@driftdev/cli 0.35.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ryan Waits
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# @driftdev/cli
+
+Command-line interface for documentation coverage analysis and drift detection. Ships as the `drift` binary.
+
+## Install
+
+```bash
+bun add -g @driftdev/cli
+```
+
+## Quick Start
+
+```bash
+# Full scan: coverage + lint + prose drift + health
+drift scan
+
+# Check documentation coverage
+drift coverage
+
+# Find JSDoc accuracy issues
+drift lint
+
+# Validate @example blocks
+drift examples
+```
+
+Entry auto-detects from `package.json` — works in any TypeScript project.
+
+## Commands
+
+### Composed
+
+| Command | Description |
+|---------|-------------|
+| `drift scan [entry]` | Coverage + lint + prose drift + health in one pass |
+| `drift health [entry]` | Documentation health score (default command) |
+| `drift ci` | CI checks on changed packages with PR comments |
+
+### Analysis
+
+| Command | Description |
+|---------|-------------|
+| `drift coverage [entry]` | Documentation coverage score |
+| `drift lint [entry]` | Cross-reference JSDoc vs code signatures |
+| `drift examples [entry]` | Validate @example blocks (presence, typecheck, run) |
+
+### Extraction
+
+| 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 |
+
+### Spec Operations
+
+| Command | Description |
+|---------|-------------|
+| `drift validate <spec>` | Validate a spec file |
+| `drift filter <spec>` | Filter exports by kind, search, tag |
+
+### Comparison
+
+| Command | Description |
+|---------|-------------|
+| `drift diff <old> <new>` | What changed between two specs |
+| `drift breaking <old> <new>` | Detect breaking changes |
+| `drift semver <old> <new>` | Recommend semver bump |
+| `drift changelog <old> <new>` | Generate changelog |
+
+### Setup & Plumbing
+
+| Command | Description |
+|---------|-------------|
+| `drift init` | Create configuration file |
+| `drift config` | Manage config (list, get, set) |
+| `drift context` | Generate agent context file |
+| `drift report` | Documentation trends from history |
+| `drift release` | Pre-release documentation audit |
+| `drift cache` | Cache management (clear, status) |
+
+### Discovery
+
+```bash
+# Machine-readable list of all commands + flags
+drift --capabilities
+```
+
+## Global Options
+
+```
+--json          Force JSON output (default when piped)
+--human         Force human-readable output (default in terminal)
+--config <path> Path to drift config file
+--cwd <dir>     Run as if started in <dir>
+--no-cache      Bypass spec cache
+```
+
+## scan
+
+Run coverage + lint + prose drift + health in one pass.
+
+```bash
+drift scan                    # single package
+drift scan --min 80           # fail if health below 80%
+drift scan --all              # all workspace packages
+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.
+
+```bash
+drift lint                    # single package
+drift lint --all              # all workspace packages
+drift lint --json             # JSON output with filePath/line
+```
+
+## coverage
+
+Documentation coverage score.
+
+```bash
+drift coverage                # single package
+drift coverage --min 80       # fail if below 80%
+drift coverage --all          # all workspace packages
+```
+
+## health
+
+Weighted health score: completeness (coverage) + accuracy (lint).
+
+```bash
+drift health                  # default command (bare `drift`)
+drift health --min 80
+drift health --all
+```
+
+## examples
+
+Validate @example blocks.
+
+```bash
+drift examples                # presence check
+drift examples --typecheck    # type-check examples
+drift examples --run          # execute examples
+drift examples --min 50       # fail if example coverage below 50%
+```
+
+## ci
+
+CI checks with GitHub integration: PR comments, step summaries, history tracking.
+
+```bash
+drift ci                      # check changed packages
+drift ci --all                # check all packages
+drift ci --private            # include private packages
+```
+
+Generates `~/.drift/projects/<slug>/context.md` — machine-readable project state for agents.
+
+## Configuration
+
+### drift.config.json
+
+```json
+{
+  "entry": "src/index.ts",
+  "coverage": {
+    "min": 80,
+    "ratchet": true
+  },
+  "lint": true,
+  "docs": {
+    "include": ["README.md", "docs/**/*.md"],
+    "exclude": ["node_modules/**"]
+  }
+}
+```
+
+See [Configuration docs](../../docs/configuration.md) for all keys and `drift config` commands.
+
+## Output Format
+
+All commands return structured JSON when piped or with `--json`:
+
+```json
+{
+  "ok": true,
+  "data": { "score": 88, "documented": 243, "total": 275 },
+  "meta": { "command": "coverage", "duration": 1234, "version": "0.34.3" }
+}
+```
+
+Human-readable output in terminal by default, or with `--human`.
+
+## Monorepo Support
+
+All analysis commands support `--all` for workspace batch mode:
+
+```bash
+drift scan --all              # scan all packages
+drift coverage --all          # coverage per package
+drift lint --all              # lint per package
+```
+
+Auto-detects workspace globs from `package.json`.
+
+## License
+
+MIT

package/dist/config/index.d.ts

@@ -0,0 +1,9 @@
+import { DocCovConfig as DocCovConfig2, DocCovConfigInput, DocsConfig } from "@driftdev/sdk";
+import { DocCovConfig } from "@driftdev/sdk";
+declare const DRIFT_CONFIG_FILENAMES: readonly ["drift.config.ts", "drift.config.mts", "drift.config.js", "drift.config.mjs"];
+interface LoadedDriftTsConfig extends DocCovConfig {
+	filePath: string;
+}
+declare const loadDriftTsConfig: (cwd: string) => Promise<LoadedDriftTsConfig | null>;
+declare const defineConfig: (config: DocCovConfigInput) => DocCovConfigInput;
+export { loadDriftTsConfig, defineConfig, LoadedDriftTsConfig, DocsConfig, DocCovConfigInput, DocCovConfig2 as DocCovConfig, DRIFT_CONFIG_FILENAMES };

package/dist/config/index.js

@@ -0,0 +1,108 @@
+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 __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/config/drift-ts-config.ts
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { docCovConfigSchema, normalizeConfig } from "@driftdev/sdk";
+var DRIFT_CONFIG_FILENAMES = [
+  "drift.config.ts",
+  "drift.config.mts",
+  "drift.config.js",
+  "drift.config.mjs"
+];
+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 DRIFT_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 loadDriftTsConfig = 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 drift 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 drift configuration at ${configPath}.
+${formatIssues(issues)}`);
+  }
+  const normalized = normalizeConfig(parsed.data);
+  return {
+    filePath: configPath,
+    ...normalized
+  };
+};
+
+// src/config/index.ts
+var defineConfig = (config) => config;
+export {
+  loadDriftTsConfig,
+  defineConfig,
+  DRIFT_CONFIG_FILENAMES
+};