@futdevpro/dynamo-eslint 1.14.3 → 1.14.4

package/src/plugin/rules/explicit-types.ts

@@ -0,0 +1,169 @@
+import { Rule } from 'eslint';
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'suggestion',
+    docs: { 
+      description: 'Enforce explicit type annotations on all TypeScript declarations',
+      recommended: true,
+    },
+    schema: [],
+    messages: {
+      missingReturnType: 'Function "{{name}}" must have an explicit return type annotation.',
+      missingArrowReturnType: 'Arrow function must have an explicit return type annotation.',
+      missingVariableType: 'Variable "{{name}}" must have an explicit type annotation.',
+      missingParameterType: 'Parameter "{{name}}" must have an explicit type annotation.',
+      missingPropertyType: 'Class property "{{name}}" must have an explicit type annotation.',
+      missingDestructuringType: 'Destructuring assignment must have explicit type annotations.',
+    },
+  },
+  create(context) {
+    return {
+      // Function declarations
+      FunctionDeclaration(node: any) {
+        try {
+          // Check return type
+          if (!node.returnType) {
+            context.report({
+              node,
+              messageId: 'missingReturnType',
+              data: { name: node.id?.name || 'anonymous' },
+            });
+          }
+
+          // Check function parameters with defensive checks
+          if (node.params && Array.isArray(node.params)) {
+            node.params.forEach((param: any) => {
+              try {
+                if (param && param.type === 'Identifier' && !param.typeAnnotation) {
+                  context.report({
+                    node: param,
+                    messageId: 'missingParameterType',
+                    data: { name: param.name || 'unknown' },
+                  });
+                }
+              } catch (paramError) {
+                console.error('[explicit-types] Error processing function parameter:', paramError);
+              }
+            });
+          }
+        } catch (error) {
+          console.error('[explicit-types] Error in FunctionDeclaration visitor:', error);
+        }
+      },
+
+      // Arrow functions
+      ArrowFunctionExpression(node: any) {
+        try {
+          // Check return type
+          if (!node.returnType) {
+            context.report({
+              node,
+              messageId: 'missingArrowReturnType',
+            });
+          }
+
+          // Check arrow function parameters with defensive checks
+          if (node.params && Array.isArray(node.params)) {
+            node.params.forEach((param: any) => {
+              try {
+                if (param && param.type === 'Identifier' && !param.typeAnnotation) {
+                  context.report({
+                    node: param,
+                    messageId: 'missingParameterType',
+                    data: { name: param.name || 'unknown' },
+                  });
+                }
+              } catch (paramError) {
+                console.error('[explicit-types] Error processing arrow function parameter:', paramError);
+              }
+            });
+          }
+        } catch (error) {
+          console.error('[explicit-types] Error in ArrowFunctionExpression visitor:', error);
+        }
+      },
+
+      // Variable declarations
+      VariableDeclarator(node: any) {
+        try {
+          // Defensive check for node.id
+          if (!node.id) {
+            return;
+          }
+
+          if (!node.id.typeAnnotation) {
+            // Skip if variable is initialized with a typed value that can be inferred
+            const hasTypedInitializer = node.init && (
+              node.init.type === 'CallExpression' ||
+              node.init.type === 'NewExpression' ||
+              node.init.type === 'ArrayExpression' ||
+              node.init.type === 'ObjectExpression' ||
+              node.init.type === 'Literal'
+            );
+
+            if (!hasTypedInitializer) {
+              context.report({
+                node: node.id,
+                messageId: 'missingVariableType',
+                data: { name: (node.id as any)?.name || 'destructured' },
+              });
+            }
+          }
+        } catch (error) {
+          console.error('[explicit-types] Error in VariableDeclarator visitor:', error);
+        }
+      },
+
+      // Class properties
+      PropertyDefinition(node: any) {
+        try {
+          // Defensive check for node.key
+          if (!node.key) {
+            return;
+          }
+
+          if (!node.typeAnnotation && !node.value) {
+            context.report({
+              node: node.key,
+              messageId: 'missingPropertyType',
+              data: { name: (node.key as any)?.name || 'computed' },
+            });
+          }
+        } catch (error) {
+          console.error('[explicit-types] Error in PropertyDefinition visitor:', error);
+        }
+      },
+
+      // Object destructuring
+      ObjectPattern(node: any) {
+        try {
+          if (!node.typeAnnotation) {
+            context.report({
+              node,
+              messageId: 'missingDestructuringType',
+            });
+          }
+        } catch (error) {
+          console.error('[explicit-types] Error in ObjectPattern visitor:', error);
+        }
+      },
+
+      // Array destructuring
+      ArrayPattern(node: any) {
+        try {
+          if (!node.typeAnnotation) {
+            context.report({
+              node,
+              messageId: 'missingDestructuringType',
+            });
+          }
+        } catch (error) {
+          console.error('[explicit-types] Error in ArrayPattern visitor:', error);
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/src/plugin/rules/import/no-import-type.ts

@@ -15,19 +15,28 @@ const rule: Rule.RuleModule = {
 
     return {
       ImportDeclaration(node: any) {
-        // Check for import type usage
-        if (node.importKind === 'type') {
-          context.report({
-            node,
-            messageId: 'forbiddenImportType',
-            fix(fixer) {
-              // Remove 'type' keyword
-              const importText = sourceCode.getText(node);
-              const newImportText = importText.replace(/import\s+type\s+/, 'import ');
+        try {
+          // Check for import type usage
+          if (node.importKind === 'type') {
+            context.report({
+              node,
+              messageId: 'forbiddenImportType',
+              fix(fixer) {
+                try {
+                  // Remove 'type' keyword
+                  const importText = sourceCode.getText(node);
+                  const newImportText = importText.replace(/import\s+type\s+/, 'import ');
 
-              return fixer.replaceText(node, newImportText);
-            },
-          });
+                  return fixer.replaceText(node, newImportText);
+                } catch (fixError) {
+                  console.error('[no-import-type] Error in fix function:', fixError);
+                  return null;
+                }
+              },
+            });
+          }
+        } catch (error) {
+          console.error('[no-import-type] Error in ImportDeclaration visitor:', error);
         }
       },
     };

package/src/plugin/rules/import/no-js-import.ts

@@ -13,19 +13,27 @@ const rule: Rule.RuleModule = {
   create(context) {
     return {
       ImportDeclaration(node: any) {
-        const source = node.source.value as string;
-        
-        if (source.endsWith('.js')) {
-          context.report({
-            node: node.source,
-            messageId: 'forbiddenJsExtension',
-            fix(fixer) {
-              // Remove .js extension
-              const newSource = source.replace(/\.js$/, '');
-
-              return fixer.replaceText(node.source, `'${newSource}'`);
-            },
-          });
+        try {
+          const source = node.source?.value as string;
+          
+          if (source && source.endsWith('.js')) {
+            context.report({
+              node: node.source,
+              messageId: 'forbiddenJsExtension',
+              fix(fixer) {
+                try {
+                  // Remove .js extension
+                  const newSource = source.replace(/\.js$/, '');
+                  return fixer.replaceText(node.source, `'${newSource}'`);
+                } catch (fixError) {
+                  console.error('[no-js-import] Error in fix function:', fixError);
+                  return null;
+                }
+              },
+            });
+          }
+        } catch (error) {
+          console.error('[no-js-import] Error in ImportDeclaration visitor:', error);
         }
       },
     };

package/src/plugin/rules/naming-patterns.ts

@@ -13,8 +13,12 @@ const rule: Rule.RuleModule = {
   create(context) {
     return {
       Identifier(node) {
-        // Future: use dyfmUtils naming patterns to validate identifiers
-        void node;
+        try {
+          // Future: use dyfmUtils naming patterns to validate identifiers
+          void node;
+        } catch (error) {
+          console.error('[naming-patterns] Error in Identifier visitor:', error);
+        }
       },
     };
   },

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,114 @@
 #!/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;
   }
 }
 
+/**
+ * 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() {
+  // Find all ESLint configuration files, excluding node_modules
   const files = await fg([ '**/.eslintrc.json' ], { ignore: [ '**/node_modules/**' ] });
   const ruleCounts: Record<string, number> = {};
   const total = 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;
     }
   }
 
+  // Sort rules by usage count (most used first)
   const entries = Object.entries(ruleCounts).sort((a, b) => 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 })));
 }
 
+// Execute the main function and handle any errors
 main().catch((err) => {
   console.error(err);
   process.exit(1);
 });
 
 
+
+
+
+
+