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.
@@ -19,40 +19,95 @@ function slug(value) {
19
19
  function promptText(value, limit = 6_000) {
20
20
  return value.length > limit ? `${value.slice(0, limit)}\n[truncated]` : value;
21
21
  }
22
+ function tryParse(value) {
23
+ try {
24
+ return JSON.parse(value);
25
+ }
26
+ catch {
27
+ return undefined;
28
+ }
29
+ }
30
+ /** Every balanced top-level `[...]` in the text, string-aware so a `[` inside a
31
+ * string does not shift the depth. */
32
+ function balancedArrays(text) {
33
+ const out = [];
34
+ let depth = 0;
35
+ let start = -1;
36
+ let inString = false;
37
+ let escape = false;
38
+ for (let index = 0; index < text.length; index++) {
39
+ const char = text[index];
40
+ if (inString) {
41
+ if (escape)
42
+ escape = false;
43
+ else if (char === "\\")
44
+ escape = true;
45
+ else if (char === '"')
46
+ inString = false;
47
+ continue;
48
+ }
49
+ if (char === '"')
50
+ inString = true;
51
+ else if (char === "[") {
52
+ if (depth === 0)
53
+ start = index;
54
+ depth++;
55
+ }
56
+ else if (char === "]" && depth > 0) {
57
+ depth--;
58
+ if (depth === 0 && start >= 0) {
59
+ out.push(text.slice(start, index + 1));
60
+ start = -1;
61
+ }
62
+ }
63
+ }
64
+ return out;
65
+ }
22
66
  function parseJson(text) {
23
67
  const cleaned = text
24
68
  .trim()
25
69
  .replace(/^```(?:json)?\s*/i, "")
26
70
  .replace(/\s*```$/, "");
27
- try {
28
- return JSON.parse(cleaned);
29
- }
30
- catch {
31
- const start = cleaned.indexOf("[");
32
- const end = cleaned.lastIndexOf("]");
33
- if (start < 0)
34
- throw new Error("AI fact output is not JSON");
35
- if (end > start)
36
- return JSON.parse(cleaned.slice(start, end + 1));
37
- const lastCompleteObject = cleaned.lastIndexOf("}");
38
- if (lastCompleteObject <= start) {
39
- throw new Error("AI fact output is truncated");
40
- }
41
- return JSON.parse(`${cleaned.slice(start, lastCompleteObject + 1)}]`);
71
+ const direct = tryParse(cleaned);
72
+ if (direct !== undefined)
73
+ return direct;
74
+ // The model sometimes appends a second array (for example `[]` then the real
75
+ // one), so the first-to-last-bracket slice is wrong. Read every balanced
76
+ // top-level array and prefer the first non-empty one.
77
+ const parsed = balancedArrays(cleaned)
78
+ .map((chunk) => tryParse(chunk))
79
+ .filter((value) => Array.isArray(value));
80
+ const nonEmpty = parsed.find((value) => value.length > 0);
81
+ if (nonEmpty)
82
+ return nonEmpty;
83
+ if (parsed.length)
84
+ return parsed[0];
85
+ // Last resort: repair an array whose final bracket was truncated.
86
+ // Nothing usable: return an empty list rather than throw. A format deviation
87
+ // must not cost the whole run.
88
+ const start = cleaned.indexOf("[");
89
+ if (start < 0)
90
+ return [];
91
+ const lastObject = cleaned.lastIndexOf("}");
92
+ if (lastObject > start) {
93
+ const repaired = tryParse(`${cleaned.slice(start, lastObject + 1)}]`);
94
+ if (repaired !== undefined)
95
+ return repaired;
42
96
  }
97
+ return [];
43
98
  }
44
99
  function factsFromResponse(text, evidence, defaultScope, origin) {
45
100
  const parsed = parseJson(text);
46
- if (!Array.isArray(parsed)) {
47
- throw new Error("AI fact output must be an array");
48
- }
101
+ if (!Array.isArray(parsed))
102
+ return [];
49
103
  return parsed.flatMap((item) => {
50
104
  if (!item || typeof item !== "object")
51
105
  return [];
52
106
  const value = item;
53
107
  const claim = String(value.claim ?? "").trim();
54
108
  const sectionKey = String(value.sectionKey ?? "").trim();
55
- if (!claim || !allowedSections.has(sectionKey))
109
+ const isReview = sectionKey === "review";
110
+ if (!claim || (!isReview && !allowedSections.has(sectionKey)))
56
111
  return [];
57
112
  const scope = value.scope === "current" ||
58
113
  value.scope === "repeated-history" ||
@@ -64,6 +119,14 @@ function factsFromResponse(text, evidence, defaultScope, origin) {
64
119
  value.confidence === "low"
65
120
  ? value.confidence
66
121
  : "medium";
122
+ // A review finding without an impact and an action is the generic advice
123
+ // that made the old guide hollow, so it is dropped rather than stored.
124
+ const impact = String(value.impact ?? "").trim();
125
+ const action = String(value.action ?? "").trim();
126
+ const location = String(value.location ?? "").trim();
127
+ const trigger = String(value.trigger ?? "").trim();
128
+ if (isReview && (!impact || !action))
129
+ return [];
67
130
  return [
68
131
  {
69
132
  id: `${sectionKey}:${slug(claim)}`,
@@ -75,6 +138,15 @@ function factsFromResponse(text, evidence, defaultScope, origin) {
75
138
  confidence,
76
139
  status: "active",
77
140
  origin,
141
+ ...(isReview
142
+ ? {
143
+ class: String(value.class ?? "general").trim() || "general",
144
+ ...(location ? { location } : {}),
145
+ ...(trigger ? { trigger } : {}),
146
+ impact,
147
+ action,
148
+ }
149
+ : {}),
78
150
  },
79
151
  ];
80
152
  });
@@ -121,18 +193,34 @@ function pullRequestUnit(pr) {
121
193
  body: promptText(pr.body),
122
194
  labels: pr.labels,
123
195
  comments: pr.comments.map((comment) => promptText(comment, 2_000)),
196
+ reviewComments: pr.reviewComments.map((comment) => promptText(comment, 2_000)),
124
197
  reviews: pr.reviews.map((review) => promptText(review, 2_000)),
125
198
  changedFiles: pr.changedFiles,
126
199
  diff: promptText(pr.diff, 8_000),
127
200
  });
128
201
  }
129
202
  function queueFor(provider, repo, ai, model, concurrency, validate) {
130
- return new AiBatch(provider, repo, Math.max(1, concurrency), `${ai}:v2:${model}`, validate);
203
+ return new AiBatch(provider, repo, Math.max(1, concurrency), `${ai}:v3:${model}`, validate);
131
204
  }
132
205
  /** `factsFromResponse` as a validator: `null` when the text parses into facts,
133
206
  * otherwise the parse error's message. Used so an unparseable response is never
134
207
  * cached. */
208
+ /** Whether the response contains a parseable JSON array at all. `parseJson`
209
+ * returns `[]` for anything it cannot read, so this is the only way to tell an
210
+ * empty-but-valid answer from garbage that must not be cached as a result. */
211
+ function hasJsonArray(text) {
212
+ const cleaned = text
213
+ .trim()
214
+ .replace(/^```(?:json)?\s*/i, "")
215
+ .replace(/\s*```$/, "");
216
+ if (Array.isArray(tryParse(cleaned)))
217
+ return true;
218
+ return balancedArrays(cleaned).some((chunk) => Array.isArray(tryParse(chunk)));
219
+ }
135
220
  function validateFacts(response, evidence, defaultScope) {
221
+ if (!hasJsonArray(response.text)) {
222
+ return `${evidence}: AI fact output is not a JSON array`;
223
+ }
136
224
  try {
137
225
  factsFromResponse(response.text, evidence, defaultScope, "repository");
138
226
  return null;
@@ -142,40 +230,29 @@ function validateFacts(response, evidence, defaultScope) {
142
230
  return `${evidence}: ${message}`;
143
231
  }
144
232
  }
145
- /** `validSection` as a validator: `null` when the section body is usable,
146
- * otherwise a short reason. A section that is empty or malformed is retried
147
- * once and then left uncached, so a later `sync` does not replay it. */
148
- function validateSection(response, key) {
149
- const section = cleanSection(response.text, key);
150
- if (!validSection(section, key)) {
151
- return "synthesis output is not a valid section";
152
- }
153
- return null;
154
- }
155
233
  function extractRequest(prompt, maxTokens) {
156
234
  return {
157
235
  job: "extract_unit",
158
236
  prompt,
159
237
  maxTokens,
160
- // Pulling facts out of a text needs no thinking, and on a thinking model
161
- // the thinking used the whole limit and left the answer empty.
162
- reasoningEffort: "none",
163
- system: "Extract only repository-specific facts. Never invent files, commands, or process.",
238
+ // Reading a discussion into structured findings is multi-step work: with no
239
+ // thinking the model returned an empty array for most pull requests, so a
240
+ // little reasoning is allowed (the answer still fits the token budget).
241
+ reasoningEffort: "low",
242
+ system: 'Extract only repository-specific facts and review findings. Never invent files, commands, or process. Never write a pull-request number, a commit id, a reviewer name, or quoted comment text in a claim. A review finding (sectionKey "review") states a concrete rule with an impact and an action.',
164
243
  };
165
244
  }
166
245
  function cleanSection(text, key) {
167
- const clean = text.replace(/^\s*```[a-zA-Z0-9_-]*\s*$/gm, "").trim();
168
- const heading = sectionTitles[key] ?? key;
169
- return clean.replace(/^##\s+.+$/m, `## ${heading}`);
170
- }
171
- function validSection(text, key) {
246
+ const clean = text
247
+ .replace(/^\s*```[a-zA-Z0-9_-]*\s*$/gm, "")
248
+ .replace(/```/g, "")
249
+ .trim();
172
250
  const heading = `## ${sectionTitles[key] ?? key}`;
173
- const bullets = text.match(/^-\s+/gm) ?? [];
174
- return (text.startsWith(heading) &&
175
- bullets.length > 0 &&
176
- bullets.length <= 6 &&
177
- !text.includes("```") &&
178
- !/\b(?:TODO|TBD)\b/i.test(text));
251
+ // Guarantee the heading the skill assembler keys on, and keep whatever body
252
+ // the model produced rather than rejecting it.
253
+ if (/^##\s+.+$/m.test(clean))
254
+ return clean.replace(/^##\s+.+$/m, heading);
255
+ return clean ? `${heading}\n\n${clean}` : heading;
179
256
  }
180
257
  function sectionGoal(key) {
181
258
  const goals = {
@@ -210,22 +287,26 @@ function synthesisFacts(facts, key) {
210
287
  .slice(0, 20));
211
288
  }
212
289
  export async function extractAiFacts(provider, repo, source, options, usage) {
213
- return (await extractAiFactsWithReport(provider, repo, source, options, usage)).facts;
214
- }
215
- export async function extractAiFactsWithReport(provider, repo, source, options, usage) {
216
290
  const requests = [];
217
291
  const evidence = [];
218
292
  const scopes = [];
219
293
  const prs = options.includePullRequests ? source.pullRequests : [];
220
294
  for (const pr of prs) {
221
- requests.push(extractRequest(`Analyze this pull request and return only a JSON array of atomic observations. Each item must have exactly:
222
- {"sectionKey":"one allowed section","claim":"one directly evidenced observation","scope":"historical-example","confidence":"medium"}
223
- Allowed sections: ${[...allowedSections].join(", ")}
224
- Use evidence from this PR only. Do not generalize this PR into a repository-wide policy.
225
- Return at most 6 items. Keep each claim under 180 characters. Do not explain the answer.
295
+ requests.push(extractRequest(`Analyze this pull request's reviews, comments, code and diff, and return only a JSON array of review findings.
296
+ Each item must have exactly:
297
+ {"sectionKey":"review","class":"a short area name","claim":"the invariant a reviewer would enforce, imperative and general","location":"path or path:line the finding is about, or empty when none","trigger":"the diff surface that should trigger this rule: a path, glob, or symbol, or empty when none","impact":"why this matters here, from the review's reasoning","action":"what to change or verify","scope":"historical-example","confidence":"medium"}
298
+ Rules:
299
+ - Include only substantive findings: a reviewer identifies something to fix, change, verify or decide.
300
+ - Never write an approval, a merge, "LGTM", thanks, a reviewer name, a pull-request number, a commit id, or quoted comment text.
301
+ - The claim is a general invariant, not one past fix: "When X changes, Y must also change", or "Every Z uses W", never "change this one line".
302
+ - trigger is what a reviewer can see in a diff: a path, a glob, or a symbol. It is how the rule applies to a future change, so a rule with no trigger is a one-off and is not useful.
303
+ - impact and action are mandatory and concrete. Paraphrase the reviewer's reasoning for impact; never quote it.
304
+ - class is a short area label chosen from a small, consistent set; reuse the same label for findings of the same kind so related findings can be grouped.
305
+ - location is a repository path when the review names one, otherwise leave it empty.
306
+ - Return every distinct finding the reviews support, not a summary. Do not explain the answer.
226
307
 
227
308
  PULL REQUEST:
228
- ${pullRequestUnit(pr)}`, 1_200));
309
+ ${pullRequestUnit(pr)}`, 2_400));
229
310
  evidence.push(`PR #${pr.number}`);
230
311
  scopes.push("historical-example");
231
312
  }
@@ -267,29 +348,33 @@ ${files}`, 2_200));
267
348
  const response = responses[index];
268
349
  if (!response)
269
350
  continue;
270
- try {
271
- facts.push(...factsFromResponse(response.text, evidence[index], scopes[index] ?? "historical-example", evidence[index] === "repository files"
272
- ? "repository"
273
- : "pull-request").filter((item) => !hasUnsupportedIdentifier(item.claim, source) &&
274
- !hasUnsupportedPath(item.claim, source) &&
275
- (evidence[index] !== "repository files" ||
276
- allowsContributionSections(source) ||
277
- !["title-body", "labels", "review-bar", "process"].includes(item.sectionKey))));
278
- }
279
- catch (error) {
280
- console.log(`[ai] invalid ${evidence[index]} output skipped: ${String(error)}`);
281
- }
351
+ facts.push(...factsFromResponse(response.text, evidence[index], scopes[index] ?? "historical-example", evidence[index] === "repository files" ? "repository" : "pull-request").filter((item) => {
352
+ if (hasUnsupportedIdentifier(item.claim, source) ||
353
+ hasUnsupportedPath(item.claim, source)) {
354
+ return false;
355
+ }
356
+ if (evidence[index] === "repository files" &&
357
+ !allowsContributionSections(source) &&
358
+ ["title-body", "labels", "review-bar", "process"].includes(item.sectionKey)) {
359
+ return false;
360
+ }
361
+ // An invented path is worse than no path: keep the finding and drop
362
+ // the location when it does not exist in the repository. The location
363
+ // may carry a line (`path:12` or `path:12-20`), which is stripped
364
+ // before the path is checked so a real path with a line survives.
365
+ if (item.sectionKey === "review" && item.location) {
366
+ const locationPath = item.location.replace(/:\d+(?:-\d+)?$/, "");
367
+ if (hasUnsupportedPath(locationPath, source)) {
368
+ item.location = undefined;
369
+ }
370
+ }
371
+ return true;
372
+ }));
282
373
  if (index % 10 === 0 || index === responses.length - 1) {
283
374
  console.log(`[ai] extract units ${index + 1}/${responses.length}`);
284
375
  }
285
376
  }
286
- return { facts, skipped: queue.skippedUnits() };
287
- }
288
- /** Same as {@link extractAiFacts}, but also reports what the batch skipped so
289
- * the caller can put it in the final `[done]` line. */
290
- export async function enrichFactsWithReport(provider, repo, base, source, options, usage) {
291
- const { facts, skipped } = await extractAiFactsWithReport(provider, repo, source, options, usage);
292
- return { facts: mergeFacts(base, facts), skipped };
377
+ return facts;
293
378
  }
294
379
  function mergeFacts(base, extra) {
295
380
  const merged = new Map(base.map((item) => [item.id, { ...item, evidence: [...item.evidence] }]));
@@ -313,18 +398,21 @@ export async function synthesizeSections(provider, repo, facts, _previousMarkdow
313
398
  const requests = [];
314
399
  const keys = [];
315
400
  for (const key of [...new Set(facts.map((item) => item.sectionKey))]) {
401
+ // Review findings are the guide's material, not a prose section.
402
+ if (!sectionTitles[key])
403
+ continue;
316
404
  if (onlySections && !onlySections.has(key))
317
405
  continue;
318
406
  const relevant = synthesisFacts(facts, key);
319
407
  // A section whose only facts came from a single pull request has no
320
- // repository policy to synthesize, so it is left to the deterministic
321
- // renderer instead of asking the model for an empty answer.
408
+ // repository policy to synthesize, so it is skipped instead of asking the
409
+ // model for an empty answer.
322
410
  if (!relevant.length)
323
411
  continue;
324
412
  keys.push(key);
325
413
  requests.push({
326
414
  job: "synth_section",
327
- maxTokens: 1_800,
415
+ maxTokens: 4_000,
328
416
  reasoningEffort: "high",
329
417
  system: `You synthesize contribution guidance for an unfamiliar open-source repository.
330
418
  Help developers make correct implementation, testing, review, debugging, and release
@@ -357,17 +445,21 @@ FACTS:
357
445
  ${JSON.stringify(relevant)}`,
358
446
  });
359
447
  }
360
- const queue = queueFor(provider, repo, ai, model, concurrency, (request, response) => validateSection(response, keys[requests.indexOf(request)] ?? ""));
448
+ // No validator: a section that does not match the ideal shape is normalized
449
+ // by `cleanSection` and kept, not rejected. Losing the whole run over a
450
+ // section's format is not worth it.
451
+ const queue = queueFor(provider, repo, ai, model, concurrency);
361
452
  const responses = await queue.run(requests, usage);
362
- // A section that the batch skipped has no response, and a unit that failed
363
- // validation never produces one: omit those keys entirely rather than
364
- // passing an empty string, so `assembleSkill` keeps its own content for them
365
- // (an empty string is a *present* override and would blank the section).
453
+ // A heading with no bullets is the model saying "no durable guidance", so the
454
+ // section is omitted rather than written empty. Anything with a bullet is
455
+ // kept as the model wrote it.
366
456
  const overrides = {};
367
457
  responses.forEach((response, index) => {
368
- const section = response ? cleanSection(response.text, keys[index]) : "";
369
- if (validSection(section, keys[index]))
458
+ if (!response)
459
+ return;
460
+ const section = cleanSection(response.text, keys[index]);
461
+ if (/^- /m.test(section))
370
462
  overrides[keys[index]] = section;
371
463
  });
372
- return { overrides, skipped: queue.skippedUnits() };
464
+ return { overrides };
373
465
  }
@@ -11,6 +11,10 @@ export type PullRequest = {
11
11
  additions: number;
12
12
  deletions: number;
13
13
  comments: string[];
14
+ /** Inline review comments (`pulls/{n}/comments`), as `path:line body`. These
15
+ * carry most of the substantive review feedback, and the reviewer never sees
16
+ * them otherwise. */
17
+ reviewComments: string[];
14
18
  reviews: string[];
15
19
  /** Set once reviews have been read. Missing means an older checkpoint
16
20
  * never stored the review state. */
@@ -44,6 +48,24 @@ export type Fact = {
44
48
  * repository-wide rule. Missing means `repository`, which
45
49
  * keeps facts written before this field existed. */
46
50
  origin?: "repository" | "pull-request";
51
+ /** Review findings only (`sectionKey === "review"`): the free-form area the
52
+ * finding belongs to, so the guide can group findings into passes without a
53
+ * fixed taxonomy. */
54
+ class?: string;
55
+ /** A repository-relative path or `path:line` the finding is about, when the
56
+ * review named one. Kept because it is the difference between a concrete
57
+ * rule and generic advice. */
58
+ location?: string;
59
+ /** Review findings only: why the finding matters here, in one or two
60
+ * sentences of the review's own reasoning (never a verbatim quote). */
61
+ impact?: string;
62
+ /** Review findings only: what to change or verify. */
63
+ action?: string;
64
+ /** Review findings only: the diff surface that should trigger this rule: a
65
+ * path, a glob, or a symbol. The guide turns these into the "when X changes,
66
+ * also do Y" obligations listed under a pass's exit check, so a reviewer that
67
+ * only sees a diff can still apply the rule. */
68
+ trigger?: string;
47
69
  };
48
70
  export type State = {
49
71
  version: 1;
@@ -70,7 +70,7 @@ function reviewOptionsForRepo(repo, useCodegraph, aiToken) {
70
70
  aiToken: aiToken ?? resolvedAiToken(config, config.ai ?? "openrouter"),
71
71
  lowModel: config.lowModel,
72
72
  highModel: config.highModel,
73
- synthesisVersion: 16,
73
+ synthesisVersion: 17,
74
74
  includeCodebase: true,
75
75
  includePullRequests: true,
76
76
  includePullRequestChanges: true,
@@ -147,7 +147,7 @@ export function reviewOptions(repo, prNumber) {
147
147
  aiToken: resolvedAiToken(config, config.ai && config.ai !== "none" ? config.ai : "openrouter"),
148
148
  highModel: config.highModel,
149
149
  lowModel: config.lowModel,
150
- synthesisVersion: 16,
150
+ synthesisVersion: 17,
151
151
  includeCodebase: true,
152
152
  includePullRequests: true,
153
153
  includePullRequestChanges: true,
@@ -2,12 +2,12 @@
2
2
  * directly; it used to re-spawn the CLI as a subprocess, a second
3
3
  * execution path with its own failure modes. */
4
4
  import { createAiProvider } from "../ai/provider.js";
5
- import { enrichFactsWithReport, synthesizeSections, } from "../knowledge/synthesis.js";
5
+ import { enrichFacts, synthesizeSections } from "../knowledge/synthesis.js";
6
6
  import { collectSource } from "../github/collect.js";
7
7
  import { GhClient } from "../github/gh.js";
8
8
  import { PatClient } from "../github/pat.js";
9
9
  import { extractFacts } from "../knowledge/facts.js";
10
- import { buildReviewDocuments, reviewSignalCount } from "../knowledge/guide.js";
10
+ import { reviewSignalCount, synthesizeReviewGuides, } from "../knowledge/guide.js";
11
11
  import { assembleSkill, codebaseBody, factSectionHashes, } from "../knowledge/skill.js";
12
12
  import { validateSkill } from "../knowledge/validate.js";
13
13
  import { readConfig, reposDir, resolvedAiToken, writeRepoConfig, } from "../config.js";
@@ -22,6 +22,7 @@ import { nowIso } from "../util/time.js";
22
22
  import { mkdir, readTextFile, remove } from "../util/runtime.js";
23
23
  import { addResponseCost, emptyTally } from "../util/cost.js";
24
24
  import { costLabel } from "../util/run_summary.js";
25
+ import { formatError } from "../cli/error.js";
25
26
  export function emptyAiMetrics() {
26
27
  return { calls: 0, tokensIn: 0, tokensOut: 0, ...emptyTally() };
27
28
  }
@@ -86,13 +87,20 @@ async function skillPath(repo) {
86
87
  async function writeReviewDocuments(repo, documents, signalCount) {
87
88
  const directory = `${reposDir()}/${repo}`;
88
89
  if (!documents) {
89
- // This used to delete the files without a word. The rule is
90
- // "says why the third file is missing": keep it to one line.
91
- log("write", `PR_REVIEW_GUIDE.md skipped: found ${signalCount} review signals, needs at least 3`);
92
- await Promise.all([
93
- remove(`${directory}/PR_REVIEW_GUIDE.md`).catch(() => { }),
94
- remove(`${directory}/PR_REVIEW_DETAILED_GUIDE.md`).catch(() => { }),
95
- ]);
90
+ // `undefined` means two different things. Below the signal threshold there
91
+ // is nothing to write, so the files are removed and the reason is one line.
92
+ // When the AI produced no usable guide, the existing files are kept: a
93
+ // provider hiccup must not delete a guide the last run wrote.
94
+ if (signalCount <= 2) {
95
+ log("write", `PR_REVIEW_GUIDE.md skipped: found ${signalCount} review signals, needs at least 3`);
96
+ await Promise.all([
97
+ remove(`${directory}/PR_REVIEW_GUIDE.md`).catch(() => { }),
98
+ remove(`${directory}/PR_REVIEW_DETAILED_GUIDE.md`).catch(() => { }),
99
+ ]);
100
+ }
101
+ else {
102
+ log("write", "PR_REVIEW_GUIDE.md not regenerated: the AI produced no guide, keeping any existing file");
103
+ }
96
104
  return;
97
105
  }
98
106
  const { writeTextFileAtomic } = await import("../util/atomic.js");
@@ -104,17 +112,19 @@ async function writeReviewDocuments(repo, documents, signalCount) {
104
112
  await remove(`${directory}/PR_REVIEW_DETAILED_GUIDE.md`).catch(() => { });
105
113
  }
106
114
  }
107
- /** Splits the codebase-description sections (layout/style/tests/devloop) out
108
- * of the assembled skill into their own file, so `review` can check a pull
109
- * request against how this repository's code actually looks, not just the
110
- * review-bar checklist mined from past PR comments. The skill links to this
111
- * file rather than repeating it, so its body is built from
112
- * the facts instead of being scraped back out of the skill. */
113
- async function writeCodebaseDocument(repo, facts, overrides = {}) {
115
+ /** Writes the codebase-description sections (layout/style/tests/devloop) to
116
+ * their own file, so `review` can check a pull request against how this
117
+ * repository's code actually looks, not just the review-bar checklist. Every
118
+ * section body is authored by the synthesis job; the skill links to this file
119
+ * rather than repeating it. */
120
+ async function writeCodebaseDocument(repo, overrides = {}) {
114
121
  const path = `${reposDir()}/${repo}/CODEBASE.md`;
115
- const body = codebaseBody(facts, overrides);
122
+ const body = codebaseBody(overrides);
116
123
  if (!body) {
117
- await remove(path).catch(() => { });
124
+ // Keep any existing file: `SKILL.md` links to it, and removing it would
125
+ // leave that link dangling. A guide the last run wrote is better than a
126
+ // broken link.
127
+ log("write", "CODEBASE.md not regenerated: the AI produced no codebase sections, keeping any existing file");
118
128
  return;
119
129
  }
120
130
  const { writeTextFileAtomic } = await import("../util/atomic.js");
@@ -157,9 +167,11 @@ async function initOrRemake(options) {
157
167
  const client = clientFor(options);
158
168
  const lowAi = createAiProvider(options, options.lowModel ?? "");
159
169
  const highAi = createAiProvider(options, options.highModel ?? "");
160
- if (lowAi || highAi) {
161
- log("ai", `${options.ai} providers configured · low=${options.lowModel} · high=${options.highModel}`);
170
+ // Every guide is AI-authored: with no provider there is nothing to build.
171
+ if (!lowAi || !highAi) {
172
+ throw new Error("init requires an AI provider. Run: co-maintainer set --ai=openrouter --token=... --low-model=... --high-model=...");
162
173
  }
174
+ log("ai", `${options.ai} providers configured · low=${options.lowModel} · high=${options.highModel}`);
163
175
  log("fetch", `${options.repo} via ${options.auth}`);
164
176
  const source = await timed("fetch repository data", options.logTime, () => collectSource(client, options, previous, async (pullRequests, cache) => {
165
177
  checkpoint.source.pullRequests = pullRequests;
@@ -193,17 +205,15 @@ async function initOrRemake(options) {
193
205
  if (options.logTime) {
194
206
  log("time", `extract deterministic facts · ${((performance.now() - factsStarted) / 1000).toFixed(2)}s`);
195
207
  }
208
+ const usage = async (job, response) => {
209
+ addAiMetrics(aiMetrics, response);
210
+ await recordAiCost(options.repo, job, response);
211
+ };
196
212
  let overrides = {};
197
- const skipped = [];
198
- if (lowAi) {
213
+ let reviewDocuments;
214
+ try {
199
215
  log("ai", "starting extract_unit jobs");
200
- const usage = async (job, response) => {
201
- addAiMetrics(aiMetrics, response);
202
- await recordAiCost(options.repo, job, response);
203
- };
204
- const enriched = await timed("extract_unit AI", options.logTime, () => enrichFactsWithReport(lowAi, options.repo, facts, source, options, usage));
205
- facts = enriched.facts;
206
- skipped.push(...enriched.skipped);
216
+ facts = await timed("extract_unit AI", options.logTime, () => enrichFacts(lowAi, options.repo, facts, source, options, usage));
207
217
  log("ai", `extract_unit complete · ${facts.length} facts`);
208
218
  const hashes = await factSectionHashes(facts);
209
219
  const synthesisChanged = previous &&
@@ -217,22 +227,28 @@ async function initOrRemake(options) {
217
227
  .map(([key]) => key))
218
228
  : undefined;
219
229
  log("ai", `starting synth_section jobs${dirtySections ? ` · ${dirtySections.size} dirty sections` : ""}`);
220
- if (highAi) {
221
- const synth = await timed("synth_section AI", options.logTime, () => synthesizeSections(highAi, options.repo, facts, previousMarkdown, options.ai, options.highModel ?? "", options.aiConcurrent, usage, dirtySections));
222
- overrides = synth.overrides;
223
- skipped.push(...synth.skipped);
224
- }
230
+ const synth = await timed("synth_section AI", options.logTime, () => synthesizeSections(highAi, options.repo, facts, previousMarkdown, options.ai, options.highModel ?? "", options.aiConcurrent, usage, dirtySections));
231
+ overrides = synth.overrides;
225
232
  log("ai", `synth_section complete · ${Object.keys(overrides).length} sections`);
233
+ log("ai", "starting synth_guide jobs");
234
+ reviewDocuments = await timed("synth_guide AI", options.logTime, () => synthesizeReviewGuides(highAi, options.repo, options.ai, options.highModel ?? "", options.aiConcurrent, facts, usage));
235
+ log("ai", reviewDocuments
236
+ ? `synth_guide complete · ${reviewDocuments.detailed ? "short + detailed" : "single guide"}`
237
+ : "synth_guide skipped · fewer than 3 review signals");
238
+ }
239
+ catch (error) {
240
+ // Nothing is written on an AI failure. Fetching and extraction are cached,
241
+ // so a rerun picks up where this stopped instead of starting over.
242
+ throw new Error(`AI failed to generate the guides: ${formatError(error)}. ` +
243
+ "Fetching and extraction are cached, so rerunning `co-maintainer sync <owner/repo>` continues without re-fetching.");
226
244
  }
227
245
  let result = await timed("assemble skill", options.logTime, () => assembleSkill(options.repo, facts, previousMarkdown, previous?.sectionHashes ?? {}, overrides));
228
- const reviewDocuments = buildReviewDocuments(facts);
229
246
  result.markdown = addReviewLink(result.markdown, reviewDocuments);
230
247
  const validation = await timed("validate skill", options.logTime, () => validateSkill(result.markdown, source));
231
- if (!validation.valid && Object.keys(overrides).length) {
232
- log("validate", `AI output rejected: ${validation.errors.join("; ")}`);
233
- overrides = {};
234
- result = await timed("reassemble valid skill", options.logTime, () => assembleSkill(options.repo, facts, previousMarkdown, previous?.sectionHashes ?? {}, overrides));
235
- result.markdown = addReviewLink(result.markdown, reviewDocuments);
248
+ // There is no deterministic fallback to reassemble from: a skill the AI could
249
+ // not write correctly is reported rather than rebuilt from facts.
250
+ if (!validation.valid) {
251
+ log("validate", `skill problems kept: ${validation.errors.join("; ")}`);
236
252
  }
237
253
  const finalValidation = await timed("final skill validation", options.logTime, () => validateSkill(result.markdown, source, "warning"));
238
254
  if (finalValidation.warnings.length) {
@@ -246,7 +262,7 @@ async function initOrRemake(options) {
246
262
  const { writeTextFileAtomic } = await import("../util/atomic.js");
247
263
  await withKnowledgeLock(options.repo, async () => {
248
264
  await writeTextFileAtomic(path, result.markdown);
249
- await writeCodebaseDocument(options.repo, facts, overrides);
265
+ await writeCodebaseDocument(options.repo, overrides);
250
266
  await writeReviewDocuments(options.repo, reviewDocuments, reviewSignalCount(facts));
251
267
  const head = source.commits[0];
252
268
  const baseSha = head?.sha ? String(head.sha) : new Date().toISOString();
@@ -290,16 +306,6 @@ async function initOrRemake(options) {
290
306
  ? `updated ${result.changed.join(", ")}`
291
307
  : "already current"}`);
292
308
  log("done", `${facts.length} facts · ${source.pullRequests.length} pull requests · ${source.commits.length} commits`);
293
- if (skipped.length) {
294
- // A skipped unit used to vanish into a log line and recur as a "cache
295
- // hit" forever. Say it in the final line instead, in this shape:
296
- // `1 unit skipped (PR #3: output was not JSON)`.
297
- const parts = skipped.map((unit) => unit.reason);
298
- const line = skipped.length === 1
299
- ? `1 unit skipped (${parts[0]})`
300
- : `${skipped.length} units skipped (${parts.join("; ")})`;
301
- log("done", line);
302
- }
303
309
  printRunSummary(summaryFromMetrics(aiMetrics, performance.now() - operationStarted));
304
310
  if (options.logTime) {
305
311
  log("time", `AI total · calls=${aiMetrics.calls} · input=${aiMetrics.tokensIn} tokens · output=${aiMetrics.tokensOut} tokens · cost=${costLabel(aiMetrics)}`);
@@ -319,7 +325,11 @@ export function optionsFromConfig(repo, command) {
319
325
  const lowModel = repoConfig.lowModel ?? config.lowModel;
320
326
  const highModel = repoConfig.highModel ?? config.highModel;
321
327
  const aiToken = resolvedAiToken(config, ai);
322
- if (ai !== "none" && (!aiToken || !lowModel || !highModel)) {
328
+ // Every guide is AI-authored: init and sync cannot run without a provider.
329
+ if (ai === "none") {
330
+ throw new Error("init and sync need an AI provider. Run: co-maintainer set --ai=openrouter --token=... --low-model=... --high-model=...");
331
+ }
332
+ if (!aiToken || !lowModel || !highModel) {
323
333
  throw new Error("AI is enabled but token/low-model/high-model are not fully configured. Run: " +
324
334
  "co-maintainer set --token=... --low-model=... --high-model=...");
325
335
  }
@@ -337,7 +347,7 @@ export function optionsFromConfig(repo, command) {
337
347
  aiToken,
338
348
  lowModel,
339
349
  highModel,
340
- synthesisVersion: 16,
350
+ synthesisVersion: 17,
341
351
  includeCodebase: repoConfig.includeCodebase ?? true,
342
352
  includePullRequests: repoConfig.includePullRequests ?? true,
343
353
  includePullRequestChanges: repoConfig.includePullRequestChanges ?? true,