@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
@@ -3,7 +3,7 @@ import { createQuorum } from "../core/quorum.js";
3
3
  import { buildProvider } from "../providers/build.js";
4
4
  import { checkCodeValue } from "./load.js";
5
5
  import { isResolvedConfig, resolveConfig } from "./resolve.js";
6
- import { configInputSchema, configPath, isProvider, statedFacts, statedWorstCase } from "./schema.js";
6
+ import { configInputSchema, configPath, isProvider, statedFacts, statedRoom, statedWorstCase } from "./schema.js";
7
7
  /** A provider the config defines as data, built by the builder: its issues name the provider where the config defines it. */
8
8
  function fromSpec(name, spec, env) {
9
9
  try {
@@ -20,7 +20,7 @@ function fromSpec(name, spec, env) {
20
20
  };
21
21
  }
22
22
  }
23
- /** A provider object of the config, which the check read once into a snapshot, under the name the config gives it, with the `timeoutMs`, `retries` and `worstCase` the snapshot holds. */
23
+ /** A provider object of the config, which the check read once into a snapshot, under the name the config gives it, with the `timeoutMs`, `retries`, `worstCase` and `room` the snapshot holds. */
24
24
  function fromObject(name, snapshot) {
25
25
  const { model, complete } = snapshot;
26
26
  if (typeof model !== 'string') {
@@ -34,6 +34,7 @@ function fromObject(name, snapshot) {
34
34
  };
35
35
  }
36
36
  const worstCase = statedWorstCase(snapshot);
37
+ const room = statedRoom(snapshot);
37
38
  return {
38
39
  provider: {
39
40
  id: name,
@@ -43,6 +44,9 @@ function fromObject(name, snapshot) {
43
44
  ...worstCase === undefined
44
45
  ? {}
45
46
  : { worstCase },
47
+ ...room === undefined
48
+ ? {}
49
+ : { room },
46
50
  },
47
51
  issues: [],
48
52
  };
@@ -100,12 +104,14 @@ export async function fromConfig(config, options = {}) {
100
104
  profiles: resolved.profiles.map(({ profile }) => profile),
101
105
  concurrency: resolved.concurrency,
102
106
  maxFindings: resolved.maxFindings,
107
+ partTokens: resolved.partTokens,
103
108
  maxReviewTokens: resolved.maxReviewTokens,
104
109
  reviewTimeoutMs: resolved.reviewTimeoutMs,
105
110
  exclude: resolved.exclude,
106
111
  }, { profiles: ports, events: options.events });
107
112
  return Object.freeze({
108
113
  review: quorum.review,
114
+ estimate: quorum.estimate,
109
115
  warnings: Object.freeze([
110
116
  ...resolved.warnings,
111
117
  ...quorum.warnings,
@@ -15,12 +15,16 @@ export interface ResolvedConfig {
15
15
  readonly profiles: readonly ResolvedProfile[];
16
16
  readonly concurrency?: number;
17
17
  readonly maxFindings?: number;
18
+ /** The most tokens of diff text one research request of a large change holds: the config's alone, no variable sets it; absent when the config does not. */
19
+ readonly partTokens?: number;
18
20
  /** The most tokens one review spends: `QUORUM_MAX_REVIEW_TOKENS`, else the config's; absent when neither sets it. */
19
21
  readonly maxReviewTokens?: number;
20
22
  /** The deadline of one review, in milliseconds: `QUORUM_REVIEW_TIMEOUT_MS`, else the config's; absent when neither sets it. */
21
23
  readonly reviewTimeoutMs?: number;
22
24
  /** The path patterns of the files every review leaves out; absent when the config lists none. */
23
25
  readonly exclude?: readonly string[];
26
+ /** The files sent to the models though held as secrets, each the path as the diff writes it; the CLI merges them with `--send`. Absent when the config lists none. */
27
+ readonly send?: readonly string[];
24
28
  readonly warnings: readonly string[];
25
29
  }
26
30
  /** Whether `value` is a config `resolveConfig` returned. */
@@ -445,9 +445,11 @@ export function resolveConfig(input, options) {
445
445
  throw new ConfigError(issues);
446
446
  const concurrency = own(input, 'concurrency');
447
447
  const maxFindings = own(input, 'maxFindings');
448
+ const partTokens = own(input, 'partTokens');
448
449
  const maxReviewTokens = own(layer, 'maxReviewTokens') ?? own(input, 'maxReviewTokens');
449
450
  const reviewTimeoutMs = own(layer, 'reviewTimeoutMs') ?? own(input, 'reviewTimeoutMs');
450
451
  const exclude = own(input, 'exclude');
452
+ const send = own(input, 'send');
451
453
  const resolved = Object.freeze({
452
454
  providers: deepFreeze(Object.fromEntries(checked.providers)),
453
455
  profiles: Object.freeze([...profiles.profiles]),
@@ -457,6 +459,9 @@ export function resolveConfig(input, options) {
457
459
  ...maxFindings === undefined
458
460
  ? {}
459
461
  : { maxFindings },
462
+ ...partTokens === undefined
463
+ ? {}
464
+ : { partTokens },
460
465
  ...maxReviewTokens === undefined
461
466
  ? {}
462
467
  : { maxReviewTokens },
@@ -468,6 +473,11 @@ export function resolveConfig(input, options) {
468
473
  : {
469
474
  exclude: Object.freeze([...exclude]),
470
475
  },
476
+ ...send === undefined || send.length === 0
477
+ ? {}
478
+ : {
479
+ send: Object.freeze([...send]),
480
+ },
471
481
  warnings: Object.freeze([
472
482
  ...layer.warnings,
473
483
  ...checked.warnings,
@@ -26,10 +26,15 @@ export declare function statedFacts(provider: unknown): {
26
26
  * value that is no function is an issue of `providerObject` and is never read here.
27
27
  */
28
28
  export declare function statedWorstCase(provider: unknown): Provider['worstCase'];
29
+ /**
30
+ * The `room` a provider states, as own data: a function, else undefined, as `statedWorstCase` reads the worst
31
+ * case. It is no fact of `FACTS` either, so the fingerprint and the printed config never see it.
32
+ */
33
+ export declare function statedRoom(provider: unknown): Provider['room'];
29
34
  /**
30
35
  * `entry` named `id`, the config's key for it, when it is a snapshot the schema made of a provider object: a
31
- * copy that holds `id` as well, built from the snapshot's own data, the facts and the `worstCase` it states
32
- * included. Anything else is returned as it is.
36
+ * copy that holds `id` as well, built from the snapshot's own data, the facts and the `worstCase` and the
37
+ * `room` it states included. Anything else is returned as it is.
33
38
  */
34
39
  export declare function nameSnapshot(id: string, entry: unknown): unknown;
35
40
  /**
@@ -109,9 +114,11 @@ export declare const configFileSchema: z.ZodObject<{
109
114
  }, z.core.$strict>>;
110
115
  concurrency: z.ZodOptional<z.ZodInt>;
111
116
  maxFindings: z.ZodOptional<z.ZodInt>;
117
+ partTokens: z.ZodOptional<z.ZodInt>;
112
118
  maxReviewTokens: z.ZodOptional<z.ZodInt>;
113
119
  reviewTimeoutMs: z.ZodOptional<z.ZodInt>;
114
120
  exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
121
+ send: z.ZodOptional<z.ZodArray<z.ZodString>>;
115
122
  profiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
116
123
  extends: z.ZodOptional<z.ZodEnum<{
117
124
  [x: string]: string;
@@ -291,9 +298,11 @@ export declare const configCodeSchema: z.ZodObject<{
291
298
  }, z.core.$strict>>;
292
299
  concurrency: z.ZodOptional<z.ZodInt>;
293
300
  maxFindings: z.ZodOptional<z.ZodInt>;
301
+ partTokens: z.ZodOptional<z.ZodInt>;
294
302
  maxReviewTokens: z.ZodOptional<z.ZodInt>;
295
303
  reviewTimeoutMs: z.ZodOptional<z.ZodInt>;
296
304
  exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
305
+ send: z.ZodOptional<z.ZodArray<z.ZodString>>;
297
306
  profiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
298
307
  extends: z.ZodOptional<z.ZodEnum<{
299
308
  [x: string]: string;
@@ -473,9 +482,11 @@ export declare const configInputSchema: z.ZodObject<{
473
482
  }, z.core.$strict>>;
474
483
  concurrency: z.ZodOptional<z.ZodInt>;
475
484
  maxFindings: z.ZodOptional<z.ZodInt>;
485
+ partTokens: z.ZodOptional<z.ZodInt>;
476
486
  maxReviewTokens: z.ZodOptional<z.ZodInt>;
477
487
  reviewTimeoutMs: z.ZodOptional<z.ZodInt>;
478
488
  exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
489
+ send: z.ZodOptional<z.ZodArray<z.ZodString>>;
479
490
  profiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
480
491
  extends: z.ZodOptional<z.ZodEnum<{
481
492
  [x: string]: string;
@@ -1,6 +1,7 @@
1
1
  import { z } from 'zod';
2
2
  import { ConfigError, isSafeSegment, issuePath } from "../core/errors.js";
3
3
  import { MAX_PATTERNS, patternProblem, TOO_MANY_PATTERNS } from "../core/exclude.js";
4
+ import { MIN_PART_TOKENS } from "../core/parts.js";
4
5
  import { MAX_RETRIES, MAX_STATED_TIMEOUT_MS, MAX_TIMEOUT_MS, MIN_TIMEOUT_MS, retriesProblem, timeoutProblem } from "../core/ports.js";
5
6
  import { ownData } from "../core/stages/context.js";
6
7
  import { securityProfile } from "../profiles/security.js";
@@ -28,6 +29,8 @@ const pattern = z.string().check((ctx) => {
28
29
  if (problem !== undefined)
29
30
  ctx.issues.push({ code: 'custom', message: problem, input: ctx.value });
30
31
  });
32
+ /** A path of `send`: a non-empty string, in the words `review` refuses it with, since the empty name is no file of a diff. */
33
+ const file = z.string({ error: 'must name a file' }).min(1, { error: 'must name a file' });
31
34
  const roles = z.strictObject({
32
35
  research: name.optional().describe('The provider that looks for candidate findings'),
33
36
  voter: name.optional().describe('The provider every lens votes with, unless the lens names its own'),
@@ -114,9 +117,11 @@ function configSchema(provider, promptForm) {
114
117
  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'),
115
118
  concurrency: z.int().min(1).optional().describe('The most provider calls in flight at once in one review, shared by every profile'),
116
119
  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'),
120
+ partTokens: z.int().min(MIN_PART_TOKENS).optional().describe('The most tokens of diff text, at one token per byte, one research request of a large change holds; 32768 when unset'),
117
121
  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
122
  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
123
  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'),
124
+ send: z.array(file.describe('A file\'s path as the diff writes it, decoded')).optional().describe('The files sent to the models though held as secrets, each the path as the diff writes it and meta.leftOut lists it; none by default'),
120
125
  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'),
121
126
  });
122
127
  }
@@ -166,13 +171,26 @@ export function statedWorstCase(provider) {
166
171
  ? worstCase
167
172
  : undefined;
168
173
  }
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 }) {
174
+ /**
175
+ * The `room` a provider states, as own data: a function, else undefined, as `statedWorstCase` reads the worst
176
+ * case. It is no fact of `FACTS` either, so the fingerprint and the printed config never see it.
177
+ */
178
+ export function statedRoom(provider) {
179
+ const room = ownData(provider, 'room');
180
+ return typeof room === 'function'
181
+ ? room
182
+ : undefined;
183
+ }
184
+ /** A provider object as a snapshot: its fields as plain data, frozen, with no prototype. A `worstCase` or a `room` it states is kept as a field, and one it does not state leaves no field. */
185
+ function snapshot({ worstCase, room, ...fields }) {
171
186
  const made = Object.freeze(withoutPrototype(Object.entries({
172
187
  ...fields,
173
188
  ...worstCase === undefined
174
189
  ? {}
175
190
  : { worstCase },
191
+ ...room === undefined
192
+ ? {}
193
+ : { room },
176
194
  })));
177
195
  SNAPSHOTS.add(made);
178
196
  return made;
@@ -185,7 +203,8 @@ function snapshot({ worstCase, ...fields }) {
185
203
  * `timeoutMs` and `retries` it states are read as own data, so no getter runs for them; the snapshot keeps
186
204
  * each that is in range, and a value out of range is an issue at its field. The `worstCase` it states is read
187
205
  * 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.
206
+ * what the object says one call may cost; a value that is no function is an issue at its field. So is the
207
+ * `room` it states, which the review reads to know how much one request of the object may hold.
189
208
  */
190
209
  const providerObject = z.custom(value => typeof value === 'object' && value !== null).transform((object, ctx) => {
191
210
  const { model, complete } = object;
@@ -195,6 +214,7 @@ const providerObject = z.custom(value => typeof value === 'object' && value !==
195
214
  }
196
215
  const { stated, problems } = statedFacts(object);
197
216
  const worstCase = ownData(object, 'worstCase');
217
+ const room = ownData(object, 'room');
198
218
  const issues = [
199
219
  ...problems,
200
220
  ...worstCase === undefined || typeof worstCase === 'function'
@@ -202,6 +222,11 @@ const providerObject = z.custom(value => typeof value === 'object' && value !==
202
222
  : [
203
223
  { field: 'worstCase', message: 'must be a function' },
204
224
  ],
225
+ ...room === undefined || typeof room === 'function'
226
+ ? []
227
+ : [
228
+ { field: 'room', message: 'must be a function' },
229
+ ],
205
230
  ];
206
231
  // `continue` keeps the union from setting this form aside as aborted: the object took its shape, so its issues are the ones reported.
207
232
  for (const { field, message } of issues) {
@@ -224,12 +249,17 @@ const providerObject = z.custom(value => typeof value === 'object' && value !==
224
249
  worstCase: (request) => Reflect.apply(worstCase, object, [request]),
225
250
  }
226
251
  : {},
252
+ ...typeof room === 'function'
253
+ ? {
254
+ room: (request) => Reflect.apply(room, object, [request]),
255
+ }
256
+ : {},
227
257
  });
228
258
  });
229
259
  /**
230
260
  * `entry` named `id`, the config's key for it, when it is a snapshot the schema made of a provider object: a
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.
261
+ * copy that holds `id` as well, built from the snapshot's own data, the facts and the `worstCase` and the
262
+ * `room` it states included. Anything else is returned as it is.
233
263
  */
234
264
  export function nameSnapshot(id, entry) {
235
265
  if (typeof entry !== 'object' || entry === null || !SNAPSHOTS.has(entry))
@@ -241,6 +271,7 @@ export function nameSnapshot(id, entry) {
241
271
  complete,
242
272
  ...statedFacts(entry).stated,
243
273
  worstCase: statedWorstCase(entry),
274
+ room: statedRoom(entry),
244
275
  });
245
276
  }
246
277
  /**
@@ -1,15 +1,18 @@
1
1
  import type { IncompleteEntry, LeftOutFile } from './types.ts';
2
2
  /** What a review covers of a diff: the diff every stage reads, and the files it leaves out. */
3
3
  export interface ReviewScope {
4
- /** The diff every stage reads: the given one less the excluded sections. */
4
+ /** The diff every stage reads: the given one less the excluded and the held sections. */
5
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. */
6
+ /** The files left out, excluded, held as secrets or with a change the diff does not carry, in the diff's order, once per file and reason. */
7
7
  readonly leftOut: LeftOutFile[];
8
+ /** Every file of the given diff, excluded and held ones too, in the diff's order, once each: '' for the text no header names, none for a blank preamble. */
9
+ readonly files: string[];
8
10
  }
9
11
  /**
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:
12
+ * What a review covers of a diff: the files `excluded` leaves out, the files held back as secrets, and the
13
+ * files whose change the diff does not carry, found from the markers git prints in their place, each
14
+ * section read line by line (a trailing `\r` is dropped), so a Windows-made diff reads as any other. In
15
+ * each section:
13
16
  * - a `binary` file shows as a line that starts with `Binary files ` and ends with ` differ`, or one
14
17
  * that starts with `GIT binary patch`;
15
18
  * - a `submodule` shows as a `Subproject commit` row (past at most one leading `+`, `-` or space), a
@@ -35,15 +38,37 @@ export interface ReviewScope {
35
38
  * there, since `git am` applies only the patch sections, and a `Submodule` line still counts.
36
39
  *
37
40
  * 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.
41
+ * first header, a diff without such headers, a header that names no path quorum reads, and a `Submodule`
42
+ * line. A readable header never names the empty path, so it is never a file's.
43
+ *
44
+ * A file is held back when its name is a secret's, by any path its section names (its header, its `---`
45
+ * and `+++` lines, its `rename` and `copy` lines), or a line of it, removed and context lines included,
46
+ * holds a credential quorum recognizes (`secretRuleOf`). One file has one verdict: the sections of one
47
+ * path are one file, held by the first rule found in the diff's order, so when any of them is held every
48
+ * one leaves the scope's `diff`, and a credential in one holds the others. The file is listed once, at
49
+ * its first section, as `secret` with its `rule`, or as `deleted-secret` when its rule is `name` and every
50
+ * section of it is a whole deletion (`isWholeDeletion`): the change then adds no code, and the file is no
51
+ * gap. A deletion of a file held for a credential in it is `secret` and a gap, since the code it removes
52
+ * would go unread, as an edit of it would. A held section's own markers are left unread, as an excluded
53
+ * one's are, so a held binary file is listed `secret` only; its `Submodule` lines still list their
54
+ * submodule. The empty name is a file like any
55
+ * other: the text before the first header, a diff without such headers and a header quorum cannot read
56
+ * are held whole by one verdict.
57
+ *
58
+ * The order is: `excluded` first, so an excluded file is listed `excluded` only and judged no further;
59
+ * then `sent`, asked of each path a header names and never of the empty name, which sends a file whatever
60
+ * would hold it, so it is neither held nor listed; then the hold.
61
+ *
62
+ * The scope's `files` names every section's file as it is read, once each, in the diff's order, the held
63
+ * ones too: the empty name for the text no header names, and again, after the section that holds one, for
64
+ * a `Submodule` line; a preamble that is blank names no file.
40
65
  *
41
66
  * 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.
67
+ * `format-patch` series, lists the file whose section holds it, and a hit anywhere in a file holds all
68
+ * of it, since a gap it should not have stops a review for a person to look, where a missed one would
69
+ * pass a change unread. The scope's `diff` is the given string itself when no section was excluded or
70
+ * held, the kept sections joined by line feeds when some were, and '' when every section was.
46
71
  */
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. */
72
+ export declare function reviewScope(diff: string, excluded?: (path: string) => boolean, sent?: (path: string) => boolean): ReviewScope;
73
+ /** The gaps the files left out make for one profile: one per reason, binary then submodule then secret, counting its files, and none for a reason with no file. A `deleted-secret` file is no gap. */
49
74
  export declare function leftOutGaps(profile: string, leftOut: readonly LeftOutFile[]): IncompleteEntry[];
@@ -1,4 +1,5 @@
1
1
  import { diffSections, movedTo } from "./diff.js";
2
+ import { isWholeDeletion, secretRuleOf } from "./secrets.js";
2
3
  const BINARY_FILES_START = 'Binary files ';
3
4
  const BINARY_FILES_END = ' differ';
4
5
  const BINARY_PATCH = 'GIT binary patch';
@@ -39,9 +40,35 @@ function markersOf(text) {
39
40
  return markers;
40
41
  }
41
42
  /**
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:
43
+ * The files to hold back among the sections to judge, by file (the sections of one path; '' for the text
44
+ * no header names). A file is held by the first rule found, in the diff's order, one section's name before
45
+ * its content, and holds every section of it. It is a deletion, which is no gap, only when its rule is
46
+ * `name` and every section of it is a whole deletion: a file named as a secret holds no code a review
47
+ * would read. A file held for a credential in it may be code, and the removed lines of a deleted source
48
+ * file are the code a review would read, so a deletion of one is held as a gap like any other.
49
+ */
50
+ function heldFiles(judged) {
51
+ const held = new Map();
52
+ for (const section of judged) {
53
+ const file = section.path ?? '';
54
+ if (held.has(file))
55
+ continue;
56
+ const rule = secretRuleOf(section);
57
+ if (rule !== undefined)
58
+ held.set(file, { rule, deletion: rule === 'name' });
59
+ }
60
+ for (const { path, text } of judged) {
61
+ const file = held.get(path ?? '');
62
+ if (file !== undefined && file.deletion)
63
+ file.deletion = isWholeDeletion(text);
64
+ }
65
+ return held;
66
+ }
67
+ /**
68
+ * What a review covers of a diff: the files `excluded` leaves out, the files held back as secrets, and the
69
+ * files whose change the diff does not carry, found from the markers git prints in their place, each
70
+ * section read line by line (a trailing `\r` is dropped), so a Windows-made diff reads as any other. In
71
+ * each section:
45
72
  * - a `binary` file shows as a line that starts with `Binary files ` and ends with ` differ`, or one
46
73
  * that starts with `GIT binary patch`;
47
74
  * - a `submodule` shows as a `Subproject commit` row (past at most one leading `+`, `-` or space), a
@@ -67,27 +94,51 @@ function markersOf(text) {
67
94
  * there, since `git am` applies only the patch sections, and a `Submodule` line still counts.
68
95
  *
69
96
  * 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.
97
+ * first header, a diff without such headers, a header that names no path quorum reads, and a `Submodule`
98
+ * line. A readable header never names the empty path, so it is never a file's.
99
+ *
100
+ * A file is held back when its name is a secret's, by any path its section names (its header, its `---`
101
+ * and `+++` lines, its `rename` and `copy` lines), or a line of it, removed and context lines included,
102
+ * holds a credential quorum recognizes (`secretRuleOf`). One file has one verdict: the sections of one
103
+ * path are one file, held by the first rule found in the diff's order, so when any of them is held every
104
+ * one leaves the scope's `diff`, and a credential in one holds the others. The file is listed once, at
105
+ * its first section, as `secret` with its `rule`, or as `deleted-secret` when its rule is `name` and every
106
+ * section of it is a whole deletion (`isWholeDeletion`): the change then adds no code, and the file is no
107
+ * gap. A deletion of a file held for a credential in it is `secret` and a gap, since the code it removes
108
+ * would go unread, as an edit of it would. A held section's own markers are left unread, as an excluded
109
+ * one's are, so a held binary file is listed `secret` only; its `Submodule` lines still list their
110
+ * submodule. The empty name is a file like any
111
+ * other: the text before the first header, a diff without such headers and a header quorum cannot read
112
+ * are held whole by one verdict.
113
+ *
114
+ * The order is: `excluded` first, so an excluded file is listed `excluded` only and judged no further;
115
+ * then `sent`, asked of each path a header names and never of the empty name, which sends a file whatever
116
+ * would hold it, so it is neither held nor listed; then the hold.
117
+ *
118
+ * The scope's `files` names every section's file as it is read, once each, in the diff's order, the held
119
+ * ones too: the empty name for the text no header names, and again, after the section that holds one, for
120
+ * a `Submodule` line; a preamble that is blank names no file.
72
121
  *
73
122
  * 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.
123
+ * `format-patch` series, lists the file whose section holds it, and a hit anywhere in a file holds all
124
+ * of it, since a gap it should not have stops a review for a person to look, where a missed one would
125
+ * pass a change unread. The scope's `diff` is the given string itself when no section was excluded or
126
+ * held, the kept sections joined by line feeds when some were, and '' when every section was.
78
127
  */
79
- export function reviewScope(diff, excluded = () => false) {
128
+ export function reviewScope(diff, excluded = () => false, sent = () => false) {
80
129
  const leftOut = [];
81
130
  const listed = {
82
131
  excluded: new Set(),
83
132
  binary: new Set(),
84
133
  submodule: new Set(),
134
+ secret: new Set(),
135
+ 'deleted-secret': new Set(),
85
136
  };
86
- const list = (file, reason) => {
87
- if (listed[reason].has(file))
137
+ const list = (entry) => {
138
+ if (listed[entry.reason].has(entry.file))
88
139
  return;
89
- listed[reason].add(file);
90
- leftOut.push({ file, reason });
140
+ listed[entry.reason].add(entry.file);
141
+ leftOut.push(entry);
91
142
  };
92
143
  const answers = new Map();
93
144
  const isExcluded = (path) => {
@@ -98,38 +149,64 @@ export function reviewScope(diff, excluded = () => false) {
98
149
  }
99
150
  return answer;
100
151
  };
152
+ /** The path of a section `excluded` takes, or undefined for any other. */
153
+ const excludedPath = ({ path, text }) => path !== undefined && path !== '' && isExcluded(path) && movedTo(text).every(moved => moved === path)
154
+ ? path
155
+ : undefined;
156
+ /** Whether the input sends the file of a section: only a path a header names can be sent, never the empty name. */
157
+ const isSent = ({ path }) => path !== undefined && path !== '' && sent(path);
158
+ const files = new Set();
101
159
  const sections = diffSections(diff);
160
+ const held = heldFiles(sections.filter(section => excludedPath(section) === undefined && !isSent(section)));
102
161
  const kept = [];
103
- for (const { path, text } of sections) {
162
+ for (const section of sections) {
163
+ const { path, text } = section;
104
164
  const markers = markersOf(text);
105
- if (path !== undefined && path !== '' && isExcluded(path) && movedTo(text).every(moved => moved === path)) {
106
- list(path, 'excluded');
165
+ if (path !== '' || text.trim() !== '')
166
+ files.add(path ?? '');
167
+ const gone = excludedPath(section);
168
+ const hold = held.get(path ?? '');
169
+ if (gone !== undefined) {
170
+ list({ file: gone, reason: 'excluded' });
171
+ }
172
+ else if (hold !== undefined) {
173
+ list({
174
+ file: path ?? '',
175
+ reason: hold.deletion ? 'deleted-secret' : 'secret',
176
+ rule: hold.rule,
177
+ });
107
178
  }
108
179
  else {
109
180
  kept.push(text);
110
181
  if (markers.binary)
111
- list(path ?? '', 'binary');
182
+ list({ file: path ?? '', reason: 'binary' });
112
183
  if (markers.submodule)
113
- list(path ?? '', 'submodule');
184
+ list({ file: path ?? '', reason: 'submodule' });
185
+ }
186
+ if (markers.submoduleLine) {
187
+ list({ file: '', reason: 'submodule' });
188
+ files.add('');
114
189
  }
115
- if (markers.submoduleLine)
116
- list('', 'submodule');
117
190
  }
118
191
  return {
119
192
  diff: kept.length === sections.length
120
193
  ? diff
121
194
  : kept.join('\n'),
122
195
  leftOut,
196
+ files: [...files],
123
197
  };
124
198
  }
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)',
199
+ /** The reasons of the gaps a diff's own files make for a profile, in the order they are recorded. A file excluded, skipped, or named as a secret and deleted whole, is no gap. */
200
+ const GAP_REASONS = ['binary', 'submodule', 'secret'];
201
+ /** What a gap's detail says of its `count` files. */
202
+ const GAP_DETAILS = {
203
+ binary: count => `the diff carries no content for ${count} binary file(s), listed in meta.leftOut`,
204
+ submodule: count => `the diff carries no content for ${count} submodule(s), listed in meta.leftOut`,
205
+ secret: count => `no model was sent ${count} file(s) held as secrets, listed in meta.leftOut`,
129
206
  };
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. */
207
+ /** The gaps the files left out make for one profile: one per reason, binary then submodule then secret, counting its files, and none for a reason with no file. A `deleted-secret` file is no gap. */
131
208
  export function leftOutGaps(profile, leftOut) {
132
- return ['binary', 'submodule'].flatMap((reason) => {
209
+ return GAP_REASONS.flatMap((reason) => {
133
210
  const count = leftOut.filter(entry => entry.reason === reason).length;
134
211
  return count === 0
135
212
  ? []
@@ -137,7 +214,7 @@ export function leftOutGaps(profile, leftOut) {
137
214
  {
138
215
  profile,
139
216
  reason,
140
- detail: `the diff carries no content for ${count} ${GAP_THINGS[reason]}, listed in meta.leftOut`,
217
+ detail: GAP_DETAILS[reason](count),
141
218
  },
142
219
  ];
143
220
  });
@@ -1,3 +1,14 @@
1
+ /**
2
+ * Decode the inside of a quoted name (`core.quotePath` writes every non-ASCII byte as `\NNN`): a
3
+ * backslash escape stands for one character (`\n`, `\t`, `\"`, `\\`, ...) and the `\NNN` bytes of a
4
+ * run are decoded together as UTF-8. An escape git never writes is kept as it is. A run of bytes
5
+ * that is not valid UTF-8 becomes one lone surrogate per byte (U+DC00 plus the byte, as Python
6
+ * names a file it cannot decode): no valid name holds a lone surrogate, so two such names never
7
+ * share a key, nor does one share a key with a name that spells out its escapes, and
8
+ * `JSON.stringify` writes the surrogate as an escape. One pass over the name and no pattern that
9
+ * can backtrack.
10
+ */
11
+ export declare function decodeQuoted(quoted: string): string;
1
12
  /**
2
13
  * The paths the `rename to ` and `copy to ` lines of a section name, in order, each less a trailing
3
14
  * `\r` and decoded when git quoted it. Git does not quote a path that holds a space, so a path with a
@@ -7,6 +18,35 @@
7
18
  * read with no hunk parsing.
8
19
  */
9
20
  export declare function movedTo(text: string): string[];
21
+ /**
22
+ * The paths a section's own lines name, in the order of the lines, each as its line writes it (an
23
+ * `a/` or `b/` prefix included) and decoded when git quoted it: the path of each `--- `, `+++ `,
24
+ * `rename from `, `rename to `, `copy from ` and `copy to ` line, less a trailing `\r` and cut at a
25
+ * tab (git ends a `---` or `+++` line with one when the name holds a space, and `diff -u` writes a
26
+ * timestamp after one). `/dev/null` and an empty name are no path. The header's own path is the
27
+ * section's `path`, and is not read again. A hunk row that reads like one of these lines (an added
28
+ * `++ b/.env` shows as `+++ b/.env`) names a path too: the lines are read with no hunk parsing, so
29
+ * the answer is generous and fails closed.
30
+ */
31
+ export declare function namedPaths(text: string): string[];
32
+ /**
33
+ * The names the first line of a section holds when it is a `diff --git` header: each space-separated
34
+ * word after the keyword, none empty, less a trailing `\r` and decoded when quoted, as `namedPaths`
35
+ * decodes. The header's own path (`path` of the section) is one reading of these words, and a header
36
+ * that is forged or cannot be read gives the words and no path, so the hold reads each of them: a
37
+ * header such as `diff --git a/.env` or `diff --git a/.env b/.env c` names `.env` to a reader that
38
+ * splits it on its spaces. A path that holds a space is cut, so this is generous and fails closed.
39
+ * None for a section that opens with another line.
40
+ */
41
+ export declare function headerNames(text: string): string[];
42
+ /**
43
+ * Whether a `--- ` line writes the old side of a `diff --git` header that names one path on both
44
+ * sides, as the header of a file git deletes whole does: the header's first half, cut at the middle
45
+ * space as `sharedPath` cuts it, and the line's path (up to a tab), are one name once decoded. A
46
+ * header whose two sides differ, or that holds a third name, has no such old side, so no line agrees
47
+ * with it.
48
+ */
49
+ export declare function namesOldSide(header: string, minusLine: string): boolean;
10
50
  /** One section of a diff: the text from a `diff --git` header to the next, or the text before the first one. */
11
51
  export interface DiffSection {
12
52
  /** 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. */
@@ -101,6 +141,43 @@ export interface AddedLine {
101
141
  * `format-patch` series.
102
142
  */
103
143
  export declare function addedLines(sections: ReadonlyMap<string, string>, path: string): AddedLine[];
144
+ export interface Hunk {
145
+ /** The index of the hunk's `@@` line among the section's lines split at line feeds. */
146
+ at: number;
147
+ /** First new-file line of the hunk. */
148
+ start: number;
149
+ /** Number of new-file lines the header promises. */
150
+ count: number;
151
+ /** The hunk's lines (with their +, - or space marker), in order. */
152
+ rows: string[];
153
+ /** For each new-file line from `start`, the index in `rows` of the row that shows it. */
154
+ rowOfLine: number[];
155
+ }
156
+ export declare function hunksOf(sections: ReadonlyMap<string, string>, path: string, text: string): Hunk[];
157
+ /** A run of new-file lines, both ends included. */
158
+ export interface Span {
159
+ readonly start: number;
160
+ readonly end: number;
161
+ }
162
+ /**
163
+ * Whether `hunk` holds the new-file line `line`, as `locate` takes it: the line is within the hunk's
164
+ * start and its count (a count of 0 holds its start alone), the hunk shows a row, and, for a hunk
165
+ * that counts new lines, a row shows the line, so a hunk cut short of its count does not hold the
166
+ * lines it never shows.
167
+ */
168
+ export declare function holds(hunk: Hunk, line: number): boolean;
169
+ /** 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. */
170
+ export declare function heldSpan(hunk: Hunk): Span | undefined;
171
+ /**
172
+ * Read the hunks of one file section. The header's line counts say where a hunk ends, so file
173
+ * headers and `` markers are never mistaken for hunk lines, and a line
174
+ * that cannot belong to a hunk closes it even when the counts promised more. The empty element
175
+ * after a final newline is not a line; an empty line before it is a blank context row.
176
+ *
177
+ * This is the one reading of a hunk: the packer of a large change, `locate` and a vote's context
178
+ * share it, so they agree on where each hunk opens, at the line `at` of its `@@` header.
179
+ */
180
+ export declare function parseHunks(section: string): Hunk[];
104
181
  /** The most diff quorum reads, from stdin, a file or a suite, in bytes: a larger one is refused and reading stops there. */
105
182
  export declare const MAX_DIFF_BYTES: number;
106
183
  /**