co-maintainer 0.6.10 → 0.6.12

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.
package/README.md CHANGED
@@ -1,110 +1,100 @@
1
- # co-maintainer
1
+ [![npm](https://img.shields.io/npm/v/co-maintainer)](https://www.npmjs.com/package/co-maintainer)
2
+ ![License](https://img.shields.io/badge/license-MIT-blue)
3
+ ![Price](https://img.shields.io/badge/price-%240-brightgreen)
4
+ ![Providers](https://img.shields.io/badge/models-OpenRouter%20%C2%B7%20OpenAI%20%C2%B7%20Anthropic%20%C2%B7%20OpenCode-0969da)
2
5
 
3
- [![NPM Version](https://img.shields.io/npm/v/co-maintainer)](https://www.npmjs.com/package/co-maintainer) [![](https://img.shields.io/badge/blog-co_maintainer_an_imitator_of_yours-blue)](https://muratkirazkaya.com/blogs/co-maintainer-an-imitator-of-yours)
6
+ ![co-maintainer](docs/assets/readme/splash.png)
4
7
 
5
- [Website](https://co-maintainer.com) ·
6
- [Docs](https://co-maintainer.com/docs/getting-started.html) ·
7
- [Cloud](https://cloud.co-maintainer.com) (hosted, free, early access, invite only for now)
8
+ # co-maintainer
8
9
 
9
- An imitator of yours, A PR review tool like co-maintainer.
10
+ An open source PR reviewer that learns how your repo is reviewed, then reviews like that.
10
11
 
11
- It collects current code and workflows, selected pull requests and diffs, and
12
- default-branch commits. A low-cost model extracts evidence-bound observations. A
13
- higher-reasoning model turns them into concise contribution guidance for
14
- implementation, testing, review, and release decisions.
12
+ It reads your code, your merged PRs and the review comments on them, and writes
13
+ review guides as plain Markdown. Every review follows those guides. It runs on
14
+ your machine or on your own server, with your own model key.
15
15
 
16
- ## Installation
16
+ [Website](https://co-maintainer.com/?utm_source=github&utm_content=readme) ·
17
+ [Docs](https://co-maintainer.com/docs/getting-started.html?utm_source=github&utm_content=readme) ·
18
+ [Newsletter](https://buttondown.com/murat)
17
19
 
18
20
  ```sh
19
21
  npm install -g co-maintainer
22
+
23
+ co-maintainer probe owner/repo # reads only, spends nothing
24
+ co-maintainer init owner/repo --include-codebase --include-pull-requests \
25
+ --max-pr-months=12 --max-commits=500
26
+ co-maintainer review owner/repo 123 # review a pull request
20
27
  ```
21
28
 
22
- Requires Node.js 24 or newer.
29
+ > [!TIP]
30
+ > `co-maintainer review` with no arguments reviews your local branch before you
31
+ > open the PR. `co-maintainer serve` runs the GitHub App and a dashboard for every
32
+ > repository on your own server.
23
33
 
24
- ## Usage
34
+ <img src="docs/assets/readme/spacer.gif" width="1" height="48"/>
25
35
 
26
- ```sh
27
- co-maintainer probe owner/repo --auth=gh
36
+ ## What it does
28
37
 
29
- co-maintainer init owner/repo --auth=gh --ai=openrouter \
30
- --low-model=openai/gpt-oss-120b \
31
- --high-model=openai/gpt-5.6-luna \
32
- --include-codebase --include-pull-requests \
33
- --include-pull-request-changes --include-commit-history \
34
- --include-how-repo-works
38
+ <table>
39
+ <tr>
40
+ <td><img src="docs/assets/readme/01-finding.png" alt="A P1 finding on PR 54"></td>
41
+ <td><img src="docs/assets/readme/02-ask.png" alt="Asking the reviewer what it meant"></td>
42
+ </tr>
43
+ <tr>
44
+ <td><img src="docs/assets/readme/03-carry-over.png" alt="New, still open and closed findings"></td>
45
+ <td><img src="docs/assets/readme/04-policy.png" alt="Review policy options"></td>
46
+ </tr>
47
+ <tr>
48
+ <td><img src="docs/assets/readme/05-probe.png" alt="probe output before init"></td>
49
+ <td><img src="docs/assets/readme/06-json.png" alt="review --json output for agents"></td>
50
+ </tr>
51
+ </table>
35
52
 
36
- co-maintainer review owner/repo 123 --improve-matrix=2 --debug
53
+ <img src="docs/assets/readme/spacer.gif" width="1" height="32"/>
37
54
 
38
- co-maintainer review # local branch (staged, unstaged, untracked)
39
- co-maintainer review --json # machine-readable stdout, logs on stderr
40
- co-maintainer review --output=github # annotations and a job summary inside GitHub Actions
41
- ```
42
-
43
- Settings live in `config.json`, so a flag you use every time can be saved once:
55
+ ## How it works
44
56
 
45
- ```sh
46
- co-maintainer config set ai openrouter # or openai, anthropic, opencode-zen, opencode-go
47
- co-maintainer config set ai-key sk-or-... # your provider's key (OpenRouter, OpenAI, Anthropic or OpenCode)
48
- co-maintainer config set high-model openai/gpt-5.6-luna
49
- co-maintainer config set low-model openai/gpt-oss-120b
50
- co-maintainer config list # every key, its value and its source
57
+ ```mermaid
58
+ flowchart LR
59
+ A[Your repo<br>code, PRs, review comments] --> B[init]
60
+ B --> C[Review guides<br>plain Markdown]
61
+ C --> D[review]
62
+ E[New merged PRs] --> F[sync] --> C
51
63
  ```
52
64
 
53
- Documentation: [Getting started](https://co-maintainer.com/docs/getting-started.html)
54
- (install to first review) and the [full docs site](https://co-maintainer.com/docs/getting-started.html),
55
- sources in [`docs/md/`](docs/md/).
65
+ A low model reads the history and extracts evidence. A high model writes the
66
+ guides and does the review. You pick both models. Read what it learned with
67
+ `co-maintainer view`.
56
68
 
57
- Use `co-maintainer help`, `co-maintainer -h`, or `co-maintainer --help` for the
58
- full CLI help. Every guide the CLI writes is also readable from the dashboard,
59
- and the dashboard keeps its guides separate from the CLI's. See
60
- [dashboard.md](docs/md/dashboard.md).
69
+ <img src="docs/assets/readme/spacer.gif" width="1" height="32"/>
61
70
 
62
- ## Compared to other tools
71
+ ## Pricing
63
72
 
64
- co-maintainer is a new tool, so it has not been compared with many others yet.
65
- It was benchmarked against [OCR](https://open-codereview.ai/) on `core_v2`. The
66
- datasets are small, so read the numbers as a signal, not a guarantee.
73
+ | Solo | Team | Company |
74
+ | ------------------- | ----------------------------------------- | --------------------------------- |
75
+ | $0 | $0 per seat | $0 forever |
76
+ | The CLI on a laptop | One server, guides shared with `--remote` | Your infrastructure, MIT licensed |
67
77
 
68
- | Claim, as measured on `core_v2` | Result |
69
- | ------------------------------- | ------------------ |
70
- | Result quality against OCR | 2 to 3x better |
71
- | Speed against OCR | 2 to 8x faster |
72
- | Tokens per review against OCR | 70 to 200x fewer |
73
- | Cost per review against OCR | 60 to 270x cheaper |
78
+ You only pay your model provider. No telemetry from the CLI, `serve` or the
79
+ dashboard. How we earn: donations and thanks.
74
80
 
75
- ```mermaid
76
- xychart-beta
77
- title "Monthly PR Review Cost by Developer Count"
78
- x-axis [1, 5, 10, 20, 30, 40, 50, 60, 70, 80, 100]
79
- y-axis "Monthly Cost ($)" 0 --> 13000
80
- line "OCR" [129.6, 648, 1296, 2592, 3888, 5184, 6480, 7776, 9072, 10368, 12960]
81
- line "co-maintainer" [2, 10, 20, 40, 60, 80, 100, 120, 140, 160, 200]
82
- ```
81
+ <img src="docs/assets/readme/spacer.gif" width="1" height="32"/>
83
82
 
84
- _Calculated from co-maintainer's `core_v2` benchmark, which reports co-maintainer as 65x cheaper per review than OCR ($0.025/review vs. $1.62/review). Assumes 80 PR reviews per developer per month (40 PRs merged, about 2 reviews each)._
83
+ ## Benchmark
85
84
 
86
- ## Benchmarks
85
+ `core_v3`: 30 PRs in one target repo, 14 with seeded defects and 16 clean
86
+ controls, so precision is measured too.
87
87
 
88
- `core_v3` fits co-maintainer's use case better than the OCR comparison, so it is
89
- the more meaningful metric here. Unlike the OCR comparison (real human review
90
- comments as gold, see `benchmark/swe-prbench`), `bench core v3` scores against
91
- deliberately seeded, hand-verified defects in a dedicated target repo. Half of
92
- the PRs are kept as defect-free controls, so precision is measurable too, not
93
- just recall. Full breakdown, per-PR results, and methodology:
94
- [`benchmark/core_v3/README.md`](benchmark/core_v3/README.md).
88
+ | Recall | Precision | F1 | Cost / PR | Time / PR |
89
+ | ------ | --------- | ----- | --------- | --------- |
90
+ | 0.857 | 0.353 | 0.500 | $0.0045 | 28.9s |
95
91
 
96
- | metric | value | context |
97
- | ------------- | ----------------------------- | ---------------------------------- |
98
- | PRs reviewed | 30 (14 defective, 16 control) | one target repo |
99
- | F1 | 0.500 | against seeded defects only |
100
- | Precision | 0.353 | 1.00 false positive per control PR |
101
- | Recall | 0.857 | 12 of 14 defects found |
102
- | Avg cost / PR | $0.0045 | low and high model together |
103
- | Avg time / PR | 28.9s | sequential, no concurrency |
92
+ deepseek-v4-flash + gpt-5.6-luna, judge gpt-5.6-luna, 2026-09-14. A small
93
+ dataset, read it as a signal. Details: [`benchmark/core_v3`](benchmark/core_v3/README.md).
104
94
 
105
- ## Development
95
+ <img src="docs/assets/readme/spacer.gif" width="1" height="32"/>
106
96
 
107
- From a checkout:
97
+ ## Development
108
98
 
109
99
  ```sh
110
100
  npm install
@@ -114,4 +104,7 @@ npm run docs:build # rebuild docs/ from docs/md/
114
104
  npm run e2e # end-to-end CLI loop
115
105
  npm run review-local-e2e # fake-AI local review loop
116
106
  npm run dashboard:smoke # browser smoke test
107
+ npm run e2e:simulate # init in a simulated GitHub, see CONTRIBUTING.md
117
108
  ```
109
+
110
+ Made by [Murat Kirazkaya](https://muratkirazkaya.com). If it helps you, a star or a thank you is how this project gets paid.
package/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "co-maintainer",
3
- "version": "0.6.10",
3
+ "version": "0.6.12",
4
4
  "description": "An imitator of yours, A PR review tool like co-maintainer.",
5
5
  "keywords": [
6
6
  "ai",
@@ -54,6 +54,7 @@
54
54
  "swe-prbench-prepare": "node benchmark/swe-prbench/prepare_dataset.ts",
55
55
  "e2e": "node scripts/e2e.ts",
56
56
  "e2e:fake": "node scripts/e2e_fake.ts",
57
+ "e2e:simulate": "node scripts/e2e_simulate.ts",
57
58
  "review-local-e2e": "node scripts/review_local_e2e.ts",
58
59
  "docs:build": "node scripts/build_docs.ts",
59
60
  "pack:smoke": "node scripts/pack_smoke.ts",
@@ -1,6 +1,6 @@
1
1
  import { getEnv } from "../util/runtime.js";
2
2
  import { outputLimitError } from "./provider.js";
3
- import { CliError, EXIT_RUNTIME, EXIT_USAGE, networkFailure, } from "../cli/error.js";
3
+ import { CliError, EXIT_RUNTIME, EXIT_USAGE, networkFailure, readBody, } from "../cli/error.js";
4
4
  /** Required on every Messages request and the only version the errors below
5
5
  * are written against. */
6
6
  export const ANTHROPIC_VERSION = "2023-06-01";
@@ -251,20 +251,20 @@ export class AnthropicProvider {
251
251
  // only a hint (the prompt also asks for a fenced JSON block), so one retry
252
252
  // without it beats failing the review outright.
253
253
  if (response.status === 400 && request.responseFormat) {
254
- const detail = await response.text();
254
+ const detail = await readBody(this.endpoint, response);
255
255
  if (/output_config|json_schema|structured/i.test(detail)) {
256
256
  const { responseFormat: _dropped, ...withoutSchema } = request;
257
257
  response = await this.post(messagesBody(this.model, withoutSchema));
258
258
  if (response.ok) {
259
- return parseMessagesBody((await response.json()), this.model);
259
+ return parseMessagesBody(JSON.parse(await readBody(this.endpoint, response)), this.model);
260
260
  }
261
- throw anthropicError(this.model, response.status, await response.text());
261
+ throw anthropicError(this.model, response.status, await readBody(this.endpoint, response));
262
262
  }
263
263
  throw anthropicError(this.model, response.status, detail);
264
264
  }
265
265
  if (!response.ok) {
266
- throw anthropicError(this.model, response.status, await response.text());
266
+ throw anthropicError(this.model, response.status, await readBody(this.endpoint, response));
267
267
  }
268
- return parseMessagesBody((await response.json()), this.model);
268
+ return parseMessagesBody(JSON.parse(await readBody(this.endpoint, response)), this.model);
269
269
  }
270
270
  }
@@ -15,7 +15,7 @@
15
15
  import { createHash, createPublicKey, randomBytes, randomUUID, verify, } from "node:crypto";
16
16
  import { spawn } from "node:child_process";
17
17
  import { createServer } from "node:http";
18
- import { CliError, EXIT_RUNTIME, EXIT_USAGE, networkFailure, } from "../../cli/error.js";
18
+ import { CliError, EXIT_RUNTIME, EXIT_USAGE, networkFailure, readBody, } from "../../cli/error.js";
19
19
  import { getConfigDir } from "../../config.js";
20
20
  import { chmod, getEnv, isNotFound, mkdir, readTextFileSync, remove, writeTextFile, } from "../../util/runtime.js";
21
21
  import { parseResponsesBody, readResponsesStream, responsesBody, } from "../openai.js";
@@ -45,6 +45,9 @@ function accountBase() {
45
45
  function apiBase() {
46
46
  return (getEnv("CM_SIWC_API_URL") ?? "https://api.openai.com/v1").replace(/\/$/, "");
47
47
  }
48
+ function responsesEndpoint() {
49
+ return `${apiBase()}/responses`;
50
+ }
48
51
  export function credentialsDir() {
49
52
  return getEnv("CM_SIWC_DIR") ?? `${getConfigDir()}/co-maintainer/oauth`;
50
53
  }
@@ -516,7 +519,7 @@ export class SignInWithChatGptProvider {
516
519
  this.model = normalizeModel(model);
517
520
  }
518
521
  async post(accessToken, request) {
519
- const endpoint = `${apiBase()}/responses`;
522
+ const endpoint = responsesEndpoint();
520
523
  try {
521
524
  return await fetch(endpoint, {
522
525
  method: "POST",
@@ -539,10 +542,10 @@ export class SignInWithChatGptProvider {
539
542
  response = await this.post(creds.access_token, request);
540
543
  }
541
544
  if (!response.ok) {
542
- const detail = await response.text();
545
+ const detail = await readBody(responsesEndpoint(), response);
543
546
  throw await planError(creds, this.model, response.status, detail);
544
547
  }
545
- const json = await readResponsesStream(response);
548
+ const json = await readResponsesStream(response, responsesEndpoint());
546
549
  if (json.status === "failed") {
547
550
  const error = (json.error ?? {});
548
551
  throw await planError(creds, this.model, Number(error.status ?? 400), JSON.stringify({ error }));
@@ -49,8 +49,8 @@ export declare function parseResponsesBody(json: Json, model: string, provider?:
49
49
  * fills it). The terminal response supplies `usage` and `status`; the
50
50
  * collected items supply `output`, so the shared {@link parseResponsesBody}
51
51
  * sees the same shape on both routes. A stream with no terminal response
52
- * throws. */
53
- export declare function readResponsesStream(response: Response): Promise<Json>;
52
+ * throws, and one cut mid-way names `url`'s host. */
53
+ export declare function readResponsesStream(response: Response, url: string): Promise<Json>;
54
54
  export declare class OpenAiProvider implements AiProvider {
55
55
  readonly supportsTools = true;
56
56
  private readonly endpoint;
@@ -1,6 +1,6 @@
1
1
  import { getEnv } from "../util/runtime.js";
2
2
  import { outputLimitError, withoutRefusedPart } from "./provider.js";
3
- import { CliError, EXIT_RUNTIME, EXIT_USAGE, networkFailure, } from "../cli/error.js";
3
+ import { CliError, EXIT_RUNTIME, EXIT_USAGE, connectionCut, networkFailure, readBody, } from "../cli/error.js";
4
4
  /** `CM_OPENAI_URL` points at a local fake in tests. Unset means the real
5
5
  * endpoint, so production behavior is unchanged. */
6
6
  export function openAiBase() {
@@ -171,8 +171,8 @@ export function parseResponsesBody(json, model, provider = "openai") {
171
171
  * fills it). The terminal response supplies `usage` and `status`; the
172
172
  * collected items supply `output`, so the shared {@link parseResponsesBody}
173
173
  * sees the same shape on both routes. A stream with no terminal response
174
- * throws. */
175
- export async function readResponsesStream(response) {
174
+ * throws, and one cut mid-way names `url`'s host. */
175
+ export async function readResponsesStream(response, url) {
176
176
  if (!response.body) {
177
177
  throw new Error("OpenAI returned no response body to stream");
178
178
  }
@@ -182,7 +182,16 @@ export async function readResponsesStream(response) {
182
182
  let terminal;
183
183
  const items = [];
184
184
  for (;;) {
185
- const { done, value } = await reader.read();
185
+ let chunk;
186
+ try {
187
+ chunk = await reader.read();
188
+ }
189
+ catch (error) {
190
+ if (error instanceof TypeError)
191
+ throw connectionCut(url, error);
192
+ throw error;
193
+ }
194
+ const { done, value } = chunk;
186
195
  if (done)
187
196
  break;
188
197
  buffer += decoder.decode(value, { stream: true });
@@ -256,9 +265,9 @@ export class OpenAiProvider {
256
265
  for (;;) {
257
266
  const response = await this.post(responsesBody(this.model, current));
258
267
  if (response.ok) {
259
- return parseResponsesBody((await response.json()), this.model);
268
+ return parseResponsesBody(JSON.parse(await readBody(this.endpoint, response)), this.model);
260
269
  }
261
- const detail = await response.text();
270
+ const detail = await readBody(this.endpoint, response);
262
271
  const lighter = response.status === 400
263
272
  ? withoutRefusedPart(current, detail, /text\.format|json_schema|structured/i)
264
273
  : undefined;
@@ -1,6 +1,6 @@
1
1
  import { chatBody, parseChatResponse, withoutRefusedPart } from "./provider.js";
2
2
  import { getEnv } from "../util/runtime.js";
3
- import { CliError, EXIT_RUNTIME, EXIT_USAGE, networkFailure, } from "../cli/error.js";
3
+ import { CliError, EXIT_RUNTIME, EXIT_USAGE, networkFailure, readBody, } from "../cli/error.js";
4
4
  /** `CM_OPENROUTER_URL` points the provider at a local fake in tests. It is
5
5
  * only a default override: with the env unset the real endpoint is used, so
6
6
  * nothing changes for users. */
@@ -79,9 +79,9 @@ export class OpenRouterProvider {
79
79
  for (;;) {
80
80
  const response = await this.post(chatBody(this.model, current));
81
81
  if (response.ok) {
82
- return parseChatResponse((await response.json()), this.host.provider, this.model);
82
+ return parseChatResponse(JSON.parse(await readBody(this.host.endpoint, response)), this.host.provider, this.model);
83
83
  }
84
- const detail = await response.text();
84
+ const detail = await readBody(this.host.endpoint, response);
85
85
  const lighter = response.status === 400
86
86
  ? withoutRefusedPart(current, detail, /response_format|json_schema|structured/i)
87
87
  : undefined;
@@ -37,3 +37,10 @@ export declare function formatError(error: unknown): string;
37
37
  /** A failed `fetch` as a message that names the host and the cause.
38
38
  * Node's own text is only `fetch failed`, which says neither. */
39
39
  export declare function networkFailure(url: string, error: unknown): CliError;
40
+ /** A response whose body stopped arriving, as a message that names the host
41
+ * and the cause. The host was reached, so "Could not reach" would be wrong,
42
+ * and Node's own text is only `terminated`, which says neither. */
43
+ export declare function connectionCut(url: string, error: unknown): CliError;
44
+ /** Reads a response body. fetch rejects with a `TypeError` when the
45
+ * connection closes mid-body; that becomes {@link connectionCut}. */
46
+ export declare function readBody(url: string, response: Response): Promise<string>;
@@ -49,16 +49,39 @@ export function formatError(error) {
49
49
  }
50
50
  return error instanceof Error ? error.message : String(error);
51
51
  }
52
+ function hostOf(url) {
53
+ try {
54
+ return new URL(url).host;
55
+ }
56
+ catch {
57
+ // Keep the raw value when it does not parse.
58
+ return url;
59
+ }
60
+ }
52
61
  /** A failed `fetch` as a message that names the host and the cause.
53
62
  * Node's own text is only `fetch failed`, which says neither. */
54
63
  export function networkFailure(url, error) {
55
64
  const code = error.cause?.code;
56
- let host = url;
65
+ return new CliError("network_failed", `Could not reach ${hostOf(url)}${code ? `: ${code}` : "."}`, undefined, EXIT_RUNTIME);
66
+ }
67
+ /** A response whose body stopped arriving, as a message that names the host
68
+ * and the cause. The host was reached, so "Could not reach" would be wrong,
69
+ * and Node's own text is only `terminated`, which says neither. */
70
+ export function connectionCut(url, error) {
71
+ const cause = error
72
+ .cause;
73
+ const detail = [cause?.code, cause?.message].filter(Boolean).join(": ");
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
+ }
76
+ /** Reads a response body. fetch rejects with a `TypeError` when the
77
+ * connection closes mid-body; that becomes {@link connectionCut}. */
78
+ export async function readBody(url, response) {
57
79
  try {
58
- host = new URL(url).host;
80
+ return await response.text();
59
81
  }
60
- catch {
61
- // Keep the raw value when it does not parse.
82
+ catch (error) {
83
+ if (error instanceof TypeError)
84
+ throw connectionCut(url, error);
85
+ throw error;
62
86
  }
63
- return new CliError("network_failed", `Could not reach ${host}${code ? `: ${code}` : "."}`, undefined, EXIT_RUNTIME);
64
87
  }
@@ -118,7 +118,7 @@ export const ENDPOINTS = [
118
118
  permission: "metadata",
119
119
  level: "read",
120
120
  identities: APP_ONLY,
121
- feature: "Check a commenter on a commit watch issue has write access",
121
+ feature: "Check a commenter has write access before acting on a comment",
122
122
  },
123
123
  {
124
124
  method: "PATCH",
@@ -0,0 +1,7 @@
1
+ /** Who may steer co-maintainer from a comment. A webhook's
2
+ * author_association is only a first filter: MEMBER means a member of the
3
+ * organization and COLLABORATOR may be read-only, so the repository
4
+ * permission is asked from GitHub. */
5
+ import type { GitHubClient } from "../types.ts";
6
+ /** True when `login` can write to `repo`. Any error counts as no. */
7
+ export declare function hasWriteAccess(client: GitHubClient, repo: string, login: string | null | undefined): Promise<boolean>;
@@ -0,0 +1,12 @@
1
+ /** True when `login` can write to `repo`. Any error counts as no. */
2
+ export async function hasWriteAccess(client, repo, login) {
3
+ if (!login)
4
+ return false;
5
+ try {
6
+ const result = await client.request(`repos/${repo}/collaborators/${encodeURIComponent(login)}/permission`);
7
+ return ["admin", "maintain", "write"].includes(String(result.role_name ?? result.permission ?? ""));
8
+ }
9
+ catch {
10
+ return false;
11
+ }
12
+ }
@@ -10,6 +10,8 @@ export type StoredFinding = {
10
10
  anchorText: string | null;
11
11
  severity: string;
12
12
  firstSeenReviewId: string | null;
13
+ /** What maintainers wrote on the finding's inline thread, oldest first. */
14
+ replies?: string[];
13
15
  };
14
16
  export type CarryPrevious = {
15
17
  files: RevisionFile[];
@@ -161,42 +161,40 @@ const VERIFY_HINT = {
161
161
  file_removed: "",
162
162
  unverifiable: "",
163
163
  verify_guide_changed: "review guide was rebuilt",
164
- unchanged: "",
164
+ unchanged: "file unchanged since the last review, the fix may be in another file",
165
165
  verify_present: "still present in changed code",
166
166
  verify_likely_fixed: "anchored code no longer found",
167
167
  verify_unlocated: "could not locate",
168
168
  };
169
169
  export function buildCarryPromptSection(items, current) {
170
170
  const verify = [];
171
- const unchanged = [];
172
171
  let index = 0;
173
172
  for (const item of items) {
174
- if (item.class === "file_reverted" || item.class === "file_removed") {
173
+ if (item.class === "file_reverted" ||
174
+ item.class === "file_removed" ||
175
+ item.class === "unverifiable") {
175
176
  continue;
176
177
  }
178
+ index++;
179
+ const label = `F${index}`;
180
+ item.promptId = label;
181
+ let from = item.lineFrom;
182
+ let to = item.lineTo;
177
183
  if (item.class === "unchanged") {
178
184
  const file = current.files.find((f) => normalizePath(f.path) === normalizePath(item.targetPath ?? ""));
179
185
  const relocated = file
180
186
  ? relocate(item.finding.anchorText, item.lineFrom, file.patch)
181
187
  : null;
182
- const from = relocated?.from ?? item.lineFrom;
183
- const to = relocated?.to ?? item.lineTo;
184
- unchanged.push(`- ${item.targetPath}:${from}${to !== from ? `-${to}` : ""} · ${item.finding.title}`);
185
- continue;
188
+ from = relocated?.from ?? from;
189
+ to = relocated?.to ?? to;
186
190
  }
187
- if (item.class === "unverifiable") {
188
- continue;
189
- }
190
- index++;
191
- const label = `F${index}`;
192
- item.promptId = label;
193
191
  const loc = item.targetPath
194
- ? `${item.targetPath}:${item.lineFrom}${item.lineTo !== item.lineFrom ? `-${item.lineTo}` : ""}`
192
+ ? `${item.targetPath}:${from}${to !== from ? `-${to}` : ""}`
195
193
  : "";
196
194
  const body = item.finding.bodyMd.slice(0, 600);
197
- verify.push(`${label} · ${VERIFY_HINT[item.class]} · ${loc}\n${item.finding.title}\n${body}`);
195
+ verify.push(`${label} · ${VERIFY_HINT[item.class]} · ${loc}\n${item.finding.title}\n${body}${repliesBlock(item.finding.replies)}`);
198
196
  }
199
- if (verify.length === 0 && unchanged.length === 0)
197
+ if (verify.length === 0)
200
198
  return "";
201
199
  const lines = [
202
200
  "PREVIOUS FINDINGS (this run has two separate jobs):",
@@ -205,21 +203,28 @@ export function buildCarryPromptSection(items, current) {
205
203
  " list below shorten or replace that scan. A changed file can contain a",
206
204
  " new finding even when a previous finding already covers its location.",
207
205
  "2. For each entry under VERIFY, decide whether the code in the DIFF still",
208
- " has that problem. Report every decision in a final section headed",
206
+ " has that problem. An entry whose file is unchanged stays open unless",
207
+ " the DIFF fixes it in another file. A maintainer reply that shows the",
208
+ " finding is wrong is a reason to close it, an unexplained objection is",
209
+ " not. Report every decision in a final section headed",
209
210
  ' exactly "## Previous findings", one line per id, exactly as',
210
211
  ' "- F1: open path:from-to" or "- F1: closed".',
211
212
  'Do not repeat an open previous finding under "## Findings"; report there',
212
213
  "only findings from job 1 that are not already covered below.",
213
214
  "",
214
215
  ];
215
- if (verify.length) {
216
- lines.push("VERIFY:", verify.join("\n\n"), "");
217
- }
218
- if (unchanged.length) {
219
- lines.push("STILL OPEN, UNCHANGED (do not report again):", unchanged.join("\n"), "");
220
- }
216
+ lines.push("VERIFY:", verify.join("\n\n"), "");
221
217
  return lines.join("\n");
222
218
  }
219
+ /** At most the last three replies, 1000 characters each. */
220
+ function repliesBlock(replies) {
221
+ if (!replies?.length)
222
+ return "";
223
+ const quoted = replies
224
+ .slice(-3)
225
+ .map((reply) => `> ${reply.slice(0, 1000).replace(/\n/g, "\n> ")}`);
226
+ return `\nMaintainer replies on this finding:\n${quoted.join("\n\n")}`;
227
+ }
223
228
  export function parsePreviousVerdicts(markdown) {
224
229
  const heading = markdown.search(/^## Previous findings\b/im);
225
230
  if (heading === -1)
@@ -252,7 +257,6 @@ export function resolveCarryOutcomes(items, current, visiblePaths, verdicts, par
252
257
  for (const item of items) {
253
258
  if (item.class === "file_reverted" ||
254
259
  item.class === "file_removed" ||
255
- item.class === "unchanged" ||
256
260
  item.class === "unverifiable") {
257
261
  continue;
258
262
  }
@@ -309,7 +313,7 @@ export function resolveCarryOutcomes(items, current, visiblePaths, verdicts, par
309
313
  lineTo = moved.to;
310
314
  }
311
315
  }
312
- if (item.class === "unchanged" || item.class === "unverifiable") {
316
+ if (item.class === "unverifiable") {
313
317
  const row = {
314
318
  id: crypto.randomUUID(),
315
319
  state: "open",
@@ -332,9 +336,12 @@ export function resolveCarryOutcomes(items, current, visiblePaths, verdicts, par
332
336
  const promptId = promptIds.get(base.id);
333
337
  const verdict = promptId ? verdictByPromptId.get(promptId) : undefined;
334
338
  const state = verdict?.state ?? "open";
339
+ // An unchanged file's anchor is read again at the relocated lines.
335
340
  const anchor = file && verdict?.path
336
341
  ? anchorTextFromPatch(file.patch, verdict.from ?? lineFrom, verdict.to ?? verdict.from ?? lineTo)
337
- : base.anchorText;
342
+ : item.class === "unchanged" && file
343
+ ? anchorTextFromPatch(file.patch, lineFrom, lineTo)
344
+ : base.anchorText;
338
345
  const row = {
339
346
  id: crypto.randomUUID(),
340
347
  state,
@@ -47,9 +47,16 @@ export interface ReviewMetadata {
47
47
  durationMs: number;
48
48
  }
49
49
  export declare function formatDuration(ms: number): string;
50
- /** Short summary on the review itself. Findings that map to the diff go
51
- * inline. Leftovers are listed here as one line each, not as a CLI dump. */
52
- export declare function reviewBody(findings: ParsedFinding[], metadata: ReviewMetadata, _inlineCount?: number): string;
50
+ /** A finding an earlier round reported that this round still finds, with the
51
+ * commit that first found it when known. */
52
+ export type StillOpenFinding = {
53
+ finding: ParsedFinding;
54
+ since?: string;
55
+ };
56
+ /** Short summary on the review itself, one line per open finding, split
57
+ * into what this round found and what earlier rounds found that still
58
+ * holds, so a repeat never reads as a new problem. */
59
+ export declare function reviewBody(findings: ParsedFinding[], metadata: ReviewMetadata, stillOpen?: StillOpenFinding[]): string;
53
60
  /** A review job's options: the config, with the job's pinned model (a
54
61
  * "Retry with the same model") over the configured one. */
55
62
  export declare function reviewOptionsForJob(repo: string, prNumber: number, args: {
@@ -71,3 +78,13 @@ export declare function enqueueManualReview(repo: string, prNumber: number, pin?
71
78
  id: string;
72
79
  debounced: boolean;
73
80
  };
81
+ /** The round, scope and base of the next review after `last`. A job queued
82
+ * without them works them out when it starts. */
83
+ export declare function roundArgs(repo: string, last: {
84
+ head_sha: string | null;
85
+ round: number;
86
+ } | undefined): {
87
+ scope: string;
88
+ sinceCommit?: string;
89
+ round: number;
90
+ };
@@ -17,12 +17,13 @@ import { matchRepeat } from "../pr/rounds.js";
17
17
  import { readConfig, resolveAppPrivateKey, resolvedAiToken, } from "../config.js";
18
18
  import { outsideCode, redact } from "../util/redact.js";
19
19
  import { getRepo, setInstallationId } from "../store/repos.js";
20
- import { findNoteCommentId, getReviewByJobId, insertReview, latestPostedReview, setReviewScope, setReviewStatus, } from "../store/reviews.js";
20
+ import { findNoteCommentId, getReview, getReviewByJobId, insertReview, latestPostedReview, setReviewScope, setReviewStatus, } from "../store/reviews.js";
21
21
  import { insertFinding, listCarryableFindingsForReview, listFindingsForPr, listFindingsForReview, setFindingPosted, } from "../store/findings.js";
22
22
  import { getOrCreatePrSubject, getSubjectRevision, parseRevisionFiles, parseVisiblePaths, saveSubjectRevision, } from "../store/subjects.js";
23
23
  import { enqueue, registerHandler } from "./jobs.js";
24
24
  import { requestedReviewBlocked } from "./webhook.js";
25
25
  import { getEnv } from "../util/runtime.js";
26
+ import { hasWriteAccess } from "../github/write_access.js";
26
27
  const ACCESS_DENIED_BODY = "The App does not have access to review this pull request.";
27
28
  /** The first words of the single note a failed review leaves on the pull
28
29
  * request. The note names no provider error and no retry command: both live
@@ -177,19 +178,32 @@ function metadataBlock({ jobId, model, durationMs }) {
177
178
  `- Duration: ${formatDuration(durationMs)}\n` +
178
179
  `</details>`);
179
180
  }
180
- /** Short summary on the review itself. Findings that map to the diff go
181
- * inline. Leftovers are listed here as one line each, not as a CLI dump. */
182
- export function reviewBody(findings, metadata, _inlineCount = 0) {
183
- if (findings.length === 0) {
181
+ function summaryLine(finding, since) {
182
+ const title = humanCopy(finding.heading || finding.path);
183
+ const summary = humanCopy(finding.summary ??
184
+ finding.excerpt.split(/\r?\n/).find((line) => line.trim()) ??
185
+ "");
186
+ const first = since ? ` (first found in ${since.slice(0, 7)})` : "";
187
+ return `- ${title}${summary ? `: ${summary}` : ""}${first}`;
188
+ }
189
+ /** Short summary on the review itself, one line per open finding, split
190
+ * into what this round found and what earlier rounds found that still
191
+ * holds, so a repeat never reads as a new problem. */
192
+ export function reviewBody(findings, metadata, stillOpen = []) {
193
+ if (findings.length === 0 && stillOpen.length === 0) {
184
194
  return `No actionable findings.${metadataBlock(metadata)}`;
185
195
  }
186
- const lines = ["Review summary", ""];
187
- for (const finding of findings) {
188
- const title = humanCopy(finding.heading || finding.path);
189
- const summary = humanCopy(finding.summary ??
190
- finding.excerpt.split(/\r?\n/).find((line) => line.trim()) ??
191
- "");
192
- lines.push(`- ${title}${summary ? `: ${summary}` : ""}`);
196
+ const lines = ["Review summary"];
197
+ if (findings.length) {
198
+ lines.push("", `New (${findings.length})`);
199
+ for (const finding of findings)
200
+ lines.push(summaryLine(finding));
201
+ }
202
+ if (stillOpen.length) {
203
+ lines.push("", `Still open (${stillOpen.length})`);
204
+ for (const { finding, since } of stillOpen) {
205
+ lines.push(summaryLine(finding, since));
206
+ }
193
207
  }
194
208
  return lines.join("\n") + metadataBlock(metadata);
195
209
  }
@@ -237,6 +251,49 @@ async function postedCommentBodies(client, job, log) {
237
251
  return new Map();
238
252
  }
239
253
  }
254
+ /** What people with write access replied on each finding's inline thread,
255
+ * oldest first, keyed by finding id. The next round weighs them when it
256
+ * decides whether the finding still holds. */
257
+ async function findingReplies(client, job, rows, log) {
258
+ const byThread = new Map();
259
+ for (const row of rows) {
260
+ for (const id of [row.posted_comment_id, row.thread_comment_id]) {
261
+ if (id)
262
+ byThread.set(id, row.id);
263
+ }
264
+ }
265
+ const replies = new Map();
266
+ if (byThread.size === 0)
267
+ return replies;
268
+ let listed;
269
+ try {
270
+ listed = await client.pages(`repos/${job.repo}/pulls/${job.pr_number}/comments`);
271
+ }
272
+ catch (error) {
273
+ log("info", `could not read the review threads: ${redact(String(error))}`);
274
+ return replies;
275
+ }
276
+ const access = new Map();
277
+ const sorted = [...listed].sort((a, b) => String(a.created_at ?? "").localeCompare(String(b.created_at ?? "")));
278
+ for (const comment of sorted) {
279
+ const findingId = byThread.get(String(comment.in_reply_to_id ?? ""));
280
+ const user = comment.user;
281
+ const login = String(user?.login ?? "");
282
+ if (!findingId || !login)
283
+ continue;
284
+ if (user?.type === "Bot" || login.endsWith("[bot]"))
285
+ continue;
286
+ if (!access.has(login)) {
287
+ access.set(login, hasWriteAccess(client, job.repo, login));
288
+ }
289
+ if (!(await access.get(login)))
290
+ continue;
291
+ const list = replies.get(findingId) ?? [];
292
+ list.push(String(comment.body ?? ""));
293
+ replies.set(findingId, list);
294
+ }
295
+ return replies;
296
+ }
240
297
  /** A review job's options: the config, with the job's pinned model (a
241
298
  * "Retry with the same model") over the configured one. */
242
299
  export function reviewOptionsForJob(repo, prNumber, args) {
@@ -402,7 +459,7 @@ async function publish(client, job, reviewId, headSha, files, log, metadata, mod
402
459
  });
403
460
  const freshRows = stored.filter((row) => !repeats.includes(row) && (row.state === "new" || row.thread_comment_id));
404
461
  const fresh = freshRows.map(rowFinding);
405
- const { inline, leftover } = splitInline(fresh, files);
462
+ const { inline } = splitInline(fresh, files);
406
463
  const commentByRow = new Map();
407
464
  for (const { finding, anchor, suggestion } of inline) {
408
465
  const row = freshRows.find((item) => item.path === finding.path &&
@@ -415,25 +472,20 @@ async function publish(client, job, reviewId, headSha, files, log, metadata, mod
415
472
  });
416
473
  }
417
474
  }
418
- const freshSummaryKeys = new Set([...leftover, ...inline.map(({ finding }) => finding)].map((finding) => `${finding.path}\0${finding.from}\0${finding.to}`));
419
- const summaryFindings = [
420
- ...leftover,
421
- ...inline.map(({ finding }) => finding),
422
- ...stored
423
- .filter((row) => row.state !== "closed")
424
- .filter((row) => {
425
- const key = `${row.path ?? ""}\0${row.line_from ?? 0}\0${row.line_to ?? row.line_from ?? 0}`;
426
- return !freshSummaryKeys.has(key);
427
- })
428
- .map((row) => ({
429
- path: row.path ?? "",
430
- from: row.line_from ?? 0,
431
- to: row.line_to ?? row.line_from ?? 0,
432
- heading: row.title,
433
- excerpt: row.body_md,
434
- })),
435
- ];
436
- const body = reviewBody(summaryFindings, metadata, inline.length + repeats.length);
475
+ // The summary lists every open finding once, by what this round made of
476
+ // it: found now, or found by an earlier round and still there.
477
+ const summaryFindings = stored
478
+ .filter((row) => row.state === "new")
479
+ .map(rowFinding);
480
+ const stillOpen = stored
481
+ .filter((row) => row.state === "open")
482
+ .map((row) => ({
483
+ finding: rowFinding(row),
484
+ since: row.first_seen_review_id
485
+ ? (getReview(row.first_seen_review_id)?.head_sha ?? undefined)
486
+ : undefined,
487
+ }));
488
+ const body = reviewBody(summaryFindings, metadata, stillOpen);
437
489
  const comments = inline.map(({ finding, anchor, suggestion }) => ({
438
490
  path: finding.path,
439
491
  body: inlineCommentBody(finding, suggestion),
@@ -489,7 +541,7 @@ async function publish(client, job, reviewId, headSha, files, log, metadata, mod
489
541
  if (error instanceof GitHubHttpError && error.status === 422) {
490
542
  log("info", "inline comments rejected, falling back to an issue comment");
491
543
  const posted = await post(client, `repos/${job.repo}/issues/${job.pr_number}/comments`, {
492
- body: reviewBody(summaryFindings, metadata),
544
+ body: reviewBody(summaryFindings, metadata, stillOpen),
493
545
  });
494
546
  setReviewStatus(reviewId, "posted", {
495
547
  posted_review_id: String(posted.id ?? ""),
@@ -604,6 +656,21 @@ async function runReviewJobCore(job, log, client, ai) {
604
656
  }
605
657
  const headSha = String(pr.head?.sha ?? "");
606
658
  const mergeBase = String(pr.base?.sha ?? "");
659
+ if (!existing) {
660
+ const last = latestPostedReview(job.repo, job.pr_number);
661
+ // A review or comment that arrived while a review of this head was
662
+ // running queued this job. That review has posted by now.
663
+ if ((args.trigger === "review" || args.trigger === "review-comment") &&
664
+ last?.head_sha === headSha) {
665
+ log("info", "this head was already reviewed, nothing new to review");
666
+ return;
667
+ }
668
+ // Round and base come from the review that posted last, read now rather
669
+ // than when the job was queued: a review may have posted in between.
670
+ if (args.round === undefined) {
671
+ Object.assign(args, roundArgs(job.repo, last));
672
+ }
673
+ }
607
674
  let scope = args.scope === "incremental" ? "incremental" : "whole-pr";
608
675
  if (scope === "incremental" && !args.sinceCommit) {
609
676
  scope = "whole-pr";
@@ -700,6 +767,7 @@ async function runReviewJobCore(job, log, client, ai) {
700
767
  const { unchanged } = incrementalDiffPaths(revision, prevFiles);
701
768
  extras.unchangedPaths = scope === "incremental" ? unchanged : undefined;
702
769
  const storedRows = listCarryableFindingsForReview(subjectRevision.review_id);
770
+ const replies = await findingReplies(github, job, storedRows, log);
703
771
  carryPrevious = {
704
772
  files: prevFiles,
705
773
  visiblePaths: parseVisiblePaths(subjectRevision),
@@ -713,6 +781,7 @@ async function runReviewJobCore(job, log, client, ai) {
713
781
  anchorText: row.anchor_text,
714
782
  severity: row.severity,
715
783
  firstSeenReviewId: row.first_seen_review_id ?? subjectRevision.review_id,
784
+ replies: replies.get(row.id),
716
785
  })),
717
786
  guideBuiltAt: subjectRevision.guide_built_at,
718
787
  };
@@ -843,19 +912,23 @@ export function registerReviewJobHandler() {
843
912
  * model" asks; without it the job resolves the model from config when it
844
913
  * runs. */
845
914
  export function enqueueManualReview(repo, prNumber, pin = {}) {
846
- const last = latestPostedReview(repo, prNumber);
847
- const row = getRepo(repo);
848
- const incremental = row?.review_scope === "incremental" && Boolean(last?.head_sha);
849
915
  return enqueue({
850
916
  type: "review",
851
917
  repo,
852
918
  prNumber,
853
919
  args: {
854
920
  trigger: "manual",
855
- scope: incremental ? "incremental" : "whole-pr",
856
- sinceCommit: incremental ? last.head_sha : undefined,
857
- round: last ? last.round + 1 : 1,
858
921
  ...(pin.model ? { model: pin.model } : {}),
859
922
  },
860
923
  });
861
924
  }
925
+ /** The round, scope and base of the next review after `last`. A job queued
926
+ * without them works them out when it starts. */
927
+ export function roundArgs(repo, last) {
928
+ const incremental = getRepo(repo)?.review_scope === "incremental" && Boolean(last?.head_sha);
929
+ return {
930
+ scope: incremental ? "incremental" : "whole-pr",
931
+ sinceCommit: incremental ? last.head_sha : undefined,
932
+ round: last ? last.round + 1 : 1,
933
+ };
934
+ }
@@ -13,6 +13,7 @@ import { FakeAiProvider } from "../ai/fake.js";
13
13
  import { completeWithMermaidTools } from "../ai/mermaid_loop.js";
14
14
  import { loadGuides } from "../review/guides.js";
15
15
  import { getEnv } from "../util/runtime.js";
16
+ import { hasWriteAccess } from "../github/write_access.js";
16
17
  import { getWatchIssue, insertWatchNote } from "../store/watch.js";
17
18
  import { registerHandler } from "./jobs.js";
18
19
  import { recordAiCost } from "./setup.js";
@@ -83,20 +84,6 @@ async function alreadyAnswered(client, repo, issueNumber, commentId) {
83
84
  return false;
84
85
  }
85
86
  }
86
- /** True when `login` can write to the repository. The webhook's
87
- * author_association is only a first filter: MEMBER means a member of the
88
- * organization and COLLABORATOR may be read-only. Any error counts as no. */
89
- async function hasWriteAccess(client, repo, login) {
90
- if (!login)
91
- return false;
92
- try {
93
- const result = await client.request(`repos/${repo}/collaborators/${encodeURIComponent(login)}/permission`);
94
- return ["admin", "maintain", "write"].includes(String(result.role_name ?? result.permission ?? ""));
95
- }
96
- catch {
97
- return false;
98
- }
99
- }
100
87
  async function runWatchComment(job, log) {
101
88
  const args = JSON.parse(job.args);
102
89
  const issue = getWatchIssue(job.repo, args.issueNumber);
@@ -201,8 +201,7 @@ export function maybeEnqueueReview(input) {
201
201
  earlier.round >= policy.maxRounds) {
202
202
  return skipped(`Round limit reached: ${earlier.round} of ${policy.maxRounds} reviews.`);
203
203
  }
204
- const last = earlier;
205
- const incremental = row.review_scope === "incremental" && Boolean(last?.head_sha);
204
+ // Round, scope and base are worked out when the job starts.
206
205
  const { id } = enqueue({
207
206
  type: "review",
208
207
  repo: input.repo,
@@ -211,9 +210,6 @@ export function maybeEnqueueReview(input) {
211
210
  debounceMs: REVIEW_DEBOUNCE_MS,
212
211
  args: {
213
212
  trigger: input.trigger,
214
- scope: incremental ? "incremental" : "whole-pr",
215
- sinceCommit: incremental ? last.head_sha : undefined,
216
- round: last ? last.round + 1 : 1,
217
213
  requestReaction: input.request?.reaction,
218
214
  },
219
215
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "co-maintainer",
3
- "version": "0.6.10",
3
+ "version": "0.6.12",
4
4
  "description": "An imitator of yours, A PR review tool like co-maintainer.",
5
5
  "keywords": [
6
6
  "ai",
@@ -54,6 +54,7 @@
54
54
  "swe-prbench-prepare": "node benchmark/swe-prbench/prepare_dataset.ts",
55
55
  "e2e": "node scripts/e2e.ts",
56
56
  "e2e:fake": "node scripts/e2e_fake.ts",
57
+ "e2e:simulate": "node scripts/e2e_simulate.ts",
57
58
  "review-local-e2e": "node scripts/review_local_e2e.ts",
58
59
  "docs:build": "node scripts/build_docs.ts",
59
60
  "pack:smoke": "node scripts/pack_smoke.ts",