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