@jmruthers/pace-core 0.6.6 → 0.6.7

package/audit-tool/index.cjs

@@ -0,0 +1,291 @@
+#!/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 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}`);
+    }
+  });
+  
+  // Display dependency audit
+  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);
+    
+    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}`);
+    }
+  }
+  
+  // 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)));
+  
+  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);
+  
+  // 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();
+}

package/audit-tool/utils/code-utils.cjs

@@ -0,0 +1,218 @@
+/**
+ * Code Analysis Utilities for Audit Tool
+ * @package @jmruthers/pace-core
+ * @module Audit/utils/code-utils
+ */
+
+/**
+ * Get line number from index in content
+ * @param {string} content - File content
+ * @param {number} index - Character index
+ * @returns {number} - Line number (1-indexed)
+ */
+function getLineNumber(content, index) {
+  return content.substring(0, index).split('\n').length;
+}
+
+/**
+ * Get code snippet around a match for context
+ * @param {string} content - File content
+ * @param {number} index - Character index
+ * @param {number} before - Characters before index
+ * @param {number} after - Characters after index
+ * @returns {string} - Code snippet
+ */
+function getCodeSnippet(content, index, before = 30, after = 50) {
+  const start = Math.max(0, index - before);
+  const end = Math.min(content.length, index + after);
+  return content.substring(start, end).trim();
+}
+
+/**
+ * Check if content is in a comment or string (for TypeScript/JavaScript)
+ * @param {string} content - File content
+ * @param {number} index - Character index
+ * @returns {boolean} - True if in comment or string
+ */
+function isInCommentOrString(content, index) {
+  const before = content.substring(0, index);
+  
+  // Check for line comments
+  const lastLineComment = before.lastIndexOf('//');
+  const lastNewline = before.lastIndexOf('\n');
+  if (lastLineComment > lastNewline) {
+    return true;
+  }
+  
+  // Check for block comments
+  const lastBlockCommentStart = before.lastIndexOf('/*');
+  const lastBlockCommentEnd = before.lastIndexOf('*/');
+  if (lastBlockCommentStart > lastBlockCommentEnd) {
+    return true;
+  }
+  
+  // Check for string literals (simple check)
+  const singleQuoteMatches = [...before.matchAll(/'/g)];
+  const doubleQuoteMatches = [...before.matchAll(/"/g)];
+  const backtickMatches = [...before.matchAll(/`/g)];
+  
+  // Simple heuristic: if odd number of quotes before, might be in string
+  const inSingleQuote = singleQuoteMatches.length % 2 === 1;
+  const inDoubleQuote = doubleQuoteMatches.length % 2 === 1;
+  const inBacktick = backtickMatches.length % 2 === 1;
+  
+  return inSingleQuote || inDoubleQuote || inBacktick;
+}
+
+/**
+ * Check if content is in a comment or string (for SQL)
+ * @param {string} content - SQL content
+ * @param {number} index - Character index
+ * @returns {boolean} - True if in comment or string
+ */
+function isInCommentOrStringSQL(content, index) {
+  const before = content.substring(0, index);
+  
+  // Check for SQL line comments
+  const lastLineComment = before.lastIndexOf('--');
+  const lastNewline = before.lastIndexOf('\n');
+  if (lastLineComment > lastNewline && !before.substring(lastLineComment, index).includes('\n')) {
+    return true;
+  }
+  
+  // Check for block comments
+  const lastBlockCommentStart = before.lastIndexOf('/*');
+  const lastBlockCommentEnd = before.lastIndexOf('*/');
+  if (lastBlockCommentStart > lastBlockCommentEnd) {
+    return true;
+  }
+  
+  // Check for string literals (SQL uses single quotes)
+  const singleQuoteMatches = [...before.matchAll(/'/g)];
+  const inSingleQuote = singleQuoteMatches.length % 2 === 1;
+  
+  return inSingleQuote;
+}
+
+/**
+ * Extract import statements from content
+ * @param {string} content - File content
+ * @returns {Array} - Array of import objects { source, specifiers, line }
+ */
+function parseImports(content) {
+  const imports = [];
+  const lines = content.split('\n');
+  
+  lines.forEach((line, index) => {
+    // Match various import patterns
+    const importPatterns = [
+      /^import\s+.*\s+from\s+['"]([^'"]+)['"]/,
+      /^import\s+['"]([^'"]+)['"]/,
+    ];
+    
+    for (const pattern of importPatterns) {
+      const match = line.match(pattern);
+      if (match) {
+        const source = match[1];
+        const specifiers = [];
+        
+        // Try to extract named imports
+        const namedMatch = line.match(/import\s+{([^}]+)}\s+from/);
+        if (namedMatch) {
+          namedMatch[1].split(',').forEach(spec => {
+            const trimmed = spec.trim();
+            if (trimmed) {
+              specifiers.push(trimmed);
+            }
+          });
+        }
+        
+        // Check for default import
+        const defaultMatch = line.match(/import\s+(\w+)\s+from/);
+        if (defaultMatch && !line.includes('{')) {
+          specifiers.push('default');
+        }
+        
+        imports.push({
+          source,
+          specifiers,
+          line: index + 1,
+          fullLine: line.trim(),
+        });
+        break;
+      }
+    }
+  });
+  
+  return imports;
+}
+
+/**
+ * Extract export statements from content
+ * @param {string} content - File content
+ * @returns {Array} - Array of export objects { name, type, line }
+ */
+function parseExports(content) {
+  const exports = [];
+  const lines = content.split('\n');
+  
+  lines.forEach((line, index) => {
+    // Match export patterns
+    const exportPatterns = [
+      /^export\s+(?:function|const|class|interface|type)\s+(\w+)/,
+      /^export\s+default\s+(?:function\s+)?(\w+)?/,
+      /^export\s+{\s*(\w+)/,
+    ];
+    
+    for (const pattern of exportPatterns) {
+      const match = line.match(pattern);
+      if (match) {
+        const name = match[1] || 'default';
+        const type = line.includes('function') ? 'function' :
+                     line.includes('const') ? 'const' :
+                     line.includes('class') ? 'class' :
+                     line.includes('interface') ? 'interface' :
+                     line.includes('type') ? 'type' :
+                     'other';
+        
+        exports.push({
+          name,
+          type,
+          line: index + 1,
+          fullLine: line.trim(),
+        });
+        break;
+      }
+    }
+  });
+  
+  return exports;
+}
+
+/**
+ * Check if file imports from pace-core
+ * @param {string} content - File content
+ * @param {string} name - Component/hook/util name to check
+ * @returns {boolean} - True if imports from pace-core
+ */
+function importsFromPaceCore(content, name) {
+  const patterns = [
+    new RegExp(`import\\s+.*\\b${name}\\b.*from\\s+['"]@jmruthers/pace-core`),
+    new RegExp(`import\\s+.*\\b${name}\\b.*from\\s+['"]@jmruthers/pace-core/components`),
+    new RegExp(`import\\s+.*\\b${name}\\b.*from\\s+['"]@jmruthers/pace-core/hooks`),
+    new RegExp(`import\\s+.*\\b${name}\\b.*from\\s+['"]@jmruthers/pace-core/utils`),
+    new RegExp(`import\\s+.*\\b${name}\\b.*from\\s+['"]@jmruthers/pace-core/rbac`),
+  ];
+  
+  return patterns.some(pattern => pattern.test(content));
+}
+
+module.exports = {
+  getLineNumber,
+  getCodeSnippet,
+  isInCommentOrString,
+  isInCommentOrStringSQL,
+  parseImports,
+  parseExports,
+  importsFromPaceCore,
+};