@doccov/cli 0.11.0 → 0.13.0

package/dist/cli.js

@@ -1,22 +1,4 @@
 #!/usr/bin/env node
-import { createRequire } from "node:module";
-var __create = Object.create;
-var __getProtoOf = Object.getPrototypeOf;
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __toESM = (mod, isNodeMode, target) => {
-  target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: () => mod[key],
-        enumerable: true
-      });
-  return to;
-};
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/config/doccov-config.ts
 import { access } from "node:fs/promises";
@@ -178,14 +160,14 @@ ${formatIssues(issues)}`);
 // src/config/index.ts
 var defineConfig = (config) => config;
 // src/cli.ts
-import { readFileSync as readFileSync4 } from "node:fs";
-import * as path9 from "node:path";
+import { readFileSync as readFileSync3 } from "node:fs";
+import * as path8 from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 
 // src/commands/check.ts
 import * as fs2 from "node:fs";
-import * as path3 from "node:path";
+import * as path4 from "node:path";
 import {
   applyEdits,
   categorizeDrifts,
@@ -208,6 +190,223 @@ import {
 } from "@openpkg-ts/spec";
 import chalk2 from "chalk";
 
+// src/reports/diff-markdown.ts
+import * as path2 from "node:path";
+function bar(pct, width = 10) {
+  const filled = Math.round(pct / 100 * width);
+  return "█".repeat(filled) + "░".repeat(width - filled);
+}
+function formatDelta(delta) {
+  if (delta > 0)
+    return `+${delta}%`;
+  if (delta < 0)
+    return `${delta}%`;
+  return "0%";
+}
+function renderDiffMarkdown(data, options = {}) {
+  const limit = options.limit ?? 10;
+  const lines = [];
+  lines.push(`# DocCov Diff Report`);
+  lines.push("");
+  lines.push(`**Comparing:** \`${data.baseName}\` → \`${data.headName}\``);
+  lines.push("");
+  lines.push("## Coverage Summary");
+  lines.push("");
+  const deltaIndicator = data.coverageDelta > 0 ? "↑" : data.coverageDelta < 0 ? "↓" : "→";
+  lines.push(`| Metric | Base | Head | Delta |`);
+  lines.push(`|--------|------|------|-------|`);
+  lines.push(`| Coverage | ${data.oldCoverage}% | ${data.newCoverage}% | ${deltaIndicator} ${formatDelta(data.coverageDelta)} |`);
+  lines.push(`| Breaking Changes | - | ${data.breaking.length} | - |`);
+  lines.push(`| New Exports | - | ${data.nonBreaking.length} | - |`);
+  lines.push(`| New Undocumented | - | ${data.newUndocumented.length} | - |`);
+  if (data.driftIntroduced > 0 || data.driftResolved > 0) {
+    const driftDelta = data.driftIntroduced > 0 ? `+${data.driftIntroduced}` : data.driftResolved > 0 ? `-${data.driftResolved}` : "0";
+    lines.push(`| Drift | - | - | ${driftDelta} |`);
+  }
+  if (data.breaking.length > 0) {
+    lines.push("");
+    lines.push("## Breaking Changes");
+    lines.push("");
+    const categorized = data.categorizedBreaking ?? [];
+    const highSeverity = categorized.filter((c) => c.severity === "high");
+    const otherSeverity = categorized.filter((c) => c.severity !== "high");
+    if (highSeverity.length > 0) {
+      lines.push("### High Severity");
+      lines.push("");
+      lines.push("| Name | Kind | Reason |");
+      lines.push("|------|------|--------|");
+      for (const c of highSeverity.slice(0, limit)) {
+        lines.push(`| \`${c.name}\` | ${c.kind} | ${c.reason} |`);
+      }
+      if (highSeverity.length > limit) {
+        lines.push(`| ... | | ${highSeverity.length - limit} more |`);
+      }
+      lines.push("");
+    }
+    if (otherSeverity.length > 0) {
+      lines.push("### Medium/Low Severity");
+      lines.push("");
+      lines.push("| Name | Kind | Reason |");
+      lines.push("|------|------|--------|");
+      for (const c of otherSeverity.slice(0, limit)) {
+        lines.push(`| \`${c.name}\` | ${c.kind} | ${c.reason} |`);
+      }
+      if (otherSeverity.length > limit) {
+        lines.push(`| ... | | ${otherSeverity.length - limit} more |`);
+      }
+      lines.push("");
+    }
+  }
+  if (data.memberChanges && data.memberChanges.length > 0) {
+    lines.push("");
+    lines.push("## Member Changes");
+    lines.push("");
+    const byClass = groupMemberChangesByClass(data.memberChanges);
+    for (const [className, changes] of byClass) {
+      lines.push(`### ${className}`);
+      lines.push("");
+      lines.push("| Member | Change | Details |");
+      lines.push("|--------|--------|---------|");
+      for (const mc of changes.slice(0, limit)) {
+        const details = getChangeDetails(mc);
+        lines.push(`| \`${mc.memberName}()\` | ${mc.changeType} | ${details} |`);
+      }
+      if (changes.length > limit) {
+        lines.push(`| ... | | ${changes.length - limit} more |`);
+      }
+      lines.push("");
+    }
+  }
+  if (data.nonBreaking.length > 0) {
+    lines.push("");
+    lines.push("## New Exports");
+    lines.push("");
+    const undocSet = new Set(data.newUndocumented);
+    lines.push("| Export | Documented |");
+    lines.push("|--------|------------|");
+    for (const name of data.nonBreaking.slice(0, limit)) {
+      const documented = undocSet.has(name) ? "No" : "Yes";
+      lines.push(`| \`${name}\` | ${documented} |`);
+    }
+    if (data.nonBreaking.length > limit) {
+      lines.push(`| ... | ${data.nonBreaking.length - limit} more |`);
+    }
+  }
+  if (data.docsImpact) {
+    renderDocsImpactSection(lines, data.docsImpact, limit);
+  }
+  lines.push("");
+  lines.push("---");
+  lines.push("*Generated by [DocCov](https://doccov.com)*");
+  return lines.join(`
+`);
+}
+function groupMemberChangesByClass(changes) {
+  const byClass = new Map;
+  for (const mc of changes) {
+    const list = byClass.get(mc.className) ?? [];
+    list.push(mc);
+    byClass.set(mc.className, list);
+  }
+  return byClass;
+}
+function getChangeDetails(mc) {
+  if (mc.changeType === "removed") {
+    return mc.suggestion ? `→ ${mc.suggestion}` : "removed";
+  }
+  if (mc.changeType === "signature-changed") {
+    if (mc.oldSignature && mc.newSignature) {
+      return `\`${mc.oldSignature}\` → \`${mc.newSignature}\``;
+    }
+    return "signature changed";
+  }
+  if (mc.changeType === "added") {
+    return "new";
+  }
+  return "-";
+}
+function renderDocsImpactSection(lines, docsImpact, limit) {
+  const { impactedFiles, missingDocs, stats, allUndocumented } = docsImpact;
+  lines.push("");
+  lines.push("## Documentation Impact");
+  lines.push("");
+  lines.push(`Scanned **${stats.filesScanned}** files, **${stats.codeBlocksFound}** code blocks, **${stats.referencesFound}** references.`);
+  lines.push("");
+  if (impactedFiles.length === 0 && missingDocs.length === 0) {
+    lines.push("No documentation updates required.");
+    return;
+  }
+  if (impactedFiles.length > 0) {
+    lines.push("### Files Requiring Updates");
+    lines.push("");
+    lines.push("| File | Issues | Details |");
+    lines.push("|------|--------|---------|");
+    for (const file of impactedFiles.slice(0, limit)) {
+      const filename = path2.basename(file.file);
+      const issueCount = file.references.length;
+      const firstRef = file.references[0];
+      const detail = firstRef ? `L${firstRef.line}: ${firstRef.memberName ?? firstRef.exportName}` : "-";
+      lines.push(`| \`${filename}\` | ${issueCount} | ${detail} |`);
+    }
+    if (impactedFiles.length > limit) {
+      lines.push(`| ... | | ${impactedFiles.length - limit} more files |`);
+    }
+    lines.push("");
+  }
+  if (missingDocs.length > 0) {
+    lines.push("### New Exports Missing Documentation");
+    lines.push("");
+    lines.push("| Export |");
+    lines.push("|--------|");
+    for (const name of missingDocs.slice(0, limit)) {
+      lines.push(`| \`${name}\` |`);
+    }
+    if (missingDocs.length > limit) {
+      lines.push(`| ... ${missingDocs.length - limit} more |`);
+    }
+    lines.push("");
+  }
+  if (allUndocumented && allUndocumented.length > 0 && stats.totalExports > 0) {
+    const docPercent = Math.round((stats.totalExports - allUndocumented.length) / stats.totalExports * 100);
+    lines.push("### Documentation Coverage");
+    lines.push("");
+    lines.push(`**${stats.documentedExports}/${stats.totalExports}** exports documented (${docPercent}%) \`${bar(docPercent)}\``);
+    lines.push("");
+  }
+}
+
+// src/reports/diff-html.ts
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function renderDiffHtml(data, options = {}) {
+  const md = renderDiffMarkdown(data, options);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>DocCov Diff: ${escapeHtml(data.baseName)} → ${escapeHtml(data.headName)}</title>
+  <style>
+    :root { --bg: #0d1117; --fg: #c9d1d9; --border: #30363d; --accent: #58a6ff; --success: #3fb950; --warning: #d29922; --danger: #f85149; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: var(--bg); color: var(--fg); max-width: 900px; margin: 0 auto; padding: 2rem; line-height: 1.6; }
+    h1, h2, h3 { border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; }
+    h1 { color: var(--accent); }
+    table { border-collapse: collapse; width: 100%; margin: 1rem 0; }
+    th, td { border: 1px solid var(--border); padding: 0.5rem 1rem; text-align: left; }
+    th { background: #161b22; }
+    code { background: #161b22; padding: 0.2rem 0.4rem; border-radius: 4px; font-size: 0.9em; }
+    a { color: var(--accent); }
+    .delta-positive { color: var(--success); }
+    .delta-negative { color: var(--danger); }
+    .delta-neutral { color: var(--fg); }
+  </style>
+</head>
+<body>
+<pre style="white-space: pre-wrap; font-family: inherit;">${escapeHtml(md)}</pre>
+</body>
+</html>`;
+}
 // src/reports/github.ts
 function renderGithubSummary(stats, options = {}) {
   const coverageScore = options.coverageScore ?? stats.coverageScore;
@@ -235,7 +434,7 @@ ${status} Coverage ${coverageScore >= 80 ? "passing" : coverageScore >= 50 ? "ne
 }
 // src/reports/markdown.ts
 import { DRIFT_CATEGORY_LABELS } from "@openpkg-ts/spec";
-function bar(pct, width = 10) {
+function bar2(pct, width = 10) {
   const filled = Math.round(pct / 100 * width);
   return "█".repeat(filled) + "░".repeat(width - filled);
 }
@@ -244,7 +443,7 @@ function renderMarkdown(stats, options = {}) {
   const lines = [];
   lines.push(`# DocCov Report: ${stats.packageName}@${stats.version}`);
   lines.push("");
-  lines.push(`**Coverage: ${stats.coverageScore}%** \`${bar(stats.coverageScore)}\``);
+  lines.push(`**Coverage: ${stats.coverageScore}%** \`${bar2(stats.coverageScore)}\``);
   lines.push("");
   lines.push("| Metric | Value |");
   lines.push("|--------|-------|");
@@ -259,7 +458,7 @@ function renderMarkdown(stats, options = {}) {
   lines.push("| Signal | Coverage |");
   lines.push("|--------|----------|");
   for (const [sig, s] of Object.entries(stats.signalCoverage)) {
-    lines.push(`| ${sig} | ${s.pct}% \`${bar(s.pct, 8)}\` |`);
+    lines.push(`| ${sig} | ${s.pct}% \`${bar2(s.pct, 8)}\` |`);
   }
   if (stats.byKind.length > 0) {
     lines.push("");
@@ -331,7 +530,7 @@ function renderMarkdown(stats, options = {}) {
 }
 
 // src/reports/html.ts
-function escapeHtml(s) {
+function escapeHtml2(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 function renderHtml(stats, options = {}) {
@@ -341,7 +540,7 @@ function renderHtml(stats, options = {}) {
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>DocCov Report: ${escapeHtml(stats.packageName)}</title>
+  <title>DocCov Report: ${escapeHtml2(stats.packageName)}</title>
   <style>
     :root { --bg: #0d1117; --fg: #c9d1d9; --border: #30363d; --accent: #58a6ff; }
     body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: var(--bg); color: var(--fg); max-width: 900px; margin: 0 auto; padding: 2rem; line-height: 1.6; }
@@ -354,7 +553,7 @@ function renderHtml(stats, options = {}) {
   </style>
 </head>
 <body>
-<pre style="white-space: pre-wrap; font-family: inherit;">${escapeHtml(md)}</pre>
+<pre style="white-space: pre-wrap; font-family: inherit;">${escapeHtml2(md)}</pre>
 </body>
 </html>`;
 }
@@ -467,18 +666,18 @@ function computeStats(spec) {
 }
 // src/reports/writer.ts
 import * as fs from "node:fs";
-import * as path2 from "node:path";
+import * as path3 from "node:path";
 import { DEFAULT_REPORT_DIR, getReportPath } from "@doccov/sdk";
 import chalk from "chalk";
 function writeReport(options) {
   const { format, content, outputPath, cwd = process.cwd(), silent = false } = options;
-  const reportPath = outputPath ? path2.resolve(cwd, outputPath) : path2.resolve(cwd, getReportPath(format));
-  const dir = path2.dirname(reportPath);
+  const reportPath = outputPath ? path3.resolve(cwd, outputPath) : path3.resolve(cwd, getReportPath(format));
+  const dir = path3.dirname(reportPath);
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
   fs.writeFileSync(reportPath, content);
-  const relativePath = path2.relative(cwd, reportPath);
+  const relativePath = path3.relative(cwd, reportPath);
   if (!silent) {
     console.log(chalk.green(`✓ Wrote ${format} report to ${relativePath}`));
   }
@@ -571,6 +770,17 @@ async function parseAssertionsWithLLM(code) {
   }
 }
 
+// src/utils/validation.ts
+function clampPercentage(value, fallback = 80) {
+  if (Number.isNaN(value))
+    return fallback;
+  return Math.min(100, Math.max(0, Math.round(value)));
+}
+function resolveThreshold(cliValue, configValue) {
+  const raw = cliValue ?? configValue;
+  return raw !== undefined ? clampPercentage(Number(raw)) : undefined;
+}
+
 // src/commands/check.ts
 var defaultDependencies = {
   createDocCov: (options) => new DocCov(options),
@@ -617,9 +827,9 @@ function registerCheckCommand(program, dependencies = {}) {
       }
       const config = await loadDocCovConfig(targetDir);
       const minCoverageRaw = options.minCoverage ?? config?.check?.minCoverage;
-      const minCoverage = minCoverageRaw !== undefined ? clampCoverage(minCoverageRaw) : undefined;
+      const minCoverage = minCoverageRaw !== undefined ? clampPercentage(minCoverageRaw) : undefined;
       const maxDriftRaw = options.maxDrift ?? config?.check?.maxDrift;
-      const maxDrift = maxDriftRaw !== undefined ? clampCoverage(maxDriftRaw) : undefined;
+      const maxDrift = maxDriftRaw !== undefined ? clampPercentage(maxDriftRaw) : undefined;
       const resolveExternalTypes = !options.skipResolve;
       let specResult;
       const doccov = createDocCov({
@@ -711,7 +921,7 @@ function registerCheckCommand(program, dependencies = {}) {
                 log(chalk2.gray(`  Skipping ${exp.name}: declaration file`));
                 continue;
               }
-              const filePath = path3.resolve(targetDir, exp.source.file);
+              const filePath = path4.resolve(targetDir, exp.source.file);
               if (!fs2.existsSync(filePath)) {
                 log(chalk2.gray(`  Skipping ${exp.name}: file not found`));
                 continue;
@@ -755,7 +965,7 @@ function registerCheckCommand(program, dependencies = {}) {
                 log(chalk2.bold("Dry run - changes that would be made:"));
                 log("");
                 for (const [filePath, fileEdits] of editsByFile) {
-                  const relativePath = path3.relative(targetDir, filePath);
+                  const relativePath = path4.relative(targetDir, filePath);
                   log(chalk2.cyan(`  ${relativePath}:`));
                   for (const { export: exp, edit, fixes } of fileEdits) {
                     const lineInfo = edit.hasExisting ? `lines ${edit.startLine + 1}-${edit.endLine + 1}` : `line ${edit.startLine + 1}`;
@@ -929,12 +1139,6 @@ function registerCheckCommand(program, dependencies = {}) {
     }
   });
 }
-function clampCoverage(value) {
-  if (Number.isNaN(value)) {
-    return 80;
-  }
-  return Math.min(100, Math.max(0, Math.round(value)));
-}
 function collectDrift(exportsList) {
   const drifts = [];
   for (const entry of exportsList) {
@@ -957,11 +1161,14 @@ function collectDrift(exportsList) {
 
 // src/commands/diff.ts
 import * as fs3 from "node:fs";
-import * as path4 from "node:path";
+import * as path5 from "node:path";
 import {
   diffSpecWithDocs,
+  ensureSpecCoverage,
+  getDiffReportPath,
   getDocsImpactSummary,
   hasDocsImpact,
+  hashString,
   parseMarkdownFiles
 } from "@doccov/sdk";
 import chalk3 from "chalk";
@@ -1033,126 +1240,151 @@ var defaultDependencies2 = {
   log: console.log,
   error: console.error
 };
-var VALID_STRICT_OPTIONS = [
-  "regression",
-  "drift",
-  "docs-impact",
-  "breaking",
-  "undocumented",
-  "all"
-];
-function parseStrictOptions(value) {
-  if (!value)
+var STRICT_PRESETS = {
+  ci: new Set(["breaking", "regression"]),
+  release: new Set(["breaking", "regression", "drift", "docs-impact", "undocumented"]),
+  quality: new Set(["drift", "undocumented"])
+};
+function getStrictChecks(preset) {
+  if (!preset)
     return new Set;
-  const options = value.split(",").map((s) => s.trim().toLowerCase());
-  const result = new Set;
-  for (const opt of options) {
-    if (opt === "all") {
-      for (const o of VALID_STRICT_OPTIONS) {
-        if (o !== "all")
-          result.add(o);
-      }
-    } else if (VALID_STRICT_OPTIONS.includes(opt)) {
-      result.add(opt);
-    }
+  const checks = STRICT_PRESETS[preset];
+  if (!checks) {
+    throw new Error(`Unknown --strict preset: ${preset}. Valid: ci, release, quality`);
   }
-  return result;
+  return checks;
 }
 function registerDiffCommand(program, dependencies = {}) {
   const { readFileSync: readFileSync2, log, error } = {
     ...defaultDependencies2,
     ...dependencies
   };
-  program.command("diff <base> <head>").description("Compare two OpenPkg specs and report coverage delta").option("--format <format>", "Output format: text, json, github, report", "text").option("--strict <options>", "Fail on conditions (comma-separated): regression, drift, docs-impact, breaking, undocumented, all").option("--docs <glob>", "Glob pattern for markdown docs to check for impact", collect, []).option("--ai", "Use AI for deeper analysis and fix suggestions").option("--output <format>", "DEPRECATED: Use --format instead").option("--fail-on-regression", "DEPRECATED: Use --strict regression").option("--fail-on-drift", "DEPRECATED: Use --strict drift").option("--fail-on-docs-impact", "DEPRECATED: Use --strict docs-impact").action(async (base, head, options) => {
+  program.command("diff [base] [head]").description("Compare two OpenPkg specs and detect breaking changes").option("--base <file>", 'Base spec file (the "before" state)').option("--head <file>", 'Head spec file (the "after" state)').option("--format <format>", "Output format: text, json, markdown, html, github", "text").option("--stdout", "Output to stdout instead of writing to .doccov/").option("-o, --output <file>", "Custom output path").option("--cwd <dir>", "Working directory", process.cwd()).option("--limit <n>", "Max items to show in terminal/reports", "10").option("--min-coverage <n>", "Minimum coverage % for HEAD spec (0-100)").option("--max-drift <n>", "Maximum drift % for HEAD spec (0-100)").option("--strict <preset>", "Fail on conditions: ci, release, quality").option("--docs <glob>", "Glob pattern for markdown docs to check for impact", collect, []).option("--ai", "Use AI for deeper analysis and fix suggestions").option("--no-cache", "Bypass cache and force regeneration").action(async (baseArg, headArg, options) => {
     try {
-      const baseSpec = loadSpec(base, readFileSync2);
-      const headSpec = loadSpec(head, readFileSync2);
-      let markdownFiles;
-      let docsPatterns = options.docs;
-      if (!docsPatterns || docsPatterns.length === 0) {
-        const configResult = await loadDocCovConfig(process.cwd());
-        if (configResult?.docs?.include) {
-          docsPatterns = configResult.docs.include;
-          log(chalk3.gray(`Using docs patterns from config: ${docsPatterns.join(", ")}`));
-        }
+      const baseFile = options.base ?? baseArg;
+      const headFile = options.head ?? headArg;
+      if (!baseFile || !headFile) {
+        throw new Error(`Both base and head specs are required.
+` + `Usage: doccov diff <base> <head>
+` + "   or: doccov diff --base main.json --head feature.json");
       }
-      if (docsPatterns && docsPatterns.length > 0) {
-        markdownFiles = await loadMarkdownFiles(docsPatterns);
+      const baseSpec = loadSpec(baseFile, readFileSync2);
+      const headSpec = loadSpec(headFile, readFileSync2);
+      const config = await loadDocCovConfig(options.cwd);
+      const baseHash = hashString(JSON.stringify(baseSpec));
+      const headHash = hashString(JSON.stringify(headSpec));
+      const cacheEnabled = options.cache !== false;
+      const cachedReportPath = path5.resolve(options.cwd, getDiffReportPath(baseHash, headHash, "json"));
+      let diff;
+      let fromCache = false;
+      if (cacheEnabled && fs3.existsSync(cachedReportPath)) {
+        try {
+          const cached = JSON.parse(fs3.readFileSync(cachedReportPath, "utf-8"));
+          diff = cached;
+          fromCache = true;
+        } catch {
+          diff = await generateDiff(baseSpec, headSpec, options, config, log);
+        }
+      } else {
+        diff = await generateDiff(baseSpec, headSpec, options, config, log);
       }
-      const diff = diffSpecWithDocs(baseSpec, headSpec, { markdownFiles });
-      const format = options.format ?? options.output ?? "text";
-      const strictOptions = parseStrictOptions(options.strict);
-      if (options.failOnRegression)
-        strictOptions.add("regression");
-      if (options.failOnDrift)
-        strictOptions.add("drift");
-      if (options.failOnDocsImpact)
-        strictOptions.add("docs-impact");
+      const minCoverage = resolveThreshold(options.minCoverage, config?.check?.minCoverage);
+      const maxDrift = resolveThreshold(options.maxDrift, config?.check?.maxDrift);
+      const format = options.format ?? "text";
+      const limit = parseInt(options.limit, 10) || 10;
+      const checks = getStrictChecks(options.strict);
+      const baseName = path5.basename(baseFile);
+      const headName = path5.basename(headFile);
+      const reportData = {
+        baseName,
+        headName,
+        ...diff
+      };
       switch (format) {
-        case "json":
-          log(JSON.stringify(diff, null, 2));
+        case "text":
+          printSummary(diff, baseName, headName, fromCache, log);
+          if (options.ai && diff.docsImpact && hasDocsImpact(diff)) {
+            await printAISummary(diff, log);
+          }
+          if (!options.stdout) {
+            const jsonPath = getDiffReportPath(baseHash, headHash, "json");
+            if (!fromCache) {
+              writeReport({
+                format: "json",
+                content: JSON.stringify(diff, null, 2),
+                cwd: options.cwd,
+                outputPath: jsonPath,
+                silent: true
+              });
+            }
+            const cacheNote = fromCache ? chalk3.cyan(" (cached)") : "";
+            log(chalk3.dim(`Report: ${jsonPath}`) + cacheNote);
+          }
           break;
-        case "github":
-          printGitHubAnnotations(diff, log);
+        case "json": {
+          const content = JSON.stringify(diff, null, 2);
+          if (options.stdout) {
+            log(content);
+          } else {
+            const outputPath = options.output ?? getDiffReportPath(baseHash, headHash, "json");
+            writeReport({
+              format: "json",
+              content,
+              outputPath,
+              cwd: options.cwd
+            });
+          }
           break;
-        case "report":
-          log(generateHTMLReport(diff));
+        }
+        case "markdown": {
+          const content = renderDiffMarkdown(reportData, { limit });
+          if (options.stdout) {
+            log(content);
+          } else {
+            const outputPath = options.output ?? getDiffReportPath(baseHash, headHash, "markdown");
+            writeReport({
+              format: "markdown",
+              content,
+              outputPath,
+              cwd: options.cwd
+            });
+          }
           break;
-        default:
-          printTextDiff(diff, log, error);
-          if (options.ai && diff.docsImpact && hasDocsImpact(diff)) {
-            if (!isAIDocsAnalysisAvailable()) {
-              log(chalk3.yellow(`
-⚠ AI analysis unavailable (set OPENAI_API_KEY or ANTHROPIC_API_KEY)`));
-            } else {
-              log(chalk3.gray(`
-Generating AI summary...`));
-              const impacts = diff.docsImpact.impactedFiles.flatMap((f) => f.references.map((r) => ({
-                file: f.file,
-                exportName: r.exportName,
-                changeType: r.changeType,
-                context: r.context
-              })));
-              const summary = await generateImpactSummary(impacts);
-              if (summary) {
-                log("");
-                log(chalk3.bold("AI Summary"));
-                log(chalk3.cyan(`  ${summary}`));
-              }
-            }
+        }
+        case "html": {
+          const content = renderDiffHtml(reportData, { limit });
+          if (options.stdout) {
+            log(content);
+          } else {
+            const outputPath = options.output ?? getDiffReportPath(baseHash, headHash, "html");
+            writeReport({
+              format: "html",
+              content,
+              outputPath,
+              cwd: options.cwd
+            });
           }
           break;
+        }
+        case "github":
+          printGitHubAnnotations(diff, log);
+          break;
       }
-      if (strictOptions.has("regression") && diff.coverageDelta < 0) {
-        error(chalk3.red(`
-Coverage regressed by ${Math.abs(diff.coverageDelta)}%`));
-        process.exitCode = 1;
-        return;
-      }
-      if (strictOptions.has("drift") && diff.driftIntroduced > 0) {
-        error(chalk3.red(`
-${diff.driftIntroduced} new drift issue(s) introduced`));
-        process.exitCode = 1;
-        return;
-      }
-      if (strictOptions.has("docs-impact") && hasDocsImpact(diff)) {
-        const summary = getDocsImpactSummary(diff);
-        error(chalk3.red(`
-${summary.totalIssues} docs issue(s) require attention`));
-        process.exitCode = 1;
-        return;
-      }
-      if (strictOptions.has("breaking") && diff.breaking.length > 0) {
-        error(chalk3.red(`
-${diff.breaking.length} breaking change(s) detected`));
-        process.exitCode = 1;
-        return;
-      }
-      if (strictOptions.has("undocumented") && diff.newUndocumented.length > 0) {
-        error(chalk3.red(`
-${diff.newUndocumented.length} new undocumented export(s)`));
+      const failures = validateDiff(diff, headSpec, {
+        minCoverage,
+        maxDrift,
+        checks
+      });
+      if (failures.length > 0) {
+        log(chalk3.red(`
+✗ Check failed`));
+        for (const f of failures) {
+          log(chalk3.red(`  - ${f}`));
+        }
         process.exitCode = 1;
-        return;
+      } else if (options.strict || minCoverage !== undefined || maxDrift !== undefined) {
+        log(chalk3.green(`
+✓ All checks passed`));
       }
     } catch (commandError) {
       error(chalk3.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
@@ -1176,193 +1408,117 @@ async function loadMarkdownFiles(patterns) {
   }
   return parseMarkdownFiles(files);
 }
+async function generateDiff(baseSpec, headSpec, options, config, log) {
+  let markdownFiles;
+  let docsPatterns = options.docs;
+  if (!docsPatterns || docsPatterns.length === 0) {
+    if (config?.docs?.include) {
+      docsPatterns = config.docs.include;
+      log(chalk3.gray(`Using docs patterns from config: ${docsPatterns.join(", ")}`));
+    }
+  }
+  if (docsPatterns && docsPatterns.length > 0) {
+    markdownFiles = await loadMarkdownFiles(docsPatterns);
+  }
+  return diffSpecWithDocs(baseSpec, headSpec, { markdownFiles });
+}
 function loadSpec(filePath, readFileSync2) {
-  const resolvedPath = path4.resolve(filePath);
+  const resolvedPath = path5.resolve(filePath);
   if (!fs3.existsSync(resolvedPath)) {
     throw new Error(`File not found: ${filePath}`);
   }
   try {
     const content = readFileSync2(resolvedPath, "utf-8");
-    return JSON.parse(content);
+    const spec = JSON.parse(content);
+    return ensureSpecCoverage(spec);
   } catch (parseError) {
     throw new Error(`Failed to parse ${filePath}: ${parseError instanceof Error ? parseError.message : parseError}`);
   }
 }
-function printTextDiff(diff, log, _error) {
+function printSummary(diff, baseName, headName, fromCache, log) {
   log("");
-  log(chalk3.bold("DocCov Diff Report"));
+  const cacheIndicator = fromCache ? chalk3.cyan(" (cached)") : "";
+  log(chalk3.bold(`Comparing: ${baseName} → ${headName}`) + cacheIndicator);
   log("─".repeat(40));
-  printCoverage(diff, log);
-  printAPIChanges(diff, log);
-  if (diff.docsImpact) {
-    printDocsRequiringUpdates(diff, log);
-  }
   log("");
-}
-function printCoverage(diff, log) {
   const coverageColor = diff.coverageDelta > 0 ? chalk3.green : diff.coverageDelta < 0 ? chalk3.red : chalk3.gray;
-  const coverageSymbol = diff.coverageDelta > 0 ? "↑" : diff.coverageDelta < 0 ? "↓" : "→";
-  const deltaStr = diff.coverageDelta > 0 ? `+${diff.coverageDelta}` : String(diff.coverageDelta);
-  log("");
-  log(chalk3.bold("Coverage"));
-  log(`  ${diff.oldCoverage}% ${coverageSymbol} ${diff.newCoverage}% ${coverageColor(`(${deltaStr}%)`)}`);
-}
-function printAPIChanges(diff, log) {
-  const hasChanges = diff.breaking.length > 0 || diff.nonBreaking.length > 0 || diff.memberChanges && diff.memberChanges.length > 0;
-  if (!hasChanges)
-    return;
-  log("");
-  log(chalk3.bold("API Changes"));
-  const membersByClass = groupMemberChangesByClass(diff.memberChanges ?? []);
-  const classesWithMembers = new Set(membersByClass.keys());
-  for (const [className, changes] of membersByClass) {
-    const categorized = diff.categorizedBreaking?.find((c) => c.id === className);
-    const isHighSeverity = categorized?.severity === "high";
-    const label = isHighSeverity ? chalk3.red(" [BREAKING]") : chalk3.yellow(" [CHANGED]");
-    log(chalk3.cyan(`  ${className}`) + label);
-    const removed = changes.filter((c) => c.changeType === "removed");
-    for (const mc of removed) {
-      const suggestion = mc.suggestion ? chalk3.gray(` → ${mc.suggestion}`) : "";
-      log(chalk3.red(`    ✖ ${mc.memberName}()`) + suggestion);
-    }
-    const changed = changes.filter((c) => c.changeType === "signature-changed");
-    for (const mc of changed) {
-      log(chalk3.yellow(`    ~ ${mc.memberName}() signature changed`));
-      if (mc.oldSignature && mc.newSignature && mc.oldSignature !== mc.newSignature) {
-        log(chalk3.gray(`        was: ${mc.oldSignature}`));
-        log(chalk3.gray(`        now: ${mc.newSignature}`));
-      }
-    }
-    const added = changes.filter((c) => c.changeType === "added");
-    if (added.length > 0) {
-      const addedNames = added.map((a) => `${a.memberName}()`).join(", ");
-      log(chalk3.green(`    + ${addedNames}`));
-    }
-  }
-  const nonClassBreaking = (diff.categorizedBreaking ?? []).filter((c) => !classesWithMembers.has(c.id));
-  const typeChanges = nonClassBreaking.filter((c) => c.kind === "interface" || c.kind === "type" || c.kind === "enum");
-  const functionChanges = nonClassBreaking.filter((c) => c.kind === "function");
-  const otherChanges = nonClassBreaking.filter((c) => !["interface", "type", "enum", "function"].includes(c.kind));
-  if (functionChanges.length > 0) {
-    log("");
-    log(chalk3.red(`  Function Changes (${functionChanges.length}):`));
-    for (const fc of functionChanges.slice(0, 3)) {
-      const reason = fc.reason === "removed" ? "removed" : "signature changed";
-      log(chalk3.red(`    ✖ ${fc.name} (${reason})`));
-    }
-    if (functionChanges.length > 3) {
-      log(chalk3.gray(`    ... and ${functionChanges.length - 3} more`));
-    }
-  }
-  if (typeChanges.length > 0) {
-    log("");
-    log(chalk3.yellow(`  Type/Interface Changes (${typeChanges.length}):`));
-    const typeNames = typeChanges.slice(0, 5).map((t) => t.name);
-    log(chalk3.yellow(`    ~ ${typeNames.join(", ")}${typeChanges.length > 5 ? ", ..." : ""}`));
-  }
-  if (otherChanges.length > 0) {
-    log("");
-    log(chalk3.gray(`  Other Changes (${otherChanges.length}):`));
-    const otherNames = otherChanges.slice(0, 3).map((o) => o.name);
-    log(chalk3.gray(`    ${otherNames.join(", ")}${otherChanges.length > 3 ? ", ..." : ""}`));
-  }
-  if (diff.nonBreaking.length > 0) {
-    const undocCount = diff.newUndocumented.length;
-    const undocSuffix = undocCount > 0 ? chalk3.yellow(` (${undocCount} undocumented)`) : "";
-    log("");
-    log(chalk3.green(`  New Exports (${diff.nonBreaking.length})`) + undocSuffix);
-    const exportNames = diff.nonBreaking.slice(0, 3);
-    log(chalk3.green(`    + ${exportNames.join(", ")}${diff.nonBreaking.length > 3 ? ", ..." : ""}`));
+  const coverageSign = diff.coverageDelta > 0 ? "+" : "";
+  log(`  Coverage:   ${diff.oldCoverage}% → ${diff.newCoverage}% ${coverageColor(`(${coverageSign}${diff.coverageDelta}%)`)}`);
+  const breakingCount = diff.breaking.length;
+  const highSeverity = diff.categorizedBreaking?.filter((c) => c.severity === "high").length ?? 0;
+  if (breakingCount > 0) {
+    const severityNote = highSeverity > 0 ? chalk3.red(` (${highSeverity} high severity)`) : "";
+    log(`  Breaking:   ${chalk3.red(breakingCount)} changes${severityNote}`);
+  } else {
+    log(`  Breaking:   ${chalk3.green("0")} changes`);
+  }
+  const newCount = diff.nonBreaking.length;
+  const undocCount = diff.newUndocumented.length;
+  if (newCount > 0) {
+    const undocNote = undocCount > 0 ? chalk3.yellow(` (${undocCount} undocumented)`) : "";
+    log(`  New:        ${chalk3.green(newCount)} exports${undocNote}`);
   }
   if (diff.driftIntroduced > 0 || diff.driftResolved > 0) {
-    log("");
     const parts = [];
-    if (diff.driftIntroduced > 0) {
-      parts.push(chalk3.red(`+${diff.driftIntroduced} drift`));
-    }
-    if (diff.driftResolved > 0) {
-      parts.push(chalk3.green(`-${diff.driftResolved} resolved`));
-    }
-    log(`  Drift: ${parts.join(", ")}`);
+    if (diff.driftIntroduced > 0)
+      parts.push(chalk3.red(`+${diff.driftIntroduced}`));
+    if (diff.driftResolved > 0)
+      parts.push(chalk3.green(`-${diff.driftResolved}`));
+    log(`  Drift:      ${parts.join(", ")}`);
   }
+  log("");
 }
-function printDocsRequiringUpdates(diff, log) {
-  if (!diff.docsImpact)
+async function printAISummary(diff, log) {
+  if (!isAIDocsAnalysisAvailable()) {
+    log(chalk3.yellow(`
+⚠ AI analysis unavailable (set OPENAI_API_KEY or ANTHROPIC_API_KEY)`));
     return;
-  const { impactedFiles, missingDocs, stats } = diff.docsImpact;
-  log("");
-  log(chalk3.bold("Docs Requiring Updates"));
-  log(chalk3.gray(`  Scanned ${stats.filesScanned} files, ${stats.codeBlocksFound} code blocks`));
-  if (impactedFiles.length === 0 && missingDocs.length === 0) {
-    log(chalk3.green("  ✓ No updates needed"));
+  }
+  if (!diff.docsImpact)
     return;
+  log(chalk3.gray(`
+Generating AI summary...`));
+  const impacts = diff.docsImpact.impactedFiles.flatMap((f) => f.references.map((r) => ({
+    file: f.file,
+    exportName: r.exportName,
+    changeType: r.changeType,
+    context: r.context
+  })));
+  const summary = await generateImpactSummary(impacts);
+  if (summary) {
+    log("");
+    log(chalk3.bold("AI Summary"));
+    log(chalk3.cyan(`  ${summary}`));
   }
-  const sortedFiles = [...impactedFiles].sort((a, b) => b.references.length - a.references.length);
-  const actionableFiles = [];
-  const instantiationOnlyFiles = [];
-  for (const file of sortedFiles) {
-    const hasActionableRefs = file.references.some((r) => r.memberName && !r.isInstantiation || !r.memberName && !r.isInstantiation);
-    if (hasActionableRefs) {
-      actionableFiles.push(file);
-    } else {
-      instantiationOnlyFiles.push(file);
-    }
+}
+function validateDiff(diff, headSpec, options) {
+  const { minCoverage, maxDrift, checks } = options;
+  const failures = [];
+  const headExportsWithDrift = new Set((headSpec.exports ?? []).filter((e) => e.docs?.drift?.length).map((e) => e.name)).size;
+  const headDriftScore = headSpec.exports?.length ? Math.round(headExportsWithDrift / headSpec.exports.length * 100) : 0;
+  if (minCoverage !== undefined && diff.newCoverage < minCoverage) {
+    failures.push(`Coverage ${diff.newCoverage}% below minimum ${minCoverage}%`);
   }
-  for (const file of actionableFiles.slice(0, 6)) {
-    const filename = path4.basename(file.file);
-    const issueCount = file.references.length;
-    log("");
-    log(chalk3.yellow(`  ${filename}`) + chalk3.gray(` (${issueCount} issue${issueCount > 1 ? "s" : ""})`));
-    const actionableRefs = file.references.filter((r) => !r.isInstantiation);
-    for (const ref of actionableRefs.slice(0, 4)) {
-      if (ref.memberName) {
-        const action = ref.changeType === "method-removed" ? "→" : "~";
-        const hint = ref.replacementSuggestion ?? (ref.changeType === "method-changed" ? "signature changed" : "removed");
-        log(chalk3.gray(`    L${ref.line}: ${ref.memberName}() ${action} ${hint}`));
-      } else {
-        const action = ref.changeType === "removed" ? "→" : "~";
-        const hint = ref.changeType === "removed" ? "removed" : ref.changeType === "signature-changed" ? "signature changed" : "changed";
-        log(chalk3.gray(`    L${ref.line}: ${ref.exportName} ${action} ${hint}`));
-      }
-    }
-    if (actionableRefs.length > 4) {
-      log(chalk3.gray(`    ... and ${actionableRefs.length - 4} more`));
-    }
+  if (maxDrift !== undefined && headDriftScore > maxDrift) {
+    failures.push(`Drift ${headDriftScore}% exceeds maximum ${maxDrift}%`);
   }
-  if (actionableFiles.length > 6) {
-    log(chalk3.gray(`  ... and ${actionableFiles.length - 6} more files with method changes`));
+  if (checks.has("regression") && diff.coverageDelta < 0) {
+    failures.push(`Coverage regressed by ${Math.abs(diff.coverageDelta)}%`);
   }
-  if (instantiationOnlyFiles.length > 0) {
-    log("");
-    const fileNames = instantiationOnlyFiles.slice(0, 4).map((f) => path4.basename(f.file));
-    const suffix = instantiationOnlyFiles.length > 4 ? ", ..." : "";
-    log(chalk3.gray(`  ${instantiationOnlyFiles.length} file(s) with class instantiation to review:`));
-    log(chalk3.gray(`    ${fileNames.join(", ")}${suffix}`));
+  if (checks.has("breaking") && diff.breaking.length > 0) {
+    failures.push(`${diff.breaking.length} breaking change(s)`);
   }
-  const { allUndocumented } = diff.docsImpact;
-  if (missingDocs.length > 0) {
-    log("");
-    log(chalk3.yellow(`  New exports missing docs (${missingDocs.length}):`));
-    const names = missingDocs.slice(0, 4);
-    log(chalk3.gray(`    ${names.join(", ")}${missingDocs.length > 4 ? ", ..." : ""}`));
+  if (checks.has("drift") && diff.driftIntroduced > 0) {
+    failures.push(`${diff.driftIntroduced} new drift issue(s)`);
   }
-  if (allUndocumented && allUndocumented.length > 0) {
-    const existingUndocumented = allUndocumented.filter((name) => !missingDocs.includes(name));
-    log("");
-    log(chalk3.gray(`  Total undocumented exports: ${allUndocumented.length}/${stats.totalExports} (${Math.round((1 - allUndocumented.length / stats.totalExports) * 100)}% documented)`));
-    if (existingUndocumented.length > 0 && existingUndocumented.length <= 10) {
-      log(chalk3.gray(`    ${existingUndocumented.slice(0, 6).join(", ")}${existingUndocumented.length > 6 ? ", ..." : ""}`));
-    }
+  if (checks.has("undocumented") && diff.newUndocumented.length > 0) {
+    failures.push(`${diff.newUndocumented.length} undocumented export(s)`);
   }
-}
-function groupMemberChangesByClass(memberChanges) {
-  const byClass = new Map;
-  for (const mc of memberChanges) {
-    const list = byClass.get(mc.className) ?? [];
-    list.push(mc);
-    byClass.set(mc.className, list);
+  if (checks.has("docs-impact") && hasDocsImpact(diff)) {
+    const summary = getDocsImpactSummary(diff);
+    failures.push(`${summary.totalIssues} docs issue(s)`);
   }
-  return byClass;
+  return failures;
 }
 function printGitHubAnnotations(diff, log) {
   if (diff.coverageDelta !== 0) {
@@ -1410,159 +1566,6 @@ function printGitHubAnnotations(diff, log) {
     log(`::warning title=Drift Detected::${diff.driftIntroduced} new drift issue(s) introduced`);
   }
 }
-function generateHTMLReport(diff) {
-  const coverageClass = diff.coverageDelta > 0 ? "positive" : diff.coverageDelta < 0 ? "negative" : "neutral";
-  const coverageSign = diff.coverageDelta > 0 ? "+" : "";
-  let html = `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>DocCov Diff Report</title>
-  <style>
-    * { box-sizing: border-box; margin: 0; padding: 0; }
-    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0d1117; color: #c9d1d9; padding: 2rem; line-height: 1.5; }
-    .container { max-width: 900px; margin: 0 auto; }
-    h1 { font-size: 1.5rem; margin-bottom: 1.5rem; color: #f0f6fc; }
-    h2 { font-size: 1.1rem; margin: 1.5rem 0 0.75rem; color: #f0f6fc; border-bottom: 1px solid #30363d; padding-bottom: 0.5rem; }
-    .card { background: #161b22; border: 1px solid #30363d; border-radius: 6px; padding: 1rem; margin-bottom: 1rem; }
-    .metric { display: flex; justify-content: space-between; align-items: center; padding: 0.5rem 0; }
-    .metric-label { color: #8b949e; }
-    .metric-value { font-weight: 600; }
-    .positive { color: #3fb950; }
-    .negative { color: #f85149; }
-    .neutral { color: #8b949e; }
-    .warning { color: #d29922; }
-    .badge { display: inline-block; padding: 0.125rem 0.5rem; border-radius: 12px; font-size: 0.75rem; font-weight: 500; }
-    .badge-breaking { background: #f8514933; color: #f85149; }
-    .badge-changed { background: #d2992233; color: #d29922; }
-    .badge-added { background: #3fb95033; color: #3fb950; }
-    .file-item { padding: 0.5rem; margin: 0.25rem 0; background: #0d1117; border-radius: 4px; }
-    .file-name { font-family: monospace; font-size: 0.9rem; }
-    .ref-list { margin-top: 0.5rem; padding-left: 1rem; font-size: 0.85rem; color: #8b949e; }
-    .ref-item { margin: 0.25rem 0; }
-    ul { list-style: none; }
-    li { padding: 0.25rem 0; }
-    code { font-family: monospace; background: #0d1117; padding: 0.125rem 0.375rem; border-radius: 3px; font-size: 0.9rem; }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <h1>\uD83D\uDCCA DocCov Diff Report</h1>
-
-    <div class="card">
-      <div class="metric">
-        <span class="metric-label">Coverage</span>
-        <span class="metric-value ${coverageClass}">${diff.oldCoverage}% → ${diff.newCoverage}% (${coverageSign}${diff.coverageDelta}%)</span>
-      </div>
-      <div class="metric">
-        <span class="metric-label">Breaking Changes</span>
-        <span class="metric-value ${diff.breaking.length > 0 ? "negative" : "neutral"}">${diff.breaking.length}</span>
-      </div>
-      <div class="metric">
-        <span class="metric-label">New Exports</span>
-        <span class="metric-value positive">${diff.nonBreaking.length}</span>
-      </div>
-      <div class="metric">
-        <span class="metric-label">Undocumented</span>
-        <span class="metric-value ${diff.newUndocumented.length > 0 ? "warning" : "neutral"}">${diff.newUndocumented.length}</span>
-      </div>
-    </div>`;
-  if (diff.breaking.length > 0) {
-    html += `
-    <h2>Breaking Changes</h2>
-    <div class="card">
-      <ul>`;
-    for (const item of diff.categorizedBreaking ?? []) {
-      const badgeClass = item.severity === "high" ? "badge-breaking" : "badge-changed";
-      html += `
-        <li><code>${item.name}</code> <span class="badge ${badgeClass}">${item.reason}</span></li>`;
-    }
-    html += `
-      </ul>
-    </div>`;
-  }
-  if (diff.memberChanges && diff.memberChanges.length > 0) {
-    html += `
-    <h2>Member Changes</h2>
-    <div class="card">
-      <ul>`;
-    for (const mc of diff.memberChanges) {
-      const badgeClass = mc.changeType === "removed" ? "badge-breaking" : mc.changeType === "added" ? "badge-added" : "badge-changed";
-      const suggestion = mc.suggestion ? ` → ${mc.suggestion}` : "";
-      html += `
-        <li><code>${mc.className}.${mc.memberName}()</code> <span class="badge ${badgeClass}">${mc.changeType}</span>${suggestion}</li>`;
-    }
-    html += `
-      </ul>
-    </div>`;
-  }
-  if (diff.docsImpact && diff.docsImpact.impactedFiles.length > 0) {
-    html += `
-    <h2>Documentation Impact</h2>
-    <div class="card">`;
-    for (const file of diff.docsImpact.impactedFiles.slice(0, 10)) {
-      const filename = path4.basename(file.file);
-      html += `
-      <div class="file-item">
-        <div class="file-name">\uD83D\uDCC4 ${filename} <span class="neutral">(${file.references.length} issue${file.references.length > 1 ? "s" : ""})</span></div>
-        <div class="ref-list">`;
-      for (const ref of file.references.slice(0, 5)) {
-        const name = ref.memberName ? `${ref.memberName}()` : ref.exportName;
-        const change = ref.changeType === "removed" || ref.changeType === "method-removed" ? "removed" : "signature changed";
-        html += `
-          <div class="ref-item">Line ${ref.line}: <code>${name}</code> ${change}</div>`;
-      }
-      if (file.references.length > 5) {
-        html += `
-          <div class="ref-item neutral">... and ${file.references.length - 5} more</div>`;
-      }
-      html += `
-        </div>
-      </div>`;
-    }
-    html += `
-    </div>`;
-  }
-  const hasNewUndocumented = diff.newUndocumented.length > 0;
-  const hasAllUndocumented = diff.docsImpact?.allUndocumented && diff.docsImpact.allUndocumented.length > 0;
-  if (hasNewUndocumented || hasAllUndocumented) {
-    html += `
-    <h2>Missing Documentation</h2>
-    <div class="card">`;
-    if (hasNewUndocumented) {
-      html += `
-      <p class="warning">New exports missing docs (${diff.newUndocumented.length}):</p>
-      <ul>`;
-      for (const name of diff.newUndocumented.slice(0, 10)) {
-        html += `
-        <li><code>${name}</code></li>`;
-      }
-      if (diff.newUndocumented.length > 10) {
-        html += `
-        <li class="neutral">... and ${diff.newUndocumented.length - 10} more</li>`;
-      }
-      html += `
-      </ul>`;
-    }
-    if (diff.docsImpact?.stats) {
-      const { stats, allUndocumented } = diff.docsImpact;
-      const docPercent = Math.round((1 - (allUndocumented?.length ?? 0) / stats.totalExports) * 100);
-      html += `
-      <div class="metric" style="margin-top: 1rem; border-top: 1px solid #30363d; padding-top: 1rem;">
-        <span class="metric-label">Total Documentation Coverage</span>
-        <span class="metric-value ${docPercent >= 80 ? "positive" : docPercent >= 50 ? "warning" : "negative"}">${stats.documentedExports}/${stats.totalExports} (${docPercent}%)</span>
-      </div>`;
-    }
-    html += `
-    </div>`;
-  }
-  html += `
-  </div>
-</body>
-</html>`;
-  return html;
-}
 
 // src/commands/info.ts
 import { DocCov as DocCov2, enrichSpec as enrichSpec2, NodeFileSystem as NodeFileSystem2, resolveTarget as resolveTarget2 } from "@doccov/sdk";
@@ -1603,7 +1606,7 @@ function registerInfoCommand(program) {
 
 // src/commands/init.ts
 import * as fs4 from "node:fs";
-import * as path5 from "node:path";
+import * as path6 from "node:path";
 import chalk5 from "chalk";
 var defaultDependencies3 = {
   fileExists: fs4.existsSync,
@@ -1618,7 +1621,7 @@ function registerInitCommand(program, dependencies = {}) {
     ...dependencies
   };
   program.command("init").description("Create a DocCov configuration file").option("--cwd <dir>", "Working directory", process.cwd()).option("--format <format>", "Config format: auto, mjs, js, cjs", "auto").action((options) => {
-    const cwd = path5.resolve(options.cwd);
+    const cwd = path6.resolve(options.cwd);
     const formatOption = String(options.format ?? "auto").toLowerCase();
     if (!isValidFormat(formatOption)) {
       error(chalk5.red(`Invalid format "${formatOption}". Use auto, mjs, js, or cjs.`));
@@ -1627,7 +1630,7 @@ function registerInitCommand(program, dependencies = {}) {
     }
     const existing = findExistingConfig(cwd, fileExists2);
     if (existing) {
-      error(chalk5.red(`A DocCov config already exists at ${path5.relative(cwd, existing) || "./doccov.config.*"}.`));
+      error(chalk5.red(`A DocCov config already exists at ${path6.relative(cwd, existing) || "./doccov.config.*"}.`));
       process.exitCode = 1;
       return;
     }
@@ -1637,7 +1640,7 @@ function registerInitCommand(program, dependencies = {}) {
       log(chalk5.yellow('Package is not marked as "type": "module"; creating doccov.config.js may require enabling ESM.'));
     }
     const fileName = `doccov.config.${targetFormat}`;
-    const outputPath = path5.join(cwd, fileName);
+    const outputPath = path6.join(cwd, fileName);
     if (fileExists2(outputPath)) {
       error(chalk5.red(`Cannot create ${fileName}; file already exists.`));
       process.exitCode = 1;
@@ -1645,18 +1648,18 @@ function registerInitCommand(program, dependencies = {}) {
     }
     const template = buildTemplate(targetFormat);
     writeFileSync3(outputPath, template, { encoding: "utf8" });
-    log(chalk5.green(`✓ Created ${path5.relative(process.cwd(), outputPath)}`));
+    log(chalk5.green(`✓ Created ${path6.relative(process.cwd(), outputPath)}`));
   });
 }
 var isValidFormat = (value) => {
   return value === "auto" || value === "mjs" || value === "js" || value === "cjs";
 };
 var findExistingConfig = (cwd, fileExists2) => {
-  let current = path5.resolve(cwd);
-  const { root } = path5.parse(current);
+  let current = path6.resolve(cwd);
+  const { root } = path6.parse(current);
   while (true) {
     for (const candidate of DOCCOV_CONFIG_FILENAMES) {
-      const candidatePath = path5.join(current, candidate);
+      const candidatePath = path6.join(current, candidate);
       if (fileExists2(candidatePath)) {
         return candidatePath;
       }
@@ -1664,7 +1667,7 @@ var findExistingConfig = (cwd, fileExists2) => {
     if (current === root) {
       break;
     }
-    current = path5.dirname(current);
+    current = path6.dirname(current);
   }
   return null;
 };
@@ -1686,17 +1689,17 @@ var detectPackageType = (cwd, fileExists2, readFileSync3) => {
   return;
 };
 var findNearestPackageJson = (cwd, fileExists2) => {
-  let current = path5.resolve(cwd);
-  const { root } = path5.parse(current);
+  let current = path6.resolve(cwd);
+  const { root } = path6.parse(current);
   while (true) {
-    const candidate = path5.join(current, "package.json");
+    const candidate = path6.join(current, "package.json");
     if (fileExists2(candidate)) {
       return candidate;
     }
     if (current === root) {
       break;
     }
-    current = path5.dirname(current);
+    current = path6.dirname(current);
   }
   return null;
 };
@@ -1754,513 +1757,21 @@ var buildTemplate = (format) => {
 `);
 };
 
-// src/commands/scan.ts
-import * as fs6 from "node:fs";
-import * as fsPromises from "node:fs/promises";
-import * as os from "node:os";
-import * as path7 from "node:path";
-import {
-  buildCloneUrl,
-  buildDisplayUrl,
-  DocCov as DocCov3,
-  detectBuildInfo,
-  detectEntryPoint,
-  detectMonorepo,
-  detectPackageManager,
-  extractSpecSummary,
-  findPackageByName,
-  formatPackageList,
-  getInstallCommand,
-  NodeFileSystem as NodeFileSystem3,
-  parseGitHubUrl
-} from "@doccov/sdk";
-import {
-  DRIFT_CATEGORIES as DRIFT_CATEGORIES3,
-  DRIFT_CATEGORY_LABELS as DRIFT_CATEGORY_LABELS2
-} from "@openpkg-ts/spec";
-import chalk6 from "chalk";
-import { simpleGit } from "simple-git";
-
-// src/utils/llm-build-plan.ts
+// src/commands/spec.ts
 import * as fs5 from "node:fs";
-import * as path6 from "node:path";
-import { createAnthropic as createAnthropic3 } from "@ai-sdk/anthropic";
-import { createOpenAI as createOpenAI3 } from "@ai-sdk/openai";
-import { generateObject as generateObject3 } from "ai";
-import { z as z4 } from "zod";
-var BuildPlanSchema = z4.object({
-  installCommand: z4.string().optional().describe("Additional install command if needed"),
-  buildCommands: z4.array(z4.string()).describe('Build steps to run, e.g. ["npm run build:wasm"]'),
-  entryPoint: z4.string().describe("Path to TS/TSX entry file after build"),
-  notes: z4.string().optional().describe("Caveats or warnings")
-});
-var CONTEXT_FILES = [
-  "package.json",
-  "README.md",
-  "README",
-  "tsconfig.json",
-  "Cargo.toml",
-  ".nvmrc",
-  ".node-version",
-  "pnpm-workspace.yaml",
-  "lerna.json",
-  "wasm-pack.json"
-];
-var MAX_FILE_CHARS = 2000;
-function getModel3() {
-  const provider = process.env.DOCCOV_LLM_PROVIDER?.toLowerCase();
-  if (provider === "anthropic" || process.env.ANTHROPIC_API_KEY) {
-    const anthropic = createAnthropic3();
-    return anthropic("claude-sonnet-4-20250514");
-  }
-  const openai = createOpenAI3();
-  return openai("gpt-4o-mini");
-}
-async function gatherContextFiles(repoDir) {
-  const sections = [];
-  for (const fileName of CONTEXT_FILES) {
-    const filePath = path6.join(repoDir, fileName);
-    if (fs5.existsSync(filePath)) {
-      try {
-        let content = fs5.readFileSync(filePath, "utf-8");
-        if (content.length > MAX_FILE_CHARS) {
-          content = `${content.slice(0, MAX_FILE_CHARS)}
-... (truncated)`;
-        }
-        sections.push(`--- ${fileName} ---
-${content}`);
-      } catch {}
-    }
-  }
-  return sections.join(`
-
-`);
-}
-var BUILD_PLAN_PROMPT = (context) => `Analyze this project to determine how to build it for TypeScript API analysis.
-
-The standard entry detection failed. This might be a WASM project, unusual monorepo, or require a build step before the TypeScript entry point exists.
-
-<files>
-${context}
-</files>
-
-Return:
-- buildCommands: Commands to run in order (e.g., ["npm run build:wasm", "npm run build"]). Empty array if no build needed.
-- entryPoint: Path to the TypeScript entry file AFTER build completes (e.g., "src/index.ts" or "pkg/index.d.ts")
-- installCommand: Additional install command if needed beyond what was already run
-- notes: Any caveats (e.g., "requires Rust/wasm-pack installed")
-
-Important:
-- Look for build scripts in package.json that might generate TypeScript bindings
-- Check README for build instructions
-- For WASM projects, look for wasm-pack or similar tooling
-- The entry point should be a .ts, .tsx, or .d.ts file`;
-async function generateBuildPlan(repoDir) {
-  const hasApiKey = process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY;
-  if (!hasApiKey) {
-    return null;
-  }
-  const context = await gatherContextFiles(repoDir);
-  if (!context.trim()) {
-    return null;
-  }
-  const model = getModel3();
-  const { object } = await generateObject3({
-    model,
-    schema: BuildPlanSchema,
-    prompt: BUILD_PLAN_PROMPT(context)
-  });
-  return object;
-}
-
-// src/commands/scan.ts
-var defaultDependencies4 = {
-  createDocCov: (options) => new DocCov3(options),
-  log: console.log,
-  error: console.error
-};
-function registerScanCommand(program, dependencies = {}) {
-  const { createDocCov, log, error } = {
-    ...defaultDependencies4,
-    ...dependencies
-  };
-  program.command("scan <url>").description("Analyze docs coverage for any public GitHub repository").option("--ref <branch>", "Branch or tag to analyze").option("--package <name>", "Target package in monorepo").option("--output <format>", "Output format: text or json", "text").option("--no-cleanup", "Keep cloned repo (for debugging)").option("--skip-install", "Skip dependency installation (faster, but may limit type resolution)").option("--skip-resolve", "Skip external type resolution from node_modules").option("--save-spec <path>", "Save full OpenPkg spec to file").action(async (url, options) => {
-    let tempDir;
-    try {
-      const parsed = parseGitHubUrl(url, options.ref ?? "main");
-      const cloneUrl = buildCloneUrl(parsed);
-      const displayUrl = buildDisplayUrl(parsed);
-      log("");
-      log(chalk6.bold(`Scanning ${displayUrl}`));
-      log(chalk6.gray(`Branch/tag: ${parsed.ref}`));
-      log("");
-      tempDir = path7.join(os.tmpdir(), `doccov-scan-${Date.now()}-${Math.random().toString(36).slice(2)}`);
-      fs6.mkdirSync(tempDir, { recursive: true });
-      process.stdout.write(chalk6.cyan(`> Cloning ${parsed.owner}/${parsed.repo}...
-`));
-      try {
-        const git = simpleGit({
-          timeout: {
-            block: 30000
-          }
-        });
-        const originalEnv = { ...process.env };
-        process.env.GIT_TERMINAL_PROMPT = "0";
-        process.env.GIT_ASKPASS = "echo";
-        try {
-          await git.clone(cloneUrl, tempDir, [
-            "--depth",
-            "1",
-            "--branch",
-            parsed.ref,
-            "--single-branch"
-          ]);
-        } finally {
-          process.env = originalEnv;
-        }
-        process.stdout.write(chalk6.green(`✓ Cloned ${parsed.owner}/${parsed.repo}
-`));
-      } catch (cloneError) {
-        process.stdout.write(chalk6.red(`✗ Failed to clone repository
-`));
-        const message = cloneError instanceof Error ? cloneError.message : String(cloneError);
-        if (message.includes("Authentication failed") || message.includes("could not read Username") || message.includes("terminal prompts disabled") || message.includes("Invalid username or password") || message.includes("Permission denied")) {
-          throw new Error(`Authentication required: This repository appears to be private. ` + `Public repositories only are currently supported.
-` + `Repository: ${displayUrl}`);
-        }
-        if (message.includes("not found") || message.includes("404")) {
-          throw new Error(`Repository not accessible or does not exist: ${displayUrl}
-` + `Note: Private repositories are not currently supported.`);
-        }
-        if (message.includes("Could not find remote branch")) {
-          throw new Error(`Branch or tag not found: ${parsed.ref}`);
-        }
-        throw new Error(`Clone failed: ${message}`);
-      }
-      const fileSystem = new NodeFileSystem3(tempDir);
-      if (options.skipInstall) {
-        log(chalk6.gray("Skipping dependency installation (--skip-install)"));
-      } else {
-        process.stdout.write(chalk6.cyan(`> Installing dependencies...
-`));
-        const installErrors = [];
-        try {
-          const { execSync } = await import("node:child_process");
-          const pmInfo = await detectPackageManager(fileSystem);
-          const installCmd = getInstallCommand(pmInfo);
-          const cmdString = installCmd.join(" ");
-          let installed = false;
-          if (pmInfo.lockfile) {
-            try {
-              execSync(cmdString, {
-                cwd: tempDir,
-                stdio: "pipe",
-                timeout: 180000
-              });
-              installed = true;
-            } catch (cmdError) {
-              const stderr = cmdError?.stderr?.toString() ?? "";
-              const msg = cmdError instanceof Error ? cmdError.message : String(cmdError);
-              installErrors.push(`[${cmdString}] ${stderr.slice(0, 150) || msg.slice(0, 150)}`);
-            }
-          }
-          if (!installed) {
-            try {
-              execSync("bun install", {
-                cwd: tempDir,
-                stdio: "pipe",
-                timeout: 120000
-              });
-              installed = true;
-            } catch (bunError) {
-              const stderr = bunError?.stderr?.toString() ?? "";
-              const msg = bunError instanceof Error ? bunError.message : String(bunError);
-              installErrors.push(`[bun install] ${stderr.slice(0, 150) || msg.slice(0, 150)}`);
-              try {
-                execSync("npm install --legacy-peer-deps --ignore-scripts", {
-                  cwd: tempDir,
-                  stdio: "pipe",
-                  timeout: 180000
-                });
-                installed = true;
-              } catch (npmError) {
-                const npmStderr = npmError?.stderr?.toString() ?? "";
-                const npmMsg = npmError instanceof Error ? npmError.message : String(npmError);
-                installErrors.push(`[npm install] ${npmStderr.slice(0, 150) || npmMsg.slice(0, 150)}`);
-              }
-            }
-          }
-          if (installed) {
-            process.stdout.write(chalk6.green(`✓ Dependencies installed
-`));
-          } else {
-            process.stdout.write(chalk6.yellow(`⚠ Could not install dependencies (analysis may be limited)
-`));
-            for (const err of installErrors) {
-              log(chalk6.gray(`  ${err}`));
-            }
-          }
-        } catch (outerError) {
-          const msg = outerError instanceof Error ? outerError.message : String(outerError);
-          process.stdout.write(chalk6.yellow(`⚠ Could not install dependencies: ${msg.slice(0, 100)}
-`));
-          for (const err of installErrors) {
-            log(chalk6.gray(`  ${err}`));
-          }
-        }
-      }
-      let targetDir = tempDir;
-      let packageName;
-      const mono = await detectMonorepo(fileSystem);
-      if (mono.isMonorepo) {
-        if (!options.package) {
-          error("");
-          error(chalk6.red(`Monorepo detected with ${mono.packages.length} packages. Specify target with --package:`));
-          error("");
-          error(formatPackageList(mono.packages));
-          error("");
-          throw new Error("Monorepo requires --package flag");
-        }
-        const pkg = findPackageByName(mono.packages, options.package);
-        if (!pkg) {
-          error("");
-          error(chalk6.red(`Package "${options.package}" not found. Available packages:`));
-          error("");
-          error(formatPackageList(mono.packages));
-          error("");
-          throw new Error(`Package not found: ${options.package}`);
-        }
-        targetDir = path7.join(tempDir, pkg.path);
-        packageName = pkg.name;
-        log(chalk6.gray(`Analyzing package: ${packageName}`));
-      }
-      process.stdout.write(chalk6.cyan(`> Detecting entry point...
-`));
-      let entryPath;
-      const targetFs = mono.isMonorepo ? new NodeFileSystem3(targetDir) : fileSystem;
-      let buildFailed = false;
-      const runLlmFallback = async (reason) => {
-        process.stdout.write(chalk6.cyan(`> ${reason}, trying LLM fallback...
-`));
-        const plan = await generateBuildPlan(targetDir);
-        if (!plan) {
-          return null;
-        }
-        if (plan.buildCommands.length > 0) {
-          const { execSync } = await import("node:child_process");
-          for (const cmd of plan.buildCommands) {
-            log(chalk6.gray(`  Running: ${cmd}`));
-            try {
-              execSync(cmd, { cwd: targetDir, stdio: "pipe", timeout: 300000 });
-            } catch (buildError) {
-              buildFailed = true;
-              const msg = buildError instanceof Error ? buildError.message : String(buildError);
-              if (msg.includes("rustc") || msg.includes("cargo") || msg.includes("wasm-pack")) {
-                log(chalk6.yellow(`  ⚠ Build requires Rust toolchain (not available)`));
-              } else if (msg.includes("rimraf") || msg.includes("command not found")) {
-                log(chalk6.yellow(`  ⚠ Build failed: missing dependencies`));
-              } else {
-                log(chalk6.yellow(`  ⚠ Build failed: ${msg.slice(0, 80)}`));
-              }
-            }
-          }
-        }
-        if (plan.notes) {
-          log(chalk6.gray(`  Note: ${plan.notes}`));
-        }
-        return plan.entryPoint;
-      };
-      try {
-        const entry = await detectEntryPoint(targetFs);
-        const buildInfo = await detectBuildInfo(targetFs);
-        const needsBuildStep = entry.isDeclarationOnly && buildInfo.exoticIndicators.wasm;
-        if (needsBuildStep) {
-          process.stdout.write(chalk6.cyan(`> Detected .d.ts entry with WASM indicators...
-`));
-          const llmEntry = await runLlmFallback("WASM project detected");
-          if (llmEntry) {
-            entryPath = path7.join(targetDir, llmEntry);
-            if (buildFailed) {
-              process.stdout.write(chalk6.green(`✓ Entry point: ${llmEntry} (using pre-committed declarations)
-`));
-              log(chalk6.gray("  Coverage may be limited - generated .d.ts files typically lack JSDoc"));
-            } else {
-              process.stdout.write(chalk6.green(`✓ Entry point: ${llmEntry} (from LLM fallback - WASM project)
-`));
-            }
-          } else {
-            entryPath = path7.join(targetDir, entry.path);
-            process.stdout.write(chalk6.green(`✓ Entry point: ${entry.path} (from ${entry.source})
-`));
-            log(chalk6.yellow("  ⚠ WASM project detected but no API key - analysis may be limited"));
-          }
-        } else {
-          entryPath = path7.join(targetDir, entry.path);
-          process.stdout.write(chalk6.green(`✓ Entry point: ${entry.path} (from ${entry.source})
-`));
-        }
-      } catch (entryError) {
-        const llmEntry = await runLlmFallback("Heuristics failed");
-        if (llmEntry) {
-          entryPath = path7.join(targetDir, llmEntry);
-          process.stdout.write(chalk6.green(`✓ Entry point: ${llmEntry} (from LLM fallback)
-`));
-        } else {
-          process.stdout.write(chalk6.red(`✗ Could not detect entry point (set OPENAI_API_KEY for smart fallback)
-`));
-          throw entryError;
-        }
-      }
-      process.stdout.write(chalk6.cyan(`> Analyzing documentation coverage...
-`));
-      let result;
-      try {
-        const resolveExternalTypes = !options.skipResolve;
-        const doccov = createDocCov({ resolveExternalTypes });
-        result = await doccov.analyzeFileWithDiagnostics(entryPath);
-        process.stdout.write(chalk6.green(`✓ Analysis complete
-`));
-      } catch (analysisError) {
-        process.stdout.write(chalk6.red(`✗ Analysis failed
-`));
-        throw analysisError;
-      }
-      const spec = result.spec;
-      if (options.saveSpec) {
-        const specPath = path7.resolve(process.cwd(), options.saveSpec);
-        fs6.writeFileSync(specPath, JSON.stringify(spec, null, 2));
-        log(chalk6.green(`✓ Saved spec to ${options.saveSpec}`));
-      }
-      const summary = extractSpecSummary(spec);
-      const scanResult = {
-        owner: parsed.owner,
-        repo: parsed.repo,
-        ref: parsed.ref,
-        packageName,
-        coverage: summary.coverage,
-        exportCount: summary.exportCount,
-        typeCount: summary.typeCount,
-        driftCount: summary.driftCount,
-        undocumented: summary.undocumented,
-        drift: summary.drift
-      };
-      if (options.output === "json") {
-        log(JSON.stringify(scanResult, null, 2));
-      } else {
-        printTextResult(scanResult, log);
-      }
-    } catch (commandError) {
-      error(chalk6.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
-      process.exitCode = 1;
-    } finally {
-      if (tempDir && options.cleanup !== false) {
-        fsPromises.rm(tempDir, { recursive: true, force: true }).catch(() => {});
-      } else if (tempDir) {
-        log(chalk6.gray(`Repo preserved at: ${tempDir}`));
-      }
-    }
-  });
-}
-function categorizeDriftIssues(drift) {
-  const byCategory = {
-    structural: [],
-    semantic: [],
-    example: []
-  };
-  for (const d of drift) {
-    const category = DRIFT_CATEGORIES3[d.type] ?? "semantic";
-    byCategory[category].push(d);
-  }
-  return {
-    summary: {
-      total: drift.length,
-      byCategory: {
-        structural: byCategory.structural.length,
-        semantic: byCategory.semantic.length,
-        example: byCategory.example.length
-      }
-    },
-    byCategory
-  };
-}
-function formatDriftSummary(summary) {
-  if (summary.total === 0) {
-    return "No drift detected";
-  }
-  const parts = [];
-  if (summary.byCategory.structural > 0) {
-    parts.push(`${summary.byCategory.structural} structural`);
-  }
-  if (summary.byCategory.semantic > 0) {
-    parts.push(`${summary.byCategory.semantic} semantic`);
-  }
-  if (summary.byCategory.example > 0) {
-    parts.push(`${summary.byCategory.example} example`);
-  }
-  return `${summary.total} issues (${parts.join(", ")})`;
-}
-function printTextResult(result, log) {
-  log("");
-  log(chalk6.bold("DocCov Scan Results"));
-  log("─".repeat(40));
-  const repoName = result.packageName ? `${result.owner}/${result.repo} (${result.packageName})` : `${result.owner}/${result.repo}`;
-  log(`Repository: ${chalk6.cyan(repoName)}`);
-  log(`Branch: ${chalk6.gray(result.ref)}`);
-  log("");
-  const coverageColor = result.coverage >= 80 ? chalk6.green : result.coverage >= 50 ? chalk6.yellow : chalk6.red;
-  log(chalk6.bold("Coverage"));
-  log(`  ${coverageColor(`${result.coverage}%`)}`);
-  log("");
-  log(chalk6.bold("Stats"));
-  log(`  ${result.exportCount} exports`);
-  log(`  ${result.typeCount} types`);
-  log(`  ${result.undocumented.length} undocumented`);
-  const categorized = categorizeDriftIssues(result.drift);
-  const driftColor = result.driftCount > 0 ? chalk6.yellow : chalk6.green;
-  log(`  ${driftColor(formatDriftSummary(categorized.summary))}`);
-  if (result.undocumented.length > 0) {
-    log("");
-    log(chalk6.bold("Undocumented Exports"));
-    for (const name of result.undocumented.slice(0, 10)) {
-      log(chalk6.yellow(`  ! ${name}`));
-    }
-    if (result.undocumented.length > 10) {
-      log(chalk6.gray(`  ... and ${result.undocumented.length - 10} more`));
-    }
-  }
-  if (result.drift.length > 0) {
-    log("");
-    log(chalk6.bold("Drift Issues"));
-    const categories = ["structural", "semantic", "example"];
-    for (const category of categories) {
-      const issues = categorized.byCategory[category];
-      if (issues.length === 0)
-        continue;
-      const label = DRIFT_CATEGORY_LABELS2[category];
-      log("");
-      log(chalk6.dim(`  ${label} (${issues.length})`));
-      for (const d of issues.slice(0, 3)) {
-        log(chalk6.red(`    • ${d.export}: ${d.issue}`));
-      }
-      if (issues.length > 3) {
-        log(chalk6.gray(`    ... and ${issues.length - 3} more`));
-      }
-    }
-  }
-  log("");
-}
+import * as path7 from "node:path";
+import { DocCov as DocCov3, NodeFileSystem as NodeFileSystem3, resolveTarget as resolveTarget3 } from "@doccov/sdk";
+import { normalize, validateSpec } from "@openpkg-ts/spec";
+// package.json
+var version = "0.13.0";
 
 // src/commands/spec.ts
-import * as fs7 from "node:fs";
-import * as path8 from "node:path";
-import { DocCov as DocCov4, NodeFileSystem as NodeFileSystem4, resolveTarget as resolveTarget3 } from "@doccov/sdk";
-import { normalize, validateSpec } from "@openpkg-ts/spec";
-import chalk8 from "chalk";
+import chalk7 from "chalk";
 
 // src/utils/filter-options.ts
 import { mergeFilters, parseListFlag } from "@doccov/sdk";
-import chalk7 from "chalk";
-var formatList = (label, values) => `${label}: ${values.map((value) => chalk7.cyan(value)).join(", ")}`;
+import chalk6 from "chalk";
+var formatList = (label, values) => `${label}: ${values.map((value) => chalk6.cyan(value)).join(", ")}`;
 var mergeFilterOptions = (config, cliOptions) => {
   const messages = [];
   if (config?.include) {
@@ -2289,9 +1800,9 @@ var mergeFilterOptions = (config, cliOptions) => {
 };
 
 // src/commands/spec.ts
-var defaultDependencies5 = {
-  createDocCov: (options) => new DocCov4(options),
-  writeFileSync: fs7.writeFileSync,
+var defaultDependencies4 = {
+  createDocCov: (options) => new DocCov3(options),
+  writeFileSync: fs5.writeFileSync,
   log: console.log,
   error: console.error
 };
@@ -2300,19 +1811,19 @@ function getArrayLength(value) {
 }
 function formatDiagnosticOutput(prefix, diagnostic, baseDir) {
   const location = diagnostic.location;
-  const relativePath = location?.file ? path8.relative(baseDir, location.file) || location.file : undefined;
-  const locationText = location && relativePath ? chalk8.gray(`${relativePath}:${location.line ?? 1}:${location.column ?? 1}`) : null;
+  const relativePath = location?.file ? path7.relative(baseDir, location.file) || location.file : undefined;
+  const locationText = location && relativePath ? chalk7.gray(`${relativePath}:${location.line ?? 1}:${location.column ?? 1}`) : null;
   const locationPrefix = locationText ? `${locationText} ` : "";
   return `${prefix} ${locationPrefix}${diagnostic.message}`;
 }
 function registerSpecCommand(program, dependencies = {}) {
-  const { createDocCov, writeFileSync: writeFileSync5, log, error } = {
-    ...defaultDependencies5,
+  const { createDocCov, writeFileSync: writeFileSync4, log, error } = {
+    ...defaultDependencies4,
     ...dependencies
   };
-  program.command("spec [entry]").description("Generate OpenPkg specification (JSON)").option("--cwd <dir>", "Working directory", process.cwd()).option("-p, --package <name>", "Target package name (for monorepos)").option("-o, --output <file>", "Output file path", "openpkg.json").option("--include <patterns>", "Include exports matching pattern (comma-separated)").option("--exclude <patterns>", "Exclude exports matching pattern (comma-separated)").option("--skip-resolve", "Skip external type resolution from node_modules").option("--max-type-depth <n>", "Maximum depth for type conversion", "20").option("--no-cache", "Bypass spec cache and force regeneration").option("--show-diagnostics", "Show TypeScript compiler diagnostics").action(async (entry, options) => {
+  program.command("spec [entry]").description("Generate OpenPkg specification (JSON)").option("--cwd <dir>", "Working directory", process.cwd()).option("-p, --package <name>", "Target package name (for monorepos)").option("-o, --output <file>", "Output file path", "openpkg.json").option("--include <patterns>", "Include exports matching pattern (comma-separated)").option("--exclude <patterns>", "Exclude exports matching pattern (comma-separated)").option("--skip-resolve", "Skip external type resolution from node_modules").option("--max-type-depth <n>", "Maximum depth for type conversion", "20").option("--no-cache", "Bypass spec cache and force regeneration").option("--show-diagnostics", "Show TypeScript compiler diagnostics").option("--verbose", "Show detailed generation metadata").action(async (entry, options) => {
     try {
-      const fileSystem = new NodeFileSystem4(options.cwd);
+      const fileSystem = new NodeFileSystem3(options.cwd);
       const resolved = await resolveTarget3(fileSystem, {
         cwd: options.cwd,
         package: options.package,
@@ -2320,19 +1831,19 @@ function registerSpecCommand(program, dependencies = {}) {
       });
       const { targetDir, entryFile, packageInfo, entryPointInfo } = resolved;
       if (packageInfo) {
-        log(chalk8.gray(`Found package at ${packageInfo.path}`));
+        log(chalk7.gray(`Found package at ${packageInfo.path}`));
       }
       if (!entry) {
-        log(chalk8.gray(`Auto-detected entry point: ${entryPointInfo.path} (from ${entryPointInfo.source})`));
+        log(chalk7.gray(`Auto-detected entry point: ${entryPointInfo.path} (from ${entryPointInfo.source})`));
       }
       let config = null;
       try {
         config = await loadDocCovConfig(targetDir);
         if (config?.filePath) {
-          log(chalk8.gray(`Loaded configuration from ${path8.relative(targetDir, config.filePath)}`));
+          log(chalk7.gray(`Loaded configuration from ${path7.relative(targetDir, config.filePath)}`));
         }
       } catch (configError) {
-        error(chalk8.red("Failed to load DocCov config:"), configError instanceof Error ? configError.message : configError);
+        error(chalk7.red("Failed to load DocCov config:"), configError instanceof Error ? configError.message : configError);
         process.exit(1);
       }
       const cliFilters = {
@@ -2341,10 +1852,10 @@ function registerSpecCommand(program, dependencies = {}) {
       };
       const resolvedFilters = mergeFilterOptions(config, cliFilters);
       for (const message of resolvedFilters.messages) {
-        log(chalk8.gray(`${message}`));
+        log(chalk7.gray(`${message}`));
       }
       const resolveExternalTypes = !options.skipResolve;
-      process.stdout.write(chalk8.cyan(`> Generating OpenPkg spec...
+      process.stdout.write(chalk7.cyan(`> Generating OpenPkg spec...
 `));
       let result;
       try {
@@ -2354,22 +1865,33 @@ function registerSpecCommand(program, dependencies = {}) {
           useCache: options.cache !== false,
           cwd: options.cwd
         });
+        const generationInput = {
+          entryPoint: path7.relative(targetDir, entryFile),
+          entryPointSource: entryPointInfo.source,
+          isDeclarationOnly: entryPointInfo.isDeclarationOnly ?? false,
+          generatorName: "@doccov/cli",
+          generatorVersion: version,
+          packageManager: packageInfo?.packageManager,
+          isMonorepo: resolved.isMonorepo,
+          targetPackage: packageInfo?.name
+        };
         const analyzeOptions = resolvedFilters.include || resolvedFilters.exclude ? {
           filters: {
             include: resolvedFilters.include,
             exclude: resolvedFilters.exclude
-          }
-        } : {};
+          },
+          generationInput
+        } : { generationInput };
         result = await doccov.analyzeFileWithDiagnostics(entryFile, analyzeOptions);
         if (result.fromCache) {
-          process.stdout.write(chalk8.gray(`> Using cached spec
+          process.stdout.write(chalk7.gray(`> Using cached spec
 `));
         } else {
-          process.stdout.write(chalk8.green(`> Generated OpenPkg spec
+          process.stdout.write(chalk7.green(`> Generated OpenPkg spec
 `));
         }
       } catch (generationError) {
-        process.stdout.write(chalk8.red(`> Failed to generate spec
+        process.stdout.write(chalk7.red(`> Failed to generate spec
 `));
         throw generationError;
       }
@@ -2379,27 +1901,64 @@ function registerSpecCommand(program, dependencies = {}) {
       const normalized = normalize(result.spec);
       const validation = validateSpec(normalized);
       if (!validation.ok) {
-        error(chalk8.red("Spec failed schema validation"));
+        error(chalk7.red("Spec failed schema validation"));
         for (const err of validation.errors) {
-          error(chalk8.red(`schema: ${err.instancePath || "/"} ${err.message}`));
+          error(chalk7.red(`schema: ${err.instancePath || "/"} ${err.message}`));
         }
         process.exit(1);
       }
-      const outputPath = path8.resolve(process.cwd(), options.output);
-      writeFileSync5(outputPath, JSON.stringify(normalized, null, 2));
-      log(chalk8.green(`> Wrote ${options.output}`));
-      log(chalk8.gray(`  ${getArrayLength(normalized.exports)} exports`));
-      log(chalk8.gray(`  ${getArrayLength(normalized.types)} types`));
+      const outputPath = path7.resolve(process.cwd(), options.output);
+      writeFileSync4(outputPath, JSON.stringify(normalized, null, 2));
+      log(chalk7.green(`> Wrote ${options.output}`));
+      log(chalk7.gray(`  ${getArrayLength(normalized.exports)} exports`));
+      log(chalk7.gray(`  ${getArrayLength(normalized.types)} types`));
+      if (options.verbose && normalized.generation) {
+        const gen = normalized.generation;
+        log("");
+        log(chalk7.bold("Generation Info"));
+        log(chalk7.gray(`  Timestamp:        ${gen.timestamp}`));
+        log(chalk7.gray(`  Generator:        ${gen.generator.name}@${gen.generator.version}`));
+        log(chalk7.gray(`  Entry point:      ${gen.analysis.entryPoint}`));
+        log(chalk7.gray(`  Detected via:     ${gen.analysis.entryPointSource}`));
+        log(chalk7.gray(`  Declaration only: ${gen.analysis.isDeclarationOnly ? "yes" : "no"}`));
+        log(chalk7.gray(`  External types:   ${gen.analysis.resolvedExternalTypes ? "resolved" : "skipped"}`));
+        if (gen.analysis.maxTypeDepth) {
+          log(chalk7.gray(`  Max type depth:   ${gen.analysis.maxTypeDepth}`));
+        }
+        log("");
+        log(chalk7.bold("Environment"));
+        log(chalk7.gray(`  node_modules:     ${gen.environment.hasNodeModules ? "found" : "not found"}`));
+        if (gen.environment.packageManager) {
+          log(chalk7.gray(`  Package manager:  ${gen.environment.packageManager}`));
+        }
+        if (gen.environment.isMonorepo) {
+          log(chalk7.gray(`  Monorepo:         yes`));
+        }
+        if (gen.environment.targetPackage) {
+          log(chalk7.gray(`  Target package:   ${gen.environment.targetPackage}`));
+        }
+        if (gen.issues.length > 0) {
+          log("");
+          log(chalk7.bold("Issues"));
+          for (const issue of gen.issues) {
+            const prefix = issue.severity === "error" ? chalk7.red(">") : issue.severity === "warning" ? chalk7.yellow(">") : chalk7.cyan(">");
+            log(`${prefix} [${issue.code}] ${issue.message}`);
+            if (issue.suggestion) {
+              log(chalk7.gray(`    ${issue.suggestion}`));
+            }
+          }
+        }
+      }
       if (options.showDiagnostics && result.diagnostics.length > 0) {
         log("");
-        log(chalk8.bold("Diagnostics"));
+        log(chalk7.bold("Diagnostics"));
         for (const diagnostic of result.diagnostics) {
-          const prefix = diagnostic.severity === "error" ? chalk8.red(">") : diagnostic.severity === "warning" ? chalk8.yellow(">") : chalk8.cyan(">");
+          const prefix = diagnostic.severity === "error" ? chalk7.red(">") : diagnostic.severity === "warning" ? chalk7.yellow(">") : chalk7.cyan(">");
           log(formatDiagnosticOutput(prefix, diagnostic, targetDir));
         }
       }
     } catch (commandError) {
-      error(chalk8.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      error(chalk7.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
       process.exit(1);
     }
   });
@@ -2407,8 +1966,8 @@ function registerSpecCommand(program, dependencies = {}) {
 
 // src/cli.ts
 var __filename2 = fileURLToPath(import.meta.url);
-var __dirname2 = path9.dirname(__filename2);
-var packageJson = JSON.parse(readFileSync4(path9.join(__dirname2, "../package.json"), "utf-8"));
+var __dirname2 = path8.dirname(__filename2);
+var packageJson = JSON.parse(readFileSync3(path8.join(__dirname2, "../package.json"), "utf-8"));
 var program = new Command;
 program.name("doccov").description("DocCov - Documentation coverage and drift detection for TypeScript").version(packageJson.version);
 registerCheckCommand(program);
@@ -2416,7 +1975,6 @@ registerInfoCommand(program);
 registerSpecCommand(program);
 registerDiffCommand(program);
 registerInitCommand(program);
-registerScanCommand(program);
 program.command("*", { hidden: true }).action(() => {
   program.outputHelp();
 });