@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.
- package/README.md +157 -31
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +19 -4
- package/dist/gate-runner.d.ts +102 -10
- package/dist/gate-runner.js +282 -37
- package/dist/init-hook-detect.d.ts +1 -0
- package/dist/init-hook-detect.js +45 -0
- package/dist/init-policy.js +13 -0
- package/dist/init.d.ts +8 -0
- package/dist/init.js +166 -20
- package/dist/intent-prepare.d.ts +51 -2
- package/dist/intent-prepare.js +160 -35
- package/dist/intent-spec.d.ts +108 -22
- package/dist/intent-spec.js +226 -55
- package/dist/normalize.d.ts +32 -2
- package/dist/normalize.js +117 -11
- package/dist/output-sarif.js +72 -1
- package/dist/output-text.d.ts +37 -1
- package/dist/output-text.js +324 -21
- package/dist/policy.d.ts +8 -0
- package/dist/policy.js +33 -6
- package/dist/products.d.ts +8 -1
- package/dist/products.js +14 -0
- package/dist/run.d.ts +13 -1
- package/dist/run.js +19 -2
- package/package.json +1 -1
- package/schema/guardrails.schema.json +6 -0
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.d.ts
CHANGED
|
@@ -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[]
|
|
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
|
|
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;
|