@tobi-or-not/quorum 0.2.0 → 0.4.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 (49) hide show
  1. package/README.md +3 -1
  2. package/dist/bench/attacks.d.ts +103 -0
  3. package/dist/bench/attacks.js +272 -0
  4. package/dist/bench/fingerprint.d.ts +37 -0
  5. package/dist/bench/fingerprint.js +80 -0
  6. package/dist/bench/independence.d.ts +28 -0
  7. package/dist/bench/independence.js +67 -0
  8. package/dist/bench/records.d.ts +220 -0
  9. package/dist/bench/records.js +184 -0
  10. package/dist/bench/report.d.ts +143 -0
  11. package/dist/bench/report.js +538 -0
  12. package/dist/bench/run-dir.d.ts +127 -0
  13. package/dist/bench/run-dir.js +458 -0
  14. package/dist/bench/runner.d.ts +92 -0
  15. package/dist/bench/runner.js +195 -0
  16. package/dist/bench/score.d.ts +61 -0
  17. package/dist/bench/score.js +85 -0
  18. package/dist/bench/stats.d.ts +105 -0
  19. package/dist/bench/stats.js +158 -0
  20. package/dist/bench/suite.d.ts +132 -0
  21. package/dist/bench/suite.js +454 -0
  22. package/dist/cli/bench.d.ts +43 -0
  23. package/dist/cli/bench.js +537 -0
  24. package/dist/cli/io.d.ts +52 -0
  25. package/dist/cli/io.js +63 -0
  26. package/dist/cli/main.d.ts +7 -37
  27. package/dist/cli/main.js +18 -85
  28. package/dist/cli/render.d.ts +10 -0
  29. package/dist/cli/render.js +20 -11
  30. package/dist/config/load.d.ts +46 -0
  31. package/dist/config/load.js +56 -14
  32. package/dist/core/diff.d.ts +20 -0
  33. package/dist/core/diff.js +102 -0
  34. package/dist/core/errors.d.ts +6 -0
  35. package/dist/core/errors.js +5 -0
  36. package/dist/core/prompts.d.ts +3 -1
  37. package/dist/core/prompts.js +8 -3
  38. package/dist/core/sanitize.d.ts +16 -1
  39. package/dist/core/sanitize.js +28 -4
  40. package/dist/core/stages/context.d.ts +12 -3
  41. package/dist/core/stages/context.js +23 -3
  42. package/dist/providers/anthropic.js +6 -3
  43. package/dist/providers/claude-code.js +11 -10
  44. package/dist/providers/gemini.js +9 -4
  45. package/dist/providers/ollama.js +6 -4
  46. package/dist/providers/openai-compatible.js +6 -4
  47. package/dist/providers/reply.d.ts +6 -2
  48. package/dist/providers/reply.js +13 -3
  49. package/package.json +2 -2
@@ -1,35 +1,8 @@
1
- import type { Env } from '../config/env.ts';
2
1
  import type { QuorumResult } from '../core/types.ts';
3
- /** Exit codes (ADR-0008, amended by ADR-0012). */
4
- export declare const EXIT: {
5
- readonly ok: 0;
6
- readonly finding: 1;
7
- readonly usage: 2;
8
- readonly runtime: 3;
9
- readonly incomplete: 4;
10
- readonly interrupted: 130;
11
- };
12
- /** The most diff the CLI reads, from stdin or a file, in bytes: a larger one is refused and reading stops there. */
13
- export declare const MAX_DIFF_BYTES: number;
14
- export interface CliIO {
15
- /** Arguments after the executable and script, e.g. `process.argv.slice(2)`. */
16
- argv: readonly string[];
17
- /** The directory a relative diff path and a relative `--config` resolve against, e.g. `process.cwd()`. */
18
- readonly cwd: string;
19
- /** Environment variables, e.g. `process.env`. */
20
- env: Env;
21
- stdin: AsyncIterable<Uint8Array | string> & {
22
- isTTY?: boolean;
23
- };
24
- stdout: {
25
- write: (text: string) => unknown;
26
- };
27
- stderr: {
28
- write: (text: string) => unknown;
29
- };
30
- /** The review's signal: once it is aborted, a run that ends without a result exits 130. */
31
- readonly signal?: AbortSignal;
32
- }
2
+ import { errorMessage, EXIT } from './io.ts';
3
+ import type { CliIO } from './io.ts';
4
+ export { errorMessage, EXIT };
5
+ export type { CliIO };
33
6
  /**
34
7
  * Run one review and return the process exit code. Never throws: usage and configuration problems
35
8
  * exit 2, runtime failures exit 3, an interrupt exits 130, and an incomplete review (a finding its
@@ -54,6 +27,9 @@ export interface CliIO {
54
27
  * The run is interrupted when `io.signal` aborts: it then writes `interrupted` and returns 130, whatever
55
28
  * error ended the review, and writes no result. A review that has already resolved is complete.
56
29
  *
30
+ * The one subcommand is `bench`: when the first argument is `bench`, the rest goes to `runBench` and its exit
31
+ * code is returned, before any review flag is read. A file named `bench` is reviewed as `quorum ./bench`.
32
+ *
57
33
  * Everything the CLI writes is inert (invariant I3): each stderr line passes through `inertLine`, and
58
34
  * the JSON result through `inertJson`.
59
35
  */
@@ -83,9 +59,3 @@ export declare function interruptSignal(source: SignalSource, exit: (code: numbe
83
59
  export declare function exitCodeFor(result: QuorumResult, options?: {
84
60
  readonly allowIncomplete?: boolean;
85
61
  }): number;
86
- /**
87
- * The text of a failure, for any value a promise can reject with: an `Error`'s message, else the
88
- * value's text form, else a fixed text when even that throws, as it does for an object without a
89
- * prototype. It never throws, so neither do the lines built from it.
90
- */
91
- export declare function errorMessage(error: unknown): string;
package/dist/cli/main.js CHANGED
@@ -1,28 +1,21 @@
1
1
  import { createReadStream } from 'node:fs';
2
2
  import { resolve } from 'node:path';
3
- import { parseArgs } from 'node:util';
4
3
  import packageJson from '../../package.json' with { type: 'json' };
5
4
  import { readEnv } from "../config/env.js";
6
5
  import { fromConfig } from "../config/from-config.js";
7
6
  import { loadConfig } from "../config/load.js";
7
+ import { decodeDiff } from "../core/diff.js";
8
8
  import { ConfigError } from "../core/errors.js";
9
9
  import { inertJson, inertLine } from "../core/sanitize.js";
10
+ import { runBench } from "./bench.js";
11
+ import { errorLines, errorMessage, EXIT, parseFlags } from "./io.js";
10
12
  import { printConfig } from "./print-config.js";
11
13
  import { bannerLines, progressSink } from "./render.js";
12
- /** Exit codes (ADR-0008, amended by ADR-0012). */
13
- export const EXIT = {
14
- ok: 0,
15
- finding: 1,
16
- usage: 2,
17
- runtime: 3,
18
- incomplete: 4,
19
- interrupted: 130,
20
- };
21
- /** The most diff the CLI reads, from stdin or a file, in bytes: a larger one is refused and reading stops there. */
22
- export const MAX_DIFF_BYTES = 16 * 1024 * 1024;
14
+ export { errorMessage, EXIT };
23
15
  const USAGE = [
24
16
  'Usage: quorum [options] [diff-file]',
25
17
  ' git diff | quorum [options]',
18
+ ' quorum bench [options] <suite>',
26
19
  '',
27
20
  'Options:',
28
21
  ' -c, --config <path> Read this config file, over QUORUM_CONFIG',
@@ -65,13 +58,18 @@ const OPTIONS = {
65
58
  * The run is interrupted when `io.signal` aborts: it then writes `interrupted` and returns 130, whatever
66
59
  * error ended the review, and writes no result. A review that has already resolved is complete.
67
60
  *
61
+ * The one subcommand is `bench`: when the first argument is `bench`, the rest goes to `runBench` and its exit
62
+ * code is returned, before any review flag is read. A file named `bench` is reviewed as `quorum ./bench`.
63
+ *
68
64
  * Everything the CLI writes is inert (invariant I3): each stderr line passes through `inertLine`, and
69
65
  * the JSON result through `inertJson`.
70
66
  */
71
67
  export async function runCli(io) {
68
+ if (io.argv[0] === 'bench')
69
+ return runBench(io, io.argv.slice(1));
72
70
  let flags;
73
71
  try {
74
- flags = parseFlags(io.argv);
72
+ flags = parseFlags(io.argv, OPTIONS);
75
73
  }
76
74
  catch (error) {
77
75
  return usageError(io, error);
@@ -189,22 +187,6 @@ export function exitCodeFor(result, options = {}) {
189
187
  ? EXIT.incomplete
190
188
  : EXIT.ok;
191
189
  }
192
- /** The flags of `argv` and its positional arguments; a usage error of `parseArgs` is raised as a `ConfigError`, one issue per line of its message. */
193
- function parseFlags(argv) {
194
- try {
195
- return parseArgs({
196
- args: [...argv],
197
- options: OPTIONS,
198
- strict: true,
199
- allowPositionals: true,
200
- });
201
- }
202
- catch (error) {
203
- if (!(error instanceof Error) || !error.code?.startsWith('ERR_PARSE_ARGS_'))
204
- throw error;
205
- throw new ConfigError(error.message.split('\n').map(message => ({ path: '', message })));
206
- }
207
- }
208
190
  /** Write a usage error and the usage, and return its exit code. */
209
191
  function usageError(io, error) {
210
192
  io.stderr.write(`${errorLines(error)}\n${USAGE}`);
@@ -215,61 +197,12 @@ async function readDiff(io, positionals) {
215
197
  const [path, ...extra] = positionals;
216
198
  if (extra.length > 0)
217
199
  throw new Error(`unexpected arguments: ${extra.join(' ')}`);
218
- if (path)
219
- return readCapped(createReadStream(resolve(io.cwd, path)));
220
- if (io.stdin.isTTY)
200
+ if (!path && io.stdin.isTTY)
221
201
  throw new Error('no diff given');
222
- return readCapped(io.stdin);
223
- }
224
- /**
225
- * Read `chunks` to the end as UTF-8 text, through one streaming decoder, so a leading byte-order mark
226
- * goes and a character split between two chunks stays whole, whatever the source. The bytes are
227
- * counted as they arrive: the chunk that takes the count past `MAX_DIFF_BYTES` throws, and leaving
228
- * the loop closes the stream, so no more is read.
229
- */
230
- async function readCapped(chunks) {
231
- const encoder = new TextEncoder();
232
- const decoder = new TextDecoder();
233
- let bytes = 0;
234
- let text = '';
235
- for await (const chunk of chunks) {
236
- const data = typeof chunk === 'string'
237
- ? encoder.encode(chunk)
238
- : chunk;
239
- bytes += data.byteLength;
240
- if (bytes > MAX_DIFF_BYTES)
241
- throw new Error('the diff is over 16 MiB, the most quorum reads');
242
- text += decoder.decode(data, { stream: true });
243
- }
244
- return text + decoder.decode();
245
- }
246
- /**
247
- * The `Error:` lines of a failure, each inert: a ConfigError's issues one per line, as its message
248
- * lists them, and any other failure's message on one line, so a line break in a file name or in text
249
- * a server sent cannot start a line of its own.
250
- */
251
- function errorLines(error) {
252
- const lines = error instanceof ConfigError
253
- ? error.message.split('\n')
254
- : [
255
- errorMessage(error),
256
- ];
257
- return lines.map((line, index) => inertLine(index === 0
258
- ? `Error: ${line}`
259
- : line)).join('\n');
260
- }
261
- /**
262
- * The text of a failure, for any value a promise can reject with: an `Error`'s message, else the
263
- * value's text form, else a fixed text when even that throws, as it does for an object without a
264
- * prototype. It never throws, so neither do the lines built from it.
265
- */
266
- export function errorMessage(error) {
267
- if (error instanceof Error)
268
- return error.message;
269
- try {
270
- return String(error);
271
- }
272
- catch {
273
- return 'an error with no text form';
274
- }
202
+ const diff = await decodeDiff(path
203
+ ? createReadStream(resolve(io.cwd, path))
204
+ : io.stdin);
205
+ if (diff === undefined)
206
+ throw new Error('the diff is over 16 MiB, the most quorum reads');
207
+ return diff;
275
208
  }
@@ -22,6 +22,16 @@ export declare function progressSink(write: (line: string) => void): EventSink;
22
22
  * polluted `Object.prototype` fills neither.
23
23
  */
24
24
  export declare function providerOrigin(spec: Exclude<ResolvedProvider, Provider>): string;
25
+ /**
26
+ * Who researches and who votes in each profile of a config, by profile in run order, as the banner names
27
+ * them: `<model> @ <origin>` for a provider (see `bannerLines`), the panel as one provider when every lens
28
+ * shares it, else each lens's. The labels are not yet inert: the caller makes each line it writes inert.
29
+ */
30
+ export declare function profileProviders(config: ResolvedConfig): Array<{
31
+ readonly profile: string;
32
+ readonly research: string;
33
+ readonly panel: string;
34
+ }>;
25
35
  /**
26
36
  * The lines a run prints before its progress: who researches and who votes, from the resolved config, as
27
37
  * `<model> @ <origin>` (a provider object as `<model> @ the provider object <name>`, a `claude-code`
@@ -87,14 +87,23 @@ function providerLabel(providers, name) {
87
87
  ? `${entry.model} @ the provider object ${name}`
88
88
  : `${own(entry, 'model')} @ ${endpointOf(entry)}`;
89
89
  }
90
- /** The banner of one profile: its research provider, then its panel, one provider for every lens when they share it. */
91
- function profileBanner({ research, voters }, providers) {
92
- const label = (name) => providerLabel(providers, name);
93
- const lenses = Object.entries(voters);
94
- const panel = new Set(lenses.map(([, name]) => name)).size === 1
95
- ? label(lenses[0][1])
96
- : lenses.map(([lens, name]) => `${lens} (${label(name)})`).join(', ');
97
- return [`Research (${label(research)})...`, `Panel will use ${panel}`];
90
+ /**
91
+ * Who researches and who votes in each profile of a config, by profile in run order, as the banner names
92
+ * them: `<model> @ <origin>` for a provider (see `bannerLines`), the panel as one provider when every lens
93
+ * shares it, else each lens's. The labels are not yet inert: the caller makes each line it writes inert.
94
+ */
95
+ export function profileProviders(config) {
96
+ const label = (name) => providerLabel(config.providers, name);
97
+ return config.profiles.map(({ profile, research, voters }) => {
98
+ const lenses = Object.entries(voters);
99
+ return {
100
+ profile: profile.id,
101
+ research: label(research),
102
+ panel: new Set(lenses.map(([, name]) => name)).size === 1
103
+ ? label(lenses[0][1])
104
+ : lenses.map(([lens, name]) => `${lens} (${label(name)})`).join(', '),
105
+ };
106
+ });
98
107
  }
99
108
  /**
100
109
  * The lines a run prints before its progress: who researches and who votes, from the resolved config, as
@@ -105,10 +114,10 @@ function profileBanner({ research, voters }, providers) {
105
114
  */
106
115
  export function bannerLines(config) {
107
116
  const prefixed = config.profiles.length > 1;
108
- return config.profiles.flatMap((resolved) => {
117
+ return profileProviders(config).flatMap(({ profile, research, panel }) => {
109
118
  const prefix = prefixed
110
- ? profilePrefix(resolved.profile.id)
119
+ ? profilePrefix(profile)
111
120
  : '';
112
- return profileBanner(resolved, config.providers).map(line => inertLine(`${prefix}${line}`));
121
+ return [`Research (${research})...`, `Panel will use ${panel}`].map(line => inertLine(`${prefix}${line}`));
113
122
  });
114
123
  }
@@ -1,4 +1,6 @@
1
+ import type { Stats } from 'node:fs';
1
2
  import type { z } from 'zod';
3
+ import type { ConfigIssue } from '../core/errors.ts';
2
4
  import type { Env } from './env.ts';
3
5
  import type { ProfileSelection } from './profiles.ts';
4
6
  import type { ResolvedConfig } from './resolve.ts';
@@ -10,6 +12,50 @@ export interface LoadedConfig {
10
12
  /** The absolute path of the file. */
11
13
  readonly source: string;
12
14
  }
15
+ /** What a read found, or the problem with the file, as an issue words it, and how many bytes the problem counts toward a total. */
16
+ export type Read<T> = {
17
+ readonly value: T;
18
+ } | {
19
+ readonly problem: string;
20
+ readonly counted?: number;
21
+ };
22
+ /** The `lstat` of a path, or the problem a failed one means by its code: the path is missing, or it cannot be read. */
23
+ export declare function lstatOf(absolute: string): Promise<Read<Stats>>;
24
+ /**
25
+ * The bytes of a regular file of at most `limit` bytes. The file is opened without blocking, so a FIFO
26
+ * is refused instead of waiting for a writer, and at most one byte past the limit is read, however large
27
+ * the file is or grows. The runtime's own message is never kept. A symbolic link is followed, unless
28
+ * `options.noFollow` is set: then a link is `is a symbolic link`, refused by an `lstat` before the open,
29
+ * and the open itself refuses one with `O_NOFOLLOW` where the platform has it, which closes the race
30
+ * between the two on Linux and macOS (without it, on Windows, a link swapped in after the `lstat` is
31
+ * followed).
32
+ */
33
+ export declare function readBounded(absolute: string, limit: number, size: string, options?: {
34
+ readonly noFollow?: boolean;
35
+ }): Promise<Read<Uint8Array>>;
36
+ /** The UTF-8 text of `bytes`, a leading byte-order mark dropped (the decoder's default). */
37
+ export declare function decode(bytes: Uint8Array): Read<string>;
38
+ /**
39
+ * One YAML 1.2 document of the core schema, as plain data. The schema is given explicitly, since a
40
+ * `%YAML 1.1` directive overrides the version alone (and 1.1 reads `off` as false); the YAML 1.1 tags
41
+ * are not resolved; any error, any warning (an unknown tag is only a warning to the parser), a key that
42
+ * repeats one of its mapping and any alias refuse the file; no problem carries source text.
43
+ */
44
+ export declare function parseYaml(text: string): Read<unknown>;
45
+ /** Whether `value` is an object of data: an object whose prototype is `Object.prototype` or none, never a class instance. */
46
+ export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
47
+ /**
48
+ * Every value of a config that is not plain data (an object of data, an array, a string, a finite
49
+ * number, a boolean or null), every own `__proto__` key, and every value more than `MAX_DEPTH` keys
50
+ * deep, each at its path after the file's. A record drops a `__proto__` key silently, and a later merge
51
+ * could turn one into a prototype change: it is refused here, before any schema reads the data.
52
+ * `constructor` and `prototype` stay allowed: they are valid names, and only `__proto__` runs a setter.
53
+ * Only a code config can hand over the rest: a provider object, which is not entered, and `undefined`,
54
+ * which leaves a field unset. Every value the walk visits counts, a provider object too, and past
55
+ * `MAX_VALUES` it stops and the config has that one issue, at the file: the schema never sees more data
56
+ * than that, and an object that refers to itself ends the walk instead of repeating it.
57
+ */
58
+ export declare function dataIssues(value: unknown, file: string | undefined): ConfigIssue[];
13
59
  /**
14
60
  * The plain object a config's code hands over, checked by `schema`: `read` returns it, then it must be a
15
61
  * plain object, hold plain data, and pass the schema, which reads each provider object it holds once into
@@ -7,7 +7,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
7
7
  return path;
8
8
  };
9
9
  import { constants } from 'node:fs';
10
- import { open } from 'node:fs/promises';
10
+ import { lstat, open } from 'node:fs/promises';
11
11
  import { dirname, extname, isAbsolute, resolve } from 'node:path';
12
12
  import { pathToFileURL } from 'node:url';
13
13
  import { isMap, isPair, isScalar, isSeq, LineCounter, parseDocument } from 'yaml';
@@ -43,24 +43,66 @@ function fail(path, message) {
43
43
  { path, message },
44
44
  ]);
45
45
  }
46
+ /** What an open that failed means, by its code: the runtime's own message is never kept. */
47
+ function openProblem(error, noFollow) {
48
+ const code = error.code;
49
+ if (code === 'ENOENT' || code === 'ENOTDIR')
50
+ return 'does not exist';
51
+ if (code === 'EISDIR')
52
+ return 'is not a file';
53
+ return code === 'ELOOP' && noFollow
54
+ ? 'is a symbolic link'
55
+ : 'cannot be read';
56
+ }
57
+ /** The `lstat` of a path, or the problem a failed one means by its code: the path is missing, or it cannot be read. */
58
+ export async function lstatOf(absolute) {
59
+ try {
60
+ return { value: await lstat(absolute) };
61
+ }
62
+ catch (error) {
63
+ const code = error.code;
64
+ return {
65
+ problem: code === 'ENOENT' || code === 'ENOTDIR'
66
+ ? 'does not exist'
67
+ : 'cannot be read',
68
+ };
69
+ }
70
+ }
71
+ /** The problem a path has before an open that must not follow a link: it is one, or it is missing or unreadable; undefined when it is not a link. */
72
+ async function linkProblem(absolute) {
73
+ const stats = await lstatOf(absolute);
74
+ if ('problem' in stats)
75
+ return stats.problem;
76
+ return stats.value.isSymbolicLink()
77
+ ? 'is a symbolic link'
78
+ : undefined;
79
+ }
46
80
  /**
47
81
  * The bytes of a regular file of at most `limit` bytes. The file is opened without blocking, so a FIFO
48
82
  * is refused instead of waiting for a writer, and at most one byte past the limit is read, however large
49
- * the file is or grows. The runtime's own message is never kept.
83
+ * the file is or grows. The runtime's own message is never kept. A symbolic link is followed, unless
84
+ * `options.noFollow` is set: then a link is `is a symbolic link`, refused by an `lstat` before the open,
85
+ * and the open itself refuses one with `O_NOFOLLOW` where the platform has it, which closes the race
86
+ * between the two on Linux and macOS (without it, on Windows, a link swapped in after the `lstat` is
87
+ * followed).
50
88
  */
51
- async function readBounded(absolute, limit, size) {
89
+ export async function readBounded(absolute, limit, size, options = {}) {
90
+ const noFollow = options.noFollow === true;
91
+ if (noFollow) {
92
+ const linked = await linkProblem(absolute);
93
+ if (linked !== undefined)
94
+ return { problem: linked };
95
+ }
96
+ const flags = noFollow && typeof constants.O_NOFOLLOW === 'number'
97
+ ? constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW
98
+ : constants.O_RDONLY | constants.O_NONBLOCK;
52
99
  let handle;
53
100
  try {
54
- handle = await open(absolute, constants.O_RDONLY | constants.O_NONBLOCK);
101
+ handle = await open(absolute, flags);
55
102
  }
56
103
  catch (error) {
57
- const code = error.code;
58
104
  return {
59
- problem: code === 'ENOENT' || code === 'ENOTDIR'
60
- ? 'does not exist'
61
- : code === 'EISDIR'
62
- ? 'is not a file'
63
- : 'cannot be read',
105
+ problem: openProblem(error, noFollow),
64
106
  };
65
107
  }
66
108
  try {
@@ -86,7 +128,7 @@ async function readBounded(absolute, limit, size) {
86
128
  }
87
129
  }
88
130
  /** The UTF-8 text of `bytes`, a leading byte-order mark dropped (the decoder's default). */
89
- function decode(bytes) {
131
+ export function decode(bytes) {
90
132
  try {
91
133
  return {
92
134
  value: new TextDecoder('utf-8', { fatal: true }).decode(bytes),
@@ -161,7 +203,7 @@ function repeatedKeyAt(doc) {
161
203
  * are not resolved; any error, any warning (an unknown tag is only a warning to the parser), a key that
162
204
  * repeats one of its mapping and any alias refuse the file; no problem carries source text.
163
205
  */
164
- function parseYaml(text) {
206
+ export function parseYaml(text) {
165
207
  const lines = new LineCounter();
166
208
  try {
167
209
  const doc = parseDocument(text, {
@@ -236,7 +278,7 @@ function parseJson(text) {
236
278
  }
237
279
  }
238
280
  /** Whether `value` is an object of data: an object whose prototype is `Object.prototype` or none, never a class instance. */
239
- function isPlainObject(value) {
281
+ export function isPlainObject(value) {
240
282
  if (typeof value !== 'object' || value === null || Array.isArray(value))
241
283
  return false;
242
284
  const prototype = Object.getPrototypeOf(value);
@@ -253,7 +295,7 @@ function isPlainObject(value) {
253
295
  * `MAX_VALUES` it stops and the config has that one issue, at the file: the schema never sees more data
254
296
  * than that, and an object that refers to itself ends the walk instead of repeating it.
255
297
  */
256
- function dataIssues(value, file) {
298
+ export function dataIssues(value, file) {
257
299
  const budget = { left: MAX_VALUES };
258
300
  const issues = valueIssues(value, [], file, 0, budget);
259
301
  return budget.left < 0
@@ -52,6 +52,16 @@ export interface FindingLocation {
52
52
  * hunk (`+c,0`) holds at `c`.
53
53
  */
54
54
  export declare function locate(sections: ReadonlyMap<string, string>, file: string, line: number): FindingLocation | undefined;
55
+ /**
56
+ * The first line from `start` to `end` that no hunk of `file` holds, or undefined when each sits in
57
+ * one: the answer `locate` gives for each line in turn, found by a binary search over the spans the
58
+ * hunks hold, merged and sorted once per section, so a range costs a search and not a walk over every
59
+ * hunk for each of its lines. The file is resolved as `locate` resolves it, and a file the diff does
60
+ * not hold has no line in a hunk, so the answer is `start`.
61
+ *
62
+ * @throws {RangeError} unless `start` and `end` are safe integers with `start` at most `end`
63
+ */
64
+ export declare function firstLineOutside(sections: ReadonlyMap<string, string>, file: string, start: number, end: number): number | undefined;
55
65
  /** A line the diff adds to the new file. */
56
66
  export interface AddedLine {
57
67
  /** The line's number in the new file. */
@@ -67,3 +77,13 @@ export interface AddedLine {
67
77
  * `format-patch` series.
68
78
  */
69
79
  export declare function addedLines(sections: ReadonlyMap<string, string>, path: string): AddedLine[];
80
+ /** The most diff quorum reads, from stdin, a file or a suite, in bytes: a larger one is refused and reading stops there. */
81
+ export declare const MAX_DIFF_BYTES: number;
82
+ /**
83
+ * Read `chunks` to the end as UTF-8 text, through one streaming decoder, so a leading byte-order mark
84
+ * goes and a character split between two chunks stays whole, whatever the source, and a byte that is
85
+ * not UTF-8 becomes the replacement character. The bytes are counted as they arrive: the chunk that
86
+ * takes the count past `maxBytes` ends the loop with `undefined`, which closes a stream, so no more
87
+ * is read.
88
+ */
89
+ export declare function decodeDiff(chunks: AsyncIterable<Uint8Array | string> | Iterable<Uint8Array | string>, maxBytes?: number): Promise<string | undefined>;
package/dist/core/diff.js CHANGED
@@ -271,6 +271,41 @@ export function locate(sections, file, line) {
271
271
  }
272
272
  return undefined;
273
273
  }
274
+ /**
275
+ * The first line from `start` to `end` that no hunk of `file` holds, or undefined when each sits in
276
+ * one: the answer `locate` gives for each line in turn, found by a binary search over the spans the
277
+ * hunks hold, merged and sorted once per section, so a range costs a search and not a walk over every
278
+ * hunk for each of its lines. The file is resolved as `locate` resolves it, and a file the diff does
279
+ * not hold has no line in a hunk, so the answer is `start`.
280
+ *
281
+ * @throws {RangeError} unless `start` and `end` are safe integers with `start` at most `end`
282
+ */
283
+ export function firstLineOutside(sections, file, start, end) {
284
+ if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start > end) {
285
+ throw new RangeError('start and end must be safe integers, start at most end');
286
+ }
287
+ const section = sectionFor(sections, file);
288
+ if (!section)
289
+ return start;
290
+ const spans = spansOf(sections, section.path, section.text);
291
+ let before = 0;
292
+ let after = spans.length;
293
+ while (before < after) {
294
+ const middle = (before + after) >>> 1;
295
+ if (spans[middle].start <= start)
296
+ before = middle + 1;
297
+ else
298
+ after = middle;
299
+ }
300
+ const span = before === 0
301
+ ? undefined
302
+ : spans[before - 1];
303
+ if (span === undefined || span.end < start)
304
+ return start;
305
+ return span.end >= end
306
+ ? undefined
307
+ : span.end + 1;
308
+ }
274
309
  /**
275
310
  * The lines the diff adds to `path`, in the order of the diff: the rows of its hunks marked `+`,
276
311
  * read from the hunks `locate` reads, so they are cached with them. `path` is the diff's own path,
@@ -315,6 +350,48 @@ function hunksOf(sections, path, text) {
315
350
  }
316
351
  return hunks;
317
352
  }
353
+ /** The merged spans of each section, built once, in a cache that is dropped with the sections map like `parsedSections`. */
354
+ const coveredSections = new WeakMap();
355
+ /** The new-file lines a hunk holds for `locate`: those it shows from its start, up to its count, or its start alone for a hunk that counts no new line; none for a hunk that shows no row. */
356
+ function heldSpan(hunk) {
357
+ if (hunk.rows.length === 0)
358
+ return undefined;
359
+ const shown = hunk.count === 0
360
+ ? 1
361
+ : Math.min(hunk.count, hunk.rowOfLine.length);
362
+ return shown === 0
363
+ ? undefined
364
+ : { start: hunk.start, end: hunk.start + shown - 1 };
365
+ }
366
+ /** The spans the hunks of a section hold, sorted by start, each merged with the one before it when it starts at most a line after that one's end, so no line between two spans is in either. */
367
+ function spansOf(sections, path, text) {
368
+ let covered = coveredSections.get(sections);
369
+ if (!covered) {
370
+ covered = new Map();
371
+ coveredSections.set(sections, covered);
372
+ }
373
+ let spans = covered.get(path);
374
+ if (!spans) {
375
+ const held = hunksOf(sections, path, text).flatMap(hunk => heldSpan(hunk) ?? []);
376
+ held.sort((first, second) => first.start - second.start);
377
+ const merged = [];
378
+ for (const span of held) {
379
+ const last = merged.at(-1);
380
+ if (last !== undefined && span.start <= last.end + 1) {
381
+ merged[merged.length - 1] = {
382
+ start: last.start,
383
+ end: Math.max(last.end, span.end),
384
+ };
385
+ }
386
+ else {
387
+ merged.push(span);
388
+ }
389
+ }
390
+ spans = merged;
391
+ covered.set(path, spans);
392
+ }
393
+ return spans;
394
+ }
318
395
  /**
319
396
  * Read the hunks of one file section. The header's line counts say where a hunk ends, so file
320
397
  * headers and `` markers are never mistaken for hunk lines, and a line
@@ -369,3 +446,28 @@ function parseHunks(section) {
369
446
  }
370
447
  return hunks;
371
448
  }
449
+ /** The most diff quorum reads, from stdin, a file or a suite, in bytes: a larger one is refused and reading stops there. */
450
+ export const MAX_DIFF_BYTES = 16 * 1024 * 1024;
451
+ /**
452
+ * Read `chunks` to the end as UTF-8 text, through one streaming decoder, so a leading byte-order mark
453
+ * goes and a character split between two chunks stays whole, whatever the source, and a byte that is
454
+ * not UTF-8 becomes the replacement character. The bytes are counted as they arrive: the chunk that
455
+ * takes the count past `maxBytes` ends the loop with `undefined`, which closes a stream, so no more
456
+ * is read.
457
+ */
458
+ export async function decodeDiff(chunks, maxBytes = MAX_DIFF_BYTES) {
459
+ const encoder = new TextEncoder();
460
+ const decoder = new TextDecoder();
461
+ let bytes = 0;
462
+ let text = '';
463
+ for await (const chunk of chunks) {
464
+ const data = typeof chunk === 'string'
465
+ ? encoder.encode(chunk)
466
+ : chunk;
467
+ bytes += data.byteLength;
468
+ if (bytes > maxBytes)
469
+ return undefined;
470
+ text += decoder.decode(data, { stream: true });
471
+ }
472
+ return text + decoder.decode();
473
+ }
@@ -1,3 +1,4 @@
1
+ import type { Usage } from './types.ts';
1
2
  /** Base class for every error quorum raises on purpose. */
2
3
  export declare class QuorumError extends Error {
3
4
  constructor(message: string, options?: ErrorOptions);
@@ -31,6 +32,8 @@ export type ProviderErrorKind = 'http' | 'network' | 'process' | 'timeout' | 'ab
31
32
  /**
32
33
  * A provider call that failed. The message starts with the provider id. Adapters never put request
33
34
  * headers, keys or the runtime's own error text in it; they quote server text through `snippet`.
35
+ * `usage` holds the counts of a reply the provider read and then refused, which the review counts as
36
+ * the failed call's usage.
34
37
  */
35
38
  export declare class ProviderError extends QuorumError {
36
39
  readonly providerId: string;
@@ -38,11 +41,14 @@ export declare class ProviderError extends QuorumError {
38
41
  readonly status: number | undefined;
39
42
  /** True for network errors, timeouts, 408, 409, 429 and 5xx; a caller may retry the call. */
40
43
  readonly retryable: boolean;
44
+ /** What the reply the call failed on reported, when the provider read one: the review counts it as the failed call's usage. */
45
+ readonly usage: Usage | undefined;
41
46
  constructor(details: {
42
47
  providerId: string;
43
48
  kind: ProviderErrorKind;
44
49
  message: string;
45
50
  status?: number;
51
+ usage?: Usage;
46
52
  cause?: unknown;
47
53
  });
48
54
  }
@@ -61,6 +61,8 @@ function isRetryable(kind, status) {
61
61
  /**
62
62
  * A provider call that failed. The message starts with the provider id. Adapters never put request
63
63
  * headers, keys or the runtime's own error text in it; they quote server text through `snippet`.
64
+ * `usage` holds the counts of a reply the provider read and then refused, which the review counts as
65
+ * the failed call's usage.
64
66
  */
65
67
  export class ProviderError extends QuorumError {
66
68
  providerId;
@@ -68,6 +70,8 @@ export class ProviderError extends QuorumError {
68
70
  status;
69
71
  /** True for network errors, timeouts, 408, 409, 429 and 5xx; a caller may retry the call. */
70
72
  retryable;
73
+ /** What the reply the call failed on reported, when the provider read one: the review counts it as the failed call's usage. */
74
+ usage;
71
75
  constructor(details) {
72
76
  super(`${details.providerId}: ${details.message}`, details.cause === undefined
73
77
  ? undefined
@@ -76,5 +80,6 @@ export class ProviderError extends QuorumError {
76
80
  this.kind = details.kind;
77
81
  this.status = details.status;
78
82
  this.retryable = isRetryable(details.kind, details.status);
83
+ this.usage = details.usage;
79
84
  }
80
85
  }
@@ -36,6 +36,8 @@ export declare function researchRequest(instructions: string, diff: string, guid
36
36
  * vote ever reaches it (blind voting, ADR-0006). The evidence is code read from the diff by the
37
37
  * harness; the finder's summary is the only text a model wrote, and it is fenced as an unverified
38
38
  * 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.
39
+ * the message as in a research call. The system message names each block the request carries. The
40
+ * cited file name's hidden characters show as `<U+XXXX>` (git's quoting decodes to any character, a
41
+ * line break included), so the claim stays two lines.
40
42
  */
41
43
  export declare function voteRequest(instructions: string, finding: Finding, diffContext: string, guidelines?: string): CompletionRequest;