@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/test-quality/scripts/lint-tests.mjs

@@ -0,0 +1,574 @@
+// lint-tests — static checks over test files for the test-quality principles
+// (../SKILL.md). Copied from ensure-coverage's lint-tests and extended; the two
+// copies evolve independently.
+//
+//   node lint-tests.mjs                          # whole-tree scan of discovered test files
+//   node lint-tests.mjs --diff <base>           # only findings on lines ADDED in base...HEAD
+//   node lint-tests.mjs --files a,b              # specific files
+//   --rules no-skip,text-oracle                  # run a subset (default: every rule)
+//   --json                                        # machine output
+//   --shares 4                                    # split the flagged files into 4 review shares
+//
+// (Named lint-tests, not test-lint, so node's --test runner doesn't glob it as a
+//  test file via its `test-*` pattern and execute the CLI mid-suite.)
+//
+// Two severities:
+//   gate — syntactically decidable, ~zero false positives. Any gate finding makes
+//          the exit code 1.
+//   lead — a heuristic that also matches some legitimate tests. Reported for the
+//          auditor to read and confirm against the principle's "Not a failure"
+//          cases; never changes the exit code.
+//
+// Adding a rule = append to ALL_RULES with id, principle, severity, message and
+// one of: `patterns` (line regexes), `match` (per line), `scanFile` (whole file),
+// or `crossFile: true` (resolved by the CLI over every scanned file). If a
+// legitimate test could trip it, it is a lead.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { execSync } from 'node:child_process'
+import { loadMockPolicyFromFile, extractMockTarget, classifyMockTarget } from './mock-policy-config.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// Skip / focus / expected-fail forms. `.only`/focus silently disable every OTHER
+// test; skip/xfail/fixme disable this one. All banned (SKILL.md principle 4).
+// Unconditional forms only: a declared-skipped test (`test.skip('name', …)`),
+// focus, fixme, todo, and the unconditional decorators. Conditional skips
+// (skipif, a runtime `test.skip()` / `t.Skip()`, xfail) are CONDITIONAL_SKIP_PATTERNS.
+export const SKIP_PATTERNS = [
+  { kind: 'skip', re: /\b(?:test|it|describe|suite|context)\s*\.\s*skip\s*(?:\.\s*each\b|\(\s*['"`])/ },
+  { kind: 'only', re: /\b(?:test|it|describe|suite|context)\s*\.\s*only\b/ },
+  { kind: 'fixme', re: /\b(?:test|it)\s*\.\s*fixme\b/ },
+  { kind: 'todo', re: /\b(?:test|it)\s*\.\s*todo\s*\(/ },
+  { kind: 'skip', re: /\b(?:xit|xdescribe|xtest)\s*\(/ },
+  { kind: 'only', re: /\b(?:fit|fdescribe|ftest)\s*\(/ },
+  { kind: 'skip', re: /@(?:pytest\.mark\.)?skip\b/ },
+  { kind: 'skip', re: /@unittest\.skip\b/ },
+]
+
+// A skip that depends on a condition: legitimate for a platform or an optional
+// dependency, a hidden hole when the condition always holds in CI. A lead.
+export const CONDITIONAL_SKIP_PATTERNS = [
+  { kind: 'skipif', re: /@(?:pytest\.mark\.)?skipif\b|@unittest\.skip(?:If|Unless)\b/ },
+  { kind: 'runtime-skip', re: /\bpytest\.(?:skip|importorskip)\s*\(|\bt\.Skip(?:f|Now)?\s*\(|\b(?:t|ctx)\.skip\s*\(/ },
+  { kind: 'runtime-skip', re: /\b(?:test|it|describe)\s*\.\s*skip\s*\(\s*(?!['"`])/ },
+  { kind: 'xfail', re: /@(?:pytest\.mark\.)?xfail\b/ },
+]
+
+// Fixed sleeps — a timer instead of an explicit wait. The single biggest source of
+// flake; doctrine is "never waitForTimeout()". Precise: these forms are ~never
+// legitimate in a test (an aliased `cy.wait('@x')` or polling helper is not matched).
+export const FIXED_TIMEOUT_PATTERNS = [
+  { kind: 'waitForTimeout', re: /\.waitForTimeout\s*\(/ },
+  { kind: 'cy.wait', re: /\bcy\.wait\s*\(\s*\d/ },     // numeric only; cy.wait('@alias') is fine
+  { kind: 'time.sleep', re: /\btime\.sleep\s*\(/ },
+  { kind: 'time.Sleep', re: /\btime\.Sleep\s*\(/ },
+]
+
+// Empty test body — a `test`/`it` whose callback body is `{}`. A placeholder
+// that passes vacuously and asserts nothing: the Missing-Assertion smell in its
+// one decidable, ~zero-false-positive form. The BROADER "has statements but no
+// assertion" case is NOT here — a test can assert through a helper, so a block
+// with no `expect`/`assert` token may still assert; that stays a review LEAD
+// for the auditor (SKILL.md principle 4).
+// Matches only single-line empty bodies (`() => {}` / `function () {}`), incl.
+// `.skip`/`.each(...)`/`.concurrent` chains and Playwright `async ({ page })`
+// fixtures; `describe`/`suite` are excluded (an empty suite is not a fake test).
+// A multi-line empty body is rarer and deliberately left to the lead, not
+// false-blocked.
+export const EMPTY_TEST_PATTERNS = [
+  { kind: 'empty-test', re: /^\s*(?:async\s+)?def\s+test\w*\s*\([^)]*\)\s*(?:->\s*[\w\[\], ]+)?:\s*(?:pass|\.\.\.)\s*$/ },
+  { kind: 'empty-test', re: /\b(?:it|test)\s*(?:\.\s*\w+\s*(?:\([^)]*\)\s*)?)?\(\s*[`'"][^`'"]*[`'"]\s*,\s*(?:async\s+)?(?:function\s*\*?\s*)?\([^)]*\)\s*(?:=>\s*)?\{\s*\}\s*\)?/ },
+]
+
+// Swallowed assertion — an assertion matcher whose rejection is eaten by a
+// chained `.catch(...)`, so the assertion can NEVER fail the test. The vacuous
+// form behind the #237 login regression: `expect(locator).not.toBeVisible().catch(() => {})`
+// passed whether or not the button was actually visible. Decidable and
+// ~zero-false-positive: a Playwright web-first matcher (`.toXxx(...)`) directly
+// chained to `.catch(` is never legitimate — a real assertion's rejection must
+// surface, not be discarded. (Synchronous Jest matchers don't return a promise,
+// so `.toBe(x).catch()` only appears as a deliberate swallow.) The broader
+// "assertion guarded by a try/catch that re-passes" case stays a review LEAD
+// for the auditor; only the directly-chained matcher form is gated here.
+export const SWALLOWED_ASSERTION_PATTERNS = [
+  { kind: 'swallowed-catch', re: /\.to[A-Z]\w*\s*\([^)]*\)\s*\.catch\s*\(/ },
+]
+
+export const RULES = [
+  { id: 'no-skip', principle: 4, severity: 'gate', message: 'test skipped, focused, or todo: a skipped test cannot fail (principle 4)', patterns: SKIP_PATTERNS },
+  { id: 'no-fixed-timeout', principle: 7, severity: 'gate', message: 'fixed sleep: flaky by construction; wait on the condition instead (principle 7)', patterns: FIXED_TIMEOUT_PATTERNS },
+  { id: 'no-empty-test', principle: 4, severity: 'gate', message: 'empty test body: passes vacuously (principle 4)', patterns: EMPTY_TEST_PATTERNS },
+  { id: 'no-swallowed-assertion', principle: 4, severity: 'gate', message: 'assertion failure swallowed by .catch(): the matcher can never fail (principle 4)', patterns: SWALLOWED_ASSERTION_PATTERNS },
+]
+
+export const CONDITIONAL_SKIP_RULE = {
+  id: 'conditional-skip',
+  principle: 4,
+  severity: 'lead',
+  message: 'conditional skip: fine for a platform or optional dependency; a hole if the condition always holds in CI (principle 4)',
+  patterns: CONDITIONAL_SKIP_PATTERNS,
+}
+
+// Over-mocking via the externals-allowlist inversion (mock-policy-config.mjs): a
+// mock whose target resolves to first-party code is a finding; declared
+// externals, bare packages and the stdlib are exempt. `coverage.config.json`
+// only declares topology; with no config the conventional `@/`/`~/` defaults
+// apply, so the rule is never silently inert.
+export const MOCK_INTERNAL_SEAM_RULE = {
+  id: 'mock-internal-seam',
+  principle: 3,
+  severity: 'gate',
+  defaultOn: true,
+  message: 'mocks a first-party module: fake only what you do not own (principle 3)',
+  match(raw, code, ctx) {
+    const target = extractMockTarget(code)
+    if (!target) return null
+    const { internal, reason } = classifyMockTarget(target, ctx && ctx.policy)
+    if (!internal) return null
+    return { kind: 'internal-seam', detail: target, reason }
+  },
+}
+
+// A matcher that adds nothing: Testing Library `getBy*` and vue-test-utils
+// `get()` already throw when the element is missing, so `toBeDefined()` after
+// them is redundant. The test still fails on a missing element; it proves
+// presence only. A lead, not a gate: the test is shallow, not vacuous.
+export const REDUNDANT_MATCHER_PATTERNS = [
+  { kind: 'getBy-exists', re: /\bexpect\(\s*(?:[\w$]+(?:\([^()]*\))?\.)*(?:getBy|getAllBy)\w+\(.*\)\s*\)\s*\.(?:toBeDefined|toBeTruthy|not\.toBeNull|not\.toBeUndefined)\(\s*\)/ },
+  { kind: 'get-exists', re: /\bexpect\(\s*[\w$.]+\.get(?:Component)?\(.*\)\.exists\(\)\s*\)\s*\.toBe\(\s*true\s*\)/ },
+]
+
+export const REDUNDANT_MATCHER_RULE = {
+  id: 'redundant-matcher',
+  principle: 4,
+  severity: 'lead',
+  message: 'the query already throws when missing, so this matcher adds nothing; the test proves presence only (principle 4)',
+  patterns: REDUNDANT_MATCHER_PATTERNS,
+}
+
+// Text oracle: the test reads a checked-in doc or source file and matches its
+// text. File-level because the path, the read and the match sit on different
+// lines. A lead: reading a file to execute it, comparing it to a value from
+// code, or a forbidden-capability pin are all legitimate (SKILL.md principle 1).
+// Config files belong to config-read, which fires whatever the assertion.
+const READ_CALL = /\b(?:readFileSync|readFile|read_text|ReadFile|open)\s*\(/
+const WRITE_CALL = /\b(?:writeFileSync|writeFile|write_text|WriteFile|appendFileSync|copyFileSync|cpSync|copyfile|copy2?)\s*\(/
+const TEXT_ASSERT = /\.(?:toContain|toMatch|includes)\s*\(|\bassert\.(?:match|doesNotMatch)\s*\(|\b(?:Contains|NotContains|Regexp)\s*\(\s*t\s*,|\bassert(?:In|NotIn|Regex)\s*\(|['"][^'"\n]{3,}['"]\s+(?:not\s+)?in\s+[\w.]/
+export const CHECKED_IN_TEXT = /['"`]([^'"`\s]*\.(?:md|mdx|txt|sh|sql|tsx?|jsx?|[cm]js|vue|py|go|css|html|prisma))['"`]/
+// Config by name, not by extension: tests read JSON and YAML as data (run
+// state, artifacts, temp files) far more often than as config.
+const CONFIG_NAME = [
+  String.raw`\.github\/workflows\/[^'"\`\s/]+\.ya?ml`,
+  String.raw`\.gitlab-ci\.ya?ml`,
+  String.raw`\.?(?:mergify|cloudbuild|docker-compose|compose|skaffold|kustomization|pnpm-workspace|action|dependabot|renovate|codecov|app|netlify|vercel|firebase|fly|wrangler|turbo|nx|biome|tsconfig|jsconfig|package|deno|pyproject|Cargo|setup|tox)(?:[.-][\w.-]*)?\.(?:ya?ml|json[c5]?|toml|cfg|ini)`,
+  String.raw`\.(?:eslint|prettier|babel|stylelint)rc(?:\.[\w]+)?`,
+  String.raw`(?:Dockerfile|Containerfile|\.env)(?:\.[\w.-]+)?`,
+].join('|')
+export const CONFIG_FILE = new RegExp(String.raw`['"\`]((?:[^'"\`\s]*\/)?(?:${CONFIG_NAME}))['"\`]`)
+const FIXTURE_PATH = /(?:^|[/'"`])(?:fixtures?|__fixtures__|testdata|__snapshots__|golden)(?:[/'"`]|$)/
+const RUNS_OR_IMPORTS = /\b(?:spawn|spawnSync|execFile|execFileSync|execSync|exec|fork|import|require|run|subprocess\.\w+|runpy\.\w+)\s*\(|^\s*(?:import|export)\b|\bfrom\s+['"]/
+const DOC_COMMENT = /^\s*(?:\*|\/\*)/
+
+// Every checked-in path matching `pathRe` that the test reads as an oracle.
+// A path that is written, copied, or bound to a name later executed or
+// imported is produced or run by the test, not read as an oracle.
+function checkedInReads(lines, code, pathRe) {
+  const exempt = new Set()
+  for (const l of code) {
+    const m = WRITE_CALL.test(l) && l.match(pathRe)
+    if (m) exempt.add(m[1])
+  }
+  code.forEach((l) => {
+    const m = l.match(pathRe)
+    const bound = m && l.match(/^\s*(?:(?:const|let|var)\s+)?([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=/)
+    if (!bound) return
+    const name = new RegExp(`\\b${bound[1].replace(/\$/g, '\\$')}\\b`)
+    if (code.some((other) => other !== l && name.test(other) && RUNS_OR_IMPORTS.test(other))) exempt.add(m[1])
+  })
+  const out = []
+  code.forEach((l, i) => {
+    const m = l.match(pathRe)
+    if (!m || exempt.has(m[1])) return
+    if (DOC_COMMENT.test(lines[i]) || FIXTURE_PATH.test(m[1]) || RUNS_OR_IMPORTS.test(l) || WRITE_CALL.test(l)) return
+    out.push({ line: i + 1, detail: m[1] })
+  })
+  return out
+}
+
+export const TEXT_ORACLE_RULE = {
+  id: 'text-oracle',
+  principle: 1,
+  severity: 'lead',
+  collapse: true,
+  message: 'reads a checked-in file and matches its text: test behavior, not text; a text-only test is not coverage (principle 1)',
+  scanFile(file, lines) {
+    const code = lines.map(stripComment)
+    if (!code.some((l) => READ_CALL.test(l)) || !code.some((l) => TEXT_ASSERT.test(l))) return []
+    return checkedInReads(lines, code, CHECKED_IN_TEXT).map((hit) => ({ ...hit, kind: 'checked-in-text' }))
+  },
+}
+
+// Config read: the test reads a checked-in config file (Dockerfile, workflow,
+// cloudbuild, .mergify.yml, package.json, tsconfig, pyproject). Any assertion
+// counts: parsing the file and comparing fields restates it as surely as a
+// text match. A lead: JSON data the app loads (locales, price tables) is not
+// config (SKILL.md principle 6).
+export const CONFIG_READ_RULE = {
+  id: 'config-read',
+  principle: 6,
+  severity: 'lead',
+  collapse: true,
+  message: 'reads a checked-in config file: the tool that reads it is the test; do not test config (principle 6)',
+  scanFile(file, lines) {
+    const code = lines.map(stripComment)
+    if (!code.some((l) => READ_CALL.test(l))) return []
+    return checkedInReads(lines, code, CONFIG_FILE).map((hit) => ({ ...hit, kind: 'config-file' }))
+  },
+}
+
+// Count pin: an exact size of five or more. Lengths that encode an external
+// format (ULID 26, MD5 32, UUID 36, SHA-1 40, SHA-256 64, SHA-512 128) are
+// excluded; a lead because a fixture's own size is a legitimate pin.
+const FORMAT_LENGTHS = new Set([26, 32, 36, 40, 64, 128])
+const COUNT_PIN_PATTERNS = [
+  /\.toHaveLength\(\s*(\d+)\s*\)/,
+  /\bexpect\([\w$.[\]()]+\.length\)\s*\.to(?:Be|Equal|StrictEqual)\(\s*(\d+)\s*\)/,
+  /\bassert\.(?:strict)?[Ee]qual\(\s*[\w$.[\]()]+\.length\s*,\s*(\d+)\s*[,)]/,
+  /\b(?:assert|require)\.Len\(\s*t\s*,\s*[^,]+,\s*(\d+)\s*\)/,
+  /\bassert\s+len\([^)]*\)\s*==\s*(\d+)\b/,
+]
+
+export const COUNT_PIN_RULE = {
+  id: 'count-pin',
+  principle: 2,
+  severity: 'lead',
+  message: 'pins an exact count: every legitimate addition fails it; derive the expected size or assert the property (principle 2)',
+  match(raw, code) {
+    for (const re of COUNT_PIN_PATTERNS) {
+      const m = code.match(re)
+      if (!m) continue
+      const n = Number(m[1])
+      if (n >= 5 && !FORMAT_LENGTHS.has(n)) return { kind: 'count-pin', detail: String(n) }
+    }
+    return null
+  },
+}
+
+// Utility-class assertion: a Tailwind-shaped token asserted on a DOM class list.
+// jsdom has no layout, so this proves neither size nor position; a semantic
+// state class (`health-unknown`) does not match.
+const CLASS_ASSERT = /\.toHaveClass\(|\.classes\(\)\s*\)\s*\.toContain\(|\.className\s*\)\s*\.(?:toContain|toMatch)\(/
+const STRING_LITERAL = /(['"`])((?:(?!\1).)*)\1/g
+const UTILITY_TOKEN = /^!?(?:(?:sm|md|lg|xl|2xl|hover|focus|group-[\w-]+|data-\[[^\]]*\]):.+|.*-\[[^\]]+\]!?|-?(?:m[trblxy]?|p[trblxy]?|w|h|min-h|min-w|max-w|max-h|size|gap|rounded|shadow|grid-cols|space-[xy])(?:-[\w./]+)?!?)$/
+const hasUtilityToken = (code) => [...code.matchAll(STRING_LITERAL)]
+  .some((m) => m[2].split(/\s+/).some((token) => UTILITY_TOKEN.test(token)))
+
+export const UTILITY_CLASS_RULE = {
+  id: 'utility-class',
+  principle: 3,
+  severity: 'lead',
+  message: 'asserts a utility CSS class: jsdom has no layout; prove size or position in a real browser (principle 3)',
+  match(raw, code) {
+    return CLASS_ASSERT.test(code) && hasUtilityToken(code) ? { kind: 'utility-class' } : null
+  },
+}
+
+// Duplicate test file: identical content after whitespace normalisation.
+// Resolved by the CLI across every scanned file (findDuplicateFiles).
+export const DUPLICATE_FILE_RULE = {
+  id: 'duplicate-file',
+  principle: 5,
+  severity: 'lead',
+  crossFile: true,
+  message: 'identical to another test file: one behavior, one place (principle 5)',
+}
+
+export const ALL_RULES = [
+  ...RULES,
+  CONDITIONAL_SKIP_RULE,
+  MOCK_INTERNAL_SEAM_RULE,
+  REDUNDANT_MATCHER_RULE,
+  TEXT_ORACLE_RULE,
+  CONFIG_READ_RULE,
+  COUNT_PIN_RULE,
+  UTILITY_CLASS_RULE,
+  DUPLICATE_FILE_RULE,
+]
+
+export function selectRules(ruleIds) {
+  if (ruleIds && ruleIds.length > 0) {
+    const set = new Set(ruleIds)
+    return ALL_RULES.filter((r) => set.has(r.id))
+  }
+  return ALL_RULES.filter((r) => r.defaultOn !== false)
+}
+
+// Strip line comments so a doc line or a commented-out example is not flagged.
+// Best-effort (ignores strings/block comments) — live code has no leading `//`.
+export function stripComment(line) {
+  return line.replace(/\/\/.*$/, '').replace(/(^|\s)#.*$/, '$1')
+}
+
+// Only test code is scanned: linting app code would false-flag a legitimate
+// `.skip()`/`.only` array method or a real `sleep`, and a data file under
+// `tests/` (parquet, JSON fixtures) is not a test.
+export function isTestFile(p) {
+  if (!p) return false
+  return /\.(spec|test)\.[cm]?[jt]sx?$/.test(p)
+    || (/(^|\/)(e2e|tests?|__tests__)\//.test(p) && /\.(?:[cm]?[jt]sx?|py|go)$/.test(p))
+    || /(^|\/)test_[^/]*\.py$/.test(p)
+    || /_test\.py$/.test(p)
+    || /_test\.go$/.test(p)
+}
+
+function finding(file, rule, line, raw, hit = {}) {
+  return {
+    file, line, rule: rule.id, severity: rule.severity, principle: rule.principle,
+    kind: hit.kind || rule.id,
+    snippet: (raw || '').trim().slice(0, 120),
+    ...(hit.detail ? { detail: hit.detail } : {}),
+    ...(hit.reason ? { reason: hit.reason } : {}),
+  }
+}
+
+// Pure: run the line-level rules over one line → findings (≤ one per rule).
+function scanLine(file, raw, lineNo, rules, ctx) {
+  const code = stripComment(raw)
+  const out = []
+  for (const rule of rules) {
+    if (typeof rule.match === 'function') {
+      const hit = rule.match(raw, code, ctx)
+      if (hit) out.push(finding(file, rule, lineNo, raw, hit))
+    } else if (rule.patterns) {
+      const hit = rule.patterns.find((p) => p.re.test(code))
+      if (hit) out.push(finding(file, rule, lineNo, raw, hit))
+    }
+  }
+  return out
+}
+
+// A `collapse` rule reports once per file, at its first hit, naming every
+// distinct detail: one lead per test file is what an auditor reads.
+function scanFileRules(file, lines, rules, ctx, keep = () => true) {
+  const out = []
+  for (const rule of rules) {
+    if (typeof rule.scanFile !== 'function') continue
+    const hits = rule.scanFile(file, lines, ctx).filter((hit) => keep(hit.line))
+    if (hits.length === 0) continue
+    if (rule.collapse) {
+      const detail = [...new Set(hits.map((hit) => hit.detail))].join(', ')
+      out.push(finding(file, rule, hits[0].line, lines[hits[0].line - 1], { ...hits[0], detail }))
+    } else {
+      for (const hit of hits) out.push(finding(file, rule, hit.line, lines[hit.line - 1], hit))
+    }
+  }
+  return out
+}
+
+const byPosition = (a, b) => a.line - b.line || a.rule.localeCompare(b.rule)
+
+export function scanLines(file, lines, ruleIds, ctx) {
+  const rules = selectRules(ruleIds)
+  const out = []
+  lines.forEach((raw, i) => out.push(...scanLine(file, raw, i + 1, rules, ctx)))
+  out.push(...scanFileRules(file, lines, rules, ctx))
+  return out.sort(byPosition)
+}
+
+export function scanText(file, text, ruleIds, ctx) {
+  return scanLines(file, (text || '').split(/\r?\n/), ruleIds, ctx)
+}
+
+// Pure: scan a unified diff, reporting only findings on ADDED lines of test
+// files. File-level rules need the whole file: pass `readFile(path) → text` and
+// they run on it, keeping only findings that land on an added line.
+export function scanDiff(diffText, ruleIds, ctx, readFile) {
+  const rules = selectRules(ruleIds)
+  const out = []
+  const added = new Map()
+  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] !== '/dev/null' ? m[1] : null
+      continue
+    }
+    if (raw.startsWith('@@')) {
+      const m = raw.match(/\+(\d+)/)
+      newLine = m ? parseInt(m[1], 10) : 0
+      continue
+    }
+    if (raw.startsWith('+')) {
+      if (isTestFile(file)) {
+        out.push(...scanLine(file, raw.slice(1), newLine, rules, ctx))
+        if (!added.has(file)) added.set(file, new Set())
+        added.get(file).add(newLine)
+      }
+      newLine++
+    } else if (raw.startsWith('-') || raw.startsWith('\\')) {
+      // removed line / "No newline" marker — do not advance the new-file counter
+    } else {
+      newLine++ // context line
+    }
+  }
+  if (typeof readFile === 'function' && rules.some((r) => typeof r.scanFile === 'function')) {
+    for (const [f, lines] of added) {
+      const text = readFile(f)
+      if (text == null) continue
+      out.push(...scanFileRules(f, text.split(/\r?\n/), rules, ctx, (line) => lines.has(line)))
+    }
+  }
+  return out
+}
+
+// Pure: group files whose whitespace-normalised content is identical. Files
+// under ten non-blank lines are ignored (tiny smoke files legitimately match).
+export function findDuplicateFiles(entries) {
+  const groups = new Map()
+  for (const { file, text } of entries) {
+    const lines = (text || '').split(/\r?\n/).filter((l) => l.trim())
+    if (lines.length < 10) continue
+    const key = crypto.createHash('sha256').update(lines.map((l) => l.trim().replace(/\s+/g, ' ')).join('\n')).digest('hex')
+    if (!groups.has(key)) groups.set(key, [])
+    groups.get(key).push(file)
+  }
+  const out = []
+  for (const files of groups.values()) {
+    if (files.length < 2) continue
+    for (const f of files) {
+      out.push(finding(f, DUPLICATE_FILE_RULE, 1, '', { detail: files.filter((o) => o !== f).join(', ') }))
+    }
+  }
+  return out
+}
+
+// ---- CLI ----
+
+const SKIP_DIRS = new Set(['node_modules', 'site-packages', 'venv'])
+
+function discover(dir, acc = []) {
+  let entries
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return acc } // unreadable dir: skip, never crash the scan
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.') || entry.name.endsWith('-workspace')) continue
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) discover(full, acc)
+    else if (isTestFile(full)) acc.push(full)
+  }
+  return acc
+}
+
+// `--exclude dist,vendor,fixtures`: drop any file with one of these as a path
+// segment (or path prefix), for vendored, generated, and fixture trees.
+export function excluded(file, segments) {
+  if (!segments || segments.length === 0) return false
+  const norm = file.split(path.sep).join('/').replace(/^\.\//, '')
+  const parts = norm.split('/')
+  return segments.some((s) => parts.includes(s) || norm.startsWith(`${s.replace(/\/$/, '')}/`))
+}
+
+// `--shares N`: split the files with findings into at most N shares of about
+// equal finding count, one per audit reviewer. A file stays whole; the
+// biggest files are placed first, each into the lightest share.
+export function splitShares(findings, n) {
+  const counts = new Map()
+  for (const f of findings) counts.set(f.file, (counts.get(f.file) || 0) + 1)
+  const files = [...counts].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+  const shares = Array.from({ length: Math.min(n, files.length) }, () => ({ findings: 0, files: [] }))
+  for (const [file, count] of files) {
+    const lightest = shares.reduce((min, share) => (share.findings < min.findings ? share : min))
+    lightest.files.push(file)
+    lightest.findings += count
+  }
+  return shares
+}
+
+const USAGE = [
+  'usage: lint-tests.mjs [--diff <base>] [--files a,b] [--rules a,b] [--exclude a,b] [--config coverage.config.json] [--shares N] [--json]',
+  '  (no flags)      scan every test file under the current directory; run from the repo root',
+  '  --diff <base>   report only findings on lines changed since the merge-base with <base>: commits,',
+  '                  staged and unstaged edits, and untracked test files (whole file)',
+  '  --files a,b     scan exactly these files; a missing file is an error',
+  `  --rules a,b     subset of: ${ALL_RULES.map((r) => r.id).join(', ')}`,
+  '  --exclude a,b   skip files with any of these path segments or prefixes (e.g. dist,vendor,fixtures)',
+  '  --shares N      also split the files with findings into at most N review shares of about equal finding count',
+  '  exit 0 no gate findings · 1 gate findings · 2 usage error. Lead findings never change the exit code.',
+].join('\n')
+
+const VALUE_FLAGS = new Set(['--diff', '--files', '--rules', '--config', '--exclude', '--shares'])
+const list = (v) => (v || '').split(',').map((s) => s.trim()).filter(Boolean)
+
+export function runCli(argv, { name = 'lint-tests', cwd = process.cwd() } = {}) {
+  if (argv.includes('--help') || argv.includes('-h')) { console.log(USAGE); return 0 }
+  const usageError = (msg) => { console.error(`${name}: ${msg}\n\n${USAGE}`); return 2 }
+  const flags = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--json') { flags.json = true; continue }
+    if (!VALUE_FLAGS.has(a)) return usageError(`unknown argument ${JSON.stringify(a)}`)
+    const v = argv[++i]
+    if (v === undefined || v.startsWith('--')) return usageError(`${a} needs a value`)
+    flags[a.slice(2)] = v
+  }
+  const ruleIds = flags.rules ? list(flags.rules) : null
+  const unknown = (ruleIds || []).filter((id) => !ALL_RULES.some((r) => r.id === id))
+  if (unknown.length) return usageError(`unknown rule(s): ${unknown.join(', ')}`)
+  const shareCount = flags.shares === undefined ? null : Number(flags.shares)
+  if (shareCount !== null && !(Number.isInteger(shareCount) && shareCount > 0)) return usageError('--shares needs a positive whole number')
+  const exclude = list(flags.exclude)
+  const configPath = flags.config && path.resolve(cwd, flags.config)
+  const ctx = { policy: loadMockPolicyFromFile(configPath, cwd) }
+
+  let findings = []
+  if (flags.diff) {
+    // Diff from the merge-base to the WORKING TREE, so a writer's uncommitted
+    // tests count; git paths are repo-root-relative, so read files from there.
+    const git = (args) => execSync(`git ${args}`, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+    const root = git('rev-parse --show-toplevel').trim()
+    const base = git(`merge-base ${flags.diff} HEAD`).trim()
+    const readAtRoot = (f) => { const p = path.join(root, f); return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null }
+    const diff = execSync(`git diff ${base}`, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+    findings = scanDiff(diff, ruleIds, ctx, readAtRoot).filter((f) => !excluded(f.file, exclude))
+    const untracked = execSync('git ls-files -o --exclude-standard', { cwd: root, encoding: 'utf8' })
+      .split('\n').filter((f) => f && isTestFile(f) && !excluded(f, exclude))
+    for (const f of untracked) findings.push(...scanText(f, readAtRoot(f), ruleIds, ctx))
+  } else {
+    let files
+    if (flags.files) {
+      files = list(flags.files)
+      const missing = files.filter((f) => !fs.existsSync(path.resolve(cwd, f)))
+      if (missing.length) return usageError(`no such file(s): ${missing.join(', ')}`)
+    } else {
+      files = discover(cwd).map((f) => path.relative(cwd, f) || f)
+    }
+    const entries = files.filter((f) => !excluded(f, exclude))
+      .map((f) => ({ file: f, text: fs.readFileSync(path.resolve(cwd, f), 'utf8') }))
+    for (const { file, text } of entries) findings.push(...scanText(file, text, ruleIds, ctx))
+    if (selectRules(ruleIds).some((r) => r.crossFile)) findings.push(...findDuplicateFiles(entries))
+  }
+
+  const gates = findings.filter((f) => f.severity === 'gate').length
+  const leads = findings.length - gates
+  const shares = shareCount === null ? null : splitShares(findings, shareCount)
+  if (flags.json) {
+    console.log(JSON.stringify({ ok: gates === 0, gates, leads, findings, ...(shares && { shares }) }, null, 2))
+  } else if (findings.length === 0) {
+    console.log(`${name}: ✓ no findings` + (flags.diff ? ' in this change' : ' in scanned test files'))
+  } else {
+    console.log(`${name}: ${gates ? '✗' : '✓'} ${gates} gate, ${leads} lead finding(s):\n`)
+    for (const f of findings) {
+      const why = f.detail ? `  → ${f.detail}${f.reason ? ` (${f.reason})` : ''}` : ''
+      console.log(`  ${f.file}:${f.line} [${f.severity} ${f.rule}/${f.kind}]  ${f.snippet}${why}`)
+    }
+    for (const [i, share] of (shares || []).entries()) {
+      console.log(`\nshare ${i + 1}: ${share.findings} finding(s) in ${share.files.length} file(s)\n  ${share.files.join('\n  ')}`)
+    }
+  }
+  return gates === 0 ? 0 : 1
+}
+
+// exitCode, not process.exit(): exiting early truncates piped stdout at 64KB.
+if (isMainModule(import.meta.url)) process.exitCode = runCli(process.argv.slice(2), { name: 'lint-tests' })