@getarbiter/cli 0.5.0

package/dist/templates/scripts/check-min-test-execution.mjs.ejs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// scripts/check-min-test-execution.mjs — generated by arbiter (anti-fake-green, INV-25).
+//
+// No-empty-suite / min-execution guard. A test tier that collects ZERO tests yet exits 0 is the
+// classic false-green ("100 tests, 0 executed = green"): the gate is green while no test body ever
+// ran. The runner's own exit code does not catch it — `vitest run --passWithNoTests`,
+// `pytest` on an empty tree (exit 5 swallowed), and a `go test ./...` over a package with no test
+// files all report success on zero tests. This guard asks the project's test runner how many tests
+// it would run and FAILS when that count is 0.
+//
+// It uses each runner's COLLECT / LIST mode (no test bodies execute), so it is cheap and never
+// double-runs the suite:
+//   - vitest : `vitest list`              → one line per collected test (the " > " test-id form)
+//   - jest   : `jest --listTests`         → one line per test FILE (file-level proxy)
+//   - pytest : `pytest --collect-only -q` → "<N> tests collected" / "no tests collected"
+//   - go     : `go test -list '.*' ./...` → one line per Test/Example/Benchmark/Fuzz function
+//
+// Semantics:
+//   - no recognized runner            → NA   (exit 0) — nothing to assert.
+//   - runner recognized, not installed→ SKIP (exit 0) — deps not present yet (fresh greenfield);
+//                                        the real test gate would fail first if this mattered.
+//   - collection errored (build/import
+//     failure, unexpected exit)       → ERROR(exit 2) — surfaced loudly, never masked as "0 tests".
+//   - collected 0 tests               → FAIL (exit 1) — the empty-suite false-green.
+//   - collected > 0 tests             → PASS (exit 0).
+//
+// This guard targets the EMPTY-collection false-green. Whether an all-skipped suite trips it is the
+// runner's call: `vitest list` omits skipped tests (so an all-skipped suite collects 0 and FAILS
+// here), while `pytest --collect-only` counts them (so it passes here and is left to the muted-test
+// guard, check-muted-test). The two guards overlap by design — defense in depth, never a gap.
+//
+// Usage: node scripts/check-min-test-execution.mjs [--help]
+// Exit codes (INV-53): 0=PASS/NA/SKIP, 1=FAIL (empty suite), 2=ERROR (collector failure / self).
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const args = process.argv.slice(2)
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(
+    'Usage: node scripts/check-min-test-execution.mjs\n' +
+      '  Fails when the project test runner collects 0 tests (the empty-suite false-green).\n' +
+      '  Uses the runner collect/list mode (no execution). NA when no recognized runner.\n',
+  )
+  process.exit(0)
+}
+
+// Test seam (INV / anti-vacuous): `--parse <runner>` reads collect output on stdin and prints the
+// parsed count (or "null"). Lets the parsers be exercised against real captured runner output
+// without invoking the runner — keeping the guard's own test deterministic and toolchain-free.
+const parseIdx = args.indexOf('--parse')
+if (parseIdx !== -1) {
+  const runner = args[parseIdx + 1]
+  const counters = { vitest: countVitest, jest: countJest, pytest: countPytest, go: countGo }
+  const counter = counters[runner]
+  if (!counter) {
+    process.stderr.write(`check-min-test-execution: unknown runner "${runner}"\n`)
+    process.exit(2)
+  }
+  let stdin = ''
+  try {
+    stdin = readFileSync(0, 'utf-8')
+  } catch {
+    stdin = ''
+  }
+  const n = counter(stdin)
+  process.stdout.write(`${n == null ? 'null' : n}\n`)
+  process.exit(0)
+}
+
+const ROOT = process.cwd()
+const IS_CI = process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true'
+const IS_WIN = process.platform === 'win32'
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+function localBin(name) {
+  const bin = join(ROOT, 'node_modules', '.bin', IS_WIN ? `${name}.cmd` : name)
+  return existsSync(bin) ? bin : null
+}
+
+function hasAnyDep(pkg, names) {
+  const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) }
+  return names.some((n) => Object.prototype.hasOwnProperty.call(deps, n))
+}
+
+function hasConfig(prefixes, exts) {
+  for (const p of prefixes) {
+    for (const e of exts) {
+      if (existsSync(join(ROOT, `${p}${e}`))) return true
+    }
+  }
+  return false
+}
+
+// ── Runner detection ──────────────────────────────────────────────────────────
+// Returns { runner, bin, cmd, args } or null (NA). `bin === null` ⇒ recognized but not installed.
+function detectRunner() {
+  const pkgPath = join(ROOT, 'package.json')
+  if (existsSync(pkgPath)) {
+    const pkg = readJson(pkgPath)
+    const usesVitest =
+      hasAnyDep(pkg, ['vitest']) || hasConfig(['vitest.config'], ['.ts', '.js', '.mjs', '.cts', '.mts'])
+    // 'src' scope mirrors the generated `test:unit` script (#1840 F4 tranche-3):
+    // an unscoped `vitest list` also collects tests/api and tests/e2e (live-server
+    // / browser suites with their OWN runner, never `vitest run`), so this guard
+    // must count the SAME scope the unit-test gate step actually executes.
+    if (usesVitest) return { runner: 'vitest', bin: localBin('vitest'), args: ['list', 'src'] }
+    const usesJest =
+      hasAnyDep(pkg, ['jest']) ||
+      pkg?.jest != null ||
+      hasConfig(['jest.config'], ['.ts', '.js', '.mjs', '.cjs', '.json'])
+    if (usesJest) return { runner: 'jest', bin: localBin('jest'), args: ['--listTests'] }
+    // No JS runner in THIS package.json — do NOT early-return NA: a polyglot repo (JS frontend +
+    // a Go/Python backend at root) still has a backend suite the empty-suite guard must assert.
+    // Fall through to the go.mod / Python markers below; NA is reached only when NO runner matches.
+  }
+  if (existsSync(join(ROOT, 'go.mod'))) {
+    return { runner: 'go', bin: 'go', args: ['test', '-list', '.*', './...'] }
+  }
+  const pyMarker =
+    existsSync(join(ROOT, 'pyproject.toml')) ||
+    existsSync(join(ROOT, 'pytest.ini')) ||
+    existsSync(join(ROOT, 'setup.cfg')) ||
+    existsSync(join(ROOT, 'tox.ini')) ||
+    existsSync(join(ROOT, 'conftest.py'))
+  if (pyMarker) return { runner: 'pytest', bin: 'pytest', args: ['--collect-only', '-q'] }
+  return null
+}
+
+// ── Count parsers (per runner) ──────────────────────────────────────────────────
+// Each returns a non-negative integer, or null when the output cannot be parsed.
+function countVitest(stdout) {
+  // `vitest list` prints one collected test per line as "file > [suite > ] name".
+  return stdout.split('\n').filter((l) => l.includes(' > ')).length
+}
+function countJest(stdout) {
+  // `jest --listTests` prints one absolute test-FILE path per line.
+  return stdout.split('\n').filter((l) => l.trim().length > 0).length
+}
+function countPytest(stdout) {
+  if (/no tests (collected|ran)/i.test(stdout)) return 0
+  let m = stdout.match(/(\d+)\s+tests?\s+(?:collected|selected)/i)
+  if (m) return Number(m[1])
+  m = stdout.match(/collected\s+(\d+)\s+items?/i)
+  if (m) return Number(m[1])
+  return null
+}
+function countGo(stdout) {
+  // `go test -list` prints one Test/Example/Benchmark/Fuzz function name per line, plus per-package
+  // status lines ("ok  pkg", "?   pkg [no test files]") which are NOT test names.
+  return stdout.split('\n').filter((l) => /^(Test|Example|Benchmark|Fuzz)\w*\s*$/.test(l.trim()))
+    .length
+}
+
+function pass(msg) {
+  process.stdout.write(`check-min-test-execution: ${msg}\n`)
+  process.exit(0)
+}
+function fail(msg) {
+  process.stderr.write(`check-min-test-execution: FAIL — ${msg}\n`)
+  process.exit(1)
+}
+function error(msg) {
+  process.stderr.write(`check-min-test-execution: ERROR — ${msg}\n`)
+  process.exit(2)
+}
+
+function main() {
+  const det = detectRunner()
+  if (!det) pass('no recognized test runner — NA')
+  if (!det.bin) {
+    // Recognized runner but the binary is absent. In CI the toolchain is installed, so an absent
+    // runner is itself suspicious — but the actual test gate fails first; we stay advisory here.
+    pass(`${det.runner} not installed — SKIP (deps not present)${IS_CI ? ' [CI]' : ''}`)
+  }
+
+  const r = spawnSync(det.bin, det.args, {
+    cwd: ROOT,
+    encoding: 'utf-8',
+    shell: false,
+    timeout: 120_000,
+    maxBuffer: 64 * 1024 * 1024,
+  })
+  if (r.error && r.error.code === 'ENOENT') pass(`${det.runner} not installed — SKIP`)
+  if (r.error) error(`${det.runner} collect failed to spawn: ${r.error.message}`)
+  const out = `${r.stdout ?? ''}\n${r.stderr ?? ''}`
+
+  // pytest signals "no tests" with exit 5 — that is a legitimate empty collection, not an error.
+  const pytestEmpty = det.runner === 'pytest' && r.status === 5
+  if (!pytestEmpty && r.status !== 0) {
+    error(`${det.runner} collect exited ${r.status} (collection error, not an empty suite):\n${out}`)
+  }
+
+  const counters = {
+    vitest: countVitest,
+    jest: countJest,
+    pytest: countPytest,
+    go: countGo,
+  }
+  const count = counters[det.runner](out)
+  if (count == null) {
+    error(`could not parse ${det.runner} collect output:\n${out}`)
+  }
+  if (count === 0) {
+    fail(
+      `${det.runner} collected 0 tests — an empty suite that reports success is a false-green. ` +
+        'Add a real test, or remove the empty tier from the gate.',
+    )
+  }
+  pass(`${det.runner} collects ${count} test(s) — OK`)
+}
+
+try {
+  main()
+} catch (e) {
+  error(e?.message ?? String(e))
+}

package/dist/templates/scripts/check-muted-test.mjs.ejs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// scripts/check-muted-test.mjs — generated by arbiter (anti-fake-green, #1497).
+//
+// Muted-gate-test guard. A GATE test silenced by a skip/disable marker is a fake-green: the
+// suite goes green because the test that would catch the regression never runs. This guard greps
+// gate test dirs for cross-stack skip markers and FAILS CLOSED:
+//   it.skip/test.skip/describe.skip, xit/xtest/xdescribe, .todo/.failing   — JS/TS
+//   @Disabled / @Ignore, assume-style aborts (assumeTrue/assumeFalse/abort) — JVM
+//   #[ignore]                                                              — Rust
+//   @pytest.mark.skip / @unittest.skip                                     — Python
+//   t.Skip(                                                                — Go
+// An AUDITED `// arbiter-allow-skip: <reason>` marker (on the skip line or the line above) makes a
+// skip explicit, greppable, and reasoned, and opts it out; an UNMARKED skip still fails. NO-DATA
+// (no test dir / no test files) is a SKIP at exit 0 — an explicit no-data signal, NEVER a
+// manufactured pass.
+//
+// BROWNFIELD BASELINE (same policy shape as spotbugs-baseline.json): a legacy repo can carry
+// dozens of pre-existing @Disabled tests that are not fixable in one adoption step. Running
+// `--update-baseline` grandfathers the CURRENT counts (per file, per marker kind) into
+// muted-tests-baseline.json; from then on the gate fails ONLY on NEW muted tests — a new marker
+// in a new file, or a count above the baselined count in a grandfathered file. Removing muted
+// tests never fails; re-run --update-baseline to ratchet the baseline down.
+//
+// Exit codes (INV-53): 0=PASS / NO-DATA-skip, 1=FAIL (muted gate test found), 2=ERROR.
+// Usage: node scripts/check-muted-test.mjs [--dir <path>] [--update-baseline] [--help]
+import { readdirSync, statSync, readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { join, resolve, relative } from 'node:path'
+
+const args = process.argv.slice(2)
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(
+    'Usage: node scripts/check-muted-test.mjs [--dir <path>] [--update-baseline]\n' +
+      '  Fails closed when a gate test is silenced by a skip/disable marker (incl. JVM assume-\n' +
+      '  style aborts: assumeTrue/assumeFalse/abort). Add `// arbiter-allow-skip: <reason>` on\n' +
+      '  the marker line or the line above to audit-exempt a legitimate skip. NO-DATA (no test\n' +
+      '  dir / no test files) is a SKIP at exit 0, never a pass.\n' +
+      '  --update-baseline grandfathers CURRENT muted tests into muted-tests-baseline.json\n' +
+      '  (brownfield adoption); afterwards only NEW muted tests fail the gate.\n',
+  )
+  process.exit(0)
+}
+const dirArgIdx = args.indexOf('--dir')
+const ROOT = dirArgIdx >= 0 && args[dirArgIdx + 1] ? resolve(args[dirArgIdx + 1]) : process.cwd()
+const UPDATE_BASELINE = args.includes('--update-baseline')
+const BASELINE_PATH = join(ROOT, 'muted-tests-baseline.json')
+
+// #1840 F4 tranche-3: '.venv'/'venv'/'__pycache__' — a Python dependency's
+// bundled test suite inside site-packages (e.g. greenlet) must never be
+// scanned as if it were project code (mirrors lib/glob-walk.mjs's SKIP_DIRS).
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'coverage',
+  '.coverage',
+  '.venv',
+  'venv',
+  '__pycache__',
+])
+
+// A file is a gate test if its name matches one of these (JS/TS/JVM/Rust/Python/Go conventions).
+// JS/TS/Rust/Python/Go tests are identified by filename; bare `.java`/`.kt` files are dir-gated to
+// a JVM test tree (src/test/**) inside collectTestFiles via the `inJvmTestTree` flag below.
+function isTestFile(name) {
+  return (
+    /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs)$/.test(name) ||
+    /Test\.(java|kt)$/.test(name) ||
+    /\.(java|kt)$/.test(name) /* JVM tests live under src/test → dir-gated below */ ||
+    /_test\.(rs|go|py)$/.test(name) ||
+    /^test_.*\.py$/.test(name) ||
+    /_spec\.rb$/.test(name)
+  )
+}
+
+// Cross-stack skip / disable markers, anchored to STATEMENT/ANNOTATION position so a string
+// literal that merely mentions a marker (e.g. expect(x).toContain('it.skip(')) is NOT a violation.
+const MUTE_PATTERNS = [
+  { re: /^(?:await\s+|return\s+)?(?:it|test|describe)\.skip\s*\(/, label: 'js/ts .skip()' },
+  { re: /^(?:await\s+|return\s+)?x(?:it|test|describe)\s*\(/, label: 'js/ts xit/xtest/xdescribe' },
+  {
+    re: /^(?:await\s+|return\s+)?(?:it|test|describe)\.(?:todo|failing)\s*\(/,
+    label: 'js/ts .todo/.failing()',
+  },
+  { re: /^@Disabled\b/, label: 'jvm @Disabled' },
+  { re: /^@Ignore\b/, label: 'jvm @Ignore' },
+  // Assume-style aborts silently skip the rest of a JVM test when their predicate is unmet — a
+  // gate test that aborts is just as muted as one annotated @Disabled.
+  {
+    re: /^(?:Assumptions?|Assume)?\.?assume(?:True|False|NotNull|That)\s*\(/,
+    label: 'jvm assume-abort',
+  },
+  { re: /^(?:Assumptions?\.)?abort\s*\(/, label: 'jvm assume abort()' },
+  { re: /^#\[ignore\]/, label: 'rust #[ignore]' },
+  { re: /^@(?:pytest\.mark\.skip|unittest\.skip)/, label: 'python skip' },
+  { re: /^t\.Skip\s*\(/, label: 'go t.Skip()' },
+]
+
+// Audited inline opt-out for an intentionally-skipped gate test. A legitimate skip must be
+// EXPLICIT, greppable, and carry a reason: `// arbiter-allow-skip: <reason>` on the marker line or
+// the line above. The marker MUST sit in a real comment (a `//`, `#`, or `*` delimiter precedes
+// the token) — this blocks the fake-green of burying the token in a STRING LITERAL to silence the
+// guard. An UNMARKED skip, or a marker with no reason, still fails closed.
+const EXEMPT_RE = /(?:^|\s)(?:\/\/+|#+|\*)\s*(?:arbiter-allow-skip|muted-test-exempt):\s*\S/
+
+/** Recursively collect gate-test file paths, gating JVM files to src/test/** dirs. */
+function collectTestFiles(dir, acc, inJvmTestTree) {
+  let entries
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry)) continue
+    const full = join(dir, entry)
+    let st
+    try {
+      st = statSync(full)
+    } catch {
+      continue
+    }
+    if (st.isDirectory()) {
+      const nextJvm = inJvmTestTree || entry === 'test' || entry === 'tests'
+      collectTestFiles(full, acc, nextJvm)
+    } else if (isTestFile(entry)) {
+      // Bare .java/.kt only count when inside a test tree (src/test/**), to avoid main sources.
+      if (/\.(java|kt)$/.test(entry) && !/Test\.(java|kt)$/.test(entry) && !inJvmTestTree) continue
+      acc.push(full)
+    }
+  }
+}
+
+// ── Brownfield baseline (grandfathered muted tests) ─────────────────────────
+// Shape: { policy, baselined: { "<repo-relative file>": { "<marker label>": count } } }.
+// Line numbers are deliberately NOT part of the fingerprint — they drift on every
+// edit; per-file per-label COUNTS are stable and still catch every NEW mute
+// (new file, new marker kind, or count above the grandfathered count).
+
+function loadBaseline() {
+  if (!existsSync(BASELINE_PATH)) return {}
+  let parsed
+  try {
+    parsed = JSON.parse(readFileSync(BASELINE_PATH, 'utf-8'))
+  } catch (e) {
+    // Fail CLOSED: an unparseable baseline must never silently disable the gate.
+    throw new Error(`muted-tests-baseline.json is invalid JSON: ${e?.message ?? e}`)
+  }
+  const baselined = parsed?.baselined
+  if (baselined === undefined || baselined === null) return {}
+  if (typeof baselined !== 'object' || Array.isArray(baselined)) {
+    throw new Error('muted-tests-baseline.json: "baselined" must be an object map')
+  }
+  return baselined
+}
+
+function writeBaseline(counts) {
+  const sorted = {}
+  for (const file of Object.keys(counts).sort()) {
+    sorted[file] = {}
+    for (const label of Object.keys(counts[file]).sort()) {
+      sorted[file][label] = counts[file][label]
+    }
+  }
+  const doc = {
+    policy:
+      'pre-existing muted tests grandfathered via --update-baseline; NEW muted gate tests always fail',
+    baselined: sorted,
+  }
+  writeFileSync(BASELINE_PATH, JSON.stringify(doc, null, 2) + '\n')
+}
+
+function main() {
+  const files = []
+  collectTestFiles(ROOT, files, false)
+
+  if (files.length === 0) {
+    // NO-DATA: no gate test files discovered. Explicit skip, never a manufactured pass.
+    process.stdout.write('check-muted-test: SKIP — no gate test files found (NO-DATA)\n')
+    return 0
+  }
+
+  /** @type {{ file: string; rel: string; line: number; label: string; text: string }[]} */
+  const findings = []
+  for (const file of files) {
+    let content
+    try {
+      content = readFileSync(file, 'utf-8')
+    } catch {
+      continue
+    }
+    const rel = relative(ROOT, file).split('\\').join('/')
+    const lines = content.split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const trimmed = lines[i].trim()
+      const prev = i > 0 ? lines[i - 1] : ''
+      if (EXEMPT_RE.test(lines[i]) || EXEMPT_RE.test(prev)) continue
+      for (const { re, label } of MUTE_PATTERNS) {
+        if (re.test(trimmed)) {
+          findings.push({ file, rel, line: i + 1, label, text: trimmed })
+        }
+      }
+    }
+  }
+
+  // Group by file+label — the baseline unit.
+  /** @type {Record<string, Record<string, number>>} */
+  const counts = {}
+  for (const f of findings) {
+    counts[f.rel] = counts[f.rel] ?? {}
+    counts[f.rel][f.label] = (counts[f.rel][f.label] ?? 0) + 1
+  }
+
+  if (UPDATE_BASELINE) {
+    writeBaseline(counts)
+    process.stdout.write(
+      `check-muted-test: baseline updated — ${findings.length} muted test(s) grandfathered ` +
+        `across ${Object.keys(counts).length} file(s) → ${BASELINE_PATH}\n`,
+    )
+    return 0
+  }
+
+  const baseline = loadBaseline()
+  const violations = []
+  let grandfathered = 0
+  for (const [rel, labels] of Object.entries(counts)) {
+    for (const [label, count] of Object.entries(labels)) {
+      const allowed = typeof baseline[rel]?.[label] === 'number' ? baseline[rel][label] : 0
+      if (count <= allowed) {
+        grandfathered += count
+        continue
+      }
+      const lines = findings.filter((f) => f.rel === rel && f.label === label)
+      violations.push(
+        `  ${rel}: ${count} × ${label}` +
+          (allowed > 0 ? ` (baseline allows ${allowed} — new mute added)` : '') +
+          '\n' +
+          lines.map((f) => `    ${f.file}:${f.line}: ${f.text}`).join('\n'),
+      )
+    }
+  }
+
+  if (violations.length > 0) {
+    process.stderr.write(
+      `check-muted-test: muted gate test(s) over baseline — a silenced gate test is a fake-green:\n`,
+    )
+    for (const v of violations) process.stderr.write(v + '\n')
+    process.stderr.write(
+      'Fix the test, add `// arbiter-allow-skip: <reason>`, or (brownfield adoption only)\n' +
+        'grandfather the CURRENT state via: node scripts/check-muted-test.mjs --update-baseline\n',
+    )
+    return 1
+  }
+  process.stdout.write(
+    `check-muted-test: OK — ${files.length} gate test file(s)` +
+      (grandfathered > 0
+        ? `, ${grandfathered} muted test(s) grandfathered by muted-tests-baseline.json`
+        : ', no skip markers') +
+      '\n',
+  )
+  return 0
+}
+
+try {
+  process.exit(main())
+} catch (e) {
+  process.stderr.write(`check-muted-test: ERROR — ${e?.message ?? e}\n`)
+  process.exit(2)
+}

package/dist/templates/scripts/check-no-stub-redirects.mjs.ejs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// scripts/check-no-stub-redirects.mjs — generated by arbiter (anti-fake-green, #1497).
+//
+// No-stub-redirects guard. A stale "Moved → X" stub .md is a fake-green for docs: the link checker
+// passes and the page "exists", but it is a redirect husk with no real content — a green doc signal
+// not backed by a real doc. This guard flags a .md that is (a) a heading/leading line with a
+// redirect VERB (Moved / Relocated / Renamed / has moved / see instead), (b) a short body, and
+// (c) exactly one .md link. Allowlist (.stub-redirects-allowlist) entries REQUIRE a hard
+// `EXPIRES: YYYY-MM-DD` date — an open-ended or lapsed exemption is itself a fake-green, so it
+// fails closed. NO-DATA (no docs) is a PASS (nothing to flag), not a manufactured fail.
+//
+// Exit codes (INV-53): 0=PASS, 1=FAIL (un-allowlisted stub / bad allowlist), 2=ERROR.
+// Usage: node scripts/check-no-stub-redirects.mjs [--dir <path>] [--help]
+import { readdirSync, statSync, readFileSync, existsSync } from 'node:fs'
+import { join, resolve, relative } from 'node:path'
+
+const args = process.argv.slice(2)
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(
+    'Usage: node scripts/check-no-stub-redirects.mjs [--dir <path>]\n' +
+      '  Fails on a stale "Moved → X" stub .md unless allowlisted with a future EXPIRES: date.\n' +
+      '  Allowlist file: .stub-redirects-allowlist (one "path  EXPIRES: YYYY-MM-DD  # note" per line).\n',
+  )
+  process.exit(0)
+}
+const dirArgIdx = args.indexOf('--dir')
+const ROOT = dirArgIdx >= 0 && args[dirArgIdx + 1] ? resolve(args[dirArgIdx + 1]) : process.cwd()
+const ALLOWLIST = '.stub-redirects-allowlist'
+
+// #1840 F4 tranche-3: '.venv'/'venv'/'__pycache__' — a Python dependency's
+// bundled test suite inside site-packages must never be scanned as project
+// code (mirrors lib/glob-walk.mjs's SKIP_DIRS).
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'coverage',
+  '.coverage',
+  '.venv',
+  'venv',
+  '__pycache__',
+])
+
+// A redirect VERB anchoring a stub. Matched against the leading non-empty lines of the doc.
+const REDIRECT_VERB_RE =
+  /\b(?:moved|relocated|renamed|has moved|now lives|see (?:instead|the new)|redirect(?:ed)? to)\b/i
+const MD_LINK_RE = /\[[^\]]*\]\(([^)]+\.md[^)]*)\)/g
+// A stub is "short": few non-trivial body words after stripping markdown punctuation.
+const SHORT_BODY_WORDS = 40
+
+function isStub(content) {
+  const lines = content.split('\n')
+  const nonEmpty = lines.map((l) => l.trim()).filter((l) => l.length > 0)
+  if (nonEmpty.length === 0) return false
+  // The redirect verb must appear in the first few lines (heading or lead paragraph).
+  const head = nonEmpty.slice(0, 4).join(' ')
+  if (!REDIRECT_VERB_RE.test(head)) return false
+  // Exactly one .md link in the whole body.
+  const links = [...content.matchAll(MD_LINK_RE)]
+  if (links.length !== 1) return false
+  // Short body: count words excluding markdown link/heading punctuation.
+  const words = content
+    .replace(MD_LINK_RE, ' ')
+    .replace(/[#>*_`[\]()]/g, ' ')
+    .split(/\s+/)
+    .filter((w) => w.length > 0)
+  return words.length <= SHORT_BODY_WORDS
+}
+
+/** Parse the allowlist into { relPath → { expires: Date|null } }. */
+function loadAllowlist() {
+  const abs = join(ROOT, ALLOWLIST)
+  if (!existsSync(abs)) return new Map()
+  const map = new Map()
+  for (const raw of readFileSync(abs, 'utf-8').split('\n')) {
+    const line = raw.replace(/#.*$/, '').trim()
+    if (line.length === 0) continue
+    const m = /^(\S+)\s*(?:EXPIRES:\s*(\d{4}-\d{2}-\d{2}))?\s*$/.exec(line)
+    if (!m) continue
+    const expires = m[2] ? new Date(m[2] + 'T00:00:00Z') : null
+    map.set(m[1].replace(/\\/g, '/'), { expires, raw: line })
+  }
+  return map
+}
+
+function collectMd(dir, acc) {
+  let entries
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry)) continue
+    const full = join(dir, entry)
+    let st
+    try {
+      st = statSync(full)
+    } catch {
+      continue
+    }
+    if (st.isDirectory()) collectMd(full, acc)
+    else if (entry.endsWith('.md')) acc.push(full)
+  }
+}
+
+function main() {
+  const allow = loadAllowlist()
+  const now = Date.now()
+  const files = []
+  collectMd(ROOT, files)
+
+  const violations = []
+  for (const file of files) {
+    let content
+    try {
+      content = readFileSync(file, 'utf-8')
+    } catch {
+      continue
+    }
+    if (!isStub(content)) continue
+    const rel = relative(ROOT, file).replace(/\\/g, '/')
+    const entry = allow.get(rel)
+    if (entry) {
+      if (entry.expires === null || Number.isNaN(entry.expires.getTime())) {
+        violations.push(`  ${rel}: allowlisted but missing a valid EXPIRES: YYYY-MM-DD date`)
+      } else if (entry.expires.getTime() < now) {
+        violations.push(`  ${rel}: allowlist EXPIRES ${entry.raw} has lapsed — remove the stub`)
+      }
+      // else: future EXPIRES → permitted, no violation.
+      continue
+    }
+    violations.push(`  ${rel}: stale "Moved →" stub (redirect husk) — restore content or delete`)
+  }
+
+  if (violations.length > 0) {
+    process.stderr.write(
+      `check-no-stub-redirects: ${violations.length} stub redirect(s) — a redirect husk is a fake-green:\n`,
+    )
+    for (const v of violations) process.stderr.write(v + '\n')
+    return 1
+  }
+  process.stdout.write(`check-no-stub-redirects: OK — ${files.length} .md file(s), no stub husks\n`)
+  return 0
+}
+
+try {
+  process.exit(main())
+} catch (e) {
+  process.stderr.write(`check-no-stub-redirects: ERROR — ${e?.message ?? e}\n`)
+  process.exit(2)
+}