@doccov/cli 0.2.1

package/dist/cli.js

@@ -0,0 +1,1551 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/config/openpkg-config.ts
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+// src/config/schema.ts
+import { z } from "zod";
+var stringList = z.union([
+  z.string(),
+  z.array(z.string())
+]);
+var docCovConfigSchema = z.object({
+  include: stringList.optional(),
+  exclude: stringList.optional(),
+  plugins: z.array(z.unknown()).optional()
+});
+var normalizeList = (value) => {
+  if (!value) {
+    return;
+  }
+  const list = Array.isArray(value) ? value : [value];
+  const normalized = list.map((item) => item.trim()).filter(Boolean);
+  return normalized.length > 0 ? normalized : undefined;
+};
+var normalizeConfig = (input) => {
+  const include = normalizeList(input.include);
+  const exclude = normalizeList(input.exclude);
+  return {
+    include,
+    exclude,
+    plugins: input.plugins
+  };
+};
+
+// src/config/openpkg-config.ts
+var DOCCOV_CONFIG_FILENAMES = [
+  "doccov.config.ts",
+  "doccov.config.mts",
+  "doccov.config.cts",
+  "doccov.config.js",
+  "doccov.config.mjs",
+  "doccov.config.cjs",
+  "openpkg.config.ts",
+  "openpkg.config.mts",
+  "openpkg.config.cts",
+  "openpkg.config.js",
+  "openpkg.config.mjs",
+  "openpkg.config.cjs"
+];
+var fileExists = async (filePath) => {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var findConfigFile = async (cwd) => {
+  let current = path.resolve(cwd);
+  const { root } = path.parse(current);
+  while (true) {
+    for (const candidate of DOCCOV_CONFIG_FILENAMES) {
+      const candidatePath = path.join(current, candidate);
+      if (await fileExists(candidatePath)) {
+        return candidatePath;
+      }
+    }
+    if (current === root) {
+      return null;
+    }
+    current = path.dirname(current);
+  }
+};
+var importConfigModule = async (absolutePath) => {
+  const fileUrl = pathToFileURL(absolutePath);
+  fileUrl.searchParams.set("t", Date.now().toString());
+  const module = await import(fileUrl.href);
+  return module?.default ?? module?.config ?? module;
+};
+var formatIssues = (issues) => issues.map((issue) => `- ${issue}`).join(`
+`);
+var loadDocCovConfig = async (cwd) => {
+  const configPath = await findConfigFile(cwd);
+  if (!configPath) {
+    return null;
+  }
+  let rawConfig;
+  try {
+    rawConfig = await importConfigModule(configPath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to load DocCov config at ${configPath}: ${message}`);
+  }
+  const parsed = docCovConfigSchema.safeParse(rawConfig);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => {
+      const pathLabel = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+      return `${pathLabel}: ${issue.message}`;
+    });
+    throw new Error(`Invalid DocCov configuration at ${configPath}.
+${formatIssues(issues)}`);
+  }
+  const normalized = normalizeConfig(parsed.data);
+  return {
+    filePath: configPath,
+    ...normalized
+  };
+};
+var loadOpenPkgConfigInternal = loadDocCovConfig;
+var loadOpenPkgConfig = loadDocCovConfig;
+
+// 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 { 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 chalk from "chalk";
+import ora from "ora";
+
+// src/utils/package-utils.ts
+import * as fs from "node:fs";
+import * as path2 from "node:path";
+async function findEntryPoint(packageDir, preferSource = false) {
+  const packageJsonPath = path2.join(packageDir, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return findDefaultEntryPoint(packageDir);
+  }
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+  if (preferSource) {
+    const srcIndex = path2.join(packageDir, "src/index.ts");
+    if (fs.existsSync(srcIndex)) {
+      return srcIndex;
+    }
+  }
+  if (!preferSource && (packageJson.types || packageJson.typings)) {
+    const typesPath = path2.join(packageDir, packageJson.types || packageJson.typings);
+    if (fs.existsSync(typesPath)) {
+      return typesPath;
+    }
+  }
+  if (packageJson.exports) {
+    const exportPath = resolveExportsField(packageJson.exports, packageDir);
+    if (exportPath) {
+      return exportPath;
+    }
+  }
+  if (packageJson.main) {
+    const mainBase = packageJson.main.replace(/\.(js|mjs|cjs)$/, "");
+    const dtsPath = path2.join(packageDir, `${mainBase}.d.ts`);
+    if (fs.existsSync(dtsPath)) {
+      return dtsPath;
+    }
+    const tsPath = path2.join(packageDir, `${mainBase}.ts`);
+    if (fs.existsSync(tsPath)) {
+      return tsPath;
+    }
+    const mainPath = path2.join(packageDir, packageJson.main);
+    if (fs.existsSync(mainPath) && fs.statSync(mainPath).isDirectory()) {
+      const indexDts = path2.join(mainPath, "index.d.ts");
+      const indexTs = path2.join(mainPath, "index.ts");
+      if (fs.existsSync(indexDts))
+        return indexDts;
+      if (fs.existsSync(indexTs))
+        return indexTs;
+    }
+  }
+  return findDefaultEntryPoint(packageDir);
+}
+function resolveExportsField(exports, packageDir) {
+  if (typeof exports === "string") {
+    return findTypeScriptFile(path2.join(packageDir, exports));
+  }
+  if (typeof exports === "object" && exports !== null && "." in exports) {
+    const dotExport = exports["."];
+    if (typeof dotExport === "string") {
+      return findTypeScriptFile(path2.join(packageDir, dotExport));
+    }
+    if (dotExport && typeof dotExport === "object") {
+      const dotRecord = dotExport;
+      const typesEntry = dotRecord.types;
+      if (typeof typesEntry === "string") {
+        const typesPath = path2.join(packageDir, typesEntry);
+        if (fs.existsSync(typesPath)) {
+          return typesPath;
+        }
+      }
+      for (const condition of ["import", "require", "default"]) {
+        const target = dotRecord[condition];
+        if (typeof target === "string") {
+          const result = findTypeScriptFile(path2.join(packageDir, target));
+          if (result)
+            return result;
+        }
+      }
+    }
+  }
+  return null;
+}
+function findTypeScriptFile(jsPath) {
+  if (!fs.existsSync(jsPath))
+    return null;
+  const dtsPath = jsPath.replace(/\.(js|mjs|cjs)$/, ".d.ts");
+  if (fs.existsSync(dtsPath)) {
+    return dtsPath;
+  }
+  const tsPath = jsPath.replace(/\.(js|mjs|cjs)$/, ".ts");
+  if (fs.existsSync(tsPath)) {
+    return tsPath;
+  }
+  return null;
+}
+async function findDefaultEntryPoint(packageDir) {
+  const candidates = [
+    "dist/index.d.ts",
+    "dist/index.ts",
+    "lib/index.d.ts",
+    "lib/index.ts",
+    "src/index.ts",
+    "index.d.ts",
+    "index.ts"
+  ];
+  for (const candidate of candidates) {
+    const fullPath = path2.join(packageDir, candidate);
+    if (fs.existsSync(fullPath)) {
+      return fullPath;
+    }
+  }
+  throw new Error(`Could not find entry point in ${packageDir}`);
+}
+async function findPackageInMonorepo(rootDir, packageName) {
+  const rootPackageJsonPath = path2.join(rootDir, "package.json");
+  if (!fs.existsSync(rootPackageJsonPath)) {
+    return null;
+  }
+  const rootPackageJson = JSON.parse(fs.readFileSync(rootPackageJsonPath, "utf-8"));
+  const workspacePatterns = Array.isArray(rootPackageJson.workspaces) ? rootPackageJson.workspaces : rootPackageJson.workspaces?.packages || [];
+  for (const pattern of workspacePatterns) {
+    const searchPath = path2.join(rootDir, pattern.replace("/**", "").replace("/*", ""));
+    if (fs.existsSync(searchPath) && fs.statSync(searchPath).isDirectory()) {
+      const entries = fs.readdirSync(searchPath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const packagePath = path2.join(searchPath, entry.name);
+          const packageJsonPath = path2.join(packagePath, "package.json");
+          if (fs.existsSync(packageJsonPath)) {
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+            if (packageJson.name === packageName) {
+              return packagePath;
+            }
+          }
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// src/commands/check.ts
+var defaultDependencies = {
+  createDocCov: (options) => new DocCov(options),
+  spinner: (text) => ora(text),
+  log: console.log,
+  error: console.error
+};
+function registerCheckCommand(program, dependencies = {}) {
+  const { createDocCov, spinner, log, error } = {
+    ...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("--no-external-types", "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(chalk.gray(`Found package at ${path3.relative(options.cwd, packageDir)}`));
+      }
+      if (!entryFile) {
+        entryFile = await findEntryPoint(targetDir, true);
+        log(chalk.gray(`Auto-detected entry point: ${path3.relative(targetDir, entryFile)}`));
+      } else {
+        entryFile = path3.resolve(targetDir, entryFile);
+        if (fs2.existsSync(entryFile) && fs2.statSync(entryFile).isDirectory()) {
+          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 spinnerInstance = spinner("Analyzing documentation coverage...");
+      spinnerInstance.start();
+      let specResult;
+      try {
+        const doccov = createDocCov({ resolveExternalTypes });
+        specResult = await doccov.analyzeFileWithDiagnostics(entryFile);
+        spinnerInstance.succeed("Documentation analysis complete");
+      } catch (analysisError) {
+        spinnerInstance.fail("Failed to analyze documentation coverage");
+        throw analysisError;
+      }
+      if (!specResult) {
+        throw new Error("Failed to analyze documentation coverage.");
+      }
+      const spec = specResult.spec;
+      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 coverageFailed = coverageScore < minCoverage;
+      const hasMissingExamples = missingExamples.length > 0;
+      const hasDrift = driftExports.length > 0;
+      if (!coverageFailed && !hasMissingExamples && !hasDrift) {
+        log(chalk.green(`✓ Docs coverage ${coverageScore}% (min ${minCoverage}%)`));
+        if (failingExports.length > 0) {
+          log(chalk.gray("Some exports have partial docs:"));
+          for (const { name, missing } of failingExports.slice(0, 10)) {
+            log(chalk.gray(`  • ${name}: missing ${missing?.join(", ")}`));
+          }
+        }
+        return;
+      }
+      error("");
+      if (coverageFailed) {
+        error(chalk.red(`Docs coverage ${coverageScore}% fell below required ${minCoverage}%.`));
+      }
+      if (hasMissingExamples) {
+        error(chalk.red(`${missingExamples.length} export(s) missing examples (required via --require-examples)`));
+      }
+      if (failingExports.length > 0 || driftExports.length > 0) {
+        error("");
+        error(chalk.bold("Missing documentation details:"));
+        for (const { name, missing } of failingExports.slice(0, 10)) {
+          error(chalk.red(`  • ${name}: missing ${missing?.join(", ")}`));
+        }
+        for (const drift of driftExports.slice(0, 10)) {
+          error(chalk.red(`  • ${drift.name}: ${drift.issue}`));
+          if (drift.suggestion) {
+            error(chalk.yellow(`    Suggestion: ${drift.suggestion}`));
+          }
+        }
+      }
+      throw new Error("Documentation coverage requirements not met.");
+    } catch (commandError) {
+      error(chalk.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      throw commandError instanceof Error ? commandError : new Error(String(commandError));
+    }
+  });
+}
+function clampCoverage(value) {
+  if (Number.isNaN(value)) {
+    return 80;
+  }
+  return Math.min(100, Math.max(0, Math.round(value)));
+}
+function collectFailingExports(exportsList, minCoverage) {
+  const offenders = [];
+  for (const entry of exportsList) {
+    const exportScore = entry.docs?.coverageScore ?? 0;
+    const missing = entry.docs?.missing;
+    if (exportScore < minCoverage || missing && missing.length > 0) {
+      offenders.push({
+        name: entry.name,
+        missing
+      });
+    }
+  }
+  return offenders;
+}
+function collectDrift(exportsList) {
+  const drifts = [];
+  for (const entry of exportsList) {
+    const drift = entry.docs?.drift;
+    if (!drift || drift.length === 0) {
+      continue;
+    }
+    for (const signal of drift) {
+      drifts.push({
+        name: entry.name,
+        issue: signal.issue ?? "Documentation drift detected.",
+        suggestion: signal.suggestion
+      });
+    }
+  }
+  return drifts;
+}
+
+// src/commands/diff.ts
+import * as fs3 from "node:fs";
+import * as path4 from "node:path";
+import { diffSpec } from "@openpkg-ts/spec";
+import chalk2 from "chalk";
+var defaultDependencies2 = {
+  readFileSync: fs3.readFileSync,
+  log: console.log,
+  error: console.error
+};
+function registerDiffCommand(program, dependencies = {}) {
+  const { readFileSync: readFileSync3, 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").action((base, head, options) => {
+    try {
+      const baseSpec = loadSpec(base, readFileSync3);
+      const headSpec = loadSpec(head, readFileSync3);
+      const diff = diffSpec(baseSpec, headSpec);
+      const format = options.output ?? "text";
+      if (format === "json") {
+        log(JSON.stringify(diff, null, 2));
+      } else {
+        printTextDiff(diff, log, error);
+      }
+      if (options.failOnRegression && diff.coverageDelta < 0) {
+        error(chalk2.red(`
+Coverage regressed by ${Math.abs(diff.coverageDelta)}%`));
+        process.exitCode = 1;
+        return;
+      }
+      if (options.failOnDrift && diff.driftIntroduced > 0) {
+        error(chalk2.red(`
+${diff.driftIntroduced} new drift issue(s) introduced`));
+        process.exitCode = 1;
+        return;
+      }
+    } catch (commandError) {
+      error(chalk2.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      process.exitCode = 1;
+    }
+  });
+}
+function loadSpec(filePath, readFileSync3) {
+  const resolvedPath = path4.resolve(filePath);
+  if (!fs3.existsSync(resolvedPath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+  try {
+    const content = readFileSync3(resolvedPath, "utf-8");
+    return JSON.parse(content);
+  } catch (parseError) {
+    throw new Error(`Failed to parse ${filePath}: ${parseError instanceof Error ? parseError.message : parseError}`);
+  }
+}
+function printTextDiff(diff, log, error) {
+  log("");
+  log(chalk2.bold("DocCov Diff Report"));
+  log("─".repeat(40));
+  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`));
+      }
+    }
+    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`));
+      }
+    }
+  }
+  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 (diff.improvedExports.length > 0) {
+    log(chalk2.green(`  ${diff.improvedExports.length} export(s) improved docs`));
+  }
+  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.driftIntroduced > 0 || diff.driftResolved > 0) {
+    log("");
+    log(chalk2.bold("Drift"));
+    if (diff.driftIntroduced > 0) {
+      log(chalk2.red(`  +${diff.driftIntroduced} new drift issue(s)`));
+    }
+    if (diff.driftResolved > 0) {
+      log(chalk2.green(`  -${diff.driftResolved} drift issue(s) resolved`));
+    }
+  }
+  log("");
+}
+
+// src/commands/generate.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 ora2 from "ora";
+
+// src/utils/filter-options.ts
+import chalk3 from "chalk";
+var unique = (values) => Array.from(new Set(values));
+var parseListFlag = (value) => {
+  if (!value) {
+    return;
+  }
+  const rawItems = Array.isArray(value) ? value : [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 mergeFilterOptions = (config, cliOptions) => {
+  const messages = [];
+  const configInclude = config?.include;
+  const configExclude = config?.exclude;
+  const cliInclude = cliOptions.include;
+  const cliExclude = cliOptions.exclude;
+  let include = configInclude;
+  let exclude = configExclude;
+  let source = include || exclude ? "config" : undefined;
+  if (configInclude) {
+    messages.push(formatList("include filters from config", configInclude));
+  }
+  if (configExclude) {
+    messages.push(formatList("exclude filters from config", configExclude));
+  }
+  if (cliInclude) {
+    include = include ? include.filter((item) => cliInclude.includes(item)) : cliInclude;
+    source = include ? "combined" : "cli";
+    messages.push(formatList("apply include filters from CLI", cliInclude));
+  }
+  if (cliExclude) {
+    exclude = exclude ? unique([...exclude, ...cliExclude]) : cliExclude;
+    source = source ? "combined" : "cli";
+    messages.push(formatList("apply exclude filters from CLI", cliExclude));
+  }
+  include = include ? unique(include) : undefined;
+  exclude = exclude ? unique(exclude) : undefined;
+  if (!include && !exclude) {
+    return { messages };
+  }
+  return {
+    include,
+    exclude,
+    source,
+    messages
+  };
+};
+
+// src/commands/generate.ts
+var defaultDependencies3 = {
+  createDocCov: (options) => new DocCov2(options),
+  writeFileSync: fs4.writeFileSync,
+  spinner: (text) => ora2(text),
+  log: console.log,
+  error: console.error
+};
+function getArrayLength(value) {
+  return Array.isArray(value) ? value.length : 0;
+}
+function stripDocsFields(spec) {
+  const { docs: _rootDocs, ...rest } = spec;
+  return {
+    ...rest,
+    exports: spec.exports?.map((exp) => {
+      const { docs: _expDocs, ...expRest } = exp;
+      return expRest;
+    })
+  };
+}
+function formatDiagnosticOutput(prefix, diagnostic, baseDir) {
+  const location = diagnostic.location;
+  const relativePath = location?.file ? path5.relative(baseDir, location.file) || location.file : undefined;
+  const locationText = location && relativePath ? chalk4.gray(`${relativePath}:${location.line ?? 1}:${location.column ?? 1}`) : null;
+  const locationPrefix = locationText ? `${locationText} ` : "";
+  return `${prefix} ${locationPrefix}${diagnostic.message}`;
+}
+function registerGenerateCommand(program, dependencies = {}) {
+  const { createDocCov, writeFileSync: writeFileSync2, spinner, log, error } = {
+    ...defaultDependencies3,
+    ...dependencies
+  };
+  program.command("generate [entry]").description("Generate OpenPkg specification for documentation coverage analysis").option("-o, --output <file>", "Output file", "openpkg.json").option("-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) => {
+    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(chalk4.gray(`Found package at ${path5.relative(options.cwd, packageDir)}`));
+      }
+      if (!entryFile) {
+        entryFile = await findEntryPoint(targetDir, true);
+        log(chalk4.gray(`Auto-detected entry point: ${path5.relative(targetDir, entryFile)}`));
+      } else {
+        entryFile = path5.resolve(targetDir, entryFile);
+        if (fs4.existsSync(entryFile) && fs4.statSync(entryFile).isDirectory()) {
+          entryFile = await findEntryPoint(entryFile, true);
+          log(chalk4.gray(`Auto-detected entry point: ${entryFile}`));
+        }
+      }
+      const resolveExternalTypes = options.externalTypes !== false;
+      const cliFilters = {
+        include: parseListFlag(options.include),
+        exclude: parseListFlag(options.exclude)
+      };
+      let config = null;
+      try {
+        config = await loadDocCovConfig(targetDir);
+        if (config?.filePath) {
+          log(chalk4.gray(`Loaded configuration from ${path5.relative(targetDir, config.filePath)}`));
+        }
+      } catch (configError) {
+        error(chalk4.red("Failed to load DocCov config:"), configError instanceof Error ? configError.message : configError);
+        process.exit(1);
+      }
+      const resolvedFilters = mergeFilterOptions(config, cliFilters);
+      for (const message of resolvedFilters.messages) {
+        log(chalk4.gray(`• ${message}`));
+      }
+      const spinnerInstance = spinner("Generating OpenPkg spec...");
+      spinnerInstance.start();
+      let result;
+      try {
+        const doccov = createDocCov({
+          resolveExternalTypes
+        });
+        const analyzeOptions = resolvedFilters.include || resolvedFilters.exclude ? {
+          filters: {
+            include: resolvedFilters.include,
+            exclude: resolvedFilters.exclude
+          }
+        } : {};
+        result = await doccov.analyzeFileWithDiagnostics(entryFile, analyzeOptions);
+        spinnerInstance.succeed("Generated OpenPkg spec");
+      } catch (generationError) {
+        spinnerInstance.fail("Failed to generate spec");
+        throw generationError;
+      }
+      if (!result) {
+        throw new Error("Failed to produce an OpenPkg spec.");
+      }
+      const outputPath = path5.resolve(process.cwd(), options.output);
+      let normalized = normalize(result.spec);
+      if (options.docs === false) {
+        normalized = stripDocsFields(normalized);
+      }
+      const validation = validateSpec(normalized);
+      if (!validation.ok) {
+        spinnerInstance.fail("Spec failed schema validation");
+        for (const err of validation.errors) {
+          error(chalk4.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`));
+      if (options.showDiagnostics && result.diagnostics.length > 0) {
+        log("");
+        log(chalk4.bold("Diagnostics"));
+        for (const diagnostic of result.diagnostics) {
+          const prefix = diagnostic.severity === "error" ? chalk4.red("✖") : diagnostic.severity === "warning" ? chalk4.yellow("⚠") : chalk4.cyan("ℹ");
+          log(formatDiagnosticOutput(prefix, diagnostic, targetDir));
+        }
+      }
+    } catch (commandError) {
+      error(chalk4.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,
+  log: console.log,
+  error: console.error
+};
+function registerInitCommand(program, dependencies = {}) {
+  const { fileExists: fileExists2, writeFileSync: writeFileSync3, readFileSync: readFileSync4, log, error } = {
+    ...defaultDependencies4,
+    ...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 formatOption = String(options.format ?? "auto").toLowerCase();
+    if (!isValidFormat(formatOption)) {
+      error(chalk5.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.*"}.`));
+      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.'));
+    }
+    const fileName = `doccov.config.${targetFormat}`;
+    const outputPath = path6.join(cwd, fileName);
+    if (fileExists2(outputPath)) {
+      error(chalk5.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)}`));
+  });
+}
+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);
+  while (true) {
+    for (const candidate of DOCCOV_CONFIG_FILENAMES) {
+      const candidatePath = path6.join(current, candidate);
+      if (fileExists2(candidatePath)) {
+        return candidatePath;
+      }
+    }
+    if (current === root) {
+      break;
+    }
+    current = path6.dirname(current);
+  }
+  return null;
+};
+var detectPackageType = (cwd, fileExists2, readFileSync4) => {
+  const packageJsonPath = findNearestPackageJson(cwd, fileExists2);
+  if (!packageJsonPath) {
+    return;
+  }
+  try {
+    const raw = readFileSync4(packageJsonPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.type === "module") {
+      return "module";
+    }
+    if (parsed.type === "commonjs") {
+      return "commonjs";
+    }
+  } catch (_error) {}
+  return;
+};
+var findNearestPackageJson = (cwd, fileExists2) => {
+  let current = path6.resolve(cwd);
+  const { root } = path6.parse(current);
+  while (true) {
+    const candidate = path6.join(current, "package.json");
+    if (fileExists2(candidate)) {
+      return candidate;
+    }
+    if (current === root) {
+      break;
+    }
+    current = path6.dirname(current);
+  }
+  return null;
+};
+var resolveFormat = (format, packageType) => {
+  if (format === "auto") {
+    return packageType === "module" ? "js" : "mjs";
+  }
+  return format;
+};
+var buildTemplate = (format) => {
+  if (format === "cjs") {
+    return [
+      "const { defineConfig } = require('@doccov/cli/config');",
+      "",
+      "module.exports = defineConfig({",
+      "  include: [],",
+      "  exclude: [],",
+      "});",
+      ""
+    ].join(`
+`);
+  }
+  return [
+    "import { defineConfig } from '@doccov/cli/config';",
+    "",
+    "export default defineConfig({",
+    "  include: [],",
+    "  exclude: [],",
+    "});",
+    ""
+  ].join(`
+`);
+};
+
+// src/commands/scan.ts
+import * as fs9 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 { simpleGit } from "simple-git";
+
+// src/utils/entry-detection.ts
+import * as fs6 from "node:fs";
+import * as path7 from "node:path";
+function detectEntryPoint(repoDir) {
+  const pkgPath = path7.join(repoDir, "package.json");
+  if (!fs6.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"));
+  } catch {
+    throw new Error("Failed to parse package.json");
+  }
+  if (typeof pkg.types === "string") {
+    const resolved = resolveToTs(repoDir, pkg.types);
+    if (resolved) {
+      return { entryPath: resolved, source: "types" };
+    }
+  }
+  if (typeof pkg.typings === "string") {
+    const resolved = resolveToTs(repoDir, pkg.typings);
+    if (resolved) {
+      return { entryPath: resolved, source: "types" };
+    }
+  }
+  const exports = pkg.exports;
+  if (exports) {
+    const mainExport = exports["."];
+    if (typeof mainExport === "object" && mainExport !== null) {
+      const exportObj = mainExport;
+      if (typeof exportObj.types === "string") {
+        const resolved = resolveToTs(repoDir, exportObj.types);
+        if (resolved) {
+          return { entryPath: resolved, source: "exports" };
+        }
+      }
+    }
+  }
+  if (typeof pkg.main === "string") {
+    const resolved = resolveToTs(repoDir, pkg.main);
+    if (resolved) {
+      return { entryPath: resolved, source: "main" };
+    }
+  }
+  if (typeof pkg.module === "string") {
+    const resolved = resolveToTs(repoDir, pkg.module);
+    if (resolved) {
+      return { entryPath: resolved, source: "module" };
+    }
+  }
+  const commonPaths = [
+    "src/index.ts",
+    "src/index.tsx",
+    "src/main.ts",
+    "index.ts",
+    "lib/index.ts",
+    "source/index.ts"
+  ];
+  for (const p of commonPaths) {
+    if (fs6.existsSync(path7.join(repoDir, p))) {
+      return { entryPath: p, source: "fallback" };
+    }
+  }
+  throw new Error("Could not detect TypeScript entry point. No types field in package.json and no common entry paths found.");
+}
+function resolveToTs(baseDir, filePath) {
+  const normalized = filePath.replace(/^\.\//, "");
+  if (normalized.endsWith(".ts") || normalized.endsWith(".tsx")) {
+    if (fs6.existsSync(path7.join(baseDir, normalized))) {
+      return normalized;
+    }
+  }
+  const candidates = [];
+  if (normalized.startsWith("dist/")) {
+    const srcPath = normalized.replace(/^dist\//, "src/");
+    candidates.push(srcPath.replace(/\.js$/, ".ts"));
+    candidates.push(srcPath.replace(/\.d\.ts$/, ".ts"));
+    candidates.push(srcPath.replace(/\.js$/, ".tsx"));
+  }
+  if (normalized.startsWith("build/")) {
+    const srcPath = normalized.replace(/^build\//, "src/");
+    candidates.push(srcPath.replace(/\.js$/, ".ts"));
+    candidates.push(srcPath.replace(/\.d\.ts$/, ".ts"));
+  }
+  if (normalized.startsWith("lib/")) {
+    const srcPath = normalized.replace(/^lib\//, "src/");
+    candidates.push(srcPath.replace(/\.js$/, ".ts"));
+    candidates.push(srcPath.replace(/\.d\.ts$/, ".ts"));
+  }
+  candidates.push(normalized.replace(/\.js$/, ".ts"));
+  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");
+    candidates.push(`src/${baseName}.ts`);
+  }
+  for (const candidate of candidates) {
+    if (fs6.existsSync(path7.join(baseDir, candidate))) {
+      return candidate;
+    }
+  }
+  return;
+}
+
+// src/utils/github-url.ts
+function parseGitHubUrl(input, defaultRef = "main") {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new Error("GitHub URL cannot be empty");
+  }
+  let normalized = trimmed.replace(/^https?:\/\//, "").replace(/^git@github\.com:/, "").replace(/\.git$/, "");
+  normalized = normalized.replace(/^github\.com\//, "");
+  const parts = normalized.split("/").filter(Boolean);
+  if (parts.length < 2) {
+    throw new Error(`Invalid GitHub URL format: "${input}". Expected owner/repo or https://github.com/owner/repo`);
+  }
+  const owner = parts[0];
+  const repo = parts[1];
+  let ref = defaultRef;
+  if (parts.length >= 4 && (parts[2] === "tree" || parts[2] === "blob")) {
+    ref = parts.slice(3).join("/");
+  }
+  if (!owner || !repo) {
+    throw new Error(`Could not parse owner/repo from: "${input}"`);
+  }
+  return { owner, repo, ref };
+}
+function buildCloneUrl(parsed) {
+  return `https://github.com/${parsed.owner}/${parsed.repo}.git`;
+}
+function buildDisplayUrl(parsed) {
+  return `github.com/${parsed.owner}/${parsed.repo}`;
+}
+
+// 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")
+});
+var CONTEXT_FILES = [
+  "package.json",
+  "README.md",
+  "README",
+  "tsconfig.json",
+  "Cargo.toml",
+  ".nvmrc",
+  ".node-version",
+  "pnpm-workspace.yaml",
+  "lerna.json",
+  "wasm-pack.json"
+];
+var MAX_FILE_CHARS = 2000;
+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");
+}
+async function gatherContextFiles(repoDir) {
+  const sections = [];
+  for (const fileName of CONTEXT_FILES) {
+    const filePath = path8.join(repoDir, fileName);
+    if (fs7.existsSync(filePath)) {
+      try {
+        let content = fs7.readFileSync(filePath, "utf-8");
+        if (content.length > MAX_FILE_CHARS) {
+          content = `${content.slice(0, MAX_FILE_CHARS)}
+... (truncated)`;
+        }
+        sections.push(`--- ${fileName} ---
+${content}`);
+      } catch {}
+    }
+  }
+  return sections.join(`
+
+`);
+}
+var BUILD_PLAN_PROMPT = (context) => `Analyze this project to determine how to build it for TypeScript API analysis.
+
+The standard entry detection failed. This might be a WASM project, unusual monorepo, or require a build step before the TypeScript entry point exists.
+
+<files>
+${context}
+</files>
+
+Return:
+- buildCommands: Commands to run in order (e.g., ["npm run build:wasm", "npm run build"]). Empty array if no build needed.
+- entryPoint: Path to the TypeScript entry file AFTER build completes (e.g., "src/index.ts" or "pkg/index.d.ts")
+- installCommand: Additional install command if needed beyond what was already run
+- notes: Any caveats (e.g., "requires Rust/wasm-pack installed")
+
+Important:
+- Look for build scripts in package.json that might generate TypeScript bindings
+- Check README for build instructions
+- For WASM projects, look for wasm-pack or similar tooling
+- The entry point should be a .ts, .tsx, or .d.ts file`;
+async function generateBuildPlan(repoDir) {
+  const hasApiKey = process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY;
+  if (!hasApiKey) {
+    return null;
+  }
+  const context = await gatherContextFiles(repoDir);
+  if (!context.trim()) {
+    return null;
+  }
+  const model = getModel();
+  const { object } = await generateObject({
+    model,
+    schema: BuildPlanSchema,
+    prompt: BUILD_PLAN_PROMPT(context)
+  });
+  return object;
+}
+
+// src/utils/monorepo-detection.ts
+import * as fs8 from "node:fs";
+import * as path9 from "node:path";
+import { glob } from "glob";
+async function detectMonorepo(repoDir) {
+  const pkgPath = path9.join(repoDir, "package.json");
+  if (!fs8.existsSync(pkgPath)) {
+    return { isMonorepo: false, packages: [], type: "none" };
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(fs8.readFileSync(pkgPath, "utf-8"));
+  } catch {
+    return { isMonorepo: false, packages: [], type: "none" };
+  }
+  if (pkg.workspaces) {
+    const patterns = extractWorkspacePatterns(pkg.workspaces);
+    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 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)) {
+    try {
+      const lerna = JSON.parse(fs8.readFileSync(lernaPath, "utf-8"));
+      const patterns = lerna.packages ?? ["packages/*"];
+      const packages = await resolveWorkspacePackages(repoDir, patterns);
+      return { isMonorepo: packages.length > 0, packages, type: "lerna" };
+    } catch {}
+  }
+  return { isMonorepo: false, packages: [], type: "none" };
+}
+function extractWorkspacePatterns(workspaces) {
+  if (Array.isArray(workspaces)) {
+    return workspaces.filter((w) => typeof w === "string");
+  }
+  if (typeof workspaces === "object" && workspaces !== null) {
+    const ws = workspaces;
+    if (Array.isArray(ws.packages)) {
+      return ws.packages.filter((w) => typeof w === "string");
+    }
+  }
+  return [];
+}
+function parsePnpmWorkspace(filePath) {
+  try {
+    const content = fs8.readFileSync(filePath, "utf-8");
+    const match = content.match(/packages:\s*\n((?:\s+-\s+.+\n?)+)/);
+    if (match) {
+      const lines = match[1].split(`
+`);
+      return lines.map((line) => line.replace(/^\s+-\s+['"]?/, "").replace(/['"]?\s*$/, "")).filter(Boolean);
+    }
+  } catch {}
+  return ["packages/*"];
+}
+async function resolveWorkspacePackages(repoDir, patterns) {
+  const packages = [];
+  for (const pattern of patterns) {
+    const normalizedPattern = pattern.endsWith("/") ? pattern.slice(0, -1) : pattern;
+    try {
+      const matches = await glob(normalizedPattern, {
+        cwd: repoDir,
+        absolute: false
+      });
+      for (const match of matches) {
+        const pkgJsonPath = path9.join(repoDir, match, "package.json");
+        if (fs8.existsSync(pkgJsonPath)) {
+          try {
+            const pkgJson = JSON.parse(fs8.readFileSync(pkgJsonPath, "utf-8"));
+            packages.push({
+              name: pkgJson.name ?? path9.basename(match),
+              path: path9.join(repoDir, match),
+              relativePath: match
+            });
+          } catch {}
+        }
+      }
+    } catch {}
+  }
+  return packages.sort((a, b) => a.name.localeCompare(b.name));
+}
+async function findPackage(repoDir, packageName) {
+  const mono = await detectMonorepo(repoDir);
+  if (!mono.isMonorepo) {
+    return;
+  }
+  return mono.packages.find((pkg) => pkg.name === packageName || pkg.relativePath === packageName);
+}
+function formatPackageList(packages, limit = 10) {
+  const lines = packages.slice(0, limit).map((pkg) => `  --package ${pkg.name}`);
+  if (packages.length > limit) {
+    lines.push(`  ... and ${packages.length - limit} more`);
+  }
+  return lines.join(`
+`);
+}
+
+// src/commands/scan.ts
+var defaultDependencies5 = {
+  createDocCov: (options) => new DocCov3(options),
+  spinner: (text) => ora3(text),
+  log: console.log,
+  error: console.error
+};
+function registerScanCommand(program, dependencies = {}) {
+  const { createDocCov, spinner, log, error } = {
+    ...defaultDependencies5,
+    ...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) => {
+    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("");
+      tempDir = path10.join(os.tmpdir(), `doccov-scan-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+      fs9.mkdirSync(tempDir, { recursive: true });
+      const cloneSpinner = spinner(`Cloning ${parsed.owner}/${parsed.repo}...`);
+      cloneSpinner.start();
+      try {
+        const git = simpleGit();
+        await git.clone(cloneUrl, tempDir, [
+          "--depth",
+          "1",
+          "--branch",
+          parsed.ref,
+          "--single-branch"
+        ]);
+        cloneSpinner.succeed(`Cloned ${parsed.owner}/${parsed.repo}`);
+      } catch (cloneError) {
+        cloneSpinner.fail("Failed to clone repository");
+        const message = cloneError instanceof Error ? cloneError.message : String(cloneError);
+        if (message.includes("not found") || message.includes("404")) {
+          throw new Error(`Repository not accessible or does not exist: ${displayUrl}`);
+        }
+        if (message.includes("Could not find remote branch")) {
+          throw new Error(`Branch or tag not found: ${parsed.ref}`);
+        }
+        throw new Error(`Clone failed: ${message}`);
+      }
+      if (options.skipInstall) {
+        log(chalk6.gray("Skipping dependency installation (--skip-install)"));
+      } else {
+        const installSpinner = spinner("Installing dependencies...");
+        installSpinner.start();
+        const installErrors = [];
+        try {
+          const { execSync } = await import("node:child_process");
+          const lockfileCommands = [
+            { file: "pnpm-lock.yaml", cmd: "pnpm install --frozen-lockfile" },
+            { file: "bun.lock", cmd: "bun install --frozen-lockfile" },
+            { file: "bun.lockb", cmd: "bun install --frozen-lockfile" },
+            { file: "yarn.lock", cmd: "yarn install --frozen-lockfile" },
+            { file: "package-lock.json", cmd: "npm install --legacy-peer-deps" }
+          ];
+          let installed = false;
+          for (const { file, cmd } of lockfileCommands) {
+            if (fs9.existsSync(path10.join(tempDir, file))) {
+              try {
+                execSync(cmd, {
+                  cwd: tempDir,
+                  stdio: "pipe",
+                  timeout: 180000
+                });
+                installed = true;
+                break;
+              } catch (cmdError) {
+                const stderr = cmdError?.stderr?.toString() ?? "";
+                const msg = cmdError instanceof Error ? cmdError.message : String(cmdError);
+                installErrors.push(`[${cmd}] ${stderr.slice(0, 150) || msg.slice(0, 150)}`);
+              }
+            }
+          }
+          if (!installed) {
+            try {
+              execSync("bun install", {
+                cwd: tempDir,
+                stdio: "pipe",
+                timeout: 120000
+              });
+              installed = true;
+            } catch (bunError) {
+              const stderr = bunError?.stderr?.toString() ?? "";
+              const msg = bunError instanceof Error ? bunError.message : String(bunError);
+              installErrors.push(`[bun install] ${stderr.slice(0, 150) || msg.slice(0, 150)}`);
+              try {
+                execSync("npm install --legacy-peer-deps --ignore-scripts", {
+                  cwd: tempDir,
+                  stdio: "pipe",
+                  timeout: 180000
+                });
+                installed = true;
+              } catch (npmError) {
+                const npmStderr = npmError?.stderr?.toString() ?? "";
+                const npmMsg = npmError instanceof Error ? npmError.message : String(npmError);
+                installErrors.push(`[npm install] ${npmStderr.slice(0, 150) || npmMsg.slice(0, 150)}`);
+              }
+            }
+          }
+          if (installed) {
+            installSpinner.succeed("Dependencies installed");
+          } else {
+            installSpinner.warn("Could not install dependencies (analysis may be limited)");
+            for (const err of installErrors) {
+              log(chalk6.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}`));
+          }
+        }
+      }
+      let targetDir = tempDir;
+      let packageName;
+      const mono = await detectMonorepo(tempDir);
+      if (mono.isMonorepo) {
+        if (!options.package) {
+          error("");
+          error(chalk6.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 = await findPackage(tempDir, options.package);
+        if (!pkg) {
+          error("");
+          error(chalk6.red(`Package "${options.package}" not found. Available packages:`));
+          error("");
+          error(formatPackageList(mono.packages));
+          error("");
+          throw new Error(`Package not found: ${options.package}`);
+        }
+        targetDir = pkg.path;
+        packageName = pkg.name;
+        log(chalk6.gray(`Analyzing package: ${packageName}`));
+      }
+      const entrySpinner = spinner("Detecting entry point...");
+      entrySpinner.start();
+      let entryPath;
+      const needsBuildStep = (pkgDir, repoRoot, entryFile) => {
+        if (!entryFile.endsWith(".d.ts"))
+          return false;
+        const cargoLocations = [
+          path10.join(pkgDir, "Cargo.toml"),
+          path10.join(repoRoot, "Cargo.toml")
+        ];
+        const hasCargoToml = cargoLocations.some((p) => fs9.existsSync(p));
+        const checkWasmScripts = (dir) => {
+          const pkgPath = path10.join(dir, "package.json");
+          if (fs9.existsSync(pkgPath)) {
+            try {
+              const pkg = JSON.parse(fs9.readFileSync(pkgPath, "utf-8"));
+              const scripts = Object.values(pkg.scripts ?? {}).join(" ");
+              return scripts.includes("wasm-pack") || scripts.includes("wasm");
+            } catch {}
+          }
+          return false;
+        };
+        const hasWasmPackScript = checkWasmScripts(pkgDir) || checkWasmScripts(repoRoot);
+        return hasCargoToml || hasWasmPackScript;
+      };
+      let buildFailed = false;
+      const runLlmFallback = async (reason) => {
+        entrySpinner.text = `${reason}, trying LLM fallback...`;
+        const plan = await generateBuildPlan(targetDir);
+        if (!plan) {
+          return null;
+        }
+        if (plan.buildCommands.length > 0) {
+          const { execSync } = await import("node:child_process");
+          for (const cmd of plan.buildCommands) {
+            log(chalk6.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)`));
+              } else if (msg.includes("rimraf") || msg.includes("command not found")) {
+                log(chalk6.yellow(`  ⚠ Build failed: missing dependencies`));
+              } else {
+                log(chalk6.yellow(`  ⚠ Build failed: ${msg.slice(0, 80)}`));
+              }
+            }
+          }
+        }
+        if (plan.notes) {
+          log(chalk6.gray(`  Note: ${plan.notes}`));
+        }
+        return plan.entryPoint;
+      };
+      try {
+        const entry = detectEntryPoint(targetDir);
+        if (needsBuildStep(targetDir, tempDir, entry.entryPath)) {
+          entrySpinner.text = "Detected .d.ts entry with WASM indicators...";
+          const llmEntry = await runLlmFallback("WASM project detected");
+          if (llmEntry) {
+            entryPath = path10.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"));
+            } else {
+              entrySpinner.succeed(`Entry point: ${llmEntry} (from LLM fallback - WASM project)`);
+            }
+          } else {
+            entryPath = path10.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"));
+          }
+        } else {
+          entryPath = path10.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);
+          entrySpinner.succeed(`Entry point: ${llmEntry} (from LLM fallback)`);
+        } else {
+          entrySpinner.fail("Could not detect entry point (set OPENAI_API_KEY for smart fallback)");
+          throw entryError;
+        }
+      }
+      const analyzeSpinner = spinner("Analyzing documentation coverage...");
+      analyzeSpinner.start();
+      let result;
+      try {
+        const doccov = createDocCov({ resolveExternalTypes: true });
+        result = await doccov.analyzeFileWithDiagnostics(entryPath);
+        analyzeSpinner.succeed("Analysis complete");
+      } catch (analysisError) {
+        analyzeSpinner.fail("Analysis failed");
+        throw analysisError;
+      }
+      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 undocumented = [];
+      const driftIssues = [];
+      for (const exp of spec.exports ?? []) {
+        const expDocs = exp.docs;
+        if (!expDocs)
+          continue;
+        if ((expDocs.missing?.length ?? 0) > 0 || (expDocs.coverageScore ?? 0) < 100) {
+          undocumented.push(exp.name);
+        }
+        for (const d of expDocs.drift ?? []) {
+          driftIssues.push({
+            export: exp.name,
+            type: d.type,
+            issue: d.issue
+          });
+        }
+      }
+      const scanResult = {
+        owner: parsed.owner,
+        repo: parsed.repo,
+        ref: parsed.ref,
+        packageName,
+        coverage: coverageScore,
+        exportCount: spec.exports?.length ?? 0,
+        typeCount: spec.types?.length ?? 0,
+        driftCount: driftIssues.length,
+        undocumented,
+        drift: driftIssues
+      };
+      if (options.output === "json") {
+        log(JSON.stringify(scanResult, null, 2));
+      } else {
+        printTextResult(scanResult, log);
+      }
+    } catch (commandError) {
+      error(chalk6.red("Error:"), commandError instanceof Error ? commandError.message : commandError);
+      process.exitCode = 1;
+    } finally {
+      if (tempDir && options.cleanup !== false) {
+        const { spawn } = await import("node:child_process");
+        spawn("rm", ["-rf", tempDir], {
+          detached: true,
+          stdio: "ignore"
+        }).unref();
+      } else if (tempDir) {
+        log(chalk6.gray(`Repo preserved at: ${tempDir}`));
+      }
+    }
+  });
+}
+function printTextResult(result, log) {
+  log("");
+  log(chalk6.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("");
+  const coverageColor = result.coverage >= 80 ? chalk6.green : result.coverage >= 50 ? chalk6.yellow : chalk6.red;
+  log(chalk6.bold("Coverage"));
+  log(`  ${coverageColor(`${result.coverage}%`)}`);
+  log("");
+  log(chalk6.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"));
+    for (const name of result.undocumented.slice(0, 10)) {
+      log(chalk6.yellow(`  ! ${name}`));
+    }
+    if (result.undocumented.length > 10) {
+      log(chalk6.gray(`  ... and ${result.undocumented.length - 10} more`));
+    }
+  }
+  if (result.drift.length > 0) {
+    log("");
+    log(chalk6.bold("Drift Issues"));
+    for (const d of result.drift.slice(0, 5)) {
+      log(chalk6.red(`  • ${d.export}: ${d.issue}`));
+    }
+    if (result.drift.length > 5) {
+      log(chalk6.gray(`  ... and ${result.drift.length - 5} more`));
+    }
+  }
+  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 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);
+registerScanCommand(program);
+program.command("*", { hidden: true }).action(() => {
+  program.outputHelp();
+});
+program.parseAsync();