@futdevpro/dynamo-eslint 1.15.25 → 1.20.2

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

@@ -1,288 +1,289 @@
-#!/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';
+#!/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;
-}
-
-/**
- * Egy `checker.typeToString(...)`-bol jovo TIPUS-STRING-et valodi `ts.TypeNode`-da
- * alakit ugy, hogy egy eldobhato `type __T = <typeString>;` forrast parse-ol es
- * kiszedi belole a TypeNode-ot.
- *
- * MIERT: a regi megoldas `ts.factory.createTypeReferenceNode(typeString)`-et hivott,
- * ami CSAK bare identifier-t (entity-name-et) fogad el. Egy generic/union/stb.
- * tipus-string (pl. `Record<string, unknown>`) eseten ez tort node-ot epitett, amit
- * a printer csonka `Record`-kent (type-argumentumok nelkul) emittalt — ami EGYSZERRE
- * tsc-hiba ES uj lint-hiba, igy egyetlen fix-futas 0 → 1+ lint-szamot regresszalt.
- * A `typeToString` mindig syntactically valid TS tipus-syntaxot ad vissza, ezert a
- * `type __T = …;` parse-olas minden esetre korrekt TypeNode-ot allit elo.
- *
- * BAIL-OUT: ha a tipus nem alakithato biztonsagos node-da — pl. inline
- * `import("/abs/path").Foo` format tartalmaz, ami abszolut path-t szivarogtatna a
- * fajlba —, `undefined`-et adunk vissza. A hivo ilyenkor KIHAGYJA az annotaciot:
- * jobb annotalatlanul hagyni (marad a figyelmeztetes), mint tort kodot irni.
- */
-function buildTypeNodeFromString(typeString: string): ts.TypeNode | undefined {
-  // Inline `import(...)` tipus → projekt-specifikus abszolut/relativ path-t vinne a
-  // fajlba; sosem biztonsagos textualisan beilleszteni, ezert bail.
-  if (typeString.includes('import(')) {
-    return undefined;
-  }
-
-  const probe: ts.SourceFile = ts.createSourceFile(
-    '__dynamo_type_probe__.ts',
-    `type __T = ${typeString};`,
-    ts.ScriptTarget.Latest,
-    /* setParentNodes */ false,
-  );
-
-  const statement: ts.Statement | undefined = probe.statements[0];
-
-  if (!statement || !ts.isTypeAliasDeclaration(statement) || !statement.type) {
-    return undefined;
-  }
-
-  return statement.type;
-}
-
-/**
- * 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,
-    strict: true,
-    skipLibCheck: true,
-  });
-  
-  const checker = program.getTypeChecker();
-  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 without return types
-    if (ts.isFunctionDeclaration(node) && !node.type) {
-      const signature = checker.getSignatureFromDeclaration(node);
-      
-      if (signature) {
-        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 = buildTypeNodeFromString(typeString);
-
-          // newType === undefined → a tipus nem serializalhato biztonsagosan,
-          // kihagyjuk az annotaciot ahelyett hogy tort kodot irnank (B2 bail-out).
-          if (newType) {
-            const updatedNode = ts.factory.updateFunctionDeclaration(
-              node,
-              node.modifiers,
-              node.asteriskToken,
-              node.name,
-              node.typeParameters,
-              node.parameters,
-              newType,
-              node.body
-            );
-            changes++;
-            hasChanges = true;
-            return ts.visitEachChild(updatedNode, visit, {} as ts.TransformationContext);
-          }
-        }
-      }
-    }
-    
-    // Handle arrow functions without return types
-    if (ts.isArrowFunction(node) && !node.type) {
-      const signature = checker.getSignatureFromDeclaration(node);
-
-      if (signature) {
-        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 = buildTypeNodeFromString(typeString);
-
-          // newType === undefined → a tipus nem serializalhato biztonsagosan,
-          // kihagyjuk az annotaciot ahelyett hogy tort kodot irnank (B2 bail-out).
-          if (newType) {
-            const updatedNode = ts.factory.updateArrowFunction(
-              node,
-              node.modifiers,
-              node.typeParameters,
-              node.parameters,
-              newType,
-              node.equalsGreaterThanToken,
-              node.body
-            );
-            changes++;
-            hasChanges = true;
-            return ts.visitEachChild(updatedNode, visit, {} as ts.TransformationContext);
-          }
-        }
-      }
-    }
-
-    // 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);
-    fs.writeFileSync(filePath, newSourceCode);
-  }
-  
-  return {
-    file: filePath,
-    fixed: hasChanges,
-    changes,
-  };
-}
-
-
-/**
- * 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/**',
-      '**/build/**',
-      '**/dist/**',
-      '**/*.spec.ts',
-      '**/*.test.ts',
-    ],
-  });
-  
-  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 = addTypesToFile(file);
-      results.push(result);
-      
-      // Track successful fixes
-      if (result.fixed) {
-        totalFixed++;
-        totalChanges += result.changes;
-        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 type annotations added: ${totalChanges}`);
-  
-  // Provide appropriate success/failure message
-  if (totalFixed > 0) {
-    DyFM_Log.log(`🎉 Successfully added type annotations to ${totalFixed} files!`);
-  } else {
-    DyFM_Log.log('✅ No files needed type annotation fixes!');
-  }
-}
-
-// Csak akkor futtatjuk a teljes fajl-scan-t, ha a scriptet KOZVETLENUL hivjak
-// (CLI bin / `npm run fix:return-types`). Import eseten (pl. spec a helper-ekhez)
-// NEM indul el a main(), igy a tiszta segedfuggvenyek unit-tesztelhetok.
-if (require.main === module) {
-  // Execute the main function and handle any errors
-  main().catch((err) => {
-    DyFM_Log.error('Fix script failed:', err);
-    process.exit(1);
-  });
-}
-
-export { buildTypeNodeFromString, addTypesToFile };
-
 
+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;
+}
+
+/**
+ * Egy `checker.typeToString(...)`-bol jovo TIPUS-STRING-et valodi `ts.TypeNode`-da
+ * alakit ugy, hogy egy eldobhato `type __T = <typeString>;` forrast parse-ol es
+ * kiszedi belole a TypeNode-ot.
+ *
+ * MIERT: a regi megoldas `ts.factory.createTypeReferenceNode(typeString)`-et hivott,
+ * ami CSAK bare identifier-t (entity-name-et) fogad el. Egy generic/union/stb.
+ * tipus-string (pl. `Record<string, unknown>`) eseten ez tort node-ot epitett, amit
+ * a printer csonka `Record`-kent (type-argumentumok nelkul) emittalt — ami EGYSZERRE
+ * tsc-hiba ES uj lint-hiba, igy egyetlen fix-futas 0 → 1+ lint-szamot regresszalt.
+ * A `typeToString` mindig syntactically valid TS tipus-syntaxot ad vissza, ezert a
+ * `type __T = …;` parse-olas minden esetre korrekt TypeNode-ot allit elo.
+ *
+ * BAIL-OUT: ha a tipus nem alakithato biztonsagos node-da — pl. inline
+ * `import("/abs/path").Foo` format tartalmaz, ami abszolut path-t szivarogtatna a
+ * fajlba —, `undefined`-et adunk vissza. A hivo ilyenkor KIHAGYJA az annotaciot:
+ * jobb annotalatlanul hagyni (marad a figyelmeztetes), mint tort kodot irni.
+ */
+function buildTypeNodeFromString(typeString: string): ts.TypeNode | undefined {
+  // Inline `import(...)` tipus → projekt-specifikus abszolut/relativ path-t vinne a
+  // fajlba; sosem biztonsagos textualisan beilleszteni, ezert bail.
+  if (typeString.includes('import(')) {
+    return undefined;
+  }
+
+  const probe: ts.SourceFile = ts.createSourceFile(
+    '__dynamo_type_probe__.ts',
+    `type __T = ${typeString};`,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */ false,
+  );
+
+  const statement: ts.Statement | undefined = probe.statements[0];
+
+  if (!statement || !ts.isTypeAliasDeclaration(statement) || !statement.type) {
+    return undefined;
+  }
+
+  return statement.type;
+}
+
+/**
+ * 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,
+    strict: true,
+    skipLibCheck: true,
+  });
+  
+  const checker = program.getTypeChecker();
+  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 without return types
+    if (ts.isFunctionDeclaration(node) && !node.type) {
+      const signature = checker.getSignatureFromDeclaration(node);
+      
+      if (signature) {
+        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 = buildTypeNodeFromString(typeString);
+
+          // newType === undefined → a tipus nem serializalhato biztonsagosan,
+          // kihagyjuk az annotaciot ahelyett hogy tort kodot irnank (B2 bail-out).
+          if (newType) {
+            const updatedNode = ts.factory.updateFunctionDeclaration(
+              node,
+              node.modifiers,
+              node.asteriskToken,
+              node.name,
+              node.typeParameters,
+              node.parameters,
+              newType,
+              node.body
+            );
+            changes++;
+            hasChanges = true;
+            return ts.visitEachChild(updatedNode, visit, {} as ts.TransformationContext);
+          }
+        }
+      }
+    }
+    
+    // Handle arrow functions without return types
+    if (ts.isArrowFunction(node) && !node.type) {
+      const signature = checker.getSignatureFromDeclaration(node);
+
+      if (signature) {
+        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 = buildTypeNodeFromString(typeString);
+
+          // newType === undefined → a tipus nem serializalhato biztonsagosan,
+          // kihagyjuk az annotaciot ahelyett hogy tort kodot irnank (B2 bail-out).
+          if (newType) {
+            const updatedNode = ts.factory.updateArrowFunction(
+              node,
+              node.modifiers,
+              node.typeParameters,
+              node.parameters,
+              newType,
+              node.equalsGreaterThanToken,
+              node.body
+            );
+            changes++;
+            hasChanges = true;
+            return ts.visitEachChild(updatedNode, visit, {} as ts.TransformationContext);
+          }
+        }
+      }
+    }
+
+    // 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);
+    fs.writeFileSync(filePath, newSourceCode);
+  }
+  
+  return {
+    file: filePath,
+    fixed: hasChanges,
+    changes,
+  };
+}
+
+
+/**
+ * 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/**',
+      '**/build/**',
+      '**/dist/**',
+      '**/*.spec.ts',
+      '**/*.test.ts',
+    ],
+  });
+  
+  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 = addTypesToFile(file);
+      results.push(result);
+      
+      // Track successful fixes
+      if (result.fixed) {
+        totalFixed++;
+        totalChanges += result.changes;
+        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 type annotations added: ${totalChanges}`);
+  
+  // Provide appropriate success/failure message
+  if (totalFixed > 0) {
+    DyFM_Log.log(`🎉 Successfully added type annotations to ${totalFixed} files!`);
+  } else {
+    DyFM_Log.log('✅ No files needed type annotation fixes!');
+  }
+}
+
+// Csak akkor futtatjuk a teljes fajl-scan-t, ha a scriptet KOZVETLENUL hivjak
+// (CLI bin / `npm run fix:return-types`). Import eseten (pl. spec a helper-ekhez)
+// NEM indul el a main(), igy a tiszta segedfuggvenyek unit-tesztelhetok.
+if (require.main === module) {
+  // Execute the main function and handle any errors
+  main().catch((err) => {
+    DyFM_Log.error('Fix script failed:', err);
+    process.exit(1);
+  });
+}
+
+export { buildTypeNodeFromString, addTypesToFile };
+
+