@futdevpro/dynamo-eslint 1.14.2 → 1.14.4

package/src/scripts/validate-naming.ts

@@ -1,31 +1,95 @@
 #!/usr/bin/env node
+/**
+ * @fileoverview Naming Convention Validation Script
+ * 
+ * This script validates naming conventions across all TypeScript files in the project
+ * using the Dynamo naming-patterns ESLint rule. It scans files, runs ESLint validation,
+ * and reports any naming convention violations.
+ * 
+ * @usage
+ * ```bash
+ * dynamo-validate-naming
+ * ```
+ * 
+ * @example
+ * ```bash
+ * # Validate naming conventions in all TypeScript files
+ * npx dynamo-validate-naming
+ * 
+ * # Or run via npm script
+ * npm run validate:naming
+ * ```
+ * 
+ * @author Future Development Program Ltd.
+ * @version 1.14.3
+ */
+
 import fg from 'fast-glob';
-import { readFileSync } from 'fs';
 import { ESLint } from 'eslint';
 
 import { DyFM_Log } from '@futdevpro/fsm-dynamo';
 
+/**
+ * Result of validating naming conventions in a single file
+ */
 interface NamingValidationResult {
+  /** Path to the file that was validated */
   file: string;
+  /** Array of naming validation errors found in the file */
   errors: Array<{
+    /** Line number where the error occurred */
     line: number;
+    /** Column number where the error occurred */
     column: number;
+    /** Error message describing the violation */
     message: string;
+    /** ID of the ESLint rule that was violated */
     ruleId: string;
   }>;
 }
 
+/**
+ * Validates naming conventions in a single TypeScript file
+ * 
+ * Uses ESLint with the Dynamo naming-patterns rule to check for naming convention
+ * violations and returns detailed error information.
+ * 
+ * @param filePath - Path to the TypeScript file to validate
+ * @returns Promise that resolves to a NamingValidationResult object
+ * 
+ * @example
+ * ```typescript
+ * const result = await validateNamingInFile('./src/components/Button.tsx');
+ * if (result.errors.length > 0) {
+ *   console.log(`Found ${result.errors.length} naming violations`);
+ * }
+ * ```
+ */
 async function validateNamingInFile(filePath: string): Promise<NamingValidationResult> {
+  // Configure ESLint using the main Dynamo configuration
   const eslint = new ESLint({
-    baseConfig: require('../eslint.config.js')[1], // Use the main config object from flat config array
+    // Use the main config object from flat config array
+    baseConfig: require('../eslint.config.js')[1],
   });
 
-  const results = await eslint.lintFiles([ filePath ]);
-  const result = results[0];
+  // Run ESLint on the file
+  const results: ESLint.LintResult[] = await eslint.lintFiles([ filePath ]);
+  const result: ESLint.LintResult = results[0];
 
+  // Transform ESLint messages into our result format
   return {
     file: filePath,
-    errors: result.messages.map(msg => ({
+    errors: result.messages.map((msg: {
+      line: number;
+      column: number;
+      message: string;
+      ruleId?: string;
+    }): {
+      line: number;
+      column: number;
+      message: string;
+      ruleId: string;
+    } => ({
       line: msg.line,
       column: msg.column,
       message: msg.message,
@@ -34,8 +98,20 @@ async function validateNamingInFile(filePath: string): Promise<NamingValidationR
   };
 }
 
-async function main() {
-  const files = await fg([ '**/*.{ts,tsx}' ], { 
+/**
+ * Main function that validates naming conventions across all TypeScript files
+ * 
+ * Scans for all .ts and .tsx files in the project, validates naming conventions
+ * using the Dynamo naming-patterns rule, and provides detailed reporting on any
+ * violations found.
+ * 
+ * @returns Promise that resolves when all files have been validated
+ * 
+ * @throws {Error} When validation fails and process exits with code 1
+ */
+async function main(): Promise<void> {
+  // Find all TypeScript files, excluding common directories and test files
+  const files: string[] = await fg([ '**/*.{ts,tsx}' ], { 
     ignore: [ '**/node_modules/**', '**/build/**', '**/dist/**', '**/*.spec.ts', '**/*.test.ts' ], 
   });
   
@@ -44,42 +120,57 @@ async function main() {
   const results: NamingValidationResult[] = [];
   let totalErrors = 0;
 
-  for (const file of files) {
+  // Process each file individually
+  for (let i = 0; i < files.length; i++) {
+    const filePath: string = files[i];
+
     try {
-      const result = await validateNamingInFile(file);
+      const result: NamingValidationResult = await validateNamingInFile(filePath);
 
       results.push(result);
       totalErrors += result.errors.length;
     } catch (error) {
-      DyFM_Log.error(`Error processing ${file}:`, error);
+      DyFM_Log.error(`Error processing ${filePath}:`, error);
     }
   }
 
-  // Report results
-  const filesWithErrors = results.filter(r => r.errors.length > 0);
+  // Filter files that have naming violations
+  const filesWithErrors: NamingValidationResult[] = results.filter(
+    (r: NamingValidationResult): boolean => r.errors.length > 0
+  );
   
+  // Report success if no violations found
   if (filesWithErrors.length === 0) {
     DyFM_Log.log('✅ All naming validations passed!');
 
     return;
   }
 
-  DyFM_Log.warn(`\n❌ Found ${totalErrors} naming validation errors in ${filesWithErrors.length} files:\n`);
+  // Report detailed error information
+  DyFM_Log.warn(
+    `\n❌ Found ${totalErrors} naming validation errors in ${filesWithErrors.length} files:\n`
+  );
 
-  filesWithErrors.forEach(result => {
+  filesWithErrors.forEach((result: NamingValidationResult): void => {
     DyFM_Log.log(`📁 ${result.file}:`);
-    result.errors.forEach(error => {
+    result.errors.forEach((error: {
+      line: number;
+      column: number;
+      message: string;
+      ruleId: string;
+    }): void => {
       DyFM_Log.log(`  ${error.line}:${error.column} - ${error.message}`);
     });
     DyFM_Log.log('');
   });
 
+  // Exit with error code to indicate validation failure
   process.exit(1);
 }
 
-main().catch((err) => {
+// Execute the main function and handle any errors
+main().catch((err: Error): void => {
   DyFM_Log.error('Validation failed:', err);
   process.exit(1);
 });
 
-