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,4 +1,5 @@
1
1
  import { type ToolHandler } from "../ai/mermaid_loop.ts";
2
+ import type { ReferenceContext } from "../review/references.ts";
2
3
  import type { Revision } from "../review/revision.ts";
3
4
  import { type Coverage, type CoverageWarning } from "../review/coverage.ts";
4
5
  import type { Snapshot } from "./snapshot.ts";
@@ -40,6 +41,9 @@ export type ReviewOutcome = AiResponse & {
40
41
  * the files it skipped as unchanged. */
41
42
  visiblePaths: string[];
42
43
  guideBuiltAt: string | null;
44
+ /** What the finding references resolve against: the `RULES.json` and the
45
+ * codebase conventions this review was given. Never sent to the model. */
46
+ referenceContext: ReferenceContext;
43
47
  codegraphState: "used" | "disabled" | "unavailable";
44
48
  coverage: Coverage;
45
49
  /** `diff_dropped`, `diff_withheld` and `summary_failed`. */
@@ -55,7 +59,7 @@ export type ReviewOutcome = AiResponse & {
55
59
  * the review itself. A server with no low model configured summarized with
56
60
  * the review's provider before, and still does, so no review fails for it. */
57
61
  export declare function summaryProvider(options: Options, reviewAi: AiProvider, report: ProgressSink, extras?: ReviewExtras): AiProvider;
58
- export declare const MERMAID_GUIDANCE = "Mermaid selection and minimal syntax:\nflowchart = decisions, branches, pipelines, and fallback paths;\nswimlane-beta = work crossing owners, actors, services, teams, or layers;\nsequenceDiagram = ordered calls, webhooks, retries, responses, and timing;\nclassDiagram = class, interface, type, inheritance, or composition relationships;\nstateDiagram-v2 = lifecycle and state transitions;\nerDiagram = database entities, keys, and cardinality;\nrequirementDiagram = requirements linked to tests or implementation;\nusecase-beta = actors and system capabilities;\nC4Context = users, systems, boundaries, and integrations;\nzenuml = compact nested call sequences;\npacket = binary fields, bit ranges, and protocol layout;\narchitecture-beta = services, containers, storage, and deployment topology;\neventmodeling = commands, events, processors, read models, and timelines;\ntreeView-beta = directory, file, module, or dependency hierarchy.\nIf a diagram is useful, call read-mermaid-syntaxes before writing any Mermaid.\nRequest every type you need in a single call, because repeated tool rounds are\ncapped. Use the smallest type that matches the evidence.";
62
+ export declare const MERMAID_GUIDANCE = "Mermaid selection and minimal syntax:\nflowchart = decisions, branches, pipelines, and fallback paths.\nswimlane-beta = work crossing owners, actors, services, teams, or layers.\nsequenceDiagram = ordered calls, webhooks, retries, responses, and timing.\nclassDiagram = class, interface, type, inheritance, or composition relationships.\nstateDiagram-v2 = lifecycle and state transitions.\nerDiagram = database entities, keys, and cardinality.\nrequirementDiagram = requirements linked to tests or implementation.\nusecase-beta = actors and system capabilities.\nC4Context = users, systems, boundaries, and integrations.\nzenuml = compact nested call sequences.\npacket = binary fields, bit ranges, and protocol layout.\narchitecture-beta = services, containers, storage, and deployment topology.\neventmodeling = commands, events, processors, read models, and timelines.\ntreeView-beta = directory, file, module, or dependency hierarchy.\nIf a diagram is useful, call read-mermaid-syntaxes before writing any Mermaid.\nRequest every type you need in a single call, because repeated tool rounds are\ncapped. Use the smallest type that matches the evidence.";
59
63
  /** Without tool support the model cannot read the Mermaid syntax docs, so
60
64
  * asking for a diagram only invites invented syntax. */
61
65
  export declare const NO_DIAGRAM_RULES = "Do not use Mermaid or any other diagram. Explain with prose only.";
@@ -63,7 +67,7 @@ export declare function reviewSystemPrompt(diagrams: boolean, options?: Options)
63
67
  /** The guide block every review sends, kept as the stable head of the system
64
68
  * prompt rather than the user prompt so a provider with prompt caching
65
69
  * (Anthropic's `cache_control`) reads it instead of re-billing it. Nothing
66
- * time-varying may enter this string — a single differing byte makes the cache
70
+ * time-varying may enter this string, a single differing byte makes the cache
67
71
  * miss. */
68
72
  export declare function reviewGuidesBlock(guide: string, detailed: string, codebase: string, instructions?: string): string;
69
73
  /** Shared PR and local/remote workspace review instructions: confirm claims
@@ -74,5 +78,5 @@ export declare function clampImproveMatrix(matrix: number): number;
74
78
  export declare function readGuide(repo: string, name: string): Promise<string>;
75
79
  export type { Snapshot };
76
80
  export declare function reviewPullRequest(client: GitHubClient, options: Options, usage?: UsageSink, snapshot?: Snapshot, ai?: AiProvider, progress?: ProgressSink, extras?: ReviewExtras): Promise<ReviewOutcome>;
77
- /** Local workspace review — same prompt loop as PR review without GitHub. */
81
+ /** Local workspace review, same prompt loop as PR review without GitHub. */
78
82
  export declare function reviewWorkspaceRevision(revision: Revision, options: Options, headSha: string, usage?: UsageSink, ai?: AiProvider, progress?: ProgressSink, extras?: ReviewExtras): Promise<ReviewOutcome>;
@@ -5,7 +5,7 @@ import { loadGuides } from "../review/guides.js";
5
5
  import { notInitializedError } from "../review/not_initialized.js";
6
6
  import { computeScope } from "./scope.js";
7
7
  import { prepareCodegraphTools } from "./codegraph_tools.js";
8
- import { REVIEW_COPY_RULE, severitySection } from "./review_copy.js";
8
+ import { severitySection } from "./review_copy.js";
9
9
  import { repositoryInstructionsBlock, reviewSystemPromptBlock, } from "../review/system_prompt.js";
10
10
  import { readDiffMaxChars } from "./diff_summary.js";
11
11
  import { intentField, intentPromptNote } from "../review/intent.js";
@@ -78,19 +78,19 @@ function diffReport(chars, coverage) {
78
78
  return `diff prepared · ${chars} chars${coverageTruncated(coverage) ? ` · ${coverageCounts(coverage)}` : ""}`;
79
79
  }
80
80
  export const MERMAID_GUIDANCE = `Mermaid selection and minimal syntax:
81
- flowchart = decisions, branches, pipelines, and fallback paths;
82
- swimlane-beta = work crossing owners, actors, services, teams, or layers;
83
- sequenceDiagram = ordered calls, webhooks, retries, responses, and timing;
84
- classDiagram = class, interface, type, inheritance, or composition relationships;
85
- stateDiagram-v2 = lifecycle and state transitions;
86
- erDiagram = database entities, keys, and cardinality;
87
- requirementDiagram = requirements linked to tests or implementation;
88
- usecase-beta = actors and system capabilities;
89
- C4Context = users, systems, boundaries, and integrations;
90
- zenuml = compact nested call sequences;
91
- packet = binary fields, bit ranges, and protocol layout;
92
- architecture-beta = services, containers, storage, and deployment topology;
93
- eventmodeling = commands, events, processors, read models, and timelines;
81
+ flowchart = decisions, branches, pipelines, and fallback paths.
82
+ swimlane-beta = work crossing owners, actors, services, teams, or layers.
83
+ sequenceDiagram = ordered calls, webhooks, retries, responses, and timing.
84
+ classDiagram = class, interface, type, inheritance, or composition relationships.
85
+ stateDiagram-v2 = lifecycle and state transitions.
86
+ erDiagram = database entities, keys, and cardinality.
87
+ requirementDiagram = requirements linked to tests or implementation.
88
+ usecase-beta = actors and system capabilities.
89
+ C4Context = users, systems, boundaries, and integrations.
90
+ zenuml = compact nested call sequences.
91
+ packet = binary fields, bit ranges, and protocol layout.
92
+ architecture-beta = services, containers, storage, and deployment topology.
93
+ eventmodeling = commands, events, processors, read models, and timelines.
94
94
  treeView-beta = directory, file, module, or dependency hierarchy.
95
95
  If a diagram is useful, call read-mermaid-syntaxes before writing any Mermaid.
96
96
  Request every type you need in a single call, because repeated tool rounds are
@@ -131,7 +131,7 @@ ${diagrams ? (plantumlSystemRules(options) ?? REVIEW_DIAGRAM_RULES) : NO_DIAGRAM
131
131
  /** The guide block every review sends, kept as the stable head of the system
132
132
  * prompt rather than the user prompt so a provider with prompt caching
133
133
  * (Anthropic's `cache_control`) reads it instead of re-billing it. Nothing
134
- * time-varying may enter this string — a single differing byte makes the cache
134
+ * time-varying may enter this string, a single differing byte makes the cache
135
135
  * miss. */
136
136
  export function reviewGuidesBlock(guide, detailed, codebase, instructions = "") {
137
137
  return `REVIEW GUIDE:
@@ -158,7 +158,7 @@ when a tool can answer. A missing regression test is not a substitute for
158
158
  identifying the concrete input or code path that misbehaves when you can.`;
159
159
  /** Turns a model reply into the Markdown every consumer already parses.
160
160
  * A reply that is not usable JSON is retried once with an
161
- * explicit reminder; if that also fails, the raw text is returned so the
161
+ * explicit reminder, if that also fails, the raw text is returned so the
162
162
  * legacy Markdown parser can still read it. This keeps a provider that ignores
163
163
  * `response_format` working, and never drops a review on the floor. */
164
164
  async function normalizeReviewResponse(provider, request, response, extraTools, maxToolRounds, usage, report, options) {
@@ -255,9 +255,9 @@ export async function reviewPullRequest(client, options, usage, snapshot, ai, pr
255
255
  console.log(`[debug] PR #${number} · comments=${comments.length} · reviews=${reviews.length} · files=${files.length}`);
256
256
  }
257
257
  // What the author actually wrote this round, as opposed to code that
258
- // arrived by merging the default branch in — see scope.ts. A re-review
258
+ // arrived by merging the default branch in, see scope.ts. A re-review
259
259
  // round's diff regularly carries a `merge main` that dwarfs the PR's own
260
- // change and that no human reviewer reads either; --review-upstream turns
260
+ // change and that no human reviewer reads either, --review-upstream turns
261
261
  // this off and reviews everything, matching the pre-scope behavior.
262
262
  const headSha = snapshot?.commit ?? String(pr.head?.sha ?? "");
263
263
  const baseRevision = snapshot?.base ?? String(pr.base?.ref ?? "main");
@@ -309,7 +309,7 @@ export async function reviewPullRequest(client, options, usage, snapshot, ai, pr
309
309
  report(`codegraph tools · ${codegraphTools.length > 0 ? "ready" : "unavailable"}`);
310
310
  }
311
311
  const extraTools = [...codegraphTools, ...prepared.tools];
312
- // Bigger own-scope diffs need more codegraph round-trips to trace — fixed
312
+ // Bigger own-scope diffs need more codegraph round-trips to trace, fixed
313
313
  // at 3 rounds regardless of size caused the model to run out mid-review on
314
314
  // large PRs (verified via a tokio benchmark run: it hallucinated fake
315
315
  // tool-call text instead of a finding once tools were dropped).
@@ -346,12 +346,12 @@ Do not invent requirements. Ignore bot noise and historical PR identities.
346
346
  Reason thoroughly, then answer with the JSON object described below and nothing
347
347
  else. There is no fixed number of findings. Return every independently
348
348
  actionable finding supported by the diff and guide, including zero findings
349
- when appropriate. Do not stop early; inspect all supplied diff text first and
349
+ when appropriate. Do not stop early. Inspect all supplied diff text first and
350
350
  return the natural count. If the diff contains a truncation marker, limit
351
351
  claims to the supplied text and do not imply that omitted files were reviewed.
352
352
  Do not invent low-value findings.
353
353
  When the DIFF section below has an UPSTREAM CONTEXT part, that code arrived
354
- through a merge and was not authored by this pull request; do not raise a
354
+ through a merge and was not authored by this pull request. Do not raise a
355
355
  finding located only there, and never mark blocking a finding whose only
356
356
  support is upstream context.
357
357
  ${CODEGRAPH_DIFF_VERIFICATION}
@@ -360,7 +360,6 @@ suggestion. Write prose only: do not emit Markdown headings, a Location line,
360
360
  backticks around the path, or the sentence "If you'd like me to explain it in
361
361
  more detail, please ask." Our code renders the heading, the location, and the
362
362
  suggestion from your JSON fields. Use P0-P3 severity, and true for blocking.
363
- ${REVIEW_COPY_RULE}
364
363
  Every diff line in the DIFF section starts with its line number in the new
365
364
  file. Copy "lineFrom" and "lineTo" from that column instead of counting from
366
365
  the @@ header. Removed lines have no number, so anchor a finding about removed
@@ -409,7 +408,7 @@ ${diff}`;
409
408
  if (!response.text.trim()) {
410
409
  throw new Error(`${aiProviderName(options)} returned an empty review. The reasoning budget may have been exhausted`);
411
410
  }
412
- // The model returns JSON; we render the Markdown. A reply
411
+ // The model returns JSON. We render the Markdown. A reply
413
412
  // that is not usable JSON is retried once and then falls back to the legacy
414
413
  // Markdown parser, so a provider that ignores the schema still works.
415
414
  let reviewText = await normalizeReviewResponse(provider, request, response, extraTools, maxToolRounds, usage, report, options);
@@ -452,6 +451,7 @@ ${reviewText}`,
452
451
  text: `${severitySection()}\n${renderDiagrams(reviewText, options)}`,
453
452
  visiblePaths: prepared.seenPaths,
454
453
  guideBuiltAt: guides.guideBuiltAt,
454
+ referenceContext: { rules: guides.rules, codebase: guides.codebase },
455
455
  codegraphState: !options.useCodegraph
456
456
  ? "disabled"
457
457
  : codegraphTools.length > 0
@@ -462,7 +462,7 @@ ${reviewText}`,
462
462
  diffStats: diffStats(named.map(({ file }) => diffFileFromGithub(file))),
463
463
  };
464
464
  }
465
- /** Local workspace review — same prompt loop as PR review without GitHub. */
465
+ /** Local workspace review, same prompt loop as PR review without GitHub. */
466
466
  export async function reviewWorkspaceRevision(revision, options, headSha, usage, ai, progress, extras) {
467
467
  const report = progress ?? (() => { });
468
468
  report(modelSummary(options));
@@ -511,7 +511,6 @@ Do not invent low-value findings. If the diff contains a truncation marker or a
511
511
  file is summarized, limit claims to the supplied text and use read-full-diff or
512
512
  codegraph tools before asserting behavior outside what was shown.
513
513
  ${CODEGRAPH_DIFF_VERIFICATION}
514
- ${REVIEW_COPY_RULE}
515
514
  ${diagrams ? (plantumlPromptRules(options) ?? DIAGRAM_PROMPT_RULES) : NO_DIAGRAM_RULES}
516
515
  ${FINDINGS_JSON_INSTRUCTIONS}
517
516
 
@@ -549,7 +548,7 @@ ${ownDiff}${unchangedListing}`;
549
548
  prompt: `Audit the draft review below against the complete diff and guides.
550
549
  Preserve valid findings, correct inaccurate ones, remove duplicate or
551
550
  unsupported ones, and add every missing actionable finding. Re-check each
552
- finding with codegraph when it depends on behavior outside the diff; remove
551
+ finding with codegraph when it depends on behavior outside the diff. Remove
553
552
  findings that only looked plausible from the diff slice.
554
553
  Return the complete revised review as the same JSON object, and nothing else.
555
554
 
@@ -574,6 +573,7 @@ ${reviewText}`,
574
573
  text: `${severitySection()}\n${renderDiagrams(reviewText, options)}`,
575
574
  visiblePaths: prepared.seenPaths,
576
575
  guideBuiltAt: guides.guideBuiltAt,
576
+ referenceContext: { rules: guides.rules, codebase: guides.codebase },
577
577
  codegraphState,
578
578
  coverage: prepared.coverage,
579
579
  warnings: prepared.warnings,
@@ -2,18 +2,18 @@ import { type Run } from "./checkout.ts";
2
2
  /** What a pull request's author actually wrote this round, as opposed to code
3
3
  * that arrived by merging the default branch in. A re-review round's diff
4
4
  * regularly includes a `merge main` a human reviewer never reads and a bot
5
- * should not either — one measured case in this repo's own benchmark had a
5
+ * should not either, one measured case in this repo's own benchmark had a
6
6
  * round diff of 48 files where the author's own commits touched 5. Findings
7
- * belong in the own set; upstream code is context, shown but not policed,
7
+ * belong in the own set. Upstream code is context, shown but not policed,
8
8
  * because the author's own change can still interact badly with it. */
9
9
  export type ScopeResult = {
10
10
  /** Files touched by a commit the author made this round: their own
11
11
  * non-merge commits, plus the conflict-resolution hunks of any merge they
12
- * made. A clean "merge main in" contributes nothing here — `--cc` only
12
+ * made. A clean "merge main in" contributes nothing here, `--cc` only
13
13
  * surfaces lines that differ from every parent, which is exactly the part
14
14
  * a human resolved by hand. */
15
15
  ownFiles: Set<string>;
16
- /** Everything else touched between the round's boundary and its head —
16
+ /** Everything else touched between the round's boundary and its head,
17
17
  * code that arrived via a merge and was not authored this round. */
18
18
  upstreamFiles: Set<string>;
19
19
  defaultBranch: string;
@@ -21,13 +21,13 @@ export type ScopeResult = {
21
21
  mergeCommits: number;
22
22
  };
23
23
  /** The scope algorithm against a clone that is already on disk. Split out from
24
- * `computeScope` so a caller that already manages its own clone — the
25
- * benchmark's OCR runner has its own, separate from co-maintainer's — can run
24
+ * `computeScope` so a caller that already manages its own clone, the
25
+ * benchmark's OCR runner has its own, separate from co-maintainer's, can run
26
26
  * the identical algorithm without a second clone of the same repository. */
27
27
  export declare function scopeInClone(clone: string, base: string, head: string, run?: Run, remote?: string): Promise<ScopeResult | undefined>;
28
28
  /** Clones (or reuses) `repo` under co-maintainer's own cache and runs the
29
- * scope algorithm against it. Returns `undefined` on any failure — no clone,
30
- * an unresolvable commit, no default branch to compare against — so the
29
+ * scope algorithm against it. Returns `undefined` on any failure, no clone,
30
+ * an unresolvable commit, no default branch to compare against, so the
31
31
  * caller's fallback is always "review everything, unscoped", never a broken
32
32
  * review. */
33
33
  export declare function computeScope(repo: string, base: string, head: string, options?: {
@@ -8,8 +8,8 @@ function lines(output) {
8
8
  .filter(Boolean);
9
9
  }
10
10
  /** The scope algorithm against a clone that is already on disk. Split out from
11
- * `computeScope` so a caller that already manages its own clone — the
12
- * benchmark's OCR runner has its own, separate from co-maintainer's — can run
11
+ * `computeScope` so a caller that already manages its own clone, the
12
+ * benchmark's OCR runner has its own, separate from co-maintainer's, can run
13
13
  * the identical algorithm without a second clone of the same repository. */
14
14
  export async function scopeInClone(clone, base, head, run = runCommand, remote = "origin") {
15
15
  let baseSha;
@@ -64,8 +64,8 @@ export async function scopeInClone(clone, base, head, run = runCommand, remote =
64
64
  };
65
65
  }
66
66
  /** Clones (or reuses) `repo` under co-maintainer's own cache and runs the
67
- * scope algorithm against it. Returns `undefined` on any failure — no clone,
68
- * an unresolvable commit, no default branch to compare against — so the
67
+ * scope algorithm against it. Returns `undefined` on any failure, no clone,
68
+ * an unresolvable commit, no default branch to compare against, so the
69
69
  * caller's fallback is always "review everything, unscoped", never a broken
70
70
  * review. */
71
71
  export async function computeScope(repo, base, head, options = {}) {
@@ -1,8 +1,8 @@
1
1
  /** Pins a review to a historical diff/discussion state instead of the PR's
2
- * current (latest) state — used by the benchmarks to show the model exactly
2
+ * current (latest) state, used by the benchmarks to show the model exactly
3
3
  * what a human reviewer saw, without leaking later comments as hints.
4
4
  * `base` defaults to the PR's merge-base with its base branch (the whole PR
5
- * so far); pass an earlier review round's commit as `base` to show only the
5
+ * so far). Pass an earlier review round's commit as `base` to show only the
6
6
  * incremental diff a re-reviewer would see since that round (P11). */
7
7
  export type Snapshot = {
8
8
  base?: string;
@@ -162,7 +162,7 @@ export async function runRemoteReview(cli) {
162
162
  gitRoot: root,
163
163
  enabled: !cli.disableCodegraph,
164
164
  allowInstall: cli.allowToolInstall,
165
- // `--json` must stay machine-readable; `canPrompt` adds TTY and CI.
165
+ // `--json` must stay machine-readable, `canPrompt` adds TTY and CI.
166
166
  interactive: !cli.json && canPrompt(),
167
167
  });
168
168
  const localTools = toolHandlerMap(codegraphPrep.tools);
@@ -188,7 +188,7 @@ export async function runRemoteReview(cli) {
188
188
  files: built.revision.files,
189
189
  },
190
190
  capabilities: { tools: capabilityTools },
191
- // Only present when this run turned BYOK on; `byokKey` is
191
+ // Only present when this run turned BYOK on, `byokKey` is
192
192
  // known to be set here because of the earlier `byokEnabled` guard.
193
193
  ...(byokEnabled ? { byok: { key: byokKey } } : {}),
194
194
  // The client's one-run instructions, when given. The server applies
@@ -219,7 +219,7 @@ export async function runRemoteReview(cli) {
219
219
  let afterLogSeq = 0;
220
220
  let toolResults = [];
221
221
  let toolCallsRun = 0;
222
- // A trustworthy server drives at most a few tool rounds; cap the total so a
222
+ // A trustworthy server drives at most a few tool rounds. Cap the total so a
223
223
  // malicious one cannot make the client read its tree without limit.
224
224
  const MAX_REMOTE_TOOL_CALLS = 200;
225
225
  const intervalMs = hs.sync.intervalSeconds * 1000;
@@ -322,6 +322,7 @@ export async function runRemoteReview(cli) {
322
322
  coverage: coverageFromResult(payload.result),
323
323
  extensions,
324
324
  intent: intent !== null,
325
+ showReferences: readConfig().repos?.[repo]?.reviewReferences === true,
325
326
  }) +
326
327
  "\n");
327
328
  if (run)
@@ -10,7 +10,7 @@ export declare const REMOTE_SYNC_INTERVAL_SECONDS = 3;
10
10
  * repository's own cap is applied on the server. Guards the body size. */
11
11
  export declare const REMOTE_MAX_SYSTEM_PROMPT_CHARS = 200000;
12
12
  /** SHA-256 of sorted `fixtures/v<N>/*.json` (name + contents, `\r\n` normalized
13
- * to `\n`); bump with schema version. */
13
+ * to `\n`). Bump with schema version. */
14
14
  export declare const REMOTE_FIXTURE_HASH: Record<number, string>;
15
15
  export declare const REMOTE_SYNC_STATUSES: readonly ["queued", "running", "done", "failed", "canceled"];
16
16
  export type RemoteSyncStatus = (typeof REMOTE_SYNC_STATUSES)[number];
@@ -10,7 +10,7 @@ export const REMOTE_SYNC_INTERVAL_SECONDS = 3;
10
10
  * repository's own cap is applied on the server. Guards the body size. */
11
11
  export const REMOTE_MAX_SYSTEM_PROMPT_CHARS = 200_000;
12
12
  /** SHA-256 of sorted `fixtures/v<N>/*.json` (name + contents, `\r\n` normalized
13
- * to `\n`); bump with schema version. */
13
+ * to `\n`). Bump with schema version. */
14
14
  export const REMOTE_FIXTURE_HASH = {
15
15
  1: "71e4e5f8637eab4b53d47817a688812a517310d967abe26aa0d7f4e7d7d65092",
16
16
  };
@@ -14,7 +14,7 @@ export type BoundedBodyResult = {
14
14
  reason: "too_large" | "empty";
15
15
  };
16
16
  /** Reads the raw body, streaming, and refuses once more than `maxBytes` have
17
- * arrived — this holds with no Content-Length (chunked) too. The caller gets
17
+ * arrived, this holds with no Content-Length (chunked) too. The caller gets
18
18
  * the exact bytes, which the webhook HMAC needs. */
19
19
  export declare function readBoundedBytes(request: Request, maxBytes: number): Promise<BoundedBytesResult>;
20
20
  export declare function readBoundedUtf8(request: Request, maxBytes: number): Promise<BoundedBodyResult>;
@@ -1,6 +1,6 @@
1
1
  /** Bounded request body read (bytes, streaming). */
2
2
  /** Reads the raw body, streaming, and refuses once more than `maxBytes` have
3
- * arrived — this holds with no Content-Length (chunked) too. The caller gets
3
+ * arrived, this holds with no Content-Length (chunked) too. The caller gets
4
4
  * the exact bytes, which the webhook HMAC needs. */
5
5
  export async function readBoundedBytes(request, maxBytes) {
6
6
  const lengthHeader = request.headers.get("content-length");
@@ -1,4 +1,4 @@
1
- /** `GET /api/remote/guides?repo=owner/repo` — read a repository's guides with a
1
+ /** `GET /api/remote/guides?repo=owner/repo`, read a repository's guides with a
2
2
  * remote token.
3
3
  *
4
4
  * This is what `view --remote` calls. It is a read-only addition: no existing
@@ -243,7 +243,7 @@ export function validateSubmitRequest(body) {
243
243
  if (typeof tool.name !== "string" || !tool.name) {
244
244
  return bad(`capabilities.tools[${i}].name`, "required");
245
245
  }
246
- // Unknown tools are ignored at runtime; no error here.
246
+ // Unknown tools are ignored at runtime. No error here.
247
247
  if (REMOTE_KNOWN_TOOL_NAMES.has(tool.name) &&
248
248
  tool.version !== undefined &&
249
249
  typeof tool.version !== "string") {
@@ -3,12 +3,12 @@
3
3
  * The same pull request was reviewed twice, the same P2 finding came back
4
4
  * `non-blocking` the first time and `blocking` the second, and the exit code
5
5
  * changed because the model's own label moved. `model` keeps that behavior
6
- * (the model decides) because it is what 0.4.13 shipped; `severity` ignores
6
+ * (the model decides) because it is what 0.4.13 shipped, `severity` ignores
7
7
  * the model's label and uses a fixed threshold, so the same finding set always
8
8
  * yields the same exit code.
9
9
  *
10
10
  * This is the one place that answers "does this finding block". Every review
11
- * path — local, PR, remote and the GitHub App — calls it, so the modes cannot
11
+ * path, local, PR, remote and the GitHub App, calls it, so the modes cannot
12
12
  * drift apart.
13
13
  */
14
14
  export type ReviewBlocking = "model" | "severity";
@@ -17,7 +17,7 @@ export declare const DEFAULT_REVIEW_BLOCKING: ReviewBlocking;
17
17
  * so an unset or mistyped value never silently tightens the rule. */
18
18
  export declare function reviewBlockingFrom(value: unknown): ReviewBlocking;
19
19
  /** One finding, in the shape any of the review paths happens to have. Only
20
- * `severity` is always available; the other two describe the model's own
20
+ * `severity` is always available. The other two describe the model's own
21
21
  * claim, which `severity` mode ignores. */
22
22
  export type BlockingInput = {
23
23
  severity?: string;
@@ -3,12 +3,12 @@
3
3
  * The same pull request was reviewed twice, the same P2 finding came back
4
4
  * `non-blocking` the first time and `blocking` the second, and the exit code
5
5
  * changed because the model's own label moved. `model` keeps that behavior
6
- * (the model decides) because it is what 0.4.13 shipped; `severity` ignores
6
+ * (the model decides) because it is what 0.4.13 shipped, `severity` ignores
7
7
  * the model's label and uses a fixed threshold, so the same finding set always
8
8
  * yields the same exit code.
9
9
  *
10
10
  * This is the one place that answers "does this finding block". Every review
11
- * path — local, PR, remote and the GitHub App — calls it, so the modes cannot
11
+ * path, local, PR, remote and the GitHub App, calls it, so the modes cannot
12
12
  * drift apart.
13
13
  */
14
14
  export const DEFAULT_REVIEW_BLOCKING = "model";
@@ -1,4 +1,5 @@
1
1
  import type { ParsedFinding } from "../pr/findings.ts";
2
+ import type { ResolvedReference } from "./references.ts";
2
3
  import { type Revision, type RevisionFile } from "./revision.ts";
3
4
  export type StoredFinding = {
4
5
  id: string;
@@ -12,6 +13,8 @@ export type StoredFinding = {
12
13
  firstSeenReviewId: string | null;
13
14
  /** What maintainers wrote on the finding's inline thread, oldest first. */
14
15
  replies?: string[];
16
+ /** What the finding rested on when it was first found. */
17
+ references?: ResolvedReference[];
15
18
  };
16
19
  export type CarryPrevious = {
17
20
  files: RevisionFile[];
@@ -41,6 +44,11 @@ export type ResolvedFinding = {
41
44
  severity: string;
42
45
  carriedFromId: string | null;
43
46
  firstSeenReviewId: string | null;
47
+ /** A carried finding keeps what it rested on. */
48
+ references?: ResolvedReference[];
49
+ /** A new or rewritten finding: the ids the answer named, resolved by the
50
+ * caller against `RULES.json`. */
51
+ referenceIds?: string[];
44
52
  };
45
53
  export declare function anchorTextFromPatch(patch: string, from: number, to: number): string | null;
46
54
  export declare function relocate(anchorText: string | null, oldFrom: number, patch: string): {
@@ -48,7 +56,7 @@ export declare function relocate(anchorText: string | null, oldFrom: number, pat
48
56
  to: number;
49
57
  } | null;
50
58
  /** A guide rebuilt after the previous review invalidates that
51
- * review's verdicts, its "unchanged" suppression and its open findings — they
59
+ * review's verdicts, its "unchanged" suppression and its open findings, they
52
60
  * were all judged against the old rules. Such a run starts fresh instead:
53
61
  * every file is scanned again and old findings are no longer carried over.
54
62
  *
@@ -71,7 +71,7 @@ function guideChanged(previous, currentGuideBuiltAt) {
71
71
  return (previous.guideBuiltAt ?? "") !== (currentGuideBuiltAt ?? "");
72
72
  }
73
73
  /** A guide rebuilt after the previous review invalidates that
74
- * review's verdicts, its "unchanged" suppression and its open findings — they
74
+ * review's verdicts, its "unchanged" suppression and its open findings, they
75
75
  * were all judged against the old rules. Such a run starts fresh instead:
76
76
  * every file is scanned again and old findings are no longer carried over.
77
77
  *
@@ -209,7 +209,7 @@ export function buildCarryPromptSection(items, current) {
209
209
  " not. Report every decision in a final section headed",
210
210
  ' exactly "## Previous findings", one line per id, exactly as',
211
211
  ' "- F1: open path:from-to" or "- F1: closed".',
212
- 'Do not repeat an open previous finding under "## Findings"; report there',
212
+ 'Do not repeat an open previous finding under "## Findings". Report there',
213
213
  "only findings from job 1 that are not already covered below.",
214
214
  "",
215
215
  ];
@@ -280,6 +280,7 @@ export function resolveCarryOutcomes(items, current, visiblePaths, verdicts, par
280
280
  anchorText: base.anchorText,
281
281
  severity: base.severity,
282
282
  carriedFromId: base.id,
283
+ ...(base.references ? { references: base.references } : {}),
283
284
  firstSeenReviewId: base.firstSeenReviewId,
284
285
  });
285
286
  continue;
@@ -297,6 +298,7 @@ export function resolveCarryOutcomes(items, current, visiblePaths, verdicts, par
297
298
  anchorText: base.anchorText,
298
299
  severity: base.severity,
299
300
  carriedFromId: base.id,
301
+ ...(base.references ? { references: base.references } : {}),
300
302
  firstSeenReviewId: base.firstSeenReviewId,
301
303
  });
302
304
  continue;
@@ -327,6 +329,7 @@ export function resolveCarryOutcomes(items, current, visiblePaths, verdicts, par
327
329
  : base.anchorText,
328
330
  severity: base.severity,
329
331
  carriedFromId: base.id,
332
+ ...(base.references ? { references: base.references } : {}),
330
333
  firstSeenReviewId: base.firstSeenReviewId,
331
334
  };
332
335
  resolved.push(row);
@@ -353,6 +356,7 @@ export function resolveCarryOutcomes(items, current, visiblePaths, verdicts, par
353
356
  anchorText: anchor,
354
357
  severity: base.severity,
355
358
  carriedFromId: base.id,
359
+ ...(base.references ? { references: base.references } : {}),
356
360
  firstSeenReviewId: base.firstSeenReviewId,
357
361
  };
358
362
  resolved.push(row);
@@ -367,6 +371,9 @@ export function resolveCarryOutcomes(items, current, visiblePaths, verdicts, par
367
371
  overlap.title = finding.heading || finding.path;
368
372
  overlap.lineFrom = finding.from;
369
373
  overlap.lineTo = finding.to;
374
+ // The rewritten text rests on what the new answer named.
375
+ overlap.references = undefined;
376
+ overlap.referenceIds = finding.references ?? [];
370
377
  continue;
371
378
  }
372
379
  resolved.push({
@@ -381,6 +388,7 @@ export function resolveCarryOutcomes(items, current, visiblePaths, verdicts, par
381
388
  severity: finding.severity ?? "P2",
382
389
  carriedFromId: null,
383
390
  firstSeenReviewId: null,
391
+ referenceIds: finding.references ?? [],
384
392
  });
385
393
  }
386
394
  return resolved;
@@ -62,6 +62,7 @@ export function plantumlServerProblem(value) {
62
62
  // The link is posted as Markdown, so a path that can end it early or be
63
63
  // rewritten as prose would break every diagram.
64
64
  if (/\s/.test(value) || /[()[\]<>`\\;"]/.test(url.pathname)) {
65
+ // punctuation: code, the message names the semicolon character the path check rejects
65
66
  return 'must not contain spaces or any of ( ) [ ] < > ` \\ ; " in its path';
66
67
  }
67
68
  return null;
@@ -253,13 +254,13 @@ const PLANTUML_GUIDANCE = `PlantUML selection and minimal syntax:
253
254
  Write standard PlantUML source in a fenced code block tagged plantuml, from
254
255
  @startuml to @enduml. Do not write an image, an image link, a server URL, or
255
256
  any other diagram language. Our code decides how the source is shown.
256
- sequence diagram = ordered calls, webhooks, retries, responses, and timing;
257
- activity diagram = decisions, branches, pipelines, and fallback paths;
257
+ sequence diagram = ordered calls, webhooks, retries, responses, and timing.
258
+ activity diagram = decisions, branches, pipelines, and fallback paths.
258
259
  class diagram = classes, interfaces, types, inheritance, composition, and
259
- database entities;
260
- state diagram = lifecycle and state transitions;
261
- component diagram = services, modules, boundaries, and integrations;
262
- deployment diagram = containers, storage, and deployment topology;
260
+ database entities.
261
+ state diagram = lifecycle and state transitions.
262
+ component diagram = services, modules, boundaries, and integrations.
263
+ deployment diagram = containers, storage, and deployment topology.
263
264
  use case diagram = actors and system capabilities.
264
265
  Use the smallest type that matches the evidence. Keep labels short.`;
265
266
  /** The system prompt's diagram section for a PlantUML runtime, or `undefined`
@@ -1,4 +1,4 @@
1
- /** Review prompt, tool loop, and improvement passes — PR adapter calls this
1
+ /** Review prompt, tool loop, and improvement passes, PR adapter calls this
2
2
  * after building a `Revision` and carry-over input. */
3
3
  import type { GitHubClient, Options } from "../types.ts";
4
4
  import type { Snapshot } from "../pr/snapshot.ts";
@@ -56,7 +56,7 @@ export async function loadGuides(repo) {
56
56
  guideBuiltAt = getRepo(repo)?.knowledge_built_at ?? null;
57
57
  }
58
58
  catch {
59
- // Local CLI review without `serve` — guides still load from disk.
59
+ // Local CLI review without `serve`, guides still load from disk.
60
60
  }
61
61
  // With no `repos` row, the files are the only evidence of when the guide
62
62
  // was built. Without this a local review always says `guide unknown` and
@@ -0,0 +1,68 @@
1
+ /** What a review finding rests on.
2
+ *
3
+ * The review answer names ids only: `R12` and `I3` from the guide and
4
+ * instruction lines, `codebase:<section>` for a CODEBASE CONVENTIONS section,
5
+ * and `system` for the review instructions themselves. No pull request number
6
+ * or date ever enters the prompt. Code turns each id into a reference from
7
+ * `RULES.json` at review time, and the result is stored with the finding, so
8
+ * a later `sync` never changes what an old review cited. */
9
+ import { type RulesFile } from "../knowledge/rules.ts";
10
+ /** What references resolve against, from the guides a review was given. */
11
+ export type ReferenceContext = {
12
+ rules: RulesFile | null;
13
+ codebase: string;
14
+ };
15
+ export type ReferenceSource = {
16
+ pr: number;
17
+ url?: string;
18
+ mergedAt?: string;
19
+ } | {
20
+ path: string;
21
+ line: number;
22
+ url?: string;
23
+ };
24
+ export type ResolvedReference = {
25
+ kind: "rule";
26
+ id: string;
27
+ sources: ReferenceSource[];
28
+ } | {
29
+ kind: "instruction";
30
+ id: string;
31
+ sources: ReferenceSource[];
32
+ } | {
33
+ kind: "codebase";
34
+ section?: string;
35
+ } | {
36
+ kind: "system";
37
+ };
38
+ /** The ids as the model wrote them, one per entry, trimmed. */
39
+ export declare function referenceIds(value: unknown): string[];
40
+ /** Turns the ids of one finding into references. An id that is not in
41
+ * `RULES.json` is dropped, so a made-up id never shows. A finding that names
42
+ * nothing usable rests on the review instructions: `system`. */
43
+ export declare function resolveReferences(ids: string[], input: {
44
+ repo: string;
45
+ rules: RulesFile | null;
46
+ codebase: string;
47
+ }): ResolvedReference[];
48
+ /** One reference as a reader sees it:
49
+ * `Rules-12 · #212, #340 · 2026-03`, `Instructions-3 · AGENTS.md:14`,
50
+ * `System Prompt`, `Codebase · Tests`. */
51
+ export declare function referenceLine(reference: ResolvedReference, links?: boolean): string;
52
+ /** The collapsed block under a finding, or `""` when there is nothing. */
53
+ export declare function referencesBlock(references: ResolvedReference[]): string;
54
+ /** Reads a stored `references_json` value. Anything that does not fit is
55
+ * skipped, so a bad row shows no references rather than failing a page. */
56
+ export declare function parseStoredReferences(text: string | null | undefined): ResolvedReference[];
57
+ /** The `references_json` to store for a finding: a carried one keeps what it
58
+ * rested on, a new one resolves the ids its answer named. */
59
+ export declare function referencesJson(finding: {
60
+ references?: ResolvedReference[];
61
+ referenceIds?: string[];
62
+ }, repo: string, context: ReferenceContext | undefined): string;
63
+ /** Gives every row that has no references yet the ones its ids resolve to,
64
+ * so every output (stored row, JSON, carry file) carries the same list. */
65
+ export declare function withResolvedReferences<T extends {
66
+ references?: ResolvedReference[];
67
+ referenceIds?: string[];
68
+ }>(rows: T[], repo: string, context: ReferenceContext | undefined): T[];