Public: anyone can read this; the crew can change it.

A hot-file hold names the open pulls on that file, oldest first, on the map and in the Flow panel #7433

Parked opened this
Closed without merging

torque/forge:torque/7423-a-hot-file-hold-names-the-open-pulls-on → main 5 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
11 files changed +225 −10
docs/FLOW.md +7
@@ -100,6 +100,13 @@ tick logs as `held=`, read through `flow/held.ts`, which keeps the rows 5 s.
100100 The terminal's Flow command prints the same rows, one line per repository
101101 (`alice/engine startable=0 stalled=4 run_cap=1`). A granted agent sees
102102 public repositories only, on both.
103 Under each repository's counts the panel lists the issues held on a hot
104 file, each with the map's sentence (`src/http/mcp.ts is in 6 open pulls`)
105 and a link to every open pull on that file, oldest first, at most 8
106 (#7423): the pulls to land or close to free it. The terminal's Flow dialog
107 prints the same under each repository's line
108 (` #12 src/a.ts is in 6 open pulls: #7290 #7316`). Only the owner sees
109 that list, on both, so no sealed issue or pull is named to anyone else.
103110
104111 One of those filters is the hot-file WIP limit (#5934, `crew/hot_files.ts`):
105112 a ready issue that names a file 5 or more open pulls already touch is held as
docs/MCP.md +3
@@ -400,6 +400,9 @@ answers
400400 issue, assigned ones too. `GET /api/v1/map` (the lanes) carries `startable`
401401 too but unfiltered: it skips the filter holds, so a hot-file issue is
402402 startable there and not in the repository's own map.
403 A `hot_file` hold also carries `pulls`: the open pulls on the file its
404 `detail` names, oldest first, at most 8 — the ones to land or close to
405 free it (#7423).
403406 - **Plugins.** `plugins/opencode` and `plugins/claude-code` register this
404407 server and add a `forge` command (tell, status, decide, plan, preview,
405408 pulls). They hold no logic.
docs/design/areas/boards.md +14
@@ -8,3 +8,17 @@ Drawn from existing components only: `card` with an icon head, `row` per hold
88 repositories the viewer administers and shows when there are none, because it
99 holds the form. A person who administers a repository but is not a forge
1010 admin sees `/boards` as this card alone.
11
12 ## Held on a hot file (`[data-hot-held]`, in `#held`)
13
14 Under a repository's counts in the "Ready, and why it waits" card, the issues
15 held on a hot file (#7423) are a `.list` of `row()`s: the issue linked as the
16 title, the map's sentence as the meta, and a link to each open pull on that
17 file, oldest first, in the trail, each named `pull N` for assistive tech.
18 The owner's alone.
19
20 - `.hot-pulls` — on that `.list`: the row wraps, the trail's pull links wrap
21 onto their own line under 640px, and each link is padded to 40px tall,
22 44×44 under `@media (pointer: coarse)`, so a thumb on a 360px phone hits
23 the pull it means among eight. Styled in `src/web/style/components.ts`
24 (list rows).
src/crew/held.ts +25 −5
@@ -47,7 +47,7 @@ import { flowOnlyHolds } from "./flow_only.ts";
4747 import { interruptionOf } from "./interrupted.ts";
4848 import { PARK_STRIKES, parkedCount } from "./parks.ts";
4949 import { heldFiles, type FileHold } from "./file_holds.ts";
50 import { expectedFiles, hotFiles, hotOverlap, relievedFiles } from "./hot_files.ts";
50 import { expectedFiles, hotFiles, hotOverlap, pullsOn, relievedFiles } from "./hot_files.ts";
5151 import { coveredByRedFix } from "./red_fix.ts";
5252
5353 export const HOLDS = [
@@ -257,6 +257,8 @@ export function stuckOf(held: Held): Stuck | undefined {
257257 export interface MapHold {
258258 readonly by: HoldName;
259259 readonly detail: string;
260 /** On `hot_file`: the open pulls on the file the detail names, oldest first, at most `PULLS_NAMED` (#7423). */
261 readonly pulls?: readonly number[];
260262 }
261263
262264 const HOLD_WORDS: Readonly<Record<HoldName, string>> = {
@@ -286,20 +288,38 @@ export function mapHolds(
286288 ): { holds: Map<number, MapHold>; startable: number[] } {
287289 const hot = hotFiles(repo.id, admit);
288290 const holds = new Map<number, MapHold>();
291 // Each path's pulls are read once, however many holds name it.
292 const named = new Map<string, number[]>();
293 const pullsOf = (path: string): number[] => {
294 let pulls = named.get(path);
295 if (pulls === undefined) named.set(path, (pulls = pullsOn(repo.id, path, admit)));
296 return pulls;
297 };
289298 for (const name of HOLDS) {
290299 for (const issue of held.by[name]) {
291300 let detail = HOLD_WORDS[name];
301 let path: string | undefined;
292302 if (name === "hot_file") {
293303 const pin = held.pinned.get(issue.number);
294304 const top = hotOverlap(issue, hot)[0];
295305 const rel = held.relieving.get(issue.number);
296 if (pin !== undefined) detail = `${pin.path} is held by an admin`;
297 else if (top === undefined && rel !== undefined)
306 if (pin !== undefined) {
307 detail = `${pin.path} is held by an admin`;
308 path = pin.path;
309 } else if (top === undefined && rel !== undefined) {
298310 detail = `waits: ${rel.path} is already being relieved by #${rel.by}`;
299 else if (top !== undefined)
311 path = rel.path;
312 } else if (top !== undefined) {
300313 detail = `${top.path} is in ${top.pulls} open ${top.pulls === 1 ? "pull" : "pulls"}`;
314 path = top.path;
315 }
301316 }
302 holds.set(issue.number, { by: name, detail });
317 holds.set(
318 issue.number,
319 name === "hot_file"
320 ? { by: name, detail, pulls: path === undefined ? [] : pullsOf(path) }
321 : { by: name, detail },
322 );
303323 }
304324 }
305325 return { holds, startable: held.startable.map((r) => r.issue.number) };
src/crew/hot_files.ts +18
@@ -139,6 +139,24 @@ export function pullCounts(
139139 return counts;
140140 }
141141
142 /** The most pulls a hold names on its file (#7423). */
143 export const PULLS_NAMED = 8;
144
145 /**
146 * The open pulls of `repoId` that touch `path`, oldest (lowest number) first,
147 * at most `PULLS_NAMED`: the narrow ones `pullCounts` counts. Memory only.
148 */
149 export function pullsOn(
150 repoId: string,
151 path: string,
152 admit: (pullNumber: number) => boolean = () => true,
153 ): number[] {
154 const out: number[] = [];
155 for (const { files, number } of touched.get(repoId)?.values() ?? [])
156 if (files.length <= WIDE_PULL && admit(number) && files.includes(path)) out.push(number);
157 return out.sort((a, b) => a - b).slice(0, PULLS_NAMED);
158 }
159
142160 /** Every file of `repo` that `HOT_PULLS` or more open pulls touch, with how many. */
143161 export function hotFiles(
144162 repoId: string,
src/flow/held.ts +13 −2
@@ -10,7 +10,7 @@
1010
1111 import type { App } from "../app.ts";
1212 import { listAutonomousRepos } from "../core/repos.ts";
13 import { heldCounts, heldNow, type HoldName } from "../crew/held.ts";
13 import { heldCounts, heldNow, mapHolds, type HoldName } from "../crew/held.ts";
1414
1515 export interface HeldRow {
1616 /** `owner/name`. */
@@ -18,6 +18,12 @@ export interface HeldRow {
1818 readonly public: boolean;
1919 readonly startable: number;
2020 readonly counts: Readonly<Record<HoldName, number>>;
21 /**
22 * Each issue held on a hot file, with the map's sentence and the open pulls
23 * on that file, oldest first (#7423). The owner's only: a reader of a public
24 * repository gets none, so no sealed issue or pull is named.
25 */
26 readonly hot: readonly { number: number; detail: string; pulls: readonly number[] }[];
2127 }
2228
2329 /** How long the rows are kept. */
@@ -33,15 +39,20 @@ export function readHeld(app: App, owner: boolean, now = Date.now()): HeldRow[]
3339 at: now,
3440 rows: listAutonomousRepos(app.db).map((repo) => {
3541 const held = heldNow(app, repo);
42 const { holds } = mapHolds(repo, held);
3643 return {
3744 repo: `${repo.ownerName}/${repo.name}`,
3845 public: repo.visibility === "public",
3946 startable: held.startable.length,
4047 counts: heldCounts(held),
48 hot: held.by.hot_file.map((issue) => {
49 const hold = holds.get(issue.number);
50 return { number: issue.number, detail: hold?.detail ?? "", pulls: hold?.pulls ?? [] };
51 }),
4152 };
4253 }),
4354 };
4455 kept.set(app, entry);
4556 }
46 return entry.rows.filter((r) => owner || r.public);
57 return owner ? [...entry.rows] : entry.rows.filter((r) => r.public).map((r) => ({ ...r, hot: [] }));
4758 }
src/tui/screens/flow.ts +6 −1
@@ -197,7 +197,7 @@ export function openerLines(rows: readonly Opener[], inner: number): string[] {
197197 return rows.length > 5 ? [...lines, `and ${rows.length - 5} more`] : lines;
198198 }
199199
200 /** One line per autonomous repository: its name, then `startable=N` and each filter holding any. */
200 /** One line per autonomous repository: its name, then `startable=N` and each filter holding any; under it, each hot-file hold the owner may see. */
201201 export function heldLines(rows: readonly HeldRow[], inner: number): string[] {
202202 if (rows.length === 0) return ["Ready, and why it waits: no repository runs on its own."];
203203 return [
@@ -210,6 +210,11 @@ export function heldLines(rows: readonly HeldRow[], inner: number): string[] {
210210 ...HOLDS.filter((h) => r.counts[h] > 0).map((h) => `${h}=${r.counts[h]}`),
211211 ].join(" "),
212212 inner,
213 ).concat(
214 // Each issue held on a hot file, with the pulls to land or close to free it (#7423).
215 r.hot.flatMap((h) =>
216 wrap(` #${h.number} ${h.detail}${h.pulls.length === 0 ? "" : `: ${h.pulls.map((n) => `#${n}`).join(" ")}`}`, inner),
217 ),
213218 ),
214219 ),
215220 ];
src/web/pages/boards-held.ts +23 −1
@@ -8,12 +8,33 @@
88 import { HOLDS } from "../../crew/held.ts";
99 import type { HeldRow } from "../../flow/held.ts";
1010 import { html, type Html } from "../html.ts";
11 import { card, meter } from "../ui.ts";
11 import { card, meter, row as listRow } from "../ui.ts";
1212
1313 function heldCount(kind: string, n: number): Html {
1414 return html`<span data-held="${kind}"><span class="mono">${kind}=${String(n)}</span></span>`;
1515 }
1616
17 /**
18 * The issues held on a hot file (#7423): a `.list` of `row()`s, the issue as
19 * the title, the map's sentence as the meta and a link to each open pull on
20 * that file, oldest first, in the trail.
21 */
22 function hotHolds(row: HeldRow): Html | null {
23 if (row.hot.length === 0) return null;
24 return html`<ul class="list hot-pulls" aria-label="Held on a hot file in ${row.repo}">
25 ${row.hot.map((h) =>
26 listRow({
27 data: { "hot-held": String(h.number) },
28 title: html`<a href="/${row.repo}/issues/${String(h.number)}">#${String(h.number)}</a>`,
29 meta: html`${h.detail}`,
30 trail: html`${h.pulls.map(
31 (n) => html`<a data-pull="${String(n)}" aria-label="pull ${String(n)}" href="/${row.repo}/pulls/${String(n)}">#${String(n)}</a> `,
32 )}`,
33 }),
34 )}
35 </ul>`;
36 }
37
1738 /** The startable share of the ready list; `attn` when none of it can start. */
1839 function startableMeter(row: HeldRow): Html {
1940 const total = row.startable + HOLDS.reduce((n, h) => n + row.counts[h], 0);
@@ -55,6 +76,7 @@ export function heldCard(rows: readonly HeldRow[]): Html {
5576 <td>${heldCount("startable", r.startable)} ${startableMeter(r)}</td>
5677 <td>
5778 ${HOLDS.filter((h) => r.counts[h] > 0).map((h) => html`${heldCount(h, r.counts[h])} `)}
79 ${hotHolds(r)}
5880 </td>
5981 </tr>`,
6082 )}
src/web/style/components.ts +7
@@ -390,6 +390,13 @@ a.sha:hover { color: var(--accent); }
390390 transition: background-color 100ms var(--ease);
391391 }
392392 a.flow-row { min-height: 44px; }
393 /* Held on a hot file (#7423): the pull links wrap under the sentence on a phone, each a 40px target, 44px for a thumb. */
394 .hot-pulls .row { flex-wrap: wrap; }
395 .hot-pulls .row-main { flex: 1 1 14rem; }
396 .hot-pulls .row-trail { flex: 0 1 auto; flex-wrap: wrap; gap: 0 4px; max-width: 100%; }
397 .hot-pulls .row-trail a { display: inline-flex; align-items: center; justify-content: center; min-height: 40px; padding: 0 8px; font-variant-numeric: tabular-nums; }
398 @media (max-width: 640px) { .hot-pulls .row-trail { flex-basis: 100%; } }
399 @media (pointer: coarse) { .hot-pulls .row-trail a { min-height: 44px; min-width: 44px; } }
393400 .row:focus-visible { outline-offset: -2px; }
394401 a.row:hover, .row[data-nav]:hover { background: var(--muted); color: inherit; }
395402 .list li[aria-current="true"] > .row { background: var(--muted); }
test/crew-held.test.ts +6 −1
@@ -25,7 +25,7 @@ import { createUser, getUserByName, type User } from "../src/core/users.ts";
2525 import { driveRepo } from "../src/crew/autonomy.ts";
2626 import { taskPrompt } from "../src/crew/brief.ts";
2727 import { ISSUE_RUN_CAP } from "../src/crew/guard.ts";
28 import { heldCounts, heldNow, heldWords, replannable, stuckOf } from "../src/crew/held.ts";
28 import { HOLDS, heldCounts, heldNow, heldWords, replannable, stuckOf, type HoldName } from "../src/crew/held.ts";
2929 import { PARK_NOTE } from "../src/crew/parks.ts";
3030 import { hunt, keyPart } from "../src/crew/sentinel.ts";
3131 import { HELD_TTL_MS, readHeld } from "../src/flow/held.ts";
@@ -448,6 +448,11 @@ describe("the tick says why each ready issue cannot start", () => {
448448 expect(agent).toContain("alice/open-door startable=0 done_on_main=1 stalled=1");
449449 expect(agent).not.toContain("shut-door");
450450 expect(heldLines([], 58)).toEqual(["Ready, and why it waits: no repository runs on its own."]);
451 // A hot-file hold the owner may see is printed under its repository, with its pulls (#7423).
452 const counts = Object.fromEntries(HOLDS.map((h) => [h, h === "hot_file" ? 1 : 0])) as Record<HoldName, number>;
453 expect(
454 heldLines([{ repo: "alice/hot", public: true, startable: 0, counts, hot: [{ number: 12, detail: "src/a.ts is in 6 open pulls", pulls: [7290, 7316] }] }], 58),
455 ).toEqual(["Ready, and why it waits:", "alice/hot startable=0 hot_file=1", " #12 src/a.ts is in 6 open pulls: #7290 #7316"]);
451456 });
452457
453458 test("the rows are kept a few seconds, then read afresh", async () => {
test/held-hot-pulls.test.ts added +103
@@ -0,0 +1,103 @@
1 /** A hot-file hold names the open pulls on its file, oldest first, on the map and in the Flow panel (#7423). */
2 import { afterAll, beforeAll, expect, test } from "bun:test";
3 import { mkdtemp, rm } from "node:fs/promises";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { createApp, type App } from "../src/app.ts";
7 import { createRepo } from "../src/actions/repos.ts";
8 import { createIssue } from "../src/core/issues.ts";
9 import { HOT_PULLS, PULLS_NAMED, pullsOn, rememberPullFiles, WIDE_PULL } from "../src/crew/hot_files.ts";
10 import { readHeld } from "../src/flow/held.ts";
11 import { heldCard } from "../src/web/pages/boards-held.ts";
12 import { flowLines } from "../src/tui/screens/flow.ts";
13 import { components } from "../src/web/style/components.ts";
14 import { serve, type Servers } from "../src/http/server.ts";
15 import { seedAdmin } from "./helpers/admin.ts";
16
17 let dataDir = "";
18 let app: App, servers: Servers, repoId = "", held = 0;
19 // Remembered out of order; at least three, and enough to make the file hot.
20 const PULLS = [7327, 7316, 7401, 7290, 7350].slice(0, Math.max(3, HOT_PULLS));
21 const OLDEST_FIRST = [...PULLS].sort((a, b) => a - b);
22
23 beforeAll(async () => {
24 dataDir = await mkdtemp(join(tmpdir(), "forge-hotpulls-"));
25 app = createApp({ dataDir, port: 0 });
26 servers = await serve(app);
27 const admin = await seedAdmin(app, { username: "alice", email: "[email protected]", password: "correct-horse-battery" });
28 if (!admin.ok) throw new Error(admin.error);
29 const made = await createRepo(app, admin.value, { name: "notes", visibility: "public", description: "" });
30 if (!made.ok) throw new Error(String(made.error));
31 repoId = made.value.id;
32 app.db.run("UPDATE repo SET autonomy = 'autonomous', autonomy_by = ?2 WHERE id = ?1", [repoId, admin.value.id]);
33 const issue = createIssue(app.db, { repoId, authorId: admin.value.id, title: "Add a flag", body: "Files: `src/hot.ts`" });
34 if (!issue.ok) throw new Error(issue.error);
35 held = issue.value.number;
36 rememberPullFiles(repoId, [
37 ...PULLS.map((number) => ({ number, files: ["src/hot.ts"] })),
38 // Too wide to count toward heat, so not named either.
39 { number: 7000, files: ["src/hot.ts", ...Array.from({ length: WIDE_PULL }, (_, i) => `src/w${i}.ts`)] },
40 { number: 7100, files: ["src/cold.ts"] },
41 ]);
42 });
43
44 afterAll(async () => {
45 rememberPullFiles(repoId, []);
46 servers.stop?.();
47 app.close();
48 await rm(dataDir, { recursive: true, force: true });
49 });
50
51 test("the map's hold names the pulls on the file, oldest first, and keeps its sentence", async () => {
52 const body = (await (await fetch(`${servers.url}/api/v1/repos/alice/notes/map`)).json()) as {
53 ready: { number: number; held: { by: string; detail: string; pulls?: number[] } | null }[];
54 };
55 const hold = body.ready.find((r) => r.number === held)!.held!;
56 expect(hold.by).toBe("hot_file");
57 expect(hold.detail).toBe(`src/hot.ts is in ${PULLS.length} open pulls`);
58 expect(hold.pulls).toEqual(OLDEST_FIRST);
59 });
60
61 test("the Flow panel's held card links each pull after the sentence, in that order", () => {
62 const rows = readHeld(app, true, Date.now());
63 const row = rows.find((r) => r.repo === "alice/notes")!;
64 expect(row.hot).toEqual([{ number: held, detail: `src/hot.ts is in ${PULLS.length} open pulls`, pulls: OLDEST_FIRST }]);
65 const page = String(heldCard(rows));
66 const item = page.slice(page.indexOf(`data-hot-held="${held}"`));
67 const sentence = item.indexOf(`src/hot.ts is in ${PULLS.length} open pulls`);
68 const at = OLDEST_FIRST.map((n) => item.indexOf(`href="/alice/notes/pulls/${n}">#${n}</a>`));
69 expect(sentence).toBeGreaterThan(0);
70 expect(at.every((i) => i > sentence)).toBe(true);
71 expect([...at].sort((a, b) => a - b)).toEqual(at);
72 expect(item).not.toContain("/pulls/7000");
73 for (const n of OLDEST_FIRST) expect(item).toContain(`aria-label="pull ${n}"`);
74 // A thumb's target on a phone: the list carries the class whose links are 44px under a coarse pointer.
75 expect(page).toContain('<ul class="list hot-pulls"');
76 expect(components).toMatch(/@media \(pointer: coarse\) \{ \.hot-pulls \.row-trail a \{ min-height: 44px; min-width: 44px; \} \}/);
77 });
78
79 test("the terminal's Flow dialog prints the hold and its pulls under the repository's line", () => {
80 const owner = flowLines(app.db, new Date(), [], undefined, readHeld(app, true)).join("\n");
81 // The dialog wraps at its width; read the words, not the breaks.
82 expect(owner.replace(/\s+/g, " ")).toContain(
83 ` #${held} src/hot.ts is in ${PULLS.length} open pulls: ${OLDEST_FIRST.map((n) => `#${n}`).join(" ")}`,
84 );
85 expect(owner.indexOf(`#${held} src/hot.ts`)).toBeGreaterThan(owner.indexOf("alice/notes startable="));
86 const guest = flowLines(app.db, new Date(), [], { queues: [] }, readHeld(app, false)).join("\n");
87 expect(guest).toContain("alice/notes startable=0 hot_file=1");
88 expect(guest).not.toContain("src/hot.ts is in");
89 });
90
91 test("a reader who is not the owner is named no pulls", () => {
92 const row = readHeld(app, false, Date.now()).find((r) => r.repo === "alice/notes")!;
93 expect(row.counts.hot_file).toBe(1);
94 expect(row.hot).toEqual([]);
95 });
96
97 test("at most PULLS_NAMED are named, the oldest", () => {
98 const many = Array.from({ length: PULLS_NAMED + 4 }, (_, i) => 900 - i);
99 rememberPullFiles("other", many.map((number) => ({ number, files: ["a/b.ts"] })));
100 expect(pullsOn("other", "a/b.ts")).toEqual([...many].sort((a, b) => a - b).slice(0, PULLS_NAMED));
101 expect(pullsOn("other", "a/b.ts", (n) => n !== 889)).not.toContain(889);
102 rememberPullFiles("other", []);
103 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs