@vaultcompass/conductor 0.6.0 → 0.7.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 +101 -17
- package/dist/cli.js +46 -11
- package/dist/output-text.d.ts +33 -0
- package/dist/output-text.js +80 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -167,7 +167,8 @@ required.
|
|
|
167
167
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
168
168
|
|
|
169
169
|
```
|
|
170
|
-
conductor 0.
|
|
170
|
+
conductor 0.7.0
|
|
171
|
+
verdict-token: blocked (1)
|
|
171
172
|
conductor run: 2 gate(s), 1 finding(s)
|
|
172
173
|
|
|
173
174
|
dependencies dep-guard 0.7.0 exit 0 153ms via dep-guard on path
|
|
@@ -222,7 +223,9 @@ required.
|
|
|
222
223
|
exit code, only a blocking finding's. Leaving the check out of branch
|
|
223
224
|
protection is what keeps that expected exit 2 from blocking the merge;
|
|
224
225
|
the step posts a comment saying so with the remedy on it, which is the
|
|
225
|
-
honest report of an unfinished adoption, not a broken tool.
|
|
226
|
+
honest report of an unfinished adoption, not a broken tool. The same
|
|
227
|
+
refusal recurs once on every new base branch; see "Why the first pull
|
|
228
|
+
request still exits 2 under `advisory: true`" below.
|
|
226
229
|
|
|
227
230
|
3. **Merge.** Every pull request after that is judged by the policy on the
|
|
228
231
|
base branch, and a change to that policy shows up as a proposal line and
|
|
@@ -483,6 +486,15 @@ proceeds normally without mentioning them.
|
|
|
483
486
|
repository root: with `--project` pointing elsewhere, a relative
|
|
484
487
|
`--output` still lands next to where you are, not next to the repository
|
|
485
488
|
being judged.
|
|
489
|
+
- `--text-report <path>`, with `--format sarif`, also writes the text report
|
|
490
|
+
to that file **from the same run**: exactly what `--format text` would have
|
|
491
|
+
rendered for this result (`--verbose`, `--compact-on-refusal` and
|
|
492
|
+
`--advisory` respected), and no gate is run a second time. This is how the
|
|
493
|
+
Action gets a SARIF log, a comment body and a verdict token that are one
|
|
494
|
+
run's answer. With `--format text` it is refused as a usage error (exit 2),
|
|
495
|
+
before any gate runs: the text report is the output already, so a second
|
|
496
|
+
copy in a file would only duplicate it. A path that cannot be written is
|
|
497
|
+
exit 2, like `--output`. See "The verdict token" below.
|
|
486
498
|
- `--verbose` prints the full per-gate report even when the run is clean.
|
|
487
499
|
Text output only; the SARIF log never changes shape with it.
|
|
488
500
|
- `--compact-on-refusal` shrinks the report to the version, the verdict and
|
|
@@ -548,6 +560,37 @@ could not run is a different failure from a blocking finding, and advisory
|
|
|
548
560
|
mode exists to leave that one alone. See "Running the gates as an advisory
|
|
549
561
|
check" below.
|
|
550
562
|
|
|
563
|
+
### The verdict token
|
|
564
|
+
|
|
565
|
+
The text report carries one more line: `verdict-token: <token>`, the **second
|
|
566
|
+
line**, directly under the version line (the closing `verdict:` sentence is
|
|
567
|
+
unchanged). It is a label for the umbrella's own exit decision, in a closed
|
|
568
|
+
set, so a person or a script can read the state without parsing a sentence.
|
|
569
|
+
It decides nothing and never overrules a gate: it is derived from the exit
|
|
570
|
+
code and the `enforce` flags the run already had.
|
|
571
|
+
|
|
572
|
+
- `pass`: exit 0, and no gate, enforced or not, has a blocking finding or
|
|
573
|
+
could not run.
|
|
574
|
+
- `advisory-blocked (N)`: the run would have exited 1, and `--advisory` made
|
|
575
|
+
it exit 0. N is the blocking findings on enforced gates.
|
|
576
|
+
- `unenforced-findings (N)`: exit 0, but a gate with `enforce: false` had
|
|
577
|
+
blocking findings or could not run. N counts those findings plus those
|
|
578
|
+
gates. Exit 0 here is not a pass, and the token says so.
|
|
579
|
+
- `blocked (N)`: exit 1. N as for `advisory-blocked`.
|
|
580
|
+
- `could-not-run`: exit 2, a refused trust base included.
|
|
581
|
+
|
|
582
|
+
When several apply the order is `could-not-run`, then `blocked` or
|
|
583
|
+
`advisory-blocked`, then `unenforced-findings`, then `pass`. A run with
|
|
584
|
+
`--advisory` whose only blocking findings sit on an unenforced gate is
|
|
585
|
+
`unenforced-findings`, not `advisory-blocked`, because the flag did nothing
|
|
586
|
+
there. A gate skipped for want of a contract does not by itself move the token
|
|
587
|
+
off `pass`; the verdict sentence is where "nothing was checked" is said. A
|
|
588
|
+
gate that exited non-zero with no finding marked blocking counts as one in N,
|
|
589
|
+
so a state that is not a pass never prints a count of zero. The one-line
|
|
590
|
+
summary of a clean, non-verbose run has no token line, since it is one line by
|
|
591
|
+
design. `conductor run` also prints the token on its job-log line,
|
|
592
|
+
`conductor run: 4 gate(s), 1 finding(s); verdict-token advisory-blocked (1); sarif report written to conductor.sarif`.
|
|
593
|
+
|
|
551
594
|
## The pull-request trust boundary
|
|
552
595
|
|
|
553
596
|
Every gate reads its own rules out of the repository it is judging. On a pull
|
|
@@ -1046,9 +1089,10 @@ provenance even though all four packages publish it.
|
|
|
1046
1089
|
> points npm at a mirror or proxy that does not (via `actions/setup-node`'s
|
|
1047
1090
|
> `registry-url:`, a corporate `~/.npmrc`, or `npm_config_registry`), the
|
|
1048
1091
|
> install succeeds and this step then fails with `EMISSINGSIGNATUREKEY`. A
|
|
1049
|
-
> sigstore outage has the same effect.
|
|
1050
|
-
>
|
|
1051
|
-
>
|
|
1092
|
+
> sigstore outage has the same effect. The audit is retried once after a short
|
|
1093
|
+
> pause before the step fails, to absorb a one-off registry hiccup. It fails
|
|
1094
|
+
> closed on purpose, so that is a red gate rather than a skipped check; pin to
|
|
1095
|
+
> `@v0.4.0`, which does not verify, if it blocks you.
|
|
1052
1096
|
|
|
1053
1097
|
`--base` is passed only when the `base-ref` input names one; left empty, the
|
|
1054
1098
|
umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
|
|
@@ -1104,7 +1148,7 @@ jobs:
|
|
|
1104
1148
|
with:
|
|
1105
1149
|
node-version: '22.11.0'
|
|
1106
1150
|
- id: conductor
|
|
1107
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1151
|
+
uses: vaultcompasshq/conductor@v0.7.0
|
|
1108
1152
|
with:
|
|
1109
1153
|
output: conductor.sarif
|
|
1110
1154
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1114,6 +1158,14 @@ jobs:
|
|
|
1114
1158
|
sarif_file: ${{ steps.conductor.outputs.sarif }}
|
|
1115
1159
|
```
|
|
1116
1160
|
|
|
1161
|
+
The examples leave the trigger unnarrowed on purpose, so the job runs for a
|
|
1162
|
+
pull request into any branch. If you narrow it with a `branches:` filter,
|
|
1163
|
+
include every branch whose merges reach users, release branches and the
|
|
1164
|
+
production branch included, for instance `branches: [main, 'release/**',
|
|
1165
|
+
production]`. The pull request that promotes a release is where a bad
|
|
1166
|
+
dependency or a leaked secret actually ships, and a job that is not triggered
|
|
1167
|
+
leaves no red check and no report to notice.
|
|
1168
|
+
|
|
1117
1169
|
No version inputs there at all: left out, the four gates run at the versions
|
|
1118
1170
|
this tag ships, which is the intended default. The fully spelled-out example
|
|
1119
1171
|
below adds explicit version pins and comments explaining each one, for a
|
|
@@ -1153,7 +1205,7 @@ jobs:
|
|
|
1153
1205
|
# pinned below.
|
|
1154
1206
|
- run: pnpm install --frozen-lockfile
|
|
1155
1207
|
- id: conductor
|
|
1156
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1208
|
+
uses: vaultcompasshq/conductor@v0.7.0
|
|
1157
1209
|
with:
|
|
1158
1210
|
output: conductor.sarif
|
|
1159
1211
|
# Exact versions, never a range and never "latest". These four
|
|
@@ -1164,7 +1216,7 @@ jobs:
|
|
|
1164
1216
|
# request of their own. Forward only on a pull request: the action
|
|
1165
1217
|
# refuses a pin below what its tag ships, and the four lines can be
|
|
1166
1218
|
# left out entirely to take that tag's own versions.
|
|
1167
|
-
conductor-version: 0.
|
|
1219
|
+
conductor-version: 0.7.0
|
|
1168
1220
|
dep-guard-version: 0.9.0
|
|
1169
1221
|
vault-guard-version: 1.8.0
|
|
1170
1222
|
intent-guard-version: 1.7.0
|
|
@@ -1259,7 +1311,7 @@ jobs:
|
|
|
1259
1311
|
node-version: '22.11.0'
|
|
1260
1312
|
- id: conductor
|
|
1261
1313
|
timeout-minutes: 5
|
|
1262
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1314
|
+
uses: vaultcompasshq/conductor@v0.7.0
|
|
1263
1315
|
with:
|
|
1264
1316
|
pr-comment: true
|
|
1265
1317
|
advisory: true
|
|
@@ -1357,6 +1409,15 @@ for `advisory` to act on. Leaving the check out of branch protection for
|
|
|
1357
1409
|
that one pull request is what keeps the expected exit 2 from blocking the
|
|
1358
1410
|
merge; the step posts a comment naming the ref and the remedy.
|
|
1359
1411
|
|
|
1412
|
+
The same refusal happens once on every new base branch, not only on the
|
|
1413
|
+
default branch, because rules are read from whatever branch the pull request
|
|
1414
|
+
targets. A release or release-candidate branch cut before the policy existed,
|
|
1415
|
+
or any long-lived branch that has never received `.guardrails.yaml`, refuses
|
|
1416
|
+
its first pull request the same way. There are two remedies. Carry the policy
|
|
1417
|
+
onto the branch before opening a pull request against it; a sync from the
|
|
1418
|
+
default branch does this. Or expect exactly one could-not-run run there, and
|
|
1419
|
+
leave the check out of that branch's protection for that one pull request.
|
|
1420
|
+
|
|
1360
1421
|
**Why "go required" means the job's own context, never the SARIF-upload
|
|
1361
1422
|
row.** The recipes above upload conductor's SARIF log with
|
|
1362
1423
|
`github/codeql-action/upload-sarif`, which can add its own code-scanning
|
|
@@ -1383,7 +1444,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1383
1444
|
steps:
|
|
1384
1445
|
# ... checkout, pnpm, setup-node, install, as in the example above ...
|
|
1385
1446
|
- id: conductor
|
|
1386
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1447
|
+
uses: vaultcompasshq/conductor@v0.7.0
|
|
1387
1448
|
with:
|
|
1388
1449
|
output: conductor.sarif
|
|
1389
1450
|
pr-comment: true
|
|
@@ -1391,13 +1452,21 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1391
1452
|
|
|
1392
1453
|
That posts conductor's own text report, the one the README quotes above
|
|
1393
1454
|
("conductor: clean, nothing blocked. 2 gate(s) ran: ..."), as a comment on
|
|
1394
|
-
the pull request. It is **
|
|
1455
|
+
the pull request. It is **the report of the run that decided the job**: the
|
|
1456
|
+
gates step asks that one run for the SARIF log and the text report together
|
|
1457
|
+
(`--text-report`), and the comment step posts the file it wrote without
|
|
1458
|
+
running the gates again. Before this the comment came from a second run, which
|
|
1459
|
+
could disagree with the first whenever a gate's answer was time or network
|
|
1460
|
+
dependent, and doubled the gate time on every pull request. An installed
|
|
1461
|
+
`conductor-version` too old to have `--text-report` is detected by asking the
|
|
1462
|
+
binary, and gets the second-run behaviour it always had, without a token. It is **sticky**: a hidden marker in the comment body lets
|
|
1395
1463
|
a re-run find and update that same comment, so a push does not pile up a new
|
|
1396
1464
|
comment every time, the way the manual recipe below does. It runs on a
|
|
1397
1465
|
`pull_request` or `pull_request_target` event only, and it runs whether the
|
|
1398
1466
|
gates step passed or failed, since a blocking run is the one an advisory
|
|
1399
1467
|
check most needs a developer to actually see. The first line of every
|
|
1400
|
-
comment carries the version of conductor that produced it,
|
|
1468
|
+
comment carries the version of conductor that produced it, the second line
|
|
1469
|
+
carries the verdict token (see "The verdict token" above), and when the
|
|
1401
1470
|
trust base was refused and no gate ran at all, the comment shrinks to the
|
|
1402
1471
|
version, the verdict, and the refusal reason (with its remedy, when one
|
|
1403
1472
|
applies) rather than the full per-gate report, so an adopter with no policy
|
|
@@ -1416,6 +1485,18 @@ add; nothing here does that for you.
|
|
|
1416
1485
|
|
|
1417
1486
|
Off by default, so an existing consumer of this action is unaffected.
|
|
1418
1487
|
|
|
1488
|
+
**The verdict, whether or not the comment is on.** The gates step reads the
|
|
1489
|
+
token out of the text report its own run wrote and publishes it twice: as a
|
|
1490
|
+
line on the job summary, `conductor verdict: advisory-blocked (1)`, and as the
|
|
1491
|
+
Action's `verdict` output, spelled exactly as the report's second line spells
|
|
1492
|
+
it (`steps.conductor.outputs.verdict`). It is flattened to one line before it
|
|
1493
|
+
goes to either. It is a label for conductor's own exit decision, and the
|
|
1494
|
+
step's exit status is conductor's own in every state. When the gate packages
|
|
1495
|
+
could not be verified and no gate ran, the summary says
|
|
1496
|
+
`conductor verdict: could-not-run (<reason>)` and the output is
|
|
1497
|
+
`could-not-run`. The output is empty when the installed `conductor-version`
|
|
1498
|
+
predates the token.
|
|
1499
|
+
|
|
1419
1500
|
**The sticky match only ever adopts conductor's own comment.** On
|
|
1420
1501
|
`pull_request_target` this step runs with a write token even though the
|
|
1421
1502
|
pull request itself is untrusted, so anyone who can comment on the pull
|
|
@@ -1435,12 +1516,12 @@ per pull request.
|
|
|
1435
1516
|
|
|
1436
1517
|
```yaml
|
|
1437
1518
|
- id: conductor-package-a
|
|
1438
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1519
|
+
uses: vaultcompasshq/conductor@v0.7.0
|
|
1439
1520
|
with:
|
|
1440
1521
|
pr-comment: true
|
|
1441
1522
|
pr-comment-marker: 'package-a'
|
|
1442
1523
|
- id: conductor-package-b
|
|
1443
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1524
|
+
uses: vaultcompasshq/conductor@v0.7.0
|
|
1444
1525
|
with:
|
|
1445
1526
|
pr-comment: true
|
|
1446
1527
|
pr-comment-marker: 'package-b'
|
|
@@ -1471,9 +1552,12 @@ case, `pr-comment: true` is the built-in answer.
|
|
|
1471
1552
|
The SARIF upload produces no alerts on a private repository without GitHub
|
|
1472
1553
|
Code Security, which is why that step carries `continue-on-error`. A comment
|
|
1473
1554
|
is free there. Add `pull-requests: write` to the job's `permissions` and this
|
|
1474
|
-
step after the gates. It **runs the gates a second time**, because
|
|
1475
|
-
|
|
1476
|
-
|
|
1555
|
+
step after the gates. It **runs the gates a second time**, because a run has
|
|
1556
|
+
one format and the recipe below asks for text, so the job costs roughly twice
|
|
1557
|
+
the gate time and the comment can in principle disagree with the first run;
|
|
1558
|
+
the built-in `pr-comment: true` does not, since it posts the file the first
|
|
1559
|
+
run wrote (`--text-report`). `--verbose` because a clean run otherwise
|
|
1560
|
+
collapses to one line.
|
|
1477
1561
|
|
|
1478
1562
|
```yaml
|
|
1479
1563
|
- name: Comment the report on the pull request
|
package/dist/cli.js
CHANGED
|
@@ -7,13 +7,13 @@
|
|
|
7
7
|
// decisions be tested without a subprocess.
|
|
8
8
|
import { Command, CommanderError } from 'commander';
|
|
9
9
|
import { execFileSync } from 'node:child_process';
|
|
10
|
-
import { readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
|
|
10
|
+
import { readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
|
|
11
11
|
import path from 'node:path';
|
|
12
12
|
import { fileURLToPath } from 'node:url';
|
|
13
13
|
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
|
|
14
14
|
import { applyInit, planInit, renderInitHuman, renderRevertHuman, revertInit, } from './init.js';
|
|
15
15
|
import { renderSarif } from './output-sarif.js';
|
|
16
|
-
import { jobLogSummary, renderText } from './output-text.js';
|
|
16
|
+
import { jobLogSummary, renderText, verdictToken } from './output-text.js';
|
|
17
17
|
import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
|
|
18
18
|
import { refusedTrustBase, runAll } from './run.js';
|
|
19
19
|
import { headTreeEqualsBase, policyDiffers, readPolicyAtRef, refuseTrustBaseForPullRequest, refuseTrustBaseRef, } from './trust-base.js';
|
|
@@ -435,6 +435,7 @@ export function buildProgram() {
|
|
|
435
435
|
.option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to origin/<GITHUB_BASE_REF> when it is set.')
|
|
436
436
|
.option('--trust-base <ref>', 'pull-request mode: read .guardrails.yaml from this ref instead of from the tree being judged, and pass the same ref to every gate that supports it. A policy change in the pull request is reported as a proposal and never takes effect for the run, so a pull request cannot change the rules it is judged by. In Actions the composite action passes origin/<GITHUB_BASE_REF> on a pull_request event.')
|
|
437
437
|
.option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
|
|
438
|
+
.option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
|
|
438
439
|
.option('--spec <path>', 'the spec the intent gate imports its contract from, outranking a Spec: line in the pull request body and the branch-name convention')
|
|
439
440
|
.option('--verbose', 'print the full per-gate report even when the run is clean. A clean run prints one summary line by default, because a pre-commit hook that prints a screenful on every commit is a hook a team switches off. Text output only; SARIF is unaffected.')
|
|
440
441
|
.option('--compact-on-refusal', 'when the trust base was refused and no gate ran, print a short body instead of the full refusal report: the version, the verdict, and the refusal reason (with its remedy, when one applies), never the full per-gate report. Built for the pull-request-comment step; every other run is unaffected, whatever --verbose says. Text output only; SARIF is unaffected.')
|
|
@@ -444,6 +445,7 @@ export function buildProgram() {
|
|
|
444
445
|
.exitOverride()
|
|
445
446
|
.action((options) => {
|
|
446
447
|
const cwd = process.cwd();
|
|
448
|
+
let textReportPath;
|
|
447
449
|
try {
|
|
448
450
|
// Inside the try, because resolveProjectRoot (like repoRoot before
|
|
449
451
|
// it) reports rather than guesses, and the catch below is what turns
|
|
@@ -459,6 +461,14 @@ export function buildProgram() {
|
|
|
459
461
|
const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF);
|
|
460
462
|
const policy = source.kind === 'policy' ? source.policy : source.inventory;
|
|
461
463
|
const format = parseFormat(options.format ?? policy.report.format);
|
|
464
|
+
// BEFORE ANY GATE RUNS. With --format text the text report already is
|
|
465
|
+
// the run's output, so a second copy of it in a file is not something
|
|
466
|
+
// this option can add: refused as a usage error rather than accepted
|
|
467
|
+
// and ignored, which would leave a caller reading a file that was
|
|
468
|
+
// never written, or one that duplicates stdout.
|
|
469
|
+
if (options.textReport !== undefined && format !== 'sarif') {
|
|
470
|
+
throw new PolicyError('--text-report is only meaningful with --format sarif: with --format text the text report is the output already.');
|
|
471
|
+
}
|
|
462
472
|
const result = source.kind === 'refused'
|
|
463
473
|
? refusedTrustBase(source.inventory, source.ref, source.detail, {
|
|
464
474
|
...(stage === undefined ? {} : { stage }),
|
|
@@ -478,14 +488,16 @@ export function buildProgram() {
|
|
|
478
488
|
// there: each finding's `properties.blocking` is the gate's own
|
|
479
489
|
// decision (see output-sarif.ts) and is unaffected by this flag,
|
|
480
490
|
// exactly as the text report's per-finding BLOCKING marker is.
|
|
481
|
-
const
|
|
482
|
-
|
|
483
|
-
:
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
491
|
+
const renderTextReport = () => renderText(result, {
|
|
492
|
+
verbose: Boolean(options.verbose),
|
|
493
|
+
version: pkg.version,
|
|
494
|
+
compact: Boolean(options.compactOnRefusal),
|
|
495
|
+
advisory,
|
|
496
|
+
});
|
|
497
|
+
const rendered = format === 'sarif' ? `${renderSarif(result, pkg.version)}\n` : renderTextReport();
|
|
498
|
+
// The SAME result, rendered a second time, never a second run: the
|
|
499
|
+
// token in this file is for the run that set the exit code below.
|
|
500
|
+
const textReport = options.textReport === undefined ? undefined : renderTextReport();
|
|
489
501
|
if (options.output === undefined) {
|
|
490
502
|
process.stdout.write(rendered);
|
|
491
503
|
}
|
|
@@ -496,6 +508,18 @@ export function buildProgram() {
|
|
|
496
508
|
// worst of the available answers: the upload step downstream would
|
|
497
509
|
// fail on a missing file with no explanation here.
|
|
498
510
|
writeFileSync(options.output, rendered);
|
|
511
|
+
}
|
|
512
|
+
// WRITTEN LAST, after the SARIF log or stdout, and removed again in
|
|
513
|
+
// the catch below if anything after it throws. A run that exits 2
|
|
514
|
+
// because a write failed must never leave a finished text report on
|
|
515
|
+
// disk: the action would read a clean report and publish a pass, and
|
|
516
|
+
// post it as a comment, beside a red job. A text report that cannot
|
|
517
|
+
// be written takes the could-not-run code, like an unwritable --output.
|
|
518
|
+
if (options.textReport !== undefined && textReport !== undefined) {
|
|
519
|
+
textReportPath = options.textReport;
|
|
520
|
+
writeFileSync(options.textReport, textReport);
|
|
521
|
+
}
|
|
522
|
+
if (options.output !== undefined) {
|
|
499
523
|
// One line, so a CI job whose only product is an uploaded artifact
|
|
500
524
|
// does not read as a job that did nothing. jobLogSummary carries
|
|
501
525
|
// its own "N gate(s), N finding(s)" on an ordinary run, unchanged,
|
|
@@ -504,11 +528,22 @@ export function buildProgram() {
|
|
|
504
528
|
// outcome per enabled gate, so the plain count used to read as
|
|
505
529
|
// "N gate(s), N finding(s)" on a run where nothing ran and nothing
|
|
506
530
|
// was found (issue #46).
|
|
507
|
-
process.stdout.write(`conductor run: ${jobLogSummary(result)}; ${
|
|
531
|
+
process.stdout.write(`conductor run: ${jobLogSummary(result)}; verdict-token ${verdictToken(result, advisory)}; ` +
|
|
532
|
+
`${format} report written to ${options.output}\n`);
|
|
508
533
|
}
|
|
509
534
|
process.exitCode = applyAdvisory(result.exitCode, advisory);
|
|
510
535
|
}
|
|
511
536
|
catch (err) {
|
|
537
|
+
// A text report this run already wrote (or half wrote) is removed:
|
|
538
|
+
// this run exits 2, and no report may say otherwise.
|
|
539
|
+
if (textReportPath !== undefined) {
|
|
540
|
+
try {
|
|
541
|
+
unlinkSync(textReportPath);
|
|
542
|
+
}
|
|
543
|
+
catch {
|
|
544
|
+
// Nothing to remove, or not removable; the exit code stands.
|
|
545
|
+
}
|
|
546
|
+
}
|
|
512
547
|
// One line, never a stack. runGate is total, so nothing from a gate
|
|
513
548
|
// reaches here; anything that does is the umbrella's own problem and
|
|
514
549
|
// still must not put a local filesystem path in front of a user who
|
package/dist/output-text.d.ts
CHANGED
|
@@ -25,6 +25,39 @@ 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
|
+
* advisory-blocked (N) exit 1 that --advisory turned into exit 0
|
|
35
|
+
* unenforced-findings (N) exit 0, but enforce: false gates blocked or
|
|
36
|
+
* could not run
|
|
37
|
+
* blocked (N) exit 1
|
|
38
|
+
* could-not-run exit 2, a refused trust base included
|
|
39
|
+
*
|
|
40
|
+
* PRECEDENCE, when several apply: could-not-run, then blocked or
|
|
41
|
+
* advisory-blocked, then unenforced-findings, then pass. So an advisory run
|
|
42
|
+
* whose only blocking findings sit on an unenforced gate is
|
|
43
|
+
* unenforced-findings and never advisory-blocked: --advisory did nothing
|
|
44
|
+
* there, and saying it did would be a false statement of what was hidden.
|
|
45
|
+
*
|
|
46
|
+
* This decides nothing. Every branch reads the exit code composeExitCode
|
|
47
|
+
* already produced (result.exitCode) and the enforce flags already on the
|
|
48
|
+
* gates; the only counting is over what those gates said. It never
|
|
49
|
+
* overrules a gate. It is also the same `advisory` boolean cli.ts hands to
|
|
50
|
+
* applyAdvisory, so the label and the process exit code cannot disagree.
|
|
51
|
+
*
|
|
52
|
+
* A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
|
|
53
|
+
* 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. The verdict sentence is
|
|
55
|
+
* where "nothing was checked" is said.
|
|
56
|
+
*
|
|
57
|
+
* Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
|
|
58
|
+
* not a pass.
|
|
59
|
+
*/
|
|
60
|
+
export declare function verdictToken(result: RunResult, advisory: boolean): string;
|
|
28
61
|
export interface TextOptions {
|
|
29
62
|
/**
|
|
30
63
|
* Print the full report even when the run is fully clean.
|
package/dist/output-text.js
CHANGED
|
@@ -382,6 +382,72 @@ 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
|
+
* advisory-blocked (N) exit 1 that --advisory turned into exit 0
|
|
409
|
+
* unenforced-findings (N) exit 0, but enforce: false gates blocked or
|
|
410
|
+
* could not run
|
|
411
|
+
* blocked (N) exit 1
|
|
412
|
+
* could-not-run exit 2, a refused trust base included
|
|
413
|
+
*
|
|
414
|
+
* PRECEDENCE, when several apply: could-not-run, then blocked or
|
|
415
|
+
* advisory-blocked, then unenforced-findings, then pass. So an advisory run
|
|
416
|
+
* whose only blocking findings sit on an unenforced gate is
|
|
417
|
+
* unenforced-findings and never advisory-blocked: --advisory did nothing
|
|
418
|
+
* there, and saying it did would be a false statement of what was hidden.
|
|
419
|
+
*
|
|
420
|
+
* This decides nothing. Every branch reads the exit code composeExitCode
|
|
421
|
+
* already produced (result.exitCode) and the enforce flags already on the
|
|
422
|
+
* gates; the only counting is over what those gates said. It never
|
|
423
|
+
* overrules a gate. It is also the same `advisory` boolean cli.ts hands to
|
|
424
|
+
* applyAdvisory, so the label and the process exit code cannot disagree.
|
|
425
|
+
*
|
|
426
|
+
* A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
|
|
427
|
+
* 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. The verdict sentence is
|
|
429
|
+
* where "nothing was checked" is said.
|
|
430
|
+
*
|
|
431
|
+
* Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
|
|
432
|
+
* not a pass.
|
|
433
|
+
*/
|
|
434
|
+
export function verdictToken(result, advisory) {
|
|
435
|
+
const refusal = result.trustBase?.refusal;
|
|
436
|
+
const refused = refusal !== undefined && refusal !== null;
|
|
437
|
+
if (refused || (result.exitCode !== 0 && result.exitCode !== EXIT_BLOCKED)) {
|
|
438
|
+
return 'could-not-run';
|
|
439
|
+
}
|
|
440
|
+
if (result.exitCode === EXIT_BLOCKED) {
|
|
441
|
+
const count = result.gates
|
|
442
|
+
.filter((gate) => gate.enforce)
|
|
443
|
+
.reduce((total, gate) => total + blockingCount(gate), 0);
|
|
444
|
+
return advisory ? `advisory-blocked (${count})` : `blocked (${count})`;
|
|
445
|
+
}
|
|
446
|
+
const unenforced = result.gates
|
|
447
|
+
.filter((gate) => !gate.enforce)
|
|
448
|
+
.reduce((total, gate) => total + (gate.couldNotRun !== null ? 1 : blockingCount(gate)), 0);
|
|
449
|
+
return unenforced > 0 ? `unenforced-findings (${unenforced})` : 'pass';
|
|
450
|
+
}
|
|
385
451
|
function verdict(result, advisory) {
|
|
386
452
|
const refusal = result.trustBase?.refusal;
|
|
387
453
|
if (refusal !== undefined && refusal !== null) {
|
|
@@ -698,6 +764,18 @@ function summaryLine(result) {
|
|
|
698
764
|
function versionLine(version) {
|
|
699
765
|
return version === undefined ? [] : [`conductor ${version}`];
|
|
700
766
|
}
|
|
767
|
+
/**
|
|
768
|
+
* The version line, then the verdict-token line directly under it: the first
|
|
769
|
+
* two lines of every report that carries a token. Without a version the
|
|
770
|
+
* token is the first line. The closing verdict sentence is a separate thing
|
|
771
|
+
* and stays where it was.
|
|
772
|
+
*/
|
|
773
|
+
function headerLines(result, options) {
|
|
774
|
+
return [
|
|
775
|
+
...versionLine(options.version),
|
|
776
|
+
`verdict-token: ${verdictToken(result, Boolean(options.advisory))}`,
|
|
777
|
+
];
|
|
778
|
+
}
|
|
701
779
|
export function renderText(result, options = {}) {
|
|
702
780
|
const refusal = refusalLines(result);
|
|
703
781
|
if (options.compact === true && refusal.length > 0) {
|
|
@@ -708,7 +786,7 @@ export function renderText(result, options = {}) {
|
|
|
708
786
|
// proposal) as part of the same sentence. Nothing here points at a step
|
|
709
787
|
// log: the reason has to be readable on the comment itself.
|
|
710
788
|
const lines = [
|
|
711
|
-
...
|
|
789
|
+
...headerLines(result, options),
|
|
712
790
|
verdict(result, Boolean(options.advisory)),
|
|
713
791
|
...refusal,
|
|
714
792
|
];
|
|
@@ -726,7 +804,7 @@ export function renderText(result, options = {}) {
|
|
|
726
804
|
// different questions, so two numbers, and the section headers and the
|
|
727
805
|
// "not enforced" lines are what connect them.
|
|
728
806
|
const lines = [
|
|
729
|
-
...
|
|
807
|
+
...headerLines(result, options),
|
|
730
808
|
...refusal,
|
|
731
809
|
...(refusal.length === 0 ? [] : ['']),
|
|
732
810
|
`conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
|