dev-diagnosis-cli 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -1,6 +1,32 @@
 # Changelog
 
-## 0.1.6 — unreleased
+## 0.1.7 — unreleased
+
+- Fix: `dev-diagnosis <path>` no longer errors with "unknown command" —
+  the usage line promises `[all] [path]`, but a bare path was treated as a
+  command name. A bare positional that is an existing directory now means
+  `all` on that path (options like `--command` still apply); a word that
+  is neither a known command nor a directory is still a usage error, so a
+  typo stays a typo. The help text and README say so.
+- Fix: `--top N` was silently ignored in `--json` output — `flakes
+  <dir> --json --top 1` returned all five demo tests instead of one.
+  The JSON `tests` array is now limited to the N highest-ranked tests,
+  in standalone `flakes` and in `all --json` alike; `totals` still
+  describes the whole run set, the same split the text table makes.
+- Fix: `all --json` dropped the reason a check could not run — a missing
+  runs directory or a failing build came out as `"flakes": null` /
+  `"cache": null` next to `overall: FAIL`, with nothing saying why.
+  A check with no result now reports `{ "error": "<reason>" }` instead,
+  so a script consuming the JSON can tell which check failed and why.
+- Fix: a run directory with no JUnit XML files was silently dropped —
+  `flakes` on two run directories, one of them empty, reported
+  "runs: 1" with no mention of the second run. An empty run directory
+  is now named in the output (and in `--json` under `skippedRuns`) and
+  fails the check: a CI run that produced no reports is a broken upload,
+  not a run with zero tests.
+  (72 tests.)
+
+## 0.1.6 — 2026-11-12
 
 - Fix: an empty JUnit file (0 bytes, whitespace only, or a declaration/comment
   and nothing else) no longer parses as a clean run of zero tests — the XML

package/README.md

@@ -20,7 +20,7 @@ npm install -g dev-diagnosis-cli
 dev-diagnosis all
 ```
 
-`dev-diagnosis` with no arguments is the same as `dev-diagnosis all` on the current directory. Each check is also available on its own:
+`dev-diagnosis` with no arguments is the same as `dev-diagnosis all` on the current directory, and `dev-diagnosis <path>` is the same as `dev-diagnosis all <path>`. Each check is also available on its own:
 
 ```sh
 dev-diagnosis context [path]                        # files an AI agent should not read
@@ -30,7 +30,7 @@ dev-diagnosis flakes <junit-dir>                    # flaky tests from JUnit XML
 dev-diagnosis all [path] --command <name> --flakes <dir> -- <build-command...>
 ```
 
-`all` always runs `context` on `[path]` (default: the current directory) and runs `path`, `flakes` and `cache` when their input is given. Checks without their input are listed as skipped, with the command that would run them, instead of silently pretending they ran. A build command on a repo with no cache directory to measure is also listed as skipped rather than failing: nothing to measure is not a problem. `--json` gives machine-readable output for `context`, `path`, `flakes` and `all`. Add `--fix` to `context` (or `all`) to write the suggestions into `<path>/.aiignore` instead of only printing them: entries already there are left alone, nothing else in the file is touched, and a later scan skips everything `.aiignore` lists — so `context --fix` followed by `context` comes back clean.
+`all` always runs `context` on `[path]` (default: the current directory) and runs `path`, `flakes` and `cache` when their input is given. Checks without their input are listed as skipped, with the command that would run them, instead of silently pretending they ran. A build command on a repo with no cache directory to measure is also listed as skipped rather than failing: nothing to measure is not a problem. `--json` gives machine-readable output for `context`, `path`, `flakes` and `all`. In `all --json`, a check that could not run (a missing runs directory, a failing build) reports `{ "error": "<reason>" }` instead of `null`, so a script can tell why the overall result failed. Add `--fix` to `context` (or `all`) to write the suggestions into `<path>/.aiignore` instead of only printing them: entries already there are left alone, nothing else in the file is touched, and a later scan skips everything `.aiignore` lists — so `context --fix` followed by `context` comes back clean.
 
 Exit codes: `0` every check that ran passed; `1` a check found something to fix or could not run; `2` usage error.
 
@@ -107,12 +107,12 @@ Runs the build command twice: cold, with the cache directory moved aside, and wa
 
 ### `flakes` — which tests are flaky
 
-Reads JUnit XML across CI runs — each subdirectory of `<junit-dir>` is one run, and each `*.xml` file directly under it is a run of its own — and ranks tests by instability, using a Wilson 95% lower bound so a test that failed twice in two runs outranks one that failed twice in twenty. It distinguishes *passed-on-retry* (failed then passed in the same run, the classic flake signature) from *always-failing* and plain cross-run flakes, and labels each test `new`, `chronic` or `recovered` from its history. CRLF line endings are normalised before parsing, so Windows-produced XML parses the same as Unix-produced XML. A file that cannot be parsed — broken XML, or a file with no root element at all (empty, whitespace-only, a lone declaration) — is printed as a warning and fails the check, so the verdict is never based on half-read data; a genuinely empty report (`<testsuites></testsuites>`) still counts as zero tests.
+Reads JUnit XML across CI runs — each subdirectory of `<junit-dir>` is one run, and each `*.xml` file directly under it is a run of its own — and ranks tests by instability, using a Wilson 95% lower bound so a test that failed twice in two runs outranks one that failed twice in twenty. It distinguishes *passed-on-retry* (failed then passed in the same run, the classic flake signature) from *always-failing* and plain cross-run flakes, and labels each test `new`, `chronic` or `recovered` from its history. CRLF line endings are normalised before parsing, so Windows-produced XML parses the same as Unix-produced XML. A file that cannot be parsed — broken XML, or a file with no root element at all (empty, whitespace-only, a lone declaration) — is printed as a warning and fails the check, so the verdict is never based on half-read data; a genuinely empty report (`<testsuites></testsuites>`) still counts as zero tests. `--top N` limits the listing to the N highest-ranked flaky tests, in the text table and in `--json` output alike; the totals still describe the whole run set. A run directory that contains no JUnit XML files at all is named and skipped, and also fails the check — a CI run that produced no reports is a broken upload, not a run with zero tests, and the report must not pretend it never existed. `--json` lists such runs under `skippedRuns`.
 
 ## Development
 
 ```sh
-npm test            # node:test, no extra dependencies — 62 tests
+npm test            # node:test, no extra dependencies — 72 tests
 npm run example     # run the CLI against the demo fixture
 ```
 

package/bin/dev-diagnosis.js

@@ -42,7 +42,8 @@ Usage:
 Commands:
   all       Run every check that has what it needs and print one unified
             report. context always runs on [path] (default: current
-            directory). path runs when --command is given, flakes when
+            directory). A bare path is the same as all <path>.
+            path runs when --command is given, flakes when
             --flakes is given, cache when a build command follows --.
             Checks without their input are listed as skipped, with the
             command that would run them.
@@ -238,7 +239,11 @@ function runPath(commandName) {
 
 function printFlakes(result, top, json) {
   if (json) {
-    console.log(JSON.stringify(result, null, 2));
+    // --top limits the listing, not the scan: the tests array holds only
+    // the N highest-ranked tests, while totals still describe the whole
+    // run set — the same split the text table already makes.
+    const out = top == null ? result : { ...result, tests: result.tests.slice(0, top) };
+    console.log(JSON.stringify(out, null, 2));
     return;
   }
   console.log(formatFlakesTable(result, top));
@@ -248,20 +253,23 @@ function runFlakes(dir) {
   if (!dir) throw new UsageError('flakes needs a runs directory, for example: dev-diagnosis flakes examples/runs');
   const result = scanRuns(dir);
   const unparsable = result.warnings.length;
-  // A file that could not be parsed means the verdict is based on
-  // incomplete data: "no flaky tests" on a half-read run set is not a
-  // pass, so the check fails and the verdict says how many files were
-  // unreadable. The warnings themselves are printed with the table.
-  const passed = result.totals.flaky === 0 && result.totals.alwaysFailing === 0 && unparsable === 0;
+  const skippedRuns = result.skippedRuns ? result.skippedRuns.length : 0;
+  // A file that could not be parsed, or a run directory that produced no
+  // reports, means the verdict is based on incomplete data: "no flaky
+  // tests" on a half-read run set is not a pass, so the check fails and
+  // the verdict says what was unreadable. The warnings themselves are
+  // printed with the table.
+  const passed = result.totals.flaky === 0 && result.totals.alwaysFailing === 0 && unparsable === 0 && skippedRuns === 0;
   const base = result.totals.flaky === 0 && result.totals.alwaysFailing === 0
     ? `no flaky tests across ${result.totals.runs} runs`
     : `${result.totals.flaky} flaky, ${result.totals.alwaysFailing} always-failing across ${result.totals.runs} runs`;
+  const problems = [];
+  if (unparsable > 0) problems.push(`${unparsable} file${unparsable === 1 ? '' : 's'} could not be parsed`);
+  if (skippedRuns > 0) problems.push(`${skippedRuns} run director${skippedRuns === 1 ? 'y' : 'ies'} had no JUnit XML files`);
   return {
     result,
     passed,
-    verdict: unparsable > 0
-      ? `${base}; ${unparsable} file${unparsable === 1 ? '' : 's'} could not be parsed`
-      : base,
+    verdict: problems.length > 0 ? `${base}; ${problems.join('; ')}` : base,
   };
 }
 
@@ -311,13 +319,26 @@ function main(argv) {
   }
 
   const command = args.command || 'all';
-  if (args.fix && command !== 'context' && command !== 'all') {
+  // `dev-diagnosis <path>` means `dev-diagnosis all <path>`: the usage line
+  // promises `[all] [path]`, so a bare positional that is an existing
+  // directory is a path, not an unknown command. Anything else that is not
+  // a known command still errors below, so a typo stays a typo.
+  let resolvedCommand = command;
+  if (!['all', 'context', 'path', 'cache', 'flakes'].includes(command)) {
+    let isDir = false;
+    try { isDir = fs.statSync(path.resolve(command)).isDirectory(); } catch { isDir = false; }
+    if (isDir) {
+      args.positional.unshift(command);
+      resolvedCommand = 'all';
+    }
+  }
+  if (args.fix && resolvedCommand !== 'context' && resolvedCommand !== 'all') {
     console.error('Error: --fix only applies to context (and all).');
     console.error('Run with --help to see the available options.');
     return 2;
   }
   try {
-    if (command === 'context') {
+    if (resolvedCommand === 'context') {
       const target = args.positional[0];
       const check = runContext(target);
       // In --json mode the fix must be part of the printed object, so it
@@ -331,27 +352,27 @@ function main(argv) {
       if (!args.json) console.log(verdictLine(check.passed, check.verdict));
       return check.passed ? 0 : 1;
     }
-    if (command === 'path') {
+    if (resolvedCommand === 'path') {
       const name = args.positional[0];
       const check = runPath(name);
       printPath(check.result, args.json);
       if (!args.json) console.log(verdictLine(check.passed, check.verdict));
       return check.passed ? 0 : 1;
     }
-    if (command === 'flakes') {
+    if (resolvedCommand === 'flakes') {
       const dir = args.positional[0];
       const check = runFlakes(dir);
       printFlakes(check.result, args.top, args.json);
       if (!args.json) console.log(verdictLine(check.passed, check.verdict));
       return check.passed ? 0 : 1;
     }
-    if (command === 'cache') {
+    if (resolvedCommand === 'cache') {
       const check = runCache({ buildCommand: args.buildCommand, cacheDir: args.cacheDir, cwd: args.cwd });
       printCache(check.result, args.json);
       if (!args.json) console.log(verdictLine(check.passed, check.verdict));
       return check.passed ? 0 : 1;
     }
-    if (command === 'all') {
+    if (resolvedCommand === 'all') {
       const target = args.positional[0];
       const root = target ? path.resolve(target) : process.cwd();
       const checks = {};
@@ -403,7 +424,19 @@ function main(argv) {
       if (args.json) {
         const out = {
           command: 'all', root,
-          checks: Object.fromEntries(Object.entries(checks).map(([key, check]) => [key, check.result])),
+          checks: Object.fromEntries(Object.entries(checks).map(([key, check]) => {
+            let result = check.result;
+            // Same --top split as the standalone flakes output: the
+            // embedded tests array is limited, totals stay whole-scan.
+            if (key === 'flakes' && result && args.top != null) {
+              result = { ...result, tests: result.tests.slice(0, args.top) };
+            }
+            // A check that could not run has no result: keep its reason
+            // in the JSON instead of emitting null, or a script consumer
+            // sees overall FAIL with no way to tell why.
+            if (result == null) result = { error: check.error || check.verdict };
+            return [key, result];
+          })),
           skipped, overall: overall ? 'PASS' : 'FAIL',
         };
         console.log(JSON.stringify(out, null, 2));

package/lib/flakes.mjs

@@ -146,11 +146,20 @@ export function scanRuns(root, options = {}) {
     .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 
   const runGroups = [];
+  const skippedRuns = [];
   for (const entry of entries) {
     const full = path.join(absolute, entry.name);
     if (entry.isDirectory()) {
       const files = listXmlFiles(full);
       if (files.length > 0) runGroups.push({ id: entry.name, files });
+      else {
+        // A run directory with no XML is a run that produced no reports —
+        // a broken CI upload, not a run with zero tests. Dropping it
+        // silently would report "runs: 1" while a second run existed, so
+        // it is recorded and the check fails on it, like an unparsable
+        // file: the verdict must not rest on half-read data.
+        skippedRuns.push({ id: entry.name, reason: 'no JUnit XML files found' });
+      }
     } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.xml')) {
       runGroups.push({ id: entry.name.replace(/\.xml$/i, ''), files: [full] });
     }
@@ -240,6 +249,7 @@ export function scanRuns(root, options = {}) {
     runs: runs.map((run) => ({ id: run.id, files: run.files, testCount: run.tests.length })),
     tests,
     warnings,
+    skippedRuns,
     totals: {
       runs: runs.length,
       tests: tests.length,
@@ -271,5 +281,13 @@ export function formatFlakesTable(result, top = null) {
     lines.push(`Warning: ${result.warnings.length} ${noun} could not be parsed — results are incomplete:`);
     for (const warning of result.warnings) lines.push(`  ${warning}`);
   }
+  // A run directory that produced no reports is not "no flaky tests":
+  // say which runs were skipped, so a missing CI upload is visible.
+  if (result.skippedRuns && result.skippedRuns.length > 0) {
+    const noun = result.skippedRuns.length === 1 ? 'run directory' : 'run directories';
+    const verb = result.skippedRuns.length === 1 ? 'was' : 'were';
+    lines.push(`Note: ${result.skippedRuns.length} ${noun} had no JUnit XML files and ${verb} skipped:`);
+    for (const run of result.skippedRuns) lines.push(`  ${run.id} — ${run.reason}`);
+  }
   return lines.join('\n');
 }

package/package.json

@@ -1 +1,45 @@
-{"author":"WJDdidi-1","bin":{"dev-diagnosis":"bin/dev-diagnosis.js"},"bugs":{"url":"https://github.com/WJDdidi-1/dev-doctor/issues"},"description":"One offline CLI that diagnoses a repo the way four small tools do: context noise for AI agents, missing CLI commands, build-cache value, and flaky tests.","engines":{"node":">=18"},"files":["bin/","lib/","examples/","README.md","LICENSE","CHANGELOG.md"],"homepage":"https://github.com/WJDdidi-1/dev-doctor#readme","keywords":["cli","diagnostics","ai-coding","context","build-cache","flaky-tests","path","developer-tools","offline"],"license":"Apache-2.0","name":"dev-diagnosis-cli","repository":{"type":"git","url":"git+https://github.com/WJDdidi-1/dev-doctor.git"},"scripts":{"example":"node examples/demo.mjs","test":"node --test"},"type":"module","version":"0.1.6"}
+{
+  "author": "WJDdidi-1",
+  "bin": {
+    "dev-diagnosis": "bin/dev-diagnosis.js"
+  },
+  "bugs": {
+    "url": "https://github.com/WJDdidi-1/dev-doctor/issues"
+  },
+  "description": "One offline CLI that diagnoses a repo the way four small tools do: context noise for AI agents, missing CLI commands, build-cache value, and flaky tests.",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "examples/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "homepage": "https://github.com/WJDdidi-1/dev-doctor#readme",
+  "keywords": [
+    "cli",
+    "diagnostics",
+    "ai-coding",
+    "context",
+    "build-cache",
+    "flaky-tests",
+    "path",
+    "developer-tools",
+    "offline"
+  ],
+  "license": "Apache-2.0",
+  "name": "dev-diagnosis-cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WJDdidi-1/dev-doctor.git"
+  },
+  "scripts": {
+    "example": "node examples/demo.mjs",
+    "test": "node --test"
+  },
+  "type": "module",
+  "version": "0.1.7"
+}