@syncerauk/test-rules 1.0.5 → 1.0.6

package/README.md

@@ -26,7 +26,8 @@ npm run gate:test-rules -- --base origin/main --list
 | 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 }`.
+`--list` prints one JSON object: `{ v, breaches: [{ file, rule, line, say }], listed, stale,
+relisted: [{ file, rule, at }] }`.
 
 ## The rules
 
@@ -71,8 +72,43 @@ Both in the repo's `scripts/test-rules/`:
 
 A repo starts with `"fail": false`: breaches are printed and the exit is 0. One line turns it on.
 
+## Bumping the version: re-listed once per version
+
+A newer version can find breaches an older one missed, in files nobody touched (Bernardo Cunha,
+6 Nov 2026: re-list once per version). The PR that bumps the pin may add those entries to
+`listed.json`, and only those:
+
+- the PR raises the installed version: the base's is lower, and the version running is the one
+  installed (the lockfile, else an exact pin in `package.json`, read at the base through git);
+- the breach is found only by a detection newer than the base's version: the check runs a
+  second time as the base's version (the `DETECTORS` table in `test-rules.mjs` says which version
+  first found what) and only what that run does not find counts;
+- the PR does not change the file.
+
+Any other new entry is still `list:grew`. Allowed growth is printed (`re-listed at 1.0.6: N
+entries`, one `relisted` line each). Do not edit the list by hand: after the bump and
+`npm install`, run
+
+```bash
+npm run gate:test-rules -- --relist
+```
+
+It writes exactly the allowed entries into `listed.json` (keeping `moved`) and refuses (exit 2)
+when the PR does not raise the version.
+
+| Version | Detections it added |
+|---|---|
+| 1.0.0 | every rule: `T1:name`, `T1:hub`, `R7:lines`, `T4:source-text` (a declared read, a raw import, a source path built from the test's place), `T6:timer`, `T6:clock`, `T6:outside`, `T6:env` |
+| 1.0.1, 1.0.4, 1.0.5, 1.0.6 | none |
+| 1.0.2 | `T4:source-text`: a path that starts with a dot-folder; a JSON register that is the whole file |
+| 1.0.3 | `T4:source-text`: the built-path scan under a JSON register |
+
 ## Versions
 
+- **1.0.6** — Re-listed once per version: a PR that raises the installed version may add the
+  entries a newer detection finds in files it does not change; `--relist` writes them.
+  `--list` carries `relisted`. Nothing new is found.
+
 - **1.0.5** — A split or rename carries its listed breaches: `listed.json` may hold
   `"moved": { "<new test file>": "<old test file>" }`, and a new file's entry is not
   `list:grew` when the base listed the same rule on the old file and the old file is gone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncerauk/test-rules",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "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",

package/test-rules.mjs

@@ -4,15 +4,17 @@
 // 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]
+//   node scripts/test-rules.mjs [--dir <worktree>] [--base <ref> | --no-base] [--list] [--init | --relist]
 //
 // 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.
+//   { v: 1, breaches: [{ file, rule, line, say }], listed: <n>, stale: [{ file, rule }],
+//     relisted: [{ file, rule, at }] }
+// `breaches` are the breaches that are not on the list; `listed` counts the ones that are;
+// `relisted` is the growth a version bump may bring (below).
 //
 // Per repo, two files:
 //   scripts/test-rules/config.json   what differs between repos (CONFIG_DEFAULTS below)
@@ -30,6 +32,17 @@
 // `list:grew` when `moved` names its old file, the base listed that same rule on the old file,
 // and the old file is no longer a test file. A `moved` line is never stale and never a breach;
 // it may be deleted at any time.
+// Re-listed once per version (Bernardo Cunha, 6 Nov 2026, 1.0.6): a newer version can find
+// breaches an older one missed, in files nobody touched. An entry the base does not hold is not
+// `list:grew` when all three hold: (a) this change raises the installed version (the base's is
+// lower than the one running, and the one running is the one installed); (b) the breach is found
+// only by a detection newer than the base's version (DETECTORS below: the check is run a second
+// time as the base's version, and only what that run does not find counts); (c) the change does
+// not edit the file. Allowed growth is printed ("re-listed at <version>: N entries"), never
+// silent. `--relist` writes exactly those entries into the list, so nobody edits it by hand.
+// The version installed is read from the lockfile, else an exact pin in package.json (in the
+// folder that holds node_modules/@syncerauk/test-rules, then the repo root), else, in the
+// orchestrator, which runs this file itself, from scripts/test-rules-package/package.json.
 // `"fail": false` in the config is report only: everything is printed, the exit is 0.
 //
 // The rules (RULES below) and how each is seen:
@@ -55,12 +68,13 @@
 //   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.
+// gate, so no test declares them. Its own version is read from its manifest:
+// reads: scripts/test-rules-package/package.json
 // =============================================================================
 
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
-import { dirname, join, posix, resolve } from 'node:path';
+import { dirname, join, posix, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 export const VERSION = 1;
@@ -68,7 +82,10 @@ 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]';
+export const PACKAGE = '@syncerauk/test-rules';
+/** The package's manifest in the orchestrator, the repo that runs this file itself. */
+export const SOURCE_MANIFEST = 'scripts/test-rules-package/package.json';
+const USAGE = 'usage: test-rules [--dir <worktree>] [--base <ref> | --no-base] [--list] [--init | --relist]';
 
 /** What a repo's scripts/test-rules/config.json may set; anything it leaves out is this. */
 export const CONFIG_DEFAULTS = Object.freeze({
@@ -102,6 +119,40 @@ export const RULES = Object.freeze({
 /** The rules a listed.json entry can never excuse. */
 export const NEVER_LISTED = Object.freeze(['T1:hub', 'list:grew']);
 
+/**
+ * Each way the check finds a breach: the rule it reports and the version that first found it,
+ * from the git history of this file. `breachesOf({ as })` runs only the ones a version had, so a
+ * re-list can tell what a bump newly finds from what was there all along. A version that changes
+ * how a breach is found adds a row here, with its own `since`, and keeps the old behaviour
+ * behind it. 1.0.1 (the same file as 1.0.0), 1.0.4 (`style_contract`: it narrows T4 and finds
+ * nothing new), 1.0.5 (`moved`) and 1.0.6 (the re-list) add none.
+ */
+export const DETECTORS = Object.freeze({
+  'T1:name': { rule: 'T1:name', since: '1.0.0' }, // the file named by task
+  'T1:hub': { rule: 'T1:hub', since: '1.0.0' }, // a listed long file grew (judged against the base, never listed)
+  'R7:lines': { rule: 'R7:lines', since: '1.0.0' }, // over max_lines
+  'T4:declared': { rule: 'T4:source-text', since: '1.0.0' }, // a declared read (comment lines or the JSON register) of a source file, folder or glob
+  'T4:raw': { rule: 'T4:source-text', since: '1.0.0' }, // a `?raw` import or a raw import.meta.glob
+  'T4:built': { rule: 'T4:source-text', since: '1.0.0' }, // a source path built from the test's own place, undeclared, with no JSON register
+  'T4:dot-folder': { rule: 'T4:source-text', since: '1.0.2' }, // that path starting with a dot-folder (.github/…) is a repo path, not one beside the test
+  'T4:whole-register': { rule: 'T4:source-text', since: '1.0.2' }, // a JSON register that is the whole file ("key": null) is read, not taken as empty
+  'T4:built-under-json': { rule: 'T4:source-text', since: '1.0.3' }, // the built-path scan runs under a JSON register too
+  'T6:timer': { rule: 'T6:timer', since: '1.0.0' },
+  'T6:clock': { rule: 'T6:clock', since: '1.0.0' },
+  'T6:outside': { rule: 'T6:outside', since: '1.0.0' },
+  'T6:env': { rule: 'T6:env', since: '1.0.0' },
+});
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+/** -1, 0 or 1 for two x.y.z versions. */
+export function compareVersions(a, b) {
+  const x = String(a).split('.').map(Number);
+  const y = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+  return 0;
+}
+/** Whether version `as` had detector `id` (no `as`: this version, every detector). */
+export const detects = (id, as = null) => !as || compareVersions(DETECTORS[id].since, as) <= 0;
+
 const fail = (code, message) => Object.assign(new Error(message), { exit: code });
 
 // ---------------------------------------------------------------------------------------------
@@ -279,7 +330,8 @@ function envLine({ code, bare }, allowed) {
 }
 
 /** 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 }) {
+function sourceTextLine({ path, text, code, bare, strings }, { config, register, tracked, as }) {
+  const on = (id) => detects(id, as);
   const isSource = (p) => config.source_ext.includes(String(p).split('.').pop().toLowerCase());
   // A style contract is the one test that may read the stylesheets it names: style rules are
   // checked once, there, the way wording is checked once from the wording list.
@@ -288,23 +340,25 @@ function sourceTextLine({ path, text, code, bare, strings }, { config, register,
   const offends = (p) => !allowed(p) && (isFolderOrGlob(p) || isSource(p));
 
   const declared = declaredIn(text);
-  if (register && typeof register === 'object') {
+  const json = register && typeof register === 'object';
+  if (on('T4:declared') && json) {
     if ((register[path] ?? []).some(offends)) return 1;
-  } else if (config.reads === 'comment') {
+  } else if (on('T4:declared') && 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)) {
+  for (const m of on('T4:raw') ? 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)) {
+  for (const m of on('T4:raw') ? 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, that the test does not declare: `// runs:` when it is only run. A JSON register does
-  // not silence this: a register can miss a read, and a source file it names returned above.
+  // not silence this (1.0.3): a register can miss a read, and a source file it names returned above.
+  if (!on('T4:built') || (json && !on('T4:built-under-json'))) 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) {
@@ -312,9 +366,11 @@ function sourceTextLine({ path, text, code, bare, strings }, { config, register,
     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;
-    // `./x` and `../x` are relative to the test; `.github/x` is a repo path like any other.
+    // `./x` and `../x` are relative to the test; `.github/x` is a repo path like any other (1.0.2;
+    // before it, any leading dot was read as beside the test).
     const here = posix.normalize(posix.join(posix.dirname(path), v));
-    const target = v.startsWith('./') || v.startsWith('../') || !tracked.has(v) ? here : v;
+    const besideTest = on('T4:dot-folder') ? v.startsWith('./') || v.startsWith('../') : v.startsWith('.');
+    const target = besideTest || !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);
@@ -324,28 +380,30 @@ function sourceTextLine({ path, text, code, bare, strings }, { config, register,
 
 /**
  * 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.
+ * its first line: [{ file, rule, line, say }], sorted. Pure: no disk, no git. `as`: a version
+ * (x.y.z) to run only the detectors it had (DETECTORS), for the re-list; null runs them all.
  */
-export function breachesOf({ files, config, register = null, tracked = null }) {
+export function breachesOf({ files, config, register = null, tracked = null, as = null }) {
   const out = [];
   const add = (file, rule, line) => out.push({ file, rule, line, say: RULES[rule] });
+  const on = (id) => detects(id, as);
   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 (on('T1:name') && names.some((re) => re.test(base))) add(path, 'T1:name', 1);
+    if (on('R7:lines') && countLines(text) > config.max_lines) add(path, 'R7:lines', config.max_lines + 1);
+    const t4 = sourceTextLine(view, { config, register, tracked, as });
     if (t4) add(path, 'T4:source-text', t4);
     const faked = fakes.some((re) => re.test(view.bare));
-    const timer = faked ? 0 : timerLine(view);
+    const timer = faked || !on('T6:timer') ? 0 : timerLine(view);
     if (timer) add(path, 'T6:timer', timer);
-    const clock = faked ? 0 : clockLine(view);
+    const clock = faked || !on('T6:clock') ? 0 : clockLine(view);
     if (clock) add(path, 'T6:clock', clock);
-    const outside = outsideLine(view);
+    const outside = on('T6:outside') ? outsideLine(view) : 0;
     if (outside) add(path, 'T6:outside', outside);
-    const env = envLine(view, config.env_allowed);
+    const env = on('T6:env') ? envLine(view, config.env_allowed) : 0;
     if (env) add(path, 'T6:env', env);
   }
   return out.sort((a, b) => a.file.localeCompare(b.file) || a.rule.localeCompare(b.rule));
@@ -358,9 +416,13 @@ export function breachesOf({ files, config, register = null, tracked = null }) {
  * `moved`: { new file: old file } from the head's list. `present`: a Set of the head's test
  * files, or null (then nothing is carried). An entry the base does not hold is carried, not
  * `list:grew`, when its old file is gone and the base listed the same rule on it.
- * → { breaches (off the list, plus T1:hub and list:grew), listed (count on the list), stale }.
+ * `relist`: null, or { from, at, allowed: Set of "file\nrule", changed: Set of files } from
+ * relistable (a version bump): an entry the base does not hold and `allowed` has is re-listed,
+ * not `list:grew`.
+ * → { breaches (off the list, plus T1:hub and list:grew), listed (count on the list), stale,
+ *     relisted: [{ file, rule, at }] }.
  */
-export function verdict({ all, listed = {}, base = null, lineCounts = {}, moved = {}, present = null }) {
+export function verdict({ all, listed = {}, base = null, lineCounts = {}, moved = {}, present = null, relist = null }) {
   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));
@@ -373,10 +435,16 @@ export function verdict({ all, listed = {}, base = null, lineCounts = {}, moved
     const old = Object.hasOwn(moved, file) ? moved[file] : null;
     return typeof old === 'string' && present !== null && !present.has(old) && (base.listed?.[old] ?? []).includes(rule);
   };
+  const relisted = [];
+  const why = (file) => !relist ? ''
+    : relist.changed.has(file) ? ` (a re-list at ${relist.at} never covers a file this change edits)`
+      : ` (a re-list at ${relist.at} covers only what ${relist.at} finds and ${relist.from} did not)`;
   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) && !carried(file, rule)) breaches.push({ file, rule: 'list:grew', line: 1, say: `${rule}: ${RULES['list:grew']}` });
+        if (!base.listed || (base.listed[file] ?? []).includes(rule) || carried(file, rule)) continue;
+        if (relist?.allowed.has(`${file}\n${rule}`)) relisted.push({ file, rule, at: relist.at });
+        else breaches.push({ file, rule: 'list:grew', line: 1, say: `${rule}: ${RULES['list:grew']}${why(file)}` });
       }
       const was = base.lines?.[file];
       if (listed[file].includes('R7:lines') && Number.isFinite(was) && lineCounts[file] > was) {
@@ -385,7 +453,33 @@ export function verdict({ all, listed = {}, base = null, lineCounts = {}, moved
     }
   }
   breaches.sort((a, b) => a.file.localeCompare(b.file) || a.rule.localeCompare(b.rule));
-  return { breaches, listed: hits.length, stale };
+  return { breaches, listed: hits.length, stale, relisted };
+}
+
+/**
+ * Whether this change may re-list, from the versions: `from` the base's installed version,
+ * `installed` the worktree's, `running` this file's own. → { open, from, at, why }: open only
+ * when all three are known, the one running is the one installed, and it is newer than the base's.
+ */
+export function relistGate({ from, installed, running }) {
+  const shut = (why) => ({ open: false, from, at: running, why });
+  if (!running) return shut(`this file's own version cannot be read`);
+  if (!from) return shut(`the base's ${PACKAGE} version cannot be read`);
+  if (!installed) return shut(`the installed ${PACKAGE} version cannot be read`);
+  if (installed !== running) return shut(`${running} is running but ${installed} is installed`);
+  if (compareVersions(from, running) >= 0) return shut(`the version did not go up (${from} at the base, ${running} here)`);
+  return { open: true, from, at: running, why: '' };
+}
+
+/**
+ * The entries a bump may re-list: "file\nrule" for each breach in `all` (this version's) that
+ * `asBase` (the same files, run as the base's version) does not hold, on a file `changed` (the
+ * files this change touches) does not hold. Pure.
+ */
+export function relistable({ all, asBase, changed }) {
+  const key = (b) => `${b.file}\n${b.rule}`;
+  const before = new Set(asBase.map(key));
+  return new Set(all.filter((b) => !NEVER_LISTED.includes(b.rule) && !changed.has(b.file) && !before.has(key(b))).map(key));
 }
 
 /** The entries a first list holds for these breaches: { file: [rule, …] }, sorted. */
@@ -395,10 +489,24 @@ export function entriesFor(all) {
   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`;
+/** The list as written: one line per file; `moved`, when it has lines, after the entries. */
+export const listedText = (entries, moved = {}) => {
+  const block = (map) => {
+    const rows = Object.keys(map).map((k) => `    ${JSON.stringify(k)}: ${JSON.stringify(map[k])}`);
+    return `{${rows.length ? `\n${rows.join(',\n')}\n  ` : ''}}`;
+  };
+  return `{\n  "v": ${VERSION},\n  "entries": ${block(entries)}${Object.keys(moved).length ? `,\n  "moved": ${block(moved)}` : ''}\n}\n`;
 };
+/** `entries` with each "file\nrule" of `keys` added, sorted as the first list is. */
+export function withEntries(entries, keys) {
+  const out = Object.fromEntries(Object.entries(entries).map(([f, r]) => [f, [...r]]));
+  for (const k of keys) {
+    const [file, rule] = k.split('\n');
+    if (!(out[file] ??= []).includes(rule)) out[file].push(rule);
+  }
+  for (const f of Object.keys(out)) out[f].sort();
+  return Object.fromEntries(Object.keys(out).sort().map((f) => [f, out[f]]));
+}
 export function countLines(text) {
   return text.length ? text.split('\n').length - (text.endsWith('\n') ? 1 : 0) : 0;
 }
@@ -431,7 +539,9 @@ export function withDefaults(raw) {
  * named), or the whole file when the key is null or empty. No map there cannot run (exit 3): an
  * empty register would read as "no test reads anything".
  */
-export function registerOf(file, reads) {
+export function registerOf(file, reads, as = null) {
+  // Before 1.0.2 a key of null or "" fell back to "tests", and no map there read as empty.
+  if (!detects('T4:whole-register', as)) return file?.[reads.key ?? 'tests'] ?? {};
   const key = reads.key === undefined ? 'tests' : reads.key;
   const whole = key === null || key === '';
   const map = whole ? file : file?.[key];
@@ -444,11 +554,12 @@ export function registerOf(file, reads) {
 // 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 };
+  const o = { dir: null, base: null, noBase: false, list: false, init: false, relist: 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 === '--relist') o.relist = true;
     else if (a === '--no-base') o.noBase = true;
     else if (a === '--help' || a === '-h') o.help = true;
     else if (a === '--dir' || a === '--base') {
@@ -458,9 +569,50 @@ export function parseArgs(argv) {
     } else throw fail(EXIT.USAGE, `unknown argument ${a}`);
   }
   if (o.base && o.noBase) throw fail(EXIT.USAGE, '--base and --no-base together');
+  if (o.relist && o.init) throw fail(EXIT.USAGE, '--relist and --init together');
+  if (o.relist && o.noBase) throw fail(EXIT.USAGE, '--relist needs a base: it re-lists against the base\'s version');
   return o;
 }
 
+// ---------------------------------------------------------------------------------------------
+// Versions. `read(rel)` gives a file's text, or null: at the base through git, here from disk.
+// ---------------------------------------------------------------------------------------------
+const jsonOrNull = (text) => { if (text == null) return null; try { return JSON.parse(text); } catch { return null; } };
+const exact = (v) => (typeof v === 'string' && SEMVER.test(v) ? v : null);
+/**
+ * The installed version of the package: for each folder in `prefixes` ('' is the repo root), its
+ * package-lock.json, else an exact pin in its package.json; else the orchestrator's own manifest
+ * (SOURCE_MANIFEST). null when none says.
+ */
+export function installedVersion(read, prefixes = ['']) {
+  for (const p of prefixes) {
+    const lock = jsonOrNull(read(`${p}package-lock.json`));
+    const locked = exact(lock?.packages?.[`node_modules/${PACKAGE}`]?.version) ?? exact(lock?.dependencies?.[PACKAGE]?.version);
+    if (locked) return locked;
+    const manifest = jsonOrNull(read(`${p}package.json`));
+    const pinned = exact(manifest?.devDependencies?.[PACKAGE]) ?? exact(manifest?.dependencies?.[PACKAGE]);
+    if (pinned) return pinned;
+  }
+  const own = jsonOrNull(read(SOURCE_MANIFEST));
+  return own?.name === PACKAGE ? exact(own.version) : null;
+}
+/** The folders to read the installed version from: the one that holds node_modules/<PACKAGE> when this file runs from there, then the root. */
+export function installPrefixes(dir, modulePath) {
+  const rel = relative(real(dir), real(modulePath)).split(sep).join('/');
+  const at = rel.startsWith('../') ? -1 : rel.indexOf(`node_modules/${PACKAGE}/`);
+  return at > 0 ? [rel.slice(0, at), ''] : [''];
+}
+/** This file's own version: the manifest beside it (as published), else the orchestrator's package folder. */
+export function ownVersion(modulePath = fileURLToPath(import.meta.url)) {
+  for (const rel of ['package.json', 'test-rules-package/package.json']) {
+    let manifest = null;
+    try { manifest = jsonOrNull(readFileSync(join(dirname(modulePath), rel), 'utf8')); } catch { /* not there */ }
+    if (manifest?.name === PACKAGE && exact(manifest.version)) return manifest.version;
+  }
+  return null;
+}
+
+const real = (p) => { try { return realpathSync(p); } catch { return p; } };
 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) {
@@ -485,7 +637,11 @@ export function movedOf(obj, where) {
   return m;
 }
 
-export function main(argv = [], { log = console.log, error = console.error } = {}) {
+/**
+ * The command line. `running`: this file's version (default: read from its manifest); `modulePath`:
+ * where this file is, to find the folder it is installed in. Both are for tests.
+ */
+export function main(argv = [], { log = console.log, error = console.error, running = undefined, modulePath = fileURLToPath(import.meta.url) } = {}) {
   try {
     const opts = parseArgs(argv);
     if (opts.help) { log(USAGE); return EXIT.CLEAN; }
@@ -497,7 +653,8 @@ export function main(argv = [], { log = console.log, error = console.error } = {
     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' ? registerOf(readJson(dir, config.reads.json), config.reads) : null;
+    const registerFile = config.reads && typeof config.reads === 'object' ? readJson(dir, config.reads.json) : null;
+    const register = registerFile ? registerOf(registerFile, config.reads) : null;
     const all = breachesOf({ files, config, register, tracked });
 
     if (opts.init) {
@@ -513,6 +670,8 @@ export function main(argv = [], { log = console.log, error = console.error } = {
     const moved = listedJson ? movedOf(listedJson, LISTED_FILE) : {};
     let base = null;
     let baseNote = 'no base';
+    let relist = null;
+    let gate = null;
     if (!opts.noBase) {
       const ref = opts.base ?? DEFAULT_BASE;
       const mb = gitOr(dir, ['merge-base', ref, 'HEAD'])?.trim();
@@ -533,16 +692,53 @@ export function main(argv = [], { log = console.log, error = console.error } = {
         }
         base = { listed: baseListed, lines };
         baseNote = `base ${mb.slice(0, 12)}${baseListed ? '' : ' (no list there)'}`;
+
+        // Re-listed once per version: only when this change raises the installed version.
+        const prefixes = installPrefixes(dir, modulePath);
+        gate = relistGate({
+          from: installedVersion((rel) => gitOr(dir, ['show', `${mb}:${rel}`]), prefixes),
+          installed: installedVersion((rel) => { try { return readFileSync(join(dir, rel), 'utf8'); } catch { return null; } }, prefixes),
+          running: running === undefined ? ownVersion(modulePath) : running,
+        });
+        if (gate.open) {
+          const changed = new Set([
+            ...git(dir, ['diff', '--name-only', '--no-renames', '-z', mb]).split('\0'),
+            ...git(dir, ['ls-files', '-o', '--exclude-standard', '-z']).split('\0'),
+          ].filter(Boolean));
+          const asBase = breachesOf({ files, config, register: registerFile ? registerOf(registerFile, config.reads, gate.from) : null, tracked, as: gate.from });
+          relist = { from: gate.from, at: gate.at, changed, allowed: relistable({ all, asBase, changed }) };
+          baseNote += `; ${PACKAGE} ${gate.from} → ${gate.at}`;
+        } else if (gate.from && gate.from !== gate.at) baseNote += `; no re-list (${gate.why})`;
       } else baseNote = `no base (${ref} does not resolve)`;
     }
+
+    if (opts.relist) {
+      if (!base) throw fail(EXIT.USAGE, `--relist needs a base: ${baseNote}`);
+      if (!base.listed) throw fail(EXIT.USAGE, `the base has no ${LISTED_FILE}: write the first list with --init`);
+      if (!relist) throw fail(EXIT.USAGE, `nothing may be re-listed: ${gate.why}`);
+      const on = (b) => (listed[b.file] ?? []).includes(b.rule);
+      const add = all.filter((b) => !on(b) && relist.allowed.has(`${b.file}\n${b.rule}`)).map((b) => `${b.file}\n${b.rule}`);
+      if (!add.length) {
+        log(`test-rules: nothing to re-list at ${relist.at} (the base ran ${relist.from})`);
+        return EXIT.CLEAN;
+      }
+      mkdirSync(dirname(join(dir, LISTED_FILE)), { recursive: true });
+      writeFileSync(join(dir, LISTED_FILE), listedText(withEntries(listed, add), moved));
+      for (const k of add) log(`relisted ${k.replace('\n', ' ')}`);
+      log(`test-rules: re-listed at ${relist.at}: ${add.length} entries, written to ${LISTED_FILE} (the base ran ${relist.from})`);
+      return EXIT.CLEAN;
+    }
+
     const lineCounts = Object.fromEntries(files.map((f) => [f.path, countLines(f.text)]));
-    const v = verdict({ all, listed, base, lineCounts, moved, present: new Set(testPaths) });
+    const v = verdict({ all, listed, base, lineCounts, moved, present: new Set(testPaths), relist });
 
     if (opts.list) {
-      log(JSON.stringify({ v: VERSION, breaches: v.breaches, listed: v.listed, stale: v.stale }));
+      log(JSON.stringify({ v: VERSION, breaches: v.breaches, listed: v.listed, stale: v.stale, relisted: v.relisted }));
     } 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}`);
+      for (const r of v.relisted) log(`relisted ${r.file} ${r.rule} — a detection newer than the base's ${relist.from} finds it`);
+      if (v.relisted.length) log(`test-rules: re-listed at ${relist.at}: ${v.relisted.length} entries`);
       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;
@@ -554,5 +750,4 @@ export function main(argv = [], { log = console.log, error = console.error } = {
   }
 }
 
-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));