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

Automate a review finding as a lint or test: Both doors: a grant and the provider are page, API and MCP, but there is no term #14340

Merged opened this

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

Merged

scout/forge:scout/14289-automate-a-review-finding-as-a-lint-or-t → main 4 commits fork 2 threads · 2 unresolved

  • Merged. scout/14289-automate-a-review-finding-as-a-lint-or-t was merged into main as 256479e.

Review

Sign in to review this change.
4 files changed +211 −0
AGENTS.md +2
@@ -5,6 +5,8 @@ Read `CLAUDE.md` first: it is the rulebook for agents editing this repo.
55 Read the guide first, in this order: `docs/guide-what-a-forge-is.md`, `docs/guide-first-app.md`, `docs/guide-tell-the-crew.md`, `docs/guide-ship-and-undo.md`, `docs/guide-your-apps.md`, `docs/guide-hosting.md`, `docs/guide-own-ai.md`, `docs/guide-agents.md`, `docs/guide-backups-moving.md`, `docs/guide-settings.md`, `docs/guide-when-wrong.md`. That is the spine (ordered in `src/view/guide.ts`, served at `/docs` with search, listed first by /llms.txt): eleven pages, each at most 300 words and 60 lines, every command, path and link in them checked by `test/guide.test.ts`. A feature's `docs/features/<name>.md` is its reference; give it one row under its topic in `docs/features/README.md`, the index every spine page links (`test/feature-orphans.test.ts`).
66
77 README.md is capped: a new feature's how-to goes in `docs/features/<name>.md`, not a new README section.
8 Both doors are also read from the tree (#14289): `test/doorless.test.ts` fails on a page in `src/web/pages/` with no terminal door unless `scripts/doorless-allow.json` lists it (the list only shrinks; `bun scripts/doorless.ts --write` prunes). A page has a door when `src/tui/` or `src/actions/` imports it, a screen is named for it, or a features doc naming the page file names `src/tui/` too.
9
810 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); an edited API route, MCP tool or `src/actions/*.ts` changes something under `src/tui/` too (#14040); `bun scripts/gate.ts` refuses it otherwise ("both doors", #10628).
911 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).
1012 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.
scripts/doorless-allow.json added +101
@@ -0,0 +1,101 @@
1 [
2 "src/web/pages/accounts.ts",
3 "src/web/pages/admin-limits.ts",
4 "src/web/pages/app_variants.ts",
5 "src/web/pages/apps-starters.ts",
6 "src/web/pages/apps.ts",
7 "src/web/pages/asking.ts",
8 "src/web/pages/backups.ts",
9 "src/web/pages/board-notes.ts",
10 "src/web/pages/board.ts",
11 "src/web/pages/board_style.ts",
12 "src/web/pages/boards-doctor.ts",
13 "src/web/pages/boards-edit.ts",
14 "src/web/pages/boards-gates.ts",
15 "src/web/pages/boards-held.ts",
16 "src/web/pages/boards-holds.ts",
17 "src/web/pages/boards-view.ts",
18 "src/web/pages/branches.ts",
19 "src/web/pages/broker_ask.ts",
20 "src/web/pages/browse.ts",
21 "src/web/pages/build_cart.ts",
22 "src/web/pages/build_info.ts",
23 "src/web/pages/build_shots.ts",
24 "src/web/pages/claim.ts",
25 "src/web/pages/config.ts",
26 "src/web/pages/cost.ts",
27 "src/web/pages/crew-settings.ts",
28 "src/web/pages/danger.ts",
29 "src/web/pages/dep_chain.ts",
30 "src/web/pages/detach.ts",
31 "src/web/pages/edit.ts",
32 "src/web/pages/everyday.ts",
33 "src/web/pages/explorer.ts",
34 "src/web/pages/family_tree_js.ts",
35 "src/web/pages/filmstrip.ts",
36 "src/web/pages/first-admin.ts",
37 "src/web/pages/first.ts",
38 "src/web/pages/flow-estimates.ts",
39 "src/web/pages/flow-panel.ts",
40 "src/web/pages/forges-refused.ts",
41 "src/web/pages/fork-offers.ts",
42 "src/web/pages/frozen.ts",
43 "src/web/pages/gate.ts",
44 "src/web/pages/global-map.ts",
45 "src/web/pages/home_figures.ts",
46 "src/web/pages/home_flow_client.ts",
47 "src/web/pages/home_flow_style.ts",
48 "src/web/pages/home_table.ts",
49 "src/web/pages/hosted-forges.ts",
50 "src/web/pages/keeper-panel.ts",
51 "src/web/pages/kept_page.ts",
52 "src/web/pages/limb.ts",
53 "src/web/pages/limb_replan.ts",
54 "src/web/pages/limb_view.ts",
55 "src/web/pages/looks.ts",
56 "src/web/pages/maintenance_budgets.ts",
57 "src/web/pages/maintenance_pause.ts",
58 "src/web/pages/migrate-prefill.ts",
59 "src/web/pages/my-repos.ts",
60 "src/web/pages/next_chapters.ts",
61 "src/web/pages/next_keys.ts",
62 "src/web/pages/now.ts",
63 "src/web/pages/oauth.ts",
64 "src/web/pages/offer-receipt.ts",
65 "src/web/pages/offer-upstream.ts",
66 "src/web/pages/offline.ts",
67 "src/web/pages/og.ts",
68 "src/web/pages/org.ts",
69 "src/web/pages/origin-archived.ts",
70 "src/web/pages/origin-flow.ts",
71 "src/web/pages/origin-reach.ts",
72 "src/web/pages/origin-repos.ts",
73 "src/web/pages/origins.ts",
74 "src/web/pages/outside-agents-live.ts",
75 "src/web/pages/packs-settings.ts",
76 "src/web/pages/pipeline.ts",
77 "src/web/pages/plan_card.ts",
78 "src/web/pages/privacy.ts",
79 "src/web/pages/pull-combined.ts",
80 "src/web/pages/pull-guest.ts",
81 "src/web/pages/pull-spec.ts",
82 "src/web/pages/pulls.ts",
83 "src/web/pages/queue.ts",
84 "src/web/pages/returns.ts",
85 "src/web/pages/search.ts",
86 "src/web/pages/security.ts",
87 "src/web/pages/settings.ts",
88 "src/web/pages/signup-passkey.ts",
89 "src/web/pages/site.ts",
90 "src/web/pages/spend-tab.ts",
91 "src/web/pages/spend.ts",
92 "src/web/pages/start_claim.ts",
93 "src/web/pages/talk.ts",
94 "src/web/pages/talk_client.ts",
95 "src/web/pages/talk_preview.ts",
96 "src/web/pages/tree_cache.ts",
97 "src/web/pages/upstream-follow.ts",
98 "src/web/pages/usage-tabs.ts",
99 "src/web/pages/visitors.ts",
100 "src/web/pages/waking.ts"
101 ]
scripts/doorless.ts added +50
@@ -0,0 +1,50 @@
1 /**
2 * Pages with no terminal door (#14289). Reviewers wrote "both doors: no screen in src/tui/"
3 * of a page that shipped without one (#11150, #11901, #12566, #11841); the diff rule
4 * (`src/kernel/both_doors.ts`) only sees a pull as it lands, so this reads the tree: every
5 * `src/web/pages/<name>.ts` has a terminal door, or is listed in `scripts/doorless-allow.json`.
6 *
7 * A page has a door when a file under `src/tui/` or `src/actions/` imports it, a screen is
8 * named for it (`<name>.ts`, dashes or none), or a `docs/features/*.md` that names the page
9 * file also names a `src/tui/` file that exists (the how-to says where the terminal shows it). The
10 * list only shrinks: `--write` prunes the pages that gained a door.
11 */
12
13 import { existsSync, readFileSync, writeFileSync } from "node:fs";
14 import { basename, join } from "node:path";
15
16 const files = (root: string, glob: string) => [...new Bun.Glob(glob).scanSync({ cwd: root })].sort();
17
18 /** `src/web/pages/<name>.ts` for each page without a terminal door, sorted. */
19 export function doorlessPages(root: string): string[] {
20 const read = (f: string) => readFileSync(join(root, f), "utf8");
21 const pages = files(root, "src/web/pages/*.ts").filter((f) => !f.endsWith(".test.ts"));
22 const doors = files(root, "src/{tui,actions}/**/*.ts").map(read).join("\n");
23 const screens = new Set(files(root, "src/tui/screens/*.ts").map((f) => basename(f, ".ts")));
24 const tuiPath = /src\/tui\/[\w./-]+\.ts/g;
outdated

Too loose: any docs/features/*.md that mentions src/tui/ anywhere and names pages/<name>.ts clears the page, even if the doc says nothing about a screen for that page. A doc listing several pages plus one unrelated tui path clears all of them. Require the screen path to be one that exists under src/tui/screens/ (or that the screen imports the page), and escape name in the RegExp built on the next lines (names contain ./_/-; escape them). Also replace the hard-coded slice(16,-3) and slice(14,-3) offsets with path.basename.

25 const docs = files(root, "docs/features/*.md")
26 .map(read)
27 .filter((t) => (t.match(tuiPath) ?? []).some((f) => existsSync(join(root, f))));
28 return pages.filter((p) => {
29 const name = basename(p, ".ts");
30 const esc = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
31 const flat = name.replace(/[-_]/g, "");
32 if ([name, name.replace(/-/g, "_"), flat].some((n) => screens.has(n))) return false;
33 if (new RegExp(`pages/${esc}(\\.ts)?["']`).test(doors)) return false;
34 return !docs.some((t) => t.includes(`pages/${name}.ts`));
35 });
36 }
37
38 if (import.meta.main) {
39 const root = join(import.meta.dir, "..");
40 const path = join(root, "scripts/doorless-allow.json");
41 const found = doorlessPages(root);
42 if (process.argv.includes("--write")) {
43 const kept = (JSON.parse(readFileSync(path, "utf8")) as string[]).filter((p) => found.includes(p));
44 writeFileSync(path, JSON.stringify(kept, null, 2) + "\n");
45 console.log(`kept ${kept.length}`);
46 } else if (process.argv.includes("--init")) {
47 writeFileSync(path, JSON.stringify(found, null, 2) + "\n");
48 console.log(`wrote ${found.length}`);
49 } else console.log(found.join("\n"));
50 }
test/doorless.test.ts added +58
@@ -0,0 +1,58 @@
1 /**
2 * Both doors, read from the tree (#14289): every page under src/web/pages/ has a terminal door
3 * or is listed in `scripts/doorless-allow.json`, and the list only shrinks.
4 */
5
6 import { expect, test } from "bun:test";
7 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
8 import { tmpdir } from "node:os";
9 import { dirname, join } from "node:path";
10 import { doorlessPages } from "../scripts/doorless.ts";
11 import allowed from "../scripts/doorless-allow.json";
12
13 const found = doorlessPages(new URL("..", import.meta.url).pathname);
14
15 test('rule "both doors": every page has a terminal screen, or is allowed', () => {
16 const fresh = found.filter((f) => !allowed.includes(f));
17 expect(
18 fresh,
19 `rule "both doors": these pages have no terminal door; add the screen in src/tui/screens/ with its entry where AGENTS.md says and a docs/features/<name>.md naming both (or, only if truly intended, list the page in scripts/doorless-allow.json): ${fresh.join(", ")}`,
20 ).toEqual([]);
21 });
22
23 test("a listed page that gained a door fails: prune the list", () => {
24 const stale = allowed.filter((f) => !found.includes(f));
25 expect(stale, `these pages now have a door; run \`bun scripts/doorless.ts --write\`: ${stale.join(", ")}`).toEqual([]);
26 });
outdated

Vacuous: Array.isArray(stale) is always true, so this test cannot fail. AGENTS.md says "the list only shrinks" but nothing enforces it: a builder can append any new page to scripts/doorless-allow.json and the main test passes. Fix: fail on stale entries (message: run bun scripts/doorless.ts --write), and fail when the allow list has an entry that is not in a pinned count or baseline (e.g. the list length must be <= the committed number, or entries must already exist on the base). The reasoning that a warning avoids list conflicts is weaker than a check that actually holds the rule.

27
28 /**
29 * Lower this when the list shrinks; raising it is adding a page without a door, which review
30 * refuses.
31 */
32 const CEILING = 99;
33
34 test("the allow list cannot gain a page", () => {
35 expect(allowed.length, "the list only shrinks: give the page a terminal door instead of listing it").toBeLessThanOrEqual(CEILING);
36 });
37
38 test("doorlessPages() flags a page nothing in the terminal reaches; each kind of door clears it", () => {
39 const dir = mkdtempSync(join(process.env.TMPDIR ?? tmpdir(), "doorless-"));
40 const put = (path: string, text: string) => {
41 mkdirSync(dirname(join(dir, path)), { recursive: true });
42 writeFileSync(join(dir, path), text);
43 };
44 try {
45 for (const p of ["alone", "named", "imported", "documented"]) put(`src/web/pages/${p}.ts`, "export {};\n");
46 put("src/tui/screens/named.ts", "export {};\n");
47 put("src/tui/screens/other.ts", 'import "../../web/pages/imported.ts";\n');
48 put("src/tui/screens/x.ts", "export {};\n");
49 put("docs/features/documented.md", "Page `src/web/pages/documented.ts`; terminal `src/tui/screens/x.ts`.\n");
50 put("src/web/pages/vague.ts", "export {};\n");
51 put("docs/features/vague.md", "Page `src/web/pages/vague.ts`; terminal `src/tui/screens/missing.ts`.\n");
52 put("src/web/pages/a.b.ts", "export {};\n");
53 put("src/tui/screens/axb.ts", "export {};\n");
54 expect(doorlessPages(dir)).toEqual(["src/web/pages/a.b.ts", "src/web/pages/alone.ts", "src/web/pages/vague.ts"]);
55 } finally {
56 rmSync(dir, { recursive: true, force: true });
57 }
58 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs