@veda-hq/pariksha 0.5.7 → 0.5.9

package/dist/module-exports.js

@@ -0,0 +1,169 @@
+// What a module exports, by its syntax tree: each exported name and whether
+// it is a function, another value or only a type. Re-exports are followed
+// (`export { a } from './x'`, `export *`, a local name bound by an import), so
+// a barrel's names resolve to their declarations. Only relative specifiers are
+// followed; a package specifier is reported as unfollowed, never guessed.
+import { posix } from 'node:path';
+import { isFile, readText } from "./registry-ratchet.js";
+const EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs', '.jsx'];
+/** The root-relative file a relative specifier in `from` names, as TypeScript and bundlers resolve it, or undefined. */
+export const resolveRelative = (root, from, specifier) => {
+    if (!specifier.startsWith('./') && !specifier.startsWith('../'))
+        return undefined;
+    const base = posix.join(posix.dirname(from), specifier);
+    // `./x.js` in TypeScript source names `./x.ts`.
+    const stem = base.replace(/\.(?:[cm]?js|jsx)$/, '');
+    const candidates = [base, ...EXTENSIONS.map((e) => `${stem}${e}`), ...EXTENSIONS.map((e) => `${base}/index${e}`)];
+    return candidates.find((c) => !c.startsWith('../') && isFile(root, c));
+};
+/** Whether a variable's initializer makes it a function: an arrow or a function expression, through parentheses and `as`/`satisfies`. */
+const isFunctionInit = (ts, init) => {
+    let e = init;
+    while (e !== undefined && (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isSatisfiesExpression(e)))
+        e = e.expression;
+    return e !== undefined && (ts.isArrowFunction(e) || ts.isFunctionExpression(e));
+};
+const hasExport = (ts, node) => ts.canHaveModifiers(node) && (ts.getModifiers(node) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+const hasDefault = (ts, node) => ts.canHaveModifiers(node) && (ts.getModifiers(node) ?? []).some((m) => m.kind === ts.SyntaxKind.DefaultKeyword);
+/** The exports of the module at `file` (root-relative), following relative re-exports. */
+export const moduleExports = (ts, root, file) => {
+    const unfollowed = [];
+    const cache = new Map();
+    const visiting = new Set();
+    const exportsOf = (at) => {
+        const cached = cache.get(at);
+        if (cached !== undefined)
+            return cached;
+        const out = new Map();
+        // A cycle reads as no further exports; the outer visit fills the rest.
+        if (visiting.has(at))
+            return out;
+        visiting.add(at);
+        const source = readText(root, at) ?? '';
+        const tree = ts.createSourceFile(at, source, ts.ScriptTarget.Latest, true);
+        const locals = new Map();
+        const follow = (specifier) => {
+            const target = resolveRelative(root, at, specifier);
+            if (target === undefined)
+                unfollowed.push(`${at}: '${specifier}'`);
+            return target;
+        };
+        /** What a local name is, following an import to the module it came from. */
+        const kindOfLocal = (name) => {
+            const local = locals.get(name);
+            if (local === undefined)
+                return 'unresolved';
+            if ('kind' in local)
+                return local.kind;
+            const target = local.from ?? follow(local.specifier);
+            return target === undefined ? 'unresolved' : (exportsOf(target).get(local.name) ?? 'unresolved');
+        };
+        const stars = [];
+        const named = [];
+        for (const statement of tree.statements) {
+            if (ts.isFunctionDeclaration(statement)) {
+                if (statement.name !== undefined)
+                    locals.set(statement.name.text, { kind: 'function' });
+                // `export default function` exports `default`, a function, named or not.
+                if (hasExport(ts, statement) && hasDefault(ts, statement))
+                    out.set('default', 'function');
+                else if (hasExport(ts, statement) && statement.name !== undefined)
+                    out.set(statement.name.text, 'function');
+            }
+            else if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+                // `export default <expression>`: a function expression, or a local resolved once every local is known.
+                const e = statement.expression;
+                if (isFunctionInit(ts, e))
+                    out.set('default', 'function');
+                else if (ts.isIdentifier(e))
+                    named.push(() => out.set('default', kindOfLocal(e.text)));
+                else
+                    out.set('default', 'value');
+            }
+            else if (ts.isVariableStatement(statement)) {
+                for (const d of statement.declarationList.declarations) {
+                    if (!ts.isIdentifier(d.name))
+                        continue;
+                    const kind = isFunctionInit(ts, d.initializer) ? 'function' : 'value';
+                    locals.set(d.name.text, { kind });
+                    if (hasExport(ts, statement))
+                        out.set(d.name.text, kind);
+                }
+            }
+            else if (ts.isClassDeclaration(statement) || ts.isEnumDeclaration(statement)) {
+                // An enum always has a name; a default class may not.
+                const name = statement.name?.text;
+                if (name !== undefined)
+                    locals.set(name, { kind: 'value' });
+                if (hasExport(ts, statement) && hasDefault(ts, statement))
+                    out.set('default', 'value');
+                else if (hasExport(ts, statement) && name !== undefined)
+                    out.set(name, 'value');
+            }
+            else if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) {
+                locals.set(statement.name.text, { kind: 'type' });
+                if (hasExport(ts, statement))
+                    out.set(statement.name.text, 'type');
+            }
+            else if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) && statement.importClause !== undefined) {
+                const clause = statement.importClause;
+                const specifier = statement.moduleSpecifier.text;
+                // A default import is the module's `default` export, followed like a named one.
+                if (clause.name !== undefined)
+                    locals.set(clause.name.text, clause.isTypeOnly ? { kind: 'type' } : { from: undefined, specifier, name: 'default' });
+                const bindings = clause.namedBindings;
+                if (bindings !== undefined && ts.isNamespaceImport(bindings))
+                    locals.set(bindings.name.text, { kind: clause.isTypeOnly ? 'type' : 'value' });
+                if (bindings !== undefined && ts.isNamedImports(bindings)) {
+                    for (const el of bindings.elements) {
+                        locals.set(el.name.text, clause.isTypeOnly || el.isTypeOnly ? { kind: 'type' } : { from: undefined, specifier, name: (el.propertyName ?? el.name).text });
+                    }
+                }
+            }
+            else if (ts.isExportDeclaration(statement)) {
+                const spec = statement.moduleSpecifier !== undefined && ts.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier.text : undefined;
+                const clause = statement.exportClause;
+                if (clause === undefined) {
+                    if (spec !== undefined && !statement.isTypeOnly)
+                        stars.push(spec);
+                }
+                else if (ts.isNamespaceExport(clause)) {
+                    out.set(clause.name.text, statement.isTypeOnly ? 'type' : 'value');
+                }
+                else {
+                    for (const el of clause.elements) {
+                        const exported = el.name.text;
+                        const original = (el.propertyName ?? el.name).text;
+                        if (statement.isTypeOnly || el.isTypeOnly) {
+                            out.set(exported, 'type');
+                            continue;
+                        }
+                        // Resolved after every local is known: an export list may precede the declarations it names.
+                        named.push(() => {
+                            if (spec === undefined)
+                                out.set(exported, kindOfLocal(original));
+                            else {
+                                const target = follow(spec);
+                                out.set(exported, target === undefined ? 'unresolved' : (exportsOf(target).get(original) ?? 'unresolved'));
+                            }
+                        });
+                    }
+                }
+            }
+        }
+        for (const resolve of named)
+            resolve();
+        for (const spec of stars) {
+            const target = follow(spec);
+            if (target === undefined)
+                continue;
+            for (const [name, kind] of exportsOf(target))
+                if (name !== 'default' && !out.has(name))
+                    out.set(name, kind);
+        }
+        visiting.delete(at);
+        cache.set(at, out);
+        return out;
+    };
+    return { exports: exportsOf(file), unfollowed: [...new Set(unfollowed)] };
+};

package/dist/registry-ratchet.js

@@ -0,0 +1,402 @@
+// The engine the registry ratchets share (codec-registry, fault-injection-registry).
+//
+// A registry ratchet holds three things to account. Discovery finds every
+// item that owes a suite. The config registers an item with its suite, or
+// exempts it with a reason. The baseline lists the items still owed, and only
+// shrinks: an entry the merge base did not have is growth, unless its file
+// only moved. Everything here is the shared part: config validation helpers,
+// the baseline's shape, the audit, the growth check and the suite wiring a
+// runner must collect.
+import { readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join, posix } from 'node:path';
+import { fileAt, mergeBaseOf, renamesSince } from "./git.js";
+export const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * A normalized relative POSIX path that stays inside the root. A backslash
+ * (a separator to Windows path operations, so `..\x` could leave the root) and
+ * a NUL are refused before any host path operation sees the path.
+ */
+export const isRepoPath = (p) => !/[\\\0]/.test(p) && !isAbsolute(p) && !posix.isAbsolute(p) && posix.normalize(p) === p && p !== '.' && p !== '..' && !p.startsWith('../') && !p.endsWith('/');
+/**
+ * An empty dictionary with no prototype, for keys a config or a file names: a
+ * key such as `__proto__` or `constructor` is then an entry like any other,
+ * never the prototype or an inherited member.
+ */
+export const dict = () => Object.create(null);
+/** Throws naming the first key of `raw` that `allowed` lacks. */
+export const onlyKeys = (raw, allowed, where) => {
+    const extra = Object.keys(raw).find((k) => !allowed.includes(k));
+    if (extra !== undefined)
+        throw new Error(`${where}unknown key "${extra}"`);
+};
+/** The object at `raw[key]`; throws when it is not one. */
+export const object = (raw, key, where) => {
+    const v = raw[key];
+    if (!isRecord(v))
+        throw new Error(`${where}"${key}" must be an object`);
+    return v;
+};
+/** A required non-blank string. */
+export const text = (raw, key, where) => {
+    const v = raw[key];
+    if (typeof v !== 'string' || v.trim() === '')
+        throw new Error(`${where}"${key}" must be a non-empty string`);
+    return v;
+};
+/** An optional string, non-blank when present. */
+export const optionalText = (raw, key, where) => (raw[key] === undefined ? undefined : text(raw, key, where));
+/** A required root-relative path. */
+export const path = (raw, key, where) => {
+    const v = text(raw, key, where);
+    if (!isRepoPath(v))
+        throw new Error(`${where}"${key}": "${v}" is not a normalized root-relative path`);
+    return v;
+};
+/** A list, empty when absent; throws when present and not a list. */
+export const list = (raw, key, where) => {
+    const v = raw[key] ?? [];
+    if (!Array.isArray(v))
+        throw new Error(`${where}"${key}" must be a list`);
+    return v;
+};
+/** A non-empty list of root-relative paths. */
+export const paths = (raw, key, where) => {
+    const v = list(raw, key, where);
+    if (v.length === 0)
+        throw new Error(`${where}"${key}" is empty, so nothing would be read`);
+    return v.map((p, i) => {
+        if (typeof p !== 'string' || !isRepoPath(p))
+            throw new Error(`${where}${key}[${i}]: ${JSON.stringify(p)} is not a normalized root-relative path`);
+        return p;
+    });
+};
+/** A regular expression from its source text. */
+export const regex = (source, where, flags = '') => {
+    if (typeof source !== 'string' || source === '')
+        throw new Error(`${where} must be a non-empty regular expression`);
+    try {
+        return new RegExp(source, flags);
+    }
+    catch (e) {
+        throw new Error(`${where}: "${source}" is not a regular expression: ${e.message}`);
+    }
+};
+/** A non-empty list of regular expressions. */
+export const regexes = (raw, key, where) => {
+    const v = list(raw, key, where);
+    if (v.length === 0)
+        throw new Error(`${where}"${key}" is empty, so nothing would match`);
+    return v.map((s, i) => regex(s, `${where}${key}[${i}]`));
+};
+/** Each entry of `items` is a record; `where` names it in a message. */
+export const records = (items, key) => items.map((raw, i) => {
+    const where = `${key}[${i}]: `;
+    if (!isRecord(raw))
+        throw new Error(`${key}[${i}] must be an object`);
+    return { raw, where };
+});
+/** An exemption must say why, in words a reviewer reads: at least `min` characters, trimmed. */
+export const reason = (raw, where, min = 1) => {
+    const v = raw['reason'];
+    if (typeof v !== 'string' || v.trim() === '')
+        throw new Error(`${where}an exemption needs a reason`);
+    if (v.trim().length < min)
+        throw new Error(`${where}"reason" is shorter than minNoteLength (${min}): say why in words`);
+    return v;
+};
+/** A note (what a suite leaves out, why it runs LF only…): optional or required, at least `min` characters trimmed when present. */
+export const note = (raw, key, where, min, required) => {
+    const v = required ? text(raw, key, where) : optionalText(raw, key, where);
+    if (v !== undefined && v.trim().length < min)
+        throw new Error(`${where}"${key}" is shorter than minNoteLength (${min}): say it in words`);
+    return v;
+};
+/** `minNoteLength`: the fewest characters, trimmed, an exemption reason or note may have. Required. */
+export const minNoteLength = (raw) => {
+    const v = raw['minNoteLength'];
+    if (typeof v !== 'number' || !Number.isInteger(v) || v < 1)
+        throw new Error('"minNoteLength" must be a whole number of at least 1');
+    return v;
+};
+/**
+ * A key every config must name, whose `null` opts its check out. Absence is
+ * refused: a forgotten key would drop a check silently. The opt-out is recorded
+ * in `skipped`, which the run prints as not checked.
+ */
+export const required = (raw, key, where, skipped, parse) => {
+    if (!(key in raw))
+        throw new Error(`${where}"${key}" is required (null opts its check out)`);
+    if (raw[key] === null) {
+        skipped.push(`${where.replace(/: $/, '.')}${key}`);
+        return undefined;
+    }
+    return parse();
+};
+/** `findingIds: { motivatedBy, example }`, each a regex or null. */
+export const parseFindingIds = (raw, skipped) => {
+    const v = required(raw, 'findingIds', '', skipped, () => object(raw, 'findingIds', ''));
+    if (v === undefined)
+        return { motivatedBy: undefined, example: undefined };
+    onlyKeys(v, ['motivatedBy', 'example'], 'findingIds: ');
+    return {
+        motivatedBy: required(v, 'motivatedBy', 'findingIds: ', skipped, () => regex(v['motivatedBy'], 'findingIds.motivatedBy')),
+        example: required(v, 'example', 'findingIds: ', skipped, () => regex(v['example'], 'findingIds.example')),
+    };
+};
+/** The config text as JSON; throws naming why not. */
+export const parseJson = (source) => {
+    let raw;
+    try {
+        raw = JSON.parse(source);
+    }
+    catch (e) {
+        throw new Error(`not JSON: ${e.message}`);
+    }
+    if (!isRecord(raw))
+        throw new Error('the config must be a JSON object');
+    return raw;
+};
+/**
+ * The baseline a JSON text holds: exactly the `lists` named, each a list of
+ * strings. Throws naming the first list that is wrong, so a malformed
+ * baseline fails loudly rather than reading as empty.
+ *
+ * `atBase` reads the baseline as the merge base holds it, against today's
+ * lists: a list the base lacks (a list added since) is empty, and one the
+ * config no longer names (a list removed since) is ignored, so changing the
+ * lists is never an unreadable base. A list it does hold must still be well formed.
+ */
+export const parseBaseline = (source, lists, where, noun, atBase = false) => {
+    let raw;
+    try {
+        raw = JSON.parse(source);
+    }
+    catch (e) {
+        throw new Error(`${where}: not JSON: ${e.message}`);
+    }
+    if (!isRecord(raw))
+        throw new Error(`${where}: must be an object with ${lists.map((l) => `"${l}"`).join(' and ')} lists`);
+    const extra = Object.keys(raw).find((k) => !lists.includes(k));
+    if (extra !== undefined && !atBase)
+        throw new Error(`${where}: unknown list "${extra}"`);
+    const out = dict();
+    for (const name of lists) {
+        const held = Object.hasOwn(raw, name) ? raw[name] : undefined;
+        const v = atBase && held === undefined ? [] : held;
+        if (!Array.isArray(v) || !v.every((s) => typeof s === 'string'))
+            throw new Error(`${where}: "${name}" must be a list of ${noun}`);
+        out[name] = v;
+    }
+    return out;
+};
+const all = (baseline) => Object.values(baseline).flat();
+const listOf = (baseline, name) => (Object.hasOwn(baseline, name) ? baseline[name] : []);
+/**
+ * List by list: `unaccounted`, discovered and uncovered but not in its list;
+ * `stale`, in a list that does not owe it. An id in the wrong list is both.
+ */
+export const audit = (expected, actual) => {
+    const unaccounted = [];
+    const stale = [];
+    for (const name of new Set([...Object.keys(expected), ...Object.keys(actual)])) {
+        const want = listOf(expected, name);
+        const have = listOf(actual, name);
+        unaccounted.push(...want.filter((id) => !have.includes(id)));
+        stale.push(...have.filter((id) => !want.includes(id)));
+    }
+    return { unaccounted, stale };
+};
+/** The file an id names, when the id is the path itself. */
+export const wholeId = (id) => id;
+/**
+ * Entries the head baseline has that the base did not, across its lists (an
+ * entry that only changed list is not growth). `fileOf` reads the file an id
+ * names (the whole id for a path; the part before a suffix for `path#suffix`);
+ * when that file was renamed (`renamed`: new path to old path) the id counts
+ * under its old path, so a move is not growth.
+ */
+export const grownEntries = (base, head, renamed = new Map(), fileOf = wholeId) => {
+    const before = new Set(all(base));
+    const asBefore = (id) => {
+        const file = fileOf(id);
+        const old = renamed.get(file);
+        return old === undefined ? id : old + id.slice(file.length);
+    };
+    return all(head).filter((id) => !before.has(asBefore(id)));
+};
+/**
+ * The growth of the baseline at `baselinePath` since the merge base of HEAD
+ * and `base`: empty when the merge base has no baseline yet. A git failure,
+ * or a baseline the merge base holds malformed, throws.
+ */
+export const growthSince = (git, base, baselinePath, head, parse, fileOf = wholeId) => {
+    const commit = mergeBaseOf(git, base);
+    const before = fileAt(git, commit, baselinePath);
+    if (before === null)
+        return [];
+    return grownEntries(parse(before, `${baselinePath} at the merge base ${commit.slice(0, 12)}`), head, renamesSince(git, commit), fileOf);
+};
+/** The roots among `roots` under which none of `files` lies: a typo'd root reads nothing and would pass. */
+export const emptyRoots = (files, roots) => roots.filter((r) => !files.some((f) => f === r || f.startsWith(`${r}/`)));
+/** The baseline file at `at` under the root, parsed; throws when it is missing or malformed. */
+export const readBaseline = (root, at, parse) => {
+    const source = readText(root, at);
+    if (source === undefined)
+        throw new Error(`the baseline ${at} is not a readable file`);
+    return parse(source, at);
+};
+// ── suite wiring ────────────────────────────────────────────────────────────
+const EXTENSION = /\.(?:ts|tsx|mts|cts|mjs|cjs|js|jsx)$/;
+/**
+ * The module specifiers a suite imports, read from its syntax tree: each
+ * import declaration that brings in a value (`import { a } from`, a default
+ * or namespace import, `import './x'`), each `export … from`, and each
+ * `import('…')` of a literal. A specifier in a comment or another string, or
+ * a type-only import, is no import.
+ */
+export const importSpecifiers = (ts, file, source) => {
+    const out = [];
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.importClause?.isTypeOnly !== true)
+            out.push(node.moduleSpecifier.text);
+        else if (ts.isExportDeclaration(node) && !node.isTypeOnly && node.moduleSpecifier !== undefined && ts.isStringLiteral(node.moduleSpecifier))
+            out.push(node.moduleSpecifier.text);
+        else if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+            const first = node.arguments[0];
+            if (first !== undefined && ts.isStringLiteralLike(first))
+                out.push(first.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true));
+    return out;
+};
+/**
+ * Whether the suite at `suite`, importing `specifiers`, imports the module at
+ * `target` by a relative specifier: each specifier is resolved against the
+ * suite's folder, so a same-named module elsewhere does not count. A folder's
+ * `index` module may be imported by the folder.
+ */
+export const importsModule = (suite, specifiers, target) => {
+    const want = target.replace(EXTENSION, '');
+    const folder = posix.basename(want) === 'index' ? posix.dirname(want) : undefined;
+    return specifiers.some((specifier) => {
+        if (!specifier.startsWith('./') && !specifier.startsWith('../'))
+            return false;
+        const got = posix.join(posix.dirname(suite), specifier).replace(EXTENSION, '').replace(/\/$/, '');
+        return got === want || got === folder;
+    });
+};
+/** Whether `specifiers` (a suite's imports) include the bare module specifier. */
+export const importsPackage = (specifiers, specifier) => specifiers.includes(specifier);
+/** Whether the text names a module specifier as a string, either quote. */
+export const namesModule = (source, specifier) => source.includes(`'${specifier}'`) || source.includes(`"${specifier}"`);
+/** Whether a runner collects a suite at `path`, by the collected-path patterns. */
+export const isCollected = (collected, path) => collected.some((p) => p.test(path));
+/** Whether `path` is a regular file under `root`. */
+export const isFile = (root, path) => statSync(join(root, path), { throwIfNoEntry: false })?.isFile() === true;
+/** The text of a file under `root`, or undefined when it is not a readable file. */
+export const readText = (root, path) => {
+    if (!isFile(root, path))
+        return undefined;
+    try {
+        return readFileSync(join(root, path), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The `examples` key of a config: required, `null` to opt out, its `catalogue` likewise. */
+export const parseExamples = (raw, skipped) => {
+    const v = required(raw, 'examples', '', skipped, () => object(raw, 'examples', ''));
+    if (v === undefined)
+        return undefined;
+    onlyKeys(v, ['catalogue', 'fixtures'], 'examples: ');
+    const catalogue = required(v, 'catalogue', 'examples: ', skipped, () => {
+        const c = object(v, 'catalogue', 'examples: ');
+        onlyKeys(c, ['path', 'slice'], 'examples.catalogue: ');
+        return { path: path(c, 'path', 'examples.catalogue: '), slice: text(c, 'slice', 'examples.catalogue: ') };
+    });
+    const fixturesRaw = object(v, 'fixtures', 'examples: ');
+    const fixtures = dict();
+    for (const [id, entry] of Object.entries(fixturesRaw)) {
+        const where = `examples.fixtures.${id}: `;
+        if (!isRecord(entry))
+            throw new Error(`examples.fixtures.${id} must be an object`);
+        onlyKeys(entry, ['example', 'test'], where);
+        fixtures[id] = { example: text(entry, 'example', where), test: path(entry, 'test', where) };
+    }
+    if (Object.keys(fixtures).length === 0)
+        throw new Error('examples: "fixtures" is empty, so nothing would be checked');
+    return { catalogue, fixtures };
+};
+/**
+ * Findings about the catalogue examples: the fixtures cover exactly the
+ * catalogue's checks for the slice, each from its own example; each fixture
+ * suite exists where a runner collects it and names its finding id; `extra`
+ * adds what a ratchet asks of a fixture's text. An unreadable catalogue throws.
+ */
+export const checkExamples = (root, examples, collected, extra = () => []) => {
+    const out = [];
+    if (examples.catalogue !== undefined) {
+        const { path: at, slice } = examples.catalogue;
+        const source = readText(root, at);
+        if (source === undefined)
+            throw new Error(`the catalogue ${at} is not a readable file`);
+        let rows;
+        try {
+            rows = JSON.parse(source).checks;
+        }
+        catch (e) {
+            throw new Error(`the catalogue ${at}: not JSON: ${e.message}`);
+        }
+        const isRow = (r) => isRecord(r) && typeof r['id'] === 'string' && typeof r['slice'] === 'string' && typeof r['example'] === 'string';
+        if (!Array.isArray(rows) || !rows.every(isRow))
+            throw new Error(`the catalogue ${at}: "checks" must be a list of { id, slice, example }`);
+        const mine = rows.filter((r) => r.slice === slice);
+        for (const row of mine) {
+            const fixture = examples.fixtures[row.id];
+            if (fixture === undefined)
+                out.push(`${at}: ${row.id} (slice ${slice}) has no example fixture`);
+            else if (!row.example.startsWith(`${fixture.example}:`))
+                out.push(`examples.fixtures.${row.id}: the catalogue's example is not ${fixture.example} ("${row.example}")`);
+        }
+        for (const id of Object.keys(examples.fixtures)) {
+            if (!mine.some((r) => r.id === id))
+                out.push(`examples.fixtures.${id}: not a check ${at} gives slice ${slice}`);
+        }
+    }
+    for (const [id, fixture] of Object.entries(examples.fixtures)) {
+        const source = readText(root, fixture.test);
+        if (source === undefined) {
+            out.push(`${fixture.test}: the ${id} example suite does not exist`);
+            continue;
+        }
+        if (!isCollected(collected, fixture.test))
+            out.push(`${fixture.test}: no runner collects the ${id} example suite`);
+        if (!source.includes(fixture.example))
+            out.push(`${fixture.test}: the ${id} example suite does not name ${fixture.example}`);
+        out.push(...extra(id, source).map((m) => `${fixture.test}: ${m}`));
+    }
+    return out;
+};
+/** Throws when an id a finding pattern must match does not. */
+export const checkFindingIds = (pattern, ids) => {
+    if (pattern === undefined)
+        return;
+    const bad = ids.find(([, id]) => id !== undefined && !pattern.test(id));
+    if (bad !== undefined)
+        throw new Error(`${bad[0]}: "${String(bad[1])}" is not a finding id (${pattern.source})`);
+};
+/**
+ * The verdict: findings on stderr, then what to do; a one-line summary on
+ * stdout when there are none. Whatever the config opted out of, and a growth
+ * comparison not made, is printed on stdout either way, so a pass says what
+ * it did not check.
+ */
+export const formatOutcome = (prefix, findings, summary, hint, notChecked = []) => {
+    const skipped = notChecked.length === 0 ? [] : [`${prefix} not checked: ${notChecked.join(', ')}`];
+    return findings.length === 0
+        ? { ok: true, out: [`${prefix} ${summary}`, ...skipped], err: [] }
+        : { ok: false, out: skipped, err: [...findings.map((f) => `${prefix} ${f}`), `${prefix} ${findings.length} problem(s). ${hint}`] };
+};