@vaultcompass/conductor 0.8.0 → 0.9.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 +263 -77
- package/dist/cli.js +152 -30
- package/dist/envelope.d.ts +8 -0
- package/dist/exit-codes.d.ts +52 -2
- package/dist/exit-codes.js +64 -14
- package/dist/external-config.d.ts +2 -1
- package/dist/external-config.js +33 -18
- package/dist/gate-runner.d.ts +141 -17
- package/dist/gate-runner.js +537 -83
- package/dist/git.d.ts +95 -0
- package/dist/git.js +244 -0
- package/dist/init-policy.js +38 -2
- package/dist/init.js +40 -3
- package/dist/intent-base.d.ts +35 -1
- package/dist/intent-base.js +124 -64
- package/dist/intent-prepare.d.ts +33 -2
- package/dist/intent-prepare.js +443 -34
- package/dist/intent-spec.d.ts +28 -0
- package/dist/intent-spec.js +22 -5
- package/dist/normalize.d.ts +11 -0
- package/dist/normalize.js +60 -6
- package/dist/osv-baseline.d.ts +84 -0
- package/dist/osv-baseline.js +325 -0
- package/dist/osv-coverage.d.ts +80 -0
- package/dist/osv-coverage.js +223 -0
- package/dist/output-sarif.js +55 -15
- package/dist/output-text.d.ts +53 -2
- package/dist/output-text.js +287 -27
- package/dist/policy.d.ts +10 -0
- package/dist/policy.js +21 -7
- package/dist/products.d.ts +32 -10
- package/dist/products.js +73 -9
- package/dist/requirements-pin.d.ts +47 -0
- package/dist/requirements-pin.js +256 -0
- package/dist/resolve.d.ts +1 -0
- package/dist/resolve.js +1 -1
- package/dist/run.d.ts +21 -0
- package/dist/run.js +74 -15
- package/dist/trust-base.d.ts +101 -20
- package/dist/trust-base.js +219 -73
- package/dist/unread-manifests.d.ts +14 -0
- package/dist/unread-manifests.js +69 -0
- package/package.json +1 -1
- package/schema/guardrails.schema.json +4 -0
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
// Which tracked files the vulnerabilities gate hands osv-scanner (osv design,
|
|
2
|
+
// item 1.1, sections 2.1 to 2.4).
|
|
3
|
+
//
|
|
4
|
+
// Selection only. Nothing here raises a finding: a file left out is named in
|
|
5
|
+
// a diagnostic, the way the basename list has always decided what is handed
|
|
6
|
+
// over without judging anything. The verdict is still osv-scanner's own.
|
|
7
|
+
import { lstatSync, readFileSync, realpathSync } from 'node:fs';
|
|
8
|
+
import path from 'node:path';
|
|
9
|
+
import { runGit } from './git.js';
|
|
10
|
+
import { osvLockfileKind } from './products.js';
|
|
11
|
+
import { checkRequirementsPins, describePinProblem, } from './requirements-pin.js';
|
|
12
|
+
import { readFileAtRefBytes } from './trust-base.js';
|
|
13
|
+
/**
|
|
14
|
+
* A reader over the head: a TRACKED regular file on disk. On disk because
|
|
15
|
+
* that is the copy osv-scanner reads; tracked because an untracked file is
|
|
16
|
+
* not part of what is being judged.
|
|
17
|
+
*/
|
|
18
|
+
export function headReader(repoRoot, tracked) {
|
|
19
|
+
return (file) => {
|
|
20
|
+
const full = path.join(repoRoot, file);
|
|
21
|
+
let stats;
|
|
22
|
+
try {
|
|
23
|
+
stats = lstatSync(full);
|
|
24
|
+
}
|
|
25
|
+
catch {
|
|
26
|
+
return { kind: 'missing', why: tracked.has(file) ? 'is tracked but not on disk' : 'does not exist' };
|
|
27
|
+
}
|
|
28
|
+
if (!tracked.has(file)) {
|
|
29
|
+
return { kind: 'missing', why: 'is not tracked' };
|
|
30
|
+
}
|
|
31
|
+
if (!stats.isFile()) {
|
|
32
|
+
return { kind: 'missing', why: 'is not a regular file' };
|
|
33
|
+
}
|
|
34
|
+
return { kind: 'file', text: readFileSync(full, 'utf8') };
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
/** Why a base reader found nothing: the base tree has no such path. */
|
|
38
|
+
export const ABSENT_ON_BASE = 'does not exist on the base';
|
|
39
|
+
/**
|
|
40
|
+
* A reader over the trust base, through the one reader (readFileAtRef's byte
|
|
41
|
+
* variant). Every byte it hands out is kept in `bytes`, so a base copy that is
|
|
42
|
+
* written out later is exactly the blob that was checked, never a re-read.
|
|
43
|
+
*/
|
|
44
|
+
export function baseReader(repoRoot, ref, bytes = new Map()) {
|
|
45
|
+
return (file) => {
|
|
46
|
+
const read = readFileAtRefBytes(repoRoot, ref, file);
|
|
47
|
+
if (read.kind === 'absent') {
|
|
48
|
+
return { kind: 'missing', why: ABSENT_ON_BASE };
|
|
49
|
+
}
|
|
50
|
+
if (read.kind === 'error') {
|
|
51
|
+
return { kind: 'missing', why: `could not be read from the base (${read.detail})` };
|
|
52
|
+
}
|
|
53
|
+
bytes.set(file, read.bytes);
|
|
54
|
+
return { kind: 'file', text: read.bytes.toString('utf8') };
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
const DIRECT_ONLY = 'direct requirements only; no lockfile, so transitive packages are not scanned.';
|
|
58
|
+
/** The not-scanned sentence for one requirements file. */
|
|
59
|
+
function notScannedMessage(file, check) {
|
|
60
|
+
return `${file} not scanned: ${describePinProblem(file, check.problems[0])}.`;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Picks what osv-scanner is handed from the tracked files.
|
|
64
|
+
*
|
|
65
|
+
* `decidedRef` is the trust base on a pull-request run, and switches the
|
|
66
|
+
* ratchet on (section 2.3): a requirements file whose head copy fails the pin
|
|
67
|
+
* check is still handed over when its base copy, and the base include
|
|
68
|
+
* closure, passes. A base copy that exists and cannot be read is handed over
|
|
69
|
+
* too: leaving it out would let an unreadable base drop a file from the scan,
|
|
70
|
+
* which is the direction this gate does not fail in.
|
|
71
|
+
*/
|
|
72
|
+
export function selectOsvInputs(args) {
|
|
73
|
+
const trackedSet = new Set(args.tracked);
|
|
74
|
+
const candidates = args.tracked
|
|
75
|
+
// Never a vendored copy under node_modules: that is a dependency's own
|
|
76
|
+
// lockfile, not a statement about what this repository resolves.
|
|
77
|
+
.filter((file) => !file.split('/').includes('node_modules'))
|
|
78
|
+
// The whole repository-relative path, not the base name: one format
|
|
79
|
+
// (gradle's verification-metadata.xml) is matched on its parent too.
|
|
80
|
+
.filter((file) => osvLockfileKind(file) !== null)
|
|
81
|
+
.sort();
|
|
82
|
+
const head = headReader(args.repoRoot, trackedSet);
|
|
83
|
+
const base = args.decidedRef === undefined ? null : baseReader(args.repoRoot, args.decidedRef);
|
|
84
|
+
const handed = [];
|
|
85
|
+
const notScanned = [];
|
|
86
|
+
const diagnostics = [];
|
|
87
|
+
const notes = [];
|
|
88
|
+
const closures = new Map();
|
|
89
|
+
for (const file of candidates) {
|
|
90
|
+
if (osvLockfileKind(file) === 'bare') {
|
|
91
|
+
handed.push(file);
|
|
92
|
+
continue;
|
|
93
|
+
}
|
|
94
|
+
const headCheck = checkRequirementsPins(file, head);
|
|
95
|
+
if (headCheck.pinned) {
|
|
96
|
+
handed.push(file);
|
|
97
|
+
closures.set(file, headCheck.files);
|
|
98
|
+
let suffix = '';
|
|
99
|
+
if (base !== null) {
|
|
100
|
+
const baseCheck = checkRequirementsPins(file, base);
|
|
101
|
+
if (!baseCheck.pinned && baseCheck.topMissing !== ABSENT_ON_BASE) {
|
|
102
|
+
suffix = ' Newly pinned in this pull request.';
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
notes.push({ code: 'conductor/requirements-direct-only', message: `${file}: ${DIRECT_ONLY}${suffix}` });
|
|
106
|
+
continue;
|
|
107
|
+
}
|
|
108
|
+
if (base !== null) {
|
|
109
|
+
const baseCheck = checkRequirementsPins(file, base);
|
|
110
|
+
const topUnreadable = baseCheck.topMissing !== null && baseCheck.topMissing !== ABSENT_ON_BASE;
|
|
111
|
+
if (baseCheck.pinned || topUnreadable) {
|
|
112
|
+
handed.push(file);
|
|
113
|
+
closures.set(file, null);
|
|
114
|
+
const lines = headCheck.problems.map((problem) => describePinProblem(file, problem)).join('; ');
|
|
115
|
+
const why = baseCheck.pinned
|
|
116
|
+
? 'Its copy on the base is pinned, so the file stays scanned under the ratchet; the lines named are read as written.'
|
|
117
|
+
: 'Its copy on the base could not be read, so the file stays scanned; the lines named are read as written.';
|
|
118
|
+
diagnostics.push({
|
|
119
|
+
code: 'conductor/requirements-not-pinned',
|
|
120
|
+
message: `${file} is scanned although ${lines}. ${why}`,
|
|
121
|
+
});
|
|
122
|
+
notes.push({
|
|
123
|
+
code: 'conductor/requirements-direct-only',
|
|
124
|
+
message: `${file}: ${DIRECT_ONLY} ${baseCheck.pinned ? 'Pinned on the base; scanned under the ratchet.' : 'Base copy unreadable; scanned under the ratchet.'}`,
|
|
125
|
+
});
|
|
126
|
+
continue;
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
notScanned.push(file);
|
|
130
|
+
diagnostics.push({ code: 'conductor/requirements-not-scanned', message: notScannedMessage(file, headCheck) });
|
|
131
|
+
}
|
|
132
|
+
return { handed: handed.sort(), notScanned, diagnostics, notes, closures };
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* Notes for every basename-matched file tracked on the base and absent from
|
|
136
|
+
* the head (section 3.2): deleted, moved, or renamed to a name the matcher
|
|
137
|
+
* does not take. Such a file is not scanned on either side, and saying so is
|
|
138
|
+
* all this does: it never blocks. A base listing git could not make yields no
|
|
139
|
+
* note rather than a guess.
|
|
140
|
+
*/
|
|
141
|
+
export function noLongerScanned(repoRoot, ref, tracked) {
|
|
142
|
+
if (ref.startsWith('-')) {
|
|
143
|
+
return [];
|
|
144
|
+
}
|
|
145
|
+
const listing = runGit(repoRoot, ['ls-tree', '-r', '-z', '--name-only', ref], { maxBuffer: 64 * 1024 * 1024 });
|
|
146
|
+
if (listing.error !== undefined || listing.status !== 0) {
|
|
147
|
+
return [];
|
|
148
|
+
}
|
|
149
|
+
return listing.stdout
|
|
150
|
+
.split('\0')
|
|
151
|
+
.filter((file) => file !== '' && !file.split('/').includes('node_modules'))
|
|
152
|
+
.filter((file) => osvLockfileKind(file) !== null && !tracked.has(file))
|
|
153
|
+
.sort()
|
|
154
|
+
.map((file) => ({
|
|
155
|
+
code: 'conductor/lockfile-no-longer-scanned',
|
|
156
|
+
message: `${file} is tracked on the base and not in this pull request, so it is no longer scanned ` +
|
|
157
|
+
'(by either run). Its removal is visible in the diff.',
|
|
158
|
+
}));
|
|
159
|
+
}
|
|
160
|
+
/** The nothing-to-scan sentence when every candidate was a requirements file left out. */
|
|
161
|
+
export function nothingScannableMessage(notScanned) {
|
|
162
|
+
return (`osv-scanner had nothing it could scan: ${notScanned.length} requirements file(s) not pinned ` +
|
|
163
|
+
`(${notScanned.join(', ')}).`);
|
|
164
|
+
}
|
|
165
|
+
/** The run detail beside `lockfiles`: how many requirements files were left out, and which. */
|
|
166
|
+
export function notScannedDetail(notScanned) {
|
|
167
|
+
return `${notScanned.length} (${notScanned.join(', ')})`;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* osv-scanner 2.4.0's per-file count line on stderr, at its default
|
|
171
|
+
* verbosity (measured): "Scanned <absolute path> file and found N packages",
|
|
172
|
+
* with "package" for one.
|
|
173
|
+
*/
|
|
174
|
+
const SCANNED_LINE = /^Scanned (.+) file and found (\d+) packages?$/;
|
|
175
|
+
/** A path in both spellings worth comparing: as written and, when it exists, resolved. */
|
|
176
|
+
function spellings(file) {
|
|
177
|
+
const out = [file];
|
|
178
|
+
try {
|
|
179
|
+
const real = realpathSync(file);
|
|
180
|
+
if (real !== file) {
|
|
181
|
+
out.push(real);
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
catch {
|
|
185
|
+
// Not on disk under this spelling: the written form is all there is.
|
|
186
|
+
}
|
|
187
|
+
return out;
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* The handed lockfiles osv-scanner said it found 0 packages in (audit
|
|
191
|
+
* finding F2). Its exit 128 covers only the case where EVERY handed file
|
|
192
|
+
* parsed to nothing, and its JSON lists only sources with findings, so a
|
|
193
|
+
* lockfile rewritten to `{}` beside a healthy one is otherwise
|
|
194
|
+
* indistinguishable from a clean one: listed as scanned, with every advisory
|
|
195
|
+
* it carried gone.
|
|
196
|
+
*
|
|
197
|
+
* Read from osv-scanner's stderr, which is annotation, never a verdict: this
|
|
198
|
+
* only adds a note. `handed` are the repository-relative paths the umbrella
|
|
199
|
+
* passed (the parse-as prefix is not part of them), and `cwd` is where the
|
|
200
|
+
* child ran. A path is compared in its written and its resolved spelling on
|
|
201
|
+
* both sides, so a temp directory reached through a symlink still matches,
|
|
202
|
+
* and by whole path, so two files with one base name never stand in for each
|
|
203
|
+
* other. A file with no count line is not named: that is a limit (a policy
|
|
204
|
+
* that lowers osv-scanner's verbosity hides every line), not a finding.
|
|
205
|
+
*/
|
|
206
|
+
export function emptiedLockfiles(stderr, handed, cwd) {
|
|
207
|
+
const empty = new Set();
|
|
208
|
+
for (const raw of stderr.split('\n')) {
|
|
209
|
+
const match = SCANNED_LINE.exec(raw.trim());
|
|
210
|
+
if (match !== null && Number(match[2]) === 0) {
|
|
211
|
+
for (const spelling of spellings(match[1])) {
|
|
212
|
+
empty.add(spelling);
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
if (empty.size === 0) {
|
|
217
|
+
return [];
|
|
218
|
+
}
|
|
219
|
+
return handed.filter((file) => spellings(path.resolve(cwd, file)).some((spelling) => empty.has(spelling)));
|
|
220
|
+
}
|
|
221
|
+
/** The note when a policy's no-resolve was dropped from an invocation. */
|
|
222
|
+
export const NO_RESOLVE_OVERRIDDEN = 'options.no-resolve in .guardrails.yaml was not passed: requirements files are always scanned ' +
|
|
223
|
+
'with --no-resolve (direct requirements only).';
|
package/dist/output-sarif.js
CHANGED
|
@@ -117,6 +117,7 @@
|
|
|
117
117
|
// product, which puts an end column in its own SARIF; see the note in
|
|
118
118
|
// normalize.ts, which is where the omission would stop mattering if the
|
|
119
119
|
// field were ever carried.
|
|
120
|
+
import { gateExitBlocks } from './exit-codes.js';
|
|
120
121
|
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
121
122
|
import { INTENT_WARNING } from './normalize.js';
|
|
122
123
|
import { POLICY_FILE_NAME } from './policy.js';
|
|
@@ -320,6 +321,18 @@ function toResult(finding, fallbackUri) {
|
|
|
320
321
|
if (finding.fingerprint !== null) {
|
|
321
322
|
entry.partialFingerprints = { [fingerprintKey(finding.fingerprint.scope)]: finding.fingerprint.value };
|
|
322
323
|
}
|
|
324
|
+
// SARIF's own baselineState, only where the umbrella has a baseline to
|
|
325
|
+
// support it: an osv result from a compared pull-request run, `new` for
|
|
326
|
+
// introduced (including every finding in a lockfile the comparison was
|
|
327
|
+
// unavailable for) and `unchanged` for present-on-base. A run with no
|
|
328
|
+
// comparison sets no label, and so no state.
|
|
329
|
+
const baseline = finding.details.baseline;
|
|
330
|
+
if (baseline === 'introduced') {
|
|
331
|
+
entry.baselineState = 'new';
|
|
332
|
+
}
|
|
333
|
+
else if (baseline === 'present-on-base') {
|
|
334
|
+
entry.baselineState = 'unchanged';
|
|
335
|
+
}
|
|
323
336
|
// Unconditional. The old code omitted the key when there was nothing
|
|
324
337
|
// honest to say, and one such result makes GitHub reject the whole log.
|
|
325
338
|
entry.locations = withFallbackLocation(locationsFor(finding), fallbackUri);
|
|
@@ -660,7 +673,9 @@ function trustBaseRefusedNotifications(result) {
|
|
|
660
673
|
{
|
|
661
674
|
id: 'conductor/trust-base-refused',
|
|
662
675
|
level: 'error',
|
|
663
|
-
message:
|
|
676
|
+
message: (result.trustBase?.notGiven === true
|
|
677
|
+
? 'this is a pull-request job and no trust base was given, so no rules were read, no gate ran and '
|
|
678
|
+
: `conductor refused the trust base "${result.trustBase?.ref ?? ''}", so no gate ran and `) +
|
|
664
679
|
`NOTHING WAS CHECKED by this run. ${refusal}`,
|
|
665
680
|
details: { ref: result.trustBase?.ref ?? null, reason: refusal },
|
|
666
681
|
},
|
|
@@ -703,17 +718,15 @@ function programRefusedNotifications(result) {
|
|
|
703
718
|
});
|
|
704
719
|
}
|
|
705
720
|
/**
|
|
706
|
-
* The gates the umbrella
|
|
721
|
+
* The gates the umbrella did not hand the trust base to.
|
|
707
722
|
*
|
|
708
723
|
* 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.
|
|
724
|
+
* close call that lands on notification: nothing went wrong with the run.
|
|
725
|
+
* What it says is how much of the pull-request boundary this run actually
|
|
726
|
+
* had, which is a coverage statement. A gate below its pull-request-mode
|
|
727
|
+
* minimum never lands here: it is could-not-run. What is left is an intent
|
|
728
|
+
* gate judging a contract imported for this run from the base, and a
|
|
729
|
+
* product with no pull-request mode at all (none today).
|
|
717
730
|
*/
|
|
718
731
|
function trustBaseWithheldNotifications(result) {
|
|
719
732
|
return result.gates.flatMap((gate) => {
|
|
@@ -724,9 +737,8 @@ function trustBaseWithheldNotifications(result) {
|
|
|
724
737
|
return [
|
|
725
738
|
{
|
|
726
739
|
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}`,
|
|
740
|
+
message: `The ${gate.role} gate (${gate.product}) did NOT run in pull-request mode: it was not ` +
|
|
741
|
+
`handed --trust-base ${gate.trustBase?.ref ?? 'the base ref'}. ${withheld}`,
|
|
730
742
|
details: {
|
|
731
743
|
role: gate.role,
|
|
732
744
|
product: gate.product,
|
|
@@ -811,9 +823,17 @@ function unenforcedNotifications(result) {
|
|
|
811
823
|
// this number answers is "what did the gate say", and the umbrella's
|
|
812
824
|
// own findings are never the gate's answer.
|
|
813
825
|
const blocking = gate.findings.filter((finding) => finding.blocking && finding.product !== UMBRELLA_DRIVER_NAME).length;
|
|
826
|
+
// Through gateExitBlocks, like every other reader of a non-zero child
|
|
827
|
+
// exit: under present-on-base: report an osv exit of 1 can be one that
|
|
828
|
+
// does not block, and saying only "exited 1" there would read as a
|
|
829
|
+
// block the exit code never had.
|
|
830
|
+
const exitBlocks = gateExitBlocks(gate);
|
|
814
831
|
const what = gate.couldNotRun !== null
|
|
815
832
|
? `It could not run (${gate.couldNotRun.reason}), and nothing was checked by it.`
|
|
816
|
-
: `It reported ${blocking} blocking finding(s) and exited ${gate.exitCode ?? -1}
|
|
833
|
+
: `It reported ${blocking} blocking finding(s) and exited ${gate.exitCode ?? -1}` +
|
|
834
|
+
(exitBlocks || gate.baseComparison === undefined
|
|
835
|
+
? '.'
|
|
836
|
+
: ', which does not block here: every finding was already on the base branch, under present-on-base: report.');
|
|
817
837
|
return {
|
|
818
838
|
id: 'conductor/gate-not-enforced',
|
|
819
839
|
message: `The ${gate.role} gate (${gate.product}) has enforce: false, so its verdict did not ` +
|
|
@@ -824,10 +844,30 @@ function unenforcedNotifications(result) {
|
|
|
824
844
|
enforced: false,
|
|
825
845
|
couldNotRun: gate.couldNotRun === null ? null : gate.couldNotRun.reason,
|
|
826
846
|
blockingFindings: blocking,
|
|
847
|
+
exitBlocks,
|
|
827
848
|
},
|
|
828
849
|
};
|
|
829
850
|
});
|
|
830
851
|
}
|
|
852
|
+
/**
|
|
853
|
+
* A gate's run facts for its SARIF run, plus the base comparison when one
|
|
854
|
+
* ran (the vulnerabilities gate on a compared pull-request run): the ref, the
|
|
855
|
+
* two counts and the base policy's present-on-base value. not-scanned is in
|
|
856
|
+
* the gate's own run details already.
|
|
857
|
+
*/
|
|
858
|
+
function runDetails(gate) {
|
|
859
|
+
const comparison = gate.baseComparison;
|
|
860
|
+
if (comparison === undefined) {
|
|
861
|
+
return gate.run.details;
|
|
862
|
+
}
|
|
863
|
+
return {
|
|
864
|
+
...gate.run.details,
|
|
865
|
+
'baseline-ref': comparison.ref,
|
|
866
|
+
introduced: comparison.introduced,
|
|
867
|
+
'present-on-base': comparison.presentOnBase,
|
|
868
|
+
'present-on-base-policy': comparison.policy,
|
|
869
|
+
};
|
|
870
|
+
}
|
|
831
871
|
/**
|
|
832
872
|
* Renders a whole run as one SARIF log.
|
|
833
873
|
*
|
|
@@ -865,7 +905,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
865
905
|
// same bag the text report renders as scalars. Carried verbatim and
|
|
866
906
|
// only when there is something in it, so a gate that reports none of
|
|
867
907
|
// this keeps the properties shape it had before.
|
|
868
|
-
...(Object.keys(gate
|
|
908
|
+
...(Object.keys(runDetails(gate)).length === 0 ? {} : { details: runDetails(gate) }),
|
|
869
909
|
}));
|
|
870
910
|
}
|
|
871
911
|
// Still RESULTS, deliberately, and the asymmetry with the three above is
|
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,14 +43,47 @@ 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
|
|
34
|
-
* nothing-checked exit 0, but no gate ran at
|
|
35
|
-
* or every one deferred,
|
|
82
|
+
* nothing-checked exit 0, but nothing was checked: no gate ran at
|
|
83
|
+
* all (none enabled, or every one deferred,
|
|
84
|
+
* tree-unchanged or skipped), or every gate that
|
|
85
|
+
* ran checked nothing (nothing to scan, or no
|
|
86
|
+
* contract; audit finding F4)
|
|
36
87
|
* advisory-blocked (N) exit 1 that --advisory turned into exit 0
|
|
37
88
|
* unenforced-findings (N) exit 0, but enforce: false gates blocked or
|
|
38
89
|
* could not run
|