@bookedsolid/rea 0.10.1 → 0.10.3

package/dist/hooks/review-gate/diff.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Git-subprocess wrappers the review gate needs.
+ *
+ * ## Why a dedicated module
+ *
+ * The bash core spawns git via inline `$(cd "$REA_ROOT" && git ... 2>/dev/null)`
+ * subshells. Each invocation carries a handful of concerns the TS port
+ * separates cleanly:
+ *
+ *   - Args passed as an ARRAY so the shell never interprets them
+ *     (push-review-ts-port design §9 security posture: no argument-injection
+ *     CVEs around refspec names like `main;rm -rf /`).
+ *   - `cwd` always set to the resolved repo root — the caller never has to
+ *     remember to `cd` first.
+ *   - stdout/stderr captured separately. Git's error text goes to stderr in
+ *     normal modes, and callers often want stderr for diagnostics while
+ *     still deciding based on exit code.
+ *   - A single shared timeout (10s) catches a hung `git` process. The bash
+ *     core had no timeout — an upstream `git` stuck on NFS could wedge the
+ *     whole push indefinitely.
+ *
+ * ## Mockability
+ *
+ * Every exported function takes a `GitRunner` as its first positional so
+ * tests can stub the subprocess layer. The default runner spawns `git`;
+ * tests supply a recording runner and assert over the command history. This
+ * is how `base-resolve.test.ts` and `diff.test.ts` avoid needing a real
+ * git repo.
+ *
+ * ## Defect carry-forwards
+ *
+ * - Two-dot `A..B` for diff inputs, NEVER three-dot `A...B`. The bash
+ *   core's comment on push-review-core.sh §1053-1060 covers this: three-dot
+ *   computes an implicit merge-base which FAILS when A is the empty-tree
+ *   SHA (a valid bootstrap anchor in `base-resolve.ts`). Two-dot accepts
+ *   any revision on the left.
+ * - `git diff --name-status` output is tab-separated, one line per change;
+ *   `protected-paths.ts` owns the parse.
+ * - `git cat-file -e <sha>^{commit}` is the "object is locally resolvable"
+ *   probe. Bash used a bare exit-code check; we preserve that.
+ */
+/**
+ * Result of a git invocation. `status` is the git exit code (0 on success).
+ * Both `stdout` and `stderr` are trimmed of trailing newlines — the bash
+ * core's callers all applied `$(...)` which already collapses trailing
+ * whitespace, so TS callers expect the same contract.
+ */
+export interface GitRunResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Signature the git-subprocess layer must implement. Tests supply a stub
+ * that records calls and returns canned results; production uses
+ * {@link spawnGit}.
+ */
+export type GitRunner = (args: readonly string[], cwd: string) => GitRunResult;
+/**
+ * Default production git runner. Spawns `git` with the supplied args, cwd,
+ * and a fixed timeout. `encoding: 'utf8'` so the returned strings are
+ * decoded, matching the bash `$()` shape.
+ *
+ * Security: args is always an array; no shell string ever participates in
+ * the invocation. Refspec names that happen to contain shell metacharacters
+ * are inert.
+ */
+export declare function spawnGit(args: readonly string[], cwd: string): GitRunResult;
+/**
+ * Return the current branch name (empty string when detached or on failure).
+ * Bash-core parity (push-review-core.sh §687): `git branch --show-current`.
+ */
+export declare function currentBranch(runner: GitRunner, cwd: string): string;
+/**
+ * Resolve `HEAD` to a commit SHA, or return the empty string when the repo
+ * has no commits / the rev-parse fails. Bash-core parity
+ * (push-review-core.sh §134 and §412): `git rev-parse HEAD`.
+ */
+export declare function resolveHead(runner: GitRunner, cwd: string): string;
+/**
+ * Resolve a ref (e.g. `feature/foo`) to a commit SHA via
+ * `git rev-parse --verify <ref>^{commit}`, or return null on failure.
+ * Bash-core parity (push-review-core.sh §187): the `^{commit}` suffix
+ * forces resolution to the commit even for annotated-tag refs.
+ */
+export declare function resolveRefToSha(runner: GitRunner, cwd: string, ref: string): string | null;
+/**
+ * Return the short-name upstream for the current branch (e.g. `origin/main`)
+ * or null if no upstream is set. Bash-core parity (push-review-core.sh §129
+ * and §601): `git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}'`.
+ */
+export declare function resolveUpstream(runner: GitRunner, cwd: string): string | null;
+/**
+ * Check whether a commit object is locally resolvable. Bash-core parity
+ * (push-review-core.sh §743): `git cat-file -e <sha>^{commit}`. Returns
+ * true on exit 0, false otherwise. Used before merge-base computation on
+ * the non-new-branch path — if the remote ref isn't fetched, `git merge-
+ * base` would silently return an unrelated base and the gate would diff
+ * against the wrong anchor.
+ */
+export declare function hasCommitLocally(runner: GitRunner, cwd: string, sha: string): boolean;
+/**
+ * Compute the merge-base between two refs. Returns the SHA on success,
+ * null on failure or empty output. Bash-core parity
+ * (push-review-core.sh §756 and §860): `git merge-base <a> <b>`.
+ */
+export declare function mergeBase(runner: GitRunner, cwd: string, a: string, b: string): string | null;
+/**
+ * True iff `ref` is a resolvable rev (commit, tag, or branch). Bash-core
+ * parity (push-review-core.sh §815 and §835): `git rev-parse --verify
+ * --quiet <ref>` with stdout suppressed and stderr ignored.
+ */
+export declare function refExists(runner: GitRunner, cwd: string, ref: string): boolean;
+/**
+ * Read a git config value (e.g. `branch.<name>.base`). Returns the value
+ * or the empty string when the config entry is absent or `git config` fails.
+ * Bash-core parity (push-review-core.sh §808): `git config --get <key>`.
+ */
+export declare function readGitConfig(runner: GitRunner, cwd: string, key: string): string;
+/**
+ * Resolve `refs/remotes/<remote>/HEAD` to its symbolic target (e.g.
+ * `refs/remotes/origin/main`). Returns null on failure. Bash-core parity
+ * (push-review-core.sh §826): `git symbolic-ref refs/remotes/<remote>/HEAD`.
+ */
+export declare function resolveRemoteDefaultRef(runner: GitRunner, cwd: string, remote: string): string | null;
+/**
+ * Full `git diff <a>..<b>` output (two-dot per the §1053-1060 rationale).
+ * Returns the diff body on success; throws via the typed error if git
+ * exits non-zero so the caller can translate to the banner + exit 2.
+ *
+ * Empty diff → empty string, status 0 is a legitimate no-op push and the
+ * caller routes to its "no reviewable diff" branch.
+ */
+export interface DiffResult {
+    /** The full `git diff` output (may be empty). */
+    diff: string;
+    /** git's exit code. */
+    status: number;
+    /** git's stderr for error-path diagnostics. */
+    stderr: string;
+}
+export declare function fullDiff(runner: GitRunner, cwd: string, a: string, b: string): DiffResult;
+/**
+ * `git diff --name-status <a>..<b>` output. One line per change, tab-
+ * separated `<STATUS>\t<path1>[\t<path2>]`. Consumed by
+ * `protected-paths.ts`. Returns stdout on success or null on error (the
+ * caller emits a banner + exit 2; see bash core §904-914).
+ */
+export interface NameStatusResult {
+    /** Raw name-status output (may be empty on a zero-change diff). */
+    output: string;
+    /** git's exit code. */
+    status: number;
+    /** git's stderr for error-path diagnostics. */
+    stderr: string;
+}
+export declare function diffNameStatus(runner: GitRunner, cwd: string, a: string, b: string): NameStatusResult;
+/**
+ * Commit count between two refs. Bash-core parity
+ * (push-review-core.sh §996): `git rev-list --count <a>..<b>`. Returns -1
+ * on error so callers can distinguish "git failed" (exit 2) from "zero
+ * commits" (legitimate, usually a same-ref push).
+ */
+export declare function revListCount(runner: GitRunner, cwd: string, a: string, b: string): number;
+/**
+ * Resolve the repository's common-dir (the path to `.git` or to a
+ * shared worktree parent). Returns the absolute path or null when not in
+ * a git repo. Bash-core parity (push-review-core.sh §272-273):
+ * `git rev-parse --path-format=absolute --git-common-dir`.
+ *
+ * Used by the cross-repo guard in §1a to distinguish two checkouts of the
+ * same repo (linked worktrees share a common-dir) from two unrelated
+ * repos. Phase 2a ships the primitive; composition happens in Phase 2b.
+ */
+export declare function gitCommonDir(runner: GitRunner, cwd: string): string | null;
+/**
+ * Read git's user email + name fallback for skip-audit actor attribution.
+ * Bash-core parity (push-review-core.sh §393-396 and §563-566): prefer
+ * email; fall back to name if email is empty; empty string if both missing.
+ */
+export declare function readGitActor(runner: GitRunner, cwd: string): string;

package/dist/hooks/review-gate/diff.js

@@ -0,0 +1,232 @@
+/**
+ * Git-subprocess wrappers the review gate needs.
+ *
+ * ## Why a dedicated module
+ *
+ * The bash core spawns git via inline `$(cd "$REA_ROOT" && git ... 2>/dev/null)`
+ * subshells. Each invocation carries a handful of concerns the TS port
+ * separates cleanly:
+ *
+ *   - Args passed as an ARRAY so the shell never interprets them
+ *     (push-review-ts-port design §9 security posture: no argument-injection
+ *     CVEs around refspec names like `main;rm -rf /`).
+ *   - `cwd` always set to the resolved repo root — the caller never has to
+ *     remember to `cd` first.
+ *   - stdout/stderr captured separately. Git's error text goes to stderr in
+ *     normal modes, and callers often want stderr for diagnostics while
+ *     still deciding based on exit code.
+ *   - A single shared timeout (10s) catches a hung `git` process. The bash
+ *     core had no timeout — an upstream `git` stuck on NFS could wedge the
+ *     whole push indefinitely.
+ *
+ * ## Mockability
+ *
+ * Every exported function takes a `GitRunner` as its first positional so
+ * tests can stub the subprocess layer. The default runner spawns `git`;
+ * tests supply a recording runner and assert over the command history. This
+ * is how `base-resolve.test.ts` and `diff.test.ts` avoid needing a real
+ * git repo.
+ *
+ * ## Defect carry-forwards
+ *
+ * - Two-dot `A..B` for diff inputs, NEVER three-dot `A...B`. The bash
+ *   core's comment on push-review-core.sh §1053-1060 covers this: three-dot
+ *   computes an implicit merge-base which FAILS when A is the empty-tree
+ *   SHA (a valid bootstrap anchor in `base-resolve.ts`). Two-dot accepts
+ *   any revision on the left.
+ * - `git diff --name-status` output is tab-separated, one line per change;
+ *   `protected-paths.ts` owns the parse.
+ * - `git cat-file -e <sha>^{commit}` is the "object is locally resolvable"
+ *   probe. Bash used a bare exit-code check; we preserve that.
+ */
+import { spawnSync } from 'node:child_process';
+/** Hard cap on git invocation runtime. Bash core had no cap; 10s is generous for a hot-cache repo. */
+const GIT_TIMEOUT_MS = 10_000;
+/**
+ * Default production git runner. Spawns `git` with the supplied args, cwd,
+ * and a fixed timeout. `encoding: 'utf8'` so the returned strings are
+ * decoded, matching the bash `$()` shape.
+ *
+ * Security: args is always an array; no shell string ever participates in
+ * the invocation. Refspec names that happen to contain shell metacharacters
+ * are inert.
+ */
+export function spawnGit(args, cwd) {
+    const opts = {
+        cwd,
+        encoding: 'utf8',
+        timeout: GIT_TIMEOUT_MS,
+        // Explicitly drop stdin — some git subcommands try to read (e.g. `git
+        // commit` prompting for a message); we never want that.
+        stdio: ['ignore', 'pipe', 'pipe'],
+        // Never use a shell. Args are an array; spawn does argv[0] execve
+        // directly, so `git` is looked up on PATH with no shell parsing.
+        shell: false,
+    };
+    const result = spawnSync('git', args, opts);
+    const stdout = typeof result.stdout === 'string' ? result.stdout.replace(/\n+$/, '') : '';
+    const stderr = typeof result.stderr === 'string' ? result.stderr.replace(/\n+$/, '') : '';
+    // On timeout/signal kill, spawnSync returns status=null and populates
+    // `signal`. Treat as a non-zero exit so callers fall through the normal
+    // error paths.
+    const status = typeof result.status === 'number' ? result.status : 1;
+    return { status, stdout, stderr };
+}
+/**
+ * SHA validator. Bash uses `=~ ^[0-9a-f]{40}$`; we match exactly.
+ */
+const SHA_HEX_40 = /^[0-9a-f]{40}$/;
+/**
+ * Return the current branch name (empty string when detached or on failure).
+ * Bash-core parity (push-review-core.sh §687): `git branch --show-current`.
+ */
+export function currentBranch(runner, cwd) {
+    const r = runner(['branch', '--show-current'], cwd);
+    if (r.status !== 0)
+        return '';
+    return r.stdout;
+}
+/**
+ * Resolve `HEAD` to a commit SHA, or return the empty string when the repo
+ * has no commits / the rev-parse fails. Bash-core parity
+ * (push-review-core.sh §134 and §412): `git rev-parse HEAD`.
+ */
+export function resolveHead(runner, cwd) {
+    const r = runner(['rev-parse', 'HEAD'], cwd);
+    if (r.status !== 0)
+        return '';
+    const sha = r.stdout;
+    return SHA_HEX_40.test(sha) ? sha : '';
+}
+/**
+ * Resolve a ref (e.g. `feature/foo`) to a commit SHA via
+ * `git rev-parse --verify <ref>^{commit}`, or return null on failure.
+ * Bash-core parity (push-review-core.sh §187): the `^{commit}` suffix
+ * forces resolution to the commit even for annotated-tag refs.
+ */
+export function resolveRefToSha(runner, cwd, ref) {
+    const r = runner(['rev-parse', '--verify', `${ref}^{commit}`], cwd);
+    if (r.status !== 0)
+        return null;
+    const sha = r.stdout;
+    return SHA_HEX_40.test(sha) ? sha : null;
+}
+/**
+ * Return the short-name upstream for the current branch (e.g. `origin/main`)
+ * or null if no upstream is set. Bash-core parity (push-review-core.sh §129
+ * and §601): `git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}'`.
+ */
+export function resolveUpstream(runner, cwd) {
+    const r = runner(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'], cwd);
+    if (r.status !== 0)
+        return null;
+    const out = r.stdout;
+    return out.length > 0 ? out : null;
+}
+/**
+ * Check whether a commit object is locally resolvable. Bash-core parity
+ * (push-review-core.sh §743): `git cat-file -e <sha>^{commit}`. Returns
+ * true on exit 0, false otherwise. Used before merge-base computation on
+ * the non-new-branch path — if the remote ref isn't fetched, `git merge-
+ * base` would silently return an unrelated base and the gate would diff
+ * against the wrong anchor.
+ */
+export function hasCommitLocally(runner, cwd, sha) {
+    if (!SHA_HEX_40.test(sha))
+        return false;
+    const r = runner(['cat-file', '-e', `${sha}^{commit}`], cwd);
+    return r.status === 0;
+}
+/**
+ * Compute the merge-base between two refs. Returns the SHA on success,
+ * null on failure or empty output. Bash-core parity
+ * (push-review-core.sh §756 and §860): `git merge-base <a> <b>`.
+ */
+export function mergeBase(runner, cwd, a, b) {
+    const r = runner(['merge-base', a, b], cwd);
+    if (r.status !== 0)
+        return null;
+    const sha = r.stdout;
+    return SHA_HEX_40.test(sha) ? sha : null;
+}
+/**
+ * True iff `ref` is a resolvable rev (commit, tag, or branch). Bash-core
+ * parity (push-review-core.sh §815 and §835): `git rev-parse --verify
+ * --quiet <ref>` with stdout suppressed and stderr ignored.
+ */
+export function refExists(runner, cwd, ref) {
+    const r = runner(['rev-parse', '--verify', '--quiet', ref], cwd);
+    return r.status === 0;
+}
+/**
+ * Read a git config value (e.g. `branch.<name>.base`). Returns the value
+ * or the empty string when the config entry is absent or `git config` fails.
+ * Bash-core parity (push-review-core.sh §808): `git config --get <key>`.
+ */
+export function readGitConfig(runner, cwd, key) {
+    const r = runner(['config', '--get', key], cwd);
+    if (r.status !== 0)
+        return '';
+    return r.stdout;
+}
+/**
+ * Resolve `refs/remotes/<remote>/HEAD` to its symbolic target (e.g.
+ * `refs/remotes/origin/main`). Returns null on failure. Bash-core parity
+ * (push-review-core.sh §826): `git symbolic-ref refs/remotes/<remote>/HEAD`.
+ */
+export function resolveRemoteDefaultRef(runner, cwd, remote) {
+    const r = runner(['symbolic-ref', `refs/remotes/${remote}/HEAD`], cwd);
+    if (r.status !== 0)
+        return null;
+    const out = r.stdout;
+    return out.length > 0 ? out : null;
+}
+export function fullDiff(runner, cwd, a, b) {
+    const r = runner(['diff', `${a}..${b}`], cwd);
+    return { diff: r.stdout, status: r.status, stderr: r.stderr };
+}
+export function diffNameStatus(runner, cwd, a, b) {
+    const r = runner(['diff', '--name-status', `${a}..${b}`], cwd);
+    return { output: r.stdout, status: r.status, stderr: r.stderr };
+}
+/**
+ * Commit count between two refs. Bash-core parity
+ * (push-review-core.sh §996): `git rev-list --count <a>..<b>`. Returns -1
+ * on error so callers can distinguish "git failed" (exit 2) from "zero
+ * commits" (legitimate, usually a same-ref push).
+ */
+export function revListCount(runner, cwd, a, b) {
+    const r = runner(['rev-list', '--count', `${a}..${b}`], cwd);
+    if (r.status !== 0)
+        return -1;
+    const n = Number.parseInt(r.stdout, 10);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+/**
+ * Resolve the repository's common-dir (the path to `.git` or to a
+ * shared worktree parent). Returns the absolute path or null when not in
+ * a git repo. Bash-core parity (push-review-core.sh §272-273):
+ * `git rev-parse --path-format=absolute --git-common-dir`.
+ *
+ * Used by the cross-repo guard in §1a to distinguish two checkouts of the
+ * same repo (linked worktrees share a common-dir) from two unrelated
+ * repos. Phase 2a ships the primitive; composition happens in Phase 2b.
+ */
+export function gitCommonDir(runner, cwd) {
+    const r = runner(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);
+    if (r.status !== 0)
+        return null;
+    const out = r.stdout;
+    return out.length > 0 ? out : null;
+}
+/**
+ * Read git's user email + name fallback for skip-audit actor attribution.
+ * Bash-core parity (push-review-core.sh §393-396 and §563-566): prefer
+ * email; fall back to name if email is empty; empty string if both missing.
+ */
+export function readGitActor(runner, cwd) {
+    const email = readGitConfig(runner, cwd, 'user.email');
+    if (email.length > 0)
+        return email;
+    return readGitConfig(runner, cwd, 'user.name');
+}

package/dist/hooks/review-gate/errors.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Typed error set for the review-gate modules (G — push-review/commit-review
+ * TypeScript port).
+ *
+ * The bash core signals outcomes via exit codes + stderr banners. The TS port
+ * expresses each outcome as a typed error so callers can branch on class
+ * instead of parsing banner text, and so the eventual CLI entry point can
+ * translate a thrown error into the same exit code + banner the bash core
+ * emitted (preserving external contract per design §2, non-goals).
+ *
+ * Every error subclass carries:
+ *   - a stable `code` (for programmatic dispatch in tests + the CLI shim)
+ *   - an `exitCode` (matches the bash core's `exit N` semantics)
+ *   - the operator-facing `message` composed by `banner.ts`
+ *
+ * This module is intentionally dependency-free so unit tests can import it
+ * without dragging in fs/child_process. The CLI entry point is the single
+ * place that translates these to `process.exit(N)`.
+ */
+/**
+ * Stable discriminator used by tests and the CLI dispatch layer. String literals
+ * (not enum) so they survive JSON serialization in audit metadata.
+ */
+export type ReviewGateErrorCode = 'PUSH_BLOCKED_DELETE' | 'PUSH_BLOCKED_HEAD_REFSPEC' | 'PUSH_BLOCKED_SOURCE_UNRESOLVABLE' | 'PUSH_BLOCKED_NO_REFSPECS' | 'PUSH_BLOCKED_REMOTE_OBJECT_MISSING' | 'PUSH_BLOCKED_NO_MERGE_BASE' | 'PUSH_BLOCKED_NO_BASE_RESOLVABLE' | 'PUSH_BLOCKED_DIFF_FAILED' | 'PUSH_BLOCKED_REV_LIST_FAILED' | 'PUSH_BLOCKED_PROTECTED_PATHS' | 'PUSH_BLOCKED_SKIP_REFUSED_IN_CI' | 'PUSH_BLOCKED_SKIP_NO_ACTOR' | 'PUSH_BLOCKED_SKIP_AUDIT_FAILED' | 'PUSH_BLOCKED_SKIP_NOT_BUILT' | 'PUSH_BLOCKED_SKIP_METADATA_FAILED' | 'PUSH_BLOCKED_CACHE_MKTEMP_UNAVAILABLE' | 'PUSH_BLOCKED_NOT_IN_REPO' | 'PUSH_BLOCKED_DEPENDENCY_MISSING' | 'PUSH_REVIEW_REQUIRED';
+/**
+ * Base class. All review-gate errors derive from this so a CLI dispatch layer
+ * can `catch (e) { if (e instanceof ReviewGateError) ... }`.
+ */
+export declare class ReviewGateError extends Error {
+    readonly code: ReviewGateErrorCode;
+    readonly exitCode: number;
+    readonly details: Record<string, unknown>;
+    constructor(code: ReviewGateErrorCode, message: string, exitCode: number, details?: Record<string, unknown>);
+}
+/**
+ * Blocked-push errors (exit 2). The bash core uses exit 2 for every blocked
+ * condition; we preserve that invariant so the shim's exit code is unchanged.
+ */
+export declare class BlockedError extends ReviewGateError {
+    constructor(code: ReviewGateErrorCode, message: string, details?: Record<string, unknown>);
+}
+/**
+ * Deletion detected anywhere in the push (defect J). Must fail-closed even
+ * when a sibling refspec would have been reviewable.
+ */
+export declare class DeletionBlockedError extends BlockedError {
+    constructor();
+}
+/**
+ * A refspec with `HEAD` as destination is operator error (design §3.1,
+ * `pr_resolve_argv_refspecs`). Carry the refspec in details for banner render.
+ */
+export declare class HeadRefspecBlockedError extends BlockedError {
+    constructor(spec: string);
+}
+/**
+ * Invalid `--delete` refspec (empty destination or HEAD destination).
+ * Distinct from the general HEAD-refspec error because bash emits a
+ * different operator banner for the delete-mode case — the remediation
+ * text is "name the branch you meant to delete" rather than the HEAD
+ * destination error. See push-review-core.sh §161-168.
+ */
+export declare class InvalidDeleteRefspecError extends BlockedError {
+    constructor(spec: string);
+}
+/**
+ * Defect N completion (landed in phase 4, type reserved in phase 1 so
+ * `base-resolve.ts` can throw it later without schema churn).
+ */
+export declare class NoBaseResolvableError extends BlockedError {
+    constructor(source: string);
+}

package/dist/hooks/review-gate/errors.js

@@ -0,0 +1,100 @@
+/**
+ * Typed error set for the review-gate modules (G — push-review/commit-review
+ * TypeScript port).
+ *
+ * The bash core signals outcomes via exit codes + stderr banners. The TS port
+ * expresses each outcome as a typed error so callers can branch on class
+ * instead of parsing banner text, and so the eventual CLI entry point can
+ * translate a thrown error into the same exit code + banner the bash core
+ * emitted (preserving external contract per design §2, non-goals).
+ *
+ * Every error subclass carries:
+ *   - a stable `code` (for programmatic dispatch in tests + the CLI shim)
+ *   - an `exitCode` (matches the bash core's `exit N` semantics)
+ *   - the operator-facing `message` composed by `banner.ts`
+ *
+ * This module is intentionally dependency-free so unit tests can import it
+ * without dragging in fs/child_process. The CLI entry point is the single
+ * place that translates these to `process.exit(N)`.
+ */
+/**
+ * Base class. All review-gate errors derive from this so a CLI dispatch layer
+ * can `catch (e) { if (e instanceof ReviewGateError) ... }`.
+ */
+export class ReviewGateError extends Error {
+    code;
+    exitCode;
+    details;
+    constructor(code, message, exitCode, details = {}) {
+        super(message);
+        this.name = 'ReviewGateError';
+        this.code = code;
+        this.exitCode = exitCode;
+        this.details = details;
+        // Node gives us a stable prototype chain via Error; no need to hack it.
+    }
+}
+/**
+ * Blocked-push errors (exit 2). The bash core uses exit 2 for every blocked
+ * condition; we preserve that invariant so the shim's exit code is unchanged.
+ */
+export class BlockedError extends ReviewGateError {
+    constructor(code, message, details = {}) {
+        super(code, message, 2, details);
+        this.name = 'BlockedError';
+    }
+}
+/**
+ * Deletion detected anywhere in the push (defect J). Must fail-closed even
+ * when a sibling refspec would have been reviewable.
+ */
+export class DeletionBlockedError extends BlockedError {
+    constructor() {
+        super('PUSH_BLOCKED_DELETE', 'refspec is a branch deletion.\n' +
+            '\n' +
+            '  Branch deletions are sensitive operations and require explicit\n' +
+            '  human action outside the agent. Perform the deletion manually.\n');
+        this.name = 'DeletionBlockedError';
+    }
+}
+/**
+ * A refspec with `HEAD` as destination is operator error (design §3.1,
+ * `pr_resolve_argv_refspecs`). Carry the refspec in details for banner render.
+ */
+export class HeadRefspecBlockedError extends BlockedError {
+    constructor(spec) {
+        super('PUSH_BLOCKED_HEAD_REFSPEC', `refspec resolves to HEAD (from ${JSON.stringify(spec)})\n` +
+            '\n' +
+            '  `git push <remote> HEAD:<branch>` or similar is almost always\n' +
+            '  operator error in this context. Name the destination branch\n' +
+            '  explicitly so the review gate can diff against it.\n', { spec });
+        this.name = 'HeadRefspecBlockedError';
+    }
+}
+/**
+ * Invalid `--delete` refspec (empty destination or HEAD destination).
+ * Distinct from the general HEAD-refspec error because bash emits a
+ * different operator banner for the delete-mode case — the remediation
+ * text is "name the branch you meant to delete" rather than the HEAD
+ * destination error. See push-review-core.sh §161-168.
+ */
+export class InvalidDeleteRefspecError extends BlockedError {
+    constructor(spec) {
+        super('PUSH_BLOCKED_HEAD_REFSPEC', `--delete refspec resolves to HEAD or empty (from ${JSON.stringify(spec)})\n`, { spec, mode: 'delete' });
+        this.name = 'InvalidDeleteRefspecError';
+    }
+}
+/**
+ * Defect N completion (landed in phase 4, type reserved in phase 1 so
+ * `base-resolve.ts` can throw it later without schema churn).
+ */
+export class NoBaseResolvableError extends BlockedError {
+    constructor(source) {
+        super('PUSH_BLOCKED_NO_BASE_RESOLVABLE', `cannot resolve base branch for ${source}; run ` +
+            '`git branch --set-upstream-to=origin/<target>` or ' +
+            '`git config branch.' +
+            source +
+            '.base <ref>`', { source });
+        this.name = 'NoBaseResolvableError';
+    }
+}

package/dist/hooks/review-gate/hash.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Portable SHA-256 over arbitrary strings. Replaces the bash core's
+ * sha256sum → shasum → openssl fallback chain (defect L) with a single
+ * Node-stdlib call, removing the Alpine/distroless "no hasher on PATH"
+ * regression class entirely.
+ *
+ * ## Why a dedicated module
+ *
+ * The cache-key contract (design §8) requires byte-exact parity with the
+ * 0.10.1 bash implementation. The bash implementation computes
+ * `sha256sum( <full git diff> )` and uses the hex digest as the cache key.
+ * `crypto.createHash('sha256').update(s).digest('hex')` is bit-identical to
+ * GNU `sha256sum < <(printf '%s' s)` output (neither includes the
+ * filename-suffix padding). Regression-tested against the fixture in
+ * `__fixtures__/cache-keys.json`.
+ *
+ * ## Hex-64 validation
+ *
+ * The bash core validates the hasher output is `^[0-9a-f]{64}$` before using
+ * it as a cache key; a partial read or broken pipe would otherwise cache
+ * garbage. Node's `createHash` is synchronous and crypto-backed, so the
+ * digest is always a valid hex-64. We preserve the validation helper for
+ * any future path where user-supplied strings might be treated as SHAs (the
+ * bash core does this for push_sha env-pass, which the TS port rejects at
+ * the type level instead).
+ */
+/** A hex-lowercased SHA-256 digest (64 chars). */
+export type HexSha256 = string;
+/**
+ * Compute a SHA-256 over the UTF-8 bytes of `input`. Returns the lowercase
+ * hex digest.
+ *
+ * This is the one function the cache-key contract depends on — never change
+ * the encoding or the digest format without bumping the cache-key version
+ * (which none of phases 1–4 are permitted to do, per design §8).
+ */
+export declare function sha256Hex(input: string): HexSha256;
+/**
+ * True iff the input looks like a canonical lowercase SHA-256 hex digest.
+ * Used by tests and by defensive callers that accept a string and want to
+ * reject malformed input before writing it into the cache.
+ */
+export declare function isValidSha256Hex(value: string): value is HexSha256;

package/dist/hooks/review-gate/hash.js

@@ -0,0 +1,46 @@
+/**
+ * Portable SHA-256 over arbitrary strings. Replaces the bash core's
+ * sha256sum → shasum → openssl fallback chain (defect L) with a single
+ * Node-stdlib call, removing the Alpine/distroless "no hasher on PATH"
+ * regression class entirely.
+ *
+ * ## Why a dedicated module
+ *
+ * The cache-key contract (design §8) requires byte-exact parity with the
+ * 0.10.1 bash implementation. The bash implementation computes
+ * `sha256sum( <full git diff> )` and uses the hex digest as the cache key.
+ * `crypto.createHash('sha256').update(s).digest('hex')` is bit-identical to
+ * GNU `sha256sum < <(printf '%s' s)` output (neither includes the
+ * filename-suffix padding). Regression-tested against the fixture in
+ * `__fixtures__/cache-keys.json`.
+ *
+ * ## Hex-64 validation
+ *
+ * The bash core validates the hasher output is `^[0-9a-f]{64}$` before using
+ * it as a cache key; a partial read or broken pipe would otherwise cache
+ * garbage. Node's `createHash` is synchronous and crypto-backed, so the
+ * digest is always a valid hex-64. We preserve the validation helper for
+ * any future path where user-supplied strings might be treated as SHAs (the
+ * bash core does this for push_sha env-pass, which the TS port rejects at
+ * the type level instead).
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Compute a SHA-256 over the UTF-8 bytes of `input`. Returns the lowercase
+ * hex digest.
+ *
+ * This is the one function the cache-key contract depends on — never change
+ * the encoding or the digest format without bumping the cache-key version
+ * (which none of phases 1–4 are permitted to do, per design §8).
+ */
+export function sha256Hex(input) {
+    return createHash('sha256').update(input, 'utf8').digest('hex');
+}
+/**
+ * True iff the input looks like a canonical lowercase SHA-256 hex digest.
+ * Used by tests and by defensive callers that accept a string and want to
+ * reject malformed input before writing it into the cache.
+ */
+export function isValidSha256Hex(value) {
+    return /^[0-9a-f]{64}$/.test(value);
+}