@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
@@ -27,8 +27,10 @@ export declare class ConfigError extends QuorumError {
27
27
  readonly issues: readonly ConfigIssue[];
28
28
  constructor(issues: readonly ConfigIssue[]);
29
29
  }
30
- /** What went wrong with a provider call. `retryable` is derived from it. */
31
- export type ProviderErrorKind = 'http' | 'network' | 'process' | 'timeout' | 'aborted' | 'refusal' | 'truncated' | 'invalid-response' | 'unsupported' | 'too-large';
30
+ /** Every kind of a provider call's failure: the kinds a `ProviderError` has, and the only ones a gap's detail names. */
31
+ export declare const PROVIDER_ERROR_KINDS: readonly ["http", "network", "process", "timeout", "aborted", "refusal", "truncated", "invalid-response", "unsupported", "too-large"];
32
+ /** What went wrong with a provider call. `retryable` is derived from it, unless the adapter sets it. */
33
+ export type ProviderErrorKind = typeof PROVIDER_ERROR_KINDS[number];
32
34
  /**
33
35
  * A provider call that failed. The message starts with the provider id. Adapters never put request
34
36
  * headers, keys or the runtime's own error text in it; they quote server text through `snippet`.
@@ -39,8 +41,13 @@ export declare class ProviderError extends QuorumError {
39
41
  readonly providerId: string;
40
42
  readonly kind: ProviderErrorKind;
41
43
  readonly status: number | undefined;
42
- /** True for network errors, timeouts, 408, 409, 429 and 5xx; a caller may retry the call. */
44
+ /**
45
+ * A caller may retry the call: true for network errors, timeouts, 408, 409, 429 and 5xx, unless
46
+ * the adapter set it. The core retries only `network`, `timeout` and `http` failures, whatever it says.
47
+ */
43
48
  readonly retryable: boolean;
49
+ /** The wait the server asked for at least, in milliseconds, when the adapter read one. */
50
+ readonly retryAfterMs: number | undefined;
44
51
  /** What the reply the call failed on reported, when the provider read one: the review counts it as the failed call's usage. */
45
52
  readonly usage: Usage | undefined;
46
53
  constructor(details: {
@@ -48,6 +55,8 @@ export declare class ProviderError extends QuorumError {
48
55
  kind: ProviderErrorKind;
49
56
  message: string;
50
57
  status?: number;
58
+ retryable?: boolean;
59
+ retryAfterMs?: number;
51
60
  usage?: Usage;
52
61
  cause?: unknown;
53
62
  });
@@ -52,6 +52,19 @@ export class ConfigError extends QuorumError {
52
52
  this.issues = issues;
53
53
  }
54
54
  }
55
+ /** Every kind of a provider call's failure: the kinds a `ProviderError` has, and the only ones a gap's detail names. */
56
+ export const PROVIDER_ERROR_KINDS = [
57
+ 'http',
58
+ 'network',
59
+ 'process',
60
+ 'timeout',
61
+ 'aborted',
62
+ 'refusal',
63
+ 'truncated',
64
+ 'invalid-response',
65
+ 'unsupported',
66
+ 'too-large',
67
+ ];
55
68
  const RETRYABLE_STATUSES = new Set([408, 409, 429]);
56
69
  function isRetryable(kind, status) {
57
70
  if (kind === 'network' || kind === 'timeout')
@@ -68,8 +81,13 @@ export class ProviderError extends QuorumError {
68
81
  providerId;
69
82
  kind;
70
83
  status;
71
- /** True for network errors, timeouts, 408, 409, 429 and 5xx; a caller may retry the call. */
84
+ /**
85
+ * A caller may retry the call: true for network errors, timeouts, 408, 409, 429 and 5xx, unless
86
+ * the adapter set it. The core retries only `network`, `timeout` and `http` failures, whatever it says.
87
+ */
72
88
  retryable;
89
+ /** The wait the server asked for at least, in milliseconds, when the adapter read one. */
90
+ retryAfterMs;
73
91
  /** What the reply the call failed on reported, when the provider read one: the review counts it as the failed call's usage. */
74
92
  usage;
75
93
  constructor(details) {
@@ -79,7 +97,8 @@ export class ProviderError extends QuorumError {
79
97
  this.providerId = details.providerId;
80
98
  this.kind = details.kind;
81
99
  this.status = details.status;
82
- this.retryable = isRetryable(details.kind, details.status);
100
+ this.retryable = details.retryable ?? isRetryable(details.kind, details.status);
101
+ this.retryAfterMs = details.retryAfterMs;
83
102
  this.usage = details.usage;
84
103
  }
85
104
  }
@@ -0,0 +1,45 @@
1
+ import type { ProfileRun } from './stages/context.ts';
2
+ import type { Estimate } from './types.ts';
3
+ /**
4
+ * How many times the bound of a research request over-counts the tokens of code. The bound is one token per
5
+ * UTF-8 byte, and code diffs run 2.9 to 3.8 bytes per token across the tokenizers measured, so a third of the
6
+ * bound is what code most likely takes, and a diff of prose or of encoded data takes more. It only scales the
7
+ * expected spend of an estimate: the ledger reserves the whole bound at run time.
8
+ */
9
+ export declare const BOUND_OVER_CODE = 3;
10
+ /** What the estimate reads of a quorum's settings. */
11
+ export interface EstimateSettings {
12
+ /** Whether a file's path is left out of every request. */
13
+ readonly excluded: (path: string) => boolean;
14
+ /** The most tokens of diff text one research part holds. */
15
+ readonly partTokens: number;
16
+ /** How many findings of a research reply each profile sends to the panel. */
17
+ readonly maxFindings: number;
18
+ /** How many provider calls run at once in one review. */
19
+ readonly concurrency: number;
20
+ /** The token cap of one review. */
21
+ readonly maxReviewTokens: number;
22
+ /** The deadline of one review, in milliseconds. */
23
+ readonly reviewTimeoutMs: number;
24
+ }
25
+ /**
26
+ * What a review of `diff` by `runs` may cost, before any call: nothing is sent, and no provider's `complete` is
27
+ * called, only the `room` and the `worstCase` it states, which are what the ledger reserves with. It reads the
28
+ * diff as `review` does, less the sections `excluded` leaves out and the files held back as secrets, except the
29
+ * ones `sent` names, and plans each profile's research the same way, so the reservation it states for each
30
+ * research part is the one the ledger takes for it. A diff with nothing left to read makes no call and costs
31
+ * nothing.
32
+ *
33
+ * A vote's reservation depends on a finding that does not exist yet, so each lens's is a bound: the request for
34
+ * a finding at the caps the harness cleans a finder's text to, citing the largest section of the filtered
35
+ * diff, whole for a voter that states no room or whose room holds it, else the partial context filled to its
36
+ * room. A review may cast `maxFindings` votes of each lens in each profile.
37
+ *
38
+ * `expected` counts the research parts at `1 / BOUND_OVER_CODE` of their reservation, rounded up, and the votes
39
+ * not at all: how many findings research reports is not known before it runs, so the votes are in `worst`,
40
+ * at their bound, alone. `inFlight` is the sum of the `concurrency` largest bounds among the research parts
41
+ * and the votes, each lens's counted `maxFindings` times, since the review's one limit shares its slots
42
+ * between every profile. `fits` is `expected + inFlight <= maxReviewTokens`. It is an estimate: the ledger
43
+ * still holds the cap at run time, whatever it says.
44
+ */
45
+ export declare function estimateReview(runs: readonly ProfileRun[], settings: EstimateSettings, diff: string, sent?: (path: string) => boolean): Estimate;
@@ -0,0 +1,188 @@
1
+ import { reviewScope } from "./coverage.js";
2
+ import { diffSections, splitDiff } from "./diff.js";
3
+ import { partText } from "./parts.js";
4
+ import { researchRequest, voteRequest } from "./prompts.js";
5
+ import { reservationOf, roomOf } from "./stages/context.js";
6
+ import { planResearch } from "./stages/research.js";
7
+ import { tokenBound } from "./tokens.js";
8
+ import { MAX_CATEGORY, MAX_EVIDENCE, MAX_SUMMARY } from "./verify.js";
9
+ /**
10
+ * How many times the bound of a research request over-counts the tokens of code. The bound is one token per
11
+ * UTF-8 byte, and code diffs run 2.9 to 3.8 bytes per token across the tokenizers measured, so a third of the
12
+ * bound is what code most likely takes, and a diff of prose or of encoded data takes more. It only scales the
13
+ * expected spend of an estimate: the ledger reserves the whole bound at run time.
14
+ */
15
+ export const BOUND_OVER_CODE = 3;
16
+ /**
17
+ * What a review of `diff` by `runs` may cost, before any call: nothing is sent, and no provider's `complete` is
18
+ * called, only the `room` and the `worstCase` it states, which are what the ledger reserves with. It reads the
19
+ * diff as `review` does, less the sections `excluded` leaves out and the files held back as secrets, except the
20
+ * ones `sent` names, and plans each profile's research the same way, so the reservation it states for each
21
+ * research part is the one the ledger takes for it. A diff with nothing left to read makes no call and costs
22
+ * nothing.
23
+ *
24
+ * A vote's reservation depends on a finding that does not exist yet, so each lens's is a bound: the request for
25
+ * a finding at the caps the harness cleans a finder's text to, citing the largest section of the filtered
26
+ * diff, whole for a voter that states no room or whose room holds it, else the partial context filled to its
27
+ * room. A review may cast `maxFindings` votes of each lens in each profile.
28
+ *
29
+ * `expected` counts the research parts at `1 / BOUND_OVER_CODE` of their reservation, rounded up, and the votes
30
+ * not at all: how many findings research reports is not known before it runs, so the votes are in `worst`,
31
+ * at their bound, alone. `inFlight` is the sum of the `concurrency` largest bounds among the research parts
32
+ * and the votes, each lens's counted `maxFindings` times, since the review's one limit shares its slots
33
+ * between every profile. `fits` is `expected + inFlight <= maxReviewTokens`. It is an estimate: the ledger
34
+ * still holds the cap at run time, whatever it says.
35
+ */
36
+ export function estimateReview(runs, settings, diff, sent = () => false) {
37
+ const scope = reviewScope(diff, settings.excluded, sent);
38
+ const filtered = diffSections(scope.diff);
39
+ const largest = scope.diff.trim() === ''
40
+ ? undefined
41
+ : largestSection(splitDiff(scope.diff), scope.diff);
42
+ const estimates = runs.map(run => ({
43
+ id: run.id,
44
+ estimate: largest === undefined
45
+ ? noCall()
46
+ : profileEstimate(run, planResearch(run, scope.diff, filtered, settings.partTokens), scope.diff, largest, settings.maxFindings),
47
+ }));
48
+ const profiles = estimates.map(({ estimate }) => estimate);
49
+ const expected = sum(profiles.map(profile => profile.expected));
50
+ const inFlight = reservedAtOnce(profiles, settings.maxFindings, settings.concurrency);
51
+ return {
52
+ profiles: Object.fromEntries(estimates.map(({ id, estimate }) => [id, estimate])),
53
+ expected,
54
+ worst: sum(profiles.map(profile => profile.worst)),
55
+ inFlight,
56
+ maxReviewTokens: settings.maxReviewTokens,
57
+ reviewTimeoutMs: settings.reviewTimeoutMs,
58
+ fits: expected + inFlight <= settings.maxReviewTokens,
59
+ };
60
+ }
61
+ function sum(numbers) {
62
+ return numbers.reduce((total, number) => total + number, 0);
63
+ }
64
+ /** The estimate of a profile whose research makes no call: nothing is reserved, and no vote is cast. */
65
+ function noCall() {
66
+ return {
67
+ parts: [],
68
+ votes: 0,
69
+ vote: {},
70
+ expected: 0,
71
+ worst: 0,
72
+ };
73
+ }
74
+ /** The largest section of the filtered diff, as `splitDiff` keys them; the whole diff when it keeps none, as a vote falls back on. */
75
+ function largestSection(sections, diff) {
76
+ let largest;
77
+ for (const [path, text] of sections) {
78
+ const tokens = tokenBound(text);
79
+ if (largest === undefined || tokens > largest.tokens)
80
+ largest = { path, text, tokens };
81
+ }
82
+ return largest ?? {
83
+ path: '',
84
+ text: diff,
85
+ tokens: tokenBound(diff),
86
+ };
87
+ }
88
+ /** One profile's estimate, from the plan its research follows. */
89
+ function profileEstimate(run, plan, diff, largest, maxFindings) {
90
+ const parts = researchReservations(run, plan, diff);
91
+ if (parts.length === 0)
92
+ return noCall();
93
+ const bounds = run.lenses.map(lens => voteBound(run, lens, largest));
94
+ return {
95
+ parts,
96
+ votes: maxFindings * run.lenses.length,
97
+ vote: Object.fromEntries(run.lenses.map((lens, index) => [lens.id, bounds[index]])),
98
+ expected: sum(parts.map(part => Math.ceil(part / BOUND_OVER_CODE))),
99
+ worst: sum(parts) + maxFindings * sum(bounds),
100
+ };
101
+ }
102
+ /**
103
+ * What the ledger reserves for each research request the review would send, in order, built as `research` builds
104
+ * them: one request holding the whole filtered diff when the plan has no packing, else one per part whose text is
105
+ * not blank, a plan of one part sending its text with no parts block, and a plan of several naming each part's
106
+ * position among them and the change's files. A part that holds only white space is asked of no model.
107
+ */
108
+ function researchReservations(run, plan, diff) {
109
+ const { instructions } = run.research;
110
+ const reserve = (request) => reservationOf(run.research, request);
111
+ const { packing } = plan;
112
+ if (packing === undefined) {
113
+ return [
114
+ reserve(researchRequest(instructions, diff, run.guidelines)),
115
+ ];
116
+ }
117
+ const { parts } = packing;
118
+ const { files, unlisted } = plan.listed ?? { files: [], unlisted: 0 };
119
+ return parts.flatMap((part, index) => {
120
+ const text = partText(plan.sections, packing, part);
121
+ if (text.trim() === '')
122
+ return [];
123
+ return [
124
+ reserve(parts.length === 1
125
+ ? researchRequest(instructions, text, run.guidelines)
126
+ : researchRequest(instructions, text, run.guidelines, {
127
+ index: index + 1,
128
+ count: parts.length,
129
+ files,
130
+ unlisted,
131
+ })),
132
+ ];
133
+ });
134
+ }
135
+ /** A finding as the harness leaves it at its longest: every text the finder or the diff writes at its cap, in the one character that costs a token a character. */
136
+ function longestFinding(file) {
137
+ return {
138
+ id: '',
139
+ profile: '',
140
+ file,
141
+ line: Number.MAX_SAFE_INTEGER,
142
+ category: 'x'.repeat(MAX_CATEGORY),
143
+ summary: 'x'.repeat(MAX_SUMMARY),
144
+ evidence: 'x'.repeat(MAX_EVIDENCE),
145
+ quoteMatched: true,
146
+ };
147
+ }
148
+ /**
149
+ * The most the ledger reserves for one vote of `lens`: the request for the longest finding citing the largest
150
+ * section. The section is sent whole, unless the lens's voter states a room the section exceeds, as the panel
151
+ * decides it: the room of the request with an empty diff block, and the room of the partial request, whose
152
+ * block takes the section's header and the hunks nearest the cited line that fit. Then the vote is the partial
153
+ * request filled to that room, the most such a context holds. A room of the partial request that states
154
+ * nothing, or less than 0, sends the whole section, which the provider refuses as too large.
155
+ */
156
+ function voteBound(run, lens, largest) {
157
+ const finding = longestFinding(largest.path);
158
+ const request = (context, partial = false) => voteRequest(lens.instructions, finding, context, run.guidelines, partial);
159
+ const room = roomOf(lens, request(''));
160
+ if (room !== undefined && largest.tokens > room) {
161
+ const partialRoom = roomOf(lens, request('', true));
162
+ if (partialRoom !== undefined && partialRoom >= 0)
163
+ return reservationOf(lens, request('x'.repeat(Math.min(partialRoom, largest.tokens)), true));
164
+ }
165
+ return reservationOf(lens, request(largest.text));
166
+ }
167
+ /**
168
+ * What the calls that run at once reserve: the sum of the `concurrency` largest bounds among every research part
169
+ * and every vote of every profile, a lens's vote counted `maxFindings` times, once per finding it may judge. The
170
+ * review's concurrency limit is one for all its profiles, so the bounds are taken from all of them together; with
171
+ * fewer calls than slots, every call counts.
172
+ */
173
+ function reservedAtOnce(profiles, maxFindings, concurrency) {
174
+ const calls = profiles.flatMap(({ parts, vote }) => [
175
+ ...parts.map(bound => ({ bound, count: 1 })),
176
+ ...Object.values(vote).map(bound => ({ bound, count: maxFindings })),
177
+ ]).sort((a, b) => b.bound - a.bound);
178
+ let slots = concurrency;
179
+ let reserved = 0;
180
+ for (const { bound, count } of calls) {
181
+ const taken = Math.min(count, slots);
182
+ reserved += bound * taken;
183
+ slots -= taken;
184
+ if (slots === 0)
185
+ break;
186
+ }
187
+ return reserved;
188
+ }
@@ -0,0 +1,42 @@
1
+ import type { ConfigIssue } from './errors.ts';
2
+ /** The most patterns `exclude` may hold. */
3
+ export declare const MAX_PATTERNS = 100;
4
+ /** The longest pattern, in characters. */
5
+ export declare const MAX_PATTERN_LENGTH = 256;
6
+ /** What a list of more than `MAX_PATTERNS` patterns is told. */
7
+ export declare const TOO_MANY_PATTERNS = "must hold at most 100 patterns";
8
+ /**
9
+ * The first problem with a pattern, with what to write instead, or undefined when it can be taken.
10
+ * The problems come in this order: empty, too long, a `\`, a `!`, a `{`, a trailing `/`, a `**`
11
+ * inside a name (a segment other than `**` that holds it), and an empty, `.` or `..` name (a segment
12
+ * of the pattern, less one leading `/`, that is one of them: no path in a diff has such a name, so
13
+ * the pattern would match less than its author meant). A pattern that would exclude something other
14
+ * than what its author meant is refused rather than guessed at. No message repeats the pattern.
15
+ */
16
+ export declare function patternProblem(pattern: string): string | undefined;
17
+ /**
18
+ * Every problem with a value given as `exclude`, so an untyped caller gets issues, never a
19
+ * TypeError: none when it is unset, `exclude: must be an array`, `exclude: must hold at most 100
20
+ * patterns` (the entries are then not read), or, for each entry, `exclude.<index>` with `must be a
21
+ * string` or the pattern's own problem.
22
+ */
23
+ export declare function excludeIssues(value: unknown): ConfigIssue[];
24
+ /**
25
+ * Whether `glob`, where `*` stands for any run of characters and `?` for one (a surrogate pair
26
+ * counts once), matches the whole of `name`; every other character is literal and case counts. It
27
+ * is the greedy algorithm: it goes back to the last `*` only, so it takes at most as many steps as
28
+ * the glob has characters times the name has, whatever the two hold. It compares code units, since
29
+ * indexing a string allocates a string per character on Bun.
30
+ */
31
+ export declare function matchName(glob: string, name: string): boolean;
32
+ /**
33
+ * The test of a path against checked patterns, each compiled once into its segments: `*` and `?`
34
+ * inside a name, `**` for whole directories, every other character literal and case-sensitive, and
35
+ * no pattern ever becomes a regular expression. The paths come from the diff, so an attacker
36
+ * controls them, and a matcher that backtracks would hang the review: this one is greedy, going back
37
+ * to the last star only. One pattern and one path cost at most as many steps as the pattern has
38
+ * characters times the path has, so with the caps (100 patterns of 256 characters) a review's
39
+ * matching costs at most 25 600 steps per character of path text, and an ordinary pattern a few.
40
+ * The matcher keeps no reference to the array it was given.
41
+ */
42
+ export declare function excludeMatcher(patterns: readonly string[]): (path: string) => boolean;
@@ -0,0 +1,189 @@
1
+ /** The most patterns `exclude` may hold. */
2
+ export const MAX_PATTERNS = 100;
3
+ /** The longest pattern, in characters. */
4
+ export const MAX_PATTERN_LENGTH = 256;
5
+ /** What a list of more than `MAX_PATTERNS` patterns is told. */
6
+ export const TOO_MANY_PATTERNS = `must hold at most ${MAX_PATTERNS} patterns`;
7
+ const STAR = 0x2A;
8
+ const QUESTION = 0x3F;
9
+ const HIGH_SURROGATES = [0xD800, 0xDBFF];
10
+ const LOW_SURROGATES = [0xDC00, 0xDFFF];
11
+ const WHOLE_DIRECTORIES = '**';
12
+ /** The names a segment of a pattern can hold that no path of a diff has. */
13
+ const NAMES_NO_PATH_HAS = new Set(['', '.', '..']);
14
+ /** How many code units the character at `at` takes: 2 for a surrogate pair, else 1. */
15
+ function width(text, at) {
16
+ const unit = text.charCodeAt(at);
17
+ if (unit < HIGH_SURROGATES[0] || unit > HIGH_SURROGATES[1])
18
+ return 1;
19
+ const next = text.charCodeAt(at + 1);
20
+ return next >= LOW_SURROGATES[0] && next <= LOW_SURROGATES[1]
21
+ ? 2
22
+ : 1;
23
+ }
24
+ /** The segments of a pattern with a `/` in it: those of the pattern less one leading `/`. */
25
+ function anchoredSegments(pattern) {
26
+ return (pattern.startsWith('/')
27
+ ? pattern.slice(1)
28
+ : pattern).split('/');
29
+ }
30
+ /**
31
+ * The first problem with a pattern, with what to write instead, or undefined when it can be taken.
32
+ * The problems come in this order: empty, too long, a `\`, a `!`, a `{`, a trailing `/`, a `**`
33
+ * inside a name (a segment other than `**` that holds it), and an empty, `.` or `..` name (a segment
34
+ * of the pattern, less one leading `/`, that is one of them: no path in a diff has such a name, so
35
+ * the pattern would match less than its author meant). A pattern that would exclude something other
36
+ * than what its author meant is refused rather than guessed at. No message repeats the pattern.
37
+ */
38
+ export function patternProblem(pattern) {
39
+ if (pattern === '')
40
+ return 'must not be empty';
41
+ if (pattern.length > MAX_PATTERN_LENGTH)
42
+ return `must be at most ${MAX_PATTERN_LENGTH} characters long`;
43
+ if (pattern.includes('\\'))
44
+ return 'holds \\, which escapes nothing here: write / between directories, and every other character as it is';
45
+ if (pattern.includes('!'))
46
+ return 'holds !, which negates nothing here: list only the paths to leave out';
47
+ if (pattern.includes('{'))
48
+ return 'holds {, which lists no alternatives here: write one pattern for each';
49
+ if (pattern.endsWith('/'))
50
+ return 'ends with /, so it matches no file: end it with /** to leave out what the directory holds';
51
+ const segments = anchoredSegments(pattern);
52
+ if (segments.some(segment => segment !== WHOLE_DIRECTORIES && segment.includes(WHOLE_DIRECTORIES))) {
53
+ return 'holds ** inside a name: ** stands for whole directories, as in **/*.min.js, and * for any characters of a name';
54
+ }
55
+ if (segments.some(segment => NAMES_NO_PATH_HAS.has(segment))) {
56
+ return 'holds an empty, . or .. name, which no path in a diff has: write the path from the root, as in dist/**';
57
+ }
58
+ return undefined;
59
+ }
60
+ /**
61
+ * Every problem with a value given as `exclude`, so an untyped caller gets issues, never a
62
+ * TypeError: none when it is unset, `exclude: must be an array`, `exclude: must hold at most 100
63
+ * patterns` (the entries are then not read), or, for each entry, `exclude.<index>` with `must be a
64
+ * string` or the pattern's own problem.
65
+ */
66
+ export function excludeIssues(value) {
67
+ if (value === undefined)
68
+ return [];
69
+ if (!Array.isArray(value)) {
70
+ return [
71
+ { path: 'exclude', message: 'must be an array' },
72
+ ];
73
+ }
74
+ if (value.length > MAX_PATTERNS) {
75
+ return [
76
+ { path: 'exclude', message: TOO_MANY_PATTERNS },
77
+ ];
78
+ }
79
+ // `Array.from` reads a hole as `undefined`, so it is reported like any other entry that is not a string.
80
+ return Array.from(value).flatMap((pattern, index) => {
81
+ const problem = typeof pattern === 'string'
82
+ ? patternProblem(pattern)
83
+ : 'must be a string';
84
+ return problem === undefined
85
+ ? []
86
+ : [
87
+ { path: `exclude.${index}`, message: problem },
88
+ ];
89
+ });
90
+ }
91
+ /**
92
+ * Whether `glob`, where `*` stands for any run of characters and `?` for one (a surrogate pair
93
+ * counts once), matches the whole of `name`; every other character is literal and case counts. It
94
+ * is the greedy algorithm: it goes back to the last `*` only, so it takes at most as many steps as
95
+ * the glob has characters times the name has, whatever the two hold. It compares code units, since
96
+ * indexing a string allocates a string per character on Bun.
97
+ */
98
+ export function matchName(glob, name) {
99
+ let g = 0;
100
+ let n = 0;
101
+ let star = -1;
102
+ let mark = 0;
103
+ while (n < name.length) {
104
+ if (g < glob.length && glob.charCodeAt(g) === STAR) {
105
+ star = g++;
106
+ mark = n;
107
+ }
108
+ else if (g < glob.length && glob.charCodeAt(g) === QUESTION) {
109
+ g++;
110
+ n += width(name, n);
111
+ }
112
+ else if (g < glob.length && glob.charCodeAt(g) === name.charCodeAt(n)) {
113
+ g++;
114
+ n++;
115
+ }
116
+ else if (star !== -1) {
117
+ g = star + 1;
118
+ mark += width(name, mark);
119
+ n = mark;
120
+ }
121
+ else {
122
+ return false;
123
+ }
124
+ }
125
+ while (g < glob.length && glob.charCodeAt(g) === STAR)
126
+ g++;
127
+ return g === glob.length;
128
+ }
129
+ /** Whether the segments of a pattern, `**` standing for any number of directories, match all the segments of a path: `matchName`'s loop, over segments. */
130
+ function matchPath(pattern, path) {
131
+ let p = 0;
132
+ let s = 0;
133
+ let star = -1;
134
+ let mark = 0;
135
+ while (s < path.length) {
136
+ if (p < pattern.length && pattern[p] === WHOLE_DIRECTORIES) {
137
+ star = p++;
138
+ mark = s;
139
+ }
140
+ else if (p < pattern.length && matchName(pattern[p], path[s])) {
141
+ p++;
142
+ s++;
143
+ }
144
+ else if (star !== -1) {
145
+ p = star + 1;
146
+ mark++;
147
+ s = mark;
148
+ }
149
+ else {
150
+ return false;
151
+ }
152
+ }
153
+ while (p < pattern.length && pattern[p] === WHOLE_DIRECTORIES)
154
+ p++;
155
+ return p === pattern.length;
156
+ }
157
+ /**
158
+ * The segments a checked pattern matches a path by: no `/` in it reads as `**` then the pattern, so
159
+ * it matches a file's name in any directory; else the pattern less one leading `/`, matched from the
160
+ * root; a last segment `**` gains `*` after it, so `dir/**` holds what is inside `dir` and never a
161
+ * file named `dir`; consecutive `**` collapse into one.
162
+ */
163
+ function segmentsOf(pattern) {
164
+ const segments = pattern.includes('/')
165
+ ? anchoredSegments(pattern)
166
+ : [WHOLE_DIRECTORIES, pattern];
167
+ if (segments.at(-1) === WHOLE_DIRECTORIES)
168
+ segments.push('*');
169
+ return segments.filter((segment, index) => segment !== WHOLE_DIRECTORIES || segments[index - 1] !== WHOLE_DIRECTORIES);
170
+ }
171
+ /**
172
+ * The test of a path against checked patterns, each compiled once into its segments: `*` and `?`
173
+ * inside a name, `**` for whole directories, every other character literal and case-sensitive, and
174
+ * no pattern ever becomes a regular expression. The paths come from the diff, so an attacker
175
+ * controls them, and a matcher that backtracks would hang the review: this one is greedy, going back
176
+ * to the last star only. One pattern and one path cost at most as many steps as the pattern has
177
+ * characters times the path has, so with the caps (100 patterns of 256 characters) a review's
178
+ * matching costs at most 25 600 steps per character of path text, and an ordinary pattern a few.
179
+ * The matcher keeps no reference to the array it was given.
180
+ */
181
+ export function excludeMatcher(patterns) {
182
+ const compiled = patterns.map(segmentsOf);
183
+ if (compiled.length === 0)
184
+ return () => false;
185
+ return (path) => {
186
+ const parts = path.split('/');
187
+ return compiled.some(segments => matchPath(segments, parts));
188
+ };
189
+ }
@@ -1,4 +1,4 @@
1
- import type { Flag } from './types.ts';
1
+ import type { Flag, LeftOutFile } from './types.ts';
2
2
  /**
3
3
  * The advisory flags of a diff, read by code from its sections before any model sees it. They tell
4
4
  * a human where to look and never change a verdict, a confidence or an exit code.
@@ -22,3 +22,16 @@ import type { Flag } from './types.ts';
22
22
  * zero-width characters, inside a word or between words, is found and its line raises both flags.
23
23
  */
24
24
  export declare function diffFlags(sections: ReadonlyMap<string, string>): Flag[];
25
+ /**
26
+ * The flags of the files left out as secrets, in the order they are listed: one `secret-file` flag for
27
+ * each `skipped` entry of the rule `secret` (a source skipped it, by its name or, when its name is no
28
+ * secret's, by a credential it holds), for each `secret` entry (held back from the diff, by its name or by
29
+ * the kind of credential it holds) and for each `deleted-secret` entry (the change deletes it whole: the
30
+ * history still holds it, so rotate what it held). Each is at the file's own path, absent for the empty
31
+ * name that stands for the text no header names, and with no line, since no model saw the file and the
32
+ * flag quotes none of it. A person should look at whether the file belongs in the change, or rotate what
33
+ * it held. An entry an `exclude` pattern matched first is `excluded`, so it raises none: leaving it out
34
+ * was the operator's choice, and a file the input sends is never held. Like every flag, it changes no
35
+ * verdict and no exit code.
36
+ */
37
+ export declare function secretFlags(leftOut: readonly LeftOutFile[]): Flag[];
@@ -1,5 +1,6 @@
1
1
  import { addedLines } from "./diff.js";
2
2
  import { hiddenLabels, spaceHidden, stripHidden } from "./sanitize.js";
3
+ import { CREDENTIAL_PHRASES, isSecretName } from "./secrets.js";
3
4
  /** How many code points or patterns a flag's detail names before it counts the rest. */
4
5
  const MAX_LISTED = 8;
5
6
  /** A byte-order mark: an editor may write one at the start of a file, so it is not flagged there. */
@@ -11,6 +12,15 @@ const TAB = 'U+0009';
11
12
  * characters belong to the emoji, so they are not flagged. Outside such a sequence they are.
12
13
  */
13
14
  const EMOJI = /\p{RGI_Emoji}/gv;
15
+ /**
16
+ * What a `secret-file` flag says, in words the code writes: a file a path review skipped, by its name or by
17
+ * a credential it holds, and a file held back from the review of a diff, held or deleted whole, by its name
18
+ * or by a kind of credential. It names the kind and never a line of the file.
19
+ */
20
+ const SKIPPED_BY_NAME = 'named as a secret, so a path review sent none of it: check that it belongs in the repository';
21
+ const SKIPPED_BY_CONTENT = 'holds what reads as a credential, so a path review sent none of it: remove it from the repository, and rotate it if it is real';
22
+ const HELD_BY_NAME = 'named as a secret, so no model was sent any of it: check that it belongs in the change';
23
+ const DELETED_BY_NAME = 'deletes a file named as a secret, so no model was sent any of it: the history still holds the file, so rotate what it held';
14
24
  /**
15
25
  * Text that speaks to an AI reviewer instead of a person, in forms rare in ordinary code: the
16
26
  * markup of chat templates and tool calls (in the research run, only LLM libraries held any),
@@ -130,3 +140,49 @@ export function diffFlags(sections) {
130
140
  }
131
141
  return flags;
132
142
  }
143
+ /** What a `secret-file` flag says of a file left out, or undefined when the file is no secret. */
144
+ function secretDetail(entry) {
145
+ switch (entry.reason) {
146
+ case 'skipped':
147
+ if (entry.rule !== 'secret')
148
+ return undefined;
149
+ return isSecretName(entry.file)
150
+ ? SKIPPED_BY_NAME
151
+ : SKIPPED_BY_CONTENT;
152
+ case 'secret':
153
+ return entry.rule === 'name'
154
+ ? HELD_BY_NAME
155
+ : `holds what reads as ${CREDENTIAL_PHRASES[entry.rule]}, so no model was sent any of it: keep it out of the repository, and rotate it if it is real`;
156
+ case 'deleted-secret':
157
+ return entry.rule === 'name'
158
+ ? DELETED_BY_NAME
159
+ : `deletes a file that holds what reads as ${CREDENTIAL_PHRASES[entry.rule]}, so no model was sent any of it: the history still holds it, so rotate it`;
160
+ default:
161
+ return undefined;
162
+ }
163
+ }
164
+ /**
165
+ * The flags of the files left out as secrets, in the order they are listed: one `secret-file` flag for
166
+ * each `skipped` entry of the rule `secret` (a source skipped it, by its name or, when its name is no
167
+ * secret's, by a credential it holds), for each `secret` entry (held back from the diff, by its name or by
168
+ * the kind of credential it holds) and for each `deleted-secret` entry (the change deletes it whole: the
169
+ * history still holds it, so rotate what it held). Each is at the file's own path, absent for the empty
170
+ * name that stands for the text no header names, and with no line, since no model saw the file and the
171
+ * flag quotes none of it. A person should look at whether the file belongs in the change, or rotate what
172
+ * it held. An entry an `exclude` pattern matched first is `excluded`, so it raises none: leaving it out
173
+ * was the operator's choice, and a file the input sends is never held. Like every flag, it changes no
174
+ * verdict and no exit code.
175
+ */
176
+ export function secretFlags(leftOut) {
177
+ return leftOut.flatMap((entry) => {
178
+ const detail = secretDetail(entry);
179
+ if (detail === undefined)
180
+ return [];
181
+ const where = entry.file === ''
182
+ ? {}
183
+ : { file: entry.file };
184
+ return [
185
+ { code: 'secret-file', ...where, detail },
186
+ ];
187
+ });
188
+ }