@a-t-h-i/bot-lobby 0.6.60 → 0.6.62

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/README.md +3 -7
  2. package/package.json +2 -1
  3. package/prompts/designer.md +25 -15
  4. package/prompts/master.md +284 -491
  5. package/prompts/panel.md +7 -0
  6. package/prompts/planner.md +15 -4
  7. package/prompts/qa.md +5 -1
  8. package/prompts/worker.md +0 -7
  9. package/scripts/builtin/affected_packages.mjs +106 -0
  10. package/scripts/builtin/check_changed.mjs +51 -0
  11. package/scripts/builtin/check_contract_breakage.mjs +118 -0
  12. package/scripts/builtin/circular_dependency_check.mjs +79 -0
  13. package/scripts/builtin/code_duplication_check.mjs +86 -0
  14. package/scripts/builtin/diff_summary.mjs +62 -0
  15. package/scripts/builtin/failure_digest.mjs +107 -0
  16. package/scripts/builtin/find_generated_files.mjs +79 -0
  17. package/scripts/builtin/find_symbol.mjs +81 -0
  18. package/scripts/builtin/find_test_fixtures.mjs +73 -0
  19. package/scripts/builtin/find_tests_for.mjs +12 -0
  20. package/scripts/builtin/lib/common.mjs +267 -0
  21. package/scripts/builtin/outline_file.mjs +77 -0
  22. package/scripts/builtin/project_commands.mjs +49 -0
  23. package/scripts/builtin/recent_changes.mjs +14 -0
  24. package/scripts/builtin/repo_map.mjs +65 -0
  25. package/scripts/builtin/run_changed_tests.mjs +48 -0
  26. package/src/delivery/transport.ts +1 -1
  27. package/src/desk/client-extension.ts +1 -31
  28. package/src/desk/ipc.ts +1 -11
  29. package/src/desk/session.ts +4 -101
  30. package/src/execution/agent-runner.ts +50 -8
  31. package/src/execution/assigned-session.ts +263 -0
  32. package/src/execution/assignment-discovery.ts +128 -0
  33. package/src/execution/assignment-policy.ts +46 -0
  34. package/src/execution/assignment.ts +175 -0
  35. package/src/execution/delegation.ts +9 -94
  36. package/src/execution/pi-runner.ts +99 -9
  37. package/src/harness/instructions.ts +1 -1
  38. package/src/index.ts +3 -0
  39. package/src/knowledge/design-record.ts +394 -0
  40. package/src/knowledge/file-notes.ts +36 -8
  41. package/src/lobby/ask.ts +6 -0
  42. package/src/lobby/exec.ts +28 -0
  43. package/src/lobby/host.ts +1 -11
  44. package/src/lobby/planner.ts +50 -124
  45. package/src/lobby/prompts.ts +1 -7
  46. package/src/lobby/runtime.ts +2 -26
  47. package/src/lobby/service.ts +25 -23
  48. package/src/lobby/topics.ts +0 -2
  49. package/src/master/evidence-freshness.ts +96 -0
  50. package/src/master/master.ts +248 -74
  51. package/src/master/scout-cache.ts +1 -1
  52. package/src/master/scout-lock.ts +44 -0
  53. package/src/master/scout-prefetch.ts +78 -0
  54. package/src/pi/activity.ts +2 -0
  55. package/src/pi/assignment-guard.ts +157 -0
  56. package/src/pi/delegation.ts +2 -21
  57. package/src/pi/model-support.ts +0 -6
  58. package/src/pi/start-task.ts +18 -7
  59. package/src/pi/tools.ts +41 -8
  60. package/src/roles/scout.ts +3 -1
  61. package/src/roles/worker.ts +107 -5
  62. package/src/schemas/configuration.ts +11 -45
  63. package/src/schemas/findings.ts +3 -0
  64. package/src/schemas/task.ts +30 -12
  65. package/src/scripts/library.ts +31 -1
  66. package/src/scripts/pick.ts +31 -15
  67. package/src/state/archive.ts +10 -0
  68. package/src/state/checkpoint.ts +0 -1
  69. package/src/state/gitignore.ts +39 -0
  70. package/src/state/persistence.ts +56 -0
  71. package/src/state/recovery.ts +33 -1
  72. package/src/webui/api/index.ts +6 -35
  73. package/src/webui/api/retention.ts +44 -0
  74. package/src/webui/api/status.ts +4 -6
  75. package/src/webui/dev/fake-service.ts +0 -117
  76. package/src/webui/dev/fixtures.ts +2 -16
  77. package/src/webui/protocol.ts +2 -142
  78. package/src/workflow/draft-assignments.ts +118 -0
  79. package/src/workflow/workflow.ts +271 -214
  80. package/webui/dist/assets/{CodeSurface-BtzJOVyH.js → CodeSurface-D3c12DBE.js} +1 -1
  81. package/webui/dist/assets/{TerminalView-Cz-KNWsq.js → TerminalView-DG4X3Yyr.js} +1 -1
  82. package/webui/dist/assets/index-BDmgr1OS.js +112 -0
  83. package/webui/dist/assets/index-BTyu99rI.css +2 -0
  84. package/webui/dist/build.json +29 -65
  85. package/webui/dist/index.html +2 -2
  86. package/prompts/expert.md +0 -17
  87. package/prompts/goal-check.md +0 -44
  88. package/prompts/pr-review.md +0 -62
  89. package/prompts/splitter.md +0 -58
  90. package/src/execution/worker-trees.ts +0 -396
  91. package/src/lobby/issues.ts +0 -219
  92. package/src/lobby/pr-review.ts +0 -366
  93. package/src/lobby/pulls.ts +0 -250
  94. package/src/lobby/split.ts +0 -262
  95. package/src/master/goal-check.ts +0 -115
  96. package/src/webui/api/gh-error.ts +0 -17
  97. package/src/webui/api/git.ts +0 -98
  98. package/src/webui/api/issues.ts +0 -50
  99. package/webui/dist/assets/index-D5fvY8f8.js +0 -112
  100. package/webui/dist/assets/index-DFvk8ADr.css +0 -2
package/prompts/panel.md CHANGED
@@ -76,3 +76,10 @@ Omit Questions when READY.)
76
76
 
77
77
  ## Notes
78
78
  - …
79
+
80
+ ## Style
81
+ spacing, radius
82
+
83
+ (DESIGN only, and only when the work changes what the user sees: the keys of
84
+ the design record fields it touches that the record lists as not settled.
85
+ The user is asked those with fixed options; omit the section otherwise.)
@@ -3,7 +3,8 @@
3
3
  You are the oracle chairing a planning panel: you help the user turn an idea
4
4
  (or a GitHub issue) into a task plan that the team of agents can execute
5
5
  without guessing. The panel's domain members — DEV, DESIGN, QA and RESEARCH —
6
- bring you their questions each round, and you decide which ones reach the
6
+ bring you their questions in the first round; after that you plan alone and
7
+ call a member back only when you need it. You decide which questions reach the
7
8
  user: you own the plan and the questions. You are thorough but you spare the
8
9
  user: every decision that changes the implementation gets made, either by the
9
10
  user or, when the answer is quite obvious, by you, written down as an
@@ -65,9 +66,15 @@ below.
65
66
  - Ground every claim about the codebase in files you read; name them.
66
67
  - Keep a draft plan updated every turn so the user sees it converge.
67
68
 
68
- Declare the plan READY only when every panel member is READY and nothing
69
- that would change the implementation is still open. Until then the status is
70
- GRILLING.
69
+ After the first round the members do not sit unless you name them under
70
+ `## Consult`: list a member only when an answer or a new direction needs its
71
+ domain's eyes (a schema change for DEV, a new screen for DESIGN). Each member
72
+ you name reads the code again, which costs the user time, so leave the section
73
+ out when you can settle it yourself.
74
+
75
+ Declare the plan READY only when every member that sat this round is READY and
76
+ nothing that would change the implementation is still open. Until then the
77
+ status is GRILLING.
71
78
 
72
79
  ## Round limit
73
80
 
@@ -103,6 +110,10 @@ Three to six words naming the task.
103
110
  question, labels of one to five words, `(Recommended)` only on an obvious one. Omit the Questions section when READY
104
111
  or when you decided everything yourself.)
105
112
 
113
+ ## Consult
114
+ DEV, DESIGN, QA or RESEARCH: the members to sit next round. (Omit the section
115
+ when you need none, which is most rounds.)
116
+
106
117
  ## Plan
107
118
  The current draft, in Markdown:
108
119
 
package/prompts/qa.md CHANGED
@@ -47,7 +47,8 @@ you state in the report.
47
47
 
48
48
  ## Verify in this order
49
49
 
50
- 1. Understand the acceptance criteria.
50
+ 1. Understand the acceptance criteria and the user's own request with its
51
+ amendments: the plan can drift from what the user asked for.
51
52
  2. Read the QA risk.
52
53
  3. Read the implementation and the diff.
53
54
  4. Name the realistic failure modes.
@@ -153,6 +154,9 @@ A PASS is a claim backed by evidence, not an absence of complaints.
153
154
  A PASS without executed checks is downgraded by the engine to
154
155
  CHANGES_REQUIRED.
155
156
  - Check every acceptance criterion; an unmet or unverifiable one is a finding.
157
+ - Check the change against the user's own request, not only the plan: a
158
+ requirement it does not meet is a `[major]` finding, unless the user agreed
159
+ to leave it out.
156
160
  - If you could not verify something important, say so and never PASS on
157
161
  assumption. Verify it another way first (the typecheck, a narrower test,
158
162
  reading the code path); if it stays unverifiable, return CHANGES_REQUIRED
package/prompts/worker.md CHANGED
@@ -89,13 +89,6 @@ repository at the same time, and files are checked out like physical documents:
89
89
  `blocker` on someone else's part, and `done` when a piece is finished and
90
90
  testable. Exact facts, a line or two each; never progress chatter. Read the
91
91
  board (`read_board`) before you build against another domain's part.
92
- - **Peers.** When `ask_peer` is available, ask the worker who owns a part a
93
- short question instead of guessing a name or a shape; answer theirs with
94
- `answer_peer` straight away. Nobody takes work from a peer: only from the
95
- brief.
96
- - **Expert.** When `ask_expert` is available and you are stuck after a real
97
- attempt, or unsure about a hard choice, ask it with what you tried and the
98
- files involved. Use it for the hard part, not to think for you.
99
92
  - **Long findings** go in a file under the task's notes folder (your context
100
93
  names it); give its path under Notes.
101
94
 
@@ -0,0 +1,106 @@
1
+ #!/usr/bin/env node
2
+ // purpose: in a monorepo, list the workspace packages the branch changed and every package that depends on them (directly or through others), with the command to test each, so only affected packages are built and tested
3
+ // usage: node {script} [--base <ref>]
4
+ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
5
+ import { join } from "node:path";
6
+ import { baseRef, changedFiles, detect, parseArgs, projectRoot, readJson } from "./lib/common.mjs";
7
+
8
+ const { flags } = parseArgs();
9
+ const root = projectRoot();
10
+ const { pkg, pm } = detect(root);
11
+
12
+ /** Workspace globs from package.json, pnpm-workspace.yaml, Cargo.toml and go.work. */
13
+ function patterns() {
14
+ const out = [];
15
+ const ws = pkg?.workspaces;
16
+ out.push(...(Array.isArray(ws) ? ws : ws?.packages ?? []));
17
+ const yaml = (() => { try { return readFileSync(join(root, "pnpm-workspace.yaml"), "utf8"); } catch { return ""; } })();
18
+ const block = /packages:\s*\n((?:\s*-.*\n?)+)/.exec(yaml);
19
+ if (block) out.push(...block[1].split("\n").map((row) => row.replace(/^\s*-\s*/, "").replace(/['"]/g, "").trim()).filter(Boolean));
20
+ const cargo = (() => { try { return readFileSync(join(root, "Cargo.toml"), "utf8"); } catch { return ""; } })();
21
+ const members = /\[workspace\][^[]*?members\s*=\s*\[([^\]]*)\]/s.exec(cargo);
22
+ if (members) out.push(...[...members[1].matchAll(/["']([^"']+)["']/g)].map((m) => m[1]));
23
+ const gowork = (() => { try { return readFileSync(join(root, "go.work"), "utf8"); } catch { return ""; } })();
24
+ for (const m of gowork.matchAll(/^\s*(?:use\s+)?(\.\/[\w./-]+)\s*$/gm)) out.push(m[1].replace(/^\.\//, ""));
25
+ return out.filter((pattern) => !pattern.startsWith("!"));
26
+ }
27
+
28
+ /** Folders a workspace glob names (`*` one level, `**` any depth). */
29
+ function expand(pattern) {
30
+ const parts = pattern.replace(/^\.\//, "").replace(/\/$/, "").split("/");
31
+ let dirs = [""];
32
+ for (const part of parts) {
33
+ const next = [];
34
+ for (const dir of dirs) {
35
+ const here = join(root, dir);
36
+ if (part === "**") {
37
+ const walk = (rel, depth) => {
38
+ next.push(rel);
39
+ if (depth > 4) return;
40
+ for (const name of safeList(join(root, rel))) if (!name.startsWith(".") && name !== "node_modules") walk(join(rel, name), depth + 1);
41
+ };
42
+ walk(dir, 0);
43
+ } else if (part.includes("*")) {
44
+ const re = new RegExp(`^${part.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")}$`);
45
+ for (const name of safeList(here)) if (re.test(name)) next.push(join(dir, name));
46
+ } else if (existsSync(join(here, part))) next.push(join(dir, part));
47
+ }
48
+ dirs = next;
49
+ }
50
+ return dirs.filter((dir) => dir && ["package.json", "Cargo.toml", "go.mod", "pyproject.toml"].some((file) => existsSync(join(root, dir, file))));
51
+ }
52
+ function safeList(dir) {
53
+ try {
54
+ return readdirSync(dir).filter((name) => statSync(join(dir, name)).isDirectory());
55
+ } catch {
56
+ return [];
57
+ }
58
+ }
59
+
60
+ const packages = new Map();
61
+ for (const dir of new Set(patterns().flatMap(expand))) {
62
+ const json = readJson(join(root, dir, "package.json"));
63
+ const cargo = (() => { try { return readFileSync(join(root, dir, "Cargo.toml"), "utf8"); } catch { return ""; } })();
64
+ const gomod = (() => { try { return readFileSync(join(root, dir, "go.mod"), "utf8"); } catch { return ""; } })();
65
+ const name = json?.name ?? /^\s*name\s*=\s*"([^"]+)"/m.exec(cargo)?.[1] ?? /^module\s+(\S+)/m.exec(gomod)?.[1] ?? dir;
66
+ const deps = new Set([
67
+ ...Object.keys({ ...json?.dependencies, ...json?.devDependencies, ...json?.peerDependencies, ...json?.optionalDependencies }),
68
+ ...[...cargo.matchAll(/^\s*([\w-]+)\s*=\s*\{[^}]*path\s*=/gm)].map((m) => m[1]),
69
+ ...[...gomod.matchAll(/^\s*(?:require\s+)?(\S+)\s+v[\d.]+/gm)].map((m) => m[1]),
70
+ ]);
71
+ packages.set(name, { name, dir, deps, json: Boolean(json), cargo: Boolean(cargo), go: Boolean(gomod) });
72
+ }
73
+ if (packages.size === 0) {
74
+ console.log("Not a monorepo: no workspaces declared (package.json workspaces, pnpm-workspace.yaml, Cargo workspace or go.work). The whole project is one package.");
75
+ process.exit(0);
76
+ }
77
+
78
+ const base = baseRef(root, flags.base);
79
+ const changed = changedFiles(root, base);
80
+ const owner = (file) => [...packages.values()].filter((p) => file === p.dir || file.startsWith(`${p.dir}/`)).sort((a, b) => b.dir.length - a.dir.length)[0];
81
+ const direct = new Map();
82
+ const outside = [];
83
+ for (const file of changed) {
84
+ const p = owner(file);
85
+ if (p) direct.set(p.name, [...(direct.get(p.name) ?? []), file]);
86
+ else outside.push(file);
87
+ }
88
+ // Reverse edges: who depends on whom inside the workspace.
89
+ const dependents = new Map();
90
+ for (const p of packages.values()) for (const dep of p.deps) if (packages.has(dep)) dependents.set(dep, [...(dependents.get(dep) ?? []), p.name]);
91
+ const reached = new Map();
92
+ const queue = [...direct.keys()];
93
+ while (queue.length) {
94
+ const name = queue.shift();
95
+ for (const user of dependents.get(name) ?? []) if (!direct.has(user) && !reached.has(user)) { reached.set(user, name); queue.push(user); }
96
+ }
97
+ const test = (p) => p.json ? (pm === "pnpm" ? `pnpm --filter ${p.name} test` : pm === "yarn" ? `yarn workspace ${p.name} test` : pm === "bun" ? `bun --filter ${p.name} test` : `npm test -w ${p.dir}`) : p.cargo ? `cargo test -p ${p.name}` : p.go ? `go test ./${p.dir}/...` : `(cd ${p.dir} && run its tests)`;
98
+
99
+ console.log(`# ${packages.size} workspace package(s); ${direct.size} changed, ${reached.size} more depend on them`);
100
+ for (const [name, files] of direct) console.log(`changed ${name} (${packages.get(name).dir}, ${files.length} file(s)) → ${test(packages.get(name))}`);
101
+ for (const [name, via] of reached) console.log(`affected ${name} (${packages.get(name).dir}, through ${via}) → ${test(packages.get(name))}`);
102
+ if (outside.length) {
103
+ const shared = outside.filter((file) => /(^|\/)(package\.json|pnpm-workspace\.yaml|tsconfig[\w.]*\.json|Cargo\.toml|go\.work|\.github\/|turbo\.json|nx\.json|babel\.config|eslint|vite\.config|jest\.config|vitest\.config)/.test(file));
104
+ console.log(`## ${outside.length} changed file(s) outside every package${shared.length ? `; root config changed (${shared.slice(0, 5).join(", ")}), so every package may be affected` : ""}`);
105
+ }
106
+ if (direct.size === 0 && outside.length === 0) console.log("Nothing changed.");
@@ -0,0 +1,51 @@
1
+ #!/usr/bin/env node
2
+ // purpose: typecheck and lint only what changed on this branch (or given files) with the project's own tools; prints each check's findings and a pass/fail line
3
+ // usage: node {script} [files…] [--base <ref>] [--timeout <seconds>]
4
+ import { existsSync } from "node:fs";
5
+ import { join } from "node:path";
6
+ import { baseRef, changedFiles, detect, parseArgs, projectRoot, sh, tail } from "./lib/common.mjs";
7
+
8
+ const { flags, rest } = parseArgs();
9
+ const root = projectRoot();
10
+ const tool = detect(root);
11
+ const files = rest.length > 0 ? rest : changedFiles(root, baseRef(root, flags.base));
12
+ const timeout = Number(flags.timeout ?? 240) * 1000;
13
+ const has = (name) => existsSync(join(root, name));
14
+ const pick = (pattern) => files.filter((file) => pattern.test(file));
15
+ const checks = [];
16
+
17
+ const ts = pick(/\.[cm]?tsx?$/);
18
+ if (ts.length > 0 && has("tsconfig.json")) checks.push({ name: "typecheck (whole project: tsc cannot check one file with the project's settings)", cmd: "npx", args: ["tsc", "--noEmit", "-p", "."] });
19
+ const js = pick(/\.[cm]?[jt]sx?$/);
20
+ const eslint = ["eslint.config.js", "eslint.config.mjs", "eslint.config.ts", ".eslintrc", ".eslintrc.js", ".eslintrc.cjs", ".eslintrc.json"].some(has) || tool.pkg?.eslintConfig;
21
+ if (js.length > 0 && eslint) checks.push({ name: "eslint", cmd: "npx", args: ["eslint", ...js] });
22
+ if (js.length > 0 && (has("biome.json") || has("biome.jsonc"))) checks.push({ name: "biome", cmd: "npx", args: ["biome", "check", ...js] });
23
+ const py = pick(/\.py$/);
24
+ if (py.length > 0) {
25
+ if (sh("ruff", ["--version"]).code === 0) checks.push({ name: "ruff", cmd: "ruff", args: ["check", ...py] });
26
+ else checks.push({ name: "python syntax", cmd: "python3", args: ["-m", "py_compile", ...py] });
27
+ if (has("mypy.ini") || /\[tool\.mypy\]/.test(sh("cat", ["pyproject.toml"], { cwd: root }).out)) checks.push({ name: "mypy", cmd: "python3", args: ["-m", "mypy", ...py] });
28
+ }
29
+ const go = pick(/\.go$/);
30
+ if (go.length > 0 && tool.go) checks.push({ name: "go vet", cmd: "go", args: ["vet", ...new Set(go.map((file) => `./${file.split("/").slice(0, -1).join("/") || "."}`))] });
31
+ if (pick(/\.rs$/).length > 0 && tool.rust) checks.push({ name: "cargo check", cmd: "cargo", args: ["check", "--quiet"] });
32
+
33
+ if (files.length === 0) {
34
+ console.log("No changed files: nothing to check.");
35
+ process.exit(0);
36
+ }
37
+ if (checks.length === 0) {
38
+ console.log(`Changed: ${files.length} file(s). No typechecker or linter is set up for them.`);
39
+ process.exit(0);
40
+ }
41
+ let failed = 0;
42
+ for (const check of checks) {
43
+ const result = sh(check.cmd, check.args, { cwd: root, timeout, env: { ...process.env, FORCE_COLOR: "0" } });
44
+ const ok = result.code === 0;
45
+ if (!ok) failed += 1;
46
+ console.log(`## ${check.name}: ${ok ? "clean" : `findings (exit ${result.code})`}`);
47
+ const output = `${result.out}${result.err}`.trim();
48
+ if (!ok && output) console.log(tail(output, 80));
49
+ }
50
+ console.log(failed === 0 ? "PASS" : `FAIL (${failed} of ${checks.length} checks)`);
51
+ process.exit(failed === 0 ? 0 : 1);
@@ -0,0 +1,118 @@
1
+ #!/usr/bin/env node
2
+ // purpose: list breaking changes to the public surface since the base: exported functions, classes, types and constants removed, renamed or with a changed signature, and the files that still use each
3
+ // usage: node {script} [--base <ref>]
4
+ import { readFileSync } from "node:fs";
5
+ import { basename, dirname, join, normalize } from "node:path";
6
+ import { baseRef, changedFiles, isCode, isNoise, isTest, lines, parseArgs, projectRoot, sh } from "./lib/common.mjs";
7
+
8
+ const { flags } = parseArgs();
9
+ const root = projectRoot();
10
+ const base = baseRef(root, flags.base);
11
+ const old = base === "HEAD" ? "HEAD" : base;
12
+
13
+ /** Exported names and their one-line signature (whitespace squeezed). */
14
+ function surface(text, file) {
15
+ const out = new Map();
16
+ const rows = text.split("\n");
17
+ const sig = (index) => {
18
+ // A signature runs while its brackets are open, at most a few lines.
19
+ let joined = "";
20
+ let depth = 0;
21
+ for (let i = index; i < Math.min(rows.length, index + 6); i++) {
22
+ joined += ` ${rows[i].trim()}`;
23
+ depth += (rows[i].match(/[(<[]/g) ?? []).length - (rows[i].match(/[)>\]]/g) ?? []).length;
24
+ if (depth <= 0) break;
25
+ }
26
+ return joined.replace(/\s*[{=]\s*$/, "").replace(/\s+/g, " ").trim().slice(0, 200);
27
+ };
28
+ if (file.endsWith(".py")) {
29
+ rows.forEach((row, i) => {
30
+ const m = /^(?:async\s+)?def\s+([A-Za-z]\w*)|^class\s+([A-Za-z]\w*)|^([A-Z][A-Z0-9_]+)\s*[:=]/.exec(row);
31
+ if (m) out.set(m[1] ?? m[2] ?? m[3], sig(i));
32
+ });
33
+ } else if (file.endsWith(".go")) {
34
+ rows.forEach((row, i) => {
35
+ const m = /^func\s+(?:\([^)]*\)\s*)?([A-Z]\w*)|^type\s+([A-Z]\w*)|^(?:const|var)\s+([A-Z]\w*)/.exec(row);
36
+ if (m) out.set(m[1] ?? m[2] ?? m[3], sig(i));
37
+ });
38
+ } else {
39
+ rows.forEach((row, i) => {
40
+ const m = /^export\s+(?:declare\s+)?(?:default\s+)?(?:async\s+)?(?:abstract\s+)?(?:function\*?|class|interface|type|enum|const|let|var|namespace)\s+([\w$]+)/.exec(row);
41
+ if (m) out.set(m[1], sig(i));
42
+ const list = /^export\s+(?:type\s+)?\{([^}]*)\}/.exec(row);
43
+ if (list) for (const part of list[1].split(",")) {
44
+ const name = part.trim().split(/\s+as\s+/).pop()?.replace(/^type\s+/, "");
45
+ if (name) out.set(name, `export { ${part.trim()} }`);
46
+ }
47
+ if (/^export\s+default\s/.test(row) && !m) out.set("default", sig(i));
48
+ });
49
+ }
50
+ return out;
51
+ }
52
+
53
+ const read = (file) => { try { return readFileSync(join(root, file), "utf8"); } catch { return undefined; } };
54
+ const before = (file) => {
55
+ const shown = sh("git", ["show", `${old}:${file}`], { cwd: root });
56
+ return shown.code === 0 ? shown.out : undefined;
57
+ };
58
+ const deleted = lines(sh("git", ["diff", "--name-only", "--diff-filter=D", ...(base === "HEAD" ? ["HEAD"] : [base])], { cwd: root }).out);
59
+ // Renamed files count as a removal at the old path.
60
+ const renamed = lines(sh("git", ["diff", "--name-status", "-M", "--diff-filter=R", ...(base === "HEAD" ? ["HEAD"] : [base])], { cwd: root }).out).map((row) => row.split("\t")[1]);
61
+ const files = [...new Set([...changedFiles(root, base), ...deleted, ...renamed])].filter((file) => isCode(file) && !isTest(file) && !isNoise(file));
62
+
63
+ /** Files that import this module (by its file name), else, outside JS/TS, every file naming the symbol. */
64
+ const importers = new Map();
65
+ const users = (name, file) => {
66
+ if (!/\.(m|c)?[jt]sx?$/.test(file)) {
67
+ return lines(sh("git", ["grep", "-l", "-I", "-w", name, "--", "."], { cwd: root }).out).filter((hit) => hit !== file && isCode(hit) && !isNoise(hit));
68
+ }
69
+ if (!importers.has(file)) {
70
+ const stem = basename(file).replace(/\.[^.]+$/, "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
71
+ const hits = lines(sh("git", ["grep", "-l", "-I", "-E", `(from|import|require\\().*['"/]${stem === "index" ? basename(dirname(file)) : stem}(\\.[a-z]+)?['"]`, "--", "."], { cwd: root }).out);
72
+ const target = file.replace(/\.[^./]+$/, "").replace(/\/index$/, "");
73
+ // A relative import must resolve to this file; a package or alias import is kept, it cannot be checked here.
74
+ const points = (hit) => {
75
+ const text = readFileSync(join(root, hit), "utf8");
76
+ return [...text.matchAll(/(?:from|import|require\()\s*['"]([^'"]+)['"]/g)].some(([, spec]) => !spec.startsWith(".")
77
+ ? spec.endsWith(target.split("/").pop())
78
+ : normalize(join(dirname(hit), spec)).replace(/\.[^./]+$/, "").replace(/\/index$/, "") === target);
79
+ };
80
+ importers.set(file, hits.filter((hit) => hit !== file && !isNoise(hit) && points(hit)));
81
+ }
82
+ return importers.get(file).filter((hit) => name === "default" || new RegExp(`\\b${name.replace(/\$/g, "\\$")}\\b`).test(readFileSync(join(root, hit), "utf8")));
83
+ };
84
+
85
+ let breaks = 0;
86
+ const report = [];
87
+ for (const file of files.sort()) {
88
+ const was = before(file);
89
+ if (was === undefined) continue; // new file: nothing to break
90
+ const now = read(file);
91
+ const a = surface(was, file);
92
+ const b = now === undefined ? new Map() : surface(now, file);
93
+ const rows = [];
94
+ for (const [name, signature] of a) {
95
+ if (!b.has(name)) rows.push({ kind: "removed", name, was: signature });
96
+ else if (b.get(name) !== signature) rows.push({ kind: "changed", name, was: signature, now: b.get(name) });
97
+ }
98
+ const added = [...b.keys()].filter((name) => !a.has(name));
99
+ // A removal next to an addition is likely a rename.
100
+ for (const row of rows) if (row.kind === "removed" && added.length === 1 && rows.filter((r) => r.kind === "removed").length === 1) row.kind = `renamed to ${added[0]}?`;
101
+ if (rows.length === 0) continue;
102
+ report.push(`## ${file}${now === undefined ? " (deleted)" : ""}`);
103
+ for (const row of rows) {
104
+ breaks += 1;
105
+ const using = users(row.name, file);
106
+ report.push(` ${row.kind}: ${row.name}${using.length ? ` — used in ${using.length} file(s): ${using.slice(0, 5).join(", ")}${using.length > 5 ? ", …" : ""}` : " — no other file names it"}`);
107
+ report.push(` was: ${row.was}`);
108
+ if (row.now) report.push(` now: ${row.now}`);
109
+ }
110
+ }
111
+ if (breaks === 0) {
112
+ console.log(`No exported name removed or changed since ${base === "HEAD" ? "the last commit" : base.slice(0, 12)}.`);
113
+ process.exit(0);
114
+ }
115
+ console.log(`# ${breaks} exported name(s) removed or changed since ${base === "HEAD" ? "the last commit" : base.slice(0, 12)}`);
116
+ console.log(report.join("\n"));
117
+ console.log("Changed signatures may be harmless (an added optional parameter); a removal or rename with users left is a break.");
118
+ process.exit(1);
@@ -0,0 +1,79 @@
1
+ #!/usr/bin/env node
2
+ // purpose: find circular imports between the project's JS/TS and Python modules (type-only imports ignored); by default only cycles through files changed on the branch
3
+ // usage: node {script} [--all] [--base <ref>]
4
+ import { baseRef, changedFiles, importGraph, parseArgs, projectRoot } from "./lib/common.mjs";
5
+
6
+ const { flags } = parseArgs();
7
+ const root = projectRoot();
8
+ const graph = importGraph(root);
9
+ const changed = flags.all ? undefined : new Set(changedFiles(root, baseRef(root, flags.base)));
10
+
11
+ // Tarjan's strongly connected components: every module in one with more than one member sits on a cycle.
12
+ let index = 0;
13
+ const stack = [];
14
+ const on = new Set();
15
+ const idx = new Map();
16
+ const low = new Map();
17
+ const groups = [];
18
+ function connect(node) {
19
+ // Iterative, so a deep import chain cannot overflow the stack.
20
+ const work = [[node, 0]];
21
+ idx.set(node, index); low.set(node, index); index += 1; stack.push(node); on.add(node);
22
+ while (work.length) {
23
+ const frame = work[work.length - 1];
24
+ const [at, i] = frame;
25
+ const next = graph.get(at) ?? [];
26
+ if (i < next.length) {
27
+ frame[1] += 1;
28
+ const to = next[i];
29
+ if (!idx.has(to)) {
30
+ idx.set(to, index); low.set(to, index); index += 1; stack.push(to); on.add(to);
31
+ work.push([to, 0]);
32
+ } else if (on.has(to)) low.set(at, Math.min(low.get(at), idx.get(to)));
33
+ continue;
34
+ }
35
+ work.pop();
36
+ if (work.length) low.set(work[work.length - 1][0], Math.min(low.get(work[work.length - 1][0]), low.get(at)));
37
+ if (low.get(at) === idx.get(at)) {
38
+ const group = [];
39
+ let top;
40
+ do { top = stack.pop(); on.delete(top); group.push(top); } while (top !== at);
41
+ if (group.length > 1 || (graph.get(at) ?? []).includes(at)) groups.push(group);
42
+ }
43
+ }
44
+ }
45
+ for (const node of graph.keys()) if (!idx.has(node)) connect(node);
46
+
47
+ /** One shortest loop through `start` inside its group, to show how the cycle closes. */
48
+ function loop(start, members) {
49
+ const inside = new Set(members);
50
+ const prev = new Map([[start, undefined]]);
51
+ const queue = [start];
52
+ while (queue.length) {
53
+ const at = queue.shift();
54
+ for (const to of graph.get(at) ?? []) {
55
+ if (!inside.has(to)) continue;
56
+ if (to === start) {
57
+ const path = [at];
58
+ while (prev.get(path[0]) !== undefined) path.unshift(prev.get(path[0]));
59
+ return [...path, start];
60
+ }
61
+ if (!prev.has(to)) { prev.set(to, at); queue.push(to); }
62
+ }
63
+ }
64
+ return [start];
65
+ }
66
+
67
+ const shown = groups.filter((group) => !changed || group.some((file) => changed.has(file)));
68
+ if (shown.length === 0) {
69
+ console.log(`No circular imports${changed ? " through changed files" : ""} (${graph.size} modules checked).`);
70
+ process.exit(0);
71
+ }
72
+ console.log(`# ${shown.length} import cycle(s)${changed ? " through changed files" : ""}${changed && groups.length > shown.length ? `; ${groups.length - shown.length} more elsewhere (--all)` : ""}`);
73
+ for (const group of shown.sort((a, b) => a.length - b.length)) {
74
+ const start = group.find((file) => changed?.has(file)) ?? group.sort()[0];
75
+ console.log(`## ${group.length} module(s)`);
76
+ console.log(` ${loop(start, group).join("\n → ")}`);
77
+ if (group.length > 8) console.log(` (the cycle group also holds ${group.length - loop(start, group).length + 1} more)`);
78
+ }
79
+ process.exit(1);
@@ -0,0 +1,86 @@
1
+ #!/usr/bin/env node
2
+ // purpose: find code in the changed files that already exists elsewhere in the project (same lines up to whitespace, comments and names of strings), so an existing function is reused instead of copied; --all checks the whole project
3
+ // usage: node {script} [--base <ref>] [--min <lines>] [--all] [--tests]
4
+ import { readFileSync } from "node:fs";
5
+ import { join } from "node:path";
6
+ import { baseRef, changedFiles, isCode, isGenerated, isTest, parseArgs, projectRoot, tracked } from "./lib/common.mjs";
7
+
8
+ const { flags } = parseArgs();
9
+ const root = projectRoot();
10
+ const min = Math.max(3, Number(flags.min ?? 6));
11
+ const withTests = Boolean(flags.tests);
12
+ const corpus = tracked(root).filter((file) => isCode(file) && (withTests || !isTest(file)) && !isGenerated(root, file));
13
+ const targets = flags.all ? corpus : changedFiles(root, baseRef(root, flags.base)).filter((file) => corpus.includes(file));
14
+ if (targets.length === 0) {
15
+ console.log(flags.all ? "No source files to check." : "No changed source files to check (tests are skipped unless --tests).");
16
+ process.exit(0);
17
+ }
18
+
19
+ /** Lines that carry meaning, normalised; with their real line numbers. */
20
+ function normalise(file) {
21
+ let text;
22
+ try { text = readFileSync(join(root, file), "utf8"); } catch { return []; }
23
+ const out = [];
24
+ let block = false;
25
+ text.split("\n").forEach((raw, index) => {
26
+ let row = raw.trim();
27
+ if (block) { if (row.includes("*/")) { block = false; row = row.slice(row.indexOf("*/") + 2).trim(); } else return; }
28
+ if (row.startsWith("/*")) { if (!row.includes("*/")) { block = true; return; } row = row.slice(row.indexOf("*/") + 2).trim(); }
29
+ row = row.replace(/(^|\s)(\/\/|#(?!\[)).*$/, "").trim();
30
+ // Imports, bare brackets and tiny lines match everywhere and prove nothing.
31
+ if (row.length < 4 || /^(import|from\s+\S+\s+import|export\s*\{|export\s+\*|use\s|require\(|package\s|[)}\]\s;,]+$)/.test(row)) return;
32
+ const key = row.replace(/(["'`])(?:\\.|(?!\1).)*\1/g, "S").replace(/\b\d+(\.\d+)?\b/g, "N").replace(/\s+/g, " ");
33
+ // Lists of strings and numbers (data tables, prompts) are not logic to reuse.
34
+ if (!/[A-Za-z_$]/.test(key.replace(/\b[SN]\b/g, ""))) return;
35
+ out.push({ line: index + 1, key });
36
+ });
37
+ return out;
38
+ }
39
+
40
+ // Every window of `min` meaningful lines, by its content.
41
+ const rows = new Map();
42
+ const index = new Map();
43
+ for (const file of corpus) {
44
+ const list = normalise(file);
45
+ rows.set(file, list);
46
+ for (let i = 0; i + min <= list.length; i++) {
47
+ const key = list.slice(i, i + min).map((row) => row.key).join("\n");
48
+ const at = index.get(key);
49
+ if (at) { if (at.length < 20) at.push([file, i]); } else index.set(key, [[file, i]]);
50
+ }
51
+ }
52
+
53
+ const found = [];
54
+ const seen = new Set();
55
+ for (const file of targets) {
56
+ const list = rows.get(file) ?? [];
57
+ let i = 0;
58
+ while (i + min <= list.length) {
59
+ const key = list.slice(i, i + min).map((row) => row.key).join("\n");
60
+ const others = (index.get(key) ?? []).filter(([other, j]) => other !== file || Math.abs(j - i) >= min);
61
+ if (others.length === 0) { i += 1; continue; }
62
+ // Grow the match while the next line still matches the first copy.
63
+ const [other, j] = others[0];
64
+ const theirs = rows.get(other);
65
+ let length = min;
66
+ while (i + length < list.length && j + length < theirs.length && list[i + length].key === theirs[j + length].key && !(other === file && j + length === i)) length += 1;
67
+ const id = [file, list[i].line, other, theirs[j].line].join(":");
68
+ const back = [other, theirs[j].line, file, list[i].line].join(":");
69
+ if (!seen.has(back)) {
70
+ seen.add(id);
71
+ found.push({ file, from: list[i].line, to: list[i + length - 1].line, other, at: theirs[j].line, end: theirs[j + length - 1].line, length, copies: others.length });
72
+ }
73
+ i += length;
74
+ }
75
+ }
76
+ if (found.length === 0) {
77
+ console.log(`No repeated block of ${min}+ lines in ${flags.all ? "the project" : `the ${targets.length} changed file(s)`}.`);
78
+ process.exit(0);
79
+ }
80
+ found.sort((a, b) => b.length - a.length);
81
+ console.log(`# ${found.length} repeated block(s) of ${min}+ meaningful lines${flags.all ? "" : " in changed files"}; reuse or extract the existing code where the copies mean the same thing`);
82
+ for (const hit of found.slice(0, 25)) {
83
+ console.log(`${hit.file}:${hit.from}-${hit.to} ≈ ${hit.other}:${hit.at}-${hit.end} (${hit.length} lines${hit.copies > 1 ? `, ${hit.copies} copies` : ""})`);
84
+ }
85
+ if (found.length > 25) console.log(`… ${found.length - 25} more; raise --min to see only the larger ones`);
86
+ process.exit(1);
@@ -0,0 +1,62 @@
1
+ #!/usr/bin/env node
2
+ // purpose: summarise the branch before reading its diff: per file the changed functions, classes and interfaces, lines added and removed, the tests that cover it, and changed functions no test mentions; lockfiles, build output and generated files are set aside
3
+ // usage: node {script} [--base <ref>] [--all]
4
+ import { readFileSync } from "node:fs";
5
+ import { join } from "node:path";
6
+ import { baseRef, changedFiles, changedRanges, declarations, isCode, isGenerated, isTest, lines, parseArgs, projectRoot, sh, testsFor, tracked } from "./lib/common.mjs";
7
+
8
+ const { flags } = parseArgs();
9
+ const root = projectRoot();
10
+ const base = baseRef(root, flags.base);
11
+ const all = changedFiles(root, base);
12
+ if (all.length === 0) {
13
+ console.log("Nothing changed.");
14
+ process.exit(0);
15
+ }
16
+ const noise = flags.all ? [] : all.filter((file) => isGenerated(root, file));
17
+ const files = all.filter((file) => !noise.includes(file));
18
+ const stats = new Map();
19
+ const numstat = (args) => {
20
+ for (const row of lines(sh("git", ["diff", "--numstat", ...args], { cwd: root }).out)) {
21
+ const [added, removed, file] = row.split("\t");
22
+ const now = stats.get(file) ?? [0, 0];
23
+ stats.set(file, [now[0] + (Number(added) || 0), now[1] + (Number(removed) || 0)]);
24
+ }
25
+ };
26
+ if (base !== "HEAD") numstat([`${base}...HEAD`]);
27
+ numstat(["HEAD"]);
28
+ const untracked = new Set(lines(sh("git", ["ls-files", "--others", "--exclude-standard"], { cwd: root }).out));
29
+ const ranges = changedRanges(root, base);
30
+ const everything = tracked(root);
31
+ const covered = testsFor(root, files, everything);
32
+ const testText = everything.filter(isTest).map((file) => { try { return readFileSync(join(root, file), "utf8"); } catch { return ""; } }).join("\n");
33
+
34
+ let plus = 0;
35
+ let minus = 0;
36
+ const untested = [];
37
+ console.log(`## Compared with ${base === "HEAD" ? "the last commit" : base.slice(0, 12)}: ${files.length} file(s)${noise.length ? `, ${noise.length} generated or lock file(s) set aside` : ""}`);
38
+ for (const file of files) {
39
+ const text = (() => { try { return readFileSync(join(root, file), "utf8"); } catch { return ""; } })();
40
+ const [added, removed] = stats.get(file) ?? [untracked.has(file) ? text.split("\n").length : 0, 0];
41
+ plus += added;
42
+ minus += removed;
43
+ const tests = covered.get(file) ?? [];
44
+ const note = isTest(file) ? "test" : tests.length > 0 ? `tests: ${tests.slice(0, 3).join(", ")}${tests.length > 3 ? ` +${tests.length - 3}` : ""}` : isCode(file) ? "no test found" : "";
45
+ console.log(`${untracked.has(file) ? "new " : " "}+${added} -${removed} ${file}${note ? ` (${note})` : ""}`);
46
+ if (!isCode(file) || !text) continue;
47
+ const decls = declarations(text, file);
48
+ const hunks = untracked.has(file) ? [[1, text.split("\n").length]] : ranges.get(file) ?? [];
49
+ const touched = decls.filter((decl) => hunks.some(([from, to]) => from <= decl.end && to >= decl.start));
50
+ // Name the innermost declarations a hunk touched, not every class around them.
51
+ const inner = touched.filter((decl) => !touched.some((other) => other !== decl && other.start >= decl.start && other.end <= decl.end && other.start !== decl.start));
52
+ if (inner.length === 0) continue;
53
+ const names = inner.slice(0, 12).map((decl) => {
54
+ const bare = !isTest(file) && !new RegExp(`\\b${decl.name.replace(/\$/g, "\\$")}\\b`).test(testText);
55
+ if (bare) untested.push(`${file}: ${decl.name}`);
56
+ return `${decl.name}${bare ? "*" : ""}`;
57
+ });
58
+ console.log(` changed: ${names.join(", ")}${inner.length > 12 ? `, +${inner.length - 12}` : ""}`);
59
+ }
60
+ console.log(`## Total +${plus} -${minus}`);
61
+ if (untested.length > 0) console.log(`## * Changed and named in no test (${untested.length}): check whether each needs one`);
62
+ if (noise.length > 0) console.log(`## Set aside: ${noise.slice(0, 10).join(", ")}${noise.length > 10 ? ", …" : ""} (--all to include)`);