@veda-hq/pariksha 0.3.1 → 0.5.1

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.3.1 <check> [flags]
-npx @veda-hq/pariksha@0.3.1 --version
+npx @veda-hq/pariksha@0.5.1 <check> [flags]
+npx @veda-hq/pariksha@0.5.1 --version
 ```
 
 Every check exits 0 when the repository passes, 1 when it refuses something
@@ -13,6 +13,37 @@ Every check exits 0 when the repository passes, 1 when it refuses something
 error. `--root <dir>` (default: the current directory) names the repository.
 Node 24 or later. MIT.
 
+## `authority-citations`
+
+```sh
+pariksha authority-citations [--mode staged|tree] [--authority <a,b>]
+  [--issue-prefix <A,B>] [--adr-dir <dir>] [--root <dir>]
+```
+
+A coherent fabrication passes every internal check: an agent that deletes a
+public API and calls the deletion "an owner decision" is consistent with
+itself. So a line that invokes an authority (`owner decision`,
+`founder decided`, `product rule`, `approved by` / `decided by` /
+`authorized by` / `mandated by` / `per` an office, a `--authority` name or an
+`@handle`) must cite, within three lines, something only that authority could
+have produced:
+
+- resolved: a commit id naming a commit here, or `ADR-NNNN` /
+  `<adr-dir>/NNNN` naming an existing `NNNN-*.md` other than the claiming file
+  (default `docs/adr`);
+- shape-checked: an issue id with a `--issue-prefix` (`ABC-123`), a GitHub
+  pull request or issue URL, or `PR #123`.
+
+`ALLOW-AUTHORITY-PHRASE: <reason>` in the window marks words used without
+asserting authority; the reason is required. TypeScript, JavaScript, SQL,
+Prisma, shell and Markdown files are read, outside `node_modules`, `dist`,
+`build`, `coverage`, `generated`, `.tmp` and `.local`.
+
+`staged` (the default, for a pre-commit or pre-merge-commit hook) judges only
+the lines the commit adds; on a merge, only lines new against every parent,
+so text a merged branch already carried is not judged again. `tree` judges
+every tracked file. When git cannot read the change it exits 2.
+
 ## `boundary`
 
 ```sh
@@ -31,6 +62,41 @@ the repository's deny list.
 - Binary files (any NUL byte) are skipped. Untracked files are not read.
   Line 0 in a finding is the file's path.
 
+## `coverage-by-type`
+
+```sh
+pariksha coverage-by-type [--config <file>] [--files-from <file>|-] [--root <dir>]
+```
+
+A source file in a category needs the tests its category names: by default a
+service, hook, utility or context a unit test, a repository a unit and an
+integration test, a component or screen a UI (`.test.tsx`) test. A suite named
+after its subject that never imports it is no test of it, so a candidate
+counts only when it loads the subject at runtime, directly or through one
+module it imports (a barrel, a collaborator). `import type`, a clause whose
+every binding is type-only, and `typeof import()` load nothing and do not
+count; `import()`, `require()`, `importActual` and `requireActual` do.
+
+Only `.ts` and `.tsx` files are judged. Without `--files-from` every tracked
+regular file is (not a symlink, not one deleted in the working tree), and a
+tree with none in a category exits 2. With it, the listed paths are (one per
+line or NUL-separated, relative to the root or absolute; `-` reads stdin, a
+file path is relative to the current directory); a listed path that does not
+exist or lies outside the root exits 2, and a listed symlink is skipped. The
+JSON `--config` (relative to the root) replaces each default it names, and
+refuses one that would judge nothing (no categories, an empty pattern, a
+category needing no test):
+`categories` (name to path regex, first match wins), `required` (category to
+test kinds), `tests` (kind to candidate paths, `{dir}` and `{name}`),
+`exclude` (path regexes), `aliases` (specifier prefix to a directory under the
+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.
+
 ## `doc-budgets`
 
 ```sh

package/dist/authority-citations.js

@@ -0,0 +1,192 @@
+// The authority-citations check: a line that invokes an authority ("owner
+// decision", "approved by the founder", "per the CTO") must cite something only
+// that authority could have produced, outside the file making the claim.
+//
+// A claim asserted inside the file it justifies cannot be checked from inside
+// that file: an agent that deletes a public API and calls it "an owner
+// decision" passes every internal-consistency gate, because a coherent
+// fabrication is consistent. So the check asks for an anchor within three lines
+// of the claim:
+//
+//   resolved here:      an ADR number whose file exists (not the claiming file),
+//                       a commit id that names a commit in this repository
+//   shape-checked only: an issue id with a configured prefix (ABC-123), a
+//                       GitHub pull request or issue URL, "PR #123"
+//
+// `ALLOW-AUTHORITY-PHRASE: <reason>` in the same window marks words that are
+// used without asserting authority; the reason is required.
+//
+// staged mode judges only lines the commit adds; on a merge, only lines new
+// against every parent, so text a merged branch already carried is not judged
+// again. tree mode judges every tracked file.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { must, PLAIN_DIFF } from "./git.js";
+export const DEFAULTS = { authorities: [], issuePrefixes: [], adrDir: 'docs/adr' };
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * An authority is a person or an office, never a subsystem: requiring one after
+ * "approved by" and "per" keeps "decided by the diff status" out.
+ */
+export const phrasePattern = (authorities) => {
+    const names = ['owner', 'founder', 'CTO', 'CEO', 'management', 'leadership', ...authorities.map(escape), '@[A-Za-z0-9._-]+'];
+    const who = `(?:the )?(?:${names.join('|')})`;
+    return new RegExp(`owner (?:decision|decided)|founder (?:decision|decided)|product rule|(?:approved|decided|authorized|mandated) by ${who}|per ${who}`, 'i');
+};
+const SOURCE_EXT = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts|sql|prisma|sh|md)$/;
+/** Vendored, generated and scratch trees carry no authored claims. */
+const SKIPPED_PATH = /(^|\/)(node_modules|dist|build|coverage|\.tmp|\.local|generated)\//;
+const WINDOW = 3;
+/** The lines within WINDOW of the 1-based line `center`, joined. */
+export const windowOf = (lines, center) => lines.slice(Math.max(0, center - 1 - WINDOW), center + WINDOW).join('\n');
+/** True when the window holds the pragma with a reason, or a citation that resolves. */
+export const hasCitation = (window, claimingFile, opts, git, adrFiles) => {
+    if (/ALLOW-AUTHORITY-PHRASE:[^\S\n]*\S/.test(window))
+        return true;
+    if (opts.issuePrefixes.length > 0 && new RegExp(`\\b(?:${opts.issuePrefixes.map(escape).join('|')})-[0-9]+\\b`).test(window))
+        return true;
+    if (/https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/(?:pull|issues)\/[0-9]+/.test(window))
+        return true;
+    if (/\bPR #[0-9]+\b/.test(window))
+        return true;
+    for (const [, n] of window.matchAll(new RegExp(`(?:ADR-|${escape(opts.adrDir)}/)([0-9]{4})`, 'g'))) {
+        if (adrFiles.some((f) => f.startsWith(`${opts.adrDir}/${n}-`) && f.endsWith('.md') && f !== claimingFile))
+            return true;
+    }
+    for (const [sha] of window.matchAll(/\b[0-9a-f]{7,40}\b/g)) {
+        if (git.run(['cat-file', '-e', `${sha}^{commit}`]) !== undefined)
+            return true;
+    }
+    return false;
+};
+/** 1-based line numbers a `-U0` diff adds. */
+export const addedLines = (diff) => {
+    const out = new Set();
+    for (const line of diff.split('\n')) {
+        const m = /^@@ [^+]*\+([0-9]+)(?:,([0-9]+))? @@/.exec(line);
+        if (!m)
+            continue;
+        const start = Number(m[1]);
+        const count = m[2] === undefined ? 1 : Number(m[2]);
+        for (let i = 0; i < count; i++)
+            out.add(start + i);
+    }
+    return out;
+};
+/**
+ * The other parents of the merge being committed; none outside a merge.
+ * MERGE_HEAD exists once a merge stops (a conflict, --no-commit). A clean
+ * merge runs the pre-merge-commit hook before writing MERGE_HEAD, leaving only
+ * the GITHEAD_<sha> variables `git merge` exports: one counts only when git is
+ * merging (AUTO_MERGE is the index tree) and the index is exactly the clean
+ * merge of HEAD and that commit, so a stale or hand-set variable hides nothing.
+ * Anything else falls back to the HEAD diff, which judges more, never less.
+ */
+export const mergeParents = (git, env, readFile) => {
+    const parents = [];
+    const listed = readFile(must(git, ['rev-parse', '--path-format=absolute', '--git-path', 'MERGE_HEAD']).trim());
+    for (const candidate of (listed ?? '').split('\n').filter(Boolean)) {
+        const sha = git.run(['rev-parse', '-q', '--verify', `${candidate}^{commit}`])?.trim();
+        if (sha)
+            parents.push(sha);
+    }
+    // An index with unresolved conflicts has no tree, and nothing can be committed from it.
+    const indexTree = git.run(['write-tree'])?.trim();
+    if (!indexTree || git.run(['rev-parse', '-q', '--verify', 'AUTO_MERGE^{tree}'])?.trim() !== indexTree)
+        return parents;
+    for (const name of Object.keys(env)) {
+        const sha = /^GITHEAD_([0-9a-f]{40}|[0-9a-f]{64})$/.exec(name)?.[1];
+        if (sha === undefined || parents.includes(sha))
+            continue;
+        if (git.run(['merge-tree', '--write-tree', 'HEAD', sha])?.trim() === indexTree)
+            parents.push(sha);
+    }
+    return parents;
+};
+const nulList = (out) => out.split('\0').filter(Boolean);
+const literal = (file) => `:(literal)${file}`;
+/** The staged change: what the commit being made adds. */
+export const stagedSource = (git, env, readFile) => {
+    const parents = mergeParents(git, env, readFile);
+    const added = (file, against) => addedLines(must(git, ['diff', ...PLAIN_DIFF, '--cached', '-U0', ...against, '--', literal(file)]));
+    return {
+        // T: a symlink or submodule replaced by a file brings in its every line.
+        files: nulList(must(git, ['diff', ...PLAIN_DIFF, '--cached', '-z', '--name-only', '--diff-filter=ACMT'])),
+        // `:0:` names stage 0 explicitly, so a path such as `0:a.md` is read as itself.
+        content: (file) => must(git, ['show', `:0:${file}`]),
+        judged: (file) => {
+            let lines = added(file, []);
+            for (const parent of parents) {
+                const vsParent = added(file, [parent]);
+                lines = new Set([...lines].filter((n) => vsParent.has(n)));
+            }
+            return lines;
+        },
+    };
+};
+/** Every tracked file, as it is in the working tree. */
+export const treeSource = (git, root, readFile) => ({
+    files: nulList(must(git, ['ls-files', '-z'])),
+    content: (file) => readFile(join(root, file)),
+    judged: () => undefined,
+});
+/** Every uncited claim the source holds. */
+export const findUncited = (source, opts, git, adrFiles) => {
+    const phrase = phrasePattern(opts.authorities);
+    const claims = [];
+    for (const file of source.files) {
+        if (!SOURCE_EXT.test(file) || SKIPPED_PATH.test(file))
+            continue;
+        const text = source.content(file);
+        if (text === undefined || !phrase.test(text))
+            continue;
+        const lines = text.split('\n');
+        const judged = source.judged(file);
+        lines.forEach((line, i) => {
+            const n = i + 1;
+            const m = phrase.exec(line);
+            if (!m || (judged !== undefined && !judged.has(n)))
+                return;
+            if (hasCitation(windowOf(lines, n), file, opts, git, adrFiles))
+                return;
+            claims.push({ file, line: n, phrase: m[0], text: line.slice(0, 120) });
+        });
+    }
+    return claims;
+};
+/**
+ * An ADR directory as the claiming files' paths spell it: `./docs//adr/`
+ * is `docs/adr`, so an ADR citing itself is still recognised as itself.
+ */
+export const adrDirOf = (dir) => posix.normalize(dir).replace(/\/+$/, '') || '.';
+/** Files (not directories) under the ADR directory, relative to the root. */
+export const listAdrs = (root, adrDir) => {
+    const dir = join(root, adrDir);
+    return existsSync(dir) ? readdirSync(dir).filter((f) => statSync(join(dir, f)).isFile()).map((f) => `${adrDir}/${f}`) : [];
+};
+/** A file's text, or undefined when it is not there (gone, or now a directory); any other failure throws. */
+export const readOrUndefined = (path) => {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        if (['ENOENT', 'ENOTDIR', 'EISDIR'].includes(e.code ?? ''))
+            return undefined;
+        throw e;
+    }
+};
+export const formatClaims = (claims, opts) => {
+    if (claims.length === 0)
+        return { ok: true, out: ['pariksha authority-citations: every authority claim cites an anchor'], err: [] };
+    const err = [];
+    let last = '';
+    for (const c of claims) {
+        if (c.file !== last)
+            err.push(`pariksha authority-citations: uncited authority claim(s) in ${c.file}:`);
+        last = c.file;
+        err.push(`  ${c.line}: [${c.phrase}] ${c.text}`);
+    }
+    const files = new Set(claims.map((c) => c.file)).size;
+    err.push('', 'An authority claim must anchor in something only that authority can produce. Cite one of:', '  a commit id                       (owner decision, f1a0da2d)', `  an existing ADR                   ADR-0040, in ${opts.adrDir}/`, ...(opts.issuePrefixes.length > 0 ? [`  an issue id                       ${opts.issuePrefixes[0]}-447`] : []), '  a GitHub pull request or issue    PR #269, or its full URL', 'A comment or a document an agent could have written is not a citation. If no such', 'artifact exists, the decision has not been made. Not an authority claim? Add', '  ALLOW-AUTHORITY-PHRASE: <reason>', '', `${claims.length} claim(s) across ${files} file(s).`);
+    return { ok: false, out: [], err };
+};

package/dist/cli.js

@@ -4,13 +4,17 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { findDenied, hash, isText, parseDenyList } from './boundary.js';
-import { checkBudgets } from './doc-budgets.js';
-import { checkExportDeletions, formatReport } from './export-deletions.js';
-import { BASE_CANDIDATES, gitAtTop, resolveBase } from './git.js';
+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 { checkBudgets } from "./doc-budgets.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';
 const USAGE = [
-    'usage: pariksha boundary [--root <dir>] [--deny <file>]',
+    '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 doc-budgets --table <file> [--section <name>] [--root <dir>]',
     '       pariksha export-deletions [--base <ref>] [--root <dir>]',
     '       pariksha hash <word>',
@@ -22,7 +26,7 @@ export const ownVersion = () => {
 };
 /** The files git tracks under root, text ones only. */
 export const trackedFiles = (root) => {
-    const names = execFileSync('git', ['ls-files', '-z'], { cwd: root, encoding: 'utf8' }).split('\0').filter(Boolean);
+    const names = must(gitAt(root), ['ls-files', '-z']).split('\0').filter(Boolean);
     const files = [];
     for (const path of names) {
         const full = join(root, path);
@@ -128,12 +132,82 @@ const exportDeletions = (f, io) => {
     result.err.forEach(io.err);
     return result.ok ? 0 : 1;
 };
+/** A comma-separated flag value as a list; empty entries dropped. */
+const list = (value) => (value ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+const authorityCitations = (f, io, env) => {
+    const mode = f.get('--mode') ?? 'staged';
+    if (mode !== 'staged' && mode !== 'tree') {
+        io.err(USAGE);
+        return 2;
+    }
+    const dir = resolve(f.get('--root') ?? '.');
+    const root = topOf(dir);
+    if (root === undefined) {
+        io.err(`pariksha authority-citations: ${dir} is not in a git repository`);
+        return 2;
+    }
+    const git = gitAt(root);
+    const opts = {
+        authorities: list(f.get('--authority')),
+        issuePrefixes: list(f.get('--issue-prefix')),
+        adrDir: adrDirOf(f.get('--adr-dir') ?? DEFAULTS.adrDir),
+    };
+    let result;
+    try {
+        const source = mode === 'tree' ? treeSource(git, root, readOrUndefined) : stagedSource(git, env, readOrUndefined);
+        result = formatClaims(findUncited(source, opts, git, listAdrs(root, opts.adrDir)), opts);
+    }
+    catch (e) {
+        io.err(`pariksha authority-citations: ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+    result.out.forEach(io.out);
+    result.err.forEach(io.err);
+    return result.ok ? 0 : 1;
+};
+const coverageByType = (f, io) => {
+    const dir = resolve(f.get('--root') ?? '.');
+    const root = topOf(dir);
+    if (root === undefined) {
+        io.err(`pariksha coverage-by-type: ${dir} is not in a git repository`);
+        return 2;
+    }
+    const ts = (io.typescript ?? (() => loadTypescript(typescriptLoaders(root))))();
+    if (typeof ts === 'string') {
+        io.err(`pariksha coverage-by-type: ${ts}`);
+        return 2;
+    }
+    try {
+        const configPath = f.get('--config');
+        const config = configPath === undefined ? DEFAULT_CONFIG : parseConfig(readFileSync(resolve(root, configPath), 'utf8'));
+        const from = f.get('--files-from');
+        const paths = from === undefined
+            ? treePaths(root, must(gitAt(root), ['ls-files', '-z']))
+            : listedPaths(root, from === '-' ? (io.stdin ?? (() => readFileSync(0, 'utf8')))() : readFileSync(resolve(from), 'utf8'));
+        const findings = findGaps(ts, config, root, paths);
+        if (from === undefined && findings.judged === 0) {
+            // The whole tree in no category is a config that checks nothing.
+            io.err(`pariksha coverage-by-type: none of ${findings.listed} tracked file(s) is in a category; nothing was checked, so this is not a pass`);
+            return 2;
+        }
+        const result = formatGaps(config, findings);
+        result.out.forEach(io.out);
+        result.err.forEach(io.err);
+        return result.ok ? 0 : 1;
+    }
+    catch (e) {
+        io.err(`pariksha coverage-by-type: ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+};
 const COMMANDS = {
+    '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 },
     'export-deletions': { allowed: ['--base', '--root'], run: exportDeletions },
 };
-export const run = (args, io, version = ownVersion()) => {
+export const run = (args, io, version = ownVersion(), env = process.env) => {
     const [command, ...rest] = args;
     if (command === '--version' && rest.length === 0) {
         io.out(version);
@@ -149,7 +223,7 @@ export const run = (args, io, version = ownVersion()) => {
         io.err(USAGE);
         return 2;
     }
-    return spec.run(f, io);
+    return spec.run(f, io, env);
 };
 const isMain = () => {
     const entry = process.argv[1];

package/dist/coverage-by-type.js

@@ -0,0 +1,396 @@
+// coverage-by-type: a source file in a category needs the tests its category names,
+// and a test counts only if it loads its subject at runtime.
+//
+// A suite named after its subject that never imports it is no test of it: a page
+// 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}`));
+export const DEFAULT_CONFIG = {
+    categories: [
+        ['service', /\/(services|domain)\/.+\.(ts|tsx)$/],
+        ['repository', /\/repositories?\/.+\.(ts|tsx)$/],
+        ['component', /\/components?\/.+\.(tsx)$/],
+        ['screen', /\/screens?\/.+\.(tsx)$/],
+        ['hook', /\/hooks?\/use[A-Z].+\.(ts|tsx)$/],
+        ['utility', /\/(utils|helpers|lib)\/.+\.(ts|tsx)$/],
+        ['context', /\/context\/.+\.(tsx)$/],
+    ],
+    required: new Map([
+        ['service', ['unit']],
+        ['repository', ['unit', 'integration']],
+        ['component', ['ui']],
+        ['screen', ['ui']],
+        ['hook', ['unit']],
+        ['utility', ['unit']],
+        ['context', ['unit']],
+    ]),
+    exclude: [
+        /\.(test|spec|test-d|spec-d|perf-test)\.(ts|tsx)$/,
+        /\.d\.ts$/,
+        /\.config\.(ts|js|mts|mjs)$/,
+        /index\.(ts|tsx)$/,
+        /types?\.(ts|tsx)$/,
+        /(^|\/)types\//,
+        /__mocks__\//,
+        /__tests__\//,
+        /\/e2e\//,
+        /\/test\//,
+        /node_modules/,
+    ],
+    tests: new Map([
+        ['unit', KINDS_AT(['{dir}/', '{dir}/__tests__/', '{dir}/test/', '{dir}/tests/'], ['.test.ts', '.test.tsx'])],
+        [
+            'integration',
+            [
+                ...KINDS_AT(['{dir}/'], ['.integration.test.ts', '.integration.test.tsx']),
+                ...KINDS_AT(['{dir}/__tests__/integration/', '{dir}/test/integration/', '{dir}/tests/integration/'], ['.test.ts', '.test.tsx']),
+            ],
+        ],
+        ['ui', KINDS_AT(['{dir}/', '{dir}/__tests__/', '{dir}/test/', '{dir}/tests/'], ['.test.tsx'])],
+    ]),
+    aliases: new Map(),
+    maxHops: 1,
+    hint: undefined,
+};
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isStrings = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
+const regex = (source, where) => {
+    // An empty pattern matches every path: an exclusion would judge nothing.
+    if (source === '')
+        throw new Error(`${where}: an empty pattern matches every path`);
+    try {
+        // The product's own config file, read from its own checkout.
+        return new RegExp(source);
+    }
+    catch (e) {
+        throw new Error(`${where}: ${e.message}`);
+    }
+};
+const KEYS = new Set(['categories', 'required', 'exclude', 'tests', 'aliases', 'maxHops', 'hint']);
+/** The config a JSON text names, over the defaults; 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) => !KEYS.has(k));
+    if (unknown !== undefined)
+        throw new Error(`unknown key "${unknown}"`);
+    const stringMap = (key) => {
+        const v = raw[key];
+        if (v === undefined)
+            return undefined;
+        if (!isRecord(v) || !Object.values(v).every((s) => typeof s === 'string'))
+            throw new Error(`"${key}" must map names to strings`);
+        return new Map(Object.entries(v));
+    };
+    const listMap = (key) => {
+        const v = raw[key];
+        if (v === undefined)
+            return undefined;
+        if (!isRecord(v) || !Object.values(v).every(isStrings))
+            throw new Error(`"${key}" must map names to lists of strings`);
+        return new Map(Object.entries(v));
+    };
+    const cats = stringMap('categories');
+    if (cats?.size === 0)
+        throw new Error('"categories" is empty, so no file would be judged');
+    // JSON objects iterate integer-like keys first, which would reorder "first match wins".
+    const numeric = cats && [...cats.keys()].find((k) => /^(0|[1-9]\d*)$/.test(k));
+    if (numeric)
+        throw new Error(`category "${numeric}": a name that is a number loses its place in the order`);
+    const categories = cats ? [...cats].map(([name, src]) => [name, regex(src, `categories.${name}`)]) : DEFAULT_CONFIG.categories;
+    const required = listMap('required') ?? DEFAULT_CONFIG.required;
+    const tests = listMap('tests') ?? DEFAULT_CONFIG.tests;
+    const aliases = stringMap('aliases') ?? DEFAULT_CONFIG.aliases;
+    let exclude = DEFAULT_CONFIG.exclude;
+    if (raw['exclude'] !== undefined) {
+        if (!isStrings(raw['exclude']))
+            throw new Error('"exclude" must be a list of strings');
+        exclude = raw['exclude'].map((src, i) => regex(src, `exclude[${i}]`));
+    }
+    const maxHops = raw['maxHops'] ?? DEFAULT_CONFIG.maxHops;
+    if (typeof maxHops !== 'number' || !Number.isInteger(maxHops) || maxHops < 0)
+        throw new Error('"maxHops" must be a whole number, 0 or more');
+    const hint = raw['hint'] ?? DEFAULT_CONFIG.hint;
+    if (hint !== undefined && typeof hint !== 'string')
+        throw new Error('"hint" must be a string');
+    for (const [name] of categories) {
+        const kinds = required.get(name);
+        if (kinds === undefined)
+            throw new Error(`category "${name}" has no "required" entry`);
+        if (kinds.length === 0)
+            throw new Error(`category "${name}" requires no test, so it would never be refused`);
+        const missing = kinds.find((k) => !tests.has(k));
+        if (missing !== undefined)
+            throw new Error(`category "${name}" requires "${missing}", which "tests" does not define`);
+    }
+    for (const [kind, paths] of tests) {
+        const bad = paths.find((p) => !p.includes('{name}'));
+        if (bad !== undefined)
+            throw new Error(`tests.${kind}: "${bad}" has no {name}, so it names one file for every source`);
+    }
+    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'];
+/** The call forms that load a module at runtime, by callee name. */
+const RUNTIME_LOADERS = new Set(['require', 'importActual', 'requireActual']);
+/**
+ * Whether an import or export clause survives to runtime. `import type` is erased
+ * and loads nothing; so is a named clause whose every binding is type-only. A
+ * clause-less import runs its module.
+ */
+const clauseReachesRuntime = (ts, node) => {
+    if (ts.isExportDeclaration(node)) {
+        if (node.isTypeOnly)
+            return false;
+        const b = node.exportClause;
+        return b && ts.isNamedExports(b) ? b.elements.some((e) => !e.isTypeOnly) : true;
+    }
+    const clause = node.importClause;
+    if (!clause)
+        return true;
+    if (clause.isTypeOnly)
+        return false;
+    if (clause.name)
+        return true;
+    const b = clause.namedBindings;
+    return b && ts.isNamedImports(b) ? b.elements.some((e) => !e.isTypeOnly) : true;
+};
+/**
+ * Every module specifier a file loads at runtime: surviving imports and re-exports,
+ * `import()`, `require()`, and `importActual`/`requireActual`. Parsed, not matched:
+ * `typeof import('./x')` in a type loads nothing, and only syntax tells it apart.
+ * A template with substitutions is not resolved; its target needs evaluating.
+ */
+export const moduleSpecifiers = (ts, source, fileName = 'file.tsx') => {
+    const parsed = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest);
+    const found = [];
+    const visit = (node) => {
+        if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+            if (clauseReachesRuntime(ts, node))
+                found.push(node.moduleSpecifier.text);
+        }
+        else if (ts.isCallExpression(node)) {
+            const [first] = node.arguments;
+            const callee = node.expression;
+            const name = ts.isPropertyAccessExpression(callee) ? callee.name.text : ts.isIdentifier(callee) ? callee.text : undefined;
+            const isDynamicImport = callee.kind === ts.SyntaxKind.ImportKeyword;
+            const specifier = first && (ts.isStringLiteral(first) || ts.isNoSubstitutionTemplateLiteral(first)) ? first.text : undefined;
+            if (specifier !== undefined && (isDynamicImport || (name !== undefined && RUNTIME_LOADERS.has(name))))
+                found.push(specifier);
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(parsed, visit);
+    return found;
+};
+const stripModuleExtension = (p) => {
+    const ext = MODULE_EXTENSIONS.find((e) => p.endsWith(e));
+    return ext ? p.slice(0, -ext.length) : p;
+};
+const isFile = (p) => existsSync(p) && statSync(p).isFile();
+/** The workspace a file belongs to: its nearest ancestor holding a package.json. */
+const workspaceRootOf = (file) => {
+    for (let dir = dirname(resolve(file));; dir = dirname(dir)) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        if (dirname(dir) === dir)
+            return undefined;
+    }
+};
+/** The walk from a test to its subject, with each file's specifiers read once. */
+export class ImportWalk {
+    #specifiers = new Map();
+    #ts;
+    #config;
+    constructor(ts, config) {
+        this.#ts = ts;
+        this.#config = config;
+    }
+    #specifiersOf(file) {
+        let found = this.#specifiers.get(file);
+        if (found === undefined) {
+            found = moduleSpecifiers(this.#ts, readFileSync(file, 'utf8'), file);
+            this.#specifiers.set(file, found);
+        }
+        return found;
+    }
+    /** An absolute extensionless path, or undefined for what cannot be followed (a package, an unknown alias). */
+    #resolveSpecifier(specifier, fromFile) {
+        if (specifier.startsWith('.'))
+            return stripModuleExtension(resolve(dirname(fromFile), specifier));
+        for (const [prefix, dir] of this.#config.aliases) {
+            if (!specifier.startsWith(prefix))
+                continue;
+            const root = workspaceRootOf(fromFile);
+            return root === undefined ? undefined : stripModuleExtension(resolve(root, dir, specifier.slice(prefix.length)));
+        }
+        return undefined;
+    }
+    /** Whether a test reaches its subject, directly or through up to maxHops modules it imports. */
+    reaches(testFile, sourceFile) {
+        const target = stripModuleExtension(resolve(sourceFile));
+        const start = resolve(testFile);
+        const visited = new Set([start]);
+        let frontier = [start];
+        for (let hop = 0; hop <= this.#config.maxHops; hop++) {
+            const next = [];
+            for (const file of frontier) {
+                for (const specifier of this.#specifiersOf(file)) {
+                    const resolved = this.#resolveSpecifier(specifier, file);
+                    if (resolved === undefined)
+                        continue;
+                    if (resolved === target)
+                        return true;
+                    const onDisk = resolveToFile(resolved);
+                    if (onDisk === undefined)
+                        continue;
+                    if (stripModuleExtension(onDisk) === target)
+                        return true;
+                    if (!visited.has(onDisk)) {
+                        visited.add(onDisk);
+                        next.push(onDisk);
+                    }
+                }
+            }
+            frontier = next;
+        }
+        return false;
+    }
+}
+/** The file an extensionless path names: itself with an extension, or its directory's index. */
+const resolveToFile = (extensionless) => MODULE_EXTENSIONS.map((e) => `${extensionless}${e}`).find(isFile) ?? MODULE_EXTENSIONS.map((e) => join(extensionless, `index${e}`)).find(isFile);
+/** The category of a root-relative path, or undefined when none matches. */
+export const categoryOf = (config, path) => config.categories.find(([, re]) => re.test(toPosix(path)))?.[0];
+export const isExcluded = (config, path) => config.exclude.some((re) => re.test(toPosix(path)));
+/** The test kinds found for one source file: a candidate that exists and reaches it. */
+export const foundKinds = (config, walk, root, path) => {
+    const full = resolve(root, path);
+    const dir = dirname(full);
+    const name = full.slice(dir.length + 1).replace(/\.(ts|tsx)$/, '');
+    const found = new Set();
+    for (const [kind, patterns] of config.tests) {
+        const hit = patterns.some((p) => {
+            // Function replacements: a `$` in a path is text, never a replacement pattern.
+            const candidate = resolve(root, p.replaceAll('{dir}', () => dir).replaceAll('{name}', () => name));
+            return isFile(candidate) && walk.reaches(candidate, full);
+        });
+        if (hit)
+            found.add(kind);
+    }
+    return found;
+};
+/** The gaps among root-relative `paths`: each `.ts`/`.tsx` file, not excluded, in a category, missing a kind. */
+export const findGaps = (ts, config, root, paths) => {
+    const walk = new ImportWalk(ts, config);
+    const gaps = [];
+    let judged = 0;
+    for (const path of paths) {
+        const rel = toPosix(path);
+        if (!/\.(ts|tsx)$/.test(rel) || isExcluded(config, rel))
+            continue;
+        const category = categoryOf(config, rel);
+        if (category === undefined)
+            continue;
+        judged++;
+        const found = foundKinds(config, walk, root, rel);
+        const missing = (config.required.get(category) ?? []).filter((k) => !found.has(k));
+        if (missing.length > 0)
+            gaps.push({ file: rel, category, missing });
+    }
+    return { gaps, judged, listed: paths.length };
+};
+/** A listing's entries: NUL-separated when it holds a NUL, else one per line; a leading BOM dropped. */
+export const entries = (text) => {
+    const body = text.startsWith('') ? text.slice(1) : text;
+    return body.split(body.includes('\0') ? '\0' : /\r?\n/).filter(Boolean);
+};
+/** Every tracked regular file under root: not deleted in the working tree, not a symlink. */
+export const treePaths = (root, listed) => entries(listed).filter((p) => lstatOrUndefined(join(root, p))?.isFile() === true);
+/**
+ * The root-relative path of each listed entry (relative to root, or absolute).
+ * An entry naming nothing, or outside the root, throws: a list that cannot be
+ * read as given is not a list that passed. A symlink is not a source file and
+ * is skipped, as git's own listings do. Directories are resolved through their
+ * real path, so a symlinked checkout prefix still matches `^`-anchored rules.
+ */
+export const listedPaths = (root, text) => {
+    const out = [];
+    for (const entry of entries(text)) {
+        const abs = resolve(root, entry);
+        const stat = lstatOrUndefined(abs);
+        if (stat === undefined)
+            throw new Error(`listed file ${entry} does not exist`);
+        if (stat.isSymbolicLink())
+            continue;
+        const rel = relative(root, join(realpathSync(dirname(abs)), basename(abs)));
+        if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+            throw new Error(`listed file ${entry} is outside ${root}`);
+        if (stat.isFile())
+            out.push(toPosix(rel));
+    }
+    return out;
+};
+const lstatOrUndefined = (p) => {
+    try {
+        return lstatSync(p);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT' || e.code === 'ENOTDIR')
+            return undefined;
+        throw e;
+    }
+};
+const P = 'pariksha coverage-by-type:';
+export const formatGaps = (config, findings) => {
+    const { gaps, judged, listed } = findings;
+    if (gaps.length === 0)
+        return { ok: true, out: [`${P} ${judged} of ${listed} listed file(s) judged, each has the tests its category needs`], err: [] };
+    const err = [];
+    const byCategory = new Map();
+    for (const g of gaps)
+        byCategory.set(g.category, [...(byCategory.get(g.category) ?? []), g]);
+    for (const [category, list] of byCategory) {
+        err.push(`${P} ${category} (needs: ${(config.required.get(category) ?? []).join(', ')} tests)`);
+        for (const g of list)
+            err.push(`  ${g.file}: missing ${g.missing.join(', ')}`);
+    }
+    err.push('', `${P} ${gaps.length} file(s) missing required tests. A suite counts only when it imports its subject at runtime.`);
+    if (config.hint !== undefined)
+        err.push(config.hint);
+    return { ok: false, out: [], err };
+};

package/dist/export-deletions.js

@@ -10,13 +10,12 @@
 //   Removes-Export: <symbol> — <why>     covers one symbol
 //   Removes-File: <path> — <why>         covers every export of a file that
 //                                        no longer exists at HEAD
-import { must } from './git.js';
+import { must, PLAIN_DIFF } from "./git.js";
 export const SOURCE_GLOBS = ['*.ts', '*.tsx', '*.js', '*.jsx', '*.mjs', '*.cjs', '*.mts', '*.cts'];
 /** Build output and vendored code never count as a source change, or as a use. */
 const SKIPPED = ['node_modules', 'dist', 'build', 'coverage', 'generated'];
 const SKIPPED_DIR = new RegExp(`(^|/)(${SKIPPED.join('|')})/`);
 const SKIPPED_PATHSPECS = SKIPPED.map((d) => `:(exclude,glob)**/${d}/**`);
-const PLAIN_DIFF = ['--no-renames', '--no-color', '--no-ext-diff', '--no-textconv'];
 /**
  * A removed named declaration on a `-` diff line. Bare re-export lists
  * (`export { a, b }`) are left out: they shuffle in refactors and name nothing new.

package/dist/git.js

@@ -5,12 +5,17 @@ import { execFileSync } from 'node:child_process';
  * quoted non-ASCII paths would name no file, and a column field would hide a
  * grep hit's text.
  */
-export const PINNED = ['-c', 'core.quotePath=off', '-c', 'grep.column=false', '-c', 'color.ui=never'];
+export const PINNED = ['-c', 'core.quotePath=off', '-c', 'grep.column=false', '-c', 'color.ui=never', '-c', 'core.precomposeUnicode=false'];
+/** Variables that change how git reads a pathspec, so `:(literal)` would name no file. */
+const PATHSPEC_ENV = ['GIT_LITERAL_PATHSPECS', 'GIT_GLOB_PATHSPECS', 'GIT_NOGLOB_PATHSPECS', 'GIT_ICASE_PATHSPECS'];
+/** The environment git runs in: the caller's, less the pathspec switches. */
+export const gitEnv = (env) => Object.fromEntries(Object.entries(env).filter(([k]) => !PATHSPEC_ENV.includes(k)));
 export const gitAt = (root) => ({
     run: (args) => {
         try {
             return execFileSync('git', [...PINNED, ...args], {
                 cwd: root,
+                env: gitEnv(process.env),
                 encoding: 'utf8',
                 maxBuffer: 1 << 28,
                 stdio: ['ignore', 'pipe', 'ignore'],
@@ -28,9 +33,17 @@ export const gitAt = (root) => ({
  * there whichever directory it was started in.
  */
 export const gitAtTop = (dir) => {
-    const top = gitAt(dir).run(['rev-parse', '--show-toplevel'])?.trim();
-    return top ? gitAt(top) : undefined;
+    const top = topOf(dir);
+    return top === undefined ? undefined : gitAt(top);
 };
+/** The top level of the repository holding `dir`, or undefined outside one. */
+export const topOf = (dir) => gitAt(dir).run(['rev-parse', '--show-toplevel'])?.trim() || undefined;
+/**
+ * Diff output a user's config cannot reshape: no colour, external tool,
+ * textconv or rename pairing, and lines even for a file git or its
+ * attributes class as binary, which would otherwise show no hunk at all.
+ */
+export const PLAIN_DIFF = ['--no-renames', '--no-color', '--no-ext-diff', '--no-textconv', '--text'];
 /** A git call whose failure must stop the check rather than read as "nothing found". */
 export const must = (git, args) => {
     const out = git.run(args);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@veda-hq/pariksha",
-  "version": "0.3.1",
-  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. Checks: boundary, doc-budgets, export-deletions.",
+  "version": "0.5.1",
+  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. Checks: authority-citations, boundary, coverage-by-type, doc-budgets, export-deletions.",
   "keywords": [
     "repository checks",
     "lint",
@@ -30,9 +30,17 @@
   "files": [
     "dist"
   ],
+  "peerDependencies": {
+    "typescript": ">=5.4 <6"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "24.19.2",
-    "typescript": "7.0.2"
+    "typescript": "5.9.3"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",