@syncerauk/test-rules 1.0.2 → 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,14 @@ 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
+  (app, portal) can see breaches that are not on its list on its first run of 1.0.3.
 - **1.0.2** — A path that starts with a dot-folder (`.github/workflows/gate.yml`) is a repo
   path; only `./` and `../` are relative to the test. A JSON reads register may be the whole
   file (`"key": null`); a register with no map at its key cannot run (exit 3) instead of reading

package/package.json

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

@@ -33,11 +33,14 @@
 //   T4:source-text  the test reads a source file as text: a read it declares (the repo's reads
 //                   register) that is a source file or a folder and is neither under a fixture
 //                   folder nor on the wording list; a `?raw` import or a raw import.meta.glob;
-//                   and, where the register is comment lines or absent, a source file whose
-//                   path the test builds from its own place (new URL(…, import.meta.url), or
-//                   join( / resolve( on import.meta.dirname, __dirname, ROOT or HERE) in a test
-//                   that reads the file system and declares it neither `// reads:` nor
-//                   `// runs:` (a file that is only run is declared `// runs:`)
+//                   and, whatever the register's form, a source file whose path the test
+//                   builds from its own place (new URL(…, import.meta.url), or join( /
+//                   resolve( on import.meta.dirname, __dirname, ROOT or HERE) in a test that
+//                   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). 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,
@@ -69,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,
@@ -271,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));
 
@@ -291,8 +297,8 @@ function sourceTextLine({ path, text, code, bare, strings }, { config, register,
     if (/\?raw|as\s*:\s*['"]raw['"]/.test(call)) return lineOf(code, m.index);
   }
   // A source file whose path the test builds from its own place, in a test that reads the file
-  // system, where no register says what the test reads: declared `// runs:` when it is only run.
-  if (register && typeof register === 'object') return 0;
+  // system, that the test does not declare: `// runs:` when it is only run. A JSON register does
+  // not silence this: a register can miss a read, and a source file it names returned above.
   if (!FS_READ.test(code) || !tracked) return 0;
   const said = [...declared.reads, ...declared.runs].map((r) => r.pattern);
   for (const s of strings) {
@@ -395,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');