@veda-hq/pariksha 0.5.13 → 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.13 <check> [flags]
-npx @veda-hq/pariksha@0.5.13 --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`
 
@@ -263,6 +336,137 @@ 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.
 
+## `doc-references`
+
+```sh
+pariksha doc-references --config <file> --staged [--checks <ids>] [--root <dir>]
+pariksha doc-references --config <file> --base <ref> [--head <ref>] [--checks <ids>] [--root <dir>]
+pariksha doc-references --config <file> --all [--update-baseline | --write-baseline] [--checks <ids>] [--root <dir>]
+```
+
+A doc that names a file, a script or a function the repository no longer
+has reads as true and sends its reader into a broken step. Three checks read
+the docs and code comments the config's `files` select:
+
+- `DOC-DRIFT-01`, paths and links. A path in backticks (in prose, a shell
+  fence, frontmatter or a code comment), a glob, or `file.ts:12` resolves
+  beside the doc, above it, at the root or from a workspace; a cited line
+  exists, and a backticked symbol beside it is near that line. Relative
+  Markdown links and their `#anchor`s are checked by
+  [lychee](https://lychee.cli.rs), offline, which must be on `PATH` (set
+  `links` to `null` to leave links out). A path the tracked `.gitignore`
+  rules cover is out of scope.
+- `DOC-DRIFT-02`, commands. A `pnpm <script>` exists in the scope it runs
+  from (a workspace script needs `--filter`; bins in `node_modules/.bin`
+  count everywhere), and a verification step does not run a script that
+  rewrites the tree (`mutating`). A command a doc shows runs as written:
+  `--filter` before the script name, every `--flag` read by the script it
+  reaches (through a package script or an interpreter), required argparse
+  flags present, enum values and first-positional actions the script
+  accepts, and, with `typescriptRunner` set, a `.ts` file started through it.
+- `DOC-DRIFT-04`, identifiers. A single-identifier code span in prose
+  (`DATABASE_URL`, `parseArgs()`, `OrderService`) occurs as a whole word in
+  the tracked code, or in the file the doc cites for it ("`x` in `y.ts`").
+  Optional kinds: Prisma `Model.field`, `@@unique([…])`, migration folders and
+  `@Roles(…)` values; routes (`GET /stores/:id`) against controller
+  decorators; CI jobs ("the `build` job"); packages against workspace names
+  and the lockfile.
+
+A line ending in `<!-- doc-ref-ok: <why> -->` (in code, a comment holding
+`doc-ref-ok: <why>`; the word is the config's `exemptMarker`) names
+something absent on purpose. Placeholders (`<id>`, `NNN`) and illustrative
+names (`src/foo.ts`) are never references.
+
+Modes. `--staged` (a commit) reads the index: staged docs and comments,
+and any doc naming a path the commit deletes or renames, under
+DOC-DRIFT-01 and -02. During a merge, what the merge took unchanged from the
+merged branch is that branch's to judge. `--base` (a push, CI) reads the
+`--head` tree (default `HEAD`) against its merge base with `--base`: changed
+docs, and docs naming a deleted or renamed path, a changed file by
+`name:line`, or an identifier, script or `--flag` the diff removed, under
+all three checks; a finding the merge base already had is not this push's.
+`--all` reads every reference file in the worktree; it alone may lower the
+baseline (`--update-baseline`) or seed it (`--write-baseline`). `--checks`
+takes a comma-separated subset (`01,02`).
+
+The baseline is a JSON file of per-file counts, `{ "version": 1, "files":
+{ "docs/old.md": { "DOC-DRIFT-01": 3 } } }`, for references that predate
+the check. A checked file may not exceed its count; a file a change touches
+must lower a count it no longer needs; the baseline may only lose entries or
+lower counts against the merge base; an entry for a file the change removed
+must go. The JSON `--config` (relative to the root):
+
+```json
+{
+  "baseline": "scripts/doc-references-baseline.json",
+  "exemptMarker": "doc-ref-ok",
+  "files": {
+    "markdown": ["\\.(md|mdx)$"],
+    "html": ["^(?:.*/)?docs/.*\\.html$"],
+    "code": ["\\.(ts|tsx|js|mjs|sh|py)$"],
+    "codeExclude": ["\\.(test|spec)\\.[jt]sx?$"],
+    "exclude": ["(^|/)node_modules/", "(^|/)fixtures?/", "^docs/history/"],
+    "hashComments": "\\.(sh|py)$"
+  },
+  "placeholder": "[<>${}%…]|\\.\\.\\.|NNN",
+  "paths": {
+    "extensions": ["ts", "js", "json", "md", "sh", "py", "yml", "yaml"],
+    "examples": { "pattern": "(^|/)(foo|bar|example)(\\.[\\w.]+)?$", "flags": "i" },
+    "untracked": [".claude/worktrees/"],
+    "workspaces": "^(apps|packages)/[^/]+/package\\.json$",
+    "layouts": [{ "pattern": "^evidence/[A-Z]-\\d{2}", "except": "^docs/work/" }]
+  },
+  "links": { "include": "\\.md$" },
+  "scripts": {
+    "manifests": ["package.json", "apps/api/package.json"],
+    "mutating": { "lint": "lint:ci", "format": "format:check" },
+    "verification": { "pattern": "verif|check|gate", "flags": "i" },
+    "wrappers": []
+  },
+  "commands": { "typescriptRunner": "pnpm exec tsx", "nested": ["vitest", "turbo", "git"] },
+  "identifiers": {
+    "notIdentifiers": ["GitHub", "TypeScript"],
+    "searchExclude": ["\\.(md|mdx|html)$", "^docs/", "^pnpm-lock\\.yaml$"],
+    "diffExclude": ["*.md", "docs/**"],
+    "prisma": { "schemas": "^apps/api/prisma/.*\\.prisma$", "migrations": "apps/api/prisma/migrations", "roles": { "schema": "apps/api/prisma/schema.prisma", "enum": "Role" } },
+    "routes": { "controllers": "^apps/api/src/.*\\.controller\\.ts$", "prefixes": "^(api|v\\d+)$" },
+    "jobs": { "workflows": "^\\.github/workflows/[^/]+\\.ya?ml$" },
+    "packages": { "manifests": "^(?!(?:.*/)?node_modules/)(?:.*/)?package\\.json$", "lockfile": "pnpm-lock.yaml", "ownScopes": ["@acme/"] }
+  }
+}
+```
+
+- `files`: what a tracked path is, first match winning after `exclude`:
+  Markdown (and Markdown-like XML), HTML pages, or code whose comments are
+  read (`codeExclude` drops tests and fixtures, which name absent paths on
+  purpose). `hashComments` is the code whose comments start with `#`.
+- `paths`: the extensions a backticked path may end in; `examples` and
+  `untracked` names that are never a tracked file; `workspaces`, the
+  manifests whose folders (and `src`) a path also resolves from;
+  `layouts`, paths that name a folder layout rather than a file outside the
+  docs `except` matches.
+- `scripts.wrappers`: repository scripts that run the rest of a line as a
+  command (`pnpm dev:exec pnpm x`). `commands.nested`: programs a wrapper
+  script hands its remaining words to, so they are not its own flags.
+- `identifiers.searchExclude`: tracked text that defines no name (prose,
+  data, sources that quote wrong names on purpose); binaries and the
+  baseline are never read. `diffExclude`: pathspecs the removed-identifier
+  diff leaves out.
+- `links`, `commands.typescriptRunner`, and each of `identifiers.prisma`
+  (and its `migrations` and `roles`), `routes`, `jobs`, `packages` (and its
+  `lockfile`) may be `null`, which leaves that part unchecked and says so on
+  stdout. Absent, each is refused.
+
+On a pass, stdout has one line, `pariksha doc-references: <n> reference
+file(s) checked (<staged|pushed|all>), no new problem; the baseline does not
+grow`. Each refusal is a stderr line, `pariksha doc-references:
+<file>:<line>: [<check>] <ref>: <reason>`, then what to do. Refused (exit 1):
+a reference over its file's count, a count a touched file no longer needs,
+baseline growth, and an entry for a removed file. Exit 2: a bad flag set or
+config (an unknown, missing or bad key or pattern), a malformed baseline, no
+`node_modules/.bin` (DOC-DRIFT-02 would know no bin), a missing or failing
+lychee, a `--base` with no merge base, or a failed git call.
+
 ## `enforcement-claims`
 
 ```sh
@@ -536,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 };
+};