project-structure-lint 1.0.1

package/src/core/validator.ts

@@ -0,0 +1,242 @@
+import * as path from 'path';
+import micromatch from 'micromatch';
+import { ProjectConfig, ValidationError, ValidationResult, FilePattern } from '../types';
+import { FileScanner, ScannedFile } from '../utils/fileScanner';
+import { validateNamingConvention, getExpectedNaming } from '../utils/naming';
+
+export class ProjectValidator {
+  private config: ProjectConfig;
+  private scanner: FileScanner;
+  private errors: ValidationError[] = [];
+  private warnings: ValidationError[] = [];
+
+  constructor(config: ProjectConfig, rootDir: string = process.cwd()) {
+    this.config = config;
+    const ignorePatterns = config.ignore || [];
+    this.scanner = new FileScanner(rootDir, ignorePatterns);
+  }
+
+  async validate(): Promise<ValidationResult> {
+    this.errors = [];
+    this.warnings = [];
+
+    const files = await this.scanner.scanDirectory();
+    const filesScanned = files.filter(f => !f.isDirectory).length;
+    const directoriesScanned = files.filter(f => f.isDirectory).length;
+
+    // Validate component co-location
+    if (this.config.rules?.componentColocation?.enabled) {
+      await this.validateComponentColocation();
+    }
+
+    // Validate file naming conventions
+    if (this.config.rules?.fileNaming) {
+      await this.validateFileNaming(files);
+    }
+
+    // Validate folder structure
+    if (this.config.rules?.folderStructure) {
+      await this.validateFolderStructure(files);
+    }
+
+    return {
+      valid: this.errors.length === 0,
+      errors: this.errors,
+      warnings: this.warnings,
+      filesScanned,
+      directoriesScanned
+    };
+  }
+
+  private async validateComponentColocation(): Promise<void> {
+    const colocationConfig = this.config.rules?.componentColocation;
+    if (!colocationConfig) return;
+
+    const componentDirs = this.scanner.getComponentDirectories(
+      colocationConfig.componentDirs
+    );
+
+    for (const dir of componentDirs) {
+      const contents = await this.scanner.getDirectoryContents(dir);
+      const componentName = path.basename(dir);
+
+      // Find the main component file
+      const mainFile = contents.find(f => 
+        !f.isDirectory && 
+        this.isComponentFile(f.name, componentName)
+      );
+
+      if (!mainFile) {
+        continue; // Skip if no main component file found
+      }
+
+      // Check for required files
+      for (const filePattern of colocationConfig.requiredFiles) {
+        if (!filePattern.required) continue;
+
+        const expectedPattern = this.expandPattern(filePattern.pattern, componentName);
+        const matchingFile = contents.find(f => 
+          !f.isDirectory && micromatch.isMatch(f.name, expectedPattern)
+        );
+
+        if (!matchingFile) {
+          const error: ValidationError = {
+            type: 'missing-file',
+            severity: this.config.severity || 'error',
+            message: `Missing required file: ${filePattern.description || expectedPattern}`,
+            directory: dir,
+            expected: expectedPattern,
+            suggestion: `Create ${expectedPattern} in ${dir}/`
+          };
+
+          this.addError(error);
+        }
+      }
+
+      // Validate naming convention for component
+      if (colocationConfig.namingConvention) {
+        const isValid = validateNamingConvention(
+          componentName,
+          colocationConfig.namingConvention
+        );
+
+        if (!isValid) {
+          const expected = getExpectedNaming(
+            componentName,
+            colocationConfig.namingConvention
+          );
+
+          const error: ValidationError = {
+            type: 'naming-violation',
+            severity: this.config.severity || 'error',
+            message: `Component directory name doesn't follow ${colocationConfig.namingConvention} convention`,
+            directory: dir,
+            actual: componentName,
+            expected,
+            suggestion: `Rename directory to ${expected}`
+          };
+
+          this.addError(error);
+        }
+      }
+    }
+  }
+
+  private async validateFileNaming(files: ScannedFile[]): Promise<void> {
+    const namingRules = this.config.rules?.fileNaming;
+    if (!namingRules) return;
+
+    for (const file of files) {
+      if (file.isDirectory) continue;
+
+      // Check each naming rule pattern
+      for (const [pattern, rule] of Object.entries(namingRules)) {
+        if (micromatch.isMatch(file.path, pattern)) {
+          const isValid = validateNamingConvention(file.name, rule.convention);
+
+          if (!isValid) {
+            const expected = getExpectedNaming(file.name, rule.convention);
+
+            const error: ValidationError = {
+              type: 'naming-violation',
+              severity: rule.severity || this.config.severity || 'error',
+              message: `File name doesn't follow ${rule.convention} convention`,
+              file: file.path,
+              actual: file.name,
+              expected,
+              suggestion: `Rename to ${expected}`
+            };
+
+            this.addError(error);
+          }
+        }
+      }
+    }
+  }
+
+  private async validateFolderStructure(files: ScannedFile[]): Promise<void> {
+    const folderRules = this.config.rules?.folderStructure;
+    if (!folderRules) return;
+
+    for (const rule of folderRules) {
+      // Check if required folder exists
+      if (!this.scanner.isDirectory(rule.path)) {
+        const error: ValidationError = {
+          type: 'structure-violation',
+          severity: this.config.severity || 'error',
+          message: `Required directory not found: ${rule.name}`,
+          directory: rule.path,
+          suggestion: `Create directory at ${rule.path}`
+        };
+
+        this.addError(error);
+        continue;
+      }
+
+      // Get files in this directory
+      const dirFiles = files.filter(f => 
+        f.path.startsWith(rule.path) && !f.isDirectory
+      );
+
+      // Validate file extensions
+      if (rule.allowedExtensions) {
+        for (const file of dirFiles) {
+          if (!rule.allowedExtensions.includes(file.extension)) {
+            const error: ValidationError = {
+              type: 'forbidden-file',
+              severity: 'warning',
+              message: `File extension ${file.extension} not allowed in ${rule.name}`,
+              file: file.path,
+              suggestion: `Allowed extensions: ${rule.allowedExtensions.join(', ')}`
+            };
+
+            this.addError(error);
+          }
+        }
+      }
+
+      // Validate naming convention for files in this directory
+      if (rule.namingConvention) {
+        for (const file of dirFiles) {
+          const isValid = validateNamingConvention(file.name, rule.namingConvention);
+
+          if (!isValid) {
+            const expected = getExpectedNaming(file.name, rule.namingConvention);
+
+            const error: ValidationError = {
+              type: 'naming-violation',
+              severity: this.config.severity || 'error',
+              message: `File in ${rule.name} doesn't follow ${rule.namingConvention} convention`,
+              file: file.path,
+              actual: file.name,
+              expected,
+              suggestion: `Rename to ${expected}`
+            };
+
+            this.addError(error);
+          }
+        }
+      }
+    }
+  }
+
+  private isComponentFile(filename: string, componentName: string): boolean {
+    const nameWithoutExt = filename.replace(/\.[^/.]+$/, '');
+    return nameWithoutExt === componentName || 
+           nameWithoutExt.toLowerCase() === componentName.toLowerCase();
+  }
+
+  private expandPattern(pattern: string, componentName: string): string {
+    return pattern.replace(/\*/g, componentName);
+  }
+
+  private addError(error: ValidationError): void {
+    if (error.severity === 'warning') {
+      this.warnings.push(error);
+    } else {
+      this.errors.push(error);
+    }
+  }
+}
+
+// Made with 

package/src/index.ts

@@ -0,0 +1,6 @@
+export { ProjectValidator } from './core/validator';
+export { loadConfig, validateConfig } from './config/loader';
+export { ConsoleReporter } from './reporters/consoleReporter';
+export { getPreset, listPresets } from './presets';
+export * from './types';
+

package/src/presets/index.ts

@@ -0,0 +1,16 @@
+import { Preset } from '../types';
+import { reactPreset } from './react';
+
+export const presets: Record<string, Preset> = {
+  react: reactPreset
+};
+
+export function getPreset(name: string): Preset | undefined {
+  return presets[name];
+}
+
+export function listPresets(): string[] {
+  return Object.keys(presets);
+}
+
+// Made with 

package/src/presets/react.ts

@@ -0,0 +1,93 @@
+import { Preset } from '../types';
+
+export const reactPreset: Preset = {
+  name: 'react',
+  description: 'React project with component co-location and testing requirements',
+  config: {
+    preset: 'react',
+    rootDir: 'src',
+    rules: {
+      componentColocation: {
+        enabled: true,
+        componentDirs: ['components', 'pages', 'features'],
+        requiredFiles: [
+          {
+            pattern: '*.test.{ts,tsx,js,jsx}',
+            required: true,
+            description: 'Test file for component'
+          },
+          {
+            pattern: '*.stories.{ts,tsx,js,jsx}',
+            required: true,
+            description: 'Storybook story file'
+          },
+          {
+            pattern: 'index.{ts,tsx,js,jsx}',
+            required: false,
+            description: 'Index file for re-exports'
+          }
+        ],
+        namingConvention: 'PascalCase'
+      },
+      fileNaming: {
+        'components/**/*.{tsx,jsx}': {
+          convention: 'PascalCase',
+          severity: 'error'
+        },
+        'hooks/**/*.{ts,tsx,js,jsx}': {
+          convention: 'camelCase',
+          severity: 'error'
+        },
+        'utils/**/*.{ts,js}': {
+          convention: 'camelCase',
+          severity: 'error'
+        },
+        'types/**/*.{ts,tsx}': {
+          convention: 'PascalCase',
+          severity: 'error'
+        },
+        'constants/**/*.{ts,js}': {
+          convention: 'UPPER_CASE',
+          severity: 'warning'
+        }
+      },
+      folderStructure: [
+        {
+          name: 'components',
+          path: 'src/components',
+          namingConvention: 'PascalCase',
+          allowedExtensions: ['.tsx', '.ts', '.jsx', '.js', '.css', '.scss', '.module.css']
+        },
+        {
+          name: 'hooks',
+          path: 'src/hooks',
+          namingConvention: 'camelCase',
+          allowedExtensions: ['.ts', '.tsx', '.js', '.jsx']
+        },
+        {
+          name: 'utils',
+          path: 'src/utils',
+          namingConvention: 'camelCase',
+          allowedExtensions: ['.ts', '.js']
+        },
+        {
+          name: 'types',
+          path: 'src/types',
+          namingConvention: 'PascalCase',
+          allowedExtensions: ['.ts', '.d.ts']
+        }
+      ]
+    },
+    ignore: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/build/**',
+      '**/.next/**',
+      '**/coverage/**',
+      '**/.git/**'
+    ],
+    severity: 'error'
+  }
+};
+
+// Made with 

package/src/reporters/consoleReporter.ts

@@ -0,0 +1,116 @@
+import chalk from 'chalk';
+import { ValidationResult, ValidationError } from '../types';
+
+export class ConsoleReporter {
+  report(result: ValidationResult): void {
+    console.log('\n' + chalk.bold('Project Structure Validation Results'));
+    console.log(chalk.gray('─'.repeat(50)));
+
+    console.log(chalk.gray(`Files scanned: ${result.filesScanned}`));
+    console.log(chalk.gray(`Directories scanned: ${result.directoriesScanned}`));
+    console.log('');
+
+    if (result.errors.length === 0 && result.warnings.length === 0) {
+      console.log(chalk.green('✓ No issues found!'));
+      console.log('');
+      return;
+    }
+
+    // Report errors
+    if (result.errors.length > 0) {
+      console.log(chalk.red.bold(`✗ ${result.errors.length} Error${result.errors.length > 1 ? 's' : ''}`));
+      console.log('');
+      
+      result.errors.forEach((error, index) => {
+        this.printError(error, index + 1);
+      });
+    }
+
+    // Report warnings
+    if (result.warnings.length > 0) {
+      console.log(chalk.yellow.bold(`⚠ ${result.warnings.length} Warning${result.warnings.length > 1 ? 's' : ''}`));
+      console.log('');
+      
+      result.warnings.forEach((warning, index) => {
+        this.printWarning(warning, index + 1);
+      });
+    }
+
+    console.log(chalk.gray('─'.repeat(50)));
+    
+    if (result.errors.length > 0) {
+      console.log(chalk.red.bold(`\n✗ Validation failed with ${result.errors.length} error${result.errors.length > 1 ? 's' : ''}`));
+    } else {
+      console.log(chalk.yellow.bold(`\n⚠ Validation passed with ${result.warnings.length} warning${result.warnings.length > 1 ? 's' : ''}`));
+    }
+    console.log('');
+  }
+
+  private printError(error: ValidationError, index: number): void {
+    console.log(chalk.red(`${index}. ${error.message}`));
+    
+    if (error.file) {
+      console.log(chalk.gray(`   File: ${error.file}`));
+    }
+    
+    if (error.directory) {
+      console.log(chalk.gray(`   Directory: ${error.directory}`));
+    }
+    
+    if (error.actual) {
+      console.log(chalk.gray(`   Actual: ${error.actual}`));
+    }
+    
+    if (error.expected) {
+      console.log(chalk.gray(`   Expected: ${error.expected}`));
+    }
+    
+    if (error.suggestion) {
+      console.log(chalk.cyan(`   💡 ${error.suggestion}`));
+    }
+    
+    console.log('');
+  }
+
+  private printWarning(warning: ValidationError, index: number): void {
+    console.log(chalk.yellow(`${index}. ${warning.message}`));
+    
+    if (warning.file) {
+      console.log(chalk.gray(`   File: ${warning.file}`));
+    }
+    
+    if (warning.directory) {
+      console.log(chalk.gray(`   Directory: ${warning.directory}`));
+    }
+    
+    if (warning.actual) {
+      console.log(chalk.gray(`   Actual: ${warning.actual}`));
+    }
+    
+    if (warning.expected) {
+      console.log(chalk.gray(`   Expected: ${warning.expected}`));
+    }
+    
+    if (warning.suggestion) {
+      console.log(chalk.cyan(`   💡 ${warning.suggestion}`));
+    }
+    
+    console.log('');
+  }
+
+  reportConfigError(error: string): void {
+    console.log(chalk.red.bold('\n✗ Configuration Error'));
+    console.log(chalk.red(error));
+    console.log('');
+  }
+
+  reportConfigErrors(errors: string[]): void {
+    console.log(chalk.red.bold('\n✗ Configuration Errors'));
+    errors.forEach(error => {
+      console.log(chalk.red(`  • ${error}`));
+    });
+    console.log('');
+  }
+}
+
+// Made with 

package/src/types/index.ts

@@ -0,0 +1,67 @@
+export type NamingConvention = 'PascalCase' | 'camelCase' | 'kebab-case' | 'snake_case' | 'UPPER_CASE';
+
+export type Severity = 'error' | 'warning';
+
+export interface FilePattern {
+  pattern: string;
+  required?: boolean;
+  description?: string;
+}
+
+export interface FolderRule {
+  name: string;
+  path: string;
+  requiredFiles?: FilePattern[];
+  namingConvention?: NamingConvention;
+  allowedExtensions?: string[];
+  maxDepth?: number;
+}
+
+export interface ProjectConfig {
+  preset?: string;
+  rootDir?: string;
+  rules?: {
+    folderStructure?: FolderRule[];
+    componentColocation?: {
+      enabled: boolean;
+      componentDirs: string[];
+      requiredFiles: FilePattern[];
+      namingConvention?: NamingConvention;
+    };
+    fileNaming?: {
+      [pattern: string]: {
+        convention: NamingConvention;
+        severity?: Severity;
+      };
+    };
+  };
+  ignore?: string[];
+  severity?: Severity;
+}
+
+export interface ValidationError {
+  type: 'missing-file' | 'naming-violation' | 'structure-violation' | 'forbidden-file';
+  severity: Severity;
+  message: string;
+  file?: string;
+  directory?: string;
+  expected?: string;
+  actual?: string;
+  suggestion?: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationError[];
+  filesScanned: number;
+  directoriesScanned: number;
+}
+
+export interface Preset {
+  name: string;
+  description: string;
+  config: ProjectConfig;
+}
+
+// Made with 

package/src/types/micromatch.d.ts

@@ -0,0 +1,41 @@
+declare module 'micromatch' {
+  function micromatch(
+    list: string | string[],
+    patterns: string | string[],
+    options?: micromatch.Options
+  ): string[];
+
+  namespace micromatch {
+    interface Options {
+      ignore?: string | string[];
+      matchBase?: boolean;
+      nobrace?: boolean;
+      nocase?: boolean;
+      noext?: boolean;
+      noglobstar?: boolean;
+      nonull?: boolean;
+      dot?: boolean;
+    }
+
+    function isMatch(
+      str: string,
+      patterns: string | string[],
+      options?: Options
+    ): boolean;
+
+    function makeRe(
+      pattern: string,
+      options?: Options
+    ): RegExp;
+
+    function match(
+      list: string[],
+      patterns: string | string[],
+      options?: Options
+    ): string[];
+  }
+
+  export = micromatch;
+}
+
+// Made with 

package/src/utils/__tests__/naming.test.ts

@@ -0,0 +1,107 @@
+import { validateNamingConvention, getExpectedNaming } from '../naming';
+
+describe('validateNamingConvention', () => {
+  describe('PascalCase', () => {
+    it('should validate correct PascalCase names', () => {
+      expect(validateNamingConvention('Button.tsx', 'PascalCase')).toBe(true);
+      expect(validateNamingConvention('MyComponent.tsx', 'PascalCase')).toBe(true);
+      expect(validateNamingConvention('UserProfile.tsx', 'PascalCase')).toBe(true);
+    });
+
+    it('should reject incorrect PascalCase names', () => {
+      expect(validateNamingConvention('button.tsx', 'PascalCase')).toBe(false);
+      expect(validateNamingConvention('myComponent.tsx', 'PascalCase')).toBe(false);
+      expect(validateNamingConvention('user-profile.tsx', 'PascalCase')).toBe(false);
+    });
+  });
+
+  describe('camelCase', () => {
+    it('should validate correct camelCase names', () => {
+      expect(validateNamingConvention('useAuth.ts', 'camelCase')).toBe(true);
+      expect(validateNamingConvention('formatDate.ts', 'camelCase')).toBe(true);
+      expect(validateNamingConvention('getUserData.ts', 'camelCase')).toBe(true);
+    });
+
+    it('should reject incorrect camelCase names', () => {
+      expect(validateNamingConvention('UseAuth.ts', 'camelCase')).toBe(false);
+      expect(validateNamingConvention('format-date.ts', 'camelCase')).toBe(false);
+      expect(validateNamingConvention('get_user_data.ts', 'camelCase')).toBe(false);
+    });
+  });
+
+  describe('kebab-case', () => {
+    it('should validate correct kebab-case names', () => {
+      expect(validateNamingConvention('my-component.tsx', 'kebab-case')).toBe(true);
+      expect(validateNamingConvention('user-profile.tsx', 'kebab-case')).toBe(true);
+      expect(validateNamingConvention('format-date.ts', 'kebab-case')).toBe(true);
+    });
+
+    it('should reject incorrect kebab-case names', () => {
+      expect(validateNamingConvention('MyComponent.tsx', 'kebab-case')).toBe(false);
+      expect(validateNamingConvention('userProfile.tsx', 'kebab-case')).toBe(false);
+      expect(validateNamingConvention('format_date.ts', 'kebab-case')).toBe(false);
+    });
+  });
+
+  describe('snake_case', () => {
+    it('should validate correct snake_case names', () => {
+      expect(validateNamingConvention('my_component.tsx', 'snake_case')).toBe(true);
+      expect(validateNamingConvention('user_profile.tsx', 'snake_case')).toBe(true);
+      expect(validateNamingConvention('format_date.ts', 'snake_case')).toBe(true);
+    });
+
+    it('should reject incorrect snake_case names', () => {
+      expect(validateNamingConvention('MyComponent.tsx', 'snake_case')).toBe(false);
+      expect(validateNamingConvention('userProfile.tsx', 'snake_case')).toBe(false);
+      expect(validateNamingConvention('format-date.ts', 'snake_case')).toBe(false);
+    });
+  });
+
+  describe('UPPER_CASE', () => {
+    it('should validate correct UPPER_CASE names', () => {
+      expect(validateNamingConvention('API_CONSTANTS.ts', 'UPPER_CASE')).toBe(true);
+      expect(validateNamingConvention('USER_ROLES.ts', 'UPPER_CASE')).toBe(true);
+      expect(validateNamingConvention('MAX_LENGTH.ts', 'UPPER_CASE')).toBe(true);
+    });
+
+    it('should reject incorrect UPPER_CASE names', () => {
+      expect(validateNamingConvention('apiConstants.ts', 'UPPER_CASE')).toBe(false);
+      expect(validateNamingConvention('UserRoles.ts', 'UPPER_CASE')).toBe(false);
+      expect(validateNamingConvention('max-length.ts', 'UPPER_CASE')).toBe(false);
+    });
+  });
+});
+
+describe('getExpectedNaming', () => {
+  it('should convert to PascalCase', () => {
+    expect(getExpectedNaming('my-component.tsx', 'PascalCase')).toBe('MyComponent.tsx');
+    expect(getExpectedNaming('user_profile.tsx', 'PascalCase')).toBe('UserProfile.tsx');
+    expect(getExpectedNaming('formatDate.ts', 'PascalCase')).toBe('FormatDate.ts');
+  });
+
+  it('should convert to camelCase', () => {
+    expect(getExpectedNaming('MyComponent.tsx', 'camelCase')).toBe('myComponent.tsx');
+    expect(getExpectedNaming('user-profile.tsx', 'camelCase')).toBe('userProfile.tsx');
+    expect(getExpectedNaming('format_date.ts', 'camelCase')).toBe('formatDate.ts');
+  });
+
+  it('should convert to kebab-case', () => {
+    expect(getExpectedNaming('MyComponent.tsx', 'kebab-case')).toBe('my-component.tsx');
+    expect(getExpectedNaming('userProfile.tsx', 'kebab-case')).toBe('user-profile.tsx');
+    expect(getExpectedNaming('formatDate.ts', 'kebab-case')).toBe('format-date.ts');
+  });
+
+  it('should convert to snake_case', () => {
+    expect(getExpectedNaming('MyComponent.tsx', 'snake_case')).toBe('my_component.tsx');
+    expect(getExpectedNaming('userProfile.tsx', 'snake_case')).toBe('user_profile.tsx');
+    expect(getExpectedNaming('formatDate.ts', 'snake_case')).toBe('format_date.ts');
+  });
+
+  it('should convert to UPPER_CASE', () => {
+    expect(getExpectedNaming('myComponent.tsx', 'UPPER_CASE')).toBe('MY_COMPONENT.tsx');
+    expect(getExpectedNaming('userProfile.tsx', 'UPPER_CASE')).toBe('USER_PROFILE.tsx');
+    expect(getExpectedNaming('formatDate.ts', 'UPPER_CASE')).toBe('FORMAT_DATE.ts');
+  });
+});
+
+// Made with