dev-diagnosis-cli 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.1.3 — unreleased
+
+- Fix: nested build-output directories are reported by their full path
+  from the repo root (`packages/foo/dist/`) instead of a bare `dist/` —
+  the bare entry only matches top-level output, so `--fix` on a repo
+  whose build output lives in a subdirectory wrote an `.aiignore`
+  entry the next scan ignored, and the scan kept failing after the
+  fix. Files under one build directory are also rolled up into a
+  single row instead of one row per file. (53 tests.)
+
+## 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

package/README.md

@@ -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`.
+`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.
 
@@ -92,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. 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.
 
 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,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 — 41 tests
+npm test            # node:test, no extra dependencies — 53 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');
@@ -360,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/lib/context.mjs

@@ -96,9 +96,15 @@ export function classifyPath(relativePath, size = 0) {
   const parts = normalized.split('/');
   const basename = parts[parts.length - 1];
 
-  for (const part of parts.slice(0, -1)) {
-    if (NOISE_DIRS.has(part)) {
-      return { noise: { label: `${part}/`, reason: NOISE_DIRS.get(part) }, suggestion: `${part}/` };
+  // A noise directory is reported by its full path from the repo root
+  // (packages/foo/dist/), not just its name: two build directories in
+  // different parts of the tree would otherwise print the same label,
+  // and the .aiignore entry --fix writes has to match the whole path —
+  // a bare dist/ only ignores top-level build output.
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    if (NOISE_DIRS.has(parts[i])) {
+      const dir = `${parts.slice(0, i + 1).join('/')}/`;
+      return { noise: { label: dir, reason: NOISE_DIRS.get(parts[i]) }, suggestion: dir };
     }
   }
   if (LOCKFILES.has(basename)) {
@@ -125,6 +131,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 {
@@ -142,10 +198,12 @@ function walk(root, dir, out, state) {
     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;
@@ -166,7 +224,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);
@@ -178,17 +239,33 @@ 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);
 
   const noise = [];
+  // One row per build-output directory, not one row per file inside it:
+  // a dist/ with hundreds of files would otherwise flood the noise list
+  // (and the score uses the summed bytes either way).
+  const dirNoise = new Map();
   const review = [];
   const suggestions = new Set();
   for (const file of files) {
     const result = classifyPath(file.relativePath, file.size);
     if (result.noise) {
-      noise.push({ ...result.noise, bytes: file.size, path: file.relativePath.split(path.sep).join('/') });
+      const item = { ...result.noise, bytes: file.size, path: file.relativePath.split(path.sep).join('/') };
+      if (item.label.endsWith('/')) {
+        const existing = dirNoise.get(item.label);
+        if (existing) existing.bytes += file.size;
+        else {
+          const aggregated = { label: item.label, reason: item.reason, bytes: file.size, path: item.label };
+          dirNoise.set(item.label, aggregated);
+          noise.push(aggregated);
+        }
+      } else {
+        noise.push(item);
+      }
       if (result.suggestion) suggestions.add(result.suggestion);
     } else if (result.review) {
       review.push({ ...result.review, bytes: file.size, path: file.relativePath.split(path.sep).join('/') });
@@ -211,3 +288,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.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"}