dev-diagnosis-cli 0.1.7 → 0.2.0

package/lib/checks.mjs

@@ -0,0 +1,280 @@
+/**
+ * The four checks, as functions both the CLI and the MCP server call.
+ *
+ * This is the one place the check logic lives: bin/dev-diagnosis.js
+ * renders it for humans, lib/mcp.mjs serves it to agents, and neither
+ * re-implements a verdict. Each runner returns the same shape —
+ * `{ result, passed, verdict }` — and a check that could not run
+ * returns `{ result: null, passed: false, verdict, error }` instead of
+ * throwing, so the `all` report can say why it failed.
+ */
+import { scanDirectory, applyAiignore, formatBytes } from './context.mjs';
+import {
+  buildContexts, findCommandCopies, fixForDirectory, lookupCommand,
+  searchToolchainBins,
+} from './pathcheck.mjs';
+import { runCacheCheck as runCacheCheckImpl } from './cache.mjs';
+import { scanRuns } from './flakes.mjs';
+import { formatMs } from './report.mjs';
+
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+// "login", "login and daemon-like", "login, non-login and daemon-like".
+function joinNames(names) {
+  if (names.length <= 1) return names.join('');
+  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+}
+
+export function runContextCheck(target) {
+  const result = scanDirectory(target || process.cwd());
+  const passed = result.score >= 85;
+  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.
+ */
+export function applyContextFix(check) {
+  const fix = applyAiignore(check.result.root, check.result.suggestions);
+  check.result.fix = fix;
+  return fix;
+}
+
+/**
+ * Apply a context check's .aiignore fix, then re-scan so the returned
+ * check describes the repo as it stands after the fix. The fix outcome
+ * is carried onto the re-scanned result, so --json and MCP output still
+ * say what was written. Without the re-scan, `context --fix` on a noisy
+ * repo would report the pre-fix verdict — exit 1 and FAIL — even though
+ * the fix landed and a re-run scores clean. The exit code of a fix
+ * command should say whether the repo is fixed now, the way
+ * eslint --fix does: it exits 0 when everything it could fix is fixed.
+ */
+export function applyContextFixAndRescan(check) {
+  const fix = applyContextFix(check);
+  const fixed = runContextCheck(check.result.root);
+  fixed.result.fix = fix;
+  return fixed;
+}
+
+/**
+ * Re-scan the context check of an `all` run after --fix, and refresh
+ * the run's overall verdict and summary to match. The pre-fix report
+ * stays printed above; what changes is the verdict the run reports.
+ * The fix outcome recorded by applyContextFix is carried over, so the
+ * post-fix result still says what was written.
+ */
+export function rescanContext(run) {
+  const before = run.checks.context;
+  const fixed = runContextCheck(run.root);
+  if (before?.result?.fix) fixed.result.fix = before.result.fix;
+  run.checks.context = fixed;
+  run.overall = Object.values(run.checks).every((check) => check.passed);
+  run.summary = buildSummary(run.checks, run.skipped);
+  return fixed;
+}
+
+export function runPathCheck(commandName) {
+  if (!commandName) throw new UsageError('path needs a command, for example: dev-diagnosis path node');
+  const contexts = buildContexts();
+  const rows = contexts.map((ctx) => {
+    const found = lookupCommand(commandName, ctx.pathValue);
+    return { ...ctx, resolved: found.resolved, path: found.path, reason: found.reason || null };
+  });
+  const copies = findCommandCopies(commandName, process.env.PATH || '');
+  const toolchainHits = rows[0].resolved ? [] : searchToolchainBins(commandName);
+  let fix = null;
+  if (!rows[0].resolved && toolchainHits.length > 0) fix = fixForDirectory(toolchainHits[0].directory);
+  else if (!rows[0].resolved && rows.some((row) => row.resolved)) {
+    fix = 'it resolves in another shell context — check which startup file sets your PATH';
+  }
+  const passed = rows[0].resolved;
+  // The verdict must agree with the four-context table above it: "missing
+  // in the current shell" was wrong on both sides — when the command
+  // missed everywhere it sounded like it might exist elsewhere, and when
+  // it resolved in another context it never said where. Name the contexts
+  // it resolves in, or say plainly that no context has it.
+  const foundIn = rows.filter((row) => row.resolved).map((row) => row.name);
+  let verdict;
+  if (passed) verdict = `${commandName} resolves to ${rows[0].path}`;
+  else if (foundIn.length > 0) verdict = `${commandName} is missing in the current shell, but resolves in ${joinNames(foundIn)}`;
+  else verdict = `${commandName} is not found in any shell context`;
+  return {
+    result: { command: commandName, contexts: rows, copies, toolchainHits, fix },
+    passed,
+    verdict,
+  };
+}
+
+export function runFlakesCheck(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;
+  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: problems.length > 0 ? `${base}; ${problems.join('; ')}` : base,
+  };
+}
+
+export function runCacheCheck(options) {
+  if (!options.buildCommand || options.buildCommand.length === 0) {
+    throw new UsageError('cache needs a build command after --, for example: dev-diagnosis cache -- node build.mjs');
+  }
+  const result = runCacheCheckImpl({
+    root: options.cwd || process.cwd(),
+    cacheDir: options.cacheDir,
+    command: options.buildCommand,
+  });
+  const passed = result.verdict !== 'cache costs';
+  return {
+    result,
+    passed,
+    verdict: `${result.verdict}: cold ${formatMs(result.coldMs)}, warm ${formatMs(result.warmMs)} (${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 the standalone cache output and by the
+// `all --json` builder below, so both shapes stay identical.
+export function stripCacheStdout(result) {
+  const { coldStdout, warmStdout, ...rest } = result;
+  return rest;
+}
+
+/**
+ * One-line summary of an `all` run: how many checks passed, failed or
+ * were skipped, how much context noise was found, and what the cache
+ * saved when it ran. `contextNoiseBytes` is the listed noise — the
+ * same bytes the token estimate is based on.
+ */
+export function buildSummary(checks, skipped) {
+  const ran = Object.values(checks);
+  const passed = ran.filter((check) => check.passed).length;
+  const noiseBytes = checks.context && checks.context.result
+    ? checks.context.result.noise.reduce((sum, item) => sum + item.bytes, 0)
+    : 0;
+  const cacheResult = checks.cache && checks.cache.result ? checks.cache.result : null;
+  return {
+    checks: { total: ran.length + skipped.length, passed, failed: ran.length - passed, skipped: skipped.length },
+    contextNoiseBytes: noiseBytes,
+    cacheSavedPct: cacheResult ? cacheResult.savedPct : null,
+  };
+}
+
+export function formatSummary(summary) {
+  const parts = [
+    `${summary.checks.total} checks — ${summary.checks.passed} passed, ${summary.checks.failed} failed, ${summary.checks.skipped} skipped`,
+  ];
+  if (summary.contextNoiseBytes > 0) parts.push(`context noise ${formatBytes(summary.contextNoiseBytes)}`);
+  if (summary.cacheSavedPct != null) parts.push(`cache saved ${summary.cacheSavedPct}%`);
+  return `Summary: ${parts.join('; ')}`;
+}
+
+/**
+ * Run every check that has what it needs, the way `all` does. The
+ * context fix is not applied here: the caller decides when, so the
+ * human report can print the diagnosis before writing .aiignore, and
+ * the JSON report can include the fix outcome. Call the returned
+ * `applyContextFix()` (memoized) when the fix should happen.
+ */
+export function runAll(options = {}) {
+  const root = options.root;
+  const checks = {};
+  const skipped = [];
+
+  const contextCheck = runContextCheck(root);
+  checks.context = contextCheck;
+  let contextFix = null;
+  const applyFix = () => {
+    if (!contextFix) contextFix = applyContextFix(contextCheck);
+    return contextFix;
+  };
+
+  if (options.commandName) checks.path = runPathCheck(options.commandName);
+  else skipped.push('path — pass --command <name>, for example: dev-diagnosis all --command node');
+
+  if (options.flakesDir) {
+    try {
+      checks.flakes = runFlakesCheck(options.flakesDir);
+    } catch (error) {
+      checks.flakes = { result: null, passed: false, verdict: `could not run: ${error.message}`, error: error.message };
+    }
+  } else {
+    skipped.push('flakes — pass --flakes <runs-dir>, for example: dev-diagnosis all --flakes examples/runs');
+  }
+
+  if (options.buildCommand && options.buildCommand.length > 0) {
+    try {
+      checks.cache = runCacheCheck({ buildCommand: options.buildCommand, cacheDir: options.cacheDir, cwd: root });
+    } catch (error) {
+      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 };
+      }
+    }
+  } else {
+    skipped.push('cache — add -- <build-command>, for example: dev-diagnosis all -- node build.mjs');
+  }
+
+  const overall = Object.values(checks).every((check) => check.passed);
+  return {
+    root, checks, skipped, overall,
+    summary: buildSummary(checks, skipped),
+    applyContextFix: applyFix,
+  };
+}
+
+/**
+ * The `all --json` shape: each check's result (flakes limited by
+ * --top, cache without the build stdout), failed checks carrying their
+ * reason instead of null, plus the summary.
+ */
+export function allJson(run, top = null) {
+  return {
+    command: 'all',
+    root: run.root,
+    checks: Object.fromEntries(Object.entries(run.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 && top != null) {
+        result = { ...result, tests: result.tests.slice(0, 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: run.skipped,
+    overall: run.overall ? 'PASS' : 'FAIL',
+    summary: run.summary,
+  };
+}

package/lib/context.mjs

@@ -56,6 +56,17 @@ export function formatBytes(bytes) {
   return `${value.toFixed(value >= 10 ? 1 : 2)} ${unit}`;
 }
 
+/**
+ * Rough token cost of the listed noise: about 4 bytes per token, the
+ * rule of thumb most tokenizers land near. It is an estimate, not a
+ * count — the label in the output says so. Returns null when there is
+ * no listed noise, so a clean repo does not claim a saving of zero.
+ */
+export function estimateTokens(bytes) {
+  if (!bytes || bytes <= 0) return null;
+  return Math.round(bytes / 4);
+}
+
 function noiseCategory(reason) {
   if (reason === 'lockfile') return 'lockfile';
   if (reason === 'local log file') return 'log';
@@ -187,6 +198,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 +353,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 +386,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,40 +402,67 @@ 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);
 
-  const noise = [];
+  const allNoise = [];
   // 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();
+  const reviewSuggestions = new Set();
   for (const file of files) {
     const result = classifyPath(file.relativePath, file.size);
     if (result.noise) {
-      const item = { ...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('/'),
+        suggestion: result.suggestion || null,
+      };
       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 };
+          const aggregated = { label: item.label, reason: item.reason, bytes: file.size, path: item.label, suggestion: result.suggestion || null };
           dirNoise.set(item.label, aggregated);
-          noise.push(aggregated);
+          allNoise.push(aggregated);
         }
       } else {
-        noise.push(item);
+        allNoise.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('/') });
-      if (result.suggestion) suggestions.add(result.suggestion);
+      if (result.suggestion) reviewSuggestions.add(result.suggestion);
     }
   }
 
-  const scored = scoreNoise(noise, state.bytes);
+  const scored = scoreNoise(allNoise, state.bytes);
+  // Only noise in a category that actually lost points is reported. A
+  // 95 B lockfile in a 1.7 MB repo loses 0 points, so listing it as
+  // "noise to keep away" — with a fix suggestion — would contradict the
+  // PASS verdict on a 100/100 scan. The score itself still uses every
+  // noise byte; the filter only decides what is worth fixing.
+  const costly = new Set(scored.breakdown.filter((item) => item.lost > 0).map((item) => item.id));
+  const noise = allNoise
+    .filter((item) => costly.has(noiseCategory(item.reason)))
+    .map(({ suggestion, ...item }) => item);
+  const suggestions = new Set();
+  for (const item of allNoise) {
+    if (item.suggestion && costly.has(noiseCategory(item.reason))) suggestions.add(item.suggestion);
+  }
+  // Review suggestions are advisory only and are never part of
+  // `suggestions`, so --fix never writes them: a review item costs no
+  // score points, so writing its entry would fix nothing — and a
+  // basename pattern like `secret.js` would hide every same-named file
+  // in the repo, including harmless test fixtures. They are reported
+  // separately so the user can add them to .aiignore by hand.
+  const noiseBytes = noise.reduce((sum, item) => sum + item.bytes, 0);
   return {
     root: absolute,
     files: state.files,
@@ -288,10 +471,15 @@ export function scanDirectory(root, options = {}) {
     noise,
     review,
     suggestions: [...suggestions].sort(),
+    // Advisory only: --fix never writes these (see above).
+    reviewSuggestions: [...reviewSuggestions].sort(),
     score: scored.score,
     lost: scored.lost,
     breakdown: scored.breakdown,
     status: statusFor(scored.score),
+    // What the listed noise costs in tokens, at ~4 bytes per token
+    // (estimate, not a count); null when there is no listed noise.
+    estimatedTokens: estimateTokens(noiseBytes),
   };
 }