@bookedsolid/rea 0.10.2 → 0.10.3

package/dist/hooks/review-gate/base-resolve.js

@@ -0,0 +1,247 @@
+/**
+ * Base-ref resolution for the push-review gate.
+ *
+ * ## What "base resolution" means
+ *
+ * Given a pushed refspec (a `local_sha` + `remote_ref` pair, plus the
+ * remote name), determine:
+ *
+ *   1. the commit SHA the local changes should be diffed against
+ *      (the "merge base"), and
+ *   2. the human-facing label for the `Target:` banner line
+ *      (defect N semantic: the SEMANTIC base, not the refspec destination).
+ *
+ * The four code paths the bash core walked (push-review-core.sh §720-889):
+ *
+ *   A. Tracked-branch push (`remote_sha != ZERO`). Use
+ *      `git merge-base <remote_sha> <local_sha>`. Label = refspec target.
+ *   B. New-branch push with `branch.<source>.base` config (defect N). The
+ *      operator opted into a specific base. Prefer `refs/remotes/<remote>/
+ *      <configured>` if it exists, else fall back to `refs/heads/<configured>`
+ *      with a WARN on stderr. Label = configured base name.
+ *   C. New-branch push without config, with `refs/remotes/<remote>/HEAD`
+ *      resolvable. Use that symbolic-ref as the anchor. Label = refspec
+ *      target (preserves the cache-key contract for bare pushes).
+ *   D. Bootstrap: no config, no symbolic-ref, probe `main` then `master`.
+ *      If both fail, anchor on the empty-tree SHA so the full push content
+ *      is reviewable. Label = refspec target.
+ *
+ * ## Phase 2a scope (this file)
+ *
+ * `resolveBaseForRefspec()` composes the four paths via the `GitRunner`
+ * port from `diff.ts`. This module is pure in the same sense `diff.ts`
+ * is — every git hit goes through the injected runner, so unit tests
+ * enumerate the four paths without touching a real repo.
+ *
+ * Defect-N fail-loud (design §7) is Phase 4's final cutover and is NOT
+ * turned on here. `NoBaseResolvableError` is reserved in `errors.ts` but
+ * the empty-tree bootstrap remains the current production fallback.
+ * Phase 2b composes the final policy into `runPushReviewGate()`.
+ */
+import { EMPTY_TREE_SHA, ZERO_SHA } from './constants.js';
+import { hasCommitLocally, mergeBase, readGitConfig, refExists, resolveRemoteDefaultRef, } from './diff.js';
+/**
+ * Strip `refs/heads/` / `refs/for/` prefixes from a ref and return the
+ * trailing branch name. Used for the target-label normalization path
+ * where both ref families should collapse to a bare branch name for
+ * display. Exported for tests.
+ */
+export function stripRefsPrefix(ref) {
+    if (ref.startsWith('refs/heads/'))
+        return ref.slice('refs/heads/'.length);
+    if (ref.startsWith('refs/for/'))
+        return ref.slice('refs/for/'.length);
+    return ref;
+}
+/**
+ * Strip ONLY the `refs/heads/` prefix — leaves `refs/for/`, `refs/tags/`,
+ * and every other ref-namespace untouched. Mirrors the bash core's
+ * `${local_ref#refs/heads/}` on the source-branch lookup path (push-review-
+ * core.sh §797), so Gerrit-style pushes (`refs/for/main`) keep their
+ * namespace and do NOT accidentally match a `branch.main.base` config
+ * entry intended for a regular branch push.
+ *
+ * Codex pass-1 on Phase 2a flagged the earlier implementation that used
+ * `stripRefsPrefix` here — it would have promoted the Target: label for
+ * a Gerrit push against the reviewer's intent. Exported for tests.
+ */
+export function stripRefsHeadsOnly(ref) {
+    if (ref.startsWith('refs/heads/'))
+        return ref.slice('refs/heads/'.length);
+    return ref;
+}
+/**
+ * Resolve the base anchor for a single push refspec. See the file-top
+ * docstring for the four code paths.
+ *
+ * Deletion refspecs (local_sha === ZERO_SHA) return `{merge_base: null,
+ * status: 'ok'}` with `path: 'tracked'` — the caller is expected to have
+ * already trapped deletions via `hasDeletion()` before calling here. We
+ * don't throw in that case because the caller owns the deletion policy,
+ * not this resolver.
+ */
+export function resolveBaseForRefspec(record, deps) {
+    const { runner, cwd } = deps;
+    const targetLabel = computeInitialTargetLabel(record);
+    // Deletion — caller owns the policy.
+    if (record.is_deletion) {
+        return {
+            merge_base: null,
+            target_label: targetLabel,
+            status: 'ok',
+            path: 'tracked',
+        };
+    }
+    // Path A: tracked-branch push (remote_sha is not ZERO). Existing
+    // history is available; merge-base against the remote's tip.
+    if (record.remote_sha !== ZERO_SHA) {
+        if (!hasCommitLocally(runner, cwd, record.remote_sha)) {
+            return {
+                merge_base: null,
+                target_label: targetLabel,
+                status: 'remote_object_missing',
+                remote_sha: record.remote_sha,
+                path: 'tracked',
+            };
+        }
+        const mb = mergeBase(runner, cwd, record.remote_sha, record.local_sha);
+        if (mb === null) {
+            return {
+                merge_base: null,
+                target_label: targetLabel,
+                status: 'no_merge_base',
+                remote_sha: record.remote_sha,
+                path: 'tracked',
+            };
+        }
+        return {
+            merge_base: mb,
+            target_label: targetLabel,
+            status: 'ok',
+            path: 'tracked',
+        };
+    }
+    // Path B/C/D: new-branch push. Need a server-authoritative anchor.
+    //
+    // Bash-core parity (push-review-core.sh §797): the source-branch lookup
+    // uses `${local_ref#refs/heads/}` — strips ONLY the `refs/heads/`
+    // prefix. For a Gerrit-style `refs/for/main` push, bash leaves the ref
+    // as `refs/for/main`, the `branch.refs/for/main.base` config key never
+    // matches, and the new-branch walk proceeds to the origin/HEAD /
+    // bootstrap path. We mirror that exactly: use `stripRefsHeadsOnly`
+    // rather than the more aggressive `stripRefsPrefix` (which also strips
+    // `refs/for/`). The aggressive strip was a Phase 1 carry-over from
+    // `args.ts`'s destination-ref normalization; applied here it would
+    // cause a `refs/for/main` push to look up `branch.main.base` and
+    // potentially promote the Target: label against the reviewer's
+    // intent. Codex pass-1 on Phase 2a flagged this (P3) and we preserve
+    // byte-for-byte bash parity.
+    const sourceBranch = stripRefsHeadsOnly(record.local_ref);
+    const newBranchOutcome = resolveNewBranchBase(sourceBranch, deps);
+    if (newBranchOutcome.kind === 'config_hit') {
+        // Defect N: promote the target label to the configured base's short
+        // name. The bash core does this ONLY when the config hit fires — for
+        // all other new-branch paths the label stays as the refspec target
+        // (preserves cache-key / label continuity for pre-config consumers).
+        //
+        // `exactOptionalPropertyTypes: true` in tsconfig means we must NOT
+        // set `local_ref_fallback_warning: undefined` — we either include the
+        // key (as a string) or omit it entirely. Spread the conditional.
+        const result = {
+            merge_base: mergeBase(runner, cwd, newBranchOutcome.ref, record.local_sha) ?? EMPTY_TREE_SHA,
+            target_label: newBranchOutcome.label,
+            status: 'ok',
+            path: 'new_branch_config',
+        };
+        if (newBranchOutcome.warning !== null) {
+            result.local_ref_fallback_warning = newBranchOutcome.warning;
+        }
+        return result;
+    }
+    if (newBranchOutcome.kind === 'origin_head') {
+        return {
+            merge_base: mergeBase(runner, cwd, newBranchOutcome.ref, record.local_sha) ?? EMPTY_TREE_SHA,
+            target_label: targetLabel,
+            status: 'ok',
+            path: 'new_branch_origin_head',
+        };
+    }
+    // Bootstrap: no config, no remote HEAD — anchor on the empty-tree SHA
+    // so the full push content is reviewable. Matches bash §887.
+    return {
+        merge_base: EMPTY_TREE_SHA,
+        target_label: targetLabel,
+        status: 'ok',
+        path: 'bootstrap_empty_tree',
+    };
+}
+/**
+ * Compute the initial `Target:` label for a refspec: the short name of
+ * the remote ref, falling back to `main` when it's empty (defensive;
+ * `args.ts` should never emit an empty remote_ref for a non-deletion).
+ *
+ * Exported for unit tests. Mirrors push-review-core.sh §725-727.
+ */
+export function computeInitialTargetLabel(record) {
+    let target = stripRefsPrefix(record.remote_ref);
+    if (target.length === 0)
+        target = 'main';
+    return target;
+}
+/**
+ * Path B: consult `branch.<source>.base`. Returns `config_hit` iff a base
+ * was configured AND resolvable to a ref that exists. Falls through
+ * otherwise. Exported so tests can exercise the config-path independently.
+ */
+export function resolveNewBranchBase(sourceBranch, deps) {
+    const { runner, cwd, remote } = deps;
+    // B — branch.<source>.base config hit.
+    if (sourceBranch.length > 0 && sourceBranch !== 'HEAD') {
+        const configuredBase = readGitConfig(runner, cwd, `branch.${sourceBranch}.base`);
+        if (configuredBase.length > 0) {
+            const remoteRef = `refs/remotes/${remote}/${configuredBase}`;
+            const localRef = `refs/heads/${configuredBase}`;
+            if (refExists(runner, cwd, remoteRef)) {
+                return {
+                    kind: 'config_hit',
+                    ref: remoteRef,
+                    label: configuredBase,
+                    warning: null,
+                };
+            }
+            if (refExists(runner, cwd, localRef)) {
+                // Bash-core §819-820: local-ref fallback is less trustworthy; emit
+                // a WARN so the reviewer knows the anchor may be stale.
+                const warning = `WARN: branch.${sourceBranch}.base=${configuredBase} resolved to local ref; ` +
+                    `remote counterpart ${remote}/${configuredBase} missing — reviewer-side diff may be stale`;
+                return {
+                    kind: 'config_hit',
+                    ref: localRef,
+                    label: configuredBase,
+                    warning,
+                };
+            }
+            // Config key set but neither ref exists: fall through to origin/HEAD
+            // (bash does the same — `configured_base` stays non-empty, but
+            // `default_ref` is still empty so the OR at §844 takes over).
+        }
+    }
+    // C — refs/remotes/<remote>/HEAD.
+    const symbolic = resolveRemoteDefaultRef(runner, cwd, remote);
+    if (symbolic !== null && symbolic.length > 0) {
+        return { kind: 'origin_head', ref: symbolic };
+    }
+    // C-bis — fall-back probes: `main`, then `master`. Bash §834-843 probes
+    // both because symbolic-ref fails on shallow or mirror clones where
+    // origin/HEAD was never set.
+    const mainRef = `refs/remotes/${remote}/main`;
+    if (refExists(runner, cwd, mainRef)) {
+        return { kind: 'origin_head', ref: mainRef };
+    }
+    const masterRef = `refs/remotes/${remote}/master`;
+    if (refExists(runner, cwd, masterRef)) {
+        return { kind: 'origin_head', ref: masterRef };
+    }
+    // D — bootstrap.
+    return { kind: 'bootstrap' };
+}

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

@@ -0,0 +1,108 @@
+/**
+ * Review-cache adapter for the push-review gate.
+ *
+ * ## What this module owns
+ *
+ * 1. Compute the cache key from a diff. **Re-exports** `computeCacheKey`
+ *    from the Phase-1 `cache-key.ts` module — this is the same function,
+ *    not a reimplementation. The fixture suite (`cache.test.ts`) locks
+ *    that invariant via a byte-exact re-run against
+ *    `__fixtures__/cache-keys.json`. If the two modules ever diverge,
+ *    the 0.10.x → 0.11.0 cache contract is broken and every consumer's
+ *    on-disk cache becomes unreachable. See design §8.
+ *
+ * 2. Wrap `src/cache/review-cache.ts` so callers get a single entry
+ *    point — `checkReviewCache({ diff, branch, base })` — that hides
+ *    the TTL semantics, the `(sha, branch, base)` key tuple, and the
+ *    cache-lookup result shape.
+ *
+ * 3. Translate the cache lookup into the same three-way outcome the
+ *    bash core's §1203 `jq -e '.hit == true and .result == "pass"'`
+ *    check emitted:
+ *
+ *      - `hit_pass`    — cache hit AND result === 'pass'. Gate passes.
+ *      - `hit_fail`    — cache hit AND result === 'fail'. Cached
+ *                        negative verdict; gate blocks. (Bash §1197-1202
+ *                        rejects this; we preserve.)
+ *      - `miss`        — no hit / expired / empty file. Gate falls
+ *                        through to the review-required banner.
+ *      - `query_error` — cache lookup threw. Bash §1180-1196 treated
+ *                        this as a `{"hit":false,"reason":"query_error"}`
+ *                        cached result; we carry the error body so the
+ *                        caller can emit the CACHE CHECK FAILED banner
+ *                        with the SANITIZED stderr (defect C0/C1 strip).
+ *
+ * ## Phase 2a scope
+ *
+ * This file exports pure functions over the already-TS
+ * `review-cache.ts`. No subprocess `spawn`, no CLI fork. The bash
+ * core's `rea cache check` subprocess hop is obviated entirely —
+ * once Phase 3 swaps the shim we no longer fork/exec node for the
+ * cache lookup at all.
+ *
+ * ## Phase 2b composition
+ *
+ * `runPushReviewGate` in `index.ts` calls `computeCacheKeyFromDiff` +
+ * `checkReviewCache` sequentially; the latter returns a discriminated
+ * outcome the gate branches on. No new behavior lands here — that's
+ * the `codex-gate.ts` / composition step.
+ */
+import type { HexSha256 } from './hash.js';
+/**
+ * Compute the cache key for a diff. This is a thin re-export of Phase 1's
+ * `computeCacheKey` — exposed on this module so callers can use a single
+ * import when they need both the key AND the lookup.
+ *
+ * The function is UNCHANGED from Phase 1. The fixture suite in
+ * `cache.test.ts` proves byte-exact parity against
+ * `__fixtures__/cache-keys.json` for all six scenarios.
+ */
+export declare function computeCacheKey(diff: string): HexSha256;
+/**
+ * Discriminated outcome of a cache lookup. Matches the three-way state
+ * the bash core's §1203 predicate surfaces, plus a `query_error` kind
+ * for the §1180-1196 case.
+ */
+export type CacheOutcome = {
+    kind: 'hit_pass';
+    key: HexSha256;
+    recorded_at: string;
+} | {
+    kind: 'hit_fail';
+    key: HexSha256;
+    recorded_at: string;
+    reason?: string;
+} | {
+    kind: 'miss';
+    key: HexSha256;
+    reason: 'no-entry' | 'expired' | 'empty-file';
+} | {
+    kind: 'query_error';
+    key: HexSha256;
+    error: string;
+};
+/**
+ * Input for `checkReviewCache`. `diff` is the full `git diff` body; the
+ * cache key is derived from it via `computeCacheKey`. `branch` + `base`
+ * select which entry in the key-bucket is returned (most-recent match).
+ */
+export interface CheckReviewCacheInput {
+    baseDir: string;
+    diff: string;
+    branch: string;
+    base: string;
+    /** Optional override for `Date.now()`-driven TTL expiration — test hook only. */
+    nowMs?: number;
+    /** Optional override for the TTL (seconds). Defaults to cache-module default. */
+    maxAgeSeconds?: number;
+}
+/**
+ * Perform a cache lookup and translate into the discriminated outcome.
+ *
+ * Does NOT throw on a lookup failure — every known error path routes
+ * through the `query_error` variant so the caller's single `switch`
+ * handles all four outcomes. This mirrors the bash core's
+ * `CACHE_STDOUT || CACHE_EXIT != 0 → {"hit":false,...}` collapse at
+ * §1180-1196.
+ */
+export declare function checkReviewCache(input: CheckReviewCacheInput): Promise<CacheOutcome>;

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

@@ -0,0 +1,120 @@
+/**
+ * Review-cache adapter for the push-review gate.
+ *
+ * ## What this module owns
+ *
+ * 1. Compute the cache key from a diff. **Re-exports** `computeCacheKey`
+ *    from the Phase-1 `cache-key.ts` module — this is the same function,
+ *    not a reimplementation. The fixture suite (`cache.test.ts`) locks
+ *    that invariant via a byte-exact re-run against
+ *    `__fixtures__/cache-keys.json`. If the two modules ever diverge,
+ *    the 0.10.x → 0.11.0 cache contract is broken and every consumer's
+ *    on-disk cache becomes unreachable. See design §8.
+ *
+ * 2. Wrap `src/cache/review-cache.ts` so callers get a single entry
+ *    point — `checkReviewCache({ diff, branch, base })` — that hides
+ *    the TTL semantics, the `(sha, branch, base)` key tuple, and the
+ *    cache-lookup result shape.
+ *
+ * 3. Translate the cache lookup into the same three-way outcome the
+ *    bash core's §1203 `jq -e '.hit == true and .result == "pass"'`
+ *    check emitted:
+ *
+ *      - `hit_pass`    — cache hit AND result === 'pass'. Gate passes.
+ *      - `hit_fail`    — cache hit AND result === 'fail'. Cached
+ *                        negative verdict; gate blocks. (Bash §1197-1202
+ *                        rejects this; we preserve.)
+ *      - `miss`        — no hit / expired / empty file. Gate falls
+ *                        through to the review-required banner.
+ *      - `query_error` — cache lookup threw. Bash §1180-1196 treated
+ *                        this as a `{"hit":false,"reason":"query_error"}`
+ *                        cached result; we carry the error body so the
+ *                        caller can emit the CACHE CHECK FAILED banner
+ *                        with the SANITIZED stderr (defect C0/C1 strip).
+ *
+ * ## Phase 2a scope
+ *
+ * This file exports pure functions over the already-TS
+ * `review-cache.ts`. No subprocess `spawn`, no CLI fork. The bash
+ * core's `rea cache check` subprocess hop is obviated entirely —
+ * once Phase 3 swaps the shim we no longer fork/exec node for the
+ * cache lookup at all.
+ *
+ * ## Phase 2b composition
+ *
+ * `runPushReviewGate` in `index.ts` calls `computeCacheKeyFromDiff` +
+ * `checkReviewCache` sequentially; the latter returns a discriminated
+ * outcome the gate branches on. No new behavior lands here — that's
+ * the `codex-gate.ts` / composition step.
+ */
+import { lookup } from '../../cache/review-cache.js';
+import { computeCacheKey as computePhase1CacheKey } from './cache-key.js';
+/**
+ * Compute the cache key for a diff. This is a thin re-export of Phase 1's
+ * `computeCacheKey` — exposed on this module so callers can use a single
+ * import when they need both the key AND the lookup.
+ *
+ * The function is UNCHANGED from Phase 1. The fixture suite in
+ * `cache.test.ts` proves byte-exact parity against
+ * `__fixtures__/cache-keys.json` for all six scenarios.
+ */
+export function computeCacheKey(diff) {
+    return computePhase1CacheKey({ diff });
+}
+/**
+ * Perform a cache lookup and translate into the discriminated outcome.
+ *
+ * Does NOT throw on a lookup failure — every known error path routes
+ * through the `query_error` variant so the caller's single `switch`
+ * handles all four outcomes. This mirrors the bash core's
+ * `CACHE_STDOUT || CACHE_EXIT != 0 → {"hit":false,...}` collapse at
+ * §1180-1196.
+ */
+export async function checkReviewCache(input) {
+    const key = computeCacheKey(input.diff);
+    let result;
+    try {
+        result = await lookup(input.baseDir, {
+            sha: key,
+            branch: input.branch,
+            base: input.base,
+            ...(input.nowMs !== undefined ? { nowMs: input.nowMs } : {}),
+            ...(input.maxAgeSeconds !== undefined ? { maxAgeSeconds: input.maxAgeSeconds } : {}),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { kind: 'query_error', key, error: msg };
+    }
+    if (!result.hit) {
+        // `result.missReason` is always set when `hit` is false (see
+        // review-cache.ts's CacheLookupResult contract). The fallback to
+        // 'no-entry' is defensive for an ill-formed result we shouldn't see.
+        return {
+            kind: 'miss',
+            key,
+            reason: result.missReason ?? 'no-entry',
+        };
+    }
+    // Hit. Branch on verdict — the bash core requires BOTH hit==true AND
+    // result==pass. A hit with result==fail is a cached negative verdict
+    // and must NOT unblock the push.
+    const entry = result.entry;
+    if (entry === undefined) {
+        // Defensive: `hit: true` without an entry is an ill-formed result.
+        return { kind: 'miss', key, reason: 'no-entry' };
+    }
+    if (entry.result === 'pass') {
+        return { kind: 'hit_pass', key, recorded_at: entry.recorded_at };
+    }
+    // result === 'fail'
+    const hitFail = {
+        kind: 'hit_fail',
+        key,
+        recorded_at: entry.recorded_at,
+    };
+    if (entry.reason !== undefined && entry.reason.length > 0) {
+        hitFail.reason = entry.reason;
+    }
+    return hitFail;
+}

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;