@veda-hq/pariksha 0.5.17 → 0.5.18

package/README.md

@@ -4,8 +4,8 @@
 test-quality ratchets. Part of [Veda](https://github.com/veda-hq/veda).
 
 ```sh
-npx @veda-hq/pariksha@0.5.17 <check> [flags]
-npx @veda-hq/pariksha@0.5.17 --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
@@ -740,6 +740,60 @@ 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
@@ -869,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/cli.js

@@ -7,11 +7,13 @@ 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 { DEFAULT_MASKED_CONFIG, findMaskedExits, formatMasked, parseMaskedConfig, readerFor as maskedReaderFor, shellFiles } from "./masked-exit-codes.js";
 import { checkNonSyncedResources, DEFAULT_GUIDANCE as NON_SYNCED_GUIDANCE } from "./non-synced-resources.js";
+import { ALL_CHECKS as SHELL_CHECKS, parseGatesConfig, runShellGates, shellcheckRunner } from "./shell-gates.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";
+import { DEFAULT_CONFIG, entries, findGaps, formatGaps, listedPaths, parseConfig, treePaths } from "./coverage-by-type.js";
 import { checkBuild, checkPackage, checkVitest, formatViolations, loaderFailure, loadVitestExclude, missingConfigs, ownedBy, parseConfig as parseExemptions } from "./coverage-exemptions.js";
 import { checkBudgets } from "./doc-budgets.js";
 import { lycheeRunner } from "./doc-links.js";
@@ -42,9 +44,11 @@ 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 masked-exit-codes [--config <file>] [--staged] [--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 shell-gates [--config <file>] [--staged | --all | --base <ref> | --files-from <file>|-] [--only <checks>] [--root <dir>]',
     '       pariksha hash <word>',
     '       pariksha --version',
 ].join('\n');
@@ -120,6 +124,76 @@ const nonSyncedResources = docCheck('non-synced-resources', NON_SYNCED_GUIDANCE,
         throw new Error(`${base} is not in a git repository`);
     return top;
 }, config));
+/** Standard input, or the file `from` names, read whole. */
+const listFrom = (from, io) => (from === '-' ? (io.stdin ?? (() => readFileSync(0, 'utf8')))() : readFileSync(resolve(from), 'utf8'));
+/**
+ * masked-exit-codes: the shell files git tracks under `--root`, read from
+ * the working tree, or the index with `--staged`. The report goes to stdout
+ * when clean and stderr when not, as the original printed it.
+ */
+const maskedExitCodes = (f, io) => {
+    const root = resolve(f.get('--root') ?? '.');
+    try {
+        const configPath = f.get('--config');
+        const config = configPath === undefined ? DEFAULT_MASKED_CONFIG : parseMaskedConfig(readFileSync(resolve(root, configPath), 'utf8'));
+        const files = shellFiles(root, config);
+        const problems = files.length === 0 ? [] : findMaskedExits(root, files, maskedReaderFor(f.has('--staged')), config);
+        const result = formatMasked(problems, files.length, config.id);
+        result.out.forEach(io.out);
+        result.err.forEach(io.err);
+        return result.ok ? 0 : 1;
+    }
+    catch (e) {
+        io.err(`pariksha masked-exit-codes: ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+};
+/**
+ * shell-gates: one of `--staged` (the default), `--all`, `--base <ref>` or
+ * `--files-from <file>|-`; `--only` names the checks to run, and then
+ * ShellCheck sits the run out, as the original did.
+ */
+const shellGates = (f, io) => {
+    const P = '❌ Shell gates could not run:';
+    const root = resolve(f.get('--root') ?? '.');
+    const modes = ['--staged', '--all', '--base', '--files-from'].filter((name) => f.has(name));
+    if (modes.length > 1) {
+        io.err(`${P} choose one of --staged, --all, --base, --files-from (got ${modes.join(', ')})`);
+        return 2;
+    }
+    let config;
+    let mode;
+    try {
+        const configPath = f.get('--config');
+        config = parseGatesConfig(configPath === undefined ? '{}' : readFileSync(resolve(root, configPath), 'utf8'));
+        const base = f.get('--base');
+        const from = f.get('--files-from');
+        if (from !== undefined) {
+            const files = entries(listFrom(from, io));
+            if (files.length === 0)
+                throw new Error('the --files-from list names no file, and a check of nothing is no pass');
+            mode = { kind: 'files', files };
+        }
+        else
+            mode = base !== undefined ? { kind: 'base', base } : f.has('--all') ? { kind: 'all' } : { kind: 'staged' };
+    }
+    catch (e) {
+        io.err(`${P} ${e.message}`);
+        return 2;
+    }
+    const only = f.get('--only');
+    let checks = SHELL_CHECKS.filter((name) => name !== 'preamble' || config.preamble !== undefined);
+    if (only !== undefined) {
+        const names = only.split(',').filter(Boolean);
+        const unknown = names.filter((name) => !SHELL_CHECKS.some((check) => check === name));
+        if (names.length === 0 || unknown.length > 0) {
+            io.err(`${P} --only takes ${SHELL_CHECKS.join(',')}; got ${names.join(',') || 'nothing'}`);
+            return 2;
+        }
+        checks = SHELL_CHECKS.filter((name) => names.includes(name));
+    }
+    return runShellGates({ root, mode, checks, only: only !== undefined }, config, { out: io.out, err: io.err, shellcheck: io.shellcheck ?? shellcheckRunner() });
+};
 const aggregateGateNeeds = (f, io) => {
     const root = resolve(f.get('--root') ?? '.');
     const configPath = f.get('--config');
@@ -636,7 +710,9 @@ const COMMANDS = {
     'enforcement-claims': { allowed: ['--config', '--root'], run: enforcementClaims },
     'env-gate-switches': { allowed: ['--config', '--mode', '--root'], run: envGateSwitches },
     'export-deletions': { allowed: ['--base', '--root'], run: exportDeletions },
+    'masked-exit-codes': { allowed: ['--config', '--root'], switches: ['--staged'], run: maskedExitCodes },
     'required-settings': { allowed: ['--require', '--settings', '--root'], run: requiredSettings },
+    'shell-gates': { allowed: ['--config', '--base', '--files-from', '--only', '--root'], switches: ['--staged', '--all'], run: shellGates },
 };
 /** The exit code; a Promise of it for the one check that is asynchronous (enforcement-claims, which loads ESLint). */
 export const run = (args, io, version = ownVersion(), env = process.env) => {

package/dist/hook-preamble.js

@@ -0,0 +1,343 @@
+// The git hook preamble contract: every hook follows one preamble, so the
+// runtime a hook uses is decided in one place (the config's `selectScript`,
+// which defines `selectFunction`) and a cancelled hook stays cancelled.
+//
+//   runtime-before-select-node  node/npx/pnpm/npm/tsx/corepack/yarn runs before
+//                               the hook sources the select script and calls
+//                               its function
+//   opt-out-after-select-node   an opt-out (`[ "$VAR" = 0 ] && exit 0`) comes
+//                               after runtime selection, so opting out still
+//                               pays for (and can fail on) selection
+//   own-runtime-path            the hook edits PATH or touches nvm/fnm/mise
+//                               itself; the select script owns that
+//   exec-sh-trampoline          `exec sh <hook>` ignores the target's bash
+//                               shebang
+//   signal-trap-continues       an INT/TERM/HUP/QUIT trap whose handler does
+//                               not end in `exit`: bash resumes after the
+//                               handler, so a cancelled gate carries on
+import { isHook } from "./shell-sources.js";
+import { codeLines, commandAt, commandPositions, maskQuoted, messageView, words } from "./shell-text.js";
+export const DEFAULT_RUNTIMES = ['node', 'npx', 'pnpm', 'npm', 'tsx', 'corepack', 'yarn'];
+const STOP_SIGNALS = new Set(['INT', 'TERM', 'HUP', 'QUIT', '1', '2', '3', '15']);
+const escapeRegex = (text) => text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+const finding = (config, source, rule, line, message) => ({ check: config.id, rule, file: source.path, line, message });
+/** Whether the first word of `rest` (a command's operands) matches `pattern`; no word, no match. */
+const firstWordMatches = (rest, pattern) => words(rest)
+    .slice(0, 1)
+    .some((word) => pattern.test(word));
+/**
+ * Quote-masked text after a command at this level only: each `( … )` or
+ * `$( … )` group becomes one space, so `&(:)&` stays two separate `&`, and
+ * the text is cut at a `)` that closes an enclosing group. Only this level's
+ * separators remain; offsets are not kept.
+ */
+const outerLevel = (masked) => {
+    let depth = 0;
+    const kept = [];
+    for (const char of masked) {
+        if (char === ')') {
+            if (depth === 0)
+                break;
+            depth -= 1;
+        }
+        else if (char === '(') {
+            if (depth === 0)
+                kept.push(' ');
+            depth += 1;
+        }
+        else if (depth === 0)
+            kept.push(char);
+    }
+    return kept.join('');
+};
+/**
+ * Whether the command at `start..end` runs in a child shell, so whatever it
+ * defines or selects is gone afterwards: a pipeline stage (`x | cmd`,
+ * `cmd | cat`, `|&` too) or a list sent to the background (`cmd &`).
+ */
+const runsInChildShell = (code, start, end) => {
+    if (/(?:^|[^|])\|&?\s*$/.test(code.slice(0, start)))
+        return true;
+    // The rest of its list (to `;` or a newline) and of its pipeline (to `&&`
+    // or `||` too, which bind looser than `|`), read at this level only: a `;`
+    // inside `"$(a; b)"` ends nothing.
+    const list = outerLevel(maskQuoted(code).slice(end)).split(/[;\n]/)[0];
+    if (/(?:^|[^&>])&(?![&>])/.test(list))
+        return true;
+    const pipeline = list.split(/&&|\|\|/)[0];
+    return /\|/.test(pipeline);
+};
+/**
+ * Offsets of each `.`/`source` command, where it runs (never in a message or
+ * quoted text), whose file operand is the select script.
+ */
+const selectSources = (code, script) => ['.', 'source'].flatMap((name) => commandPositions(code, name).filter((end) => firstWordMatches(code.slice(end), script) && !runsInChildShell(code, end - name.length, end)));
+/**
+ * `[ "$VAR" ... ] && exit 0` or `if [ ... ]; then exit 0`, on one line or
+ * several (`then` and `exit 0` on lines of their own), read over the logical
+ * lines joined with newlines.
+ */
+const OPT_OUT = /\$\{?[A-Z][A-Z0-9_]*\b[^\]\n]*\]\]?\s*(?:&&|(?:;|\n)\s*then)\s*exit\s+0\b/g;
+const PATH_EDIT = /(?:^|[\s;&|(])(?:export\s+)?PATH\+?=/;
+const NVM = /\bNVM_DIR\b|\bnvm\.sh\b/;
+const FNM_USE = /(?:^|[\s;&|("])fnm\s+(?:use|env)\b/;
+/** `mise activate`, `mise env`, `mise exec`/`x` or `mise shell`: each edits the runtime PATH. */
+const MISE_USE = /(?:^|[\s;&|("])mise\s+(?:activate|env|exec|x|shell)\b/;
+/** `. "$NVM_DIR/nvm.sh"`, `\. ~/.nvm/nvm.sh` or `source …nvm.sh`: the path is often quoted. */
+const sourcesNvm = (code) => ['.', '\\.', 'source'].some((name) => commandPositions(code, name).some((end) => firstWordMatches(code.slice(end), /nvm\.sh\b/)));
+/** The first position, in line then offset order, that `find` yields and `keep` accepts. */
+const firstAt = (lines, find, keep) => {
+    for (const [index, line] of lines.entries()) {
+        const kept = find(line.code).filter((offset) => keep({ index, offset }));
+        if (kept.length > 0)
+            return { index, offset: Math.min(...kept) };
+    }
+    return undefined;
+};
+const NAME = String.raw `[A-Za-z_][\w-]*`;
+/** `f() {`, `function f {` or `function f() {`, capturing the name and the rest. */
+const FUNCTION_HEADER = new RegExp(String.raw `^\s*(?:function\s+(${NAME})\s*(?:\(\s*\))?|(${NAME})\s*\(\s*\))\s*\{(.*)$`);
+/** `f()`, `function f` or `function f()` alone: the `{` opens the next line. */
+const BARE_HEADER = new RegExp(String.raw `^\s*(?:function\s+(${NAME})\s*(?:\(\s*\))?|(${NAME})\s*\(\s*\))\s*$`);
+/**
+ * Statements split at unquoted `;` and newlines only: `echo "a; exit 1"` is
+ * one statement, and `cleanup && exit 130` is one whose exit may not run.
+ */
+const splitStatements = (code) => {
+    const masked = maskQuoted(code);
+    const parts = [];
+    let from = 0;
+    for (let at = 0; at <= code.length; at += 1) {
+        if (at === code.length || masked[at] === ';' || masked[at] === '\n') {
+            parts.push(code.slice(from, at).trim());
+            from = at + 1;
+        }
+    }
+    return parts.filter(Boolean);
+};
+/** Unquoted code with `${…}` blanked, offsets preserved, for brace counting. */
+const braceView = (code) => maskQuoted(code).replace(/\$\{[^}]*\}/g, (match) => ' '.repeat(match.length));
+/** A function header at `index`: its name, the line holding its `{`, and the code after that `{`. */
+const headerAt = (lines, index) => {
+    const code = lines[index].code;
+    const match = FUNCTION_HEADER.exec(code);
+    if (match !== null)
+        return { name: (match[1] ?? match[2]), braceLine: index, rest: match[3] };
+    // `f()` alone, its `{` opening the next line, is a definition too.
+    const bare = BARE_HEADER.exec(code);
+    const next = lines.at(index + 1);
+    if (bare === null || next === undefined)
+        return undefined;
+    const brace = /^\s*\{(.*)$/.exec(next.code);
+    if (brace === null)
+        return undefined;
+    return { name: (bare[1] ?? bare[2]), braceLine: index + 1, rest: brace[1] };
+};
+/**
+ * Every function definition, from its header to the `}` that brings the
+ * brace depth back to zero, so a nested `{ …; }` group does not end it and
+ * code after the closing brace on that line stays top level.
+ */
+const functionDefinitions = (lines) => {
+    const out = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const start = index;
+        const header = headerAt(lines, index);
+        if (header === undefined)
+            continue;
+        const { name, braceLine, rest } = header;
+        index = braceLine;
+        // Where the body starts: just past the `{`, on the line holding it.
+        const bodyStart = lines[braceLine].code.length - rest.length;
+        let depth = 0;
+        let end;
+        for (; index < lines.length && end === undefined; index += 1) {
+            for (const [offset, char] of braceView(lines[index].code)
+                .split('')
+                .entries()) {
+                if (char === '{')
+                    depth += 1;
+                else if (char === '}' && --depth === 0) {
+                    end = { index, offset };
+                    break;
+                }
+            }
+        }
+        index -= 1; // back to the closing line; the outer loop steps past it
+        const close = end ?? { index, offset: lines[index].code.length };
+        const parts = [];
+        for (let line = braceLine; line <= close.index; line += 1)
+            parts.push(lines[line].code.slice(line === braceLine ? bodyStart : 0, line === close.index ? close.offset : undefined));
+        const body = parts.join(';');
+        out.push({ name, start, end: close, body, statements: splitStatements(body).filter((statement) => statement !== '}' && statement !== '{') });
+    }
+    return out;
+};
+/** Strictly earlier: by logical line, then by offset within it. */
+export const isBefore = (a, b) => a.index < b.index || (a.index === b.index && a.offset < b.offset);
+// A command ends before the `}` that closes its function: `node}` is one word.
+const insideFunction = (functions, at) => functions.some((fn) => at.index >= fn.start && isBefore(at, fn.end));
+/**
+ * Whether `at` runs in the hook's own shell: no unquoted `(` left open before
+ * it, across lines, and no open backtick substitution. Selection inside
+ * `( … )`, `$( … )` or `` `…` `` is lost when the subshell exits.
+ */
+const inHookShell = (lines, at) => {
+    let depth = 0;
+    let inBacktick = false;
+    const before = lines
+        .slice(0, at.index)
+        .map((line) => maskQuoted(line.code))
+        .concat(maskQuoted(lines[at.index].code).slice(0, at.offset));
+    for (const text of before) {
+        for (const char of text) {
+            if (char === '(')
+                depth += 1;
+            else if (char === ')')
+                depth = Math.max(0, depth - 1);
+            else if (char === '`')
+                inBacktick = !inBacktick;
+        }
+    }
+    return depth === 0 && !inBacktick;
+};
+/** `'x'` or `"x"` without its quotes; anything else as it is. */
+const unquote = (word) => /^(['"])([\s\S]*)\1$/.exec(word)?.[2] ?? word;
+/** Leading redirections (`2>&1`, `>/dev/null`) of a command's remainder. */
+const REDIRECTIONS = /^(?:\s*[0-9]*[<>]{1,2}&?\s*[^\s;&|]+)+/;
+/**
+ * `exit` or `exit N`, plus any redirections (`exit 130 >&2` still exits the
+ * hook); `exit 130 &` or `exit 130 | cat` exits a child shell instead.
+ */
+const EXIT = String.raw `exit(?:\s+[^\s&|;<>]+)?(?:\s*[0-9]*[<>]{1,2}&?\s*[^\s;&|<>]+)*`;
+const EXIT_STATEMENT = new RegExp(String.raw `^${EXIT}\s*$`);
+/** Whether the last statement of a handler string, or of a named function's body, exits. */
+const handlerEndsInExit = (handler, functions) => {
+    // `trap - SIG` restores the default (the hook dies); `trap '' SIG` ignores
+    // the signal, so a cancelled hook runs on.
+    if (handler === '-')
+        return true;
+    const body = unquote(handler).trim();
+    // A function name ends in exit when its body's last statement does.
+    // Otherwise split on `;` and newlines only: `cleanup && exit 130` is one
+    // statement whose exit is skipped when cleanup fails. An empty handler
+    // (`trap '' SIG`) has no last statement.
+    const last = /^[A-Za-z_][A-Za-z0-9_]*$/.test(body) ? functions.find((entry) => entry.name === body)?.statements.at(-1) : splitStatements(body).at(-1);
+    return last !== undefined && EXIT_STATEMENT.test(last);
+};
+const trapFindings = (config, source, lines, functions) => {
+    const out = [];
+    for (const entry of lines) {
+        // Every trap on the line: `trap 'exit 130' INT; trap '' TERM` has two.
+        for (const at of commandPositions(entry.code, 'trap')) {
+            let args = words(entry.code.slice(at));
+            // `trap -- handler SIG` ends options; `-p` and `-l` only list.
+            // `trap - SIG` restores the default, so it needs no check either.
+            if (args[0] === '--')
+                args = args.slice(1);
+            else if (args[0]?.startsWith('-'))
+                continue;
+            if (args.length < 2)
+                continue;
+            const [handler, ...signals] = args;
+            const stops = signals.some((signal) => STOP_SIGNALS.has(unquote(signal).toUpperCase().replace(/^SIG/, '')));
+            if (stops && !handlerEndsInExit(handler, functions)) {
+                out.push(finding(config, source, 'signal-trap-continues', entry.line, `trap ${handler} on ${signals.join(' ')} does not end in exit: bash resumes after the handler, so a cancelled hook keeps running`));
+            }
+        }
+    }
+    return out;
+};
+export const checkHookPreamble = (source, config) => {
+    if (!isHook(source.path, config.hooksDir))
+        return [];
+    const lines = codeLines(source.text);
+    const out = [];
+    const select = config.selectFunction;
+    // Absolute or repository-relative: hooks run from the repository root.
+    const script = new RegExp(String.raw `(?:^["']?|\/)${escapeRegex(config.selectScript)}\b`);
+    // A function body runs where the function is called, not where it is
+    // defined: selection inside one does not count as the preamble selecting,
+    // and a runtime inside one counts at each call of that function.
+    const functions = functionDefinitions(lines);
+    const outsideFunctions = (at) => !insideFunction(functions, at);
+    const runtimeOffsets = (code, names) => names.flatMap((name) => commandPositions(code, name));
+    // A function that runs a runtime, or calls a function that does, is a
+    // runner. A Set's iteration also visits what is added during it, so each
+    // new runner is in turn checked for callers, and each name once.
+    const runners = new Set(functions.filter((definition) => runtimeOffsets(definition.body, config.runtimes).length > 0).map((definition) => definition.name));
+    for (const runner of runners) {
+        for (const definition of functions)
+            if (runtimeOffsets(definition.body, [runner]).length > 0)
+                runners.add(definition.name);
+    }
+    // Selection must also run in the hook's own shell: inside `( … )` or
+    // `$( … )` its PATH change is gone once the subshell exits.
+    const topLevel = (at) => outsideFunctions(at) && inHookShell(lines, at);
+    const sourcedAt = firstAt(lines, (code) => selectSources(code, script), topLevel);
+    // And its failure must stop the hook: `<select> || exit 1`, or the
+    // condition of an `if`. A bare call, `|| true`, or a top-level `|| return`
+    // (which fails and carries on) runs on unselected.
+    const calledAt = firstAt(lines, (code) => commandPositions(code, select).filter((end) => {
+        const start = end - select.length;
+        // A pipeline stage runs in a subshell: `x | select`; so does a list
+        // sent to the background: `select || exit 1 &`.
+        if (runsInChildShell(code, start, end))
+            return false;
+        // Redirections may sit between the call and `||`: `2>&1 || exit 1`.
+        const rest = code.slice(end).replace(REDIRECTIONS, '');
+        return (
+        // `|| exit`, or a `|| { …; }` block whose last statement exits. The
+        // exit must end the list: `|| exit 1 | cat` exits a pipeline child.
+        new RegExp(String.raw `^\s*\|\|\s*${EXIT}\s*(?:$|;|&&)`).test(rest) ||
+            new RegExp(String.raw `^\s*\|\|\s*\{(?:[^}]*;)?\s*${EXIT}\s*;\s*\}\s*(?:$|;|&&)`).test(rest) ||
+            /(?:^|[\s;&])if\s+(?:!\s*)?$/.test(code.slice(0, start)));
+    }), topLevel);
+    const runtimeAt = firstAt(lines, (code) => runtimeOffsets(code, [...config.runtimes, ...runners]), outsideFunctions);
+    if (runtimeAt !== undefined) {
+        // Ordered by logical line, then by offset within it, so
+        // `. select.sh; select; node x` on one line is in order.
+        const selectedBefore = sourcedAt !== undefined && calledAt !== undefined && isBefore(sourcedAt, calledAt) && isBefore(calledAt, runtimeAt);
+        if (!selectedBefore) {
+            out.push(finding(config, source, 'runtime-before-select-node', lines[runtimeAt.index].line, `runs a Node tool before sourcing ${config.selectScript} and calling ${select}, so it uses whatever node PATH happens to hold`));
+        }
+    }
+    if (sourcedAt !== undefined) {
+        // Everything after the source, its own line's rest included:
+        // `. select.sh; [ "$X" ] && exit 0` opts out after selecting.
+        const sourceLine = lines[sourcedAt.index];
+        const after = [{ line: sourceLine.line, code: sourceLine.code.slice(sourcedAt.offset) }, ...lines.slice(sourcedAt.index + 1)];
+        // Messages blanked: `echo '[ "$X" ] && exit 0'` shows an opt-out.
+        const texts = after.map((entry) => `${messageView(entry.code)}\n`);
+        const joined = texts.join('');
+        const starts = texts.map((_, index) => texts.slice(0, index).join('').length);
+        const masked = maskQuoted(joined);
+        for (const match of joined.matchAll(OPT_OUT)) {
+            // The exit must run: in `HELP='[ "$X" ] && exit 0'` it is quoted text.
+            const exitAt = match.index + match[0].lastIndexOf('exit');
+            if (!masked.startsWith('exit', exitAt))
+                continue;
+            // Reported on the condition's line: the last starting at or before it.
+            const owner = starts.findLastIndex((start) => start <= match.index);
+            out.push(finding(config, source, 'opt-out-after-select-node', after[owner].line, 'opt-out comes after runtime selection; check it first so an opted-out hook does no work and cannot fail'));
+        }
+    }
+    for (const entry of lines) {
+        // Code text, not command positions, with quoted literals blanked: a
+        // message (echo/printf) is judged with its words blanked too, so
+        // `echo export PATH=...` and `HELP="export PATH=..."` name an edit
+        // without making one, while `eval "$(fnm env)"` keeps its substitution.
+        const view = messageView(entry.code);
+        const code = maskQuoted(view);
+        if (PATH_EDIT.test(code) || NVM.test(code) || sourcesNvm(view) || commandAt(entry.code, 'nvm') !== -1 || FNM_USE.test(code) || MISE_USE.test(code)) {
+            out.push(finding(config, source, 'own-runtime-path', entry.line, `hook edits PATH or drives nvm/fnm/mise itself; ${config.selectScript} owns runtime and tool PATH`));
+        }
+        // `exec` at a command position, never in a message; sh and dash only:
+        // `exec bash <hook>` names the dialect the hook needs.
+        const masked = maskQuoted(entry.code);
+        if (commandPositions(entry.code, 'exec').some((end) => /^\s+(?:\/usr\/bin\/env\s+)?(?:\/bin\/)?(?:da)?sh(?=\s|$)/.test(masked.slice(end)))) {
+            out.push(finding(config, source, 'exec-sh-trampoline', entry.line, '`exec sh <hook>` runs the target under sh whatever its shebang says; exec the hook itself'));
+        }
+    }
+    return [...out, ...trapFindings(config, source, lines, functions)].sort((a, b) => a.line - b.line);
+};