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

"before/after looks" is now the gate rule that fails most checks: a missing commit-message line should not cost a check and a builder run #13364

Merged opened this in answer to

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

Merged

mason/forge:mason/13362-before-after-looks-is-now-the-gate-rule → main 3 commits fork 3 threads · 3 unresolved

  • Merged. mason/13362-before-after-looks-is-now-the-gate-rule was merged into main as 25eb4dc.

Review

Sign in to review this change.
6 files changed +313 −33
scripts/gate.ts +40 −7
@@ -606,10 +606,15 @@ export async function bothDoorsRefusal(cwd: string = process.cwd()): Promise<str
606606 return bothDoorsProblems(changes, log.out.split("\0").map((m) => m.trim()).filter(Boolean), imported);
607607 }
608608
609 /** A pull that changes a screen says which pictured page shows it (#12362). */
610 export async function lookRefusal(cwd: string = process.cwd()): Promise<string[]> {
609 /**
610 * A pull that changes a screen: the pages the forge pictures for it, never a refusal (#12362,
611 * #13362).
612 */
613 export async function lookNote(cwd: string = process.cwd()): Promise<string[]> {
611614 const { parseNameStatus } = await import("../src/kernel/pin_edits.ts");
612 const { lookProblems } = await import("../src/kernel/look_rule.ts");
615 const { lookNotes } = await import("../src/kernel/look_rule.ts");
616 const { pagesShowing } = await import("../src/kernel/look_pages.ts");
617 const { readTui } = await import("../src/kernel/tui_entry.ts");
613618 const base =
614619 process.env.FORGE_CHECK_BASE ||
615620 git(["merge-base", "origin/main", "HEAD"], cwd).out ||
@@ -622,7 +627,11 @@ export async function lookRefusal(cwd: string = process.cwd()): Promise<string[]
622627 try {
623628 looks = JSON.parse(readFileSync(join(cwd, "forge.json"), "utf8"))?.app?.looks ?? [];
624629 } catch {}
625 return lookProblems(parseNameStatus(diff.out), log.out.split("\0").map((m) => m.trim()).filter(Boolean), looks);
630 const infer = (touched: readonly string[]) => {
631 const sources = ["src/http", "src/web", "src/tui"].flatMap((dir) => readTui(cwd, dir));
632 return pagesShowing(touched, looks, sources);
633 };
634 return lookNotes(parseNameStatus(diff.out), log.out.split("\0").map((m) => m.trim()).filter(Boolean), looks, infer);
626635 }
627636
628637 /** A pull that adds a feature without touching the pipeline says why (#11036). */
@@ -672,6 +681,29 @@ export async function readmeCapRefusal(cwd: string = process.cwd()): Promise<str
672681 return readmeCapProblems(before.out, existsSync(path) ? readFileSync(path, "utf8") : undefined);
673682 }
674683
684 /**
685 * What the gate says of the clone at `cwd`: `notes` are only said, `refusal` fails the check
686 * (exit 2). The look rule is a note (#13362).
687 */
688 export async function gateVerdict(cwd: string = process.cwd()): Promise<{ notes: string[]; refusal: string[] }> {
689 const present = presentTests(cwd);
690 const refusal = [
outdated

No test fails if lookNote returns to this refusal list. Add one covering the exit code.

691 ...gateRefusal(present),
692 ...slowRefusal(present),
693 ...(await pinRefusal(cwd)),
694 ...(await tryItRefusal(cwd)),
695 ...(await bothDoorsRefusal(cwd)),
696 ...(await directionRefusal(cwd)),
697 ...strayTestRefusal(cwd),
698 ...reviewRefusal(cwd),
699 ...(await addedRefusal(cwd)),
700 ...(await dependencyRefusal(cwd)),
701 ...(await readmeCapRefusal(cwd)),
702 ...billingDeletesRefusal(cwd),
703 ];
704 return { notes: [...wrapNote(cwd), ...(await lookNote(cwd))], refusal };
705 }
706
675707 // `bun scripts/gate.ts`: the audit alone, first in `forge.json`'s check, so
676708 // a stale exclusion fails in under a second — not after install and tsc.
677709 // `--fix` first rewraps the over-long comment lines of the files this pull changes (`--all`: of
@@ -681,9 +713,10 @@ if (import.meta.main) {
681713 const fixed = wrapFix(".", process.argv.includes("--all"));
682714 if (fixed.length) console.error(`gate: rewrapped comments in ${fixed.length === 1 ? "1 file" : `${fixed.length} files`}; commit them`);
683715 }
684 const refusal = [...gateRefusal(presentTests()), ...slowRefusal(presentTests()), ...(await pinRefusal()), ...(await tryItRefusal()), ...(await bothDoorsRefusal()), ...(await lookRefusal()), ...(await directionRefusal()), ...strayTestRefusal(), ...reviewRefusal(), ...(await addedRefusal()), ...(await dependencyRefusal()), ...(await readmeCapRefusal()), ...billingDeletesRefusal()];
685 // Said, never refused: a comment's width stops no check (#12968).
686 for (const line of wrapNote()) console.error(`gate: ${line}`);
716 const { notes, refusal } = await gateVerdict();
717 // Said, never refused: a comment's width stops no check (#12968), nor does the look rule
718 // (#13362).
719 for (const line of notes) console.error(`gate: ${line}`);
687720 for (const line of refusal) console.error(`gate: ${line}`);
688721 process.exit(refusal.length === 0 ? 0 : 2);
689722 }
src/kernel/look_pages.ts added +115
@@ -0,0 +1,115 @@
1 /**
2 * Which pages of `app.looks` show a changed file (#13362). A route is mounted in
3 * `src/http/server.ts` as `router.add("GET", "/path", handler)`, and the handler is imported from
4 * a module; the pages that show a file are those whose handler module reaches it through static
5 * imports. Plain text in, plain data out: `gate.ts` reads the files.
6 */
7
8 import { resolveSpecifier, specifiers, type Source } from "./tui_entry.ts";
9

IMPORT and ROUTE only match named imports and identifier handlers. Inline or wrapped handlers, default imports and import * as fall through to 'none'. Handle them, or say 'could not infer'.

10 const SERVER = "src/http/server.ts";
11 const NAMED = /import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*["']([^"']+)["']/g;
12 const DEFAULT = /import\s+([A-Za-z_$][\w$]*)\s*(?:,\s*\{[^}]*\}\s*)?from\s*["']([^"']+)["']/g;
13 const NAMESPACE = /import\s*\*\s*as\s+([A-Za-z_$][\w$]*)\s*from\s*["']([^"']+)["']/g;
14 const ROUTE = /router\.add\(\s*"GET"\s*,\s*"([^"]+)"\s*,\s*([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)?)\s*[,)]/g;
15
16 /**
17 * The module each GET route's handler comes from, by route path: a named, default or namespace
18 * import used as `handler` or `ns.handler`. An inline or wrapped handler has no module here; the
19 * page is then reported untraced by `pagesShowing`.
20 */
21 export function routeModules(serverText: string): Map<string, string> {
22 const from = new Map<string, string>();
23 for (const m of serverText.matchAll(NAMED)) {
24 for (const part of m[1]!.split(",")) {
25 const [name, alias] = part.trim().replace(/^type\s+/, "").split(/\s+as\s+/);
26 if (name) from.set((alias ?? name).trim(), resolveSpecifier(SERVER, m[2]!));
27 }
28 }
29 for (const m of serverText.matchAll(DEFAULT)) from.set(m[1]!, resolveSpecifier(SERVER, m[2]!));
30 for (const m of serverText.matchAll(NAMESPACE)) from.set(m[1]!, resolveSpecifier(SERVER, m[2]!));
outdated

Takes the first fitting :param route. Pick the route with the most literal segments, and add a test.

31 const out = new Map<string, string>();
32 for (const m of serverText.matchAll(ROUTE)) {
33 const file = from.get(m[2]!.split(".")[0]!);
34 if (file && !out.has(m[1]!)) out.set(m[1]!, file);
35 }
36 return out;
37 }
38
39 /**
40 * Does a route's segments fit a path's, and with how many literal segments (more is more specific)?
41 */
42 function fit(route: string, path: string): number {
43 const r = route.split("/");
44 const parts = path.split("/");
45 if (r.length !== parts.length) return -1;
46 let literal = 0;
47 for (let i = 0; i < r.length; i++) {
48 if (r[i]!.startsWith(":")) continue;
49 if (r[i] !== parts[i]) return -1;
50 literal++;
51 }
52 return literal;
53 }
54
55 /**
56 * The module for a path: the exact route, else the fitting `:param` route with the most literal
57 * segments.
58 */
59 export function routeFor(routes: ReadonlyMap<string, string>, path: string): string | undefined {
60 const exact = routes.get(path);
61 if (exact) return exact;
62 let best: string | undefined;
63 let most = -1;
64 for (const [route, file] of routes) {
65 const n = fit(route, path);
66 if (n > most) {
67 most = n;
68 best = file;
69 }
70 }
71 return best;
72 }
73
74 /** Every file `entry` reaches through relative imports, itself included. */
75 export function reach(entry: string, files: ReadonlyMap<string, string>): Set<string> {
76 const seen = new Set<string>();
77 const todo = [entry];
78 while (todo.length) {
79 const path = todo.pop()!;
80 if (seen.has(path)) continue;
81 seen.add(path);
82 const text = files.get(path);
83 if (text === undefined) continue;
84 for (const s of specifiers(text)) todo.push(resolveSpecifier(path, s));
85 }
86 return seen;
87 }
88
89 /**
90 * The pages among `looks` whose route's handler reaches any of `touched`, with the file that
91 * does; and the pages whose route could not be traced (an inline or wrapped handler, or a route
92 * not mounted by name), so "none found" is never claimed of them.
93 */
94 export function pagesShowing(
95 touched: readonly string[],
96 looks: readonly string[],
97 sources: readonly Source[],
98 ): { found: { page: string; via: string }[]; untraced: string[] } {
99 const files = new Map(sources.map((s) => [s.path, s.text]));
100 const server = files.get(SERVER);
101 if (server === undefined) return { found: [], untraced: [...looks] };
102 const routes = routeModules(server);
103 const found: { page: string; via: string }[] = [];
104 const untraced: string[] = [];
105 for (const page of looks) {
106 const module = routeFor(routes, page.split(/[?#]/)[0]!);
107 if (!module) {
108 untraced.push(page);
109 continue;
110 }
111 const via = touched.find((t) => reach(module, files).has(t));
112 if (via) found.push({ page, via });
113 }
114 return { found, untraced };
115 }
src/kernel/look_rule.ts +25 −7
@@ -20,19 +20,37 @@ export function renderChanged(changes: readonly Change[]): string[] {
2020 return changes.filter((c) => !c.status.startsWith("D") && RENDERS.test(c.path)).map((c) => c.path);
2121 }
2222
23 /** One line per problem: none when nothing rendered changes, or a commit names a pictured page
24 * or waives it. */
25 export function lookProblems(changes: readonly Change[], messages: readonly string[], looks: readonly string[]): string[] {
23 export type Inferred = { found: { page: string; via: string }[]; untraced: string[] };
24
25 /**
26 * One note, never a failure (#13362): nothing when nothing rendered changes, or a commit names a
27 * pictured page or waives it. Otherwise the pages the forge chose (`infer`: the pages of
28 * `looks` whose routes reach the changed files) and why, or that none was found. Each note
29 * starts `look pages (inferred|named|none)` so a log can be counted.
30 */
31 export function lookNotes(
32 changes: readonly Change[],
33 messages: readonly string[],
34 looks: readonly string[],
35 infer: (touched: readonly string[]) => Inferred = () => ({ found: [], untraced: [] }),
36 ): string[] {
2637 const touched = renderChanged(changes);
2738 if (touched.length === 0) return [];
2839 if (messages.some((m) => WAIVER.test(m))) return [];
2940 const named = messages.flatMap((m) => [...m.matchAll(new RegExp(LOOKS.source, "gim"))].map((x) => x[1]!));
3041 if (named.some((p) => looks.includes(p))) return [];
3142 const shown = touched.slice(0, 3).join(", ") + (touched.length > 3 ? ` and ${touched.length - 3} more` : "");
32 const why = named.length
33 ? `"Looks: ${named[0]}" is not a page of app.looks in forge.json (add it there, or name one that is)`
34 : `no commit message has a "Looks: <path>" line naming the page of app.looks that shows it`;
43 const stray = named.length ? `"Looks: ${named[0]}" is not a page of app.looks in forge.json; ` : "";
44 const { found, untraced } = infer(touched);
45 if (found.length) {
46 const pages = found.slice(0, 3).map((f) => `${f.page} (${f.via})`).join(", ") + (found.length > 3 ? ` and ${found.length - 3} more` : "");
47 return [`look pages (inferred): ${stray}this pull changes ${shown}; the forge pictures ${pages}, the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides`];
48 }
49 const names = untraced.slice(0, 3).join(", ") + (untraced.length > 3 ? ` and ${untraced.length - 3} more` : "");
50 const cannot = untraced.length
51 ? `the forge could not trace the route of ${names} (an inline or wrapped handler), so it could not infer a page`
52 : "no page of app.looks imports it";
3553 return [
36 `rule "before/after looks": this pull changes ${shown} but ${why}; the forge takes the before/after pictures (light and dark) of that page on the preview. Or put a "No look: <why>" line (10+ characters) in a commit message`,
54 `look pages (none): ${stray}this pull changes ${shown} but ${cannot}; the reviewer decides. A "Looks: <path>" line naming the nearest page, or a "No look: <why>" line (10+ characters), says it`,
3755 ];
3856 }
src/kernel/tui_entry.ts +5 −3
@@ -34,8 +34,10 @@ export function screenOpened(screen: string, files: readonly Source[], added: Re
3434 );
3535 }
3636
37 /** Every `.ts` file under `src/tui` in `cwd`; none when the directory is absent. */
38 export function readTui(cwd: string): Source[] {
37 /**
38 * Every `.ts` file under `root` (default `src/tui`) in `cwd`; none when the directory is absent.
39 */
40 export function readTui(cwd: string, root = "src/tui"): Source[] {
3941 const out: Source[] = [];
4042 const walk = (dir: string) => {
4143 if (!existsSync(join(cwd, dir))) return;
@@ -45,6 +47,6 @@ export function readTui(cwd: string): Source[] {
4547 else if (e.name.endsWith(".ts")) out.push({ path: rel, text: readFileSync(join(cwd, rel), "utf8") });
4648 }
4749 };
48 walk("src/tui");
50 walk(root);
4951 return out;
5052 }
test/gate-look-note.test.ts added +60
@@ -0,0 +1,60 @@
1 import { afterEach, expect, test } from "bun:test";
2 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
3 import { tmpdir } from "node:os";
4 import { join } from "node:path";
5 import { gateVerdict, lookNote } from "../scripts/gate.ts";
6 import { readTui } from "../src/kernel/tui_entry.ts";
7
8 const dirs: string[] = [];
9 const saved = process.env.FORGE_CHECK_BASE;
10 afterEach(() => {
11 for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
12 if (saved === undefined) delete process.env.FORGE_CHECK_BASE;
13 else process.env.FORGE_CHECK_BASE = saved;
14 });
15
16 function sh(cwd: string, ...args: string[]): string {
17 const r = Bun.spawnSync(["git", "-c", "user.email=t@t", "-c", "user.name=t", "-c", "commit.gpgsign=false", ...args], { cwd });
18 if (r.exitCode !== 0) throw new Error(r.stderr.toString());
19 return r.stdout.toString().trim();
20 }
21
22 /** A repository whose one page `/flow` imports a screen; the head commit edits the screen. */
23 function repo(message: string): { dir: string; base: string } {
24 const dir = mkdtempSync(join(tmpdir(), "forge-look-"));
25 dirs.push(dir);
26 sh(dir, "init", "-q", "-b", "trunk");
27 mkdirSync(join(dir, "src/http"), { recursive: true });
28 mkdirSync(join(dir, "src/web/pages"), { recursive: true });
29 writeFileSync(join(dir, "forge.json"), JSON.stringify({ app: { looks: ["/flow"] } }));
30 writeFileSync(join(dir, "src/http/server.ts"), `import { flowPage } from "../web/pages/flow.ts";\nrouter.add("GET", "/flow", flowPage);\n`);
31 writeFileSync(join(dir, "src/web/pages/flow.ts"), "export const flowPage = 1;\n");
32 sh(dir, "add", "-A");
33 sh(dir, "commit", "-qm", "base");
34 const base = sh(dir, "rev-parse", "HEAD");
35 writeFileSync(join(dir, "src/web/pages/flow.ts"), "export const flowPage = 2;\n");
36 sh(dir, "commit", "-qam", message);
37 return { dir, base };
38 }
39
40 test("a changed screen with no Looks line gives a note naming the page, from the gate's own seam", async () => {
41 const { dir, base } = repo("Edit flow\n\nTry: open /flow on the preview");
42 process.env.FORGE_CHECK_BASE = base;
43 const [note] = await lookNote(dir);
44 expect(note).toContain("look pages (inferred)");
45 expect(note).toContain("/flow (src/web/pages/flow.ts)");
46 });
47
48 test("the gate's verdict carries the look note as a note and never in its refusal", async () => {
49 const { dir, base } = repo("Edit flow\n\nTry: open /flow on the preview\nNo door: the terminal shows nothing new here");
50 process.env.FORGE_CHECK_BASE = base;
51 const { notes, refusal } = await gateVerdict(dir);
52 expect(notes.some((n) => n.startsWith("look pages (inferred)"))).toBe(true);
53 expect(refusal.filter((r) => /look pages|before\/after looks/.test(r))).toEqual([]);
54 });
55
56 test("readTui reads the root it is given", () => {
57 const { dir } = repo("x");
58 expect(readTui(dir, "src/http").map((f) => f.path)).toEqual(["src/http/server.ts"]);
59 expect(readTui(dir, "src/nowhere")).toEqual([]);
60 });
test/look-rule.test.ts +68 −16
@@ -1,29 +1,81 @@
11 import { expect, test } from "bun:test";
2 import { lookProblems } from "../src/kernel/look_rule.ts";
2 import { lookNotes } from "../src/kernel/look_rule.ts";
3 import { pagesShowing, routeFor, routeModules } from "../src/kernel/look_pages.ts";
34
45 const ch = (status: string, path: string) => ({ status, path });
56 const looks = ["/", "/flow", "/settings/crew?help"];
67 const edit = ch("M", "src/web/pages/talk.ts");
8 const shows = (page: string) => () => ({ found: [{ page, via: "src/web/pages/talk.ts" }], untraced: [] });
79
8 test("a changed screen with no Looks line is refused, naming the rule", () => {
9 const [p] = lookProblems([edit], ["Open prompt"], looks);
10 expect(p).toContain('rule "before/after looks"');
11 expect(p).toContain("src/web/pages/talk.ts");
12 expect(p).toContain('"Looks: <path>"');
10 test("a changed screen with no Looks line is a note naming the inferred pages, never a refusal", () => {
11 const [n] = lookNotes([edit], ["Open prompt"], looks, shows("/flow"));
12 expect(n).toContain("look pages (inferred)");
13 expect(n).toContain("/flow (src/web/pages/talk.ts)");
1314 });
1415
15 test("a Looks line must name a page of app.looks", () => {
16 expect(lookProblems([edit], ["x\n\nLooks: /flow"], looks)).toEqual([]);
17 expect(lookProblems([edit], ["Looks: /settings/crew?help open prompt"], looks)).toEqual([]);
18 expect(lookProblems([edit], ["Looks: /nowhere"], looks)[0]).toContain("is not a page of app.looks");
16 test("no page found says so and asks for a line", () => {
17 const [n] = lookNotes([edit], ["Open prompt"], looks);
18 expect(n).toContain("look pages (none)");
19 expect(n).toContain("No look:");
1920 });
2021
21 test("No look waives with a reason; short reasons do not", () => {
22 expect(lookProblems([edit], ["No look: copy change inside a hidden admin form"], looks)).toEqual([]);
23 expect(lookProblems([edit], ["No look: no"], looks)).toHaveLength(1);
22 test("a Looks line naming a page of app.looks is the override; a stray one is noted", () => {
23 expect(lookNotes([edit], ["x\n\nLooks: /flow"], looks)).toEqual([]);
24 expect(lookNotes([edit], ["Looks: /settings/crew?help open prompt"], looks)).toEqual([]);
25 expect(lookNotes([edit], ["Looks: /nowhere"], looks, shows("/"))[0]).toContain("is not a page of app.looks");
2426 });
2527
26 test("css counts; deletions, tests and other files are never asked", () => {
27 expect(lookProblems([ch("A", "src/web/theme.css")], [], looks)).toHaveLength(1);
28 expect(lookProblems([ch("D", "src/web/pages/a.ts"), ch("M", "src/core/x.ts"), ch("M", "test/a.test.ts")], [], looks)).toEqual([]);
28 test("No look waives with a reason; a short one does not", () => {
29 expect(lookNotes([edit], ["No look: copy change inside a hidden admin form"], looks)).toEqual([]);
30 expect(lookNotes([edit], ["No look: no"], looks)).toHaveLength(1);
31 });
32
33 test("css counts; deletions, tests and other files are never noted", () => {
34 expect(lookNotes([ch("A", "src/web/theme.css")], [], looks)).toHaveLength(1);
35 expect(lookNotes([ch("D", "src/web/pages/a.ts"), ch("M", "src/core/x.ts"), ch("M", "test/a.test.ts")], [], looks)).toEqual([]);
36 });
37
38 const server = `import { flowPage, other as renamed } from "../web/pages/flow.ts";
39 router.add("GET", "/flow", flowPage);
40 router.add("GET", "/x", renamed);
41 router.add("POST", "/p", flowPage);`;
42 const sources = [
43 { path: "src/http/server.ts", text: server },
44 { path: "src/web/pages/flow.ts", text: `import { row } from "../row.ts";` },
45 { path: "src/web/row.ts", text: "" },
46 { path: "src/web/render/epub.ts", text: "" },
47 ];
48
49 test("routes map to the module of their handler", () => {
50 expect([...routeModules(server)]).toEqual([["/flow", "src/web/pages/flow.ts"], ["/x", "src/web/pages/flow.ts"]]);
51 });
52
53 test("a page shows a file its handler imports, deeply; a file nothing imports shows on none", () => {
54 expect(pagesShowing(["src/web/row.ts"], looks, sources).found).toEqual([{ page: "/flow", via: "src/web/row.ts" }]);
55 expect(pagesShowing(["src/web/render/epub.ts"], ["/flow"], sources)).toEqual({ found: [], untraced: [] });
56 });
57
58 test("a route with an inline handler is untraced, and the note says it could not infer, not that nothing imports", () => {
59 const text = `import { flowPage } from "../web/pages/flow.ts";
60 router.add("GET", "/flow", flowPage);
61 router.add("GET", "/assets/:name.css", (ctx) => asset(ctx));`;
62 const files = [{ path: "src/http/server.ts", text }, { path: "src/web/pages/flow.ts", text: "" }];
63 const traced = pagesShowing(["src/web/theme.css"], ["/flow", "/assets/a.css"], files);
64 expect(traced.untraced).toEqual(["/assets/a.css"]);
65 const [n] = lookNotes([ch("M", "src/web/theme.css")], [], looks, () => traced);
66 expect(n).toContain("could not trace");
67 expect(n).not.toContain("no page of app.looks imports it");
68 });
69
70 test("default and namespace imports place a route", () => {
71 const text = `import home from "../web/home.ts";
72 import * as pages from "../web/pages/talk.ts";
73 router.add("GET", "/", home);
74 router.add("GET", "/talk", pages.talkView);`;
75 expect([...routeModules(text)]).toEqual([["/", "src/web/home.ts"], ["/talk", "src/web/pages/talk.ts"]]);
76 });
77
78 test("the most specific :param route wins, not the first that fits", () => {
79 const routes = new Map([["/preview-admin/:id/:page/:n", "src/web/generic.ts"], ["/preview-admin/:id/pulls/:n", "src/web/pulls.ts"]]);
80 expect(routeFor(routes, "/preview-admin/sample/pulls/3")).toBe("src/web/pulls.ts");
2981 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs