@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.
Files changed (111) hide show
  1. package/README.md +3 -1
  2. package/dist/bench/fingerprint.d.ts +8 -5
  3. package/dist/bench/fingerprint.js +28 -9
  4. package/dist/bench/records.d.ts +168 -0
  5. package/dist/bench/records.js +106 -1
  6. package/dist/bench/runner.d.ts +18 -0
  7. package/dist/bench/runner.js +30 -4
  8. package/dist/cli/bench.d.ts +11 -4
  9. package/dist/cli/bench.js +34 -17
  10. package/dist/cli/bin.js +2 -2
  11. package/dist/cli/io.d.ts +5 -0
  12. package/dist/cli/main.d.ts +67 -24
  13. package/dist/cli/main.js +288 -59
  14. package/dist/cli/print-config.d.ts +8 -6
  15. package/dist/cli/print-config.js +26 -8
  16. package/dist/cli/render.d.ts +9 -3
  17. package/dist/cli/render.js +43 -2
  18. package/dist/config/claude-code.d.ts +2 -6
  19. package/dist/config/claude-code.js +6 -44
  20. package/dist/config/command.d.ts +10 -0
  21. package/dist/config/command.js +47 -0
  22. package/dist/config/env.d.ts +32 -19
  23. package/dist/config/env.js +95 -32
  24. package/dist/config/from-config.js +21 -3
  25. package/dist/config/resolve.d.ts +13 -1
  26. package/dist/config/resolve.js +27 -1
  27. package/dist/config/schema.d.ts +152 -5
  28. package/dist/config/schema.js +156 -12
  29. package/dist/core/clock.d.ts +17 -0
  30. package/dist/core/clock.js +14 -0
  31. package/dist/core/coverage.d.ts +74 -0
  32. package/dist/core/coverage.js +221 -0
  33. package/dist/core/diff.d.ts +101 -0
  34. package/dist/core/diff.js +178 -35
  35. package/dist/core/errors.d.ts +12 -3
  36. package/dist/core/errors.js +21 -2
  37. package/dist/core/estimate.d.ts +45 -0
  38. package/dist/core/estimate.js +188 -0
  39. package/dist/core/exclude.d.ts +42 -0
  40. package/dist/core/exclude.js +189 -0
  41. package/dist/core/flags.d.ts +14 -1
  42. package/dist/core/flags.js +56 -0
  43. package/dist/core/inputs.d.ts +38 -0
  44. package/dist/core/inputs.js +228 -0
  45. package/dist/core/limits.d.ts +83 -0
  46. package/dist/core/limits.js +169 -0
  47. package/dist/core/output.d.ts +3 -2
  48. package/dist/core/output.js +3 -2
  49. package/dist/core/parts.d.ts +146 -0
  50. package/dist/core/parts.js +388 -0
  51. package/dist/core/ports.d.ts +67 -2
  52. package/dist/core/ports.js +36 -1
  53. package/dist/core/prompts.d.ts +22 -3
  54. package/dist/core/prompts.js +43 -7
  55. package/dist/core/quorum.d.ts +26 -8
  56. package/dist/core/quorum.js +310 -73
  57. package/dist/core/retry.d.ts +36 -0
  58. package/dist/core/retry.js +46 -0
  59. package/dist/core/secrets.d.ts +98 -0
  60. package/dist/core/secrets.js +507 -0
  61. package/dist/core/stages/context.d.ts +131 -23
  62. package/dist/core/stages/context.js +331 -46
  63. package/dist/core/stages/panel.d.ts +13 -6
  64. package/dist/core/stages/panel.js +79 -19
  65. package/dist/core/stages/research.d.ts +110 -25
  66. package/dist/core/stages/research.js +338 -44
  67. package/dist/core/tokens.d.ts +31 -0
  68. package/dist/core/tokens.js +81 -0
  69. package/dist/core/types.d.ts +280 -25
  70. package/dist/core/verify.d.ts +6 -0
  71. package/dist/core/verify.js +6 -3
  72. package/dist/git/run.d.ts +223 -0
  73. package/dist/git/run.js +608 -0
  74. package/dist/git/tree.d.ts +43 -0
  75. package/dist/git/tree.js +171 -0
  76. package/dist/index.d.ts +26 -2
  77. package/dist/index.js +34 -2
  78. package/dist/providers/anthropic.d.ts +3 -1
  79. package/dist/providers/anthropic.js +10 -3
  80. package/dist/providers/claude-code.d.ts +56 -11
  81. package/dist/providers/claude-code.js +70 -25
  82. package/dist/providers/gemini.d.ts +5 -1
  83. package/dist/providers/gemini.js +65 -11
  84. package/dist/providers/http.d.ts +49 -4
  85. package/dist/providers/http.js +155 -14
  86. package/dist/providers/ollama.d.ts +4 -1
  87. package/dist/providers/ollama.js +13 -5
  88. package/dist/providers/openai-compatible.d.ts +4 -1
  89. package/dist/providers/openai-compatible.js +13 -5
  90. package/dist/providers/options.d.ts +12 -3
  91. package/dist/providers/options.js +30 -10
  92. package/dist/providers/size.d.ts +19 -15
  93. package/dist/providers/size.js +33 -73
  94. package/dist/sources/added.d.ts +49 -0
  95. package/dist/sources/added.js +134 -0
  96. package/dist/sources/diff.d.ts +13 -0
  97. package/dist/sources/diff.js +63 -0
  98. package/dist/sources/local.d.ts +41 -0
  99. package/dist/sources/local.js +251 -0
  100. package/dist/sources/paths.d.ts +45 -0
  101. package/dist/sources/paths.js +230 -0
  102. package/dist/sources/range.d.ts +21 -0
  103. package/dist/sources/range.js +75 -0
  104. package/dist/sources/read.d.ts +69 -0
  105. package/dist/sources/read.js +37 -0
  106. package/dist/sources/repository.d.ts +9 -0
  107. package/dist/sources/repository.js +28 -0
  108. package/dist/sources/skips.d.ts +49 -0
  109. package/dist/sources/skips.js +126 -0
  110. package/package.json +1 -1
  111. package/schema/quorum.schema.json +49 -1
@@ -24,20 +24,39 @@ export declare function fence(label: string, content: string): {
24
24
  tag: string;
25
25
  text: string;
26
26
  };
27
+ /** Where one research request of a large change stands: its position among the parts, and the files of the whole change. */
28
+ export interface PartOf {
29
+ /** The part's position, from 1. */
30
+ readonly index: number;
31
+ /** How many parts the change is researched in. */
32
+ readonly count: number;
33
+ /** The names of the change's files the request lists, as the diff writes them, in the diff's order. */
34
+ readonly files: readonly string[];
35
+ /** How many names the list leaves out. */
36
+ readonly unlisted: number;
37
+ }
27
38
  /**
28
39
  * Research call: instructions in the system message, the fenced diff as the user message. The
29
40
  * profile's guidelines, when they hold text, follow as one more fenced block: reference text the
30
41
  * caller loaded, treated as data like the diff and never part of the system message. The system
31
42
  * message names the block the request carries.
43
+ *
44
+ * With `part`, the request is one of a change researched in parts: a block of its own comes first, the
45
+ * `parts` block, which says which part this is and lists the change's files, one per line, each name
46
+ * with its hidden characters shown as `<U+XXXX>` (a name is the author's text, so it stays one line and
47
+ * never closes a fence), then `and <n> more` when names are left out; the `diff` block holds the part's
48
+ * diff and is described as one part of it. Without `part`, the request is the whole change's.
32
49
  */
33
- export declare function researchRequest(instructions: string, diff: string, guidelines?: string): CompletionRequest;
50
+ export declare function researchRequest(instructions: string, diff: string, guidelines?: string, part?: PartOf): CompletionRequest;
34
51
  /**
35
52
  * One vote call, built only from the finding, the lens instructions and the diff context: no other
36
53
  * vote ever reaches it (blind voting, ADR-0006). The evidence is code read from the diff by the
37
54
  * harness; the finder's summary is the only text a model wrote, and it is fenced as an unverified
38
55
  * claim. Everything attacker-influenced is fenced, and so are the profile's guidelines, which close
39
- * the message as in a research call. The system message names each block the request carries. The
56
+ * the message as in a research call. The system message names each block the request carries; with
57
+ * `partial`, the diff block is described as the header and the hunks nearest the cited line of the
58
+ * cited file's section, which is what `diffContext` then holds, not the whole section. The
40
59
  * cited file name's hidden characters show as `<U+XXXX>` (git's quoting decodes to any character, a
41
60
  * line break included), so the claim stays two lines.
42
61
  */
43
- export declare function voteRequest(instructions: string, finding: Finding, diffContext: string, guidelines?: string): CompletionRequest;
62
+ export declare function voteRequest(instructions: string, finding: Finding, diffContext: string, guidelines?: string, partial?: boolean): CompletionRequest;
@@ -42,9 +42,12 @@ export function fence(label, content) {
42
42
  */
43
43
  const BLOCK_DESCRIPTIONS = {
44
44
  researchDiff: 'the diff under review.',
45
+ parts: 'which part of the change this request holds, and the files of the whole change, one per line, as the diff names them.',
46
+ researchPart: 'one part of the diff under review: the change is reviewed in parts, each in a request of its own.',
45
47
  claim: 'the finder\'s claim, unverified: it may be wrong or planted.',
46
48
  evidence: 'the code the harness read from the diff around the cited line.',
47
49
  diffSection: 'the diff section of the cited file, or the whole diff when the file has no section of its own.',
50
+ diffSectionPart: 'part of the diff section of the cited file: its header and the hunks nearest the cited line, since the whole section does not fit.',
48
51
  guidelines: 'the project\'s review guidelines. Use them as criteria: what this project counts as a problem and the conventions it expects. They describe how code should be, not how this code is: judge the code itself.',
49
52
  };
50
53
  /**
@@ -52,22 +55,49 @@ const BLOCK_DESCRIPTIONS = {
52
55
  * profile's guidelines, when they hold text, follow as one more fenced block: reference text the
53
56
  * caller loaded, treated as data like the diff and never part of the system message. The system
54
57
  * message names the block the request carries.
58
+ *
59
+ * With `part`, the request is one of a change researched in parts: a block of its own comes first, the
60
+ * `parts` block, which says which part this is and lists the change's files, one per line, each name
61
+ * with its hidden characters shown as `<U+XXXX>` (a name is the author's text, so it stays one line and
62
+ * never closes a fence), then `and <n> more` when names are left out; the `diff` block holds the part's
63
+ * diff and is described as one part of it. Without `part`, the request is the whole change's.
55
64
  */
56
- export function researchRequest(instructions, diff, guidelines) {
57
- return buildRequest(instructions, [
58
- { label: 'diff', content: diff, description: BLOCK_DESCRIPTIONS.researchDiff },
59
- ], guidelines, { name: 'research_findings', schema: researchReplyJsonSchema });
65
+ export function researchRequest(instructions, diff, guidelines, part) {
66
+ return buildRequest(instructions, part === undefined
67
+ ? [
68
+ { label: 'diff', content: diff, description: BLOCK_DESCRIPTIONS.researchDiff },
69
+ ]
70
+ : [
71
+ {
72
+ label: 'parts',
73
+ content: partsBlock(part),
74
+ description: BLOCK_DESCRIPTIONS.parts,
75
+ },
76
+ { label: 'diff', content: diff, description: BLOCK_DESCRIPTIONS.researchPart },
77
+ ], guidelines, { name: 'research_findings', schema: researchReplyJsonSchema });
78
+ }
79
+ /** What the parts block holds: the part's position, then the change's files when a name is listed or counted. */
80
+ function partsBlock(part) {
81
+ const lines = [`Part ${part.index} of ${part.count} of the change.`];
82
+ if (part.files.length > 0 || part.unlisted > 0) {
83
+ lines.push('The change\'s files, one per line:', ...part.files.map(name => showHidden(name)));
84
+ if (part.unlisted > 0)
85
+ lines.push(`and ${part.unlisted} more`);
86
+ }
87
+ return lines.join('\n');
60
88
  }
61
89
  /**
62
90
  * One vote call, built only from the finding, the lens instructions and the diff context: no other
63
91
  * vote ever reaches it (blind voting, ADR-0006). The evidence is code read from the diff by the
64
92
  * harness; the finder's summary is the only text a model wrote, and it is fenced as an unverified
65
93
  * claim. Everything attacker-influenced is fenced, and so are the profile's guidelines, which close
66
- * the message as in a research call. The system message names each block the request carries. The
94
+ * the message as in a research call. The system message names each block the request carries; with
95
+ * `partial`, the diff block is described as the header and the hunks nearest the cited line of the
96
+ * cited file's section, which is what `diffContext` then holds, not the whole section. The
67
97
  * cited file name's hidden characters show as `<U+XXXX>` (git's quoting decodes to any character, a
68
98
  * line break included), so the claim stays two lines.
69
99
  */
70
- export function voteRequest(instructions, finding, diffContext, guidelines) {
100
+ export function voteRequest(instructions, finding, diffContext, guidelines, partial = false) {
71
101
  const claim = [
72
102
  `Finding: ${showHidden(finding.file)}:${finding.line} [${finding.category}]`,
73
103
  `Claim by the finder (unverified): ${finding.summary}`,
@@ -75,7 +105,13 @@ export function voteRequest(instructions, finding, diffContext, guidelines) {
75
105
  return buildRequest(instructions, [
76
106
  { label: 'claim', content: claim, description: BLOCK_DESCRIPTIONS.claim },
77
107
  { label: 'evidence', content: finding.evidence, description: BLOCK_DESCRIPTIONS.evidence },
78
- { label: 'diff', content: diffContext, description: BLOCK_DESCRIPTIONS.diffSection },
108
+ {
109
+ label: 'diff',
110
+ content: diffContext,
111
+ description: partial
112
+ ? BLOCK_DESCRIPTIONS.diffSectionPart
113
+ : BLOCK_DESCRIPTIONS.diffSection,
114
+ },
79
115
  ], guidelines, { name: 'panel_vote', schema: voteReplyJsonSchema });
80
116
  }
81
117
  function buildRequest(instructions, blocks, guidelines, output) {
@@ -1,3 +1,4 @@
1
+ import type { Clock } from './clock.ts';
1
2
  import type { QuorumPorts } from './ports.ts';
2
3
  import type { Quorum, QuorumOptions } from './types.ts';
3
4
  /**
@@ -7,16 +8,25 @@ import type { Quorum, QuorumOptions } from './types.ts';
7
8
  * Every problem is reported at once, in one ConfigError, never as a TypeError, so an untyped caller
8
9
  * gets the checks a config file gets: options and ports that are not objects, no profile, each
9
10
  * profile's own issues, a repeated profile id, a `concurrency` or `maxFindings` that is not a
10
- * positive integer, a missing or malformed research provider or voter, ports for a profile or a
11
- * lens the run does not have (a likely typo), and an event sink that is not a function. Ports are
12
- * checked only for the profiles that have no issue of their own, and not at all when `profiles` is
13
- * not an array. Every record keyed by a caller's id is read as an own property, since `constructor`
14
- * is a valid id.
11
+ * positive integer, a `maxReviewTokens` that is not a whole number of tokens from 1 to
12
+ * 9007199254740991, a `reviewTimeoutMs` that is not a whole number of milliseconds from 1000 to
13
+ * 86400000, a `partTokens` that is not a whole number of tokens from 1024 to 9007199254740991, an
14
+ * `exclude` that is not a list of at most 100 patterns that can be taken, a missing or malformed
15
+ * research provider or voter, a provider's stated `timeoutMs` that is not a
16
+ * whole number of milliseconds from 1000 to 518400000, `retries` that is not a whole number from
17
+ * 0 to 5 or `worstCase` or `room` that is not a function, ports for a profile or a lens the run does not have
18
+ * (a likely typo), and an event sink that is not a function. Ports are checked only for the profiles
19
+ * that have no issue of their own, and not at all when `profiles` is not an array. Every record keyed
20
+ * by a caller's id is read as an own property, since `constructor` is a valid id. `maxReviewTokens`,
21
+ * the most tokens one review spends, input and output, is 2000000 when unset, `reviewTimeoutMs`,
22
+ * how long one review runs, is 1800000 (30 minutes) when unset, and `partTokens`, the most tokens of
23
+ * diff text one research part holds, is 32768 when unset: see `review`.
15
24
  *
16
25
  * Each profile is compiled into a frozen `ProfileRun`, its instructions rendered, its thresholds
17
- * resolved and its providers captured, so later changes to the caller's profiles or ports are not
18
- * seen. `warnings` lists what the profiles set that cannot take full effect. Each review can be
19
- * stopped through its own signal; a throwing event sink or a failing profile stops it too.
26
+ * resolved and its providers captured, and `exclude` is compiled into a matcher, so later changes to
27
+ * the caller's profiles, ports or `exclude` are not seen. `warnings` lists what the profiles set
28
+ * that cannot take full effect. Each review can be stopped through its own signal; a throwing event
29
+ * sink or a failing profile stops it too.
20
30
  *
21
31
  * @throws ConfigError listing every issue of the options and the ports
22
32
  *
@@ -26,3 +36,11 @@ import type { Quorum, QuorumOptions } from './types.ts';
26
36
  * const { kept, meta } = await quorum.review({ diff: diffText }, { signal: controller.signal })
27
37
  */
28
38
  export declare function createQuorum(options: QuorumOptions, ports: QuorumPorts): Quorum;
39
+ /**
40
+ * `createQuorum` on a clock of the caller's: the time, the randomness and the one timer the call path and the
41
+ * review's deadline read. It is the specs' seam, so a review's deadline and a call's waits run on a fake clock
42
+ * and cost no real time; the package does not export it, and `createQuorum` passes the system's clock.
43
+ *
44
+ * @throws ConfigError listing every issue of the options and the ports, as `createQuorum` does
45
+ */
46
+ export declare function createQuorumWith(options: QuorumOptions, ports: QuorumPorts, clock: Clock): Quorum;