dev-diagnosis-cli 0.0.0-stage → 0.1.1

package/examples/demo-repo/dist/app.bundle.js

@@ -0,0 +1,2 @@
+// Generated build output — an AI agent does not need to read this.
+console.log('bundled app');

package/examples/demo-repo/logs/dev.log

@@ -0,0 +1,2 @@
+2026-11-10T08:00:00Z dev server started
+2026-11-10T08:00:01Z request GET / 200

package/examples/demo-repo/package-lock.json

@@ -0,0 +1 @@
+{"lockfileVersion":3,"name":"demo-repo","packages":{"":{"name":"demo-repo","version":"0.1.0"}}}

package/examples/demo-repo/package.json

@@ -0,0 +1 @@
+{"name":"demo-repo","private":true,"type":"module","version":"0.1.0"}

package/examples/demo-repo/src/index.js

@@ -0,0 +1 @@
+console.log('demo repo: hello from src/index.js');

package/examples/demo.mjs

@@ -0,0 +1,20 @@
+/**
+ * Demo: run dev-diagnosis against the fixture repo and print the report.
+ * The output is pasted verbatim into the README, so this script prints
+ * only the CLI's own output. The demo repo has real noise and a failing
+ * test on purpose, so the exit code is 1; this script exits 0 so that
+ * `npm run example` stays a demo, not a failing check.
+ */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const bin = path.join(root, 'bin', 'dev-diagnosis.js');
+const result = spawnSync(
+  process.execPath,
+  [bin, 'all', 'examples/demo-repo', '--command', 'node', '--flakes', 'examples/runs', '--', 'node', 'build.mjs'],
+  { cwd: root, encoding: 'utf8' },
+);
+process.stdout.write(result.stdout);
+if (result.stderr) process.stderr.write(result.stderr);

package/examples/runs/run-01/results.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<testsuites>
+  <testsuite name="com.example.CheckoutTest" timestamp="2026-01-05T10:00:00">
+    <testcase classname="com.example.CheckoutTest" name="appliesCoupon">
+      <flakyFailure message="expected 10% discount, got 0">
+        <stackTrace>org.opentest4j.AssertionFailedError: expected 10% discount, got 0
+  at CheckoutTest.appliesCoupon(CheckoutTest.java:42)</stackTrace>
+      </flakyFailure>
+    </testcase>
+  </testsuite>
+  <testsuite name="com.example.LoginTest" timestamp="2026-01-05T10:00:00">
+    <testcase classname="com.example.LoginTest" name="rejectsExpiredToken">
+      <failure message="expected 401, got 200">
+        <stackTrace>org.opentest4j.AssertionFailedError: expected 401, got 200</stackTrace>
+      </failure>
+    </testcase>
+  </testsuite>
+  <testsuite name="com.example.SearchTest" timestamp="2026-01-05T10:00:00">
+    <testcase classname="com.example.SearchTest" name="filtersByPrice"/>
+  </testsuite>
+  <testsuite name="com.example.CartTest" timestamp="2026-01-05T10:00:00">
+    <testcase classname="com.example.CartTest" name="addsItem"/>
+  </testsuite>
+  <testsuite name="com.example.ReportTest" timestamp="2026-01-05T10:00:00">
+    <testcase classname="com.example.ReportTest" name="exportsCsv">
+      <skipped message="CSV export not configured"/>
+    </testcase>
+  </testsuite>
+</testsuites>

package/examples/runs/run-02/results.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<testsuites>
+  <testsuite name="com.example.CheckoutTest" timestamp="2026-01-06T10:00:00">
+    <testcase classname="com.example.CheckoutTest" name="appliesCoupon"/>
+  </testsuite>
+  <testsuite name="com.example.LoginTest" timestamp="2026-01-06T10:00:00">
+    <testcase classname="com.example.LoginTest" name="rejectsExpiredToken">
+      <failure message="expected 401, got 200"/>
+    </testcase>
+  </testsuite>
+  <testsuite name="com.example.SearchTest" timestamp="2026-01-06T10:00:00">
+    <testcase classname="com.example.SearchTest" name="filtersByPrice"/>
+  </testsuite>
+  <testsuite name="com.example.CartTest" timestamp="2026-01-06T10:00:00">
+    <testcase classname="com.example.CartTest" name="addsItem"/>
+  </testsuite>
+  <testsuite name="com.example.ReportTest" timestamp="2026-01-06T10:00:00">
+    <testcase classname="com.example.ReportTest" name="exportsCsv">
+      <skipped message="CSV export not configured"/>
+    </testcase>
+  </testsuite>
+</testsuites>

package/lib/cache.mjs

@@ -0,0 +1,159 @@
+/**
+ * Build-cache verdict.
+ *
+ * Simplified from cache-verdict (WJDdidi-1/cache-verdict, Apache-2.0).
+ * The original detects the ecosystem, hashes inputs into a content key,
+ * and keeps a ledger of stored caches. This version does the one thing
+ * the question needs and nothing else: run the same build command twice,
+ * once with the cache moved aside (cold) and once with it present
+ * (warm), time both, and say whether the cache pays. The cache directory
+ * is always restored to exactly the state it was in before the check,
+ * even when a run fails.
+ *
+ * Safety rules, enforced before anything moves:
+ *   - the cache directory must live inside the project root;
+ *   - it must not be the project root, and must not contain the project;
+ *   - it must not be inside dev-diagnosis's own work area (there is none —
+ *     the stash lives in os.tmpdir(), never in the project).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { runCommand } from './run-command.mjs';
+
+export const CACHE_DIR_CANDIDATES = [
+  'node_modules/.cache',
+  '.next/cache',
+  '.cache',
+  '.turbo',
+  'target',
+  '.gradle',
+];
+
+/** First existing cache directory under root, or null. */
+export function detectCacheDir(root) {
+  const absolute = path.resolve(root);
+  for (const candidate of CACHE_DIR_CANDIDATES) {
+    const full = path.join(absolute, candidate);
+    try {
+      if (fs.statSync(full).isDirectory()) return full;
+    } catch { /* not present — try the next candidate */ }
+  }
+  return null;
+}
+
+function assertCacheDirSafe(root, cacheDir) {
+  const project = path.resolve(root);
+  const resolved = path.resolve(cacheDir);
+  if (resolved === project) throw new Error('cacheDir must not point at the project root');
+  const rel = path.relative(project, resolved);
+  if (rel === '' || rel.startsWith(`..${path.sep}`) || rel === '..' || path.isAbsolute(rel)) {
+    throw new Error(`cacheDir ${resolved} is outside the project ${project}`);
+  }
+  const projectInside = path.relative(resolved, project);
+  if (projectInside !== '' && !projectInside.startsWith(`..${path.sep}`) && projectInside !== '..' && !path.isAbsolute(projectInside)) {
+    throw new Error(`cacheDir ${resolved} contains the project itself`);
+  }
+}
+
+function movePath(from, to) {
+  fs.renameSync(from, to);
+}
+
+function removeTree(target) {
+  fs.rmSync(target, { recursive: true, force: true });
+}
+
+/**
+ * Run the build command cold (cache moved aside) and warm (cache present).
+ * Returns timings in ms and a verdict. The cache directory is restored to
+ * its original state in a finally block, whatever happens.
+ */
+export function runCacheCheck(options = {}) {
+  const root = path.resolve(options.root || process.cwd());
+  const command = options.command;
+  if (!Array.isArray(command) || command.length === 0) {
+    throw new Error('cache check needs a build command after --, for example: dev-diagnosis cache -- node build.mjs');
+  }
+  let cacheDir = options.cacheDir ? path.resolve(root, options.cacheDir) : detectCacheDir(root);
+  if (!cacheDir) {
+    throw new Error(
+      'no cache directory found in this project; pass --cache-dir <dir> '
+      + `(looked for ${CACHE_DIR_CANDIDATES.join(', ')})`,
+    );
+  }
+  assertCacheDirSafe(root, cacheDir);
+
+  const stashRoot = path.join(
+    path.dirname(cacheDir),
+    `.dev-diagnosis-stash-${process.pid}-${randomUUID()}`,
+  );
+  // The stash lives next to the cache directory, on the same filesystem:
+  // renaming across devices (for example into os.tmpdir()) fails with
+  // EXDEV. It is removed in the finally block below.
+  fs.mkdirSync(stashRoot);
+  const originalStash = path.join(stashRoot, 'original');
+  const producedStash = path.join(stashRoot, 'produced');
+  const hadOriginal = fs.existsSync(cacheDir);
+  let movedOriginal = false;
+  let movedProduced = false;
+  let originalRestored = false;
+
+  const run = () => runCommand(command, { cwd: root, timeoutMs: options.timeoutMs });
+  let cold;
+  let warm;
+  try {
+    if (hadOriginal) { movePath(cacheDir, originalStash); movedOriginal = true; }
+    cold = run();
+    if (!cold.ok) {
+      throw new Error(`cold build failed (exit ${cold.status ?? 'unknown'}): ${(cold.stderr || cold.error || '').trim().split('\n')[0] || 'no output'}`);
+    }
+    if (hadOriginal) {
+      // Set the freshly produced cache aside; the warm run measures the
+      // cache as it was before this check.
+      if (fs.existsSync(cacheDir)) { movePath(cacheDir, producedStash); movedProduced = true; }
+      movePath(originalStash, cacheDir);
+      originalRestored = true;
+    }
+    // With no original cache, the cold run's output stays in place: it is
+    // the cache the warm run should measure.
+    warm = run();
+    if (!warm.ok) {
+      throw new Error(`warm build failed (exit ${warm.status ?? 'unknown'}): ${(warm.stderr || warm.error || '').trim().split('\n')[0] || 'no output'}`);
+    }
+  } finally {
+    // Restore the original cache exactly. If it was already put back for
+    // the warm run it is sitting in cacheDir now and must be left alone;
+    // only an error before that point leaves it in the stash.
+    try {
+      if (movedOriginal && !originalRestored) {
+        if (fs.existsSync(cacheDir)) removeTree(cacheDir);
+        if (fs.existsSync(originalStash)) movePath(originalStash, cacheDir);
+      }
+      if (movedProduced && fs.existsSync(producedStash)) removeTree(producedStash);
+    } catch { /* best effort: never let cleanup hide the real result */ }
+    try { removeTree(stashRoot); } catch { /* best effort */ }
+  }
+
+  const coldMs = cold.ms;
+  const warmMs = warm.ms;
+  const savedMs = coldMs - warmMs;
+  const savedPct = coldMs > 0 ? Math.round((savedMs / coldMs) * 100) : 0;
+  let verdict;
+  let verdictDetail;
+  if (savedMs >= 50 && savedPct >= 10) {
+    verdict = 'cache pays';
+    verdictDetail = `warm run is ${savedMs.toFixed(0)} ms (${savedPct}%) faster than cold`;
+  } else if (savedMs <= -50 && savedPct <= -10) {
+    verdict = 'cache costs';
+    verdictDetail = `warm run is ${(-savedMs).toFixed(0)} ms (${-savedPct}%) slower than cold — the cache is not helping this build`;
+  } else {
+    verdict = 'inconclusive';
+    verdictDetail = 'cold and warm runs are within noise of each other; rerun to confirm';
+  }
+  return {
+    root, cacheDir, command,
+    coldMs, warmMs, savedMs, savedPct, verdict, verdictDetail,
+    coldStdout: cold.stdout, warmStdout: warm.stdout,
+  };
+}

package/lib/context.mjs

@@ -0,0 +1,213 @@
+/**
+ * Context-noise check.
+ *
+ * Adapted from ai-context-doctor (WJDdidi-1/ai-context-doctor, Apache-2.0):
+ * the same classification rules and the same category-weighted score — build
+ * output costs at most 40 points, large files 25, lockfiles 20, logs 15 —
+ * so one pathological file cannot speak for the whole repository. The
+ * five-dimension score, .aiignore levels and policy handling from the
+ * original are deliberately left out: this is the small, single-purpose
+ * version that answers "what should an AI agent not be handed".
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SECRET_LIKE = /(^\.env(\..+)?$)|(\.env$)|(^credentials(\..+)?$)|(^secrets?(\..+)?$)|(\.pem$)|(\.key$)/i;
+const TEMPLATE = /\.(example|sample|template|dist)$/i;
+
+export const IGNORED_DIRS = new Set(['.git', 'node_modules', '.venv', 'venv', '__pycache__', 'vendor']);
+
+export const NOISE_DIRS = new Map([
+  ['dist', 'generated build output'],
+  ['build', 'generated build output'],
+  ['coverage', 'test coverage output'],
+  ['.next', 'framework output'],
+  ['.turbo', 'framework cache'],
+]);
+
+export const LOCKFILES = new Set(['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock']);
+
+export const LARGE_FILE_THRESHOLD_BYTES = 1024 * 1024;
+
+export const CATEGORY_WEIGHTS = [
+  { id: 'build', label: 'build output', weight: 40 },
+  { id: 'large', label: 'large files', weight: 25 },
+  { id: 'lockfile', label: 'lockfiles', weight: 20 },
+  { id: 'log', label: 'logs', weight: 15 },
+];
+
+export function isSecretLikeFile(basename) {
+  return SECRET_LIKE.test(basename);
+}
+
+export function isTemplateFile(basename) {
+  return TEMPLATE.test(basename);
+}
+
+export function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ['KB', 'MB', 'GB'];
+  let value = bytes / 1024;
+  let unit = units[0];
+  for (let i = 1; i < units.length && value >= 1024; i += 1) {
+    value /= 1024;
+    unit = units[i];
+  }
+  return `${value.toFixed(value >= 10 ? 1 : 2)} ${unit}`;
+}
+
+function noiseCategory(reason) {
+  if (reason === 'lockfile') return 'lockfile';
+  if (reason === 'local log file') return 'log';
+  if (reason === 'generated build output' || reason === 'test coverage output'
+    || reason === 'framework output' || reason === 'framework cache') return 'build';
+  return 'large';
+}
+
+export function scoreNoise(noise, totalBytes) {
+  const bytesByCategory = new Map();
+  for (const item of noise) {
+    const id = noiseCategory(item.reason);
+    bytesByCategory.set(id, (bytesByCategory.get(id) || 0) + item.bytes);
+  }
+  const breakdown = CATEGORY_WEIGHTS.map(({ id, label, weight }) => {
+    const bytes = bytesByCategory.get(id) || 0;
+    const share = totalBytes > 0 ? bytes / totalBytes : 0;
+    const lost = Math.min(weight, weight * share);
+    return { id, label, weight, bytes, share: Math.round(share * 1000) / 10, lost: Math.round(lost * 10) / 10 };
+  });
+  const lost = Math.round(breakdown.reduce((sum, item) => sum + item.lost, 0) * 10) / 10;
+  return { score: Math.max(0, Math.min(100, Math.round(100 - lost))), lost, breakdown };
+}
+
+export function statusFor(score) {
+  if (score >= 85) return 'Looks clean for an AI coding agent';
+  if (score >= 60) return 'Some context noise found';
+  return 'Too much noise for an AI coding agent';
+}
+
+/**
+ * Classify one path without touching the filesystem. The relative path is
+ * normalised to forward slashes first, so a Windows path and a POSIX path
+ * classify the same way.
+ */
+export function classifyPath(relativePath, size = 0) {
+  const normalized = String(relativePath).split(path.sep).join('/').split('\\').join('/');
+  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}/` };
+    }
+  }
+  if (LOCKFILES.has(basename)) {
+    return { noise: { label: normalized, reason: 'lockfile' }, suggestion: basename };
+  }
+  if (basename.endsWith('.log')) {
+    return { noise: { label: normalized, reason: 'local log file' }, suggestion: '*.log' };
+  }
+  if (size > LARGE_FILE_THRESHOLD_BYTES) {
+    return { noise: { label: normalized, reason: 'large file' }, suggestion: null };
+  }
+  if (isTemplateFile(basename)) {
+    return { review: { label: normalized, reason: 'environment template (usually safe to share)' }, suggestion: null };
+  }
+  if (isSecretLikeFile(basename)) {
+    return {
+      review: { label: normalized, reason: 'environment-like file' },
+      suggestion: basename.startsWith('.env') ? '.env*' : basename,
+    };
+  }
+  if (/deploy/i.test(normalized)) {
+    return { review: { label: normalized, reason: 'deployment script' }, suggestion: null };
+  }
+  return { suggestion: null };
+}
+
+function walk(root, dir, out, state) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  // Sort entries so two runs over the same tree report in the same order on
+  // every platform; directory listing order is not guaranteed.
+  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);
+    // 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;
+      walk(root, full, out, state);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (state.files >= state.maxFiles) {
+      state.truncated = true;
+      continue;
+    }
+    let size = 0;
+    try {
+      size = fs.statSync(full).size;
+    } catch {
+      continue;
+    }
+    state.files += 1;
+    state.bytes += size;
+    out.push({ relativePath: rel, size });
+  }
+}
+
+/**
+ * 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.
+ */
+export function scanDirectory(root, options = {}) {
+  const absolute = path.resolve(root);
+  let stat;
+  try {
+    stat = fs.statSync(absolute);
+  } catch {
+    throw new Error(`directory not found: ${root}`);
+  }
+  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 files = [];
+  walk(absolute, absolute, files, state);
+
+  const noise = [];
+  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('/') });
+      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);
+    }
+  }
+
+  const scored = scoreNoise(noise, state.bytes);
+  return {
+    root: absolute,
+    files: state.files,
+    bytes: state.bytes,
+    truncated: state.truncated,
+    noise,
+    review,
+    suggestions: [...suggestions].sort(),
+    score: scored.score,
+    lost: scored.lost,
+    breakdown: scored.breakdown,
+    status: statusFor(scored.score),
+  };
+}