@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/README.md CHANGED
@@ -43,6 +43,7 @@ export QUORUM_RESEARCH_MODEL=qwen3.6:27b # a model your local Ollama serves
43
43
  export QUORUM_RESEARCH_CONTEXT_TOKENS=32768 # its context window, in tokens
44
44
  quorum ./my.diff > result.json # review a diff file
45
45
  git diff origin/main...HEAD | quorum > result.json # or what your branch changes
46
+ quorum --range origin/main...HEAD > result.json # what your branch changes, git run by quorum
46
47
  ```
47
48
 
48
49
  `QUORUM_RESEARCH_CONTEXT_TOKENS` is the model's context window in tokens, which quorum checks every request against, and without it the run exits `2` with a message that names it. With no provider configured and no base URL, preset or protocol variable, quorum talks to the Ollama on this machine through its native API, `http://localhost:11434`, which Ollama listens on, on `127.0.0.1`, by default. That API takes `num_ctx`, `truncate: false` and `shift: false`, so quorum tells the server the context size and the server refuses an overflow, where Ollama's OpenAI-compatible `/v1` would cut the prompt in silence. Refusing needs Ollama 0.12.6 or later: an older server ignores `truncate` and `shift`. A base URL variable set on its own means an OpenAI-compatible server, as before. Keep the number at most what `ollama show <model>` reports for the model, since Ollama clamps a larger `num_ctx` to it, and read the context a running model loaded in the `CONTEXT` column of `ollama ps`.
@@ -72,6 +73,7 @@ The JSON result goes to stdout, and the exit code says what to do with it: `0` f
72
73
 
73
74
  *Using it*
74
75
  - [The CLI](./docs/20-using/10-cli.md) *- The invocation, stdout and stderr, every exit code and its causes, and gating a CI job on them*
76
+ - [Sources](./docs/20-using/15-sources.md) *- A diff file or stdin, a range of commits, the local changes or the files at a commit, and how quorum runs git*
75
77
  - [Configuration](./docs/20-using/20-configuration.md) *- The config file and its trust model in CI, the `QUORUM_*` variables and the voter's fallback, the context size each provider states, running Claude Code, the keys, `--print-config`, and the errors a bad setting causes*
76
78
  - [Providers](./docs/20-using/30-providers.md) *- The provider port, the shipped adapters and their options, Claude Code run isolated as a provider, the presets, `ProviderError`, and writing a provider of your own*
77
79
  - [Profiles](./docs/20-using/40-profiles.md) *- The security profile, writing your own, several in one review, gating and guidelines*
@@ -8,11 +8,12 @@
8
8
  * out in place of their names; every field of a provider defined as data but its key, the values of
9
9
  * `headers`, `query` and `extraBody` and the whole base URL included, `timeoutMs` and `retries` among them;
10
10
  * a provider object as its config key, its model and the `timeoutMs` and `retries` it states, so one that
11
- * states none keeps the form it had, and never the `worstCase` it states, which is code like its `complete`;
12
- * `concurrency`, `maxFindings`, `maxReviewTokens` and `reviewTimeoutMs` as the review applies them, defaults
13
- * filled in, and `exclude` when the config lists a pattern. It holds no config-file path, no warning and no
14
- * provider name, so the same settings under other names are one configuration, and a rotated key keeps a
15
- * run. A `claude-code` provider's resolved command path is one of its settings, so it is in the form.
11
+ * states none keeps the form it had, and never the `worstCase` or the `room` it states, which are code like its
12
+ * `complete`; `concurrency`, `maxFindings`, `partTokens`, `maxReviewTokens` and `reviewTimeoutMs` as the review applies
13
+ * them, defaults filled in, `exclude` when the config lists a pattern, and `send` when it lists a file. It
14
+ * holds no config-file path, no warning and no provider name, so the same settings under other names are one
15
+ * configuration, and a rotated key keeps a run. A `claude-code` provider's resolved command path is one of its
16
+ * settings, so it is in the form.
16
17
  *
17
18
  * The form can hold a secret (a credential kept in a header, a query parameter or the base path), so it
18
19
  * never leaves this module: not written, not logged, not put in an error message. Only the HMAC does.
@@ -8,11 +8,12 @@
8
8
  * out in place of their names; every field of a provider defined as data but its key, the values of
9
9
  * `headers`, `query` and `extraBody` and the whole base URL included, `timeoutMs` and `retries` among them;
10
10
  * a provider object as its config key, its model and the `timeoutMs` and `retries` it states, so one that
11
- * states none keeps the form it had, and never the `worstCase` it states, which is code like its `complete`;
12
- * `concurrency`, `maxFindings`, `maxReviewTokens` and `reviewTimeoutMs` as the review applies them, defaults
13
- * filled in, and `exclude` when the config lists a pattern. It holds no config-file path, no warning and no
14
- * provider name, so the same settings under other names are one configuration, and a rotated key keeps a
15
- * run. A `claude-code` provider's resolved command path is one of its settings, so it is in the form.
11
+ * states none keeps the form it had, and never the `worstCase` or the `room` it states, which are code like its
12
+ * `complete`; `concurrency`, `maxFindings`, `partTokens`, `maxReviewTokens` and `reviewTimeoutMs` as the review applies
13
+ * them, defaults filled in, `exclude` when the config lists a pattern, and `send` when it lists a file. It
14
+ * holds no config-file path, no warning and no provider name, so the same settings under other names are one
15
+ * configuration, and a rotated key keeps a run. A `claude-code` provider's resolved command path is one of its
16
+ * settings, so it is in the form.
16
17
  *
17
18
  * The form can hold a secret (a credential kept in a header, a query parameter or the base path), so it
18
19
  * never leaves this module: not written, not logged, not put in an error message. Only the HMAC does.
@@ -25,6 +26,7 @@ import { isPlainObject } from "../config/load.js";
25
26
  import { isProvider, statedFacts } from "../config/schema.js";
26
27
  import { DEFAULT_CONCURRENCY } from "../core/concurrency.js";
27
28
  import { DEFAULT_MAX_REVIEW_TOKENS, DEFAULT_REVIEW_TIMEOUT_MS } from "../core/limits.js";
29
+ import { DEFAULT_PART_TOKENS } from "../core/parts.js";
28
30
  import { DEFAULT_MAX_FINDINGS } from "../core/stages/research.js";
29
31
  const SALT = /^[0-9a-f]{64}$/;
30
32
  /** A fresh salt: 32 random bytes as 64 lowercase hex digits. */
@@ -72,11 +74,15 @@ export function canonicalSettings(config) {
72
74
  return JSON.stringify({
73
75
  concurrency: config.concurrency ?? DEFAULT_CONCURRENCY,
74
76
  maxFindings: config.maxFindings ?? DEFAULT_MAX_FINDINGS,
77
+ partTokens: config.partTokens ?? DEFAULT_PART_TOKENS,
75
78
  maxReviewTokens: config.maxReviewTokens ?? DEFAULT_MAX_REVIEW_TOKENS,
76
79
  reviewTimeoutMs: config.reviewTimeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS,
77
80
  ...config.exclude === undefined
78
81
  ? {}
79
82
  : { exclude: config.exclude },
83
+ ...config.send === undefined
84
+ ? {}
85
+ : { send: config.send },
80
86
  profiles,
81
87
  }, sortKeys);
82
88
  }
@@ -219,6 +219,37 @@ export declare const resultSchema: z.ZodObject<{
219
219
  version: z.ZodString;
220
220
  startedAt: z.ZodString;
221
221
  durationMs: z.ZodInt;
222
+ source: z.ZodDiscriminatedUnion<[z.ZodObject<{
223
+ kind: z.ZodLiteral<"diff">;
224
+ }, z.core.$strict>, z.ZodObject<{
225
+ kind: z.ZodLiteral<"range">;
226
+ base: z.ZodString;
227
+ mergeBase: z.ZodString;
228
+ head: z.ZodString;
229
+ objectFormat: z.ZodEnum<{
230
+ sha1: "sha1";
231
+ sha256: "sha256";
232
+ }>;
233
+ }, z.core.$strict>, z.ZodObject<{
234
+ kind: z.ZodEnum<{
235
+ local: "local";
236
+ staged: "staged";
237
+ }>;
238
+ head: z.ZodNullable<z.ZodString>;
239
+ objectFormat: z.ZodEnum<{
240
+ sha1: "sha1";
241
+ sha256: "sha256";
242
+ }>;
243
+ }, z.core.$strict>, z.ZodObject<{
244
+ kind: z.ZodLiteral<"paths">;
245
+ commit: z.ZodString;
246
+ paths: z.ZodArray<z.ZodString>;
247
+ skips: z.ZodBoolean;
248
+ objectFormat: z.ZodEnum<{
249
+ sha1: "sha1";
250
+ sha256: "sha256";
251
+ }>;
252
+ }, z.core.$strict>], "kind">;
222
253
  profiles: z.ZodRecord<z.ZodString, z.ZodObject<{
223
254
  providers: z.ZodObject<{
224
255
  research: z.ZodObject<{
@@ -237,6 +268,41 @@ export declare const resultSchema: z.ZodObject<{
237
268
  }, z.core.$strict>;
238
269
  gating: z.ZodBoolean;
239
270
  invalidFindings: z.ZodInt;
271
+ coverage: z.ZodArray<z.ZodObject<{
272
+ file: z.ZodString;
273
+ status: z.ZodEnum<{
274
+ unreviewed: "unreviewed";
275
+ excluded: "excluded";
276
+ reviewed: "reviewed";
277
+ partial: "partial";
278
+ }>;
279
+ reason: z.ZodOptional<z.ZodEnum<{
280
+ "too-large": "too-large";
281
+ "token-cap": "token-cap";
282
+ "review-deadline": "review-deadline";
283
+ "research-failed": "research-failed";
284
+ "request-too-large": "request-too-large";
285
+ binary: "binary";
286
+ submodule: "submodule";
287
+ secret: "secret";
288
+ "deleted-secret": "deleted-secret";
289
+ }>>;
290
+ left: z.ZodOptional<z.ZodArray<z.ZodObject<{
291
+ start: z.ZodInt;
292
+ end: z.ZodInt;
293
+ reason: z.ZodEnum<{
294
+ "too-large": "too-large";
295
+ "token-cap": "token-cap";
296
+ "review-deadline": "review-deadline";
297
+ "research-failed": "research-failed";
298
+ "request-too-large": "request-too-large";
299
+ binary: "binary";
300
+ submodule: "submodule";
301
+ secret: "secret";
302
+ "deleted-secret": "deleted-secret";
303
+ }>;
304
+ }, z.core.$strict>>>;
305
+ }, z.core.$strict>>;
240
306
  }, z.core.$strict>>;
241
307
  usage: z.ZodOptional<z.ZodObject<{
242
308
  inputTokens: z.ZodNumber;
@@ -246,6 +312,7 @@ export declare const resultSchema: z.ZodObject<{
246
312
  incomplete: z.ZodArray<z.ZodObject<{
247
313
  profile: z.ZodString;
248
314
  reason: z.ZodEnum<{
315
+ "too-large": "too-large";
249
316
  "token-cap": "token-cap";
250
317
  "review-deadline": "review-deadline";
251
318
  "research-unusable": "research-unusable";
@@ -256,22 +323,53 @@ export declare const resultSchema: z.ZodObject<{
256
323
  "request-too-large": "request-too-large";
257
324
  binary: "binary";
258
325
  submodule: "submodule";
326
+ secret: "secret";
259
327
  }>;
260
328
  file: z.ZodOptional<z.ZodString>;
261
329
  detail: z.ZodString;
262
330
  }, z.core.$strict>>;
263
- leftOut: z.ZodArray<z.ZodObject<{
331
+ leftOut: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
264
332
  file: z.ZodString;
265
333
  reason: z.ZodEnum<{
266
334
  binary: "binary";
267
335
  submodule: "submodule";
268
336
  excluded: "excluded";
269
337
  }>;
270
- }, z.core.$strict>>;
338
+ }, z.core.$strict>, z.ZodObject<{
339
+ file: z.ZodString;
340
+ reason: z.ZodLiteral<"skipped">;
341
+ rule: z.ZodEnum<{
342
+ binary: "binary";
343
+ submodule: "submodule";
344
+ secret: "secret";
345
+ vendored: "vendored";
346
+ lockfile: "lockfile";
347
+ minified: "minified";
348
+ lfs: "lfs";
349
+ }>;
350
+ }, z.core.$strict>, z.ZodObject<{
351
+ file: z.ZodString;
352
+ reason: z.ZodEnum<{
353
+ secret: "secret";
354
+ "deleted-secret": "deleted-secret";
355
+ }>;
356
+ rule: z.ZodEnum<{
357
+ "private-key": "private-key";
358
+ "aws-key": "aws-key";
359
+ "github-token": "github-token";
360
+ "slack-token": "slack-token";
361
+ "google-key": "google-key";
362
+ "stripe-key": "stripe-key";
363
+ "anthropic-key": "anthropic-key";
364
+ "openai-key": "openai-key";
365
+ name: "name";
366
+ }>;
367
+ }, z.core.$strict>], "reason">>;
271
368
  flags: z.ZodArray<z.ZodObject<{
272
369
  code: z.ZodEnum<{
273
370
  "hidden-characters": "hidden-characters";
274
371
  "ai-addressed-text": "ai-addressed-text";
372
+ "secret-file": "secret-file";
275
373
  }>;
276
374
  file: z.ZodOptional<z.ZodString>;
277
375
  line: z.ZodOptional<z.ZodInt>;
@@ -14,7 +14,9 @@
14
14
  * that a model's reply denied, which denial it was, never the reply.
15
15
  */
16
16
  import { z } from 'zod';
17
+ import { SKIP_RULES, sourceIssues } from "../core/inputs.js";
17
18
  import { inertJsonLine } from "../core/sanitize.js";
19
+ import { SECRET_RULES } from "../core/secrets.js";
18
20
  import { MAX_TRIALS, SUITE_ID } from "./suite.js";
19
21
  /** The `format` of the run file this quorum writes and reads. */
20
22
  export const RUN_FORMAT = 2;
@@ -94,6 +96,33 @@ const usage = z.strictObject({
94
96
  outputTokens: amount,
95
97
  costUsd: amount.optional(),
96
98
  });
99
+ const coverageReason = z.enum([
100
+ 'binary',
101
+ 'submodule',
102
+ 'secret',
103
+ 'deleted-secret',
104
+ 'too-large',
105
+ 'request-too-large',
106
+ 'token-cap',
107
+ 'review-deadline',
108
+ 'research-failed',
109
+ ]);
110
+ const leftRange = z.strictObject({
111
+ start: count,
112
+ end: count,
113
+ reason: coverageReason,
114
+ });
115
+ const coverageEntry = z.strictObject({
116
+ file: z.string(),
117
+ status: z.enum([
118
+ 'reviewed',
119
+ 'partial',
120
+ 'unreviewed',
121
+ 'excluded',
122
+ ]),
123
+ reason: coverageReason.optional(),
124
+ left: z.array(leftRange).optional(),
125
+ });
97
126
  const profileMeta = z.strictObject({
98
127
  providers: z.strictObject({
99
128
  research: providerRef,
@@ -102,6 +131,7 @@ const profileMeta = z.strictObject({
102
131
  policy: thresholds,
103
132
  gating: z.boolean(),
104
133
  invalidFindings: count,
134
+ coverage: z.array(coverageEntry),
105
135
  });
106
136
  const incompleteEntry = z.strictObject({
107
137
  profile: z.string(),
@@ -112,20 +142,64 @@ const incompleteEntry = z.strictObject({
112
142
  'finding-unreadable',
113
143
  'vote-failed',
114
144
  'request-too-large',
145
+ 'too-large',
115
146
  'token-cap',
116
147
  'review-deadline',
117
148
  'binary',
118
149
  'submodule',
150
+ 'secret',
119
151
  ]),
120
152
  file: z.string().optional(),
121
153
  detail: z.string(),
122
154
  });
123
- const leftOutFile = z.strictObject({
124
- file: z.string(),
125
- reason: z.enum(['excluded', 'binary', 'submodule']),
126
- });
155
+ /** A file left out: a rule belongs to a skipped or a held file, and to none else. */
156
+ const leftOutFile = z.discriminatedUnion('reason', [
157
+ z.strictObject({
158
+ file: z.string(),
159
+ reason: z.enum(['excluded', 'binary', 'submodule']),
160
+ }),
161
+ z.strictObject({
162
+ file: z.string(),
163
+ reason: z.literal('skipped'),
164
+ rule: z.enum(SKIP_RULES),
165
+ }),
166
+ z.strictObject({
167
+ file: z.string(),
168
+ reason: z.enum(['secret', 'deleted-secret']),
169
+ rule: z.enum(SECRET_RULES),
170
+ }),
171
+ ]);
172
+ const objectFormat = z.enum(['sha1', 'sha256']);
173
+ /**
174
+ * Where a review's diff came from. The shapes are strict, one object per kind; the ids are checked as a
175
+ * review checks its input's, by `sourceIssues`, so a record holds a full commit id of its object format.
176
+ */
177
+ const reviewSource = z.discriminatedUnion('kind', [
178
+ z.strictObject({
179
+ kind: z.literal('diff'),
180
+ }),
181
+ z.strictObject({
182
+ kind: z.literal('range'),
183
+ base: z.string(),
184
+ mergeBase: z.string(),
185
+ head: z.string(),
186
+ objectFormat,
187
+ }),
188
+ z.strictObject({
189
+ kind: z.enum(['local', 'staged']),
190
+ head: z.string().nullable(),
191
+ objectFormat,
192
+ }),
193
+ z.strictObject({
194
+ kind: z.literal('paths'),
195
+ commit: z.string(),
196
+ paths: z.array(z.string()),
197
+ skips: z.boolean(),
198
+ objectFormat,
199
+ }),
200
+ ]).refine(source => sourceIssues(source).length === 0);
127
201
  const flag = z.strictObject({
128
- code: z.enum(['hidden-characters', 'ai-addressed-text']),
202
+ code: z.enum(['hidden-characters', 'ai-addressed-text', 'secret-file']),
129
203
  file: z.string().optional(),
130
204
  line: count.optional(),
131
205
  detail: z.string(),
@@ -143,6 +217,7 @@ export const resultSchema = z.strictObject({
143
217
  version: z.string(),
144
218
  startedAt: z.string(),
145
219
  durationMs: count,
220
+ source: reviewSource,
146
221
  profiles: z.record(z.string(), profileMeta),
147
222
  usage: usage.optional(),
148
223
  incomplete: z.array(incompleteEntry),
@@ -155,7 +155,7 @@ export async function runReviews(options) {
155
155
  });
156
156
  let result;
157
157
  try {
158
- result = await quorum.review({ diff }, { signal });
158
+ result = await quorum.review({ diff, send: configuration.config.send }, { signal });
159
159
  }
160
160
  catch (error) {
161
161
  const denied = signal.aborted
package/dist/cli/io.d.ts CHANGED
@@ -5,6 +5,7 @@
5
5
  */
6
6
  import type { ParseArgsOptionsConfig } from 'node:util';
7
7
  import type { Env } from '../config/env.ts';
8
+ import type { GitSeam } from '../sources/read.ts';
8
9
  /** Exit codes (ADR-0008, amended by ADR-0012). */
9
10
  export declare const EXIT: {
10
11
  readonly ok: 0;
@@ -32,6 +33,10 @@ export interface CliIO {
32
33
  };
33
34
  /** The review's signal: once it is aborted, a run that ends without a result exits 130. */
34
35
  readonly signal?: AbortSignal;
36
+ /** The git a source runs, for the specs: its executable and its spawn. A run looks git up on `PATH` when unset. */
37
+ readonly git?: GitSeam;
38
+ /** The platform the git sources check, `process.platform` when unset: for the specs. */
39
+ readonly platform?: NodeJS.Platform;
35
40
  }
36
41
  /**
37
42
  * The `Error:` lines of a failure, each inert: a ConfigError's issues one per line, as its message
@@ -12,20 +12,42 @@ export type { CliIO };
12
12
  * turns that exit 4 into 0 only when every failed vote behind it failed in passing (see `exitCodeFor`).
13
13
  * `exitCodeFor` maps the result; advisory flags never change it.
14
14
  *
15
- * It reads at most 16 MiB of diff, from stdin or a file, counted in bytes: a larger diff is a usage error,
16
- * and reading stops at the chunk that crosses the cap.
15
+ * It reads at most 16 MiB of diff, from stdin, a file, a range of commits, the local changes or the files at
16
+ * a commit, counted in bytes: a larger diff is a usage error. A diff file or stdin stops at the chunk that
17
+ * crosses the cap, and the child of a git source is stopped at its own cap.
17
18
  *
18
- * Its flags are `--config`, `--profile`, `--allow-incomplete`, `--print-config`, `--help` and `--version`;
19
- * a usage error prints the usage after its message. Its settings are the config file `--config` or
20
- * `QUORUM_CONFIG` names (`--config` resolved against `io.cwd`, `QUORUM_CONFIG` an absolute path), and the
21
- * `QUORUM_*` variables of `io.env` with their deprecated aliases. Each warning is printed once, before the
22
- * banner, and when the configuration is refused the environment's warnings come before the `Error:` lines,
23
- * since a deprecated or mistyped variable is often what caused the error.
19
+ * The diff comes from one source: a diff file, stdin, `--range <base>...<head>`, `--local` (what `git add
20
+ * -A` would commit), `--staged` (what the next commit holds) or `--path <path>` (the files under it at the
21
+ * commit `--at` names, HEAD by default, skipping by default what `--no-default-skips` reviews), the last four
22
+ * running git itself (see `rangeSource`, `localSource` and `pathsSource`). Every usage rule of the source is
23
+ * checked first, before any git and any config, the form of a range included (`parseRange`), and a diff file
24
+ * or stdin is read then. A git source is read once the config is: it needs the config's `exclude` and `send`,
25
+ * and a source git refuses, or a repository whose own config names a filter without `--trust-repo-config`, exits 2
26
+ * before the banner, a git command that fails exits 3.
27
+ *
28
+ * A path review is a codebase and not a change, so its size is the tree's. After the banner and before any
29
+ * call it prints its estimate on stderr (see `Quorum.estimate`), and exits 2 when its research's expected
30
+ * spend and what the calls in flight reserve pass `maxReviewTokens`, unless `--large` is given: the review then
31
+ * reviews what the cap allows and ends incomplete, exit 4, where the cap stops it. A diff, a range and the
32
+ * local changes print no estimate and are never gated, since their size is the change's.
33
+ *
34
+ * Its flags are `--config`, `--profile`, `--range`, `--local`, `--staged`, `--trust-repo-config`, `--path`,
35
+ * `--at`, `--no-default-skips`, `--large`, `--send`, `--allow-incomplete`, `--print-config`, `--help` and
36
+ * `--version`; a usage error prints the usage after its message. Its settings are the config file `--config` or `QUORUM_CONFIG`
37
+ * names (`--config` resolved against `io.cwd`, `QUORUM_CONFIG` an absolute path), and the `QUORUM_*`
38
+ * variables of `io.env` with their deprecated aliases. Each warning is printed once, before the banner, and
39
+ * when the configuration is refused the environment's warnings come before the `Error:` lines, since a
40
+ * deprecated or mistyped variable is often what caused the error.
24
41
  *
25
42
  * `--print-config` reads no diff and calls no model: it writes the resolved config as YAML on stdout
26
- * (see `printConfig`), warnings included, and returns 0; a diff argument with it is a usage error, and
43
+ * (see `printConfig`), warnings included, and returns 0; a diff argument or a git source with it is a usage error, and
27
44
  * a configuration the run refuses, one of its providers that cannot be built included, exits 2 as in a run.
28
45
  *
46
+ * A file held back as a secret is sent all the same when `--send <path>` names it, repeatable, or the config's
47
+ * `send` lists it: the path is the one the diff writes and the `left out:` line prints, matched exactly. The
48
+ * CLI merges both lists, the config's first, and gives them to the source, the estimate and the review, so
49
+ * the operator alone, never the change, lifts the hold. An empty `--send` is a usage error, before any config.
50
+ *
29
51
  * The run is interrupted when `io.signal` aborts: it then writes `interrupted` and returns 130, whatever
30
52
  * error ended the review, and writes no result. A review that has already resolved is complete.
31
53
  *
@@ -57,10 +79,11 @@ export declare function interruptSignal(source: SignalSource, exit: (code: numbe
57
79
  * A profile gates unless `meta.profiles` holds it with `gating: false`, so a profile missing from the
58
80
  * result counts as gating and a gap never hides.
59
81
  *
60
- * Why so narrow: a pull request causes the other gaps directly (ADR-0012). It pads the diff until a
61
- * request is refused as too large, floods the research with decoy findings past `maxFindings`, or
62
- * plants text that a voter refuses or that cuts its reply off or leaves it unusable, and one
63
- * `.gitattributes` line, one NUL byte or a submodule's bump leaves a file's change out of the diff.
82
+ * Why so narrow: a pull request causes the other gaps directly (ADR-0012). It pads a hunk until no
83
+ * research request holds it (`too-large`), floods the research with decoy findings past `maxFindings`, or
84
+ * plants text that a voter refuses or that cuts its reply off or leaves it unusable, one
85
+ * `.gitattributes` line, one NUL byte or a submodule's bump leaves a file's change out of the diff, and
86
+ * a file named as a secret, or one that holds a credential, is held back from every request (`secret`).
64
87
  * The flag lifts only what the code names, so a reason added later is out of its reach by default,
65
88
  * and so is what a result built by hand or by an older quorum leaves unsaid: a failed vote with no
66
89
  * `failure`, a verdict whose `votes` is no array, a reason no quorum writes. A gating profile's