@syncerauk/test-rules 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @syncerauk/test-rules
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The static check of Syncera's test-writing rules: T1, T4, T6 and the line limit of R7 (adopted
+by Bernardo Cunha on 5 Nov 2026). One file, no dependency. It reads only the repo it runs in
+and git.
+
+## In a repo
+
+```bash
+npm install --save-dev --save-exact @syncerauk/test-rules
+```
+
+```json
+{ "scripts": { "gate:test-rules": "test-rules" } }
+```
+
+```bash
+npm run gate:test-rules
+npm run gate:test-rules -- --base origin/main --list
+```
+
+| Exit | Meaning |
+|---|---|
+| 0 | Clean, or the repo is still report only |
+| 1 | A breach off the list, a stale entry, or the list grew |
+| 2 | A bad command line |
+| 3 | The check could not run (no config, unreadable JSON, not a git worktree) |
+
+`--list` prints one JSON object: `{ v, breaches: [{ file, rule, line, say }], listed, stale }`.
+
+## The rules
+
+| Id | Breach |
+|---|---|
+| `T1:name` | A test file named by task |
+| `T1:hub` | A file listed as over the line limit grew against the base |
+| `R7:lines` | A test file over 1,500 lines |
+| `T4:source-text` | A test reads a source file as text |
+| `T6:timer` | A real wait, with no fake timers in the file |
+| `T6:clock` | The wall clock, with no fake timers in the file |
+| `T6:outside` | The home folder, a path that climbs out of the repo, a real host |
+| `T6:env` | `process.env.<NAME>` read and never set in the file |
+
+How each is seen is in the header of `test-rules.mjs`.
+
+## The repo's two files
+
+Both in the repo's `scripts/test-rules/`:
+
+- `config.json`: what differs between repos. `fail` (false is report only), `tests` and
+  `ignore` (which files are test files), `fixtures` (folders a test may read), `wording` (the
+  one list of what a person reads), `reads` (the reads register: `"comment"` or
+  `{ "json": "<path>" }`). The defaults are `CONFIG_DEFAULTS` in the script.
+- `listed.json`: the breaches the repo had on the day the check arrived. Written once by
+  `test-rules --init`.
+
+## The list only shrinks
+
+- A breach on the list passes. A breach off the list fails.
+- An entry whose breach is gone is stale and fails until its line is deleted.
+- Against a base, an entry the base's list does not hold fails. The base is `--base <ref>`,
+  else `origin/main` when it resolves.
+
+A repo starts with `"fail": false`: breaches are printed and the exit is 0. One line turns it on.
+
+## Releases
+
+The source is `scripts/test-rules.mjs` in Syncera-UK/syncera-orchestrator, where its tests run
+in the gate. A release is a version bump in this folder's `package.json`, merged, then the tag
+`test-rules-v<version>` on `main`.

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@syncerauk/test-rules",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "The static check of Syncera's test-writing rules (T1, T4, T6 and the line limit of R7). One file, no dependency. Published to npm by the orchestrator's publish-test-rules workflow; each repo pins an exact version.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Syncera-UK/syncera-orchestrator.git",
+    "directory": "scripts/test-rules-package"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "test-rules": "test-rules.mjs"
+  },
+  "files": [
+    "test-rules.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  }
+}

package/test-rules.mjs

@@ -0,0 +1,505 @@
+#!/usr/bin/env node
+// =============================================================================
+// test-rules.mjs — the static check of the test-writing rules (T7: T1, T4, T6 and the line half
+// of R7; docs/test-review/2026-11-05/RULES.md, adopted by Bernardo Cunha on 5 Nov 2026).
+//
+//   npm run gate:test-rules [-- --base <ref>] [--list]
+//   node scripts/test-rules.mjs [--dir <worktree>] [--base <ref> | --no-base] [--list] [--init]
+//
+// One implementation for the six repos (R8): one file, no dependency, no build; it imports
+// nothing from this repo and reads only the worktree and git, so another repo can run this same
+// file. Exit 0 clean, 1 a breach, 2 a bad command line, 3 the check itself could not run (no
+// config, unreadable JSON, not a git worktree, a --base that does not resolve).
+// `--list` prints one JSON object on one line and nothing else:
+//   { v: 1, breaches: [{ file, rule, line, say }], listed: <n>, stale: [{ file, rule }] }
+// `breaches` are the breaches that are not on the list; `listed` counts the ones that are.
+//
+// Per repo, two files:
+//   scripts/test-rules/config.json   what differs between repos (CONFIG_DEFAULTS below)
+//   scripts/test-rules/listed.json   { v: 1, entries: { "<test file>": ["<rule id>", …] } }
+//
+// The list only shrinks. A breach on the list passes; a breach off the list fails; an entry
+// whose breach is gone is `stale` and fails until its line is deleted; with a base, an entry the
+// base's list does not hold fails (`list:grew`), and a file listed under R7:lines that has more
+// lines than at the base fails (`T1:hub`). The base is `--base <ref>`, else origin/main when it
+// resolves (the merge base with HEAD is what is read); `--no-base` skips those two checks. The
+// base having no list at all is the one change that may add it (`--init` writes it once).
+// `"fail": false` in the config is report only: everything is printed, the exit is 0.
+//
+// The rules (RULES below) and how each is seen:
+//   T1:name         the file is named by task (w-184, fs-7-15, ops-3, s12)
+//   T1:hub          a file listed under R7:lines grew against the base
+//   R7:lines        more than `max_lines` lines (1,500). The 60 s half is tier 3's, not static.
+//   T4:source-text  the test reads a source file as text: a read it declares (the repo's reads
+//                   register) that is a source file or a folder and is neither under a fixture
+//                   folder nor on the wording list; a `?raw` import or a raw import.meta.glob;
+//                   and, where the register is comment lines or absent, a source file whose
+//                   path the test builds from its own place (new URL(…, import.meta.url), or
+//                   join( / resolve( on import.meta.dirname, __dirname, ROOT or HERE) in a test
+//                   that reads the file system and declares it neither `// reads:` nor
+//                   `// runs:` (a file that is only run is declared `// runs:`)
+//   T6:timer        setTimeout( / setInterval( / sleep( / timers/promises with no fake timers in the file
+//   T6:clock        Date.now( / new Date() / performance.now( with no fake timers in the file
+//   T6:outside      homedir(), process.env.HOME, a relative path that climbs out of the repo,
+//                   fetch( of a real host. A made-up absolute path handed to a pure function
+//                   is not a read and is not judged.
+//   T6:env          process.env.<NAME> read and never set in that file
+// Comments are never read; code patterns are never matched inside a string.
+// The config and the list are read by the command line only, and the check runs on every small
+// gate, so no test declares them.
+// =============================================================================
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const VERSION = 1;
+export const EXIT = Object.freeze({ CLEAN: 0, BREACH: 1, USAGE: 2, FAILED: 3 });
+export const CONFIG_FILE = 'scripts/test-rules/config.json';
+export const LISTED_FILE = 'scripts/test-rules/listed.json';
+export const DEFAULT_BASE = 'origin/main';
+const USAGE = 'usage: test-rules [--dir <worktree>] [--base <ref> | --no-base] [--list] [--init]';
+
+/** What a repo's scripts/test-rules/config.json may set; anything it leaves out is this. */
+export const CONFIG_DEFAULTS = Object.freeze({
+  v: VERSION,
+  fail: false, // report only until the repo's one-line PR sets it to true
+  tests: ['**/*.test.*', '**/*.spec.*'], // which tracked files are test files
+  ignore: [], // test files the rules do not judge (a real-time tier 3 suite)
+  fixtures: [], // folders a test may read: `a/fixtures/`
+  wording: [], // the one list of what a person reads (a built page, a legal text): files, globs, folders
+  reads: null, // the reads register: null, "comment" (`// reads:` lines) or { json: "<path>", key: "tests" }
+  source_ext: ['mjs', 'cjs', 'js', 'jsx', 'ts', 'tsx', 'mts', 'cts', 'sql', 'css', 'scss', 'html', 'sh', 'yml', 'yaml', 'md', 'mdx'],
+  max_lines: 1500,
+  task_names: ['(?:^|[^a-z0-9])w-?\\d+', '(?:^|[^a-z0-9])(?:fs|ops|trk|ci|app|leg|mig|bank|push|fun)-\\d+', '(?:^|[^a-z0-9])s\\d+(?:[^a-z0-9]|$)'],
+  fake_timers: ['useFakeTimers', 'mock\\.timers', '[fF]akeClock', '\\bclock\\.mjs\\b'],
+  env_allowed: ['PATH'], // process.env names a test may read without setting them (PATH: to find a binary)
+});
+
+/** Rule id → the one sentence that tells the builder what to do instead. */
+export const RULES = Object.freeze({
+  'T1:name': 'name the test file by its topic, never by the task that added it',
+  'T1:hub': 'this file is listed as over the line limit and it grew: the new test goes in a new file, by topic',
+  'R7:lines': 'over the line limit: split the file by topic',
+  'T4:source-text': 'a test does not open a source file and search it: run the code and assert on what it did (wording is checked once, from the wording list)',
+  'T6:timer': 'no real wait in a gated test: use the fake clock or fake timers',
+  'T6:clock': 'no wall clock in a gated test: pass a fixed time in, or use fake timers',
+  'T6:outside': 'nothing outside the commit: no home folder, machine path, path out of the repo or real host',
+  'T6:env': 'the machine\'s environment is not part of the commit: set the variable in the test, or pass the value in',
+  'list:grew': 'the list only shrinks: fix the breach, do not list it',
+});
+/** The rules a listed.json entry can never excuse. */
+export const NEVER_LISTED = Object.freeze(['T1:hub', 'list:grew']);
+
+const fail = (code, message) => Object.assign(new Error(message), { exit: code });
+
+// ---------------------------------------------------------------------------------------------
+// Globs: `*` within a path segment, `**` across segments, a trailing `/` is the folder and all
+// under it.
+// ---------------------------------------------------------------------------------------------
+const reCache = new Map();
+export function globRe(glob) {
+  if (reCache.has(glob)) return reCache.get(glob);
+  let g = String(glob);
+  if (g.endsWith('/')) g += '**';
+  let re = '';
+  for (let i = 0; i < g.length; i++) {
+    const c = g[i];
+    if (c === '*' && g[i + 1] === '*') {
+      if (g[i + 2] === '/') { re += '(?:.*/)?'; i += 2; } else { re += '.*'; i += 1; }
+    } else if (c === '*') re += '[^/]*';
+    else if (c === '?') re += '[^/]';
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  const out = new RegExp(`^${re}$`);
+  reCache.set(glob, out);
+  return out;
+}
+export const matches = (globs, path) => (globs ?? []).some((g) => globRe(g).test(path));
+/** The part of a pattern before its first wildcard: `api/**` → `api/`. */
+const literalHead = (pattern) => String(pattern).split(/[*?]/)[0];
+/** Whether a declared read (a path, a folder or a glob) lies wholly under one of `entries`. */
+export function under(entries, pattern) {
+  const head = literalHead(pattern);
+  return (entries ?? []).some((e) => {
+    if (globRe(e).test(pattern)) return true;
+    const folder = String(e).endsWith('/') ? e : String(e).endsWith('/**') ? String(e).slice(0, -2) : null;
+    return folder ? head.startsWith(folder) : false;
+  });
+}
+
+// ---------------------------------------------------------------------------------------------
+// scan: one pass over a source text. `code` has comments and the inside of every string and
+// regex blanked; `bare` has only comments blanked; both keep every offset and newline. `strings`
+// lists each string literal's inside with its start offset.
+// ---------------------------------------------------------------------------------------------
+const REGEX_AFTER = new Set(['', '(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';', '+', '-', '*', '%', '<', '>', '~', '^']);
+const REGEX_AFTER_WORD = new Set(['return', 'typeof', 'case', 'do', 'else', 'in', 'of', 'void', 'delete', 'throw', 'new', 'yield', 'await']);
+export function scan(text) {
+  const src = String(text);
+  const n = src.length;
+  const code = src.split('');
+  const bare = src.split('');
+  const strings = [];
+  const blank = (arr, a, b) => { for (let k = a; k < b; k++) if (arr[k] !== '\n') arr[k] = ' '; };
+  const regexMayStart = (i) => {
+    let k = i - 1;
+    while (k >= 0 && /\s/.test(code[k])) k--;
+    if (k < 0) return true;
+    if (/[\w$]/.test(code[k])) {
+      let s = k;
+      while (s > 0 && /[\w$]/.test(code[s - 1])) s--;
+      return REGEX_AFTER_WORD.has(code.slice(s, k + 1).join(''));
+    }
+    return REGEX_AFTER.has(code[k]);
+  };
+  let i = 0;
+  while (i < n) {
+    const c = src[i];
+    const d = src[i + 1];
+    if (c === '/' && d === '/') {
+      let j = src.indexOf('\n', i);
+      if (j < 0) j = n;
+      blank(code, i, j); blank(bare, i, j);
+      i = j;
+    } else if (c === '/' && d === '*') {
+      let j = src.indexOf('*/', i + 2);
+      j = j < 0 ? n : j + 2;
+      blank(code, i, j); blank(bare, i, j);
+      i = j;
+    } else if (c === '"' || c === "'" || c === '`') {
+      let j = i + 1;
+      while (j < n && src[j] !== c) {
+        if (src[j] === '\\') j++;
+        else if (c !== '`' && src[j] === '\n') break;
+        j++;
+      }
+      const end = Math.min(j, n);
+      strings.push({ start: i + 1, value: src.slice(i + 1, end) });
+      blank(code, i + 1, end);
+      i = end + 1;
+    } else if (c === '/' && regexMayStart(i)) {
+      let j = i + 1;
+      let cls = false;
+      while (j < n && src[j] !== '\n') {
+        const e = src[j];
+        if (e === '\\') { j += 2; continue; }
+        if (e === '[') cls = true;
+        else if (e === ']') cls = false;
+        else if (e === '/' && !cls) break;
+        j++;
+      }
+      if (j < n && src[j] === '/') { blank(code, i + 1, j); i = j + 1; } else i++;
+    } else i++;
+  }
+  return { code: code.join(''), bare: bare.join(''), strings };
+}
+export const lineOf = (text, index) => {
+  let line = 1;
+  for (let k = 0; k < index && k < text.length; k++) if (text.charCodeAt(k) === 10) line++;
+  return line;
+};
+const firstIndex = (text, re) => { const m = re.exec(text); return m ? m.index : -1; };
+
+// ---------------------------------------------------------------------------------------------
+// The reads register. Comment form: `// reads: a b` and `// runs: a b` on comment lines of their
+// own (the orchestrator's declared reads). JSON form: { <key>: { "<test>": ["<pattern>", …] } }.
+// ---------------------------------------------------------------------------------------------
+const DECLARED = /^[ \t]*\/\/[ \t]*(reads|runs):[ \t]*(\S.*)$/gm;
+export function declaredIn(text) {
+  const out = { reads: [], runs: [] };
+  for (const m of String(text).matchAll(DECLARED)) {
+    const line = lineOf(text, m.index);
+    for (const word of m[2].trim().split(/\s+/)) out[m[1]].push({ pattern: word, line });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------------------------
+// The per-file rules. Each returns the line of its first breach, or 0.
+// ---------------------------------------------------------------------------------------------
+const TIMER = /(?<![\w$.])(?:(?:globalThis|global|window|self)\.)?(?:setTimeout|setInterval|sleep)\s*\(/;
+const TIMERS_PROMISES = /['"`](?:node:)?timers\/promises['"`]/;
+const CLOCK = /\bDate\.now\s*\(|\bnew\s+Date\s*\(\s*\)|\bperformance\.now\s*\(/;
+const HOME = /\bhomedir\s*\(|\bprocess\.env\.HOME\b/;
+const FETCH = /(?<![\w$.])fetch\s*\(\s*(['"`])/g;
+const LOCAL_HOST = /^https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]|[^/:]*\.(?:test|localhost|invalid|example)|example\.(?:com|org|net))(?=[/:?#]|$)/i;
+const ENV_READ = /\bprocess\.env\.([A-Za-z_][A-Za-z0-9_]*)/g;
+const FS_READ = /\b(?:readFileSync|readFile|createReadStream|readdirSync|readdir|opendirSync)\s*\(/;
+const RAW_IMPORT = /(?:\bfrom|\bimport)\s*\(?\s*['"]([^'"\n]+)\?raw['"]/g;
+const RAW_GLOB = /\bimport\.meta\.glob\s*\(/g;
+const IMPORT_BEFORE = /(?:\bfrom|\bimport|\brequire)\s*\(?\s*$/;
+const BUILT_HERE = /\bnew\s+URL\s*\(\s*$|\b(?:join|resolve)\s*\([^;]*(?:\bimport\.meta\.(?:dirname|url|filename)|\b__dirname\b|\bROOT\b|\bHERE\b)[^;]*$/;
+
+function timerLine({ code, bare }) {
+  const a = firstIndex(code, TIMER);
+  const b = firstIndex(bare, TIMERS_PROMISES);
+  const at = [a, b].filter((x) => x >= 0).sort((x, y) => x - y)[0];
+  return at === undefined ? 0 : lineOf(code, at);
+}
+const clockLine = ({ code }) => { const at = firstIndex(code, CLOCK); return at < 0 ? 0 : lineOf(code, at); };
+
+function outsideLine({ path, code, bare, strings }) {
+  const hits = [];
+  const home = firstIndex(code, HOME);
+  if (home >= 0) hits.push(home);
+  const depth = path.split('/').length - 1;
+  for (const s of strings) {
+    const climb = /^((?:\.\.\/)+)[^\s]*$/.exec(s.value);
+    if (climb && climb[1].length / 3 > depth) hits.push(s.start);
+  }
+  for (const m of code.matchAll(FETCH)) {
+    const open = m.index + m[0].length;
+    const url = bare.slice(open, open + 200).split(m[1])[0];
+    if (/^https?:\/\//i.test(url) && !LOCAL_HOST.test(url)) hits.push(m.index);
+  }
+  return hits.length ? lineOf(code, Math.min(...hits)) : 0;
+}
+
+function envLine({ code, bare }, allowed) {
+  for (const m of code.matchAll(ENV_READ)) {
+    const name = m[1];
+    if (name === 'HOME' || allowed.includes(name)) continue; // HOME is T6:outside's
+    const set = new RegExp(`\\bprocess\\.env\\.${name}\\s*=(?!=)|\\bdelete\\s+process\\.env\\.${name}\\b|\\bstubEnv\\s*\\(\\s*['"\`]${name}['"\`]`);
+    if (!set.test(bare)) return lineOf(code, m.index);
+  }
+  return 0;
+}
+
+/** T4: the line of the first read of a source file as text, or 0. */
+function sourceTextLine({ path, text, code, bare, strings }, { config, register, tracked }) {
+  const isSource = (p) => config.source_ext.includes(String(p).split('.').pop().toLowerCase());
+  const allowed = (p) => under(config.fixtures, p) || under(config.wording, p);
+  const isFolderOrGlob = (p) => (/[*?]/.test(p) ? !/\.[A-Za-z0-9]+$/.test(p) || isSource(p) : String(p).endsWith('/'));
+  const offends = (p) => !allowed(p) && (isFolderOrGlob(p) || isSource(p));
+
+  const declared = declaredIn(text);
+  if (register && typeof register === 'object') {
+    if ((register[path] ?? []).some(offends)) return 1;
+  } else if (config.reads === 'comment') {
+    const hit = declared.reads.find((r) => offends(r.pattern));
+    if (hit) return hit.line;
+  }
+  for (const m of bare.matchAll(RAW_IMPORT)) {
+    if (code[m.index] === ' ') continue; // the words are inside a string, not an import
+    if (!allowed(posix.normalize(posix.join(posix.dirname(path), m[1])))) return lineOf(bare, m.index);
+  }
+  for (const m of code.matchAll(RAW_GLOB)) {
+    const call = bare.slice(m.index, m.index + 300).split(')')[0];
+    if (/\?raw|as\s*:\s*['"]raw['"]/.test(call)) return lineOf(code, m.index);
+  }
+  // A source file whose path the test builds from its own place, in a test that reads the file
+  // system, where no register says what the test reads: declared `// runs:` when it is only run.
+  if (register && typeof register === 'object') return 0;
+  if (!FS_READ.test(code) || !tracked) return 0;
+  const said = [...declared.reads, ...declared.runs].map((r) => r.pattern);
+  for (const s of strings) {
+    const v = s.value;
+    if (/[\s*?$]/.test(v) || !isSource(v)) continue;
+    const before = code.slice(code.lastIndexOf('\n', s.start) + 1, s.start - 1);
+    if (IMPORT_BEFORE.test(before) || !BUILT_HERE.test(before)) continue;
+    const here = posix.normalize(posix.join(posix.dirname(path), v));
+    const target = v.startsWith('.') || !tracked.has(v) ? here : v;
+    if (target === path || !tracked.has(target) || allowed(target)) continue;
+    if (said.some((p) => globRe(p).test(target))) continue;
+    return lineOf(code, s.start);
+  }
+  return 0;
+}
+
+/**
+ * Every breach in `files` (the repo's test files as { path, text }), one per file and rule, at
+ * its first line: [{ file, rule, line, say }], sorted. Pure: no disk, no git.
+ */
+export function breachesOf({ files, config, register = null, tracked = null }) {
+  const out = [];
+  const add = (file, rule, line) => out.push({ file, rule, line, say: RULES[rule] });
+  const names = config.task_names.map((s) => new RegExp(s, 'i'));
+  const fakes = config.fake_timers.map((s) => new RegExp(s));
+  for (const { path, text } of files) {
+    const view = { path, text, ...scan(text) };
+    const base = path.split('/').pop();
+    if (names.some((re) => re.test(base))) add(path, 'T1:name', 1);
+    if (countLines(text) > config.max_lines) add(path, 'R7:lines', config.max_lines + 1);
+    const t4 = sourceTextLine(view, { config, register, tracked });
+    if (t4) add(path, 'T4:source-text', t4);
+    const faked = fakes.some((re) => re.test(view.bare));
+    const timer = faked ? 0 : timerLine(view);
+    if (timer) add(path, 'T6:timer', timer);
+    const clock = faked ? 0 : clockLine(view);
+    if (clock) add(path, 'T6:clock', clock);
+    const outside = outsideLine(view);
+    if (outside) add(path, 'T6:outside', outside);
+    const env = envLine(view, config.env_allowed);
+    if (env) add(path, 'T6:env', env);
+  }
+  return out.sort((a, b) => a.file.localeCompare(b.file) || a.rule.localeCompare(b.rule));
+}
+
+/**
+ * The verdict over the breaches and the list. `listed`: the head's entries ({ file: [rule] }).
+ * `base`: null (no base read), or { listed: the base's entries or null when the base has no
+ * list, lines: { file: its line count at the base } }.
+ * → { breaches (off the list, plus T1:hub and list:grew), listed (count on the list), stale }.
+ */
+export function verdict({ all, listed = {}, base = null, lineCounts = {} }) {
+  const on = (file, rule) => (listed[file] ?? []).includes(rule) && !NEVER_LISTED.includes(rule);
+  const breaches = all.filter((b) => !on(b.file, b.rule));
+  const hits = all.filter((b) => on(b.file, b.rule));
+  const found = new Set(all.map((b) => `${b.file}\n${b.rule}`));
+  const stale = [];
+  for (const file of Object.keys(listed).sort()) {
+    for (const rule of [...listed[file]].sort()) if (!found.has(`${file}\n${rule}`)) stale.push({ file, rule });
+  }
+  if (base) {
+    for (const file of Object.keys(listed).sort()) {
+      for (const rule of [...listed[file]].sort()) {
+        if (base.listed && !(base.listed[file] ?? []).includes(rule)) breaches.push({ file, rule: 'list:grew', line: 1, say: `${rule}: ${RULES['list:grew']}` });
+      }
+      const was = base.lines?.[file];
+      if (listed[file].includes('R7:lines') && Number.isFinite(was) && lineCounts[file] > was) {
+        breaches.push({ file, rule: 'T1:hub', line: was + 1, say: `${RULES['T1:hub']} (${was} lines at the base, ${lineCounts[file]} now)` });
+      }
+    }
+  }
+  breaches.sort((a, b) => a.file.localeCompare(b.file) || a.rule.localeCompare(b.rule));
+  return { breaches, listed: hits.length, stale };
+}
+
+/** The entries a first list holds for these breaches: { file: [rule, …] }, sorted. */
+export function entriesFor(all) {
+  const entries = {};
+  for (const b of all) if (!NEVER_LISTED.includes(b.rule)) (entries[b.file] ??= []).push(b.rule);
+  for (const k of Object.keys(entries)) entries[k].sort();
+  return Object.fromEntries(Object.keys(entries).sort().map((k) => [k, entries[k]]));
+}
+export const listedText = (entries) => {
+  const rows = Object.keys(entries).map((k) => `    ${JSON.stringify(k)}: ${JSON.stringify(entries[k])}`);
+  return `{\n  "v": ${VERSION},\n  "entries": {${rows.length ? `\n${rows.join(',\n')}\n  ` : ''}}\n}\n`;
+};
+export function countLines(text) {
+  return text.length ? text.split('\n').length - (text.endsWith('\n') ? 1 : 0) : 0;
+}
+
+/** A config object with the defaults filled in; throws (exit 3) on a wrong shape. */
+export function withDefaults(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw fail(EXIT.FAILED, `${CONFIG_FILE}: not an object`);
+  const unknown = Object.keys(raw).filter((k) => !(k in CONFIG_DEFAULTS) && k !== '_');
+  if (unknown.length) throw fail(EXIT.FAILED, `${CONFIG_FILE}: unknown key ${unknown.join(', ')}`);
+  const config = { ...CONFIG_DEFAULTS, ...raw };
+  if (config.v !== VERSION) throw fail(EXIT.FAILED, `${CONFIG_FILE}: v must be ${VERSION}`);
+  if (typeof config.fail !== 'boolean') throw fail(EXIT.FAILED, `${CONFIG_FILE}: fail must be true or false`);
+  for (const k of ['tests', 'ignore', 'fixtures', 'wording', 'source_ext', 'task_names', 'fake_timers', 'env_allowed']) {
+    if (!Array.isArray(config[k]) || config[k].some((x) => typeof x !== 'string')) throw fail(EXIT.FAILED, `${CONFIG_FILE}: ${k} must be a list of strings`);
+  }
+  const r = config.reads;
+  if (!(r === null || r === 'comment' || (r && typeof r === 'object' && typeof r.json === 'string'))) throw fail(EXIT.FAILED, `${CONFIG_FILE}: reads must be null, "comment" or { "json": "<path>" }`);
+  return config;
+}
+
+// ---------------------------------------------------------------------------------------------
+// The command line: the only part that touches disk and git.
+// ---------------------------------------------------------------------------------------------
+export function parseArgs(argv) {
+  const o = { dir: null, base: null, noBase: false, list: false, init: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--list') o.list = true;
+    else if (a === '--init') o.init = true;
+    else if (a === '--no-base') o.noBase = true;
+    else if (a === '--help' || a === '-h') o.help = true;
+    else if (a === '--dir' || a === '--base') {
+      const v = argv[++i];
+      if (!v || v.startsWith('--')) throw fail(EXIT.USAGE, `${a} needs a value`);
+      o[a.slice(2)] = v;
+    } else throw fail(EXIT.USAGE, `unknown argument ${a}`);
+  }
+  if (o.base && o.noBase) throw fail(EXIT.USAGE, '--base and --no-base together');
+  return o;
+}
+
+const git = (dir, args) => execFileSync('git', args, { cwd: dir, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+const gitOr = (dir, args) => { try { return git(dir, args); } catch { return null; } };
+function readJson(dir, rel) {
+  let text;
+  try { text = readFileSync(join(dir, rel), 'utf8'); } catch { throw fail(EXIT.FAILED, `${rel}: cannot be read`); }
+  try { return JSON.parse(text); } catch (e) { throw fail(EXIT.FAILED, `${rel}: not JSON (${e.message})`); }
+}
+export function entriesOf(obj, where) {
+  const e = obj?.entries;
+  const ok = obj?.v === VERSION && e && typeof e === 'object' && !Array.isArray(e)
+    && Object.values(e).every((r) => Array.isArray(r) && r.every((x) => typeof x === 'string' && x in RULES && !NEVER_LISTED.includes(x)));
+  if (!ok) throw fail(EXIT.FAILED, `${where}: must be { "v": ${VERSION}, "entries": { "<test file>": ["<rule id>", …] } }`);
+  return e;
+}
+
+export function main(argv = [], { log = console.log, error = console.error } = {}) {
+  try {
+    const opts = parseArgs(argv);
+    if (opts.help) { log(USAGE); return EXIT.CLEAN; }
+    const dir = resolve(opts.dir ?? process.cwd());
+    if (gitOr(dir, ['rev-parse', '--show-toplevel']) === null) throw fail(EXIT.FAILED, `${dir}: not a git worktree`);
+    const config = withDefaults(readJson(dir, CONFIG_FILE));
+
+    const present = git(dir, ['ls-files', '-co', '--exclude-standard', '-z']).split('\0').filter((p) => p && existsSync(join(dir, p)));
+    const tracked = new Set(present);
+    const testPaths = present.filter((p) => !p.split('/').includes('node_modules') && matches(config.tests, p) && !matches(config.ignore, p)).sort();
+    const files = testPaths.map((path) => ({ path, text: readFileSync(join(dir, path), 'utf8') }));
+    const register = config.reads && typeof config.reads === 'object' ? (readJson(dir, config.reads.json)[config.reads.key ?? 'tests'] ?? {}) : null;
+    const all = breachesOf({ files, config, register, tracked });
+
+    if (opts.init) {
+      if (existsSync(join(dir, LISTED_FILE))) throw fail(EXIT.USAGE, `${LISTED_FILE} exists: the list is written once and only shrinks`);
+      mkdirSync(dirname(join(dir, LISTED_FILE)), { recursive: true });
+      writeFileSync(join(dir, LISTED_FILE), listedText(entriesFor(all)));
+      log(`test-rules: wrote ${LISTED_FILE} — ${all.length} breach(es) in ${new Set(all.map((b) => b.file)).size} of ${files.length} test files`);
+      return EXIT.CLEAN;
+    }
+
+    const listed = existsSync(join(dir, LISTED_FILE)) ? entriesOf(readJson(dir, LISTED_FILE), LISTED_FILE) : {};
+    let base = null;
+    let baseNote = 'no base';
+    if (!opts.noBase) {
+      const ref = opts.base ?? DEFAULT_BASE;
+      const mb = gitOr(dir, ['merge-base', ref, 'HEAD'])?.trim();
+      if (!mb && opts.base) throw fail(EXIT.FAILED, `--base ${ref}: no merge base with HEAD`);
+      if (mb) {
+        const text = gitOr(dir, ['show', `${mb}:${LISTED_FILE}`]);
+        let baseListed = null;
+        if (text !== null) {
+          let parsed;
+          try { parsed = JSON.parse(text); } catch (e) { throw fail(EXIT.FAILED, `${LISTED_FILE} at ${mb.slice(0, 12)}: not JSON (${e.message})`); }
+          baseListed = entriesOf(parsed, `${LISTED_FILE} at ${mb.slice(0, 12)}`);
+        }
+        const lines = {};
+        for (const file of Object.keys(listed)) {
+          if (!listed[file].includes('R7:lines')) continue;
+          const was = gitOr(dir, ['show', `${mb}:${file}`]);
+          if (was !== null) lines[file] = countLines(was);
+        }
+        base = { listed: baseListed, lines };
+        baseNote = `base ${mb.slice(0, 12)}${baseListed ? '' : ' (no list there)'}`;
+      } else baseNote = `no base (${ref} does not resolve)`;
+    }
+    const lineCounts = Object.fromEntries(files.map((f) => [f.path, countLines(f.text)]));
+    const v = verdict({ all, listed, base, lineCounts });
+
+    if (opts.list) {
+      log(JSON.stringify({ v: VERSION, breaches: v.breaches, listed: v.listed, stale: v.stale }));
+    } else {
+      for (const b of v.breaches) log(`${b.rule} ${b.file}:${b.line} — ${b.say}`);
+      for (const s of v.stale) log(`stale ${s.file} ${s.rule} — the breach is gone: delete it from ${LISTED_FILE}`);
+      log(`test-rules: ${files.length} test files, ${v.breaches.length} breach(es), ${v.listed} listed, ${v.stale.length} stale; ${baseNote}${config.fail ? '' : '; report only ("fail": false)'}`);
+    }
+    return config.fail && (v.breaches.length || v.stale.length) ? EXIT.BREACH : EXIT.CLEAN;
+  } catch (e) {
+    const code = e?.exit ?? EXIT.FAILED;
+    error(`test-rules: ${e?.message ?? e}`);
+    if (code === EXIT.USAGE) error(USAGE);
+    return code;
+  }
+}
+
+const real = (p) => { try { return realpathSync(p); } catch { return p; } };
+if (process.argv[1] && real(process.argv[1]) === real(fileURLToPath(import.meta.url))) process.exitCode = main(process.argv.slice(2));