@syncerauk/test-rules 1.0.6 → 1.0.7

package/README.md

@@ -37,6 +37,7 @@ relisted: [{ file, rule, at }] }`.
 | `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 |
+| `T4:pin` | A `pins` entry that does not hold (judged on the config, never listed) |
 | `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 |
@@ -52,6 +53,7 @@ Both in the repo's `scripts/test-rules/`:
   `ignore` (which files are test files), `fixtures` (folders a test may read), `wording` (the
   one list of what a person reads), `style_contract` (`{ "<test file>": ["<.css or .scss path or
   glob>"] }`: the one test that may read those stylesheets; style rules are checked there, once),
+  `pins` (the kept pins, below),
   `reads` (the reads register: `"comment"`, or
   `{ "json": "<path>" }` for the map under `"tests"` in that file, `"key": "<name>"` for another
   key, `"key": null` when the file itself is the map). The defaults are `CONFIG_DEFAULTS` in the
@@ -60,6 +62,28 @@ Both in the repo's `scripts/test-rules/`:
   `test-rules --init`. An optional `moved` map, `{ "<new test file>": "<old test file>" }`,
   says where a split or a rename took a listed file.
 
+## Kept pins
+
+R4 allows a pin (a test that asserts on source text, a prompt or a document) only as a guard
+with a recorded mutation that turns it red, one per rule (Bernardo Cunha, 6 Nov 2026). The
+config registers each kept pin in `pins`:
+
+```json
+"pins": [
+  { "file": "<test file>", "rule": "<the rule it guards>",
+    "mutation": "<the change that turns it red>", "red_before": "<where that red is recorded>" }
+]
+```
+
+- A test file on `pins` is not a `T4:source-text` breach. It excuses T4 only, and only in that
+  file.
+- An entry fails the check (`T4:pin`, on the config) when it names no file or one that is not a
+  test file here, names no rule, names a rule another entry already pins (one pin per rule),
+  records no mutation or no `red_before`, or carries a key not above. An entry that fails
+  excuses nothing.
+- `T4:pin` is never listed. Registering a listed file makes its `T4:source-text` entry stale:
+  delete that line in the same change.
+
 ## The list only shrinks
 
 - A breach on the list passes. A breach off the list fails.
@@ -102,9 +126,15 @@ when the PR does not raise the version.
 | 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 |
+| 1.0.7 | `T4:pin`: a `pins` entry that does not hold (never listed, so never re-listed) |
 
 ## Versions
 
+- **1.0.7** — Kept pins: the config's `pins` list registers each pin R4 allows, with the rule it
+  guards and its recorded mutation; a file on it is not a `T4:source-text` breach, and an entry
+  that does not hold is `T4:pin`. Nothing changes for a repo that does not set it; an older
+  version refuses a config with `pins` (unknown key), so bump before you register one.
+
 - **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.

package/package.json

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

@@ -17,7 +17,8 @@
 // `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)
+//   scripts/test-rules/config.json   what differs between repos (CONFIG_DEFAULTS below); its
+//                                    `pins` list registers the kept pins (1.0.7, below)
 //   scripts/test-rules/listed.json   { v: 1, entries: { "<test file>": ["<rule id>", …] },
 //                                      moved: { "<new test file>": "<old test file>" } }
 // `moved` is optional: it says where a split or a rename took a listed file (1.0.5).
@@ -60,6 +61,10 @@
 //                   A JSON register is what a test says it reads; it does not stop the code
 //                   being read for what it does read (1.0.3). A stylesheet named for a test in
 //                   `style_contract` is not a breach in that test, and only in that test (1.0.4).
+//                   A test on the config's `pins` list is a kept pin (R4) and not a breach (1.0.7).
+//   T4:pin          a `pins` entry that does not hold: no test file, or one that is not a test
+//                   file here; no rule it guards, or a rule another entry already pins (one pin
+//                   per rule); no recorded mutation, or no record of its red-before (1.0.7)
 //   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,
@@ -96,6 +101,7 @@ export const CONFIG_DEFAULTS = Object.freeze({
   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
   style_contract: {}, // { "<test file>": ["<.css/.scss path or glob>", …] }: the one test that may read those stylesheets
+  pins: [], // [{ file, rule, mutation, red_before }]: the kept pins (R4), one per rule, each with the mutation that turns it red
   reads: null, // the reads register: null, "comment" (`// reads:` lines) or { json: "<path>", key: "tests" } (key null: the file itself is the map)
   source_ext: ['mjs', 'cjs', 'js', 'jsx', 'ts', 'tsx', 'mts', 'cts', 'sql', 'css', 'scss', 'html', 'sh', 'yml', 'yaml', 'md', 'mdx'],
   max_lines: 1500,
@@ -110,6 +116,7 @@ export const RULES = Object.freeze({
   '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)',
+  'T4:pin': 'a kept pin (R4) is the guard of one rule: its `pins` entry names the test file, the rule, the mutation that turns it red and where that red-before is recorded',
   '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',
@@ -117,7 +124,7 @@ export const RULES = Object.freeze({
   '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']);
+export const NEVER_LISTED = Object.freeze(['T1:hub', 'T4:pin', 'list:grew']);
 
 /**
  * Each way the check finds a breach: the rule it reports and the version that first found it,
@@ -125,7 +132,8 @@ export const NEVER_LISTED = Object.freeze(['T1:hub', 'list:grew']);
  * 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.
+ * nothing new), 1.0.5 (`moved`) and 1.0.6 (the re-list) add none. 1.0.7 adds T4:pin, which is
+ * judged on the config and never listed, so a re-list never carries it.
  */
 export const DETECTORS = Object.freeze({
   'T1:name': { rule: 'T1:name', since: '1.0.0' }, // the file named by task
@@ -137,6 +145,7 @@ export const DETECTORS = Object.freeze({
   '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
+  'T4:pin': { rule: 'T4:pin', since: '1.0.7' }, // a `pins` entry that does not hold (judged on the config, never listed)
   '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' },
@@ -378,6 +387,36 @@ function sourceTextLine({ path, text, code, bare, strings }, { config, register,
   return 0;
 }
 
+/**
+ * The pins register (1.0.7; R4, Bernardo Cunha, 6 Nov 2026: a pin is allowed only as a guard with
+ * a recorded mutation that turns it red, one per rule). `pins`: the config's list; `testPaths`: a
+ * Set of the repo's test files. → { pinned: Set of the test files a sound entry names, problems:
+ * [why each entry does not hold] }. An entry that does not hold excuses nothing, so a second entry
+ * for a rule that has its pin leaves its test a T4 breach.
+ */
+export function pinsOf(pins, testPaths) {
+  const pinned = new Set();
+  const problems = [];
+  const byRule = new Map();
+  const said = (v) => typeof v === 'string' && v.trim().length > 0;
+  (pins ?? []).forEach((pin, i) => {
+    const at = `pins[${i}]${said(pin.file) ? ` (${pin.file})` : ''}`;
+    const why = [];
+    if (!said(pin.file)) why.push('names no test file');
+    else if (!testPaths.has(pin.file)) why.push(`${pin.file} is not a test file in this repo`);
+    if (!said(pin.rule)) why.push('names no rule it guards');
+    else if (byRule.has(pin.rule.trim())) why.push(`"${pin.rule.trim()}" is already pinned by ${byRule.get(pin.rule.trim())}: one pin per rule`);
+    if (!said(pin.mutation)) why.push('records no mutation that turns it red');
+    if (!said(pin.red_before)) why.push('says not where its red-before is recorded');
+    const unknown = Object.keys(pin).filter((k) => !['file', 'rule', 'mutation', 'red_before'].includes(k));
+    if (unknown.length) why.push(`unknown key ${unknown.join(', ')}`);
+    if (said(pin.rule) && !byRule.has(pin.rule.trim())) byRule.set(pin.rule.trim(), at);
+    if (why.length) problems.push(`${at} ${why.join('; ')}`);
+    else pinned.add(pin.file);
+  });
+  return { pinned, problems };
+}
+
 /**
  * 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. `as`: a version
@@ -389,13 +428,16 @@ export function breachesOf({ files, config, register = null, tracked = null, as
   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));
+  // A kept pin is not a T4 breach; an entry that does not hold is one T4:pin on the config.
+  const pins = pinsOf(config.pins, new Set(files.map((f) => f.path)));
+  if (on('T4:pin') && pins.problems.length) out.push({ file: CONFIG_FILE, rule: 'T4:pin', line: 1, say: `${RULES['T4:pin']} (${pins.problems.join(' · ')})` });
   for (const { path, text } of files) {
     const view = { path, text, ...scan(text) };
     const base = path.split('/').pop();
     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);
+    if (t4 && !pins.pinned.has(path)) add(path, 'T4:source-text', t4);
     const faked = fakes.some((re) => re.test(view.bare));
     const timer = faked || !on('T6:timer') ? 0 : timerLine(view);
     if (timer) add(path, 'T6:timer', timer);
@@ -527,6 +569,9 @@ export function withDefaults(raw) {
   if (!sc || typeof sc !== 'object' || Array.isArray(sc) || Object.values(sc).some((v) => !Array.isArray(v) || !v.length || !v.every(styleOnly))) {
     throw fail(EXIT.FAILED, `${CONFIG_FILE}: style_contract must be { "<test file>": ["<path or glob ending .css or .scss>", …] }`);
   }
+  if (!Array.isArray(config.pins) || config.pins.some((p) => !p || typeof p !== 'object' || Array.isArray(p))) {
+    throw fail(EXIT.FAILED, `${CONFIG_FILE}: pins must be [{ "file": "<test file>", "rule": "<the rule it guards>", "mutation": "<what turns it red>", "red_before": "<where that red is recorded>" }, …]`);
+  }
   const r = config.reads;
   const json = r && typeof r === 'object' && !Array.isArray(r) && typeof r.json === 'string'
     && Object.keys(r).every((k) => k === 'json' || k === 'key') && (r.key === undefined || r.key === null || typeof r.key === 'string');