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

Merged opened this

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

Merged

scout/forge:scout/14040-automate-a-review-finding-as-a-lint-or-t → main 1 commit fork

  • Merged. scout/14040-automate-a-review-finding-as-a-lint-or-t was merged into main as e13f72d.

Review

Sign in to review this change.
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.
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 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).
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).
1010 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.
1111
src/kernel/both_doors.ts +23 −2
@@ -29,6 +29,13 @@
2929 * under `src/tui/` and a `docs/features/*.md` too, or says `No door:` in a commit
3030 * message. The waiver is for a fix or a refactor that shows nothing new; a line a
3131 * 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.
3239 */
3340
3441 import type { Change } from "./pin_edits.ts";
@@ -36,6 +43,7 @@ import type { Change } from "./pin_edits.ts";
3643 const PAGE = /^src\/web\/pages\/[^/]+\.ts$/;
3744 const SURFACE = /^src\/(web\/(render|studio)|actions)\/[^/]+\.ts$/;
3845 const EDITED_PAGE = PAGE;
46 const EDITED_API = /^src\/(http\/api\.ts|http\/api\/[^/]+\.ts|http\/mcp\/.+\.ts|actions\/[^/]+\.ts)$/;
3947 const EDITED_WEB = /^src\/web\/(?!pages\/)(?:[^/]+\/)*[^/]+\.ts$/;
4048 const FEATURE_MODULE = /^src\/(?!tui\/|kernel\/|web\/(pages|render|studio)\/|actions\/)(?:[^/]+\/)+[^/]+\.ts$/;
4149 const SCREEN = /^src\/tui\/screens\/[^/]+\.ts$/;
@@ -58,7 +66,7 @@ export function bothDoorsProblems(
5866 ): string[] {
5967 const pages = added(changes, PAGE);
6068 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)));
6270 const modules = wired && pages.length === 0 ? added(changes, FEATURE_MODULE) : [];
6371 const featured = modules.length > 0;
6472 const waived = messages.some((m) => WAIVER.test(m));
@@ -87,7 +95,7 @@ const touched = (changes: readonly Change[], re: RegExp) =>
8795 */
8896 function editedPageProblems(changes: readonly Change[]): string[] {
8997 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);
9199 const missing: string[] = [];
92100 if (!touched(changes, TUI_FILE)) missing.push("change under src/tui/ showing the same line");
93101 if (!touched(changes, DOC)) missing.push("docs/features/<name>.md how-to");
@@ -97,3 +105,16 @@ function editedPageProblems(changes: readonly Change[]): string[] {
97105 `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`,
98106 ];
99107 }
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
4848 ]);
4949 expect(bothDoorsProblems([ch("A", f), ch("A", "src/tui/screens/s.ts")], [], () => true)).toEqual([]);
5050 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([]);
5252 }
5353 });
5454
@@ -92,3 +92,23 @@ test("an edit to an existing page needs a terminal change and a how-to, or a No
9292 expect(bothDoorsProblems([edit], ["No door: a typo fix, nothing new shown"], () => true)).toEqual([]);
9393 expect(bothDoorsProblems([ch("M", "src/web/render/x.ts"), ch("M", "src/core/x.ts")], [], () => true)).toEqual([]);
9494 });
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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs