@jmruthers/pace-core 0.6.6 → 0.6.8

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 };

package/audit-tool/index.cjs

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+
+/**
+ * Comprehensive Audit Script for Consuming Apps
+ * @package @jmruthers/pace-core
+ * @module Audit
+ * 
+ * Audits consuming apps against pace-core standards and generates a markdown report.
+ * Organized by the 10-file standards structure (Standards 1-9).
+ * 
+ * This is Layer 4 of the quality enforcement strategy:
+ * - Layer 1: Standards Documents (Source of Truth)
+ * - Layer 2: Cursor Rules (Real-time Guidance)
+ * - Layer 3: ESLint (Fast, Local Static Analysis)
+ * - Layer 4: Audit Tool (Deep, System-Level Analysis) ← You are here
+ * 
+ * Usage:
+ *   node packages/core/audit-tool/index.cjs [path-to-consuming-app] [--output report.md]
+ *   npm run audit:pace-core [path-to-consuming-app] [--output report.md]
+ * 
+ * If no path provided, assumes current directory is consuming app.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Import dependency audit (runs before standards)
+const { runDependencyAudit } = require('./00-dependencies.cjs');
+
+// Import new standard-aligned audit modules
+const { runStandard1Audit } = require('./audits/01-pace-core-compliance.cjs');
+const { runStandard2Audit } = require('./audits/02-project-structure.cjs');
+const { runStandard3Audit } = require('./audits/03-architecture.cjs');
+const { runStandard4Audit } = require('./audits/04-code-quality.cjs');
+const { runStandard5Audit } = require('./audits/05-styling.cjs');
+const { runStandard6Audit } = require('./audits/06-security-rbac.cjs');
+const { runStandard7Audit } = require('./audits/07-api-tech-stack.cjs');
+const { runStandard8Audit } = require('./audits/08-testing-documentation.cjs');
+const { runStandard9Audit } = require('./audits/09-operations.cjs');
+
+// Import report utilities
+const { generateMarkdownReport, generateSummary } = require('./utils/report-utils.cjs');
+
+// Colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  bold: '\x1b[1m',
+};
+
+/**
+ * Run all standard audits
+ */
+function runAllAudits(consumingAppPath, showProgress = false) {
+  const results = {};
+  
+  const standardNames = {
+    '01-pace-core-compliance': 'pace-core Compliance',
+    '02-project-structure': 'Project Structure',
+    '03-architecture': 'Architecture',
+    '04-code-quality': 'Code Quality',
+    '05-styling': 'Styling',
+    '06-security-rbac': 'Security & RBAC',
+    '07-api-tech-stack': 'API & Tech Stack',
+    '08-testing-documentation': 'Testing & Documentation',
+    '09-operations': 'Operations',
+  };
+  
+  const auditFunctions = [
+    { key: '01-pace-core-compliance', name: standardNames['01-pace-core-compliance'], fn: runStandard1Audit },
+    { key: '02-project-structure', name: standardNames['02-project-structure'], fn: runStandard2Audit },
+    { key: '03-architecture', name: standardNames['03-architecture'], fn: runStandard3Audit },
+    { key: '04-code-quality', name: standardNames['04-code-quality'], fn: runStandard4Audit },
+    { key: '05-styling', name: standardNames['05-styling'], fn: runStandard5Audit },
+    { key: '06-security-rbac', name: standardNames['06-security-rbac'], fn: runStandard6Audit },
+    { key: '07-api-tech-stack', name: standardNames['07-api-tech-stack'], fn: runStandard7Audit },
+    { key: '08-testing-documentation', name: standardNames['08-testing-documentation'], fn: runStandard8Audit },
+    { key: '09-operations', name: standardNames['09-operations'], fn: runStandard9Audit },
+  ];
+  
+  auditFunctions.forEach(({ key, name, fn }) => {
+    if (showProgress) {
+      console.log(`${colors.blue}Running ${name} audit...${colors.reset}`);
+    }
+    
+    try {
+      const result = fn(consumingAppPath);
+      results[key] = result;
+      
+      if (result.error && showProgress) {
+        console.warn(`${colors.yellow}Warning: ${name} audit failed: ${result.error}${colors.reset}`);
+      }
+    } catch (error) {
+      if (showProgress) {
+        console.warn(`${colors.yellow}Warning: ${name} audit encountered an error: ${error.message}${colors.reset}`);
+      }
+      results[key] = {
+        standard: key,
+        issues: [],
+        error: error.message,
+      };
+    }
+  });
+  
+  return results;
+}
+
+/**
+ * Main function
+ */
+function main() {
+  const args = process.argv.slice(2);
+  const outputArg = args.find(arg => arg.startsWith('--output'));
+  const outputPath = outputArg ? (outputArg.includes('=') ? outputArg.split('=')[1] : args[args.indexOf(outputArg) + 1] || 'audit-report.md') : null;
+  const consumingAppPath = args.find(arg => !arg.startsWith('--') && arg !== outputPath) || process.cwd();
+  
+  console.log(`${colors.bold}${colors.cyan}pace-core Comprehensive Audit${colors.reset}\n`);
+  console.log(`${colors.cyan}${'='.repeat(50)}${colors.reset}\n`);
+  
+  // Get project info from package.json
+  const packageJsonPath = path.join(consumingAppPath, 'package.json');
+  let projectName = 'unknown';
+  let paceCoreVersion = 'unknown';
+  
+  if (fs.existsSync(packageJsonPath)) {
+    try {
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+      projectName = packageJson.name || 'unknown';
+      
+      // Find pace-core version
+      const allDeps = {
+        ...(packageJson.dependencies || {}),
+        ...(packageJson.devDependencies || {}),
+      };
+      paceCoreVersion = allDeps['@jmruthers/pace-core'] || 'not found in package.json';
+    } catch (error) {
+      // Skip if package.json can't be parsed
+    }
+  }
+  
+  console.log(`Project: ${colors.bold}${projectName}${colors.reset}`);
+  console.log(`pace-core: ${colors.bold}${paceCoreVersion}${colors.reset}\n`);
+  
+  // Run dependency audit
+  console.log(`${colors.blue}Running dependency audit...${colors.reset}`);
+  const dependencyResult = runDependencyAudit(consumingAppPath);
+  
+  // Run all standard audits
+  const standardResults = runAllAudits(consumingAppPath, true);
+  
+  // Combine results
+  const allResults = {
+    ...standardResults,
+    dependencies: dependencyResult,
+  };
+  
+  // Generate summary
+  const summary = generateSummary(standardResults);
+  
+  // Display audit results summary
+  console.log(`\n${colors.bold}Audit Results:${colors.reset}\n`);
+  
+  // Display dependency audit first
+  if (dependencyResult.error) {
+    console.log(`  ${colors.red}❌ Dependency Audit: Error - ${dependencyResult.error}${colors.reset}`);
+  } else {
+    const depIssues = dependencyResult.issues || {};
+    const depCount = (depIssues.includedDeps?.length || 0) +
+                     (depIssues.missingRequired?.length || 0) +
+                     (depIssues.versionIssues?.length || 0) +
+                     (depIssues.wrongLocation?.length || 0) +
+                     (depIssues.missingDevDeps?.length || 0) +
+                     (depIssues.devVersionIssues?.length || 0);
+    
+    if (depCount === 0) {
+      console.log(`  ${colors.green}✅ Dependency Audit: 0 issues${colors.reset}`);
+    } else {
+      console.log(`  ${colors.red}❌ Dependency Audit: ${depCount} issue(s)${colors.reset}`);
+    }
+  }
+  
+  // Display each standard
+  Object.entries(standardResults).forEach(([key, result]) => {
+    const standardNames = {
+      '01-pace-core-compliance': 'pace-core Compliance',
+      '02-project-structure': 'Project Structure',
+      '03-architecture': 'Architecture',
+      '04-code-quality': 'Code Quality',
+      '05-styling': 'Styling',
+      '06-security-rbac': 'Security & RBAC',
+      '07-api-tech-stack': 'API & Tech Stack',
+      '08-testing-documentation': 'Testing & Documentation',
+      '09-operations': 'Operations',
+    };
+    
+    const name = standardNames[key] || key;
+    const issues = Array.isArray(result.issues) ? result.issues : Object.values(result.issues || {}).flat();
+    const count = issues.length;
+    
+    if (count === 0) {
+      console.log(`  ${colors.green}✅ ${name}: 0 issues${colors.reset}`);
+    } else {
+      console.log(`  ${colors.red}❌ ${name}: ${count} issue(s)${colors.reset}`);
+    }
+  });
+  
+  // Total summary
+  const totalIssues = summary.total + (dependencyResult.error ? 0 : 
+    ((dependencyResult.issues?.includedDeps?.length || 0) +
+     (dependencyResult.issues?.missingRequired?.length || 0) +
+     (dependencyResult.issues?.versionIssues?.length || 0) +
+     (dependencyResult.issues?.wrongLocation?.length || 0) +
+     (dependencyResult.issues?.missingDevDeps?.length || 0) +
+     (dependencyResult.issues?.devVersionIssues?.length || 0)));
+  
+  console.log(`\n${colors.bold}Total Issues: ${totalIssues === 0 ? colors.green + '0 (All checks passed!)' : colors.red + totalIssues}${colors.reset}\n`);
+  
+  // Generate and save markdown report
+  const markdownReport = generateMarkdownReport(standardResults, consumingAppPath, dependencyResult);
+  
+  // Generate timestamp in yyyymmddHHMM format
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, '0');
+  const day = String(now.getDate()).padStart(2, '0');
+  const hours = String(now.getHours()).padStart(2, '0');
+  const minutes = String(now.getMinutes()).padStart(2, '0');
+  const timestamp = `${year}${month}${day}${hours}${minutes}`;
+  
+  // Helper function to add timestamp to filename
+  function addTimestampToFilename(filePath) {
+    const dir = path.dirname(filePath);
+    const ext = path.extname(filePath);
+    const name = path.basename(filePath, ext);
+    return path.join(dir, `${name}-${timestamp}${ext}`);
+  }
+  
+  // Determine report path
+  let reportPath;
+  if (outputPath) {
+    reportPath = addTimestampToFilename(path.join(consumingAppPath, outputPath));
+  } else {
+    // Default: save to audit/ directory
+    const auditDir = path.join(consumingAppPath, 'audit');
+    if (!fs.existsSync(auditDir)) {
+      fs.mkdirSync(auditDir, { recursive: true });
+    }
+    reportPath = path.join(auditDir, `pace-core-audit-${timestamp}.md`);
+  }
+  
+  // Save report
+  fs.writeFileSync(reportPath, markdownReport, 'utf8');
+  
+  // Display report location
+  const relativeReportPath = path.relative(consumingAppPath, reportPath);
+  console.log(`${colors.bold}Report saved to:${colors.reset} ${colors.cyan}${relativeReportPath}${colors.reset}\n`);
+  
+  // Exit with error code if issues found
+  process.exit(totalIssues > 0 ? 1 : 0);
+}
+
+// Export for programmatic usage
+module.exports = {
+  runAudit: main,
+  runAllAudits,
+  runStandardAudit: (standardNumber, consumingAppPath) => {
+    const auditFunctions = {
+      '1': runStandard1Audit,
+      '2': runStandard2Audit,
+      '3': runStandard3Audit,
+      '4': runStandard4Audit,
+      '5': runStandard5Audit,
+      '6': runStandard6Audit,
+      '7': runStandard7Audit,
+      '8': runStandard8Audit,
+      '9': runStandard9Audit,
+    };
+    
+    const fn = auditFunctions[standardNumber];
+    if (!fn) {
+      throw new Error(`Invalid standard number: ${standardNumber}. Must be 1-9.`);
+    }
+    
+    return fn(consumingAppPath);
+  },
+};
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}