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,5 +1,5 @@
1
1
  /** `co-maintainer view`: print the guides co-maintainer already generated.
2
- * Read-only — the counterpart to `config` for the generated
2
+ * Read-only, the counterpart to `config` for the generated
3
3
  * knowledge rather than the settings.
4
4
  *
5
5
  * Two sources, one presentation: the guide directory on this machine,
@@ -8,7 +8,7 @@
8
8
  * and the every-guide headers are all rendered by the same code.
9
9
  *
10
10
  * Naming: the guide kinds are `skill`, `codebase`,
11
- * `review-guide`, `detailed-guide`; `--list` and the headers show the real
11
+ * `review-guide`, `detailed-guide`, `--list` and the headers show the real
12
12
  * file names, and a kind name is accepted too so a user never has to type
13
13
  * `PR_REVIEW_GUIDE.md` unless they want to. */
14
14
  import { readConfig, reposDir } from "../../config.js";
@@ -42,5 +42,5 @@ export declare function networkFailure(url: string, error: unknown): CliError;
42
42
  * and Node's own text is only `terminated`, which says neither. */
43
43
  export declare function connectionCut(url: string, error: unknown): CliError;
44
44
  /** Reads a response body. fetch rejects with a `TypeError` when the
45
- * connection closes mid-body; that becomes {@link connectionCut}. */
45
+ * connection closes mid-body. That becomes {@link connectionCut}. */
46
46
  export declare function readBody(url: string, response: Response): Promise<string>;
@@ -74,7 +74,7 @@ export function connectionCut(url, error) {
74
74
  return new CliError("connection_cut", `${hostOf(url)} closed the connection before the answer was complete${detail ? ` (${detail}).` : "."}`, "The request reached the provider and the answer was cut off. Run the command again.", EXIT_RUNTIME);
75
75
  }
76
76
  /** Reads a response body. fetch rejects with a `TypeError` when the
77
- * connection closes mid-body; that becomes {@link connectionCut}. */
77
+ * connection closes mid-body. That becomes {@link connectionCut}. */
78
78
  export async function readBody(url, response) {
79
79
  try {
80
80
  return await response.text();
@@ -1,4 +1,5 @@
1
1
  import type { GitHubClient, Options } from "../types.ts";
2
+ import type { ReferenceContext } from "../review/references.ts";
2
3
  import { type ResolvedFinding } from "../review/carry_over.ts";
3
4
  import type { ReviewExtras } from "../pr/reviewer.ts";
4
5
  import type { ReviewWarning } from "./review_result.ts";
@@ -6,6 +7,7 @@ type EngineAnswer = {
6
7
  text: string;
7
8
  visiblePaths: string[];
8
9
  guideBuiltAt: string | null;
10
+ referenceContext?: ReferenceContext;
9
11
  };
10
12
  /** What a CLI pull request review needs around the engine call. `extras` goes
11
13
  * to `reviewPullRequest` as it is, `finish` turns its answer into findings and
@@ -74,7 +74,7 @@ export async function startPrCarry(client, options, fresh, log = () => { }) {
74
74
  description: "",
75
75
  baseLabel: "",
76
76
  producer: "github",
77
- }, response).resolved,
77
+ }, response, repo).resolved,
78
78
  };
79
79
  }
80
80
  const guides = await loadGuides(repo);
@@ -105,7 +105,7 @@ export async function startPrCarry(client, options, fresh, log = () => { }) {
105
105
  extras: { ...run.extras, prefetched },
106
106
  warnings,
107
107
  finish: async (response) => {
108
- const { resolved, visiblePaths } = finishCarryRun(run, current, response);
108
+ const { resolved, visiblePaths } = finishCarryRun(run, current, response, repo);
109
109
  try {
110
110
  await savePrCarry({
111
111
  subjectId: prSubjectId(repo, prNumber),
@@ -1,4 +1,4 @@
1
- /** Free-text question; empty input yields the fallback (or ""). */
1
+ /** Free-text question. Empty input yields the fallback (or ""). */
2
2
  export declare function askLine(label: string, fallback?: string): Promise<string>;
3
- /** Yes/no question; anything but `y`/`yes` is a no. */
3
+ /** Yes/no question. Anything but `y`/`yes` is a no. */
4
4
  export declare function askConfirm(question: string): Promise<boolean>;
@@ -33,7 +33,7 @@ async function ask(question) {
33
33
  resolve(value);
34
34
  };
35
35
  // `question` rejects when stdin closes mid-prompt (Ctrl-D, a detached
36
- // pipeline, a killed parent); treat that as "no answer" too.
36
+ // pipeline, a killed parent). Treat that as "no answer" too.
37
37
  void rl.question(question).then(done, () => done(""));
38
38
  rl.once("close", () => done(""));
39
39
  process.stdin.once("end", () => done(""));
@@ -58,13 +58,13 @@ function raiseInterrupt() {
58
58
  else
59
59
  process.kill(process.pid, "SIGINT");
60
60
  }
61
- /** Free-text question; empty input yields the fallback (or ""). */
61
+ /** Free-text question. Empty input yields the fallback (or ""). */
62
62
  export async function askLine(label, fallback) {
63
63
  const suffix = fallback ? ` [${fallback}]` : "";
64
64
  const answer = await ask(`${label}${suffix}:`);
65
65
  return answer || fallback || "";
66
66
  }
67
- /** Yes/no question; anything but `y`/`yes` is a no. */
67
+ /** Yes/no question. Anything but `y`/`yes` is a no. */
68
68
  export async function askConfirm(question) {
69
69
  const answer = (await ask(`${question} [y/N]`)).toLowerCase();
70
70
  return answer === "y" || answer === "yes";
@@ -28,7 +28,7 @@ function parseTimeout(value) {
28
28
  }
29
29
  function reviewFlags(rest) {
30
30
  const text = (name) => rest.find((item) => item.startsWith(`--${name}=`))?.slice(name.length + 3);
31
- // `--remake-before-review` is the 0.4.13 spelling; both names mean the same
31
+ // `--remake-before-review` is the 0.4.13 spelling. Both names mean the same
32
32
  // thing, and only the new one is documented.
33
33
  const syncBeforeReview = rest.some((arg) => arg === "--sync-before-review" || arg === "--remake-before-review");
34
34
  const remoteByokOn = rest.includes("--remote-byok");
@@ -146,7 +146,7 @@ export async function parseReviewArgs(args) {
146
146
  die("--experimental-siwc cannot be used with --remote");
147
147
  }
148
148
  // `--remote-host` / `--remote-token` only mean something together with
149
- // `--remote`; silently dropping them is exactly the kind of surprise to avoid.
149
+ // `--remote`. Silently dropping them is exactly the kind of surprise to avoid.
150
150
  if ((flags.remoteHost || flags.remoteToken) && !flags.remote) {
151
151
  die("--remote-host and --remote-token require --remote");
152
152
  }
@@ -1,5 +1,6 @@
1
1
  import { type CarryItem, type CarryPrevious, type ResolvedFinding, type StoredFinding } from "../review/carry_over.ts";
2
2
  import type { Revision, RevisionFile } from "../review/revision.ts";
3
+ import { type ReferenceContext } from "../review/references.ts";
3
4
  /** What a CLI run keeps for the next one: the findings that are still live. */
4
5
  export declare function storedFindings(resolved: ResolvedFinding[]): StoredFinding[];
5
6
  export type PreviousRun = {
@@ -26,7 +27,8 @@ export declare function finishCarryRun(run: CarryRun, revision: Revision, respon
26
27
  text: string;
27
28
  visiblePaths: string[];
28
29
  guideBuiltAt: string | null;
29
- }): {
30
+ referenceContext?: ReferenceContext;
31
+ }, repo?: string): {
30
32
  resolved: ResolvedFinding[];
31
33
  visiblePaths: Set<string>;
32
34
  };
@@ -2,6 +2,7 @@ import { buildCarryPromptSection, classifyCarryItems, incrementalDiffPaths, pars
2
2
  import { visiblePathsToSave } from "../review/visible_paths.js";
3
3
  import { parseFindings } from "../pr/findings.js";
4
4
  import { resolvedFromFirstReview } from "./review_result.js";
5
+ import { withResolvedReferences, } from "../review/references.js";
5
6
  /** What a CLI run keeps for the next one: the findings that are still live. */
6
7
  export function storedFindings(resolved) {
7
8
  return resolved
@@ -16,6 +17,7 @@ export function storedFindings(resolved) {
16
17
  anchorText: row.anchorText,
17
18
  severity: row.severity,
18
19
  firstSeenReviewId: row.firstSeenReviewId,
20
+ ...(row.references ? { references: row.references } : {}),
19
21
  }));
20
22
  }
21
23
  /** `previous` is null on a first or fresh run, and then nothing is carried. */
@@ -42,19 +44,19 @@ export function startCarryRun(previous, revision, currentGuideBuiltAt) {
42
44
  /** Turns the engine's answer into `new`, `open` and `closed` rows. Without a
43
45
  * previous run every parsed finding is `new`. `visiblePaths` is what to save
44
46
  * for the next run, decided by `visiblePathsToSave`. */
45
- export function finishCarryRun(run, revision, response) {
47
+ export function finishCarryRun(run, revision, response, repo = "") {
46
48
  const visiblePaths = new Set(response.visiblePaths);
47
49
  const parsed = parseFindings(response.text);
48
50
  if (!run.previous) {
49
51
  const filesByPath = new Map(revision.files.map((f) => [f.path, f]));
50
52
  return {
51
- resolved: resolvedFromFirstReview(parsed, filesByPath),
53
+ resolved: withResolvedReferences(resolvedFromFirstReview(parsed, filesByPath), repo, response.referenceContext),
52
54
  visiblePaths: visiblePathsToSave(null, run.extras.unchangedPaths, visiblePaths),
53
55
  };
54
56
  }
55
57
  const items = classifyCarryItems(run.previous, revision, visiblePaths, response.guideBuiltAt);
56
58
  return {
57
- resolved: resolveCarryOutcomes(items, revision, visiblePaths, parsePreviousVerdicts(response.text), parsed),
59
+ resolved: withResolvedReferences(resolveCarryOutcomes(items, revision, visiblePaths, parsePreviousVerdicts(response.text), parsed), repo, response.referenceContext),
58
60
  visiblePaths: visiblePathsToSave(run.previous.visiblePaths, run.extras.unchangedPaths, visiblePaths),
59
61
  };
60
62
  }
@@ -1,3 +1,4 @@
1
+ import { type ResolvedReference } from "../review/references.ts";
1
2
  import { type ParsedFinding } from "../pr/findings.ts";
2
3
  import { type ResolvedFinding } from "../review/carry_over.ts";
3
4
  import { type ReviewBlocking } from "../review/blocking.ts";
@@ -29,6 +30,9 @@ export type JsonReviewFinding = {
29
30
  lineTo: number;
30
31
  text: string;
31
32
  } | null;
33
+ /** What the finding rests on. Always present, shown in a comment only when
34
+ * the repository turns references on. */
35
+ references: ResolvedReference[];
32
36
  };
33
37
  export declare function isBlockingFinding(title: string, severity: string, mode?: ReviewBlocking): boolean;
34
38
  export declare function resolvedFromFirstReview(parsed: ParsedFinding[], filesByPath: Map<string, {
@@ -85,6 +89,8 @@ export type HumanFinding = {
85
89
  } | null;
86
90
  /** An extension finding's `[P2 · blocking] · extension: name`. */
87
91
  label?: string;
92
+ /** What the finding rests on, printed only with `showReferences`. */
93
+ references?: ResolvedReference[];
88
94
  };
89
95
  /** Local and PR findings: blocking is decided here from the configured rule,
90
96
  * exactly as the exit code decides it. */
@@ -95,10 +101,9 @@ export declare function humanFindingsFromResolved(findings: ResolvedFinding[], m
95
101
  export declare function humanFindingsFromJson(findings: JsonReviewFinding[]): HumanFinding[];
96
102
  /** The finding heading, as the shared header prints it. A parsed heading is
97
103
  * `[P2 · non-blocking] \`path\`: \`symbol\``. The label and the location are
98
- * already printed beside it, so only the symbol survives. An older heading
99
- * that used an em dash is still accepted, so comments posted before 0.5.0
100
- * stay readable. A heading with no symbol leaves nothing: printing the label
101
- * or the path again would repeat what the line already says. */
104
+ * already printed beside it, so only the symbol survives. A heading with no
105
+ * symbol leaves nothing: printing the label or the path again would repeat
106
+ * what the line already says. */
102
107
  export declare function humanShortTitle(row: HumanFinding): string;
103
108
  export declare function sortHumanFindings(rows: HumanFinding[]): HumanFinding[];
104
109
  export type HumanReviewInput = {
@@ -118,6 +123,9 @@ export type HumanReviewInput = {
118
123
  coverage?: Coverage;
119
124
  /** The extensions' results. Absent or empty prints nothing extra. */
120
125
  extensions?: ExtensionReport;
126
+ /** Print each finding's references. On only when the repository turned
127
+ * references on. */
128
+ showReferences?: boolean;
121
129
  /** An intent file was given. The line says so and never shows the text. */
122
130
  intent?: boolean;
123
131
  };
@@ -130,7 +138,7 @@ export type HumanReviewInput = {
130
138
  * stay in the GitHub comment, which is a different reader. */
131
139
  export declare function formatHumanReview(input: HumanReviewInput): string;
132
140
  /** Local review output: the shared format plus the working-tree file stats. */
133
- export declare function formatHumanLocalReview(header: string, revision: Revision, guideBuiltAt: string | null, codegraphState: "used" | "disabled" | "unavailable", findings: ResolvedFinding[], warnings: ReviewWarning[], mode?: ReviewBlocking, coverage?: Coverage, extensions?: ExtensionReport, intent?: boolean): string;
141
+ export declare function formatHumanLocalReview(header: string, revision: Revision, guideBuiltAt: string | null, codegraphState: "used" | "disabled" | "unavailable", findings: ResolvedFinding[], warnings: ReviewWarning[], mode?: ReviewBlocking, coverage?: Coverage, extensions?: ExtensionReport, intent?: boolean, showReferences?: boolean): string;
134
142
  /** The exit code for a remote review. The server already decided
135
143
  * each finding's `blocking` under its own configured rule, so the client
136
144
  * trusts that field instead of re-deriving the rule from a title: the client
@@ -1,3 +1,4 @@
1
+ import { referenceLine } from "../review/references.js";
1
2
  import { parseFindings } from "../pr/findings.js";
2
3
  import { readSuggestion, stripSuggestion } from "../pr/suggestion.js";
3
4
  import { stripControlChars } from "../util/sanitize.js";
@@ -37,6 +38,7 @@ export function resolvedFromFirstReview(parsed, filesByPath) {
37
38
  severity: finding.severity ?? "P2",
38
39
  carriedFromId: null,
39
40
  firstSeenReviewId: null,
41
+ referenceIds: finding.references ?? [],
40
42
  };
41
43
  });
42
44
  }
@@ -78,6 +80,7 @@ export function toJsonFinding(row, mode = DEFAULT_REVIEW_BLOCKING) {
78
80
  text: suggestion.code,
79
81
  }
80
82
  : null,
83
+ references: row.references ?? [],
81
84
  };
82
85
  }
83
86
  function statsOf(revision) {
@@ -149,6 +152,7 @@ export function humanFindingsFromResolved(findings, mode = DEFAULT_REVIEW_BLOCKI
149
152
  text: suggestion.code,
150
153
  }
151
154
  : null,
155
+ ...(row.references ? { references: row.references } : {}),
152
156
  };
153
157
  });
154
158
  }
@@ -166,6 +170,8 @@ export function humanFindingsFromJson(findings) {
166
170
  title: row.title,
167
171
  body: row.body.trim(),
168
172
  suggestion: row.suggestion,
173
+ // A server older than references sends none.
174
+ ...(Array.isArray(row.references) ? { references: row.references } : {}),
169
175
  }));
170
176
  }
171
177
  function humanLocation(row) {
@@ -178,16 +184,13 @@ function humanLocation(row) {
178
184
  }
179
185
  /** The finding heading, as the shared header prints it. A parsed heading is
180
186
  * `[P2 · non-blocking] \`path\`: \`symbol\``. The label and the location are
181
- * already printed beside it, so only the symbol survives. An older heading
182
- * that used an em dash is still accepted, so comments posted before 0.5.0
183
- * stay readable. A heading with no symbol leaves nothing: printing the label
184
- * or the path again would repeat what the line already says. */
187
+ * already printed beside it, so only the symbol survives. A heading with no
188
+ * symbol leaves nothing: printing the label or the path again would repeat
189
+ * what the line already says. */
185
190
  export function humanShortTitle(row) {
186
191
  const withoutLabel = row.title.replace(/^\[P\d\s*·\s*[^\]]*\]\s*/, "");
187
- const dash = withoutLabel.indexOf(" — ");
188
- const tail = dash === -1 ? withoutLabel : withoutLabel.slice(dash + 3);
189
- const colon = tail.indexOf(": ");
190
- const symbol = colon === -1 ? tail : tail.slice(colon + 2);
192
+ const colon = withoutLabel.indexOf(": ");
193
+ const symbol = colon === -1 ? withoutLabel : withoutLabel.slice(colon + 2);
191
194
  const clean = symbol.replace(/^`|`$/g, "").trim();
192
195
  return clean === "" || clean === row.path ? "" : clean;
193
196
  }
@@ -264,6 +267,12 @@ export function formatHumanReview(input) {
264
267
  lines.push(` ${stripControlChars(part)}`);
265
268
  lines.push(" ```");
266
269
  }
270
+ if (input.showReferences && row.references?.length) {
271
+ lines.push(` References (${row.references.length})`);
272
+ for (const reference of row.references) {
273
+ lines.push(` - ${stripControlChars(referenceLine(reference, false))}`);
274
+ }
275
+ }
267
276
  }
268
277
  lines.push("");
269
278
  }
@@ -307,7 +316,7 @@ export function formatHumanReview(input) {
307
316
  return lines.join("\n");
308
317
  }
309
318
  /** Local review output: the shared format plus the working-tree file stats. */
310
- export function formatHumanLocalReview(header, revision, guideBuiltAt, codegraphState, findings, warnings, mode = DEFAULT_REVIEW_BLOCKING, coverage, extensions, intent) {
319
+ export function formatHumanLocalReview(header, revision, guideBuiltAt, codegraphState, findings, warnings, mode = DEFAULT_REVIEW_BLOCKING, coverage, extensions, intent, showReferences) {
311
320
  const stats = revisionStats(revision);
312
321
  return formatHumanReview({
313
322
  title: header,
@@ -319,6 +328,7 @@ export function formatHumanLocalReview(header, revision, guideBuiltAt, codegraph
319
328
  coverage,
320
329
  extensions,
321
330
  intent,
331
+ showReferences,
322
332
  });
323
333
  }
324
334
  /** The exit code for a remote review. The server already decided
@@ -1,6 +1,6 @@
1
1
  import { type Platform } from "./util/runtime.ts";
2
2
  import type { ExtensionRegistration } from "./extensions/registry.ts";
3
- /** Everything init/remake resolved for one repo, except secrets — an API
3
+ /** Everything init/remake resolved for one repo, except secrets, an API
4
4
  * token is never written to config.json, only ever taken from --token or
5
5
  * an env file. Remembering this lets `remake owner/repo` run with no
6
6
  * flags and no interactive prompts, reusing what `init` was told. */
@@ -38,12 +38,21 @@ export type RepoConfig = {
38
38
  /** How a review decides a blocking finding for this repository. Unset
39
39
  * follows the server default. */
40
40
  reviewBlocking?: "model" | "severity";
41
+ /** Show each finding's references (the guide rules, instructions,
42
+ * codebase conventions or review instructions it rests on) in the review
43
+ * comment. Unset or false keeps them out of the comment. They are stored
44
+ * and shown on the dashboard either way. */
45
+ reviewReferences?: boolean;
46
+ /** When the first sync after `reviewReferences` was turned on re-read
47
+ * every pull request so its rules get comment links. Set once, so turning
48
+ * the setting off and on again never re-reads them a second time. */
49
+ referencesBackfilledAt?: string;
41
50
  /** A repository's own review instructions, appended to the built-in
42
51
  * reviewer prompt as a `CUSTOM REVIEW INSTRUCTIONS` section. Unset or blank
43
52
  * means none. */
44
53
  reviewSystemPrompt?: string;
45
54
  /** Cap on `reviewSystemPrompt` in characters for this repository. Unset
46
- * means the default; `0` or a negative number means no limit. */
55
+ * means the default, `0` or a negative number means no limit. */
47
56
  reviewSystemPromptMaxChars?: number;
48
57
  /** Which diagram language this repository's reviews use. Unset means
49
58
  * `mermaid`. `set --repo` writes it, so App reviews can use it too. */
@@ -54,7 +63,7 @@ export type RepoConfig = {
54
63
  /** `svg` or `png`. Unset means `svg`. */
55
64
  plantumlOutputFormat?: "svg" | "png";
56
65
  /** Cap on one `read-full-diff` answer in characters for this repository.
57
- * Unset means the default; `0` or a negative number means no limit. */
66
+ * Unset means the default, `0` or a negative number means no limit. */
58
67
  reviewReadDiffMaxChars?: number;
59
68
  };
60
69
  export type UserConfig = {
@@ -68,7 +77,7 @@ export type UserConfig = {
68
77
  /** GitHub Personal Access Token, used when `--auth=pat`. Only ever
69
78
  * written by `set --github-pat=...`. */
70
79
  githubPat?: string;
71
- /** GitHub App credentials for `co-maintainer serve` — also only ever
80
+ /** GitHub App credentials for `co-maintainer serve`, also only ever
72
81
  * written by `set`. `githubWebhookSecret` is optional. */
73
82
  githubAppId?: string;
74
83
  githubAppPrivateKey?: string;
@@ -78,12 +87,12 @@ export type UserConfig = {
78
87
  githubWebhookSecret?: string;
79
88
  webhookUrl?: string;
80
89
  /** "Sign in with GitHub" for the dashboard, reusing the App's own OAuth
81
- * client — only `githubOAuthAllowedUser` may complete it. All three only
90
+ * client, only `githubOAuthAllowedUser` may complete it. All three only
82
91
  * ever written by `set`. */
83
92
  githubOAuthClientId?: string;
84
93
  githubOAuthClientSecret?: string;
85
94
  githubOAuthAllowedUser?: string;
86
- /** Which sign-in methods `serve` accepts by default; a `--disable-auth`/
95
+ /** Which sign-in methods `serve` accepts by default. A `--disable-auth`/
87
96
  * `--enable-auth` flag on the `serve` command overrides these per run. */
88
97
  passwordAuthDisabled?: boolean;
89
98
  githubAuthEnabled?: boolean;
@@ -112,11 +121,11 @@ export type UserConfig = {
112
121
  codegraphVersion?: string;
113
122
  /** Remote review CLI target (`co-maintainer set`). */
114
123
  remoteHost?: string;
115
- /** Bearer token for `/api/remote/*`; only written by `set`. */
124
+ /** Bearer token for `/api/remote/*`. Only written by `set`. */
116
125
  remoteToken?: string;
117
126
  /** Hosts for which the unpublished-code notice was shown. */
118
127
  remoteNoticeShownFor?: string[];
119
- /** Remote client watchdog timeout; dashboard may override. */
128
+ /** Remote client watchdog timeout. Dashboard may override. */
120
129
  remoteSyncTimeoutSeconds?: number;
121
130
  maxConcurrentRemoteReviewsPerToken?: number;
122
131
  remoteToolOutputMaxChars?: number;
@@ -171,11 +180,11 @@ export declare function remoteByokPolicy(config?: Pick<UserConfig, "remoteByokPo
171
180
  * migration's `"windows"` vs `"win32"` trap is invisible otherwise. */
172
181
  export declare function getConfigDir(os?: Platform, env?: (name: string) => string | undefined): string;
173
182
  export declare function getCacheDir(os?: Platform, env?: (name: string) => string | undefined): string;
174
- /** `CM_CONFIG_PATH` overrides the path — tests point it at a temp file so
183
+ /** `CM_CONFIG_PATH` overrides the path, tests point it at a temp file so
175
184
  * they never read or write the real config.json. */
176
185
  export declare function configPath(): string;
177
186
  /** Where generated skills (SKILL.md, CODEBASE.md, review guides) live.
178
- * Never relative to the current directory — a globally installed CLI can be
187
+ * Never relative to the current directory, a globally installed CLI can be
179
188
  * invoked from anywhere, including directories it has no permission to
180
189
  * write into (e.g. C:\Windows\System32). */
181
190
  export declare function reposDir(): string;
@@ -227,7 +236,7 @@ export declare function writeRepoConfig(repo: string, patch: RepoConfig): Promis
227
236
  export declare function removeRepoConfig(repo: string): Promise<boolean>;
228
237
  /** Drops every per-repo entry. `clear all` forgets every repository it knows. */
229
238
  export declare function removeAllRepoConfig(): Promise<boolean>;
230
- /** Merges `patch` into the top-level (global, cross-repo) config —
239
+ /** Merges `patch` into the top-level (global, cross-repo) config,
231
240
  * used by `co-maintainer set`. This is the only path allowed to persist
232
241
  * a token. */
233
242
  export declare function writeUserConfig(patch: Partial<UserConfig>): Promise<void>;
@@ -88,13 +88,13 @@ export function getCacheDir(os = currentPlatform(), env = getEnv) {
88
88
  return env("XDG_CACHE_HOME") ?? `${home}/.cache`;
89
89
  }
90
90
  }
91
- /** `CM_CONFIG_PATH` overrides the path — tests point it at a temp file so
91
+ /** `CM_CONFIG_PATH` overrides the path, tests point it at a temp file so
92
92
  * they never read or write the real config.json. */
93
93
  export function configPath() {
94
94
  return (getEnv("CM_CONFIG_PATH") ?? `${getConfigDir()}/co-maintainer/config.json`);
95
95
  }
96
96
  /** Where generated skills (SKILL.md, CODEBASE.md, review guides) live.
97
- * Never relative to the current directory — a globally installed CLI can be
97
+ * Never relative to the current directory, a globally installed CLI can be
98
98
  * invoked from anywhere, including directories it has no permission to
99
99
  * write into (e.g. C:\Windows\System32). */
100
100
  export function reposDir() {
@@ -245,7 +245,7 @@ export async function removeAllRepoConfig() {
245
245
  await writeConfig({ ...config, repos: undefined });
246
246
  return true;
247
247
  }
248
- /** Merges `patch` into the top-level (global, cross-repo) config —
248
+ /** Merges `patch` into the top-level (global, cross-repo) config,
249
249
  * used by `co-maintainer set`. This is the only path allowed to persist
250
250
  * a token. */
251
251
  export async function writeUserConfig(patch) {
@@ -12,7 +12,7 @@ export type Installation = {
12
12
  events?: string[];
13
13
  };
14
14
  /** App-level calls: list installations, mint an installation access token.
15
- * Not scoped to one installation — `AppClient` below is. */
15
+ * Not scoped to one installation, `AppClient` below is. */
16
16
  export declare class AppJwtClient {
17
17
  private readonly appId;
18
18
  private readonly privateKeyPem;
@@ -27,7 +27,7 @@ async function get(endpoint, token) {
27
27
  }
28
28
  const installationTokens = new Map();
29
29
  /** App-level calls: list installations, mint an installation access token.
30
- * Not scoped to one installation — `AppClient` below is. */
30
+ * Not scoped to one installation, `AppClient` below is. */
31
31
  export class AppJwtClient {
32
32
  appId;
33
33
  privateKeyPem;
@@ -36,7 +36,7 @@ export type ManifestConversion = {
36
36
  clientId: string;
37
37
  clientSecret: string;
38
38
  };
39
- /** `POST /app-manifests/{code}/conversions` — the `code` is single use and
39
+ /** `POST /app-manifests/{code}/conversions`, the `code` is single use and
40
40
  * expires roughly an hour after GitHub redirects the browser back. */
41
41
  export declare function convertManifest(code: string): Promise<ManifestConversion>;
42
42
  export declare function beginManifestState(now?: number): string;
@@ -75,7 +75,7 @@ export function manifestBlockedReason(webhookUrl) {
75
75
  return `${reach} Set a public webhook address first.`;
76
76
  return undefined;
77
77
  }
78
- /** `POST /app-manifests/{code}/conversions` — the `code` is single use and
78
+ /** `POST /app-manifests/{code}/conversions`, the `code` is single use and
79
79
  * expires roughly an hour after GitHub redirects the browser back. */
80
80
  export async function convertManifest(code) {
81
81
  const response = await githubFetch(`https://api.github.com/app-manifests/${encodeURIComponent(code)}/conversions`, {
@@ -1,6 +1,6 @@
1
1
  /** Shared by every `GitHubClient` implementation that talks over `fetch`
2
2
  * (pat.ts, and app.ts). `GhClient` shells out to the `gh` binary and does
3
- * not use `githubFetch`; both paths share `paginate` and `waitForRateLimit`. */
3
+ * not use `githubFetch`. Both paths share `paginate` and `waitForRateLimit`. */
4
4
  export declare class GitHubHttpError extends Error {
5
5
  readonly status: number;
6
6
  constructor(status: number, body: string, hint?: string);
@@ -1,6 +1,6 @@
1
1
  /** Shared by every `GitHubClient` implementation that talks over `fetch`
2
2
  * (pat.ts, and app.ts). `GhClient` shells out to the `gh` binary and does
3
- * not use `githubFetch`; both paths share `paginate` and `waitForRateLimit`. */
3
+ * not use `githubFetch`. Both paths share `paginate` and `waitForRateLimit`. */
4
4
  import { log } from "../util/log.js";
5
5
  import { networkFailure } from "../cli/error.js";
6
6
  import { missingHint, refusalHint } from "./permissions.js";
@@ -1,5 +1,11 @@
1
- import type { GitHubClient, Options } from "../types.ts";
1
+ import type { GitHubClient, Json, Options } from "../types.ts";
2
2
  import type { Source, State } from "../knowledge/types.ts";
3
+ /** The non-empty texts and the GitHub link of each, kept at the same index so
4
+ * a fact can later name a comment and code can find its link. */
5
+ export declare function textsWithLinks(items: Json[], text: (item: Json) => string, max?: number): {
6
+ texts: string[];
7
+ urls: string[];
8
+ };
3
9
  /** What the codebase fetch saves while it runs. `instructionFiles` is always
4
10
  * named, even when missing: the blob SHAs it is checked against are saved in
5
11
  * the same write, so a checkpoint never pairs new SHAs with old contents. */
@@ -14,8 +14,26 @@ function percent(done, total) {
14
14
  function changesRequested(reviews) {
15
15
  return reviews.some((review) => review.state === "CHANGES_REQUESTED");
16
16
  }
17
+ /** The non-empty texts and the GitHub link of each, kept at the same index so
18
+ * a fact can later name a comment and code can find its link. */
19
+ export function textsWithLinks(items, text, max = Infinity) {
20
+ const kept = items
21
+ .map((item) => ({ text: text(item), url: String(item.html_url ?? "") }))
22
+ .filter((item) => item.text)
23
+ .slice(0, max);
24
+ return {
25
+ texts: kept.map((item) => item.text),
26
+ urls: kept.map((item) => item.url),
27
+ };
28
+ }
17
29
  function reviewBodies(reviews) {
18
- return reviews.map((review) => String(review.body ?? "")).filter(Boolean);
30
+ return textsWithLinks(reviews, (review) => String(review.body ?? ""));
31
+ }
32
+ function reviewCommentText(comment) {
33
+ const path = String(comment.path ?? "");
34
+ const line = String(comment.line ?? comment.original_line ?? "");
35
+ const body = String(comment.body ?? "");
36
+ return path ? `${path}:${line} ${body}` : body;
19
37
  }
20
38
  function withinPrWindow(updatedAt, months) {
21
39
  if (months === undefined || months === 0)
@@ -396,6 +414,11 @@ async function pullRequests(client, options, previous, phase) {
396
414
  comments: cached?.comments ?? [],
397
415
  reviewComments: cached?.reviewComments ?? [],
398
416
  reviews: cached?.reviews ?? [],
417
+ ...(cached?.commentUrls ? { commentUrls: cached.commentUrls } : {}),
418
+ ...(cached?.reviewCommentUrls
419
+ ? { reviewCommentUrls: cached.reviewCommentUrls }
420
+ : {}),
421
+ ...(cached?.reviewUrls ? { reviewUrls: cached.reviewUrls } : {}),
399
422
  changedFiles: cached?.changedFiles ?? [],
400
423
  diff: cached?.diff ?? "",
401
424
  };
@@ -403,7 +426,14 @@ async function pullRequests(client, options, previous, phase) {
403
426
  current.changesRequested = cached.changesRequested;
404
427
  }
405
428
  const only = options.onlyRequestChangedPr;
406
- const discussionUnchanged = cached?.updatedAt === current.updatedAt;
429
+ // A row cached before comment links were kept is read again once, after
430
+ // the repository turned references on, so its rules get links.
431
+ const missingLinks = options.refreshCommentLinks === true &&
432
+ cached !== undefined &&
433
+ cached.commentUrls === undefined &&
434
+ cached.reviewCommentUrls === undefined &&
435
+ cached.reviewUrls === undefined;
436
+ const discussionUnchanged = cached?.updatedAt === current.updatedAt && !missingLinks;
407
437
  const decisionKnown = typeof cached?.changesRequested === "boolean";
408
438
  const diffUnchanged = cached?.headSha === current.headSha && Boolean(cached?.diff);
409
439
  let droppedFromCache = only &&
@@ -412,28 +442,23 @@ async function pullRequests(client, options, previous, phase) {
412
442
  let dropped = droppedFromCache;
413
443
  const loadComments = async () => {
414
444
  const comments = await client.pages(`repos/${options.repo}/issues/${number}/comments`);
415
- current.comments = comments
416
- .map((comment) => String(comment.body ?? ""))
417
- .filter(Boolean)
418
- .slice(0, options.maxComments);
445
+ const kept = textsWithLinks(comments, (comment) => String(comment.body ?? ""), options.maxComments);
446
+ current.comments = kept.texts;
447
+ current.commentUrls = kept.urls;
419
448
  };
420
449
  // Inline review comments carry most of the substantive feedback, and the
421
450
  // reviewer only sees them if they are read here.
422
451
  const loadReviewComments = async () => {
423
452
  const comments = await client.pages(`repos/${options.repo}/pulls/${number}/comments`);
424
- current.reviewComments = comments
425
- .map((comment) => {
426
- const path = String(comment.path ?? "");
427
- const line = String(comment.line ?? comment.original_line ?? "");
428
- const body = String(comment.body ?? "");
429
- return path ? `${path}:${line} ${body}` : body;
430
- })
431
- .filter(Boolean)
432
- .slice(0, options.maxComments);
453
+ const kept = textsWithLinks(comments, reviewCommentText, options.maxComments);
454
+ current.reviewComments = kept.texts;
455
+ current.reviewCommentUrls = kept.urls;
433
456
  };
434
457
  const loadReviews = async () => {
435
458
  const reviews = await client.pages(`repos/${options.repo}/pulls/${number}/reviews`);
436
- current.reviews = reviewBodies(reviews);
459
+ const kept = reviewBodies(reviews);
460
+ current.reviews = kept.texts;
461
+ current.reviewUrls = kept.urls;
437
462
  current.changesRequested = changesRequested(reviews);
438
463
  };
439
464
  if (!dropped && only && (!discussionUnchanged || !decisionKnown)) {
@@ -40,14 +40,14 @@ function runGh(args, input) {
40
40
  * what to do next. The four shapes that came up in practice:
41
41
  * `gh` missing from PATH, the repo missing or unreadable, an empty stderr, and
42
42
  * everything else. The first line is the only part a human reads, so it always
43
- * names the situation; the raw gh text moves to the hint so it stays available
43
+ * names the situation. The raw gh text moves to the hint so it stays available
44
44
  * without drowning the message. */
45
45
  function ghFailure(method, endpoint, stderr) {
46
46
  if (/ENOENT|command not found|not recognized/i.test(stderr)) {
47
47
  return new CliError("gh_not_installed", "GitHub CLI (gh) was not found.", "Install it from https://cli.github.com or use --auth=pat.", EXIT_USAGE);
48
48
  }
49
49
  if (/HTTP 404|Not Found/i.test(stderr)) {
50
- // The endpoint is `repos/owner/repo/...`; the user thinks in `owner/repo`.
50
+ // The endpoint is `repos/owner/repo/...`. The user thinks in `owner/repo`.
51
51
  const match = endpoint.match(/^repos\/([^/]+)\/([^/]+)/);
52
52
  const subject = match ? `${match[1]}/${match[2]}` : endpoint;
53
53
  return new CliError("repo_not_found", `${subject} was not found, or your GitHub account cannot read it.`, "Check the name and run gh auth status.", EXIT_USAGE);