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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/15106-each-fork-in-the-tree-shows-how-many-cha → main 6 commits fork 2 threads · 2 unresolved
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. | ||
| 12 | 12 | - In the terminal: the fork tree screen shows the same words per node. |
| 13 | 13 | - For tools: the `fork_tree` MCP tool and the family API return the same |
| 14 | 14 | 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 { | ||
| 21 | 21 | readonly repo: string; |
| 22 | 22 | /** How it follows its parent, in the Following card's line; `follows nothing` at the top of the chain. */ |
| 23 | 23 | 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 | */ | |
| 25 | 29 | 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; | |
| 26 | 35 | /** When its default branch last moved (ISO), as the page's "pushed"; null when unknown. */ |
| 27 | 36 | readonly updatedAt: string | null; |
| 28 | 37 | } |
| @@ -39,13 +48,18 @@ export interface TreeRows { | ||
| 39 | 48 | |
| 40 | 49 | const nameOf = (r: Repo): string => `${r.ownerName}/${r.name}`; |
| 41 | 50 | |
| 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 | ||
| 42 | 55 | 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 }; | |
| 44 | 57 | const [ranked] = await driftOfForks(app, parent, [repo]); |
| 45 | 58 | return { |
| 46 | 59 | repo: nameOf(repo), |
| 47 | 60 | follows: followModeWords(await followModeOf(app, repo), nameOf(parent)).line, |
| 48 | 61 | standing: ranked === undefined ? null : driftWords(ranked.drift), |
| 62 | chip: behindChip(ranked?.drift.behind ?? null), | |
| 49 | 63 | updatedAt: ranked?.pushedAt ?? null, |
| 50 | 64 | }; |
| 51 | 65 | } |
src/tui/screens/fork_tree.ts +2 −1
| @@ -5,6 +5,7 @@ | ||
| 5 | 5 | */ |
| 6 | 6 | |
| 7 | 7 | import { HIDDEN_FORK_WORD, agoWords, treeFollowPhrase } from "../../actions/follow_words.ts"; |
| 8 | import { behindChip } from "../../actions/fork_tree_rows.ts"; | |
| 8 | 9 | import { forkTree, type ForkTree } from "../../actions/fork_tree.ts"; |
| 9 | 10 | import { followLine } from "../../actions/follow.ts"; |
| 10 | 11 | import type { Repo } from "../../core/repos.ts"; |
| @@ -23,7 +24,7 @@ export function treeLines(tree: ForkTree | undefined, asked: string, width = 80, | ||
| 23 | 24 | if (tree === undefined) return ["Nothing to show."]; |
| 24 | 25 | const lines = tree.nodes.map((n) => { |
| 25 | 26 | const phrase = n.word === "" ? "" : treeFollowPhrase(n.follow); |
| 26 | const behind = n.behind === null ? "" : ` · ${n.behind} behind`; | |
| 27 | const behind = ` · ${behindChip(n.behind)}`; | |
| 27 | 28 | const took = n.tookAt === undefined ? "" : ` · last took ${agoWords(n.tookAt)}`; |
| 28 | 29 | const follow = (phrase === "" ? "" : ` ${phrase}${behind}${took}`) + (n.hiddenParent === true ? ` ${HIDDEN_FORK_WORD}` : ""); |
| 29 | 30 | const you = n.repo !== asked && viewer !== undefined && n.repo.startsWith(`${viewer}/`) ? " (you)" : ""; |
src/web/pages/repo.ts +2 −1
| @@ -48,6 +48,7 @@ import { | ||
| 48 | 48 | } from "../../actions/forks.ts"; |
| 49 | 49 | import { FORK_DEFAULT_MODE, forkFollowModes, lastTookAts, type ForkFollowMode } from "../../core/fork_follow.ts"; |
| 50 | 50 | import { FOLLOW_PHRASE, agoWords, isSevered } from "../../actions/follow_words.ts"; |
| 51 | import { behindChip } from "../../actions/fork_tree_rows.ts"; | |
| 51 | 52 | import { keptBehind, lineageOf, MINE_ANCHOR, ownsInTree } from "../../core/following.ts"; |
| 52 | 53 | import { |
| 53 | 54 | archivedLine, |
| @@ -256,7 +257,7 @@ function forkRanking( | ||
| 256 | 257 | title: html`<a href="/${n.repo.ownerName}/${n.repo.name}" |
| 257 | 258 | >${n.repo.ownerName}/${n.repo.name}</a |
| 258 | 259 | >`, |
| 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 | |
| 260 | 261 | ? html`` |
| 261 | 262 | : html` · <a href="/${n.repo.ownerName}/${n.repo.name}/forks" |
| 262 | 263 | >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 | ||
| 113 | 113 | const tree = forkTree(app.db, top, ann, app); |
| 114 | 114 | const lines = treeLines(tree, name(top), 160); |
| 115 | 115 | 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"); | |
| 117 | 117 | expect(lines.find((l) => l.includes(name(top)))).not.toContain("behind"); |
| 118 | 118 | expect(lines.find((l) => l.includes(name(mid)))).toContain(`${nodeOf(tree, mid).behind} behind`); |
| 119 | 119 | 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", () => { | ||
| 146 | 146 | const { treeLines } = await import("../src/tui/screens/fork_tree.ts"); |
| 147 | 147 | const lines = treeLines(forkTree(app.db, org, users["dan"]!, app), "bob/app"); |
| 148 | 148 | expect(lines).toContain("alice/app"); |
| 149 | expect(lines).toContain(" * bob/app proposes only"); | |
| 149 | expect(lines).toContain(" * bob/app proposes only · behind unknown"); | |
| 150 | 150 | 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"); | |
| 152 | 152 | expect(lines.join("\n")).not.toContain("offers"); |
| 153 | 153 | expect(lines.join("\n")).not.toContain("secret"); |
| 154 | 154 | expect(treeLines(forkTree(app.db, hidden, users["dan"]!, app), "erin/secret")).toEqual(["Nothing to show."]); |
new above
offline
Reuse this in the terminal tree (src/tui) so both doors show up to date / unknown / N behind; today only this reader has it.