@veda-hq/pariksha 0.5.14 → 0.5.18

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.18 <check> [flags]
+npx @veda-hq/pariksha@0.5.18 --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,131 @@ 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`.
 
+## `masked-exit-codes`
+
+```sh
+pariksha masked-exit-codes [--config <file>] [--staged] [--root <dir>]
+```
+
+A gate that keeps reporting success after it stopped checking passes
+everything: a hook that runs a commit-message linter and then `exit 0`, a
+review step whose failures read as "no issues found", a baseline read with
+`2>/dev/null || true`. `|| true` has honest uses (an optional tool, grep's
+"no matches"), so this refuses only the shapes that silence a gate command's
+verdict:
+
+1. `exit 0` at the end of a script that ran a gate, with no branch on the
+   gate's status;
+2. `|| true`, a `||` handler that does not exit non-zero, or `2>/dev/null`
+   with the status unchecked, on a gate command, also in a script the line
+   hands a shell (`eval '…'`, `bash -c '…'`, what `echo`/`printf` pipes
+   into `sh`) and inside `$( … )`;
+3. in a file `pipefailScope` matches, `echo`/`printf` of a variable piped
+   into a reader that stops early (`grep -q`, `-m`, `-l`, `head`): under
+   pipefail the writer can fail after the match, which reads as a miss.
+
+The files are those git tracks under the root ending `.sh` or under a hook
+directory, outside `node_modules/`, read from the working tree, or the index
+with `--staged`. Comments, quoted text, heredoc bodies and continuation lines
+are read as bash reads them. The JSON `--config` (relative to the root) is
+optional:
+
+```json
+{
+  "id": "SH-001",
+  "gateCommands": ["eslint", "tsc", "vitest", "prettier --check", "commitlint", "run-validation.sh"],
+  "hookDirs": [".husky/"],
+  "pipefailScope": ["^\\.husky/", "^scripts/lib/.+\\.sh$"]
+}
+```
+
+- `id` (default `masked-exit-codes`) names the check in its messages.
+- `gateCommands` (default `eslint`, `tsc`, `vitest`, `prettier --check`,
+  `commitlint`, `cubic review`, `gitleaks`, `actionlint`, `shellcheck`,
+  `depcruise`, `stryker`) are the commands whose status is a verdict; one of
+  several words must appear whole. Keep it narrow: a broad list fires on
+  every optional-tool probe.
+- `hookDirs` (default `.husky/`) are path prefixes whose files are shell
+  whatever their name.
+- `pipefailScope` (default `^\.husky/`) are path regexes: the files that run
+  under `set -o pipefail`.
+
+A clean run prints `✅ <id>: no masked exit codes (N shell file(s) scanned)`
+to stdout; each finding goes to stderr with its line and why, and exits 1.
+No shell file at all exits 1 (`the file lookup failed`), as the original
+did; a bad config or a failed git call exits 2.
+
+## `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
@@ -725,6 +923,93 @@ Parsing those is the job of a command guard such as kavach's `git_safety`.
 project's settings and then also skips the user's own `defaultMode`, so it
 belongs in user settings only.
 
+## `shell-gates`
+
+```sh
+pariksha shell-gates [--config <file>] [--staged | --all | --base <ref> | --files-from <file>|-] [--only <checks>] [--root <dir>]
+```
+
+A shell script that works on its writer's Mac can fail on Linux CI, and a
+git hook that picks up whatever `node` is on PATH can run a check under the
+wrong runtime. This runs three gates over the shell files a change writes:
+
+1. ShellCheck, a binary on PATH (install it: <https://www.shellcheck.net>),
+   once per pass, by default `--severity=warning`, then `--severity=info
+   --include=SC2086,SC2013,SC2015` (an unquoted expansion, `for x in $(cat
+   f)`, `a && b || c`). Its targets are `*.sh`, `*.bash`, the hooks
+   directory's direct children without an extension, and extensionless
+   files whose first line is a sh, bash, dash or ksh `#!`. Staged mode
+   writes the index's copy of each to a temporary directory and judges
+   that; base mode judges the HEAD commit's copy of what the branch changed
+   since its merge base with `<ref>`; `--all` judges the working tree; files
+   mode passes the listed paths as they are.
+2. The hook preamble, over the hooks directory's direct children without an
+   extension. A hook must source `selectScript` and call `selectFunction`
+   (with `|| exit 1`, or a branch that exits) before it runs a runtime
+   (`runtimes`, by default `node`, `npx`, `pnpm`, `npm`, `tsx`, `corepack`,
+   `yarn`), here or in a function it calls; an opt-out (`[ "$X" = 0 ] &&
+   exit 0`) comes before that selection; it never edits PATH or drives
+   nvm, fnm or mise itself; it never `exec sh <hook>`s (that ignores the
+   target's shebang); and an INT, TERM, HUP or QUIT trap's handler ends in
+   `exit`, or bash resumes after it and a cancelled hook carries on.
+3. The pitfalls, over every shell target: `grep -E` or `egrep` with `\s`,
+   `\S`, `\d` or `\D` (not POSIX ERE: BSD grep matches nothing); GNU-only
+   `xargs -d`/`-r`; `xargs` without `-0` fed a file list; file operands
+   after `xargs`, or a list expansion to grep, without `--`; `<( … )` in a
+   file `validatorPaths` matches; a literal `/tmp/<name>` (use `mktemp`);
+   an unguarded `/opt/homebrew` or `/Users/` literal, a fixed `-avd
+   <name>`, a personal device name; `NVM_DIR` set without honouring an
+   existing one; `lockf` without `-k`; `$(( … ))` over a value from `read`
+   or `date` without `10#` (`08` is bad octal); `dirname "$0"` beside
+   `BASH_SOURCE`; `git worktree list` parsed without `--porcelain`; and
+   `grep -o` over a JSON `"key":`. Comments, quoted text and heredoc bodies
+   are read as bash reads them.
+
+The preamble and pitfalls judge the same kind of target, less `exclude`
+and symlinks: `--staged` (the default) the staged copies, `--base` the
+files changed since the merge base with `<ref>` (read from the working
+tree), `--all` every tracked one, `--files-from` the listed paths (one per
+line or NUL-separated; a file, or `-` for stdin). A change under
+`gateInputs` (staged, or on the branch) re-judges every target, and a
+staged change to a `shellcheck.inputs` path makes ShellCheck judge the
+whole index. `--only preamble,pitfalls` runs
+only those checks, and no ShellCheck. The JSON `--config` (relative to the
+root) is optional:
+
+```json
+{
+  "hooksDir": ".husky/",
+  "exclude": ["node_modules/", ".husky/_/", "vendor/"],
+  "gateInputs": ["scripts/validations/shell/"],
+  "preamble": { "id": "SHELL-06", "selectScript": "scripts/lib/select-node.sh", "selectFunction": "select_node" },
+  "pitfalls": { "id": "SHELL-03", "validatorPaths": ["^scripts/validations/"] },
+  "shellcheck": { "inputs": ["scripts/run-validation.sh"], "install": "run the machine setup (or: brew install shellcheck)" },
+  "guidance": ["", "   SHELL-06 and SHELL-03 are described in docs/shell.md."]
+}
+```
+
+- `hooksDir` (default `.husky/`, ending in `/`) is the git hooks directory.
+- `exclude` (default `node_modules/`, `.husky/_/`) are path prefixes never
+  judged by the preamble and pitfalls; a `/node_modules/` segment never is.
+- `gateInputs` (default none) are path prefixes of the gate's own inputs.
+- `preamble` (default none, which leaves only the pitfalls to run):
+  `selectScript` and `selectFunction` are required; `id` defaults to
+  `hook-preamble`, `runtimes` to the list above.
+- `pitfalls`: `id` (default `shell-pitfalls`) and `validatorPaths` (path
+  regexes, default none).
+- `shellcheck`: `passes` (lists of flags after `--norc`; `[]` runs no
+  ShellCheck), `inputs` (default none) and `install`, the text a missing
+  ShellCheck message gives.
+- `guidance` (default a pointer to this section) is printed after the
+  findings.
+
+ShellCheck's own report comes first, then `✅ Shell gates: N file(s) pass
+<checks>`, or `❌ Shell gates: N finding(s) in M file(s)` on stderr with
+each finding as `file:line  <id> <rule>` and its message, then the
+guidance. It exits 1 on any ShellCheck or rule finding, or when ShellCheck
+is not installed; 2 on a bad config, two modes, an empty list, or a
+selection or git failure, since nothing was checked.
+
 ## markdownlint rules
 
 ```jsonc

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 };
+};