co-maintainer 0.6.13 → 0.7.0-beta.2

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,10 +8,13 @@ import { parseFindings } from "../pr/findings.js";
8
8
  import { anchorFor } from "../pr/hunks.js";
9
9
  import { stripSuggestion, suggestionAnchor, withoutSuggestionLine, } from "../pr/suggestion.js";
10
10
  import { githubPullRequestToRevision } from "../pr/github_revision.js";
11
+ import { visiblePathsToSave } from "../review/visible_paths.js";
11
12
  import { anchorTextFromPatch, buildCarryPromptSection, classifyCarryItems, guideRebuiltSince, incrementalDiffPaths, parsePreviousVerdicts, resolveCarryOutcomes, } from "../review/carry_over.js";
12
13
  import { runReviewEngine } from "../review/engine.js";
14
+ import { coverageCounts, notReviewedLines, postedPathSpan, } from "../review/coverage.js";
13
15
  import { addResponseCost, costColumns, emptyTally, settle, } from "../util/cost.js";
14
16
  import { loadGuides } from "../review/guides.js";
17
+ import { serverDiagramOptions } from "../review/diagram.js";
15
18
  import { reviewBlockingFrom, isBlocking, DEFAULT_REVIEW_BLOCKING, } from "../review/blocking.js";
16
19
  import { matchRepeat } from "../pr/rounds.js";
17
20
  import { readConfig, resolveAppPrivateKey, resolvedAiToken, } from "../config.js";
@@ -24,6 +27,12 @@ import { enqueue, registerHandler } from "./jobs.js";
24
27
  import { requestedReviewBlocked } from "./webhook.js";
25
28
  import { getEnv } from "../util/runtime.js";
26
29
  import { hasWriteAccess } from "../github/write_access.js";
30
+ import { withExtensions } from "../extensions/session.js";
31
+ import { appPrContext } from "../extensions/contexts.js";
32
+ import { reviewResultJson } from "../extensions/review_result.js";
33
+ import { EMPTY_REPORT, hasExtensions, } from "../extensions/report.js";
34
+ import { reviewBodyWithExtensions, reviewEventWithExtensions, splitExtensionFindings, standingExtensionFindings, } from "../extensions/render_review.js";
35
+ import { addExtensionCost } from "../extensions/cost.js";
27
36
  const ACCESS_DENIED_BODY = "The App does not have access to review this pull request.";
28
37
  /** The first words of the single note a failed review leaves on the pull
29
38
  * request. The note names no provider error and no retry command: both live
@@ -105,8 +114,14 @@ async function resolveFailureNote(github, job, reviewId, log) {
105
114
  const noteId = existingNoteId(job);
106
115
  if (!noteId)
107
116
  return;
117
+ // An edit is a PATCH, the method the App's permission table names. GitHub
118
+ // has no POST for it, so a client without PATCH cannot edit the note.
119
+ if (!github.patch) {
120
+ log("info", "could not update the failure note: this client cannot edit");
121
+ return;
122
+ }
108
123
  try {
109
- await post(github, `repos/${job.repo}/issues/comments/${noteId}`, {
124
+ await github.patch(`repos/${job.repo}/issues/comments/${noteId}`, {
110
125
  body: REVIEWED_NOTE,
111
126
  });
112
127
  setReviewStatus(reviewId, "posted", { note_comment_id: noteId });
@@ -170,14 +185,23 @@ export function formatDuration(ms) {
170
185
  return `${minutes}m ${seconds}s`;
171
186
  return `${seconds}s`;
172
187
  }
173
- function metadataBlock({ jobId, model, durationMs }) {
188
+ function metadataBlock({ jobId, model, durationMs, coverage, }) {
174
189
  return (`\n\n<details>\n<summary>Metadata</summary>\n\n` +
175
190
  `- Activity: ${jobId}\n` +
176
191
  `- co-maintainer version: ${VERSION}\n` +
177
192
  `- Model: ${model}\n` +
178
193
  `- Duration: ${formatDuration(durationMs)}\n` +
194
+ (coverage ? `- Coverage: ${coverageCounts(coverage)}\n` : "") +
179
195
  `</details>`);
180
196
  }
197
+ /** The files this round never sent to the model, as a list under the
198
+ * findings. Paths are made safe code spans: a path is not prose, the copy
199
+ * guard must not read a semicolon in one as a sentence, and the author's file
200
+ * names must not inject Markdown or mentions. */
201
+ function notReviewedBlock(metadata) {
202
+ const lines = notReviewedLines(metadata.coverage, metadata.catchesUp ?? false, postedPathSpan);
203
+ return lines.length > 0 ? `\n\n${lines.join("\n")}` : "";
204
+ }
181
205
  function summaryLine(finding, since) {
182
206
  const title = humanCopy(finding.heading || finding.path);
183
207
  const summary = humanCopy(finding.summary ??
@@ -190,8 +214,12 @@ function summaryLine(finding, since) {
190
214
  * into what this round found and what earlier rounds found that still
191
215
  * holds, so a repeat never reads as a new problem. */
192
216
  export function reviewBody(findings, metadata, stillOpen = []) {
217
+ const notReviewed = notReviewedBlock(metadata);
193
218
  if (findings.length === 0 && stillOpen.length === 0) {
194
- return `No actionable findings.${metadataBlock(metadata)}`;
219
+ const none = notReviewed
220
+ ? "No actionable findings in the files reviewed."
221
+ : "No actionable findings.";
222
+ return `${none}${notReviewed}${metadataBlock(metadata)}`;
195
223
  }
196
224
  const lines = ["Review summary"];
197
225
  if (findings.length) {
@@ -205,7 +233,7 @@ export function reviewBody(findings, metadata, stillOpen = []) {
205
233
  lines.push(summaryLine(finding, since));
206
234
  }
207
235
  }
208
- return lines.join("\n") + metadataBlock(metadata);
236
+ return lines.join("\n") + notReviewed + metadataBlock(metadata);
209
237
  }
210
238
  function inlineCommentBody(finding, suggestion = false) {
211
239
  const heading = humanCopy(finding.heading);
@@ -296,11 +324,11 @@ async function findingReplies(client, job, rows, log) {
296
324
  }
297
325
  /** A review job's options: the config, with the job's pinned model (a
298
326
  * "Retry with the same model") over the configured one. */
299
- export function reviewOptionsForJob(repo, prNumber, args) {
300
- const options = reviewOptions(repo, prNumber);
327
+ export function reviewOptionsForJob(repo, prNumber, args, warn) {
328
+ const options = reviewOptions(repo, prNumber, warn);
301
329
  return args.model ? { ...options, highModel: args.model } : options;
302
330
  }
303
- export function reviewOptions(repo, prNumber) {
331
+ export function reviewOptions(repo, prNumber, warn) {
304
332
  const config = readConfig();
305
333
  return {
306
334
  command: "review",
@@ -328,6 +356,7 @@ export function reviewOptions(repo, prNumber) {
328
356
  useCodegraph: getRepo(repo)?.use_codegraph === 1,
329
357
  reviewBlocking: reviewBlockingFrom(config.repos?.[repo]?.reviewBlocking ?? config.reviewBlocking),
330
358
  reviewSystemPrompt: config.repos?.[repo]?.reviewSystemPrompt,
359
+ ...serverDiagramOptions(config.repos?.[repo] ?? {}, repo, warn),
331
360
  };
332
361
  }
333
362
  export function aiFor(options) {
@@ -444,7 +473,7 @@ async function finishCheck(client, job, checkRunId, conclusion, title, findings,
444
473
  },
445
474
  }, log);
446
475
  }
447
- async function publish(client, job, reviewId, headSha, files, log, metadata, mode = DEFAULT_REVIEW_BLOCKING) {
476
+ async function publish(client, job, reviewId, headSha, files, log, metadata, mode = DEFAULT_REVIEW_BLOCKING, extensions = EMPTY_REPORT) {
448
477
  const stored = listFindingsForReview(reviewId);
449
478
  // GitHub wraps every `in_reply_to` comment in a review of its own, so a round
450
479
  // posts no replies. A repeat stays on its thread and in the summary, and a
@@ -485,8 +514,9 @@ async function publish(client, job, reviewId, headSha, files, log, metadata, mod
485
514
  ? (getReview(row.first_seen_review_id)?.head_sha ?? undefined)
486
515
  : undefined,
487
516
  }));
488
- const body = reviewBody(summaryFindings, metadata, stillOpen);
489
- const comments = inline.map(({ finding, anchor, suggestion }) => ({
517
+ const extensionSplit = splitExtensionFindings(extensions, files, humanCopy);
518
+ const body = reviewBodyWithExtensions(reviewBody(summaryFindings, metadata, stillOpen), extensions, extensionSplit.listed, humanCopy);
519
+ const aiComments = inline.map(({ finding, anchor, suggestion }) => ({
490
520
  path: finding.path,
491
521
  body: inlineCommentBody(finding, suggestion),
492
522
  line: anchor.line,
@@ -495,6 +525,7 @@ async function publish(client, job, reviewId, headSha, files, log, metadata, mod
495
525
  ? {}
496
526
  : { start_line: anchor.start_line, start_side: "RIGHT" }),
497
527
  }));
528
+ const comments = [...aiComments, ...extensionSplit.comments];
498
529
  if (hasForbiddenCopy(body) ||
499
530
  hasForbiddenCopy(ACCESS_DENIED_BODY) ||
500
531
  comments.some((comment) => hasForbiddenCopy(comment.body))) {
@@ -506,7 +537,7 @@ async function publish(client, job, reviewId, headSha, files, log, metadata, mod
506
537
  const payload = {
507
538
  commit_id: headSha,
508
539
  body,
509
- event: appReviewEvent(stored, mode),
540
+ event: reviewEventWithExtensions(appReviewEvent(stored, mode), extensions),
510
541
  comments,
511
542
  };
512
543
  setReviewStatus(reviewId, "posting");
@@ -540,9 +571,7 @@ async function publish(client, job, reviewId, headSha, files, log, metadata, mod
540
571
  catch (error) {
541
572
  if (error instanceof GitHubHttpError && error.status === 422) {
542
573
  log("info", "inline comments rejected, falling back to an issue comment");
543
- const posted = await post(client, `repos/${job.repo}/issues/${job.pr_number}/comments`, {
544
- body: reviewBody(summaryFindings, metadata, stillOpen),
545
- });
574
+ const posted = await post(client, `repos/${job.repo}/issues/${job.pr_number}/comments`, { body });
546
575
  setReviewStatus(reviewId, "posted", {
547
576
  posted_review_id: String(posted.id ?? ""),
548
577
  findings_count: stored.length,
@@ -591,9 +620,9 @@ export async function reconcileReview(job, log, client) {
591
620
  setReviewStatus(review.id, "failed");
592
621
  log("info", "posting crashed and no matching GitHub review was found");
593
622
  }
594
- export async function runReviewJob(job, log, client, ai) {
623
+ export async function runReviewJob(job, log, client, ai, signal) {
595
624
  try {
596
- await runReviewJobCore(job, log, client, ai);
625
+ await runReviewJobCore(job, log, client, ai, signal);
597
626
  }
598
627
  catch (error) {
599
628
  const review = getReviewByJobId(job.id);
@@ -615,7 +644,7 @@ export async function runReviewJob(job, log, client, ai) {
615
644
  throw error;
616
645
  }
617
646
  }
618
- async function runReviewJobCore(job, log, client, ai) {
647
+ async function runReviewJobCore(job, log, client, ai, signal) {
619
648
  const startedAt = Date.now();
620
649
  if (job.pr_number === null) {
621
650
  throw new Error("review job is missing a pull request number");
@@ -635,7 +664,7 @@ async function runReviewJobCore(job, log, client, ai) {
635
664
  return;
636
665
  }
637
666
  const args = JSON.parse(job.args || "{}");
638
- const options = reviewOptionsForJob(job.repo, job.pr_number, args);
667
+ const options = reviewOptionsForJob(job.repo, job.pr_number, args, (text) => log("info", text));
639
668
  const pr = await github.request(`repos/${job.repo}/pulls/${job.pr_number}`);
640
669
  if (args.trigger === "request-comment" && !existing) {
641
670
  const blocked = requestedReviewBlocked(job.repo, pr);
@@ -755,7 +784,10 @@ async function runReviewJobCore(job, log, client, ai) {
755
784
  const subjectRevision = getSubjectRevision(subject.id);
756
785
  let carryItems = [];
757
786
  let carryPrevious = null;
758
- const extras = {};
787
+ // Only an incremental round leaves out what the last round saw, so only
788
+ // it sends the files the last round dropped.
789
+ const catchesUp = scope === "incremental";
790
+ const extras = { catchesUp };
759
791
  // A guide rebuilt after the previous review invalidates that review's
760
792
  // verdicts and its "unchanged" suppression. Treat the run as
761
793
  // if it had started fresh: carry-over off, every changed file back in scope,
@@ -764,8 +796,19 @@ async function runReviewJobCore(job, log, client, ai) {
764
796
  guideRebuiltSince(subjectRevision.guide_built_at, guidesBefore.guideBuiltAt);
765
797
  if (subjectRevision && !guideRebuilt) {
766
798
  const prevFiles = parseRevisionFiles(subjectRevision);
767
- const { unchanged } = incrementalDiffPaths(revision, prevFiles);
799
+ const { changed, unchanged } = incrementalDiffPaths(revision, prevFiles, parseVisiblePaths(subjectRevision));
768
800
  extras.unchangedPaths = scope === "incremental" ? unchanged : undefined;
801
+ if (scope === "incremental") {
802
+ // The compare lists only what changed since the last round. A file
803
+ // that round dropped or withheld is not in it when nobody touched it
804
+ // since, so it is sent from the pull request's own file list.
805
+ const due = new Set(changed.map((file) => file.path));
806
+ const compared = new Set(files.map((file) => String(file.filename)));
807
+ extras.resend = publishFiles.filter((file) => {
808
+ const path = String(file.filename ?? "");
809
+ return due.has(path) && !compared.has(path);
810
+ });
811
+ }
769
812
  const storedRows = listCarryableFindingsForReview(subjectRevision.review_id);
770
813
  const replies = await findingReplies(github, job, storedRows, log);
771
814
  carryPrevious = {
@@ -789,9 +832,33 @@ async function runReviewJobCore(job, log, client, ai) {
789
832
  extras.carryPrompt = buildCarryPromptSection(carryItems, revision);
790
833
  }
791
834
  const costTally = emptyTally();
835
+ // The engine's answer carries the last review call's tokens only. A JSON
836
+ // retry and a large diff summary are calls of this review too.
837
+ const tokens = { in: 0, out: 0 };
792
838
  let response;
839
+ let extensions;
793
840
  try {
794
- response = await runReviewEngine(github, options, async (call) => addResponseCost(costTally, call), snapshot, ai ?? aiFor(options), (message) => log("info", message), extras);
841
+ ({ review: response, extensions } = await withExtensions(appPrContext({
842
+ jobId: job.id,
843
+ repo: job.repo,
844
+ prNumber: job.pr_number,
845
+ headSha,
846
+ baseSha: reviewBase,
847
+ branch: String(pr.head?.ref ?? "") || null,
848
+ scope,
849
+ sinceCommit: scope === "incremental" ? (args.sinceCommit ?? null) : null,
850
+ trigger: args.trigger ?? "manual",
851
+ round: args.round ?? 1,
852
+ files,
853
+ subjectId: subject.id,
854
+ reviewId,
855
+ signal,
856
+ log: (message) => log("info", message),
857
+ }), () => runReviewEngine(github, options, async (call) => {
858
+ addResponseCost(costTally, call);
859
+ tokens.in += call.tokensIn;
860
+ tokens.out += call.tokensOut;
861
+ }, snapshot, ai ?? aiFor(options), (message) => log("info", message), extras), (result) => reviewResultJson(result.text, options.reviewBlocking)));
795
862
  }
796
863
  catch (error) {
797
864
  // A provider throw or an empty/unusable answer is a failed attempt, not a
@@ -800,6 +867,10 @@ async function runReviewJobCore(job, log, client, ai) {
800
867
  await recordFailedReview(github, job, reviewId, costTally, log);
801
868
  throw error;
802
869
  }
870
+ // A Stop while extensions ran cut them short: posting would name them as
871
+ // failed. The remote job returns the same way.
872
+ if (signal?.aborted && hasExtensions(extensions))
873
+ return;
803
874
  guideBuiltAt = response.guideBuiltAt;
804
875
  const visiblePaths = new Set(response.visiblePaths);
805
876
  if (carryPrevious) {
@@ -851,6 +922,9 @@ async function runReviewJobCore(job, log, client, ai) {
851
922
  const previous = listFindingsForPr(job.repo, job.pr_number).filter((row) => row.review_id !== reviewId);
852
923
  for (const finding of parsed) {
853
924
  const repeat = matchRepeat(finding, previous);
925
+ // The next round finds the line again by this text, as the carry-over
926
+ // branch above stores it for its own new findings.
927
+ const patch = revision.files.find((file) => file.path === finding.path)?.patch ?? "";
854
928
  insertFinding({
855
929
  id: crypto.randomUUID(),
856
930
  reviewId,
@@ -860,6 +934,7 @@ async function runReviewJobCore(job, log, client, ai) {
860
934
  lineTo: finding.to,
861
935
  title: finding.heading || finding.path,
862
936
  bodyMd: redact(finding.excerpt),
937
+ anchorText: anchorTextFromPatch(patch, finding.from, finding.to),
863
938
  state: "new",
864
939
  firstSeenReviewId: repeat
865
940
  ? (repeat.first_seen_review_id ?? repeat.review_id)
@@ -868,19 +943,23 @@ async function runReviewJobCore(job, log, client, ai) {
868
943
  });
869
944
  }
870
945
  }
946
+ addExtensionCost(costTally, extensions);
871
947
  setReviewStatus(reviewId, "drafting", {
872
948
  findings_count: totalFindings,
873
949
  open_count: openCount,
874
950
  closed_count: closedCount,
875
- tokens_in: response.tokensIn,
876
- tokens_out: response.tokensOut,
951
+ tokens_in: tokens.in,
952
+ tokens_out: tokens.out,
877
953
  ...costColumns(settle(costTally)),
878
954
  });
879
955
  saveSubjectRevision({
880
956
  subjectId: subject.id,
881
957
  reviewId,
882
958
  files: revision.files,
883
- visiblePaths: [...visiblePaths],
959
+ // A file skipped as unchanged this round stays judged for the next one.
960
+ visiblePaths: [
961
+ ...visiblePathsToSave(carryPrevious?.visiblePaths, extras.unchangedPaths, visiblePaths),
962
+ ],
884
963
  guideBuiltAt,
885
964
  });
886
965
  log("info", `publishing ${totalFindings} finding(s) to GitHub`);
@@ -888,15 +967,17 @@ async function runReviewJobCore(job, log, client, ai) {
888
967
  jobId: job.id,
889
968
  model: options.highModel ?? "unknown",
890
969
  durationMs: Date.now() - startedAt,
891
- }, options.reviewBlocking);
970
+ coverage: response.coverage,
971
+ catchesUp,
972
+ }, options.reviewBlocking, extensions);
892
973
  await resolveFailureNote(github, job, reviewId, log);
893
- const openFindings = totalFindings - closedCount;
974
+ const openFindings = totalFindings - closedCount + standingExtensionFindings(extensions);
894
975
  await finishCheck(github, job, checkRunId, openFindings === 0 ? "success" : "neutral", openFindings === 0 ? "Review completed" : "Review findings", listFindingsForReview(reviewId), log);
895
976
  }
896
977
  export function registerReviewJobHandler() {
897
978
  registerHandler("review", {
898
- run(job, log, _signal) {
899
- return runReviewJob(job, log);
979
+ run(job, log, signal) {
980
+ return runReviewJob(job, log, undefined, undefined, signal);
900
981
  },
901
982
  reconcile(job, log) {
902
983
  return resolveInstallationId(job.repo).then((installationId) => {
@@ -0,0 +1,46 @@
1
+ import { type InstructionCounts, type InstructionsResult } from "../knowledge/instructions.ts";
2
+ import { type RuleChanges } from "../knowledge/rule_changes.ts";
3
+ import type { Source } from "../knowledge/types.ts";
4
+ import type { AiProvider, AiResponse, Options } from "../types.ts";
5
+ export type InstructionsOutcome = InstructionsResult | {
6
+ status: "skipped";
7
+ reason: string;
8
+ }
9
+ /** Files matched but none could be read: a GitHub hiccup, not a removed
10
+ * file, so the previous file and its ids are kept. */
11
+ | {
12
+ status: "unreadable";
13
+ };
14
+ /** One `synth_instructions` call over the files `collect` read. Never
15
+ * throws: the run must not fail over the instructions. */
16
+ export declare function buildInstructions(provider: AiProvider, options: Options, source: Source, usage: (job: string, response: AiResponse) => Promise<void>): Promise<InstructionsOutcome>;
17
+ /** What `init --json` and `sync --json` say about `INSTRUCTIONS.md`. */
18
+ export declare function instructionsJson(outcome: InstructionsOutcome): {
19
+ status: "written" | "kept" | "empty" | "skipped";
20
+ rules: number;
21
+ reason?: string;
22
+ counts?: InstructionCounts;
23
+ };
24
+ export type RulesWriteResult = {
25
+ rules: number;
26
+ /** `null` when there was no earlier `RULES.json` to compare with. */
27
+ changes: {
28
+ instructions: RuleChanges;
29
+ } | null;
30
+ /** False when the instructions were skipped and there was no earlier
31
+ * `INSTRUCTIONS.md` or `RULES.json`: nothing happened that the run's output
32
+ * should mention, so a repository without instruction files sees the same
33
+ * output as before. */
34
+ reported: boolean;
35
+ };
36
+ /** Writes or removes `INSTRUCTIONS.md`, writes `RULES.json`, and reports
37
+ * what changed since the last build. The caller holds the knowledge lock, so
38
+ * the ids here and the files beside them belong to one build. */
39
+ export declare function writeInstructionsAndRules(input: {
40
+ repo: string;
41
+ /** `init` names a skip even with nothing to remove, so a first build says
42
+ * why it has no `INSTRUCTIONS.md`. A `sync` stays quiet then. */
43
+ command: "init" | "remake" | "probe" | "review";
44
+ instructions: InstructionsOutcome;
45
+ source: Source;
46
+ }): Promise<RulesWriteResult>;
@@ -0,0 +1,155 @@
1
+ /** The `INSTRUCTIONS.md` and `RULES.json` half of `init` and `sync`.
2
+ *
3
+ * Kept out of `setup.ts` so the build step there stays one call to build the
4
+ * instructions and one call, under the knowledge lock, to write them with the
5
+ * rules. */
6
+ import { reposDir } from "../config.js";
7
+ import { agentInstructionsLimit, DEFAULT_AGENT_INSTRUCTIONS, } from "../knowledge/instruction_files.js";
8
+ import { instructionRuleEntries, instructionsWriteLine, synthesizeInstructions, } from "../knowledge/instructions.js";
9
+ import { compareRules, ruleChangeLine, } from "../knowledge/rule_changes.js";
10
+ import { INSTRUCTIONS_FILE, parseRules, RULES_FILE, rulesFileText, rulesOfKind, } from "../knowledge/rules.js";
11
+ import { log, timed } from "../util/log.js";
12
+ import { readTextFile, remove, stat } from "../util/runtime.js";
13
+ /** Why no instructions are built this run, or `null` when they are. */
14
+ function skipReason(options, source) {
15
+ if (!options.includeCodebase)
16
+ return "--include-codebase is off";
17
+ if (options.agentInstructions?.trim() === "") {
18
+ return "--agent-instructions is blank";
19
+ }
20
+ // `collect` leaves the field out when nothing matched, and leaves it empty
21
+ // when files matched but none could be read.
22
+ if (source.instructionFiles === undefined) {
23
+ return `no file matches ${options.agentInstructions ?? DEFAULT_AGENT_INSTRUCTIONS}`;
24
+ }
25
+ return null;
26
+ }
27
+ /** One `synth_instructions` call over the files `collect` read. Never
28
+ * throws: the run must not fail over the instructions. */
29
+ export async function buildInstructions(provider, options, source, usage) {
30
+ const reason = skipReason(options, source);
31
+ if (reason)
32
+ return { status: "skipped", reason };
33
+ if (Object.keys(source.instructionFiles ?? {}).length === 0) {
34
+ return { status: "unreadable" };
35
+ }
36
+ log("ai", "starting synth_instructions job");
37
+ // Timed only when it runs, so a repository with no instruction file gets
38
+ // no extra `--log-time` line.
39
+ const result = await timed("synth_instructions AI", options.logTime, () => synthesizeInstructions(provider, options.repo, options.ai, options.highModel ?? "", source.instructionFiles ?? {}, source.tree, agentInstructionsLimit(options.agentInstructionsMaxChars), usage)).catch(() => ({ status: "failed" }));
40
+ log("ai", `synth_instructions complete · ${result.status}`);
41
+ return result;
42
+ }
43
+ /** What `init --json` and `sync --json` say about `INSTRUCTIONS.md`. */
44
+ export function instructionsJson(outcome) {
45
+ switch (outcome.status) {
46
+ case "written":
47
+ return {
48
+ status: "written",
49
+ rules: outcome.rules.length,
50
+ counts: outcome.counts,
51
+ };
52
+ case "failed":
53
+ return { status: "kept", rules: 0 };
54
+ case "unreadable":
55
+ return {
56
+ status: "kept",
57
+ rules: 0,
58
+ reason: "no matched instruction file could be read",
59
+ };
60
+ case "empty":
61
+ return { status: "empty", rules: 0, counts: outcome.counts };
62
+ case "skipped":
63
+ return { status: "skipped", rules: 0, reason: outcome.reason };
64
+ }
65
+ }
66
+ async function exists(path) {
67
+ try {
68
+ await stat(path);
69
+ return true;
70
+ }
71
+ catch {
72
+ return false;
73
+ }
74
+ }
75
+ async function readRulesFile(repo) {
76
+ try {
77
+ return parseRules(await readTextFile(`${reposDir()}/${repo}/${RULES_FILE}`));
78
+ }
79
+ catch {
80
+ return null;
81
+ }
82
+ }
83
+ function instructionsLine(counts) {
84
+ const dropped = counts.unsupportedSource + counts.unknownName;
85
+ return `${INSTRUCTIONS_FILE} skipped: the instruction files hold no rule a reviewer can check · ${dropped} dropped · ${counts.overCap} over the cap`;
86
+ }
87
+ /** Writes or removes `INSTRUCTIONS.md`, writes `RULES.json`, and reports
88
+ * what changed since the last build. The caller holds the knowledge lock, so
89
+ * the ids here and the files beside them belong to one build. */
90
+ export async function writeInstructionsAndRules(input) {
91
+ const { repo, instructions, source } = input;
92
+ const directory = `${reposDir()}/${repo}`;
93
+ const { writeTextFileAtomic } = await import("../util/atomic.js");
94
+ const previous = await readRulesFile(repo);
95
+ const hadInstructions = await exists(`${directory}/${INSTRUCTIONS_FILE}`);
96
+ const hadRules = await exists(`${directory}/${RULES_FILE}`);
97
+ if (instructions.status === "skipped" && !hadInstructions && !hadRules) {
98
+ if (input.command === "init") {
99
+ log("write", `${INSTRUCTIONS_FILE} skipped: ${instructions.reason}`);
100
+ }
101
+ return { rules: 0, changes: null, reported: false };
102
+ }
103
+ let instructionRules = {};
104
+ switch (instructions.status) {
105
+ case "written": {
106
+ await writeTextFileAtomic(`${directory}/${INSTRUCTIONS_FILE}`, instructions.markdown);
107
+ const head = source.commits[0];
108
+ instructionRules = instructionRuleEntries(instructions.rules, head?.sha ? String(head.sha) : undefined);
109
+ log("write", instructionsWriteLine(instructions.rules.length, instructions.counts));
110
+ break;
111
+ }
112
+ case "failed":
113
+ // As with the guide: a provider hiccup must not delete the file the
114
+ // last run wrote, so it and its ids are kept.
115
+ instructionRules = rulesOfKind(previous?.rules, "I");
116
+ log("write", `${INSTRUCTIONS_FILE} not regenerated: the AI produced no usable rules, keeping any existing file`);
117
+ break;
118
+ case "unreadable":
119
+ // A failed fetch is not a removed file: keep what the last run wrote.
120
+ instructionRules = rulesOfKind(previous?.rules, "I");
121
+ log("write", `${INSTRUCTIONS_FILE} not regenerated: no matched instruction file could be read, keeping any existing file`);
122
+ break;
123
+ case "empty":
124
+ await remove(`${directory}/${INSTRUCTIONS_FILE}`).catch(() => { });
125
+ log("write", instructionsLine(instructions.counts));
126
+ break;
127
+ case "skipped":
128
+ await remove(`${directory}/${INSTRUCTIONS_FILE}`).catch(() => { });
129
+ log("write", `${INSTRUCTIONS_FILE} skipped: ${instructions.reason}`);
130
+ break;
131
+ }
132
+ const rules = { ...instructionRules };
133
+ if (Object.keys(rules).length > 0) {
134
+ await writeTextFileAtomic(`${directory}/${RULES_FILE}`, rulesFileText({
135
+ schemaVersion: 1,
136
+ builtAt: new Date().toISOString(),
137
+ rules,
138
+ }));
139
+ }
140
+ else {
141
+ // No rule means no file, as with `INSTRUCTIONS.md`.
142
+ await remove(`${directory}/${RULES_FILE}`).catch(() => { });
143
+ }
144
+ if (!previous) {
145
+ return { rules: Object.keys(rules).length, changes: null, reported: true };
146
+ }
147
+ const changes = {
148
+ instructions: compareRules(previous.rules, rules, "I"),
149
+ };
150
+ if (Object.keys(rulesOfKind(previous.rules, "I")).length > 0 ||
151
+ Object.keys(rules).length > 0) {
152
+ log("instructions", ruleChangeLine(changes.instructions));
153
+ }
154
+ return { rules: Object.keys(rules).length, changes, reported: true };
155
+ }
@@ -1,4 +1,6 @@
1
+ import type { ReviewDocuments } from "../knowledge/guide.ts";
1
2
  import type { AiResponse, GitHubClient, Options } from "../types.ts";
3
+ import type { State } from "../knowledge/types.ts";
2
4
  import type { LogFn } from "./jobs.ts";
3
5
  import type { JobRow } from "../store/rows.ts";
4
6
  import { type CostTally } from "../util/cost.ts";
@@ -12,6 +14,35 @@ export declare function emptyAiMetrics(): AiMetrics;
12
14
  export declare function addAiMetrics(metrics: AiMetrics, response: AiResponse): void;
13
15
  export declare function recordAiCost(repo: string, job: string, response: AiResponse): Promise<void>;
14
16
  export declare function clientFor(options: Options): GitHubClient;
17
+ /** The sections this run rebuilds. With no previous state, or after the high
18
+ * model or the synthesis version changed, that is every section: `undefined`
19
+ * on a first run, all keys after a change. Otherwise the sections whose facts
20
+ * changed, and every codebase section that has facts but is missing from the
21
+ * CODEBASE.md on disk. That last rule rebuilds a section an earlier run lost,
22
+ * for example one 0.6.13 dropped on a sync, instead of keeping it missing
23
+ * until its facts change. */
24
+ export declare function dirtySectionKeys(previous: State | undefined, options: Pick<Options, "highModel" | "synthesisVersion">, hashes: Record<string, string>, previousCodebase?: string): Set<string> | undefined;
25
+ /** The sections that still have facts and that this run did not rebuild, so
26
+ * their previous text is still right. */
27
+ export declare function unchangedSectionKeys(hashes: Record<string, string>, dirty: Set<string> | undefined): Set<string>;
28
+ /** The CODEBASE.md body. A sync rebuilds only the sections whose facts
29
+ * changed, so a section in `keep` keeps the text the last run wrote, the way
30
+ * `assembleSkill` keeps an unchanged skill section. `keep` holds the
31
+ * unchanged sections and those whose synthesis call failed: a failed call is
32
+ * not an answer. A rebuilt section takes its new text, and one that came back
33
+ * empty is dropped: the old text was written from facts that are gone. */
34
+ export declare function mergeCodebaseSections(previousMarkdown: string | undefined, overrides: Record<string, string>, keep: Set<string>): string;
35
+ export type ReviewGuideStatus = {
36
+ /** `kept` is a guide the last run wrote that this run could not rebuild. */
37
+ reviewGuide: "detailed" | "single" | "kept" | "skipped";
38
+ detailed: boolean;
39
+ };
40
+ /** The review guides on disk once this run has written its files. When the AI
41
+ * produced no guide above the signal threshold, `writeReviewDocuments` keeps
42
+ * the last run's files, and every review still reads them. Below the
43
+ * threshold it removes them. */
44
+ export declare function reviewGuideStatus(repo: string, documents: ReviewDocuments | undefined, signalCount: number): Promise<ReviewGuideStatus>;
45
+ export declare function addReviewLink(markdown: string, guide: ReviewGuideStatus): string;
15
46
  export declare function runInitOrRemake(options: Options): Promise<void>;
16
47
  /** Builds `Options` for a server-triggered `init`/`remake` from config
17
48
  * alone — no CLI flags, no interactive prompt, there is no terminal here. */