@tobi-or-not/quorum 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/README.md +3 -1
  2. package/dist/bench/fingerprint.d.ts +8 -5
  3. package/dist/bench/fingerprint.js +28 -9
  4. package/dist/bench/records.d.ts +168 -0
  5. package/dist/bench/records.js +106 -1
  6. package/dist/bench/runner.d.ts +18 -0
  7. package/dist/bench/runner.js +30 -4
  8. package/dist/cli/bench.d.ts +11 -4
  9. package/dist/cli/bench.js +34 -17
  10. package/dist/cli/bin.js +2 -2
  11. package/dist/cli/io.d.ts +5 -0
  12. package/dist/cli/main.d.ts +67 -24
  13. package/dist/cli/main.js +288 -59
  14. package/dist/cli/print-config.d.ts +8 -6
  15. package/dist/cli/print-config.js +26 -8
  16. package/dist/cli/render.d.ts +9 -3
  17. package/dist/cli/render.js +43 -2
  18. package/dist/config/claude-code.d.ts +2 -6
  19. package/dist/config/claude-code.js +6 -44
  20. package/dist/config/command.d.ts +10 -0
  21. package/dist/config/command.js +47 -0
  22. package/dist/config/env.d.ts +32 -19
  23. package/dist/config/env.js +95 -32
  24. package/dist/config/from-config.js +21 -3
  25. package/dist/config/resolve.d.ts +13 -1
  26. package/dist/config/resolve.js +27 -1
  27. package/dist/config/schema.d.ts +152 -5
  28. package/dist/config/schema.js +156 -12
  29. package/dist/core/clock.d.ts +17 -0
  30. package/dist/core/clock.js +14 -0
  31. package/dist/core/coverage.d.ts +74 -0
  32. package/dist/core/coverage.js +221 -0
  33. package/dist/core/diff.d.ts +101 -0
  34. package/dist/core/diff.js +178 -35
  35. package/dist/core/errors.d.ts +12 -3
  36. package/dist/core/errors.js +21 -2
  37. package/dist/core/estimate.d.ts +45 -0
  38. package/dist/core/estimate.js +188 -0
  39. package/dist/core/exclude.d.ts +42 -0
  40. package/dist/core/exclude.js +189 -0
  41. package/dist/core/flags.d.ts +14 -1
  42. package/dist/core/flags.js +56 -0
  43. package/dist/core/inputs.d.ts +38 -0
  44. package/dist/core/inputs.js +228 -0
  45. package/dist/core/limits.d.ts +83 -0
  46. package/dist/core/limits.js +169 -0
  47. package/dist/core/output.d.ts +3 -2
  48. package/dist/core/output.js +3 -2
  49. package/dist/core/parts.d.ts +146 -0
  50. package/dist/core/parts.js +388 -0
  51. package/dist/core/ports.d.ts +67 -2
  52. package/dist/core/ports.js +36 -1
  53. package/dist/core/prompts.d.ts +22 -3
  54. package/dist/core/prompts.js +43 -7
  55. package/dist/core/quorum.d.ts +26 -8
  56. package/dist/core/quorum.js +310 -73
  57. package/dist/core/retry.d.ts +36 -0
  58. package/dist/core/retry.js +46 -0
  59. package/dist/core/secrets.d.ts +98 -0
  60. package/dist/core/secrets.js +507 -0
  61. package/dist/core/stages/context.d.ts +131 -23
  62. package/dist/core/stages/context.js +331 -46
  63. package/dist/core/stages/panel.d.ts +13 -6
  64. package/dist/core/stages/panel.js +79 -19
  65. package/dist/core/stages/research.d.ts +110 -25
  66. package/dist/core/stages/research.js +338 -44
  67. package/dist/core/tokens.d.ts +31 -0
  68. package/dist/core/tokens.js +81 -0
  69. package/dist/core/types.d.ts +280 -25
  70. package/dist/core/verify.d.ts +6 -0
  71. package/dist/core/verify.js +6 -3
  72. package/dist/git/run.d.ts +223 -0
  73. package/dist/git/run.js +608 -0
  74. package/dist/git/tree.d.ts +43 -0
  75. package/dist/git/tree.js +171 -0
  76. package/dist/index.d.ts +26 -2
  77. package/dist/index.js +34 -2
  78. package/dist/providers/anthropic.d.ts +3 -1
  79. package/dist/providers/anthropic.js +10 -3
  80. package/dist/providers/claude-code.d.ts +56 -11
  81. package/dist/providers/claude-code.js +70 -25
  82. package/dist/providers/gemini.d.ts +5 -1
  83. package/dist/providers/gemini.js +65 -11
  84. package/dist/providers/http.d.ts +49 -4
  85. package/dist/providers/http.js +155 -14
  86. package/dist/providers/ollama.d.ts +4 -1
  87. package/dist/providers/ollama.js +13 -5
  88. package/dist/providers/openai-compatible.d.ts +4 -1
  89. package/dist/providers/openai-compatible.js +13 -5
  90. package/dist/providers/options.d.ts +12 -3
  91. package/dist/providers/options.js +30 -10
  92. package/dist/providers/size.d.ts +19 -15
  93. package/dist/providers/size.js +33 -73
  94. package/dist/sources/added.d.ts +49 -0
  95. package/dist/sources/added.js +134 -0
  96. package/dist/sources/diff.d.ts +13 -0
  97. package/dist/sources/diff.js +63 -0
  98. package/dist/sources/local.d.ts +41 -0
  99. package/dist/sources/local.js +251 -0
  100. package/dist/sources/paths.d.ts +45 -0
  101. package/dist/sources/paths.js +230 -0
  102. package/dist/sources/range.d.ts +21 -0
  103. package/dist/sources/range.js +75 -0
  104. package/dist/sources/read.d.ts +69 -0
  105. package/dist/sources/read.js +37 -0
  106. package/dist/sources/repository.d.ts +9 -0
  107. package/dist/sources/repository.js +28 -0
  108. package/dist/sources/skips.d.ts +49 -0
  109. package/dist/sources/skips.js +126 -0
  110. package/package.json +1 -1
  111. package/schema/quorum.schema.json +49 -1
@@ -0,0 +1,608 @@
1
+ import { spawn } from 'node:child_process';
2
+ import { systemClock } from "../core/clock.js";
3
+ import { ConfigError, QuorumError } from "../core/errors.js";
4
+ /**
5
+ * The one place quorum runs git: a closed set of typed operations (`GitOperation`), each built into one
6
+ * argument vector by `gitArgs` and spawned by `runGit` with no shell, and `openRepository`, which checks a
7
+ * working directory and hands back the operations the sources call. Quorum reviews repositories it was
8
+ * handed, so nothing a repository holds may run a program or reshape the bytes git prints.
9
+ *
10
+ * @see ../../docs/95-reference/40-architecture.md for where it sits in the layers.
11
+ */
12
+ /** The oldest git quorum runs: `--attr-source` came with 2.41, and every other option it pins is older. */
13
+ export const GIT_FLOOR = Object.freeze({ major: 2, minor: 41 });
14
+ /** The deadline of one git call, on the injected clock. */
15
+ export const GIT_TIMEOUT_MS = 120_000;
16
+ /** The most a diff or a listing may print, which `core/diff.ts`'s `MAX_DIFF_BYTES` is: the layer imports no `diff.ts`, so a spec holds the two equal. */
17
+ export const MAX_GIT_OUTPUT_BYTES = 16 * 1024 * 1024;
18
+ /** The most of a child's stderr that is kept; the rest is read and dropped. */
19
+ export const MAX_GIT_STDERR_BYTES = 65_536;
20
+ /** The most `--version`, `rev-parse`, `merge-base`, `hash-object` and `config` print. */
21
+ export const MAX_GIT_SMALL_OUTPUT_BYTES = 65_536;
22
+ /** The characters of git's stderr a `GitError` quotes. */
23
+ export const STDERR_EXCERPT = 500;
24
+ /** What a run's `code` is when quorum stopped the child, which then has no exit code of its own. */
25
+ const STOPPED = -1;
26
+ /** Before every command: no pager, no lock and no replace ref, literal pathspecs, and the config keys that would run a program or reshape a path. */
27
+ export const GLOBAL_PINS = Object.freeze([
28
+ '--no-pager',
29
+ '--no-optional-locks',
30
+ '--no-replace-objects',
31
+ '--literal-pathspecs',
32
+ '-c',
33
+ 'core.fsmonitor=false',
34
+ '-c',
35
+ 'core.hooksPath=/dev/null',
36
+ '-c',
37
+ 'core.pager=cat',
38
+ '-c',
39
+ 'core.quotePath=true',
40
+ '-c',
41
+ 'core.bigFileThreshold=512m',
42
+ '-c',
43
+ 'core.attributesFile=/dev/null',
44
+ '-c',
45
+ 'safe.bareRepository=explicit',
46
+ '-c',
47
+ 'diff.suppressBlankEmpty=false',
48
+ '-c',
49
+ 'diff.autoRefreshIndex=false',
50
+ ]);
51
+ /** After `diff`: the options that give one form of diff whatever the repository's `diff.*` and `color.*` config says. */
52
+ export const DIFF_PINS = Object.freeze([
53
+ '--no-ext-diff',
54
+ '--no-textconv',
55
+ '--no-color',
56
+ '--src-prefix=a/',
57
+ '--dst-prefix=b/',
58
+ '--unified=3',
59
+ '--inter-hunk-context=0',
60
+ '--diff-algorithm=myers',
61
+ '--indent-heuristic',
62
+ '--full-index',
63
+ '--no-renames',
64
+ '--no-relative',
65
+ '--submodule=short',
66
+ '-O/dev/null',
67
+ ]);
68
+ /** The variables of the parent's environment a child gets, when the parent holds them as its own strings. Every other variable is dropped. */
69
+ export const ENVIRONMENT_ALLOWLIST = Object.freeze([
70
+ 'PATH',
71
+ 'HOME',
72
+ 'XDG_CONFIG_HOME',
73
+ 'TMPDIR',
74
+ 'GIT_DIR',
75
+ 'GIT_WORK_TREE',
76
+ 'GIT_INDEX_FILE',
77
+ 'GIT_COMMON_DIR',
78
+ 'GIT_OBJECT_DIRECTORY',
79
+ 'GIT_ALTERNATE_OBJECT_DIRECTORIES',
80
+ 'GIT_CEILING_DIRECTORIES',
81
+ 'GIT_DISCOVERY_ACROSS_FILESYSTEM',
82
+ 'GIT_CONFIG_GLOBAL',
83
+ 'GIT_CONFIG_SYSTEM',
84
+ 'GIT_CONFIG_NOSYSTEM',
85
+ ]);
86
+ /** The variables quorum sets, over whatever the parent holds. An empty allowlist of protocols refuses every transport, a lazy fetch's included. */
87
+ const SET_BY_QUORUM = Object.freeze({
88
+ LC_ALL: 'C',
89
+ GIT_PAGER: 'cat',
90
+ GIT_TERMINAL_PROMPT: '0',
91
+ GIT_OPTIONAL_LOCKS: '0',
92
+ GIT_NO_REPLACE_OBJECTS: '1',
93
+ GIT_NO_LAZY_FETCH: '1',
94
+ GIT_ALLOW_PROTOCOL: '',
95
+ });
96
+ const ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
97
+ const ID_OF = { sha1: /^[0-9a-f]{40}$/, sha256: /^[0-9a-f]{64}$/ };
98
+ /** The id of the empty tree in each object format, which `hash-object -t tree --stdin` of nothing prints: git's answer is checked against it. */
99
+ const EMPTY_TREE = Object.freeze({
100
+ sha1: '4b825dc642cb6eb9a060e54bf8d69288fbee4904',
101
+ sha256: '6ef19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321',
102
+ });
103
+ const VERSION = /^git version (\d+)\.(\d+)/;
104
+ const ERROR_CODE = /^[A-Z][A-Z0-9_]{0,39}$/;
105
+ /** A git call that failed: it could not start, passed its deadline, was stopped by a signal, exited with a failure, or printed what quorum cannot read. */
106
+ export class GitError extends QuorumError {
107
+ /** The git subcommand the call ran: `diff`, `rev-parse`, `ls-tree`, and `version` for `--version`. */
108
+ operation;
109
+ /** The exit code, or null when there was none: the child did not start or did not finish. */
110
+ exitCode;
111
+ constructor(message, operation, exitCode = null) {
112
+ super(message);
113
+ this.operation = operation;
114
+ this.exitCode = exitCode;
115
+ }
116
+ }
117
+ /**
118
+ * What a child gets of the parent's environment: each name of `ENVIRONMENT_ALLOWLIST` the parent holds as its
119
+ * own string, then quorum's own seven variables, which win. Nothing else passes: not `GIT_DIFF_OPTS` or
120
+ * `GIT_EXTERNAL_DIFF`, not `GIT_CONFIG_PARAMETERS` or `GIT_CONFIG_COUNT`, not a pager, not a key.
121
+ */
122
+ export function gitEnvironment(env) {
123
+ const result = {};
124
+ for (const name of ENVIRONMENT_ALLOWLIST) {
125
+ const value = Object.hasOwn(env, name)
126
+ ? env[name]
127
+ : undefined;
128
+ if (typeof value === 'string')
129
+ result[name] = value;
130
+ }
131
+ return {
132
+ ...result,
133
+ ...SET_BY_QUORUM,
134
+ };
135
+ }
136
+ /** The git subcommand each operation runs, as a `GitError` names it. */
137
+ const SUBCOMMAND = {
138
+ version: 'version',
139
+ toplevel: 'rev-parse',
140
+ prefix: 'rev-parse',
141
+ 'git-dir': 'rev-parse',
142
+ 'top-git-dir': 'rev-parse',
143
+ 'object-format': 'rev-parse',
144
+ resolve: 'rev-parse',
145
+ 'merge-base': 'merge-base',
146
+ 'empty-tree': 'hash-object',
147
+ 'diff-commits': 'diff',
148
+ 'diff-index': 'diff',
149
+ 'diff-worktree': 'diff',
150
+ 'filter-config': 'config',
151
+ untracked: 'ls-files',
152
+ 'list-tree': 'ls-tree',
153
+ 'read-objects': 'cat-file',
154
+ };
155
+ /** An id as it goes into a vector: 40 or 64 lowercase hexadecimal characters, else a `RangeError` that does not repeat it. */
156
+ export function checkedId(value) {
157
+ if (!ID.test(value))
158
+ throw new RangeError('a git id must be 40 or 64 lowercase hexadecimal characters');
159
+ return value;
160
+ }
161
+ /** Whether `value` is a revision quorum passes git: not empty, not an option, with no NUL (which no argument can hold). */
162
+ function isRevision(value) {
163
+ return value !== '' && !value.startsWith('-') && !value.includes('\0');
164
+ }
165
+ /** The vector of a command run inside the top level: `-C <top>` after the pins, which git reads as one argument whatever it holds. */
166
+ function inTop(top, ...words) {
167
+ return [
168
+ ...GLOBAL_PINS,
169
+ '-C',
170
+ top,
171
+ ...words,
172
+ ];
173
+ }
174
+ /**
175
+ * The argument vector of `operation`: `GLOBAL_PINS`, then the operation's own words. Every id is checked
176
+ * first, as 40 or 64 lowercase hexadecimal characters, and a revision, the one string a user gives git, as
177
+ * not empty and not an option (it follows `--end-of-options` besides): a `RangeError` otherwise, before any
178
+ * vector is built. Every diff ends with `--`, so no name is read as a revision.
179
+ */
180
+ export function gitArgs(operation) {
181
+ switch (operation.op) {
182
+ case 'version':
183
+ return [...GLOBAL_PINS, '--version'];
184
+ case 'toplevel':
185
+ return [...GLOBAL_PINS, 'rev-parse', '--show-toplevel'];
186
+ case 'prefix':
187
+ return [...GLOBAL_PINS, 'rev-parse', '--show-prefix'];
188
+ case 'git-dir':
189
+ return [...GLOBAL_PINS, 'rev-parse', '--absolute-git-dir'];
190
+ case 'top-git-dir':
191
+ return inTop(operation.top, 'rev-parse', '--absolute-git-dir');
192
+ case 'object-format':
193
+ return inTop(operation.top, 'rev-parse', '--show-object-format');
194
+ case 'resolve':
195
+ if (!isRevision(operation.revision))
196
+ throw new RangeError('a revision must name something, may not start with - and may not hold a NUL');
197
+ return inTop(operation.top, 'rev-parse', '--verify', '--quiet', '--end-of-options', `${operation.revision}^{commit}`);
198
+ case 'merge-base':
199
+ return inTop(operation.top, 'merge-base', checkedId(operation.first), checkedId(operation.second));
200
+ case 'empty-tree':
201
+ return inTop(operation.top, 'hash-object', '-t', 'tree', '--stdin');
202
+ case 'diff-commits':
203
+ return inTop(operation.top, `--attr-source=${checkedId(operation.attributes)}`, 'diff', ...DIFF_PINS, '--ignore-submodules=none', checkedId(operation.from), checkedId(operation.to), '--');
204
+ case 'diff-index':
205
+ return inTop(operation.top, `--attr-source=${checkedId(operation.attributes)}`, 'diff', ...DIFF_PINS, '--ignore-submodules=dirty', '--cached', checkedId(operation.from), '--');
206
+ case 'diff-worktree':
207
+ return inTop(operation.top, `--attr-source=${checkedId(operation.attributes)}`, 'diff', ...DIFF_PINS, '--ignore-submodules=dirty', checkedId(operation.from), '--');
208
+ case 'filter-config':
209
+ return inTop(operation.top, 'config', '--show-scope', '-z', '--get-regexp', '^filter\\..+\\.(clean|smudge|process)$');
210
+ case 'untracked':
211
+ return inTop(operation.top, 'ls-files', '-z', '--others', '--exclude-standard');
212
+ case 'list-tree':
213
+ return inTop(operation.top, 'ls-tree', '-r', '-z', '--long', '--full-tree', checkedId(operation.commit));
214
+ case 'read-objects':
215
+ return inTop(operation.top, 'cat-file', '--batch', '--buffer');
216
+ }
217
+ }
218
+ /** `error`'s system code as a message writes it, or `unknown`: the message of the error holds the path, and a path is not printed. */
219
+ function startFailure(name, error) {
220
+ const code = typeof error === 'object' && error !== null && 'code' in error
221
+ ? error.code
222
+ : undefined;
223
+ const named = typeof code === 'string' && ERROR_CODE.test(code)
224
+ ? code
225
+ : 'unknown';
226
+ return new GitError(`git could not start (${named})`, name);
227
+ }
228
+ /** `chunks` as one array of `size` bytes, their total. */
229
+ export function joined(chunks, size) {
230
+ const bytes = new Uint8Array(size);
231
+ let at = 0;
232
+ for (const chunk of chunks) {
233
+ bytes.set(chunk, at);
234
+ at += chunk.length;
235
+ }
236
+ return bytes;
237
+ }
238
+ /**
239
+ * Runs one operation: spawns `context.git` with `gitArgs`'s vector and `gitEnvironment`'s environment, with
240
+ * no shell, from `context.cwd`, its stdin ignored unless the operation takes input (`empty-tree` and
241
+ * `read-objects`, which get `options.input` and an end). It resolves for any exit code, with stdout up to
242
+ * `options.maxStdout` (`MAX_GIT_SMALL_OUTPUT_BYTES` unless a caller says) and the first 64 KiB of stderr; a
243
+ * child that prints more is killed and the run says `over`. With `options.onStdout` each chunk is handed over
244
+ * and not kept, and `false` stops the child, `over` again. It rejects with a `GitError` when git cannot start,
245
+ * passes its deadline (`GIT_TIMEOUT_MS` on the context's clock) or is ended by a signal quorum did not send,
246
+ * and with the signal's reason when `context.signal` aborts. Quorum's own stops, at a cap, a deadline or an
247
+ * abort, are SIGKILL, after which the child's pipes are destroyed so that a helper holding them cannot keep
248
+ * the call open. The timer and the listener are gone on every path.
249
+ *
250
+ * What is pinned, and what the prototype on git 2.50.1 saw without it:
251
+ * - `core.fsmonitor`, `core.hooksPath` and the pager (`--no-pager`, `core.pager`, `GIT_PAGER`): a repository's
252
+ * own config ran its marker programs as fsmonitor, as hooks and, under a pseudo-terminal, as the pager.
253
+ * - `--no-ext-diff`, `--no-textconv` and `core.attributesFile`, with `--attr-source=<commit>` on each diff:
254
+ * `diff.external`, a text converter and a driver's `command` ran, and `.gitattributes` and `info/attributes`
255
+ * named them. Every operation ran nothing but the working-tree diff, whose filters the trust check refuses.
256
+ * - `--no-replace-objects` and `GIT_NO_REPLACE_OBJECTS`: a replace ref swapped a blob for another.
257
+ * - `diff.autoRefreshIndex=false`, `--no-optional-locks` and `GIT_OPTIONAL_LOCKS`: a working-tree diff
258
+ * rewrote `.git/index`, a stat refresh, and quorum never writes to a repository.
259
+ * - The `DIFF_PINS`, `core.quotePath` and `diff.suppressBlankEmpty`: a hostile `diff.algorithm`,
260
+ * `diff.context`, `diff.renames`, `core.abbrev`, `diff.orderFile` and the like changed the bytes of a diff.
261
+ * - `--` after every diff: a tracked file named after a commit id made `git diff <id> <id>` fatal.
262
+ * - `GIT_NO_LAZY_FETCH` and an empty `GIT_ALLOW_PROTOCOL`: a partial clone fetched a missing blob; each alone
263
+ * stops it, and the allowlist holds on every release.
264
+ * - `safe.bareRepository=explicit`: a bare repository committed in the tree was refused from inside it.
265
+ * - The environment allowlist: `GIT_DIFF_OPTS` and `GIT_EXTERNAL_DIFF` of the parent reshaped and ran.
266
+ */
267
+ export function runGit(context, operation, options = {}) {
268
+ return new Promise((resolve, reject) => {
269
+ const args = gitArgs(operation);
270
+ const name = SUBCOMMAND[operation.op];
271
+ const { signal } = context;
272
+ if (signal?.aborted) {
273
+ reject(signal.reason);
274
+ return;
275
+ }
276
+ const takesInput = operation.op === 'empty-tree' || operation.op === 'read-objects';
277
+ let child;
278
+ try {
279
+ child = (context.spawn ?? spawn)(context.git, args, {
280
+ cwd: context.cwd,
281
+ env: gitEnvironment(context.env),
282
+ stdio: [
283
+ takesInput ? 'pipe' : 'ignore',
284
+ 'pipe',
285
+ 'pipe',
286
+ ],
287
+ shell: false,
288
+ windowsHide: true,
289
+ });
290
+ }
291
+ catch (error) {
292
+ reject(startFailure(name, error));
293
+ return;
294
+ }
295
+ const timeoutMs = context.timeoutMs ?? GIT_TIMEOUT_MS;
296
+ const limit = options.maxStdout ?? MAX_GIT_SMALL_OUTPUT_BYTES;
297
+ const stdout = [];
298
+ const stderr = [];
299
+ let stdoutBytes = 0;
300
+ let stderrBytes = 0;
301
+ let cause;
302
+ let thrown;
303
+ let started = false;
304
+ let done = false;
305
+ const stop = (why) => {
306
+ if (cause !== undefined || done)
307
+ return;
308
+ cause = why;
309
+ child.kill('SIGKILL');
310
+ // A helper that outlives git and holds the pipes must not keep `close` from firing.
311
+ child.stdout?.destroy();
312
+ child.stderr?.destroy();
313
+ };
314
+ const onAbort = () => stop('abort');
315
+ const cancel = (context.clock ?? systemClock).timer(timeoutMs, () => stop('deadline'));
316
+ const finish = (settle) => {
317
+ if (done)
318
+ return;
319
+ done = true;
320
+ cancel();
321
+ signal?.removeEventListener('abort', onAbort);
322
+ settle();
323
+ };
324
+ signal?.addEventListener('abort', onAbort, { once: true });
325
+ child.stdout?.on('data', (chunk) => {
326
+ if (cause !== undefined)
327
+ return;
328
+ if (options.onStdout !== undefined) {
329
+ try {
330
+ if (!options.onStdout(chunk))
331
+ stop('over');
332
+ }
333
+ catch (error) {
334
+ thrown = error;
335
+ stop('consumer');
336
+ }
337
+ return;
338
+ }
339
+ const room = limit - stdoutBytes;
340
+ if (chunk.length > room) {
341
+ stdout.push(chunk.subarray(0, room));
342
+ stdoutBytes = limit;
343
+ stop('over');
344
+ return;
345
+ }
346
+ stdout.push(chunk);
347
+ stdoutBytes += chunk.length;
348
+ });
349
+ child.stderr?.on('data', (chunk) => {
350
+ const room = MAX_GIT_STDERR_BYTES - stderrBytes;
351
+ if (room <= 0)
352
+ return;
353
+ const kept = chunk.subarray(0, room);
354
+ stderr.push(kept);
355
+ stderrBytes += kept.length;
356
+ });
357
+ child.once('spawn', () => {
358
+ started = true;
359
+ });
360
+ child.on('error', (error) => {
361
+ if (!started)
362
+ finish(() => reject(startFailure(name, error)));
363
+ });
364
+ child.once('close', (code, endedBy) => finish(() => {
365
+ switch (cause) {
366
+ case 'abort':
367
+ reject(signal?.reason);
368
+ return;
369
+ case 'deadline':
370
+ reject(new GitError(`git ${name} did not finish within ${timeoutMs} ms`, name));
371
+ return;
372
+ case 'consumer':
373
+ reject(thrown);
374
+ return;
375
+ case 'over':
376
+ resolve({
377
+ code: STOPPED,
378
+ stdout: joined(stdout, stdoutBytes),
379
+ stderr: new TextDecoder().decode(joined(stderr, stderrBytes)),
380
+ over: true,
381
+ });
382
+ return;
383
+ default:
384
+ if (code === null) {
385
+ reject(new GitError(`git ${name} was stopped by ${endedBy ?? 'a signal'}`, name));
386
+ return;
387
+ }
388
+ resolve({
389
+ code,
390
+ stdout: joined(stdout, stdoutBytes),
391
+ stderr: new TextDecoder().decode(joined(stderr, stderrBytes)),
392
+ over: false,
393
+ });
394
+ }
395
+ }));
396
+ if (takesInput) {
397
+ // git may exit before it has read its input: its exit code says what happened.
398
+ child.stdin?.on('error', () => { });
399
+ child.stdin?.end(options.input);
400
+ }
401
+ });
402
+ }
403
+ /** `stderr` as a failure quotes it: decoded already, trimmed and cut to `STDERR_EXCERPT` characters, written as a JSON string so a name in it is inert; nothing when it holds no text. */
404
+ function excerptOf(stderr) {
405
+ const text = stderr.trim().slice(0, STDERR_EXCERPT);
406
+ return text === ''
407
+ ? ''
408
+ : `: ${JSON.stringify(text)}`;
409
+ }
410
+ /** The `GitError` of an operation that exited with a failure: `git <name> failed (exit <code>)`, then what stderr said. */
411
+ export function gitFailure(operation, run) {
412
+ const name = SUBCOMMAND[operation];
413
+ return new GitError(`git ${name} failed (exit ${run.code})${excerptOf(run.stderr)}`, name, run.code);
414
+ }
415
+ /** The `GitError` of an operation that printed more than quorum reads of it. */
416
+ function overflow(operation) {
417
+ const name = SUBCOMMAND[operation];
418
+ return new GitError(`git ${name} printed more than quorum reads`, name);
419
+ }
420
+ /** The `GitError` of an operation that exited cleanly and printed what quorum cannot read. */
421
+ function unreadable(operation) {
422
+ const name = SUBCOMMAND[operation];
423
+ return new GitError(`git ${name} printed something quorum cannot read`, name, 0);
424
+ }
425
+ /** What git printed, as a line: its last line feed dropped, and no other character. */
426
+ function lineOf(bytes) {
427
+ const text = new TextDecoder().decode(bytes);
428
+ return text.endsWith('\n')
429
+ ? text.slice(0, -1)
430
+ : text;
431
+ }
432
+ /** The `filter.*` keys of `config --show-scope -z` output: each record is `<scope>\0<key>[\n<value>]\0`. */
433
+ function parseFilterKeys(bytes) {
434
+ const tokens = new TextDecoder().decode(bytes).split('\0');
435
+ if (tokens.pop() !== '' || tokens.length % 2 !== 0)
436
+ return undefined;
437
+ const keys = [];
438
+ for (let at = 0; at < tokens.length; at += 2) {
439
+ const key = tokens[at + 1].split('\n', 1)[0];
440
+ if (tokens[at] === '' || key === '')
441
+ return undefined;
442
+ keys.push({ scope: tokens[at], key });
443
+ }
444
+ return keys;
445
+ }
446
+ /** The names of `-z` output, as bytes. */
447
+ function splitNames(bytes) {
448
+ const names = [];
449
+ let from = 0;
450
+ for (let at = bytes.indexOf(0); at !== -1; at = bytes.indexOf(0, from)) {
451
+ names.push(bytes.subarray(from, at));
452
+ from = at + 1;
453
+ }
454
+ if (from < bytes.length)
455
+ names.push(bytes.subarray(from));
456
+ return names;
457
+ }
458
+ function repositoryOf(context, top, prefix, objectFormat) {
459
+ const read = (operation, maxStdout) => runGit(context, operation, { maxStdout });
460
+ const idPrinted = (bytes) => {
461
+ const id = lineOf(bytes);
462
+ return ID_OF[objectFormat].test(id)
463
+ ? id
464
+ : undefined;
465
+ };
466
+ /** The id an operation printed: any failure, a cut and anything but a full id of the repository's format are a `GitError`. */
467
+ const idFrom = (operation, run) => {
468
+ if (run.over)
469
+ throw overflow(operation.op);
470
+ if (run.code !== 0)
471
+ throw gitFailure(operation.op, run);
472
+ const id = idPrinted(run.stdout);
473
+ if (id === undefined)
474
+ throw unreadable(operation.op);
475
+ return id;
476
+ };
477
+ const readDiff = async (operation) => {
478
+ const run = await read(operation, MAX_GIT_OUTPUT_BYTES);
479
+ if (run.over)
480
+ return undefined;
481
+ if (run.code !== 0)
482
+ throw gitFailure(operation.op, run);
483
+ return run.stdout;
484
+ };
485
+ return {
486
+ context,
487
+ top,
488
+ prefix,
489
+ objectFormat,
490
+ resolveCommit: async (revision) => {
491
+ if (!isRevision(revision))
492
+ return undefined;
493
+ const run = await read({ op: 'resolve', top, revision });
494
+ return run.code === 0 && !run.over
495
+ ? idPrinted(run.stdout)
496
+ : undefined;
497
+ },
498
+ mergeBase: async (first, second) => {
499
+ const operation = { op: 'merge-base', top, first, second };
500
+ const run = await read(operation);
501
+ return run.code === 1
502
+ ? undefined
503
+ : idFrom(operation, run);
504
+ },
505
+ emptyTree: async () => {
506
+ const operation = { op: 'empty-tree', top };
507
+ const id = idFrom(operation, await read(operation));
508
+ if (id !== EMPTY_TREE[objectFormat])
509
+ throw unreadable('empty-tree');
510
+ return id;
511
+ },
512
+ diffCommits: (from, to, attributes) => readDiff({
513
+ op: 'diff-commits',
514
+ top,
515
+ from,
516
+ to,
517
+ attributes,
518
+ }),
519
+ diffIndex: (from, attributes) => readDiff({
520
+ op: 'diff-index',
521
+ top,
522
+ from,
523
+ attributes,
524
+ }),
525
+ diffWorktree: (from, attributes) => readDiff({
526
+ op: 'diff-worktree',
527
+ top,
528
+ from,
529
+ attributes,
530
+ }),
531
+ filterConfig: async () => {
532
+ const run = await read({ op: 'filter-config', top });
533
+ if (run.over)
534
+ throw overflow('filter-config');
535
+ if (run.code === 1)
536
+ return [];
537
+ if (run.code !== 0)
538
+ throw gitFailure('filter-config', run);
539
+ const keys = parseFilterKeys(run.stdout);
540
+ if (keys === undefined)
541
+ throw unreadable('filter-config');
542
+ return keys;
543
+ },
544
+ untracked: async () => {
545
+ const run = await read({ op: 'untracked', top }, MAX_GIT_OUTPUT_BYTES);
546
+ if (run.over)
547
+ return undefined;
548
+ if (run.code !== 0)
549
+ throw gitFailure('untracked', run);
550
+ return splitNames(run.stdout);
551
+ },
552
+ };
553
+ }
554
+ const NO_WORK_TREE = 'runs inside a git work tree, and the working directory is in none: pipe a diff in instead';
555
+ const NOT_OURS = 'git refuses this repository, as another user owns it: add it to safe.directory if you trust it, or pipe a diff in';
556
+ const OTHER_WORK_TREE = 'the repository\'s work tree belongs to another repository or to none (core.worktree, GIT_WORK_TREE): run quorum in a clone you made';
557
+ /** The path an operation printed, which loses only its last line feed. */
558
+ async function readPath(context, operation) {
559
+ const run = await runGit(context, operation);
560
+ if (run.over)
561
+ throw overflow(operation.op);
562
+ if (run.code !== 0)
563
+ throw gitFailure(operation.op, run);
564
+ return lineOf(run.stdout);
565
+ }
566
+ /**
567
+ * Opens the repository the working directory is in, or refuses it with a `ConfigError` at `context.flag`.
568
+ * The calls, in order: `--version`, which must read as 2.41 or later; then `toplevel`, `prefix` and `git-dir`
569
+ * in `context.cwd`, which never enters a bare repository nested in the tree (`safe.bareRepository=explicit`
570
+ * refuses it, and so does `toplevel` outside a work tree) and which names `safe.directory` when another user
571
+ * owns the repository (`detected dubious ownership`, the only phrase of git's stderr that is read); then
572
+ * `top-git-dir` and `object-format` with `-C <top>`. A `core.worktree` can name another repository's work
573
+ * tree, which `-C <top>` would then enter and read instead, so the git directory is read from the working
574
+ * directory and again from the top level, and the two must be the same: the later calls never land in
575
+ * another repository. Each path git prints loses only its last line feed.
576
+ */
577
+ export async function openRepository(context) {
578
+ const refusal = (message) => new ConfigError([
579
+ { path: context.flag, message },
580
+ ]);
581
+ const version = await runGit(context, { op: 'version' });
582
+ const named = VERSION.exec(lineOf(version.stdout));
583
+ if (version.code !== 0 || version.over || named === null)
584
+ throw refusal('could not read the version of git: pipe a diff in instead');
585
+ const major = Number(named[1]);
586
+ const minor = Number(named[2]);
587
+ if (major < GIT_FLOOR.major || (major === GIT_FLOOR.major && minor < GIT_FLOOR.minor)) {
588
+ throw refusal(`needs git ${GIT_FLOOR.major}.${GIT_FLOOR.minor} or later, and this git is ${major}.${minor}: upgrade it, or pipe a diff in`);
589
+ }
590
+ const toplevel = await runGit(context, { op: 'toplevel' });
591
+ if (toplevel.code !== 0 || toplevel.over) {
592
+ throw refusal(toplevel.stderr.includes('detected dubious ownership')
593
+ ? NOT_OURS
594
+ : NO_WORK_TREE);
595
+ }
596
+ const top = lineOf(toplevel.stdout);
597
+ if (top === '')
598
+ throw refusal(NO_WORK_TREE);
599
+ const prefix = await readPath(context, { op: 'prefix' });
600
+ const gitDir = await readPath(context, { op: 'git-dir' });
601
+ const topGitDir = await runGit(context, { op: 'top-git-dir', top });
602
+ if (gitDir === '' || topGitDir.code !== 0 || topGitDir.over || lineOf(topGitDir.stdout) !== gitDir)
603
+ throw refusal(OTHER_WORK_TREE);
604
+ const objectFormat = await readPath(context, { op: 'object-format', top });
605
+ if (objectFormat !== 'sha1' && objectFormat !== 'sha256')
606
+ throw new GitError('git rev-parse printed an object format quorum does not read', 'rev-parse', 0);
607
+ return repositoryOf(context, top, prefix, objectFormat);
608
+ }
@@ -0,0 +1,43 @@
1
+ import type { Repository } from './run.ts';
2
+ /**
3
+ * The tree reader: what a commit holds, and what its files say, by id. `listTree` lists the commit's entries
4
+ * with `ls-tree -r -z --long`, so every size of an entry it keeps is known before any read and a kept object
5
+ * the repository lacks is refused; `readBlobs` reads blobs through one `cat-file --batch`. Neither reads
6
+ * the working tree, a `<rev>:<path>` or a pathspec: the only strings git is handed are ids this module has
7
+ * checked.
8
+ *
9
+ * @see ../../docs/95-reference/40-architecture.md for where it sits in the layers.
10
+ */
11
+ /** The modes a tracked entry has: a file, an executable, a link and a gitlink (a submodule's commit). */
12
+ export type TreeMode = '100644' | '100755' | '120000' | '160000';
13
+ /** One entry of a commit's tree. */
14
+ export interface TreeEntry {
15
+ readonly mode: TreeMode;
16
+ readonly type: 'blob' | 'commit';
17
+ /** The full id of the object: 40 lowercase hexadecimal characters in a sha1 repository, 64 in a sha256 one. */
18
+ readonly id: string;
19
+ /** The size of the blob in bytes; undefined exactly for a gitlink, which names a commit of another repository. */
20
+ readonly size: number | undefined;
21
+ /** The path as git printed it: bytes, not text, since a name can hold any byte but NUL. */
22
+ readonly path: Uint8Array;
23
+ }
24
+ /**
25
+ * The entries of `commit`, an id, in git's order, one `ls-tree -r -z --long --full-tree`. The listing is
26
+ * parsed as it streams and only the entries `keep` takes are held, each path as bytes, so a large tree costs
27
+ * what its kept paths cost. Every record git prints is checked, kept or not, and a `GitError` follows for one
28
+ * quorum cannot read (a mode, a type or a record it does not know, an id that is not the length of the
29
+ * repository's object format, a gitlink with a size, a blob with none), and for a git that fails. A blob git
30
+ * could not size, as a partial clone's missing one, is a `GitError` only when `keep` takes it: an entry the
31
+ * caller does not read costs it nothing. `undefined` once the kept paths hold more than `maxPathBytes`, which
32
+ * the child is then stopped for: no entry is a partial answer.
33
+ */
34
+ export declare function listTree(repository: Repository, commit: string, keep: (path: Uint8Array) => boolean, maxPathBytes?: number): Promise<TreeEntry[] | undefined>;
35
+ /**
36
+ * The bytes of each of `entries`' blobs, in the entries' order, through one `cat-file --batch --buffer` whose
37
+ * stdin is their ids. Each answer must be the header `<id> blob <size>`, the body of exactly that size and a
38
+ * line feed: a missing object, another type, size or id, a short answer and a byte past the last are each a
39
+ * `GitError`. The sizes are summed first, and a `ConfigError` at the run's flag comes before any spawn when
40
+ * they pass `limit`. A gitlink, which names no blob, and an id that is not 40 or 64 lowercase hexadecimal
41
+ * characters are a `RangeError`, also before any spawn. The blobs are views of one array.
42
+ */
43
+ export declare function readBlobs(repository: Repository, entries: readonly TreeEntry[], limit: number): Promise<Uint8Array[]>;