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

Automate a review finding as a lint or test: Both doors: no docs/features/<name>.md is added for this behaviour. Add the how- #12973

Merged opened this

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

Merged

mason/forge:mason/12972-automate-a-review-finding-as-a-lint-or-t → main 1 commit fork 1 thread · 1 unresolved

  • Merged. mason/12972-automate-a-review-finding-as-a-lint-or-t was merged into main as 12274f2.

Review

Sign in to review this change.
3 files changed +42 −6
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` or `src/actions/*.ts` is asked for the screen alone; `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; `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 +17 −4
@@ -10,12 +10,22 @@
1010 * (#11626): a new `src/web/render/*.ts` or `src/actions/*.ts` is a feature
1111 * the web door shows, so it needs its terminal screen too (the how-to is
1212 * asked of pages only), or the same `No door:` line.
13 *
14 * Four more reviews (#12972) found the rule walked around: a feature built as
15 * a new module in `src/web/studio/` (#12342), or as a new module elsewhere
16 * under `src/` wired into a page that already exists (#12444, #12927). A new
17 * `src/web/studio/*.ts` is a surface; a new feature module (any new file under
18 * `src/` outside tests, the kernel and the terminal's own folders) in a pull
19 * that edits an existing page is a feature, and is asked for the screen and
20 * the how-to like a new page.
1321 */
1422
1523 import type { Change } from "./pin_edits.ts";
1624
1725 const PAGE = /^src\/web\/pages\/[^/]+\.ts$/;
18 const SURFACE = /^src\/(web\/render|actions)\/[^/]+\.ts$/;
26 const SURFACE = /^src\/(web\/(render|studio)|actions)\/[^/]+\.ts$/;
27 const EDITED_PAGE = PAGE;

EDITED_PAGE is a bare alias of PAGE; use PAGE at the call site and delete this line.

28 const FEATURE_MODULE = /^src\/(?!tui\/|kernel\/|web\/(pages|render|studio)\/|actions\/)(?:[^/]+\/)+[^/]+\.ts$/;
1929 const SCREEN = /^src\/tui\/screens\/[^/]+\.ts$/;
2030 const DOC = /^docs\/features\/[^/]+\.md$/;
2131 const WAIVER = /^No door:\s*\S[^\n]{9,}/im;
@@ -36,15 +46,18 @@ export function bothDoorsProblems(
3646 ): string[] {
3747 const pages = added(changes, PAGE);
3848 const surfaces = added(changes, SURFACE);
39 if (pages.length === 0 && surfaces.length === 0) return [];
49 const wired = changes.some((c) => c.status.startsWith("M") && EDITED_PAGE.test(c.path));
50 const modules = wired && pages.length === 0 ? added(changes, FEATURE_MODULE) : [];
51 const featured = modules.length > 0;
52 if (pages.length === 0 && surfaces.length === 0 && !featured) return [];
4053 if (messages.some((m) => WAIVER.test(m))) return [];
4154 const missing: string[] = [];
4255 const screens = added(changes, SCREEN);
4356 if (screens.length === 0) missing.push("terminal screen in src/tui/screens/ (entry where AGENTS.md says)");
4457 else if (!screens.some(imported)) missing.push(`entry that opens ${screens[0]} (add its palette entry per AGENTS.md)`);
45 if (pages.length > 0 && added(changes, DOC).length === 0) missing.push("docs/features/<name>.md how-to");
58 if ((pages.length > 0 || featured) && added(changes, DOC).length === 0) missing.push("docs/features/<name>.md how-to");
4659 if (missing.length === 0) return [];
47 const all = [...pages, ...surfaces];
60 const all = [...pages, ...surfaces, ...modules];
4861 const shown = all.slice(0, 3).join(", ") + (all.length > 3 ? ` and ${all.length - 3} more` : "");
4962 return [
5063 `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`,
test/both-doors.test.ts +24 −1
@@ -27,7 +27,8 @@ 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"), ch("A", "src/core/x.ts")], [], () => true)).toEqual([]);
30 expect(bothDoorsProblems([ch("M", "src/web/pages/traffic.ts")], [], () => true)).toEqual([]);
31 expect(bothDoorsProblems([ch("A", "src/core/x.ts")], [], () => true)).toEqual([]);
3132 });
3233
3334 test("a helper under src/tui/ is not a screen, and a screen nothing imports is not a door", () => {
@@ -51,3 +52,25 @@ test("a new file renderer or action needs a terminal screen, and is not asked fo
5152 expect(bothDoorsProblems([ch("M", f)], [], () => true)).toEqual([]);
5253 }
5354 });
55
56 test("a new studio module is a surface and needs a terminal screen (#12342)", () => {
57 const f = "src/web/studio/share_tell.ts";
58 expect(bothDoorsProblems([ch("A", f)], [], () => true)).toEqual([`rule "both doors": this pull adds ${f} but no ${TUI}${tail}`]);
59 expect(bothDoorsProblems([ch("A", f), ch("A", "src/tui/screens/s.ts")], [], () => true)).toEqual([]);
60 });
61
62 test("a new feature module wired into an existing page needs both doors (#12444, #12927)", () => {
63 const edit = ch("M", "src/web/pages/maintenance.ts");
64 const mod = ch("A", "src/maintain/stale_pulls.ts");
65 expect(bothDoorsProblems([edit, mod], [], () => true)).toEqual([
66 `rule "both doors": this pull adds src/maintain/stale_pulls.ts but no ${TUI} and no ${DOCS}${tail}`,
67 ]);
68 expect(bothDoorsProblems([edit, mod, ch("A", "src/tui/screens/s.ts")], [], () => true)).toEqual([
69 `rule "both doors": this pull adds src/maintain/stale_pulls.ts but no ${DOCS}${tail}`,
70 ]);
71 expect(bothDoorsProblems([edit, mod, ch("A", "src/tui/screens/s.ts"), ch("A", "docs/features/s.md")], [], () => true)).toEqual([]);
72 expect(bothDoorsProblems([edit, mod], ["No door: a refactor that only moves a helper"], () => true)).toEqual([]);
73 // a module with no page edit beside it, or a kernel or test file, is not a feature
74 expect(bothDoorsProblems([mod], [], () => true)).toEqual([]);
75 expect(bothDoorsProblems([edit, ch("A", "src/kernel/x.ts"), ch("A", "src/tui/ui/x.ts")], [], () => true)).toEqual([]);
76 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs