@syncerauk/test-rules 1.0.1 → 1.0.3

package/README.md

@@ -49,8 +49,10 @@ 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
-  `{ "json": "<path>" }`). The defaults are `CONFIG_DEFAULTS` in the script.
+  one list of what a person reads), `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`.
 
@@ -63,6 +65,19 @@ Both in the repo's `scripts/test-rules/`:
 
 A repo starts with `"fail": false`: breaches are printed and the exit is 0. One line turns it on.
 
+## Versions
+
+- **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
+  as empty. Both make the check see reads it missed, so a repo's first run on 1.0.2 can show
+  breaches that are not on its list.
+- **1.0.1** — The first release through the publish workflow. Same file as 1.0.0.
+
 ## Releases
 
 The source is `scripts/test-rules.mjs` in Syncera-UK/syncera-orchestrator, where its tests run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncerauk/test-rules",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "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,13 @@
 //   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).
 //   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,7 +71,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
-  reads: null, // the reads register: null, "comment" (`// reads:` lines) or { json: "<path>", key: "tests" }
+  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,
   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]|$)'],
@@ -204,7 +206,8 @@ const firstIndex = (text, re) => { const m = re.exec(text); return m ? m.index :
 
 // ---------------------------------------------------------------------------------------------
 // The reads register. Comment form: `// reads: a b` and `// runs: a b` on comment lines of their
-// own (the orchestrator's declared reads). JSON form: { <key>: { "<test>": ["<pattern>", …] } }.
+// own (the orchestrator's declared reads). JSON form: { <key>: { "<test>": ["<pattern>", …] } },
+// or the file itself is that map (`"key": null`): registerOf, below the config.
 // ---------------------------------------------------------------------------------------------
 const DECLARED = /^[ \t]*\/\/[ \t]*(reads|runs):[ \t]*(\S.*)$/gm;
 export function declaredIn(text) {
@@ -290,8 +293,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) {
@@ -299,8 +302,9 @@ function sourceTextLine({ path, text, code, bare, strings }, { config, register,
     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.
     const here = posix.normalize(posix.join(posix.dirname(path), v));
-    const target = v.startsWith('.') || !tracked.has(v) ? here : v;
+    const target = v.startsWith('./') || v.startsWith('../') || !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);
@@ -394,10 +398,26 @@ export function withDefaults(raw) {
     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 r = config.reads;
-  if (!(r === null || r === 'comment' || (r && typeof r === 'object' && typeof r.json === 'string'))) throw fail(EXIT.FAILED, `${CONFIG_FILE}: reads must be null, "comment" or { "json": "<path>" }`);
+  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 }`);
   return config;
 }
 
+/**
+ * The reads register inside a parsed JSON file: the map at `reads.key` ("tests" when no key is
+ * named), or the whole file when the key is null or empty. No map there cannot run (exit 3): an
+ * empty register would read as "no test reads anything".
+ */
+export function registerOf(file, reads) {
+  const key = reads.key === undefined ? 'tests' : reads.key;
+  const whole = key === null || key === '';
+  const map = whole ? file : file?.[key];
+  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 ${whole ? 'top-level' : `"${key}"`} map of { "<test file>": ["<pattern>", …] }${whole ? '' : ' (name it with "key", or "key": null when the file itself is the map)'}`);
+  return map;
+}
+
 // ---------------------------------------------------------------------------------------------
 // The command line: the only part that touches disk and git.
 // ---------------------------------------------------------------------------------------------
@@ -446,7 +466,7 @@ export function main(argv = [], { log = console.log, error = console.error } = {
     const tracked = new Set(present);
     const testPaths = present.filter((p) => !p.split('/').includes('node_modules') && matches(config.tests, p) && !matches(config.ignore, p)).sort();
     const files = testPaths.map((path) => ({ path, text: readFileSync(join(dir, path), 'utf8') }));
-    const register = config.reads && typeof config.reads === 'object' ? (readJson(dir, config.reads.json)[config.reads.key ?? 'tests'] ?? {}) : null;
+    const register = config.reads && typeof config.reads === 'object' ? registerOf(readJson(dir, config.reads.json), config.reads) : null;
     const all = breachesOf({ files, config, register, tracked });
 
     if (opts.init) {