@doccov/cli 0.25.11 → 0.27.0

package/dist/cli.js

@@ -25,10 +25,18 @@ var exampleModesSchema = z.union([
   z.array(exampleModeSchema),
   z.string()
 ]);
+var apiSurfaceConfigSchema = z.object({
+  minCompleteness: z.number().min(0).max(100).optional(),
+  warnBelow: z.number().min(0).max(100).optional(),
+  ignore: z.array(z.string()).optional()
+});
 var checkConfigSchema = z.object({
   examples: exampleModesSchema.optional(),
+  minHealth: z.number().min(0).max(100).optional(),
   minCoverage: z.number().min(0).max(100).optional(),
-  maxDrift: z.number().min(0).max(100).optional()
+  maxDrift: z.number().min(0).max(100).optional(),
+  minApiSurface: z.number().min(0).max(100).optional(),
+  apiSurface: apiSurfaceConfigSchema.optional()
 });
 var docCovConfigSchema = z.object({
   include: stringList.optional(),
@@ -63,8 +71,11 @@ var normalizeConfig = (input) => {
   if (input.check) {
     check = {
       examples: input.check.examples,
+      minHealth: input.check.minHealth,
       minCoverage: input.check.minCoverage,
-      maxDrift: input.check.maxDrift
+      maxDrift: input.check.maxDrift,
+      minApiSurface: input.check.minApiSurface,
+      apiSurface: input.check.apiSurface
     };
   }
   return {
@@ -151,6 +162,16 @@ import * as path10 from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 
+// src/commands/check/index.ts
+import {
+  buildDocCovSpec,
+  DocCov,
+  NodeFileSystem,
+  parseExamplesFlag,
+  resolveTarget
+} from "@doccov/sdk";
+import chalk7 from "chalk";
+
 // ../cli-utils/dist/index.js
 import chalk from "chalk";
 import chalk2 from "chalk";
@@ -1141,16 +1162,6 @@ function summary(options) {
   return new Summary(options);
 }
 
-// src/commands/check/index.ts
-import {
-  buildDocCovSpec,
-  DocCov,
-  NodeFileSystem,
-  parseExamplesFlag,
-  resolveTarget
-} from "@doccov/sdk";
-import chalk7 from "chalk";
-
 // src/utils/filter-options.ts
 import { mergeFilters, parseListFlag } from "@doccov/sdk";
 import chalk3 from "chalk";
@@ -1218,12 +1229,15 @@ import * as fs2 from "node:fs";
 import * as path3 from "node:path";
 import {
   applyEdits,
+  applyForgottenExportFixes,
   categorizeDrifts,
   createSourceFile,
   findJSDocLocation,
   generateFixesForExport,
+  generateForgottenExportFixes,
   mergeFixes,
   parseJSDocToPatch,
+  previewForgottenExportFixes,
   serializeJSDoc
 } from "@doccov/sdk";
 import chalk5 from "chalk";
@@ -1296,12 +1310,12 @@ async function handleFixes(openpkg, doccov, options, deps) {
   const fixedDriftKeys = new Set;
   const allDrifts = collectDriftsFromExports(openpkg.exports ?? [], doccov);
   if (allDrifts.length === 0) {
-    return { fixedDriftKeys, editsApplied: 0, filesModified: 0 };
+    return { fixedDriftKeys, editsApplied: 0, filesModified: 0, forgottenExportsFixed: 0 };
   }
   const { fixable, nonFixable } = categorizeDrifts(allDrifts.map((d) => d.drift));
   if (fixable.length === 0) {
     log(chalk5.yellow(`Found ${nonFixable.length} drift issue(s), but none are auto-fixable.`));
-    return { fixedDriftKeys, editsApplied: 0, filesModified: 0 };
+    return { fixedDriftKeys, editsApplied: 0, filesModified: 0, forgottenExportsFixed: 0 };
   }
   log("");
   log(chalk5.bold(`Found ${fixable.length} fixable issue(s)`));
@@ -1330,11 +1344,11 @@ async function handleFixes(openpkg, doccov, options, deps) {
     editsByFile.set(edit.filePath, fileEdits);
   }
   if (edits.length === 0) {
-    return { fixedDriftKeys, editsApplied: 0, filesModified: 0 };
+    return { fixedDriftKeys, editsApplied: 0, filesModified: 0, forgottenExportsFixed: 0 };
   }
   if (isPreview) {
     displayPreview(editsByFile, targetDir, log);
-    return { fixedDriftKeys, editsApplied: 0, filesModified: 0 };
+    return { fixedDriftKeys, editsApplied: 0, filesModified: 0, forgottenExportsFixed: 0 };
   }
   const applyResult = await applyEdits(edits);
   if (applyResult.errors.length > 0) {
@@ -1350,12 +1364,78 @@ async function handleFixes(openpkg, doccov, options, deps) {
     const fixCount = fileEdits.reduce((s, e) => s + e.fixes.length, 0);
     log(chalk5.dim(`  ${relativePath} (${fixCount} fixes)`));
   }
+  if (options.healthScore !== undefined) {
+    log("");
+    log(chalk5.cyan("Run doccov check again to see updated health score"));
+  }
   return {
     fixedDriftKeys,
     editsApplied: totalFixes,
-    filesModified: applyResult.filesModified
+    filesModified: applyResult.filesModified,
+    forgottenExportsFixed: 0
   };
 }
+async function handleForgottenExportFixes(doccov, options, deps) {
+  const { isPreview, targetDir, entryFile } = options;
+  const { log, error } = deps;
+  if (!doccov.apiSurface || doccov.apiSurface.forgotten.length === 0) {
+    return { fixesApplied: 0, filesModified: 0 };
+  }
+  const fixable = doccov.apiSurface.forgotten.filter((f) => !f.isExternal && f.fix);
+  if (fixable.length === 0) {
+    return { fixesApplied: 0, filesModified: 0 };
+  }
+  const fixes = generateForgottenExportFixes(doccov.apiSurface, {
+    baseDir: targetDir,
+    entryFile: entryFile ?? "src/index.ts"
+  });
+  if (fixes.length === 0) {
+    return { fixesApplied: 0, filesModified: 0 };
+  }
+  log("");
+  log(chalk5.bold(`Found ${fixes.length} forgotten export(s) to fix`));
+  if (isPreview) {
+    displayForgottenExportPreview(fixes, targetDir, log);
+    return { fixesApplied: 0, filesModified: 0 };
+  }
+  const result = await applyForgottenExportFixes(fixes);
+  if (result.errors.length > 0) {
+    for (const err of result.errors) {
+      error(chalk5.red(`  ${err.file}: ${err.error}`));
+    }
+  }
+  if (result.fixesApplied > 0) {
+    log("");
+    log(chalk5.green(`✓ Added ${result.fixesApplied} export(s) to ${result.filesModified} file(s)`));
+    const grouped = new Map;
+    for (const fix of fixes) {
+      const relativePath = path3.relative(targetDir, fix.targetFile);
+      const types = grouped.get(relativePath) ?? [];
+      types.push(fix.typeName);
+      grouped.set(relativePath, types);
+    }
+    for (const [file, types] of grouped) {
+      log(chalk5.dim(`  ${file}: ${types.join(", ")}`));
+    }
+  }
+  return { fixesApplied: result.fixesApplied, filesModified: result.filesModified };
+}
+function displayForgottenExportPreview(fixes, targetDir, log) {
+  log(chalk5.bold("Preview - forgotten exports that would be added:"));
+  log("");
+  const previews = previewForgottenExportFixes(fixes);
+  for (const [filePath, preview] of previews) {
+    const relativePath = path3.relative(targetDir, filePath);
+    log(chalk5.cyan(`${relativePath}:${preview.insertLine + 1}`));
+    log("");
+    for (const stmt of preview.statements) {
+      log(chalk5.green(`  + ${stmt}`));
+    }
+    log("");
+  }
+  log(chalk5.yellow(`${fixes.length} export(s) would be added.`));
+  log(chalk5.gray("Run with --fix to apply these changes."));
+}
 function generateEditForExport(exp, drifts, targetDir, log) {
   if (!exp.source?.file) {
     log(chalk5.gray(`  Skipping ${exp.name}: no source location`));
@@ -1726,9 +1806,31 @@ 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}%
+  let output = "";
+  if (stats.health) {
+    const h = stats.health;
+    const status = h.score >= 80 ? "✅" : h.score >= 50 ? "⚠️" : "❌";
+    output += `## ${status} Documentation Health: ${h.score}%
 
 `;
+    output += `| Metric | Score | Details |
+|--------|-------|---------|
+`;
+    output += `| Completeness | ${h.completeness.score}% | ${h.completeness.total - h.completeness.documented} missing docs |
+`;
+    output += `| Accuracy | ${h.accuracy.score}% | ${h.accuracy.issues} drift issues |
+`;
+    if (h.examples) {
+      output += `| Examples | ${h.examples.score}% | ${h.examples.passed}/${h.examples.total} passed |
+`;
+    }
+    output += `
+`;
+  } else {
+    output += `## Documentation Coverage: ${coverageScore}%
+
+`;
+  }
   output += `| Metric | Value |
 |--------|-------|
 `;
@@ -1740,10 +1842,12 @@ function renderGithubSummary(stats, options = {}) {
 `;
   output += `| Quality Issues | ${qualityIssues} |
 `;
-  const status = coverageScore >= 80 ? "✅" : coverageScore >= 50 ? "⚠️" : "❌";
-  output += `
+  if (!stats.health) {
+    const status = coverageScore >= 80 ? "✅" : coverageScore >= 50 ? "⚠️" : "❌";
+    output += `
 ${status} Coverage ${coverageScore >= 80 ? "passing" : coverageScore >= 50 ? "needs improvement" : "failing"}
 `;
+  }
   return output;
 }
 // src/reports/markdown.ts
@@ -1757,6 +1861,19 @@ function renderMarkdown(stats, options = {}) {
   const lines = [];
   lines.push(`# DocCov Report: ${stats.packageName}@${stats.version}`);
   lines.push("");
+  if (stats.health) {
+    const h = stats.health;
+    lines.push(`## Documentation Health: ${h.score}%`);
+    lines.push("");
+    lines.push("| Metric | Score | Details |");
+    lines.push("|--------|-------|---------|");
+    lines.push(`| Completeness | ${h.completeness.score}% | ${h.completeness.total - h.completeness.documented} missing docs |`);
+    lines.push(`| Accuracy | ${h.accuracy.score}% | ${h.accuracy.issues} drift issues |`);
+    if (h.examples) {
+      lines.push(`| Examples | ${h.examples.score}% | ${h.examples.passed}/${h.examples.total} passed |`);
+    }
+    lines.push("");
+  }
   lines.push(`**Coverage: ${stats.coverageScore}%** \`${bar2(stats.coverageScore)}\``);
   lines.push("");
   lines.push("| Metric | Value |");
@@ -1836,6 +1953,24 @@ function renderMarkdown(stats, options = {}) {
       lines.push("");
     }
   }
+  if (stats.apiSurface && stats.apiSurface.forgotten.length > 0) {
+    lines.push("");
+    lines.push("## API Surface");
+    lines.push("");
+    lines.push(`**${stats.apiSurface.completeness}% complete** (${stats.apiSurface.forgotten.length} forgotten exports)`);
+    lines.push("");
+    lines.push("| Type | Defined In | Referenced By |");
+    lines.push("|------|------------|---------------|");
+    for (const f of stats.apiSurface.forgotten.slice(0, limit)) {
+      const definedIn = f.definedIn ? `${f.definedIn.file}${f.definedIn.line ? `:${f.definedIn.line}` : ""}` : "-";
+      const refs = f.referencedBy.slice(0, 2).map((r) => `${r.exportName} (${r.location})`).join(", ");
+      const moreRefs = f.referencedBy.length > 2 ? ` +${f.referencedBy.length - 2}` : "";
+      lines.push(`| \`${f.name}\` | ${definedIn} | ${refs}${moreRefs} |`);
+    }
+    if (stats.apiSurface.forgotten.length > limit) {
+      lines.push(`| ... | | ${stats.apiSurface.forgotten.length - limit} more |`);
+    }
+  }
   lines.push("");
   lines.push("---");
   lines.push("*Generated by [DocCov](https://doccov.com)*");
@@ -2253,7 +2388,9 @@ function computeStats(openpkg, doccov) {
     exports: sortedExports,
     driftIssues,
     driftByCategory,
-    driftSummary
+    driftSummary,
+    apiSurface: doccov.apiSurface,
+    health: doccov.summary.health
   };
 }
 // src/reports/writer.ts
@@ -2295,26 +2432,97 @@ function writeReports(options) {
   return results;
 }
 // src/commands/check/output.ts
+function getHealthStatus(score) {
+  if (score >= 80)
+    return "pass";
+  if (score >= 60)
+    return "warn";
+  return "fail";
+}
+function getHealthColor(status) {
+  switch (status) {
+    case "pass":
+      return colors.success;
+    case "warn":
+      return colors.warning;
+    case "fail":
+      return colors.error;
+  }
+}
+function displayHealthTree(health, log) {
+  const tree = supportsUnicode() ? { branch: "├─", corner: "└─" } : { branch: "|-", corner: "\\-" };
+  const missingTotal = Object.values(health.completeness.missing).reduce((a, b) => a + b, 0);
+  const completenessLabel = missingTotal > 0 ? `${health.completeness.score}%  (${missingTotal} missing docs)` : `${health.completeness.score}%`;
+  const completenessColor = getHealthColor(getHealthStatus(health.completeness.score));
+  log(`${tree.branch} ${colors.muted("completeness")}  ${completenessColor(completenessLabel)}`);
+  const accuracyLabel = health.accuracy.issues > 0 ? `${health.accuracy.score}%  (${health.accuracy.issues} drift issues${health.accuracy.fixable > 0 ? `, ${health.accuracy.fixable} fixable` : ""})` : `${health.accuracy.score}%`;
+  const accuracyColor = getHealthColor(getHealthStatus(health.accuracy.score));
+  const lastBranch = !health.examples ? tree.corner : tree.branch;
+  log(`${lastBranch} ${colors.muted("accuracy")}      ${accuracyColor(accuracyLabel)}`);
+  if (health.examples) {
+    const examplesLabel = health.examples.failed > 0 ? `${health.examples.score}%  (${health.examples.failed} failed)` : `${health.examples.score}%`;
+    const examplesColor = getHealthColor(getHealthStatus(health.examples.score));
+    log(`${tree.corner} ${colors.muted("examples")}      ${examplesColor(examplesLabel)}`);
+  }
+}
+function displayHealthVerbose(health, log) {
+  const tree = supportsUnicode() ? { branch: "├─", corner: "└─" } : { branch: "|-", corner: "\\-" };
+  log(colors.bold("COMPLETENESS") + `  ${health.completeness.score}%`);
+  const missingRules = Object.entries(health.completeness.missing);
+  for (let i = 0;i < missingRules.length; i++) {
+    const [rule, count] = missingRules[i];
+    const isLast = i === missingRules.length - 1;
+    const prefix2 = isLast ? tree.corner : tree.branch;
+    const label = count > 0 ? `(${count} missing)` : "";
+    const pct = health.completeness.total > 0 ? Math.round((health.completeness.total - count) / health.completeness.total * 100) : 100;
+    const color = getHealthColor(getHealthStatus(pct));
+    log(`${prefix2} ${colors.muted(rule.padEnd(12))} ${color(`${pct}%`)}  ${colors.muted(label)}`);
+  }
+  log("");
+  log(colors.bold("ACCURACY") + `  ${health.accuracy.score}%  ${colors.muted(`(${health.accuracy.issues} issues)`)}`);
+  const categories = Object.entries(health.accuracy.byCategory);
+  for (let i = 0;i < categories.length; i++) {
+    const [category, count] = categories[i];
+    const isLast = i === categories.length - 1;
+    const prefix2 = isLast ? tree.corner : tree.branch;
+    log(`${prefix2} ${colors.muted(category.padEnd(12))} ${count}`);
+  }
+  if (health.examples) {
+    log("");
+    log(colors.bold("EXAMPLES") + `  ${health.examples.score}%`);
+    log(`${tree.branch} ${colors.muted("passed".padEnd(12))} ${health.examples.passed}`);
+    log(`${tree.corner} ${colors.muted("failed".padEnd(12))} ${health.examples.failed}`);
+  }
+}
 function displayTextOutput(options, deps) {
   const {
     openpkg,
+    doccov,
     coverageScore,
-    minCoverage,
-    maxDrift,
+    minHealth,
+    minApiSurface,
+    warnBelowApiSurface,
     driftExports,
     typecheckErrors,
     staleRefs,
     exampleResult,
     specWarnings,
-    specInfos
+    specInfos,
+    verbose
   } = options;
   const { log } = deps;
   const sym = getSymbols(supportsUnicode());
+  const health = doccov.summary.health;
+  const healthScore = health?.score ?? coverageScore;
   const totalExportsForDrift = openpkg.exports?.length ?? 0;
   const exportsWithDrift = new Set(driftExports.map((d) => d.name)).size;
   const driftScore = totalExportsForDrift === 0 ? 0 : Math.round(exportsWithDrift / totalExportsForDrift * 100);
-  const coverageFailed = coverageScore < minCoverage;
-  const driftFailed = maxDrift !== undefined && driftScore > maxDrift;
+  const apiSurface = doccov.apiSurface;
+  const apiSurfaceScore = apiSurface?.completeness ?? 100;
+  const forgottenCount = apiSurface?.forgotten?.length ?? 0;
+  const healthFailed = healthScore < minHealth;
+  const apiSurfaceFailed = minApiSurface !== undefined && apiSurfaceScore < minApiSurface;
+  const apiSurfaceWarn = warnBelowApiSurface !== undefined && apiSurfaceScore < warnBelowApiSurface && !apiSurfaceFailed;
   const hasTypecheckErrors = typecheckErrors.length > 0;
   if (specWarnings.length > 0 || specInfos.length > 0) {
     log("");
@@ -2333,31 +2541,35 @@ function displayTextOutput(options, deps) {
   }
   const pkgName = openpkg.meta?.name ?? "unknown";
   const pkgVersion = openpkg.meta?.version ?? "";
-  const totalExports = openpkg.exports?.length ?? 0;
   log("");
-  log(colors.bold(`${pkgName}${pkgVersion ? `@${pkgVersion}` : ""}`));
+  log(colors.bold(`${pkgName}${pkgVersion ? ` v${pkgVersion}` : ""}`));
   log("");
-  const summaryBuilder = summary({ keyWidth: 10 });
-  summaryBuilder.addKeyValue("Exports", totalExports);
-  summaryBuilder.addKeyValue("Coverage", `${coverageScore}%`, coverageFailed ? "fail" : "pass");
-  if (maxDrift !== undefined) {
-    summaryBuilder.addKeyValue("Drift", `${driftScore}%`, driftFailed ? "fail" : "pass");
+  const hasStaleRefs = staleRefs.length > 0;
+  if (health) {
+    const healthColor = getHealthColor(getHealthStatus(health.score));
+    log(`${colors.muted("Health")}   ${healthColor(`${health.score}%`)}`);
+    if (verbose) {
+      log("");
+      displayHealthVerbose(health, log);
+    } else {
+      displayHealthTree(health, log);
+    }
   } else {
+    const summaryBuilder = summary({ keyWidth: 10 });
+    summaryBuilder.addKeyValue("Exports", openpkg.exports?.length ?? 0);
+    summaryBuilder.addKeyValue("Coverage", `${coverageScore}%`);
     summaryBuilder.addKeyValue("Drift", `${driftScore}%`);
+    summaryBuilder.print();
   }
-  if (exampleResult) {
-    const typecheckCount = exampleResult.typecheck?.errors.length ?? 0;
-    if (typecheckCount > 0) {
-      summaryBuilder.addKeyValue("Examples", `${typecheckCount} type error(s)`, "warn");
-    } else {
-      summaryBuilder.addKeyValue("Examples", "validated", "pass");
-    }
+  log("");
+  if (forgottenCount > 0 || minApiSurface !== undefined || warnBelowApiSurface !== undefined) {
+    const surfaceLabel = forgottenCount > 0 ? `${apiSurfaceScore}% (${forgottenCount} forgotten)` : `${apiSurfaceScore}%`;
+    const surfaceColor = apiSurfaceFailed ? colors.error : apiSurfaceWarn || forgottenCount > 0 ? colors.warning : colors.success;
+    log(`${colors.muted("API Surface")}  ${surfaceColor(surfaceLabel)}`);
   }
-  const hasStaleRefs = staleRefs.length > 0;
   if (hasStaleRefs) {
-    summaryBuilder.addKeyValue("Docs", `${staleRefs.length} stale ref(s)`, "warn");
+    log(`${colors.muted("Stale refs")}   ${colors.warning(`${staleRefs.length} found`)}`);
   }
-  summaryBuilder.print();
   if (hasTypecheckErrors) {
     log("");
     for (const err of typecheckErrors.slice(0, 5)) {
@@ -2378,22 +2590,55 @@ function displayTextOutput(options, deps) {
       log(colors.muted(`  ... and ${staleRefs.length - 5} more`));
     }
   }
+  if (verbose && forgottenCount > 0 && apiSurface?.forgotten) {
+    log("");
+    log(colors.bold(`Forgotten Exports (${forgottenCount})`));
+    log("");
+    for (const forgotten of apiSurface.forgotten.slice(0, 10)) {
+      log(`  ${colors.warning(forgotten.name)}`);
+      if (forgotten.definedIn) {
+        log(colors.muted(`    Defined in: ${forgotten.definedIn.file}${forgotten.definedIn.line ? `:${forgotten.definedIn.line}` : ""}`));
+      }
+      if (forgotten.referencedBy.length > 0) {
+        log(colors.muted("    Referenced by:"));
+        for (const ref of forgotten.referencedBy.slice(0, 3)) {
+          log(colors.muted(`      - ${ref.exportName} (${ref.location})`));
+        }
+        if (forgotten.referencedBy.length > 3) {
+          log(colors.muted(`      ... and ${forgotten.referencedBy.length - 3} more`));
+        }
+      }
+      if (forgotten.fix) {
+        log(colors.info(`    Fix: Add to ${forgotten.fix.targetFile}:`));
+        log(colors.info(`      ${forgotten.fix.exportStatement}`));
+      }
+    }
+    if (apiSurface.forgotten.length > 10) {
+      log(colors.muted(`  ... and ${apiSurface.forgotten.length - 10} more`));
+    }
+  }
   log("");
-  const failed = coverageFailed || driftFailed || hasTypecheckErrors || hasStaleRefs;
+  const failed = healthFailed || apiSurfaceFailed || hasTypecheckErrors || hasStaleRefs;
   if (!failed) {
     const thresholdParts = [];
-    thresholdParts.push(`coverage ${coverageScore}% ≥ ${minCoverage}%`);
-    if (maxDrift !== undefined) {
-      thresholdParts.push(`drift ${driftScore}% ≤ ${maxDrift}%`);
+    thresholdParts.push(`health ${healthScore}% ≥ ${minHealth}%`);
+    if (minApiSurface !== undefined) {
+      thresholdParts.push(`api-surface ${apiSurfaceScore}% ≥ ${minApiSurface}%`);
     }
     log(colors.success(`${sym.success} Check passed (${thresholdParts.join(", ")})`));
+    if (apiSurfaceWarn) {
+      log(colors.warning(`${sym.warning} API Surface ${apiSurfaceScore}% below warning threshold ${warnBelowApiSurface}%`));
+    }
+    if (!verbose && health) {
+      log(colors.muted("Use --verbose for detailed breakdown"));
+    }
     return true;
   }
-  if (coverageFailed) {
-    log(colors.error(`${sym.error} Coverage ${coverageScore}% below minimum ${minCoverage}%`));
+  if (healthFailed) {
+    log(colors.error(`${sym.error} Health ${healthScore}% below minimum ${minHealth}%`));
   }
-  if (driftFailed) {
-    log(colors.error(`${sym.error} Drift ${driftScore}% exceeds maximum ${maxDrift}%`));
+  if (apiSurfaceFailed) {
+    log(colors.error(`${sym.error} API Surface ${apiSurfaceScore}% below minimum ${minApiSurface}%`));
   }
   if (hasTypecheckErrors) {
     log(colors.error(`${sym.error} ${typecheckErrors.length} example type errors`));
@@ -2401,8 +2646,10 @@ function displayTextOutput(options, deps) {
   if (hasStaleRefs) {
     log(colors.error(`${sym.error} ${staleRefs.length} stale references in docs`));
   }
-  log("");
-  log(colors.muted("Use --format json or --format markdown for detailed reports"));
+  if (health && health.accuracy.fixable > 0) {
+    log("");
+    log(colors.muted(`Use --fix to auto-fix ${health.accuracy.fixable} drift issue(s)`));
+  }
   return false;
 }
 function handleNonTextOutput(options, deps) {
@@ -2411,8 +2658,8 @@ function handleNonTextOutput(options, deps) {
     openpkg,
     doccov,
     coverageScore,
-    minCoverage,
-    maxDrift,
+    minHealth,
+    minApiSurface,
     driftExports,
     typecheckErrors,
     limit,
@@ -2424,6 +2671,7 @@ function handleNonTextOutput(options, deps) {
   const stats = computeStats(openpkg, doccov);
   const report = generateReportFromDocCov(openpkg, doccov);
   const jsonContent = JSON.stringify(report, null, 2);
+  const healthScore = doccov.summary.health?.score ?? coverageScore;
   let formatContent;
   switch (format) {
     case "json":
@@ -2455,13 +2703,57 @@ function handleNonTextOutput(options, deps) {
       cwd
     });
   }
-  const totalExportsForDrift = openpkg.exports?.length ?? 0;
-  const exportsWithDrift = new Set(driftExports.map((d) => d.name)).size;
-  const driftScore = totalExportsForDrift === 0 ? 0 : Math.round(exportsWithDrift / totalExportsForDrift * 100);
-  const coverageFailed = coverageScore < minCoverage;
-  const driftFailed = maxDrift !== undefined && driftScore > maxDrift;
+  const healthFailed = healthScore < minHealth;
+  const apiSurfaceScore = doccov.apiSurface?.completeness ?? 100;
+  const apiSurfaceFailed = minApiSurface !== undefined && apiSurfaceScore < minApiSurface;
   const hasTypecheckErrors = typecheckErrors.length > 0;
-  return !(coverageFailed || driftFailed || hasTypecheckErrors);
+  return !(healthFailed || apiSurfaceFailed || hasTypecheckErrors);
+}
+function displayApiSurfaceOutput(doccov, deps) {
+  const { log } = deps;
+  const apiSurface = doccov.apiSurface;
+  log("");
+  log(colors.bold("API Surface Analysis"));
+  log("");
+  if (!apiSurface) {
+    log(colors.muted("No API surface data available"));
+    return;
+  }
+  const sym = getSymbols(supportsUnicode());
+  const summaryBuilder = summary({ keyWidth: 12 });
+  summaryBuilder.addKeyValue("Referenced", apiSurface.totalReferenced);
+  summaryBuilder.addKeyValue("Exported", apiSurface.exported);
+  summaryBuilder.addKeyValue("Forgotten", apiSurface.forgotten.length);
+  summaryBuilder.addKeyValue("Completeness", `${apiSurface.completeness}%`, apiSurface.forgotten.length > 0 ? "warn" : "pass");
+  summaryBuilder.print();
+  if (apiSurface.forgotten.length > 0) {
+    log("");
+    log(colors.bold(`Forgotten Exports (${apiSurface.forgotten.length})`));
+    log("");
+    for (const forgotten of apiSurface.forgotten) {
+      log(`  ${colors.warning(forgotten.name)}`);
+      if (forgotten.definedIn) {
+        log(colors.muted(`    Defined in: ${forgotten.definedIn.file}${forgotten.definedIn.line ? `:${forgotten.definedIn.line}` : ""}`));
+      }
+      if (forgotten.referencedBy.length > 0) {
+        log(colors.muted("    Referenced by:"));
+        for (const ref of forgotten.referencedBy.slice(0, 5)) {
+          log(colors.muted(`      - ${ref.exportName} (${ref.location})`));
+        }
+        if (forgotten.referencedBy.length > 5) {
+          log(colors.muted(`      ... and ${forgotten.referencedBy.length - 5} more`));
+        }
+      }
+      if (forgotten.fix) {
+        log(colors.info(`    Fix: Add to ${forgotten.fix.targetFile}:`));
+        log(colors.info(`      ${forgotten.fix.exportStatement}`));
+      }
+      log("");
+    }
+  } else {
+    log("");
+    log(colors.success(`${sym.success} All referenced types are exported`));
+  }
 }
 
 // src/commands/check/validation.ts
@@ -2546,12 +2838,12 @@ function registerCheckCommand(program, dependencies = {}) {
     ...defaultDependencies,
     ...dependencies
   };
-  program.command("check [entry]").description("Check documentation coverage and output reports").option("--cwd <dir>", "Working directory", process.cwd()).option("--package <name>", "Target package name (for monorepos)").option("--min-coverage <percentage>", "Minimum docs coverage percentage (0-100)", (value) => Number(value)).option("--max-drift <percentage>", "Maximum drift percentage allowed (0-100)", (value) => Number(value)).option("--examples [mode]", "Example validation: presence, typecheck, run (comma-separated). Bare flag runs all.").option("--skip-resolve", "Skip external type resolution from node_modules").option("--docs <glob>", "Glob pattern for markdown docs to check for stale refs", collect, []).option("--fix", "Auto-fix drift issues").option("--preview", "Preview fixes with diff output (implies --fix)").option("--format <format>", "Output format: text, json, markdown, html, github", "text").option("-o, --output <file>", "Custom output path (overrides default .doccov/ path)").option("--stdout", "Output to stdout instead of writing to .doccov/").option("--update-snapshot", "Force regenerate .doccov/report.json").option("--limit <n>", "Max exports to show in report tables", "20").option("--max-type-depth <number>", "Maximum depth for type conversion (default: 20)", (value) => {
+  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-health <percentage>", "Minimum health score (0-100)", (value) => Number(value)).option("--min-coverage <percentage>", "[deprecated] Use --min-health instead", (value) => Number(value)).option("--max-drift <percentage>", "[deprecated] Use --min-health instead", (value) => Number(value)).option("--examples [mode]", "Example validation: presence, typecheck, run (comma-separated). Bare flag runs all.").option("--skip-resolve", "Skip external type resolution from node_modules").option("--docs <glob>", "Glob pattern for markdown docs to check for stale refs", collect, []).option("--fix", "Auto-fix drift issues").option("--preview", "Preview fixes with diff output (implies --fix)").option("--format <format>", "Output format: text, json, markdown, html, github", "text").option("-o, --output <file>", "Custom output path (overrides default .doccov/ path)").option("--stdout", "Output to stdout instead of writing to .doccov/").option("--update-snapshot", "Force regenerate .doccov/report.json").option("--limit <n>", "Max exports to show in report tables", "20").option("--max-type-depth <number>", "Maximum depth for type conversion (default: 20)", (value) => {
     const n = parseInt(value, 10);
     if (Number.isNaN(n) || n < 1)
       throw new Error("--max-type-depth must be a positive integer");
     return n;
-  }).option("--no-cache", "Bypass spec cache and force regeneration").option("--visibility <tags>", "Filter by release stage: public,beta,alpha,internal (comma-separated)").action(async (entry, options) => {
+  }).option("--no-cache", "Bypass spec cache and force regeneration").option("--visibility <tags>", "Filter by release stage: public,beta,alpha,internal (comma-separated)").option("--min-api-surface <percentage>", "Minimum API surface completeness percentage (0-100)", (value) => Number(value)).option("--api-surface", "Show only API surface / forgotten exports info").option("-v, --verbose", "Show detailed output including forgotten exports").action(async (entry, options) => {
     try {
       const spin = spinner("Analyzing...");
       let validations = parseExamplesFlag(options.examples);
@@ -2573,11 +2865,30 @@ function registerCheckCommand(program, dependencies = {}) {
         }
         hasExamples = validations.length > 0;
       }
-      const DEFAULT_MIN_COVERAGE = 80;
-      const minCoverageRaw = options.minCoverage ?? config?.check?.minCoverage ?? DEFAULT_MIN_COVERAGE;
+      if (options.minCoverage !== undefined) {
+        log(chalk7.yellow("Warning: --min-coverage is deprecated. Use --min-health instead."));
+      }
+      if (options.maxDrift !== undefined) {
+        log(chalk7.yellow("Warning: --max-drift is deprecated. Use --min-health instead."));
+      }
+      if (config?.check?.minCoverage !== undefined) {
+        log(chalk7.yellow("Warning: config.check.minCoverage is deprecated. Use minHealth."));
+      }
+      if (config?.check?.maxDrift !== undefined) {
+        log(chalk7.yellow("Warning: config.check.maxDrift is deprecated. Use minHealth."));
+      }
+      const DEFAULT_MIN_HEALTH = 80;
+      const minHealthRaw = options.minHealth ?? config?.check?.minHealth ?? DEFAULT_MIN_HEALTH;
+      const minHealth = clampPercentage(minHealthRaw);
+      const minCoverageRaw = options.minCoverage ?? config?.check?.minCoverage ?? DEFAULT_MIN_HEALTH;
       const minCoverage = clampPercentage(minCoverageRaw);
       const maxDriftRaw = options.maxDrift ?? config?.check?.maxDrift;
       const maxDrift = maxDriftRaw !== undefined ? clampPercentage(maxDriftRaw) : undefined;
+      const apiSurfaceConfig = config?.check?.apiSurface;
+      const minApiSurfaceRaw = options.minApiSurface ?? apiSurfaceConfig?.minCompleteness ?? config?.check?.minApiSurface;
+      const minApiSurface = minApiSurfaceRaw !== undefined ? clampPercentage(minApiSurfaceRaw) : undefined;
+      const warnBelowApiSurface = apiSurfaceConfig?.warnBelow ? clampPercentage(apiSurfaceConfig.warnBelow) : undefined;
+      const apiSurfaceIgnore = apiSurfaceConfig?.ignore ?? [];
       const cliFilters = {
         include: undefined,
         exclude: undefined,
@@ -2604,7 +2915,9 @@ function registerCheckCommand(program, dependencies = {}) {
       const doccov = buildDocCovSpec({
         openpkg,
         openpkgPath: entryFile,
-        packagePath: targetDir
+        packagePath: targetDir,
+        forgottenExports: specResult.forgottenExports,
+        apiSurfaceIgnore
       });
       const format = options.format ?? "text";
       const specWarnings = specResult.diagnostics.filter((d) => d.severity === "warning");
@@ -2635,21 +2948,33 @@ function registerCheckCommand(program, dependencies = {}) {
       const coverageScore = doccov.summary.score;
       const allDriftExports = [...collectDrift(openpkg.exports ?? [], doccov), ...runtimeDrifts];
       let driftExports = hasExamples ? allDriftExports : allDriftExports.filter((d) => d.category !== "example");
+      const healthScore = doccov.summary.health?.score ?? coverageScore;
       if (shouldFix && driftExports.length > 0) {
-        const fixResult = await handleFixes(openpkg, doccov, { isPreview, targetDir }, { log, error });
+        const fixResult = await handleFixes(openpkg, doccov, { isPreview, targetDir, entryFile, healthScore }, { log, error });
         if (!isPreview) {
           driftExports = driftExports.filter((d) => !fixResult.fixedDriftKeys.has(`${d.name}:${d.issue}`));
         }
       }
+      if (shouldFix && doccov.apiSurface?.forgotten.length) {
+        await handleForgottenExportFixes(doccov, { isPreview, targetDir, entryFile }, { log, error });
+      }
       spin.success("Analysis complete");
+      if (options.apiSurface) {
+        displayApiSurfaceOutput(doccov, { log });
+        const apiSurfaceScore = doccov.apiSurface?.completeness ?? 100;
+        if (minApiSurface !== undefined && apiSurfaceScore < minApiSurface) {
+          process.exit(1);
+        }
+        return;
+      }
       if (format !== "text") {
         const passed2 = handleNonTextOutput({
           format,
           openpkg,
           doccov,
           coverageScore,
-          minCoverage,
-          maxDrift,
+          minHealth,
+          minApiSurface,
           driftExports,
           typecheckErrors,
           limit: parseInt(options.limit, 10) || 20,
@@ -2666,14 +2991,16 @@ function registerCheckCommand(program, dependencies = {}) {
         openpkg,
         doccov,
         coverageScore,
-        minCoverage,
-        maxDrift,
+        minHealth,
+        minApiSurface,
+        warnBelowApiSurface,
         driftExports,
         typecheckErrors,
         staleRefs,
         exampleResult,
         specWarnings,
-        specInfos
+        specInfos,
+        verbose: options.verbose ?? false
       }, { log });
       if (!passed) {
         process.exit(1);
@@ -3098,7 +3425,8 @@ function registerInfoCommand(program) {
       const doccov = buildDocCovSpec2({
         openpkg,
         openpkgPath: entryFile,
-        packagePath: targetDir
+        packagePath: targetDir,
+        forgottenExports: specResult.forgottenExports
       });
       const stats = computeStats(openpkg, doccov);
       spin.success("Analysis complete");
@@ -3312,12 +3640,11 @@ import {
   resolveTarget as resolveTarget3
 } from "@doccov/sdk";
 import { validateDocCovSpec } from "@doccov/spec";
-import { normalize, validateSpec } from "@openpkg-ts/spec";
+import {
+  normalize,
+  validateSpec
+} from "@openpkg-ts/spec";
 import chalk11 from "chalk";
-// package.json
-var version = "0.25.9";
-
-// src/commands/spec.ts
 var defaultDependencies4 = {
   createDocCov: (options) => new DocCov3(options),
   writeFileSync: fs6.writeFileSync,
@@ -3371,24 +3698,13 @@ function registerSpecCommand(program, dependencies = {}) {
         cwd: options.cwd,
         schemaExtraction: options.runtime ? "hybrid" : "static"
       });
-      const generationInput = {
-        entryPoint: path8.relative(targetDir, entryFile),
-        entryPointSource: entryPointInfo.source,
-        isDeclarationOnly: entryPointInfo.isDeclarationOnly ?? false,
-        generatorName: "@doccov/cli",
-        generatorVersion: version,
-        packageManager: packageInfo?.packageManager,
-        isMonorepo: resolved.isMonorepo,
-        targetPackage: packageInfo?.name
-      };
       const analyzeOptions = resolvedFilters.include || resolvedFilters.exclude || resolvedFilters.visibility ? {
         filters: {
           include: resolvedFilters.include,
           exclude: resolvedFilters.exclude,
           visibility: resolvedFilters.visibility
-        },
-        generationInput
-      } : { generationInput };
+        }
+      } : {};
       const result = await doccov.analyzeFileWithDiagnostics(entryFile, analyzeOptions);
       if (!result) {
         spin.fail("Generation failed");
@@ -3409,7 +3725,8 @@ function registerSpecCommand(program, dependencies = {}) {
         doccovSpec = buildDocCovSpec3({
           openpkgPath: "openpkg.json",
           openpkg: normalized,
-          packagePath: targetDir
+          packagePath: targetDir,
+          forgottenExports: result.forgottenExports
         });
         const doccovValidation = validateDocCovSpec(doccovSpec);
         if (!doccovValidation.ok) {
@@ -3444,7 +3761,11 @@ function registerSpecCommand(program, dependencies = {}) {
           log(chalk11.gray(`  ${getArrayLength(normalized.types)} types`));
         }
       }
-      const schemaExtraction = normalized.generation?.analysis?.schemaExtraction;
+      const isFullGenerationInfo = (gen) => {
+        return gen !== undefined && "analysis" in gen && "environment" in gen;
+      };
+      const fullGen = isFullGenerationInfo(normalized.generation) ? normalized.generation : undefined;
+      const schemaExtraction = fullGen?.analysis?.schemaExtraction;
       if (options.runtime && (!schemaExtraction?.runtimeCount || schemaExtraction.runtimeCount === 0)) {
         const pm = await detectPackageManager(fileSystem);
         const buildCmd = pm.name === "npm" ? "npm run build" : `${pm.name} run build`;
@@ -3452,21 +3773,20 @@ function registerSpecCommand(program, dependencies = {}) {
         log(chalk11.yellow("⚠ Runtime extraction requested but no schemas extracted."));
         log(chalk11.yellow(`  Ensure project is built (${buildCmd}) and dist/ exists.`));
       }
-      if (options.verbose && normalized.generation) {
-        const gen = normalized.generation;
+      if (options.verbose && fullGen) {
         log("");
         log(chalk11.bold("Generation Info"));
-        log(chalk11.gray(`  Timestamp:        ${gen.timestamp}`));
-        log(chalk11.gray(`  Generator:        ${gen.generator.name}@${gen.generator.version}`));
-        log(chalk11.gray(`  Entry point:      ${gen.analysis.entryPoint}`));
-        log(chalk11.gray(`  Detected via:     ${gen.analysis.entryPointSource}`));
-        log(chalk11.gray(`  Declaration only: ${gen.analysis.isDeclarationOnly ? "yes" : "no"}`));
-        log(chalk11.gray(`  External types:   ${gen.analysis.resolvedExternalTypes ? "resolved" : "skipped"}`));
-        if (gen.analysis.maxTypeDepth) {
-          log(chalk11.gray(`  Max type depth:   ${gen.analysis.maxTypeDepth}`));
+        log(chalk11.gray(`  Timestamp:        ${fullGen.timestamp}`));
+        log(chalk11.gray(`  Generator:        ${fullGen.generator.name}@${fullGen.generator.version}`));
+        log(chalk11.gray(`  Entry point:      ${fullGen.analysis.entryPoint}`));
+        log(chalk11.gray(`  Detected via:     ${fullGen.analysis.entryPointSource}`));
+        log(chalk11.gray(`  Declaration only: ${fullGen.analysis.isDeclarationOnly ? "yes" : "no"}`));
+        log(chalk11.gray(`  External types:   ${fullGen.analysis.resolvedExternalTypes ? "resolved" : "skipped"}`));
+        if (fullGen.analysis.maxTypeDepth) {
+          log(chalk11.gray(`  Max type depth:   ${fullGen.analysis.maxTypeDepth}`));
         }
-        if (gen.analysis.schemaExtraction) {
-          const se = gen.analysis.schemaExtraction;
+        if (fullGen.analysis.schemaExtraction) {
+          const se = fullGen.analysis.schemaExtraction;
           log(chalk11.gray(`  Schema extraction: ${se.method}`));
           if (se.runtimeCount) {
             log(chalk11.gray(`  Runtime schemas:   ${se.runtimeCount} (${se.vendors?.join(", ")})`));
@@ -3474,20 +3794,20 @@ function registerSpecCommand(program, dependencies = {}) {
         }
         log("");
         log(chalk11.bold("Environment"));
-        log(chalk11.gray(`  node_modules:     ${gen.environment.hasNodeModules ? "found" : "not found"}`));
-        if (gen.environment.packageManager) {
-          log(chalk11.gray(`  Package manager:  ${gen.environment.packageManager}`));
+        log(chalk11.gray(`  node_modules:     ${fullGen.environment.hasNodeModules ? "found" : "not found"}`));
+        if (fullGen.environment.packageManager) {
+          log(chalk11.gray(`  Package manager:  ${fullGen.environment.packageManager}`));
         }
-        if (gen.environment.isMonorepo) {
+        if (fullGen.environment.isMonorepo) {
           log(chalk11.gray(`  Monorepo:         yes`));
         }
-        if (gen.environment.targetPackage) {
-          log(chalk11.gray(`  Target package:   ${gen.environment.targetPackage}`));
+        if (fullGen.environment.targetPackage) {
+          log(chalk11.gray(`  Target package:   ${fullGen.environment.targetPackage}`));
         }
-        if (gen.issues.length > 0) {
+        if (fullGen.issues.length > 0) {
           log("");
           log(chalk11.bold("Issues"));
-          for (const issue of gen.issues) {
+          for (const issue of fullGen.issues) {
             const prefix2 = issue.severity === "error" ? chalk11.red(">") : issue.severity === "warning" ? chalk11.yellow(">") : chalk11.cyan(">");
             log(`${prefix2} [${issue.code}] ${issue.message}`);
             if (issue.suggestion) {
@@ -3548,9 +3868,9 @@ function getColorForScore(score) {
 function formatSnapshot(snapshot) {
   const color = getColorForScore(snapshot.coverageScore);
   const date = formatDate(snapshot.timestamp);
-  const version2 = snapshot.version ? ` v${snapshot.version}` : "";
+  const version = snapshot.version ? ` v${snapshot.version}` : "";
   const commit = snapshot.commit ? chalk12.gray(` (${snapshot.commit.slice(0, 7)})`) : "";
-  return `${chalk12.gray(date)}  ${color(`${snapshot.coverageScore}%`)}  ${snapshot.documentedExports}/${snapshot.totalExports} exports${version2}${commit}`;
+  return `${chalk12.gray(date)}  ${color(`${snapshot.coverageScore}%`)}  ${snapshot.documentedExports}/${snapshot.totalExports} exports${version}${commit}`;
 }
 function formatWeekDate(timestamp) {
   const date = new Date(timestamp);

package/dist/config/index.d.ts

@@ -13,12 +13,23 @@ declare const exampleModeSchema: z.ZodEnum<["presence", "typecheck", "run"]>;
 /** Example validation modes - can be single, array, or comma-separated */
 declare const exampleModesSchema: z.ZodUnion<[typeof exampleModeSchema, z.ZodArray<typeof exampleModeSchema>, z.ZodString]>;
 /**
+* API surface configuration schema.
+*/
+declare const apiSurfaceConfigSchema: z.ZodObject<{
+	minCompleteness: z.ZodOptional<z.ZodNumber>;
+	warnBelow: z.ZodOptional<z.ZodNumber>;
+	ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}>;
+/**
 * Check command configuration schema.
 */
 declare const checkConfigSchema: z.ZodObject<{
 	examples: z.ZodOptional<typeof exampleModesSchema>;
+	minHealth: z.ZodOptional<z.ZodNumber>;
 	minCoverage: z.ZodOptional<z.ZodNumber>;
 	maxDrift: z.ZodOptional<z.ZodNumber>;
+	minApiSurface: z.ZodOptional<z.ZodNumber>;
+	apiSurface: z.ZodOptional<typeof apiSurfaceConfigSchema>;
 }>;
 declare const docCovConfigSchema: z.ZodObject<{
 	include: z.ZodOptional<typeof stringList>;

package/dist/config/index.js

@@ -23,10 +23,18 @@ var exampleModesSchema = z.union([
   z.array(exampleModeSchema),
   z.string()
 ]);
+var apiSurfaceConfigSchema = z.object({
+  minCompleteness: z.number().min(0).max(100).optional(),
+  warnBelow: z.number().min(0).max(100).optional(),
+  ignore: z.array(z.string()).optional()
+});
 var checkConfigSchema = z.object({
   examples: exampleModesSchema.optional(),
+  minHealth: z.number().min(0).max(100).optional(),
   minCoverage: z.number().min(0).max(100).optional(),
-  maxDrift: z.number().min(0).max(100).optional()
+  maxDrift: z.number().min(0).max(100).optional(),
+  minApiSurface: z.number().min(0).max(100).optional(),
+  apiSurface: apiSurfaceConfigSchema.optional()
 });
 var docCovConfigSchema = z.object({
   include: stringList.optional(),
@@ -61,8 +69,11 @@ var normalizeConfig = (input) => {
   if (input.check) {
     check = {
       examples: input.check.examples,
+      minHealth: input.check.minHealth,
       minCoverage: input.check.minCoverage,
-      maxDrift: input.check.maxDrift
+      maxDrift: input.check.maxDrift,
+      minApiSurface: input.check.minApiSurface,
+      apiSurface: input.check.apiSurface
     };
   }
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doccov/cli",
-  "version": "0.25.11",
+  "version": "0.27.0",
   "description": "DocCov CLI - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",
@@ -48,8 +48,8 @@
   "dependencies": {
     "@ai-sdk/anthropic": "^1.0.0",
     "@ai-sdk/openai": "^1.0.0",
-    "@doccov/sdk": "^0.25.11",
-    "@doccov/spec": "^0.24.1",
+    "@doccov/sdk": "^0.27.0",
+    "@doccov/spec": "^0.27.0",
     "@inquirer/prompts": "^7.8.0",
     "@openpkg-ts/spec": "^0.12.0",
     "ai": "^4.0.0",