@vaultcompass/conductor 0.4.6 → 0.4.7

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
@@ -89,7 +89,7 @@ conductor: clean, nothing blocked. 2 gate(s) ran: dependencies (dep-guard), secr
89
89
  A commit with a staged credential in it prints the full report and exits 1:
90
90
 
91
91
  ```
92
- conductor 0.4.6
92
+ conductor 0.4.7
93
93
  conductor run: 2 gate(s), 1 finding(s)
94
94
 
95
95
  dependencies dep-guard 0.2.1 exit 0 251ms via dep-guard on path
@@ -281,6 +281,15 @@ proceeds normally without mentioning them.
281
281
  leaves out is named as excluded, on one line in the text report and as a
282
282
  `conductor/gate-excluded` notification in the SARIF log's `conductor` run.
283
283
  It never reaches the exit code.
284
+ - `--advisory` maps exit 1 to exit 0: a run whose only failure is a blocking
285
+ finding no longer fails. A gate that could not run is unaffected and still
286
+ exits 2, so a crashed install or a missing policy still shows red rather
287
+ than a silent green: this flag changes what a **finding** does, never what
288
+ a **broken gate** does. The report is unchanged, a blocking finding still
289
+ prints with its `BLOCKING` marker, and only the process exit and the
290
+ verdict line's own wording (it says findings were advisory and did not
291
+ block) change. Text output only; the SARIF log has no verdict line to
292
+ change and its `properties.blocking` on each result is unaffected.
284
293
 
285
294
  ### Exit codes
286
295
 
@@ -291,6 +300,11 @@ proceeds normally without mentioning them.
291
300
  stdout, which is what a rejected config file looks like from two of the
292
301
  three.
293
302
 
303
+ `run --advisory` maps exit 1 to exit 0. It never touches exit 2: a gate that
304
+ could not run is a different failure from a blocking finding, and advisory
305
+ mode exists to leave that one alone. See "Running the gates as an advisory
306
+ check" below.
307
+
294
308
  ## The pull-request trust boundary
295
309
 
296
310
  Every gate reads its own rules out of the repository it is judging. On a pull
@@ -661,7 +675,7 @@ jobs:
661
675
  with:
662
676
  node-version: '22.11.0'
663
677
  - id: conductor
664
- uses: vaultcompasshq/conductor@v0.4.6
678
+ uses: vaultcompasshq/conductor@v0.4.7
665
679
  with:
666
680
  output: conductor.sarif
667
681
  - uses: github/codeql-action/upload-sarif@v3
@@ -710,7 +724,7 @@ jobs:
710
724
  # pinned below.
711
725
  - run: pnpm install --frozen-lockfile
712
726
  - id: conductor
713
- uses: vaultcompasshq/conductor@v0.4.6
727
+ uses: vaultcompasshq/conductor@v0.4.7
714
728
  with:
715
729
  output: conductor.sarif
716
730
  # Exact versions, never a range and never "latest". These four
@@ -721,7 +735,7 @@ jobs:
721
735
  # request of their own. Forward only on a pull request: the action
722
736
  # refuses a pin below what its tag ships, and the four lines can be
723
737
  # left out entirely to take that tag's own versions.
724
- conductor-version: 0.4.6
738
+ conductor-version: 0.4.7
725
739
  dep-guard-version: 0.7.0
726
740
  vault-guard-version: 1.8.0
727
741
  intent-guard-version: 1.5.2
@@ -747,15 +761,22 @@ workflows do.
747
761
 
748
762
  ### Running the gates as an advisory check
749
763
 
750
- To run the gates without blocking a merge, set `continue-on-error: true` on the
751
- `conductor` step and leave the check not required in branch protection. Set a
752
- step `timeout-minutes` as well. `continue-on-error` swallows a failing exit
753
- code, but it does not bound a step that hangs: on a required job a stuck run
754
- still drags the job to its own job-level limit and blocks the very merge the
755
- advisory setting was meant to leave alone. The Action already caps each gate's
756
- own subprocess at 120 seconds and reports a gate that exceeds it as
757
- could-not-run, so a step `timeout-minutes` is an outer bound around the whole
758
- run rather than the primary control.
764
+ To run the gates without blocking a merge, set `advisory: true` on the
765
+ `conductor` step and leave the check not required in branch protection.
766
+ `advisory: true` maps a blocking finding to exit 0, so it never fails this
767
+ run; a gate that **could not run** is unaffected and still exits 2, so a
768
+ crashed install or a missing policy on the base ref still shows red rather
769
+ than a silent green. That distinction is why the recipe below carries no
770
+ `continue-on-error` anywhere: an earlier version of this recipe put
771
+ `continue-on-error: true` on every step, including the umbrella's own, and a
772
+ transient `npm audit signatures` failure then read as nothing wrong for two
773
+ days (issue #36) because the step's exit code was swallowed regardless of
774
+ which of the two reasons produced it. `advisory` fixes the failure that
775
+ caused that; `continue-on-error` is the thing that let it happen, so the two
776
+ do not belong in the same recipe. Set a step `timeout-minutes` as well: the
777
+ Action already caps each gate's own subprocess at 120 seconds and reports one
778
+ that exceeds it as could-not-run, so the timeout is an outer bound around the
779
+ whole run rather than the primary control.
759
780
 
760
781
  A complete copy-paste job, rather than the one step above in isolation:
761
782
 
@@ -771,39 +792,43 @@ jobs:
771
792
  pull-requests: write
772
793
  steps:
773
794
  - uses: actions/checkout@v4
774
- continue-on-error: true
775
795
  with:
776
796
  fetch-depth: 0
777
797
  - uses: actions/setup-node@v4
778
- continue-on-error: true
779
798
  with:
780
799
  node-version: '22.11.0'
781
- - name: Fetch the base ref
782
- continue-on-error: true
783
- run: git fetch origin "$GITHUB_BASE_REF:refs/remotes/origin/$GITHUB_BASE_REF"
784
- env:
785
- GITHUB_BASE_REF: ${{ github.base_ref }}
786
800
  - id: conductor
787
- continue-on-error: true
788
801
  timeout-minutes: 5
789
- uses: vaultcompasshq/conductor@v0.4.6
802
+ uses: vaultcompasshq/conductor@v0.4.7
790
803
  with:
791
804
  pr-comment: true
805
+ advisory: true
792
806
  ```
793
807
 
794
- Every fallible step above, the checkout, the node setup, the explicit fetch,
795
- and the conductor step itself, carries `continue-on-error: true`, because a
796
- required job must never go red over an advisory step that hung or failed.
797
808
  `action.yml` already shallow-fetches the trust base itself as of 0.4.5 when
798
809
  the checkout does not already carry it (see the changelog entry for that
799
- version), so the explicit "Fetch the base ref" step above is belt and
800
- braces, not a requirement; it is here so the recipe still resolves the base
801
- ref on an action version that predates that self-fetch. `pr-comment: true`
802
- is what makes the advisory finding visible at all: a `pull_request` check
803
- that is not required posts nothing anywhere else a developer would look, so
804
- without it the run's only trace is a green-looking step nobody opens. See
805
- "The report as a pull request comment" below for what that input needs and
806
- what it does on a fork.
810
+ version), so this recipe needs no separate "fetch the base ref" step. None of
811
+ the three steps above swallows its own exit code: a checkout or setup-node
812
+ failure is an infrastructure problem this recipe should still surface, and
813
+ the `conductor` step's own advisory behaviour comes from `advisory: true`
814
+ rather than from hiding a failing step, for the reason above. `pr-comment:
815
+ true` is what makes the advisory finding visible at all: a `pull_request`
816
+ check that is not required posts nothing anywhere else a developer would
817
+ look, so without it the run's only trace is a step that exited 0 and nobody
818
+ opens. See "The report as a pull request comment" below for what that input
819
+ needs and what it does on a fork.
820
+
821
+ `advisory` changes the umbrella's own process exit code only: it does not
822
+ reach the SARIF log, so a GitHub Code Scanning tab shows the same results and
823
+ the same alerts either way, and Code Scanning's own merge protection can
824
+ still block on them regardless of what this step's exit code says. `advisory`
825
+ is also an input on the `conductor` step, which means it is read from the
826
+ pull request's own workflow file on a same-repo `pull_request` event, the
827
+ same as every other input this Action takes; that gives a pull request
828
+ author nothing they could not already do by editing the workflow to add
829
+ `continue-on-error` themselves, and the control for that, as for any workflow
830
+ edit, is branch protection requiring review on `.github/workflows`, not
831
+ anything in `action.yml`.
807
832
 
808
833
  ### Adopting conductor
809
834
 
@@ -816,11 +841,15 @@ steps rather than being surprised by one:
816
841
  inside the trust boundary, so it reads the policy you just wrote. This is
817
842
  where you tune thresholds, not on a pull request.
818
843
  2. Open the pull request with `.guardrails.yaml` and the workflow together,
819
- and set `continue-on-error: true` on the conductor step for it. The step
820
- is inert on this pull request: the base branch has no policy yet, so the
821
- run has no rules, exits 2, and posts a comment saying so with the remedy
822
- on it. That is the honest report of an unfinished adoption, not a broken
823
- tool.
844
+ and set `advisory: true` on the conductor step, the same as the advisory
845
+ recipe above, and leave the check not required in branch protection for
846
+ this one pull request. The step still exits 2 on this pull request even
847
+ with `advisory: true`: the base branch has no policy yet, so the run has
848
+ no rules, and `advisory` never touches that exit code, only a blocking
849
+ finding's. Leaving the check unrequired is what keeps that expected exit 2
850
+ from blocking the merge; the step posts a comment saying so with the
851
+ remedy on it, which is the honest report of an unfinished adoption, not a
852
+ broken tool.
824
853
  3. Merge. Every pull request after that is judged by the policy on the base
825
854
  branch, and a change to that policy shows up as a proposal line and takes
826
855
  effect after its own merge.
@@ -846,7 +875,7 @@ step and add `pull-requests: write` to the job's `permissions`:
846
875
  steps:
847
876
  # ... checkout, pnpm, setup-node, install, as in the example above ...
848
877
  - id: conductor
849
- uses: vaultcompasshq/conductor@v0.4.6
878
+ uses: vaultcompasshq/conductor@v0.4.7
850
879
  with:
851
880
  output: conductor.sarif
852
881
  pr-comment: true
@@ -898,12 +927,12 @@ per pull request.
898
927
 
899
928
  ```yaml
900
929
  - id: conductor-package-a
901
- uses: vaultcompasshq/conductor@v0.4.6
930
+ uses: vaultcompasshq/conductor@v0.4.7
902
931
  with:
903
932
  pr-comment: true
904
933
  pr-comment-marker: 'package-a'
905
934
  - id: conductor-package-b
906
- uses: vaultcompasshq/conductor@v0.4.6
935
+ uses: vaultcompasshq/conductor@v0.4.7
907
936
  with:
908
937
  pr-comment: true
909
938
  pr-comment-marker: 'package-b'
@@ -976,13 +1005,17 @@ came from, so a pull request that plants one gets a clean comment beside a
976
1005
  SARIF log that refused it.
977
1006
 
978
1007
  **Mirror whatever you gave the Action**, or the two runs can report different
979
- contracts. The step above matches the example, which passes neither
980
- `base-ref`, `trust-base` nor `spec`, so both runs read `GITHUB_BASE_REF` and
981
- the `Spec:` line out of the job environment themselves and land on the same
982
- contract and the same ref. If you set any of those inputs on the gates step,
983
- pass the same values here as `--base`, `--trust-base` and `--spec`; if you do
984
- not, the comment is a report of a contract source, or of a boundary, the
985
- uploaded log never used.
1008
+ contracts, or different verdicts. The step above matches the example, which
1009
+ passes neither `base-ref`, `trust-base`, `spec` nor `advisory`, so both runs
1010
+ read `GITHUB_BASE_REF` and the `Spec:` line out of the job environment
1011
+ themselves and land on the same contract and the same ref, and neither one
1012
+ maps a blocking finding to exit 0. If you set any of those inputs on the
1013
+ gates step, pass the same values here: `--base`, `--trust-base` and `--spec`
1014
+ for the first three, and `--advisory` if you set `advisory: true`. Missing
1015
+ one of the first three means the comment is a report of a contract source,
1016
+ or of a boundary, the uploaded log never used; missing `--advisory` means the
1017
+ comment's own verdict line reads "exit 1" underneath a gates step that just
1018
+ exited 0, which is confusing in the opposite direction from silence.
986
1019
 
987
1020
  **On a pull request from a fork the token is read-only**, so `gh pr comment`
988
1021
  fails, `continue-on-error` swallows the failure, and no comment appears on
package/dist/cli.js CHANGED
@@ -10,7 +10,7 @@ import { execFileSync } from 'node:child_process';
10
10
  import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
11
11
  import path from 'node:path';
12
12
  import { fileURLToPath } from 'node:url';
13
- import { EXIT_COULD_NOT_RUN } from './exit-codes.js';
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
16
  import { renderText } from './output-text.js';
@@ -65,6 +65,27 @@ function repoRoot(cwd) {
65
65
  throw new Error(`git could not be run to find the repository root: ${err.message}`);
66
66
  }
67
67
  }
68
+ /**
69
+ * The process exit code for a run, with --advisory applied.
70
+ *
71
+ * ONE PLACE, so the mapping cannot drift from what the verdict line claims:
72
+ * this reads the same `result.exitCode` that `renderText`'s own `advisory`
73
+ * option reads, and the two are always passed the same boolean from the same
74
+ * call site below.
75
+ *
76
+ * ONLY EXIT_BLOCKED (1) IS EVER REMAPPED, and only to EXIT_OK (0). A gate
77
+ * that could not run (2) is left exactly alone: "advisory" means a finding
78
+ * does not block, never that the umbrella cannot fail. Swallowing a
79
+ * could-not-run exit is the precise failure this flag exists to close (a
80
+ * crashed `npm audit signatures` read as nothing wrong for two days,
81
+ * issue #36, because every step carried `continue-on-error` instead of a
82
+ * flag that only ever touches a FINDING's verdict). Any other code -- there
83
+ * is none today besides 0, 1 and 2, but a future one would land here too --
84
+ * passes through unchanged for the same reason.
85
+ */
86
+ function applyAdvisory(exitCode, advisory) {
87
+ return advisory && exitCode === EXIT_BLOCKED ? EXIT_OK : exitCode;
88
+ }
68
89
  /**
69
90
  * Reads the policy for one run, from the base ref in pull-request mode.
70
91
  *
@@ -286,6 +307,7 @@ export function buildProgram() {
286
307
  .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.')
287
308
  .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.')
288
309
  .option('--gate <role>', 'restrict the run to this role; repeatable', (value, previous = []) => [...previous, value])
310
+ .option('--advisory', 'maps exit 1 (every enabled gate ran and at least one blocked) to exit 0, so a blocking finding never fails this run. A gate that could not run is unaffected and still exits 2: advisory changes what a FINDING does, never what a broken gate does. The report is unchanged and a blocking finding still prints as BLOCKING; only the process exit code and the verdict line, which says findings were advisory, are different.')
289
311
  .exitOverride()
290
312
  .action((options) => {
291
313
  const cwd = process.cwd();
@@ -317,12 +339,18 @@ export function buildProgram() {
317
339
  ...(options.spec === undefined ? {} : { spec: options.spec }),
318
340
  ...(source.trustBase === undefined ? {} : { trustBase: source.trustBase }),
319
341
  });
342
+ const advisory = Boolean(options.advisory);
343
+ // SARIF carries no verdict line, so --advisory has nothing to say
344
+ // there: each finding's `properties.blocking` is the gate's own
345
+ // decision (see output-sarif.ts) and is unaffected by this flag,
346
+ // exactly as the text report's per-finding BLOCKING marker is.
320
347
  const rendered = format === 'sarif'
321
348
  ? `${renderSarif(result, pkg.version)}\n`
322
349
  : renderText(result, {
323
350
  verbose: Boolean(options.verbose),
324
351
  version: pkg.version,
325
352
  compact: Boolean(options.compactOnRefusal),
353
+ advisory,
326
354
  });
327
355
  if (options.output === undefined) {
328
356
  process.stdout.write(rendered);
@@ -339,7 +367,7 @@ export function buildProgram() {
339
367
  process.stdout.write(`conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s); ` +
340
368
  `${format} report written to ${options.output}\n`);
341
369
  }
342
- process.exitCode = result.exitCode;
370
+ process.exitCode = applyAdvisory(result.exitCode, advisory);
343
371
  }
344
372
  catch (err) {
345
373
  // One line, never a stack. runGate is total, so nothing from a gate
@@ -36,5 +36,20 @@ export interface TextOptions {
36
36
  * fires when the trust base was actually refused, whatever --verbose says.
37
37
  */
38
38
  compact?: boolean;
39
+ /**
40
+ * Maps an EXIT_BLOCKED verdict to exit 0 in the printed verdict line, and
41
+ * says so in words. This never touches the RunResult passed in: the exit
42
+ * code composed for this run (`result.exitCode`) is unchanged, and so is
43
+ * every finding's own `blocking` marker in the sections above the verdict.
44
+ * `cli.ts` is what actually maps the PROCESS exit code, from the same
45
+ * `result.exitCode` this option reads; this flag exists so the one line a
46
+ * reader is most likely to read alone does not contradict the exit code
47
+ * the process is about to produce.
48
+ *
49
+ * Has no effect on any other verdict shape: a could-not-run run (exit 2)
50
+ * reads the same whatever this says, because advisory is about a finding
51
+ * that did not block, never about a gate that did not run.
52
+ */
53
+ advisory?: boolean;
39
54
  }
40
55
  export declare function renderText(result: RunResult, options?: TextOptions): string;
@@ -338,18 +338,20 @@ function refusalLines(result) {
338
338
  ` ${refusal}`,
339
339
  ];
340
340
  }
341
- function verdict(result) {
341
+ function verdict(result, advisory) {
342
342
  const refusal = result.trustBase?.refusal;
343
343
  if (refusal !== undefined && refusal !== null) {
344
344
  // Written rather than composed, exactly as the exit code is: no gate ran,
345
345
  // so there is nothing for the clauses below to count, and every one of
346
- // them would describe a different run from the one that happened.
346
+ // them would describe a different run from the one that happened. A
347
+ // refusal is a could-not-run outcome (exit 2), which --advisory never
348
+ // touches, so this branch reads advisory or not exactly the same.
347
349
  return (`verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
348
350
  'so no gate ran and nothing here is a result of any kind.');
349
351
  }
350
- return verdictForRun(result);
352
+ return verdictForRun(result, advisory);
351
353
  }
352
- function verdictForRun(result) {
354
+ function verdictForRun(result, advisory) {
353
355
  // Counted over ENFORCED gates only. The exit code came from those alone,
354
356
  // so a count taken over all of them describes a different run from the one
355
357
  // the number at the front of the line is about, and the umbrella's own
@@ -410,16 +412,37 @@ function verdictForRun(result) {
410
412
  // on the one line somebody reads when they read nothing else contradicts
411
413
  // the exit code printed beside it, and sends a reader looking for a
412
414
  // finding that this report deliberately does not claim.
415
+ //
416
+ // ADVISORY ONLY EVER REWRITES THIS ONE BRANCH. The process's own exit
417
+ // code is decided in cli.ts by mapping EXIT_BLOCKED to EXIT_OK when
418
+ // --advisory was given; this function never changes result.exitCode
419
+ // itself, so a could-not-run verdict a few lines up is untouched
420
+ // whatever `advisory` says. The findings above this line still print
421
+ // with their BLOCKING marker: advisory changes what the exit code
422
+ // claims, never what a gate found.
413
423
  if (blocking === 0) {
424
+ // The mismatch branch: composeExitCode also lands here when an
425
+ // enforced gate exited non-zero but nothing reconciled as a blocking
426
+ // finding (conductor/blocking-count-mismatch or
427
+ // conductor/blocking-threshold-unknown; see normalize.ts). "Findings
428
+ // were advisory and did not block" would claim a finding this branch
429
+ // explicitly says there is none of, so it gets its own, narrower
430
+ // wording that is true here and says nothing about findings at all.
414
431
  const names = enforcedGates
415
432
  .filter((gate) => (gate.exitCode ?? 0) !== 0)
416
433
  .map((gate) => `${gate.role} (exit ${gate.exitCode ?? '?'})`)
417
434
  .join(', ');
418
- return (`verdict: exit 1, and no finding here is marked blocking. Enforced gate(s) that exited ` +
435
+ const base = `and no finding here is marked blocking. Enforced gate(s) that exited ` +
419
436
  `non-zero: ${names}. The umbrella could not reconcile a blocking count with what those ` +
420
- `gates reported, so the gate exit code decided the run.${aside}`);
437
+ `gates reported, so the gate exit code decided the run.${aside}`;
438
+ return advisory
439
+ ? `verdict: exit 0, ${base} This run was advisory, so exit 1 became exit 0.`
440
+ : `verdict: exit 1, ${base}`;
421
441
  }
422
- return `verdict: exit 1, ${blocking} blocking finding(s) across ${enforcedGates.length} gate(s).${aside}`;
442
+ const base = `${blocking} blocking finding(s) across ${enforcedGates.length} gate(s).${aside}`;
443
+ return advisory
444
+ ? `verdict: exit 0, ${base} Findings were advisory and did not block, so this run exits 0 rather than 1.`
445
+ : `verdict: exit 1, ${base}`;
423
446
  }
424
447
  // Exit 0 with red on the screen above it. The verdict is the one line
425
448
  // somebody reads when they read nothing else, so it is the line that has
@@ -618,7 +641,11 @@ export function renderText(result, options = {}) {
618
641
  // "conductor init", or reading the pull request's own file as a
619
642
  // proposal) as part of the same sentence. Nothing here points at a step
620
643
  // log: the reason has to be readable on the comment itself.
621
- const lines = [...versionLine(options.version), verdict(result), ...refusal];
644
+ const lines = [
645
+ ...versionLine(options.version),
646
+ verdict(result, Boolean(options.advisory)),
647
+ ...refusal,
648
+ ];
622
649
  return `${lines.join('\n')}\n`;
623
650
  }
624
651
  if (refusal.length === 0 && !options.verbose && isFullyClean(result)) {
@@ -655,6 +682,6 @@ export function renderText(result, options = {}) {
655
682
  if (result.findings.some((finding) => finding.severityIsDerived)) {
656
683
  lines.push('', '* severity assigned by the umbrella; that gate reports no per-finding severity.');
657
684
  }
658
- lines.push('', verdict(result));
685
+ lines.push('', verdict(result, Boolean(options.advisory)));
659
686
  return `${lines.join('\n')}\n`;
660
687
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.4.6",
3
+ "version": "0.4.7",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [