Public: anyone can read this; the crew can change it.
Automate a review finding as a lint or test: Fix first: item 1, the terminal door, then the tests in item 2. #14041
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14040-automate-a-review-finding-as-a-lint-or-t → main 1 commit fork
3 files
changed +45
−4
AGENTS.md +1 −1
| @@ -5,7 +5,7 @@ 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 | 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). | |
| 8 | 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 | 9 | 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 | 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. |
| 11 | 11 |
src/kernel/both_doors.ts +23 −2
| @@ -29,6 +29,13 @@ | ||
| 29 | 29 | * under `src/tui/` and a `docs/features/*.md` too, or says `No door:` in a commit |
| 30 | 30 | * message. The waiver is for a fix or a refactor that shows nothing new; a line a |
| 31 | 31 | * person can read on the page is not one, and the terminal must match it. |
| 32 | * | |
| 33 | * Four reviews more (#14040: #10072, #10663, #10703, #11735) said "fix first: the terminal | |
| 34 | * door" of a change that reached people only through the API or an MCP tool: a new route in | |
| 35 | * `src/http/api.ts`, a new action on an existing tool in `src/http/mcp/`, an edited | |
| 36 | * `src/actions/*.ts`. Such an edit is a door too: it changes something under `src/tui/` (the | |
| 37 | * how-to is not asked), and a new feature module wired into it is asked for the screen and the | |
| 38 | * how-to, or `No door:` says why. | |
| 32 | 39 | */ |
| 33 | 40 | |
| 34 | 41 | import type { Change } from "./pin_edits.ts"; |
| @@ -36,6 +43,7 @@ import type { Change } from "./pin_edits.ts"; | ||
| 36 | 43 | const PAGE = /^src\/web\/pages\/[^/]+\.ts$/; |
| 37 | 44 | const SURFACE = /^src\/(web\/(render|studio)|actions)\/[^/]+\.ts$/; |
| 38 | 45 | const EDITED_PAGE = PAGE; |
| 46 | const EDITED_API = /^src\/(http\/api\.ts|http\/api\/[^/]+\.ts|http\/mcp\/.+\.ts|actions\/[^/]+\.ts)$/; | |
| 39 | 47 | const EDITED_WEB = /^src\/web\/(?!pages\/)(?:[^/]+\/)*[^/]+\.ts$/; |
| 40 | 48 | const FEATURE_MODULE = /^src\/(?!tui\/|kernel\/|web\/(pages|render|studio)\/|actions\/)(?:[^/]+\/)+[^/]+\.ts$/; |
| 41 | 49 | const SCREEN = /^src\/tui\/screens\/[^/]+\.ts$/; |
| @@ -58,7 +66,7 @@ export function bothDoorsProblems( | ||
| 58 | 66 | ): string[] { |
| 59 | 67 | const pages = added(changes, PAGE); |
| 60 | 68 | const surfaces = added(changes, SURFACE); |
| 61 | const wired = changes.some((c) => c.status.startsWith("M") && (EDITED_PAGE.test(c.path) || EDITED_WEB.test(c.path))); | |
| 69 | const wired = changes.some((c) => c.status.startsWith("M") && (EDITED_PAGE.test(c.path) || EDITED_WEB.test(c.path) || EDITED_API.test(c.path))); | |
| 62 | 70 | const modules = wired && pages.length === 0 ? added(changes, FEATURE_MODULE) : []; |
| 63 | 71 | const featured = modules.length > 0; |
| 64 | 72 | const waived = messages.some((m) => WAIVER.test(m)); |
| @@ -87,7 +95,7 @@ const touched = (changes: readonly Change[], re: RegExp) => | ||
| 87 | 95 | */ |
| 88 | 96 | function editedPageProblems(changes: readonly Change[]): string[] { |
| 89 | 97 | const edited = changes.filter((c) => c.status.startsWith("M") && EDITED_PAGE.test(c.path)).map((c) => c.path); |
| 90 | if (edited.length === 0) return []; | |
| 98 | if (edited.length === 0) return editedApiProblems(changes); | |
| 91 | 99 | const missing: string[] = []; |
| 92 | 100 | if (!touched(changes, TUI_FILE)) missing.push("change under src/tui/ showing the same line"); |
| 93 | 101 | if (!touched(changes, DOC)) missing.push("docs/features/<name>.md how-to"); |
| @@ -97,3 +105,16 @@ function editedPageProblems(changes: readonly Change[]): string[] { | ||
| 97 | 105 | `rule "both doors": this pull edits ${shown} but has no ${missing.join(" and no ")}; the terminal must show what the page shows. Add them, or put a "No door: <why>" line (10+ characters) in a commit message when the edit shows nothing new`, |
| 98 | 106 | ]; |
| 99 | 107 | } |
| 108 | ||
| 109 | /** | |
| 110 | * The API half (#14040): an existing route, MCP tool or action changed and nothing under | |
| 111 | * `src/tui/` changed with it. Named once, with the files, so the reviewer need not say it. | |
| 112 | */ | |
| 113 | function editedApiProblems(changes: readonly Change[]): string[] { | |
| 114 | const edited = changes.filter((c) => c.status.startsWith("M") && EDITED_API.test(c.path)).map((c) => c.path); | |
| 115 | if (edited.length === 0 || touched(changes, TUI_FILE)) return []; | |
| 116 | const shown = edited.slice(0, 3).join(", ") + (edited.length > 3 ? ` and ${edited.length - 3} more` : ""); | |
| 117 | return [ | |
| 118 | `rule "both doors": this pull edits ${shown} but has no change under src/tui/; the terminal must reach what the API and the MCP reach. Add it, or put a "No door: <why>" line (10+ characters) in a commit message when the edit shows nothing new`, | |
| 119 | ]; | |
| 120 | } |
test/both-doors.test.ts +21 −1
| @@ -48,7 +48,7 @@ test("a new file renderer or action needs a terminal screen, and is not asked fo | ||
| 48 | 48 | ]); |
| 49 | 49 | expect(bothDoorsProblems([ch("A", f), ch("A", "src/tui/screens/s.ts")], [], () => true)).toEqual([]); |
| 50 | 50 | expect(bothDoorsProblems([ch("A", f)], ["No door: a helper with no screen of its own"], () => true)).toEqual([]); |
| 51 | expect(bothDoorsProblems([ch("M", f)], [], () => true)).toEqual([]); | |
| 51 | expect(bothDoorsProblems([ch("M", f), ch("M", "src/tui/screens/s.ts")], [], () => true)).toEqual([]); | |
| 52 | 52 | } |
| 53 | 53 | }); |
| 54 | 54 | |
| @@ -92,3 +92,23 @@ test("an edit to an existing page needs a terminal change and a how-to, or a No | ||
| 92 | 92 | expect(bothDoorsProblems([edit], ["No door: a typo fix, nothing new shown"], () => true)).toEqual([]); |
| 93 | 93 | expect(bothDoorsProblems([ch("M", "src/web/render/x.ts"), ch("M", "src/core/x.ts")], [], () => true)).toEqual([]); |
| 94 | 94 | }); |
| 95 | ||
| 96 | test("an edited route, MCP tool or action needs a terminal change, or a No door line (#14040)", () => { | |
| 97 | const msg = (f: string) => | |
| 98 | `rule "both doors": this pull edits ${f} but has no change under src/tui/; the terminal must reach what the API and the MCP reach. Add it, or put a "No door: <why>" line (10+ characters) in a commit message when the edit shows nothing new`; | |
| 99 | for (const f of ["src/http/api.ts", "src/http/api/repos.ts", "src/http/mcp/tools/app_domains.ts", "src/actions/apps.ts"]) { | |
| 100 | expect(bothDoorsProblems([ch("M", f)], [], () => true)).toEqual([msg(f)]); | |
| 101 | expect(bothDoorsProblems([ch("M", f), ch("M", "src/tui/screens/deploys.ts")], [], () => true)).toEqual([]); | |
| 102 | expect(bothDoorsProblems([ch("M", f)], ["No door: a fix, nothing new reached"], () => true)).toEqual([]); | |
| 103 | } | |
| 104 | expect(bothDoorsProblems([ch("M", "src/http/respond.ts")], [], () => true)).toEqual([]); | |
| 105 | }); | |
| 106 | ||
| 107 | test("a new module wired into an API route or MCP tool needs both doors (#14040)", () => { | |
| 108 | const mod = ch("A", "src/core/transfer.ts"); | |
| 109 | const route = ch("M", "src/http/api.ts"); | |
| 110 | expect(bothDoorsProblems([route, mod], [], () => true)).toEqual([ | |
| 111 | `rule "both doors": this pull adds src/core/transfer.ts but no ${TUI} and no ${DOCS}${tail}`, | |
| 112 | ]); | |
| 113 | expect(bothDoorsProblems([route, mod, ch("A", "src/tui/screens/t.ts"), ch("A", "docs/features/t.md")], [], () => true)).toEqual([]); | |
| 114 | }); |
new above
offline