@veda-hq/pariksha 0.5.11 → 0.5.12

package/README.md

@@ -4,8 +4,8 @@
 test-quality ratchets. Part of [Veda](https://github.com/veda-hq/veda).
 
 ```sh
-npx @veda-hq/pariksha@0.5.11 <check> [flags]
-npx @veda-hq/pariksha@0.5.11 --version
+npx @veda-hq/pariksha@0.5.12 <check> [flags]
+npx @veda-hq/pariksha@0.5.12 --version
 ```
 
 Every check exits 0 when the repository passes, 1 when it refuses something
@@ -263,6 +263,105 @@ row that is not `` | `path` | bytes | ``, since nothing would enforce it.
 The table file is read on every check too, so it must budget itself: a row
 for its own path (relative to `--root`) is required.
 
+## `enforcement-claims`
+
+```sh
+pariksha enforcement-claims --config <file> [--root <dir>]
+```
+
+A standard that says how it is enforced is believed, and nothing else checks
+it: a standard can claim an ESLint rule that was never configured, or one
+configured only in a workspace it does not apply to, or a validator nothing
+runs, and the corpus reads as enforced while nothing runs. This check holds
+each claim to the repository's real configuration. The JSON `--config`
+(relative to the root) names every repository-specific path:
+
+```json
+{
+  "id": "STD-001",
+  "standards": "docs/standards",
+  "workspaces": [
+    { "dir": ".", "probes": ["scripts/probe.ts", "scripts/probe.test.ts"] },
+    { "dir": "apps/api", "probes": ["src/probe.ts", "src/probe.test.ts"] }
+  ],
+  "dispatcher": { "path": "scripts/run-validation.sh" },
+  "packageRunner": { "path": "scripts/validate-package.sh", "call": "run_validator", "validatorsDir": "scripts/validators" },
+  "stageRoots": { "hooks": [".husky"], "workflows": [".github/workflows"], "actions": [".github/actions"] },
+  "runnable": { "prefixes": ["scripts/", ".claude/scripts/", "apps/*/scripts/"], "extensions": ["sh", "ts", "mjs", "js"], "bin": "node_modules/.bin" },
+  "workspaceList": { "pnpm": "pnpm-workspace.yaml", "turbo": "turbo.json" },
+  "tests": { "file": "\\.test\\.tsx?$", "runner": "\\bvitest\\b|\\s--test\\b" }
+}
+```
+
+The standards are the `.md` files under `standards`, read recursively; their
+YAML frontmatter is the contract:
+
+| Field | Meaning |
+| --- | --- |
+| `id` | the standard's id, printed with its problems |
+| `enforcement` | `eslint-rule` and `validator` are checked; other values (`guidance`, …) claim no gate. A file with none is not a standard |
+| `enforcement_config` | for `eslint-rule`, the rules, comma-separated; for `validator`, may cite `<dispatcher file name> <target>` |
+| `partial_gates` | rules that gate part of a standard, on any `enforcement`; checked like `enforcement_config` |
+| `applies_to` | workspace paths or prefixes, a list or one string |
+| `enforcement_script` | for `validator`, the script or test file the claim runs |
+| `status: deprecated` | a retired standard claims nothing |
+
+Frontmatter is parsed as YAML (block lists, multiline flow lists and a bare
+scalar `applies_to` all read as lists); frontmatter that does not parse is
+skipped, not counted.
+
+- **eslint-rule.** Each workspace's flat config is resolved through ESLint
+  (`new ESLint({ cwd: dir }).calculateConfigForFile` on each probe, so
+  plugins load from the repository), and a rule is on at error or warn; `off`
+  is a false claim. A rule name is one token (`eqeqeq`, `no-console`,
+  `@scope/plugin/rule`; a parenthetical is dropped), so prose names nothing,
+  and a claim naming no rule is refused. `linterOptions.noInlineConfig` may
+  be claimed like a rule. Each named rule must be on in EVERY workspace an
+  `applies_to` target covers: a prefix covers every workspace under it, and
+  a path under none is the root workspace's (`.`).
+- **validator.** A cited `<dispatcher> <target>` must be a case of the
+  dispatcher, a shell `case` whose lines read `name)` or `a|b)` (any alias
+  counts). Then every path the claim names (`enforcement_script`, and the
+  paths the target's case names) must exist, and at least one of them must be
+  reached from a stage: the files directly in
+  each `hooks` folder (not those starting with `_`) and each workflow under
+  `workflows`, with the local actions they `uses: ./<actions folder>/<name>`.
+  The walk follows a path a command names under a `runnable.prefixes`
+  folder (a `*` segment is one folder) with one of its `extensions`, resolved
+  from the caller's folder; a `<bin>/<name>` binary in command position (not
+  `test -x <bin>/<name>`); a dispatcher call, to that target's case only (the
+  dispatcher file is never followed whole); a package runner's `<call> "X"`,
+  to `<validatorsDir>/X.sh`; `pnpm [run] <script>`, to the calling
+  workspace's script (workspaces from the pnpm file's `packages:`, `dir/*`
+  expanded, `!` exclusions removed); and `turbo run <task>`, to every
+  workspace's script of that name and the root's when the turbo config names
+  `//#<task>`. Shell scripts and hooks are followed; nothing else is
+  (TypeScript included). In a workflow or action only a step's `run:` and
+  `uses:` are read (not `paths:` filters, `name:` fields or `with:` inputs),
+  each run from the step's `working-directory`, else the job's or workflow's
+  `defaults.run.working-directory`, else the root; in shell, comment lines and
+  `echo`/`printf` lines are not calls. A cited test
+  file (`tests.file`) counts as run when a reached script of its workspace
+  matches `tests.runner`.
+
+`id` is optional and only labels the output. `packageRunner`, `bin` and
+`turbo` are optional (absent or `null`: none, so less is reached). Exit 0
+prints `pariksha enforcement-claims (<id>): every eslint-rule claim is real
+and every validator claim runs at a stage (<eslint-rule> + <validator> of
+<standards> rule(s))`. Exit 1 prints one line per problem, ``<file> (<id>):
+`<rule or path>` <reason>``, and a count. Exit 2: a bad config (an unknown,
+missing or bad key, a path that is not a normalized root-relative POSIX path,
+a prefix that is not a folder path, a workspace listed twice), no standard
+declaring an enforcement (the scan failed), a missing standards folder,
+dispatcher or workspace folder, a workspace whose every probe fails to
+resolve a config, or no `eslint`. The stage walk runs only when some live
+standard claims `validator`; then a missing pnpm workspace file or turbo
+config, a workflow that is not YAML and a `package.json` that is not JSON
+exit 2 too.
+
+Needs `eslint` `>=9.24 <10` installed beside pariksha (an optional peer
+dependency: only this check loads it).
+
 ## `env-gate-switches`
 
 ```sh

package/dist/cli.js

@@ -17,6 +17,7 @@ import { BASE_CANDIDATES, gitAt, gitAtTop, must, resolveBase, topOf, trackedUnde
 import { discover as discoverCodecs, fileOf as codecFileOf, findings as codecFindings, formatFindings as formatCodecFindings, parseBaseline as parseCodecBaseline, parseConfig as parseCodecConfig } from "./codec-registry.js";
 import { discoverGroup, findings as faultFindings, formatFindings as formatFaultFindings, parseBaseline as parseFaultBaseline, parseConfig as parseFaultConfig } from "./fault-injection-registry.js";
 import { emptyRoots, growthSince, readBaseline, wholeId } from "./registry-ratchet.js";
+import { checkClaims, formatOutcome, loadEslint, parseConfig as parseClaimsConfig } from "./enforcement-claims.js";
 export const DENY_FILE = '.veda/deny.sha256';
 const USAGE = [
     'usage: pariksha authority-citations [--mode staged|tree] [--authority <a,b>] [--issue-prefix <A,B>] [--adr-dir <dir>] [--root <dir>]',
@@ -25,6 +26,7 @@ const USAGE = [
     '       pariksha coverage-by-type [--config <file>] [--files-from <file>|-] [--root <dir>]',
     '       pariksha coverage-exemptions --config <file> [--package <dir>] [--root <dir>]',
     '       pariksha doc-budgets --table <file> [--section <name>] [--root <dir>]',
+    '       pariksha enforcement-claims --config <file> [--root <dir>]',
     '       pariksha env-gate-switches --config <file> [--mode staged|tree] [--root <dir>]',
     '       pariksha export-deletions [--base <ref>] [--root <dir>]',
     '       pariksha fault-injection-registry --config <file> [--base <ref> | --no-base] [--root <dir>]',
@@ -127,6 +129,33 @@ const docBudgets = (f, io) => {
     outcome.err.forEach(io.err);
     return outcome.ok ? 0 : 1;
 };
+const enforcementClaims = async (f, io) => {
+    const configPath = f.get('--config');
+    if (configPath === undefined) {
+        io.err(USAGE);
+        return 2;
+    }
+    const root = resolve(f.get('--root') ?? '.');
+    let P = 'pariksha enforcement-claims:';
+    try {
+        const config = parseClaimsConfig(readFileSync(resolve(root, configPath), 'utf8'));
+        if (config.id !== undefined)
+            P = `pariksha enforcement-claims (${config.id}):`;
+        const ESLint = await (io.eslint ?? loadEslint)();
+        if (typeof ESLint === 'string') {
+            io.err(`${P} ${ESLint}`);
+            return 2;
+        }
+        const result = formatOutcome(P, await checkClaims(root, config, ESLint));
+        result.out.forEach(io.out);
+        result.err.forEach(io.err);
+        return result.ok ? 0 : 1;
+    }
+    catch (e) {
+        io.err(`${P} ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+};
 const exportDeletions = (f, io) => {
     const dir = resolve(f.get('--root') ?? '.');
     const git = gitAtTop(dir);
@@ -474,10 +503,12 @@ const COMMANDS = {
     boundary: { allowed: ['--root', '--deny'], run: boundary },
     'coverage-by-type': { allowed: ['--config', '--files-from', '--root'], run: coverageByType },
     'doc-budgets': { allowed: ['--table', '--section', '--root'], run: docBudgets },
+    'enforcement-claims': { allowed: ['--config', '--root'], run: enforcementClaims },
     'env-gate-switches': { allowed: ['--config', '--mode', '--root'], run: envGateSwitches },
     'export-deletions': { allowed: ['--base', '--root'], run: exportDeletions },
     'required-settings': { allowed: ['--require', '--settings', '--root'], run: requiredSettings },
 };
+/** The exit code; a Promise of it for the one check that is asynchronous (enforcement-claims, which loads ESLint). */
 export const run = (args, io, version = ownVersion(), env = process.env) => {
     const [command, ...rest] = args;
     if (command === '--version' && rest.length === 0) {
@@ -501,7 +532,7 @@ const isMain = () => {
     return entry !== undefined && realpathSync(entry) === fileURLToPath(import.meta.url);
 };
 if (isMain()) {
-    process.exitCode = run(process.argv.slice(2), {
+    process.exitCode = await run(process.argv.slice(2), {
         out: (line) => console.info(line),
         err: (line) => console.error(line),
     });

package/dist/enforcement-claims.js

@@ -0,0 +1,334 @@
+// enforcement-claims: a standard's frontmatter says how it is enforced, and
+// nothing else checks that the description is true. A standard can claim
+// `enforcement: eslint-rule` naming a rule that was never configured, or one
+// configured in one workspace and not the one it `applies_to`, or claim
+// `enforcement: validator` naming a script nothing runs; the corpus then reads
+// as enforced while nothing runs. The document asserting the guarantee is the
+// one nobody can verify by reading.
+//
+// This resolves each configured workspace's REAL flat config through the
+// ESLint API, and holds every rule a standard names to being on (error or
+// warn) in every workspace it applies to; a rule at `off` is a false claim.
+// Validator claims must name a dispatcher target that exists, and something
+// a stage runs (stage-reach.ts).
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, join, posix, relative, resolve } from 'node:path';
+import { load } from 'js-yaml';
+import { isRecord, isRepoPath, list, object, onlyKeys, optionalText, parseJson, path, paths, records, regex, text } from "./registry-ratchet.js";
+import { dispatcherTargets, findUncalledValidators, runnablePatterns } from "./stage-reach.js";
+const KEYS = ['id', 'standards', 'workspaces', 'dispatcher', 'packageRunner', 'stageRoots', 'runnable', 'workspaceList', 'tests'];
+/** A list of folder paths, empty when absent or empty. */
+const folders = (raw, key, where) => {
+    const v = list(raw, key, where);
+    return v.length === 0 ? [] : paths(raw, key, where);
+};
+/** An optional object key: absent or null is none. */
+const optional = (raw, key) => (raw[key] === undefined || raw[key] === null ? undefined : object(raw, key, ''));
+const PREFIX = /^(?:(?:[\w.-]+|\*)\/)+$/;
+/** The config text: every repository-specific literal of the check. Throws naming the first bad key. */
+export const parseConfig = (source) => {
+    const raw = parseJson(source);
+    onlyKeys(raw, KEYS, '');
+    const workspaces = records(list(raw, 'workspaces', ''), 'workspaces').map(({ raw: w, where }) => {
+        onlyKeys(w, ['dir', 'probes'], where);
+        const dir = text(w, 'dir', where);
+        if (dir !== '.' && !isRepoPath(dir))
+            throw new Error(`${where}"dir": "${dir}" is not "." or a normalized root-relative path`);
+        return { dir, probes: paths(w, 'probes', where) };
+    });
+    if (workspaces.length === 0)
+        throw new Error('"workspaces" is empty, so no rule could be found enabled');
+    const dirs = workspaces.map((w) => w.dir);
+    const twice = dirs.find((d, i) => dirs.indexOf(d) !== i);
+    if (twice !== undefined)
+        throw new Error(`workspace "${twice}" is listed more than once`);
+    const dispatcherRaw = object(raw, 'dispatcher', '');
+    onlyKeys(dispatcherRaw, ['path'], 'dispatcher: ');
+    const dispatcher = path(dispatcherRaw, 'path', 'dispatcher: ');
+    const runnerRaw = optional(raw, 'packageRunner');
+    let packageRunner;
+    if (runnerRaw !== undefined) {
+        onlyKeys(runnerRaw, ['path', 'call', 'validatorsDir'], 'packageRunner: ');
+        const call = text(runnerRaw, 'call', 'packageRunner: ');
+        if (!/^[A-Za-z_][\w-]*$/.test(call))
+            throw new Error('packageRunner: "call" must be a shell function name');
+        packageRunner = { path: path(runnerRaw, 'path', 'packageRunner: '), call, validatorsDir: path(runnerRaw, 'validatorsDir', 'packageRunner: ') };
+    }
+    const stages = object(raw, 'stageRoots', '');
+    onlyKeys(stages, ['hooks', 'workflows', 'actions'], 'stageRoots: ');
+    const hooks = folders(stages, 'hooks', 'stageRoots: ');
+    const workflows = folders(stages, 'workflows', 'stageRoots: ');
+    if (hooks.length + workflows.length === 0)
+        throw new Error('stageRoots: "hooks" and "workflows" are both empty, so no stage would be walked');
+    const runnableRaw = object(raw, 'runnable', '');
+    onlyKeys(runnableRaw, ['prefixes', 'extensions', 'bin'], 'runnable: ');
+    const prefixes = list(runnableRaw, 'prefixes', 'runnable: ').map((p, i) => {
+        if (typeof p !== 'string' || !PREFIX.test(p) || p.split('/').some((s) => s === '.' || s === '..')) {
+            throw new Error(`runnable.prefixes[${i}]: ${JSON.stringify(p)} is not a folder path ending in "/" (a "*" segment is one folder)`);
+        }
+        return p;
+    });
+    if (prefixes.length === 0)
+        throw new Error('runnable: "prefixes" is empty, so no command would name a script');
+    const extensions = list(runnableRaw, 'extensions', 'runnable: ').map((e, i) => {
+        if (typeof e !== 'string' || !/^[A-Za-z0-9]+$/.test(e))
+            throw new Error(`runnable.extensions[${i}]: ${JSON.stringify(e)} is not a file extension without its dot`);
+        return e;
+    });
+    if (extensions.length === 0)
+        throw new Error('runnable: "extensions" is empty, so no command would name a script');
+    const bin = runnableRaw['bin'] === undefined || runnableRaw['bin'] === null ? undefined : path(runnableRaw, 'bin', 'runnable: ');
+    const listRaw = object(raw, 'workspaceList', '');
+    onlyKeys(listRaw, ['pnpm', 'turbo'], 'workspaceList: ');
+    const turbo = listRaw['turbo'] === undefined || listRaw['turbo'] === null ? undefined : path(listRaw, 'turbo', 'workspaceList: ');
+    const tests = object(raw, 'tests', '');
+    onlyKeys(tests, ['file', 'runner'], 'tests: ');
+    return {
+        id: optionalText(raw, 'id', ''),
+        standards: path(raw, 'standards', ''),
+        workspaces,
+        dispatcher,
+        dispatchCall: new RegExp(`${basename(dispatcher).replace(/[.*+?^${}()|[\]\\/-]/g, '\\$&')}\\s+([a-z][a-z0-9-]*)`),
+        packageRunner,
+        hooks,
+        workflows,
+        actions: folders(stages, 'actions', 'stageRoots: '),
+        runnable: runnablePatterns(prefixes, extensions, bin),
+        workspaceFile: path(listRaw, 'pnpm', 'workspaceList: '),
+        turbo,
+        testFile: regex(tests['file'], 'tests.file'),
+        testRunner: regex(tests['runner'], 'tests.runner'),
+    };
+};
+const markdown = (dir, out = []) => {
+    for (const entry of readdirSync(dir).sort()) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            markdown(full, out);
+        else if (entry.endsWith('.md'))
+            out.push(full);
+    }
+    return out;
+};
+/**
+ * The standards under `dir` that declare an enforcement, sorted by file.
+ *
+ * Frontmatter is PARSED AS YAML, not matched with regexes: a regex read the
+ * block form's first entry as `- apps/api` and dropped the rest, and its
+ * repair still read a multiline flow list as [], which is indistinguishable
+ * from "declares no workspace": a silent skip of the very check. Frontmatter
+ * that does not parse is skipped, never counted as a standard that passed.
+ */
+export const readStandards = (root, dir) => {
+    const standards = [];
+    for (const file of markdown(join(root, dir))) {
+        const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(readFileSync(file, 'utf8'));
+        if (match === null)
+            continue;
+        let frontmatter;
+        try {
+            const loaded = load(match[1]);
+            if (!isRecord(loaded))
+                continue;
+            frontmatter = loaded;
+        }
+        catch {
+            continue;
+        }
+        const field = (name) => {
+            const value = frontmatter[name];
+            if (value === undefined || value === null)
+                return '';
+            return typeof value === 'string' ? value.trim() : String(value);
+        };
+        // A bare scalar is a one-entry list: `applies_to: apps/api` claims one
+        // workspace, and reading it as no claim would be the silent skip again.
+        const listField = (name) => {
+            const value = frontmatter[name];
+            return (Array.isArray(value) ? value : [value])
+                .filter((entry) => typeof entry === 'string')
+                .map((entry) => entry.trim())
+                .filter(Boolean);
+        };
+        const enforcement = field('enforcement');
+        if (enforcement === '')
+            continue;
+        standards.push({
+            file: relative(root, file).split('\\').join('/'),
+            id: field('id'),
+            enforcement,
+            enforcementConfig: field('enforcement_config'),
+            partialGates: field('partial_gates'),
+            appliesTo: listField('applies_to'),
+            enforcementScript: field('enforcement_script'),
+            deprecated: field('status') === 'deprecated',
+        });
+    }
+    return standards.sort((a, b) => a.file.localeCompare(b.file));
+};
+/**
+ * The rule names a claim names. Entries are prose as often as not, and a
+ * parenthetical narrows a rule rather than naming one (`no-restricted-globals
+ * (Buffer)`). A rule name is one unbroken token, hyphen or not (`eqeqeq`,
+ * `curly`); prose is a sentence. An empty claim names nothing.
+ */
+export const claimedRules = (claim) => 
+// Parentheticals go first: `no-restricted-globals (Buffer, process)` is one rule.
+(claim.replace(/\([^)]*\)/g, '').match(/[^,]+/g) ?? []).map((part) => part.trim()).filter((part) => /^[@a-z][\w@/.-]*$/i.test(part));
+/** Is one resolved rule setting on (error or warn), as a number or a word, bare or an options array's head? */
+export const ruleIsOn = (setting) => {
+    const severity = Array.isArray(setting) ? setting[0] : setting;
+    return severity !== 0 && severity !== 'off';
+};
+/** The claim token for `linterOptions.noInlineConfig`, which refuses every inline directive as a rule would. */
+export const NO_INLINE_CONFIG = 'linterOptions.noInlineConfig';
+/** ESLint's class from pariksha's resolution of the `eslint` peer; a message naming why not when it cannot be loaded. */
+export const loadEslint = async (load = () => import('eslint')) => {
+    try {
+        const mod = await load();
+        if (typeof mod.ESLint === 'function')
+            return mod.ESLint;
+    }
+    catch {
+        // not installed beside pariksha
+    }
+    return 'needs the eslint package (>=9.24 <10) installed beside pariksha';
+};
+/**
+ * Every rule that is on in each workspace's resolved config, by workspace. A
+ * probe ESLint ignores contributes nothing; one whose config does not load is
+ * skipped while another probe of the workspace resolves, and a workspace no
+ * probe resolves exits 2, since its rules would read as all off.
+ */
+export const activeRules = async (ESLint, root, workspaces) => {
+    const resolved = await Promise.all(workspaces.map(async (workspace) => {
+        const cwd = resolve(root, workspace.dir);
+        if (!statSync(cwd, { throwIfNoEntry: false })?.isDirectory())
+            throw new Error(`workspace "${workspace.dir}" is not a folder under the root`);
+        const eslint = new ESLint({ cwd });
+        const settled = await Promise.allSettled(workspace.probes.map((probe) => eslint.calculateConfigForFile(resolve(cwd, probe))));
+        const failed = settled.find((s) => s.status === 'rejected');
+        if (failed !== undefined && settled.every((s) => s.status === 'rejected')) {
+            throw new Error(`no probe of workspace "${workspace.dir}" resolves a config: ${failed.reason.message}`);
+        }
+        const active = new Set();
+        for (const s of settled) {
+            if (s.status === 'rejected' || !isRecord(s.value))
+                continue;
+            const rules = s.value['rules'];
+            if (isRecord(rules))
+                for (const [name, setting] of Object.entries(rules))
+                    if (ruleIsOn(setting))
+                        active.add(name);
+            const options = s.value['linterOptions'];
+            if (isRecord(options) && options['noInlineConfig'] === true)
+                active.add(NO_INLINE_CONFIG);
+        }
+        return [workspace.dir, active];
+    }));
+    return new Map(resolved);
+};
+/**
+ * Every workspace an `applies_to` target covers. A target is a path prefix
+ * and names a SET: `packages` covers every workspace under it, and each must
+ * enforce the rule. A target under no workspace belongs to the root one,
+ * where root-level folders live.
+ */
+export const ownersOf = (target, workspaces) => {
+    const matches = [...workspaces].filter((dir) => target === dir || target.startsWith(`${dir}/`) || dir.startsWith(`${target}/`));
+    return matches.length > 0 ? matches : ['.'];
+};
+const verifyRules = (standard, rules, field, problems, anywhere, byWorkspace) => {
+    for (const rule of rules) {
+        if (!anywhere.has(rule)) {
+            problems.push({ file: standard.file, id: standard.id, rule, reason: `(${field}) is not enabled in ANY workspace config — the claim is false` });
+            continue;
+        }
+        const scopes = standard.appliesTo
+            .flatMap((target) => ownersOf(target, byWorkspace.keys()))
+            .map((dir) => byWorkspace.get(dir))
+            .filter((active) => active !== undefined);
+        // EVERY, not some: a rule enabled in one of two claimed workspaces is
+        // unenforced in the other. No applies_to has no scope, and passes.
+        if (!scopes.every((active) => active.has(rule))) {
+            problems.push({
+                file: standard.file,
+                id: standard.id,
+                rule,
+                reason: `(${field}) is enabled elsewhere but NOT in ${standard.appliesTo.join(', ')}, which is where this rule claims to apply`,
+            });
+        }
+    }
+};
+/** The eslint-rule, partial_gates and dispatcher-target problems, against each workspace's active rules. */
+export const findEnforcementProblems = (standards, byWorkspace, dispatch, config) => {
+    const anywhere = new Set([...byWorkspace.values()].flatMap((rules) => [...rules]));
+    const targets = dispatcherTargets(dispatch);
+    const problems = [];
+    for (const standard of standards) {
+        // A retired standard claims nothing.
+        if (standard.deprecated)
+            continue;
+        // partial_gates is verified whatever the enforcement mode: the field
+        // exists to be usable on a guidance standard. Prose there names no rule,
+        // would check nothing, and is refused like an empty eslint-rule claim.
+        const partial = claimedRules(standard.partialGates);
+        if (standard.partialGates !== '' && partial.length === 0) {
+            problems.push({ file: standard.file, id: standard.id, rule: standard.partialGates, reason: '(partial_gates) names no rule this gate can adjudicate — a partial gate that cannot be checked is not a gate' });
+        }
+        verifyRules(standard, partial, 'partial_gates', problems, anywhere, byWorkspace);
+        // A validator claim naming a dispatcher target must name a real one, by
+        // any alias on its case line; otherwise relabelling an eslint-rule claim
+        // as a validator would be the cheapest way past this check.
+        if (standard.enforcement === 'validator') {
+            const target = config.dispatchCall.exec(standard.enforcementConfig);
+            if (target !== null && !targets.has(target[1])) {
+                problems.push({ file: standard.file, id: standard.id, rule: target[1], reason: `is not a case in ${config.dispatcher} — the command does not exist` });
+            }
+            continue;
+        }
+        if (standard.enforcement !== 'eslint-rule')
+            continue;
+        const rules = claimedRules(standard.enforcementConfig);
+        if (rules.length === 0) {
+            problems.push({
+                file: standard.file,
+                id: standard.id,
+                rule: standard.enforcementConfig || '(empty)',
+                reason: 'claims eslint-rule enforcement but enforcement_config names no rule — nothing here can be checked, by a reader or by this gate',
+            });
+            continue;
+        }
+        verifyRules(standard, rules, 'enforcement_config', problems, anywhere, byWorkspace);
+    }
+    return problems;
+};
+/** Reads the standards and checks every claim; throws on anything that leaves the check unable to run. */
+export const checkClaims = async (root, config, ESLint) => {
+    const dir = statSync(join(root, config.standards), { throwIfNoEntry: false });
+    if (!dir?.isDirectory())
+        throw new Error(`the standards folder ${config.standards} is not a folder under the root`);
+    const standards = readStandards(root, config.standards);
+    if (standards.length === 0)
+        throw new Error(`no standard under ${config.standards} declares an enforcement — the scan failed`);
+    const dispatch = readFileSync(posix.join(root, config.dispatcher), 'utf8');
+    const byWorkspace = await activeRules(ESLint, root, config.workspaces);
+    return { standards, problems: [...findEnforcementProblems(standards, byWorkspace, dispatch, config), ...findUncalledValidators(root, standards, config)] };
+};
+/** The verdict lines: each problem, or the counts of the claims that held. */
+export const formatOutcome = (prefix, outcome) => {
+    const { standards, problems } = outcome;
+    if (problems.length > 0) {
+        return {
+            ok: false,
+            out: [],
+            err: [
+                ...problems.map((p) => `${prefix} ${p.file} (${p.id || 'no id'}): \`${p.rule}\` ${p.reason}`),
+                `${prefix} ${problems.length} untrue enforcement claim(s); a standard whose enforcement is described wrongly reads as enforced while nothing runs`,
+            ],
+        };
+    }
+    const claimed = standards.filter((s) => s.enforcement === 'eslint-rule' && !s.deprecated).length;
+    const run = standards.filter((s) => s.enforcement === 'validator' && !s.deprecated).length;
+    return { ok: true, out: [`${prefix} every eslint-rule claim is real and every validator claim runs at a stage (${claimed} + ${run} of ${standards.length} rule(s))`], err: [] };
+};

package/dist/stage-reach.js

@@ -0,0 +1,337 @@
+// enforcement-claims, second half: a validator claim must name something a
+// stage RUNS. A dispatcher target that exists proves nothing: a standard can
+// name a working validator that no hook, workflow or task ever calls, and
+// that validator can fail on the default branch for months unseen.
+//
+// This walks what the stages execute, from the roots out:
+//
+//   roots       the files directly in each hooks folder (not those starting
+//               with `_`) and the `.yml`/`.yaml` workflows, plus the local
+//               actions a workflow or action `uses: ./<actions folder>/<name>`
+//   paths       a path a command names under a configured prefix, with a
+//               configured extension, resolved against the caller's working
+//               directory (a package script's `../../scripts/x.sh` is the
+//               root's `scripts/x.sh`); shell scripts and hooks are followed,
+//               nothing else is (a runner that spawns any command would make
+//               everything reachable); a `<bin>/<name>` binary in command
+//               position is reached the same way
+//   dispatcher  `<dispatcher> <target>` resolves to that target's case block
+//               only; the dispatcher FILE is never followed, since it names
+//               every target
+//   package     `<call> "X"` in the package runner resolves to
+//               `<validatorsDir>/X.sh`
+//   pnpm        `pnpm [run] <script>` resolves to the calling workspace's script
+//   turbo       `turbo run <task>` resolves to every workspace's script of that
+//               name, and to the root's when the turbo config declares
+//               `//#<task>`
+//
+// A cited test file counts as run when a reached script of its workspace runs
+// a test runner. A runner's include and exclude globs are not modelled.
+//
+// Only code lines are read: full-line comments and lines starting with `echo`
+// or `printf` are dropped, since hooks print commands for a person to run. A
+// workflow or action is parsed as YAML and only its `run:` steps are read: a
+// `paths:` filter or a step `name:` that mentions a script watches or
+// describes it, it does not run it.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { posix } from 'node:path';
+import { load } from 'js-yaml';
+/** The repository root, both as a working directory and as a workspace key. */
+export const ROOT_DIR = '.';
+const read = (root, path) => readFileSync(posix.join(root, path), 'utf8');
+/** Drops comments and printed text, keeping the lines a shell or runner executes. */
+export const codeLines = (text) => text
+    .split('\n')
+    .filter((line) => !/^\s*(?:#|echo\b|printf\b)/.test(line))
+    .join('\n');
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\/-]/g, '\\$&');
+const isNode = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * A `working-directory` as a root-relative folder (GitHub resolves it against
+ * the checkout); `fallback` when there is none, or when it is an expression,
+ * absolute, or climbs out of the root.
+ */
+const workingDir = (value, fallback) => {
+    if (typeof value !== 'string' || value.trim() === '' || value.includes('${{') || posix.isAbsolute(value.trim()))
+        return fallback;
+    const dir = posix.normalize(value.trim()).replace(/\/$/, '');
+    return dir === '..' || dir.startsWith('../') ? fallback : dir;
+};
+/** A workflow's or job's `defaults.run.working-directory`, else `fallback`. */
+const defaultsDir = (node, fallback) => {
+    const defaults = node['defaults'];
+    const run = isNode(defaults) ? defaults['run'] : undefined;
+    return isNode(run) ? workingDir(run['working-directory'], fallback) : fallback;
+};
+/**
+ * What a workflow or action executes: the `run:` of each step (an entry of a
+ * `steps` list, in the folder its `working-directory` or the enclosing
+ * `defaults.run.working-directory` names), and the local actions a step
+ * `uses:`. A `run` or `uses` anywhere else (an action input under `with:`, an
+ * env value) executes nothing.
+ */
+export const yamlCommands = (text, actionDirs) => {
+    const runs = [];
+    const actions = [];
+    const local = actionDirs.map((dir) => new RegExp(`\\./(${escape(dir)}/[\\w-]+)`));
+    const step = (s, dir) => {
+        if (typeof s['run'] === 'string')
+            runs.push({ text: s['run'], dir: workingDir(s['working-directory'], dir) });
+        const uses = s['uses'];
+        if (typeof uses !== 'string')
+            return;
+        for (const pattern of local) {
+            const hit = pattern.exec(uses);
+            if (hit !== null)
+                actions.push(hit[1]);
+        }
+    };
+    const walk = (node, key, dir) => {
+        if (Array.isArray(node)) {
+            for (const item of node) {
+                if (key === 'steps' && isNode(item))
+                    step(item, dir);
+                walk(item, undefined, dir);
+            }
+            return;
+        }
+        if (!isNode(node))
+            return;
+        const here = defaultsDir(node, dir);
+        for (const [child, value] of Object.entries(node))
+            walk(value, child, here);
+    };
+    walk(load(text), undefined, ROOT_DIR);
+    return { runs, actions };
+};
+/**
+ * The workspace directories the pnpm workspace file declares: a literal folder,
+ * or `dir/*` expanded to its folders holding a package.json; an exclusion
+ * (`!dir` or `!dir/*`) removes what it names. Other globs match nothing.
+ */
+export const workspaceDirs = (root, workspaceFile) => {
+    const parsed = load(read(root, workspaceFile));
+    const packages = isNode(parsed) ? parsed['packages'] : undefined;
+    if (!Array.isArray(packages))
+        return [];
+    const patterns = packages.filter((p) => typeof p === 'string');
+    const matches = (pattern, dir) => (pattern.endsWith('/*') ? dir.startsWith(pattern.slice(0, -1)) && !dir.slice(pattern.length - 1).includes('/') : dir === pattern);
+    const excluded = patterns.filter((p) => p.startsWith('!')).map((p) => p.slice(1));
+    const dirs = [];
+    for (const pattern of patterns.filter((p) => !p.startsWith('!'))) {
+        if (!pattern.endsWith('/*')) {
+            dirs.push(pattern);
+            continue;
+        }
+        const parent = pattern.slice(0, -2);
+        const full = posix.join(root, parent);
+        if (!existsSync(full))
+            continue;
+        for (const entry of readdirSync(full).sort()) {
+            if (existsSync(posix.join(full, entry, 'package.json')))
+                dirs.push(`${parent}/${entry}`);
+        }
+    }
+    return dirs.filter((dir) => !excluded.some((pattern) => matches(pattern, dir)));
+};
+const scriptsOf = (root, dir) => {
+    const file = posix.join(dir, 'package.json');
+    if (!existsSync(posix.join(root, file)))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(read(root, file));
+    }
+    catch (e) {
+        throw new Error(`${file} is not JSON: ${e.message}`);
+    }
+    const scripts = typeof parsed === 'object' && parsed !== null ? parsed.scripts : undefined;
+    if (typeof scripts !== 'object' || scripts === null)
+        return {};
+    return Object.fromEntries(Object.entries(scripts).filter((entry) => typeof entry[1] === 'string'));
+};
+/** The body of the dispatcher case that names `target` by any of its aliases, or '' when none does. */
+export const dispatcherCase = (dispatch, target) => {
+    for (const match of dispatch.matchAll(/^\s*([a-z][a-z0-9|-]*)\)\n([\s\S]*?)^\s*;;/gm)) {
+        if (match[1].split('|').includes(target))
+            return match[2];
+    }
+    return '';
+};
+/** Every alias a dispatcher case line offers: `a|b)` offers both. */
+export const dispatcherTargets = (dispatch) => new Set([...dispatch.matchAll(/^\s*([a-z][a-z0-9|-]*)\)/gm)].flatMap((line) => line[1].split('|')));
+/**
+ * The patterns for what a command can name. `prefixes` are folder paths
+ * ending in `/`, where a `*` segment is one folder name; `bin`, when set, is
+ * the folder of installed binaries, read only in command position: a line's
+ * first word, or one after a separator, `!`, a shell keyword that starts a
+ * command (`if`, `elif`, `else`, `then`, `do`, `while`, `until`) or `exec`,
+ * past any VAR=value prefixes. `test -x <bin>/x` runs nothing.
+ */
+export const runnablePatterns = (prefixes, extensions, bin) => {
+    const folder = (prefix) => prefix
+        .slice(0, -1)
+        .split('/')
+        .map((segment) => (segment === '*' ? '[\\w-]+' : escape(segment)))
+        .join('\\/');
+    const alternatives = [...prefixes].sort((a, b) => b.length - a.length).map((p) => `${folder(p)}\\/`);
+    const patterns = [new RegExp(`(?<![\\w./-])((?:\\.\\.?\\/)*(?:${alternatives.join('|')})[\\w./-]*[\\w-]\\.(?:${extensions.map(escape).join('|')}))(?![\\w])`, 'g')];
+    if (bin !== undefined) {
+        patterns.push(new RegExp(`(?:^|[;&|(!]|\\b(?:if|elif|else|then|do|while|until|exec)\\b)[^\\S\\n]*(?:\\w+=\\S*[^\\S\\n]+)*["']?((?:\\.\\.?\\/)*${escape(bin)}\\/[\\w-]+)(?![\\w./-])`, 'gm'));
+    }
+    return patterns;
+};
+/** Root-relative paths a command names, resolved from the directory it runs in; a path that climbs out of the root is dropped. */
+export const pathsIn = (text, cwd, runnable) => {
+    const paths = [];
+    for (const pattern of runnable) {
+        for (const match of text.matchAll(pattern)) {
+            const resolved = posix.normalize(posix.join(cwd, match[1]));
+            if (!resolved.startsWith('../'))
+                paths.push(resolved);
+        }
+    }
+    return paths;
+};
+/** Is `path` a file directly in one of the hooks folders? */
+const isHook = (path, hooks) => hooks.some((dir) => path.startsWith(`${dir}/`) && !path.slice(dir.length + 1).includes('/'));
+/** Walks every stage root and returns what it reaches. */
+export const resolveStageReach = (root, config) => {
+    const workspaces = workspaceDirs(root, config.workspaceFile);
+    const turbo = config.turbo === undefined ? '' : read(root, config.turbo);
+    const dispatch = read(root, config.dispatcher);
+    const reach = { files: new Set(), scripts: new Map(), workspaces };
+    const seen = new Set();
+    const runner = config.packageRunner;
+    const runnerCall = new RegExp(`${escape(runner?.call ?? '')}\\s+"([\\w-]+)"`, 'g');
+    const visitScript = (dir, name) => {
+        const scripts = scriptsOf(root, dir);
+        // Own keys only: `pnpm constructor` names no script, not Object's.
+        const command = Object.hasOwn(scripts, name) ? scripts[name] : undefined;
+        const key = `${dir}\t${name}`;
+        if (command === undefined || reach.scripts.has(key))
+            return;
+        reach.scripts.set(key, command);
+        visitText(command, dir);
+    };
+    const visitFile = (path, cwd) => {
+        const key = `${path}\t${cwd}`;
+        if (path === config.dispatcher || seen.has(key))
+            return;
+        seen.add(key);
+        const full = posix.join(root, path);
+        if (!existsSync(full) || !statSync(full).isFile())
+            return;
+        reach.files.add(path);
+        if (/\.ya?ml$/.test(path)) {
+            let commands;
+            try {
+                commands = yamlCommands(read(root, path), config.actions);
+            }
+            catch (e) {
+                throw new Error(`${path} is not YAML: ${e.message}`);
+            }
+            for (const action of commands.actions) {
+                for (const name of ['action.yml', 'action.yaml'])
+                    visitFile(`${action}/${name}`, ROOT_DIR);
+            }
+            // A workflow or action runs from the checkout, so a step's folder is root-relative.
+            for (const step of commands.runs)
+                visitText(step.text, step.dir);
+            return;
+        }
+        if (!path.endsWith('.sh') && !isHook(path, config.hooks))
+            return;
+        const text = codeLines(read(root, path));
+        if (runner !== undefined && path === runner.path) {
+            for (const match of text.matchAll(runnerCall))
+                visitFile(`${runner.validatorsDir}/${match[1]}.sh`, cwd);
+        }
+        visitText(text, cwd);
+    };
+    const visitText = (raw, cwd) => {
+        const text = codeLines(raw);
+        for (const path of pathsIn(text, cwd, config.runnable))
+            visitFile(path, cwd);
+        for (const match of text.matchAll(new RegExp(config.dispatchCall.source, 'g'))) {
+            visitText(dispatcherCase(dispatch, match[1]), ROOT_DIR);
+        }
+        for (const match of text.matchAll(/\bpnpm\s+(?:run\s+)?([a-z][\w:.-]*)/g))
+            visitScript(cwd, match[1]);
+        for (const match of text.matchAll(/\bturbo\s+run((?:\s+[^-\s|&;>][^\s|&;>]*)+)/g)) {
+            for (const task of match[1].trim().split(/\s+/)) {
+                if (task.startsWith('//#')) {
+                    visitScript(ROOT_DIR, task.slice(3));
+                    continue;
+                }
+                for (const dir of workspaces)
+                    visitScript(dir, task);
+                if (turbo.includes(`"//#${task}"`))
+                    visitScript(ROOT_DIR, task);
+            }
+        }
+    };
+    const roots = [];
+    for (const [dirs, isRoot] of [
+        [config.hooks, (entry) => !entry.startsWith('_')],
+        [config.workflows, (entry) => /\.ya?ml$/.test(entry)],
+    ]) {
+        for (const dir of dirs) {
+            const full = posix.join(root, dir);
+            if (!existsSync(full))
+                continue;
+            for (const entry of readdirSync(full).sort())
+                if (isRoot(entry))
+                    roots.push(`${dir}/${entry}`);
+        }
+    }
+    for (const path of roots)
+        visitFile(path, ROOT_DIR);
+    return reach;
+};
+/** The workspace a path belongs to: the longest declared prefix, else the root. */
+const ownerOf = (path, workspaces) => workspaces.filter((dir) => path.startsWith(`${dir}/`)).sort((a, b) => b.length - a.length)[0] ?? ROOT_DIR;
+/** Is a cited test file run by a test runner some stage starts in its workspace? */
+export const testFileRuns = (path, reach, config) => {
+    if (!config.testFile.test(path))
+        return false;
+    const owner = ownerOf(path, reach.workspaces);
+    return [...reach.scripts].some(([key, command]) => key.startsWith(`${owner}\t`) && config.testRunner.test(command));
+};
+/** Every live validator claim whose named scripts no stage reaches. */
+export const findUncalledValidators = (root, standards, config, given) => {
+    const claims = standards.filter((s) => s.enforcement === 'validator' && !s.deprecated);
+    // Walked only when some claim needs it: a corpus with no live validator
+    // claim has nothing to resolve, and its tree need not be a workspace.
+    if (claims.length === 0)
+        return [];
+    const reach = given ?? resolveStageReach(root, config);
+    const dispatch = read(root, config.dispatcher);
+    const problems = [];
+    for (const standard of claims) {
+        const target = config.dispatchCall.exec(standard.enforcementConfig);
+        // Once each: the script and the dispatcher target usually name one file.
+        const named = [
+            ...new Set([
+                ...(standard.enforcementScript === '' ? [] : [posix.normalize(standard.enforcementScript)]),
+                ...(target === null ? [] : pathsIn(dispatcherCase(dispatch, target[1]), ROOT_DIR, config.runnable)),
+            ]),
+        ];
+        const report = (rule, reason) => {
+            problems.push({ file: standard.file, id: standard.id, rule, reason });
+        };
+        if (named.length === 0) {
+            report(standard.enforcementConfig || '(empty)', 'claims validator enforcement but names no script — nothing here can run');
+            continue;
+        }
+        const missing = named.filter((path) => !existsSync(posix.join(root, path)));
+        for (const path of missing)
+            report(path, 'does not exist');
+        if (missing.length > 0)
+            continue;
+        if (!named.some((path) => reach.files.has(path) || testFileRuns(path, reach, config))) {
+            report(named.join(', '), 'is never run by a hook or workflow — the claim names a validator nothing calls');
+        }
+    }
+    return problems;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@veda-hq/pariksha",
-  "version": "0.5.11",
-  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. Checks: authority-citations, boundary, codec-registry, coverage-by-type, coverage-exemptions, doc-budgets, env-gate-switches, export-deletions, fault-injection-registry, required-settings. Also markdownlint rules for Markdown that renders mangled: @veda-hq/pariksha/markdownlint.",
+  "version": "0.5.12",
+  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. Checks: authority-citations, boundary, codec-registry, coverage-by-type, coverage-exemptions, doc-budgets, enforcement-claims, env-gate-switches, export-deletions, fault-injection-registry, required-settings. Also markdownlint rules for Markdown that renders mangled: @veda-hq/pariksha/markdownlint.",
   "keywords": [
     "repository checks",
     "lint",
@@ -38,16 +38,24 @@
     "dist",
     "baselines"
   ],
+  "dependencies": {
+    "js-yaml": "4.3.2"
+  },
   "peerDependencies": {
+    "eslint": ">=9.24 <10",
     "typescript": ">=5.4 <6"
   },
   "peerDependenciesMeta": {
+    "eslint": {
+      "optional": true
+    },
     "typescript": {
       "optional": true
     }
   },
   "devDependencies": {
     "@types/node": "24.19.2",
+    "eslint": "9.39.1",
     "typescript": "5.9.3"
   },
   "scripts": {