@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
@@ -2,19 +2,22 @@ import packageJson from '../../package.json' with { type: 'json' };
2
2
  import { systemClock } from "./clock.js";
3
3
  import { createLimiter, DEFAULT_CONCURRENCY } from "./concurrency.js";
4
4
  import { leftOutGaps, reviewScope } from "./coverage.js";
5
- import { splitDiff } from "./diff.js";
5
+ import { diffSections, splitDiff } from "./diff.js";
6
6
  import { ConfigError } from "./errors.js";
7
+ import { estimateReview } from "./estimate.js";
7
8
  import { excludeIssues, excludeMatcher } from "./exclude.js";
8
- import { diffFlags } from "./flags.js";
9
+ import { diffFlags, secretFlags } from "./flags.js";
10
+ import { leftOutIssues, mergeLeftOut, sendIssues, sourceIssues, sourceOf } from "./inputs.js";
9
11
  import { createLedger, DEFAULT_MAX_REVIEW_TOKENS, DEFAULT_REVIEW_TIMEOUT_MS, LimitError, limitGaps, maxReviewTokensProblem } from "./limits.js";
10
12
  import { isRecord } from "./output.js";
13
+ import { coverageOf, DEFAULT_PART_TOKENS, partTokensProblem, tooLargeGap } from "./parts.js";
11
14
  import { MAX_STATED_TIMEOUT_MS, retriesProblem, timeoutProblem } from "./ports.js";
12
15
  import { profileIssues, profileWarnings, thresholdsFor } from "./profile.js";
13
16
  import { renderTemplate } from "./prompts.js";
14
17
  import { addUsage, elapsed, ownData, stage, targetOf } from "./stages/context.js";
15
18
  import { dedup } from "./stages/dedup.js";
16
19
  import { panel } from "./stages/panel.js";
17
- import { DEFAULT_MAX_FINDINGS, research } from "./stages/research.js";
20
+ import { DEFAULT_MAX_FINDINGS, planResearch, research } from "./stages/research.js";
18
21
  const PROVIDER_SHAPE = 'must be a provider: an object with a string id, a string model and a complete function';
19
22
  /** The options that must be positive integers when they are set. */
20
23
  const LIMITS = ['concurrency', 'maxFindings'];
@@ -27,15 +30,17 @@ const LIMITS = ['concurrency', 'maxFindings'];
27
30
  * profile's own issues, a repeated profile id, a `concurrency` or `maxFindings` that is not a
28
31
  * positive integer, a `maxReviewTokens` that is not a whole number of tokens from 1 to
29
32
  * 9007199254740991, a `reviewTimeoutMs` that is not a whole number of milliseconds from 1000 to
30
- * 86400000, an `exclude` that is not a list of at most 100 patterns that can be taken, a
31
- * missing or malformed research provider or voter, a provider's stated `timeoutMs` that is not a
33
+ * 86400000, a `partTokens` that is not a whole number of tokens from 1024 to 9007199254740991, an
34
+ * `exclude` that is not a list of at most 100 patterns that can be taken, a missing or malformed
35
+ * research provider or voter, a provider's stated `timeoutMs` that is not a
32
36
  * whole number of milliseconds from 1000 to 518400000, `retries` that is not a whole number from
33
- * 0 to 5 or `worstCase` that is not a function, ports for a profile or a lens the run does not have
37
+ * 0 to 5 or `worstCase` or `room` that is not a function, ports for a profile or a lens the run does not have
34
38
  * (a likely typo), and an event sink that is not a function. Ports are checked only for the profiles
35
39
  * that have no issue of their own, and not at all when `profiles` is not an array. Every record keyed
36
40
  * by a caller's id is read as an own property, since `constructor` is a valid id. `maxReviewTokens`,
37
- * the most tokens one review spends, input and output, is 2000000 when unset, and `reviewTimeoutMs`,
38
- * how long one review runs, is 1800000 (30 minutes) when unset: see `review`.
41
+ * the most tokens one review spends, input and output, is 2000000 when unset, `reviewTimeoutMs`,
42
+ * how long one review runs, is 1800000 (30 minutes) when unset, and `partTokens`, the most tokens of
43
+ * diff text one research part holds, is 32768 when unset: see `review`.
39
44
  *
40
45
  * Each profile is compiled into a frozen `ProfileRun`, its instructions rendered, its thresholds
41
46
  * resolved and its providers captured, and `exclude` is compiled into a matcher, so later changes to
@@ -71,6 +76,7 @@ export function createQuorumWith(options, ports, clock) {
71
76
  maxFindings: options.maxFindings ?? DEFAULT_MAX_FINDINGS,
72
77
  maxReviewTokens: options.maxReviewTokens ?? DEFAULT_MAX_REVIEW_TOKENS,
73
78
  reviewTimeoutMs: options.reviewTimeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS,
79
+ partTokens: options.partTokens ?? DEFAULT_PART_TOKENS,
74
80
  clock,
75
81
  excluded: excludeMatcher(options.exclude ?? []),
76
82
  sink: ports.events,
@@ -78,29 +84,73 @@ export function createQuorumWith(options, ports, clock) {
78
84
  const warnings = Object.freeze(options.profiles.flatMap(profile => profileWarnings(profile)));
79
85
  return Object.freeze({
80
86
  review: (input, options) => review(compiled, input, options),
87
+ estimate: (input) => estimate(compiled, input),
81
88
  warnings,
82
89
  });
83
90
  }
91
+ /**
92
+ * What one review of `input.diff` may cost, before any call: no provider is called and nothing is read or
93
+ * written. Per profile, it states what the review's ledger reserves for each research part, in order, exactly
94
+ * as `review` plans and builds them (the diff less the sections `exclude` leaves out, parted on each research
95
+ * provider's stated room), and a bound for the votes: `maxFindings` votes of each lens, each at the request for
96
+ * a finding at its longest citing the largest section of the filtered diff. `expected` counts the research
97
+ * parts alone, each at a third of its reservation, rounded up (`BOUND_OVER_CODE`), and `worst` the parts in full
98
+ * and every vote at its bound, so the votes are in the worst case only. `inFlight` is what the calls that run
99
+ * at once reserve, the `concurrency` largest bounds among all the profiles' calls, and `fits` is whether
100
+ * `expected` and `inFlight` are within `maxReviewTokens`. A diff with nothing left to read, blank or whose every
101
+ * file is excluded or held back as a secret, makes no call and costs nothing; a file `input.send` names is not
102
+ * held back, so it is counted, as `review` sends it. It is an estimate, not a limit: a review reserves each call
103
+ * against the cap, which still holds whatever `fits` says.
104
+ *
105
+ * @throws ConfigError listing every issue of the input that `review` refuses: an input that is not an object, a `diff` that is not a string, a `source`, a `leftOut` or a `send` it cannot take
106
+ */
107
+ function estimate(compiled, input) {
108
+ const issues = reviewIssues(input, {});
109
+ if (issues.length > 0)
110
+ throw new ConfigError(issues);
111
+ const sent = new Set(input.send);
112
+ return estimateReview(compiled.runs, compiled, input.diff, path => sent.has(path));
113
+ }
84
114
  /**
85
115
  * One review of a diff by every profile of the quorum, concurrently, each through research, dedup
86
116
  * and panel under the review's one concurrency limit; a blank diff runs no stage. The diff is
87
- * filtered once: the sections the quorum's `exclude` patterns match leave every request, so
88
- * research, the check of each finding and the votes read the diff less those sections, split into
89
- * one section per file once for every profile, and a finding that cites an excluded file is dropped
90
- * as outside the diff. A filtered diff that is blank, with every file excluded and nothing before
91
- * the first header, runs no stage, as a blank diff does. The advisory flags are read before any
92
- * stage runs, from the whole diff, the excluded files included. The review lists the files it
93
- * leaves out in `meta.leftOut`: the excluded ones, which are no gap, and the files whose change the
94
- * diff does not carry, binary files and submodules' commits, for each reason of which it records a
95
- * gap for every profile; their sections still reach the stages. Everything it knows before a call
96
- * is sent in this order: `run:start`, then a `left-out` event naming those files when it leaves one
97
- * out, then the gaps' `incomplete` events, then the `flag` events of the advisory flags, kept in
98
- * `meta.flags`, none of which changes a verdict, then the stages. Each event is handed to the sink
117
+ * filtered once: the sections the quorum's `exclude` patterns match, and the files held back as secrets
118
+ * (below), leave every request, so research, the check of each finding and the votes read the diff less
119
+ * those sections, split into one section per file once for every profile, and a finding that cites an
120
+ * excluded or a held file is dropped as outside the diff. A filtered diff that is blank, with every file
121
+ * excluded or held and nothing before the first header, runs no stage, as a blank diff does, and still
122
+ * records the gaps its held files make. The advisory flags are read before any stage runs, from the
123
+ * whole diff, the excluded and the held files included. The review lists the files it leaves out in
124
+ * `meta.leftOut`: the excluded ones, which are no gap, the files whose change the diff does not carry,
125
+ * binary files and submodules' commits, and the files held back, for each reason of which it records a
126
+ * gap for every profile; the sections of a file whose change the diff does not carry still reach the
127
+ * stages. The input's own `leftOut`, the files its
128
+ * source left out before it made the diff, comes first in the list, in the `left-out` event and in the gaps'
129
+ * counts, each file, reason and rule once, and a skipped one is no gap; the input's `source` is checked,
130
+ * copied and recorded in `meta.source`, `{ kind: 'diff' }` when it names none. Its `skipped` files of the
131
+ * rule `secret`, and the `secret` and `deleted-secret` files `meta.leftOut` lists, each raise one `secret-file`
132
+ * flag, as many as `meta.leftOut` lists, ahead of the diff's flags and whatever the diff is.
133
+ * Everything it knows before a call is sent in this order: `run:start`, then a `left-out` event naming those files when it leaves one
134
+ * out, then the gaps' `incomplete` events (each profile's `binary`, `submodule` and `secret` gaps, then its
135
+ * `too-large` gap), then the `flag` events of the advisory flags, the `secret-file` flags first,
136
+ * kept in `meta.flags`, none of which changes a verdict, then the stages. Each event is handed to the sink
99
137
  * as a copy, so a sink that changes one changes nothing else. The review reports itself through
100
138
  * events, from `run:start` to `run:end`, and its result merges the profiles' verdicts and gaps in
101
139
  * profile order. `meta.profiles[<id>].invalidFindings` and `meta.usage` are counted from the
102
140
  * events before the sink receives them.
103
141
  *
142
+ * No model is sent a line of a file held back as a secret. A file is held when its name is a secret's
143
+ * (`.env`, `id_ed25519`, a `.pem` file) or a line of it, removed and context lines included, holds a credential
144
+ * quorum recognizes (a private key's armor and body, the keys of AWS, GitHub, Slack, Google, Stripe, Anthropic
145
+ * and OpenAI), by any path its section names; every section of it leaves the diff, and a credential in one
146
+ * holds all. It is listed in `meta.leftOut` as `secret` with its `rule` (`name`, or the kind of credential),
147
+ * raises a `secret-file` flag, and is a `secret` gap of every profile that no flag lifts; a change that deletes
148
+ * a file named as a secret whole lists it as `deleted-secret` with its flag and no gap, while a deletion of a
149
+ * file held for a credential in it, whose removed code would go unread, is a `secret` gap. The text no header names is one file
150
+ * of the empty name, held as any other. `input.send` names the files to send though held, each the path exactly
151
+ * as `meta.leftOut` lists it, never the empty name: such a file is sent, neither listed nor flagged, and one
152
+ * `exclude` matches is excluded first. `send` is copied before the review's first await.
153
+ *
104
154
  * Abort never fails open. The review's signal joins the caller's `signal` to an internal one; every
105
155
  * stage and every call checks it, every attempt carries a signal of its own, which the review's
106
156
  * abort and the attempt's deadline abort, and it is checked once more after the profiles have run,
@@ -114,20 +164,35 @@ export function createQuorumWith(options, ports, clock) {
114
164
  *
115
165
  * A review ends at its deadline, `reviewTimeoutMs` after it starts, with an answer: at it every call in
116
166
  * flight and every wait is stopped at once, no call still queued starts, and what was not done is a
117
- * `review-deadline` gap of its profile, its research request or its votes, each a failed vote of the
118
- * deadline. The review then resolves with its findings so far, exiting `4` for a gating profile whatever
119
- * the flags; the deadline is no abort, so an interrupt still rejects with its reason, before the deadline
120
- * or after it, and a review that reaches its deadline is never a failed run. The deadline's timer is armed
121
- * once the input checks pass and cleared however the review ends: it resolves, it rejects, its sink throws
122
- * or it is aborted.
167
+ * `review-deadline` gap of its profile, its research request (the parts of it not yet answered) or its
168
+ * votes, each a failed vote of the deadline. The review then resolves with its findings so far, exiting
169
+ * `4` for a gating profile whatever the flags; the deadline is no abort, so an interrupt still rejects
170
+ * with its reason, before the deadline or after it, and a review that reaches its deadline is never a
171
+ * failed run. The deadline's timer is armed once the input checks pass and cleared however the review
172
+ * ends: it resolves, it rejects, its sink throws or it is aborted.
173
+ *
174
+ * A change larger than one research request is researched in parts, not refused. Each profile's research
175
+ * is planned once the scope is known, on its own research provider's stated room: a provider that
176
+ * states none, or a diff within `partTokens` and within the room, is sent the whole diff in one request,
177
+ * as it always was; else the filtered diff's sections, in order, are packed into parts of at most
178
+ * `partTokens` whose request fits the room, a section too large for a part split between its hunks and
179
+ * a hunk never cut. Each part is one research call, in order, that names its position and the change's
180
+ * files; the replies are read in order, up to `maxFindings` findings in all, each checked against the
181
+ * whole diff. A hunk, or a section with no hunk, that fits in no research part of the window is no part's:
182
+ * the profile records one `too-large` gap for them before any call is sent, which no flag lifts for a
183
+ * gating profile. `meta.profiles.<id>.coverage` lists every file of the input diff once, in its order,
184
+ * with how much of it the profile's research reviewed: reviewed, partly (with the ranges left), not
185
+ * (with the reason), or excluded by `exclude`; each profile has its own, since each has its own
186
+ * research model.
123
187
  *
124
188
  * A review spends at most `maxReviewTokens` tokens. Each review has its own ledger of that cap: every
125
189
  * attempt of every call reserves its worst case in it before it is sent and settles at what it spent,
126
190
  * so concurrent calls cannot overshoot it. A call the cap stops is no failed review: its profile's
127
191
  * research or vote is a `token-cap` gap, which exits 4 for a gating profile, and the other profiles
128
- * and votes run as far as the cap lets them.
192
+ * and votes run as far as the cap lets them. A research in parts spends up to the cap, each part reserved
193
+ * before it is sent: the parts the cap cannot fund are not sent, and one gap counts them.
129
194
  *
130
- * @throws ConfigError listing every issue of the input and the options: an input that is not an object, a `diff` that is not a string, options that are not an object, a `signal` that is not an AbortSignal
195
+ * @throws ConfigError listing every issue of the input and the options: an input that is not an object, a `diff` that is not a string, a `source`, a `leftOut` or a `send` it cannot take, options that are not an object, a `signal` that is not an AbortSignal
131
196
  * @throws the signal's reason once the review is aborted, before it starts or while it runs
132
197
  * @throws the error of a sink that throws, or of a gating profile that fails: a ProviderError from its research call, an OutputError for its reply
133
198
  */
@@ -168,22 +233,45 @@ async function reviewUntil(compiled, input, options, deadline, expired) {
168
233
  const whole = input.diff.trim() === ''
169
234
  ? undefined
170
235
  : splitDiff(input.diff);
171
- const flags = whole === undefined
172
- ? []
173
- : diffFlags(whole);
236
+ // Copied before the first await, so the caller's later changes to its input reach neither the result nor the events.
237
+ const sent = new Set(input.send);
238
+ const source = sourceOf(input.source);
174
239
  const scope = whole === undefined
175
- ? { diff: input.diff, leftOut: [] }
176
- : reviewScope(input.diff, compiled.excluded);
240
+ ? { diff: input.diff, leftOut: [], files: [] }
241
+ : reviewScope(input.diff, compiled.excluded, path => sent.has(path));
242
+ const leftOut = mergeLeftOut(input.leftOut ?? [], scope.leftOut);
243
+ // The source's secrets are read from the merged list, so a file it lists twice is flagged once, as `meta.leftOut` lists it once.
244
+ const flags = [
245
+ ...secretFlags(leftOut),
246
+ ...whole === undefined
247
+ ? []
248
+ : diffFlags(whole),
249
+ ];
177
250
  // What the stages read: none when the filtered diff is blank, else the sections the flags read when nothing was left out.
178
251
  const sections = scope.diff.trim() === ''
179
252
  ? undefined
180
253
  : scope.diff === input.diff
181
254
  ? whole
182
255
  : splitDiff(scope.diff);
183
- const gaps = new Map(runs.map(run => [
184
- run.id,
185
- leftOutGaps(run.id, scope.leftOut),
186
- ]));
256
+ // The same sections as the research packs them, and how each profile's research goes: none when no stage runs.
257
+ const filtered = sections === undefined
258
+ ? []
259
+ : diffSections(scope.diff);
260
+ const plans = sections === undefined
261
+ ? []
262
+ : runs.map(run => planResearch(run, scope.diff, filtered, compiled.partTokens));
263
+ const gaps = new Map(runs.map((run, index) => {
264
+ const tooLarge = tooLargeGap(run.id, filtered, plans[index]?.packing, scope.leftOut);
265
+ return [
266
+ run.id,
267
+ [
268
+ ...leftOutGaps(run.id, leftOut),
269
+ ...tooLarge === undefined
270
+ ? []
271
+ : [tooLarge],
272
+ ],
273
+ ];
274
+ }));
187
275
  const tally = {
188
276
  invalidFindings: new Map(),
189
277
  };
@@ -212,6 +300,7 @@ async function reviewUntil(compiled, input, options, deadline, expired) {
212
300
  deadline,
213
301
  fail,
214
302
  maxFindings: compiled.maxFindings,
303
+ concurrency: compiled.concurrency,
215
304
  clock: compiled.clock,
216
305
  };
217
306
  emit({
@@ -222,15 +311,15 @@ async function reviewUntil(compiled, input, options, deadline, expired) {
222
311
  providersOf(run),
223
312
  ])),
224
313
  });
225
- if (scope.leftOut.length > 0)
226
- emit({ type: 'left-out', files: scope.leftOut });
314
+ if (leftOut.length > 0)
315
+ emit({ type: 'left-out', files: leftOut });
227
316
  for (const run of runs) {
228
317
  for (const entry of gaps.get(run.id) ?? [])
229
318
  emit({ type: 'incomplete', entry });
230
319
  }
231
320
  for (const flag of flags)
232
321
  emit({ type: 'flag', flag });
233
- const outcomes = await reviewAll(ctx, runs, scope.diff, sections).catch((error) => {
322
+ const outcomes = await reviewAll(ctx, runs, plans, scope.diff, sections).catch((error) => {
234
323
  // A gating profile's research failure aborted the review where it failed; any other failure aborts it here. The first reason stays the reason.
235
324
  const reason = signal.aborted ? signal.reason : error;
236
325
  internal.abort(reason);
@@ -249,15 +338,16 @@ async function reviewUntil(compiled, input, options, deadline, expired) {
249
338
  version: packageJson.version,
250
339
  startedAt,
251
340
  durationMs,
252
- profiles: Object.fromEntries(runs.map(run => [
341
+ source,
342
+ profiles: Object.fromEntries(runs.map((run, index) => [
253
343
  run.id,
254
- profileMeta(run, tally.invalidFindings.get(run.id) ?? 0),
344
+ profileMeta(run, tally.invalidFindings.get(run.id) ?? 0, coverageOf(scope, filtered, plans[index]?.packing, outcomes[index]?.parts ?? [])),
255
345
  ])),
256
346
  ...(tally.usage === undefined
257
347
  ? {}
258
348
  : { usage: tally.usage }),
259
349
  incomplete,
260
- leftOut: scope.leftOut,
350
+ leftOut,
261
351
  flags,
262
352
  };
263
353
  emit({
@@ -270,21 +360,21 @@ async function reviewUntil(compiled, input, options, deadline, expired) {
270
360
  });
271
361
  return { kept, discarded, unreviewed, meta };
272
362
  }
273
- /** Run every profile through its stages at once on the diff's sections; a blank diff, which has none, runs no stage. */
274
- async function reviewAll(ctx, runs, diff, sections) {
363
+ /** Run every profile through its stages at once on the diff's sections, each on its own plan; a blank diff, which has none, runs no stage. */
364
+ async function reviewAll(ctx, runs, plans, diff, sections) {
275
365
  if (sections === undefined)
276
366
  return [];
277
- return Promise.all(runs.map(run => reviewProfile(ctx, run, diff, sections)));
367
+ return Promise.all(runs.map((run, index) => reviewProfile(ctx, run, plans[index], diff, sections)));
278
368
  }
279
369
  /**
280
370
  * One profile's review: its panel's outcome, with the research gaps before the panel's own, and last the
281
371
  * gap of each limit that stopped its work, reported by an `incomplete` event once the panel's stage has ended.
282
372
  */
283
- async function reviewProfile(ctx, run, diff, sections) {
284
- const researched = await stage(ctx, run.id, 'research', () => research(ctx, run, diff, sections), outcome => outcome.findings.length);
373
+ async function reviewProfile(ctx, run, plan, diff, sections) {
374
+ const researched = await stage(ctx, run.id, 'research', () => research(ctx, run, plan, diff, sections), outcome => outcome.findings.length);
285
375
  const candidates = await stage(ctx, run.id, 'dedup', () => dedup(researched.findings), found => found.length);
286
376
  const judged = await stage(ctx, run.id, 'panel', () => panel(ctx, run, candidates, sections, diff), outcome => outcome.kept.length + outcome.discarded.length + outcome.unreviewed.length);
287
- const limits = limitGaps(run.id, researched.stopped, [
377
+ const limits = limitGaps(run.id, researched.parts, [
288
378
  ...judged.kept,
289
379
  ...judged.discarded,
290
380
  ...judged.unreviewed,
@@ -298,20 +388,26 @@ async function reviewProfile(ctx, run, diff, sections) {
298
388
  ...judged.incomplete,
299
389
  ...limits,
300
390
  ],
391
+ parts: researched.parts,
301
392
  };
302
393
  }
303
394
  /**
304
395
  * Every problem with one review's input and options, so an untyped caller gets issues, never a
305
396
  * TypeError. An input that is not an object is named as the input, not as its diff: the likely
306
- * mistake is the diff text passed on its own, as `runQuorum` takes it. The signal must be a real
307
- * AbortSignal: `AbortSignal.any` accepts nothing else.
397
+ * mistake is the diff text passed on its own, as `runQuorum` takes it. The `source`, the `leftOut` and the
398
+ * `send`, when set, are checked after the diff, so a caller sees every issue of the input at once. The signal
399
+ * must be a real AbortSignal: `AbortSignal.any` accepts nothing else.
308
400
  */
309
401
  function reviewIssues(input, options) {
310
402
  const issues = [];
311
- if (!isRecord(input))
403
+ if (!isRecord(input)) {
312
404
  issues.push({ path: 'input', message: 'must be an object holding the diff string' });
313
- else if (typeof input.diff !== 'string')
314
- issues.push({ path: 'diff', message: 'must be a string' });
405
+ }
406
+ else {
407
+ if (typeof input.diff !== 'string')
408
+ issues.push({ path: 'diff', message: 'must be a string' });
409
+ issues.push(...sourceIssues(input.source), ...leftOutIssues(input.leftOut), ...sendIssues(input.send));
410
+ }
315
411
  if (!isRecord(options))
316
412
  issues.push({ path: 'options', message: 'must be an object' });
317
413
  else if (options.signal !== undefined && !(options.signal instanceof AbortSignal))
@@ -328,12 +424,13 @@ function providersOf(run) {
328
424
  ])),
329
425
  };
330
426
  }
331
- function profileMeta(run, invalidFindings) {
427
+ function profileMeta(run, invalidFindings, coverage) {
332
428
  return {
333
429
  providers: providersOf(run),
334
430
  policy: { ...run.thresholds },
335
431
  gating: run.gating,
336
432
  invalidFindings,
433
+ coverage,
337
434
  };
338
435
  }
339
436
  /**
@@ -420,8 +517,9 @@ function profileListIssues(profiles) {
420
517
  }
421
518
  /**
422
519
  * `concurrency` and `maxFindings` are positive integers when set, `maxReviewTokens` a whole number of
423
- * tokens from 1 to 9007199254740991, and `reviewTimeoutMs` a whole number of milliseconds from 1000 to
424
- * 86400000. A number is quoted in the first two; anything else is described by the rule alone.
520
+ * tokens from 1 to 9007199254740991, `reviewTimeoutMs` a whole number of milliseconds from 1000 to
521
+ * 86400000, and `partTokens` a whole number of tokens from 1024 to 9007199254740991. A number is
522
+ * quoted in the first two; anything else is described by the rule alone.
425
523
  */
426
524
  function limitIssues(options) {
427
525
  const issues = LIMITS.flatMap((path) => {
@@ -445,6 +543,11 @@ function limitIssues(options) {
445
543
  : timeoutProblem(options.reviewTimeoutMs);
446
544
  if (timeout !== undefined)
447
545
  issues.push({ path: 'reviewTimeoutMs', message: timeout });
546
+ const partTokens = options.partTokens === undefined
547
+ ? undefined
548
+ : partTokensProblem(options.partTokens);
549
+ if (partTokens !== undefined)
550
+ issues.push({ path: 'partTokens', message: partTokens });
448
551
  return issues;
449
552
  }
450
553
  /** The ports of each checked profile in order, then the ports no profile of the run names, then the sink. */
@@ -505,7 +608,7 @@ function profilePortIssues(entries, profile) {
505
608
  }
506
609
  /**
507
610
  * The issues of one provider: it is missing, it is not one, the `timeoutMs` or the `retries` it
508
- * states, as own data, is out of range, or the `worstCase` it states, as own data, is not a function.
611
+ * states, as own data, is out of range, or the `worstCase` or the `room` it states, as own data, is not a function.
509
612
  */
510
613
  function providerIssues(path, value) {
511
614
  if (value === undefined) {
@@ -534,6 +637,9 @@ function providerIssues(path, value) {
534
637
  const worstCase = ownData(value, 'worstCase');
535
638
  if (worstCase !== undefined && typeof worstCase !== 'function')
536
639
  issues.push({ path: `${path}.worstCase`, message: 'must be a function' });
640
+ const room = ownData(value, 'room');
641
+ if (room !== undefined && typeof room !== 'function')
642
+ issues.push({ path: `${path}.room`, message: 'must be a function' });
537
643
  return issues;
538
644
  }
539
645
  /** A provider is a non-null object with a string id, a string model and a complete function. */
@@ -0,0 +1,98 @@
1
+ /*!
2
+ * The credential rules below are gitleaks 8.30.1's, and the private-key markers are
3
+ * pre-commit-hooks v5.0.0's. Both are MIT licensed:
4
+ *
5
+ * Copyright (c) 2019 Zachary Rice
6
+ * Copyright (c) 2014 pre-commit dev team: Anthony Sottile, Ken Struys
7
+ *
8
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
9
+ * of this software and associated documentation files (the "Software"), to deal
10
+ * in the Software without restriction, including without limitation the rights
11
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12
+ * copies of the Software, and to permit persons to whom the Software is
13
+ * furnished to do so, subject to the following conditions:
14
+ *
15
+ * The above copyright notice and this permission notice shall be included in all
16
+ * copies or substantial portions of the Software.
17
+ *
18
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24
+ * SOFTWARE.
25
+ */
26
+ import type { DiffSection } from './diff.ts';
27
+ import type { CredentialKind, SecretRule } from './types.ts';
28
+ /** The names of files that hold a secret, matched whole against a path's last segment, in any case. */
29
+ export declare const SECRET_NAMES: readonly string[];
30
+ /** A name that starts with this is a secret's: `.env.local`, and `.env.defaults`, which a loader reads as values at run time. In any case. */
31
+ export declare const SECRET_PREFIX = ".env.";
32
+ /** What the name of a file that holds a secret ends with, in any case. */
33
+ export declare const SECRET_SUFFIXES: readonly string[];
34
+ /** What ends the name of a template, after `SECRET_PREFIX`: `.env.example` is committed with no value in it, and is sent. In any case. */
35
+ export declare const TEMPLATE_SUFFIXES: readonly string[];
36
+ /** Every rule a file can be held by, in the order a reader lists them. */
37
+ export declare const SECRET_RULES: readonly ["name", "private-key", "aws-key", "github-token", "slack-token", "google-key", "stripe-key", "anthropic-key", "openai-key"];
38
+ /** What a kind of credential is called in a sentence, after "holds what reads as". */
39
+ export declare const CREDENTIAL_PHRASES: Readonly<Record<CredentialKind, string>>;
40
+ /** One rule of gitleaks' default config: what it reads, and what makes a match no hit. */
41
+ export interface CredentialRule {
42
+ /** The kind a hit of this rule reports. */
43
+ readonly kind: CredentialKind;
44
+ /** The rule's id in gitleaks' config. */
45
+ readonly id: string;
46
+ /** Gitleaks' regex, as JavaScript: its `(?i)` is the `i` flag. */
47
+ readonly pattern: RegExp;
48
+ /** A match whose secret has an entropy at or below this is no hit; none when the rule has no floor. */
49
+ readonly entropy?: number;
50
+ /** A match whose secret this matches is no hit: the rule's own allowlist. */
51
+ readonly allow?: RegExp;
52
+ /** A line that holds none of these, in any case, runs no rule. */
53
+ readonly keywords: readonly string[];
54
+ }
55
+ /** The 21 rules of gitleaks 8.30.1 for AWS, GitHub, Slack, Google, Stripe, Anthropic and OpenAI, grouped by kind, in the order of `SECRET_RULES`. */
56
+ export declare const CREDENTIAL_RULES: readonly CredentialRule[];
57
+ /**
58
+ * Whether the name of a file is a secret's: its last segment is one of `SECRET_NAMES`, starts with
59
+ * `SECRET_PREFIX` or ends in one of `SECRET_SUFFIXES`, in any case, and is no template (a `.env.` name
60
+ * that ends in one of `TEMPLATE_SUFFIXES`, or a `secrets.yaml` or `secrets.yml` in a directory named
61
+ * `templates`). It reads a path as the diff writes it, so an `a/` or `b/` prefix changes nothing.
62
+ * Generous: only the name decides, never the directory, a template apart.
63
+ */
64
+ export declare function isSecretName(path: string): boolean;
65
+ /**
66
+ * The kind of the first credential a text holds, read line by line as gitleaks reads a fragment, or
67
+ * undefined. A line is first tested for a private-key marker, which counts only when a body run
68
+ * follows it, on its own line or within `BODY_REACH` lines; then, when it holds a keyword of the rules, for each rule in
69
+ * the table's order and every match of it on the line, a match whose secret has an entropy at or below
70
+ * the rule's floor, or that the rule's own allowlist matches, being no hit. It reads every row alike
71
+ * (added, removed, context, or none), a line of any length and a line that ends with `\r`, and it is
72
+ * linear in the text. Generous: a removed line and a key in a comment hold as any other.
73
+ */
74
+ export declare function credentialIn(text: string): CredentialKind | undefined;
75
+ /**
76
+ * Why a section is held back, or undefined: `name` when its header's path (a non-empty one), a name
77
+ * its `diff --git` line holds (each word of it, so a header that cannot be read, or that is forged as
78
+ * `diff --git a/.env` or `diff --git a/.env b/.env c`, still names the `.env` it spells), or a path its
79
+ * own lines name is a secret's, else the kind of the first credential its text holds. The name is
80
+ * taken before the content, so a `.env` is held by its name whatever it holds. Generous: any one path
81
+ * the section names, a rename's old side included, holds it.
82
+ */
83
+ export declare function secretRuleOf(section: DiffSection): SecretRule | undefined;
84
+ /**
85
+ * Whether a section deletes its file whole: it starts with its `diff --git` header, holds a `deleted
86
+ * file mode` line, and every other line of it is one git writes for a deletion: `deleted file mode`,
87
+ * `index`, a `-` row (the `---` line is one), `+++ /dev/null`, `Binary files <path> and /dev/null
88
+ * differ`, a hunk header whose new side is `+0,0`, ``, and an empty last
89
+ * piece, each less a trailing `\r`. Any other line (a `+` or context row, a blank line in the
90
+ * middle, a mail's headers in a `format-patch` series, a `GIT binary patch`) makes it no whole
91
+ * deletion, so a forged or mixed section is a gap and never passes as one, and a file truncated to
92
+ * empty, which has no `deleted file mode`, is no deletion. Its first `--- ` line, when it has one (an
93
+ * empty or a binary file has none), also names the old side of a header that names one path on both
94
+ * sides (`namesOldSide`): a `.env` header over a `--- a/src/auth.ts` line is a forged section that
95
+ * would hide the removal of another file, so it is no deletion and a gap. Only the first such line
96
+ * counts: a later one is a removed row of the file.
97
+ */
98
+ export declare function isWholeDeletion(text: string): boolean;