dev-diagnosis-cli 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,6 +1,32 @@
 # Changelog
 
-## 0.1.4 — unreleased
+## 0.1.6 — unreleased
+
+- 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
+  reader now requires a root element, so the file is reported as
+  "no root element", listed in the warnings, and the `flakes` check fails
+  instead of silently reporting on half-read data. A genuinely empty report
+  (`<testsuites></testsuites>`) still parses to zero tests. (62 tests.)
+- Docs: the 0.1.5 entry below is now dated — it went live on npm on
+  2026-11-11 but the entry still said "unreleased".
+
+## 0.1.5 — 2026-11-11
+
+- Fix: a JUnit file that cannot be parsed no longer passes silently —
+  `flakes` used to collect the parse error into a warnings list nothing
+  ever printed, so a run set of only corrupt XML reported "no flaky
+  tests" and exited 0. The warning is now printed with the file and the
+  parse position, and the check fails with how many files could not be
+  parsed, so the verdict is never based on half-read data. (58 tests.)
+- Docs: a Troubleshooting note for running `npx` inside a checkout of
+  this repo — npx prefers the checkout's own package.json and fails
+  with `dev-diagnosis: not found`; `npm install` does not fix it (no
+  dependencies, so no `node_modules` is created). Run
+  `node bin/dev-diagnosis.js` directly, `npm link`, or run `npx` from
+  another directory.
+
+## 0.1.4 — 2026-11-11
 
 - Fix: a large file now carries a suggestion — its exact path from the
   repo root — so `context --fix` writes it into `.aiignore` and a

package/README.md

@@ -107,17 +107,32 @@ 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.
+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.
 
 ## Development
 
 ```sh
-npm test            # node:test, no extra dependencies — 54 tests
+npm test            # node:test, no extra dependencies — 62 tests
 npm run example     # run the CLI against the demo fixture
 ```
 
+There is nothing to install: the CLI has no runtime dependencies, so
+`npm test` works straight after cloning. Run the checkout as
+`node bin/dev-diagnosis.js …` — see Troubleshooting if you reach for
+`npx` inside the checkout.
+
 Requires Node.js 18 or later. CI runs the tests and the demo on Node 18, 20, 22 and 24 across Ubuntu, macOS and Windows, and smoke-tests the packed tarball by installing it in a clean directory. Windows is covered by CI only — the Windows-only code paths (the `cmd.exe` retry for `.cmd`/`.bat` shims, `PATHEXT` lookup) have not been run on a real Windows machine.
 
+## Troubleshooting
+
+**`npx dev-diagnosis-cli` inside a checkout of this repo fails with
+`dev-diagnosis: not found`.** npx sees the checkout's own `package.json`
+— same name, same version — and tries to run the local bin, which only
+exists once the bin is linked. `npm install` does not link it: with no
+dependencies to install, npm creates no `node_modules` at all. Run the
+checkout directly instead — `node bin/dev-diagnosis.js …` — or `npm link`
+to get a `dev-diagnosis` command, or run `npx` from any other directory.
+
 ## Credits
 
 dev-diagnosis merges four tools by the same author, each of which keeps working on its own:

package/bin/dev-diagnosis.js

@@ -247,13 +247,21 @@ function printFlakes(result, top, json) {
 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 passed = result.totals.flaky === 0 && result.totals.alwaysFailing === 0;
+  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 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`;
   return {
     result,
     passed,
-    verdict: passed
-      ? `no flaky tests across ${result.totals.runs} runs`
-      : `${result.totals.flaky} flaky, ${result.totals.alwaysFailing} always-failing across ${result.totals.runs} runs`,
+    verdict: unparsable > 0
+      ? `${base}; ${unparsable} file${unparsable === 1 ? '' : 's'} could not be parsed`
+      : base,
   };
 }
 

package/lib/flakes.mjs

@@ -166,7 +166,10 @@ export function scanRuns(root, options = {}) {
       try {
         parsed = parseJunitFile(file);
       } catch (error) {
-        warnings.push(`${file}: ${error.message}`);
+        // parseJunitFile already puts the file path in an XML error's
+        // message; only prepend it for errors that do not carry it, so
+        // the warning never reads "file: file:line:col: ...".
+        warnings.push(error.message.startsWith(file) ? error.message : `${file}: ${error.message}`);
         continue;
       }
       for (const test of parsed) {
@@ -253,13 +256,20 @@ export function formatFlakesTable(result, top = null) {
   lines.push(`runs: ${result.totals.runs}  tests: ${result.totals.tests}  flaky: ${result.totals.flaky}  always-failing: ${result.totals.alwaysFailing}`);
   if (unstable.length === 0) {
     lines.push('No flaky tests: every test passed in every run it appeared in.');
-    return lines.join('\n');
+  } else {
+    const header = `${'test'.padEnd(46)} ${'unstable'.padStart(8)} ${'runs'.padStart(5)} ${'trend'.padStart(8)}  classification`;
+    lines.push(header);
+    for (const test of unstable) {
+      const label = test.id.length > 46 ? `${test.id.slice(0, 43)}...` : test.id;
+      lines.push(`${label.padEnd(46)} ${`${test.unstableRuns}/${test.eligibleRuns}`.padStart(8)} ${String(test.eligibleRuns).padStart(5)} ${test.trend.padStart(8)}  ${test.classification}`);
+    }
   }
-  const header = `${'test'.padEnd(46)} ${'unstable'.padStart(8)} ${'runs'.padStart(5)} ${'trend'.padStart(8)}  classification`;
-  lines.push(header);
-  for (const test of unstable) {
-    const label = test.id.length > 46 ? `${test.id.slice(0, 43)}...` : test.id;
-    lines.push(`${label.padEnd(46)} ${`${test.unstableRuns}/${test.eligibleRuns}`.padStart(8)} ${String(test.eligibleRuns).padStart(5)} ${test.trend.padStart(8)}  ${test.classification}`);
+  // A file that could not be parsed is not "no flaky tests": say so on
+  // screen, with the file and the reason, instead of passing silently.
+  if (result.warnings && result.warnings.length > 0) {
+    const noun = result.warnings.length === 1 ? 'file' : 'files';
+    lines.push(`Warning: ${result.warnings.length} ${noun} could not be parsed — results are incomplete:`);
+    for (const warning of result.warnings) lines.push(`  ${warning}`);
   }
   return lines.join('\n');
 }

package/lib/xml.mjs

@@ -165,6 +165,11 @@ export function parseXml(source, options = {}) {
     index = start.end;
   }
   if (stack.length > 1) fail(`unclosed tag <${stack[stack.length - 1].name}>`, length);
+  // An empty document, a file of only whitespace, or a file of only a
+  // declaration/comment is not XML at all: it has no root element, so
+  // treating it as "zero testcases" would silently report a run set as
+  // clean when one of its files was never read.
+  if (!document.children.some((child) => isElement(child))) fail('no root element', length);
   return document;
 }
 

package/package.json

@@ -1 +1 @@
-{"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.4"}
+{"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"}