@syncerauk/test-rules 1.0.3 → 1.0.5

package/README.md

@@ -49,12 +49,15 @@ 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
+  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),
+  `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
   script.
 - `listed.json`: the breaches the repo had on the day the check arrived. Written once by
-  `test-rules --init`.
+  `test-rules --init`. An optional `moved` map, `{ "<new test file>": "<old test file>" }`,
+  says where a split or a rename took a listed file.
 
 ## The list only shrinks
 
@@ -62,11 +65,22 @@ Both in the repo's `scripts/test-rules/`:
 - 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 split or a rename carries its listed breaches: the new file's entry passes when `moved`
+  names the old file, the base listed the same rule on it, and the old file is no longer a test
+  file. A `moved` line is never stale and never a breach; delete it whenever you like.
 
 A repo starts with `"fail": false`: breaches are printed and the exit is 0. One line turns it on.
 
 ## Versions
 
+- **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.
+  Nothing changes for a repo that does not set it.
+- **1.0.4** — `style_contract`: a repo may name one test that reads its stylesheets (`.css`,
+  `.scss`), the way wording is read once from the wording list. Those files are not a
+  `T4:source-text` breach in that test, and only in that test. Nothing changes for a repo that
+  does not set it.
 - **1.0.3** — A JSON reads register no longer turns off the scan of the test's code. A source
   file the test builds a path to from its own place, in a test that reads files, is a
   `T4:source-text` breach unless the test declares it `// runs:`. A repo with a JSON register

package/package.json

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

@@ -16,7 +16,9 @@
 //
 // 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>", …] } }
+//   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).
 //
 // 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
@@ -24,6 +26,10 @@
 // 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).
+// A split or a rename carries its listed breaches: an entry the base does not hold is not
+// `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.
 // `"fail": false` in the config is report only: everything is printed, the exit is 0.
 //
 // The rules (RULES below) and how each is seen:
@@ -39,7 +45,8 @@
 //                   reads the file system and declares it neither `// reads:`, `// runs:` nor
 //                   in its JSON register entry (a file that is only run is declared `// runs:`).
 //                   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).
+//                   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).
 //   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,
@@ -71,6 +78,7 @@ export const CONFIG_DEFAULTS = Object.freeze({
   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
+  style_contract: {}, // { "<test file>": ["<.css/.scss path or glob>", …] }: the one test that may read those stylesheets
   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,
@@ -273,7 +281,9 @@ 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 }) {
   const isSource = (p) => config.source_ext.includes(String(p).split('.').pop().toLowerCase());
-  const allowed = (p) => under(config.fixtures, p) || under(config.wording, p);
+  // 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.
+  const allowed = (p) => under(config.fixtures, p) || under(config.wording, p) || under(config.style_contract?.[path], 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));
 
@@ -345,9 +355,12 @@ export function breachesOf({ files, config, register = null, tracked = null }) {
  * 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 } }.
+ * `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 }.
  */
-export function verdict({ all, listed = {}, base = null, lineCounts = {} }) {
+export function verdict({ all, listed = {}, base = null, lineCounts = {}, moved = {}, present = 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));
@@ -356,10 +369,14 @@ export function verdict({ all, listed = {}, base = null, lineCounts = {} }) {
   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 });
   }
+  const carried = (file, rule) => {
+    const old = Object.hasOwn(moved, file) ? moved[file] : null;
+    return typeof old === 'string' && present !== null && !present.has(old) && (base.listed?.[old] ?? []).includes(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']}` });
+        if (base.listed && !(base.listed[file] ?? []).includes(rule) && !carried(file, 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) {
@@ -397,6 +414,11 @@ export function withDefaults(raw) {
   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 sc = config.style_contract;
+  const styleOnly = (g) => typeof g === 'string' && /\.s?css$/.test(g);
+  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>", …] }`);
+  }
   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');
@@ -453,6 +475,15 @@ export function entriesOf(obj, where) {
   if (!ok) throw fail(EXIT.FAILED, `${where}: must be { "v": ${VERSION}, "entries": { "<test file>": ["<rule id>", …] } }`);
   return e;
 }
+/** The optional `moved` map of a list: { "<new test file>": "<old test file>" }, or {} when absent. */
+export function movedOf(obj, where) {
+  if (obj?.moved === undefined) return {};
+  const m = obj.moved;
+  const ok = m && typeof m === 'object' && !Array.isArray(m)
+    && Object.entries(m).every(([to, from]) => typeof from === 'string' && from.length > 0 && from !== to);
+  if (!ok) throw fail(EXIT.FAILED, `${where}: "moved" must be { "<new test file>": "<old test file>", … }, each old file named and not the new one`);
+  return m;
+}
 
 export function main(argv = [], { log = console.log, error = console.error } = {}) {
   try {
@@ -477,7 +508,9 @@ export function main(argv = [], { log = console.log, error = console.error } = {
       return EXIT.CLEAN;
     }
 
-    const listed = existsSync(join(dir, LISTED_FILE)) ? entriesOf(readJson(dir, LISTED_FILE), LISTED_FILE) : {};
+    const listedJson = existsSync(join(dir, LISTED_FILE)) ? readJson(dir, LISTED_FILE) : null;
+    const listed = listedJson ? entriesOf(listedJson, LISTED_FILE) : {};
+    const moved = listedJson ? movedOf(listedJson, LISTED_FILE) : {};
     let base = null;
     let baseNote = 'no base';
     if (!opts.noBase) {
@@ -503,7 +536,7 @@ export function main(argv = [], { log = console.log, error = console.error } = {
       } 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 });
+    const v = verdict({ all, listed, base, lineCounts, moved, present: new Set(testPaths) });
 
     if (opts.list) {
       log(JSON.stringify({ v: VERSION, breaches: v.breaches, listed: v.listed, stale: v.stale }));