@driftdev/cli 0.36.0 → 0.38.0

package/dist/drift.js

@@ -175286,6 +175286,25 @@ function validateConfig(raw) {
       if (docs.exclude !== undefined && (!Array.isArray(docs.exclude) || !docs.exclude.every((i) => typeof i === "string"))) {
         errors.push('"docs.exclude" must be an array of strings');
       }
+      if (docs.remote !== undefined) {
+        if (!Array.isArray(docs.remote)) {
+          errors.push('"docs.remote" must be an array');
+        } else {
+          for (let i = 0;i < docs.remote.length; i++) {
+            const target = docs.remote[i];
+            if (typeof target !== "object" || target === null) {
+              errors.push(`"docs.remote[${i}]" must be an object`);
+              continue;
+            }
+            if (typeof target.repo !== "string" || !/^[^/]+\/[^/]+$/.test(target.repo)) {
+              errors.push(`"docs.remote[${i}].repo" must be in "owner/repo" format`);
+            }
+            if (target.branch !== undefined && typeof target.branch !== "string") {
+              errors.push(`"docs.remote[${i}].branch" must be a string`);
+            }
+          }
+        }
+      }
     }
   }
   if (errors.length > 0)
@@ -175651,14 +175670,17 @@ function renderBatchLint(data) {
 function renderBatchList(data) {
   const lines = [""];
   const rows = data.packages;
+  const columnLabel = data.filter === "undocumented" ? "UNDOCUMENTED" : "EXPORTS";
   const nameW = Math.max(7, ...rows.map((r) => r.name.length));
-  lines.push(indent(`${c.gray(pad("PACKAGE", nameW))}  ${c.gray("EXPORTS")}`));
+  lines.push(indent(`${c.gray(pad("PACKAGE", nameW))}  ${c.gray(columnLabel)}`));
   for (const r of rows) {
-    lines.push(indent(`${pad(r.name, nameW)}  ${r.count}`));
+    const countStr = data.filter === "undocumented" ? r.count === 0 ? c.green("0") : c.yellow(String(r.count)) : String(r.count);
+    lines.push(indent(`${pad(r.name, nameW)}  ${countStr}`));
   }
   const total = rows.reduce((s, r) => s + r.count, 0);
   lines.push("");
-  lines.push(indent(`${c.bold("Total")}: ${total} exports across ${rows.length} packages`));
+  const label = data.filter === "undocumented" ? "undocumented exports" : "exports";
+  lines.push(indent(`${c.bold("Total")}: ${total} ${label} across ${rows.length} packages`));
   lines.push("");
   return lines.join(`
 `);
@@ -175681,6 +175703,54 @@ function renderBatchExamples(data) {
   return lines.join(`
 `);
 }
+function renderBatchDiff(data) {
+  const lines = [""];
+  const rows = data.packages;
+  const nameW = Math.max(7, ...rows.map((r) => r.name.length));
+  lines.push(indent(`${c.gray(pad("PACKAGE", nameW))}  ${c.gray(pad("BREAKING", 8))}  ${c.gray(pad("ADDED", 5))}  ${c.gray("CHANGED")}`));
+  for (const r of rows) {
+    const bStr = pad(String(r.breaking), 8);
+    const aStr = pad(String(r.added), 5);
+    const cStr = String(r.changed);
+    const breaking = r.breaking === 0 ? c.green(bStr) : c.red(bStr);
+    const added = r.added === 0 ? aStr : c.green(aStr);
+    const changed = r.changed === 0 ? cStr : c.yellow(cStr);
+    lines.push(indent(`${pad(r.name, nameW)}  ${breaking}  ${added}  ${changed}`));
+  }
+  lines.push("");
+  const parts = [];
+  if (data.aggregate.breaking > 0)
+    parts.push(`${data.aggregate.breaking} breaking`);
+  if (data.aggregate.added > 0)
+    parts.push(`${data.aggregate.added} added`);
+  if (data.aggregate.changed > 0)
+    parts.push(`${data.aggregate.changed} changed`);
+  lines.push(indent(`${c.bold("Total")}: ${parts.length > 0 ? parts.join(", ") : "no changes"}`));
+  if (data.skipped && data.skipped.length > 0) {
+    lines.push(indent(`${c.gray(`Skipped ${data.skipped.length} private: ${data.skipped.join(", ")}`)}`));
+  }
+  lines.push("");
+  return lines.join(`
+`);
+}
+function renderBatchBreaking(data) {
+  const lines = [""];
+  const rows = data.packages;
+  const nameW = Math.max(7, ...rows.map((r) => r.name.length));
+  lines.push(indent(`${c.gray(pad("PACKAGE", nameW))}  ${c.gray("BREAKING")}`));
+  for (const r of rows) {
+    const count = r.count === 0 ? c.green("0") : c.red(String(r.count));
+    lines.push(indent(`${pad(r.name, nameW)}  ${count}`));
+  }
+  lines.push("");
+  lines.push(indent(`${c.bold("Total")}: ${data.aggregate.count} breaking change${data.aggregate.count === 1 ? "" : "s"}`));
+  if (data.skipped && data.skipped.length > 0) {
+    lines.push(indent(`${c.gray(`Skipped ${data.skipped.length} private: ${data.skipped.join(", ")}`)}`));
+  }
+  lines.push("");
+  return lines.join(`
+`);
+}
 function pad(s, w) {
   return s + " ".repeat(Math.max(0, w - s.length));
 }
@@ -176013,7 +176083,7 @@ function getPackageInfo(cwd) {
   }
 }
 function registerHealthCommand(program) {
-  program.command("health [entry]", { isDefault: true }).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 (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) => {
     const startTime = Date.now();
     const version = getVersion();
     try {
@@ -176105,7 +176175,7 @@ function registerHealthCommand(program) {
 import { readFileSync as readFileSync15 } from "node:fs";
 import * as path19 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { diffSpec as diffSpec3, categorizeBreakingChanges as categorizeBreakingChanges2 } from "@openpkg-ts/spec";
+import { diffSpec as diffSpec3, categorizeBreakingChanges as categorizeBreakingChanges2, normalize as normalize4 } from "@openpkg-ts/spec";
 
 // src/formatters/breaking.ts
 function renderBreaking(data) {
@@ -176128,17 +176198,20 @@ function renderBreaking(data) {
 `);
 }
 
-// src/utils/resolve-specs.ts
-import { readFileSync as readFileSync14 } from "node:fs";
-import * as path18 from "node:path";
-import { normalize as normalize3 } from "@openpkg-ts/spec";
-
 // src/utils/git-extract.ts
 import { execSync } from "node:child_process";
 import { existsSync as existsSync14, mkdirSync as mkdirSync4, mkdtempSync, rmSync as rmSync2, symlinkSync, writeFileSync as writeFileSync4, cpSync } from "node:fs";
 import * as os4 from "node:os";
 import * as path17 from "node:path";
 import { normalize as normalize2 } from "@openpkg-ts/spec";
+function getGitRoot(cwd) {
+  return execSync("git rev-parse --show-toplevel", {
+    encoding: "utf-8",
+    cwd,
+    timeout: 5000,
+    stdio: ["pipe", "pipe", "pipe"]
+  }).trim();
+}
 function listFilesAtRef(ref, prefix, cwd) {
   try {
     const output = execSync(`git ls-tree -r --name-only ${ref} -- ${prefix}`, {
@@ -176178,19 +176251,21 @@ function validateRef(ref, cwd = process.cwd()) {
   }
 }
 async function extractSpecFromRef(ref, entry, cwd = process.cwd()) {
-  const relEntry = path17.relative(cwd, path17.resolve(cwd, entry));
-  const entryDir = path17.dirname(relEntry);
+  const gitRoot = getGitRoot(cwd);
+  const absEntry = path17.resolve(cwd, entry);
+  const repoRelEntry = path17.relative(gitRoot, absEntry);
+  const entryDir = path17.dirname(repoRelEntry);
   const srcPrefix = entryDir.includes("/") ? entryDir.split("/").slice(0, 2).join("/") : ".";
   const tmpDir = mkdtempSync(path17.join(os4.tmpdir(), "drift-git-"));
   try {
     const prefixes = srcPrefix === "." ? [""] : [srcPrefix];
     const rootFiles = ["tsconfig.json", "tsconfig.base.json", "package.json"];
     for (const prefix of prefixes) {
-      const files = listFilesAtRef(ref, prefix || ".", cwd);
+      const files = listFilesAtRef(ref, prefix || ".", gitRoot);
       for (const file of files) {
         if (!file.match(/\.(ts|tsx|json|js|mjs|cjs)$/))
           continue;
-        const content = getFileAtRef(ref, file, cwd);
+        const content = getFileAtRef(ref, file, gitRoot);
         if (content === null)
           continue;
         const destPath = path17.join(tmpDir, file);
@@ -176201,7 +176276,7 @@ async function extractSpecFromRef(ref, entry, cwd = process.cwd()) {
     for (const rootFile of rootFiles) {
       const dest = path17.join(tmpDir, rootFile);
       if (!existsSync14(dest)) {
-        const content = getFileAtRef(ref, rootFile, cwd);
+        const content = getFileAtRef(ref, rootFile, gitRoot);
         if (content) {
           writeFileSync4(dest, content);
         }
@@ -176212,8 +176287,15 @@ async function extractSpecFromRef(ref, entry, cwd = process.cwd()) {
     if (existsSync14(nmSrc) && !existsSync14(nmDest)) {
       symlinkSync(nmSrc, nmDest, "dir");
     }
+    if (cwd !== gitRoot) {
+      const rootNm = path17.join(gitRoot, "node_modules");
+      const rootNmDest = path17.join(tmpDir, "node_modules");
+      if (existsSync14(rootNm) && !existsSync14(rootNmDest)) {
+        symlinkSync(rootNm, rootNmDest, "dir");
+      }
+    }
     if (srcPrefix !== ".") {
-      const nestedNm = path17.join(cwd, srcPrefix, "node_modules");
+      const nestedNm = path17.join(gitRoot, srcPrefix, "node_modules");
       const nestedDest = path17.join(tmpDir, srcPrefix, "node_modules");
       if (existsSync14(nestedNm) && !existsSync14(nestedDest)) {
         symlinkSync(nestedNm, nestedDest, "dir");
@@ -176224,9 +176306,9 @@ async function extractSpecFromRef(ref, entry, cwd = process.cwd()) {
     if (existsSync14(tsconfigSrc) && !existsSync14(tsconfigDest)) {
       cpSync(tsconfigSrc, tsconfigDest);
     }
-    const entryFile = path17.join(tmpDir, relEntry);
+    const entryFile = path17.join(tmpDir, repoRelEntry);
     if (!existsSync14(entryFile)) {
-      throw new Error(`Entry file not found at ref ${ref}: ${relEntry}`);
+      throw new Error(`Entry file not found at ref ${ref}: ${repoRelEntry}`);
     }
     const result = await extract({ entryFile });
     return normalize2(result.spec);
@@ -176236,6 +176318,9 @@ async function extractSpecFromRef(ref, entry, cwd = process.cwd()) {
 }
 
 // src/utils/resolve-specs.ts
+import { readFileSync as readFileSync14 } from "node:fs";
+import * as path18 from "node:path";
+import { normalize as normalize3 } from "@openpkg-ts/spec";
 function loadSpec(filePath) {
   return JSON.parse(readFileSync14(path18.resolve(process.cwd(), filePath), "utf-8"));
 }
@@ -176294,10 +176379,52 @@ function getVersion2() {
   }
 }
 function registerBreakingCommand(program) {
-  program.command("breaking [old] [new]").description("Detect breaking changes between two specs").option("--base <ref>", "Git ref for old spec").option("--head <ref>", "Git ref for new spec (default: working tree)").option("--entry <file>", "Entry file for git ref extraction").action(async (oldPath, newPath, options) => {
+  program.command("breaking [old] [new]").description("Detect breaking changes between two specs").option("--base <ref>", "Git ref for old spec").option("--head <ref>", "Git ref for new spec (default: working tree)").option("--entry <file>", "Entry file for git ref extraction").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").action(async (oldPath, newPath, options) => {
     const startTime = Date.now();
     const version = getVersion2();
     try {
+      const cwd = process.cwd();
+      const allPackages = options.all ? discoverPackages(cwd) : null;
+      const autoDetected = !options.all && options.base && !options.entry && !oldPath ? discoverPackages(cwd) : null;
+      const batchPackages = allPackages ?? autoDetected;
+      if (batchPackages && batchPackages.length > 0 && options.base) {
+        const skipped = options.private ? [] : batchPackages.filter((p) => p.private).map((p) => p.name);
+        const packages = options.private ? batchPackages : filterPublic(batchPackages);
+        if (packages.length === 0) {
+          formatError("breaking", "No workspace packages found", startTime, version);
+          return;
+        }
+        const rows = [];
+        let totalBreaking = 0;
+        for (const pkg of packages) {
+          const relEntry = path19.relative(cwd, pkg.entry);
+          const oldSpec2 = await extractSpecFromRef(options.base, relEntry, cwd);
+          let newSpec2;
+          if (options.head) {
+            newSpec2 = await extractSpecFromRef(options.head, relEntry, cwd);
+          } else {
+            const result = await extract({ entryFile: pkg.entry });
+            newSpec2 = normalize4(result.spec);
+          }
+          const diff2 = diffSpec3(oldSpec2, newSpec2);
+          const breaking2 = categorizeBreakingChanges2(diff2.breaking, oldSpec2, newSpec2);
+          rows.push({ name: pkg.name, breaking: breaking2, count: breaking2.length });
+          totalBreaking += breaking2.length;
+        }
+        const data2 = { packages: rows, aggregate: { count: totalBreaking }, ...skipped.length > 0 ? { skipped } : {} };
+        formatOutput("breaking", data2, startTime, version, renderBatchBreaking);
+        if (totalBreaking > 0) {
+          if (!shouldRenderHuman()) {
+            process.stderr.write(`${totalBreaking} breaking change${totalBreaking === 1 ? "" : "s"} found
+`);
+          }
+          process.exitCode = 1;
+        } else if (!shouldRenderHuman()) {
+          process.stderr.write(`No breaking changes
+`);
+        }
+        return;
+      }
       const args = [oldPath, newPath].filter(Boolean);
       const { oldSpec, newSpec } = await resolveSpecs({ args, ...options });
       const diff = diffSpec3(oldSpec, newSpec);
@@ -176517,6 +176644,7 @@ import { existsSync as existsSync17, readFileSync as readFileSync20 } from "node
 import * as path24 from "node:path";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 import { computeDrift as computeDrift2 } from "@driftdev/sdk";
+import { diffSpec as diffSpec6, categorizeBreakingChanges as categorizeBreakingChanges4 } from "@openpkg-ts/spec";
 
 // src/formatters/ci.ts
 function renderCi(data) {
@@ -176771,25 +176899,109 @@ function filterChangedPackages(allDirs, changedFiles) {
     return changedFiles.some((f) => prefix === "" || f.startsWith(prefix));
   });
 }
-function buildMarkdownTable(results, pass) {
+function buildPRComment(results, pass, commit) {
   const lines = [];
-  lines.push(`## Drift CI Results
+  const multi = results.length > 1;
+  lines.push(`## Drift CI
 `);
   lines.push("| Package | Exports | Coverage | Lint | Status |");
   lines.push("|---------|---------|----------|------|--------|");
   for (const r of results) {
-    const cov = r.coveragePass ? `${r.coverage}%` : `${r.coverage}% ❌`;
-    const lint = r.lintPass ? `${r.lintIssues} issues` : `${r.lintIssues} issues ❌`;
-    const status = r.pass ? "✅" : "❌";
+    const cov = r.coveragePass ? `${r.coverage}%` : `${r.coverage}% :x:`;
+    const lint = r.lintPass ? `${r.lintIssues}` : `${r.lintIssues} :x:`;
+    const status = r.pass ? ":white_check_mark:" : ":x:";
     lines.push(`| ${r.name} | ${r.exports} | ${cov} | ${lint} | ${status} |`);
   }
+  const apiEntries = [];
+  for (const r of results) {
+    if (!r.diff)
+      continue;
+    const { breaking, added, changed } = r.diff;
+    if (breaking.length === 0 && added.length === 0 && changed.length === 0)
+      continue;
+    const pkgLines = [];
+    if (multi)
+      pkgLines.push(`
+**${r.name}**`);
+    for (const name of added)
+      pkgLines.push(`- :heavy_plus_sign: Added: \`${name}\``);
+    for (const name of changed)
+      pkgLines.push(`- :pencil2: Changed: \`${name}\``);
+    for (const b of breaking)
+      pkgLines.push(`- :x: Removed: \`${b.name}\``);
+    apiEntries.push(pkgLines.join(`
+`));
+  }
+  if (apiEntries.length > 0) {
+    const total = results.reduce((s, r) => s + (r.diff ? r.diff.breaking.length + r.diff.added.length + r.diff.changed.length : 0), 0);
+    lines.push("");
+    lines.push(`<details>
+<summary>API Changes (${total})</summary>
+`);
+    lines.push(apiEntries.join(`
+`));
+    lines.push(`
+</details>`);
+  }
+  const breakingEntries = [];
+  for (const r of results) {
+    if (!r.diff?.breaking.length)
+      continue;
+    const pkgLines = [];
+    if (multi)
+      pkgLines.push(`
+**${r.name}**`);
+    for (const b of r.diff.breaking) {
+      pkgLines.push(`- \`${b.name}\`${b.reason ? `: ${b.reason}` : ""}`);
+    }
+    breakingEntries.push(pkgLines.join(`
+`));
+  }
+  if (breakingEntries.length > 0) {
+    const total = results.reduce((s, r) => s + (r.diff?.breaking.length ?? 0), 0);
+    lines.push("");
+    lines.push(`<details>
+<summary>Breaking Changes (${total})</summary>
+`);
+    lines.push(breakingEntries.join(`
+`));
+    lines.push(`
+</details>`);
+  }
+  const undocEntries = [];
+  for (const r of results) {
+    if (!r.undocumented?.length)
+      continue;
+    const pkgLines = [];
+    if (multi)
+      pkgLines.push(`
+**${r.name}**`);
+    for (const name of r.undocumented)
+      pkgLines.push(`- \`${name}\``);
+    undocEntries.push(pkgLines.join(`
+`));
+  }
+  if (undocEntries.length > 0) {
+    const total = results.reduce((s, r) => s + (r.undocumented?.length ?? 0), 0);
+    lines.push("");
+    lines.push(`<details>
+<summary>Undocumented Exports (${total})</summary>
+`);
+    lines.push(undocEntries.join(`
+`));
+    lines.push(`
+</details>`);
+  }
   lines.push("");
-  lines.push(pass ? "**All checks passed.**" : "**Some checks failed.**");
+  lines.push("---");
+  const ts18 = new Date().toISOString();
+  const sha = commit ?? "";
+  lines.push(`*[Drift](https://github.com/driftdev/drift) · ${ts18}${sha ? ` · ${sha}` : ""}*`);
   return lines.join(`
 `);
 }
 function registerCiCommand(program) {
-  program.command("ci").description("Run CI checks on changed packages").option("--all", "Check all packages, not just changed ones").option("--private", "Include private packages").action(async (options) => {
+  program.command("ci").description("Run CI checks on changed packages").option("--all", "Check all packages, not just changed ones").option("--private", "Include private packages").option("--min <number>", "Minimum coverage percentage (0-100)").action(async (options) => {
     const startTime = Date.now();
     const version = getVersion5();
     const cwd = process.cwd();
@@ -176806,7 +177018,7 @@ function registerCiCommand(program) {
       }
       if (packageDirs.length === 0)
         packageDirs = allDirs;
-      let minThreshold = config.coverage?.min ?? 0;
+      let minThreshold = options.min ? Number(options.min) : config.coverage?.min ?? 0;
       if (minThreshold > 0 && config.coverage?.ratchet) {
         const ratchet = computeRatchetMin(minThreshold);
         minThreshold = ratchet.effectiveMin;
@@ -176852,6 +177064,24 @@ function registerCiCommand(program) {
             lintIssues += drifts.length;
           }
           const lintPass = config.lint === false || lintIssues === 0;
+          let diff;
+          let undocumented;
+          if (gh.isPR && gh.baseRef) {
+            try {
+              const relEntry = path24.relative(cwd, detectEntry(absDir));
+              const oldSpec = await extractSpecFromRef(`origin/${gh.baseRef}`, relEntry, cwd);
+              const diffResult = diffSpec6(oldSpec, spec);
+              const breaking = categorizeBreakingChanges4(diffResult.breaking, oldSpec, spec);
+              diff = {
+                breaking: breaking.map((b) => ({ name: b.name, reason: b.reason })),
+                added: diffResult.nonBreaking,
+                changed: diffResult.docsOnly
+              };
+            } catch {}
+            const undoc = exports.filter((e) => !e.description?.trim()).map((e) => e.name);
+            if (undoc.length > 0)
+              undocumented = undoc;
+          }
           results.push({
             name,
             coverage,
@@ -176859,7 +177089,9 @@ function registerCiCommand(program) {
             lintIssues,
             lintPass,
             exports: total,
-            pass: coveragePass && lintPass
+            pass: coveragePass && lintPass,
+            diff,
+            undocumented
           });
         } catch {
           results.push({
@@ -176897,7 +177129,7 @@ function registerCiCommand(program) {
         });
       } catch {}
       if (gh.isPR && gh.token && gh.repository) {
-        const md = buildMarkdownTable(results, allPass);
+        const md = buildPRComment(results, allPass, commit);
         writeStepSummary(md);
         const prNumber = getPRNumber(gh.eventPath);
         if (prNumber) {
@@ -177244,7 +177476,7 @@ function registerExamplesCommand(program) {
 import { readFileSync as readFileSync23 } from "node:fs";
 import * as path27 from "node:path";
 import { fileURLToPath as fileURLToPath8 } from "node:url";
-import { diffSpec as diffSpec6, categorizeBreakingChanges as categorizeBreakingChanges4 } from "@openpkg-ts/spec";
+import { diffSpec as diffSpec7, categorizeBreakingChanges as categorizeBreakingChanges5, normalize as normalize5 } from "@openpkg-ts/spec";
 
 // src/formatters/diff.ts
 function renderDiff(data) {
@@ -177304,14 +177536,62 @@ function getVersion8() {
   }
 }
 function registerDiffCommand(program) {
-  program.command("diff [old] [new]").description("Compare two specs and show what changed").option("--base <ref>", "Git ref for old spec").option("--head <ref>", "Git ref for new spec (default: working tree)").option("--entry <file>", "Entry file for git ref extraction").action(async (oldPath, newPath, options) => {
+  program.command("diff [old] [new]").description("Compare two specs and show what changed").option("--base <ref>", "Git ref for old spec").option("--head <ref>", "Git ref for new spec (default: working tree)").option("--entry <file>", "Entry file for git ref extraction").option("--all", "Run across all workspace packages").option("--private", "Include private packages in --all mode").action(async (oldPath, newPath, options) => {
     const startTime = Date.now();
     const version = getVersion8();
     try {
+      const cwd = process.cwd();
+      const allPackages = options.all ? discoverPackages(cwd) : null;
+      const autoDetected = !options.all && options.base && !options.entry && !oldPath ? discoverPackages(cwd) : null;
+      const batchPackages = allPackages ?? autoDetected;
+      if (batchPackages && batchPackages.length > 0 && options.base) {
+        const skipped = options.private ? [] : batchPackages.filter((p) => p.private).map((p) => p.name);
+        const packages = options.private ? batchPackages : filterPublic(batchPackages);
+        if (packages.length === 0) {
+          formatError("diff", "No workspace packages found", startTime, version);
+          return;
+        }
+        const rows = [];
+        let totalBreaking = 0;
+        let totalAdded = 0;
+        let totalChanged = 0;
+        for (const pkg of packages) {
+          const relEntry = path27.relative(cwd, pkg.entry);
+          const oldSpec2 = await extractSpecFromRef(options.base, relEntry, cwd);
+          let newSpec2;
+          if (options.head) {
+            newSpec2 = await extractSpecFromRef(options.head, relEntry, cwd);
+          } else {
+            const result = await extract({ entryFile: pkg.entry });
+            newSpec2 = normalize5(result.spec);
+          }
+          const diff2 = diffSpec7(oldSpec2, newSpec2);
+          rows.push({ name: pkg.name, breaking: diff2.breaking.length, added: diff2.nonBreaking.length, changed: diff2.docsOnly.length });
+          totalBreaking += diff2.breaking.length;
+          totalAdded += diff2.nonBreaking.length;
+          totalChanged += diff2.docsOnly.length;
+        }
+        const data2 = { packages: rows, aggregate: { breaking: totalBreaking, added: totalAdded, changed: totalChanged }, ...skipped.length > 0 ? { skipped } : {} };
+        formatOutput("diff", data2, startTime, version, renderBatchDiff);
+        if (!shouldRenderHuman()) {
+          const parts = [];
+          if (totalBreaking > 0)
+            parts.push(`${totalBreaking} breaking`);
+          if (totalAdded > 0)
+            parts.push(`${totalAdded} added`);
+          if (totalChanged > 0)
+            parts.push(`${totalChanged} changed`);
+          process.stderr.write(`${parts.length > 0 ? parts.join(", ") : "no changes"}
+`);
+        }
+        if (totalBreaking > 0)
+          process.exitCode = 1;
+        return;
+      }
       const args = [oldPath, newPath].filter(Boolean);
       const { oldSpec, newSpec } = await resolveSpecs({ args, ...options });
-      const diff = diffSpec6(oldSpec, newSpec);
-      const breaking = categorizeBreakingChanges4(diff.breaking, oldSpec, newSpec);
+      const diff = diffSpec7(oldSpec, newSpec);
+      const breaking = categorizeBreakingChanges5(diff.breaking, oldSpec, newSpec);
       const data = {
         breaking,
         added: diff.nonBreaking,
@@ -177347,7 +177627,7 @@ import { readFileSync as readFileSync24 } from "node:fs";
 import * as path28 from "node:path";
 import { fileURLToPath as fileURLToPath9 } from "node:url";
 import { DocCov } from "@driftdev/sdk";
-import { normalize as normalize4 } from "@openpkg-ts/spec";
+import { normalize as normalize6 } from "@openpkg-ts/spec";
 
 // src/formatters/extract.ts
 function renderExtract(data) {
@@ -177415,7 +177695,7 @@ function registerExtractCommand(program) {
           formatError("extract", "Failed to extract spec", startTime, version);
           return;
         }
-        spec = normalize4(result.spec);
+        spec = normalize6(result.spec);
       } else {
         const result = await cachedExtract(entryFile);
         spec = result.spec;
@@ -177831,7 +178111,7 @@ function flattenConfig(obj, prefix = "") {
 }
 function registerConfigCommand(program) {
   const cmd = program.command("config").description("Manage drift configuration");
-  cmd.command("list").description("Show all config values").action(() => {
+  cmd.command("list").alias("show").description("Show all config values").action(() => {
     const startTime = Date.now();
     const version = getVersion12();
     try {
@@ -178025,17 +178305,18 @@ import { existsSync as existsSync19, mkdirSync as mkdirSync7, readFileSync as re
 import * as path33 from "node:path";
 import { fileURLToPath as fileURLToPath14 } from "node:url";
 init_global();
-import { normalize as normalize5 } from "@openpkg-ts/spec";
+import { normalize as normalize7 } from "@openpkg-ts/spec";
 
 // src/formatters/init.ts
 function renderInit(data) {
   const lines = [""];
   lines.push(indent(`${data.isMonorepo ? "Monorepo" : "Project"} scan  ${c.gray(`${data.packages.length} package${data.packages.length === 1 ? "" : "s"}`)}`));
   lines.push("");
-  const header = ["PACKAGE", "ENTRY", "EXPORTS", "COVERAGE"];
+  const header = ["Package", "Exports", "Coverage", "Health"];
   const rows = data.packages.map((pkg) => {
-    const color = coverageColor(pkg.coverage);
-    return [pkg.name, pkg.entry, String(pkg.exports), color(`${pkg.coverage}%`)];
+    const covColor = coverageColor(pkg.coverage);
+    const healthColor = coverageColor(pkg.health);
+    return [pkg.name, String(pkg.exports), covColor(`${pkg.coverage}%`), healthColor(`${pkg.health}%`)];
   });
   lines.push(indent(table([header, ...rows])));
   lines.push("");
@@ -178050,6 +178331,277 @@ function renderInit(data) {
 `);
 }
 
+// src/utils/progress/spinner.ts
+import chalk3 from "chalk";
+
+// src/utils/progress/colors.ts
+import chalk2 from "chalk";
+var colors = {
+  success: chalk2.green,
+  error: chalk2.red,
+  warning: chalk2.yellow,
+  info: chalk2.cyan,
+  muted: chalk2.gray,
+  bold: chalk2.bold,
+  dim: chalk2.dim,
+  underline: chalk2.underline,
+  primary: chalk2.cyan,
+  secondary: chalk2.magenta,
+  path: chalk2.cyan,
+  number: chalk2.yellow,
+  code: chalk2.gray
+};
+var symbols = {
+  success: "✓",
+  error: "✗",
+  warning: "⚠",
+  info: "ℹ",
+  spinner: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+  bullet: "•",
+  arrow: "→",
+  arrowRight: "›",
+  line: "─",
+  corner: "└",
+  vertical: "│",
+  horizontalLine: "─"
+};
+var asciiSymbols = {
+  success: "+",
+  error: "x",
+  warning: "!",
+  info: "i",
+  spinner: ["-", "\\", "|", "/"],
+  bullet: "*",
+  arrow: "->",
+  arrowRight: ">",
+  line: "-",
+  corner: "\\",
+  vertical: "|",
+  horizontalLine: "-"
+};
+function getSymbols(unicodeSupport = true) {
+  return unicodeSupport ? symbols : asciiSymbols;
+}
+var prefix = {
+  success: colors.success(symbols.success),
+  error: colors.error(symbols.error),
+  warning: colors.warning(symbols.warning),
+  info: colors.info(symbols.info)
+};
+
+// src/utils/progress/utils.ts
+function isTTY2() {
+  return Boolean(process.stdout.isTTY);
+}
+function isCI() {
+  return Boolean(process.env.CI || process.env.GITHUB_ACTIONS || process.env.GITLAB_CI || process.env.CIRCLECI || process.env.TRAVIS || process.env.JENKINS_URL || process.env.BUILDKITE || process.env.TEAMCITY_VERSION || process.env.TF_BUILD || process.env.CODEBUILD_BUILD_ID || process.env.BITBUCKET_BUILD_NUMBER);
+}
+function isInteractive() {
+  return isTTY2() && !isCI();
+}
+function supportsUnicode() {
+  if (process.platform === "win32") {
+    return Boolean(process.env.WT_SESSION) || process.env.TERM_PROGRAM === "vscode";
+  }
+  return process.env.TERM !== "linux";
+}
+var MIN_TERMINAL_WIDTH = 40;
+var DEFAULT_TERMINAL_WIDTH = 80;
+function getTerminalWidth() {
+  const width = process.stdout.columns || DEFAULT_TERMINAL_WIDTH;
+  return Math.max(width, MIN_TERMINAL_WIDTH);
+}
+var cursor = {
+  hide: "\x1B[?25l",
+  show: "\x1B[?25h",
+  up: (n = 1) => `\x1B[${n}A`,
+  down: (n = 1) => `\x1B[${n}B`,
+  forward: (n = 1) => `\x1B[${n}C`,
+  back: (n = 1) => `\x1B[${n}D`,
+  left: "\x1B[G",
+  clearLine: "\x1B[2K",
+  clearDown: "\x1B[J",
+  save: "\x1B[s",
+  restore: "\x1B[u"
+};
+function clearLine() {
+  if (isTTY2()) {
+    process.stdout.write(cursor.clearLine + cursor.left);
+  }
+}
+function hideCursor() {
+  if (isTTY2()) {
+    process.stdout.write(cursor.hide);
+  }
+}
+function showCursor() {
+  if (isTTY2()) {
+    process.stdout.write(cursor.show);
+  }
+}
+function truncate(text, maxLength) {
+  if (text.length <= maxLength)
+    return text;
+  return `${text.slice(0, maxLength - 1)}…`;
+}
+
+// src/utils/progress/spinner.ts
+var spinnerColors = {
+  cyan: chalk3.cyan,
+  yellow: chalk3.yellow,
+  green: chalk3.green,
+  red: chalk3.red,
+  magenta: chalk3.magenta,
+  blue: chalk3.blue,
+  white: chalk3.white
+};
+var FRAME_SETS = {
+  dots: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+  circle: ["◐", "◓", "◑", "◒"]
+};
+var ASCII_FRAME_SET = ["-", "\\", "|", "/"];
+
+class Spinner {
+  label;
+  detail;
+  frames;
+  interval;
+  colorFn;
+  frameIndex = 0;
+  timer = null;
+  state = "stopped";
+  symbols = getSymbols(supportsUnicode());
+  lastRenderedLines = 0;
+  sigintHandler = null;
+  constructor(options = {}) {
+    this.label = options.label ?? "";
+    this.detail = options.detail;
+    this.interval = options.interval ?? 80;
+    this.colorFn = spinnerColors[options.color ?? "cyan"];
+    const style = options.style ?? "circle";
+    this.frames = supportsUnicode() ? FRAME_SETS[style] : ASCII_FRAME_SET;
+  }
+  start(label) {
+    if (label !== undefined)
+      this.label = label;
+    if (this.state === "spinning")
+      return this;
+    this.state = "spinning";
+    this.frameIndex = 0;
+    this.lastRenderedLines = 0;
+    if (!isInteractive()) {
+      console.log(`${this.symbols.bullet} ${this.label}`);
+      return this;
+    }
+    hideCursor();
+    this.setupSignalHandler();
+    this.render();
+    this.timer = setInterval(() => {
+      this.frameIndex = (this.frameIndex + 1) % this.frames.length;
+      this.render();
+    }, this.interval);
+    return this;
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.state = "stopped";
+    this.clearOutput();
+    this.cleanup();
+    return this;
+  }
+  success(label) {
+    if (label !== undefined)
+      this.label = label;
+    this.finish("success");
+    return this;
+  }
+  fail(label) {
+    if (label !== undefined)
+      this.label = label;
+    this.finish("error");
+    return this;
+  }
+  update(label) {
+    this.label = label;
+    if (this.state === "spinning" && isInteractive()) {
+      this.render();
+    }
+    return this;
+  }
+  setDetail(detail) {
+    this.detail = detail;
+    if (this.state === "spinning" && isInteractive()) {
+      this.render();
+    }
+    return this;
+  }
+  get isSpinning() {
+    return this.state === "spinning";
+  }
+  finish(state) {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.state = state;
+    if (!isInteractive()) {
+      const symbol = state === "success" ? this.symbols.success : this.symbols.error;
+      const colorFn = state === "success" ? colors.success : colors.error;
+      console.log(`${colorFn(symbol)} ${this.label}`);
+    } else {
+      this.clearOutput();
+      const symbol = state === "success" ? this.symbols.success : this.symbols.error;
+      const colorFn = state === "success" ? colors.success : colors.error;
+      process.stdout.write(`${colorFn(symbol)} ${this.label}
+`);
+    }
+    this.cleanup();
+  }
+  render() {
+    if (!isTTY2())
+      return;
+    this.clearOutput();
+    const frame = this.colorFn(this.frames[this.frameIndex]);
+    const width = getTerminalWidth();
+    const mainLine = truncate(`${frame} ${this.label}`, width);
+    process.stdout.write(mainLine);
+    let lines = 1;
+    if (this.detail) {
+      const detailLine = truncate(`  ${colors.muted(this.detail)}`, width);
+      process.stdout.write(`
+${detailLine}`);
+      lines = 2;
+    }
+    this.lastRenderedLines = lines;
+  }
+  clearOutput() {
+    if (!isTTY2())
+      return;
+    for (let i = 0;i < this.lastRenderedLines; i++) {
+      if (i > 0)
+        process.stdout.write(cursor.up(1));
+      clearLine();
+    }
+  }
+  setupSignalHandler() {
+    this.sigintHandler = () => {
+      this.cleanup();
+      process.exit(130);
+    };
+    process.on("SIGINT", this.sigintHandler);
+  }
+  cleanup() {
+    if (this.sigintHandler) {
+      process.removeListener("SIGINT", this.sigintHandler);
+      this.sigintHandler = null;
+    }
+    showCursor();
+  }
+}
+
 // src/commands/init.ts
 var __dirname15 = path33.dirname(fileURLToPath14(import.meta.url));
 function getVersion14() {
@@ -178075,7 +178627,7 @@ async function scanPackage(cwd, pkgDir) {
   try {
     const entryFile = detectEntry(absDir);
     const result = await extract({ entryFile });
-    const spec = normalize5(result.spec);
+    const spec = normalize7(result.spec);
     const exports = spec.exports ?? [];
     const total = exports.length;
     let documented = 0;
@@ -178084,7 +178636,8 @@ async function scanPackage(cwd, pkgDir) {
         documented++;
     }
     const coverage = total > 0 ? Math.round(documented / total * 100) : 100;
-    return { name, entry: path33.relative(cwd, entryFile), exports: total, coverage };
+    const health = Math.round(coverage * 0.5 + 100 * 0.5);
+    return { name, entry: path33.relative(cwd, entryFile), exports: total, coverage, health };
   } catch {
     return null;
   }
@@ -178105,12 +178658,16 @@ function registerInitCommand(program) {
       const workspaces = detectWorkspaces(cwd);
       const isMonorepo = workspaces !== null;
       const packageDirs = isMonorepo ? resolveGlobs(cwd, workspaces) : ["."];
+      const spin = new Spinner({ style: "dots" });
+      spin.start("Scanning packages…");
       const packages = [];
       for (const dir of packageDirs) {
+        spin.update(`Scanning ${dir}…`);
         const result = await scanPackage(cwd, dir);
         if (result)
           packages.push(result);
       }
+      spin.success(`Scanned ${packages.length} package${packages.length === 1 ? "" : "s"}`);
       if (packages.length === 0) {
         formatError("init", "No TypeScript packages found", startTime, version);
         return;
@@ -178523,6 +179080,13 @@ function renderList(data) {
     lines.push(`  ${c.bold(`${total} exports`)}`);
   }
   lines.push("");
+  if (total === 0 && data.filter) {
+    const msg = data.filter === "undocumented" ? `${c.green(sym.ok)} All exports are documented` : `${c.green(sym.ok)} No drifted exports found`;
+    lines.push(indent(msg));
+    lines.push("");
+    return lines.join(`
+`);
+  }
   if (!data.search) {
     const kindCounts = new Map;
     for (const exp of exports) {
@@ -178579,9 +179143,14 @@ function registerListCommand(program) {
         const rows = [];
         for (const pkg of packages) {
           const res = await listExports({ entryFile: pkg.entry });
-          rows.push({ name: pkg.name, count: res.exports.length });
+          let filtered = res.exports;
+          if (options.undocumented) {
+            filtered = filtered.filter((e) => !e.description || e.description.trim().length === 0);
+          }
+          rows.push({ name: pkg.name, count: filtered.length });
         }
-        formatOutput("list", { packages: rows }, startTime, version, renderBatchList);
+        const filter2 = options.undocumented ? "undocumented" : undefined;
+        formatOutput("list", { packages: rows, filter: filter2 }, startTime, version, renderBatchList);
         return;
       }
       let entryFile;
@@ -178618,6 +179187,7 @@ function registerListCommand(program) {
         const matches = fuzzySearch(searchTerm, exports);
         exports = matches.map((m) => exports.find((e) => e.name === m.name));
       }
+      const filter = options.undocumented ? "undocumented" : options.drifted ? "drifted" : undefined;
       const data = {
         exports: exports.map((e) => ({
           name: e.name,
@@ -178626,7 +179196,8 @@ function registerListCommand(program) {
           ...e.deprecated ? { deprecated: true } : {}
         })),
         ...searchTerm ? { search: searchTerm } : {},
-        showAll: !!options.full
+        showAll: !!options.full,
+        ...filter ? { filter } : {}
       };
       formatOutput("list", data, startTime, version, renderList);
     } catch (err) {
@@ -178968,7 +179539,7 @@ function registerReportCommand(program) {
 import { readFileSync as readFileSync36 } from "node:fs";
 import * as path40 from "node:path";
 import { fileURLToPath as fileURLToPath20 } from "node:url";
-import { diffSpec as diffSpec7, recommendSemverBump as recommendSemverBump3 } from "@openpkg-ts/spec";
+import { diffSpec as diffSpec8, recommendSemverBump as recommendSemverBump3 } from "@openpkg-ts/spec";
 
 // src/formatters/semver.ts
 function renderSemver(data) {
@@ -178997,7 +179568,7 @@ function registerSemverCommand(program) {
     try {
       const args = [oldPath, newPath].filter(Boolean);
       const { oldSpec, newSpec } = await resolveSpecs({ args, ...options });
-      const diff = diffSpec7(oldSpec, newSpec);
+      const diff = diffSpec8(oldSpec, newSpec);
       const recommendation = recommendSemverBump3(diff);
       const data = {
         bump: recommendation.bump,
@@ -179158,6 +179729,12 @@ if (process.argv.includes("--capabilities")) {
 `);
   process.exit(0);
 }
+var userArgs = process.argv.slice(2).filter((a) => !a.startsWith("-"));
+if (userArgs.length === 0) {
+  const { configPath } = loadConfig();
+  const subcommand = configPath ? "health" : "init";
+  process.argv.splice(2, 0, subcommand);
+}
 program.parseAsync().catch(() => {
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftdev/cli",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Drift CLI - Documentation coverage and drift detection for TypeScript",
   "keywords": [
     "typescript",