co-maintainer 0.7.9 → 0.7.10-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,4 @@
1
1
  import type { ToolHandler } from "../ai/mermaid_loop.ts";
2
- import { type Run } from "./checkout.ts";
3
2
  import { type Presence } from "../tools/codegraph.ts";
4
3
  import { type CodegraphRunner } from "../tools/codegraph_exec.ts";
5
4
  export declare function ensureCodegraphIndex(binary: string, worktree: string, runner: CodegraphRunner, indexDir?: string): Promise<void>;
@@ -8,9 +7,12 @@ export declare function ensureCodegraphIndex(binary: string, worktree: string, r
8
7
  * `init`/`remake`/`serve` setup step, not for a single review that happens to
9
8
  * want this tool. With `allowInstall` (`--allow-tool-install`) a missing or
10
9
  * mismatched install is resolved through `ensureCodegraphForReview`, which
11
- * installs without prompting and returns a reason instead of exiting. */
12
- export declare function prepareCodegraphTools(repo: string, pr: number, commit: string, options?: {
13
- run?: Run;
10
+ * installs without prompting and returns a reason instead of exiting.
11
+ *
12
+ * `worktree` is the checkout to index, made by the caller
13
+ * (`prepareReviewTools`), which needs it for search too. It is asked for only
14
+ * once a codegraph binary is there. */
15
+ export declare function prepareCodegraphTools(worktree: () => Promise<string>, options?: {
14
16
  detect?: () => Promise<Presence>;
15
17
  allowInstall?: boolean;
16
18
  /** Overrides the install step, for tests. */
@@ -1,4 +1,4 @@
1
- import { ensureWorktree, pathExists, runCommand, } from "./checkout.js";
1
+ import { pathExists } from "./checkout.js";
2
2
  import { detect, ensureCodegraphForReview, } from "../tools/codegraph.js";
3
3
  import { createCodegraphRunner, LOCAL_CODEGRAPH_DIR, runCodegraphTool, SERVER_CODEGRAPH_DIR, } from "../tools/codegraph_exec.js";
4
4
  import { log } from "../util/log.js";
@@ -47,9 +47,12 @@ export async function ensureCodegraphIndex(binary, worktree, runner, indexDir =
47
47
  * `init`/`remake`/`serve` setup step, not for a single review that happens to
48
48
  * want this tool. With `allowInstall` (`--allow-tool-install`) a missing or
49
49
  * mismatched install is resolved through `ensureCodegraphForReview`, which
50
- * installs without prompting and returns a reason instead of exiting. */
51
- export async function prepareCodegraphTools(repo, pr, commit, options = {}) {
52
- const runner = options.run ?? runCommand;
50
+ * installs without prompting and returns a reason instead of exiting.
51
+ *
52
+ * `worktree` is the checkout to index, made by the caller
53
+ * (`prepareReviewTools`), which needs it for search too. It is asked for only
54
+ * once a codegraph binary is there. */
55
+ export async function prepareCodegraphTools(worktree, options = {}) {
53
56
  const detectPresence = options.detect ?? detect;
54
57
  const ensure = options.ensure ??
55
58
  (() => ensureCodegraphForReview({
@@ -73,10 +76,10 @@ export async function prepareCodegraphTools(repo, pr, commit, options = {}) {
73
76
  log("codegraph", `tools unavailable · codegraph is ${presence.state}`);
74
77
  return [];
75
78
  }
76
- const worktree = await ensureWorktree(repo, pr, commit, runner);
79
+ const tree = await worktree();
77
80
  const cgRun = createCodegraphRunner(SERVER_CODEGRAPH_DIR);
78
- await ensureCodegraphIndex(binary, worktree, cgRun);
79
- return codegraphTools(binary, worktree, cgRun);
81
+ await ensureCodegraphIndex(binary, tree, cgRun);
82
+ return codegraphTools(binary, tree, cgRun);
80
83
  }
81
84
  catch (error) {
82
85
  log("codegraph", `tools unavailable · ${String(error)}`);
@@ -0,0 +1,55 @@
1
+ /** The tools a review offers the model, prepared in one place for every mode
2
+ * (issue 79): codegraph when it is on, `search-non-code` where a checkout is
3
+ * there to search, and `read-full-diff` from the diff plan. A later kind of
4
+ * tool, such as a repository's MCP servers, joins the list here. */
5
+ import type { ToolHandler } from "../ai/mermaid_loop.ts";
6
+ import type { Options } from "../types.ts";
7
+ import { type Run } from "./checkout.ts";
8
+ import { type SearchOptions } from "../tools/search_non_code.ts";
9
+ /** Where a review's tools run. */
10
+ export type ReviewToolSource =
11
+ /** A checkout co-maintainer makes of the repository: the pull request's
12
+ * worktree for CLI PR and App reviews, worktree 0 at the pushed commit for
13
+ * a push review, which gets no search. */
14
+ {
15
+ kind: "checkout";
16
+ pr: number;
17
+ commit: string;
18
+ search: boolean;
19
+ allowInstall?: boolean;
20
+ }
21
+ /** A tree already on disk with its codegraph tools ready: local review at
22
+ * the git root. */
23
+ | {
24
+ kind: "tree";
25
+ root: string;
26
+ codegraph: ToolHandler[];
27
+ }
28
+ /** Tools another process runs: a remote review, where the client runs
29
+ * codegraph and search in its own checkout. */
30
+ | {
31
+ kind: "bridge";
32
+ tools: ToolHandler[];
33
+ };
34
+ export type ReviewTools = {
35
+ /** Every tool to offer, codegraph first. */
36
+ tools: ToolHandler[];
37
+ /** The codegraph tools alone, which decide `codegraphState`. */
38
+ codegraph: ToolHandler[];
39
+ };
40
+ export type ReviewToolsDeps = {
41
+ run?: Run;
42
+ /** Overrides the codegraph setup, for tests. */
43
+ codegraph?: (worktree: () => Promise<string>) => Promise<ToolHandler[]>;
44
+ /** Overrides the repository's search settings, for tests. */
45
+ search?: SearchOptions;
46
+ };
47
+ export declare function isCodegraphTool(name: string): boolean;
48
+ /** The review's tools. `diffTools` is the diff plan's own tools
49
+ * (`read-full-diff`), awaited last so the plan and the checkout can be
50
+ * prepared at the same time. A setup that fails leaves its tools out and the
51
+ * review goes on with the rest. */
52
+ export declare function prepareReviewTools(source: ReviewToolSource, options: Pick<Options, "repo" | "useCodegraph">, diffTools: ToolHandler[] | Promise<ToolHandler[]>, deps?: ReviewToolsDeps): Promise<ReviewTools>;
53
+ /** `codegraphState` from the codegraph tools alone, never from the length of
54
+ * the whole tool list. */
55
+ export declare function codegraphState(useCodegraph: boolean | undefined, codegraph: ToolHandler[]): "used" | "disabled" | "unavailable";
@@ -0,0 +1,69 @@
1
+ import { log } from "../util/log.js";
2
+ import { ensureWorktree, runCommand } from "./checkout.js";
3
+ import { prepareCodegraphTools } from "./codegraph_tools.js";
4
+ import { searchNonCodeTool, searchOptionsFor, } from "../tools/search_non_code.js";
5
+ export function isCodegraphTool(name) {
6
+ return name.startsWith("codegraph-");
7
+ }
8
+ /** The review's tools. `diffTools` is the diff plan's own tools
9
+ * (`read-full-diff`), awaited last so the plan and the checkout can be
10
+ * prepared at the same time. A setup that fails leaves its tools out and the
11
+ * review goes on with the rest. */
12
+ export async function prepareReviewTools(source, options, diffTools, deps = {}) {
13
+ const [own, diff] = await Promise.all([
14
+ prepareOwnTools(source, options, deps),
15
+ diffTools,
16
+ ]);
17
+ return { ...own, tools: [...own.tools, ...diff] };
18
+ }
19
+ async function prepareOwnTools(source, options, deps) {
20
+ const search = (root) => searchNonCodeTool(root, deps.search ?? searchOptionsFor(options.repo));
21
+ if (source.kind === "bridge") {
22
+ const codegraph = options.useCodegraph
23
+ ? source.tools.filter((tool) => isCodegraphTool(tool.name))
24
+ : [];
25
+ const others = source.tools.filter((tool) => !isCodegraphTool(tool.name));
26
+ return { tools: [...codegraph, ...others], codegraph };
27
+ }
28
+ if (source.kind === "tree") {
29
+ const codegraph = options.useCodegraph ? source.codegraph : [];
30
+ return {
31
+ tools: [...codegraph, search(source.root)],
32
+ codegraph,
33
+ };
34
+ }
35
+ if (!options.useCodegraph && !source.search) {
36
+ return { tools: [], codegraph: [] };
37
+ }
38
+ // One checkout for both, made once, and only when something needs it.
39
+ const run = deps.run ?? runCommand;
40
+ let checkout;
41
+ const worktree = () => (checkout ??= ensureWorktree(options.repo, source.pr, source.commit, run));
42
+ let root;
43
+ if (source.search) {
44
+ try {
45
+ root = await worktree();
46
+ }
47
+ catch (error) {
48
+ log("checkout", `search unavailable · ${String(error)}`);
49
+ }
50
+ }
51
+ const codegraph = options.useCodegraph
52
+ ? await (deps.codegraph
53
+ ? deps.codegraph(worktree)
54
+ : prepareCodegraphTools(worktree, {
55
+ allowInstall: source.allowInstall,
56
+ }))
57
+ : [];
58
+ return {
59
+ tools: [...codegraph, ...(root ? [search(root)] : [])],
60
+ codegraph,
61
+ };
62
+ }
63
+ /** `codegraphState` from the codegraph tools alone, never from the length of
64
+ * the whole tool list. */
65
+ export function codegraphState(useCodegraph, codegraph) {
66
+ if (!useCodegraph)
67
+ return "disabled";
68
+ return codegraph.length > 0 ? "used" : "unavailable";
69
+ }
@@ -1,6 +1,7 @@
1
- import { type ToolHandler } from "../ai/mermaid_loop.ts";
2
1
  import type { ReferenceContext } from "../review/references.ts";
3
2
  import type { Revision } from "../review/revision.ts";
3
+ import { type ReviewToolSource } from "./review_tools.ts";
4
+ import { type ToolUsage } from "../ai/tool_gate.ts";
4
5
  import { type Coverage, type CoverageWarning } from "../review/coverage.ts";
5
6
  import type { Snapshot } from "./snapshot.ts";
6
7
  import type { AiProvider, AiResponse, GitHubClient, Json, Options } from "../types.ts";
@@ -13,7 +14,10 @@ export declare function modelSummary(options: Options): string;
13
14
  export type ReviewExtras = {
14
15
  carryPrompt?: string;
15
16
  unchangedPaths?: string[];
16
- prepareCodegraphTools?: () => Promise<ToolHandler[]>;
17
+ /** Where the review's tools run. Left out, a pull request review checks
18
+ * the pull request out, and a workspace review is a push review, which
19
+ * checks out the pushed commit only for codegraph. */
20
+ tools?: ReviewToolSource;
17
21
  /** The pull request and its files, already read by the caller. The review
18
22
  * then makes neither request, so it judges what the caller stored. */
19
23
  prefetched?: {
@@ -49,8 +53,11 @@ export type ReviewOutcome = AiResponse & {
49
53
  referenceContext: ReferenceContext;
50
54
  codegraphState: "used" | "disabled" | "unavailable";
51
55
  coverage: Coverage;
52
- /** `diff_dropped`, `diff_withheld` and `summary_failed`. */
56
+ /** `diff_dropped`, `diff_withheld`, `summary_failed` and
57
+ * `tool_budget_spent`. */
53
58
  warnings: CoverageWarning[];
59
+ /** What the review's tools did, for `usage.tools`. */
60
+ tools: ToolUsage;
54
61
  /** Every changed file of the subject, for the result's `revision` block. */
55
62
  diffStats: {
56
63
  files: number;
@@ -76,6 +83,8 @@ export declare function reviewGuidesBlock(guide: string, detailed: string, codeb
76
83
  /** Shared PR and local/remote workspace review instructions: confirm claims
77
84
  * against the indexed graph, not only the diff slice. */
78
85
  export declare const CODEGRAPH_DIFF_VERIFICATION = "Examine the changes line by line, not just file by file. A single file can\ncontain more than one independent defect, and a change that looks fine in\nisolation can be wrong once you trace what calls it or what else it affects.\nWhen a finding depends on behavior outside the changed lines, confirm it with\ncodegraph-node, codegraph-callers, codegraph-callees, codegraph-impact, and\ncodegraph-affected before reporting it. Drop or correct findings that only seem\nplausible from the diff but contradict unchanged callers, callees, or the same\npattern elsewhere in the repo. Use those tools to check blast radius and whether\na test reaches the path. Do not guess coverage or impact from the diff alone\nwhen a tool can answer. A missing regression test is not a substitute for\nidentifying the concrete input or code path that misbehaves when you can.";
86
+ /** Said next to the codegraph instructions when the review offers search. */
87
+ export declare const SEARCH_NON_CODE_GUIDANCE = "Use search-non-code for docs, configuration and other files codegraph does not index. Use codegraph for code.";
79
88
  export declare function clampToolRounds(totalDiffLines: number): number;
80
89
  export declare function clampImproveMatrix(matrix: number): number;
81
90
  export declare function readGuide(repo: string, name: string): Promise<string>;
@@ -4,7 +4,9 @@ import { completeWithMermaidTools, } from "../ai/mermaid_loop.js";
4
4
  import { loadGuides } from "../review/guides.js";
5
5
  import { notInitializedError } from "../review/not_initialized.js";
6
6
  import { computeScope } from "./scope.js";
7
- import { prepareCodegraphTools } from "./codegraph_tools.js";
7
+ import { codegraphState, prepareReviewTools, } from "./review_tools.js";
8
+ import { ToolGate, toolBudgetChars, toolResultMaxChars, } from "../ai/tool_gate.js";
9
+ import { SEARCH_NON_CODE } from "../tools/search_non_code.js";
8
10
  import { severitySection } from "./review_copy.js";
9
11
  import { repositoryInstructionsBlock, reviewSystemPromptBlock, } from "../review/system_prompt.js";
10
12
  import { readDiffMaxChars } from "./diff_summary.js";
@@ -96,8 +98,8 @@ If a diagram is useful, call read-mermaid-syntaxes before writing any Mermaid.
96
98
  Request every type you need in a single call, because repeated tool rounds are
97
99
  capped. Use the smallest type that matches the evidence.`;
98
100
  const REVIEW_ROLE = `You are a precise open-source code reviewer.
99
- Evidence must come from the supplied diff and review guide. Keep findings
100
- concise by default.`;
101
+ Evidence must come from the supplied diff, the review guide and the results
102
+ of the tools you call. Keep findings concise by default.`;
101
103
  const REVIEW_DIAGRAM_RULES = `People generally find it easier to understand the
102
104
  problem you've identified when it's presented in diagrams. When a multi-step
103
105
  flow, lifecycle, dependency, data model, protocol, or architecture change is
@@ -156,6 +158,24 @@ pattern elsewhere in the repo. Use those tools to check blast radius and whether
156
158
  a test reaches the path. Do not guess coverage or impact from the diff alone
157
159
  when a tool can answer. A missing regression test is not a substitute for
158
160
  identifying the concrete input or code path that misbehaves when you can.`;
161
+ /** Said next to the codegraph instructions when the review offers search. */
162
+ export const SEARCH_NON_CODE_GUIDANCE = `Use search-non-code for docs, configuration and other files codegraph does not index. Use codegraph for code.`;
163
+ /** The codegraph instructions, with the search sentence when search is one
164
+ * of the tools the model can call. A provider without tool support gets
165
+ * none, so it is passed no tools. */
166
+ function toolGuidance(tools) {
167
+ return tools.some((tool) => tool.name === SEARCH_NON_CODE)
168
+ ? `${CODEGRAPH_DIFF_VERIFICATION}\n${SEARCH_NON_CODE_GUIDANCE}`
169
+ : CODEGRAPH_DIFF_VERIFICATION;
170
+ }
171
+ /** One review's tool gate, from the repository's settings. */
172
+ function reviewGate(repo) {
173
+ const repoConfig = readConfig().repos?.[repo];
174
+ return new ToolGate({
175
+ resultMaxChars: toolResultMaxChars(repoConfig),
176
+ budgetChars: toolBudgetChars(repoConfig),
177
+ });
178
+ }
159
179
  /** An AI call a Stop can cut between tool rounds. The calls made before the
160
180
  * Stop are paid, so their cost is recorded before the stop goes on up. */
161
181
  async function stoppable(call, usage) {
@@ -174,7 +194,7 @@ async function stoppable(call, usage) {
174
194
  * explicit reminder, if that also fails, the raw text is returned so the
175
195
  * legacy Markdown parser can still read it. This keeps a provider that ignores
176
196
  * `response_format` working, and never drops a review on the floor. */
177
- async function normalizeReviewResponse(provider, request, response, extraTools, maxToolRounds, usage, report, options, signal) {
197
+ async function normalizeReviewResponse(provider, request, response, extraTools, maxToolRounds, usage, report, options, gate, signal) {
178
198
  const direct = findingsMarkdownFromJson(response.text);
179
199
  if (direct !== undefined)
180
200
  return direct;
@@ -183,7 +203,7 @@ async function normalizeReviewResponse(provider, request, response, extraTools,
183
203
  ...request,
184
204
  job: "review_pull_request_retry",
185
205
  prompt: `${request.prompt}\n\nThe previous answer was not valid JSON. Return only the JSON object described above, with no prose and no code fence.`,
186
- }, 1, extraTools, maxToolRounds, { signal }), usage);
206
+ }, 1, extraTools, maxToolRounds, { signal, gate }), usage);
187
207
  if (usage)
188
208
  await usage(retry);
189
209
  if (options.debug) {
@@ -301,28 +321,40 @@ export async function reviewPullRequest(client, options, usage, snapshot, ai, pr
301
321
  }
302
322
  const provider = ai ?? reviewProvider(options, options.highModel, "high");
303
323
  const diagrams = provider.supportsTools !== false;
304
- const [prepared, codegraphTools] = await Promise.all([
305
- prepareReviewDiff({
306
- files: ownFiles.map(({ file }) => diffFileFromGithub(file)),
307
- unchangedPaths: extras?.unchangedPaths,
308
- catchesUp: extras?.catchesUp ?? false,
309
- tools: diagrams,
310
- concurrency: options.aiConcurrent,
311
- readDiffMaxChars: readDiffMaxChars(readConfig().repos?.[options.repo]),
312
- summaryProvider: () => summaryProvider(options, provider, report, extras),
313
- usage,
314
- report,
315
- }),
316
- options.useCodegraph && headSha
317
- ? prepareCodegraphTools(options.repo, number, headSha, {
324
+ const preparing = prepareReviewDiff({
325
+ files: ownFiles.map(({ file }) => diffFileFromGithub(file)),
326
+ unchangedPaths: extras?.unchangedPaths,
327
+ catchesUp: extras?.catchesUp ?? false,
328
+ tools: diagrams,
329
+ concurrency: options.aiConcurrent,
330
+ readDiffMaxChars: readDiffMaxChars(readConfig().repos?.[options.repo]),
331
+ summaryProvider: () => summaryProvider(options, provider, report, extras),
332
+ usage,
333
+ report,
334
+ });
335
+ // The pull request's checkout serves codegraph and search alike, and is
336
+ // made while the diff is prepared.
337
+ const source = extras?.tools ??
338
+ (headSha
339
+ ? {
340
+ kind: "checkout",
341
+ pr: number,
342
+ commit: headSha,
343
+ search: true,
318
344
  allowInstall: options.allowToolInstall,
319
- })
320
- : Promise.resolve([]),
345
+ }
346
+ : undefined);
347
+ const [prepared, reviewTools] = await Promise.all([
348
+ preparing,
349
+ source
350
+ ? prepareReviewTools(source, options, preparing.then((plan) => plan.tools))
351
+ : preparing.then((plan) => ({ tools: plan.tools, codegraph: [] })),
321
352
  ]);
322
353
  if (options.useCodegraph) {
323
- report(`codegraph tools · ${codegraphTools.length > 0 ? "ready" : "unavailable"}`);
354
+ report(`codegraph tools · ${reviewTools.codegraph.length > 0 ? "ready" : "unavailable"}`);
324
355
  }
325
- const extraTools = [...codegraphTools, ...prepared.tools];
356
+ const extraTools = reviewTools.tools;
357
+ const gate = reviewGate(options.repo);
326
358
  // Bigger own-scope diffs need more codegraph round-trips to trace, fixed
327
359
  // at 3 rounds regardless of size caused the model to run out mid-review on
328
360
  // large PRs (verified via a tokio benchmark run: it hallucinated fake
@@ -368,7 +400,7 @@ When the DIFF section below has an UPSTREAM CONTEXT part, that code arrived
368
400
  through a merge and was not authored by this pull request. Do not raise a
369
401
  finding located only there, and never mark blocking a finding whose only
370
402
  support is upstream context.
371
- ${CODEGRAPH_DIFF_VERIFICATION}
403
+ ${toolGuidance(diagrams ? extraTools : [])}
372
404
  Keep the default finding's "body" under 120 words excluding an optional
373
405
  suggestion. Write prose only: do not emit Markdown headings, a Location line,
374
406
  backticks around the path, or the sentence "If you'd like me to explain it in
@@ -413,6 +445,7 @@ ${diff}`;
413
445
  }
414
446
  let response = await stoppable(completeWithMermaidTools(provider, request, 1, extraTools, maxToolRounds, {
415
447
  signal,
448
+ gate,
416
449
  }), usage);
417
450
  if (usage)
418
451
  await usage(response);
@@ -427,7 +460,7 @@ ${diff}`;
427
460
  // The model returns JSON. We render the Markdown. A reply
428
461
  // that is not usable JSON is retried once and then falls back to the legacy
429
462
  // Markdown parser, so a provider that ignores the schema still works.
430
- let reviewText = await normalizeReviewResponse(provider, request, response, extraTools, maxToolRounds, usage, report, options, signal);
463
+ let reviewText = await normalizeReviewResponse(provider, request, response, extraTools, maxToolRounds, usage, report, options, gate, signal);
431
464
  for (let pass = 2; pass <= matrix; pass++) {
432
465
  const improvementRequest = {
433
466
  ...request,
@@ -448,7 +481,7 @@ ${reviewText}`,
448
481
  console.log(`[debug] improvement ${pass - 1} request · prompt=${improvementRequest.prompt.length} chars · maxTokens=${improvementRequest.maxTokens}`);
449
482
  }
450
483
  report(`AI improvement pass ${pass - 1} of ${matrix - 1}`);
451
- response = await stoppable(completeWithMermaidTools(provider, improvementRequest, 1, extraTools, maxToolRounds, { signal }), usage);
484
+ response = await stoppable(completeWithMermaidTools(provider, improvementRequest, 1, extraTools, maxToolRounds, { signal, gate }), usage);
452
485
  if (usage)
453
486
  await usage(response);
454
487
  report(`AI improvement response · input=${response.tokensIn} tokens · ` +
@@ -456,7 +489,7 @@ ${reviewText}`,
456
489
  if (!response.text.trim()) {
457
490
  throw new Error(`${aiProviderName(options)} returned an empty review improvement at pass ${pass - 1}`);
458
491
  }
459
- reviewText = await normalizeReviewResponse(provider, improvementRequest, response, extraTools, maxToolRounds, usage, report, options, signal);
492
+ reviewText = await normalizeReviewResponse(provider, improvementRequest, response, extraTools, maxToolRounds, usage, report, options, gate, signal);
460
493
  if (options.debug) {
461
494
  console.log(`[debug] improvement ${pass - 1} response · input=${response.tokensIn} tokens · output=${response.tokensOut} tokens`);
462
495
  console.log(`\n----- IMPROVED REVIEW ${pass - 1} -----\n${reviewText}\n`);
@@ -468,13 +501,10 @@ ${reviewText}`,
468
501
  visiblePaths: prepared.seenPaths,
469
502
  guideBuiltAt: guides.guideBuiltAt,
470
503
  referenceContext: { rules: guides.rules, codebase: guides.codebase },
471
- codegraphState: !options.useCodegraph
472
- ? "disabled"
473
- : codegraphTools.length > 0
474
- ? "used"
475
- : "unavailable",
504
+ codegraphState: codegraphState(options.useCodegraph, reviewTools.codegraph),
476
505
  coverage: prepared.coverage,
477
- warnings: prepared.warnings,
506
+ warnings: [...prepared.warnings, ...gate.warnings()],
507
+ tools: gate.usage(),
478
508
  diffStats: diffStats(named.map(({ file }) => diffFileFromGithub(file))),
479
509
  };
480
510
  }
@@ -505,12 +535,14 @@ export async function reviewWorkspaceRevision(revision, options, headSha, usage,
505
535
  usage,
506
536
  report,
507
537
  });
508
- const codegraphTools = options.useCodegraph
509
- ? extras?.prepareCodegraphTools
510
- ? await extras.prepareCodegraphTools()
511
- : await prepareCodegraphTools(options.repo, 0, headSha)
512
- : [];
513
- const extraTools = [...codegraphTools, ...prepared.tools];
538
+ const reviewTools = await prepareReviewTools(extras?.tools ?? {
539
+ kind: "checkout",
540
+ pr: 0,
541
+ commit: headSha,
542
+ search: false,
543
+ }, options, prepared.tools);
544
+ const extraTools = reviewTools.tools;
545
+ const gate = reviewGate(options.repo);
514
546
  const totalDiffLines = ownFiles.reduce((sum, file) => sum + file.changes, 0);
515
547
  const maxToolRounds = clampToolRounds(totalDiffLines);
516
548
  const ownDiff = prepared.diff;
@@ -527,7 +559,7 @@ the diff and either the guide or the codebase conventions.
527
559
  Do not invent low-value findings. If the diff contains a truncation marker or a
528
560
  file is summarized, limit claims to the supplied text and use read-full-diff or
529
561
  codegraph tools before asserting behavior outside what was shown.
530
- ${CODEGRAPH_DIFF_VERIFICATION}
562
+ ${toolGuidance(diagrams ? extraTools : [])}
531
563
  ${diagrams ? (plantumlPromptRules(options) ?? DIAGRAM_PROMPT_RULES) : NO_DIAGRAM_RULES}
532
564
  ${FINDINGS_JSON_INSTRUCTIONS}
533
565
 
@@ -553,13 +585,14 @@ ${ownDiff}${unchangedListing}`;
553
585
  report(`AI request · prompt=${prompt.length} chars`);
554
586
  let response = await stoppable(completeWithMermaidTools(provider, request, 1, extraTools, maxToolRounds, {
555
587
  signal,
588
+ gate,
556
589
  }), usage);
557
590
  if (usage)
558
591
  await usage(response);
559
592
  if (!response.text.trim()) {
560
593
  throw new Error(`${aiProviderName(options)} returned an empty review`);
561
594
  }
562
- let reviewText = await normalizeReviewResponse(provider, request, response, extraTools, maxToolRounds, usage, report, options, signal);
595
+ let reviewText = await normalizeReviewResponse(provider, request, response, extraTools, maxToolRounds, usage, report, options, gate, signal);
563
596
  for (let pass = 2; pass <= matrix; pass++) {
564
597
  const improvementRequest = {
565
598
  ...request,
@@ -577,25 +610,21 @@ ${prompt}
577
610
  DRAFT REVIEW (Markdown rendering of the previous JSON answer):
578
611
  ${reviewText}`,
579
612
  };
580
- response = await stoppable(completeWithMermaidTools(provider, improvementRequest, 1, extraTools, maxToolRounds, { signal }), usage);
613
+ response = await stoppable(completeWithMermaidTools(provider, improvementRequest, 1, extraTools, maxToolRounds, { signal, gate }), usage);
581
614
  if (usage)
582
615
  await usage(response);
583
- reviewText = await normalizeReviewResponse(provider, improvementRequest, response, extraTools, maxToolRounds, usage, report, options, signal);
616
+ reviewText = await normalizeReviewResponse(provider, improvementRequest, response, extraTools, maxToolRounds, usage, report, options, gate, signal);
584
617
  }
585
- const codegraphState = !options.useCodegraph
586
- ? "disabled"
587
- : codegraphTools.length > 0
588
- ? "used"
589
- : "unavailable";
590
618
  return {
591
619
  ...response,
592
620
  text: `${severitySection()}\n${renderDiagrams(reviewText, options)}`,
593
621
  visiblePaths: prepared.seenPaths,
594
622
  guideBuiltAt: guides.guideBuiltAt,
595
623
  referenceContext: { rules: guides.rules, codebase: guides.codebase },
596
- codegraphState,
624
+ codegraphState: codegraphState(options.useCodegraph, reviewTools.codegraph),
597
625
  coverage: prepared.coverage,
598
- warnings: prepared.warnings,
626
+ warnings: [...prepared.warnings, ...gate.warnings()],
627
+ tools: gate.usage(),
599
628
  diffStats: diffStats(files),
600
629
  };
601
630
  }
@@ -12,6 +12,8 @@ import { prepareLocalCodegraph } from "../local/codegraph_prepare.js";
12
12
  import { canPrompt } from "../tools/codegraph.js";
13
13
  import { runRemoteToolCalls, toolHandlerMap, } from "./client_tools.js";
14
14
  import { REMOTE_KNOWN_TOOL_NAMES } from "./schema.js";
15
+ import { searchNonCodeTool, searchOptionsFor, } from "../tools/search_non_code.js";
16
+ import { toolUsageFromJson } from "../ai/tool_gate.js";
15
17
  import { runCommand } from "../pr/checkout.js";
16
18
  import { assertGitQuiet, currentBranch, detectRemoteRepo, gitRoot, } from "../local/git_ops.js";
17
19
  import { buildLocalRevision, mergeBase, resolveBaseRef, } from "../local/git_revision.js";
@@ -165,7 +167,12 @@ export async function runRemoteReview(cli) {
165
167
  // `--json` must stay machine-readable, `canPrompt` adds TTY and CI.
166
168
  interactive: !cli.json && canPrompt(),
167
169
  });
168
- const localTools = toolHandlerMap(codegraphPrep.tools);
170
+ // The server asks for search the way it asks for codegraph, and the
171
+ // client runs it in this checkout. An older server ignores the name.
172
+ const localTools = toolHandlerMap([
173
+ ...codegraphPrep.tools,
174
+ searchNonCodeTool(root, searchOptionsFor(repo)),
175
+ ]);
169
176
  const capabilityTools = [...localTools.keys()]
170
177
  .filter((name) => REMOTE_KNOWN_TOOL_NAMES.has(name))
171
178
  .map((name) => ({ name }));
@@ -304,7 +311,6 @@ export async function runRemoteReview(cli) {
304
311
  catchesUp: true,
305
312
  extensions,
306
313
  intent: intent !== null,
307
- showReferences: readConfig().repos?.[repo]?.reviewReferences === true,
308
314
  });
309
315
  }
310
316
  else {
@@ -324,6 +330,8 @@ export async function runRemoteReview(cli) {
324
330
  extensions,
325
331
  intent: intent !== null,
326
332
  showReferences: readConfig().repos?.[repo]?.reviewReferences === true,
333
+ tools: toolUsageFromJson(payload.result.usage
334
+ ?.tools),
327
335
  }) +
328
336
  "\n");
329
337
  if (run)
@@ -13,6 +13,7 @@
13
13
  * - a server that cannot be reached or rejects the token is red. */
14
14
  import { VERSION } from "../version.js";
15
15
  import { exitWith } from "../cli/error.js";
16
+ import { toolUsageFromJson } from "../ai/tool_gate.js";
16
17
  import { formatHumanReview, humanFindingsFromJson, } from "../cli/review_result.js";
17
18
  import { coverageFromResult, warningsFromJson } from "../review/coverage.js";
18
19
  import { baseUrl, die, handshakeFailure, readApiError, remoteFetch, remoteFromEnv, } from "./http.js";
@@ -273,6 +274,8 @@ export async function runRemotePushReview(cli) {
273
274
  findings: human,
274
275
  warnings: warningsFromJson(payload.result.warnings),
275
276
  coverage: coverageFromResult(payload.result),
277
+ tools: toolUsageFromJson(payload.result.usage
278
+ ?.tools),
276
279
  }) +
277
280
  "\n");
278
281
  }
@@ -31,4 +31,5 @@ export const REMOTE_KNOWN_TOOL_NAMES = new Set([
31
31
  "codegraph-impact",
32
32
  "codegraph-affected",
33
33
  "read-full-diff",
34
+ "search-non-code",
34
35
  ]);
@@ -16,6 +16,7 @@ import { withResolvedReferences } from "../review/references.js";
16
16
  import { parseFindings } from "../pr/findings.js";
17
17
  import { githubFileToRevisionFile } from "../pr/github_revision.js";
18
18
  import { reviewWorkspaceRevision } from "../pr/reviewer.js";
19
+ import { emptyToolUsage } from "../ai/tool_gate.js";
19
20
  import { anchorTextFromPatch, parsePreviousVerdicts, } from "../review/carry_over.js";
20
21
  import { normalizeAnchor } from "../review/revision.js";
21
22
  import { revisionFromSubmitJson } from "../remote/revision_from_submit.js";
@@ -749,6 +750,7 @@ async function runPushReview(job, log, signal) {
749
750
  tokensOut,
750
751
  ...costUsage(costTally),
751
752
  billedTo: "server",
753
+ tools: response?.tools ?? emptyToolUsage(),
752
754
  },
753
755
  remote: { jobId: job.id, reviewId: review.id },
754
756
  };
@@ -4,6 +4,8 @@ import { CliError } from "../cli/error.js";
4
4
  import { resolvedFromFirstReview, reviewCoverageFields, sortResolvedFindings, summaryCounts, toJsonFinding, } from "../cli/review_result.js";
5
5
  import { parseFindings } from "../pr/findings.js";
6
6
  import { codegraphToolHandlersForBridge } from "../pr/codegraph_tools.js";
7
+ import { isCodegraphTool } from "../pr/review_tools.js";
8
+ import { SEARCH_NON_CODE, SEARCH_NON_CODE_TOOL, } from "../tools/search_non_code.js";
7
9
  import { reviewWorkspaceRevision } from "../pr/reviewer.js";
8
10
  import { buildCarryPromptSection, classifyCarryItems, guideRebuiltSince, incrementalDiffPaths, parsePreviousVerdicts, resolveCarryOutcomes, } from "../review/carry_over.js";
9
11
  import { visiblePathsToSave } from "../review/visible_paths.js";
@@ -301,7 +303,9 @@ export function registerRemoteReviewHandler() {
301
303
  const allowed = new Set((caps.tools ?? [])
302
304
  .map((tool) => tool.name)
303
305
  .filter((name) => typeof name === "string" && name));
304
- const useCodegraph = allowed.size > 0;
306
+ // Codegraph is on when the client offers a codegraph tool. Search
307
+ // alone does not turn it on.
308
+ const useCodegraph = [...allowed].some(isCodegraphTool);
305
309
  const options = reviewOptionsForRepo(job.repo, useCodegraph, byokKey, (text) => log("info", text));
306
310
  // The client's one-run instructions travel with the job, so a retry
307
311
  // keeps them. They apply on top of the server's per-repo prompt.
@@ -356,10 +360,18 @@ export function registerRemoteReviewHandler() {
356
360
  extras.carryPrompt = buildCarryPromptSection(carryItems, revision);
357
361
  }
358
362
  }
359
- if (useCodegraph) {
360
- const schemas = codegraphToolHandlersForBridge();
361
- extras.prepareCodegraphTools = async () => remoteBridgeToolHandlers(job.id, signal, allowed, schemas);
362
- }
363
+ // The client runs codegraph and search in its own checkout.
364
+ extras.tools = {
365
+ kind: "bridge",
366
+ tools: remoteBridgeToolHandlers(job.id, signal, allowed, [
367
+ ...codegraphToolHandlersForBridge(),
368
+ {
369
+ name: SEARCH_NON_CODE,
370
+ tool: SEARCH_NON_CODE_TOOL,
371
+ run: () => "",
372
+ },
373
+ ]),
374
+ };
363
375
  const started = performance.now();
364
376
  let tokensIn = 0;
365
377
  let tokensOut = 0;
@@ -404,6 +416,7 @@ export function registerRemoteReviewHandler() {
404
416
  tokensOut,
405
417
  ...costUsage(costTally),
406
418
  billedTo: billed,
419
+ tools: result.tools,
407
420
  },
408
421
  }, extensions, true);
409
422
  setRemoteSyncResult(job.id, {
@@ -5,6 +5,13 @@ import { type UserConfig } from "../config.ts";
5
5
  * someone else's machine. Raise it, adjust whatever reads the output, done. */
6
6
  export declare const CODEGRAPH_VERSION = "1.6.0";
7
7
  export declare const CODEGRAPH_PACKAGE = "@colbymchenry/codegraph";
8
+ /** The file extensions codegraph {@link CODEGRAPH_VERSION} extracts symbols
9
+ * from, lower case. `search-non-code` searches every other tracked text file,
10
+ * so update this list whenever the version is raised. Taken from
11
+ * `EXTENSION_MAP` in the installed package's `extraction/grammars.js`, without
12
+ * the languages it tracks only as files and extracts nothing from (`.yml`,
13
+ * `.yaml`, `.twig`, `.properties`, and `.xml` outside MyBatis mappers). */
14
+ export declare const CODEGRAPH_EXTENSIONS: readonly string[];
8
15
  /** A version that is safe in a directory name and an npm argument: a bare
9
16
  * semver, optionally with a prerelease suffix. Anything else (a path, a
10
17
  * leading `-`, whitespace) is refused, so a bad config value can never reach