@vaultcompass/conductor 0.2.3 → 0.3.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 +147 -2
- package/dist/cli.js +96 -15
- package/dist/envelope.d.ts +16 -0
- package/dist/gate-runner.d.ts +118 -2
- package/dist/gate-runner.js +211 -9
- package/dist/init.d.ts +15 -1
- package/dist/init.js +215 -33
- package/dist/intent-prepare.d.ts +16 -0
- package/dist/intent-prepare.js +18 -0
- package/dist/normalize.d.ts +14 -1
- package/dist/normalize.js +76 -0
- package/dist/output-sarif.d.ts +11 -0
- package/dist/output-sarif.js +230 -19
- package/dist/output-text.js +134 -3
- package/dist/policy.js +24 -3
- package/dist/resolve.d.ts +11 -0
- package/dist/resolve.js +4 -0
- package/dist/run.d.ts +92 -0
- package/dist/run.js +119 -5
- 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,55 @@ 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 pull-request-mode block of the full report.
|
|
250
|
+
*
|
|
251
|
+
* Three things in one place, because they answer one question between them:
|
|
252
|
+
* where the rules came from, what this pull request proposes to change them
|
|
253
|
+
* to, and which gates were not covered by any of it.
|
|
254
|
+
*/
|
|
255
|
+
function trustBaseLines(result) {
|
|
256
|
+
if (result.trustBase === null) {
|
|
257
|
+
return [];
|
|
258
|
+
}
|
|
259
|
+
const lines = [
|
|
260
|
+
` pull-request mode: rules from ${result.trustBase.ref}. ${proposalCount(result)}.`,
|
|
261
|
+
];
|
|
262
|
+
for (const proposal of result.proposals) {
|
|
263
|
+
lines.push(` proposed ${proposal.product.padEnd(13)} ${proposal.line}`);
|
|
264
|
+
}
|
|
265
|
+
for (const { gate, reason } of withheldTrustBase(result)) {
|
|
266
|
+
lines.push(` NOT in pull-request mode ${gate.role} ${gate.product} ${reason}`);
|
|
267
|
+
}
|
|
268
|
+
return lines;
|
|
269
|
+
}
|
|
221
270
|
/**
|
|
222
271
|
* What an unenforced gate did, as clauses for a verdict line.
|
|
223
272
|
*
|
|
@@ -244,7 +293,39 @@ function unenforcedClauses(result) {
|
|
|
244
293
|
}
|
|
245
294
|
return clauses;
|
|
246
295
|
}
|
|
296
|
+
/**
|
|
297
|
+
* The refusal, as the first line of the report and as the verdict.
|
|
298
|
+
*
|
|
299
|
+
* FIRST, and before any question about how many gates there are. The old
|
|
300
|
+
* order asked that question first, and an inventory naming no gate -- every
|
|
301
|
+
* gate `enabled: false` in the head's file, or a head file that will not
|
|
302
|
+
* parse -- fell into the "no gate ran because none is enabled" branch, which
|
|
303
|
+
* printed exit 0 and told the reader to switch a gate on while the process
|
|
304
|
+
* exited 2 and nothing had been checked. The refusal is the whole story of
|
|
305
|
+
* such a run and there is no arrangement of the other clauses that tells it.
|
|
306
|
+
*/
|
|
307
|
+
function refusalLines(result) {
|
|
308
|
+
const refusal = result.trustBase?.refusal;
|
|
309
|
+
if (refusal === undefined || refusal === null) {
|
|
310
|
+
return [];
|
|
311
|
+
}
|
|
312
|
+
return [
|
|
313
|
+
`conductor: refused the trust base "${result.trustBase?.ref ?? ''}". Nothing was checked.`,
|
|
314
|
+
` ${refusal}`,
|
|
315
|
+
];
|
|
316
|
+
}
|
|
247
317
|
function verdict(result) {
|
|
318
|
+
const refusal = result.trustBase?.refusal;
|
|
319
|
+
if (refusal !== undefined && refusal !== null) {
|
|
320
|
+
// Written rather than composed, exactly as the exit code is: no gate ran,
|
|
321
|
+
// so there is nothing for the clauses below to count, and every one of
|
|
322
|
+
// them would describe a different run from the one that happened.
|
|
323
|
+
return (`verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
|
|
324
|
+
'so no gate ran and nothing here is a result of any kind.');
|
|
325
|
+
}
|
|
326
|
+
return verdictForRun(result);
|
|
327
|
+
}
|
|
328
|
+
function verdictForRun(result) {
|
|
248
329
|
// Counted over ENFORCED gates only. The exit code came from those alone,
|
|
249
330
|
// so a count taken over all of them describes a different run from the one
|
|
250
331
|
// the number at the front of the line is about, and the umbrella's own
|
|
@@ -417,9 +498,15 @@ function summaryLine(result) {
|
|
|
417
498
|
// is the easiest of the three to lose: a --gate run is usually somebody
|
|
418
499
|
// narrowing a run on purpose, and a log of it that says nothing about the
|
|
419
500
|
// narrowing is the log that gets uploaded and read as a full run later.
|
|
501
|
+
// Counted even at zero for the same suppression reason as the enforcement
|
|
502
|
+
// count above: a gate the command line dropped had no vote, and "0 gate(s)
|
|
503
|
+
// left out by --gate" says the run was not narrowed.
|
|
420
504
|
if (result.excluded.length > 0) {
|
|
421
505
|
const names = result.excluded.map((gate) => `${gate.role} (${gate.product})`).join(', ');
|
|
422
|
-
parts.push(
|
|
506
|
+
parts.push(`${result.excluded.length} gate(s) left out by --gate: ${names}.`);
|
|
507
|
+
}
|
|
508
|
+
else {
|
|
509
|
+
parts.push('0 gate(s) left out by --gate.');
|
|
423
510
|
}
|
|
424
511
|
// A gate that ran with enforce: false could not have failed this run
|
|
425
512
|
// whatever it found. Naming it among the gates that ran and then saying
|
|
@@ -428,10 +515,19 @@ function summaryLine(result) {
|
|
|
428
515
|
// full report says this in the line under that gate's findings; on a clean
|
|
429
516
|
// run there are no findings, so the summary line is the only place left to
|
|
430
517
|
// say it.
|
|
518
|
+
//
|
|
519
|
+
// Printed as a count even when it is zero. This is the family suppression
|
|
520
|
+
// rule: a gate that can be turned off is the user's decision, and a clean
|
|
521
|
+
// line that says nothing about enforcement lets a repository read as fully
|
|
522
|
+
// gated when a gate's result did not move the exit code. "0 gate(s) not
|
|
523
|
+
// enforced" is the umbrella saying every gate that ran had a vote.
|
|
431
524
|
const unenforced = result.gates.filter((gate) => !gate.enforce);
|
|
432
525
|
if (unenforced.length > 0) {
|
|
433
526
|
const names = unenforced.map((gate) => `${gate.role} (${gate.product})`).join(', ');
|
|
434
|
-
parts.push(
|
|
527
|
+
parts.push(`${unenforced.length} gate(s) not enforced, could not have blocked, enforce: false in .guardrails.yaml: ${names}.`);
|
|
528
|
+
}
|
|
529
|
+
else {
|
|
530
|
+
parts.push('0 gate(s) not enforced.');
|
|
435
531
|
}
|
|
436
532
|
// Non-blocking findings are counted rather than hidden, for the same reason
|
|
437
533
|
// the full report prints the suppressed and ignored counts at zero: they
|
|
@@ -448,11 +544,40 @@ function summaryLine(result) {
|
|
|
448
544
|
if (counts.length > 0) {
|
|
449
545
|
parts.push(`${counts.join(', ')}.`);
|
|
450
546
|
}
|
|
547
|
+
// The suppressed and ignored counts the gates reported, summed across them
|
|
548
|
+
// and printed even at zero. The full report prints these per gate for the
|
|
549
|
+
// same reason, so a quiet report is not mistaken for a clean one; the clean
|
|
550
|
+
// summary line is the one a hook and a pull request comment actually print,
|
|
551
|
+
// and it is where a repository baselining findings without saying so would
|
|
552
|
+
// otherwise read as clean. Suppressed always shows because it is always a
|
|
553
|
+
// number the gate reported. Ignored shows only when every gate that ran
|
|
554
|
+
// reported it: a gate that drops ignored files before its own output has no
|
|
555
|
+
// count to give, and "0 ignored" there would state a fact no gate stated.
|
|
556
|
+
const suppressed = result.gates.reduce((total, gate) => total + gate.run.suppressed, 0);
|
|
557
|
+
const gatesReportingIgnored = result.gates.filter((gate) => gate.run.details.ignoredReported !== false);
|
|
558
|
+
const ignored = gatesReportingIgnored.reduce((total, gate) => total + gate.run.ignored, 0);
|
|
559
|
+
parts.push(gatesReportingIgnored.length === result.gates.length
|
|
560
|
+
? `${suppressed} suppressed, ${ignored} ignored across all gates.`
|
|
561
|
+
: `${suppressed} suppressed across all gates.`);
|
|
562
|
+
// Pull-request mode, on the one line a hook and a pull request comment
|
|
563
|
+
// actually print. A clean run is exactly where this matters most: a pull
|
|
564
|
+
// request that proposes to switch a gate off and carries nothing else
|
|
565
|
+
// produces a clean report, and without this clause the only trace of the
|
|
566
|
+
// attempt would be in a file nobody re-reads.
|
|
567
|
+
if (result.trustBase !== null) {
|
|
568
|
+
parts.push(`Rules from ${result.trustBase.ref}. ${proposalCount(result)}.`);
|
|
569
|
+
const withheld = withheldTrustBase(result);
|
|
570
|
+
if (withheld.length > 0) {
|
|
571
|
+
const names = withheld.map(({ gate }) => `${gate.role} (${gate.product})`).join(', ');
|
|
572
|
+
parts.push(`${withheld.length} gate(s) NOT in pull-request mode: ${names}.`);
|
|
573
|
+
}
|
|
574
|
+
}
|
|
451
575
|
parts.push('Re-run with --verbose for the full report.');
|
|
452
576
|
return parts.join(' ');
|
|
453
577
|
}
|
|
454
578
|
export function renderText(result, options = {}) {
|
|
455
|
-
|
|
579
|
+
const refusal = refusalLines(result);
|
|
580
|
+
if (refusal.length === 0 && !options.verbose && isFullyClean(result)) {
|
|
456
581
|
return `${summaryLine(result)}\n`;
|
|
457
582
|
}
|
|
458
583
|
// Counted over EVERY gate, unenforced ones included, and deliberately not
|
|
@@ -464,6 +589,8 @@ export function renderText(result, options = {}) {
|
|
|
464
589
|
// different questions, so two numbers, and the section headers and the
|
|
465
590
|
// "not enforced" lines are what connect them.
|
|
466
591
|
const lines = [
|
|
592
|
+
...refusal,
|
|
593
|
+
...(refusal.length === 0 ? [] : ['']),
|
|
467
594
|
`conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
|
|
468
595
|
];
|
|
469
596
|
for (const gate of result.gates) {
|
|
@@ -473,6 +600,10 @@ export function renderText(result, options = {}) {
|
|
|
473
600
|
if (aside.length > 0) {
|
|
474
601
|
lines.push('', ...aside);
|
|
475
602
|
}
|
|
603
|
+
const trust = trustBaseLines(result);
|
|
604
|
+
if (trust.length > 0) {
|
|
605
|
+
lines.push('', ...trust);
|
|
606
|
+
}
|
|
476
607
|
// A derived severity is marked with a trailing asterisk above; say what
|
|
477
608
|
// that means rather than leaving a reader to guess, and only when one is
|
|
478
609
|
// 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;
|
package/dist/resolve.js
CHANGED
|
@@ -170,6 +170,8 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
|
|
|
170
170
|
if (!isExecutableFile(gate.command) && /\.(?:js|mjs|cjs)$/.test(gate.command)) {
|
|
171
171
|
return {
|
|
172
172
|
command: process.execPath,
|
|
173
|
+
// Node is the command; the script is what actually decides anything.
|
|
174
|
+
program: gate.command,
|
|
173
175
|
argvPrefix: [gate.command, ...prefix],
|
|
174
176
|
source: 'policy',
|
|
175
177
|
candidate: candidateName,
|
|
@@ -180,6 +182,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
|
|
|
180
182
|
}
|
|
181
183
|
return {
|
|
182
184
|
command: gate.command,
|
|
185
|
+
program: gate.command,
|
|
183
186
|
argvPrefix: prefix,
|
|
184
187
|
source: 'policy',
|
|
185
188
|
candidate: candidateName,
|
|
@@ -193,6 +196,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
|
|
|
193
196
|
}
|
|
194
197
|
return {
|
|
195
198
|
command: found.command,
|
|
199
|
+
program: found.command,
|
|
196
200
|
argvPrefix: [...candidate.prefix],
|
|
197
201
|
source: found.source,
|
|
198
202
|
candidate: candidate.name,
|
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;
|
package/dist/run.js
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
// One run across every enabled gate.
|
|
2
2
|
import { compareFindings } from './envelope.js';
|
|
3
|
-
import { composeExitCode } from './exit-codes.js';
|
|
3
|
+
import { EXIT_COULD_NOT_RUN, composeExitCode } from './exit-codes.js';
|
|
4
4
|
import { preparationFailed, runGate } from './gate-runner.js';
|
|
5
5
|
import { resolveBaseRef } from './intent-base.js';
|
|
6
|
-
import { prepareIntent } from './intent-prepare.js';
|
|
6
|
+
import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
|
|
7
7
|
import { GATE_ROLES, enabledGates, runsAtStage } from './policy.js';
|
|
8
8
|
import { ResolveError, resolveGateBinary } from './resolve.js';
|
|
9
|
+
import { POLICY_PROPOSAL_LINE } from './trust-base.js';
|
|
9
10
|
/**
|
|
10
11
|
* Whether this run is the pull-request shaped one.
|
|
11
12
|
*
|
|
@@ -36,13 +37,21 @@ function intentBinary(gate, options) {
|
|
|
36
37
|
return null;
|
|
37
38
|
}
|
|
38
39
|
}
|
|
39
|
-
|
|
40
|
+
/**
|
|
41
|
+
* The three lists a stage filter and a `--gate` flag produce between them.
|
|
42
|
+
*
|
|
43
|
+
* Factored out because the trust-base refusal below needs the same partition:
|
|
44
|
+
* a run that could not read its policy from the base ref still has to report
|
|
45
|
+
* the gates it did not run and the stage each of them sits at, or the report
|
|
46
|
+
* of the most serious failure this tool has is thinner than the report of an
|
|
47
|
+
* ordinary one.
|
|
48
|
+
*/
|
|
49
|
+
function partitionGates(policy, requested) {
|
|
40
50
|
const enabled = enabledGates(policy);
|
|
41
51
|
// Partitioned before anything is spawned, and before any binary is even
|
|
42
52
|
// looked for: a gate that will not run at this stage must not be able to
|
|
43
53
|
// fail the run by being uninstalled here. An intent gate that lives only
|
|
44
54
|
// on the CI image is the ordinary case, not an error.
|
|
45
|
-
const requested = options.stage;
|
|
46
55
|
const gates = requested === undefined ? enabled : enabled.filter((gate) => runsAtStage(gate.stage, requested));
|
|
47
56
|
const deferred = requested === undefined
|
|
48
57
|
? []
|
|
@@ -52,7 +61,100 @@ export function runAll(policy, options) {
|
|
|
52
61
|
// Read off the policy rather than off the enabled list, because these gates
|
|
53
62
|
// are exactly the ones the override took out of it. In role order, so a
|
|
54
63
|
// report's ordering never depends on the order the flags were typed.
|
|
55
|
-
const excluded = GATE_ROLES.map((role) => policy.gates[role])
|
|
64
|
+
const excluded = GATE_ROLES.map((role) => policy.gates[role])
|
|
65
|
+
.filter((gate) => gate !== undefined && gate.excludedByCli)
|
|
66
|
+
.map((gate) => ({ role: gate.role, product: gate.product }));
|
|
67
|
+
return { gates, deferred, excluded };
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* The run that never happened, because the trust base could not be judged
|
|
71
|
+
* against.
|
|
72
|
+
*
|
|
73
|
+
* EVERY ENABLED GATE IS COULD-NOT-RUN, which is the fail-closed half of
|
|
74
|
+
* pull-request mode. A base ref that will not resolve is not a reason to fall
|
|
75
|
+
* back to the head's policy: falling back to the head is the behaviour this
|
|
76
|
+
* release removes, and it would be reachable by anybody who could make the
|
|
77
|
+
* base ref unfetchable.
|
|
78
|
+
*
|
|
79
|
+
* TWO THINGS HERE ARE DELIBERATELY NOT READ OFF THE POLICY, and both are the
|
|
80
|
+
* point rather than shortcuts. The policy handed in is the HEAD's, used only
|
|
81
|
+
* as an inventory so the report can name the gates that did not run; it
|
|
82
|
+
* cannot be trusted, so:
|
|
83
|
+
*
|
|
84
|
+
* - Every synthesized outcome is ENFORCED, whatever the file says. The
|
|
85
|
+
* `enforce` flag is itself a control input, and the file it lives in is
|
|
86
|
+
* the one that could not be read from the base. A head policy setting
|
|
87
|
+
* `enforce: false` everywhere must not be able to turn this into exit 0.
|
|
88
|
+
* - The exit code is written here rather than composed. A head policy
|
|
89
|
+
* enabling NO gate at all would otherwise compose to 0 over an empty list,
|
|
90
|
+
* which would report a run that checked nothing as a clean one.
|
|
91
|
+
*/
|
|
92
|
+
export function refusedTrustBase(policy, ref, detail, options) {
|
|
93
|
+
const { gates, deferred, excluded } = partitionGates(policy, options.stage);
|
|
94
|
+
const outcomes = gates.map((gate) => preparationFailed({ ...gate, enforce: true }, `the trust base could not be used: ${detail}`));
|
|
95
|
+
const findings = outcomes.flatMap((outcome) => outcome.findings).sort(compareFindings);
|
|
96
|
+
const byProduct = {};
|
|
97
|
+
const bySeverity = {};
|
|
98
|
+
for (const finding of findings) {
|
|
99
|
+
byProduct[finding.product] = (byProduct[finding.product] ?? 0) + 1;
|
|
100
|
+
bySeverity[finding.severity] = (bySeverity[finding.severity] ?? 0) + 1;
|
|
101
|
+
}
|
|
102
|
+
return {
|
|
103
|
+
schemaVersion: 1,
|
|
104
|
+
generatedAt: (options.now?.() ?? new Date()).toISOString(),
|
|
105
|
+
gates: outcomes,
|
|
106
|
+
deferred,
|
|
107
|
+
skipped: [],
|
|
108
|
+
excluded,
|
|
109
|
+
findings,
|
|
110
|
+
// policyChanged is unknowable: the base side of the comparison is the
|
|
111
|
+
// thing that could not be read. False rather than a third state, because
|
|
112
|
+
// no proposal is reported on a run where nothing was judged. The refusal
|
|
113
|
+
// itself is carried, and it is what both renderers lead with.
|
|
114
|
+
trustBase: { ref, policyChanged: false, refusal: detail },
|
|
115
|
+
proposals: [],
|
|
116
|
+
summary: {
|
|
117
|
+
blocking: findings.filter((finding) => finding.blocking).length,
|
|
118
|
+
byProduct,
|
|
119
|
+
bySeverity,
|
|
120
|
+
},
|
|
121
|
+
exitCode: EXIT_COULD_NOT_RUN,
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Every proposed control change, the umbrella's own policy first.
|
|
126
|
+
*
|
|
127
|
+
* The umbrella's line comes first because it is the one that decides what the
|
|
128
|
+
* others even are: a pull request that rewrites `.guardrails.yaml` is
|
|
129
|
+
* proposing to change which gates run at all, and reading that after a gate's
|
|
130
|
+
* own contract line would bury it.
|
|
131
|
+
*/
|
|
132
|
+
function collectProposals(outcomes, trustBase) {
|
|
133
|
+
const proposals = [];
|
|
134
|
+
if (trustBase?.policyChanged === true) {
|
|
135
|
+
proposals.push({ product: 'conductor', role: null, line: POLICY_PROPOSAL_LINE });
|
|
136
|
+
}
|
|
137
|
+
for (const outcome of outcomes) {
|
|
138
|
+
for (const line of outcome.trustBase?.proposals ?? []) {
|
|
139
|
+
proposals.push({ product: outcome.product, role: outcome.role, line });
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
return proposals;
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* The `intentContract` option for a run with no preparation, or nothing.
|
|
146
|
+
*
|
|
147
|
+
* A small helper rather than an inline conditional because the spread at the
|
|
148
|
+
* call site is already three lines, and because "nothing" has to be an empty
|
|
149
|
+
* object rather than an undefined property: the option is optional and
|
|
150
|
+
* `exactOptionalPropertyTypes` refuses an explicit undefined.
|
|
151
|
+
*/
|
|
152
|
+
function nativeContractOption(repoRoot) {
|
|
153
|
+
const contract = frozenNativeContractPath(repoRoot);
|
|
154
|
+
return contract === null ? {} : { intentContract: contract };
|
|
155
|
+
}
|
|
156
|
+
export function runAll(policy, options) {
|
|
157
|
+
const { gates, deferred, excluded } = partitionGates(policy, options.stage);
|
|
56
158
|
const env = options.env ?? {};
|
|
57
159
|
const skipped = [];
|
|
58
160
|
const cleanups = [];
|
|
@@ -104,6 +206,16 @@ export function runAll(policy, options) {
|
|
|
104
206
|
pathValue: options.pathValue,
|
|
105
207
|
...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
|
|
106
208
|
...(intent === undefined ? {} : { intent }),
|
|
209
|
+
// For a run with no preparation: which contract the child will read
|
|
210
|
+
// out of the repository itself. Looked up only for the gate it is
|
|
211
|
+
// about, so no other gate pays for the two stat calls.
|
|
212
|
+
...(intent !== undefined || gate.role !== 'intent'
|
|
213
|
+
? {}
|
|
214
|
+
: nativeContractOption(options.repoRoot)),
|
|
215
|
+
// Offered to every child. runGate decides which ones can take it,
|
|
216
|
+
// so a gate with no pull-request mode yet is not handed a flag it
|
|
217
|
+
// would reject, and the reason it was withheld is on the outcome.
|
|
218
|
+
...(options.trustBase === undefined ? {} : { trustBase: options.trustBase.ref }),
|
|
107
219
|
}));
|
|
108
220
|
}
|
|
109
221
|
}
|
|
@@ -138,6 +250,8 @@ export function runAll(policy, options) {
|
|
|
138
250
|
skipped,
|
|
139
251
|
excluded,
|
|
140
252
|
findings,
|
|
253
|
+
trustBase: options.trustBase ?? null,
|
|
254
|
+
proposals: collectProposals(outcomes, options.trustBase),
|
|
141
255
|
summary: {
|
|
142
256
|
blocking: findings.filter((finding) => finding.blocking).length,
|
|
143
257
|
byProduct,
|