docguard-cli 0.7.3 → 0.8.2

package/cli/validators/docs-diff.mjs

@@ -0,0 +1,185 @@
+/**
+ * Docs-Diff Validator — Checks alignment between canonical docs and code.
+ *
+ * Runs as part of `docguard guard` on every invocation.
+ * Detects undocumented code artifacts and documented items not found in code.
+ * Returns warnings (not errors) since drift is a soft signal.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, extname, basename } from 'node:path';
+
+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',
+]);
+
+/**
+ * Validate doc-code alignment — compares canonical docs vs source code.
+ * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ */
+export function validateDocsDiff(projectDir, config) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  const checks = [
+    diffTechStack(projectDir),
+    diffEnvVars(projectDir),
+    diffTests(projectDir),
+  ];
+
+  for (const result of checks) {
+    if (!result) continue;
+
+    total++;
+    const undocumented = result.onlyInCode.length;
+    const stale = result.onlyInDocs.length;
+
+    if (undocumented === 0 && stale === 0) {
+      passed++;
+    } else {
+      const parts = [];
+      if (undocumented > 0) parts.push(`${undocumented} in code but not documented`);
+      if (stale > 0) parts.push(`${stale} documented but not found in code`);
+      warnings.push(`${result.title} drift: ${parts.join(', ')}`);
+    }
+  }
+
+  return { errors: [], warnings, passed, total };
+}
+
+// ── Diff Functions (lightweight versions for validator) ──────────────────
+
+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');
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')); } catch { return null; }
+
+  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);
+    }
+  }
+
+  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',
+    onlyInDocs: [...docTech].filter(t => !codeTech.has(t)),
+    onlyInCode: [...codeTech].filter(t => !docTech.has(t)),
+  };
+}
+
+function diffEnvVars(dir) {
+  const envDocPath = resolve(dir, 'docs-canonical/ENVIRONMENT.md');
+  if (!existsSync(envDocPath)) return null;
+
+  const content = readFileSync(envDocPath, 'utf-8');
+  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]);
+  }
+
+  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',
+    onlyInDocs: [...docVars].filter(v => !codeVars.has(v)),
+    onlyInCode: [...codeVars].filter(v => !docVars.has(v)),
+  };
+}
+
+function diffTests(dir) {
+  const testSpecPath = resolve(dir, 'docs-canonical/TEST-SPEC.md');
+  if (!existsSync(testSpecPath)) return null;
+
+  const content = readFileSync(testSpecPath, 'utf-8');
+  const docTests = new Set();
+  const testFileRegex = /`([^`]*\.(test|spec)\.[^`]+)`/g;
+  let match;
+  while ((match = testFileRegex.exec(content)) !== null) {
+    docTests.add(match[1]);
+  }
+
+  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) {
+      codeTests.add(f.replace(dir + '/', ''));
+    }
+  }
+
+  if (docTests.size === 0 && codeTests.size === 0) return null;
+
+  return {
+    title: 'Test Files',
+    onlyInDocs: [...docTests].filter(t => !codeTests.has(t)),
+    onlyInCode: [...codeTests].filter(t => !docTests.has(t)),
+  };
+}
+
+function getFilesRecursive(dir) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+  let entries;
+  try { entries = readdirSync(dir); } catch { return results; }
+
+  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;
+}

package/cli/validators/metadata-sync.mjs

@@ -0,0 +1,179 @@
+/**
+ * Metadata Sync Validator — Detects stale version references across docs.
+ *
+ * Cross-checks package.json version against extension.yml and all .md files.
+ * Flags outdated version strings (e.g., README references v0.7.2 but package.json is 0.8.0).
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, relative, extname } from 'node:path';
+import { loadIgnorePatterns } from '../shared.mjs';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
+  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+]);
+
+/**
+ * Validate version/metadata consistency across project files.
+ * @param {string} projectDir - Project root directory
+ * @param {object} config - DocGuard config
+ * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ */
+export function validateMetadataSync(projectDir, config) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  // ── Get source of truth: package.json version ──
+  const pkgPath = resolve(projectDir, 'package.json');
+  if (!existsSync(pkgPath)) {
+    return { errors: [], warnings, passed: 0, total: 0 };
+  }
+
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')); } catch { return { errors: [], warnings, passed: 0, total: 0 }; }
+  const currentVersion = pkg.version;
+  if (!currentVersion) return { errors: [], warnings, passed: 0, total: 0 };
+
+  // Parse into components for smart comparison
+  const vParts = currentVersion.split('.');
+  const major = parseInt(vParts[0], 10);
+  const minor = parseInt(vParts[1], 10);
+
+  // ── Check 1: extension.yml version sync ──
+  const extFiles = findExtensionYmls(projectDir);
+  for (const extFile of extFiles) {
+    total++;
+    const relPath = relative(projectDir, extFile);
+    try {
+      const content = readFileSync(extFile, 'utf-8');
+      const versionMatch = content.match(/version:\s*["']?(\d+\.\d+\.\d+)["']?/);
+      if (versionMatch) {
+        if (versionMatch[1] !== currentVersion) {
+          warnings.push(
+            `${relPath} has version "${versionMatch[1]}" but package.json is "${currentVersion}"`
+          );
+        } else {
+          passed++;
+        }
+      }
+    } catch { /* skip unreadable */ }
+  }
+
+  // ── Check 2: Version references in markdown files ──
+  const isIgnored = loadIgnorePatterns(projectDir);
+  const mdFiles = findMarkdownFiles(projectDir);
+  // Version patterns to find: v0.7.2, @0.7.2, /v0.7.2/, docguard-cli@0.7.2
+  const versionRegex = /(?:v|@|\/v?)(\d+\.\d+\.\d+)/g;
+
+  for (const mdFile of mdFiles) {
+    const relPath = relative(projectDir, mdFile);
+    // Skip CHANGELOG.md and DRIFT-LOG.md — these are historical by definition
+    const baseName = relPath.toLowerCase();
+    if (baseName.includes('changelog') || baseName.includes('drift-log')) continue;
+    // Skip files matched by .docguardignore
+    if (isIgnored(relPath)) continue;
+
+    let content;
+    try { content = readFileSync(mdFile, 'utf-8'); } catch { continue; }
+
+    // Only flag version references in actionable contexts:
+    // - URLs (download, install, archive links)
+    // - version: declarations (YAML-style)
+    // - npm install / npx commands
+    // - Badge URLs
+    // NOT in prose text like "In v0.2.0 we added..." or roadmap discussions
+    const actionablePatterns = [
+      // URLs with version: /v0.7.2/, /tags/v0.7.2, @0.7.2
+      /(?:archive|tags|releases|download)\/v?(\d+\.\d+\.\d+)/g,
+      // npm install/npx commands: docguard-cli@0.7.2
+      /@(\d+\.\d+\.\d+)/g,
+      // YAML-style: version: "0.7.2" or version: 0.7.2
+      /version:\s*["']?(\d+\.\d+\.\d+)["']?/g,
+    ];
+
+    for (const pattern of actionablePatterns) {
+      pattern.lastIndex = 0;
+      let match;
+      while ((match = pattern.exec(content)) !== null) {
+        const foundVersion = match[1];
+        const fParts = foundVersion.split('.');
+        const fMajor = parseInt(fParts[0], 10);
+        const fMinor = parseInt(fParts[1], 10);
+
+        // Only flag if same major but older minor (same package, stale ref)
+        if (fMajor === major && fMinor < minor && foundVersion !== currentVersion) {
+          total++;
+          warnings.push(
+            `${relPath} references "v${foundVersion}" in an actionable context (URL/install/declaration) but current version is "${currentVersion}"`
+          );
+        } else if (fMajor === major && fMinor === minor && foundVersion === currentVersion) {
+          total++;
+          passed++;
+        }
+      }
+    }
+  }
+
+  return { errors: [], warnings, passed, total };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function findExtensionYmls(dir) {
+  const results = [];
+  const extDir = resolve(dir, 'extensions');
+  if (existsSync(extDir)) {
+    walkFiles(extDir, (f) => {
+      if (f.endsWith('extension.yml') || f.endsWith('extension.yaml')) {
+        results.push(f);
+      }
+    });
+  }
+  // Also check root
+  const rootExt = resolve(dir, 'extension.yml');
+  if (existsSync(rootExt)) results.push(rootExt);
+  return results;
+}
+
+function findMarkdownFiles(dir) {
+  const seen = new Set();
+  const mdFiles = [];
+  const searchDirs = [
+    dir,
+    resolve(dir, 'docs-canonical'),
+    resolve(dir, 'extensions'),
+  ];
+
+  for (const searchDir of searchDirs) {
+    if (!existsSync(searchDir)) continue;
+    walkFiles(searchDir, (f) => {
+      if (f.endsWith('.md') && !seen.has(f)) {
+        seen.add(f);
+        mdFiles.push(f);
+      }
+    });
+  }
+
+  return mdFiles;
+}
+
+function walkFiles(dir, callback) {
+  if (!existsSync(dir)) return;
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+
+  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()) {
+        walkFiles(fullPath, callback);
+      } else if (stat.isFile()) {
+        callback(fullPath);
+      }
+    } catch { /* skip */ }
+  }
+}

package/cli/validators/metrics-consistency.mjs

@@ -0,0 +1,166 @@
+/**
+ * Metrics Consistency Validator — Detects stale hardcoded numbers in docs.
+ *
+ * Scans all .md files for patterns like "N checks", "N validators", "N tests"
+ * and compares against actual values from guard results and package.json.
+ * Returns warnings for mismatches.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join, relative } from 'node:path';
+import { loadIgnorePatterns } from '../shared.mjs';
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
+  '.cache', '__pycache__', '.venv', 'vendor', '.turbo', '.vercel',
+]);
+
+/**
+ * Validate metrics consistency across documentation.
+ * @param {string} projectDir - Project root directory
+ * @param {object} config - DocGuard config
+ * @param {object} [guardResults] - Results from runGuardInternal (optional)
+ * @returns {{ errors: string[], warnings: string[], passed: number, total: number }}
+ */
+export function validateMetricsConsistency(projectDir, config, guardResults) {
+  const warnings = [];
+  let passed = 0;
+  let total = 0;
+
+  // ── Collect actual metrics ──
+  const actuals = {};
+
+  // Guard check count (from guard results if available)
+  if (guardResults && Array.isArray(guardResults)) {
+    const totalChecks = guardResults.reduce((sum, r) => {
+      if (r.status === 'skipped') return sum;
+      return sum + (r.total || 0);
+    }, 0);
+    const validatorCount = guardResults.filter(r => r.status !== 'skipped').length;
+
+    actuals.checks = totalChecks;
+    actuals.validators = validatorCount;
+  }
+
+  // Test count — count test files on disk
+  const testFiles = findTestFiles(projectDir);
+  if (testFiles.length > 0) {
+    actuals.tests = testFiles.length;
+  }
+
+  // If no actuals to compare, skip
+  if (Object.keys(actuals).length === 0) {
+    return { errors: [], warnings, passed: 0, total: 0 };
+  }
+
+  // ── Scan markdown files for hardcoded numbers ──
+  const isIgnored = loadIgnorePatterns(projectDir);
+  const mdFiles = findMarkdownFiles(projectDir);
+  // Patterns must match standalone number references, not ratio-style "8/8 checks"
+  const patterns = [
+    { key: 'checks', regex: /(?<!\d\/)\b(\d{2,})\s+(?:automated\s+)?checks?\b/gi, label: 'checks' },
+    { key: 'validators', regex: /(?<!\d\/)\b(\d{2,})\s+validators?\b/gi, label: 'validators' },
+  ];
+
+  for (const mdFile of mdFiles) {
+    const relPath = relative(projectDir, mdFile);
+    // Skip changelog (historical numbers are fine by definition)
+    if (relPath.toLowerCase().includes('changelog')) continue;
+    // Skip files matched by .docguardignore
+    if (isIgnored(relPath)) continue;
+
+    let content;
+    try { content = readFileSync(mdFile, 'utf-8'); } catch { continue; }
+
+    for (const { key, regex, label } of patterns) {
+      if (actuals[key] === undefined) continue;
+
+      regex.lastIndex = 0;
+      let match;
+      while ((match = regex.exec(content)) !== null) {
+        total++;
+        const found = parseInt(match[1], 10);
+        if (found !== actuals[key] && found > 0) {
+          warnings.push(
+            `${relPath} says "${found} ${label}" but actual count is ${actuals[key]}. Update the doc or run \`docguard generate --force\``
+          );
+        } else {
+          passed++;
+        }
+      }
+    }
+  }
+
+  return { errors: [], warnings, passed, total };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function findTestFiles(dir) {
+  const tests = [];
+  const testDirs = ['tests', 'test', '__tests__', 'spec', 'e2e'];
+
+  // Top-level test dirs
+  for (const td of testDirs) {
+    const fullDir = resolve(dir, td);
+    if (existsSync(fullDir)) {
+      walkFiles(fullDir, (f) => {
+        if (/\.(test|spec)\.[^.]+$/.test(f)) tests.push(f);
+      });
+    }
+  }
+
+  // Co-located tests in src/
+  const srcDir = resolve(dir, 'src');
+  if (existsSync(srcDir)) {
+    walkFiles(srcDir, (f) => {
+      if (/\.(test|spec)\.[^.]+$/.test(f) || f.includes('__tests__')) {
+        if (!tests.includes(f)) tests.push(f);
+      }
+    });
+  }
+
+  return tests;
+}
+
+function findMarkdownFiles(dir) {
+  const seen = new Set();
+  const mdFiles = [];
+  // Check root, docs-canonical, and extensions
+  const searchDirs = [
+    dir,
+    resolve(dir, 'docs-canonical'),
+    resolve(dir, 'extensions'),
+  ];
+
+  for (const searchDir of searchDirs) {
+    if (!existsSync(searchDir)) continue;
+    walkFiles(searchDir, (f) => {
+      if (f.endsWith('.md') && !seen.has(f)) {
+        seen.add(f);
+        mdFiles.push(f);
+      }
+    });
+  }
+
+  return mdFiles;
+}
+
+function walkFiles(dir, callback) {
+  if (!existsSync(dir)) return;
+  let entries;
+  try { entries = readdirSync(dir); } catch { return; }
+
+  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()) {
+        walkFiles(fullPath, callback);
+      } else if (stat.isFile()) {
+        callback(fullPath);
+      }
+    } catch { /* skip */ }
+  }
+}

package/cli/validators/test-spec.mjs

@@ -37,6 +37,7 @@ export function validateTestSpec(projectDir, config) {
       if (cells.length < 3) continue;
 
       const sourceFile = cells[0];
+      const testFile = cells[1];
       const status = cells[cells.length - 1]; // Last column is always status
 
       // Skip template/example rows and italic placeholder rows
@@ -56,6 +57,38 @@ export function validateTestSpec(projectDir, config) {
         results.total++;
         results.passed++;
       }
+
+      // ── File existence checks ───────────────────────────────────────
+      // Verify source file still exists (catch stale map entries)
+      const cleanSource = sourceFile.replace(/`/g, '').trim();
+      if (cleanSource && cleanSource !== '—' && cleanSource !== 'Source File') {
+        const sourcePath = resolve(projectDir, cleanSource);
+        if (!existsSync(sourcePath)) {
+          results.total++;
+          results.warnings.push(
+            `Source-to-Test Map: source file \`${cleanSource}\` not found on disk — stale entry?`
+          );
+        } else {
+          results.total++;
+          results.passed++;
+        }
+      }
+
+      // Verify test file exists (catch wrong/stale test references)
+      const cleanTest = testFile ? testFile.replace(/`/g, '').trim() : '';
+      if (cleanTest && cleanTest !== '—' && cleanTest !== 'Test File' &&
+          cleanTest !== 'Unit Test' && !cleanTest.includes('N/A')) {
+        const testPath = resolve(projectDir, cleanTest);
+        if (!existsSync(testPath)) {
+          results.total++;
+          results.warnings.push(
+            `Source-to-Test Map: test file \`${cleanTest}\` not found — referenced by ${cleanSource}`
+          );
+        } else {
+          results.total++;
+          results.passed++;
+        }
+      }
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.7.3",
+  "version": "0.8.2",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {

package/templates/TEST-SPEC.md.template

@@ -53,3 +53,16 @@
 |--------|---------------|------|
 | Health | <!-- e.g. /health returns 200 --> | |
 | Auth | <!-- e.g. Login flow completes --> | |
+
+## Recommended Test Patterns
+
+<!-- DocGuard validates that files listed in the Source-to-Test Map exist on disk.
+     Keep the map up to date — stale entries will trigger warnings. -->
+
+| Pattern | Description | Priority |
+|---------|-------------|----------|
+| Config-awareness | Test behavior changes per `.docguard.json` / env config | ⚠️ High |
+| Individual functions | Test each module/function directly, not just via CLI | ⚠️ High |
+| Edge cases | Empty inputs, missing files, invalid config | ✅ Medium |
+| Error paths | Verify graceful failure, not just happy path | ✅ Medium |
+| Regression guards | Pin specific bug fixes with dedicated tests | ✅ Medium |

package/cli/commands/audit.mjs

@@ -1,92 +0,0 @@
-/**
- * Audit Command — Scan project, report what CDD docs exist or are missing
- * Now uses the full documentTypes config to show ALL docs with categories.
- */
-
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { c } from '../docguard.mjs';
-
-export function runAudit(projectDir, config, flags) {
-  console.log(`${c.bold}📋 DocGuard Audit — ${config.projectName}${c.reset}`);
-  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
-
-  const results = { found: 0, missing: 0, optional: 0, total: 0, details: [] };
-
-  // Use documentTypes from config (all 16 doc types with required/optional)
-  const docTypes = config.documentTypes || {};
-
-  // Group by category
-  const categories = {};
-  for (const [filePath, meta] of Object.entries(docTypes)) {
-    const cat = meta.category || 'other';
-    if (!categories[cat]) categories[cat] = [];
-    categories[cat].push({ filePath, ...meta });
-  }
-
-  // Category display names and order
-  const categoryLabels = {
-    canonical: '📘 Canonical Documentation (Design Intent)',
-    implementation: '📗 Implementation Documentation (Current State)',
-    agent: '🤖 Agent Instructions',
-    tracking: '📑 Change Tracking',
-  };
-
-  const categoryOrder = ['canonical', 'implementation', 'agent', 'tracking'];
-
-  for (const cat of categoryOrder) {
-    const docs = categories[cat];
-    if (!docs || docs.length === 0) continue;
-
-    console.log(`${c.bold}  ${categoryLabels[cat] || cat}${c.reset}`);
-
-    for (const doc of docs) {
-      const fullPath = resolve(projectDir, doc.filePath);
-      const exists = existsSync(fullPath);
-
-      if (exists) {
-        results.found++;
-        results.total++;
-        results.details.push({ file: doc.filePath, status: 'found', required: doc.required });
-        console.log(`    ${c.green}✅${c.reset} ${doc.filePath} ${c.dim}— ${doc.description}${c.reset}`);
-      } else if (doc.required) {
-        results.missing++;
-        results.total++;
-        results.details.push({ file: doc.filePath, status: 'missing', required: true });
-        console.log(`    ${c.red}❌${c.reset} ${doc.filePath} ${c.dim}— ${doc.description}${c.reset} ${c.red}(required)${c.reset}`);
-      } else {
-        results.optional++;
-        results.details.push({ file: doc.filePath, status: 'optional', required: false });
-        if (flags.verbose) {
-          console.log(`    ${c.dim}○  ${doc.filePath} — ${doc.description} (optional)${c.reset}`);
-        }
-      }
-    }
-    console.log('');
-  }
-
-  // Score (only required files)
-  const requiredTotal = results.found + results.missing;
-  const pct = requiredTotal === 0 ? 100 : Math.round((results.found / requiredTotal) * 100);
-  const scoreColor = pct >= 80 ? c.green : pct >= 50 ? c.yellow : c.red;
-
-  console.log(`${c.bold}  ─────────────────────────────────────${c.reset}`);
-  console.log(`  ${c.bold}Required:${c.reset} ${scoreColor}${results.found - (results.found - requiredTotal + results.missing)}/${requiredTotal} files (${pct}%)${c.reset}`);
-
-  // Show optional count
-  if (!flags.verbose && results.optional > 0) {
-    console.log(`  ${c.dim}Optional: ${results.optional} not present (use --verbose to see all)${c.reset}`);
-  }
-
-  if (results.missing > 0) {
-    console.log(`\n  ${c.yellow}💡 Run ${c.cyan}docguard init${c.yellow} to create missing docs from templates.${c.reset}`);
-    console.log(`  ${c.yellow}💡 Run ${c.cyan}docguard generate${c.yellow} to auto-fill docs from your codebase.${c.reset}`);
-  } else {
-    console.log(`\n  ${c.green}🎉 All required CDD documentation present!${c.reset}`);
-    console.log(`  ${c.dim}Run ${c.cyan}docguard guard${c.dim} to validate content alignment.${c.reset}`);
-    console.log(`  ${c.dim}Run ${c.cyan}docguard score${c.dim} to check your CDD maturity.${c.reset}`);
-  }
-
-  console.log('');
-  return results;
-}