omp-conductor 0.12.0 → 0.14.0

package/src/tracker/github.ts

@@ -25,6 +25,8 @@ import { credentialedEnv } from "../gitops.ts";
 import { parsePrDiff } from "../diff-flags.ts";
 import type {
   IssueState,
+  IssueSnapshot,
+  MergedPrInfo,
   OpenCloser,
   PrDiff,
   PrState,
@@ -32,6 +34,7 @@ import type {
   ProjectConfig,
   ReadyIssue,
   Tracker,
+  WorkflowRun,
 } from "../types.ts";
 
 /**
@@ -48,8 +51,8 @@ import type {
  * MERGED reference with the argument both true and false. The state is filtered
  * in this consumer instead.
  *
- * ponytail: one page of ten. An issue closed by more than ten PRs is not a
- * dispatch problem, and the first OPEN one already answers the question.
+ * ponytail: one page of ten. Admission stops at the first OPEN closer; salvage
+ * recovery searches that page for its exact branch and repository identity.
  */
 const CLOSERS_QUERY = `query($owner:String!,$repo:String!,$n:Int!){
   repository(owner:$owner,name:$repo){
@@ -75,7 +78,7 @@ interface ClosersResponse {
       issue?: {
         closedByPullRequestsReferences?: {
           nodes?:
-            | ({ state: string; isDraft: boolean; url: string; headRefName?: string } | null)[]
+            | ({ state: string; isDraft: boolean; url: string; headRefName?: string; repository?: { nameWithOwner?: string } | null } | null)[]
             | null;
         } | null;
       } | null;
@@ -186,33 +189,32 @@ function isLabelNoop(err: unknown, op: "add" | "remove"): boolean {
       );
 }
 
+/** Every OPEN closer in a `gh api graphql` reply. */
+export function openClosers(raw: string): OpenCloser[] {
+  const nodes =
+    (JSON.parse(raw) as ClosersResponse).data?.repository?.issue?.closedByPullRequestsReferences
+      ?.nodes ?? [];
+  const closers: OpenCloser[] = [];
+  for (const node of nodes) {
+    if (node === null || node.state !== "OPEN") continue;
+    closers.push({
+      url: node.url,
+      headRefName: node.headRefName ?? "",
+      repo: node.repository?.nameWithOwner ?? "",
+    });
+  }
+  return closers;
+}
+
 /**
- * The first OPEN closer in a `gh api graphql` reply, if any.
- *
- * Split from the call so the state filter — the only real logic in this file —
- * is pinned against recorded payloads instead of a live repo.
+ * The first OPEN closer, for admission's any-open guard.
  *
- * A draft counts. `isDraft` is selected because the API offers it, not because
- * it changes the answer: draft means "not ready to review", not "not pushed",
- * and the branch behind a draft still holds the only copy of the work. Sending
- * a second worker at it duplicates that work exactly as much as a ready PR
- * would, so OPEN is the whole test.
- *
- * `headRefName` is selected because admission needs to recognise a PR opened on
- * a run's retained branch *after* that run ended — veltro#324 on 2026-08-09,
- * killed at the turns cap before its worker opened a PR, so the row kept the
- * branch and `prUrl` stayed NULL (#50). A node without it is not a crash and
- * not a hold: an empty string simply never equals a stored branch, so such a
- * reply degrades to the URL-equality identity that shipped before.
+ * A draft counts: it is pushed work, and dispatching another worker duplicates
+ * it. Missing branch or repository identity still guards admission; recovery
+ * reads {@link openClosers} and refuses to adopt such a node.
  */
 export function firstOpenCloser(raw: string): OpenCloser | undefined {
-  const nodes =
-    (JSON.parse(raw) as ClosersResponse).data?.repository?.issue?.closedByPullRequestsReferences
-      ?.nodes ?? [];
-  const open = nodes.find((n) => n !== null && n.state === "OPEN");
-  return open === undefined || open === null
-    ? undefined
-    : { url: open.url, headRefName: open.headRefName ?? "" };
+  return openClosers(raw)[0];
 }
 
 /**
@@ -242,6 +244,122 @@ export function prUrlParts(
   return { owner: match[1], repo: match[2], number: Number.parseInt(match[3], 10) };
 }
 
+/** Parse the merge identity emitted by `gh pr view --json mergeCommit,baseRefName`. */
+export function mergedPrInfoFrom(raw: string): MergedPrInfo | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return undefined;
+  }
+  if (
+    parsed === null ||
+    typeof parsed !== "object" ||
+    !("mergeCommit" in parsed) ||
+    !("baseRefName" in parsed)
+  ) {
+    return undefined;
+  }
+  const commit = parsed.mergeCommit;
+  const mergeSha =
+    commit !== null && typeof commit === "object" && "oid" in commit ? commit.oid : undefined;
+  const baseRef = parsed.baseRefName;
+  return typeof mergeSha === "string" &&
+    /^[0-9a-f]{40,64}$/i.test(mergeSha) &&
+    typeof baseRef === "string" &&
+    baseRef.length > 0
+    ? { mergeSha, baseRef }
+    : undefined;
+}
+
+/** Parse the commit identity emitted by GitHub's branch REST endpoint. */
+export function branchHeadFrom(raw: string): string | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return undefined;
+  }
+  if (
+    parsed === null ||
+    typeof parsed !== "object" ||
+    !("commit" in parsed) ||
+    parsed.commit === null ||
+    typeof parsed.commit !== "object" ||
+    !("sha" in parsed.commit)
+  ) {
+    return undefined;
+  }
+  const sha = parsed.commit.sha;
+  return typeof sha === "string" && /^[0-9a-f]{40,64}$/i.test(sha) ? sha : undefined;
+}
+
+/** Parse an Actions workflow-run list, skipping malformed entries without
+ *  turning a valid empty list into an unreadable response. */
+export function workflowRunsFrom(raw: string): WorkflowRun[] | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object" || !("workflow_runs" in parsed)) {
+    return undefined;
+  }
+  const entries = parsed.workflow_runs;
+  if (!Array.isArray(entries)) return undefined;
+  const runs: WorkflowRun[] = [];
+  for (const entry of entries) {
+    if (
+      entry === null ||
+      typeof entry !== "object" ||
+      !("id" in entry) ||
+      !("workflow_id" in entry) ||
+      !("name" in entry) ||
+      !("status" in entry) ||
+      !("html_url" in entry) ||
+      !("created_at" in entry)
+    ) {
+      continue;
+    }
+    const id = entry.id;
+    const workflowId = entry.workflow_id;
+    const name = entry.name;
+    const status = entry.status;
+    const conclusion = "conclusion" in entry ? entry.conclusion : undefined;
+    const url = entry.html_url;
+    const createdAt = entry.created_at;
+    if (
+      typeof id !== "number" ||
+      !Number.isSafeInteger(id) ||
+      id <= 0 ||
+      typeof workflowId !== "number" ||
+      !Number.isSafeInteger(workflowId) ||
+      workflowId <= 0 ||
+      typeof name !== "string" ||
+      name.length === 0 ||
+      typeof status !== "string" ||
+      status.length === 0 ||
+      typeof url !== "string" ||
+      url.length === 0 ||
+      typeof createdAt !== "string" ||
+      !Number.isFinite(Date.parse(createdAt))
+    ) {
+      continue;
+    }
+    runs.push({
+      id,
+      workflowId,
+      name,
+      status,
+      ...(typeof conclusion === "string" && conclusion.length > 0 ? { conclusion } : {}),
+      url,
+      createdAt,
+    });
+  }
+  return runs;
+}
+
 /**
  * How much of a pull request's diff the settlement audit will hold in memory.
  *
@@ -272,33 +390,39 @@ function checkVerdict(check: GhCheck): CheckVerdict {
 
 /**
  * Verify one `gh pr view --json state,isDraft,headRefOid,statusCheckRollup`
- * payload against the worker-observed head. A missing rollup is pending rather
- * than green because GitHub may not have created the checks yet.
+ * payload, optionally against a caller-observed head. A missing rollup is
+ * pending rather than green because GitHub may not have created the checks yet.
  */
-export function prVerificationFrom(raw: string, expectedHead: string): PrVerification {
+export function prVerificationFrom(raw: string, expectedHead?: string): PrVerification {
   const pr = JSON.parse(raw) as GhPrVerification;
+  if (typeof pr.headRefOid !== "string" || pr.headRefOid === "") {
+    throw new Error("PR head is unavailable");
+  }
+  const headSha = pr.headRefOid;
   if (pr.state !== "OPEN") {
-    return { status: "failed", reason: `PR is ${pr.state ?? "unknown"}, expected OPEN` };
+    return { status: "failed", reason: `PR is ${pr.state ?? "unknown"}, expected OPEN`, headSha };
   }
   if (pr.isDraft !== false) {
-    return { status: "failed", reason: "PR is draft or draft state is unknown" };
+    return { status: "failed", reason: "PR is draft or draft state is unknown", headSha };
   }
-  if (pr.headRefOid?.toLowerCase() !== expectedHead.toLowerCase()) {
+  if (expectedHead !== undefined && headSha.toLowerCase() !== expectedHead.toLowerCase()) {
     return {
       status: "failed",
-      reason: `PR head changed: expected ${expectedHead}, found ${pr.headRefOid ?? "unknown"}`,
+      reason: `PR head changed: expected ${expectedHead}, found ${headSha}`,
+      headSha,
     };
   }
 
   const checks = pr.statusCheckRollup ?? [];
   if (checks.length === 0) {
-    return { status: "pending", reason: "GitHub has not reported any checks yet" };
+    return { status: "pending", reason: "GitHub has not reported any checks yet", headSha };
   }
   const failed = checks.filter((check) => checkVerdict(check) === "failed");
   if (failed.length > 0) {
     return {
       status: "failed",
       reason: `Checks failed: ${failed.map((check) => `${checkName(check)} (${check.conclusion ?? check.state ?? "unknown"})`).join(", ")}`,
+      headSha,
     };
   }
   const pending = checks.filter((check) => checkVerdict(check) === "pending");
@@ -306,9 +430,10 @@ export function prVerificationFrom(raw: string, expectedHead: string): PrVerific
     return {
       status: "pending",
       reason: `Checks pending: ${pending.map(checkName).join(", ")}`,
+      headSha,
     };
   }
-  return { status: "green", reason: `${checks.length} checks succeeded or were skipped` };
+  return { status: "green", reason: `${checks.length} checks succeeded or were skipped`, headSha };
 }
 
 function failedCheck(raw: string): GhCheck | undefined {
@@ -380,6 +505,25 @@ export function issueStateFrom(raw: string): IssueState | undefined {
   }
 }
 
+/** Direct issue admission facts parsed fail-closed from a REST projection. */
+export function issueSnapshotFrom(raw: string): IssueSnapshot | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const row = parsed as { readonly [key: string]: unknown };
+  const rawState = row["state"];
+  const labels = row["labels"];
+  if (typeof rawState !== "string" || !Array.isArray(labels) || !labels.every((label) => typeof label === "string")) {
+    return undefined;
+  }
+  const state = issueStateFrom(rawState.toUpperCase());
+  return state === undefined ? undefined : { state, labels };
+}
+
 /**
  * GitHub's REST pull-request shape (`{state, merged_at}`) mapped onto
  * {@link PrState}. `merged_at` is what distinguishes a merged PR from a
@@ -868,6 +1012,43 @@ export function makeTracker(
     }
   };
 
+  const readOpenClosers = async (issue: number): Promise<OpenCloser[]> => {
+    // GraphQL wants the halves of `owner/repo` separately. Config validates
+    // that spelling, so an empty half means a hand-edited config: `gh` then
+    // errors and the caller holds the candidate rather than guessing.
+    const [owner = "", name = ""] = repo.split("/");
+    const raw = await runGh([
+      "api",
+      "graphql",
+      "-f",
+      `query=${CLOSERS_QUERY}`,
+      "-F",
+      `owner=${owner}`,
+      "-F",
+      `repo=${name}`,
+      // -F, not -f: the query declares $n as Int! and a string would be a
+      // type error rather than a coerced number.
+      "-F",
+      `n=${issue}`,
+    ]);
+    return openClosers(raw);
+  };
+
+  const readIssueSnapshot = async (issue: number): Promise<IssueSnapshot | undefined> => {
+    try {
+      return issueSnapshotFrom(
+        await runGh([
+          "api",
+          `repos/${repo}/issues/${issue}`,
+          "--jq",
+          "{state: .state, labels: [.labels[].name]}",
+        ]),
+      );
+    } catch {
+      return undefined;
+    }
+  };
+
   // Named rather than returned inline, so `rerunFailedChecks` can reuse
   // `checkConclusions` instead of re-implementing the same `gh` call.
   const tracker: Tracker = {
@@ -972,28 +1153,11 @@ export function makeTracker(
     },
 
     async openCloserFor(issue: number): Promise<OpenCloser | undefined> {
-      // GraphQL wants the halves of `owner/repo` separately. Config validates
-      // that spelling, so an empty half means a hand-edited config: `gh` then
-      // errors and the caller holds the candidate rather than guessing.
-      const [owner = "", name = ""] = repo.split("/");
-      const raw = await runGh([
-        "api",
-        "graphql",
-        "-f",
-        `query=${CLOSERS_QUERY}`,
-        "-F",
-        `owner=${owner}`,
-        "-F",
-        `repo=${name}`,
-        // -F, not -f: the query declares $n as Int! and a string would be a
-        // type error rather than a coerced number.
-        "-F",
-        `n=${issue}`,
-      ]);
-
-      return firstOpenCloser(raw);
+      return (await readOpenClosers(issue))[0];
     },
 
+    openClosersFor: readOpenClosers,
+
     async issueState(issue: number): Promise<IssueState | undefined> {
       try {
         // REST answers lowercase `open`/`closed`; the shared parser expects the
@@ -1006,6 +1170,8 @@ export function makeTracker(
       }
     },
 
+    issueSnapshot: readIssueSnapshot,
+
     async prState(url: string): Promise<PrState | undefined> {
       // No `--repo`: the full URL names the repository, and the daemon runs
       // from its own state directory rather than a checkout — so the REST path
@@ -1032,7 +1198,84 @@ export function makeTracker(
       }
     },
 
-    async verifyPr(url: string, expectedHead: string): Promise<PrVerification | undefined> {
+    async mergedPrInfo(url: string): Promise<MergedPrInfo | undefined> {
+      if (!PR_URL.test(url)) return undefined;
+      try {
+        return mergedPrInfoFrom(
+          await runGh(["pr", "view", url, "--json", "mergeCommit,baseRefName"]),
+        );
+      } catch {
+        return undefined;
+      }
+    },
+
+    async branchHead(repo: string, branch: string): Promise<string | undefined> {
+      if (!/^[^/\s]+\/[^/\s]+$/.test(repo) || branch.length === 0) return undefined;
+      try {
+        return branchHeadFrom(
+          await runGh(["api", `repos/${repo}/branches/${encodeURIComponent(branch)}`]),
+        );
+      } catch {
+        return undefined;
+      }
+    },
+
+    async workflowRunsAt(
+      repo: string,
+      sha: string,
+      opts?: { event?: string; branch?: string },
+    ): Promise<WorkflowRun[] | undefined> {
+      if (!/^[^/\s]+\/[^/\s]+$/.test(repo) || !/^[0-9a-f]{40,64}$/i.test(sha)) {
+        return undefined;
+      }
+      const query = [`head_sha=${encodeURIComponent(sha)}`];
+      if (opts?.event !== undefined) query.push(`event=${encodeURIComponent(opts.event)}`);
+      if (opts?.branch !== undefined) query.push(`branch=${encodeURIComponent(opts.branch)}`);
+      query.push("per_page=50");
+      try {
+        return workflowRunsFrom(
+          await runGh(["api", `repos/${repo}/actions/runs?${query.join("&")}`]),
+        );
+      } catch {
+        return undefined;
+      }
+    },
+
+    async previousWorkflowRun(
+      repo: string,
+      workflowId: number,
+      branch: string,
+      before: string,
+    ): Promise<WorkflowRun | null | undefined> {
+      if (
+        !/^[^/\s]+\/[^/\s]+$/.test(repo) ||
+        !Number.isSafeInteger(workflowId) ||
+        workflowId <= 0 ||
+        branch.length === 0 ||
+        !Number.isFinite(Date.parse(before))
+      ) {
+        return undefined;
+      }
+      try {
+        const runs = workflowRunsFrom(
+          await runGh([
+            "api",
+            `repos/${repo}/actions/workflows/${workflowId}/runs?branch=${encodeURIComponent(branch)}&created=${encodeURIComponent(`<${before}`)}&per_page=2`,
+          ]),
+        );
+        if (runs === undefined) return undefined;
+        const beforeMs = Date.parse(before);
+        return (
+          runs
+            .filter((run) => Date.parse(run.createdAt) < beforeMs)
+            .sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt))[0] ?? null
+        );
+      } catch {
+        return undefined;
+      }
+    },
+
+    async verifyPr(url: string, expectedHead?: string): Promise<PrVerification | undefined> {
       if (!PR_URL.test(url)) return undefined;
       try {
         const raw = await runGh([