@doccov/cli 0.3.0 → 0.4.0

package/dist/cli.js

@@ -124,18 +124,93 @@ ${formatIssues(issues)}`);
 // src/config/index.ts
 var defineConfig = (config) => config;
 // src/cli.ts
-import { readFileSync as readFileSync8 } from "node:fs";
-import * as path11 from "node:path";
+import { readFileSync as readFileSync9 } from "node:fs";
+import * as path13 from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 
 // src/commands/check.ts
 import * as fs2 from "node:fs";
 import * as path3 from "node:path";
-import { DocCov } from "@doccov/sdk";
+import {
+  DocCov,
+  detectExampleAssertionFailures,
+  detectExampleRuntimeErrors,
+  hasNonAssertionComments,
+  parseAssertions,
+  runExamplesWithPackage
+} from "@doccov/sdk";
 import chalk from "chalk";
 import ora from "ora";
 
+// src/utils/llm-assertion-parser.ts
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAI } from "@ai-sdk/openai";
+import { generateObject } from "ai";
+import { z as z2 } from "zod";
+var AssertionParseSchema = z2.object({
+  assertions: z2.array(z2.object({
+    lineNumber: z2.number().describe("1-indexed line number where the assertion appears"),
+    expected: z2.string().describe("The expected output value"),
+    originalComment: z2.string().describe("The original comment text"),
+    suggestedSyntax: z2.string().describe("The line rewritten with standard // => value syntax")
+  })).describe("List of assertion-like comments found in the code"),
+  hasAssertions: z2.boolean().describe("Whether any assertion-like comments were found")
+});
+var ASSERTION_PARSE_PROMPT = (code) => `Analyze this TypeScript/JavaScript example code for assertion-like comments.
+
+Look for comments that appear to specify expected output values, such as:
+- "// should be 3"
+- "// returns 5"
+- "// outputs: hello"
+- "// expected: [1, 2, 3]"
+- "// 42" (bare value after console.log)
+- "// result: true"
+
+Do NOT include:
+- Regular code comments that explain what the code does
+- Comments that are instructions or documentation
+- Comments with // => (already using standard syntax)
+
+For each assertion found, extract:
+1. The line number (1-indexed)
+2. The expected value (just the value, not the comment prefix)
+3. The original comment text
+4. A suggested rewrite of the ENTIRE line using "// => value" syntax
+
+Code:
+\`\`\`
+${code}
+\`\`\``;
+function getModel() {
+  const provider = process.env.DOCCOV_LLM_PROVIDER?.toLowerCase();
+  if (provider === "anthropic" || process.env.ANTHROPIC_API_KEY) {
+    const anthropic = createAnthropic();
+    return anthropic("claude-sonnet-4-20250514");
+  }
+  const openai = createOpenAI();
+  return openai("gpt-4o-mini");
+}
+function isLLMAssertionParsingAvailable() {
+  return Boolean(process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY);
+}
+async function parseAssertionsWithLLM(code) {
+  if (!isLLMAssertionParsingAvailable()) {
+    return null;
+  }
+  try {
+    const model = getModel();
+    const { object } = await generateObject({
+      model,
+      schema: AssertionParseSchema,
+      prompt: ASSERTION_PARSE_PROMPT(code)
+    });
+    return object;
+  } catch {
+    return null;
+  }
+}
+
 // src/utils/package-utils.ts
 import * as fs from "node:fs";
 import * as path2 from "node:path";
@@ -286,7 +361,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("--ignore-drift", "Do not fail on documentation drift").option("--no-external-types", "Skip external type resolution from node_modules").action(async (entry, options) => {
+  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("--run-examples", "Execute @example blocks and fail on runtime errors").option("--ignore-drift", "Do not fail on documentation drift").option("--skip-resolve", "Skip external type resolution from node_modules").action(async (entry, options) => {
     try {
       let targetDir = options.cwd;
       let entryFile = entry;
@@ -304,12 +379,13 @@ function registerCheckCommand(program, dependencies = {}) {
       } else {
         entryFile = path3.resolve(targetDir, entryFile);
         if (fs2.existsSync(entryFile) && fs2.statSync(entryFile).isDirectory()) {
+          targetDir = entryFile;
           entryFile = await findEntryPoint(entryFile, true);
           log(chalk.gray(`Auto-detected entry point: ${entryFile}`));
         }
       }
       const minCoverage = clampCoverage(options.minCoverage ?? 80);
-      const resolveExternalTypes = options.externalTypes !== false;
+      const resolveExternalTypes = !options.skipResolve;
       const spinnerInstance = spinner("Analyzing documentation coverage...");
       spinnerInstance.start();
       let specResult;
@@ -325,10 +401,129 @@ function registerCheckCommand(program, dependencies = {}) {
         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 runtimeDrifts = [];
+      if (options.runExamples) {
+        const allExamples = [];
+        for (const entry2 of spec.exports ?? []) {
+          if (entry2.examples && entry2.examples.length > 0) {
+            allExamples.push({ exportName: entry2.name, examples: entry2.examples });
+          }
+        }
+        if (allExamples.length === 0) {
+          log(chalk.gray("No @example blocks found"));
+        } else {
+          const examplesSpinner = spinner("Installing package for examples...");
+          examplesSpinner.start();
+          const flatExamples = allExamples.flatMap((e) => e.examples);
+          const packageResult = await runExamplesWithPackage(flatExamples, {
+            packagePath: targetDir,
+            timeout: 5000,
+            installTimeout: 60000,
+            cwd: targetDir
+          });
+          if (!packageResult.installSuccess) {
+            examplesSpinner.fail(`Package install failed: ${packageResult.installError}`);
+            log(chalk.yellow("Skipping example execution. Ensure the package is built."));
+          } else {
+            examplesSpinner.text = "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) {
+              examplesSpinner.fail(`${examplesFailed}/${examplesRun} example(s) failed`);
+            } else {
+              examplesSpinner.succeed(`${examplesRun} example(s) passed`);
+            }
+          }
+        }
+      }
       const coverageScore = spec.docs?.coverageScore ?? 0;
       const failingExports = collectFailingExports(spec.exports ?? [], minCoverage);
       const missingExamples = options.requireExamples ? failingExports.filter((item) => item.missing?.includes("examples")) : [];
-      const driftExports = collectDrift(spec.exports ?? []);
+      const driftExports = [...collectDrift(spec.exports ?? []), ...runtimeDrifts];
       const coverageFailed = coverageScore < minCoverage;
       const hasMissingExamples = missingExamples.length > 0;
       const hasDrift = !options.ignoreDrift && driftExports.length > 0;
@@ -538,16 +733,215 @@ function printTextDiff(diff, log, _error) {
   log("");
 }
 
-// src/commands/generate.ts
+// src/commands/fix.ts
 import * as fs4 from "node:fs";
 import * as path5 from "node:path";
-import { DocCov as DocCov2 } from "@doccov/sdk";
-import { normalize, validateSpec } from "@openpkg-ts/spec";
-import chalk4 from "chalk";
+import {
+  applyEdits,
+  categorizeDrifts,
+  createSourceFile,
+  DocCov as DocCov2,
+  findJSDocLocation,
+  generateFixesForExport,
+  mergeFixes,
+  parseJSDocToPatch,
+  serializeJSDoc
+} from "@doccov/sdk";
+import chalk3 from "chalk";
 import ora2 from "ora";
+var defaultDependencies3 = {
+  createDocCov: (options) => new DocCov2(options),
+  spinner: (text) => ora2(text),
+  log: console.log,
+  error: console.error
+};
+function collectDrifts(exports) {
+  const results = [];
+  for (const exp of exports) {
+    const drifts = exp.docs?.drift ?? [];
+    for (const drift of drifts) {
+      results.push({ export: exp, drift });
+    }
+  }
+  return results;
+}
+function filterDriftsByType(drifts, onlyTypes) {
+  if (!onlyTypes)
+    return drifts;
+  const allowedTypes = new Set(onlyTypes.split(",").map((t) => t.trim()));
+  return drifts.filter((d) => allowedTypes.has(d.drift.type));
+}
+function groupByExport(drifts) {
+  const map = new Map;
+  for (const { export: exp, drift } of drifts) {
+    const existing = map.get(exp) ?? [];
+    existing.push(drift);
+    map.set(exp, existing);
+  }
+  return map;
+}
+function registerFixCommand(program, dependencies = {}) {
+  const { createDocCov, spinner, log, error } = {
+    ...defaultDependencies3,
+    ...dependencies
+  };
+  program.command("fix [entry]").description("Automatically fix documentation drift").option("--cwd <dir>", "Working directory", process.cwd()).option("--package <name>", "Target package name (for monorepos)").option("--dry-run", "Preview changes without writing").option("--only <types>", "Only fix specific drift types (comma-separated)").option("--skip-resolve", "Skip external type resolution from node_modules").action(async (entry, options) => {
+    try {
+      let targetDir = options.cwd;
+      let entryFile = entry;
+      if (options.package) {
+        const packageDir = await findPackageInMonorepo(options.cwd, options.package);
+        if (!packageDir) {
+          throw new Error(`Package "${options.package}" not found in monorepo`);
+        }
+        targetDir = packageDir;
+        log(chalk3.gray(`Found package at ${path5.relative(options.cwd, packageDir)}`));
+      }
+      if (!entryFile) {
+        entryFile = await findEntryPoint(targetDir, true);
+        log(chalk3.gray(`Auto-detected entry point: ${path5.relative(targetDir, entryFile)}`));
+      } else {
+        entryFile = path5.resolve(targetDir, entryFile);
+        if (fs4.existsSync(entryFile) && fs4.statSync(entryFile).isDirectory()) {
+          targetDir = entryFile;
+          entryFile = await findEntryPoint(entryFile, true);
+          log(chalk3.gray(`Auto-detected entry point: ${entryFile}`));
+        }
+      }
+      const resolveExternalTypes = !options.skipResolve;
+      const analyzeSpinner = spinner("Analyzing documentation...");
+      analyzeSpinner.start();
+      const doccov = createDocCov({ resolveExternalTypes });
+      const result = await doccov.analyzeFileWithDiagnostics(entryFile);
+      const spec = result.spec;
+      analyzeSpinner.succeed("Analysis complete");
+      const allDrifts = collectDrifts(spec.exports ?? []);
+      if (allDrifts.length === 0) {
+        log(chalk3.green("No drift issues found. Documentation is in sync!"));
+        return;
+      }
+      const filteredDrifts = filterDriftsByType(allDrifts, options.only);
+      if (filteredDrifts.length === 0) {
+        log(chalk3.yellow("No matching drift issues for the specified types."));
+        return;
+      }
+      const { fixable, nonFixable } = categorizeDrifts(filteredDrifts.map((d) => d.drift));
+      if (fixable.length === 0) {
+        log(chalk3.yellow(`Found ${nonFixable.length} drift issue(s), but none are auto-fixable.`));
+        log(chalk3.gray("Non-fixable drift types require manual intervention:"));
+        for (const drift of nonFixable.slice(0, 5)) {
+          log(chalk3.gray(`  • ${drift.type}: ${drift.issue}`));
+        }
+        return;
+      }
+      log("");
+      log(chalk3.bold(`Found ${fixable.length} fixable issue(s)`));
+      if (nonFixable.length > 0) {
+        log(chalk3.gray(`(${nonFixable.length} non-fixable issue(s) skipped)`));
+      }
+      log("");
+      const groupedDrifts = groupByExport(filteredDrifts.filter((d) => fixable.includes(d.drift)));
+      const edits = [];
+      const editsByFile = new Map;
+      for (const [exp, drifts] of groupedDrifts) {
+        if (!exp.source?.file) {
+          log(chalk3.gray(`  Skipping ${exp.name}: no source location`));
+          continue;
+        }
+        if (exp.source.file.endsWith(".d.ts")) {
+          log(chalk3.gray(`  Skipping ${exp.name}: declaration file`));
+          continue;
+        }
+        const filePath = path5.resolve(targetDir, exp.source.file);
+        if (!fs4.existsSync(filePath)) {
+          log(chalk3.gray(`  Skipping ${exp.name}: file not found`));
+          continue;
+        }
+        const sourceFile = createSourceFile(filePath);
+        const location = findJSDocLocation(sourceFile, exp.name, exp.source.line);
+        if (!location) {
+          log(chalk3.gray(`  Skipping ${exp.name}: could not find declaration`));
+          continue;
+        }
+        let existingPatch = {};
+        if (location.hasExisting && location.existingJSDoc) {
+          existingPatch = parseJSDocToPatch(location.existingJSDoc);
+        }
+        const fixes = generateFixesForExport({ ...exp, docs: { ...exp.docs, drift: drifts } }, existingPatch);
+        if (fixes.length === 0)
+          continue;
+        const mergedPatch = mergeFixes(fixes, existingPatch);
+        const newJSDoc = serializeJSDoc(mergedPatch, location.indent);
+        const edit = {
+          filePath,
+          symbolName: exp.name,
+          startLine: location.startLine,
+          endLine: location.endLine,
+          hasExisting: location.hasExisting,
+          existingJSDoc: location.existingJSDoc,
+          newJSDoc,
+          indent: location.indent
+        };
+        edits.push(edit);
+        const fileEdits = editsByFile.get(filePath) ?? [];
+        fileEdits.push({ export: exp, edit, fixes, existingPatch });
+        editsByFile.set(filePath, fileEdits);
+      }
+      if (edits.length === 0) {
+        log(chalk3.yellow("No edits could be generated."));
+        return;
+      }
+      if (options.dryRun) {
+        log(chalk3.bold("Dry run - changes that would be made:"));
+        log("");
+        for (const [filePath, fileEdits] of editsByFile) {
+          const relativePath = path5.relative(targetDir, filePath);
+          log(chalk3.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(`    ${chalk3.bold(exp.name)} [${lineInfo}]`);
+            for (const fix of fixes) {
+              log(chalk3.green(`      + ${fix.description}`));
+            }
+          }
+          log("");
+        }
+        log(chalk3.gray("Run without --dry-run to apply these changes."));
+      } else {
+        const applySpinner = spinner("Applying fixes...");
+        applySpinner.start();
+        const result2 = await applyEdits(edits);
+        if (result2.errors.length > 0) {
+          applySpinner.warn("Some fixes could not be applied");
+          for (const err of result2.errors) {
+            error(chalk3.red(`  ${err.file}: ${err.error}`));
+          }
+        } else {
+          applySpinner.succeed(`Applied ${result2.editsApplied} fix(es) to ${result2.filesModified} file(s)`);
+        }
+        log("");
+        for (const [filePath, fileEdits] of editsByFile) {
+          const relativePath = path5.relative(targetDir, filePath);
+          log(chalk3.green(`  ✓ ${relativePath}: ${fileEdits.length} fix(es)`));
+        }
+      }
+    } catch (commandError) {
+      error(chalk3.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      process.exitCode = 1;
+    }
+  });
+}
+
+// src/commands/generate.ts
+import * as fs5 from "node:fs";
+import * as path6 from "node:path";
+import { DocCov as DocCov3 } from "@doccov/sdk";
+import { normalize, validateSpec } from "@openpkg-ts/spec";
+import chalk5 from "chalk";
+import ora3 from "ora";
 
 // src/utils/filter-options.ts
-import chalk3 from "chalk";
+import chalk4 from "chalk";
 var unique = (values) => Array.from(new Set(values));
 var parseListFlag = (value) => {
   if (!value) {
@@ -557,7 +951,7 @@ var parseListFlag = (value) => {
   const normalized = rawItems.flatMap((item) => String(item).split(",")).map((item) => item.trim()).filter(Boolean);
   return normalized.length > 0 ? unique(normalized) : undefined;
 };
-var formatList = (label, values) => `${label}: ${values.map((value) => chalk3.cyan(value)).join(", ")}`;
+var formatList = (label, values) => `${label}: ${values.map((value) => chalk4.cyan(value)).join(", ")}`;
 var mergeFilterOptions = (config, cliOptions) => {
   const messages = [];
   const configInclude = config?.include;
@@ -597,10 +991,10 @@ var mergeFilterOptions = (config, cliOptions) => {
 };
 
 // src/commands/generate.ts
-var defaultDependencies3 = {
-  createDocCov: (options) => new DocCov2(options),
-  writeFileSync: fs4.writeFileSync,
-  spinner: (text) => ora2(text),
+var defaultDependencies4 = {
+  createDocCov: (options) => new DocCov3(options),
+  writeFileSync: fs5.writeFileSync,
+  spinner: (text) => ora3(text),
   log: console.log,
   error: console.error
 };
@@ -619,17 +1013,17 @@ function stripDocsFields(spec) {
 }
 function formatDiagnosticOutput(prefix, diagnostic, baseDir) {
   const location = diagnostic.location;
-  const relativePath = location?.file ? path5.relative(baseDir, location.file) || location.file : undefined;
-  const locationText = location && relativePath ? chalk4.gray(`${relativePath}:${location.line ?? 1}:${location.column ?? 1}`) : null;
+  const relativePath = location?.file ? path6.relative(baseDir, location.file) || location.file : undefined;
+  const locationText = location && relativePath ? chalk5.gray(`${relativePath}:${location.line ?? 1}:${location.column ?? 1}`) : null;
   const locationPrefix = locationText ? `${locationText} ` : "";
   return `${prefix} ${locationPrefix}${diagnostic.message}`;
 }
 function registerGenerateCommand(program, dependencies = {}) {
   const { createDocCov, writeFileSync: writeFileSync2, spinner, log, error } = {
-    ...defaultDependencies3,
+    ...defaultDependencies4,
     ...dependencies
   };
-  program.command("generate [entry]").description("Generate OpenPkg specification for documentation coverage analysis").option("-o, --output <file>", "Output file", "openpkg.json").option("-p, --package <name>", "Target package name (for monorepos)").option("--cwd <dir>", "Working directory", process.cwd()).option("--no-external-types", "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("-y, --yes", "Skip all prompts and use defaults").action(async (entry, options) => {
+  program.command("generate [entry]").description("Generate OpenPkg specification for documentation coverage analysis").option("-o, --output <file>", "Output file", "openpkg.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("-y, --yes", "Skip all prompts and use defaults").action(async (entry, options) => {
     try {
       let targetDir = options.cwd;
       let entryFile = entry;
@@ -639,19 +1033,19 @@ function registerGenerateCommand(program, dependencies = {}) {
           throw new Error(`Package "${options.package}" not found in monorepo`);
         }
         targetDir = packageDir;
-        log(chalk4.gray(`Found package at ${path5.relative(options.cwd, packageDir)}`));
+        log(chalk5.gray(`Found package at ${path6.relative(options.cwd, packageDir)}`));
       }
       if (!entryFile) {
         entryFile = await findEntryPoint(targetDir, true);
-        log(chalk4.gray(`Auto-detected entry point: ${path5.relative(targetDir, entryFile)}`));
+        log(chalk5.gray(`Auto-detected entry point: ${path6.relative(targetDir, entryFile)}`));
       } else {
-        entryFile = path5.resolve(targetDir, entryFile);
-        if (fs4.existsSync(entryFile) && fs4.statSync(entryFile).isDirectory()) {
+        entryFile = path6.resolve(targetDir, entryFile);
+        if (fs5.existsSync(entryFile) && fs5.statSync(entryFile).isDirectory()) {
           entryFile = await findEntryPoint(entryFile, true);
-          log(chalk4.gray(`Auto-detected entry point: ${entryFile}`));
+          log(chalk5.gray(`Auto-detected entry point: ${entryFile}`));
         }
       }
-      const resolveExternalTypes = options.externalTypes !== false;
+      const resolveExternalTypes = !options.skipResolve;
       const cliFilters = {
         include: parseListFlag(options.include),
         exclude: parseListFlag(options.exclude)
@@ -660,15 +1054,15 @@ function registerGenerateCommand(program, dependencies = {}) {
       try {
         config = await loadDocCovConfig(targetDir);
         if (config?.filePath) {
-          log(chalk4.gray(`Loaded configuration from ${path5.relative(targetDir, config.filePath)}`));
+          log(chalk5.gray(`Loaded configuration from ${path6.relative(targetDir, config.filePath)}`));
         }
       } catch (configError) {
-        error(chalk4.red("Failed to load DocCov config:"), configError instanceof Error ? configError.message : configError);
+        error(chalk5.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}`));
+        log(chalk5.gray(`• ${message}`));
       }
       const spinnerInstance = spinner("Generating OpenPkg spec...");
       spinnerInstance.start();
@@ -692,7 +1086,7 @@ function registerGenerateCommand(program, dependencies = {}) {
       if (!result) {
         throw new Error("Failed to produce an OpenPkg spec.");
       }
-      const outputPath = path5.resolve(process.cwd(), options.output);
+      const outputPath = path6.resolve(process.cwd(), options.output);
       let normalized = normalize(result.spec);
       if (options.docs === false) {
         normalized = stripDocsFields(normalized);
@@ -701,85 +1095,85 @@ function registerGenerateCommand(program, dependencies = {}) {
       if (!validation.ok) {
         spinnerInstance.fail("Spec failed schema validation");
         for (const err of validation.errors) {
-          error(chalk4.red(`schema: ${err.instancePath || "/"} ${err.message}`));
+          error(chalk5.red(`schema: ${err.instancePath || "/"} ${err.message}`));
         }
         process.exit(1);
       }
       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`));
+      log(chalk5.green(`✓ Generated ${options.output}`));
+      log(chalk5.gray(`  ${getArrayLength(normalized.exports)} exports`));
+      log(chalk5.gray(`  ${getArrayLength(normalized.types)} types`));
       if (options.showDiagnostics && result.diagnostics.length > 0) {
         log("");
-        log(chalk4.bold("Diagnostics"));
+        log(chalk5.bold("Diagnostics"));
         for (const diagnostic of result.diagnostics) {
-          const prefix = diagnostic.severity === "error" ? chalk4.red("✖") : diagnostic.severity === "warning" ? chalk4.yellow("⚠") : chalk4.cyan("ℹ");
+          const prefix = diagnostic.severity === "error" ? chalk5.red("✖") : diagnostic.severity === "warning" ? chalk5.yellow("⚠") : chalk5.cyan("ℹ");
           log(formatDiagnosticOutput(prefix, diagnostic, targetDir));
         }
       }
     } catch (commandError) {
-      error(chalk4.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      error(chalk5.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
       process.exit(1);
     }
   });
 }
 
 // src/commands/init.ts
-import * as fs5 from "node:fs";
-import * as path6 from "node:path";
-import chalk5 from "chalk";
-var defaultDependencies4 = {
-  fileExists: fs5.existsSync,
-  writeFileSync: fs5.writeFileSync,
-  readFileSync: fs5.readFileSync,
+import * as fs6 from "node:fs";
+import * as path7 from "node:path";
+import chalk6 from "chalk";
+var defaultDependencies5 = {
+  fileExists: fs6.existsSync,
+  writeFileSync: fs6.writeFileSync,
+  readFileSync: fs6.readFileSync,
   log: console.log,
   error: console.error
 };
 function registerInitCommand(program, dependencies = {}) {
   const { fileExists: fileExists2, writeFileSync: writeFileSync3, readFileSync: readFileSync4, log, error } = {
-    ...defaultDependencies4,
+    ...defaultDependencies5,
     ...dependencies
   };
   program.command("init").description("Create a DocCov configuration file").option("--cwd <dir>", "Working directory", process.cwd()).option("--format <format>", "Config format: auto, mjs, js, cjs", "auto").action((options) => {
-    const cwd = path6.resolve(options.cwd);
+    const cwd = path7.resolve(options.cwd);
     const formatOption = String(options.format ?? "auto").toLowerCase();
     if (!isValidFormat(formatOption)) {
-      error(chalk5.red(`Invalid format "${formatOption}". Use auto, mjs, js, or cjs.`));
+      error(chalk6.red(`Invalid format "${formatOption}". Use auto, mjs, js, or cjs.`));
       process.exitCode = 1;
       return;
     }
     const existing = findExistingConfig(cwd, fileExists2);
     if (existing) {
-      error(chalk5.red(`A DocCov config already exists at ${path6.relative(cwd, existing) || "./doccov.config.*"}.`));
+      error(chalk6.red(`A DocCov config already exists at ${path7.relative(cwd, existing) || "./doccov.config.*"}.`));
       process.exitCode = 1;
       return;
     }
     const packageType = detectPackageType(cwd, fileExists2, readFileSync4);
     const targetFormat = resolveFormat(formatOption, packageType);
     if (targetFormat === "js" && packageType !== "module") {
-      log(chalk5.yellow('Package is not marked as "type": "module"; creating doccov.config.js may require enabling ESM.'));
+      log(chalk6.yellow('Package is not marked as "type": "module"; creating doccov.config.js may require enabling ESM.'));
     }
     const fileName = `doccov.config.${targetFormat}`;
-    const outputPath = path6.join(cwd, fileName);
+    const outputPath = path7.join(cwd, fileName);
     if (fileExists2(outputPath)) {
-      error(chalk5.red(`Cannot create ${fileName}; file already exists.`));
+      error(chalk6.red(`Cannot create ${fileName}; file already exists.`));
       process.exitCode = 1;
       return;
     }
     const template = buildTemplate(targetFormat);
     writeFileSync3(outputPath, template, { encoding: "utf8" });
-    log(chalk5.green(`✓ Created ${path6.relative(process.cwd(), outputPath)}`));
+    log(chalk6.green(`✓ Created ${path7.relative(process.cwd(), outputPath)}`));
   });
 }
 var isValidFormat = (value) => {
   return value === "auto" || value === "mjs" || value === "js" || value === "cjs";
 };
 var findExistingConfig = (cwd, fileExists2) => {
-  let current = path6.resolve(cwd);
-  const { root } = path6.parse(current);
+  let current = path7.resolve(cwd);
+  const { root } = path7.parse(current);
   while (true) {
     for (const candidate of DOCCOV_CONFIG_FILENAMES) {
-      const candidatePath = path6.join(current, candidate);
+      const candidatePath = path7.join(current, candidate);
       if (fileExists2(candidatePath)) {
         return candidatePath;
       }
@@ -787,7 +1181,7 @@ var findExistingConfig = (cwd, fileExists2) => {
     if (current === root) {
       break;
     }
-    current = path6.dirname(current);
+    current = path7.dirname(current);
   }
   return null;
 };
@@ -809,17 +1203,17 @@ var detectPackageType = (cwd, fileExists2, readFileSync4) => {
   return;
 };
 var findNearestPackageJson = (cwd, fileExists2) => {
-  let current = path6.resolve(cwd);
-  const { root } = path6.parse(current);
+  let current = path7.resolve(cwd);
+  const { root } = path7.parse(current);
   while (true) {
-    const candidate = path6.join(current, "package.json");
+    const candidate = path7.join(current, "package.json");
     if (fileExists2(candidate)) {
       return candidate;
     }
     if (current === root) {
       break;
     }
-    current = path6.dirname(current);
+    current = path7.dirname(current);
   }
   return null;
 };
@@ -854,26 +1248,256 @@ var buildTemplate = (format) => {
 `);
 };
 
+// src/commands/report.ts
+import * as fs7 from "node:fs";
+import * as path8 from "node:path";
+import { DocCov as DocCov4 } from "@doccov/sdk";
+import chalk7 from "chalk";
+import ora4 from "ora";
+
+// 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/commands/report.ts
+function registerReportCommand(program) {
+  program.command("report [entry]").description("Generate a documentation coverage report").option("--cwd <dir>", "Working directory", process.cwd()).option("--package <name>", "Target package name (for monorepos)").option("--spec <file>", "Use existing openpkg.json instead of analyzing").option("--output <format>", "Output format: markdown, html, json", "markdown").option("--out <file>", "Write to file instead of stdout").option("--limit <n>", "Max exports to show in tables", "20").option("--skip-resolve", "Skip external type resolution from node_modules").action(async (entry, options) => {
+    try {
+      let spec;
+      if (options.spec) {
+        const specPath = path8.resolve(options.cwd, options.spec);
+        spec = JSON.parse(fs7.readFileSync(specPath, "utf-8"));
+      } else {
+        let targetDir = options.cwd;
+        let entryFile = entry;
+        if (options.package) {
+          const packageDir = await findPackageInMonorepo(options.cwd, options.package);
+          if (!packageDir)
+            throw new Error(`Package "${options.package}" not found`);
+          targetDir = packageDir;
+        }
+        if (!entryFile) {
+          entryFile = await findEntryPoint(targetDir, true);
+        } else {
+          entryFile = path8.resolve(targetDir, entryFile);
+        }
+        const spinner = ora4("Analyzing...").start();
+        const resolveExternalTypes = !options.skipResolve;
+        const doccov = new DocCov4({ resolveExternalTypes });
+        const result = await doccov.analyzeFileWithDiagnostics(entryFile);
+        spinner.succeed("Analysis complete");
+        spec = result.spec;
+      }
+      const stats = computeStats(spec);
+      const format = options.output;
+      const limit = parseInt(options.limit, 10) || 20;
+      let output;
+      if (format === "json") {
+        output = JSON.stringify(stats, null, 2);
+      } else if (format === "html") {
+        output = renderHtml(stats, { limit });
+      } else {
+        output = renderMarkdown(stats, { limit });
+      }
+      if (options.out) {
+        const outPath = path8.resolve(options.cwd, options.out);
+        fs7.writeFileSync(outPath, output);
+        console.log(chalk7.green(`Report written to ${outPath}`));
+      } else {
+        console.log(output);
+      }
+    } catch (err) {
+      console.error(chalk7.red("Error:"), err instanceof Error ? err.message : err);
+      process.exitCode = 1;
+    }
+  });
+}
+
 // src/commands/scan.ts
-import * as fs9 from "node:fs";
+import * as fs11 from "node:fs";
 import * as os from "node:os";
-import * as path10 from "node:path";
-import { DocCov as DocCov3 } from "@doccov/sdk";
-import chalk6 from "chalk";
-import ora3 from "ora";
+import * as path12 from "node:path";
+import { DocCov as DocCov5 } from "@doccov/sdk";
+import chalk8 from "chalk";
+import ora5 from "ora";
 import { simpleGit } from "simple-git";
 
 // src/utils/entry-detection.ts
-import * as fs6 from "node:fs";
-import * as path7 from "node:path";
+import * as fs8 from "node:fs";
+import * as path9 from "node:path";
 function detectEntryPoint(repoDir) {
-  const pkgPath = path7.join(repoDir, "package.json");
-  if (!fs6.existsSync(pkgPath)) {
+  const pkgPath = path9.join(repoDir, "package.json");
+  if (!fs8.existsSync(pkgPath)) {
     throw new Error("No package.json found - not a valid npm package");
   }
   let pkg;
   try {
-    pkg = JSON.parse(fs6.readFileSync(pkgPath, "utf-8"));
+    pkg = JSON.parse(fs8.readFileSync(pkgPath, "utf-8"));
   } catch {
     throw new Error("Failed to parse package.json");
   }
@@ -923,7 +1547,7 @@ function detectEntryPoint(repoDir) {
     "source/index.ts"
   ];
   for (const p of commonPaths) {
-    if (fs6.existsSync(path7.join(repoDir, p))) {
+    if (fs8.existsSync(path9.join(repoDir, p))) {
       return { entryPath: p, source: "fallback" };
     }
   }
@@ -932,7 +1556,7 @@ function detectEntryPoint(repoDir) {
 function resolveToTs(baseDir, filePath) {
   const normalized = filePath.replace(/^\.\//, "");
   if (normalized.endsWith(".ts") || normalized.endsWith(".tsx")) {
-    if (fs6.existsSync(path7.join(baseDir, normalized))) {
+    if (fs8.existsSync(path9.join(baseDir, normalized))) {
       return normalized;
     }
   }
@@ -957,11 +1581,11 @@ function resolveToTs(baseDir, filePath) {
   candidates.push(normalized.replace(/\.d\.ts$/, ".ts"));
   candidates.push(normalized.replace(/\.js$/, ".tsx"));
   if (normalized.endsWith(".d.ts")) {
-    const baseName = path7.basename(normalized, ".d.ts");
+    const baseName = path9.basename(normalized, ".d.ts");
     candidates.push(`src/${baseName}.ts`);
   }
   for (const candidate of candidates) {
-    if (fs6.existsSync(path7.join(baseDir, candidate))) {
+    if (fs8.existsSync(path9.join(baseDir, candidate))) {
       return candidate;
     }
   }
@@ -999,17 +1623,17 @@ function buildDisplayUrl(parsed) {
 }
 
 // src/utils/llm-build-plan.ts
-import * as fs7 from "node:fs";
-import * as path8 from "node:path";
-import { createAnthropic } from "@ai-sdk/anthropic";
-import { createOpenAI } from "@ai-sdk/openai";
-import { generateObject } from "ai";
-import { z as z2 } from "zod";
-var BuildPlanSchema = z2.object({
-  installCommand: z2.string().optional().describe("Additional install command if needed"),
-  buildCommands: z2.array(z2.string()).describe('Build steps to run, e.g. ["npm run build:wasm"]'),
-  entryPoint: z2.string().describe("Path to TS/TSX entry file after build"),
-  notes: z2.string().optional().describe("Caveats or warnings")
+import * as fs9 from "node:fs";
+import * as path10 from "node:path";
+import { createAnthropic as createAnthropic2 } from "@ai-sdk/anthropic";
+import { createOpenAI as createOpenAI2 } from "@ai-sdk/openai";
+import { generateObject as generateObject2 } from "ai";
+import { z as z3 } from "zod";
+var BuildPlanSchema = z3.object({
+  installCommand: z3.string().optional().describe("Additional install command if needed"),
+  buildCommands: z3.array(z3.string()).describe('Build steps to run, e.g. ["npm run build:wasm"]'),
+  entryPoint: z3.string().describe("Path to TS/TSX entry file after build"),
+  notes: z3.string().optional().describe("Caveats or warnings")
 });
 var CONTEXT_FILES = [
   "package.json",
@@ -1024,22 +1648,22 @@ var CONTEXT_FILES = [
   "wasm-pack.json"
 ];
 var MAX_FILE_CHARS = 2000;
-function getModel() {
+function getModel2() {
   const provider = process.env.DOCCOV_LLM_PROVIDER?.toLowerCase();
   if (provider === "anthropic" || process.env.ANTHROPIC_API_KEY) {
-    const anthropic = createAnthropic();
+    const anthropic = createAnthropic2();
     return anthropic("claude-sonnet-4-20250514");
   }
-  const openai = createOpenAI();
+  const openai = createOpenAI2();
   return openai("gpt-4o-mini");
 }
 async function gatherContextFiles(repoDir) {
   const sections = [];
   for (const fileName of CONTEXT_FILES) {
-    const filePath = path8.join(repoDir, fileName);
-    if (fs7.existsSync(filePath)) {
+    const filePath = path10.join(repoDir, fileName);
+    if (fs9.existsSync(filePath)) {
       try {
-        let content = fs7.readFileSync(filePath, "utf-8");
+        let content = fs9.readFileSync(filePath, "utf-8");
         if (content.length > MAX_FILE_CHARS) {
           content = `${content.slice(0, MAX_FILE_CHARS)}
 ... (truncated)`;
@@ -1081,8 +1705,8 @@ async function generateBuildPlan(repoDir) {
   if (!context.trim()) {
     return null;
   }
-  const model = getModel();
-  const { object } = await generateObject({
+  const model = getModel2();
+  const { object } = await generateObject2({
     model,
     schema: BuildPlanSchema,
     prompt: BUILD_PLAN_PROMPT(context)
@@ -1091,17 +1715,17 @@ async function generateBuildPlan(repoDir) {
 }
 
 // src/utils/monorepo-detection.ts
-import * as fs8 from "node:fs";
-import * as path9 from "node:path";
+import * as fs10 from "node:fs";
+import * as path11 from "node:path";
 import { glob } from "glob";
 async function detectMonorepo(repoDir) {
-  const pkgPath = path9.join(repoDir, "package.json");
-  if (!fs8.existsSync(pkgPath)) {
+  const pkgPath = path11.join(repoDir, "package.json");
+  if (!fs10.existsSync(pkgPath)) {
     return { isMonorepo: false, packages: [], type: "none" };
   }
   let pkg;
   try {
-    pkg = JSON.parse(fs8.readFileSync(pkgPath, "utf-8"));
+    pkg = JSON.parse(fs10.readFileSync(pkgPath, "utf-8"));
   } catch {
     return { isMonorepo: false, packages: [], type: "none" };
   }
@@ -1110,16 +1734,16 @@ async function detectMonorepo(repoDir) {
     const packages = await resolveWorkspacePackages(repoDir, patterns);
     return { isMonorepo: packages.length > 0, packages, type: "npm" };
   }
-  const pnpmPath = path9.join(repoDir, "pnpm-workspace.yaml");
-  if (fs8.existsSync(pnpmPath)) {
+  const pnpmPath = path11.join(repoDir, "pnpm-workspace.yaml");
+  if (fs10.existsSync(pnpmPath)) {
     const patterns = parsePnpmWorkspace(pnpmPath);
     const packages = await resolveWorkspacePackages(repoDir, patterns);
     return { isMonorepo: packages.length > 0, packages, type: "pnpm" };
   }
-  const lernaPath = path9.join(repoDir, "lerna.json");
-  if (fs8.existsSync(lernaPath)) {
+  const lernaPath = path11.join(repoDir, "lerna.json");
+  if (fs10.existsSync(lernaPath)) {
     try {
-      const lerna = JSON.parse(fs8.readFileSync(lernaPath, "utf-8"));
+      const lerna = JSON.parse(fs10.readFileSync(lernaPath, "utf-8"));
       const patterns = lerna.packages ?? ["packages/*"];
       const packages = await resolveWorkspacePackages(repoDir, patterns);
       return { isMonorepo: packages.length > 0, packages, type: "lerna" };
@@ -1141,7 +1765,7 @@ function extractWorkspacePatterns(workspaces) {
 }
 function parsePnpmWorkspace(filePath) {
   try {
-    const content = fs8.readFileSync(filePath, "utf-8");
+    const content = fs10.readFileSync(filePath, "utf-8");
     const match = content.match(/packages:\s*\n((?:\s+-\s+.+\n?)+)/);
     if (match) {
       const lines = match[1].split(`
@@ -1161,13 +1785,13 @@ async function resolveWorkspacePackages(repoDir, patterns) {
         absolute: false
       });
       for (const match of matches) {
-        const pkgJsonPath = path9.join(repoDir, match, "package.json");
-        if (fs8.existsSync(pkgJsonPath)) {
+        const pkgJsonPath = path11.join(repoDir, match, "package.json");
+        if (fs10.existsSync(pkgJsonPath)) {
           try {
-            const pkgJson = JSON.parse(fs8.readFileSync(pkgJsonPath, "utf-8"));
+            const pkgJson = JSON.parse(fs10.readFileSync(pkgJsonPath, "utf-8"));
             packages.push({
-              name: pkgJson.name ?? path9.basename(match),
-              path: path9.join(repoDir, match),
+              name: pkgJson.name ?? path11.basename(match),
+              path: path11.join(repoDir, match),
               relativePath: match
             });
           } catch {}
@@ -1194,29 +1818,29 @@ function formatPackageList(packages, limit = 10) {
 }
 
 // src/commands/scan.ts
-var defaultDependencies5 = {
-  createDocCov: (options) => new DocCov3(options),
-  spinner: (text) => ora3(text),
+var defaultDependencies6 = {
+  createDocCov: (options) => new DocCov5(options),
+  spinner: (text) => ora5(text),
   log: console.log,
   error: console.error
 };
 function registerScanCommand(program, dependencies = {}) {
   const { createDocCov, spinner, log, error } = {
-    ...defaultDependencies5,
+    ...defaultDependencies6,
     ...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("--save-spec <path>", "Save full OpenPkg spec to file").action(async (url, options) => {
+  program.command("scan <url>").description("Analyze docs coverage for any public GitHub repository").option("--ref <branch>", "Branch or tag to analyze").option("--package <name>", "Target package in monorepo").option("--output <format>", "Output format: text or json", "text").option("--no-cleanup", "Keep cloned repo (for debugging)").option("--skip-install", "Skip dependency installation (faster, but may limit type resolution)").option("--skip-resolve", "Skip external type resolution from node_modules").option("--save-spec <path>", "Save full OpenPkg spec to file").action(async (url, options) => {
     let tempDir;
     try {
       const parsed = parseGitHubUrl(url, options.ref ?? "main");
       const cloneUrl = buildCloneUrl(parsed);
       const displayUrl = buildDisplayUrl(parsed);
       log("");
-      log(chalk6.bold(`Scanning ${displayUrl}`));
-      log(chalk6.gray(`Branch/tag: ${parsed.ref}`));
+      log(chalk8.bold(`Scanning ${displayUrl}`));
+      log(chalk8.gray(`Branch/tag: ${parsed.ref}`));
       log("");
-      tempDir = path10.join(os.tmpdir(), `doccov-scan-${Date.now()}-${Math.random().toString(36).slice(2)}`);
-      fs9.mkdirSync(tempDir, { recursive: true });
+      tempDir = path12.join(os.tmpdir(), `doccov-scan-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+      fs11.mkdirSync(tempDir, { recursive: true });
       const cloneSpinner = spinner(`Cloning ${parsed.owner}/${parsed.repo}...`);
       cloneSpinner.start();
       try {
@@ -1241,7 +1865,7 @@ function registerScanCommand(program, dependencies = {}) {
         throw new Error(`Clone failed: ${message}`);
       }
       if (options.skipInstall) {
-        log(chalk6.gray("Skipping dependency installation (--skip-install)"));
+        log(chalk8.gray("Skipping dependency installation (--skip-install)"));
       } else {
         const installSpinner = spinner("Installing dependencies...");
         installSpinner.start();
@@ -1257,7 +1881,7 @@ function registerScanCommand(program, dependencies = {}) {
           ];
           let installed = false;
           for (const { file, cmd } of lockfileCommands) {
-            if (fs9.existsSync(path10.join(tempDir, file))) {
+            if (fs11.existsSync(path12.join(tempDir, file))) {
               try {
                 execSync(cmd, {
                   cwd: tempDir,
@@ -1304,14 +1928,14 @@ function registerScanCommand(program, dependencies = {}) {
           } else {
             installSpinner.warn("Could not install dependencies (analysis may be limited)");
             for (const err of installErrors) {
-              log(chalk6.gray(`  ${err}`));
+              log(chalk8.gray(`  ${err}`));
             }
           }
         } catch (outerError) {
           const msg = outerError instanceof Error ? outerError.message : String(outerError);
           installSpinner.warn(`Could not install dependencies: ${msg.slice(0, 100)}`);
           for (const err of installErrors) {
-            log(chalk6.gray(`  ${err}`));
+            log(chalk8.gray(`  ${err}`));
           }
         }
       }
@@ -1321,7 +1945,7 @@ function registerScanCommand(program, dependencies = {}) {
       if (mono.isMonorepo) {
         if (!options.package) {
           error("");
-          error(chalk6.red(`Monorepo detected with ${mono.packages.length} packages. Specify target with --package:`));
+          error(chalk8.red(`Monorepo detected with ${mono.packages.length} packages. Specify target with --package:`));
           error("");
           error(formatPackageList(mono.packages));
           error("");
@@ -1330,7 +1954,7 @@ function registerScanCommand(program, dependencies = {}) {
         const pkg = await findPackage(tempDir, options.package);
         if (!pkg) {
           error("");
-          error(chalk6.red(`Package "${options.package}" not found. Available packages:`));
+          error(chalk8.red(`Package "${options.package}" not found. Available packages:`));
           error("");
           error(formatPackageList(mono.packages));
           error("");
@@ -1338,7 +1962,7 @@ function registerScanCommand(program, dependencies = {}) {
         }
         targetDir = pkg.path;
         packageName = pkg.name;
-        log(chalk6.gray(`Analyzing package: ${packageName}`));
+        log(chalk8.gray(`Analyzing package: ${packageName}`));
       }
       const entrySpinner = spinner("Detecting entry point...");
       entrySpinner.start();
@@ -1347,15 +1971,15 @@ function registerScanCommand(program, dependencies = {}) {
         if (!entryFile.endsWith(".d.ts"))
           return false;
         const cargoLocations = [
-          path10.join(pkgDir, "Cargo.toml"),
-          path10.join(repoRoot, "Cargo.toml")
+          path12.join(pkgDir, "Cargo.toml"),
+          path12.join(repoRoot, "Cargo.toml")
         ];
-        const hasCargoToml = cargoLocations.some((p) => fs9.existsSync(p));
+        const hasCargoToml = cargoLocations.some((p) => fs11.existsSync(p));
         const checkWasmScripts = (dir) => {
-          const pkgPath = path10.join(dir, "package.json");
-          if (fs9.existsSync(pkgPath)) {
+          const pkgPath = path12.join(dir, "package.json");
+          if (fs11.existsSync(pkgPath)) {
             try {
-              const pkg = JSON.parse(fs9.readFileSync(pkgPath, "utf-8"));
+              const pkg = JSON.parse(fs11.readFileSync(pkgPath, "utf-8"));
               const scripts = Object.values(pkg.scripts ?? {}).join(" ");
               return scripts.includes("wasm-pack") || scripts.includes("wasm");
             } catch {}
@@ -1375,24 +1999,24 @@ function registerScanCommand(program, dependencies = {}) {
         if (plan.buildCommands.length > 0) {
           const { execSync } = await import("node:child_process");
           for (const cmd of plan.buildCommands) {
-            log(chalk6.gray(`  Running: ${cmd}`));
+            log(chalk8.gray(`  Running: ${cmd}`));
             try {
               execSync(cmd, { cwd: targetDir, stdio: "pipe", timeout: 300000 });
             } catch (buildError) {
               buildFailed = true;
               const msg = buildError instanceof Error ? buildError.message : String(buildError);
               if (msg.includes("rustc") || msg.includes("cargo") || msg.includes("wasm-pack")) {
-                log(chalk6.yellow(`  ⚠ Build requires Rust toolchain (not available)`));
+                log(chalk8.yellow(`  ⚠ Build requires Rust toolchain (not available)`));
               } else if (msg.includes("rimraf") || msg.includes("command not found")) {
-                log(chalk6.yellow(`  ⚠ Build failed: missing dependencies`));
+                log(chalk8.yellow(`  ⚠ Build failed: missing dependencies`));
               } else {
-                log(chalk6.yellow(`  ⚠ Build failed: ${msg.slice(0, 80)}`));
+                log(chalk8.yellow(`  ⚠ Build failed: ${msg.slice(0, 80)}`));
               }
             }
           }
         }
         if (plan.notes) {
-          log(chalk6.gray(`  Note: ${plan.notes}`));
+          log(chalk8.gray(`  Note: ${plan.notes}`));
         }
         return plan.entryPoint;
       };
@@ -1402,26 +2026,26 @@ function registerScanCommand(program, dependencies = {}) {
           entrySpinner.text = "Detected .d.ts entry with WASM indicators...";
           const llmEntry = await runLlmFallback("WASM project detected");
           if (llmEntry) {
-            entryPath = path10.join(targetDir, llmEntry);
+            entryPath = path12.join(targetDir, llmEntry);
             if (buildFailed) {
               entrySpinner.succeed(`Entry point: ${llmEntry} (using pre-committed declarations)`);
-              log(chalk6.gray("  Coverage may be limited - generated .d.ts files typically lack JSDoc"));
+              log(chalk8.gray("  Coverage may be limited - generated .d.ts files typically lack JSDoc"));
             } else {
               entrySpinner.succeed(`Entry point: ${llmEntry} (from LLM fallback - WASM project)`);
             }
           } else {
-            entryPath = path10.join(targetDir, entry.entryPath);
+            entryPath = path12.join(targetDir, entry.entryPath);
             entrySpinner.succeed(`Entry point: ${entry.entryPath} (from ${entry.source})`);
-            log(chalk6.yellow("  ⚠ WASM project detected but no API key - analysis may be limited"));
+            log(chalk8.yellow("  ⚠ WASM project detected but no API key - analysis may be limited"));
           }
         } else {
-          entryPath = path10.join(targetDir, entry.entryPath);
+          entryPath = path12.join(targetDir, entry.entryPath);
           entrySpinner.succeed(`Entry point: ${entry.entryPath} (from ${entry.source})`);
         }
       } catch (entryError) {
         const llmEntry = await runLlmFallback("Heuristics failed");
         if (llmEntry) {
-          entryPath = path10.join(targetDir, llmEntry);
+          entryPath = path12.join(targetDir, llmEntry);
           entrySpinner.succeed(`Entry point: ${llmEntry} (from LLM fallback)`);
         } else {
           entrySpinner.fail("Could not detect entry point (set OPENAI_API_KEY for smart fallback)");
@@ -1432,7 +2056,8 @@ function registerScanCommand(program, dependencies = {}) {
       analyzeSpinner.start();
       let result;
       try {
-        const doccov = createDocCov({ resolveExternalTypes: true });
+        const resolveExternalTypes = !options.skipResolve;
+        const doccov = createDocCov({ resolveExternalTypes });
         result = await doccov.analyzeFileWithDiagnostics(entryPath);
         analyzeSpinner.succeed("Analysis complete");
       } catch (analysisError) {
@@ -1442,9 +2067,9 @@ function registerScanCommand(program, dependencies = {}) {
       const spec = result.spec;
       const coverageScore = spec.docs?.coverageScore ?? 0;
       if (options.saveSpec) {
-        const specPath = path10.resolve(process.cwd(), options.saveSpec);
-        fs9.writeFileSync(specPath, JSON.stringify(spec, null, 2));
-        log(chalk6.green(`✓ Saved spec to ${options.saveSpec}`));
+        const specPath = path12.resolve(process.cwd(), options.saveSpec);
+        fs11.writeFileSync(specPath, JSON.stringify(spec, null, 2));
+        log(chalk8.green(`✓ Saved spec to ${options.saveSpec}`));
       }
       const undocumented = [];
       const driftIssues = [];
@@ -1481,7 +2106,7 @@ function registerScanCommand(program, dependencies = {}) {
         printTextResult(scanResult, log);
       }
     } catch (commandError) {
-      error(chalk6.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      error(chalk8.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
       process.exitCode = 1;
     } finally {
       if (tempDir && options.cleanup !== false) {
@@ -1491,46 +2116,46 @@ function registerScanCommand(program, dependencies = {}) {
           stdio: "ignore"
         }).unref();
       } else if (tempDir) {
-        log(chalk6.gray(`Repo preserved at: ${tempDir}`));
+        log(chalk8.gray(`Repo preserved at: ${tempDir}`));
       }
     }
   });
 }
 function printTextResult(result, log) {
   log("");
-  log(chalk6.bold("DocCov Scan Results"));
+  log(chalk8.bold("DocCov Scan Results"));
   log("─".repeat(40));
   const repoName = result.packageName ? `${result.owner}/${result.repo} (${result.packageName})` : `${result.owner}/${result.repo}`;
-  log(`Repository: ${chalk6.cyan(repoName)}`);
-  log(`Branch: ${chalk6.gray(result.ref)}`);
+  log(`Repository: ${chalk8.cyan(repoName)}`);
+  log(`Branch: ${chalk8.gray(result.ref)}`);
   log("");
-  const coverageColor = result.coverage >= 80 ? chalk6.green : result.coverage >= 50 ? chalk6.yellow : chalk6.red;
-  log(chalk6.bold("Coverage"));
+  const coverageColor = result.coverage >= 80 ? chalk8.green : result.coverage >= 50 ? chalk8.yellow : chalk8.red;
+  log(chalk8.bold("Coverage"));
   log(`  ${coverageColor(`${result.coverage}%`)}`);
   log("");
-  log(chalk6.bold("Stats"));
+  log(chalk8.bold("Stats"));
   log(`  ${result.exportCount} exports`);
   log(`  ${result.typeCount} types`);
   log(`  ${result.undocumented.length} undocumented`);
   log(`  ${result.driftCount} drift issues`);
   if (result.undocumented.length > 0) {
     log("");
-    log(chalk6.bold("Undocumented Exports"));
+    log(chalk8.bold("Undocumented Exports"));
     for (const name of result.undocumented.slice(0, 10)) {
-      log(chalk6.yellow(`  ! ${name}`));
+      log(chalk8.yellow(`  ! ${name}`));
     }
     if (result.undocumented.length > 10) {
-      log(chalk6.gray(`  ... and ${result.undocumented.length - 10} more`));
+      log(chalk8.gray(`  ... and ${result.undocumented.length - 10} more`));
     }
   }
   if (result.drift.length > 0) {
     log("");
-    log(chalk6.bold("Drift Issues"));
+    log(chalk8.bold("Drift Issues"));
     for (const d of result.drift.slice(0, 5)) {
-      log(chalk6.red(`  • ${d.export}: ${d.issue}`));
+      log(chalk8.red(`  • ${d.export}: ${d.issue}`));
     }
     if (result.drift.length > 5) {
-      log(chalk6.gray(`  ... and ${result.drift.length - 5} more`));
+      log(chalk8.gray(`  ... and ${result.drift.length - 5} more`));
     }
   }
   log("");
@@ -1538,14 +2163,16 @@ function printTextResult(result, log) {
 
 // src/cli.ts
 var __filename2 = fileURLToPath(import.meta.url);
-var __dirname2 = path11.dirname(__filename2);
-var packageJson = JSON.parse(readFileSync8(path11.join(__dirname2, "../package.json"), "utf-8"));
+var __dirname2 = path13.dirname(__filename2);
+var packageJson = JSON.parse(readFileSync9(path13.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);
 registerDiffCommand(program);
+registerFixCommand(program);
 registerInitCommand(program);
+registerReportCommand(program);
 registerScanCommand(program);
 program.command("*", { hidden: true }).action(() => {
   program.outputHelp();