@vaultcompass/conductor 0.2.4 → 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 +91 -14
- package/dist/envelope.d.ts +16 -0
- package/dist/gate-runner.d.ts +118 -2
- package/dist/gate-runner.js +211 -9
- 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 +102 -1
- 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-sarif.js
CHANGED
|
@@ -88,6 +88,24 @@
|
|
|
88
88
|
// Everything genuinely inside keeps the relative, forward-slashed,
|
|
89
89
|
// `%SRCROOT%`-based spelling that GitHub code scanning wants.
|
|
90
90
|
//
|
|
91
|
+
// - EVERY RESULT CARRIES AT LEAST ONE LOCATION, and the fallback is a real
|
|
92
|
+
// file rather than an invented one. GitHub code scanning rejects a whole
|
|
93
|
+
// uploaded log with "locationFromSarifResult: expected at least one
|
|
94
|
+
// location" the moment any single result has none, so one location-less
|
|
95
|
+
// result loses the entire report rather than one alert. That happened on
|
|
96
|
+
// every main-branch run of a sibling repository's guardrails job, and the
|
|
97
|
+
// offender was `intent-guard/gate-blocked`, whose subject is `none`.
|
|
98
|
+
//
|
|
99
|
+
// This does NOT weaken the two rules above it. A location the gate gave is
|
|
100
|
+
// never overwritten, no region is invented, and no path is fabricated: the
|
|
101
|
+
// fallback is the CONTROL FILE this result is a statement about, which is
|
|
102
|
+
// a file that exists in the repository and is the one a reader would open.
|
|
103
|
+
// For the umbrella's own results and for the two gates whose control files
|
|
104
|
+
// the umbrella does not read, that is the policy file, which is where the
|
|
105
|
+
// gate that produced the result is enabled. For the intent gate it is the
|
|
106
|
+
// frozen contract, when the run recorded which of the two state
|
|
107
|
+
// directories answered.
|
|
108
|
+
//
|
|
91
109
|
// - A REGION ONLY WHEN A REAL POSITION IS KNOWN. One of the three gates
|
|
92
110
|
// reports a line and a column; the other two report no position at all.
|
|
93
111
|
// An invented startLine annotates an unrelated line of somebody's file
|
|
@@ -99,6 +117,7 @@
|
|
|
99
117
|
// normalize.ts, which is where the omission would stop mattering if the
|
|
100
118
|
// field were ever carried.
|
|
101
119
|
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
120
|
+
import { POLICY_FILE_NAME } from './policy.js';
|
|
102
121
|
const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
|
|
103
122
|
export const UMBRELLA_DRIVER_NAME = 'conductor';
|
|
104
123
|
/**
|
|
@@ -242,7 +261,41 @@ function locationsFor(finding) {
|
|
|
242
261
|
return undefined;
|
|
243
262
|
}
|
|
244
263
|
}
|
|
245
|
-
|
|
264
|
+
/**
|
|
265
|
+
* The file a result with no location of its own is filed against.
|
|
266
|
+
*
|
|
267
|
+
* A real, repository-relative path, never a placeholder: the policy file is
|
|
268
|
+
* where every gate is enabled and where a reader goes to change what ran, and
|
|
269
|
+
* for the intent gate the frozen contract is the file its gate-state findings
|
|
270
|
+
* are literally about. Both exist in the repository whenever a run happened at
|
|
271
|
+
* all, so this never points at nothing.
|
|
272
|
+
*/
|
|
273
|
+
export function fallbackLocationFor(gate) {
|
|
274
|
+
const source = gate?.intent?.contractSource;
|
|
275
|
+
if (source !== undefined && source.kind === 'native') {
|
|
276
|
+
return source.path;
|
|
277
|
+
}
|
|
278
|
+
return POLICY_FILE_NAME;
|
|
279
|
+
}
|
|
280
|
+
/**
|
|
281
|
+
* The locations for one result, with the fallback filled in where a real one
|
|
282
|
+
* is missing.
|
|
283
|
+
*
|
|
284
|
+
* TWO SEPARATE CASES, and conflating them would lose information. A finding
|
|
285
|
+
* with no locations at all gets one made of the fallback. A finding that has
|
|
286
|
+
* a LOGICAL location and no physical one (a drift finding's contract
|
|
287
|
+
* category, a package whose manifest could not be placed) keeps the logical
|
|
288
|
+
* one and gains the physical fallback beside it, because the logical location
|
|
289
|
+
* is what a consumer groups on and replacing it would drop that.
|
|
290
|
+
*/
|
|
291
|
+
function withFallbackLocation(locations, fallbackUri) {
|
|
292
|
+
const physicalLocation = { artifactLocation: { uri: fallbackUri, uriBaseId: '%SRCROOT%' } };
|
|
293
|
+
if (locations === undefined || locations.length === 0) {
|
|
294
|
+
return [{ physicalLocation }];
|
|
295
|
+
}
|
|
296
|
+
return locations.map((location) => location.physicalLocation === undefined ? { ...location, physicalLocation } : location);
|
|
297
|
+
}
|
|
298
|
+
function toResult(finding, fallbackUri) {
|
|
246
299
|
// A path that escapes the source root gets no physical location, so the
|
|
247
300
|
// path itself is carried here instead. Dropping a location is honest;
|
|
248
301
|
// dropping the information as well would just lose the finding's subject.
|
|
@@ -265,10 +318,9 @@ function toResult(finding) {
|
|
|
265
318
|
if (finding.fingerprint !== null) {
|
|
266
319
|
entry.partialFingerprints = { [fingerprintKey(finding.fingerprint.scope)]: finding.fingerprint.value };
|
|
267
320
|
}
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
}
|
|
321
|
+
// Unconditional. The old code omitted the key when there was nothing
|
|
322
|
+
// honest to say, and one such result makes GitHub reject the whole log.
|
|
323
|
+
entry.locations = withFallbackLocation(locationsFor(finding), fallbackUri);
|
|
272
324
|
return entry;
|
|
273
325
|
}
|
|
274
326
|
function ruleDeclarations(findings) {
|
|
@@ -286,10 +338,7 @@ function toNotification(notification) {
|
|
|
286
338
|
// filed under when it was a result, so a consumer that had rules for
|
|
287
339
|
// these still recognises them.
|
|
288
340
|
descriptor: { id: notification.id },
|
|
289
|
-
|
|
290
|
-
// code, and a notification that arrived as a warning would push these
|
|
291
|
-
// straight back into the alert list they were moved out of.
|
|
292
|
-
level: 'note',
|
|
341
|
+
level: notification.level ?? 'note',
|
|
293
342
|
message: { text: notification.message },
|
|
294
343
|
properties: { details: notification.details },
|
|
295
344
|
};
|
|
@@ -298,7 +347,9 @@ function notificationDeclarations(notifications) {
|
|
|
298
347
|
const ids = [...new Set(notifications.map((notification) => notification.id))].sort();
|
|
299
348
|
return ids.map((id) => ({ id, name: id.slice(id.indexOf('/') + 1) }));
|
|
300
349
|
}
|
|
301
|
-
function makeRun(name, version, findings,
|
|
350
|
+
function makeRun(name, version, findings,
|
|
351
|
+
/** The artifact a result with no location of its own is filed against. */
|
|
352
|
+
fallbackUri, properties, invocation) {
|
|
302
353
|
const notifications = invocation?.notifications ?? [];
|
|
303
354
|
return {
|
|
304
355
|
tool: {
|
|
@@ -316,7 +367,7 @@ function makeRun(name, version, findings, properties, invocation) {
|
|
|
316
367
|
: { notifications: notificationDeclarations(notifications) }),
|
|
317
368
|
},
|
|
318
369
|
},
|
|
319
|
-
results: findings.map(toResult),
|
|
370
|
+
results: findings.map((finding) => toResult(finding, fallbackUri)),
|
|
320
371
|
...(invocation === undefined
|
|
321
372
|
? {}
|
|
322
373
|
: {
|
|
@@ -500,6 +551,141 @@ function skippedNotifications(result) {
|
|
|
500
551
|
details: { role: gate.role, product: gate.product, reason: gate.reason },
|
|
501
552
|
}));
|
|
502
553
|
}
|
|
554
|
+
/**
|
|
555
|
+
* The control inputs this pull request proposes to change, as notifications.
|
|
556
|
+
*
|
|
557
|
+
* A NOTIFICATION and never a result, decided by the rule at
|
|
558
|
+
* skippedNotifications below rather than by a fresh judgment. A proposed
|
|
559
|
+
* control change is a statement about CONFIGURATION in the purest form that
|
|
560
|
+
* rule describes: nothing went wrong, nobody's code is at fault, the
|
|
561
|
+
* proposal did not take effect, and it is true of every run of this pull
|
|
562
|
+
* request until it merges or the file is reverted. As a result it would be a
|
|
563
|
+
* fingerprint-less alert reappearing on every push to the branch, which is
|
|
564
|
+
* how a code scanning tab becomes something nobody reads.
|
|
565
|
+
*
|
|
566
|
+
* The id is the UMBRELLA'S, even for a line a gate wrote, and that is a
|
|
567
|
+
* deliberate departure from skippedNotifications, which uses the gate's
|
|
568
|
+
* namespace. The statement here is the umbrella's summing: it is the one
|
|
569
|
+
* place a reviewer sees that a pull request tried to change three gates'
|
|
570
|
+
* rules at once, which is the sentence the whole wave exists to produce. The
|
|
571
|
+
* gate that raised each line is in the details.
|
|
572
|
+
*/
|
|
573
|
+
function proposalNotifications(result) {
|
|
574
|
+
return result.proposals.map((proposal) => ({
|
|
575
|
+
id: 'conductor/control-change-proposed',
|
|
576
|
+
message: `This pull request proposes a control change that did NOT take effect for this run: ` +
|
|
577
|
+
`${proposal.line} (${proposal.product}). The rules came from ` +
|
|
578
|
+
`${result.trustBase?.ref ?? 'the base ref'}; the proposed change decides what runs once ` +
|
|
579
|
+
'it is on the base branch.',
|
|
580
|
+
details: {
|
|
581
|
+
product: proposal.product,
|
|
582
|
+
role: proposal.role,
|
|
583
|
+
proposal: proposal.line,
|
|
584
|
+
ref: result.trustBase?.ref ?? null,
|
|
585
|
+
},
|
|
586
|
+
}));
|
|
587
|
+
}
|
|
588
|
+
/**
|
|
589
|
+
* The trust base the umbrella refused, when it refused one.
|
|
590
|
+
*
|
|
591
|
+
* ERROR LEVEL, and the only notification here that is not a note. Every other
|
|
592
|
+
* one says how much of the policy a run covered; this one says the run did
|
|
593
|
+
* not happen. It is the one statement in this file that a reader must not be
|
|
594
|
+
* able to scroll past.
|
|
595
|
+
*
|
|
596
|
+
* A NOTIFICATION rather than a result even so, and the reason is the
|
|
597
|
+
* discriminator further down: a result is about a place in somebody's code,
|
|
598
|
+
* and this is about a ref. The could-not-run RESULTS for whatever gates the
|
|
599
|
+
* inventory named sit beside it in the same run and carry the same sentence,
|
|
600
|
+
* so a consumer that reads only results still learns that nothing ran.
|
|
601
|
+
*/
|
|
602
|
+
function trustBaseRefusedNotifications(result) {
|
|
603
|
+
const refusal = result.trustBase?.refusal;
|
|
604
|
+
if (refusal === undefined || refusal === null) {
|
|
605
|
+
return [];
|
|
606
|
+
}
|
|
607
|
+
return [
|
|
608
|
+
{
|
|
609
|
+
id: 'conductor/trust-base-refused',
|
|
610
|
+
level: 'error',
|
|
611
|
+
message: `conductor refused the trust base "${result.trustBase?.ref ?? ''}", so no gate ran and ` +
|
|
612
|
+
`NOTHING WAS CHECKED by this run. ${refusal}`,
|
|
613
|
+
details: { ref: result.trustBase?.ref ?? null, reason: refusal },
|
|
614
|
+
},
|
|
615
|
+
];
|
|
616
|
+
}
|
|
617
|
+
/**
|
|
618
|
+
* The gates whose PROGRAM the umbrella refused to run.
|
|
619
|
+
*
|
|
620
|
+
* ERROR level, beside the refused trust base and for the same reason: this is
|
|
621
|
+
* not a statement about how much of the policy a run covered. A pull request
|
|
622
|
+
* put a file where the gate's binary resolves and the umbrella declined to
|
|
623
|
+
* execute it, which a reviewer has to meet rather than scroll past.
|
|
624
|
+
*
|
|
625
|
+
* The gate's could-not-run RESULT carries the same sentence, so a consumer
|
|
626
|
+
* reading only results still learns the gate did not run. This adds the
|
|
627
|
+
* structured half: which gate, which program, and which ref it was measured
|
|
628
|
+
* against.
|
|
629
|
+
*/
|
|
630
|
+
function programRefusedNotifications(result) {
|
|
631
|
+
return result.gates.flatMap((gate) => {
|
|
632
|
+
if (gate.couldNotRun?.reason !== 'gate-program-refused') {
|
|
633
|
+
return [];
|
|
634
|
+
}
|
|
635
|
+
return [
|
|
636
|
+
{
|
|
637
|
+
id: 'conductor/gate-program-refused',
|
|
638
|
+
level: 'error',
|
|
639
|
+
message: `The ${gate.role} gate (${gate.product}) did NOT run: its program is a file this pull ` +
|
|
640
|
+
`request controls, so running it would let the pull request choose the program that ` +
|
|
641
|
+
`judges it. ${gate.couldNotRun.detail}`,
|
|
642
|
+
details: {
|
|
643
|
+
role: gate.role,
|
|
644
|
+
product: gate.product,
|
|
645
|
+
program: gate.binary?.program ?? null,
|
|
646
|
+
ref: gate.trustBase?.ref ?? null,
|
|
647
|
+
reason: gate.couldNotRun.detail,
|
|
648
|
+
},
|
|
649
|
+
},
|
|
650
|
+
];
|
|
651
|
+
});
|
|
652
|
+
}
|
|
653
|
+
/**
|
|
654
|
+
* The gates the umbrella could not put into pull-request mode.
|
|
655
|
+
*
|
|
656
|
+
* The loud half of the same mode, and by the discriminator below it is a
|
|
657
|
+
* close call that lands on notification: nothing went wrong with the run, and
|
|
658
|
+
* the fact is true of the configuration (an older gate is installed) rather
|
|
659
|
+
* than of this change, so it is identical on every run until somebody
|
|
660
|
+
* upgrades. What it says is how much of the pull-request boundary this run
|
|
661
|
+
* actually had, which is a coverage statement.
|
|
662
|
+
*
|
|
663
|
+
* It is still the most important notification in the log. A gate here read
|
|
664
|
+
* its own control inputs out of the tree under judgment.
|
|
665
|
+
*/
|
|
666
|
+
function trustBaseWithheldNotifications(result) {
|
|
667
|
+
return result.gates.flatMap((gate) => {
|
|
668
|
+
const withheld = gate.trustBase?.withheld;
|
|
669
|
+
if (withheld === undefined || withheld === null) {
|
|
670
|
+
return [];
|
|
671
|
+
}
|
|
672
|
+
return [
|
|
673
|
+
{
|
|
674
|
+
id: 'conductor/trust-base-not-passed',
|
|
675
|
+
message: `The ${gate.role} gate (${gate.product}) did NOT run in pull-request mode, so it read ` +
|
|
676
|
+
`its own control inputs from the tree being judged rather than from ` +
|
|
677
|
+
`${gate.trustBase?.ref ?? 'the base ref'}. ${withheld}`,
|
|
678
|
+
details: {
|
|
679
|
+
role: gate.role,
|
|
680
|
+
product: gate.product,
|
|
681
|
+
productVersion: gate.productVersion,
|
|
682
|
+
ref: gate.trustBase?.ref ?? null,
|
|
683
|
+
reason: withheld,
|
|
684
|
+
},
|
|
685
|
+
},
|
|
686
|
+
];
|
|
687
|
+
});
|
|
688
|
+
}
|
|
503
689
|
/**
|
|
504
690
|
* The gates the policy file told not to decide anything, as notifications.
|
|
505
691
|
*
|
|
@@ -582,7 +768,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
582
768
|
// and one measured against a contract somebody approved by hand are
|
|
583
769
|
// different claims, and so are one over a branch diff and one over an
|
|
584
770
|
// index.
|
|
585
|
-
runs.push(makeRun(gate.product, gate.productVersion, own, {
|
|
771
|
+
runs.push(makeRun(gate.product, gate.productVersion, own, fallbackLocationFor(gate), {
|
|
586
772
|
enforced: gate.enforce,
|
|
587
773
|
stage: gate.stage,
|
|
588
774
|
...(gate.intent === undefined
|
|
@@ -609,18 +795,43 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
609
795
|
...skippedNotifications(result),
|
|
610
796
|
...unenforcedNotifications(result),
|
|
611
797
|
...legacyStateDirNotifications(result),
|
|
798
|
+
...trustBaseRefusedNotifications(result),
|
|
799
|
+
...programRefusedNotifications(result),
|
|
800
|
+
...proposalNotifications(result),
|
|
801
|
+
...trustBaseWithheldNotifications(result),
|
|
612
802
|
];
|
|
613
803
|
// Notifications earn the run on their own. Before this, the umbrella run
|
|
614
804
|
// existed only when it had findings and a deferred gate was one; without
|
|
615
805
|
// this clause a commit-stage log would say nothing whatever about the gate
|
|
616
806
|
// that did not run there.
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
807
|
+
//
|
|
808
|
+
// A REFUSAL EARNS IT UNCONDITIONALLY, and that clause is not redundant with
|
|
809
|
+
// the two beside it even though a refusal always adds a notification: it
|
|
810
|
+
// says out loud that the worst run this tool can have is the one case where
|
|
811
|
+
// an empty log is not acceptable. `{"runs": []}` was the output when the
|
|
812
|
+
// base ref could not be read and the head's inventory named no gate, and an
|
|
813
|
+
// empty log uploads cleanly and is indistinguishable from a repository
|
|
814
|
+
// nobody scanned.
|
|
815
|
+
if (umbrellaFindings.length > 0 ||
|
|
816
|
+
notifications.length > 0 ||
|
|
817
|
+
(result.trustBase?.refusal ?? null) !== null) {
|
|
818
|
+
runs.push(makeRun(UMBRELLA_DRIVER_NAME, umbrellaVersion, umbrellaFindings, POLICY_FILE_NAME,
|
|
819
|
+
// On the umbrella's run rather than on any gate's, because it is a
|
|
820
|
+
// fact about the whole run: every gate that could take the flag was
|
|
821
|
+
// handed this same ref. A consumer reading only the log can then tell
|
|
822
|
+
// a pull-request run from an ordinary one without parsing sentences.
|
|
823
|
+
result.trustBase === null ? undefined : { trustBase: result.trustBase }, {
|
|
824
|
+
// A claim about whether the analysis completed, taken from the
|
|
825
|
+
// gates rather than from the exit code: an unenforced gate that
|
|
826
|
+
// could not run leaves the run at exit 0, and nothing was checked
|
|
827
|
+
// by it either way. Written whenever this run is written, in both
|
|
828
|
+
// directions.
|
|
829
|
+
// A refusal is false whatever the gate list says, and with an
|
|
830
|
+
// empty inventory `every` over nothing is vacuously true, which
|
|
831
|
+
// would have claimed the analysis completed on the one run where
|
|
832
|
+
// nothing was even attempted.
|
|
833
|
+
executionSuccessful: (result.trustBase?.refusal ?? null) === null &&
|
|
834
|
+
result.gates.every((gate) => gate.couldNotRun === null),
|
|
624
835
|
notifications,
|
|
625
836
|
}));
|
|
626
837
|
}
|
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
|
|
@@ -478,11 +559,25 @@ function summaryLine(result) {
|
|
|
478
559
|
parts.push(gatesReportingIgnored.length === result.gates.length
|
|
479
560
|
? `${suppressed} suppressed, ${ignored} ignored across all gates.`
|
|
480
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
|
+
}
|
|
481
575
|
parts.push('Re-run with --verbose for the full report.');
|
|
482
576
|
return parts.join(' ');
|
|
483
577
|
}
|
|
484
578
|
export function renderText(result, options = {}) {
|
|
485
|
-
|
|
579
|
+
const refusal = refusalLines(result);
|
|
580
|
+
if (refusal.length === 0 && !options.verbose && isFullyClean(result)) {
|
|
486
581
|
return `${summaryLine(result)}\n`;
|
|
487
582
|
}
|
|
488
583
|
// Counted over EVERY gate, unenforced ones included, and deliberately not
|
|
@@ -494,6 +589,8 @@ export function renderText(result, options = {}) {
|
|
|
494
589
|
// different questions, so two numbers, and the section headers and the
|
|
495
590
|
// "not enforced" lines are what connect them.
|
|
496
591
|
const lines = [
|
|
592
|
+
...refusal,
|
|
593
|
+
...(refusal.length === 0 ? [] : ['']),
|
|
497
594
|
`conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
|
|
498
595
|
];
|
|
499
596
|
for (const gate of result.gates) {
|
|
@@ -503,6 +600,10 @@ export function renderText(result, options = {}) {
|
|
|
503
600
|
if (aside.length > 0) {
|
|
504
601
|
lines.push('', ...aside);
|
|
505
602
|
}
|
|
603
|
+
const trust = trustBaseLines(result);
|
|
604
|
+
if (trust.length > 0) {
|
|
605
|
+
lines.push('', ...trust);
|
|
606
|
+
}
|
|
506
607
|
// A derived severity is marked with a trailing asterisk above; say what
|
|
507
608
|
// that means rather than leaving a reader to guess, and only when one is
|
|
508
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,
|