dev-diagnosis-cli 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,6 +1,34 @@
 # Changelog
 
-## 0.1.3 — unreleased
+## 0.1.5 — unreleased
+
+- 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
+  re-scan comes back clean. Large files used to carry no suggestion, so
+  on any repo with one oversized file the fix wrote everything else and
+  the next scan still failed on the same file, including this project's
+  own demo fixture (its 1.7 MB `data/export.json`). The documented
+  "`--fix` followed by a re-scan comes back clean" promise now holds
+  for every kind of noise. (54 tests.)
+- Docs: the 0.1.3 entry below is now dated — it went live on npm on
+  2026-11-11 but the entry still said "unreleased".
+
+## 0.1.3 — 2026-11-11
 
 - Fix: nested build-output directories are reported by their full path
   from the repo root (`packages/foo/dist/`) instead of a bare `dist/` —

package/README.md

@@ -58,6 +58,7 @@ Worth a look before sharing:
   .env.example — environment template (usually safe to share)
 Fix: add these to .aiignore (or the agent's ignore list):
   *.log
+  data/export.json
   dist/
   package-lock.json
 FAIL  some context noise found (score 75/100)
@@ -92,7 +93,7 @@ The demo repo is intentionally noisy, so `all` exits 1: the context and flakes c
 
 ### `context` — what an AI agent should not read
 
-Walks the repo (skipping `.git`, `node_modules` and other hidden directories) and classifies every file: build output, large files over 1 MB, lockfiles, logs, binary payloads, secret-like files and environment templates. It prints a 0–100 score, the bytes lost per category, the noisy files, the files worth a look before sharing, and the `.aiignore` entries that would fix it. Build-output directories are reported by their full path from the repo root (`packages/foo/dist/`, not a bare `dist/`) and rolled up into one row per directory, so the entry `--fix` writes matches nested build output too. Files the repo's `.aiignore` already lists are excluded from the scan entirely — they are what the agent will not be handed, so they are not noise any more. `context --fix` writes the suggestions into `.aiignore` for you; `--json` includes the fix outcome in the output.
+Walks the repo (skipping `.git`, `node_modules` and other hidden directories) and classifies every file: build output, large files over 1 MB, lockfiles, logs, binary payloads, secret-like files and environment templates. It prints a 0–100 score, the bytes lost per category, the noisy files, the files worth a look before sharing, and the `.aiignore` entries that would fix it. Build-output directories are reported by their full path from the repo root (`packages/foo/dist/`, not a bare `dist/`) and rolled up into one row per directory, so the entry `--fix` writes matches nested build output too. A large file is fixed by its exact path from the repo root — no glob can single one file out — so `--fix` followed by a re-scan comes back clean even when the noise is a single oversized file. Files the repo's `.aiignore` already lists are excluded from the scan entirely — they are what the agent will not be handed, so they are not noise any more. `context --fix` writes the suggestions into `.aiignore` for you; `--json` includes the fix outcome in the output.
 
 The score is the *noise-only* part of ai-context-doctor's score: 100 minus the category-weighted share of noise bytes (build 40, large 25, lockfile 20, log 15). The full ai-context-doctor score also weighs context volume, one file dominating, file sprawl and binary payloads, so its composite number reads lower on the same repo. The file classification itself is the same.
 
@@ -111,12 +112,27 @@ Reads JUnit XML across CI runs — each subdirectory of `<junit-dir>` is one run
 ## Development
 
 ```sh
-npm test            # node:test, no extra dependencies — 53 tests
+npm test            # node:test, no extra dependencies — 58 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/context.mjs

@@ -114,7 +114,13 @@ export function classifyPath(relativePath, size = 0) {
     return { noise: { label: normalized, reason: 'local log file' }, suggestion: '*.log' };
   }
   if (size > LARGE_FILE_THRESHOLD_BYTES) {
-    return { noise: { label: normalized, reason: 'large file' }, suggestion: null };
+    // A large file has no pattern that fixes it — a glob would be wrong —
+    // so the fix is its exact path from the repo root. Without that, a
+    // repo with one oversized file could never come back clean: --fix
+    // would write everything else and the next scan would still fail on
+    // the same file, which is exactly what the --fix round-trip promises
+    // not to do.
+    return { noise: { label: normalized, reason: 'large file' }, suggestion: normalized };
   }
   if (isTemplateFile(basename)) {
     return { review: { label: normalized, reason: 'environment template (usually safe to share)' }, suggestion: null };

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/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.3"}
+{"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.5"}