co-maintainer 0.5.4 → 0.6.0

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/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "co-maintainer",
3
- "version": "0.5.4",
3
+ "version": "0.6.0",
4
4
  "description": "An imitator of yours, A PR review tool like co-maintainer.",
5
5
  "keywords": [
6
6
  "ai",
@@ -5,12 +5,20 @@ type UsageSink = (job: string, response: AiResponse) => Promise<void>;
5
5
  * fine HTTP response can still be unparseable output, and caching that is what
6
6
  * poisoned every later `sync`. */
7
7
  export type AiValidator = (request: AiRequest, response: AiResponse) => string | null;
8
- /** A unit whose output never parsed, kept so the run can say what it dropped. */
9
- export type SkippedUnit = {
10
- index: number;
11
- job: string;
12
- reason: string;
13
- };
8
+ /** A provider call and an unusable response are both retried this many times
9
+ * before the batch gives up and the run fails. */
10
+ export declare const MAX_ATTEMPTS = 3;
11
+ /** A rate-limited unit gets more tries than a broken one. The provider needs a
12
+ * window to recover, and giving up after three fast retries fails a run that
13
+ * would have gone through a minute later. Only `429`/`rate limit` failures use
14
+ * this bound. */
15
+ export declare const MAX_RATE_LIMIT_ATTEMPTS = 6;
16
+ /** True when a failure is the provider throttling, not a broken request. */
17
+ export declare function isRateLimit(reason: string): boolean;
18
+ /** How long to wait before the next attempt. Zero unless the failure is a rate
19
+ * limit, so every other failure retries immediately. Exported so the schedule
20
+ * can be tested without waiting on it. */
21
+ export declare function retryDelayMs(reason: string, attempt: number): number;
14
22
  export declare class AiBatch {
15
23
  private records;
16
24
  private loaded;
@@ -20,19 +28,14 @@ export declare class AiBatch {
20
28
  private readonly concurrency;
21
29
  private readonly profile;
22
30
  private readonly validate?;
23
- private readonly skipped;
24
31
  constructor(provider: AiProvider, repo: string, concurrency: number, profile: string, validate?: AiValidator);
25
- /** Units whose output did not parse this run (or on re-try), in request order. */
26
- skippedUnits(): SkippedUnit[];
27
32
  run(requests: AiRequest[], usage?: UsageSink): Promise<(AiResponse | undefined)[]>;
28
- /** Runs one unit, caching its response only when the validator accepts it.
29
- * A rejected response is retried once; a second rejection is recorded as
30
- * skipped and never cached, so the next `sync` retries it rather than
31
- * replaying the same unusable output. */
33
+ /** Runs one unit, retrying a provider error and a response the validator
34
+ * rejects. It never throws: a provider error that outlives its retries drops
35
+ * the unit, and a response that still does not validate is used anyway. A run
36
+ * that has already paid for extraction must still write what it has; a format
37
+ * deviation is not worth losing the whole run over. */
32
38
  private completeUnit;
33
- /** Records a unit as skipped: no cache write, so it stays retried and its
34
- * absence is never mistaken for a deliberate empty result. */
35
- private markSkipped;
36
39
  private load;
37
40
  private persist;
38
41
  }
@@ -1,6 +1,27 @@
1
1
  import { cacheGet, cacheSet } from "../store/cache_db.js";
2
2
  import { isNotFound, readTextFile } from "../util/runtime.js";
3
3
  import { formatError } from "../cli/error.js";
4
+ /** A provider call and an unusable response are both retried this many times
5
+ * before the batch gives up and the run fails. */
6
+ export const MAX_ATTEMPTS = 3;
7
+ /** A rate-limited unit gets more tries than a broken one. The provider needs a
8
+ * window to recover, and giving up after three fast retries fails a run that
9
+ * would have gone through a minute later. Only `429`/`rate limit` failures use
10
+ * this bound. */
11
+ export const MAX_RATE_LIMIT_ATTEMPTS = 6;
12
+ const RATE_LIMIT_BACKOFF_MS = [5_000, 15_000, 30_000, 45_000, 60_000];
13
+ /** True when a failure is the provider throttling, not a broken request. */
14
+ export function isRateLimit(reason) {
15
+ return /429|rate limit/i.test(reason);
16
+ }
17
+ /** How long to wait before the next attempt. Zero unless the failure is a rate
18
+ * limit, so every other failure retries immediately. Exported so the schedule
19
+ * can be tested without waiting on it. */
20
+ export function retryDelayMs(reason, attempt) {
21
+ if (!isRateLimit(reason))
22
+ return 0;
23
+ return RATE_LIMIT_BACKOFF_MS[Math.min(attempt - 1, RATE_LIMIT_BACKOFF_MS.length - 1)];
24
+ }
4
25
  async function digest(value) {
5
26
  const bytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
6
27
  return [...new Uint8Array(bytes)]
@@ -16,7 +37,6 @@ export class AiBatch {
16
37
  concurrency;
17
38
  profile;
18
39
  validate;
19
- skipped = [];
20
40
  constructor(provider, repo, concurrency, profile, validate) {
21
41
  this.provider = provider;
22
42
  this.repo = repo;
@@ -24,10 +44,6 @@ export class AiBatch {
24
44
  this.profile = profile;
25
45
  this.validate = validate;
26
46
  }
27
- /** Units whose output did not parse this run (or on re-try), in request order. */
28
- skippedUnits() {
29
- return [...this.skipped];
30
- }
31
47
  async run(requests, usage) {
32
48
  await this.load();
33
49
  const results = new Array(requests.length);
@@ -59,7 +75,11 @@ export class AiBatch {
59
75
  }
60
76
  }
61
77
  else if (cached?.status === "quarantine") {
62
- console.log(`[ai] quarantined job skipped: ${request.job} ${id.slice(0, 8)}`);
78
+ // A provider error from an earlier run is not a permanent verdict: drop
79
+ // the record and try again rather than skipping it forever.
80
+ delete this.records[id];
81
+ await this.persist();
82
+ pending.push({ index, id, request });
63
83
  }
64
84
  else {
65
85
  pending.push({ index, id, request });
@@ -88,57 +108,59 @@ export class AiBatch {
88
108
  await this.saveChain;
89
109
  return results;
90
110
  }
91
- /** Runs one unit, caching its response only when the validator accepts it.
92
- * A rejected response is retried once; a second rejection is recorded as
93
- * skipped and never cached, so the next `sync` retries it rather than
94
- * replaying the same unusable output. */
111
+ /** Runs one unit, retrying a provider error and a response the validator
112
+ * rejects. It never throws: a provider error that outlives its retries drops
113
+ * the unit, and a response that still does not validate is used anyway. A run
114
+ * that has already paid for extraction must still write what it has; a format
115
+ * deviation is not worth losing the whole run over. */
95
116
  async completeUnit(item, results, usage, startedAt) {
96
- for (const attempt of [1, 2]) {
117
+ for (let attempt = 1;; attempt++) {
118
+ let response;
97
119
  try {
98
- const response = await this.provider.complete(item.request);
99
- const reason = this.validate?.(item.request, response) ?? null;
100
- if (reason !== null) {
101
- if (attempt === 2) {
102
- this.markSkipped(item, reason);
103
- return;
120
+ response = await this.provider.complete(item.request);
121
+ }
122
+ catch (error) {
123
+ const reason = formatError(error);
124
+ const limit = isRateLimit(reason)
125
+ ? MAX_RATE_LIMIT_ATTEMPTS
126
+ : MAX_ATTEMPTS;
127
+ console.log(`[ai] call failed ${attempt}/${limit} ${item.request.job} ${item.id.slice(0, 8)}: ${reason}`);
128
+ if (attempt < limit) {
129
+ const wait = retryDelayMs(reason, attempt);
130
+ if (wait > 0) {
131
+ console.log(`[ai] waiting ${Math.round(wait / 1000)}s before retry (provider is rate limiting)`);
132
+ await new Promise((resolve) => setTimeout(resolve, wait));
104
133
  }
105
- console.log(`[ai] retrying ${item.request.job} ${item.id.slice(0, 8)}: ${reason}`);
106
134
  continue;
107
135
  }
108
- this.records[item.id] = {
109
- status: "done",
110
- response,
111
- updatedAt: new Date().toISOString(),
112
- };
113
- results[item.index] = response;
114
- await this.persist();
115
- if (usage)
116
- await usage(item.request.job, response);
117
- console.log(`[ai] ${attempt === 1 ? "done" : "retried"} ${item.request.job} ${item.id.slice(0, 8)} · ${Math.round((Date.now() - startedAt) / 1000)}s`);
136
+ console.log(`[ai] gave up ${item.request.job} ${item.id.slice(0, 8)} after ${attempt} attempts; continuing without it`);
118
137
  return;
119
138
  }
120
- catch (error) {
121
- this.records[item.id] = {
122
- status: "quarantine",
123
- error: formatError(error),
124
- updatedAt: new Date().toISOString(),
125
- };
126
- await this.persist();
127
- console.log(`[ai] quarantined ${item.request.job} ${item.id.slice(0, 8)}: ${formatError(error)}`);
139
+ const reason = this.validate?.(item.request, response) ?? null;
140
+ if (reason !== null && attempt < MAX_ATTEMPTS) {
141
+ console.log(`[ai] output rejected ${attempt}/${MAX_ATTEMPTS} ${item.request.job} ${item.id.slice(0, 8)}: ${reason}`);
142
+ continue;
143
+ }
144
+ if (reason !== null) {
145
+ // The last attempt still failed its contract. Do not cache it, so a
146
+ // later sync retries instead of replaying the same unusable output, and
147
+ // do not throw: the run keeps its other work.
148
+ console.log(`[ai] dropping ${item.request.job} ${item.id.slice(0, 8)} after ${attempt} attempts: ${reason}`);
128
149
  return;
129
150
  }
151
+ this.records[item.id] = {
152
+ status: "done",
153
+ response,
154
+ updatedAt: new Date().toISOString(),
155
+ };
156
+ results[item.index] = response;
157
+ await this.persist();
158
+ if (usage)
159
+ await usage(item.request.job, response);
160
+ console.log(`[ai] ${attempt === 1 ? "done" : `retried (${attempt})`} ${item.request.job} ${item.id.slice(0, 8)} · ${Math.round((Date.now() - startedAt) / 1000)}s`);
161
+ return;
130
162
  }
131
163
  }
132
- /** Records a unit as skipped: no cache write, so it stays retried and its
133
- * absence is never mistaken for a deliberate empty result. */
134
- markSkipped(item, reason) {
135
- this.skipped.push({
136
- index: item.index,
137
- job: item.request.job,
138
- reason,
139
- });
140
- console.log(`[ai] skipped ${item.request.job} ${item.index}: ${reason}`);
141
- }
142
164
  async load() {
143
165
  if (this.loaded)
144
166
  return;
@@ -201,7 +201,7 @@ export async function parseArgs(args) {
201
201
  }
202
202
  }
203
203
  else if (!explicitAi && !configuredAi && command !== "probe") {
204
- const selected = await ask(`AI provider (${AI_PROVIDERS.join("|")})`, "openrouter");
204
+ const selected = await ask(`AI provider (${AI_PROVIDERS.filter((p) => p !== "none").join("|")})`, "openrouter");
205
205
  rejectRetiredProvider(selected);
206
206
  if (!AI_PROVIDERS.includes(selected)) {
207
207
  die(`AI provider must be one of: ${AI_PROVIDERS.join(", ")}`);
@@ -264,7 +264,7 @@ export async function parseArgs(args) {
264
264
  aiToken,
265
265
  lowModel,
266
266
  highModel,
267
- synthesisVersion: 16,
267
+ synthesisVersion: 17,
268
268
  includeCodebase: enabled("include-codebase"),
269
269
  includePullRequests: enabled("include-pull-requests"),
270
270
  includePullRequestChanges: enabled("include-pull-request-changes"),
@@ -30,6 +30,24 @@ const REVIEW_OUTPUT_FLAGS = {
30
30
  },
31
31
  ],
32
32
  };
33
+ const AI_KEY_FLAGS = [
34
+ { name: "token", value: "KEY", description: "The provider API key." },
35
+ {
36
+ name: "ai-key",
37
+ value: "KEY",
38
+ description: "The same key as --token, named for what it is.",
39
+ },
40
+ {
41
+ name: "low-model",
42
+ value: "ID",
43
+ description: "Model for extraction work.",
44
+ },
45
+ {
46
+ name: "high-model",
47
+ value: "ID",
48
+ description: "Model for the review itself.",
49
+ },
50
+ ];
33
51
  const AI_FLAGS = {
34
52
  title: "AI",
35
53
  flags: [
@@ -37,24 +55,22 @@ const AI_FLAGS = {
37
55
  name: "ai",
38
56
  value: AI_PROVIDERS.join("|"),
39
57
  default: "none",
40
- description: "Which provider writes the review.",
41
- },
42
- { name: "token", value: "KEY", description: "The provider API key." },
43
- {
44
- name: "ai-key",
45
- value: "KEY",
46
- description: "The same key as --token, named for what it is.",
47
- },
48
- {
49
- name: "low-model",
50
- value: "ID",
51
- description: "Model for extraction work.",
58
+ description: "Which provider writes the review. `none` turns AI off.",
52
59
  },
60
+ ...AI_KEY_FLAGS,
61
+ ],
62
+ };
63
+ /** `init` and `sync` author every guide with AI, so no provider is not a
64
+ * choice there. */
65
+ const AI_FLAGS_REQUIRED = {
66
+ title: "AI",
67
+ flags: [
53
68
  {
54
- name: "high-model",
55
- value: "ID",
56
- description: "Model for the review itself.",
69
+ name: "ai",
70
+ value: AI_PROVIDERS.filter((provider) => provider !== "none").join("|"),
71
+ description: "Which provider writes the guides. Required: init and sync cannot run without one.",
57
72
  },
73
+ ...AI_KEY_FLAGS,
58
74
  ],
59
75
  };
60
76
  const GITHUB_FLAGS = {
@@ -186,7 +202,7 @@ export const COMMANDS = [
186
202
  },
187
203
  ],
188
204
  },
189
- AI_FLAGS,
205
+ AI_FLAGS_REQUIRED,
190
206
  GITHUB_FLAGS,
191
207
  OUTPUT_FLAGS,
192
208
  {
@@ -273,7 +289,7 @@ export const COMMANDS = [
273
289
  },
274
290
  ],
275
291
  },
276
- AI_FLAGS,
292
+ AI_FLAGS_REQUIRED,
277
293
  GITHUB_FLAGS,
278
294
  OUTPUT_FLAGS,
279
295
  ],
@@ -303,6 +303,7 @@ async function pullRequests(client, options, previous, phase, progress) {
303
303
  additions: Number(detail?.additions ?? cached?.additions ?? 0),
304
304
  deletions: Number(detail?.deletions ?? cached?.deletions ?? 0),
305
305
  comments: cached?.comments ?? [],
306
+ reviewComments: cached?.reviewComments ?? [],
306
307
  reviews: cached?.reviews ?? [],
307
308
  changedFiles: cached?.changedFiles ?? [],
308
309
  diff: cached?.diff ?? "",
@@ -325,6 +326,20 @@ async function pullRequests(client, options, previous, phase, progress) {
325
326
  .filter(Boolean)
326
327
  .slice(0, options.maxComments);
327
328
  };
329
+ // Inline review comments carry most of the substantive feedback, and the
330
+ // reviewer only sees them if they are read here.
331
+ const loadReviewComments = async () => {
332
+ const comments = await client.pages(`repos/${options.repo}/pulls/${number}/comments`);
333
+ current.reviewComments = comments
334
+ .map((comment) => {
335
+ const path = String(comment.path ?? "");
336
+ const line = String(comment.line ?? comment.original_line ?? "");
337
+ const body = String(comment.body ?? "");
338
+ return path ? `${path}:${line} ${body}` : body;
339
+ })
340
+ .filter(Boolean)
341
+ .slice(0, options.maxComments);
342
+ };
328
343
  const loadReviews = async () => {
329
344
  const reviews = await client.pages(`repos/${options.repo}/pulls/${number}/reviews`);
330
345
  current.reviews = reviewBodies(reviews);
@@ -334,11 +349,14 @@ async function pullRequests(client, options, previous, phase, progress) {
334
349
  await loadReviews();
335
350
  if (!current.changesRequested)
336
351
  dropped = true;
337
- else if (!discussionUnchanged)
352
+ else if (!discussionUnchanged) {
338
353
  await loadComments();
354
+ await loadReviewComments();
355
+ }
339
356
  }
340
357
  else if (!dropped && !discussionUnchanged) {
341
358
  await loadComments();
359
+ await loadReviewComments();
342
360
  await loadReviews();
343
361
  }
344
362
  const discussionStatus = dropped
@@ -1,14 +1,29 @@
1
+ import type { AiProvider, AiResponse, Options } from "../types.ts";
1
2
  import type { Fact } from "./types.ts";
2
3
  export type ReviewDocuments = {
3
4
  guide: string;
4
5
  detailed?: string;
5
6
  };
7
+ type UsageSink = (job: string, response: AiResponse) => Promise<void>;
6
8
  /** A fact read out of a single pull request describes that request, not the
7
9
  * repository. `origin` is absent on facts written before the field existed, so
8
10
  * those count as repository policy. */
9
11
  export declare function isPullRequestFact(item: Fact): boolean;
10
- /** The selected review signals, before the `>2` threshold is applied. Exported
11
- * so `init` can tell the user how far short of the threshold a repository is,
12
- * rather than silently skipping the two guide files. */
12
+ /** The selected review findings before the frequency threshold is applied.
13
+ * Exported so `init` can tell the user how far short of the threshold a
14
+ * repository is instead of silently skipping the guide. */
13
15
  export declare function reviewSignalCount(facts: Fact[]): number;
14
- export declare function buildReviewDocuments(facts: Fact[]): ReviewDocuments | undefined;
16
+ /** The guide's concreteness contract. Returns `null` when usable, else the
17
+ * reason the batch retries on. This is the context-loss detector: a rule that
18
+ * could sit in any repository's guide fails it, and it also forces the guide to
19
+ * be a small set of coherent passes rather than one area per finding. */
20
+ export declare function validateGuide(text: string, options?: {
21
+ minChecks?: number;
22
+ minPasses?: number;
23
+ maxPasses?: number;
24
+ }): string | null;
25
+ /** Builds the review method with the high model. Returns `undefined` below the
26
+ * signal threshold, which is a data condition, not an AI failure. There is no
27
+ * deterministic fallback: a failed or unusable generation fails the run. */
28
+ export declare function synthesizeReviewGuides(provider: AiProvider, repo: string, ai: Options["ai"], model: string, concurrency: number, facts: Fact[], usage?: UsageSink): Promise<ReviewDocuments | undefined>;
29
+ export {};