@jmruthers/pace-core 0.5.193 → 0.6.2

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;

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;