Public: anyone can read this; the crew can change it.
A fork tree reader returns an app's ancestors, siblings and descendants as plain data, filtered by what the caller may read #10510
scout/forge:scout/10508-a-fork-tree-reader-returns-an-app-s-ance → main 5 commits fork
4 files
changed +206
−2
scripts/hollow-allow.ts +7 −1
| @@ -18,4 +18,10 @@ export type Allowed = { | ||
| 18 | 18 | issue: number; |
| 19 | 19 | }; |
| 20 | 20 | |
| 21 | export const ALLOWED: readonly Allowed[] = []; | |
| 21 | export const ALLOWED: readonly Allowed[] = [ | |
| 22 | { | |
| 23 | orphan: "src/actions/fork_tree.ts#forkTree", | |
| 24 | reason: "the data half of the fork tree; its HTTP and MCP doors are split off #10388", | |
| 25 | issue: 10388, | |
| 26 | }, | |
| 27 | ]; |
scripts/unreached-allow.json +1 −1
| @@ -1,4 +1,5 @@ | ||
| 1 | 1 | [ |
| 2 | "src/actions/fork_tree.ts", | |
| 2 | 3 | "src/apps/cloud.ts", |
| 3 | 4 | "src/boards/machine.ts", |
| 4 | 5 | "src/crew/governor_log.ts", |
| @@ -15,7 +16,6 @@ | ||
| 15 | 16 | "src/flow/review_rounds.ts", |
| 16 | 17 | "src/flow/shared_red.ts", |
| 17 | 18 | "src/flow/stale_fold.ts", |
| 18 | "src/kernel/why_now.ts", | |
| 19 | 19 | "src/spawn/pod.ts", |
| 20 | 20 | "src/tui/gallery.ts", |
| 21 | 21 | "src/tui/ui/qr.ts", |
src/actions/fork_tree.ts added +96
| @@ -0,0 +1,96 @@ | ||
| 1 | /** | |
| 2 | * An app's place in its fork tree as plain data: its ancestors up to the | |
| 3 | * root the caller may read, then every readable descendant of that root | |
| 4 | * breadth-first (so siblings come with it). No git is read. | |
| 5 | */ | |
| 6 | ||
| 7 | import type { Database } from "bun:sqlite"; | |
| 8 | import { forkParentFor, visibleForks, type Repo } from "../core/repos.ts"; | |
| 9 | import { forkFollowMode } from "../core/fork_follow.ts"; | |
| 10 | import type { User } from "../core/users.ts"; | |
| 11 | ||
| 12 | /** How far below the root the tree is walked when the caller does not say. */ | |
| 13 | export const DEFAULT_TREE_DEPTH = 4; | |
| 14 | /** The deepest a caller may ask for; more is clamped, not refused. */ | |
| 15 | export const MAX_TREE_DEPTH = 8; | |
| 16 | /** Most nodes returned; past it `truncated` is true. Bounds the work of one call. */ | |
| 17 | export const MAX_TREE_NODES = 200; | |
| 18 | ||
| 19 | export type TreeFollow = "take-updates" | "offers" | "autonomous"; | |
| 20 | ||
| 21 | export interface TreeNode { | |
| 22 | readonly repo: string; | |
| 23 | readonly parent: string | null; | |
| 24 | readonly depth: number; | |
| 25 | readonly follow: TreeFollow; | |
| 26 | } | |
| 27 | ||
| 28 | export interface ForkTree { | |
| 29 | readonly root: string; | |
| 30 | readonly nodes: TreeNode[]; | |
| 31 | readonly truncated: boolean; | |
| 32 | } | |
| 33 | ||
| 34 | const nameOf = (r: Repo): string => `${r.ownerName}/${r.name}`; | |
| 35 | ||
| 36 | /** A fork that follows nothing (the root) is autonomous; "tell-me" is the fork offering back. */ | |
| 37 | function followOf(db: Database, repo: Repo, hasParent: boolean): TreeFollow { | |
| 38 | if (!hasParent) return "autonomous"; | |
| 39 | return forkFollowMode(db, repo.id) === "take-updates" ? "take-updates" : "offers"; | |
| 40 | } | |
| 41 | ||
| 42 | const clamp = (n: number | undefined, fallback: number, max: number): number => | |
| 43 | n === undefined || !Number.isFinite(n) ? fallback : Math.min(max, Math.max(0, Math.floor(n))); | |
| 44 | ||
| 45 | export function forkTree( | |
| 46 | db: Database, | |
| 47 | repo: Repo, | |
| 48 | user: User | undefined, | |
| 49 | opts: { depth?: number; limit?: number } = {}, | |
| 50 | ): ForkTree { | |
| 51 | const depthCap = clamp(opts.depth, DEFAULT_TREE_DEPTH, MAX_TREE_DEPTH); | |
| 52 | const limit = Math.max(1, clamp(opts.limit, MAX_TREE_NODES, MAX_TREE_NODES)); | |
| 53 | ||
| 54 | // Ancestors: each hop only while the caller may read the parent. | |
| 55 | const seen = new Set<string>([repo.id]); | |
| 56 | const chain: Repo[] = [repo]; | |
| 57 | for (let at = repo; ; ) { | |
| 58 | const up = forkParentFor(db, at, user); | |
| 59 | if (up === undefined || seen.has(up.id)) break; | |
| 60 | seen.add(up.id); | |
| 61 | chain.push(up); | |
| 62 | at = up; | |
| 63 | } | |
| 64 | chain.reverse(); // root first | |
| 65 | const root = chain[0]!; | |
| 66 | ||
| 67 | // Breadth-first from the root. The path down to `repo` is kept past the | |
| 68 | // depth cap so the node asked about is always in its own tree. | |
| 69 | const onPath = new Set(chain.map((r) => r.id)); | |
| 70 | const nodes: TreeNode[] = []; | |
| 71 | const visited = new Set<string>([root.id]); | |
| 72 | const add = (r: Repo, parent: Repo | undefined, depth: number): void => { | |
| 73 | nodes.push({ | |
| 74 | repo: nameOf(r), | |
| 75 | parent: parent === undefined ? null : nameOf(parent), | |
| 76 | depth, | |
| 77 | follow: followOf(db, r, parent !== undefined), | |
| 78 | }); | |
| 79 | }; | |
| 80 | add(root, undefined, 0); | |
| 81 | let level: Repo[] = [root]; | |
| 82 | for (let depth = 1; level.length > 0; depth++) { | |
| 83 | const next: Repo[] = []; | |
| 84 | for (const parent of level) { | |
| 85 | for (const kid of visibleForks(db, parent.id, user)) { | |
| 86 | if (visited.has(kid.id) || (depth > depthCap && !onPath.has(kid.id))) continue; | |
| 87 | if (nodes.length >= limit) return { root: nameOf(root), nodes, truncated: true }; | |
| 88 | visited.add(kid.id); | |
| 89 | add(kid, parent, depth); | |
| 90 | next.push(kid); | |
| 91 | } | |
| 92 | } | |
| 93 | level = next; | |
| 94 | } | |
| 95 | return { root: nameOf(root), nodes, truncated: false }; | |
| 96 | } |
test/fork-tree-reader.test.ts added +102
| @@ -0,0 +1,102 @@ | ||
| 1 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 2 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 3 | import { tmpdir } from "node:os"; | |
| 4 | import { join } from "node:path"; | |
| 5 | import { createRepo, forkRepo } from "../src/actions/repos.ts"; | |
| 6 | import { forkTree, MAX_TREE_NODES } from "../src/actions/fork_tree.ts"; | |
| 7 | import { getRepo } from "../src/core/repos.ts"; | |
| 8 | import { setForkFollowMode } from "../src/core/fork_follow.ts"; | |
| 9 | import { createApp, type App } from "../src/app.ts"; | |
| 10 | import { createUser, type User } from "../src/core/users.ts"; | |
| 11 | import { statements } from "./helpers/statements.ts"; | |
| 12 | import { expectWork } from "./helpers/work.ts"; | |
| 13 | import { promote } from "./helpers/members.ts"; | |
| 14 | ||
| 15 | const must = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => { | |
| 16 | if (!r.ok) throw new Error(JSON.stringify(r.error)); | |
| 17 | return r.value; | |
| 18 | }; | |
| 19 | ||
| 20 | let dataDir: string; | |
| 21 | let app: App; | |
| 22 | const users: Record<string, User> = {}; | |
| 23 | const repo = (o: string, n: string) => getRepo(app.db, o, n)!; | |
| 24 | ||
| 25 | beforeAll(async () => { | |
| 26 | dataDir = await mkdtemp(join(tmpdir(), "forge-fork-tree-reader-")); | |
| 27 | app = createApp({ dataDir, port: 0 }); | |
| 28 | for (const name of ["alice", "acme", "bob", "carol", "dan", "stranger"]) { | |
| 29 | users[name] = must( | |
| 30 | await createUser(app.db, { | |
| 31 | origin: "seed", | |
| 32 | trusted: true, | |
| 33 | username: name, | |
| 34 | email: `${name}@f.dev`, | |
| 35 | password: "a-good-passphrase", | |
| 36 | adminIfFirst: name === "alice", | |
| 37 | }), | |
| 38 | ); | |
| 39 | promote(app.db, users[name]!); | |
| 40 | } | |
| 41 | const root = must(await createRepo(app, users["alice"]!, { name: "app", visibility: "public" })); | |
| 42 | const acme = must(await forkRepo(app, users["acme"]!, root)); | |
| 43 | const bob = must(await forkRepo(app, users["bob"]!, acme)); | |
| 44 | must(await forkRepo(app, users["carol"]!, root)); // a sibling of acme's fork | |
| 45 | must(await forkRepo(app, users["dan"]!, bob, "secret", { visibility: "private" })); | |
| 46 | must(await forkRepo(app, users["dan"]!, getRepo(app.db, "dan", "secret")!, "deep", { visibility: "public" })); | |
| 47 | setForkFollowMode(app.db, bob.id, "take-updates"); | |
| 48 | }, 60_000); | |
| 49 | ||
| 50 | afterAll(async () => { | |
| 51 | app.close(); | |
| 52 | await rm(dataDir, { recursive: true, force: true }); | |
| 53 | }); | |
| 54 | ||
| 55 | describe("forkTree", () => { | |
| 56 | test("read from the middle: ancestors, then every descendant of the root", () => { | |
| 57 | const t = forkTree(app.db, repo("acme", "app"), users["stranger"]); | |
| 58 | expect(t.root).toBe("alice/app"); | |
| 59 | expect(t.truncated).toBe(false); | |
| 60 | expect(t.nodes).toEqual([ | |
| 61 | { repo: "alice/app", parent: null, depth: 0, follow: "autonomous" }, | |
| 62 | { repo: "acme/app", parent: "alice/app", depth: 1, follow: "offers" }, | |
| 63 | { repo: "carol/app", parent: "alice/app", depth: 1, follow: "offers" }, | |
| 64 | { repo: "bob/app", parent: "acme/app", depth: 2, follow: "take-updates" }, | |
| 65 | ]); | |
| 66 | }); | |
| 67 | ||
| 68 | test("a private fork and everything under it is gone for a stranger, present for its owner", () => { | |
| 69 | const names = (u: User | undefined) => forkTree(app.db, repo("bob", "app"), u).nodes.map((n) => n.repo); | |
| 70 | const stranger = names(users["stranger"]); | |
| 71 | expect(stranger.join()).not.toContain("secret"); | |
| 72 | expect(stranger.join()).not.toContain("deep"); | |
| 73 | const owner = names(users["dan"]); | |
| 74 | expect(owner).toContain("dan/secret"); | |
| 75 | expect(owner).toContain("dan/deep"); | |
| 76 | expect(owner).not.toEqual(stranger); | |
| 77 | }); | |
| 78 | ||
| 79 | test("depth is capped and the asked-for node stays in", () => { | |
| 80 | const t = forkTree(app.db, repo("alice", "app"), users["dan"], { depth: 1 }); | |
| 81 | expect(t.nodes.map((n) => n.repo).sort()).toEqual(["acme/app", "alice/app", "carol/app"]); | |
| 82 | expect(forkTree(app.db, repo("alice", "app"), users["dan"], { depth: 99 }).nodes.length).toBe(6); | |
| 83 | }); | |
| 84 | ||
| 85 | test("nodes are capped and truncation is said; 200 forks cost a bounded count of statements", async () => { | |
| 86 | const root = repo("alice", "app"); | |
| 87 | const ins = app.db.query( | |
| 88 | "INSERT INTO repo (id, owner_id, name, visibility, fork_parent_id) VALUES (?1, ?2, ?3, 'public', ?4)", | |
| 89 | ); | |
| 90 | for (let i = 0; i < MAX_TREE_NODES; i++) ins.run(`bulk-${i}`, users["carol"]!.id, `bulk${i}`, root.id); | |
| 91 | forkTree(app.db, root, users["stranger"]); | |
| 92 | let t!: ReturnType<typeof forkTree>; | |
| 93 | const cost = await statements(app.db, async () => { | |
| 94 | t = forkTree(app.db, root, users["stranger"]); | |
| 95 | }); | |
| 96 | // One child query per visited node plus a few reads each: bounded, no git, no N+1 per row. | |
| 97 | expectWork(cost, { max: 2_000 }); | |
| 98 | expect(t.nodes.length).toBe(MAX_TREE_NODES); | |
| 99 | expect(t.truncated).toBe(true); | |
| 100 | expect(forkTree(app.db, root, users["stranger"], { limit: 5 }).nodes.length).toBe(5); | |
| 101 | }); | |
| 102 | }); |
new above
offline