@vaultcompass/conductor 0.10.0 → 0.12.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
  }
package/dist/normalize.js CHANGED
@@ -736,13 +736,38 @@ export function normalizeGitleaks(raw, version, blocked) {
736
736
  const entry = needRecord(rawEntry, product, where);
737
737
  const rule = needString(entry.RuleID, product, `${where}.RuleID`);
738
738
  const file = needString(entry.File, product, `${where}.File`);
739
- const line = needNumber(entry.StartLine, product, `${where}.StartLine`);
739
+ // Required, and then floored like the columns below: SARIF 2.1.0 gives
740
+ // startLine a minimum of 1, so a line below 1 or not an integer is 1.
741
+ const startLine = needNumber(entry.StartLine, product, `${where}.StartLine`);
742
+ const line = Number.isInteger(startLine) && startLine >= 1 ? startLine : 1;
740
743
  // Carried as gitleaks reports them, which is also what its own SARIF
741
744
  // output uses. gitleaks 8.30.1 column numbers are not consistently 0- or
742
745
  // 1-based across findings (one token at character 21 was reported at 22,
743
746
  // another at character 15 at 15), so no correction is applied.
744
- const column = typeof entry.StartColumn === 'number' ? entry.StartColumn : 1;
745
- const endColumn = typeof entry.EndColumn === 'number' ? entry.EndColumn : undefined;
747
+ //
748
+ // BUT A COLUMN BELOW 1 IS NEVER CARRIED. The envelope's columns are
749
+ // 1-based and SARIF 2.1.0 gives startColumn and endColumn a minimum of 1,
750
+ // and gitleaks 8.30.1 writes "EndColumn": 0 on its private-key rule over
751
+ // a PEM file (tests/fixtures/gitleaks-8.30.1-private-key-endcolumn-zero.json),
752
+ // which made the SARIF file invalid and so refused by code scanning
753
+ // (audit 2026-10-18 B1). A start column below 1 becomes 1. The end column
754
+ // is kept only as an integer that is at least 1 and at least the start
755
+ // column, on a finding whose EndLine is absent or equals its StartLine:
756
+ // the subject carries no end line, so a region read from it ends on its
757
+ // start line, and an end column from a later line would mark the wrong
758
+ // span. Otherwise it is left out, which SARIF reads as "to the end of
759
+ // the line".
760
+ const column = typeof entry.StartColumn === 'number' && Number.isInteger(entry.StartColumn) && entry.StartColumn >= 1
761
+ ? entry.StartColumn
762
+ : 1;
763
+ const oneLine = entry.EndLine === undefined || entry.EndLine === entry.StartLine;
764
+ const endColumn = oneLine &&
765
+ typeof entry.EndColumn === 'number' &&
766
+ Number.isInteger(entry.EndColumn) &&
767
+ entry.EndColumn >= 1 &&
768
+ entry.EndColumn >= column
769
+ ? entry.EndColumn
770
+ : undefined;
746
771
  const commit = optionalString(entry.Commit, product, `${where}.Commit`);
747
772
  const date = optionalString(entry.Date, product, `${where}.Date`);
748
773
  // gitleaks' own Fingerprint is commit:file:rule:line, identical across
@@ -75,6 +75,71 @@ export interface CompareResult {
75
75
  * finding is introduced. Never could-not-run.
76
76
  */
77
77
  export declare function comparisonFailed(args: CompareArgs, reason: string): CompareResult;
78
+ /** How the emptied-lockfile check's one spawn went, classified by the caller's spawnFailure. */
79
+ export interface EmptiedSpawnResult {
80
+ status: number | null;
81
+ stderr: string;
82
+ failure: null | {
83
+ reason: 'timed-out';
84
+ signal: string | null;
85
+ } | {
86
+ reason: 'spawn-failed';
87
+ message: string;
88
+ };
89
+ }
90
+ export interface EmptiedCheckArgs {
91
+ repoRoot: string;
92
+ ref: string;
93
+ workDir: string;
94
+ /** Repository-relative: the emptied handed lockfiles, or every handed one on exit 128. */
95
+ emptied: readonly string[];
96
+ /** Repository-relative: base lockfiles the head no longer tracks (deleted or moved). */
97
+ removed: readonly string[];
98
+ /** The head run's package count for each handed lockfile, for the same-directory replacement rule. */
99
+ headCounts: ReadonlyMap<string, number>;
100
+ /** Null when nothing was handed and the head was never spawned: no symmetry check. */
101
+ headArgv: readonly string[] | null;
102
+ baseArgv: (copies: readonly string[]) => string[];
103
+ /** What is left of the gate's time limit after the head scan. */
104
+ budgetMs: number;
105
+ spawn: (argv: readonly string[], cwd: string, timeoutMs: number) => EmptiedSpawnResult;
106
+ }
107
+ export type EmptiedCheckResult = {
108
+ kind: 'clear';
109
+ } | {
110
+ kind: 'emptied';
111
+ files: Array<{
112
+ path: string;
113
+ packages: number;
114
+ removed: boolean;
115
+ }>;
116
+ } | {
117
+ kind: 'unverified';
118
+ detail: string;
119
+ } | {
120
+ kind: 'timed-out';
121
+ elapsedMs: number;
122
+ signal: string | null;
123
+ };
124
+ /**
125
+ * The emptied-lockfile base check (design
126
+ * docs/superpowers/specs/2026-10-18-emptied-lockfile-under-trust-base.md,
127
+ * audit 2026-10-18 N1). On a decided trust base, a handed lockfile that read
128
+ * no packages at the head, and a base lockfile the head deleted or moved,
129
+ * is copied from the base and osv-scanner is run once on those copies; a
130
+ * copy with packages means the head removed what the gate judges. A removed
131
+ * file is cleared only by a head-handed lockfile in the SAME directory that
132
+ * read packages, is not a requirements file, and is absent from the base
133
+ * tree (a migration, say npm to pnpm, beside the same manifest).
134
+ *
135
+ * FAIL CLOSED, unlike compareWithBase, whose labels only ever move toward
136
+ * introduced. This check exists only to stop a head from removing what the
137
+ * gate judges, so anything that keeps it from clearing the head (a base
138
+ * copy that cannot be read, an asymmetric command line, a base run that
139
+ * fails, times out or prints no count for a copy) is a failure the caller
140
+ * turns into could-not-run. Requirements files are not checked (known-open).
141
+ */
142
+ export declare function checkEmptiedAgainstBase(args: EmptiedCheckArgs): EmptiedCheckResult;
78
143
  /**
79
144
  * Runs the comparison. Assumes the caller has established section 3.1: a
80
145
  * decided trust base, a head run that exited blocked, at least one finding.