co-maintainer 0.6.13 → 0.7.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (156) hide show
  1. package/README.md +1 -1
  2. package/dist/package.json +1 -1
  3. package/dist/src/ai/anthropic.js +2 -0
  4. package/dist/src/ai/batch.d.ts +3 -1
  5. package/dist/src/ai/batch.js +23 -2
  6. package/dist/src/ai/mermaid_loop.js +1 -1
  7. package/dist/src/ai/oauth/sign-in-with-chatgpt.js +8 -10
  8. package/dist/src/ai/openai.js +2 -0
  9. package/dist/src/ai/openrouter.js +2 -0
  10. package/dist/src/cli/args.js +47 -0
  11. package/dist/src/cli/command_json.d.ts +20 -1
  12. package/dist/src/cli/command_json.js +4 -0
  13. package/dist/src/cli/commands/config.d.ts +1 -1
  14. package/dist/src/cli/commands/config.js +1 -0
  15. package/dist/src/cli/commands/registry.js +226 -1
  16. package/dist/src/cli/commands/review.js +50 -9
  17. package/dist/src/cli/commands/serve.js +5 -0
  18. package/dist/src/cli/commands/set.js +70 -2
  19. package/dist/src/cli/commands/view.js +46 -5
  20. package/dist/src/cli/commands/view_sources.d.ts +11 -0
  21. package/dist/src/cli/commands/view_sources.js +40 -0
  22. package/dist/src/cli/main.js +5 -0
  23. package/dist/src/cli/pr_carry.d.ts +25 -0
  24. package/dist/src/cli/pr_carry.js +128 -0
  25. package/dist/src/cli/prompt.js +26 -1
  26. package/dist/src/cli/review_args.d.ts +8 -0
  27. package/dist/src/cli/review_args.js +18 -0
  28. package/dist/src/cli/review_carry.d.ts +32 -0
  29. package/dist/src/cli/review_carry.js +60 -0
  30. package/dist/src/cli/review_github.d.ts +16 -2
  31. package/dist/src/cli/review_github.js +49 -12
  32. package/dist/src/cli/review_intent.d.ts +25 -0
  33. package/dist/src/cli/review_intent.js +87 -0
  34. package/dist/src/cli/review_result.d.ts +53 -2
  35. package/dist/src/cli/review_result.js +90 -23
  36. package/dist/src/config.d.ts +27 -0
  37. package/dist/src/config.js +20 -12
  38. package/dist/src/extensions/command.d.ts +1 -0
  39. package/dist/src/extensions/command.js +355 -0
  40. package/dist/src/extensions/contexts.d.ts +65 -0
  41. package/dist/src/extensions/contexts.js +134 -0
  42. package/dist/src/extensions/cost.d.ts +8 -0
  43. package/dist/src/extensions/cost.js +6 -0
  44. package/dist/src/extensions/local_tracking.d.ts +7 -0
  45. package/dist/src/extensions/local_tracking.js +29 -0
  46. package/dist/src/extensions/mock.d.ts +29 -0
  47. package/dist/src/extensions/mock.js +67 -0
  48. package/dist/src/extensions/process.d.ts +43 -0
  49. package/dist/src/extensions/process.js +244 -0
  50. package/dist/src/extensions/registry.d.ts +79 -0
  51. package/dist/src/extensions/registry.js +240 -0
  52. package/dist/src/extensions/render_actions.d.ts +6 -0
  53. package/dist/src/extensions/render_actions.js +50 -0
  54. package/dist/src/extensions/render_cli.d.ts +18 -0
  55. package/dist/src/extensions/render_cli.js +88 -0
  56. package/dist/src/extensions/render_json.d.ts +51 -0
  57. package/dist/src/extensions/render_json.js +144 -0
  58. package/dist/src/extensions/render_markdown.d.ts +22 -0
  59. package/dist/src/extensions/render_markdown.js +96 -0
  60. package/dist/src/extensions/render_review.d.ts +44 -0
  61. package/dist/src/extensions/render_review.js +167 -0
  62. package/dist/src/extensions/report.d.ts +57 -0
  63. package/dist/src/extensions/report.js +97 -0
  64. package/dist/src/extensions/review_result.d.ts +2 -0
  65. package/dist/src/extensions/review_result.js +14 -0
  66. package/dist/src/extensions/run_folder.d.ts +74 -0
  67. package/dist/src/extensions/run_folder.js +172 -0
  68. package/dist/src/extensions/runner.d.ts +66 -0
  69. package/dist/src/extensions/runner.js +251 -0
  70. package/dist/src/extensions/schema.d.ts +103 -0
  71. package/dist/src/extensions/schema.js +539 -0
  72. package/dist/src/extensions/session.d.ts +56 -0
  73. package/dist/src/extensions/session.js +173 -0
  74. package/dist/src/github/collect.d.ts +7 -2
  75. package/dist/src/github/collect.js +66 -6
  76. package/dist/src/github/gh.d.ts +7 -0
  77. package/dist/src/github/gh.js +24 -29
  78. package/dist/src/knowledge/guide.js +3 -2
  79. package/dist/src/knowledge/instruction_files.d.ts +45 -0
  80. package/dist/src/knowledge/instruction_files.js +91 -0
  81. package/dist/src/knowledge/instructions.d.ts +78 -0
  82. package/dist/src/knowledge/instructions.js +280 -0
  83. package/dist/src/knowledge/rule_changes.d.ts +39 -0
  84. package/dist/src/knowledge/rule_changes.js +90 -0
  85. package/dist/src/knowledge/rules.d.ts +44 -0
  86. package/dist/src/knowledge/rules.js +82 -0
  87. package/dist/src/knowledge/synthesis.d.ts +1 -0
  88. package/dist/src/knowledge/synthesis.js +12 -5
  89. package/dist/src/knowledge/types.d.ts +4 -0
  90. package/dist/src/local/carry_over_store.d.ts +10 -0
  91. package/dist/src/local/carry_over_store.js +17 -0
  92. package/dist/src/local/review_local.js +100 -62
  93. package/dist/src/local/review_lock.js +15 -4
  94. package/dist/src/pr/diff_plan.d.ts +110 -0
  95. package/dist/src/pr/diff_plan.js +429 -0
  96. package/dist/src/pr/diff_summary.d.ts +17 -1
  97. package/dist/src/pr/diff_summary.js +87 -13
  98. package/dist/src/pr/review_diff.d.ts +47 -0
  99. package/dist/src/pr/review_diff.js +112 -0
  100. package/dist/src/pr/reviewer.d.ts +44 -19
  101. package/dist/src/pr/reviewer.js +114 -142
  102. package/dist/src/remote/client.js +67 -8
  103. package/dist/src/remote/http.d.ts +12 -0
  104. package/dist/src/remote/http.js +31 -0
  105. package/dist/src/remote/push_client.js +14 -3
  106. package/dist/src/remote/server/guides.js +12 -1
  107. package/dist/src/remote/server/routes.js +4 -2
  108. package/dist/src/remote/server/sessions.js +4 -1
  109. package/dist/src/remote/validate.js +11 -0
  110. package/dist/src/review/carry_over.d.ts +6 -1
  111. package/dist/src/review/carry_over.js +10 -2
  112. package/dist/src/review/coverage.d.ts +57 -0
  113. package/dist/src/review/coverage.js +186 -0
  114. package/dist/src/review/diagram.d.ts +73 -0
  115. package/dist/src/review/diagram.js +309 -0
  116. package/dist/src/review/engine.d.ts +2 -6
  117. package/dist/src/review/engine.js +1 -1
  118. package/dist/src/review/guides.d.ts +6 -0
  119. package/dist/src/review/guides.js +8 -1
  120. package/dist/src/review/intent.d.ts +24 -0
  121. package/dist/src/review/intent.js +28 -0
  122. package/dist/src/review/not_initialized.d.ts +13 -0
  123. package/dist/src/review/not_initialized.js +18 -0
  124. package/dist/src/review/system_prompt.d.ts +6 -0
  125. package/dist/src/review/system_prompt.js +13 -0
  126. package/dist/src/review/visible_paths.d.ts +22 -0
  127. package/dist/src/review/visible_paths.js +41 -0
  128. package/dist/src/server/pages/extensions.d.ts +5 -0
  129. package/dist/src/server/pages/extensions.js +72 -0
  130. package/dist/src/server/pages/pr.js +3 -2
  131. package/dist/src/services/dashboard.d.ts +8 -0
  132. package/dist/src/services/dashboard.js +8 -0
  133. package/dist/src/services/push_review.js +14 -5
  134. package/dist/src/services/remote_review.js +81 -26
  135. package/dist/src/services/replies.js +15 -8
  136. package/dist/src/services/review.d.ts +9 -3
  137. package/dist/src/services/review.js +109 -28
  138. package/dist/src/services/rules_build.d.ts +46 -0
  139. package/dist/src/services/rules_build.js +155 -0
  140. package/dist/src/services/setup.d.ts +31 -0
  141. package/dist/src/services/setup.js +120 -25
  142. package/dist/src/services/watch_comments.js +2 -0
  143. package/dist/src/store/cache_db.js +3 -0
  144. package/dist/src/store/extensions.d.ts +51 -0
  145. package/dist/src/store/extensions.js +132 -0
  146. package/dist/src/store/migrations.js +40 -0
  147. package/dist/src/types.d.ts +22 -1
  148. package/dist/src/util/atomic.d.ts +15 -1
  149. package/dist/src/util/atomic.js +59 -29
  150. package/dist/src/util/interrupt.d.ts +6 -0
  151. package/dist/src/util/interrupt.js +27 -0
  152. package/dist/src/util/runtime.d.ts +3 -1
  153. package/dist/src/util/runtime.js +2 -2
  154. package/dist/src/util/test_location_guard.d.ts +6 -0
  155. package/dist/src/util/test_location_guard.js +47 -0
  156. package/package.json +1 -1
@@ -16,15 +16,18 @@ import { detectRemoteRepo } from "../../local/git_ops.js";
16
16
  import { CliError, EXIT_USAGE } from "../error.js";
17
17
  import { renderCommandHelp, unknownOptionMessage } from "./registry.js";
18
18
  import { readDir, readTextFile, stat } from "../../util/runtime.js";
19
+ import { parseRules, RULES_FILE } from "../../knowledge/rules.js";
20
+ import { renderSources } from "./view_sources.js";
19
21
  import { baseUrl, die, readApiError, remoteFetch, remoteFromEnv, } from "../../remote/http.js";
20
- /** The four generated guides, in the order a reader wants them: the
21
- * contribution skill first, then the codebase notes, then the two review
22
- * guides (short, then the evidence behind it). */
22
+ /** The generated guides, in the order a reader wants them: the contribution
23
+ * skill first, then the codebase notes, then the two review guides (short,
24
+ * then the evidence behind it), then the repository instructions. */
23
25
  const GUIDES = [
24
26
  { kind: "skill", file: "SKILL.md" },
25
27
  { kind: "codebase", file: "CODEBASE.md" },
26
28
  { kind: "review-guide", file: "PR_REVIEW_GUIDE.md" },
27
29
  { kind: "detailed-guide", file: "PR_REVIEW_DETAILED_GUIDE.md" },
30
+ { kind: "instructions", file: "INSTRUCTIONS.md" },
28
31
  ];
29
32
  /** Resolves a user-supplied name to a guide. Accepts the kind names
30
33
  * (`review-guide`), the file name (`PR_REVIEW_GUIDE.md`), and the bare stem
@@ -143,6 +146,23 @@ function printGuides(repo, guides, options) {
143
146
  .map((guide) => `== ${guide.file} · built ${builtDate(guide.builtAt)} ==\n${guide.content.trimEnd()}`)
144
147
  .join("\n\n"));
145
148
  }
149
+ /** `--sources`: the rules in `RULES.json`, by file, or the file itself with
150
+ * `--json`. */
151
+ function printSources(repo, guides, json) {
152
+ const found = guides.find((guide) => guide.file === RULES_FILE);
153
+ if (!found) {
154
+ throw new CliError("no_rules", `${repo} has no ${RULES_FILE}.`, `co-maintainer sync ${repo}`, EXIT_USAGE);
155
+ }
156
+ const rules = parseRules(found.content);
157
+ if (!rules) {
158
+ throw new CliError("rules_unreadable", `${RULES_FILE} for ${repo} could not be read.`, `co-maintainer sync ${repo}`, EXIT_USAGE);
159
+ }
160
+ if (json) {
161
+ process.stdout.write(found.content.endsWith("\n") ? found.content : `${found.content}\n`);
162
+ return;
163
+ }
164
+ console.log(renderSources(rules));
165
+ }
146
166
  export async function runView(args) {
147
167
  if (args.includes("--help") || args.includes("-h")) {
148
168
  console.log(renderCommandHelp("view") ??
@@ -152,10 +172,25 @@ export async function runView(args) {
152
172
  const remote = args.includes("--remote");
153
173
  for (const arg of args) {
154
174
  if (arg.startsWith("--") &&
155
- !["--list", "--path", "--remote", "--help", "-h"].includes(arg)) {
175
+ ![
176
+ "--list",
177
+ "--path",
178
+ "--remote",
179
+ "--sources",
180
+ "--json",
181
+ "--help",
182
+ "-h",
183
+ ].includes(arg)) {
156
184
  throw new CliError("usage", unknownOptionMessage(arg, "view"));
157
185
  }
158
186
  }
187
+ const sources = args.includes("--sources");
188
+ if (args.includes("--json") && !sources) {
189
+ throw new CliError("usage", "--json needs --sources.", "co-maintainer view owner/repo --sources --json", EXIT_USAGE);
190
+ }
191
+ if (sources && (args.includes("--list") || args.includes("--path"))) {
192
+ throw new CliError("usage", "--sources cannot be combined with --list or --path.", undefined, EXIT_USAGE);
193
+ }
159
194
  // The directory belongs to this machine, so it cannot answer for a server.
160
195
  if (remote && args.includes("--path")) {
161
196
  throw new CliError("usage", "--path and --remote cannot be combined.", "Drop --remote to print the local guide directory.", EXIT_USAGE);
@@ -166,9 +201,15 @@ export async function runView(args) {
166
201
  console.log(`${reposDir()}/${repo}`);
167
202
  return;
168
203
  }
169
- const guides = remote
204
+ const all = remote
170
205
  ? await readRemoteGuides(repo)
171
206
  : await readLocalGuides(repo);
207
+ if (sources) {
208
+ printSources(repo, all, args.includes("--json"));
209
+ return;
210
+ }
211
+ // `RULES.json` is the data behind `--sources`, not a guide to read.
212
+ const guides = all.filter((guide) => guide.file !== RULES_FILE);
172
213
  if (guides.length === 0) {
173
214
  throw new CliError("no_guides", remote
174
215
  ? `The server has no guides for ${repo}.`
@@ -0,0 +1,11 @@
1
+ /** `view --sources`: every rule id with where it came from.
2
+ *
3
+ * ```
4
+ * INSTRUCTIONS.md
5
+ * I1 Format amounts with formatMoney(), never with number methods
6
+ * AGENTS.md:31 · packages/billing/AGENTS.md:8
7
+ * ```
8
+ */
9
+ import { type RulesFile } from "../../knowledge/rules.ts";
10
+ /** The human listing, grouped by the file each rule lives in. */
11
+ export declare function renderSources(file: RulesFile): string;
@@ -0,0 +1,40 @@
1
+ /** `view --sources`: every rule id with where it came from.
2
+ *
3
+ * ```
4
+ * INSTRUCTIONS.md
5
+ * I1 Format amounts with formatMoney(), never with number methods
6
+ * AGENTS.md:31 · packages/billing/AGENTS.md:8
7
+ * ```
8
+ */
9
+ import { INSTRUCTIONS_FILE, sortedRuleIds, sourceLabel, } from "../../knowledge/rules.js";
10
+ const FILE_ORDER = [INSTRUCTIONS_FILE];
11
+ /** The second line under a rule: its instruction file lines. */
12
+ function sourcesLine(entry) {
13
+ if (entry.sources.length === 0)
14
+ return "no sources";
15
+ return entry.sources.map(sourceLabel).join(" · ");
16
+ }
17
+ /** The human listing, grouped by the file each rule lives in. */
18
+ export function renderSources(file) {
19
+ const ids = sortedRuleIds(file.rules);
20
+ if (ids.length === 0)
21
+ return "No rules recorded.";
22
+ const width = Math.max(...ids.map((id) => id.length)) + 2;
23
+ const files = [
24
+ ...FILE_ORDER,
25
+ ...[...new Set(ids.map((id) => file.rules[id].file))].filter((name) => !FILE_ORDER.includes(name)),
26
+ ];
27
+ const lines = [];
28
+ for (const name of files) {
29
+ const inFile = ids.filter((id) => file.rules[id].file === name);
30
+ if (inFile.length === 0)
31
+ continue;
32
+ lines.push(name);
33
+ for (const id of inFile) {
34
+ const entry = file.rules[id];
35
+ lines.push(` ${id.padEnd(width)}${entry.text}`);
36
+ lines.push(` ${" ".repeat(width)}${sourcesLine(entry)}`);
37
+ }
38
+ }
39
+ return lines.join("\n");
40
+ }
@@ -11,6 +11,7 @@ import { runClear } from "./commands/clear.js";
11
11
  import { runUninstall } from "./commands/uninstall.js";
12
12
  import { runProbe } from "./commands/probe.js";
13
13
  import { runReviewFromCli } from "./commands/review.js";
14
+ import { runExtensionCommand } from "../extensions/command.js";
14
15
  import { runInitOrRemake } from "../services/setup.js";
15
16
  import { VERSION } from "../version.js";
16
17
  import { CliError, EXIT_RUNTIME, exitWith } from "./error.js";
@@ -95,6 +96,10 @@ export async function run(args) {
95
96
  await runReviewFromCli(args.slice(1));
96
97
  return;
97
98
  }
99
+ if (args[0] === "extension") {
100
+ await runExtensionCommand(args.slice(1));
101
+ return;
102
+ }
98
103
  // An unknown command is a usage error with a suggestion, and it must resolve
99
104
  // through the registry so hidden aliases still work.
100
105
  if (args[0] && !args[0].startsWith("-") && !findCommand(args[0])) {
@@ -0,0 +1,25 @@
1
+ import type { GitHubClient, Options } from "../types.ts";
2
+ import { type ResolvedFinding } from "../review/carry_over.ts";
3
+ import type { ReviewExtras } from "../pr/reviewer.ts";
4
+ import type { ReviewWarning } from "./review_result.ts";
5
+ type EngineAnswer = {
6
+ text: string;
7
+ visiblePaths: string[];
8
+ guideBuiltAt: string | null;
9
+ };
10
+ /** What a CLI pull request review needs around the engine call. `extras` goes
11
+ * to `reviewPullRequest` as it is, `finish` turns its answer into findings and
12
+ * stores them for the next run. `warnings` is read after `finish`. */
13
+ export type PrCarry = {
14
+ extras: ReviewExtras;
15
+ warnings: ReviewWarning[];
16
+ finish(response: EngineAnswer): Promise<ResolvedFinding[]>;
17
+ };
18
+ /** Loads what the last run of this pull request left, decides whether it may
19
+ * be used, and builds the carry-over the engine takes. The decision mirrors
20
+ * local review, plus the force-push check: `--fresh`, a guide rebuilt since
21
+ * the last run, and a head that no longer contains the last reviewed head each
22
+ * start fresh. A cache or GitHub problem never fails the review. It only means
23
+ * nothing is carried, and the run says so in a warning. */
24
+ export declare function startPrCarry(client: GitHubClient, options: Options, fresh: boolean, log?: (message: string) => void): Promise<PrCarry>;
25
+ export {};
@@ -0,0 +1,128 @@
1
+ import { guideRebuiltSince, } from "../review/carry_over.js";
2
+ import { loadGuides } from "../review/guides.js";
3
+ import { githubPullRequestToRevision } from "../pr/github_revision.js";
4
+ import { clearPrCarry, prSubjectId, savePrCarry, tryLoadPrCarry, } from "../local/carry_over_store.js";
5
+ import { finishCarryRun, startCarryRun, storedFindings, } from "./review_carry.js";
6
+ /** True when `head` is the last reviewed head or was pushed on top of it. A
7
+ * force-push leaves the old head out of the new history, and then the stored
8
+ * findings point at code that no longer exists. Any doubt counts as a
9
+ * force-push, because starting fresh costs one scan and a wrong match hides a
10
+ * real finding. */
11
+ /** Null when the stored run may be used, otherwise the reason it may not. */
12
+ async function whyNotContained(client, repo, last, head) {
13
+ if (!last)
14
+ return "the last run did not record its head";
15
+ if (!head)
16
+ return "GitHub gave no head for this pull request";
17
+ if (last === head)
18
+ return null;
19
+ try {
20
+ const compare = await client.request(`repos/${repo}/compare/${last}...${head}?per_page=1`);
21
+ if (compare.status === "ahead" || compare.status === "identical") {
22
+ return null;
23
+ }
24
+ return `the head does not contain the last reviewed head (${String(compare.status)})`;
25
+ }
26
+ catch (error) {
27
+ const reason = error instanceof Error ? error.message : String(error);
28
+ return `could not compare the heads (${reason})`;
29
+ }
30
+ }
31
+ /** Loads what the last run of this pull request left, decides whether it may
32
+ * be used, and builds the carry-over the engine takes. The decision mirrors
33
+ * local review, plus the force-push check: `--fresh`, a guide rebuilt since
34
+ * the last run, and a head that no longer contains the last reviewed head each
35
+ * start fresh. A cache or GitHub problem never fails the review. It only means
36
+ * nothing is carried, and the run says so in a warning. */
37
+ export async function startPrCarry(client, options, fresh, log = () => { }) {
38
+ const repo = options.repo;
39
+ const prNumber = options.prNumber;
40
+ const warnings = [];
41
+ const forget = async () => {
42
+ await clearPrCarry(repo, prNumber).catch(() => { });
43
+ };
44
+ if (fresh)
45
+ await forget();
46
+ let current;
47
+ let headSha;
48
+ let prefetched;
49
+ try {
50
+ const [pr, files] = await Promise.all([
51
+ client.request(`repos/${repo}/pulls/${prNumber}`),
52
+ client.pages(`repos/${repo}/pulls/${prNumber}/files`),
53
+ ]);
54
+ // The review judges exactly what is stored, so it does not read these
55
+ // again. A push between two reads can no longer split them.
56
+ prefetched = { pull: pr, files };
57
+ headSha = String(pr.head?.sha ?? "");
58
+ const baseLabel = `origin/${String(pr.base?.ref ?? "main")}`;
59
+ current = githubPullRequestToRevision(files, pr, baseLabel);
60
+ }
61
+ catch {
62
+ // The review reads the same pull request and reports a real failure.
63
+ // Without the file list there is nothing to match findings against.
64
+ warnings.push({
65
+ code: "carry_over_unavailable",
66
+ message: "Could not read the pull request files for carry-over. Continuing without prior findings.",
67
+ });
68
+ return {
69
+ extras: {},
70
+ warnings,
71
+ finish: async (response) => finishCarryRun({ previous: null, items: [], extras: {} }, {
72
+ files: [],
73
+ title: "",
74
+ description: "",
75
+ baseLabel: "",
76
+ producer: "github",
77
+ }, response).resolved,
78
+ };
79
+ }
80
+ const guides = await loadGuides(repo);
81
+ const loaded = await tryLoadPrCarry(repo, prNumber);
82
+ if (loaded.unavailable) {
83
+ warnings.push({
84
+ code: "carry_over_unavailable",
85
+ message: "Could not read the carry-over cache. Continuing without prior findings.",
86
+ });
87
+ }
88
+ let previous = loaded.data;
89
+ if (previous &&
90
+ guideRebuiltSince(previous.guideBuiltAt, guides.guideBuiltAt)) {
91
+ log("the guide was rebuilt since the last review, starting fresh");
92
+ await forget();
93
+ previous = null;
94
+ }
95
+ if (previous) {
96
+ const why = await whyNotContained(client, repo, previous.headSha, headSha);
97
+ if (why) {
98
+ log(`${why}, starting fresh`);
99
+ await forget();
100
+ previous = null;
101
+ }
102
+ }
103
+ const run = startCarryRun(previous, current, guides.guideBuiltAt);
104
+ return {
105
+ extras: { ...run.extras, prefetched },
106
+ warnings,
107
+ finish: async (response) => {
108
+ const { resolved, visiblePaths } = finishCarryRun(run, current, response);
109
+ try {
110
+ await savePrCarry({
111
+ subjectId: prSubjectId(repo, prNumber),
112
+ files: current.files,
113
+ visiblePaths: [...visiblePaths],
114
+ findings: storedFindings(resolved),
115
+ guideBuiltAt: response.guideBuiltAt,
116
+ headSha,
117
+ });
118
+ }
119
+ catch {
120
+ warnings.push({
121
+ code: "carry_over_unavailable",
122
+ message: "Could not save carry-over state for the next review.",
123
+ });
124
+ }
125
+ return resolved;
126
+ },
127
+ };
128
+ }
@@ -10,9 +10,19 @@ import { createInterface } from "node:readline/promises";
10
10
  * is the hang: `co-maintainer review </dev/null` awaited the answer
11
11
  * forever, printed `Warning: Detected unsettled top-level await`, and exited
12
12
  * 13. Racing the question against `close`/`end` and treating those as "no
13
- * answer" keeps the caller's fallback path alive instead. */
13
+ * answer" keeps the caller's fallback path alive instead.
14
+ *
15
+ * While readline holds the terminal, Ctrl-C is a key press, not a signal, and
16
+ * it used to count as "no answer": a local review went on to the model after
17
+ * a Ctrl-C at the codegraph install prompt. Now the prompt closes and the
18
+ * interrupt is raised as if the signal had arrived. */
14
19
  async function ask(question) {
15
20
  const rl = createInterface({ input: process.stdin, output: process.stdout });
21
+ let interrupted = false;
22
+ rl.on("SIGINT", () => {
23
+ interrupted = true;
24
+ rl.close();
25
+ });
16
26
  try {
17
27
  return (await new Promise((resolve) => {
18
28
  let settled = false;
@@ -31,8 +41,23 @@ async function ask(question) {
31
41
  }
32
42
  finally {
33
43
  rl.close();
44
+ // After `close`, so the terminal is out of raw mode first.
45
+ if (interrupted)
46
+ raiseInterrupt();
34
47
  }
35
48
  }
49
+ /** Does what a real SIGINT would. A command with a handler (a local review)
50
+ * gets it at once, before the prompt returns, so nothing after the prompt
51
+ * runs as if the user had answered. Emitting rather than sending the signal
52
+ * keeps it synchronous, and works on Windows, where sending a signal to the
53
+ * own process ends it without running any handler. A command with no handler
54
+ * ends the way Ctrl-C ends it outside a prompt. */
55
+ function raiseInterrupt() {
56
+ if (process.listenerCount("SIGINT") > 0)
57
+ process.emit("SIGINT", "SIGINT");
58
+ else
59
+ process.kill(process.pid, "SIGINT");
60
+ }
36
61
  /** Free-text question; empty input yields the fallback (or ""). */
37
62
  export async function askLine(label, fallback) {
38
63
  const suffix = fallback ? ` [${fallback}]` : "";
@@ -1,3 +1,4 @@
1
+ import { type IntentLoad } from "./review_intent.ts";
1
2
  import type { Options } from "../types.ts";
2
3
  export type ReviewMode = "local" | "remote" | "pr";
3
4
  type ReviewFlags = {
@@ -26,6 +27,9 @@ type ReviewFlags = {
26
27
  /** `--system-prompt-override-file`: a file whose contents replace the
27
28
  * repository's custom review section for this run only. */
28
29
  systemPromptOverrideFile?: string;
30
+ /** `--intent-file`: a file, or `-` for standard input, that says what the
31
+ * change is for. Context for the prompt, never a rule. */
32
+ intentFile?: string;
29
33
  /** `--range=<before>..<after>`: review a push instead of the working tree
30
34
  * (commit watch). Only with `--remote`. */
31
35
  range?: {
@@ -35,10 +39,14 @@ type ReviewFlags = {
35
39
  /** `--timeout-minutes`: how long a `--range` review waits for the server
36
40
  * before it leaves the result to the dashboard. */
37
41
  timeoutMinutes?: number;
42
+ /** `--include-extension-markdowns`: keep each extension's `markdown` in
43
+ * `--json`. */
44
+ includeExtensionMarkdowns?: boolean;
38
45
  };
39
46
  export type ReviewCliArgs = ({
40
47
  mode: "pr";
41
48
  options: Options;
49
+ intentLoad?: IntentLoad;
42
50
  } & ReviewFlags) | ({
43
51
  mode: "local";
44
52
  rawArgs: string[];
@@ -3,6 +3,7 @@ import { die } from "./error.js";
3
3
  import { readConfig } from "../config.js";
4
4
  import { readTextFile } from "../util/runtime.js";
5
5
  import { checkReviewSystemPrompt, reviewSystemPromptLimit, } from "../review/system_prompt.js";
6
+ import { loadIntentFlag } from "./review_intent.js";
6
7
  /** `before..after`. Each side is any revision git can resolve. */
7
8
  function parseRange(value) {
8
9
  if (value === undefined)
@@ -66,8 +67,10 @@ function reviewFlags(rest) {
66
67
  output,
67
68
  systemPromptFile: text("system-prompt-file"),
68
69
  systemPromptOverrideFile: text("system-prompt-override-file"),
70
+ intentFile: text("intent-file"),
69
71
  range: parseRange(text("range")),
70
72
  timeoutMinutes: parseTimeout(text("timeout-minutes")),
73
+ includeExtensionMarkdowns: rest.includes("--include-extension-markdowns"),
71
74
  };
72
75
  }
73
76
  const LOCAL_ONLY_FLAGS = new Set([
@@ -80,6 +83,7 @@ const LOCAL_ONLY_FLAGS = new Set([
80
83
  "--sync-before-review",
81
84
  "--remote-byok",
82
85
  "--no-remote-byok",
86
+ "--include-extension-markdowns",
83
87
  ]);
84
88
  /** Strip local-only flags before `parseArgs` for PR-style options. */
85
89
  export function filterReviewConfigArgs(raw) {
@@ -94,6 +98,7 @@ export function filterReviewConfigArgs(raw) {
94
98
  arg.startsWith("--output=") ||
95
99
  arg.startsWith("--system-prompt-file=") ||
96
100
  arg.startsWith("--system-prompt-override-file=") ||
101
+ arg.startsWith("--intent-file=") ||
97
102
  arg.startsWith("--range=") ||
98
103
  arg.startsWith("--timeout-minutes=")) {
99
104
  return false;
@@ -148,12 +153,22 @@ export async function parseReviewArgs(args) {
148
153
  if (flags.remoteByok !== undefined && !flags.remote) {
149
154
  die("--remote-byok requires --remote");
150
155
  }
156
+ // The server reviews with the repository's saved diagram settings, so a flag
157
+ // here would be dropped without a word.
158
+ const diagramFlag = args.find((arg) => /^--(diagram-runtime|plantuml-server|plantuml-output-format)(=|$)/.test(arg));
159
+ if (flags.remote && diagramFlag) {
160
+ die(`${diagramFlag.split("=")[0]} cannot be used with --remote. ` +
161
+ "The server uses the diagram settings saved for the repository.");
162
+ }
151
163
  if (flags.range && !flags.remote) {
152
164
  die("--range requires --remote");
153
165
  }
154
166
  if (flags.timeoutMinutes !== undefined && !flags.range) {
155
167
  die("--timeout-minutes requires --range");
156
168
  }
169
+ if (flags.range && flags.intentFile !== undefined) {
170
+ die("--intent-file is not supported with --range");
171
+ }
157
172
  if (flags.range && (flags.fresh || flags.toBranch)) {
158
173
  die("--range cannot be used with --fresh or --to-branch");
159
174
  }
@@ -183,6 +198,7 @@ export async function parseReviewArgs(args) {
183
198
  die("--sync-before-review is not supported for PR review");
184
199
  }
185
200
  const promptFlags = await loadReviewSystemPromptFlags(flags, reviewSystemPromptLimitFor(options.repo));
201
+ const intentLoad = await loadIntentFlag(flags.intentFile, reviewSystemPromptLimitFor(options.repo));
186
202
  return {
187
203
  mode: "pr",
188
204
  options: {
@@ -191,7 +207,9 @@ export async function parseReviewArgs(args) {
191
207
  allowToolInstall: flags.allowToolInstall,
192
208
  reviewSystemPromptAdd: promptFlags.add,
193
209
  reviewSystemPromptOverride: promptFlags.override,
210
+ reviewIntent: intentLoad.intent?.text,
194
211
  },
212
+ intentLoad,
195
213
  ...flags,
196
214
  };
197
215
  }
@@ -0,0 +1,32 @@
1
+ import { type CarryItem, type CarryPrevious, type ResolvedFinding, type StoredFinding } from "../review/carry_over.ts";
2
+ import type { Revision, RevisionFile } from "../review/revision.ts";
3
+ /** What a CLI run keeps for the next one: the findings that are still live. */
4
+ export declare function storedFindings(resolved: ResolvedFinding[]): StoredFinding[];
5
+ export type PreviousRun = {
6
+ files: RevisionFile[];
7
+ visiblePaths: string[];
8
+ findings: StoredFinding[];
9
+ guideBuiltAt: string | null;
10
+ };
11
+ /** The carry-over a CLI review (local or pull request) hands the engine. */
12
+ export type CarryRun = {
13
+ previous: CarryPrevious | null;
14
+ items: CarryItem[];
15
+ extras: {
16
+ carryPrompt?: string;
17
+ unchangedPaths?: string[];
18
+ };
19
+ };
20
+ /** `previous` is null on a first or fresh run, and then nothing is carried. */
21
+ export declare function startCarryRun(previous: PreviousRun | null, revision: Revision, currentGuideBuiltAt: string | null): CarryRun;
22
+ /** Turns the engine's answer into `new`, `open` and `closed` rows. Without a
23
+ * previous run every parsed finding is `new`. `visiblePaths` is what to save
24
+ * for the next run, decided by `visiblePathsToSave`. */
25
+ export declare function finishCarryRun(run: CarryRun, revision: Revision, response: {
26
+ text: string;
27
+ visiblePaths: string[];
28
+ guideBuiltAt: string | null;
29
+ }): {
30
+ resolved: ResolvedFinding[];
31
+ visiblePaths: Set<string>;
32
+ };
@@ -0,0 +1,60 @@
1
+ import { buildCarryPromptSection, classifyCarryItems, incrementalDiffPaths, parsePreviousVerdicts, resolveCarryOutcomes, } from "../review/carry_over.js";
2
+ import { visiblePathsToSave } from "../review/visible_paths.js";
3
+ import { parseFindings } from "../pr/findings.js";
4
+ import { resolvedFromFirstReview } from "./review_result.js";
5
+ /** What a CLI run keeps for the next one: the findings that are still live. */
6
+ export function storedFindings(resolved) {
7
+ return resolved
8
+ .filter((row) => row.state === "new" || row.state === "open")
9
+ .map((row) => ({
10
+ id: row.id,
11
+ path: row.path,
12
+ lineFrom: row.lineFrom,
13
+ lineTo: row.lineTo,
14
+ title: row.title,
15
+ bodyMd: row.bodyMd,
16
+ anchorText: row.anchorText,
17
+ severity: row.severity,
18
+ firstSeenReviewId: row.firstSeenReviewId,
19
+ }));
20
+ }
21
+ /** `previous` is null on a first or fresh run, and then nothing is carried. */
22
+ export function startCarryRun(previous, revision, currentGuideBuiltAt) {
23
+ if (!previous)
24
+ return { previous: null, items: [], extras: {} };
25
+ const carryPrevious = {
26
+ files: previous.files,
27
+ visiblePaths: new Set(previous.visiblePaths),
28
+ findings: previous.findings,
29
+ guideBuiltAt: previous.guideBuiltAt,
30
+ };
31
+ const { unchanged } = incrementalDiffPaths(revision, previous.files, carryPrevious.visiblePaths);
32
+ const items = classifyCarryItems(carryPrevious, revision, carryPrevious.visiblePaths, currentGuideBuiltAt);
33
+ return {
34
+ previous: carryPrevious,
35
+ items,
36
+ extras: {
37
+ unchangedPaths: unchanged,
38
+ carryPrompt: buildCarryPromptSection(items, revision),
39
+ },
40
+ };
41
+ }
42
+ /** Turns the engine's answer into `new`, `open` and `closed` rows. Without a
43
+ * previous run every parsed finding is `new`. `visiblePaths` is what to save
44
+ * for the next run, decided by `visiblePathsToSave`. */
45
+ export function finishCarryRun(run, revision, response) {
46
+ const visiblePaths = new Set(response.visiblePaths);
47
+ const parsed = parseFindings(response.text);
48
+ if (!run.previous) {
49
+ const filesByPath = new Map(revision.files.map((f) => [f.path, f]));
50
+ return {
51
+ resolved: resolvedFromFirstReview(parsed, filesByPath),
52
+ visiblePaths: visiblePathsToSave(null, run.extras.unchangedPaths, visiblePaths),
53
+ };
54
+ }
55
+ const items = classifyCarryItems(run.previous, revision, visiblePaths, response.guideBuiltAt);
56
+ return {
57
+ resolved: resolveCarryOutcomes(items, revision, visiblePaths, parsePreviousVerdicts(response.text), parsed),
58
+ visiblePaths: visiblePathsToSave(run.previous.visiblePaths, run.extras.unchangedPaths, visiblePaths),
59
+ };
60
+ }
@@ -1,5 +1,7 @@
1
1
  import { type RunSummary } from "../util/run_summary.ts";
2
+ import { type Coverage } from "../review/coverage.ts";
2
3
  import { type HumanFinding } from "./review_result.ts";
4
+ import type { ExtensionReport } from "../extensions/report.ts";
3
5
  /** GitHub shows at most this many error and this many warning annotations per
4
6
  * step and drops the rest without a word. */
5
7
  export declare const MAX_ANNOTATIONS_PER_LEVEL = 10;
@@ -9,8 +11,9 @@ export declare function escapeData(value: string): string;
9
11
  /** A property value (`file`, `title`) also cannot hold `:` or `,`, which end it. */
10
12
  export declare function escapeProperty(value: string): string;
11
13
  /** One workflow command per finding still standing, errors first. A finding
12
- * that was closed since the last review needs no annotation. */
13
- export declare function githubAnnotations(findings: HumanFinding[]): string[];
14
+ * that was closed since the last review needs no annotation. The dropped
15
+ * files warning takes one of the warning slots. */
16
+ export declare function githubAnnotations(findings: HumanFinding[], coverage?: Coverage): string[];
14
17
  export type GithubSummaryInput = {
15
18
  /** What was reviewed, for the line under the heading. */
16
19
  title: string;
@@ -18,6 +21,17 @@ export type GithubSummaryInput = {
18
21
  /** Cost and time, in the same words the terminal uses. Left out when the run
19
22
  * cannot say. */
20
23
  run?: RunSummary;
24
+ /** What the model received. Left out by a remote server older than this
25
+ * field. */
26
+ coverage?: Coverage;
27
+ /** Whether this mode's next run covers the files this one dropped, see
28
+ * `coverageWarnings`. */
29
+ catchesUp?: boolean;
30
+ /** The extensions' results. Their findings join the table, and their
31
+ * `markdown` follows the AI part. */
32
+ extensions?: ExtensionReport;
33
+ /** An intent file was given. The summary says so and never shows the text. */
34
+ intent?: boolean;
21
35
  };
22
36
  export declare function githubSummary(input: GithubSummaryInput): string;
23
37
  /** Appends to `$GITHUB_STEP_SUMMARY` when it is set. A summary that cannot be