@syncerauk/test-rules 1.0.8 → 1.0.9

package/README.md

@@ -56,7 +56,8 @@ Both in the repo's `scripts/test-rules/`:
   `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
+  key, `"key": null` when the file itself is the map; `"runs": "<name>"` (1.0.9) names a second
+  map in that file of what each test only runs). 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`. An optional `moved` map, `{ "<new test file>": "<old test file>" }`,
@@ -123,7 +124,7 @@ 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.1, 1.0.4, 1.0.5, 1.0.6, 1.0.9 | 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) |
@@ -131,6 +132,14 @@ when the PR does not raise the version.
 
 ## Versions
 
+- **1.0.9** — Run, not read, under a JSON register: a register row the test also names as run
+  is not a `T4:source-text` breach. A test says what it runs on a `// runs:` line, as the
+  comment-form repos already do, or in the register file's runs map, named by
+  `"reads": { …, "runs": "<name>" }`. That covers a script the test runs, the migrations it
+  replays, or a checker's input paths (TESTING.md, 6 Nov 2026). A runs-map row also declares a
+  built path, as a `// runs:` line does. `**` covers nothing; a missing or malformed runs map
+  that the config names cannot run (exit 3). It only drops breaches: listed entries it clears come off
+  the list in the PR that bumps the pin.
 - **1.0.8** — Reads made through a helper: a source path a test hands to a helper that reads
   the file system at that argument is a `T4:source-text` read, as a `readFileSync` in the test
   is. A helper is a function of the test's own or one the test imports by a relative path

package/package.json

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

@@ -64,6 +64,9 @@
 //                   A test on the config's `pins` list is a kept pin (R4) and not a breach (1.0.7).
 //                   A source path the test hands to a helper of its own or of the repo's, at a
 //                   parameter the helper reads the file system at, is a read too (1.0.8; below).
+//                   A JSON register row the test also names as run (a `// runs:` line, or the
+//                   register's `runs` map) is run, not read, and is not a breach; `**` covers
+//                   nothing (1.0.9).
 //   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)
@@ -104,7 +107,7 @@ export const CONFIG_DEFAULTS = Object.freeze({
   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)
+  reads: null, // the reads register: null, "comment" (`// reads:` lines) or { json: "<path>", key: "tests", runs: "runs" } (key null: the file itself is the map; runs, 1.0.9: the map of what each test only runs)
   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]|$)'],
@@ -605,7 +608,7 @@ function helperArgsOf(path, view, ctx) {
 }
 
 /** T4: the line of the first read of a source file as text, or 0. */
-function sourceTextLine(view, { config, register, tracked, as, helpers }) {
+function sourceTextLine(view, { config, register, runs = null, tracked, as, helpers }) {
   const { path, text, code, bare, strings } = view;
   const on = (id) => detects(id, as);
   const isSource = (p) => config.source_ext.includes(String(p).split('.').pop().toLowerCase());
@@ -617,8 +620,15 @@ function sourceTextLine(view, { config, register, tracked, as, helpers }) {
 
   const declared = declaredIn(text);
   const json = register && typeof register === 'object';
+  const wide = (p) => /^\*\*\/?$/.test(p); // `**`: the whole repo is never "run"
+  const mapped = (runs?.[path] ?? []).filter((p) => !wide(p));
+  const ran = [...declared.runs.map((r) => r.pattern).filter((p) => !wide(p)), ...mapped];
   if (on('T4:declared') && json) {
-    if ((register[path] ?? []).some(offends)) return 1;
+    // A register row the test also names as run, on a `// runs:` line or in the register's runs
+    // map, is run, not read as text (1.0.9): a script it runs, migrations it replays, or a
+    // checker's inputs (TESTING.md, 6 Nov), never the whole repo.
+    const run = (p) => ran.some((q) => q === p || globRe(q).test(p));
+    if ((register[path] ?? []).some((p) => offends(p) && !run(p))) return 1;
   } else if (on('T4:declared') && config.reads === 'comment') {
     const hit = declared.reads.find((r) => offends(r.pattern));
     if (hit) return hit.line;
@@ -635,7 +645,7 @@ function sourceTextLine(view, { config, register, tracked, as, helpers }) {
   // system, that the test does not declare: `// runs:` when it is only run. A JSON register does
   // not silence this (1.0.3): a register can miss a read, and a source file it names returned above.
   if (!tracked) return 0;
-  const said = [...declared.reads, ...declared.runs].map((r) => r.pattern);
+  const said = [...[...declared.reads, ...declared.runs].map((r) => r.pattern), ...mapped];
   const breach = (target) => target !== path && tracked.has(target) && !allowed(target) && !said.some((p) => globRe(p).test(target));
   // `./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).
@@ -724,7 +734,7 @@ export function pinsOf(pins, testPaths) {
  * 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, as = null, readText = null }) {
+export function breachesOf({ files, config, register = null, runs = null, tracked = null, as = null, readText = null }) {
   const out = [];
   const add = (file, rule, line) => out.push({ file, rule, line, say: RULES[rule] });
   const on = (id) => detects(id, as);
@@ -740,7 +750,7 @@ export function breachesOf({ files, config, register = null, tracked = null, as
     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, helpers });
+    const t4 = sourceTextLine(view, { config, register, runs, tracked, as, helpers });
     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);
@@ -878,8 +888,9 @@ export function withDefaults(raw) {
   }
   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');
-  if (!(r === null || r === 'comment' || json)) throw fail(EXIT.FAILED, `${CONFIG_FILE}: reads must be null, "comment" or { "json": "<path>", "key": "<name>" | null }`);
+    && Object.keys(r).every((k) => k === 'json' || k === 'key' || k === 'runs') && (r.key === undefined || r.key === null || typeof r.key === 'string')
+    && (r.runs === undefined || (typeof r.runs === 'string' && r.runs !== ''));
+  if (!(r === null || r === 'comment' || json)) throw fail(EXIT.FAILED, `${CONFIG_FILE}: reads must be null, "comment" or { "json": "<path>", "key": "<name>" | null, "runs": "<name>" (optional) }`);
   return config;
 }
 
@@ -899,6 +910,18 @@ export function registerOf(file, reads, as = null) {
   return map;
 }
 
+/**
+ * The runs map beside the reads register (1.0.9), when `reads.runs` names one: what each test only
+ * runs (scripts, migrations it replays, a checker's inputs). No map there cannot run (exit 3).
+ */
+export function runsOf(file, reads) {
+  if (!reads || typeof reads !== 'object' || reads.runs === undefined) return null;
+  const map = file?.[reads.runs];
+  const isMap = map && typeof map === 'object' && !Array.isArray(map) && Object.values(map).every((v) => Array.isArray(v));
+  if (!isMap) throw fail(EXIT.FAILED, `${reads.json}: no "${reads.runs}" map of { "<test file>": ["<pattern>", …] } (named by "runs")`);
+  return map;
+}
+
 // ---------------------------------------------------------------------------------------------
 // The command line: the only part that touches disk and git.
 // ---------------------------------------------------------------------------------------------
@@ -1004,13 +1027,14 @@ export function main(argv = [], { log = console.log, error = console.error, runn
     const files = testPaths.map((path) => ({ path, text: readFileSync(join(dir, path), 'utf8') }));
     const registerFile = config.reads && typeof config.reads === 'object' ? readJson(dir, config.reads.json) : null;
     const register = registerFile ? registerOf(registerFile, config.reads) : null;
+    const runs = registerFile ? runsOf(registerFile, config.reads) : null;
     // A helper a test imports is read from the worktree, once (1.0.8).
     const texts = new Map(files.map((f) => [f.path, f.text]));
     const readText = (rel) => {
       if (!texts.has(rel)) { try { texts.set(rel, tracked.has(rel) ? readFileSync(join(dir, rel), 'utf8') : null); } catch { texts.set(rel, null); } }
       return texts.get(rel);
     };
-    const all = breachesOf({ files, config, register, tracked, readText });
+    const all = breachesOf({ files, config, register, runs, tracked, readText });
 
     if (opts.init) {
       if (existsSync(join(dir, LISTED_FILE))) throw fail(EXIT.USAGE, `${LISTED_FILE} exists: the list is written once and only shrinks`);