docguard-cli 0.5.1

package/cli/commands/diagnose.mjs

@@ -0,0 +1,273 @@
+/**
+ * Diagnose Command — The AI Orchestrator
+ *
+ * Chains guard → fix in a single command.
+ * Runs guard internally, maps every failure to an AI-actionable
+ * fix prompt, and outputs them as one combined remediation plan.
+ *
+ * This is the command AI agents run to self-heal a project's docs.
+ *
+ * Output modes:
+ *   --format text    Summary with fix instructions (default)
+ *   --format json    Structured {issues, fixPrompts} for automation
+ *   --format prompt  Full AI-ready prompt (all issues combined)
+ */
+
+import { c } from '../docguard.mjs';
+import { runGuardInternal } from './guard.mjs';
+import { runScoreInternal } from './score.mjs';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+// Map validator failures to the right fix --doc target
+const VALIDATOR_TO_DOC = {
+  'Structure':     null,       // structural — needs init, not doc fix
+  'Doc Sections':  null,       // section-level — maps to specific doc
+  'Docs-Sync':     null,       // cross-reference — needs manual review
+  'Drift':         null,       // drift log maintenance
+  'Changelog':     null,       // changelog maintenance
+  'Test-Spec':     'test-spec',
+  'Environment':   'environment',
+  'Security':      'security',
+  'Architecture':  'architecture',
+  'Freshness':     null,       // freshness — maps to stale doc
+};
+
+// Actionable fix instructions per validator
+const FIX_INSTRUCTIONS = {
+  'Structure': {
+    action: 'Create missing files',
+    command: 'docguard init',
+    description: 'Run init to create missing documentation templates.',
+  },
+  'Doc Sections': {
+    action: 'Fill document sections',
+    command: 'docguard fix --doc',
+    description: 'Documents exist but have missing or placeholder sections. Use fix --doc to generate AI content prompts.',
+  },
+  'Docs-Sync': {
+    action: 'Sync documentation references',
+    command: 'docguard fix --doc architecture',
+    description: 'Documentation references are out of sync with code. Review and update component maps.',
+  },
+  'Drift': {
+    action: 'Update DRIFT-LOG.md',
+    description: 'Code deviates from canonical docs without logged reasons. Add DRIFT entries or update the canonical docs.',
+  },
+  'Changelog': {
+    action: 'Update CHANGELOG.md',
+    description: 'CHANGELOG.md is missing or has no [Unreleased] section. Add recent changes.',
+  },
+  'Test-Spec': {
+    action: 'Update TEST-SPEC.md',
+    command: 'docguard fix --doc test-spec',
+    description: 'Test documentation needs updating to match actual test structure.',
+  },
+  'Environment': {
+    action: 'Update ENVIRONMENT.md',
+    command: 'docguard fix --doc environment',
+    description: 'Environment documentation is missing or incomplete.',
+  },
+  'Security': {
+    action: 'Update SECURITY.md',
+    command: 'docguard fix --doc security',
+    description: 'Security documentation needs updating.',
+  },
+  'Architecture': {
+    action: 'Update ARCHITECTURE.md',
+    command: 'docguard fix --doc architecture',
+    description: 'Architecture documentation doesn\'t match the codebase.',
+  },
+  'Freshness': {
+    action: 'Review stale documents',
+    description: 'Documents haven\'t been reviewed since recent code changes. Re-run fix --doc for each stale doc.',
+  },
+};
+
+export function runDiagnose(projectDir, config, flags) {
+  // ── Step 1: Run guard internally ──
+  const guardData = runGuardInternal(projectDir, config);
+  const scoreData = runScoreInternal(projectDir, config);
+
+  // ── Step 2: Collect issues ──
+  const issues = [];
+  for (const v of guardData.validators) {
+    if (v.status === 'skipped' || v.status === 'pass') continue;
+
+    const fixInfo = FIX_INSTRUCTIONS[v.name] || { action: `Review ${v.name}`, description: 'Manual review needed.' };
+    const docTarget = VALIDATOR_TO_DOC[v.name];
+
+    for (const err of v.errors) {
+      issues.push({
+        severity: 'error',
+        validator: v.name,
+        message: err,
+        action: fixInfo.action,
+        command: fixInfo.command || null,
+        docTarget,
+      });
+    }
+    for (const warn of v.warnings) {
+      issues.push({
+        severity: 'warning',
+        validator: v.name,
+        message: warn,
+        action: fixInfo.action,
+        command: fixInfo.command || null,
+        docTarget,
+      });
+    }
+  }
+
+  // Detect stale docs from freshness and map to specific fix --doc targets
+  for (const issue of issues) {
+    if (issue.validator === 'Freshness' && !issue.docTarget) {
+      // Try to extract doc name from warning message
+      const match = issue.message.match(/([\w-]+\.md)/i);
+      if (match) {
+        const docName = match[1].toLowerCase().replace('.md', '');
+        const docMap = { 'architecture': 'architecture', 'data-model': 'data-model', 'security': 'security', 'test-spec': 'test-spec', 'environment': 'environment' };
+        issue.docTarget = docMap[docName] || null;
+        if (issue.docTarget) {
+          issue.command = `docguard fix --doc ${issue.docTarget}`;
+        }
+      }
+    }
+  }
+
+  // ── Step 3: Output ──
+  if (flags.format === 'json') {
+    outputJSON(guardData, scoreData, issues);
+  } else if (flags.format === 'prompt') {
+    outputPrompt(projectDir, guardData, scoreData, issues);
+  } else {
+    outputText(projectDir, guardData, scoreData, issues);
+  }
+}
+
+function outputJSON(guardData, scoreData, issues) {
+  const result = {
+    project: guardData.project,
+    profile: guardData.profile,
+    status: guardData.status,
+    score: scoreData.score,
+    grade: scoreData.grade,
+    issueCount: issues.length,
+    issues: issues.map(i => ({
+      severity: i.severity,
+      validator: i.validator,
+      message: i.message,
+      action: i.action,
+      command: i.command,
+      docTarget: i.docTarget,
+    })),
+    // Unique fix commands for automation
+    fixCommands: [...new Set(issues.filter(i => i.command).map(i => i.command))],
+    timestamp: new Date().toISOString(),
+  };
+  console.log(JSON.stringify(result, null, 2));
+}
+
+function outputText(projectDir, guardData, scoreData, issues) {
+  console.log(`${c.bold}🔍 DocGuard Diagnose — ${guardData.project}${c.reset}`);
+  console.log(`${c.dim}   Profile: ${guardData.profile} | Score: ${scoreData.score}/100 (${scoreData.grade})${c.reset}`);
+  console.log(`${c.dim}   Guard:   ${guardData.passed}/${guardData.total} passed | Status: ${guardData.status}${c.reset}\n`);
+
+  if (issues.length === 0) {
+    console.log(`  ${c.green}${c.bold}✅ All clear!${c.reset} No issues found.\n`);
+    console.log(`  ${c.dim}Your documentation is healthy. Run \`docguard score --tax\` to see maintenance estimate.${c.reset}\n`);
+    return;
+  }
+
+  // Group by severity
+  const errors = issues.filter(i => i.severity === 'error');
+  const warnings = issues.filter(i => i.severity === 'warning');
+
+  if (errors.length > 0) {
+    console.log(`  ${c.red}${c.bold}Errors (${errors.length}):${c.reset}`);
+    for (const e of errors) {
+      console.log(`  ${c.red}✗${c.reset} [${e.validator}] ${e.message}`);
+      if (e.command) console.log(`    ${c.dim}Fix: ${e.command}${c.reset}`);
+    }
+    console.log('');
+  }
+
+  if (warnings.length > 0) {
+    console.log(`  ${c.yellow}${c.bold}Warnings (${warnings.length}):${c.reset}`);
+    for (const w of warnings) {
+      console.log(`  ${c.yellow}⚠${c.reset} [${w.validator}] ${w.message}`);
+      if (w.command) console.log(`    ${c.dim}Fix: ${w.command}${c.reset}`);
+    }
+    console.log('');
+  }
+
+  // ── Remediation Plan ──
+  const commands = [...new Set(issues.filter(i => i.command).map(i => i.command))];
+  if (commands.length > 0) {
+    console.log(`  ${c.bold}📋 Remediation Plan:${c.reset}`);
+    for (let i = 0; i < commands.length; i++) {
+      console.log(`  ${c.cyan}${i + 1}. ${commands[i]}${c.reset}`);
+    }
+    console.log(`  ${c.cyan}${commands.length + 1}. docguard guard${c.reset} ${c.dim}← verify fixes${c.reset}`);
+    console.log('');
+  }
+
+  // ── AI Prompt (always shown in text mode for easy copy) ──
+  console.log(`  ${c.bold}🤖 AI-Ready Prompt:${c.reset}`);
+  console.log(`  ${c.dim}Copy everything below and paste to your AI agent:${c.reset}\n`);
+  outputPrompt(undefined, guardData, scoreData, issues);
+}
+
+function outputPrompt(projectDir, guardData, scoreData, issues) {
+  if (issues.length === 0) {
+    console.log('No issues to fix. Documentation is healthy.');
+    return;
+  }
+
+  const lines = [];
+  lines.push(`TASK: Fix ${issues.length} documentation issue(s) in project "${guardData.project}"`);
+  lines.push(`Profile: ${guardData.profile} | Score: ${scoreData.score}/100 | Guard: ${guardData.status}`);
+  lines.push('');
+  lines.push('ISSUES FOUND:');
+
+  for (let i = 0; i < issues.length; i++) {
+    const issue = issues[i];
+    lines.push(`${i + 1}. [${issue.severity.toUpperCase()}] [${issue.validator}] ${issue.message}`);
+  }
+
+  lines.push('');
+  lines.push('REMEDIATION STEPS:');
+
+  // Group by unique fix commands
+  const fixGroups = {};
+  for (const issue of issues) {
+    const key = issue.command || issue.action;
+    if (!fixGroups[key]) {
+      fixGroups[key] = { action: issue.action, command: issue.command, docTarget: issue.docTarget, issues: [] };
+    }
+    fixGroups[key].issues.push(issue.message);
+  }
+
+  let step = 1;
+  for (const [key, group] of Object.entries(fixGroups)) {
+    lines.push(`${step}. ${group.action}`);
+    if (group.command) {
+      lines.push(`   Run: ${group.command}`);
+    }
+    if (group.docTarget) {
+      lines.push(`   Then research the codebase and write real content for this document.`);
+    }
+    for (const msg of group.issues) {
+      lines.push(`   - ${msg}`);
+    }
+    step++;
+  }
+
+  lines.push('');
+  lines.push('VALIDATION:');
+  lines.push('After making all fixes, run: docguard guard');
+  lines.push('Expected result: All checks pass (0 errors, 0 warnings)');
+  lines.push(`Target score: ≥${scoreData.score + 5}/100`);
+
+  console.log(lines.join('\n'));
+}

package/cli/commands/diff.mjs

@@ -0,0 +1,360 @@
+/**
+ * Diff Command — Show differences between canonical docs and implementation
+ * Compares what's documented vs what's actually in the code.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, extname, basename } from 'node:path';
+import { c } from '../docguard.mjs';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build',
+  'coverage', '.cache', '__pycache__', '.venv', 'vendor',
+  'docs-canonical', 'docs-implementation', 'templates',
+]);
+
+const CODE_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
+  '.py', '.java', '.go', '.rs', '.rb', '.php',
+]);
+
+export function runDiff(projectDir, config, flags) {
+  console.log(`${c.bold}🔍 DocGuard Diff — ${config.projectName}${c.reset}`);
+  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+
+  const results = [];
+
+  // 1. Routes documented vs routes in code
+  results.push(diffRoutes(projectDir, config));
+
+  // 2. Entities documented vs models in code
+  results.push(diffEntities(projectDir, config));
+
+  // 3. Env vars documented vs .env.example
+  results.push(diffEnvVars(projectDir, config));
+
+  // 4. Tech stack documented vs package.json
+  results.push(diffTechStack(projectDir, config));
+
+  // 5. Tests documented vs tests that exist
+  results.push(diffTests(projectDir, config));
+
+  if (flags.format === 'json') {
+    console.log(JSON.stringify(results.filter(r => r), null, 2));
+    return;
+  }
+
+  // Display results
+  let hasAnyDiff = false;
+
+  for (const result of results) {
+    if (!result) continue;
+
+    console.log(`  ${c.bold}${result.icon} ${result.title}${c.reset}`);
+
+    if (result.onlyInDocs.length > 0) {
+      hasAnyDiff = true;
+      console.log(`    ${c.yellow}Documented but not found in code:${c.reset}`);
+      for (const item of result.onlyInDocs) {
+        console.log(`      ${c.yellow}− ${item}${c.reset}`);
+      }
+    }
+
+    if (result.onlyInCode.length > 0) {
+      hasAnyDiff = true;
+      console.log(`    ${c.red}In code but not documented:${c.reset}`);
+      for (const item of result.onlyInCode) {
+        console.log(`      ${c.red}+ ${item}${c.reset}`);
+      }
+    }
+
+    if (result.matched.length > 0 && flags.verbose) {
+      console.log(`    ${c.green}Matched (${result.matched.length}):${c.reset}`);
+      for (const item of result.matched) {
+        console.log(`      ${c.green}✓ ${item}${c.reset}`);
+      }
+    }
+
+    if (result.onlyInDocs.length === 0 && result.onlyInCode.length === 0) {
+      console.log(`    ${c.green}✓ In sync${c.reset}`);
+    }
+
+    console.log('');
+  }
+
+  if (!hasAnyDiff) {
+    console.log(`  ${c.green}${c.bold}✅ No drift detected — canonical docs match implementation!${c.reset}\n`);
+  } else {
+    console.log(`  ${c.yellow}${c.bold}⚠️  Drift detected — update canonical docs or code to match.${c.reset}\n`);
+  }
+}
+
+// ── Diff Functions ─────────────────────────────────────────────────────────
+
+function diffRoutes(dir) {
+  const archPath = resolve(dir, 'docs-canonical/ARCHITECTURE.md');
+  if (!existsSync(archPath)) return null;
+
+  const content = readFileSync(archPath, 'utf-8');
+
+  // Extract route-like patterns from ARCHITECTURE.md
+  const docRoutes = new Set();
+  const routeRegex = /(?:\/api\/\S+|GET|POST|PUT|DELETE|PATCH)\s+(\S+)/gi;
+  let match;
+  while ((match = routeRegex.exec(content)) !== null) {
+    docRoutes.add(match[1] || match[0]);
+  }
+
+  // Also check for paths in tables
+  const pathRegex = /`(\/api\/[^`]+)`/g;
+  while ((match = pathRegex.exec(content)) !== null) {
+    docRoutes.add(match[1]);
+  }
+
+  // Find route files in code
+  const codeRoutes = new Set();
+  const routeDirs = ['src/routes', 'src/app/api', 'routes', 'api'];
+  for (const rd of routeDirs) {
+    const routeDir = resolve(dir, rd);
+    if (!existsSync(routeDir)) continue;
+
+    const files = getFilesRecursive(routeDir);
+    for (const f of files) {
+      const rel = f.replace(dir + '/', '');
+      codeRoutes.add(rel);
+    }
+  }
+
+  return {
+    title: 'API Routes',
+    icon: '🛣️',
+    onlyInDocs: [...docRoutes].filter(r => ![...codeRoutes].some(cr => cr.includes(r.replace(/\//g, '/')))),
+    onlyInCode: [...codeRoutes].filter(cr => {
+      const name = basename(cr, extname(cr));
+      return ![...docRoutes].some(dr => dr.includes(name));
+    }),
+    matched: [...codeRoutes].filter(cr => {
+      const name = basename(cr, extname(cr));
+      return [...docRoutes].some(dr => dr.includes(name));
+    }),
+  };
+}
+
+function diffEntities(dir) {
+  const dataModelPath = resolve(dir, 'docs-canonical/DATA-MODEL.md');
+  if (!existsSync(dataModelPath)) return null;
+
+  const content = readFileSync(dataModelPath, 'utf-8');
+
+  // Extract entity names from DATA-MODEL.md (look for ### headers or table rows)
+  const docEntities = new Set();
+
+  // Filter out template placeholders and common header noise
+  const HEADER_NOISE = new Set([
+    'EntityName', 'Entity', 'metadata', 'tbd', 'cascade', 'fields',
+    'purpose', 'version', 'author', 'example', 'TODO', 'Overview',
+    'Revision', 'History', 'Entities', 'Relationships', 'Indexes',
+    'Migration', 'Strategy',
+  ]);
+
+  const headerRegex = /^### (\S+)/gm;
+  let match;
+  while ((match = headerRegex.exec(content)) !== null) {
+    const name = match[1].replace(/[`*]/g, '');
+    // Skip template placeholders (<!-- ... -->) and noise words
+    if (name.startsWith('<!--') || name.length <= 1 || HEADER_NOISE.has(name) || HEADER_NOISE.has(name.toLowerCase())) {
+      continue;
+    }
+    docEntities.add(name.toLowerCase());
+  }
+
+  // Also check tables for entity references
+  const tableRegex = /\|\s*(?:`)?(\w+)(?:`)?\s*\|/g;
+  // Filter out common table headers, template placeholders, and markdown noise
+  const TABLE_NOISE = new Set([
+    'entity', 'field', 'type', 'from', 'to', 'table', 'index', 'storage',
+    'required', 'default', 'constraints', 'description', 'name', 'value',
+    'status', 'version', 'category', 'technology', 'license', 'purpose',
+    'cascade', 'relationship', 'notes', 'date', 'author', 'changes',
+    'metadata', 'tbd', 'fields', 'todo', 'example', 'primary', 'key',
+    'none', 'see', 'detected', 'yes', 'no', 'all', 'the', 'for', 'not',
+    'add', 'database', 'orm', 'source', 'unit', 'test', 'integration',
+    'metric', 'target', 'current', 'journey', 'file', 'score', 'weight',
+    'weighted', 'method', 'provider', 'token', 'expiry', 'role',
+    'permissions', 'secret', 'rotation', 'access', 'variable', 'tool',
+    'command', 'run', 'component', 'responsibility', 'location', 'tests',
+  ]);
+  while ((match = tableRegex.exec(content)) !== null) {
+    const name = match[1];
+    if (name.length > 2 && !TABLE_NOISE.has(name.toLowerCase())) {
+      docEntities.add(name.toLowerCase());
+    }
+  }
+
+  // Find model/entity files in code
+  const codeEntities = new Set();
+  const modelDirs = ['src/models', 'models', 'src/entities', 'entities', 'src/schema', 'schema', 'prisma'];
+  for (const md of modelDirs) {
+    const modelDir = resolve(dir, md);
+    if (!existsSync(modelDir)) continue;
+
+    const files = getFilesRecursive(modelDir);
+    for (const f of files) {
+      const name = basename(f, extname(f)).toLowerCase();
+      if (name !== 'index') {
+        codeEntities.add(name);
+      }
+    }
+  }
+
+  return {
+    title: 'Data Entities',
+    icon: '🗃️',
+    onlyInDocs: [...docEntities].filter(d => ![...codeEntities].some(ce => ce.includes(d) || d.includes(ce))),
+    onlyInCode: [...codeEntities].filter(ce => ![...docEntities].some(d => d.includes(ce) || ce.includes(d))),
+    matched: [...codeEntities].filter(ce => [...docEntities].some(d => d.includes(ce) || ce.includes(d))),
+  };
+}
+
+function diffEnvVars(dir) {
+  const envDocPath = resolve(dir, 'docs-canonical/ENVIRONMENT.md');
+  if (!existsSync(envDocPath)) return null;
+
+  const content = readFileSync(envDocPath, 'utf-8');
+
+  // Extract env var names from ENVIRONMENT.md
+  const docVars = new Set();
+  const varRegex = /`([A-Z][A-Z0-9_]{2,})`/g;
+  let match;
+  while ((match = varRegex.exec(content)) !== null) {
+    docVars.add(match[1]);
+  }
+
+  // Read .env.example
+  const codeVars = new Set();
+  const envExamplePath = resolve(dir, '.env.example');
+  if (existsSync(envExamplePath)) {
+    const envContent = readFileSync(envExamplePath, 'utf-8');
+    const envRegex = /^([A-Z][A-Z0-9_]+)\s*=/gm;
+    while ((match = envRegex.exec(envContent)) !== null) {
+      codeVars.add(match[1]);
+    }
+  }
+
+  if (docVars.size === 0 && codeVars.size === 0) return null;
+
+  return {
+    title: 'Environment Variables',
+    icon: '🔧',
+    onlyInDocs: [...docVars].filter(v => !codeVars.has(v)),
+    onlyInCode: [...codeVars].filter(v => !docVars.has(v)),
+    matched: [...docVars].filter(v => codeVars.has(v)),
+  };
+}
+
+function diffTechStack(dir) {
+  const archPath = resolve(dir, 'docs-canonical/ARCHITECTURE.md');
+  const pkgPath = resolve(dir, 'package.json');
+  if (!existsSync(archPath) || !existsSync(pkgPath)) return null;
+
+  const archContent = readFileSync(archPath, 'utf-8');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+
+  // Extract tech from ARCHITECTURE.md
+  const docTech = new Set();
+  const techPatterns = ['React', 'Next.js', 'Vue', 'Angular', 'Svelte', 'Express', 'Fastify', 'Hono',
+    'PostgreSQL', 'MySQL', 'MongoDB', 'DynamoDB', 'Redis', 'Prisma', 'Drizzle',
+    'TypeScript', 'Tailwind', 'Docker', 'Terraform'];
+
+  for (const tech of techPatterns) {
+    if (archContent.toLowerCase().includes(tech.toLowerCase())) {
+      docTech.add(tech);
+    }
+  }
+
+  // Extract from package.json
+  const codeTech = new Set();
+  const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const depMap = {
+    'react': 'React', 'next': 'Next.js', 'vue': 'Vue', 'express': 'Express',
+    'fastify': 'Fastify', 'hono': 'Hono', 'prisma': 'Prisma', '@prisma/client': 'Prisma',
+    'drizzle-orm': 'Drizzle', 'typescript': 'TypeScript', 'tailwindcss': 'Tailwind',
+    'redis': 'Redis', 'ioredis': 'Redis', 'pg': 'PostgreSQL', 'mysql2': 'MySQL',
+    'mongoose': 'MongoDB', '@aws-sdk/client-dynamodb': 'DynamoDB',
+  };
+
+  for (const [dep, tech] of Object.entries(depMap)) {
+    if (allDeps[dep]) codeTech.add(tech);
+  }
+
+  if (docTech.size === 0 && codeTech.size === 0) return null;
+
+  return {
+    title: 'Tech Stack',
+    icon: '⚙️',
+    onlyInDocs: [...docTech].filter(t => !codeTech.has(t)),
+    onlyInCode: [...codeTech].filter(t => !docTech.has(t)),
+    matched: [...docTech].filter(t => codeTech.has(t)),
+  };
+}
+
+function diffTests(dir) {
+  const testSpecPath = resolve(dir, 'docs-canonical/TEST-SPEC.md');
+  if (!existsSync(testSpecPath)) return null;
+
+  const content = readFileSync(testSpecPath, 'utf-8');
+
+  // Extract test file references from TEST-SPEC.md
+  const docTests = new Set();
+  const testFileRegex = /`([^`]*\.(?:test|spec)\.[^`]+)`/g;
+  let match;
+  while ((match = testFileRegex.exec(content)) !== null) {
+    docTests.add(match[1]);
+  }
+
+  // Find actual test files
+  const codeTests = new Set();
+  const testDirs = ['tests', 'test', '__tests__', 'spec', 'e2e'];
+  for (const td of testDirs) {
+    const testDir = resolve(dir, td);
+    if (!existsSync(testDir)) continue;
+
+    const files = getFilesRecursive(testDir);
+    for (const f of files) {
+      const rel = f.replace(dir + '/', '');
+      codeTests.add(rel);
+    }
+  }
+
+  if (docTests.size === 0 && codeTests.size === 0) return null;
+
+  return {
+    title: 'Test Files',
+    icon: '🧪',
+    onlyInDocs: [...docTests].filter(t => !codeTests.has(t)),
+    onlyInCode: [...codeTests].filter(t => !docTests.has(t)),
+    matched: [...docTests].filter(t => codeTests.has(t)),
+  };
+}
+
+// ── Utilities ──────────────────────────────────────────────────────────────
+
+function getFilesRecursive(dir) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+
+  const entries = readdirSync(dir);
+  for (const entry of entries) {
+    if (IGNORE_DIRS.has(entry) || entry.startsWith('.')) continue;
+    const fullPath = join(dir, entry);
+    try {
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        results.push(...getFilesRecursive(fullPath));
+      } else if (stat.isFile() && CODE_EXTENSIONS.has(extname(fullPath))) {
+        results.push(fullPath);
+      }
+    } catch { /* skip */ }
+  }
+  return results;
+}