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

The fork tree names each fork's follow mode in words beside it: follows automatically, proposes only, or severed #13472

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13396-the-fork-tree-names-each-fork-s-follow-m → main 3 commits fork 3 threads · 3 unresolved

  • Merged. scout/13396-the-fork-tree-names-each-fork-s-follow-m was merged into main as 4f85986.

Review

Sign in to review this change.
8 files changed +188 −22
docs/features/fork-tree.md +2
@@ -52,3 +52,5 @@ Right opens a branch (or steps in), Left closes it (or steps out), Home/End jump
5252 the tree is at most four levels deep, so indentation is at most three steps. The row itself is the `treeitem`
5353 (it takes focus, so it says its level and state); the "level N" text is hidden from screen readers, which hear `aria-level`.
5454 A child cannot report a severed mode, so that word is not drawn. Test: `test/family-a11y.test.ts`.
55
56 Each fork in the forks page's tree and in the terminal's tree and forks screens also says its mode in words (`FOLLOW_PHRASE` in `src/actions/follow_words.ts`): `follows automatically`, `proposes only`, or `severed · no longer follows`, the last drawn dimmed. Test: `test/fork-tree-mode.test.ts`.
src/actions/follow_words.ts +30 −2
@@ -36,7 +36,10 @@ export const FOLLOW_SWITCH_LABELS: Record<ForkFollowMode, string> = {
3636 "dont-follow": "Stop following",
3737 };
3838
39 /** How a fork follows its upstream, in one line and the reason beside it: the page and the MCP say these words. */
39 /**
40 * How a fork follows its upstream, in one line and the reason beside it: the page and the MCP say
41 * these words.
42 */
4043 export function followModeWords(
4144 mode: ForkFollowMode,
4245 upstream: string,
@@ -105,9 +108,34 @@ export function followStandingLine(
105108 return tookAt === null ? line : `${line} · last took ${agoWords(tookAt, now)}`;
106109 }
107110
108 /** How a fork follows its upstream in one word, for a tree node; a severed fork says so rather than saying nothing. */
111 /**
112 * How a fork follows its upstream in one word, for a tree node; a severed fork says so rather than
113 * saying nothing.
114 */
109115 export const FOLLOW_WORD: Readonly<Record<ForkFollowMode, string>> = {
110116 "take-updates": "follows",
111117 "tell-me": "proposes",
112118 "dont-follow": "severed",
113119 };
120
121 /**
122 * A tree node's follow mode in words (#13396): the one table the web fork tree and the terminal
123 * both say.
124 */
125 export const FOLLOW_PHRASE: Readonly<Record<ForkFollowMode, string>> = {
126 "take-updates": "follows automatically",
127 "tell-me": "proposes only",
128 "dont-follow": "severed · no longer follows",
129 };
130
131 /** Whether a fork's node is drawn dimmed: it is shown, but it no longer follows. */
132 export const isSevered = (mode: ForkFollowMode | undefined): boolean => mode === "dont-follow";
133
134 /**
135 * A tree node's phrase from how the tree stores it (`offers` is `tell-me`); the root follows
136 * nothing and says nothing.
137 */
138 export function treeFollowPhrase(follow: "take-updates" | "offers" | "dont-follow" | "autonomous"): string {
139 if (follow === "autonomous") return "";
140 return FOLLOW_PHRASE[follow === "offers" ? "tell-me" : follow];
141 }
src/tui/screens/fork_tree.ts +3 −2
@@ -4,7 +4,7 @@
44 * the tool does: a repo the session's person may not read has no tree.
55 */
66
7 import { HIDDEN_FORK_WORD } from "../../actions/follow_words.ts";
7 import { HIDDEN_FORK_WORD, treeFollowPhrase } from "../../actions/follow_words.ts";
88 import { forkTree, type ForkTree } from "../../actions/fork_tree.ts";
99 import type { Repo } from "../../core/repos.ts";
1010 import type { Ctx, Screen } from "../app/app.ts";
@@ -21,7 +21,8 @@ import { Scroll } from "./common.ts";
2121 export function treeLines(tree: ForkTree | undefined, asked: string, width = 80, viewer?: string): string[] {
2222 if (tree === undefined) return ["Nothing to show."];
2323 const lines = tree.nodes.map((n) => {
24 const follow = (n.word === "" ? "" : ` ${n.word}`) + (n.hiddenParent === true ? ` ${HIDDEN_FORK_WORD}` : "");
24 const phrase = n.word === "" ? "" : treeFollowPhrase(n.follow);
25 const follow = (phrase === "" ? "" : ` ${phrase}`) + (n.hiddenParent === true ? ` ${HIDDEN_FORK_WORD}` : "");
outdated

Cast plus inline 'offers' remap on one long line: put a small function beside FOLLOW_PHRASE so the table owns the mapping, and no as.

2526 const you = n.repo !== asked && viewer !== undefined && n.repo.startsWith(`${viewer}/`) ? " (you)" : "";
2627 return truncate(`${" ".repeat(n.depth)}${n.repo === asked ? "* " : ""}${n.repo}${you}${follow}`, width);
2728 });
src/tui/screens/forks.ts +11 −5
@@ -21,7 +21,7 @@ import {
2121 type ForkRanking,
2222 type ForkRelation,
2323 } from "../../actions/forks.ts";
24 import { FOLLOW_WORD, FOLLOWS_NOTHING, followModeWords, proposeRefusalWords } from "../../actions/follow_words.ts";
24 import { FOLLOW_PHRASE, FOLLOW_WORD, FOLLOWS_NOTHING, followModeWords, proposeRefusalWords } from "../../actions/follow_words.ts";
2525 import { FOLLOW_MODE_REFUSALS, convergeWords, followModeOf, followStanding, followModeSaid, setFollowMode, takeOrTell, takeWords } from "../../actions/follow.ts";
2626 import { incomingOf, type Incoming } from "../../actions/follow_incoming.ts";
2727 import { convergeFollowed, followedAs, followedOf } from "../../actions/upstream_sync.ts";
@@ -29,7 +29,7 @@ import { STANDING_EVENTS } from "../../core/standing_events.ts";
2929 import { openProposal, proposeUpstream } from "../../actions/upstream.ts";
3030 import type { Pull } from "../../core/pulls.ts";
3131 import { convergeState, type Converge } from "../../crew/converge.ts";
32 import { FORK_FOLLOW_MODES, type ForkFollowMode } from "../../core/fork_follow.ts";
32 import { FORK_DEFAULT_MODE, FORK_FOLLOW_MODES, forkFollowModes, type ForkFollowMode } from "../../core/fork_follow.ts";
3333 import { canAdmin, canRead, canWrite, forkTree, getRepoById, listForks, type ForkNode, type Repo } from "../../core/repos.ts";
3434 import type { Ctx, Screen } from "../app/app.ts";
3535 import { binding } from "../app/keys.ts";
@@ -57,19 +57,23 @@ export interface ForkRow {
5757 export function forkRows(
5858 ranked: ForkRanking,
5959 tree: readonly ForkNode[] = [],
60 /** How each fork follows its parent (#13396); with none given, no phrase is said. */
61 modes?: ReadonlyMap<string, ForkFollowMode>,
6062 ): ForkRow[] {
63 const phrase = (id: string, rest: string): string =>
64 modes === undefined ? rest : [FOLLOW_PHRASE[modes.get(id) ?? FORK_DEFAULT_MODE], rest].filter((w) => w !== "").join(" · ");
6165 const below = new Map(tree.map((n) => [n.repo.id, n.forks]));
6266 const row = (f: ForkRanking["offering"][number], heading: string) => [
6367 {
6468 repo: f.fork,
6569 name: `${f.fork.ownerName}/${f.fork.name}`,
66 words: ranked.archived ? "" : driftWords(f.drift),
70 words: phrase(f.fork.id, ranked.archived ? "" : driftWords(f.drift)),
6771 heading,
6872 },
6973 ...(below.get(f.fork.id) ?? []).map((n) => ({
7074 repo: n.repo,
7175 name: ` ${n.repo.ownerName}/${n.repo.name}`,
72 words: n.deeper === 0 ? "" : `and ${n.deeper} more fork${n.deeper === 1 ? "" : "s"} below`,
76 words: phrase(n.repo.id, n.deeper === 0 ? "" : `and ${n.deeper} more fork${n.deeper === 1 ? "" : "s"} below`),
7377 heading: "",
7478 })),
7579 ];
@@ -157,6 +161,7 @@ export function incomingLines(incoming: Incoming | undefined): string[] {
157161 export function forksScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
158162 let ranked: ForkRanking | undefined;
159163 let tree: ForkNode[] = [];
164 let forkModes: Map<string, ForkFollowMode> = new Map();
160165 let following: ForkRow[] = [];
161166 let relation: ForkRelation | undefined;
162167 let offer: string | undefined;
@@ -212,12 +217,13 @@ export function forksScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
212217 const rows = (): ForkRow[] => [
213218 ...(open === undefined || relation === undefined ? [] : [openRow(open, relation.parent)]),
214219 ...following,
215 ...(ranked === undefined ? [] : forkRows(ranked, tree)),
220 ...(ranked === undefined ? [] : forkRows(ranked, tree, forkModes)),
216221 ];
217222 const read = async (): Promise<void> => {
218223 const forks = listForks(f.db, repo.id).filter((r) => canRead(f.db, r, f.user));
219224 ranked = await rankedForksOf(f.app, repo, forks);
220225 tree = forkTree(f.db, repo.id, f.user);
226 forkModes = forkFollowModes(f.db, [...tree, ...tree.flatMap((n) => n.forks)].map((n) => n.repo.id));
221227 relation = await relationOf(f.app, f.user, repo);
222228 open = relation === undefined ? undefined : openProposal(f.app, repo, relation.parent);
223229 incoming = relation === undefined ? undefined : await incomingOf(f.app.reposRoot, repo, relation);
src/web/pages/repo.ts +19 −11
@@ -38,6 +38,8 @@ import {
3838 takeUpdates,
3939 type ForkDrift,
4040 } from "../../actions/forks.ts";
41 import { FORK_DEFAULT_MODE, forkFollowModes, type ForkFollowMode } from "../../core/fork_follow.ts";
42 import { FOLLOW_PHRASE, isSevered } from "../../actions/follow_words.ts";
4143 import { lineageOf } from "../../core/following.ts";
4244 import {
4345 archivedParentLine,
@@ -167,6 +169,7 @@ export async function forksPage(ctx: Ctx): Promise<Response> {
167169 notePhase(ctx.request, "forks", performance.now() - t);
168170 t = performance.now();
169171 const tree = forkTree(ctx.app.db, repo.id, ctx.auth.user);
172 const forkModes = forkFollowModes(ctx.app.db, [...tree, ...tree.flatMap((n) => n.forks)].map((n) => n.repo.id));
170173 notePhase(ctx.request, "fork-tree", performance.now() - t);
171174 t = performance.now();
172175 // The whole family, from the oldest ancestor this viewer may see: who
@@ -199,7 +202,7 @@ export async function forksPage(ctx: Ctx): Promise<Response> {
199202 note: "A fork is a copy under another name that can propose changes back here, and follows this one until it has work of its own.",
200203 bind: BIND.rest,
201204 })
202 : html`${forkRanking(ranked, new Map(tree.map((n) => [n.repo.id, n])), BIND.rest)}
205 : html`${forkRanking(ranked, new Map(tree.map((n) => [n.repo.id, n])), BIND.rest, forkModes)}
203206 <h3 class="mt">The family, by who follows whom</h3>
204207 ${lineageCard(lineage, repo.id, ctx.auth.user?.id)}`}`;
205208 const res = page({
@@ -220,32 +223,37 @@ function forkRanking(
220223 tree: ReadonlyMap<string, ForkNode>,
221224 /** The binding key of the forks counted (`bind.ts`): each ranked row is one. */
222225 bind: string,
226 /** How each fork follows its parent; a fork without a row follows the default. */
227 modes: ReadonlyMap<string, ForkFollowMode> = new Map(),
223228 ): Html {
229 const modeOf = (id: string): ForkFollowMode => modes.get(id) ?? FORK_DEFAULT_MODE;
224230 const below = (n: ForkNode): Html =>
225231 row({
226232 lead: icon("fork"),
233 ...(isSevered(modeOf(n.repo.id)) ? { data: { severed: "" } } : {}),
227234 title: html`<a href="/${n.repo.ownerName}/${n.repo.name}"
228235 >${n.repo.ownerName}/${n.repo.name}</a
229236 >`,
230 ...(n.deeper === 0
231 ? {}
232 : {
233 meta: html`<a href="/${n.repo.ownerName}/${n.repo.name}/forks"
237 meta: html`<span>${FOLLOW_PHRASE[modeOf(n.repo.id)]}</span>${n.deeper === 0
238 ? html``
239 : html` · <a href="/${n.repo.ownerName}/${n.repo.name}/forks"
234240 >and ${n.deeper} more fork${n.deeper === 1 ? "" : "s"} below</a
235 >`,
236 }),
241 >`}`,
237242 });
238243 const line = (f: RankedFork, offer: boolean): Html =>
239244 row({
240 data: { row: "" },
245 data: { row: "", ...(isSevered(modeOf(f.fork.id)) ? { severed: "" } : {}) },
241246 children: (tree.get(f.fork.id)?.forks ?? []).map(below),
242247 lead: icon("fork"),
243248 title: html`<a href="/${f.fork.ownerName}/${f.fork.name}"
244249 >${f.fork.ownerName}/${f.fork.name}</a
245250 >`,
246 meta: html`${ranked.archived ? "" : driftWords(f.drift)}${f.pushedAt === null
247 ? html``
248 : html` · pushed ${time(f.pushedAt)}`}`,
251 meta: html`<span>${FOLLOW_PHRASE[modeOf(f.fork.id)]}</span>${[
outdated

Principle 8 / plain words: with an archived repo or empty drift words this renders a trailing ' · '. Join only the non-empty parts, as forks.ts does in the terminal.

252 ranked.archived ? "" : driftWords(f.drift),
253 f.pushedAt === null ? "" : html`pushed ${time(f.pushedAt)}`,
254 ]
255 .filter((p) => String(p) !== "")
256 .map((p) => html` · ${p}`)}`,
249257 ...(offer
250258 ? {
251259 trail: btn("Compare", {
src/web/style/components.ts +1
@@ -496,6 +496,7 @@ a.row:hover, .row[data-nav]:hover { background: var(--muted); color: inherit; }
496496 .list.bare-tree [data-level] { font-variant-numeric: tabular-nums; opacity: .8; }
497497 .list.bare-tree [data-word] { font-weight: 600; }
498498 .list.bare-tree [hidden] { display: none; }
499 li[data-severed] .row-lead, li[data-severed] .row-title { opacity: .6; }
outdated

Principle 4: opacity .6 over --muted text risks failing contrast on a 360px phone. Dim without lowering the phrase below readable contrast. Also the bold on [data-follow-phrase] adds a second emphasis to every row; muted plain text would keep rhythm (principle 3).

499500 .list.bare-tree .row { padding-top: 10px; padding-bottom: 10px; }
500501 .list.bare-tree .row-title, .list.bare-tree .row-meta { white-space: normal; overflow: visible; overflow-wrap: anywhere; }
501502 /* A row's look thumbs (/review): inset like a row, side by side at any width; the link's hit area grows to 44px. */
test/fork-tree-mode.test.ts added +120
@@ -0,0 +1,120 @@
1 /**
2 * #13396: the fork tree names each fork's follow mode in words, web and terminal from one table.
3 */
4 import { afterAll, beforeAll, expect, test } from "bun:test";
5 import { mkdtemp, rm } from "node:fs/promises";
6 import { tmpdir } from "node:os";
7 import { join } from "node:path";
8 import { FOLLOW_PHRASE, treeFollowPhrase } from "../src/actions/follow_words.ts";
9 import { forkTree } from "../src/actions/fork_tree.ts";
10 import { setRole } from "../src/actions/roles.ts";
11 import { commitToBranch, createRepo, forkRepo } from "../src/actions/repos.ts";
12 import { createApp, type App } from "../src/app.ts";
13 import { forkFollowModes, setForkFollowMode, type ForkFollowMode } from "../src/core/fork_follow.ts";
14 import { type Repo } from "../src/core/repos.ts";
15 import { createUser, type User } from "../src/core/users.ts";
16 import { serve, type Servers } from "../src/http/server.ts";
17 import { treeLines } from "../src/tui/screens/fork_tree.ts";
18 import { forkRows } from "../src/tui/screens/forks.ts";
19 import { rankedForksOf } from "../src/actions/forks.ts";
20 import { listForks } from "../src/core/repos.ts";
21
22 let dataDir: string;
23 let app: App;
24 let servers: Servers;
25 let ann: User;
26 let root: Repo;
27 const kids = new Map<ForkFollowMode, Repo>();
28
29 const must = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
30 if (!r.ok) throw new Error(JSON.stringify(r.error));
31 return r.value;
32 };
33
34 beforeAll(async () => {
35 dataDir = await mkdtemp(join(tmpdir(), "forge-tree-mode-"));
36 app = createApp({ dataDir, port: 0 });
37 servers = await serve(app);
38 const mk = async (username: string, first: boolean) =>
39 must(await createUser(app.db, { origin: "seed", trusted: true, username, email: `${username}@forge.local`, password: "a-good-passphrase", adminIfFirst: first }));
40 ann = await mk("ann", true);
41 root = must(await createRepo(app, ann, { name: "yard", visibility: "public" }));
42 must(await commitToBranch(app, ann, root, { message: "first", files: [{ path: "a.txt", content: "a\n" }] }));
43 for (const [user, mode] of [["bea", "take-updates"], ["cal", "tell-me"], ["dan", "dont-follow"]] as const) {
44 const u = await mk(user, false);
45 must(setRole(app, ann, user, "member"));
46 const fork = must(await forkRepo(app, u, root));
47 setForkFollowMode(app.db, fork.id, mode);
48 kids.set(mode, fork);
49 }
50 }, 60_000);
51
52 afterAll(async () => {
53 servers?.stop();
54 app?.close();
55 await rm(dataDir, { recursive: true, force: true });
56 });
57
58 const name = (r: Repo) => `${r.ownerName}/${r.name}`;
59
60 test("the web forks page says each mode's phrase beside the fork; only the severed one is dimmed", async () => {
61 const html = await (await fetch(`${servers.url}/ann/yard/forks`)).text();
62 const rowOf = (r: Repo): string => {
63 const at = html.indexOf(`href="/${name(r)}"`);
64 expect(at).toBeGreaterThan(0);
65 return html.slice(Math.max(0, html.lastIndexOf("<li", at)), html.indexOf("</li>", at));
66 };
67 for (const [mode, repo] of kids) {
68 const row = rowOf(repo);
69 expect(row).toContain(`>${FOLLOW_PHRASE[mode]}<`);
70 expect(row.includes("data-severed")).toBe(mode === "dont-follow");
71 }
72 expect(FOLLOW_PHRASE["take-updates"]).toBe("follows automatically");
73 expect(FOLLOW_PHRASE["tell-me"]).toBe("proposes only");
74 expect(FOLLOW_PHRASE["dont-follow"]).toContain("no longer follows");
75 });
76
77 test("the terminal's forks rows say the same phrase from the same table", async () => {
78 const ranked = await rankedForksOf(app, root, listForks(app.db, root.id));
79 const modes = forkFollowModes(app.db, [...kids.values()].map((r) => r.id));
80 const rows = forkRows(ranked, [], modes);
81 for (const [mode, repo] of kids) expect(rows.find((r) => r.name === name(repo))?.words).toContain(FOLLOW_PHRASE[mode]);
82 });
83
84 test("the terminal's tree lines say the phrase beside each node", () => {
85 const lines = treeLines(forkTree(app.db, root, ann), name(root), 120);
86 for (const [mode, repo] of kids) expect(lines.find((l) => l.includes(name(repo)))).toContain(FOLLOW_PHRASE[mode]);
87 });
88
89 test("the tree's phrase comes from one function: offers is tell-me, the root says nothing", () => {
90 expect(treeFollowPhrase("offers")).toBe(FOLLOW_PHRASE["tell-me"]);
91 expect(treeFollowPhrase("take-updates")).toBe(FOLLOW_PHRASE["take-updates"]);
92 expect(treeFollowPhrase("dont-follow")).toBe(FOLLOW_PHRASE["dont-follow"]);
93 expect(treeFollowPhrase("autonomous")).toBe("");
94 });
95
96 test("a nested fork row says its phrase on the web and in the terminal", async () => {
97 const bea = kids.get("take-updates")!;
98 const eve = must(await createUser(app.db, { origin: "seed", trusted: true, username: "eve", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: false }));
99 must(setRole(app, ann, "eve", "member"));
100 const deep = must(await forkRepo(app, eve, bea));
101 setForkFollowMode(app.db, deep.id, "tell-me");
102 const html = await (await fetch(`${servers.url}/ann/yard/forks`)).text();
103 const at = html.indexOf(`href="/${name(deep)}"`);
104 expect(at).toBeGreaterThan(0);
105 expect(html.slice(at, html.indexOf("</li>", at))).toContain(`>${FOLLOW_PHRASE["tell-me"]}<`);
106 const line = treeLines(forkTree(app.db, root, ann), name(root), 160).find((l) => l.includes(name(deep)));
107 expect(line).toContain(FOLLOW_PHRASE["tell-me"]);
108 expect(line!.startsWith(" ")).toBe(true);
109 });
110
111 test("an archived repo's fork row has no dangling separator", async () => {
112 app.db.query("UPDATE repo SET archived_at = ? WHERE id = ?").run(new Date().toISOString(), root.id);
113 const html = await (await fetch(`${servers.url}/ann/yard/forks`)).text();
114 const cal = kids.get("tell-me")!;
115 const at = html.indexOf(`href="/${name(cal)}"`);
116 const row = html.slice(at, html.indexOf("</li>", at));
117 expect(row).toContain(FOLLOW_PHRASE["tell-me"]);
118 expect(row).not.toMatch(/·\s*(<\/|$)/);
119 expect(row).not.toMatch(/·\s*·/);
120 });
test/fork-tree-reader.test.ts +2 −2
@@ -146,9 +146,9 @@ describe("the terminal screen", () => {
146146 const { treeLines } = await import("../src/tui/screens/fork_tree.ts");
147147 const lines = treeLines(forkTree(app.db, org, users["dan"]!), "bob/app");
148148 expect(lines).toContain("alice/app");
149 expect(lines).toContain(" * bob/app proposes");
149 expect(lines).toContain(" * bob/app proposes only");
150150 const own = treeLines(forkTree(app.db, person, users["dan"]!), "dan/app");
151 expect(own).toContain(" * dan/app follows");
151 expect(own).toContain(" * dan/app follows automatically");
152152 expect(lines.join("\n")).not.toContain("offers");
153153 expect(lines.join("\n")).not.toContain("secret");
154154 expect(treeLines(forkTree(app.db, hidden, users["dan"]!), "erin/secret")).toEqual(["Nothing to show."]);

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs