co-maintainer 0.7.2-beta.1 → 0.7.3

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 (194) hide show
  1. package/dist/package.json +2 -1
  2. package/dist/src/ai/anthropic.d.ts +1 -1
  3. package/dist/src/ai/anthropic.js +1 -1
  4. package/dist/src/ai/batch.d.ts +1 -1
  5. package/dist/src/ai/batch.js +3 -3
  6. package/dist/src/ai/copy_rule.d.ts +7 -0
  7. package/dist/src/ai/copy_rule.js +23 -0
  8. package/dist/src/ai/estimate.js +3 -3
  9. package/dist/src/ai/fake.js +2 -1
  10. package/dist/src/ai/mermaid.js +1 -0
  11. package/dist/src/ai/oauth/registry.d.ts +1 -1
  12. package/dist/src/ai/oauth/sign-in-with-chatgpt.d.ts +4 -4
  13. package/dist/src/ai/oauth/sign-in-with-chatgpt.js +6 -6
  14. package/dist/src/ai/openai.d.ts +3 -3
  15. package/dist/src/ai/openai.js +4 -4
  16. package/dist/src/ai/openrouter.d.ts +1 -1
  17. package/dist/src/ai/openrouter.js +1 -1
  18. package/dist/src/ai/pricing.js +1 -1
  19. package/dist/src/ai/provider.d.ts +2 -0
  20. package/dist/src/ai/provider.js +8 -2
  21. package/dist/src/ai/verify.d.ts +1 -1
  22. package/dist/src/ai/verify.js +1 -1
  23. package/dist/src/cli/args.js +1 -1
  24. package/dist/src/cli/command_json.d.ts +4 -2
  25. package/dist/src/cli/command_json.js +1 -0
  26. package/dist/src/cli/commands/config.d.ts +1 -1
  27. package/dist/src/cli/commands/config.js +1 -1
  28. package/dist/src/cli/commands/oauth.js +1 -1
  29. package/dist/src/cli/commands/probe.js +1 -1
  30. package/dist/src/cli/commands/review.js +2 -0
  31. package/dist/src/cli/commands/serve.d.ts +1 -1
  32. package/dist/src/cli/commands/serve.js +1 -1
  33. package/dist/src/cli/commands/set.d.ts +1 -1
  34. package/dist/src/cli/commands/set.js +23 -6
  35. package/dist/src/cli/commands/view.js +2 -2
  36. package/dist/src/cli/error.d.ts +1 -1
  37. package/dist/src/cli/error.js +1 -1
  38. package/dist/src/cli/pr_carry.d.ts +2 -0
  39. package/dist/src/cli/pr_carry.js +2 -2
  40. package/dist/src/cli/prompt.d.ts +2 -2
  41. package/dist/src/cli/prompt.js +3 -3
  42. package/dist/src/cli/review_args.js +2 -2
  43. package/dist/src/cli/review_carry.d.ts +3 -1
  44. package/dist/src/cli/review_carry.js +5 -3
  45. package/dist/src/cli/review_result.d.ts +13 -5
  46. package/dist/src/cli/review_result.js +19 -9
  47. package/dist/src/config.d.ts +20 -11
  48. package/dist/src/config.js +3 -3
  49. package/dist/src/github/app.d.ts +1 -1
  50. package/dist/src/github/app.js +1 -1
  51. package/dist/src/github/app_manifest.d.ts +1 -1
  52. package/dist/src/github/app_manifest.js +1 -1
  53. package/dist/src/github/client.d.ts +1 -1
  54. package/dist/src/github/client.js +1 -1
  55. package/dist/src/github/collect.d.ts +7 -1
  56. package/dist/src/github/collect.js +41 -16
  57. package/dist/src/github/gh.js +2 -2
  58. package/dist/src/github/jwt.d.ts +1 -1
  59. package/dist/src/github/jwt.js +1 -1
  60. package/dist/src/github/oauth.js +2 -2
  61. package/dist/src/knowledge/facts.js +3 -3
  62. package/dist/src/knowledge/guide.d.ts +24 -1
  63. package/dist/src/knowledge/guide.js +46 -16
  64. package/dist/src/knowledge/guide_ids.d.ts +9 -0
  65. package/dist/src/knowledge/guide_ids.js +26 -7
  66. package/dist/src/knowledge/probe.js +1 -1
  67. package/dist/src/knowledge/rule_changes.d.ts +18 -0
  68. package/dist/src/knowledge/rule_changes.js +41 -0
  69. package/dist/src/knowledge/rules.d.ts +11 -0
  70. package/dist/src/knowledge/rules.js +10 -1
  71. package/dist/src/knowledge/skill.js +1 -1
  72. package/dist/src/knowledge/stable_ids.d.ts +29 -0
  73. package/dist/src/knowledge/stable_ids.js +90 -0
  74. package/dist/src/knowledge/synthesis.d.ts +13 -1
  75. package/dist/src/knowledge/synthesis.js +94 -26
  76. package/dist/src/knowledge/types.d.ts +16 -0
  77. package/dist/src/local/carry_over_store.d.ts +1 -1
  78. package/dist/src/local/carry_over_store.js +1 -1
  79. package/dist/src/local/codegraph_prepare.js +1 -1
  80. package/dist/src/local/git_ops.js +1 -1
  81. package/dist/src/local/review_local.js +6 -5
  82. package/dist/src/local/review_lock.d.ts +1 -1
  83. package/dist/src/pr/checkout.d.ts +3 -3
  84. package/dist/src/pr/checkout.js +7 -7
  85. package/dist/src/pr/codegraph_tool_args.d.ts +1 -1
  86. package/dist/src/pr/codegraph_tool_args.js +1 -1
  87. package/dist/src/pr/findings.d.ts +3 -0
  88. package/dist/src/pr/findings.js +29 -10
  89. package/dist/src/pr/findings_json.d.ts +2 -2
  90. package/dist/src/pr/findings_json.js +15 -2
  91. package/dist/src/pr/github_revision.js +1 -1
  92. package/dist/src/pr/review_copy.d.ts +2 -3
  93. package/dist/src/pr/review_copy.js +2 -3
  94. package/dist/src/pr/reviewer.d.ts +7 -3
  95. package/dist/src/pr/reviewer.js +26 -26
  96. package/dist/src/pr/scope.d.ts +8 -8
  97. package/dist/src/pr/scope.js +4 -4
  98. package/dist/src/pr/snapshot.d.ts +2 -2
  99. package/dist/src/remote/client.js +4 -3
  100. package/dist/src/remote/schema.d.ts +1 -1
  101. package/dist/src/remote/schema.js +1 -1
  102. package/dist/src/remote/server/body.d.ts +1 -1
  103. package/dist/src/remote/server/body.js +1 -1
  104. package/dist/src/remote/server/guides.js +1 -1
  105. package/dist/src/remote/validate.js +1 -1
  106. package/dist/src/review/blocking.d.ts +3 -3
  107. package/dist/src/review/blocking.js +2 -2
  108. package/dist/src/review/carry_over.d.ts +9 -1
  109. package/dist/src/review/carry_over.js +10 -2
  110. package/dist/src/review/diagram.js +7 -6
  111. package/dist/src/review/engine.d.ts +1 -1
  112. package/dist/src/review/guides.js +1 -1
  113. package/dist/src/review/references.d.ts +68 -0
  114. package/dist/src/review/references.js +176 -0
  115. package/dist/src/review/system_prompt.d.ts +1 -1
  116. package/dist/src/review/system_prompt.js +1 -1
  117. package/dist/src/server/api/jobs.js +2 -2
  118. package/dist/src/server/api/repos.js +1 -1
  119. package/dist/src/server/app.js +1 -1
  120. package/dist/src/server/auth.d.ts +3 -3
  121. package/dist/src/server/auth.js +9 -4
  122. package/dist/src/server/http.js +5 -5
  123. package/dist/src/server/pages/activity.js +1 -1
  124. package/dist/src/server/pages/add_repo.js +1 -0
  125. package/dist/src/server/pages/client.d.ts +2 -2
  126. package/dist/src/server/pages/client.js +2 -2
  127. package/dist/src/server/pages/home.d.ts +1 -1
  128. package/dist/src/server/pages/home.js +1 -1
  129. package/dist/src/server/pages/icons.d.ts +1 -1
  130. package/dist/src/server/pages/icons.js +1 -1
  131. package/dist/src/server/pages/layout.d.ts +2 -2
  132. package/dist/src/server/pages/layout.js +3 -3
  133. package/dist/src/server/pages/pr.js +4 -0
  134. package/dist/src/server/pages/rate_limit_waits.js +2 -2
  135. package/dist/src/server/pages/references.d.ts +2 -0
  136. package/dist/src/server/pages/references.js +55 -0
  137. package/dist/src/server/pages/repo.js +26 -0
  138. package/dist/src/server/pages/repo_settings.js +1 -0
  139. package/dist/src/server/pages/router.js +3 -2
  140. package/dist/src/server/pages/styles.d.ts +2 -2
  141. package/dist/src/server/pages/styles.js +2 -2
  142. package/dist/src/server/pages/ui.d.ts +1 -1
  143. package/dist/src/server/pages/ui.js +2 -2
  144. package/dist/src/server/webhook/index.js +1 -1
  145. package/dist/src/services/clear.d.ts +2 -2
  146. package/dist/src/services/clear.js +2 -2
  147. package/dist/src/services/dashboard.d.ts +2 -0
  148. package/dist/src/services/dashboard.js +2 -0
  149. package/dist/src/services/probe.js +1 -1
  150. package/dist/src/services/push_review.js +4 -1
  151. package/dist/src/services/remote_review.js +5 -2
  152. package/dist/src/services/remote_review_abort.d.ts +1 -1
  153. package/dist/src/services/remote_review_abort.js +1 -1
  154. package/dist/src/services/remote_tokens.js +1 -1
  155. package/dist/src/services/replies.js +0 -2
  156. package/dist/src/services/review.d.ts +3 -5
  157. package/dist/src/services/review.js +43 -18
  158. package/dist/src/services/rules_build.d.ts +20 -1
  159. package/dist/src/services/rules_build.js +85 -6
  160. package/dist/src/services/setup.d.ts +2 -2
  161. package/dist/src/services/setup.js +36 -11
  162. package/dist/src/services/watch_comments.js +1 -2
  163. package/dist/src/services/watch_notes.js +1 -3
  164. package/dist/src/store/app_db.d.ts +1 -1
  165. package/dist/src/store/app_db.js +2 -2
  166. package/dist/src/store/findings.d.ts +2 -0
  167. package/dist/src/store/findings.js +3 -3
  168. package/dist/src/store/jobs.d.ts +2 -2
  169. package/dist/src/store/jobs.js +3 -3
  170. package/dist/src/store/migrations.d.ts +2 -2
  171. package/dist/src/store/migrations.js +35 -18
  172. package/dist/src/store/rows.d.ts +4 -2
  173. package/dist/src/store/rows.js +1 -1
  174. package/dist/src/store/rule_events.d.ts +15 -0
  175. package/dist/src/store/rule_events.js +20 -0
  176. package/dist/src/store/sessions.d.ts +1 -1
  177. package/dist/src/store/sessions.js +2 -2
  178. package/dist/src/store/sqlite.js +2 -2
  179. package/dist/src/tools/codegraph.d.ts +1 -1
  180. package/dist/src/tools/codegraph.js +3 -3
  181. package/dist/src/tools/codegraph_exec.d.ts +1 -1
  182. package/dist/src/tools/codegraph_exec.js +1 -1
  183. package/dist/src/types.d.ts +6 -2
  184. package/dist/src/util/keyed_lock.d.ts +1 -1
  185. package/dist/src/util/keyed_lock.js +1 -1
  186. package/dist/src/util/log.js +1 -1
  187. package/dist/src/util/redact.js +2 -1
  188. package/dist/src/util/run_summary.d.ts +3 -3
  189. package/dist/src/util/run_summary.js +3 -3
  190. package/dist/src/util/runtime.d.ts +4 -4
  191. package/dist/src/util/runtime.js +5 -5
  192. package/dist/src/util/time.d.ts +1 -1
  193. package/dist/src/util/time.js +1 -1
  194. package/package.json +2 -1
@@ -1,6 +1,7 @@
1
1
  /** `init`/`remake` orchestration. The dashboard calls `runInitOrRemake`
2
- * directly; it used to re-spawn the CLI as a subprocess, a second
2
+ * directly. It used to re-spawn the CLI as a subprocess, a second
3
3
  * execution path with its own failure modes. */
4
+ import { recordContradictions } from "../store/rule_events.js";
4
5
  import { aiProviderName, createAiProvider } from "../ai/provider.js";
5
6
  import { enrichFacts, synthesizeSections } from "../knowledge/synthesis.js";
6
7
  import { collectSource } from "../github/collect.js";
@@ -27,7 +28,7 @@ import { addResponseCost, emptyTally } from "../util/cost.js";
27
28
  import { costLabel } from "../util/run_summary.js";
28
29
  import { formatError } from "../cli/error.js";
29
30
  import { buildSetupJson } from "../cli/command_json.js";
30
- import { buildInstructions, instructionsJson, writeInstructionsAndRules, } from "./rules_build.js";
31
+ import { buildInstructions, instructionsJson, readRulesFile, stabilizeRuleIds, writeInstructionsAndRules, } from "./rules_build.js";
31
32
  export function emptyAiMetrics() {
32
33
  return { calls: 0, tokensIn: 0, tokensOut: 0, ...emptyTally() };
33
34
  }
@@ -182,7 +183,7 @@ async function readCodebaseDocument(repo) {
182
183
  /** Writes the codebase-description sections (layout/style/tests/devloop) to
183
184
  * their own file, so `review` can check a pull request against how this
184
185
  * repository's code actually looks, not just the review-bar checklist. Every
185
- * section body is authored by the synthesis job; the skill links to this file
186
+ * section body is authored by the synthesis job. The skill links to this file
186
187
  * rather than repeating it. */
187
188
  async function writeCodebaseDocument(repo, overrides = {}, keep = new Set()) {
188
189
  const path = `${reposDir()}/${repo}/CODEBASE.md`;
@@ -249,6 +250,14 @@ export async function runInitOrRemake(options) {
249
250
  }
250
251
  }
251
252
  async function initOrRemake(options) {
253
+ // Turning review references on re-reads every pull request once, so the
254
+ // guide rules get links to the review comments they came from.
255
+ const repoConfig = readConfig().repos?.[options.repo];
256
+ const backfillLinks = repoConfig?.reviewReferences === true && !repoConfig.referencesBackfilledAt;
257
+ if (backfillLinks) {
258
+ options = { ...options, refreshCommentLinks: true };
259
+ log("fetch", "review references are on: reading every pull request again once for comment links");
260
+ }
252
261
  const operationStarted = performance.now();
253
262
  const aiMetrics = emptyAiMetrics();
254
263
  const previous = await readState(options.repo);
@@ -322,7 +331,11 @@ async function initOrRemake(options) {
322
331
  unchangedSections.add(key);
323
332
  log("ai", `synth_section complete · ${Object.keys(overrides).length} sections`);
324
333
  log("ai", "starting synth_guide jobs");
325
- reviewDocuments = await timed("synth_guide AI", options.logTime, () => synthesizeReviewGuides(highAi, options.repo, options.ai, options.highModel ?? "", options.aiConcurrent, facts, usage));
334
+ // The last build's rules let the guide AI say which old rule a new line
335
+ // goes against. Read outside the lock: it only shapes the prompt, the ids
336
+ // are mapped under the lock below.
337
+ const previousRules = (await readRulesFile(options.repo))?.rules;
338
+ reviewDocuments = await timed("synth_guide AI", options.logTime, () => synthesizeReviewGuides(highAi, options.repo, options.ai, options.highModel ?? "", options.aiConcurrent, facts, usage, previousRules));
326
339
  log("ai", reviewDocuments
327
340
  ? `synth_guide complete · ${reviewDocuments.detailed ? "short + detailed" : "single guide"}`
328
341
  : reviewSignalCount(facts) > 2
@@ -345,19 +358,24 @@ async function initOrRemake(options) {
345
358
  // There is no deterministic fallback to reassemble from: a skill the AI could
346
359
  // not write correctly is reported rather than rebuilt from facts.
347
360
  if (!validation.valid) {
348
- log("validate", `skill problems kept: ${validation.errors.join("; ")}`);
361
+ log("validate", `skill problems kept: ${validation.errors.join(", ")}`);
349
362
  }
350
363
  const finalValidation = await timed("final skill validation", options.logTime, () => validateSkill(result.markdown, source, "warning"));
351
364
  if (finalValidation.warnings.length) {
352
365
  log("validate", `stale references kept: ${finalValidation.warnings.join(", ")}`);
353
366
  }
354
367
  if (!finalValidation.valid) {
355
- log("validate", `skill problems kept: ${finalValidation.errors.join("; ")}`);
368
+ log("validate", `skill problems kept: ${finalValidation.errors.join(", ")}`);
356
369
  }
357
370
  await timed("write skill and state", options.logTime, async () => {
358
371
  const { withKnowledgeLock } = await import("../review/guides.js");
359
372
  const { writeTextFileAtomic } = await import("../util/atomic.js");
360
373
  await withKnowledgeLock(options.repo, async () => {
374
+ // Ids are mapped onto the last build's before the guides are written,
375
+ // so a review that cited R4 still points at the same rule.
376
+ const stable = await stabilizeRuleIds(options.repo, reviewDocuments, instructions);
377
+ reviewDocuments = stable.documents;
378
+ instructions = stable.instructions;
361
379
  await writeTextFileAtomic(path, result.markdown);
362
380
  await writeCodebaseDocument(options.repo, overrides, unchangedSections);
363
381
  await writeReviewDocuments(options.repo, reviewDocuments, reviewSignalCount(facts));
@@ -371,13 +389,16 @@ async function initOrRemake(options) {
371
389
  signalCount: reviewSignalCount(facts),
372
390
  instructions,
373
391
  source,
392
+ lastIds: stable.lastIds,
374
393
  });
375
394
  const head = source.commits[0];
376
395
  const baseSha = head?.sha ? String(head.sha) : new Date().toISOString();
377
- // A CLI init has no app.db row for the repository yet; without one the
396
+ // A CLI init has no app.db row for the repository yet. Without one the
378
397
  // dashboard never sees what it built. A dashboard job already has one.
379
398
  registerCliRepo(options.repo);
380
399
  markKnowledgeBuilt(options.repo, baseSha);
400
+ // The dashboard repo page lists guide rules a newer rule went against.
401
+ recordContradictions(options.repo, rulesResult.contradicted);
381
402
  });
382
403
  await writeState({
383
404
  version: 1,
@@ -413,6 +434,9 @@ async function initOrRemake(options) {
413
434
  prState: options.prState,
414
435
  agentInstructions: options.agentInstructions,
415
436
  agentInstructionsMaxChars: options.agentInstructionsMaxChars,
437
+ ...(backfillLinks
438
+ ? { referencesBackfilledAt: new Date().toISOString() }
439
+ : {}),
416
440
  });
417
441
  });
418
442
  log("write", `${path} · ${result.changed.length
@@ -441,6 +465,7 @@ async function initOrRemake(options) {
441
465
  ? {
442
466
  instructions: instructionsJson(instructions),
443
467
  ruleChanges: rulesResult.changes,
468
+ contradicted: rulesResult.contradicted,
444
469
  }
445
470
  : {}),
446
471
  summary,
@@ -452,13 +477,13 @@ async function initOrRemake(options) {
452
477
  }
453
478
  }
454
479
  /** Builds `Options` for a server-triggered `init`/`remake` from config
455
- * alone — no CLI flags, no interactive prompt, there is no terminal here. */
480
+ * alone, no CLI flags, no interactive prompt, there is no terminal here. */
456
481
  export function optionsFromConfig(repo, command) {
457
482
  const config = readConfig();
458
483
  const repoConfig = config.repos?.[repo] ?? {};
459
484
  const auth = repoConfig.auth ?? config.auth ?? "gh";
460
485
  if (auth === "pat" && !config.githubPat) {
461
- throw new Error("auth=pat requires a GitHub PAT; run: co-maintainer set --github-pat=...");
486
+ throw new Error("auth=pat requires a GitHub PAT. Run: co-maintainer set --github-pat=...");
462
487
  }
463
488
  const ai = repoConfig.ai ?? config.ai ?? "none";
464
489
  const lowModel = repoConfig.lowModel ?? config.lowModel;
@@ -504,12 +529,12 @@ export function optionsFromConfig(repo, command) {
504
529
  agentInstructionsMaxChars: repoConfig.agentInstructionsMaxChars,
505
530
  };
506
531
  }
507
- /** `runner` defaults to the real `runInitOrRemake`; tests substitute a fake
532
+ /** `runner` defaults to the real `runInitOrRemake`. Tests substitute a fake
508
533
  * to check the option merging and log wiring without touching the network. */
509
534
  // ponytail: the AbortSignal the queue passes to `run` is not threaded
510
535
  // through `runInitOrRemake`'s GitHub fetch loops, so `cancel()` on a
511
536
  // running init/remake marks it canceled and stops it being picked up
512
- // again, but does not interrupt in-flight fetches — a live job keeps
537
+ // again, but does not interrupt in-flight fetches, a live job keeps
513
538
  // running to natural completion. Wire the signal into `github/collect.ts`'s
514
539
  // `mapPool` if truly stopping a large in-flight fetch turns out to matter.
515
540
  export function buildSetupHandler(runner = runInitOrRemake) {
@@ -13,7 +13,6 @@ import { FakeAiProvider } from "../ai/fake.js";
13
13
  import { completeWithMermaidTools } from "../ai/mermaid_loop.js";
14
14
  import { mermaidToolFields } from "../review/diagram.js";
15
15
  import { loadGuides } from "../review/guides.js";
16
- import { REVIEW_COPY_RULE } from "../pr/review_copy.js";
17
16
  import { getEnv } from "../util/runtime.js";
18
17
  import { hasWriteAccess } from "../github/write_access.js";
19
18
  import { getWatchIssue, insertWatchNote } from "../store/watch.js";
@@ -145,7 +144,7 @@ async function runWatchComment(job, log) {
145
144
  reasoningEffort: "high",
146
145
  maxTokens: 6000,
147
146
  ...mermaidToolFields(options),
148
- 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. ${REVIEW_COPY_RULE}
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.
149
148
 
150
149
  REVIEW GUIDE:
151
150
  ${(guides.shortGuide || guides.skill || "").slice(0, 20_000)}`,
@@ -6,15 +6,13 @@
6
6
  * filter: no issue, comment or report for that finding again. */
7
7
  import { getWatchIssue, listWatchNotes, markWatchNoteApplied, updateWatchIssue, } from "../store/watch.js";
8
8
  import { log } from "../util/log.js";
9
- import { REVIEW_COPY_RULE } from "../pr/review_copy.js";
10
9
  const SECTION_START = "<!-- co-maintainer:maintainer-notes -->";
11
10
  const SECTION_TITLE = "## Maintainer notes";
12
11
  function notePrompt(note, issueTitle, path) {
13
12
  return `A maintainer replied on an issue an automated code reviewer opened.
14
13
  Turn the reply into one line for the repository's review guide: a general
15
14
  statement a future reviewer must follow, in English, at most 200 characters,
16
- with no names, mentions, issue numbers or quotes. ${REVIEW_COPY_RULE}
17
- Return only that line.
15
+ with no names, mentions, issue numbers or quotes. Return only that line.
18
16
 
19
17
  The reviewer had reported: ${issueTitle}${path ? ` (in ${path})` : ""}
20
18
  The maintainer ${note.kind === "ignore" ? "said to ignore it" : "added information"}:
@@ -1,7 +1,7 @@
1
1
  import { Database } from "./sqlite.ts";
2
2
  import { type BackupPaths } from "./backup.ts";
3
3
  export declare function appDbDir(): string;
4
- /** `CM_APP_DB` overrides the path — tests point it at a temp file. */
4
+ /** `CM_APP_DB` overrides the path, tests point it at a temp file. */
5
5
  export declare function appDbPath(): string;
6
6
  /** The lock file on its own, so `uninstall` deletes it with the database
7
7
  * instead of leaving a pid file that names a process that no longer exists. */
@@ -10,7 +10,7 @@ import { getEnv, isNotFound, isProcessAlive, mkdir, readTextFile, remove, writeT
10
10
  export function appDbDir() {
11
11
  return `${getCacheDir()}/co-maintainer`;
12
12
  }
13
- /** `CM_APP_DB` overrides the path — tests point it at a temp file. */
13
+ /** `CM_APP_DB` overrides the path, tests point it at a temp file. */
14
14
  export function appDbPath() {
15
15
  return getEnv("CM_APP_DB") ?? `${appDbDir()}/app.db`;
16
16
  }
@@ -82,7 +82,7 @@ export async function releaseLock() {
82
82
  await remove(lockPath()).catch(() => { });
83
83
  }
84
84
  /** A database already at a migration this binary does not know about means
85
- * an older release started against one a newer release already touched —
85
+ * an older release started against one a newer release already touched,
86
86
  * refuse loudly instead of running unfamiliar structure through old code. */
87
87
  function migrate(database) {
88
88
  const current = database.prepare("PRAGMA user_version").get()
@@ -14,6 +14,8 @@ export declare function insertFinding(row: {
14
14
  state?: string;
15
15
  carriedFromFindingId?: string | null;
16
16
  closeReason?: string | null;
17
+ /** `ResolvedReference[]` as JSON. Missing stores `[]`. */
18
+ referencesJson?: string;
17
19
  }): void;
18
20
  export declare function listCarryableFindingsForReview(reviewId: string): FindingRow[];
19
21
  export declare function setFindingPosted(id: string, postedCommentId: string, threadCommentId?: string): void;
@@ -4,9 +4,9 @@ export function insertFinding(row) {
4
4
  .prepare(`INSERT INTO findings
5
5
  (id, review_id, severity, path, line_from, line_to, title, body_md,
6
6
  first_seen_review_id, thread_comment_id, anchor_text, state,
7
- carried_from_finding_id, close_reason)
8
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
9
- .run(row.id, row.reviewId, row.severity, row.path ?? null, row.lineFrom ?? null, row.lineTo ?? null, row.title, row.bodyMd, row.firstSeenReviewId ?? null, row.threadCommentId ?? null, row.anchorText ?? null, row.state ?? "new", row.carriedFromFindingId ?? null, row.closeReason ?? null);
7
+ carried_from_finding_id, close_reason, references_json)
8
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
9
+ .run(row.id, row.reviewId, row.severity, row.path ?? null, row.lineFrom ?? null, row.lineTo ?? null, row.title, row.bodyMd, row.firstSeenReviewId ?? null, row.threadCommentId ?? null, row.anchorText ?? null, row.state ?? "new", row.carriedFromFindingId ?? null, row.closeReason ?? null, row.referencesJson ?? "[]");
10
10
  }
11
11
  export function listCarryableFindingsForReview(reviewId) {
12
12
  return getAppDb()
@@ -14,7 +14,7 @@ export declare function listJobs(filter?: {
14
14
  status?: string;
15
15
  repo?: string;
16
16
  }): JobRow[];
17
- /** The queued job for this (repo, PR), if any — the unique partial index
17
+ /** The queued job for this (repo, PR), if any, the unique partial index
18
18
  * guarantees there is at most one. */
19
19
  export declare function getQueuedJob(repo: string, prNumber: number): JobRow | undefined;
20
20
  export declare function getQueuedJobByKey(queueKey: string): JobRow | undefined;
@@ -22,6 +22,6 @@ export declare function getRunningJobByKey(queueKey: string): JobRow | undefined
22
22
  export declare function listJobsByQueueKey(queueKey: string, statuses: string[]): JobRow[];
23
23
  export declare function getOldestQueuedJob(): JobRow | undefined;
24
24
  /** Atomically queued -> running. Returns false if someone else claimed it
25
- * first (or it was superseded/canceled in the meantime) — the caller must
25
+ * first (or it was superseded/canceled in the meantime), the caller must
26
26
  * not assume a claim it did not win. */
27
27
  export declare function claimJob(id: string): boolean;
@@ -1,4 +1,4 @@
1
- /** Row storage only; queue behaviour (claim, supersede, debounce) lives in
1
+ /** Row storage only. Queue behaviour (claim, supersede, debounce) lives in
2
2
  * `services/jobs.ts`, built on top of these primitives. */
3
3
  import { getAppDb } from "./app_db.js";
4
4
  import { nowIso } from "../util/time.js";
@@ -43,7 +43,7 @@ export function listJobs(filter = {}) {
43
43
  .prepare(`SELECT * FROM jobs ${where} ORDER BY created_at DESC`)
44
44
  .all(...params);
45
45
  }
46
- /** The queued job for this (repo, PR), if any — the unique partial index
46
+ /** The queued job for this (repo, PR), if any, the unique partial index
47
47
  * guarantees there is at most one. */
48
48
  export function getQueuedJob(repo, prNumber) {
49
49
  return getAppDb()
@@ -77,7 +77,7 @@ export function getOldestQueuedJob() {
77
77
  .get();
78
78
  }
79
79
  /** Atomically queued -> running. Returns false if someone else claimed it
80
- * first (or it was superseded/canceled in the meantime) — the caller must
80
+ * first (or it was superseded/canceled in the meantime), the caller must
81
81
  * not assume a claim it did not win. */
82
82
  export function claimJob(id) {
83
83
  const db = getAppDb();
@@ -1,5 +1,5 @@
1
1
  /** Numbered, forward-only migrations. Each entry is a
2
2
  * list of individual statements (not one multi-statement blob) run in a
3
- * transaction; `PRAGMA user_version` tracks how many have applied. Never
4
- * edit an already-released migration — add a new one instead. */
3
+ * transaction, `PRAGMA user_version` tracks how many have applied. Never
4
+ * edit an already-released migration, add a new one instead. */
5
5
  export declare const migrations: string[][];
@@ -1,9 +1,9 @@
1
1
  /** Numbered, forward-only migrations. Each entry is a
2
2
  * list of individual statements (not one multi-statement blob) run in a
3
- * transaction; `PRAGMA user_version` tracks how many have applied. Never
4
- * edit an already-released migration — add a new one instead. */
3
+ * transaction, `PRAGMA user_version` tracks how many have applied. Never
4
+ * edit an already-released migration, add a new one instead. */
5
5
  export const migrations = [
6
- // 1 — initial schema
6
+ // 1: initial schema
7
7
  [
8
8
  `CREATE TABLE installations (
9
9
  id INTEGER PRIMARY KEY,
@@ -116,9 +116,9 @@ export const migrations = [
116
116
  files_changed INTEGER NOT NULL
117
117
  )`,
118
118
  ],
119
- // 2 — P7 records when a review fell back to an issue comment
119
+ // 2: P7 records when a review fell back to an issue comment
120
120
  [`ALTER TABLE reviews ADD COLUMN posted_fallback INTEGER NOT NULL DEFAULT 0`],
121
- // 3 — durable conversation replies and purpose-specific queued jobs
121
+ // 3: durable conversation replies and purpose-specific queued jobs
122
122
  [
123
123
  `ALTER TABLE jobs ADD COLUMN queue_key TEXT`,
124
124
  `UPDATE jobs SET queue_key = 'review:' || repo || ':' || pr_number
@@ -154,14 +154,14 @@ export const migrations = [
154
154
  `CREATE INDEX idx_reply_requests_status
155
155
  ON reply_requests(status, created_at)`,
156
156
  ],
157
- // 4 — drift separates pull requests opened since the build from older
157
+ // 4: drift separates pull requests opened since the build from older
158
158
  // ones that were merely touched again
159
159
  [`ALTER TABLE drift ADD COLUMN prs_updated INTEGER NOT NULL DEFAULT 0`],
160
- // 5 — codegraph tools are an opt-in cost per repo, off until asked for
160
+ // 5: codegraph tools are an opt-in cost per repo, off until asked for
161
161
  [`ALTER TABLE repos ADD COLUMN use_codegraph INTEGER NOT NULL DEFAULT 0`],
162
- // 6 — why a job was canceled (dashboard, superseded, remote abort, …)
162
+ // 6: why a job was canceled (dashboard, superseded, remote abort, …)
163
163
  [`ALTER TABLE jobs ADD COLUMN cancel_reason TEXT`],
164
- // 7 — subjects, carry-over fields, reviews table rebuild for nullable PR keys
164
+ // 7: subjects, carry-over fields, reviews table rebuild for nullable PR keys
165
165
  [
166
166
  `CREATE TABLE reviews_new (
167
167
  id TEXT PRIMARY KEY,
@@ -233,7 +233,7 @@ export const migrations = [
233
233
  created_at TEXT NOT NULL
234
234
  )`,
235
235
  ],
236
- // 8 — remote review bearer tokens and large submit payloads
236
+ // 8: remote review bearer tokens and large submit payloads
237
237
  [
238
238
  `CREATE TABLE remote_tokens (
239
239
  id TEXT PRIMARY KEY,
@@ -255,7 +255,7 @@ export const migrations = [
255
255
  `CREATE UNIQUE INDEX idx_remote_inputs_request
256
256
  ON remote_review_inputs(token_id, request_id)`,
257
257
  ],
258
- // 9 — a missing cost is unknown, not zero. Older rows are filled in place
258
+ // 9: a missing cost is unknown, not zero. Older rows are filled in place
259
259
  [
260
260
  `ALTER TABLE reviews ADD COLUMN cost_status TEXT`,
261
261
  `ALTER TABLE reviews ADD COLUMN cost_note TEXT`,
@@ -265,9 +265,9 @@ export const migrations = [
265
265
  WHERE cost IS NULL`,
266
266
  `UPDATE reviews SET billed_to = 'server'`,
267
267
  ],
268
- // 10 — BYOK: persist only whether a review used a client key, never the key
268
+ // 10: BYOK: persist only whether a review used a client key, never the key
269
269
  [`ALTER TABLE remote_review_inputs ADD COLUMN billed_to TEXT`],
270
- // 11 — a per repository review policy. Existing repositories are
270
+ // 11: a per repository review policy. Existing repositories are
271
271
  // pinned to the policy their three old switches amount to, so they keep
272
272
  // behaving exactly as before and the switches keep working. A new repository
273
273
  // starts empty and takes the server default.
@@ -275,21 +275,21 @@ export const migrations = [
275
275
  `ALTER TABLE repos ADD COLUMN review_policy_json TEXT`,
276
276
  `UPDATE repos SET review_policy_json = '"legacy"'`,
277
277
  ],
278
- // 12 — a remote client's one-run review instructions travel with the job so
278
+ // 12: a remote client's one-run review instructions travel with the job so
279
279
  // a retry keeps them. The per-repo prompt stays in config.json and is read
280
280
  // on the server where the review runs.
281
281
  [
282
282
  `ALTER TABLE remote_review_inputs ADD COLUMN system_prompt_add TEXT`,
283
283
  `ALTER TABLE remote_review_inputs ADD COLUMN system_prompt_override TEXT`,
284
284
  ],
285
- // 13 — the one issue comment a failed review leaves on the pull request,
285
+ // 13: the one issue comment a failed review leaves on the pull request,
286
286
  // kept so a retry edits that same note instead of opening a second one.
287
287
  [`ALTER TABLE reviews ADD COLUMN note_comment_id TEXT`],
288
- // 14 — where a repository came from. `'cli'` for one a CLI init built
288
+ // 14: where a repository came from. `'cli'` for one a CLI init built
289
289
  // (registered by init itself, or found on disk by serve after an upgrade),
290
290
  // NULL for one added from the dashboard.
291
291
  [`ALTER TABLE repos ADD COLUMN added_from TEXT`],
292
- // 15 — commit watch: pushes to the default branch, the issues opened for
292
+ // 15: commit watch: pushes to the default branch, the issues opened for
293
293
  // their P0/P1 findings, and the maintainer notes left on those issues.
294
294
  [
295
295
  `ALTER TABLE repos ADD COLUMN watch_open_issues INTEGER NOT NULL DEFAULT 1`,
@@ -352,7 +352,7 @@ 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,
355
+ // 16: extensions: each extension's result for a review, for the dashboard,
356
356
  // and its findings, so a keyed finding is tracked across rounds. A tracked
357
357
  // finding keeps its id from round to round, so the key is (review_id, id).
358
358
  [
@@ -392,4 +392,21 @@ export const migrations = [
392
392
  )`,
393
393
  `CREATE INDEX idx_extension_findings_review ON extension_findings(review_id)`,
394
394
  ],
395
+ // 17: what a finding rests on (guide and instruction rules, the codebase
396
+ // conventions, the review instructions), resolved at review time so a later
397
+ // sync never changes what an old review cited. And a log of guide rules a
398
+ // newer rule went against, for the dashboard.
399
+ [
400
+ `ALTER TABLE findings ADD COLUMN references_json TEXT NOT NULL DEFAULT '[]'`,
401
+ `CREATE TABLE rule_events (
402
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
403
+ repo TEXT NOT NULL,
404
+ at TEXT NOT NULL,
405
+ kind TEXT NOT NULL,
406
+ rule_id TEXT NOT NULL,
407
+ by_rule_id TEXT,
408
+ detail_json TEXT NOT NULL DEFAULT '{}'
409
+ )`,
410
+ `CREATE INDEX idx_rule_events_repo ON rule_events(repo, at)`,
411
+ ],
395
412
  ];
@@ -1,5 +1,5 @@
1
1
  /** JSON columns (permissions, events, args, settings) are stored as their
2
- * raw text; the table module that owns each one decides whether callers
2
+ * raw text. The table module that owns each one decides whether callers
3
3
  * see the string or a parsed object. */
4
4
  export type InstallationRow = {
5
5
  id: number;
@@ -31,7 +31,7 @@ export type RepoRow = {
31
31
  * Optional so a row built by hand (a test fixture) need not name it. */
32
32
  added_from?: string | null;
33
33
  /** Commit watch: 1 opens an issue for each P0/P1 finding. Optional so a
34
- * hand-built fixture need not name it; missing means on. */
34
+ * hand-built fixture need not name it. Missing means on. */
35
35
  watch_open_issues?: number;
36
36
  /** Commit watch: `queue` reviews pushes in a row one by one,
37
37
  * `cancel-and-merge` folds a waiting or running review into the next. */
@@ -115,6 +115,8 @@ export type FindingRow = {
115
115
  state: string;
116
116
  carried_from_finding_id: string | null;
117
117
  close_reason: string | null;
118
+ /** JSON array of `ResolvedReference`, `[]` for rows before references. */
119
+ references_json: string;
118
120
  };
119
121
  export type SubjectRow = {
120
122
  id: string;
@@ -1,4 +1,4 @@
1
1
  /** JSON columns (permissions, events, args, settings) are stored as their
2
- * raw text; the table module that owns each one decides whether callers
2
+ * raw text. The table module that owns each one decides whether callers
3
3
  * see the string or a parsed object. */
4
4
  export {};
@@ -0,0 +1,15 @@
1
+ /** A log of guide rules a newer rule went against, written by `sync` and read
2
+ * by the dashboard repo page. */
3
+ import type { Contradiction } from "../knowledge/rule_changes.ts";
4
+ export type RuleEventRow = {
5
+ id: number;
6
+ repo: string;
7
+ at: string;
8
+ kind: string;
9
+ rule_id: string;
10
+ by_rule_id: string | null;
11
+ detail_json: string;
12
+ };
13
+ export declare function recordContradictions(repo: string, items: Contradiction[], at?: string): void;
14
+ /** The newest events first. */
15
+ export declare function listRuleEvents(repo: string, limit?: number): RuleEventRow[];
@@ -0,0 +1,20 @@
1
+ import { getAppDb } from "./app_db.js";
2
+ export function recordContradictions(repo, items, at = new Date().toISOString()) {
3
+ if (items.length === 0)
4
+ return;
5
+ const insert = getAppDb().prepare(`INSERT INTO rule_events (repo, at, kind, rule_id, by_rule_id, detail_json)
6
+ VALUES (?, ?, 'contradicted', ?, ?, ?)`);
7
+ for (const item of items) {
8
+ insert.run(repo, at, item.id, item.by, JSON.stringify({
9
+ sources: item.sources,
10
+ newest: item.newest,
11
+ dropped: item.dropped,
12
+ }));
13
+ }
14
+ }
15
+ /** The newest events first. */
16
+ export function listRuleEvents(repo, limit = 20) {
17
+ return getAppDb()
18
+ .prepare(`SELECT * FROM rule_events WHERE repo = ? ORDER BY at DESC, id DESC LIMIT ?`)
19
+ .all(repo, limit);
20
+ }
@@ -1,7 +1,7 @@
1
1
  import type { SessionRow } from "./rows.ts";
2
2
  export declare function insertSession(tokenHash: string, username: string, expiresAt: string): void;
3
3
  /** Returns the session only if it exists and has not expired, touching
4
- * `last_seen_at` on the way — an expired row is left for
4
+ * `last_seen_at` on the way, an expired row is left for
5
5
  * `deleteExpiredSessions` to reap rather than deleted here. */
6
6
  export declare function getSession(tokenHash: string): SessionRow | undefined;
7
7
  export declare function deleteSession(tokenHash: string): void;
@@ -1,4 +1,4 @@
1
- /** Stores only the token's hash, never the raw token — hashing itself is
1
+ /** Stores only the token's hash, never the raw token, hashing itself is
2
2
  * `server/auth.ts`'s concern, not this module's. */
3
3
  import { getAppDb } from "./app_db.js";
4
4
  import { nowIso } from "../util/time.js";
@@ -10,7 +10,7 @@ export function insertSession(tokenHash, username, expiresAt) {
10
10
  .run(tokenHash, username, now, expiresAt, now);
11
11
  }
12
12
  /** Returns the session only if it exists and has not expired, touching
13
- * `last_seen_at` on the way — an expired row is left for
13
+ * `last_seen_at` on the way, an expired row is left for
14
14
  * `deleteExpiredSessions` to reap rather than deleted here. */
15
15
  export function getSession(tokenHash) {
16
16
  const db = getAppDb();
@@ -34,7 +34,7 @@ export class Statement {
34
34
  }
35
35
  /** Normalizes call arguments: a single object binds by name, everything else
36
36
  * is a positional list. Values `node:sqlite` refuses are mapped to what it
37
- * accepts — `undefined` to NULL, booleans to 0/1 — on both paths, so a field
37
+ * accepts, `undefined` to NULL, booleans to 0/1, on both paths, so a field
38
38
  * typed `boolean | undefined` survives a named bind too. */
39
39
  function args(params) {
40
40
  if (params.length === 1 && isBindObject(params[0])) {
@@ -69,7 +69,7 @@ export class Database {
69
69
  #changes = 0;
70
70
  constructor(path) {
71
71
  // node --test runs test files in parallel processes, and the cache/app
72
- // databases are shared; node:sqlite defaults to no busy timeout while
72
+ // databases are shared. Node:sqlite defaults to no busy timeout while
73
73
  // @db/sqlite tolerated contention. Wait rather than throw SQLITE_BUSY.
74
74
  this.#database = new DatabaseSync(path, { timeout: 5_000 });
75
75
  }
@@ -27,7 +27,7 @@ export type EnsureOptions = {
27
27
  allowInstall?: boolean;
28
28
  interactive?: boolean;
29
29
  run?: Runner;
30
- /** `node:readline/promises` made this async; both shapes are accepted. */
30
+ /** `node:readline/promises` made this async. Both shapes are accepted. */
31
31
  confirm?: (question: string) => boolean | Promise<boolean>;
32
32
  log?: (message: string) => void;
33
33
  /** Overrides `toolsDir()`, for tests. */
@@ -164,12 +164,12 @@ export async function ensureCodegraph(options = {}) {
164
164
  return present.path;
165
165
  if (present.state === "mismatch") {
166
166
  log(`[codegraph] expected ${version} but found ${present.version} ` +
167
- `at ${present.path}; reinstalling the pinned version`);
167
+ `at ${present.path}, reinstalling the pinned version`);
168
168
  }
169
169
  if (!options.allowInstall) {
170
170
  if (!interactive) {
171
171
  // This path exits rather than continuing, so it must not say "reviewing
172
- // without it"; it says how to proceed.
172
+ // without it". It says how to proceed.
173
173
  log(`[codegraph] codegraph ${version} is not installed.\n` +
174
174
  `Run with --allow-tool-install, or install it yourself:\n ${installHint(version, root)}`);
175
175
  exit(1);
@@ -210,7 +210,7 @@ export async function ensureCodegraphForReview(options = {}) {
210
210
  if (present.state === "ok")
211
211
  return { path: present.path };
212
212
  if (present.state === "mismatch") {
213
- log(`[codegraph] expected ${version} but found ${present.version}; reinstalling`);
213
+ log(`[codegraph] expected ${version} but found ${present.version}, reinstalling`);
214
214
  }
215
215
  if (!options.allowInstall) {
216
216
  // Non-interactive: do not ask, review without it. The caller logs the
@@ -10,7 +10,7 @@ export type CodegraphRunner = (binary: string, args: string[], worktree: string)
10
10
  /** Run the codegraph CLI in a repo root.
11
11
  *
12
12
  * On Windows the CLI is a `.cmd`/`.ps1` shim, and `node:child_process.spawn`
13
- * cannot execute those without a shell — it fails with `EINVAL`. `Deno.Command`
13
+ * cannot execute those without a shell, it fails with `EINVAL`. `Deno.Command`
14
14
  * resolved them natively, so this wrapper is needed only after the Node move.
15
15
  * Route through `cmd /c` exactly like `pr/checkout.ts` does for `git`.
16
16
  */
@@ -6,7 +6,7 @@ const INDEX_COMMANDS = new Set(["init", "sync", "index", "unlock"]);
6
6
  /** Run the codegraph CLI in a repo root.
7
7
  *
8
8
  * On Windows the CLI is a `.cmd`/`.ps1` shim, and `node:child_process.spawn`
9
- * cannot execute those without a shell — it fails with `EINVAL`. `Deno.Command`
9
+ * cannot execute those without a shell, it fails with `EINVAL`. `Deno.Command`
10
10
  * resolved them natively, so this wrapper is needed only after the Node move.
11
11
  * Route through `cmd /c` exactly like `pr/checkout.ts` does for `git`.
12
12
  */
@@ -8,14 +8,14 @@ export type Options = {
8
8
  prNumber?: number;
9
9
  debug: boolean;
10
10
  logTime: boolean;
11
- /** Reviews every changed file with no own/upstream split — the behavior
11
+ /** Reviews every changed file with no own/upstream split, the behavior
12
12
  * before scope.ts existed. Off by default: a re-review round's diff can
13
13
  * carry a merge from the default branch that dwarfs the PR's own change,
14
14
  * and neither a human reviewer nor this flag's absence asks anyone to read
15
15
  * it as if the PR authored it. */
16
16
  reviewUpstream?: boolean;
17
17
  /** CLI review enables codegraph by default (`--disable-codegraph` to skip).
18
- * Server jobs still follow per-repo settings. Indexing adds tokens and time;
18
+ * Server jobs still follow per-repo settings. Indexing adds tokens and time,
19
19
  * measured PR recall gains were small when this was opt-in only (K25). */
20
20
  useCodegraph?: boolean;
21
21
  /** PR review installs the pinned codegraph when `--allow-tool-install` is
@@ -45,6 +45,10 @@ export type Options = {
45
45
  /** Keep only pull requests in the window that have at least one
46
46
  * `CHANGES_REQUESTED` review. Off by default, so the window is unchanged. */
47
47
  onlyRequestChangedPr: boolean;
48
+ /** Read the comments of cached pull requests again when they were stored
49
+ * before comment links were kept. Set by `sync` once, after a repository
50
+ * turned review references on. */
51
+ refreshCommentLinks?: boolean;
48
52
  /** Empty or omitted means every state. `closed` is closed and not merged. */
49
53
  prState?: ("open" | "closed" | "merged")[];
50
54
  maxCommits?: number;
@@ -1,3 +1,3 @@
1
- /** @internal For tests — number of keys with an active or queued lock. */
1
+ /** @internal For tests, number of keys with an active or queued lock. */
2
2
  export declare function keyedLockActiveKeys(): number;
3
3
  export declare function withKeyedLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
@@ -1,5 +1,5 @@
1
1
  const queues = new Map();
2
- /** @internal For tests — number of keys with an active or queued lock. */
2
+ /** @internal For tests, number of keys with an active or queued lock. */
3
3
  export function keyedLockActiveKeys() {
4
4
  return queues.size;
5
5
  }