@doccov/cli 0.22.0 → 0.24.0

package/dist/cli.js

@@ -147,36 +147,360 @@ ${formatIssues(issues)}`);
 var defineConfig = (config) => config;
 // src/cli.ts
 import { readFileSync as readFileSync5 } from "node:fs";
-import * as path9 from "node:path";
+import * as path10 from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 
-// src/commands/check.ts
+// src/commands/check/index.ts
+import {
+  DocCov,
+  enrichSpec,
+  NodeFileSystem,
+  parseExamplesFlag,
+  resolveTarget
+} from "@doccov/sdk";
+import chalk6 from "chalk";
+
+// src/utils/filter-options.ts
+import { mergeFilters, parseListFlag } from "@doccov/sdk";
+import chalk from "chalk";
+var parseVisibilityFlag = (value) => {
+  if (!value)
+    return;
+  const validTags = ["public", "beta", "alpha", "internal"];
+  const parsed = parseListFlag(value);
+  if (!parsed)
+    return;
+  const result = [];
+  for (const tag of parsed) {
+    const lower = tag.toLowerCase();
+    if (validTags.includes(lower)) {
+      result.push(lower);
+    }
+  }
+  return result.length > 0 ? result : undefined;
+};
+var formatList = (label, values) => `${label}: ${values.map((value) => chalk.cyan(value)).join(", ")}`;
+var mergeFilterOptions = (config, cliOptions) => {
+  const messages = [];
+  if (config?.include) {
+    messages.push(formatList("include filters from config", config.include));
+  }
+  if (config?.exclude) {
+    messages.push(formatList("exclude filters from config", config.exclude));
+  }
+  if (cliOptions.include) {
+    messages.push(formatList("apply include filters from CLI", cliOptions.include));
+  }
+  if (cliOptions.exclude) {
+    messages.push(formatList("apply exclude filters from CLI", cliOptions.exclude));
+  }
+  if (cliOptions.visibility) {
+    messages.push(formatList("apply visibility filter from CLI", cliOptions.visibility));
+  }
+  const resolved = mergeFilters(config, cliOptions);
+  if (!resolved.include && !resolved.exclude && !cliOptions.visibility) {
+    return { messages };
+  }
+  const source = resolved.source === "override" ? "cli" : resolved.source;
+  return {
+    include: resolved.include,
+    exclude: resolved.exclude,
+    visibility: cliOptions.visibility,
+    source,
+    messages
+  };
+};
+
+// src/utils/progress.ts
+import chalk2 from "chalk";
+class StepProgress {
+  steps;
+  currentStep = 0;
+  startTime;
+  stepStartTime;
+  constructor(steps) {
+    this.steps = steps;
+    this.startTime = Date.now();
+    this.stepStartTime = Date.now();
+  }
+  start(stepIndex) {
+    this.currentStep = stepIndex ?? 0;
+    this.stepStartTime = Date.now();
+    this.render();
+  }
+  next() {
+    this.completeCurrentStep();
+    this.currentStep++;
+    if (this.currentStep < this.steps.length) {
+      this.stepStartTime = Date.now();
+      this.render();
+    }
+  }
+  complete(message) {
+    this.completeCurrentStep();
+    if (message) {
+      const elapsed = ((Date.now() - this.startTime) / 1000).toFixed(1);
+      console.log(`${chalk2.green("✓")} ${message} ${chalk2.dim(`(${elapsed}s)`)}`);
+    }
+  }
+  render() {
+    const step = this.steps[this.currentStep];
+    if (!step)
+      return;
+    const label = step.activeLabel ?? step.label;
+    const prefix = chalk2.dim(`[${this.currentStep + 1}/${this.steps.length}]`);
+    process.stdout.write(`\r${prefix} ${chalk2.cyan(label)}...`);
+  }
+  completeCurrentStep() {
+    const step = this.steps[this.currentStep];
+    if (!step)
+      return;
+    const elapsed = ((Date.now() - this.stepStartTime) / 1000).toFixed(1);
+    const prefix = chalk2.dim(`[${this.currentStep + 1}/${this.steps.length}]`);
+    process.stdout.write(`\r${" ".repeat(80)}\r`);
+    console.log(`${prefix} ${step.label} ${chalk2.green("✓")} ${chalk2.dim(`(${elapsed}s)`)}`);
+  }
+}
+
+// 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/fix-handler.ts
 import * as fs2 from "node:fs";
-import * as path4 from "node:path";
+import * as path3 from "node:path";
 import {
   applyEdits,
   categorizeDrifts,
   createSourceFile,
-  DocCov,
-  enrichSpec,
   findJSDocLocation,
   generateFixesForExport,
-  generateReport,
   mergeFixes,
-  NodeFileSystem,
-  parseExamplesFlag,
   parseJSDocToPatch,
-  parseMarkdownFiles,
-  resolveTarget,
-  serializeJSDoc,
-  validateExamples
+  serializeJSDoc
 } from "@doccov/sdk";
+import chalk3 from "chalk";
+
+// src/commands/check/utils.ts
+import * as fs from "node:fs";
+import * as path2 from "node:path";
 import {
-  DRIFT_CATEGORIES as DRIFT_CATEGORIES2
-} from "@openpkg-ts/spec";
-import chalk4 from "chalk";
+  DRIFT_CATEGORIES,
+  parseMarkdownFiles
+} from "@doccov/sdk";
 import { glob } from "glob";
+function collectDriftsFromExports(exports) {
+  const results = [];
+  for (const exp of exports) {
+    for (const drift of exp.docs?.drift ?? []) {
+      results.push({ export: exp, drift });
+    }
+  }
+  return results;
+}
+function groupByExport(drifts) {
+  const map = new Map;
+  for (const { export: exp, drift } of drifts) {
+    const existing = map.get(exp) ?? [];
+    existing.push(drift);
+    map.set(exp, existing);
+  }
+  return map;
+}
+function collectDrift(exportsList) {
+  const drifts = [];
+  for (const entry of exportsList) {
+    const drift = entry.docs?.drift;
+    if (!drift || drift.length === 0) {
+      continue;
+    }
+    for (const d of drift) {
+      drifts.push({
+        name: entry.name,
+        type: d.type,
+        issue: d.issue ?? "Documentation drift detected.",
+        suggestion: d.suggestion,
+        category: DRIFT_CATEGORIES[d.type]
+      });
+    }
+  }
+  return drifts;
+}
+function collect(value, previous) {
+  return previous.concat([value]);
+}
+async function loadMarkdownFiles(patterns, cwd) {
+  const files = [];
+  for (const pattern of patterns) {
+    const matches = await glob(pattern, { nodir: true, cwd });
+    for (const filePath of matches) {
+      try {
+        const fullPath = path2.resolve(cwd, filePath);
+        const content = fs.readFileSync(fullPath, "utf-8");
+        files.push({ path: filePath, content });
+      } catch {}
+    }
+  }
+  return parseMarkdownFiles(files);
+}
+
+// src/commands/check/fix-handler.ts
+async function handleFixes(spec, options, deps) {
+  const { isPreview, targetDir } = options;
+  const { log, error } = deps;
+  const fixedDriftKeys = new Set;
+  const allDrifts = collectDriftsFromExports(spec.exports ?? []);
+  if (allDrifts.length === 0) {
+    return { fixedDriftKeys, editsApplied: 0, filesModified: 0 };
+  }
+  const { fixable, nonFixable } = categorizeDrifts(allDrifts.map((d) => d.drift));
+  if (fixable.length === 0) {
+    log(chalk3.yellow(`Found ${nonFixable.length} drift issue(s), but none are auto-fixable.`));
+    return { fixedDriftKeys, editsApplied: 0, filesModified: 0 };
+  }
+  log("");
+  log(chalk3.bold(`Found ${fixable.length} fixable issue(s)`));
+  if (nonFixable.length > 0) {
+    log(chalk3.gray(`(${nonFixable.length} non-fixable issue(s) skipped)`));
+  }
+  log("");
+  const groupedDrifts = groupByExport(allDrifts.filter((d) => fixable.includes(d.drift)));
+  const edits = [];
+  const editsByFile = new Map;
+  for (const [exp, drifts] of groupedDrifts) {
+    const edit = generateEditForExport(exp, drifts, targetDir, log);
+    if (!edit)
+      continue;
+    for (const drift of drifts) {
+      fixedDriftKeys.add(`${exp.name}:${drift.issue}`);
+    }
+    edits.push(edit.edit);
+    const fileEdits = editsByFile.get(edit.filePath) ?? [];
+    fileEdits.push({
+      export: exp,
+      edit: edit.edit,
+      fixes: edit.fixes,
+      existingPatch: edit.existingPatch
+    });
+    editsByFile.set(edit.filePath, fileEdits);
+  }
+  if (edits.length === 0) {
+    return { fixedDriftKeys, editsApplied: 0, filesModified: 0 };
+  }
+  if (isPreview) {
+    displayPreview(editsByFile, targetDir, log);
+    return { fixedDriftKeys, editsApplied: 0, filesModified: 0 };
+  }
+  const applyResult = await applyEdits(edits);
+  if (applyResult.errors.length > 0) {
+    for (const err of applyResult.errors) {
+      error(chalk3.red(`  ${err.file}: ${err.error}`));
+    }
+  }
+  const totalFixes = Array.from(editsByFile.values()).reduce((sum, fileEdits) => sum + fileEdits.reduce((s, e) => s + e.fixes.length, 0), 0);
+  log("");
+  log(chalk3.green(`✓ Applied ${totalFixes} fix(es) to ${applyResult.filesModified} file(s)`));
+  for (const [filePath, fileEdits] of editsByFile) {
+    const relativePath = path3.relative(targetDir, filePath);
+    const fixCount = fileEdits.reduce((s, e) => s + e.fixes.length, 0);
+    log(chalk3.dim(`  ${relativePath} (${fixCount} fixes)`));
+  }
+  return {
+    fixedDriftKeys,
+    editsApplied: totalFixes,
+    filesModified: applyResult.filesModified
+  };
+}
+function generateEditForExport(exp, drifts, targetDir, log) {
+  if (!exp.source?.file) {
+    log(chalk3.gray(`  Skipping ${exp.name}: no source location`));
+    return null;
+  }
+  if (exp.source.file.endsWith(".d.ts")) {
+    log(chalk3.gray(`  Skipping ${exp.name}: declaration file`));
+    return null;
+  }
+  const filePath = path3.resolve(targetDir, exp.source.file);
+  if (!fs2.existsSync(filePath)) {
+    log(chalk3.gray(`  Skipping ${exp.name}: file not found`));
+    return null;
+  }
+  const sourceFile = createSourceFile(filePath);
+  const location = findJSDocLocation(sourceFile, exp.name, exp.source.line);
+  if (!location) {
+    log(chalk3.gray(`  Skipping ${exp.name}: could not find declaration`));
+    return null;
+  }
+  let existingPatch = {};
+  if (location.hasExisting && location.existingJSDoc) {
+    existingPatch = parseJSDocToPatch(location.existingJSDoc);
+  }
+  const expWithDrift = { ...exp, docs: { ...exp.docs, drift: drifts } };
+  const fixes = generateFixesForExport(expWithDrift, existingPatch);
+  if (fixes.length === 0)
+    return null;
+  const mergedPatch = mergeFixes(fixes, existingPatch);
+  const newJSDoc = serializeJSDoc(mergedPatch, location.indent);
+  const edit = {
+    filePath,
+    symbolName: exp.name,
+    startLine: location.startLine,
+    endLine: location.endLine,
+    hasExisting: location.hasExisting,
+    existingJSDoc: location.existingJSDoc,
+    newJSDoc,
+    indent: location.indent
+  };
+  return { filePath, edit, fixes, existingPatch };
+}
+function displayPreview(editsByFile, targetDir, log) {
+  log(chalk3.bold("Preview - changes that would be made:"));
+  log("");
+  for (const [filePath, fileEdits] of editsByFile) {
+    const relativePath = path3.relative(targetDir, filePath);
+    for (const { export: exp, edit, fixes } of fileEdits) {
+      log(chalk3.cyan(`${relativePath}:${edit.startLine + 1}`));
+      log(chalk3.bold(`  ${exp.name}`));
+      log("");
+      if (edit.hasExisting && edit.existingJSDoc) {
+        const oldLines = edit.existingJSDoc.split(`
+`);
+        const newLines = edit.newJSDoc.split(`
+`);
+        for (const line of oldLines) {
+          log(chalk3.red(`  - ${line}`));
+        }
+        for (const line of newLines) {
+          log(chalk3.green(`  + ${line}`));
+        }
+      } else {
+        const newLines = edit.newJSDoc.split(`
+`);
+        for (const line of newLines) {
+          log(chalk3.green(`  + ${line}`));
+        }
+      }
+      log("");
+      log(chalk3.dim(`  Fixes: ${fixes.map((f) => f.description).join(", ")}`));
+      log("");
+    }
+  }
+  const totalFixes = Array.from(editsByFile.values()).reduce((sum, fileEdits) => sum + fileEdits.reduce((s, e) => s + e.fixes.length, 0), 0);
+  log(chalk3.yellow(`${totalFixes} fix(es) across ${editsByFile.size} file(s) would be applied.`));
+  log(chalk3.gray("Run with --fix to apply these changes."));
+}
+
+// src/commands/check/output.ts
+import { generateReport } from "@doccov/sdk";
+import chalk5 from "chalk";
 
 // src/reports/changelog-renderer.ts
 function renderChangelog(data, options = {}) {
@@ -246,7 +570,7 @@ function renderChangelog(data, options = {}) {
 `);
 }
 // src/reports/diff-markdown.ts
-import * as path2 from "node:path";
+import * as path4 from "node:path";
 function bar(pct, width = 10) {
   const filled = Math.round(pct / 100 * width);
   return "█".repeat(filled) + "░".repeat(width - filled);
@@ -397,7 +721,7 @@ function renderDocsImpactSection(lines, docsImpact, limit) {
     lines.push("| File | Issues | Details |");
     lines.push("|------|--------|---------|");
     for (const file of impactedFiles.slice(0, limit)) {
-      const filename = path2.basename(file.file);
+      const filename = path4.basename(file.file);
       const issueCount = file.references.length;
       const firstRef = file.references[0];
       const detail = firstRef ? `L${firstRef.line}: ${firstRef.memberName ?? firstRef.exportName}` : "-";
@@ -488,7 +812,7 @@ ${status} Coverage ${coverageScore >= 80 ? "passing" : coverageScore >= 50 ? "ne
   return output;
 }
 // src/reports/markdown.ts
-import { DRIFT_CATEGORY_LABELS } from "@openpkg-ts/spec";
+import { DRIFT_CATEGORY_LABELS } from "@doccov/sdk";
 function bar2(pct, width = 10) {
   const filled = Math.round(pct / 100 * width);
   return "█".repeat(filled) + "░".repeat(width - filled);
@@ -784,8 +1108,20 @@ function buildFileLink(file, opts) {
   }
   return `\`${file}\``;
 }
+function getExportKeyword(kind) {
+  switch (kind) {
+    case "type":
+      return "type";
+    case "interface":
+      return "interface";
+    case "class":
+      return "class";
+    default:
+      return "function";
+  }
+}
 function formatExportSignature(exp) {
-  const prefix = `export ${exp.kind === "type" ? "type" : exp.kind === "interface" ? "interface" : exp.kind === "class" ? "class" : "function"}`;
+  const prefix = `export ${getExportKeyword(exp.kind)}`;
   if (exp.kind === "function" && exp.signatures?.[0]) {
     const sig = exp.signatures[0];
     const params = sig.parameters?.map((p) => `${p.name}${p.required === false ? "?" : ""}`).join(", ") ?? "";
@@ -853,7 +1189,7 @@ function renderFixGuidance(diff, opts) {
 
 **Quick fix:** Run \`npx doccov check --fix\` to auto-fix ${opts.fixableDriftCount} issue(s).` : "";
     sections.push(`**For doc drift:**
-` + "Update JSDoc to match current code signatures." + fixableNote);
+Update JSDoc to match current code signatures.${fixableNote}`);
   }
   if (opts.staleDocsRefs && opts.staleDocsRefs.length > 0) {
     sections.push(`**For stale docs:**
@@ -886,10 +1222,10 @@ function renderDetailsTable(lines, diff) {
   }
 }
 // src/reports/stats.ts
-import { isFixableDrift } from "@doccov/sdk";
 import {
-  DRIFT_CATEGORIES
-} from "@openpkg-ts/spec";
+  DRIFT_CATEGORIES as DRIFT_CATEGORIES2,
+  isFixableDrift
+} from "@doccov/sdk";
 function computeStats(spec) {
   const exports = spec.exports ?? [];
   const signals = {
@@ -934,7 +1270,7 @@ function computeStats(spec) {
         suggestion: d.suggestion
       };
       driftIssues.push(item);
-      const category = DRIFT_CATEGORIES[d.type] ?? "semantic";
+      const category = DRIFT_CATEGORIES2[d.type] ?? "semantic";
       driftByCategory[category].push(item);
     }
   }
@@ -983,21 +1319,21 @@ function computeStats(spec) {
   };
 }
 // src/reports/writer.ts
-import * as fs from "node:fs";
-import * as path3 from "node:path";
+import * as fs3 from "node:fs";
+import * as path5 from "node:path";
 import { DEFAULT_REPORT_DIR, getReportPath } from "@doccov/sdk";
-import chalk from "chalk";
+import chalk4 from "chalk";
 function writeReport(options) {
   const { format, content, outputPath, cwd = process.cwd(), silent = false } = options;
-  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 });
+  const reportPath = outputPath ? path5.resolve(cwd, outputPath) : path5.resolve(cwd, getReportPath(format));
+  const dir = path5.dirname(reportPath);
+  if (!fs3.existsSync(dir)) {
+    fs3.mkdirSync(dir, { recursive: true });
   }
-  fs.writeFileSync(reportPath, content);
-  const relativePath = path3.relative(cwd, reportPath);
+  fs3.writeFileSync(reportPath, content);
+  const relativePath = path5.relative(cwd, reportPath);
   if (!silent) {
-    console.log(chalk.green(`✓ Wrote ${format} report to ${relativePath}`));
+    console.log(chalk4.green(`✓ Wrote ${format} report to ${relativePath}`));
   }
   return { path: reportPath, format, relativePath };
 }
@@ -1020,149 +1356,257 @@ function writeReports(options) {
   }));
   return results;
 }
-// src/utils/filter-options.ts
-import { mergeFilters, parseListFlag } from "@doccov/sdk";
-import chalk2 from "chalk";
-var parseVisibilityFlag = (value) => {
-  if (!value)
-    return;
-  const validTags = ["public", "beta", "alpha", "internal"];
-  const parsed = parseListFlag(value);
-  if (!parsed)
-    return;
-  const result = [];
-  for (const tag of parsed) {
-    const lower = tag.toLowerCase();
-    if (validTags.includes(lower)) {
-      result.push(lower);
+// src/commands/check/output.ts
+function displayTextOutput(options, deps) {
+  const {
+    spec,
+    coverageScore,
+    minCoverage,
+    maxDrift,
+    driftExports,
+    typecheckErrors,
+    staleRefs,
+    exampleResult,
+    specWarnings,
+    specInfos
+  } = options;
+  const { log } = deps;
+  const totalExportsForDrift = spec.exports?.length ?? 0;
+  const exportsWithDrift = new Set(driftExports.map((d) => d.name)).size;
+  const driftScore = totalExportsForDrift === 0 ? 0 : Math.round(exportsWithDrift / totalExportsForDrift * 100);
+  const coverageFailed = coverageScore < minCoverage;
+  const driftFailed = maxDrift !== undefined && driftScore > maxDrift;
+  const hasTypecheckErrors = typecheckErrors.length > 0;
+  if (specWarnings.length > 0 || specInfos.length > 0) {
+    log("");
+    for (const diag of specWarnings) {
+      log(chalk5.yellow(`⚠ ${diag.message}`));
+      if (diag.suggestion) {
+        log(chalk5.gray(`  ${diag.suggestion}`));
+      }
+    }
+    for (const diag of specInfos) {
+      log(chalk5.cyan(`ℹ ${diag.message}`));
+      if (diag.suggestion) {
+        log(chalk5.gray(`  ${diag.suggestion}`));
+      }
     }
   }
-  return result.length > 0 ? result : undefined;
-};
-var formatList = (label, values) => `${label}: ${values.map((value) => chalk2.cyan(value)).join(", ")}`;
-var mergeFilterOptions = (config, cliOptions) => {
-  const messages = [];
-  if (config?.include) {
-    messages.push(formatList("include filters from config", config.include));
+  const pkgName = spec.meta?.name ?? "unknown";
+  const pkgVersion = spec.meta?.version ?? "";
+  const totalExports = spec.exports?.length ?? 0;
+  log("");
+  log(chalk5.bold(`${pkgName}${pkgVersion ? `@${pkgVersion}` : ""}`));
+  log("");
+  log(`  Exports:    ${totalExports}`);
+  if (coverageFailed) {
+    log(chalk5.red(`  Coverage:   ✗ ${coverageScore}%`) + chalk5.dim(` (min ${minCoverage}%)`));
+  } else {
+    log(chalk5.green(`  Coverage:   ✓ ${coverageScore}%`) + chalk5.dim(` (min ${minCoverage}%)`));
   }
-  if (config?.exclude) {
-    messages.push(formatList("exclude filters from config", config.exclude));
+  if (maxDrift !== undefined) {
+    if (driftFailed) {
+      log(chalk5.red(`  Drift:      ✗ ${driftScore}%`) + chalk5.dim(` (max ${maxDrift}%)`));
+    } else {
+      log(chalk5.green(`  Drift:      ✓ ${driftScore}%`) + chalk5.dim(` (max ${maxDrift}%)`));
+    }
+  } else {
+    log(`  Drift:      ${driftScore}%`);
+  }
+  if (exampleResult) {
+    const typecheckCount = exampleResult.typecheck?.errors.length ?? 0;
+    if (typecheckCount > 0) {
+      log(chalk5.yellow(`  Examples:   ${typecheckCount} type error(s)`));
+      for (const err of typecheckErrors.slice(0, 5)) {
+        const loc = `example[${err.error.exampleIndex}]:${err.error.line}:${err.error.column}`;
+        log(chalk5.dim(`              ${err.exportName} ${loc}`));
+        log(chalk5.red(`                ${err.error.message}`));
+      }
+      if (typecheckErrors.length > 5) {
+        log(chalk5.dim(`              ... and ${typecheckErrors.length - 5} more`));
+      }
+    } else {
+      log(chalk5.green(`  Examples:   ✓ validated`));
+    }
   }
-  if (cliOptions.include) {
-    messages.push(formatList("apply include filters from CLI", cliOptions.include));
+  const hasStaleRefs = staleRefs.length > 0;
+  if (hasStaleRefs) {
+    log(chalk5.yellow(`  Docs:       ${staleRefs.length} stale ref(s)`));
+    for (const ref of staleRefs.slice(0, 5)) {
+      log(chalk5.dim(`              ${ref.file}:${ref.line} - "${ref.exportName}"`));
+    }
+    if (staleRefs.length > 5) {
+      log(chalk5.dim(`              ... and ${staleRefs.length - 5} more`));
+    }
   }
-  if (cliOptions.exclude) {
-    messages.push(formatList("apply exclude filters from CLI", cliOptions.exclude));
+  log("");
+  const failed = coverageFailed || driftFailed || hasTypecheckErrors || hasStaleRefs;
+  if (!failed) {
+    const thresholdParts = [];
+    thresholdParts.push(`coverage ${coverageScore}% ≥ ${minCoverage}%`);
+    if (maxDrift !== undefined) {
+      thresholdParts.push(`drift ${driftScore}% ≤ ${maxDrift}%`);
+    }
+    log(chalk5.green(`✓ Check passed (${thresholdParts.join(", ")})`));
+    return true;
   }
-  if (cliOptions.visibility) {
-    messages.push(formatList("apply visibility filter from CLI", cliOptions.visibility));
+  if (hasTypecheckErrors) {
+    log(chalk5.red(`✗ ${typecheckErrors.length} example type errors`));
   }
-  const resolved = mergeFilters(config, cliOptions);
-  if (!resolved.include && !resolved.exclude && !cliOptions.visibility) {
-    return { messages };
+  if (hasStaleRefs) {
+    log(chalk5.red(`✗ ${staleRefs.length} stale references in docs`));
   }
-  const source = resolved.source === "override" ? "cli" : resolved.source;
-  return {
-    include: resolved.include,
-    exclude: resolved.exclude,
-    visibility: cliOptions.visibility,
-    source,
-    messages
-  };
-};
-
-// src/utils/progress.ts
-import chalk3 from "chalk";
-class StepProgress {
-  steps;
-  currentStep = 0;
-  startTime;
-  stepStartTime;
-  constructor(steps) {
-    this.steps = steps;
-    this.startTime = Date.now();
-    this.stepStartTime = Date.now();
+  log("");
+  log(chalk5.dim("Use --format json or --format markdown for detailed reports"));
+  return false;
+}
+function handleNonTextOutput(options, deps) {
+  const {
+    format,
+    spec,
+    rawSpec,
+    coverageScore,
+    minCoverage,
+    maxDrift,
+    driftExports,
+    typecheckErrors,
+    limit,
+    stdout,
+    outputPath,
+    cwd
+  } = options;
+  const { log } = deps;
+  const stats = computeStats(spec);
+  const report = generateReport(rawSpec);
+  const jsonContent = JSON.stringify(report, null, 2);
+  let formatContent;
+  switch (format) {
+    case "json":
+      formatContent = jsonContent;
+      break;
+    case "markdown":
+      formatContent = renderMarkdown(stats, { limit });
+      break;
+    case "html":
+      formatContent = renderHtml(stats, { limit });
+      break;
+    case "github":
+      formatContent = renderGithubSummary(stats, {
+        coverageScore,
+        driftCount: driftExports.length
+      });
+      break;
+    default:
+      throw new Error(`Unknown format: ${format}`);
   }
-  start(stepIndex) {
-    this.currentStep = stepIndex ?? 0;
-    this.stepStartTime = Date.now();
-    this.render();
+  if (stdout) {
+    log(formatContent);
+  } else {
+    writeReports({
+      format,
+      formatContent,
+      jsonContent,
+      outputPath,
+      cwd
+    });
   }
-  next() {
-    this.completeCurrentStep();
-    this.currentStep++;
-    if (this.currentStep < this.steps.length) {
-      this.stepStartTime = Date.now();
-      this.render();
+  const totalExportsForDrift = spec.exports?.length ?? 0;
+  const exportsWithDrift = new Set(driftExports.map((d) => d.name)).size;
+  const driftScore = totalExportsForDrift === 0 ? 0 : Math.round(exportsWithDrift / totalExportsForDrift * 100);
+  const coverageFailed = coverageScore < minCoverage;
+  const driftFailed = maxDrift !== undefined && driftScore > maxDrift;
+  const hasTypecheckErrors = typecheckErrors.length > 0;
+  return !(coverageFailed || driftFailed || hasTypecheckErrors);
+}
+
+// src/commands/check/validation.ts
+import { validateExamples } from "@doccov/sdk";
+async function runExampleValidation(spec, options) {
+  const { validations, targetDir, timeout = 5000, installTimeout = 60000 } = options;
+  const typecheckErrors = [];
+  const runtimeDrifts = [];
+  const result = await validateExamples(spec.exports ?? [], {
+    validations,
+    packagePath: targetDir,
+    exportNames: (spec.exports ?? []).map((e) => e.name),
+    timeout,
+    installTimeout
+  });
+  if (result.typecheck) {
+    for (const err of result.typecheck.errors) {
+      typecheckErrors.push({
+        exportName: err.exportName,
+        error: err.error
+      });
     }
   }
-  complete(message) {
-    this.completeCurrentStep();
-    if (message) {
-      const elapsed = ((Date.now() - this.startTime) / 1000).toFixed(1);
-      console.log(`${chalk3.green("✓")} ${message} ${chalk3.dim(`(${elapsed}s)`)}`);
+  if (result.run) {
+    for (const drift of result.run.drifts) {
+      runtimeDrifts.push({
+        name: drift.exportName,
+        type: "example-runtime-error",
+        issue: drift.issue,
+        suggestion: drift.suggestion,
+        category: "example"
+      });
     }
   }
-  render() {
-    const step = this.steps[this.currentStep];
-    if (!step)
-      return;
-    const label = step.activeLabel ?? step.label;
-    const prefix = chalk3.dim(`[${this.currentStep + 1}/${this.steps.length}]`);
-    process.stdout.write(`\r${prefix} ${chalk3.cyan(label)}...`);
-  }
-  completeCurrentStep() {
-    const step = this.steps[this.currentStep];
-    if (!step)
-      return;
-    const elapsed = ((Date.now() - this.stepStartTime) / 1000).toFixed(1);
-    const prefix = chalk3.dim(`[${this.currentStep + 1}/${this.steps.length}]`);
-    process.stdout.write(`\r${" ".repeat(80)}\r`);
-    console.log(`${prefix} ${step.label} ${chalk3.green("✓")} ${chalk3.dim(`(${elapsed}s)`)}`);
-  }
-}
-
-// 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)));
+  return { result, typecheckErrors, runtimeDrifts };
 }
-function resolveThreshold(cliValue, configValue) {
-  const raw = cliValue ?? configValue;
-  return raw !== undefined ? clampPercentage(Number(raw)) : undefined;
+async function validateMarkdownDocs(options) {
+  const { docsPatterns, targetDir, exportNames } = options;
+  const staleRefs = [];
+  if (docsPatterns.length === 0) {
+    return staleRefs;
+  }
+  const markdownFiles = await loadMarkdownFiles(docsPatterns, targetDir);
+  if (markdownFiles.length === 0) {
+    return staleRefs;
+  }
+  const exportSet = new Set(exportNames);
+  for (const mdFile of markdownFiles) {
+    for (const block of mdFile.codeBlocks) {
+      const codeLines = block.code.split(`
+`);
+      for (let i = 0;i < codeLines.length; i++) {
+        const line = codeLines[i];
+        const importMatch = line.match(/import\s*\{([^}]+)\}\s*from\s*['"][^'"]*['"]/);
+        if (importMatch) {
+          const imports = importMatch[1].split(",").map((s) => s.trim().split(/\s+/)[0]);
+          for (const imp of imports) {
+            if (imp && !exportSet.has(imp)) {
+              staleRefs.push({
+                file: mdFile.path,
+                line: block.lineStart + i,
+                exportName: imp,
+                context: line.trim()
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+  return staleRefs;
 }
 
-// src/commands/check.ts
+// src/commands/check/index.ts
 var defaultDependencies = {
   createDocCov: (options) => new DocCov(options),
   log: console.log,
   error: console.error
 };
-function collectDriftsFromExports(exports) {
-  const results = [];
-  for (const exp of exports) {
-    for (const drift of exp.docs?.drift ?? []) {
-      results.push({ export: exp, drift });
-    }
-  }
-  return results;
-}
-function groupByExport(drifts) {
-  const map = new Map;
-  for (const { export: exp, drift } of drifts) {
-    const existing = map.get(exp) ?? [];
-    existing.push(drift);
-    map.set(exp, existing);
-  }
-  return map;
-}
 function registerCheckCommand(program, dependencies = {}) {
   const { createDocCov, log, error } = {
     ...defaultDependencies,
     ...dependencies
   };
-  program.command("check [entry]").description("Check documentation coverage and output reports").option("--cwd <dir>", "Working directory", process.cwd()).option("--package <name>", "Target package name (for monorepos)").option("--min-coverage <percentage>", "Minimum docs coverage percentage (0-100)", (value) => Number(value)).option("--max-drift <percentage>", "Maximum drift percentage allowed (0-100)", (value) => Number(value)).option("--examples [mode]", "Example validation: presence, typecheck, run (comma-separated). Bare flag runs all.").option("--skip-resolve", "Skip external type resolution from node_modules").option("--docs <glob>", "Glob pattern for markdown docs to check for stale refs", collect, []).option("--fix", "Auto-fix drift issues").option("--write", "Alias for --fix").option("--preview", "Preview fixes with diff output (implies --fix)").option("--dry-run", "Alias for --preview").option("--format <format>", "Output format: text, json, markdown, html, github", "text").option("-o, --output <file>", "Custom output path (overrides default .doccov/ path)").option("--stdout", "Output to stdout instead of writing to .doccov/").option("--update-snapshot", "Force regenerate .doccov/report.json").option("--limit <n>", "Max exports to show in report tables", "20").option("--max-type-depth <number>", "Maximum depth for type conversion (default: 20)").option("--no-cache", "Bypass spec cache and force regeneration").option("--visibility <tags>", "Filter by release stage: public,beta,alpha,internal (comma-separated)").action(async (entry, options) => {
+  program.command("check [entry]").description("Check documentation coverage and output reports").option("--cwd <dir>", "Working directory", process.cwd()).option("--package <name>", "Target package name (for monorepos)").option("--min-coverage <percentage>", "Minimum docs coverage percentage (0-100)", (value) => Number(value)).option("--max-drift <percentage>", "Maximum drift percentage allowed (0-100)", (value) => Number(value)).option("--examples [mode]", "Example validation: presence, typecheck, run (comma-separated). Bare flag runs all.").option("--skip-resolve", "Skip external type resolution from node_modules").option("--docs <glob>", "Glob pattern for markdown docs to check for stale refs", collect, []).option("--fix", "Auto-fix drift issues").option("--preview", "Preview fixes with diff output (implies --fix)").option("--format <format>", "Output format: text, json, markdown, html, github", "text").option("-o, --output <file>", "Custom output path (overrides default .doccov/ path)").option("--stdout", "Output to stdout instead of writing to .doccov/").option("--update-snapshot", "Force regenerate .doccov/report.json").option("--limit <n>", "Max exports to show in report tables", "20").option("--max-type-depth <number>", "Maximum depth for type conversion (default: 20)", (value) => {
+    const n = parseInt(value, 10);
+    if (Number.isNaN(n) || n < 1)
+      throw new Error("--max-type-depth must be a positive integer");
+    return n;
+  }).option("--no-cache", "Bypass spec cache and force regeneration").option("--visibility <tags>", "Filter by release stage: public,beta,alpha,internal (comma-separated)").action(async (entry, options) => {
     try {
       let validations = parseExamplesFlag(options.examples);
       let hasExamples = validations.length > 0;
@@ -1206,19 +1650,18 @@ function registerCheckCommand(program, dependencies = {}) {
       };
       const resolvedFilters = mergeFilterOptions(config, cliFilters);
       if (resolvedFilters.visibility) {
-        log(chalk4.dim(`Filtering by visibility: ${resolvedFilters.visibility.join(", ")}`));
+        log(chalk6.dim(`Filtering by visibility: ${resolvedFilters.visibility.join(", ")}`));
       }
       steps.next();
       const resolveExternalTypes = !options.skipResolve;
-      let specResult;
       const doccov = createDocCov({
         resolveExternalTypes,
-        maxDepth: options.maxTypeDepth ? parseInt(options.maxTypeDepth, 10) : undefined,
+        maxDepth: options.maxTypeDepth,
         useCache: options.cache !== false,
         cwd: options.cwd
       });
       const analyzeOptions = resolvedFilters.visibility ? { filters: { visibility: resolvedFilters.visibility } } : {};
-      specResult = await doccov.analyzeFileWithDiagnostics(entryFile, analyzeOptions);
+      const specResult = await doccov.analyzeFileWithDiagnostics(entryFile, analyzeOptions);
       if (!specResult) {
         throw new Error("Failed to analyze documentation coverage.");
       }
@@ -1228,384 +1671,84 @@ function registerCheckCommand(program, dependencies = {}) {
       steps.next();
       const specWarnings = specResult.diagnostics.filter((d) => d.severity === "warning");
       const specInfos = specResult.diagnostics.filter((d) => d.severity === "info");
-      const isPreview = options.preview || options.dryRun;
-      const shouldFix = options.fix || options.write || isPreview;
+      const isPreview = options.preview;
+      const shouldFix = options.fix || isPreview;
       let exampleResult;
-      const typecheckErrors = [];
-      const runtimeDrifts = [];
+      let typecheckErrors = [];
+      let runtimeDrifts = [];
       if (hasExamples) {
-        exampleResult = await validateExamples(spec.exports ?? [], {
+        const validation = await runExampleValidation(spec, {
           validations,
-          packagePath: targetDir,
-          exportNames: (spec.exports ?? []).map((e) => e.name),
-          timeout: 5000,
-          installTimeout: 60000
+          targetDir
         });
-        if (exampleResult.typecheck) {
-          for (const err of exampleResult.typecheck.errors) {
-            typecheckErrors.push({
-              exportName: err.exportName,
-              error: err.error
-            });
-          }
-        }
-        if (exampleResult.run) {
-          for (const drift of exampleResult.run.drifts) {
-            runtimeDrifts.push({
-              name: drift.exportName,
-              type: "example-runtime-error",
-              issue: drift.issue,
-              suggestion: drift.suggestion,
-              category: "example"
-            });
-          }
-        }
+        exampleResult = validation.result;
+        typecheckErrors = validation.typecheckErrors;
+        runtimeDrifts = validation.runtimeDrifts;
         steps.next();
       }
-      const staleRefs = [];
       let docsPatterns = options.docs;
       if (docsPatterns.length === 0 && config?.docs?.include) {
         docsPatterns = config.docs.include;
       }
-      if (docsPatterns.length > 0) {
-        const markdownFiles = await loadMarkdownFiles(docsPatterns, targetDir);
-        if (markdownFiles.length > 0) {
-          const exportNames = (spec.exports ?? []).map((e) => e.name);
-          const exportSet = new Set(exportNames);
-          for (const mdFile of markdownFiles) {
-            for (const block of mdFile.codeBlocks) {
-              const codeLines = block.code.split(`
-`);
-              for (let i = 0;i < codeLines.length; i++) {
-                const line = codeLines[i];
-                const importMatch = line.match(/import\s*\{([^}]+)\}\s*from\s*['"][^'"]*['"]/);
-                if (importMatch) {
-                  const imports = importMatch[1].split(",").map((s) => s.trim().split(/\s+/)[0]);
-                  for (const imp of imports) {
-                    if (imp && !exportSet.has(imp)) {
-                      staleRefs.push({
-                        file: mdFile.path,
-                        line: block.lineStart + i,
-                        exportName: imp,
-                        context: line.trim()
-                      });
-                    }
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
+      const staleRefs = await validateMarkdownDocs({
+        docsPatterns,
+        targetDir,
+        exportNames: (spec.exports ?? []).map((e) => e.name)
+      });
       const coverageScore = spec.docs?.coverageScore ?? 0;
       const allDriftExports = [...collectDrift(spec.exports ?? []), ...runtimeDrifts];
       let driftExports = hasExamples ? allDriftExports : allDriftExports.filter((d) => d.category !== "example");
-      const fixedDriftKeys = new Set;
       if (shouldFix && driftExports.length > 0) {
-        const allDrifts = collectDriftsFromExports(spec.exports ?? []);
-        if (allDrifts.length > 0) {
-          const { fixable, nonFixable } = categorizeDrifts(allDrifts.map((d) => d.drift));
-          if (fixable.length === 0) {
-            log(chalk4.yellow(`Found ${nonFixable.length} drift issue(s), but none are auto-fixable.`));
-          } else {
-            log("");
-            log(chalk4.bold(`Found ${fixable.length} fixable issue(s)`));
-            if (nonFixable.length > 0) {
-              log(chalk4.gray(`(${nonFixable.length} non-fixable issue(s) skipped)`));
-            }
-            log("");
-            const groupedDrifts = groupByExport(allDrifts.filter((d) => fixable.includes(d.drift)));
-            const edits = [];
-            const editsByFile = new Map;
-            for (const [exp, drifts] of groupedDrifts) {
-              if (!exp.source?.file) {
-                log(chalk4.gray(`  Skipping ${exp.name}: no source location`));
-                continue;
-              }
-              if (exp.source.file.endsWith(".d.ts")) {
-                log(chalk4.gray(`  Skipping ${exp.name}: declaration file`));
-                continue;
-              }
-              const filePath = path4.resolve(targetDir, exp.source.file);
-              if (!fs2.existsSync(filePath)) {
-                log(chalk4.gray(`  Skipping ${exp.name}: file not found`));
-                continue;
-              }
-              const sourceFile = createSourceFile(filePath);
-              const location = findJSDocLocation(sourceFile, exp.name, exp.source.line);
-              if (!location) {
-                log(chalk4.gray(`  Skipping ${exp.name}: could not find declaration`));
-                continue;
-              }
-              let existingPatch = {};
-              if (location.hasExisting && location.existingJSDoc) {
-                existingPatch = parseJSDocToPatch(location.existingJSDoc);
-              }
-              const expWithDrift = { ...exp, docs: { ...exp.docs, drift: drifts } };
-              const fixes = generateFixesForExport(expWithDrift, existingPatch);
-              if (fixes.length === 0)
-                continue;
-              for (const drift of drifts) {
-                fixedDriftKeys.add(`${exp.name}:${drift.issue}`);
-              }
-              const mergedPatch = mergeFixes(fixes, existingPatch);
-              const newJSDoc = serializeJSDoc(mergedPatch, location.indent);
-              const edit = {
-                filePath,
-                symbolName: exp.name,
-                startLine: location.startLine,
-                endLine: location.endLine,
-                hasExisting: location.hasExisting,
-                existingJSDoc: location.existingJSDoc,
-                newJSDoc,
-                indent: location.indent
-              };
-              edits.push(edit);
-              const fileEdits = editsByFile.get(filePath) ?? [];
-              fileEdits.push({ export: exp, edit, fixes, existingPatch });
-              editsByFile.set(filePath, fileEdits);
-            }
-            if (edits.length > 0) {
-              if (isPreview) {
-                log(chalk4.bold("Preview - changes that would be made:"));
-                log("");
-                for (const [filePath, fileEdits] of editsByFile) {
-                  const relativePath = path4.relative(targetDir, filePath);
-                  for (const { export: exp, edit, fixes } of fileEdits) {
-                    log(chalk4.cyan(`${relativePath}:${edit.startLine + 1}`));
-                    log(chalk4.bold(`  ${exp.name}`));
-                    log("");
-                    if (edit.hasExisting && edit.existingJSDoc) {
-                      const oldLines = edit.existingJSDoc.split(`
-`);
-                      const newLines = edit.newJSDoc.split(`
-`);
-                      for (const line of oldLines) {
-                        log(chalk4.red(`  - ${line}`));
-                      }
-                      for (const line of newLines) {
-                        log(chalk4.green(`  + ${line}`));
-                      }
-                    } else {
-                      const newLines = edit.newJSDoc.split(`
-`);
-                      for (const line of newLines) {
-                        log(chalk4.green(`  + ${line}`));
-                      }
-                    }
-                    log("");
-                    log(chalk4.dim(`  Fixes: ${fixes.map((f) => f.description).join(", ")}`));
-                    log("");
-                  }
-                }
-                const totalFixes = Array.from(editsByFile.values()).reduce((sum, edits2) => sum + edits2.reduce((s, e) => s + e.fixes.length, 0), 0);
-                log(chalk4.yellow(`${totalFixes} fix(es) across ${editsByFile.size} file(s) would be applied.`));
-                log(chalk4.gray("Run with --fix to apply these changes."));
-              } else {
-                const applyResult = await applyEdits(edits);
-                if (applyResult.errors.length > 0) {
-                  for (const err of applyResult.errors) {
-                    error(chalk4.red(`  ${err.file}: ${err.error}`));
-                  }
-                }
-                const totalFixes = Array.from(editsByFile.values()).reduce((sum, edits2) => sum + edits2.reduce((s, e) => s + e.fixes.length, 0), 0);
-                log("");
-                log(chalk4.green(`✓ Applied ${totalFixes} fix(es) to ${applyResult.filesModified} file(s)`));
-                for (const [filePath, fileEdits] of editsByFile) {
-                  const relativePath = path4.relative(targetDir, filePath);
-                  const fixCount = fileEdits.reduce((s, e) => s + e.fixes.length, 0);
-                  log(chalk4.dim(`  ${relativePath} (${fixCount} fixes)`));
-                }
-              }
-            }
-          }
-        }
+        const fixResult = await handleFixes(spec, { isPreview, targetDir }, { log, error });
         if (!isPreview) {
-          driftExports = driftExports.filter((d) => !fixedDriftKeys.has(`${d.name}:${d.issue}`));
+          driftExports = driftExports.filter((d) => !fixResult.fixedDriftKeys.has(`${d.name}:${d.issue}`));
         }
       }
       steps.complete("Check complete");
       if (format !== "text") {
-        const limit = parseInt(options.limit, 10) || 20;
-        const stats = computeStats(spec);
-        const report = generateReport(specResult.spec);
-        const jsonContent = JSON.stringify(report, null, 2);
-        let formatContent;
-        switch (format) {
-          case "json":
-            formatContent = jsonContent;
-            break;
-          case "markdown":
-            formatContent = renderMarkdown(stats, { limit });
-            break;
-          case "html":
-            formatContent = renderHtml(stats, { limit });
-            break;
-          case "github":
-            formatContent = renderGithubSummary(stats, {
-              coverageScore,
-              driftCount: driftExports.length
-            });
-            break;
-          default:
-            throw new Error(`Unknown format: ${format}`);
-        }
-        if (options.stdout) {
-          log(formatContent);
-        } else {
-          writeReports({
-            format,
-            formatContent,
-            jsonContent,
-            outputPath: options.output,
-            cwd: options.cwd
-          });
-        }
-        const totalExportsForDrift2 = spec.exports?.length ?? 0;
-        const exportsWithDrift2 = new Set(driftExports.map((d) => d.name)).size;
-        const driftScore2 = totalExportsForDrift2 === 0 ? 0 : Math.round(exportsWithDrift2 / totalExportsForDrift2 * 100);
-        const coverageFailed2 = coverageScore < minCoverage;
-        const driftFailed2 = maxDrift !== undefined && driftScore2 > maxDrift;
-        const hasTypecheckErrors2 = typecheckErrors.length > 0;
-        if (coverageFailed2 || driftFailed2 || hasTypecheckErrors2) {
+        const passed2 = handleNonTextOutput({
+          format,
+          spec,
+          rawSpec: specResult.spec,
+          coverageScore,
+          minCoverage,
+          maxDrift,
+          driftExports,
+          typecheckErrors,
+          limit: parseInt(options.limit, 10) || 20,
+          stdout: options.stdout,
+          outputPath: options.output,
+          cwd: options.cwd
+        }, { log });
+        if (!passed2) {
           process.exit(1);
         }
         return;
       }
-      const totalExportsForDrift = spec.exports?.length ?? 0;
-      const exportsWithDrift = new Set(driftExports.map((d) => d.name)).size;
-      const driftScore = totalExportsForDrift === 0 ? 0 : Math.round(exportsWithDrift / totalExportsForDrift * 100);
-      const coverageFailed = coverageScore < minCoverage;
-      const driftFailed = maxDrift !== undefined && driftScore > maxDrift;
-      const hasTypecheckErrors = typecheckErrors.length > 0;
-      if (specWarnings.length > 0 || specInfos.length > 0) {
-        log("");
-        for (const diag of specWarnings) {
-          log(chalk4.yellow(`⚠ ${diag.message}`));
-          if (diag.suggestion) {
-            log(chalk4.gray(`  ${diag.suggestion}`));
-          }
-        }
-        for (const diag of specInfos) {
-          log(chalk4.cyan(`ℹ ${diag.message}`));
-          if (diag.suggestion) {
-            log(chalk4.gray(`  ${diag.suggestion}`));
-          }
-        }
-      }
-      const pkgName = spec.meta?.name ?? "unknown";
-      const pkgVersion = spec.meta?.version ?? "";
-      const totalExports = spec.exports?.length ?? 0;
-      log("");
-      log(chalk4.bold(`${pkgName}${pkgVersion ? `@${pkgVersion}` : ""}`));
-      log("");
-      log(`  Exports:    ${totalExports}`);
-      if (coverageFailed) {
-        log(chalk4.red(`  Coverage:   ✗ ${coverageScore}%`) + chalk4.dim(` (min ${minCoverage}%)`));
-      } else {
-        log(chalk4.green(`  Coverage:   ✓ ${coverageScore}%`) + chalk4.dim(` (min ${minCoverage}%)`));
-      }
-      if (maxDrift !== undefined) {
-        if (driftFailed) {
-          log(chalk4.red(`  Drift:      ✗ ${driftScore}%`) + chalk4.dim(` (max ${maxDrift}%)`));
-        } else {
-          log(chalk4.green(`  Drift:      ✓ ${driftScore}%`) + chalk4.dim(` (max ${maxDrift}%)`));
-        }
-      } else {
-        log(`  Drift:      ${driftScore}%`);
-      }
-      if (exampleResult) {
-        const typecheckCount = exampleResult.typecheck?.errors.length ?? 0;
-        if (typecheckCount > 0) {
-          log(chalk4.yellow(`  Examples:   ${typecheckCount} type error(s)`));
-          for (const err of typecheckErrors.slice(0, 5)) {
-            const loc = `example[${err.error.exampleIndex}]:${err.error.line}:${err.error.column}`;
-            log(chalk4.dim(`              ${err.exportName} ${loc}`));
-            log(chalk4.red(`                ${err.error.message}`));
-          }
-          if (typecheckErrors.length > 5) {
-            log(chalk4.dim(`              ... and ${typecheckErrors.length - 5} more`));
-          }
-        } else {
-          log(chalk4.green(`  Examples:   ✓ validated`));
-        }
-      }
-      const hasStaleRefs = staleRefs.length > 0;
-      if (hasStaleRefs) {
-        log(chalk4.yellow(`  Docs:       ${staleRefs.length} stale ref(s)`));
-        for (const ref of staleRefs.slice(0, 5)) {
-          log(chalk4.dim(`              ${ref.file}:${ref.line} - "${ref.exportName}"`));
-        }
-        if (staleRefs.length > 5) {
-          log(chalk4.dim(`              ... and ${staleRefs.length - 5} more`));
-        }
-      }
-      log("");
-      const failed = coverageFailed || driftFailed || hasTypecheckErrors || hasStaleRefs;
-      if (!failed) {
-        const thresholdParts = [];
-        thresholdParts.push(`coverage ${coverageScore}% ≥ ${minCoverage}%`);
-        if (maxDrift !== undefined) {
-          thresholdParts.push(`drift ${driftScore}% ≤ ${maxDrift}%`);
-        }
-        log(chalk4.green(`✓ Check passed (${thresholdParts.join(", ")})`));
-        return;
-      }
-      if (hasTypecheckErrors) {
-        log(chalk4.red(`✗ ${typecheckErrors.length} example type errors`));
-      }
-      if (hasStaleRefs) {
-        log(chalk4.red(`✗ ${staleRefs.length} stale references in docs`));
+      const passed = displayTextOutput({
+        spec,
+        coverageScore,
+        minCoverage,
+        maxDrift,
+        driftExports,
+        typecheckErrors,
+        staleRefs,
+        exampleResult,
+        specWarnings,
+        specInfos
+      }, { log });
+      if (!passed) {
+        process.exit(1);
       }
-      log("");
-      log(chalk4.dim("Use --format json or --format markdown for detailed reports"));
-      process.exit(1);
     } catch (commandError) {
-      error(chalk4.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      error(chalk6.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
       process.exit(1);
     }
   });
 }
-function collectDrift(exportsList) {
-  const drifts = [];
-  for (const entry of exportsList) {
-    const drift = entry.docs?.drift;
-    if (!drift || drift.length === 0) {
-      continue;
-    }
-    for (const d of drift) {
-      drifts.push({
-        name: entry.name,
-        type: d.type,
-        issue: d.issue ?? "Documentation drift detected.",
-        suggestion: d.suggestion,
-        category: DRIFT_CATEGORIES2[d.type]
-      });
-    }
-  }
-  return drifts;
-}
-function collect(value, previous) {
-  return previous.concat([value]);
-}
-async function loadMarkdownFiles(patterns, cwd) {
-  const files = [];
-  for (const pattern of patterns) {
-    const matches = await glob(pattern, { nodir: true, cwd });
-    for (const filePath of matches) {
-      try {
-        const fullPath = path4.resolve(cwd, filePath);
-        const content = fs2.readFileSync(fullPath, "utf-8");
-        files.push({ path: filePath, content });
-      } catch {}
-    }
-  }
-  return parseMarkdownFiles(files);
-}
-
 // src/commands/diff.ts
-import * as fs3 from "node:fs";
-import * as path5 from "node:path";
+import * as fs4 from "node:fs";
+import * as path6 from "node:path";
 import {
   diffSpecWithDocs,
   ensureSpecCoverage,
@@ -1616,10 +1759,10 @@ import {
   parseMarkdownFiles as parseMarkdownFiles2
 } from "@doccov/sdk";
 import { calculateNextVersion, recommendSemverBump } from "@openpkg-ts/spec";
-import chalk5 from "chalk";
+import chalk7 from "chalk";
 import { glob as glob2 } from "glob";
 var defaultDependencies2 = {
-  readFileSync: fs3.readFileSync,
+  readFileSync: fs4.readFileSync,
   log: console.log,
   error: console.error
 };
@@ -1657,12 +1800,12 @@ function registerDiffCommand(program, dependencies = {}) {
       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"));
+      const cachedReportPath = path6.resolve(options.cwd, getDiffReportPath(baseHash, headHash, "json"));
       let diff;
       let fromCache = false;
-      if (cacheEnabled && fs3.existsSync(cachedReportPath)) {
+      if (cacheEnabled && fs4.existsSync(cachedReportPath)) {
         try {
-          const cached = JSON.parse(fs3.readFileSync(cachedReportPath, "utf-8"));
+          const cached = JSON.parse(fs4.readFileSync(cachedReportPath, "utf-8"));
           diff = cached;
           fromCache = true;
         } catch {
@@ -1689,9 +1832,9 @@ function registerDiffCommand(program, dependencies = {}) {
           }, null, 2));
         } else {
           log("");
-          log(chalk5.bold("Semver Recommendation"));
+          log(chalk7.bold("Semver Recommendation"));
           log(`  Current version:    ${currentVersion}`);
-          log(`  Recommended:        ${chalk5.cyan(nextVersion)} (${chalk5.yellow(recommendation.bump.toUpperCase())})`);
+          log(`  Recommended:        ${chalk7.cyan(nextVersion)} (${chalk7.yellow(recommendation.bump.toUpperCase())})`);
           log(`  Reason:             ${recommendation.reason}`);
         }
         return;
@@ -1699,8 +1842,8 @@ function registerDiffCommand(program, dependencies = {}) {
       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 baseName = path6.basename(baseFile);
+      const headName = path6.basename(headFile);
       const reportData = {
         baseName,
         headName,
@@ -1720,8 +1863,8 @@ function registerDiffCommand(program, dependencies = {}) {
                 silent: true
               });
             }
-            const cacheNote = fromCache ? chalk5.cyan(" (cached)") : "";
-            log(chalk5.dim(`Report: ${jsonPath}`) + cacheNote);
+            const cacheNote = fromCache ? chalk7.cyan(" (cached)") : "";
+            log(chalk7.dim(`Report: ${jsonPath}`) + cacheNote);
           }
           break;
         case "json": {
@@ -1779,7 +1922,10 @@ function registerDiffCommand(program, dependencies = {}) {
             sha: options.sha,
             minCoverage,
             limit,
-            semverBump: { bump: semverRecommendation.bump, reason: semverRecommendation.reason }
+            semverBump: {
+              bump: semverRecommendation.bump,
+              reason: semverRecommendation.reason
+            }
           });
           log(content);
           break;
@@ -1813,18 +1959,18 @@ function registerDiffCommand(program, dependencies = {}) {
         checks
       });
       if (failures.length > 0) {
-        log(chalk5.red(`
+        log(chalk7.red(`
 ✗ Check failed`));
         for (const f of failures) {
-          log(chalk5.red(`  - ${f}`));
+          log(chalk7.red(`  - ${f}`));
         }
         process.exitCode = 1;
       } else if (options.strict || minCoverage !== undefined || maxDrift !== undefined) {
-        log(chalk5.green(`
+        log(chalk7.green(`
 ✓ All checks passed`));
       }
     } catch (commandError) {
-      error(chalk5.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      error(chalk7.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
       process.exitCode = 1;
     }
   });
@@ -1838,7 +1984,7 @@ async function loadMarkdownFiles2(patterns) {
     const matches = await glob2(pattern, { nodir: true });
     for (const filePath of matches) {
       try {
-        const content = fs3.readFileSync(filePath, "utf-8");
+        const content = fs4.readFileSync(filePath, "utf-8");
         files.push({ path: filePath, content });
       } catch {}
     }
@@ -1851,7 +1997,7 @@ async function generateDiff(baseSpec, headSpec, options, config, log) {
   if (!docsPatterns || docsPatterns.length === 0) {
     if (config?.docs?.include) {
       docsPatterns = config.docs.include;
-      log(chalk5.gray(`Using docs patterns from config: ${docsPatterns.join(", ")}`));
+      log(chalk7.gray(`Using docs patterns from config: ${docsPatterns.join(", ")}`));
     }
   }
   if (docsPatterns && docsPatterns.length > 0) {
@@ -1860,8 +2006,8 @@ async function generateDiff(baseSpec, headSpec, options, config, log) {
   return diffSpecWithDocs(baseSpec, headSpec, { markdownFiles });
 }
 function loadSpec(filePath, readFileSync3) {
-  const resolvedPath = path5.resolve(filePath);
-  if (!fs3.existsSync(resolvedPath)) {
+  const resolvedPath = path6.resolve(filePath);
+  if (!fs4.existsSync(resolvedPath)) {
     throw new Error(`File not found: ${filePath}`);
   }
   try {
@@ -1874,37 +2020,37 @@ function loadSpec(filePath, readFileSync3) {
 }
 function printSummary(diff, baseName, headName, fromCache, log) {
   log("");
-  const cacheIndicator = fromCache ? chalk5.cyan(" (cached)") : "";
-  log(chalk5.bold(`Comparing: ${baseName} → ${headName}`) + cacheIndicator);
+  const cacheIndicator = fromCache ? chalk7.cyan(" (cached)") : "";
+  log(chalk7.bold(`Comparing: ${baseName} → ${headName}`) + cacheIndicator);
   log("─".repeat(40));
   log("");
-  const coverageColor = diff.coverageDelta > 0 ? chalk5.green : diff.coverageDelta < 0 ? chalk5.red : chalk5.gray;
+  const coverageColor = diff.coverageDelta > 0 ? chalk7.green : diff.coverageDelta < 0 ? chalk7.red : chalk7.gray;
   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 ? chalk5.red(` (${highSeverity} high severity)`) : "";
-    log(`  Breaking:   ${chalk5.red(breakingCount)} changes${severityNote}`);
+    const severityNote = highSeverity > 0 ? chalk7.red(` (${highSeverity} high severity)`) : "";
+    log(`  Breaking:   ${chalk7.red(breakingCount)} changes${severityNote}`);
   } else {
-    log(`  Breaking:   ${chalk5.green("0")} changes`);
+    log(`  Breaking:   ${chalk7.green("0")} changes`);
   }
   const newCount = diff.nonBreaking.length;
   const undocCount = diff.newUndocumented.length;
   if (newCount > 0) {
-    const undocNote = undocCount > 0 ? chalk5.yellow(` (${undocCount} undocumented)`) : "";
-    log(`  New:        ${chalk5.green(newCount)} exports${undocNote}`);
+    const undocNote = undocCount > 0 ? chalk7.yellow(` (${undocCount} undocumented)`) : "";
+    log(`  New:        ${chalk7.green(newCount)} exports${undocNote}`);
   }
   if (diff.driftIntroduced > 0 || diff.driftResolved > 0) {
     const parts = [];
     if (diff.driftIntroduced > 0)
-      parts.push(chalk5.red(`+${diff.driftIntroduced}`));
+      parts.push(chalk7.red(`+${diff.driftIntroduced}`));
     if (diff.driftResolved > 0)
-      parts.push(chalk5.green(`-${diff.driftResolved}`));
+      parts.push(chalk7.green(`-${diff.driftResolved}`));
     log(`  Drift:      ${parts.join(", ")}`);
   }
   const recommendation = recommendSemverBump(diff);
-  const bumpColor = recommendation.bump === "major" ? chalk5.red : recommendation.bump === "minor" ? chalk5.yellow : chalk5.green;
+  const bumpColor = recommendation.bump === "major" ? chalk7.red : recommendation.bump === "minor" ? chalk7.yellow : chalk7.green;
   log(`  Semver:     ${bumpColor(recommendation.bump.toUpperCase())} (${recommendation.reason})`);
   log("");
 }
@@ -1986,7 +2132,7 @@ function printGitHubAnnotations(diff, log) {
 
 // src/commands/info.ts
 import { DocCov as DocCov2, enrichSpec as enrichSpec2, NodeFileSystem as NodeFileSystem2, resolveTarget as resolveTarget2 } from "@doccov/sdk";
-import chalk6 from "chalk";
+import chalk8 from "chalk";
 function registerInfoCommand(program) {
   program.command("info [entry]").description("Show brief documentation coverage summary").option("--cwd <dir>", "Working directory", process.cwd()).option("--package <name>", "Target package name (for monorepos)").option("--skip-resolve", "Skip external type resolution from node_modules").action(async (entry, options) => {
     try {
@@ -2008,28 +2154,28 @@ function registerInfoCommand(program) {
       const spec = enrichSpec2(specResult.spec);
       const stats = computeStats(spec);
       console.log("");
-      console.log(chalk6.bold(`${stats.packageName}@${stats.version}`));
+      console.log(chalk8.bold(`${stats.packageName}@${stats.version}`));
       console.log("");
-      console.log(`  Exports:    ${chalk6.bold(stats.totalExports.toString())}`);
-      console.log(`  Coverage:   ${chalk6.bold(`${stats.coverageScore}%`)}`);
-      console.log(`  Drift:      ${chalk6.bold(`${stats.driftScore}%`)}`);
+      console.log(`  Exports:    ${chalk8.bold(stats.totalExports.toString())}`);
+      console.log(`  Coverage:   ${chalk8.bold(`${stats.coverageScore}%`)}`);
+      console.log(`  Drift:      ${chalk8.bold(`${stats.driftScore}%`)}`);
       console.log("");
     } catch (err) {
-      console.error(chalk6.red("Error:"), err instanceof Error ? err.message : err);
+      console.error(chalk8.red("Error:"), err instanceof Error ? err.message : err);
       process.exit(1);
     }
   });
 }
 
 // src/commands/init.ts
-import * as fs4 from "node:fs";
-import * as path6 from "node:path";
-import chalk7 from "chalk";
+import * as fs5 from "node:fs";
+import * as path7 from "node:path";
+import chalk9 from "chalk";
 var defaultDependencies3 = {
-  fileExists: fs4.existsSync,
-  writeFileSync: fs4.writeFileSync,
-  readFileSync: fs4.readFileSync,
-  mkdirSync: fs4.mkdirSync,
+  fileExists: fs5.existsSync,
+  writeFileSync: fs5.writeFileSync,
+  readFileSync: fs5.readFileSync,
+  mkdirSync: fs5.mkdirSync,
   log: console.log,
   error: console.error
 };
@@ -2039,56 +2185,56 @@ function registerInitCommand(program, dependencies = {}) {
     ...dependencies
   };
   program.command("init").description("Initialize DocCov: config, GitHub Action, and badge").option("--cwd <dir>", "Working directory", process.cwd()).option("--skip-action", "Skip GitHub Action workflow creation").action((options) => {
-    const cwd = path6.resolve(options.cwd);
+    const cwd = path7.resolve(options.cwd);
     const existing = findExistingConfig(cwd, fileExists2);
     if (existing) {
-      error(chalk7.red(`A DocCov config already exists at ${path6.relative(cwd, existing) || "./doccov.config.*"}.`));
+      error(chalk9.red(`A DocCov config already exists at ${path7.relative(cwd, existing) || "./doccov.config.*"}.`));
       process.exitCode = 1;
       return;
     }
     const packageType = detectPackageType(cwd, fileExists2, readFileSync4);
     const targetFormat = packageType === "module" ? "ts" : "mts";
     const fileName = `doccov.config.${targetFormat}`;
-    const outputPath = path6.join(cwd, fileName);
+    const outputPath = path7.join(cwd, fileName);
     if (fileExists2(outputPath)) {
-      error(chalk7.red(`Cannot create ${fileName}; file already exists.`));
+      error(chalk9.red(`Cannot create ${fileName}; file already exists.`));
       process.exitCode = 1;
       return;
     }
     const template = buildConfigTemplate();
     writeFileSync3(outputPath, template, { encoding: "utf8" });
-    log(chalk7.green(`✓ Created ${fileName}`));
+    log(chalk9.green(`✓ Created ${fileName}`));
     if (!options.skipAction) {
-      const workflowDir = path6.join(cwd, ".github", "workflows");
-      const workflowPath = path6.join(workflowDir, "doccov.yml");
+      const workflowDir = path7.join(cwd, ".github", "workflows");
+      const workflowPath = path7.join(workflowDir, "doccov.yml");
       if (!fileExists2(workflowPath)) {
         mkdirSync3(workflowDir, { recursive: true });
         writeFileSync3(workflowPath, buildWorkflowTemplate(), { encoding: "utf8" });
-        log(chalk7.green(`✓ Created .github/workflows/doccov.yml`));
+        log(chalk9.green(`✓ Created .github/workflows/doccov.yml`));
       } else {
-        log(chalk7.yellow(`  Skipped .github/workflows/doccov.yml (already exists)`));
+        log(chalk9.yellow(`  Skipped .github/workflows/doccov.yml (already exists)`));
       }
     }
     const repoInfo = detectRepoInfo(cwd, fileExists2, readFileSync4);
     log("");
-    log(chalk7.bold("Add this badge to your README:"));
+    log(chalk9.bold("Add this badge to your README:"));
     log("");
     if (repoInfo) {
-      log(chalk7.cyan(`[![DocCov](https://doccov.dev/badge/${repoInfo.owner}/${repoInfo.repo})](https://doccov.dev/${repoInfo.owner}/${repoInfo.repo})`));
+      log(chalk9.cyan(`[![DocCov](https://doccov.dev/badge/${repoInfo.owner}/${repoInfo.repo})](https://doccov.dev/${repoInfo.owner}/${repoInfo.repo})`));
     } else {
-      log(chalk7.cyan(`[![DocCov](https://doccov.dev/badge/OWNER/REPO)](https://doccov.dev/OWNER/REPO)`));
-      log(chalk7.dim("  Replace OWNER/REPO with your GitHub repo"));
+      log(chalk9.cyan(`[![DocCov](https://doccov.dev/badge/OWNER/REPO)](https://doccov.dev/OWNER/REPO)`));
+      log(chalk9.dim("  Replace OWNER/REPO with your GitHub repo"));
     }
     log("");
-    log(chalk7.dim("Run `doccov check` to verify your documentation coverage"));
+    log(chalk9.dim("Run `doccov check` to verify your documentation coverage"));
   });
 }
 var findExistingConfig = (cwd, fileExists2) => {
-  let current = path6.resolve(cwd);
-  const { root } = path6.parse(current);
+  let current = path7.resolve(cwd);
+  const { root } = path7.parse(current);
   while (true) {
     for (const candidate of DOCCOV_CONFIG_FILENAMES) {
-      const candidatePath = path6.join(current, candidate);
+      const candidatePath = path7.join(current, candidate);
       if (fileExists2(candidatePath)) {
         return candidatePath;
       }
@@ -2096,7 +2242,7 @@ var findExistingConfig = (cwd, fileExists2) => {
     if (current === root) {
       break;
     }
-    current = path6.dirname(current);
+    current = path7.dirname(current);
   }
   return null;
 };
@@ -2118,17 +2264,17 @@ var detectPackageType = (cwd, fileExists2, readFileSync4) => {
   return;
 };
 var findNearestPackageJson = (cwd, fileExists2) => {
-  let current = path6.resolve(cwd);
-  const { root } = path6.parse(current);
+  let current = path7.resolve(cwd);
+  const { root } = path7.parse(current);
   while (true) {
-    const candidate = path6.join(current, "package.json");
+    const candidate = path7.join(current, "package.json");
     if (fileExists2(candidate)) {
       return candidate;
     }
     if (current === root) {
       break;
     }
-    current = path6.dirname(current);
+    current = path7.dirname(current);
   }
   return null;
 };
@@ -2190,7 +2336,7 @@ var detectRepoInfo = (cwd, fileExists2, readFileSync4) => {
       }
     } catch {}
   }
-  const gitConfigPath = path6.join(cwd, ".git", "config");
+  const gitConfigPath = path7.join(cwd, ".git", "config");
   if (fileExists2(gitConfigPath)) {
     try {
       const config = readFileSync4(gitConfigPath, "utf8");
@@ -2204,18 +2350,26 @@ var detectRepoInfo = (cwd, fileExists2, readFileSync4) => {
 };
 
 // src/commands/spec.ts
-import * as fs5 from "node:fs";
-import * as path7 from "node:path";
-import { detectPackageManager, DocCov as DocCov3, NodeFileSystem as NodeFileSystem3, renderApiSurface, resolveTarget as resolveTarget3 } from "@doccov/sdk";
+import * as fs6 from "node:fs";
+import * as path8 from "node:path";
+import {
+  buildDocCovSpec,
+  DocCov as DocCov3,
+  detectPackageManager,
+  NodeFileSystem as NodeFileSystem3,
+  renderApiSurface,
+  resolveTarget as resolveTarget3
+} from "@doccov/sdk";
+import { validateDocCovSpec } from "@doccov/spec";
 import { normalize, validateSpec } from "@openpkg-ts/spec";
-import chalk8 from "chalk";
+import chalk10 from "chalk";
 // package.json
-var version = "0.21.0";
+var version = "0.23.0";
 
 // src/commands/spec.ts
 var defaultDependencies4 = {
   createDocCov: (options) => new DocCov3(options),
-  writeFileSync: fs5.writeFileSync,
+  writeFileSync: fs6.writeFileSync,
   log: console.log,
   error: console.error
 };
@@ -2224,8 +2378,8 @@ function getArrayLength(value) {
 }
 function formatDiagnosticOutput(prefix, diagnostic, baseDir) {
   const location = diagnostic.location;
-  const relativePath = location?.file ? path7.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 ? path8.relative(baseDir, location.file) || location.file : undefined;
+  const locationText = location && relativePath ? chalk10.gray(`${relativePath}:${location.line ?? 1}:${location.column ?? 1}`) : null;
   const locationPrefix = locationText ? `${locationText} ` : "";
   return `${prefix} ${locationPrefix}${diagnostic.message}`;
 }
@@ -2234,15 +2388,19 @@ function registerSpecCommand(program, dependencies = {}) {
     ...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("-f, --format <format>", "Output format: json (default) or api-surface", "json").option("--include <patterns>", "Include exports matching pattern (comma-separated)").option("--exclude <patterns>", "Exclude exports matching pattern (comma-separated)").option("--visibility <tags>", "Filter by release stage: public,beta,alpha,internal (comma-separated)").option("--skip-resolve", "Skip external type resolution from node_modules").option("--max-type-depth <n>", "Maximum depth for type conversion", "20").option("--runtime", "Enable Standard Schema runtime extraction (richer output for Zod, Valibot, etc.)").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) => {
+  program.command("spec [entry]").description("Generate OpenPkg + DocCov specifications").option("--cwd <dir>", "Working directory", process.cwd()).option("-p, --package <name>", "Target package name (for monorepos)").option("-o, --output <dir>", "Output directory", ".doccov").option("-f, --format <format>", "Output format: json (default) or api-surface", "json").option("--openpkg-only", "Only generate openpkg.json (skip coverage analysis)").option("--include <patterns>", "Include exports matching pattern (comma-separated)").option("--exclude <patterns>", "Exclude exports matching pattern (comma-separated)").option("--visibility <tags>", "Filter by release stage: public,beta,alpha,internal (comma-separated)").option("--skip-resolve", "Skip external type resolution from node_modules").option("--max-type-depth <n>", "Maximum depth for type conversion", "20").option("--runtime", "Enable Standard Schema runtime extraction (richer output for Zod, Valibot, etc.)").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 steps = new StepProgress([
+      const stepsList = [
         { label: "Resolved target", activeLabel: "Resolving target" },
         { label: "Loaded config", activeLabel: "Loading config" },
         { label: "Generated spec", activeLabel: "Generating spec" },
-        { label: "Validated schema", activeLabel: "Validating schema" },
-        { label: "Wrote output", activeLabel: "Writing output" }
-      ]);
+        { label: "Validated schema", activeLabel: "Validating schema" }
+      ];
+      if (!options.openpkgOnly) {
+        stepsList.push({ label: "Built coverage analysis", activeLabel: "Building coverage" });
+      }
+      stepsList.push({ label: "Wrote output", activeLabel: "Writing output" });
+      const steps = new StepProgress(stepsList);
       steps.start();
       const fileSystem = new NodeFileSystem3(options.cwd);
       const resolved = await resolveTarget3(fileSystem, {
@@ -2256,7 +2414,7 @@ function registerSpecCommand(program, dependencies = {}) {
       try {
         config = await loadDocCovConfig(targetDir);
       } catch (configError) {
-        error(chalk8.red("Failed to load DocCov config:"), configError instanceof Error ? configError.message : configError);
+        error(chalk10.red("Failed to load DocCov config:"), configError instanceof Error ? configError.message : configError);
         process.exit(1);
       }
       steps.next();
@@ -2275,7 +2433,7 @@ function registerSpecCommand(program, dependencies = {}) {
         schemaExtraction: options.runtime ? "hybrid" : "static"
       });
       const generationInput = {
-        entryPoint: path7.relative(targetDir, entryFile),
+        entryPoint: path8.relative(targetDir, entryFile),
         entryPointSource: entryPointInfo.source,
         isDeclarationOnly: entryPointInfo.isDeclarationOnly ?? false,
         generatorName: "@doccov/cli",
@@ -2300,95 +2458,123 @@ function registerSpecCommand(program, dependencies = {}) {
       const normalized = normalize(result.spec);
       const validation = validateSpec(normalized);
       if (!validation.ok) {
-        error(chalk8.red("Spec failed schema validation"));
+        error(chalk10.red("Spec failed schema validation"));
         for (const err of validation.errors) {
-          error(chalk8.red(`schema: ${err.instancePath || "/"} ${err.message}`));
+          error(chalk10.red(`schema: ${err.instancePath || "/"} ${err.message}`));
         }
         process.exit(1);
       }
       steps.next();
+      let doccovSpec = null;
+      if (!options.openpkgOnly) {
+        doccovSpec = buildDocCovSpec({
+          openpkgPath: "openpkg.json",
+          openpkg: normalized,
+          packagePath: targetDir
+        });
+        const doccovValidation = validateDocCovSpec(doccovSpec);
+        if (!doccovValidation.ok) {
+          error(chalk10.red("DocCov spec failed schema validation"));
+          for (const err of doccovValidation.errors) {
+            error(chalk10.red(`doccov: ${err.instancePath || "/"} ${err.message}`));
+          }
+          process.exit(1);
+        }
+        steps.next();
+      }
       const format = options.format ?? "json";
-      const outputPath = path7.resolve(options.cwd, options.output);
+      const outputDir = path8.resolve(options.cwd, options.output);
+      fs6.mkdirSync(outputDir, { recursive: true });
       if (format === "api-surface") {
         const apiSurface = renderApiSurface(normalized);
-        writeFileSync4(outputPath, apiSurface);
-        steps.complete(`Generated ${options.output} (API surface)`);
+        const apiSurfacePath = path8.join(outputDir, "api-surface.txt");
+        writeFileSync4(apiSurfacePath, apiSurface);
+        steps.complete(`Generated ${options.output}/ (API surface)`);
       } else {
-        writeFileSync4(outputPath, JSON.stringify(normalized, null, 2));
-        steps.complete(`Generated ${options.output}`);
+        const openpkgPath = path8.join(outputDir, "openpkg.json");
+        writeFileSync4(openpkgPath, JSON.stringify(normalized, null, 2));
+        if (doccovSpec) {
+          const doccovPath = path8.join(outputDir, "doccov.json");
+          writeFileSync4(doccovPath, JSON.stringify(doccovSpec, null, 2));
+          steps.complete(`Generated ${options.output}/`);
+          log(chalk10.gray(`  openpkg.json: ${getArrayLength(normalized.exports)} exports`));
+          log(chalk10.gray(`  doccov.json:  ${doccovSpec.summary.score}% coverage, ${doccovSpec.summary.drift.total} drift issues`));
+        } else {
+          steps.complete(`Generated ${options.output}/openpkg.json`);
+          log(chalk10.gray(`  ${getArrayLength(normalized.exports)} exports`));
+          log(chalk10.gray(`  ${getArrayLength(normalized.types)} types`));
+        }
       }
-      log(chalk8.gray(`  ${getArrayLength(normalized.exports)} exports`));
-      log(chalk8.gray(`  ${getArrayLength(normalized.types)} types`));
       const schemaExtraction = normalized.generation?.analysis?.schemaExtraction;
       if (options.runtime && (!schemaExtraction?.runtimeCount || schemaExtraction.runtimeCount === 0)) {
         const pm = await detectPackageManager(fileSystem);
         const buildCmd = pm.name === "npm" ? "npm run build" : `${pm.name} run build`;
         log("");
-        log(chalk8.yellow("⚠ Runtime extraction requested but no schemas extracted."));
-        log(chalk8.yellow(`  Ensure project is built (${buildCmd}) and dist/ exists.`));
+        log(chalk10.yellow("⚠ Runtime extraction requested but no schemas extracted."));
+        log(chalk10.yellow(`  Ensure project is built (${buildCmd}) and dist/ exists.`));
       }
       if (options.verbose && normalized.generation) {
         const gen = normalized.generation;
         log("");
-        log(chalk8.bold("Generation Info"));
-        log(chalk8.gray(`  Timestamp:        ${gen.timestamp}`));
-        log(chalk8.gray(`  Generator:        ${gen.generator.name}@${gen.generator.version}`));
-        log(chalk8.gray(`  Entry point:      ${gen.analysis.entryPoint}`));
-        log(chalk8.gray(`  Detected via:     ${gen.analysis.entryPointSource}`));
-        log(chalk8.gray(`  Declaration only: ${gen.analysis.isDeclarationOnly ? "yes" : "no"}`));
-        log(chalk8.gray(`  External types:   ${gen.analysis.resolvedExternalTypes ? "resolved" : "skipped"}`));
+        log(chalk10.bold("Generation Info"));
+        log(chalk10.gray(`  Timestamp:        ${gen.timestamp}`));
+        log(chalk10.gray(`  Generator:        ${gen.generator.name}@${gen.generator.version}`));
+        log(chalk10.gray(`  Entry point:      ${gen.analysis.entryPoint}`));
+        log(chalk10.gray(`  Detected via:     ${gen.analysis.entryPointSource}`));
+        log(chalk10.gray(`  Declaration only: ${gen.analysis.isDeclarationOnly ? "yes" : "no"}`));
+        log(chalk10.gray(`  External types:   ${gen.analysis.resolvedExternalTypes ? "resolved" : "skipped"}`));
         if (gen.analysis.maxTypeDepth) {
-          log(chalk8.gray(`  Max type depth:   ${gen.analysis.maxTypeDepth}`));
+          log(chalk10.gray(`  Max type depth:   ${gen.analysis.maxTypeDepth}`));
         }
         if (gen.analysis.schemaExtraction) {
           const se = gen.analysis.schemaExtraction;
-          log(chalk8.gray(`  Schema extraction: ${se.method}`));
+          log(chalk10.gray(`  Schema extraction: ${se.method}`));
           if (se.runtimeCount) {
-            log(chalk8.gray(`  Runtime schemas:   ${se.runtimeCount} (${se.vendors?.join(", ")})`));
+            log(chalk10.gray(`  Runtime schemas:   ${se.runtimeCount} (${se.vendors?.join(", ")})`));
           }
         }
         log("");
-        log(chalk8.bold("Environment"));
-        log(chalk8.gray(`  node_modules:     ${gen.environment.hasNodeModules ? "found" : "not found"}`));
+        log(chalk10.bold("Environment"));
+        log(chalk10.gray(`  node_modules:     ${gen.environment.hasNodeModules ? "found" : "not found"}`));
         if (gen.environment.packageManager) {
-          log(chalk8.gray(`  Package manager:  ${gen.environment.packageManager}`));
+          log(chalk10.gray(`  Package manager:  ${gen.environment.packageManager}`));
         }
         if (gen.environment.isMonorepo) {
-          log(chalk8.gray(`  Monorepo:         yes`));
+          log(chalk10.gray(`  Monorepo:         yes`));
         }
         if (gen.environment.targetPackage) {
-          log(chalk8.gray(`  Target package:   ${gen.environment.targetPackage}`));
+          log(chalk10.gray(`  Target package:   ${gen.environment.targetPackage}`));
         }
         if (gen.issues.length > 0) {
           log("");
-          log(chalk8.bold("Issues"));
+          log(chalk10.bold("Issues"));
           for (const issue of gen.issues) {
-            const prefix = issue.severity === "error" ? chalk8.red(">") : issue.severity === "warning" ? chalk8.yellow(">") : chalk8.cyan(">");
+            const prefix = issue.severity === "error" ? chalk10.red(">") : issue.severity === "warning" ? chalk10.yellow(">") : chalk10.cyan(">");
             log(`${prefix} [${issue.code}] ${issue.message}`);
             if (issue.suggestion) {
-              log(chalk8.gray(`    ${issue.suggestion}`));
+              log(chalk10.gray(`    ${issue.suggestion}`));
             }
           }
         }
       }
       if (options.showDiagnostics && result.diagnostics.length > 0) {
         log("");
-        log(chalk8.bold("Diagnostics"));
+        log(chalk10.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" ? chalk10.red(">") : diagnostic.severity === "warning" ? chalk10.yellow(">") : chalk10.cyan(">");
           log(formatDiagnosticOutput(prefix, diagnostic, targetDir));
         }
       }
     } catch (commandError) {
-      error(chalk8.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      error(chalk10.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
       process.exit(1);
     }
   });
 }
 
 // src/commands/trends.ts
-import * as fs6 from "node:fs";
-import * as path8 from "node:path";
+import * as fs7 from "node:fs";
+import * as path9 from "node:path";
 import {
   formatDelta as formatDelta2,
   getExtendedTrend,
@@ -2396,11 +2582,11 @@ import {
   loadSnapshots,
   pruneByTier,
   pruneHistory,
-  renderSparkline,
   RETENTION_DAYS,
+  renderSparkline,
   saveSnapshot
 } from "@doccov/sdk";
-import chalk9 from "chalk";
+import chalk11 from "chalk";
 function formatDate(timestamp) {
   const date = new Date(timestamp);
   return date.toLocaleDateString("en-US", {
@@ -2413,19 +2599,19 @@ function formatDate(timestamp) {
 }
 function getColorForScore(score) {
   if (score >= 90)
-    return chalk9.green;
+    return chalk11.green;
   if (score >= 70)
-    return chalk9.yellow;
+    return chalk11.yellow;
   if (score >= 50)
-    return chalk9.hex("#FFA500");
-  return chalk9.red;
+    return chalk11.hex("#FFA500");
+  return chalk11.red;
 }
 function formatSnapshot(snapshot) {
   const color = getColorForScore(snapshot.coverageScore);
   const date = formatDate(snapshot.timestamp);
   const version2 = snapshot.version ? ` v${snapshot.version}` : "";
-  const commit = snapshot.commit ? chalk9.gray(` (${snapshot.commit.slice(0, 7)})`) : "";
-  return `${chalk9.gray(date)}  ${color(`${snapshot.coverageScore}%`)}  ${snapshot.documentedExports}/${snapshot.totalExports} exports${version2}${commit}`;
+  const commit = snapshot.commit ? chalk11.gray(` (${snapshot.commit.slice(0, 7)})`) : "";
+  return `${chalk11.gray(date)}  ${color(`${snapshot.coverageScore}%`)}  ${snapshot.documentedExports}/${snapshot.totalExports} exports${version2}${commit}`;
 }
 function formatWeekDate(timestamp) {
   const date = new Date(timestamp);
@@ -2433,55 +2619,55 @@ function formatWeekDate(timestamp) {
 }
 function formatVelocity(velocity) {
   if (velocity > 0)
-    return chalk9.green(`+${velocity}%/day`);
+    return chalk11.green(`+${velocity}%/day`);
   if (velocity < 0)
-    return chalk9.red(`${velocity}%/day`);
-  return chalk9.gray("0%/day");
+    return chalk11.red(`${velocity}%/day`);
+  return chalk11.gray("0%/day");
 }
 function registerTrendsCommand(program) {
   program.command("trends").description("Show coverage trends over time").option("--cwd <dir>", "Working directory", process.cwd()).option("-n, --limit <count>", "Number of snapshots to show", "10").option("--prune <count>", "Prune history to keep only N snapshots").option("--record", "Record current coverage to history").option("--json", "Output as JSON").option("--extended", "Show extended trend analysis (velocity, projections)").option("--tier <tier>", "Retention tier: free (7d), team (30d), pro (90d)", "pro").option("--weekly", "Show weekly summary breakdown").action(async (options) => {
-    const cwd = path8.resolve(options.cwd);
+    const cwd = path9.resolve(options.cwd);
     const tier = options.tier ?? "pro";
     if (options.prune) {
       const keepCount = parseInt(options.prune, 10);
-      if (!isNaN(keepCount)) {
+      if (!Number.isNaN(keepCount)) {
         const deleted = pruneHistory(cwd, keepCount);
-        console.log(chalk9.green(`Pruned ${deleted} old snapshots, kept ${keepCount} most recent`));
+        console.log(chalk11.green(`Pruned ${deleted} old snapshots, kept ${keepCount} most recent`));
       } else {
         const deleted = pruneByTier(cwd, tier);
-        console.log(chalk9.green(`Pruned ${deleted} snapshots older than ${RETENTION_DAYS[tier]} days`));
+        console.log(chalk11.green(`Pruned ${deleted} snapshots older than ${RETENTION_DAYS[tier]} days`));
       }
       return;
     }
     if (options.record) {
-      const specPath = path8.resolve(cwd, "openpkg.json");
-      if (!fs6.existsSync(specPath)) {
-        console.error(chalk9.red("No openpkg.json found. Run `doccov spec` first to generate a spec."));
+      const specPath = path9.resolve(cwd, "openpkg.json");
+      if (!fs7.existsSync(specPath)) {
+        console.error(chalk11.red("No openpkg.json found. Run `doccov spec` first to generate a spec."));
         process.exit(1);
       }
       try {
-        const specContent = fs6.readFileSync(specPath, "utf-8");
+        const specContent = fs7.readFileSync(specPath, "utf-8");
         const spec = JSON.parse(specContent);
         const trend = getTrend(spec, cwd);
         saveSnapshot(trend.current, cwd);
-        console.log(chalk9.green("Recorded coverage snapshot:"));
+        console.log(chalk11.green("Recorded coverage snapshot:"));
         console.log(formatSnapshot(trend.current));
         if (trend.delta !== undefined) {
           const deltaStr = formatDelta2(trend.delta);
-          const deltaColor = trend.delta > 0 ? chalk9.green : trend.delta < 0 ? chalk9.red : chalk9.gray;
-          console.log(chalk9.gray("Change from previous:"), deltaColor(deltaStr));
+          const deltaColor = trend.delta > 0 ? chalk11.green : trend.delta < 0 ? chalk11.red : chalk11.gray;
+          console.log(chalk11.gray("Change from previous:"), deltaColor(deltaStr));
         }
         return;
       } catch (error) {
-        console.error(chalk9.red("Failed to read openpkg.json:"), error instanceof Error ? error.message : error);
+        console.error(chalk11.red("Failed to read openpkg.json:"), error instanceof Error ? error.message : error);
         process.exit(1);
       }
     }
     const snapshots = loadSnapshots(cwd);
     const limit = parseInt(options.limit ?? "10", 10);
     if (snapshots.length === 0) {
-      console.log(chalk9.yellow("No coverage history found."));
-      console.log(chalk9.gray("Run `doccov trends --record` to save the current coverage."));
+      console.log(chalk11.yellow("No coverage history found."));
+      console.log(chalk11.gray("Run `doccov trends --record` to save the current coverage."));
       return;
     }
     if (options.json) {
@@ -2496,28 +2682,28 @@ function registerTrendsCommand(program) {
     }
     const sparklineData = snapshots.slice(0, 10).map((s) => s.coverageScore).reverse();
     const sparkline = renderSparkline(sparklineData);
-    console.log(chalk9.bold("Coverage Trends"));
-    console.log(chalk9.gray(`Package: ${snapshots[0].package}`));
-    console.log(chalk9.gray(`Sparkline: ${sparkline}`));
+    console.log(chalk11.bold("Coverage Trends"));
+    console.log(chalk11.gray(`Package: ${snapshots[0].package}`));
+    console.log(chalk11.gray(`Sparkline: ${sparkline}`));
     console.log("");
     if (snapshots.length >= 2) {
       const oldest = snapshots[snapshots.length - 1];
       const newest = snapshots[0];
       const overallDelta = newest.coverageScore - oldest.coverageScore;
       const deltaStr = formatDelta2(overallDelta);
-      const deltaColor = overallDelta > 0 ? chalk9.green : overallDelta < 0 ? chalk9.red : chalk9.gray;
-      console.log(chalk9.gray("Overall trend:"), deltaColor(deltaStr), chalk9.gray(`(${snapshots.length} snapshots)`));
+      const deltaColor = overallDelta > 0 ? chalk11.green : overallDelta < 0 ? chalk11.red : chalk11.gray;
+      console.log(chalk11.gray("Overall trend:"), deltaColor(deltaStr), chalk11.gray(`(${snapshots.length} snapshots)`));
       console.log("");
     }
     if (options.extended) {
-      const specPath = path8.resolve(cwd, "openpkg.json");
-      if (fs6.existsSync(specPath)) {
+      const specPath = path9.resolve(cwd, "openpkg.json");
+      if (fs7.existsSync(specPath)) {
         try {
-          const specContent = fs6.readFileSync(specPath, "utf-8");
+          const specContent = fs7.readFileSync(specPath, "utf-8");
           const spec = JSON.parse(specContent);
           const extended = getExtendedTrend(spec, cwd, { tier });
-          console.log(chalk9.bold("Extended Analysis"));
-          console.log(chalk9.gray(`Tier: ${tier} (${RETENTION_DAYS[tier]}-day retention)`));
+          console.log(chalk11.bold("Extended Analysis"));
+          console.log(chalk11.gray(`Tier: ${tier} (${RETENTION_DAYS[tier]}-day retention)`));
           console.log("");
           console.log("  Velocity:");
           console.log(`    7-day:   ${formatVelocity(extended.velocity7d)}`);
@@ -2526,55 +2712,55 @@ function registerTrendsCommand(program) {
             console.log(`    90-day:  ${formatVelocity(extended.velocity90d)}`);
           }
           console.log("");
-          const projColor = extended.projected30d >= extended.trend.current.coverageScore ? chalk9.green : chalk9.red;
+          const projColor = extended.projected30d >= extended.trend.current.coverageScore ? chalk11.green : chalk11.red;
           console.log(`  Projected (30d): ${projColor(`${extended.projected30d}%`)}`);
-          console.log(`  All-time high:   ${chalk9.green(`${extended.allTimeHigh}%`)}`);
-          console.log(`  All-time low:    ${chalk9.red(`${extended.allTimeLow}%`)}`);
+          console.log(`  All-time high:   ${chalk11.green(`${extended.allTimeHigh}%`)}`);
+          console.log(`  All-time low:    ${chalk11.red(`${extended.allTimeLow}%`)}`);
           if (extended.dataRange) {
             const startDate = formatWeekDate(extended.dataRange.start);
             const endDate = formatWeekDate(extended.dataRange.end);
-            console.log(chalk9.gray(`  Data range: ${startDate} - ${endDate}`));
+            console.log(chalk11.gray(`  Data range: ${startDate} - ${endDate}`));
           }
           console.log("");
           if (options.weekly && extended.weeklySummaries.length > 0) {
-            console.log(chalk9.bold("Weekly Summary"));
+            console.log(chalk11.bold("Weekly Summary"));
             const weekLimit = Math.min(extended.weeklySummaries.length, 8);
             for (let i = 0;i < weekLimit; i++) {
               const week = extended.weeklySummaries[i];
               const weekStart = formatWeekDate(week.weekStart);
               const weekEnd = formatWeekDate(week.weekEnd);
-              const deltaColor = week.delta > 0 ? chalk9.green : week.delta < 0 ? chalk9.red : chalk9.gray;
+              const deltaColor = week.delta > 0 ? chalk11.green : week.delta < 0 ? chalk11.red : chalk11.gray;
               const deltaStr = week.delta > 0 ? `+${week.delta}%` : `${week.delta}%`;
               console.log(`  ${weekStart} - ${weekEnd}:  ${week.avgCoverage}% avg  ${deltaColor(deltaStr)}  (${week.snapshotCount} snapshots)`);
             }
             if (extended.weeklySummaries.length > weekLimit) {
-              console.log(chalk9.gray(`  ... and ${extended.weeklySummaries.length - weekLimit} more weeks`));
+              console.log(chalk11.gray(`  ... and ${extended.weeklySummaries.length - weekLimit} more weeks`));
             }
             console.log("");
           }
         } catch {
-          console.log(chalk9.yellow("Could not load openpkg.json for extended analysis"));
+          console.log(chalk11.yellow("Could not load openpkg.json for extended analysis"));
           console.log("");
         }
       }
     }
-    console.log(chalk9.bold("History"));
+    console.log(chalk11.bold("History"));
     const displaySnapshots = snapshots.slice(0, limit);
     for (let i = 0;i < displaySnapshots.length; i++) {
       const snapshot = displaySnapshots[i];
-      const prefix = i === 0 ? chalk9.cyan("→") : " ";
+      const prefix = i === 0 ? chalk11.cyan("→") : " ";
       console.log(`${prefix} ${formatSnapshot(snapshot)}`);
     }
     if (snapshots.length > limit) {
-      console.log(chalk9.gray(`  ... and ${snapshots.length - limit} more`));
+      console.log(chalk11.gray(`  ... and ${snapshots.length - limit} more`));
     }
   });
 }
 
 // src/cli.ts
 var __filename2 = fileURLToPath(import.meta.url);
-var __dirname2 = path9.dirname(__filename2);
-var packageJson = JSON.parse(readFileSync5(path9.join(__dirname2, "../package.json"), "utf-8"));
+var __dirname2 = path10.dirname(__filename2);
+var packageJson = JSON.parse(readFileSync5(path10.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);