@doccov/cli 0.8.0 → 0.10.0

package/dist/cli.js

@@ -33,14 +33,24 @@ var docsConfigSchema = z.object({
   include: stringList.optional(),
   exclude: stringList.optional()
 });
-var lintSeveritySchema = z.enum(["error", "warn", "off"]);
+var severitySchema = z.enum(["error", "warn", "off"]);
+var exampleModeSchema = z.enum([
+  "presence",
+  "typecheck",
+  "run"
+]);
+var exampleModesSchema = z.union([
+  exampleModeSchema,
+  z.array(exampleModeSchema),
+  z.string()
+]);
 var checkConfigSchema = z.object({
-  lint: z.boolean().optional(),
-  typecheck: z.boolean().optional(),
-  exec: z.boolean().optional()
+  examples: exampleModesSchema.optional(),
+  minCoverage: z.number().min(0).max(100).optional(),
+  maxDrift: z.number().min(0).max(100).optional()
 });
-var lintConfigSchema = z.object({
-  rules: z.record(lintSeveritySchema).optional()
+var qualityConfigSchema = z.object({
+  rules: z.record(severitySchema).optional()
 });
 var docCovConfigSchema = z.object({
   include: stringList.optional(),
@@ -48,7 +58,7 @@ var docCovConfigSchema = z.object({
   plugins: z.array(z.unknown()).optional(),
   docs: docsConfigSchema.optional(),
   check: checkConfigSchema.optional(),
-  lint: lintConfigSchema.optional()
+  quality: qualityConfigSchema.optional()
 });
 var normalizeList = (value) => {
   if (!value) {
@@ -75,15 +85,15 @@ var normalizeConfig = (input) => {
   let check;
   if (input.check) {
     check = {
-      lint: input.check.lint,
-      typecheck: input.check.typecheck,
-      exec: input.check.exec
+      examples: input.check.examples,
+      minCoverage: input.check.minCoverage,
+      maxDrift: input.check.maxDrift
     };
   }
-  let lint;
-  if (input.lint) {
-    lint = {
-      rules: input.lint.rules
+  let quality;
+  if (input.quality) {
+    quality = {
+      rules: input.quality.rules
     };
   }
   return {
@@ -92,7 +102,7 @@ var normalizeConfig = (input) => {
     plugins: input.plugins,
     docs,
     check,
-    lint
+    quality
   };
 };
 
@@ -169,36 +179,330 @@ ${formatIssues(issues)}`);
 var defineConfig = (config) => config;
 // src/cli.ts
 import { readFileSync as readFileSync4 } from "node:fs";
-import * as path8 from "node:path";
+import * as path9 from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 
 // src/commands/check.ts
-import * as fs from "node:fs";
-import * as path2 from "node:path";
+import * as fs2 from "node:fs";
+import * as path3 from "node:path";
 import {
   applyEdits,
   categorizeDrifts,
   createSourceFile,
   DocCov,
-  detectExampleAssertionFailures,
-  detectExampleRuntimeErrors,
+  enrichSpec,
   findJSDocLocation,
   generateFixesForExport,
-  getDefaultConfig as getLintDefaultConfig,
-  hasNonAssertionComments,
-  lintExport,
+  generateReport,
   mergeFixes,
   NodeFileSystem,
-  parseAssertions,
+  parseExamplesFlag,
   parseJSDocToPatch,
   resolveTarget,
-  runExamplesWithPackage,
   serializeJSDoc,
-  typecheckExamples
+  validateExamples
 } from "@doccov/sdk";
-import chalk from "chalk";
+import {
+  DRIFT_CATEGORIES as DRIFT_CATEGORIES2
+} from "@openpkg-ts/spec";
+import chalk2 from "chalk";
+
+// src/reports/github.ts
+function renderGithubSummary(stats, options = {}) {
+  const coverageScore = options.coverageScore ?? stats.coverageScore;
+  const driftCount = options.driftCount ?? stats.driftCount;
+  const qualityIssues = options.qualityIssues ?? 0;
+  let output = `## Documentation Coverage: ${coverageScore}%
+
+`;
+  output += `| Metric | Value |
+|--------|-------|
+`;
+  output += `| Coverage Score | ${coverageScore}% |
+`;
+  output += `| Total Exports | ${stats.totalExports} |
+`;
+  output += `| Drift Issues | ${driftCount} |
+`;
+  output += `| Quality Issues | ${qualityIssues} |
+`;
+  const status = coverageScore >= 80 ? "✅" : coverageScore >= 50 ? "⚠️" : "❌";
+  output += `
+${status} Coverage ${coverageScore >= 80 ? "passing" : coverageScore >= 50 ? "needs improvement" : "failing"}
+`;
+  return output;
+}
+// src/reports/markdown.ts
+import { DRIFT_CATEGORY_LABELS } from "@openpkg-ts/spec";
+function bar(pct, width = 10) {
+  const filled = Math.round(pct / 100 * width);
+  return "█".repeat(filled) + "░".repeat(width - filled);
+}
+function renderMarkdown(stats, options = {}) {
+  const limit = options.limit ?? 20;
+  const lines = [];
+  lines.push(`# DocCov Report: ${stats.packageName}@${stats.version}`);
+  lines.push("");
+  lines.push(`**Coverage: ${stats.coverageScore}%** \`${bar(stats.coverageScore)}\``);
+  lines.push("");
+  lines.push("| Metric | Value |");
+  lines.push("|--------|-------|");
+  lines.push(`| Exports | ${stats.totalExports} |`);
+  lines.push(`| Fully documented | ${stats.fullyDocumented} |`);
+  lines.push(`| Partially documented | ${stats.partiallyDocumented} |`);
+  lines.push(`| Undocumented | ${stats.undocumented} |`);
+  lines.push(`| Drift issues | ${stats.driftCount} |`);
+  lines.push("");
+  lines.push("## Coverage by Signal");
+  lines.push("");
+  lines.push("| Signal | Coverage |");
+  lines.push("|--------|----------|");
+  for (const [sig, s] of Object.entries(stats.signalCoverage)) {
+    lines.push(`| ${sig} | ${s.pct}% \`${bar(s.pct, 8)}\` |`);
+  }
+  if (stats.byKind.length > 0) {
+    lines.push("");
+    lines.push("## Coverage by Kind");
+    lines.push("");
+    lines.push("| Kind | Count | Avg Score |");
+    lines.push("|------|-------|-----------|");
+    for (const k of stats.byKind) {
+      lines.push(`| ${k.kind} | ${k.count} | ${k.avgScore}% |`);
+    }
+  }
+  const lowExports = stats.exports.filter((e) => e.score < 100).slice(0, limit);
+  if (lowExports.length > 0) {
+    lines.push("");
+    lines.push("## Lowest Coverage Exports");
+    lines.push("");
+    lines.push("| Export | Kind | Score | Missing |");
+    lines.push("|--------|------|-------|---------|");
+    for (const e of lowExports) {
+      lines.push(`| \`${e.name}\` | ${e.kind} | ${e.score}% | ${e.missing.join(", ") || "-"} |`);
+    }
+    const totalLow = stats.exports.filter((e) => e.score < 100).length;
+    if (totalLow > limit) {
+      lines.push(`| ... | | | ${totalLow - limit} more |`);
+    }
+  }
+  if (stats.driftIssues.length > 0) {
+    lines.push("");
+    lines.push("## Drift Issues");
+    lines.push("");
+    const { driftSummary } = stats;
+    const summaryParts = [];
+    if (driftSummary.byCategory.structural > 0) {
+      summaryParts.push(`${driftSummary.byCategory.structural} structural`);
+    }
+    if (driftSummary.byCategory.semantic > 0) {
+      summaryParts.push(`${driftSummary.byCategory.semantic} semantic`);
+    }
+    if (driftSummary.byCategory.example > 0) {
+      summaryParts.push(`${driftSummary.byCategory.example} example`);
+    }
+    const fixableNote = driftSummary.fixable > 0 ? ` (${driftSummary.fixable} auto-fixable)` : "";
+    lines.push(`**${driftSummary.total} issues** (${summaryParts.join(", ")})${fixableNote}`);
+    lines.push("");
+    const categories = ["structural", "semantic", "example"];
+    for (const category of categories) {
+      const issues = stats.driftByCategory[category];
+      if (issues.length === 0)
+        continue;
+      lines.push(`### ${DRIFT_CATEGORY_LABELS[category]}`);
+      lines.push("");
+      lines.push("| Export | Issue |");
+      lines.push("|--------|-------|");
+      for (const d of issues.slice(0, Math.min(limit, 10))) {
+        const hint = d.suggestion ? ` → ${d.suggestion}` : "";
+        lines.push(`| \`${d.exportName}\` | ${d.issue}${hint} |`);
+      }
+      if (issues.length > 10) {
+        lines.push(`| ... | ${issues.length - 10} more ${category} issues |`);
+      }
+      lines.push("");
+    }
+  }
+  lines.push("");
+  lines.push("---");
+  lines.push("*Generated by [DocCov](https://doccov.com)*");
+  return lines.join(`
+`);
+}
 
+// src/reports/html.ts
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function renderHtml(stats, options = {}) {
+  const md = renderMarkdown(stats, options);
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>DocCov Report: ${escapeHtml(stats.packageName)}</title>
+  <style>
+    :root { --bg: #0d1117; --fg: #c9d1d9; --border: #30363d; --accent: #58a6ff; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: var(--bg); color: var(--fg); max-width: 900px; margin: 0 auto; padding: 2rem; line-height: 1.6; }
+    h1, h2 { border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; }
+    table { border-collapse: collapse; width: 100%; margin: 1rem 0; }
+    th, td { border: 1px solid var(--border); padding: 0.5rem 1rem; text-align: left; }
+    th { background: #161b22; }
+    code { background: #161b22; padding: 0.2rem 0.4rem; border-radius: 4px; font-size: 0.9em; }
+    a { color: var(--accent); }
+  </style>
+</head>
+<body>
+<pre style="white-space: pre-wrap; font-family: inherit;">${escapeHtml(md)}</pre>
+</body>
+</html>`;
+}
+// src/reports/stats.ts
+import {
+  DRIFT_CATEGORIES
+} from "@openpkg-ts/spec";
+var FIXABLE_DRIFT_TYPES = new Set([
+  "param-mismatch",
+  "param-type-mismatch",
+  "optionality-mismatch",
+  "return-type-mismatch",
+  "generic-constraint-mismatch",
+  "example-assertion-failed",
+  "deprecated-mismatch",
+  "async-mismatch",
+  "property-type-drift"
+]);
+function computeStats(spec) {
+  const exports = spec.exports ?? [];
+  const signals = {
+    description: { covered: 0, total: 0 },
+    params: { covered: 0, total: 0 },
+    returns: { covered: 0, total: 0 },
+    examples: { covered: 0, total: 0 }
+  };
+  const kindMap = new Map;
+  const driftIssues = [];
+  const driftByCategory = {
+    structural: [],
+    semantic: [],
+    example: []
+  };
+  let fullyDocumented = 0;
+  let partiallyDocumented = 0;
+  let undocumented = 0;
+  for (const exp of exports) {
+    const score = exp.docs?.coverageScore ?? 0;
+    const missing = exp.docs?.missing ?? [];
+    for (const sig of ["description", "params", "returns", "examples"]) {
+      signals[sig].total++;
+      if (!missing.includes(sig))
+        signals[sig].covered++;
+    }
+    const kindEntry = kindMap.get(exp.kind) ?? { count: 0, totalScore: 0 };
+    kindEntry.count++;
+    kindEntry.totalScore += score;
+    kindMap.set(exp.kind, kindEntry);
+    if (score === 100)
+      fullyDocumented++;
+    else if (score > 0)
+      partiallyDocumented++;
+    else
+      undocumented++;
+    for (const d of exp.docs?.drift ?? []) {
+      const item = {
+        exportName: exp.name,
+        type: d.type,
+        issue: d.issue,
+        suggestion: d.suggestion
+      };
+      driftIssues.push(item);
+      const category = DRIFT_CATEGORIES[d.type] ?? "semantic";
+      driftByCategory[category].push(item);
+    }
+  }
+  const signalCoverage = Object.fromEntries(Object.entries(signals).map(([k, v]) => [
+    k,
+    { ...v, pct: v.total ? Math.round(v.covered / v.total * 100) : 0 }
+  ]));
+  const byKind = Array.from(kindMap.entries()).map(([kind, { count, totalScore }]) => ({
+    kind,
+    count,
+    avgScore: Math.round(totalScore / count)
+  })).sort((a, b) => b.count - a.count);
+  const sortedExports = exports.map((e) => ({
+    name: e.name,
+    kind: e.kind,
+    score: e.docs?.coverageScore ?? 0,
+    missing: e.docs?.missing ?? []
+  })).sort((a, b) => a.score - b.score);
+  const driftSummary = {
+    total: driftIssues.length,
+    byCategory: {
+      structural: driftByCategory.structural.length,
+      semantic: driftByCategory.semantic.length,
+      example: driftByCategory.example.length
+    },
+    fixable: driftIssues.filter((d) => FIXABLE_DRIFT_TYPES.has(d.type)).length
+  };
+  const exportsWithDrift = new Set(driftIssues.map((d) => d.exportName)).size;
+  const driftScore = exports.length === 0 ? 0 : Math.round(exportsWithDrift / exports.length * 100);
+  return {
+    packageName: spec.meta.name ?? "unknown",
+    version: spec.meta.version ?? "0.0.0",
+    coverageScore: spec.docs?.coverageScore ?? 0,
+    driftScore,
+    totalExports: exports.length,
+    fullyDocumented,
+    partiallyDocumented,
+    undocumented,
+    driftCount: driftIssues.length,
+    signalCoverage,
+    byKind,
+    exports: sortedExports,
+    driftIssues,
+    driftByCategory,
+    driftSummary
+  };
+}
+// src/reports/writer.ts
+import * as fs from "node:fs";
+import * as path2 from "node:path";
+import { DEFAULT_REPORT_DIR, getReportPath } from "@doccov/sdk";
+import chalk from "chalk";
+function writeReport(options) {
+  const { format, content, outputPath, cwd = process.cwd(), silent = false } = options;
+  const reportPath = outputPath ? path2.resolve(cwd, outputPath) : path2.resolve(cwd, getReportPath(format));
+  const dir = path2.dirname(reportPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(reportPath, content);
+  const relativePath = path2.relative(cwd, reportPath);
+  if (!silent) {
+    console.log(chalk.green(`✓ Wrote ${format} report to ${relativePath}`));
+  }
+  return { path: reportPath, format, relativePath };
+}
+function writeReports(options) {
+  const { format, formatContent, jsonContent, outputPath, cwd = process.cwd() } = options;
+  const results = [];
+  if (format !== "json") {
+    results.push(writeReport({
+      format: "json",
+      content: jsonContent,
+      cwd,
+      silent: true
+    }));
+  }
+  results.push(writeReport({
+    format,
+    content: format === "json" ? jsonContent : formatContent,
+    outputPath,
+    cwd
+  }));
+  return results;
+}
 // src/utils/llm-assertion-parser.ts
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { createOpenAI } from "@ai-sdk/openai";
@@ -296,7 +600,7 @@ function registerCheckCommand(program, dependencies = {}) {
     ...defaultDependencies,
     ...dependencies
   };
-  program.command("check [entry]").description("Fail if documentation coverage falls below a threshold").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("--require-examples", "Require at least one @example for every export").option("--exec", "Execute @example blocks at runtime").option("--no-lint", "Skip lint checks").option("--no-typecheck", "Skip example type checking").option("--ignore-drift", "Do not fail on documentation drift").option("--skip-resolve", "Skip external type resolution from node_modules").option("--fix", "Auto-fix drift and lint issues").option("--write", "Alias for --fix").option("--dry-run", "Preview fixes without writing (requires --fix)").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("--fix", "Auto-fix drift issues").option("--write", "Alias for --fix").option("--dry-run", "Preview fixes without writing (requires --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)").option("--no-cache", "Bypass spec cache and force regeneration").action(async (entry, options) => {
     try {
       const fileSystem = new NodeFileSystem(options.cwd);
       const resolved = await resolveTarget(fileSystem, {
@@ -306,220 +610,93 @@ function registerCheckCommand(program, dependencies = {}) {
       });
       const { targetDir, entryFile, packageInfo, entryPointInfo } = resolved;
       if (packageInfo) {
-        log(chalk.gray(`Found package at ${packageInfo.path}`));
+        log(chalk2.gray(`Found package at ${packageInfo.path}`));
       }
       if (!entry) {
-        log(chalk.gray(`Auto-detected entry point: ${entryPointInfo.path} (from ${entryPointInfo.source})`));
+        log(chalk2.gray(`Auto-detected entry point: ${entryPointInfo.path} (from ${entryPointInfo.source})`));
       }
-      const minCoverage = clampCoverage(options.minCoverage ?? 80);
+      const config = await loadDocCovConfig(targetDir);
+      const minCoverageRaw = options.minCoverage ?? config?.check?.minCoverage;
+      const minCoverage = minCoverageRaw !== undefined ? clampCoverage(minCoverageRaw) : undefined;
+      const maxDriftRaw = options.maxDrift ?? config?.check?.maxDrift;
+      const maxDrift = maxDriftRaw !== undefined ? clampCoverage(maxDriftRaw) : undefined;
       const resolveExternalTypes = !options.skipResolve;
-      process.stdout.write(chalk.cyan(`> Analyzing documentation coverage...
-`));
       let specResult;
-      try {
-        const doccov = createDocCov({ resolveExternalTypes });
-        specResult = await doccov.analyzeFileWithDiagnostics(entryFile);
-        process.stdout.write(chalk.green(`✓ Documentation analysis complete
-`));
-      } catch (analysisError) {
-        process.stdout.write(chalk.red(`✗ Failed to analyze documentation coverage
-`));
-        throw analysisError;
+      const doccov = createDocCov({
+        resolveExternalTypes,
+        maxDepth: options.maxTypeDepth ? parseInt(options.maxTypeDepth, 10) : undefined,
+        useCache: options.cache !== false,
+        cwd: options.cwd
+      });
+      specResult = await doccov.analyzeFileWithDiagnostics(entryFile);
+      if (specResult.fromCache) {
+        log(chalk2.gray("Using cached spec"));
       }
       if (!specResult) {
         throw new Error("Failed to analyze documentation coverage.");
       }
-      const spec = specResult.spec;
-      const warnings = specResult.diagnostics.filter((d) => d.severity === "warning");
-      const infos = specResult.diagnostics.filter((d) => d.severity === "info");
-      if (warnings.length > 0 || infos.length > 0) {
-        log("");
-        for (const diag of warnings) {
-          log(chalk.yellow(`⚠ ${diag.message}`));
-          if (diag.suggestion) {
-            log(chalk.gray(`  ${diag.suggestion}`));
-          }
-        }
-        for (const diag of infos) {
-          log(chalk.cyan(`ℹ ${diag.message}`));
-          if (diag.suggestion) {
-            log(chalk.gray(`  ${diag.suggestion}`));
-          }
-        }
-        log("");
-      }
+      const spec = enrichSpec(specResult.spec);
+      const format = options.format ?? "text";
+      const specWarnings = specResult.diagnostics.filter((d) => d.severity === "warning");
+      const specInfos = specResult.diagnostics.filter((d) => d.severity === "info");
       const shouldFix = options.fix || options.write;
-      const lintViolations = [];
-      if (options.lint !== false) {
-        process.stdout.write(chalk.cyan(`> Running lint checks...
-`));
-        const lintConfig = getLintDefaultConfig();
-        for (const exp of spec.exports ?? []) {
-          const violations = lintExport(exp, undefined, lintConfig);
-          for (const violation of violations) {
-            lintViolations.push({ exportName: exp.name, violation });
-          }
-        }
-        if (lintViolations.length === 0) {
-          process.stdout.write(chalk.green(`✓ No lint issues
-`));
-        } else {
-          const errors = lintViolations.filter((v) => v.violation.severity === "error").length;
-          const warns = lintViolations.filter((v) => v.violation.severity === "warn").length;
-          process.stdout.write(chalk.yellow(`⚠ ${lintViolations.length} lint issue(s) (${errors} error, ${warns} warn)
-`));
+      const violations = [];
+      for (const exp of spec.exports ?? []) {
+        for (const v of exp.docs?.violations ?? []) {
+          violations.push({ exportName: exp.name, violation: v });
         }
       }
+      const validations = parseExamplesFlag(options.examples);
+      let exampleResult;
       const typecheckErrors = [];
-      if (options.typecheck !== false) {
-        const allExamplesForTypecheck = [];
-        for (const exp of spec.exports ?? []) {
-          if (exp.examples && exp.examples.length > 0) {
-            allExamplesForTypecheck.push({
-              exportName: exp.name,
-              examples: exp.examples
-            });
-          }
-        }
-        if (allExamplesForTypecheck.length > 0) {
-          process.stdout.write(chalk.cyan(`> Type-checking examples...
-`));
-          for (const { exportName, examples } of allExamplesForTypecheck) {
-            const result = typecheckExamples(examples, targetDir);
-            for (const err of result.errors) {
-              typecheckErrors.push({ exportName, error: err });
-            }
-          }
-          if (typecheckErrors.length === 0) {
-            process.stdout.write(chalk.green(`✓ All examples type-check
-`));
-          } else {
-            process.stdout.write(chalk.red(`✗ ${typecheckErrors.length} type error(s)
-`));
-          }
-        }
-      }
       const runtimeDrifts = [];
-      if (options.exec) {
-        const allExamples = [];
-        for (const entry2 of spec.exports ?? []) {
-          if (entry2.examples && entry2.examples.length > 0) {
-            allExamples.push({ exportName: entry2.name, examples: entry2.examples });
+      if (validations.length > 0) {
+        exampleResult = await validateExamples(spec.exports ?? [], {
+          validations,
+          packagePath: targetDir,
+          exportNames: (spec.exports ?? []).map((e) => e.name),
+          timeout: 5000,
+          installTimeout: 60000,
+          llmAssertionParser: isLLMAssertionParsingAvailable() ? async (example) => {
+            const result = await parseAssertionsWithLLM(example);
+            return result;
+          } : undefined
+        });
+        if (exampleResult.typecheck) {
+          for (const err of exampleResult.typecheck.errors) {
+            typecheckErrors.push({
+              exportName: err.exportName,
+              error: err.error
+            });
           }
         }
-        if (allExamples.length === 0) {
-          log(chalk.gray("No @example blocks found"));
-        } else {
-          process.stdout.write(chalk.cyan(`> Installing package for examples...
-`));
-          const flatExamples = allExamples.flatMap((e) => e.examples);
-          const packageResult = await runExamplesWithPackage(flatExamples, {
-            packagePath: targetDir,
-            timeout: 5000,
-            installTimeout: 60000,
-            cwd: targetDir
-          });
-          if (!packageResult.installSuccess) {
-            process.stdout.write(chalk.red(`✗ Package install failed: ${packageResult.installError}
-`));
-            log(chalk.yellow("Skipping example execution. Ensure the package is built."));
-          } else {
-            process.stdout.write(chalk.cyan(`> Running @example blocks...
-`));
-            let examplesRun = 0;
-            let examplesFailed = 0;
-            let exampleIndex = 0;
-            for (const { exportName, examples } of allExamples) {
-              const entryResults = new Map;
-              for (let i = 0;i < examples.length; i++) {
-                const result = packageResult.results.get(exampleIndex);
-                if (result) {
-                  entryResults.set(i, result);
-                  examplesRun++;
-                  if (!result.success)
-                    examplesFailed++;
-                }
-                exampleIndex++;
-              }
-              const entry2 = (spec.exports ?? []).find((e) => e.name === exportName);
-              if (entry2) {
-                const runtimeErrorDrifts = detectExampleRuntimeErrors(entry2, entryResults);
-                for (const drift of runtimeErrorDrifts) {
-                  runtimeDrifts.push({
-                    name: entry2.name,
-                    issue: drift.issue,
-                    suggestion: drift.suggestion
-                  });
-                }
-                const assertionDrifts = detectExampleAssertionFailures(entry2, entryResults);
-                for (const drift of assertionDrifts) {
-                  runtimeDrifts.push({
-                    name: entry2.name,
-                    issue: drift.issue,
-                    suggestion: drift.suggestion
-                  });
-                }
-                if (isLLMAssertionParsingAvailable() && entry2.examples) {
-                  for (let exIdx = 0;exIdx < entry2.examples.length; exIdx++) {
-                    const example = entry2.examples[exIdx];
-                    const result = entryResults.get(exIdx);
-                    if (!result?.success || typeof example !== "string")
-                      continue;
-                    const regexAssertions = parseAssertions(example);
-                    if (regexAssertions.length === 0 && hasNonAssertionComments(example)) {
-                      const llmResult = await parseAssertionsWithLLM(example);
-                      if (llmResult?.hasAssertions && llmResult.assertions.length > 0) {
-                        const stdoutLines = result.stdout.split(`
-`).map((l) => l.trim()).filter((l) => l.length > 0);
-                        for (let aIdx = 0;aIdx < llmResult.assertions.length; aIdx++) {
-                          const assertion = llmResult.assertions[aIdx];
-                          const actual = stdoutLines[aIdx];
-                          if (actual === undefined) {
-                            runtimeDrifts.push({
-                              name: entry2.name,
-                              issue: `Assertion expected "${assertion.expected}" but no output was produced`,
-                              suggestion: `Consider using standard syntax: ${assertion.suggestedSyntax}`
-                            });
-                          } else if (assertion.expected.trim() !== actual.trim()) {
-                            runtimeDrifts.push({
-                              name: entry2.name,
-                              issue: `Assertion failed: expected "${assertion.expected}" but got "${actual}"`,
-                              suggestion: `Consider using standard syntax: ${assertion.suggestedSyntax}`
-                            });
-                          }
-                        }
-                      }
-                    }
-                  }
-                }
-              }
-            }
-            if (examplesFailed > 0) {
-              process.stdout.write(chalk.red(`✗ ${examplesFailed}/${examplesRun} example(s) failed
-`));
-            } else {
-              process.stdout.write(chalk.green(`✓ ${examplesRun} example(s) passed
-`));
-            }
+        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"
+            });
           }
         }
       }
       const coverageScore = spec.docs?.coverageScore ?? 0;
-      const failingExports = collectFailingExports(spec.exports ?? [], minCoverage);
-      const missingExamples = options.requireExamples ? failingExports.filter((item) => item.missing?.includes("examples")) : [];
-      let driftExports = [...collectDrift(spec.exports ?? []), ...runtimeDrifts];
+      const allDriftExports = [...collectDrift(spec.exports ?? []), ...runtimeDrifts];
+      let driftExports = validations.length > 0 ? 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(chalk.yellow(`Found ${nonFixable.length} drift issue(s), but none are auto-fixable.`));
+            log(chalk2.yellow(`Found ${nonFixable.length} drift issue(s), but none are auto-fixable.`));
           } else {
             log("");
-            log(chalk.bold(`Found ${fixable.length} fixable issue(s)`));
+            log(chalk2.bold(`Found ${fixable.length} fixable issue(s)`));
             if (nonFixable.length > 0) {
-              log(chalk.gray(`(${nonFixable.length} non-fixable issue(s) skipped)`));
+              log(chalk2.gray(`(${nonFixable.length} non-fixable issue(s) skipped)`));
             }
             log("");
             const groupedDrifts = groupByExport(allDrifts.filter((d) => fixable.includes(d.drift)));
@@ -527,29 +704,30 @@ function registerCheckCommand(program, dependencies = {}) {
             const editsByFile = new Map;
             for (const [exp, drifts] of groupedDrifts) {
               if (!exp.source?.file) {
-                log(chalk.gray(`  Skipping ${exp.name}: no source location`));
+                log(chalk2.gray(`  Skipping ${exp.name}: no source location`));
                 continue;
               }
               if (exp.source.file.endsWith(".d.ts")) {
-                log(chalk.gray(`  Skipping ${exp.name}: declaration file`));
+                log(chalk2.gray(`  Skipping ${exp.name}: declaration file`));
                 continue;
               }
-              const filePath = path2.resolve(targetDir, exp.source.file);
-              if (!fs.existsSync(filePath)) {
-                log(chalk.gray(`  Skipping ${exp.name}: file not found`));
+              const filePath = path3.resolve(targetDir, exp.source.file);
+              if (!fs2.existsSync(filePath)) {
+                log(chalk2.gray(`  Skipping ${exp.name}: file not found`));
                 continue;
               }
               const sourceFile = createSourceFile(filePath);
               const location = findJSDocLocation(sourceFile, exp.name, exp.source.line);
               if (!location) {
-                log(chalk.gray(`  Skipping ${exp.name}: could not find declaration`));
+                log(chalk2.gray(`  Skipping ${exp.name}: could not find declaration`));
                 continue;
               }
               let existingPatch = {};
               if (location.hasExisting && location.existingJSDoc) {
                 existingPatch = parseJSDocToPatch(location.existingJSDoc);
               }
-              const fixes = generateFixesForExport({ ...exp, docs: { ...exp.docs, drift: drifts } }, existingPatch);
+              const expWithDrift = { ...exp, docs: { ...exp.docs, drift: drifts } };
+              const fixes = generateFixesForExport(expWithDrift, existingPatch);
               if (fixes.length === 0)
                 continue;
               for (const drift of drifts) {
@@ -574,39 +752,27 @@ function registerCheckCommand(program, dependencies = {}) {
             }
             if (edits.length > 0) {
               if (options.dryRun) {
-                log(chalk.bold("Dry run - changes that would be made:"));
+                log(chalk2.bold("Dry run - changes that would be made:"));
                 log("");
                 for (const [filePath, fileEdits] of editsByFile) {
-                  const relativePath = path2.relative(targetDir, filePath);
-                  log(chalk.cyan(`  ${relativePath}:`));
+                  const relativePath = path3.relative(targetDir, filePath);
+                  log(chalk2.cyan(`  ${relativePath}:`));
                   for (const { export: exp, edit, fixes } of fileEdits) {
                     const lineInfo = edit.hasExisting ? `lines ${edit.startLine + 1}-${edit.endLine + 1}` : `line ${edit.startLine + 1}`;
-                    log(`    ${chalk.bold(exp.name)} [${lineInfo}]`);
+                    log(`    ${chalk2.bold(exp.name)} [${lineInfo}]`);
                     for (const fix of fixes) {
-                      log(chalk.green(`      + ${fix.description}`));
+                      log(chalk2.green(`      + ${fix.description}`));
                     }
                   }
                   log("");
                 }
-                log(chalk.gray("Run without --dry-run to apply these changes."));
+                log(chalk2.gray("Run without --dry-run to apply these changes."));
               } else {
-                process.stdout.write(chalk.cyan(`> Applying fixes...
-`));
                 const applyResult = await applyEdits(edits);
                 if (applyResult.errors.length > 0) {
-                  process.stdout.write(chalk.yellow(`⚠ Some fixes could not be applied
-`));
                   for (const err of applyResult.errors) {
-                    error(chalk.red(`  ${err.file}: ${err.error}`));
+                    error(chalk2.red(`  ${err.file}: ${err.error}`));
                   }
-                } else {
-                  process.stdout.write(chalk.green(`✓ Applied ${applyResult.editsApplied} fix(es) to ${applyResult.filesModified} file(s)
-`));
-                }
-                log("");
-                for (const [filePath, fileEdits] of editsByFile) {
-                  const relativePath = path2.relative(targetDir, filePath);
-                  log(chalk.green(`  ✓ ${relativePath}: ${fileEdits.length} fix(es)`));
                 }
               }
             }
@@ -616,68 +782,149 @@ function registerCheckCommand(program, dependencies = {}) {
           driftExports = driftExports.filter((d) => !fixedDriftKeys.has(`${d.name}:${d.issue}`));
         }
       }
-      const coverageFailed = coverageScore < minCoverage;
-      const hasMissingExamples = missingExamples.length > 0;
-      const hasDrift = !options.ignoreDrift && driftExports.length > 0;
-      const hasLintErrors = lintViolations.filter((v) => v.violation.severity === "error").length > 0;
+      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,
+              qualityIssues: violations.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 = minCoverage !== undefined && coverageScore < minCoverage;
+        const driftFailed2 = maxDrift !== undefined && driftScore2 > maxDrift;
+        const hasQualityErrors2 = violations.filter((v) => v.violation.severity === "error").length > 0;
+        const hasTypecheckErrors2 = typecheckErrors.length > 0;
+        if (coverageFailed2 || driftFailed2 || hasQualityErrors2 || hasTypecheckErrors2) {
+          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 = minCoverage !== undefined && coverageScore < minCoverage;
+      const driftFailed = maxDrift !== undefined && driftScore > maxDrift;
+      const hasQualityErrors = violations.filter((v) => v.violation.severity === "error").length > 0;
       const hasTypecheckErrors = typecheckErrors.length > 0;
-      if (!coverageFailed && !hasMissingExamples && !hasDrift && !hasLintErrors && !hasTypecheckErrors) {
-        log(chalk.green(`✓ Docs coverage ${coverageScore}% (min ${minCoverage}%)`));
-        if (failingExports.length > 0) {
-          log(chalk.gray("Some exports have partial docs:"));
-          for (const { name, missing } of failingExports.slice(0, 10)) {
-            log(chalk.gray(`  • ${name}: missing ${missing?.join(", ")}`));
+      if (specWarnings.length > 0 || specInfos.length > 0) {
+        log("");
+        for (const diag of specWarnings) {
+          log(chalk2.yellow(`⚠ ${diag.message}`));
+          if (diag.suggestion) {
+            log(chalk2.gray(`  ${diag.suggestion}`));
           }
         }
-        if (options.ignoreDrift && driftExports.length > 0) {
-          log("");
-          log(chalk.yellow(`⚠️ ${driftExports.length} drift issue(s) detected (ignored):`));
-          for (const drift of driftExports.slice(0, 10)) {
-            log(chalk.yellow(`  • ${drift.name}: ${drift.issue}`));
-            if (drift.suggestion) {
-              log(chalk.gray(`    Suggestion: ${drift.suggestion}`));
-            }
+        for (const diag of specInfos) {
+          log(chalk2.cyan(`ℹ ${diag.message}`));
+          if (diag.suggestion) {
+            log(chalk2.gray(`  ${diag.suggestion}`));
           }
         }
-        return;
       }
-      error("");
-      if (coverageFailed) {
-        error(chalk.red(`Docs coverage ${coverageScore}% fell below required ${minCoverage}%.`));
-      }
-      if (hasMissingExamples) {
-        error(chalk.red(`${missingExamples.length} export(s) missing examples (required via --require-examples)`));
+      const pkgName = spec.meta?.name ?? "unknown";
+      const pkgVersion = spec.meta?.version ?? "";
+      const totalExports = spec.exports?.length ?? 0;
+      const errorCount = violations.filter((v) => v.violation.severity === "error").length;
+      const warnCount = violations.filter((v) => v.violation.severity === "warn").length;
+      log("");
+      log(chalk2.bold(`${pkgName}${pkgVersion ? `@${pkgVersion}` : ""}`));
+      log("");
+      log(`  Exports:    ${totalExports}`);
+      if (minCoverage !== undefined) {
+        if (coverageFailed) {
+          log(chalk2.red(`  Coverage:   ✗ ${coverageScore}%`) + chalk2.dim(` (min ${minCoverage}%)`));
+        } else {
+          log(chalk2.green(`  Coverage:   ✓ ${coverageScore}%`) + chalk2.dim(` (min ${minCoverage}%)`));
+        }
+      } else {
+        log(`  Coverage:   ${coverageScore}%`);
       }
-      if (hasLintErrors) {
-        error("");
-        error(chalk.bold("Lint errors:"));
-        for (const { exportName, violation } of lintViolations.filter((v) => v.violation.severity === "error").slice(0, 10)) {
-          error(chalk.red(`  • ${exportName}: ${violation.message}`));
+      if (maxDrift !== undefined) {
+        if (driftFailed) {
+          log(chalk2.red(`  Drift:      ✗ ${driftScore}%`) + chalk2.dim(` (max ${maxDrift}%)`));
+        } else {
+          log(chalk2.green(`  Drift:      ✓ ${driftScore}%`) + chalk2.dim(` (max ${maxDrift}%)`));
         }
+      } else {
+        log(`  Drift:      ${driftScore}%`);
       }
-      if (hasTypecheckErrors) {
-        error("");
-        error(chalk.bold("Type errors in examples:"));
-        for (const { exportName, error: err } of typecheckErrors.slice(0, 10)) {
-          error(chalk.red(`  • ${exportName} @example ${err.exampleIndex + 1}, line ${err.line}: ${err.message}`));
+      if (exampleResult) {
+        const typecheckCount = exampleResult.typecheck?.errors.length ?? 0;
+        if (typecheckCount > 0) {
+          log(`  Examples:   ${typecheckCount} type errors`);
+        } else {
+          log(chalk2.green(`  Examples:   ✓ validated`));
         }
       }
-      if (failingExports.length > 0 || driftExports.length > 0) {
-        error("");
-        error(chalk.bold("Missing documentation details:"));
-        for (const { name, missing } of failingExports.slice(0, 10)) {
-          error(chalk.red(`  • ${name}: missing ${missing?.join(", ")}`));
+      if (errorCount > 0 || warnCount > 0) {
+        const parts = [];
+        if (errorCount > 0)
+          parts.push(`${errorCount} errors`);
+        if (warnCount > 0)
+          parts.push(`${warnCount} warnings`);
+        log(`  Quality:    ${parts.join(", ")}`);
+      }
+      log("");
+      const failed = coverageFailed || driftFailed || hasQualityErrors || hasTypecheckErrors;
+      if (!failed) {
+        const thresholdParts = [];
+        if (minCoverage !== undefined) {
+          thresholdParts.push(`coverage ${coverageScore}% ≥ ${minCoverage}%`);
         }
-        for (const drift of driftExports.slice(0, 10)) {
-          error(chalk.red(`  • ${drift.name}: ${drift.issue}`));
-          if (drift.suggestion) {
-            error(chalk.yellow(`    Suggestion: ${drift.suggestion}`));
-          }
+        if (maxDrift !== undefined) {
+          thresholdParts.push(`drift ${driftScore}% ≤ ${maxDrift}%`);
+        }
+        if (thresholdParts.length > 0) {
+          log(chalk2.green(`✓ Check passed (${thresholdParts.join(", ")})`));
+        } else {
+          log(chalk2.green("✓ Check passed"));
+          log(chalk2.dim("  No thresholds configured. Use --min-coverage or --max-drift to enforce."));
         }
+        return;
       }
+      if (hasQualityErrors) {
+        log(chalk2.red(`✗ ${errorCount} quality errors`));
+      }
+      if (hasTypecheckErrors) {
+        log(chalk2.red(`✗ ${typecheckErrors.length} example type errors`));
+      }
+      log("");
+      log(chalk2.dim("Use --format json or --format markdown for detailed reports"));
       process.exit(1);
     } catch (commandError) {
-      error(chalk.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      error(chalk2.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
       process.exit(1);
     }
   });
@@ -688,20 +935,6 @@ function clampCoverage(value) {
   }
   return Math.min(100, Math.max(0, Math.round(value)));
 }
-function collectFailingExports(exportsList, minCoverage) {
-  const offenders = [];
-  for (const entry of exportsList) {
-    const exportScore = entry.docs?.coverageScore ?? 0;
-    const missing = entry.docs?.missing;
-    if (exportScore < minCoverage || missing && missing.length > 0) {
-      offenders.push({
-        name: entry.name,
-        missing
-      });
-    }
-  }
-  return offenders;
-}
 function collectDrift(exportsList) {
   const drifts = [];
   for (const entry of exportsList) {
@@ -709,11 +942,13 @@ function collectDrift(exportsList) {
     if (!drift || drift.length === 0) {
       continue;
     }
-    for (const signal of drift) {
+    for (const d of drift) {
       drifts.push({
         name: entry.name,
-        issue: signal.issue ?? "Documentation drift detected.",
-        suggestion: signal.suggestion
+        type: d.type,
+        issue: d.issue ?? "Documentation drift detected.",
+        suggestion: d.suggestion,
+        category: DRIFT_CATEGORIES2[d.type]
       });
     }
   }
@@ -721,15 +956,15 @@ function collectDrift(exportsList) {
 }
 
 // src/commands/diff.ts
-import * as fs2 from "node:fs";
-import * as path3 from "node:path";
+import * as fs3 from "node:fs";
+import * as path4 from "node:path";
 import {
   diffSpecWithDocs,
   getDocsImpactSummary,
   hasDocsImpact,
   parseMarkdownFiles
 } from "@doccov/sdk";
-import chalk2 from "chalk";
+import chalk3 from "chalk";
 import { glob } from "glob";
 
 // src/utils/docs-impact-ai.ts
@@ -794,7 +1029,7 @@ Keep it concise and developer-friendly.`
 
 // src/commands/diff.ts
 var defaultDependencies2 = {
-  readFileSync: fs2.readFileSync,
+  readFileSync: fs3.readFileSync,
   log: console.log,
   error: console.error
 };
@@ -838,7 +1073,7 @@ function registerDiffCommand(program, dependencies = {}) {
         const configResult = await loadDocCovConfig(process.cwd());
         if (configResult?.docs?.include) {
           docsPatterns = configResult.docs.include;
-          log(chalk2.gray(`Using docs patterns from config: ${docsPatterns.join(", ")}`));
+          log(chalk3.gray(`Using docs patterns from config: ${docsPatterns.join(", ")}`));
         }
       }
       if (docsPatterns && docsPatterns.length > 0) {
@@ -867,10 +1102,10 @@ function registerDiffCommand(program, dependencies = {}) {
           printTextDiff(diff, log, error);
           if (options.ai && diff.docsImpact && hasDocsImpact(diff)) {
             if (!isAIDocsAnalysisAvailable()) {
-              log(chalk2.yellow(`
+              log(chalk3.yellow(`
 ⚠ AI analysis unavailable (set OPENAI_API_KEY or ANTHROPIC_API_KEY)`));
             } else {
-              log(chalk2.gray(`
+              log(chalk3.gray(`
 Generating AI summary...`));
               const impacts = diff.docsImpact.impactedFiles.flatMap((f) => f.references.map((r) => ({
                 file: f.file,
@@ -881,46 +1116,46 @@ Generating AI summary...`));
               const summary = await generateImpactSummary(impacts);
               if (summary) {
                 log("");
-                log(chalk2.bold("AI Summary"));
-                log(chalk2.cyan(`  ${summary}`));
+                log(chalk3.bold("AI Summary"));
+                log(chalk3.cyan(`  ${summary}`));
               }
             }
           }
           break;
       }
       if (strictOptions.has("regression") && diff.coverageDelta < 0) {
-        error(chalk2.red(`
+        error(chalk3.red(`
 Coverage regressed by ${Math.abs(diff.coverageDelta)}%`));
         process.exitCode = 1;
         return;
       }
       if (strictOptions.has("drift") && diff.driftIntroduced > 0) {
-        error(chalk2.red(`
+        error(chalk3.red(`
 ${diff.driftIntroduced} new drift issue(s) introduced`));
         process.exitCode = 1;
         return;
       }
       if (strictOptions.has("docs-impact") && hasDocsImpact(diff)) {
         const summary = getDocsImpactSummary(diff);
-        error(chalk2.red(`
+        error(chalk3.red(`
 ${summary.totalIssues} docs issue(s) require attention`));
         process.exitCode = 1;
         return;
       }
       if (strictOptions.has("breaking") && diff.breaking.length > 0) {
-        error(chalk2.red(`
+        error(chalk3.red(`
 ${diff.breaking.length} breaking change(s) detected`));
         process.exitCode = 1;
         return;
       }
       if (strictOptions.has("undocumented") && diff.newUndocumented.length > 0) {
-        error(chalk2.red(`
+        error(chalk3.red(`
 ${diff.newUndocumented.length} new undocumented export(s)`));
         process.exitCode = 1;
         return;
       }
     } catch (commandError) {
-      error(chalk2.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      error(chalk3.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
       process.exitCode = 1;
     }
   });
@@ -934,7 +1169,7 @@ async function loadMarkdownFiles(patterns) {
     const matches = await glob(pattern, { nodir: true });
     for (const filePath of matches) {
       try {
-        const content = fs2.readFileSync(filePath, "utf-8");
+        const content = fs3.readFileSync(filePath, "utf-8");
         files.push({ path: filePath, content });
       } catch {}
     }
@@ -942,8 +1177,8 @@ async function loadMarkdownFiles(patterns) {
   return parseMarkdownFiles(files);
 }
 function loadSpec(filePath, readFileSync2) {
-  const resolvedPath = path3.resolve(filePath);
-  if (!fs2.existsSync(resolvedPath)) {
+  const resolvedPath = path4.resolve(filePath);
+  if (!fs3.existsSync(resolvedPath)) {
     throw new Error(`File not found: ${filePath}`);
   }
   try {
@@ -955,7 +1190,7 @@ function loadSpec(filePath, readFileSync2) {
 }
 function printTextDiff(diff, log, _error) {
   log("");
-  log(chalk2.bold("DocCov Diff Report"));
+  log(chalk3.bold("DocCov Diff Report"));
   log("─".repeat(40));
   printCoverage(diff, log);
   printAPIChanges(diff, log);
@@ -965,11 +1200,11 @@ function printTextDiff(diff, log, _error) {
   log("");
 }
 function printCoverage(diff, log) {
-  const coverageColor = diff.coverageDelta > 0 ? chalk2.green : diff.coverageDelta < 0 ? chalk2.red : chalk2.gray;
+  const coverageColor = diff.coverageDelta > 0 ? chalk3.green : diff.coverageDelta < 0 ? chalk3.red : chalk3.gray;
   const coverageSymbol = diff.coverageDelta > 0 ? "↑" : diff.coverageDelta < 0 ? "↓" : "→";
   const deltaStr = diff.coverageDelta > 0 ? `+${diff.coverageDelta}` : String(diff.coverageDelta);
   log("");
-  log(chalk2.bold("Coverage"));
+  log(chalk3.bold("Coverage"));
   log(`  ${diff.oldCoverage}% ${coverageSymbol} ${diff.newCoverage}% ${coverageColor(`(${deltaStr}%)`)}`);
 }
 function printAPIChanges(diff, log) {
@@ -977,31 +1212,31 @@ function printAPIChanges(diff, log) {
   if (!hasChanges)
     return;
   log("");
-  log(chalk2.bold("API Changes"));
+  log(chalk3.bold("API Changes"));
   const membersByClass = groupMemberChangesByClass(diff.memberChanges ?? []);
   const classesWithMembers = new Set(membersByClass.keys());
   for (const [className, changes] of membersByClass) {
     const categorized = diff.categorizedBreaking?.find((c) => c.id === className);
     const isHighSeverity = categorized?.severity === "high";
-    const label = isHighSeverity ? chalk2.red(" [BREAKING]") : chalk2.yellow(" [CHANGED]");
-    log(chalk2.cyan(`  ${className}`) + label);
+    const label = isHighSeverity ? chalk3.red(" [BREAKING]") : chalk3.yellow(" [CHANGED]");
+    log(chalk3.cyan(`  ${className}`) + label);
     const removed = changes.filter((c) => c.changeType === "removed");
     for (const mc of removed) {
-      const suggestion = mc.suggestion ? chalk2.gray(` → ${mc.suggestion}`) : "";
-      log(chalk2.red(`    ✖ ${mc.memberName}()`) + suggestion);
+      const suggestion = mc.suggestion ? chalk3.gray(` → ${mc.suggestion}`) : "";
+      log(chalk3.red(`    ✖ ${mc.memberName}()`) + suggestion);
     }
     const changed = changes.filter((c) => c.changeType === "signature-changed");
     for (const mc of changed) {
-      log(chalk2.yellow(`    ~ ${mc.memberName}() signature changed`));
+      log(chalk3.yellow(`    ~ ${mc.memberName}() signature changed`));
       if (mc.oldSignature && mc.newSignature && mc.oldSignature !== mc.newSignature) {
-        log(chalk2.gray(`        was: ${mc.oldSignature}`));
-        log(chalk2.gray(`        now: ${mc.newSignature}`));
+        log(chalk3.gray(`        was: ${mc.oldSignature}`));
+        log(chalk3.gray(`        now: ${mc.newSignature}`));
       }
     }
     const added = changes.filter((c) => c.changeType === "added");
     if (added.length > 0) {
       const addedNames = added.map((a) => `${a.memberName}()`).join(", ");
-      log(chalk2.green(`    + ${addedNames}`));
+      log(chalk3.green(`    + ${addedNames}`));
     }
   }
   const nonClassBreaking = (diff.categorizedBreaking ?? []).filter((c) => !classesWithMembers.has(c.id));
@@ -1010,43 +1245,43 @@ function printAPIChanges(diff, log) {
   const otherChanges = nonClassBreaking.filter((c) => !["interface", "type", "enum", "function"].includes(c.kind));
   if (functionChanges.length > 0) {
     log("");
-    log(chalk2.red(`  Function Changes (${functionChanges.length}):`));
+    log(chalk3.red(`  Function Changes (${functionChanges.length}):`));
     for (const fc of functionChanges.slice(0, 3)) {
       const reason = fc.reason === "removed" ? "removed" : "signature changed";
-      log(chalk2.red(`    ✖ ${fc.name} (${reason})`));
+      log(chalk3.red(`    ✖ ${fc.name} (${reason})`));
     }
     if (functionChanges.length > 3) {
-      log(chalk2.gray(`    ... and ${functionChanges.length - 3} more`));
+      log(chalk3.gray(`    ... and ${functionChanges.length - 3} more`));
     }
   }
   if (typeChanges.length > 0) {
     log("");
-    log(chalk2.yellow(`  Type/Interface Changes (${typeChanges.length}):`));
+    log(chalk3.yellow(`  Type/Interface Changes (${typeChanges.length}):`));
     const typeNames = typeChanges.slice(0, 5).map((t) => t.name);
-    log(chalk2.yellow(`    ~ ${typeNames.join(", ")}${typeChanges.length > 5 ? ", ..." : ""}`));
+    log(chalk3.yellow(`    ~ ${typeNames.join(", ")}${typeChanges.length > 5 ? ", ..." : ""}`));
   }
   if (otherChanges.length > 0) {
     log("");
-    log(chalk2.gray(`  Other Changes (${otherChanges.length}):`));
+    log(chalk3.gray(`  Other Changes (${otherChanges.length}):`));
     const otherNames = otherChanges.slice(0, 3).map((o) => o.name);
-    log(chalk2.gray(`    ${otherNames.join(", ")}${otherChanges.length > 3 ? ", ..." : ""}`));
+    log(chalk3.gray(`    ${otherNames.join(", ")}${otherChanges.length > 3 ? ", ..." : ""}`));
   }
   if (diff.nonBreaking.length > 0) {
     const undocCount = diff.newUndocumented.length;
-    const undocSuffix = undocCount > 0 ? chalk2.yellow(` (${undocCount} undocumented)`) : "";
+    const undocSuffix = undocCount > 0 ? chalk3.yellow(` (${undocCount} undocumented)`) : "";
     log("");
-    log(chalk2.green(`  New Exports (${diff.nonBreaking.length})`) + undocSuffix);
+    log(chalk3.green(`  New Exports (${diff.nonBreaking.length})`) + undocSuffix);
     const exportNames = diff.nonBreaking.slice(0, 3);
-    log(chalk2.green(`    + ${exportNames.join(", ")}${diff.nonBreaking.length > 3 ? ", ..." : ""}`));
+    log(chalk3.green(`    + ${exportNames.join(", ")}${diff.nonBreaking.length > 3 ? ", ..." : ""}`));
   }
   if (diff.driftIntroduced > 0 || diff.driftResolved > 0) {
     log("");
     const parts = [];
     if (diff.driftIntroduced > 0) {
-      parts.push(chalk2.red(`+${diff.driftIntroduced} drift`));
+      parts.push(chalk3.red(`+${diff.driftIntroduced} drift`));
     }
     if (diff.driftResolved > 0) {
-      parts.push(chalk2.green(`-${diff.driftResolved} resolved`));
+      parts.push(chalk3.green(`-${diff.driftResolved} resolved`));
     }
     log(`  Drift: ${parts.join(", ")}`);
   }
@@ -1056,10 +1291,10 @@ function printDocsRequiringUpdates(diff, log) {
     return;
   const { impactedFiles, missingDocs, stats } = diff.docsImpact;
   log("");
-  log(chalk2.bold("Docs Requiring Updates"));
-  log(chalk2.gray(`  Scanned ${stats.filesScanned} files, ${stats.codeBlocksFound} code blocks`));
+  log(chalk3.bold("Docs Requiring Updates"));
+  log(chalk3.gray(`  Scanned ${stats.filesScanned} files, ${stats.codeBlocksFound} code blocks`));
   if (impactedFiles.length === 0 && missingDocs.length === 0) {
-    log(chalk2.green("  ✓ No updates needed"));
+    log(chalk3.green("  ✓ No updates needed"));
     return;
   }
   const sortedFiles = [...impactedFiles].sort((a, b) => b.references.length - a.references.length);
@@ -1074,49 +1309,49 @@ function printDocsRequiringUpdates(diff, log) {
     }
   }
   for (const file of actionableFiles.slice(0, 6)) {
-    const filename = path3.basename(file.file);
+    const filename = path4.basename(file.file);
     const issueCount = file.references.length;
     log("");
-    log(chalk2.yellow(`  ${filename}`) + chalk2.gray(` (${issueCount} issue${issueCount > 1 ? "s" : ""})`));
+    log(chalk3.yellow(`  ${filename}`) + chalk3.gray(` (${issueCount} issue${issueCount > 1 ? "s" : ""})`));
     const actionableRefs = file.references.filter((r) => !r.isInstantiation);
     for (const ref of actionableRefs.slice(0, 4)) {
       if (ref.memberName) {
         const action = ref.changeType === "method-removed" ? "→" : "~";
         const hint = ref.replacementSuggestion ?? (ref.changeType === "method-changed" ? "signature changed" : "removed");
-        log(chalk2.gray(`    L${ref.line}: ${ref.memberName}() ${action} ${hint}`));
+        log(chalk3.gray(`    L${ref.line}: ${ref.memberName}() ${action} ${hint}`));
       } else {
         const action = ref.changeType === "removed" ? "→" : "~";
         const hint = ref.changeType === "removed" ? "removed" : ref.changeType === "signature-changed" ? "signature changed" : "changed";
-        log(chalk2.gray(`    L${ref.line}: ${ref.exportName} ${action} ${hint}`));
+        log(chalk3.gray(`    L${ref.line}: ${ref.exportName} ${action} ${hint}`));
       }
     }
     if (actionableRefs.length > 4) {
-      log(chalk2.gray(`    ... and ${actionableRefs.length - 4} more`));
+      log(chalk3.gray(`    ... and ${actionableRefs.length - 4} more`));
     }
   }
   if (actionableFiles.length > 6) {
-    log(chalk2.gray(`  ... and ${actionableFiles.length - 6} more files with method changes`));
+    log(chalk3.gray(`  ... and ${actionableFiles.length - 6} more files with method changes`));
   }
   if (instantiationOnlyFiles.length > 0) {
     log("");
-    const fileNames = instantiationOnlyFiles.slice(0, 4).map((f) => path3.basename(f.file));
+    const fileNames = instantiationOnlyFiles.slice(0, 4).map((f) => path4.basename(f.file));
     const suffix = instantiationOnlyFiles.length > 4 ? ", ..." : "";
-    log(chalk2.gray(`  ${instantiationOnlyFiles.length} file(s) with class instantiation to review:`));
-    log(chalk2.gray(`    ${fileNames.join(", ")}${suffix}`));
+    log(chalk3.gray(`  ${instantiationOnlyFiles.length} file(s) with class instantiation to review:`));
+    log(chalk3.gray(`    ${fileNames.join(", ")}${suffix}`));
   }
   const { allUndocumented } = diff.docsImpact;
   if (missingDocs.length > 0) {
     log("");
-    log(chalk2.yellow(`  New exports missing docs (${missingDocs.length}):`));
+    log(chalk3.yellow(`  New exports missing docs (${missingDocs.length}):`));
     const names = missingDocs.slice(0, 4);
-    log(chalk2.gray(`    ${names.join(", ")}${missingDocs.length > 4 ? ", ..." : ""}`));
+    log(chalk3.gray(`    ${names.join(", ")}${missingDocs.length > 4 ? ", ..." : ""}`));
   }
   if (allUndocumented && allUndocumented.length > 0) {
     const existingUndocumented = allUndocumented.filter((name) => !missingDocs.includes(name));
     log("");
-    log(chalk2.gray(`  Total undocumented exports: ${allUndocumented.length}/${stats.totalExports} (${Math.round((1 - allUndocumented.length / stats.totalExports) * 100)}% documented)`));
+    log(chalk3.gray(`  Total undocumented exports: ${allUndocumented.length}/${stats.totalExports} (${Math.round((1 - allUndocumented.length / stats.totalExports) * 100)}% documented)`));
     if (existingUndocumented.length > 0 && existingUndocumented.length <= 10) {
-      log(chalk2.gray(`    ${existingUndocumented.slice(0, 6).join(", ")}${existingUndocumented.length > 6 ? ", ..." : ""}`));
+      log(chalk3.gray(`    ${existingUndocumented.slice(0, 6).join(", ")}${existingUndocumented.length > 6 ? ", ..." : ""}`));
     }
   }
 }
@@ -1267,7 +1502,7 @@ function generateHTMLReport(diff) {
     <h2>Documentation Impact</h2>
     <div class="card">`;
     for (const file of diff.docsImpact.impactedFiles.slice(0, 10)) {
-      const filename = path3.basename(file.file);
+      const filename = path4.basename(file.file);
       html += `
       <div class="file-item">
         <div class="file-name">\uD83D\uDCC4 ${filename} <span class="neutral">(${file.references.length} issue${file.references.length > 1 ? "s" : ""})</span></div>
@@ -1301,278 +1536,39 @@ function generateHTMLReport(diff) {
       <ul>`;
       for (const name of diff.newUndocumented.slice(0, 10)) {
         html += `
-        <li><code>${name}</code></li>`;
-      }
-      if (diff.newUndocumented.length > 10) {
-        html += `
-        <li class="neutral">... and ${diff.newUndocumented.length - 10} more</li>`;
-      }
-      html += `
-      </ul>`;
-    }
-    if (diff.docsImpact?.stats) {
-      const { stats, allUndocumented } = diff.docsImpact;
-      const docPercent = Math.round((1 - (allUndocumented?.length ?? 0) / stats.totalExports) * 100);
-      html += `
-      <div class="metric" style="margin-top: 1rem; border-top: 1px solid #30363d; padding-top: 1rem;">
-        <span class="metric-label">Total Documentation Coverage</span>
-        <span class="metric-value ${docPercent >= 80 ? "positive" : docPercent >= 50 ? "warning" : "negative"}">${stats.documentedExports}/${stats.totalExports} (${docPercent}%)</span>
-      </div>`;
-    }
-    html += `
-    </div>`;
-  }
-  html += `
-  </div>
-</body>
-</html>`;
-  return html;
-}
-
-// src/commands/generate.ts
-import * as fs3 from "node:fs";
-import * as path4 from "node:path";
-import {
-  DocCov as DocCov2,
-  NodeFileSystem as NodeFileSystem2,
-  resolveTarget as resolveTarget2
-} from "@doccov/sdk";
-import { normalize, validateSpec } from "@openpkg-ts/spec";
-import chalk4 from "chalk";
-
-// src/reports/markdown.ts
-function bar(pct, width = 10) {
-  const filled = Math.round(pct / 100 * width);
-  return "█".repeat(filled) + "░".repeat(width - filled);
-}
-function renderMarkdown(stats, options = {}) {
-  const limit = options.limit ?? 20;
-  const lines = [];
-  lines.push(`# DocCov Report: ${stats.packageName}@${stats.version}`);
-  lines.push("");
-  lines.push(`**Coverage: ${stats.coverageScore}%** \`${bar(stats.coverageScore)}\``);
-  lines.push("");
-  lines.push("| Metric | Value |");
-  lines.push("|--------|-------|");
-  lines.push(`| Exports | ${stats.totalExports} |`);
-  lines.push(`| Fully documented | ${stats.fullyDocumented} |`);
-  lines.push(`| Partially documented | ${stats.partiallyDocumented} |`);
-  lines.push(`| Undocumented | ${stats.undocumented} |`);
-  lines.push(`| Drift issues | ${stats.driftCount} |`);
-  lines.push("");
-  lines.push("## Coverage by Signal");
-  lines.push("");
-  lines.push("| Signal | Coverage |");
-  lines.push("|--------|----------|");
-  for (const [sig, s] of Object.entries(stats.signalCoverage)) {
-    lines.push(`| ${sig} | ${s.pct}% \`${bar(s.pct, 8)}\` |`);
-  }
-  if (stats.byKind.length > 0) {
-    lines.push("");
-    lines.push("## Coverage by Kind");
-    lines.push("");
-    lines.push("| Kind | Count | Avg Score |");
-    lines.push("|------|-------|-----------|");
-    for (const k of stats.byKind) {
-      lines.push(`| ${k.kind} | ${k.count} | ${k.avgScore}% |`);
-    }
-  }
-  const lowExports = stats.exports.filter((e) => e.score < 100).slice(0, limit);
-  if (lowExports.length > 0) {
-    lines.push("");
-    lines.push("## Lowest Coverage Exports");
-    lines.push("");
-    lines.push("| Export | Kind | Score | Missing |");
-    lines.push("|--------|------|-------|---------|");
-    for (const e of lowExports) {
-      lines.push(`| \`${e.name}\` | ${e.kind} | ${e.score}% | ${e.missing.join(", ") || "-"} |`);
-    }
-    const totalLow = stats.exports.filter((e) => e.score < 100).length;
-    if (totalLow > limit) {
-      lines.push(`| ... | | | ${totalLow - limit} more |`);
-    }
-  }
-  if (stats.driftIssues.length > 0) {
-    lines.push("");
-    lines.push("## Drift Issues");
-    lines.push("");
-    lines.push("| Export | Type | Issue |");
-    lines.push("|--------|------|-------|");
-    for (const d of stats.driftIssues.slice(0, limit)) {
-      const hint = d.suggestion ? ` → ${d.suggestion}` : "";
-      lines.push(`| \`${d.exportName}\` | ${d.type} | ${d.issue}${hint} |`);
-    }
-  }
-  lines.push("");
-  lines.push("---");
-  lines.push("*Generated by [DocCov](https://doccov.com)*");
-  return lines.join(`
-`);
-}
-
-// src/reports/html.ts
-function escapeHtml(s) {
-  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}
-function renderHtml(stats, options = {}) {
-  const md = renderMarkdown(stats, options);
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>DocCov Report: ${escapeHtml(stats.packageName)}</title>
-  <style>
-    :root { --bg: #0d1117; --fg: #c9d1d9; --border: #30363d; --accent: #58a6ff; }
-    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: var(--bg); color: var(--fg); max-width: 900px; margin: 0 auto; padding: 2rem; line-height: 1.6; }
-    h1, h2 { border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; }
-    table { border-collapse: collapse; width: 100%; margin: 1rem 0; }
-    th, td { border: 1px solid var(--border); padding: 0.5rem 1rem; text-align: left; }
-    th { background: #161b22; }
-    code { background: #161b22; padding: 0.2rem 0.4rem; border-radius: 4px; font-size: 0.9em; }
-    a { color: var(--accent); }
-  </style>
-</head>
-<body>
-<pre style="white-space: pre-wrap; font-family: inherit;">${escapeHtml(md)}</pre>
-</body>
-</html>`;
-}
-// src/reports/stats.ts
-function computeStats(spec) {
-  const exports = spec.exports ?? [];
-  const signals = {
-    description: { covered: 0, total: 0 },
-    params: { covered: 0, total: 0 },
-    returns: { covered: 0, total: 0 },
-    examples: { covered: 0, total: 0 }
-  };
-  const kindMap = new Map;
-  const driftIssues = [];
-  let fullyDocumented = 0;
-  let partiallyDocumented = 0;
-  let undocumented = 0;
-  for (const exp of exports) {
-    const score = exp.docs?.coverageScore ?? 0;
-    const missing = exp.docs?.missing ?? [];
-    for (const sig of ["description", "params", "returns", "examples"]) {
-      signals[sig].total++;
-      if (!missing.includes(sig))
-        signals[sig].covered++;
-    }
-    const kindEntry = kindMap.get(exp.kind) ?? { count: 0, totalScore: 0 };
-    kindEntry.count++;
-    kindEntry.totalScore += score;
-    kindMap.set(exp.kind, kindEntry);
-    if (score === 100)
-      fullyDocumented++;
-    else if (score > 0)
-      partiallyDocumented++;
-    else
-      undocumented++;
-    for (const d of exp.docs?.drift ?? []) {
-      driftIssues.push({
-        exportName: exp.name,
-        type: d.type,
-        issue: d.issue,
-        suggestion: d.suggestion
-      });
-    }
-  }
-  const signalCoverage = Object.fromEntries(Object.entries(signals).map(([k, v]) => [
-    k,
-    { ...v, pct: v.total ? Math.round(v.covered / v.total * 100) : 0 }
-  ]));
-  const byKind = Array.from(kindMap.entries()).map(([kind, { count, totalScore }]) => ({
-    kind,
-    count,
-    avgScore: Math.round(totalScore / count)
-  })).sort((a, b) => b.count - a.count);
-  const sortedExports = exports.map((e) => ({
-    name: e.name,
-    kind: e.kind,
-    score: e.docs?.coverageScore ?? 0,
-    missing: e.docs?.missing ?? []
-  })).sort((a, b) => a.score - b.score);
-  return {
-    packageName: spec.meta.name ?? "unknown",
-    version: spec.meta.version ?? "0.0.0",
-    coverageScore: spec.docs?.coverageScore ?? 0,
-    totalExports: exports.length,
-    fullyDocumented,
-    partiallyDocumented,
-    undocumented,
-    driftCount: driftIssues.length,
-    signalCoverage,
-    byKind,
-    exports: sortedExports,
-    driftIssues
-  };
-}
-// src/utils/filter-options.ts
-import { mergeFilters, parseListFlag } from "@doccov/sdk";
-import chalk3 from "chalk";
-var formatList = (label, values) => `${label}: ${values.map((value) => chalk3.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));
-  }
-  const resolved = mergeFilters(config, cliOptions);
-  if (!resolved.include && !resolved.exclude) {
-    return { messages };
+        <li><code>${name}</code></li>`;
+      }
+      if (diff.newUndocumented.length > 10) {
+        html += `
+        <li class="neutral">... and ${diff.newUndocumented.length - 10} more</li>`;
+      }
+      html += `
+      </ul>`;
+    }
+    if (diff.docsImpact?.stats) {
+      const { stats, allUndocumented } = diff.docsImpact;
+      const docPercent = Math.round((1 - (allUndocumented?.length ?? 0) / stats.totalExports) * 100);
+      html += `
+      <div class="metric" style="margin-top: 1rem; border-top: 1px solid #30363d; padding-top: 1rem;">
+        <span class="metric-label">Total Documentation Coverage</span>
+        <span class="metric-value ${docPercent >= 80 ? "positive" : docPercent >= 50 ? "warning" : "negative"}">${stats.documentedExports}/${stats.totalExports} (${docPercent}%)</span>
+      </div>`;
+    }
+    html += `
+    </div>`;
   }
-  const source = resolved.source === "override" ? "cli" : resolved.source;
-  return {
-    include: resolved.include,
-    exclude: resolved.exclude,
-    source,
-    messages
-  };
-};
-
-// src/commands/generate.ts
-var defaultDependencies3 = {
-  createDocCov: (options) => new DocCov2(options),
-  writeFileSync: fs3.writeFileSync,
-  log: console.log,
-  error: console.error
-};
-function getArrayLength(value) {
-  return Array.isArray(value) ? value.length : 0;
-}
-function stripDocsFields(spec) {
-  const { docs: _rootDocs, ...rest } = spec;
-  return {
-    ...rest,
-    exports: spec.exports?.map((exp) => {
-      const { docs: _expDocs, ...expRest } = exp;
-      return expRest;
-    })
-  };
-}
-function formatDiagnosticOutput(prefix, diagnostic, baseDir) {
-  const location = diagnostic.location;
-  const relativePath = location?.file ? path4.relative(baseDir, location.file) || location.file : undefined;
-  const locationText = location && relativePath ? chalk4.gray(`${relativePath}:${location.line ?? 1}:${location.column ?? 1}`) : null;
-  const locationPrefix = locationText ? `${locationText} ` : "";
-  return `${prefix} ${locationPrefix}${diagnostic.message}`;
+  html += `
+  </div>
+</body>
+</html>`;
+  return html;
 }
-function registerGenerateCommand(program, dependencies = {}) {
-  const { createDocCov, writeFileSync: writeFileSync2, log, error } = {
-    ...defaultDependencies3,
-    ...dependencies
-  };
-  program.command("generate [entry]").description("Generate OpenPkg specification for documentation coverage analysis").option("-o, --output <file>", "Output file", "openpkg.json").option("--format <format>", "Output format: json, markdown, html", "json").option("-p, --package <name>", "Target package name (for monorepos)").option("--cwd <dir>", "Working directory", process.cwd()).option("--skip-resolve", "Skip external type resolution from node_modules").option("--include <ids>", "Filter exports by identifier (comma-separated or repeated)").option("--exclude <ids>", "Exclude exports by identifier (comma-separated or repeated)").option("--show-diagnostics", "Print TypeScript diagnostics from analysis").option("--no-docs", "Omit docs coverage fields from output (pure structural spec)").option("--limit <n>", "Max exports to show in report tables (for markdown/html)", "20").option("-y, --yes", "Skip all prompts and use defaults").action(async (entry, options) => {
+
+// src/commands/info.ts
+import { DocCov as DocCov2, enrichSpec as enrichSpec2, NodeFileSystem as NodeFileSystem2, resolveTarget as resolveTarget2 } from "@doccov/sdk";
+import chalk4 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 {
       const fileSystem = new NodeFileSystem2(options.cwd);
       const resolved = await resolveTarget2(fileSystem, {
@@ -1580,94 +1576,26 @@ function registerGenerateCommand(program, dependencies = {}) {
         package: options.package,
         entry
       });
-      const { targetDir, entryFile, packageInfo, entryPointInfo } = resolved;
-      if (packageInfo) {
-        log(chalk4.gray(`Found package at ${packageInfo.path}`));
-      }
-      if (!entry) {
-        log(chalk4.gray(`Auto-detected entry point: ${entryPointInfo.path} (from ${entryPointInfo.source})`));
-      }
+      const { entryFile } = resolved;
       const resolveExternalTypes = !options.skipResolve;
-      const cliFilters = {
-        include: parseListFlag(options.include),
-        exclude: parseListFlag(options.exclude)
-      };
-      let config = null;
-      try {
-        config = await loadDocCovConfig(targetDir);
-        if (config?.filePath) {
-          log(chalk4.gray(`Loaded configuration from ${path4.relative(targetDir, config.filePath)}`));
-        }
-      } catch (configError) {
-        error(chalk4.red("Failed to load DocCov config:"), configError instanceof Error ? configError.message : configError);
-        process.exit(1);
-      }
-      const resolvedFilters = mergeFilterOptions(config, cliFilters);
-      for (const message of resolvedFilters.messages) {
-        log(chalk4.gray(`• ${message}`));
-      }
-      process.stdout.write(chalk4.cyan(`> Generating OpenPkg spec...
-`));
-      let result;
-      try {
-        const doccov = createDocCov({
-          resolveExternalTypes
-        });
-        const analyzeOptions = resolvedFilters.include || resolvedFilters.exclude ? {
-          filters: {
-            include: resolvedFilters.include,
-            exclude: resolvedFilters.exclude
-          }
-        } : {};
-        result = await doccov.analyzeFileWithDiagnostics(entryFile, analyzeOptions);
-        process.stdout.write(chalk4.green(`✓ Generated OpenPkg spec
-`));
-      } catch (generationError) {
-        process.stdout.write(chalk4.red(`✗ Failed to generate spec
-`));
-        throw generationError;
-      }
-      if (!result) {
-        throw new Error("Failed to produce an OpenPkg spec.");
-      }
-      let normalized = normalize(result.spec);
-      if (options.docs === false) {
-        normalized = stripDocsFields(normalized);
-      }
-      const validation = validateSpec(normalized);
-      if (!validation.ok) {
-        error(chalk4.red("Spec failed schema validation"));
-        for (const err of validation.errors) {
-          error(chalk4.red(`schema: ${err.instancePath || "/"} ${err.message}`));
-        }
-        process.exit(1);
-      }
-      const format = options.format ?? "json";
-      const outputPath = path4.resolve(process.cwd(), options.output);
-      if (format === "markdown" || format === "html") {
-        const stats = computeStats(normalized);
-        const limit = parseInt(options.limit, 10) || 20;
-        const reportOutput = format === "html" ? renderHtml(stats, { limit }) : renderMarkdown(stats, { limit });
-        writeFileSync2(outputPath, reportOutput);
-        log(chalk4.green(`✓ Generated ${format} report: ${options.output}`));
-        log(chalk4.gray(`  Coverage: ${stats.coverageScore}%`));
-        log(chalk4.gray(`  ${stats.totalExports} exports, ${stats.driftCount} drift issues`));
-      } else {
-        writeFileSync2(outputPath, JSON.stringify(normalized, null, 2));
-        log(chalk4.green(`✓ Generated ${options.output}`));
-        log(chalk4.gray(`  ${getArrayLength(normalized.exports)} exports`));
-        log(chalk4.gray(`  ${getArrayLength(normalized.types)} types`));
-      }
-      if (options.showDiagnostics && result.diagnostics.length > 0) {
-        log("");
-        log(chalk4.bold("Diagnostics"));
-        for (const diagnostic of result.diagnostics) {
-          const prefix = diagnostic.severity === "error" ? chalk4.red("✖") : diagnostic.severity === "warning" ? chalk4.yellow("⚠") : chalk4.cyan("ℹ");
-          log(formatDiagnosticOutput(prefix, diagnostic, targetDir));
-        }
+      const doccov = new DocCov2({
+        resolveExternalTypes
+      });
+      const specResult = await doccov.analyzeFileWithDiagnostics(entryFile);
+      if (!specResult) {
+        throw new Error("Failed to analyze documentation coverage.");
       }
-    } catch (commandError) {
-      error(chalk4.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      const spec = enrichSpec2(specResult.spec);
+      const stats = computeStats(spec);
+      console.log("");
+      console.log(chalk4.bold(`${stats.packageName}@${stats.version}`));
+      console.log("");
+      console.log(`  Exports:    ${chalk4.bold(stats.totalExports.toString())}`);
+      console.log(`  Coverage:   ${chalk4.bold(`${stats.coverageScore}%`)}`);
+      console.log(`  Drift:      ${chalk4.bold(`${stats.driftScore}%`)}`);
+      console.log("");
+    } catch (err) {
+      console.error(chalk4.red("Error:"), err instanceof Error ? err.message : err);
       process.exit(1);
     }
   });
@@ -1677,7 +1605,7 @@ function registerGenerateCommand(program, dependencies = {}) {
 import * as fs4 from "node:fs";
 import * as path5 from "node:path";
 import chalk5 from "chalk";
-var defaultDependencies4 = {
+var defaultDependencies3 = {
   fileExists: fs4.existsSync,
   writeFileSync: fs4.writeFileSync,
   readFileSync: fs4.readFileSync,
@@ -1686,7 +1614,7 @@ var defaultDependencies4 = {
 };
 function registerInitCommand(program, dependencies = {}) {
   const { fileExists: fileExists2, writeFileSync: writeFileSync3, readFileSync: readFileSync3, log, error } = {
-    ...defaultDependencies4,
+    ...defaultDependencies3,
     ...dependencies
   };
   program.command("init").description("Create a DocCov configuration file").option("--cwd <dir>", "Working directory", process.cwd()).option("--format <format>", "Config format: auto, mjs, js, cjs", "auto").action((options) => {
@@ -1779,14 +1707,40 @@ var resolveFormat = (format, packageType) => {
   return format;
 };
 var buildTemplate = (format) => {
+  const configBody = `{
+  // Filter which exports to analyze
+  // include: ['MyClass', 'myFunction'],
+  // exclude: ['internal*'],
+
+  // Check command thresholds
+  check: {
+    // Minimum documentation coverage percentage (0-100)
+    // minCoverage: 80,
+
+    // Maximum drift percentage allowed (0-100)
+    // maxDrift: 20,
+
+    // Example validation: 'presence' | 'typecheck' | 'run'
+    // examples: 'typecheck',
+  },
+
+  // Quality rule severities: 'error' | 'warn' | 'off'
+  quality: {
+    rules: {
+      // 'has-description': 'warn',
+      // 'has-params': 'off',
+      // 'has-returns': 'off',
+      // 'has-examples': 'off',
+      // 'no-empty-returns': 'warn',
+      // 'consistent-param-style': 'off',
+    },
+  },
+}`;
   if (format === "cjs") {
     return [
       "const { defineConfig } = require('@doccov/cli/config');",
       "",
-      "module.exports = defineConfig({",
-      "  include: [],",
-      "  exclude: [],",
-      "});",
+      `module.exports = defineConfig(${configBody});`,
       ""
     ].join(`
 `);
@@ -1794,10 +1748,7 @@ var buildTemplate = (format) => {
   return [
     "import { defineConfig } from '@doccov/cli/config';",
     "",
-    "export default defineConfig({",
-    "  include: [],",
-    "  exclude: [],",
-    "});",
+    `export default defineConfig(${configBody});`,
     ""
   ].join(`
 `);
@@ -1809,9 +1760,9 @@ import * as fsPromises from "node:fs/promises";
 import * as os from "node:os";
 import * as path7 from "node:path";
 import {
-  DocCov as DocCov3,
   buildCloneUrl,
   buildDisplayUrl,
+  DocCov as DocCov3,
   detectBuildInfo,
   detectEntryPoint,
   detectMonorepo,
@@ -1823,6 +1774,10 @@ import {
   NodeFileSystem as NodeFileSystem3,
   parseGitHubUrl
 } from "@doccov/sdk";
+import {
+  DRIFT_CATEGORIES as DRIFT_CATEGORIES3,
+  DRIFT_CATEGORY_LABELS as DRIFT_CATEGORY_LABELS2
+} from "@openpkg-ts/spec";
 import chalk6 from "chalk";
 import { simpleGit } from "simple-git";
 
@@ -1919,14 +1874,14 @@ async function generateBuildPlan(repoDir) {
 }
 
 // src/commands/scan.ts
-var defaultDependencies5 = {
+var defaultDependencies4 = {
   createDocCov: (options) => new DocCov3(options),
   log: console.log,
   error: console.error
 };
 function registerScanCommand(program, dependencies = {}) {
   const { createDocCov, log, error } = {
-    ...defaultDependencies5,
+    ...defaultDependencies4,
     ...dependencies
   };
   program.command("scan <url>").description("Analyze docs coverage for any public GitHub repository").option("--ref <branch>", "Branch or tag to analyze").option("--package <name>", "Target package in monorepo").option("--output <format>", "Output format: text or json", "text").option("--no-cleanup", "Keep cloned repo (for debugging)").option("--skip-install", "Skip dependency installation (faster, but may limit type resolution)").option("--skip-resolve", "Skip external type resolution from node_modules").option("--save-spec <path>", "Save full OpenPkg spec to file").action(async (url, options) => {
@@ -2206,6 +2161,44 @@ function registerScanCommand(program, dependencies = {}) {
     }
   });
 }
+function categorizeDriftIssues(drift) {
+  const byCategory = {
+    structural: [],
+    semantic: [],
+    example: []
+  };
+  for (const d of drift) {
+    const category = DRIFT_CATEGORIES3[d.type] ?? "semantic";
+    byCategory[category].push(d);
+  }
+  return {
+    summary: {
+      total: drift.length,
+      byCategory: {
+        structural: byCategory.structural.length,
+        semantic: byCategory.semantic.length,
+        example: byCategory.example.length
+      }
+    },
+    byCategory
+  };
+}
+function formatDriftSummary(summary) {
+  if (summary.total === 0) {
+    return "No drift detected";
+  }
+  const parts = [];
+  if (summary.byCategory.structural > 0) {
+    parts.push(`${summary.byCategory.structural} structural`);
+  }
+  if (summary.byCategory.semantic > 0) {
+    parts.push(`${summary.byCategory.semantic} semantic`);
+  }
+  if (summary.byCategory.example > 0) {
+    parts.push(`${summary.byCategory.example} example`);
+  }
+  return `${summary.total} issues (${parts.join(", ")})`;
+}
 function printTextResult(result, log) {
   log("");
   log(chalk6.bold("DocCov Scan Results"));
@@ -2222,7 +2215,9 @@ function printTextResult(result, log) {
   log(`  ${result.exportCount} exports`);
   log(`  ${result.typeCount} types`);
   log(`  ${result.undocumented.length} undocumented`);
-  log(`  ${result.driftCount} drift issues`);
+  const categorized = categorizeDriftIssues(result.drift);
+  const driftColor = result.driftCount > 0 ? chalk6.yellow : chalk6.green;
+  log(`  ${driftColor(formatDriftSummary(categorized.summary))}`);
   if (result.undocumented.length > 0) {
     log("");
     log(chalk6.bold("Undocumented Exports"));
@@ -2236,24 +2231,189 @@ function printTextResult(result, log) {
   if (result.drift.length > 0) {
     log("");
     log(chalk6.bold("Drift Issues"));
-    for (const d of result.drift.slice(0, 5)) {
-      log(chalk6.red(`  • ${d.export}: ${d.issue}`));
-    }
-    if (result.drift.length > 5) {
-      log(chalk6.gray(`  ... and ${result.drift.length - 5} more`));
+    const categories = ["structural", "semantic", "example"];
+    for (const category of categories) {
+      const issues = categorized.byCategory[category];
+      if (issues.length === 0)
+        continue;
+      const label = DRIFT_CATEGORY_LABELS2[category];
+      log("");
+      log(chalk6.dim(`  ${label} (${issues.length})`));
+      for (const d of issues.slice(0, 3)) {
+        log(chalk6.red(`    • ${d.export}: ${d.issue}`));
+      }
+      if (issues.length > 3) {
+        log(chalk6.gray(`    ... and ${issues.length - 3} more`));
+      }
     }
   }
   log("");
 }
 
+// src/commands/spec.ts
+import * as fs7 from "node:fs";
+import * as path8 from "node:path";
+import { DocCov as DocCov4, NodeFileSystem as NodeFileSystem4, resolveTarget as resolveTarget3 } from "@doccov/sdk";
+import { normalize, validateSpec } from "@openpkg-ts/spec";
+import chalk8 from "chalk";
+
+// src/utils/filter-options.ts
+import { mergeFilters, parseListFlag } from "@doccov/sdk";
+import chalk7 from "chalk";
+var formatList = (label, values) => `${label}: ${values.map((value) => chalk7.cyan(value)).join(", ")}`;
+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));
+  }
+  const resolved = mergeFilters(config, cliOptions);
+  if (!resolved.include && !resolved.exclude) {
+    return { messages };
+  }
+  const source = resolved.source === "override" ? "cli" : resolved.source;
+  return {
+    include: resolved.include,
+    exclude: resolved.exclude,
+    source,
+    messages
+  };
+};
+
+// src/commands/spec.ts
+var defaultDependencies5 = {
+  createDocCov: (options) => new DocCov4(options),
+  writeFileSync: fs7.writeFileSync,
+  log: console.log,
+  error: console.error
+};
+function getArrayLength(value) {
+  return Array.isArray(value) ? value.length : 0;
+}
+function formatDiagnosticOutput(prefix, diagnostic, baseDir) {
+  const location = diagnostic.location;
+  const relativePath = location?.file ? path8.relative(baseDir, location.file) || location.file : undefined;
+  const locationText = location && relativePath ? chalk8.gray(`${relativePath}:${location.line ?? 1}:${location.column ?? 1}`) : null;
+  const locationPrefix = locationText ? `${locationText} ` : "";
+  return `${prefix} ${locationPrefix}${diagnostic.message}`;
+}
+function registerSpecCommand(program, dependencies = {}) {
+  const { createDocCov, writeFileSync: writeFileSync5, log, error } = {
+    ...defaultDependencies5,
+    ...dependencies
+  };
+  program.command("spec [entry]").description("Generate OpenPkg specification (JSON)").option("--cwd <dir>", "Working directory", process.cwd()).option("-p, --package <name>", "Target package name (for monorepos)").option("-o, --output <file>", "Output file path", "openpkg.json").option("--include <patterns>", "Include exports matching pattern (comma-separated)").option("--exclude <patterns>", "Exclude exports matching pattern (comma-separated)").option("--skip-resolve", "Skip external type resolution from node_modules").option("--max-type-depth <n>", "Maximum depth for type conversion", "20").option("--no-cache", "Bypass spec cache and force regeneration").option("--show-diagnostics", "Show TypeScript compiler diagnostics").action(async (entry, options) => {
+    try {
+      const fileSystem = new NodeFileSystem4(options.cwd);
+      const resolved = await resolveTarget3(fileSystem, {
+        cwd: options.cwd,
+        package: options.package,
+        entry
+      });
+      const { targetDir, entryFile, packageInfo, entryPointInfo } = resolved;
+      if (packageInfo) {
+        log(chalk8.gray(`Found package at ${packageInfo.path}`));
+      }
+      if (!entry) {
+        log(chalk8.gray(`Auto-detected entry point: ${entryPointInfo.path} (from ${entryPointInfo.source})`));
+      }
+      let config = null;
+      try {
+        config = await loadDocCovConfig(targetDir);
+        if (config?.filePath) {
+          log(chalk8.gray(`Loaded configuration from ${path8.relative(targetDir, config.filePath)}`));
+        }
+      } catch (configError) {
+        error(chalk8.red("Failed to load DocCov config:"), configError instanceof Error ? configError.message : configError);
+        process.exit(1);
+      }
+      const cliFilters = {
+        include: parseListFlag(options.include),
+        exclude: parseListFlag(options.exclude)
+      };
+      const resolvedFilters = mergeFilterOptions(config, cliFilters);
+      for (const message of resolvedFilters.messages) {
+        log(chalk8.gray(`${message}`));
+      }
+      const resolveExternalTypes = !options.skipResolve;
+      process.stdout.write(chalk8.cyan(`> Generating OpenPkg spec...
+`));
+      let result;
+      try {
+        const doccov = createDocCov({
+          resolveExternalTypes,
+          maxDepth: options.maxTypeDepth ? parseInt(options.maxTypeDepth, 10) : undefined,
+          useCache: options.cache !== false,
+          cwd: options.cwd
+        });
+        const analyzeOptions = resolvedFilters.include || resolvedFilters.exclude ? {
+          filters: {
+            include: resolvedFilters.include,
+            exclude: resolvedFilters.exclude
+          }
+        } : {};
+        result = await doccov.analyzeFileWithDiagnostics(entryFile, analyzeOptions);
+        if (result.fromCache) {
+          process.stdout.write(chalk8.gray(`> Using cached spec
+`));
+        } else {
+          process.stdout.write(chalk8.green(`> Generated OpenPkg spec
+`));
+        }
+      } catch (generationError) {
+        process.stdout.write(chalk8.red(`> Failed to generate spec
+`));
+        throw generationError;
+      }
+      if (!result) {
+        throw new Error("Failed to produce an OpenPkg spec.");
+      }
+      const normalized = normalize(result.spec);
+      const validation = validateSpec(normalized);
+      if (!validation.ok) {
+        error(chalk8.red("Spec failed schema validation"));
+        for (const err of validation.errors) {
+          error(chalk8.red(`schema: ${err.instancePath || "/"} ${err.message}`));
+        }
+        process.exit(1);
+      }
+      const outputPath = path8.resolve(process.cwd(), options.output);
+      writeFileSync5(outputPath, JSON.stringify(normalized, null, 2));
+      log(chalk8.green(`> Wrote ${options.output}`));
+      log(chalk8.gray(`  ${getArrayLength(normalized.exports)} exports`));
+      log(chalk8.gray(`  ${getArrayLength(normalized.types)} types`));
+      if (options.showDiagnostics && result.diagnostics.length > 0) {
+        log("");
+        log(chalk8.bold("Diagnostics"));
+        for (const diagnostic of result.diagnostics) {
+          const prefix = diagnostic.severity === "error" ? chalk8.red(">") : diagnostic.severity === "warning" ? chalk8.yellow(">") : chalk8.cyan(">");
+          log(formatDiagnosticOutput(prefix, diagnostic, targetDir));
+        }
+      }
+    } catch (commandError) {
+      error(chalk8.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      process.exit(1);
+    }
+  });
+}
+
 // src/cli.ts
 var __filename2 = fileURLToPath(import.meta.url);
-var __dirname2 = path8.dirname(__filename2);
-var packageJson = JSON.parse(readFileSync4(path8.join(__dirname2, "../package.json"), "utf-8"));
+var __dirname2 = path9.dirname(__filename2);
+var packageJson = JSON.parse(readFileSync4(path9.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);
-registerGenerateCommand(program);
 registerCheckCommand(program);
+registerInfoCommand(program);
+registerSpecCommand(program);
 registerDiffCommand(program);
 registerInitCommand(program);
 registerScanCommand(program);