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

The roadmap list is keyboard-first: j/k move between rows, enter opens one #10424

Parked opened this
Closed without merging

torque/forge:torque/10406-the-roadmap-list-is-keyboard-first-j-k-m → main 5 commits fork 2 threads · 2 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
6 files changed +84 −66
docs/features/roadmap.md +6
@@ -24,3 +24,9 @@ sealed, and Needs you is shown to writers only.
2424 - MCP: `map` with `roadmap: true`.
2525 - Terminal: the palette command "Roadmap of a repository" (`owner/name`);
2626 `j`/`k` scroll, `esc` closes. Same model, `src/web/roadmap.ts`.
27
28 ## Keyboard
29
30 `j`/`k` move between the linked rows (Needs you and each issue) and `enter`
31 opens the focused one. Rows inside a folded pillar are skipped; open a pillar
32 and its rows join the walk.
src/kernel/why_now.ts deleted −37
@@ -1,37 +0,0 @@
1 /**
2 * Retired 2026-11-09: the direction no longer puts the pipeline first —
3 * order is set by the pillars and the captain's ranking — so the gate no
4 * longer asks (`scripts/gate.ts`). A finished, approved pull closed unmerged
5 * on this rule (#10317); nothing reads it now. Kept with its test until the
6 * next sweep of unused modules.
7 *
8 * The direction issue put the pipeline first (#8839), so a new feature
9 * said why it went ahead of it. A feature is a file a pull adds, at any
10 * depth, under an action, a page, an API route, an MCP tool or a terminal
11 * screen; the pull's commits must then say either `Pipeline: #N` (it is
12 * pipeline work) or `Why now: <reason>` (it goes ahead, and why). The check
13 * cannot read the pull description, so the answer lives in a commit
14 * message. It is a nudge, not a proof: it checks a reason was written, not
15 * that it is a good one.
16 */
17
18 import type { Change } from "./pin_edits.ts";
19
20 const FEATURE = /^src\/(actions|web\/pages|http\/api|http\/mcp\/tools|tui)\/.+\.ts$/;
21 const PIPELINE = /^Pipeline:\s*#\d+/im;
22 const WHY_NOW = /^Why now:\s*\S[^\n]{14,}/im;
23
24 /** The files a pull adds that make a new feature. */
25 export function featuresAdded(changes: readonly Change[]): string[] {
26 return changes.filter((c) => c.status.startsWith("A") && FEATURE.test(c.path)).map((c) => c.path);
27 }
28
29 /** One line per problem: none when no feature is added or a commit answers the direction. */
30 export function whyNowProblems(changes: readonly Change[], messages: readonly string[]): string[] {
31 const added = featuresAdded(changes);
32 if (added.length === 0) return [];
33 if (messages.some((m) => PIPELINE.test(m) || WHY_NOW.test(m))) return [];
34 return [
35 `rule "say why it goes ahead of the pipeline": this pull adds ${added.join(", ")} but no commit message has a "Why now: <reason>" line (15+ characters) or a "Pipeline: #N" line`,
36 ];
37 }
src/web/client.ts +9 −1
@@ -1469,7 +1469,15 @@ const shellCore = /* js */ `
14691469
14701470 // ---- keyboard: sequences from the DOM, so the help can never drift ----
14711471 var seq = []; var last = 0;
1472 function rows() { return Array.prototype.slice.call(doc.querySelectorAll('[data-nav]')); }
1472 // A row inside a closed <details> is not rendered and cannot take focus, so
1473 // the walk skips it (the details' own <summary> stays reachable).
1474 function folded(el) {
1475 for (var d = el.closest('details'); d; d = d.parentElement && d.parentElement.closest('details')) {
1476 if (!d.open && !d.hasAttribute('open')) return true;
1477 }
1478 return false;
1479 }
1480 function rows() { return Array.prototype.slice.call(doc.querySelectorAll('[data-nav]')).filter(function (el) { return !folded(el); }); }
14731481 function move(step) {
14741482 var all = rows();
14751483 if (all.length === 0) return;
src/web/pages/roadmap.ts +2
@@ -34,6 +34,7 @@ function needs(base: string, rows: readonly NeedsYou[]): Html | null {
3434 title: r.text,
3535 href: `${base}/${r.pull ? "pulls" : "issues"}/${r.number}`,
3636 trail: html`${r.action}`,
37 nav: true,
3738 }),
3839 )}
3940 </ul>
@@ -48,6 +49,7 @@ function issueRow(base: string, i: RoadmapIssue): Html {
4849 ...(i.assignee === null ? {} : { lead: avatar(i.assignee) }),
4950 title: html`#${i.number} ${i.title}${i.moved ? html`<span class="rm-moved">moved</span>` : null}`,
5051 href: `${base}/${i.pull === undefined ? "issues" : "pulls"}/${i.pull ?? i.number}`,
52 nav: true,

Keyboard, no mouse: only the current pillar is open; the others are closed <details>. move() in client.ts calls focus() on the next [data-nav] row, and focus() on a row inside a closed <details> does nothing. Pressing j from the last visible row therefore stays put, and every press after that does the same. Fix: have the nav walk skip rows that are not rendered (e.g. offsetParent/closest(details:not([open]))), or mark rows data-nav only in the open pillar. Add a test that rows in a folded pillar are not reachable. The same holds for the issue rows in other pillars.

5153 ...(bits.length === 0 ? {} : { meta: html`${bits.join(" · ")}` }),
5254 });
5355 }
test/keys-roadmap.test.ts added +67
@@ -0,0 +1,67 @@
1 /** The roadmap joins the shell's j/k row traversal (#10406): one data-nav per linked row, none on the empty page. */
2 import { expect, test } from "bun:test";
3 import { roadmapBody } from "../src/web/pages/roadmap.ts";
4 import type { Roadmap, RoadmapIssue, RoadmapPillar } from "../src/web/roadmap.ts";
5
6 const issue = (number: number, extra: Partial<RoadmapIssue> = {}): RoadmapIssue => ({
7 number, title: `Issue ${number}`, assignee: null, at: "2026-11-01T00:00:00Z", moved: false, ...extra,
8 });
9
10 function pillar(over: Partial<RoadmapPillar>): RoadmapPillar {
11 return {
12 short: "P1", name: "P1 Core", umbrella: 1, state: "current", done: 0, total: 2, merged: 0,
13 building: [], next: null, lastLanding: null, etaDays: null, etaAt: null,
14 groups: { building: [], upNext: [], waiting: [], blocked: [], doneThisWeek: [] },
15 movedCount: 0, ...over,
16 };
17 }
18
19 const road = (pillars: RoadmapPillar[], needsYou: Roadmap["needsYou"] = []): Roadmap => ({
20 generatedAt: "2026-11-09T00:00:00Z",
21 pace: { landed24h: 0, landed7d: 0, days: 7, current: null, etaDays: null, etaAt: null },
22 needsYou, pillars,
23 });
24
25 const NAV = /class="row"[^>]*data-nav tabindex="-1"/g;
26
27 test("each linked roadmap row carries data-nav; the folding pillar rows do not", () => {
28 const p = pillar({
29 groups: { building: [issue(11), issue(12, { pull: 99 })], upNext: [issue(13)], waiting: [], blocked: [], doneThisWeek: [] },

This test counts rows in the open pillar only (the pillar fixture is state current). Add a folded (non-current) pillar case so the fix above is covered. Without it, nothing shows j/k can walk past a fold.

30 });
31 const out = roadmapBody("/acme/forge", road([p], [
32 { kind: "hold", text: "Hold it", action: "Release", number: 5, pull: true },
33 ])).text;
34 expect(out.match(NAV)?.length).toBe(4); // 1 needs-you + 3 issues
35 expect(out).toContain('href="/acme/forge/pulls/99"');
36 // the pillar summary is a fold, not a link
37 expect(out).not.toMatch(/<summary[^>]*data-nav/);
38 });
39
40 test("the empty roadmap draws no data-nav row", () => {
41 const out = roadmapBody("/acme/forge", road([])).text;
42 expect(out).not.toContain("data-nav");
43 const bare = roadmapBody("/acme/forge", road([pillar({})])).text;
44 expect(bare).not.toContain("data-nav");
45 });
46
47 test("j/k skip rows inside a folded pillar (client walk)", async () => {
48 const { shellJs } = await import("../src/web/client.ts");
49 const m = shellJs.match(/function folded\(el\)[\s\S]*?function rows\(\)[^\n]*\n/);
50 expect(m).not.toBeNull();
51 type D = { open: boolean; parentElement: null; closest: (s: string) => D | null; hasAttribute: (n: string) => boolean };
52 const det = (open: boolean): D => ({ open, parentElement: null, closest: () => null, hasAttribute: () => open });
53 const row = (d: D | null, name: string) => ({ name, closest: () => d });
54 const openP = det(true), foldedP = det(false);
55 const all = [row(null, "needs"), row(openP, "a"), row(foldedP, "b"), row(foldedP, "c")];
56 const doc = { querySelectorAll: () => all };
57 const rows = new Function("doc", `${m![0]}; return rows;`)(doc) as () => { name: string }[];
58 expect(rows().map((r) => r.name)).toEqual(["needs", "a"]);
59 });
60
61 test("a folded pillar still renders its linked rows as data-nav (the walk filters them at runtime)", () => {
62 const cur = pillar({ groups: { building: [issue(1)], upNext: [], waiting: [], blocked: [], doneThisWeek: [] } });
63 const fold = pillar({ short: "P2", name: "P2 Later", umbrella: 2, state: "later" as RoadmapPillar["state"],
64 groups: { building: [issue(2)], upNext: [], waiting: [], blocked: [], doneThisWeek: [] } });
65 const out = roadmapBody("/acme/forge", road([cur, fold])).text;
66 expect(out.match(NAV)?.length).toBe(2);
67 });
test/why-now.test.ts deleted −28
@@ -1,28 +0,0 @@
1 /** Retired 2026-11-09 with the pipeline-first direction: the gate no longer asks (`scripts/gate.ts`); the pure rule keeps its tests until the module goes. */
2 import { expect, test } from "bun:test";
3 import { featuresAdded, whyNowProblems } from "../src/kernel/why_now.ts";
4
5 const add = (path: string) => ({ status: "A", path });
6
7 test("a new action, page or route is a feature; edits, tests and other files are not", () => {
8 expect(featuresAdded([add("src/actions/x.ts"), add("src/web/pages/y.ts"), add("src/http/api/z.ts")])).toHaveLength(3);
9 expect(featuresAdded([add("src/http/mcp/tools/x.ts"), add("src/tui/app/screen.ts"), add("src/http/api/v1/y.ts")])).toHaveLength(3);
10 expect(featuresAdded([{ status: "M", path: "src/actions/x.ts" }, add("test/x.test.ts"), add("src/core/x.ts")])).toEqual([]);
11 });
12
13 test("a feature with no answer to the direction is refused, naming the rule and the file", () => {
14 const [p] = whyNowProblems([add("src/actions/x.ts")], ["Add x\n\nIt does x."]);
15 expect(p).toContain("say why it goes ahead of the pipeline");
16 expect(p).toContain("src/actions/x.ts");
17 });
18
19 test("a Why now line or a Pipeline line answers it; a thin reason does not", () => {
20 const changes = [add("src/actions/x.ts")];
21 expect(whyNowProblems(changes, ["Add x\n\nWhy now: the owner asked for it in #1234 this week"])).toEqual([]);
22 expect(whyNowProblems(changes, ["Add x\n\nPipeline: #6534"])).toEqual([]);
23 expect(whyNowProblems(changes, ["Add x\n\nWhy now: soon"])).toHaveLength(1);
24 });
25
26 test("a pull that adds no feature is never asked", () => {
27 expect(whyNowProblems([add("test/a.test.ts")], ["Fix a"])).toEqual([]);
28 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs