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

Each fork in the tree shows how many changes it is behind its upstream as one chip #15117

Merged opened this

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

Merged

scout/forge:scout/15106-each-fork-in-the-tree-shows-how-many-cha → main 6 commits fork 2 threads · 2 unresolved

  • Merged. scout/15106-each-fork-in-the-tree-shows-how-many-cha was merged into main as 3cb0bf4.

Review

Sign in to review this change.
8 files changed +126 −8
docs/features/fork-chip.md added +15
@@ -0,0 +1,15 @@
1 ---
2 topic: What a forge is
3 row: The chip on each fork in the tree
4 ---
5 # The chip on each fork in the tree
6
7 Each fork row of the tree ends in one chip for how far it is behind the repo
8 it follows: `N behind`, `up to date`, or `behind unknown` when its standing
9 cannot be read (a missing repository, no default branch). The top of the chain
10 follows nothing and has no chip.
11
12 - In the terminal: the fork tree screen prints the chip after the follow word.
13 - For tools: the MCP `explore` tool with view `tree` returns it as `chip` on
14 each row; `standing` beside it is the longer line (ahead and behind).
15 - `up to date` means no commits behind; it says nothing about being ahead.
docs/features/fork-tree-behind.md +1 −1
@@ -12,4 +12,4 @@ never from git on the request.
1212 - In the terminal: the fork tree screen shows the same words per node.
1313 - For tools: the `fork_tree` MCP tool and the family API return the same
1414 field per node.
15 - A fork never counted shows its follow word alone.
15 - A fork never counted shows `behind unknown`; see fork-chip.
src/actions/fork_tree_rows.ts +16 −2
@@ -21,8 +21,17 @@ export interface TreeRow {
2121 readonly repo: string;
2222 /** How it follows its parent, in the Following card's line; `follows nothing` at the top of the chain. */
2323 readonly follows: string;
24 /** Commits ahead and behind its parent, as the forks page words them; null at the top. */
24 /**
25 * Commits ahead and behind its parent, as the forks page words them; null at the top. Both this
26 * and `chip` read the same drift: this is the page's full meta line (it also says ahead), the
27 * chip is its behind half alone, with the unknown case worded.
28 */
2529 readonly standing: string | null;
30 /**
31 * One chip for how far behind its parent it is: `N behind`, `up to date`, `behind unknown`; null
32 * at the top.
33 */
34 readonly chip: string | null;
2635 /** When its default branch last moved (ISO), as the page's "pushed"; null when unknown. */
2736 readonly updatedAt: string | null;
2837 }
@@ -39,13 +48,18 @@ export interface TreeRows {
3948
outdated

Reuse this in the terminal tree (src/tui) so both doors show up to date / unknown / N behind; today only this reader has it.

4049 const nameOf = (r: Repo): string => `${r.ownerName}/${r.name}`;
4150
51 /** The chip's words; the count is read from the cached drift, never from user text. */
52 export const behindChip = (behind: number | null): string =>
53 behind === null ? "behind unknown" : behind === 0 ? "up to date" : `${behind} behind`;
54
4255 async function rowOf(app: App, repo: Repo, parent: Repo | undefined): Promise<TreeRow> {
43 if (parent === undefined) return { repo: nameOf(repo), follows: FOLLOWS_NOTHING, standing: null, updatedAt: null };
56 if (parent === undefined) return { repo: nameOf(repo), follows: FOLLOWS_NOTHING, standing: null, chip: null, updatedAt: null };
4457 const [ranked] = await driftOfForks(app, parent, [repo]);
4558 return {
4659 repo: nameOf(repo),
4760 follows: followModeWords(await followModeOf(app, repo), nameOf(parent)).line,
4861 standing: ranked === undefined ? null : driftWords(ranked.drift),
62 chip: behindChip(ranked?.drift.behind ?? null),
4963 updatedAt: ranked?.pushedAt ?? null,
5064 };
5165 }
src/tui/screens/fork_tree.ts +2 −1
@@ -5,6 +5,7 @@
55 */
66
77 import { HIDDEN_FORK_WORD, agoWords, treeFollowPhrase } from "../../actions/follow_words.ts";
8 import { behindChip } from "../../actions/fork_tree_rows.ts";
89 import { forkTree, type ForkTree } from "../../actions/fork_tree.ts";
910 import { followLine } from "../../actions/follow.ts";
1011 import type { Repo } from "../../core/repos.ts";
@@ -23,7 +24,7 @@ export function treeLines(tree: ForkTree | undefined, asked: string, width = 80,
2324 if (tree === undefined) return ["Nothing to show."];
2425 const lines = tree.nodes.map((n) => {
2526 const phrase = n.word === "" ? "" : treeFollowPhrase(n.follow);
26 const behind = n.behind === null ? "" : ` · ${n.behind} behind`;
27 const behind = ` · ${behindChip(n.behind)}`;
2728 const took = n.tookAt === undefined ? "" : ` · last took ${agoWords(n.tookAt)}`;
2829 const follow = (phrase === "" ? "" : ` ${phrase}${behind}${took}`) + (n.hiddenParent === true ? ` ${HIDDEN_FORK_WORD}` : "");
2930 const you = n.repo !== asked && viewer !== undefined && n.repo.startsWith(`${viewer}/`) ? " (you)" : "";
src/web/pages/repo.ts +2 −1
@@ -48,6 +48,7 @@ import {
4848 } from "../../actions/forks.ts";
4949 import { FORK_DEFAULT_MODE, forkFollowModes, lastTookAts, type ForkFollowMode } from "../../core/fork_follow.ts";
5050 import { FOLLOW_PHRASE, agoWords, isSevered } from "../../actions/follow_words.ts";
51 import { behindChip } from "../../actions/fork_tree_rows.ts";
5152 import { keptBehind, lineageOf, MINE_ANCHOR, ownsInTree } from "../../core/following.ts";
5253 import {
5354 archivedLine,
@@ -256,7 +257,7 @@ function forkRanking(
256257 title: html`<a href="/${n.repo.ownerName}/${n.repo.name}"
257258 >${n.repo.ownerName}/${n.repo.name}</a
258259 >`,
259 meta: html`<span>${FOLLOW_PHRASE[modeOf(n.repo.id)]}</span>${behind === undefined ? "" : html` · ${behind} behind`}${took(n.repo.id) === "" ? "" : html` · ${took(n.repo.id)}`}${n.deeper === 0
260 meta: html`<span>${FOLLOW_PHRASE[modeOf(n.repo.id)]}</span>${html` · ${behindChip(behind ?? null)}`}${took(n.repo.id) === "" ? "" : html` · ${took(n.repo.id)}`}${n.deeper === 0
260261 ? html``
261262 : html` · <a href="/${n.repo.ownerName}/${n.repo.name}/forks"
262263 >and ${n.deeper} more fork${n.deeper === 1 ? "" : "s"} below</a
test/fork-tree-chip.test.ts added +87
@@ -0,0 +1,87 @@
1 /** #15106: each fork row carries one chip: `N behind`, `up to date`, or `behind unknown`. */

Add a case where driftOfForks yields no row or null behind through forkTreeRows, and a TUI test once the terminal shows the chip.

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 { commitToBranch, createRepo, forkRepo } from "../src/actions/repos.ts";
7 import { behindChip, forkTreeRows } from "../src/actions/fork_tree_rows.ts";
8 import { createApp, type App } from "../src/app.ts";
9 import { setForkFollowMode } from "../src/core/fork_follow.ts";
10 import { getRepo } from "../src/core/repos.ts";
11 import { createUser } from "../src/core/users.ts";
12 import { treeLines } from "../src/tui/screens/fork_tree.ts";
13 import { promote } from "./helpers/members.ts";
14
15 let dataDir = "";
16 let app: App;
17 const users: Record<string, any> = {};
18 const must = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
19 if (!r.ok) throw new Error(JSON.stringify(r.error));
20 return r.value;
21 };
22
23 beforeAll(async () => {
24 dataDir = await mkdtemp(join(tmpdir(), "forge-chip-"));
25 app = createApp({ dataDir, port: 0 });
26 for (const name of ["ann", "bea"]) {
27 users[name] = must(await createUser(app.db, { origin: "seed", trusted: true, username: name, email: `${name}@f.dev`, password: "a-good-passphrase", adminIfFirst: name === "ann" }));
28 promote(app.db, users[name]);
29 }
30 const lib = must(await createRepo(app, users["ann"], { name: "lib", visibility: "public" }));
31 must(await commitToBranch(app, users["ann"], lib, { message: "start", files: [{ path: "a.txt", content: "a\n" }] }));
32 must(await forkRepo(app, users["bea"], lib));
33 // The fork must not follow on its own, or it would catch up as the parent moves.
34 setForkFollowMode(app.db, getRepo(app.db, "bea", "lib")!.id, "tell-me");
35 }, 30_000);
36
37 afterAll(async () => {
38 app?.close();
39 await rm(dataDir, { recursive: true, force: true });
40 });
41
42 const chips = async () => {
43 const rows = await forkTreeRows(app, getRepo(app.db, "ann", "lib")!, undefined);
44 return { top: rows.app.chip, fork: rows.forks[0]?.chip };
45 };
46
47 test("equal tips say up to date; the top of the chain has no chip", async () => {
48 expect(await chips()).toEqual({ top: null, fork: "up to date" });
49 });
50
51 test("a parent that moved on leaves the fork N behind", async () => {
52 const lib = getRepo(app.db, "ann", "lib")!;
53 must(await commitToBranch(app, users["ann"], lib, { message: "two", files: [{ path: "b.txt", content: "b\n" }] }));
54 must(await commitToBranch(app, users["ann"], lib, { message: "three", files: [{ path: "c.txt", content: "c\n" }] }));
55 expect((await chips()).fork).toBe("2 behind");
56 });
57
58 test("an unreadable standing is unknown, not zero", () => {
59 expect(behindChip(null)).toBe("behind unknown");
60 expect(behindChip(0)).toBe("up to date");
61 expect(behindChip(1)).toBe("1 behind");
62 });
63
64 test("a fork whose repository cannot be read is behind unknown through forkTreeRows", async () => {
65 const fork = getRepo(app.db, "bea", "lib")!;
66 await rm(join(app.reposRoot, "bea", "lib.git"), { recursive: true, force: true });
67 await rm(join(app.reposRoot, "bea", "lib"), { recursive: true, force: true });
68 const rows = await forkTreeRows(app, getRepo(app.db, "ann", "lib")!, undefined);
69 expect(rows.forks[0]?.repo).toBe(`${fork.ownerName}/${fork.name}`);
70 expect(rows.forks[0]?.chip).toBe("behind unknown");
71 expect(rows.forks[0]?.standing).toBe("standing unknown");
72 });
73
74 test("the terminal tree prints the same chip: N behind, up to date, behind unknown", () => {
75 const node = (repo: string, behind: number | null) => ({ repo, parent: "ann/lib", depth: 1, follow: "offers" as const, word: "proposes", behind });
76 const tree = {
77 root: "ann/lib",
78 truncated: false,
79 nodes: [{ repo: "ann/lib", parent: null, depth: 0, follow: "autonomous" as const, word: "", behind: null }, node("a/x", 2), node("b/x", 0), node("c/x", null)],
80 };
81 const lines = treeLines(tree, "ann/lib", 160);
82 expect(lines[0]).not.toContain("behind");
83 expect(lines[0]).not.toContain("up to date");
84 expect(lines[1]).toContain("2 behind");
85 expect(lines[2]).toContain("up to date");
86 expect(lines[3]).toContain("behind unknown");
87 });
test/fork-tree-follow.test.ts +1 −1
@@ -113,7 +113,7 @@ test("the terminal and the web page say the same: N behind once counted, 0 inclu
113113 const tree = forkTree(app.db, top, ann, app);
114114 const lines = treeLines(tree, name(top), 160);
115115 expect(lines.find((l) => l.includes(name(leaf)))).toContain("1 behind");
116 expect(lines.find((l) => l.includes(name(twin)))).toContain("0 behind");
116 expect(lines.find((l) => l.includes(name(twin)))).toContain("up to date");
117117 expect(lines.find((l) => l.includes(name(top)))).not.toContain("behind");
118118 expect(lines.find((l) => l.includes(name(mid)))).toContain(`${nodeOf(tree, mid).behind} behind`);
119119 const html = await (await fetch(`${servers.url}/${name(top)}/forks`)).text();
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"]!, app), "bob/app");
148148 expect(lines).toContain("alice/app");
149 expect(lines).toContain(" * bob/app proposes only");
149 expect(lines).toContain(" * bob/app proposes only · behind unknown");
150150 const own = treeLines(forkTree(app.db, person, users["dan"]!, app), "dan/app");
151 expect(own).toContain(" * dan/app follows automatically");
151 expect(own).toContain(" * dan/app follows automatically · behind unknown");
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"]!, app), "erin/secret")).toEqual(["Nothing to show."]);

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs