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
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/14619-prior-art-before-new-code-the-crew-sees → main 2 commits fork
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 { | ||
| 422 | 422 | const MCP_SIZE_RULE = |
| 423 | 423 | "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."; |
| 424 | 424 | |
| 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 | ||
| 425 | 433 | /** |
| 426 | 434 | * A time promised to the owner is a record first (#11955); the task prompt carries it, |
| 427 | 435 | * not the system brief, to keep that short. |
| @@ -537,6 +545,7 @@ function taskBody(input: TaskInput): string { | ||
| 537 | 545 | ); |
| 538 | 546 | if (input.pull === undefined && isForge(input.repo) && namesMcp(issue.title, issue.body)) |
| 539 | 547 | out.push("", MCP_SIZE_RULE); |
| 548 | if (input.pull === undefined && isForge(input.repo)) out.push("", PRIOR_ART_RULE); | |
| 540 | 549 | if (input.pull === undefined && isForge(input.repo)) out.push("", planRule(input.tools)); |
| 541 | 550 | if (input.pull === undefined && isForge(input.repo)) out.push("", estimateRule(input.tools)); |
| 542 | 551 | out.push( |
test/brief-plan.test.ts +11
| @@ -21,3 +21,14 @@ describe("a forge task brief tells the agent to keep a plan", () => { | ||
| 21 | 21 | expect(build("notes")).not.toContain("keep_plan"); |
| 22 | 22 | }); |
| 23 | 23 | }); |
| 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 | }); |
new above
offline