@bookedsolid/rea 0.10.2 → 0.10.3

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

@@ -0,0 +1,131 @@
+/**
+ * Audit-record emission + consumption for the review gate.
+ *
+ * ## Responsibilities
+ *
+ * 1. Emit `push.review.skipped` and `codex.review.skipped` records via the
+ *    existing `appendAuditRecord()` helper. These are NEVER forgeable-
+ *    verdict records (the push-review gate never consults them as Codex
+ *    receipts), so they intentionally go through the `"other"`-stamped
+ *    public path rather than the `"rea-cli"` dedicated writer.
+ *
+ * 2. Scan `.rea/audit.jsonl` for a qualifying `codex.review` receipt
+ *    certifying a given `head_sha`. This is the TS equivalent of the
+ *    bash core's `jq -R 'fromjson? | select(...)'` predicate
+ *    (push-review-core.sh §959-966).
+ *
+ * ## Defect carry-forwards
+ *
+ * - **Defect P** (forgery rejection). The scan filter requires
+ *   `emission_source ∈ {"rea-cli", "codex-cli"}`. The public
+ *   `appendAuditRecord()` helper stamps `"other"`; only the dedicated
+ *   `appendCodexReviewAuditRecord()` helper and the Codex CLI write
+ *   `"rea-cli"` / `"codex-cli"`. Records with `emission_source: "other"`
+ *   or missing the field entirely are rejected here.
+ *
+ * - **Defect U** (streaming-parse tolerance). Every line in `.rea/
+ *   audit.jsonl` is parsed independently in a try/catch. A single
+ *   corrupt line mid-file does NOT abort the scan — later lines still
+ *   get a chance. Before 0.10.2 the bash `jq -e` scan would bail on the
+ *   first unparseable line and miss every subsequent legitimate record.
+ *
+ * - **Verdict whitelist**. Only `verdict ∈ {"pass", "concerns"}` records
+ *   satisfy the protected-path gate. `blocking` and `error` verdicts are
+ *   receipts that a review HAPPENED but with a negative outcome, which
+ *   does NOT unblock the push. Mirrors push-review-core.sh §964.
+ */
+import { type AuditRecord } from '../../audit/append.js';
+import { type OsIdentity } from './metadata.js';
+/** Tool-names the gate emits. Kept as constants so string-literal drift is caught at compile time. */
+export declare const PUSH_REVIEW_SKIPPED_TOOL = "push.review.skipped";
+export declare const CODEX_REVIEW_SKIPPED_TOOL = "codex.review.skipped";
+export declare const PUSH_REVIEW_CACHE_HIT_TOOL = "push.review.cache.hit";
+export declare const PUSH_REVIEW_CACHE_ERROR_TOOL = "push.review.cache.error";
+/** Server-names for the emit paths — carry forward from bash §473/§639. */
+export declare const ESCAPE_HATCH_SERVER = "rea.escape_hatch";
+export declare const PUSH_REVIEW_SERVER = "rea.push_review";
+/**
+ * Input shape for the `REA_SKIP_PUSH_REVIEW` escape hatch's audit record.
+ *
+ * The `os_identity` field is captured inside this module (not by the
+ * caller) so every emitter gets the same shape and failing fields degrade
+ * to empty strings uniformly. The pid/ppid numeric-not-string invariant
+ * (defect M) is enforced by `metadata.ts`.
+ */
+export interface SkipPushReviewAuditInput {
+    /** Repo root (the dir containing `.rea/`). */
+    baseDir: string;
+    /** `HEAD` SHA at the time of the skip. */
+    head_sha: string;
+    /** Current branch or empty string. */
+    branch: string;
+    /** The non-empty value of `REA_SKIP_PUSH_REVIEW` (the reason). */
+    reason: string;
+    /** The resolved git actor (email, then name, else empty). */
+    actor: string;
+    /**
+     * OS-identity fields. Optional — when absent, `collectOsIdentity()` runs
+     * and fills them. Tests inject a deterministic stub for snapshot stability.
+     */
+    os_identity?: OsIdentity;
+}
+/**
+ * Emit the `push.review.skipped` audit record. Wraps the public
+ * `appendAuditRecord()` helper — emission_source lands as `"other"`.
+ *
+ * The skipped record is intentionally NOT a `codex.review` receipt: the
+ * push-review cache-gate scan rejects any record whose `tool_name` is not
+ * `codex.review` AND any record whose `emission_source` is not
+ * `rea-cli` / `codex-cli`. So this record is on the hash chain as
+ * forensic evidence but cannot be confused with a real Codex review.
+ */
+export declare function emitPushReviewSkipped(input: SkipPushReviewAuditInput): Promise<AuditRecord>;
+/**
+ * Input shape for the `REA_SKIP_CODEX_REVIEW` (Codex-only) waiver.
+ *
+ * `metadata_source` records whether the skip metadata came from the
+ * pre-push stdin (`"prepush-stdin"`) or from a local HEAD fallback
+ * (`"local-fallback"`). Bash-core §594+§606.
+ */
+export interface SkipCodexReviewAuditInput {
+    baseDir: string;
+    head_sha: string;
+    target: string;
+    reason: string;
+    actor: string;
+    metadata_source: 'prepush-stdin' | 'local-fallback';
+}
+export declare function emitCodexReviewSkipped(input: SkipCodexReviewAuditInput): Promise<AuditRecord>;
+/**
+ * Predicate: does this parsed JSON object qualify as a valid
+ * `codex.review` receipt for the given `head_sha`?
+ *
+ * Exported for unit tests; callers should usually use
+ * `hasValidCodexReview()` below.
+ */
+export declare function isQualifyingCodexReview(record: unknown, head_sha: string): boolean;
+/**
+ * Scan `.rea/audit.jsonl` for a qualifying `codex.review` record matching
+ * the given `head_sha`. Returns true as soon as one is found.
+ *
+ * ## Defect U tolerance
+ *
+ * Each line is parsed independently via `JSON.parse` inside try/catch. A
+ * malformed line logs nothing and the scan continues. The bash fix in
+ * 0.10.2 was `jq -R 'fromjson?'`; we mirror the per-line behavior in
+ * native JS.
+ *
+ * ## Path safety
+ *
+ * The audit file is always `<baseDir>/.rea/audit.jsonl` — baseDir flows
+ * in from the caller and is the same resolved path used everywhere else.
+ * No caller-supplied path segments.
+ *
+ * ## Missing file
+ *
+ * ENOENT resolves to `false` (no receipt exists yet). Any other error
+ * propagates — the caller's policy is to fail-closed, and a permission
+ * error on the audit file is a distinct operational concern the caller
+ * should surface rather than silently mask as "no receipt".
+ */
+export declare function hasValidCodexReview(baseDir: string, head_sha: string): Promise<boolean>;

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

@@ -0,0 +1,181 @@
+/**
+ * Audit-record emission + consumption for the review gate.
+ *
+ * ## Responsibilities
+ *
+ * 1. Emit `push.review.skipped` and `codex.review.skipped` records via the
+ *    existing `appendAuditRecord()` helper. These are NEVER forgeable-
+ *    verdict records (the push-review gate never consults them as Codex
+ *    receipts), so they intentionally go through the `"other"`-stamped
+ *    public path rather than the `"rea-cli"` dedicated writer.
+ *
+ * 2. Scan `.rea/audit.jsonl` for a qualifying `codex.review` receipt
+ *    certifying a given `head_sha`. This is the TS equivalent of the
+ *    bash core's `jq -R 'fromjson? | select(...)'` predicate
+ *    (push-review-core.sh §959-966).
+ *
+ * ## Defect carry-forwards
+ *
+ * - **Defect P** (forgery rejection). The scan filter requires
+ *   `emission_source ∈ {"rea-cli", "codex-cli"}`. The public
+ *   `appendAuditRecord()` helper stamps `"other"`; only the dedicated
+ *   `appendCodexReviewAuditRecord()` helper and the Codex CLI write
+ *   `"rea-cli"` / `"codex-cli"`. Records with `emission_source: "other"`
+ *   or missing the field entirely are rejected here.
+ *
+ * - **Defect U** (streaming-parse tolerance). Every line in `.rea/
+ *   audit.jsonl` is parsed independently in a try/catch. A single
+ *   corrupt line mid-file does NOT abort the scan — later lines still
+ *   get a chance. Before 0.10.2 the bash `jq -e` scan would bail on the
+ *   first unparseable line and miss every subsequent legitimate record.
+ *
+ * - **Verdict whitelist**. Only `verdict ∈ {"pass", "concerns"}` records
+ *   satisfy the protected-path gate. `blocking` and `error` verdicts are
+ *   receipts that a review HAPPENED but with a negative outcome, which
+ *   does NOT unblock the push. Mirrors push-review-core.sh §964.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { appendAuditRecord, InvocationStatus, Tier, } from '../../audit/append.js';
+import { collectOsIdentity } from './metadata.js';
+/** Tool-names the gate emits. Kept as constants so string-literal drift is caught at compile time. */
+export const PUSH_REVIEW_SKIPPED_TOOL = 'push.review.skipped';
+export const CODEX_REVIEW_SKIPPED_TOOL = 'codex.review.skipped';
+export const PUSH_REVIEW_CACHE_HIT_TOOL = 'push.review.cache.hit';
+export const PUSH_REVIEW_CACHE_ERROR_TOOL = 'push.review.cache.error';
+/** Server-names for the emit paths — carry forward from bash §473/§639. */
+export const ESCAPE_HATCH_SERVER = 'rea.escape_hatch';
+export const PUSH_REVIEW_SERVER = 'rea.push_review';
+/**
+ * Emit the `push.review.skipped` audit record. Wraps the public
+ * `appendAuditRecord()` helper — emission_source lands as `"other"`.
+ *
+ * The skipped record is intentionally NOT a `codex.review` receipt: the
+ * push-review cache-gate scan rejects any record whose `tool_name` is not
+ * `codex.review` AND any record whose `emission_source` is not
+ * `rea-cli` / `codex-cli`. So this record is on the hash chain as
+ * forensic evidence but cannot be confused with a real Codex review.
+ */
+export async function emitPushReviewSkipped(input) {
+    const osIdentity = input.os_identity ?? collectOsIdentity();
+    const metadata = {
+        head_sha: input.head_sha,
+        branch: input.branch,
+        reason: input.reason,
+        actor: input.actor,
+        verdict: 'skipped',
+        os_identity: osIdentity,
+    };
+    const record = {
+        tool_name: PUSH_REVIEW_SKIPPED_TOOL,
+        server_name: ESCAPE_HATCH_SERVER,
+        status: InvocationStatus.Allowed,
+        tier: Tier.Read,
+        metadata,
+    };
+    return appendAuditRecord(input.baseDir, record);
+}
+export async function emitCodexReviewSkipped(input) {
+    const metadata = {
+        head_sha: input.head_sha,
+        target: input.target,
+        reason: input.reason,
+        actor: input.actor,
+        verdict: 'skipped',
+        files_changed: null,
+        metadata_source: input.metadata_source,
+    };
+    const record = {
+        tool_name: CODEX_REVIEW_SKIPPED_TOOL,
+        server_name: ESCAPE_HATCH_SERVER,
+        status: InvocationStatus.Allowed,
+        tier: Tier.Read,
+        metadata,
+    };
+    return appendAuditRecord(input.baseDir, record);
+}
+/** Verdicts that satisfy the protected-path Codex-receipt gate. */
+const ACCEPTABLE_VERDICTS = new Set(['pass', 'concerns']);
+/** Emission sources that satisfy the protected-path Codex-receipt gate. */
+const ACCEPTABLE_SOURCES = new Set(['rea-cli', 'codex-cli']);
+/**
+ * Predicate: does this parsed JSON object qualify as a valid
+ * `codex.review` receipt for the given `head_sha`?
+ *
+ * Exported for unit tests; callers should usually use
+ * `hasValidCodexReview()` below.
+ */
+export function isQualifyingCodexReview(record, head_sha) {
+    if (record === null || typeof record !== 'object')
+        return false;
+    const r = record;
+    if (r.tool_name !== 'codex.review')
+        return false;
+    if (typeof r.emission_source !== 'string' || !ACCEPTABLE_SOURCES.has(r.emission_source)) {
+        return false;
+    }
+    const md = r.metadata;
+    if (md === null || md === undefined || typeof md !== 'object')
+        return false;
+    if (md.head_sha !== head_sha)
+        return false;
+    if (typeof md.verdict !== 'string' || !ACCEPTABLE_VERDICTS.has(md.verdict)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Scan `.rea/audit.jsonl` for a qualifying `codex.review` record matching
+ * the given `head_sha`. Returns true as soon as one is found.
+ *
+ * ## Defect U tolerance
+ *
+ * Each line is parsed independently via `JSON.parse` inside try/catch. A
+ * malformed line logs nothing and the scan continues. The bash fix in
+ * 0.10.2 was `jq -R 'fromjson?'`; we mirror the per-line behavior in
+ * native JS.
+ *
+ * ## Path safety
+ *
+ * The audit file is always `<baseDir>/.rea/audit.jsonl` — baseDir flows
+ * in from the caller and is the same resolved path used everywhere else.
+ * No caller-supplied path segments.
+ *
+ * ## Missing file
+ *
+ * ENOENT resolves to `false` (no receipt exists yet). Any other error
+ * propagates — the caller's policy is to fail-closed, and a permission
+ * error on the audit file is a distinct operational concern the caller
+ * should surface rather than silently mask as "no receipt".
+ */
+export async function hasValidCodexReview(baseDir, head_sha) {
+    const auditFile = path.join(baseDir, '.rea', 'audit.jsonl');
+    let raw;
+    try {
+        raw = await fs.readFile(auditFile, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+    if (raw.length === 0)
+        return false;
+    // Walk lines. Each line is independently parsed; a corrupt line is
+    // silently skipped. A matching record short-circuits the scan.
+    for (const line of raw.split('\n')) {
+        if (line.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            // Defect U tolerance — move on.
+            continue;
+        }
+        if (isQualifyingCodexReview(parsed, head_sha))
+            return true;
+    }
+    return false;
+}

package/dist/hooks/review-gate/base-resolve.d.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 { type GitRunner } from './diff.js';
+import type { RefspecRecord } from './args.js';
+/**
+ * Resolved base outcome for a single refspec. Never thrown — callers
+ * translate blocked conditions (remote object missing, no merge-base)
+ * into `BlockedError` subclasses up the stack.
+ */
+export interface ResolvedBase {
+    /**
+     * The commit / tree SHA to diff against. Always set when
+     * `status === 'ok'`; otherwise null.
+     */
+    merge_base: string | null;
+    /**
+     * The human-facing `Target:` label (defect N). The bash core defaults
+     * this to the refspec target and promotes it to the configured base's
+     * short name only when `branch.<source>.base` resolved. We mirror that.
+     */
+    target_label: string;
+    /** Discriminator for the caller. */
+    status: 'ok' | 'remote_object_missing' | 'no_merge_base' | 'no_base_resolvable';
+    /**
+     * For the "tracked branch but the remote commit isn't locally present"
+     * path, return the remote SHA so the caller's banner can echo it. Empty
+     * otherwise.
+     */
+    remote_sha?: string;
+    /**
+     * True when the configured-base branch was resolved via the LOCAL ref
+     * (`refs/heads/<configured>`) instead of the remote-tracking ref. The
+     * bash core prints a WARN in this case (push-review-core.sh §819-820).
+     * Phase 2a carries the signal; Phase 2b's composition emits the banner.
+     */
+    local_ref_fallback_warning?: string;
+    /**
+     * The resolution path taken. Audit + debugging aid; never part of the
+     * cache key. Phase 2b's audit records include this for forensic trace.
+     */
+    path: 'tracked' | 'new_branch_config' | 'new_branch_origin_head' | 'bootstrap_empty_tree';
+}
+/**
+ * Deps for base resolution. Same `GitRunner` port `diff.ts` uses; plus the
+ * remote name (from the adapter's argv, defaults to `origin`). `cwd` is
+ * the resolved repo root.
+ */
+export interface ResolveBaseDeps {
+    runner: GitRunner;
+    cwd: string;
+    /** Remote name (`origin` by convention, but respect what git passed to the hook). */
+    remote: string;
+}
+/**
+ * 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 declare function stripRefsPrefix(ref: string): string;
+/**
+ * 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 declare function stripRefsHeadsOnly(ref: string): string;
+/**
+ * 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 declare function resolveBaseForRefspec(record: RefspecRecord, deps: ResolveBaseDeps): ResolvedBase;
+/**
+ * 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 declare function computeInitialTargetLabel(record: RefspecRecord): string;
+/**
+ * Inner helper: resolve the new-branch anchor via the B→C→D walk. Stays
+ * module-private so callers only see `resolveBaseForRefspec` as the
+ * public surface. Returns a discriminated union so the caller can branch
+ * on path + extract the warning / label cleanly.
+ */
+type NewBranchOutcome = {
+    kind: 'config_hit';
+    ref: string;
+    label: string;
+    /** Non-null when we fell back to `refs/heads/<base>` (§819-820 WARN). */
+    warning: string | null;
+} | {
+    kind: 'origin_head';
+    ref: string;
+} | {
+    kind: 'bootstrap';
+};
+/**
+ * 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 declare function resolveNewBranchBase(sourceBranch: string, deps: ResolveBaseDeps): NewBranchOutcome;
+export {};