@dev-loops/core 1.0.0-rc.2 → 1.0.0-rc.4

package/src/github/copilot-helpers.mjs

@@ -6,11 +6,76 @@
  * scripts and other packages/core modules.
  */
 
-const SUBMITTED_REVIEW_STATES = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"]);
+// Exported so anything deciding "is there a real prior review" uses the same
+// whitelist as the loop-state reader — two copies could drift, and a guard
+// acting on the gate's behalf must agree with the gate about what a submitted
+// review is.
+export const SUBMITTED_REVIEW_STATES = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"]);
 const GATE_REVIEW_NAMES = new Set(["draft_gate", "pre_approval_gate"]);
 const GATE_REVIEW_VERDICTS = new Set(["clean", "findings_present", "blocked"]);
 const GATE_EXECUTION_MODES = new Set(["fanout_fanin", "inline_single_agent"]);
 
+// The literal header line the gate review body always emits first
+// (upsert-checkpoint-verdict.mjs's renderGateReviewCommentBody, re-exported
+// from there). Owned here so the machine-artifact filter below and every
+// consumer that needs to recognize "is this a real gate verdict surface" read
+// the same producer-owned literal instead of restating it. Line-start anchored
+// (`m`) so a quoted header in a reply/blockquote can't match.
+export const GATE_REVIEW_COMMENT_HEADER_RE = /^###\s+Gate review:\s*`(draft_gate|pre_approval_gate)`\s*$/m;
+
+/** Returns the matched gate name when `body` carries a genuine gate verdict header, else null. */
+export function matchGateReviewCommentHeader(body) {
+  if (typeof body !== "string") return null;
+  const match = body.match(GATE_REVIEW_COMMENT_HEADER_RE);
+  return match ? match[1] : null;
+}
+
+// Machine-authored gate artifacts that must never win the newest-gate-marker
+// tie-break in summarizeGateReviewComments/summarizeGateReviewCommentMarkers:
+// a historical standalone findings review always embedded this gate's name in
+// its header line and could quote the current head sha inside a finding's own
+// free text (the lenient gate-name+hex-token fallback in
+// parseGateReviewCommentFields would otherwise happily match that), and the
+// historical deferred-summary PR comment quoted a gate name plus a sha-shaped
+// id in its table rows the same way. Both are excluded HERE, inside the two
+// shared summarizers, because this module is the true merge point: every
+// consumer (detect-checkpoint-evidence.mjs, pre-pr-ready-gate.mjs,
+// ready-for-review.mjs, request-copilot-review.mjs) calls
+// summarizeGateReviewComments/summarizeGateReviewCommentMarkers to turn a raw
+// comment/review list into a gate verdict, so filtering here — rather than
+// per-caller — covers all of them by construction.
+//
+// Anchored to the start of a line (`^` with `m`) so only a marker rendered as
+// the first character of its own line is excluded — a genuine verdict
+// comment whose findings summary merely QUOTES the marker text mid-line (for
+// example, describing this very mechanism) still counts as evidence. Both
+// producers render their marker at column 0, so the anchor costs nothing
+// against genuine artifacts.
+// The set covers exactly three marker tokens: the per-round review round
+// marker (gate-findings-review), post-gate-findings.mjs's opt-in findings
+// COMMENT marker (gate-findings gate=...), and the historical
+// deferred-summary comment. Without the findings-comment marker, that comment
+// parses as a verdict marker candidate (its "Gate fan-out findings:"/
+// "Reviewed head:" lines yield gate+headSha) and the verdict upsert claims
+// and overwrites it in place, silently destroying the round's visible
+// findings record. Every branch is delimiter-anchored — the token must be
+// followed by whitespace or the closing `-->` — so no suffixed `<token>-<x>`
+// variant ever matches.
+const GATE_MACHINE_ARTIFACT_MARKER_RE = /^<!--\s*dev-loops:(?:gate-findings-review|gate-findings|deferred-summary)(?=\s|-->)/mu;
+
+export function isGateMachineArtifactBody(body) {
+  if (typeof body !== "string" || !GATE_MACHINE_ARTIFACT_MARKER_RE.test(body)) {
+    return false;
+  }
+  // A gate round now posts ONE PR review carrying BOTH the verdict header and
+  // the gate-findings-review marker (the findings it files live on that same
+  // surface). Such a body IS the verdict, not a separate machine artifact, so
+  // the producer-owned verdict header wins over the artifact marker. Only a
+  // marker-bearing body with NO genuine verdict header (a historical standalone
+  // findings review or deferred-summary comment) stays excluded.
+  return matchGateReviewCommentHeader(body) === null;
+}
+
 export function isCopilotLogin(login) {
   return typeof login === "string" && /^copilot(?:[^a-z]|$)/i.test(login);
 }
@@ -234,50 +299,86 @@ function parseGateReviewCommentFields(body) {
     }
     const line = stripped;
 
+    // First-NON-EMPTY-wins per field: a genuine comment renders its structured
+    // block first, so the first column-0 match for each field is normally the
+    // real one. A free-text field (findings summary, next action) rendered
+    // later in the SAME comment can embed a newline plus a spoofed
+    // "Verdict: clean" (or any other field label) at column 0; capturing only
+    // the first match (rather than the last) stops that later line from
+    // winning and flipping/nulling the field. But the label regex's
+    // `\s*(.+)$` also matches a label followed by nothing but whitespace,
+    // capturing an empty string — for the enum fields (gate/headSha/verdict/
+    // executionMode) an empty capture normalizes to null already, so the
+    // `=== null` guard below naturally stays open for a later, genuine line.
+    // The two free-text fields (findingsSummary, nextAction) do NOT normalize
+    // through an enum, so an empty capture must be checked for explicitly:
+    // treat it as no-capture (leave the field open) rather than locking it to
+    // "" and hiding a real line that renders after it.
     let match = line.match(/^(?:[-*]\s*)?(?:gate(?:\s+name)?|gate\s+review)\s*:\s*(.+)$/iu);
     if (match) {
-      fields.gate = normalizeGateReviewName(match[1]);
+      if (fields.gate === null) {
+        fields.gate = normalizeGateReviewName(match[1]);
+      }
       continue;
     }
 
     match = line.match(/^(?:[-*]\s*)?(?:head\s+sha(?:\s+reviewed)?|reviewed\s+head\s+sha)\s*:\s*(.+)$/iu);
     if (match) {
-      fields.headSha = normalizeGateReviewHeadSha(match[1]);
+      if (fields.headSha === null) {
+        fields.headSha = normalizeGateReviewHeadSha(match[1]);
+      }
       continue;
     }
 
     match = line.match(/^(?:[-*]\s*)?verdict\s*:\s*(.+)$/iu);
     if (match) {
-      fields.verdict = normalizeGateReviewVerdict(match[1]);
+      if (fields.verdict === null) {
+        fields.verdict = normalizeGateReviewVerdict(match[1]);
+      }
       continue;
     }
 
     match = line.match(/^(?:[-*]\s*)?(?:findings(?:\s+summary)?|summary)\s*:\s*(.+)$/iu);
     if (match) {
-      fields.findingsSummary = match[1].trim();
+      if (fields.findingsSummary === null) {
+        const candidate = match[1].trim();
+        // An empty capture (label followed only by whitespace) is treated as
+        // no-capture: leave the field open so a later, genuine line can still
+        // win instead of first-wins locking it to "".
+        if (candidate.length > 0) {
+          fields.findingsSummary = candidate;
+        }
+      }
       continue;
     }
 
     match = line.match(/^(?:[-*]\s*)?next\s+action\s*:\s*(.+)$/iu);
     if (match) {
-      fields.nextAction = match[1].trim();
+      if (fields.nextAction === null) {
+        const candidate = match[1].trim();
+        if (candidate.length > 0) {
+          fields.nextAction = candidate;
+        }
+      }
       continue;
     }
 
     match = line.match(/^(?:[-*]\s*)?execution\s+mode\s*:\s*(.+)$/iu);
     if (match) {
-      const rest = match[1].trim();
-      // Split on the first em-dash / en-dash / " - " separator to recover an
-      // optional inline reason: "inline_single_agent — <reason>".
-      const sepMatch = rest.match(/^(.*?)\s*(?:[—–]|\s-\s)\s*(.*)$/u);
-      const modeToken = sepMatch ? sepMatch[1].trim() : rest;
-      const reasonToken = sepMatch ? sepMatch[2].trim() : "";
-      fields.executionMode = normalizeGateExecutionMode(modeToken);
-      // Only record an inline reason for inline_single_agent. A trailing
-      // "— text" on a fanout_fanin (or invalid) mode line must not surface an
-      // inconsistent mode/reason pair, so leave inlineReason null otherwise.
-      if (reasonToken.length > 0 && fields.executionMode === "inline_single_agent") {
-        fields.inlineReason = reasonToken;
+      if (fields.executionMode === null) {
+        const rest = match[1].trim();
+        // Split on the first em-dash / en-dash / " - " separator to recover an
+        // optional inline reason: "inline_single_agent — <reason>".
+        const sepMatch = rest.match(/^(.*?)\s*(?:[—–]|\s-\s)\s*(.*)$/u);
+        const modeToken = sepMatch ? sepMatch[1].trim() : rest;
+        const reasonToken = sepMatch ? sepMatch[2].trim() : "";
+        fields.executionMode = normalizeGateExecutionMode(modeToken);
+        // Only record an inline reason for inline_single_agent. A trailing
+        // "— text" on a fanout_fanin (or invalid) mode line must not surface an
+        // inconsistent mode/reason pair, so leave inlineReason null otherwise.
+        if (reasonToken.length > 0 && fields.executionMode === "inline_single_agent") {
+          fields.inlineReason = reasonToken;
+        }
       }
       continue;
     }
@@ -353,6 +454,18 @@ export function parseGateReviewCommentMarkerBody(body) {
   };
 }
 
+// Which GitHub surface carries a gate verdict. The poster needs it to pick the
+// right in-place correction endpoint on a same-head rerun (a PR review is PUT
+// to pulls/{pr}/reviews/{id}; a legacy verdict issue comment is PATCHed to
+// issues/comments/{id}). Anything that is not the review surface — including a
+// raw issue-comment payload with no `surface` field — is issue_comment, so the
+// historical shape survives untouched. SINGLE definition: a restatement that
+// misses a future third surface would silently route its body to the
+// issue-comment endpoint, where it does not live.
+export function normalizeVerdictSurface(value) {
+  return value === "review" ? "review" : "issue_comment";
+}
+
 export function summarizeGateReviewComments(comments) {
   const summary = {
     draft_gate: null,
@@ -363,6 +476,9 @@ export function summarizeGateReviewComments(comments) {
 
   for (let index = 0; index < entries.length; index += 1) {
     const comment = entries[index];
+    if (isGateMachineArtifactBody(comment?.body)) {
+      continue;
+    }
     const parsed = parseGateReviewCommentBody(comment?.body);
     if (!parsed) {
       continue;
@@ -378,6 +494,7 @@ export function summarizeGateReviewComments(comments) {
       nextAction: parsed.nextAction,
       executionMode: parsed.executionMode ?? null,
       inlineReason: parsed.inlineReason ?? null,
+      surface: normalizeVerdictSurface(comment?.surface),
       commentId: Number.isInteger(comment?.id) ? comment.id : null,
       commentUrl: typeof comment?.html_url === "string" && comment.html_url.trim().length > 0 ? comment.html_url.trim() : null,
       updatedAt: typeof (comment?.updated_at ?? comment?.updatedAt) === "string"
@@ -409,6 +526,9 @@ export function summarizeGateReviewCommentMarkers(comments, { headSha } = {}) {
 
   for (let index = 0; index < entries.length; index += 1) {
     const comment = entries[index];
+    if (isGateMachineArtifactBody(comment?.body)) {
+      continue;
+    }
     const parsed = parseGateReviewCommentMarkerBody(comment?.body);
     if (!parsed) {
       continue;
@@ -429,6 +549,7 @@ export function summarizeGateReviewCommentMarkers(comments, { headSha } = {}) {
       executionMode: parsed.executionMode ?? null,
       inlineReason: parsed.inlineReason ?? null,
       contractComplete: parsed.contractComplete,
+      surface: normalizeVerdictSurface(comment?.surface),
       commentId: Number.isInteger(comment?.id) ? comment.id : null,
       commentUrl: typeof comment?.html_url === "string" && comment.html_url.trim().length > 0 ? comment.html_url.trim() : null,
       updatedAt: typeof (comment?.updated_at ?? comment?.updatedAt) === "string"