@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
@@ -40,12 +40,31 @@ export interface Lens {
40
40
  /** What the voter judging from this lens is asked, filled into the vote template's `{{lens.question}}`. */
41
41
  readonly question: string;
42
42
  }
43
- /** One lens's vote, or the error if that call failed. */
43
+ /**
44
+ * What a vote failed with: a provider's kind of failure, the limit that stopped it (`token-cap` or
45
+ * `review-deadline`), `unusable-reply` for a reply the panel could not read as a vote, or `unknown` for
46
+ * anything else thrown.
47
+ * The kinds a gating profile's `--allow-incomplete` lifts are `network`, `timeout` and an `http` failure of
48
+ * status 408, 409, 429 or 5xx.
49
+ */
50
+ export type VoteFailureKind = 'http' | 'network' | 'process' | 'timeout' | 'aborted' | 'refusal' | 'truncated' | 'invalid-response' | 'unsupported' | 'too-large' | 'token-cap' | 'review-deadline' | 'unusable-reply' | 'unknown';
51
+ /** The facts of a failed vote the code read, never a word a server or a model wrote. */
52
+ export interface VoteFailure {
53
+ kind: VoteFailureKind;
54
+ /** An `http` failure's HTTP status, an integer from 100 to 599; absent for every other kind, and for an `http` failure that states none. */
55
+ status?: number;
56
+ }
57
+ /**
58
+ * One lens's vote, or the error if that call failed. A failed vote also records its `failure`: what it
59
+ * failed with, which the CLI's `--allow-incomplete` reads to lift only a vote that failed in passing.
60
+ */
44
61
  export interface LensVote {
45
62
  /** The id of the lens the vote was cast from. */
46
63
  angle: string;
47
64
  vote: Vote | null;
48
65
  error: string | null;
66
+ /** What a failed vote failed with; `null` for a vote that was cast. */
67
+ failure: VoteFailure | null;
49
68
  }
50
69
  /** Instruction templates, one per stage. `{{name}}` placeholders are filled by renderTemplate. */
51
70
  export interface Prompts {
@@ -96,15 +115,30 @@ export interface Verdict extends Finding {
96
115
  */
97
116
  export type VerdictStatus = 'kept' | 'discarded' | 'unreviewed';
98
117
  /**
99
- * Why part of a review is missing, as an `IncompleteEntry` records it. `request-too-large`: a
100
- * provider refused a request that may not fit its model's context, so it was not sent.
118
+ * Why part of a review is missing, as an `IncompleteEntry` records it. `research-failed`: an
119
+ * advisory profile's research call failed after its retries, or its reply was no findings
120
+ * envelope, so the profile reviewed nothing; a gating profile's ends the review instead.
121
+ * `request-too-large`: a provider refused a request that may not fit its model's context, so it was
122
+ * not sent. `binary` and `submodule`: the diff carries no content for a file, shown only as binary
123
+ * or as a submodule's commit; `secret`: no model was sent a file, held back because its name is a
124
+ * secret's or it holds a credential quorum recognizes; `meta.leftOut` lists the files. `too-large`: a
125
+ * hunk of a file, or a section with no hunk, fits in no research part of the profile's model's window,
126
+ * so no part holds it and no model read it; one entry per profile counts them, and
127
+ * `meta.profiles.<id>.coverage` lists their ranges. `token-cap`: the review's token cap stopped part of the profile's work, its research (some
128
+ * of its parts, for a large change) or some of its votes, which were not sent; `review-deadline`: the
129
+ * review reached its deadline, which stopped part of the profile's work, its research (some of its
130
+ * parts) or some of its votes, in flight or not yet sent; one entry per limit and profile counts them.
131
+ * For a large change researched in parts, `research-failed` and `request-too-large` count the parts that
132
+ * failed or were refused, and each of the other reasons its parts' share.
101
133
  */
102
- export type IncompleteReason = 'research-unusable' | 'findings-capped' | 'finding-unreadable' | 'vote-failed' | 'request-too-large';
134
+ export type IncompleteReason = 'research-unusable' | 'research-failed' | 'findings-capped' | 'finding-unreadable' | 'vote-failed' | 'request-too-large' | 'too-large' | 'token-cap' | 'review-deadline' | 'binary' | 'submodule' | 'secret';
103
135
  /**
104
- * Work the run could not review: a research reply with findings but none usable, findings beyond
105
- * the cap, a finding the harness could not read, a kept finding whose failed votes could have
106
- * raised it to a higher level, or a request its provider refused as too large to send. It is
107
- * reported and counted, never dropped silently (ADR-0012).
136
+ * Work the run could not review: a research reply with findings but none usable, an advisory
137
+ * profile's research that failed (`research-failed`), findings beyond the cap, a finding the
138
+ * harness could not read, a kept finding whose failed votes could have raised it to a higher
139
+ * level, a request its provider refused as too large to send, work the review's token cap or deadline
140
+ * stopped, a file whose change the diff does not carry, binary or a submodule's commit, or a file held back
141
+ * as a secret, which no model was sent. It is reported and counted, never dropped silently (ADR-0012).
108
142
  */
109
143
  export interface IncompleteEntry {
110
144
  /** The id of the profile whose run has the gap. */
@@ -114,17 +148,94 @@ export interface IncompleteEntry {
114
148
  file?: string;
115
149
  detail: string;
116
150
  }
117
- /** What an advisory flag points at. */
118
- export type FlagCode = 'hidden-characters' | 'ai-addressed-text';
119
151
  /**
120
- * An advisory signal the harness read from the diff by code, before any model saw it: it tells a
121
- * human where to look, and never changes a verdict, a confidence or an exit code.
152
+ * Why a file is in `meta.leftOut`: an `exclude` pattern matches it, its change reaches the models only as
153
+ * binary or as a submodule's commit, a path review skipped it (`skipped`), or it was held back as a secret
154
+ * (`secret`, or `deleted-secret` when the change deletes a file named as one whole): a skipped or held file
155
+ * has its `rule`.
156
+ */
157
+ export type LeftOutReason = 'excluded' | 'binary' | 'submodule' | 'skipped' | 'secret' | 'deleted-secret';
158
+ /**
159
+ * Why a path review skips a file: `vendored`, `lockfile`, `minified` and `binary` only while the default
160
+ * skips are on, `secret` (a file named as a secret, or whose text holds a credential), `submodule` (a
161
+ * gitlink) and `lfs` (a Git LFS pointer) always, a secret unless the operator sends it. A skip is no gap:
162
+ * the file is listed with its rule, and `--no-default-skips` reviews the first four.
163
+ */
164
+ export type SkipRule = 'vendored' | 'lockfile' | 'minified' | 'secret' | 'binary' | 'submodule' | 'lfs';
165
+ /**
166
+ * The kinds of credential the content check reads, one per provider and `private-key`: the rules of
167
+ * gitleaks 8.30.1 for AWS, GitHub, Slack, Google, Stripe, Anthropic and OpenAI, and the private-key
168
+ * markers of pre-commit-hooks v5.0.0, each followed by a key's body.
169
+ */
170
+ export type CredentialKind = 'private-key' | 'aws-key' | 'github-token' | 'slack-token' | 'google-key' | 'stripe-key' | 'anthropic-key' | 'openai-key';
171
+ /** Why a file is held back from every review: its name is a secret's (`name`), or it holds a credential of this kind. */
172
+ export type SecretRule = 'name' | CredentialKind;
173
+ /**
174
+ * A file the review left out: one an `exclude` pattern matches, which is no gap; one a path review
175
+ * skipped, which is no gap either, and whose `rule` says which rule did; one whose change the diff
176
+ * does not carry, `binary` or `submodule`, which is a gap of every profile; or one held back as a secret,
177
+ * which no model was sent: `secret` is a gap of every profile, `deleted-secret` (the change deletes a file
178
+ * named as a secret whole, so it adds no code a review would read) is none, and the `rule` of either says
179
+ * whether its name or a credential in it held it. `rule` is there exactly for a skipped or a held file. A
180
+ * reader takes a reason or a rule it does not know as a file left out, never as an error.
181
+ */
182
+ export type LeftOutFile = {
183
+ /** The diff's own path, decoded; '' for a part of the diff that no `diff --git` header names. */
184
+ file: string;
185
+ reason: 'excluded' | 'binary' | 'submodule';
186
+ } | {
187
+ /** The path as the source named it: a path review's, decoded as the diff would name it. */
188
+ file: string;
189
+ reason: 'skipped';
190
+ rule: SkipRule;
191
+ } | {
192
+ /** The diff's own path, decoded, by which no model was sent the file; '' for the text no `diff --git` header names. */
193
+ file: string;
194
+ reason: 'secret' | 'deleted-secret';
195
+ /** What held it: `name` when its name is a secret's, else the kind of credential its text holds. */
196
+ rule: SecretRule;
197
+ };
198
+ /**
199
+ * Why part of a file was not reviewed, as `CoverageEntry` records it: a `LeftOutReason`'s `binary`,
200
+ * `submodule`, `secret` or `deleted-secret`, `too-large` for a hunk, or a section with no hunk, that fits in
201
+ * no research part of its model's window, or the `IncompleteReason` of the research part that held it and
202
+ * did not read it: `request-too-large`, `token-cap`, `review-deadline` or `research-failed`.
203
+ */
204
+ export type CoverageReason = 'binary' | 'submodule' | 'secret' | 'deleted-secret' | 'too-large' | 'request-too-large' | 'token-cap' | 'review-deadline' | 'research-failed';
205
+ /**
206
+ * How much of a file a profile's research reviewed: `reviewed` when every part that holds it was
207
+ * read, `partial` when some was not, `unreviewed` when none was, and `excluded` when an `exclude`
208
+ * pattern keeps it out of every request.
209
+ */
210
+ export type CoverageStatus = 'reviewed' | 'partial' | 'unreviewed' | 'excluded';
211
+ /** A run of new-file lines a profile's research did not review, both ends included, and why. */
212
+ export interface LeftRange {
213
+ start: number;
214
+ end: number;
215
+ reason: CoverageReason;
216
+ }
217
+ /** One file of the input diff and how much of it a profile's research reviewed. */
218
+ export interface CoverageEntry {
219
+ /** The diff's own path, decoded; '' for a part of the diff that no `diff --git` header names. */
220
+ file: string;
221
+ status: CoverageStatus;
222
+ /** Why the file is unreviewed; absent for any other status. */
223
+ reason?: CoverageReason;
224
+ /** The ranges a partial file left unreviewed, in the diff's order; absent for any other status. */
225
+ left?: LeftRange[];
226
+ }
227
+ /** What an advisory flag points at: hidden characters, text addressed to an AI reviewer, or a file held back or skipped as a secret, by its name or a credential it holds. */
228
+ export type FlagCode = 'hidden-characters' | 'ai-addressed-text' | 'secret-file';
229
+ /**
230
+ * An advisory signal the harness read by code, before any model saw it, from the diff or from the files
231
+ * the input's source left out: it tells a human where to look, and never changes a verdict, a confidence
232
+ * or an exit code.
122
233
  */
123
234
  export interface Flag {
124
235
  code: FlagCode;
125
- /** The diff's own path for the file; absent for a diff without per-file headers. */
236
+ /** The diff's own path for the file, or the path of a file held back or skipped as a secret; absent for a diff without per-file headers, and for the text no header names. */
126
237
  file?: string;
127
- /** The first added line, in the new file, the flag is about; absent when it is about the file name. */
238
+ /** The first added line, in the new file, the flag is about; absent when it is about the file name, and for a `secret-file` flag. */
128
239
  line?: number;
129
240
  /** What was found, in words the code wrote: code points or the names of patterns, never text of the diff. */
130
241
  detail: string;
@@ -148,7 +259,40 @@ export interface ProfileMeta {
148
259
  gating: boolean;
149
260
  /** How many findings it dropped for citing code outside the diff. */
150
261
  invalidFindings: number;
262
+ /**
263
+ * Every file of the input diff once, in its order, with how much of it this profile's research
264
+ * reviewed: `reviewed` when a research request that carried all of the file's text was answered with a
265
+ * valid envelope, whatever it found; the other statuses, and the ranges a `partial` file left, say what
266
+ * was not. Each profile has its own, since each has its own research model.
267
+ */
268
+ coverage: CoverageEntry[];
151
269
  }
270
+ /**
271
+ * Where a review's diff came from, as `meta.source` records it: `diff` for a diff file or standard input,
272
+ * `range` for the commits `base...head` (`mergeBase` the commit the diff starts from), `local` and `staged`
273
+ * for the local changes (`head` null before a first commit), and `paths` for the files under `paths` at
274
+ * `commit`, with `skips` whether the default skips applied. Every id is a full commit id of the repository's
275
+ * `objectFormat`. It never holds a revision as written, a local file name or a git version.
276
+ */
277
+ export type ReviewSource = {
278
+ kind: 'diff';
279
+ } | {
280
+ kind: 'range';
281
+ base: string;
282
+ mergeBase: string;
283
+ head: string;
284
+ objectFormat: ObjectFormat;
285
+ } | {
286
+ kind: 'local' | 'staged';
287
+ head: string | null;
288
+ objectFormat: ObjectFormat;
289
+ } | {
290
+ kind: 'paths';
291
+ commit: string;
292
+ paths: string[];
293
+ skips: boolean;
294
+ objectFormat: ObjectFormat;
295
+ };
152
296
  /** What a review records about itself, besides its verdicts. */
153
297
  export interface QuorumMeta {
154
298
  /** The version of quorum that ran the review, read from package.json. */
@@ -157,13 +301,17 @@ export interface QuorumMeta {
157
301
  startedAt: string;
158
302
  /** How long the review took, in whole milliseconds. */
159
303
  durationMs: number;
304
+ /** Where the diff came from: `{ kind: 'diff' }` when the input names no source. It never holds a revision as written, a local file name or a git version. */
305
+ source: ReviewSource;
160
306
  /** One entry per profile, keyed by profile id, in the run's profile order. */
161
307
  profiles: Record<string, ProfileMeta>;
162
308
  /** The usage summed over the calls that reported valid counts; absent when none did. */
163
309
  usage?: Usage;
164
310
  /** Gaps that are not findings. An entry here, or an unreviewed finding, makes the review incomplete. */
165
311
  incomplete: IncompleteEntry[];
166
- /** Advisory signals the harness read from the diff: where a human should look. They change no verdict and no exit code. */
312
+ /** The files the review left out, the input's own first, then the diff's, once per file, reason and rule. Each, but an excluded, a skipped or a `deleted-secret` one, is also a gap of every profile: a file held back as a secret is one no model was sent. */
313
+ leftOut: LeftOutFile[];
314
+ /** Advisory signals the harness read from the diff, and from the files left out as secrets, held back or skipped by a source, which come first: where a human should look. They change no verdict and no exit code. */
167
315
  flags: Flag[];
168
316
  }
169
317
  /** Final review output. */
@@ -182,20 +330,110 @@ export interface QuorumOptions {
182
330
  readonly concurrency?: number;
183
331
  /** How many findings of a research reply each profile sends to the panel; `DEFAULT_MAX_FINDINGS` when unset. */
184
332
  readonly maxFindings?: number;
333
+ /** Path patterns of the files left out of every request; none when unset. */
334
+ readonly exclude?: readonly string[];
335
+ /**
336
+ * The most tokens, input and output, one review may spend: a whole number from 1 to `Number.MAX_SAFE_INTEGER`,
337
+ * 2000000 when unset. Each attempt reserves its worst case before it is sent and settles at what it spent; what
338
+ * the cap stops is a `token-cap` gap of its profile.
339
+ */
340
+ readonly maxReviewTokens?: number;
341
+ /**
342
+ * How long one review runs, in milliseconds: a whole number from 1000 to 86400000, 1800000 (30 minutes) when
343
+ * unset. At it every call in flight and every wait is stopped at once and no new call starts, and what was not
344
+ * done is a `review-deadline` gap of its profile: the review resolves with its findings so far. It is no abort.
345
+ */
346
+ readonly reviewTimeoutMs?: number;
347
+ /**
348
+ * The most tokens of diff text, counted as the size guard counts, one research request of a large change
349
+ * holds: a whole number from 1024 to `Number.MAX_SAFE_INTEGER`, 32768 when unset. A diff over it, or over
350
+ * what the research model's window leaves, is researched in parts of at most this size; a provider that
351
+ * states no room is sent the whole diff in one request.
352
+ */
353
+ readonly partTokens?: number;
354
+ }
355
+ /**
356
+ * What one review takes: the diff, and optionally where it came from, the files its source left out before it
357
+ * made the diff, and the files to send though they are held back as secrets.
358
+ */
359
+ export interface ReviewInput {
360
+ readonly diff: string;
361
+ /** Where the diff came from, checked and recorded in `meta.source` as given; `{ kind: 'diff' }` when unset. */
362
+ readonly source?: ReviewSource;
363
+ /**
364
+ * The files the source left out before it made the diff, listed in `meta.leftOut` and in the `left-out`
365
+ * event ahead of the diff's own. A `binary`, `submodule` or `secret` one is a gap of every profile, as the
366
+ * diff's are; an `excluded`, a `skipped` or a `deleted-secret` one is no gap. A `skipped` one of the rule
367
+ * `secret`, a `secret` and a `deleted-secret` one each raise a `secret-file` flag.
368
+ */
369
+ readonly leftOut?: readonly LeftOutFile[];
370
+ /**
371
+ * The files of the diff to send the models though they are held back as secrets, each the path as the diff
372
+ * writes it, the one `meta.leftOut` lists, matched exactly: `./.env` names no file `.env`. A file named here
373
+ * is never held, so it is neither listed nor flagged as a secret; the text no header names, the file of the
374
+ * empty name, can never be named. None when unset.
375
+ */
376
+ readonly send?: readonly string[];
377
+ }
378
+ /**
379
+ * What one profile's review may cost, in tokens, as `Quorum.estimate` counts it before any call. Each figure is
380
+ * what the review's token ledger reserves for a call, not what the call spends.
381
+ */
382
+ export interface ProfileEstimate {
383
+ /** What the ledger reserves for each research request of the profile, in order: one for a diff researched whole, else one per part that holds more than white space. Empty when research makes no call. */
384
+ parts: number[];
385
+ /** The most votes the panel casts: `maxFindings` findings, each voted by every lens of the profile. 0 when research makes no call. */
386
+ votes: number;
387
+ /** What the ledger reserves at most for one vote of each lens, keyed by lens id. Empty when research makes no call. */
388
+ vote: Record<string, number>;
389
+ /** The research parts alone, each counted at a third of its reservation, rounded up: code takes about that many tokens, not one per byte. The votes are not in it, since how many findings research reports is not known before it runs. */
390
+ expected: number;
391
+ /** The most the profile may reserve in all: the research parts in full, and `maxFindings` votes of every lens at its bound. */
392
+ worst: number;
393
+ }
394
+ /**
395
+ * What a review of a diff may cost, as `Quorum.estimate` states it: no call is made. `profiles` is keyed by
396
+ * profile id, in the run's order; `expected` and `worst` sum the profiles'. `inFlight` is what the calls that
397
+ * run at once reserve, the `concurrency` largest bounds among every research part and vote, and `fits` is
398
+ * whether `expected` and `inFlight` together are within `maxReviewTokens`. It is an estimate: the review's
399
+ * ledger still holds the cap, whatever `fits` says.
400
+ */
401
+ export interface Estimate {
402
+ profiles: Record<string, ProfileEstimate>;
403
+ expected: number;
404
+ worst: number;
405
+ inFlight: number;
406
+ /** The token cap of every review of the quorum, as `createQuorum` was given or defaulted it. */
407
+ maxReviewTokens: number;
408
+ /** The deadline of every review of the quorum, in milliseconds. */
409
+ reviewTimeoutMs: number;
410
+ fits: boolean;
185
411
  }
186
412
  /** A quorum built by createQuorum: its profiles compiled once, ready to review any number of diffs. */
187
413
  export interface Quorum {
188
414
  /**
189
- * Review one diff with every profile of the quorum. Once `signal` aborts, the review stops and
190
- * rejects with the signal's reason; an aborted review never resolves. The review is over once it
191
- * has sent `run:end`: an abort from that event's handler, or later, has no effect, and the review
192
- * resolves with its result.
415
+ * Review one diff with every profile of the quorum, recording its `source` in `meta.source` and
416
+ * listing the files its source left out (`leftOut`) before the diff's own. Once `signal` aborts, the
417
+ * review stops and rejects with the signal's reason; an aborted review never resolves. The review is
418
+ * over once it has sent `run:end`: an abort from that event's handler, or later, has no effect, and the
419
+ * review resolves with its result.
193
420
  */
194
- readonly review: (input: {
195
- readonly diff: string;
196
- }, options?: {
421
+ readonly review: (input: ReviewInput, options?: {
197
422
  readonly signal?: AbortSignal;
198
423
  }) => Promise<QuorumResult>;
424
+ /**
425
+ * What a review of `input.diff` may cost, before any call: per profile, what the token ledger reserves for each
426
+ * research part, and a bound for every vote. It makes no call and reads no file. The research parts are counted
427
+ * at a third of their reservation in `expected`, code taking about three bytes a token, and the votes in the
428
+ * worst case only; `fits` says whether `expected` and what the calls in flight reserve are within
429
+ * `maxReviewTokens`. It is an estimate, not a promise: a review still reserves each call against the cap.
430
+ * A file held back as a secret costs nothing, and one `input.send` names is counted, as `review` sends it.
431
+ * Throws a `ConfigError` for an input `review` would refuse.
432
+ */
433
+ readonly estimate: (input: {
434
+ readonly diff: string;
435
+ readonly send?: readonly string[];
436
+ }) => Estimate;
199
437
  /** Settings that cannot take full effect, such as a policy level that never applies; each starts at its profile id. */
200
438
  readonly warnings: readonly string[];
201
439
  }
@@ -211,7 +449,12 @@ export type QuorumEvent = {
211
449
  profiles: string[];
212
450
  providers: Record<string, ProfileProviders>;
213
451
  }
214
- /** An advisory flag read from the diff, sent before any stage starts. */
452
+ /** The files the review leaves out, as `meta.leftOut` holds them, the input's first: sent once right after `run:start` when there is one. */
453
+ | {
454
+ type: 'left-out';
455
+ files: LeftOutFile[];
456
+ }
457
+ /** An advisory flag, read from the diff or from the files left out as secrets, sent before any stage starts. */
215
458
  | {
216
459
  type: 'flag';
217
460
  flag: Flag;
@@ -230,7 +473,14 @@ export type QuorumEvent = {
230
473
  durationMs: number;
231
474
  count: number;
232
475
  }
233
- /** One per provider call, failed ones included: its latency inside its slot and its usage, when valid. */
476
+ /**
477
+ * One per provider call, failed ones included, sent when the call ends. The call runs its
478
+ * attempts inside its slot, retried as the retry policy decides, so `durationMs` runs from its
479
+ * first attempt to its end, the waits between attempts included; `attempts` is their number,
480
+ * only when the call made more than one; `usage` is summed over the attempts that reported
481
+ * valid counts; `spent` is the tokens the review's cap counted for the call: each attempt's
482
+ * reported usage, nothing for one the server refused before any work, else its reservation.
483
+ */
234
484
  | {
235
485
  type: 'call';
236
486
  profile: string;
@@ -239,7 +489,9 @@ export type QuorumEvent = {
239
489
  provider: ProviderRef;
240
490
  durationMs: number;
241
491
  ok: boolean;
492
+ attempts?: number;
242
493
  usage?: Usage;
494
+ spent: number;
243
495
  }
244
496
  /** A finding was dropped for citing code outside the diff, with the reason. */
245
497
  | {
@@ -252,7 +504,7 @@ export type QuorumEvent = {
252
504
  type: 'incomplete';
253
505
  entry: IncompleteEntry;
254
506
  }
255
- /** One lens voted on one finding; `keep` is null, with the error, when the vote failed. */
507
+ /** One lens voted on one finding; `keep` is null, with the error and the failure's kind and status, when the vote failed. */
256
508
  | {
257
509
  type: 'vote';
258
510
  profile: string;
@@ -260,6 +512,7 @@ export type QuorumEvent = {
260
512
  lens: string;
261
513
  keep: boolean | null;
262
514
  error?: string;
515
+ failure?: VoteFailure;
263
516
  }
264
517
  /** The panel decided one finding: its vote split, the confidence it earned and where it lands. */
265
518
  | {
@@ -295,3 +548,5 @@ export interface Usage {
295
548
  outputTokens: number;
296
549
  costUsd?: number;
297
550
  }
551
+ /** The hash a repository names its objects with: `sha1` is git's default, `sha256` the repositories made with `--object-format=sha256`. A full id is 40 hexadecimal characters for the first and 64 for the second. */
552
+ export type ObjectFormat = 'sha1' | 'sha256';
@@ -1,6 +1,12 @@
1
1
  import type { Finding, FindingDetails } from './types.ts';
2
2
  /** A finding as the harness verified it, before the research stage names it and tags its profile. */
3
3
  export type VerifiedFinding = Omit<Finding, 'id' | 'profile'>;
4
+ /** The most characters of a finding's summary, which the finder writes, as the harness caps it. */
5
+ export declare const MAX_SUMMARY = 500;
6
+ /** The most characters of a finding's category, which the finder writes, as the harness caps it. */
7
+ export declare const MAX_CATEGORY = 80;
8
+ /** The most characters of the evidence a finding carries, read from the diff and capped. */
9
+ export declare const MAX_EVIDENCE = 2000;
4
10
  /**
5
11
  * Check what the finder reported against the diff itself. A finding must cite a file of the diff
6
12
  * and a line inside one of its hunks, otherwise it is dropped with a reason. What reaches the
@@ -1,11 +1,14 @@
1
1
  import { locate } from "./diff.js";
2
2
  import { stripHidden } from "./sanitize.js";
3
- const MAX_SUMMARY = 500;
4
- const MAX_CATEGORY = 80;
3
+ /** The most characters of a finding's summary, which the finder writes, as the harness caps it. */
4
+ export const MAX_SUMMARY = 500;
5
+ /** The most characters of a finding's category, which the finder writes, as the harness caps it. */
6
+ export const MAX_CATEGORY = 80;
5
7
  const MAX_FILE = 260;
6
8
  /** The file name echoed in an `invalid` reason only has to identify the finding, so it is shorter than a stored one. */
7
9
  const MAX_REPORTED_FILE = 80;
8
- const MAX_EVIDENCE = 2000;
10
+ /** The most characters of the evidence a finding carries, read from the diff and capped. */
11
+ export const MAX_EVIDENCE = 2000;
9
12
  /** A quote longer than this once whitespace is collapsed is no usable citation of a few diff lines: it never matches. */
10
13
  const MAX_QUOTE = 2000;
11
14
  /**