@vaultcompass/conductor 0.4.0 → 0.4.6

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,6 +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
93
  conductor run: 2 gate(s), 1 finding(s)
93
94
 
94
95
  dependencies dep-guard 0.2.1 exit 0 251ms via dep-guard on path
@@ -270,6 +271,12 @@ proceeds normally without mentioning them.
270
271
  report nobody can read.
271
272
  - `--verbose` prints the full per-gate report even when the run is clean.
272
273
  Text output only; the SARIF log never changes shape with it.
274
+ - `--compact-on-refusal` shrinks the report to the version, the verdict and
275
+ the refusal reason when the trust base was refused and no gate ran,
276
+ instead of the full per-gate report. Built for the pull-request-comment
277
+ step. It has no effect on a run that was not refused, whatever `--verbose`
278
+ says. Text output only; it has no effect on the SARIF log and never
279
+ changes the exit code.
273
280
  - `--gate <role>`, repeatable. A gate the policy file enables and this flag
274
281
  leaves out is named as excluded, on one line in the text report and as a
275
282
  `conductor/gate-excluded` notification in the SARIF log's `conductor` run.
@@ -328,10 +335,27 @@ and your pre-commit hook still run the pin, which is what `pnpm exec` does in
328
335
  the same repository.
329
336
 
330
337
  **The versions that judge a pull request are pinned in the workflow file**,
331
- which on a `pull_request` event is read from the base branch. That is the
332
- protected side, and it is the point: the pull request can change its own
333
- lockfile, and cannot change the pin that decides which conductor and which
334
- gates run over it.
338
+ and that is the point: the pull request can change its own lockfile,
339
+ manifest and `node_modules`, and none of those decide which conductor and
340
+ which gates run over it any more. Be clear about what that does not cover.
341
+ On a `pull_request` event GitHub runs the workflow as it is in the pull
342
+ request's merge commit, so a pull request that edits the workflow file can
343
+ change the pins or remove the gates step, exactly as it could rewrite any
344
+ other step in your CI. The boundary here is against the tree choosing its
345
+ own judge; the control for a workflow edit is branch protection on your
346
+ base branch with review required for `.github/workflows`, and no action can
347
+ provide that for you. Only `pull_request_target` runs the base branch's copy
348
+ of a workflow, and that event exposes the base's secrets to the pull
349
+ request's code, which is the wrong trade for a gate over untrusted changes.
350
+
351
+ One part of that is closed, and only one. Because the pins are written in a
352
+ file the pull request controls, a pull request could otherwise pin a gate
353
+ **backward** to a published version that predates the rule which would have
354
+ caught it: an exact version, so the validate step's shape check accepts it,
355
+ and a change that reads as ordinary version management. **On a pull request
356
+ the action now refuses any of the four `*-version` inputs naming a version
357
+ below the one the action tag ships.** Pinning forward is still accepted.
358
+ See "The Action" below.
335
359
 
336
360
  So on a pull-request run a gate's program must be **outside the working tree**
337
361
  (on PATH, or an absolute `command:` elsewhere on the machine), or else meet
@@ -407,6 +431,12 @@ judged while still reporting pull-request mode as on. Pass the base
407
431
  commit, which is HEAD. If the base branch has no `.guardrails.yaml` at all,
408
432
  the run has no rules and exits 2 rather than using the pull request's; the
409
433
  file the pull request adds decides what runs once it is on the base branch.
434
+ That is why adopting conductor takes one merge before the gates can judge
435
+ anything, and it is not an oversight: the policy file can name a program to
436
+ run, so a run that read it from the pull request would let the pull request
437
+ choose its own judge on exactly the repositories that have no rules yet. See
438
+ "Adopting conductor" below for the sequence and for how to see what your
439
+ policy will do before you merge it.
410
440
 
411
441
  **Which gates are covered.** All three: dep-guard from **0.6.0**,
412
442
  intent-guard from **1.4.0**, vault-guard from **1.7.0**.
@@ -532,11 +562,58 @@ defaulting to the version this release pins. A validate step refuses anything
532
562
  that is not an exact version, a range and `latest` included: the version that
533
563
  judges a pull request has to be a decision taken on the base branch rather
534
564
  than one the registry takes on the morning of the run. An install step then
535
- runs `npm install -g` under the runner temp, never into the workspace, and
536
- prepends that bin directory to `PATH`, so the run step invokes `conductor` off
537
- `PATH` and each gate resolves by name the same way. The install is
538
- **unconditional**, on push and `pull_request` alike, so there is one code path
539
- rather than one that matters and one that nobody exercises.
565
+ runs `npm install -g --ignore-scripts` under the runner temp, never into the
566
+ workspace, and prepends that bin directory to `PATH`, so the run step invokes
567
+ `conductor` off `PATH` and each gate resolves by name the same way. The install
568
+ is **unconditional**, on push and `pull_request` alike, so there is one code
569
+ path rather than one that matters and one that nobody exercises.
570
+
571
+ **On a pull request those four inputs may not pin backward.** The shape check
572
+ asks whether an input is an exact version; it says nothing about which one, and
573
+ on a `pull_request` event the workflow file comes from the head, so the pins are
574
+ written by the pull request being judged. Once a gate has two published versions
575
+ that is a bypass with an innocent shape: pin back to the release that predates
576
+ the rule which would have caught the change, and the change picks the rules it
577
+ is judged by. So where `GITHUB_BASE_REF` is set, the validate step refuses an
578
+ input naming a version below the one the action tag ships, naming both numbers,
579
+ and the fix is to **remove the input**: the default is that version. Pinning
580
+ **forward** is still accepted, on an assumption the rule does not enforce, that
581
+ a newer gate is at least as strict; nothing bounds how far forward you pin.
582
+
583
+ Three things follow from that, stated because the summary is wider than the rule.
584
+ It fires on fork pull requests too, where the base repository's workflow file is
585
+ the one that runs, so a deliberate backward pin you wrote yourself will refuse
586
+ every fork run until you remove it. Push runs are out of scope rather than safe:
587
+ a push to an unprotected branch runs that branch's own workflow file, written by
588
+ the same author. And `merge_group` runs are not covered at all: `GITHUB_BASE_REF`
589
+ is set on `pull_request` and `pull_request_target` only, so it is empty in a
590
+ merge queue even though the queue branch carries the pull request's commits and
591
+ its workflow file. If your only required check runs on `merge_group`, this rule
592
+ does nothing for you; keep the `pull_request` run required as well and the pin is
593
+ caught before the queue. Neither this nor anything else in `action.yml`
594
+ replaces branch protection with review required for `.github/workflows`, which
595
+ is still the only control over a pull request that edits the workflow.
596
+
597
+ `--ignore-scripts` is there because the step holds the job's token and the four
598
+ things it installs decide whether a pull request may merge; without it every
599
+ package in the resolved tree would run code on the runner. The step then runs
600
+ `npm audit signatures` over what it installed.
601
+
602
+ **What that verification proves, and what it does not.** It asks the registry
603
+ for each name and version in the tree, the four gates included, and checks the
604
+ signature served back, so an unpublished, replaced or unsigned package fails the
605
+ step. It does **not** read the installed files, so it will not detect a tampered
606
+ install; it does **not** defeat a compromised registry, which signs what it
607
+ serves; and a **missing** attestation is not a failure, so it does not require
608
+ provenance even though all four packages publish it.
609
+
610
+ > **This step needs a registry that serves `/-/npm/v1/keys`.** If your runner
611
+ > points npm at a mirror or proxy that does not (via `actions/setup-node`'s
612
+ > `registry-url:`, a corporate `~/.npmrc`, or `npm_config_registry`), the
613
+ > install succeeds and this step then fails with `EMISSINGSIGNATUREKEY`. A
614
+ > sigstore outage has the same effect. It fails closed on purpose, so that is a
615
+ > red gate rather than a skipped check; pin to `@v0.4.0`, which does not
616
+ > verify, if it blocks you.
540
617
 
541
618
  `--base` is passed only when the `base-ref` input names one; left empty, the
542
619
  umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
@@ -557,6 +634,49 @@ event the workflow file itself runs from the pull request's own ref, so an
557
634
  opt-out here would be settable by the very pull request the mode exists to
558
635
  judge: the knob and the thing it protects against would be the same file.
559
636
 
637
+ **The normal way to use this is by tag, not by path.** `uses: ./` reads
638
+ `action.yml` out of whichever tree the workflow runs against, which is
639
+ correct only for this repository's own workflows testing themselves; on a
640
+ pull request from anywhere else it would read `action.yml` out of the pull
641
+ request being judged, and the version-pin protection described above
642
+ "protects nothing" against a tree that controls its own judge (the
643
+ validate step's own comment in `action.yml` says so in those words). Name
644
+ this action by owner and tag instead:
645
+
646
+ ```yaml
647
+ name: guardrails
648
+ on: pull_request
649
+
650
+ jobs:
651
+ gates:
652
+ runs-on: ubuntu-latest
653
+ permissions:
654
+ contents: read
655
+ security-events: write
656
+ steps:
657
+ - uses: actions/checkout@v4
658
+ with:
659
+ fetch-depth: 0
660
+ - uses: actions/setup-node@v4
661
+ with:
662
+ node-version: '22.11.0'
663
+ - id: conductor
664
+ uses: vaultcompasshq/conductor@v0.4.6
665
+ with:
666
+ output: conductor.sarif
667
+ - uses: github/codeql-action/upload-sarif@v3
668
+ if: always()
669
+ continue-on-error: true
670
+ with:
671
+ sarif_file: ${{ steps.conductor.outputs.sarif }}
672
+ ```
673
+
674
+ No version inputs there at all: left out, the four gates run at the versions
675
+ this tag ships, which is the intended default. The fully spelled-out example
676
+ below adds explicit version pins and comments explaining each one, for a
677
+ workflow that wants that transparency; the four lines can still be left out
678
+ entirely to take the tag's own versions, exactly as the form above does.
679
+
560
680
  ```yaml
561
681
  name: guardrails
562
682
  on: pull_request
@@ -579,26 +699,32 @@ jobs:
579
699
  - uses: pnpm/action-setup@v4
580
700
  - uses: actions/setup-node@v4
581
701
  with:
582
- node-version: 22
702
+ # Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
703
+ # refuses because that client reports a clean install as tampered
704
+ # with. 22.1.0 or later, or 20.13.0 or later, carries an npm that
705
+ # can verify.
706
+ node-version: '22.11.0'
583
707
  cache: pnpm
584
708
  # Your own dependencies. The gates are NOT among the things this has to
585
709
  # install: the action installs those itself, globally, at the versions
586
710
  # pinned below.
587
711
  - run: pnpm install --frozen-lockfile
588
712
  - id: conductor
589
- uses: ./
713
+ uses: vaultcompasshq/conductor@v0.4.6
590
714
  with:
591
715
  output: conductor.sarif
592
- # Exact versions, never a range and never "latest". On a
593
- # pull_request event this file is read from the base branch, so
594
- # these four lines are the protected side: a pull request can change
595
- # its own lockfile and cannot change which programs judge it.
596
- # Bump them like any other pin, in a pull request, on the base
597
- # branch first.
598
- conductor-version: 0.4.0
599
- dep-guard-version: 0.6.0
600
- vault-guard-version: 1.7.0
601
- intent-guard-version: 1.4.0
716
+ # Exact versions, never a range and never "latest". These four
717
+ # lines decide which programs judge a pull request, so a pull
718
+ # request's own lockfile no longer does. They are only as protected
719
+ # as this file is: require review on .github/workflows in your
720
+ # branch protection. Bump them like any other pin, in a pull
721
+ # request of their own. Forward only on a pull request: the action
722
+ # refuses a pin below what its tag ships, and the four lines can be
723
+ # left out entirely to take that tag's own versions.
724
+ conductor-version: 0.4.6
725
+ dep-guard-version: 0.7.0
726
+ vault-guard-version: 1.8.0
727
+ intent-guard-version: 1.5.2
602
728
  - uses: github/codeql-action/upload-sarif@v3
603
729
  # Always: the log is most worth having on the run that failed.
604
730
  if: always()
@@ -619,8 +745,192 @@ runs whatever its author pushes to it next. Pin every third-party action by
619
745
  commit digest in a workflow you actually run, the way this repository's own
620
746
  workflows do.
621
747
 
748
+ ### Running the gates as an advisory check
749
+
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.
759
+
760
+ A complete copy-paste job, rather than the one step above in isolation:
761
+
762
+ ```yaml
763
+ name: guardrails-advisory
764
+ on: pull_request
765
+
766
+ jobs:
767
+ gates:
768
+ runs-on: ubuntu-latest
769
+ permissions:
770
+ contents: read
771
+ pull-requests: write
772
+ steps:
773
+ - uses: actions/checkout@v4
774
+ continue-on-error: true
775
+ with:
776
+ fetch-depth: 0
777
+ - uses: actions/setup-node@v4
778
+ continue-on-error: true
779
+ with:
780
+ 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
+ - id: conductor
787
+ continue-on-error: true
788
+ timeout-minutes: 5
789
+ uses: vaultcompasshq/conductor@v0.4.6
790
+ with:
791
+ pr-comment: true
792
+ ```
793
+
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
+ `action.yml` already shallow-fetches the trust base itself as of 0.4.5 when
798
+ 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.
807
+
808
+ ### Adopting conductor
809
+
810
+ The first pull request cannot be judged by the policy it adds. Plan for two
811
+ steps rather than being surprised by one:
812
+
813
+ 1. On a branch, run `conductor init`, then run `conductor run --verbose` on
814
+ your own checkout. That is the full report your policy will produce, with
815
+ no `--trust-base` involved: a direct run on your own checkout is already
816
+ inside the trust boundary, so it reads the policy you just wrote. This is
817
+ where you tune thresholds, not on a pull request.
818
+ 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.
824
+ 3. Merge. Every pull request after that is judged by the policy on the base
825
+ branch, and a change to that policy shows up as a proposal line and takes
826
+ effect after its own merge.
827
+
828
+ There is deliberately no mode in which the pull request's own policy file
829
+ decides the run, not even as a preview: the preview in step 1 gives you the
830
+ same report without putting a file the pull request controls behind a
831
+ verdict on the pull request page.
832
+
622
833
  ### The report as a pull request comment
623
834
 
835
+ **Built in, opt-in.** This matters most for an advisory job: a `pull_request`
836
+ check that is not marked required does not block anything when it fails, and
837
+ without a comment its findings live only in the job's exit code and log,
838
+ which teaches a developer nothing. Set `pr-comment: true` on the Action's own
839
+ step and add `pull-requests: write` to the job's `permissions`:
840
+
841
+ ```yaml
842
+ permissions:
843
+ contents: read
844
+ security-events: write
845
+ pull-requests: write
846
+ steps:
847
+ # ... checkout, pnpm, setup-node, install, as in the example above ...
848
+ - id: conductor
849
+ uses: vaultcompasshq/conductor@v0.4.6
850
+ with:
851
+ output: conductor.sarif
852
+ pr-comment: true
853
+ ```
854
+
855
+ That posts conductor's own text report, the one the README quotes above
856
+ ("conductor: clean, nothing blocked. 2 gate(s) ran: ..."), as a comment on
857
+ the pull request. It is **sticky**: a hidden marker in the comment body lets
858
+ a re-run find and update that same comment, so a push does not pile up a new
859
+ comment every time, the way the manual recipe below does. It runs on a
860
+ `pull_request` or `pull_request_target` event only, and it runs whether the
861
+ gates step passed or failed, since a blocking run is the one an advisory
862
+ check most needs a developer to actually see. The first line of every
863
+ comment carries the version of conductor that produced it, and when the
864
+ trust base was refused and no gate ran at all, the comment shrinks to the
865
+ version, the verdict, and the refusal reason (with its remedy, when one
866
+ applies) rather than the full per-gate report, so an adopter with no policy
867
+ on the base ref yet does not get a full sticky comment whose only content is
868
+ "refused, nothing checked" on every push.
869
+
870
+ **It is a no-op on a pull request from a fork.** The default `GITHUB_TOKEN`
871
+ there is read-only regardless of the `pull-requests: write` permission you
872
+ grant, so the post fails; the step catches that, prints a `::warning::`
873
+ naming the likely cause, and continues. The gate's own pass/fail is decided
874
+ entirely by the earlier "Run the gates" step and never depends on whether
875
+ the comment posted, on a fork or anywhere else. `pull_request_target` runs
876
+ with a writable token and the base repository's own workflow instead, which
877
+ is a different security decision to take on purpose rather than a flag to
878
+ add; nothing here does that for you.
879
+
880
+ Off by default, so an existing consumer of this action is unaffected.
881
+
882
+ **The sticky match only ever adopts conductor's own comment.** On
883
+ `pull_request_target` this step runs with a write token even though the
884
+ pull request itself is untrusted, so anyone who can comment on the pull
885
+ request could, in principle, author a comment carrying the same hidden
886
+ marker before conductor's first run. The match requires the marker AND that
887
+ the comment was authored by the GitHub Actions bot; a marker in anyone
888
+ else's comment is never adopted, and conductor creates its own comment
889
+ instead, exactly as if no marked comment existed.
890
+
891
+ **Running this Action more than once against the same pull request** (for
892
+ example, once per package in a monorepo) needs its own marker per run, or
893
+ those runs fight over one shared comment. Set `pr-comment-marker` to a
894
+ distinct string per invocation and each run stays sticky to its own
895
+ comment; left unset (the default), every invocation uses the same built-in
896
+ marker, which is the existing, unchanged behaviour for a single invocation
897
+ per pull request.
898
+
899
+ ```yaml
900
+ - id: conductor-package-a
901
+ uses: vaultcompasshq/conductor@v0.4.6
902
+ with:
903
+ pr-comment: true
904
+ pr-comment-marker: 'package-a'
905
+ - id: conductor-package-b
906
+ uses: vaultcompasshq/conductor@v0.4.6
907
+ with:
908
+ pr-comment: true
909
+ pr-comment-marker: 'package-b'
910
+ ```
911
+
912
+ **A note for anyone changing this surface, not for a consumer of the
913
+ Action**: the comment body reaches `gh` with `-F body=@<file>` (`gh api`'s
914
+ file-read form), never `-f`, which sends the value as a literal string
915
+ instead of reading the file. The offline test suite
916
+ (`scripts/tests/pr-comment.test.mjs`, `scripts/tests/pr-comment-cli.test.mjs`)
917
+ replaces `gh` with a recorder or a shim, and neither can tell `-f` from `-F`
918
+ apart, since both simply accept a `key=value` string and neither actually
919
+ reads the `@file` form. `scripts/tests/pr-comment-smoke.test.mjs` is what
920
+ actually proves the distinction, against a real `gh` binary; it is skipped
921
+ by an ordinary offline `pnpm test` run and only runs with `GH_TOKEN` (or
922
+ `GITHUB_TOKEN`), `CONDUCTOR_PR_COMMENT_SMOKE_REPO`, and
923
+ `CONDUCTOR_PR_COMMENT_SMOKE_ISSUE` set. Run it for real against a scratch
924
+ issue or pull request before any release that touches
925
+ `scripts/lib/pr-comment.mjs` or `scripts/pr-comment.mjs`; the file itself
926
+ documents the exact invocation.
927
+
928
+ **The manual recipe below still has a reason to exist**: a non-sticky
929
+ comment (one per run, never edited), a report you want to post yourself with
930
+ different formatting, or a workflow that would rather not add
931
+ `pull-requests: write` to the same job the gates run in. For the common
932
+ case, `pr-comment: true` is the built-in answer.
933
+
624
934
  The SARIF upload produces no alerts on a private repository without GitHub
625
935
  Code Security, which is why that step carries `continue-on-error`. A comment
626
936
  is free there. Add `pull-requests: write` to the job's `permissions` and this
@@ -723,6 +1033,8 @@ SARIF result, how the exit code is composed, and the mechanism behind the
723
1033
  intent gate at a pull request. Several of them were learned from running this
724
1034
  tool against real repositories rather than reasoned out in advance.
725
1035
 
1036
+ Adopter feedback is a row in [FINDINGS.md](FINDINGS.md). How to change this repository is in [CONTRIBUTING.md](CONTRIBUTING.md).
1037
+
726
1038
  ## License
727
1039
 
728
1040
  MIT, [Vault & Compass](https://vaultcompass.io)
package/dist/cli.js CHANGED
@@ -79,49 +79,89 @@ function repoRoot(cwd) {
79
79
  * reported, and, when the trust base itself cannot be used, it names the
80
80
  * gates the report says did not run.
81
81
  */
82
+ /**
83
+ * An inventory, and only an inventory: a list of gate NAMES for the report,
84
+ * taken from the one file available when the trust base itself cannot supply
85
+ * a policy. It is head-controlled, so it can be SHORTER as well as longer
86
+ * than the base's -- every gate `enabled: false`, or a file that will not
87
+ * parse at all, leaves it empty.
88
+ *
89
+ * Neither direction can weaken the verdict, and that is the property this
90
+ * rests on rather than on the inventory being right. refusedTrustBase
91
+ * enforces every gate it names and writes exit 2 itself, and the refusal is
92
+ * carried on the result so both renderers lead with it whether the inventory
93
+ * names three gates or none. A longer list makes the report longer; a
94
+ * shorter one makes it shorter; the verdict is the same sentence either way.
95
+ *
96
+ * An unreadable head file leaves the list empty rather than throwing: the
97
+ * trust base is what went wrong, and reporting the head's malformed file
98
+ * would send the reader to the wrong fix on a run that would have ignored
99
+ * that file anyway.
100
+ */
101
+ function inventoryFromHead(root, overrides) {
102
+ try {
103
+ return applyCliOverrides(loadPolicy(root), overrides);
104
+ }
105
+ catch {
106
+ return { version: 1, gates: {}, report: { format: 'text' } };
107
+ }
108
+ }
82
109
  function policyForRun(root, trustBase, overrides) {
83
110
  if (trustBase === undefined) {
84
111
  return { kind: 'policy', policy: applyCliOverrides(loadPolicy(root), overrides) };
85
112
  }
86
113
  const refusal = refuseTrustBaseRef(root, trustBase);
87
114
  if (refusal !== null) {
88
- // An inventory, and only an inventory: a list of gate NAMES for the
89
- // report, taken from the one file available when the base ref cannot be
90
- // read. It is head-controlled, so it can be SHORTER as well as longer
91
- // than the base's -- every gate `enabled: false`, or a file that will not
92
- // parse at all, leaves it empty -- and an earlier comment here claimed
93
- // only the longer direction, which is how the empty case went unnoticed.
94
- //
95
- // Neither direction can weaken the verdict, and that is the property this
96
- // rests on rather than on the inventory being right. refusedTrustBase
97
- // enforces every gate it names and writes exit 2 itself, and the refusal
98
- // is carried on the result so both renderers lead with it whether the
99
- // inventory names three gates or none. A longer list makes the report
100
- // longer; a shorter one makes it shorter; the verdict is the same
101
- // sentence either way.
102
- //
103
- // An unreadable head file leaves the list empty rather than replacing the
104
- // refusal with a policy error: the ref is what went wrong, and reporting
105
- // the head's malformed file would send the reader to the wrong fix on a
106
- // run that would have ignored that file anyway.
107
- let inventory = { version: 1, gates: {}, report: { format: 'text' } };
108
- try {
109
- inventory = applyCliOverrides(loadPolicy(root), overrides);
110
- }
111
- catch {
112
- inventory = { version: 1, gates: {}, report: { format: 'text' } };
113
- }
114
- return { kind: 'refused', ref: trustBase, detail: refusal, inventory };
115
+ return {
116
+ kind: 'refused',
117
+ ref: trustBase,
118
+ detail: refusal,
119
+ inventory: inventoryFromHead(root, overrides),
120
+ };
115
121
  }
116
122
  const baseText = readPolicyAtRef(root, trustBase);
117
123
  const headText = readPolicyAtRef(root, 'HEAD');
118
124
  if (baseText === null) {
119
- throw new PolicyError(`No ${POLICY_FILE_NAME} on "${trustBase}". On a pull-request run every rule comes from the ` +
125
+ // CONFIG ABSENT ON THE BASE, not a policy error thrown from here. The old
126
+ // shape threw a PolicyError, which the run command's catch prints as one
127
+ // line on STDERR and nothing else: no report on stdout, no SARIF file
128
+ // written, exit code 2 by accident of `fail()` rather than by the same
129
+ // could-not-run machinery every other trust-base failure goes through.
130
+ // Two real adopters, running in advisory mode, hit exactly this on their
131
+ // first pull request -- before "conductor init" had ever landed on their
132
+ // base branch -- and read a red step with an empty report as either
133
+ // nothing to see or a broken tool, never as "finish adopting".
134
+ //
135
+ // This is DISCOVERED-empty, not IMPOSED-empty: nobody wrote a policy file
136
+ // down and disabled every gate in it, the base ref simply has none yet.
137
+ // That is the same "nothing here is a result of any kind" shape as a base
138
+ // ref that will not resolve, so it goes through the exact same
139
+ // refusedTrustBase reporting: could-not-run (exit 2), the reason on the
140
+ // text report and in the SARIF log, and the head's own gates named as not
141
+ // having run. A base ref whose file is merely ABSENT must not be treated
142
+ // more gently than one that will not resolve at all; both mean this run
143
+ // has no policy to have been judged by.
144
+ //
145
+ // CONTRAST: a base ref that DOES carry a policy file in which the user
146
+ // switched every gate off, or deferred them all past this stage, is left
147
+ // alone below in the ordinary `runAll` path and keeps reporting a clean
148
+ // exit 0 -- see the "no gate ran because none is enabled" verdict in
149
+ // output-text.ts. That is an IMPOSED-empty state, a decision written down
150
+ // on the base branch on purpose, and mirrors the no-contract
151
+ // (discovered, write one) vs contract-waived (imposed, a person already
152
+ // decided) distinction the intent gate already makes for a missing spec.
153
+ const detail = `No ${POLICY_FILE_NAME} on "${trustBase}". On a pull-request run every rule comes from the ` +
120
154
  'base ref, so this run has no policy at all and nothing was checked. ' +
121
155
  (headText === null
122
156
  ? `Run "conductor init" on the base branch.`
123
157
  : `The ${POLICY_FILE_NAME} in this pull request is a proposal: it decides what runs ` +
124
- 'once it is on the base branch, and never on the pull request that adds it.'));
158
+ 'once it is on the base branch, and never on the pull request that adds it.');
159
+ return {
160
+ kind: 'refused',
161
+ ref: trustBase,
162
+ detail,
163
+ inventory: inventoryFromHead(root, overrides),
164
+ };
125
165
  }
126
166
  return {
127
167
  kind: 'policy',
@@ -244,6 +284,7 @@ export function buildProgram() {
244
284
  .option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
245
285
  .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')
246
286
  .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
+ .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.')
247
288
  .option('--gate <role>', 'restrict the run to this role; repeatable', (value, previous = []) => [...previous, value])
248
289
  .exitOverride()
249
290
  .action((options) => {
@@ -278,7 +319,11 @@ export function buildProgram() {
278
319
  });
279
320
  const rendered = format === 'sarif'
280
321
  ? `${renderSarif(result, pkg.version)}\n`
281
- : renderText(result, { verbose: Boolean(options.verbose) });
322
+ : renderText(result, {
323
+ verbose: Boolean(options.verbose),
324
+ version: pkg.version,
325
+ compact: Boolean(options.compactOnRefusal),
326
+ });
282
327
  if (options.output === undefined) {
283
328
  process.stdout.write(rendered);
284
329
  }