@futdevpro/dynamo-eslint 1.14.3 → 1.14.4

package/src/scripts/fix-return-types.ts

@@ -1,20 +1,69 @@
 #!/usr/bin/env node
+/**
+ * @fileoverview TypeScript Type Annotation Fix Script
+ * 
+ * This script uses TypeScript's AST (Abstract Syntax Tree) to automatically add
+ * type annotations to functions and arrow functions. It analyzes TypeScript files,
+ * infers return types using the TypeScript compiler, and adds explicit type
+ * annotations where missing.
+ * 
+ * @usage
+ * ```bash
+ * dynamo-fix-return-types
+ * ```
+ * 
+ * @example
+ * ```bash
+ * # Fix type annotations in all TypeScript files
+ * npx dynamo-fix-return-types
+ * 
+ * # Or run via npm script
+ * npm run fix:types
+ * ```
+ * 
+ * @author Future Development Program Ltd.
+ * @version 1.14.3
+ */
+
 import * as ts from 'typescript';
 import * as fs from 'fs';
 import * as path from 'path';
 import fg from 'fast-glob';
 import { DyFM_Log } from '@futdevpro/fsm-dynamo';
 
+/**
+ * Result of fixing type annotations in a single file
+ */
 interface FixResult {
+  /** Path to the file that was processed */
   file: string;
+  /** Whether the file was actually modified */
   fixed: boolean;
+  /** Number of type annotations added to the file */
   changes: number;
 }
 
-function addReturnTypesToFile(filePath: string): FixResult {
+/**
+ * Adds type annotations to functions and arrow functions in a TypeScript file
+ * 
+ * Uses TypeScript's compiler API to analyze the file, infer return types,
+ * and automatically add explicit type annotations where missing.
+ * 
+ * @param filePath - Path to the TypeScript file to process
+ * @returns FixResult object containing statistics about the changes made
+ * 
+ * @example
+ * ```typescript
+ * const result = addTypesToFile('./src/utils.ts');
+ * console.log(`Added ${result.changes} type annotations to ${result.file}`);
+ * ```
+ */
+function addTypesToFile(filePath: string): FixResult {
+  // Read and parse the source file
   const sourceCode = fs.readFileSync(filePath, 'utf8');
   const sourceFile = ts.createSourceFile(filePath, sourceCode, ts.ScriptTarget.Latest, true);
   
+  // Create TypeScript program for type checking
   const program = ts.createProgram([filePath], {
     target: ts.ScriptTarget.Latest,
     module: ts.ModuleKind.ESNext,
@@ -26,8 +75,14 @@ function addReturnTypesToFile(filePath: string): FixResult {
   let changes = 0;
   let hasChanges = false;
   
+  /**
+   * Recursively visits AST nodes and adds type annotations where needed
+   * 
+   * @param node - The current AST node being visited
+   * @returns The potentially modified AST node
+   */
   function visit(node: ts.Node): ts.Node {
-    // Handle function declarations
+    // Handle function declarations without return types
     if (ts.isFunctionDeclaration(node) && !node.type) {
       const signature = checker.getSignatureFromDeclaration(node);
       
@@ -35,6 +90,7 @@ function addReturnTypesToFile(filePath: string): FixResult {
         const returnType = checker.getReturnTypeOfSignature(signature);
         const typeString = checker.typeToString(returnType);
         
+        // Add type annotation if it's not void or any
         if (typeString !== 'void' && typeString !== 'any') {
           const newType = ts.factory.createTypeReferenceNode(typeString);
           const updatedNode = ts.factory.updateFunctionDeclaration(
@@ -54,7 +110,7 @@ function addReturnTypesToFile(filePath: string): FixResult {
       }
     }
     
-    // Handle arrow functions
+    // Handle arrow functions without return types
     if (ts.isArrowFunction(node) && !node.type) {
       const signature = checker.getSignatureFromDeclaration(node);
 
@@ -62,6 +118,7 @@ function addReturnTypesToFile(filePath: string): FixResult {
         const returnType = checker.getReturnTypeOfSignature(signature);
         const typeString = checker.typeToString(returnType);
         
+        // Add type annotation if it's not void or any
         if (typeString !== 'void' && typeString !== 'any') {
           const newType = ts.factory.createTypeReferenceNode(typeString);
           const updatedNode = ts.factory.updateArrowFunction(
@@ -79,12 +136,18 @@ function addReturnTypesToFile(filePath: string): FixResult {
         }
       }
     }
+
+    // Note: Variable declarations, parameters, and class properties
+    // are handled by the existing @typescript-eslint/typedef rule
+    // and can be auto-fixed with eslint --fix
     
     return ts.visitEachChild(node, visit, {} as ts.TransformationContext);
   }
   
+  // Transform the AST and apply changes
   const result = ts.visitEachChild(sourceFile, visit, {} as ts.TransformationContext);
   
+  // Write the modified code back to the file if changes were made
   if (hasChanges) {
     const printer = ts.createPrinter();
     const newSourceCode = printer.printFile(result);
@@ -98,7 +161,19 @@ function addReturnTypesToFile(filePath: string): FixResult {
   };
 }
 
+
+/**
+ * Main function that processes all TypeScript files and adds type annotations
+ * 
+ * Scans for all .ts and .tsx files in the project, processes each file to add
+ * missing type annotations, and provides comprehensive reporting on the results.
+ * 
+ * @returns Promise that resolves when all files have been processed
+ * 
+ * @throws {Error} When file processing fails
+ */
 async function main() {
+  // Find all TypeScript files, excluding common directories and test files
   const files = await fg([ '**/*.{ts,tsx}' ], {
     ignore: [
       '**/node_modules/**',
@@ -109,40 +184,47 @@ async function main() {
     ],
   });
   
-  DyFM_Log.log(`[fix-return-types] Processing ${files.length} files...`);
+  DyFM_Log.log(`[fix-types] Processing ${files.length} files...`);
   
   const results: FixResult[] = [];
   let totalFixed = 0;
   let totalChanges = 0;
   
+  // Process each file individually
   for (const file of files) {
     try {
-      const result = addReturnTypesToFile(file);
+      const result = addTypesToFile(file);
       results.push(result);
       
+      // Track successful fixes
       if (result.fixed) {
         totalFixed++;
         totalChanges += result.changes;
-        DyFM_Log.log(`✅ Fixed ${result.changes} return types in ${file}`);
+        DyFM_Log.log(`✅ Fixed ${result.changes} type annotations in ${file}`);
       }
     } catch (error) {
       DyFM_Log.error(`❌ Error processing ${file}:`, error);
     }
   }
   
+  // Generate comprehensive summary report
   DyFM_Log.log(`\n📊 Fix Summary:`);
   DyFM_Log.log(`   Files processed: ${files.length}`);
   DyFM_Log.log(`   Files fixed: ${totalFixed}`);
-  DyFM_Log.log(`   Total return types added: ${totalChanges}`);
+  DyFM_Log.log(`   Total type annotations added: ${totalChanges}`);
   
+  // Provide appropriate success/failure message
   if (totalFixed > 0) {
-    DyFM_Log.log(`🎉 Successfully added return types to ${totalFixed} files!`);
+    DyFM_Log.log(`🎉 Successfully added type annotations to ${totalFixed} files!`);
   } else {
-    DyFM_Log.log('✅ No files needed return type fixes!');
+    DyFM_Log.log('✅ No files needed type annotation fixes!');
   }
 }
 
+// Execute the main function and handle any errors
 main().catch((err) => {
   DyFM_Log.error('Fix script failed:', err);
   process.exit(1);
 });
+
+

package/src/scripts/validate-imports.ts

@@ -1,4 +1,28 @@
 #!/usr/bin/env node
+/**
+ * @fileoverview Import Validation Script
+ * 
+ * This script validates import ordering across all TypeScript files in the project
+ * using the Dynamo import-order ESLint rule. It scans files, runs ESLint validation,
+ * and reports any import ordering violations.
+ * 
+ * @usage
+ * ```bash
+ * dynamo-validate-imports
+ * ```
+ * 
+ * @example
+ * ```bash
+ * # Validate import ordering in all TypeScript files
+ * npx dynamo-validate-imports
+ * 
+ * # Or run via npm script
+ * npm run validate:imports
+ * ```
+ * 
+ * @author Future Development Program Ltd.
+ * @version 1.14.3
+ */
 
 
 
@@ -84,17 +108,44 @@ import { DyFM_Log } from '@futdevpro/fsm-dynamo';
 import fg from 'fast-glob';
 import { ESLint } from 'eslint';
 
+/**
+ * Result of validating imports in a single file
+ */
 interface ImportValidationResult {
+  /** Path to the file that was validated */
   file: string;
+  /** Array of import 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 import ordering in a single TypeScript file
+ * 
+ * Uses ESLint with the Dynamo import-order rule to check for import ordering
+ * violations and returns detailed error information.
+ * 
+ * @param filePath - Path to the TypeScript file to validate
+ * @returns Promise that resolves to an ImportValidationResult object
+ * 
+ * @example
+ * ```typescript
+ * const result = await validateImportsInFile('./src/components/Button.tsx');
+ * if (result.errors.length > 0) {
+ *   console.log(`Found ${result.errors.length} import violations`);
+ * }
+ * ```
+ */
 async function validateImportsInFile(filePath: string): Promise<ImportValidationResult> {
+  // Configure ESLint with Dynamo import-order rule
   const eslint = new ESLint({
     baseConfig: {
       parser: '@typescript-eslint/parser',
@@ -115,9 +166,11 @@ async function validateImportsInFile(filePath: string): Promise<ImportValidation
     } as any,
   });
 
+  // Run ESLint on the file
   const results = await eslint.lintFiles([ filePath ]);
   const result = results[0];
 
+  // Transform ESLint messages into our result format
   return {
     file: filePath,
     errors: result.messages.map(msg => ({
@@ -129,7 +182,19 @@ async function validateImportsInFile(filePath: string): Promise<ImportValidation
   };
 }
 
+/**
+ * Main function that validates import ordering across all TypeScript files
+ * 
+ * Scans for all .ts and .tsx files in the project, validates import ordering
+ * using the Dynamo import-order 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() {
+  // Find all TypeScript files, excluding common directories and test files
   const files = await fg([ '**/*.{ts,tsx}' ], { 
     ignore: [ '**/node_modules/**', '**/build/**', '**/dist/**', '**/*.spec.ts', '**/*.test.ts' ], 
   });
@@ -139,6 +204,7 @@ async function main() {
   const results: ImportValidationResult[] = [];
   let totalErrors = 0;
 
+  // Process each file individually
   for (const file of files) {
     try {
       const result = await validateImportsInFile(file);
@@ -150,15 +216,16 @@ async function main() {
     }
   }
 
-  // Report results
+  // Filter files that have import violations
   const filesWithErrors = results.filter(r => r.errors.length > 0);
   
+  // Report success if no violations found
   if (filesWithErrors.length === 0) {
     DyFM_Log.log('✅ All import validations passed!');
-
     return;
   }
 
+  // Report detailed error information
   DyFM_Log.warn(`\n❌ Found ${totalErrors} import validation errors in ${filesWithErrors.length} files:\n`);
 
   filesWithErrors.forEach(result => {
@@ -169,9 +236,11 @@ async function main() {
     DyFM_Log.log('');
   });
 
+  // Exit with error code to indicate validation failure
   process.exit(1);
 }
 
+// Execute the main function and handle any errors
 main().catch((err) => {
   DyFM_Log.error('Validation failed:', err);
   process.exit(1);

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);
 });
 
-