@kaynooo/cli-doctor 0.5.1 → 0.6.0

package/README.md

@@ -38,10 +38,10 @@ Each bin completes itself through `<bin> __complete`. fish gets a file per bin (
 ## cli stats
 
 ```sh
-cli stats [--since 7d] [--json]   # runs per bin, failures, and the options usage errors did not know
+cli stats [--since 7d] [--json]   # runs per bin and per command, failures (exit 1) apart from usage errors (exit 2), and the options usage errors did not know
 ```
 
-Every bin records each run in `~/.local/state/kaynooo-cli/usage.jsonl`: the bin, its command, the flag names it saw (never values or arguments), the exit code and, on a usage error, the unknown option. `KAYNOOO_CLI_NO_USAGE=1` turns it off; `guard` never records.
+Every bin records each run in `~/.local/state/kaynooo-cli/usage.jsonl`: the bin, its command, the flag names it saw (never values or arguments), the exit code and, on a usage error, the unknown option (never its message). `KAYNOOO_CLI_NO_USAGE=1` turns it off; `guard` never records.
 
 ## cli list
 

package/dist/cli-bin.js

@@ -808,26 +808,38 @@ async function readUsage(path = usagePath(), since = 0) {
     }
   });
 }
+function tally(counts, code) {
+  counts.runs++;
+  counts.failed += code === 0 || code === 2 ? 0 : 1;
+  counts.usageErrors += code === 2 ? 1 : 0;
+}
 function summarizeUsage(entries) {
   const bins = new Map;
-  const errors = new Map;
+  const commands = new Map;
+  const unknowns = new Map;
   for (const entry of entries) {
     const bin = bins.get(entry.bin) ?? { runs: 0, failed: 0, usageErrors: 0 };
-    bin.runs++;
-    bin.failed += entry.code === 0 ? 0 : 1;
-    bin.usageErrors += entry.code === 2 ? 1 : 0;
+    tally(bin, entry.code);
     bins.set(entry.bin, bin);
-    if (entry.code === 2 && entry.unknown !== undefined) {
+    if (entry.command !== undefined) {
+      const command = commands.get(`${entry.bin} ${entry.command}`) ?? { bin: entry.bin, command: entry.command, runs: 0, failed: 0, usageErrors: 0 };
+      tally(command, entry.code);
+      commands.set(`${entry.bin} ${entry.command}`, command);
+    }
+    if (entry.code !== 2)
+      continue;
+    if (entry.unknown !== undefined) {
       const key = `${entry.bin} ${entry.command ?? ""} ${entry.unknown}`;
-      const error = errors.get(key) ?? { bin: entry.bin, ...entry.command === undefined ? {} : { command: entry.command }, unknown: entry.unknown, count: 0 };
-      error.count++;
-      errors.set(key, error);
+      const unknown = unknowns.get(key) ?? { bin: entry.bin, ...entry.command === undefined ? {} : { command: entry.command }, unknown: entry.unknown, count: 0 };
+      unknown.count++;
+      unknowns.set(key, unknown);
     }
   }
   return {
     runs: entries.length,
     bins: [...bins].map(([bin, counts]) => ({ bin, ...counts })).toSorted((a, b) => b.runs - a.runs),
-    usageErrors: [...errors.values()].toSorted((a, b) => b.count - a.count)
+    commands: [...commands.values()].toSorted((a, b) => b.runs - a.runs),
+    usageErrors: [...unknowns.values()].toSorted((a, b) => b.count - a.count)
   };
 }
 
@@ -931,7 +943,7 @@ function reportThrown(prefix, error, redact = (text) => text, json = false) {
   const help = error instanceof UsageError ? `run ${prefix} --help for its options` : undefined;
   const named = error instanceof Error && !(error instanceof Exit) && error.name !== "Error" ? `${error.name}: ${error.message}` : undefined;
   const cause = error instanceof Error && error.cause instanceof Error ? redact(error.cause.message) : undefined;
-  if (error instanceof UsageError)
+  if (error instanceof Exit && error.code === 2)
     noteUsageError(error.message);
   const report = json ? printJsonError : (message, hint, causeText) => printError(prefix, message, hint, causeText);
   report(redact(named ?? (error instanceof Error ? error.message : String(error))), error instanceof Exit ? error.hint ?? help : undefined, cause);
@@ -1211,16 +1223,16 @@ async function checkTool(host, name, bins) {
   if (version === undefined)
     return { check, ok: false, detail: "not installed", fix: `bun install -g ${name}` };
   const off = bins.filter((bin) => host.which(bin) === null);
-  if (off.length > 0)
-    return { check, ok: false, detail: `${version}, ${off.join(", ")} not on the PATH`, fix: `add ${join3(host.globalModules, "..", "..", "..", "bin")} to the PATH` };
   const info = await host.run(["bun", "info", name, "version", "--no-cache"]);
   const answered = info.code === 0 ? firstLine(info.stdout.trim().split(`
 `).at(-1) ?? "") : "";
   const latest = VERSION.test(answered) ? answered : "";
+  if (latest !== "" && Bun.semver.order(version, latest) < 0)
+    return { check, ok: false, detail: `${version}, ${latest} released${off.length > 0 ? `, ${off.join(", ")} not on the PATH` : ""}`, fix: `bun install -g ${name}@${latest}` };
+  if (off.length > 0)
+    return { check, ok: false, detail: `${version}, ${off.join(", ")} not on the PATH`, fix: `add ${join3(host.globalModules, "..", "..", "..", "bin")} to the PATH` };
   if (latest === "")
     return { check, ok: true, detail: `${version}, the registry did not answer: ${firstLine(info.stderr) || answered || "no version"}` };
-  if (Bun.semver.order(version, latest) < 0)
-    return { check, ok: false, detail: `${version}, ${latest} released`, fix: `bun install -g ${name}@${latest}` };
   return { check, ok: true, detail: version };
 }
 async function checkTea(host) {
@@ -1440,11 +1452,11 @@ async function completions(args, host = hostHere()) {
 }
 var STATS_USAGE = `cli stats [--since 7d] [--json]: how often each bin ran, and the usage errors by the option it did not know
 
-Every bin records each run in ~/.local/state/kaynooo-cli/usage.jsonl (or $XDG_STATE_HOME): the bin, its command, the names of the flags it saw (never a value or an argument), the exit code and, on a usage error, the unknown option. Set KAYNOOO_CLI_NO_USAGE=1 to stop recording; \`guard\` never records.
+Every bin records each run in ~/.local/state/kaynooo-cli/usage.jsonl (or $XDG_STATE_HOME): the bin, its command, the names of the flags it saw (never a value or an argument), the exit code and and, on a usage error, the unknown option (never the message, which carries the values it refused). failed counts exits other than 0 and 2, usage errors are exit 2 (misuse, or a check that could not be made). Set KAYNOOO_CLI_NO_USAGE=1 to stop recording; \`guard\` never records.
 Exits 0 when it printed the summary, 2 on a usage error.`;
 var STATS_OPTIONS = {
   since: { type: "string", description: "only the runs this recent (7d, 12h)" },
-  json: jsonOption("{runs, bins: [{bin, runs, failed, usageErrors}], usageErrors: [{bin, command?, unknown, count}]}")
+  json: jsonOption("{runs, bins: [{bin, runs, failed, usageErrors}], commands: [{bin, command, runs, failed, usageErrors}], usageErrors: [{bin, command?, unknown, count}]}")
 };
 async function stats(args, path = usagePath()) {
   const { values } = parse(args, STATS_USAGE, STATS_OPTIONS, { positionals: [], examples: ["cli stats", ["cli stats --since 7d", "the last week"]] });
@@ -1461,6 +1473,11 @@ async function stats(args, path = usagePath()) {
   console.log(`${summary.runs} runs
 
 ${table(summary.bins.map((each) => [each.bin, String(each.runs), `${each.failed} failed`, `${each.usageErrors} usage errors`]))}`);
+  const busy = summary.commands.filter((each) => each.failed + each.usageErrors > 0).toSorted((a, b) => b.failed + b.usageErrors - (a.failed + a.usageErrors)).slice(0, 15);
+  if (busy.length > 0)
+    console.log(`
+commands with failures or usage errors
+${table(busy.map((each) => [`${each.bin} ${each.command}`, String(each.runs), `${each.failed} failed`, `${each.usageErrors} usage errors`]))}`);
   if (summary.usageErrors.length > 0)
     console.log(`
 unknown options

package/dist/cli.js

@@ -808,26 +808,38 @@ async function readUsage(path = usagePath(), since = 0) {
     }
   });
 }
+function tally(counts, code) {
+  counts.runs++;
+  counts.failed += code === 0 || code === 2 ? 0 : 1;
+  counts.usageErrors += code === 2 ? 1 : 0;
+}
 function summarizeUsage(entries) {
   const bins = new Map;
-  const errors = new Map;
+  const commands = new Map;
+  const unknowns = new Map;
   for (const entry of entries) {
     const bin = bins.get(entry.bin) ?? { runs: 0, failed: 0, usageErrors: 0 };
-    bin.runs++;
-    bin.failed += entry.code === 0 ? 0 : 1;
-    bin.usageErrors += entry.code === 2 ? 1 : 0;
+    tally(bin, entry.code);
     bins.set(entry.bin, bin);
-    if (entry.code === 2 && entry.unknown !== undefined) {
+    if (entry.command !== undefined) {
+      const command = commands.get(`${entry.bin} ${entry.command}`) ?? { bin: entry.bin, command: entry.command, runs: 0, failed: 0, usageErrors: 0 };
+      tally(command, entry.code);
+      commands.set(`${entry.bin} ${entry.command}`, command);
+    }
+    if (entry.code !== 2)
+      continue;
+    if (entry.unknown !== undefined) {
       const key = `${entry.bin} ${entry.command ?? ""} ${entry.unknown}`;
-      const error = errors.get(key) ?? { bin: entry.bin, ...entry.command === undefined ? {} : { command: entry.command }, unknown: entry.unknown, count: 0 };
-      error.count++;
-      errors.set(key, error);
+      const unknown = unknowns.get(key) ?? { bin: entry.bin, ...entry.command === undefined ? {} : { command: entry.command }, unknown: entry.unknown, count: 0 };
+      unknown.count++;
+      unknowns.set(key, unknown);
     }
   }
   return {
     runs: entries.length,
     bins: [...bins].map(([bin, counts]) => ({ bin, ...counts })).toSorted((a, b) => b.runs - a.runs),
-    usageErrors: [...errors.values()].toSorted((a, b) => b.count - a.count)
+    commands: [...commands.values()].toSorted((a, b) => b.runs - a.runs),
+    usageErrors: [...unknowns.values()].toSorted((a, b) => b.count - a.count)
   };
 }
 
@@ -931,7 +943,7 @@ function reportThrown(prefix, error, redact = (text) => text, json = false) {
   const help = error instanceof UsageError ? `run ${prefix} --help for its options` : undefined;
   const named = error instanceof Error && !(error instanceof Exit) && error.name !== "Error" ? `${error.name}: ${error.message}` : undefined;
   const cause = error instanceof Error && error.cause instanceof Error ? redact(error.cause.message) : undefined;
-  if (error instanceof UsageError)
+  if (error instanceof Exit && error.code === 2)
     noteUsageError(error.message);
   const report = json ? printJsonError : (message, hint, causeText) => printError(prefix, message, hint, causeText);
   report(redact(named ?? (error instanceof Error ? error.message : String(error))), error instanceof Exit ? error.hint ?? help : undefined, cause);
@@ -1270,16 +1282,16 @@ async function checkTool(host, name, bins) {
   if (version === undefined)
     return { check, ok: false, detail: "not installed", fix: `bun install -g ${name}` };
   const off = bins.filter((bin) => host.which(bin) === null);
-  if (off.length > 0)
-    return { check, ok: false, detail: `${version}, ${off.join(", ")} not on the PATH`, fix: `add ${join4(host.globalModules, "..", "..", "..", "bin")} to the PATH` };
   const info = await host.run(["bun", "info", name, "version", "--no-cache"]);
   const answered = info.code === 0 ? firstLine(info.stdout.trim().split(`
 `).at(-1) ?? "") : "";
   const latest = VERSION.test(answered) ? answered : "";
+  if (latest !== "" && Bun.semver.order(version, latest) < 0)
+    return { check, ok: false, detail: `${version}, ${latest} released${off.length > 0 ? `, ${off.join(", ")} not on the PATH` : ""}`, fix: `bun install -g ${name}@${latest}` };
+  if (off.length > 0)
+    return { check, ok: false, detail: `${version}, ${off.join(", ")} not on the PATH`, fix: `add ${join4(host.globalModules, "..", "..", "..", "bin")} to the PATH` };
   if (latest === "")
     return { check, ok: true, detail: `${version}, the registry did not answer: ${firstLine(info.stderr) || answered || "no version"}` };
-  if (Bun.semver.order(version, latest) < 0)
-    return { check, ok: false, detail: `${version}, ${latest} released`, fix: `bun install -g ${name}@${latest}` };
   return { check, ok: true, detail: version };
 }
 async function checkTea(host) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kaynooo/cli-doctor",
   "type": "module",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "doctor: checks the @kaynooo/cli-* install of a host: each bin's version against the registry, tea's login to Forgejo, the Claude Code hooks and the Bun floor; cli list: every bin in one line, read from its own help.",
   "author": "Kaynooo <contact@kaynooo.fr>",
   "license": "MIT",
@@ -36,6 +36,6 @@
     "doctor": "$npm_execpath src/cli.ts"
   },
   "devDependencies": {
-    "@kaynooo/cli-kit": "0.21.0"
+    "@kaynooo/cli-kit": "0.21.1"
   }
 }