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

Prior art before new code: the crew sees the forge's similar existing functions #14648

Merged opened this in answer to

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

Merged

mason/forge:mason/14619-prior-art-before-new-code-the-crew-sees → main 2 commits fork

  • Merged. mason/14619-prior-art-before-new-code-the-crew-sees was merged into main as 61970b5.

Review

Sign in to review this change.
5 files changed +258 −0
docs/features/similar.md added +28
@@ -0,0 +1,28 @@
1 ---
2 topic: Tell the crew
3 row: Similar functions: what already exists, before new code is written
4 ---
5 # Similar functions
6
7 `bun scripts/similar.ts <file>` (or `-` for stdin) lists the functions under `src/` most like a snippet, with
8 `path:line`. `bun scripts/similar.ts --diff main` does it for each function your branch adds. Read-only; flags
9 `--top N` (5), `--min S` (0.8) and `--src DIR` (`src`). Arguments are parsed by `parseArgs`, the diff by
10 `addedLines`; both are tested.
11
12 It is a builder's tool, deliberately without a `src/tui/` entry: it reads the clone, not the running forge. It indexes
13 `src/` on every run (about 6 s), so run it once on a finished draft or on the branch before pushing, not on every edit.
14
15 It is Aroma's cheap pass (Luan et al., OOPSLA 2019): tokens and adjacent token pairs, names a function declares
16 itself replaced by `#`, scored by how much of the snippet a function holds. A half-written snippet finds the whole.
17
18 The crew's brief for a forge issue names it, and asks the pull to say what it reused (#14619).
19
20 ## The hand trial (#14619)
21
22 The last 14 non-merge commits touching `src/` that added functions, each checked against `src/` as it was before the
23 commit. Three of the 14 added a helper that already existed in another shape: `attr` in the Collada pull (`xmlAttr`,
24 `src/web/render/office-zip.ts`) and `plural` in the Gerber and WebAssembly pulls (`plural`, `src/web/render/dxf.ts`).
25 Two more (`daeFromText`, `readDae`) followed `src/web/render/obj.ts` by design. Scores under 0.8 were noise.
26
27 The trial is 14 commits by hand, fewer than the 20 the issue asked for, and is a sample, not a measurement of review
28 round-trips saved. It is not tied to the pipeline items; the pull says so.
scripts/similar.ts added +160
@@ -0,0 +1,160 @@
1 /**
2 * `bun scripts/similar.ts <file|-> [--top N] [--min 0.8]`: the existing functions in src/ most like
3 * a snippet or a new function (#14619). Read-only. After Aroma (Luan et al., OOPSLA 2019,
4 * §3.2-3.3): each function is a bag of tokens with its local names (params, const/let/var) replaced
5 * by `#`; a snippet's score is the share of its own tokens that a function's bag holds
6 * (containment), so a half-written snippet still finds the whole. `--diff <base>` reads the
7 * functions a diff adds and lists, for each, its nearest existing one elsewhere.
8 */
9 import { readdirSync, readFileSync } from "node:fs";
10 import { join } from "node:path";
11
12 export type Fn = { name: string; path: string; line: number; bag: Map<string, number>; size: number };
13
14 const KEYWORDS_DECL = new Set(["const", "let", "var"]);
15 const TOKEN = /\/\/[^\n]*|\/\*[\s\S]*?\*\/|"(?:\\.|[^"\\\n])*"|'(?:\\.|[^'\\\n])*'|`(?:\\.|[^`\\])*`|[A-Za-z_$][\w$]*|\d+(?:\.\d+)?|=>|===|!==|\?\?|\?\.|&&|\|\||[^\s\w]/g;
16
17 /** Tokens of source with comments dropped and strings/numbers collapsed to their kind. */
18 export function tokens(src: string): string[] {
19 const out: string[] = [];
20 for (const m of src.matchAll(TOKEN)) {
21 const t = m[0];
22 if (t.startsWith("//") || t.startsWith("/*")) continue;
23 if (t[0] === '"' || t[0] === "'" || t[0] === "`") out.push("STR");
24 else if (/^\d/.test(t)) out.push("NUM");
25 else out.push(t);
26 }
27 return out;
28 }
29
30 /**
31 * The bag of features: tokens, names this function declares replaced by `#`, plus adjacent-pair
32 * features.
33 */
34 export function features(toks: string[]): Map<string, number> {
35 const local = new Set<string>();
36 for (let i = 0; i < toks.length; i++) {
37 if (KEYWORDS_DECL.has(toks[i]!) && /^[A-Za-z_$]/.test(toks[i + 1] ?? "")) local.add(toks[i + 1]!);
38 }
39 const open = toks.indexOf("("); // the head's parameter list is the first parenthesis
40 for (let j = open + 1; open >= 0 && j < toks.length && toks[j] !== ")"; j++) {
41 if (/^[A-Za-z_$]/.test(toks[j]!) && /^[,):=]$/.test(toks[j + 1] ?? "")) local.add(toks[j]!);
42 }
43 const t = toks.map((x) => (local.has(x) ? "#" : x));
44 const bag = new Map<string, number>();
45 const add = (k: string) => bag.set(k, (bag.get(k) ?? 0) + 1);
46 for (let i = 0; i < t.length; i++) {
47 if (/^[(){}\[\];,]$/.test(t[i]!)) continue;
48 add(t[i]!);
49 if (i + 1 < t.length) add(t[i] + " " + t[i + 1]);
50 }
51 return bag;
52 }
53
54 const HEAD = /^(?:export\s+)?(?:async\s+)?(?:function\*?\s+([A-Za-z_$][\w$]*)|const\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*(?::[^={]+)?=>)/;
55
56 /**
57 * Top-level functions of a file: a head at column 0, to the matching close brace (or the end of a
58 * one-liner).
59 */
60 export function functionsOf(path: string, src: string): Fn[] {
61 const lines = src.split("\n");
62 const found: Fn[] = [];
63 for (let i = 0; i < lines.length; i++) {
64 const m = HEAD.exec(lines[i]!);
65 if (!m) continue;
66 let end = i, depth = 0, opened = false;
67 for (; end < lines.length; end++) {
68 const l = lines[end]!.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`|\/\/.*$/g, "");
69 for (const c of l) { if (c === "{") { depth++; opened = true; } else if (c === "}") depth--; }
70 if (opened && depth <= 0) break;
71 if (!opened && /;\s*$/.test(l)) break;
72 }
73 const body = lines.slice(i, end + 1).join("\n");
74 const toks = tokens(body);
75 if (toks.length < 25) continue; // too small to be prior art
76 const bag = features(toks);
77 found.push({ name: (m[1] ?? m[2])!, path, line: i + 1, bag, size: toks.length });
78 i = end;
79 }
80 return found;
81 }
82
83 export function sourceFiles(dir: string): string[] {
84 const out: string[] = [];
85 for (const e of readdirSync(dir, { withFileTypes: true })) {
86 const p = join(dir, e.name);
87 if (e.isDirectory()) out.push(...sourceFiles(p));
88 else if (e.name.endsWith(".ts")) out.push(p);
89 }
90 return out;
91 }
92
93 export function indexOf(root: string): Fn[] {
94 return sourceFiles(root).flatMap((p) => functionsOf(p, readFileSync(p, "utf8")));
95 }
96
97 /**
98 * Share of the query's features the candidate holds (containment), tempered by how much bigger it
99 * is.
100 */
101 export function score(q: Map<string, number>, c: Map<string, number>): number {
102 let have = 0, all = 0, cs = 0;
103 for (const [k, n] of q) { all += n; have += Math.min(n, c.get(k) ?? 0); }
104 for (const n of c.values()) cs += n;
105 if (!all) return 0;
106 const contain = have / all;
107 return contain * Math.min(1, Math.sqrt(all / cs) * 2);
108 }
109
110 export function nearest(q: Map<string, number>, index: Fn[], top: number, skip?: (f: Fn) => boolean): { fn: Fn; score: number }[] {
111 return index.filter((f) => !skip?.(f)).map((fn) => ({ fn, score: score(q, fn.bag) })).sort((a, b) => b.score - a.score).slice(0, top);
112 }
113
114 function show(rows: { fn: Fn; score: number }[], min: number): string[] {
115 return rows.filter((r) => r.score >= min).map((r) => ` ${r.score.toFixed(2)} ${r.fn.name} ${r.fn.path}:${r.fn.line}`);
116 }
117
118 export type Args = { file?: string; top: number; min: number; src: string; diff?: string };
119
120 /** Flags that take a value; every other non-flag argument is the file. */
121 export function parseArgs(a: string[]): Args {
122 const out: Args = { top: 5, min: 0.8, src: "src" };
123 for (let i = 0; i < a.length; i++) {
124 const x = a[i]!;
125 if (x === "--top") out.top = Number(a[++i]);
126 else if (x === "--min") out.min = Number(a[++i]);
127 else if (x === "--src") out.src = a[++i] ?? "src";
128 else if (x === "--diff") out.diff = a[i + 1] && !a[i + 1]!.startsWith("--") ? a[++i]! : "main";
129 else if (!x.startsWith("--") || x === "-") out.file = x;
130 }
131 return out;
132 }
133
134 /** The lines a `--unified=0` diff adds, by file. */
135 export function addedLines(diff: string): Map<string, string[]> {
136 const added = new Map<string, string[]>();
137 let file = "";
138 for (const l of diff.split("\n")) {
139 if (l.startsWith("+++ b/")) file = l.slice(6);
140 else if (l.startsWith("+") && !l.startsWith("+++")) (added.get(file) ?? added.set(file, []).get(file)!).push(l.slice(1));
141 }
142 return added;
143 }
144
145 if (import.meta.main) {
146 const args = parseArgs(process.argv.slice(2));
147 const { top, min } = args;
148 const index = indexOf(args.src);
149 if (args.diff !== undefined) {
150 const proc = Bun.spawnSync(["git", "diff", "--unified=0", "--diff-filter=AM", `${args.diff}...HEAD`, "--", "src"]);
151 for (const [f, ls] of addedLines(proc.stdout.toString())) for (const fn of functionsOf(f, ls.join("\n"))) {
152 const hits = show(nearest(fn.bag, index, top, (x) => x.path === f), min);
153 if (hits.length) console.log(`${fn.name} (${f})\n${hits.join("\n")}`);
154 }
155 } else {
156 const src = args.file && args.file !== "-" ? readFileSync(args.file, "utf8") : await Bun.stdin.text();
157 const hits = show(nearest(features(tokens(src)), index, top), min);
158 console.log(hits.length ? hits.join("\n") : "nothing like it under src/");
159 }
160 }
src/crew/brief.ts +9
@@ -422,6 +422,14 @@ export function taskPrompt(input: TaskInput): string {
422422 const MCP_SIZE_RULE =
423423 "This issue touches the MCP. Run `bun test test/mcp-size.test.ts` before pushing; it names the five costliest tools when it fails. Prefer an `action` or `kind` on an existing tool (docs/MCP.md, \"Room for a new tool\") over a new tool, and never raise the ceilings.";
424424
425 /**
426 * Prior art before new code (#14619): a hand trial found 3 of 14 pulls adding a helper the forge
427 * already had in another shape. The clone carries the finder, so the brief names it; only the
428 * forge's own repository has it.
429 */
430 export const PRIOR_ART_RULE =
431 "Before writing a new function, run `bun scripts/similar.ts <file>` on a draft (or `--diff main` on your branch) to list the existing ones most like it; reuse one that fits, and say in the description what you reused.";
432
425433 /**
426434 * A time promised to the owner is a record first (#11955); the task prompt carries it,
427435 * not the system brief, to keep that short.
@@ -537,6 +545,7 @@ function taskBody(input: TaskInput): string {
537545 );
538546 if (input.pull === undefined && isForge(input.repo) && namesMcp(issue.title, issue.body))
539547 out.push("", MCP_SIZE_RULE);
548 if (input.pull === undefined && isForge(input.repo)) out.push("", PRIOR_ART_RULE);
540549 if (input.pull === undefined && isForge(input.repo)) out.push("", planRule(input.tools));
541550 if (input.pull === undefined && isForge(input.repo)) out.push("", estimateRule(input.tools));
542551 out.push(
test/brief-plan.test.ts +11
@@ -21,3 +21,14 @@ describe("a forge task brief tells the agent to keep a plan", () => {
2121 expect(build("notes")).not.toContain("keep_plan");
2222 });
2323 });
24
25 describe("a forge task brief names the similar-functions finder (#14619)", () => {
26 test("the forge's own brief says to run it and to report what was reused", () => {
27 const text = build("forge");
28 expect(text).toContain("bun scripts/similar.ts");
29 expect(text).toContain("what you reused");
30 });
31 test("another repository's brief does not", () => {
32 expect(build("notes")).not.toContain("similar.ts");
33 });
34 });
test/similar.test.ts added +50
@@ -0,0 +1,50 @@
1 import { describe, expect, test } from "bun:test";
2 import { addedLines, features, functionsOf, nearest, parseArgs, score, tokens } from "../scripts/similar.ts";
3
4 const lib = `
5 export const plural = (n: number, one: string): string => \`\${n.toLocaleString("en")} \${one}\${n === 1 ? "" : "s"}\`;
6
7 export function slugFor(name: string): string {
8 const lower = name.toLowerCase();
9 const dashed = lower.replace(/[^a-z0-9]+/g, "-");
10 return dashed.replace(/^-+|-+$/g, "");
11 }
12 `;
13
14 describe("scripts/similar.ts finds prior art (#14619)", () => {
15 test("finds functions by their top-level heads", () => {
16 const names = functionsOf("lib.ts", lib).map((f) => f.name);
17 expect(names).toContain("slugFor");
18 });
19 test("a copy with other local names still ranks its original first", () => {
20 const index = functionsOf("lib.ts", lib);
21 const draft = `function toSlug(input: string): string {
22 const a = input.toLowerCase();
23 const b = a.replace(/[^a-z0-9]+/g, "-");
24 return b.replace(/^-+|-+$/g, "");
25 }`;
26 const [best] = nearest(features(tokens(draft)), index, 1);
27 expect(best?.fn.name).toBe("slugFor");
28 expect(best!.score).toBeGreaterThan(0.8);
29 });
30 test("an unrelated snippet scores low", () => {
31 const q = features(tokens("for (const row of rows) { await fetch(url + row.id, { method: 'POST' }); }"));
32 expect(score(q, functionsOf("lib.ts", lib)[0]!.bag)).toBeLessThan(0.5);
33 });
34 });
35
36 describe("similar.ts command line (#14619)", () => {
37 test("a file named like a flag value is still the file", () => {
38 expect(parseArgs(["5", "--top", "5"])).toEqual({ file: "5", top: 5, min: 0.8, src: "src" });
39 });
40 test("flags and --diff default", () => {
41 const a = parseArgs(["--diff", "--min", "0.5", "--src", "lib"]);
42 expect([a.diff, a.min, a.src, a.file]).toEqual(["main", 0.5, "lib", undefined]);
43 expect(parseArgs(["--diff", "dev"]).diff).toBe("dev");
44 expect(parseArgs(["-"]).file).toBe("-");
45 });
46 test("added lines are grouped by file, headers dropped", () => {
47 const diff = "+++ b/src/a.ts\n@@ -0,0 +1,2 @@\n+one\n+two\n+++ b/src/b.ts\n+three\n-gone\n";
48 expect([...addedLines(diff)]).toEqual([["src/a.ts", ["one", "two"]], ["src/b.ts", ["three"]]]);
49 });
50 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs