co-maintainer 0.6.13 → 0.7.0-beta.1

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 (156) hide show
  1. package/README.md +1 -1
  2. package/dist/package.json +1 -1
  3. package/dist/src/ai/anthropic.js +2 -0
  4. package/dist/src/ai/batch.d.ts +3 -1
  5. package/dist/src/ai/batch.js +23 -2
  6. package/dist/src/ai/mermaid_loop.js +1 -1
  7. package/dist/src/ai/oauth/sign-in-with-chatgpt.js +8 -10
  8. package/dist/src/ai/openai.js +2 -0
  9. package/dist/src/ai/openrouter.js +2 -0
  10. package/dist/src/cli/args.js +47 -0
  11. package/dist/src/cli/command_json.d.ts +20 -1
  12. package/dist/src/cli/command_json.js +4 -0
  13. package/dist/src/cli/commands/config.d.ts +1 -1
  14. package/dist/src/cli/commands/config.js +1 -0
  15. package/dist/src/cli/commands/registry.js +226 -1
  16. package/dist/src/cli/commands/review.js +50 -9
  17. package/dist/src/cli/commands/serve.js +5 -0
  18. package/dist/src/cli/commands/set.js +70 -2
  19. package/dist/src/cli/commands/view.js +46 -5
  20. package/dist/src/cli/commands/view_sources.d.ts +11 -0
  21. package/dist/src/cli/commands/view_sources.js +40 -0
  22. package/dist/src/cli/main.js +5 -0
  23. package/dist/src/cli/pr_carry.d.ts +25 -0
  24. package/dist/src/cli/pr_carry.js +128 -0
  25. package/dist/src/cli/prompt.js +26 -1
  26. package/dist/src/cli/review_args.d.ts +8 -0
  27. package/dist/src/cli/review_args.js +18 -0
  28. package/dist/src/cli/review_carry.d.ts +32 -0
  29. package/dist/src/cli/review_carry.js +60 -0
  30. package/dist/src/cli/review_github.d.ts +16 -2
  31. package/dist/src/cli/review_github.js +49 -12
  32. package/dist/src/cli/review_intent.d.ts +25 -0
  33. package/dist/src/cli/review_intent.js +87 -0
  34. package/dist/src/cli/review_result.d.ts +53 -2
  35. package/dist/src/cli/review_result.js +90 -23
  36. package/dist/src/config.d.ts +27 -0
  37. package/dist/src/config.js +20 -12
  38. package/dist/src/extensions/command.d.ts +1 -0
  39. package/dist/src/extensions/command.js +355 -0
  40. package/dist/src/extensions/contexts.d.ts +65 -0
  41. package/dist/src/extensions/contexts.js +134 -0
  42. package/dist/src/extensions/cost.d.ts +8 -0
  43. package/dist/src/extensions/cost.js +6 -0
  44. package/dist/src/extensions/local_tracking.d.ts +7 -0
  45. package/dist/src/extensions/local_tracking.js +29 -0
  46. package/dist/src/extensions/mock.d.ts +29 -0
  47. package/dist/src/extensions/mock.js +67 -0
  48. package/dist/src/extensions/process.d.ts +43 -0
  49. package/dist/src/extensions/process.js +244 -0
  50. package/dist/src/extensions/registry.d.ts +79 -0
  51. package/dist/src/extensions/registry.js +240 -0
  52. package/dist/src/extensions/render_actions.d.ts +6 -0
  53. package/dist/src/extensions/render_actions.js +50 -0
  54. package/dist/src/extensions/render_cli.d.ts +18 -0
  55. package/dist/src/extensions/render_cli.js +88 -0
  56. package/dist/src/extensions/render_json.d.ts +51 -0
  57. package/dist/src/extensions/render_json.js +144 -0
  58. package/dist/src/extensions/render_markdown.d.ts +22 -0
  59. package/dist/src/extensions/render_markdown.js +96 -0
  60. package/dist/src/extensions/render_review.d.ts +44 -0
  61. package/dist/src/extensions/render_review.js +167 -0
  62. package/dist/src/extensions/report.d.ts +57 -0
  63. package/dist/src/extensions/report.js +97 -0
  64. package/dist/src/extensions/review_result.d.ts +2 -0
  65. package/dist/src/extensions/review_result.js +14 -0
  66. package/dist/src/extensions/run_folder.d.ts +74 -0
  67. package/dist/src/extensions/run_folder.js +172 -0
  68. package/dist/src/extensions/runner.d.ts +66 -0
  69. package/dist/src/extensions/runner.js +251 -0
  70. package/dist/src/extensions/schema.d.ts +103 -0
  71. package/dist/src/extensions/schema.js +539 -0
  72. package/dist/src/extensions/session.d.ts +56 -0
  73. package/dist/src/extensions/session.js +173 -0
  74. package/dist/src/github/collect.d.ts +7 -2
  75. package/dist/src/github/collect.js +66 -6
  76. package/dist/src/github/gh.d.ts +7 -0
  77. package/dist/src/github/gh.js +24 -29
  78. package/dist/src/knowledge/guide.js +3 -2
  79. package/dist/src/knowledge/instruction_files.d.ts +45 -0
  80. package/dist/src/knowledge/instruction_files.js +91 -0
  81. package/dist/src/knowledge/instructions.d.ts +78 -0
  82. package/dist/src/knowledge/instructions.js +280 -0
  83. package/dist/src/knowledge/rule_changes.d.ts +39 -0
  84. package/dist/src/knowledge/rule_changes.js +90 -0
  85. package/dist/src/knowledge/rules.d.ts +44 -0
  86. package/dist/src/knowledge/rules.js +82 -0
  87. package/dist/src/knowledge/synthesis.d.ts +1 -0
  88. package/dist/src/knowledge/synthesis.js +12 -5
  89. package/dist/src/knowledge/types.d.ts +4 -0
  90. package/dist/src/local/carry_over_store.d.ts +10 -0
  91. package/dist/src/local/carry_over_store.js +17 -0
  92. package/dist/src/local/review_local.js +100 -62
  93. package/dist/src/local/review_lock.js +15 -4
  94. package/dist/src/pr/diff_plan.d.ts +110 -0
  95. package/dist/src/pr/diff_plan.js +429 -0
  96. package/dist/src/pr/diff_summary.d.ts +17 -1
  97. package/dist/src/pr/diff_summary.js +87 -13
  98. package/dist/src/pr/review_diff.d.ts +47 -0
  99. package/dist/src/pr/review_diff.js +112 -0
  100. package/dist/src/pr/reviewer.d.ts +44 -19
  101. package/dist/src/pr/reviewer.js +114 -142
  102. package/dist/src/remote/client.js +67 -8
  103. package/dist/src/remote/http.d.ts +12 -0
  104. package/dist/src/remote/http.js +31 -0
  105. package/dist/src/remote/push_client.js +14 -3
  106. package/dist/src/remote/server/guides.js +12 -1
  107. package/dist/src/remote/server/routes.js +4 -2
  108. package/dist/src/remote/server/sessions.js +4 -1
  109. package/dist/src/remote/validate.js +11 -0
  110. package/dist/src/review/carry_over.d.ts +6 -1
  111. package/dist/src/review/carry_over.js +10 -2
  112. package/dist/src/review/coverage.d.ts +57 -0
  113. package/dist/src/review/coverage.js +186 -0
  114. package/dist/src/review/diagram.d.ts +73 -0
  115. package/dist/src/review/diagram.js +309 -0
  116. package/dist/src/review/engine.d.ts +2 -6
  117. package/dist/src/review/engine.js +1 -1
  118. package/dist/src/review/guides.d.ts +6 -0
  119. package/dist/src/review/guides.js +8 -1
  120. package/dist/src/review/intent.d.ts +24 -0
  121. package/dist/src/review/intent.js +28 -0
  122. package/dist/src/review/not_initialized.d.ts +13 -0
  123. package/dist/src/review/not_initialized.js +18 -0
  124. package/dist/src/review/system_prompt.d.ts +6 -0
  125. package/dist/src/review/system_prompt.js +13 -0
  126. package/dist/src/review/visible_paths.d.ts +22 -0
  127. package/dist/src/review/visible_paths.js +41 -0
  128. package/dist/src/server/pages/extensions.d.ts +5 -0
  129. package/dist/src/server/pages/extensions.js +72 -0
  130. package/dist/src/server/pages/pr.js +3 -2
  131. package/dist/src/services/dashboard.d.ts +8 -0
  132. package/dist/src/services/dashboard.js +8 -0
  133. package/dist/src/services/push_review.js +14 -5
  134. package/dist/src/services/remote_review.js +81 -26
  135. package/dist/src/services/replies.js +15 -8
  136. package/dist/src/services/review.d.ts +9 -3
  137. package/dist/src/services/review.js +109 -28
  138. package/dist/src/services/rules_build.d.ts +46 -0
  139. package/dist/src/services/rules_build.js +155 -0
  140. package/dist/src/services/setup.d.ts +31 -0
  141. package/dist/src/services/setup.js +120 -25
  142. package/dist/src/services/watch_comments.js +2 -0
  143. package/dist/src/store/cache_db.js +3 -0
  144. package/dist/src/store/extensions.d.ts +51 -0
  145. package/dist/src/store/extensions.js +132 -0
  146. package/dist/src/store/migrations.js +40 -0
  147. package/dist/src/types.d.ts +22 -1
  148. package/dist/src/util/atomic.d.ts +15 -1
  149. package/dist/src/util/atomic.js +59 -29
  150. package/dist/src/util/interrupt.d.ts +6 -0
  151. package/dist/src/util/interrupt.js +27 -0
  152. package/dist/src/util/runtime.d.ts +3 -1
  153. package/dist/src/util/runtime.js +2 -2
  154. package/dist/src/util/test_location_guard.d.ts +6 -0
  155. package/dist/src/util/test_location_guard.js +47 -0
  156. package/package.json +1 -1
@@ -0,0 +1,173 @@
1
+ /** The one call each review mode makes: run the AI review with its
2
+ * extensions around it.
3
+ *
4
+ * The review starts at once and never waits for an extension. The extensions
5
+ * that may run alongside it start too. When the review returns, its results
6
+ * are written for the extensions that wait on it, and the call returns only
7
+ * after every extension has finished, so a review is posted with all of them.
8
+ * A review that throws cancels the extensions, and the run folder is removed
9
+ * however the review ends.
10
+ *
11
+ * With `CM_EXTENSIONS_DISABLED=1`, or no registration for this repository and
12
+ * review type, the review runs alone and nothing is written to disk. */
13
+ import { readConfig } from "../config.js";
14
+ import { applicableRegistrations, extensionsDisabled, readRegistrations, rerunsOnRestart, } from "./registry.js";
15
+ import { openRunFolder, removeDeadCliRunFolders, isRunId, removeRunFolder, writeReviewResult, } from "./run_folder.js";
16
+ import { failedResult, runExtensions } from "./runner.js";
17
+ import { buildReport, EMPTY_REPORT, nextPrevious, } from "./report.js";
18
+ const C_ESCAPES = {
19
+ 7: "\\a",
20
+ 8: "\\b",
21
+ 9: "\\t",
22
+ 10: "\\n",
23
+ 11: "\\v",
24
+ 12: "\\f",
25
+ 13: "\\r",
26
+ 34: '\\"',
27
+ 92: "\\\\",
28
+ };
29
+ /** A path in a diff header, quoted the way git quotes it. A file name may
30
+ * hold a newline, and unquoted it could forge a `+++` header in the patch an
31
+ * extension reads. */
32
+ export function quotePath(path) {
33
+ const bytes = Buffer.from(path, "utf8");
34
+ if (!bytes.some((byte) => byte < 32 || byte >= 127 || byte === 34 || byte === 92)) {
35
+ return path;
36
+ }
37
+ let out = "";
38
+ for (const byte of bytes) {
39
+ if (C_ESCAPES[byte])
40
+ out += C_ESCAPES[byte];
41
+ else if (byte < 32 || byte >= 127)
42
+ out += `\\${byte.toString(8).padStart(3, "0")}`;
43
+ else
44
+ out += String.fromCharCode(byte);
45
+ }
46
+ return `"${out}"`;
47
+ }
48
+ /** A unified diff from the per-file patches every review type already has. */
49
+ export function unifiedDiff(files) {
50
+ return files
51
+ .map((file) => {
52
+ const before = file.previousPath ?? file.path;
53
+ const oldName = file.status === "added" ? "/dev/null" : quotePath(`a/${before}`);
54
+ const newName = file.status === "removed" ? "/dev/null" : quotePath(`b/${file.path}`);
55
+ const body = file.patch.endsWith("\n") ? file.patch : `${file.patch}\n`;
56
+ return `diff --git ${quotePath(`a/${before}`)} ${quotePath(`b/${file.path}`)}\n--- ${oldName}\n+++ ${newName}\n${file.patch ? body : ""}`;
57
+ })
58
+ .join("");
59
+ }
60
+ export async function withExtensions(context, review, reviewResult) {
61
+ if (extensionsDisabled()) {
62
+ return { review: await review(), extensions: EMPTY_REPORT };
63
+ }
64
+ const config = readConfig();
65
+ const registrations = applicableRegistrations(readRegistrations(config), context.repo, context.reviewType);
66
+ if (registrations.length === 0) {
67
+ return { review: await review(), extensions: EMPTY_REPORT };
68
+ }
69
+ if (context.owner === "cli")
70
+ await removeDeadCliRunFolders().catch(() => 0);
71
+ const tracked = (await context.tracking?.load().catch(() => undefined)) ?? {
72
+ previous: [],
73
+ };
74
+ let folder;
75
+ try {
76
+ // The diff first: building it may fill in the context's shas.
77
+ const diff = await context.diff();
78
+ const details = {
79
+ schemaVersion: 1,
80
+ reviewType: context.reviewType,
81
+ repo: context.repo,
82
+ prNumber: context.prNumber,
83
+ branch: context.branch,
84
+ workdir: context.workdir,
85
+ headSha: context.headSha,
86
+ baseSha: context.baseSha,
87
+ scope: context.scope,
88
+ sinceCommit: context.sinceCommit,
89
+ trigger: context.trigger,
90
+ round: tracked.round ?? context.round,
91
+ };
92
+ folder = await openRunFolder({
93
+ // A job id that is not a UUID cannot name a run folder. Such a run only
94
+ // loses its restart record.
95
+ runId: isRunId(context.runId) ? context.runId : crypto.randomUUID(),
96
+ owner: context.owner,
97
+ details,
98
+ diff,
99
+ });
100
+ }
101
+ catch (error) {
102
+ // An extension failure never blocks a review, and neither does failing
103
+ // to prepare for one: the review runs alone and says why.
104
+ const reason = `co-maintainer could not prepare the run: ${error instanceof Error ? error.message : String(error)}`;
105
+ context.log?.(`extensions: ${reason}`);
106
+ const result = await review();
107
+ return {
108
+ review: result,
109
+ extensions: buildReport(registrations.map((entry) => failedResult(entry.name, reason))),
110
+ };
111
+ }
112
+ const controller = new AbortController();
113
+ const onAbort = () => controller.abort();
114
+ if (context.signal?.aborted)
115
+ controller.abort();
116
+ context.signal?.addEventListener("abort", onAbort, { once: true });
117
+ let reviewSettled;
118
+ const reviewDone = new Promise((resolve) => {
119
+ reviewSettled = resolve;
120
+ });
121
+ context.log?.(`extensions: ${registrations.map((entry) => entry.name).join(", ")}`);
122
+ const running = runExtensions({
123
+ registrations,
124
+ folder,
125
+ // A local review runs in its checkout. Everywhere else the run folder is
126
+ // the working directory, not wherever `serve` was started.
127
+ cwd: context.workdir || folder.dir,
128
+ reviewDone,
129
+ signal: controller.signal,
130
+ rerunOnRestart: (entry) => rerunsOnRestart(entry, config),
131
+ log: context.log,
132
+ });
133
+ try {
134
+ let result;
135
+ try {
136
+ result = await review();
137
+ }
138
+ catch (error) {
139
+ controller.abort();
140
+ reviewSettled(false);
141
+ await running;
142
+ throw error;
143
+ }
144
+ try {
145
+ await writeReviewResult(folder, await reviewResult(result));
146
+ reviewSettled(true);
147
+ }
148
+ catch (error) {
149
+ // The extensions that wait for the results cannot run. The review
150
+ // itself is done and is not lost for it.
151
+ context.log?.(`extensions: could not write the review results: ${String(error)}`);
152
+ reviewSettled(false);
153
+ }
154
+ const results = await running;
155
+ for (const entry of results) {
156
+ context.log?.(`extension ${entry.name}: ${entry.status}${entry.reason ? ` (${entry.reason})` : ""}`);
157
+ }
158
+ const extensions = buildReport(results, tracked.previous);
159
+ try {
160
+ await context.tracking?.save(extensions, nextPrevious(extensions, tracked.previous));
161
+ }
162
+ catch (error) {
163
+ // Losing the tracking state costs the next round its open and closed
164
+ // states. It does not cost this review.
165
+ context.log?.(`could not save the extension findings for the next round: ${String(error)}`);
166
+ }
167
+ return { review: result, extensions };
168
+ }
169
+ finally {
170
+ context.signal?.removeEventListener("abort", onAbort);
171
+ await removeRunFolder(folder);
172
+ }
173
+ }
@@ -1,7 +1,12 @@
1
1
  import type { GitHubClient, Options } from "../types.ts";
2
2
  import type { Source, State } from "../knowledge/types.ts";
3
- export declare function collectSource(client: GitHubClient, options: Options, previous?: State, codebaseProgress?: (data: {
3
+ /** What the codebase fetch saves while it runs. `instructionFiles` is always
4
+ * named, even when missing: the blob SHAs it is checked against are saved in
5
+ * the same write, so a checkpoint never pairs new SHAs with old contents. */
6
+ export type CodebaseCheckpoint = {
4
7
  tree: string[];
5
8
  treeSha: Record<string, string>;
6
9
  files: Record<string, string>;
7
- }) => Promise<void>): Promise<Source>;
10
+ instructionFiles: Record<string, string> | undefined;
11
+ };
12
+ export declare function collectSource(client: GitHubClient, options: Options, previous?: State, codebaseProgress?: (data: CodebaseCheckpoint) => Promise<void>): Promise<Source>;
@@ -1,5 +1,6 @@
1
1
  import { log, startHeartbeat } from "../util/log.js";
2
2
  import { cacheGet, cacheSet, cacheValues } from "../store/cache_db.js";
3
+ import { agentInstructionsPattern, capInstructionFiles, leftOutLine, matchInstructionPaths, MAX_INSTRUCTION_FILES, } from "../knowledge/instruction_files.js";
3
4
  function decodeBase64(value) {
4
5
  const binary = atob(value.replaceAll("\n", ""));
5
6
  const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
@@ -188,7 +189,7 @@ async function file(client, repo, path, branch) {
188
189
  return undefined;
189
190
  }
190
191
  }
191
- async function codebase(client, repo, meta, concurrency, previous, phase, progress) {
192
+ async function codebase(client, repo, meta, concurrency, previous, phase, progress, instructionPattern = null) {
192
193
  const branch = String(meta.default_branch ?? "main");
193
194
  const response = await client.request(`repos/${repo}/git/trees/${encodeURIComponent(branch)}?recursive=1`);
194
195
  const blobs = Array.isArray(response.tree)
@@ -199,9 +200,22 @@ async function codebase(client, repo, meta, concurrency, previous, phase, progre
199
200
  const value = item;
200
201
  return [String(value.path), String(value.sha ?? "")];
201
202
  }));
202
- const canonical = tree.filter((path) => /(^|\/)(README|CONTRIBUTING|CODE_OF_CONDUCT|SECURITY|CHANGELOG)(\.[^/]*)?$|(^|\/)(package\.json|deno\.json|Cargo\.toml|Makefile|justfile|CODEOWNERS|build\.rs)$|^\.github\/(workflows\/.+\.(yml|yaml)|PULL_REQUEST_TEMPLATE.*)$/i.test(path));
203
+ // Instruction files are read first and in full, and only the ones actually
204
+ // read leave the codebase extraction input. A file a cap left out stays
205
+ // there, so a broad pattern never hides a file from both steps.
206
+ const instructionPaths = instructionPattern
207
+ ? matchInstructionPaths(tree, instructionPattern)
208
+ : [];
209
+ let instructionFiles;
210
+ if (instructionPaths.length > 0) {
211
+ instructionFiles = await readInstructionFiles(client, repo, branch, instructionPaths, treeSha, concurrency, previous);
212
+ }
213
+ const isInstruction = new Set(Object.keys(instructionFiles ?? {}));
214
+ const canonical = tree.filter((path) => !isInstruction.has(path) &&
215
+ /(^|\/)(README|CONTRIBUTING|CODE_OF_CONDUCT|SECURITY|CHANGELOG)(\.[^/]*)?$|(^|\/)(package\.json|deno\.json|Cargo\.toml|Makefile|justfile|CODEOWNERS|build\.rs)$|^\.github\/(workflows\/.+\.(yml|yaml)|PULL_REQUEST_TEMPLATE.*)$/i.test(path));
203
216
  const representative = tree
204
- .filter((path) => /\.(rs|ts|tsx|js|jsx|py|go|java|cs|cpp|c|swift)$/i.test(path) &&
217
+ .filter((path) => !isInstruction.has(path) &&
218
+ /\.(rs|ts|tsx|js|jsx|py|go|java|cs|cpp|c|swift)$/i.test(path) &&
205
219
  !/(^|\/)(test|tests|vendor|dist|target)\//i.test(path))
206
220
  .slice(0, 20);
207
221
  const important = [...new Set([...canonical, ...representative])].slice(0, 80);
@@ -212,12 +226,21 @@ async function codebase(client, repo, meta, concurrency, previous, phase, progre
212
226
  phase.text = `codebase files 0/${important.length} · 0% · concurrency=${concurrency}`;
213
227
  }
214
228
  log("fetch", `codebase · ${important.length} files · concurrency=${concurrency}`);
229
+ // Every checkpoint saves the instruction files read above with the blob
230
+ // SHAs they were checked against, never old text under new SHAs.
215
231
  const checkpoint = () => {
216
232
  if (!progress)
217
233
  return Promise.resolve();
218
- save = save.then(() => progress({ tree, treeSha, files: { ...files } }));
234
+ save = save.then(() => progress({
235
+ tree,
236
+ treeSha,
237
+ files: { ...files },
238
+ instructionFiles: instructionFiles && { ...instructionFiles },
239
+ }));
219
240
  return save;
220
241
  };
242
+ if (instructionFiles)
243
+ await checkpoint();
221
244
  await mapPool(important, concurrency, async (path) => {
222
245
  if (previous?.treeSha?.[path] &&
223
246
  previous.treeSha[path] === treeSha[path] &&
@@ -242,7 +265,36 @@ async function codebase(client, repo, meta, concurrency, previous, phase, progre
242
265
  log("fetch", `codebase file ${completed}/${important.length} · ${percent(completed, important.length)}: ${path}`);
243
266
  await checkpoint();
244
267
  });
245
- return { tree, treeSha, files };
268
+ // Nothing matched: no log line and no new state field, so a repository
269
+ // without instruction files is fetched exactly as before.
270
+ return instructionFiles
271
+ ? { tree, treeSha, files, instructionFiles }
272
+ : { tree, treeSha, files };
273
+ }
274
+ /** Reads the matched instruction files in full, reusing a cached copy whose
275
+ * blob SHA has not moved, and applies the count and size caps. Every file left
276
+ * out is named in the build output. */
277
+ async function readInstructionFiles(client, repo, branch, paths, treeSha, concurrency, previous) {
278
+ const wanted = paths.slice(0, MAX_INSTRUCTION_FILES);
279
+ const overCount = paths.slice(MAX_INSTRUCTION_FILES).map((path) => ({
280
+ path,
281
+ reason: `over the ${MAX_INSTRUCTION_FILES}-file cap`,
282
+ }));
283
+ log("fetch", `instruction files · ${wanted.length} matched`);
284
+ const contents = await mapPool(wanted, concurrency, async (path) => {
285
+ const cached = previous?.instructionFiles?.[path];
286
+ if (cached !== undefined &&
287
+ previous?.treeSha?.[path] &&
288
+ previous.treeSha[path] === treeSha[path]) {
289
+ return { path, content: cached };
290
+ }
291
+ return { path, content: await file(client, repo, path, branch) };
292
+ });
293
+ const selection = capInstructionFiles(contents);
294
+ const leftOut = [...selection.leftOut, ...overCount];
295
+ if (leftOut.length > 0)
296
+ log("fetch", leftOutLine(leftOut));
297
+ return selection.files;
246
298
  }
247
299
  /** One pull request's cached evidence, keyed by number. `cacheValues` returns
248
300
  * the newest rows first, so a later row for the same number wins. Legacy
@@ -536,8 +588,13 @@ export async function collectSource(client, options, previous, codebaseProgress)
536
588
  try {
537
589
  const repo = await client.request(`repos/${options.repo}`);
538
590
  const includeCodebase = options.includeCodebase || options.includeHowRepoWorks;
591
+ // Instruction files belong to `--include-codebase` alone: with it off
592
+ // there is no `INSTRUCTIONS.md`.
593
+ const instructionPattern = options.includeCodebase
594
+ ? agentInstructionsPattern(options.agentInstructions)
595
+ : null;
539
596
  const files = includeCodebase
540
- ? await codebase(client, options.repo, repo, options.ghConcurrent, previous?.source, phase, codebaseProgress)
597
+ ? await codebase(client, options.repo, repo, options.ghConcurrent, previous?.source, phase, codebaseProgress, instructionPattern)
541
598
  : { tree: [], treeSha: {}, files: {} };
542
599
  const selectedPullRequests = options.includePullRequests
543
600
  ? await pullRequests(client, options, previous, phase)
@@ -550,6 +607,9 @@ export async function collectSource(client, options, previous, codebaseProgress)
550
607
  tree: files.tree,
551
608
  treeSha: files.treeSha,
552
609
  files: files.files,
610
+ ...(files.instructionFiles
611
+ ? { instructionFiles: files.instructionFiles }
612
+ : {}),
553
613
  pullRequests: selectedPullRequests,
554
614
  commits: commitData,
555
615
  };
@@ -1,4 +1,11 @@
1
1
  import type { GitHubClient } from "../types.ts";
2
+ import { type CommandOutput } from "../util/runtime.ts";
3
+ /** Answers a `gh` call in this process. `input` is the body sent on stdin. */
4
+ export type GhRunner = (args: string[], input?: string) => Promise<CommandOutput>;
5
+ /** Test seam: `e2e:simulate` answers `gh` in its own process, because a
6
+ * child process cannot reach the GitHub it simulates in memory. Unset means
7
+ * the `gh` process, so production behaviour is unchanged. */
8
+ export declare function setGhRunner(runner: GhRunner | undefined): void;
2
9
  type QuotaRow = {
3
10
  limit?: number;
4
11
  remaining?: number;
@@ -16,6 +16,26 @@ function ghSpawn() {
16
16
  const script = getEnv("CM_GH_SCRIPT");
17
17
  return { command: bin, prefix: script ? [script] : [] };
18
18
  }
19
+ let ghRunner;
20
+ /** Test seam: `e2e:simulate` answers `gh` in its own process, because a
21
+ * child process cannot reach the GitHub it simulates in memory. Unset means
22
+ * the `gh` process, so production behaviour is unchanged. */
23
+ export function setGhRunner(runner) {
24
+ ghRunner = runner;
25
+ }
26
+ function runGh(args, input) {
27
+ if (ghRunner)
28
+ return ghRunner(args, input);
29
+ const { command, prefix } = ghSpawn();
30
+ const options = {
31
+ args: [...prefix, ...args],
32
+ stdout: "piped",
33
+ stderr: "piped",
34
+ };
35
+ return input === undefined
36
+ ? commandOutput(command, options)
37
+ : commandWithInput(command, { ...options, stdin: "piped" }, input);
38
+ }
19
39
  /** Turns a failed `gh api` call into a message that says what broke, why, and
20
40
  * what to do next. The four shapes that came up in practice:
21
41
  * `gh` missing from PATH, the repo missing or unreadable, an empty stderr, and
@@ -63,12 +83,7 @@ export function quotaLine(body) {
63
83
  }
64
84
  async function printQuota() {
65
85
  try {
66
- const { command, prefix } = ghSpawn();
67
- const result = await commandOutput(command, {
68
- args: [...prefix, "api", "rate_limit"],
69
- stdout: "piped",
70
- stderr: "piped",
71
- });
86
+ const result = await runGh(["api", "rate_limit"]);
72
87
  if (!result.success)
73
88
  return;
74
89
  log("debug", quotaLine(JSON.parse(new TextDecoder().decode(result.stdout))));
@@ -103,12 +118,7 @@ function noteGhCall(debug) {
103
118
  }
104
119
  async function readLimit(endpoint) {
105
120
  try {
106
- const { command, prefix } = ghSpawn();
107
- const result = await commandOutput(command, {
108
- args: [...prefix, "api", "rate_limit"],
109
- stdout: "piped",
110
- stderr: "piped",
111
- });
121
+ const result = await runGh(["api", "rate_limit"]);
112
122
  if (!result.success)
113
123
  return undefined;
114
124
  const body = JSON.parse(new TextDecoder().decode(result.stdout));
@@ -132,14 +142,7 @@ export class GhClient {
132
142
  this.debug = debug;
133
143
  }
134
144
  request(endpoint) {
135
- return this.call("GET", endpoint, () => {
136
- const { command, prefix } = ghSpawn();
137
- return commandOutput(command, {
138
- args: [...prefix, "api", endpoint],
139
- stdout: "piped",
140
- stderr: "piped",
141
- });
142
- });
145
+ return this.call("GET", endpoint, () => runGh(["api", endpoint]));
143
146
  }
144
147
  write(endpoint, body) {
145
148
  return this.send(endpoint, "POST", body);
@@ -154,15 +157,7 @@ export class GhClient {
154
157
  return paginate((e) => this.request(e), endpoint, limit, progress);
155
158
  }
156
159
  send(endpoint, method, body) {
157
- return this.call(method, endpoint, () => {
158
- const { command, prefix } = ghSpawn();
159
- return commandWithInput(command, {
160
- args: [...prefix, "api", "-X", method, endpoint, "--input", "-"],
161
- stdin: "piped",
162
- stdout: "piped",
163
- stderr: "piped",
164
- }, JSON.stringify(body));
165
- });
160
+ return this.call(method, endpoint, () => runGh(["api", "-X", method, endpoint, "--input", "-"], JSON.stringify(body)));
166
161
  }
167
162
  async call(method, endpoint, run) {
168
163
  noteGhCall(this.debug);
@@ -229,7 +229,8 @@ export async function synthesizeReviewGuides(provider, repo, ai, model, concurre
229
229
  }
230
230
  /** Strips a wrapping code fence and the tokens a guide must never carry (a
231
231
  * priority tag, a mention, a pull-request number), so an otherwise good guide is
232
- * cleaned rather than rejected. */
232
+ * cleaned rather than rejected. Runs of spaces are squeezed only after text: a
233
+ * line's leading indent nests an example under its rule, as the prompt asks. */
233
234
  function cleanGuide(text) {
234
235
  return text
235
236
  .replace(/^```[a-zA-Z0-9_-]*\s*/, "")
@@ -237,6 +238,6 @@ function cleanGuide(text) {
237
238
  .replace(/\[\s*P[0-3]\s*\]/gi, "")
238
239
  .replace(/@[A-Za-z0-9_-]{2,}/g, "")
239
240
  .replace(/\bPR\s*#?\s*\d+\b/gi, "the change")
240
- .replace(/[ \t]{2,}/g, " ")
241
+ .replace(/(\S)[ \t]{2,}/g, "$1 ")
241
242
  .trim();
242
243
  }
@@ -0,0 +1,45 @@
1
+ /** Which files on the default branch are agent instruction files, and how
2
+ * many of them a build reads.
3
+ *
4
+ * `--agent-instructions` is a JavaScript regex matched against each full path.
5
+ * The matches are read in full, outside the codebase file cap, but a
6
+ * repository with hundreds of them must not turn one synthesis call into a
7
+ * book, so there is a cap on the count and on the total size. */
8
+ /** The default `--agent-instructions`: every `AGENTS.md`, at any depth. */
9
+ export declare const DEFAULT_AGENT_INSTRUCTIONS = "(^|/)AGENTS\\.md$";
10
+ /** The default `--agent-instructions-max-chars`. */
11
+ export declare const DEFAULT_AGENT_INSTRUCTIONS_MAX_CHARS = 6000;
12
+ /** At most this many instruction files are read. */
13
+ export declare const MAX_INSTRUCTION_FILES = 50;
14
+ /** At most this many characters of instruction files are read in total. */
15
+ export declare const MAX_INSTRUCTION_CHARS = 400000;
16
+ /** The parse error for a pattern, or `null` when it compiles. */
17
+ export declare function agentInstructionsError(source: string): string | null;
18
+ /** The regex a build uses, or `null` when the feature is off. Unset takes the
19
+ * default and a blank value turns the feature off. */
20
+ export declare function agentInstructionsPattern(source: string | undefined): RegExp | null;
21
+ /** The cap on `INSTRUCTIONS.md`, or `null` for no limit. */
22
+ export declare function agentInstructionsLimit(raw: number | undefined): number | null;
23
+ /** The matching paths in reading order: root files first, then deeper ones,
24
+ * alphabetical within a depth. A root file is usually the one that applies to
25
+ * the whole repository, so it is the last to be left out by the caps. */
26
+ export declare function matchInstructionPaths(tree: string[], pattern: RegExp): string[];
27
+ export type InstructionSelection = {
28
+ files: Record<string, string>;
29
+ /** Each path that was not read, with the reason. */
30
+ leftOut: {
31
+ path: string;
32
+ reason: string;
33
+ }[];
34
+ };
35
+ /** Applies the total size cap to files already read in reading order. A file
36
+ * that would cross the cap is left out and later, smaller ones still fit. */
37
+ export declare function capInstructionFiles(ordered: {
38
+ path: string;
39
+ content: string | undefined;
40
+ }[], maxChars?: number): InstructionSelection;
41
+ /** One log line naming every file a build did not read. */
42
+ export declare function leftOutLine(leftOut: {
43
+ path: string;
44
+ reason: string;
45
+ }[]): string;
@@ -0,0 +1,91 @@
1
+ /** Which files on the default branch are agent instruction files, and how
2
+ * many of them a build reads.
3
+ *
4
+ * `--agent-instructions` is a JavaScript regex matched against each full path.
5
+ * The matches are read in full, outside the codebase file cap, but a
6
+ * repository with hundreds of them must not turn one synthesis call into a
7
+ * book, so there is a cap on the count and on the total size. */
8
+ import { CliError, EXIT_USAGE } from "../cli/error.js";
9
+ /** The default `--agent-instructions`: every `AGENTS.md`, at any depth. */
10
+ export const DEFAULT_AGENT_INSTRUCTIONS = "(^|/)AGENTS\\.md$";
11
+ /** The default `--agent-instructions-max-chars`. */
12
+ export const DEFAULT_AGENT_INSTRUCTIONS_MAX_CHARS = 6000;
13
+ /** At most this many instruction files are read. */
14
+ export const MAX_INSTRUCTION_FILES = 50;
15
+ /** At most this many characters of instruction files are read in total. */
16
+ export const MAX_INSTRUCTION_CHARS = 400_000;
17
+ /** The parse error for a pattern, or `null` when it compiles. */
18
+ export function agentInstructionsError(source) {
19
+ try {
20
+ new RegExp(source);
21
+ return null;
22
+ }
23
+ catch (error) {
24
+ return error instanceof Error ? error.message : String(error);
25
+ }
26
+ }
27
+ /** The regex a build uses, or `null` when the feature is off. Unset takes the
28
+ * default and a blank value turns the feature off. */
29
+ export function agentInstructionsPattern(source) {
30
+ const value = source ?? DEFAULT_AGENT_INSTRUCTIONS;
31
+ if (value.trim() === "")
32
+ return null;
33
+ const error = agentInstructionsError(value);
34
+ // A flag value is checked when it is parsed, so this is a saved value that
35
+ // was edited by hand. Name it, and exit as a usage error.
36
+ if (error) {
37
+ throw new CliError("usage", `The saved agentInstructions pattern is not a valid regular expression: ${error}`, "Pass --agent-instructions=REGEX to sync to replace it.", EXIT_USAGE);
38
+ }
39
+ return new RegExp(value);
40
+ }
41
+ /** The cap on `INSTRUCTIONS.md`, or `null` for no limit. */
42
+ export function agentInstructionsLimit(raw) {
43
+ if (raw === undefined)
44
+ return DEFAULT_AGENT_INSTRUCTIONS_MAX_CHARS;
45
+ if (!Number.isFinite(raw) || raw <= 0)
46
+ return null;
47
+ return Math.floor(raw);
48
+ }
49
+ function depth(path) {
50
+ return path.split("/").length;
51
+ }
52
+ /** The matching paths in reading order: root files first, then deeper ones,
53
+ * alphabetical within a depth. A root file is usually the one that applies to
54
+ * the whole repository, so it is the last to be left out by the caps. */
55
+ export function matchInstructionPaths(tree, pattern) {
56
+ return tree
57
+ .filter((path) => pattern.test(path))
58
+ .sort((a, b) => depth(a) - depth(b) || a.localeCompare(b));
59
+ }
60
+ /** Applies the total size cap to files already read in reading order. A file
61
+ * that would cross the cap is left out and later, smaller ones still fit. */
62
+ export function capInstructionFiles(ordered, maxChars = MAX_INSTRUCTION_CHARS) {
63
+ const files = {};
64
+ const leftOut = [];
65
+ let total = 0;
66
+ for (const { path, content } of ordered) {
67
+ if (content === undefined) {
68
+ leftOut.push({ path, reason: "could not be read" });
69
+ continue;
70
+ }
71
+ if (total + content.length > maxChars) {
72
+ leftOut.push({
73
+ path,
74
+ reason: `over the ${maxChars.toLocaleString("en-US")}-character cap`,
75
+ });
76
+ continue;
77
+ }
78
+ files[path] = content;
79
+ total += content.length;
80
+ }
81
+ return { files, leftOut };
82
+ }
83
+ /** One log line naming every file a build did not read. */
84
+ export function leftOutLine(leftOut) {
85
+ // A pattern that matches the whole tree would otherwise print every path.
86
+ const shown = leftOut.slice(0, 20);
87
+ const more = leftOut.length - shown.length;
88
+ return `instruction files left out: ${shown
89
+ .map(({ path, reason }) => `${path} (${reason})`)
90
+ .join(", ")}${more > 0 ? `, and ${more} more` : ""}`;
91
+ }
@@ -0,0 +1,78 @@
1
+ import type { AiProvider, AiRequest, AiResponse, Options } from "../types.ts";
2
+ import { type RuleEntry } from "./rules.ts";
3
+ type UsageSink = (job: string, response: AiResponse) => Promise<void>;
4
+ export type InstructionRule = {
5
+ id: string;
6
+ text: string;
7
+ /** The folder the rule applies to, ending in `/`, or empty for the whole
8
+ * repository. */
9
+ scope: string;
10
+ sources: {
11
+ path: string;
12
+ line: number;
13
+ }[];
14
+ };
15
+ export type InstructionCounts = {
16
+ /** A source that is not a real, non-blank line of a file that was read. */
17
+ unsupportedSource: number;
18
+ /** A name or path in backticks that appears in none of the files. */
19
+ unknownName: number;
20
+ /** Rules after the one that would have crossed the cap. */
21
+ overCap: number;
22
+ };
23
+ export type InstructionsResult = {
24
+ status: "written";
25
+ markdown: string;
26
+ rules: InstructionRule[];
27
+ counts: InstructionCounts;
28
+ }
29
+ /** The answer parsed but no rule survived: there is no file. */
30
+ | {
31
+ status: "empty";
32
+ counts: InstructionCounts;
33
+ }
34
+ /** The call failed or never returned usable JSON: the previous file is
35
+ * kept. */
36
+ | {
37
+ status: "failed";
38
+ };
39
+ type Candidate = {
40
+ rule: string;
41
+ scope: string;
42
+ sources: string[];
43
+ };
44
+ export declare function instructionsRequest(files: Record<string, string>): AiRequest;
45
+ /** The model's rules, or `null` when the answer is not the JSON object asked
46
+ * for. An empty `rules` array is a valid answer. */
47
+ export declare function parseInstructionRules(text: string): Candidate[] | null;
48
+ type Checked = {
49
+ text: string;
50
+ scope: string;
51
+ sources: {
52
+ path: string;
53
+ line: number;
54
+ }[];
55
+ };
56
+ /** Every rule the files support, duplicates merged, in the model's order. A
57
+ * rule with one bad source or one unknown name is dropped whole: a rule that
58
+ * cites a line that is not there was not read from the files. */
59
+ export declare function checkInstructionRules(candidates: Candidate[], files: Record<string, string>, tree: string[]): {
60
+ rules: Checked[];
61
+ counts: Omit<InstructionCounts, "overCap">;
62
+ };
63
+ /** The file, with rules kept in order until the next one would cross the
64
+ * cap. `limit` of `null` means no cap. */
65
+ export declare function renderInstructions(rules: Checked[], limit: number | null): {
66
+ markdown: string;
67
+ rules: InstructionRule[];
68
+ overCap: number;
69
+ };
70
+ /** Builds `INSTRUCTIONS.md` from the files `collect` read. Never throws: a
71
+ * provider failure is `failed`, and the caller keeps the previous file. */
72
+ export declare function synthesizeInstructions(provider: AiProvider, repo: string, ai: Options["ai"], model: string, files: Record<string, string>, tree: string[], limit: number | null, usage?: UsageSink): Promise<InstructionsResult>;
73
+ /** The build output line for a written file. */
74
+ export declare function instructionsWriteLine(rules: number, counts: InstructionCounts): string;
75
+ /** The `RULES.json` entries for a written file. The text drops the backticks
76
+ * the Markdown uses. */
77
+ export declare function instructionRuleEntries(rules: InstructionRule[], commit: string | undefined): Record<string, RuleEntry>;
78
+ export {};