@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/review-generation.js

@@ -0,0 +1,219 @@
+/**
+ * Review-generation correlation for the resumable ticket-review wait (BAPI-1104, R77).
+ *
+ * THE GAP THIS CLOSES. `wait_for_ticket_review` holds no claim token, so on its
+ * own it cannot tell "the review I just submitted finished" from "a review from
+ * last week is still attached". The backend's `202`-while-generating branch looks
+ * like it settles that, but it does not: the pending branch is gated on
+ * `generating_doc_type_set_at` being inside `_GENERATING_TTL_SECONDS`
+ * (`api/routes/jira_api.py:2977-2996`), and a review that outlives the TTL falls
+ * straight through to the attachment lookup and returns the PRIOR document as a
+ * `200`. A worker that resolved against that would write a verdict for a review
+ * that never happened — the exact class of failure this ticket exists to remove.
+ *
+ * WHAT MAKES IT CLOSEABLE WITHOUT A ROUTE CHANGE. Every delivered review
+ * document already carries a terminal `bridge-review-decision-identity` footer
+ * with a monotonic `generation` integer (stamped by
+ * `api/library/review_decision_integrity.py`). So the client can record what was
+ * attached at submission time and refuse a `200` whose generation has not
+ * advanced past it. The ticket forbids touching the route; this needs nothing
+ * from it.
+ *
+ * WHAT IS STORED. Normalized repository and ticket identity plus two small
+ * integers. Never a credential, a header, a URL carrying a query secret, a
+ * response body, or exception text — the registry is in-process, bounded, and
+ * deliberately holds nothing worth leaking.
+ */
+/** The identity footer's marker, mirroring `review_decision_integrity.py:44`. */
+const REVIEW_DECISION_IDENTITY_MARKER = "bridge-review-decision-identity";
+/**
+ * Matches the footer at the TERMINAL end of a document — the one position the
+ * stamper writes it. The payload is "any character that does not begin a `-->`"
+ * rather than a lazy `.*?` for the same reason the Python side spells it that
+ * way: a lazy payload backtracks across an intervening `-->` and swallows two
+ * footers as one.
+ */
+const IDENTITY_TERMINAL_RE = new RegExp(`<!--\\s*${REVIEW_DECISION_IDENTITY_MARKER}\\s*:((?:(?!-->)[\\s\\S])*)-->\\s*$`);
+/**
+ * The generation integer from a delivered review document, or `null`.
+ *
+ * `null` means "this document carries no readable identity" — an unstamped
+ * legacy attachment, or a body that is not the document at all. The caller
+ * treats that as NOT-advanced rather than as advanced, because an unreadable
+ * identity is not evidence that a new review landed.
+ */
+export function parseReviewGeneration(markdown) {
+    if (typeof markdown !== "string")
+        return null;
+    const match = IDENTITY_TERMINAL_RE.exec(markdown);
+    if (!match)
+        return null;
+    let payload;
+    try {
+        payload = JSON.parse(match[1]);
+    }
+    catch {
+        return null;
+    }
+    if (payload === null || typeof payload !== "object")
+        return null;
+    const generation = payload.generation;
+    if (typeof generation !== "number" || !Number.isInteger(generation))
+        return null;
+    return generation;
+}
+/** Valid domain for `expectedLegCount`: a review has at most two legs. */
+function isValidExpectedLegCount(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 2;
+}
+/**
+ * True when `delivered` is a strictly newer generation than `baseline`.
+ *
+ * An absent baseline (`null`) means nothing was attached at submission, so any
+ * readable generation is an advance. An unreadable delivered generation is never
+ * an advance — see {@link parseReviewGeneration}.
+ */
+export function generationAdvanced(baseline, delivered) {
+    if (delivered === null)
+        return false;
+    if (baseline === null)
+        return true;
+    return delivered > baseline;
+}
+/**
+ * Normalized registry key. Case-folded so two spellings cannot split an entry.
+ *
+ * The separator is NUL because it cannot occur in a repository name or a ticket
+ * key, so no pair of inputs can collide by straddling it. It is written as an
+ * ESCAPE rather than as a literal byte deliberately: a raw NUL makes git treat
+ * the whole file as binary, which renders it as `+0/-0` in a pull request and
+ * makes the generation-correlation logic in this file unreviewable. The runtime
+ * string is identical either way.
+ */
+const KEY_SEPARATOR = "\u0000";
+function baselineKey(repoName, ticketNumber) {
+    return `${repoName.trim().toLowerCase()}${KEY_SEPARATOR}${ticketNumber.trim().toUpperCase()}`;
+}
+/**
+ * How long one submission baseline stays usable.
+ *
+ * Sized against the consumer, not the producer: a spec-review worker waits in
+ * repeated 240-second windows under a 120-minute job timeout
+ * (`job_registry.py`), so a baseline must outlive that whole span or the wait it
+ * exists to correlate would lose its anchor partway through and start accepting
+ * whatever is attached. Two hours covers it with margin.
+ */
+const BASELINE_TTL_MS = 2 * 60 * 60 * 1000;
+/**
+ * Cap on live baselines. One MCP server process reviews a handful of tickets at
+ * a time; the bound is what keeps a long-lived process from accumulating an
+ * entry per ticket it ever touched.
+ */
+const MAX_BASELINES = 64;
+/**
+ * In-process, bounded submission-generation registry.
+ *
+ * In-process is the right scope and not a compromise: the baseline correlates
+ * ONE submission with the waits that follow it in the same MCP server, which is
+ * exactly the lifetime a recipe run has. Persisting it would make a stale row
+ * from a crashed run able to block a fresh review — strictly worse than losing
+ * the anchor, which merely degrades to today's behavior.
+ *
+ * BAPI-1121: an entry's `expectedLegCount` diagnostic is cleared only once the
+ * artifact gate has persisted its accepted artifacts and handled any
+ * withheld canonical file — see `clear()`. A rejected or indeterminate
+ * submission still drops its entry immediately (`clear()` from the trigger
+ * failure/non-OK paths), so an unaccepted submission can never wedge a later
+ * wait on stale diagnostic metadata.
+ *
+ * BAPI-1129: the submission context serves BOTH consumers of the gate — the
+ * blocking `request_ticket_review(wait_for_result: true)` call that reaches
+ * it inline, and any subsequent explicit `wait_for_ticket_review` in the same
+ * process. That is why a blocking call which wrote nothing (a zero-advance
+ * `200`, a classification-only `save_locally: false` call, a parse or
+ * persistence failure) must leave the entry alone: the review it anchored may
+ * still be completing, and the follow-up wait needs this anchor to prove it.
+ */
+export class ReviewGenerationRegistry {
+    now;
+    entries = new Map();
+    constructor(now = () => Date.now()) {
+        this.now = now;
+    }
+    /** Record what was attached when a review was submitted. */
+    record(repoName, ticketNumber, baseline) {
+        this.evictExpired();
+        const key = baselineKey(repoName, ticketNumber);
+        // Delete-then-set so the insertion order Map iteration gives us is also
+        // recency order, which is what makes the eviction below drop the oldest.
+        this.entries.delete(key);
+        this.entries.set(key, { baseline, recordedAtMs: this.now() });
+        while (this.entries.size > MAX_BASELINES) {
+            const oldest = this.entries.keys().next();
+            if (oldest.done)
+                break;
+            this.entries.delete(oldest.value);
+        }
+    }
+    /** The recorded baseline, or `null` when none is live for this ticket. */
+    get(repoName, ticketNumber) {
+        this.evictExpired();
+        return this.entries.get(baselineKey(repoName, ticketNumber))?.baseline ?? null;
+    }
+    /**
+     * Attach the accepted submission's `expected_leg_count` diagnostic to the
+     * live entry (BAPI-1121). Called only AFTER the generate POST is accepted —
+     * the pre-POST baseline recording order above is unchanged.
+     *
+     * Silently a no-op (never poisons state) when there is no live entry to
+     * attach to, or when `expectedLegCount` fails validation (non-integer,
+     * negative, or outside the 0-2 domain a two-leg review allows).
+     */
+    attachExpectedLegCount(repoName, ticketNumber, expectedLegCount) {
+        this.evictExpired();
+        if (!isValidExpectedLegCount(expectedLegCount))
+            return;
+        const key = baselineKey(repoName, ticketNumber);
+        const entry = this.entries.get(key);
+        if (!entry)
+            return;
+        entry.expectedLegCount = expectedLegCount;
+    }
+    /**
+     * The full submission context for the wait: the original baseline plus any
+     * attached diagnostic. Returns `null` when no baseline is live — same
+     * absence contract as `get()`. `expectedLegCount` is `undefined` in the
+     * returned context when none was attached, so callers can distinguish "not
+     * supplied" from "supplied as zero".
+     */
+    getContext(repoName, ticketNumber) {
+        this.evictExpired();
+        const entry = this.entries.get(baselineKey(repoName, ticketNumber));
+        if (!entry)
+            return null;
+        return { baseline: entry.baseline, expectedLegCount: entry.expectedLegCount };
+    }
+    /**
+     * Consume a baseline. Clearing means "durable persistence has happened",
+     * not "a terminal envelope was received" (BAPI-1129) — the anchor is
+     * dropped only after the artifact gate has actually written at least one
+     * accepted leg. Receiving a terminal `200` proves nothing landed on disk,
+     * and a baseline dropped at that moment would downgrade the next
+     * `wait_for_ticket_review` in this process to `terminality_only`, which is
+     * the degraded mode the anchor exists to avoid.
+     *
+     * The one exception is the pre-acceptance case: a submission POST that
+     * failed or was rejected started no review at all, so its anchor is dropped
+     * immediately (see `requestTicketReview`'s trigger-failure paths).
+     */
+    clear(repoName, ticketNumber) {
+        this.entries.delete(baselineKey(repoName, ticketNumber));
+    }
+    evictExpired() {
+        const cutoff = this.now() - BASELINE_TTL_MS;
+        for (const [key, entry] of this.entries) {
+            if (entry.recordedAtMs <= cutoff)
+                this.entries.delete(key);
+        }
+    }
+}

package/build/run-unit-tests-launcher.js

@@ -49,8 +49,13 @@ export const MODULE_MOCK_MANIFEST = [
     "build/attachment-download.test.js",
     "build/attachment-upload.test.js",
     "build/automation-progress.test.js",
+    // BAPI-1104: wait_for_ci_checks drives the real registered handler through the
+    // SDK-capture seam, so it needs --experimental-test-module-mocks. Without an
+    // entry here it would run in the NORMAL lane, where `mock.module` does not
+    // exist — the failure mode this manifest is for.
+    "build/ci-check-wait.test.js",
     "build/conductor/cli-git-hooks.test.js",
-    "build/conductor/cli.test.js",
+    "build/conductor/epic-implementer-cli.test.js",
     "build/conductor/git-inspection.test.js",
     "build/conductor/paths.test.js",
     "build/conductor/pr-ci-producer-emit-seam.test.js",