@jmruthers/pace-core 0.6.5 → 0.6.7

package/audit-tool/audits/07-api-tech-stack.cjs

@@ -0,0 +1,301 @@
+/**
+ * Standard 7: API & Tech Stack Audit
+ * @package @jmruthers/pace-core
+ * @module Audit/Standard7
+ * 
+ * Audits consuming apps for compliance with Standard 7: API & Tech Stack.
+ * Validates RPC naming in SQL migrations, tech stack versions, and Vite configuration.
+ * 
+ * Reference: packages/core/docs/standards/7-api-tech-stack-standards.md
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { findSQLFiles, findConfigFiles, readFileSafe, getRelativePath, findPaceCorePackageJson } = require('../utils/file-utils.cjs');
+const { getLineNumber, getCodeSnippet, isInCommentOrStringSQL } = require('../utils/code-utils.cjs');
+
+/**
+ * Check RPC naming in SQL migrations (data_* for reads, app_* for writes)
+ */
+function checkRPCNaming(consumingAppPath) {
+  const issues = [];
+  
+  // Find SQL migration files
+  const migrationsPath = path.join(consumingAppPath, 'supabase', 'migrations');
+  const altMigrationsPath = path.join(consumingAppPath, 'migrations');
+  
+  const migrationsDir = fs.existsSync(migrationsPath) ? migrationsPath : 
+                        (fs.existsSync(altMigrationsPath) ? altMigrationsPath : null);
+  
+  if (!migrationsDir) {
+    return issues; // No migrations directory, skip check
+  }
+  
+  const sqlFiles = findSQLFiles(migrationsDir);
+  
+  sqlFiles.forEach(filePath => {
+    try {
+      const content = readFileSafe(filePath);
+      if (!content) {
+        return;
+      }
+      
+      const relativePath = getRelativePath(filePath, consumingAppPath);
+      
+      // Find CREATE FUNCTION statements for RPCs
+      const functionPattern = /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+(?:public\.)?["']?([^"'\s()]+)["']?\s*\(/gi;
+      let match;
+      
+      while ((match = functionPattern.exec(content)) !== null) {
+        const functionName = match[1];
+        const functionStart = match.index;
+        
+        if (isInCommentOrStringSQL(content, functionStart)) {
+          continue;
+        }
+        
+        // Skip if it's a helper function (starts with check_, get_, is_)
+        if (/^(check_|get_|is_)/i.test(functionName)) {
+          continue;
+        }
+        
+        // Check if it's a system function (starts with pg_ or other system prefixes)
+        if (/^(pg_|information_schema|current_|session_|set_|reset_|show_)/i.test(functionName)) {
+          continue;
+        }
+        
+        // Check if it's an RPC (functions that are exposed as RPCs typically follow naming pattern)
+        // Skip if it's a helper function (doesn't follow data_* or app_* pattern)
+        if (!/^(data_|app_)/.test(functionName)) {
+          // Not an RPC, but should follow naming convention
+          issues.push({
+            type: 'rpcNaming',
+            file: relativePath,
+            line: getLineNumber(content, functionStart),
+            message: `RPC function '${functionName}' does not follow naming convention. Should start with 'data_' (read) or 'app_' (write) prefix.`,
+            code: getCodeSnippet(content, functionStart, 0, 100),
+            severity: 'error',
+            fix: `Rename function to follow pattern: data_${functionName} (for read) or app_${functionName} (for write)`,
+          });
+          continue;
+        }
+        
+        // Check naming pattern: data_* for reads, app_* for writes
+        const readVerbs = ['list', 'get', 'read'];
+        const writeVerbs = ['create', 'update', 'delete', 'bulk_create', 'bulk_update'];
+        const validVerbs = [...readVerbs, ...writeVerbs];
+        
+        const parts = functionName.split('_');
+        const verb = parts[parts.length - 1];
+        
+        if (!validVerbs.includes(verb)) {
+          issues.push({
+            type: 'rpcNaming',
+            file: relativePath,
+            line: getLineNumber(content, functionStart),
+            message: `RPC '${functionName}' uses invalid verb '${verb}'. Use only: ${validVerbs.join(', ')}`,
+            code: getCodeSnippet(content, functionStart, 0, 100),
+            severity: 'error',
+            fix: `Rename RPC to use valid verb: ${functionName.replace(verb, validVerbs[0])}`,
+          });
+          continue;
+        }
+        
+        // Check prefix-verb alignment
+        const hasDataPrefix = functionName.startsWith('data_');
+        const hasAppPrefix = functionName.startsWith('app_');
+        const isReadOperation = readVerbs.includes(verb);
+        const isWriteOperation = writeVerbs.includes(verb);
+        
+        if (hasDataPrefix && isWriteOperation) {
+          issues.push({
+            type: 'rpcNaming',
+            file: relativePath,
+            line: getLineNumber(content, functionStart),
+            message: `RPC '${functionName}' has 'data_' prefix but uses write verb '${verb}'. Use 'app_' prefix for write operations.`,
+            code: getCodeSnippet(content, functionStart, 0, 100),
+            severity: 'error',
+            fix: `Rename to app_${functionName.replace('data_', '')}`,
+          });
+        }
+        
+        if (hasAppPrefix && isReadOperation) {
+          issues.push({
+            type: 'rpcNaming',
+            file: relativePath,
+            line: getLineNumber(content, functionStart),
+            message: `RPC '${functionName}' has 'app_' prefix but uses read verb '${verb}'. Use 'data_' prefix for read operations.`,
+            code: getCodeSnippet(content, functionStart, 0, 100),
+            severity: 'error',
+            fix: `Rename to data_${functionName.replace('app_', '')}`,
+          });
+        }
+      }
+    } catch (error) {
+      // Skip files that can't be read
+    }
+  });
+  
+  return issues;
+}
+
+/**
+ * Check tech stack versions
+ */
+function checkTechStackVersions(consumingAppPath) {
+  const issues = [];
+  
+  const packageJsonPath = path.join(consumingAppPath, 'package.json');
+  const packageJsonContent = readFileSafe(packageJsonPath);
+  
+  if (!packageJsonContent) {
+    return issues;
+  }
+  
+  let packageJson;
+  try {
+    packageJson = JSON.parse(packageJsonContent);
+  } catch (error) {
+    return issues;
+  }
+  
+  const allDeps = {
+    ...(packageJson.dependencies || {}),
+    ...(packageJson.devDependencies || {}),
+  };
+  
+  // Get pace-core package.json for peer dependencies
+  const paceCorePath = findPaceCorePackageJson(consumingAppPath);
+  if (!paceCorePath) {
+    return issues;
+  }
+  
+  const paceCorePkg = JSON.parse(fs.readFileSync(paceCorePath, 'utf8'));
+  const peerDeps = paceCorePkg.peerDependencies || {};
+  
+  // Check required peer dependencies
+  const requiredPeers = ['react', 'react-dom', 'react-router-dom'];
+  
+  requiredPeers.forEach(dep => {
+    if (!allDeps[dep]) {
+      issues.push({
+        type: 'techStack',
+        file: 'package.json',
+        line: 1,
+        message: `Missing required dependency: ${dep}. Required version: ${peerDeps[dep] || 'latest'}`,
+        severity: 'error',
+        fix: `Install ${dep}: npm install ${dep}@${peerDeps[dep] || 'latest'}`,
+      });
+    }
+  });
+  
+  // Check React 19+ requirement
+  if (allDeps.react) {
+    const reactVersion = allDeps.react.replace(/[\^~]/, '');
+    const reactMajor = parseInt(reactVersion.split('.')[0]);
+    
+    if (reactMajor < 19) {
+      issues.push({
+        type: 'techStack',
+        file: 'package.json',
+        line: 1,
+        message: `React version ${reactVersion} is below required version 19+. pace-core requires React 19+.`,
+        severity: 'error',
+        fix: 'Upgrade React: npm install react@^19.0.0 react-dom@^19.0.0',
+      });
+    }
+  }
+  
+  return issues;
+}
+
+/**
+ * Check Vite configuration (optimizeDeps, resolve.dedupe)
+ */
+function checkViteConfig(consumingAppPath) {
+  const issues = [];
+  
+  const viteConfigFiles = findConfigFiles(consumingAppPath, ['vite.config.ts', 'vite.config.js']);
+  const viteConfigPath = viteConfigFiles['vite.config.ts'] || viteConfigFiles['vite.config.js'];
+  
+  if (!viteConfigPath) {
+    return issues; // No vite config, skip
+  }
+  
+  const content = readFileSafe(viteConfigPath);
+  if (!content) {
+    return issues;
+  }
+  
+  const relativePath = getRelativePath(viteConfigPath, consumingAppPath);
+  
+  // Check for optimizeDeps.exclude (should exclude pace-core and react-router-dom)
+  const hasOptimizeDepsExclude = /optimizeDeps\s*:\s*\{[^}]*exclude/.test(content);
+  if (!hasOptimizeDepsExclude) {
+    issues.push({
+      type: 'viteConfig',
+      file: relativePath,
+      line: 1,
+      message: 'vite.config.ts missing optimizeDeps.exclude. Should exclude @jmruthers/pace-core and react-router-dom to prevent React context mismatches.',
+      severity: 'warning',
+      fix: 'Add: optimizeDeps: { exclude: [\'@jmruthers/pace-core\', \'react-router-dom\'] }',
+    });
+  } else {
+    // Check if pace-core is excluded
+    const excludesPaceCore = /exclude\s*:\s*\[[^\]]*['"]@jmruthers\/pace-core['"]/.test(content);
+    if (!excludesPaceCore) {
+      issues.push({
+        type: 'viteConfig',
+        file: relativePath,
+        line: 1,
+        message: 'vite.config.ts optimizeDeps.exclude should include @jmruthers/pace-core to prevent React context mismatches.',
+        severity: 'warning',
+        fix: 'Add \'@jmruthers/pace-core\' to optimizeDeps.exclude array',
+      });
+    }
+  }
+  
+  // Check for resolve.dedupe (should dedupe React dependencies)
+  const hasResolveDedupe = /resolve\s*:\s*\{[^}]*dedupe/.test(content);
+  if (!hasResolveDedupe) {
+    issues.push({
+      type: 'viteConfig',
+      file: relativePath,
+      line: 1,
+      message: 'vite.config.ts missing resolve.dedupe. Should dedupe React dependencies to prevent context mismatches.',
+      severity: 'warning',
+      fix: 'Add: resolve: { dedupe: [\'react\', \'react-dom\', \'react-router-dom\'] }',
+    });
+  }
+  
+  return issues;
+}
+
+/**
+ * Run audit for Standard 7: API & Tech Stack
+ * @param {string} consumingAppPath - Path to consuming app
+ * @returns {object} - Audit results with issues array
+ */
+function runStandard7Audit(consumingAppPath) {
+  const issues = [];
+  
+  try {
+    issues.push(...checkRPCNaming(consumingAppPath));
+    issues.push(...checkTechStackVersions(consumingAppPath));
+    issues.push(...checkViteConfig(consumingAppPath));
+  } catch (error) {
+    return {
+      standard: '07-api-tech-stack',
+      issues: [],
+      error: error.message,
+    };
+  }
+  
+  return {
+    standard: '07-api-tech-stack',
+    issues,
+    error: null,
+  };
+}
+
+module.exports = { runStandard7Audit };

package/audit-tool/audits/08-testing-documentation.cjs

@@ -0,0 +1,202 @@
+/**
+ * Standard 8: Testing & Documentation Audit
+ * @package @jmruthers/pace-core
+ * @module Audit/Standard8
+ * 
+ * Audits consuming apps for compliance with Standard 8: Testing & Documentation.
+ * Validates test structure, test timeout configuration, and testing tools.
+ * 
+ * Reference: packages/core/docs/standards/8-testing-documentation-standards.md
+ */
+
+const path = require('path');
+const { findConfigFiles, readFileSafe, getRelativePath, findSourceFiles, directoryExists } = require('../utils/file-utils.cjs');
+
+/**
+ * Check test timeout configuration
+ */
+function checkTestTimeoutConfig(consumingAppPath) {
+  const issues = [];
+  
+  // Check vitest.config.ts
+  const vitestConfigFiles = findConfigFiles(consumingAppPath, ['vitest.config.ts', 'vitest.config.js']);
+  const vitestConfigPath = vitestConfigFiles['vitest.config.ts'] || vitestConfigFiles['vitest.config.js'];
+  
+  // Also check package.json for test scripts
+  const packageJsonPath = path.join(consumingAppPath, 'package.json');
+  const packageJsonContent = readFileSafe(packageJsonPath);
+  
+  let hasTimeoutInConfig = false;
+  let hasTimeoutInScripts = false;
+  
+  // Check vitest.config.ts
+  if (vitestConfigPath) {
+    const content = readFileSafe(vitestConfigPath);
+    if (content) {
+      const hasTestTimeout = /testTimeout\s*[:=]/.test(content);
+      const hasHookTimeout = /hookTimeout\s*[:=]/.test(content);
+      
+      if (hasTestTimeout || hasHookTimeout) {
+        hasTimeoutInConfig = true;
+      } else {
+        const relativePath = getRelativePath(vitestConfigPath, consumingAppPath);
+        issues.push({
+          type: 'testTimeout',
+          file: relativePath,
+          line: 1,
+          message: 'vitest.config.ts missing test timeout configuration. Tests may hang indefinitely without timeouts.',
+          severity: 'error',
+          fix: 'Add: test: { testTimeout: 10000, hookTimeout: 10000, teardownTimeout: 5000 }',
+        });
+      }
+    }
+  }
+  
+  // Check package.json scripts
+  if (packageJsonContent) {
+    try {
+      const packageJson = JSON.parse(packageJsonContent);
+      const scripts = packageJson.scripts || {};
+      
+      const testScripts = Object.values(scripts).filter(script => 
+        typeof script === 'string' && script.includes('vitest')
+      );
+      
+      hasTimeoutInScripts = testScripts.some(script => 
+        script.includes('--test-timeout') || script.includes('testTimeout')
+      );
+      
+      if (!hasTimeoutInConfig && !hasTimeoutInScripts && testScripts.length > 0) {
+        issues.push({
+          type: 'testTimeout',
+          file: 'package.json',
+          line: 1,
+          message: 'Test scripts missing timeout configuration. Tests may hang indefinitely without timeouts.',
+          severity: 'error',
+          fix: 'Add --test-timeout=10000 to test scripts or configure in vitest.config.ts',
+        });
+      }
+    } catch (error) {
+      // Skip if package.json can't be parsed
+    }
+  }
+  
+  return issues;
+}
+
+/**
+ * Check testing tools (React Testing Library, userEvent, Vitest)
+ */
+function checkTestingTools(consumingAppPath) {
+  const issues = [];
+  
+  const packageJsonPath = path.join(consumingAppPath, 'package.json');
+  const packageJsonContent = readFileSafe(packageJsonPath);
+  
+  if (!packageJsonContent) {
+    return issues;
+  }
+  
+  let packageJson;
+  try {
+    packageJson = JSON.parse(packageJsonContent);
+  } catch (error) {
+    return issues;
+  }
+  
+  const allDeps = {
+    ...(packageJson.dependencies || {}),
+    ...(packageJson.devDependencies || {}),
+  };
+  
+  // Check for required testing tools
+  const requiredTools = [
+    { name: 'vitest', description: 'Test runner' },
+    { name: '@testing-library/react', description: 'React Testing Library' },
+    { name: '@testing-library/user-event', description: 'userEvent for interaction simulation' },
+  ];
+  
+  requiredTools.forEach(({ name, description }) => {
+    if (!allDeps[name]) {
+      issues.push({
+        type: 'testingTools',
+        file: 'package.json',
+        line: 1,
+        message: `Missing required testing tool: ${name} (${description})`,
+        severity: 'warning',
+        fix: `Install: npm install --save-dev ${name}`,
+      });
+    }
+  });
+  
+  return issues;
+}
+
+/**
+ * Check test file structure (colocation, naming)
+ */
+function checkTestStructure(consumingAppPath) {
+  const issues = [];
+  
+  const srcDir = path.join(consumingAppPath, 'src');
+  if (!directoryExists(srcDir)) {
+    return issues;
+  }
+  
+  // Find all test files
+  const testFiles = findSourceFiles(srcDir).filter(file => 
+    file.includes('.test.') || file.includes('.spec.')
+  );
+  
+  testFiles.forEach(testFile => {
+    const content = readFileSafe(testFile);
+    if (!content) {
+      return;
+    }
+    
+    const relativePath = getRelativePath(testFile, consumingAppPath);
+    
+    // Check if using .spec instead of .test
+    if (testFile.includes('.spec.')) {
+      issues.push({
+        type: 'testStructure',
+        file: relativePath,
+        line: 1,
+        message: 'Test file uses .spec extension. Should use .test extension for consistency.',
+        severity: 'warning',
+        fix: `Rename to ${testFile.replace('.spec.', '.test.')}`,
+      });
+    }
+  });
+  
+  return issues;
+}
+
+/**
+ * Run audit for Standard 8: Testing & Documentation
+ * @param {string} consumingAppPath - Path to consuming app
+ * @returns {object} - Audit results with issues array
+ */
+function runStandard8Audit(consumingAppPath) {
+  const issues = [];
+  
+  try {
+    issues.push(...checkTestTimeoutConfig(consumingAppPath));
+    issues.push(...checkTestingTools(consumingAppPath));
+    issues.push(...checkTestStructure(consumingAppPath));
+  } catch (error) {
+    return {
+      standard: '08-testing-documentation',
+      issues: [],
+      error: error.message,
+    };
+  }
+  
+  return {
+    standard: '08-testing-documentation',
+    issues,
+    error: null,
+  };
+}
+
+module.exports = { runStandard8Audit };

package/audit-tool/audits/09-operations.cjs

@@ -0,0 +1,208 @@
+/**
+ * Standard 9: Operations Audit
+ * @package @jmruthers/pace-core
+ * @module Audit/Standard9
+ * 
+ * Audits consuming apps for compliance with Standard 9: Operations.
+ * Validates error handling patterns, CI/CD configuration, and performance patterns.
+ * 
+ * Reference: packages/core/docs/standards/9-operations-standards.md
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { findSourceFiles, readFileSafe, getRelativePath, directoryExists } = require('../utils/file-utils.cjs');
+const { getLineNumber, getCodeSnippet, isInCommentOrString } = require('../utils/code-utils.cjs');
+
+/**
+ * Check error handling patterns (ApiResult usage)
+ */
+function checkErrorHandlingPatterns(consumingAppPath) {
+  const issues = [];
+  
+  const srcDir = path.join(consumingAppPath, 'src');
+  if (!directoryExists(srcDir)) {
+    return issues;
+  }
+  
+  const sourceFiles = findSourceFiles(srcDir);
+  
+  // Check for API functions that don't use ApiResult pattern
+  sourceFiles.forEach(filePath => {
+    const content = readFileSafe(filePath);
+    if (!content) {
+      return;
+    }
+    
+    // Skip test files
+    if (filePath.includes('.test.') || filePath.includes('.spec.')) {
+      return;
+    }
+    
+    const relativePath = getRelativePath(filePath, consumingAppPath);
+    
+    // Look for async functions that might be API functions
+    const asyncFunctionPattern = /(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\([^)]*\)\s*:\s*Promise/gi;
+    const matches = [...content.matchAll(asyncFunctionPattern)];
+    
+    matches.forEach(match => {
+      const functionName = match[1];
+      const functionIndex = match.index;
+      
+      // Skip if it's a hook
+      if (functionName.startsWith('use')) {
+        return;
+      }
+      
+      // Check if function uses ApiResult
+      const functionBody = content.substring(functionIndex, Math.min(functionIndex + 500, content.length));
+      const usesApiResult = /ApiResult|ok:\s*(true|false)/.test(functionBody);
+      
+      if (!usesApiResult) {
+        // Check if it's likely an API function (returns Promise, might throw errors)
+        const returnsPromise = /:\s*Promise/.test(match[0]);
+        const hasErrorHandling = /catch|throw|error/i.test(functionBody);
+        
+        if (returnsPromise && hasErrorHandling) {
+          issues.push({
+            type: 'errorHandling',
+            file: relativePath,
+            line: getLineNumber(content, functionIndex),
+            message: `API function '${functionName}' does not use ApiResult pattern. Consider using ApiResult<T> for consistent error handling.`,
+            code: getCodeSnippet(content, functionIndex),
+            severity: 'info',
+            fix: 'Use ApiResult<T> type: type ApiResult<T> = { ok: true; data: T } | { ok: false; error: ApiError }',
+          });
+        }
+      }
+    });
+  });
+  
+  return issues;
+}
+
+/**
+ * Check CI/CD configuration
+ */
+function checkCICDConfig(consumingAppPath) {
+  const issues = [];
+  
+  // Check for .github/workflows directory
+  const workflowsDir = path.join(consumingAppPath, '.github', 'workflows');
+  
+  if (!directoryExists(workflowsDir)) {
+    issues.push({
+      type: 'cicd',
+      file: '.github/workflows/ (not found)',
+      line: 0,
+      message: 'CI/CD workflows directory not found. Consider setting up GitHub Actions for automated testing and deployment.',
+      severity: 'info',
+      fix: 'Create .github/workflows/ directory and add CI/CD workflow files',
+    });
+    return issues;
+  }
+  
+  // Check for common workflow files
+  const workflowFiles = fs.existsSync(workflowsDir) 
+    ? fs.readdirSync(workflowsDir).filter(file => file.endsWith('.yml') || file.endsWith('.yaml'))
+    : [];
+  
+  if (workflowFiles.length === 0) {
+    issues.push({
+      type: 'cicd',
+      file: '.github/workflows/',
+      line: 0,
+      message: 'No CI/CD workflow files found. Consider setting up automated testing and deployment.',
+      severity: 'info',
+      fix: 'Create workflow files in .github/workflows/ (e.g., ci.yml, deploy.yml)',
+    });
+  }
+  
+  return issues;
+}
+
+/**
+ * Check for error boundary usage
+ */
+function checkErrorBoundaries(consumingAppPath) {
+  const issues = [];
+  
+  const srcDir = path.join(consumingAppPath, 'src');
+  if (!directoryExists(srcDir)) {
+    return issues;
+  }
+  
+  const sourceFiles = findSourceFiles(srcDir);
+  
+  // Check if ErrorBoundary is used
+  let hasErrorBoundary = false;
+  sourceFiles.forEach(filePath => {
+    const content = readFileSafe(filePath);
+    if (!content) {
+      return;
+    }
+    
+    if (/ErrorBoundary|errorBoundary/i.test(content)) {
+      hasErrorBoundary = true;
+    }
+  });
+  
+  // Check main.tsx or App.tsx for ErrorBoundary
+  const mainFiles = [
+    path.join(consumingAppPath, 'src', 'main.tsx'),
+    path.join(consumingAppPath, 'src', 'App.tsx'),
+    path.join(consumingAppPath, 'App.tsx'),
+  ];
+  
+  let hasErrorBoundaryInApp = false;
+  mainFiles.forEach(filePath => {
+    if (fs.existsSync(filePath)) {
+      const content = readFileSafe(filePath);
+      if (content && /ErrorBoundary|errorBoundary/i.test(content)) {
+        hasErrorBoundaryInApp = true;
+      }
+    }
+  });
+  
+  if (!hasErrorBoundaryInApp && hasErrorBoundary) {
+    issues.push({
+      type: 'errorBoundary',
+      file: 'src/main.tsx or src/App.tsx',
+      line: 1,
+      message: 'ErrorBoundary component exists but is not used in main.tsx or App.tsx. Should wrap the app root to catch React errors.',
+      severity: 'warning',
+      fix: 'Wrap app root with ErrorBoundary in main.tsx or App.tsx',
+    });
+  }
+  
+  return issues;
+}
+
+/**
+ * Run audit for Standard 9: Operations
+ * @param {string} consumingAppPath - Path to consuming app
+ * @returns {object} - Audit results with issues array
+ */
+function runStandard9Audit(consumingAppPath) {
+  const issues = [];
+  
+  try {
+    issues.push(...checkErrorHandlingPatterns(consumingAppPath));
+    issues.push(...checkCICDConfig(consumingAppPath));
+    issues.push(...checkErrorBoundaries(consumingAppPath));
+  } catch (error) {
+    return {
+      standard: '09-operations',
+      issues: [],
+      error: error.message,
+    };
+  }
+  
+  return {
+    standard: '09-operations',
+    issues,
+    error: null,
+  };
+}
+
+module.exports = { runStandard9Audit };