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

Automate a review finding as a lint or test: Both doors: no src/tui/ screen or entry shows the Done line / Undo, and there is #13204

Merged opened this

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

Merged

scout/forge:scout/13196-automate-a-review-finding-as-a-lint-or-t → main 2 commits fork

  • Merged. scout/13196-automate-a-review-finding-as-a-lint-or-t was merged into main as 5b81678.

Review

Sign in to review this change.
3 files changed +52 −5
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; `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 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).
1010
1111 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.
src/kernel/both_doors.ts +31 −2
@@ -18,6 +18,13 @@
1818 * `src/` outside tests, the kernel and the terminal's own folders) in a pull
1919 * that edits an existing page is a feature, and is asked for the screen and
2020 * the how-to like a new page.
21 *
22 * Five reviews more (#13196: #11827, #13064, #13084, #10171, #10311) asked it of a
23 * line added to a page that already existed, which no new file marks. A pull that
24 * edits an existing `src/web/pages/*.ts` therefore changes (adds or edits) a file
25 * under `src/tui/` and a `docs/features/*.md` too, or says `No door:` in a commit
26 * message. The waiver is for a fix or a refactor that shows nothing new; a line a
27 * person can read on the page is not one, and the terminal must match it.
2128 */
2229
2330 import type { Change } from "./pin_edits.ts";
@@ -49,8 +56,9 @@ export function bothDoorsProblems(
4956 const wired = changes.some((c) => c.status.startsWith("M") && EDITED_PAGE.test(c.path));
5057 const modules = wired && pages.length === 0 ? added(changes, FEATURE_MODULE) : [];
5158 const featured = modules.length > 0;
52 if (pages.length === 0 && surfaces.length === 0 && !featured) return [];
53 if (messages.some((m) => WAIVER.test(m))) return [];
59 const waived = messages.some((m) => WAIVER.test(m));
60 if (pages.length === 0 && surfaces.length === 0 && !featured) return waived ? [] : editedPageProblems(changes);
61 if (waived) return [];
5462 const missing: string[] = [];
5563 const screens = added(changes, SCREEN);
5664 if (screens.length === 0) missing.push("terminal screen in src/tui/screens/ (entry where AGENTS.md says)");
@@ -63,3 +71,24 @@ export function bothDoorsProblems(
6371 `rule "both doors": this pull adds ${shown} but no ${missing.join(" and no ")}; add them, or put a "No door: <why>" line (10+ characters) in a commit message`,
6472 ];
6573 }
74
75 const TUI_FILE = /^src\/tui\/.+\.ts$/;
76 const touched = (changes: readonly Change[], re: RegExp) =>
77 changes.some((c) => !c.status.startsWith("D") && re.test(c.path));
78
79 /**
80 * The edited-page half of the rule (#13196): an existing page changed, no terminal change or how-to
81 * with it.
82 */
83 function editedPageProblems(changes: readonly Change[]): string[] {
84 const edited = changes.filter((c) => c.status.startsWith("M") && EDITED_PAGE.test(c.path)).map((c) => c.path);
85 if (edited.length === 0) return [];
86 const missing: string[] = [];
87 if (!touched(changes, TUI_FILE)) missing.push("change under src/tui/ showing the same line");
88 if (!touched(changes, DOC)) missing.push("docs/features/<name>.md how-to");
89 if (missing.length === 0) return [];
90 const shown = edited.slice(0, 3).join(", ") + (edited.length > 3 ? ` and ${edited.length - 3} more` : "");
91 return [
92 `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`,
93 ];
94 }
test/both-doors.test.ts +20 −2
@@ -27,7 +27,6 @@ test("both doors pass; so does a No door line; edits and other files are never a
2727 expect(bothDoorsProblems([page, ch("A", "src/tui/screens/t.ts"), ch("A", "docs/features/t.md")], [], () => true)).toEqual([]);
2828 expect(bothDoorsProblems([page], ["x\n\nNo door: a public landing page, nothing to administer"], () => true)).toEqual([]);
2929 expect(bothDoorsProblems([page], ["No door: no"], () => true)).toHaveLength(1);
30 expect(bothDoorsProblems([ch("M", "src/web/pages/traffic.ts")], [], () => true)).toEqual([]);
3130 expect(bothDoorsProblems([ch("A", "src/core/x.ts")], [], () => true)).toEqual([]);
3231 });
3332
@@ -72,5 +71,24 @@ test("a new feature module wired into an existing page needs both doors (#12444,
7271 expect(bothDoorsProblems([edit, mod], ["No door: a refactor that only moves a helper"], () => true)).toEqual([]);
7372 // a module with no page edit beside it, or a kernel or test file, is not a feature
7473 expect(bothDoorsProblems([mod], [], () => true)).toEqual([]);
75 expect(bothDoorsProblems([edit, ch("A", "src/kernel/x.ts"), ch("A", "src/tui/ui/x.ts")], [], () => true)).toEqual([]);
74 expect(bothDoorsProblems([edit, ch("A", "src/kernel/x.ts"), ch("A", "src/tui/ui/x.ts"), ch("A", "docs/features/x.md")], [], () => true)).toEqual([]);
75 });
76
77 const edit = ch("M", "src/web/pages/settings.ts");
78
79 test("an edit to an existing page needs a terminal change and a how-to, or a No door line (#13196)", () => {
80 const msg = (what: string) =>
81 `rule "both doors": this pull edits src/web/pages/settings.ts but has no ${what}; 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`;
82 expect(bothDoorsProblems([edit], ["x"], () => true)).toEqual([
83 msg("change under src/tui/ showing the same line and no docs/features/<name>.md how-to"),
84 ]);
85 expect(bothDoorsProblems([edit, ch("M", "src/tui/screens/settings.ts")], [], () => true)).toEqual([
86 msg("docs/features/<name>.md how-to"),
87 ]);
88 expect(bothDoorsProblems([edit, ch("M", "docs/features/a.md")], [], () => true)).toEqual([
89 msg("change under src/tui/ showing the same line"),
90 ]);
91 expect(bothDoorsProblems([edit, ch("M", "src/tui/screens/settings.ts"), ch("M", "docs/features/a.md")], [], () => true)).toEqual([]);
92 expect(bothDoorsProblems([edit], ["No door: a typo fix, nothing new shown"], () => true)).toEqual([]);
93 expect(bothDoorsProblems([ch("M", "src/web/render/x.ts"), ch("M", "src/core/x.ts")], [], () => true)).toEqual([]);
7694 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs