@tobi-or-not/quorum 0.5.0 → 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.
Files changed (88) hide show
  1. package/README.md +2 -0
  2. package/dist/bench/fingerprint.d.ts +6 -5
  3. package/dist/bench/fingerprint.js +11 -5
  4. package/dist/bench/records.d.ts +100 -2
  5. package/dist/bench/records.js +80 -5
  6. package/dist/bench/runner.js +1 -1
  7. package/dist/cli/io.d.ts +5 -0
  8. package/dist/cli/main.d.ts +36 -13
  9. package/dist/cli/main.js +194 -44
  10. package/dist/cli/print-config.d.ts +5 -5
  11. package/dist/cli/print-config.js +10 -5
  12. package/dist/cli/render.d.ts +7 -1
  13. package/dist/cli/render.js +25 -3
  14. package/dist/config/claude-code.d.ts +2 -6
  15. package/dist/config/claude-code.js +6 -44
  16. package/dist/config/command.d.ts +10 -0
  17. package/dist/config/command.js +47 -0
  18. package/dist/config/from-config.js +8 -2
  19. package/dist/config/resolve.d.ts +4 -0
  20. package/dist/config/resolve.js +10 -0
  21. package/dist/config/schema.d.ts +13 -2
  22. package/dist/config/schema.js +36 -5
  23. package/dist/core/coverage.d.ts +38 -13
  24. package/dist/core/coverage.js +105 -28
  25. package/dist/core/diff.d.ts +77 -0
  26. package/dist/core/diff.js +122 -24
  27. package/dist/core/estimate.d.ts +45 -0
  28. package/dist/core/estimate.js +188 -0
  29. package/dist/core/flags.d.ts +14 -1
  30. package/dist/core/flags.js +56 -0
  31. package/dist/core/inputs.d.ts +38 -0
  32. package/dist/core/inputs.js +228 -0
  33. package/dist/core/limits.d.ts +5 -4
  34. package/dist/core/limits.js +11 -5
  35. package/dist/core/parts.d.ts +146 -0
  36. package/dist/core/parts.js +388 -0
  37. package/dist/core/ports.d.ts +10 -0
  38. package/dist/core/prompts.d.ts +22 -3
  39. package/dist/core/prompts.js +43 -7
  40. package/dist/core/quorum.d.ts +7 -5
  41. package/dist/core/quorum.js +164 -58
  42. package/dist/core/secrets.d.ts +98 -0
  43. package/dist/core/secrets.js +507 -0
  44. package/dist/core/stages/context.d.ts +16 -3
  45. package/dist/core/stages/context.js +44 -17
  46. package/dist/core/stages/panel.d.ts +8 -2
  47. package/dist/core/stages/panel.js +50 -9
  48. package/dist/core/stages/research.d.ts +107 -31
  49. package/dist/core/stages/research.js +290 -53
  50. package/dist/core/types.d.ts +217 -29
  51. package/dist/core/verify.d.ts +6 -0
  52. package/dist/core/verify.js +6 -3
  53. package/dist/git/run.d.ts +223 -0
  54. package/dist/git/run.js +608 -0
  55. package/dist/git/tree.d.ts +43 -0
  56. package/dist/git/tree.js +171 -0
  57. package/dist/index.d.ts +26 -2
  58. package/dist/index.js +34 -2
  59. package/dist/providers/anthropic.d.ts +2 -1
  60. package/dist/providers/anthropic.js +4 -2
  61. package/dist/providers/claude-code.d.ts +5 -0
  62. package/dist/providers/claude-code.js +11 -1
  63. package/dist/providers/gemini.d.ts +2 -1
  64. package/dist/providers/gemini.js +4 -2
  65. package/dist/providers/ollama.d.ts +2 -1
  66. package/dist/providers/ollama.js +4 -2
  67. package/dist/providers/openai-compatible.d.ts +2 -1
  68. package/dist/providers/openai-compatible.js +4 -2
  69. package/dist/providers/size.d.ts +9 -1
  70. package/dist/providers/size.js +18 -4
  71. package/dist/sources/added.d.ts +49 -0
  72. package/dist/sources/added.js +134 -0
  73. package/dist/sources/diff.d.ts +13 -0
  74. package/dist/sources/diff.js +63 -0
  75. package/dist/sources/local.d.ts +41 -0
  76. package/dist/sources/local.js +251 -0
  77. package/dist/sources/paths.d.ts +45 -0
  78. package/dist/sources/paths.js +230 -0
  79. package/dist/sources/range.d.ts +21 -0
  80. package/dist/sources/range.js +75 -0
  81. package/dist/sources/read.d.ts +69 -0
  82. package/dist/sources/read.js +37 -0
  83. package/dist/sources/repository.d.ts +9 -0
  84. package/dist/sources/repository.js +28 -0
  85. package/dist/sources/skips.d.ts +49 -0
  86. package/dist/sources/skips.js +126 -0
  87. package/package.json +1 -1
  88. package/schema/quorum.schema.json +15 -0
package/dist/cli/main.js CHANGED
@@ -1,30 +1,43 @@
1
- import { createReadStream } from 'node:fs';
2
- import { resolve } from 'node:path';
3
1
  import packageJson from '../../package.json' with { type: 'json' };
4
2
  import { readEnv } from "../config/env.js";
5
3
  import { fromConfig } from "../config/from-config.js";
6
4
  import { loadConfig } from "../config/load.js";
7
- import { decodeDiff } from "../core/diff.js";
8
5
  import { ConfigError } from "../core/errors.js";
9
6
  import { inertJson, inertLine } from "../core/sanitize.js";
10
7
  import { ownData } from "../core/stages/context.js";
8
+ import { readDiffInput } from "../sources/diff.js";
9
+ import { atProblem, pathProblem } from "../sources/paths.js";
10
+ import { parseRange } from "../sources/range.js";
11
+ import { readSource } from "../sources/read.js";
11
12
  import { runBench } from "./bench.js";
12
13
  import { errorLines, errorMessage, EXIT, parseFlags } from "./io.js";
13
14
  import { printConfig } from "./print-config.js";
14
- import { bannerLines, progressSink } from "./render.js";
15
+ import { bannerLines, estimateLines, progressSink } from "./render.js";
15
16
  export { errorMessage, EXIT };
16
17
  const USAGE = [
17
18
  'Usage: quorum [options] [diff-file]',
18
19
  ' git diff | quorum [options]',
20
+ ' quorum --range <base>...<head> [options]',
21
+ ' quorum --local | --staged [options]',
22
+ ' quorum --path <path> [--at <rev>] [options]',
19
23
  ' quorum bench [options] <suite>',
20
24
  '',
21
25
  'Options:',
22
- ' -c, --config <path> Read this config file, over QUORUM_CONFIG',
23
- ' -p, --profile <id> Run only this profile; repeat it to run several',
24
- ' --allow-incomplete Exit 0 instead of 4 when every gap is a vote that failed in passing: a dropped connection, a timeout, or an HTTP 408, 409, 429 or 5xx',
25
- ' --print-config Print the resolved config, keys redacted, and exit',
26
- ' -h, --help Print this help and exit',
27
- ' -v, --version Print the version and exit',
26
+ ' -c, --config <path> Read this config file, over QUORUM_CONFIG',
27
+ ' -p, --profile <id> Run only this profile; repeat it to run several',
28
+ ' --range <range> Review a range of commits, written <base>...<head>',
29
+ ' --local Review the local changes: staged, unstaged and untracked',
30
+ ' --staged Review the staged changes: what the next commit holds',
31
+ ' --trust-repo-config Run --local or --staged where the repository\'s own config names a filter program',
32
+ ' --path <path> Review the files under a path at a commit; repeat it to review several',
33
+ ' --at <rev> The commit --path reads, HEAD by default',
34
+ ' --no-default-skips Review in --path the vendored, lockfile, minified and binary files too',
35
+ ' --large Run a --path review that may pass the token cap, reviewing what the cap allows',
36
+ ' --send <path> Send a file held as a secret to the models all the same; repeat it to send several',
37
+ ' --allow-incomplete Exit 0 instead of 4 when every gap is a vote that failed in passing: a dropped connection, a timeout, or an HTTP 408, 409, 429 or 5xx',
38
+ ' --print-config Print the resolved config, keys redacted, and exit',
39
+ ' -h, --help Print this help and exit',
40
+ ' -v, --version Print the version and exit',
28
41
  '',
29
42
  ].join('\n');
30
43
  /** The HTTP statuses, besides 5xx, that a call fails with in passing: a request timeout, a conflict and a rate limit. */
@@ -32,6 +45,15 @@ const PASSING_STATUSES = new Set([408, 409, 429]);
32
45
  const OPTIONS = {
33
46
  config: { type: 'string', short: 'c' },
34
47
  profile: { type: 'string', short: 'p', multiple: true },
48
+ range: { type: 'string', multiple: true },
49
+ local: { type: 'boolean' },
50
+ staged: { type: 'boolean' },
51
+ 'trust-repo-config': { type: 'boolean' },
52
+ path: { type: 'string', multiple: true },
53
+ at: { type: 'string', multiple: true },
54
+ 'no-default-skips': { type: 'boolean' },
55
+ large: { type: 'boolean' },
56
+ send: { type: 'string', multiple: true },
35
57
  'allow-incomplete': { type: 'boolean' },
36
58
  'print-config': { type: 'boolean' },
37
59
  help: { type: 'boolean', short: 'h' },
@@ -46,20 +68,42 @@ const OPTIONS = {
46
68
  * turns that exit 4 into 0 only when every failed vote behind it failed in passing (see `exitCodeFor`).
47
69
  * `exitCodeFor` maps the result; advisory flags never change it.
48
70
  *
49
- * It reads at most 16 MiB of diff, from stdin or a file, counted in bytes: a larger diff is a usage error,
50
- * and reading stops at the chunk that crosses the cap.
71
+ * It reads at most 16 MiB of diff, from stdin, a file, a range of commits, the local changes or the files at
72
+ * a commit, counted in bytes: a larger diff is a usage error. A diff file or stdin stops at the chunk that
73
+ * crosses the cap, and the child of a git source is stopped at its own cap.
51
74
  *
52
- * Its flags are `--config`, `--profile`, `--allow-incomplete`, `--print-config`, `--help` and `--version`;
53
- * a usage error prints the usage after its message. Its settings are the config file `--config` or
54
- * `QUORUM_CONFIG` names (`--config` resolved against `io.cwd`, `QUORUM_CONFIG` an absolute path), and the
55
- * `QUORUM_*` variables of `io.env` with their deprecated aliases. Each warning is printed once, before the
56
- * banner, and when the configuration is refused the environment's warnings come before the `Error:` lines,
57
- * since a deprecated or mistyped variable is often what caused the error.
75
+ * The diff comes from one source: a diff file, stdin, `--range <base>...<head>`, `--local` (what `git add
76
+ * -A` would commit), `--staged` (what the next commit holds) or `--path <path>` (the files under it at the
77
+ * commit `--at` names, HEAD by default, skipping by default what `--no-default-skips` reviews), the last four
78
+ * running git itself (see `rangeSource`, `localSource` and `pathsSource`). Every usage rule of the source is
79
+ * checked first, before any git and any config, the form of a range included (`parseRange`), and a diff file
80
+ * or stdin is read then. A git source is read once the config is: it needs the config's `exclude` and `send`,
81
+ * and a source git refuses, or a repository whose own config names a filter without `--trust-repo-config`, exits 2
82
+ * before the banner, a git command that fails exits 3.
83
+ *
84
+ * A path review is a codebase and not a change, so its size is the tree's. After the banner and before any
85
+ * call it prints its estimate on stderr (see `Quorum.estimate`), and exits 2 when its research's expected
86
+ * spend and what the calls in flight reserve pass `maxReviewTokens`, unless `--large` is given: the review then
87
+ * reviews what the cap allows and ends incomplete, exit 4, where the cap stops it. A diff, a range and the
88
+ * local changes print no estimate and are never gated, since their size is the change's.
89
+ *
90
+ * Its flags are `--config`, `--profile`, `--range`, `--local`, `--staged`, `--trust-repo-config`, `--path`,
91
+ * `--at`, `--no-default-skips`, `--large`, `--send`, `--allow-incomplete`, `--print-config`, `--help` and
92
+ * `--version`; a usage error prints the usage after its message. Its settings are the config file `--config` or `QUORUM_CONFIG`
93
+ * names (`--config` resolved against `io.cwd`, `QUORUM_CONFIG` an absolute path), and the `QUORUM_*`
94
+ * variables of `io.env` with their deprecated aliases. Each warning is printed once, before the banner, and
95
+ * when the configuration is refused the environment's warnings come before the `Error:` lines, since a
96
+ * deprecated or mistyped variable is often what caused the error.
58
97
  *
59
98
  * `--print-config` reads no diff and calls no model: it writes the resolved config as YAML on stdout
60
- * (see `printConfig`), warnings included, and returns 0; a diff argument with it is a usage error, and
99
+ * (see `printConfig`), warnings included, and returns 0; a diff argument or a git source with it is a usage error, and
61
100
  * a configuration the run refuses, one of its providers that cannot be built included, exits 2 as in a run.
62
101
  *
102
+ * A file held back as a secret is sent all the same when `--send <path>` names it, repeatable, or the config's
103
+ * `send` lists it: the path is the one the diff writes and the `left out:` line prints, matched exactly. The
104
+ * CLI merges both lists, the config's first, and gives them to the source, the estimate and the review, so
105
+ * the operator alone, never the change, lifts the hold. An empty `--send` is a usage error, before any config.
106
+ *
63
107
  * The run is interrupted when `io.signal` aborts: it then writes `interrupted` and returns 130, whatever
64
108
  * error ended the review, and writes no result. A review that has already resolved is complete.
65
109
  *
@@ -88,18 +132,14 @@ export async function runCli(io) {
88
132
  io.stdout.write(`quorum ${packageJson.version}\n`);
89
133
  return EXIT.ok;
90
134
  }
91
- const printing = values['print-config'] === true;
92
- let diff = '';
135
+ let spec;
93
136
  try {
94
137
  if (values.config === '') {
95
138
  throw new ConfigError([
96
139
  { path: '--config', message: 'must name a file' },
97
140
  ]);
98
141
  }
99
- if (printing && positionals.length > 0)
100
- throw new Error('--print-config takes no diff file');
101
- if (!printing)
102
- diff = await readDiff(io, positionals);
142
+ spec = await sourceSpec(io, values, positionals);
103
143
  }
104
144
  catch (error) {
105
145
  return usageError(io, error);
@@ -115,20 +155,37 @@ export async function runCli(io) {
115
155
  configPath: values.config,
116
156
  selection,
117
157
  });
158
+ const send = [
159
+ ...config.send ?? [],
160
+ ...values.send ?? [],
161
+ ];
162
+ const read = spec === undefined
163
+ ? undefined
164
+ : await readSource(spec, {
165
+ cwd: io.cwd,
166
+ env: io.env,
167
+ platform: io.platform ?? process.platform,
168
+ signal: io.signal,
169
+ exclude: config.exclude,
170
+ send,
171
+ git: io.git,
172
+ });
118
173
  quorum = await fromConfig(config, {
119
174
  env: io.env,
120
175
  events: progressSink(line => io.stderr.write(`${line}\n`)),
121
176
  });
122
- if (printing) {
177
+ if (read === undefined) {
123
178
  io.stdout.write(printConfig(config, source));
124
179
  return EXIT.ok;
125
180
  }
126
181
  writeWarnings(io, quorum.warnings);
127
182
  for (const line of bannerLines(config))
128
183
  io.stderr.write(`${line}\n`);
129
- if (diff.trim() === '')
184
+ if (spec?.kind === 'paths')
185
+ holdLargeReview(io, quorum.estimate({ diff: read.diff, send }), values.large === true);
186
+ if (read.diff.trim() === '')
130
187
  io.stderr.write('empty diff: nothing to review\n');
131
- const result = await quorum.review({ diff }, { signal: io.signal });
188
+ const result = await quorum.review({ ...read, send }, { signal: io.signal });
132
189
  io.stdout.write(`${inertJson(result)}\n`);
133
190
  return exitCodeFor(result, { allowIncomplete: values['allow-incomplete'] === true });
134
191
  }
@@ -145,6 +202,24 @@ export async function runCli(io) {
145
202
  : EXIT.runtime;
146
203
  }
147
204
  }
205
+ /**
206
+ * Print a path review's estimate on stderr, and refuse the review when it may not finish under the token cap:
207
+ * its research's expected spend and what the calls in flight reserve are over `maxReviewTokens`. The gate is
208
+ * a `ConfigError` that names `--path`, a narrower path, the cap and `--large`, which `large` lifts: the review
209
+ * then runs, spends no more than the cap and ends incomplete where the cap stops it. It runs before any call.
210
+ */
211
+ function holdLargeReview(io, estimate, large) {
212
+ for (const line of estimateLines(estimate))
213
+ io.stderr.write(`${line}\n`);
214
+ if (estimate.fits || large)
215
+ return;
216
+ throw new ConfigError([
217
+ {
218
+ path: '--path',
219
+ message: `may not finish under the review's token cap of ${estimate.maxReviewTokens} tokens: its research alone expects about ${estimate.expected}, with ${estimate.inFlight} reserved at once: name a narrower path, raise maxReviewTokens, or pass --large to review what the cap allows`,
220
+ },
221
+ ]);
222
+ }
148
223
  /** Write each warning as an inert `warning:` line. */
149
224
  function writeWarnings(io, warnings) {
150
225
  for (const warning of warnings)
@@ -180,10 +255,11 @@ export function interruptSignal(source, exit) {
180
255
  * A profile gates unless `meta.profiles` holds it with `gating: false`, so a profile missing from the
181
256
  * result counts as gating and a gap never hides.
182
257
  *
183
- * Why so narrow: a pull request causes the other gaps directly (ADR-0012). It pads the diff until a
184
- * request is refused as too large, floods the research with decoy findings past `maxFindings`, or
185
- * plants text that a voter refuses or that cuts its reply off or leaves it unusable, and one
186
- * `.gitattributes` line, one NUL byte or a submodule's bump leaves a file's change out of the diff.
258
+ * Why so narrow: a pull request causes the other gaps directly (ADR-0012). It pads a hunk until no
259
+ * research request holds it (`too-large`), floods the research with decoy findings past `maxFindings`, or
260
+ * plants text that a voter refuses or that cuts its reply off or leaves it unusable, one
261
+ * `.gitattributes` line, one NUL byte or a submodule's bump leaves a file's change out of the diff, and
262
+ * a file named as a secret, or one that holds a credential, is held back from every request (`secret`).
187
263
  * The flag lifts only what the code names, so a reason added later is out of its reach by default,
188
264
  * and so is what a result built by hand or by an older quorum leaves unsaid: a failed vote with no
189
265
  * `failure`, a verdict whose `votes` is no array, a reason no quorum writes. A gating profile's
@@ -271,17 +347,91 @@ function usageError(io, error) {
271
347
  io.stderr.write(`${errorLines(error)}\n${USAGE}`);
272
348
  return EXIT.usage;
273
349
  }
274
- /** Read the diff from the file argument, or from stdin unless stdin is an interactive terminal. */
275
- async function readDiff(io, positionals) {
276
- const [path, ...extra] = positionals;
350
+ /**
351
+ * The one source the flags and the positional arguments name, with its usage rules checked before anything
352
+ * is read, in this order: a source beside `--print-config`, which reads no diff, so it names none
353
+ * (undefined); a second source, taken in the order diff file, `--range`, `--local`, `--staged`, `--path`,
354
+ * which names the first it cannot be given with; `--trust-repo-config` without `--local` or `--staged`;
355
+ * `--at`, `--large` or `--no-default-skips` without `--path`; an empty `--send`; a second range, a second commit. A
356
+ * diff file, or stdin when no file is named, is read here, as the usage errors of its own come before the config's. A range
357
+ * written wrongly is refused here too, in the words `rangeSource` refuses it with, and so is an empty or
358
+ * absolute `--path` value (`pathProblem`) and an `--at` that starts with `-` (`atProblem`), so no config is
359
+ * read for any of them.
360
+ */
361
+ async function sourceSpec(io, values, positionals) {
362
+ const refuse = (path, message) => new ConfigError([
363
+ { path, message },
364
+ ]);
365
+ const local = values.local === true;
366
+ const staged = values.staged === true;
367
+ const paths = values.path;
368
+ if (values['print-config']) {
369
+ if (values.range !== undefined || local || staged || paths !== undefined)
370
+ throw refuse('--print-config', 'reads no diff, so it takes no --range, --local, --staged or --path');
371
+ if (positionals.length > 0)
372
+ throw new Error('--print-config takes no diff file');
373
+ }
374
+ const [first, second] = [
375
+ { flag: 'a diff file', given: positionals.length > 0 },
376
+ { flag: '--range', given: values.range !== undefined },
377
+ { flag: '--local', given: local },
378
+ { flag: '--staged', given: staged },
379
+ { flag: '--path', given: paths !== undefined },
380
+ ].filter(({ given }) => given);
381
+ if (second !== undefined)
382
+ throw refuse(second.flag, `cannot be given with ${first.flag}: give one source`);
383
+ if (values['trust-repo-config'] === true && !local && !staged)
384
+ throw refuse('--trust-repo-config', 'needs --local or --staged');
385
+ if (paths === undefined) {
386
+ if (values.at !== undefined)
387
+ throw refuse('--at', 'needs --path');
388
+ if (values.large === true)
389
+ throw refuse('--large', 'needs --path');
390
+ if (values['no-default-skips'] === true)
391
+ throw refuse('--no-default-skips', 'needs --path');
392
+ }
393
+ if (values.send?.includes(''))
394
+ throw refuse('--send', 'must name a file');
395
+ if (values['print-config'])
396
+ return undefined;
397
+ if (values.range !== undefined) {
398
+ if (values.range.length > 1)
399
+ throw refuse('--range', 'takes one range');
400
+ const [range] = values.range;
401
+ const problem = parseRange(range);
402
+ if (typeof problem === 'string')
403
+ throw refuse('--range', problem);
404
+ return { kind: 'range', range };
405
+ }
406
+ if (local || staged) {
407
+ return {
408
+ kind: local
409
+ ? 'local'
410
+ : 'staged',
411
+ trustRepoConfig: values['trust-repo-config'] === true,
412
+ };
413
+ }
414
+ if (paths !== undefined) {
415
+ for (const value of paths) {
416
+ const problem = pathProblem(value);
417
+ if (problem !== undefined)
418
+ throw refuse('--path', problem);
419
+ }
420
+ if (values.at !== undefined && values.at.length > 1)
421
+ throw refuse('--at', 'takes one commit');
422
+ const at = values.at?.[0];
423
+ const atIssue = atProblem(at);
424
+ if (atIssue !== undefined)
425
+ throw refuse('--at', atIssue);
426
+ return {
427
+ kind: 'paths',
428
+ paths,
429
+ at,
430
+ skips: values['no-default-skips'] !== true,
431
+ };
432
+ }
433
+ const [file, ...extra] = positionals;
277
434
  if (extra.length > 0)
278
- throw new Error(`unexpected arguments: ${extra.join(' ')}`);
279
- if (!path && io.stdin.isTTY)
280
- throw new Error('no diff given');
281
- const diff = await decodeDiff(path
282
- ? createReadStream(resolve(io.cwd, path))
283
- : io.stdin);
284
- if (diff === undefined)
285
- throw new Error('the diff is over 16 MiB, the most quorum reads');
286
- return diff;
435
+ throw refuse('', `takes one diff file, and ${extra.length} more argument(s) were given`);
436
+ return { kind: 'diff', text: await readDiffInput(io.cwd, file, io.stdin) };
287
437
  }
@@ -2,11 +2,11 @@ import type { ResolvedConfig } from '../config/resolve.ts';
2
2
  /**
3
3
  * The resolved config as the YAML `--print-config` writes, for a CI log that anyone can read: the file it
4
4
  * came from (`null` for none), the providers, the profiles that run, the limits the review applies
5
- * (`concurrency`, `maxFindings`, `maxReviewTokens` and `reviewTimeoutMs`, defaults filled in), the
6
- * patterns it excludes, and the warnings. A key and every value of `headers`, `query` and `extraBody`
7
- * print as `[redacted]`, a base URL as its origin, and a prompt as its SHA-256. A provider's `timeoutMs` and
8
- * `retries` print when it sets them, a provider object's when it states them. A `claude-code` provider
9
- * prints its protocol, command, model, context size, key (redacted), auth mode and args, and no origin:
5
+ * (`concurrency`, `maxFindings`, `partTokens`, `maxReviewTokens` and `reviewTimeoutMs`, defaults filled in), the
6
+ * patterns it excludes, the files it sends though held as secrets, and the warnings. A key and every value of
7
+ * `headers`, `query` and `extraBody` print as `[redacted]`, a base URL as its origin, and a prompt as its
8
+ * SHA-256. A provider's `timeoutMs` and `retries` print when it sets them, a provider object's when it states
9
+ * them. A `claude-code` provider prints its protocol, command, model, context size, key (redacted), auth mode and args, and no origin:
10
10
  * the command and the args are the user's own config. The view is an allowlist, so a field added to the
11
11
  * config prints nothing until it is added here on purpose.
12
12
  *
@@ -4,6 +4,7 @@ import { own } from "../config/profiles.js";
4
4
  import { isProvider, statedFacts } from "../config/schema.js";
5
5
  import { DEFAULT_CONCURRENCY } from "../core/concurrency.js";
6
6
  import { DEFAULT_MAX_REVIEW_TOKENS, DEFAULT_REVIEW_TIMEOUT_MS } from "../core/limits.js";
7
+ import { DEFAULT_PART_TOKENS } from "../core/parts.js";
7
8
  import { thresholdsFor } from "../core/profile.js";
8
9
  import { inertLine } from "../core/sanitize.js";
9
10
  import { DEFAULT_MAX_FINDINGS } from "../core/stages/research.js";
@@ -100,11 +101,11 @@ function profileView({ profile, research, voters }) {
100
101
  /**
101
102
  * The resolved config as the YAML `--print-config` writes, for a CI log that anyone can read: the file it
102
103
  * came from (`null` for none), the providers, the profiles that run, the limits the review applies
103
- * (`concurrency`, `maxFindings`, `maxReviewTokens` and `reviewTimeoutMs`, defaults filled in), the
104
- * patterns it excludes, and the warnings. A key and every value of `headers`, `query` and `extraBody`
105
- * print as `[redacted]`, a base URL as its origin, and a prompt as its SHA-256. A provider's `timeoutMs` and
106
- * `retries` print when it sets them, a provider object's when it states them. A `claude-code` provider
107
- * prints its protocol, command, model, context size, key (redacted), auth mode and args, and no origin:
104
+ * (`concurrency`, `maxFindings`, `partTokens`, `maxReviewTokens` and `reviewTimeoutMs`, defaults filled in), the
105
+ * patterns it excludes, the files it sends though held as secrets, and the warnings. A key and every value of
106
+ * `headers`, `query` and `extraBody` print as `[redacted]`, a base URL as its origin, and a prompt as its
107
+ * SHA-256. A provider's `timeoutMs` and `retries` print when it sets them, a provider object's when it states
108
+ * them. A `claude-code` provider prints its protocol, command, model, context size, key (redacted), auth mode and args, and no origin:
108
109
  * the command and the args are the user's own config. The view is an allowlist, so a field added to the
109
110
  * config prints nothing until it is added here on purpose.
110
111
  *
@@ -126,11 +127,15 @@ export function printConfig(config, source) {
126
127
  ])),
127
128
  concurrency: config.concurrency ?? DEFAULT_CONCURRENCY,
128
129
  maxFindings: config.maxFindings ?? DEFAULT_MAX_FINDINGS,
130
+ partTokens: config.partTokens ?? DEFAULT_PART_TOKENS,
129
131
  maxReviewTokens: config.maxReviewTokens ?? DEFAULT_MAX_REVIEW_TOKENS,
130
132
  reviewTimeoutMs: config.reviewTimeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS,
131
133
  exclude: [
132
134
  ...config.exclude ?? [],
133
135
  ],
136
+ send: [
137
+ ...config.send ?? [],
138
+ ],
134
139
  warnings: [...config.warnings],
135
140
  };
136
141
  return stringify(view, { version: '1.1', lineWidth: 0, blockQuote: false }).split('\n').map(line => inertLine(line)).join('\n');
@@ -1,6 +1,6 @@
1
1
  import type { ResolvedConfig, ResolvedProvider } from '../config/resolve.ts';
2
2
  import type { EventSink, Provider } from '../core/ports.ts';
3
- import type { QuorumEvent } from '../core/types.ts';
3
+ import type { Estimate, QuorumEvent } from '../core/types.ts';
4
4
  /**
5
5
  * The progress line of an event, or undefined for the events the CLI keeps quiet about. These lines
6
6
  * are the CLI's progress output on stderr, so a person follows a run without the full event stream.
@@ -16,6 +16,12 @@ export declare function renderEvent(event: QuorumEvent, prefixed?: boolean): str
16
16
  * profile's line is prefixed. Rendering never throws, so the sink adds no failure of its own to a review.
17
17
  */
18
18
  export declare function progressSink(write: (line: string) => void): EventSink;
19
+ /**
20
+ * The lines a path review prints once its estimate is made, before any call: one per profile, starting with
21
+ * `[<id>] ` when several run, then the total, which belongs to the whole review and is never prefixed. The
22
+ * expected figure is the research's alone, as the votes are in the worst case only. Each line is inert.
23
+ */
24
+ export declare function estimateLines(estimate: Estimate): string[];
19
25
  /**
20
26
  * The origin of a provider defined as data, as the banner and `--print-config` name its endpoint: the
21
27
  * scheme, host and port of its own base URL, else of its preset's. Both are read as own fields, so a
@@ -46,14 +46,18 @@ function progressLine(event, prefixed) {
46
46
  }
47
47
  /**
48
48
  * The line that names the files a review left out: their count, the first `LISTED_FILES` of them as
49
- * `<file> (<reason>)`, then how many more. A file is a JSON string, as a flag's is; the empty name, which
50
- * stands for a part of the diff no header names, is `<no path>`.
49
+ * `<file> (<reason>)`, a skipped or a held one as `<file> (<reason>: <rule>)`, then how many more. A file is
50
+ * a JSON string, as a flag's is; the empty name, which stands for a part of the diff no header names, is
51
+ * `<no path>`.
51
52
  */
52
53
  function leftOutLine(files) {
53
54
  const named = (file) => file === ''
54
55
  ? '<no path>'
55
56
  : JSON.stringify(file);
56
- const entries = files.slice(0, LISTED_FILES).map(({ file, reason }) => `${named(file)} (${reason})`);
57
+ const reasonOf = (entry) => 'rule' in entry
58
+ ? `${entry.reason}: ${entry.rule}`
59
+ : entry.reason;
60
+ const entries = files.slice(0, LISTED_FILES).map(entry => `${named(entry.file)} (${reasonOf(entry)})`);
57
61
  const more = files.length > LISTED_FILES
58
62
  ? ` and ${files.length - LISTED_FILES} more`
59
63
  : '';
@@ -84,6 +88,24 @@ export function progressSink(write) {
84
88
  write(line);
85
89
  };
86
90
  }
91
+ /**
92
+ * The lines a path review prints once its estimate is made, before any call: one per profile, starting with
93
+ * `[<id>] ` when several run, then the total, which belongs to the whole review and is never prefixed. The
94
+ * expected figure is the research's alone, as the votes are in the worst case only. Each line is inert.
95
+ */
96
+ export function estimateLines(estimate) {
97
+ const entries = Object.entries(estimate.profiles);
98
+ const prefixed = entries.length > 1;
99
+ return [
100
+ ...entries.map(([id, { parts, expected, votes, worst }]) => {
101
+ const prefix = prefixed
102
+ ? profilePrefix(id)
103
+ : '';
104
+ return `${prefix}estimate: ${parts.length} research part(s), about ${expected} tokens expected for them; then up to ${votes} vote(s), at most ${worst} tokens in all`;
105
+ }),
106
+ `estimate: research about ${estimate.expected} tokens expected, at most ${estimate.worst} with every vote, ${estimate.inFlight} of them reserved at once; the review's token cap is ${estimate.maxReviewTokens} and its deadline ${estimate.reviewTimeoutMs} ms`,
107
+ ].map(inertLine);
108
+ }
87
109
  /**
88
110
  * The origin of a provider defined as data, as the banner and `--print-config` name its endpoint: the
89
111
  * scheme, host and port of its own base URL, else of its preset's. Both are read as own fields, so a
@@ -10,12 +10,8 @@ import type { ProviderSettings } from './schema.ts';
10
10
  /** The issue of a provider whose command is neither set nor on `PATH`. */
11
11
  export declare const CLAUDE_NOT_FOUND = "claude CLI not found; install Claude Code or set QUORUM_CLAUDE_CODE_COMMAND";
12
12
  /**
13
- * The executable `command` names: an absolute path as it is, a bare name in the first absolute entry of the
14
- * environment's `PATH` that holds it (`;` separates the entries on Windows, `:` elsewhere, and a name with no
15
- * extension is looked up as `<name>.exe` there). A match is a regular file the process may run; any file
16
- * system error is no match. Never reads a relative entry, and never a variable the environment only inherits.
17
- * A command the adapter refuses (a relative path with a separator, which would climb out of an entry, or a
18
- * Windows script) names no executable.
13
+ * The executable `command` names (`findExecutable`), unless the adapter refuses the command first: a relative
14
+ * path with a separator, which would climb out of an entry, or a Windows script names no executable.
19
15
  */
20
16
  export declare function findCommand(command: string, env: Env, platform?: NodeJS.Platform): string | undefined;
21
17
  /** What a provider's command comes to: the executable it runs, or the issues that say why there is none. */
@@ -1,6 +1,5 @@
1
- import { accessSync, constants, statSync } from 'node:fs';
2
- import { extname, isAbsolute, join } from 'node:path';
3
1
  import { commandProblem } from "../providers/claude-code.js";
2
+ import { findExecutable } from "./command.js";
4
3
  import { CLAUDE_CODE_COMMAND, envValue } from "./env.js";
5
4
  import { own } from "./profiles.js";
6
5
  import { configPath } from "./schema.js";
@@ -14,51 +13,14 @@ import { configPath } from "./schema.js";
14
13
  export const CLAUDE_NOT_FOUND = `claude CLI not found; install Claude Code or set ${CLAUDE_CODE_COMMAND}`;
15
14
  const NO_EXECUTABLE = 'names no executable file';
16
15
  const DEFAULT_COMMAND = 'claude';
17
- /** Whether `path` names a regular file the process may run; on Windows no file has an execute bit, so a regular file is enough. Any file system error is no. */
18
- function isExecutableFile(path, platform) {
19
- try {
20
- if (!statSync(path).isFile())
21
- return false;
22
- if (platform !== 'win32')
23
- accessSync(path, constants.X_OK);
24
- return true;
25
- }
26
- catch {
27
- return false;
28
- }
29
- }
30
- /** The `PATH` of the environment: its own variable, in the letter case Windows gives its name, else undefined. */
31
- function searchPath(env, platform) {
32
- const name = platform === 'win32'
33
- ? Object.keys(env).find(key => key.toUpperCase() === 'PATH')
34
- : 'PATH';
35
- return name === undefined
36
- ? undefined
37
- : envValue(env, name);
38
- }
39
16
  /**
40
- * The executable `command` names: an absolute path as it is, a bare name in the first absolute entry of the
41
- * environment's `PATH` that holds it (`;` separates the entries on Windows, `:` elsewhere, and a name with no
42
- * extension is looked up as `<name>.exe` there). A match is a regular file the process may run; any file
43
- * system error is no match. Never reads a relative entry, and never a variable the environment only inherits.
44
- * A command the adapter refuses (a relative path with a separator, which would climb out of an entry, or a
45
- * Windows script) names no executable.
17
+ * The executable `command` names (`findExecutable`), unless the adapter refuses the command first: a relative
18
+ * path with a separator, which would climb out of an entry, or a Windows script names no executable.
46
19
  */
47
20
  export function findCommand(command, env, platform = process.platform) {
48
- if (commandProblem(command) !== undefined)
49
- return undefined;
50
- if (isAbsolute(command)) {
51
- return isExecutableFile(command, platform)
52
- ? command
53
- : undefined;
54
- }
55
- const file = platform === 'win32' && extname(command) === ''
56
- ? `${command}.exe`
57
- : command;
58
- const entries = (searchPath(env, platform) ?? '').split(platform === 'win32'
59
- ? ';'
60
- : ':').filter(entry => isAbsolute(entry));
61
- return entries.map(entry => join(entry, file)).find(candidate => isExecutableFile(candidate, platform));
21
+ return commandProblem(command) === undefined
22
+ ? findExecutable(command, env, platform)
23
+ : undefined;
62
24
  }
63
25
  /**
64
26
  * The command of a `claude-code` provider in use: `variable` (`QUORUM_CLAUDE_CODE_COMMAND`, already checked),
@@ -0,0 +1,10 @@
1
+ import type { Env } from './env.ts';
2
+ /**
3
+ * The executable `command` names: an absolute path as it is, a bare name in the first absolute entry of the
4
+ * environment's `PATH` that holds it (`;` separates the entries on Windows, `:` elsewhere, and a name with no
5
+ * extension is looked up as `<name>.exe` there). A match is a regular file the process may run; any file
6
+ * system error is no match. Never reads a relative entry, and never a variable the environment only inherits.
7
+ * It takes the command as it is given: a caller whose command a user wrote refuses a relative path with a
8
+ * separator, which would climb out of an entry, before it gets here (`findCommand` does).
9
+ */
10
+ export declare function findExecutable(command: string, env: Env, platform: NodeJS.Platform): string | undefined;
@@ -0,0 +1,47 @@
1
+ import { accessSync, constants, statSync } from 'node:fs';
2
+ import { extname, isAbsolute, join } from 'node:path';
3
+ import { envValue } from "./env.js";
4
+ /** Whether `path` names a regular file the process may run; on Windows no file has an execute bit, so a regular file is enough. Any file system error is no. */
5
+ function isExecutableFile(path, platform) {
6
+ try {
7
+ if (!statSync(path).isFile())
8
+ return false;
9
+ if (platform !== 'win32')
10
+ accessSync(path, constants.X_OK);
11
+ return true;
12
+ }
13
+ catch {
14
+ return false;
15
+ }
16
+ }
17
+ /** The `PATH` of the environment: its own variable, in the letter case Windows gives its name, else undefined. */
18
+ function searchPath(env, platform) {
19
+ const name = platform === 'win32'
20
+ ? Object.keys(env).find(key => key.toUpperCase() === 'PATH')
21
+ : 'PATH';
22
+ return name === undefined
23
+ ? undefined
24
+ : envValue(env, name);
25
+ }
26
+ /**
27
+ * The executable `command` names: an absolute path as it is, a bare name in the first absolute entry of the
28
+ * environment's `PATH` that holds it (`;` separates the entries on Windows, `:` elsewhere, and a name with no
29
+ * extension is looked up as `<name>.exe` there). A match is a regular file the process may run; any file
30
+ * system error is no match. Never reads a relative entry, and never a variable the environment only inherits.
31
+ * It takes the command as it is given: a caller whose command a user wrote refuses a relative path with a
32
+ * separator, which would climb out of an entry, before it gets here (`findCommand` does).
33
+ */
34
+ export function findExecutable(command, env, platform) {
35
+ if (isAbsolute(command)) {
36
+ return isExecutableFile(command, platform)
37
+ ? command
38
+ : undefined;
39
+ }
40
+ const file = platform === 'win32' && extname(command) === ''
41
+ ? `${command}.exe`
42
+ : command;
43
+ const entries = (searchPath(env, platform) ?? '').split(platform === 'win32'
44
+ ? ';'
45
+ : ':').filter(entry => isAbsolute(entry));
46
+ return entries.map(entry => join(entry, file)).find(candidate => isExecutableFile(candidate, platform));
47
+ }