@doccov/cli 0.5.6 → 0.5.8

package/dist/cli.js

@@ -33,11 +33,22 @@ var docsConfigSchema = z.object({
   include: stringList.optional(),
   exclude: stringList.optional()
 });
+var lintSeveritySchema = z.enum(["error", "warn", "off"]);
+var checkConfigSchema = z.object({
+  lint: z.boolean().optional(),
+  typecheck: z.boolean().optional(),
+  exec: z.boolean().optional()
+});
+var lintConfigSchema = z.object({
+  rules: z.record(lintSeveritySchema).optional()
+});
 var docCovConfigSchema = z.object({
   include: stringList.optional(),
   exclude: stringList.optional(),
   plugins: z.array(z.unknown()).optional(),
-  docs: docsConfigSchema.optional()
+  docs: docsConfigSchema.optional(),
+  check: checkConfigSchema.optional(),
+  lint: lintConfigSchema.optional()
 });
 var normalizeList = (value) => {
   if (!value) {
@@ -61,11 +72,27 @@ var normalizeConfig = (input) => {
       };
     }
   }
+  let check;
+  if (input.check) {
+    check = {
+      lint: input.check.lint,
+      typecheck: input.check.typecheck,
+      exec: input.check.exec
+    };
+  }
+  let lint;
+  if (input.lint) {
+    lint = {
+      rules: input.lint.rules
+    };
+  }
   return {
     include,
     exclude,
     plugins: input.plugins,
-    docs
+    docs,
+    check,
+    lint
   };
 };
 
@@ -142,7 +169,7 @@ ${formatIssues(issues)}`);
 var defineConfig = (config) => config;
 // src/cli.ts
 import { readFileSync as readFileSync5 } from "node:fs";
-import * as path9 from "node:path";
+import * as path11 from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 
@@ -161,13 +188,16 @@ import {
   findPackageByName,
   findJSDocLocation,
   generateFixesForExport,
+  getDefaultConfig as getLintDefaultConfig,
   hasNonAssertionComments,
+  lintExport,
   mergeFixes,
   NodeFileSystem,
   parseAssertions,
   parseJSDocToPatch,
   runExamplesWithPackage,
-  serializeJSDoc
+  serializeJSDoc,
+  typecheckExamples
 } from "@doccov/sdk";
 import chalk from "chalk";
 
@@ -274,7 +304,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("--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").option("--write", "Auto-fix drift issues").option("--only <types>", "Only fix specific drift types (comma-separated)").option("--dry-run", "Preview fixes without writing (requires --write)").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("--exec", "Execute @example blocks at runtime").option("--no-lint", "Skip lint checks").option("--no-typecheck", "Skip example type checking").option("--ignore-drift", "Do not fail on documentation drift").option("--skip-resolve", "Skip external type resolution from node_modules").option("--fix", "Auto-fix drift and lint issues").option("--write", "Alias for --fix").option("--only <types>", "Only fix specific drift types (comma-separated)").option("--dry-run", "Preview fixes without writing (requires --fix)").action(async (entry, options) => {
     try {
       let targetDir = options.cwd;
       let entryFile = entry;
@@ -344,8 +374,56 @@ function registerCheckCommand(program, dependencies = {}) {
         }
         log("");
       }
+      const shouldFix = options.fix || options.write;
+      const lintViolations = [];
+      if (options.lint !== false) {
+        process.stdout.write(chalk.cyan(`> Running lint checks...
+`));
+        const lintConfig = getLintDefaultConfig();
+        for (const exp of spec.exports ?? []) {
+          const violations = lintExport(exp, undefined, lintConfig);
+          for (const violation of violations) {
+            lintViolations.push({ exportName: exp.name, violation });
+          }
+        }
+        if (lintViolations.length === 0) {
+          process.stdout.write(chalk.green(`✓ No lint issues
+`));
+        } else {
+          const errors = lintViolations.filter((v) => v.violation.severity === "error").length;
+          const warns = lintViolations.filter((v) => v.violation.severity === "warn").length;
+          process.stdout.write(chalk.yellow(`⚠ ${lintViolations.length} lint issue(s) (${errors} error, ${warns} warn)
+`));
+        }
+      }
+      const typecheckErrors = [];
+      if (options.typecheck !== false) {
+        const allExamplesForTypecheck = [];
+        for (const exp of spec.exports ?? []) {
+          if (exp.examples && exp.examples.length > 0) {
+            allExamplesForTypecheck.push({ exportName: exp.name, examples: exp.examples });
+          }
+        }
+        if (allExamplesForTypecheck.length > 0) {
+          process.stdout.write(chalk.cyan(`> Type-checking examples...
+`));
+          for (const { exportName, examples } of allExamplesForTypecheck) {
+            const result = typecheckExamples(examples, targetDir);
+            for (const err of result.errors) {
+              typecheckErrors.push({ exportName, error: err });
+            }
+          }
+          if (typecheckErrors.length === 0) {
+            process.stdout.write(chalk.green(`✓ All examples type-check
+`));
+          } else {
+            process.stdout.write(chalk.red(`✗ ${typecheckErrors.length} type error(s)
+`));
+          }
+        }
+      }
       const runtimeDrifts = [];
-      if (options.runExamples) {
+      if (options.exec) {
         const allExamples = [];
         for (const entry2 of spec.exports ?? []) {
           if (entry2.examples && entry2.examples.length > 0) {
@@ -454,7 +532,7 @@ function registerCheckCommand(program, dependencies = {}) {
       const missingExamples = options.requireExamples ? failingExports.filter((item) => item.missing?.includes("examples")) : [];
       let driftExports = [...collectDrift(spec.exports ?? []), ...runtimeDrifts];
       const fixedDriftKeys = new Set;
-      if (options.write && driftExports.length > 0) {
+      if (shouldFix && driftExports.length > 0) {
         const allDrifts = collectDriftsFromExports(spec.exports ?? []);
         const filteredDrifts = filterDriftsByType(allDrifts, options.only);
         if (filteredDrifts.length === 0 && options.only) {
@@ -567,7 +645,9 @@ function registerCheckCommand(program, dependencies = {}) {
       const coverageFailed = coverageScore < minCoverage;
       const hasMissingExamples = missingExamples.length > 0;
       const hasDrift = !options.ignoreDrift && driftExports.length > 0;
-      if (!coverageFailed && !hasMissingExamples && !hasDrift) {
+      const hasLintErrors = lintViolations.filter((v) => v.violation.severity === "error").length > 0;
+      const hasTypecheckErrors = typecheckErrors.length > 0;
+      if (!coverageFailed && !hasMissingExamples && !hasDrift && !hasLintErrors && !hasTypecheckErrors) {
         log(chalk.green(`✓ Docs coverage ${coverageScore}% (min ${minCoverage}%)`));
         if (failingExports.length > 0) {
           log(chalk.gray("Some exports have partial docs:"));
@@ -594,6 +674,20 @@ function registerCheckCommand(program, dependencies = {}) {
       if (hasMissingExamples) {
         error(chalk.red(`${missingExamples.length} export(s) missing examples (required via --require-examples)`));
       }
+      if (hasLintErrors) {
+        error("");
+        error(chalk.bold("Lint errors:"));
+        for (const { exportName, violation } of lintViolations.filter((v) => v.violation.severity === "error").slice(0, 10)) {
+          error(chalk.red(`  • ${exportName}: ${violation.message}`));
+        }
+      }
+      if (hasTypecheckErrors) {
+        error("");
+        error(chalk.bold("Type errors in examples:"));
+        for (const { exportName, error: err } of typecheckErrors.slice(0, 10)) {
+          error(chalk.red(`  • ${exportName} @example ${err.exampleIndex + 1}, line ${err.line}: ${err.message}`));
+        }
+      }
       if (failingExports.length > 0 || driftExports.length > 0) {
         error("");
         error(chalk.bold("Missing documentation details:"));
@@ -730,12 +824,37 @@ var defaultDependencies2 = {
   log: console.log,
   error: console.error
 };
+var VALID_STRICT_OPTIONS = [
+  "regression",
+  "drift",
+  "docs-impact",
+  "breaking",
+  "undocumented",
+  "all"
+];
+function parseStrictOptions(value) {
+  if (!value)
+    return new Set;
+  const options = value.split(",").map((s) => s.trim().toLowerCase());
+  const result = new Set;
+  for (const opt of options) {
+    if (opt === "all") {
+      for (const o of VALID_STRICT_OPTIONS) {
+        if (o !== "all")
+          result.add(o);
+      }
+    } else if (VALID_STRICT_OPTIONS.includes(opt)) {
+      result.add(opt);
+    }
+  }
+  return result;
+}
 function registerDiffCommand(program, dependencies = {}) {
   const { readFileSync: readFileSync2, log, error } = {
     ...defaultDependencies2,
     ...dependencies
   };
-  program.command("diff <base> <head>").description("Compare two OpenPkg specs and report coverage delta").option("--output <format>", "Output format: json or text", "text").option("--fail-on-regression", "Exit with error if coverage regressed").option("--fail-on-drift", "Exit with error if new drift was introduced").option("--docs <glob>", "Glob pattern for markdown docs to check for impact", collect, []).option("--fail-on-docs-impact", "Exit with error if docs need updates").option("--ai", "Use AI for deeper analysis and fix suggestions").action(async (base, head, options) => {
+  program.command("diff <base> <head>").description("Compare two OpenPkg specs and report coverage delta").option("--format <format>", "Output format: text, json, github, report", "text").option("--strict <options>", "Fail on conditions (comma-separated): regression, drift, docs-impact, breaking, undocumented, all").option("--docs <glob>", "Glob pattern for markdown docs to check for impact", collect, []).option("--ai", "Use AI for deeper analysis and fix suggestions").option("--output <format>", "DEPRECATED: Use --format instead").option("--fail-on-regression", "DEPRECATED: Use --strict regression").option("--fail-on-drift", "DEPRECATED: Use --strict drift").option("--fail-on-docs-impact", "DEPRECATED: Use --strict docs-impact").action(async (base, head, options) => {
     try {
       const baseSpec = loadSpec(base, readFileSync2);
       const headSpec = loadSpec(head, readFileSync2);
@@ -752,52 +871,81 @@ function registerDiffCommand(program, dependencies = {}) {
         markdownFiles = await loadMarkdownFiles(docsPatterns);
       }
       const diff = diffSpecWithDocs(baseSpec, headSpec, { markdownFiles });
-      const format = options.output ?? "text";
-      if (format === "json") {
-        log(JSON.stringify(diff, null, 2));
-      } else {
-        printTextDiff(diff, log, error);
-        if (options.ai && diff.docsImpact && hasDocsImpact(diff)) {
-          if (!isAIDocsAnalysisAvailable()) {
-            log(chalk2.yellow(`
+      const format = options.format ?? options.output ?? "text";
+      const strictOptions = parseStrictOptions(options.strict);
+      if (options.failOnRegression)
+        strictOptions.add("regression");
+      if (options.failOnDrift)
+        strictOptions.add("drift");
+      if (options.failOnDocsImpact)
+        strictOptions.add("docs-impact");
+      switch (format) {
+        case "json":
+          log(JSON.stringify(diff, null, 2));
+          break;
+        case "github":
+          printGitHubAnnotations(diff, log);
+          break;
+        case "report":
+          log(generateHTMLReport(diff));
+          break;
+        case "text":
+        default:
+          printTextDiff(diff, log, error);
+          if (options.ai && diff.docsImpact && hasDocsImpact(diff)) {
+            if (!isAIDocsAnalysisAvailable()) {
+              log(chalk2.yellow(`
 ⚠ AI analysis unavailable (set OPENAI_API_KEY or ANTHROPIC_API_KEY)`));
-          } else {
-            log(chalk2.gray(`
+            } else {
+              log(chalk2.gray(`
 Generating AI summary...`));
-            const impacts = diff.docsImpact.impactedFiles.flatMap((f) => f.references.map((r) => ({
-              file: f.file,
-              exportName: r.exportName,
-              changeType: r.changeType,
-              context: r.context
-            })));
-            const summary = await generateImpactSummary(impacts);
-            if (summary) {
-              log("");
-              log(chalk2.bold("AI Summary"));
-              log(chalk2.cyan(`  ${summary}`));
+              const impacts = diff.docsImpact.impactedFiles.flatMap((f) => f.references.map((r) => ({
+                file: f.file,
+                exportName: r.exportName,
+                changeType: r.changeType,
+                context: r.context
+              })));
+              const summary = await generateImpactSummary(impacts);
+              if (summary) {
+                log("");
+                log(chalk2.bold("AI Summary"));
+                log(chalk2.cyan(`  ${summary}`));
+              }
             }
           }
-        }
+          break;
       }
-      if (options.failOnRegression && diff.coverageDelta < 0) {
+      if (strictOptions.has("regression") && diff.coverageDelta < 0) {
         error(chalk2.red(`
 Coverage regressed by ${Math.abs(diff.coverageDelta)}%`));
         process.exitCode = 1;
         return;
       }
-      if (options.failOnDrift && diff.driftIntroduced > 0) {
+      if (strictOptions.has("drift") && diff.driftIntroduced > 0) {
         error(chalk2.red(`
 ${diff.driftIntroduced} new drift issue(s) introduced`));
         process.exitCode = 1;
         return;
       }
-      if (options.failOnDocsImpact && hasDocsImpact(diff)) {
+      if (strictOptions.has("docs-impact") && hasDocsImpact(diff)) {
         const summary = getDocsImpactSummary(diff);
         error(chalk2.red(`
 ${summary.totalIssues} docs issue(s) require attention`));
         process.exitCode = 1;
         return;
       }
+      if (strictOptions.has("breaking") && diff.breaking.length > 0) {
+        error(chalk2.red(`
+${diff.breaking.length} breaking change(s) detected`));
+        process.exitCode = 1;
+        return;
+      }
+      if (strictOptions.has("undocumented") && diff.newUndocumented.length > 0) {
+        error(chalk2.red(`
+${diff.newUndocumented.length} new undocumented export(s)`));
+        process.exitCode = 1;
+        return;
+      }
     } catch (commandError) {
       error(chalk2.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
       process.exitCode = 1;
@@ -836,142 +984,376 @@ function printTextDiff(diff, log, _error) {
   log("");
   log(chalk2.bold("DocCov Diff Report"));
   log("─".repeat(40));
+  printCoverage(diff, log);
+  printAPIChanges(diff, log);
+  if (diff.docsImpact) {
+    printDocsRequiringUpdates(diff, log);
+  }
+  log("");
+}
+function printCoverage(diff, log) {
   const coverageColor = diff.coverageDelta > 0 ? chalk2.green : diff.coverageDelta < 0 ? chalk2.red : chalk2.gray;
   const coverageSymbol = diff.coverageDelta > 0 ? "↑" : diff.coverageDelta < 0 ? "↓" : "→";
   const deltaStr = diff.coverageDelta > 0 ? `+${diff.coverageDelta}` : String(diff.coverageDelta);
   log("");
   log(chalk2.bold("Coverage"));
   log(`  ${diff.oldCoverage}% ${coverageSymbol} ${diff.newCoverage}% ${coverageColor(`(${deltaStr}%)`)}`);
-  if (diff.breaking.length > 0 || diff.nonBreaking.length > 0) {
-    log("");
-    log(chalk2.bold("API Changes"));
-    if (diff.breaking.length > 0) {
-      log(chalk2.red(`  ${diff.breaking.length} breaking change(s)`));
-      for (const id of diff.breaking.slice(0, 5)) {
-        log(chalk2.red(`    - ${id}`));
-      }
-      if (diff.breaking.length > 5) {
-        log(chalk2.gray(`    ... and ${diff.breaking.length - 5} more`));
-      }
+}
+function printAPIChanges(diff, log) {
+  const hasChanges = diff.breaking.length > 0 || diff.nonBreaking.length > 0 || diff.memberChanges && diff.memberChanges.length > 0;
+  if (!hasChanges)
+    return;
+  log("");
+  log(chalk2.bold("API Changes"));
+  const membersByClass = groupMemberChangesByClass(diff.memberChanges ?? []);
+  const classesWithMembers = new Set(membersByClass.keys());
+  for (const [className, changes] of membersByClass) {
+    const categorized = diff.categorizedBreaking?.find((c) => c.id === className);
+    const isHighSeverity = categorized?.severity === "high";
+    const label = isHighSeverity ? chalk2.red(" [BREAKING]") : chalk2.yellow(" [CHANGED]");
+    log(chalk2.cyan(`  ${className}`) + label);
+    const removed = changes.filter((c) => c.changeType === "removed");
+    for (const mc of removed) {
+      const suggestion = mc.suggestion ? chalk2.gray(` → ${mc.suggestion}`) : "";
+      log(chalk2.red(`    ✖ ${mc.memberName}()`) + suggestion);
     }
-    if (diff.nonBreaking.length > 0) {
-      log(chalk2.green(`  ${diff.nonBreaking.length} new export(s)`));
-      for (const id of diff.nonBreaking.slice(0, 5)) {
-        log(chalk2.green(`    + ${id}`));
-      }
-      if (diff.nonBreaking.length > 5) {
-        log(chalk2.gray(`    ... and ${diff.nonBreaking.length - 5} more`));
+    const changed = changes.filter((c) => c.changeType === "signature-changed");
+    for (const mc of changed) {
+      log(chalk2.yellow(`    ~ ${mc.memberName}() signature changed`));
+      if (mc.oldSignature && mc.newSignature && mc.oldSignature !== mc.newSignature) {
+        log(chalk2.gray(`        was: ${mc.oldSignature}`));
+        log(chalk2.gray(`        now: ${mc.newSignature}`));
       }
     }
+    const added = changes.filter((c) => c.changeType === "added");
+    if (added.length > 0) {
+      const addedNames = added.map((a) => a.memberName + "()").join(", ");
+      log(chalk2.green(`    + ${addedNames}`));
+    }
   }
-  if (diff.memberChanges && diff.memberChanges.length > 0) {
+  const nonClassBreaking = (diff.categorizedBreaking ?? []).filter((c) => !classesWithMembers.has(c.id));
+  const typeChanges = nonClassBreaking.filter((c) => c.kind === "interface" || c.kind === "type" || c.kind === "enum");
+  const functionChanges = nonClassBreaking.filter((c) => c.kind === "function");
+  const otherChanges = nonClassBreaking.filter((c) => !["interface", "type", "enum", "function"].includes(c.kind));
+  if (functionChanges.length > 0) {
     log("");
-    log(chalk2.bold("Member Changes"));
-    const byClass = new Map;
-    for (const mc of diff.memberChanges) {
-      const list = byClass.get(mc.className) ?? [];
-      list.push(mc);
-      byClass.set(mc.className, list);
+    log(chalk2.red(`  Function Changes (${functionChanges.length}):`));
+    for (const fc of functionChanges.slice(0, 3)) {
+      const reason = fc.reason === "removed" ? "removed" : "signature changed";
+      log(chalk2.red(`    ✖ ${fc.name} (${reason})`));
     }
-    for (const [className, changes] of byClass) {
-      log(chalk2.cyan(`  ${className}:`));
-      const removed = changes.filter((c) => c.changeType === "removed");
-      const added = changes.filter((c) => c.changeType === "added");
-      const changed = changes.filter((c) => c.changeType === "signature-changed");
-      for (const mc of removed.slice(0, 3)) {
-        const suggestion = mc.suggestion ? ` (${mc.suggestion})` : "";
-        log(chalk2.red(`    - ${mc.memberName}()${suggestion}`));
-      }
-      for (const mc of added.slice(0, 3)) {
-        log(chalk2.green(`    + ${mc.memberName}()`));
-      }
-      for (const mc of changed.slice(0, 3)) {
-        log(chalk2.yellow(`    ~ ${mc.memberName}() signature changed`));
-      }
-      const total = removed.length + added.length + changed.length;
-      const shown = Math.min(removed.length, 3) + Math.min(added.length, 3) + Math.min(changed.length, 3);
-      if (total > shown) {
-        log(chalk2.gray(`    ... and ${total - shown} more member change(s)`));
-      }
+    if (functionChanges.length > 3) {
+      log(chalk2.gray(`    ... and ${functionChanges.length - 3} more`));
     }
   }
-  log("");
-  log(chalk2.bold("Docs Health"));
-  if (diff.newUndocumented.length > 0) {
-    log(chalk2.yellow(`  ${diff.newUndocumented.length} new undocumented export(s)`));
-    for (const id of diff.newUndocumented.slice(0, 5)) {
-      log(chalk2.yellow(`    ! ${id}`));
-    }
-    if (diff.newUndocumented.length > 5) {
-      log(chalk2.gray(`    ... and ${diff.newUndocumented.length - 5} more`));
-    }
+  if (typeChanges.length > 0) {
+    log("");
+    log(chalk2.yellow(`  Type/Interface Changes (${typeChanges.length}):`));
+    const typeNames = typeChanges.slice(0, 5).map((t) => t.name);
+    log(chalk2.yellow(`    ~ ${typeNames.join(", ")}${typeChanges.length > 5 ? ", ..." : ""}`));
   }
-  if (diff.improvedExports.length > 0) {
-    log(chalk2.green(`  ${diff.improvedExports.length} export(s) improved docs`));
+  if (otherChanges.length > 0) {
+    log("");
+    log(chalk2.gray(`  Other Changes (${otherChanges.length}):`));
+    const otherNames = otherChanges.slice(0, 3).map((o) => o.name);
+    log(chalk2.gray(`    ${otherNames.join(", ")}${otherChanges.length > 3 ? ", ..." : ""}`));
   }
-  if (diff.regressedExports.length > 0) {
-    log(chalk2.red(`  ${diff.regressedExports.length} export(s) regressed docs`));
-    for (const id of diff.regressedExports.slice(0, 5)) {
-      log(chalk2.red(`    ↓ ${id}`));
-    }
+  if (diff.nonBreaking.length > 0) {
+    const undocCount = diff.newUndocumented.length;
+    const undocSuffix = undocCount > 0 ? chalk2.yellow(` (${undocCount} undocumented)`) : "";
+    log("");
+    log(chalk2.green(`  New Exports (${diff.nonBreaking.length})`) + undocSuffix);
+    const exportNames = diff.nonBreaking.slice(0, 3);
+    log(chalk2.green(`    + ${exportNames.join(", ")}${diff.nonBreaking.length > 3 ? ", ..." : ""}`));
   }
   if (diff.driftIntroduced > 0 || diff.driftResolved > 0) {
     log("");
-    log(chalk2.bold("Drift"));
+    const parts = [];
     if (diff.driftIntroduced > 0) {
-      log(chalk2.red(`  +${diff.driftIntroduced} new drift issue(s)`));
+      parts.push(chalk2.red(`+${diff.driftIntroduced} drift`));
     }
     if (diff.driftResolved > 0) {
-      log(chalk2.green(`  -${diff.driftResolved} drift issue(s) resolved`));
+      parts.push(chalk2.green(`-${diff.driftResolved} resolved`));
     }
+    log(`  Drift: ${parts.join(", ")}`);
   }
-  if (diff.docsImpact) {
+}
+function printDocsRequiringUpdates(diff, log) {
+  if (!diff.docsImpact)
+    return;
+  const { impactedFiles, missingDocs, stats } = diff.docsImpact;
+  log("");
+  log(chalk2.bold("Docs Requiring Updates"));
+  log(chalk2.gray(`  Scanned ${stats.filesScanned} files, ${stats.codeBlocksFound} code blocks`));
+  if (impactedFiles.length === 0 && missingDocs.length === 0) {
+    log(chalk2.green("  ✓ No updates needed"));
+    return;
+  }
+  const sortedFiles = [...impactedFiles].sort((a, b) => b.references.length - a.references.length);
+  const actionableFiles = [];
+  const instantiationOnlyFiles = [];
+  for (const file of sortedFiles) {
+    const hasActionableRefs = file.references.some((r) => r.memberName && !r.isInstantiation || !r.memberName && !r.isInstantiation);
+    if (hasActionableRefs) {
+      actionableFiles.push(file);
+    } else {
+      instantiationOnlyFiles.push(file);
+    }
+  }
+  for (const file of actionableFiles.slice(0, 6)) {
+    const filename = path3.basename(file.file);
+    const issueCount = file.references.length;
     log("");
-    log(chalk2.bold("Docs Impact"));
-    const { impactedFiles, missingDocs, stats } = diff.docsImpact;
-    log(chalk2.gray(`  Scanned ${stats.filesScanned} file(s), ${stats.codeBlocksFound} code block(s)`));
-    if (impactedFiles.length > 0) {
-      log("");
-      log(chalk2.yellow(`  ${impactedFiles.length} file(s) need updates:`));
-      for (const file of impactedFiles.slice(0, 10)) {
-        log(chalk2.yellow(`    \uD83D\uDCC4 ${file.file}`));
-        for (const ref of file.references.slice(0, 5)) {
-          if (ref.memberName) {
-            const changeLabel = ref.changeType === "method-removed" ? "removed" : ref.changeType === "method-changed" ? "signature changed" : ref.changeType === "method-deprecated" ? "deprecated" : "changed";
-            log(chalk2.gray(`       Line ${ref.line}: ${ref.memberName}() ${changeLabel}`));
-            if (ref.replacementSuggestion) {
-              log(chalk2.cyan(`         → ${ref.replacementSuggestion}`));
-            }
-          } else if (ref.isInstantiation) {
-            log(chalk2.gray(`       Line ${ref.line}: new ${ref.exportName}() (class changed)`));
-          } else {
-            const changeLabel = ref.changeType === "signature-changed" ? "signature changed" : ref.changeType === "removed" ? "removed" : "deprecated";
-            log(chalk2.gray(`       Line ${ref.line}: ${ref.exportName} (${changeLabel})`));
-          }
-        }
-        if (file.references.length > 5) {
-          log(chalk2.gray(`       ... and ${file.references.length - 5} more reference(s)`));
-        }
+    log(chalk2.yellow(`  ${filename}`) + chalk2.gray(` (${issueCount} issue${issueCount > 1 ? "s" : ""})`));
+    const actionableRefs = file.references.filter((r) => !r.isInstantiation);
+    for (const ref of actionableRefs.slice(0, 4)) {
+      if (ref.memberName) {
+        const action = ref.changeType === "method-removed" ? "→" : "~";
+        const hint = ref.replacementSuggestion ?? (ref.changeType === "method-changed" ? "signature changed" : "removed");
+        log(chalk2.gray(`    L${ref.line}: ${ref.memberName}() ${action} ${hint}`));
+      } else {
+        const action = ref.changeType === "removed" ? "→" : "~";
+        const hint = ref.changeType === "removed" ? "removed" : ref.changeType === "signature-changed" ? "signature changed" : "changed";
+        log(chalk2.gray(`    L${ref.line}: ${ref.exportName} ${action} ${hint}`));
+      }
+    }
+    if (actionableRefs.length > 4) {
+      log(chalk2.gray(`    ... and ${actionableRefs.length - 4} more`));
+    }
+  }
+  if (actionableFiles.length > 6) {
+    log(chalk2.gray(`  ... and ${actionableFiles.length - 6} more files with method changes`));
+  }
+  if (instantiationOnlyFiles.length > 0) {
+    log("");
+    const fileNames = instantiationOnlyFiles.slice(0, 4).map((f) => path3.basename(f.file));
+    const suffix = instantiationOnlyFiles.length > 4 ? ", ..." : "";
+    log(chalk2.gray(`  ${instantiationOnlyFiles.length} file(s) with class instantiation to review:`));
+    log(chalk2.gray(`    ${fileNames.join(", ")}${suffix}`));
+  }
+  const { allUndocumented } = diff.docsImpact;
+  if (missingDocs.length > 0) {
+    log("");
+    log(chalk2.yellow(`  New exports missing docs (${missingDocs.length}):`));
+    const names = missingDocs.slice(0, 4);
+    log(chalk2.gray(`    ${names.join(", ")}${missingDocs.length > 4 ? ", ..." : ""}`));
+  }
+  if (allUndocumented && allUndocumented.length > 0) {
+    const existingUndocumented = allUndocumented.filter((name) => !missingDocs.includes(name));
+    log("");
+    log(chalk2.gray(`  Total undocumented exports: ${allUndocumented.length}/${stats.totalExports} (${Math.round((1 - allUndocumented.length / stats.totalExports) * 100)}% documented)`));
+    if (existingUndocumented.length > 0 && existingUndocumented.length <= 10) {
+      log(chalk2.gray(`    ${existingUndocumented.slice(0, 6).join(", ")}${existingUndocumented.length > 6 ? ", ..." : ""}`));
+    }
+  }
+}
+function groupMemberChangesByClass(memberChanges) {
+  const byClass = new Map;
+  for (const mc of memberChanges) {
+    const list = byClass.get(mc.className) ?? [];
+    list.push(mc);
+    byClass.set(mc.className, list);
+  }
+  return byClass;
+}
+function printGitHubAnnotations(diff, log) {
+  if (diff.coverageDelta !== 0) {
+    const level = diff.coverageDelta < 0 ? "warning" : "notice";
+    const sign = diff.coverageDelta > 0 ? "+" : "";
+    log(`::${level} title=Coverage Change::Coverage ${diff.oldCoverage}% → ${diff.newCoverage}% (${sign}${diff.coverageDelta}%)`);
+  }
+  for (const breaking of diff.categorizedBreaking ?? []) {
+    const level = breaking.severity === "high" ? "error" : "warning";
+    log(`::${level} title=Breaking Change::${breaking.name} - ${breaking.reason}`);
+  }
+  for (const mc of diff.memberChanges ?? []) {
+    if (mc.changeType === "removed") {
+      const suggestion = mc.suggestion ? ` ${mc.suggestion}` : "";
+      log(`::warning title=Method Removed::${mc.className}.${mc.memberName}() removed.${suggestion}`);
+    } else if (mc.changeType === "signature-changed") {
+      log(`::warning title=Signature Changed::${mc.className}.${mc.memberName}() signature changed`);
+    }
+  }
+  if (diff.docsImpact) {
+    for (const file of diff.docsImpact.impactedFiles) {
+      for (const ref of file.references) {
+        const level = ref.changeType === "removed" || ref.changeType === "method-removed" ? "error" : "warning";
+        const name = ref.memberName ? `${ref.memberName}()` : ref.exportName;
+        const changeDesc = ref.changeType === "removed" || ref.changeType === "method-removed" ? "removed" : ref.changeType === "signature-changed" || ref.changeType === "method-changed" ? "signature changed" : "changed";
+        const suggestion = ref.replacementSuggestion ? ` → ${ref.replacementSuggestion}` : "";
+        log(`::${level} file=${file.file},line=${ref.line},title=API Change::${name} ${changeDesc}${suggestion}`);
       }
-      if (impactedFiles.length > 10) {
-        log(chalk2.gray(`    ... and ${impactedFiles.length - 10} more file(s)`));
+    }
+    for (const name of diff.docsImpact.missingDocs) {
+      log(`::notice title=Missing Documentation::New export ${name} needs documentation`);
+    }
+    const { stats, allUndocumented } = diff.docsImpact;
+    if (allUndocumented && allUndocumented.length > 0) {
+      const docPercent = Math.round((1 - allUndocumented.length / stats.totalExports) * 100);
+      log(`::notice title=Documentation Coverage::${stats.documentedExports}/${stats.totalExports} exports documented (${docPercent}%)`);
+    }
+  }
+  if (!diff.docsImpact && diff.newUndocumented.length > 0) {
+    for (const name of diff.newUndocumented) {
+      log(`::notice title=Missing Documentation::New export ${name} needs documentation`);
+    }
+  }
+  if (diff.driftIntroduced > 0) {
+    log(`::warning title=Drift Detected::${diff.driftIntroduced} new drift issue(s) introduced`);
+  }
+}
+function generateHTMLReport(diff) {
+  const coverageClass = diff.coverageDelta > 0 ? "positive" : diff.coverageDelta < 0 ? "negative" : "neutral";
+  const coverageSign = diff.coverageDelta > 0 ? "+" : "";
+  let html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>DocCov Diff Report</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0d1117; color: #c9d1d9; padding: 2rem; line-height: 1.5; }
+    .container { max-width: 900px; margin: 0 auto; }
+    h1 { font-size: 1.5rem; margin-bottom: 1.5rem; color: #f0f6fc; }
+    h2 { font-size: 1.1rem; margin: 1.5rem 0 0.75rem; color: #f0f6fc; border-bottom: 1px solid #30363d; padding-bottom: 0.5rem; }
+    .card { background: #161b22; border: 1px solid #30363d; border-radius: 6px; padding: 1rem; margin-bottom: 1rem; }
+    .metric { display: flex; justify-content: space-between; align-items: center; padding: 0.5rem 0; }
+    .metric-label { color: #8b949e; }
+    .metric-value { font-weight: 600; }
+    .positive { color: #3fb950; }
+    .negative { color: #f85149; }
+    .neutral { color: #8b949e; }
+    .warning { color: #d29922; }
+    .badge { display: inline-block; padding: 0.125rem 0.5rem; border-radius: 12px; font-size: 0.75rem; font-weight: 500; }
+    .badge-breaking { background: #f8514933; color: #f85149; }
+    .badge-changed { background: #d2992233; color: #d29922; }
+    .badge-added { background: #3fb95033; color: #3fb950; }
+    .file-item { padding: 0.5rem; margin: 0.25rem 0; background: #0d1117; border-radius: 4px; }
+    .file-name { font-family: monospace; font-size: 0.9rem; }
+    .ref-list { margin-top: 0.5rem; padding-left: 1rem; font-size: 0.85rem; color: #8b949e; }
+    .ref-item { margin: 0.25rem 0; }
+    ul { list-style: none; }
+    li { padding: 0.25rem 0; }
+    code { font-family: monospace; background: #0d1117; padding: 0.125rem 0.375rem; border-radius: 3px; font-size: 0.9rem; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>\uD83D\uDCCA DocCov Diff Report</h1>
+
+    <div class="card">
+      <div class="metric">
+        <span class="metric-label">Coverage</span>
+        <span class="metric-value ${coverageClass}">${diff.oldCoverage}% → ${diff.newCoverage}% (${coverageSign}${diff.coverageDelta}%)</span>
+      </div>
+      <div class="metric">
+        <span class="metric-label">Breaking Changes</span>
+        <span class="metric-value ${diff.breaking.length > 0 ? "negative" : "neutral"}">${diff.breaking.length}</span>
+      </div>
+      <div class="metric">
+        <span class="metric-label">New Exports</span>
+        <span class="metric-value positive">${diff.nonBreaking.length}</span>
+      </div>
+      <div class="metric">
+        <span class="metric-label">Undocumented</span>
+        <span class="metric-value ${diff.newUndocumented.length > 0 ? "warning" : "neutral"}">${diff.newUndocumented.length}</span>
+      </div>
+    </div>`;
+  if (diff.breaking.length > 0) {
+    html += `
+    <h2>Breaking Changes</h2>
+    <div class="card">
+      <ul>`;
+    for (const item of diff.categorizedBreaking ?? []) {
+      const badgeClass = item.severity === "high" ? "badge-breaking" : "badge-changed";
+      html += `
+        <li><code>${item.name}</code> <span class="badge ${badgeClass}">${item.reason}</span></li>`;
+    }
+    html += `
+      </ul>
+    </div>`;
+  }
+  if (diff.memberChanges && diff.memberChanges.length > 0) {
+    html += `
+    <h2>Member Changes</h2>
+    <div class="card">
+      <ul>`;
+    for (const mc of diff.memberChanges) {
+      const badgeClass = mc.changeType === "removed" ? "badge-breaking" : mc.changeType === "added" ? "badge-added" : "badge-changed";
+      const suggestion = mc.suggestion ? ` → ${mc.suggestion}` : "";
+      html += `
+        <li><code>${mc.className}.${mc.memberName}()</code> <span class="badge ${badgeClass}">${mc.changeType}</span>${suggestion}</li>`;
+    }
+    html += `
+      </ul>
+    </div>`;
+  }
+  if (diff.docsImpact && diff.docsImpact.impactedFiles.length > 0) {
+    html += `
+    <h2>Documentation Impact</h2>
+    <div class="card">`;
+    for (const file of diff.docsImpact.impactedFiles.slice(0, 10)) {
+      const filename = path3.basename(file.file);
+      html += `
+      <div class="file-item">
+        <div class="file-name">\uD83D\uDCC4 ${filename} <span class="neutral">(${file.references.length} issue${file.references.length > 1 ? "s" : ""})</span></div>
+        <div class="ref-list">`;
+      for (const ref of file.references.slice(0, 5)) {
+        const name = ref.memberName ? `${ref.memberName}()` : ref.exportName;
+        const change = ref.changeType === "removed" || ref.changeType === "method-removed" ? "removed" : "signature changed";
+        html += `
+          <div class="ref-item">Line ${ref.line}: <code>${name}</code> ${change}</div>`;
+      }
+      if (file.references.length > 5) {
+        html += `
+          <div class="ref-item neutral">... and ${file.references.length - 5} more</div>`;
       }
+      html += `
+        </div>
+      </div>`;
     }
-    if (missingDocs.length > 0) {
-      log("");
-      log(chalk2.yellow(`  ${missingDocs.length} new export(s) missing docs:`));
-      for (const name of missingDocs.slice(0, 5)) {
-        log(chalk2.yellow(`    • ${name}`));
+    html += `
+    </div>`;
+  }
+  const hasNewUndocumented = diff.newUndocumented.length > 0;
+  const hasAllUndocumented = diff.docsImpact?.allUndocumented && diff.docsImpact.allUndocumented.length > 0;
+  if (hasNewUndocumented || hasAllUndocumented) {
+    html += `
+    <h2>Missing Documentation</h2>
+    <div class="card">`;
+    if (hasNewUndocumented) {
+      html += `
+      <p class="warning">New exports missing docs (${diff.newUndocumented.length}):</p>
+      <ul>`;
+      for (const name of diff.newUndocumented.slice(0, 10)) {
+        html += `
+        <li><code>${name}</code></li>`;
       }
-      if (missingDocs.length > 5) {
-        log(chalk2.gray(`    ... and ${missingDocs.length - 5} more`));
+      if (diff.newUndocumented.length > 10) {
+        html += `
+        <li class="neutral">... and ${diff.newUndocumented.length - 10} more</li>`;
       }
+      html += `
+      </ul>`;
     }
-    if (impactedFiles.length === 0 && missingDocs.length === 0) {
-      log(chalk2.green("  ✓ No docs impact detected"));
+    if (diff.docsImpact?.stats) {
+      const { stats, allUndocumented } = diff.docsImpact;
+      const docPercent = Math.round((1 - (allUndocumented?.length ?? 0) / stats.totalExports) * 100);
+      html += `
+      <div class="metric" style="margin-top: 1rem; border-top: 1px solid #30363d; padding-top: 1rem;">
+        <span class="metric-label">Total Documentation Coverage</span>
+        <span class="metric-value ${docPercent >= 80 ? "positive" : docPercent >= 50 ? "warning" : "negative"}">${stats.documentedExports}/${stats.totalExports} (${docPercent}%)</span>
+      </div>`;
     }
+    html += `
+    </div>`;
   }
-  log("");
+  html += `
+  </div>
+</body>
+</html>`;
+  return html;
 }
 
 // src/commands/generate.ts
@@ -1306,17 +1688,225 @@ var buildTemplate = (format) => {
 `);
 };
 
-// src/commands/report.ts
+// src/commands/lint.ts
 import * as fs5 from "node:fs";
 import * as path6 from "node:path";
 import {
-  DocCov as DocCov3,
+  applyEdits as applyEdits2,
+  createSourceFile as createSourceFile2,
   detectEntryPoint as detectEntryPoint3,
   detectMonorepo as detectMonorepo3,
+  DocCov as DocCov3,
+  findJSDocLocation as findJSDocLocation2,
   findPackageByName as findPackageByName3,
-  NodeFileSystem as NodeFileSystem3
+  getDefaultConfig,
+  getRule,
+  lintExport as lintExport2,
+  NodeFileSystem as NodeFileSystem3,
+  serializeJSDoc as serializeJSDoc2
 } from "@doccov/sdk";
 import chalk6 from "chalk";
+var defaultDependencies5 = {
+  createDocCov: (options) => new DocCov3(options),
+  log: console.log,
+  error: console.error
+};
+function getRawJSDoc(exp, targetDir) {
+  if (!exp.source?.file)
+    return;
+  const filePath = path6.resolve(targetDir, exp.source.file);
+  if (!fs5.existsSync(filePath))
+    return;
+  try {
+    const sourceFile = createSourceFile2(filePath);
+    const location = findJSDocLocation2(sourceFile, exp.name, exp.source.line);
+    return location?.existingJSDoc;
+  } catch {
+    return;
+  }
+}
+function registerLintCommand(program, dependencies = {}) {
+  const { createDocCov, log, error } = {
+    ...defaultDependencies5,
+    ...dependencies
+  };
+  program.command("lint [entry]").description("Lint documentation for style and quality issues").option("--cwd <dir>", "Working directory", process.cwd()).option("--package <name>", "Target package name (for monorepos)").option("--fix", "Auto-fix fixable issues").option("--write", "Alias for --fix").option("--rule <name>", "Run only a specific rule").option("--skip-resolve", "Skip external type resolution").action(async (entry, options) => {
+    try {
+      let targetDir = options.cwd;
+      let entryFile = entry;
+      const fileSystem = new NodeFileSystem3(options.cwd);
+      if (options.package) {
+        const mono = await detectMonorepo3(fileSystem);
+        if (!mono.isMonorepo) {
+          throw new Error("Not a monorepo. Remove --package flag.");
+        }
+        const pkg = findPackageByName3(mono.packages, options.package);
+        if (!pkg) {
+          const available = mono.packages.map((p) => p.name).join(", ");
+          throw new Error(`Package "${options.package}" not found. Available: ${available}`);
+        }
+        targetDir = path6.join(options.cwd, pkg.path);
+        log(chalk6.gray(`Found package at ${pkg.path}`));
+      }
+      if (!entryFile) {
+        const targetFs = new NodeFileSystem3(targetDir);
+        const detected = await detectEntryPoint3(targetFs);
+        entryFile = path6.join(targetDir, detected.path);
+        log(chalk6.gray(`Auto-detected entry point: ${detected.path}`));
+      } else {
+        entryFile = path6.resolve(targetDir, entryFile);
+        if (fs5.existsSync(entryFile) && fs5.statSync(entryFile).isDirectory()) {
+          targetDir = entryFile;
+          const dirFs = new NodeFileSystem3(entryFile);
+          const detected = await detectEntryPoint3(dirFs);
+          entryFile = path6.join(entryFile, detected.path);
+          log(chalk6.gray(`Auto-detected entry point: ${detected.path}`));
+        }
+      }
+      const resolveExternalTypes = !options.skipResolve;
+      process.stdout.write(chalk6.cyan(`> Analyzing documentation...
+`));
+      const doccov = createDocCov({ resolveExternalTypes });
+      const specResult = await doccov.analyzeFileWithDiagnostics(entryFile);
+      if (!specResult) {
+        throw new Error("Failed to analyze documentation.");
+      }
+      process.stdout.write(chalk6.cyan(`> Running lint rules...
+`));
+      let config = getDefaultConfig();
+      if (options.rule) {
+        const rule = getRule(options.rule);
+        if (!rule) {
+          throw new Error(`Unknown rule: ${options.rule}`);
+        }
+        const rules = {};
+        for (const key of Object.keys(config.rules)) {
+          rules[key] = "off";
+        }
+        rules[options.rule] = rule.defaultSeverity === "off" ? "warn" : rule.defaultSeverity;
+        config = { rules };
+      }
+      const exportsWithJSDoc = [];
+      for (const exp of specResult.spec.exports ?? []) {
+        const rawJSDoc = getRawJSDoc(exp, targetDir);
+        exportsWithJSDoc.push({
+          export: exp,
+          rawJSDoc,
+          filePath: exp.source?.file ? path6.resolve(targetDir, exp.source.file) : undefined
+        });
+      }
+      const allViolations = [];
+      for (const { export: exp, rawJSDoc, filePath } of exportsWithJSDoc) {
+        const violations = lintExport2(exp, rawJSDoc, config);
+        for (const violation of violations) {
+          allViolations.push({ export: exp, violation, filePath, rawJSDoc });
+        }
+      }
+      const shouldFix = options.fix || options.write;
+      const fixableViolations = allViolations.filter((v) => v.violation.fixable);
+      if (shouldFix && fixableViolations.length > 0) {
+        process.stdout.write(chalk6.cyan(`> Applying fixes...
+`));
+        const edits = [];
+        for (const { export: exp, rawJSDoc, filePath } of fixableViolations) {
+          if (!filePath || !rawJSDoc)
+            continue;
+          if (filePath.endsWith(".d.ts"))
+            continue;
+          const sourceFile = createSourceFile2(filePath);
+          const location = findJSDocLocation2(sourceFile, exp.name, exp.source?.line);
+          if (!location)
+            continue;
+          const rule = getRule("consistent-param-style");
+          if (!rule?.fix)
+            continue;
+          const patch = rule.fix(exp, rawJSDoc);
+          if (!patch)
+            continue;
+          const newJSDoc = serializeJSDoc2(patch, location.indent);
+          edits.push({
+            filePath,
+            symbolName: exp.name,
+            startLine: location.startLine,
+            endLine: location.endLine,
+            hasExisting: location.hasExisting,
+            existingJSDoc: location.existingJSDoc,
+            newJSDoc,
+            indent: location.indent
+          });
+        }
+        if (edits.length > 0) {
+          const result = await applyEdits2(edits);
+          if (result.errors.length > 0) {
+            for (const err of result.errors) {
+              error(chalk6.red(`  ${err.file}: ${err.error}`));
+            }
+          } else {
+            process.stdout.write(chalk6.green(`✓ Fixed ${result.editsApplied} issue(s) in ${result.filesModified} file(s)
+`));
+          }
+          const fixedExports = new Set(edits.map((e) => e.symbolName));
+          const remaining = allViolations.filter((v) => !v.violation.fixable || !fixedExports.has(v.export.name));
+          allViolations.length = 0;
+          allViolations.push(...remaining);
+        }
+      }
+      if (allViolations.length === 0) {
+        log(chalk6.green("✓ No lint issues found"));
+        return;
+      }
+      const byFile = new Map;
+      for (const v of allViolations) {
+        const file = v.filePath ?? "unknown";
+        const existing = byFile.get(file) ?? [];
+        existing.push(v);
+        byFile.set(file, existing);
+      }
+      log("");
+      for (const [filePath, violations] of byFile) {
+        const relativePath = path6.relative(targetDir, filePath);
+        log(chalk6.underline(relativePath));
+        for (const { export: exp, violation } of violations) {
+          const line = exp.source?.line ?? 0;
+          const severity = violation.severity === "error" ? chalk6.red("error") : chalk6.yellow("warning");
+          const fixable = violation.fixable ? chalk6.gray(" (fixable)") : "";
+          log(`  ${line}:1  ${severity}  ${violation.message}  ${chalk6.gray(violation.rule)}${fixable}`);
+        }
+        log("");
+      }
+      const errorCount = allViolations.filter((v) => v.violation.severity === "error").length;
+      const warnCount = allViolations.filter((v) => v.violation.severity === "warn").length;
+      const fixableCount = allViolations.filter((v) => v.violation.fixable).length;
+      const summary = [];
+      if (errorCount > 0)
+        summary.push(chalk6.red(`${errorCount} error(s)`));
+      if (warnCount > 0)
+        summary.push(chalk6.yellow(`${warnCount} warning(s)`));
+      if (fixableCount > 0 && !shouldFix) {
+        summary.push(chalk6.gray(`${fixableCount} fixable with --fix`));
+      }
+      log(summary.join(", "));
+      if (errorCount > 0) {
+        process.exit(1);
+      }
+    } catch (commandError) {
+      error(chalk6.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/report.ts
+import * as fs6 from "node:fs";
+import * as path7 from "node:path";
+import {
+  DocCov as DocCov4,
+  detectEntryPoint as detectEntryPoint4,
+  detectMonorepo as detectMonorepo4,
+  findPackageByName as findPackageByName4,
+  NodeFileSystem as NodeFileSystem4
+} from "@doccov/sdk";
+import chalk7 from "chalk";
 
 // src/reports/markdown.ts
 function bar(pct, width = 10) {
@@ -1493,42 +2083,42 @@ function registerReportCommand(program) {
     try {
       let spec;
       if (options.spec) {
-        const specPath = path6.resolve(options.cwd, options.spec);
-        spec = JSON.parse(fs5.readFileSync(specPath, "utf-8"));
+        const specPath = path7.resolve(options.cwd, options.spec);
+        spec = JSON.parse(fs6.readFileSync(specPath, "utf-8"));
       } else {
         let targetDir = options.cwd;
         let entryFile = entry;
-        const fileSystem = new NodeFileSystem3(options.cwd);
+        const fileSystem = new NodeFileSystem4(options.cwd);
         if (options.package) {
-          const mono = await detectMonorepo3(fileSystem);
+          const mono = await detectMonorepo4(fileSystem);
           if (!mono.isMonorepo) {
             throw new Error(`Not a monorepo. Remove --package flag for single-package repos.`);
           }
-          const pkg = findPackageByName3(mono.packages, options.package);
+          const pkg = findPackageByName4(mono.packages, options.package);
           if (!pkg) {
             const available = mono.packages.map((p) => p.name).join(", ");
             throw new Error(`Package "${options.package}" not found. Available: ${available}`);
           }
-          targetDir = path6.join(options.cwd, pkg.path);
+          targetDir = path7.join(options.cwd, pkg.path);
         }
         if (!entryFile) {
-          const targetFs = new NodeFileSystem3(targetDir);
-          const detected = await detectEntryPoint3(targetFs);
-          entryFile = path6.join(targetDir, detected.path);
+          const targetFs = new NodeFileSystem4(targetDir);
+          const detected = await detectEntryPoint4(targetFs);
+          entryFile = path7.join(targetDir, detected.path);
         } else {
-          entryFile = path6.resolve(targetDir, entryFile);
+          entryFile = path7.resolve(targetDir, entryFile);
         }
-        process.stdout.write(chalk6.cyan(`> Analyzing...
+        process.stdout.write(chalk7.cyan(`> Analyzing...
 `));
         try {
           const resolveExternalTypes = !options.skipResolve;
-          const doccov = new DocCov3({ resolveExternalTypes });
+          const doccov = new DocCov4({ resolveExternalTypes });
           const result = await doccov.analyzeFileWithDiagnostics(entryFile);
-          process.stdout.write(chalk6.green(`✓ Analysis complete
+          process.stdout.write(chalk7.green(`✓ Analysis complete
 `));
           spec = result.spec;
         } catch (analysisError) {
-          process.stdout.write(chalk6.red(`✗ Analysis failed
+          process.stdout.write(chalk7.red(`✗ Analysis failed
 `));
           throw analysisError;
         }
@@ -1545,35 +2135,35 @@ function registerReportCommand(program) {
         output = renderMarkdown(stats, { limit });
       }
       if (options.out) {
-        const outPath = path6.resolve(options.cwd, options.out);
-        fs5.writeFileSync(outPath, output);
-        console.log(chalk6.green(`Report written to ${outPath}`));
+        const outPath = path7.resolve(options.cwd, options.out);
+        fs6.writeFileSync(outPath, output);
+        console.log(chalk7.green(`Report written to ${outPath}`));
       } else {
         console.log(output);
       }
     } catch (err) {
-      console.error(chalk6.red("Error:"), err instanceof Error ? err.message : err);
+      console.error(chalk7.red("Error:"), err instanceof Error ? err.message : err);
       process.exitCode = 1;
     }
   });
 }
 
 // src/commands/scan.ts
-import * as fs7 from "node:fs";
+import * as fs8 from "node:fs";
 import * as os from "node:os";
-import * as path8 from "node:path";
+import * as path9 from "node:path";
 import {
-  DocCov as DocCov4,
+  DocCov as DocCov5,
   detectBuildInfo,
-  detectEntryPoint as detectEntryPoint4,
-  detectMonorepo as detectMonorepo4,
+  detectEntryPoint as detectEntryPoint5,
+  detectMonorepo as detectMonorepo5,
   detectPackageManager,
-  findPackageByName as findPackageByName4,
+  findPackageByName as findPackageByName5,
   formatPackageList,
   getInstallCommand,
-  NodeFileSystem as NodeFileSystem4
+  NodeFileSystem as NodeFileSystem5
 } from "@doccov/sdk";
-import chalk7 from "chalk";
+import chalk8 from "chalk";
 import { simpleGit } from "simple-git";
 
 // src/utils/github-url.ts
@@ -1607,8 +2197,8 @@ function buildDisplayUrl(parsed) {
 }
 
 // src/utils/llm-build-plan.ts
-import * as fs6 from "node:fs";
-import * as path7 from "node:path";
+import * as fs7 from "node:fs";
+import * as path8 from "node:path";
 import { createAnthropic as createAnthropic3 } from "@ai-sdk/anthropic";
 import { createOpenAI as createOpenAI3 } from "@ai-sdk/openai";
 import { generateObject as generateObject3 } from "ai";
@@ -1644,10 +2234,10 @@ function getModel3() {
 async function gatherContextFiles(repoDir) {
   const sections = [];
   for (const fileName of CONTEXT_FILES) {
-    const filePath = path7.join(repoDir, fileName);
-    if (fs6.existsSync(filePath)) {
+    const filePath = path8.join(repoDir, fileName);
+    if (fs7.existsSync(filePath)) {
       try {
-        let content = fs6.readFileSync(filePath, "utf-8");
+        let content = fs7.readFileSync(filePath, "utf-8");
         if (content.length > MAX_FILE_CHARS) {
           content = `${content.slice(0, MAX_FILE_CHARS)}
 ... (truncated)`;
@@ -1699,14 +2289,14 @@ async function generateBuildPlan(repoDir) {
 }
 
 // src/commands/scan.ts
-var defaultDependencies5 = {
-  createDocCov: (options) => new DocCov4(options),
+var defaultDependencies6 = {
+  createDocCov: (options) => new DocCov5(options),
   log: console.log,
   error: console.error
 };
 function registerScanCommand(program, dependencies = {}) {
   const { createDocCov, 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("--skip-resolve", "Skip external type resolution from node_modules").option("--save-spec <path>", "Save full OpenPkg spec to file").action(async (url, options) => {
@@ -1716,12 +2306,12 @@ function registerScanCommand(program, dependencies = {}) {
       const cloneUrl = buildCloneUrl(parsed);
       const displayUrl = buildDisplayUrl(parsed);
       log("");
-      log(chalk7.bold(`Scanning ${displayUrl}`));
-      log(chalk7.gray(`Branch/tag: ${parsed.ref}`));
+      log(chalk8.bold(`Scanning ${displayUrl}`));
+      log(chalk8.gray(`Branch/tag: ${parsed.ref}`));
       log("");
-      tempDir = path8.join(os.tmpdir(), `doccov-scan-${Date.now()}-${Math.random().toString(36).slice(2)}`);
-      fs7.mkdirSync(tempDir, { recursive: true });
-      process.stdout.write(chalk7.cyan(`> Cloning ${parsed.owner}/${parsed.repo}...
+      tempDir = path9.join(os.tmpdir(), `doccov-scan-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+      fs8.mkdirSync(tempDir, { recursive: true });
+      process.stdout.write(chalk8.cyan(`> Cloning ${parsed.owner}/${parsed.repo}...
 `));
       try {
         const git = simpleGit({
@@ -1743,10 +2333,10 @@ function registerScanCommand(program, dependencies = {}) {
         } finally {
           process.env = originalEnv;
         }
-        process.stdout.write(chalk7.green(`✓ Cloned ${parsed.owner}/${parsed.repo}
+        process.stdout.write(chalk8.green(`✓ Cloned ${parsed.owner}/${parsed.repo}
 `));
       } catch (cloneError) {
-        process.stdout.write(chalk7.red(`✗ Failed to clone repository
+        process.stdout.write(chalk8.red(`✗ Failed to clone repository
 `));
         const message = cloneError instanceof Error ? cloneError.message : String(cloneError);
         if (message.includes("Authentication failed") || message.includes("could not read Username") || message.includes("terminal prompts disabled") || message.includes("Invalid username or password") || message.includes("Permission denied")) {
@@ -1762,11 +2352,11 @@ function registerScanCommand(program, dependencies = {}) {
         }
         throw new Error(`Clone failed: ${message}`);
       }
-      const fileSystem = new NodeFileSystem4(tempDir);
+      const fileSystem = new NodeFileSystem5(tempDir);
       if (options.skipInstall) {
-        log(chalk7.gray("Skipping dependency installation (--skip-install)"));
+        log(chalk8.gray("Skipping dependency installation (--skip-install)"));
       } else {
-        process.stdout.write(chalk7.cyan(`> Installing dependencies...
+        process.stdout.write(chalk8.cyan(`> Installing dependencies...
 `));
         const installErrors = [];
         try {
@@ -1816,56 +2406,56 @@ function registerScanCommand(program, dependencies = {}) {
             }
           }
           if (installed) {
-            process.stdout.write(chalk7.green(`✓ Dependencies installed
+            process.stdout.write(chalk8.green(`✓ Dependencies installed
 `));
           } else {
-            process.stdout.write(chalk7.yellow(`⚠ Could not install dependencies (analysis may be limited)
+            process.stdout.write(chalk8.yellow(`⚠ Could not install dependencies (analysis may be limited)
 `));
             for (const err of installErrors) {
-              log(chalk7.gray(`  ${err}`));
+              log(chalk8.gray(`  ${err}`));
             }
           }
         } catch (outerError) {
           const msg = outerError instanceof Error ? outerError.message : String(outerError);
-          process.stdout.write(chalk7.yellow(`⚠ Could not install dependencies: ${msg.slice(0, 100)}
+          process.stdout.write(chalk8.yellow(`⚠ Could not install dependencies: ${msg.slice(0, 100)}
 `));
           for (const err of installErrors) {
-            log(chalk7.gray(`  ${err}`));
+            log(chalk8.gray(`  ${err}`));
           }
         }
       }
       let targetDir = tempDir;
       let packageName;
-      const mono = await detectMonorepo4(fileSystem);
+      const mono = await detectMonorepo5(fileSystem);
       if (mono.isMonorepo) {
         if (!options.package) {
           error("");
-          error(chalk7.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("");
           throw new Error("Monorepo requires --package flag");
         }
-        const pkg = findPackageByName4(mono.packages, options.package);
+        const pkg = findPackageByName5(mono.packages, options.package);
         if (!pkg) {
           error("");
-          error(chalk7.red(`Package "${options.package}" not found. Available packages:`));
+          error(chalk8.red(`Package "${options.package}" not found. Available packages:`));
           error("");
           error(formatPackageList(mono.packages));
           error("");
           throw new Error(`Package not found: ${options.package}`);
         }
-        targetDir = path8.join(tempDir, pkg.path);
+        targetDir = path9.join(tempDir, pkg.path);
         packageName = pkg.name;
-        log(chalk7.gray(`Analyzing package: ${packageName}`));
+        log(chalk8.gray(`Analyzing package: ${packageName}`));
       }
-      process.stdout.write(chalk7.cyan(`> Detecting entry point...
+      process.stdout.write(chalk8.cyan(`> Detecting entry point...
 `));
       let entryPath;
-      const targetFs = mono.isMonorepo ? new NodeFileSystem4(targetDir) : fileSystem;
+      const targetFs = mono.isMonorepo ? new NodeFileSystem5(targetDir) : fileSystem;
       let buildFailed = false;
       const runLlmFallback = async (reason) => {
-        process.stdout.write(chalk7.cyan(`> ${reason}, trying LLM fallback...
+        process.stdout.write(chalk8.cyan(`> ${reason}, trying LLM fallback...
 `));
         const plan = await generateBuildPlan(targetDir);
         if (!plan) {
@@ -1874,88 +2464,88 @@ function registerScanCommand(program, dependencies = {}) {
         if (plan.buildCommands.length > 0) {
           const { execSync } = await import("node:child_process");
           for (const cmd of plan.buildCommands) {
-            log(chalk7.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(chalk7.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(chalk7.yellow(`  ⚠ Build failed: missing dependencies`));
+                log(chalk8.yellow(`  ⚠ Build failed: missing dependencies`));
               } else {
-                log(chalk7.yellow(`  ⚠ Build failed: ${msg.slice(0, 80)}`));
+                log(chalk8.yellow(`  ⚠ Build failed: ${msg.slice(0, 80)}`));
               }
             }
           }
         }
         if (plan.notes) {
-          log(chalk7.gray(`  Note: ${plan.notes}`));
+          log(chalk8.gray(`  Note: ${plan.notes}`));
         }
         return plan.entryPoint;
       };
       try {
-        const entry = await detectEntryPoint4(targetFs);
+        const entry = await detectEntryPoint5(targetFs);
         const buildInfo = await detectBuildInfo(targetFs);
         const needsBuildStep = entry.isDeclarationOnly && buildInfo.exoticIndicators.wasm;
         if (needsBuildStep) {
-          process.stdout.write(chalk7.cyan(`> Detected .d.ts entry with WASM indicators...
+          process.stdout.write(chalk8.cyan(`> Detected .d.ts entry with WASM indicators...
 `));
           const llmEntry = await runLlmFallback("WASM project detected");
           if (llmEntry) {
-            entryPath = path8.join(targetDir, llmEntry);
+            entryPath = path9.join(targetDir, llmEntry);
             if (buildFailed) {
-              process.stdout.write(chalk7.green(`✓ Entry point: ${llmEntry} (using pre-committed declarations)
+              process.stdout.write(chalk8.green(`✓ Entry point: ${llmEntry} (using pre-committed declarations)
 `));
-              log(chalk7.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 {
-              process.stdout.write(chalk7.green(`✓ Entry point: ${llmEntry} (from LLM fallback - WASM project)
+              process.stdout.write(chalk8.green(`✓ Entry point: ${llmEntry} (from LLM fallback - WASM project)
 `));
             }
           } else {
-            entryPath = path8.join(targetDir, entry.path);
-            process.stdout.write(chalk7.green(`✓ Entry point: ${entry.path} (from ${entry.source})
+            entryPath = path9.join(targetDir, entry.path);
+            process.stdout.write(chalk8.green(`✓ Entry point: ${entry.path} (from ${entry.source})
 `));
-            log(chalk7.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 = path8.join(targetDir, entry.path);
-          process.stdout.write(chalk7.green(`✓ Entry point: ${entry.path} (from ${entry.source})
+          entryPath = path9.join(targetDir, entry.path);
+          process.stdout.write(chalk8.green(`✓ Entry point: ${entry.path} (from ${entry.source})
 `));
         }
       } catch (entryError) {
         const llmEntry = await runLlmFallback("Heuristics failed");
         if (llmEntry) {
-          entryPath = path8.join(targetDir, llmEntry);
-          process.stdout.write(chalk7.green(`✓ Entry point: ${llmEntry} (from LLM fallback)
+          entryPath = path9.join(targetDir, llmEntry);
+          process.stdout.write(chalk8.green(`✓ Entry point: ${llmEntry} (from LLM fallback)
 `));
         } else {
-          process.stdout.write(chalk7.red(`✗ Could not detect entry point (set OPENAI_API_KEY for smart fallback)
+          process.stdout.write(chalk8.red(`✗ Could not detect entry point (set OPENAI_API_KEY for smart fallback)
 `));
           throw entryError;
         }
       }
-      process.stdout.write(chalk7.cyan(`> Analyzing documentation coverage...
+      process.stdout.write(chalk8.cyan(`> Analyzing documentation coverage...
 `));
       let result;
       try {
         const resolveExternalTypes = !options.skipResolve;
         const doccov = createDocCov({ resolveExternalTypes });
         result = await doccov.analyzeFileWithDiagnostics(entryPath);
-        process.stdout.write(chalk7.green(`✓ Analysis complete
+        process.stdout.write(chalk8.green(`✓ Analysis complete
 `));
       } catch (analysisError) {
-        process.stdout.write(chalk7.red(`✗ Analysis failed
+        process.stdout.write(chalk8.red(`✗ Analysis failed
 `));
         throw analysisError;
       }
       const spec = result.spec;
       const coverageScore = spec.docs?.coverageScore ?? 0;
       if (options.saveSpec) {
-        const specPath = path8.resolve(process.cwd(), options.saveSpec);
-        fs7.writeFileSync(specPath, JSON.stringify(spec, null, 2));
-        log(chalk7.green(`✓ Saved spec to ${options.saveSpec}`));
+        const specPath = path9.resolve(process.cwd(), options.saveSpec);
+        fs8.writeFileSync(specPath, JSON.stringify(spec, null, 2));
+        log(chalk8.green(`✓ Saved spec to ${options.saveSpec}`));
       }
       const undocumented = [];
       const driftIssues = [];
@@ -1992,7 +2582,7 @@ function registerScanCommand(program, dependencies = {}) {
         printTextResult(scanResult, log);
       }
     } catch (commandError) {
-      error(chalk7.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) {
@@ -2002,63 +2592,180 @@ function registerScanCommand(program, dependencies = {}) {
           stdio: "ignore"
         }).unref();
       } else if (tempDir) {
-        log(chalk7.gray(`Repo preserved at: ${tempDir}`));
+        log(chalk8.gray(`Repo preserved at: ${tempDir}`));
       }
     }
   });
 }
 function printTextResult(result, log) {
   log("");
-  log(chalk7.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: ${chalk7.cyan(repoName)}`);
-  log(`Branch: ${chalk7.gray(result.ref)}`);
+  log(`Repository: ${chalk8.cyan(repoName)}`);
+  log(`Branch: ${chalk8.gray(result.ref)}`);
   log("");
-  const coverageColor = result.coverage >= 80 ? chalk7.green : result.coverage >= 50 ? chalk7.yellow : chalk7.red;
-  log(chalk7.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(chalk7.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(chalk7.bold("Undocumented Exports"));
+    log(chalk8.bold("Undocumented Exports"));
     for (const name of result.undocumented.slice(0, 10)) {
-      log(chalk7.yellow(`  ! ${name}`));
+      log(chalk8.yellow(`  ! ${name}`));
     }
     if (result.undocumented.length > 10) {
-      log(chalk7.gray(`  ... and ${result.undocumented.length - 10} more`));
+      log(chalk8.gray(`  ... and ${result.undocumented.length - 10} more`));
     }
   }
   if (result.drift.length > 0) {
     log("");
-    log(chalk7.bold("Drift Issues"));
+    log(chalk8.bold("Drift Issues"));
     for (const d of result.drift.slice(0, 5)) {
-      log(chalk7.red(`  • ${d.export}: ${d.issue}`));
+      log(chalk8.red(`  • ${d.export}: ${d.issue}`));
     }
     if (result.drift.length > 5) {
-      log(chalk7.gray(`  ... and ${result.drift.length - 5} more`));
+      log(chalk8.gray(`  ... and ${result.drift.length - 5} more`));
     }
   }
   log("");
 }
 
+// src/commands/typecheck.ts
+import * as fs9 from "node:fs";
+import * as path10 from "node:path";
+import {
+  detectEntryPoint as detectEntryPoint6,
+  detectMonorepo as detectMonorepo6,
+  DocCov as DocCov6,
+  findPackageByName as findPackageByName6,
+  NodeFileSystem as NodeFileSystem6,
+  typecheckExamples as typecheckExamples2
+} from "@doccov/sdk";
+import chalk9 from "chalk";
+var defaultDependencies7 = {
+  createDocCov: (options) => new DocCov6(options),
+  log: console.log,
+  error: console.error
+};
+function registerTypecheckCommand(program, dependencies = {}) {
+  const { createDocCov, log, error } = {
+    ...defaultDependencies7,
+    ...dependencies
+  };
+  program.command("typecheck [entry]").description("Type-check @example blocks without executing them").option("--cwd <dir>", "Working directory", process.cwd()).option("--package <name>", "Target package name (for monorepos)").option("--skip-resolve", "Skip external type resolution").action(async (entry, options) => {
+    try {
+      let targetDir = options.cwd;
+      let entryFile = entry;
+      const fileSystem = new NodeFileSystem6(options.cwd);
+      if (options.package) {
+        const mono = await detectMonorepo6(fileSystem);
+        if (!mono.isMonorepo) {
+          throw new Error("Not a monorepo. Remove --package flag.");
+        }
+        const pkg = findPackageByName6(mono.packages, options.package);
+        if (!pkg) {
+          const available = mono.packages.map((p) => p.name).join(", ");
+          throw new Error(`Package "${options.package}" not found. Available: ${available}`);
+        }
+        targetDir = path10.join(options.cwd, pkg.path);
+        log(chalk9.gray(`Found package at ${pkg.path}`));
+      }
+      if (!entryFile) {
+        const targetFs = new NodeFileSystem6(targetDir);
+        const detected = await detectEntryPoint6(targetFs);
+        entryFile = path10.join(targetDir, detected.path);
+        log(chalk9.gray(`Auto-detected entry point: ${detected.path}`));
+      } else {
+        entryFile = path10.resolve(targetDir, entryFile);
+        if (fs9.existsSync(entryFile) && fs9.statSync(entryFile).isDirectory()) {
+          targetDir = entryFile;
+          const dirFs = new NodeFileSystem6(entryFile);
+          const detected = await detectEntryPoint6(dirFs);
+          entryFile = path10.join(entryFile, detected.path);
+          log(chalk9.gray(`Auto-detected entry point: ${detected.path}`));
+        }
+      }
+      const resolveExternalTypes = !options.skipResolve;
+      process.stdout.write(chalk9.cyan(`> Analyzing documentation...
+`));
+      const doccov = createDocCov({ resolveExternalTypes });
+      const specResult = await doccov.analyzeFileWithDiagnostics(entryFile);
+      if (!specResult) {
+        throw new Error("Failed to analyze documentation.");
+      }
+      const allExamples = [];
+      for (const exp of specResult.spec.exports ?? []) {
+        if (exp.examples && exp.examples.length > 0) {
+          allExamples.push({ exportName: exp.name, examples: exp.examples });
+        }
+      }
+      if (allExamples.length === 0) {
+        log(chalk9.gray("No @example blocks found"));
+        return;
+      }
+      const totalExamples = allExamples.reduce((sum, e) => sum + e.examples.length, 0);
+      process.stdout.write(chalk9.cyan(`> Type-checking ${totalExamples} example(s)...
+`));
+      const allErrors = [];
+      let passed = 0;
+      let failed = 0;
+      for (const { exportName, examples } of allExamples) {
+        const result = typecheckExamples2(examples, targetDir);
+        for (const err of result.errors) {
+          allErrors.push({ exportName, error: err });
+        }
+        passed += result.passed;
+        failed += result.failed;
+      }
+      if (allErrors.length === 0) {
+        log(chalk9.green(`✓ All ${totalExamples} example(s) passed type checking`));
+        return;
+      }
+      log("");
+      const byExport = new Map;
+      for (const { exportName, error: err } of allErrors) {
+        const existing = byExport.get(exportName) ?? [];
+        existing.push(err);
+        byExport.set(exportName, existing);
+      }
+      for (const [exportName, errors] of byExport) {
+        log(chalk9.red(`✗ ${exportName}`));
+        for (const err of errors) {
+          log(chalk9.gray(`  @example block ${err.exampleIndex + 1}, line ${err.line}:`));
+          log(chalk9.red(`    ${err.message}`));
+        }
+        log("");
+      }
+      log(chalk9.red(`${failed} example(s) failed`) + chalk9.gray(`, ${passed} passed`));
+      process.exit(1);
+    } catch (commandError) {
+      error(chalk9.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      process.exit(1);
+    }
+  });
+}
+
 // src/cli.ts
 var __filename2 = fileURLToPath(import.meta.url);
-var __dirname2 = path9.dirname(__filename2);
-var packageJson = JSON.parse(readFileSync5(path9.join(__dirname2, "../package.json"), "utf-8"));
+var __dirname2 = path11.dirname(__filename2);
+var packageJson = JSON.parse(readFileSync5(path11.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);
 registerInitCommand(program);
+registerLintCommand(program);
 registerReportCommand(program);
 registerScanCommand(program);
+registerTypecheckCommand(program);
 program.command("*", { hidden: true }).action(() => {
   program.outputHelp();
 });