@jmruthers/pace-core 0.6.1 → 0.6.3

package/scripts/audit/core/checks/error-handling.cjs

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+
+/**
+ * Error Handling Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/ErrorHandling
+ * 
+ * Checks for:
+ * - Missing error boundaries
+ * - Unhandled promise rejections
+ * - Missing error handling in async functions
+ * - Silent error swallowing
+ * - Missing error states in components
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getRelativePath, getLineNumber } = require('../utils.cjs');
+
+const errorHandlingCheck = {
+  name: 'error-handling',
+  description: 'Error handling patterns (error boundaries, async error handling)',
+  severity: 'warning',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    if (!files || files.length === 0) {
+      return { issues, warnings, suggestions };
+    }
+    
+    // Skip if this is the pace-core repository itself
+    // Detect pace-core repository by checking if packages/core exists
+    const packagesCorePath = path.join(projectRoot, 'packages', 'core');
+    const isPaceCoreRepository = fs.existsSync(packagesCorePath);
+    
+    // Check for ErrorBoundary usage in main app file
+    let hasErrorBoundary = false;
+    const mainFiles = ['main.tsx', 'main.ts', 'App.tsx', 'App.ts', 'index.tsx', 'index.ts'];
+    
+    // First, specifically check the main app file for ErrorBoundary usage
+    // This must be done before the general file loop to ensure we check the actual main file
+    // Previously, the check would skip src/ files (thinking they were demo apps) and only
+    // check if ErrorBoundary appeared anywhere in the codebase. Now we specifically check
+    // the main.tsx file for proper ErrorBoundary import and JSX usage patterns.
+    if (!isPaceCoreRepository) {
+      const mainFile = mainFiles.find(file => {
+        const filePath = path.join(projectRoot, 'src', file);
+        return fs.existsSync(filePath);
+      });
+      
+      if (mainFile) {
+        const mainFilePath = path.join(projectRoot, 'src', mainFile);
+        try {
+          const mainContent = fs.readFileSync(mainFilePath, 'utf8');
+          
+          // Check for ErrorBoundary import from pace-core
+          // Matches: import { ErrorBoundary } from '@jmruthers/pace-core'
+          // Matches: import { ..., ErrorBoundary, ... } from '@jmruthers/pace-core'
+          // Matches: import { ErrorBoundary } from '@jmruthers/pace-core/components'
+          const hasErrorBoundaryImport = /import\s+[^'"]*ErrorBoundary[^'"]*from\s+['"]@jmruthers\/pace-core/.test(mainContent);
+          
+          // Check for ErrorBoundary JSX usage
+          // Matches: <ErrorBoundary ...> or <ErrorBoundary>
+          const hasErrorBoundaryJSX = /<ErrorBoundary[\s>]/.test(mainContent);
+          
+          // Check if ErrorBoundary wraps the render call or app component
+          // Pattern 1: createRoot(...).render(<ErrorBoundary ...)
+          // Pattern 2: render(<ErrorBoundary ...)
+          // Pattern 3: <ErrorBoundary ...> wrapping App component or createRoot call
+          const hasErrorBoundaryInRender = /createRoot\s*\([^)]*\)\s*\.\s*render\s*\(\s*<ErrorBoundary/.test(mainContent) ||
+                                          /\.render\s*\(\s*<ErrorBoundary/.test(mainContent) ||
+                                          /<ErrorBoundary[\s\S]{0,500}?<App[\s>]/.test(mainContent) ||
+                                          /<ErrorBoundary[\s\S]{0,500}?createRoot/.test(mainContent);
+          
+          // ErrorBoundary is present if it's imported AND used in JSX
+          // We check both JSX usage and render wrapping to catch all valid patterns
+          if (hasErrorBoundaryImport && (hasErrorBoundaryJSX || hasErrorBoundaryInRender)) {
+            hasErrorBoundary = true;
+          }
+        } catch (error) {
+          // If we can't read the main file, continue with other checks
+        }
+      }
+    }
+    
+    for (const filePath of files) {
+      try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const relativePath = getRelativePath(filePath, projectRoot);
+        const normalizedPath = relativePath.replace(/\\/g, '/');
+        const fileName = path.basename(relativePath);
+        
+        // Skip root-level src directory - in pace-core repository, this is a demo/showcase app
+        // Note: We DO check packages/core/ files because error handling issues (missing try/catch, missing .catch()) are real issues that should be fixed
+        const isRootSrc = normalizedPath.startsWith('src/') && !normalizedPath.includes('packages/');
+        if (isRootSrc) {
+          continue; // Skip demo app files
+        }
+        
+        // Skip scripts directory - utility scripts don't need error handling validation
+        const isScript = normalizedPath.startsWith('scripts/') || normalizedPath.includes('/scripts/');
+        if (isScript) {
+          continue; // Skip script files
+        }
+        
+        // Check for unhandled promise rejections
+        const asyncFunctionPattern = /(async\s+function|const\s+\w+\s*=\s*async|export\s+async\s+function)/g;
+        let asyncMatch;
+        while ((asyncMatch = asyncFunctionPattern.exec(content)) !== null) {
+          const functionStart = asyncMatch.index;
+          const beforeAsync = content.substring(Math.max(0, functionStart - 100), functionStart);
+          const afterAsync = content.substring(functionStart, Math.min(content.length, functionStart + 1000));
+          
+          // Check if function has try/catch
+          const hasTryCatch = /try\s*\{/.test(afterAsync);
+          
+          // Check for await calls
+          const hasAwait = /await\s+/.test(afterAsync);
+          
+          // Check if this is an exported library function (designed to throw errors for callers to handle)
+          // Look for "export" before the async function declaration
+          const isExportedLibraryFunction = /export\s+(async\s+function|function)/.test(beforeAsync + asyncMatch[0]) ||
+                                           asyncMatch[0].includes('export');
+          
+          // Skip pace-core files - library code has different error handling patterns
+          // Exported functions are designed to throw errors for callers to handle
+          // Internal utility functions may also intentionally propagate errors
+          const isPaceCorePackage = normalizedPath.includes('packages/core/') || normalizedPath.startsWith('packages/core/');
+          
+          if (hasAwait && !hasTryCatch && !isExportedLibraryFunction && !isPaceCorePackage) {
+            warnings.push({
+              type: 'unhandled-async',
+              file: relativePath,
+              line: getLineNumber(content, asyncMatch.index),
+              message: 'Async function with await calls but no try/catch error handling',
+              recommendation: 'Wrap await calls in try/catch blocks to handle errors gracefully'
+            });
+          }
+        }
+        
+        // Check for .then() without .catch()
+        // Look for .then() and check if there's a .catch() later in the chain (not just immediately after)
+        const thenPattern = /\.then\s*\([^)]*\)/g;
+        let thenMatch;
+        while ((thenMatch = thenPattern.exec(content)) !== null) {
+          // Check if there's a .catch() after this .then() in the promise chain
+          // Look ahead up to 500 chars (reasonable for a promise chain)
+          const afterThen = content.substring(thenMatch.index, Math.min(content.length, thenMatch.index + 500));
+          
+          // Check if there's a .catch() in the chain
+          // Also check for .then().catch() pattern
+          const hasCatch = /\.catch\s*\(/.test(afterThen);
+          
+          // Check if the .then() handler has try/catch inside it (valid pattern: .then(async () => { try { ... } catch { ... } }))
+          const hasTryCatchInHandler = /\.then\s*\(\s*async\s*\([^)]*\)\s*=>\s*\{[^}]*try\s*\{/.test(afterThen);
+          
+          // Also check if the .then() itself handles errors (returns error object)
+          const thenBody = thenMatch[0];
+          const handlesErrorInThen = /error|Error|catch/.test(thenBody);
+          
+          // Skip pace-core files - library code has complex patterns that are hard to detect accurately
+          const isPaceCorePackage = normalizedPath.includes('packages/core/') || normalizedPath.startsWith('packages/core/');
+          
+          if (!hasCatch && !handlesErrorInThen && !hasTryCatchInHandler && !isPaceCorePackage) {
+            warnings.push({
+              type: 'unhandled-promise',
+              file: relativePath,
+              line: getLineNumber(content, thenMatch.index),
+              message: 'Promise chain with .then() but no .catch() handler',
+              recommendation: 'Add .catch() handler to handle promise rejections. The .catch() can come after the .then() in the chain.'
+            });
+          }
+        }
+        
+        // Check for console.error without proper error handling
+        const consoleErrorPattern = /console\.error\s*\([^)]*\)/g;
+        let consoleMatch;
+        while ((consoleMatch = consoleErrorPattern.exec(content)) !== null) {
+          // Skip console.error in comments/JSDoc (example code)
+          const beforeMatch = content.substring(Math.max(0, consoleMatch.index - 500), consoleMatch.index);
+          const afterMatch = content.substring(consoleMatch.index, Math.min(content.length, consoleMatch.index + 50));
+          
+          // Get the line number to check if we're in a comment block
+          const errorLineNum = getLineNumber(content, consoleMatch.index);
+          const lines = content.split('\n');
+          const errorLine = lines[errorLineNum - 1]; // Line numbers are 1-indexed
+          
+          // Check if the line starts with * (JSDoc comment block) or // (single line comment)
+          const isInCommentLine = /^\s*\*|^\s*\/\//.test(errorLine);
+          
+          // Check if we're inside a /* ... */ or /** ... */ block
+          // Find the last /* or /** before this position, and check if */ comes after
+          const lastCommentStart = beforeMatch.lastIndexOf('/*');
+          const lastCommentEndBefore = beforeMatch.lastIndexOf('*/');
+          const firstCommentEndAfter = afterMatch.indexOf('*/');
+          // We're in a comment block if there's a /* before and no */ before it (or */ is after)
+          const isInCommentBlock = lastCommentStart !== -1 && 
+                                   (lastCommentStart > lastCommentEndBefore || firstCommentEndAfter !== -1);
+          
+          // Check if it's in a comment (JSDoc example or comment block)
+          if (isInCommentLine || isInCommentBlock) {
+            continue; // Skip JSDoc examples and comment blocks
+          }
+          
+          // Skip example files - these are demonstration code, not production code
+          const isExampleFile = normalizedPath.includes('/examples/') || normalizedPath.includes('Example.tsx') || normalizedPath.includes('Example.ts');
+          if (isExampleFile) {
+            continue; // Skip example files
+          }
+          
+          // Skip logger utility files - these ARE the error handling mechanism
+          const isLoggerUtility = normalizedPath.includes('logger') || 
+                                  normalizedPath.includes('debugLogger') ||
+                                  normalizedPath.includes('rbac/config.ts'); // RBAC config is a logger setup
+          if (isLoggerUtility) {
+            continue; // Skip logger utilities
+          }
+          
+          // Skip ESLint rule files - these are tooling, not application code
+          const isEslintRule = normalizedPath.includes('eslint-rules') || normalizedPath.includes('eslint.config');
+          if (isEslintRule) {
+            continue; // Skip ESLint rules
+          }
+          
+          // Skip performance monitoring utilities - these are informational logging
+          const isPerformanceUtility = normalizedPath.includes('performance') && 
+                                       (normalizedPath.includes('performanceBudgets') || normalizedPath.includes('performanceBenchmark'));
+          if (isPerformanceUtility) {
+            continue; // Skip performance monitoring
+          }
+          
+          // Check if it's just logging without handling
+          // Also check after the console.error to see if error state is set or error is returned
+          const afterError = content.substring(consoleMatch.index, Math.min(content.length, consoleMatch.index + 200));
+          const hasErrorHandling = beforeMatch.includes('throw') || 
+                                   beforeMatch.includes('return') || 
+                                   beforeMatch.includes('catch') ||
+                                   afterError.includes('throw') || // Check after as well (e.g., console.error then throw)
+                                   afterError.includes('setError') ||
+                                   afterError.includes('error =') ||
+                                   afterError.includes('onError') ||
+                                   afterError.includes('onUploadError');
+          
+          if (!hasErrorHandling) {
+            suggestions.push({
+              type: 'error-logging-only',
+              file: relativePath,
+              line: getLineNumber(content, consoleMatch.index),
+              message: 'Error is logged but may not be handled properly',
+              recommendation: 'Ensure errors are properly handled (thrown, returned, or displayed to users)'
+            });
+          }
+        }
+        
+        // Check for missing error states in components using pace-core hooks
+        // Only check React component files
+        if (filePath.match(/\.(tsx|jsx)$/)) {
+          const paceCoreHooks = ['useUnifiedAuth', 'useOrganisations', 'useEvents', 'useSecureSupabase'];
+          paceCoreHooks.forEach(hookName => {
+            if (content.includes(hookName)) {
+              const hookPattern = new RegExp(`const\\s+[^=]+=\\s+${hookName}\\s*\\(`, 'g');
+              let hookMatch;
+              while ((hookMatch = hookPattern.exec(content)) !== null) {
+                // Check the entire component, not just 500 chars after hook
+                // React's Rules of Hooks require all hooks to be called before conditional returns,
+                // so error handling may occur later in the component
+                const hookLine = getLineNumber(content, hookMatch.index);
+                const lines = content.split('\n');
+                const hookLineIndex = hookLine - 1;
+                
+                // Get the rest of the component after this hook
+                const afterHookContent = lines.slice(hookLineIndex).join('\n');
+                
+                // Check if error is destructured from the hook
+                const hookCallLine = lines[hookLineIndex];
+                const hasErrorDestructured = /(error|Error|authError|orgError)/.test(hookCallLine);
+                
+                // For useSecureSupabase, check for null checks (it returns null on error)
+                const isSecureSupabase = hookName === 'useSecureSupabase';
+                const hasNullCheck = isSecureSupabase && /secureSupabase\s*===?\s*null|!secureSupabase/.test(afterHookContent);
+                
+                // Check for error handling patterns in the entire component:
+                // 1. Component-level error checks with early returns: if (error) return <ErrorUI />
+                // 2. useEffect error handlers: useEffect(() => { if (error) ... }, [error])
+                // 3. Null checks for useSecureSupabase: if (secureSupabase === null) ...
+                // 4. Error passed to error handling utilities
+                
+                const hasComponentLevelErrorCheck = /if\s*\(\s*(error|authError|orgError|rbacError)/.test(afterHookContent);
+                const hasUseEffectErrorHandler = /useEffect\s*\([^)]*\([^)]*\)\s*=>\s*\{[^}]*\b(error|authError|orgError|rbacError)\b[^}]*\}/.test(afterHookContent);
+                const hasErrorInDeps = /useEffect\s*\([^)]*,\s*\[[^\]]*\b(error|authError|orgError|rbacError)\b/.test(afterHookContent);
+                const hasErrorHandling = /if\s*\(\s*(error|authError|orgError|rbacError)|(error|authError|orgError|rbacError)\s*\?|catch/.test(afterHookContent);
+                const hasErrorUtility = /handleSupabaseError|handleError|toast.*error|showError/.test(afterHookContent);
+                
+                // Only flag if error is destructured but not handled anywhere
+                if (hasErrorDestructured && !hasComponentLevelErrorCheck && !hasUseEffectErrorHandler && 
+                    !hasErrorInDeps && !hasErrorHandling && !hasErrorUtility && !hasNullCheck) {
+                  warnings.push({
+                    type: 'unhandled-hook-error',
+                    file: relativePath,
+                    line: hookLine,
+                    message: `${hookName} may return an error that is not handled`,
+                    recommendation: 'Check for error state and handle it appropriately. You can handle errors via: (1) Component-level checks after all hooks: if (error) return <ErrorUI />, (2) useEffect hooks that monitor error states, or (3) For useSecureSupabase, null checks: if (secureSupabase === null) ...'
+                  });
+                }
+              }
+            }
+          });
+        }
+      } catch (error) {
+        // Skip files with errors
+      }
+    }
+    
+    // Check if ErrorBoundary is used in main app file
+    // Skip this check if this is the pace-core repository (root src/ is a demo app)
+    if (!hasErrorBoundary && !isPaceCoreRepository) {
+      const mainFile = mainFiles.find(file => {
+        const filePath = path.join(projectRoot, 'src', file);
+        return fs.existsSync(filePath);
+      });
+      
+      if (mainFile) {
+        suggestions.push({
+          type: 'missing-error-boundary',
+          file: `src/${mainFile}`,
+          message: 'No ErrorBoundary found in main app file',
+          recommendation: 'Wrap your app with ErrorBoundary from @jmruthers/pace-core to catch and handle React errors gracefully'
+        });
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = errorHandlingCheck;

package/scripts/audit/core/checks/forms.cjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+/**
+ * Form Validation Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Forms
+ * 
+ * Checks for:
+ * - Missing form validation
+ * - Incorrect useZodForm usage
+ * - Missing error messages
+ * - Form submission without loading states
+ */
+
+const fs = require('fs');
+const { getRelativePath, getLineNumber } = require('../utils.cjs');
+
+const formsCheck = {
+  name: 'forms',
+  description: 'Form validation patterns (useZodForm, error handling)',
+  severity: 'warning',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    if (!files || files.length === 0) {
+      return { issues, warnings, suggestions };
+    }
+    
+    for (const filePath of files) {
+      try {
+        // Only check React component files
+        if (!filePath.match(/\.(tsx|jsx)$/)) {
+          continue;
+        }
+        
+        const content = fs.readFileSync(filePath, 'utf8');
+        const relativePath = getRelativePath(filePath, projectRoot);
+        const normalizedPath = relativePath.replace(/\\/g, '/');
+        
+        // Skip pace-core package files - forms check is for consuming applications, not the library itself
+        // Note: Library components (like Form.tsx, LoginForm.tsx, Select.tsx) ARE the Form components
+        // They don't need to use themselves - they provide the form functionality
+        const isPaceCorePackage = normalizedPath.includes('packages/core/') || normalizedPath.startsWith('packages/core/');
+        if (isPaceCorePackage) {
+          continue; // Skip library files (including examples)
+        }
+        
+        // Skip root-level src directory - in pace-core repository, this is a demo/showcase app
+        const isRootSrc = normalizedPath.startsWith('src/') && !normalizedPath.includes('packages/');
+        if (isRootSrc) {
+          continue; // Skip demo app files
+        }
+        
+        // Skip scripts directory - utility scripts don't need form validation
+        const isScript = normalizedPath.startsWith('scripts/') || normalizedPath.includes('/scripts/');
+        if (isScript) {
+          continue; // Skip script files
+        }
+        
+        // Check for form elements
+        const hasForm = /<form|Form|useZodForm/.test(content);
+        if (!hasForm) {
+          continue;
+        }
+        
+        // Check for useZodForm usage
+        if (content.includes('useZodForm')) {
+          const zodFormPattern = /const\s+[^=]+=\s+useZodForm\s*\(/g;
+          let formMatch;
+          while ((formMatch = zodFormPattern.exec(content)) !== null) {
+            const afterForm = content.substring(formMatch.index, Math.min(content.length, formMatch.index + 500));
+            
+            // Check if schema is provided
+            if (!afterForm.includes('schema:') && !afterForm.includes('schema =')) {
+              warnings.push({
+                type: 'missing-form-schema',
+                file: relativePath,
+                line: getLineNumber(content, formMatch.index),
+                message: 'useZodForm called without schema',
+                recommendation: 'Provide a Zod schema to useZodForm for form validation'
+              });
+            }
+            
+            // Check if form errors are displayed
+            const hasErrorDisplay = /formState\.errors|errors\[|\.error/.test(content);
+            if (!hasErrorDisplay) {
+              suggestions.push({
+                type: 'missing-form-errors',
+                file: relativePath,
+                line: getLineNumber(content, formMatch.index),
+                message: 'Form may not be displaying validation errors',
+                recommendation: 'Display form errors to users using formState.errors or FormField error prop'
+              });
+            }
+          }
+        }
+        
+        // Check for form submission without loading state
+        const onSubmitPattern = /onSubmit\s*=\s*\{[^}]*async/g;
+        let submitMatch;
+        while ((submitMatch = onSubmitPattern.exec(content)) !== null) {
+          const afterSubmit = content.substring(submitMatch.index, Math.min(content.length, submitMatch.index + 1000));
+          
+          // Check if there's a loading state
+          const hasLoadingState = /isLoading|loading|isSubmitting|submitting/.test(afterSubmit);
+          const hasDisabled = /disabled\s*=\s*\{/.test(content);
+          
+          if (!hasLoadingState && !hasDisabled) {
+            suggestions.push({
+              type: 'missing-submit-loading',
+              file: relativePath,
+              line: getLineNumber(content, submitMatch.index),
+              message: 'Form submission without loading state',
+              recommendation: 'Add loading state during form submission to prevent double-submission and provide user feedback'
+            });
+          }
+        }
+        
+        // Check for native form elements that should use pace-core Form
+        const nativeFormPattern = /<form[^>]*>/g;
+        let nativeMatch;
+        while ((nativeMatch = nativeFormPattern.exec(content)) !== null) {
+          const beforeMatch = content.substring(Math.max(0, nativeMatch.index - 100), nativeMatch.index);
+          const usesPaceCoreForm = beforeMatch.includes('from \'@jmruthers/pace-core\'') ||
+                                   content.includes('<Form');
+          
+          if (!usesPaceCoreForm) {
+            suggestions.push({
+              type: 'native-form-element',
+              file: relativePath,
+              line: getLineNumber(content, nativeMatch.index),
+              message: 'Native <form> element detected',
+              recommendation: 'Use Form component from @jmruthers/pace-core for consistent styling and validation'
+            });
+          }
+        }
+        
+        // Check for input elements without validation
+        const inputPattern = /<input[^>]*>/g;
+        let inputMatch;
+        while ((inputMatch = inputPattern.exec(content)) !== null) {
+          const inputTag = inputMatch[0];
+          const hasFormField = content.substring(Math.max(0, inputMatch.index - 200), inputMatch.index).includes('FormField');
+          const hasValidation = inputTag.includes('required') || 
+                               inputTag.includes('pattern') ||
+                               content.substring(Math.max(0, inputMatch.index - 200), inputMatch.index).includes('register');
+          
+          if (!hasFormField && !hasValidation && !inputTag.includes('type="hidden"')) {
+            suggestions.push({
+              type: 'unvalidated-input',
+              file: relativePath,
+              line: getLineNumber(content, inputMatch.index),
+              message: 'Input element without validation',
+              recommendation: 'Use FormField from @jmruthers/pace-core or add validation to form inputs'
+            });
+          }
+        }
+        
+      } catch (error) {
+        // Skip files with errors
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = formsCheck;

package/scripts/audit/core/checks/heuristics.cjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+/**
+ * Heuristic Checks Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Heuristics
+ * 
+ * Code quality heuristics including:
+ * - Large files
+ * - God objects (files with many exports)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const heuristicsCheck = {
+  name: 'heuristics',
+  description: 'Code quality heuristics (large files, god objects)',
+  severity: 'suggestion',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const suggestions = [];
+    
+    if (!files || files.length === 0) {
+      return { issues: [], warnings: [], suggestions: [] };
+    }
+    
+    const maxLines = 1000;
+    
+    // Check for large files
+    for (const filePath of files) {
+      try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const lines = content.split('\n').length;
+        
+        if (lines > maxLines) {
+          const relativePath = path.relative(projectRoot, filePath);
+          suggestions.push({
+            type: 'large-file',
+            file: relativePath,
+            message: `File has ${lines} lines, consider splitting into smaller modules`,
+            recommendation: `Split this file into smaller, focused modules (target: <${maxLines} lines)`
+          });
+        }
+        
+        // Check for god objects (files with many exports)
+        const exportCount = (content.match(/export\s+(const|function|class|interface|type)/g) || []).length;
+        
+        if (exportCount > 10) {
+          const relativePath = path.relative(projectRoot, filePath);
+          suggestions.push({
+            type: 'god-object',
+            file: relativePath,
+            message: `File exports ${exportCount} items, consider splitting into smaller modules`,
+            recommendation: `Split this file into smaller modules, each with a focused responsibility (target: <10 exports per file)`
+          });
+        }
+      } catch (error) {
+        // Skip files we can't read
+      }
+    }
+    
+    return { issues: [], warnings: [], suggestions };
+  }
+};
+
+module.exports = heuristicsCheck;