Structure Validation

A Node.js CLI tool for validating codebase folder and file structure using a clean declarative configuration. Part of the guardz ecosystem for comprehensive TypeScript development.

Features

• ✅ Declarative Configuration: Define folder structure rules in a simple TypeScript config
• ✅ Pattern Matching: Use glob patterns to define allowed file types per folder
• ✅ Git Integration: Validate only changed files with --changed flag
• ✅ Smart Suggestions: Get suggestions for where to move misplaced files
• ✅ CI/CD Ready: Returns non-zero exit codes for automation
• ✅ Beautiful Output: Colored CLI output with clear error messages

Quick Start

Installation

npm install structure-validation

Global Installation (for CLI usage)

npm install -g structure-validation

Basic Usage

1. Create a configuration file structure-validation.config.ts:

export default {
  components: ['*.tsx'],
  services: ['*.service.ts'],
  hooks: ['use*.ts', 'use*.tsx'],
  utils: ['*.util.ts'],
  constant: ['*.constant.ts'],
  enum: ['*.enum.ts'],
  types: ['*.type.ts', '*.interface.ts', '*.d.ts', 'is*.guardz.ts'],
  e2e: ['*.e2e.ts', '*.e2e.tsx'],
  pages: ['*.tsx'],
  '**': ['*.test.ts', '*.test.tsx']
};

2. Run validation:

# Validate staged files (default)
npx structure-validation

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

# Validate only staged files
npx structure-validation --scope staged

# Validate all changed files (staged + unstaged)
npx structure-validation --scope changes

# Validate specific files
npx structure-validation --files src/components/Button.tsx src/hooks/useAuth.ts

Configuration

The configuration file defines which file patterns are allowed in which folders:

export default {
  // Folder name: [allowed file patterns]
  components: ['*.tsx', '*.jsx'],
  services: ['*.service.ts'],
  hooks: ['use*.ts', 'use*.tsx'],
  utils: ['*.util.ts', '*.helper.ts'],
  
  // Global patterns (apply to all folders)
  '**': ['*.test.ts', '*.test.tsx', '*.spec.ts']
};

Pattern Syntax

• *.tsx - Files ending with .tsx
• use*.ts - Files starting with "use" and ending with .ts
• *.service.ts - Files ending with .service.ts
• ** - Global wildcard (applies to all folders)

CLI Options

npx structure-validation [options]

Options:
  --scope <scope>    Validation scope: all, staged, or changes (default: staged)
  --files <files>    Specific files to validate
  --config <path>    Path to configuration file (default: structure-validation.config.ts)
  -h, --help         Show help
  -v, --version      Show version

Examples

Validate All Files

npx structure-validation

Output:

🔍 Validating all files...
✅ All files are properly structured!

Validate All Files

npx structure-validation --scope all

Output:

🔍 Validating all files...
❌ Found 2 validation error(s):

  src/utils/Button.tsx
  File Button.tsx in utils/ doesn't match any allowed pattern
  Expected patterns: *.util.ts, *.helper.ts

  src/components/auth.service.ts
  File auth.service.ts should be in one of: services
  Expected folder: services

💡 2 suggestion(s):

  src/utils/Button.tsx
  File matches patterns for components folder
  Move to: components/

  src/components/auth.service.ts
  File matches patterns for services folder
  Move to: services/

Validate Staged Files (Default)

npx structure-validation
# or explicitly
npx structure-validation --scope staged

Output:

🔍 Validating staged files...
✅ All files are properly structured!

Validate All Changed Files

npx structure-validation --scope changes

Output:

🔍 Validating all changed files...
❌ Found 2 validation error(s):

  src/utils/Button.tsx
  File Button.tsx in utils/ doesn't match any allowed pattern
  Expected patterns: *.util.ts, *.helper.ts

  src/components/auth.service.ts
  File auth.service.ts should be in one of: services
  Expected folder: services

💡 2 suggestion(s):

  src/utils/Button.tsx
  File matches patterns for components folder
  Move to: components/

  src/components/auth.service.ts
  File matches patterns for services folder
  Move to: services/

Validate Specific Files

npx structure-validation --files src/components/Button.tsx src/hooks/useAuth.ts

Integration

CI/CD Pipeline

Add to your CI pipeline to ensure code structure compliance:

# GitHub Actions example
- name: Validate Structure
  run: npx structure-validation --scope changes

Pre-commit Hook

Add to your pre-commit hooks:

{
  "husky": {
    "hooks": {
      "pre-commit": "npx structure-validation"
    }
  }
}

Package.json Scripts

{
  "scripts": {
    "validate": "structure-validation",
    "validate:all": "structure-validation --scope all",
    "validate:staged": "structure-validation --scope staged",
    "validate:changes": "structure-validation --scope changes"
  }
}

Error Types

Pattern Mismatch

Files that don't match any allowed pattern in their folder.

Folder Mismatch

Files that match patterns for a different folder.

Suggestions

The tool provides intelligent suggestions for:

• Moving files to the correct folder based on their patterns
• Identifying which rule was violated
• Showing expected patterns and folders

Advanced Configuration

Custom Config Path

npx structure-validation --config ./custom-config.ts

Complex Patterns

export default {
  components: ['*.tsx', '*.jsx'],
  services: ['*.service.ts', '*.api.ts'],
  hooks: ['use*.ts', 'use*.tsx', 'with*.ts'],
  utils: ['*.util.ts', '*.helper.ts', '*.helper.js'],
  types: ['*.type.ts', '*.interface.ts', '*.d.ts', 'is*.guardz.ts'],
  tests: ['*.test.ts', '*.test.tsx', '*.spec.ts'],
  '**': ['*.md', '*.json', '*.yml', '*.yaml']
};

Troubleshooting

Configuration Not Found

❌ Configuration file not found: structure-validation.config.ts

Solution: Create the configuration file in your project root.

Git Repository Required

❌ --changed option requires a git repository

Solution: Initialize git repository or run without --changed flag.

No Files Found

✅ All files are properly structured!

Solution: Check your file patterns and ensure files exist in the expected locations.

Contributing

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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Related Projects

• guardz - TypeScript type guard library
• guardz-axios - Type-safe HTTP client
• guardz-generator - Code generation tools

License

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