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

Taking updates from upstream passes the forge's own gate: the merge is judged as an update, not as one pull #13758

Merged opened this in answer to

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

Merged

scout/forge:scout/13751-taking-updates-from-upstream-passes-the → main 3 commits fork 2 threads · 2 unresolved

  • Merged. scout/13751-taking-updates-from-upstream-passes-the was merged into main as 5e4406a.

Review

Sign in to review this change.
4 files changed +174 −18
AGENTS.md +1
@@ -7,6 +7,7 @@ Read the guide first, in this order: `docs/guide-what-a-forge-is.md`, `docs/guid
77 README.md is capped: a new feature's how-to goes in `docs/features/<name>.md`, not a new README section.
88 A pull that adds a page (`src/web/pages/*.ts`) also adds a terminal screen under `src/tui/screens/` that another module imports (its palette entry) and a `docs/features/<name>.md`, or a commit line `No door: <why>`; a new `src/web/render/*.ts`, `src/web/studio/*.ts` or `src/actions/*.ts` is asked for the screen alone, and a new feature module under `src/` in a pull that edits an existing page is asked for both, and a pull that edits an existing page (or any shared `src/web/` file, #13376: a new feature module wired into it is asked for both) changes something under `src/tui/` and a `docs/features/*.md` too (#13196); `bun scripts/gate.ts` refuses it otherwise ("both doors", #10628).
99 A pull that changes `src/web/` (a `.ts` or `.css`) names, in a commit line `Looks: <path>`, the page of `app.looks` in forge.json whose before/after pictures show it, or says `No look: <why>`; `bun scripts/gate.ts` refuses it otherwise ("before/after looks", #12362).
10 An update pull (upstream's main merged into a fork, #13751) is a merge commit named `Take updates from <upstream>` whose second parent is upstream's main: the tip or an ancestor of `FORGE_CHECK_UPSTREAM`, `origin/upstream-main` or `upstream/main`. The name alone is not trusted; when the second parent cannot be verified the pull is judged whole. A verified update is judged by its first side (`HEAD^1`, the fork's own work) for the Try line, both doors, pipeline-first, the added-lines rules, the README cap and the dependency rule; the tests still run whole.
1011
1112 When you write an issue, end it with a `Files:` line naming the files the work touches (`Files: src/a.ts, docs/b.md`). The hot-file hold reads only that line when it is there; without it, every path the issue mentions counts.
1213
scripts/gate.ts +51 −13
@@ -501,6 +501,37 @@ export function reviewRefusal(root = "."): string[] {
501501 return reviewProblems([...tests, ...code]);
502502 }
503503
504 /**
505 * The refs that carry upstream's main in a check's clone: `FORGE_CHECK_UPSTREAM` (a ref or commit
506 * id the check names) first, then the mirror refs a fork keeps.
507 */
508 function upstreamTips(cwd: string): string[] {
509 const named = process.env.FORGE_CHECK_UPSTREAM?.trim();
510 return [named, "origin/upstream-main", "upstream/main"].filter((r): r is string => !!r && git(["rev-parse", "--verify", "-q", `${r}^{commit}`], cwd).ok);
511 }
512
513 /**
514 * The head the pull rules judge (#13751). An update pull is upstream's main merged into the fork:
outdated

The subject regex is the whole trust boundary and anyone can write it. Verify that HEAD^2 is reachable from upstream main, and fail closed to HEAD when it cannot be verified.

515 * a merge commit named "Take updates from <upstream>" whose second parent is upstream's own main
516 * (its tip or an ancestor of it), so its commits already passed upstream's rules there. The name
517 * alone proves nothing, so the second parent is checked against upstream's main in the clone; when
518 * that cannot be verified the pull is judged whole. An update is judged by its first side,
519 * `HEAD^1`, the fork's own work. The tests still run whole. Any other head is `HEAD`.
outdated

isUpdatePull skips the dependency and README-cap rules for the whole pull, untested. Use the HEAD^1 judgement here as well, or add tests.

520 */
521 export function judgedHead(cwd: string = process.cwd()): string {
522 const parents = git(["rev-list", "--parents", "-n", "1", "HEAD"], cwd);
523 if (!parents.ok || parents.out.split(" ").length !== 3) return "HEAD";
524 const subject = git(["log", "-1", "--format=%s", "HEAD"], cwd);
525 if (!subject.ok || !/^Take updates from \S/.test(subject.out)) return "HEAD";
526 if (!git(["rev-parse", "--verify", "-q", "HEAD^1"], cwd).ok) return "HEAD";
527 const second = parents.out.split(" ")[2] ?? "";
528 const onUpstream = upstreamTips(cwd).some((tip) => git(["merge-base", "--is-ancestor", second, tip], cwd).ok);
529 return onUpstream ? "HEAD^1" : "HEAD";
530 }
531
532 /** True when the pull is an update from upstream, whose own writing there is not judged again. */
533 export const isUpdatePull = (cwd: string = process.cwd()): boolean => judgedHead(cwd) !== "HEAD";
534
504535 /**
505536 * The files the comment rewrapper judges: what this pull's commits change under `src/`, `test/`
506537 * and `scripts/`, so a pull is never stopped by a line it did not write and a file is rewrapped
@@ -521,7 +552,7 @@ function wrapSources(root: string, all: boolean, working = false): { path: strin
521552 const base =
522553 process.env.FORGE_CHECK_BASE || git(["merge-base", "origin/main", "HEAD"], root).out || git(["merge-base", "main", "HEAD"], root).out;
523554 if (!base) return [];
524 const changed = git(["diff", "--name-only", "--diff-filter=d", ...(working ? [base] : [`${base}..HEAD`]), "--", ...dirs], root);
555 const changed = git(["diff", "--name-only", "--diff-filter=d", ...(working ? [base] : [`${base}..${judgedHead(root)}`]), "--", ...dirs], root);
525556 const fresh = working ? git(["ls-files", "--others", "--exclude-standard", "--", ...dirs], root) : { ok: false, out: "" };
526557 paths = [...new Set([...(changed.ok ? changed.out.split("\n") : []), ...(fresh.ok ? fresh.out.split("\n") : [])])];
527558 }
@@ -567,7 +598,7 @@ export async function addedRefusal(cwd: string = process.cwd()): Promise<string[
567598 git(["merge-base", "origin/main", "HEAD"], cwd).out ||
568599 git(["merge-base", "main", "HEAD"], cwd).out;
569600 if (!base) return [];
570 const diff = git(["diff", "-U0", "--no-color", "--no-ext-diff", `${base}..HEAD`, "--", "src", "test"], cwd);
601 const diff = git(["diff", "-U0", "--no-color", "--no-ext-diff", `${base}..${judgedHead(cwd)}`, "--", "src", "test"], cwd);
571602 return diff.ok ? addedProblems(parseAdded(diff.out)) : [];
572603 }
573604
@@ -583,8 +614,8 @@ export async function tryItRefusal(cwd: string = process.cwd()): Promise<string[
583614 git(["merge-base", "origin/main", "HEAD"], cwd).out ||
584615 git(["merge-base", "main", "HEAD"], cwd).out;
585616 if (!base) return [];
586 const diff = git(["diff", "--name-status", "-M", `${base}..HEAD`], cwd);
587 const log = git(["log", "--format=%B%x00", `${base}..HEAD`], cwd);
617 const diff = git(["diff", "--name-status", "-M", `${base}..${judgedHead(cwd)}`], cwd);
618 const log = git(["log", "--format=%B%x00", `${base}..${judgedHead(cwd)}`], cwd);
588619 if (!diff.ok || !log.ok) return [];
589620 return tryItProblems(parseNameStatus(diff.out), log.out.split("\0").map((m) => m.trim()).filter(Boolean));
590621 }
@@ -598,8 +629,8 @@ export async function bothDoorsRefusal(cwd: string = process.cwd()): Promise<str
598629 git(["merge-base", "origin/main", "HEAD"], cwd).out ||
599630 git(["merge-base", "main", "HEAD"], cwd).out;
600631 if (!base) return [];
601 const diff = git(["diff", "--name-status", "-M", `${base}..HEAD`], cwd);
602 const log = git(["log", "--format=%B%x00", `${base}..HEAD`], cwd);
632 const diff = git(["diff", "--name-status", "-M", `${base}..${judgedHead(cwd)}`], cwd);
633 const log = git(["log", "--format=%B%x00", `${base}..${judgedHead(cwd)}`], cwd);
603634 if (!diff.ok || !log.ok) return [];
604635 const { readTui, screenOpened } = await import("../src/kernel/tui_entry.ts");
605636 const changes = parseNameStatus(diff.out);
@@ -623,8 +654,8 @@ export async function lookNote(cwd: string = process.cwd()): Promise<string[]> {
623654 git(["merge-base", "origin/main", "HEAD"], cwd).out ||
624655 git(["merge-base", "main", "HEAD"], cwd).out;
625656 if (!base) return [];
626 const diff = git(["diff", "--name-status", "-M", `${base}..HEAD`], cwd);
627 const log = git(["log", "--format=%B%x00", `${base}..HEAD`], cwd);
657 const diff = git(["diff", "--name-status", "-M", `${base}..${judgedHead(cwd)}`], cwd);
658 const log = git(["log", "--format=%B%x00", `${base}..${judgedHead(cwd)}`], cwd);
628659 if (!diff.ok || !log.ok) return [];
629660 let looks: string[] = [];
630661 try {
@@ -671,10 +702,10 @@ export async function directionRefusal(cwd: string = process.cwd(), run: typeof
671702 run(["merge-base", "origin/main", "HEAD"], cwd).out ||
672703 run(["merge-base", "main", "HEAD"], cwd).out;
673704 if (!base) return [];
674 const diff = run(["diff", "--name-status", "-M", `${base}..HEAD`], cwd);
675 const log = run(["log", "--format=%B%x00", `${base}..HEAD`], cwd);
705 const diff = run(["diff", "--name-status", "-M", `${base}..${judgedHead(cwd)}`], cwd);
706 const log = run(["log", "--format=%B%x00", `${base}..${judgedHead(cwd)}`], cwd);
676707 if (!diff.ok || !log.ok) return [];
677 const stat = run(["diff", "--numstat", "-z", "-M", `${base}..HEAD`], cwd);
708 const stat = run(["diff", "--numstat", "-z", "-M", `${base}..${judgedHead(cwd)}`], cwd);
678709 if (!stat.ok) return [`rule "pipeline first": could not read the pull's line counts (git diff --numstat failed), so redesigns cannot be checked`];
679710 return directionProblems(parseNameStatus(diff.out), log.out.split("\0").map((m) => m.trim()).filter(Boolean), numstatLines(stat.out));
680711 }
@@ -692,7 +723,12 @@ export async function dependencyRefusal(cwd: string = process.cwd()): Promise<st
692723 git(["merge-base", "origin/main", "HEAD"], cwd).out ||
693724 git(["merge-base", "main", "HEAD"], cwd).out;
694725 if (!base) return [];
695 const read = (path: string) => (existsSync(join(cwd, path)) ? readFileSync(join(cwd, path), "utf8") : "");
726 const head = judgedHead(cwd);
727 const read = (path: string) => {
728 if (head === "HEAD") return existsSync(join(cwd, path)) ? readFileSync(join(cwd, path), "utf8") : "";
729 const shown = git(["show", `${head}:${path}`], cwd);
730 return shown.ok ? shown.out : "";
731 };
696732 const before = git(["show", `${base}:package.json`], cwd);
697733 return dependencyProblems(before.ok ? before.out : undefined, read("package.json"), read("README.md"), read(DEPENDENCIES_DOC));
698734 }
@@ -707,8 +743,10 @@ export async function readmeCapRefusal(cwd: string = process.cwd()): Promise<str
707743 if (!base) return [];
708744 const before = git(["show", `${base}:README.md`], cwd);
709745 if (!before.ok) return [];
746 const head = judgedHead(cwd);
710747 const path = join(cwd, "README.md");
711 return readmeCapProblems(before.out, existsSync(path) ? readFileSync(path, "utf8") : undefined);
748 const after = head === "HEAD" ? (existsSync(path) ? readFileSync(path, "utf8") : undefined) : (() => { const s = git(["show", `${head}:README.md`], cwd); return s.ok ? s.out : undefined; })();
749 return readmeCapProblems(before.out, after);
712750 }
713751
714752 /**
test/gate-update-pull.test.ts added +112
@@ -0,0 +1,112 @@
1 import { afterAll, expect, test } from "bun:test";
2 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
3 import { join } from "node:path";
4 import { tmpdir } from "node:os";
5 import { addedRefusal, dependencyRefusal, judgedHead, readmeCapRefusal, tryItRefusal } from "../scripts/gate.ts";
6
7 const root = mkdtempSync(join(tmpdir(), "gate-update-"));
8 afterAll(() => rmSync(root, { recursive: true, force: true }));
9
10 const git = (cwd: string, ...args: string[]) => {
11 const r = Bun.spawnSync(["git", "-c", "user.name=t", "-c", "user.email=t@t", ...args], { cwd });
12 if (r.exitCode !== 0) throw new Error(r.stderr.toString());
13 return r.stdout.toString().trim();
14 };
15 const put = (dir: string, file: string, text: string) => {
16 mkdirSync(join(dir, file, ".."), { recursive: true });
17 writeFileSync(join(dir, file), text);
18 };
19 /** Runs `f` with the check's base and, when given, the ref the check names as upstream's main. */
20 const withBase = async <T>(base: string, f: () => Promise<T>, upstream?: string) => {
21 process.env.FORGE_CHECK_BASE = base;
22 if (upstream) process.env.FORGE_CHECK_UPSTREAM = upstream;
23 try {
24 return await f();
25 } finally {
26 delete process.env.FORGE_CHECK_BASE;
27 delete process.env.FORGE_CHECK_UPSTREAM;
28 }
29 };
30
31 type Files = Record<string, string>;
32 const SLEEP = "await Bun.sleep(5);\n"; // real-timer: fixture text written to a scratch repo, never run
33
34 /**
35 * A fork whose main has moved on, and a branch `upstream` that adds a page and a sleeping test
36 * (plus `upstreamFiles`). `forkFiles` are the fork's own commit. The merge is of `merged`: the
37 * branch `upstream`, or a branch `sneaky` that has the same files but is not upstream's.
38 */
39 function fork(name: string, mergeMessage: string, o: { forkFiles?: Files; upstreamFiles?: Files; merged?: "upstream" | "sneaky" } = {}) {
40 const dir = join(root, name);
41 mkdirSync(dir);
42 git(dir, "init", "-q", "-b", "main");
43 put(dir, "README.md", "x\n");
44 put(dir, "package.json", "{}");
45 git(dir, "add", "-A");
46 git(dir, "commit", "-qm", "base");
47 const upstreamWork: Files = { "test/a.test.ts": SLEEP, "src/web/pages/traffic.ts": "x", ...o.upstreamFiles };
48 for (const branch of ["upstream", "sneaky"]) {
49 git(dir, "checkout", "-q", "-b", branch, "main");
50 for (const [f, t] of Object.entries(branch === "upstream" && o.merged === "sneaky" ? { "other.txt": "z" } : upstreamWork)) put(dir, f, t);
51 git(dir, "add", "-A");
52 git(dir, "commit", "-qm", "Upstream work");
53 }
54 git(dir, "checkout", "-q", "main");
55 const before = git(dir, "rev-parse", "HEAD");
56 for (const [f, t] of Object.entries({ "NOTES.md": "y", ...o.forkFiles })) put(dir, f, t);
57 git(dir, "add", "-A");
58 git(dir, "commit", "-qm", "Fork work");
59 const base = git(dir, "rev-parse", "HEAD");
60 git(dir, "merge", "-q", "--no-ff", "-m", mergeMessage, o.merged ?? "upstream");
61 return { dir, base, before };
62 }
63
64 const UPDATE = "Take updates from trevato/forge";
65
66 test("an update merge is judged on its own side: upstream's commits owe no Try line and no real timer", async () => {
67 const { dir, base } = fork("update", UPDATE);
68 expect(await withBase(base, async () => judgedHead(dir), "upstream")).toBe("HEAD^1");
69 expect(await withBase(base, () => tryItRefusal(dir), "upstream")).toEqual([]);
70 expect(await withBase(base, () => addedRefusal(dir), "upstream")).toEqual([]);
71 });
72
73 test("the same merge under another name is judged whole", async () => {
74 const { dir, base } = fork("plain", "Merge upstream");
75 expect(await withBase(base, async () => judgedHead(dir), "upstream")).toBe("HEAD");
76 expect((await withBase(base, () => tryItRefusal(dir), "upstream")).length).toBe(1);
77 expect((await withBase(base, () => addedRefusal(dir), "upstream")).length).toBe(1);
78 });
79
80 test("the subject alone proves nothing: a second parent that is not upstream's is judged whole", async () => {
81 const { dir, base } = fork("impostor", UPDATE, { merged: "sneaky" });
82 expect(await withBase(base, async () => judgedHead(dir), "upstream")).toBe("HEAD");
83 expect((await withBase(base, () => tryItRefusal(dir), "upstream")).length).toBe(1);
84 expect((await withBase(base, () => addedRefusal(dir), "upstream")).length).toBe(1);
85 });
86
87 test("an update that cannot be checked against upstream is judged whole", async () => {
88 const { dir, base } = fork("unverified", UPDATE);
89 expect(await withBase(base, async () => judgedHead(dir))).toBe("HEAD");
90 expect(await withBase(base, async () => judgedHead(dir), "no-such-ref")).toBe("HEAD");
91 expect((await withBase(base, () => addedRefusal(dir))).length).toBe(1);
92 });
93
94 test("an update's first side is still judged: a fork-side line that breaks a rule is refused", async () => {
95 const { dir, base, before } = fork("fork-side", UPDATE, { forkFiles: { "test/b.test.ts": SLEEP } });
96 expect(await withBase(base, async () => judgedHead(dir), "upstream")).toBe("HEAD^1");
97 const refused = await withBase(before, () => addedRefusal(dir), "upstream");
98 expect(refused.length).toBe(1);
99 expect(refused[0]).toContain("test/b.test.ts");
100 });
101
102 test("an update's dependencies and README are judged on the first side: upstream's are not asked again, the fork's are", async () => {
103 const dep = (name: string) => JSON.stringify({ dependencies: { [name]: "1.0.0" } });
104 const theirs = fork("deps-upstream", UPDATE, { upstreamFiles: { "package.json": dep("theirs"), "README.md": "x\n## Theirs\n" } });
105 expect(await withBase(theirs.base, () => dependencyRefusal(theirs.dir), "upstream")).toEqual([]);
106 expect(await withBase(theirs.base, () => readmeCapRefusal(theirs.dir), "upstream")).toEqual([]);
107 const ours = fork("deps-fork", UPDATE, { forkFiles: { "package.json": dep("ours"), "README.md": "x\n## Ours\n" } });
108 expect((await withBase(ours.before, () => dependencyRefusal(ours.dir), "upstream")).join("\n")).toContain("ours");
109 expect((await withBase(ours.before, () => readmeCapRefusal(ours.dir), "upstream")).length).toBeGreaterThan(0);
110 const impostor = fork("deps-impostor", UPDATE, { merged: "sneaky", upstreamFiles: { "package.json": dep("theirs") } });
111 expect((await withBase(impostor.base, () => dependencyRefusal(impostor.dir), "upstream")).join("\n")).toContain("theirs");
112 });
test/stranger-three-screens.test.ts +10 −5
@@ -64,7 +64,8 @@ test("screen 1 to 2: the answer is the one page that says what is happening and
6464 expect(res.headers.get("cache-control")).toBe("no-store");
6565 const body = await res.text();
6666 expect(body).toContain("walker is made and is starting. This usually takes about 15 seconds.");
67 // Made for themselves: the account screen of their own forge, not the one for a link someone sent.
67 // Made for themselves: the account screen of their own forge, not the one for a link someone
68 // sent.
6869 expect(linkOf(body)).toMatch(/^https:\/\/walker--forge\.test\/welcome#[A-Za-z0-9_-]{43}$/);
6970 expect(body).toContain("Whoever holds this link owns the forge.");
7071 // A code a phone's camera opens, beside the link and a way to copy it.
@@ -74,14 +75,14 @@ test("screen 1 to 2: the answer is the one page that says what is happening and
7475
7576 test("the answer does not wait on the first reach proof: the page shows the start, the proof goes on behind it", async () => {
7677 const asked: string[] = [];
77 useReach(parent, { fetch: async (url) => { asked.push(String(url)); await new Promise((r) => setTimeout(r, 400)); return new Response("{}", { status: 502 }); }, settleMs: 1, pollMs: 1 });
78 useReach(parent, { fetch: async (url) => { asked.push(String(url)); await new Promise((r) => setTimeout(r, 400)); return new Response("{}", { status: 502 }); }, settleMs: 1, pollMs: 1 }); // real-timer: a proof slower than the answer
7879 const t0 = performance.now();
7980 const res = await start("quickly");
8081 await res.body?.cancel();
8182 expect(res.status).toBe(200);
8283 expect(performance.now() - t0).toBeLessThan(350);
8384 // Still proved, behind the answer.
84 await new Promise((r) => setTimeout(r, 500));
85 await new Promise((r) => setTimeout(r, 500)); // real-timer: the proof goes on behind the answer
8586 expect(asked.some((u) => u.includes("quickly--forge.test"))).toBe(true);
8687 useReach(parent, { off: true });
8788 });
@@ -96,7 +97,10 @@ test("a signed-out /forges/new answers the same page (201); the home form and it
9697 expect(home).not.toContain("data-js");
9798 });
9899
99 /** Run the made page's script against stubs; `answers` is what each ask gets. `phone` is a narrow screen. */
100 /**
101 * Run the made page's script against stubs; `answers` is what each ask gets. `phone` is a narrow
102 * screen.
103 */
100104 function runMade(answers: Array<"starting" | "answering" | "down" | "ready">, o: { phone?: boolean; own?: boolean; clock?: () => number } = {}) {
101105 const words = madeWords("walker");
102106 const says = { textContent: words.starting as string };
@@ -128,7 +132,8 @@ test("the page says each real step as it comes, and shows the link the moment th
128132 expect(w.link.hidden).toBe(false);
129133 expect(w.open.focused).toBe(1);
130134 expect(w.replaced).toEqual([]);
131 // Asked again a quarter of a second after each answer: the wait past the forge's own start is the poll, not seconds.
135 // Asked again a quarter of a second after each answer: the wait past the forge's own start is the
136 // poll, not seconds.
132137 expect(w.waits).toEqual([250, 250]);
133138 });
134139

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs