@jmruthers/pace-core 0.5.193 → 0.6.2

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

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+/**
+ * Documentation Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Documentation
+ * 
+ * Checks for:
+ * - Missing JSDoc on exported functions/components
+ * - Missing README updates
+ * - Outdated comments
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getRelativePath, getLineNumber } = require('../utils.cjs');
+
+const documentationCheck = {
+  name: 'documentation',
+  description: 'Documentation coverage (JSDoc, README)',
+  severity: 'suggestion',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    if (!files || files.length === 0) {
+      return { issues, warnings, suggestions };
+    }
+    
+    // Detect if this is the pace-core repository itself
+    const packagesCorePath = path.join(projectRoot, 'packages', 'core');
+    const isPaceCoreRepository = fs.existsSync(packagesCorePath);
+    
+    // Check for README
+    const readmePath = path.join(projectRoot, 'README.md');
+    if (!fs.existsSync(readmePath)) {
+      suggestions.push({
+        type: 'missing-readme',
+        file: 'README.md',
+        message: 'README.md file is missing',
+        recommendation: 'Create a README.md with project description, setup instructions, and usage examples'
+      });
+    }
+    
+    // Check for JSDoc on exported functions/components
+    for (const filePath of files) {
+      try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const relativePath = getRelativePath(filePath, projectRoot);
+        const normalizedPath = relativePath.replace(/\\/g, '/');
+        
+        // Skip test files
+        if (normalizedPath.includes('.test.') || normalizedPath.includes('.spec.')) {
+          continue;
+        }
+        
+        // Skip test directories
+        if (normalizedPath.includes('/__tests__/') || normalizedPath.includes('__tests__/')) {
+          continue;
+        }
+        
+        // Skip scripts directory (build/test scripts, not public API)
+        if (normalizedPath.includes('/scripts/') || normalizedPath.startsWith('scripts/')) {
+          continue;
+        }
+        
+        // Skip generated files
+        if (normalizedPath.includes('.generated.') || normalizedPath.includes('.gen.')) {
+          continue;
+        }
+        
+        // When running in pace-core repository, skip non-public API files
+        if (isPaceCoreRepository) {
+          // Skip examples - these are demonstration code, not public API
+          if (normalizedPath.includes('packages/core/examples/') || 
+              normalizedPath.startsWith('packages/core/examples/')) {
+            continue;
+          }
+          
+          // Skip root-level src directory - in pace-core repository, this is a demo/showcase app
+          if (normalizedPath.startsWith('src/') && !normalizedPath.startsWith('packages/core/src/')) {
+            continue;
+          }
+          
+          // Skip test setup files
+          if (normalizedPath.includes('test-setup.') || normalizedPath.includes('test-setup/')) {
+            continue;
+          }
+          
+          // Skip database.generated.ts - this is a generated file
+          if (normalizedPath.includes('database.generated.ts')) {
+            continue;
+          }
+        }
+        
+        // Find exported functions/components
+        const exportPattern = /export\s+(?:default\s+)?(?:async\s+)?(function|const|class|interface|type)\s+(\w+)/g;
+        let match;
+        while ((match = exportPattern.exec(content)) !== null) {
+          const exportName = match[2];
+          const exportType = match[1];
+          const exportIndex = match.index;
+          
+          // Check if there's JSDoc before this export
+          const beforeExport = content.substring(Math.max(0, exportIndex - 500), exportIndex);
+          const hasJSDoc = /\/\*\*[\s\S]*?\*\//.test(beforeExport) || 
+                          /\/\/\/\s*</.test(beforeExport);
+          
+          // Only check public exports (not internal utilities)
+          const isPublic = match[0].includes('export') && 
+                          !normalizedPath.includes('/internal/') &&
+                          !normalizedPath.includes('/private/');
+          
+          if (!isPublic || hasJSDoc) {
+            continue;
+          }
+          
+          // Get the content after the export to analyze what it is
+          const afterExport = content.substring(exportIndex, Math.min(content.length, exportIndex + 200));
+          
+          // Skip simple type aliases (e.g., `type UUID = string`, `type X = 'a' | 'b'`)
+          if (exportType === 'type') {
+            // Check if it's a simple type alias (not a complex type)
+            const simpleTypePattern = /type\s+\w+\s*=\s*(?:string|number|boolean|'[^']+'|"[^"]+"|`[^`]+`|[\w.]+(?:\s*\|\s*[\w.]+)*)\s*[;=]/;
+            if (simpleTypePattern.test(afterExport)) {
+              continue; // Skip simple type aliases - they're self-documenting
+            }
+          }
+          
+          // Skip Props interfaces that have inline JSDoc on properties
+          if (exportType === 'interface' && exportName.endsWith('Props')) {
+            // Check if the interface has inline JSDoc comments on its properties
+            const interfaceContent = content.substring(exportIndex, Math.min(content.length, exportIndex + 2000));
+            const hasInlineJSDoc = /\/\*\*[\s\S]*?\*\//.test(interfaceContent) || 
+                                  /\/\/\/\s*</.test(interfaceContent);
+            // If it has inline JSDoc on properties, the interface itself doesn't need a block comment
+            if (hasInlineJSDoc) {
+              continue;
+            }
+          }
+          
+          // Skip simple Props type aliases that just extend React types
+          if (exportType === 'type' && exportName.endsWith('Props')) {
+            // Check if it's a simple type alias extending React types
+            const simplePropsPattern = /type\s+\w+Props\s*=\s*React\.\w+Attributes/;
+            if (simplePropsPattern.test(afterExport)) {
+              continue; // Skip simple Props type aliases - they're self-documenting
+            }
+          }
+          
+          // Skip simple constants that are self-explanatory
+          if (exportType === 'const') {
+            // Check if it's a simple constant assignment (not a function/component)
+            const simpleConstPattern = /const\s+\w+\s*=\s*(?:['"`][^'"`]+['"`]|\d+|true|false|null|undefined|\[\]|\{\})\s*[;=]/;
+            if (simpleConstPattern.test(afterExport)) {
+              // Skip very simple constants - they're self-documenting
+              continue;
+            }
+          }
+          
+          // All other exports should have JSDoc
+          suggestions.push({
+            type: 'missing-jsdoc',
+            file: relativePath,
+            line: getLineNumber(content, exportIndex),
+            message: `Exported ${exportType} '${exportName}' missing JSDoc documentation`,
+            recommendation: 'Add JSDoc comments to document the function/component purpose, parameters, and return value'
+          });
+        }
+        
+        // Check for TODO/FIXME comments that might be outdated
+        const todoPattern = /(?:TODO|FIXME|XXX|HACK|NOTE):\s*(.+)/gi;
+        let todoMatch;
+        const todos = [];
+        while ((todoMatch = todoPattern.exec(content)) !== null) {
+          todos.push({
+            text: todoMatch[1],
+            line: getLineNumber(content, todoMatch.index)
+          });
+        }
+        
+        if (todos.length > 5) {
+          suggestions.push({
+            type: 'many-todos',
+            file: relativePath,
+            message: `File has ${todos.length} TODO/FIXME comments`,
+            recommendation: 'Review and address TODO comments, or remove outdated ones'
+          });
+        }
+        
+      } catch (error) {
+        // Skip files with errors
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = documentationCheck;

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

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+/**
+ * Environment Variables Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Environment
+ * 
+ * Checks for:
+ * - Missing required environment variables
+ * - Hardcoded secrets/API keys
+ * - Incorrect environment variable usage
+ * - Missing .env.example file
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const environmentCheck = {
+  name: 'environment',
+  description: 'Environment variable usage (secrets, required vars, .env.example)',
+  severity: 'warning',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    // Check for .env.example
+    const envExamplePath = path.join(projectRoot, '.env.example');
+    if (!fs.existsSync(envExamplePath)) {
+      suggestions.push({
+        type: 'missing-env-example',
+        file: '.env.example',
+        message: '.env.example file is missing',
+        recommendation: 'Create .env.example with all required environment variables (without actual values)'
+      });
+    }
+    
+    // Required environment variables for pace-core apps
+    const requiredEnvVars = [
+      'VITE_SUPABASE_URL',
+      'VITE_SUPABASE_PUBLISHABLE_KEY'
+    ];
+    
+    // Check .env.example for required vars
+    if (fs.existsSync(envExamplePath)) {
+      try {
+        const envExampleContent = fs.readFileSync(envExamplePath, 'utf8');
+        requiredEnvVars.forEach(envVar => {
+          if (!envExampleContent.includes(envVar)) {
+            warnings.push({
+              type: 'missing-env-var',
+              file: '.env.example',
+              message: `Required environment variable '${envVar}' missing from .env.example`,
+              recommendation: `Add ${envVar} to .env.example file`
+            });
+          }
+        });
+      } catch (error) {
+        // Skip if can't read
+      }
+    }
+    
+    // Check source files for hardcoded secrets
+    if (files && files.length > 0) {
+      const secretPatterns = [
+        /(?:api[_-]?key|secret|password|token)\s*[:=]\s*['"]([^'"]{10,})['"]/gi,
+        /(?:supabase[_-]?url|supabase[_-]?key)\s*[:=]\s*['"]https?:\/\/[^'"]+['"]/gi
+      ];
+      
+      for (const filePath of files) {
+        try {
+          // Skip test files and config files (they may have example values)
+          const relativePath = getRelativePath(filePath, projectRoot);
+          if (relativePath.includes('.test.') || 
+              relativePath.includes('.spec.') ||
+              relativePath.includes('.example.') ||
+              relativePath.includes('config')) {
+            continue;
+          }
+          
+          const content = fs.readFileSync(filePath, 'utf8');
+          
+          secretPatterns.forEach(pattern => {
+            let match;
+            while ((match = pattern.exec(content)) !== null) {
+              // Check if it's in a comment
+              const beforeMatch = content.substring(Math.max(0, match.index - 100), match.index);
+              const isInComment = beforeMatch.includes('//') || beforeMatch.includes('/*');
+              
+              if (!isInComment) {
+                issues.push({
+                  type: 'hardcoded-secret',
+                  file: relativePath,
+                  line: content.substring(0, match.index).split('\n').length,
+                  message: 'Potential hardcoded secret or API key detected',
+                  recommendation: 'Move secrets to environment variables and use import.meta.env or process.env'
+                });
+              }
+            }
+          });
+          
+          // Check for direct Supabase URL/key usage (should use env vars)
+          if (content.includes('supabase') && 
+              (content.includes('https://') || content.includes('eyJ'))) {
+            const hasEnvVar = /import\.meta\.env|process\.env/.test(content);
+            if (!hasEnvVar) {
+              warnings.push({
+                type: 'hardcoded-config',
+                file: relativePath,
+                message: 'Supabase configuration may be hardcoded',
+                recommendation: 'Use environment variables: import.meta.env.VITE_SUPABASE_URL'
+              });
+            }
+          }
+          
+        } catch (error) {
+          // Skip files with errors
+        }
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = environmentCheck;

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

@@ -0,0 +1,299 @@
+#!/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
+    let hasErrorBoundary = false;
+    const mainFiles = ['main.tsx', 'main.ts', 'App.tsx', 'App.ts', 'index.tsx', 'index.ts'];
+    
+    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 ErrorBoundary
+        if (content.includes('ErrorBoundary') || content.includes('error-boundary')) {
+          hasErrorBoundary = true;
+        }
+        
+        // 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;