@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 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.6.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. It fails closed on purpose, so that is a
1050
- > red gate rather than a skipped check; pin to `@v0.4.0`, which does not
1051
- > verify, if it blocks you.
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.6.0
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.6.0
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.6.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.6.0
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.6.0
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 **sticky**: a hidden marker in the comment body lets
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, and when the
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.6.0
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.6.0
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 the Action
1475
- writes SARIF and nothing else, so the job costs roughly twice the gate time;
1476
- `--verbose` because a clean run otherwise collapses to one line.
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 rendered = format === 'sarif'
482
- ? `${renderSarif(result, pkg.version)}\n`
483
- : renderText(result, {
484
- verbose: Boolean(options.verbose),
485
- version: pkg.version,
486
- compact: Boolean(options.compactOnRefusal),
487
- advisory,
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)}; ${format} report written to ${options.output}\n`);
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
@@ -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.
@@ -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
- ...versionLine(options.version),
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
- ...versionLine(options.version),
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)`,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [