src/job-overlaps.ts

Functions

Imports

It imports src/env.ts, src/github/client.ts, src/github/pr-files.ts. Imported by src/jobs-holder.ts, src/jobs-transition.ts.

Source

1import type { Env } from "./env";
2import { PR_URL_SOURCE, parsePrUrl, resolveRepo } from "./github/client";
3import { readAllPages, readPrFiles } from "./github/pr-files";
4
5// Overlap warnings (Track A D1, capsid/research/design-track-a.md section 1). When block or
6// complete names a pull request, say which other open pull requests in the same repo change
7// the same files, from the file lists GitHub reports. Stacked and parallel pull requests that
8// rewrote the same function cost the seat a rebase on 2026-09-25; the warning is the moment
9// to merge in order instead. It informs and never refuses: a read that fails is reported as
10// "not checked", so a missing check is visible and never reads as a clean one.
11
12// Other open pull requests read per transition. A repo with more is reported, not silently
13// cut: the warning says how many it did not read.
14export const OTHER_PRS_READ = 20;
15const OPEN_LIST_MAX_PAGES = 5;
16const FILES_SHOWN = 3;
17
18export interface PrOverlap {
19  pr: number;
20  other: number;
21  files: string[];
22}
23
24export interface OverlapReport {
25  overlaps: PrOverlap[];
26  // Why the comparison is not the whole of it, or null when every list was read.
27  problem: string | null;
28}
29
30interface PrPaths {
31  number: number;
32  paths: string[];
33}
34
35/** The files each named pull request shares with each other pull request, the older
36 *  (lower-numbered) first. A pull request named by the job is never compared with itself or
37 *  with another named one: a job's own stack is not a collision. */
38export function overlapsOf(named: PrPaths[], others: PrPaths[]): PrOverlap[] {
39  const namedNumbers = new Set(named.map((n) => n.number));
40  const found: PrOverlap[] = [];
41  for (const mine of named) {
42    const mineSet = new Set(mine.paths);
43    for (const other of others) {
44      if (namedNumbers.has(other.number)) continue;
45      const files = [...new Set(other.paths.filter((p) => mineSet.has(p)))].sort();
46      if (files.length > 0) found.push({ pr: mine.number, other: other.number, files });
47    }
48  }
49  return found.sort((a, b) => Math.min(a.pr, a.other) - Math.min(b.pr, b.other) || a.pr - b.pr || a.other - b.other);
50}
51
52/** The line appended to a summary, or null when there is nothing to say. */
53export function overlapLine(report: OverlapReport): string | null {
54  if (report.overlaps.length === 0) return report.problem ? `Overlaps: not checked (${report.problem}).` : null;
55  const parts = report.overlaps.map((o) => {
56    const shown = o.files.slice(0, FILES_SHOWN).join(", ");
57    const more = o.files.length > FILES_SHOWN ? `, +${o.files.length - FILES_SHOWN} more` : "";
58    return `#${o.pr} with #${o.other} (${shown}${more})`;
59  });
60  const partial = report.problem ? ` Not fully checked (${report.problem}).` : "";
61  return `Overlaps: ${parts.join(", ")}. Merge in PR order, oldest first, and rebase the later.${partial}`;
62}
63
64/** The pull request URLs in free text, such as a block command: `gh pr merge` takes a
65 *  number, but a command that carries the URL names the pull request all the same. */
66export function prUrlsIn(text: string | null | undefined): string[] {
67  return [...new Set(text?.match(new RegExp(PR_URL_SOURCE, "g")) ?? [])];
68}
69
70/** Compare the named pull requests with every other open pull request in the namespace's
71 *  repo. Null when none of `urls` is a pull request of that repo, which is the normal case
72 *  for a job that opened nothing. Never throws: a failure is the report's `problem`. */
73export async function checkOverlaps(env: Env, namespace: string, urls: string[]): Promise<OverlapReport | null> {
74  const parsed = urls.map((u) => parsePrUrl(u)).filter((p): p is NonNullable<typeof p> => p !== null);
75  if (parsed.length === 0) return null;
76  try {
77    const repo = await resolveRepo(env, namespace);
78    const mine = parsed.filter((p) => `${p.owner}/${p.repo}`.toLowerCase() === repo.full.toLowerCase());
79    if (mine.length === 0) return null;
80    const numbers = [...new Set(mine.map((p) => p.number))];
81
82    return await compare(env, repo.owner, repo.repo, numbers);
83  } catch (err) {
84    return { overlaps: [], problem: err instanceof Error ? err.message : String(err) };
85  }
86}
87
88async function compare(env: Env, owner: string, repo: string, numbers: number[]): Promise<OverlapReport> {
89  const problems: string[] = [];
90  const listed = await readAllPages<{ number: number }>(
91    env, owner, repo, `/repos/${owner}/${repo}/pulls?state=open`,
92    (page) => page as Array<{ number: number }>, OPEN_LIST_MAX_PAGES
93  );
94  if (listed.problem) problems.push(`the open pull request list: ${listed.problem}`);
95  const otherNumbers = listed.items.map((p) => p.number).filter((n) => !numbers.includes(n)).sort((a, b) => a - b);
96  const read = otherNumbers.slice(0, OTHER_PRS_READ);
97  if (otherNumbers.length > read.length) problems.push(`${otherNumbers.length - read.length} open pull requests were not read`);
98
99  const readOne = async (number: number): Promise<PrPaths> => {
100    const files = await readPrFiles(env, owner, repo, number);
101    if (files.problem) problems.push(`#${number} files: ${files.problem}`);
102    return { number, paths: files.paths };
103  };
104  const [named, others] = await Promise.all([Promise.all(numbers.map(readOne)), Promise.all(read.map(readOne))]);
105  return { overlaps: overlapsOf(named, others), problem: problems.length > 0 ? problems.join("; ") : null };
106}