@tobi-or-not/quorum 0.4.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 (111) hide show
  1. package/README.md +3 -1
  2. package/dist/bench/fingerprint.d.ts +8 -5
  3. package/dist/bench/fingerprint.js +28 -9
  4. package/dist/bench/records.d.ts +168 -0
  5. package/dist/bench/records.js +106 -1
  6. package/dist/bench/runner.d.ts +18 -0
  7. package/dist/bench/runner.js +30 -4
  8. package/dist/cli/bench.d.ts +11 -4
  9. package/dist/cli/bench.js +34 -17
  10. package/dist/cli/bin.js +2 -2
  11. package/dist/cli/io.d.ts +5 -0
  12. package/dist/cli/main.d.ts +67 -24
  13. package/dist/cli/main.js +288 -59
  14. package/dist/cli/print-config.d.ts +8 -6
  15. package/dist/cli/print-config.js +26 -8
  16. package/dist/cli/render.d.ts +9 -3
  17. package/dist/cli/render.js +43 -2
  18. package/dist/config/claude-code.d.ts +2 -6
  19. package/dist/config/claude-code.js +6 -44
  20. package/dist/config/command.d.ts +10 -0
  21. package/dist/config/command.js +47 -0
  22. package/dist/config/env.d.ts +32 -19
  23. package/dist/config/env.js +95 -32
  24. package/dist/config/from-config.js +21 -3
  25. package/dist/config/resolve.d.ts +13 -1
  26. package/dist/config/resolve.js +27 -1
  27. package/dist/config/schema.d.ts +152 -5
  28. package/dist/config/schema.js +156 -12
  29. package/dist/core/clock.d.ts +17 -0
  30. package/dist/core/clock.js +14 -0
  31. package/dist/core/coverage.d.ts +74 -0
  32. package/dist/core/coverage.js +221 -0
  33. package/dist/core/diff.d.ts +101 -0
  34. package/dist/core/diff.js +178 -35
  35. package/dist/core/errors.d.ts +12 -3
  36. package/dist/core/errors.js +21 -2
  37. package/dist/core/estimate.d.ts +45 -0
  38. package/dist/core/estimate.js +188 -0
  39. package/dist/core/exclude.d.ts +42 -0
  40. package/dist/core/exclude.js +189 -0
  41. package/dist/core/flags.d.ts +14 -1
  42. package/dist/core/flags.js +56 -0
  43. package/dist/core/inputs.d.ts +38 -0
  44. package/dist/core/inputs.js +228 -0
  45. package/dist/core/limits.d.ts +83 -0
  46. package/dist/core/limits.js +169 -0
  47. package/dist/core/output.d.ts +3 -2
  48. package/dist/core/output.js +3 -2
  49. package/dist/core/parts.d.ts +146 -0
  50. package/dist/core/parts.js +388 -0
  51. package/dist/core/ports.d.ts +67 -2
  52. package/dist/core/ports.js +36 -1
  53. package/dist/core/prompts.d.ts +22 -3
  54. package/dist/core/prompts.js +43 -7
  55. package/dist/core/quorum.d.ts +26 -8
  56. package/dist/core/quorum.js +310 -73
  57. package/dist/core/retry.d.ts +36 -0
  58. package/dist/core/retry.js +46 -0
  59. package/dist/core/secrets.d.ts +98 -0
  60. package/dist/core/secrets.js +507 -0
  61. package/dist/core/stages/context.d.ts +131 -23
  62. package/dist/core/stages/context.js +331 -46
  63. package/dist/core/stages/panel.d.ts +13 -6
  64. package/dist/core/stages/panel.js +79 -19
  65. package/dist/core/stages/research.d.ts +110 -25
  66. package/dist/core/stages/research.js +338 -44
  67. package/dist/core/tokens.d.ts +31 -0
  68. package/dist/core/tokens.js +81 -0
  69. package/dist/core/types.d.ts +280 -25
  70. package/dist/core/verify.d.ts +6 -0
  71. package/dist/core/verify.js +6 -3
  72. package/dist/git/run.d.ts +223 -0
  73. package/dist/git/run.js +608 -0
  74. package/dist/git/tree.d.ts +43 -0
  75. package/dist/git/tree.js +171 -0
  76. package/dist/index.d.ts +26 -2
  77. package/dist/index.js +34 -2
  78. package/dist/providers/anthropic.d.ts +3 -1
  79. package/dist/providers/anthropic.js +10 -3
  80. package/dist/providers/claude-code.d.ts +56 -11
  81. package/dist/providers/claude-code.js +70 -25
  82. package/dist/providers/gemini.d.ts +5 -1
  83. package/dist/providers/gemini.js +65 -11
  84. package/dist/providers/http.d.ts +49 -4
  85. package/dist/providers/http.js +155 -14
  86. package/dist/providers/ollama.d.ts +4 -1
  87. package/dist/providers/ollama.js +13 -5
  88. package/dist/providers/openai-compatible.d.ts +4 -1
  89. package/dist/providers/openai-compatible.js +13 -5
  90. package/dist/providers/options.d.ts +12 -3
  91. package/dist/providers/options.js +30 -10
  92. package/dist/providers/size.d.ts +19 -15
  93. package/dist/providers/size.js +33 -73
  94. package/dist/sources/added.d.ts +49 -0
  95. package/dist/sources/added.js +134 -0
  96. package/dist/sources/diff.d.ts +13 -0
  97. package/dist/sources/diff.js +63 -0
  98. package/dist/sources/local.d.ts +41 -0
  99. package/dist/sources/local.js +251 -0
  100. package/dist/sources/paths.d.ts +45 -0
  101. package/dist/sources/paths.js +230 -0
  102. package/dist/sources/range.d.ts +21 -0
  103. package/dist/sources/range.js +75 -0
  104. package/dist/sources/read.d.ts +69 -0
  105. package/dist/sources/read.js +37 -0
  106. package/dist/sources/repository.d.ts +9 -0
  107. package/dist/sources/repository.js +28 -0
  108. package/dist/sources/skips.d.ts +49 -0
  109. package/dist/sources/skips.js +126 -0
  110. package/package.json +1 -1
  111. package/schema/quorum.schema.json +49 -1
package/dist/cli/main.js CHANGED
@@ -1,34 +1,59 @@
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";
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";
10
12
  import { runBench } from "./bench.js";
11
13
  import { errorLines, errorMessage, EXIT, parseFlags } from "./io.js";
12
14
  import { printConfig } from "./print-config.js";
13
- import { bannerLines, progressSink } from "./render.js";
15
+ import { bannerLines, estimateLines, progressSink } from "./render.js";
14
16
  export { errorMessage, EXIT };
15
17
  const USAGE = [
16
18
  'Usage: quorum [options] [diff-file]',
17
19
  ' git diff | quorum [options]',
20
+ ' quorum --range <base>...<head> [options]',
21
+ ' quorum --local | --staged [options]',
22
+ ' quorum --path <path> [--at <rev>] [options]',
18
23
  ' quorum bench [options] <suite>',
19
24
  '',
20
25
  'Options:',
21
- ' -c, --config <path> Read this config file, over QUORUM_CONFIG',
22
- ' -p, --profile <id> Run only this profile; repeat it to run several',
23
- ' --allow-incomplete Exit 0 instead of 4 when the review is incomplete, except for a request too large for its model',
24
- ' --print-config Print the resolved config, keys redacted, and exit',
25
- ' -h, --help Print this help and exit',
26
- ' -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',
27
41
  '',
28
42
  ].join('\n');
43
+ /** The HTTP statuses, besides 5xx, that a call fails with in passing: a request timeout, a conflict and a rate limit. */
44
+ const PASSING_STATUSES = new Set([408, 409, 429]);
29
45
  const OPTIONS = {
30
46
  config: { type: 'string', short: 'c' },
31
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 },
32
57
  'allow-incomplete': { type: 'boolean' },
33
58
  'print-config': { type: 'boolean' },
34
59
  help: { type: 'boolean', short: 'h' },
@@ -36,25 +61,49 @@ const OPTIONS = {
36
61
  };
37
62
  /**
38
63
  * Run one review and return the process exit code. Never throws: usage and configuration problems
39
- * exit 2, runtime failures exit 3, an interrupt exits 130, and an incomplete review (a finding its
40
- * failed votes left undecided, or a research gap) of a gating profile exits 4 unless a `high` finding
41
- * was kept by a gating profile, so CI can tell a broken run and a partial review from a real finding
42
- * (exit 1) and from a clean one (exit 0). `exitCodeFor` maps the result; advisory flags never change it.
64
+ * exit 2, a gating profile's failed research and other runtime failures exit 3, an interrupt exits
65
+ * 130, and an incomplete review (a finding its failed votes left undecided, or a gap) of a gating
66
+ * profile exits 4 unless a `high` finding was kept by a gating profile, so CI can tell a broken run
67
+ * and a partial review from a real finding (exit 1) and from a clean one (exit 0). `--allow-incomplete`
68
+ * turns that exit 4 into 0 only when every failed vote behind it failed in passing (see `exitCodeFor`).
69
+ * `exitCodeFor` maps the result; advisory flags never change it.
43
70
  *
44
- * It reads at most 16 MiB of diff, from stdin or a file, counted in bytes: a larger diff is a usage error,
45
- * 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.
46
74
  *
47
- * Its flags are `--config`, `--profile`, `--allow-incomplete`, `--print-config`, `--help` and `--version`;
48
- * a usage error prints the usage after its message. Its settings are the config file `--config` or
49
- * `QUORUM_CONFIG` names (`--config` resolved against `io.cwd`, `QUORUM_CONFIG` an absolute path), and the
50
- * `QUORUM_*` variables of `io.env` with their deprecated aliases. Each warning is printed once, before the
51
- * banner, and when the configuration is refused the environment's warnings come before the `Error:` lines,
52
- * 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.
53
97
  *
54
98
  * `--print-config` reads no diff and calls no model: it writes the resolved config as YAML on stdout
55
- * (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
56
100
  * a configuration the run refuses, one of its providers that cannot be built included, exits 2 as in a run.
57
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
+ *
58
107
  * The run is interrupted when `io.signal` aborts: it then writes `interrupted` and returns 130, whatever
59
108
  * error ended the review, and writes no result. A review that has already resolved is complete.
60
109
  *
@@ -83,18 +132,14 @@ export async function runCli(io) {
83
132
  io.stdout.write(`quorum ${packageJson.version}\n`);
84
133
  return EXIT.ok;
85
134
  }
86
- const printing = values['print-config'] === true;
87
- let diff = '';
135
+ let spec;
88
136
  try {
89
137
  if (values.config === '') {
90
138
  throw new ConfigError([
91
139
  { path: '--config', message: 'must name a file' },
92
140
  ]);
93
141
  }
94
- if (printing && positionals.length > 0)
95
- throw new Error('--print-config takes no diff file');
96
- if (!printing)
97
- diff = await readDiff(io, positionals);
142
+ spec = await sourceSpec(io, values, positionals);
98
143
  }
99
144
  catch (error) {
100
145
  return usageError(io, error);
@@ -110,20 +155,37 @@ export async function runCli(io) {
110
155
  configPath: values.config,
111
156
  selection,
112
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
+ });
113
173
  quorum = await fromConfig(config, {
114
174
  env: io.env,
115
175
  events: progressSink(line => io.stderr.write(`${line}\n`)),
116
176
  });
117
- if (printing) {
177
+ if (read === undefined) {
118
178
  io.stdout.write(printConfig(config, source));
119
179
  return EXIT.ok;
120
180
  }
121
181
  writeWarnings(io, quorum.warnings);
122
182
  for (const line of bannerLines(config))
123
183
  io.stderr.write(`${line}\n`);
124
- 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() === '')
125
187
  io.stderr.write('empty diff: nothing to review\n');
126
- const result = await quorum.review({ diff }, { signal: io.signal });
188
+ const result = await quorum.review({ ...read, send }, { signal: io.signal });
127
189
  io.stdout.write(`${inertJson(result)}\n`);
128
190
  return exitCodeFor(result, { allowIncomplete: values['allow-incomplete'] === true });
129
191
  }
@@ -140,6 +202,24 @@ export async function runCli(io) {
140
202
  : EXIT.runtime;
141
203
  }
142
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
+ }
143
223
  /** Write each warning as an inert `warning:` line. */
144
224
  function writeWarnings(io, warnings) {
145
225
  for (const warning of warnings)
@@ -147,7 +227,7 @@ function writeWarnings(io, warnings) {
147
227
  }
148
228
  /**
149
229
  * The signal of one review, aborted by the first SIGINT or SIGTERM. The next one calls `exit(130)`: the
150
- * way out of a provider that ignores its signal, since no timer waits for it.
230
+ * way out when what a provider still runs, after the review settled its call, keeps the process alive.
151
231
  */
152
232
  export function interruptSignal(source, exit) {
153
233
  const controller = new AbortController();
@@ -165,44 +245,193 @@ export function interruptSignal(source, exit) {
165
245
  }
166
246
  /**
167
247
  * The exit code of a finished review: 1 when a kept finding is `high` and its profile gates, 4 when
168
- * an unreviewed finding or a gap belongs to a gating profile (unless `allowIncomplete` turns it into
169
- * 0, which it does for every gap but a `request-too-large` one), 0 otherwise. A profile gates
170
- * unless `meta.profiles` holds it with `gating: false`, so a profile missing from the result counts
171
- * as gating and a gap never hides.
248
+ * an unreviewed finding or a gap belongs to a gating profile, 0 otherwise. `allowIncomplete` turns
249
+ * that 4 into 0 only when every gap of a gating profile is a `vote-failed` one (an unreviewed finding
250
+ * is no gap) and, for each gating profile that has a gap, every failed vote of its own kept and
251
+ * unreviewed findings failed in passing, as `failedInPassing` says: a dropped connection, a timeout,
252
+ * or an HTTP 408, 409, 429 or 5xx. A gating profile with no gap blocks no other profile's lift. A gap
253
+ * with no failed vote behind it lifts nothing: an unreviewed finding whose votes hold none, or a
254
+ * `vote-failed` gap beside kept findings that hold none, which no review writes.
255
+ * A profile gates unless `meta.profiles` holds it with `gating: false`, so a profile missing from the
256
+ * result counts as gating and a gap never hides.
172
257
  *
173
- * A `request-too-large` gap of a gating profile exits 4 whatever `allowIncomplete` says: a pull
174
- * request can cause that gap by padding the diff until a request is refused, so no flag lifts it
175
- * (ADR-0012). The flag lifts every other gap, including gaps a pull request can cause: decoy findings
176
- * that push a real one past `maxFindings`, or text that trips a hosted voter's content filter. On a
177
- * gating profile, do not use it for a pull request you do not trust.
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`).
263
+ * The flag lifts only what the code names, so a reason added later is out of its reach by default,
264
+ * and so is what a result built by hand or by an older quorum leaves unsaid: a failed vote with no
265
+ * `failure`, a verdict whose `votes` is no array, a reason no quorum writes. A gating profile's
266
+ * `research-failed` gap, which no review records, is out too: a review that read nothing is never
267
+ * turned into exit 0. Planted text can still draw out a reply that ends in a lifted failure, a
268
+ * timeout of its own, so on a gating profile do not use the flag for a pull request you do not trust.
178
269
  */
179
270
  export function exitCodeFor(result, options = {}) {
180
271
  const gates = (profile) => !Object.hasOwn(result.meta.profiles, profile) || result.meta.profiles[profile].gating !== false;
181
272
  if (result.kept.some(verdict => verdict.confidence === 'high' && gates(verdict.profile)))
182
273
  return EXIT.finding;
183
- if (result.meta.incomplete.some(entry => entry.reason === 'request-too-large' && gates(entry.profile)))
184
- return EXIT.incomplete;
185
274
  const incomplete = result.unreviewed.some(verdict => gates(verdict.profile)) || result.meta.incomplete.some(entry => gates(entry.profile));
186
- return incomplete && options.allowIncomplete !== true
187
- ? EXIT.incomplete
188
- : EXIT.ok;
275
+ if (!incomplete)
276
+ return EXIT.ok;
277
+ return options.allowIncomplete === true && liftable(result, gates)
278
+ ? EXIT.ok
279
+ : EXIT.incomplete;
280
+ }
281
+ /** True when every gap of a gating profile is a `vote-failed` one, and each gating profile that has a gap passes `liftsProfile`. */
282
+ function liftable(result, gates) {
283
+ const gaps = result.meta.incomplete.filter(entry => gates(entry.profile));
284
+ if (gaps.some(entry => entry.reason !== 'vote-failed'))
285
+ return false;
286
+ const unreviewed = result.unreviewed.filter(verdict => gates(verdict.profile));
287
+ const profiles = new Set([
288
+ ...gaps,
289
+ ...unreviewed,
290
+ ].map(({ profile }) => profile));
291
+ return [...profiles].every(profile => liftsProfile(result, profile, gaps.some(entry => entry.profile === profile)));
292
+ }
293
+ /**
294
+ * True when the failed votes behind `profile`'s gaps all failed in passing: those of its own kept and
295
+ * unreviewed findings, each finding's `votes` an array. Every unreviewed finding holds a failed vote, and
296
+ * so do the kept findings when the profile has a `vote-failed` gap (`gap`): a gap with no failed vote behind
297
+ * it lifts nothing.
298
+ */
299
+ function liftsProfile(result, profile, gap) {
300
+ const kept = failedVotesOf(result.kept.filter(verdict => verdict.profile === profile));
301
+ const unreviewed = failedVotesOf(result.unreviewed.filter(verdict => verdict.profile === profile));
302
+ if (kept === undefined || unreviewed === undefined)
303
+ return false;
304
+ return [
305
+ ...kept,
306
+ ...unreviewed,
307
+ ].every(failed => failed.every(lensVote => failedInPassing(ownData(lensVote, 'failure'))))
308
+ && unreviewed.every(failed => failed.length > 0)
309
+ && (!gap || kept.some(failed => failed.length > 0));
310
+ }
311
+ /**
312
+ * The failed votes of each verdict, in order, or undefined when the `votes` of one is no array. A vote is
313
+ * cast only when its own data `vote` is an object and its own data `failure` is `null` or absent: any other
314
+ * entry is failed, so a vote that records a failure never counts as cast.
315
+ */
316
+ function failedVotesOf(verdicts) {
317
+ const lists = verdicts.map((verdict) => {
318
+ const votes = verdict.votes;
319
+ return Array.isArray(votes)
320
+ ? votes.filter((lensVote) => {
321
+ const cast = ownData(lensVote, 'vote');
322
+ const failure = ownData(lensVote, 'failure');
323
+ return typeof cast !== 'object' || cast === null || (failure !== null && failure !== undefined);
324
+ })
325
+ : undefined;
326
+ });
327
+ return lists.every(list => list !== undefined)
328
+ ? lists
329
+ : undefined;
330
+ }
331
+ /**
332
+ * True for a vote's failure that is infrastructure's: its own data `kind` is `network` or `timeout`, or
333
+ * `http` with an own data `status` of 408, 409, 429 or an integer from 500 to 599. Anything else is false:
334
+ * a refusal, a reply cut off or unusable, a request too large, any other status, a status that is no
335
+ * number, a kind no provider has, `null` and a value that is no object. It reads own data only, never
336
+ * runs a getter and never throws.
337
+ */
338
+ export function failedInPassing(failure) {
339
+ const kind = ownData(failure, 'kind');
340
+ if (kind === 'network' || kind === 'timeout')
341
+ return true;
342
+ const status = ownData(failure, 'status');
343
+ return kind === 'http' && typeof status === 'number' && Number.isInteger(status) && (PASSING_STATUSES.has(status) || (status >= 500 && status <= 599));
189
344
  }
190
345
  /** Write a usage error and the usage, and return its exit code. */
191
346
  function usageError(io, error) {
192
347
  io.stderr.write(`${errorLines(error)}\n${USAGE}`);
193
348
  return EXIT.usage;
194
349
  }
195
- /** Read the diff from the file argument, or from stdin unless stdin is an interactive terminal. */
196
- async function readDiff(io, positionals) {
197
- 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;
198
434
  if (extra.length > 0)
199
- throw new Error(`unexpected arguments: ${extra.join(' ')}`);
200
- if (!path && io.stdin.isTTY)
201
- throw new Error('no diff given');
202
- const diff = await decodeDiff(path
203
- ? createReadStream(resolve(io.cwd, path))
204
- : io.stdin);
205
- if (diff === undefined)
206
- throw new Error('the diff is over 16 MiB, the most quorum reads');
207
- 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) };
208
437
  }
@@ -1,12 +1,14 @@
1
1
  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
- * came from (`null` for none), the providers, the profiles that run, the limits the review applies, and
5
- * the warnings. A key and every value of `headers`, `query` and `extraBody` print as `[redacted]`, a base
6
- * URL as its origin, and a prompt as its SHA-256. A `claude-code` provider prints its protocol, command,
7
- * model, context size, key (redacted), auth mode and args, and no origin: the command and the args are the
8
- * user's own config. The view is an allowlist, so a field added to the config prints nothing until it is
9
- * added here on purpose.
4
+ * came from (`null` for none), the providers, the profiles that run, the limits the review applies
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
+ * the command and the args are the user's own config. The view is an allowlist, so a field added to the
11
+ * config prints nothing until it is added here on purpose.
10
12
  *
11
13
  * The text ends with a newline, and each line passes through `inertLine`. It is YAML 1.1, so a reader of
12
14
  * that version reads `off` as a string, and no line folds.
@@ -1,8 +1,10 @@
1
1
  import { createHash } from 'node:crypto';
2
2
  import { stringify } from 'yaml';
3
3
  import { own } from "../config/profiles.js";
4
- import { isProvider } from "../config/schema.js";
4
+ import { isProvider, statedFacts } from "../config/schema.js";
5
5
  import { DEFAULT_CONCURRENCY } from "../core/concurrency.js";
6
+ import { DEFAULT_MAX_REVIEW_TOKENS, DEFAULT_REVIEW_TIMEOUT_MS } from "../core/limits.js";
7
+ import { DEFAULT_PART_TOKENS } from "../core/parts.js";
6
8
  import { thresholdsFor } from "../core/profile.js";
7
9
  import { inertLine } from "../core/sanitize.js";
8
10
  import { DEFAULT_MAX_FINDINGS } from "../core/stages/research.js";
@@ -66,16 +68,21 @@ function specView(spec) {
66
68
  maxTokens: own(spec, 'maxTokens'),
67
69
  maxTokensField: own(spec, 'maxTokensField'),
68
70
  systemPrompt: systemPromptView(own(spec, 'systemPrompt')),
71
+ timeoutMs: own(spec, 'timeoutMs'),
72
+ retries: own(spec, 'retries'),
69
73
  };
70
74
  }
71
- /** A provider object by what it implements and its model, when that is a string; never its function. */
75
+ /** A provider object by what it implements, its model when that is a string, and the `timeoutMs` and `retries` it states; never its function. */
72
76
  function objectView(provider) {
73
77
  const model = own(provider, 'model');
78
+ const { timeoutMs, retries } = statedFacts(provider).stated;
74
79
  return {
75
80
  implements: 'Provider',
76
81
  model: typeof model === 'string'
77
82
  ? model
78
83
  : undefined,
84
+ timeoutMs,
85
+ retries,
79
86
  };
80
87
  }
81
88
  /** A profile that runs: its providers, the votes its policy needs, and each prompt as its hash. */
@@ -93,12 +100,14 @@ function profileView({ profile, research, voters }) {
93
100
  }
94
101
  /**
95
102
  * The resolved config as the YAML `--print-config` writes, for a CI log that anyone can read: the file it
96
- * came from (`null` for none), the providers, the profiles that run, the limits the review applies, and
97
- * the warnings. A key and every value of `headers`, `query` and `extraBody` print as `[redacted]`, a base
98
- * URL as its origin, and a prompt as its SHA-256. A `claude-code` provider prints its protocol, command,
99
- * model, context size, key (redacted), auth mode and args, and no origin: the command and the args are the
100
- * user's own config. The view is an allowlist, so a field added to the config prints nothing until it is
101
- * added here on purpose.
103
+ * came from (`null` for none), the providers, the profiles that run, the limits the review applies
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:
109
+ * the command and the args are the user's own config. The view is an allowlist, so a field added to the
110
+ * config prints nothing until it is added here on purpose.
102
111
  *
103
112
  * The text ends with a newline, and each line passes through `inertLine`. It is YAML 1.1, so a reader of
104
113
  * that version reads `off` as a string, and no line folds.
@@ -118,6 +127,15 @@ export function printConfig(config, source) {
118
127
  ])),
119
128
  concurrency: config.concurrency ?? DEFAULT_CONCURRENCY,
120
129
  maxFindings: config.maxFindings ?? DEFAULT_MAX_FINDINGS,
130
+ partTokens: config.partTokens ?? DEFAULT_PART_TOKENS,
131
+ maxReviewTokens: config.maxReviewTokens ?? DEFAULT_MAX_REVIEW_TOKENS,
132
+ reviewTimeoutMs: config.reviewTimeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS,
133
+ exclude: [
134
+ ...config.exclude ?? [],
135
+ ],
136
+ send: [
137
+ ...config.send ?? [],
138
+ ],
121
139
  warnings: [...config.warnings],
122
140
  };
123
141
  return stringify(view, { version: '1.1', lineWidth: 0, blockQuote: false }).split('\n').map(line => inertLine(line)).join('\n');
@@ -1,13 +1,13 @@
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.
7
7
  * Each line passes through `inertLine` whole: the reasons, details and file names it carries come
8
8
  * from the finder or the diff, and nothing in them can act on a terminal or a CI log. When `prefixed`,
9
- * a line of an event that names a profile starts with `[<profile>] `: the `flag:` and totals lines
10
- * belong to the whole review and never do.
9
+ * a line of an event that names a profile starts with `[<profile>] `: the `left out:`, `flag:` and totals
10
+ * lines belong to the whole review and never do.
11
11
  */
12
12
  export declare function renderEvent(event: QuorumEvent, prefixed?: boolean): string | undefined;
13
13
  /**
@@ -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