@cldmv/gh-broker 0.7.0 → 0.9.0

package/src/verbs/issue_labels.ts

@@ -1,329 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/issue_labels.ts
- *	@Date: 2026-10-16T17:14:34-07:00 (1792196074)
- *	@Author: Nate Corcoran <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-16T17:25:33-07:00 (1792196733)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-import type { Octokit } from "@octokit/core";
-
-/**
- * Custom verb: issue_labels — edit the labels on one issue or PR without replacing the
- * whole set.
- *
- * Why a custom verb: the hosted MCP's only label write path is `issue_write`, whose
- * `labels` argument REPLACES every label on the issue. Changing one status label that way
- * silently drops the rest (CLDMV/gh-broker#117), and reading the set then writing the
- * merged set back loses any label someone else adds in between. GitHub's REST API has
- * per-label endpoints that touch only the labels named, so this verb drives those:
- *
- *  - `add`    → POST   /repos/{o}/{r}/issues/{n}/labels         (server-side append)
- *  - `remove` → DELETE /repos/{o}/{r}/issues/{n}/labels/{name}  (one call per label)
- *  - `swap`   → a POST of `to`, then a DELETE for every current label starting with `prefix`
- *  - `set`    → PUT    /repos/{o}/{r}/issues/{n}/labels         (explicit full replace, never empty)
- *
- * Writes run create → add → remove, so a call that fails part-way never leaves the issue
- * with fewer labels than it should have (a swap whose add is rate-limited keeps its old
- * status label). The error then names exactly what was applied and what was not.
- *
- * Issues and PRs share these endpoints, so a PR number works the same way.
- *
- * Label names to ADD (via `add`, `swap.to` or `set`) must already exist in the repo —
- * a typo would otherwise create a stray label silently. `create_missing: true` creates
- * them instead. Every add-side name is checked before any write, so a refused call
- * changes nothing.
- *
- * GitHub label names are case-insensitive; all matching here (existence, swap prefix,
- * add/remove overlap) is too, and the repo's own spelling is what gets written.
- */
-
-export interface IssueLabelsSwap {
-	/** Every current label starting with this (e.g. "status: ") is removed. */
-	prefix: string;
-	/** Then these are added. One label or several. */
-	to: string | string[];
-}
-
-export interface IssueLabelsInput {
-	owner: string;
-	repo: string;
-	/** Issue or pull-request number. */
-	issue_number: number;
-	add?: string | string[];
-	remove?: string | string[];
-	swap?: IssueLabelsSwap;
-	/** Replace the whole set. Cannot be combined with add/remove/swap. */
-	set?: string | string[];
-	/** Create add-side labels that don't exist in the repo instead of refusing. */
-	create_missing?: boolean;
-	/** Hex color (no #) for labels created via create_missing. */
-	color?: string;
-}
-
-export interface IssueLabelsResult {
-	issue: string;
-	/** The issue's label set after the call. */
-	labels: string[];
-	added: string[];
-	removed: string[];
-	created: string[];
-}
-
-const DEFAULT_COLOR = "ededed";
-/** GitHub's own per-issue label limit; also bounds the requests one call can make. */
-export const MAX_LABELS = 100;
-const INPUT_KEYS = new Set(["owner", "repo", "issue_number", "add", "remove", "swap", "set", "create_missing", "color"]);
-const SWAP_KEYS = new Set(["prefix", "to"]);
-
-const fail = (msg: string): never => {
-	throw new Error(`issue_labels: ${msg}`);
-};
-
-function toList(v: unknown, field: string): string[] {
-	if (v === undefined) return [];
-	const arr = Array.isArray(v) ? v : [v];
-	if (arr.length === 0) fail(`"${field}" is empty — pass at least one label name`);
-	for (const x of arr) {
-		if (typeof x !== "string" || !x.trim()) fail(`"${field}" must be a label name or a list of label names`);
-	}
-	const list = dedupe((arr as string[]).map((x) => x.trim()));
-	if (list.length > MAX_LABELS) fail(`"${field}" has ${list.length} labels — at most ${MAX_LABELS} per call`);
-	return list;
-}
-
-const key = (s: string): string => s.toLowerCase();
-
-function dedupe(list: string[]): string[] {
-	const seen = new Set<string>();
-	return list.filter((x) => (seen.has(key(x)) ? false : (seen.add(key(x)), true)));
-}
-
-function statusOf(err: unknown): number | undefined {
-	return (err as { status?: number })?.status;
-}
-
-const fmt = (list: string[]): string => `[${list.join(", ")}]`;
-
-type Label = { name: string };
-const names = (data: unknown): string[] => (Array.isArray(data) ? (data as Label[]).map((l) => l.name) : []);
-
-/**
- * The handler is the real contract: the MCP server does not validate against the
- * advertised inputSchema, so every key and type is checked here, before any request.
- */
-function validate(input: unknown) {
-	if (typeof input !== "object" || input === null || Array.isArray(input)) fail("arguments must be an object");
-	const a = input as Record<string, unknown>;
-	const unknown = Object.keys(a).filter((k) => !INPUT_KEYS.has(k));
-	if (unknown.length) fail(`unknown argument(s): ${unknown.join(", ")} — expected ${[...INPUT_KEYS].join(", ")}`);
-	if (typeof a.owner !== "string" || !a.owner.trim()) fail('"owner" must be a non-empty string');
-	if (typeof a.repo !== "string" || !a.repo.trim()) fail('"repo" must be a non-empty string');
-	if (typeof a.issue_number !== "number" || !Number.isInteger(a.issue_number) || a.issue_number <= 0) fail('"issue_number" must be a positive integer');
-	if (a.create_missing !== undefined && typeof a.create_missing !== "boolean") fail('"create_missing" must be a boolean');
-	if (a.color !== undefined && (typeof a.color !== "string" || !/^#?[0-9a-f]{6}$/i.test(a.color))) fail('"color" must be a 6-digit hex color, e.g. "ededed"');
-
-	const add = toList(a.add, "add");
-	const remove = toList(a.remove, "remove");
-	const set = a.set === undefined ? undefined : toList(a.set, "set");
-	let swapTo: string[] = [];
-	let swapPrefix: string | undefined;
-	if (a.swap !== undefined) {
-		const sw = a.swap as Record<string, unknown>;
-		if (typeof sw !== "object" || sw === null || Array.isArray(sw)) fail('"swap" must be an object { prefix, to }');
-		const extra = Object.keys(sw).filter((k) => !SWAP_KEYS.has(k));
-		if (extra.length) fail(`unknown "swap" key(s): ${extra.join(", ")} — expected prefix, to`);
-		if (typeof sw.prefix !== "string" || !sw.prefix) fail('"swap.prefix" is required');
-		if (sw.to === undefined) fail('"swap.to" needs at least one label');
-		swapPrefix = sw.prefix as string;
-		swapTo = toList(sw.to, "swap.to");
-	}
-
-	if (set !== undefined && (add.length || remove.length || swapPrefix !== undefined)) {
-		fail('"set" replaces the whole label set and cannot be combined with add/remove/swap');
-	}
-	if (set === undefined && !add.length && !remove.length && swapPrefix === undefined) fail("nothing to do — pass add, remove, swap or set");
-	const addSide = dedupe([...add, ...swapTo]);
-	if (addSide.length > MAX_LABELS) fail(`${addSide.length} labels to add — at most ${MAX_LABELS} per call`);
-	const removeKeys = new Set(remove.map(key));
-	const clash = addSide.filter((l) => removeKeys.has(key(l)));
-	if (clash.length) fail(`label(s) both added and removed: ${clash.join(", ")}`);
-
-	return {
-		owner: a.owner as string,
-		repo: a.repo as string,
-		issue_number: a.issue_number as number,
-		remove,
-		set,
-		swapPrefix,
-		addSide,
-		createMissing: a.create_missing === true,
-		color: ((a.color as string | undefined) ?? DEFAULT_COLOR).replace(/^#/, "")
-	};
-}
-
-export async function issueLabels(octokit: Octokit, input: IssueLabelsInput): Promise<IssueLabelsResult> {
-	const { owner, repo, issue_number, remove, set, swapPrefix, addSide, createMissing, color } = validate(input);
-	const issue = `${owner}/${repo}#${issue_number}`;
-	const base = { owner, repo, issue_number };
-	const readLabels = async (): Promise<string[]> =>
-		names((await octokit.request("GET /repos/{owner}/{repo}/issues/{issue_number}/labels", { ...base, per_page: MAX_LABELS })).data);
-
-	// 0. The current set: needed for swap's prefix matches, for the spelling of removals and
-	//    for reporting what changed. It also fails a wrong issue number (404) before anything
-	//    is written or created.
-	const before = await readLabels();
-	const beforeKeys = new Set(before.map(key));
-	const onIssue = (n: string): string | undefined => before.find((l) => key(l) === key(n));
-
-	// 1. Resolve every add-side label against the repo before writing anything.
-	const toResolve = set ?? addSide;
-	const resolved: string[] = [];
-	const missing: string[] = [];
-	for (const name of toResolve) {
-		try {
-			const res = await octokit.request("GET /repos/{owner}/{repo}/labels/{name}", { owner, repo, name });
-			resolved.push((res.data as Label).name);
-		} catch (err) {
-			if (statusOf(err) !== 404) throw err;
-			missing.push(name);
-		}
-	}
-	if (missing.length && !createMissing) {
-		fail(`label(s) not found in ${owner}/${repo}: ${missing.join(", ")} — nothing was changed. Check the spelling (list_label), or pass create_missing: true to create them.`);
-	}
-
-	// 2. Plan the removals: only labels actually on the issue, in the issue's own spelling.
-	//    swap removes every prefix match except a label this call also adds — that one stays
-	//    put instead of being deleted and re-added.
-	const removals: string[] = [];
-	if (set === undefined) {
-		for (const n of remove) {
-			const hit = onIssue(n);
-			if (hit) removals.push(hit);
-		}
-		if (swapPrefix !== undefined) {
-			const keep = new Set(addSide.map(key));
-			const p = key(swapPrefix);
-			for (const l of before) if (key(l).startsWith(p) && !keep.has(key(l))) removals.push(l);
-		}
-	}
-	const plannedRemovals = dedupe(removals);
-
-	// 3. Writes. Order is chosen so a failure part-way never leaves the issue with LESS than
-	//    it started with plus what was asked: create, then add (POST), and removals last.
-	//    Any failure is rethrown with exactly what was applied and what was not.
-	const created: string[] = [];
-	let addedDone = false;
-	const removed: string[] = [];
-	let latest: string[] | undefined;
-	const canonical = (): string[] => [...resolved, ...created];
-	const canon = (n: string): string => canonical().find((c) => key(c) === key(n)) ?? n;
-	try {
-		for (const name of missing) {
-			const res = await octokit.request("POST /repos/{owner}/{repo}/labels", { owner, repo, name, color });
-			created.push((res.data as Label).name);
-		}
-
-		if (set !== undefined) {
-			const res = await octokit.request("PUT /repos/{owner}/{repo}/issues/{issue_number}/labels", { ...base, labels: set.map(canon) });
-			latest = names(res.data);
-			addedDone = true;
-			return result(latest, before);
-		}
-
-		if (addSide.length) {
-			const res = await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/labels", { ...base, labels: addSide.map(canon) });
-			latest = names(res.data);
-			addedDone = true;
-		}
-
-		for (const name of plannedRemovals) {
-			try {
-				const res = await octokit.request("DELETE /repos/{owner}/{repo}/issues/{issue_number}/labels/{name}", { ...base, name });
-				latest = names(res.data);
-				removed.push(name);
-			} catch (err) {
-				// Someone removed it since the read above: already the state asked for.
-				if (statusOf(err) !== 404) throw err;
-			}
-		}
-	} catch (err) {
-		const applied: string[] = [];
-		const notApplied: string[] = [];
-		const part = (label: string, done: string[], all: string[]) => {
-			const doneKeys = new Set(done.map(key));
-			if (done.length) applied.push(`${label} ${fmt(done)}`);
-			const rest = all.filter((l) => !doneKeys.has(key(l)));
-			if (rest.length) notApplied.push(`${label} ${fmt(rest)}`);
-		};
-		part("created", created, missing);
-		if (set !== undefined) part("set", addedDone ? set : [], set);
-		else part("added", addedDone ? addSide.map(canon) : [], addSide.map(canon));
-		part("removed", removed, plannedRemovals);
-		const e = new Error(
-			`issue_labels: failed part-way on ${issue}: ${(err as Error).message}. Applied: ${applied.join("; ") || "nothing"}. Not applied: ${notApplied.join("; ") || "nothing"}.`,
-			{ cause: err }
-		);
-		(e as Error & { status?: number }).status = statusOf(err);
-		throw e;
-	}
-
-	return result(latest ?? (await readLabels()), removed);
-
-	function result(labels: string[], removedFrom: string[]): IssueLabelsResult {
-		const afterKeys = new Set(labels.map(key));
-		// Only what this call asked for — a label someone else added meanwhile isn't ours to report.
-		const requested = new Set(toResolve.map(key));
-		return {
-			issue,
-			labels,
-			added: labels.filter((l) => requested.has(key(l)) && !beforeKeys.has(key(l))),
-			removed: removedFrom.filter((l) => !afterKeys.has(key(l))),
-			created
-		};
-	}
-}
-
-const labelList = (description: string) => ({
-	description,
-	oneOf: [{ type: "string" }, { type: "array", items: { type: "string" }, minItems: 1, maxItems: MAX_LABELS }]
-});
-
-/** JSON Schema advertised to the agent for issue_labels. */
-export const ISSUE_LABELS_SCHEMA = {
-	type: "object" as const,
-	required: ["owner", "repo", "issue_number"],
-	additionalProperties: false,
-	properties: {
-		owner: { type: "string", description: "repository owner (org/user login) — selects the write credential" },
-		repo: { type: "string", description: "repository name" },
-		issue_number: { type: "number", description: "issue or pull-request number" },
-		add: labelList("label(s) to add; ones already on the issue are a no-op"),
-		remove: labelList("label(s) to remove; ones the issue doesn't have are a no-op"),
-		swap: {
-			type: "object",
-			additionalProperties: false,
-			required: ["prefix", "to"],
-			description: 'remove every current label starting with prefix, then add to — e.g. { "prefix": "status: ", "to": "status: verified" }',
-			properties: {
-				prefix: { type: "string", description: 'label-name prefix, e.g. "status: "' },
-				to: labelList("label(s) to add after the prefix matches are removed")
-			}
-		},
-		set: labelList("replace the WHOLE label set with these (at least one); cannot be combined with add/remove/swap"),
-		create_missing: {
-			type: "boolean",
-			default: false,
-			description: "create add-side labels that don't exist in the repo; without it an unknown name refuses the call and nothing changes"
-		},
-		color: { type: "string", pattern: "^#?[0-9a-fA-F]{6}$", description: `6-digit hex color (with or without #) for labels created via create_missing; default ${DEFAULT_COLOR}` }
-	}
-};

package/src/verbs/link_issue.ts

@@ -1,84 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/link_issue.ts
- *	@Date: 2026-07-07T00:24:51-07:00 (1783409091)
- *	@Author: Nate Corcoran <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-02T11:30:58-07:00 (1790965858)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-import type { Octokit } from "@octokit/core";
-
-/**
- * Custom verb: link_issue — create an EXPLICIT PR→issue closing reference via the
- * `addClosingIssueReference` GraphQL mutation.
- *
- * Why a custom verb and why an App token:
- *  - The hosted GitHub MCP has no tool for PR→issue closing links (verified), so
- *    it can't be proxied — it's a direct GitHub API call.
- *  - `addClosingIssueReference` is NOT in the fine-grained-PAT GraphQL schema
- *    (GitHub returns "Field doesn't exist", distinct from a permission error). It
- *    is available to GitHub **App** tokens — exactly what CLDMV's own
- *    `sync-closing-issues` action uses. So this runs on an App-authed Octokit.
- *  - We deliberately do NOT depend on commit-message keywords for linkage.
- *
- * Uses Octokit (`octokit.graphql`) — GitHub's official SDK — not a hand-rolled fetch.
- */
-
-export interface LinkIssueInput {
-	owner: string;
-	repo: string;
-	/** pull request number */
-	pull: number;
-	/** issue number to link as a closing reference */
-	issue: number;
-}
-
-const RESOLVE_IDS = `
-	query($owner: String!, $repo: String!, $pr: Int!, $issue: Int!) {
-		repository(owner: $owner, name: $repo) {
-			pullRequest(number: $pr) { id }
-			issue(number: $issue) { id }
-		}
-	}`;
-
-const ADD_CLOSING_REF = `
-	mutation($prId: ID!, $issueId: ID!) {
-		addClosingIssueReference(input: { pullRequestId: $prId, issueId: $issueId }) {
-			pullRequest { id }
-		}
-	}`;
-
-/** Resolve node IDs, then create the closing reference. Returns the linked node IDs. */
-export async function linkIssue(octokit: Octokit, input: LinkIssueInput): Promise<{ pullRequestId: string; issueId: string }> {
-	const ids = await octokit.graphql<{
-		repository: { pullRequest: { id: string } | null; issue: { id: string } | null };
-	}>(RESOLVE_IDS, { owner: input.owner, repo: input.repo, pr: input.pull, issue: input.issue });
-
-	const pullRequestId = ids.repository.pullRequest?.id;
-	const issueId = ids.repository.issue?.id;
-	if (!pullRequestId) throw new Error(`link_issue: PR #${input.pull} not found in ${input.owner}/${input.repo}`);
-	if (!issueId) throw new Error(`link_issue: issue #${input.issue} not found in ${input.owner}/${input.repo}`);
-
-	await octokit.graphql(ADD_CLOSING_REF, { prId: pullRequestId, issueId });
-	return { pullRequestId, issueId };
-}
-
-/** JSON Schema advertised to the agent for this custom verb. */
-export const LINK_ISSUE_SCHEMA = {
-	type: "object" as const,
-	required: ["owner", "repo", "pull", "issue"],
-	additionalProperties: false,
-	properties: {
-		owner: { type: "string", description: "repository owner (org/user login)" },
-		repo: { type: "string", description: "repository name" },
-		pull: { type: "integer", description: "pull request number" },
-		issue: { type: "integer", description: "issue number to close when the PR merges to the default branch" }
-	}
-};

package/src/verbs/release-analysis.ts

@@ -1,210 +0,0 @@
-/**
- *
- *	@Project: @cldmv/gh-broker
- *	@Filename: /src/verbs/release-analysis.ts
- *	@Date: 2026-10-04T15:40:09-07:00 (1791153609)
- *	@Author: Nate Corcoran <CLDMV>
- *	@Email: <Shinrai@users.noreply.github.com>
- *	-----
- *	@Last modified by: Nate Corcoran <CLDMV> (Shinrai@users.noreply.github.com)
- *	@Last modified time: 2026-10-04T16:41:24-07:00 (1791157284)
- *	-----
- *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
- *
- */
-
-/**
- * Release-readiness analysis for report_release_prs `analyze: true`.
- *
- * This is the decision logic the release-docs skill used to walk by hand: what is still open against
- * the release's integration branch, whether an existing changelog actually covers what merged, and
- * the resulting verdict. The pure helpers (parsing, classification, coverage, verdict) are exported
- * for tests; `analyzeRelease` does the reads.
- */
-
-import type { Octokit } from "@octokit/core";
-import { CallBudget, CallBudgetExhausted, RateLimited, paginate, reqOne } from "./rest-client.ts";
-
-export type OpenPrKind = "doc" | "dependency" | "feature" | "draft";
-
-export interface OpenPr {
-	number: number;
-	title: string;
-	url: string;
-	kind: OpenPrKind;
-	/** Version named in a doc PR's title (`v1.2.3`), when it has one. */
-	version?: string;
-}
-
-export type FreshnessStatus = "current" | "minor-gap" | "stale" | "version-drift" | "thin";
-
-export interface CoverageGap {
-	number: number;
-	title: string;
-}
-
-export interface Freshness {
-	status: FreshnessStatus;
-	/** Non-doc PRs that shipped in this release (the expected coverage). */
-	expectedPrs: number;
-	/** User-facing PRs the changelog never mentions — these make it stale. */
-	missingUserFacing: CoverageGap[];
-	/** CI / chore / style / test PRs it never mentions — reported, but not stale on their own. */
-	missingInternal: CoverageGap[];
-	/** The changelog's own heading carries the release PR's current version. */
-	headingMatchesVersion: boolean;
-	/** The README What's New block names this version. */
-	readmeMentionsVersion: boolean;
-}
-
-export type ReleaseVerdict = "done" | "in-flight" | "wait" | "gray" | "write" | "update" | "inspect";
-
-export interface ReleaseAnalysis {
-	openPrs: OpenPr[];
-	/** Set only when a changelog file exists. */
-	freshness?: Freshness;
-	/** A doc PR's version differs from the release PR's current version. */
-	docVersionMismatch?: boolean;
-	verdict: ReleaseVerdict;
-	/** One line explaining the verdict. */
-	reason: string;
-}
-
-const INTERNAL_TYPES = new Set(["ci", "chore", "style", "test"]);
-
-/** `feat(scope)!: x` -> `feat`. Returns "" when the subject is not conventional. */
-export function commitType(subject: string): string {
-	const m = /^([a-z]+)(?:\([^)]*\))?!?:/i.exec(subject.trim());
-	return m ? m[1]!.toLowerCase() : "";
-}
-
-export interface ReleaseCommitPr {
-	number: number;
-	title: string;
-	type: string;
-}
-
-/**
- * PR numbers shipped by a release, from the commits of its release PR. Only the first line of each
- * commit is read: squash bodies list other PR numbers and would fake coverage. Docs PRs (they describe
- * the release rather than being part of it) and the version bump are dropped.
- */
-export function releaseCommitPrs(messages: string[]): ReleaseCommitPr[] {
-	const seen = new Map<number, ReleaseCommitPr>();
-	for (const message of messages) {
-		const subject = message.split("\n", 1)[0]!.trim();
-		let number: number | undefined;
-		let title = subject;
-		const squash = /\(#(\d+)\)\s*$/.exec(subject);
-		const merge = /^Merge pull request #(\d+)\b/.exec(subject);
-		if (squash) {
-			number = Number(squash[1]);
-			title = subject.slice(0, squash.index).trim();
-		} else if (merge) {
-			number = Number(merge[1]);
-		}
-		if (number === undefined) continue;
-		const type = commitType(title);
-		if (type === "docs" || /^chore: bump version/i.test(title)) continue;
-		if (!seen.has(number)) seen.set(number, { number, title, type });
-	}
-	return [...seen.values()];
-}
-
-/** Every PR number a changelog mentions, by `#N` or `/pull/N`. */
-export function mentionedPrs(changelog: string): Set<number> {
-	const out = new Set<number>();
-	for (const m of changelog.matchAll(/(?:#|\/pull\/)(\d+)\b/g)) out.add(Number(m[1]));
-	return out;
-}
-
-export function classifyOpenPr(pr: { number: number; title: string; html_url: string; draft?: boolean; head?: { ref?: string }; user?: { login?: string }; labels?: Array<{ name?: string }> }): OpenPr {
-	const title = pr.title;
-	const labels = (pr.labels ?? []).map((l) => l.name ?? "");
-	let kind: OpenPrKind;
-	if (pr.draft) kind = "draft";
-	else if (/^docs?(\([^)]*\))?!?:/i.test(title) || (pr.head?.ref ?? "").startsWith("docs/")) kind = "doc";
-	else if (labels.includes("type: dependencies") || /^deps?(\([^)]*\))?!?:/i.test(title) || (pr.user?.login ?? "").toLowerCase().startsWith("dependabot")) kind = "dependency";
-	else kind = "feature";
-	const v = kind === "doc" ? /\bv?(\d+\.\d+\.\d+)\b/.exec(title) : null;
-	return { number: pr.number, title, url: pr.html_url, kind, ...(v ? { version: v[1]! } : {}) };
-}
-
-export function assessFreshness(version: string, changelog: string, commits: ReleaseCommitPr[], readme: string | undefined): Freshness {
-	const mentioned = mentionedPrs(changelog);
-	const missing = commits.filter((c) => !mentioned.has(c.number));
-	const missingUserFacing = missing.filter((c) => !INTERNAL_TYPES.has(c.type)).map(({ number, title }) => ({ number, title }));
-	const missingInternal = missing.filter((c) => INTERNAL_TYPES.has(c.type)).map(({ number, title }) => ({ number, title }));
-	const firstLine = changelog.split("\n", 1)[0] ?? "";
-	const headingMatchesVersion = new RegExp(`v?${version.replace(/\./g, "\\.")}\\b`).test(firstLine);
-	const readmeMentionsVersion = readme !== undefined && new RegExp(`Latest:\\s*v?${version.replace(/\./g, "\\.")}\\b`).test(readme);
-	const thin = changelog.length < 400 || !/^##\s+Overview/m.test(changelog);
-	let status: FreshnessStatus = "current";
-	if (!headingMatchesVersion) status = "version-drift";
-	else if (missingUserFacing.length > 0) status = "stale";
-	else if (thin) status = "thin";
-	else if (missingInternal.length > 0) status = "minor-gap";
-	return { status, expectedPrs: commits.length, missingUserFacing, missingInternal, headingMatchesVersion, readmeMentionsVersion };
-}
-
-/** The release-docs decision table. */
-export function decideVerdict(args: { hasChangelog: boolean; unknownVersion: boolean; freshness?: Freshness; openPrs: OpenPr[]; version: string | null }): { verdict: ReleaseVerdict; reason: string; docVersionMismatch?: boolean } {
-	if (args.unknownVersion) return { verdict: "inspect", reason: "the release PR title has no `release: vX.Y.Z` version" };
-	const f = args.freshness;
-	if (args.hasChangelog && f && (f.status === "current" || f.status === "minor-gap")) {
-		return { verdict: "done", reason: f.status === "minor-gap" ? `changelog covers every user-facing change; ${f.missingInternal.length} internal PR(s) not mentioned` : "changelog is current" };
-	}
-	const docs = args.openPrs.filter((p) => p.kind === "doc");
-	const features = args.openPrs.filter((p) => p.kind === "feature");
-	const others = args.openPrs.filter((p) => p.kind === "dependency" || p.kind === "draft");
-	const need = args.hasChangelog ? `changelog is ${f?.status ?? "out of date"}` : "no changelog file";
-	if (docs.length > 0) {
-		const mismatch = args.version !== null && docs.some((d) => d.version !== undefined && d.version !== args.version);
-		return { verdict: "in-flight", reason: `${need}; doc PR #${docs[0]!.number} is open`, ...(mismatch ? { docVersionMismatch: true } : {}) };
-	}
-	if (features.length > 0) return { verdict: "wait", reason: `${need}; ${features.length} feature/fix PR(s) still open against the release branch` };
-	if (others.length > 0) return { verdict: "gray", reason: `${need}; only dependency PR(s) or drafts are open (${others.length})` };
-	return { verdict: args.hasChangelog ? "update" : "write", reason: `${need}; nothing is open against the release branch` };
-}
-
-function decodeContent(data: unknown): string | undefined {
-	const d = data as { content?: string; encoding?: string } | undefined;
-	if (!d || typeof d.content !== "string") return undefined;
-	return d.encoding === "base64" ? Buffer.from(d.content, "base64").toString("utf8") : d.content;
-}
-
-async function getText(octokit: Octokit, budget: CallBudget, owner: string, repo: string, path: string, ref: string): Promise<string | undefined> {
-	try {
-		return decodeContent(await reqOne(octokit, budget, "GET /repos/{owner}/{repo}/contents/{path}", { owner, repo, path, ref }));
-	} catch (err) {
-		if (err instanceof RateLimited || err instanceof CallBudgetExhausted) throw err;
-		if ((err as { status?: number }).status === 404) return undefined;
-		throw err;
-	}
-}
-
-export async function analyzeRelease(
-	octokit: Octokit,
-	budget: CallBudget,
-	args: { owner: string; repo: string; pull: number; head: string; version: string | null; changelogPath?: string }
-): Promise<ReleaseAnalysis> {
-	const { owner, repo } = args;
-	const open = await paginate<Parameters<typeof classifyOpenPr>[0]>(octokit, budget, "GET /repos/{owner}/{repo}/pulls", { owner, repo, state: "open", base: args.head }, 200);
-	const openPrs = open.map(classifyOpenPr);
-
-	let freshness: Freshness | undefined;
-	if (args.changelogPath && args.version) {
-		const commits = await paginate<{ commit?: { message?: string } }>(octokit, budget, "GET /repos/{owner}/{repo}/pulls/{pull_number}/commits", { owner, repo, pull_number: args.pull }, 300);
-		const changelog = (await getText(octokit, budget, owner, repo, args.changelogPath, args.head)) ?? "";
-		const readme = await getText(octokit, budget, owner, repo, "README.md", args.head);
-		freshness = assessFreshness(args.version, changelog, releaseCommitPrs(commits.map((c) => c.commit?.message ?? "")), readme);
-	}
-	const decision = decideVerdict({ hasChangelog: Boolean(args.changelogPath), unknownVersion: args.version === null, freshness, openPrs, version: args.version });
-	return {
-		openPrs,
-		...(freshness ? { freshness } : {}),
-		...(decision.docVersionMismatch ? { docVersionMismatch: true } : {}),
-		verdict: decision.verdict,
-		reason: decision.reason
-	};
-}