connections-arkitect 0.3.4

package/src/checks/code/veteran-would-mock.mjs

@@ -0,0 +1,699 @@
+// CORE check — "Things a 30-year veteran coder would make fun of."
+//
+// A taxonomy of the small, unambiguous embarrassments that survive review because each one is
+// individually harmless: debug droppings, 2010-era fossils, copy-paste artifacts, silent error
+// swallows, redundant boolean gymnastics. None of them break the build; all of them tell a
+// visiting greybeard exactly how much the codebase is skimmed rather than read.
+//
+// Two tiers, matching the runner's gating model:
+//   - error   → definitive, zero-tolerance (the check FAILS): each of these was at ZERO when the
+//               rule landed, so any hit is a fresh regression, never archaeology.
+//   - warning/info → the thermometer tier: real smells worth harvesting worst-first, but a living
+//               codebase carries some; they never fail the check.
+//
+// Detection is a light JS lexer, not naive line-grep, because the classic false positives are
+// exactly the interesting ones:
+//   - `var` inside a template literal is usually a DELIBERATE embedded ES5 snippet (tracking
+//     pixels, CloudFront Functions, iframe embed codes) — template-literal content is blanked.
+//   - patterns quoted inside strings, comments, or regex literals are not code — blanked.
+//   - minified vendored bundles (isomorphic-git etc.) are not YOUR code — skipped, counted.
+//   - an empty `catch` / `.catch(() => {})` that carries a comment — inside the braces, on the
+//     same line, or attached directly above the statement — is a documented decision; only the
+//     wordless swallow is flagged.
+//
+// Considered and deliberately NOT rules (so nobody re-proposes them):
+//   - TODO/FIXME/HACK — owned by the `stale-todos` check.
+//   - `await new Promise(r => setTimeout(r, n))` — legitimate backoff/polling is mechanically
+//     indistinguishable from sleep-based race-dodging; a rule would be mostly false positives.
+//   - `setTimeout(fn, 0)` — sometimes the correct macrotask deferral in UI code.
+//   - `x == null` — the one idiomatic loose equality (null-or-undefined).
+//   - complexity / file size / duplication — owned by the codeRisk group.
+//
+//   bun packages/connections-arkitect/bin/arkitect.mjs --root . --check veteran-would-mock
+import { readFileSync } from "node:fs";
+import { relative, extname, basename, dirname } from "node:path";
+import { createFinding } from "../../core/finding.mjs";
+import { walkFiles } from "../../core/fs-walk.mjs";
+
+// ── Lexer: blank everything that is not code ─────────────────────────────────
+// Produces two same-length views of the source (offsets preserved, newlines kept):
+//   code    — code only; strings, template literals, comments, regex bodies → spaces
+//   comment — comment CONTENT only (line + block); everything else → spaces
+// For .vue files only <script> block contents are lexed; the rest stays blank.
+
+const REGEX_KEYWORDS = new Set([
+  "return",
+  "typeof",
+  "case",
+  "in",
+  "of",
+  "instanceof",
+  "new",
+  "delete",
+  "void",
+  "do",
+  "else",
+  "yield",
+  "await",
+  "throw",
+]);
+
+function regexCanStart(prevSig, lastWord) {
+  if (REGEX_KEYWORDS.has(lastWord)) return true;
+  // After an identifier, number, `)` or `]` a slash is division, not a regex.
+  return !/[A-Za-z0-9_$)\]]/.test(prevSig);
+}
+
+function scriptRanges(raw) {
+  const ranges = [];
+  const open = /<script\b[^>]*>/gi;
+  let m;
+  while ((m = open.exec(raw))) {
+    const start = m.index + m[0].length;
+    const close = raw.indexOf("</script", start);
+    const end = close === -1 ? raw.length : close;
+    ranges.push([start, end]);
+    open.lastIndex = end;
+  }
+  return ranges;
+}
+
+export function buildViews(raw, isVue = false) {
+  const n = raw.length;
+  const code = new Array(n);
+  const comment = new Array(n);
+  for (let i = 0; i < n; i++) {
+    const keep = raw[i] === "\n" ? "\n" : " ";
+    code[i] = keep;
+    comment[i] = keep;
+  }
+  const ranges = isVue ? scriptRanges(raw) : [[0, n]];
+  for (const [start, end] of ranges) lexInto(raw, start, end, code, comment);
+  return { code: code.join(""), comment: comment.join("") };
+}
+
+function lexInto(raw, start, end, code, comment) {
+  let mode = "code";
+  const frames = [{ interp: false, depth: 0 }]; // brace-tracking frames; `${` pushes an interp frame
+  const templateReturns = []; // mode to return to when a template literal closes
+  let prevSig = "";
+  let lastWord = "";
+  for (let i = start; i < end; i++) {
+    const ch = raw[i];
+    const next = i + 1 < end ? raw[i + 1] : "";
+    if (mode === "code") {
+      if (ch === "/" && next === "/") {
+        mode = "line";
+        i++;
+        continue;
+      }
+      if (ch === "/" && next === "*") {
+        mode = "block";
+        i++;
+        continue;
+      }
+      if (ch === "'") {
+        mode = "sq";
+        continue;
+      }
+      if (ch === '"') {
+        mode = "dq";
+        continue;
+      }
+      if (ch === "`") {
+        templateReturns.push("code");
+        mode = "tpl";
+        continue;
+      }
+      if (ch === "/" && regexCanStart(prevSig, lastWord)) {
+        mode = "regex";
+        continue;
+      }
+      if (ch === "{") {
+        frames[frames.length - 1].depth++;
+      } else if (ch === "}") {
+        const top = frames[frames.length - 1];
+        if (top.interp && top.depth === 0) {
+          frames.pop();
+          mode = "tpl";
+          continue;
+        }
+        if (top.depth > 0) top.depth--;
+      }
+      code[i] = ch;
+      if (!/\s/.test(ch)) {
+        prevSig = ch;
+        lastWord = /[A-Za-z0-9_$]/.test(ch) ? lastWord + ch : "";
+      }
+      continue;
+    }
+    if (mode === "line") {
+      if (ch === "\n") mode = "code";
+      else comment[i] = ch;
+      continue;
+    }
+    if (mode === "block") {
+      if (ch === "*" && next === "/") {
+        mode = "code";
+        i++;
+        continue;
+      }
+      if (ch !== "\n") comment[i] = ch;
+      continue;
+    }
+    if (mode === "sq" || mode === "dq") {
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if ((mode === "sq" && ch === "'") || (mode === "dq" && ch === '"') || ch === "\n") mode = "code";
+      continue;
+    }
+    if (mode === "tpl") {
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if (ch === "`") {
+        mode = templateReturns.pop() || "code";
+        continue;
+      }
+      if (ch === "$" && next === "{") {
+        frames.push({ interp: true, depth: 0 });
+        mode = "code";
+        i++;
+        continue;
+      }
+      continue;
+    }
+    if (mode === "regex") {
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if (ch === "[") {
+        mode = "regexClass";
+        continue;
+      }
+      if (ch === "/" || ch === "\n") mode = "code";
+      continue;
+    }
+    if (mode === "regexClass") {
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if (ch === "]") mode = "regex";
+      continue;
+    }
+  }
+}
+
+// ── Rules ────────────────────────────────────────────────────────────────────
+// view: which lens the pattern runs against. `guardComment`: a brace-span match is skipped when the
+// raw span carries a comment (a documented swallow is a decision, not a smell).
+
+const CODE_RULES = [
+  {
+    id: "debugger-statement",
+    severity: "error",
+    re: /(?<![.\w$])debugger\b/g,
+    what: "a `debugger` statement is committed",
+    fix: "Delete it.",
+  },
+  {
+    id: "var-declaration",
+    severity: "error",
+    extKey: "varDeclarationExtensions",
+    re: /(?<![.\w$])var\s+[A-Za-z_$]/g,
+    what: "`var` in TypeScript/Vue source — hoisting roulette, retired by `let`/`const` in 2015",
+    fix: "Use `const` (or `let` when reassigned). Embedded ES5 snippets belong in template literals, which this rule already ignores.",
+  },
+  {
+    id: "eval-call",
+    severity: "error",
+    re: /(?<![.\w$])eval\s*\(/g,
+    what: "`eval()` — the veteran does not even make fun of this one, he just leaves",
+    fix: "There is always another way. Find it.",
+  },
+  {
+    id: "document-write",
+    severity: "error",
+    re: /(?<![.\w$])document\.write(?:ln)?\s*\(/g,
+    what: "`document.write` on the live document — a 1998 idiom that nukes the page",
+    fix: "Render through the framework (a child window's print document, e.g. `printWindow.document.write`, is fine and not matched).",
+  },
+  {
+    id: "xml-http-request",
+    severity: "error",
+    re: /\bnew\s+XMLHttpRequest\b/g,
+    what: "hand-rolled XMLHttpRequest in the fetch era",
+    fix: "Use fetch (or the shared HTTP client).",
+  },
+  {
+    id: "nan-comparison",
+    severity: "error",
+    re: /[=!]==?\s*NaN\b|\bNaN\s*[=!]==?/g,
+    what: "comparing against NaN — always false, the bug every veteran was bitten by exactly once",
+    fix: "Use Number.isNaN(value).",
+  },
+  {
+    id: "self-alias-fossil",
+    severity: "error",
+    re: /\b(?:const|let|var)\s+(?:self|that|_this)\s*=\s*this\b/g,
+    what: "`self = this` — the pre-arrow-function fossil",
+    fix: "Use an arrow function; lexical `this` has existed since 2015.",
+  },
+  {
+    id: "empty-else-block",
+    severity: "error",
+    re: /\belse\s*\{\s*\}/g,
+    guardComment: true,
+    what: "an empty `else {}` — code that says something and then says nothing",
+    fix: "Delete the else branch.",
+  },
+  {
+    id: "redundant-boolean-ternary",
+    severity: "error",
+    re: /\?\s*true\s*:\s*false\b|\?\s*false\s*:\s*true\b/g,
+    what: "`cond ? true : false` — a boolean laundered through a ternary",
+    fix: "Use the condition itself (negate it for the inverted form).",
+  },
+  {
+    id: "date-gettime",
+    severity: "error",
+    re: /new\s+Date\s*\(\s*\)\s*\.\s*getTime\s*\(\s*\)/g,
+    what: "`new Date().getTime()` — allocating an object to ask the clock",
+    fix: "Date.now().",
+  },
+  {
+    id: "deprecated-substr",
+    severity: "error",
+    re: /\.substr\s*\(/g,
+    what: "`.substr()` — deprecated for so long its MDN page is mostly an apology",
+    fix: "Use .slice() (mind the second argument: substr takes a LENGTH, slice takes an END index).",
+  },
+  {
+    id: "foreach-async",
+    severity: "error",
+    re: /\.forEach\s*\(\s*async\b/g,
+    what: "`.forEach(async …)` — fire-and-forget promises nobody awaits; errors vanish",
+    fix: "Use `for … of` with await, or Promise.all(items.map(async …)).",
+  },
+  {
+    id: "console-log-frontend",
+    severity: "error",
+    markerKey: "frontendPathMarkers",
+    re: /\bconsole\s*\.\s*log\s*\(/g,
+    what: "console.log debug droppings in shipped frontend code",
+    fix: "Delete it. (console.error/warn for real error surfacing and console.debug — the devtools-filtered verbose channel — are deliberate APIs and not matched; server-side CloudWatch logging is out of scope.)",
+  },
+  {
+    id: "native-dialog",
+    severity: "error",
+    markerKey: "frontendPathMarkers",
+    re: /\bwindow\s*\.\s*(?:alert|confirm|prompt)\s*\(|(?<![.\w$])alert\s*\(/g,
+    what: "window.alert/confirm/prompt in a polished SPA — the browser's 1995 chrome over your design system",
+    fix: "Use the shared dialog/confirm component. (The one sanctioned wrapper that FALLS BACK to window.confirm is declared in config `sanctionedHomes`.)",
+  },
+  {
+    id: "empty-catch-swallow",
+    severity: "warning",
+    re: /\bcatch\s*(?:\(\s*[\w$]*\s*\))?\s*\{\s*\}/g,
+    guardComment: true,
+    what: "an empty catch with no comment — the error goes to die in silence and nobody agreed to it",
+    fix: "Handle it, rethrow it, or leave a comment stating WHY swallowing is correct here (a commented empty catch is not flagged).",
+  },
+  {
+    id: "swallowed-promise-catch",
+    severity: "warning",
+    re: /\.catch\s*\(\s*\(\s*\)\s*=>\s*\{\s*\}\s*\)|\.catch\s*\(\s*function\s*\(\s*\)\s*\{\s*\}\s*\)/g,
+    guardComment: true,
+    what: "`.catch(() => {})` — a rejection muzzled with no explanation",
+    fix: "Handle it, or leave a comment in the handler stating why dropping it is correct (a commented handler is not flagged).",
+  },
+  {
+    id: "json-deep-clone",
+    severity: "warning",
+    re: /JSON\s*\.\s*parse\s*\(\s*JSON\s*\.\s*stringify\s*\(/g,
+    guardComment: true,
+    what: "JSON.parse(JSON.stringify(…)) deep clone — drops undefined/functions/Dates and walks the object twice",
+    fix: "structuredClone(value) — unless the JSON round-trip's lossiness is the point (stripping reactivity/functions); then say so in a comment and keep it (a commented clone is not flagged).",
+  },
+  {
+    id: "math-random-token",
+    severity: "warning",
+    re: /Math\s*\.\s*random\s*\(\s*\)\s*\.\s*toString\s*\(\s*36\b/g,
+    what: "Math.random().toString(36) hand-rolled IDs — collision-prone and non-cryptographic",
+    fix: "crypto.randomUUID(), or the shared random helper if the workspace has one.",
+  },
+  {
+    id: "loose-boolean-equality",
+    severity: "warning",
+    re: /(?<![=!<>])[=!]=(?!=)\s*(?:true|false)\b/g,
+    what: "loose `== true` / `!= false` — coercion gymnastics around a value that is already a boolean",
+    fix: "Use the value directly, or strict equality when it is genuinely nullable.",
+  },
+  {
+    id: "double-cast",
+    severity: "info",
+    extKey: "doubleCastExtensions",
+    re: /\bas\s+unknown\s+as\b/g,
+    what: "`as unknown as` double-cast — the type system asked a question and was told to shut up",
+    fix: "Prefer a real type guard or a narrower seam type; keep only genuinely unavoidable boundary casts.",
+  },
+];
+
+const RAW_RULES = [
+  {
+    id: "merge-conflict-marker",
+    severity: "error",
+    re: /^(?:<{7} |>{7} )/gm,
+    what: "a committed merge-conflict marker — the codebase equivalent of walking out with toilet paper on your shoe",
+    fix: "Resolve the conflict.",
+  },
+  {
+    id: "lorem-ipsum-placeholder",
+    severity: "error",
+    re: /lorem\s+ipsum/gi,
+    what: "lorem-ipsum placeholder copy in committed source",
+    fix: "Write the real copy (i18n-keyed where the surface is localized).",
+  },
+];
+
+// Filename smells — checked against EVERY walked file (dotfiles included), content never read.
+const ARTIFACT_TESTS = [
+  { re: /\.(?:bak|orig|rej|swp|swo)$/i, label: "editor/merge backup extension" },
+  { re: /^(?:\.DS_Store|Thumbs\.db|desktop\.ini)$/i, label: "OS metadata litter" },
+  { re: / copy(?: ?\d+)?\.[^.]+$/i, label: "finder/explorer duplicate" },
+  { re: / \(\d+\)\.[^.]+$/, label: "download-dedupe duplicate" },
+  { re: /[._-]old\.[^.]+$/i, label: "parked old version" },
+  { re: /~$/, label: "editor backup tilde" },
+];
+
+// Commented-out-code shape test. Deliberately conservative: pragmas, JSDoc `*` lines, URLs,
+// arrow-prose (route tables, flow descriptions) and bare key=value shorthand (runbook env vars,
+// parameter reference tables) never count; only runs of clearly code-shaped comment lines do.
+// Assignment/call shapes must carry the statement's own trailing `;` — prose that merely contains
+// code-ish punctuation does not (the 2026-07-05 skeptic pass: every FP was punctuation-shaped prose).
+const COMMENT_PRAGMA = /^(?:eslint|prettier|biome|oxlint|stylelint|c8 |istanbul|v8 |@ts-|ts-|@vite|vite-|webpack|#|!|\*)/i;
+const COMMENT_CODE_SHAPES = [
+  /^(?:const |let |var |if\s*\(|for\s*\(|while\s*\(|switch\s*\(|return[ ;(]|await |import |export |function |case |break;|continue;|try\b|catch\s*\(|\}\s*else\b|else\s*\{)/,
+  /^[\w$.[\]"']+\s*[-+*/|&]?=[^=>].*;\s*$/,
+  /^[\w$]+(?:\.[\w$]+)*\([^()]*\);\s*$/,
+];
+
+function isCodeShapedComment(text) {
+  const t = text.trim();
+  if (t.length < 3) return false;
+  if (COMMENT_PRAGMA.test(t)) return false;
+  if (/https?:\/\//.test(t)) return false;
+  if (/[→⇒]/.test(t)) return false;
+  if (/\b(?:TODO|FIXME|HACK|NOTE|e\.g\.|i\.e\.)\b/i.test(t)) return false;
+  return COMMENT_CODE_SHAPES.some((re) => re.test(t));
+}
+
+function lineStartsOf(text) {
+  const starts = [0];
+  for (let i = 0; i < text.length; i++) if (text[i] === "\n") starts.push(i + 1);
+  return starts;
+}
+
+function lineAt(starts, offset) {
+  let lo = 0;
+  let hi = starts.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (starts[mid] <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo + 1;
+}
+
+function looksMinified(raw, fileName) {
+  if (/\.min\.(?:js|mjs|cjs)$/i.test(fileName)) return true;
+  const lines = raw.split("\n");
+  let maxLen = 0;
+  for (const l of lines) if (l.length > maxLen) maxLen = l.length;
+  if (maxLen > 2500) return true;
+  return lines.length >= 8 && raw.length / lines.length > 240;
+}
+
+function compileList(values) {
+  return (values || []).map((v) => new RegExp(v));
+}
+
+export const audit = {
+  id: "veteran-would-mock",
+  title: "Things a 30-year veteran coder would make fun of",
+  category: "maintainability",
+  domain: "code",
+  requires: {},
+  defaultConfig: {
+    extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue"],
+    varDeclarationExtensions: [".ts", ".tsx", ".vue"],
+    doubleCastExtensions: [".ts", ".tsx", ".vue"],
+    // Rules that only make sense in browser-shipped code fire only under these path markers.
+    frontendPathMarkers: ["/web/src/"],
+    // Per-rule canonical homes (declared, not silenced): the ONE shared wrapper allowed to fall
+    // back to window.confirm, the ONE shared random helper, etc. Shape: { "<rule-id>": ["rel/path"] }.
+    sanctionedHomes: {},
+    // Path substrings excluded from CONTENT rules (e.g. an in-tree copy of this very check corpus,
+    // which quotes the smells it hunts). Filename-artifact rules still apply everywhere.
+    skipPathMarkers: [],
+    testDirSegments: ["__tests__", "__mocks__", "test", "tests", "testing", "e2e", "fixtures", "playground"],
+    testFilePatterns: ["\\.(spec|test)\\.[a-z]+$", "\\.d\\.ts$", "(test|spec)-(helpers|harness)", "-harness\\."],
+    commentedCodeMinLines: 4,
+    maxListedPerRule: 50,
+    outputPath: "tmp/audits/VETERAN_WOULD_MOCK.md",
+  },
+  async run(ctx) {
+    const { root, checkConfig: cfg } = ctx;
+    const findings = [];
+    const extSet = new Set(cfg.extensions);
+    const testFileRes = compileList(cfg.testFilePatterns);
+    const testDirSet = new Set(cfg.testDirSegments);
+    const skippedMinified = [];
+    const filesByDir = new Map(); // dir → Set of basenames, for the numbered-clone rule
+    let scanned = 0;
+
+    const isTestPath = (rel) => {
+      const segments = rel.split("/");
+      if (segments.some((s) => testDirSet.has(s))) return true;
+      return testFileRes.some((re) => re.test(rel));
+    };
+
+    // Pass 1 — filename artifacts, dotfiles included (content never read).
+    for (const abs of walkFiles(root, { includeDotfiles: true, ignore: new Set([".claude"]) })) {
+      const name = basename(abs);
+      for (const t of ARTIFACT_TESTS) {
+        if (t.re.test(name)) {
+          findings.push(
+            createFinding({
+              id: "committed-backup-artifact",
+              title: "Committed backup/copy artifact",
+              severity: "error",
+              file: relative(root, abs).replace(/\\/g, "/"),
+              message: `\`${name}\` (${t.label}) — version control IS the backup; parked copies are what the veteran screenshots for the group chat.`,
+              fix: "Delete it; git remembers.",
+            }),
+          );
+          break;
+        }
+      }
+    }
+
+    // Pass 2 — content rules.
+    for (const abs of walkFiles(root)) {
+      const ext = extname(abs);
+      if (!extSet.has(ext)) continue;
+      const rel = relative(root, abs).replace(/\\/g, "/");
+      if (cfg.skipPathMarkers.some((m) => rel.includes(m))) continue;
+      if (isTestPath(rel)) continue;
+
+      let raw;
+      try {
+        raw = readFileSync(abs, "utf8");
+      } catch {
+        continue;
+      }
+      const fileName = basename(abs);
+      if (looksMinified(raw, fileName)) {
+        skippedMinified.push(rel);
+        continue;
+      }
+      scanned++;
+
+      const dir = dirname(rel);
+      let names = filesByDir.get(dir);
+      if (!names) filesByDir.set(dir, (names = new Set()));
+      names.add(fileName);
+
+      const starts = lineStartsOf(raw);
+      const rawLines = raw.split("\n");
+      const push = (rule, offset) => {
+        const line = lineAt(starts, offset);
+        const snippet = (rawLines[line - 1] || "").trim().slice(0, 100);
+        findings.push(
+          createFinding({
+            id: rule.id,
+            title: rule.what,
+            severity: rule.severity,
+            file: rel,
+            line,
+            message: `${rule.what} — \`${snippet}\``,
+            fix: rule.fix,
+          }),
+        );
+      };
+
+      for (const rule of RAW_RULES) {
+        rule.re.lastIndex = 0;
+        let m;
+        while ((m = rule.re.exec(raw))) push(rule, m.index);
+      }
+
+      const views = buildViews(raw, ext === ".vue");
+      const sanctionedHomes = cfg.sanctionedHomes || {};
+      for (const rule of CODE_RULES) {
+        if (rule.extKey && !cfg[rule.extKey].includes(ext)) continue;
+        if (rule.markerKey && !cfg[rule.markerKey].some((mk) => rel.includes(mk))) continue;
+        if ((sanctionedHomes[rule.id] || []).includes(rel)) continue;
+        rule.re.lastIndex = 0;
+        let m;
+        while ((m = rule.re.exec(views.code))) {
+          // A guarded rule is skipped when a comment documents the decision: in the RAW match
+          // span, on the rest of its line, or attached directly above the statement (up to 3
+          // lines up, a blank line breaks attachment) — `catch { /* best-effort */ }`,
+          // `x.catch(() => {}); // reason`, and a comment block written above a fire-and-forget
+          // are all documented decisions, not smells (the 2026-07-05 skeptic pass found the
+          // above-the-statement form is how this codebase actually documents them).
+          if (rule.guardComment) {
+            const lineEnd = raw.indexOf("\n", m.index + m[0].length);
+            const span = raw.slice(m.index, lineEnd === -1 ? raw.length : lineEnd);
+            if (/\/\/|\/\*/.test(span)) continue;
+            const matchLine = lineAt(starts, m.index);
+            let documentedAbove = false;
+            for (let k = matchLine - 2; k >= 0 && k >= matchLine - 4; k--) {
+              const above = (rawLines[k] || "").trim();
+              if (!above) break;
+              if (/^(?:\/\/|\/\*|\*)/.test(above)) {
+                documentedAbove = true;
+                break;
+              }
+            }
+            if (documentedAbove) continue;
+          }
+          push(rule, m.index);
+        }
+      }
+
+      // Commented-out code: runs of ≥ N consecutive code-shaped comment lines.
+      const commentLines = views.comment.split("\n");
+      let runStart = -1;
+      let runLen = 0;
+      const flushRun = (endIdx) => {
+        // An explicitly labelled example/usage block directly above the run is documentation
+        // (integration scaffolds, runbooks), not dead code — the label states the intent.
+        const labelledExample = [1, 2, 3].some((k) => {
+          const above = commentLines[runStart - k];
+          return typeof above === "string" && /\b(?:example|usage)\b/i.test(above);
+        });
+        if (runLen >= cfg.commentedCodeMinLines && !labelledExample) {
+          const line = runStart + 1;
+          findings.push(
+            createFinding({
+              id: "commented-out-code",
+              title: "Commented-out code block",
+              severity: "warning",
+              file: rel,
+              line,
+              message: `${runLen} consecutive lines of commented-out code starting at line ${line} — dead code with a paint job; git already remembers it.`,
+              fix: "Delete the block (restore it from history if it is ever needed).",
+            }),
+          );
+        }
+        runStart = -1;
+        runLen = 0;
+        void endIdx;
+      };
+      for (let i = 0; i < commentLines.length; i++) {
+        if (isCodeShapedComment(commentLines[i])) {
+          if (runStart === -1) runStart = i;
+          runLen++;
+        } else if (runStart !== -1) {
+          flushRun(i);
+        }
+      }
+      if (runStart !== -1) flushRun(commentLines.length);
+    }
+
+    // Pass 3 — numbered file clones (utils2.ts beside utils.ts).
+    for (const [dir, names] of filesByDir) {
+      for (const name of names) {
+        const m = /^(.*[a-z])(\d+)(\.[a-z]+)$/i.exec(name);
+        if (!m) continue;
+        const [, stem, , ext] = m;
+        if (stem.length < 4) continue;
+        if (/(?:oauth|http|https|utf|sha|md|base|es|v)$/i.test(stem)) continue;
+        if (!names.has(`${stem}${ext}`)) continue;
+        findings.push(
+          createFinding({
+            id: "numbered-file-clone",
+            title: "Numbered file clone",
+            severity: "warning",
+            file: `${dir === "." ? "" : `${dir}/`}${name}`.replace(/\\/g, "/"),
+            message: `\`${name}\` sits beside \`${stem}${ext}\` — versioning by filename suffix; the number says "we gave up on naming".`,
+            fix: "Merge them or give the second file a name that states its actual difference.",
+          }),
+        );
+      }
+    }
+
+    const errors = findings.filter((f) => f.severity === "error").length;
+    const warnings = findings.filter((f) => f.severity === "warning").length;
+    const infos = findings.length - errors - warnings;
+    return {
+      failed: errors > 0,
+      findings,
+      outputPath: cfg.outputPath,
+      jsonPayload: { scanned, skippedMinified, errors, warnings, infos },
+      report: renderReport({ findings, scanned, skippedMinified, maxListed: cfg.maxListedPerRule }),
+    };
+  },
+};
+
+function renderReport({ findings, scanned, skippedMinified, maxListed }) {
+  const lines = [
+    "# Things a 30-year veteran coder would make fun of",
+    "",
+    "_Small, unambiguous embarrassments: debug droppings, 2010 fossils, copy-paste artifacts, silent swallows._",
+    "_Errors gate (each rule was at zero when it landed — a hit is a fresh regression). Warnings/info are the_",
+    "_thermometer tier: harvest worst-first, never expect zero._",
+    "",
+    `- Files scanned: ${scanned}`,
+    `- Minified/vendored bundles skipped (not your code): ${skippedMinified.length}${skippedMinified.length ? ` — ${skippedMinified.join(", ")}` : ""}`,
+    `- Findings: ${findings.length}`,
+    "",
+  ];
+  if (!findings.length) {
+    lines.push("## Clean — the veteran walks through and finds nothing to screenshot.");
+    return `${lines.join("\n")}\n`;
+  }
+  const byRule = new Map();
+  for (const f of findings) {
+    const list = byRule.get(f.id) || [];
+    list.push(f);
+    byRule.set(f.id, list);
+  }
+  const sevRank = { error: 0, warning: 1, info: 2 };
+  const groups = [...byRule.entries()].sort((a, b) => sevRank[a[1][0].severity] - sevRank[b[1][0].severity] || b[1].length - a[1].length);
+  for (const [ruleId, items] of groups) {
+    lines.push(`## ${ruleId} — ${items.length} (${items[0].severity})`, "");
+    if (items[0].fix) lines.push(`_Fix: ${items[0].fix}_`, "");
+    for (const f of items.slice(0, maxListed)) lines.push(`- \`${f.file}${f.line ? `:${f.line}` : ""}\` — ${f.message}`);
+    if (items.length > maxListed) lines.push(`- …and ${items.length - maxListed} more (full list in findings JSON — no silent cap)`);
+    lines.push("");
+  }
+  return `${lines.join("\n")}\n`;
+}