@syncerauk/test-rules 1.0.3 → 1.0.4

package/README.md

@@ -49,7 +49,9 @@ 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.
@@ -67,6 +69,10 @@ A repo starts with `"fail": false`: breaches are printed and the exit is 0. One
 
 ## Versions
 
+- **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.4",
   "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

@@ -39,7 +39,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 +72,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 +275,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));
 
@@ -397,6 +401,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');