@jmruthers/pace-core 0.6.1 → 0.6.3

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

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+
+/**
+ * React Hooks Compliance Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Hooks
+ * 
+ * Checks for:
+ * - Hooks called conditionally or after early returns
+ * - Hooks called in loops
+ * - Missing dependencies in useEffect/useMemo/useCallback
+ * - Hooks called in wrong order
+ */
+
+const fs = require('fs');
+const { getRelativePath, getLineNumber } = require('../utils.cjs');
+
+const hooksCheck = {
+  name: 'hooks',
+  description: 'React hooks compliance (conditional calls, missing dependencies, etc.)',
+  severity: 'error',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    if (!files || files.length === 0) {
+      return { issues, warnings, suggestions };
+    }
+    
+    // React hooks that must follow rules
+    // Separate actual React hooks from custom hooks
+    const actualReactHooks = [
+      'useState', 'useEffect', 'useContext', 'useReducer', 'useCallback',
+      'useMemo', 'useRef', 'useImperativeHandle', 'useLayoutEffect',
+      'useDebugValue'
+    ];
+    
+    const customHooks = [
+      'useUnifiedAuth', 'useOrganisations', 'useEvents',
+      'usePermissions', 'useCan', 'useSecureSupabase', 'useToast',
+      'useDebounce', 'useZodForm', 'useFileReference', 'useRBAC'
+    ];
+    
+    // Combined list for pattern matching
+    const hookNames = [...actualReactHooks, ...customHooks];
+    
+    const hookPattern = new RegExp(`\\b(${hookNames.join('|')})\\s*\\(`, 'g');
+    
+    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 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 hooks validation
+        const isScript = normalizedPath.startsWith('scripts/') || normalizedPath.includes('/scripts/');
+        if (isScript) {
+          continue; // Skip script files
+        }
+        
+        // Check if this is a pace-core package file
+        // Skip "hook-after-return" check for pace-core files - these are false positives.
+        // The detection logic has issues with complex nested structures in library code.
+        // Other hook checks (conditional calls, missing dependencies) still apply to pace-core.
+        const isPaceCorePackage = normalizedPath.includes('packages/core/') || normalizedPath.startsWith('packages/core/');
+        
+        // Check for hooks
+        if (!hookPattern.test(content)) {
+          continue; // No hooks in this file
+        }
+        
+        // Find all hook calls
+        const hookCalls = [];
+        let match;
+        const regex = new RegExp(`\\b(${hookNames.join('|')})\\s*\\(`, 'g');
+        while ((match = regex.exec(content)) !== null) {
+          hookCalls.push({
+            name: match[1],
+            index: match.index,
+            line: getLineNumber(content, match.index)
+          });
+        }
+        
+        if (hookCalls.length === 0) {
+          continue;
+        }
+        
+        // Check for hooks called conditionally
+        for (const hookCall of hookCalls) {
+          const beforeHook = content.substring(0, hookCall.index);
+          const linesBefore = beforeHook.split('\n');
+          const currentLine = linesBefore[linesBefore.length - 1];
+          
+          // Check if hook is in a conditional
+          const isInConditional = /if\s*\(|else\s*\{|switch\s*\(|case\s+.*:|for\s*\(|while\s*\(|\.map\s*\(/.test(currentLine);
+          
+          if (isInConditional) {
+            issues.push({
+              type: 'hook-in-conditional',
+              file: relativePath,
+              line: hookCall.line,
+              message: `Hook '${hookCall.name}' is called conditionally or in a loop`,
+              recommendation: 'Hooks must be called at the top level of the component, not conditionally or in loops'
+            });
+          }
+          
+          // Check if there's an early return before this hook at the component level
+          // Only flag returns at the component function level, not inside nested functions
+          const functionStart = beforeHook.lastIndexOf('function') > beforeHook.lastIndexOf('=>') ?
+            beforeHook.lastIndexOf('function') : beforeHook.lastIndexOf('=>');
+          
+          if (functionStart !== -1) {
+            const functionBody = content.substring(functionStart, hookCall.index);
+            
+            // Find all return statements and check if they're at component level (not in nested functions)
+            // Only flag CONDITIONAL early returns (guard clauses), not the final return statement
+            const returnPattern = /\breturn\s+[^;]+;|\breturn\s*;|\breturn\s+\(/g;
+            let returnMatch;
+            let hasComponentLevelReturn = false;
+            
+            while ((returnMatch = returnPattern.exec(functionBody)) !== null) {
+              const returnIndex = returnMatch.index;
+              const beforeReturn = functionBody.substring(Math.max(0, returnIndex - 200), returnIndex);
+              const afterReturn = functionBody.substring(returnIndex, Math.min(functionBody.length, returnIndex + 100));
+              
+              // Check if this is a CONDITIONAL early return (guard clause)
+              // Pattern: if (...) return ...; or if (...) { return ...; }
+              // NOT the final return statement of the component
+              const isConditionalReturn = /\bif\s*\([^)]+\)\s*(return|{[\s\S]*?return)/.test(beforeReturn) ||
+                                         /\belse\s+if\s*\([^)]+\)\s*(return|{[\s\S]*?return)/.test(beforeReturn) ||
+                                         /\belse\s*{\s*return/.test(beforeReturn) ||
+                                         /\?\s*\([^)]*\)\s*=>\s*{?\s*return/.test(beforeReturn); // Ternary operator
+              
+              // If it's not a conditional return, it's likely the final return - skip it
+              if (!isConditionalReturn) {
+                continue;
+              }
+              
+              // Check if return is inside a nested function by looking for patterns
+              const isInHookInitializer = /useState\s*\(\s*\([^)]*\)\s*=>/.test(beforeReturn);
+              const isInEffectCallback = /useEffect\s*\(\s*\([^)]*\)\s*=>/.test(beforeReturn);
+              const isInQueryFn = /queryFn\s*:\s*\([^)]*\)\s*=>|useQuery\s*\(\s*\{[^}]*queryFn/.test(beforeReturn);
+              const isInArrayMethod = /\.(map|filter|find|reduce|forEach|some|every)\s*\(\s*\([^)]*\)\s*=>/.test(beforeReturn);
+              const isInIIFE = /\(\s*\([^)]*\)\s*=>/.test(beforeReturn);
+              const isInFunctionExpr = /\bfunction\s*\([^)]*\)\s*\{/.test(beforeReturn);
+              const isInUseMemo = /useMemo\s*\(\s*\([^)]*\)\s*=>/.test(beforeReturn);
+              const isInUseCallback = /useCallback\s*\(\s*\([^)]*\)\s*=>/.test(beforeReturn);
+              
+              // Check if return is inside a switch case (also nested)
+              const isInSwitchCase = /\bcase\s+[^:]+:\s*[\s\S]*?return/.test(beforeReturn);
+              
+              // If return is NOT in any nested function pattern, it's a component-level conditional return
+              if (!isInHookInitializer && !isInEffectCallback && !isInQueryFn && 
+                  !isInArrayMethod && !isInIIFE && !isInFunctionExpr && 
+                  !isInUseMemo && !isInUseCallback && !isInSwitchCase) {
+                hasComponentLevelReturn = true;
+                break;
+              }
+            }
+            
+            if (hasComponentLevelReturn && !isPaceCorePackage) {
+              // Skip this check for pace-core files - false positives due to complex nested structures
+              issues.push({
+                type: 'hook-after-return',
+                file: relativePath,
+                line: hookCall.line,
+                message: `Hook '${hookCall.name}' is called after an early return`,
+                recommendation: 'All hooks must be called before any conditional returns at the component level. Move hooks to the top of the component, before any component-level conditional returns. Returns inside nested functions (useState initializers, useEffect callbacks, etc.) are fine. If you have guard clauses (if (loading) return <Loading />), move all hooks above these guard clauses.'
+              });
+            }
+          }
+        }
+        
+        // Check for missing dependencies in useEffect, useMemo, useCallback
+        const dependencyHooks = ['useEffect', 'useMemo', 'useCallback', 'useLayoutEffect'];
+        dependencyHooks.forEach(hookName => {
+          // Match hook with dependency array - handle multiline and various formats
+          const hookRegex = new RegExp(`${hookName}\\s*\\(([^)]*)\\)\\s*,\\s*\\[([^\\]]*)\\]`, 'gs');
+          let depMatch;
+          while ((depMatch = hookRegex.exec(content)) !== null) {
+            const hookBody = depMatch[1]; // The function body or callback
+            const deps = depMatch[2].trim();
+            
+            // If dependency array is empty, check if hook only uses stable globals
+            if (deps === '') {
+              // Extract the actual callback body (handle arrow functions and regular functions)
+              let callbackBody = hookBody;
+              
+              // Check if it's an arrow function: () => { ... } or () => ...
+              if (hookBody.includes('=>')) {
+                const arrowMatch = hookBody.match(/=>\s*\{?([^}]*)\}?$/);
+                if (arrowMatch) {
+                  callbackBody = arrowMatch[1];
+                }
+              }
+              
+              // Check if callback only uses stable global APIs or imported module-level constants
+              // Stable globals that don't need dependencies:
+              const stableGlobals = [
+                /window\.(location|document|localStorage|sessionStorage|navigator)/,
+                /document\.(documentElement|body|getElementById|querySelector)/,
+                /localStorage\.(getItem|setItem|removeItem|clear)/,
+                /sessionStorage\.(getItem|setItem|removeItem|clear)/,
+                /console\.(log|error|warn|info|debug)/,
+                /Math\./,
+                /Date\./,
+                /JSON\./,
+                /Object\./,
+                /Array\./,
+                /String\./,
+                /Number\./,
+                /Boolean\./,
+                /RegExp\./,
+                /Error\./,
+                /Promise\./,
+                /Symbol\./,
+                /Reflect\./,
+                /Proxy\./
+              ];
+              
+              // Check for imported module-level constants (classes, functions, constants)
+              // Pattern: ImportedClass.method() or importedFunction() or importedConstant
+              const importedModulePattern = /[A-Z]\w+\.\w+\(|^[A-Z]\w+\(|\b[A-Z][A-Z_]+/;
+              
+              // Check if callback body only contains stable globals or simple operations
+              const hasOnlyStableGlobals = stableGlobals.some(pattern => pattern.test(callbackBody));
+              const hasImportedModule = importedModulePattern.test(callbackBody);
+              
+              // Check if callback uses reactive values (props, state, context) that would need deps
+              const hasReactiveValues = /\b(props|state|context|use[A-Z]\w+\(\))/.test(callbackBody);
+              
+              // Check for variable references that might be reactive
+              // Simple heuristic: if callback references variables that aren't stable globals
+              const variablePattern = /\b[a-z][a-zA-Z0-9_]*\b/g;
+              const variables = callbackBody.match(variablePattern) || [];
+              const hasNonGlobalVariables = variables.some(v => {
+                // Skip common stable globals and built-ins
+                const stableVars = ['window', 'document', 'localStorage', 'sessionStorage', 'console', 
+                                   'Math', 'Date', 'JSON', 'Object', 'Array', 'String', 'Number', 
+                                   'Boolean', 'RegExp', 'Error', 'Promise', 'Symbol', 'Reflect', 'Proxy',
+                                   'true', 'false', 'null', 'undefined', 'this', 'return', 'if', 'else',
+                                   'const', 'let', 'var', 'function', 'async', 'await', 'for', 'while',
+                                   'switch', 'case', 'default', 'break', 'continue', 'try', 'catch', 'finally'];
+                return !stableVars.includes(v) && !v.match(/^[A-Z]/); // Lowercase vars that aren't stable
+              });
+              
+              // Only warn if callback uses reactive values or non-global variables
+              if (hasReactiveValues || (hasNonGlobalVariables && !hasOnlyStableGlobals && !hasImportedModule)) {
+                warnings.push({
+                  type: 'missing-dependencies',
+                  file: relativePath,
+                  line: getLineNumber(content, depMatch.index),
+                  message: `${hookName} has empty dependency array but may need dependencies`,
+                  recommendation: 'Review the hook body and add all dependencies to the dependency array. If the callback only uses stable global APIs (window, document, localStorage, etc.) or imported module-level constants, an empty dependency array is correct.'
+                });
+              }
+            }
+          }
+        });
+        
+        // Check hook order (hooks should be called in consistent order)
+        // This is a simplified check - full implementation would track hook order across renders
+        
+        // SKIP hook grouping suggestions for pace-core library files
+        // Library components often have complex hook usage organized by feature/concern,
+        // and strict grouping is less critical than in consuming applications.
+        // The grouping suggestions are primarily for consuming apps, not library code.
+        if (isPaceCorePackage) {
+          continue; // Skip grouping suggestions for pace-core library files
+        }
+        
+        // Filter to only actual React hooks (not custom hooks) for grouping suggestions
+        // Files with only custom hooks (like useToast()) don't need grouping suggestions
+        const actualReactHookCalls = hookCalls.filter(h => actualReactHooks.includes(h.name));
+        
+        // Skip files that only have custom hooks (no actual React hooks)
+        // Custom hooks are typically called once and don't need grouping
+        // This also filters out files like Toast.tsx that only have forwardRef components
+        // (forwardRef components don't use React hooks, so actualReactHookCalls will be empty)
+        if (actualReactHookCalls.length === 0) {
+          continue; // No actual React hooks, skip grouping suggestion
+        }
+        
+        // Check if hooks are already grouped (look for grouping comments)
+        // Accept more flexible patterns:
+        // - Specific keywords: // ============================================================================ // REFS / STATE HOOKS / etc.
+        // - Section dividers: // ============================================================================ (any text)
+        // - Comment blocks near hooks: // HOOKS or // State management or similar
+        const hasGroupingComments = 
+          /\/\/\s*=+\s*(REFS|STATE HOOKS|CUSTOM HOOKS|MEMOIZATION HOOKS|EFFECT HOOKS|HOOKS|STATE|EFFECTS|MEMOIZATION|CALLBACKS)/i.test(content) ||
+          /\/\/\s*=+\s*[A-Z].*HOOK/i.test(content) ||
+          /\/\/\s*=+\s*[A-Z].*STATE/i.test(content) ||
+          /\/\/\s*=+\s*[A-Z].*EFFECT/i.test(content);
+        
+        // Only suggest grouping if:
+        // 1. File has actual React hooks (not just custom hooks)
+        // 2. Hooks are called multiple times (duplicate hook names)
+        // 3. Hooks are not already grouped (no grouping comments found)
+        const hookOrder = actualReactHookCalls.map(h => h.name);
+        const uniqueHooks = [...new Set(hookOrder)];
+        
+        if (uniqueHooks.length !== hookOrder.length && !hasGroupingComments) {
+          // Hooks are called multiple times and not grouped
+          suggestions.push({
+            type: 'hook-order',
+            file: relativePath,
+            message: 'Consider grouping related hooks together for better readability',
+            recommendation: 'Group hooks by purpose (state hooks, effect hooks, custom hooks)'
+          });
+        }
+      } catch (error) {
+        // Skip files with errors
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = hooksCheck;

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

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+
+/**
+ * Import Patterns Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Imports
+ * 
+ * Checks for:
+ * - Unused imports from pace-core
+ * - Missing default imports
+ * - Circular dependencies
+ * - Wrong import paths
+ * - Barrel import anti-patterns
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { findSourceFiles, getRelativePath } = require('../utils.cjs');
+
+const importsCheck = {
+  name: 'imports',
+  description: 'Import pattern analysis (unused imports, circular dependencies, wrong paths)',
+  severity: 'warning',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    if (!files || files.length === 0) {
+      return { issues, warnings, suggestions };
+    }
+    
+    // Track imports and usage
+    const importMap = new Map(); // file -> { imports: [], exports: [] }
+    const usageMap = new Map(); // file -> Set of used identifiers
+    
+    // First pass: collect imports and exports
+    for (const filePath of files) {
+      try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const relativePath = getRelativePath(filePath, projectRoot);
+        
+        const imports = [];
+        const exports = [];
+        const used = new Set();
+        
+        // Find all imports
+        const importPattern = /import\s+(?:(?:\*\s+as\s+(\w+))|(?:{([^}]+)})|(\w+))\s+from\s+['"]([^'"]+)['"]/g;
+        let match;
+        while ((match = importPattern.exec(content)) !== null) {
+          const namespace = match[1];
+          const namedImports = match[2];
+          const defaultImport = match[3];
+          const modulePath = match[4];
+          
+          imports.push({
+            namespace,
+            namedImports: namedImports ? namedImports.split(',').map(s => s.trim().replace(/\s+as\s+\w+/, '')) : [],
+            defaultImport,
+            modulePath,
+            line: content.substring(0, match.index).split('\n').length
+          });
+        }
+        
+        // Find all exports
+        const exportPattern = /export\s+(?:(?:default\s+)?(?:function|const|class|interface|type)\s+(\w+)|(?:{([^}]+)})|(\w+))/g;
+        while ((match = exportPattern.exec(content)) !== null) {
+          const namedExport = match[1] || match[3];
+          const namedExports = match[2];
+          
+          if (namedExport) {
+            exports.push(namedExport);
+          }
+          if (namedExports) {
+            exports.push(...namedExports.split(',').map(s => s.trim()));
+          }
+        }
+        
+        // Find usage of imported identifiers (simplified heuristic)
+        imports.forEach(imp => {
+          if (imp.defaultImport) {
+            // Check if default import is used
+            const usagePattern = new RegExp(`\\b${imp.defaultImport}\\b`, 'g');
+            if (usagePattern.test(content)) {
+              used.add(imp.defaultImport);
+            }
+          }
+          if (imp.namespace) {
+            const usagePattern = new RegExp(`\\b${imp.namespace}\\.`, 'g');
+            if (usagePattern.test(content)) {
+              used.add(imp.namespace);
+            }
+          }
+          imp.namedImports.forEach(name => {
+            const cleanName = name.trim();
+            const usagePattern = new RegExp(`\\b${cleanName}\\b`, 'g');
+            // Count occurrences - if more than 1, it's likely used (1 is the import itself)
+            const matches = content.match(usagePattern);
+            if (matches && matches.length > 1) {
+              used.add(cleanName);
+            }
+          });
+        });
+        
+        importMap.set(relativePath, { imports, exports, content });
+        usageMap.set(relativePath, used);
+      } catch (error) {
+        // Skip files with errors
+      }
+    }
+    
+    // Second pass: analyze imports
+    for (const [filePath, { imports, content }] of importMap.entries()) {
+      const relativePath = filePath;
+      const normalizedPath = relativePath.replace(/\\/g, '/');
+      
+      // Skip pace-core package files - imports check is for consuming applications, not the library itself
+      // The library must use internal import paths and may have unused imports in examples/config files
+      const isPaceCorePackage = normalizedPath.includes('packages/core/') || normalizedPath.startsWith('packages/core/');
+      if (isPaceCorePackage) {
+        continue; // Skip library files
+      }
+      
+      // 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 import validation
+      const isScript = normalizedPath.startsWith('scripts/') || normalizedPath.includes('/scripts/');
+      if (isScript) {
+        continue; // Skip script files
+      }
+      
+      const used = usageMap.get(filePath) || new Set();
+      
+      imports.forEach(imp => {
+        // Check for unused imports from pace-core
+        if (imp.modulePath === '@jmruthers/pace-core' || imp.modulePath.startsWith('@jmruthers/pace-core/')) {
+          const unused = [];
+          
+          if (imp.defaultImport && !used.has(imp.defaultImport)) {
+            unused.push(imp.defaultImport);
+          }
+          
+          imp.namedImports.forEach(name => {
+            if (!used.has(name.trim())) {
+              unused.push(name.trim());
+            }
+          });
+          
+          if (imp.namespace && !used.has(imp.namespace)) {
+            unused.push(`${imp.namespace} (namespace)`);
+          }
+          
+          if (unused.length > 0) {
+            warnings.push({
+              type: 'unused-import',
+              file: relativePath,
+              line: imp.line,
+              message: `Unused imports from pace-core: ${unused.join(', ')}`,
+              recommendation: `Remove unused imports to reduce bundle size`
+            });
+          }
+        }
+        
+        // Check for wrong import paths
+        if (imp.modulePath.startsWith('@jmruthers/pace-core/')) {
+          const validPaths = [
+            '@jmruthers/pace-core',
+            '@jmruthers/pace-core/components',
+            '@jmruthers/pace-core/hooks',
+            '@jmruthers/pace-core/utils',
+            '@jmruthers/pace-core/providers',
+            '@jmruthers/pace-core/rbac',
+            '@jmruthers/pace-core/types'
+          ];
+          
+          if (!validPaths.includes(imp.modulePath)) {
+            warnings.push({
+              type: 'wrong-import-path',
+              file: relativePath,
+              line: imp.line,
+              message: `Invalid import path: ${imp.modulePath}`,
+              recommendation: `Use one of the valid paths: ${validPaths.join(', ')}`
+            });
+          }
+        }
+        
+        // Check for barrel import anti-patterns (importing entire modules)
+        if (imp.namespace && (imp.modulePath === '@jmruthers/pace-core' || imp.modulePath.startsWith('@jmruthers/pace-core/'))) {
+          warnings.push({
+            type: 'barrel-import',
+            file: relativePath,
+            line: imp.line,
+            message: `Namespace import from pace-core: import * as ${imp.namespace}`,
+            recommendation: `Import specific exports instead to enable tree-shaking: import { Component1, Component2 } from '@jmruthers/pace-core'`
+          });
+        }
+      });
+    }
+    
+    // Check for circular dependencies (simplified - check if file A imports B and B imports A)
+    const filePaths = Array.from(importMap.keys());
+    for (let i = 0; i < filePaths.length; i++) {
+      for (let j = i + 1; j < filePaths.length; j++) {
+        const fileA = filePaths[i];
+        const fileB = filePaths[j];
+        const importsA = importMap.get(fileA)?.imports || [];
+        const importsB = importMap.get(fileB)?.imports || [];
+        
+        // Check if A imports B
+        const aImportsB = importsA.some(imp => {
+          const importPath = imp.modulePath;
+          return importPath.startsWith('./') || importPath.startsWith('../') ?
+            path.resolve(path.dirname(fileA), importPath) === fileB : false;
+        });
+        
+        // Check if B imports A
+        const bImportsA = importsB.some(imp => {
+          const importPath = imp.modulePath;
+          return importPath.startsWith('./') || importPath.startsWith('../') ?
+            path.resolve(path.dirname(fileB), importPath) === fileA : false;
+        });
+        
+        if (aImportsB && bImportsA) {
+          issues.push({
+            type: 'circular-dependency',
+            file: fileA,
+            message: `Circular dependency detected between ${fileA} and ${fileB}`,
+            recommendation: `Refactor to break the circular dependency by extracting shared code to a third module`
+          });
+        }
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = importsCheck;