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
@@ -8,8 +8,9 @@ import { GhClient } from "../github/gh.js";
8
8
  import { PatClient } from "../github/pat.js";
9
9
  import { extractFacts } from "../knowledge/facts.js";
10
10
  import { reviewSignalCount, synthesizeReviewGuides, } from "../knowledge/guide.js";
11
- import { assembleSkill, codebaseBody, factSectionHashes, } from "../knowledge/skill.js";
11
+ import { assembleSkill, codebaseBody, extractSections, factSectionHashes, } from "../knowledge/skill.js";
12
12
  import { validateSkill } from "../knowledge/validate.js";
13
+ import { codebaseSectionKeys } from "../knowledge/sections.js";
13
14
  import { readConfig, reposDir, resolvedAiToken, writeRepoConfig, } from "../config.js";
14
15
  import { readState, writeState } from "../store/skill_state.js";
15
16
  import { cacheSet } from "../store/cache_db.js";
@@ -20,12 +21,13 @@ import { resolveConcurrency } from "./concurrency.js";
20
21
  import { closeAppDb, isAppDbOpen, openAppDb } from "../store/app_db.js";
21
22
  import { getRepo, markKnowledgeBuilt, registerCliRepo, } from "../store/repos.js";
22
23
  import { nowIso } from "../util/time.js";
23
- import { mkdir, readTextFile, remove } from "../util/runtime.js";
24
+ import { mkdir, readTextFile, remove, stat } from "../util/runtime.js";
24
25
  import { applyWatchNotes, withMaintainerNotes } from "./watch_notes.js";
25
26
  import { addResponseCost, emptyTally } from "../util/cost.js";
26
27
  import { costLabel } from "../util/run_summary.js";
27
28
  import { formatError } from "../cli/error.js";
28
29
  import { buildSetupJson } from "../cli/command_json.js";
30
+ import { buildInstructions, instructionsJson, writeInstructionsAndRules, } from "./rules_build.js";
29
31
  export function emptyAiMetrics() {
30
32
  return { calls: 0, tokensIn: 0, tokensOut: 0, ...emptyTally() };
31
33
  }
@@ -130,14 +132,62 @@ async function writeMaintainerNotes(repo, lines) {
130
132
  const { writeTextFileAtomic } = await import("../util/atomic.js");
131
133
  await writeTextFileAtomic(path, withMaintainerNotes(current, lines));
132
134
  }
135
+ /** The sections this run rebuilds. With no previous state, or after the high
136
+ * model or the synthesis version changed, that is every section: `undefined`
137
+ * on a first run, all keys after a change. Otherwise the sections whose facts
138
+ * changed, and every codebase section that has facts but is missing from the
139
+ * CODEBASE.md on disk. That last rule rebuilds a section an earlier run lost,
140
+ * for example one 0.6.13 dropped on a sync, instead of keeping it missing
141
+ * until its facts change. */
142
+ export function dirtySectionKeys(previous, options, hashes, previousCodebase) {
143
+ if (!previous)
144
+ return undefined;
145
+ const synthesisChanged = previous.options.highModel !== options.highModel ||
146
+ previous.options.synthesisVersion !== options.synthesisVersion;
147
+ if (synthesisChanged)
148
+ return new Set(Object.keys(hashes));
149
+ const onDisk = previousCodebase ? extractSections(previousCodebase) : {};
150
+ return new Set(Object.entries(hashes)
151
+ .filter(([key, hash]) => previous.sectionHashes[key] !== hash ||
152
+ (codebaseSectionKeys.has(key) && !onDisk[key]))
153
+ .map(([key]) => key));
154
+ }
155
+ /** The sections that still have facts and that this run did not rebuild, so
156
+ * their previous text is still right. */
157
+ export function unchangedSectionKeys(hashes, dirty) {
158
+ if (!dirty)
159
+ return new Set();
160
+ return new Set(Object.keys(hashes).filter((key) => !dirty.has(key)));
161
+ }
162
+ /** The CODEBASE.md body. A sync rebuilds only the sections whose facts
163
+ * changed, so a section in `keep` keeps the text the last run wrote, the way
164
+ * `assembleSkill` keeps an unchanged skill section. `keep` holds the
165
+ * unchanged sections and those whose synthesis call failed: a failed call is
166
+ * not an answer. A rebuilt section takes its new text, and one that came back
167
+ * empty is dropped: the old text was written from facts that are gone. */
168
+ export function mergeCodebaseSections(previousMarkdown, overrides, keep) {
169
+ const previous = previousMarkdown ? extractSections(previousMarkdown) : {};
170
+ const kept = Object.fromEntries(Object.entries(previous).filter(([key]) => keep.has(key)));
171
+ return codebaseBody({ ...kept, ...overrides });
172
+ }
173
+ async function readCodebaseDocument(repo) {
174
+ try {
175
+ return await readTextFile(`${reposDir()}/${repo}/CODEBASE.md`);
176
+ }
177
+ catch {
178
+ // No CODEBASE.md yet.
179
+ return undefined;
180
+ }
181
+ }
133
182
  /** Writes the codebase-description sections (layout/style/tests/devloop) to
134
183
  * their own file, so `review` can check a pull request against how this
135
184
  * repository's code actually looks, not just the review-bar checklist. Every
136
185
  * section body is authored by the synthesis job; the skill links to this file
137
186
  * rather than repeating it. */
138
- async function writeCodebaseDocument(repo, overrides = {}) {
187
+ async function writeCodebaseDocument(repo, overrides = {}, keep = new Set()) {
139
188
  const path = `${reposDir()}/${repo}/CODEBASE.md`;
140
- const body = codebaseBody(overrides);
189
+ const previous = await readCodebaseDocument(repo);
190
+ const body = mergeCodebaseSections(previous, overrides, keep);
141
191
  if (!body) {
142
192
  // Keep any existing file: `SKILL.md` links to it, and removing it would
143
193
  // leave that link dangling. A guide the last run wrote is better than a
@@ -148,10 +198,35 @@ async function writeCodebaseDocument(repo, overrides = {}) {
148
198
  const { writeTextFileAtomic } = await import("../util/atomic.js");
149
199
  await writeTextFileAtomic(path, `# Codebase conventions for ${repo}\n\nHow this repository's code is actually structured and written. A pull request that departs from these observed conventions is worth flagging even without a matching review-bar rule.\n\n${body}\n`);
150
200
  }
151
- function addReviewLink(markdown, documents) {
152
- if (!documents)
201
+ /** The review guides on disk once this run has written its files. When the AI
202
+ * produced no guide above the signal threshold, `writeReviewDocuments` keeps
203
+ * the last run's files, and every review still reads them. Below the
204
+ * threshold it removes them. */
205
+ export async function reviewGuideStatus(repo, documents, signalCount) {
206
+ if (documents) {
207
+ return documents.detailed
208
+ ? { reviewGuide: "detailed", detailed: true }
209
+ : { reviewGuide: "single", detailed: false };
210
+ }
211
+ const skipped = {
212
+ reviewGuide: "skipped",
213
+ detailed: false,
214
+ };
215
+ if (signalCount <= 2)
216
+ return skipped;
217
+ const directory = `${reposDir()}/${repo}`;
218
+ const exists = (name) => stat(`${directory}/${name}`).then(() => true, () => false);
219
+ if (!(await exists("PR_REVIEW_GUIDE.md")))
220
+ return skipped;
221
+ return {
222
+ reviewGuide: "kept",
223
+ detailed: await exists("PR_REVIEW_DETAILED_GUIDE.md"),
224
+ };
225
+ }
226
+ export function addReviewLink(markdown, guide) {
227
+ if (guide.reviewGuide === "skipped")
153
228
  return markdown;
154
- const detailedLink = documents.detailed
229
+ const detailedLink = guide.detailed
155
230
  ? " See [PR_REVIEW_DETAILED_GUIDE.md](PR_REVIEW_DETAILED_GUIDE.md) for evidence."
156
231
  : "";
157
232
  return `${markdown.trimEnd()}\n\n## Pull request review guides\n\n- Read [PR_REVIEW_GUIDE.md](PR_REVIEW_GUIDE.md).${detailedLink}\n`;
@@ -197,11 +272,14 @@ async function initOrRemake(options) {
197
272
  log("ai", `${aiProviderName(options)} providers configured · low=${options.lowModel} · high=${options.highModel}`);
198
273
  log("fetch", `${options.repo} via ${options.auth}`);
199
274
  const source = await timed("fetch repository data", options.logTime, () => collectSource(client, options, previous, async (codebase) => {
275
+ // `instructionFiles` is set even when missing: it is checked against
276
+ // the blob SHAs saved here, so the old contents must not survive them.
200
277
  checkpoint.source = {
201
278
  ...checkpoint.source,
202
279
  tree: codebase.tree,
203
280
  treeSha: codebase.treeSha,
204
281
  files: codebase.files,
282
+ instructionFiles: codebase.instructionFiles,
205
283
  };
206
284
  await writeState(checkpoint);
207
285
  }));
@@ -225,30 +303,32 @@ async function initOrRemake(options) {
225
303
  };
226
304
  let overrides = {};
227
305
  let reviewDocuments;
306
+ let unchangedSections = new Set();
307
+ let instructions = { status: "failed" };
308
+ let rulesResult;
228
309
  try {
229
310
  log("ai", "starting extract_unit jobs");
230
311
  facts = await timed("extract_unit AI", options.logTime, () => enrichFacts(lowAi, options.repo, facts, source, options, usage));
231
312
  log("ai", `extract_unit complete · ${facts.length} facts`);
232
313
  const hashes = await factSectionHashes(facts);
233
- const synthesisChanged = previous &&
234
- (previous.options.highModel !== options.highModel ||
235
- previous.options.synthesisVersion !== options.synthesisVersion);
236
- const dirtySections = previous
237
- ? synthesisChanged
238
- ? new Set(Object.keys(hashes))
239
- : new Set(Object.entries(hashes)
240
- .filter(([key, hash]) => previous.sectionHashes[key] !== hash)
241
- .map(([key]) => key))
242
- : undefined;
314
+ const dirtySections = dirtySectionKeys(previous, options, hashes, await readCodebaseDocument(options.repo));
315
+ unchangedSections = unchangedSectionKeys(hashes, dirtySections);
243
316
  log("ai", `starting synth_section jobs${dirtySections ? ` · ${dirtySections.size} dirty sections` : ""}`);
244
317
  const synth = await timed("synth_section AI", options.logTime, () => synthesizeSections(highAi, options.repo, facts, previousMarkdown, options.ai, options.highModel ?? "", options.aiConcurrent, usage, dirtySections));
245
318
  overrides = synth.overrides;
319
+ // A section whose call failed keeps its CODEBASE.md text, as SKILL.md
320
+ // keeps a dropped unit's text.
321
+ for (const key of synth.failed)
322
+ unchangedSections.add(key);
246
323
  log("ai", `synth_section complete · ${Object.keys(overrides).length} sections`);
247
324
  log("ai", "starting synth_guide jobs");
248
325
  reviewDocuments = await timed("synth_guide AI", options.logTime, () => synthesizeReviewGuides(highAi, options.repo, options.ai, options.highModel ?? "", options.aiConcurrent, facts, usage));
249
326
  log("ai", reviewDocuments
250
327
  ? `synth_guide complete · ${reviewDocuments.detailed ? "short + detailed" : "single guide"}`
251
- : "synth_guide skipped · fewer than 3 review signals");
328
+ : reviewSignalCount(facts) > 2
329
+ ? "synth_guide produced no guide"
330
+ : "synth_guide skipped · fewer than 3 review signals");
331
+ instructions = await buildInstructions(highAi, options, source, usage);
252
332
  }
253
333
  catch (error) {
254
334
  // Nothing is written on an AI failure. Fetching and extraction are cached,
@@ -257,7 +337,8 @@ async function initOrRemake(options) {
257
337
  "Fetching and extraction are cached, so rerunning `co-maintainer sync <owner/repo>` continues without re-fetching.");
258
338
  }
259
339
  let result = await timed("assemble skill", options.logTime, () => assembleSkill(options.repo, facts, previousMarkdown, previous?.sectionHashes ?? {}, overrides));
260
- result.markdown = addReviewLink(result.markdown, reviewDocuments);
340
+ const guideStatus = await reviewGuideStatus(options.repo, reviewDocuments, reviewSignalCount(facts));
341
+ result.markdown = addReviewLink(result.markdown, guideStatus);
261
342
  // What maintainers said on commit watch issues since the last sync.
262
343
  const noteLines = await applyWatchNotes(options.repo, lowAi, (response) => usage("watch_note", response));
263
344
  const validation = await timed("validate skill", options.logTime, () => validateSkill(result.markdown, source));
@@ -278,11 +359,17 @@ async function initOrRemake(options) {
278
359
  const { writeTextFileAtomic } = await import("../util/atomic.js");
279
360
  await withKnowledgeLock(options.repo, async () => {
280
361
  await writeTextFileAtomic(path, result.markdown);
281
- await writeCodebaseDocument(options.repo, overrides);
362
+ await writeCodebaseDocument(options.repo, overrides, unchangedSections);
282
363
  await writeReviewDocuments(options.repo, reviewDocuments, reviewSignalCount(facts));
283
364
  if (noteLines.length > 0) {
284
365
  await writeMaintainerNotes(options.repo, noteLines);
285
366
  }
367
+ rulesResult = await writeInstructionsAndRules({
368
+ repo: options.repo,
369
+ command: options.command,
370
+ instructions,
371
+ source,
372
+ });
286
373
  const head = source.commits[0];
287
374
  const baseSha = head?.sha ? String(head.sha) : new Date().toISOString();
288
375
  // A CLI init has no app.db row for the repository yet; without one the
@@ -322,6 +409,8 @@ async function initOrRemake(options) {
322
409
  includeHowRepoWorks: options.includeHowRepoWorks,
323
410
  onlyRequestChangedPr: options.onlyRequestChangedPr,
324
411
  prState: options.prState,
412
+ agentInstructions: options.agentInstructions,
413
+ agentInstructionsMaxChars: options.agentInstructionsMaxChars,
325
414
  });
326
415
  });
327
416
  log("write", `${path} · ${result.changed.length
@@ -339,15 +428,19 @@ async function initOrRemake(options) {
339
428
  facts: facts.length,
340
429
  pullRequests: source.pullRequests.length,
341
430
  commits: source.commits.length,
342
- reviewGuide: reviewDocuments
343
- ? reviewDocuments.detailed
344
- ? "detailed"
345
- : "single"
346
- : "skipped",
431
+ reviewGuide: guideStatus.reviewGuide,
347
432
  validation: {
348
433
  errors: finalValidation.errors,
349
434
  warnings: finalValidation.warnings,
350
435
  },
436
+ // Only when the instructions did something, so `sync --json` for a
437
+ // repository without instruction files prints what it printed before.
438
+ ...(rulesResult?.reported
439
+ ? {
440
+ instructions: instructionsJson(instructions),
441
+ ruleChanges: rulesResult.changes,
442
+ }
443
+ : {}),
351
444
  summary,
352
445
  }));
353
446
  }
@@ -405,6 +498,8 @@ export function optionsFromConfig(repo, command) {
405
498
  maxPullRequestChangeLines: repoConfig.maxPullRequestChangeLines ??
406
499
  config.defaults?.maxPullRequestChangeLines,
407
500
  maxComments: repoConfig.maxComments,
501
+ agentInstructions: repoConfig.agentInstructions,
502
+ agentInstructionsMaxChars: repoConfig.agentInstructionsMaxChars,
408
503
  };
409
504
  }
410
505
  /** `runner` defaults to the real `runInitOrRemake`; tests substitute a fake
@@ -11,6 +11,7 @@
11
11
  import { createAiProvider } from "../ai/provider.js";
12
12
  import { FakeAiProvider } from "../ai/fake.js";
13
13
  import { completeWithMermaidTools } from "../ai/mermaid_loop.js";
14
+ import { mermaidToolFields } from "../review/diagram.js";
14
15
  import { loadGuides } from "../review/guides.js";
15
16
  import { getEnv } from "../util/runtime.js";
16
17
  import { hasWriteAccess } from "../github/write_access.js";
@@ -142,6 +143,7 @@ async function runWatchComment(job, log) {
142
143
  job: "watch_comment_answer",
143
144
  reasoningEffort: "high",
144
145
  maxTokens: 6000,
146
+ ...mermaidToolFields(options),
145
147
  system: `You are co-maintainer, the code reviewer that opened this issue. Answer the maintainer's question about the problem in plain prose. Write the answer in the same language as the question. Do not use semicolons.
146
148
 
147
149
  REVIEW GUIDE:
@@ -120,6 +120,9 @@ export async function cacheDeleteRepoEvidence(repo) {
120
120
  removed += deleteRows(db, namespace, { prefix: `${repo}:` });
121
121
  }
122
122
  removed += deleteRows(db, "local-review", { prefix: `${repo}\0` });
123
+ removed += deleteRows(db, "local-extension-findings", {
124
+ prefix: `${repo}\0`,
125
+ });
123
126
  return removed;
124
127
  }
125
128
  finally {
@@ -0,0 +1,51 @@
1
+ import type { ExtensionReport, PreviousExtensionFinding } from "../extensions/report.ts";
2
+ export type ExtensionResultRow = {
3
+ id: string;
4
+ review_id: string;
5
+ name: string;
6
+ status: string;
7
+ verdict: string | null;
8
+ reason: string | null;
9
+ markdown: string;
10
+ data_json: string;
11
+ extra_json: string | null;
12
+ usage_json: string | null;
13
+ cost: number | null;
14
+ details: string | null;
15
+ duration_ms: number | null;
16
+ attempts: number;
17
+ created_at: string;
18
+ };
19
+ export type ExtensionFindingRow = {
20
+ id: string;
21
+ review_id: string;
22
+ extension: string;
23
+ key: string | null;
24
+ state: string;
25
+ severity: string;
26
+ blocking: number;
27
+ title: string;
28
+ body: string;
29
+ path: string | null;
30
+ line_from: number | null;
31
+ line_to: number | null;
32
+ created_at: string;
33
+ };
34
+ /** Stores one review's extensions. A rerun of the same review replaces what an
35
+ * earlier attempt stored. */
36
+ export declare function saveExtensionReport(reviewId: string, report: ExtensionReport): void;
37
+ export declare function listExtensionResults(reviewId: string): ExtensionResultRow[];
38
+ export declare function listExtensionFindings(reviewId: string): ExtensionFindingRow[];
39
+ /** The keyed findings still standing from the last review of `subjectId` in
40
+ * which each extension returned `ok`, other than `excludeReviewId`. Only a
41
+ * review that reached the pull request or the client counts: after a failed
42
+ * post, the next round treats its findings as new and comments on them. */
43
+ export declare function previousExtensionFindings(subjectId: string, excludeReviewId: string): PreviousExtensionFinding[];
44
+ /** One review's extensions, as every output reads them. */
45
+ export declare function loadExtensionReport(reviewId: string): ExtensionReport;
46
+ /** The extensions' share of a review's cost, for "review cost is total minus
47
+ * extensions". */
48
+ export declare function extensionCostForReview(reviewId: string): number;
49
+ /** How many reviews of `subjectId` came before `reviewId`, for the round
50
+ * number of a review type that keeps none of its own. */
51
+ export declare function earlierReviewCount(subjectId: string, reviewId: string): number;
@@ -0,0 +1,132 @@
1
+ /** Extension results and findings for the reviews `serve` runs: App reviews
2
+ * and remote reviews. The dashboard reads them, and the next round of the same
3
+ * subject compares its keyed findings against them. */
4
+ import { getAppDb } from "./app_db.js";
5
+ import { nowIso } from "../util/time.js";
6
+ /** Stores one review's extensions. A rerun of the same review replaces what an
7
+ * earlier attempt stored. */
8
+ export function saveExtensionReport(reviewId, report) {
9
+ const db = getAppDb();
10
+ const at = nowIso();
11
+ db.exec("BEGIN");
12
+ try {
13
+ db.prepare(`DELETE FROM extension_results WHERE review_id = ?`).run(reviewId);
14
+ db.prepare(`DELETE FROM extension_findings WHERE review_id = ?`).run(reviewId);
15
+ const result = db.prepare(`INSERT INTO extension_results
16
+ (id, review_id, name, status, verdict, reason, markdown, data_json,
17
+ extra_json, usage_json, cost, details, duration_ms, attempts, created_at)
18
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
19
+ for (const row of report.results) {
20
+ result.run(crypto.randomUUID(), reviewId, row.name, row.status, row.verdict, row.reason, row.markdown, JSON.stringify(row.data), row.extraData === null || row.extraData === undefined
21
+ ? null
22
+ : JSON.stringify(row.extraData), row.usage ? JSON.stringify(row.usage) : null, row.usage?.costUsd ?? null, row.details, row.durationMs, row.attempts, at);
23
+ }
24
+ const finding = db.prepare(`INSERT INTO extension_findings
25
+ (id, review_id, extension, key, state, severity, blocking, title, body,
26
+ path, line_from, line_to, created_at)
27
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
28
+ for (const row of report.findings) {
29
+ finding.run(row.id, reviewId, row.extensionId, row.key, row.state, row.severity, row.blocking ? 1 : 0, row.title, row.body, row.path, row.lineFrom, row.lineTo, at);
30
+ }
31
+ db.exec("COMMIT");
32
+ }
33
+ catch (error) {
34
+ db.exec("ROLLBACK");
35
+ throw error;
36
+ }
37
+ }
38
+ export function listExtensionResults(reviewId) {
39
+ return getAppDb()
40
+ .prepare(`SELECT * FROM extension_results WHERE review_id = ? ORDER BY rowid`)
41
+ .all(reviewId);
42
+ }
43
+ export function listExtensionFindings(reviewId) {
44
+ return getAppDb()
45
+ .prepare(`SELECT * FROM extension_findings WHERE review_id = ? ORDER BY rowid`)
46
+ .all(reviewId);
47
+ }
48
+ function toFinding(row) {
49
+ return {
50
+ id: row.id,
51
+ extensionId: row.extension,
52
+ key: row.key,
53
+ state: row.state,
54
+ severity: row.severity,
55
+ blocking: row.blocking === 1,
56
+ title: row.title,
57
+ body: row.body,
58
+ path: row.path,
59
+ lineFrom: row.line_from,
60
+ lineTo: row.line_to,
61
+ };
62
+ }
63
+ /** The keyed findings still standing from the last review of `subjectId` in
64
+ * which each extension returned `ok`, other than `excludeReviewId`. Only a
65
+ * review that reached the pull request or the client counts: after a failed
66
+ * post, the next round treats its findings as new and comments on them. */
67
+ export function previousExtensionFindings(subjectId, excludeReviewId) {
68
+ const db = getAppDb();
69
+ const latest = db
70
+ .prepare(`SELECT er.name AS name, er.review_id AS review_id
71
+ FROM extension_results er
72
+ JOIN reviews r ON r.id = er.review_id
73
+ WHERE r.subject_id = ? AND er.review_id != ? AND er.status = 'ok'
74
+ AND r.status IN ('posted', 'done')
75
+ ORDER BY er.created_at DESC, er.rowid DESC`)
76
+ .all(subjectId, excludeReviewId);
77
+ const chosen = new Map();
78
+ for (const row of latest) {
79
+ if (!chosen.has(row.name))
80
+ chosen.set(row.name, row.review_id);
81
+ }
82
+ const previous = [];
83
+ for (const [name, reviewId] of chosen) {
84
+ const rows = db
85
+ .prepare(`SELECT * FROM extension_findings
86
+ WHERE review_id = ? AND extension = ? AND key IS NOT NULL
87
+ AND state != 'closed'
88
+ ORDER BY rowid`)
89
+ .all(reviewId, name);
90
+ for (const row of rows) {
91
+ const { state: _state, ...rest } = toFinding(row);
92
+ previous.push(rest);
93
+ }
94
+ }
95
+ return previous;
96
+ }
97
+ /** One review's extensions, as every output reads them. */
98
+ export function loadExtensionReport(reviewId) {
99
+ return {
100
+ results: listExtensionResults(reviewId).map((row) => ({
101
+ name: row.name,
102
+ status: row.status,
103
+ verdict: row.verdict,
104
+ reason: row.reason,
105
+ markdown: row.markdown,
106
+ findings: [],
107
+ data: JSON.parse(row.data_json),
108
+ extraData: row.extra_json ? JSON.parse(row.extra_json) : null,
109
+ usage: row.usage_json ? JSON.parse(row.usage_json) : null,
110
+ details: row.details,
111
+ durationMs: row.duration_ms ?? 0,
112
+ attempts: row.attempts,
113
+ })),
114
+ findings: listExtensionFindings(reviewId).map(toFinding),
115
+ };
116
+ }
117
+ /** The extensions' share of a review's cost, for "review cost is total minus
118
+ * extensions". */
119
+ export function extensionCostForReview(reviewId) {
120
+ const row = getAppDb()
121
+ .prepare(`SELECT SUM(cost) AS total FROM extension_results WHERE review_id = ?`)
122
+ .get(reviewId);
123
+ return row?.total ?? 0;
124
+ }
125
+ /** How many reviews of `subjectId` came before `reviewId`, for the round
126
+ * number of a review type that keeps none of its own. */
127
+ export function earlierReviewCount(subjectId, reviewId) {
128
+ const row = getAppDb()
129
+ .prepare(`SELECT COUNT(*) AS count FROM reviews WHERE subject_id = ? AND id != ?`)
130
+ .get(subjectId, reviewId);
131
+ return row?.count ?? 0;
132
+ }
@@ -352,4 +352,44 @@ export const migrations = [
352
352
  UNIQUE(repo, comment_id)
353
353
  )`,
354
354
  ],
355
+ // 16 — extensions: each extension's result for a review, for the dashboard,
356
+ // and its findings, so a keyed finding is tracked across rounds. A tracked
357
+ // finding keeps its id from round to round, so the key is (review_id, id).
358
+ [
359
+ `CREATE TABLE extension_results (
360
+ id TEXT PRIMARY KEY,
361
+ review_id TEXT NOT NULL,
362
+ name TEXT NOT NULL,
363
+ status TEXT NOT NULL,
364
+ verdict TEXT,
365
+ reason TEXT,
366
+ markdown TEXT NOT NULL DEFAULT '',
367
+ data_json TEXT NOT NULL DEFAULT '{}',
368
+ extra_json TEXT,
369
+ usage_json TEXT,
370
+ cost REAL,
371
+ details TEXT,
372
+ duration_ms INTEGER,
373
+ attempts INTEGER NOT NULL DEFAULT 0,
374
+ created_at TEXT NOT NULL
375
+ )`,
376
+ `CREATE INDEX idx_extension_results_review ON extension_results(review_id)`,
377
+ `CREATE TABLE extension_findings (
378
+ id TEXT NOT NULL,
379
+ review_id TEXT NOT NULL,
380
+ extension TEXT NOT NULL,
381
+ key TEXT,
382
+ state TEXT NOT NULL,
383
+ severity TEXT NOT NULL,
384
+ blocking INTEGER NOT NULL,
385
+ title TEXT NOT NULL,
386
+ body TEXT NOT NULL,
387
+ path TEXT,
388
+ line_from INTEGER,
389
+ line_to INTEGER,
390
+ created_at TEXT NOT NULL,
391
+ PRIMARY KEY (review_id, id)
392
+ )`,
393
+ `CREATE INDEX idx_extension_findings_review ON extension_findings(review_id)`,
394
+ ],
355
395
  ];
@@ -51,6 +51,13 @@ export type Options = {
51
51
  maxPrMonths?: number;
52
52
  maxPullRequestChangeLines?: number;
53
53
  maxComments?: number;
54
+ /** `--agent-instructions`: a JavaScript regex matched against every path on
55
+ * the default branch to find the agent instruction files. Unset means the
56
+ * default, blank turns the feature off. */
57
+ agentInstructions?: string;
58
+ /** `--agent-instructions-max-chars`: the cap on `INSTRUCTIONS.md`. Unset
59
+ * means the default, 0 or below means no limit. */
60
+ agentInstructionsMaxChars?: number;
54
61
  /** `probe --run`: after printing the plan, run the recommended init in the
55
62
  * same process. */
56
63
  run?: boolean;
@@ -71,6 +78,16 @@ export type Options = {
71
78
  * (`review --system-prompt-override-file`). The built-in role, diagram
72
79
  * rules and guide block are still kept. */
73
80
  reviewSystemPromptOverride?: string;
81
+ /** What a pull request review is for (`review --intent-file`), added to the
82
+ * PULL REQUEST block of the prompt as context, never as a rule. */
83
+ reviewIntent?: string;
84
+ /** The diagram language a review asks for (`review --diagram-runtime`, or
85
+ * the repository's `diagramRuntime`). Unset means `mermaid`. */
86
+ diagramRuntime?: "mermaid" | "plantuml" | "plantuml-server";
87
+ /** Only read by `plantuml-server`. Unset means the public server. */
88
+ plantumlServer?: string;
89
+ /** Only read by `plantuml-server`. Unset means `svg`. */
90
+ plantumlOutputFormat?: "svg" | "png";
74
91
  };
75
92
  export type GitHubClient = {
76
93
  request<T>(endpoint: string): Promise<T>;
@@ -78,7 +95,8 @@ export type GitHubClient = {
78
95
  /** POST JSON. Optional so collect-test fakes stay GET-only. Review
79
96
  * posting requires it. */
80
97
  write?<T>(endpoint: string, body: unknown): Promise<T>;
81
- /** PATCH JSON, for closing an issue. Only the App client has it. */
98
+ /** PATCH JSON, for closing an issue or editing a comment. Only the App
99
+ * client has it. */
82
100
  patch?<T>(endpoint: string, body: unknown): Promise<T>;
83
101
  /** GitHub Checks API operations. Optional so read-only test clients and
84
102
  * older integrations can continue to review without check runs. */
@@ -111,6 +129,9 @@ export type AiRequest = {
111
129
  * `response_format`. Providers without structured output ignore it, so the
112
130
  * model is also asked for a fenced JSON block in the prompt. */
113
131
  responseFormat?: Json;
132
+ /** Leave the Mermaid syntax tool out of the tool list. Set when the review
133
+ * asks for PlantUML, which needs no syntax lookup. */
134
+ withoutMermaidTool?: boolean;
114
135
  reasoningEffort?: "max" | "xhigh" | "high" | "medium" | "low" | "none";
115
136
  };
116
137
  export type AiResponse = {
@@ -1,4 +1,18 @@
1
1
  /** Remove leftover `.<name>.tmp-*` files from an interrupted write.
2
2
  * Only deletes temps older than `minAgeMs` so concurrent writers are not disturbed. */
3
3
  export declare function cleanStaleTempFiles(directory: string, baseName: string, minAgeMs?: number): Promise<void>;
4
- export declare function writeTextFileAtomic(path: string, text: string): Promise<void>;
4
+ /** The file operations a write goes through. Tests pass their own to make a
5
+ * step fail, or to play Windows on another platform. */
6
+ export type AtomicIo = {
7
+ writeTextFile: (path: string, text: string, mode?: number) => Promise<void>;
8
+ rename: (from: string, to: string) => Promise<void>;
9
+ windows: boolean;
10
+ sleep: (ms: number) => Promise<void>;
11
+ };
12
+ /** Writes a temp file beside `path`, then renames it over `path`, so a reader
13
+ * in this or another process sees the old file or the new one, never half of
14
+ * one. `mode` is set on the temp file before the rename, so the real file never
15
+ * exists with a wider mode. The temp file is removed when any step fails. */
16
+ export declare function writeTextFileAtomic(path: string, text: string, options?: {
17
+ mode?: number;
18
+ }, io?: AtomicIo): Promise<void>;