@vaultcompass/conductor 0.2.4 → 0.4.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 +239 -15
- package/dist/cli.js +91 -14
- package/dist/envelope.d.ts +16 -0
- package/dist/gate-runner.d.ts +160 -2
- package/dist/gate-runner.js +311 -14
- package/dist/intent-prepare.d.ts +16 -0
- package/dist/intent-prepare.js +18 -0
- package/dist/normalize.d.ts +26 -2
- package/dist/normalize.js +89 -2
- package/dist/output-sarif.d.ts +11 -0
- package/dist/output-sarif.js +266 -19
- package/dist/output-text.js +126 -1
- package/dist/policy.js +24 -3
- package/dist/resolve.d.ts +39 -1
- package/dist/resolve.js +63 -12
- package/dist/run.d.ts +92 -0
- package/dist/run.js +155 -9
- package/dist/trust-base.d.ts +142 -0
- package/dist/trust-base.js +414 -0
- package/package.json +1 -1
package/dist/output-text.js
CHANGED
|
@@ -218,6 +218,79 @@ function skipWording(reason) {
|
|
|
218
218
|
function excludedLines(result) {
|
|
219
219
|
return result.excluded.map((gate) => ` excluded ${gate.role} ${gate.product} did not run here; --gate did not name it`);
|
|
220
220
|
}
|
|
221
|
+
/**
|
|
222
|
+
* The one sentence the whole of pull-request mode has to fit into.
|
|
223
|
+
*
|
|
224
|
+
* Counted even at ZERO, by the family suppression rule: the number is the
|
|
225
|
+
* answer to "did this pull request also try to change the rules", and leaving
|
|
226
|
+
* it out when the answer is none makes a run in pull-request mode
|
|
227
|
+
* indistinguishable from a run that was never in it.
|
|
228
|
+
*/
|
|
229
|
+
function proposalCount(result) {
|
|
230
|
+
return `${result.proposals.length} control change(s) proposed in this pull request`;
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* The gates the umbrella could not put into pull-request mode.
|
|
234
|
+
*
|
|
235
|
+
* This is the loud half and it must never be silent. A gate here read its own
|
|
236
|
+
* contract, config or baseline out of the tree being judged, which is exactly
|
|
237
|
+
* the hole pull-request mode exists to close, so a run where one gate is
|
|
238
|
+
* still exposed must not read like a run where none is. It is a statement
|
|
239
|
+
* about coverage rather than about anybody's code, so it is a line and a
|
|
240
|
+
* notification rather than a finding, and it never reaches the exit code.
|
|
241
|
+
*/
|
|
242
|
+
function withheldTrustBase(result) {
|
|
243
|
+
return result.gates.flatMap((gate) => {
|
|
244
|
+
const reason = gate.trustBase?.withheld;
|
|
245
|
+
return reason === undefined || reason === null ? [] : [{ gate, reason }];
|
|
246
|
+
});
|
|
247
|
+
}
|
|
248
|
+
/**
|
|
249
|
+
* The gates whose own node_modules/.bin copy this run declined to take.
|
|
250
|
+
*
|
|
251
|
+
* ONE LINE FOR THE WHOLE RUN rather than one per gate. The fact is about the
|
|
252
|
+
* run's mode, not about any gate's verdict, and in the repository shape it is
|
|
253
|
+
* most likely to happen in, gates installed as devDependencies and nothing
|
|
254
|
+
* else, it is true of all three at once. Three lines saying the same thing
|
|
255
|
+
* would read as three problems.
|
|
256
|
+
*/
|
|
257
|
+
function nodeModulesSkippedLine(result) {
|
|
258
|
+
const skipped = result.gates.flatMap((gate) => gate.nodeModulesSkipped === undefined
|
|
259
|
+
? []
|
|
260
|
+
: [`${gate.role} (${gate.product}) at ${gate.nodeModulesSkipped}`]);
|
|
261
|
+
if (skipped.length === 0) {
|
|
262
|
+
return [];
|
|
263
|
+
}
|
|
264
|
+
return [
|
|
265
|
+
` node_modules/.bin not consulted: ${skipped.join(', ')}. What is installed there is ` +
|
|
266
|
+
'chosen by the head own manifest and lockfile, so no ref approves it; each of those gates ' +
|
|
267
|
+
'was resolved from PATH or from an absolute command: instead, or reported as could-not-run.',
|
|
268
|
+
];
|
|
269
|
+
}
|
|
270
|
+
/**
|
|
271
|
+
* The pull-request-mode block of the full report.
|
|
272
|
+
*
|
|
273
|
+
* Four things in one place, because they answer one question between them:
|
|
274
|
+
* where the rules came from, what this pull request proposes to change them
|
|
275
|
+
* to, which gates were not covered by any of it, and where the programs that
|
|
276
|
+
* did run came from.
|
|
277
|
+
*/
|
|
278
|
+
function trustBaseLines(result) {
|
|
279
|
+
if (result.trustBase === null) {
|
|
280
|
+
return [];
|
|
281
|
+
}
|
|
282
|
+
const lines = [
|
|
283
|
+
` pull-request mode: rules from ${result.trustBase.ref}. ${proposalCount(result)}.`,
|
|
284
|
+
];
|
|
285
|
+
for (const proposal of result.proposals) {
|
|
286
|
+
lines.push(` proposed ${proposal.product.padEnd(13)} ${proposal.line}`);
|
|
287
|
+
}
|
|
288
|
+
for (const { gate, reason } of withheldTrustBase(result)) {
|
|
289
|
+
lines.push(` NOT in pull-request mode ${gate.role} ${gate.product} ${reason}`);
|
|
290
|
+
}
|
|
291
|
+
lines.push(...nodeModulesSkippedLine(result));
|
|
292
|
+
return lines;
|
|
293
|
+
}
|
|
221
294
|
/**
|
|
222
295
|
* What an unenforced gate did, as clauses for a verdict line.
|
|
223
296
|
*
|
|
@@ -244,7 +317,39 @@ function unenforcedClauses(result) {
|
|
|
244
317
|
}
|
|
245
318
|
return clauses;
|
|
246
319
|
}
|
|
320
|
+
/**
|
|
321
|
+
* The refusal, as the first line of the report and as the verdict.
|
|
322
|
+
*
|
|
323
|
+
* FIRST, and before any question about how many gates there are. The old
|
|
324
|
+
* order asked that question first, and an inventory naming no gate -- every
|
|
325
|
+
* gate `enabled: false` in the head's file, or a head file that will not
|
|
326
|
+
* parse -- fell into the "no gate ran because none is enabled" branch, which
|
|
327
|
+
* printed exit 0 and told the reader to switch a gate on while the process
|
|
328
|
+
* exited 2 and nothing had been checked. The refusal is the whole story of
|
|
329
|
+
* such a run and there is no arrangement of the other clauses that tells it.
|
|
330
|
+
*/
|
|
331
|
+
function refusalLines(result) {
|
|
332
|
+
const refusal = result.trustBase?.refusal;
|
|
333
|
+
if (refusal === undefined || refusal === null) {
|
|
334
|
+
return [];
|
|
335
|
+
}
|
|
336
|
+
return [
|
|
337
|
+
`conductor: refused the trust base "${result.trustBase?.ref ?? ''}". Nothing was checked.`,
|
|
338
|
+
` ${refusal}`,
|
|
339
|
+
];
|
|
340
|
+
}
|
|
247
341
|
function verdict(result) {
|
|
342
|
+
const refusal = result.trustBase?.refusal;
|
|
343
|
+
if (refusal !== undefined && refusal !== null) {
|
|
344
|
+
// Written rather than composed, exactly as the exit code is: no gate ran,
|
|
345
|
+
// so there is nothing for the clauses below to count, and every one of
|
|
346
|
+
// them would describe a different run from the one that happened.
|
|
347
|
+
return (`verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
|
|
348
|
+
'so no gate ran and nothing here is a result of any kind.');
|
|
349
|
+
}
|
|
350
|
+
return verdictForRun(result);
|
|
351
|
+
}
|
|
352
|
+
function verdictForRun(result) {
|
|
248
353
|
// Counted over ENFORCED gates only. The exit code came from those alone,
|
|
249
354
|
// so a count taken over all of them describes a different run from the one
|
|
250
355
|
// the number at the front of the line is about, and the umbrella's own
|
|
@@ -478,11 +583,25 @@ function summaryLine(result) {
|
|
|
478
583
|
parts.push(gatesReportingIgnored.length === result.gates.length
|
|
479
584
|
? `${suppressed} suppressed, ${ignored} ignored across all gates.`
|
|
480
585
|
: `${suppressed} suppressed across all gates.`);
|
|
586
|
+
// Pull-request mode, on the one line a hook and a pull request comment
|
|
587
|
+
// actually print. A clean run is exactly where this matters most: a pull
|
|
588
|
+
// request that proposes to switch a gate off and carries nothing else
|
|
589
|
+
// produces a clean report, and without this clause the only trace of the
|
|
590
|
+
// attempt would be in a file nobody re-reads.
|
|
591
|
+
if (result.trustBase !== null) {
|
|
592
|
+
parts.push(`Rules from ${result.trustBase.ref}. ${proposalCount(result)}.`);
|
|
593
|
+
const withheld = withheldTrustBase(result);
|
|
594
|
+
if (withheld.length > 0) {
|
|
595
|
+
const names = withheld.map(({ gate }) => `${gate.role} (${gate.product})`).join(', ');
|
|
596
|
+
parts.push(`${withheld.length} gate(s) NOT in pull-request mode: ${names}.`);
|
|
597
|
+
}
|
|
598
|
+
}
|
|
481
599
|
parts.push('Re-run with --verbose for the full report.');
|
|
482
600
|
return parts.join(' ');
|
|
483
601
|
}
|
|
484
602
|
export function renderText(result, options = {}) {
|
|
485
|
-
|
|
603
|
+
const refusal = refusalLines(result);
|
|
604
|
+
if (refusal.length === 0 && !options.verbose && isFullyClean(result)) {
|
|
486
605
|
return `${summaryLine(result)}\n`;
|
|
487
606
|
}
|
|
488
607
|
// Counted over EVERY gate, unenforced ones included, and deliberately not
|
|
@@ -494,6 +613,8 @@ export function renderText(result, options = {}) {
|
|
|
494
613
|
// different questions, so two numbers, and the section headers and the
|
|
495
614
|
// "not enforced" lines are what connect them.
|
|
496
615
|
const lines = [
|
|
616
|
+
...refusal,
|
|
617
|
+
...(refusal.length === 0 ? [] : ['']),
|
|
497
618
|
`conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
|
|
498
619
|
];
|
|
499
620
|
for (const gate of result.gates) {
|
|
@@ -503,6 +624,10 @@ export function renderText(result, options = {}) {
|
|
|
503
624
|
if (aside.length > 0) {
|
|
504
625
|
lines.push('', ...aside);
|
|
505
626
|
}
|
|
627
|
+
const trust = trustBaseLines(result);
|
|
628
|
+
if (trust.length > 0) {
|
|
629
|
+
lines.push('', ...trust);
|
|
630
|
+
}
|
|
506
631
|
// A derived severity is marked with a trailing asterisk above; say what
|
|
507
632
|
// that means rather than leaving a reader to guess, and only when one is
|
|
508
633
|
// actually on screen.
|
package/dist/policy.js
CHANGED
|
@@ -87,8 +87,15 @@ export const PRODUCT_FOR_ROLE = {
|
|
|
87
87
|
* could read in their own policy file.
|
|
88
88
|
*/
|
|
89
89
|
export const RESERVED_OPTIONS = {
|
|
90
|
-
|
|
91
|
-
|
|
90
|
+
// `trust-base` is reserved for all three products, and the umbrella now
|
|
91
|
+
// writes it for all three. It was reserved here before dep-guard's own
|
|
92
|
+
// pull-request mode shipped, deliberately: a policy file is a standing
|
|
93
|
+
// document, and a key that parsed one week and was rejected the next would
|
|
94
|
+
// have broken repositories on an upgrade nobody asked for. The flag it
|
|
95
|
+
// names is the one that decides where a gate reads its rules from, which
|
|
96
|
+
// is the last place to leave a window open.
|
|
97
|
+
'dep-guard': ['format', 'staged', 'base', 'trust-base'],
|
|
98
|
+
'vault-guard': ['format', 'f', 'staged', 'trust-base'],
|
|
92
99
|
// `base` is reserved even though the umbrella never passes it to this gate,
|
|
93
100
|
// and that is the point. The umbrella works the changed-path set out itself
|
|
94
101
|
// and hands over `--paths`, because `--project` may be a temporary
|
|
@@ -96,7 +103,15 @@ export const RESERVED_OPTIONS = {
|
|
|
96
103
|
// sends intent-guard looking for git THERE, and the run exits 2 blaming git
|
|
97
104
|
// for a line in the policy file. Rejecting the key at load time is the only
|
|
98
105
|
// place that failure can be explained by the thing that caused it.
|
|
99
|
-
|
|
106
|
+
// `trust-base` is written by the umbrella on a pull-request run, and only
|
|
107
|
+
// there. It is reserved unconditionally rather than only in that mode,
|
|
108
|
+
// because a policy file is a standing document: a key that is accepted on a
|
|
109
|
+
// push build and rejected on a pull request would be a policy file that
|
|
110
|
+
// parses on one event and not the other, which is the worst place to find
|
|
111
|
+
// out. It is also the one flag where two writers would be a security
|
|
112
|
+
// problem rather than a confusion, since the loser decides where the gate
|
|
113
|
+
// reads its rules from.
|
|
114
|
+
'intent-guard': ['json', 'staged', 'project', 'paths', 'base', 'trust-base'],
|
|
100
115
|
};
|
|
101
116
|
export class PolicyError extends Error {
|
|
102
117
|
constructor(message) {
|
|
@@ -147,6 +162,12 @@ function describeErrors(errors, source) {
|
|
|
147
162
|
* so a fourth cannot be added without saying why.
|
|
148
163
|
*/
|
|
149
164
|
function reservedReason(product, key) {
|
|
165
|
+
if (key === 'trust-base') {
|
|
166
|
+
return ('That flag says where a gate reads its rules from, and on a pull-request run the umbrella ' +
|
|
167
|
+
'writes it itself, pointing at the base ref it read its own policy from. A value here ' +
|
|
168
|
+
'would be a second writer of the flag that decides the trust boundary, set in the file ' +
|
|
169
|
+
"the pull request controls. Use the umbrella own --trust-base instead.");
|
|
170
|
+
}
|
|
150
171
|
if (product === 'intent-guard' && key === 'base') {
|
|
151
172
|
return ('The umbrella works the changed-path set out itself and passes --paths, because ' +
|
|
152
173
|
'--project may be a temporary directory holding only a contract. A --base here ' +
|
package/dist/resolve.d.ts
CHANGED
|
@@ -21,6 +21,17 @@ export interface VersionProbe {
|
|
|
21
21
|
export interface ResolvedBinary {
|
|
22
22
|
/** What to spawn. */
|
|
23
23
|
command: string;
|
|
24
|
+
/**
|
|
25
|
+
* The FILE whose contents decide what this gate does.
|
|
26
|
+
*
|
|
27
|
+
* Usually the same as `command`, and deliberately not the same when a
|
|
28
|
+
* `.js` build is run through this Node: there `command` is the Node
|
|
29
|
+
* executable and the program is the script after it. Carried explicitly
|
|
30
|
+
* rather than reconstructed from `argvPrefix[0]` by every caller, because
|
|
31
|
+
* getting that wrong means vetting the wrong file, and the one caller that
|
|
32
|
+
* vets it is the pull-request provenance check.
|
|
33
|
+
*/
|
|
34
|
+
program: string;
|
|
24
35
|
/** Arguments placed before the ones the umbrella adds. */
|
|
25
36
|
argvPrefix: string[];
|
|
26
37
|
source: ResolutionSource;
|
|
@@ -30,9 +41,36 @@ export interface ResolvedBinary {
|
|
|
30
41
|
versionProbe: VersionProbe | null;
|
|
31
42
|
}
|
|
32
43
|
export declare const CANDIDATES: Record<Product, Candidate[]>;
|
|
44
|
+
export interface ResolveOptions {
|
|
45
|
+
/**
|
|
46
|
+
* Leave `node_modules/.bin` out of the search entirely.
|
|
47
|
+
*
|
|
48
|
+
* True on a pull-request run and false everywhere else, decided by the
|
|
49
|
+
* caller from whether a trust base is set rather than re-derived here: this
|
|
50
|
+
* module knows nothing about refs, and there must be exactly one place that
|
|
51
|
+
* says what pull-request mode is.
|
|
52
|
+
*/
|
|
53
|
+
skipNodeModules?: boolean;
|
|
54
|
+
}
|
|
33
55
|
export declare class ResolveError extends Error {
|
|
34
56
|
constructor(message: string);
|
|
35
57
|
}
|
|
58
|
+
/**
|
|
59
|
+
* The node_modules/.bin candidate a pull-request run declined to take.
|
|
60
|
+
*
|
|
61
|
+
* Repository-relative, because it goes into a report and a published SARIF
|
|
62
|
+
* log, where an absolute path is somebody's machine layout.
|
|
63
|
+
*
|
|
64
|
+
* Returns null when the policy names a `command:`: that overrides resolution
|
|
65
|
+
* entirely, so no candidate was skipped, and saying one was would send a
|
|
66
|
+
* reader to fix a file that decided nothing.
|
|
67
|
+
*
|
|
68
|
+
* Separate from `resolveGateBinary` rather than a field on its result,
|
|
69
|
+
* because the case that most needs reporting is the one where resolution
|
|
70
|
+
* returns NOTHING: a repository with the gates only as devDependencies, which
|
|
71
|
+
* is the shape this whole change exists for.
|
|
72
|
+
*/
|
|
73
|
+
export declare function nodeModulesCandidate(gate: GatePolicy, repoRoot: string): string | null;
|
|
36
74
|
/**
|
|
37
75
|
* Resolves the binary for one gate.
|
|
38
76
|
*
|
|
@@ -47,6 +85,6 @@ export declare class ResolveError extends Error {
|
|
|
47
85
|
* named one specific file and falling back to something else would run a
|
|
48
86
|
* different tool than the one they asked for.
|
|
49
87
|
*/
|
|
50
|
-
export declare function resolveGateBinary(gate: GatePolicy, repoRoot: string, pathValue: string): ResolvedBinary | null;
|
|
88
|
+
export declare function resolveGateBinary(gate: GatePolicy, repoRoot: string, pathValue: string, options?: ResolveOptions): ResolvedBinary | null;
|
|
51
89
|
/** Every name resolution would try, for the missing-gate finding's message. */
|
|
52
90
|
export declare function candidateNames(product: Product): string[];
|
package/dist/resolve.js
CHANGED
|
@@ -24,6 +24,19 @@
|
|
|
24
24
|
// no say in that; a LOCATION is a statement about which build, and the
|
|
25
25
|
// repository does.
|
|
26
26
|
//
|
|
27
|
+
// 1c. ON A PULL-REQUEST RUN node_modules/.bin IS NOT A LOCATION AT ALL.
|
|
28
|
+
// Rule 1b says a LOCATION is a statement about which build and the
|
|
29
|
+
// repository gets to make it. On a pull request the repository making
|
|
30
|
+
// that statement IS the pull request: what is under node_modules was
|
|
31
|
+
// chosen by the head's own manifest and lockfile, installed by a step
|
|
32
|
+
// that runs before the gates, and git has no record of those bytes at
|
|
33
|
+
// either ref. 0.3.0 let resolution take it and then refused the program,
|
|
34
|
+
// which was safe and made every ordinary pull request in a
|
|
35
|
+
// devDependency-installed repository exit 2 with three refusals. Not
|
|
36
|
+
// trying that location at all is the same safety with the gate still
|
|
37
|
+
// running, from a build the base branch pinned. The skip is never
|
|
38
|
+
// silent: the caller reports the candidate it declined.
|
|
39
|
+
//
|
|
27
40
|
// 2. Only a unified binary is asked for its version. `intent-guard`
|
|
28
41
|
// answers --version; a per-command binary once did not parse the flag at
|
|
29
42
|
// all and RAN THE GATE against the current directory instead, and a
|
|
@@ -104,12 +117,16 @@ function findInNodeModules(name, repoRoot) {
|
|
|
104
117
|
const full = path.join(repoRoot, 'node_modules', '.bin', name);
|
|
105
118
|
return isExecutableFile(full) ? full : null;
|
|
106
119
|
}
|
|
107
|
-
function locate(name, repoRoot, pathValue) {
|
|
120
|
+
function locate(name, repoRoot, pathValue, skipNodeModules) {
|
|
108
121
|
// The repository's own copy first: a project pin beats a global install,
|
|
109
|
-
// which is what "pnpm exec <name>" does in the same repository.
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
122
|
+
// which is what "pnpm exec <name>" does in the same repository. Unless this
|
|
123
|
+
// is a pull-request run, where the repository saying which build to use is
|
|
124
|
+
// the pull request itself (rule 1c at the top of this file).
|
|
125
|
+
if (!skipNodeModules) {
|
|
126
|
+
const local = findInNodeModules(name, repoRoot);
|
|
127
|
+
if (local !== null) {
|
|
128
|
+
return { command: local, source: 'node_modules' };
|
|
129
|
+
}
|
|
113
130
|
}
|
|
114
131
|
const onPath = findOnPath(name, pathValue);
|
|
115
132
|
if (onPath !== null) {
|
|
@@ -117,8 +134,34 @@ function locate(name, repoRoot, pathValue) {
|
|
|
117
134
|
}
|
|
118
135
|
return null;
|
|
119
136
|
}
|
|
137
|
+
/**
|
|
138
|
+
* The node_modules/.bin candidate a pull-request run declined to take.
|
|
139
|
+
*
|
|
140
|
+
* Repository-relative, because it goes into a report and a published SARIF
|
|
141
|
+
* log, where an absolute path is somebody's machine layout.
|
|
142
|
+
*
|
|
143
|
+
* Returns null when the policy names a `command:`: that overrides resolution
|
|
144
|
+
* entirely, so no candidate was skipped, and saying one was would send a
|
|
145
|
+
* reader to fix a file that decided nothing.
|
|
146
|
+
*
|
|
147
|
+
* Separate from `resolveGateBinary` rather than a field on its result,
|
|
148
|
+
* because the case that most needs reporting is the one where resolution
|
|
149
|
+
* returns NOTHING: a repository with the gates only as devDependencies, which
|
|
150
|
+
* is the shape this whole change exists for.
|
|
151
|
+
*/
|
|
152
|
+
export function nodeModulesCandidate(gate, repoRoot) {
|
|
153
|
+
if (gate.command !== undefined) {
|
|
154
|
+
return null;
|
|
155
|
+
}
|
|
156
|
+
for (const candidate of CANDIDATES[gate.product]) {
|
|
157
|
+
if (findInNodeModules(candidate.name, repoRoot) !== null) {
|
|
158
|
+
return `node_modules/.bin/${candidate.name}`;
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
return null;
|
|
162
|
+
}
|
|
120
163
|
/** The candidate whose --version can be asked without running anything. */
|
|
121
|
-
function versionProbeFor(product, resolvedCandidate, resolvedCommand, repoRoot, pathValue) {
|
|
164
|
+
function versionProbeFor(product, resolvedCandidate, resolvedCommand, repoRoot, pathValue, skipNodeModules) {
|
|
122
165
|
if (resolvedCandidate.versionSafe) {
|
|
123
166
|
return { command: resolvedCommand, argv: ['--version'] };
|
|
124
167
|
}
|
|
@@ -126,7 +169,10 @@ function versionProbeFor(product, resolvedCandidate, resolvedCommand, repoRoot,
|
|
|
126
169
|
if (!candidate.versionSafe) {
|
|
127
170
|
continue;
|
|
128
171
|
}
|
|
129
|
-
|
|
172
|
+
// The skip reaches here too, and it has to: a probe RUNS the binary, so
|
|
173
|
+
// resolving the version-safe sibling out of node_modules would execute a
|
|
174
|
+
// head-chosen program in order to answer a question about it.
|
|
175
|
+
const found = locate(candidate.name, repoRoot, pathValue, skipNodeModules);
|
|
130
176
|
if (found !== null) {
|
|
131
177
|
return { command: found.command, argv: ['--version'] };
|
|
132
178
|
}
|
|
@@ -151,8 +197,9 @@ function baseName(file) {
|
|
|
151
197
|
* named one specific file and falling back to something else would run a
|
|
152
198
|
* different tool than the one they asked for.
|
|
153
199
|
*/
|
|
154
|
-
export function resolveGateBinary(gate, repoRoot, pathValue) {
|
|
200
|
+
export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
155
201
|
const table = CANDIDATES[gate.product];
|
|
202
|
+
const skipNodeModules = options.skipNodeModules ?? false;
|
|
156
203
|
if (gate.command !== undefined) {
|
|
157
204
|
if (!existsAsFile(gate.command)) {
|
|
158
205
|
throw new ResolveError(`gates.${gate.role}.command points at "${gate.command}", which is not a file. ` +
|
|
@@ -170,33 +217,37 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
|
|
|
170
217
|
if (!isExecutableFile(gate.command) && /\.(?:js|mjs|cjs)$/.test(gate.command)) {
|
|
171
218
|
return {
|
|
172
219
|
command: process.execPath,
|
|
220
|
+
// Node is the command; the script is what actually decides anything.
|
|
221
|
+
program: gate.command,
|
|
173
222
|
argvPrefix: [gate.command, ...prefix],
|
|
174
223
|
source: 'policy',
|
|
175
224
|
candidate: candidateName,
|
|
176
225
|
versionProbe: candidate.versionSafe
|
|
177
226
|
? { command: process.execPath, argv: [gate.command, '--version'] }
|
|
178
|
-
: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue),
|
|
227
|
+
: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
|
|
179
228
|
};
|
|
180
229
|
}
|
|
181
230
|
return {
|
|
182
231
|
command: gate.command,
|
|
232
|
+
program: gate.command,
|
|
183
233
|
argvPrefix: prefix,
|
|
184
234
|
source: 'policy',
|
|
185
235
|
candidate: candidateName,
|
|
186
|
-
versionProbe: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue),
|
|
236
|
+
versionProbe: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
|
|
187
237
|
};
|
|
188
238
|
}
|
|
189
239
|
for (const candidate of table) {
|
|
190
|
-
const found = locate(candidate.name, repoRoot, pathValue);
|
|
240
|
+
const found = locate(candidate.name, repoRoot, pathValue, skipNodeModules);
|
|
191
241
|
if (found === null) {
|
|
192
242
|
continue;
|
|
193
243
|
}
|
|
194
244
|
return {
|
|
195
245
|
command: found.command,
|
|
246
|
+
program: found.command,
|
|
196
247
|
argvPrefix: [...candidate.prefix],
|
|
197
248
|
source: found.source,
|
|
198
249
|
candidate: candidate.name,
|
|
199
|
-
versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue),
|
|
250
|
+
versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
|
|
200
251
|
};
|
|
201
252
|
}
|
|
202
253
|
return null;
|
package/dist/run.d.ts
CHANGED
|
@@ -54,6 +54,55 @@ export interface SkippedGate {
|
|
|
54
54
|
reason: 'no-contract' | 'contract-waived';
|
|
55
55
|
detail: string;
|
|
56
56
|
}
|
|
57
|
+
/**
|
|
58
|
+
* One control input this pull request proposes to change.
|
|
59
|
+
*
|
|
60
|
+
* A statement about CONFIGURATION, never a finding. It carries no severity,
|
|
61
|
+
* no fingerprint and no blocking flag, it is not in `findings`, and nothing
|
|
62
|
+
* here reaches the exit code: a pull request is allowed to propose changing
|
|
63
|
+
* the rules, and the whole of the mechanism is that the proposal does not
|
|
64
|
+
* take effect for the run that carries it. What it must do is be VISIBLE, so
|
|
65
|
+
* a reviewer meets "this pull request also proposes to loosen the gate" as
|
|
66
|
+
* one sentence beside the verdict.
|
|
67
|
+
*
|
|
68
|
+
* `line` is the sentence the gate that owns the control input wrote, carried
|
|
69
|
+
* verbatim. The umbrella writes only its own, about its own policy file.
|
|
70
|
+
*/
|
|
71
|
+
export interface ControlProposal {
|
|
72
|
+
/** The gate that raised it, or the umbrella for its own policy file. */
|
|
73
|
+
product: Product | 'conductor';
|
|
74
|
+
/** The role that gate fills, or null for the umbrella's own. */
|
|
75
|
+
role: GateRole | null;
|
|
76
|
+
line: string;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Pull-request mode as the whole run saw it.
|
|
80
|
+
*
|
|
81
|
+
* `policyChanged` is decided in one place, before any gate runs, by comparing
|
|
82
|
+
* the policy file at the base ref with the one at the head commit. It is
|
|
83
|
+
* reported and never acted on: the base ref's policy is the one that ran.
|
|
84
|
+
*/
|
|
85
|
+
export interface RunTrustBase {
|
|
86
|
+
/** The ref the umbrella took its own policy from. */
|
|
87
|
+
ref: string;
|
|
88
|
+
/** Whether the head commit's own policy file differs from that one. */
|
|
89
|
+
policyChanged: boolean;
|
|
90
|
+
/**
|
|
91
|
+
* Why this ref could not be used at all, or null when it was.
|
|
92
|
+
*
|
|
93
|
+
* A SEPARATE FIELD RATHER THAN AN ABSENT `trustBase`, and it is load-bearing
|
|
94
|
+
* in both renderers. A refusal is the worst outcome this tool has -- nothing
|
|
95
|
+
* was checked, on a run that was supposed to be the gate -- and it has to be
|
|
96
|
+
* the first thing a reader meets rather than something inferred from an exit
|
|
97
|
+
* code. Both reports used to work the number of gates out first, and an
|
|
98
|
+
* inventory naming no gate (every gate `enabled: false` in the head's file,
|
|
99
|
+
* or a head file that will not parse) then printed "no gate ran because none
|
|
100
|
+
* is enabled" in text and `{"runs": []}` in SARIF, with the refusal sentence
|
|
101
|
+
* nowhere. That is reachable on the DEFAULT actions/checkout, which fetches
|
|
102
|
+
* depth 1 and so carries no base ref.
|
|
103
|
+
*/
|
|
104
|
+
refusal: string | null;
|
|
105
|
+
}
|
|
57
106
|
export interface RunResult {
|
|
58
107
|
schemaVersion: 1;
|
|
59
108
|
generatedAt: string;
|
|
@@ -70,6 +119,14 @@ export interface RunResult {
|
|
|
70
119
|
* consumer reads one list instead of three.
|
|
71
120
|
*/
|
|
72
121
|
findings: Finding[];
|
|
122
|
+
/** Present only on a pull-request run; null means ordinary mode. */
|
|
123
|
+
trustBase: RunTrustBase | null;
|
|
124
|
+
/**
|
|
125
|
+
* Every control input this pull request proposes to change, the umbrella's
|
|
126
|
+
* own policy file first and then each gate's, in gate order. Empty outside
|
|
127
|
+
* pull-request mode, and empty inside it when nothing was proposed.
|
|
128
|
+
*/
|
|
129
|
+
proposals: ControlProposal[];
|
|
73
130
|
summary: {
|
|
74
131
|
blocking: number;
|
|
75
132
|
byProduct: Record<string, number>;
|
|
@@ -91,6 +148,14 @@ export interface RunOptions {
|
|
|
91
148
|
base?: string;
|
|
92
149
|
/** An explicit spec for the intent gate, outranking every other source. */
|
|
93
150
|
spec?: string;
|
|
151
|
+
/**
|
|
152
|
+
* Pull-request mode. The policy this run was handed was ALREADY read from
|
|
153
|
+
* this ref by the caller: `runAll` does not read it, because the policy has
|
|
154
|
+
* to be parsed before there is a run to configure. What this carries is the
|
|
155
|
+
* ref, so it can be passed down to every child that can take it, and the
|
|
156
|
+
* one fact the caller established while reading it.
|
|
157
|
+
*/
|
|
158
|
+
trustBase?: RunTrustBase;
|
|
94
159
|
/**
|
|
95
160
|
* The environment the pull-request defaults are read from.
|
|
96
161
|
*
|
|
@@ -111,4 +176,31 @@ export interface RunOptions {
|
|
|
111
176
|
*/
|
|
112
177
|
tempRoot?: string;
|
|
113
178
|
}
|
|
179
|
+
/**
|
|
180
|
+
* The run that never happened, because the trust base could not be judged
|
|
181
|
+
* against.
|
|
182
|
+
*
|
|
183
|
+
* EVERY ENABLED GATE IS COULD-NOT-RUN, which is the fail-closed half of
|
|
184
|
+
* pull-request mode. A base ref that will not resolve is not a reason to fall
|
|
185
|
+
* back to the head's policy: falling back to the head is the behaviour this
|
|
186
|
+
* release removes, and it would be reachable by anybody who could make the
|
|
187
|
+
* base ref unfetchable.
|
|
188
|
+
*
|
|
189
|
+
* TWO THINGS HERE ARE DELIBERATELY NOT READ OFF THE POLICY, and both are the
|
|
190
|
+
* point rather than shortcuts. The policy handed in is the HEAD's, used only
|
|
191
|
+
* as an inventory so the report can name the gates that did not run; it
|
|
192
|
+
* cannot be trusted, so:
|
|
193
|
+
*
|
|
194
|
+
* - Every synthesized outcome is ENFORCED, whatever the file says. The
|
|
195
|
+
* `enforce` flag is itself a control input, and the file it lives in is
|
|
196
|
+
* the one that could not be read from the base. A head policy setting
|
|
197
|
+
* `enforce: false` everywhere must not be able to turn this into exit 0.
|
|
198
|
+
* - The exit code is written here rather than composed. A head policy
|
|
199
|
+
* enabling NO gate at all would otherwise compose to 0 over an empty list,
|
|
200
|
+
* which would report a run that checked nothing as a clean one.
|
|
201
|
+
*/
|
|
202
|
+
export declare function refusedTrustBase(policy: Policy, ref: string, detail: string, options: {
|
|
203
|
+
stage?: GateStage;
|
|
204
|
+
now?: () => Date;
|
|
205
|
+
}): RunResult;
|
|
114
206
|
export declare function runAll(policy: Policy, options: RunOptions): RunResult;
|