Structure Validation

A Node.js CLI tool for validating and maintaining consistent codebase folder and file structure using declarative configuration.

Why Structure Validation?

Maintaining a clean, consistent file structure across your codebase is crucial for:

• Team Productivity - Developers can quickly locate files
• Code Quality - Enforced patterns prevent structural debt
• Scalability - Consistent structure scales with your project
• Onboarding - New team members understand the codebase faster

Features

• 🔍 Declarative Configuration - Define your structure rules in TypeScript
• 🚀 Fast Validation - Built with performance in mind for large codebases
• 🛠️ Auto-fix Mode - Automatically move files to correct locations
• 📦 Git Integration - Validate staged, changed, or all files
• 🎯 Pattern Matching - Support for glob patterns and variable placeholders
• 🔧 Husky Integration - Pre-commit hooks for consistent validation
• 📊 Detailed Reporting - Clear error messages and suggestions

Quick Start

Installation

npm install structure-validation

Basic Usage

1. Create Configuration

Create structure-validation.config.ts in your project root:

export default {
  components: ['*.tsx'],
  services: ['*.service.ts'],
  hooks: ['use*.ts', 'use*.tsx'],
  utils: ['*.util.ts'],
  '{a}': ['{a}.ts', '{a}.tsx', '{a}.*.ts', '{a}.*.tsx'],
  '{root}': ['*.config.ts', '*.config.js', 'package.json', 'README.md', 'tsconfig.json'],
  '**': ['*.test.ts', '*.test.tsx', 'index.ts', 'index.tsx', 'page.tsx', 'route.ts', 'not-found.tsx']
};

2. Run Validation

# Validate staged files (default)
npx structure-validation

# Validate all files
npx structure-validation --scope all

# Auto-fix issues
npx structure-validation --fix

# Validate with root folder verification
npx structure-validation --verify-root

CLI Options

npx structure-validation [options]

Options:
  --scope <scope>    all, staged, or changes (default: staged)
  --files <files>    Specific files to validate
  --config <path>    Config file path (default: structure-validation.config.ts)
  --fix              Auto-fix file structure issues
  --dry-run          Preview changes without applying
  --backup           Create backup before fixing (default: true)
  --verify-root      Enable root folder validation
  --skip-error       Skip interactive mode and continue on errors
  -h, --help         Show help
  -v, --version      Show version

Pattern Examples

Basic Patterns

• *.tsx - Files ending with .tsx
• use*.ts - Files starting with "use" and ending with .ts
• *.service.ts - Files ending with .service.ts

Variable Placeholders

• {a}.ts - Matches user.ts in user/ folder
• {a}.*.ts - Matches user.profile.ts in user/ folder
• {root} - Root folder patterns (use with --verify-root)

Global Patterns

• ** - Applies to all folders (e.g., *.test.ts, index.ts)

Examples

Validate All Files

npx structure-validation --scope all

Auto-fix with Preview

npx structure-validation --scope all --dry-run

Validate Root Folder

npx structure-validation --verify-root

Interactive Mode

# Start interactive mode for fixing validation errors
npx structure-validation

# Skip interactive mode and continue on errors
npx structure-validation --skip-error

In interactive mode, you'll be prompted for each file with validation errors:

• 1 - Move to subfolder (automatically uses suggested folder name)
• 2 - Rename file (keep extension)
• 3 - Move to upper folder (creates folder with suggested name if needed)
• 4 - Delete file
• 5 - Add file to structure-validation.config.ts (modifies config and restarts)
• 6 - Add file pattern to structure-validation.config.ts (modifies config and restarts)
• 7 - Skip this file (adds to structure-validation.skip.json)

The subfolder suggestions are based on your structure-validation.config.ts file:

• File patterns in the config determine the suggested folder
• Matches are found by comparing filename against configured patterns
• Special patterns like {root}, {a}, and ** are excluded from suggestions

Skip functionality:

• Skipped files are stored in structure-validation.skip.json
• Skipped files are automatically excluded from future validation runs
• The skip file persists across sessions

Husky Integration

Basic Setup

Add structure-validation to your pre-commit hooks:

# Install and setup
npm install --save-dev husky
npx husky init
npx husky add .husky/pre-commit "npx structure-validation"

Custom Scripts

Add to your package.json for more control:

{
  "scripts": {
    "validate:staged": "structure-validation --scope staged --verify-root",
    "validate:all": "structure-validation --scope all --verify-root"
  },
  "husky": {
    "hooks": {
      "pre-commit": "npm run validate:staged"
    }
  }
}

CI/CD Integration

Add to your GitHub Actions workflow:

- name: Validate Structure
  run: npx structure-validation --scope changes

Configuration

Simple Configuration

export default {
  components: ['*.tsx'],
  services: ['*.service.ts'],
  utils: ['*.util.ts'],
  '{a}': ['{a}.ts', '{a}.*.ts'],
  '{root}': ['*.config.ts', 'package.json'],
  '**': ['*.test.ts', 'index.ts']
};

Advanced Configuration

export default {
  components: {
    patterns: ['*.tsx'],
    exclude: ['*.test.tsx'],
    nested: true
  },
  services: {
    patterns: ['*.service.ts'],
    nested: false
  },
  '{a}': ['{a}.ts', '{a}.*.ts'],
  '{root}': ['*.config.ts', 'package.json'],
  '**': ['*.test.ts', 'index.ts']
};

Troubleshooting

Configuration Not Found

Create structure-validation.config.ts in your project root.

Git Repository Required

Initialize git repository or run without --scope flag.

Auto-fix Errors

• Check if target files already exist
• Verify write permissions
• Check disk space for backups

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.