@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.
- package/README.md +131 -21
- package/dist/cli.js +27 -2
- package/dist/envelope.d.ts +7 -1
- package/dist/gate-runner.d.ts +36 -10
- package/dist/gate-runner.js +202 -19
- package/dist/intent-prepare.d.ts +33 -1
- package/dist/intent-prepare.js +137 -33
- package/dist/intent-spec.d.ts +108 -22
- package/dist/intent-spec.js +226 -55
- package/dist/normalize.js +28 -3
- package/dist/osv-baseline.d.ts +65 -0
- package/dist/osv-baseline.js +105 -1
- package/dist/osv-coverage.d.ts +18 -2
- package/dist/osv-coverage.js +47 -10
- package/dist/output-sarif.js +90 -1
- package/dist/output-text.d.ts +39 -7
- package/dist/output-text.js +205 -19
- package/dist/run.d.ts +9 -1
- package/dist/run.js +1 -0
- package/dist/unread-manifests.js +4 -0
- package/package.json +1 -1
package/dist/intent-spec.d.ts
CHANGED
|
@@ -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'
|
|
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
|
-
/**
|
|
68
|
-
|
|
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
|
-
|
|
87
|
-
|
|
88
|
-
|
|
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;
|
package/dist/intent-spec.js
CHANGED
|
@@ -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
|
|
33
|
-
// that is the layout intent-guard's
|
|
34
|
-
// archive subdirectory is not a candidate
|
|
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
|
-
/**
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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
|
|
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
|
|
294
|
-
if (
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
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
|
-
|
|
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
|
-
|
|
745
|
-
|
|
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
|
package/dist/osv-baseline.d.ts
CHANGED
|
@@ -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.
|