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

Automate a review finding as a lint or test: Both doors: the fold is on the page only. Nothing in src/tui/ shows a folded bur #14843

Merged opened this

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

Merged

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

  • Merged. mason/14842-automate-a-review-finding-as-a-lint-or-t was merged into main as 3ab1eae.

Review

Sign in to review this change.
4 files changed +110 −0
AGENTS.md +1
@@ -9,6 +9,7 @@ A maintenance duty is a file in `src/maintain/duties/` that exports `duty`; `src
99 README.md is capped: a new feature's how-to goes in `docs/features/<name>.md`, not a new README section.
1010 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); a new `src/http/api/*.ts` or `src/http/mcp/tools/*.ts` is asked for the screen, and a new module wired into `src/http/server.ts` for both (#14320); `bun scripts/gate.ts` refuses it otherwise ("both doors", #10628).
1111 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.
12 A how-to is read the same way (#14842): `test/feature-doors.test.ts` fails on a `docs/features/*.md` that names a `src/web/pages/` file but no existing `src/tui/` file, unless `scripts/feature-doors-allow.json` lists it (the list only shrinks; `bun scripts/feature-doors.ts --write` prunes).
1213
1314 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).
1415 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/feature-doors-allow.json added +21
@@ -0,0 +1,21 @@
1 [
2 "docs/features/absorb.md",
3 "docs/features/bring.md",
4 "docs/features/claim-own-name.md",
5 "docs/features/crawl-budget.md",
6 "docs/features/dependency-standing.md",
7 "docs/features/html-preview.md",
8 "docs/features/markdown-relative.md",
9 "docs/features/measure-page.md",
10 "docs/features/signin-asking.md",
11 "docs/features/speak.md",
12 "docs/features/stranger-pulls.md",
13 "docs/features/talk-resume-writes.md",
14 "docs/features/template-page.md",
15 "docs/features/template-timing.md",
16 "docs/features/thread-fold.md",
17 "docs/features/wave-standing.md",
18 "docs/features/webhook-pause.md",
19 "docs/features/webhook-redeliver.md",
20 "docs/features/welcome.md"
21 ]
scripts/feature-doors.ts added +34
@@ -0,0 +1,34 @@
1 /**
2 * How-tos that name one door only (#14842). Reviewers wrote "both doors: nothing in src/tui/
3 * shows it, and there is no docs/features/ how-to" of the fold (#12335), the stale list (#12444),
4 * the price line (#13084) and the client week line (#14732). `scripts/doorless.ts` reads pages;
5 * this reads the how-tos: a `docs/features/*.md` that names a `src/web/pages/` file also names a
6 * `src/tui/` file that exists, so the page's how-to says where the terminal shows the same thing.
7 * The list in `scripts/feature-doors-allow.json` only shrinks: `--write` prunes it.
8 */
9
10 import { existsSync, readFileSync, writeFileSync } from "node:fs";
11 import { join } from "node:path";
12
13 const TUI = /src\/tui\/[\w./-]+\.ts/g;
14
15 /** `docs/features/<name>.md` for each how-to naming a page but no terminal file, sorted. */
16 export function pageOnlyHowtos(root: string): string[] {
17 const docs = [...new Bun.Glob("docs/features/*.md").scanSync({ cwd: root })].sort();
18 return docs.filter((d) => {
19 const text = readFileSync(join(root, d), "utf8");
20 if (!/src\/web\/pages\/[\w.-]+\.ts/.test(text)) return false;
21 return !(text.match(TUI) ?? []).some((f) => existsSync(join(root, f)));
22 });
23 }
24
25 if (import.meta.main) {
26 const root = join(import.meta.dir, "..");
27 const path = join(root, "scripts/feature-doors-allow.json");
28 const found = pageOnlyHowtos(root);
29 if (process.argv.includes("--write")) {
30 const kept = existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as string[]).filter((p) => found.includes(p)) : found;
31 writeFileSync(path, JSON.stringify(kept, null, 2) + "\n");
32 console.log(`kept ${kept.length}`);
33 } else console.log(found.join("\n"));
34 }
test/feature-doors.test.ts added +54
@@ -0,0 +1,54 @@
1 /**
2 * Both doors, read from the how-tos (#14842): a docs/features how-to that names a page also names
3 * the src/tui/ file that shows the same thing, or is listed in `scripts/feature-doors-allow.json`,
4 * and the list only shrinks.
5 */
6
7 import { expect, test } from "bun:test";
8 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
9 import { tmpdir } from "node:os";
10 import { dirname, join } from "node:path";
11 import { pageOnlyHowtos } from "../scripts/feature-doors.ts";
12 import allowed from "../scripts/feature-doors-allow.json";
13
14 const found = pageOnlyHowtos(new URL("..", import.meta.url).pathname);
15
16 test('rule "both doors": a how-to that names a page names the terminal file too, or is allowed', () => {
17 const fresh = found.filter((f) => !allowed.includes(f));
18 expect(
19 fresh,
20 `rule "both doors": these how-tos name a src/web/pages/ file but no existing src/tui/ file; say where the terminal shows the same line (add the screen if there is none), or list the how-to in scripts/feature-doors-allow.json: ${fresh.join(", ")}`,
21 ).toEqual([]);
22 });
23
24 test("a listed how-to that gained its terminal file fails: prune the list", () => {
25 const stale = allowed.filter((f) => !found.includes(f));
26 expect(stale, `these how-tos now name a terminal file; run \`bun scripts/feature-doors.ts --write\`: ${stale.join(", ")}`).toEqual([]);
27 });
28
29 /**
30 * Lower this when the list shrinks; raising it is adding a page-only how-to, which review refuses.
31 */
32 const CEILING = 19;
33
34 test("the allow list cannot gain a how-to", () => {
35 expect(allowed.length, "the list only shrinks: name the terminal door in the how-to instead of listing it").toBeLessThanOrEqual(CEILING);
36 });
37
38 test("pageOnlyHowtos() flags a how-to with a page and no existing terminal file", () => {
39 const dir = mkdtempSync(join(process.env.TMPDIR ?? tmpdir(), "feature-doors-"));
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 put("src/tui/screens/real.ts", "export {};\n");
46 put("docs/features/both.md", "`src/web/pages/a.ts` and `src/tui/screens/real.ts`\n");
47 put("docs/features/page-only.md", "`src/web/pages/a.ts`\n");
48 put("docs/features/ghost.md", "`src/web/pages/a.ts` and `src/tui/screens/gone.ts`\n");
49 put("docs/features/no-page.md", "just prose\n");
50 expect(pageOnlyHowtos(dir)).toEqual(["docs/features/ghost.md", "docs/features/page-only.md"]);
51 } finally {
52 rmSync(dir, { recursive: true, force: true });
53 }
54 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs