@jmruthers/pace-core 0.5.193 → 0.6.2

package/scripts/audit/core/checks/api-usage.cjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+/**
+ * API Usage Patterns Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/ApiUsage
+ * 
+ * Checks for:
+ * - Incorrect usage of pace-core hooks
+ * - Missing loading states
+ * - Missing error states
+ * - Race conditions in async operations
+ */
+
+const fs = require('fs');
+const { getRelativePath, getLineNumber } = require('../utils.cjs');
+
+const apiUsageCheck = {
+  name: 'api-usage',
+  description: 'API usage patterns (hook usage, loading/error states)',
+  severity: 'warning',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    if (!files || files.length === 0) {
+      return { issues, warnings, suggestions };
+    }
+    
+    // pace-core hooks that return loading/error states
+    const asyncHooks = {
+      'useUnifiedAuth': ['loading', 'error'],
+      'useOrganisations': ['isLoading', 'error'],
+      'useEvents': ['isLoading', 'error'],
+      'useSecureSupabase': [],
+      'useFileReference': ['isLoading', 'error'],
+      'useRBAC': ['isLoading', 'error']
+    };
+    
+    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 - api-usage check is for consuming applications, not the library itself
+        // Note: Library components may intentionally not check loading/error states in all cases
+        // (e.g., internal components that assume context is already set up)
+        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 API usage validation
+        const isScript = normalizedPath.startsWith('scripts/') || normalizedPath.includes('/scripts/');
+        if (isScript) {
+          continue; // Skip script files
+        }
+        
+        // Check each async hook
+        Object.entries(asyncHooks).forEach(([hookName, expectedStates]) => {
+          if (!content.includes(hookName)) {
+            return;
+          }
+          
+          const hookPattern = new RegExp(`const\\s+[^=]+=\\s+${hookName}\\s*\\(`, 'g');
+          let hookMatch;
+          while ((hookMatch = hookPattern.exec(content)) !== null) {
+            // Check the entire component, not just 300 chars after hook
+            // React's Rules of Hooks require all hooks to be called before conditional returns,
+            // so state checks may occur later in the component
+            const hookLine = getLineNumber(content, hookMatch.index);
+            const lines = content.split('\n');
+            const hookLineIndex = hookLine - 1;
+            
+            // Get the rest of the component after this hook
+            const afterHookContent = lines.slice(hookLineIndex).join('\n');
+            
+            // Check if loading state is used
+            if (expectedStates.includes('loading') || expectedStates.includes('isLoading')) {
+              const loadingState = expectedStates.includes('loading') ? 'loading' : 'isLoading';
+              // Check for loading state usage in the entire component
+              // Also check for common patterns: isLoading, authLoading, etc.
+              const loadingPattern = new RegExp(`\\b(${loadingState}|authLoading|rbacLoading|orgLoading)\\b`);
+              if (!loadingPattern.test(afterHookContent)) {
+                warnings.push({
+                  type: 'missing-loading-state',
+                  file: relativePath,
+                  line: hookLine,
+                  message: `${hookName} returns loading state but it's not being checked`,
+                  recommendation: `Check ${loadingState} state and show loading UI while data is fetching. You can check loading state after all hooks are called (required by React's Rules of Hooks).`
+                });
+              }
+            }
+            
+            // Check if error state is used
+            if (expectedStates.includes('error')) {
+              // Check for error state usage in the entire component
+              // Also check for common patterns: error, authError, orgError, rbacError
+              // Also check for null checks for useSecureSupabase
+              const errorPattern = /\b(error|authError|orgError|rbacError)\b/;
+              const hasNullCheck = hookName === 'useSecureSupabase' && /secureSupabase\s*===?\s*null|!secureSupabase/.test(afterHookContent);
+              
+              if (!errorPattern.test(afterHookContent) && !hasNullCheck) {
+                warnings.push({
+                  type: 'missing-error-state',
+                  file: relativePath,
+                  line: hookLine,
+                  message: `${hookName} returns error state but it's not being checked`,
+                  recommendation: 'Check error state and handle errors appropriately. You can check error state after all hooks are called (required by React\'s Rules of Hooks), or handle errors via useEffect hooks. For useSecureSupabase, null checks are also valid error handling.'
+                });
+              }
+            }
+          }
+        });
+        
+        // Check for race conditions in async operations
+        const asyncOperationPattern = /(?:const|let)\s+(\w+)\s*=\s*(?:await\s+)?(\w+)\.(from|rpc|select)/g;
+        let asyncMatch;
+        while ((asyncMatch = asyncOperationPattern.exec(content)) !== null) {
+          const varName = asyncMatch[1];
+          const operation = asyncMatch[0];
+          
+          // Check if this is in a useEffect without cleanup
+          const beforeMatch = content.substring(Math.max(0, asyncMatch.index - 500), asyncMatch.index);
+          const isInUseEffect = /useEffect\s*\(/.test(beforeMatch);
+          
+          if (isInUseEffect) {
+            // Check if there's cleanup/abort
+            const afterMatch = content.substring(asyncMatch.index, Math.min(content.length, asyncMatch.index + 500));
+            const hasCleanup = /return\s+\(\)\s*=>|AbortController|signal/.test(afterMatch);
+            
+            if (!hasCleanup) {
+              suggestions.push({
+                type: 'potential-race-condition',
+                file: relativePath,
+                line: getLineNumber(content, asyncMatch.index),
+                message: 'Async operation in useEffect without cleanup - potential race condition',
+                recommendation: 'Add cleanup function to cancel requests when component unmounts or dependencies change'
+              });
+            }
+          }
+        }
+        
+        // Check for missing request cancellation
+        const fetchPattern = /fetch\s*\(|axios\.(get|post|put|delete)\s*\(/g;
+        let fetchMatch;
+        while ((fetchMatch = fetchPattern.exec(content)) !== null) {
+          const beforeMatch = content.substring(Math.max(0, fetchMatch.index - 200), fetchMatch.index);
+          const isInUseEffect = /useEffect\s*\(/.test(beforeMatch);
+          
+          if (isInUseEffect) {
+            const afterMatch = content.substring(fetchMatch.index, Math.min(content.length, fetchMatch.index + 500));
+            const hasAbort = /AbortController|signal|abort/.test(afterMatch);
+            
+            if (!hasAbort) {
+              suggestions.push({
+                type: 'missing-abort',
+                file: relativePath,
+                line: getLineNumber(content, fetchMatch.index),
+                message: 'Fetch/axios request without abort signal',
+                recommendation: 'Use AbortController to cancel requests when component unmounts'
+              });
+            }
+          }
+        }
+        
+      } catch (error) {
+        // Skip files with errors
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = apiUsageCheck;

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

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+/**
+ * Bundle Analysis Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Bundle
+ * 
+ * Checks for:
+ * - Large bundle sizes
+ * - Duplicate dependencies
+ * - Unused code imports
+ * - Missing code splitting opportunities
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getRelativePath } = require('../utils.cjs');
+
+const bundleCheck = {
+  name: 'bundle',
+  description: 'Bundle analysis (size, duplicates, code splitting)',
+  severity: 'suggestion',
+  
+  async run(context) {
+    const { projectRoot } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    // Skip if this is the pace-core repository itself
+    // Detect pace-core repository by checking if packages/core exists
+    // Bundle analysis is more relevant for consuming applications, not the library itself
+    const packagesCorePath = path.join(projectRoot, 'packages', 'core');
+    const isPaceCoreRepository = fs.existsSync(packagesCorePath);
+    
+    // Check for bundle analysis reports
+    const bundleReportPaths = [
+      path.join(projectRoot, 'dist', 'stats.html'),
+      path.join(projectRoot, 'dist', 'bundle-analysis.json'),
+      path.join(projectRoot, '.vite', 'dist', 'stats.html')
+    ];
+    
+    let hasBundleReport = false;
+    for (const reportPath of bundleReportPaths) {
+      if (fs.existsSync(reportPath)) {
+        hasBundleReport = true;
+        break;
+      }
+    }
+    
+    // Skip bundle analysis suggestion if this is the pace-core repository
+    // The library itself doesn't need bundle analysis in the same way as consuming apps
+    if (!hasBundleReport && !isPaceCoreRepository) {
+      suggestions.push({
+        type: 'missing-bundle-analysis',
+        file: 'package.json',
+        message: 'No bundle analysis report found',
+        recommendation: 'Run bundle analysis to identify optimization opportunities: npm run build -- --analyze or use vite-bundle-visualizer'
+      });
+      return { issues, warnings, suggestions };
+    }
+    
+    // Check dist folder size
+    const distPath = path.join(projectRoot, 'dist');
+    if (fs.existsSync(distPath)) {
+      try {
+        const distSize = getDirectorySize(distPath);
+        const sizeMB = distSize / (1024 * 1024);
+        
+        if (sizeMB > 5) {
+          warnings.push({
+            type: 'large-bundle',
+            file: 'dist/',
+            message: `Bundle size is ${sizeMB.toFixed(2)}MB, which is quite large`,
+            recommendation: 'Consider code splitting, lazy loading, and removing unused dependencies'
+          });
+        }
+      } catch (error) {
+        // Skip if can't calculate size
+      }
+    }
+    
+    // Check for duplicate imports (same package imported multiple ways)
+    // This is a simplified check - full implementation would analyze actual bundle
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        const allDeps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+        
+        // Check for potential duplicates (e.g., lodash and lodash-es)
+        // Note: '@supabase/supabase-js' (client library) and 'supabase' (CLI tool) are NOT duplicates
+        // - '@supabase/supabase-js' is the JavaScript client library (runtime dependency)
+        // - 'supabase' is the Supabase CLI tool (dev dependency for migrations, local dev)
+        // The CLI tool is not bundled in the application, so having both is correct
+        const duplicatePatterns = [
+          ['lodash', 'lodash-es'],
+          ['date-fns', 'date-fns-tz']
+        ];
+        
+        duplicatePatterns.forEach(([dep1, dep2]) => {
+          if (allDeps[dep1] && allDeps[dep2]) {
+            warnings.push({
+              type: 'duplicate-dependency',
+              file: 'package.json',
+              message: `Both '${dep1}' and '${dep2}' are installed - may cause duplicate code in bundle`,
+              recommendation: `Remove one and use pace-core alternatives if available, or ensure only one is bundled`
+            });
+          }
+        });
+      } catch (error) {
+        // Skip if can't parse package.json
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+/**
+ * Calculate directory size recursively
+ */
+function getDirectorySize(dirPath) {
+  let size = 0;
+  try {
+    const items = fs.readdirSync(dirPath);
+    items.forEach(item => {
+      const itemPath = path.join(dirPath, item);
+      const stat = fs.statSync(itemPath);
+      if (stat.isDirectory()) {
+        size += getDirectorySize(itemPath);
+      } else {
+        size += stat.size;
+      }
+    });
+  } catch (error) {
+    // Skip if can't read
+  }
+  return size;
+}
+
+module.exports = bundleCheck;