@syncerauk/test-rules 1.0.7 → 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,13 +124,30 @@ 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) |
+| 1.0.8 | `T4:source-text`: a source path handed to a helper (the test's own function, or one it imports from the repo) at a parameter the helper reads the file system at |
 
 ## 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
+  (followed through re-exports and one more import). Only the arguments at the parameters that
+  reach the read are judged, so a path passed as data is not a read; a destructured parameter
+  and an aliased import (`@/…`) are not followed. A repo's first run of 1.0.8 can show breaches
+  in files nobody changed: the PR that bumps the pin re-lists them with `--relist`.
+
 - **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

package/package.json

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

@@ -62,6 +62,11 @@
 //                   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).
+//                   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)
@@ -102,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]|$)'],
@@ -133,7 +138,7 @@ export const NEVER_LISTED = Object.freeze(['T1:hub', 'T4:pin', 'list:grew']);
  * 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. 1.0.7 adds T4:pin, which is
- * judged on the config and never listed, so a re-list never carries it.
+ * judged on the config and never listed, so a re-list never carries it. 1.0.8 adds T4:helper.
  */
 export const DETECTORS = Object.freeze({
   'T1:name': { rule: 'T1:name', since: '1.0.0' }, // the file named by task
@@ -146,6 +151,7 @@ export const DETECTORS = Object.freeze({
   '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)
+  'T4:helper': { rule: 'T4:source-text', since: '1.0.8' }, // a source path handed to a helper of the repo's own that reads at its argument
   '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' },
@@ -338,8 +344,272 @@ function envLine({ code, bare }, allowed) {
   return 0;
 }
 
+// ---------------------------------------------------------------------------------------------
+// Reads made through a helper (1.0.8; Bernardo Cunha, 6 Nov 2026, card s7). A test that hands a
+// source path to a helper of the repo's own reads that source as surely as a readFileSync of its
+// own. A helper is a function of the test's own, or one exported by a tracked file the test
+// imports by a relative path (`import`, `require`, followed through `export … from`), with a
+// parameter that reaches a read of the file system: `readFileSync(join(ROOT, rel))`, directly,
+// through a local variable, or through another such function, in that file or one it imports.
+// Only the arguments at those parameters are judged, so a path handed as data (an option, a name
+// in a list) is not a read. A parameter that is destructured is not followed. Aliased imports
+// (`@/…`) and packages are not followed. A path handed over is the repo path it names, else the
+// first tracked file it names from the helper's folder or one above it, then the test's.
+// `readText(path)` gives a tracked file's text, or null.
+// ---------------------------------------------------------------------------------------------
+const FS_READ_CALL = /(?<![\w$])(?:[\w$]+\.)?(?:readFileSync|readFile|createReadStream|readdirSync|readdir|opendirSync)\s*\(/g;
+const IMPORT_FROM = /\bimport\s+(?!type\b)([\w$*{}\s,]+?)\s*\bfrom\s*(['"])([^'"\n]+)\2/g;
+const REQUIRE_OF = /\b(?:const|let|var)\s+([\w$]+|\{[^}]*\})\s*=\s*require\s*\(\s*(['"])([^'"\n]+)\2\s*\)/g;
+const EXPORT_FROM = /\bexport\s+(\*|\{[^}]*\})\s*from\s*(['"])([^'"\n]+)\2/g;
+const MODULE_EXT = ['', '.mjs', '.js', '.ts', '.tsx', '.mts', '.cts', '.cjs', '.jsx', '/index.mjs', '/index.js', '/index.ts', '/index.tsx'];
+const HELPER_DEPTH = 2; // the test's helper, and the helpers that helper imports
+
+/** The tracked file a relative import names (`./x.js` may be x.ts), or null: a package, an alias, a file not here. */
+export function resolveImport(from, spec, tracked) {
+  if (!/^\.\.?\//.test(spec)) return null;
+  const p = posix.normalize(posix.join(posix.dirname(from), spec));
+  for (const stem of [p, p.replace(/\.[cm]?jsx?$/, '')]) for (const ext of MODULE_EXT) if (tracked.has(stem + ext)) return stem + ext;
+  return null;
+}
+
+/** The index just past the bracket that closes the one at `open` in blanked code, or the end. */
+function closing(code, open) {
+  let depth = 0;
+  for (let k = open; k < code.length; k++) {
+    const c = code[k];
+    if (c === '(' || c === '[' || c === '{') depth++;
+    else if ((c === ')' || c === ']' || c === '}') && --depth === 0) return k + 1;
+  }
+  return code.length;
+}
+
+/** The spans [from, to) of each argument of the call whose `(` is at `open`, in blanked code. */
+function argSpans(code, open) {
+  const end = closing(code, open) - 1;
+  const spans = [];
+  let depth = 0;
+  let from = open + 1;
+  for (let k = open + 1; k < end; k++) {
+    const c = code[k];
+    if ('([{'.includes(c)) depth++;
+    else if (')]}'.includes(c)) depth--;
+    else if (c === ',' && depth === 0) { spans.push([from, k]); from = k + 1; }
+  }
+  if (code.slice(from, end).trim()) spans.push([from, end]);
+  return spans;
+}
+
+/** { local name: exported name } of an import clause; a namespace (`* as ns`, a whole `require`) is '*'. */
+function bindingsOf(clause, required = false) {
+  const out = {};
+  const named = /\{([^}]*)\}/.exec(clause);
+  for (const part of named ? named[1].split(',') : []) {
+    const m = /^\s*(?:type\s+)?([\w$]+)(?:\s*(?:\bas\b|:)\s*([\w$]+))?\s*$/.exec(part);
+    if (m) out[m[2] ?? m[1]] = m[1];
+  }
+  const rest = clause.replace(/\{[^}]*\}/, '');
+  const ns = /\*\s*as\s+([\w$]+)/.exec(rest);
+  if (ns) out[ns[1]] = '*';
+  else { const def = /^\s*([\w$]+)/.exec(rest); if (def) out[def[1]] = required ? '*' : 'default'; }
+  return out;
+}
+
+/** The relative imports of a file's code: [{ target, bindings }], `target` the tracked file. */
+function importsOf(path, { code, bare }, tracked) {
+  const out = [];
+  for (const [re, required] of [[IMPORT_FROM, false], [REQUIRE_OF, true]]) {
+    for (const m of bare.matchAll(re)) {
+      if (code[m.index] === ' ') continue; // inside a string
+      const target = resolveImport(path, m[3], tracked);
+      if (target) out.push({ target, bindings: bindingsOf(m[1], required) });
+    }
+  }
+  return out;
+}
+
+/** The name at each place of a parameter list, null where it is destructured or a rest: `(rel: string, { a } = {}, ...r)` → rel, null, null. */
+function paramNames(text) {
+  const parts = [];
+  let depth = 0;
+  let cur = '';
+  for (const c of text) {
+    if ('([{<'.includes(c)) depth++;
+    else if (')]}'.includes(c) || (c === '>' && !cur.endsWith('='))) depth--;
+    if (c === ',' && depth === 0) { parts.push(cur); cur = ''; } else cur += c;
+  }
+  if (cur.trim() || parts.length) parts.push(cur);
+  return parts.map((part) => /^\s*([A-Za-z_$][\w$]*)\s*\??\s*(?:[:=]|$)/.exec(part)?.[1] ?? null);
+}
+
+/** The functions a file defines, at any depth: [{ name, params, from, to }], `from`/`to` the body. */
+function functionsOf(code) {
+  const out = [];
+  const DEF = /\bfunction\s*\*?\s*([\w$]+)\s*(?:<[^>()]*>)?\s*\(|\b(?:const|let|var)\s+([\w$]+)\s*(?::[^=;]+)?=\s*(?:async\s+)?(?:function\b\s*\*?\s*[\w$]*\s*)?(?:<[^>()]*>)?\s*(\(|[\w$]+\s*=>)/g;
+  for (const m of code.matchAll(DEF)) {
+    const named = Boolean(m[1]) || /\bfunction\b/.test(m[0]);
+    let params;
+    let after;
+    if (m[3] && m[3] !== '(') {
+      params = [m[3].replace(/\s*=>$/, '')];
+      after = m.index + m[0].length;
+    } else {
+      const open = m.index + m[0].length - 1;
+      after = closing(code, open);
+      params = paramNames(code.slice(open + 1, after - 1));
+      const arrow = /^\s*(?::[^={]+)?=>\s*/.exec(code.slice(after));
+      if (!named && !arrow) continue; // `const x = (a, b)`: a value, not a function
+      if (arrow) after += arrow[0].length;
+    }
+    let from = after;
+    while (from < code.length && /\s/.test(code[from])) from++;
+    if (!named && code[from] !== '{') {
+      // An arrow with an expression body: to the end of the statement.
+      let depth = 0;
+      let k = from;
+      for (; k < code.length; k++) {
+        const c = code[k];
+        if ('([{'.includes(c)) depth++;
+        else if (')]}'.includes(c)) { if (depth === 0) break; depth--; } else if ((c === ';' || c === '\n' || c === ',') && depth === 0) break;
+      }
+      out.push({ name: m[1] ?? m[2], params, from, to: k });
+      continue;
+    }
+    const open = code.indexOf('{', after);
+    if (open >= 0) out.push({ name: m[1] ?? m[2], params, from: open, to: closing(code, open) });
+  }
+  return out;
+}
+
+/**
+ * The places of `fn`'s parameters that reach a read of the file system: a Set of indexes.
+ * `callees`: { local name: Set of the places at which it reads }; `nsCallees`: { namespace: that map }.
+ */
+function placesRead(fn, { code, bare }, callees, nsCallees) {
+  const body = code.slice(fn.from, fn.to);
+  const raw = bare.slice(fn.from, fn.to);
+  const taint = new Map(fn.params.flatMap((p, i) => (p ? [[p, new Set([i])]] : [])));
+  const out = new Set();
+  if (!taint.size) return out;
+  // The places a span of the body carries: by a name in the code, or inside a template's `${…}`.
+  const named = (p) => `(?<![\\w$.])${p.replace(/\$/g, '\\$')}(?![\\w$])`;
+  const carried = (from, to) => {
+    const got = new Set();
+    for (const [p, places] of taint) {
+      if (new RegExp(named(p)).test(body.slice(from, to)) || new RegExp(`\\$\\{[^}]*${named(p)}`).test(raw.slice(from, to))) for (const i of places) got.add(i);
+    }
+    return got;
+  };
+  for (let round = 0; round < 3; round++) {
+    for (const a of body.matchAll(/\b(?:const|let|var)\s+([\w$]+)\s*(?::[^=;]+)?=\s*([^;\n]*)/g)) {
+      const from = a.index + a[0].length - a[2].length;
+      const got = carried(from, from + a[2].length);
+      if (got.size) taint.set(a[1], new Set([...(taint.get(a[1]) ?? []), ...got]));
+    }
+  }
+  const reach = (open, places) => {
+    const spans = argSpans(body, open);
+    for (const [k, span] of spans.entries()) if (places === null || places.has(k)) for (const i of carried(...span)) out.add(i);
+  };
+  for (const c of body.matchAll(FS_READ_CALL)) reach(c.index + c[0].length - 1, null);
+  for (const c of body.matchAll(/(?<![\w$.])([\w$]+)\s*\(/g)) if (callees.has(c[1])) reach(c.index + c[0].length - 1, callees.get(c[1]));
+  for (const c of body.matchAll(/(?<![\w$.])([\w$]+)\s*\.\s*([\w$]+)\s*\(/g)) {
+    const places = nsCallees.get(c[1])?.get(c[2]);
+    if (places) reach(c.index + c[0].length - 1, places);
+  }
+  return out;
+}
+
+/**
+ * The functions a file can call that read at a parameter, its own and those it imports (at
+ * `depth`): { reading: { local name: Set of places }, nsCallees: { namespace: that map }, origin:
+ * { local name or namespace: the file that defines it } }.
+ */
+function localReaders(path, view, ctx, depth) {
+  const reading = new Map();
+  const nsCallees = new Map();
+  const origin = new Map();
+  for (const imp of importsOf(path, view, ctx.tracked)) {
+    const theirs = readersOf(imp.target, ctx, depth);
+    for (const [local, name] of Object.entries(imp.bindings)) {
+      if (name === '*' ? !theirs.size : !theirs.has(name)) continue;
+      if (name === '*') nsCallees.set(local, theirs); else reading.set(local, theirs.get(name));
+      origin.set(local, imp.target);
+    }
+  }
+  if (!reading.size && !nsCallees.size && !FS_READ.test(view.code)) return { reading, nsCallees, origin }; // nothing here can read
+  const fns = functionsOf(view.code);
+  for (let grew = true; grew;) {
+    grew = false;
+    for (const fn of fns) {
+      const places = placesRead(fn, view, reading, nsCallees);
+      const had = reading.get(fn.name);
+      if (places.size && (!had || [...places].some((i) => !had.has(i)))) {
+        reading.set(fn.name, new Set([...(had ?? []), ...places]));
+        origin.set(fn.name, path);
+        grew = true;
+      }
+    }
+  }
+  return { reading, nsCallees, origin };
+}
+
+/** The exported functions of `path` that read at a parameter: { exported name ('default' for a default export): Set of places }. */
+function readersOf(path, ctx, depth = 0) {
+  const key = `${depth}\n${path}`;
+  if (ctx.memo.has(key)) return ctx.memo.get(key);
+  const out = new Map();
+  ctx.memo.set(key, out); // a cycle reads as nothing
+  const text = depth >= HELPER_DEPTH ? null : ctx.readText(path);
+  if (text == null) return out;
+  const view = scan(text);
+  const { code, bare } = view;
+  const { reading } = localReaders(path, view, ctx, depth + 1);
+  const add = (as, name) => { if (reading.has(name)) out.set(as, reading.get(name)); };
+  for (const m of code.matchAll(/\bexport\s+(?:async\s+)?(?:function\s*\*?|const|let|var)\s*([\w$]+)/g)) add(m[1], m[1]);
+  for (const m of code.matchAll(/\bexport\s+default\s+(?:async\s+)?(?:function\s*\*?\s*)?([\w$]+)/g)) add('default', m[1]);
+  for (const m of bare.matchAll(/\bexport\s*\{([^}]*)\}(?!\s*from)/g)) for (const [as, name] of Object.entries(bindingsOf(`{${m[1]}}`))) add(as, name);
+  for (const m of bare.matchAll(/\b(?:module\.)?exports\s*(?:\.\s*([\w$]+)\s*=\s*([\w$]+)|=\s*\{([^}]*)\})/g)) {
+    if (m[1]) add(m[1], m[2]);
+    for (const part of (m[3] ?? '').split(',')) {
+      const p = /^\s*([\w$]+)(?:\s*:\s*([\w$]+))?\s*$/.exec(part);
+      if (p) add(p[1], p[2] ?? p[1]);
+    }
+  }
+  for (const m of bare.matchAll(EXPORT_FROM)) {
+    if (code[m.index] === ' ') continue;
+    const target = resolveImport(path, m[3], ctx.tracked);
+    const theirs = target ? readersOf(target, ctx, depth + 1) : new Map();
+    if (m[1] === '*') { for (const [n, places] of theirs) if (n !== 'default') out.set(n, places); continue; }
+    for (const [as, name] of Object.entries(bindingsOf(m[1]))) if (theirs.has(name)) out.set(as, theirs.get(name));
+  }
+  return out;
+}
+
+/**
+ * The arguments a test hands to a helper at a place it reads: [{ helper, from, to }], spans of
+ * the test's code. A helper is imported, or a function of the test's own.
+ */
+function helperArgsOf(path, view, ctx) {
+  const out = [];
+  const { code } = view;
+  const { reading, nsCallees, origin } = localReaders(path, view, ctx, 0);
+  const take = (places, helper, open) => {
+    for (const [k, [from, to]] of argSpans(code, open).entries()) if (places.has(k)) out.push({ helper, from, to });
+  };
+  for (const c of code.matchAll(/(?<![\w$.])([\w$]+)\s*\(/g)) {
+    if (!reading.has(c[1]) || /\bfunction\s*\*?\s*$/.test(code.slice(Math.max(0, c.index - 12), c.index))) continue; // its definition
+    take(reading.get(c[1]), origin.get(c[1]), c.index + c[0].length - 1);
+  }
+  for (const c of code.matchAll(/(?<![\w$.])([\w$]+)\s*\.\s*([\w$]+)\s*\(/g)) {
+    const places = nsCallees.get(c[1])?.get(c[2]);
+    if (places) take(places, origin.get(c[1]), c.index + c[0].length - 1);
+  }
+  return out;
+}
+
 /** 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, as }) {
+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());
   // A style contract is the one test that may read the stylesheets it names: style rules are
@@ -350,8 +620,15 @@ function sourceTextLine({ path, text, code, bare, strings }, { config, register,
 
   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;
@@ -367,24 +644,59 @@ function sourceTextLine({ path, text, code, bare, strings }, { config, register,
   // 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 (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) {
-    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;
-    // `./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));
+  if (!tracked) return 0;
+  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).
+  const builtTarget = (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);
+    return besideTest || !tracked.has(v) ? posix.normalize(posix.join(posix.dirname(path), v)) : v;
+  };
+  const builtBefore = (start) => {
+    const before = code.slice(code.lastIndexOf('\n', start) + 1, start - 1);
+    return !IMPORT_BEFORE.test(before) && BUILT_HERE.test(before);
+  };
+  const lines = [];
+  if (on('T4:built') && !(json && !on('T4:built-under-json')) && FS_READ.test(code)) {
+    for (const s of strings) {
+      const v = s.value;
+      if (/[\s*?$]/.test(v) || !isSource(v) || !builtBefore(s.start)) continue;
+      if (breach(builtTarget(v))) { lines.push(lineOf(code, s.start)); break; }
+    }
   }
-  return 0;
+  // A source path handed to a helper at a place it reads (1.0.8): a string in that argument, or a
+  // constant of the test holding one. Built from the test's place, it is read as above; else the
+  // helper may read it from the repo root, beside itself or beside the test.
+  const handed = on('T4:helper') && helpers ? helperArgsOf(path, view, helpers) : [];
+  if (handed.length) {
+    const consts = new Map();
+    for (const s of strings) {
+      const name = /\b(?:const|let|var)\s+([\w$]+)\s*=\s*$/.exec(code.slice(code.lastIndexOf('\n', s.start) + 1, s.start - 1));
+      if (name) consts.set(name[1], s);
+    }
+    const targetOf = (s, helper) => {
+      const v = s.value;
+      if (/[\s*?$]/.test(v) || !isSource(v)) return null;
+      if (builtBefore(s.start)) return builtTarget(v);
+      const from = (file) => posix.normalize(posix.join(posix.dirname(file), v));
+      // A repo path, else beside the helper or a folder above it, then the same from the test.
+      const above = (file) => { const dirs = []; for (let d = posix.dirname(file); d !== '.'; d = posix.dirname(d)) dirs.push(posix.join(d, v)); return dirs; };
+      const tries = /^\.\.?\//.test(v) ? [from(path), from(helper)] : [v, ...above(helper), ...above(path)];
+      return tries.find((t) => tracked.has(t)) ?? null;
+    };
+    for (const arg of handed) {
+      const found = [
+        ...strings.filter((s) => s.start > arg.from && s.start < arg.to).map((s) => ({ s, at: s.start })),
+        ...[...code.slice(arg.from, arg.to).matchAll(/(?<![\w$.])([A-Za-z_$][\w$]*)/g)].filter((m) => consts.has(m[1])).map((m) => ({ s: consts.get(m[1]), at: arg.from + m.index })),
+      ];
+      for (const { s, at } of found) {
+        const target = targetOf(s, arg.helper);
+        if (target && breach(target)) lines.push(lineOf(code, at));
+      }
+    }
+  }
+  return lines.length ? Math.min(...lines) : 0;
 }
 
 /**
@@ -422,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 }) {
+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);
@@ -430,13 +742,15 @@ export function breachesOf({ files, config, register = null, tracked = null, as
   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)));
+  // The repo's own helpers, read once each (1.0.8): only with a reader and the tracked files.
+  const helpers = readText && tracked ? { readText, tracked, memo: new Map() } : null;
   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 });
+    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);
@@ -574,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;
 }
 
@@ -595,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.
 // ---------------------------------------------------------------------------------------------
@@ -700,7 +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 all = breachesOf({ files, config, register, tracked });
+    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, 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`);
@@ -750,7 +1084,7 @@ export function main(argv = [], { log = console.log, error = console.error, runn
             ...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 });
+          const asBase = breachesOf({ files, config, register: registerFile ? registerOf(registerFile, config.reads, gate.from) : null, tracked, readText, 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})`;