@vaultcompass/conductor 0.5.0 → 0.6.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 +212 -23
- package/dist/cli.js +169 -40
- package/dist/gate-runner.js +12 -2
- package/dist/normalize.d.ts +13 -2
- package/dist/normalize.js +137 -8
- package/dist/output-sarif.js +58 -0
- package/dist/output-text.js +59 -20
- package/dist/products.d.ts +16 -0
- package/dist/products.js +9 -0
- package/dist/run.d.ts +40 -0
- package/dist/run.js +39 -1
- package/dist/trust-base.d.ts +68 -0
- package/dist/trust-base.js +152 -0
- package/package.json +4 -3
package/dist/output-sarif.js
CHANGED
|
@@ -118,6 +118,7 @@
|
|
|
118
118
|
// normalize.ts, which is where the omission would stop mattering if the
|
|
119
119
|
// field were ever carried.
|
|
120
120
|
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
121
|
+
import { INTENT_WARNING } from './normalize.js';
|
|
121
122
|
import { POLICY_FILE_NAME } from './policy.js';
|
|
122
123
|
const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
|
|
123
124
|
export const UMBRELLA_DRIVER_NAME = 'conductor';
|
|
@@ -499,6 +500,25 @@ function excludedNotifications(result) {
|
|
|
499
500
|
details: { role: gate.role, product: gate.product },
|
|
500
501
|
}));
|
|
501
502
|
}
|
|
503
|
+
/**
|
|
504
|
+
* The gates skipped because the head tree equals the trust base's tree, as
|
|
505
|
+
* notifications (issue #69).
|
|
506
|
+
*
|
|
507
|
+
* Same discriminator as excludedNotifications just above: how much of the
|
|
508
|
+
* policy this run covered is a statement about the run, not about anybody's
|
|
509
|
+
* code, so it is a NOTE and never a result. Reachable only on the one
|
|
510
|
+
* accepted equal-tree shape (a merge commit whose first parent is the trust
|
|
511
|
+
* base; see trust-base.ts), where every enabled gate whose profile does not
|
|
512
|
+
* say readsHistory is recorded here instead of being spawned.
|
|
513
|
+
*/
|
|
514
|
+
function treeUnchangedNotifications(result) {
|
|
515
|
+
return result.treeUnchanged.map((gate) => ({
|
|
516
|
+
id: 'conductor/tree-unchanged',
|
|
517
|
+
message: `The ${gate.role} gate (${gate.product}) did not run: the head tree is identical to the ` +
|
|
518
|
+
'base tree, so there is no change for this gate to judge.',
|
|
519
|
+
details: { role: gate.role, product: gate.product },
|
|
520
|
+
}));
|
|
521
|
+
}
|
|
502
522
|
/**
|
|
503
523
|
* The gates that had nothing to check, as notifications.
|
|
504
524
|
*
|
|
@@ -552,6 +572,36 @@ function skippedNotifications(result) {
|
|
|
552
572
|
details: { role: gate.role, product: gate.product, reason: gate.reason },
|
|
553
573
|
}));
|
|
554
574
|
}
|
|
575
|
+
/**
|
|
576
|
+
* intent-guard 1.7.0's own advance-notice warnings, as notifications.
|
|
577
|
+
*
|
|
578
|
+
* A frozen contract's protected_paths or allowed_paths entry that no git
|
|
579
|
+
* path can ever match is a statement about that contract's own
|
|
580
|
+
* configuration, in the same sense skippedNotifications above already
|
|
581
|
+
* describes: nothing went wrong with this commit, nobody's code is at
|
|
582
|
+
* fault, and the statement is true of every run against this contract until
|
|
583
|
+
* it is edited. As a result it belongs beside no-contract and the rest, a
|
|
584
|
+
* notification rather than a result, so it never gains a severity, a
|
|
585
|
+
* fingerprint, or a place in the exit code.
|
|
586
|
+
*
|
|
587
|
+
* Read off `run.diagnostics` rather than `diagnostics`, deliberately: this
|
|
588
|
+
* repository's `diagnostics` field is the umbrella's OWN fixed set of ids
|
|
589
|
+
* (see AGENTS.md), and intent-guard/warning is not one of them. It is the
|
|
590
|
+
* gate's own statement, carried through unchanged, the same way
|
|
591
|
+
* dep-guard's online-deadline-exceeded diagnostic already prints under the
|
|
592
|
+
* gate in the text report; this is the SARIF half of that same channel,
|
|
593
|
+
* scoped to intent-guard's own warning code so a future run-diagnostic on
|
|
594
|
+
* another gate does not silently start appearing here too.
|
|
595
|
+
*/
|
|
596
|
+
function intentWarningNotifications(result) {
|
|
597
|
+
return result.gates.flatMap((gate) => gate.run.diagnostics
|
|
598
|
+
.filter((diagnostic) => diagnostic.code === INTENT_WARNING)
|
|
599
|
+
.map((diagnostic) => ({
|
|
600
|
+
id: diagnostic.code,
|
|
601
|
+
message: diagnostic.message,
|
|
602
|
+
details: { role: gate.role, product: gate.product },
|
|
603
|
+
})));
|
|
604
|
+
}
|
|
555
605
|
/**
|
|
556
606
|
* The control inputs this pull request proposes to change, as notifications.
|
|
557
607
|
*
|
|
@@ -810,6 +860,12 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
810
860
|
...(gate.intent === undefined
|
|
811
861
|
? {}
|
|
812
862
|
: { contractSource: gate.intent.contractSource, baseRef: gate.intent.baseRef }),
|
|
863
|
+
// The gate's own run facts (issue #72: the lockfiles the umbrella
|
|
864
|
+
// handed osv-scanner, and dep-guard's online-lookup reporting), the
|
|
865
|
+
// same bag the text report renders as scalars. Carried verbatim and
|
|
866
|
+
// only when there is something in it, so a gate that reports none of
|
|
867
|
+
// this keeps the properties shape it had before.
|
|
868
|
+
...(Object.keys(gate.run.details).length === 0 ? {} : { details: gate.run.details }),
|
|
813
869
|
}));
|
|
814
870
|
}
|
|
815
871
|
// Still RESULTS, deliberately, and the asymmetry with the three above is
|
|
@@ -828,6 +884,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
828
884
|
const notifications = [
|
|
829
885
|
...deferredNotifications(result),
|
|
830
886
|
...excludedNotifications(result),
|
|
887
|
+
...treeUnchangedNotifications(result),
|
|
831
888
|
...skippedNotifications(result),
|
|
832
889
|
...unenforcedNotifications(result),
|
|
833
890
|
...legacyStateDirNotifications(result),
|
|
@@ -836,6 +893,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
836
893
|
...proposalNotifications(result),
|
|
837
894
|
...trustBaseWithheldNotifications(result),
|
|
838
895
|
...nodeModulesSkippedNotifications(result),
|
|
896
|
+
...intentWarningNotifications(result),
|
|
839
897
|
];
|
|
840
898
|
// Notifications earn the run on their own. Before this, the umbrella run
|
|
841
899
|
// existed only when it had findings and a deferred gate was one; without
|
package/dist/output-text.js
CHANGED
|
@@ -218,6 +218,18 @@ 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
|
+
* One line per gate skipped because the head tree equals the trust base's
|
|
223
|
+
* (issue #69).
|
|
224
|
+
*
|
|
225
|
+
* Modeled on deferredLines and excludedLines just above: nothing ran for
|
|
226
|
+
* these gates either, so there is no header, no exit code and no duration to
|
|
227
|
+
* put in a section, and the reason has to be on screen or a run in this shape
|
|
228
|
+
* reads exactly like a run that judged every enabled gate's tree.
|
|
229
|
+
*/
|
|
230
|
+
function treeUnchangedLines(result) {
|
|
231
|
+
return result.treeUnchanged.map((gate) => ` tree-unchanged ${gate.role} ${gate.product} did not run: the head tree is identical to the base tree, so there is no change for this gate to judge`);
|
|
232
|
+
}
|
|
221
233
|
/**
|
|
222
234
|
* The one sentence the whole of pull-request mode has to fit into.
|
|
223
235
|
*
|
|
@@ -392,25 +404,40 @@ function verdictForRun(result, advisory) {
|
|
|
392
404
|
const blocking = enforcedGates
|
|
393
405
|
.flatMap((gate) => gate.findings)
|
|
394
406
|
.filter((finding) => finding.blocking).length;
|
|
395
|
-
if (result.gates.length === 0 &&
|
|
396
|
-
|
|
397
|
-
//
|
|
398
|
-
//
|
|
399
|
-
//
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
//
|
|
405
|
-
//
|
|
406
|
-
//
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
.join(', ');
|
|
413
|
-
|
|
407
|
+
if (result.gates.length === 0 &&
|
|
408
|
+
(result.deferred.length > 0 || result.treeUnchanged.length > 0 || result.skipped.length > 0)) {
|
|
409
|
+
// Three distinct states can each leave result.gates empty, and a run can
|
|
410
|
+
// land in more than one of them at once: a stage that deferred one gate
|
|
411
|
+
// while another was tree-unchanged (issue #69) is a real shape, not a
|
|
412
|
+
// hypothetical, so this names EVERY one that applies rather than the
|
|
413
|
+
// first one found. Naming only "every enabled gate is deferred" when a
|
|
414
|
+
// tree-unchanged gate was also in the mix would be false: not every gate
|
|
415
|
+
// was deferred, some had nothing to judge for a different reason. All
|
|
416
|
+
// three are also distinct from "none is enabled" below, and each needs
|
|
417
|
+
// its own fix: set enabled: true is wrong for all three of them, since
|
|
418
|
+
// every gate named here IS enabled.
|
|
419
|
+
const clauses = [];
|
|
420
|
+
if (result.deferred.length > 0) {
|
|
421
|
+
// Never "every enabled gate is deferred" here: that claim is only true
|
|
422
|
+
// when nothing else in this branch fired, and a mix with a
|
|
423
|
+
// tree-unchanged or skipped gate makes it false.
|
|
424
|
+
const names = result.deferred.map((gate) => `${gate.role} at stage ${gate.stage}`).join(', ');
|
|
425
|
+
clauses.push(`deferred to a later stage (${names})`);
|
|
426
|
+
}
|
|
427
|
+
if (result.treeUnchanged.length > 0) {
|
|
428
|
+
// The head tree is identical to the trust base's, so there is nothing
|
|
429
|
+
// for these gates to judge (issue #69).
|
|
430
|
+
const names = result.treeUnchanged.map((gate) => gate.role).join(', ');
|
|
431
|
+
clauses.push(`the head tree is identical to the base tree, so there is no change for these gates to judge (${names})`);
|
|
432
|
+
}
|
|
433
|
+
if (result.skipped.length > 0) {
|
|
434
|
+
// What to do about this is NOT the same for every reason, which is why
|
|
435
|
+
// the clause comes from the skip reason rather than being written
|
|
436
|
+
// here: for a missing spec the fix is to write one, and for a waiver
|
|
437
|
+
// there is nothing to fix, because a person decided it.
|
|
438
|
+
clauses.push(result.skipped.map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`).join(', '));
|
|
439
|
+
}
|
|
440
|
+
return `verdict: exit 0, nothing was checked: ${clauses.join('; ')}.`;
|
|
414
441
|
}
|
|
415
442
|
if (result.gates.length === 0) {
|
|
416
443
|
// Exit 0 with an empty report is indistinguishable from a clean run at a
|
|
@@ -552,6 +579,13 @@ function summaryLine(result) {
|
|
|
552
579
|
.join(', ');
|
|
553
580
|
parts.push(`Deferred to a later stage: ${names}.`);
|
|
554
581
|
}
|
|
582
|
+
// Same reasoning as the deferred clause, for the equal-tree shape
|
|
583
|
+
// (issue #69): these gates are enabled and did not run, so a clean run in
|
|
584
|
+
// this shape must not read like a run that judged their tree too.
|
|
585
|
+
if (result.treeUnchanged.length > 0) {
|
|
586
|
+
const names = result.treeUnchanged.map((gate) => `${gate.role} (${gate.product})`).join(', ');
|
|
587
|
+
parts.push(`Tree unchanged from the trust base, skipped: ${names}.`);
|
|
588
|
+
}
|
|
555
589
|
// Same reasoning as the deferred clause. A gate that ran and had nothing to
|
|
556
590
|
// check covered none of this commit, and silence there makes a branch with
|
|
557
591
|
// no spec read as a branch that passed the intent gate.
|
|
@@ -700,7 +734,12 @@ export function renderText(result, options = {}) {
|
|
|
700
734
|
for (const gate of result.gates) {
|
|
701
735
|
lines.push(...gateSection(gate));
|
|
702
736
|
}
|
|
703
|
-
const aside = [
|
|
737
|
+
const aside = [
|
|
738
|
+
...deferredLines(result),
|
|
739
|
+
...skippedLines(result),
|
|
740
|
+
...excludedLines(result),
|
|
741
|
+
...treeUnchangedLines(result),
|
|
742
|
+
];
|
|
704
743
|
if (aside.length > 0) {
|
|
705
744
|
lines.push('', ...aside);
|
|
706
745
|
}
|
package/dist/products.d.ts
CHANGED
|
@@ -67,6 +67,22 @@ export interface ProductProfile {
|
|
|
67
67
|
* materialised from the base ref and the tool is run from that directory.
|
|
68
68
|
*/
|
|
69
69
|
followsConfigExtend: boolean;
|
|
70
|
+
/**
|
|
71
|
+
* Whether this gate's INPUT is git history rather than the tree being
|
|
72
|
+
* judged.
|
|
73
|
+
*
|
|
74
|
+
* True only for gitleaks. Every other gate here reads the tree (vault-guard
|
|
75
|
+
* and dep-guard scan files, intent-guard reads a diff of paths) or a
|
|
76
|
+
* lockfile in it (osv-scanner), so when the head tree is byte-identical to
|
|
77
|
+
* the trust base's -- issue #69's shape, a value committed and then backed
|
|
78
|
+
* out inside one pull request -- those gates have nothing to judge that the
|
|
79
|
+
* base ref did not already judge, and the umbrella skips them rather than
|
|
80
|
+
* reporting a clean scan of a change that is not there. gitleaks' report is
|
|
81
|
+
* about commits between the base and HEAD, not about either tree, so it is
|
|
82
|
+
* the one gate an equal tree does not blind: see `decideTrustBase` and the
|
|
83
|
+
* equal-tree branch in `runAll` (src/run.ts).
|
|
84
|
+
*/
|
|
85
|
+
readsHistory: boolean;
|
|
70
86
|
}
|
|
71
87
|
/**
|
|
72
88
|
* The lockfiles osv-scanner is handed, matched by base name at any depth
|
package/dist/products.js
CHANGED
|
@@ -57,6 +57,7 @@ function managedProfile(product) {
|
|
|
57
57
|
stderrError: null,
|
|
58
58
|
lockfileNames: null,
|
|
59
59
|
followsConfigExtend: false,
|
|
60
|
+
readsHistory: false,
|
|
60
61
|
};
|
|
61
62
|
}
|
|
62
63
|
const PROFILES = {
|
|
@@ -94,6 +95,11 @@ const PROFILES = {
|
|
|
94
95
|
stderrError: /^\S+\s+ERR\s/,
|
|
95
96
|
lockfileNames: null,
|
|
96
97
|
followsConfigExtend: true,
|
|
98
|
+
// gitleaks reads git history (--log-opts), never the tree, which is
|
|
99
|
+
// exactly what makes it the one gate an equal-tree pull request does not
|
|
100
|
+
// blind (issue #69): the history between the base and HEAD still holds
|
|
101
|
+
// whatever was committed and backed out, even when the two trees match.
|
|
102
|
+
readsHistory: true,
|
|
97
103
|
},
|
|
98
104
|
'osv-scanner': {
|
|
99
105
|
product: 'osv-scanner',
|
|
@@ -116,6 +122,9 @@ const PROFILES = {
|
|
|
116
122
|
stderrError: null,
|
|
117
123
|
lockfileNames: OSV_LOCKFILE_NAMES,
|
|
118
124
|
followsConfigExtend: false,
|
|
125
|
+
// osv-scanner reads the tracked lockfiles it is handed, which are the
|
|
126
|
+
// tree being judged, not history.
|
|
127
|
+
readsHistory: false,
|
|
119
128
|
},
|
|
120
129
|
};
|
|
121
130
|
export function profileFor(product) {
|
package/dist/run.d.ts
CHANGED
|
@@ -31,6 +31,24 @@ export interface ExcludedGate {
|
|
|
31
31
|
role: GateRole;
|
|
32
32
|
product: Product;
|
|
33
33
|
}
|
|
34
|
+
/**
|
|
35
|
+
* An enabled gate skipped because the head tree equals the trust base's tree
|
|
36
|
+
* (issue #69).
|
|
37
|
+
*
|
|
38
|
+
* Only reachable when `RunTrustBase.treeUnchanged` is true, which itself only
|
|
39
|
+
* happens on the one accepted equal-tree shape (see trust-base.ts): a merge
|
|
40
|
+
* commit whose first parent is the base. In that shape a tree-reading gate
|
|
41
|
+
* has nothing to judge that the base ref did not already judge, so it is
|
|
42
|
+
* recorded here rather than run, exactly the way DeferredGate and
|
|
43
|
+
* ExcludedGate record a gate that did not run rather than reporting it as
|
|
44
|
+
* clean. NOT a GateOutcome, for the same reason those two are not one: no
|
|
45
|
+
* binary was looked for, nothing was spawned, and there is no exit code to
|
|
46
|
+
* report.
|
|
47
|
+
*/
|
|
48
|
+
export interface TreeUnchangedGate {
|
|
49
|
+
role: GateRole;
|
|
50
|
+
product: Product;
|
|
51
|
+
}
|
|
34
52
|
/**
|
|
35
53
|
* An enabled gate that had nothing to check.
|
|
36
54
|
*
|
|
@@ -102,6 +120,23 @@ export interface RunTrustBase {
|
|
|
102
120
|
* depth 1 and so carries no base ref.
|
|
103
121
|
*/
|
|
104
122
|
refusal: string | null;
|
|
123
|
+
/**
|
|
124
|
+
* Whether HEAD's tree is byte-identical to this ref's tree, on a run that
|
|
125
|
+
* was not refused (issue #69).
|
|
126
|
+
*
|
|
127
|
+
* OPTIONAL, and read as false wherever absent, rather than a required
|
|
128
|
+
* field: most `RunTrustBase` values in this codebase's own tests are built
|
|
129
|
+
* by hand for a run where the trees plainly differ, and a required field
|
|
130
|
+
* would be a mechanical edit to every one of them for a fact that is false
|
|
131
|
+
* in all of them. The one place this is actually computed is `policyForRun`
|
|
132
|
+
* in cli.ts, which calls `headTreeEqualsBase` (trust-base.ts) right after
|
|
133
|
+
* `refuseTrustBaseRef` returns null, on the one shape that check accepts
|
|
134
|
+
* despite an identical tree. `runAll` reads it to decide which enabled
|
|
135
|
+
* gates run: every gate whose profile says `readsHistory` runs as usual,
|
|
136
|
+
* and every other enabled gate is recorded in `RunResult.treeUnchanged`
|
|
137
|
+
* instead of being spawned.
|
|
138
|
+
*/
|
|
139
|
+
treeUnchanged?: boolean;
|
|
105
140
|
}
|
|
106
141
|
export interface RunResult {
|
|
107
142
|
schemaVersion: 1;
|
|
@@ -113,6 +148,11 @@ export interface RunResult {
|
|
|
113
148
|
skipped: SkippedGate[];
|
|
114
149
|
/** Gates the --gate flag left out. Empty with no --gate. */
|
|
115
150
|
excluded: ExcludedGate[];
|
|
151
|
+
/**
|
|
152
|
+
* Enabled gates skipped because the head tree equals the trust base's tree
|
|
153
|
+
* (issue #69). Always empty outside that one shape.
|
|
154
|
+
*/
|
|
155
|
+
treeUnchanged: TreeUnchangedGate[];
|
|
116
156
|
/**
|
|
117
157
|
* Every finding, flat across products, ordered blocking-first. Which gate
|
|
118
158
|
* produced a finding is IN the finding rather than in the structure, so a
|
package/dist/run.js
CHANGED
|
@@ -5,6 +5,7 @@ import { gateProgramRefused, preparationFailed, refuseHeadControlledBinary, runG
|
|
|
5
5
|
import { resolveBaseRef } from './intent-base.js';
|
|
6
6
|
import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
|
|
7
7
|
import { GATE_ROLES, enabledGates, runsAtStage } from './policy.js';
|
|
8
|
+
import { profileFor } from './products.js';
|
|
8
9
|
import { ResolveError, resolveGateBinary } from './resolve.js';
|
|
9
10
|
import { POLICY_PROPOSAL_LINE } from './trust-base.js';
|
|
10
11
|
/**
|
|
@@ -115,6 +116,9 @@ export function refusedTrustBase(policy, ref, detail, options) {
|
|
|
115
116
|
deferred,
|
|
116
117
|
skipped: [],
|
|
117
118
|
excluded,
|
|
119
|
+
// Always empty here: the equal-tree exception only ever applies to a run
|
|
120
|
+
// that was NOT refused, and this whole function is the refused path.
|
|
121
|
+
treeUnchanged: [],
|
|
118
122
|
findings,
|
|
119
123
|
// policyChanged is unknowable: the base side of the comparison is the
|
|
120
124
|
// thing that could not be read. False rather than a third state, because
|
|
@@ -162,8 +166,41 @@ function nativeContractOption(repoRoot) {
|
|
|
162
166
|
const contract = frozenNativeContractPath(repoRoot);
|
|
163
167
|
return contract === null ? {} : { intentContract: contract };
|
|
164
168
|
}
|
|
169
|
+
/**
|
|
170
|
+
* Splits the gates a stage and a --gate flag left in two: the ones this run
|
|
171
|
+
* actually spawns, and the ones it records as tree-unchanged instead
|
|
172
|
+
* (issue #69).
|
|
173
|
+
*
|
|
174
|
+
* A no-op, returning `gates` unchanged with an empty second list, whenever
|
|
175
|
+
* `treeUnchanged` is not true -- which is every run outside the one accepted
|
|
176
|
+
* equal-tree shape (`headTreeEqualsBase`, called from `policyForRun` in
|
|
177
|
+
* cli.ts right after `refuseTrustBaseRef` returns null). Inside that shape a
|
|
178
|
+
* tree-reading gate has nothing to judge that the base ref did not already
|
|
179
|
+
* judge, so only the gates whose profile says `readsHistory` -- gitleaks
|
|
180
|
+
* today, see src/products.ts -- are kept to run with their ordinary
|
|
181
|
+
* arguments; gitleaks already gets `--log-opts <base>..HEAD`
|
|
182
|
+
* (src/gate-runner.ts, gateArgs), which is the range that still holds
|
|
183
|
+
* whatever was committed and backed out.
|
|
184
|
+
*/
|
|
185
|
+
function splitOnTreeUnchanged(gates, trustBase) {
|
|
186
|
+
if (trustBase?.treeUnchanged !== true) {
|
|
187
|
+
return { toRun: gates, treeUnchanged: [] };
|
|
188
|
+
}
|
|
189
|
+
const toRun = [];
|
|
190
|
+
const treeUnchanged = [];
|
|
191
|
+
for (const gate of gates) {
|
|
192
|
+
if (profileFor(gate.product).readsHistory) {
|
|
193
|
+
toRun.push(gate);
|
|
194
|
+
}
|
|
195
|
+
else {
|
|
196
|
+
treeUnchanged.push({ role: gate.role, product: gate.product });
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
return { toRun, treeUnchanged };
|
|
200
|
+
}
|
|
165
201
|
export function runAll(policy, options) {
|
|
166
|
-
const { gates, deferred, excluded } = partitionGates(policy, options.stage);
|
|
202
|
+
const { gates: partitioned, deferred, excluded } = partitionGates(policy, options.stage);
|
|
203
|
+
const { toRun: gates, treeUnchanged } = splitOnTreeUnchanged(partitioned, options.trustBase);
|
|
167
204
|
const env = options.env ?? {};
|
|
168
205
|
const skipped = [];
|
|
169
206
|
const cleanups = [];
|
|
@@ -284,6 +321,7 @@ export function runAll(policy, options) {
|
|
|
284
321
|
deferred,
|
|
285
322
|
skipped,
|
|
286
323
|
excluded,
|
|
324
|
+
treeUnchanged,
|
|
287
325
|
findings,
|
|
288
326
|
trustBase: options.trustBase ?? null,
|
|
289
327
|
proposals: collectProposals(outcomes, options.trustBase),
|
package/dist/trust-base.d.ts
CHANGED
|
@@ -1,3 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether HEAD's tree is byte-identical to the trust base's tree.
|
|
3
|
+
*
|
|
4
|
+
* Exported separately from `refuseTrustBaseRef` rather than folded into its
|
|
5
|
+
* return value, so that function's return type stays the simple `string |
|
|
6
|
+
* null` every other caller and test already reads. The one caller that needs
|
|
7
|
+
* this fact (`policyForRun` in cli.ts) calls it AFTER the refusal check has
|
|
8
|
+
* already passed, on the one shape that is accepted despite an identical
|
|
9
|
+
* tree: a merge commit whose first parent is the base. In that shape every
|
|
10
|
+
* tree-reading gate still has nothing to judge, and the caller uses this to
|
|
11
|
+
* decide which gates run.
|
|
12
|
+
*/
|
|
13
|
+
export declare function headTreeEqualsBase(repoRoot: string, ref: string): boolean;
|
|
1
14
|
/**
|
|
2
15
|
* Why this ref cannot be a trust base, or null when it can.
|
|
3
16
|
*
|
|
@@ -11,8 +24,63 @@
|
|
|
11
24
|
* the umbrella never spawns a child at all on a base it has already decided
|
|
12
25
|
* it cannot judge against, and it means the two gates give a user the same
|
|
13
26
|
* answer to the same mistake.
|
|
27
|
+
*
|
|
28
|
+
* The identical-tree refusal carries ONE exception (issue #69): when HEAD is
|
|
29
|
+
* a merge commit and this ref is HEAD's first parent, this returns null
|
|
30
|
+
* rather than refusing, because that is precisely the shape GitHub's own
|
|
31
|
+
* merge ref takes on a pull request whose net diff is empty. See the header
|
|
32
|
+
* comment above and `headTreeEqualsBase` below, which is how the caller
|
|
33
|
+
* learns the trees matched even on this accepted path.
|
|
14
34
|
*/
|
|
15
35
|
export declare function refuseTrustBaseRef(repoRoot: string, ref: string): string | null;
|
|
36
|
+
/**
|
|
37
|
+
* Why an explicit --trust-base cannot be honoured on a pull request, or null.
|
|
38
|
+
*
|
|
39
|
+
* Issue #58. The refusal above only refuses a ref that resolves to HEAD's own
|
|
40
|
+
* commit or to HEAD's own tree, which covers HEAD itself and an UNMOVED
|
|
41
|
+
* origin/<pr-branch>. Once the base branch has moved, origin/<pr-branch> no
|
|
42
|
+
* longer matches either test, so a same-repo pull request could set
|
|
43
|
+
* trust-base to its own branch, in its own workflow file, and have this
|
|
44
|
+
* package read .guardrails.yaml from the pull request after all -- at which
|
|
45
|
+
* point the pull request controls the whole policy, which is the one thing
|
|
46
|
+
* pull-request mode exists to prevent.
|
|
47
|
+
*
|
|
48
|
+
* action.yml's validate step now refuses an explicit trust-base input
|
|
49
|
+
* outright on a pull_request or pull_request_target event, the stronger line
|
|
50
|
+
* dep-guard's own base input took in 0.8.0. This function is the CLI's own
|
|
51
|
+
* line of defence for anyone invoking it directly in CI, bypassing that step.
|
|
52
|
+
*
|
|
53
|
+
* GITHUB_BASE_REF IS ACTIONS' OWN PULL-REQUEST SIGNAL: the base branch's
|
|
54
|
+
* NAME on a pull_request or pull_request_target event, and empty everywhere
|
|
55
|
+
* else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
|
|
56
|
+
* a platform that never sets it. When it is set, the given ref is accepted
|
|
57
|
+
* only when it resolves to the SAME COMMIT as origin/<githubBaseRef>, which
|
|
58
|
+
* is exactly what the composite action itself always passes
|
|
59
|
+
* (`--trust-base "origin/$GITHUB_BASE_REF"` in action.yml's gates step). So
|
|
60
|
+
* an ordinary pull-request run sees the given ref and the expected ref as the
|
|
61
|
+
* identical spelling and this returns null immediately, before
|
|
62
|
+
* refuseTrustBaseRef's own checks -- HEAD, and the equal-tree exception from
|
|
63
|
+
* issue #69/#73 -- ever run: this check is narrower than those and says
|
|
64
|
+
* nothing about HEAD or about tree equality, only about whether the given ref
|
|
65
|
+
* agrees with the one Actions says this run must use. A ref naming the pull
|
|
66
|
+
* request's own branch, or anything else that disagrees, is refused with both
|
|
67
|
+
* refs and both commits named.
|
|
68
|
+
*
|
|
69
|
+
* FAILS CLOSED when origin/<githubBaseRef> itself does not resolve, naming
|
|
70
|
+
* it: reachable on the default actions/checkout (fetch-depth: 1), which does
|
|
71
|
+
* not carry the base branch at all. The README already asks for
|
|
72
|
+
* fetch-depth: 0, and a checkout that does not carry the base branch is not a
|
|
73
|
+
* reason to skip the comparison.
|
|
74
|
+
*
|
|
75
|
+
* When the GIVEN ref does not resolve at all, this returns null rather than
|
|
76
|
+
* refusing: refuseTrustBaseRef is the function with its own sentence for an
|
|
77
|
+
* unresolvable ref, and repeating it here under a second name would only
|
|
78
|
+
* confuse which check actually fired.
|
|
79
|
+
*
|
|
80
|
+
* A no-op -- always null -- when githubBaseRef is undefined or empty, which
|
|
81
|
+
* is every push, schedule, workflow_dispatch, merge_group and local run.
|
|
82
|
+
*/
|
|
83
|
+
export declare function refuseTrustBaseForPullRequest(repoRoot: string, ref: string, githubBaseRef: string | undefined): string | null;
|
|
16
84
|
/**
|
|
17
85
|
* The policy file's contents at a ref, or null when that ref carries none.
|
|
18
86
|
*
|
package/dist/trust-base.js
CHANGED
|
@@ -40,6 +40,30 @@
|
|
|
40
40
|
// on a pull_request event `github.sha` IS the merge commit, and what
|
|
41
41
|
// GitHub publishes as the merge ref carries the head branch's tree
|
|
42
42
|
// whenever the base has not moved since the fork.
|
|
43
|
+
//
|
|
44
|
+
// ONE NARROW EXCEPTION to the tree rule, added for issue #69. When a pull
|
|
45
|
+
// request's net diff is empty -- a value committed and then backed out in
|
|
46
|
+
// the same pull request -- the merge ref GitHub builds has a tree
|
|
47
|
+
// byte-identical to the base's, and the refusal above would stop
|
|
48
|
+
// secrets-history (gitleaks) from running on exactly the shape it exists
|
|
49
|
+
// to catch: the value is gone from the tree but still in the history
|
|
50
|
+
// between the base and HEAD. The discriminator is FIRST-PARENT IDENTITY,
|
|
51
|
+
// not ancestry: GitHub always builds the merge ref with the base branch as
|
|
52
|
+
// the first parent and the pull request's own head as the second, so a
|
|
53
|
+
// trust base that resolves to HEAD's first parent is the base the merge
|
|
54
|
+
// ref was actually built from, while HEAD's second parent is the pull
|
|
55
|
+
// request's own branch -- also an ancestor of HEAD, also carrying the
|
|
56
|
+
// same tree, and exactly the ref this rule must keep refusing, because
|
|
57
|
+
// trusting it would put the policy back inside the tree being judged. An
|
|
58
|
+
// ancestry check cannot tell those two apart; first-parent identity can.
|
|
59
|
+
// The exception applies ONLY when HEAD has two or more parents (a real
|
|
60
|
+
// merge commit) and the ref resolves to the first one; every other
|
|
61
|
+
// equal-tree shape -- a non-merge HEAD, the second parent, any other
|
|
62
|
+
// ancestor -- keeps refusing exactly as before. And the exception does not
|
|
63
|
+
// change what a tree-reading gate is told: it changes only whether the
|
|
64
|
+
// RUN proceeds, so the caller can still learn the trees matched
|
|
65
|
+
// (`headTreeEqualsBase` below) and run only the gates whose input is
|
|
66
|
+
// history rather than the tree.
|
|
43
67
|
import { spawnSync } from 'node:child_process';
|
|
44
68
|
import { realpathSync } from 'node:fs';
|
|
45
69
|
import path from 'node:path';
|
|
@@ -63,6 +87,47 @@ function resolveRev(repoRoot, rev, kind) {
|
|
|
63
87
|
const value = (child.stdout ?? '').trim();
|
|
64
88
|
return value === '' ? null : value;
|
|
65
89
|
}
|
|
90
|
+
/**
|
|
91
|
+
* HEAD's own parent commits, in order, or an empty list when they cannot be
|
|
92
|
+
* read.
|
|
93
|
+
*
|
|
94
|
+
* `git rev-list --parents -n 1 HEAD` prints one line, HEAD's own sha
|
|
95
|
+
* followed by each parent's, in order. The first entry is dropped here so
|
|
96
|
+
* this returns parents only: for an ordinary commit that is one entry, for a
|
|
97
|
+
* merge commit two or more, and GitHub's merge ref always puts the base
|
|
98
|
+
* branch first and the pull request's own head second.
|
|
99
|
+
*/
|
|
100
|
+
function headParents(repoRoot) {
|
|
101
|
+
const child = spawnSync('git', ['rev-list', '--parents', '-n', '1', 'HEAD'], {
|
|
102
|
+
cwd: repoRoot,
|
|
103
|
+
encoding: 'utf8',
|
|
104
|
+
});
|
|
105
|
+
if (child.error !== undefined || child.status !== 0) {
|
|
106
|
+
return [];
|
|
107
|
+
}
|
|
108
|
+
const line = (child.stdout ?? '').trim();
|
|
109
|
+
if (line === '') {
|
|
110
|
+
return [];
|
|
111
|
+
}
|
|
112
|
+
return line.split(/\s+/).slice(1);
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Whether HEAD's tree is byte-identical to the trust base's tree.
|
|
116
|
+
*
|
|
117
|
+
* Exported separately from `refuseTrustBaseRef` rather than folded into its
|
|
118
|
+
* return value, so that function's return type stays the simple `string |
|
|
119
|
+
* null` every other caller and test already reads. The one caller that needs
|
|
120
|
+
* this fact (`policyForRun` in cli.ts) calls it AFTER the refusal check has
|
|
121
|
+
* already passed, on the one shape that is accepted despite an identical
|
|
122
|
+
* tree: a merge commit whose first parent is the base. In that shape every
|
|
123
|
+
* tree-reading gate still has nothing to judge, and the caller uses this to
|
|
124
|
+
* decide which gates run.
|
|
125
|
+
*/
|
|
126
|
+
export function headTreeEqualsBase(repoRoot, ref) {
|
|
127
|
+
const baseTree = resolveRev(repoRoot, ref, 'tree');
|
|
128
|
+
const headTree = resolveRev(repoRoot, 'HEAD', 'tree');
|
|
129
|
+
return baseTree !== null && headTree !== null && baseTree === headTree;
|
|
130
|
+
}
|
|
66
131
|
/**
|
|
67
132
|
* Why this ref cannot be a trust base, or null when it can.
|
|
68
133
|
*
|
|
@@ -76,6 +141,13 @@ function resolveRev(repoRoot, rev, kind) {
|
|
|
76
141
|
* the umbrella never spawns a child at all on a base it has already decided
|
|
77
142
|
* it cannot judge against, and it means the two gates give a user the same
|
|
78
143
|
* answer to the same mistake.
|
|
144
|
+
*
|
|
145
|
+
* The identical-tree refusal carries ONE exception (issue #69): when HEAD is
|
|
146
|
+
* a merge commit and this ref is HEAD's first parent, this returns null
|
|
147
|
+
* rather than refusing, because that is precisely the shape GitHub's own
|
|
148
|
+
* merge ref takes on a pull request whose net diff is empty. See the header
|
|
149
|
+
* comment above and `headTreeEqualsBase` below, which is how the caller
|
|
150
|
+
* learns the trees matched even on this accepted path.
|
|
79
151
|
*/
|
|
80
152
|
export function refuseTrustBaseRef(repoRoot, ref) {
|
|
81
153
|
const base = resolveRev(repoRoot, ref, 'commit');
|
|
@@ -100,6 +172,16 @@ export function refuseTrustBaseRef(repoRoot, ref) {
|
|
|
100
172
|
const baseTree = resolveRev(repoRoot, ref, 'tree');
|
|
101
173
|
const headTree = resolveRev(repoRoot, 'HEAD', 'tree');
|
|
102
174
|
if (baseTree !== null && headTree !== null && baseTree === headTree) {
|
|
175
|
+
// THE ONE EXCEPTION: HEAD is a real merge commit (two or more parents)
|
|
176
|
+
// and this ref resolves to HEAD's FIRST parent, which is the base
|
|
177
|
+
// GitHub's merge ref was actually built from. Checked by identity against
|
|
178
|
+
// `base` above, never by ancestry: HEAD's SECOND parent -- the pull
|
|
179
|
+
// request's own branch -- is an ancestor too and carries the same tree,
|
|
180
|
+
// and trusting it would be exactly the hole this rule closes.
|
|
181
|
+
const parents = headParents(repoRoot);
|
|
182
|
+
if (parents.length >= 2 && parents[0] === base) {
|
|
183
|
+
return null;
|
|
184
|
+
}
|
|
103
185
|
return (`refusing "${ref}" as the trust base: it is a different commit from HEAD but carries an ` +
|
|
104
186
|
`identical tree (${headTree}), so the policy would come from the tree being judged and ` +
|
|
105
187
|
'there would be nothing for pull-request mode to compare. A pull request merge ref looks ' +
|
|
@@ -108,6 +190,76 @@ export function refuseTrustBaseRef(repoRoot, ref) {
|
|
|
108
190
|
}
|
|
109
191
|
return null;
|
|
110
192
|
}
|
|
193
|
+
/**
|
|
194
|
+
* Why an explicit --trust-base cannot be honoured on a pull request, or null.
|
|
195
|
+
*
|
|
196
|
+
* Issue #58. The refusal above only refuses a ref that resolves to HEAD's own
|
|
197
|
+
* commit or to HEAD's own tree, which covers HEAD itself and an UNMOVED
|
|
198
|
+
* origin/<pr-branch>. Once the base branch has moved, origin/<pr-branch> no
|
|
199
|
+
* longer matches either test, so a same-repo pull request could set
|
|
200
|
+
* trust-base to its own branch, in its own workflow file, and have this
|
|
201
|
+
* package read .guardrails.yaml from the pull request after all -- at which
|
|
202
|
+
* point the pull request controls the whole policy, which is the one thing
|
|
203
|
+
* pull-request mode exists to prevent.
|
|
204
|
+
*
|
|
205
|
+
* action.yml's validate step now refuses an explicit trust-base input
|
|
206
|
+
* outright on a pull_request or pull_request_target event, the stronger line
|
|
207
|
+
* dep-guard's own base input took in 0.8.0. This function is the CLI's own
|
|
208
|
+
* line of defence for anyone invoking it directly in CI, bypassing that step.
|
|
209
|
+
*
|
|
210
|
+
* GITHUB_BASE_REF IS ACTIONS' OWN PULL-REQUEST SIGNAL: the base branch's
|
|
211
|
+
* NAME on a pull_request or pull_request_target event, and empty everywhere
|
|
212
|
+
* else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
|
|
213
|
+
* a platform that never sets it. When it is set, the given ref is accepted
|
|
214
|
+
* only when it resolves to the SAME COMMIT as origin/<githubBaseRef>, which
|
|
215
|
+
* is exactly what the composite action itself always passes
|
|
216
|
+
* (`--trust-base "origin/$GITHUB_BASE_REF"` in action.yml's gates step). So
|
|
217
|
+
* an ordinary pull-request run sees the given ref and the expected ref as the
|
|
218
|
+
* identical spelling and this returns null immediately, before
|
|
219
|
+
* refuseTrustBaseRef's own checks -- HEAD, and the equal-tree exception from
|
|
220
|
+
* issue #69/#73 -- ever run: this check is narrower than those and says
|
|
221
|
+
* nothing about HEAD or about tree equality, only about whether the given ref
|
|
222
|
+
* agrees with the one Actions says this run must use. A ref naming the pull
|
|
223
|
+
* request's own branch, or anything else that disagrees, is refused with both
|
|
224
|
+
* refs and both commits named.
|
|
225
|
+
*
|
|
226
|
+
* FAILS CLOSED when origin/<githubBaseRef> itself does not resolve, naming
|
|
227
|
+
* it: reachable on the default actions/checkout (fetch-depth: 1), which does
|
|
228
|
+
* not carry the base branch at all. The README already asks for
|
|
229
|
+
* fetch-depth: 0, and a checkout that does not carry the base branch is not a
|
|
230
|
+
* reason to skip the comparison.
|
|
231
|
+
*
|
|
232
|
+
* When the GIVEN ref does not resolve at all, this returns null rather than
|
|
233
|
+
* refusing: refuseTrustBaseRef is the function with its own sentence for an
|
|
234
|
+
* unresolvable ref, and repeating it here under a second name would only
|
|
235
|
+
* confuse which check actually fired.
|
|
236
|
+
*
|
|
237
|
+
* A no-op -- always null -- when githubBaseRef is undefined or empty, which
|
|
238
|
+
* is every push, schedule, workflow_dispatch, merge_group and local run.
|
|
239
|
+
*/
|
|
240
|
+
export function refuseTrustBaseForPullRequest(repoRoot, ref, githubBaseRef) {
|
|
241
|
+
if (githubBaseRef === undefined || githubBaseRef === '') {
|
|
242
|
+
return null;
|
|
243
|
+
}
|
|
244
|
+
const expectedRef = `origin/${githubBaseRef}`;
|
|
245
|
+
const expectedCommit = resolveRev(repoRoot, expectedRef, 'commit');
|
|
246
|
+
if (expectedCommit === null) {
|
|
247
|
+
return (`cannot verify "${ref}" as the trust base: "${expectedRef}" does not resolve to a commit ` +
|
|
248
|
+
'in this repository, so there is nothing to compare it against. Nothing was checked. In ' +
|
|
249
|
+
'CI, fetch the base branch (actions/checkout with fetch-depth: 0) before running the gates.');
|
|
250
|
+
}
|
|
251
|
+
const givenCommit = resolveRev(repoRoot, ref, 'commit');
|
|
252
|
+
if (givenCommit === null) {
|
|
253
|
+
return null;
|
|
254
|
+
}
|
|
255
|
+
if (givenCommit === expectedCommit) {
|
|
256
|
+
return null;
|
|
257
|
+
}
|
|
258
|
+
return (`refusing "${ref}" as the trust base: GITHUB_BASE_REF is set to "${githubBaseRef}", so this ` +
|
|
259
|
+
'run is a pull request, and on a pull request the trust base must be the base branch and ' +
|
|
260
|
+
`nothing else. "${ref}" resolves to ${givenCommit}, and "${expectedRef}" resolves to ` +
|
|
261
|
+
`${expectedCommit}, a different commit. Pass ${expectedRef} instead. Nothing was checked.`);
|
|
262
|
+
}
|
|
111
263
|
/**
|
|
112
264
|
* The policy file's contents at a ref, or null when that ref carries none.
|
|
113
265
|
*
|