@veda-hq/pariksha 0.5.1 → 0.5.3

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.1 <check> [flags]
-npx @veda-hq/pariksha@0.5.1 --version
+npx @veda-hq/pariksha@0.5.3 <check> [flags]
+npx @veda-hq/pariksha@0.5.3 --version
 ```
 
 Every check exits 0 when the repository passes, 1 when it refuses something
@@ -93,9 +93,44 @@ importing file's nearest `package.json`), `maxHops` (default 1) and `hint` (a
 line printed under a failure).
 
 Needs `typescript` `>=5.4 <6`, the repository's own install first, else one
-beside pariksha (an optional peer dependency: only this check reads it).
-TypeScript 7 exports no stable compiler API yet, so it exits 2 naming the
-installed version.
+beside pariksha (an optional peer dependency: only the checks that read code
+or tsconfig files load it). TypeScript 7 exports no stable compiler API yet,
+so they exit 2 naming the installed version.
+
+## `coverage-exemptions`
+
+```sh
+pariksha coverage-exemptions --config <file> [--package <dir>] [--root <dir>]
+```
+
+Each vitest config's `coverage.exclude` holds every pattern the product
+exempts, and no production tsconfig's `include` brings those files back. The
+JSON `--config` (relative to the root) names both lists:
+
+```json
+{
+  "vitest": { "configs": ["apps/api/vitest.config.ts"], "requiredExcludes": ["**/*.test.ts", "**/__mocks__/**"] },
+  "build": { "configs": ["apps/api/tsconfig.build.json"], "forbiddenIncludes": ["__mocks__", ".test."] },
+  "loader": "tsx"
+}
+```
+
+- Each vitest config is imported in its own Node process, in the config's
+  folder, after `loader` when one is named (a relative path is the root's
+  file; a package name resolves as `node --import` does), so a config that
+  imports the product's TypeScript loads as the product's tooling loads it. A
+  default export may be an object or a factory, sync or async. The answer
+  comes back on fd 3, so nothing a config prints can pose as it, and the
+  process exits once it answers. A config that fails to load is a finding,
+  with its error; a loader that does not load exits 2.
+- Each build config is read as TypeScript reads it (comments allowed); only
+  its own `include` is judged, not one it `extends`.
+- `--package <dir>` judges only the configs under that folder (a package's
+  own run), which must be a normalized folder under the root.
+- A listed config that is not a file, a tsconfig TypeScript cannot read, and
+  a config naming no configs or empty lists exit 2.
+
+Needs `typescript` for the build configs.
 
 ## `doc-budgets`
 
@@ -120,6 +155,72 @@ 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.
 
+## `env-gate-switches`
+
+```sh
+pariksha env-gate-switches --config <file> [--mode staged|tree] [--root <dir>]
+```
+
+A hook that reads `PUSH_SKIP` from the environment has a bypass anyone can
+type: `PUSH_SKIP=1 git push`. This check refuses gate code that READS an
+environment variable whose name has a switch word (`X_SKIP`, `SKIP_X`,
+`X_PROBE_Y`): writing or deleting one is not a read. The JSON `--config`
+(relative to the root) says where gate code is:
+
+```json
+{
+  "gatePaths": ["^\\.husky/", "^scripts/", "^\\.github/workflows/"],
+  "notGateCode": ["\\.test\\.[cm]?[jt]sx?$", "(?:^|/)fixtures?/", "\\.md$"],
+  "notAGate": {
+    "SETUP_SKIP_MOBILE": { "files": ["scripts/setup.sh"], "reason": "installs no mobile toolchain; checks nothing" }
+  },
+  "words": ["SKIP", "PROBE"]
+}
+```
+
+- `gatePaths` (required) and `notGateCode` are path regexes: a file is gate
+  code when a gate path matches it and no `notGateCode` entry does.
+- `notAGate` allows a switch that turns off something other than a check,
+  in the files listed only, with the reason a reviewer reads; the same name
+  anywhere else is still refused.
+- `words` (default `SKIP` and `PROBE`) are upper-case words; a name made of
+  `_`-joined words, one of them a switch word, is a switch.
+- Shell (`.sh`, and every file under `.husky/`) is read as bash reads it:
+  single quotes, escapes, comments and quoted heredoc bodies expand nothing,
+  and a bare name bash reads is a read: in arithmetic (`(( X_SKIP ))`,
+  `let`, `-eq`, a subscript), `printenv X_SKIP`, and `-v X_SKIP` in `[ ]`,
+  `[[ ]]` or `test`. A variable the file initialises at the top level before
+  reading it is the script's own decision, not a read; one initialised in a
+  branch, loop, function, group, subshell, pipeline or the end of a `&&`
+  list, or self-defaulted (`X_SKIP="${X_SKIP:-0}"`), is.
+- TypeScript and JavaScript are read as a syntax tree, with a type checker
+  over the one file: dotted, bracketed, optional, destructured (nested too:
+  `const { env: { X_SKIP } } = process`) and `in` reads count, through
+  `process`, `globalThis.process`, `node:process` and any local bound to the
+  environment, with constant keys resolved (`env['X_' + 'SKIP']`); a mention
+  in a comment or string does not.
+- Python reads are `os.environ[…]`, `.get(…)`, `.setdefault(…)`, `.pop(…)`,
+  `'X' in` / `'X' not in os.environ`, the same on `os.environ.copy()` or
+  `dict(os.environ)`, and `os.getenv(…)`, with the bytes forms (`environb`,
+  `getenvb`): under `os` by any name, through `from os import environ as e`
+  / `getenv as g`, and through a name assigned one (`env = os.environ`,
+  `read = os.getenv`), outside strings and comments (f-string fields are
+  code). A key held in a variable is not resolved. Workflow YAML reads are
+  `$X`, `env.X` and `env['X']` outside comments.
+
+`tree` (the default) reads every tracked file in the working tree, skipping
+one deleted there; when every tracked gate file is deleted, nothing was read
+and it exits 2. `staged` (for a pre-commit hook) reads the files the index
+adds, copies, modifies, renames or changes the type of (a symlink replaced
+by a file), as the index holds them. In either mode, a repository with no
+tracked gate code exits 2, since the config would check nothing, and a gate
+file that is a symlink (in the index for staged, in the working tree for
+tree) exits 2: its text is a path, and its target goes unchecked. A gate
+file that cannot be read (one under a folder the check cannot open
+included), a git call that fails, or a failure while reading a file's code
+exits 2: an unread gate is never clean. Needs `typescript` only when a
+TypeScript or JavaScript file is gate code.
+
 ## `export-deletions`
 
 ```sh

package/dist/cli.js

@@ -6,8 +6,11 @@ import { join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { adrDirOf, DEFAULTS, findUncited, formatClaims, listAdrs, readOrUndefined, stagedSource, treeSource } from "./authority-citations.js";
 import { findDenied, hash, isText, parseDenyList } from "./boundary.js";
-import { DEFAULT_CONFIG, findGaps, formatGaps, listedPaths, loadTypescript, parseConfig, treePaths, typescriptLoaders } from "./coverage-by-type.js";
+import { DEFAULT_CONFIG, findGaps, formatGaps, listedPaths, parseConfig, treePaths } from "./coverage-by-type.js";
+import { checkBuild, checkPackage, checkVitest, formatViolations, loaderFailure, loadVitestExclude, missingConfigs, ownedBy, parseConfig as parseExemptions } from "./coverage-exemptions.js";
 import { checkBudgets } from "./doc-budgets.js";
+import { diskReads, formatReads, listFiles, needsTypescript, parseConfig as parseGateConfig, readerFor, readGate } from "./env-gate-switches.js";
+import { loadTypescript, typescriptLoaders } from "./typescript.js";
 import { checkExportDeletions, formatReport } from "./export-deletions.js";
 import { BASE_CANDIDATES, gitAt, gitAtTop, must, resolveBase, topOf } from "./git.js";
 export const DENY_FILE = '.veda/deny.sha256';
@@ -15,7 +18,9 @@ const USAGE = [
     'usage: pariksha authority-citations [--mode staged|tree] [--authority <a,b>] [--issue-prefix <A,B>] [--adr-dir <dir>] [--root <dir>]',
     '       pariksha boundary [--root <dir>] [--deny <file>]',
     '       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 env-gate-switches --config <file> [--mode staged|tree] [--root <dir>]',
     '       pariksha export-deletions [--base <ref>] [--root <dir>]',
     '       pariksha hash <word>',
     '       pariksha --version',
@@ -200,11 +205,124 @@ const coverageByType = (f, io) => {
         return 2;
     }
 };
+const coverageExemptions = (f, io) => {
+    const configPath = f.get('--config');
+    if (configPath === undefined) {
+        io.err(USAGE);
+        return 2;
+    }
+    const dir = resolve(f.get('--root') ?? '.');
+    const root = topOf(dir);
+    if (root === undefined) {
+        io.err(`pariksha coverage-exemptions: ${dir} is not in a git repository`);
+        return 2;
+    }
+    try {
+        const config = parseExemptions(readFileSync(resolve(root, configPath), 'utf8'));
+        const pkg = f.get('--package');
+        const refused = pkg === undefined ? undefined : checkPackage(root, pkg);
+        if (refused !== undefined) {
+            io.err(`pariksha coverage-exemptions: --package ${refused}`);
+            return 2;
+        }
+        const vitest = ownedBy(config.vitest.configs, pkg);
+        const build = ownedBy(config.build.configs, pkg);
+        const missing = missingConfigs(root, [...vitest, ...build]);
+        if (missing.length > 0) {
+            io.err(`pariksha coverage-exemptions: ${missing.join(', ')} named in ${configPath} but not a file; nothing was checked, so this is not a pass`);
+            return 2;
+        }
+        const noLoader = vitest.length > 0 ? loaderFailure(root, config.loader) : undefined;
+        if (noLoader !== undefined) {
+            io.err(`pariksha coverage-exemptions: ${noLoader}; nothing was checked, so this is not a pass`);
+            return 2;
+        }
+        let violations = checkVitest(config, vitest, (c) => loadVitestExclude(root, c, config.loader));
+        if (build.length > 0) {
+            const ts = (io.typescript ?? (() => loadTypescript(typescriptLoaders(root))))();
+            if (typeof ts === 'string') {
+                io.err(`pariksha coverage-exemptions: ${ts}`);
+                return 2;
+            }
+            violations = [...violations, ...checkBuild(ts, config, root, build)];
+        }
+        const result = formatViolations(violations, vitest.length, build.length, pkg);
+        result.out.forEach(io.out);
+        result.err.forEach(io.err);
+        return result.ok ? 0 : 1;
+    }
+    catch (e) {
+        io.err(`pariksha coverage-exemptions: ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+};
+const envGateSwitches = (f, io) => {
+    const P = 'pariksha env-gate-switches:';
+    const configPath = f.get('--config');
+    const mode = f.get('--mode') ?? 'tree';
+    if (configPath === undefined || (mode !== 'staged' && mode !== 'tree')) {
+        io.err(USAGE);
+        return 2;
+    }
+    const dir = resolve(f.get('--root') ?? '.');
+    const root = topOf(dir);
+    if (root === undefined) {
+        io.err(`${P} ${dir} is not in a git repository`);
+        return 2;
+    }
+    let reader;
+    let words;
+    try {
+        const config = parseGateConfig(readFileSync(resolve(root, configPath), 'utf8'));
+        reader = readerFor(config);
+        words = config.words;
+    }
+    catch (e) {
+        io.err(`${P} ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+    const reads = (io.gateReads ?? diskReads)(root);
+    let result;
+    try {
+        const listed = listFiles(reads, mode).filter((l) => reader.isGateCode(l.file));
+        // A tree with no gate code is a config whose gatePaths match nothing (a
+        // typo): staged mode would pass every commit under it, so both refuse.
+        if (!(mode === 'tree' ? listed.length > 0 : listFiles(reads, 'tree').some((l) => reader.isGateCode(l.file)))) {
+            io.err(`${P} no tracked file is gate code under the config's gatePaths; nothing was checked, so this is not a pass`);
+            return 2;
+        }
+        const sources = listed.flatMap((entry) => {
+            const text = readGate(reads, mode, entry);
+            return text === undefined ? [] : [{ file: entry.file, text }];
+        });
+        if (mode === 'tree' && sources.length === 0) {
+            // Staged mode reads the index, which holds every file it lists.
+            io.err(`${P} every tracked gate file (${listed.length}) is gone from the working tree; nothing was checked, so this is not a pass`);
+            return 2;
+        }
+        const ts = sources.some((s) => needsTypescript(s.file)) ? (io.typescript ?? (() => loadTypescript(typescriptLoaders(root))))() : undefined;
+        if (typeof ts === 'string') {
+            io.err(`${P} ${ts}`);
+            return 2;
+        }
+        result = formatReads(sources.flatMap((s) => reader.findSwitchReads(s.file, s.text, ts)), words, sources.length, configPath);
+    }
+    catch (e) {
+        // An unread gate, or one the reader failed on, is unchecked, never clean.
+        io.err(`${P} could not read gate code, so it is unchecked: ${e.message}`);
+        return 2;
+    }
+    result.out.forEach(io.out);
+    result.err.forEach(io.err);
+    return result.ok ? 0 : 1;
+};
 const COMMANDS = {
+    'coverage-exemptions': { allowed: ['--config', '--package', '--root'], run: coverageExemptions },
     'authority-citations': { allowed: ['--mode', '--authority', '--issue-prefix', '--adr-dir', '--root'], run: authorityCitations },
     boundary: { allowed: ['--root', '--deny'], run: boundary },
     'coverage-by-type': { allowed: ['--config', '--files-from', '--root'], run: coverageByType },
     'doc-budgets': { allowed: ['--table', '--section', '--root'], run: docBudgets },
+    'env-gate-switches': { allowed: ['--config', '--mode', '--root'], run: envGateSwitches },
     'export-deletions': { allowed: ['--base', '--root'], run: exportDeletions },
 };
 export const run = (args, io, version = ownVersion(), env = process.env) => {

package/dist/coverage-by-type.js

@@ -5,7 +5,6 @@
 // sat at 0% covered while `Page.test.tsx` tested a helper, and a filename match
 // called the page covered. So a candidate suite counts only when it reaches the
 // subject through a runtime import, directly or through one module it imports.
-import { createRequire } from 'node:module';
 import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 const KINDS_AT = (dirs, suffixes) => dirs.flatMap((d) => suffixes.map((s) => `${d}{name}${s}`));
@@ -141,28 +140,6 @@ export const parseConfig = (text) => {
     }
     return { categories, required, exclude, tests, aliases, maxHops, hint };
 };
-/** Where typescript is looked for: the product's own install at `root` first, then beside pariksha (npx installs no optional peer). */
-export const typescriptLoaders = (root) => [createRequire(join(root, 'package.json')), createRequire(import.meta.url)];
-/** TypeScript from the first loader that has it; a message naming why when it cannot be used. */
-export const loadTypescript = (loaders = typescriptLoaders(process.cwd())) => {
-    let mod;
-    for (const load of loaders) {
-        try {
-            mod = load('typescript');
-            break;
-        }
-        catch {
-            // not installed there; try the next
-        }
-    }
-    if (mod === undefined)
-        return 'needs the typescript package (>=5.4 <6) in the repository or beside pariksha';
-    const ts = mod;
-    if (typeof ts.createSourceFile !== 'function') {
-        return `needs the TypeScript compiler API, which typescript ${String(ts.version)} does not export; install typescript >=5.4 <6`;
-    }
-    return ts;
-};
 const toPosix = (p) => p.split(sep).join('/');
 /** Extensions a specifier may omit, or carry as its ESM-facing `.js` form. */
 const MODULE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs'];

package/dist/coverage-exemptions.js

@@ -0,0 +1,189 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// coverage-exemptions: each vitest config excludes from coverage what the product
+// exempts (tests, mocks, declarations), and no production build config includes
+// those files back.
+//
+// An exemption list that drifts lets test files count as covered source, and a
+// build config that includes `__mocks__` ships them. Both are configuration a
+// reviewer reads past, so the lists are named once, in the product's config,
+// and every config is held to them.
+import { spawnSync } from 'node:child_process';
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, posix, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isStrings = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string' && s !== '');
+const section = (raw, key, list) => {
+    const v = raw[key] ?? { configs: [], [list]: [] };
+    if (!isRecord(v))
+        throw new Error(`"${key}" must be an object`);
+    const extra = Object.keys(v).find((k) => k !== 'configs' && k !== list);
+    if (extra !== undefined)
+        throw new Error(`${key}: unknown key "${extra}"`);
+    const configs = v['configs'] ?? [];
+    const rules = v[list] ?? [];
+    if (!isStrings(configs))
+        throw new Error(`${key}.configs must be a list of non-empty paths`);
+    if (!isStrings(rules))
+        throw new Error(`${key}.${list} must be a list of non-empty strings`);
+    const bad = configs.find((c) => !isRepoPath(c));
+    if (bad !== undefined)
+        throw new Error(`${key}.configs: "${bad}" is not a normalized root-relative path`);
+    // A config with nothing to hold it to would pass whatever it says.
+    if (configs.length > 0 && rules.length === 0)
+        throw new Error(`${key}.${list} is empty, so its configs would always pass`);
+    return { configs, rules };
+};
+/** The config a JSON text names; throws naming the first bad key. */
+export const parseConfig = (text) => {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`not JSON: ${e.message}`);
+    }
+    if (!isRecord(raw))
+        throw new Error('the config must be a JSON object');
+    const unknown = Object.keys(raw).find((k) => !['vitest', 'build', 'loader'].includes(k));
+    if (unknown !== undefined)
+        throw new Error(`unknown key "${unknown}"`);
+    const vitest = section(raw, 'vitest', 'requiredExcludes');
+    const build = section(raw, 'build', 'forbiddenIncludes');
+    if (vitest.configs.length + build.configs.length === 0)
+        throw new Error('no vitest or build config is named, so nothing would be checked');
+    const loader = raw['loader'];
+    if (loader !== undefined && (typeof loader !== 'string' || loader === ''))
+        throw new Error('"loader" must be a module name');
+    return {
+        vitest: { configs: vitest.configs, requiredExcludes: vitest.rules },
+        build: { configs: build.configs, forbiddenIncludes: build.rules },
+        loader,
+    };
+};
+/** A normalized relative POSIX path that stays inside the root. */
+const isRepoPath = (p) => !isAbsolute(p) && posix.normalize(p) === p && p !== '.' && p !== '..' && !p.startsWith('../') && !p.endsWith('/');
+/** A `--package` folder, checked: a value that matches no config would check nothing and pass. */
+export const checkPackage = (root, dir) => {
+    if (!isRepoPath(dir))
+        return `"${dir}" is not a normalized root-relative folder`;
+    const full = join(root, dir);
+    if (statSync(full, { throwIfNoEntry: false })?.isDirectory() !== true)
+        return `"${dir}" is not a folder under the root`;
+    // On a case-insensitive disk `Apps/Server` is a folder too, but owns no config spelled `apps/server/…`.
+    if (realpathSync.native(full) !== join(realpathSync.native(root), dir))
+        return `"${dir}" is not spelled as the folder on disk is`;
+    return undefined;
+};
+/** The configs that belong to `dir`, or all of them. */
+export const ownedBy = (configs, dir) => (dir === undefined ? [...configs] : configs.filter((c) => c.startsWith(`${dir}/`)));
+/** A vitest config's `coverage.exclude`, as the config file exports it. */
+export const readExclude = async (file) => {
+    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+    const raw = mod.default;
+    // A config may export a factory, sync or async (`defineConfig(async () => …)`).
+    const config = (await (typeof raw === 'function' ? raw() : raw));
+    return config?.test?.coverage?.exclude || config?.coverage?.exclude;
+};
+/** The child script beside a module: the `.ts` source under test, the `.js` build when installed. */
+export const loaderScriptBeside = (moduleUrl) => fileURLToPath(new URL(`./load-vitest-config${moduleUrl.endsWith('.ts') ? '.ts' : '.js'}`, moduleUrl));
+const LOADER_SCRIPT = loaderScriptBeside(import.meta.url);
+/** The `--import` argument for a loader: a relative path is the root's file, a bare name resolves from the config's folder. */
+const importArg = (root, loader) => (loader.startsWith('.') ? pathToFileURL(resolve(root, loader)).href : loader);
+/** Why a child failed: the error's own line (`Error: …`), the value thrown when it is not an Error, else its first line. */
+export const failureOf = (stderr, status) => {
+    const lines = stderr.split('\n');
+    const named = lines.find((l) => /^\w*Error\b/.test(l));
+    if (named !== undefined)
+        return named.trim();
+    // `throw 'text'` prints Node's own frame, a caret line, then the value.
+    const caret = lines.findIndex((l) => /^\s*\^+\s*$/.test(l));
+    const thrown = caret >= 0 ? lines.slice(caret + 1).find((l) => /\S/.test(l)) : undefined;
+    return (thrown ?? lines.find((l) => /\S/.test(l)) ?? `exit ${String(status)}`).trim();
+};
+/**
+ * One vitest config's exclusions, loaded in its own Node process under the
+ * product's loader, in the config's own folder (as the product's tooling runs
+ * it, so its tsconfig `paths` and relative reads hold). One process per config:
+ * two configs loaded side by side in one process can race on a shared module.
+ * The answer comes back on fd 3, which nothing a config prints can reach.
+ */
+export const loadVitestExclude = (root, config, loader, timeout = 120_000) => {
+    const file = join(root, config);
+    const args = [...(loader === undefined ? [] : ['--import', importArg(root, loader)]), LOADER_SCRIPT, file];
+    const r = spawnSync(process.execPath, args, { cwd: dirname(file), encoding: 'utf8', timeout, maxBuffer: 1 << 26, stdio: ['ignore', 'pipe', 'pipe', 'pipe'] });
+    const answer = r.status === 0 && r.error === undefined ? (r.output[3] ?? '') : '';
+    if (answer === '')
+        return { ok: false, error: r.error?.message ?? failureOf(r.stderr, r.status) };
+    try {
+        return { ok: true, exclude: JSON.parse(answer) };
+    }
+    catch {
+        return { ok: false, error: `the config's coverage.exclude is not data: ${answer.slice(0, 80)}` };
+    }
+};
+/** Whether the loader itself loads, from the root; a missing one would otherwise be blamed on every config. */
+export const loaderFailure = (root, loader) => {
+    if (loader === undefined)
+        return undefined;
+    const r = spawnSync(process.execPath, ['--import', importArg(root, loader), '-e', ''], { cwd: root, encoding: 'utf8', timeout: 120_000 });
+    return r.status === 0 && r.error === undefined ? undefined : `loader ${loader} does not load: ${r.error?.message ?? failureOf(r.stderr, r.status)}`;
+};
+/** The violations among the vitest configs. */
+export const checkVitest = (config, configs, load) => {
+    const out = [];
+    for (const file of configs) {
+        const r = load(file);
+        if (!r.ok) {
+            out.push({ file, message: `cannot load the config: ${r.error}` });
+            continue;
+        }
+        if (!Array.isArray(r.exclude) || r.exclude.length === 0) {
+            out.push({ file, message: 'has no coverage.exclude' });
+            continue;
+        }
+        const exclude = r.exclude;
+        for (const pattern of config.vitest.requiredExcludes) {
+            if (!exclude.includes(pattern))
+                out.push({ file, message: `coverage.exclude lacks ${pattern}` });
+        }
+    }
+    return out;
+};
+/** The violations among the build configs; a config that cannot be read throws. */
+export const checkBuild = (ts, config, root, configs) => {
+    const out = [];
+    for (const file of configs) {
+        const read = ts.readConfigFile(join(root, file), (p) => readFileSync(p, 'utf8'));
+        if (read.error !== undefined)
+            throw new Error(`${file}: ${ts.flattenDiagnosticMessageText(read.error.messageText, '\n')}`);
+        const include = read.config?.include ?? [];
+        if (!Array.isArray(include) || !include.every((e) => typeof e === 'string'))
+            throw new Error(`${file}: "include" is not a list of strings`);
+        for (const pattern of config.build.forbiddenIncludes) {
+            if (include.some((entry) => entry.includes(pattern)))
+                out.push({ file, message: `include brings test files into the build: ${pattern}` });
+        }
+    }
+    return out;
+};
+/** Every listed config exists as a file; a missing one would otherwise pass unread. */
+export const missingConfigs = (root, configs) => configs.filter((c) => statSync(join(root, c), { throwIfNoEntry: false })?.isFile() !== true);
+const P = 'pariksha coverage-exemptions:';
+export const formatViolations = (violations, vitest, build, dir) => {
+    const scope = dir === undefined ? '' : ` under ${dir}`;
+    if (violations.length === 0)
+        return { ok: true, out: [`${P} ${vitest} vitest and ${build} build config(s)${scope} checked, none drifts`], err: [] };
+    return {
+        ok: false,
+        out: [],
+        err: [...violations.map((v) => `${P} ${v.file}: ${v.message}`), `${P} ${violations.length} problem(s). Exempt test files from coverage in every vitest config, and keep them out of every build.`],
+    };
+};