@veda-hq/pariksha 0.1.0 → 0.3.2

package/README.md

@@ -3,24 +3,115 @@
 परीक्षा, examination. Repository checks: doc drift, rule enforcement,
 test-quality ratchets. Part of [Veda](https://github.com/veda-hq/veda).
 
-## v0.1: `pariksha boundary`
+```sh
+npx @veda-hq/pariksha@0.3.2 <check> [flags]
+npx @veda-hq/pariksha@0.3.2 --version
+```
 
-Refuses any file git tracks, by its path or its text, that names a word on
-the repository's deny list.
+Every check exits 0 when the repository passes, 1 when it refuses something
+(each finding on stderr, with how to fix it), and 2 on a usage or input
+error. `--root <dir>` (default: the current directory) names the repository.
+Node 24 or later. MIT.
+
+## `authority-citations`
 
 ```sh
-npx @veda-hq/pariksha@0.1.0 boundary [--root <dir>] [--deny <file>]
-npx @veda-hq/pariksha@0.1.0 hash <word>
-npx @veda-hq/pariksha@0.1.0 --version
+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
+pariksha boundary [--root <dir>] [--deny <file>]
+pariksha hash <word>
+```
+
+Refuses any file git tracks, by its path or its text, that names a word on
+the repository's deny list.
+
 - The deny list (default `.veda/deny.sha256`, relative to the root) holds one
   SHA-256 hash of a lowercase word per line; blank lines and `#` comments are
   ignored. `pariksha hash <word>` prints the line for a word.
 - Words are runs of ASCII letters and digits, compared case-insensitively:
   `foo-bar`, `foo_bar` and `@Foo/bar` all contain the word `foo`.
 - Binary files (any NUL byte) are skipped. Untracked files are not read.
-- Exit codes: 0 clean, 1 a denied word was found (each is listed with its file
-  and line; line 0 is the file's path), 2 a usage or deny-list error.
+  Line 0 in a finding is the file's path.
 
-Node 24 or later. MIT.
+## `doc-budgets`
+
+```sh
+pariksha doc-budgets --table <file> [--section <name>] [--root <dir>]
+```
+
+Keeps the documents agents read on every turn inside a byte budget. The
+budgets are one Markdown table, under `## Budgets` (or `--section`) in the
+`--table` file:
+
+```md
+## Budgets
+
+| Doc         | Budget |
+| ----------- | -----: |
+| `CLAUDE.md` | 9,000  |
+```
+
+Refuses a file over its budget, a budgeted file that does not exist, and a
+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.
+
+## `export-deletions`
+
+```sh
+pariksha export-deletions [--base <ref>] [--root <dir>]
+```
+
+An agent that removes a public function can remove its callers and their
+tests too: everything typechecks and passes, so only a statement of intent
+tells a correct removal from a coherent mistake. This check compares
+`<base>...HEAD` and refuses an exported declaration (`export const`,
+`function`, `class`, `interface`, `type`, `enum`) that is gone from every
+TypeScript and JavaScript file at HEAD, unless a commit body in the range
+declares it:
+
+```text
+Removes-Export: <symbol> — <why it is safe to remove>
+Removes-File: <path> — <why the file is gone>
+```
+
+`Removes-File` covers every export of a file that no longer exists at HEAD.
+A symbol still used anywhere (a move, a rename with its callers, a re-export)
+is never reported; a mention in a comment does not count as a use. Bare
+`export { a, b }` lists and files under `node_modules`, `dist`, `build`,
+`coverage` and `generated` are not read. Without `--base`, the base is the
+first of `origin/main`, `origin/develop`, `origin/master` and `main` that
+exists. It reads the whole repository from any directory inside it, and
+renames, colour, external diff tools and textconv in a user's git config
+do not change what it reads. With no base, or when git cannot read the
+range (no merge base, a shallow clone), it exits 2: nothing was checked,
+so it is not a pass.

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

@@ -1,13 +1,20 @@
 #!/usr/bin/env node
-// pariksha: repository checks. v0.1 has one, `boundary`.
+// pariksha: repository checks. One subcommand per check.
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+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 { checkBudgets } from './doc-budgets.js';
+import { checkExportDeletions, formatReport } from './export-deletions.js';
+import { BASE_CANDIDATES, gitAt, gitAtTop, 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 doc-budgets --table <file> [--section <name>] [--root <dir>]',
+    '       pariksha export-deletions [--base <ref>] [--root <dir>]',
     '       pariksha hash <word>',
     '       pariksha --version',
 ].join('\n');
@@ -29,23 +36,19 @@ export const trackedFiles = (root) => {
     }
     return files;
 };
-const flags = (rest) => {
+/** `--name value` pairs, each name allowed once and from `allowed`; undefined on anything else. */
+export const flags = (rest, allowed) => {
     const out = new Map();
     for (let i = 0; i < rest.length; i += 2) {
         const name = rest[i];
         const value = rest[i + 1];
-        if ((name !== '--root' && name !== '--deny') || !value || out.has(name))
+        if (name === undefined || !allowed.includes(name) || !value || out.has(name))
             return undefined;
         out.set(name, value);
     }
     return out;
 };
-const boundary = (rest, io) => {
-    const f = flags(rest);
-    if (!f) {
-        io.err(USAGE);
-        return 2;
-    }
+const boundary = (f, io) => {
     const root = resolve(f.get('--root') ?? '.');
     const denyPath = resolve(root, f.get('--deny') ?? DENY_FILE);
     if (!existsSync(denyPath)) {
@@ -72,7 +75,101 @@ const boundary = (rest, io) => {
     io.out(`pariksha boundary: ${files.length} files, none names a denied word (${deny.size} on the list)`);
     return 0;
 };
-export const run = (args, io, version = ownVersion()) => {
+const fileSize = (path) => {
+    try {
+        const s = statSync(path);
+        return s.isFile() ? s.size : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const docBudgets = (f, io) => {
+    const table = f.get('--table');
+    if (table === undefined) {
+        io.err(USAGE);
+        return 2;
+    }
+    const root = resolve(f.get('--root') ?? '.');
+    const tablePath = resolve(root, table);
+    if (fileSize(tablePath) === undefined) {
+        io.err(`pariksha doc-budgets: no budget table at ${tablePath}`);
+        return 2;
+    }
+    const outcome = checkBudgets(readFileSync(tablePath, 'utf8'), f.get('--section') ?? 'Budgets', relative(root, tablePath), (p) => fileSize(resolve(root, p)));
+    outcome.out.forEach(io.out);
+    outcome.err.forEach(io.err);
+    return outcome.ok ? 0 : 1;
+};
+const exportDeletions = (f, io) => {
+    const dir = resolve(f.get('--root') ?? '.');
+    const git = gitAtTop(dir);
+    if (git === undefined) {
+        io.err(`pariksha export-deletions: ${dir} is not in a git repository`);
+        return 2;
+    }
+    const asked = f.get('--base');
+    const base = asked === undefined ? resolveBase(git) : resolveBase(git, [asked]);
+    if (base === undefined) {
+        // A shallow single-branch checkout lands here; passing it would pass unread work.
+        io.err(asked === undefined
+            ? `pariksha export-deletions: none of ${BASE_CANDIDATES.join(', ')} names a commit; fetch one or pass --base`
+            : `pariksha export-deletions: --base ${asked} names no commit`);
+        return 2;
+    }
+    let report;
+    try {
+        report = checkExportDeletions(git, base);
+    }
+    catch (e) {
+        io.err(`pariksha export-deletions: ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+    const result = formatReport(report);
+    result.out.forEach(io.out);
+    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 COMMANDS = {
+    'authority-citations': { allowed: ['--mode', '--authority', '--issue-prefix', '--adr-dir', '--root'], run: authorityCitations },
+    boundary: { allowed: ['--root', '--deny'], run: boundary },
+    'doc-budgets': { allowed: ['--table', '--section', '--root'], run: docBudgets },
+    'export-deletions': { allowed: ['--base', '--root'], run: exportDeletions },
+};
+export const run = (args, io, version = ownVersion(), env = process.env) => {
     const [command, ...rest] = args;
     if (command === '--version' && rest.length === 0) {
         io.out(version);
@@ -82,10 +179,13 @@ export const run = (args, io, version = ownVersion()) => {
         io.out(hash(rest[0]));
         return 0;
     }
-    if (command === 'boundary')
-        return boundary(rest, io);
-    io.err(USAGE);
-    return 2;
+    const spec = command !== undefined && Object.hasOwn(COMMANDS, command) ? COMMANDS[command] : undefined;
+    const f = spec && flags(rest, spec.allowed);
+    if (!spec || !f) {
+        io.err(USAGE);
+        return 2;
+    }
+    return spec.run(f, io, env);
 };
 const isMain = () => {
     const entry = process.argv[1];

package/dist/doc-budgets.js

@@ -0,0 +1,60 @@
+// The doc-budgets check: documents that agents read on every turn stay inside
+// a byte budget. The budgets live in one Markdown table, so the rule that sets
+// them is also the only list of them:
+//
+//   ## Budgets
+//
+//   | Doc         | Budget |
+//   | ----------- | -----: |
+//   | `CLAUDE.md` | 9,000  |
+/** The text of the `## <section>` section, up to the next `## ` heading; '' when absent. */
+export const section = (markdown, name) => {
+    // Line endings normalised and a leading newline added, so a CRLF file and a
+    // heading on the first line read like any other.
+    const text = `\n${markdown.replaceAll('\r\n', '\n')}`;
+    const start = text.indexOf(`\n## ${name}\n`);
+    if (start === -1)
+        return '';
+    const end = text.indexOf('\n## ', start + 1);
+    return text.slice(start, end === -1 ? undefined : end);
+};
+/** Table lines after the header row and its `| --- |` (or `|:--|`) separator. */
+export const dataRows = (text) => text
+    .split('\n')
+    .filter((line) => line.startsWith('|'))
+    .slice(1)
+    .filter((line) => !/^\|\s*:?-/.test(line));
+/** Rows of the form "| `path` | 1,200 |". */
+export const parseBudgets = (text) => [...text.matchAll(/^\|\s*`([^`]+)`\s*\|\s*([\d,]+)\s*\|$/gm)].map(([, path = '', bytes = '']) => ({
+    path,
+    bytes: Number(bytes.replaceAll(',', '')),
+}));
+/**
+ * Every budget row is well formed, and every file it names is within budget.
+ * `size` returns a file's byte length, or undefined when it does not exist.
+ */
+export const checkBudgets = (table, sectionName, tablePath, size) => {
+    const text = section(table, sectionName);
+    const budgets = parseBudgets(text);
+    const rows = dataRows(text);
+    const err = [];
+    if (rows.length === 0)
+        err.push(`pariksha doc-budgets: ${tablePath} has no table under "## ${sectionName}"`);
+    else if (budgets.length !== rows.length)
+        err.push(`pariksha doc-budgets: ${tablePath}: ${rows.length - budgets.length} row(s) under "## ${sectionName}" are not "| \`path\` | bytes |", so nothing enforces them`);
+    // The table is read on every check, so it is a hot document too; a table
+    // without its own row could grow without limit while every row it lists passes.
+    if (rows.length > 0 && !budgets.some((b) => b.path === tablePath))
+        err.push(`pariksha doc-budgets: ${tablePath} sets budgets but has no row for itself; add "| \`${tablePath}\` | <bytes> |"`);
+    const out = [];
+    for (const b of budgets) {
+        const bytes = size(b.path);
+        if (bytes === undefined)
+            err.push(`pariksha doc-budgets: ${b.path} has a budget but does not exist`);
+        else if (bytes > b.bytes)
+            err.push(`pariksha doc-budgets: ${b.path} is ${bytes} bytes, over its budget of ${b.bytes}; cut it`);
+        else
+            out.push(`pariksha doc-budgets: ${b.path} ${bytes} / ${b.bytes} bytes`);
+    }
+    return { ok: err.length === 0, out, err };
+};

package/dist/export-deletions.js

@@ -0,0 +1,124 @@
+// The export-deletions check: a public export that disappears from the whole
+// tree on a branch needs a stated reason, a commit trailer naming it.
+//
+// An agent that removes a public function can also remove its callers and the
+// tests that used it: everything typechecks and passes, so nothing internal
+// tells a correct removal from a coherent mistake. Only a statement of intent
+// can, so the check asks for one, and stays quiet for anything that moved:
+// a symbol still named anywhere in the tree's source is not reported.
+//
+//   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, 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}/**`);
+/**
+ * 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.
+ */
+const EXPORT_DECL = /^-\s*export\s+(?:default\s+)?(?:declare\s+)?(?:async\s+)?(?:abstract\s+)?(?:const\s+enum|const|let|var|function|class|interface|type|enum|namespace)[\s*]+([A-Za-z_$][A-Za-z0-9_$]*)/;
+/**
+ * A grep hit (`HEAD:path:line:text`) whose text starts a comment (`//`, `*`,
+ * `/*`) is a mention, not a use. Unanchored, so a colon in a path still matches.
+ */
+const COMMENT_HIT = /:\d+:\s*(?:\/\/|\*|\/\*)/;
+const unique = (xs) => [...new Set(xs)].sort();
+/** Symbols named by `Removes-Export:` trailers: the first word, trailing punctuation dropped. */
+export const declaredExports = (messages) => unique(messages
+    .split('\n')
+    .map((line) => /^\s*removes-export:\s*(\S+)/i.exec(line)?.[1]?.replace(/[,;()]+$/, ''))
+    .filter((s) => s !== undefined && s !== ''));
+/**
+ * Paths named by `Removes-File:` trailers. The path runs up to the " — " or
+ * " - " that starts the reason, so a path with a space in it survives.
+ */
+export const declaredFiles = (messages) => unique(messages
+    .split('\n')
+    .map((line) => /^\s*removes-file:\s*(.*)$/i
+    .exec(line)?.[1]
+    ?.replace(/\s+(?:—|-)\s.*$/, '')
+    .trim()
+    .replace(/[,;()]+$/, ''))
+    .filter((s) => s !== undefined && s !== ''));
+/** The symbols a unified diff removes from export declarations. */
+export const removedExports = (diff) => diff
+    .split('\n')
+    .map((line) => EXPORT_DECL.exec(line)?.[1])
+    .filter((s) => s !== undefined);
+/** True when some `git grep -n <sym> HEAD` hit is code rather than a comment. */
+export const usedOutsideComments = (hits) => hits.split('\n').some((hit) => hit !== '' && !COMMENT_HIT.test(hit));
+/**
+ * Compares `base...HEAD`: every export removed and named nowhere in HEAD's
+ * source must be declared. A git failure throws (with no merge base, say, in a
+ * shallow clone): the check cannot pass without having read the branch.
+ */
+export const checkExportDeletions = (git, base) => {
+    const messages = must(git, ['log', '--format=%B', `${base}..HEAD`]);
+    const symbols = new Set(declaredExports(messages));
+    const files = new Set(declaredFiles(messages));
+    // Renames off, so a file moved and edited lists its old path, whose removed
+    // lines the per-file diff then shows; colour, external diff tools and
+    // textconv off, so a user's config cannot rewrite the lines read here.
+    // NUL-separated, so no name comes back quoted.
+    const changed = must(git, ['diff', ...PLAIN_DIFF, '-z', '--name-only', '--diff-filter=ACMRD', `${base}...HEAD`, '--', ...SOURCE_GLOBS])
+        .split('\0')
+        .filter((f) => f !== '' && !SKIPPED_DIR.test(f));
+    const violations = [];
+    const declared = [];
+    const coveredFiles = [];
+    const used = new Map();
+    for (const file of changed) {
+        // `:(literal)` so a name like `src/[id].ts` names only itself.
+        const spec = `:(literal)${file}`;
+        const removed = removedExports(must(git, ['diff', ...PLAIN_DIFF, '-U0', `${base}...HEAD`, '--', spec]));
+        if (removed.length === 0)
+            continue;
+        // A file trailer covers a file only once HEAD has nothing at its path.
+        if (files.has(file) && must(git, ['ls-tree', '--name-only', 'HEAD', '--', spec]).trim() === '') {
+            coveredFiles.push(file);
+            continue;
+        }
+        for (const symbol of removed) {
+            let stillUsed = used.get(symbol);
+            if (stillUsed === undefined) {
+                // git grep exits 1 when nothing matches, so undefined here is "no hit".
+                // Skipped trees are excluded here too: a stale committed build naming the symbol is no use.
+                stillUsed = usedOutsideComments(git.run(['grep', '--no-color', '-nwF', '-e', symbol, 'HEAD', '--', ...SOURCE_GLOBS, ...SKIPPED_PATHSPECS]) ?? '');
+                used.set(symbol, stillUsed);
+            }
+            if (stillUsed)
+                continue;
+            (symbols.has(symbol) ? declared : violations).push({ symbol, file });
+        }
+    }
+    return { base, violations, declared, declaredFiles: coveredFiles };
+};
+/** The report as output lines; a refusal tells the author how to declare a removal. */
+export const formatReport = (report) => {
+    const out = [
+        ...report.declaredFiles.map((f) => `pariksha export-deletions: ${f} deleted; a Removes-File trailer declares its exports`),
+        ...report.declared.map((d) => `pariksha export-deletions: ${d.symbol} removed from ${d.file}; a Removes-Export trailer declares it`),
+    ];
+    if (report.violations.length === 0) {
+        out.push(`pariksha export-deletions: no undeclared export removals since ${report.base}`);
+        return { ok: true, out, err: [] };
+    }
+    const err = [
+        `pariksha export-deletions: ${report.violations.length} export(s) removed from the whole tree since ${report.base} with no stated reason:`,
+        ...report.violations.map((v) => `  ${v.symbol}   (removed from ${v.file})`),
+        '',
+        'Each is gone from every source file, not moved or renamed. If the removal is intended,',
+        'say so in a commit body:',
+        '',
+        '  Removes-Export: <symbol> — <why it is safe to remove>',
+        '',
+        'A file deleted outright can be declared once, covering all its exports:',
+        '',
+        '  Removes-File: <path> — <why the file is gone>',
+    ];
+    return { ok: false, out, err };
+};

package/dist/git.js

@@ -0,0 +1,56 @@
+// Git, as the checks read it: a function from arguments to stdout.
+import { execFileSync } from 'node:child_process';
+/**
+ * Settings that change what git prints, pinned so a user's config cannot:
+ * quoted non-ASCII paths would name no file, and a column field would hide a
+ * grep hit's text.
+ */
+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'],
+                timeout: 120_000,
+            });
+        }
+        catch {
+            return undefined;
+        }
+    },
+});
+/**
+ * Git at the top level of the repository holding `dir`, or undefined outside
+ * one. Paths git prints are relative to the top level, so every check runs
+ * there whichever directory it was started in.
+ */
+export const gitAtTop = (dir) => {
+    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);
+    if (out === undefined)
+        throw new Error(`git ${args.join(' ')} failed`);
+    return out;
+};
+export const BASE_CANDIDATES = ['origin/main', 'origin/develop', 'origin/master', 'main'];
+/** The first ref that names a commit, or undefined. */
+export const resolveBase = (git, candidates = BASE_CANDIDATES) => candidates.find((ref) => git.run(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]) !== undefined);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@veda-hq/pariksha",
-  "version": "0.1.0",
-  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. v0.1: the boundary check, which refuses any tracked file naming a denied word.",
+  "version": "0.3.2",
+  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. Checks: authority-citations, boundary, doc-budgets, export-deletions.",
   "keywords": [
     "repository checks",
     "lint",