Files
OmniRoute/scripts/merge-queue/github.mjs
diegosouzapw 1374b95fed feat(ci): bless only with the queue refs protected and the candidate tree recomposed
The final review of cut-over part 1 parked one residual risk as the main condition
for live mode: verifyComposition checks the shape of a candidate (first-parent chain,
trailers, second parents) but never the tree of its merge commits. Someone with write
access who is not the queue could plant an in-flight record plus a candidate whose
merge commit names a queued, approved PR with the right parents and trailers and
carries any tree, and the queue would bless and land it. The only barrier was the
queue-refs ruleset, which nothing in the tick checked.

Two independent locks, both evaluated before anything is blessed:

- verifyComposition({ trees: true }) recomposes every merge commit of the chain with
  compose.mergeTree(parents[0], parents[1]), the exact call the composer makes, and
  refuses a commit whose tree differs, or whose parents conflict or share no history
  ("merge commit <sha12> of #<n>: tree <t12>, recomposing gives <r12|conflict>"). The
  tick asks for it in live and in shadow; a failure takes the existing composition
  mismatch pause (reason "error"). mergeTree and haveCommonAncestor are now exported.
- refs-guard.mjs (new) reads the ACTIVE rules of omni-queue-state and of the batch's
  candidate ref through the new github.getBranchRules (GET /rules/branches/<branch>,
  every page, read-only) and lists every creation/update/deletion rule GitHub does not
  enforce. In landOrWouldLand it runs right after the composition check and before the
  landing-attempts limit, at most once per tick, never stored. Live: an unprotected ref
  pauses ("queue refs are not protected (...): not blessed, not landed; apply
  apply-ruleset.mjs --kind queue-refs, then resume"), whatever the attempt count.
  Shadow: never pauses; the would-land detail gets "; live mode would pause: queue refs
  unprotected (...)". Dry-run: reads (GET) and plans. A read error fails the tick (no
  pause, nothing blessed). Bypass actors are not checked (the App token cannot read
  them). The manual bless is unchanged; no new event type or config key.

Fakes default to "protected": the tick fake GitHub (getBranchRules, branchRules map,
gh.unprotect / h.unprotect) and the HTTP fake (GET /rules/branches/<branch>,
fake.branchRules, fake.unprotect, exposed as world.unprotect) answer the queue-refs
rules for omni-queue-state and any omni-queue/ name. The fake verifyComposition
records `trees`.

Re-aimed test (no assertion dropped):
- "a stored batch is checked against its candidate before the would-land and the
  bless": before, the recorded verifyComposition call was {expectedBaseSha,
  candidateSha, prs, treeSha} in shadow and the squash-api call carried the stored
  tree; now the shadow call must also carry trees: true and the squash-api call must
  carry [stored tree, trees: true]. Why: the fake now records the new argument, and
  the test pins that the tick asks for the tree check in shadow and in live.

New tests: refs-guard.test.mjs (4), github getBranchRules (1), real-git
verifyComposition with trees (3: composed batch with a stacked PR and a real
same-file merge, from a fresh scratch repository too; planted tree on the last and on
a middle merge commit; conflicting and unrelated parents), tick (8: live merge-ff and
squash-api pause on a missing update rule; an unprotected candidate ref beats the
attempts limit; shadow note; read error fails the tick; dry-run; a tree mismatch
pauses before the rules read in live and shadow).
2026-11-15 13:33:53 -03:00

916 lines
36 KiB
JavaScript

// scripts/merge-queue/github.mjs — WP4. Minimal REST client for omni-queue (fetch, no deps).
//
// Every method returns NORMALIZED objects (shapes below / in eligibility.mjs, checks.mjs,
// classify.mjs) so pure modules never see raw API payloads. Retries with exponential backoff on
// network errors, 5xx, 429 and secondary-rate-limit 403 (honors Retry-After / x-ratelimit-reset).
// Never logs the token or Authorization headers; every error message is redacted.
import { CANDIDATE_PREFIX, commentMarker, isSha } from "./contracts.mjs";
export class GitHubError extends Error {
/** @param {number} status @param {string} method @param {string} path @param {string} message */
constructor(status, method, path, message) {
super(`${method} ${path} → ${status}: ${message}`);
this.name = "GitHubError";
this.status = status;
this.method = method;
this.path = path;
}
}
/**
* @typedef {object} PullSummary
* @property {number} number
* @property {boolean} draft
* @property {string} baseRef
* @property {string} headSha
* @property {string} headRef
* @property {string|null} headRepoFullName
* @property {string} title
* @property {string} author
* @property {string[]} labels
* @property {string} createdAt
* @property {string} updatedAt
*/
/**
* @typedef {PullSummary & {state: "open"|"closed", merged: boolean, mergeable: boolean|null,
* mergeableState: string, body: string, changedFiles: number|null}} Pull
* changedFiles = GitHub's `changed_files` count (null when absent)
*/
/**
* @typedef {object} WorkflowRun
* @property {number} id
* @property {string} name
* @property {string} status
* @property {string|null} conclusion
* @property {string} htmlUrl
* @property {string} headSha
* @property {string|null} headBranch branch (or tag) whose event started the run
* @property {string} event "push" | "pull_request" | "workflow_dispatch" | ...
* @property {number|null} checkSuiteId the check suite holding this run's check runs
*/
/**
* @typedef {object} GitHubClient
* @property {string} owner
* @property {string} repo
* @property {(method: string, path: string, opts?: {query?: object, body?: unknown,
* accept?: string, allowStatuses?: number[], retryServerErrors?: boolean})
* => Promise<{status: number, data: any, headers: Headers}>} request
* retryServerErrors:false = a 5xx / network error / timeout is thrown at once (for
* non-idempotent writes whose outcome must be verified instead of replayed)
* @property {(path: string, query?: object) => Promise<any[]>} paginate follows Link rel="next";
* unwraps {total_count, <items>} envelopes (check_runs, workflow_runs, ...)
*
* — pull requests / issues —
* @property {(opts?: {base?: string}) => Promise<PullSummary[]>} listOpenPulls
* @property {(n: number) => Promise<Pull>} getPull
* @property {(n: number) => Promise<string[]>} listPullFiles incl. previous_filename of renames
* @property {(n: number) => Promise<{files: string[], listed: number}>} listPullFileManifest
* files as listPullFiles; listed = entries GitHub returned (it stops at 3,000), to
* compare with Pull.changedFiles
* @property {(n: number) => Promise<import("./eligibility.mjs").TimelineEvent[]>} listIssueTimeline
* @property {(n: number, labels: string[]) => Promise<void>} addLabels
* @property {(n: number, label: string) => Promise<void>} removeLabel 404 = already absent (ok)
* @property {(n: number) => Promise<{id: number, body: string, author: string,
* createdAt: string}[]>} listIssueComments
* @property {(n: number, body: string) => Promise<{id: number}>} createIssueComment
* @property {(n: number, key: string, body: string) => Promise<{posted: boolean}>} commentOnce
* posts `body + "\n\n" + contracts.commentMarker(key)` unless a comment on issue/PR n
* already contains that marker (then {posted:false}). The ONLY way queue code comments.
* After posting it re-reads the comments: when two writers raced (approval job + tick,
* or a POST replayed after a 5xx), the lowest comment id wins and the newer duplicate
* this call created is deleted ({posted:false}).
* @property {(commentId: number) => Promise<void>} deleteIssueComment 404 = already gone
* @property {(opts: {labels?: string[], state?: "open"|"closed"|"all"}) => Promise<{number: number,
* title: string, body: string, labels: string[], state: string,
* updatedAt: string}[]>} listIssues issues only (PRs filtered out)
* @property {(input: {title: string, body: string, labels?: string[]}) => Promise<{number: number}>} createIssue
* @property {(n: number, patch: {title?: string, body?: string, state?: string}) => Promise<void>} updateIssue
*
* — commits / checks / statuses —
* @property {(branch: string) => Promise<string|null>} getBranchSha null when absent
* @property {(sha: string) => Promise<{sha: string, treeSha: string, parents: string[],
* message: string}>} getCommit
* @property {(sha: string) => Promise<import("./checks.mjs").CheckRun[]>} listCheckRuns
* every run carries checkSuiteId (its check suite; null when the payload has none),
* headBranch (head_branch of that suite, read from GET /commits/{sha}/check-suites;
* null when unknown), appSlug, startedAt, completedAt
* @property {(checkRunId: number) => Promise<import("./classify.mjs").Annotation[]>} listCheckRunAnnotations
* @property {(sha: string) => Promise<import("./eligibility.mjs").CommitStatus[]>} listCommitStatuses newest first
* @property {(sha: string, s: {state: string, context: string, description: string,
* targetUrl?: string}) => Promise<void>} createCommitStatus
*
* — merge (squash-api landing) —
* @property {(n: number, opts: {method: "squash"|"merge", sha: string, commitTitle?: string,
* commitMessage?: string}) => Promise<{merged: boolean, sha: string|null,
* status: number, message: string}>} mergePull 405/409 → merged:false (no throw).
* The PUT is never replayed blindly: after a 5xx / network error / timeout, and on
* 405/409, GET /pulls/{n} decides — merged with head === sha → merged:true (the
* earlier attempt landed); otherwise a 5xx / network error is retried with backoff.
*
* — contents API (state store CAS) —
* @property {(path: string, ref: string) => Promise<{content: string, sha: string}|null>} getFileContent
* @property {(path: string, ref: string) => Promise<{name: string, path: string, type: string,
* sha: string}[]>} listDirectory [] when the directory or the ref is absent
* @property {(path: string, input: {branch: string, message: string, content: string,
* sha?: string|null}) => Promise<{ok: true, sha: string}|{ok: false,
* conflict: true}>} putFileContent 409/422 sha mismatch → conflict
* @property {(branch: string, files: {path: string, content: string}[], message: string)
* => Promise<string|null>} createOrphanBranch commit sha; null if branch exists
*
* — refs / actions / rulesets —
* @property {(prefix: string) => Promise<{ref: string, sha: string}[]>} listMatchingBranches
* (GET /git/matching-refs/heads/<prefix>; ref = branch name without refs/heads/)
* @property {(branch: string) => Promise<void>} deleteBranch refuses names outside
* contracts.CANDIDATE_PREFIX; 404/422 = already gone
* @property {(q: {branch?: string, headSha?: string, event?: string})
* => Promise<WorkflowRun[]>} listWorkflowRuns GET /actions/runs filtered by branch /
* head_sha / event (at most 10 pages)
* @property {(workflowFile: string, q: {branch?: string, event?: string})
* => Promise<WorkflowRun[]>} listWorkflowFileRuns runs of ONE workflow file, newest
* first (first page only: callers look for runs they just triggered)
* @property {(workflowFile: string, ref: string, inputs: object) => Promise<void>} dispatchWorkflow
* @property {(branch: string) => Promise<{type: string, rulesetId: number|null}[]>} getBranchRules
* the ACTIVE rules that apply to a branch name (GET /rules/branches/<branch>, every
* page, every ruleset that matches the name, organization ones included); GitHub
* matches by name pattern, so a branch that does not exist yet gets its rules too
* @property {() => Promise<object[]>} listRulesets
* @property {(id: number) => Promise<object>} getRuleset
* @property {(body: object) => Promise<object>} createRuleset
* @property {(id: number, body: object) => Promise<object>} updateRuleset
*/
const DEFAULT_API_URL = "https://api.github.com";
const DEFAULT_USER_AGENT = "omni-queue";
const API_VERSION = "2022-11-28";
const PER_PAGE = 100;
const MAX_PAGES = 50;
const MAX_STATUS_DESCRIPTION = 140;
const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// ───────────────────────────── helpers (exported for tests) ─────────────────────────────
/**
* Parse an RFC 8288 Link header into {rel: url}.
* @param {string|null|undefined} header
* @returns {Object<string, string>}
*/
export function parseLinkHeader(header) {
const out = {};
for (const part of String(header ?? "").split(",")) {
const m = /<([^>]+)>\s*;\s*rel="([^"]+)"/.exec(part);
if (m) for (const rel of m[2].split(/\s+/)) out[rel] = m[1];
}
return out;
}
/**
* True when a 403/429 is a (primary or secondary) rate limit and thus worth retrying.
* @param {number} status @param {Headers|null} headers @param {any} data
*/
export function isRateLimited(status, headers, data) {
if (status === 429) return true;
if (status !== 403) return false;
if (headers?.get("retry-after")) return true;
if (headers?.get("x-ratelimit-remaining") === "0") return true;
return /rate limit/i.test(String(data?.message ?? ""));
}
/**
* Delay before retry `attempt` (0-based): Retry-After seconds, else the primary-limit reset
* time, else exponential backoff. Only the local backoff is capped at maxDelayMs: a delay the
* server asked for is never shortened, so a result above maxDelayMs means "do not retry now".
* @param {number} attempt
* @param {Headers|null} headers
* @param {{baseDelayMs: number, maxDelayMs: number, nowMs: number}} opts
*/
export function retryDelayMs(attempt, headers, { baseDelayMs, maxDelayMs, nowMs }) {
const clamp = (ms) => Math.min(maxDelayMs, Math.max(0, Math.round(ms)));
const server = (ms) => Math.max(0, Math.round(ms));
const retryAfter = headers?.get("retry-after")?.trim();
if (retryAfter && /^\d+$/.test(retryAfter)) return server(Number(retryAfter) * 1000);
if (headers?.get("x-ratelimit-remaining") === "0") {
const reset = Number(headers.get("x-ratelimit-reset"));
if (Number.isFinite(reset) && reset > 0) return server(reset * 1000 - nowMs + 1000);
}
return clamp(baseDelayMs * 2 ** attempt);
}
/** "a/b c" → "a/b%20c": encodes each path segment, keeps the separators. */
export function encodePath(path) {
return String(path)
.split("/")
.map((segment) => encodeURIComponent(segment))
.join("/");
}
const labelNames = (labels) =>
(labels ?? []).map((l) => (typeof l === "string" ? l : l?.name)).filter(Boolean);
/** @returns {PullSummary} */
export function normalizePullSummary(raw) {
return {
number: raw.number,
draft: raw.draft === true,
baseRef: raw.base?.ref ?? "",
headSha: raw.head?.sha ?? "",
headRef: raw.head?.ref ?? "",
headRepoFullName: raw.head?.repo?.full_name ?? null,
title: String(raw.title ?? ""),
author: raw.user?.login ?? "",
labels: labelNames(raw.labels),
createdAt: raw.created_at ?? "",
updatedAt: raw.updated_at ?? "",
};
}
/** @returns {Pull} */
export function normalizePull(raw) {
return {
...normalizePullSummary(raw),
state: raw.state === "closed" ? "closed" : "open",
merged: raw.merged === true || Boolean(raw.merged_at),
mergeable: typeof raw.mergeable === "boolean" ? raw.mergeable : null,
mergeableState: String(raw.mergeable_state ?? "unknown"),
body: String(raw.body ?? ""),
changedFiles: Number.isSafeInteger(raw.changed_files) ? raw.changed_files : null,
};
}
/**
* Normalize one issue timeline event. Server-side `created_at`/`actor` are trusted; `committed`
* events carry only git dates (author/committer), which are forgeable, so createdAt is null.
* @returns {import("./eligibility.mjs").TimelineEvent}
*/
export function normalizeTimelineEvent(raw) {
const event = String(raw.event ?? "");
const out = {
event,
actor: raw.actor?.login ?? null,
createdAt: event === "committed" ? null : (raw.created_at ?? null),
};
if ((event === "labeled" || event === "unlabeled") && raw.label?.name) out.label = raw.label.name;
const sha = raw.commit_id ?? (event === "committed" ? raw.sha : undefined);
if (sha) out.sha = sha;
return out;
}
/**
* @param {any} raw check run payload
* @param {Map<number, string|null>} [branchBySuite] check_suite.id → check suite head_branch
* (GET /commits/{sha}/check-suites); headBranch is null when the suite is unknown
* @returns {import("./checks.mjs").CheckRun}
*/
export function normalizeCheckRun(raw, branchBySuite) {
const branch = branchBySuite?.get(raw.check_suite?.id);
return {
id: raw.id,
name: String(raw.name ?? ""),
status: String(raw.status ?? ""),
conclusion: raw.conclusion ?? null,
startedAt: raw.started_at ?? null,
completedAt: raw.completed_at ?? null,
htmlUrl: raw.html_url ?? null,
appSlug: raw.app?.slug ?? null,
headBranch: typeof branch === "string" && branch ? branch : null,
checkSuiteId: raw.check_suite?.id ?? null,
output: {
title: raw.output?.title ?? null,
summary: raw.output?.summary ?? null,
text: raw.output?.text ?? null,
},
};
}
/** @returns {import("./classify.mjs").Annotation} */
export function normalizeAnnotation(raw) {
return {
path: raw.path ?? null,
title: raw.title ?? null,
message: String(raw.message ?? ""),
level: String(raw.annotation_level ?? raw.level ?? "notice"),
};
}
/** @returns {import("./eligibility.mjs").CommitStatus} */
export function normalizeStatus(raw) {
return {
context: String(raw.context ?? ""),
state: raw.state,
creator: raw.creator?.login ?? null,
description: String(raw.description ?? ""),
createdAt: raw.created_at ?? "",
targetUrl: raw.target_url ?? null,
};
}
export function normalizeIssue(raw) {
return {
number: raw.number,
title: String(raw.title ?? ""),
body: String(raw.body ?? ""),
labels: labelNames(raw.labels),
state: String(raw.state ?? ""),
updatedAt: raw.updated_at ?? "",
};
}
export function normalizeComment(raw) {
return {
id: raw.id,
body: String(raw.body ?? ""),
author: raw.user?.login ?? "",
createdAt: raw.created_at ?? "",
};
}
/** @returns {WorkflowRun} */
export function normalizeWorkflowRun(raw) {
return {
id: raw.id,
name: String(raw.name ?? ""),
status: String(raw.status ?? ""),
conclusion: raw.conclusion ?? null,
htmlUrl: raw.html_url ?? "",
headSha: raw.head_sha ?? "",
headBranch: typeof raw.head_branch === "string" && raw.head_branch ? raw.head_branch : null,
event: String(raw.event ?? ""),
checkSuiteId: raw.check_suite_id ?? null,
};
}
/** Items of a list response: the array itself, or the array inside a {total_count, …} envelope. */
function unwrapItems(data) {
if (Array.isArray(data)) return data;
if (data && typeof data === "object") {
for (const [key, value] of Object.entries(data)) {
if (key !== "total_count" && Array.isArray(value)) return value;
}
}
return [];
}
function errorMessage(data, fallback) {
if (data && typeof data === "object") {
const parts = [String(data.message ?? fallback)];
if (Array.isArray(data.errors)) {
for (const e of data.errors.slice(0, 5)) {
parts.push(typeof e === "string" ? e : String(e?.message ?? e?.code ?? ""));
}
}
return parts.filter(Boolean).join("; ").slice(0, 1000);
}
return String(data || fallback).slice(0, 1000);
}
// ───────────────────────────── client ─────────────────────────────
/**
* @param {{token: string, repository: string, apiUrl?: string, fetchImpl?: typeof fetch,
* sleep?: (ms: number) => Promise<void>, log?: (msg: string) => void,
* maxRetries?: number, userAgent?: string, baseDelayMs?: number, maxDelayMs?: number,
* nowMs?: () => number, botLogin?: string, requestTimeoutMs?: number}} options
* baseDelayMs/maxDelayMs/nowMs tune the backoff (tests); maxDelayMs (default 120 s) is also
* the longest Retry-After / rate-limit reset wait honored: a longer one throws at once;
* botLogin, when set, makes commentOnce
* count only markers in comments authored by that login (a third party cannot pre-post one);
* requestTimeoutMs (default 30 s) aborts a hung request, which then counts as a network error.
* @returns {GitHubClient}
*/
export function createGitHubClient(options) {
const {
token,
repository,
apiUrl = DEFAULT_API_URL,
fetchImpl = globalThis.fetch,
sleep = defaultSleep,
log = () => {},
maxRetries = 4,
userAgent = DEFAULT_USER_AGENT,
baseDelayMs = 1000,
maxDelayMs = 120_000,
nowMs = () => Date.now(),
botLogin,
requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
} = options ?? {};
if (!token || typeof token !== "string") throw new Error("createGitHubClient: token required");
const m = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(String(repository ?? ""));
if (!m) throw new Error(`createGitHubClient: invalid repository ${JSON.stringify(repository)}`);
const [, owner, repo] = m;
const apiBase = String(apiUrl).replace(/\/+$/, "");
const apiOrigin = new URL(apiBase).origin;
const repoPath = `/repos/${owner}/${repo}`;
const redact = (text) =>
String(text ?? "")
.split(token)
.join("***");
/** Resolve a path (relative to the API root) or a pagination URL on the same origin. */
function resolveUrl(path, query) {
let url;
if (/^https?:\/\//i.test(path)) {
url = new URL(path);
if (url.origin !== apiOrigin)
throw new Error(`refusing to call foreign origin ${url.origin}`);
} else {
url = new URL(`${apiBase}${path.startsWith("/") ? "" : "/"}${path}`);
}
for (const [key, value] of Object.entries(query ?? {})) {
if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
}
return url;
}
async function request(method, path, opts = {}) {
const { query, body, accept, allowStatuses = [], retryServerErrors = true } = opts;
const url = resolveUrl(path, query);
const shown = `${url.pathname}${url.search}`;
const headers = {
Authorization: `Bearer ${token}`,
Accept: accept ?? "application/vnd.github+json",
"X-GitHub-Api-Version": API_VERSION,
"User-Agent": userAgent,
};
let payload;
if (body !== undefined) {
headers["Content-Type"] = "application/json";
payload = JSON.stringify(body);
}
for (let attempt = 0; ; attempt++) {
let res;
let text;
try {
// The signal also bounds reading the body: a stalled response cannot hold the tick.
const signal = AbortSignal.timeout(requestTimeoutMs);
res = await fetchImpl(url.href, { method, headers, body: payload, signal });
text = await res.text();
} catch (error) {
const timedOut = error?.name === "TimeoutError" || error?.name === "AbortError";
const message = timedOut
? `timed out after ${requestTimeoutMs} ms`
: redact(error?.message ?? error);
if (attempt >= maxRetries || !retryServerErrors) {
throw new GitHubError(0, method, shown, `network: ${message}`);
}
const delay = retryDelayMs(attempt, null, { baseDelayMs, maxDelayMs, nowMs: nowMs() });
log(`${method} ${shown} → network error (${message}); retry in ${delay} ms`);
await sleep(delay);
continue;
}
let data = null;
if (text) {
try {
data = JSON.parse(text);
} catch {
data = text;
}
}
const status = res.status;
if (status < 400 || allowStatuses.includes(status)) {
return { status, data, headers: res.headers };
}
// A rate-limited request was not processed, so it is always safe to replay.
const retryable =
(status >= 500 && retryServerErrors) || isRateLimited(status, res.headers, data);
if (retryable && attempt < maxRetries) {
const delay = retryDelayMs(attempt, res.headers, {
baseDelayMs,
maxDelayMs,
nowMs: nowMs(),
});
if (delay > maxDelayMs) {
// The server asked for a longer wait than one tick should sleep: retrying earlier only
// adds rate-limit pressure. Fail now; the next tick tries again.
const wait = Math.ceil(delay / 1000);
const why = redact(errorMessage(data, res.statusText));
throw new GitHubError(
status,
method,
shown,
`retry after ${wait} s (over the ${maxDelayMs} ms retry cap): ${why}`
);
}
log(`${method} ${shown} → ${status}; retry ${attempt + 1}/${maxRetries} in ${delay} ms`);
await sleep(delay);
continue;
}
throw new GitHubError(status, method, shown, redact(errorMessage(data, res.statusText)));
}
}
async function paginate(path, query = {}, { maxPages = MAX_PAGES } = {}) {
const items = [];
let next = path;
let q = { per_page: PER_PAGE, ...query };
for (let page = 0; next; page++) {
if (page >= maxPages) {
log(`paginate ${path}: stopped after ${maxPages} pages`);
break;
}
const res = await request("GET", next, { query: q });
items.push(...unwrapItems(res.data));
next = parseLinkHeader(res.headers.get("link")).next ?? null;
q = undefined; // the next URL already carries every query parameter
}
return items;
}
const r = (suffix) => `${repoPath}${suffix}`;
const assertNumber = (n) => {
if (!Number.isSafeInteger(n) || n <= 0) throw new Error(`invalid issue/PR number: ${n}`);
};
const assertSha = (sha) => {
if (!isSha(sha)) throw new Error(`invalid sha: ${sha}`);
};
const toBase64 = (s) => Buffer.from(String(s), "utf8").toString("base64");
const fromBase64 = (s) => Buffer.from(String(s).replace(/\s+/g, ""), "base64").toString("utf8");
async function listIssueComments(n) {
assertNumber(n);
return (await paginate(r(`/issues/${n}/comments`))).map(normalizeComment);
}
async function listPullFileManifest(n) {
assertNumber(n);
const files = new Set();
const entries = await paginate(r(`/pulls/${n}/files`));
for (const f of entries) {
if (f.filename) files.add(f.filename);
if (f.previous_filename) files.add(f.previous_filename);
}
return { files: [...files], listed: entries.length };
}
async function createIssueComment(n, body) {
assertNumber(n);
const res = await request("POST", r(`/issues/${n}/comments`), { body: { body } });
return { id: res.data?.id };
}
async function deleteIssueComment(commentId) {
assertNumber(commentId);
await request("DELETE", r(`/issues/comments/${commentId}`), { allowStatuses: [404] });
}
/** Raw PR payload → a merge result when it is merged at `sha`, else null. */
async function mergedAt(n, sha) {
const raw = (await request("GET", r(`/pulls/${n}`))).data;
const merged = raw?.merged === true || Boolean(raw?.merged_at);
if (!merged || raw?.head?.sha !== sha) return null;
return {
merged: true,
sha: raw.merge_commit_sha ?? null,
status: 200,
message: "already merged (confirmed by GET /pulls)",
};
}
return {
owner,
repo,
request,
paginate,
async listOpenPulls({ base } = {}) {
const query = { state: "open", ...(base ? { base } : {}) };
return (await paginate(r("/pulls"), query)).map(normalizePullSummary);
},
async getPull(n) {
assertNumber(n);
return normalizePull((await request("GET", r(`/pulls/${n}`))).data);
},
async listPullFiles(n) {
return (await listPullFileManifest(n)).files;
},
listPullFileManifest,
async listIssueTimeline(n) {
assertNumber(n);
return (await paginate(r(`/issues/${n}/timeline`))).map(normalizeTimelineEvent);
},
async addLabels(n, labels) {
assertNumber(n);
await request("POST", r(`/issues/${n}/labels`), { body: { labels } });
},
async removeLabel(n, label) {
assertNumber(n);
await request("DELETE", r(`/issues/${n}/labels/${encodeURIComponent(label)}`), {
allowStatuses: [404],
});
},
listIssueComments,
createIssueComment,
deleteIssueComment,
async commentOnce(n, key, body) {
const marker = commentMarker(key);
const ours = (c) => c.body.includes(marker) && (!botLogin || c.author === botLogin);
if ((await listIssueComments(n)).some(ours)) return { posted: false };
const { id } = await createIssueComment(n, `${body}\n\n${marker}`);
// Read-then-write is not atomic: another writer may have posted the same marker meanwhile,
// and each POST replayed after a 5xx may have left one more copy. The lowest id wins; drop
// every newer copy written by our login (never a comment of someone else).
const found = (await listIssueComments(n)).filter(ours).sort((a, b) => a.id - b.id);
const winner = found[0]?.id;
if (winner === undefined || id === undefined) return { posted: true };
const self = botLogin ?? found.find((c) => c.id === id)?.author;
const extra = found.filter((c) => c.id !== winner && (c.id === id || c.author === self));
for (const c of extra) await deleteIssueComment(c.id);
if (extra.length) {
const ids = extra.map((c) => c.id).join(", ");
log(`commentOnce #${n} ${key}: duplicate(s) ${ids} removed (kept ${winner})`);
}
return { posted: winner === id };
},
async listIssues({ labels, state = "open" } = {}) {
const query = { state, ...(labels?.length ? { labels: labels.join(",") } : {}) };
return (await paginate(r("/issues"), query))
.filter((i) => !i.pull_request)
.map(normalizeIssue);
},
async createIssue({ title, body, labels }) {
const res = await request("POST", r("/issues"), {
body: { title, body, ...(labels ? { labels } : {}) },
});
return { number: res.data?.number };
},
async updateIssue(n, patch) {
assertNumber(n);
await request("PATCH", r(`/issues/${n}`), { body: patch });
},
async getBranchSha(branch) {
const res = await request("GET", r(`/git/ref/heads/${encodePath(branch)}`), {
allowStatuses: [404],
});
if (res.status === 404) return null;
// A prefix match returns an array (older API behavior): only an exact ref counts.
if (Array.isArray(res.data)) return null;
return res.data?.object?.sha ?? null;
},
async getCommit(sha) {
assertSha(sha);
const { data } = await request("GET", r(`/git/commits/${sha}`));
return {
sha: data.sha,
treeSha: data.tree?.sha ?? "",
parents: (data.parents ?? []).map((p) => p.sha),
message: String(data.message ?? ""),
};
},
async listCheckRuns(sha) {
assertSha(sha);
const runs = await paginate(r(`/commits/${sha}/check-runs`), { filter: "all" });
if (!runs.length) return [];
// A check run carries only its suite id; the suite says which branch push started it, so
// the tick reads only the runs of the candidate ref when one SHA lives on several refs.
const branchBySuite = new Map();
for (const suite of await paginate(r(`/commits/${sha}/check-suites`))) {
if (suite?.id !== undefined) branchBySuite.set(suite.id, suite.head_branch ?? null);
}
return runs.map((run) => normalizeCheckRun(run, branchBySuite));
},
async listCheckRunAnnotations(checkRunId) {
assertNumber(checkRunId);
return (await paginate(r(`/check-runs/${checkRunId}/annotations`))).map(normalizeAnnotation);
},
async listCommitStatuses(sha) {
assertSha(sha);
const statuses = (await paginate(r(`/commits/${sha}/statuses`))).map(normalizeStatus);
// Newest first; the sort is stable, so equal timestamps keep the API order.
return statuses
.map((s, i) => ({ s, i, t: Date.parse(s.createdAt) || 0 }))
.sort((a, b) => b.t - a.t || a.i - b.i)
.map(({ s }) => s);
},
async createCommitStatus(sha, { state, context, description, targetUrl }) {
assertSha(sha);
await request("POST", r(`/statuses/${sha}`), {
body: {
state,
context,
description: String(description ?? "").slice(0, MAX_STATUS_DESCRIPTION),
...(targetUrl ? { target_url: targetUrl } : {}),
},
});
},
async mergePull(n, { method, sha, commitTitle, commitMessage }) {
assertNumber(n);
assertSha(sha);
const body = {
merge_method: method,
sha,
...(commitTitle !== undefined ? { commit_title: commitTitle } : {}),
...(commitMessage !== undefined ? { commit_message: commitMessage } : {}),
};
for (let attempt = 0; ; attempt++) {
let res;
try {
// Never replayed by request(): a 5xx may hide a merge that did happen.
res = await request("PUT", r(`/pulls/${n}/merge`), {
body,
allowStatuses: [405, 409],
retryServerErrors: false,
});
} catch (error) {
const ambiguous =
error instanceof GitHubError && (error.status === 0 || error.status >= 500);
if (!ambiguous) throw error;
const confirmed = await mergedAt(n, sha);
if (confirmed) return confirmed;
if (attempt >= maxRetries) throw error;
const delay = retryDelayMs(attempt, null, { baseDelayMs, maxDelayMs, nowMs: nowMs() });
log(`mergePull #${n}: ${error.message}; not merged, retry in ${delay} ms`);
await sleep(delay);
continue;
}
if (res.status === 405 || res.status === 409) {
// "not mergeable" also answers a PR that an earlier (ambiguous) attempt merged.
const confirmed = await mergedAt(n, sha);
if (confirmed) return confirmed;
}
return {
merged: res.status < 300 && res.data?.merged === true,
sha: res.status < 300 ? (res.data?.sha ?? null) : null,
status: res.status,
message: String(res.data?.message ?? ""),
};
}
},
async getFileContent(path, ref) {
const res = await request("GET", r(`/contents/${encodePath(path)}`), {
query: { ref },
allowStatuses: [404],
});
if (res.status === 404) return null;
const data = res.data;
if (!data || Array.isArray(data) || data.type !== "file") {
throw new Error(`getFileContent: ${path} is not a file`);
}
if (data.encoding === "base64" && typeof data.content === "string") {
return { content: fromBase64(data.content), sha: data.sha };
}
// Files over 1 MB come back without inline content: read the blob instead.
const blob = (await request("GET", r(`/git/blobs/${data.sha}`))).data;
return { content: fromBase64(blob.content), sha: data.sha };
},
async listDirectory(path, ref) {
const res = await request("GET", r(`/contents/${encodePath(path)}`), {
query: { ref },
allowStatuses: [404],
});
if (res.status === 404 || !Array.isArray(res.data)) return [];
return res.data.map((e) => ({
name: String(e.name ?? ""),
path: String(e.path ?? ""),
type: String(e.type ?? ""),
sha: String(e.sha ?? ""),
}));
},
async putFileContent(path, { branch, message, content, sha }) {
const res = await request("PUT", r(`/contents/${encodePath(path)}`), {
body: {
message,
content: toBase64(content),
branch,
...(sha ? { sha } : {}),
},
allowStatuses: [409, 422],
});
if (res.status === 409) return { ok: false, conflict: true };
if (res.status === 422) {
const message422 = errorMessage(res.data, "Unprocessable Entity");
if (/\bsha\b/i.test(message422)) return { ok: false, conflict: true };
throw new GitHubError(422, "PUT", `${r("/contents/")}${path}`, redact(message422));
}
return { ok: true, sha: res.data?.content?.sha };
},
async createOrphanBranch(branch, files, message) {
const tree = [];
for (const file of files) {
const blob = await request("POST", r("/git/blobs"), {
body: { content: toBase64(file.content), encoding: "base64" },
});
tree.push({ path: file.path, mode: "100644", type: "blob", sha: blob.data.sha });
}
const treeRes = await request("POST", r("/git/trees"), { body: { tree } });
const commit = await request("POST", r("/git/commits"), {
body: { message, tree: treeRes.data.sha, parents: [] },
});
const ref = await request("POST", r("/git/refs"), {
body: { ref: `refs/heads/${branch}`, sha: commit.data.sha },
allowStatuses: [422],
});
if (ref.status === 422) {
const msg = errorMessage(ref.data, "Unprocessable Entity");
if (/already exists/i.test(msg)) return null;
throw new GitHubError(422, "POST", r("/git/refs"), redact(msg));
}
return commit.data.sha;
},
async listMatchingBranches(prefix) {
const refs = await paginate(r(`/git/matching-refs/heads/${encodePath(prefix)}`));
return refs.map((x) => ({
ref: String(x.ref ?? "").replace(/^refs\/heads\//, ""),
sha: x.object?.sha ?? "",
}));
},
async deleteBranch(branch) {
const name = String(branch ?? "");
if (
!name.startsWith(CANDIDATE_PREFIX) ||
name.length === CANDIDATE_PREFIX.length ||
name.split("/").some((s) => s === ".." || s === "")
) {
throw new Error(`deleteBranch: refusing to delete ${JSON.stringify(name)}`);
}
await request("DELETE", r(`/git/refs/heads/${encodePath(name)}`), {
allowStatuses: [404, 422],
});
},
async listWorkflowRuns({ branch, headSha, event } = {}) {
const query = {
...(branch ? { branch } : {}),
...(headSha ? { head_sha: headSha } : {}),
...(event ? { event } : {}),
};
const runs = await paginate(r("/actions/runs"), query, { maxPages: 10 });
return runs.map(normalizeWorkflowRun);
},
async listWorkflowFileRuns(workflowFile, { branch, event } = {}) {
const query = { ...(branch ? { branch } : {}), ...(event ? { event } : {}) };
const path = r(`/actions/workflows/${encodeURIComponent(workflowFile)}/runs`);
const runs = await paginate(path, query, { maxPages: 1 });
return runs.map(normalizeWorkflowRun);
},
async dispatchWorkflow(workflowFile, ref, inputs) {
await request(
"POST",
r(`/actions/workflows/${encodeURIComponent(workflowFile)}/dispatches`),
{
body: { ref, inputs },
}
);
},
async getBranchRules(branch) {
const name = String(branch ?? "");
if (!name) throw new Error("getBranchRules: a branch name is required");
const rules = await paginate(r(`/rules/branches/${encodePath(name)}`));
return rules.map((rule) => ({
type: String(rule?.type ?? ""),
rulesetId: rule?.ruleset_id ?? null,
}));
},
async listRulesets() {
return paginate(r("/rulesets"));
},
async getRuleset(id) {
assertNumber(id);
return (await request("GET", r(`/rulesets/${id}`))).data;
},
async createRuleset(body) {
return (await request("POST", r("/rulesets"), { body })).data;
},
async updateRuleset(id, body) {
assertNumber(id);
return (await request("PUT", r(`/rulesets/${id}`), { body })).data;
},
};
}