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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14289-automate-a-review-finding-as-a-lint-or-t → main 4 commits fork 2 threads · 2 unresolved
AGENTS.md +2
| @@ -5,6 +5,8 @@ Read `CLAUDE.md` first: it is the rulebook for agents editing this repo. | ||
| 5 | 5 | 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`). |
| 6 | 6 | |
| 7 | 7 | 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 | ||
| 8 | 10 | 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). |
| 9 | 11 | 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 | 12 | 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; | |
| 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 |
||
| 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 | }); |
Too loose: any docs/features/*.md that mentions
src/tui/anywhere and namespages/<name>.tsclears 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 escapenamein 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.