@vaultcompass/conductor 0.7.0 → 0.8.1
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 +223 -78
- package/dist/cli.js +204 -37
- package/dist/external-config.d.ts +2 -1
- package/dist/external-config.js +34 -13
- package/dist/gate-runner.d.ts +128 -17
- package/dist/gate-runner.js +365 -53
- package/dist/git.d.ts +80 -0
- package/dist/git.js +224 -0
- package/dist/init-policy.js +2 -1
- package/dist/init.js +40 -3
- package/dist/intent-base.d.ts +64 -1
- package/dist/intent-base.js +194 -40
- package/dist/intent-prepare.d.ts +33 -2
- package/dist/intent-prepare.js +448 -35
- package/dist/intent-spec.d.ts +28 -0
- package/dist/intent-spec.js +22 -5
- package/dist/normalize.d.ts +9 -0
- package/dist/normalize.js +19 -5
- package/dist/output-sarif.js +12 -13
- package/dist/output-text.d.ts +52 -2
- package/dist/output-text.js +150 -16
- package/dist/policy.js +9 -7
- package/dist/products.js +1 -1
- package/dist/resolve.d.ts +1 -0
- package/dist/resolve.js +1 -1
- package/dist/run.d.ts +8 -0
- package/dist/run.js +63 -13
- package/dist/trust-base.d.ts +133 -24
- package/dist/trust-base.js +353 -60
- package/package.json +1 -1
package/dist/intent-spec.js
CHANGED
|
@@ -154,7 +154,7 @@ function exists(repoRoot, relative) {
|
|
|
154
154
|
* the failure actually had: "superpowers" beat
|
|
155
155
|
* "1.2.1-base-and-superpowers" by being shorter and vaguer.
|
|
156
156
|
*/
|
|
157
|
-
function bestMatch(names, target) {
|
|
157
|
+
export function bestMatch(names, target) {
|
|
158
158
|
return names
|
|
159
159
|
.filter((name) => stemMatches(normalizeStem(name), target))
|
|
160
160
|
.sort((a, b) => {
|
|
@@ -192,7 +192,18 @@ function planFor(repoRoot, specPath) {
|
|
|
192
192
|
const specStem = normalizeStem(path.basename(specPath));
|
|
193
193
|
const matches = markdownFilesIn(repoRoot, PLAN_DIR).filter((name) => normalizeStem(name) === specStem);
|
|
194
194
|
const newest = matches[matches.length - 1];
|
|
195
|
-
|
|
195
|
+
if (newest === undefined) {
|
|
196
|
+
return { plan: null };
|
|
197
|
+
}
|
|
198
|
+
const plan = `${PLAN_DIR}/${newest}`;
|
|
199
|
+
// Held to the repository like the convention spec: a plans directory
|
|
200
|
+
// linked out of the checkout is refused, never read and never dropped.
|
|
201
|
+
return resolvesInsideRoot(repoRoot, plan) ? { plan } : { escaped: plan };
|
|
202
|
+
}
|
|
203
|
+
/** A found spec with its plan, or the refusal for a plan that escapes. */
|
|
204
|
+
function withPlan(repoRoot, kind, spec) {
|
|
205
|
+
const found = planFor(repoRoot, spec);
|
|
206
|
+
return 'escaped' in found ? { kind: 'escaped', path: found.escaped } : { kind, spec, plan: found.plan };
|
|
196
207
|
}
|
|
197
208
|
/** Normalizes a user-supplied path to a repository-relative one. */
|
|
198
209
|
function relativeToRoot(repoRoot, candidate) {
|
|
@@ -253,7 +264,7 @@ export function discoverSpec(options) {
|
|
|
253
264
|
if (!exists(repoRoot, relative)) {
|
|
254
265
|
return { kind: 'missing-flag', spec: relative };
|
|
255
266
|
}
|
|
256
|
-
return
|
|
267
|
+
return withPlan(repoRoot, 'flag', relative);
|
|
257
268
|
}
|
|
258
269
|
if (options.prBody !== undefined) {
|
|
259
270
|
const named = specFromPrBody(options.prBody);
|
|
@@ -274,7 +285,7 @@ export function discoverSpec(options) {
|
|
|
274
285
|
// Containment subsumes existence here, since a path that does not
|
|
275
286
|
// resolve is not contained.
|
|
276
287
|
if (resolvesInsideRoot(repoRoot, relative)) {
|
|
277
|
-
return
|
|
288
|
+
return withPlan(repoRoot, 'pr-body', relative);
|
|
278
289
|
}
|
|
279
290
|
}
|
|
280
291
|
}
|
|
@@ -282,7 +293,13 @@ export function discoverSpec(options) {
|
|
|
282
293
|
const best = bestMatch(markdownFilesIn(repoRoot, SPEC_DIR), branchSlug(options.branch));
|
|
283
294
|
if (best !== undefined) {
|
|
284
295
|
const relative = `${SPEC_DIR}/${best}`;
|
|
285
|
-
|
|
296
|
+
// The convention spec is held to the repository too: a specs directory
|
|
297
|
+
// linked out of the checkout is refused, never imported. Only --spec is
|
|
298
|
+
// exempt, as a path a person typed.
|
|
299
|
+
if (!resolvesInsideRoot(repoRoot, relative)) {
|
|
300
|
+
return { kind: 'escaped', path: relative };
|
|
301
|
+
}
|
|
302
|
+
return withPlan(repoRoot, 'convention', relative);
|
|
286
303
|
}
|
|
287
304
|
}
|
|
288
305
|
return { kind: 'none' };
|
package/dist/normalize.d.ts
CHANGED
|
@@ -54,6 +54,15 @@ roots?: readonly string[],
|
|
|
54
54
|
/** The lockfiles the umbrella passed with --lockfile, repository-relative. */
|
|
55
55
|
lockfiles?: readonly string[]): NormalizedGateOutput;
|
|
56
56
|
export type GateProblemRule = 'conductor/gate-missing' | 'conductor/gate-output-unparseable' | 'conductor/gate-failed';
|
|
57
|
+
/**
|
|
58
|
+
* What to install for a product, spelled so it cannot be mistaken for
|
|
59
|
+
* another package. The three npm gates are published under the
|
|
60
|
+
* @vaultcompass scope only: the unscoped dep-guard and intent-guard names are
|
|
61
|
+
* unclaimed on npm, so a reader (or an agent) told to install the bare name
|
|
62
|
+
* could install a squatted package. The external tools are not npm packages
|
|
63
|
+
* of this family and keep their own names.
|
|
64
|
+
*/
|
|
65
|
+
export declare function installName(product: Product): string;
|
|
57
66
|
/**
|
|
58
67
|
* The finding raised when an ENABLED gate's binary cannot be found.
|
|
59
68
|
*
|
package/dist/normalize.js
CHANGED
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
// own reported count says otherwise.
|
|
15
15
|
import { createHash } from 'node:crypto';
|
|
16
16
|
import { NormalizeError, atOrAboveThreshold, } from './envelope.js';
|
|
17
|
+
import { profileFor } from './products.js';
|
|
17
18
|
const BLOCKING_MISMATCH = 'conductor/blocking-count-mismatch';
|
|
18
19
|
const THRESHOLD_UNKNOWN = 'conductor/blocking-threshold-unknown';
|
|
19
20
|
function isRecord(value) {
|
|
@@ -336,10 +337,12 @@ export function normalizeVaultGuard(raw, version) {
|
|
|
336
337
|
run: {
|
|
337
338
|
failOn: threshold,
|
|
338
339
|
suppressed: typeof run.baseline_suppressed === 'number' ? run.baseline_suppressed : 0,
|
|
339
|
-
//
|
|
340
|
-
//
|
|
341
|
-
//
|
|
342
|
-
//
|
|
340
|
+
// This normalizer reads no ignore count out of vault-guard's run object
|
|
341
|
+
// (which does carry config_ignored_files; it is not mapped here), so 0
|
|
342
|
+
// is a placeholder and not a claim that nothing was ignored. What makes
|
|
343
|
+
// the report say "ignored not reported" is not this number: it is
|
|
344
|
+
// `ignoredReported: false` in `details` below, which output-text.ts and
|
|
345
|
+
// the summary line read in its place.
|
|
343
346
|
ignored: 0,
|
|
344
347
|
// vault-guard's diagnostics carry a context object rather than a
|
|
345
348
|
// message, so the context is rendered as one. Validated the same way
|
|
@@ -1045,6 +1048,17 @@ function gateProblem(ruleId, role, product, message, details) {
|
|
|
1045
1048
|
details: { role, product, ...details },
|
|
1046
1049
|
};
|
|
1047
1050
|
}
|
|
1051
|
+
/**
|
|
1052
|
+
* What to install for a product, spelled so it cannot be mistaken for
|
|
1053
|
+
* another package. The three npm gates are published under the
|
|
1054
|
+
* @vaultcompass scope only: the unscoped dep-guard and intent-guard names are
|
|
1055
|
+
* unclaimed on npm, so a reader (or an agent) told to install the bare name
|
|
1056
|
+
* could install a squatted package. The external tools are not npm packages
|
|
1057
|
+
* of this family and keep their own names.
|
|
1058
|
+
*/
|
|
1059
|
+
export function installName(product) {
|
|
1060
|
+
return profileFor(product).managed ? `@vaultcompass/${product}` : product;
|
|
1061
|
+
}
|
|
1048
1062
|
/**
|
|
1049
1063
|
* The finding raised when an ENABLED gate's binary cannot be found.
|
|
1050
1064
|
*
|
|
@@ -1066,7 +1080,7 @@ export function normalizeMissingGate(role, product, candidates,
|
|
|
1066
1080
|
*/
|
|
1067
1081
|
remedy = '') {
|
|
1068
1082
|
return gateProblem('conductor/gate-missing', role, product, `The "${role}" gate is enabled but no ${product} binary was found. ` +
|
|
1069
|
-
`Looked for: ${candidates.join(', ')}. Install
|
|
1083
|
+
`Looked for: ${candidates.join(', ')}. Install ${installName(product)}, point the gate at a build with an ` +
|
|
1070
1084
|
`absolute "command:", or set enabled: false to switch the gate off on purpose.${remedy}`, { candidates });
|
|
1071
1085
|
}
|
|
1072
1086
|
/**
|
package/dist/output-sarif.js
CHANGED
|
@@ -660,7 +660,9 @@ function trustBaseRefusedNotifications(result) {
|
|
|
660
660
|
{
|
|
661
661
|
id: 'conductor/trust-base-refused',
|
|
662
662
|
level: 'error',
|
|
663
|
-
message:
|
|
663
|
+
message: (result.trustBase?.notGiven === true
|
|
664
|
+
? 'this is a pull-request job and no trust base was given, so no rules were read, no gate ran and '
|
|
665
|
+
: `conductor refused the trust base "${result.trustBase?.ref ?? ''}", so no gate ran and `) +
|
|
664
666
|
`NOTHING WAS CHECKED by this run. ${refusal}`,
|
|
665
667
|
details: { ref: result.trustBase?.ref ?? null, reason: refusal },
|
|
666
668
|
},
|
|
@@ -703,17 +705,15 @@ function programRefusedNotifications(result) {
|
|
|
703
705
|
});
|
|
704
706
|
}
|
|
705
707
|
/**
|
|
706
|
-
* The gates the umbrella
|
|
708
|
+
* The gates the umbrella did not hand the trust base to.
|
|
707
709
|
*
|
|
708
710
|
* The loud half of the same mode, and by the discriminator below it is a
|
|
709
|
-
* close call that lands on notification: nothing went wrong with the run
|
|
710
|
-
*
|
|
711
|
-
*
|
|
712
|
-
*
|
|
713
|
-
*
|
|
714
|
-
*
|
|
715
|
-
* It is still the most important notification in the log. A gate here read
|
|
716
|
-
* its own control inputs out of the tree under judgment.
|
|
711
|
+
* close call that lands on notification: nothing went wrong with the run.
|
|
712
|
+
* What it says is how much of the pull-request boundary this run actually
|
|
713
|
+
* had, which is a coverage statement. A gate below its pull-request-mode
|
|
714
|
+
* minimum never lands here: it is could-not-run. What is left is an intent
|
|
715
|
+
* gate judging a contract imported for this run from the base, and a
|
|
716
|
+
* product with no pull-request mode at all (none today).
|
|
717
717
|
*/
|
|
718
718
|
function trustBaseWithheldNotifications(result) {
|
|
719
719
|
return result.gates.flatMap((gate) => {
|
|
@@ -724,9 +724,8 @@ function trustBaseWithheldNotifications(result) {
|
|
|
724
724
|
return [
|
|
725
725
|
{
|
|
726
726
|
id: 'conductor/trust-base-not-passed',
|
|
727
|
-
message: `The ${gate.role} gate (${gate.product}) did NOT run in pull-request mode
|
|
728
|
-
`
|
|
729
|
-
`${gate.trustBase?.ref ?? 'the base ref'}. ${withheld}`,
|
|
727
|
+
message: `The ${gate.role} gate (${gate.product}) did NOT run in pull-request mode: it was not ` +
|
|
728
|
+
`handed --trust-base ${gate.trustBase?.ref ?? 'the base ref'}. ${withheld}`,
|
|
730
729
|
details: {
|
|
731
730
|
role: gate.role,
|
|
732
731
|
product: gate.product,
|
package/dist/output-text.d.ts
CHANGED
|
@@ -1,4 +1,22 @@
|
|
|
1
1
|
import type { RunResult } from './run.js';
|
|
2
|
+
/**
|
|
3
|
+
* The one sentence the whole of pull-request mode has to fit into.
|
|
4
|
+
*
|
|
5
|
+
* Counted even at ZERO, by the family suppression rule: the number is the
|
|
6
|
+
* answer to "did this pull request also try to change the rules", and leaving
|
|
7
|
+
* it out when the answer is none makes a run in pull-request mode
|
|
8
|
+
* indistinguishable from a run that was never in it.
|
|
9
|
+
*
|
|
10
|
+
* NEVER A COUNT THAT TREATS A GATE THAT COULD NOT RUN AS ZERO. A gate that
|
|
11
|
+
* was put into pull-request mode and could not run reported no summary the
|
|
12
|
+
* umbrella reads, so its proposals are not known rather than none. The
|
|
13
|
+
* sentence then names those gates and counts only what the others proposed.
|
|
14
|
+
* On a run with a trust base that includes a gate that stopped before its
|
|
15
|
+
* pull-request mode was even decided (it carries no trustBase: a preparation
|
|
16
|
+
* that failed, a git older than the floor, a missing binary), because it was
|
|
17
|
+
* meant to run in that mode and reported nothing either.
|
|
18
|
+
*/
|
|
19
|
+
export declare function proposalCount(result: RunResult): string;
|
|
2
20
|
/**
|
|
3
21
|
* The one-line summary a `--output` run prints to the job log after writing
|
|
4
22
|
* its report to a file (see cli.ts). Refused first, exactly like every other
|
|
@@ -25,12 +43,44 @@ import type { RunResult } from './run.js';
|
|
|
25
43
|
* not change.
|
|
26
44
|
*/
|
|
27
45
|
export declare function jobLogSummary(result: RunResult): string;
|
|
46
|
+
/**
|
|
47
|
+
* One plain line per gate, for the job log: which gate, which version, what
|
|
48
|
+
* happened, and the exit code. Written to stderr by cli.ts on EVERY run, so
|
|
49
|
+
* an adopter reading the log learns which gate did what without opening a
|
|
50
|
+
* report (the SARIF log, the text report file or the pull request comment).
|
|
51
|
+
*
|
|
52
|
+
* Outcomes, in the words the lines use: `ok`, `findings (N, M blocking)`,
|
|
53
|
+
* `could-not-run (reason)` with the gate's own stated reason when it gave
|
|
54
|
+
* one, or conductor's own reason when the refusal was conductor's (both
|
|
55
|
+
* cleaned, one line, capped and quoted), `missing (reason)` for a gate that
|
|
56
|
+
* was not found, and `skipped (why)`
|
|
57
|
+
* for a gate that was enabled and never spawned (deferred by stage, left out
|
|
58
|
+
* by --gate, no contract, tree unchanged). A gate with no process behind it
|
|
59
|
+
* says `no exit code`, never a made-up one.
|
|
60
|
+
*
|
|
61
|
+
* Describes, decides nothing: every word is read off the outcomes the exit
|
|
62
|
+
* code was already composed from. Same plain ASCII as the rest of this file.
|
|
63
|
+
*/
|
|
64
|
+
export declare function gateLogLines(result: RunResult): string[];
|
|
65
|
+
/**
|
|
66
|
+
* One warning per gate that was found on PATH at a version other than the one
|
|
67
|
+
* this run expected (the Action's pin).
|
|
68
|
+
*
|
|
69
|
+
* For the job log only: it names where the binary was found, and an absolute
|
|
70
|
+
* path has no business in a published SARIF log or a pull request comment, so
|
|
71
|
+
* this is never part of either report. A warning and nothing more. Resolution
|
|
72
|
+
* is unchanged and the gate ran (or was refused) exactly as it would have
|
|
73
|
+
* without it.
|
|
74
|
+
*/
|
|
75
|
+
export declare function versionSkewWarnings(result: RunResult): string[];
|
|
28
76
|
/**
|
|
29
77
|
* The verdict token: a label for the umbrella's OWN exit decision, in a
|
|
30
78
|
* closed set, so a person or a script reading a report or a job summary gets
|
|
31
79
|
* the state without parsing the verdict sentence.
|
|
32
80
|
*
|
|
33
81
|
* pass exit 0 and nothing was hidden by it
|
|
82
|
+
* nothing-checked exit 0, but no gate ran at all (none enabled,
|
|
83
|
+
* or every one deferred, tree-unchanged or skipped)
|
|
34
84
|
* advisory-blocked (N) exit 1 that --advisory turned into exit 0
|
|
35
85
|
* unenforced-findings (N) exit 0, but enforce: false gates blocked or
|
|
36
86
|
* could not run
|
|
@@ -51,8 +101,8 @@ export declare function jobLogSummary(result: RunResult): string;
|
|
|
51
101
|
*
|
|
52
102
|
* A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
|
|
53
103
|
* than result.gates, is neither a blocking finding nor a could-not-run, and
|
|
54
|
-
* so does not by itself move the token off pass
|
|
55
|
-
*
|
|
104
|
+
* so does not by itself move the token off pass when another gate ran. When
|
|
105
|
+
* NO gate ran, the token is nothing-checked, matching the verdict sentence.
|
|
56
106
|
*
|
|
57
107
|
* Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
|
|
58
108
|
* not a pass.
|
package/dist/output-text.js
CHANGED
|
@@ -23,6 +23,7 @@
|
|
|
23
23
|
// everywhere is worth more here than a nicer-looking terminal.
|
|
24
24
|
import { compareFindings } from './envelope.js';
|
|
25
25
|
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN } from './exit-codes.js';
|
|
26
|
+
import { CONDUCTOR_OWN_REASONS, cleanOutputLine, conductorStatedReason, } from './gate-runner.js';
|
|
26
27
|
import { isLegacyContractPath } from './intent-prepare.js';
|
|
27
28
|
function subjectLabel(finding) {
|
|
28
29
|
const subject = finding.subject;
|
|
@@ -112,12 +113,18 @@ function gateSection(gate) {
|
|
|
112
113
|
const contract = contractLine(gate);
|
|
113
114
|
if (contract !== null) {
|
|
114
115
|
lines.push(contract);
|
|
116
|
+
if (gate.intent?.note !== undefined) {
|
|
117
|
+
lines.push(` note: ${gate.intent.note}`);
|
|
118
|
+
}
|
|
115
119
|
}
|
|
116
120
|
if (gate.couldNotRun !== null) {
|
|
117
121
|
lines.push(` ${gate.couldNotRun.detail}`);
|
|
122
|
+
if (gate.couldNotRun.gateSaid !== undefined) {
|
|
123
|
+
lines.push(` gate said: "${gate.couldNotRun.gateSaid}"`);
|
|
124
|
+
}
|
|
118
125
|
if (gate.stderr.trim().length > 0) {
|
|
119
126
|
for (const line of gate.stderr.trim().split('\n')) {
|
|
120
|
-
lines.push(` | ${line}`);
|
|
127
|
+
lines.push(` | ${cleanOutputLine(line)}`);
|
|
121
128
|
}
|
|
122
129
|
}
|
|
123
130
|
}
|
|
@@ -237,19 +244,39 @@ function treeUnchangedLines(result) {
|
|
|
237
244
|
* answer to "did this pull request also try to change the rules", and leaving
|
|
238
245
|
* it out when the answer is none makes a run in pull-request mode
|
|
239
246
|
* indistinguishable from a run that was never in it.
|
|
247
|
+
*
|
|
248
|
+
* NEVER A COUNT THAT TREATS A GATE THAT COULD NOT RUN AS ZERO. A gate that
|
|
249
|
+
* was put into pull-request mode and could not run reported no summary the
|
|
250
|
+
* umbrella reads, so its proposals are not known rather than none. The
|
|
251
|
+
* sentence then names those gates and counts only what the others proposed.
|
|
252
|
+
* On a run with a trust base that includes a gate that stopped before its
|
|
253
|
+
* pull-request mode was even decided (it carries no trustBase: a preparation
|
|
254
|
+
* that failed, a git older than the floor, a missing binary), because it was
|
|
255
|
+
* meant to run in that mode and reported nothing either.
|
|
240
256
|
*/
|
|
241
|
-
function proposalCount(result) {
|
|
242
|
-
|
|
257
|
+
export function proposalCount(result) {
|
|
258
|
+
const unknown = result.gates.filter((gate) => gate.couldNotRun !== null &&
|
|
259
|
+
(gate.trustBase === undefined
|
|
260
|
+
? result.trustBase !== null
|
|
261
|
+
: gate.trustBase.withheld === null && gate.trustBase.refused === null));
|
|
262
|
+
if (unknown.length === 0) {
|
|
263
|
+
return `${result.proposals.length} control change(s) proposed in this pull request`;
|
|
264
|
+
}
|
|
265
|
+
const names = unknown.map((gate) => `${gate.role} (${gate.product})`).join(', ');
|
|
266
|
+
return (`${result.proposals.length} control change(s) proposed by the gates that ran; ` +
|
|
267
|
+
`${names} could not run, so the proposals of ${unknown.length === 1 ? 'that gate are' : 'those gates are'} not known`);
|
|
243
268
|
}
|
|
244
269
|
/**
|
|
245
|
-
* The gates the umbrella
|
|
270
|
+
* The gates the umbrella did not hand the trust base to.
|
|
246
271
|
*
|
|
247
|
-
* This is the loud half and it must never be silent
|
|
248
|
-
*
|
|
249
|
-
*
|
|
250
|
-
*
|
|
251
|
-
*
|
|
252
|
-
*
|
|
272
|
+
* This is the loud half and it must never be silent: a run where one gate was
|
|
273
|
+
* not handed the base ref must not read like a run where every gate was. A
|
|
274
|
+
* gate below its pull-request-mode minimum is never here (it is
|
|
275
|
+
* could-not-run); what is left is an intent gate judging a contract imported
|
|
276
|
+
* from the base for this run, and a product with no pull-request mode at all.
|
|
277
|
+
* It is a statement about coverage rather than about anybody's code, so it is
|
|
278
|
+
* a line and a notification rather than a finding, and it never reaches the
|
|
279
|
+
* exit code.
|
|
253
280
|
*/
|
|
254
281
|
function withheldTrustBase(result) {
|
|
255
282
|
return result.gates.flatMap((gate) => {
|
|
@@ -291,6 +318,9 @@ function trustBaseLines(result) {
|
|
|
291
318
|
if (result.trustBase === null) {
|
|
292
319
|
return [];
|
|
293
320
|
}
|
|
321
|
+
if (result.trustBase.notGiven === true) {
|
|
322
|
+
return [' pull-request mode: no trust base was given, so no rules were read.'];
|
|
323
|
+
}
|
|
294
324
|
const lines = [
|
|
295
325
|
` pull-request mode: rules from ${result.trustBase.ref}. ${proposalCount(result)}.`,
|
|
296
326
|
];
|
|
@@ -346,7 +376,9 @@ function refusalLines(result) {
|
|
|
346
376
|
return [];
|
|
347
377
|
}
|
|
348
378
|
return [
|
|
349
|
-
|
|
379
|
+
result.trustBase?.notGiven === true
|
|
380
|
+
? 'conductor: this is a pull-request job and no trust base was given, so no rules were read. Nothing was checked.'
|
|
381
|
+
: `conductor: refused the trust base "${result.trustBase?.ref ?? ''}". Nothing was checked.`,
|
|
350
382
|
` ${refusal}`,
|
|
351
383
|
];
|
|
352
384
|
}
|
|
@@ -378,10 +410,97 @@ function refusalLines(result) {
|
|
|
378
410
|
export function jobLogSummary(result) {
|
|
379
411
|
const refusal = result.trustBase?.refusal;
|
|
380
412
|
if (refusal !== undefined && refusal !== null) {
|
|
381
|
-
return
|
|
413
|
+
return result.trustBase?.notGiven === true
|
|
414
|
+
? `pull-request job with no trust base, no rules read: ${refusal.replace(/\.+\s*$/, '')}`
|
|
415
|
+
: `refused the trust base "${result.trustBase?.ref ?? ''}": ${refusal.replace(/\.+\s*$/, '')}`;
|
|
382
416
|
}
|
|
383
417
|
return `${result.gates.length} gate(s), ${result.findings.length} finding(s)`;
|
|
384
418
|
}
|
|
419
|
+
/**
|
|
420
|
+
* One plain line per gate, for the job log: which gate, which version, what
|
|
421
|
+
* happened, and the exit code. Written to stderr by cli.ts on EVERY run, so
|
|
422
|
+
* an adopter reading the log learns which gate did what without opening a
|
|
423
|
+
* report (the SARIF log, the text report file or the pull request comment).
|
|
424
|
+
*
|
|
425
|
+
* Outcomes, in the words the lines use: `ok`, `findings (N, M blocking)`,
|
|
426
|
+
* `could-not-run (reason)` with the gate's own stated reason when it gave
|
|
427
|
+
* one, or conductor's own reason when the refusal was conductor's (both
|
|
428
|
+
* cleaned, one line, capped and quoted), `missing (reason)` for a gate that
|
|
429
|
+
* was not found, and `skipped (why)`
|
|
430
|
+
* for a gate that was enabled and never spawned (deferred by stage, left out
|
|
431
|
+
* by --gate, no contract, tree unchanged). A gate with no process behind it
|
|
432
|
+
* says `no exit code`, never a made-up one.
|
|
433
|
+
*
|
|
434
|
+
* Describes, decides nothing: every word is read off the outcomes the exit
|
|
435
|
+
* code was already composed from. Same plain ASCII as the rest of this file.
|
|
436
|
+
*/
|
|
437
|
+
export function gateLogLines(result) {
|
|
438
|
+
const lines = [];
|
|
439
|
+
for (const gate of result.gates) {
|
|
440
|
+
const version = gate.productVersion === null ? 'version unknown' : gate.productVersion;
|
|
441
|
+
const exit = gate.exitCode === null ? 'no exit code' : `exit ${gate.exitCode}`;
|
|
442
|
+
let outcome;
|
|
443
|
+
if (gate.couldNotRun !== null) {
|
|
444
|
+
const reason = gate.couldNotRun.reason;
|
|
445
|
+
outcome =
|
|
446
|
+
reason === 'binary-missing' || reason === 'configured-command-missing'
|
|
447
|
+
? `missing (${reason})`
|
|
448
|
+
: `could-not-run (${reason})`;
|
|
449
|
+
}
|
|
450
|
+
else {
|
|
451
|
+
const total = gate.findings.length;
|
|
452
|
+
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
453
|
+
outcome =
|
|
454
|
+
total === 0 && (gate.exitCode ?? 0) === 0 ? 'ok' : `findings (${total}, ${blocking} blocking)`;
|
|
455
|
+
}
|
|
456
|
+
// conductor's own refusals (a git below the floor, a path list it cannot
|
|
457
|
+
// pass, a PATH or git-directory failure, a gate below its minimum) carry
|
|
458
|
+
// their reason the same way, since no gate said anything for them.
|
|
459
|
+
const conductorSaid = gate.couldNotRun !== null &&
|
|
460
|
+
gate.couldNotRun.gateSaid === undefined &&
|
|
461
|
+
CONDUCTOR_OWN_REASONS.has(gate.couldNotRun.reason)
|
|
462
|
+
? conductorStatedReason(gate.couldNotRun.detail)
|
|
463
|
+
: null;
|
|
464
|
+
lines.push(`conductor: gate ${gate.role} (${gate.product} ${version}): ${outcome}, ${exit}` +
|
|
465
|
+
(gate.enforce ? '' : ', not enforced') +
|
|
466
|
+
(gate.couldNotRun?.gateSaid === undefined ? '' : `, gate said: "${gate.couldNotRun.gateSaid}"`) +
|
|
467
|
+
(conductorSaid === null ? '' : `, conductor said: "${conductorSaid}"`));
|
|
468
|
+
}
|
|
469
|
+
const notRun = (role, product, why) => `conductor: gate ${role} (${product}): skipped (${why}), no exit code`;
|
|
470
|
+
for (const gate of result.deferred) {
|
|
471
|
+
lines.push(notRun(gate.role, gate.product, `deferred to stage ${gate.stage}`));
|
|
472
|
+
}
|
|
473
|
+
for (const gate of result.skipped) {
|
|
474
|
+
lines.push(notRun(gate.role, gate.product, skipWording(gate.reason).line));
|
|
475
|
+
}
|
|
476
|
+
for (const gate of result.excluded) {
|
|
477
|
+
lines.push(notRun(gate.role, gate.product, '--gate did not name it'));
|
|
478
|
+
}
|
|
479
|
+
for (const gate of result.treeUnchanged) {
|
|
480
|
+
lines.push(notRun(gate.role, gate.product, 'head tree equals the base tree'));
|
|
481
|
+
}
|
|
482
|
+
return lines;
|
|
483
|
+
}
|
|
484
|
+
/**
|
|
485
|
+
* One warning per gate that was found on PATH at a version other than the one
|
|
486
|
+
* this run expected (the Action's pin).
|
|
487
|
+
*
|
|
488
|
+
* For the job log only: it names where the binary was found, and an absolute
|
|
489
|
+
* path has no business in a published SARIF log or a pull request comment, so
|
|
490
|
+
* this is never part of either report. A warning and nothing more. Resolution
|
|
491
|
+
* is unchanged and the gate ran (or was refused) exactly as it would have
|
|
492
|
+
* without it.
|
|
493
|
+
*/
|
|
494
|
+
export function versionSkewWarnings(result) {
|
|
495
|
+
return result.gates.flatMap((gate) => gate.versionSkew === undefined
|
|
496
|
+
? []
|
|
497
|
+
: [
|
|
498
|
+
`conductor: warning: ${gate.product} resolved from PATH reports version ${gate.versionSkew.found}, ` +
|
|
499
|
+
`but this run expects ${gate.versionSkew.expected} (the version the action pinned). ` +
|
|
500
|
+
`It was found at ${gate.versionSkew.path}. Resolution is unchanged and that binary was used. ` +
|
|
501
|
+
`Fix: remove the other ${gate.product} from PATH, or install ${gate.versionSkew.expected}.`,
|
|
502
|
+
]);
|
|
503
|
+
}
|
|
385
504
|
/**
|
|
386
505
|
* How many blocking findings one gate that RAN is carrying, for the token.
|
|
387
506
|
*
|
|
@@ -405,6 +524,8 @@ function blockingCount(gate) {
|
|
|
405
524
|
* the state without parsing the verdict sentence.
|
|
406
525
|
*
|
|
407
526
|
* pass exit 0 and nothing was hidden by it
|
|
527
|
+
* nothing-checked exit 0, but no gate ran at all (none enabled,
|
|
528
|
+
* or every one deferred, tree-unchanged or skipped)
|
|
408
529
|
* advisory-blocked (N) exit 1 that --advisory turned into exit 0
|
|
409
530
|
* unenforced-findings (N) exit 0, but enforce: false gates blocked or
|
|
410
531
|
* could not run
|
|
@@ -425,8 +546,8 @@ function blockingCount(gate) {
|
|
|
425
546
|
*
|
|
426
547
|
* A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
|
|
427
548
|
* than result.gates, is neither a blocking finding nor a could-not-run, and
|
|
428
|
-
* so does not by itself move the token off pass
|
|
429
|
-
*
|
|
549
|
+
* so does not by itself move the token off pass when another gate ran. When
|
|
550
|
+
* NO gate ran, the token is nothing-checked, matching the verdict sentence.
|
|
430
551
|
*
|
|
431
552
|
* Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
|
|
432
553
|
* not a pass.
|
|
@@ -443,6 +564,13 @@ export function verdictToken(result, advisory) {
|
|
|
443
564
|
.reduce((total, gate) => total + blockingCount(gate), 0);
|
|
444
565
|
return advisory ? `advisory-blocked (${count})` : `blocked (${count})`;
|
|
445
566
|
}
|
|
567
|
+
// Exit 0 with no gate having run at all (none enabled, every one deferred,
|
|
568
|
+
// tree-unchanged or skipped): the exit code stays 0, since nothing failed,
|
|
569
|
+
// but the label must not say pass. It is the same condition the verdict
|
|
570
|
+
// sentence words as "nothing was checked".
|
|
571
|
+
if (result.gates.length === 0) {
|
|
572
|
+
return 'nothing-checked';
|
|
573
|
+
}
|
|
446
574
|
const unenforced = result.gates
|
|
447
575
|
.filter((gate) => !gate.enforce)
|
|
448
576
|
.reduce((total, gate) => total + (gate.couldNotRun !== null ? 1 : blockingCount(gate)), 0);
|
|
@@ -456,8 +584,11 @@ function verdict(result, advisory) {
|
|
|
456
584
|
// them would describe a different run from the one that happened. A
|
|
457
585
|
// refusal is a could-not-run outcome (exit 2), which --advisory never
|
|
458
586
|
// touches, so this branch reads advisory or not exactly the same.
|
|
459
|
-
return
|
|
460
|
-
'
|
|
587
|
+
return result.trustBase?.notGiven === true
|
|
588
|
+
? 'verdict: exit 2, this is a pull-request job and no trust base was given, so no rules ' +
|
|
589
|
+
'were read, no gate ran and nothing here is a result of any kind.'
|
|
590
|
+
: `verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
|
|
591
|
+
'so no gate ran and nothing here is a result of any kind.';
|
|
461
592
|
}
|
|
462
593
|
return verdictForRun(result, advisory);
|
|
463
594
|
}
|
|
@@ -614,6 +745,9 @@ function isFullyClean(result) {
|
|
|
614
745
|
return result.gates.every((gate) => gate.couldNotRun === null &&
|
|
615
746
|
(gate.exitCode ?? 0) === 0 &&
|
|
616
747
|
gate.diagnostics.length === 0 &&
|
|
748
|
+
// A note about an input this run did not use is never folded into the
|
|
749
|
+
// one-line summary, where nobody would see it.
|
|
750
|
+
gate.intent?.note === undefined &&
|
|
617
751
|
!gate.findings.some((finding) => finding.blocking));
|
|
618
752
|
}
|
|
619
753
|
/**
|
package/dist/policy.js
CHANGED
|
@@ -195,13 +195,15 @@ function describeErrors(errors, source) {
|
|
|
195
195
|
* Why one reserved key is reserved.
|
|
196
196
|
*
|
|
197
197
|
* The general sentence, at the bottom, is that the umbrella writes that exact
|
|
198
|
-
* flag itself, and it is true of most of these keys.
|
|
199
|
-
*
|
|
200
|
-
*
|
|
201
|
-
* the
|
|
202
|
-
*
|
|
203
|
-
*
|
|
204
|
-
*
|
|
198
|
+
* flag itself, and it is true of most of these keys. Two keys are reserved
|
|
199
|
+
* although the umbrella writes no such flag, and that is what
|
|
200
|
+
* policy.test.ts pins: format on vault-guard, and base on intent-guard. The
|
|
201
|
+
* test derives the flags gateArgs actually writes and holds that
|
|
202
|
+
* reserved-without-writing list to exactly those two, so another one cannot
|
|
203
|
+
* be added without saying why. trust-base, and base on dep-guard, get their
|
|
204
|
+
* own messages as well, because the umbrella writes those flags only on some
|
|
205
|
+
* runs and the general sentence would send somebody looking for a flag that
|
|
206
|
+
* is not on the command line of the run they are debugging.
|
|
205
207
|
*/
|
|
206
208
|
function reservedReason(product, key) {
|
|
207
209
|
if (key === 'trust-base') {
|
package/dist/products.js
CHANGED
|
@@ -39,7 +39,7 @@ function managedRemedy(product) {
|
|
|
39
39
|
? `Install the gate outside the tree with npm install -g @vaultcompass/${product}. The ` +
|
|
40
40
|
`conductor Action does exactly that, at the version its ${product}-version input pins, and ` +
|
|
41
41
|
'that pin lives in the workflow file on the base branch.'
|
|
42
|
-
: `
|
|
42
|
+
: `The package is @vaultcompass/${product}, never the unscoped name: install it with npm install -g @vaultcompass/${product}, or add @vaultcompass/${product} to the repository's devDependencies.`;
|
|
43
43
|
}
|
|
44
44
|
function managedProfile(product) {
|
|
45
45
|
return {
|
package/dist/resolve.d.ts
CHANGED
|
@@ -55,6 +55,7 @@ export interface ResolveOptions {
|
|
|
55
55
|
export declare class ResolveError extends Error {
|
|
56
56
|
constructor(message: string);
|
|
57
57
|
}
|
|
58
|
+
export declare function findOnPath(name: string, pathValue: string): string | null;
|
|
58
59
|
/**
|
|
59
60
|
* The node_modules/.bin candidate a pull-request run declined to take.
|
|
60
61
|
*
|
package/dist/resolve.js
CHANGED
|
@@ -106,7 +106,7 @@ function existsAsFile(candidate) {
|
|
|
106
106
|
return false;
|
|
107
107
|
}
|
|
108
108
|
}
|
|
109
|
-
function findOnPath(name, pathValue) {
|
|
109
|
+
export function findOnPath(name, pathValue) {
|
|
110
110
|
for (const dir of pathValue.split(path.delimiter)) {
|
|
111
111
|
if (dir.length === 0) {
|
|
112
112
|
continue;
|
package/dist/run.d.ts
CHANGED
|
@@ -137,6 +137,13 @@ export interface RunTrustBase {
|
|
|
137
137
|
* instead of being spawned.
|
|
138
138
|
*/
|
|
139
139
|
treeUnchanged?: boolean;
|
|
140
|
+
/**
|
|
141
|
+
* True on the refusal for a pull-request job that gave no trust base at
|
|
142
|
+
* all (GITHUB_ACTIONS and GITHUB_BASE_REF set, no --trust-base). `ref` is
|
|
143
|
+
* then empty, and the reports say no trust base was given and no rules
|
|
144
|
+
* were read, rather than naming a ref.
|
|
145
|
+
*/
|
|
146
|
+
notGiven?: boolean;
|
|
140
147
|
}
|
|
141
148
|
export interface RunResult {
|
|
142
149
|
schemaVersion: 1;
|
|
@@ -242,5 +249,6 @@ export interface RunOptions {
|
|
|
242
249
|
export declare function refusedTrustBase(policy: Policy, ref: string, detail: string, options: {
|
|
243
250
|
stage?: GateStage;
|
|
244
251
|
now?: () => Date;
|
|
252
|
+
notGiven?: boolean;
|
|
245
253
|
}): RunResult;
|
|
246
254
|
export declare function runAll(policy: Policy, options: RunOptions): RunResult;
|