@tobi-or-not/quorum 0.3.0 → 0.5.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 (91) hide show
  1. package/README.md +2 -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 +7 -4
  5. package/dist/bench/fingerprint.js +22 -8
  6. package/dist/bench/independence.d.ts +28 -0
  7. package/dist/bench/independence.js +67 -0
  8. package/dist/bench/records.d.ts +241 -13
  9. package/dist/bench/records.js +64 -11
  10. package/dist/bench/report.d.ts +44 -11
  11. package/dist/bench/report.js +238 -32
  12. package/dist/bench/run-dir.d.ts +52 -26
  13. package/dist/bench/run-dir.js +124 -45
  14. package/dist/bench/runner.d.ts +47 -17
  15. package/dist/bench/runner.js +82 -21
  16. package/dist/bench/score.d.ts +38 -7
  17. package/dist/bench/score.js +64 -17
  18. package/dist/bench/stats.d.ts +61 -7
  19. package/dist/bench/stats.js +82 -7
  20. package/dist/bench/suite.d.ts +54 -9
  21. package/dist/bench/suite.js +264 -96
  22. package/dist/cli/bench.d.ts +27 -9
  23. package/dist/cli/bench.js +174 -83
  24. package/dist/cli/bin.js +2 -2
  25. package/dist/cli/io.d.ts +9 -2
  26. package/dist/cli/io.js +20 -2
  27. package/dist/cli/main.d.ts +34 -14
  28. package/dist/cli/main.js +100 -38
  29. package/dist/cli/print-config.d.ts +8 -6
  30. package/dist/cli/print-config.js +21 -8
  31. package/dist/cli/render.d.ts +2 -2
  32. package/dist/cli/render.js +21 -2
  33. package/dist/config/env.d.ts +32 -19
  34. package/dist/config/env.js +95 -32
  35. package/dist/config/from-config.js +15 -3
  36. package/dist/config/load.d.ts +3 -0
  37. package/dist/config/load.js +17 -8
  38. package/dist/config/resolve.d.ts +9 -1
  39. package/dist/config/resolve.js +17 -1
  40. package/dist/config/schema.d.ts +141 -5
  41. package/dist/config/schema.js +125 -12
  42. package/dist/core/clock.d.ts +17 -0
  43. package/dist/core/clock.js +14 -0
  44. package/dist/core/coverage.d.ts +49 -0
  45. package/dist/core/coverage.js +144 -0
  46. package/dist/core/diff.d.ts +34 -0
  47. package/dist/core/diff.js +140 -18
  48. package/dist/core/errors.d.ts +18 -3
  49. package/dist/core/errors.js +26 -2
  50. package/dist/core/exclude.d.ts +42 -0
  51. package/dist/core/exclude.js +189 -0
  52. package/dist/core/limits.d.ts +82 -0
  53. package/dist/core/limits.js +163 -0
  54. package/dist/core/output.d.ts +3 -2
  55. package/dist/core/output.js +3 -2
  56. package/dist/core/ports.d.ts +57 -2
  57. package/dist/core/ports.js +36 -1
  58. package/dist/core/quorum.d.ts +24 -8
  59. package/dist/core/quorum.js +187 -56
  60. package/dist/core/retry.d.ts +36 -0
  61. package/dist/core/retry.js +46 -0
  62. package/dist/core/stages/context.d.ts +126 -22
  63. package/dist/core/stages/context.js +319 -41
  64. package/dist/core/stages/panel.d.ts +5 -4
  65. package/dist/core/stages/panel.js +30 -11
  66. package/dist/core/stages/research.d.ts +15 -6
  67. package/dist/core/stages/research.js +75 -18
  68. package/dist/core/tokens.d.ts +31 -0
  69. package/dist/core/tokens.js +81 -0
  70. package/dist/core/types.d.ts +77 -10
  71. package/dist/index.d.ts +1 -1
  72. package/dist/providers/anthropic.d.ts +2 -1
  73. package/dist/providers/anthropic.js +14 -6
  74. package/dist/providers/claude-code.d.ts +51 -11
  75. package/dist/providers/claude-code.js +69 -33
  76. package/dist/providers/gemini.d.ts +4 -1
  77. package/dist/providers/gemini.js +72 -15
  78. package/dist/providers/http.d.ts +49 -4
  79. package/dist/providers/http.js +155 -14
  80. package/dist/providers/ollama.d.ts +3 -1
  81. package/dist/providers/ollama.js +17 -9
  82. package/dist/providers/openai-compatible.d.ts +3 -1
  83. package/dist/providers/openai-compatible.js +17 -9
  84. package/dist/providers/options.d.ts +12 -3
  85. package/dist/providers/options.js +30 -10
  86. package/dist/providers/reply.d.ts +6 -2
  87. package/dist/providers/reply.js +13 -3
  88. package/dist/providers/size.d.ts +10 -14
  89. package/dist/providers/size.js +15 -69
  90. package/package.json +1 -1
  91. package/schema/quorum.schema.json +34 -1
@@ -1,5 +1,8 @@
1
1
  import { z } from 'zod';
2
2
  import { ConfigError, isSafeSegment, issuePath } from "../core/errors.js";
3
+ import { MAX_PATTERNS, patternProblem, TOO_MANY_PATTERNS } from "../core/exclude.js";
4
+ import { MAX_RETRIES, MAX_STATED_TIMEOUT_MS, MAX_TIMEOUT_MS, MIN_TIMEOUT_MS, retriesProblem, timeoutProblem } from "../core/ports.js";
5
+ import { ownData } from "../core/stages/context.js";
3
6
  import { securityProfile } from "../profiles/security.js";
4
7
  import { wordList } from "../providers/options.js";
5
8
  import { presets, withoutPrototype } from "../providers/presets.js";
@@ -19,6 +22,12 @@ const PROTOCOLS = {
19
22
  const STRUCTURED_OUTPUTS = { prompt: true, json: true, schema: true };
20
23
  const VERSION = 'must be 1, the only config version this quorum reads: upgrade quorum to read a later one';
21
24
  const name = z.string().regex(NAME);
25
+ /** A path pattern of `exclude`, refused in the words `createQuorum` uses, since both ask `patternProblem`. */
26
+ const pattern = z.string().check((ctx) => {
27
+ const problem = patternProblem(ctx.value);
28
+ if (problem !== undefined)
29
+ ctx.issues.push({ code: 'custom', message: problem, input: ctx.value });
30
+ });
22
31
  const roles = z.strictObject({
23
32
  research: name.optional().describe('The provider that looks for candidate findings'),
24
33
  voter: name.optional().describe('The provider every lens votes with, unless the lens names its own'),
@@ -51,9 +60,11 @@ const providerShape = {
51
60
  extraBody: z.record(z.string(), z.json()).optional().describe('JSON values deep-merged into the request body last'),
52
61
  structuredOutput: z.enum(Object.keys(STRUCTURED_OUTPUTS)).optional().describe('How the reply shape reaches the endpoint: described in the prompt, as a JSON object, or as a strict schema'),
53
62
  temperature: z.number().nullable().optional().describe('The sampling temperature; null leaves the field out'),
54
- maxTokens: z.int().min(1).optional().describe('The most tokens the reply may hold'),
63
+ maxTokens: z.int().min(1).optional().describe('The most tokens the reply may hold, thinking included, sent as the server\'s limit; 16000 when unset. On claude-code, Claude Code\'s own limit on each reply'),
55
64
  maxTokensField: z.enum(['max_tokens', 'max_completion_tokens']).optional().describe('The body field that carries maxTokens, on the openai-compatible protocol'),
56
65
  systemPrompt: z.enum(['native', 'inline']).optional().describe('Where the instructions go: the protocol\'s system field, or inline in the first message'),
66
+ timeoutMs: z.int().min(MIN_TIMEOUT_MS).max(MAX_TIMEOUT_MS).optional().describe('The deadline of one attempt of a call, in milliseconds; 600000 when unset. On claude-code, Claude Code\'s wait for each attempt\'s response headers, and the whole run\'s deadline is timeoutMs times retries plus one'),
67
+ retries: z.int().min(0).max(MAX_RETRIES).optional().describe('How many times a call that failed in passing is tried again; 2 when unset'),
57
68
  args: z.array(z.string()).optional().describe('On claude-code, extra claude flags, each with its value: --effort, --fallback-model, --max-budget-usd, or --betas with auth api-key'),
58
69
  };
59
70
  const prompt = z.union([
@@ -103,6 +114,9 @@ function configSchema(provider, promptForm) {
103
114
  roles: roles.optional().describe('The providers every profile uses, unless it names its own. research is required once several providers are defined; voter is research when unset'),
104
115
  concurrency: z.int().min(1).optional().describe('The most provider calls in flight at once in one review, shared by every profile'),
105
116
  maxFindings: z.int().min(1).optional().describe('The most findings of a research reply each profile reads, the only ones that can reach its panel'),
117
+ maxReviewTokens: z.int().min(1).optional().describe('The most tokens, input and output, one review may spend; 2000000 when unset. Set here or in QUORUM_MAX_REVIEW_TOKENS'),
118
+ reviewTimeoutMs: z.int().min(MIN_TIMEOUT_MS).max(MAX_TIMEOUT_MS).optional().describe('The deadline of one review, in milliseconds; 1800000 when unset. Set here or in QUORUM_REVIEW_TIMEOUT_MS'),
119
+ exclude: z.array(pattern.describe('A path pattern: * and ? within a name, ** for whole directories, no / to match a file name in any directory, a leading / for the root')).max(MAX_PATTERNS, { error: TOO_MANY_PATTERNS }).optional().describe('The files left out of every request, by path pattern, each listed as excluded in meta.leftOut; nothing is excluded by default'),
106
120
  profiles: z.record(name, profileSchema(promptForm)).optional().describe('The review profiles, by id: a built-in profile, one that extends it, or one of your own. The ones --profile names run, else the ones QUORUM_PROFILES names, else every one listed here, else the security profile alone'),
107
121
  });
108
122
  }
@@ -112,9 +126,54 @@ export function isProvider(value) {
112
126
  }
113
127
  /** The snapshots the schema made of provider objects, recognised by identity: a settings object is never taken for one, whatever its prototype holds. */
114
128
  const SNAPSHOTS = new WeakSet();
115
- /** A provider object as a snapshot: its fields as plain data, frozen, with no prototype. */
116
- function snapshot(fields) {
117
- const made = Object.freeze(withoutPrototype(Object.entries(fields)));
129
+ /** Each fact a provider states, with the check of its value: a deadline up to what a provider may state, which is more than an option takes. */
130
+ const FACTS = [
131
+ {
132
+ field: 'timeoutMs',
133
+ problem: value => timeoutProblem(value, MAX_STATED_TIMEOUT_MS),
134
+ },
135
+ { field: 'retries', problem: retriesProblem },
136
+ ];
137
+ /**
138
+ * The facts `provider` states, each read as own data, so a getter never runs and an inherited property
139
+ * or a proxy that throws states nothing: `stated` holds those that pass their check, and `problems` the
140
+ * field and wording of each that does not. A value is never quoted.
141
+ */
142
+ export function statedFacts(provider) {
143
+ // No prototype, so a reader of `stated` never finds a fact on `Object.prototype`.
144
+ const stated = Object.create(null);
145
+ const problems = [];
146
+ for (const { field, problem } of FACTS) {
147
+ const value = ownData(provider, field);
148
+ if (value === undefined)
149
+ continue;
150
+ const message = problem(value);
151
+ if (message === undefined)
152
+ stated[field] = value;
153
+ else
154
+ problems.push({ field, message });
155
+ }
156
+ return { stated, problems };
157
+ }
158
+ /**
159
+ * The `worstCase` a provider states, as own data: a function, else undefined. It is no fact of `FACTS`: a
160
+ * function is no number to check or to hash, so the fingerprint and the printed config never see it, and a
161
+ * value that is no function is an issue of `providerObject` and is never read here.
162
+ */
163
+ export function statedWorstCase(provider) {
164
+ const worstCase = ownData(provider, 'worstCase');
165
+ return typeof worstCase === 'function'
166
+ ? worstCase
167
+ : undefined;
168
+ }
169
+ /** A provider object as a snapshot: its fields as plain data, frozen, with no prototype. A `worstCase` it states is kept as a field, and one it does not state leaves no field. */
170
+ function snapshot({ worstCase, ...fields }) {
171
+ const made = Object.freeze(withoutPrototype(Object.entries({
172
+ ...fields,
173
+ ...worstCase === undefined
174
+ ? {}
175
+ : { worstCase },
176
+ })));
118
177
  SNAPSHOTS.add(made);
119
178
  return made;
120
179
  }
@@ -122,7 +181,11 @@ function snapshot(fields) {
122
181
  * The provider-object form of a code config's provider: an object whose `complete` is a function, read once
123
182
  * into a snapshot. The check reads `model` and `complete` one time each, and nothing reads the object again,
124
183
  * so a getter of the program's cannot run outside the guard that hides what it throws. The snapshot calls the
125
- * method read here on the object itself, through `Reflect.apply`, which reads nothing off the function.
184
+ * method read here on the object itself, through `Reflect.apply`, which reads nothing off the function. The
185
+ * `timeoutMs` and `retries` it states are read as own data, so no getter runs for them; the snapshot keeps
186
+ * each that is in range, and a value out of range is an issue at its field. The `worstCase` it states is read
187
+ * as own data too and kept as a function that calls it on the object, so the review's token cap counts
188
+ * what the object says one call may cost; a value that is no function is an issue at its field.
126
189
  */
127
190
  const providerObject = z.custom(value => typeof value === 'object' && value !== null).transform((object, ctx) => {
128
191
  const { model, complete } = object;
@@ -130,20 +193,55 @@ const providerObject = z.custom(value => typeof value === 'object' && value !==
130
193
  ctx.issues.push({ code: 'custom', message: 'complete is not a function', input: object });
131
194
  return z.NEVER;
132
195
  }
196
+ const { stated, problems } = statedFacts(object);
197
+ const worstCase = ownData(object, 'worstCase');
198
+ const issues = [
199
+ ...problems,
200
+ ...worstCase === undefined || typeof worstCase === 'function'
201
+ ? []
202
+ : [
203
+ { field: 'worstCase', message: 'must be a function' },
204
+ ],
205
+ ];
206
+ // `continue` keeps the union from setting this form aside as aborted: the object took its shape, so its issues are the ones reported.
207
+ for (const { field, message } of issues) {
208
+ ctx.issues.push({
209
+ code: 'custom',
210
+ message,
211
+ input: object,
212
+ path: [field],
213
+ continue: true,
214
+ });
215
+ }
216
+ if (issues.length > 0)
217
+ return z.NEVER;
133
218
  return snapshot({
134
219
  model,
135
220
  complete: request => Reflect.apply(complete, object, [request]),
221
+ ...stated,
222
+ ...typeof worstCase === 'function'
223
+ ? {
224
+ worstCase: (request) => Reflect.apply(worstCase, object, [request]),
225
+ }
226
+ : {},
136
227
  });
137
228
  });
138
229
  /**
139
230
  * `entry` named `id`, the config's key for it, when it is a snapshot the schema made of a provider object: a
140
- * copy that holds `id` as well, built from the snapshot's own data. Anything else is returned as it is.
231
+ * copy that holds `id` as well, built from the snapshot's own data, the facts and the `worstCase` it states
232
+ * included. Anything else is returned as it is.
141
233
  */
142
234
  export function nameSnapshot(id, entry) {
143
235
  if (typeof entry !== 'object' || entry === null || !SNAPSHOTS.has(entry))
144
236
  return entry;
145
237
  const { model, complete } = entry;
146
- return snapshot({ id, model, complete });
238
+ return snapshot({
239
+ id,
240
+ model,
241
+ complete,
242
+ ...statedFacts(entry).stated,
243
+ worstCase: statedWorstCase(entry),
244
+ });
147
245
  }
148
246
  /**
149
247
  * A YAML or JSON config: data only, so a provider names the variable that holds its key and never holds
@@ -151,14 +249,29 @@ export function nameSnapshot(id, entry) {
151
249
  * fill is optional, and the references between fields are checked once the layers are merged.
152
250
  */
153
251
  export const configFileSchema = configSchema(z.strictObject(providerShape), prompt);
252
+ /** The settings of a provider in a code config: those of a file, which may also hold the key itself and the executable. */
253
+ const codeSettings = z.strictObject({
254
+ ...providerShape,
255
+ apiKey: z.string().optional().describe('The key itself, which only a code config may hold'),
256
+ command: z.string().optional().describe('On claude-code, the claude executable: an absolute path, or a name found on PATH; only a code config may name it'),
257
+ });
258
+ /**
259
+ * Whether `value` may be the settings of a provider: anything but an object that holds a `complete`, unless
260
+ * that is plain data and no function, which the settings form reports as a field it does not know. An object
261
+ * that holds one is a provider object, read once, by `providerObject` alone; the settings form reads every
262
+ * field it knows through the object, a getter's included, so it is never offered one. Only the key and its
263
+ * descriptor are looked at here, so no getter of the object runs.
264
+ */
265
+ function isSettings(value) {
266
+ if (typeof value !== 'object' || value === null || !('complete' in value))
267
+ return true;
268
+ const descriptor = Object.getOwnPropertyDescriptor(value, 'complete');
269
+ return descriptor !== undefined && Object.hasOwn(descriptor, 'value') && typeof descriptor.value !== 'function';
270
+ }
154
271
  /** What a code config may hold as a provider: settings that may hold their key, or an object implementing `Provider`. */
155
272
  const codeProvider = z.union([
156
273
  providerObject,
157
- z.strictObject({
158
- ...providerShape,
159
- apiKey: z.string().optional().describe('The key itself, which only a code config may hold'),
160
- command: z.string().optional().describe('On claude-code, the claude executable: an absolute path, or a name found on PATH; only a code config may name it'),
161
- }),
274
+ z.custom(isSettings).pipe(codeSettings),
162
275
  ], { error: 'must be the settings of a provider, or an object whose complete is a function' });
163
276
  /** A TS or JS config: the file variant, where a provider may also hold its key, or be an object implementing `Provider`. */
164
277
  export const configCodeSchema = configSchema(codeProvider, prompt);
@@ -0,0 +1,17 @@
1
+ /**
2
+ * The time and the randomness the core reads, and the one timer it arms: the system's, unless a spec
3
+ * injects its own. The review holds it in its context and nothing outside the core sets it.
4
+ */
5
+ export interface Clock {
6
+ /** Milliseconds on a monotonic clock, from an origin of its own: only the difference of two readings means anything. */
7
+ readonly now: () => number;
8
+ /** A number from 0 up to, and not including, 1. */
9
+ readonly random: () => number;
10
+ /** Calls `fire` once, after `ms` milliseconds; returns the function that cancels it, which may be called at any time and any number of times. */
11
+ readonly timer: (ms: number, fire: () => void) => () => void;
12
+ }
13
+ /**
14
+ * The system's clock. Each reading goes through a function that reads the global at the call, never a
15
+ * reference taken when the module loads, so a spec that replaces `Math.random` is seen.
16
+ */
17
+ export declare const systemClock: Clock;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * The system's clock. Each reading goes through a function that reads the global at the call, never a
3
+ * reference taken when the module loads, so a spec that replaces `Math.random` is seen.
4
+ */
5
+ export const systemClock = Object.freeze({
6
+ now: () => performance.now(),
7
+ random: () => Math.random(),
8
+ timer: (ms, fire) => {
9
+ const handle = setTimeout(fire, ms);
10
+ return () => {
11
+ clearTimeout(handle);
12
+ };
13
+ },
14
+ });
@@ -0,0 +1,49 @@
1
+ import type { IncompleteEntry, LeftOutFile } from './types.ts';
2
+ /** What a review covers of a diff: the diff every stage reads, and the files it leaves out. */
3
+ export interface ReviewScope {
4
+ /** The diff every stage reads: the given one less the excluded sections. */
5
+ readonly diff: string;
6
+ /** The files left out, excluded or with a change the diff does not carry, in the diff's order, once per file and reason. */
7
+ readonly leftOut: LeftOutFile[];
8
+ }
9
+ /**
10
+ * What a review covers of a diff: the files `excluded` leaves out, and the files whose change the
11
+ * diff does not carry, found from the markers git prints in their place, each section read line by
12
+ * line (a trailing `\r` is dropped), so a Windows-made diff reads as any other. In each section:
13
+ * - a `binary` file shows as a line that starts with `Binary files ` and ends with ` differ`, or one
14
+ * that starts with `GIT binary patch`;
15
+ * - a `submodule` shows as a `Subproject commit` row (past at most one leading `+`, `-` or space), a
16
+ * header of mode 160000 (`new file mode`, `deleted file mode`, `old mode` and `new mode`), or an
17
+ * `index` line that ends in ` 160000`;
18
+ * - a `Submodule` line, which git's `log` and `diff` formats print in place of a header, at the end of
19
+ * the section before it, lists a `submodule` under the empty name, whatever section holds it.
20
+ *
21
+ * A file is listed by the diff's own path, decoded, in the diff's order, once per file and reason.
22
+ * `excluded` is asked once per distinct path a header names; a section it takes is listed as
23
+ * `excluded`, leaves the scope's `diff` and has its own markers left unread, but its `Submodule`
24
+ * lines still list their submodule, since such a line belongs to no section. Nothing a header does
25
+ * not name is ever excluded: the text before the first header, a diff without such headers and a
26
+ * header that names no path quorum reads.
27
+ *
28
+ * A header can read two ways: git does not quote a path that holds a space, so a rename's header
29
+ * (`a/src/auth.js b/src/x b/dist/auth.js`) can name a path the file does not have. A section is
30
+ * therefore excluded only when every `rename to` and `copy to` line it holds names the header's
31
+ * path, as `movedTo` reads them; otherwise it is kept, as a header quorum cannot read is, its markers
32
+ * read and its text sent. A forged line, such as a `format-patch` series carries in the next mail's
33
+ * message, can then only make quorum exclude less. That next mail's headers and message sit at the
34
+ * end of the previous file's section and leave with it when that file is excluded: no code hides
35
+ * there, since `git am` applies only the patch sections, and a `Submodule` line still counts.
36
+ *
37
+ * The empty name stands for a part of the diff that no `diff --git` header names: the text before the
38
+ * first header, a diff without such headers, a header that names no path quorum reads, and a
39
+ * `Submodule` line. A readable header never names the empty path, so it is never a file's.
40
+ *
41
+ * Detection is generous: a line of the same form elsewhere, such as a commit message line of a
42
+ * `format-patch` series, lists the file whose section holds it, since a gap it should not have stops a
43
+ * review for a person to look, where a missed one would pass a change unread. The scope's `diff` is
44
+ * the given string itself when no section was excluded, the kept sections joined by line feeds when
45
+ * some were, and '' when every section was.
46
+ */
47
+ export declare function reviewScope(diff: string, excluded?: (path: string) => boolean): ReviewScope;
48
+ /** The gaps the files left out make for one profile: one per reason, binary then submodule, counting its files, and none for a reason with no file. */
49
+ export declare function leftOutGaps(profile: string, leftOut: readonly LeftOutFile[]): IncompleteEntry[];
@@ -0,0 +1,144 @@
1
+ import { diffSections, movedTo } from "./diff.js";
2
+ const BINARY_FILES_START = 'Binary files ';
3
+ const BINARY_FILES_END = ' differ';
4
+ const BINARY_PATCH = 'GIT binary patch';
5
+ const SUBPROJECT_COMMIT = 'Subproject commit ';
6
+ const SUBMODULE_MODES = new Set([
7
+ 'new file mode 160000',
8
+ 'deleted file mode 160000',
9
+ 'old mode 160000',
10
+ 'new mode 160000',
11
+ ]);
12
+ const INDEX_START = 'index ';
13
+ const GITLINK_MODE_END = ' 160000';
14
+ /** The line git's `log` and `diff` submodule formats print in place of a header, at the end of the section before it. */
15
+ const SUBMODULE_LINE_START = 'Submodule ';
16
+ /** The characters a hunk row starts with, the only ones that can come before `Subproject commit`. */
17
+ const ROW_MARKERS = '+- ';
18
+ /** Whether `line` (less its `\r`) is a line of the section's own submodule. */
19
+ function isOwnSubmodule(line) {
20
+ return line.startsWith(SUBPROJECT_COMMIT)
21
+ || (line.startsWith(SUBPROJECT_COMMIT, 1) && ROW_MARKERS.includes(line[0]))
22
+ || SUBMODULE_MODES.has(line)
23
+ || (line.startsWith(INDEX_START) && line.endsWith(GITLINK_MODE_END));
24
+ }
25
+ /** The markers of one section, each line read on its own, with no hunk parsing, and at most one marker for a line: binary first, then the section's own submodule, then a `Submodule` line. */
26
+ function markersOf(text) {
27
+ const markers = { binary: false, submodule: false, submoduleLine: false };
28
+ for (const raw of text.split('\n')) {
29
+ const line = raw.endsWith('\r')
30
+ ? raw.slice(0, -1)
31
+ : raw;
32
+ if ((line.startsWith(BINARY_FILES_START) && line.endsWith(BINARY_FILES_END)) || line.startsWith(BINARY_PATCH))
33
+ markers.binary = true;
34
+ else if (isOwnSubmodule(line))
35
+ markers.submodule = true;
36
+ else if (line.startsWith(SUBMODULE_LINE_START))
37
+ markers.submoduleLine = true;
38
+ }
39
+ return markers;
40
+ }
41
+ /**
42
+ * What a review covers of a diff: the files `excluded` leaves out, and the files whose change the
43
+ * diff does not carry, found from the markers git prints in their place, each section read line by
44
+ * line (a trailing `\r` is dropped), so a Windows-made diff reads as any other. In each section:
45
+ * - a `binary` file shows as a line that starts with `Binary files ` and ends with ` differ`, or one
46
+ * that starts with `GIT binary patch`;
47
+ * - a `submodule` shows as a `Subproject commit` row (past at most one leading `+`, `-` or space), a
48
+ * header of mode 160000 (`new file mode`, `deleted file mode`, `old mode` and `new mode`), or an
49
+ * `index` line that ends in ` 160000`;
50
+ * - a `Submodule` line, which git's `log` and `diff` formats print in place of a header, at the end of
51
+ * the section before it, lists a `submodule` under the empty name, whatever section holds it.
52
+ *
53
+ * A file is listed by the diff's own path, decoded, in the diff's order, once per file and reason.
54
+ * `excluded` is asked once per distinct path a header names; a section it takes is listed as
55
+ * `excluded`, leaves the scope's `diff` and has its own markers left unread, but its `Submodule`
56
+ * lines still list their submodule, since such a line belongs to no section. Nothing a header does
57
+ * not name is ever excluded: the text before the first header, a diff without such headers and a
58
+ * header that names no path quorum reads.
59
+ *
60
+ * A header can read two ways: git does not quote a path that holds a space, so a rename's header
61
+ * (`a/src/auth.js b/src/x b/dist/auth.js`) can name a path the file does not have. A section is
62
+ * therefore excluded only when every `rename to` and `copy to` line it holds names the header's
63
+ * path, as `movedTo` reads them; otherwise it is kept, as a header quorum cannot read is, its markers
64
+ * read and its text sent. A forged line, such as a `format-patch` series carries in the next mail's
65
+ * message, can then only make quorum exclude less. That next mail's headers and message sit at the
66
+ * end of the previous file's section and leave with it when that file is excluded: no code hides
67
+ * there, since `git am` applies only the patch sections, and a `Submodule` line still counts.
68
+ *
69
+ * The empty name stands for a part of the diff that no `diff --git` header names: the text before the
70
+ * first header, a diff without such headers, a header that names no path quorum reads, and a
71
+ * `Submodule` line. A readable header never names the empty path, so it is never a file's.
72
+ *
73
+ * Detection is generous: a line of the same form elsewhere, such as a commit message line of a
74
+ * `format-patch` series, lists the file whose section holds it, since a gap it should not have stops a
75
+ * review for a person to look, where a missed one would pass a change unread. The scope's `diff` is
76
+ * the given string itself when no section was excluded, the kept sections joined by line feeds when
77
+ * some were, and '' when every section was.
78
+ */
79
+ export function reviewScope(diff, excluded = () => false) {
80
+ const leftOut = [];
81
+ const listed = {
82
+ excluded: new Set(),
83
+ binary: new Set(),
84
+ submodule: new Set(),
85
+ };
86
+ const list = (file, reason) => {
87
+ if (listed[reason].has(file))
88
+ return;
89
+ listed[reason].add(file);
90
+ leftOut.push({ file, reason });
91
+ };
92
+ const answers = new Map();
93
+ const isExcluded = (path) => {
94
+ let answer = answers.get(path);
95
+ if (answer === undefined) {
96
+ answer = excluded(path);
97
+ answers.set(path, answer);
98
+ }
99
+ return answer;
100
+ };
101
+ const sections = diffSections(diff);
102
+ const kept = [];
103
+ for (const { path, text } of sections) {
104
+ const markers = markersOf(text);
105
+ if (path !== undefined && path !== '' && isExcluded(path) && movedTo(text).every(moved => moved === path)) {
106
+ list(path, 'excluded');
107
+ }
108
+ else {
109
+ kept.push(text);
110
+ if (markers.binary)
111
+ list(path ?? '', 'binary');
112
+ if (markers.submodule)
113
+ list(path ?? '', 'submodule');
114
+ }
115
+ if (markers.submoduleLine)
116
+ list('', 'submodule');
117
+ }
118
+ return {
119
+ diff: kept.length === sections.length
120
+ ? diff
121
+ : kept.join('\n'),
122
+ leftOut,
123
+ };
124
+ }
125
+ /** How a gap's detail names what it counts. An excluded file is no gap, so `excluded` has no entry. */
126
+ const GAP_THINGS = {
127
+ binary: 'binary file(s)',
128
+ submodule: 'submodule(s)',
129
+ };
130
+ /** The gaps the files left out make for one profile: one per reason, binary then submodule, counting its files, and none for a reason with no file. */
131
+ export function leftOutGaps(profile, leftOut) {
132
+ return ['binary', 'submodule'].flatMap((reason) => {
133
+ const count = leftOut.filter(entry => entry.reason === reason).length;
134
+ return count === 0
135
+ ? []
136
+ : [
137
+ {
138
+ profile,
139
+ reason,
140
+ detail: `the diff carries no content for ${count} ${GAP_THINGS[reason]}, listed in meta.leftOut`,
141
+ },
142
+ ];
143
+ });
144
+ }
@@ -1,3 +1,27 @@
1
+ /**
2
+ * The paths the `rename to ` and `copy to ` lines of a section name, in order, each less a trailing
3
+ * `\r` and decoded when git quoted it. Git does not quote a path that holds a space, so a path with a
4
+ * space before `b/` makes a rename's `diff --git` header read two ways (`a/src/auth.js b/src/x
5
+ * b/dist/auth.js` reads as a rename to `dist/auth.js`), while these lines name the new path whole. A
6
+ * hunk row starts with a space, `+`, `-` or `\`, never with these words, so the section's lines are
7
+ * read with no hunk parsing.
8
+ */
9
+ export declare function movedTo(text: string): string[];
10
+ /** One section of a diff: the text from a `diff --git` header to the next, or the text before the first one. */
11
+ export interface DiffSection {
12
+ /** The path the header names; '' for the text before the first header or a diff without headers; undefined for a header that names no readable path. */
13
+ readonly path: string | undefined;
14
+ readonly text: string;
15
+ }
16
+ /**
17
+ * Every section of a git-style unified diff, in order. Only `diff --git` lines open a section, so the
18
+ * text before the first one is a section of its own, of path '', and a diff without such headers
19
+ * (plain `diff -u` output) is one section of path ''. A header that names no path quorum can read
20
+ * gives a section of path `undefined`, kept here whatever `splitDiff` does with it. A section holds
21
+ * at least one line, so a diff that starts with its header has no section before it, and the texts
22
+ * joined by line feeds are the diff.
23
+ */
24
+ export declare function diffSections(diff: string): DiffSection[];
1
25
  /**
2
26
  * Split a git-style unified diff into sections keyed by file path. Only `diff --git` lines open a
3
27
  * section: inside a hunk every line starts with ' ', '+', '-' or '\', so that text cannot appear
@@ -52,6 +76,16 @@ export interface FindingLocation {
52
76
  * hunk (`+c,0`) holds at `c`.
53
77
  */
54
78
  export declare function locate(sections: ReadonlyMap<string, string>, file: string, line: number): FindingLocation | undefined;
79
+ /**
80
+ * The first line from `start` to `end` that no hunk of `file` holds, or undefined when each sits in
81
+ * one: the answer `locate` gives for each line in turn, found by a binary search over the spans the
82
+ * hunks hold, merged and sorted once per section, so a range costs a search and not a walk over every
83
+ * hunk for each of its lines. The file is resolved as `locate` resolves it, and a file the diff does
84
+ * not hold has no line in a hunk, so the answer is `start`.
85
+ *
86
+ * @throws {RangeError} unless `start` and `end` are safe integers with `start` at most `end`
87
+ */
88
+ export declare function firstLineOutside(sections: ReadonlyMap<string, string>, file: string, start: number, end: number): number | undefined;
55
89
  /** A line the diff adds to the new file. */
56
90
  export interface AddedLine {
57
91
  /** The line's number in the new file. */