@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
@@ -1,13 +1,21 @@
1
- import { diffSectionFor } from "../diff.js";
1
+ import { diffSectionFor, hunksOf, sectionFor } from "../diff.js";
2
2
  import { isLimit } from "../limits.js";
3
3
  import { parseVoteReply } from "../output.js";
4
+ import { nearestHunks } from "../parts.js";
4
5
  import { confidenceFor, undecidedLevel, verdictStatus } from "../policy.js";
5
6
  import { voteRequest } from "../prompts.js";
6
- import { callProvider, isTooLarge, providerFailure, refusalMessage } from "./context.js";
7
+ import { tokenBound } from "../tokens.js";
8
+ import { callProvider, isTooLarge, providerFailure, refusalMessage, roomOf } from "./context.js";
7
9
  /**
8
10
  * The panel stage of one profile: every finding goes to every lens, each vote to the lens's own
9
- * provider, and the quorum verdict is computed in code. Each voter receives the diff section of the
10
- * file its finding cites.
11
+ * provider, and the quorum verdict is computed in code. A vote's context is the diff section of the
12
+ * file its finding cites, the whole diff when the file has no section of its own. It is partial only
13
+ * for a voter that states a room (`Provider.room`) the section does not fit: that voter receives the
14
+ * section's header and the hunks nearest the cited line that fit its room, the cited hunk first (see
15
+ * `nearestHunks`), and its diff block says so. A voter that states no room, or whose room holds the
16
+ * section, receives the section as before, and so does one whose room does not hold the cited hunk
17
+ * alone, which its provider then refuses as too large. The context is chosen when the vote's request
18
+ * is built, inside the vote's slot.
11
19
  *
12
20
  * A voter never sees the other votes or their reasoning - independence is the point, not an
13
21
  * oversight. Letting verifiers see each other's reasoning measurably converges results toward
@@ -26,7 +34,10 @@ import { callProvider, isTooLarge, providerFailure, refusalMessage } from "./con
26
34
  * `vote-failed` gap when a kept verdict's failed votes leave a higher level undecided (ADR-0012).
27
35
  */
28
36
  export async function panel(ctx, run, findings, sections, diff) {
29
- const judged = await Promise.all(findings.map(finding => judge(ctx, run, finding, diffSectionFor(sections, finding.file, diff))));
37
+ const judged = await Promise.all(findings.map(finding => judge(ctx, run, finding, {
38
+ text: diffSectionFor(sections, finding.file, diff),
39
+ sections,
40
+ })));
30
41
  const outcome = {
31
42
  kept: [],
32
43
  discarded: [],
@@ -39,8 +50,8 @@ export async function panel(ctx, run, findings, sections, diff) {
39
50
  }
40
51
  return outcome;
41
52
  }
42
- async function judge(ctx, run, finding, diffContext) {
43
- const casts = await Promise.all(run.lenses.map(lens => castVote(ctx, run, finding, lens, diffContext)));
53
+ async function judge(ctx, run, finding, context) {
54
+ const casts = await Promise.all(run.lenses.map(lens => castVote(ctx, run, finding, lens, context)));
44
55
  const votes = casts.map(({ lensVote }) => lensVote);
45
56
  const refusals = casts.flatMap(({ refusal }) => refusal === undefined
46
57
  ? []
@@ -89,12 +100,12 @@ async function judge(ctx, run, finding, diffContext) {
89
100
  * raised, so an aborted review never resolves with a finding the abort left unreviewed. The `vote` event
90
101
  * is emitted after the vote's own `try`, so a sink that throws on it is never recorded as a failed vote.
91
102
  */
92
- async function castVote(ctx, run, finding, lens, diffContext) {
103
+ async function castVote(ctx, run, finding, lens, context) {
93
104
  let lensVote;
94
105
  let refusal;
95
106
  let replied = false;
96
107
  try {
97
- const text = await callProvider(ctx, { profile: run.id, role: 'vote', lens: lens.id }, lens, () => voteRequest(lens.instructions, finding, diffContext, run.guidelines));
108
+ const text = await callProvider(ctx, { profile: run.id, role: 'vote', lens: lens.id }, lens, () => requestFor(run, finding, lens, context));
98
109
  replied = true;
99
110
  lensVote = {
100
111
  angle: lens.id,
@@ -137,6 +148,36 @@ async function castVote(ctx, run, finding, lens, diffContext) {
137
148
  ? { lensVote }
138
149
  : { lensVote, refusal };
139
150
  }
151
+ /**
152
+ * The request of one vote. The finding's cited file's section is its context, as `voteRequest` takes it,
153
+ * unless the lens's voter states a room the section does not fit: its room for the request with an empty
154
+ * diff block, which text added to the block lowers by exactly its `tokenBound`, is below the section's.
155
+ * The context is then the section's header and the hunks nearest the cited line that fit the room of the
156
+ * request that describes them (see `nearestHunks`), when the cited hunk fits alone. A voter that states no
157
+ * room has no request built to ask. `undefined` from `nearestHunks`, a cited line no hunk holds or a cited
158
+ * hunk that does not fit alone, sends the whole context, which the provider refuses as too large if it is.
159
+ */
160
+ function requestFor(run, finding, lens, context) {
161
+ const nearest = lens.room === undefined
162
+ ? undefined
163
+ : nearestContext(run, finding, lens, context.sections);
164
+ return nearest === undefined
165
+ ? voteRequest(lens.instructions, finding, context.text, run.guidelines)
166
+ : voteRequest(lens.instructions, finding, nearest, run.guidelines, true);
167
+ }
168
+ /** The partial context of a voter that states a room, or undefined when the whole section fits, or nothing of it does. */
169
+ function nearestContext(run, finding, lens, sections) {
170
+ const section = sectionFor(sections, finding.file);
171
+ if (section === undefined)
172
+ return undefined;
173
+ const room = roomOf(lens, voteRequest(lens.instructions, finding, '', run.guidelines));
174
+ if (room === undefined || tokenBound(section.text) <= room)
175
+ return undefined;
176
+ const partialRoom = roomOf(lens, voteRequest(lens.instructions, finding, '', run.guidelines, true));
177
+ return partialRoom === undefined
178
+ ? undefined
179
+ : nearestHunks(section.text, hunksOf(sections, section.path, section.text), finding.line, partialRoom);
180
+ }
140
181
  /** What a call that failed says of itself as a vote's failure: the limit that stopped it, else what `providerFailure` reads, else `unknown`. */
141
182
  function voteFailureOf(error) {
142
183
  if (isLimit(error))
@@ -1,4 +1,5 @@
1
- import type { LimitName } from '../limits.ts';
1
+ import type { DiffSection } from '../diff.ts';
2
+ import type { Packing, PartOutcome } from '../parts.ts';
2
3
  import type { Finding, IncompleteEntry } from '../types.ts';
3
4
  import type { ProfileRun, RunContext } from './context.ts';
4
5
  /** How many reported findings a research reply may send to the panel; the rest is reported as incomplete. */
@@ -10,10 +11,15 @@ export interface ResearchOutcome {
10
11
  * code outside the diff, or names no file). An unreadable finding is reported in `incomplete` only.
11
12
  */
12
13
  invalid: string[];
13
- /** What the run could not review: findings the harness could not read, findings beyond the cap, a reply whose findings were all unusable, a research request refused as too large, or an advisory profile's research that failed. */
14
+ /** What the run could not review: findings the harness could not read, findings beyond the cap, a reply whose findings were all unusable, research requests refused as too large, or an advisory profile's research that failed. */
14
15
  incomplete: IncompleteEntry[];
15
- /** The limit that stopped the research request, so the profile reviews nothing. Its gap is written once the profile's panel has run, with the votes the limit stopped. */
16
- stopped?: LimitName;
16
+ /**
17
+ * What became of each research part, in the parts' order: `reviewed` when its reply was a valid findings
18
+ * envelope, the limit's name when the token cap or the deadline stopped it (its gap is written once the
19
+ * profile's panel has run, with the votes the limit stopped), else why it was not read. One entry for a
20
+ * research of one request, none when no part holds any of the diff.
21
+ */
22
+ parts: PartOutcome[];
17
23
  }
18
24
  /**
19
25
  * The id of a finding, stable across runs: the first 12 hex characters of SHA-256 over the JSON
@@ -23,40 +29,110 @@ export interface ResearchOutcome {
23
29
  */
24
30
  export declare function findingId(profile: string, file: string, line: number, category: string): string;
25
31
  /**
26
- * Turn a research reply into what the panel receives. The reply is parsed strictly (a malformed
27
- * envelope, or one with a key other than `findings`, throws, so it never reads as "no findings"),
28
- * only the first `maxFindings` findings it lists are read and checked against the diff (the work
29
- * spent on a reply built to flood the run stays bounded, whatever the entries hold), and nothing
30
- * the harness read is dropped silently: a finding that does not match the reply schema (what
31
- * planted text that closes a string early leaves behind), findings beyond the cap, and a reply
32
- * whose findings were all unusable, are recorded as incomplete, which fails the run (ADR-0012).
33
- * A finding that cites code outside the diff is only dropped with its reason: it was read, and
34
- * it is wrong. `invalid` holds only the reasons of the findings the check against the diff
35
- * dropped, so an unreadable finding is reported once, in `incomplete`. Every finding it keeps is
36
- * named by `findingId` and tagged with `profile`, and every incomplete entry it records is tagged
37
- * with `profile` too.
32
+ * How one profile's research goes: the sections of the filtered diff, and how they are packed. No packing
33
+ * is one request holding the whole diff, as it always was. A packing is the parts the research is sent in,
34
+ * and `listed` is the change's files every part's request names.
35
+ */
36
+ export interface ResearchPlan {
37
+ readonly sections: readonly DiffSection[];
38
+ readonly packing?: Packing;
39
+ /** The files the parts' requests name; set with `packing`. */
40
+ readonly listed?: ListedFiles;
41
+ }
42
+ /** The files a part's request names, as the diff writes them, and how many are left out. */
43
+ interface ListedFiles {
44
+ readonly files: readonly string[];
45
+ readonly unlisted: number;
46
+ }
47
+ /**
48
+ * Plan a profile's research of the filtered `diff`, whose sections are `sections`, before any stage runs.
49
+ * The research is one request holding the whole diff, which is what 0.5.0 sent, when:
50
+ * 1. the research provider states no room: no request is built to ask, so no nonce is drawn;
51
+ * 2. the room of the one-request research with an empty diff is no safe integer or is negative: its guard
52
+ * then refuses the request as it always did;
53
+ * 3. the diff's `tokenBound` is within the lesser of `partTokens` and that room;
54
+ * 4. the room of a part's request with an empty diff, its parts block at its widest (a position and a
55
+ * count of as many digits as the diff has lines, which no packing has more parts than), is no safe
56
+ * integer or is negative;
57
+ * 5. the packing sets a hunk aside while the one request still holds the whole diff: that hunk fits the
58
+ * one request but not a part's, which carries the parts block, and 0.5.0 read it, so nothing it read is
59
+ * left unread now.
60
+ * Otherwise it is the packing of the sections into parts of at most `partTokens` that fit that room (see
61
+ * `packParts`), with the change's files its requests name: at most 100, and at most a quarter of the
62
+ * lesser of `partTokens` and the one request's room, so the list stays small beside the diff of a part. When that
63
+ * packing sets a unit aside and the list names a file, the sections are packed again at the room of a parts
64
+ * block that lists no name (`and <n> more` alone), asked at the same widest position, because the list
65
+ * may be what left the unit out: the second packing and its block are kept when it sets fewer units aside,
66
+ * else the first, and the rule above (5) applies to the packing kept.
67
+ */
68
+ export declare function planResearch(run: ProfileRun, diff: string, sections: readonly DiffSection[], partTokens: number): ResearchPlan;
69
+ /**
70
+ * Turn one research reply into what the panel receives: `checkReplies` of that reply alone, unlabelled, so
71
+ * its gaps and its errors are the ones `checkReplies` states.
38
72
  *
39
73
  * @throws OutputError when the reply is not one JSON object holding a `findings` array and nothing else
40
74
  * @throws RangeError when `maxFindings` is not a positive integer
41
75
  */
42
- export declare function checkReply(text: string, sections: ReadonlyMap<string, string>, profile: string, maxFindings?: number): ResearchOutcome;
76
+ export declare function checkReply(text: string, sections: ReadonlyMap<string, string>, profile: string, maxFindings?: number): Omit<ResearchOutcome, 'parts'>;
43
77
  /**
44
- * The research stage of one profile: one call to its research provider, with the profile's
45
- * research instructions, the diff and the guidelines, whose reply `checkReply` turns into what the
46
- * panel receives. Each finding dropped for citing code outside the diff is reported by a
47
- * `finding:invalid` event, and each gap by an `incomplete` event. A research request its provider
48
- * refused as too large (a `too-large` `ProviderError`) was not sent: the profile reviews nothing,
49
- * records one `request-too-large` gap, and the other profiles run. For any other failed research,
50
- * the call after its retries or a reply that is not a valid envelope, a gating profile fails and
51
- * aborts the review where it fails (`onFailure` aborts it for the call), so no other profile starts
52
- * a call after it; an advisory profile's failure is its own `research-failed` gap, in words the code
53
- * writes, and the other profiles run. A research request a limit stopped (the token cap refused it or left
54
- * no room for it, or the review's deadline ended it) is no failure of either kind: the outcome holds no
55
- * finding and names the limit in `stopped`, which the review turns into the profile's one gap for that
56
- * limit, a gating profile's included.
78
+ * Turn the research replies of a profile, in the parts' order, into what the panel receives. Each reply is
79
+ * parsed strictly (a malformed envelope, or one with a key other than `findings`, throws, so it never reads
80
+ * as "no findings"), only the first `maxFindings` findings the replies list in all are read and checked
81
+ * against the diff, the earlier replies' first (the work spent on a reply built to flood the run stays
82
+ * bounded, whatever the entries hold), and nothing the harness read is dropped silently: a finding that
83
+ * does not match the reply schema (what planted text that closes a string early leaves behind), findings
84
+ * beyond the cap, counted over all the replies in one gap, and replies whose findings were all unusable,
85
+ * are recorded as incomplete, which fails the run (ADR-0012). A finding that cites code outside the diff,
86
+ * the whole diff of every part, is only dropped with its reason: it was read, and it is wrong. `invalid`
87
+ * holds only the reasons of the findings the check against the diff dropped, so an unreadable finding is
88
+ * reported once, in `incomplete`, with its reply's `label` before the reason when it has one. Every
89
+ * finding it keeps is named by `findingId` and tagged with `profile`, and every incomplete entry it
90
+ * records is tagged with `profile` too.
91
+ *
92
+ * @throws OutputError when a reply is not one JSON object holding a `findings` array and nothing else
93
+ * @throws RangeError when `maxFindings` is not a positive integer
94
+ */
95
+ export declare function checkReplies(replies: ReadonlyArray<{
96
+ readonly text: string;
97
+ readonly label?: string;
98
+ }>, sections: ReadonlyMap<string, string>, profile: string, maxFindings?: number): Omit<ResearchOutcome, 'parts'>;
99
+ /**
100
+ * The research stage of one profile, as `plan` lays it out: a change within one request is researched by one
101
+ * call to its research provider, with the profile's research instructions, the diff and the guidelines, and a
102
+ * large change is researched in parts, one call each, whose replies `checkReplies` turns into what the panel
103
+ * receives. Each finding dropped for citing code outside the diff is reported by a `finding:invalid` event,
104
+ * and each gap by an `incomplete` event.
105
+ *
106
+ * A change in one request (no packing, or a packing of one part, whose text is that part's) goes through
107
+ * one call. A research request its provider refused as too large (a `too-large` `ProviderError`) was not
108
+ * sent: the profile reviews nothing, records one `request-too-large` gap, and the other profiles run. For
109
+ * any other failed research, the call after its retries or a reply that is not a valid envelope, a gating
110
+ * profile fails and aborts the review where it fails (`onFailure` aborts it for the call), so no other
111
+ * profile starts a call after it; an advisory profile's failure is its own `research-failed` gap, in words
112
+ * the code writes, and the other profiles run. A research request a limit stopped (the token cap refused it
113
+ * or left no room for it, or the review's deadline ended it) is no failure of either kind: the outcome holds
114
+ * no finding and names the limit in `parts`, which the review turns into the profile's one gap for that
115
+ * limit, a gating profile's included. A packing of none, where no part holds any of the diff, makes no call, and
116
+ * neither does a part whose text is blank (white space only, as the text before a diff's first header can be,
117
+ * when every other unit was set aside): there is nothing to ask a model, so its outcome is `reviewed`.
118
+ *
119
+ * A packing of several parts runs `ctx.concurrency` workers of this profile, each taking the next part, in
120
+ * order, while one is left, and a call of each through the review's one limit, so the review's concurrency
121
+ * holds across profiles. Each part fails as a one-request research does, and a reply's envelope is checked
122
+ * as it arrives: a gating profile's failed call or unreadable envelope aborts the review where it fails, so
123
+ * no queued part starts and the review rejects with the first reason, and an advisory profile's is that
124
+ * part's `research-failed`, while its other parts go on. Once a part ends with a limit, the profile's parts
125
+ * not yet taken are stopped by the same limit without a call: each would be built and counted only to be
126
+ * refused, and the gap counts them, failing closed. Once every part has answered, the replies are read in
127
+ * the parts' order, up to `maxFindings` findings in all, each checked against the whole diff, and a finding
128
+ * two parts report is dropped by the dedup stage. The gaps come in this order, each counting parts: the
129
+ * requests refused as too large, then the parts that failed, then the reading's. The events follow: the
130
+ * `finding:invalid` ones, then the `incomplete` ones.
131
+ *
57
132
  * A review that is aborted rejects with its reason, never with a gap.
58
133
  *
59
134
  * @throws ProviderError, or whatever a custom provider throws, when a gating profile's research call fails for any other reason than a refusal as too large
60
135
  * @throws OutputError when a gating profile's reply is not one JSON object holding a `findings` array and nothing else
61
136
  */
62
- export declare function research(ctx: RunContext, run: ProfileRun, diff: string, sections: ReadonlyMap<string, string>): Promise<ResearchOutcome>;
137
+ export declare function research(ctx: RunContext, run: ProfileRun, plan: ResearchPlan, diff: string, sections: ReadonlyMap<string, string>): Promise<ResearchOutcome>;
138
+ export {};