@jmruthers/pace-core 0.5.193 → 0.6.2

package/scripts/audit/index.cjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+/**
+ * Main Audit Entry Point
+ * @package @jmruthers/pace-core
+ * @module Audit
+ * 
+ * CLI interface for running comprehensive audits
+ */
+
+const path = require('path');
+const Scanner = require('./core/scanner.cjs');
+const { findProjectRoot, getPackageInfo, getPaceCoreVersion, colors } = require('./core/utils.cjs');
+const consoleReporter = require('./reporters/console.cjs');
+const markdownReporter = require('./reporters/markdown.cjs');
+const jsonReporter = require('./reporters/json.cjs');
+
+// Import all checks
+const complianceCheck = require('./core/checks/compliance.cjs');
+const structureCheck = require('./core/checks/structure.cjs');
+const configCheck = require('./core/checks/config.cjs');
+const typescriptCheck = require('./core/checks/typescript.cjs');
+const coverageCheck = require('./core/checks/coverage.cjs');
+const heuristicsCheck = require('./core/checks/heuristics.cjs');
+const importsCheck = require('./core/checks/imports.cjs');
+const hooksCheck = require('./core/checks/hooks.cjs');
+const performanceCheck = require('./core/checks/performance.cjs');
+const dependenciesCheck = require('./core/checks/dependencies.cjs');
+const errorHandlingCheck = require('./core/checks/error-handling.cjs');
+const bundleCheck = require('./core/checks/bundle.cjs');
+const accessibilityCheck = require('./core/checks/accessibility.cjs');
+const styleCheck = require('./core/checks/style.cjs');
+const stateCheck = require('./core/checks/state.cjs');
+const apiUsageCheck = require('./core/checks/api-usage.cjs');
+const documentationCheck = require('./core/checks/documentation.cjs');
+const testingCheck = require('./core/checks/testing.cjs');
+const environmentCheck = require('./core/checks/environment.cjs');
+const routesCheck = require('./core/checks/routes.cjs');
+const formsCheck = require('./core/checks/forms.cjs');
+
+/**
+ * Parse CLI arguments
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    checks: [],
+    exclude: [],
+    reporters: ['console', 'markdown'],
+    verbose: false,
+    json: false
+  };
+  
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    
+    if (arg === '--check' || arg === '-c') {
+      options.checks.push(args[++i]);
+    } else if (arg === '--exclude' || arg === '-e') {
+      options.exclude.push(args[++i]);
+    } else if (arg === '--reporter' || arg === '-r') {
+      options.reporters = [args[++i]];
+    } else if (arg === '--verbose' || arg === '-v') {
+      options.verbose = true;
+    } else if (arg === '--json') {
+      options.json = true;
+      options.reporters = ['json'];
+    } else if (arg === '--help' || arg === '-h') {
+      printHelp();
+      process.exit(0);
+    }
+  }
+  
+  return options;
+}
+
+/**
+ * Print help message
+ */
+function printHelp() {
+  console.log(`
+${colors.bold}pace-core Audit Tool${colors.reset}
+
+Usage: node audit/index.cjs [options]
+
+Options:
+  --check, -c <name>     Run specific check (can be used multiple times)
+  --exclude, -e <name>   Exclude specific check (can be used multiple times)
+  --reporter, -r <name>  Use specific reporter (console, markdown, json)
+  --verbose, -v          Show detailed output
+  --json                 Output JSON only (for CI/CD)
+  --help, -h             Show this help message
+
+Available Checks:
+  - compliance      pace-core compliance checks
+  - structure       File structure checks
+  - config          Config file checks
+  - typescript      TypeScript config checks
+  - coverage        Test coverage checks
+  - heuristics      Code quality heuristics
+  - imports         Import pattern analysis
+  - hooks           React hooks compliance
+  - performance     Performance anti-patterns
+  - dependencies    Dependency analysis
+  - error-handling  Error handling patterns
+  - bundle          Bundle analysis
+  - accessibility   Accessibility checks
+  - style           Code style issues
+  - state           State management patterns
+  - api-usage       API usage patterns
+  - documentation  Documentation coverage
+  - testing         Testing patterns
+  - environment     Environment variable usage
+  - routes          Route protection
+  - forms           Form validation patterns
+
+Examples:
+  node audit/index.cjs
+  node audit/index.cjs --check compliance --check structure
+  node audit/index.cjs --exclude heuristics --reporter markdown
+  node audit/index.cjs --json
+`);
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  const options = parseArgs();
+  const projectRoot = findProjectRoot();
+  const packageJson = getPackageInfo(projectRoot);
+  const paceCoreVersion = getPaceCoreVersion(packageJson);
+  
+  console.log(`${colors.cyan}${colors.bold}═══════════════════════════════════════════════════════════${colors.reset}`);
+  console.log(`${colors.cyan}${colors.bold}  pace-core Comprehensive Audit${colors.reset}`);
+  console.log(`${colors.cyan}${colors.bold}═══════════════════════════════════════════════════════════${colors.reset}\n`);
+  console.log(`${colors.cyan}Project:${colors.reset} ${packageJson?.name || 'Unknown'}`);
+  console.log(`${colors.cyan}Root:${colors.reset} ${projectRoot}`);
+  console.log(`${colors.cyan}pace-core Version:${colors.reset} ${paceCoreVersion}\n`);
+  
+  // Initialize scanner
+  const scanner = new Scanner(projectRoot);
+  
+  // Register all checks
+  scanner.registerChecks([
+    complianceCheck,
+    structureCheck,
+    configCheck,
+    typescriptCheck,
+    coverageCheck,
+    heuristicsCheck,
+    importsCheck,
+    hooksCheck,
+    performanceCheck,
+    dependenciesCheck,
+    errorHandlingCheck,
+    bundleCheck,
+    accessibilityCheck,
+    styleCheck,
+    stateCheck,
+    apiUsageCheck,
+    documentationCheck,
+    testingCheck,
+    environmentCheck,
+    routesCheck,
+    formsCheck
+  ]);
+  
+  // Initialize scanner context
+  await scanner.initialize();
+  
+  // Run checks
+  console.log(`${colors.cyan}Running checks...${colors.reset}\n`);
+  const results = await scanner.run({
+    checkNames: options.checks.length > 0 ? options.checks : null,
+    excludeChecks: options.exclude,
+    parallel: false
+  });
+  
+  // Generate reports
+  const reportOptions = {
+    projectRoot,
+    packageJson,
+    paceCoreVersion,
+    verbose: options.verbose
+  };
+  
+  for (const reporterName of options.reporters) {
+    try {
+      if (reporterName === 'console') {
+        consoleReporter.generateReport(results, reportOptions);
+      } else if (reporterName === 'markdown') {
+        const { filename } = markdownReporter.generateReport(results, reportOptions);
+        console.log(`${colors.green}Markdown report saved to: audit/${filename}${colors.reset}`);
+      } else if (reporterName === 'json') {
+        const outputPath = options.json ? undefined : path.join(projectRoot, 'audit', `audit-${Date.now()}.json`);
+        const jsonOutput = jsonReporter.generateReport(results, { ...reportOptions, outputPath });
+        if (options.json) {
+          console.log(jsonOutput);
+        } else {
+          console.log(`${colors.green}JSON report saved${colors.reset}`);
+        }
+      }
+    } catch (error) {
+      console.error(`${colors.red}Error generating ${reporterName} report: ${error.message}${colors.reset}`);
+    }
+  }
+  
+  // Exit with appropriate code
+  const exitCode = results.summary.errors > 0 ? 1 : 0;
+  process.exit(exitCode);
+}
+
+// Run if called directly
+if (require.main === module) {
+  main().catch(error => {
+    console.error(`${colors.red}Error: ${error.message}${colors.reset}`);
+    console.error(error.stack);
+    process.exit(1);
+  });
+}
+
+module.exports = { main };

package/scripts/audit/reporters/console.cjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+/**
+ * Console Reporter
+ * @package @jmruthers/pace-core
+ * @module Audit/Reporters/Console
+ * 
+ * Formats audit results for terminal output with color coding
+ */
+
+const { colors } = require('../core/utils.cjs');
+
+/**
+ * Format check results for console output
+ */
+function formatCheckResult(checkName, result) {
+  const { issues = [], warnings = [], suggestions = [] } = result;
+  const total = issues.length + warnings.length + suggestions.length;
+  
+  if (total === 0) {
+    return `${colors.green}✓${colors.reset} ${checkName}: No issues found`;
+  }
+  
+  const parts = [];
+  if (issues.length > 0) {
+    parts.push(`${colors.red}${issues.length} error${issues.length !== 1 ? 's' : ''}${colors.reset}`);
+  }
+  if (warnings.length > 0) {
+    parts.push(`${colors.yellow}${warnings.length} warning${warnings.length !== 1 ? 's' : ''}${colors.reset}`);
+  }
+  if (suggestions.length > 0) {
+    parts.push(`${colors.blue}${suggestions.length} suggestion${suggestions.length !== 1 ? 's' : ''}${colors.reset}`);
+  }
+  
+  return `${colors.red}✗${colors.reset} ${checkName}: ${parts.join(', ')}`;
+}
+
+/**
+ * Format a single issue/warning/suggestion for console
+ */
+function formatItem(item, type) {
+  const icon = type === 'issue' ? `${colors.red}•${colors.reset}` : 
+               type === 'warning' ? `${colors.yellow}⚠${colors.reset}` : 
+               `${colors.blue}💡${colors.reset}`;
+  
+  const fileInfo = item.line ? `${colors.yellow}${item.file}:${item.line}${colors.reset}` : `${colors.yellow}${item.file}${colors.reset}`;
+  
+  let output = `  ${icon} ${fileInfo}\n`;
+  output += `    ${item.message || item.type}\n`;
+  
+  if (item.recommendation) {
+    output += `    ${colors.green}Recommendation:${colors.reset} ${item.recommendation}\n`;
+  }
+  
+  return output + '\n';
+}
+
+/**
+ * Generate console report
+ */
+function generateReport(results, options = {}) {
+  const { verbose = false } = options;
+  
+  console.log(`\n${colors.bold}${colors.cyan}═══════════════════════════════════════════════════════════${colors.reset}`);
+  console.log(`${colors.bold}${colors.cyan}  pace-core Audit Report${colors.reset}`);
+  console.log(`${colors.bold}${colors.cyan}═══════════════════════════════════════════════════════════${colors.reset}\n`);
+  
+  // Summary
+  const summary = results.summary || {};
+  console.log(`${colors.bold}Summary:${colors.reset}`);
+  console.log(`  ${colors.red}Errors:${colors.reset} ${summary.errors || 0}`);
+  console.log(`  ${colors.yellow}Warnings:${colors.reset} ${summary.warnings || 0}`);
+  console.log(`  ${colors.blue}Suggestions:${colors.reset} ${summary.suggestions || 0}`);
+  console.log(`  ${colors.green}Passed:${colors.reset} ${summary.passed || 0}`);
+  console.log(`  ${colors.cyan}Total Checks:${colors.reset} ${summary.total || 0}\n`);
+  
+  // Check results
+  if (results.checks) {
+    console.log(`${colors.bold}Check Results:${colors.reset}\n`);
+    Object.entries(results.checks).forEach(([checkName, result]) => {
+      console.log(formatCheckResult(checkName, result));
+      
+      if (verbose && (result.issues?.length > 0 || result.warnings?.length > 0 || result.suggestions?.length > 0)) {
+        if (result.issues?.length > 0) {
+          console.log(`\n  ${colors.red}${colors.bold}Errors:${colors.reset}\n`);
+          result.issues.forEach(issue => {
+            console.log(formatItem(issue, 'issue'));
+          });
+        }
+        
+        if (result.warnings?.length > 0) {
+          console.log(`  ${colors.yellow}${colors.bold}Warnings:${colors.reset}\n`);
+          result.warnings.forEach(warning => {
+            console.log(formatItem(warning, 'warning'));
+          });
+        }
+        
+        if (result.suggestions?.length > 0) {
+          console.log(`  ${colors.blue}${colors.bold}Suggestions:${colors.reset}\n`);
+          result.suggestions.forEach(suggestion => {
+            console.log(formatItem(suggestion, 'suggestion'));
+          });
+        }
+      }
+    });
+  }
+  
+  // Compliance violations (if present)
+  if (results.checks?.compliance?.violations) {
+    const violations = results.checks.compliance.violations;
+    console.log(`\n${colors.bold}${colors.cyan}Compliance Details:${colors.reset}\n`);
+    
+    // Format compliance violations similar to original report
+    formatComplianceViolations(violations);
+  }
+  
+  console.log('');
+}
+
+/**
+ * Format compliance violations for console (similar to original format)
+ */
+function formatComplianceViolations(violations) {
+  const totalRestricted = violations.restrictedImports?.length || 0;
+  const totalDuplicates = 
+    (violations.duplicateComponents?.length || 0) +
+    (violations.duplicateHooks?.length || 0) +
+    (violations.duplicateUtils?.length || 0);
+  
+  if (totalRestricted > 0) {
+    console.log(`${colors.red}${colors.bold}❌ Restricted Imports: ${totalRestricted}${colors.reset}\n`);
+    violations.restrictedImports.forEach(({ module, reason, file, line }) => {
+      console.log(`  ${colors.red}•${colors.reset} ${colors.yellow}${file}:${line}${colors.reset}`);
+      console.log(`    Import: ${colors.cyan}${module}${colors.reset}`);
+      console.log(`    ${colors.yellow}Reason:${colors.reset} ${reason}\n`);
+    });
+  }
+  
+  if (totalDuplicates > 0) {
+    console.log(`${colors.red}${colors.bold}❌ Duplicates: ${totalDuplicates}${colors.reset}\n`);
+    // Format duplicates...
+  }
+  
+  // Format other violation types...
+}
+
+module.exports = {
+  generateReport,
+  formatCheckResult,
+  formatItem
+};

package/scripts/audit/reporters/json.cjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+/**
+ * JSON Reporter
+ * @package @jmruthers/pace-core
+ * @module Audit/Reporters/JSON
+ * 
+ * Generates machine-readable JSON reports for CI/CD integration
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Generate JSON report from audit results
+ */
+function generateReport(results, options = {}) {
+  const { projectRoot, outputPath } = options;
+  
+  // Create simplified JSON structure
+  const jsonReport = {
+    timestamp: new Date().toISOString(),
+    summary: results.summary || {},
+    checks: {},
+    metadata: results.metadata || {}
+  };
+  
+  // Format check results
+  if (results.checks) {
+    Object.entries(results.checks).forEach(([checkName, result]) => {
+      jsonReport.checks[checkName] = {
+        name: checkName,
+        status: result.status || 'completed',
+        duration: result.duration || 0,
+        issues: result.issues || [],
+        warnings: result.warnings || [],
+        suggestions: result.suggestions || []
+      };
+    });
+  }
+  
+  // Write to file or return
+  if (outputPath) {
+    fs.writeFileSync(outputPath, JSON.stringify(jsonReport, null, 2), 'utf8');
+    return { reportPath: outputPath };
+  }
+  
+  // Return JSON string for stdout
+  return JSON.stringify(jsonReport, null, 2);
+}
+
+module.exports = {
+  generateReport
+};

package/scripts/audit/reporters/markdown.cjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+/**
+ * Markdown Reporter
+ * @package @jmruthers/pace-core
+ * @module Audit/Reporters/Markdown
+ * 
+ * Generates timestamped markdown reports
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Generate markdown report from audit results
+ */
+function generateReport(results, options = {}) {
+  const { projectRoot, packageJson, paceCoreVersion } = options;
+  const timestamp = new Date();
+  
+  // Format: yyyymmddhhmmss
+  const timestampStr = timestamp.toISOString().replace(/[-:]/g, '').replace(/\..+/, '').replace('T', '');
+  const filename = `audit-${timestampStr}.md`;
+  const auditDir = path.join(projectRoot, 'audit');
+  
+  // Create audit directory if it doesn't exist
+  if (!fs.existsSync(auditDir)) {
+    fs.mkdirSync(auditDir, { recursive: true });
+  }
+  
+  const reportPath = path.join(auditDir, filename);
+  
+  // Generate markdown content
+  let markdown = `# pace-core Compliance Audit Report\n\n`;
+  markdown += `**Generated:** ${timestamp.toISOString()}\n`;
+  markdown += `**Project:** ${packageJson?.name || 'Unknown'}\n`;
+  markdown += `**pace-core Version:** ${paceCoreVersion || 'unknown'}\n\n`;
+  
+  // Summary
+  const summary = results.summary || {};
+  markdown += `## Executive Summary\n\n`;
+  markdown += `- **Total Issues:** ${summary.errors + summary.warnings + summary.suggestions}\n`;
+  markdown += `- **Errors:** ${summary.errors || 0}\n`;
+  markdown += `- **Warnings:** ${summary.warnings || 0}\n`;
+  markdown += `- **Suggestions:** ${summary.suggestions || 0}\n`;
+  markdown += `- **Passed:** ${summary.passed || 0}\n\n`;
+  
+  // Check results
+  if (results.checks) {
+    Object.entries(results.checks).forEach(([checkName, result]) => {
+      const { issues = [], warnings = [], suggestions = [] } = result;
+      
+      if (issues.length === 0 && warnings.length === 0 && suggestions.length === 0) {
+        markdown += `## ${checkName}\n\n`;
+        markdown += `✅ No issues found\n\n`;
+        return;
+      }
+      
+      markdown += `## ${checkName}\n\n`;
+      
+      if (issues.length > 0) {
+        markdown += `### Errors (${issues.length})\n\n`;
+        issues.forEach(issue => {
+          markdown += `- **${issue.file}${issue.line ? `:${issue.line}` : ''}**\n`;
+          markdown += `  - ${issue.message}\n`;
+          if (issue.recommendation) {
+            markdown += `  - Recommendation: ${issue.recommendation}\n`;
+          }
+          markdown += `\n`;
+        });
+      }
+      
+      if (warnings.length > 0) {
+        markdown += `### Warnings (${warnings.length})\n\n`;
+        warnings.forEach(warning => {
+          markdown += `- **${warning.file}${warning.line ? `:${warning.line}` : ''}**\n`;
+          markdown += `  - ${warning.message}\n`;
+          if (warning.recommendation) {
+            markdown += `  - Recommendation: ${warning.recommendation}\n`;
+          }
+          markdown += `\n`;
+        });
+      }
+      
+      if (suggestions.length > 0) {
+        markdown += `### Suggestions (${suggestions.length})\n\n`;
+        suggestions.forEach(suggestion => {
+          markdown += `- **${suggestion.file}**\n`;
+          markdown += `  - ${suggestion.message}\n`;
+          if (suggestion.recommendation) {
+            markdown += `  - Recommendation: ${suggestion.recommendation}\n`;
+          }
+          markdown += `\n`;
+        });
+      }
+    });
+  }
+  
+  // Compliance violations (if present)
+  if (results.checks?.compliance?.violations) {
+    markdown += formatComplianceViolations(results.checks.compliance.violations);
+  }
+  
+  // Write report
+  fs.writeFileSync(reportPath, markdown, 'utf8');
+  
+  return { reportPath, filename };
+}
+
+/**
+ * Format compliance violations for markdown
+ */
+function formatComplianceViolations(violations) {
+  let markdown = `## Compliance Violations\n\n`;
+  
+  // Add violation details similar to original format
+  // This is a simplified version - can be enhanced
+  
+  return markdown;
+}
+
+module.exports = {
+  generateReport
+};

package/scripts/audit-consuming-app.cjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+/**
+ * Audit Script for Consuming Apps
+ * @package @jmruthers/pace-core
+ * 
+ * This script allows consuming apps to run pace-core audits.
+ * It resolves the audit script path relative to the installed pace-core package
+ * and forwards all arguments to the main audit script.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { spawn } = require('child_process');
+
+// Find the pace-core package directory and audit script
+// This script should be at: node_modules/@jmruthers/pace-core/scripts/audit-consuming-app.cjs
+// The audit script should be at: node_modules/@jmruthers/pace-core/scripts/audit/index.cjs
+
+const scriptDir = __dirname;
+let auditScript;
+
+// Strategy 1: If this script is in scripts/, the audit script is in scripts/audit/
+const relativePath = path.join(scriptDir, 'audit', 'index.cjs');
+if (fs.existsSync(relativePath)) {
+  auditScript = relativePath;
+} else {
+  // Strategy 2: Try to resolve via package.json location
+  try {
+    const packageJsonPath = require.resolve('@jmruthers/pace-core/package.json');
+    const packageDir = path.dirname(packageJsonPath);
+    const resolvedPath = path.join(packageDir, 'scripts', 'audit', 'index.cjs');
+    if (fs.existsSync(resolvedPath)) {
+      auditScript = resolvedPath;
+    }
+  } catch (e) {
+    // Package not found via require.resolve, continue to fallback
+  }
+  
+  // Strategy 3: Fallback - assume we're in scripts/ and go up one level
+  if (!auditScript) {
+    const paceCoreRoot = path.resolve(scriptDir, '..');
+    const fallbackPath = path.join(paceCoreRoot, 'scripts', 'audit', 'index.cjs');
+    if (fs.existsSync(fallbackPath)) {
+      auditScript = fallbackPath;
+    }
+  }
+}
+
+// Verify the audit script exists
+if (!auditScript || !fs.existsSync(auditScript)) {
+  console.error(`Error: Audit script not found.`);
+  console.error(`Searched locations:`);
+  console.error(`  - ${path.join(scriptDir, 'audit', 'index.cjs')}`);
+  try {
+    const packageJsonPath = require.resolve('@jmruthers/pace-core/package.json');
+    const packageDir = path.dirname(packageJsonPath);
+    console.error(`  - ${path.join(packageDir, 'scripts', 'audit', 'index.cjs')}`);
+  } catch (e) {
+    console.error(`  - (Could not resolve package location)`);
+  }
+  console.error(`\nThis may indicate:`);
+  console.error(`  1. The pace-core package is not installed correctly`);
+  console.error(`  2. The package needs to be updated (npm install @jmruthers/pace-core@latest)`);
+  console.error(`  3. The scripts directory was not included in the published package`);
+  process.exit(1);
+}
+
+// Forward all command line arguments to the audit script
+const args = process.argv.slice(2);
+
+// Spawn the audit script with forwarded arguments
+const child = spawn('node', [auditScript, ...args], {
+  stdio: 'inherit',
+  cwd: process.cwd() // Use the consuming app's working directory
+});
+
+child.on('error', (error) => {
+  console.error(`Error running audit script: ${error.message}`);
+  process.exit(1);
+});
+
+child.on('exit', (code) => {
+  process.exit(code || 0);
+});
+