@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
@@ -120,19 +120,25 @@ export type VerdictStatus = 'kept' | 'discarded' | 'unreviewed';
120
120
  * envelope, so the profile reviewed nothing; a gating profile's ends the review instead.
121
121
  * `request-too-large`: a provider refused a request that may not fit its model's context, so it was
122
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; `meta.leftOut` lists the files. `token-cap`: the review's token cap
124
- * stopped part of the profile's work, its research request or some of its votes, which were not sent;
125
- * `review-deadline`: the review reached its deadline, which stopped part of the profile's work, its
126
- * research request or some of its votes, in flight or not yet sent; one entry per limit and profile counts them.
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.
127
133
  */
128
- export type IncompleteReason = 'research-unusable' | 'research-failed' | 'findings-capped' | 'finding-unreadable' | 'vote-failed' | 'request-too-large' | 'token-cap' | 'review-deadline' | 'binary' | 'submodule';
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';
129
135
  /**
130
136
  * Work the run could not review: a research reply with findings but none usable, an advisory
131
137
  * profile's research that failed (`research-failed`), findings beyond the cap, a finding the
132
138
  * harness could not read, a kept finding whose failed votes could have raised it to a higher
133
139
  * level, a request its provider refused as too large to send, work the review's token cap or deadline
134
- * stopped, or a file whose change the diff does not carry, binary or a submodule's commit. It is reported and
135
- * counted, never dropped silently (ADR-0012).
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).
136
142
  */
137
143
  export interface IncompleteEntry {
138
144
  /** The id of the profile whose run has the gap. */
@@ -142,25 +148,94 @@ export interface IncompleteEntry {
142
148
  file?: string;
143
149
  detail: string;
144
150
  }
145
- /** Why a file is in `meta.leftOut`: an `exclude` pattern matches it, or its change reaches the models only as binary, or as a submodule's commit. */
146
- export type LeftOutReason = 'excluded' | 'binary' | 'submodule';
147
- /** A file the review left out: one an `exclude` pattern matches, which is no gap, or one whose change the diff does not carry, which is a gap of every profile. */
148
- export interface LeftOutFile {
151
+ /**
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 = {
149
183
  /** The diff's own path, decoded; '' for a part of the diff that no `diff --git` header names. */
150
184
  file: string;
151
- reason: LeftOutReason;
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[];
152
226
  }
153
- /** What an advisory flag points at. */
154
- export type FlagCode = 'hidden-characters' | 'ai-addressed-text';
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';
155
229
  /**
156
- * An advisory signal the harness read from the diff by code, before any model saw it: it tells a
157
- * human where to look, and never changes a verdict, a confidence or an exit code.
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.
158
233
  */
159
234
  export interface Flag {
160
235
  code: FlagCode;
161
- /** 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. */
162
237
  file?: string;
163
- /** 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. */
164
239
  line?: number;
165
240
  /** What was found, in words the code wrote: code points or the names of patterns, never text of the diff. */
166
241
  detail: string;
@@ -184,7 +259,40 @@ export interface ProfileMeta {
184
259
  gating: boolean;
185
260
  /** How many findings it dropped for citing code outside the diff. */
186
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[];
187
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
+ };
188
296
  /** What a review records about itself, besides its verdicts. */
189
297
  export interface QuorumMeta {
190
298
  /** The version of quorum that ran the review, read from package.json. */
@@ -193,15 +301,17 @@ export interface QuorumMeta {
193
301
  startedAt: string;
194
302
  /** How long the review took, in whole milliseconds. */
195
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;
196
306
  /** One entry per profile, keyed by profile id, in the run's profile order. */
197
307
  profiles: Record<string, ProfileMeta>;
198
308
  /** The usage summed over the calls that reported valid counts; absent when none did. */
199
309
  usage?: Usage;
200
310
  /** Gaps that are not findings. An entry here, or an unreviewed finding, makes the review incomplete. */
201
311
  incomplete: IncompleteEntry[];
202
- /** The files the review left out, in the diff's order, once per file and reason. Each, but an excluded one, is also a gap of every profile. */
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. */
203
313
  leftOut: LeftOutFile[];
204
- /** Advisory signals the harness read from the diff: where a human should look. They change no verdict and no exit code. */
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. */
205
315
  flags: Flag[];
206
316
  }
207
317
  /** Final review output. */
@@ -234,20 +344,96 @@ export interface QuorumOptions {
234
344
  * done is a `review-deadline` gap of its profile: the review resolves with its findings so far. It is no abort.
235
345
  */
236
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;
237
411
  }
238
412
  /** A quorum built by createQuorum: its profiles compiled once, ready to review any number of diffs. */
239
413
  export interface Quorum {
240
414
  /**
241
- * Review one diff with every profile of the quorum. Once `signal` aborts, the review stops and
242
- * rejects with the signal's reason; an aborted review never resolves. The review is over once it
243
- * has sent `run:end`: an abort from that event's handler, or later, has no effect, and the review
244
- * 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.
245
420
  */
246
- readonly review: (input: {
247
- readonly diff: string;
248
- }, options?: {
421
+ readonly review: (input: ReviewInput, options?: {
249
422
  readonly signal?: AbortSignal;
250
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;
251
437
  /** Settings that cannot take full effect, such as a policy level that never applies; each starts at its profile id. */
252
438
  readonly warnings: readonly string[];
253
439
  }
@@ -263,12 +449,12 @@ export type QuorumEvent = {
263
449
  profiles: string[];
264
450
  providers: Record<string, ProfileProviders>;
265
451
  }
266
- /** The files the review leaves out, as `meta.leftOut` holds them: sent once right after `run:start` when there is one. */
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. */
267
453
  | {
268
454
  type: 'left-out';
269
455
  files: LeftOutFile[];
270
456
  }
271
- /** An advisory flag read from the diff, sent before any stage starts. */
457
+ /** An advisory flag, read from the diff or from the files left out as secrets, sent before any stage starts. */
272
458
  | {
273
459
  type: 'flag';
274
460
  flag: Flag;
@@ -362,3 +548,5 @@ export interface Usage {
362
548
  outputTokens: number;
363
549
  costUsd?: number;
364
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
  /**
@@ -0,0 +1,223 @@
1
+ import type { ChildProcess, SpawnOptions } from 'node:child_process';
2
+ import type { Clock } from '../core/clock.ts';
3
+ import { QuorumError } from '../core/errors.ts';
4
+ import type { ObjectFormat } from '../core/types.ts';
5
+ /**
6
+ * The one place quorum runs git: a closed set of typed operations (`GitOperation`), each built into one
7
+ * argument vector by `gitArgs` and spawned by `runGit` with no shell, and `openRepository`, which checks a
8
+ * working directory and hands back the operations the sources call. Quorum reviews repositories it was
9
+ * handed, so nothing a repository holds may run a program or reshape the bytes git prints.
10
+ *
11
+ * @see ../../docs/95-reference/40-architecture.md for where it sits in the layers.
12
+ */
13
+ /** The oldest git quorum runs: `--attr-source` came with 2.41, and every other option it pins is older. */
14
+ export declare const GIT_FLOOR: Readonly<{
15
+ major: 2;
16
+ minor: 41;
17
+ }>;
18
+ /** The deadline of one git call, on the injected clock. */
19
+ export declare const GIT_TIMEOUT_MS = 120000;
20
+ /** The most a diff or a listing may print, which `core/diff.ts`'s `MAX_DIFF_BYTES` is: the layer imports no `diff.ts`, so a spec holds the two equal. */
21
+ export declare const MAX_GIT_OUTPUT_BYTES: number;
22
+ /** The most of a child's stderr that is kept; the rest is read and dropped. */
23
+ export declare const MAX_GIT_STDERR_BYTES = 65536;
24
+ /** The most `--version`, `rev-parse`, `merge-base`, `hash-object` and `config` print. */
25
+ export declare const MAX_GIT_SMALL_OUTPUT_BYTES = 65536;
26
+ /** The characters of git's stderr a `GitError` quotes. */
27
+ export declare const STDERR_EXCERPT = 500;
28
+ /** Before every command: no pager, no lock and no replace ref, literal pathspecs, and the config keys that would run a program or reshape a path. */
29
+ export declare const GLOBAL_PINS: readonly string[];
30
+ /** After `diff`: the options that give one form of diff whatever the repository's `diff.*` and `color.*` config says. */
31
+ export declare const DIFF_PINS: readonly string[];
32
+ /** The variables of the parent's environment a child gets, when the parent holds them as its own strings. Every other variable is dropped. */
33
+ export declare const ENVIRONMENT_ALLOWLIST: readonly string[];
34
+ /** A git call that failed: it could not start, passed its deadline, was stopped by a signal, exited with a failure, or printed what quorum cannot read. */
35
+ export declare class GitError extends QuorumError {
36
+ /** The git subcommand the call ran: `diff`, `rev-parse`, `ls-tree`, and `version` for `--version`. */
37
+ readonly operation: string;
38
+ /** The exit code, or null when there was none: the child did not start or did not finish. */
39
+ readonly exitCode: number | null;
40
+ constructor(message: string, operation: string, exitCode?: number | null);
41
+ }
42
+ /** `spawn`, as the runner calls it, so a spec injects its own. */
43
+ export type SpawnGit = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
44
+ /** What every git call of a review runs with. */
45
+ export interface GitContext {
46
+ /** The absolute path of the git executable. */
47
+ readonly git: string;
48
+ /** The directory the child starts in: the user's working directory. */
49
+ readonly cwd: string;
50
+ /** The parent's environment; `gitEnvironment` picks what a child gets of it. */
51
+ readonly env: Readonly<Record<string, string | undefined>>;
52
+ /** The flag a `ConfigError` of this run names as its issue path: `--range`, `--local`, `--staged` or `--path`. */
53
+ readonly flag: string;
54
+ readonly signal?: AbortSignal;
55
+ readonly spawn?: SpawnGit;
56
+ /** The clock the deadline runs on; the system's when unset. */
57
+ readonly clock?: Clock;
58
+ /** The deadline of each call; `GIT_TIMEOUT_MS` when unset. */
59
+ readonly timeoutMs?: number;
60
+ }
61
+ /**
62
+ * What a child gets of the parent's environment: each name of `ENVIRONMENT_ALLOWLIST` the parent holds as its
63
+ * own string, then quorum's own seven variables, which win. Nothing else passes: not `GIT_DIFF_OPTS` or
64
+ * `GIT_EXTERNAL_DIFF`, not `GIT_CONFIG_PARAMETERS` or `GIT_CONFIG_COUNT`, not a pager, not a key.
65
+ */
66
+ export declare function gitEnvironment(env: GitContext['env']): Record<string, string>;
67
+ /** The calls quorum makes: the ones that name the repository, then the reads of one. `top` is the top level `openRepository` found. */
68
+ export type GitOperation = {
69
+ readonly op: 'version';
70
+ } | {
71
+ readonly op: 'toplevel';
72
+ } | {
73
+ readonly op: 'prefix';
74
+ } | {
75
+ readonly op: 'git-dir';
76
+ } | {
77
+ readonly op: 'top-git-dir';
78
+ readonly top: string;
79
+ } | {
80
+ readonly op: 'object-format';
81
+ readonly top: string;
82
+ } | {
83
+ readonly op: 'resolve';
84
+ readonly top: string;
85
+ readonly revision: string;
86
+ } | {
87
+ readonly op: 'merge-base';
88
+ readonly top: string;
89
+ readonly first: string;
90
+ readonly second: string;
91
+ } | {
92
+ readonly op: 'empty-tree';
93
+ readonly top: string;
94
+ } | {
95
+ readonly op: 'diff-commits';
96
+ readonly top: string;
97
+ readonly from: string;
98
+ readonly to: string;
99
+ readonly attributes: string;
100
+ } | {
101
+ readonly op: 'diff-index';
102
+ readonly top: string;
103
+ readonly from: string;
104
+ readonly attributes: string;
105
+ } | {
106
+ readonly op: 'diff-worktree';
107
+ readonly top: string;
108
+ readonly from: string;
109
+ readonly attributes: string;
110
+ } | {
111
+ readonly op: 'filter-config';
112
+ readonly top: string;
113
+ } | {
114
+ readonly op: 'untracked';
115
+ readonly top: string;
116
+ } | {
117
+ readonly op: 'list-tree';
118
+ readonly top: string;
119
+ readonly commit: string;
120
+ } | {
121
+ readonly op: 'read-objects';
122
+ readonly top: string;
123
+ };
124
+ /** An id as it goes into a vector: 40 or 64 lowercase hexadecimal characters, else a `RangeError` that does not repeat it. */
125
+ export declare function checkedId(value: string): string;
126
+ /**
127
+ * The argument vector of `operation`: `GLOBAL_PINS`, then the operation's own words. Every id is checked
128
+ * first, as 40 or 64 lowercase hexadecimal characters, and a revision, the one string a user gives git, as
129
+ * not empty and not an option (it follows `--end-of-options` besides): a `RangeError` otherwise, before any
130
+ * vector is built. Every diff ends with `--`, so no name is read as a revision.
131
+ */
132
+ export declare function gitArgs(operation: GitOperation): string[];
133
+ /** What a git call came to, whatever its exit code. */
134
+ export interface GitRun {
135
+ /** The exit code; -1 when quorum stopped the child, at its stdout cap or at the consumer's word, which `over` says. */
136
+ readonly code: number;
137
+ /** What the child printed, up to the cap: empty when the consumer was handed each chunk. */
138
+ readonly stdout: Uint8Array;
139
+ /** The first 64 KiB of stderr, decoded. */
140
+ readonly stderr: string;
141
+ /** Whether the child was stopped for printing more than was read, so `stdout` is a cut and no answer. */
142
+ readonly over: boolean;
143
+ }
144
+ /** `chunks` as one array of `size` bytes, their total. */
145
+ export declare function joined(chunks: readonly Uint8Array[], size: number): Uint8Array;
146
+ /**
147
+ * Runs one operation: spawns `context.git` with `gitArgs`'s vector and `gitEnvironment`'s environment, with
148
+ * no shell, from `context.cwd`, its stdin ignored unless the operation takes input (`empty-tree` and
149
+ * `read-objects`, which get `options.input` and an end). It resolves for any exit code, with stdout up to
150
+ * `options.maxStdout` (`MAX_GIT_SMALL_OUTPUT_BYTES` unless a caller says) and the first 64 KiB of stderr; a
151
+ * child that prints more is killed and the run says `over`. With `options.onStdout` each chunk is handed over
152
+ * and not kept, and `false` stops the child, `over` again. It rejects with a `GitError` when git cannot start,
153
+ * passes its deadline (`GIT_TIMEOUT_MS` on the context's clock) or is ended by a signal quorum did not send,
154
+ * and with the signal's reason when `context.signal` aborts. Quorum's own stops, at a cap, a deadline or an
155
+ * abort, are SIGKILL, after which the child's pipes are destroyed so that a helper holding them cannot keep
156
+ * the call open. The timer and the listener are gone on every path.
157
+ *
158
+ * What is pinned, and what the prototype on git 2.50.1 saw without it:
159
+ * - `core.fsmonitor`, `core.hooksPath` and the pager (`--no-pager`, `core.pager`, `GIT_PAGER`): a repository's
160
+ * own config ran its marker programs as fsmonitor, as hooks and, under a pseudo-terminal, as the pager.
161
+ * - `--no-ext-diff`, `--no-textconv` and `core.attributesFile`, with `--attr-source=<commit>` on each diff:
162
+ * `diff.external`, a text converter and a driver's `command` ran, and `.gitattributes` and `info/attributes`
163
+ * named them. Every operation ran nothing but the working-tree diff, whose filters the trust check refuses.
164
+ * - `--no-replace-objects` and `GIT_NO_REPLACE_OBJECTS`: a replace ref swapped a blob for another.
165
+ * - `diff.autoRefreshIndex=false`, `--no-optional-locks` and `GIT_OPTIONAL_LOCKS`: a working-tree diff
166
+ * rewrote `.git/index`, a stat refresh, and quorum never writes to a repository.
167
+ * - The `DIFF_PINS`, `core.quotePath` and `diff.suppressBlankEmpty`: a hostile `diff.algorithm`,
168
+ * `diff.context`, `diff.renames`, `core.abbrev`, `diff.orderFile` and the like changed the bytes of a diff.
169
+ * - `--` after every diff: a tracked file named after a commit id made `git diff <id> <id>` fatal.
170
+ * - `GIT_NO_LAZY_FETCH` and an empty `GIT_ALLOW_PROTOCOL`: a partial clone fetched a missing blob; each alone
171
+ * stops it, and the allowlist holds on every release.
172
+ * - `safe.bareRepository=explicit`: a bare repository committed in the tree was refused from inside it.
173
+ * - The environment allowlist: `GIT_DIFF_OPTS` and `GIT_EXTERNAL_DIFF` of the parent reshaped and ran.
174
+ */
175
+ export declare function runGit(context: GitContext, operation: GitOperation, options?: {
176
+ readonly input?: Uint8Array | string;
177
+ readonly maxStdout?: number;
178
+ readonly onStdout?: (chunk: Uint8Array) => boolean;
179
+ }): Promise<GitRun>;
180
+ /** The `GitError` of an operation that exited with a failure: `git <name> failed (exit <code>)`, then what stderr said. */
181
+ export declare function gitFailure(operation: GitOperation['op'], run: GitRun): GitError;
182
+ /** One config entry of a filter: where git read it from, and its key. */
183
+ export interface FilterKey {
184
+ readonly scope: string;
185
+ readonly key: string;
186
+ }
187
+ /** A repository a source reads, opened by `openRepository`. A diff or a listing over its cap is `undefined`. */
188
+ export interface Repository {
189
+ readonly context: GitContext;
190
+ /** The top level of the work tree, as git prints it. */
191
+ readonly top: string;
192
+ /** The path of the working directory under the top level, as git prints it: empty at the top, else ending with `/`. */
193
+ readonly prefix: string;
194
+ readonly objectFormat: ObjectFormat;
195
+ /** The full id of the commit `revision` names, or undefined for any failure: git's stderr there quotes the revision as typed, so it is never read. */
196
+ readonly resolveCommit: (revision: string) => Promise<string | undefined>;
197
+ /** The merge base of two commits, undefined when they share no history. */
198
+ readonly mergeBase: (first: string, second: string) => Promise<string | undefined>;
199
+ /** The id of the empty tree of the repository's object format, as git prints it and as the format's constant says: any other reply is a `GitError`. */
200
+ readonly emptyTree: () => Promise<string>;
201
+ /** The diff from commit `from` to commit `to`, its attributes read from the commit `attributes`. */
202
+ readonly diffCommits: (from: string, to: string, attributes: string) => Promise<Uint8Array | undefined>;
203
+ /** The diff of the index against commit `from`. */
204
+ readonly diffIndex: (from: string, attributes: string) => Promise<Uint8Array | undefined>;
205
+ /** The diff of the working tree against commit `from`; it runs the filters the repository's config names. */
206
+ readonly diffWorktree: (from: string, attributes: string) => Promise<Uint8Array | undefined>;
207
+ /** Every `filter.<name>.clean`, `.smudge` and `.process` key of the repository's config, with its scope. */
208
+ readonly filterConfig: () => Promise<FilterKey[]>;
209
+ /** The names of the untracked files that are not ignored, as git prints them, each as its bytes. */
210
+ readonly untracked: () => Promise<Uint8Array[] | undefined>;
211
+ }
212
+ /**
213
+ * Opens the repository the working directory is in, or refuses it with a `ConfigError` at `context.flag`.
214
+ * The calls, in order: `--version`, which must read as 2.41 or later; then `toplevel`, `prefix` and `git-dir`
215
+ * in `context.cwd`, which never enters a bare repository nested in the tree (`safe.bareRepository=explicit`
216
+ * refuses it, and so does `toplevel` outside a work tree) and which names `safe.directory` when another user
217
+ * owns the repository (`detected dubious ownership`, the only phrase of git's stderr that is read); then
218
+ * `top-git-dir` and `object-format` with `-C <top>`. A `core.worktree` can name another repository's work
219
+ * tree, which `-C <top>` would then enter and read instead, so the git directory is read from the working
220
+ * directory and again from the top level, and the two must be the same: the later calls never land in
221
+ * another repository. Each path git prints loses only its last line feed.
222
+ */
223
+ export declare function openRepository(context: GitContext): Promise<Repository>;