@jmruthers/pace-core 0.6.5 → 0.6.7

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

@@ -1,334 +0,0 @@
-#!/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

@@ -1,244 +0,0 @@
-#!/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;