@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.
- package/README.md +2 -0
- package/dist/bench/fingerprint.d.ts +6 -5
- package/dist/bench/fingerprint.js +11 -5
- package/dist/bench/records.d.ts +100 -2
- package/dist/bench/records.js +80 -5
- package/dist/bench/runner.js +1 -1
- package/dist/cli/io.d.ts +5 -0
- package/dist/cli/main.d.ts +36 -13
- package/dist/cli/main.js +194 -44
- package/dist/cli/print-config.d.ts +5 -5
- package/dist/cli/print-config.js +10 -5
- package/dist/cli/render.d.ts +7 -1
- package/dist/cli/render.js +25 -3
- package/dist/config/claude-code.d.ts +2 -6
- package/dist/config/claude-code.js +6 -44
- package/dist/config/command.d.ts +10 -0
- package/dist/config/command.js +47 -0
- package/dist/config/from-config.js +8 -2
- package/dist/config/resolve.d.ts +4 -0
- package/dist/config/resolve.js +10 -0
- package/dist/config/schema.d.ts +13 -2
- package/dist/config/schema.js +36 -5
- package/dist/core/coverage.d.ts +38 -13
- package/dist/core/coverage.js +105 -28
- package/dist/core/diff.d.ts +77 -0
- package/dist/core/diff.js +122 -24
- package/dist/core/estimate.d.ts +45 -0
- package/dist/core/estimate.js +188 -0
- package/dist/core/flags.d.ts +14 -1
- package/dist/core/flags.js +56 -0
- package/dist/core/inputs.d.ts +38 -0
- package/dist/core/inputs.js +228 -0
- package/dist/core/limits.d.ts +5 -4
- package/dist/core/limits.js +11 -5
- package/dist/core/parts.d.ts +146 -0
- package/dist/core/parts.js +388 -0
- package/dist/core/ports.d.ts +10 -0
- package/dist/core/prompts.d.ts +22 -3
- package/dist/core/prompts.js +43 -7
- package/dist/core/quorum.d.ts +7 -5
- package/dist/core/quorum.js +164 -58
- package/dist/core/secrets.d.ts +98 -0
- package/dist/core/secrets.js +507 -0
- package/dist/core/stages/context.d.ts +16 -3
- package/dist/core/stages/context.js +44 -17
- package/dist/core/stages/panel.d.ts +8 -2
- package/dist/core/stages/panel.js +50 -9
- package/dist/core/stages/research.d.ts +107 -31
- package/dist/core/stages/research.js +290 -53
- package/dist/core/types.d.ts +217 -29
- package/dist/core/verify.d.ts +6 -0
- package/dist/core/verify.js +6 -3
- package/dist/git/run.d.ts +223 -0
- package/dist/git/run.js +608 -0
- package/dist/git/tree.d.ts +43 -0
- package/dist/git/tree.js +171 -0
- package/dist/index.d.ts +26 -2
- package/dist/index.js +34 -2
- package/dist/providers/anthropic.d.ts +2 -1
- package/dist/providers/anthropic.js +4 -2
- package/dist/providers/claude-code.d.ts +5 -0
- package/dist/providers/claude-code.js +11 -1
- package/dist/providers/gemini.d.ts +2 -1
- package/dist/providers/gemini.js +4 -2
- package/dist/providers/ollama.d.ts +2 -1
- package/dist/providers/ollama.js +4 -2
- package/dist/providers/openai-compatible.d.ts +2 -1
- package/dist/providers/openai-compatible.js +4 -2
- package/dist/providers/size.d.ts +9 -1
- package/dist/providers/size.js +18 -4
- package/dist/sources/added.d.ts +49 -0
- package/dist/sources/added.js +134 -0
- package/dist/sources/diff.d.ts +13 -0
- package/dist/sources/diff.js +63 -0
- package/dist/sources/local.d.ts +41 -0
- package/dist/sources/local.js +251 -0
- package/dist/sources/paths.d.ts +45 -0
- package/dist/sources/paths.js +230 -0
- package/dist/sources/range.d.ts +21 -0
- package/dist/sources/range.js +75 -0
- package/dist/sources/read.d.ts +69 -0
- package/dist/sources/read.js +37 -0
- package/dist/sources/repository.d.ts +9 -0
- package/dist/sources/repository.js +28 -0
- package/dist/sources/skips.d.ts +49 -0
- package/dist/sources/skips.js +126 -0
- package/package.json +1 -1
- package/schema/quorum.schema.json +15 -0
package/dist/core/types.d.ts
CHANGED
|
@@ -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; `
|
|
124
|
-
*
|
|
125
|
-
*
|
|
126
|
-
*
|
|
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,
|
|
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
|
-
/**
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
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:
|
|
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
|
|
157
|
-
* human where to look, and never changes a verdict, a confidence
|
|
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,
|
|
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
|
|
242
|
-
*
|
|
243
|
-
*
|
|
244
|
-
*
|
|
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';
|
package/dist/core/verify.d.ts
CHANGED
|
@@ -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
|
package/dist/core/verify.js
CHANGED
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
import { locate } from "./diff.js";
|
|
2
2
|
import { stripHidden } from "./sanitize.js";
|
|
3
|
-
|
|
4
|
-
const
|
|
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
|
-
|
|
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>;
|