@driftdev/cli 1.0.0 → 1.4.0

package/README.md

@@ -44,8 +44,8 @@ Entry auto-detects from `package.json` (`types`, `exports`, `main`, `module`, `b
 
 | Command | Description |
 |---------|-------------|
-| `drift scan [entry]` | Coverage + lint + prose drift + health in one pass |
-| `drift health [entry]` | Documentation health score (default command) |
+| `drift scan [entry]` | Coverage + lint + prose drift + health in one pass (default command) |
+| `drift health [entry]` | Documentation health score |
 | `drift ci` | CI checks on changed packages with PR comments |
 
 ### Analysis
@@ -61,8 +61,8 @@ Entry auto-detects from `package.json` (`types`, `exports`, `main`, `module`, `b
 | Command | Description |
 |---------|-------------|
 | `drift extract [entry]` | Extract full API spec as JSON |
-| `drift list [entry]` | List all exports with kinds |
-| `drift get <name> [entry]` | Inspect single export detail + types |
+| `drift list [searchOrEntry]` | List all exports with kinds |
+| `drift get <name>` | Inspect single export detail + types (entry auto-detected; `drift get <entry> <name>` to override) |
 
 ### Spec Operations
 
@@ -112,8 +112,10 @@ drift --tools
 
 Run coverage + lint + prose drift + health in one pass.
 
+Default command — bare `drift` runs this.
+
 ```bash
-drift scan                    # single package
+drift scan                    # single package (bare `drift` does the same)
 drift scan --min 80           # fail if health below 80%
 drift scan --all              # all workspace packages
 drift scan --all --private    # include private packages
@@ -121,7 +123,7 @@ drift scan --all --private    # include private packages
 
 ## lint
 
-Cross-reference JSDoc against code signatures. Detects 15 drift types across 4 categories (structural, semantic, example, prose). Prose detection scans markdown files for broken import references.
+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.
 
 ```bash
 drift lint                    # single package
@@ -144,7 +146,7 @@ drift coverage --all          # all workspace packages
 Weighted health score: completeness (coverage) + accuracy (lint).
 
 ```bash
-drift health                  # default command (bare `drift`)
+drift health
 drift health --min 80
 drift health --all
 ```
@@ -201,7 +203,7 @@ All commands return structured JSON when piped or with `--json`:
 {
   "ok": true,
   "data": { "score": 88, "documented": 243, "total": 275 },
-  "meta": { "command": "coverage", "duration": 1234, "version": "0.38.0" }
+  "meta": { "command": "coverage", "duration": 1234, "version": "1.4.0" }
 }
 ```
 

package/dist/drift.js

@@ -1,13 +1,17 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -1161,26 +1165,6 @@ function registerBreakingCommand(program) {
   });
 }
 
-// src/commands/commands.ts
-var GROUPS = {
-  Composed: ["scan", "ci", "health"],
-  Analysis: ["coverage", "lint", "examples"],
-  Extraction: ["extract", "list", "get"],
-  Comparison: ["diff", "breaking", "semver", "changelog"],
-  Setup: ["init", "config", "context"],
-  Plumbing: ["validate", "filter", "cache", "report", "release"]
-};
-function registerCommandsCommand(program) {
-  program.command("commands").description("List all available commands grouped by category").action(() => {
-    const maxGroup = Math.max(...Object.keys(GROUPS).map((g) => g.length));
-    for (const [group, cmds] of Object.entries(GROUPS)) {
-      const pad2 = " ".repeat(maxGroup - group.length);
-      process.stdout.write(`  ${group}${pad2}   ${cmds.join(", ")}
-`);
-    }
-  });
-}
-
 // src/formatters/cache.ts
 function renderCacheStatus(data) {
   const lines = [];
@@ -1974,6 +1958,26 @@ function registerCiCommand(program) {
   });
 }
 
+// src/commands/commands.ts
+var GROUPS = {
+  Composed: ["scan", "ci", "health"],
+  Analysis: ["coverage", "lint", "examples"],
+  Extraction: ["extract", "list", "get"],
+  Comparison: ["diff", "breaking", "semver", "changelog"],
+  Setup: ["init", "config", "context"],
+  Plumbing: ["validate", "filter", "cache", "report", "release"]
+};
+function registerCommandsCommand(program) {
+  program.command("commands").description("List all available commands grouped by category").action(() => {
+    const maxGroup = Math.max(...Object.keys(GROUPS).map((g) => g.length));
+    for (const [group, cmds] of Object.entries(GROUPS)) {
+      const pad2 = " ".repeat(maxGroup - group.length);
+      process.stdout.write(`  ${group}${pad2}   ${cmds.join(", ")}
+`);
+    }
+  });
+}
+
 // src/commands/config.ts
 init_global();
 import { existsSync as existsSync11, mkdirSync as mkdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync4 } from "node:fs";
@@ -3162,7 +3166,7 @@ function getPackageInfo(cwd) {
   }
 }
 function registerHealthCommand(program) {
-  program.command("health [entry]").description("Show documentation health score (default command)").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").action(async (entry, options) => {
+  program.command("health [entry]").description("Show documentation health score").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").action(async (entry, options) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
@@ -4249,6 +4253,8 @@ function registerReportCommand(program) {
 // src/commands/scan.ts
 import { existsSync as existsSync16, readFileSync as readFileSync20 } from "node:fs";
 import * as path27 from "node:path";
+import { fromSource } from "@driftdev/clarity-adapter";
+import { fromDocument } from "@driftdev/openapi-adapter";
 import {
   buildExportRegistry as buildExportRegistry2,
   computeDrift as computeDrift8,
@@ -4327,11 +4333,59 @@ function getPackageInfo2(cwd) {
     return {};
   }
 }
+async function loadSpec2(entryFile, lang, abiPath, specPath) {
+  if (lang === "openapi") {
+    if (!specPath)
+      throw new Error("--spec is required when --lang openapi");
+    if (!existsSync16(specPath))
+      throw new Error(`Spec file not found: ${specPath}`);
+    const document = readFileSync20(specPath, "utf-8");
+    const name = path27.basename(specPath, path27.extname(specPath));
+    const apiSpec = fromDocument(document);
+    if (!apiSpec.meta.name || apiSpec.meta.name === "openapi")
+      apiSpec.meta.name = name;
+    return { apiSpec, packageName: apiSpec.meta.name, packageVersion: apiSpec.meta.version };
+  }
+  if (lang === "clarity") {
+    if (!abiPath)
+      throw new Error("--abi is required when --lang clarity");
+    if (!existsSync16(entryFile))
+      throw new Error(`Source file not found: ${entryFile}`);
+    if (!existsSync16(abiPath))
+      throw new Error(`ABI file not found: ${abiPath}`);
+    const source = readFileSync20(entryFile, "utf-8");
+    const abi = JSON.parse(readFileSync20(abiPath, "utf-8"));
+    const name = path27.basename(entryFile, path27.extname(entryFile));
+    const pkg2 = getPackageInfo2(process.cwd());
+    const apiSpec = fromSource(source, abi, { name, version: pkg2.version });
+    return { apiSpec, packageName: pkg2.name ?? name, packageVersion: pkg2.version };
+  }
+  const { spec } = await cachedExtract(entryFile);
+  const pkg = getPackageInfo2(process.cwd());
+  return { apiSpec: spec, packageName: pkg.name, packageVersion: pkg.version };
+}
 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").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", "typescript").option("--abi <path>", "ABI JSON file (required for --lang clarity)").option("--spec <path>", "OpenAPI document (required for --lang openapi)").action(async (entry, options) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
+      const lang = options.lang ?? "typescript";
+      if (lang !== "typescript" && lang !== "clarity" && lang !== "openapi") {
+        formatError("scan", `Unknown language: ${lang}`, startTime, version);
+        return;
+      }
+      if (lang !== "typescript" && options.all) {
+        formatError("scan", `Batch mode (--all) not yet supported for ${lang}`, startTime, version);
+        return;
+      }
+      if (lang === "clarity" && !options.abi) {
+        formatError("scan", "--abi is required when --lang clarity", startTime, version);
+        return;
+      }
+      if (lang === "openapi" && !options.spec) {
+        formatError("scan", "--spec is required when --lang openapi", startTime, version);
+        return;
+      }
       if (options.all) {
         const allPackages = discoverPackages(process.cwd());
         if (!allPackages || allPackages.length === 0) {
@@ -4346,16 +4400,16 @@ function registerScanCommand(program) {
         }
         const rows = [];
         let anyFail = false;
-        for (const pkg2 of packages) {
-          const { spec: spec2 } = await cachedExtract(pkg2.entry);
-          const exps = spec2.exports ?? [];
+        for (const pkg of packages) {
+          const { spec } = await cachedExtract(pkg.entry);
+          const exps = spec.exports ?? [];
           let documented2 = 0;
           for (const e of exps) {
             if (e.description?.trim())
               documented2++;
           }
           const coverage = exps.length > 0 ? Math.round(documented2 / exps.length * 100) : 100;
-          const driftResult2 = computeDrift8(spec2);
+          const driftResult2 = computeDrift8(spec);
           const issues2 = [];
           for (const [exportName, drifts] of driftResult2.exports) {
             for (const d of drifts)
@@ -4366,7 +4420,7 @@ function registerScanCommand(program) {
           if (min2 !== undefined && h2.health < min2)
             anyFail = true;
           rows.push({
-            name: pkg2.name,
+            name: pkg.name,
             exports: exps.length,
             coverage,
             lintIssues: issues2.length,
@@ -4385,9 +4439,13 @@ function registerScanCommand(program) {
         return;
       }
       const { config } = loadConfig();
-      const entryFile = entry ? path27.resolve(process.cwd(), entry) : config.entry ? path27.resolve(process.cwd(), config.entry) : detectEntry();
-      const { spec } = await cachedExtract(entryFile);
-      const exports = spec.exports ?? [];
+      const specPath = options.spec ? path27.resolve(process.cwd(), options.spec) : undefined;
+      const entryFile = lang === "openapi" ? specPath : entry ? path27.resolve(process.cwd(), entry) : lang === "clarity" ? (() => {
+        throw new Error("Entry file required for --lang clarity");
+      })() : config.entry ? path27.resolve(process.cwd(), config.entry) : detectEntry();
+      const abiPath = options.abi ? path27.resolve(process.cwd(), options.abi) : undefined;
+      const { apiSpec, packageName, packageVersion } = await loadSpec2(entryFile, lang, abiPath, specPath);
+      const exports = apiSpec.exports ?? [];
       const total = exports.length;
       let documented = 0;
       for (const exp of exports) {
@@ -4395,7 +4453,7 @@ function registerScanCommand(program) {
           documented++;
       }
       const coverageScore = total > 0 ? Math.round(documented / total * 100) : 100;
-      const driftResult = computeDrift8(spec);
+      const driftResult = computeDrift8(apiSpec);
       const issues = [];
       for (const [exportName, drifts] of driftResult.exports) {
         for (const drift of drifts) {
@@ -4408,30 +4466,35 @@ function registerScanCommand(program) {
           });
         }
       }
-      try {
-        const pkgJsonPath = path27.resolve(process.cwd(), "package.json");
-        const pkgJson = JSON.parse(readFileSync20(pkgJsonPath, "utf-8"));
-        const packageName = pkgJson.name;
-        if (packageName) {
-          const registry = buildExportRegistry2(spec);
-          const markdownFiles = discoverMarkdownFiles2(process.cwd(), config.docs);
-          const proseDrifts = detectProseDrift2({ packageName, markdownFiles, registry });
-          for (const drift of proseDrifts) {
-            issues.push({
-              export: drift.target ?? "",
-              issue: drift.issue,
-              ...drift.suggestion ? { location: drift.suggestion } : {},
-              filePath: drift.filePath,
-              line: drift.line
+      if (lang === "typescript") {
+        try {
+          const pkgJsonPath = path27.resolve(process.cwd(), "package.json");
+          const pkgJson = JSON.parse(readFileSync20(pkgJsonPath, "utf-8"));
+          const pkgName = pkgJson.name;
+          if (pkgName) {
+            const registry = buildExportRegistry2(apiSpec);
+            const markdownFiles = discoverMarkdownFiles2(process.cwd(), config.docs);
+            const proseDrifts = detectProseDrift2({
+              packageName: pkgName,
+              markdownFiles,
+              registry
             });
+            for (const drift of proseDrifts) {
+              issues.push({
+                export: drift.target ?? "",
+                issue: drift.issue,
+                ...drift.suggestion ? { location: drift.suggestion } : {},
+                filePath: drift.filePath,
+                line: drift.line
+              });
+            }
           }
+        } catch (err) {
+          formatWarning(`Prose drift skipped: ${err instanceof Error ? err.message : String(err)}`);
         }
-      } catch (err) {
-        formatWarning(`Prose drift skipped: ${err instanceof Error ? err.message : String(err)}`);
       }
       const healthIssues = issues.map((i) => ({ export: i.export, issue: i.issue }));
       const h = computeHealth(total, documented, healthIssues);
-      const pkg = getPackageInfo2(process.cwd());
       let min = options.min ? parseInt(options.min, 10) : config.coverage?.min;
       if (min !== undefined && config.coverage?.ratchet) {
         const ratchet = computeRatchetMin(min);
@@ -4443,8 +4506,8 @@ function registerScanCommand(program) {
         lint: { issues, count: issues.length },
         health: h.health,
         pass,
-        packageName: pkg.name,
-        packageVersion: pkg.version
+        packageName,
+        packageVersion
       };
       let next;
       if (issues.length > 0) {
@@ -4645,11 +4708,20 @@ function extractCapabilities(program) {
       }
     ],
     workflows: {
-      "detect-drift": { steps: ["extract", "lint"], description: "Find stale JSDoc and prose drift" },
+      "detect-drift": {
+        steps: ["extract", "lint"],
+        description: "Find stale JSDoc and prose drift"
+      },
       "full-scan": { steps: ["scan"], description: "Coverage + lint + prose in one pass" },
-      "detect-and-enrich": { steps: ["scan", "context"], description: "Scan and generate agent context" },
+      "detect-and-enrich": {
+        steps: ["scan", "context"],
+        description: "Scan and generate agent context"
+      },
       "ci-pipeline": { steps: ["ci"], description: "Run CI checks on changed packages" },
-      "pre-release": { steps: ["scan", "breaking", "release"], description: "Full pre-release quality gate" }
+      "pre-release": {
+        steps: ["scan", "breaking", "release"],
+        description: "Full pre-release quality gate"
+      }
     }
   };
 }
@@ -4659,7 +4731,7 @@ var __filename2 = fileURLToPath2(import.meta.url);
 var __dirname3 = path29.dirname(__filename2);
 var packageJson = JSON.parse(readFileSync22(path29.join(__dirname3, "../package.json"), "utf-8"));
 var program = new Command;
-program.name("drift").description("drift — documentation quality for TypeScript").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) => {
+program.name("drift").description("drift — documentation quality for TypeScript, Clarity, and OpenAPI").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(path29.resolve(opts.cwd));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftdev/cli",
-  "version": "1.0.0",
+  "version": "1.4.0",
   "description": "Drift CLI - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",
@@ -19,17 +19,9 @@
   "license": "MIT",
   "author": "Ryan Waits",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "bin": {
     "drift": "./dist/drift.js"
   },
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
   "scripts": {
     "build": "bunup",
     "dev": "bunup --watch",
@@ -37,22 +29,28 @@
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
     "format": "biome format --write src/",
-    "test": "for f in test/*.test.ts; do bun test \"$f\" || exit 1; done"
+    "prepublishOnly": "bun run build",
+    "test": "bun run --cwd ../sdk build && bun run --cwd ../adapters/clarity build && bun run --cwd ../adapters/openapi build && for f in test/*.test.ts; do bun test \"$f\" || exit 1; done"
   },
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
-    "@driftdev/sdk": "^1.0.0",
-    "@openpkg-ts/sdk": "^0.37.0",
+    "@driftdev/clarity-adapter": "^1.0.1",
+    "@driftdev/openapi-adapter": "^1.0.0",
+    "@driftdev/sdk": "^1.4.0",
+    "@openpkg-ts/sdk": "^0.38.0",
     "@openpkg-ts/spec": "^0.37.0",
     "chalk": "^5.4.1",
     "commander": "^14.0.0"
   },
   "devDependencies": {
-    "@types/bun": "latest",
-    "@types/node": "^20.0.0",
-    "bunup": "latest"
+    "@types/bun": "^1.3.14",
+    "@types/node": "^24.0.0",
+    "bunup": "0.16.26"
   },
   "publishConfig": {
     "access": "public"