@futdevpro/dynamo-eslint 1.14.3 → 1.14.6

package/src/scripts/dynamo-fix.ts

@@ -1,17 +1,63 @@
 #!/usr/bin/env node
+/**
+ * @fileoverview Dynamo ESLint Auto-Fix Script
+ * 
+ * This script runs ESLint with auto-fix capabilities on TypeScript files across the project.
+ * It processes all .ts and .tsx files, applies Dynamo-specific rules, and automatically
+ * fixes issues where possible.
+ * 
+ * @usage
+ * ```bash
+ * dynamo-fix
+ * ```
+ * 
+ * @example
+ * ```bash
+ * # Fix all TypeScript files in the project
+ * npx dynamo-fix
+ * 
+ * # Or run via npm script
+ * npm run fix
+ * ```
+ * 
+ * @author Future Development Program Ltd.
+ * @version 1.14.3
+ */
+
 import fg from 'fast-glob';
 import { ESLint } from 'eslint';
 import { writeFileSync } from 'fs';
 
+/**
+ * Result of fixing a single file
+ */
 interface FixResult {
+  /** Path to the file that was processed */
   file: string;
+  /** Whether the file was actually modified */
   fixed: boolean;
+  /** Number of errors found in the file */
   errors: number;
+  /** Number of warnings found in the file */
   warnings: number;
+  /** Number of fixes applied to the file */
   fixes: number;
 }
 
+/**
+ * Fixes a single TypeScript file using ESLint with auto-fix capabilities
+ * 
+ * @param filePath - Path to the TypeScript file to fix
+ * @returns Promise that resolves to a FixResult object containing fix statistics
+ * 
+ * @example
+ * ```typescript
+ * const result = await fixFile('./src/components/Button.tsx');
+ * console.log(`Fixed ${result.fixes} issues in ${result.file}`);
+ * ```
+ */
 async function fixFile(filePath: string): Promise<FixResult> {
+  // Configure ESLint with Dynamo-specific rules and auto-fix enabled
   const eslint = new ESLint({
     baseConfig: [
       { ignores: [ 'build/**', 'dist/**', 'node_modules/**' ] },
@@ -38,14 +84,16 @@ async function fixFile(filePath: string): Promise<FixResult> {
     fix: true, // Enable auto-fixing
   });
 
+  // Run ESLint on the file
   const results = await eslint.lintFiles([ filePath ]);
   const result = results[0];
 
+  // Write the fixed content back to the file if changes were made
   if (result && result.output) {
-    // Write the fixed content back to the file
     writeFileSync(filePath, result.output);
   }
 
+  // Return comprehensive fix statistics
   return {
     file: filePath,
     fixed: result && result.output !== undefined,
@@ -55,7 +103,18 @@ async function fixFile(filePath: string): Promise<FixResult> {
   };
 }
 
+/**
+ * Main function that processes all TypeScript files in the project
+ * 
+ * Scans for all .ts and .tsx files, applies ESLint fixes, 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/**', '**/build/**', '**/dist/**', '**/*.spec.ts', '**/*.test.ts' ], 
   });
@@ -68,17 +127,20 @@ async function main() {
   let totalWarnings = 0;
   let totalFixes = 0;
 
+  // Process each file individually
   for (const file of files) {
     try {
       const result = await fixFile(file);
 
       results.push(result);
       
+      // Track successful fixes
       if (result.fixed) {
         totalFixed++;
         console.log(`✅ Fixed: ${result.file}`);
       }
       
+      // Accumulate statistics
       totalErrors += result.errors;
       totalWarnings += result.warnings;
       totalFixes += result.fixes;
@@ -87,7 +149,7 @@ async function main() {
     }
   }
 
-  // Report results
+  // Generate comprehensive summary report
   console.log(`\n📊 Fix Summary:`);
   console.log(`   Files processed: ${files.length}`);
   console.log(`   Files fixed: ${totalFixed}`);
@@ -95,6 +157,7 @@ async function main() {
   console.log(`   Total warnings: ${totalWarnings}`);
   console.log(`   Total fixes applied: ${totalFixes}`);
 
+  // Provide appropriate success/failure message
   if (totalFixed === 0) {
     console.log('✅ No files needed fixing!');
   } else {
@@ -102,6 +165,7 @@ async function main() {
   }
 }
 
+// Execute the main function and handle any errors
 main().catch((err) => {
   console.error('Fix failed:', err);
   process.exit(1);

package/src/scripts/eslintrc-audit.ts

@@ -1,43 +1,116 @@
 #!/usr/bin/env node
+/**
+ * @fileoverview ESLint Configuration Audit Script
+ * 
+ * This script analyzes ESLint configuration files (.eslintrc.json) across the project
+ * to provide statistics on rule usage. It helps identify commonly used rules and
+ * potential configuration inconsistencies.
+ * 
+ * @usage
+ * ```bash
+ * dynamo-eslintrc-audit
+ * ```
+ * 
+ * @example
+ * ```bash
+ * # Audit all ESLint configurations in the project
+ * npx dynamo-eslintrc-audit
+ * 
+ * # Or run via npm script
+ * npm run audit:eslintrc
+ * ```
+ * 
+ * @author Future Development Program Ltd.
+ * @version 1.14.3
+ */
+
 import fg from 'fast-glob';
 import { readFileSync } from 'fs';
-
+/** Type alias for any JSON value */
 type AnyJson = any;
 
+/**
+ * Safely parses a JSON file and returns the parsed object or null if parsing fails
+ * 
+ * @param jsonPath - Path to the JSON file to parse
+ * @returns Parsed JSON object or null if parsing fails
+ * 
+ * @example
+ * ```typescript
+ * const config = safeParse('./.eslintrc.json');
+ * if (config) {
+ *   console.log('Rules:', Object.keys(config.rules || {}));
+ * }
+ * ```
+ */
 function safeParse(jsonPath: string): AnyJson | null {
   try {
     const content = readFileSync(jsonPath, 'utf8');
 
     return JSON.parse(content);
   } catch {
+    // Return null for any parsing errors (malformed JSON, file not found, etc.)
     return null;
   }
 }
 
-async function main() {
-  const files = await fg([ '**/.eslintrc.json' ], { ignore: [ '**/node_modules/**' ] });
+/**
+ * Main function that analyzes ESLint configuration files and generates rule usage statistics
+ * 
+ * Scans for all .eslintrc.json files in the project, extracts rule configurations,
+ * and provides a sorted table of the most commonly used rules.
+ * 
+ * @returns Promise that resolves when analysis is complete
+ * 
+ * @example
+ * ```typescript
+ * // The function will output a table like:
+ * // ┌─────────┬─────────────────────────┬───────┐
+ * // │ (index) │          rule           │ count │
+ * // ├─────────┼─────────────────────────┼───────┤
+ * // │    0    │    'no-unused-vars'     │   5   │
+ * // │    1    │    'semi'               │   4   │
+ * // └─────────┴─────────────────────────┴───────┘
+ * ```
+ */
+async function main(): Promise<void> {
+  // Find all ESLint configuration files, excluding node_modules
+  const files: string[] = await fg([ '**/.eslintrc.json' ], { ignore: [ '**/node_modules/**' ] });
   const ruleCounts: Record<string, number> = {};
-  const total = files.length;
+  const total: number = files.length;
 
+  // Process each configuration file
   for (const p of files) {
     const cfg = safeParse(p);
 
+    // Skip files without rules configuration
     if (!cfg?.rules) continue;
 
+    // Count each rule occurrence
     for (const key of Object.keys(cfg.rules)) {
       ruleCounts[key] = (ruleCounts[key] ?? 0) + 1;
     }
   }
 
-  const entries = Object.entries(ruleCounts).sort((a, b) => b[1] - a[1]);
+  // Sort rules by usage count (most used first)
+  const entries = Object.entries(ruleCounts).sort(
+    (a: [ string, number ], b: [ string, number ]): number => b[1] - a[1]
+  );
 
+  // Display results
   console.log(`[dynamo-eslintrc-audit] analyzed ${total} files`);
   console.table(entries.slice(0, 50).map(([ rule, count ]) => ({ rule, count })));
 }
 
-main().catch((err) => {
+// Execute the main function and handle any errors
+main().catch((err: Error): void => {
   console.error(err);
   process.exit(1);
 });
 
 
+
+
+
+
+

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