@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/better-review/scripts/scan-diff.mjs

@@ -0,0 +1,365 @@
+// Cheap scan of a unified diff. It emits TWO channels, and the distinction is
+// load-bearing:
+//   • LEADS (heuristic) — "look here and verify"; the reviewer reads the code and
+//     builds the counterexample before any becomes a finding (see references/passes.md).
+//   • FINDINGS (decidable) — near-zero-false-positive checks that ARE blockers on
+//     their own. Currently: `over-mock-internal-seam` (a vi/jest.mock of a
+//     first-party seam = Over-mocked, zero-tolerance). This makes better-review the
+//     standalone first line of enforcement — no dependency on ensure-coverage's
+//     gate being wired in the repo.
+//
+//   git diff <merge-base>...HEAD | node scan-diff.mjs        # leads + findings from stdin
+//   node scan-diff.mjs --diff changes.patch
+//
+// Best-effort and JS/TS-oriented (regex/branch heuristics are language-bound; the
+// mock/interception checks are framework-specific). On other languages it simply
+// finds fewer — it is additive, and absence means "the scanner found nothing,"
+// not "the code is fine."
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// ---- pure core ----
+
+// Parse a unified diff into added lines with their NEW-file line numbers.
+export function parseAddedLines(diffText) {
+  const out = []
+  let file = null
+  let newLine = 0
+  for (const raw of (diffText || '').split(/\r?\n/)) {
+    if (raw.startsWith('+++ ')) {
+      const m = raw.match(/^\+\+\+ b\/(.+)$/)
+      file = m ? m[1] : raw.slice(4).replace(/^b\//, '')
+      continue
+    }
+    if (raw.startsWith('diff --git')) { file = null; continue }
+    const hm = raw.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/)
+    if (hm) { newLine = parseInt(hm[1], 10); continue }
+    if (raw.startsWith('+')) { out.push({ file, line: newLine, text: raw.slice(1) }); newLine++; continue }
+    if (raw.startsWith('-')) continue // removed line: no advance in new file
+    if (raw.startsWith('\\')) continue // ""
+    newLine++ // context line
+  }
+  return out
+}
+
+const TEST_FILE = /\.(test|spec)\.[jt]sx?$/
+const INTERCEPT = /\broute\.fulfill\b|\bpage\.route\s*\(|\bsetupServer\s*\(|\bsetupWorker\s*\(|from\s+['"]msw['"]/
+
+export function interceptionLeads(added) {
+  return added
+    .filter((a) => a.file && TEST_FILE.test(a.file) && INTERCEPT.test(a.text))
+    .map((a) => ({ type: 'first-party-interception', file: a.file, line: a.line, snippet: a.text.trim(),
+      note: 'first-party interception in a test — over-mock risk; verify the real path is actually proven (browser/journey, not stub). Skip if: the route is a third-party/external boundary, or this is a Tier-2 functional failure-injection test (interception is correct there).' }))
+}
+
+// Regex literals / RegExp() added without ^ or $ anchors → boundary-leak risk.
+export function regexLeads(added) {
+  const out = []
+  for (const a of added) {
+    for (const lit of a.text.match(/\/(?:[^/\n\\]|\\.){2,}\/[gimsuy]*/g) || []) {
+      const body = lit.replace(/\/[gimsuy]*$/, '').slice(1)
+      if (!/[\^$]/.test(body) && /[A-Za-z0-9]/.test(body)) {
+        out.push({ type: 'unanchored-pattern', file: a.file, line: a.line, snippet: lit,
+          note: 'regex without ^/$ anchors — verify prefix/substring leakage at boundaries (does /foo also match /foobar?). Skip if: inputs are a closed/validated set where leakage cannot occur, or a substring match is intended — produce the breaking input or drop it.' })
+      }
+    }
+    const re = a.text.match(/new RegExp\(([^)]*)\)/)
+    if (re && !/[\^$]/.test(re[1])) {
+      out.push({ type: 'unanchored-pattern', file: a.file, line: a.line, snippet: re[0].trim(),
+        note: 'RegExp without ^/$ — verify boundary behavior.' })
+    }
+  }
+  return out
+}
+
+// Weakened assertions in tests → a test that can't fail the way its name promises.
+// Two tells from real "smoke wearing a journey label" specs:
+//   - `.catch(() => false)` (or null/undefined/0/'') swallows a locator/await throw
+//     into a falsy, defeating Playwright's web-first retry and any assertion on it.
+//   - `expect(a || b || c).toBeTruthy()` / `.toBe(true)` — a disjunctive truthiness
+//     assertion passes if ANY branch holds, so it pins down no specific behavior.
+// Reviewer then checks the test's @level: a journey/functional test asserting only
+// these is Wrong Level (references/passes.md → Spec).
+const CATCH_SWALLOW = /\.catch\s*\(\s*\(\s*\)\s*=>\s*(?:false|null|undefined|0|''|""|``)\s*\)/
+const DISJUNCTIVE_TRUTHY = /\bexpect\s*\([^;]*\|\|[^;]*\)\s*\.\s*(?:toBeTruthy\b|toBe\s*\(\s*true\s*\))/
+export function weakAssertionLeads(added) {
+  const out = []
+  for (const a of added) {
+    if (!a.file || !TEST_FILE.test(a.file)) continue
+    if (CATCH_SWALLOW.test(a.text)) out.push({ type: 'swallowed-assertion', file: a.file, line: a.line, snippet: a.text.trim(),
+      note: 'catch swallows a locator/await throw into a falsy — defeats web-first retry and hides real failures; assert directly (web-first expect), do not catch-to-false. Skip if: the falsy genuinely feeds a non-assertion control-flow decision and the real outcome is asserted separately.' })
+    if (DISJUNCTIVE_TRUTHY.test(a.text)) out.push({ type: 'weak-assertion', file: a.file, line: a.line, snippet: a.text.trim(),
+      note: 'disjunctive truthiness — passes if any branch holds, so it proves nothing specific; if this is a @level journey/functional test it is Wrong Level (drive the flow to a concrete outcome). Skip if: this is a @level render-health test (alias: smoke) where "renders at all" is the whole contract.' })
+  }
+  return out
+}
+
+// A test that *names itself* a race but reads state some earlier test already created
+// cannot exercise the first-writer path: both "concurrent" callers take the
+// already-exists early return, and the contended create never runs. The tell is a
+// pre-existing capture (`x!.id`, `find*OrThrow`) reached before the `Promise.all`.
+// Kept a LEAD, not a finding: post-seal/replay races legitimately look exactly like
+// this. What makes it a defect is the test being cited as first-writer proof — a
+// judgment about the AC mapping that no regex can make.
+const ANY_TEST_TITLE = /\b(?:it|test)\s*(?:\.\w+)?\s*\(\s*['"`]/
+const CONCURRENCY_TEST_TITLE = /\b(?:it|test)\s*(?:\.\w+)?\s*\(\s*['"`][^'"`]*\b(?:race|races|racing|concurrent|concurrently|simultaneous(?:ly)?|parallel)\b/i
+const PREEXISTING_CAPTURE = /\w\s*!\s*\.\s*\w|\bfind(?:First|Unique)OrThrow\s*\(/
+const CONCURRENT_CALL = /\bPromise\s*\.\s*(?:all|allSettled|race)\s*\(/
+
+export function concurrencyFixtureLeads(added) {
+  const out = []
+  const byFile = new Map()
+  for (const a of added) {
+    if (!a.file || !TEST_FILE_ANY.test(a.file)) continue
+    if (!byFile.has(a.file)) byFile.set(a.file, [])
+    byFile.get(a.file).push(a)
+  }
+  for (const [, lines] of byFile) {
+    lines.sort((x, y) => x.line - y.line)
+    let title = null // the concurrency-named test we are inside
+    let capture = null // first pre-existing capture seen since that title
+    for (const a of lines) {
+      // Any test title closes the previous body. Tracking only concurrency titles
+      // would leave scope open across the rest of the file, so the next ordinary
+      // test's fixture would be attributed to a race test that already ended.
+      if (ANY_TEST_TITLE.test(a.text)) {
+        title = CONCURRENCY_TEST_TITLE.test(a.text) ? a : null
+        capture = null
+        continue
+      }
+      if (!title) continue
+      if (!capture && PREEXISTING_CAPTURE.test(a.text)) { capture = a; continue }
+      if (capture && CONCURRENT_CALL.test(a.text)) {
+        out.push({ type: 'concurrency-test-preexisting-fixture', file: capture.file, line: capture.line, snippet: capture.text.trim(),
+          note: `test named as a race/concurrent case reads pre-existing state before ${a.text.trim().slice(0, 40)}… — if that state is what the concurrent calls are supposed to be creating, every caller takes the already-exists path and the contended first-write is never exercised (a green test for an untested race). Verify the fixture starts from ABSENT, with independent clients/connections and a barrier. Skip if: this is deliberately a post-create replay/idempotency case AND a separate test covers the first-write race — then check that the AC cites that one, not this.` })
+        title = null; capture = null
+      }
+    }
+  }
+  return out
+}
+
+// New conditional branches → each needs a test (line coverage ≠ branch coverage).
+export function branchLeads(added) {
+  return added
+    .filter((a) => /\b(if|else if|case)\b/.test(a.text) || /\?[^?]*:/.test(a.text))
+    .map((a) => ({ type: 'new-branch', file: a.file, line: a.line, snippet: a.text.trim(),
+      note: 'new branch — name a test that exercises it; line coverage is not branch coverage. Skip if: an integration/E2E test already drives it, or the branch is a trivial guard whose failure is inert.' }))
+}
+
+// Files whose EXISTING behavior is modified (edited/removed lines in a non-test
+// SOURCE file) owe a characterization test pinning prior behavior before the
+// change (ensure-coverage → depth/characterization.md). A new file or a test
+// file is excluded; only changed/removed content in a non-test source file
+// signals an existing-behavior modification. The *detection* is decidable; the
+// adjudication ("is there an adequate @characterizes test, or a declared intended
+// change?") is the reviewer's — hence a lead, not a finding.
+const TEST_FILE_ANY = /\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(e2e|tests?|__tests__)\/|(^|\/)test_[^/]*\.py$|_test\.py$/
+const NON_SOURCE = /\.(md|markdown|json|ya?ml|txt|lock|svg|png|jpe?g|gif|webp|ico|csv|tsv|toml|ini|cfg|snap)$/i
+
+// Parse a diff into per-file change shape: { isNew, removed, added, firstLine }.
+// `removed` counts changed/deleted content lines (the modify signal); a new file
+// (--- /dev/null or `new file mode`) is flagged so it's treated as addition.
+export function parseFileChanges(diffText) {
+  const files = new Map()
+  let file = null
+  let pendingNew = false
+  let newLine = 0
+  for (const raw of (diffText || '').split(/\r?\n/)) {
+    if (raw.startsWith('diff --git')) { file = null; pendingNew = false; continue }
+    if (raw.startsWith('new file mode')) { pendingNew = true; continue }
+    if (raw.startsWith('--- ')) { if (/\/dev\/null/.test(raw)) pendingNew = true; continue }
+    if (raw.startsWith('+++ ')) {
+      const m = raw.match(/^\+\+\+ (?:b\/)?(.+)$/)
+      file = m && m[1] !== '/dev/null' ? m[1] : null
+      if (file && !files.has(file)) files.set(file, { isNew: pendingNew, removed: 0, added: 0, firstLine: 0 })
+      pendingNew = false
+      continue
+    }
+    if (!file) continue
+    const hm = raw.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/)
+    if (hm) { newLine = parseInt(hm[1], 10); continue }
+    const rec = files.get(file)
+    if (!rec) continue
+    if (raw.startsWith('-')) { rec.removed++; if (!rec.firstLine) rec.firstLine = newLine; continue } // no new-line advance
+    if (raw.startsWith('+')) { rec.added++; if (!rec.firstLine) rec.firstLine = newLine; newLine++; continue }
+    if (raw.startsWith('\\')) continue
+    newLine++ // context
+  }
+  return files
+}
+
+export function characterizationLeads(diffText) {
+  const out = []
+  for (const [file, rec] of parseFileChanges(diffText)) {
+    if (rec.isNew) continue                    // new file = new behavior, not a modification
+    if (TEST_FILE_ANY.test(file)) continue     // editing tests is not modifying production behavior
+    if (NON_SOURCE.test(file)) continue        // docs/config/snapshots carry no behavior to pin
+    if (rec.removed === 0) continue            // pure addition into an existing file = added behavior
+    out.push({ type: 'modifies-existing-behavior', file, line: rec.firstLine || 1,
+      snippet: `${rec.removed} existing line(s) changed/removed`,
+      note: 'existing behavior modified — verify a characterization test pins the PRIOR behavior (authored to pass on the pre-change tree) so this diff is proven not to shift observable behavior unintentionally; tag it `// @characterizes <surface>`. Skip if: an existing behavior test already covers this exact path and still passes unchanged (cite it), this is a declared intended behavior change with its AC and the assertion delta is in the diff, or the edit is trivial/generated/non-behavioral. See ensure-coverage depth/characterization.md.' })
+  }
+  return out
+}
+
+// ---- VENDORED over-mock classifier — DECIDABLE FINDING, not a lead ----
+//
+// Self-contained copy of ensure-coverage's `mock-internal-seam` classifier
+// (skills/engineering/ensure-coverage/scripts/mock-policy-config.mjs), vendored
+// here so better-review enforces no-over-mock with ZERO dependency on ensure-coverage
+// being installed/wired. ensure-coverage stays CANONICAL: if the two diverge,
+// ensure-coverage wins and this copy is stale → resync. Kept tiny on purpose.
+//
+// The "externals-allowlist inversion": you can't enumerate internal seams, but
+// the legitimately-fakeable set (third-party/stdlib) is small and known — so a
+// mock whose target resolves to first-party code is a seam (a defect), and the
+// declared externals / stdlib / bare packages are exempt. Unlike the heuristic
+// leads above this is DECIDABLE, so its hits are emitted as `findings`.
+
+export const DEFAULT_MOCK_TOPOLOGY = {
+  firstPartyAliasPrefixes: ['@/', '~/'],
+  firstPartyPackages: [],                 // e.g. a monorepo's own scope '@acme/'
+  externals: [],                          // regex SOURCES for first-party-looking-but-external targets
+  testUtilHints: ['__mocks__', '__fixtures__', 'fixtures', 'mocks', 'helpers',
+    'test-utils', 'testing', 'support', 'stubs', 'factories'],
+}
+
+// Best-effort read of coverage.config.json topology (so a monorepo's own @scope
+// is recognized); never throws — defaults to conventional @/ ~/ when absent.
+// Config declares TOPOLOGY only; it cannot disable the check (zero-tolerance).
+export function loadMockTopology(cwd = process.cwd()) {
+  for (const name of ['coverage.config.json', '.coverage.config.json']) {
+    try {
+      const mp = (JSON.parse(fs.readFileSync(path.join(cwd, name), 'utf8')).mockPolicy) || {}
+      return {
+        firstPartyAliasPrefixes: mp.firstPartyAliasPrefixes ?? DEFAULT_MOCK_TOPOLOGY.firstPartyAliasPrefixes,
+        firstPartyPackages: mp.firstPartyPackages ?? DEFAULT_MOCK_TOPOLOGY.firstPartyPackages,
+        externals: mp.externals ?? DEFAULT_MOCK_TOPOLOGY.externals,
+        testUtilHints: mp.testUtilHints ?? DEFAULT_MOCK_TOPOLOGY.testUtilHints,
+      }
+    } catch { /* missing or malformed → try next, else defaults */ }
+  }
+  return { ...DEFAULT_MOCK_TOPOLOGY }
+}
+
+// Pull the mocked specifier from a vi/jest/vitest `.mock`/`.doMock(...)` call.
+export function extractMockTarget(codeLine) {
+  const m = /\b(?:vi|jest|vitest)\s*\.\s*(?:mock|doMock)\s*\(\s*(['"`])([^'"`]+)\1/.exec(codeLine || '')
+  return m ? m[2] : null
+}
+
+// Classify a mock target as an internal seam (a defect) or an allowed external.
+// Precedence: declared externals > stdlib > relative(util vs source) >
+// first-party alias > first-party package > bare package (external default).
+export function classifyMockTarget(target, topo = DEFAULT_MOCK_TOPOLOGY) {
+  if (!target) return { internal: false, reason: 'no target' }
+  for (const src of topo.externals || []) {
+    try { if (new RegExp(src).test(target)) return { internal: false, reason: 'declared external' } } catch { /* ignore bad regex */ }
+  }
+  if (target.startsWith('node:')) return { internal: false, reason: 'node builtin' }
+  if (target.startsWith('.')) {
+    if (target.split('/').some((s) => (topo.testUtilHints || []).includes(s))) return { internal: false, reason: 'relative test util/fixture/mock' }
+    return { internal: true, reason: 'relative import into first-party source' }
+  }
+  for (const pre of topo.firstPartyAliasPrefixes || []) {
+    if (target.startsWith(pre)) return { internal: true, reason: `first-party alias "${pre}"` }
+  }
+  for (const fp of topo.firstPartyPackages || []) {
+    const base = fp.endsWith('/') ? fp.slice(0, -1) : fp
+    if (target === base || target.startsWith(`${base}/`)) return { internal: true, reason: `first-party package "${fp}"` }
+  }
+  return { internal: false, reason: 'external package' }
+}
+
+// Diff-scoped over-mock FINDINGS: a vi/jest/vitest.mock of a first-party internal
+// seam ADDED in a test file → Over-mocked (a blocker), not a lead. Diff-scoped is
+// the right scope for a PR review (review the diff; pre-existing mocks are notes by
+// diff-discipline) — the whole-tree inherited burndown is ensure-coverage's audit lint.
+export function overMockFindings(added, topo = DEFAULT_MOCK_TOPOLOGY) {
+  const out = []
+  for (const a of added) {
+    if (!a.file || !TEST_FILE_ANY.test(a.file)) continue
+    const target = extractMockTarget(a.text)
+    if (!target) continue
+    const { internal, reason } = classifyMockTarget(target, topo)
+    if (!internal) continue
+    out.push({ type: 'over-mock-internal-seam', file: a.file, line: a.line, snippet: a.text.trim(), target, reason,
+      note: 'mocks a first-party internal seam → Over-mocked (dishonest green): zero-tolerance, NO @mock-ok waiver and no "approved with justification" (ensure-coverage depth/mock-policy.md). Resolve by making the test real, faking only the external, or DELETING it (over-mock is worse than no test). Only NOT a finding if the target is genuinely external — then declare it as topology in coverage.config.json.' })
+  }
+  return out
+}
+
+export function scanDiff(diffText, topo = DEFAULT_MOCK_TOPOLOGY) {
+  const added = parseAddedLines(diffText)
+  const byPlace = (a, b) => (a.file || '').localeCompare(b.file || '') || a.line - b.line
+  const leads = [...interceptionLeads(added), ...regexLeads(added), ...weakAssertionLeads(added), ...branchLeads(added),
+    ...concurrencyFixtureLeads(added), ...characterizationLeads(diffText)].sort(byPlace)
+  const findings = overMockFindings(added, topo).sort(byPlace)
+  const tally = (xs) => xs.reduce((m, l) => ((m[l.type] = (m[l.type] || 0) + 1), m), {})
+  // `counts`/`leads` kept for back-compat; `findings` is the decidable, blocker-grade channel.
+  return { kind: 'leads+findings', counts: tally(leads), leads, findingCounts: tally(findings), findings }
+}
+
+// ---- CLI ----
+
+// Exit codes. Both are usage errors (distinct from 0 = scanned OK, and from a
+// generic crash). NO_INPUT is the fail-open this tool exists NOT to have: a
+// parity proof that returns "all clear" on zero bytes proved nothing about the
+// diff (issue #416). USAGE catches the `--base/--head` invocation producers
+// invented — flags this tool never had, which used to fall through to an empty
+// stdin read and a vacuous clean result.
+export const NO_INPUT_EXIT = 2
+export const USAGE_EXIT = 2
+
+// The ONE correct invocation, echoed in every error so a wrong call self-corrects.
+const USAGE = 'Pipe the net diff: git diff <merge-base>...HEAD | node scan-diff.mjs   (or: node scan-diff.mjs --diff <file>). This tool takes NO --base/--head.'
+
+// A usage/no-input error carrying its own process exit code. Thrown by the arg
+// parser and the empty-input guard; main() prints .message to stderr and exits.
+export class ScanDiffCliError extends Error {
+  constructor(message, code = USAGE_EXIT) { super(message); this.name = 'ScanDiffCliError'; this.code = code }
+}
+
+// Parse argv (already sliced of node + script). Returns { diffPath } — null means
+// read stdin. Anything that isn't `--diff <file>` HARD-FAILS: an unknown flag
+// (the `--base/--head` mistake) or a stray positional would otherwise be silently
+// ignored, dropping through to an empty stdin read and a false-clean proof.
+export function parseCliArgs(argv) {
+  let diffPath = null
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--diff') {
+      diffPath = argv[i + 1]
+      if (diffPath == null) throw new ScanDiffCliError(`scan-diff: --diff requires a file path. ${USAGE}`)
+      i++
+      continue
+    }
+    if (arg.startsWith('-')) throw new ScanDiffCliError(`scan-diff: unknown flag "${arg}". ${USAGE}`)
+    throw new ScanDiffCliError(`scan-diff: unexpected argument "${arg}". ${USAGE}`)
+  }
+  return { diffPath }
+}
+
+function main() {
+  let diff
+  try {
+    const { diffPath } = parseCliArgs(process.argv.slice(2))
+    diff = diffPath != null ? fs.readFileSync(diffPath, 'utf8') : fs.readFileSync(0, 'utf8') // --diff <file> or stdin
+    // Fail LOUD on no input. Empty/whitespace-only means the diff never arrived
+    // (a non-piped context, or the `--base/--head` fall-through) — NOT a clean
+    // diff. A real diff with content but zero findings still exits 0 below;
+    // "no INPUT" and "input with no findings" are different answers.
+    if (!diff.trim()) throw new ScanDiffCliError(`scan-diff: no diff on stdin (or --diff <file> is empty). ${USAGE}`, NO_INPUT_EXIT)
+  } catch (err) {
+    if (err instanceof ScanDiffCliError) { process.stderr.write(`${err.message}\n`); process.exit(err.code) }
+    throw err
+  }
+  const result = scanDiff(diff, loadMockTopology())
+  result.disclaimer = 'TWO channels. `leads` = heuristic "look here and verify" (read the code, build the counterexample first). `findings` = DECIDABLE blockers (over-mock-internal-seam): a vi/jest.mock of a first-party seam is Over-mocked, zero-tolerance, no waiver — fix it, do not merge over it. Best-effort, JS/TS-oriented; absence != code is fine.'
+  console.log(JSON.stringify(result, null, 2))
+}
+
+if (isMainModule(import.meta.url)) main()