dev-diagnosis-cli 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,6 +1,55 @@
 # Changelog
 
-## 0.1.6 — unreleased
+## 0.1.8 — 2026-11-12
+
+- Fix: `all --json` embedded the build's full stdout (`coldStdout` /
+  `warmStdout`) in the cache check, while standalone `cache --json`
+  already left it out — a chatty build bloated the machine-readable
+  output. Both shapes are now the same: timings and verdict only. The
+  `--json` option also now documents `cache` (the usage line and help
+  text listed only `context`, `path`, `flakes` and `all`, although
+  standalone `cache --json` already worked).
+- New: `context` now also honours `.gitignore` — files and directories
+  it lists are excluded from the scan, at the repo root and in nested
+  `.gitignore` files alike, so a repo whose build output, logs or data
+  dumps are already git-ignored no longer gets flagged for them, and
+  `--fix` no longer duplicates those entries into `.aiignore`. The
+  common pattern forms work (`*`, `?`, `[...]`, `**`, `/`-anchored
+  paths, directory-only `dir/`, `!` negation with last-match-wins);
+  `.git/info/exclude` and the global gitignore are not read. (82 tests.)
+- Dogfood: the repo now ships a `.aiignore` excluding the demo fixture
+  (`examples/demo-repo/`), so `dev-diagnosis all` on a checkout passes
+  its own `context` check (was 77/100 FAIL, now 100/100 PASS). The
+  fixture is intentionally noisy test data and stays noisy when scanned
+  directly — `npm run example` output is unchanged.
+
+## 0.1.7 — 2026-11-12
+
+- 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`, `cache`, `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.
 
@@ -93,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. 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.
+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. Files and directories listed in `.gitignore` — at the repo root or in a subdirectory — are excluded the same way: they are already invisible to most agents, so flagging them would be noise about noise, and `--fix` will not duplicate them into `.aiignore`. The common pattern forms work (`*`, `?`, `[...]`, `**`, `/`-anchored paths, directory-only `dir/`, and `!` negation with last-match-wins); `.git/info/exclude` and the global gitignore are not read. `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.
 
@@ -103,23 +103,27 @@ Runs the lookup in four shell contexts — current, login, non-login and daemon-
 
 ### `cache` — does the cache pay
 
-Runs the build command twice: cold, with the cache directory moved aside, and warm, with it present, then reports both timings and the saving. The original cache is restored to its original state afterwards, and anything the cold run produced is thrown away. A cache directory that is the project root, contains it, or lies outside it is refused rather than moved. No network is involved; the check only runs your own build command.
+Runs the build command twice: cold, with the cache directory moved aside, and warm, with it present, then reports both timings and the saving. The original cache is restored to its original state afterwards, and anything the cold run produced is thrown away. A cache directory that is the project root, contains it, or lies outside it is refused rather than moved. No network is involved; the check only runs your own build command. `--json` reports the timings and the verdict without the build's stdout, so a chatty build does not bloat the machine-readable output — in `all --json` the embedded cache check is the same shape.
 
 ### `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 — 82 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.
+`npx` inside the checkout. The checkout ships a `.aiignore` that
+excludes the demo fixture (`examples/demo-repo/`), so `dev-diagnosis
+all` on the repo itself passes its own `context` check — the fixture
+is intentionally noisy test data, and it stays noisy when scanned
+directly (`npm run example`).
 
 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.
 

package/bin/dev-diagnosis.js

@@ -34,7 +34,7 @@ Usage:
   dev-diagnosis [all] [path] [--command <name>] [--flakes <dir>] [--fix] [-- <build-command...>]
   dev-diagnosis context [path] [--json] [--fix]
   dev-diagnosis path <command> [--json]
-  dev-diagnosis cache [--cache-dir <dir>] [--cwd <dir>] -- <build-command...>
+  dev-diagnosis cache [--json] [--cache-dir <dir>] [--cwd <dir>] -- <build-command...>
   dev-diagnosis flakes <runs-dir> [--json] [--top N]
   dev-diagnosis --help
   dev-diagnosis --version
@@ -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.
@@ -60,7 +61,7 @@ Commands:
             each *.xml file directly under it is a run of its own.
 
 Options:
-  --json          machine-readable output (context, path, flakes, all)
+  --json          machine-readable output (context, path, cache, flakes, all)
   --fix           write the context check's .aiignore suggestions into
                   <path>/.aiignore (context and all only). Entries that
                   are already there are left alone; nothing else in the
@@ -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,
   };
 }
 
@@ -284,8 +292,7 @@ function runCache(options) {
 
 function printCache(result, json) {
   if (json) {
-    const { coldStdout, warmStdout, ...rest } = result;
-    console.log(JSON.stringify(rest, null, 2));
+    console.log(JSON.stringify(stripCacheStdout(result), null, 2));
     return;
   }
   console.log(`Cache dir: ${result.cacheDir}`);
@@ -294,6 +301,15 @@ function printCache(result, json) {
   console.log(`Verdict: ${result.verdict} — ${result.verdictDetail}`);
 }
 
+// The raw cache result carries the build's full stdout from both runs;
+// JSON output drops it, so a chatty build does not bloat the machine-
+// readable output. Used by printCache and by the `all --json` builder
+// below, so both shapes stay identical.
+function stripCacheStdout(result) {
+  const { coldStdout, warmStdout, ...rest } = result;
+  return rest;
+}
+
 function main(argv) {
   const args = parseArgs(argv);
   if (args.error) {
@@ -311,13 +327,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 +360,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 +432,22 @@ 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) };
+            }
+            // Same stdout strip as standalone `cache --json`: the raw
+            // result carries the build's full stdout from both runs.
+            if (key === 'cache' && result) result = stripCacheStdout(result);
+            // 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/context.mjs

@@ -187,6 +187,143 @@ function readAiignore(root) {
   }
 }
 
+function escapeRegExpChar(ch) {
+  return ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Convert one .gitignore glob into a RegExp (anchored at both ends).
+ * `*` and `?` never cross a `/`; `**` does — `**/` at the start matches
+ * zero or more directories, a trailing `/**` matches everything under a
+ * directory, and a bare `**` matches anything. `[...]` is a character
+ * class, with git's `!` negation spelled `^` for the RegExp.
+ */
+function gitignorePatternToRegExp(pattern) {
+  let out = '';
+  let i = 0;
+  while (i < pattern.length) {
+    const ch = pattern[i];
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        if (pattern[i + 2] === '/') {
+          out += '(?:.*/)?';
+          i += 3;
+        } else {
+          out += '.*';
+          i += 2;
+        }
+      } else {
+        out += '[^/]*';
+        i += 1;
+      }
+    } else if (ch === '?') {
+      out += '[^/]';
+      i += 1;
+    } else if (ch === '[') {
+      let j = i + 1;
+      let negated = false;
+      if (pattern[j] === '!') {
+        negated = true;
+        j += 1;
+      }
+      if (pattern[j] === ']') j += 1; // a leading ] is literal
+      while (j < pattern.length && pattern[j] !== ']') j += 1;
+      if (j >= pattern.length) {
+        out += '\\[';
+        i += 1;
+      } else {
+        const inner = pattern.slice(i + 1 + (negated ? 1 : 0), j).replace(/\\/g, '\\\\');
+        out += `[${negated ? '^' : ''}${inner}]`;
+        i = j + 1;
+      }
+    } else {
+      out += escapeRegExpChar(ch);
+      i += 1;
+    }
+  }
+  return new RegExp(`^${out}$`);
+}
+
+/**
+ * Parse .gitignore content into rules. Supports the common subset of
+ * git's pattern language: blank lines and `#` comments are skipped, a
+ * leading `!` negates (last matching pattern wins), a trailing `/`
+ * matches directories only, a leading `/` — or a `/` anywhere else in
+ * the pattern — anchors it to the .gitignore's own directory, otherwise
+ * the pattern matches a basename at any depth. `\\#` and `\\!` at the
+ * start of a line are literal. Trailing spaces are stripped, as git
+ * does. `.git/info/exclude` and the global gitignore are not read —
+ * only `.gitignore` files in the scanned tree.
+ */
+export function parseGitignore(text) {
+  const rules = [];
+  for (let raw of String(text).split(/\r?\n/)) {
+    raw = raw.replace(/ +$/, '');
+    if (!raw) continue;
+    if (raw.startsWith('\\#') || raw.startsWith('\\!')) raw = raw.slice(1);
+    else if (raw.startsWith('#')) continue;
+    let negate = false;
+    if (raw.startsWith('!')) {
+      negate = true;
+      raw = raw.slice(1);
+      if (!raw) continue;
+    }
+    let dirOnly = false;
+    if (raw.endsWith('/')) {
+      dirOnly = true;
+      raw = raw.slice(0, -1);
+      if (!raw) continue;
+    }
+    let anchored = false;
+    if (raw.startsWith('/')) {
+      anchored = true;
+      raw = raw.slice(1);
+      if (!raw) continue;
+    } else if (raw.includes('/')) {
+      anchored = true;
+    }
+    rules.push({ negate, dirOnly, anchored, regex: gitignorePatternToRegExp(raw) });
+  }
+  return rules;
+}
+
+/**
+ * Is this repo-relative path ignored by the .gitignore stack? Each level
+ * is `{ base, rules }`, where `base` is the .gitignore's directory
+ * relative to the repo root (`''` for the root). Deeper levels are
+ * checked after shallower ones, and the last matching pattern decides —
+ * so a `!` negation re-includes a file, but only when no parent
+ * directory was pruned first (the walk never descends into an ignored
+ * directory, which is also git's rule: a file cannot be re-included
+ * under an excluded parent).
+ */
+export function isGitignored(relativePath, isDir, stack) {
+  const normalized = String(relativePath).split(path.sep).join('/').split('\\').join('/');
+  let ignored = false;
+  for (const { base, rules } of stack) {
+    let rel;
+    if (base === '') rel = normalized;
+    else if (normalized === base) continue; // a rule cannot ignore its own directory
+    else if (normalized.startsWith(`${base}/`)) rel = normalized.slice(base.length + 1);
+    else continue;
+    for (const rule of rules) {
+      if (rule.dirOnly && !isDir) continue;
+      const candidate = rule.anchored ? rel : rel.split('/').pop();
+      if (rule.regex.test(candidate)) ignored = !rule.negate;
+    }
+  }
+  return ignored;
+}
+
+function readGitignore(dir, base) {
+  try {
+    const rules = parseGitignore(fs.readFileSync(path.join(dir, '.gitignore'), 'utf8'));
+    return rules.length > 0 ? { base, rules } : null;
+  } catch {
+    return null;
+  }
+}
+
 function walk(root, dir, out, state) {
   let entries;
   try {
@@ -205,11 +342,16 @@ function walk(root, dir, out, state) {
     if (entry.isDirectory()) {
       if (IGNORED_DIRS.has(entry.name)) continue;
       if (state.ignore.length > 0 && matchesAiignore(rel, state.ignore)) continue;
+      if (isGitignored(rel, true, state.gitignore)) continue;
+      const level = readGitignore(full, rel);
+      if (level) state.gitignore.push(level);
       walk(root, full, out, state);
+      if (level) state.gitignore.pop();
       continue;
     }
     if (!entry.isFile()) continue;
     if (state.ignore.length > 0 && matchesAiignore(rel, state.ignore)) continue;
+    if (isGitignored(rel, false, state.gitignore)) continue;
     if (state.files >= state.maxFiles) {
       state.truncated = true;
       continue;
@@ -233,7 +375,10 @@ function walk(root, dir, out, state) {
  * under-counting. Files listed in the repo's `.aiignore` are excluded
  * from the scan entirely — they are what the agent will not be handed,
  * so they are not noise any more — which is also what makes
- * `context --fix` followed by `context` come back clean.
+ * `context --fix` followed by `context` come back clean. Files and
+ * directories listed in `.gitignore` (at the root or nested) are
+ * excluded the same way: they are already invisible to most agents, so
+ * flagging them would be noise about noise.
  */
 export function scanDirectory(root, options = {}) {
   const absolute = path.resolve(root);
@@ -246,7 +391,10 @@ export function scanDirectory(root, options = {}) {
   if (!stat.isDirectory()) throw new Error(`not a directory: ${root}`);
   const maxFiles = options.maxFiles == null ? 10000 : options.maxFiles;
   const ignore = readAiignore(absolute);
-  const state = { files: 0, bytes: 0, maxFiles, truncated: false, ignore };
+  const gitignore = [];
+  const rootLevel = readGitignore(absolute, '');
+  if (rootLevel) gitignore.push(rootLevel);
+  const state = { files: 0, bytes: 0, maxFiles, truncated: false, ignore, gitignore };
   const files = [];
   walk(absolute, absolute, files, state);
 

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.8"
+}