co-maintainer 0.7.2 → 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 (59) hide show
  1. package/dist/package.json +1 -1
  2. package/dist/src/cli/command_json.d.ts +3 -1
  3. package/dist/src/cli/command_json.js +1 -0
  4. package/dist/src/cli/commands/review.js +2 -0
  5. package/dist/src/cli/commands/set.js +19 -2
  6. package/dist/src/cli/pr_carry.d.ts +2 -0
  7. package/dist/src/cli/pr_carry.js +2 -2
  8. package/dist/src/cli/review_carry.d.ts +3 -1
  9. package/dist/src/cli/review_carry.js +5 -3
  10. package/dist/src/cli/review_result.d.ts +10 -1
  11. package/dist/src/cli/review_result.js +14 -1
  12. package/dist/src/config.d.ts +9 -0
  13. package/dist/src/github/collect.d.ts +7 -1
  14. package/dist/src/github/collect.js +41 -16
  15. package/dist/src/knowledge/guide.d.ts +24 -1
  16. package/dist/src/knowledge/guide.js +39 -9
  17. package/dist/src/knowledge/guide_ids.d.ts +9 -0
  18. package/dist/src/knowledge/guide_ids.js +26 -7
  19. package/dist/src/knowledge/rule_changes.d.ts +18 -0
  20. package/dist/src/knowledge/rule_changes.js +41 -0
  21. package/dist/src/knowledge/rules.d.ts +11 -0
  22. package/dist/src/knowledge/rules.js +10 -1
  23. package/dist/src/knowledge/stable_ids.d.ts +29 -0
  24. package/dist/src/knowledge/stable_ids.js +90 -0
  25. package/dist/src/knowledge/synthesis.d.ts +13 -1
  26. package/dist/src/knowledge/synthesis.js +89 -21
  27. package/dist/src/knowledge/types.d.ts +16 -0
  28. package/dist/src/local/review_local.js +3 -2
  29. package/dist/src/pr/findings.d.ts +3 -0
  30. package/dist/src/pr/findings.js +21 -1
  31. package/dist/src/pr/findings_json.d.ts +1 -1
  32. package/dist/src/pr/findings_json.js +14 -1
  33. package/dist/src/pr/reviewer.d.ts +4 -0
  34. package/dist/src/pr/reviewer.js +2 -0
  35. package/dist/src/remote/client.js +1 -0
  36. package/dist/src/review/carry_over.d.ts +8 -0
  37. package/dist/src/review/carry_over.js +8 -0
  38. package/dist/src/review/references.d.ts +68 -0
  39. package/dist/src/review/references.js +176 -0
  40. package/dist/src/server/pages/pr.js +2 -0
  41. package/dist/src/server/pages/references.d.ts +2 -0
  42. package/dist/src/server/pages/references.js +55 -0
  43. package/dist/src/server/pages/repo.js +26 -0
  44. package/dist/src/services/dashboard.d.ts +2 -0
  45. package/dist/src/services/dashboard.js +2 -0
  46. package/dist/src/services/push_review.js +4 -1
  47. package/dist/src/services/remote_review.js +5 -2
  48. package/dist/src/services/review.js +35 -8
  49. package/dist/src/services/rules_build.d.ts +20 -1
  50. package/dist/src/services/rules_build.js +85 -6
  51. package/dist/src/services/setup.js +27 -2
  52. package/dist/src/store/findings.d.ts +2 -0
  53. package/dist/src/store/findings.js +3 -3
  54. package/dist/src/store/migrations.js +17 -0
  55. package/dist/src/store/rows.d.ts +2 -0
  56. package/dist/src/store/rule_events.d.ts +15 -0
  57. package/dist/src/store/rule_events.js +20 -0
  58. package/dist/src/types.d.ts +4 -0
  59. package/package.json +1 -1
@@ -1,3 +1,4 @@
1
+ import { referenceIds } from "../review/references.js";
1
2
  const SEVERITIES = ["P0", "P1", "P2", "P3"];
2
3
  /** OpenRouter `response_format` for a review. Providers that ignore it still
3
4
  * get the prompt's instruction to return a fenced JSON block. */
@@ -23,6 +24,7 @@ export const FINDINGS_JSON_SCHEMA = {
23
24
  title: { type: "string" },
24
25
  body: { type: "string" },
25
26
  suggestion: { type: "string" },
27
+ references: { type: "array", items: { type: "string" } },
26
28
  },
27
29
  required: ["severity", "path", "lineFrom", "title", "body"],
28
30
  },
@@ -48,7 +50,7 @@ export const FINDINGS_JSON_SCHEMA = {
48
50
  };
49
51
  /** The prompt's contract, kept next to the schema so the two cannot drift. */
50
52
  export const FINDINGS_JSON_INSTRUCTIONS = `Return a single JSON object, and nothing else, with this shape:
51
- {"findings":[{"severity":"P1","blocking":true,"path":"src/a.ts","lineFrom":42,"lineTo":42,"symbol":"helper()","title":"The helper ignores its argument","body":"One sentence on what is wrong and its impact, then a short evidence paragraph.","suggestion":"the exact replacement lines, or omit this field"}],"previousFindings":[{"id":"F1","state":"open"}]}
53
+ {"findings":[{"severity":"P1","blocking":true,"path":"src/a.ts","lineFrom":42,"lineTo":42,"symbol":"helper()","title":"The helper ignores its argument","body":"One sentence on what is wrong and its impact, then a short evidence paragraph.","suggestion":"the exact replacement lines, or omit this field","references":["R12"]}],"previousFindings":[{"id":"F1","state":"open"}]}
52
54
 
53
55
  Rules for the JSON:
54
56
  - "severity" is exactly one of P0, P1, P2, P3. "blocking" is true or false.
@@ -64,6 +66,10 @@ Rules for the JSON:
64
66
  hunk of the same file. Omit it otherwise. Never wrap it in a code fence.
65
67
  - When a fix needs removed lines, another file, or more than one hunk, omit
66
68
  "suggestion".
69
+ - "references" lists what the finding rests on: the bracketed id at the end
70
+ of a guide or repository instruction line (such as R12 or I3),
71
+ "codebase:<section title>" for a CODEBASE CONVENTIONS section, or "system"
72
+ when it rests only on these review instructions. Name only ids you used.
67
73
  - Return every independently actionable finding, including none: use
68
74
  {"findings":[]} when the change is clean. Never invent a finding to fill the
69
75
  array.`;
@@ -125,9 +131,16 @@ function findingMarkdown(raw) {
125
131
  const lineTo = asNumber(raw.lineTo) ?? lineFrom;
126
132
  const span = lineTo === lineFrom ? `${lineFrom}` : `${lineFrom}-${lineTo}`;
127
133
  const suggestion = asSource(raw.suggestion);
134
+ const references = referenceIds(raw.references)
135
+ // One line per finding: a comma or a newline in an id would split it.
136
+ .map((id) => id.replace(/[,\r\n]+/g, " ").trim())
137
+ .filter(Boolean);
128
138
  const lines = [
129
139
  `### [${level} · ${impact}] \`${path}\`${symbol ? `: \`${symbol}\`` : ""}`,
130
140
  `Location: \`${path}:${span}\``,
141
+ // Read back by `parseFindings` and never shown as is: code turns the ids
142
+ // into references.
143
+ ...(references.length ? [`References: ${references.join(", ")}`] : []),
131
144
  "",
132
145
  asText(raw.body),
133
146
  ];
@@ -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`. */
@@ -451,6 +451,7 @@ ${reviewText}`,
451
451
  text: `${severitySection()}\n${renderDiagrams(reviewText, options)}`,
452
452
  visiblePaths: prepared.seenPaths,
453
453
  guideBuiltAt: guides.guideBuiltAt,
454
+ referenceContext: { rules: guides.rules, codebase: guides.codebase },
454
455
  codegraphState: !options.useCodegraph
455
456
  ? "disabled"
456
457
  : codegraphTools.length > 0
@@ -572,6 +573,7 @@ ${reviewText}`,
572
573
  text: `${severitySection()}\n${renderDiagrams(reviewText, options)}`,
573
574
  visiblePaths: prepared.seenPaths,
574
575
  guideBuiltAt: guides.guideBuiltAt,
576
+ referenceContext: { rules: guides.rules, codebase: guides.codebase },
575
577
  codegraphState,
576
578
  coverage: prepared.coverage,
577
579
  warnings: prepared.warnings,
@@ -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)
@@ -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): {
@@ -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;
@@ -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[];
@@ -0,0 +1,176 @@
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 { RULE_ID } from "../knowledge/rules.js";
10
+ /** The ids as the model wrote them, one per entry, trimmed. */
11
+ export function referenceIds(value) {
12
+ if (!Array.isArray(value))
13
+ return [];
14
+ return [
15
+ ...new Set(value
16
+ .map((item) => (typeof item === "string" ? item.trim() : ""))
17
+ .filter(Boolean)),
18
+ ];
19
+ }
20
+ /** The `## ` section titles of CODEBASE.md, so a made-up section is not
21
+ * shown as if it existed. */
22
+ function codebaseSections(codebase) {
23
+ return new Set([...codebase.matchAll(/^##\s+(.+?)\s*$/gm)].map((match) => match[1].toLowerCase()));
24
+ }
25
+ function instructionUrl(repo, commit, path, line) {
26
+ if (!commit || !/^[\w.-]+\/[\w.-]+$/.test(repo))
27
+ return undefined;
28
+ // A space, `#` or `?` in a path would end the URL early, and a space or a
29
+ // parenthesis would break the Markdown link around it.
30
+ const encoded = path
31
+ .split("/")
32
+ .map((segment) => encodeURIComponent(segment).replace(/[()]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`))
33
+ .join("/");
34
+ return `https://github.com/${repo}/blob/${commit}/${encoded}#L${line}`;
35
+ }
36
+ /** Turns the ids of one finding into references. An id that is not in
37
+ * `RULES.json` is dropped, so a made-up id never shows. A finding that names
38
+ * nothing usable rests on the review instructions: `system`. */
39
+ export function resolveReferences(ids, input) {
40
+ const sections = codebaseSections(input.codebase);
41
+ const resolved = [];
42
+ const seen = new Set();
43
+ for (const raw of ids) {
44
+ const id = raw.replace(/^\[|\]$/g, "").trim();
45
+ const lower = id.toLowerCase();
46
+ if (lower === "system") {
47
+ if (!seen.has("system"))
48
+ resolved.push({ kind: "system" });
49
+ seen.add("system");
50
+ continue;
51
+ }
52
+ if (lower === "codebase" || lower.startsWith("codebase:")) {
53
+ const name = id.slice("codebase".length).replace(/^:/, "").trim();
54
+ const section = name && sections.has(name.toLowerCase()) ? name : undefined;
55
+ const key = `codebase:${section ?? ""}`;
56
+ if (!seen.has(key))
57
+ resolved.push({ kind: "codebase", section });
58
+ seen.add(key);
59
+ continue;
60
+ }
61
+ const upper = id.toUpperCase();
62
+ if (!RULE_ID.test(upper) || seen.has(upper))
63
+ continue;
64
+ const entry = input.rules?.rules[upper];
65
+ if (!entry)
66
+ continue;
67
+ seen.add(upper);
68
+ const sources = entry.sources.map((source) => "pr" in source
69
+ ? {
70
+ pr: source.pr,
71
+ ...(source.mergedAt ? { mergedAt: source.mergedAt } : {}),
72
+ ...(source.url ? { url: source.url } : {}),
73
+ }
74
+ : {
75
+ path: source.path,
76
+ line: source.line,
77
+ ...(() => {
78
+ const url = instructionUrl(input.repo, entry.commit, source.path, source.line);
79
+ return url ? { url } : {};
80
+ })(),
81
+ });
82
+ resolved.push({
83
+ kind: upper.startsWith("R") ? "rule" : "instruction",
84
+ id: upper,
85
+ sources,
86
+ });
87
+ }
88
+ return resolved.length ? resolved : [{ kind: "system" }];
89
+ }
90
+ function linkWith(links) {
91
+ return (text, url) => links && url ? `[${text}](${url})` : text;
92
+ }
93
+ /** One reference as a reader sees it:
94
+ * `Rules-12 · #212, #340 · 2026-03`, `Instructions-3 · AGENTS.md:14`,
95
+ * `System Prompt`, `Codebase · Tests`. */
96
+ export function referenceLine(reference, links = true) {
97
+ const link = linkWith(links);
98
+ switch (reference.kind) {
99
+ case "system":
100
+ return "System Prompt";
101
+ case "codebase":
102
+ return reference.section ? `Codebase · ${reference.section}` : "Codebase";
103
+ case "rule": {
104
+ const prs = reference.sources.flatMap((source) => "pr" in source ? [link(`#${source.pr}`, source.url)] : []);
105
+ const dates = reference.sources
106
+ .flatMap((source) => "pr" in source && source.mergedAt ? [source.mergedAt] : [])
107
+ .sort();
108
+ const newest = dates.at(-1)?.slice(0, 7);
109
+ return [`Rules-${reference.id.slice(1)}`, prs.join(", "), newest]
110
+ .filter(Boolean)
111
+ .join(" · ");
112
+ }
113
+ case "instruction": {
114
+ const lines = reference.sources.flatMap((source) => "path" in source
115
+ ? [link(`${source.path}:${source.line}`, source.url)]
116
+ : []);
117
+ return [`Instructions-${reference.id.slice(1)}`, lines.join(", ")]
118
+ .filter(Boolean)
119
+ .join(" · ");
120
+ }
121
+ }
122
+ }
123
+ /** The collapsed block under a finding, or `""` when there is nothing. */
124
+ export function referencesBlock(references) {
125
+ if (references.length === 0)
126
+ return "";
127
+ return [
128
+ `<details><summary>References (${references.length})</summary>`,
129
+ "",
130
+ ...references.map((reference) => `- ${referenceLine(reference)}`),
131
+ "",
132
+ "</details>",
133
+ ].join("\n");
134
+ }
135
+ /** Reads a stored `references_json` value. Anything that does not fit is
136
+ * skipped, so a bad row shows no references rather than failing a page. */
137
+ export function parseStoredReferences(text) {
138
+ if (!text)
139
+ return [];
140
+ try {
141
+ const value = JSON.parse(text);
142
+ if (!Array.isArray(value))
143
+ return [];
144
+ return value.filter((item) => !!item &&
145
+ typeof item === "object" &&
146
+ ["rule", "instruction", "codebase", "system"].includes(item.kind));
147
+ }
148
+ catch {
149
+ return [];
150
+ }
151
+ }
152
+ /** The `references_json` to store for a finding: a carried one keeps what it
153
+ * rested on, a new one resolves the ids its answer named. */
154
+ export function referencesJson(finding, repo, context) {
155
+ if (finding.references)
156
+ return JSON.stringify(finding.references);
157
+ return JSON.stringify(resolveReferences(finding.referenceIds ?? [], {
158
+ repo,
159
+ rules: context?.rules ?? null,
160
+ codebase: context?.codebase ?? "",
161
+ }));
162
+ }
163
+ /** Gives every row that has no references yet the ones its ids resolve to,
164
+ * so every output (stored row, JSON, carry file) carries the same list. */
165
+ export function withResolvedReferences(rows, repo, context) {
166
+ for (const row of rows) {
167
+ if (row.references)
168
+ continue;
169
+ row.references = resolveReferences(row.referenceIds ?? [], {
170
+ repo,
171
+ rules: context?.rules ?? null,
172
+ codebase: context?.codebase ?? "",
173
+ });
174
+ }
175
+ return rows;
176
+ }
@@ -1,6 +1,7 @@
1
1
  import { empty, html, layout, markdown, repoTabs, skSlot, text, when, } from "./layout.js";
2
2
  import { formatCost, formatCostTotal, totalOfRows } from "./cost.js";
3
3
  import { extensionCostNote, renderExtensionResults } from "./extensions.js";
4
+ import { referencesHtml } from "./references.js";
4
5
  export function renderPr(username, fullName, data) {
5
6
  const n = data.prNumber;
6
7
  const totalCost = totalOfRows(data.reviews);
@@ -35,6 +36,7 @@ export function renderPr(username, fullName, data) {
35
36
  : ""}</div>
36
37
  <div class="mono muted" style="font-size:13px;margin-bottom:8px">${text(finding.path ? `${finding.path}:${finding.line_from ?? ""}` : "")}</div>
37
38
  ${markdown(finding.body_md)}
39
+ ${referencesHtml(finding.references_json)}
38
40
  </div>`)
39
41
  .join("")}
40
42
  </div>`)
@@ -0,0 +1,2 @@
1
+ /** The collapsed block, or `""` for a finding stored before references. */
2
+ export declare function referencesHtml(stored: string | null | undefined): string;
@@ -0,0 +1,55 @@
1
+ /** A finding's references on the dashboard: the same collapsed list a review
2
+ * comment shows when the repository turns references on, shown here always. */
3
+ import { parseStoredReferences, } from "../../review/references.js";
4
+ import { text } from "./layout.js";
5
+ /** Only GitHub links are made clickable. Anything else is plain text. */
6
+ function linked(label, url) {
7
+ return url && url.startsWith("https://github.com/")
8
+ ? `<a href="${text(url)}" target="_blank" rel="noopener noreferrer">${text(label)}</a>`
9
+ : text(label);
10
+ }
11
+ function sourceLinks(sources) {
12
+ return sources
13
+ .map((source) => "pr" in source
14
+ ? linked(`#${source.pr}`, source.url)
15
+ : linked(`${source.path}:${source.line}`, source.url))
16
+ .join(", ");
17
+ }
18
+ function referenceItem(reference) {
19
+ switch (reference.kind) {
20
+ case "system":
21
+ return text("System Prompt");
22
+ case "codebase":
23
+ return text(reference.section ? `Codebase · ${reference.section}` : "Codebase");
24
+ case "rule": {
25
+ const newest = reference.sources
26
+ .flatMap((source) => "pr" in source && source.mergedAt ? [source.mergedAt] : [])
27
+ .sort()
28
+ .at(-1)
29
+ ?.slice(0, 7);
30
+ return [
31
+ text(`Rules-${reference.id.slice(1)}`),
32
+ sourceLinks(reference.sources),
33
+ newest ? text(newest) : "",
34
+ ]
35
+ .filter(Boolean)
36
+ .join(" · ");
37
+ }
38
+ case "instruction":
39
+ return [
40
+ text(`Instructions-${reference.id.slice(1)}`),
41
+ sourceLinks(reference.sources),
42
+ ]
43
+ .filter(Boolean)
44
+ .join(" · ");
45
+ }
46
+ }
47
+ /** The collapsed block, or `""` for a finding stored before references. */
48
+ export function referencesHtml(stored) {
49
+ const references = parseStoredReferences(stored);
50
+ if (references.length === 0)
51
+ return "";
52
+ return `<details style="margin-top:8px"><summary class="muted" style="font-size:13px;cursor:pointer">${text(`References (${references.length})`)}</summary><ul style="margin:6px 0 0 18px;font-size:13px">${references
53
+ .map((reference) => `<li>${referenceItem(reference)}</li>`)
54
+ .join("")}</ul></details>`;
55
+ }
@@ -1,4 +1,5 @@
1
1
  import { capped, empty, html, layout, repoTabs, skSlot, text, when, } from "./layout.js";
2
+ import { contradictionLine } from "../../knowledge/rule_changes.js";
2
3
  import { badge, crumb, dl, icon, pageHeader, section, statCard, } from "./ui.js";
3
4
  import { formatCostTotal } from "./cost.js";
4
5
  import { COMPARE_FILE_CAP, MAX_COMMITS_COUNTED } from "../../services/drift.js";
@@ -136,6 +137,7 @@ commitWatch = "") {
136
137
  action: `<a class="btn gh sm" href="/repos/${text(name)}/settings">Change</a>`,
137
138
  })}</div>
138
139
  </div>
140
+ ${ruleEventsCard(data.ruleEvents)}
139
141
  ${commitWatch}
140
142
  </div>
141
143
  <script>
@@ -147,3 +149,27 @@ if (remake) remake.addEventListener("click", function() {
147
149
  </script>`,
148
150
  }));
149
151
  }
152
+ /** Guide rules a newer rule went against, newest first, from `sync`. Left
153
+ * out when there are none. */
154
+ function ruleEventsCard(events) {
155
+ if (events.length === 0)
156
+ return "";
157
+ const items = events.map((event) => {
158
+ let detail = {};
159
+ try {
160
+ detail = JSON.parse(event.detail_json);
161
+ }
162
+ catch {
163
+ // A bad row still shows its ids.
164
+ }
165
+ const line = contradictionLine({
166
+ id: event.rule_id,
167
+ by: event.by_rule_id ?? "",
168
+ sources: Array.isArray(detail.sources) ? detail.sources : [],
169
+ newest: typeof detail.newest === "string" ? detail.newest : "",
170
+ dropped: detail.dropped === true,
171
+ });
172
+ return `<li>${text(line)} <span class="muted" style="font-size:13px">${when(event.at)}</span></li>`;
173
+ });
174
+ return `<div class="card">${section(`<ul style="margin:0 0 0 18px">${items.join("")}</ul>`, { title: "Guide rules that changed direction" })}</div>`;
175
+ }
@@ -100,6 +100,7 @@ export declare function repoOverview(fullName: string): {
100
100
  note_comment_id: string | null;
101
101
  }[];
102
102
  latestJob: JobRow | undefined;
103
+ ruleEvents: import("../store/rule_events.ts").RuleEventRow[];
103
104
  };
104
105
  export declare function repoRemoteReviews(fullName: string, limit?: number): {
105
106
  items: ReviewRow[];
@@ -178,6 +179,7 @@ export declare function prDetail(fullName: string, prNumber: number): {
178
179
  state: string;
179
180
  carried_from_finding_id: string | null;
180
181
  close_reason: string | null;
182
+ references_json: string;
181
183
  }[];
182
184
  extensions: import("../extensions/report.ts").ExtensionReport;
183
185
  id: string;
@@ -1,4 +1,5 @@
1
1
  /** Read models for dashboard pages and the JSON APIs that mirror them. */
2
+ import { listRuleEvents } from "../store/rule_events.js";
2
3
  import { reposDir } from "../config.js";
3
4
  import { getDrift } from "../store/drift.js";
4
5
  import { refreshDrift } from "./drift.js";
@@ -109,6 +110,7 @@ export function repoOverview(fullName) {
109
110
  severities: listFindingsForReview(review.id).map((f) => f.severity),
110
111
  })),
111
112
  latestJob: latestSetupJob(fullName),
113
+ ruleEvents: listRuleEvents(fullName, 10),
112
114
  };
113
115
  }
114
116
  export function repoRemoteReviews(fullName, limit = 30) {
@@ -11,6 +11,7 @@
11
11
  *
12
12
  * Issues need the App. Without it a push review still runs and reports to
13
13
  * CI, but opens, comments on and closes nothing. */
14
+ import { withResolvedReferences } from "../review/references.js";
14
15
  import { parseFindings } from "../pr/findings.js";
15
16
  import { githubFileToRevisionFile } from "../pr/github_revision.js";
16
17
  import { reviewWorkspaceRevision } from "../pr/reviewer.js";
@@ -400,6 +401,7 @@ function resolvedNew(parsed, revision) {
400
401
  severity: finding.severity ?? "P2",
401
402
  carriedFromId: null,
402
403
  firstSeenReviewId: null,
404
+ referenceIds: finding.references ?? [],
403
405
  };
404
406
  });
405
407
  }
@@ -676,7 +678,7 @@ async function runPushReview(job, log, signal) {
676
678
  return;
677
679
  const text = response?.text ?? "";
678
680
  const verdicts = new Map(parsePreviousVerdicts(text).map((v) => [v.id, v]));
679
- const found = sortResolvedFindings(resolvedNew(parseFindings(text), revision));
681
+ const found = sortResolvedFindings(withResolvedReferences(resolvedNew(parseFindings(text), revision), job.repo, response?.referenceContext));
680
682
  const row = getRepo(job.repo);
681
683
  const { report, activity } = client
682
684
  ? await applyIssues({
@@ -715,6 +717,7 @@ async function runPushReview(job, log, signal) {
715
717
  bodyMd: finding.bodyMd,
716
718
  anchorText: finding.anchorText,
717
719
  state: "new",
720
+ referencesJson: JSON.stringify(finding.references ?? []),
718
721
  });
719
722
  }
720
723
  const blockingMode = reviewBlockingFrom(options.reviewBlocking);
@@ -1,4 +1,5 @@
1
1
  import { VERSION } from "../version.js";
2
+ import { parseStoredReferences, withResolvedReferences, } from "../review/references.js";
2
3
  import { CliError } from "../cli/error.js";
3
4
  import { resolvedFromFirstReview, reviewCoverageFields, sortResolvedFindings, summaryCounts, toJsonFinding, } from "../cli/review_result.js";
4
5
  import { parseFindings } from "../pr/findings.js";
@@ -345,6 +346,7 @@ export function registerRemoteReviewHandler() {
345
346
  title: row.title,
346
347
  bodyMd: row.body_md,
347
348
  anchorText: row.anchor_text,
349
+ references: parseStoredReferences(row.references_json),
348
350
  severity: row.severity,
349
351
  firstSeenReviewId: row.first_seen_review_id ?? subjectRevision.review_id,
350
352
  })),
@@ -385,9 +387,9 @@ export function registerRemoteReviewHandler() {
385
387
  // findings, as a local review does. Reading only the new ones dropped
386
388
  // a finding the model kept open, for good.
387
389
  const visible = new Set(result.visiblePaths);
388
- const findings = sortResolvedFindings(previous
390
+ const findings = sortResolvedFindings(withResolvedReferences(previous
389
391
  ? resolveCarryOutcomes(classifyCarryItems(previous, revision, visible, result.guideBuiltAt), revision, visible, parsePreviousVerdicts(result.text), parsed)
390
- : resolvedFromFirstReview(parsed, filesByPath));
392
+ : resolvedFromFirstReview(parsed, filesByPath), options.repo, result.referenceContext));
391
393
  const durationMs = Math.round(performance.now() - started);
392
394
  const blockingMode = reviewBlockingFrom(options.reviewBlocking);
393
395
  // The plan ran here, on the patches the client submitted, so the
@@ -453,6 +455,7 @@ export function registerRemoteReviewHandler() {
453
455
  anchorText: row.anchorText,
454
456
  state: row.state,
455
457
  closeReason: row.closeReason ?? null,
458
+ referencesJson: JSON.stringify(row.references ?? []),
456
459
  });
457
460
  }
458
461
  }