@jmruthers/pace-core 0.6.6 → 0.6.8

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

@@ -0,0 +1,355 @@
+/**
+ * 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)
+  // Need to handle nested objects, so look for dedupe anywhere after resolve: {
+  // Match resolve: { ... and then look for dedupe before the matching closing brace
+  // Use a more flexible pattern that handles nested braces
+  const resolvePattern = /resolve\s*:\s*\{/;
+  const resolveMatch = content.match(resolvePattern);
+  
+  let hasResolveDedupe = false;
+  if (resolveMatch) {
+    const resolveStart = resolveMatch.index + resolveMatch[0].length;
+    // Find the matching closing brace for the resolve object
+    let braceCount = 1;
+    let i = resolveStart;
+    let resolveEnd = -1;
+    
+    while (i < content.length && braceCount > 0) {
+      if (content[i] === '{') braceCount++;
+      if (content[i] === '}') braceCount--;
+      if (braceCount === 0) {
+        resolveEnd = i;
+        break;
+      }
+      i++;
+    }
+    
+    if (resolveEnd > 0) {
+      const resolveBody = content.substring(resolveStart, resolveEnd);
+      // Check if dedupe exists in the resolve object body
+      hasResolveDedupe = /dedupe\s*:/.test(resolveBody);
+      
+      // Also verify it includes the required dependencies
+      if (hasResolveDedupe) {
+        const dedupePattern = /dedupe\s*:\s*\[([^\]]+)\]/;
+        const dedupeMatch = resolveBody.match(dedupePattern);
+        if (dedupeMatch) {
+          const dedupeArray = dedupeMatch[1];
+          const hasReact = /['"]react['"]/.test(dedupeArray);
+          const hasReactDom = /['"]react-dom['"]/.test(dedupeArray);
+          const hasReactRouter = /['"]react-router-dom['"]/.test(dedupeArray);
+          
+          // If any required dependency is missing, flag it
+          if (!hasReact || !hasReactDom || !hasReactRouter) {
+            issues.push({
+              type: 'viteConfig',
+              file: relativePath,
+              line: 1,
+              message: 'vite.config.ts resolve.dedupe is missing required dependencies. Should include: react, react-dom, react-router-dom',
+              severity: 'warning',
+              fix: 'Update resolve.dedupe to include: [\'react\', \'react-dom\', \'react-router-dom\']',
+            });
+          }
+        }
+      }
+    }
+  }
+  
+  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 };