@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,223 @@
1
+ import type { ChildProcess, SpawnOptions } from 'node:child_process';
2
+ import type { Clock } from '../core/clock.ts';
3
+ import { QuorumError } from '../core/errors.ts';
4
+ import type { ObjectFormat } from '../core/types.ts';
5
+ /**
6
+ * The one place quorum runs git: a closed set of typed operations (`GitOperation`), each built into one
7
+ * argument vector by `gitArgs` and spawned by `runGit` with no shell, and `openRepository`, which checks a
8
+ * working directory and hands back the operations the sources call. Quorum reviews repositories it was
9
+ * handed, so nothing a repository holds may run a program or reshape the bytes git prints.
10
+ *
11
+ * @see ../../docs/95-reference/40-architecture.md for where it sits in the layers.
12
+ */
13
+ /** The oldest git quorum runs: `--attr-source` came with 2.41, and every other option it pins is older. */
14
+ export declare const GIT_FLOOR: Readonly<{
15
+ major: 2;
16
+ minor: 41;
17
+ }>;
18
+ /** The deadline of one git call, on the injected clock. */
19
+ export declare const GIT_TIMEOUT_MS = 120000;
20
+ /** 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. */
21
+ export declare const MAX_GIT_OUTPUT_BYTES: number;
22
+ /** The most of a child's stderr that is kept; the rest is read and dropped. */
23
+ export declare const MAX_GIT_STDERR_BYTES = 65536;
24
+ /** The most `--version`, `rev-parse`, `merge-base`, `hash-object` and `config` print. */
25
+ export declare const MAX_GIT_SMALL_OUTPUT_BYTES = 65536;
26
+ /** The characters of git's stderr a `GitError` quotes. */
27
+ export declare const STDERR_EXCERPT = 500;
28
+ /** 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. */
29
+ export declare const GLOBAL_PINS: readonly string[];
30
+ /** After `diff`: the options that give one form of diff whatever the repository's `diff.*` and `color.*` config says. */
31
+ export declare const DIFF_PINS: readonly string[];
32
+ /** The variables of the parent's environment a child gets, when the parent holds them as its own strings. Every other variable is dropped. */
33
+ export declare const ENVIRONMENT_ALLOWLIST: readonly string[];
34
+ /** 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. */
35
+ export declare class GitError extends QuorumError {
36
+ /** The git subcommand the call ran: `diff`, `rev-parse`, `ls-tree`, and `version` for `--version`. */
37
+ readonly operation: string;
38
+ /** The exit code, or null when there was none: the child did not start or did not finish. */
39
+ readonly exitCode: number | null;
40
+ constructor(message: string, operation: string, exitCode?: number | null);
41
+ }
42
+ /** `spawn`, as the runner calls it, so a spec injects its own. */
43
+ export type SpawnGit = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
44
+ /** What every git call of a review runs with. */
45
+ export interface GitContext {
46
+ /** The absolute path of the git executable. */
47
+ readonly git: string;
48
+ /** The directory the child starts in: the user's working directory. */
49
+ readonly cwd: string;
50
+ /** The parent's environment; `gitEnvironment` picks what a child gets of it. */
51
+ readonly env: Readonly<Record<string, string | undefined>>;
52
+ /** The flag a `ConfigError` of this run names as its issue path: `--range`, `--local`, `--staged` or `--path`. */
53
+ readonly flag: string;
54
+ readonly signal?: AbortSignal;
55
+ readonly spawn?: SpawnGit;
56
+ /** The clock the deadline runs on; the system's when unset. */
57
+ readonly clock?: Clock;
58
+ /** The deadline of each call; `GIT_TIMEOUT_MS` when unset. */
59
+ readonly timeoutMs?: number;
60
+ }
61
+ /**
62
+ * What a child gets of the parent's environment: each name of `ENVIRONMENT_ALLOWLIST` the parent holds as its
63
+ * own string, then quorum's own seven variables, which win. Nothing else passes: not `GIT_DIFF_OPTS` or
64
+ * `GIT_EXTERNAL_DIFF`, not `GIT_CONFIG_PARAMETERS` or `GIT_CONFIG_COUNT`, not a pager, not a key.
65
+ */
66
+ export declare function gitEnvironment(env: GitContext['env']): Record<string, string>;
67
+ /** The calls quorum makes: the ones that name the repository, then the reads of one. `top` is the top level `openRepository` found. */
68
+ export type GitOperation = {
69
+ readonly op: 'version';
70
+ } | {
71
+ readonly op: 'toplevel';
72
+ } | {
73
+ readonly op: 'prefix';
74
+ } | {
75
+ readonly op: 'git-dir';
76
+ } | {
77
+ readonly op: 'top-git-dir';
78
+ readonly top: string;
79
+ } | {
80
+ readonly op: 'object-format';
81
+ readonly top: string;
82
+ } | {
83
+ readonly op: 'resolve';
84
+ readonly top: string;
85
+ readonly revision: string;
86
+ } | {
87
+ readonly op: 'merge-base';
88
+ readonly top: string;
89
+ readonly first: string;
90
+ readonly second: string;
91
+ } | {
92
+ readonly op: 'empty-tree';
93
+ readonly top: string;
94
+ } | {
95
+ readonly op: 'diff-commits';
96
+ readonly top: string;
97
+ readonly from: string;
98
+ readonly to: string;
99
+ readonly attributes: string;
100
+ } | {
101
+ readonly op: 'diff-index';
102
+ readonly top: string;
103
+ readonly from: string;
104
+ readonly attributes: string;
105
+ } | {
106
+ readonly op: 'diff-worktree';
107
+ readonly top: string;
108
+ readonly from: string;
109
+ readonly attributes: string;
110
+ } | {
111
+ readonly op: 'filter-config';
112
+ readonly top: string;
113
+ } | {
114
+ readonly op: 'untracked';
115
+ readonly top: string;
116
+ } | {
117
+ readonly op: 'list-tree';
118
+ readonly top: string;
119
+ readonly commit: string;
120
+ } | {
121
+ readonly op: 'read-objects';
122
+ readonly top: string;
123
+ };
124
+ /** An id as it goes into a vector: 40 or 64 lowercase hexadecimal characters, else a `RangeError` that does not repeat it. */
125
+ export declare function checkedId(value: string): string;
126
+ /**
127
+ * The argument vector of `operation`: `GLOBAL_PINS`, then the operation's own words. Every id is checked
128
+ * first, as 40 or 64 lowercase hexadecimal characters, and a revision, the one string a user gives git, as
129
+ * not empty and not an option (it follows `--end-of-options` besides): a `RangeError` otherwise, before any
130
+ * vector is built. Every diff ends with `--`, so no name is read as a revision.
131
+ */
132
+ export declare function gitArgs(operation: GitOperation): string[];
133
+ /** What a git call came to, whatever its exit code. */
134
+ export interface GitRun {
135
+ /** The exit code; -1 when quorum stopped the child, at its stdout cap or at the consumer's word, which `over` says. */
136
+ readonly code: number;
137
+ /** What the child printed, up to the cap: empty when the consumer was handed each chunk. */
138
+ readonly stdout: Uint8Array;
139
+ /** The first 64 KiB of stderr, decoded. */
140
+ readonly stderr: string;
141
+ /** Whether the child was stopped for printing more than was read, so `stdout` is a cut and no answer. */
142
+ readonly over: boolean;
143
+ }
144
+ /** `chunks` as one array of `size` bytes, their total. */
145
+ export declare function joined(chunks: readonly Uint8Array[], size: number): Uint8Array;
146
+ /**
147
+ * Runs one operation: spawns `context.git` with `gitArgs`'s vector and `gitEnvironment`'s environment, with
148
+ * no shell, from `context.cwd`, its stdin ignored unless the operation takes input (`empty-tree` and
149
+ * `read-objects`, which get `options.input` and an end). It resolves for any exit code, with stdout up to
150
+ * `options.maxStdout` (`MAX_GIT_SMALL_OUTPUT_BYTES` unless a caller says) and the first 64 KiB of stderr; a
151
+ * child that prints more is killed and the run says `over`. With `options.onStdout` each chunk is handed over
152
+ * and not kept, and `false` stops the child, `over` again. It rejects with a `GitError` when git cannot start,
153
+ * passes its deadline (`GIT_TIMEOUT_MS` on the context's clock) or is ended by a signal quorum did not send,
154
+ * and with the signal's reason when `context.signal` aborts. Quorum's own stops, at a cap, a deadline or an
155
+ * abort, are SIGKILL, after which the child's pipes are destroyed so that a helper holding them cannot keep
156
+ * the call open. The timer and the listener are gone on every path.
157
+ *
158
+ * What is pinned, and what the prototype on git 2.50.1 saw without it:
159
+ * - `core.fsmonitor`, `core.hooksPath` and the pager (`--no-pager`, `core.pager`, `GIT_PAGER`): a repository's
160
+ * own config ran its marker programs as fsmonitor, as hooks and, under a pseudo-terminal, as the pager.
161
+ * - `--no-ext-diff`, `--no-textconv` and `core.attributesFile`, with `--attr-source=<commit>` on each diff:
162
+ * `diff.external`, a text converter and a driver's `command` ran, and `.gitattributes` and `info/attributes`
163
+ * named them. Every operation ran nothing but the working-tree diff, whose filters the trust check refuses.
164
+ * - `--no-replace-objects` and `GIT_NO_REPLACE_OBJECTS`: a replace ref swapped a blob for another.
165
+ * - `diff.autoRefreshIndex=false`, `--no-optional-locks` and `GIT_OPTIONAL_LOCKS`: a working-tree diff
166
+ * rewrote `.git/index`, a stat refresh, and quorum never writes to a repository.
167
+ * - The `DIFF_PINS`, `core.quotePath` and `diff.suppressBlankEmpty`: a hostile `diff.algorithm`,
168
+ * `diff.context`, `diff.renames`, `core.abbrev`, `diff.orderFile` and the like changed the bytes of a diff.
169
+ * - `--` after every diff: a tracked file named after a commit id made `git diff <id> <id>` fatal.
170
+ * - `GIT_NO_LAZY_FETCH` and an empty `GIT_ALLOW_PROTOCOL`: a partial clone fetched a missing blob; each alone
171
+ * stops it, and the allowlist holds on every release.
172
+ * - `safe.bareRepository=explicit`: a bare repository committed in the tree was refused from inside it.
173
+ * - The environment allowlist: `GIT_DIFF_OPTS` and `GIT_EXTERNAL_DIFF` of the parent reshaped and ran.
174
+ */
175
+ export declare function runGit(context: GitContext, operation: GitOperation, options?: {
176
+ readonly input?: Uint8Array | string;
177
+ readonly maxStdout?: number;
178
+ readonly onStdout?: (chunk: Uint8Array) => boolean;
179
+ }): Promise<GitRun>;
180
+ /** The `GitError` of an operation that exited with a failure: `git <name> failed (exit <code>)`, then what stderr said. */
181
+ export declare function gitFailure(operation: GitOperation['op'], run: GitRun): GitError;
182
+ /** One config entry of a filter: where git read it from, and its key. */
183
+ export interface FilterKey {
184
+ readonly scope: string;
185
+ readonly key: string;
186
+ }
187
+ /** A repository a source reads, opened by `openRepository`. A diff or a listing over its cap is `undefined`. */
188
+ export interface Repository {
189
+ readonly context: GitContext;
190
+ /** The top level of the work tree, as git prints it. */
191
+ readonly top: string;
192
+ /** The path of the working directory under the top level, as git prints it: empty at the top, else ending with `/`. */
193
+ readonly prefix: string;
194
+ readonly objectFormat: ObjectFormat;
195
+ /** The full id of the commit `revision` names, or undefined for any failure: git's stderr there quotes the revision as typed, so it is never read. */
196
+ readonly resolveCommit: (revision: string) => Promise<string | undefined>;
197
+ /** The merge base of two commits, undefined when they share no history. */
198
+ readonly mergeBase: (first: string, second: string) => Promise<string | undefined>;
199
+ /** The id of the empty tree of the repository's object format, as git prints it and as the format's constant says: any other reply is a `GitError`. */
200
+ readonly emptyTree: () => Promise<string>;
201
+ /** The diff from commit `from` to commit `to`, its attributes read from the commit `attributes`. */
202
+ readonly diffCommits: (from: string, to: string, attributes: string) => Promise<Uint8Array | undefined>;
203
+ /** The diff of the index against commit `from`. */
204
+ readonly diffIndex: (from: string, attributes: string) => Promise<Uint8Array | undefined>;
205
+ /** The diff of the working tree against commit `from`; it runs the filters the repository's config names. */
206
+ readonly diffWorktree: (from: string, attributes: string) => Promise<Uint8Array | undefined>;
207
+ /** Every `filter.<name>.clean`, `.smudge` and `.process` key of the repository's config, with its scope. */
208
+ readonly filterConfig: () => Promise<FilterKey[]>;
209
+ /** The names of the untracked files that are not ignored, as git prints them, each as its bytes. */
210
+ readonly untracked: () => Promise<Uint8Array[] | undefined>;
211
+ }
212
+ /**
213
+ * Opens the repository the working directory is in, or refuses it with a `ConfigError` at `context.flag`.
214
+ * The calls, in order: `--version`, which must read as 2.41 or later; then `toplevel`, `prefix` and `git-dir`
215
+ * in `context.cwd`, which never enters a bare repository nested in the tree (`safe.bareRepository=explicit`
216
+ * refuses it, and so does `toplevel` outside a work tree) and which names `safe.directory` when another user
217
+ * owns the repository (`detected dubious ownership`, the only phrase of git's stderr that is read); then
218
+ * `top-git-dir` and `object-format` with `-C <top>`. A `core.worktree` can name another repository's work
219
+ * tree, which `-C <top>` would then enter and read instead, so the git directory is read from the working
220
+ * directory and again from the top level, and the two must be the same: the later calls never land in
221
+ * another repository. Each path git prints loses only its last line feed.
222
+ */
223
+ export declare function openRepository(context: GitContext): Promise<Repository>;