@vaultcompass/conductor 0.6.0 → 0.8.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 +200 -48
- package/dist/cli.js +96 -16
- package/dist/external-config.js +7 -1
- package/dist/gate-runner.d.ts +9 -1
- package/dist/gate-runner.js +49 -5
- package/dist/init-policy.js +2 -1
- package/dist/intent-base.d.ts +29 -0
- package/dist/intent-base.js +96 -2
- package/dist/intent-prepare.js +6 -2
- package/dist/normalize.d.ts +9 -0
- package/dist/normalize.js +13 -1
- package/dist/output-text.d.ts +35 -0
- package/dist/output-text.js +89 -2
- package/dist/products.js +1 -1
- package/dist/trust-base.d.ts +57 -10
- package/dist/trust-base.js +194 -18
- package/package.json +1 -1
package/dist/gate-runner.d.ts
CHANGED
|
@@ -36,7 +36,15 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
|
|
|
36
36
|
* verdict to is not there. Only a tool whose output is a report file can
|
|
37
37
|
* land here.
|
|
38
38
|
*/
|
|
39
|
-
| 'report-missing'
|
|
39
|
+
| 'report-missing'
|
|
40
|
+
/**
|
|
41
|
+
* The gate reads git history and the checkout is shallow, so the history it
|
|
42
|
+
* would read is truncated (at depth 1 the pull request's merge commit is
|
|
43
|
+
* grafted, and base..HEAD holds one commit: a secret added and removed
|
|
44
|
+
* inside the pull request is never seen). Never unshallowed automatically:
|
|
45
|
+
* the remedy is a checkout setting, fetch-depth: 0.
|
|
46
|
+
*/
|
|
47
|
+
| 'history-shallow';
|
|
40
48
|
export interface CouldNotRun {
|
|
41
49
|
reason: CouldNotRunReason;
|
|
42
50
|
detail: string;
|
package/dist/gate-runner.js
CHANGED
|
@@ -274,9 +274,10 @@ external = {}) {
|
|
|
274
274
|
// with cwd at the repository root anyway. Passing one would also risk
|
|
275
275
|
// a passthrough value being read as the positional.
|
|
276
276
|
//
|
|
277
|
-
// `scan` takes --trust-base from 1.7.0
|
|
278
|
-
//
|
|
279
|
-
//
|
|
277
|
+
// `scan` takes --trust-base from 1.7.0. On exit 2 it prints a line on
|
|
278
|
+
// stderr and may also write a JSON document (it can on a staged run);
|
|
279
|
+
// conductor never parses stdout on exit 2, so the could-not-run path
|
|
280
|
+
// above handles both before JSON.parse is reached.
|
|
280
281
|
return [...(staged ? ['--staged'] : []), '-f', 'json', ...trust, ...passthrough];
|
|
281
282
|
case 'intent-guard': {
|
|
282
283
|
if (intent === undefined) {
|
|
@@ -484,7 +485,10 @@ function missingGateRemedy(product, skipNodeModules, skipped) {
|
|
|
484
485
|
return ` ${profile.remedy(skipNodeModules)}`;
|
|
485
486
|
}
|
|
486
487
|
if (!skipNodeModules) {
|
|
487
|
-
|
|
488
|
+
// Named on a local run too: the scoped package is the only correct
|
|
489
|
+
// install target, and the finding's own sentence must not be the only
|
|
490
|
+
// place a reader could take a bare name from.
|
|
491
|
+
return ` ${profile.remedy(false)}`;
|
|
488
492
|
}
|
|
489
493
|
return (' On a pull-request run node_modules/.bin is not consulted at all: what is installed there ' +
|
|
490
494
|
'is chosen by the head own manifest and lockfile, so no ref approves it.' +
|
|
@@ -559,6 +563,18 @@ export function runGate(gate, options) {
|
|
|
559
563
|
};
|
|
560
564
|
}
|
|
561
565
|
}
|
|
566
|
+
/**
|
|
567
|
+
* Whether git says the repository at `repoRoot` is shallow. Anything other
|
|
568
|
+
* than a clear "true" (no git, an old git that does not know the flag) is
|
|
569
|
+
* not shallow: those runs have their own failure paths.
|
|
570
|
+
*/
|
|
571
|
+
function isShallowRepository(repoRoot) {
|
|
572
|
+
const probe = spawnSync('git', ['rev-parse', '--is-shallow-repository'], {
|
|
573
|
+
cwd: repoRoot,
|
|
574
|
+
encoding: 'utf8',
|
|
575
|
+
});
|
|
576
|
+
return probe.status === 0 && typeof probe.stdout === 'string' && probe.stdout.trim() === 'true';
|
|
577
|
+
}
|
|
562
578
|
function runGateInner(gate, options, started, progress) {
|
|
563
579
|
const timeoutMs = options.timeoutMs ?? profileFor(gate.product).timeoutMs;
|
|
564
580
|
// ONE PLACE DECIDES WHAT PULL-REQUEST MODE IS, and it is the presence of a
|
|
@@ -611,7 +627,9 @@ function runGateInner(gate, options, started, progress) {
|
|
|
611
627
|
// not a location this run has.
|
|
612
628
|
detail: (skipNodeModules
|
|
613
629
|
? `no ${gate.product} binary on PATH`
|
|
614
|
-
: `no ${gate.product} binary in node_modules/.bin or on PATH`) +
|
|
630
|
+
: `no ${gate.product} binary in node_modules/.bin or on PATH`) +
|
|
631
|
+
(remedy === '' ? '' : '.') +
|
|
632
|
+
remedy,
|
|
615
633
|
},
|
|
616
634
|
// A missing enabled gate is a finding of the umbrella's own, never a
|
|
617
635
|
// silent skip. Skipping is how a gate ends up switched on in the
|
|
@@ -642,6 +660,27 @@ function runGateInner(gate, options, started, progress) {
|
|
|
642
660
|
};
|
|
643
661
|
}
|
|
644
662
|
}
|
|
663
|
+
// A history gate cannot vouch for history it was not given. Checked before
|
|
664
|
+
// the version probe so nothing is executed for a run that cannot be honest.
|
|
665
|
+
if (profileFor(gate.product).readsHistory && isShallowRepository(options.repoRoot)) {
|
|
666
|
+
const detail = `this checkout is shallow, so the git history ${gate.product} reads is truncated: ` +
|
|
667
|
+
'with the default actions/checkout depth of 1 the range from the base to HEAD holds a ' +
|
|
668
|
+
'single grafted commit, and a secret added and then removed inside the pull request ' +
|
|
669
|
+
'would never be seen. Check out with fetch-depth: 0 (actions/checkout) or run ' +
|
|
670
|
+
'git fetch --unshallow, then run again. conductor does not deepen the checkout itself.';
|
|
671
|
+
return {
|
|
672
|
+
...base,
|
|
673
|
+
// Under a trust base this is enforced whatever the policy says: the
|
|
674
|
+
// gate produced nothing for `enforce: false` to be a decision about.
|
|
675
|
+
// A local run keeps the policy's own value.
|
|
676
|
+
enforce: options.trustBase !== undefined ? true : gate.enforce,
|
|
677
|
+
durationMs: Date.now() - started,
|
|
678
|
+
couldNotRun: { reason: 'history-shallow', detail },
|
|
679
|
+
findings: [normalizeFailedGate(gate.role, gate.product, detail)],
|
|
680
|
+
run: EMPTY_RUN,
|
|
681
|
+
diagnostics: [],
|
|
682
|
+
};
|
|
683
|
+
}
|
|
645
684
|
const version = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
|
|
646
685
|
// The command-line floor. Only the external tools have one: the umbrella
|
|
647
686
|
// writes flags they grew at a known release (gitleaks' git subcommand,
|
|
@@ -895,6 +934,11 @@ function spawnAndRead(ctx) {
|
|
|
895
934
|
encoding: 'utf8',
|
|
896
935
|
timeout: timeoutMs,
|
|
897
936
|
maxBuffer: 64 * 1024 * 1024,
|
|
937
|
+
// A history gate reads git history, and replace refs or grafts can cut
|
|
938
|
+
// that history without making the repository shallow. Ignoring replace
|
|
939
|
+
// objects makes it read the real commits. Other gates keep the
|
|
940
|
+
// inherited environment untouched.
|
|
941
|
+
...(profile.readsHistory ? { env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' } } : {}),
|
|
898
942
|
});
|
|
899
943
|
const withRun = {
|
|
900
944
|
...base,
|
package/dist/init-policy.js
CHANGED
|
@@ -2,6 +2,7 @@ import { statSync } from 'node:fs';
|
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
import { NATIVE_CONTRACT_PATH } from './intent-prepare.js';
|
|
4
4
|
import { DEFAULT_STAGE_FOR_ROLE, GATE_ROLES, POLICY_FILE_NAME, PRODUCT_FOR_ROLE } from './policy.js';
|
|
5
|
+
import { installName } from './normalize.js';
|
|
5
6
|
import { CANDIDATES } from './resolve.js';
|
|
6
7
|
export { POLICY_FILE_NAME };
|
|
7
8
|
/** Names of the gates whose binary resolves right now. */
|
|
@@ -96,7 +97,7 @@ export function renderPolicy(detected, frozenContractPath) {
|
|
|
96
97
|
const enabled = detected.has(role);
|
|
97
98
|
lines.push(` # ${ROLE_DESCRIPTION[role]}`);
|
|
98
99
|
if (!enabled) {
|
|
99
|
-
lines.push(` # not found in node_modules/.bin or on PATH. Install ${product}, then set enabled: true.`);
|
|
100
|
+
lines.push(` # not found in node_modules/.bin or on PATH. Install ${installName(product)}, then set enabled: true.`);
|
|
100
101
|
}
|
|
101
102
|
lines.push(` ${role}:`);
|
|
102
103
|
lines.push(` product: ${product}`);
|
package/dist/intent-base.d.ts
CHANGED
|
@@ -23,6 +23,35 @@ export declare function resolveBaseRef(options: {
|
|
|
23
23
|
base?: string;
|
|
24
24
|
env: NodeJS.ProcessEnv;
|
|
25
25
|
}): BaseResolution | null;
|
|
26
|
+
export type ResolvedBase = {
|
|
27
|
+
ok: true;
|
|
28
|
+
base: BaseResolution | null;
|
|
29
|
+
} | {
|
|
30
|
+
ok: false;
|
|
31
|
+
detail: string;
|
|
32
|
+
};
|
|
33
|
+
/**
|
|
34
|
+
* The base to diff against, resolved against the repository and always
|
|
35
|
+
* spelled so a tag cannot shadow it (the same class as the trust base: git
|
|
36
|
+
* resolves a short origin/<base> through refs/tags/ first, so a tag at
|
|
37
|
+
* HEAD~1 would narrow the change set to the last commit).
|
|
38
|
+
*
|
|
39
|
+
* - An explicit --base keeps its meaning, but a short name that matches
|
|
40
|
+
* more than one kind of ref is refused (refuseAmbiguousRef).
|
|
41
|
+
* - Otherwise, on a pull request: refs/conductor/trust-base (the composite
|
|
42
|
+
* action's private fetch) when it exists, else refs/remotes/origin/<base>,
|
|
43
|
+
* both in full. The private ref wins and is not compared against the
|
|
44
|
+
* remote-tracking ref. If neither exists the spelled remote ref is returned and the
|
|
45
|
+
* diff fails closed, naming fetch-depth: 0.
|
|
46
|
+
* - Null outside a pull request.
|
|
47
|
+
*
|
|
48
|
+
* Nothing is deepened here: a depth-1 private ref has no merge base and the
|
|
49
|
+
* diff fails closed, the same outcome as a depth-1 origin/<base> always had.
|
|
50
|
+
*/
|
|
51
|
+
export declare function resolveBaseRefInRepo(repoRoot: string, options: {
|
|
52
|
+
base?: string;
|
|
53
|
+
env: NodeJS.ProcessEnv;
|
|
54
|
+
}): ResolvedBase;
|
|
26
55
|
/**
|
|
27
56
|
* The branch this run is about.
|
|
28
57
|
*
|
package/dist/intent-base.js
CHANGED
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
// the flags below are copied from intent-guard 1.2.1 so the two agree on what
|
|
17
17
|
// "changed" means rather than agreeing by coincidence.
|
|
18
18
|
import { spawnSync } from 'node:child_process';
|
|
19
|
+
import { PRIVATE_TRUST_BASE_REF, exactRefObject, refuseAmbiguousRef } from './trust-base.js';
|
|
19
20
|
/**
|
|
20
21
|
* The ref to diff against, or null for a run that is not a pull request.
|
|
21
22
|
*
|
|
@@ -35,6 +36,77 @@ export function resolveBaseRef(options) {
|
|
|
35
36
|
}
|
|
36
37
|
return null;
|
|
37
38
|
}
|
|
39
|
+
/**
|
|
40
|
+
* The base to diff against, resolved against the repository and always
|
|
41
|
+
* spelled so a tag cannot shadow it (the same class as the trust base: git
|
|
42
|
+
* resolves a short origin/<base> through refs/tags/ first, so a tag at
|
|
43
|
+
* HEAD~1 would narrow the change set to the last commit).
|
|
44
|
+
*
|
|
45
|
+
* - An explicit --base keeps its meaning, but a short name that matches
|
|
46
|
+
* more than one kind of ref is refused (refuseAmbiguousRef).
|
|
47
|
+
* - Otherwise, on a pull request: refs/conductor/trust-base (the composite
|
|
48
|
+
* action's private fetch) when it exists, else refs/remotes/origin/<base>,
|
|
49
|
+
* both in full. The private ref wins and is not compared against the
|
|
50
|
+
* remote-tracking ref. If neither exists the spelled remote ref is returned and the
|
|
51
|
+
* diff fails closed, naming fetch-depth: 0.
|
|
52
|
+
* - Null outside a pull request.
|
|
53
|
+
*
|
|
54
|
+
* Nothing is deepened here: a depth-1 private ref has no merge base and the
|
|
55
|
+
* diff fails closed, the same outcome as a depth-1 origin/<base> always had.
|
|
56
|
+
*/
|
|
57
|
+
export function resolveBaseRefInRepo(repoRoot, options) {
|
|
58
|
+
if (options.base !== undefined && options.base !== '') {
|
|
59
|
+
// A base that starts with a dash is an OPTION to git, not a ref:
|
|
60
|
+
// "--output=/x" made "git diff --output=/x...HEAD" write that file and
|
|
61
|
+
// print nothing, an empty change set the intent gate then judged as clean.
|
|
62
|
+
// Refused here, and changedPathsSince passes --end-of-options as well.
|
|
63
|
+
if (options.base.startsWith('-')) {
|
|
64
|
+
return {
|
|
65
|
+
ok: false,
|
|
66
|
+
detail: `refusing "${options.base}" as the intent gate base: it starts with a dash, so git would ` +
|
|
67
|
+
'read it as an option rather than a ref. Nothing was checked.',
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
const ambiguous = refuseAmbiguousRef(repoRoot, options.base, 'the intent gate base');
|
|
71
|
+
if (ambiguous !== null) {
|
|
72
|
+
return { ok: false, detail: ambiguous };
|
|
73
|
+
}
|
|
74
|
+
// A refs/ name is checked with show-ref: git's name resolution would
|
|
75
|
+
// otherwise fall back to refs/tags/<that name> when the ref is absent.
|
|
76
|
+
if (options.base.startsWith('refs/') && exactRefObject(repoRoot, options.base) === null) {
|
|
77
|
+
return {
|
|
78
|
+
ok: false,
|
|
79
|
+
detail: `refusing "${options.base}" as the intent gate base: no such ref exists in this ` +
|
|
80
|
+
'repository (a tag of that name does not count). Nothing was checked.',
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
return { ok: true, base: { ref: options.base, source: 'flag' } };
|
|
84
|
+
}
|
|
85
|
+
const fromGithub = options.env.GITHUB_BASE_REF;
|
|
86
|
+
if (fromGithub === undefined || fromGithub === '') {
|
|
87
|
+
return { ok: true, base: null };
|
|
88
|
+
}
|
|
89
|
+
const remoteRef = `refs/remotes/origin/${fromGithub}`;
|
|
90
|
+
// The private ref is the authority when it exists; refs/remotes/origin/<base>
|
|
91
|
+
// is fixed at checkout time, is the side pull-request code can move, and is
|
|
92
|
+
// not compared against it (a merge to the base in between would be a false
|
|
93
|
+
// refusal). It is the base only when the private ref is absent. Both are
|
|
94
|
+
// read with show-ref (the EXACT ref, never git's name resolution, which
|
|
95
|
+
// would take a tag of that name) and the base handed on is the commit id.
|
|
96
|
+
const priv = exactRefObject(repoRoot, PRIVATE_TRUST_BASE_REF);
|
|
97
|
+
const remote = exactRefObject(repoRoot, remoteRef);
|
|
98
|
+
const chosen = priv ?? remote;
|
|
99
|
+
if (chosen === null) {
|
|
100
|
+
return {
|
|
101
|
+
ok: false,
|
|
102
|
+
detail: `neither ${PRIVATE_TRUST_BASE_REF} (the composite action's fetch of the base branch) nor ` +
|
|
103
|
+
`${remoteRef} exists in this repository, so there is no base to measure the intent gate ` +
|
|
104
|
+
'against. Nothing was checked. In CI, check out with fetch-depth: 0, or fetch the base ' +
|
|
105
|
+
'ref before the run.',
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
return { ok: true, base: { ref: chosen, source: 'github' } };
|
|
109
|
+
}
|
|
38
110
|
/**
|
|
39
111
|
* The branch this run is about.
|
|
40
112
|
*
|
|
@@ -83,7 +155,15 @@ export function changedPathsSince(repoRoot, base) {
|
|
|
83
155
|
'core.quotePath=false',
|
|
84
156
|
'diff',
|
|
85
157
|
'--name-only',
|
|
158
|
+
// NUL-terminated, so a name with a quote, a backslash, a tab or a
|
|
159
|
+
// newline arrives byte for byte instead of C-quoted ("a\"b.txt"), which
|
|
160
|
+
// names no file and which intent-guard refuses outright (backslash).
|
|
161
|
+
'-z',
|
|
86
162
|
'--no-renames',
|
|
163
|
+
// Everything after this is a revision, never an option, whatever the
|
|
164
|
+
// caller-given base looks like (the second line of defence behind the
|
|
165
|
+
// dash refusal in resolveBaseRefInRepo).
|
|
166
|
+
'--end-of-options',
|
|
87
167
|
`${base}...HEAD`,
|
|
88
168
|
], { cwd: repoRoot, encoding: 'utf8' });
|
|
89
169
|
if (child.error !== undefined) {
|
|
@@ -102,11 +182,11 @@ export function changedPathsSince(repoRoot, base) {
|
|
|
102
182
|
'check out with fetch-depth: 0, or fetch the base ref before the run.',
|
|
103
183
|
};
|
|
104
184
|
}
|
|
105
|
-
// Split on
|
|
185
|
+
// Split on NUL and NOTHING else. Trimming each entry was corrupting a
|
|
106
186
|
// filename with leading or trailing whitespace into a different filename,
|
|
107
187
|
// which is worse than refusing it: the gate would then check a path that
|
|
108
188
|
// does not exist and never check the one that changed.
|
|
109
|
-
const paths = (child.stdout ?? '').split('\
|
|
189
|
+
const paths = (child.stdout ?? '').split('\0').filter((line) => line.length > 0);
|
|
110
190
|
for (const entry of paths) {
|
|
111
191
|
// Fail closed rather than hand over a path the encoding cannot carry.
|
|
112
192
|
// `--paths` is comma-joined, which is the only shape intent-guard 1.2.1
|
|
@@ -122,6 +202,20 @@ export function changedPathsSince(repoRoot, base) {
|
|
|
122
202
|
'Nothing was checked, rather than checking a path that does not exist.',
|
|
123
203
|
};
|
|
124
204
|
}
|
|
205
|
+
// intent-guard refuses ANY explicit --paths entry containing a backslash
|
|
206
|
+
// (skill/src/changed-paths.ts, explicitPathIssue: "it contains a
|
|
207
|
+
// backslash"), and exits 2 with a message that names the flag rather than
|
|
208
|
+
// the file. Said here instead, naming the file. A newline, tab or quote
|
|
209
|
+
// inside a path is accepted by intent-guard (it splits on commas only) and
|
|
210
|
+
// passes through intact.
|
|
211
|
+
if (entry.includes('\\')) {
|
|
212
|
+
return {
|
|
213
|
+
ok: false,
|
|
214
|
+
detail: `the changed path "${entry}" contains a backslash, and intent-guard refuses an explicit ` +
|
|
215
|
+
'path list entry with one (--paths), so it cannot judge this change. Nothing was ' +
|
|
216
|
+
'checked. Rename the file, or run the intent gate against the index instead.',
|
|
217
|
+
};
|
|
218
|
+
}
|
|
125
219
|
if (entry !== entry.trim()) {
|
|
126
220
|
return {
|
|
127
221
|
ok: false,
|
package/dist/intent-prepare.js
CHANGED
|
@@ -34,7 +34,7 @@ import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, st
|
|
|
34
34
|
import os from 'node:os';
|
|
35
35
|
import path from 'node:path';
|
|
36
36
|
import { parse as parseYaml } from 'yaml';
|
|
37
|
-
import { changedPathsSince, currentBranch,
|
|
37
|
+
import { changedPathsSince, currentBranch, resolveBaseRefInRepo } from './intent-base.js';
|
|
38
38
|
import { summariseStderr } from './normalize.js';
|
|
39
39
|
import { SPEC_DIR, discoverSpec, prBodyFromEvent } from './intent-spec.js';
|
|
40
40
|
/** Prefix of the per-run directory, exported so a test can count leaks. */
|
|
@@ -383,10 +383,14 @@ export function prepareIntent(options) {
|
|
|
383
383
|
'Name one with a "Spec: <path>" line in the pull request body, or pass --spec.',
|
|
384
384
|
};
|
|
385
385
|
}
|
|
386
|
-
const
|
|
386
|
+
const resolvedBase = resolveBaseRefInRepo(repoRoot, {
|
|
387
387
|
...(options.base === undefined ? {} : { base: options.base }),
|
|
388
388
|
env,
|
|
389
389
|
});
|
|
390
|
+
if (!resolvedBase.ok) {
|
|
391
|
+
return { kind: 'failed', step: 'base', detail: resolvedBase.detail };
|
|
392
|
+
}
|
|
393
|
+
const base = resolvedBase.base;
|
|
390
394
|
let paths = null;
|
|
391
395
|
if (base !== null) {
|
|
392
396
|
const changed = changedPathsSince(repoRoot, base.ref);
|
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) {
|
|
@@ -1045,6 +1046,17 @@ function gateProblem(ruleId, role, product, message, details) {
|
|
|
1045
1046
|
details: { role, product, ...details },
|
|
1046
1047
|
};
|
|
1047
1048
|
}
|
|
1049
|
+
/**
|
|
1050
|
+
* What to install for a product, spelled so it cannot be mistaken for
|
|
1051
|
+
* another package. The three npm gates are published under the
|
|
1052
|
+
* @vaultcompass scope only: the unscoped dep-guard and intent-guard names are
|
|
1053
|
+
* unclaimed on npm, so a reader (or an agent) told to install the bare name
|
|
1054
|
+
* could install a squatted package. The external tools are not npm packages
|
|
1055
|
+
* of this family and keep their own names.
|
|
1056
|
+
*/
|
|
1057
|
+
export function installName(product) {
|
|
1058
|
+
return profileFor(product).managed ? `@vaultcompass/${product}` : product;
|
|
1059
|
+
}
|
|
1048
1060
|
/**
|
|
1049
1061
|
* The finding raised when an ENABLED gate's binary cannot be found.
|
|
1050
1062
|
*
|
|
@@ -1066,7 +1078,7 @@ export function normalizeMissingGate(role, product, candidates,
|
|
|
1066
1078
|
*/
|
|
1067
1079
|
remedy = '') {
|
|
1068
1080
|
return gateProblem('conductor/gate-missing', role, product, `The "${role}" gate is enabled but no ${product} binary was found. ` +
|
|
1069
|
-
`Looked for: ${candidates.join(', ')}. Install
|
|
1081
|
+
`Looked for: ${candidates.join(', ')}. Install ${installName(product)}, point the gate at a build with an ` +
|
|
1070
1082
|
`absolute "command:", or set enabled: false to switch the gate off on purpose.${remedy}`, { candidates });
|
|
1071
1083
|
}
|
|
1072
1084
|
/**
|
package/dist/output-text.d.ts
CHANGED
|
@@ -25,6 +25,41 @@ import type { RunResult } from './run.js';
|
|
|
25
25
|
* not change.
|
|
26
26
|
*/
|
|
27
27
|
export declare function jobLogSummary(result: RunResult): string;
|
|
28
|
+
/**
|
|
29
|
+
* The verdict token: a label for the umbrella's OWN exit decision, in a
|
|
30
|
+
* closed set, so a person or a script reading a report or a job summary gets
|
|
31
|
+
* the state without parsing the verdict sentence.
|
|
32
|
+
*
|
|
33
|
+
* pass exit 0 and nothing was hidden by it
|
|
34
|
+
* nothing-checked exit 0, but no gate ran at all (none enabled,
|
|
35
|
+
* or every one deferred, tree-unchanged or skipped)
|
|
36
|
+
* advisory-blocked (N) exit 1 that --advisory turned into exit 0
|
|
37
|
+
* unenforced-findings (N) exit 0, but enforce: false gates blocked or
|
|
38
|
+
* could not run
|
|
39
|
+
* blocked (N) exit 1
|
|
40
|
+
* could-not-run exit 2, a refused trust base included
|
|
41
|
+
*
|
|
42
|
+
* PRECEDENCE, when several apply: could-not-run, then blocked or
|
|
43
|
+
* advisory-blocked, then unenforced-findings, then pass. So an advisory run
|
|
44
|
+
* whose only blocking findings sit on an unenforced gate is
|
|
45
|
+
* unenforced-findings and never advisory-blocked: --advisory did nothing
|
|
46
|
+
* there, and saying it did would be a false statement of what was hidden.
|
|
47
|
+
*
|
|
48
|
+
* This decides nothing. Every branch reads the exit code composeExitCode
|
|
49
|
+
* already produced (result.exitCode) and the enforce flags already on the
|
|
50
|
+
* gates; the only counting is over what those gates said. It never
|
|
51
|
+
* overrules a gate. It is also the same `advisory` boolean cli.ts hands to
|
|
52
|
+
* applyAdvisory, so the label and the process exit code cannot disagree.
|
|
53
|
+
*
|
|
54
|
+
* A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
|
|
55
|
+
* than result.gates, is neither a blocking finding nor a could-not-run, and
|
|
56
|
+
* so does not by itself move the token off pass when another gate ran. When
|
|
57
|
+
* NO gate ran, the token is nothing-checked, matching the verdict sentence.
|
|
58
|
+
*
|
|
59
|
+
* Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
|
|
60
|
+
* not a pass.
|
|
61
|
+
*/
|
|
62
|
+
export declare function verdictToken(result: RunResult, advisory: boolean): string;
|
|
28
63
|
export interface TextOptions {
|
|
29
64
|
/**
|
|
30
65
|
* Print the full report even when the run is fully clean.
|
package/dist/output-text.js
CHANGED
|
@@ -382,6 +382,81 @@ export function jobLogSummary(result) {
|
|
|
382
382
|
}
|
|
383
383
|
return `${result.gates.length} gate(s), ${result.findings.length} finding(s)`;
|
|
384
384
|
}
|
|
385
|
+
/**
|
|
386
|
+
* How many blocking findings one gate that RAN is carrying, for the token.
|
|
387
|
+
*
|
|
388
|
+
* A gate that exited non-zero with nothing on screen marked blocking (the
|
|
389
|
+
* mismatch shape the verdict sentence already has its own wording for) counts
|
|
390
|
+
* as one, so a state that is not a pass never prints a count of zero. A gate
|
|
391
|
+
* that could not run is not counted here at all: its findings list carries
|
|
392
|
+
* the umbrella's own blocking gate-missing finding, and counting that as well
|
|
393
|
+
* would report one broken gate as two things.
|
|
394
|
+
*/
|
|
395
|
+
function blockingCount(gate) {
|
|
396
|
+
if (gate.couldNotRun !== null) {
|
|
397
|
+
return 0;
|
|
398
|
+
}
|
|
399
|
+
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
400
|
+
return blocking === 0 && (gate.exitCode ?? 0) !== 0 ? 1 : blocking;
|
|
401
|
+
}
|
|
402
|
+
/**
|
|
403
|
+
* The verdict token: a label for the umbrella's OWN exit decision, in a
|
|
404
|
+
* closed set, so a person or a script reading a report or a job summary gets
|
|
405
|
+
* the state without parsing the verdict sentence.
|
|
406
|
+
*
|
|
407
|
+
* pass exit 0 and nothing was hidden by it
|
|
408
|
+
* nothing-checked exit 0, but no gate ran at all (none enabled,
|
|
409
|
+
* or every one deferred, tree-unchanged or skipped)
|
|
410
|
+
* advisory-blocked (N) exit 1 that --advisory turned into exit 0
|
|
411
|
+
* unenforced-findings (N) exit 0, but enforce: false gates blocked or
|
|
412
|
+
* could not run
|
|
413
|
+
* blocked (N) exit 1
|
|
414
|
+
* could-not-run exit 2, a refused trust base included
|
|
415
|
+
*
|
|
416
|
+
* PRECEDENCE, when several apply: could-not-run, then blocked or
|
|
417
|
+
* advisory-blocked, then unenforced-findings, then pass. So an advisory run
|
|
418
|
+
* whose only blocking findings sit on an unenforced gate is
|
|
419
|
+
* unenforced-findings and never advisory-blocked: --advisory did nothing
|
|
420
|
+
* there, and saying it did would be a false statement of what was hidden.
|
|
421
|
+
*
|
|
422
|
+
* This decides nothing. Every branch reads the exit code composeExitCode
|
|
423
|
+
* already produced (result.exitCode) and the enforce flags already on the
|
|
424
|
+
* gates; the only counting is over what those gates said. It never
|
|
425
|
+
* overrules a gate. It is also the same `advisory` boolean cli.ts hands to
|
|
426
|
+
* applyAdvisory, so the label and the process exit code cannot disagree.
|
|
427
|
+
*
|
|
428
|
+
* A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
|
|
429
|
+
* than result.gates, is neither a blocking finding nor a could-not-run, and
|
|
430
|
+
* so does not by itself move the token off pass when another gate ran. When
|
|
431
|
+
* NO gate ran, the token is nothing-checked, matching the verdict sentence.
|
|
432
|
+
*
|
|
433
|
+
* Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
|
|
434
|
+
* not a pass.
|
|
435
|
+
*/
|
|
436
|
+
export function verdictToken(result, advisory) {
|
|
437
|
+
const refusal = result.trustBase?.refusal;
|
|
438
|
+
const refused = refusal !== undefined && refusal !== null;
|
|
439
|
+
if (refused || (result.exitCode !== 0 && result.exitCode !== EXIT_BLOCKED)) {
|
|
440
|
+
return 'could-not-run';
|
|
441
|
+
}
|
|
442
|
+
if (result.exitCode === EXIT_BLOCKED) {
|
|
443
|
+
const count = result.gates
|
|
444
|
+
.filter((gate) => gate.enforce)
|
|
445
|
+
.reduce((total, gate) => total + blockingCount(gate), 0);
|
|
446
|
+
return advisory ? `advisory-blocked (${count})` : `blocked (${count})`;
|
|
447
|
+
}
|
|
448
|
+
// Exit 0 with no gate having run at all (none enabled, every one deferred,
|
|
449
|
+
// tree-unchanged or skipped): the exit code stays 0, since nothing failed,
|
|
450
|
+
// but the label must not say pass. It is the same condition the verdict
|
|
451
|
+
// sentence words as "nothing was checked".
|
|
452
|
+
if (result.gates.length === 0) {
|
|
453
|
+
return 'nothing-checked';
|
|
454
|
+
}
|
|
455
|
+
const unenforced = result.gates
|
|
456
|
+
.filter((gate) => !gate.enforce)
|
|
457
|
+
.reduce((total, gate) => total + (gate.couldNotRun !== null ? 1 : blockingCount(gate)), 0);
|
|
458
|
+
return unenforced > 0 ? `unenforced-findings (${unenforced})` : 'pass';
|
|
459
|
+
}
|
|
385
460
|
function verdict(result, advisory) {
|
|
386
461
|
const refusal = result.trustBase?.refusal;
|
|
387
462
|
if (refusal !== undefined && refusal !== null) {
|
|
@@ -698,6 +773,18 @@ function summaryLine(result) {
|
|
|
698
773
|
function versionLine(version) {
|
|
699
774
|
return version === undefined ? [] : [`conductor ${version}`];
|
|
700
775
|
}
|
|
776
|
+
/**
|
|
777
|
+
* The version line, then the verdict-token line directly under it: the first
|
|
778
|
+
* two lines of every report that carries a token. Without a version the
|
|
779
|
+
* token is the first line. The closing verdict sentence is a separate thing
|
|
780
|
+
* and stays where it was.
|
|
781
|
+
*/
|
|
782
|
+
function headerLines(result, options) {
|
|
783
|
+
return [
|
|
784
|
+
...versionLine(options.version),
|
|
785
|
+
`verdict-token: ${verdictToken(result, Boolean(options.advisory))}`,
|
|
786
|
+
];
|
|
787
|
+
}
|
|
701
788
|
export function renderText(result, options = {}) {
|
|
702
789
|
const refusal = refusalLines(result);
|
|
703
790
|
if (options.compact === true && refusal.length > 0) {
|
|
@@ -708,7 +795,7 @@ export function renderText(result, options = {}) {
|
|
|
708
795
|
// proposal) as part of the same sentence. Nothing here points at a step
|
|
709
796
|
// log: the reason has to be readable on the comment itself.
|
|
710
797
|
const lines = [
|
|
711
|
-
...
|
|
798
|
+
...headerLines(result, options),
|
|
712
799
|
verdict(result, Boolean(options.advisory)),
|
|
713
800
|
...refusal,
|
|
714
801
|
];
|
|
@@ -726,7 +813,7 @@ export function renderText(result, options = {}) {
|
|
|
726
813
|
// different questions, so two numbers, and the section headers and the
|
|
727
814
|
// "not enforced" lines are what connect them.
|
|
728
815
|
const lines = [
|
|
729
|
-
...
|
|
816
|
+
...headerLines(result, options),
|
|
730
817
|
...refusal,
|
|
731
818
|
...(refusal.length === 0 ? [] : ['']),
|
|
732
819
|
`conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
|
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/trust-base.d.ts
CHANGED
|
@@ -1,3 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The private, fully spelled ref the composite action fetches the base branch
|
|
3
|
+
* into (action.yml, gates step). Nothing else writes it and no short name can
|
|
4
|
+
* shadow it: git resolves a short name like origin/main through refs/tags/
|
|
5
|
+
* BEFORE refs/remotes/, so a tag pushed by anyone able to push tags would
|
|
6
|
+
* otherwise choose the commit the rules are read from.
|
|
7
|
+
*/
|
|
8
|
+
export declare const PRIVATE_TRUST_BASE_REF = "refs/conductor/trust-base";
|
|
9
|
+
/**
|
|
10
|
+
* The object id a fully spelled ref EXACTLY names, or null when there is no
|
|
11
|
+
* such ref. `show-ref --verify` looks at that ref and nothing else: it does
|
|
12
|
+
* not run git's name-resolution rules, so a tag stored as
|
|
13
|
+
* refs/tags/refs/conductor/trust-base is never taken for
|
|
14
|
+
* refs/conductor/trust-base.
|
|
15
|
+
*/
|
|
16
|
+
export declare function exactRefObject(repoRoot: string, fullRef: string): string | null;
|
|
17
|
+
/**
|
|
18
|
+
* A caller-given trust base that starts with "-", or null. Git allows a tag
|
|
19
|
+
* named refs/tags/--output=x, and such a name handed to git as an argument is
|
|
20
|
+
* read as an option, not a revision. Refused before any git call sees it; the
|
|
21
|
+
* git calls below also pass --end-of-options as a second line of defence.
|
|
22
|
+
*/
|
|
23
|
+
export declare function refuseDashLeadingRef(ref: string): string | null;
|
|
24
|
+
/** A full 40- or 64-hex object id: never subject to ref name resolution. */
|
|
25
|
+
export declare function isFullObjectId(value: string): boolean;
|
|
26
|
+
/**
|
|
27
|
+
* Why a SHORT ref name cannot be trusted as spelled, or null.
|
|
28
|
+
*
|
|
29
|
+
* A name that matches more than one kind of ref (a tag and a remote-tracking
|
|
30
|
+
* ref or a branch) is resolved by git in its own precedence order, tags
|
|
31
|
+
* first, with no warning under --quiet. That is a choice made by whoever can
|
|
32
|
+
* create the tag, so it is refused rather than resolved. A ref already spelled
|
|
33
|
+
* from refs/ is unambiguous, and revision expressions (HEAD, HEAD~1, a sha) are
|
|
34
|
+
* not names and are left to the callers' own checks.
|
|
35
|
+
*/
|
|
36
|
+
export declare function refuseAmbiguousRef(repoRoot: string, ref: string,
|
|
37
|
+
/** What the ref is used as, for the message: "the trust base", "the intent base". */
|
|
38
|
+
noun?: string): string | null;
|
|
39
|
+
/**
|
|
40
|
+
* What a rev resolves to at this repository, or null when it does not.
|
|
41
|
+
*
|
|
42
|
+
* `--quiet` suppresses git's own explanation, so there is nothing worth
|
|
43
|
+
* forwarding on failure: the caller writes a sentence a reader can act on
|
|
44
|
+
* rather than repeating the command line that failed.
|
|
45
|
+
*/
|
|
46
|
+
export declare function resolveRev(repoRoot: string, rev: string, kind: 'commit' | 'tree'): string | null;
|
|
1
47
|
/**
|
|
2
48
|
* Whether HEAD's tree is byte-identical to the trust base's tree.
|
|
3
49
|
*
|
|
@@ -54,11 +100,12 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
|
|
|
54
100
|
* NAME on a pull_request or pull_request_target event, and empty everywhere
|
|
55
101
|
* else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
|
|
56
102
|
* a platform that never sets it. When it is set, the given ref is accepted
|
|
57
|
-
* only when it
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
103
|
+
* only when it is the FULL COMMIT ID the composite action's "Fetch the trust
|
|
104
|
+
* base" step published (which must equal refs/conductor/trust-base, the
|
|
105
|
+
* authority, or refs/remotes/origin/<githubBaseRef>, both read with show-ref),
|
|
106
|
+
* or is that private ref itself, or -- for an explicit trust base -- resolves
|
|
107
|
+
* to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
|
|
108
|
+
* pull-request run through the action returns null here, before
|
|
62
109
|
* refuseTrustBaseRef's own checks -- HEAD, and the equal-tree exception from
|
|
63
110
|
* issue #69/#73 -- ever run: this check is narrower than those and says
|
|
64
111
|
* nothing about HEAD or about tree equality, only about whether the given ref
|
|
@@ -66,11 +113,11 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
|
|
|
66
113
|
* request's own branch, or anything else that disagrees, is refused with both
|
|
67
114
|
* refs and both commits named.
|
|
68
115
|
*
|
|
69
|
-
* FAILS CLOSED when
|
|
70
|
-
*
|
|
71
|
-
*
|
|
72
|
-
* fetch-depth: 0, and a checkout
|
|
73
|
-
* reason to skip the comparison.
|
|
116
|
+
* FAILS CLOSED when neither the private ref nor refs/remotes/origin/
|
|
117
|
+
* <githubBaseRef> exists, naming them: reachable through the CLI on the
|
|
118
|
+
* default actions/checkout (fetch-depth: 1), which does not carry the base
|
|
119
|
+
* branch at all. The README already asks for fetch-depth: 0, and a checkout
|
|
120
|
+
* that does not carry the base branch is not a reason to skip the comparison.
|
|
74
121
|
*
|
|
75
122
|
* When the GIVEN ref does not resolve at all, this returns null rather than
|
|
76
123
|
* refusing: refuseTrustBaseRef is the function with its own sentence for an
|