co-maintainer 0.7.7 → 0.7.8-beta.2

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.7.7",
3
+ "version": "0.7.8-beta.2",
4
4
  "description": "An imitator of yours, A PR review tool like co-maintainer.",
5
5
  "keywords": [
6
6
  "ai",
@@ -192,6 +192,7 @@ export async function parseArgs(args) {
192
192
  arg === "--run" ||
193
193
  arg === "--json" ||
194
194
  arg === "--only-request-changed-pr" ||
195
+ arg === "--full-guide" ||
195
196
  arg === "--experimental-siwc")
196
197
  continue;
197
198
  if (arg.startsWith("--") && !known)
@@ -345,6 +346,7 @@ export async function parseArgs(args) {
345
346
  prNumber,
346
347
  debug: rest.includes("--debug"),
347
348
  logTime: rest.includes("--log-time"),
349
+ ...(rest.includes("--full-guide") ? { fullGuide: true } : {}),
348
350
  reviewUpstream: rest.includes("--review-upstream"),
349
351
  run: rest.includes("--run"),
350
352
  ...(json ? { json: true } : {}),
@@ -472,6 +472,15 @@ export const COMMANDS = [
472
472
  },
473
473
  ],
474
474
  },
475
+ {
476
+ title: "Review guide",
477
+ flags: [
478
+ {
479
+ name: "full-guide",
480
+ description: "Rewrite the review guide in full now, instead of editing it, and start the count of --guide-full-every again.",
481
+ },
482
+ ],
483
+ },
475
484
  ],
476
485
  examples: [
477
486
  "co-maintainer sync owner/repo --include-codebase",
@@ -908,6 +917,12 @@ export const COMMANDS = [
908
917
  default: "20000",
909
918
  description: "The most characters one read-full-diff answer returns in a review of this repository. Needs --repo. 0 or -1 means no limit.",
910
919
  },
920
+ {
921
+ name: "guide-full-every",
922
+ value: "N",
923
+ default: "10",
924
+ description: "Every N-th sync whose input changed rewrites the review guide in full, the others edit it. 1 always rewrites, 0 never after init. Needs --repo.",
925
+ },
911
926
  {
912
927
  name: "review-blocking",
913
928
  value: "model|severity",
@@ -85,6 +85,7 @@ export async function runSet(args) {
85
85
  "review-system-prompt-max-chars",
86
86
  ...DIAGRAM_FLAGS,
87
87
  "review-read-diff-max-chars",
88
+ "guide-full-every",
88
89
  "password",
89
90
  "extension-rerun-on-restart",
90
91
  "unset",
@@ -400,6 +401,7 @@ const REPO_SCOPED_FLAGS = new Set([
400
401
  "review-system-prompt-max-chars",
401
402
  ...DIAGRAM_FLAGS,
402
403
  "review-read-diff-max-chars",
404
+ "guide-full-every",
403
405
  "review-references",
404
406
  "gh-concurrent",
405
407
  "ai-concurrent",
@@ -418,6 +420,8 @@ const REPO_SCOPED_UNSET = new Set([
418
420
  "plantumlOutputFormat",
419
421
  "review-read-diff-max-chars",
420
422
  "reviewReadDiffMaxChars",
423
+ "guide-full-every",
424
+ "guideFullEvery",
421
425
  "gh-concurrent",
422
426
  "ghConcurrent",
423
427
  "ai-concurrent",
@@ -524,6 +528,22 @@ async function runSetRepo(typed, args) {
524
528
  patch.reviewReadDiffMaxChars = value;
525
529
  }
526
530
  }
531
+ if (unset.has("guide-full-every") || unset.has("guideFullEvery")) {
532
+ patch.guideFullEvery = undefined;
533
+ }
534
+ const fullEveryRaw = text(args, "guide-full-every");
535
+ if (fullEveryRaw !== undefined) {
536
+ if (fullEveryRaw.trim() === "") {
537
+ patch.guideFullEvery = undefined;
538
+ }
539
+ else {
540
+ const value = Number(fullEveryRaw);
541
+ if (!Number.isInteger(value) || value < 0) {
542
+ die("--guide-full-every must be a whole number: 1 always rewrites the guide, 0 never does after init");
543
+ }
544
+ patch.guideFullEvery = value;
545
+ }
546
+ }
527
547
  if (unset.has("review-references") || unset.has("reviewReferences")) {
528
548
  patch.reviewReferences = undefined;
529
549
  }
@@ -542,7 +562,7 @@ async function runSetRepo(typed, args) {
542
562
  patch.reviewSystemPrompt = prompt.trim() === "" ? undefined : prompt;
543
563
  }
544
564
  if (Object.keys(patch).length === 0) {
545
- die("Nothing to set. Pass --review-system-prompt=, --review-system-prompt-max-chars=N, --diagram-runtime=, --plantuml-server=, --plantuml-output-format=, --review-read-diff-max-chars=N, --review-references=on|off, or --unset=name with --repo.");
565
+ die("Nothing to set. Pass --review-system-prompt=, --review-system-prompt-max-chars=N, --diagram-runtime=, --plantuml-server=, --plantuml-output-format=, --review-read-diff-max-chars=N, --guide-full-every=N, --review-references=on|off, or --unset=name with --repo.");
546
566
  }
547
567
  // The values after this write are the ones given here, or the stored ones.
548
568
  // Lowering the cap re-checks the stored prompt too, so it cannot end up over
@@ -65,6 +65,10 @@ export type RepoConfig = {
65
65
  /** Cap on one `read-full-diff` answer in characters for this repository.
66
66
  * Unset means the default, `0` or a negative number means no limit. */
67
67
  reviewReadDiffMaxChars?: number;
68
+ /** Every N-th `sync` whose guide input changed rewrites the review guide
69
+ * in full, the others edit it. Unset means 10, `1` always rewrites, `0`
70
+ * never rewrites after `init`. */
71
+ guideFullEvery?: number;
68
72
  };
69
73
  export type UserConfig = {
70
74
  auth?: "gh" | "pat";
@@ -1,3 +1,4 @@
1
+ import type { RuleEntry } from "./rules.ts";
1
2
  import type { AiProvider, AiResponse, Options } from "../types.ts";
2
3
  import type { Fact } from "./types.ts";
3
4
  import { type GuideFileCount, type GuideRule } from "./guide_ids.ts";
@@ -59,5 +60,25 @@ export declare function synthesizeReviewGuides(provider: AiProvider, repo: strin
59
60
  * new line goes against. */
60
61
  previousRules?: Record<string, {
61
62
  text: string;
62
- }>): Promise<ReviewDocuments | undefined>;
63
+ }>,
64
+ /** The guide on disk to edit instead of rewriting it. Left out, the guide
65
+ * is written in full. */
66
+ edit?: GuideEditInput,
67
+ /** Filled with what this build did, for the sync counter. */
68
+ outcome?: {
69
+ mode?: "full" | "edit" | "unchanged";
70
+ }): Promise<ReviewDocuments | undefined>;
71
+ /** What a sync needs to edit the guide: the files on disk, the last build's
72
+ * rules and the findings the guide was written from. */
73
+ export type GuideEditInput = {
74
+ guide: string;
75
+ detailed?: string;
76
+ rules: Record<string, RuleEntry>;
77
+ findings: string[];
78
+ /** The count of edits reached `--guide-full-every`: a sync whose findings
79
+ * changed rewrites in full, one whose findings did not keeps the guide. */
80
+ rewriteIfChanged?: boolean;
81
+ };
82
+ /** The findings a guide is written from, by key, for the next edit. */
83
+ export declare function guideFindingKeys(facts: Fact[]): string[];
63
84
  export {};
@@ -1,3 +1,4 @@
1
+ import { applyGuideEdits, GuideEditError, guideRuleIds, keptSources, parseGuideEdits, } from "./guide_edit.js";
1
2
  import { AiBatch } from "../ai/batch.js";
2
3
  import { log } from "../util/log.js";
3
4
  import { assignGuideIds, } from "./guide_ids.js";
@@ -264,11 +265,26 @@ async function uncut(queue, request, usage) {
264
265
  export async function synthesizeReviewGuides(provider, repo, ai, model, concurrency, facts, usage,
265
266
  /** The last build's `RULES.json` rules, so the AI can say which old rule a
266
267
  * new line goes against. */
267
- previousRules) {
268
+ previousRules,
269
+ /** The guide on disk to edit instead of rewriting it. Left out, the guide
270
+ * is written in full. */
271
+ edit,
272
+ /** Filled with what this build did, for the sync counter. */
273
+ outcome) {
268
274
  const findings = guideFindings(facts);
269
275
  if (findings.length <= 2)
270
276
  return undefined;
271
277
  const material = guideMaterial(facts);
278
+ if (edit) {
279
+ const edited = await editReviewGuides(provider, repo, ai, model, concurrency, facts, material, edit, usage);
280
+ if (edited !== FULL) {
281
+ if (outcome)
282
+ outcome.mode = edited.mode;
283
+ return edited.documents;
284
+ }
285
+ }
286
+ if (outcome)
287
+ outcome.mode = "full";
272
288
  // No validator: the guide is kept as written. Losing the run over format is
273
289
  // not worth it, and a later `sync` reuses the cached text.
274
290
  const queue = new AiBatch(provider, repo, Math.max(1, concurrency), `${ai}:v3:${model}:guide`);
@@ -299,10 +315,132 @@ previousRules) {
299
315
  return withRuleIds(withTrailingNewline(full), undefined, sources, links);
300
316
  return withRuleIds(withTrailingNewline(short), full, sources, links);
301
317
  }
318
+ /** A guide longer than this is rewritten in full rather than sent whole to
319
+ * an edit call. A full method stops at about 64,000 characters. */
320
+ const MAX_EDIT_GUIDE_CHARS = 80_000;
321
+ /** The edit prompt's input in tokens, estimated at 2.5 characters a token,
322
+ * which is dense text. With the 8,000-token answer this stays well inside a
323
+ * 64,000-token context, so the call never fails on length before the
324
+ * full-rewrite fallback can run. A bigger change is rewritten in full. */
325
+ const MAX_EDIT_INPUT_TOKENS = 40_000;
326
+ function estimatedTokens(chars) {
327
+ return Math.ceil(chars / 2.5);
328
+ }
329
+ const FULL = Symbol("rewrite in full");
330
+ /** The key a finding is compared by between builds. */
331
+ function findingKey(item) {
332
+ return item.claim.trim().toLowerCase().replace(/\s+/g, " ");
333
+ }
334
+ /** The findings a guide is written from, by key, for the next edit. */
335
+ export function guideFindingKeys(facts) {
336
+ return guideFindings(facts).slice(0, MAX_FINDINGS).map(findingKey);
337
+ }
338
+ function editGuideRequest(current, added, gone) {
339
+ return {
340
+ job: "edit_guide",
341
+ maxTokens: 8_000,
342
+ reasoningEffort: "high",
343
+ system: GUIDE_SYSTEM,
344
+ prompt: `Update the review method below with the findings that changed since it was written. Return only this JSON object:
345
+ {"add": [{"pass": "<the title of an existing pass>", "rule": "<rule> · <why it matters here> [<finding numbers>]", "example": "<the concrete case>"}],
346
+ "change": [{"id": "R12", "rule": "<rule> · <why it matters here> [<finding numbers>]"}],
347
+ "remove": ["R4"]}
348
+ - NEW FINDINGS are numbered. For each one, change the rule that already covers it and end its line with that finding's number, or add a rule under the pass it belongs to. A rule is a general invariant in the same shape as the rules in the method.
349
+ - GONE FINDINGS are no longer in the repository's history. Remove a rule only when nothing it says still holds, otherwise leave it.
350
+ - Name rules only by the ids at the end of their lines. Change nothing else. Empty lists are fine.
351
+
352
+ CURRENT METHOD:
353
+ ${current}
354
+
355
+ NEW FINDINGS:
356
+ ${added || "None."}
357
+
358
+ GONE FINDINGS:
359
+ ${gone || "None."}`,
360
+ };
361
+ }
362
+ /** Edits the guide on disk with the findings that changed. Returns `FULL`
363
+ * when the guide must be rewritten instead: no usable answer, or an edit that
364
+ * does not fit the file. A sync whose findings did not change keeps the guide
365
+ * as it is and makes no call. */
366
+ async function editReviewGuides(provider, repo, ai, model, concurrency, facts, material, edit, usage) {
367
+ const current = guideFindings(facts).slice(0, MAX_FINDINGS);
368
+ const keys = current.map(findingKey);
369
+ const before = new Set(edit.findings);
370
+ const now = new Set(keys);
371
+ const added = JSON.parse(material).filter((_item, index) => !before.has(keys[index]));
372
+ const gone = edit.findings.filter((key) => !now.has(key));
373
+ const main = edit.detailed ?? edit.guide;
374
+ const ids = [
375
+ ...new Set([
376
+ ...guideRuleIds(main),
377
+ ...(edit.detailed ? guideRuleIds(edit.guide) : []),
378
+ ]),
379
+ ];
380
+ const kept = keptSources(ids, edit.rules, current.length);
381
+ const sources = [...findingPullRequests(facts), ...kept.pullRequests];
382
+ const links = [...findingLinks(facts), ...kept.links];
383
+ const total = current.length + kept.pullRequests.length;
384
+ const noEdits = { add: [], change: [], remove: [] };
385
+ const relabel = (edits) => {
386
+ const detailed = edit.detailed
387
+ ? applyGuideEdits(edit.detailed, edits, kept.pseudo, current.length, true)
388
+ : undefined;
389
+ const guide = applyGuideEdits(edit.guide, edits, kept.pseudo, current.length, !edit.detailed);
390
+ return withRuleIds(withTrailingNewline(guide), detailed === undefined ? undefined : withTrailingNewline(detailed), sources, links, total);
391
+ };
392
+ if (added.length === 0 && gone.length === 0) {
393
+ log("ai", "the review guide's findings did not change, keeping it as it is");
394
+ return { mode: "unchanged", documents: relabel(noEdits) };
395
+ }
396
+ if (edit.rewriteIfChanged)
397
+ return FULL;
398
+ const addedText = added.length ? JSON.stringify(added, null, 2) : "";
399
+ const goneText = gone.length ? JSON.stringify(gone, null, 2) : "";
400
+ // The whole edit prompt is bounded: the guide and the changed findings.
401
+ // Past it, a full rewrite is cheaper than an edit and stays in the limit.
402
+ const request = editGuideRequest(main.trim(), addedText, goneText);
403
+ const tokens = estimatedTokens((request.system ?? "").length + request.prompt.length);
404
+ if (main.length > MAX_EDIT_GUIDE_CHARS || tokens > MAX_EDIT_INPUT_TOKENS) {
405
+ log("ai", `the edit prompt would be about ${tokens} tokens, rewriting the guide in full instead of editing it`);
406
+ return FULL;
407
+ }
408
+ const queue = new AiBatch(provider, repo, Math.max(1, concurrency), `${ai}:v3:${model}:guide`);
409
+ // An edit call that fails, for example on a context limit the size
410
+ // estimate missed, is not a failed sync: the guide is rewritten in full.
411
+ let response;
412
+ try {
413
+ response = await uncut(queue, request, usage);
414
+ }
415
+ catch (error) {
416
+ log("ai", `edit_guide failed (${error instanceof Error ? error.message : String(error)}), rewriting the guide in full`);
417
+ return FULL;
418
+ }
419
+ if (response === CUT || !response) {
420
+ log("ai", "edit_guide gave no usable answer, rewriting the guide in full");
421
+ return FULL;
422
+ }
423
+ const edits = parseGuideEdits(response.text);
424
+ if (!edits) {
425
+ log("ai", "edit_guide did not answer the edit format, rewriting the guide in full");
426
+ return FULL;
427
+ }
428
+ try {
429
+ const documents = relabel(edits);
430
+ log("ai", `edit_guide · ${edits.add.length} added · ${edits.change.length} changed · ${edits.remove.length} removed`);
431
+ return { mode: "edit", documents };
432
+ }
433
+ catch (error) {
434
+ if (!(error instanceof GuideEditError))
435
+ throw error;
436
+ log("ai", `edit_guide: ${error.message}, rewriting the guide in full`);
437
+ return FULL;
438
+ }
439
+ }
302
440
  /** Replaces the finding brackets with `R` ids and attaches each id's pull
303
441
  * requests. */
304
- function withRuleIds(guide, detailed, sources, links = []) {
305
- const assigned = assignGuideIds(guide, detailed, sources.length);
442
+ function withRuleIds(guide, detailed, sources, links = [], findingCount = sources.length) {
443
+ const assigned = assignGuideIds(guide, detailed, findingCount);
306
444
  return {
307
445
  guide: assigned.guide,
308
446
  ...(assigned.detailed !== undefined ? { detailed: assigned.detailed } : {}),
@@ -0,0 +1,50 @@
1
+ /** Editing the review guide instead of rewriting it (#113).
2
+ *
3
+ * A full rewrite sends every finding to the high model and gets a whole new
4
+ * guide back, so every `sync` pays for both guide calls and the text churns.
5
+ * An edit sends the current guide with its rule ids, the findings that are new
6
+ * since the last guide and the ones that are gone, and gets back only what to
7
+ * add, change and remove. Every other line stays byte for byte.
8
+ *
9
+ * The ids come out of the same pipeline as a full rewrite. A kept line's
10
+ * `[R12]` becomes a pseudo finding number past the real findings, and that
11
+ * number carries the rule's old pull requests and links. A changed line keeps
12
+ * the pseudo number next to its new findings. `assignGuideIds` then numbers
13
+ * every line, and the stable id mapping gives each kept rule its old id back
14
+ * by its sources. */
15
+ import type { RuleEntry } from "./rules.ts";
16
+ export type GuideEdits = {
17
+ add: {
18
+ pass: string;
19
+ rule: string;
20
+ example?: string;
21
+ }[];
22
+ change: {
23
+ id: string;
24
+ rule: string;
25
+ }[];
26
+ remove: string[];
27
+ };
28
+ /** The answer of an edit call, or `null` when it is not usable. An unusable
29
+ * answer falls back to a full rewrite, never to a half-applied edit. */
30
+ export declare function parseGuideEdits(text: string): GuideEdits | null;
31
+ /** The rule ids of a guide's check lines, in file order. */
32
+ export declare function guideRuleIds(text: string): string[];
33
+ export declare class GuideEditError extends Error {
34
+ }
35
+ /** Applies `edits` to one guide file. `pseudo` maps each kept id to its
36
+ * pseudo finding number. Every kept line's `[R12]` becomes `[pseudo]`. Throws
37
+ * `GuideEditError` on an edit that does not fit the file, so the caller can
38
+ * rewrite in full instead. `strict` is for the detailed guide: there, every
39
+ * id and pass the edits name must exist. The short guide takes what fits. */
40
+ export declare function applyGuideEdits(text: string, edits: GuideEdits, pseudo: Map<string, number>, findingCount: number, strict: boolean): string;
41
+ /** The pseudo numbers of the kept rules, past the real findings, and the pull
42
+ * requests and links each one carries. */
43
+ export declare function keptSources(ids: string[], rules: Record<string, RuleEntry>, findingCount: number): {
44
+ pseudo: Map<string, number>;
45
+ pullRequests: number[][];
46
+ links: {
47
+ pr: number;
48
+ url: string;
49
+ }[][];
50
+ };
@@ -0,0 +1,217 @@
1
+ /** The answer of an edit call, or `null` when it is not usable. An unusable
2
+ * answer falls back to a full rewrite, never to a half-applied edit. */
3
+ export function parseGuideEdits(text) {
4
+ const json = text
5
+ .trim()
6
+ .replace(/^```(?:json)?\s*/i, "")
7
+ .replace(/\s*```$/, "");
8
+ let value;
9
+ try {
10
+ value = JSON.parse(json);
11
+ }
12
+ catch {
13
+ return null;
14
+ }
15
+ // The prompt asks for all three lists, empty or not. An answer without
16
+ // them, such as `{}`, is not taken as "no edits".
17
+ if (!value || typeof value !== "object" || Array.isArray(value))
18
+ return null;
19
+ const record = value;
20
+ if (!["add", "change", "remove"].every((key) => key in record))
21
+ return null;
22
+ const list = (key) => record[key];
23
+ const add = list("add");
24
+ const change = list("change");
25
+ const remove = list("remove");
26
+ if (!Array.isArray(add) || !Array.isArray(change) || !Array.isArray(remove)) {
27
+ return null;
28
+ }
29
+ const edits = { add: [], change: [], remove: [] };
30
+ for (const item of add) {
31
+ const entry = item;
32
+ if (typeof entry?.pass !== "string" || typeof entry.rule !== "string") {
33
+ return null;
34
+ }
35
+ edits.add.push({
36
+ pass: entry.pass.trim(),
37
+ rule: entry.rule.trim(),
38
+ ...(typeof entry.example === "string" && entry.example.trim()
39
+ ? { example: entry.example.trim() }
40
+ : {}),
41
+ });
42
+ }
43
+ for (const item of change) {
44
+ const entry = item;
45
+ if (typeof entry?.id !== "string" || typeof entry.rule !== "string") {
46
+ return null;
47
+ }
48
+ edits.change.push({ id: entry.id.trim(), rule: entry.rule.trim() });
49
+ }
50
+ for (const item of remove) {
51
+ if (typeof item !== "string")
52
+ return null;
53
+ edits.remove.push(item.trim());
54
+ }
55
+ return edits;
56
+ }
57
+ const ID_AT_END = /\s+\[(R[1-9]\d*)\]\s*$/;
58
+ const NUMBERS_AT_END = /\s+\[\s*(\d+(?:\s*,\s*\d+)*)\s*\]\s*$/;
59
+ function isCheckLine(line) {
60
+ return line.startsWith("- ") && line.includes(" · ");
61
+ }
62
+ /** The rule ids of a guide's check lines, in file order. */
63
+ export function guideRuleIds(text) {
64
+ return text
65
+ .split("\n")
66
+ .filter(isCheckLine)
67
+ .flatMap((line) => {
68
+ const match = ID_AT_END.exec(line);
69
+ return match ? [match[1]] : [];
70
+ });
71
+ }
72
+ /** `- rule · why [3, 17]` as the model wrote it, made a check line: a bullet,
73
+ * and the finding numbers that exist. `null` when the rule has no usable
74
+ * source list. */
75
+ function newLine(rule, findingCount) {
76
+ const text = rule.replace(/^-\s*/, "").trim();
77
+ const match = NUMBERS_AT_END.exec(text);
78
+ if (!match || !text.includes(" · "))
79
+ return null;
80
+ const numbers = [
81
+ ...new Set(match[1]
82
+ .split(",")
83
+ .map(Number)
84
+ .filter((n) => n >= 1 && n <= findingCount)),
85
+ ];
86
+ if (numbers.length === 0)
87
+ return null;
88
+ return `- ${text.slice(0, match.index)} [${numbers.sort((a, b) => a - b).join(", ")}]`;
89
+ }
90
+ /** Adds a pseudo number to a line that already ends in finding numbers. */
91
+ function withPseudo(line, pseudo) {
92
+ const match = NUMBERS_AT_END.exec(line);
93
+ const numbers = [...match[1].split(",").map(Number), pseudo];
94
+ return `${line.slice(0, match.index)} [${[...new Set(numbers)].sort((a, b) => a - b).join(", ")}]`;
95
+ }
96
+ /** The section of `## title`, matched without case or extra spaces. */
97
+ function sectionOf(lines, title) {
98
+ const want = title
99
+ .replace(/^#+\s*/, "")
100
+ .trim()
101
+ .toLowerCase();
102
+ const start = lines.findIndex((line) => /^##\s+/.test(line) &&
103
+ line
104
+ .replace(/^##\s+/, "")
105
+ .trim()
106
+ .toLowerCase() === want);
107
+ if (start === -1)
108
+ return null;
109
+ let end = lines.findIndex((line, index) => index > start && /^##\s/.test(line));
110
+ if (end === -1)
111
+ end = lines.length;
112
+ return { start, end };
113
+ }
114
+ /** Where a new rule goes in a section: after its last rule and that rule's
115
+ * indented lines, so before the exit check. */
116
+ function insertAt(lines, section) {
117
+ let at = section.start + 1;
118
+ for (let index = section.start + 1; index < section.end; index++) {
119
+ if (isCheckLine(lines[index])) {
120
+ at = index + 1;
121
+ while (at < section.end && /^\s+\S/.test(lines[at]))
122
+ at++;
123
+ }
124
+ }
125
+ return at;
126
+ }
127
+ export class GuideEditError extends Error {
128
+ }
129
+ /** Applies `edits` to one guide file. `pseudo` maps each kept id to its
130
+ * pseudo finding number. Every kept line's `[R12]` becomes `[pseudo]`. Throws
131
+ * `GuideEditError` on an edit that does not fit the file, so the caller can
132
+ * rewrite in full instead. `strict` is for the detailed guide: there, every
133
+ * id and pass the edits name must exist. The short guide takes what fits. */
134
+ export function applyGuideEdits(text, edits, pseudo, findingCount, strict) {
135
+ let lines = text.split("\n");
136
+ const ids = new Set(guideRuleIds(text));
137
+ if (strict) {
138
+ for (const id of [...edits.remove, ...edits.change.map((c) => c.id)]) {
139
+ if (!ids.has(id))
140
+ throw new GuideEditError(`no rule ${id} in the guide`);
141
+ }
142
+ }
143
+ const removed = new Set(edits.remove);
144
+ const changed = new Map(edits.change.map((item) => [item.id, item.rule]));
145
+ const out = [];
146
+ for (let index = 0; index < lines.length; index++) {
147
+ const line = lines[index];
148
+ const id = isCheckLine(line) ? ID_AT_END.exec(line)?.[1] : undefined;
149
+ if (id && removed.has(id)) {
150
+ // The rule's own indented lines go with it.
151
+ while (index + 1 < lines.length && /^\s+\S/.test(lines[index + 1])) {
152
+ index++;
153
+ }
154
+ continue;
155
+ }
156
+ if (id && changed.has(id)) {
157
+ const next = newLine(changed.get(id), findingCount);
158
+ if (!next) {
159
+ if (strict)
160
+ throw new GuideEditError(`the change to ${id} has no sources`);
161
+ out.push(line.replace(ID_AT_END, ` [${pseudo.get(id)}]`));
162
+ continue;
163
+ }
164
+ out.push(withPseudo(next, pseudo.get(id)));
165
+ continue;
166
+ }
167
+ if (id && pseudo.has(id)) {
168
+ out.push(line.replace(ID_AT_END, ` [${pseudo.get(id)}]`));
169
+ continue;
170
+ }
171
+ out.push(line);
172
+ }
173
+ lines = out;
174
+ for (const item of edits.add) {
175
+ const line = newLine(item.rule, findingCount);
176
+ if (!line) {
177
+ if (strict)
178
+ throw new GuideEditError("an added rule has no sources");
179
+ continue;
180
+ }
181
+ let section = sectionOf(lines, item.pass);
182
+ if (!section) {
183
+ if (strict)
184
+ throw new GuideEditError(`no pass "${item.pass}" in the guide`);
185
+ // The short guide may group passes differently: the rule joins its
186
+ // last pass, so the two guides still name the same rules.
187
+ const last = lines.findLastIndex((entry) => /^##\s/.test(entry));
188
+ if (last === -1)
189
+ continue;
190
+ section = sectionOf(lines, lines[last]);
191
+ if (!section)
192
+ continue;
193
+ }
194
+ const at = insertAt(lines, section);
195
+ const added = item.example && strict ? [line, ` - ${item.example}`] : [line];
196
+ lines.splice(at, 0, ...added);
197
+ }
198
+ return lines.join("\n");
199
+ }
200
+ /** The pseudo numbers of the kept rules, past the real findings, and the pull
201
+ * requests and links each one carries. */
202
+ export function keptSources(ids, rules, findingCount) {
203
+ const pseudo = new Map();
204
+ const pullRequests = [];
205
+ const links = [];
206
+ for (const id of ids) {
207
+ if (pseudo.has(id))
208
+ continue;
209
+ pseudo.set(id, findingCount + pullRequests.length + 1);
210
+ const sources = rules[id]?.sources ?? [];
211
+ pullRequests.push(sources.flatMap((source) => ("pr" in source ? [source.pr] : [])));
212
+ links.push(sources.flatMap((source) => "pr" in source && "url" in source && typeof source.url === "string"
213
+ ? [{ pr: source.pr, url: source.url }]
214
+ : []));
215
+ }
216
+ return { pseudo, pullRequests, links };
217
+ }
@@ -96,6 +96,12 @@ export type State = {
96
96
  source: Source;
97
97
  facts: Fact[];
98
98
  sectionHashes: Record<string, string>;
99
+ /** For editing the review guide on the next sync: the findings it was
100
+ * written from, by key, and the edits since its last full rewrite. */
101
+ guide?: {
102
+ findings: string[];
103
+ edits: number;
104
+ };
99
105
  scanDone: {
100
106
  pullRequests: number;
101
107
  commits: number;
@@ -1,6 +1,7 @@
1
- import type { ReviewDocuments } from "../knowledge/guide.ts";
1
+ import type { GuideEditInput, ReviewDocuments } from "../knowledge/guide.ts";
2
+ import type { RuleEntry } from "../knowledge/rules.ts";
2
3
  import type { AiResponse, GitHubClient, Options } from "../types.ts";
3
- import type { State } from "../knowledge/types.ts";
4
+ import type { Fact, State } from "../knowledge/types.ts";
4
5
  import type { LogFn } from "./jobs.ts";
5
6
  import type { JobRow } from "../store/rows.ts";
6
7
  import { type CostTally } from "../util/cost.ts";
@@ -48,6 +49,19 @@ export declare function addReviewLink(markdown: string, guide: ReviewGuideStatus
48
49
  export declare class StoppedError extends Error {
49
50
  }
50
51
  export declare function runInitOrRemake(options: Options, signal?: AbortSignal): Promise<void>;
52
+ /** What the next sync needs to edit the guide: the findings this guide was
53
+ * written from, and how many edits since its last full rewrite. A sync that
54
+ * kept the guide as it was does not count, and a full rewrite starts again. */
55
+ export declare function guideState(previous: State | null | undefined, outcome: {
56
+ mode?: "full" | "edit" | "unchanged";
57
+ }, documents: ReviewDocuments | undefined, facts: Fact[]): Pick<State, "guide">;
58
+ /** How many syncs whose guide input changed edit the guide before one
59
+ * rewrites it in full. */
60
+ export declare const DEFAULT_GUIDE_FULL_EVERY = 10;
61
+ /** The guide on disk to edit, or `undefined` when this build rewrites it in
62
+ * full: `init`, `sync --full-guide`, `--guide-full-every=1`, the N-th
63
+ * changed sync, or no earlier guide, rules or finding list to edit from. */
64
+ export declare function guideEditInput(options: Options, previous: State | null | undefined, rules: Record<string, RuleEntry> | undefined): Promise<GuideEditInput | undefined>;
51
65
  /** Builds `Options` for a server-triggered `init`/`remake` from config
52
66
  * alone, no CLI flags, no interactive prompt, there is no terminal here. */
53
67
  export declare function optionsFromConfig(repo: string, command: "init" | "remake"): Options;
@@ -9,6 +9,7 @@ import { GhClient } from "../github/gh.js";
9
9
  import { PatClient } from "../github/pat.js";
10
10
  import { extractFacts } from "../knowledge/facts.js";
11
11
  import { reviewSignalCount, synthesizeReviewGuides, } from "../knowledge/guide.js";
12
+ import { guideFindingKeys } from "../knowledge/guide.js";
12
13
  import { assembleSkill, codebaseBody, extractSections, factSectionHashes, } from "../knowledge/skill.js";
13
14
  import { validateSkill } from "../knowledge/validate.js";
14
15
  import { codebaseSectionKeys } from "../knowledge/sections.js";
@@ -22,7 +23,7 @@ import { resolveConcurrency } from "./concurrency.js";
22
23
  import { closeAppDb, isAppDbOpen, openAppDb } from "../store/app_db.js";
23
24
  import { getRepo, markKnowledgeBuilt, registerCliRepo, } from "../store/repos.js";
24
25
  import { nowIso } from "../util/time.js";
25
- import { mkdir, readTextFile, remove, stat } from "../util/runtime.js";
26
+ import { isNotFound, mkdir, readTextFile, remove, stat, } from "../util/runtime.js";
26
27
  import { applyWatchNotes, withMaintainerNotes } from "./watch_notes.js";
27
28
  import { addResponseCost, emptyTally } from "../util/cost.js";
28
29
  import { costLabel } from "../util/run_summary.js";
@@ -261,7 +262,77 @@ export async function runInitOrRemake(options, signal) {
261
262
  await closeAppDb();
262
263
  }
263
264
  }
265
+ /** What the next sync needs to edit the guide: the findings this guide was
266
+ * written from, and how many edits since its last full rewrite. A sync that
267
+ * kept the guide as it was does not count, and a full rewrite starts again. */
268
+ export function guideState(previous, outcome, documents, facts) {
269
+ if (!documents)
270
+ return previous?.guide ? { guide: previous.guide } : {};
271
+ const edits = previous?.guide?.edits ?? 0;
272
+ return {
273
+ guide: {
274
+ findings: guideFindingKeys(facts),
275
+ edits: outcome.mode === "edit"
276
+ ? edits + 1
277
+ : outcome.mode === "unchanged"
278
+ ? edits
279
+ : 0,
280
+ },
281
+ };
282
+ }
283
+ /** How many syncs whose guide input changed edit the guide before one
284
+ * rewrites it in full. */
285
+ export const DEFAULT_GUIDE_FULL_EVERY = 10;
286
+ /** The guide on disk to edit, or `undefined` when this build rewrites it in
287
+ * full: `init`, `sync --full-guide`, `--guide-full-every=1`, the N-th
288
+ * changed sync, or no earlier guide, rules or finding list to edit from. */
289
+ export async function guideEditInput(options, previous, rules) {
290
+ if (options.command === "init" || options.fullGuide)
291
+ return undefined;
292
+ const every = readConfig().repos?.[options.repo]?.guideFullEvery ??
293
+ DEFAULT_GUIDE_FULL_EVERY;
294
+ if (every === 1)
295
+ return undefined;
296
+ const edits = previous?.guide?.edits ?? 0;
297
+ // The count only decides once the findings changed: a sync whose findings
298
+ // are the same keeps the guide, whatever the count.
299
+ const rewriteIfChanged = every > 0 && edits + 1 >= every;
300
+ if (rewriteIfChanged) {
301
+ log("ai", `${edits} edits since the last full rewrite, --guide-full-every=${every}: a changed guide is rewritten in full`);
302
+ }
303
+ const findings = previous?.guide?.findings;
304
+ if (!findings || !rules)
305
+ return undefined;
306
+ const directory = `${reposDir()}/${options.repo}`;
307
+ // Only a missing file means "no such guide". Any other read error rewrites
308
+ // in full, so the two guides are never edited apart.
309
+ const UNREADABLE = Symbol("unreadable");
310
+ const read = (name) => readTextFile(`${directory}/${name}`).catch((error) => isNotFound(error) ? undefined : UNREADABLE);
311
+ const [guide, detailed] = await Promise.all([
312
+ read("PR_REVIEW_GUIDE.md"),
313
+ read("PR_REVIEW_DETAILED_GUIDE.md"),
314
+ ]);
315
+ if (!guide || guide === UNREADABLE || detailed === UNREADABLE) {
316
+ return undefined;
317
+ }
318
+ // The last build wrote a detailed guide that is gone now: rewrite in full.
319
+ const hadDetailed = Object.values(rules).some((rule) => rule.file === "PR_REVIEW_DETAILED_GUIDE.md");
320
+ if (hadDetailed && detailed === undefined)
321
+ return undefined;
322
+ // An empty guide file is not a guide to edit.
323
+ if (!guide.trim() || (detailed !== undefined && !detailed.trim())) {
324
+ return undefined;
325
+ }
326
+ return {
327
+ guide,
328
+ ...(detailed !== undefined ? { detailed } : {}),
329
+ rules,
330
+ findings,
331
+ ...(rewriteIfChanged ? { rewriteIfChanged: true } : {}),
332
+ };
333
+ }
264
334
  async function initOrRemake(options, signal) {
335
+ const guideOutcome = {};
265
336
  // Turning review references on re-reads every pull request once, so the
266
337
  // guide rules get links to the review comments they came from.
267
338
  const repoConfig = readConfig().repos?.[options.repo];
@@ -350,7 +421,8 @@ async function initOrRemake(options, signal) {
350
421
  // goes against. Read outside the lock: it only shapes the prompt, the ids
351
422
  // are mapped under the lock below.
352
423
  const previousRules = (await readRulesFile(options.repo))?.rules;
353
- reviewDocuments = await timed("synth_guide AI", options.logTime, () => synthesizeReviewGuides(highAi, options.repo, options.ai, options.highModel ?? "", options.aiConcurrent, facts, usage, previousRules));
424
+ const edit = await guideEditInput(options, previous, previousRules);
425
+ reviewDocuments = await timed("synth_guide AI", options.logTime, () => synthesizeReviewGuides(highAi, options.repo, options.ai, options.highModel ?? "", options.aiConcurrent, facts, usage, previousRules, edit, guideOutcome));
354
426
  log("ai", reviewDocuments
355
427
  ? `synth_guide complete · ${reviewDocuments.detailed ? "short + detailed" : "single guide"}`
356
428
  : reviewSignalCount(facts) > 2
@@ -426,6 +498,7 @@ async function initOrRemake(options, signal) {
426
498
  source,
427
499
  facts,
428
500
  sectionHashes: result.hashes,
501
+ ...guideState(previous, guideOutcome, reviewDocuments, facts),
429
502
  scanDone: {
430
503
  pullRequests: source.pullRequests.length,
431
504
  commits: source.commits.length,
@@ -8,6 +8,8 @@ export type Options = {
8
8
  prNumber?: number;
9
9
  debug: boolean;
10
10
  logTime: boolean;
11
+ /** `sync --full-guide`: rewrite the review guide in full this time. */
12
+ fullGuide?: boolean;
11
13
  /** Reviews every changed file with no own/upstream split, the behavior
12
14
  * before scope.ts existed. Off by default: a re-review round's diff can
13
15
  * carry a merge from the default branch that dwarfs the PR's own change,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "co-maintainer",
3
- "version": "0.7.7",
3
+ "version": "0.7.8-beta.2",
4
4
  "description": "An imitator of yours, A PR review tool like co-maintainer.",
5
5
  "keywords": [
6
6
  "ai",