dev-diagnosis-cli 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.1.2 — 2026-11-11
+
+- New: `context --fix` (and `all --fix`) writes the `.aiignore`
+  suggestions into `<path>/.aiignore` instead of only printing them —
+  entries already there are left alone, nothing else in the file is
+  touched, and no file is created when there is nothing to add. The fix
+  outcome is included in `--json` output.
+- Fix: the context scan now honours the repo's `.aiignore` — files it
+  lists are excluded from the scan entirely, so applying the fix and
+  re-scanning comes back clean instead of failing on the same noise
+  forever. (50 tests.)
+
+## 0.1.1 — 2026-11-11
+
+- Docs: README now has npm version, CI, license and Node badges, and the
+  example output is regenerated verbatim — its paths match the repo layout.
+- Fix: the demo build and the cache test fixture now simulate 400 ms of
+  work (was 150 ms), so the cache check's verdict stays decisive even on
+  loaded CI machines — 0.1.1's first CI run failed one job (macOS, Node 22)
+  because a 41 ms saving fell under the 50 ms "cache pays" threshold.
+- Fix: `all` on a repo with no build cache no longer ends in FAIL — a
+  build command with no cache directory to measure is listed as skipped,
+  with the `--cache-dir` hint, instead of a failed cache check. (41 tests.)
+
 ## 0.1.0 — 2026-11-10
 
 - First release: one CLI combining the four diagnostic checks.

package/README.md

@@ -1,5 +1,10 @@
 # dev-diagnosis
 
+[![npm version](https://img.shields.io/npm/v/dev-diagnosis-cli.svg)](https://www.npmjs.com/package/dev-diagnosis-cli)
+[![CI](https://github.com/WJDdidi-1/dev-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/WJDdidi-1/dev-doctor/actions/workflows/ci.yml)
+[![license](https://img.shields.io/github/license/WJDdidi-1/dev-doctor.svg)](https://github.com/WJDdidi-1/dev-doctor/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/dev-diagnosis-cli.svg)](https://www.npmjs.com/package/dev-diagnosis-cli)
+
 One command that diagnoses your repo, your commands, your cache and your tests. It runs four checks that used to be four separate tools — whether an AI coding agent would read files it should not (`context`), why a CLI command is missing (`path`), whether a build cache actually pays (`cache`), and which tests are flaky (`flakes`) — and prints one report with a verdict per check. It is offline, has no runtime dependencies (Node.js standard library only), and works on Linux, macOS and Windows.
 
 ## Install and run
@@ -25,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. `--json` gives machine-readable output for `context`, `path`, `flakes` and `all`.
+`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.
 
 Exit codes: `0` every check that ran passed; `1` a check found something to fix or could not run; `2` usage error.
 
@@ -35,10 +40,10 @@ The repo ships a small demo project in `examples/demo-repo` (a build output, a l
 
 ```
 $ dev-diagnosis all examples/demo-repo --command node --flakes examples/runs -- node build.mjs
-dev-diagnosis — /home/hatch/workspace/dev-diagnosis-build/dev-diagnosis/examples/demo-repo
+dev-diagnosis — /home/hatch/workspace/dev-doctor-build/dev-doctor/examples/demo-repo
 
 == context ==
-Repo: /home/hatch/workspace/dev-diagnosis-build/dev-diagnosis/examples/demo-repo
+Repo: /home/hatch/workspace/dev-doctor-build/dev-doctor/examples/demo-repo
 Files: 9  Size: 1.68 MB  Score: 75/100 — Some context noise found
   build output: 98 B (0%) — lost 0 of 40
   large files: 1.68 MB (99.9%) — lost 25 of 25
@@ -72,11 +77,11 @@ com.example.CheckoutTest::appliesCoupon             1/2     2      new  passed-o
 FAIL  1 flaky, 1 always-failing across 2 runs
 
 == cache ==
-Cache dir: /home/hatch/workspace/dev-diagnosis-build/dev-diagnosis/examples/demo-repo/.cache
+Cache dir: /home/hatch/workspace/dev-doctor-build/dev-doctor/examples/demo-repo/.cache
 Command: node build.mjs
-Cold: 234 ms  Warm: 80 ms  Saved: 154 ms (66%)
-Verdict: cache pays — warm run is 154 ms (66%) faster than cold
-PASS  cache pays: cold 234 ms, warm 80 ms (warm run is 154 ms (66%) faster than cold)
+Cold: 491 ms  Warm: 90 ms  Saved: 401 ms (82%)
+Verdict: cache pays — warm run is 401 ms (82%) faster than cold
+PASS  cache pays: cold 491 ms, warm 90 ms (warm run is 401 ms (82%) faster than cold)
 
 Overall: FAIL — see the checks above
 ```
@@ -87,7 +92,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.
+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. 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.
 
@@ -106,7 +111,7 @@ Reads JUnit XML across CI runs — each subdirectory of `<junit-dir>` is one run
 ## Development
 
 ```sh
-npm test            # node:test, no extra dependencies — 40 tests
+npm test            # node:test, no extra dependencies — 50 tests
 npm run example     # run the CLI against the demo fixture
 ```
 

package/bin/dev-diagnosis.js

@@ -15,7 +15,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { scanDirectory, formatBytes } from '../lib/context.mjs';
+import { scanDirectory, applyAiignore, formatBytes } from '../lib/context.mjs';
 import {
   buildContexts, findCommandCopies, fixForDirectory, lookupCommand,
   searchToolchainBins,
@@ -31,8 +31,8 @@ const VERSION = JSON.parse(
 const USAGE = `dev-diagnosis: one diagnosis for your repo, your commands, your cache and your tests.
 
 Usage:
-  dev-diagnosis [all] [path] [--command <name>] [--flakes <dir>] [-- <build-command...>]
-  dev-diagnosis context [path] [--json]
+  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 flakes <runs-dir> [--json] [--top N]
@@ -61,6 +61,10 @@ Commands:
 
 Options:
   --json          machine-readable output (context, path, 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
+                  file is changed.
   --top N         show only the N highest-ranked flaky tests
   -h, --help      show this help
   -v, --version   print the version
@@ -78,7 +82,7 @@ class UsageError extends Error {
 
 function parseArgs(argv) {
   const parsed = {
-    command: null, positional: [], json: false, help: false, version: false,
+    command: null, positional: [], json: false, fix: false, help: false, version: false,
     commandName: null, flakesDir: null, cacheDir: null, cwd: null, top: null,
     buildCommand: null, error: null,
   };
@@ -90,6 +94,7 @@ function parseArgs(argv) {
       break;
     }
     if (arg === '--json' || arg === '-j') parsed.json = true;
+    else if (arg === '--fix') parsed.fix = true;
     else if (arg === '--help' || arg === '-h') parsed.help = true;
     else if (arg === '--version' || arg === '-v') parsed.version = true;
     else if (arg === '--command') {
@@ -166,6 +171,28 @@ function runContext(target) {
   return { result, passed, verdict: passed ? 'context is clean' : `${result.status.toLowerCase()} (score ${result.score}/100)` };
 }
 
+// Apply the context check's .aiignore suggestions and record the outcome
+// on the check result, so --json output carries it too.
+function applyContextFix(check) {
+  const fix = applyAiignore(check.result.root, check.result.suggestions);
+  check.result.fix = fix;
+  return fix;
+}
+
+function printFixLine(fix, suggestionCount) {
+  if (fix.added.length > 0) {
+    const noun = fix.added.length === 1 ? 'entry' : 'entries';
+    const lead = fix.created
+      ? `Created .aiignore with ${fix.added.length} ${noun}`
+      : `Added ${fix.added.length} ${noun} to .aiignore`;
+    console.log(`${lead}: ${fix.added.join(', ')}`);
+  } else if (suggestionCount === 0) {
+    console.log('Nothing to add to .aiignore: no suggestions.');
+  } else {
+    console.log('Nothing added: .aiignore already has all suggestions.');
+  }
+}
+
 function printPath(result, json) {
   if (json) {
     console.log(JSON.stringify(result, null, 2));
@@ -276,11 +303,23 @@ function main(argv) {
   }
 
   const command = args.command || 'all';
+  if (args.fix && command !== 'context' && command !== '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') {
       const target = args.positional[0];
       const check = runContext(target);
+      // In --json mode the fix must be part of the printed object, so it
+      // runs before printing; in text mode the report prints first, so a
+      // failed write still leaves the diagnosis on screen.
+      if (args.fix && args.json) applyContextFix(check);
       printContext(check.result, args.json);
+      if (args.fix && !args.json) {
+        printFixLine(applyContextFix(check), check.result.suggestions.length);
+      }
       if (!args.json) console.log(verdictLine(check.passed, check.verdict));
       return check.passed ? 0 : 1;
     }
@@ -312,6 +351,12 @@ function main(argv) {
 
       const contextCheck = runContext(root);
       checks.context = contextCheck;
+      let contextFix = null;
+      const getContextFix = () => {
+        if (!contextFix) contextFix = applyContextFix(contextCheck);
+        return contextFix;
+      };
+      if (args.fix && args.json) getContextFix();
       const pathCheck = args.commandName ? runPath(args.commandName) : null;
       if (pathCheck) checks.path = pathCheck;
       else skipped.push('path — pass --command <name>, for example: dev-diagnosis all --command node');
@@ -333,8 +378,14 @@ function main(argv) {
           cacheCheck = runCache({ buildCommand: args.buildCommand, cacheDir: args.cacheDir, cwd: root });
           checks.cache = cacheCheck;
         } catch (error) {
-          checks.cache = { result: null, passed: false, verdict: `could not run: ${error.message}`, error: error.message };
-          cacheCheck = checks.cache;
+          if (String(error.message).includes('no cache directory found')) {
+            // Nothing to measure is not a failure: report it as skipped so
+            // `all` on a repo without a build cache does not end in FAIL.
+            skipped.push('cache — no cache directory found in this project; pass --cache-dir <dir> to measure one');
+          } else {
+            checks.cache = { result: null, passed: false, verdict: `could not run: ${error.message}`, error: error.message };
+            cacheCheck = checks.cache;
+          }
         }
       } else {
         skipped.push('cache — add -- <build-command>, for example: dev-diagnosis all -- node build.mjs');
@@ -354,6 +405,7 @@ function main(argv) {
       console.log(`dev-diagnosis — ${root}`);
       console.log(section('context'));
       printContext(contextCheck.result, false);
+      if (args.fix) printFixLine(getContextFix(), contextCheck.result.suggestions.length);
       console.log(verdictLine(contextCheck.passed, contextCheck.verdict));
       if (pathCheck) {
         console.log(section('path'));

package/examples/demo-repo/build.mjs

@@ -1,6 +1,8 @@
 // Demo build: slow on a cold cache, fast on a warm one.
 // If .cache/out.txt exists the work is already done; otherwise this
-// script simulates 150 ms of real work and writes the cache file.
+// script simulates 400 ms of real work and writes the cache file.
+// 400 ms (not 150) so the cold-vs-warm gap dwarfs Node startup time
+// and stays decisive on loaded CI machines.
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -9,7 +11,7 @@ const out = path.join(cacheDir, 'out.txt');
 if (fs.existsSync(out)) {
   console.log('cache hit');
 } else {
-  const until = Date.now() + 150;
+  const until = Date.now() + 400;
   while (Date.now() < until) { /* simulate work the cache would skip */ }
   fs.mkdirSync(cacheDir, { recursive: true });
   fs.writeFileSync(out, 'built\n');

package/lib/context.mjs

@@ -125,6 +125,56 @@ export function classifyPath(relativePath, size = 0) {
   return { suggestion: null };
 }
 
+function patternToRegExp(pattern) {
+  let out = '';
+  for (const ch of pattern) {
+    if (ch === '*') out += '[^/]*';
+    else if (ch === '?') out += '[^/]';
+    else out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${out}$`);
+}
+
+/**
+ * Does a .aiignore pattern match this repo-relative path? Patterns are
+ * the small subset the tool itself writes: `dir/` matches everything
+ * under that directory, a pattern with a slash matches the whole path,
+ * anything else matches the basename as a glob (`*` and `?` only).
+ * Comment, blank and negation (`!`) lines never match: negation is not
+ * supported, and silently treating one as an ignore would hide files
+ * the user explicitly wanted back.
+ */
+export function matchesAiignore(relativePath, patterns) {
+  const normalized = String(relativePath).split(path.sep).join('/').split('\\').join('/');
+  const basename = normalized.split('/').pop();
+  for (const raw of patterns) {
+    const pattern = String(raw).trim();
+    if (!pattern || pattern.startsWith('#') || pattern.startsWith('!')) continue;
+    if (pattern.endsWith('/')) {
+      const dir = pattern.slice(0, -1);
+      if (normalized === dir || normalized.startsWith(`${dir}/`)) return true;
+      continue;
+    }
+    if (pattern.includes('/')) {
+      if (patternToRegExp(pattern).test(normalized)) return true;
+    } else if (patternToRegExp(pattern).test(basename)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function readAiignore(root) {
+  try {
+    return fs.readFileSync(path.join(root, '.aiignore'), 'utf8')
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith('#') && !line.startsWith('!'));
+  } catch {
+    return [];
+  }
+}
+
 function walk(root, dir, out, state) {
   let entries;
   try {
@@ -137,13 +187,17 @@ function walk(root, dir, out, state) {
   entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
   for (const entry of entries) {
     const full = path.join(dir, entry.name);
-    const rel = path.relative(root, full);
+    // Always report forward slashes, so output (and tests) are identical
+    // on Windows, macOS and Linux.
+    const rel = path.relative(root, full).split(path.sep).join('/');
     if (entry.isDirectory()) {
       if (IGNORED_DIRS.has(entry.name)) continue;
+      if (state.ignore.length > 0 && matchesAiignore(rel, state.ignore)) continue;
       walk(root, full, out, state);
       continue;
     }
     if (!entry.isFile()) continue;
+    if (state.ignore.length > 0 && matchesAiignore(rel, state.ignore)) continue;
     if (state.files >= state.maxFiles) {
       state.truncated = true;
       continue;
@@ -164,7 +218,10 @@ function walk(root, dir, out, state) {
  * Scan a directory and describe how much of it is context noise.
  * Synchronous and dependency-free, like the original. `maxFiles` caps the
  * walk; a capped walk reports `truncated: true` instead of silently
- * under-counting.
+ * 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.
  */
 export function scanDirectory(root, options = {}) {
   const absolute = path.resolve(root);
@@ -176,7 +233,8 @@ export function scanDirectory(root, options = {}) {
   }
   if (!stat.isDirectory()) throw new Error(`not a directory: ${root}`);
   const maxFiles = options.maxFiles == null ? 10000 : options.maxFiles;
-  const state = { files: 0, bytes: 0, maxFiles, truncated: false };
+  const ignore = readAiignore(absolute);
+  const state = { files: 0, bytes: 0, maxFiles, truncated: false, ignore };
   const files = [];
   walk(absolute, absolute, files, state);
 
@@ -209,3 +267,43 @@ export function scanDirectory(root, options = {}) {
     status: statusFor(scored.score),
   };
 }
+
+/**
+ * Write the scan's .aiignore suggestions into `<root>/.aiignore`.
+ * Only appends entries that are not already there (compared after
+ * trimming); existing content is never removed or reordered, and no file
+ * is created when there is nothing to add. Returns what happened so the
+ * CLI can report it: `{ path, added, alreadyPresent, created }`.
+ */
+export function applyAiignore(root, suggestions) {
+  const target = path.join(path.resolve(root), '.aiignore');
+  const wanted = [...new Set(suggestions)].sort();
+  if (wanted.length === 0) {
+    return { path: target, added: [], alreadyPresent: [], created: false };
+  }
+  let content = '';
+  let created = false;
+  try {
+    content = fs.readFileSync(target, 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw new Error(`cannot read .aiignore: ${error.message}`);
+    created = true;
+  }
+  const present = new Set(
+    content.split(/\r?\n/).map((line) => line.trim()).filter(Boolean),
+  );
+  const added = wanted.filter((entry) => !present.has(entry));
+  if (added.length === 0) {
+    return { path: target, added: [], alreadyPresent: wanted, created: false };
+  }
+  const newline = content.includes('\r\n') ? '\r\n' : '\n';
+  let next = content;
+  if (next.length > 0 && !next.endsWith('\n')) next += newline;
+  next += added.map((entry) => entry + newline).join('');
+  try {
+    fs.writeFileSync(target, next);
+  } catch (error) {
+    throw new Error(`cannot write .aiignore: ${error.message}`);
+  }
+  return { path: target, added, alreadyPresent: wanted.filter((entry) => present.has(entry)), created };
+}

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.0"}
+{"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.2"}