Structure Validation

A Node.js CLI tool for validating and maintaining consistent codebase folder and file structure using declarative configuration. Now with automatic import updates! 🚀

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
• 🔄 Automatic Import Updates - NEW! Automatically update import statements when files are moved or renamed
• 📁 Smart File Operations - Comprehensive file operations with import management
• 🛡️ Enhanced Error Handling - Better user experience with detailed error reporting
• ⚡ Batch Operations - Efficient handling of multiple file operations

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 with automatic import updates
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 with import updates
  --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

Automatic Import Updates

NEW FEATURE! Structure Validation now automatically updates import statements when files are moved, renamed, or deleted. This ensures your code continues to work after file operations.

How It Works

When you move or rename files, the tool:

1. Detects all import statements that reference the moved/renamed files
2. Calculates new relative paths based on the new file location
3. Updates all import statements automatically
4. Validates the changes to ensure code functionality is maintained

Example

# Move a file and automatically update all imports
npx structure-validation --fix

# The tool will:
# 1. Move src/utils/helper.ts → shared/utils/helper.ts
# 2. Update all imports from './utils/helper' to '../../shared/utils/helper'
# 3. Validate that all imports are correctly updated

Supported Import Types

• Named imports: import { name } from './module'
• Default imports: import defaultExport from './module'
• Namespace imports: import * as namespace from './module'
• Type imports: import type { Type } from './module'
• Mixed imports: import defaultExport, { named } from './module'

For detailed information about automatic import updates, see AUTOMATIC_IMPORT_UPDATES.md.

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 Import Updates

npx structure-validation --scope all --fix

Preview Changes

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",
    "validate:fix": "structure-validation --scope staged --fix --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']
};

File Operations with Import Updates

The tool provides comprehensive file operations that automatically handle import updates:

Moving Files

import { FileOperationService } from 'structure-validation';

const fileOperationService = new FileOperationService();

// Move a file and automatically update all imports
const result = await fileOperationService.moveFile(
  'src/utils/helper.ts',
  'shared/utils/helper.ts'
);

Renaming Files

// Rename a file and automatically update all imports
const result = await fileOperationService.renameFile(
  'src/services/OldService.ts',
  'NewService.ts'
);

Batch Operations

// Move multiple files and update all imports in a single operation
const moves = [
  { sourcePath: 'src/components/Button.tsx', targetPath: 'ui/components/Button.tsx' },
  { sourcePath: 'src/components/Input.tsx', targetPath: 'ui/components/Input.tsx' }
];

const results = await fileOperationService.batchMoveFiles(moves);

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
• Ensure TypeScript configuration is correct for import updates

Import Update Issues

• Verify that import paths are relative (not absolute)
• Check that files actually import the moved/renamed files
• Use --dry-run to preview changes before applying
• Check the validation report for import update errors

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.