@jmruthers/pace-core 0.5.191 → 0.6.1

package/scripts/audit-consuming-app.cjs

@@ -0,0 +1,961 @@
+#!/usr/bin/env node
+
+/**
+ * Comprehensive Audit Tool for Consuming Apps
+ * @package @jmruthers/pace-core
+ * @module Scripts/audit-consuming-app
+ * 
+ * Performs comprehensive audit of consuming app including:
+ * - Phase 1: Deterministic checks (file structure, configs, coverage)
+ * - Phase 2: Heuristic checks (SOLID principles, code complexity)
+ * - Standards compliance
+ * - Testing compliance
+ * - Code quality metrics
+ * 
+ * Generates timestamped markdown report in audit/ directory.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Import existing compliance checker
+let complianceChecker;
+try {
+  complianceChecker = require('./check-pace-core-compliance.cjs');
+} catch (error) {
+  console.error('Error loading compliance checker:', error.message);
+  process.exit(1);
+}
+
+// Run compliance check and get results
+function runComplianceCheck(projectRoot) {
+  const manifest = complianceChecker.loadManifest();
+  const files = complianceChecker.findSourceFiles(projectRoot, []);
+  
+  console.log(`  Scanning ${files.length} files for compliance issues...`);
+  
+  // Scan all files
+  const allViolations = {
+    restrictedImports: [],
+    duplicateComponents: [],
+    duplicateHooks: [],
+    duplicateUtils: [],
+    suggestions: [],
+    customAuthCode: [],
+    duplicateConfig: [],
+    unprotectedPages: [],
+    directSupabaseAuth: [],
+    providerSetupIssues: [],
+    viteConfigIssues: [],
+    routerSetupIssues: [],
+    unnecessaryWrappers: [],
+    appDiscoveryIssues: []
+  };
+  
+  let scanned = 0;
+  files.forEach(file => {
+    try {
+      const violations = complianceChecker.scanFile(file, manifest);
+      allViolations.restrictedImports.push(...violations.restrictedImports);
+      allViolations.duplicateComponents.push(...violations.duplicateComponents);
+      allViolations.duplicateHooks.push(...violations.duplicateHooks);
+      allViolations.duplicateUtils.push(...violations.duplicateUtils);
+      allViolations.suggestions.push(...violations.suggestions);
+      allViolations.customAuthCode.push(...violations.customAuthCode);
+      allViolations.duplicateConfig.push(...violations.duplicateConfig);
+      allViolations.unprotectedPages.push(...violations.unprotectedPages);
+      allViolations.directSupabaseAuth.push(...violations.directSupabaseAuth);
+      allViolations.providerSetupIssues.push(...violations.providerSetupIssues);
+      allViolations.viteConfigIssues.push(...violations.viteConfigIssues);
+      allViolations.routerSetupIssues.push(...violations.routerSetupIssues);
+      allViolations.unnecessaryWrappers.push(...violations.unnecessaryWrappers);
+      allViolations.appDiscoveryIssues.push(...violations.appDiscoveryIssues);
+      scanned++;
+      if (scanned % 50 === 0) {
+        process.stdout.write(`  Scanned ${scanned}/${files.length} files...\r`);
+      }
+    } catch (error) {
+      // Skip files with errors
+      scanned++;
+    }
+  });
+  
+  if (scanned > 0) {
+    process.stdout.write(`  Scanned ${scanned}/${files.length} files...\n`);
+  }
+  
+  return allViolations;
+}
+
+// Convert compliance violations to markdown
+function complianceViolationsToMarkdown(allViolations) {
+  let markdown = '';
+  
+  const totalRestricted = allViolations.restrictedImports.length;
+  const totalDuplicates = 
+    allViolations.duplicateComponents.length +
+    allViolations.duplicateHooks.length +
+    allViolations.duplicateUtils.length;
+  const totalSuggestions = allViolations.suggestions.length;
+  const totalRbacAuth = 
+    allViolations.customAuthCode.length +
+    allViolations.duplicateConfig.length +
+    allViolations.unprotectedPages.length +
+    allViolations.directSupabaseAuth.length;
+  const totalSetupIssues = 
+    allViolations.providerSetupIssues.length +
+    allViolations.viteConfigIssues.length +
+    allViolations.routerSetupIssues.length;
+  const totalUnnecessaryWrappers = allViolations.unnecessaryWrappers.length;
+  const totalAppDiscovery = allViolations.appDiscoveryIssues.length;
+  const totalIssues = totalRestricted + totalDuplicates + totalSuggestions + totalRbacAuth + totalSetupIssues + totalUnnecessaryWrappers + totalAppDiscovery;
+  
+  markdown += `### Summary\n\n`;
+  markdown += `- **Total Issues:** ${totalIssues}\n`;
+  markdown += `- **Restricted Imports:** ${totalRestricted}\n`;
+  markdown += `- **Duplicate Components/Hooks/Utils:** ${totalDuplicates}\n`;
+  markdown += `- **RBAC/Auth Issues:** ${totalRbacAuth}\n`;
+  markdown += `- **Setup Issues:** ${totalSetupIssues}\n`;
+  markdown += `- **Unnecessary Wrappers:** ${totalUnnecessaryWrappers}\n`;
+  markdown += `- **App Discovery Issues:** ${totalAppDiscovery}\n`;
+  markdown += `- **Suggestions:** ${totalSuggestions}\n\n`;
+  
+  // Restricted Imports
+  if (totalRestricted > 0) {
+    markdown += `#### ❌ Restricted Imports (${totalRestricted})\n\n`;
+    allViolations.restrictedImports.forEach(({ module, reason, file, line }) => {
+      markdown += `- **${file}:${line}**\n`;
+      markdown += `  - Import: \`${module}\`\n`;
+      markdown += `  - Reason: ${reason}\n\n`;
+    });
+  } else {
+    markdown += `#### ✅ No Restricted Imports\n\n`;
+  }
+  
+  // Duplicate Components
+  if (allViolations.duplicateComponents.length > 0) {
+    markdown += `#### ❌ Duplicate Components (${allViolations.duplicateComponents.length})\n\n`;
+    allViolations.duplicateComponents.forEach(({ component, file }) => {
+      markdown += `- **${file}**\n`;
+      markdown += `  - Component \`${component}\` conflicts with pace-core component\n`;
+      markdown += `  - Suggestion: Use \`${component}\` from '@jmruthers/pace-core' instead\n\n`;
+    });
+  }
+  
+  // Duplicate Hooks
+  if (allViolations.duplicateHooks.length > 0) {
+    markdown += `#### ❌ Duplicate Hooks (${allViolations.duplicateHooks.length})\n\n`;
+    allViolations.duplicateHooks.forEach(({ hook, file }) => {
+      markdown += `- **${file}**\n`;
+      markdown += `  - Hook \`${hook}\` conflicts with pace-core hook\n`;
+      markdown += `  - Suggestion: Use \`${hook}\` from '@jmruthers/pace-core' instead\n\n`;
+    });
+  }
+  
+  // Duplicate Utils
+  if (allViolations.duplicateUtils.length > 0) {
+    markdown += `#### ❌ Duplicate Utils (${allViolations.duplicateUtils.length})\n\n`;
+    allViolations.duplicateUtils.forEach(({ util, file }) => {
+      markdown += `- **${file}**\n`;
+      markdown += `  - Util \`${util}\` conflicts with pace-core util\n`;
+      markdown += `  - Suggestion: Use \`${util}\` from '@jmruthers/pace-core' instead\n\n`;
+    });
+  }
+  
+  // Unnecessary Wrappers
+  if (totalUnnecessaryWrappers > 0) {
+    markdown += `#### ⚠️ Unnecessary Wrappers (${totalUnnecessaryWrappers})\n\n`;
+    allViolations.unnecessaryWrappers.forEach(({ component, wrappedComponent, file, line, reason, recommendation }) => {
+      markdown += `- **${file}:${line}**\n`;
+      markdown += `  - Component: \`${component}\`\n`;
+      markdown += `  - Wraps: \`${wrappedComponent}\`\n`;
+      markdown += `  - Issue: ${reason}\n`;
+      if (recommendation) {
+        markdown += `  - Recommendation: ${recommendation}\n\n`;
+      } else {
+        markdown += `  - Recommendation: Remove the wrapper and use the component directly.\n\n`;
+      }
+    });
+  }
+  
+  // Custom Auth/RBAC Code
+  if (allViolations.customAuthCode.length > 0) {
+    // Separate by severity
+    const errors = allViolations.customAuthCode.filter(v => !v.severity || v.severity === 'error');
+    const warnings = allViolations.customAuthCode.filter(v => v.severity === 'warning');
+    
+    if (errors.length > 0) {
+      markdown += `#### ❌ Custom Auth/RBAC Code (${errors.length})\n\n`;
+      errors.forEach(({ name, type, file, line, reason, replacement, example }) => {
+        markdown += `- **${file}:${line}**\n`;
+        markdown += `  - ${type}: \`${name}\`\n`;
+        markdown += `  - Reason: ${reason}\n`;
+        if (replacement) {
+          markdown += `  - Fix: ${replacement}\n`;
+        }
+        if (example) {
+          markdown += `  - Example:\n\`\`\`typescript\n${example}\n\`\`\`\n`;
+        }
+        markdown += `\n`;
+      });
+    }
+    
+    if (warnings.length > 0) {
+      markdown += `#### ⚠️ Custom Auth/RBAC Warnings (${warnings.length})\n\n`;
+      warnings.forEach(({ name, type, file, line, reason, replacement, example }) => {
+        markdown += `- **${file}:${line}**\n`;
+        markdown += `  - ${type}: \`${name}\`\n`;
+        markdown += `  - Note: ${reason}\n`;
+        if (replacement) {
+          markdown += `  - Recommendation: ${replacement}\n`;
+        }
+        if (example) {
+          markdown += `  - Example:\n\`\`\`typescript\n${example}\n\`\`\`\n`;
+        }
+        markdown += `\n`;
+      });
+    }
+  }
+  
+  // Duplicate Configurations
+  if (allViolations.duplicateConfig.length > 0) {
+    markdown += `#### ❌ Duplicate Configurations (${allViolations.duplicateConfig.length})\n\n`;
+    allViolations.duplicateConfig.forEach(({ type, file, count, reason }) => {
+      markdown += `- **${file}**\n`;
+      markdown += `  - Type: \`${type}\`${count ? ` (${count} instances)` : ''}\n`;
+      markdown += `  - Reason: ${reason}\n\n`;
+    });
+  }
+  
+  // Provider Setup Issues
+  if (allViolations.providerSetupIssues.length > 0) {
+    markdown += `#### ❌ Provider Setup Issues (${allViolations.providerSetupIssues.length})\n\n`;
+    allViolations.providerSetupIssues.forEach(({ issue, file, line, recommendation }) => {
+      markdown += `- **${file}:${line}**\n`;
+      markdown += `  - Issue: ${issue}\n`;
+      if (recommendation) {
+        markdown += `  - Recommendation: ${recommendation}\n\n`;
+      }
+    });
+  }
+  
+  // Vite Config Issues
+  if (allViolations.viteConfigIssues.length > 0) {
+    markdown += `#### ❌ Vite Config Issues (${allViolations.viteConfigIssues.length})\n\n`;
+    allViolations.viteConfigIssues.forEach(({ issue, file, line, recommendation }) => {
+      markdown += `- **${file}:${line}**\n`;
+      markdown += `  - Issue: ${issue}\n`;
+      if (recommendation) {
+        markdown += `  - Recommendation: ${recommendation}\n\n`;
+      }
+    });
+  }
+  
+  // Router Setup Issues
+  if (allViolations.routerSetupIssues.length > 0) {
+    markdown += `#### ❌ Router Setup Issues (${allViolations.routerSetupIssues.length})\n\n`;
+    allViolations.routerSetupIssues.forEach(({ issue, file, line, recommendation }) => {
+      markdown += `- **${file}:${line}**\n`;
+      markdown += `  - Issue: ${issue}\n`;
+      if (recommendation) {
+        markdown += `  - Recommendation: ${recommendation}\n\n`;
+      }
+    });
+  }
+  
+  // Unprotected Pages
+  if (allViolations.unprotectedPages.length > 0) {
+    markdown += `#### ❌ Unprotected Pages (${allViolations.unprotectedPages.length})\n\n`;
+    allViolations.unprotectedPages.forEach(({ page, file, recommendation }) => {
+      markdown += `- **${file}**\n`;
+      markdown += `  - Page: ${page}\n`;
+      if (recommendation) {
+        markdown += `  - Recommendation: ${recommendation}\n\n`;
+      }
+    });
+  }
+  
+  // Direct Supabase Auth
+  if (allViolations.directSupabaseAuth.length > 0) {
+    markdown += `#### ❌ Direct Supabase Auth Usage (${allViolations.directSupabaseAuth.length})\n\n`;
+    allViolations.directSupabaseAuth.forEach(({ file, line, recommendation }) => {
+      markdown += `- **${file}:${line}**\n`;
+      if (recommendation) {
+        markdown += `  - Recommendation: ${recommendation}\n\n`;
+      }
+    });
+  }
+  
+  // App Discovery Issues
+  if (totalAppDiscovery > 0) {
+    markdown += `#### ⚠️ App Discovery Issues (${totalAppDiscovery})\n\n`;
+    allViolations.appDiscoveryIssues.forEach(({ issue, file, recommendation }) => {
+      markdown += `- **${file}**\n`;
+      markdown += `  - Issue: ${issue}\n`;
+      if (recommendation) {
+        markdown += `  - Recommendation: ${recommendation}\n\n`;
+      }
+    });
+  }
+  
+  // Suggestions
+  if (totalSuggestions > 0) {
+    markdown += `#### 💡 Suggestions (${totalSuggestions})\n\n`;
+    const grouped = {};
+    allViolations.suggestions.forEach(s => {
+      if (!grouped[s.file]) grouped[s.file] = [];
+      grouped[s.file].push(s);
+    });
+    Object.entries(grouped).forEach(([file, suggestions]) => {
+      markdown += `- **${file}**\n`;
+      suggestions.forEach(s => {
+        markdown += `  - ${s.suggestion}\n`;
+      });
+      markdown += `\n`;
+    });
+  }
+  
+  if (totalIssues === 0) {
+    markdown += `✅ **Excellent!** No compliance issues found.\n\n`;
+  }
+  
+  return markdown;
+}
+
+// ANSI color codes
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m'
+};
+
+// Find project root
+function findProjectRoot() {
+  let current = path.resolve(process.cwd());
+  while (current !== path.dirname(current)) {
+    if (fs.existsSync(path.join(current, 'package.json'))) {
+      return current;
+    }
+    current = path.dirname(current);
+  }
+  return process.cwd();
+}
+
+// Get package.json info
+function getPackageInfo(projectRoot) {
+  const packagePath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(packagePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+  } catch (error) {
+    return null;
+  }
+}
+
+// Get pace-core version
+function getPaceCoreVersion(packageJson) {
+  const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+  return deps['@jmruthers/pace-core'] || 'unknown';
+}
+
+// Phase 1: Deterministic Checks
+
+// Check file structure
+function checkFileStructure(projectRoot) {
+  const issues = [];
+  const warnings = [];
+  
+  const requiredDirs = ['src'];
+  const recommendedDirs = ['src/components', 'src/hooks', 'src/utils', 'src/pages'];
+  
+  requiredDirs.forEach(dir => {
+    const dirPath = path.join(projectRoot, dir);
+    if (!fs.existsSync(dirPath)) {
+      issues.push({
+        type: 'missing-directory',
+        directory: dir,
+        severity: 'error',
+        message: `Required directory '${dir}' is missing`
+      });
+    }
+  });
+  
+  recommendedDirs.forEach(dir => {
+    const dirPath = path.join(projectRoot, dir);
+    if (!fs.existsSync(dirPath)) {
+      warnings.push({
+        type: 'missing-directory',
+        directory: dir,
+        severity: 'warning',
+        message: `Recommended directory '${dir}' is missing`
+      });
+    }
+  });
+  
+  return { issues, warnings };
+}
+
+// Check config files
+function checkConfigFiles(projectRoot) {
+  const issues = [];
+  const warnings = [];
+  
+  const requiredConfigs = [
+    { file: 'package.json', severity: 'error' },
+    { file: 'tsconfig.json', severity: 'error' },
+    { file: 'vite.config.ts', severity: 'warning' },
+    { file: 'vitest.config.ts', severity: 'warning' }
+  ];
+  
+  requiredConfigs.forEach(({ file, severity }) => {
+    const filePath = path.join(projectRoot, file);
+    if (!fs.existsSync(filePath)) {
+      if (severity === 'error') {
+        issues.push({
+          type: 'missing-config',
+          file,
+          severity,
+          message: `Required config file '${file}' is missing`
+        });
+      } else {
+        warnings.push({
+          type: 'missing-config',
+          file,
+          severity,
+          message: `Recommended config file '${file}' is missing`
+        });
+      }
+    }
+  });
+  
+  return { issues, warnings };
+}
+
+// Check TypeScript strict mode
+function checkTypeScriptConfig(projectRoot) {
+  const issues = [];
+  const warnings = [];
+  
+  const tsconfigPath = path.join(projectRoot, 'tsconfig.json');
+  if (!fs.existsSync(tsconfigPath)) {
+    return { issues, warnings };
+  }
+  
+  try {
+    const tsconfig = JSON.parse(fs.readFileSync(tsconfigPath, 'utf8'));
+    const compilerOptions = tsconfig.compilerOptions || {};
+    
+    if (!compilerOptions.strict) {
+      issues.push({
+        type: 'typescript-config',
+        severity: 'error',
+        message: 'TypeScript strict mode is not enabled',
+        recommendation: 'Set "strict": true in tsconfig.json'
+      });
+    }
+    
+    if (compilerOptions.noImplicitAny === false) {
+      issues.push({
+        type: 'typescript-config',
+        severity: 'error',
+        message: 'noImplicitAny is disabled',
+        recommendation: 'Set "noImplicitAny": true in tsconfig.json'
+      });
+    }
+  } catch (error) {
+    warnings.push({
+      type: 'typescript-config',
+      severity: 'warning',
+      message: `Could not parse tsconfig.json: ${error.message}`
+    });
+  }
+  
+  return { issues, warnings };
+}
+
+// Check test coverage
+function checkTestCoverage(projectRoot) {
+  const issues = [];
+  const warnings = [];
+  
+  // Try to find coverage report
+  const coveragePaths = [
+    path.join(projectRoot, 'coverage', 'coverage-summary.json'),
+    path.join(projectRoot, 'coverage', 'coverage-final.json')
+  ];
+  
+  let coverageData = null;
+  for (const coveragePath of coveragePaths) {
+    if (fs.existsSync(coveragePath)) {
+      try {
+        coverageData = JSON.parse(fs.readFileSync(coveragePath, 'utf8'));
+        break;
+      } catch (error) {
+        // Continue to next path
+      }
+    }
+  }
+  
+  if (!coverageData) {
+    warnings.push({
+      type: 'coverage',
+      severity: 'warning',
+      message: 'No coverage report found. Run tests with coverage to get accurate metrics.'
+    });
+    return { issues, warnings };
+  }
+  
+  // Check coverage thresholds
+  const total = coverageData.total || {};
+  const lines = total.lines?.pct || 0;
+  const functions = total.functions?.pct || 0;
+  const branches = total.branches?.pct || 0;
+  const statements = total.statements?.pct || 0;
+  
+  if (lines < 70) {
+    warnings.push({
+      type: 'coverage',
+      severity: 'warning',
+      message: `Line coverage is ${lines.toFixed(1)}%, below recommended 70%`
+    });
+  }
+  
+  if (functions < 70) {
+    warnings.push({
+      type: 'coverage',
+      severity: 'warning',
+      message: `Function coverage is ${functions.toFixed(1)}%, below recommended 70%`
+    });
+  }
+  
+  return { issues, warnings, metrics: { lines, functions, branches, statements } };
+}
+
+// Phase 2: Heuristic Checks
+
+// Check for large files
+function checkLargeFiles(projectRoot) {
+  const suggestions = [];
+  const maxLines = 500;
+  
+  function scanDirectory(dir, relativePath = '') {
+    const items = fs.readdirSync(dir);
+    
+    items.forEach(item => {
+      const fullPath = path.join(dir, item);
+      const stat = fs.statSync(fullPath);
+      
+      if (stat.isDirectory() && !item.startsWith('.') && item !== 'node_modules' && item !== 'dist') {
+        scanDirectory(fullPath, path.join(relativePath, item));
+      } else if (stat.isFile() && /\.(ts|tsx|js|jsx)$/.test(item)) {
+        const content = fs.readFileSync(fullPath, 'utf8');
+        const lines = content.split('\n').length;
+        
+        if (lines > maxLines) {
+          suggestions.push({
+            type: 'large-file',
+            file: path.join(relativePath, item),
+            lines,
+            severity: 'suggestion',
+            message: `File has ${lines} lines, consider splitting into smaller modules`
+          });
+        }
+      }
+    });
+  }
+  
+  const srcPath = path.join(projectRoot, 'src');
+  if (fs.existsSync(srcPath)) {
+    scanDirectory(srcPath, 'src');
+  }
+  
+  return suggestions;
+}
+
+// Check for god objects (heuristic)
+function checkGodObjects(projectRoot) {
+  const suggestions = [];
+  
+  // This is a simplified heuristic - in practice, you'd use AST parsing
+  function scanFile(filePath, relativePath) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      
+      // Heuristic: Files with many exports might be god objects
+      const exportCount = (content.match(/export\s+(const|function|class|interface|type)/g) || []).length;
+      
+      if (exportCount > 10) {
+        suggestions.push({
+          type: 'god-object',
+          file: relativePath,
+          exportCount,
+          severity: 'suggestion',
+          message: `File exports ${exportCount} items, consider splitting into smaller modules`
+        });
+      }
+    } catch (error) {
+      // Skip files we can't read
+    }
+  }
+  
+  function scanDirectory(dir, relativePath = '') {
+    const items = fs.readdirSync(dir);
+    
+    items.forEach(item => {
+      const fullPath = path.join(dir, item);
+      const stat = fs.statSync(fullPath);
+      
+      if (stat.isDirectory() && !item.startsWith('.') && item !== 'node_modules' && item !== 'dist') {
+        scanDirectory(fullPath, path.join(relativePath, item));
+      } else if (stat.isFile() && /\.(ts|tsx|js|jsx)$/.test(item)) {
+        scanFile(fullPath, path.join(relativePath, item));
+      }
+    });
+  }
+  
+  const srcPath = path.join(projectRoot, 'src');
+  if (fs.existsSync(srcPath)) {
+    scanDirectory(srcPath, 'src');
+  }
+  
+  return suggestions;
+}
+
+// Generate markdown report
+function generateMarkdownReport(auditResults, projectRoot, packageJson, paceCoreVersion) {
+  const timestamp = new Date();
+  // Format: yyyymmddhhmmss
+  const year = timestamp.getFullYear();
+  const month = String(timestamp.getMonth() + 1).padStart(2, '0');
+  const day = String(timestamp.getDate()).padStart(2, '0');
+  const hours = String(timestamp.getHours()).padStart(2, '0');
+  const minutes = String(timestamp.getMinutes()).padStart(2, '0');
+  const seconds = String(timestamp.getSeconds()).padStart(2, '0');
+  const timestampStr = `${year}${month}${day}${hours}${minutes}${seconds}`;
+  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);
+  
+  // Calculate totals
+  const phase1Errors = auditResults.phase1.issues.length;
+  const phase1Warnings = auditResults.phase1.warnings.length;
+  const phase2Suggestions = auditResults.phase2.suggestions.length;
+  
+  // Calculate compliance issues
+  const complianceIssues = auditResults.compliance 
+    ? (auditResults.compliance.customAuthCode.length + 
+       auditResults.compliance.restrictedImports.length + 
+       auditResults.compliance.duplicateComponents.length + 
+       auditResults.compliance.duplicateHooks.length + 
+       auditResults.compliance.duplicateUtils.length +
+       auditResults.compliance.unprotectedPages.length +
+       auditResults.compliance.directSupabaseAuth.length +
+       auditResults.compliance.providerSetupIssues.length +
+       auditResults.compliance.viteConfigIssues.length +
+       auditResults.compliance.routerSetupIssues.length +
+       auditResults.compliance.duplicateConfig.length)
+    : 0;
+  
+  const totalIssues = phase1Errors + phase1Warnings + phase2Suggestions + complianceIssues;
+  
+  // Calculate compliance score (0-100)
+  const maxIssues = 100; // Arbitrary max for scoring
+  const complianceScore = Math.max(0, 100 - Math.min(100, (totalIssues / maxIssues) * 100));
+  
+  // Generate markdown
+  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}\n`;
+  markdown += `**Audit Tool Version:** 1.0.0\n\n`;
+  
+  markdown += `## Executive Summary\n\n`;
+  markdown += `- **Total Issues:** ${totalIssues}\n`;
+  markdown += `- **Critical Failures:** ${phase1Errors} (Phase 1 - Must Fix)\n`;
+  markdown += `- **Warnings:** ${phase1Warnings} (Phase 1 - Should Fix)\n`;
+  markdown += `- **Suggestions:** ${phase2Suggestions} (Phase 2 - Consider)\n`;
+  markdown += `- **Compliance Issues:** ${complianceIssues} (pace-core Compliance Check)\n`;
+  markdown += `- **Compliance Score:** ${complianceScore.toFixed(1)}%\n\n`;
+  
+  // Phase 1: Deterministic Checks
+  markdown += `## Phase 1: Deterministic Checks\n\n`;
+  
+  // File Structure
+  if (auditResults.phase1.fileStructure.issues.length > 0 || auditResults.phase1.fileStructure.warnings.length > 0) {
+    markdown += `### File Structure\n\n`;
+    auditResults.phase1.fileStructure.issues.forEach(issue => {
+      markdown += `- [ ] ❌ **${issue.directory}**: ${issue.message}\n`;
+    });
+    auditResults.phase1.fileStructure.warnings.forEach(warning => {
+      markdown += `- [ ] ⚠️ **${warning.directory}**: ${warning.message}\n`;
+    });
+    markdown += `\n`;
+  } else {
+    markdown += `### File Structure\n\n`;
+    markdown += `- [x] ✅ All required directories present\n\n`;
+  }
+  
+  // Config Files
+  if (auditResults.phase1.configFiles.issues.length > 0 || auditResults.phase1.configFiles.warnings.length > 0) {
+    markdown += `### Config Files\n\n`;
+    auditResults.phase1.configFiles.issues.forEach(issue => {
+      markdown += `- [ ] ❌ **${issue.file}**: ${issue.message}\n`;
+    });
+    auditResults.phase1.configFiles.warnings.forEach(warning => {
+      markdown += `- [ ] ⚠️ **${warning.file}**: ${warning.message}\n`;
+    });
+    markdown += `\n`;
+  } else {
+    markdown += `### Config Files\n\n`;
+    markdown += `- [x] ✅ All required config files present\n\n`;
+  }
+  
+  // TypeScript Config
+  if (auditResults.phase1.typescript.issues.length > 0 || auditResults.phase1.typescript.warnings.length > 0) {
+    markdown += `### TypeScript Configuration\n\n`;
+    auditResults.phase1.typescript.issues.forEach(issue => {
+      markdown += `- [ ] ❌ ${issue.message}\n`;
+      if (issue.recommendation) {
+        markdown += `  - Recommendation: ${issue.recommendation}\n`;
+      }
+    });
+    auditResults.phase1.typescript.warnings.forEach(warning => {
+      markdown += `- [ ] ⚠️ ${warning.message}\n`;
+    });
+    markdown += `\n`;
+  } else {
+    markdown += `### TypeScript Configuration\n\n`;
+    markdown += `- [x] ✅ TypeScript strict mode enabled\n\n`;
+  }
+  
+  // Test Coverage
+  if (auditResults.phase1.coverage.warnings.length > 0) {
+    markdown += `### Test Coverage\n\n`;
+    if (auditResults.phase1.coverage.metrics) {
+      const m = auditResults.phase1.coverage.metrics;
+      markdown += `**Current Coverage:**\n`;
+      markdown += `- Lines: ${m.lines.toFixed(1)}%\n`;
+      markdown += `- Functions: ${m.functions.toFixed(1)}%\n`;
+      markdown += `- Branches: ${m.branches.toFixed(1)}%\n`;
+      markdown += `- Statements: ${m.statements.toFixed(1)}%\n\n`;
+    }
+    auditResults.phase1.coverage.warnings.forEach(warning => {
+      markdown += `- [ ] ⚠️ ${warning.message}\n`;
+    });
+    markdown += `\n`;
+  } else if (auditResults.phase1.coverage.metrics) {
+    markdown += `### Test Coverage\n\n`;
+    const m = auditResults.phase1.coverage.metrics;
+    markdown += `- [x] ✅ Coverage meets requirements\n`;
+    markdown += `  - Lines: ${m.lines.toFixed(1)}%\n`;
+    markdown += `  - Functions: ${m.functions.toFixed(1)}%\n`;
+    markdown += `  - Branches: ${m.branches.toFixed(1)}%\n`;
+    markdown += `  - Statements: ${m.statements.toFixed(1)}%\n\n`;
+  }
+  
+  // Phase 2: Heuristic Checks
+  markdown += `## Phase 2: Heuristic Checks (Suggestions)\n\n`;
+  
+  if (auditResults.phase2.suggestions.length === 0) {
+    markdown += `- ✅ No suggestions at this time\n\n`;
+  } else {
+    // Group by type
+    const byType = {};
+    auditResults.phase2.suggestions.forEach(suggestion => {
+      if (!byType[suggestion.type]) {
+        byType[suggestion.type] = [];
+      }
+      byType[suggestion.type].push(suggestion);
+    });
+    
+    Object.entries(byType).forEach(([type, suggestions]) => {
+      const typeName = type.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+      markdown += `### ${typeName}\n\n`;
+      suggestions.forEach(suggestion => {
+        markdown += `- 💡 **${suggestion.file}**: ${suggestion.message}\n`;
+        if (suggestion.lines) {
+          markdown += `  - Lines: ${suggestion.lines}\n`;
+        }
+        if (suggestion.exportCount) {
+          markdown += `  - Exports: ${suggestion.exportCount}\n`;
+        }
+      });
+      markdown += `\n`;
+    });
+  }
+  
+  // Compliance Check Results
+  markdown += `## pace-core Compliance Check\n\n`;
+  if (auditResults.compliance) {
+    markdown += complianceViolationsToMarkdown(auditResults.compliance);
+  } else {
+    markdown += `⚠️ Compliance check was not run. Run the audit script to include compliance results.\n\n`;
+  }
+  
+  // Recommendations
+  markdown += `## Recommendations\n\n`;
+  
+  if (phase1Errors > 0) {
+    markdown += `### Must Fix (Phase 1 Failures)\n\n`;
+    auditResults.phase1.issues.forEach(issue => {
+      markdown += `1. **Priority: High** - ${issue.message || issue.type}\n`;
+      if (issue.recommendation) {
+        markdown += `   - ${issue.recommendation}\n`;
+      }
+    });
+    markdown += `\n`;
+  }
+  
+  if (phase1Warnings > 0) {
+    markdown += `### Should Fix (Phase 1 Warnings)\n\n`;
+    auditResults.phase1.warnings.forEach(warning => {
+      markdown += `1. **Priority: Medium** - ${warning.message || warning.type}\n`;
+      if (warning.recommendation) {
+        markdown += `   - ${warning.recommendation}\n`;
+      }
+    });
+    markdown += `\n`;
+  }
+  
+  if (phase2Suggestions > 0) {
+    markdown += `### Consider (Phase 2 Suggestions)\n\n`;
+    auditResults.phase2.suggestions.slice(0, 10).forEach(suggestion => {
+      markdown += `1. **Priority: Low** - ${suggestion.message}\n`;
+      markdown += `   - File: ${suggestion.file}\n`;
+    });
+    if (phase2Suggestions > 10) {
+      markdown += `\n*... and ${phase2Suggestions - 10} more suggestions*\n`;
+    }
+    markdown += `\n`;
+  }
+  
+  if (totalIssues === 0) {
+    markdown += `✅ **Excellent!** No issues found. Your codebase is fully compliant.\n\n`;
+  }
+  
+  // Write report
+  fs.writeFileSync(reportPath, markdown, 'utf8');
+  
+  return { reportPath, filename };
+}
+
+// Main function
+function main() {
+  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`);
+  
+  // Note: We don't call complianceChecker.main() because it calls process.exit()
+  // The compliance check output you see is from a previous run or separate execution
+  // We'll continue with Phase 1 and Phase 2 checks and generate markdown report
+  
+  // Phase 1: Deterministic Checks
+  console.log(`\n${colors.cyan}Phase 1: Running deterministic checks...${colors.reset}`);
+  const fileStructure = checkFileStructure(projectRoot);
+  const configFiles = checkConfigFiles(projectRoot);
+  const typescript = checkTypeScriptConfig(projectRoot);
+  const coverage = checkTestCoverage(projectRoot);
+  
+  const phase1 = {
+    issues: [
+      ...fileStructure.issues,
+      ...configFiles.issues,
+      ...typescript.issues,
+      ...coverage.issues
+    ],
+    warnings: [
+      ...fileStructure.warnings,
+      ...configFiles.warnings,
+      ...typescript.warnings,
+      ...coverage.warnings
+    ],
+    fileStructure,
+    configFiles,
+    typescript,
+    coverage
+  };
+  
+  // Phase 2: Heuristic Checks
+  console.log(`${colors.cyan}Phase 2: Running heuristic checks...${colors.reset}`);
+  const largeFiles = checkLargeFiles(projectRoot);
+  const godObjects = checkGodObjects(projectRoot);
+  
+  const phase2 = {
+    suggestions: [
+      ...largeFiles,
+      ...godObjects
+    ]
+  };
+  
+  // Compliance Check
+  console.log(`${colors.cyan}Running pace-core compliance check...${colors.reset}`);
+  let complianceResults = null;
+  try {
+    complianceResults = runComplianceCheck(projectRoot);
+    console.log(`${colors.green}✓ Compliance check complete${colors.reset}`);
+  } catch (error) {
+    console.error(`${colors.red}Compliance check failed: ${error.message}${colors.reset}`);
+    if (error.stack) {
+      console.error(`${colors.red}Stack: ${error.stack}${colors.reset}`);
+    }
+    console.error(`${colors.yellow}Continuing with other audit checks...${colors.reset}`);
+  }
+  
+  // Generate report
+  console.log(`\n${colors.cyan}Generating audit report...${colors.reset}`);
+  const auditResults = { phase1, phase2, compliance: complianceResults };
+  const { reportPath, filename } = generateMarkdownReport(
+    auditResults,
+    projectRoot,
+    packageJson,
+    paceCoreVersion
+  );
+  
+  console.log(`\n${colors.green}${colors.bold}✅ Audit complete!${colors.reset}`);
+  console.log(`${colors.green}Report saved to: ${reportPath}${colors.reset}\n`);
+  
+  // Summary
+  const totalErrors = phase1.issues.length;
+  const totalWarnings = phase1.warnings.length;
+  const totalSuggestions = phase2.suggestions.length;
+  
+  console.log(`${colors.bold}Summary:${colors.reset}`);
+  console.log(`  ${colors.red}Critical Failures:${colors.reset} ${totalErrors}`);
+  console.log(`  ${colors.yellow}Warnings:${colors.reset} ${totalWarnings}`);
+  console.log(`  ${colors.blue}Suggestions:${colors.reset} ${totalSuggestions}`);
+  console.log(`\n${colors.cyan}See ${filename} for detailed report.${colors.reset}\n`);
+  
+  process.exit(totalErrors > 0 ? 1 : 0);
+}
+
+// Run if called directly
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`${colors.red}Error: ${error.message}${colors.reset}`);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+module.exports = { main };