@vaultcompass/conductor 0.9.0 → 0.11.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.
@@ -3,10 +3,17 @@ export declare const PLAN_DIR = "docs/superpowers/plans";
3
3
  export type SpecDiscovery =
4
4
  /** Found, with the source that won. Paths are repository-relative. */
5
5
  {
6
- kind: 'flag' | 'pr-body' | 'convention';
6
+ kind: 'flag' | 'pr-body';
7
7
  spec: string;
8
8
  plan: string | null;
9
9
  }
10
+ /** Found by the branch-name convention, with how it was chosen. */
11
+ | {
12
+ kind: 'convention';
13
+ spec: string;
14
+ plan: string | null;
15
+ match: ConventionMatch;
16
+ }
10
17
  /** `--spec` named a file that is not there. Never silently replaced. */
11
18
  | {
12
19
  kind: 'missing-flag';
@@ -25,8 +32,11 @@ export type SpecDiscovery =
25
32
  | {
26
33
  kind: 'escaped';
27
34
  path: string;
28
- } | {
35
+ }
36
+ /** Nothing found. `selection` is present when a branch was available. */
37
+ | {
29
38
  kind: 'none';
39
+ selection?: SelectionMiss;
30
40
  };
31
41
  /**
32
42
  * The token that turns a `Spec:` line into a waiver.
@@ -64,8 +74,98 @@ export declare function branchSlug(branch: string): string;
64
74
  * importer pairs them.
65
75
  */
66
76
  export declare function normalizeStem(fileName: string): string;
67
- /** Whether a normalized stem and a slug name the same work. */
68
- export declare function stemMatches(stem: string, slug: string): boolean;
77
+ /**
78
+ * The shortest token that can be evidence for a binding.
79
+ *
80
+ * Two-letter tokens (pr, ci, ui, db, v2) are the shape of the dogfood failure
81
+ * this rule exists to close, and they recur across unrelated work. Three
82
+ * keeps the short domain words a team actually names features after (api,
83
+ * cli, osv).
84
+ */
85
+ export declare const MIN_TOKEN_LENGTH = 3;
86
+ /**
87
+ * Words that appear in branch and spec names because of the naming
88
+ * convention, not because of the feature. Closed and pinned exactly by a
89
+ * test. A stop word is ignored as EVIDENCE, never deleted from a sequence: it
90
+ * still occupies its position for the contiguity test.
91
+ */
92
+ export declare const STOP_WORDS: readonly string[];
93
+ /**
94
+ * A branch slug or a spec stem as a sequence of whole words.
95
+ *
96
+ * ASCII letters only are folded, never toLowerCase(): that maps U+212A
97
+ * KELVIN SIGN to an ASCII k, so a branch spelled with one would fold into an
98
+ * ASCII word and could bind a spec. The delimiters are ASCII only for the
99
+ * same reason, never \s, which also matches Unicode whitespace git allows in
100
+ * a ref name (U+00A0 and the rest). A non-ASCII character therefore survives
101
+ * unchanged inside its token, and the charset rule in isSignificant keeps
102
+ * that token from ever counting. A dot is not a delimiter: 1.2.1 is one token.
103
+ */
104
+ export declare function tokens(text: string): string[];
105
+ /**
106
+ * Whether a token can be evidence for a binding: three or more characters,
107
+ * letters digits and dots only, at least one letter, and not a stop word.
108
+ * The charset rule is also what keeps every word the report prints as
109
+ * "shared" free of markup, whatever the head branch was called.
110
+ */
111
+ export declare function isSignificant(token: string): boolean;
112
+ /**
113
+ * Whether a spec stem is a candidate for a branch slug, and on what words.
114
+ *
115
+ * The shorter token sequence must appear as ONE CONTIGUOUS RUN of the longer,
116
+ * compared token by token, in either direction, and that run must hold a
117
+ * significant token. This is the old substring test moved from characters to
118
+ * whole tokens and nothing looser: on tokens(x).join("-") of both sides,
119
+ * every candidate here is one the substring rule also accepts.
120
+ */
121
+ export declare function candidateRun(slug: string, stem: string): {
122
+ exact: boolean;
123
+ shared: string[];
124
+ } | null;
125
+ /** How a convention selection was made, carried to every report surface. */
126
+ export interface ConventionMatch {
127
+ strength: 'exact' | 'strong' | 'weak';
128
+ weakBecause: Array<'single-token' | 'length-tiebreak'>;
129
+ /** The significant tokens of the shared run, charset-restricted. */
130
+ shared: string[];
131
+ /** The next stem group's member, if any. */
132
+ runnerUp: string | null;
133
+ /** The runner-up's shared significant tokens, for the length-tiebreak wording. */
134
+ runnerUpShared: string[];
135
+ /**
136
+ * What 0.10.0's substring rule would have chosen, when that differs from
137
+ * this choice; null when it is the same file. Reporting only.
138
+ */
139
+ legacy: string | null;
140
+ }
141
+ /** Why the convention chose nothing, when a branch was available. */
142
+ export interface SelectionMiss {
143
+ why: 'no-usable-token' | 'no-candidate' | 'ambiguous';
144
+ /** Ambiguous only: every tied group's member, sorted lexically, in full. */
145
+ tied: string[];
146
+ /** What 0.10.0's substring rule would have chosen. Reporting only. */
147
+ legacy: string | null;
148
+ }
149
+ export type BranchSelection = ({
150
+ kind: 'selected';
151
+ name: string;
152
+ } & ConventionMatch) | ({
153
+ kind: 'none';
154
+ } & SelectionMiss);
155
+ /**
156
+ * The branch-name convention's choice among `names` (spec filenames), the one
157
+ * function both selection paths call, on the working tree and at the trust
158
+ * base.
159
+ *
160
+ * Candidates are grouped by their folded stem sequence; a group's member is
161
+ * its lexically greatest filename. Groups are ranked by an exact sequence,
162
+ * then the number of significant shared tokens, then the length of the
163
+ * longest one. A tie on all three between the top two groups chooses
164
+ * NOTHING: every key the old code used after the first was a guess about
165
+ * which feature the branch meant, and a tie on everything this measures is
166
+ * the code saying it does not know.
167
+ */
168
+ export declare function selectByBranch(names: string[], branch: string): BranchSelection;
69
169
  /**
70
170
  * The path named by a `Spec:` line in a pull request body.
71
171
  *
@@ -82,22 +182,8 @@ export declare function stemMatches(stem: string, slug: string): boolean;
82
182
  export declare function specFromPrBody(body: string): string | null;
83
183
  /** `pull_request.body` out of a GitHub event payload, or null. */
84
184
  export declare function prBodyFromEvent(eventPath: string): string | null;
85
- /**
86
- * The best of the candidates whose stem relates to `target`, or undefined.
87
- *
88
- * `stemMatches` decides who is a CANDIDATE; this decides who wins, and the
89
- * two are different questions. Ranking on the lexically newest filename alone
90
- * was answering the second with the first: a loose candidate carrying a later
91
- * date beat the spec whose stem was the branch slug exactly, and an undated
92
- * name beat everything because it sorts after every date. A pull request was
93
- * then measured against a different feature's requirements, with nothing in
94
- * the report saying so, since naming the spec it used is exactly what the
95
- * report does.
96
- *
97
- * So: an exact stem first, then the most specific stem, and only then the
98
- * newest name. Specificity is stem LENGTH, which is crude but is the property
99
- * the failure actually had: "superpowers" beat
100
- * "1.2.1-base-and-superpowers" by being shorter and vaguer.
101
- */
102
- export declare function bestMatch(names: string[], target: string): string | undefined;
185
+ /** The match record of a selection, without its discriminant and name. */
186
+ export declare function matchOf(selection: Extract<BranchSelection, {
187
+ kind: 'selected';
188
+ }>): ConventionMatch;
103
189
  export declare function discoverSpec(options: SpecDiscoveryOptions): SpecDiscovery;
@@ -29,9 +29,10 @@
29
29
  // explicit statement beats the inferred convention below.
30
30
  //
31
31
  // 3. The convention: a markdown file directly under docs/superpowers/specs
32
- // whose name relates to the branch. Directly under, not nested, because
33
- // that is the layout intent-guard's own importer discovers and an
34
- // archive subdirectory is not a candidate for this branch's contract.
32
+ // whose name matches the branch on WHOLE WORDS (selectByBranch below).
33
+ // Directly under, not nested, because that is the layout intent-guard's
34
+ // own importer discovers and an archive subdirectory is not a candidate
35
+ // for this branch's contract.
35
36
  import { readFileSync, readdirSync, realpathSync } from 'node:fs';
36
37
  import path from 'node:path';
37
38
  export const SPEC_DIR = 'docs/superpowers/specs';
@@ -69,12 +70,197 @@ export function normalizeStem(fileName) {
69
70
  const stem = fileName.replace(/\.md$/i, '');
70
71
  return stem.replace(/^\d{4}-\d{2}-\d{2}-/, '').replace(/-design$/, '');
71
72
  }
72
- /** Whether a normalized stem and a slug name the same work. */
73
- export function stemMatches(stem, slug) {
74
- if (stem === '' || slug === '') {
75
- return false;
73
+ /**
74
+ * The shortest token that can be evidence for a binding.
75
+ *
76
+ * Two-letter tokens (pr, ci, ui, db, v2) are the shape of the dogfood failure
77
+ * this rule exists to close, and they recur across unrelated work. Three
78
+ * keeps the short domain words a team actually names features after (api,
79
+ * cli, osv).
80
+ */
81
+ export const MIN_TOKEN_LENGTH = 3;
82
+ /**
83
+ * Words that appear in branch and spec names because of the naming
84
+ * convention, not because of the feature. Closed and pinned exactly by a
85
+ * test. A stop word is ignored as EVIDENCE, never deleted from a sequence: it
86
+ * still occupies its position for the contiguity test.
87
+ */
88
+ export const STOP_WORDS = Object.freeze([
89
+ // Change-type words
90
+ 'feat', 'feature', 'fix', 'bugfix', 'hotfix', 'chore', 'docs',
91
+ 'refactor', 'test', 'tests', 'wip', 'release', 'build', 'perf',
92
+ 'style', 'revert', 'deps', 'bump',
93
+ // Convention words
94
+ 'design', 'spec', 'specs', 'plan', 'draft', 'review', 'followup',
95
+ 'temp', 'tmp',
96
+ // Function words
97
+ 'and', 'the', 'for', 'with', 'from', 'into', 'onto', 'per', 'via', 'not',
98
+ 'add', 'use', 'new', 'more', 'misc',
99
+ ]);
100
+ const STOP_WORD_SET = new Set(STOP_WORDS);
101
+ /**
102
+ * A branch slug or a spec stem as a sequence of whole words.
103
+ *
104
+ * ASCII letters only are folded, never toLowerCase(): that maps U+212A
105
+ * KELVIN SIGN to an ASCII k, so a branch spelled with one would fold into an
106
+ * ASCII word and could bind a spec. The delimiters are ASCII only for the
107
+ * same reason, never \s, which also matches Unicode whitespace git allows in
108
+ * a ref name (U+00A0 and the rest). A non-ASCII character therefore survives
109
+ * unchanged inside its token, and the charset rule in isSignificant keeps
110
+ * that token from ever counting. A dot is not a delimiter: 1.2.1 is one token.
111
+ */
112
+ export function tokens(text) {
113
+ return text
114
+ .replace(/[A-Z]/g, (letter) => String.fromCharCode(letter.charCodeAt(0) + 32))
115
+ .split(/[-_/ \t\n\r\f\v]+/)
116
+ .filter((token) => token !== '');
117
+ }
118
+ /**
119
+ * Whether a token can be evidence for a binding: three or more characters,
120
+ * letters digits and dots only, at least one letter, and not a stop word.
121
+ * The charset rule is also what keeps every word the report prints as
122
+ * "shared" free of markup, whatever the head branch was called.
123
+ */
124
+ export function isSignificant(token) {
125
+ return (token.length >= MIN_TOKEN_LENGTH &&
126
+ /^[a-z0-9.]+$/.test(token) &&
127
+ /[a-z]/.test(token) &&
128
+ !STOP_WORD_SET.has(token));
129
+ }
130
+ /** Where `needle` sits as one contiguous run of `haystack`, or -1. */
131
+ function runAt(haystack, needle) {
132
+ for (let start = 0; start + needle.length <= haystack.length; start++) {
133
+ if (needle.every((token, offset) => haystack[start + offset] === token)) {
134
+ return start;
135
+ }
76
136
  }
77
- return stem.includes(slug) || slug.includes(stem);
137
+ return -1;
138
+ }
139
+ function candidateOnTokens(slug, stem) {
140
+ if (slug.length === 0 || stem.length === 0) {
141
+ return null;
142
+ }
143
+ const [longer, shorter] = slug.length >= stem.length ? [slug, stem] : [stem, slug];
144
+ if (runAt(longer, shorter) === -1) {
145
+ return null;
146
+ }
147
+ const shared = shorter.filter(isSignificant);
148
+ if (shared.length === 0) {
149
+ return null;
150
+ }
151
+ return { exact: slug.length === stem.length, shared };
152
+ }
153
+ /**
154
+ * Whether a spec stem is a candidate for a branch slug, and on what words.
155
+ *
156
+ * The shorter token sequence must appear as ONE CONTIGUOUS RUN of the longer,
157
+ * compared token by token, in either direction, and that run must hold a
158
+ * significant token. This is the old substring test moved from characters to
159
+ * whole tokens and nothing looser: on tokens(x).join("-") of both sides,
160
+ * every candidate here is one the substring rule also accepts.
161
+ */
162
+ export function candidateRun(slug, stem) {
163
+ return candidateOnTokens(tokens(slug), tokens(stem));
164
+ }
165
+ /**
166
+ * 0.10.0's convention rule, verbatim: a character substring test in either
167
+ * direction, then an exact stem, the longer stem, the lexically greatest
168
+ * filename. Kept for one minor release for the legacy sentence in the report
169
+ * and for nothing else; it never selects.
170
+ */
171
+ function legacySelection(names, slug) {
172
+ const contains = (stem) => stem !== '' && slug !== '' && (stem.includes(slug) || slug.includes(stem));
173
+ const ranked = names
174
+ .filter((name) => contains(normalizeStem(name)))
175
+ .sort((a, b) => {
176
+ const stemA = normalizeStem(a);
177
+ const stemB = normalizeStem(b);
178
+ const exactA = stemA === slug ? 0 : 1;
179
+ const exactB = stemB === slug ? 0 : 1;
180
+ if (exactA !== exactB) {
181
+ return exactA - exactB;
182
+ }
183
+ if (stemA.length !== stemB.length) {
184
+ return stemB.length - stemA.length;
185
+ }
186
+ return a < b ? 1 : a > b ? -1 : 0;
187
+ });
188
+ return ranked[0] ?? null;
189
+ }
190
+ function compareScore(a, b) {
191
+ if (a.exact !== b.exact) {
192
+ return a.exact ? -1 : 1;
193
+ }
194
+ if (a.shared.length !== b.shared.length) {
195
+ return b.shared.length - a.shared.length;
196
+ }
197
+ return b.longest - a.longest;
198
+ }
199
+ /**
200
+ * The branch-name convention's choice among `names` (spec filenames), the one
201
+ * function both selection paths call, on the working tree and at the trust
202
+ * base.
203
+ *
204
+ * Candidates are grouped by their folded stem sequence; a group's member is
205
+ * its lexically greatest filename. Groups are ranked by an exact sequence,
206
+ * then the number of significant shared tokens, then the length of the
207
+ * longest one. A tie on all three between the top two groups chooses
208
+ * NOTHING: every key the old code used after the first was a guess about
209
+ * which feature the branch meant, and a tie on everything this measures is
210
+ * the code saying it does not know.
211
+ */
212
+ export function selectByBranch(names, branch) {
213
+ const rawSlug = branchSlug(branch);
214
+ const slug = tokens(rawSlug);
215
+ const oldAnswer = legacySelection(names, rawSlug);
216
+ if (!slug.some(isSignificant)) {
217
+ return { kind: 'none', why: 'no-usable-token', tied: [], legacy: oldAnswer };
218
+ }
219
+ const groups = new Map();
220
+ for (const name of [...names].sort()) {
221
+ const stem = tokens(normalizeStem(name));
222
+ const run = candidateOnTokens(slug, stem);
223
+ if (run === null) {
224
+ continue;
225
+ }
226
+ // Sorted ascending, so a later name in the same group replaces an
227
+ // earlier one: the member is the lexically greatest filename.
228
+ groups.set(JSON.stringify(stem), {
229
+ member: name,
230
+ exact: run.exact,
231
+ shared: run.shared,
232
+ longest: Math.max(...run.shared.map((token) => token.length)),
233
+ });
234
+ }
235
+ const ranked = [...groups.values()].sort((a, b) => compareScore(a, b) || (a.member < b.member ? -1 : a.member > b.member ? 1 : 0));
236
+ const top = ranked[0];
237
+ if (top === undefined) {
238
+ return { kind: 'none', why: 'no-candidate', tied: [], legacy: oldAnswer };
239
+ }
240
+ const second = ranked[1];
241
+ if (second !== undefined && compareScore(top, second) === 0) {
242
+ const tied = ranked.filter((group) => compareScore(top, group) === 0).map((group) => group.member);
243
+ return { kind: 'none', why: 'ambiguous', tied: tied.sort(), legacy: oldAnswer };
244
+ }
245
+ const weakBecause = [];
246
+ if (!top.exact) {
247
+ if (top.shared.length === 1) {
248
+ weakBecause.push('single-token');
249
+ }
250
+ if (second !== undefined && second.exact === top.exact && second.shared.length === top.shared.length) {
251
+ weakBecause.push('length-tiebreak');
252
+ }
253
+ }
254
+ return {
255
+ kind: 'selected',
256
+ name: top.member,
257
+ strength: top.exact ? 'exact' : weakBecause.length > 0 ? 'weak' : 'strong',
258
+ weakBecause,
259
+ shared: top.shared,
260
+ runnerUp: second?.member ?? null,
261
+ runnerUpShared: second?.shared ?? [],
262
+ legacy: oldAnswer === top.member ? null : oldAnswer,
263
+ };
78
264
  }
79
265
  /**
80
266
  * The path named by a `Spec:` line in a pull request body.
@@ -137,43 +323,6 @@ function exists(repoRoot, relative) {
137
323
  return false;
138
324
  }
139
325
  }
140
- /**
141
- * The best of the candidates whose stem relates to `target`, or undefined.
142
- *
143
- * `stemMatches` decides who is a CANDIDATE; this decides who wins, and the
144
- * two are different questions. Ranking on the lexically newest filename alone
145
- * was answering the second with the first: a loose candidate carrying a later
146
- * date beat the spec whose stem was the branch slug exactly, and an undated
147
- * name beat everything because it sorts after every date. A pull request was
148
- * then measured against a different feature's requirements, with nothing in
149
- * the report saying so, since naming the spec it used is exactly what the
150
- * report does.
151
- *
152
- * So: an exact stem first, then the most specific stem, and only then the
153
- * newest name. Specificity is stem LENGTH, which is crude but is the property
154
- * the failure actually had: "superpowers" beat
155
- * "1.2.1-base-and-superpowers" by being shorter and vaguer.
156
- */
157
- export function bestMatch(names, target) {
158
- return names
159
- .filter((name) => stemMatches(normalizeStem(name), target))
160
- .sort((a, b) => {
161
- const stemA = normalizeStem(a);
162
- const stemB = normalizeStem(b);
163
- const exactA = stemA === target ? 0 : 1;
164
- const exactB = stemB === target ? 0 : 1;
165
- if (exactA !== exactB) {
166
- return exactA - exactB;
167
- }
168
- if (stemA.length !== stemB.length) {
169
- return stemB.length - stemA.length;
170
- }
171
- // Newest name last in lexical order, so descending puts it first. The
172
- // names carry an ISO date prefix, so this is date order among equally
173
- // good candidates and nothing more.
174
- return a < b ? 1 : a > b ? -1 : 0;
175
- })[0];
176
- }
177
326
  /**
178
327
  * The plan belonging to a spec.
179
328
  *
@@ -205,6 +354,24 @@ function withPlan(repoRoot, kind, spec) {
205
354
  const found = planFor(repoRoot, spec);
206
355
  return 'escaped' in found ? { kind: 'escaped', path: found.escaped } : { kind, spec, plan: found.plan };
207
356
  }
357
+ /** The same, for a convention spec, which carries how it was chosen. */
358
+ function conventionWithPlan(repoRoot, spec, match) {
359
+ const found = planFor(repoRoot, spec);
360
+ return 'escaped' in found
361
+ ? { kind: 'escaped', path: found.escaped }
362
+ : { kind: 'convention', spec, plan: found.plan, match };
363
+ }
364
+ /** The match record of a selection, without its discriminant and name. */
365
+ export function matchOf(selection) {
366
+ return {
367
+ strength: selection.strength,
368
+ weakBecause: selection.weakBecause,
369
+ shared: selection.shared,
370
+ runnerUp: selection.runnerUp,
371
+ runnerUpShared: selection.runnerUpShared,
372
+ legacy: selection.legacy,
373
+ };
374
+ }
208
375
  /** Normalizes a user-supplied path to a repository-relative one. */
209
376
  function relativeToRoot(repoRoot, candidate) {
210
377
  const relative = path.isAbsolute(candidate)
@@ -290,17 +457,21 @@ export function discoverSpec(options) {
290
457
  }
291
458
  }
292
459
  if (options.branch !== undefined) {
293
- const best = bestMatch(markdownFilesIn(repoRoot, SPEC_DIR), branchSlug(options.branch));
294
- if (best !== undefined) {
295
- const relative = `${SPEC_DIR}/${best}`;
296
- // The convention spec is held to the repository too: a specs directory
297
- // linked out of the checkout is refused, never imported. Only --spec is
298
- // exempt, as a path a person typed.
299
- if (!resolvesInsideRoot(repoRoot, relative)) {
300
- return { kind: 'escaped', path: relative };
301
- }
302
- return withPlan(repoRoot, 'convention', relative);
460
+ const selection = selectByBranch(markdownFilesIn(repoRoot, SPEC_DIR), options.branch);
461
+ if (selection.kind === 'none') {
462
+ return {
463
+ kind: 'none',
464
+ selection: { why: selection.why, tied: selection.tied, legacy: selection.legacy },
465
+ };
466
+ }
467
+ const relative = `${SPEC_DIR}/${selection.name}`;
468
+ // The convention spec is held to the repository too: a specs directory
469
+ // linked out of the checkout is refused, never imported. Only --spec is
470
+ // exempt, as a path a person typed.
471
+ if (!resolvesInsideRoot(repoRoot, relative)) {
472
+ return { kind: 'escaped', path: relative };
303
473
  }
474
+ return conventionWithPlan(repoRoot, relative, matchOf(selection));
304
475
  }
305
476
  return { kind: 'none' };
306
477
  }
@@ -59,11 +59,39 @@ export declare function cvssToSeverity(score: number | null): Severity;
59
59
  * F2) is marked in place, so the count never reads as that many files read.
60
60
  */
61
61
  export declare function describeLockfiles(lockfiles: readonly string[], emptied?: ReadonlySet<string>): string;
62
+ /**
63
+ * The advisories osv-scanner.toml filtered out of this run, read from
64
+ * osv-scanner's stderr, the only place it says so.
65
+ *
66
+ * Measured on 2.4.0 (tests/fixtures/osv-scanner-2.4.0-filtered.stderr.txt):
67
+ * the JSON carries no trace of a filtered advisory at all, while stderr
68
+ * prints one "<id> and N alias(es) have been filtered out because: <reason>"
69
+ * line per advisory PER LOCKFILE, then "Filtered N vulnerabilities from
70
+ * output", where N counts the same way (two ignored advisories in two
71
+ * lockfiles print 4). The ignoreUntil expiry is printed nowhere, so it is
72
+ * never claimed here.
73
+ *
74
+ * Annotation only, never a verdict: the count and the ids feed the report's
75
+ * suppressed number and one run fact, and nothing reads them for a decision.
76
+ * A stderr without the count line (a policy that lowers osv-scanner's
77
+ * verbosity) gives null, and the caller keeps the old 0.
78
+ */
79
+ export interface OsvSuppressions {
80
+ count: number;
81
+ /** Distinct ids in first-seen order, each with the reason osv printed. */
82
+ ids: Array<{
83
+ id: string;
84
+ reason: string;
85
+ }>;
86
+ }
87
+ export declare function osvSuppressions(stderr: string): OsvSuppressions | null;
62
88
  export declare function normalizeOsvScanner(raw: unknown, version: string | null, blocked: boolean,
63
89
  /** The scan root as a path osv-scanner may have printed it, in any spelling. */
64
90
  roots?: readonly string[],
65
91
  /** The lockfiles the umbrella passed with --lockfile, repository-relative. */
66
- lockfiles?: readonly string[]): NormalizedGateOutput;
92
+ lockfiles?: readonly string[],
93
+ /** osv-scanner's stderr, read only for the osv-scanner.toml suppressions it names. */
94
+ stderr?: string): NormalizedGateOutput;
67
95
  export type GateProblemRule = 'conductor/gate-missing' | 'conductor/gate-output-unparseable' | 'conductor/gate-failed';
68
96
  /**
69
97
  * What to install for a product, spelled so it cannot be mistaken for
@@ -144,4 +172,6 @@ export declare function summariseStderr(stderr: string | null | undefined): stri
144
172
  * the product and never over the message, so a gate that reworded its error
145
173
  * is the same alert rather than a new one every run.
146
174
  */
147
- export declare function normalizeFailedGate(role: GateRole, product: Product, detail: string, stderr?: string | null): Finding;
175
+ export declare function normalizeFailedGate(role: GateRole, product: Product, detail: string, stderr?: string | null,
176
+ /** Structured facts beside the detail, such as a timed-out gate's limit and elapsed time. */
177
+ extra?: Record<string, unknown>): Finding;