@veda-hq/pariksha 0.5.14 → 0.5.17

package/NOTICE

@@ -0,0 +1,6 @@
+@veda-hq/pariksha includes third-party code:
+
+- src/semver-range.ts (dist/semver-range.js) is ported from semver 7.8.1
+  (npm `semver`, https://github.com/npm/node-semver), ISC licence,
+  Copyright (c) Isaac Z. Schlueter and Contributors. The licence text is in
+  the file's header.

package/README.md

@@ -4,14 +4,87 @@
 test-quality ratchets. Part of [Veda](https://github.com/veda-hq/veda).
 
 ```sh
-npx @veda-hq/pariksha@0.5.14 <check> [flags]
-npx @veda-hq/pariksha@0.5.14 --version
+npx @veda-hq/pariksha@0.5.17 <check> [flags]
+npx @veda-hq/pariksha@0.5.17 --version
 ```
 
 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.
+(each finding on stderr, with how to fix it; `absolute-paths` and
+`non-synced-resources` print theirs on stdout, as the shell checks they were
+ported from did), and 2 on a usage or input error. `--root <dir>` (default:
+the current directory) names the repository. Node 24 or later. MIT; one
+ported file is ISC, see `NOTICE`.
+
+## `absolute-paths`
+
+```sh
+pariksha absolute-paths [--config <file>] [--files-from <file>|-] [--root <dir>]
+```
+
+A document that points at `/Users/me/notes.md` points at something only its
+writer has. This refuses a line naming a path on a local machine: `file://`,
+`/Users/`, `/home/<name>/`, `/tmp/<x>`, `/var/<x>`, `/private/var`, `~/`, or a
+drive (`C:\x`). Not refused: a line inside a fenced block (between lines that
+start with three backticks), a path in an inline code span, and a line that
+says it is an example (`forbidden`, `example`, `not allowed`, `should not`,
+`must not`, in any case). Only the first path on a line is tested for a code
+span, and a `/tmp/<x>` or `/var/<x>` path runs to the next `/`, so
+`` `/tmp/x` `` alone on a line is refused: the shell check this was ported
+from read it so.
+
+The documents are the ones `--files-from` lists, one path per line (a file,
+or `-` for stdin; relative paths are read from the root), or with no list
+every file git tracks; a listed path that is not a regular file is dropped.
+The JSON `--config` (relative to the root) is optional:
+
+```json
+{
+  "include": "\\.(md|mdx)$",
+  "guidance": ["Please use relative paths only.", "See docs/WRITING.md."]
+}
+```
+
+- `include` (default `\.(md|mdx)$`) is the regex a listed path must match to
+  be a document.
+- `guidance` (default one line asking for relative paths) is printed after a
+  refusal.
+
+The report goes to stdout: `→ Checking …`, `Checking N documentation
+file(s)...`, then each finding as `file:line:text`. It exits 1 on a finding,
+0 with none or nothing to check, and 2 on a bad config, an unreadable list,
+or no list outside a git repository.
+
+## `aggregate-gate-needs`
+
+```sh
+pariksha aggregate-gate-needs [--config <file>] [--root <dir>]
+```
+
+A merge queue that requires one aggregate status, a workflow's "CI Gate",
+lets through any job that gate does not wait on: a job missing from its
+`needs:` cannot block a merge however it fails, and an upstream failure turns
+into a skip downstream that the gate accepts. Each shows a green required
+check. In every `.yml` and `.yaml` workflow, a gate (a job whose `name:`, or
+id, matches `gateName`) is refused when its `needs:` leaves out a job other
+than another gate or a `nonGating` one, or when it reads a job's result
+without declaring it: `needs.<id>` or `needs['<id>']` in the job's `if:`, a
+step's `if:`, or any `${{ … }}` in the job, outside quoted literals. Text in
+a `run:` script and an action input named `if` are not reads. A non-gating
+job (a change detector) need not be gated, but must be declared once read.
+
+```json
+{ "id": "CI-001", "workflowsDir": ".github/workflows", "gateName": "gate$", "nonGating": ["detect-changes"] }
+```
+
+- `id` (default `aggregate-gate-needs`) names the check in its messages: a
+  project's rule id, say.
+- `workflowsDir` (default `.github/workflows`, relative to the root).
+- `gateName` (default `gate$`) is a regex, matched case-insensitively.
+- `nonGating` (default none) lists job ids that gate nothing.
+
+A workflow that does not parse is reported as a gap, never passed. No
+workflow to read exits 1 (`no workflow files found — the lookup failed`),
+as the original did; a bad config exits 2.
 
 ## `authority-citations`
 
@@ -667,6 +740,77 @@ root-relative POSIX path, a check not in `checks`, an `exemptIn` group
 baseline, a root holding no tracked file, a group discovering nothing, no
 base without `--no-base`, a failed git call, or no `typescript`.
 
+## `non-synced-resources`
+
+```sh
+pariksha non-synced-resources [--config <file>] [--files-from <file>|-] [--root <dir>]
+```
+
+A link to a file that was never committed works for its writer and for
+nobody else. Every `[text](dest)` and `![alt](dest)` on a line of a document
+(inside code blocks too) is read, except `http(s)://`, `mailto:` and `#`
+links. The destination loses its `#fragment` and `?query`, then is the text
+inside `<…>` or the text before a space (a title); one starting with `/` is
+read from the repository's top folder. It is refused when its folder does
+not exist, when it lands outside the repository, when nothing is there, or
+when the name on disk differs in case (macOS opens `./README.MD` as
+`./readme.md`; Linux and CI do not). An image over 1 MiB is warned about,
+never refused. Paths are joined and split as the shell check this was ported
+from joined them (`dirname`, `basename`, `cd && pwd`), so what counts as
+inside the repository is unchanged.
+
+The documents, the config (`include`, `guidance`) and the report on stdout
+are as for [`absolute-paths`](#absolute-paths); a document listed by absolute
+path has its links read from its own folder. With `--files-from`, a
+repository is needed only when there is a document to read; without it, the
+documents come from `git ls-files`, so a root that is not a repository exits
+2 even when it holds no document.
+
+## `pnpm-settings`
+
+```sh
+pariksha pnpm-settings [--config <file>] [--root <dir>]
+```
+
+pnpm 11 stopped reading the `pnpm` field of package.json without a warning
+(pnpm/pnpm#11536): an `overrides` or `patchedDependencies` left there gives a
+green install in which every security pin has reverted and every patch has
+stopped applying. A green install proves nothing, so this reads the resolved
+`pnpm-lock.yaml` (the last of its YAML documents, which pnpm 12 writes after
+its own) and refuses:
+
+1. a setting pnpm 11 ignores still in `package.json#pnpm`;
+2. an override in `pnpm-workspace.yaml` the lockfile does not record, records
+   differently, or still records after it was removed;
+3. the same for a patch, a patch file that is not on disk, or one whose
+   sha256 is not the one the lockfile records;
+4. a resolved version inside the range an override excludes
+   (`tar@<=7.5.20`), or, for a bare-name override (`tar: '>=7.5.21'`),
+   outside the range it forces. Prereleases count: `7.5.20-beta.1` is inside
+   `<=7.5.20`;
+5. a `minimumReleaseAgeExclude` entry that is not one exact version the
+   lockfile still resolves, or whose list has no comment right above it, no
+   `EXPIRES: <ISO-8601>` line, or an expiry already past. `ownScopes` entries
+   are standing and exempt.
+
+```json
+{ "id": "CFG-005", "ownScopes": ["@your-scope/*"] }
+```
+
+- `id` (default `pnpm-settings`) names the check in its messages.
+- `ownScopes` (default none) lists `minimumReleaseAgeExclude` entries asked
+  for no expiry or exact version: a project's own scopes, released by its own
+  CI.
+
+Ranges are read by pariksha's own matcher, a port of the `semver` package's
+range reading (strict mode, prereleases included): comparator sets joined by
+`||`, comparators joined by spaces, and the same sugar (`^`, `~`, `1.x`,
+`*`, partial versions such as `<8`, hyphen ranges). A range `semver` would
+refuse is not passed: it is printed as a selector not version-checked.
+`semver`'s loose mode is not read. Notes and failures go to stderr, the clean
+line to stdout; a missing input file is a failure (exit 1), a bad config or
+an unreadable `package.json` exits 2.
+
 ## `required-settings`
 
 ```sh

package/dist/absolute-paths.js

@@ -0,0 +1,59 @@
+// absolute-paths: no document names a path on the writer's own machine.
+//
+// A doc that says `see /Users/me/code/app/notes.md` or `file:///home/me/x`
+// points at something nobody else has. This check refuses a line of prose
+// that holds such a path: `file://`, `/Users/`, `/home/<name>/`, `/tmp/<x>`,
+// `/var/<x>`, `/private/var`, `~/`, or a drive (`C:\x`). Not refused: a line
+// inside a fenced block (between lines that start with three backticks), a
+// path inside an inline code span, and a line that says it is an example
+// ("forbidden", "example", "not allowed", "should not", "must not", any case).
+//
+// Ported from a shell check unchanged, quirks included: only the first path on
+// a line is tested for a code span, and that path runs to the next `/`, so a
+// span's closing backtick may fall inside it.
+import { linesOf } from "./doc-files.js";
+/** A local path, as the shell check's grep and awk matched it. */
+export const LOCAL_PATH = /(file:\/\/|\/Users\/|\/home\/[^/]+\/|C:\\[^/]|\/tmp\/[^/]+|\/var\/[^/]+|\/private\/var|~\/|[A-Z]:\\[^/])/;
+/** A line that says it shows what not to do. */
+export const EXAMPLE_LINE = /(forbidden|example|not allowed|should not|must not)/i;
+export const DEFAULT_GUIDANCE = ['Please use relative paths only.'];
+const FENCE = /^```/;
+const backticks = (text) => text.split('`').length - 1;
+/**
+ * Whether the first local path on `line` sits inside an inline code span: an
+ * odd number of backticks before it and at least one after it.
+ */
+export const inBackticks = (line) => {
+    const match = LOCAL_PATH.exec(line);
+    if (match === null)
+        return false;
+    const before = backticks(line.slice(0, match.index));
+    const after = backticks(line.slice(match.index + match[0].length));
+    return before > 0 && after > 0 && before % 2 === 1;
+};
+/** `file:line:text` for each refused line of one document. */
+export const findInDoc = (file, text) => {
+    const found = [];
+    let inFence = false;
+    linesOf(text).forEach((line, index) => {
+        if (FENCE.test(line)) {
+            inFence = !inFence;
+            return;
+        }
+        if (inFence || !LOCAL_PATH.test(line) || inBackticks(line) || EXAMPLE_LINE.test(line))
+            return;
+        found.push(`${file}:${index + 1}:${line}`);
+    });
+    return found;
+};
+/** The report for `docs` (path and text, in order), printed as the shell check printed it. */
+export const checkAbsolutePaths = (docs, config) => {
+    const out = ['→ Checking for absolute paths in documentation...'];
+    if (docs.length === 0)
+        return { ok: true, out: [...out, '✅ No documentation files to check.'] };
+    out.push(`   Checking ${docs.length} documentation file(s)...`);
+    const found = docs.flatMap((doc) => findInDoc(doc.file, doc.text()));
+    if (found.length === 0)
+        return { ok: true, out: [...out, '✅ No absolute paths found in documentation'] };
+    return { ok: false, out: [...out, '', '❌ Error: Absolute paths or local file references found:', '', ...found, '', ...config.guidance] };
+};

package/dist/aggregate-gate-needs.js

@@ -0,0 +1,153 @@
+// aggregate-gate-needs: an aggregate gate depends on every job it gates.
+//
+// A merge queue that requires one status, a workflow's "CI Gate", lets
+// through anything that gate does not wait on: a job missing from its
+// `needs:` cannot block a merge however it fails, and an upstream failure
+// becomes a downstream skip the gate accepts. Every such mistake shows a green
+// required check, so this refuses, in each workflow, a gate (a job whose id or
+// `name:` matches the config's `gateName`) whose `needs:` leaves out a job
+// other than another gate or one the config calls non-gating. A non-gating job
+// (a change detector, say) is exempt from "must be gated", not from "must be
+// declared when read": a gate whose `if:` or `${{ }}` reads `needs.<id>` or
+// `needs['<id>']` without declaring it gets an undefined output and skips.
+//
+// Read as conditions: the job's `if:` and each step's `if:`, and every
+// `${{ … }}` in the job. Not read: text in a `run:` script, quoted literals in
+// an expression, and an action input that happens to be called `if`. A
+// workflow that does not parse is reported, never read as having no gaps.
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { load as parseYaml } from 'js-yaml';
+export const DEFAULT_GATE_CONFIG = {
+    workflowsDir: '.github/workflows',
+    gateName: /gate$/i,
+    nonGating: new Set(),
+    id: 'aggregate-gate-needs',
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * `{ "id"?: "<label>", "workflowsDir"?: "<dir>", "gateName"?: "<regex>",
+ * "nonGating"?: ["<job id>", …] }`; `gateName` matches case-insensitively.
+ * Absent keys take the defaults; anything else throws.
+ */
+export const parseGateConfig = (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) => !['id', 'workflowsDir', 'gateName', 'nonGating'].includes(k));
+    if (unknown !== undefined)
+        throw new Error(`unknown key "${unknown}"`);
+    const text_ = (key, fallback) => {
+        // Absent takes the default; a present `null` is refused like any other wrong value.
+        const value = key in raw ? raw[key] : fallback;
+        if (typeof value !== 'string' || value.trim() === '')
+            throw new Error(`"${key}" must be a non-empty string`);
+        return value;
+    };
+    const id = text_('id', DEFAULT_GATE_CONFIG.id);
+    const workflowsDir = text_('workflowsDir', DEFAULT_GATE_CONFIG.workflowsDir);
+    const source = text_('gateName', DEFAULT_GATE_CONFIG.gateName.source);
+    let gateName;
+    try {
+        gateName = new RegExp(source, 'i');
+    }
+    catch (e) {
+        throw new Error(`"gateName" is not a regex: ${e.message}`);
+    }
+    const nonGating = 'nonGating' in raw ? raw['nonGating'] : [];
+    if (!Array.isArray(nonGating) || nonGating.some((j) => typeof j !== 'string' || j === ''))
+        throw new Error('"nonGating" must be a list of job ids');
+    return { id, workflowsDir, gateName, nonGating: new Set(nonGating) };
+};
+/** The `.yml` and `.yaml` files in the workflows folder, as root-relative paths; none when it cannot be read. */
+export const workflowFiles = (root, dir) => {
+    try {
+        return readdirSync(join(root, dir))
+            .filter((name) => name.endsWith('.yml') || name.endsWith('.yaml'))
+            .map((name) => join(dir, name));
+    }
+    catch {
+        return [];
+    }
+};
+/** The job's `if:` and each step's `if:`: the two places GitHub reads a condition. */
+const ifExpressions = (job) => {
+    const out = [];
+    if (typeof job.if === 'string')
+        out.push(job.if);
+    for (const step of job.steps ?? []) {
+        if (step && typeof step === 'object' && typeof step.if === 'string')
+            out.push(step.if);
+    }
+    return out;
+};
+/** An expression with its quoted literals emptied: `'needs.x'` is an argument, not a read. */
+const stripLiterals = (expression) => expression.replace(/'(?:[^']|'')*'/g, "''");
+/** The job ids a gate reads, by `needs.<id>` or `needs['<id>']`, in its conditions and `${{ }}` blocks. */
+export const consumedNeeds = (job) => {
+    if (!job)
+        return [];
+    const expressions = ifExpressions(job);
+    for (const m of JSON.stringify(job).matchAll(/\$\{\{([\s\S]*?)\}\}/g))
+        expressions.push(m[1] ?? '');
+    const ids = new Set();
+    for (const raw of expressions) {
+        // Brackets first, off the raw text: stripping literals would erase the quoted id.
+        for (const m of raw.matchAll(/needs\[\s*'([A-Za-z0-9_-]+)'\s*\]/g))
+            ids.add(m[1] ?? '');
+        for (const m of stripLiterals(raw).matchAll(/needs\.([A-Za-z0-9_-]+)/g))
+            ids.add(m[1] ?? '');
+    }
+    return [...ids];
+};
+const asArray = (needs) => (needs === undefined ? [] : Array.isArray(needs) ? needs : [needs]);
+/** Each gate, in each of `files` (root-relative), whose `needs:` leaves out a job it gates or reads. */
+export const findGateGaps = (root, files, config) => {
+    const gaps = [];
+    for (const relative of files) {
+        let document;
+        try {
+            // A workflow that parses to a scalar or null is no job map: read as empty.
+            const parsed = parseYaml(readFileSync(join(root, relative), 'utf8'));
+            document = typeof parsed === 'object' && parsed !== null ? parsed : {};
+        }
+        catch {
+            gaps.push({ workflow: relative, gate: '(unparseable)', missing: ['<file did not parse>'] });
+            continue;
+        }
+        const jobs = document.jobs ?? {};
+        const jobIds = Object.keys(jobs);
+        const gateIds = jobIds.filter((id) => config.gateName.test(jobs[id]?.name ?? id) || config.gateName.test(id));
+        for (const gateId of gateIds) {
+            const declared = new Set(asArray(jobs[gateId]?.needs));
+            const missing = jobIds.filter((id) => id !== gateId && !gateIds.includes(id) && !config.nonGating.has(id) && !declared.has(id));
+            const undeclared = consumedNeeds(jobs[gateId]).filter((id) => jobIds.includes(id) && !declared.has(id));
+            const all = [...new Set([...missing, ...undeclared])];
+            if (all.length > 0)
+                gaps.push({ workflow: relative, gate: gateId, missing: all });
+        }
+    }
+    return gaps;
+};
+/** The verdict on the workflows under `root`, worded as the original check worded it. */
+export const checkGates = (root, config) => {
+    const files = workflowFiles(root, config.workflowsDir);
+    if (files.length === 0)
+        return { ok: false, out: [], err: [`❌ ${config.id}: no workflow files found — the lookup failed`] };
+    const gaps = findGateGaps(root, files, config);
+    if (gaps.length === 0)
+        return { ok: true, out: [`✅ ${config.id}: every aggregate gate depends on all its jobs (${files.length} workflow(s))`], err: [] };
+    const err = [`\n❌ ${config.id}: ${gaps.length} aggregate gate(s) with an incomplete needs list\n`];
+    for (const gap of gaps)
+        err.push(` ${gap.workflow} → job "${gap.gate}"`, `   not depended on: ${gap.missing.join(', ')}\n`);
+    err.push('The merge queue checks only the gate. A job absent from its `needs:` cannot\n' +
+        'block a merge however it fails — and a failure upstream turns into a SKIP\n' +
+        'downstream, which the gate then accepts.\n');
+    return { ok: false, out: [], err };
+};

package/dist/cli.js

@@ -4,6 +4,11 @@ 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 { checkAbsolutePaths, DEFAULT_GUIDANCE as ABSOLUTE_PATHS_GUIDANCE } from "./absolute-paths.js";
+import { checkGates, DEFAULT_GATE_CONFIG, parseGateConfig as parseAggregateConfig } from "./aggregate-gate-needs.js";
+import { parseDocConfig, readDoc, selectDocs } from "./doc-files.js";
+import { checkNonSyncedResources, DEFAULT_GUIDANCE as NON_SYNCED_GUIDANCE } from "./non-synced-resources.js";
+import { checkPnpmSettings, DEFAULT_PNPM_CONFIG, formatParity, parsePnpmConfig } from "./pnpm-settings.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, parseConfig, treePaths } from "./coverage-by-type.js";
@@ -25,6 +30,8 @@ import { checkClaims, formatOutcome, loadEslint, parseConfig as parseClaimsConfi
 export const DENY_FILE = '.veda/deny.sha256';
 const USAGE = [
     'usage: pariksha authority-citations [--mode staged|tree] [--authority <a,b>] [--issue-prefix <A,B>] [--adr-dir <dir>] [--root <dir>]',
+    '       pariksha absolute-paths [--config <file>] [--files-from <file>|-] [--root <dir>]',
+    '       pariksha aggregate-gate-needs [--config <file>] [--root <dir>]',
     '       pariksha boundary [--root <dir>] [--deny <file>]',
     '       pariksha codec-registry --config <file> [--base <ref> | --no-base] [--root <dir>]',
     '       pariksha coverage-by-type [--config <file>] [--files-from <file>|-] [--root <dir>]',
@@ -35,6 +42,8 @@ const USAGE = [
     '       pariksha env-gate-switches --config <file> [--mode staged|tree] [--root <dir>]',
     '       pariksha export-deletions [--base <ref>] [--root <dir>]',
     '       pariksha fault-injection-registry --config <file> [--base <ref> | --no-base] [--root <dir>]',
+    '       pariksha non-synced-resources [--config <file>] [--files-from <file>|-] [--root <dir>]',
+    '       pariksha pnpm-settings [--config <file>] [--root <dir>]',
     '       pariksha required-settings --require <file> [--settings <file>] [--root <dir>]',
     '       pariksha hash <word>',
     '       pariksha --version',
@@ -81,6 +90,68 @@ export const flags = (rest, allowed, switches = []) => {
     }
     return out;
 };
+/**
+ * absolute-paths and non-synced-resources: the documents `--files-from`
+ * lists (a file, or `-` for stdin), or every tracked one, each path read
+ * from `--root`; the report goes to stdout, as the shell checks printed it.
+ */
+const docCheck = (name, defaultGuidance, check) => (f, io) => {
+    const P = `pariksha ${name}:`;
+    const base = resolve(f.get('--root') ?? '.');
+    try {
+        const configPath = f.get('--config');
+        const config = parseDocConfig(configPath === undefined ? undefined : readFileSync(resolve(base, configPath), 'utf8'), defaultGuidance);
+        const from = f.get('--files-from');
+        const listed = from === undefined ? undefined : from === '-' ? (io.stdin ?? (() => readFileSync(0, 'utf8')))() : readFileSync(resolve(from), 'utf8');
+        const docs = selectDocs(base, listed, config.include).map((file) => ({ file, text: () => readDoc(base, file) }));
+        const result = check(docs, base, config);
+        result.out.forEach(io.out);
+        return result.ok ? 0 : 1;
+    }
+    catch (e) {
+        io.err(`${P} ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+};
+const absolutePaths = docCheck('absolute-paths', ABSOLUTE_PATHS_GUIDANCE, (docs, _base, config) => checkAbsolutePaths(docs, config));
+const nonSyncedResources = docCheck('non-synced-resources', NON_SYNCED_GUIDANCE, (docs, base, config) => checkNonSyncedResources(docs, () => {
+    const top = topOf(base);
+    if (top === undefined)
+        throw new Error(`${base} is not in a git repository`);
+    return top;
+}, config));
+const aggregateGateNeeds = (f, io) => {
+    const root = resolve(f.get('--root') ?? '.');
+    const configPath = f.get('--config');
+    let config = DEFAULT_GATE_CONFIG;
+    try {
+        if (configPath !== undefined)
+            config = parseAggregateConfig(readFileSync(resolve(root, configPath), 'utf8'));
+    }
+    catch (e) {
+        io.err(`pariksha aggregate-gate-needs: ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+    const result = checkGates(root, config);
+    result.out.forEach(io.out);
+    result.err.forEach(io.err);
+    return result.ok ? 0 : 1;
+};
+const pnpmSettings = (f, io) => {
+    const root = resolve(f.get('--root') ?? '.');
+    const configPath = f.get('--config');
+    try {
+        const config = configPath === undefined ? DEFAULT_PNPM_CONFIG : parsePnpmConfig(readFileSync(resolve(root, configPath), 'utf8'));
+        const result = formatParity(checkPnpmSettings(root, config, (io.now ?? Date.now)()), config.id);
+        result.err.forEach(io.err);
+        result.out.forEach(io.out);
+        return result.ok ? 0 : 1;
+    }
+    catch (e) {
+        io.err(`pariksha pnpm-settings: ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+};
 const boundary = (f, io) => {
     const root = resolve(f.get('--root') ?? '.');
     const denyPath = resolve(root, f.get('--deny') ?? DENY_FILE);
@@ -553,6 +624,10 @@ const COMMANDS = {
     'codec-registry': { allowed: ['--config', '--base', '--root'], switches: ['--no-base'], run: codecRegistry },
     'coverage-exemptions': { allowed: ['--config', '--package', '--root'], run: coverageExemptions },
     'fault-injection-registry': { allowed: ['--config', '--base', '--root'], switches: ['--no-base'], run: faultInjectionRegistry },
+    'absolute-paths': { allowed: ['--config', '--files-from', '--root'], run: absolutePaths },
+    'aggregate-gate-needs': { allowed: ['--config', '--root'], run: aggregateGateNeeds },
+    'non-synced-resources': { allowed: ['--config', '--files-from', '--root'], run: nonSyncedResources },
+    'pnpm-settings': { allowed: ['--config', '--root'], run: pnpmSettings },
     '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 },

package/dist/doc-files.js

@@ -0,0 +1,74 @@
+// The documents absolute-paths and non-synced-resources read, and the config
+// both take. A product's hook hands them its own list (`--files-from`); with
+// none, they read every file git tracks.
+import { readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { entries } from "./coverage-by-type.js";
+import { gitAt, must } from "./git.js";
+/** Markdown and MDX. */
+export const DEFAULT_INCLUDE = '\\.(md|mdx)$';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * `{ "include"?: "<regex>", "guidance"?: ["<line>", …] }`; absent keys take
+ * the defaults. Throws on anything else, so a mistyped key never passes as
+ * the default.
+ */
+export const parseDocConfig = (text, defaultGuidance) => {
+    if (text === undefined)
+        return { include: new RegExp(DEFAULT_INCLUDE), guidance: defaultGuidance };
+    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) => k !== 'include' && k !== 'guidance');
+    if (unknown !== undefined)
+        throw new Error(`unknown key "${unknown}"`);
+    // Absent takes the default; a present `null` is refused like any other wrong value.
+    const include = 'include' in raw ? raw['include'] : DEFAULT_INCLUDE;
+    if (typeof include !== 'string' || include === '')
+        throw new Error('"include" must be a non-empty regex string');
+    let pattern;
+    try {
+        pattern = new RegExp(include);
+    }
+    catch (e) {
+        throw new Error(`"include" is not a regex: ${e.message}`);
+    }
+    const guidance = 'guidance' in raw ? raw['guidance'] : defaultGuidance;
+    if (!Array.isArray(guidance) || guidance.some((line) => typeof line !== 'string'))
+        throw new Error('"guidance" must be a list of lines');
+    return { include: pattern, guidance: guidance };
+};
+/** Whether `path` (under `base` when relative) names a regular file, a symlink to one included. */
+export const isFileAt = (base, path) => {
+    try {
+        return statSync(resolve(base, path)).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The documents to check, as listed: each entry of `listed` that names a
+ * regular file under `base` and matches `include`, in order; a named path
+ * that is not a file is dropped. With no list, every file git tracks under
+ * `base`, as git names it.
+ */
+export const selectDocs = (base, listed, include) => {
+    const paths = listed === undefined ? must(gitAt(base), ['ls-files', '-z']).split('\0').filter(Boolean) : entries(listed);
+    return paths.filter((path) => isFileAt(base, path) && include.test(path));
+};
+/** A document's lines as a shell `read` loop sees them: split on newlines, a last line without one included. */
+export const linesOf = (text) => {
+    const lines = text.split('\n');
+    if (lines.at(-1) === '')
+        lines.pop();
+    return lines;
+};
+/** A listed document's text. */
+export const readDoc = (base, path) => readFileSync(resolve(base, path), 'utf8');