@veda-hq/pariksha 0.5.8 → 0.5.9

package/dist/codec-registry.js

@@ -0,0 +1,360 @@
+// codec-registry: every module that hand-parses a format, and every exported
+// writer/reader pair, has a suite that holds it to a reference.
+//
+// A hand parser (a module that reads markdown, HTML, YAML, CSV, shell or
+// TypeScript source by its own regexes) registers with a property suite that
+// compares it with the format's reference parser, over both line endings. A
+// producer/consumer pair (`writeX`/`readX`, `renderX`/`parseX`…) registers with
+// a suite that feeds real producer output through the real consumer; a
+// schema-versioned digest registers with a golden. Discovery reads tracked
+// source as a syntax tree; whatever it finds is registered, exempt with a
+// reason, or in the baseline, and the baseline only shrinks.
+import { readFileSync } from 'node:fs';
+import { join, matchesGlob } from 'node:path';
+import { audit, checkExamples, checkFindingIds, formatOutcome, importSpecifiers, importsModule, importsPackage, isCollected, isFile, list, minNoteLength, namesModule, note, object, onlyKeys, optionalText, parseBaseline as parseLists, parseExamples, parseFindingIds, parseJson, path, paths, readText, reason, records, regexes, required, text, } from "./registry-ratchet.js";
+export const FORMATS = ['markdown', 'html', 'yaml', 'csv', 'shell', 'ts'];
+const PAIR_ID = /^[^#]+#(?:[A-Za-z_$][\w$]*->[A-Za-z_$][\w$]*|digest)$/;
+/**
+ * The file an id names. An id is `path#format`, `path#producer->consumer` or
+ * `path#digest`, and no suffix holds a `#`, so the path is everything before
+ * the last one: a path may itself hold a `#`.
+ */
+export const fileOf = (id) => {
+    const hash = id.lastIndexOf('#');
+    return hash === -1 ? id : id.slice(0, hash);
+};
+const isFormat = (f) => typeof f === 'string' && FORMATS.includes(f);
+/** The config a JSON text names; throws naming the first bad key. */
+export const parseConfig = (source) => {
+    const raw = parseJson(source);
+    onlyKeys(raw, ['baseline', 'roots', 'oracles', 'collected', 'surfaces', 'library', 'markers', 'handParsers', 'pairs', 'exempt', 'minNoteLength', 'examples', 'findingIds'], '');
+    const skipped = [];
+    const min = minNoteLength(raw);
+    const oraclesRaw = object(raw, 'oracles', '');
+    const oracles = {};
+    for (const [format, module] of Object.entries(oraclesRaw)) {
+        if (!isFormat(format))
+            throw new Error(`oracles: "${format}" is not a format discovery reads (${FORMATS.join(', ')})`);
+        if (typeof module !== 'string' || module === '')
+            throw new Error(`oracles.${format} must be a module name`);
+        oracles[format] = module;
+    }
+    if (Object.keys(oracles).length === 0)
+        throw new Error('"oracles" is empty, so no format would be discovered');
+    const surfaces = required(raw, 'surfaces', '', skipped, () => {
+        const globs = list(raw, 'surfaces', '');
+        if (globs.length === 0)
+            throw new Error('"surfaces" is empty; name the globs a property suite must sit on, or null to check no surface');
+        return globs.map((g, i) => {
+            if (typeof g !== 'string' || g === '')
+                throw new Error(`surfaces[${i}] must be a non-empty glob`);
+            return g;
+        });
+    });
+    const markersRaw = object(raw, 'markers', '');
+    onlyKeys(markersRaw, ['seed', 'lineEndings', 'golden'], 'markers: ');
+    const markers = { seed: text(markersRaw, 'seed', 'markers: '), lineEndings: text(markersRaw, 'lineEndings', 'markers: '), golden: text(markersRaw, 'golden', 'markers: ') };
+    const handParsers = records(list(raw, 'handParsers', ''), 'handParsers').map(({ raw: e, where }) => {
+        onlyKeys(e, ['source', 'formats', 'suite', 'outOfModel', 'lfOnly', 'motivatedBy'], where);
+        const formats = e['formats'];
+        if (!Array.isArray(formats) || formats.length === 0 || !formats.every(isFormat))
+            throw new Error(`${where}"formats" must be a non-empty list of ${FORMATS.join(', ')}`);
+        const unheld = formats.find((f) => oracles[f] === undefined);
+        if (unheld !== undefined)
+            throw new Error(`${where}"${unheld}" has no entry in "oracles", so its suite has no reference to import`);
+        return {
+            source: path(e, 'source', where),
+            formats,
+            suite: path(e, 'suite', where),
+            outOfModel: note(e, 'outOfModel', where, min, true) ?? '',
+            lfOnly: note(e, 'lfOnly', where, min, false),
+            motivatedBy: optionalText(e, 'motivatedBy', where),
+        };
+    });
+    const pairs = records(list(raw, 'pairs', ''), 'pairs').map(({ raw: e, where }) => {
+        onlyKeys(e, ['id', 'kind', 'suite', 'motivatedBy'], where);
+        const id = text(e, 'id', where);
+        if (!PAIR_ID.test(id))
+            throw new Error(`${where}"${id}" is not path#producer->consumer or path#digest`);
+        const kind = e['kind'];
+        if (kind !== 'round-trip' && kind !== 'golden')
+            throw new Error(`${where}"kind" must be "round-trip" or "golden"`);
+        // The id's shape names the kind, so a pair cannot skip the checks its
+        // kind needs: a producer->consumer pair round-trips under the property
+        // library and a seed; a digest pins a golden.
+        const shaped = id.endsWith('#digest') ? 'golden' : 'round-trip';
+        if (kind !== shaped)
+            throw new Error(`${where}"kind" is "${kind}", but "${id}" is ${shaped === 'golden' ? 'a digest, which is "golden"' : 'a producer->consumer pair, which is "round-trip"'}`);
+        return { id, kind, suite: path(e, 'suite', where), motivatedBy: optionalText(e, 'motivatedBy', where) };
+    });
+    const exempt = records(list(raw, 'exempt', ''), 'exempt').map(({ raw: e, where }) => {
+        onlyKeys(e, ['id', 'reason'], where);
+        const id = text(e, 'id', where);
+        if (!id.includes('#'))
+            throw new Error(`${where}"${id}" is not path#format or a pair id`);
+        return { id, reason: reason(e, where, min) };
+    });
+    const ids = [...handParsers.flatMap((h) => h.formats.map((f) => `${h.source}#${f}`)), ...pairs.map((p) => p.id), ...exempt.map((e) => e.id)];
+    const twice = ids.find((id, i) => ids.indexOf(id) !== i);
+    if (twice !== undefined)
+        throw new Error(`"${twice}" is registered or exempt more than once`);
+    const examples = parseExamples(raw, skipped);
+    const findingIds = parseFindingIds(raw, skipped);
+    checkFindingIds(findingIds.motivatedBy, [
+        ...handParsers.map((h) => [`handParsers ${h.source}: motivatedBy`, h.motivatedBy]),
+        ...pairs.map((p) => [`pairs ${p.id}: motivatedBy`, p.motivatedBy]),
+    ]);
+    checkFindingIds(findingIds.example, Object.entries(examples?.fixtures ?? {}).map(([id, f]) => [`examples.fixtures.${id}: example`, f.example]));
+    return {
+        baseline: path(raw, 'baseline', ''),
+        roots: paths(raw, 'roots', ''),
+        oracles,
+        collected: regexes(raw, 'collected', ''),
+        surfaces,
+        library: raw['library'] === undefined ? 'fast-check' : text(raw, 'library', ''),
+        markers,
+        handParsers,
+        pairs,
+        exempt,
+        minNoteLength: min,
+        examples,
+        findingIds,
+        skipped,
+    };
+};
+export const LISTS = ['handParsers', 'pairs'];
+/** The baseline a JSON text holds: `handParsers` and `pairs`, lists of ids (at the merge base, a missing list is empty). */
+export const parseBaseline = (source, where, atBase = false) => parseLists(source, LISTS, where, 'ids', atBase);
+// ── discovery ───────────────────────────────────────────────────────────────
+const SOURCE = /\.(?:ts|tsx|mts|cts|js|mjs|cjs)$/;
+const NOT_SOURCE = /\.(?:test|spec)\.|\.d\.ts$|(?:^|\/)(?:__tests__|__mocks__|__fixtures__|fixtures?)\/|\.fixture\./;
+/** Regex-literal bodies that read a format's syntax. */
+const REGEX_SIGNATURES = [
+    // ATX headings anchored at line start (CommonMark's 0-3 space indent
+    // included), code fences, inline link syntax.
+    ['markdown', /\^(?:\\s\*|\(\?:\\s\*\)\?| \{0,3\})?#|```|`\{3|~~~|\\\]\\\(/],
+    // A frontmatter delimiter.
+    ['yaml', /\^---|---\\r|---\\n|---\$/],
+    // A tag, closing tag, comment or `<script>` block; an opening tag by name
+    // (`<div[^>]*>`) too, but not a named group or its backreference
+    // (`(?<name>`, `\k<name>`).
+    ['html', /<script|<\\\/|<\/[a-z]|<\[\^>|<!--|<\[a-z|<\[A-Za-z|(?<!\(\?|\\k)<[a-z]/i],
+    // Import/export/require statements in source text.
+    ['ts', /\bimport\\s|\\bimport\\b|\bexport\\s|\brequire\\\(|from\\s\*\[/],
+];
+/** String literals that delimit a format by themselves. */
+const STRING_SIGNATURES = new Map([
+    ['---', 'yaml'],
+    ['```', 'markdown'],
+    ['~~~', 'markdown'],
+    ['<script', 'html'],
+]);
+const CSV_TOKEN = /\bcsv\b/i;
+const SHELL_TOKEN = /\b(?:shell|bash|argv|tokeni[sz]e)\b/i;
+/** What one module's source shows: the formats it reads by hand, its exported functions, a versioned hash. */
+export const scanSource = (ts, file, source) => {
+    const tree = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+    const formats = new Set();
+    const exported = [];
+    const quoteChars = new Set();
+    let createsHash = false;
+    let schemaMarked = false;
+    /** Functions declared in the module, exported or not, by local name. */
+    const functions = new Set();
+    /** `export { local as name }` entries, as [local, name]. */
+    const listed = [];
+    const isExported = (node) => ts.canHaveModifiers(node) && (ts.getModifiers(node) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    const visit = (node) => {
+        if (ts.isRegularExpressionLiteral(node)) {
+            const body = node.text.slice(1, node.text.lastIndexOf('/'));
+            for (const [format, signature] of REGEX_SIGNATURES)
+                if (signature.test(body))
+                    formats.add(format);
+            // A tokenizer written as ONE regex, naming both quotes and the backslash
+            // it escapes (`\\` in its source), tracks them as a hand-written one
+            // does. Quotes spread across unrelated regexes are no tokenizer.
+            const named = new Set(Array.from(body.matchAll(/['"]|\\(?=\\)/g), ([quote]) => quote));
+            if (named.size === 3)
+                for (const quote of named)
+                    quoteChars.add(quote);
+        }
+        else if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+            const format = STRING_SIGNATURES.get(node.text);
+            if (format !== undefined)
+                formats.add(format);
+            if (node.text === "'" || node.text === '"' || node.text === '\\')
+                quoteChars.add(node.text);
+            if (node.text === 'schema' && ts.isCallExpression(node.parent))
+                schemaMarked = true;
+        }
+        else if (ts.isCallExpression(node)) {
+            const callee = node.expression;
+            const first = node.arguments[0];
+            if (ts.isPropertyAccessExpression(callee) && callee.name.text === 'split' && first !== undefined && ts.isStringLiteral(first) && first.text === ',' && CSV_TOKEN.test(source))
+                formats.add('csv');
+            if (ts.isIdentifier(callee) && callee.text === 'createHash')
+                createsHash = true;
+        }
+        else if (ts.isFunctionDeclaration(node) && node.name) {
+            functions.add(node.name.text);
+            if (isExported(node))
+                exported.push(node.name.text);
+        }
+        else if (ts.isExportDeclaration(node) && !node.isTypeOnly && node.moduleSpecifier === undefined && node.exportClause !== undefined && ts.isNamedExports(node.exportClause)) {
+            // `export { writeEntry, readEntry as read }`: read once every binding is known, below.
+            // `export { type writeEntry }` exports no value, so it makes no pair.
+            for (const element of node.exportClause.elements)
+                if (!element.isTypeOnly)
+                    listed.push([(element.propertyName ?? element.name).text, element.name.text]);
+        }
+        else if (ts.isVariableStatement(node)) {
+            for (const declaration of node.declarationList.declarations) {
+                if (!ts.isIdentifier(declaration.name))
+                    continue;
+                const init = declaration.initializer;
+                const isFunction = init !== undefined && (ts.isArrowFunction(init) || ts.isFunctionExpression(init));
+                if (isFunction)
+                    functions.add(declaration.name.text);
+                if (!isExported(node))
+                    continue;
+                if (isFunction)
+                    exported.push(declaration.name.text);
+                if (/SCHEMA/.test(declaration.name.text) && init !== undefined && ts.isNumericLiteral(init))
+                    schemaMarked = true;
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(tree);
+    // An export list names functions as exports do, under their exported
+    // names; a listed constant or class is not a function.
+    for (const [local, name] of listed)
+        if (functions.has(local))
+            exported.push(name);
+    // A tokenizer that tracks both quote kinds and backslashes, in a module
+    // about shell commands, is a shell parser.
+    if (quoteChars.size === 3 && SHELL_TOKEN.test(source))
+        formats.add('shell');
+    return { formats, exported, createsHash, schemaMarked };
+};
+const PRODUCER = /^(?:build|write|render|format|serialize|encode|stringify|emit)([A-Z]\w*)$/;
+const CONSUMER = /^(?:parse|read|decode|load)([A-Z]\w*)$/;
+/** Same-module producer/consumer pairs among exported names. */
+export const pairsIn = (file, exported) => {
+    const consumers = new Map();
+    for (const name of exported) {
+        const stem = CONSUMER.exec(name)?.[1];
+        if (stem !== undefined)
+            consumers.set(stem, [...(consumers.get(stem) ?? []), name]);
+    }
+    const out = [];
+    for (const name of exported) {
+        const stem = PRODUCER.exec(name)?.[1];
+        if (stem === undefined)
+            continue;
+        for (const consumer of consumers.get(stem) ?? [])
+            out.push(`${file}#${name}->${consumer}`);
+    }
+    return out;
+};
+/** Hand parsers and producer/consumer pairs among `files` (tracked, root-relative), in the `formats` given. */
+export const discover = (ts, root, files, formats) => {
+    const handParsers = [];
+    const pairs = [];
+    for (const file of files) {
+        if (!SOURCE.test(file) || NOT_SOURCE.test(file))
+            continue;
+        const scan = scanSource(ts, file, readFileSync(join(root, file), 'utf8'));
+        for (const format of [...scan.formats].sort())
+            if (formats.has(format))
+                handParsers.push(`${file}#${format}`);
+        pairs.push(...pairsIn(file, scan.exported));
+        if (scan.createsHash && scan.schemaMarked)
+            pairs.push(`${file}#digest`);
+    }
+    return { handParsers: handParsers.sort(), pairs: pairs.sort() };
+};
+// ── accounting ──────────────────────────────────────────────────────────────
+/** Discovered ids the registered and exempt entries cover. */
+export const covered = (config) => new Set([...config.handParsers.flatMap((e) => e.formats.map((f) => `${e.source}#${f}`)), ...config.pairs.map((p) => p.id), ...config.exempt.map((e) => e.id)]);
+/** What the baseline must be: every discovered id nothing covers. */
+export const expectedBaseline = (found, cover) => ({
+    handParsers: found.handParsers.filter((id) => !cover.has(id)),
+    pairs: found.pairs.filter((id) => !cover.has(id)),
+});
+/** Findings about the registered suites: each exists where a runner collects it and holds what its kind needs. */
+export const checkWiring = (ts, root, config) => {
+    const out = [];
+    const surfaces = config.surfaces ?? [];
+    const onSurface = (suite) => config.surfaces === undefined || surfaces.some((g) => matchesGlob(suite, g));
+    const common = (what, source, suite) => {
+        if (!isFile(root, source))
+            out.push(`${what}: ${source} does not exist`);
+        if (!isCollected(config.collected, suite))
+            out.push(`${what}: no runner collects ${suite}`);
+        const body = readText(root, suite);
+        if (body === undefined) {
+            out.push(`${what}: the suite ${suite} does not exist`);
+            return undefined;
+        }
+        const imports = importSpecifiers(ts, suite, body);
+        if (!importsModule(suite, imports, source))
+            out.push(`${what}: ${suite} does not import ${source}`);
+        return { body, imports };
+    };
+    for (const entry of config.handParsers) {
+        const what = `hand parser ${entry.source}`;
+        if (!onSurface(entry.suite))
+            out.push(`${what}: ${entry.suite} is not on a property-suite surface (${surfaces.join(', ')})`);
+        const suite = common(what, entry.source, entry.suite);
+        if (suite === undefined)
+            continue;
+        const { body, imports } = suite;
+        if (!importsPackage(imports, config.library))
+            out.push(`${what}: ${entry.suite} does not import ${config.library}`);
+        for (const format of entry.formats) {
+            const oracle = config.oracles[format] ?? '';
+            if (!namesModule(body, oracle))
+                out.push(`${what}: ${entry.suite} does not import ${oracle}, the ${format} reference`);
+        }
+        if (!body.includes(config.markers.seed))
+            out.push(`${what}: ${entry.suite} runs no fixed seed (${config.markers.seed})`);
+        if (entry.lfOnly === undefined && !body.includes(config.markers.lineEndings))
+            out.push(`${what}: ${entry.suite} runs LF only; run CRLF too (${config.markers.lineEndings}) or give lfOnly a reason`);
+    }
+    for (const pair of config.pairs) {
+        const what = `pair ${pair.id}`;
+        const source = fileOf(pair.id);
+        if (pair.kind === 'round-trip' && !onSurface(pair.suite))
+            out.push(`${what}: ${pair.suite} is not on a property-suite surface (${surfaces.join(', ')})`);
+        const suite = common(what, source, pair.suite);
+        if (suite === undefined)
+            continue;
+        const { body, imports } = suite;
+        if (pair.kind === 'golden') {
+            if (!body.includes(config.markers.golden))
+                out.push(`${what}: ${pair.suite} pins no golden (${config.markers.golden})`);
+            continue;
+        }
+        if (!importsPackage(imports, config.library))
+            out.push(`${what}: ${pair.suite} does not import ${config.library}`);
+        if (!body.includes(config.markers.seed))
+            out.push(`${what}: ${pair.suite} runs no fixed seed (${config.markers.seed})`);
+    }
+    return out;
+};
+/** Every finding: wiring, examples, accounting against the baseline, and growth when `grown` is given. */
+export const findings = (ts, root, config, found, baseline, grown) => {
+    const cover = covered(config);
+    const { unaccounted, stale } = audit(expectedBaseline(found, cover), baseline);
+    const discovered = new Set([...found.handParsers, ...found.pairs]);
+    return [
+        ...checkWiring(ts, root, config),
+        ...(config.examples === undefined ? [] : checkExamples(root, config.examples, config.collected)),
+        ...[...cover].filter((id) => !discovered.has(id)).map((id) => `${id}: registered or exempt, but discovery does not find it; drop the entry, or fix what it names`),
+        ...unaccounted.map((id) => `${id}: discovered and unaccounted; register a suite for it, or exempt it with a reason`),
+        ...stale.map((id) => `${id}: in ${config.baseline}, but registered, exempt, gone or in the wrong list; remove it from the baseline`),
+        ...grown.map((id) => `${id}: added to ${config.baseline} since the merge base; the baseline only shrinks, so register a suite instead`),
+    ];
+};
+export const formatFindings = (list, found, baseline, notChecked, compared) => formatOutcome('pariksha codec-registry:', list, `${found.handParsers.length} hand parser(s) and ${found.pairs.length} pair(s) discovered, each registered, exempt or among the ${(baseline['handParsers']?.length ?? 0) + (baseline['pairs']?.length ?? 0)} baselined${compared ? '; the baseline does not grow' : ''}`, 'Register a suite for a discovered parser or pair, or exempt it with a reason; the baseline only shrinks.', notChecked);

package/dist/fault-injection-registry.js

@@ -0,0 +1,203 @@
+// fault-injection-registry: every unit whose dependencies can fail runs under
+// the repository's fault-injection harness, or says why it need not.
+//
+// A consumer is a unit (a CLI's entry, a service method) whose suite fails its
+// dependencies call by call through the harness and asserts each declared
+// check (an exit contract, containment of a best-effort step, convergence on a
+// rerun) with zero violations. Discovery finds the units that owe one by their
+// text: under each configured group's roots, a tracked source matching the
+// group's marker (a CLI entry point, a best-effort step). Whatever it finds is
+// registered, exempt with a reason, or in the baseline, and the baseline only
+// shrinks.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { audit, checkExamples, checkFindingIds, dict, formatOutcome, importSpecifiers, importsModule, importsPackage, isCollected, isRecord, list, minNoteLength, note, object, onlyKeys, optionalText, parseBaseline as parseLists, parseExamples, parseFindingIds, parseJson, path, paths, readText, reason, records, regex, regexes, text, } from "./registry-ratchet.js";
+import { moduleExports } from "./module-exports.js";
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+const LIST_NAME = /^[A-Za-z_][\w-]*$/;
+/** The config a JSON text names; throws naming the first bad key. */
+export const parseConfig = (source) => {
+    const raw = parseJson(source);
+    onlyKeys(raw, ['baseline', 'discover', 'collected', 'harness', 'consumers', 'exempt', 'exemptIn', 'minNoteLength', 'examples', 'findingIds'], '');
+    const groupsRaw = object(raw, 'discover', '');
+    const discover = dict();
+    for (const [name, group] of Object.entries(groupsRaw)) {
+        const where = `discover.${name}: `;
+        if (!LIST_NAME.test(name))
+            throw new Error(`discover: "${name}" is not a baseline list name`);
+        if (!isRecord(group))
+            throw new Error(`discover.${name} must be an object`);
+        onlyKeys(group, ['roots', 'include', 'marker'], where);
+        const marker = object(group, 'marker', where);
+        onlyKeys(marker, ['pattern', 'flags'], `${where}marker: `);
+        const flags = marker['flags'] ?? '';
+        if (typeof flags !== 'string' || !/^[imsu]*$/.test(flags))
+            throw new Error(`${where}marker.flags must be some of i, m, s, u`);
+        discover[name] = { roots: paths(group, 'roots', where), include: regex(group['include'], `${where}"include"`), marker: regex(marker['pattern'], `${where}marker.pattern`, flags) };
+    }
+    if (Object.keys(discover).length === 0)
+        throw new Error('"discover" is empty, so nothing would be discovered');
+    const harnessRaw = object(raw, 'harness', '');
+    onlyKeys(harnessRaw, ['module', 'imports', 'checks', 'heldBy'], 'harness: ');
+    const imports = list(harnessRaw, 'imports', 'harness: ').map((s, i) => {
+        if (typeof s !== 'string' || s === '' || s.startsWith('.'))
+            throw new Error(`harness.imports[${i}] must be a bare module specifier`);
+        return s;
+    });
+    const checksRaw = object(harnessRaw, 'checks', 'harness: ');
+    const checks = dict();
+    for (const [id, fn] of Object.entries(checksRaw)) {
+        if (typeof fn !== 'string' || !IDENTIFIER.test(fn))
+            throw new Error(`harness.checks.${id} must be a function name`);
+        checks[id] = fn;
+    }
+    if (Object.keys(checks).length === 0)
+        throw new Error('harness: "checks" is empty, so no suite would assert anything');
+    const heldBy = text(harnessRaw, 'heldBy', 'harness: ');
+    if (!IDENTIFIER.test(heldBy))
+        throw new Error('harness: "heldBy" must be a function name');
+    const harness = { module: path(harnessRaw, 'module', 'harness: '), imports, checks, heldBy };
+    const skipped = [];
+    const min = minNoteLength(raw);
+    const consumers = records(list(raw, 'consumers', ''), 'consumers').map(({ raw: e, where }) => {
+        onlyKeys(e, ['source', 'unit', 'checks', 'test', 'motivatedBy', 'uncovered'], where);
+        const declared = e['checks'];
+        if (!Array.isArray(declared) || declared.length === 0)
+            throw new Error(`${where}"checks" must be a non-empty list of check ids`);
+        const unknown = declared.find((c) => typeof c !== 'string' || checks[c] === undefined);
+        if (unknown !== undefined)
+            throw new Error(`${where}${JSON.stringify(unknown)} is not a check in harness.checks`);
+        return {
+            source: path(e, 'source', where),
+            unit: text(e, 'unit', where),
+            checks: declared,
+            test: path(e, 'test', where),
+            motivatedBy: optionalText(e, 'motivatedBy', where),
+            uncovered: note(e, 'uncovered', where, min, false),
+        };
+    });
+    const exemptInRaw = raw['exemptIn'];
+    if (!Array.isArray(exemptInRaw) || exemptInRaw.length === 0)
+        throw new Error('"exemptIn" must name the discovery groups an exemption may sit in');
+    const exemptIn = exemptInRaw.map((g, i) => {
+        if (typeof g !== 'string' || discover[g] === undefined)
+            throw new Error(`exemptIn[${i}]: ${JSON.stringify(g)} is not a group in "discover"`);
+        return g;
+    });
+    const exempt = records(list(raw, 'exempt', ''), 'exempt').map(({ raw: e, where }) => {
+        onlyKeys(e, ['source', 'reason'], where);
+        return { source: path(e, 'source', where), reason: reason(e, where, min) };
+    });
+    const sources = [...consumers.map((c) => c.source), ...exempt.map((e) => e.source)];
+    const twice = sources.find((s, i) => sources.indexOf(s) !== i);
+    if (twice !== undefined)
+        throw new Error(`"${twice}" is registered or exempt more than once`);
+    const examples = parseExamples(raw, skipped);
+    const unchecked = Object.keys(examples?.fixtures ?? {}).find((id) => checks[id] === undefined);
+    if (unchecked !== undefined)
+        throw new Error(`examples.fixtures.${unchecked}: not a check in harness.checks`);
+    const findingIds = parseFindingIds(raw, skipped);
+    checkFindingIds(findingIds.motivatedBy, consumers.map((c) => [`consumers ${c.source}: motivatedBy`, c.motivatedBy]));
+    checkFindingIds(findingIds.example, Object.entries(examples?.fixtures ?? {}).map(([id, f]) => [`examples.fixtures.${id}: example`, f.example]));
+    return { baseline: path(raw, 'baseline', ''), discover, collected: regexes(raw, 'collected', ''), harness, consumers, exempt, exemptIn, minNoteLength: min, examples, findingIds, skipped };
+};
+/** The baseline a JSON text holds: one list of paths per discovery group (at the merge base, read against today's groups). */
+export const parseBaseline = (source, where, config, atBase = false) => parseLists(source, Object.keys(config.discover), where, 'paths', atBase);
+// ── discovery ───────────────────────────────────────────────────────────────
+const NOT_SOURCE = /\.test\.|\.spec\.|\.d\.ts$|(^|\/)fixtures?\//;
+/** The sources among `files` (tracked, root-relative, under the group's roots) that owe a suite. */
+export const discoverGroup = (root, files, group) => files
+    .filter((file) => group.include.test(file) && !NOT_SOURCE.test(file))
+    .filter((file) => group.marker.test(readFileSync(join(root, file)).toString()))
+    .sort();
+// ── accounting ──────────────────────────────────────────────────────────────
+/** What the baseline must be now: everything discovered that no consumer or exemption covers. */
+export const expectedBaseline = (found, config) => {
+    const covered = new Set([...config.consumers.map((c) => c.source), ...config.exempt.map((e) => e.source)]);
+    return Object.fromEntries(Object.entries(found).map(([name, sources]) => [name, sources.filter((s) => !covered.has(s))]));
+};
+/** The identifier a consumer's `unit` opens with, or '' when it opens with none. */
+export const leadName = (unit) => /^[A-Za-z_$][\w$]*/.exec(unit)?.[0] ?? '';
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Findings about the harness module: it exists and exports, as a function,
+ * every function the config names. Its syntax tree is read, re-exports
+ * followed, so a type of that name, a constant holding no function, or a
+ * re-export that leads nowhere does not count.
+ */
+export const checkHarness = (ts, root, config) => {
+    const { module, checks, heldBy } = config.harness;
+    if (readText(root, module) === undefined)
+        return [`harness: ${module} does not exist`];
+    const { exports, unfollowed } = moduleExports(ts, root, module);
+    const why = unfollowed.length === 0 ? '' : ` (not followed: ${unfollowed.join(', ')})`;
+    const out = [];
+    for (const fn of new Set([...Object.values(checks), heldBy])) {
+        const kind = exports.get(fn);
+        if (kind === undefined)
+            out.push(`harness: ${module} does not export ${fn}${why}`);
+        else if (kind === 'unresolved')
+            out.push(`harness: ${module} exports ${fn}, but it resolves to no declaration${why}`);
+        else if (kind !== 'function')
+            out.push(`harness: ${module} exports ${fn} as a ${kind}, not a function`);
+    }
+    return out;
+};
+/** Findings about the registered consumers: each suite runs every declared check through the harness. */
+export const checkConsumers = (ts, root, config) => {
+    const out = [];
+    const { harness } = config;
+    for (const consumer of config.consumers) {
+        const what = `${consumer.source}`;
+        const source = readText(root, consumer.source);
+        if (source === undefined)
+            out.push(`${what}: the registered source does not exist`);
+        if (!isCollected(config.collected, consumer.test))
+            out.push(`${what}: no runner collects ${consumer.test}`);
+        const suite = readText(root, consumer.test);
+        if (suite === undefined) {
+            out.push(`${what}: the suite ${consumer.test} does not exist`);
+            continue;
+        }
+        const imports = importSpecifiers(ts, consumer.test, suite);
+        if (!importsModule(consumer.test, imports, harness.module) && !harness.imports.some((s) => importsPackage(imports, s)))
+            out.push(`${what}: ${consumer.test} does not import the harness (${[harness.module, ...harness.imports].join(' or ')})`);
+        if (!importsModule(consumer.test, imports, consumer.source))
+            out.push(`${what}: ${consumer.test} does not import ${consumer.source}`);
+        for (const check of consumer.checks) {
+            const fn = harness.checks[check] ?? '';
+            if (!suite.includes(`${fn}(`))
+                out.push(`${what}: ${consumer.test} declares ${check} but never calls ${fn}(`);
+        }
+        // Registered means held to zero violations, not merely explored.
+        if (!suite.includes(`${harness.heldBy}(`))
+            out.push(`${what}: ${consumer.test} never calls ${harness.heldBy}(, so no run is held to zero violations`);
+        const unit = leadName(consumer.unit);
+        if (unit === '')
+            out.push(`${what}: unit "${consumer.unit}" opens with no name`);
+        else if (source !== undefined && !new RegExp(String.raw `(?<![\w$])${escape(unit)}(?![\w$])`).test(source))
+            out.push(`${what}: unit ${unit} is not named in the source`);
+    }
+    return out;
+};
+/** Every finding: harness, consumers, examples, accounting against the baseline, and growth. */
+export const findings = (ts, root, config, found, baseline, grown) => {
+    const { unaccounted, stale } = audit(expectedBaseline(found, config), baseline);
+    const exemptable = new Set(config.exemptIn.flatMap((g) => found[g] ?? []));
+    const callsCheck = (id, body) => {
+        const fn = config.harness.checks[id] ?? '';
+        return body.includes(`${fn}(`) ? [] : [`the ${id} example suite never calls ${fn}(`];
+    };
+    return [
+        ...checkHarness(ts, root, config),
+        ...checkConsumers(ts, root, config),
+        ...(config.examples === undefined ? [] : checkExamples(root, config.examples, config.collected, callsCheck)),
+        ...config.exempt.filter((e) => !exemptable.has(e.source)).map((e) => `${e.source}: exempt, but discovery does not find it in ${config.exemptIn.join(' or ')}; drop the exemption`),
+        ...unaccounted.map((s) => `${s}: discovered and unaccounted; register it with a fault-injection suite, or exempt it with a reason`),
+        ...stale.map((s) => `${s}: in ${config.baseline}, but registered, exempt, renamed, gone or in the wrong list; remove it from the baseline`),
+        ...grown.map((s) => `${s}: added to ${config.baseline} since the merge base; the baseline only shrinks, so register a suite instead`),
+    ];
+};
+export const formatFindings = (list, found, baseline, notChecked, compared) => formatOutcome('pariksha fault-injection-registry:', list, `${Object.entries(found)
+    .map(([name, s]) => `${s.length} ${name}`)
+    .join(' and ')} source(s) discovered, each registered, exempt or among the ${Object.values(baseline).flat().length} baselined${compared ? '; the baseline does not grow' : ''}`, 'Register a fault-injection suite for a discovered source, or exempt it with a reason; the baseline only shrinks.', notChecked);

package/dist/git.js

@@ -1,5 +1,7 @@
 // Git, as the checks read it: a function from arguments to stdout.
 import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 /**
  * Settings that change what git prints, pinned so a user's config cannot:
  * quoted non-ASCII paths would name no file, and a column field would hide a
@@ -51,6 +53,44 @@ export const must = (git, args) => {
         throw new Error(`git ${args.join(' ')} failed`);
     return out;
 };
+/** Tracked paths under `roots` (each a literal path: a folder or one file) that still exist in the working tree. */
+export const trackedUnder = (git, root, roots) => must(git, ['ls-files', '-z', '--', ...roots.map((r) => `:(literal)${r}`)])
+    .split('\0')
+    .filter((path) => path !== '' && existsSync(join(root, path)));
+/** The merge base of HEAD and `base`; throws when git cannot name one. */
+export const mergeBaseOf = (git, base) => must(git, ['merge-base', 'HEAD', base]).trim();
+/**
+ * `path` as committed at `commit`, or null when the commit does not have it.
+ * `ls-tree` prints nothing for an absent path and fails on a real read
+ * failure, so only a confirmed absence is null.
+ */
+export const fileAt = (git, commit, path) => must(git, ['ls-tree', '--name-only', commit, '--', `:(literal)${path}`]) === '' ? null : must(git, ['show', `${commit}:${path}`]);
+/**
+ * The renames in `git diff --name-status -z` output, new path to old path.
+ * NUL-separated, so a path arrives as committed. Each entry is a status then
+ * its paths: two for a rename (`R`) or copy (`C`), one otherwise. Only a
+ * rename counts: a copy leaves its source in place.
+ */
+export const parseRenames = (nameStatus) => {
+    const renamed = new Map();
+    const fields = nameStatus.split('\0');
+    // How many of the fields that follow are the current entry's paths.
+    let paths = 0;
+    for (const [index, status] of fields.entries()) {
+        if (paths > 0) {
+            paths -= 1;
+            continue;
+        }
+        paths = status.startsWith('R') || status.startsWith('C') ? 2 : 1;
+        const from = fields[index + 1];
+        const to = fields[index + 2];
+        if (status.startsWith('R') && from !== undefined && to !== undefined)
+            renamed.set(to, from);
+    }
+    return renamed;
+};
+/** Files renamed between `commit` and the working tree (staged files count), new path to old path, by git's own rename detection. */
+export const renamesSince = (git, commit) => parseRenames(must(git, ['diff', '--name-status', '-z', '-M', '--no-ext-diff', commit]));
 export const BASE_CANDIDATES = ['origin/main', 'origin/develop', 'origin/master', 'main'];
 /** The first ref that names a commit, or undefined. */
 export const resolveBase = (git, candidates = BASE_CANDIDATES) => candidates.find((ref) => git.run(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]) !== undefined);