@driftdev/cli 1.5.1 → 1.7.0

package/README.md

@@ -123,7 +123,7 @@ drift scan --all --private    # include private packages
 
 ## lint
 
-Cross-reference JSDoc against code signatures. Detects 16 drift types across 4 categories (structural, semantic, example, prose). Prose detection scans markdown files for broken import references and method calls that don't exist on any exported type.
+Cross-reference JSDoc against code signatures. Detects 17 drift types across 4 categories (structural, semantic, example, prose). Prose detection scans markdown files for broken import references, method calls that don't exist on any exported type, and references to deprecated APIs with no deprecation note.
 
 ```bash
 drift lint                    # single package

package/dist/drift.js

@@ -51,8 +51,8 @@ function getGlobalConfigPath() {
 var init_global = () => {};
 
 // src/drift.ts
-import { readFileSync as readFileSync22 } from "node:fs";
-import * as path30 from "node:path";
+import { readFileSync as readFileSync21 } from "node:fs";
+import * as path31 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { Command } from "commander";
 
@@ -2260,13 +2260,15 @@ function registerContextCommand(program) {
 
 // src/commands/coverage.ts
 import * as path16 from "node:path";
+import { isExternalExport } from "@driftdev/sdk";
 
 // src/formatters/coverage.ts
 function renderCoverage(data) {
   const lines = [""];
   const color = coverageColor(data.score);
   const bar = progressBar(data.score);
-  lines.push(indent(`Coverage  ${color(`${data.score}%`)}  ${bar}  (${data.documented}/${data.total})`));
+  const externalNote = data.external ? c.gray(`  +${data.external} external (not resolvable here)`) : "";
+  lines.push(indent(`Coverage  ${color(`${data.score}%`)}  ${bar}  (${data.documented}/${data.total})${externalNote}`));
   lines.push("");
   if (data.undocumented.length > 0) {
     lines.push(indent(c.gray("UNDOCUMENTED")));
@@ -2411,7 +2413,7 @@ function registerCoverageCommand(program) {
         let totalAll = 0;
         for (const pkg of packages) {
           const { spec: spec2 } = await cachedExtract(pkg.entry);
-          const exps = spec2.exports ?? [];
+          const exps = (spec2.exports ?? []).filter((e) => !isExternalExport(e));
           let doc = 0;
           for (const e of exps) {
             if (e.description?.trim())
@@ -2445,7 +2447,9 @@ function registerCoverageCommand(program) {
         spec: options.spec,
         abi: options.abi
       });
-      const exports = spec.exports ?? [];
+      const allExports = spec.exports ?? [];
+      const exports = allExports.filter((exp) => !isExternalExport(exp));
+      const external = allExports.length - exports.length;
       const total = exports.length;
       const undocumented = [];
       for (const exp of exports) {
@@ -2455,7 +2459,13 @@ function registerCoverageCommand(program) {
       }
       const documented = total - undocumented.length;
       const score = total > 0 ? Math.round(documented / total * 100) : 100;
-      const data = { score, documented, total, undocumented };
+      const data = {
+        score,
+        documented,
+        total,
+        undocumented,
+        ...external > 0 ? { external } : {}
+      };
       const next = undocumented.length > 0 ? {
         suggested: "drift-enrich skill",
         reason: `${undocumented.length} exports lack documentation`
@@ -3319,7 +3329,7 @@ function renderNotFound(exportName, suggestions, startTime, version) {
 
 // src/commands/health.ts
 import * as path22 from "node:path";
-import { computeDrift as computeDrift3 } from "@driftdev/sdk";
+import { computeDrift as computeDrift3, isExternalExport as isExternalExport2 } from "@driftdev/sdk";
 
 // src/formatters/health.ts
 function renderHealth(data, next) {
@@ -3334,7 +3344,8 @@ function renderHealth(data, next) {
   lines.push(indent(`${sym.branch} completeness  ${data.completeness}%  (${data.undocumented} missing docs)`));
   lines.push(indent(`${sym.end} accuracy      ${data.accuracy}%  (${data.drifted} stale signatures)`));
   lines.push("");
-  lines.push(indent(`${data.totalExports} exports  ${c.gray(sym.dot)}  ${data.documented} documented  ${c.gray(sym.dot)}  ${data.drifted} drifted`));
+  const externalNote = data.external ? `  ${c.gray(sym.dot)}  ${c.gray(`${data.external} external (not resolvable here)`)}` : "";
+  lines.push(indent(`${data.totalExports} exports  ${c.gray(sym.dot)}  ${data.documented} documented  ${c.gray(sym.dot)}  ${data.drifted} drifted${externalNote}`));
   lines.push("");
   if (data.issues.length > 0) {
     lines.push(indent("Top issues"));
@@ -3417,7 +3428,7 @@ function registerHealthCommand(program) {
         let totalAll = 0;
         for (const pkg of packages) {
           const { spec: spec2 } = await cachedExtract(pkg.entry);
-          const exps = spec2.exports ?? [];
+          const exps = (spec2.exports ?? []).filter((e) => !isExternalExport2(e));
           let doc = 0;
           for (const e of exps) {
             if (e.description?.trim())
@@ -3447,7 +3458,9 @@ function registerHealthCommand(program) {
         packageName,
         packageVersion
       } = await resolveTruth({ entry: entryFile, lang, spec: options.spec, abi: options.abi });
-      const exports = spec.exports ?? [];
+      const allExports = spec.exports ?? [];
+      const exports = allExports.filter((exp) => !isExternalExport2(exp));
+      const external = allExports.length - exports.length;
       const total = exports.length;
       let documented = 0;
       for (const exp of exports) {
@@ -3465,6 +3478,7 @@ function registerHealthCommand(program) {
       const health = computeHealth(total, documented, issues);
       const data = {
         ...health,
+        ...external > 0 ? { external } : {},
         packageName,
         packageVersion
       };
@@ -3894,14 +3908,8 @@ function registerInitCommand(program) {
 }
 
 // src/commands/lint.ts
-import { readFileSync as readFileSync17 } from "node:fs";
-import * as path24 from "node:path";
-import {
-  buildExportRegistry,
-  computeDrift as computeDrift4,
-  detectProseDrift,
-  discoverMarkdownFiles
-} from "@driftdev/sdk";
+import * as path25 from "node:path";
+import { buildExportRegistry, computeDrift as computeDrift4, detectProseDrift } from "@driftdev/sdk";
 
 // src/formatters/lint.ts
 function renderLint(data, next) {
@@ -3937,9 +3945,47 @@ function renderLint(data, next) {
 `);
 }
 
+// src/utils/docs-corpus.ts
+import { readFileSync as readFileSync17, statSync as statSync2 } from "node:fs";
+import * as path24 from "node:path";
+import { discoverMarkdownFiles } from "@driftdev/sdk";
+function resolveDocsCorpus(cwd, docsPatterns, configDocs) {
+  if (!docsPatterns || docsPatterns.length === 0) {
+    return discoverMarkdownFiles(cwd, configDocs);
+  }
+  const include = [];
+  for (const pattern of docsPatterns) {
+    if (isDirectory(path24.resolve(cwd, pattern))) {
+      include.push(path24.join(pattern, "**/*.md"), path24.join(pattern, "**/*.mdx"));
+    } else {
+      include.push(pattern);
+    }
+  }
+  const files = discoverMarkdownFiles(cwd, { include });
+  if (files.length === 0) {
+    formatWarning(`--docs matched no markdown files: ${docsPatterns.join(", ")}`);
+  }
+  return files;
+}
+function isDirectory(p) {
+  try {
+    return statSync2(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function readPackageName(cwd = process.cwd()) {
+  try {
+    const pkgJson = JSON.parse(readFileSync17(path24.resolve(cwd, "package.json"), "utf-8"));
+    return typeof pkgJson.name === "string" ? pkgJson.name : undefined;
+  } catch {
+    return;
+  }
+}
+
 // src/commands/lint.ts
 function registerLintCommand(program) {
-  program.command("lint [entry]").description("Cross-reference docs against the API surface for accuracy issues").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").action(async (entry, options) => {
+  program.command("lint [entry]").description("Cross-reference docs against the API surface for accuracy issues").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").option("--docs <patterns...>", "Markdown corpus for prose drift: glob patterns or directories (overrides repo-local defaults)").action(async (entry, options) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
@@ -3991,9 +4037,9 @@ function registerLintCommand(program) {
         formatOutput("lint", { issues: [], count: 0 }, startTime, version, renderLint);
         return;
       }
-      let entryFile = entry ? path24.resolve(process.cwd(), entry) : undefined;
+      let entryFile = entry ? path25.resolve(process.cwd(), entry) : undefined;
       if (lang === "typescript" && !entryFile) {
-        entryFile = config.entry ? path24.resolve(process.cwd(), config.entry) : detectEntry();
+        entryFile = config.entry ? path25.resolve(process.cwd(), config.entry) : detectEntry();
       }
       const { apiSpec: spec } = await resolveTruth({
         entry: entryFile,
@@ -4014,14 +4060,12 @@ function registerLintCommand(program) {
           });
         }
       }
-      if (lang === "typescript")
+      if (lang === "typescript" || options.docs)
         try {
-          const pkgJsonPath = path24.resolve(process.cwd(), "package.json");
-          const pkgJson = JSON.parse(readFileSync17(pkgJsonPath, "utf-8"));
-          const packageName = pkgJson.name;
+          const packageName = readPackageName() ?? spec.meta?.name;
           if (packageName) {
             const registry = buildExportRegistry(spec);
-            const markdownFiles = discoverMarkdownFiles(process.cwd(), config.docs);
+            const markdownFiles = resolveDocsCorpus(process.cwd(), options.docs, config.docs);
             const proseDrifts = detectProseDrift({ packageName, markdownFiles, registry });
             for (const drift of proseDrifts) {
               issues.push({
@@ -4059,7 +4103,7 @@ function registerLintCommand(program) {
 }
 
 // src/commands/list.ts
-import * as path25 from "node:path";
+import * as path26 from "node:path";
 import { computeDrift as computeDrift5 } from "@driftdev/sdk";
 import { listExports as listExports2 } from "@openpkg-ts/sdk";
 
@@ -4174,7 +4218,7 @@ function registerListCommand(program) {
       } else {
         let entryFile;
         if (searchOrEntry && looksLikeFilePath(searchOrEntry)) {
-          entryFile = path25.resolve(process.cwd(), searchOrEntry);
+          entryFile = path26.resolve(process.cwd(), searchOrEntry);
         } else if (searchOrEntry) {
           entryFile = detectEntry();
           searchTerm = searchOrEntry;
@@ -4250,7 +4294,7 @@ function truthFlags(args) {
   return out;
 }
 function runDrift(cliArgs, cwd) {
-  return new Promise((resolve18) => {
+  return new Promise((resolve19) => {
     const child = spawn(process.execPath, [process.argv[1], ...cliArgs, "--json"], {
       cwd: cwd ?? process.cwd(),
       env: { ...process.env, NO_COLOR: "1" },
@@ -4270,9 +4314,9 @@ function runDrift(cliArgs, cwd) {
       try {
         ok = JSON.parse(stdout).ok === true;
       } catch {}
-      resolve18({ text, ok });
+      resolve19({ text, ok });
     });
-    child.on("error", (err) => resolve18({ text: `Failed to run drift: ${err.message}`, ok: false }));
+    child.on("error", (err) => resolve19({ text: `Failed to run drift: ${err.message}`, ok: false }));
   });
 }
 function toResult({ text, ok }) {
@@ -4386,7 +4430,7 @@ function diffArgs(command, args) {
 // src/commands/release.ts
 import { execSync as execSync4 } from "node:child_process";
 import { existsSync as existsSync14, readFileSync as readFileSync18 } from "node:fs";
-import * as path26 from "node:path";
+import * as path27 from "node:path";
 import { computeDrift as computeDrift6 } from "@driftdev/sdk";
 
 // src/formatters/release.ts
@@ -4434,7 +4478,7 @@ function getLastTag() {
   }
 }
 function getPackageVersion(cwd) {
-  const pkgPath = path26.join(cwd, "package.json");
+  const pkgPath = path27.join(cwd, "package.json");
   if (!existsSync14(pkgPath))
     return null;
   try {
@@ -4450,7 +4494,7 @@ function registerReleaseCommand(program) {
     const cwd = process.cwd();
     try {
       const { config } = loadConfig();
-      const entryFile = entry ? path26.resolve(cwd, entry) : config.entry ? path26.resolve(cwd, config.entry) : detectEntry();
+      const entryFile = entry ? path27.resolve(cwd, entry) : config.entry ? path27.resolve(cwd, config.entry) : detectEntry();
       const { spec } = await cachedExtract(entryFile);
       const exports = spec.exports ?? [];
       const total = exports.length;
@@ -4575,7 +4619,7 @@ function renderReport(data) {
 // src/utils/scan-packages.ts
 import { execSync as execSync5 } from "node:child_process";
 import { existsSync as existsSync15, readFileSync as readFileSync19 } from "node:fs";
-import * as path27 from "node:path";
+import * as path28 from "node:path";
 import { computeDrift as computeDrift7 } from "@driftdev/sdk";
 function detectPackageDirs2(cwd) {
   const workspaces = detectWorkspaces(cwd);
@@ -4594,11 +4638,11 @@ async function scanAllPackages(cwd) {
   const packageDirs = detectPackageDirs2(cwd);
   const results = [];
   for (const dir of packageDirs) {
-    const absDir = dir === "." ? cwd : path27.join(cwd, dir);
+    const absDir = dir === "." ? cwd : path28.join(cwd, dir);
     if (!existsSync15(absDir))
       continue;
     let name = dir;
-    const pkgPath = path27.join(absDir, "package.json");
+    const pkgPath = path28.join(absDir, "package.json");
     if (existsSync15(pkgPath)) {
       try {
         const pkg = JSON.parse(readFileSync19(pkgPath, "utf-8"));
@@ -4697,13 +4741,12 @@ function registerReportCommand(program) {
 }
 
 // src/commands/scan.ts
-import { readFileSync as readFileSync20 } from "node:fs";
-import * as path28 from "node:path";
+import * as path29 from "node:path";
 import {
   buildExportRegistry as buildExportRegistry2,
   computeDrift as computeDrift8,
   detectProseDrift as detectProseDrift2,
-  discoverMarkdownFiles as discoverMarkdownFiles2
+  isExternalExport as isExternalExport3
 } from "@driftdev/sdk";
 
 // src/formatters/scan.ts
@@ -4716,7 +4759,8 @@ function renderScan(data, next) {
   }
   const hColor = coverageColor(data.health);
   lines.push(indent(`Health     ${hColor(`${data.health}%`)}`));
-  lines.push(indent(`Coverage   ${coverageColor(data.coverage.score)(`${data.coverage.score}%`)}  (${data.coverage.documented}/${data.coverage.total} exports)`));
+  const externalNote = data.coverage.external ? c.gray(`  +${data.coverage.external} external (not resolvable here)`) : "";
+  lines.push(indent(`Coverage   ${coverageColor(data.coverage.score)(`${data.coverage.score}%`)}  (${data.coverage.documented}/${data.coverage.total} exports)${externalNote}`));
   lines.push(indent(`Lint       ${data.lint.count === 0 ? c.green("0 issues") : c.red(`${data.lint.count} issues`)}`));
   lines.push("");
   if (data.lint.count > 0) {
@@ -4766,7 +4810,7 @@ function renderBatchScan(data) {
 
 // src/commands/scan.ts
 function registerScanCommand(program) {
-  program.command("scan [entry]").description("Run coverage + lint + prose drift in one pass").option("--min <n>", "Minimum health threshold (exit 1 if below)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").action(async (entry, options) => {
+  program.command("scan [entry]").description("Run coverage + lint + prose drift in one pass").option("--min <n>", "Minimum health threshold (exit 1 if below)").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").option("--lang <language>", "Source language (inferred from --spec/--abi/.clar; default typescript)").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document: path or URL (implies --lang openapi)").option("--docs <patterns...>", "Markdown corpus for prose drift: glob patterns or directories (overrides repo-local defaults)").action(async (entry, options) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
@@ -4804,7 +4848,7 @@ function registerScanCommand(program) {
         let anyFail = false;
         for (const pkg of packages) {
           const { spec } = await cachedExtract(pkg.entry);
-          const exps = spec.exports ?? [];
+          const exps = (spec.exports ?? []).filter((e) => !isExternalExport3(e));
           let documented2 = 0;
           for (const e of exps) {
             if (e.description?.trim())
@@ -4841,9 +4885,9 @@ function registerScanCommand(program) {
         return;
       }
       const { config } = loadConfig();
-      let entryFile = entry ? path28.resolve(process.cwd(), entry) : undefined;
+      let entryFile = entry ? path29.resolve(process.cwd(), entry) : undefined;
       if (lang === "typescript" && !entryFile) {
-        entryFile = config.entry ? path28.resolve(process.cwd(), config.entry) : detectEntry();
+        entryFile = config.entry ? path29.resolve(process.cwd(), config.entry) : detectEntry();
       }
       const { apiSpec, packageName, packageVersion } = await resolveTruth({
         entry: entryFile,
@@ -4851,7 +4895,9 @@ function registerScanCommand(program) {
         spec: options.spec,
         abi: options.abi
       });
-      const exports = apiSpec.exports ?? [];
+      const allExports = apiSpec.exports ?? [];
+      const exports = allExports.filter((exp) => !isExternalExport3(exp));
+      const external = allExports.length - exports.length;
       const total = exports.length;
       let documented = 0;
       for (const exp of exports) {
@@ -4872,14 +4918,12 @@ function registerScanCommand(program) {
           });
         }
       }
-      if (lang === "typescript") {
+      if (lang === "typescript" || options.docs) {
         try {
-          const pkgJsonPath = path28.resolve(process.cwd(), "package.json");
-          const pkgJson = JSON.parse(readFileSync20(pkgJsonPath, "utf-8"));
-          const pkgName = pkgJson.name;
+          const pkgName = readPackageName() ?? packageName;
           if (pkgName) {
             const registry = buildExportRegistry2(apiSpec);
-            const markdownFiles = discoverMarkdownFiles2(process.cwd(), config.docs);
+            const markdownFiles = resolveDocsCorpus(process.cwd(), options.docs, config.docs);
             const proseDrifts = detectProseDrift2({
               packageName: pkgName,
               markdownFiles,
@@ -4908,7 +4952,13 @@ function registerScanCommand(program) {
       }
       const pass = min === undefined || h.health >= min;
       const data = {
-        coverage: { score: coverageScore, documented, total, undocumented: total - documented },
+        coverage: {
+          score: coverageScore,
+          documented,
+          total,
+          undocumented: total - documented,
+          ...external > 0 ? { external } : {}
+        },
         lint: { issues, count: issues.length },
         health: h.health,
         pass,
@@ -4981,8 +5031,8 @@ function registerSemverCommand(program) {
 }
 
 // src/commands/validate.ts
-import { readFileSync as readFileSync21 } from "node:fs";
-import * as path29 from "node:path";
+import { readFileSync as readFileSync20 } from "node:fs";
+import * as path30 from "node:path";
 import { validateSpec } from "@openpkg-ts/spec";
 
 // src/formatters/validate.ts
@@ -5008,8 +5058,8 @@ function registerValidateCommand(program) {
     const startTime = Date.now();
     const version = getVersion();
     try {
-      const filePath = path29.resolve(process.cwd(), file);
-      const content = readFileSync21(filePath, "utf-8");
+      const filePath = path30.resolve(process.cwd(), file);
+      const content = readFileSync20(filePath, "utf-8");
       const spec = JSON.parse(content);
       const result = validateSpec(spec);
       const data = {
@@ -5134,13 +5184,13 @@ function extractCapabilities(program) {
 
 // src/drift.ts
 var __filename2 = fileURLToPath2(import.meta.url);
-var __dirname3 = path30.dirname(__filename2);
-var packageJson = JSON.parse(readFileSync22(path30.join(__dirname3, "../package.json"), "utf-8"));
+var __dirname3 = path31.dirname(__filename2);
+var packageJson = JSON.parse(readFileSync21(path31.join(__dirname3, "../package.json"), "utf-8"));
 var program = new Command;
 program.name("drift").description("drift — detect when your docs drift from your code").version(packageJson.version).option("--json", "Force JSON output (default when piped)").option("--human", "Force human-readable output (default in terminal)").option("--config <path>", "Path to drift config file").option("--cwd <dir>", "Run as if started in <dir>").option("--no-cache", "Bypass spec cache").option("--tools", "List all available tools for agent use (JSON)").hook("preAction", (_thisCommand) => {
   const opts = program.opts();
   if (opts.cwd) {
-    process.chdir(path30.resolve(opts.cwd));
+    process.chdir(path31.resolve(opts.cwd));
   }
   setOutputMode({ json: opts.json, human: opts.human });
   setConfigPath(opts.config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftdev/cli",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "Drift CLI - detect when your docs drift from your code",
   "keywords": [
     "typescript",
@@ -46,7 +46,7 @@
   "dependencies": {
     "@driftdev/clarity-adapter": "^1.0.1",
     "@driftdev/openapi-adapter": "^1.0.1",
-    "@driftdev/sdk": "^1.4.0",
+    "@driftdev/sdk": "^1.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openpkg-ts/sdk": "^0.38.0",
     "@openpkg-ts/spec": "^0.37.0",