@jmruthers/pace-core 0.5.193 → 0.6.2

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;

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

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+
+/**
+ * Performance Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Performance
+ * 
+ * Checks for:
+ * - Missing React.memo on expensive components
+ * - Missing useMemo/useCallback for expensive computations
+ * - Unnecessary re-renders
+ * - Large inline objects/functions in JSX props
+ * - Missing key props in lists
+ */
+
+const fs = require('fs');
+const { getRelativePath, getLineNumber } = require('../utils.cjs');
+
+const performanceCheck = {
+  name: 'performance',
+  description: 'Performance anti-patterns (missing memoization, unnecessary re-renders)',
+  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 root-level src directory - in pace-core repository, this is a demo/showcase app
+        // Note: We DO check packages/core/ files because performance issues (like missing key props) 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 performance validation
+        const isScript = normalizedPath.startsWith('scripts/') || normalizedPath.includes('/scripts/');
+        if (isScript) {
+          continue; // Skip script files
+        }
+        
+        // Skip examples directory - these are demo/example files, not production code
+        // Examples are meant to show usage patterns, not be optimized for performance
+        const isExample = normalizedPath.includes('/examples/') || normalizedPath.startsWith('examples/');
+        if (isExample) {
+          continue; // Skip example files
+        }
+        
+        // Skip test files - test code doesn't need performance optimization
+        const isTestFile = normalizedPath.includes('.test.') || 
+                          normalizedPath.includes('.spec.') || 
+                          normalizedPath.includes('test-setup') ||
+                          normalizedPath.includes('__tests__');
+        if (isTestFile) {
+          continue; // Skip test files
+        }
+        
+        // For library code (packages/core/src), be more lenient with performance suggestions
+        // Library components often use inline functions which are acceptable patterns
+        const isLibraryCode = normalizedPath.includes('packages/core/src/');
+        
+        // Check for components that could benefit from React.memo
+        // Note: For library components, React.memo should be used judiciously
+        // We only suggest it for components that are likely to render frequently
+        const componentPattern = /export\s+(default\s+)?(function|const)\s+(\w+)\s*[=\(]/g;
+        let match;
+        while ((match = componentPattern.exec(content)) !== null) {
+          const componentName = match[3];
+          const isMemoized = content.includes(`React.memo(${componentName})`) || 
+                           content.includes(`memo(${componentName})`) ||
+                           content.includes(`export default memo(${componentName})`);
+          
+          // Check if component receives props and is not memoized
+          if (match[0].includes('props') || match[0].includes('{') || content.includes(`${componentName}({`)) {
+            // Check if component has significant JSX (heuristic: more than 5 lines of JSX)
+            const componentStart = match.index;
+            const afterMatch = content.substring(componentStart);
+            const jsxLines = (afterMatch.match(/<[A-Z]/g) || []).length;
+            
+            // Skip if component uses forwardRef (memoization handled differently)
+            // Skip if component is a hook (starts with 'use')
+            // Skip if component is very simple (less than 5 JSX elements)
+            // Skip if component is already memoized
+            if (jsxLines > 5 && !isMemoized && !content.includes('forwardRef') && !componentName.startsWith('use')) {
+              // For library components, be more conservative - only suggest for components
+              // that are likely to be in lists or render frequently
+              // Skip if it's a page-level component (like *Page, *Layout, *Route)
+              const isPageComponent = /Page|Layout|Route|Modal|Dialog/.test(componentName);
+              
+            // Only suggest memo for components that are likely to render frequently
+            // (not page-level components, which typically render once per route)
+            // For library code, skip React.memo suggestions entirely - memoization decisions
+            // should be made by the consuming application based on their specific use case
+            if (!isPageComponent && !isLibraryCode) {
+              suggestions.push({
+                type: 'missing-memo',
+                file: relativePath,
+                line: getLineNumber(content, match.index),
+                message: `Component '${componentName}' receives props but is not memoized`,
+                recommendation: `Consider wrapping with React.memo if the component renders frequently: export default React.memo(${componentName})`
+              });
+            }
+            // For library code, skip React.memo suggestions - library components are often
+            // controlled by parent components, and memoization should be decided by consumers
+            }
+          }
+        }
+        
+        // Check for large inline objects/functions in JSX props
+        // But exclude JSX children (which is standard React pattern)
+        const jsxPropPattern = /<[A-Z]\w+\s+[^>]*\{[^}]{100,}[^>]*>/g;
+        let jsxMatch;
+        while ((jsxMatch = jsxPropPattern.exec(content)) !== null) {
+          const matchText = jsxMatch[0];
+          
+          // Check if this is JSX children (element prop) or guard component props
+          // Patterns to exclude (these are valid React patterns):
+          // 1. <Route element={<Component />} /> - React Router pattern
+          // 2. <GuardComponent fallback={<Component />} /> - Guard component pattern
+          // 3. <Component>{children}</Component> - JSX children (but this won't match our pattern)
+          // 4. Any prop that contains JSX elements (starts with <)
+          
+          const isRouteElement = /element\s*=\s*\{/.test(matchText);
+          const isGuardProp = /(fallback|loading|error|children)\s*=\s*\{/.test(matchText);
+          const hasJSXElement = /<[A-Z]\w+/.test(matchText);
+          
+          // Also check if it's a className utility call (like cn()) - not a performance issue
+          const isUtilityCall = /cn\s*\(|clsx\s*\(|classnames\s*\(/.test(matchText);
+          
+          // Only flag if it's an actual inline object/function, not JSX children
+          if (!isRouteElement && !isGuardProp && !hasJSXElement && !isUtilityCall) {
+            warnings.push({
+              type: 'inline-object-in-jsx',
+              file: relativePath,
+              line: getLineNumber(content, jsxMatch.index),
+              message: 'Large inline object or function in JSX props detected',
+              recommendation: 'Extract inline objects/functions to variables or useMemo/useCallback to prevent unnecessary re-renders. JSX children in props (like React Router element prop or guard component fallback prop) are standard React patterns and not performance issues.'
+            });
+          }
+        }
+        
+        // Check for missing key props in lists
+        // Only flag if JSX is returned, not data arrays
+        const mapPattern = /\.map\s*\(\s*\([^)]+\)\s*=>/g;
+        while ((match = mapPattern.exec(content)) !== null) {
+          const afterMap = content.substring(match.index, match.index + 500);
+          // Check if JSX is returned without key
+          // Also check if it's actually returning JSX (not just data objects)
+          const returnsJSX = afterMap.includes('return') && afterMap.includes('<');
+          
+          // Check for key in various formats: key=, key:, or inside React.cloneElement
+          const hasKey = afterMap.includes('key=') || 
+                        /key\s*:/.test(afterMap) || 
+                        /React\.cloneElement\s*\([^,]+,\s*\{[^}]*key\s*:/.test(afterMap);
+          
+          // Check if it's a data transformation (returns object/array/primitive, not JSX)
+          // Pattern 1: Returns a simple value like .map(([key, _]) => key)
+          const returnsSimpleValue = /=>\s*[a-zA-Z_$][a-zA-Z0-9_$]*\s*;/.test(afterMap) && !afterMap.includes('<');
+          // Pattern 2: Returns a data object without JSX
+          const returnsDataObject = /return\s*\{[^<]*\}/.test(afterMap) && !afterMap.match(/return\s*\{[^<]*<[A-Z]/);
+          // Pattern 3: Returns array element access like .map((subRow) => subRow.original)
+          const returnsDataProperty = /=>\s*[a-zA-Z_$][a-zA-Z0-9_$]*\.[a-zA-Z_$][a-zA-Z0-9_$]*\s*[;}]/.test(afterMap) && !afterMap.includes('<');
+          
+          // Skip pace-core files for this check - library code has complex patterns that are hard to detect accurately
+          const isPaceCorePackage = normalizedPath.includes('packages/core/') || normalizedPath.startsWith('packages/core/');
+          
+          if (returnsJSX && !hasKey && !returnsDataObject && !returnsSimpleValue && !returnsDataProperty && !isPaceCorePackage) {
+            warnings.push({
+              type: 'missing-key',
+              file: relativePath,
+              line: getLineNumber(content, match.index),
+              message: 'Array map returns JSX without key prop',
+              recommendation: 'Add a unique key prop to list items: {items.map(item => <Item key={item.id} ... />)}. Data array transformations (not JSX) do not need keys.'
+            });
+          }
+        }
+        
+        // Check for expensive computations that could use useMemo
+        const expensivePatterns = [
+          /\.filter\([^)]*\)\.map\(/g, // filter().map() chains
+          /\.sort\([^)]*\)\.map\(/g,   // sort().map() chains
+          /\.reduce\([^)]*\)/g          // reduce operations
+        ];
+        
+        expensivePatterns.forEach(pattern => {
+          let expMatch;
+          while ((expMatch = pattern.exec(content)) !== null) {
+            // Check a larger context to see if it's already in useMemo or useCallback
+            const beforeMatch = content.substring(Math.max(0, expMatch.index - 500), expMatch.index);
+            const afterMatch = content.substring(expMatch.index, Math.min(content.length, expMatch.index + 200));
+            
+            // Check if it's already in useMemo or useCallback
+            if (beforeMatch.includes('useMemo') || beforeMatch.includes('useCallback')) {
+              continue;
+            }
+            
+            // Check if it's inside a function definition that's static (like aggregateFn, cell renderer, etc.)
+            // These are function definitions that are called by the library, not recalculated on every render
+            const isStaticFunctionDefinition = /(aggregateFn|cell|header|footer|render|format|transform)\s*[:=]\s*\(/.test(beforeMatch);
+            if (isStaticFunctionDefinition) {
+              continue; // Skip static function definitions
+            }
+            
+            // Check if it's inside a const/let declaration that's likely already memoized
+            // Pattern: const x = useMemo(() => ... or const x = useCallback(() => ...
+            const isInMemoizedConst = /const\s+\w+\s*=\s*(useMemo|useCallback)\s*\(/.test(beforeMatch);
+            if (isInMemoizedConst) {
+              continue;
+            }
+            
+            // Check if it's part of a column definition (static, not recalculated)
+            const isColumnDefinition = /(accessorKey|header|cell|aggregateFn|aggregateCell)\s*:/.test(beforeMatch);
+            if (isColumnDefinition) {
+              continue; // Skip column definitions - these are static
+            }
+            
+            suggestions.push({
+              type: 'expensive-computation',
+              file: relativePath,
+              line: getLineNumber(content, expMatch.index),
+              message: 'Expensive computation detected that could benefit from useMemo',
+              recommendation: 'Wrap expensive computations in useMemo to prevent recalculation on every render'
+            });
+          }
+        });
+        
+        // Check for functions passed as props that could use useCallback
+        // Only flag complex inline functions, not simple event handlers
+        // For library code, be very lenient - inline functions are often acceptable patterns
+        if (!isLibraryCode) {
+          // Only check for consuming applications, not library code
+          const functionPropPattern = /(onClick|onChange|onSubmit|onFocus|onBlur|onMouseEnter|onMouseLeave|onValueChange)\s*=\s*\{[^}]*=>/g;
+          let funcMatch;
+          while ((funcMatch = functionPropPattern.exec(content)) !== null) {
+            const beforeMatch = content.substring(Math.max(0, funcMatch.index - 150), funcMatch.index);
+            const afterMatch = content.substring(funcMatch.index, Math.min(content.length, funcMatch.index + 300));
+            
+            // Skip if already using useCallback or defined as const
+            if (beforeMatch.includes('useCallback') || beforeMatch.includes('const ')) {
+              continue;
+            }
+            
+            // Extract the function body to check complexity
+            // Handle both arrow functions with and without braces
+            let funcBody = '';
+            const arrowMatch = afterMatch.match(/=>\s*(\{?)([^}]*?)(\}?)/);
+            if (arrowMatch) {
+              if (arrowMatch[1] === '{') {
+                // Multi-line function with braces - extract content between braces
+                const braceMatch = afterMatch.match(/=>\s*\{([^}]+)\}/);
+                if (braceMatch) {
+                  funcBody = braceMatch[1];
+                }
+              } else {
+                // Single expression arrow function
+                funcBody = arrowMatch[2];
+              }
+            }
+            
+            if (funcBody) {
+              const trimmedBody = funcBody.trim();
+              
+              // Very short handlers are usually simple
+              if (trimmedBody.length < 50) {
+                continue;
+              }
+              
+              // Check for simple setState patterns (even with object spread)
+              const isSimpleSetState = /^\s*set\w+\s*\([^)]*\)\s*;?\s*$/.test(trimmedBody) ||
+                                      /^\s*set\w+\s*\([^)]*prev\s*=>\s*\(\{[^}]*\}\)[^}]*\)\s*;?\s*$/.test(trimmedBody);
+              
+              // Check for simple function calls
+              const isSimpleFunctionCall = /^\s*(handle\w+|on\w+|navigate|window\.|document\.)\s*\([^)]*\)\s*;?\s*$/.test(trimmedBody);
+              
+              // Check for simple conditional (single if/ternary)
+              const isSimpleConditional = /^\s*(if\s*\([^)]+\)\s*\{[^}]{0,50}\}|[^?]+\?[^:]+:[^;]+;?)\s*$/.test(trimmedBody);
+              
+              // Check for simple value transformations (common in library components)
+              // Pattern: (e) => handleFunc(e.target.value || undefined)
+              // Pattern: (e) => handleFunc(e.target.value ? transform(e.target.value) : undefined)
+              const isSimpleValueTransform = /^\s*\w+\s*\([^)]*\.(target|value|checked|selected)[^)]*\)\s*;?\s*$/.test(trimmedBody) ||
+                                            /^\s*\w+\s*\([^)]*\?[^:]+:[^;]+\)\s*;?\s*$/.test(trimmedBody);
+              
+              // Skip simple handlers - they're fine as inline functions
+              if (isSimpleSetState || isSimpleFunctionCall || isSimpleConditional || isSimpleValueTransform) {
+                continue;
+              }
+            }
+            
+            suggestions.push({
+              type: 'inline-function-prop',
+              file: relativePath,
+              line: getLineNumber(content, funcMatch.index),
+              message: 'Complex inline function passed as prop',
+              recommendation: 'Use useCallback to memoize complex functions passed as props to prevent child re-renders. Simple event handlers (single setState call or function invocation) are fine as inline functions.'
+            });
+          }
+        }
+        // For library code, skip this check entirely - inline functions are acceptable patterns
+      } catch (error) {
+        // Skip files with errors
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = performanceCheck;