@driftdev/cli 1.9.0 → 1.11.0

package/dist/drift.js

@@ -573,8 +573,13 @@ async function extractSpecFromRef(ref, entry, cwd = process.cwd()) {
 }
 
 // src/utils/output.ts
+function elapsed(startTime) {
+  if (process.env.SOURCE_DATE_EPOCH !== undefined)
+    return 0;
+  return Date.now() - startTime;
+}
 function formatOutput(command, data, startTime, version, humanRenderer, next) {
-  const duration = Date.now() - startTime;
+  const duration = elapsed(startTime);
   const envelope = {
     ok: true,
     data,
@@ -593,8 +598,8 @@ function formatOutput(command, data, startTime, version, humanRenderer, next) {
   }
   return envelope;
 }
-function formatError(command, error, startTime, version, suggestion) {
-  const duration = Date.now() - startTime;
+function formatError(command, error, startTime, version, suggestion, exitCode = 2) {
+  const duration = elapsed(startTime);
   if (shouldRenderHuman()) {
     process.stdout.write(`
   ${c.red("x")} ${error}
@@ -615,7 +620,7 @@ function formatError(command, error, startTime, version, suggestion) {
     process.stderr.write(`drift ${command} failed: ${error}
 `);
   }
-  process.exitCode = 1;
+  process.exitCode = exitCode;
 }
 function formatWarning(message) {
   if (shouldRenderHuman()) {
@@ -710,7 +715,8 @@ function validateConfig(raw) {
   }
   if (errors.length > 0)
     return { ok: false, errors };
-  return { ok: true, config: mergeDefaults(obj) };
+  const { $schema: _schema, ...rest } = obj;
+  return { ok: true, config: mergeDefaults(rest) };
 }
 
 // src/config/loader.ts
@@ -3321,9 +3327,9 @@ function renderNotFound(exportName, suggestions, startTime, version) {
 `));
     process.exitCode = 1;
   } else if (suggestions.length > 0) {
-    formatError("get", `Export '${exportName}' not found. Similar: ${suggestions.join(", ")}`, startTime, version);
+    formatError("get", `Export '${exportName}' not found. Similar: ${suggestions.join(", ")}`, startTime, version, undefined, 1);
   } else {
-    formatError("get", `Export '${exportName}' not found`, startTime, version);
+    formatError("get", `Export '${exportName}' not found`, startTime, version, undefined, 1);
   }
 }
 
@@ -3857,6 +3863,7 @@ function generateConfig(packages) {
   const worstCoverage = Math.min(...packages.map((p) => p.coverage));
   const threshold = Math.max(0, Math.floor(worstCoverage) - 5);
   return {
+    $schema: "https://unpkg.com/@driftdev/cli/schemas/drift.config.schema.json",
     coverage: { min: threshold }
   };
 }
@@ -3945,6 +3952,26 @@ function renderLint(data, next) {
 `);
 }
 
+// src/utils/annotations.ts
+function escapeData(value) {
+  return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function escapeProperty(value) {
+  return escapeData(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+function emitAnnotations(issues, level = "error") {
+  for (const issue of issues) {
+    const props = [];
+    if (issue.filePath)
+      props.push(`file=${escapeProperty(issue.filePath)}`);
+    if (issue.line !== undefined)
+      props.push(`line=${issue.line}`);
+    props.push(`title=${escapeProperty(`drift: ${issue.export || "docs"}`)}`);
+    process.stdout.write(`::${level} ${props.join(",")}::${escapeData(issue.issue)}
+`);
+  }
+}
+
 // src/utils/docs-corpus.ts
 import { readFileSync as readFileSync17, statSync as statSync2 } from "node:fs";
 import * as path24 from "node:path";
@@ -3985,7 +4012,7 @@ function readPackageName(cwd = process.cwd()) {
 
 // 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)").option("--docs <patterns...>", "Markdown corpus for prose drift: glob patterns or directories (overrides repo-local defaults)").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)").option("--annotations", "Emit GitHub Actions ::error annotations for findings").action(async (entry, options) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
@@ -4086,6 +4113,8 @@ function registerLintCommand(program) {
         reason: `${issues.length} issue${issues.length === 1 ? "" : "s"} found`
       } : undefined;
       formatOutput("lint", data, startTime, version, renderLint, next);
+      if (options.annotations && issues.length > 0)
+        emitAnnotations(issues);
       if (issues.length > 0) {
         if (!shouldRenderHuman()) {
           process.stderr.write(`${issues.length} issue${issues.length === 1 ? "" : "s"} found
@@ -4385,6 +4414,51 @@ function registerMcpCommand(program) {
         cli.push("--min", String(args.min));
       return toResult(await runDrift([...cli, ...truthFlags(args)], args.cwd));
     });
+    server.registerTool("drift_lint", {
+      title: "Lint docs accuracy",
+      description: "Cross-reference docs against the real API surface: wrong parameter names/types, stale signatures, references to removed exports, prose drift in markdown docs. Returns issues with file/line locations. The primary fix loop: lint, fix what it reports, lint again until clean.",
+      inputSchema: {
+        ...truthShape,
+        docs: z.array(z.string()).optional().describe("Markdown corpus for prose drift: glob patterns or directories (overrides repo-local defaults)")
+      }
+    }, async (args) => {
+      const cli = ["lint"];
+      if (args.entry)
+        cli.push(args.entry);
+      if (args.docs?.length)
+        cli.push("--docs", ...args.docs);
+      return toResult(await runDrift([...cli, ...truthFlags(args)], args.cwd));
+    });
+    server.registerTool("drift_coverage", {
+      title: "Measure docs coverage",
+      description: "Documentation coverage of an API surface: documented vs total exports, score, what is missing per rule. Use to find undocumented surface before writing docs.",
+      inputSchema: {
+        ...truthShape,
+        min: z.number().optional().describe("Minimum coverage % (result fails below it)")
+      }
+    }, async (args) => {
+      const cli = ["coverage"];
+      if (args.entry)
+        cli.push(args.entry);
+      if (args.min !== undefined)
+        cli.push("--min", String(args.min));
+      return toResult(await runDrift([...cli, ...truthFlags(args)], args.cwd));
+    });
+    server.registerTool("drift_health", {
+      title: "Docs health score",
+      description: "Combined docs health score (coverage + accuracy) for an API surface, with the breakdown. The single number to gate on in CI.",
+      inputSchema: {
+        ...truthShape,
+        min: z.number().optional().describe("Minimum health % (result fails below it)")
+      }
+    }, async (args) => {
+      const cli = ["health"];
+      if (args.entry)
+        cli.push(args.entry);
+      if (args.min !== undefined)
+        cli.push("--min", String(args.min));
+      return toResult(await runDrift([...cli, ...truthFlags(args)], args.cwd));
+    });
     server.registerTool("drift_diff", {
       title: "Diff two API specs",
       description: "Diff two extracted API specs (TypeScript only today): spec files or git refs. Reports added/removed/changed exports. Useful for changelog and release-note verification.",
@@ -5243,5 +5317,5 @@ if (userArgs.length === 0 && !hasHelpOrVersion) {
   process.argv.splice(2, 0, "scan");
 }
 program.parseAsync().catch(() => {
-  process.exit(1);
+  process.exit(2);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftdev/cli",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "Drift CLI - detect when your docs drift from your code",
   "keywords": [
     "typescript",
@@ -38,7 +38,8 @@
     "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"
+    "dist",
+    "schemas"
   ],
   "engines": {
     "node": ">=20"
@@ -46,10 +47,10 @@
   "dependencies": {
     "@driftdev/clarity-adapter": "^1.0.1",
     "@driftdev/openapi-adapter": "^1.0.1",
-    "@driftdev/sdk": "^1.9.0",
+    "@driftdev/sdk": "^1.11.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@openpkg-ts/sdk": "^0.40.0",
-    "@openpkg-ts/spec": "^0.37.0",
+    "@openpkg-ts/sdk": "^0.43.0",
+    "@openpkg-ts/spec": "^0.43.0",
     "chalk": "^5.4.1",
     "commander": "^14.0.0",
     "zod": "^4.2.1"

package/schemas/drift.config.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/@driftdev/cli/schemas/drift.config.schema.json",
+  "title": "Drift configuration",
+  "description": "Configuration for the drift CLI, loaded from drift.config.json or the \"drift\" key in package.json. JSON only — no code execution.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Path or URL of this schema, for editor/agent validation"
+    },
+    "entry": {
+      "type": "string",
+      "description": "Entry point override (otherwise auto-detected)"
+    },
+    "include": {
+      "description": "Export include patterns",
+      "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }]
+    },
+    "exclude": {
+      "description": "Export exclude patterns",
+      "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }]
+    },
+    "coverage": {
+      "type": "object",
+      "description": "Coverage thresholds",
+      "properties": {
+        "min": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Minimum coverage % (exit 1 if below)"
+        },
+        "ratchet": {
+          "type": "boolean",
+          "description": "Ratchet: effective min = max(min, highest coverage ever recorded)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "lint": {
+      "type": "boolean",
+      "default": true,
+      "description": "Enable lint checks"
+    },
+    "docs": {
+      "type": "object",
+      "description": "Markdown docs discovery",
+      "properties": {
+        "include": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Glob patterns for markdown docs to include"
+        },
+        "exclude": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Glob patterns for markdown docs to exclude"
+        },
+        "remote": {
+          "type": "array",
+          "description": "Remote repos to sync docs on breaking changes",
+          "items": {
+            "type": "object",
+            "properties": {
+              "repo": {
+                "type": "string",
+                "pattern": "^[^/]+/[^/]+$",
+                "description": "Target repo in \"owner/repo\" format"
+              },
+              "branch": {
+                "type": "string",
+                "description": "Target branch (defaults to repo's default branch)"
+              }
+            },
+            "required": ["repo"],
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": true
+}