@vaultcompass/conductor 0.3.0 → 0.4.5
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 +306 -21
- package/dist/cli.js +69 -29
- package/dist/gate-runner.d.ts +42 -0
- package/dist/gate-runner.js +113 -18
- package/dist/normalize.d.ts +12 -1
- package/dist/normalize.js +13 -2
- package/dist/output-sarif.js +40 -4
- package/dist/output-text.js +26 -2
- package/dist/resolve.d.ts +28 -1
- package/dist/resolve.js +59 -12
- package/dist/run.js +36 -4
- package/package.json +14 -1
package/README.md
CHANGED
|
@@ -56,6 +56,14 @@ become the annoying part:
|
|
|
56
56
|
npm install -g @vaultcompass/conductor
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
+
**Globally, and that is the guidance for CI too.** A devDependency is fine
|
|
60
|
+
beside it for your own pre-commit hook, and nothing about a local run changed.
|
|
61
|
+
It is not what gates your pull requests: on a pull-request run the umbrella
|
|
62
|
+
never looks in `node_modules/.bin` at all, because what is installed there is
|
|
63
|
+
chosen by the head's own manifest and lockfile. The Action installs all four
|
|
64
|
+
packages itself, globally, at versions pinned in your workflow file. See "The
|
|
65
|
+
pull-request trust boundary" and "The Action" below.
|
|
66
|
+
|
|
59
67
|
From the repository root, look before you write:
|
|
60
68
|
|
|
61
69
|
```
|
|
@@ -304,6 +312,44 @@ where a head-committed `node_modules/.bin/<gate>` shadows the real gate,
|
|
|
304
312
|
because resolution prefers the repository's own copy over PATH so that a
|
|
305
313
|
project pin beats a global install.
|
|
306
314
|
|
|
315
|
+
**On a pull-request run `node_modules/.bin` is not consulted at all.** That
|
|
316
|
+
second shape is closed one step earlier than the first, and this is why: what
|
|
317
|
+
is installed there is chosen by the head's own manifest and lockfile, so it is
|
|
318
|
+
never approved by any ref, and a repository whose gates are devDependencies
|
|
319
|
+
would otherwise meet the program refusal on every ordinary pull request. So
|
|
320
|
+
that location is simply not searched when a trust base is set. PATH and an
|
|
321
|
+
absolute `command:` remain, and both still go through the program check below.
|
|
322
|
+
The skip is never silent: one line in the full report and one
|
|
323
|
+
`conductor/node-modules-skipped` note in the SARIF log name each gate and the
|
|
324
|
+
copy that was not taken, and a gate with nothing on PATH either is
|
|
325
|
+
could-not-run with `npm install -g` and the Action's version input named as
|
|
326
|
+
the remedy. **Outside pull-request mode nothing changes**: your own checkout
|
|
327
|
+
and your pre-commit hook still run the pin, which is what `pnpm exec` does in
|
|
328
|
+
the same repository.
|
|
329
|
+
|
|
330
|
+
**The versions that judge a pull request are pinned in the workflow file**,
|
|
331
|
+
and that is the point: the pull request can change its own lockfile,
|
|
332
|
+
manifest and `node_modules`, and none of those decide which conductor and
|
|
333
|
+
which gates run over it any more. Be clear about what that does not cover.
|
|
334
|
+
On a `pull_request` event GitHub runs the workflow as it is in the pull
|
|
335
|
+
request's merge commit, so a pull request that edits the workflow file can
|
|
336
|
+
change the pins or remove the gates step, exactly as it could rewrite any
|
|
337
|
+
other step in your CI. The boundary here is against the tree choosing its
|
|
338
|
+
own judge; the control for a workflow edit is branch protection on your
|
|
339
|
+
base branch with review required for `.github/workflows`, and no action can
|
|
340
|
+
provide that for you. Only `pull_request_target` runs the base branch's copy
|
|
341
|
+
of a workflow, and that event exposes the base's secrets to the pull
|
|
342
|
+
request's code, which is the wrong trade for a gate over untrusted changes.
|
|
343
|
+
|
|
344
|
+
One part of that is closed, and only one. Because the pins are written in a
|
|
345
|
+
file the pull request controls, a pull request could otherwise pin a gate
|
|
346
|
+
**backward** to a published version that predates the rule which would have
|
|
347
|
+
caught it: an exact version, so the validate step's shape check accepts it,
|
|
348
|
+
and a change that reads as ordinary version management. **On a pull request
|
|
349
|
+
the action now refuses any of the four `*-version` inputs naming a version
|
|
350
|
+
below the one the action tag ships.** Pinning forward is still accepted.
|
|
351
|
+
See "The Action" below.
|
|
352
|
+
|
|
307
353
|
So on a pull-request run a gate's program must be **outside the working tree**
|
|
308
354
|
(on PATH, or an absolute `command:` elsewhere on the machine), or else meet
|
|
309
355
|
**both** of these:
|
|
@@ -341,12 +387,13 @@ the exit code even where the policy sets `enforce: false`, because the gate
|
|
|
341
387
|
produced no findings to un-enforce: the umbrella declined to run a program
|
|
342
388
|
the pull request chose.
|
|
343
389
|
|
|
344
|
-
Nothing under `node_modules` is ever base-approved,
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
390
|
+
Nothing under `node_modules` is ever base-approved, which is why the rule
|
|
391
|
+
above does not look there at all. Were it to look, the answer would always be
|
|
392
|
+
the same refusal: what is there is chosen by the head's own manifest and
|
|
393
|
+
lockfile and installed by a step that runs before the gates, so git has no
|
|
394
|
+
record of those bytes at either ref. A pull request that edits its lockfile to
|
|
395
|
+
pull a different build of a gate has chosen its own judge just as surely as
|
|
396
|
+
one that commits a stub. **Vendoring a gate still works**, on those
|
|
350
397
|
terms: put it in its own directory, keep everything it needs inside that
|
|
351
398
|
directory, and leave the whole directory alone in a pull request the gate is
|
|
352
399
|
meant to judge. Changing it is not forbidden, it just has to land on the base
|
|
@@ -489,14 +536,75 @@ no severity threshold of its own here either.
|
|
|
489
536
|
`action.yml` at the root is a composite action that runs the gates at the
|
|
490
537
|
`ci` stage and writes one SARIF log for the caller to upload.
|
|
491
538
|
|
|
492
|
-
It **installs
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
539
|
+
It **installs all four packages itself**, and outside the workspace. Until
|
|
540
|
+
0.4.0 it installed nothing and ran the `node_modules/.bin/conductor` your
|
|
541
|
+
repository already had, which put every program in the family inside the tree
|
|
542
|
+
under judgment: the install step runs the head's lockfile, so a pull request
|
|
543
|
+
could repoint any gate, or the umbrella itself, at a build it controls while
|
|
544
|
+
leaving the version number alone.
|
|
545
|
+
|
|
546
|
+
Now four inputs name exact versions, `conductor-version`,
|
|
547
|
+
`dep-guard-version`, `vault-guard-version` and `intent-guard-version`, each
|
|
548
|
+
defaulting to the version this release pins. A validate step refuses anything
|
|
549
|
+
that is not an exact version, a range and `latest` included: the version that
|
|
550
|
+
judges a pull request has to be a decision taken on the base branch rather
|
|
551
|
+
than one the registry takes on the morning of the run. An install step then
|
|
552
|
+
runs `npm install -g --ignore-scripts` under the runner temp, never into the
|
|
553
|
+
workspace, and prepends that bin directory to `PATH`, so the run step invokes
|
|
554
|
+
`conductor` off `PATH` and each gate resolves by name the same way. The install
|
|
555
|
+
is **unconditional**, on push and `pull_request` alike, so there is one code
|
|
556
|
+
path rather than one that matters and one that nobody exercises.
|
|
557
|
+
|
|
558
|
+
**On a pull request those four inputs may not pin backward.** The shape check
|
|
559
|
+
asks whether an input is an exact version; it says nothing about which one, and
|
|
560
|
+
on a `pull_request` event the workflow file comes from the head, so the pins are
|
|
561
|
+
written by the pull request being judged. Once a gate has two published versions
|
|
562
|
+
that is a bypass with an innocent shape: pin back to the release that predates
|
|
563
|
+
the rule which would have caught the change, and the change picks the rules it
|
|
564
|
+
is judged by. So where `GITHUB_BASE_REF` is set, the validate step refuses an
|
|
565
|
+
input naming a version below the one the action tag ships, naming both numbers,
|
|
566
|
+
and the fix is to **remove the input**: the default is that version. Pinning
|
|
567
|
+
**forward** is still accepted, on an assumption the rule does not enforce, that
|
|
568
|
+
a newer gate is at least as strict; nothing bounds how far forward you pin.
|
|
569
|
+
|
|
570
|
+
Three things follow from that, stated because the summary is wider than the rule.
|
|
571
|
+
It fires on fork pull requests too, where the base repository's workflow file is
|
|
572
|
+
the one that runs, so a deliberate backward pin you wrote yourself will refuse
|
|
573
|
+
every fork run until you remove it. Push runs are out of scope rather than safe:
|
|
574
|
+
a push to an unprotected branch runs that branch's own workflow file, written by
|
|
575
|
+
the same author. And `merge_group` runs are not covered at all: `GITHUB_BASE_REF`
|
|
576
|
+
is set on `pull_request` and `pull_request_target` only, so it is empty in a
|
|
577
|
+
merge queue even though the queue branch carries the pull request's commits and
|
|
578
|
+
its workflow file. If your only required check runs on `merge_group`, this rule
|
|
579
|
+
does nothing for you; keep the `pull_request` run required as well and the pin is
|
|
580
|
+
caught before the queue. Neither this nor anything else in `action.yml`
|
|
581
|
+
replaces branch protection with review required for `.github/workflows`, which
|
|
582
|
+
is still the only control over a pull request that edits the workflow.
|
|
583
|
+
|
|
584
|
+
`--ignore-scripts` is there because the step holds the job's token and the four
|
|
585
|
+
things it installs decide whether a pull request may merge; without it every
|
|
586
|
+
package in the resolved tree would run code on the runner. The step then runs
|
|
587
|
+
`npm audit signatures` over what it installed.
|
|
588
|
+
|
|
589
|
+
**What that verification proves, and what it does not.** It asks the registry
|
|
590
|
+
for each name and version in the tree, the four gates included, and checks the
|
|
591
|
+
signature served back, so an unpublished, replaced or unsigned package fails the
|
|
592
|
+
step. It does **not** read the installed files, so it will not detect a tampered
|
|
593
|
+
install; it does **not** defeat a compromised registry, which signs what it
|
|
594
|
+
serves; and a **missing** attestation is not a failure, so it does not require
|
|
595
|
+
provenance even though all four packages publish it.
|
|
596
|
+
|
|
597
|
+
> **This step needs a registry that serves `/-/npm/v1/keys`.** If your runner
|
|
598
|
+
> points npm at a mirror or proxy that does not (via `actions/setup-node`'s
|
|
599
|
+
> `registry-url:`, a corporate `~/.npmrc`, or `npm_config_registry`), the
|
|
600
|
+
> install succeeds and this step then fails with `EMISSINGSIGNATUREKEY`. A
|
|
601
|
+
> sigstore outage has the same effect. It fails closed on purpose, so that is a
|
|
602
|
+
> red gate rather than a skipped check; pin to `@v0.4.0`, which does not
|
|
603
|
+
> verify, if it blocks you.
|
|
604
|
+
|
|
605
|
+
`--base` is passed only when the `base-ref` input names one; left empty, the
|
|
606
|
+
umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
|
|
607
|
+
pull request", which is what a push build wants.
|
|
500
608
|
|
|
501
609
|
On a `pull_request` event the action passes
|
|
502
610
|
**`--trust-base origin/$GITHUB_BASE_REF`** of its own accord, so the run takes
|
|
@@ -513,6 +621,49 @@ event the workflow file itself runs from the pull request's own ref, so an
|
|
|
513
621
|
opt-out here would be settable by the very pull request the mode exists to
|
|
514
622
|
judge: the knob and the thing it protects against would be the same file.
|
|
515
623
|
|
|
624
|
+
**The normal way to use this is by tag, not by path.** `uses: ./` reads
|
|
625
|
+
`action.yml` out of whichever tree the workflow runs against, which is
|
|
626
|
+
correct only for this repository's own workflows testing themselves; on a
|
|
627
|
+
pull request from anywhere else it would read `action.yml` out of the pull
|
|
628
|
+
request being judged, and the version-pin protection described above
|
|
629
|
+
"protects nothing" against a tree that controls its own judge (the
|
|
630
|
+
validate step's own comment in `action.yml` says so in those words). Name
|
|
631
|
+
this action by owner and tag instead:
|
|
632
|
+
|
|
633
|
+
```yaml
|
|
634
|
+
name: guardrails
|
|
635
|
+
on: pull_request
|
|
636
|
+
|
|
637
|
+
jobs:
|
|
638
|
+
gates:
|
|
639
|
+
runs-on: ubuntu-latest
|
|
640
|
+
permissions:
|
|
641
|
+
contents: read
|
|
642
|
+
security-events: write
|
|
643
|
+
steps:
|
|
644
|
+
- uses: actions/checkout@v4
|
|
645
|
+
with:
|
|
646
|
+
fetch-depth: 0
|
|
647
|
+
- uses: actions/setup-node@v4
|
|
648
|
+
with:
|
|
649
|
+
node-version: '22.11.0'
|
|
650
|
+
- id: conductor
|
|
651
|
+
uses: vaultcompasshq/conductor@v0.4.5
|
|
652
|
+
with:
|
|
653
|
+
output: conductor.sarif
|
|
654
|
+
- uses: github/codeql-action/upload-sarif@v3
|
|
655
|
+
if: always()
|
|
656
|
+
continue-on-error: true
|
|
657
|
+
with:
|
|
658
|
+
sarif_file: ${{ steps.conductor.outputs.sarif }}
|
|
659
|
+
```
|
|
660
|
+
|
|
661
|
+
No version inputs there at all: left out, the four gates run at the versions
|
|
662
|
+
this tag ships, which is the intended default. The fully spelled-out example
|
|
663
|
+
below adds explicit version pins and comments explaining each one, for a
|
|
664
|
+
workflow that wants that transparency; the four lines can still be left out
|
|
665
|
+
entirely to take the tag's own versions, exactly as the form above does.
|
|
666
|
+
|
|
516
667
|
```yaml
|
|
517
668
|
name: guardrails
|
|
518
669
|
on: pull_request
|
|
@@ -535,13 +686,32 @@ jobs:
|
|
|
535
686
|
- uses: pnpm/action-setup@v4
|
|
536
687
|
- uses: actions/setup-node@v4
|
|
537
688
|
with:
|
|
538
|
-
|
|
689
|
+
# Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
|
|
690
|
+
# refuses because that client reports a clean install as tampered
|
|
691
|
+
# with. 22.1.0 or later, or 20.13.0 or later, carries an npm that
|
|
692
|
+
# can verify.
|
|
693
|
+
node-version: '22.11.0'
|
|
539
694
|
cache: pnpm
|
|
695
|
+
# Your own dependencies. The gates are NOT among the things this has to
|
|
696
|
+
# install: the action installs those itself, globally, at the versions
|
|
697
|
+
# pinned below.
|
|
540
698
|
- run: pnpm install --frozen-lockfile
|
|
541
699
|
- id: conductor
|
|
542
|
-
uses:
|
|
700
|
+
uses: vaultcompasshq/conductor@v0.4.5
|
|
543
701
|
with:
|
|
544
702
|
output: conductor.sarif
|
|
703
|
+
# Exact versions, never a range and never "latest". These four
|
|
704
|
+
# lines decide which programs judge a pull request, so a pull
|
|
705
|
+
# request's own lockfile no longer does. They are only as protected
|
|
706
|
+
# as this file is: require review on .github/workflows in your
|
|
707
|
+
# branch protection. Bump them like any other pin, in a pull
|
|
708
|
+
# request of their own. Forward only on a pull request: the action
|
|
709
|
+
# refuses a pin below what its tag ships, and the four lines can be
|
|
710
|
+
# left out entirely to take that tag's own versions.
|
|
711
|
+
conductor-version: 0.4.5
|
|
712
|
+
dep-guard-version: 0.7.0
|
|
713
|
+
vault-guard-version: 1.8.0
|
|
714
|
+
intent-guard-version: 1.5.2
|
|
545
715
|
- uses: github/codeql-action/upload-sarif@v3
|
|
546
716
|
# Always: the log is most worth having on the run that failed.
|
|
547
717
|
if: always()
|
|
@@ -564,6 +734,99 @@ workflows do.
|
|
|
564
734
|
|
|
565
735
|
### The report as a pull request comment
|
|
566
736
|
|
|
737
|
+
**Built in, opt-in.** This matters most for an advisory job: a `pull_request`
|
|
738
|
+
check that is not marked required does not block anything when it fails, and
|
|
739
|
+
without a comment its findings live only in the job's exit code and log,
|
|
740
|
+
which teaches a developer nothing. Set `pr-comment: true` on the Action's own
|
|
741
|
+
step and add `pull-requests: write` to the job's `permissions`:
|
|
742
|
+
|
|
743
|
+
```yaml
|
|
744
|
+
permissions:
|
|
745
|
+
contents: read
|
|
746
|
+
security-events: write
|
|
747
|
+
pull-requests: write
|
|
748
|
+
steps:
|
|
749
|
+
# ... checkout, pnpm, setup-node, install, as in the example above ...
|
|
750
|
+
- id: conductor
|
|
751
|
+
uses: vaultcompasshq/conductor@v0.4.5
|
|
752
|
+
with:
|
|
753
|
+
output: conductor.sarif
|
|
754
|
+
pr-comment: true
|
|
755
|
+
```
|
|
756
|
+
|
|
757
|
+
That posts conductor's own text report, the one the README quotes above
|
|
758
|
+
("conductor: clean, nothing blocked. 2 gate(s) ran: ..."), as a comment on
|
|
759
|
+
the pull request. It is **sticky**: a hidden marker in the comment body lets
|
|
760
|
+
a re-run find and update that same comment, so a push does not pile up a new
|
|
761
|
+
comment every time, the way the manual recipe below does. It runs on a
|
|
762
|
+
`pull_request` or `pull_request_target` event only, and it runs whether the
|
|
763
|
+
gates step passed or failed, since a blocking run is the one an advisory
|
|
764
|
+
check most needs a developer to actually see.
|
|
765
|
+
|
|
766
|
+
**It is a no-op on a pull request from a fork.** The default `GITHUB_TOKEN`
|
|
767
|
+
there is read-only regardless of the `pull-requests: write` permission you
|
|
768
|
+
grant, so the post fails; the step catches that, prints a `::warning::`
|
|
769
|
+
naming the likely cause, and continues. The gate's own pass/fail is decided
|
|
770
|
+
entirely by the earlier "Run the gates" step and never depends on whether
|
|
771
|
+
the comment posted, on a fork or anywhere else. `pull_request_target` runs
|
|
772
|
+
with a writable token and the base repository's own workflow instead, which
|
|
773
|
+
is a different security decision to take on purpose rather than a flag to
|
|
774
|
+
add; nothing here does that for you.
|
|
775
|
+
|
|
776
|
+
Off by default, so an existing consumer of this action is unaffected.
|
|
777
|
+
|
|
778
|
+
**The sticky match only ever adopts conductor's own comment.** On
|
|
779
|
+
`pull_request_target` this step runs with a write token even though the
|
|
780
|
+
pull request itself is untrusted, so anyone who can comment on the pull
|
|
781
|
+
request could, in principle, author a comment carrying the same hidden
|
|
782
|
+
marker before conductor's first run. The match requires the marker AND that
|
|
783
|
+
the comment was authored by the GitHub Actions bot; a marker in anyone
|
|
784
|
+
else's comment is never adopted, and conductor creates its own comment
|
|
785
|
+
instead, exactly as if no marked comment existed.
|
|
786
|
+
|
|
787
|
+
**Running this Action more than once against the same pull request** (for
|
|
788
|
+
example, once per package in a monorepo) needs its own marker per run, or
|
|
789
|
+
those runs fight over one shared comment. Set `pr-comment-marker` to a
|
|
790
|
+
distinct string per invocation and each run stays sticky to its own
|
|
791
|
+
comment; left unset (the default), every invocation uses the same built-in
|
|
792
|
+
marker, which is the existing, unchanged behaviour for a single invocation
|
|
793
|
+
per pull request.
|
|
794
|
+
|
|
795
|
+
```yaml
|
|
796
|
+
- id: conductor-package-a
|
|
797
|
+
uses: vaultcompasshq/conductor@v0.4.5
|
|
798
|
+
with:
|
|
799
|
+
pr-comment: true
|
|
800
|
+
pr-comment-marker: 'package-a'
|
|
801
|
+
- id: conductor-package-b
|
|
802
|
+
uses: vaultcompasshq/conductor@v0.4.5
|
|
803
|
+
with:
|
|
804
|
+
pr-comment: true
|
|
805
|
+
pr-comment-marker: 'package-b'
|
|
806
|
+
```
|
|
807
|
+
|
|
808
|
+
**A note for anyone changing this surface, not for a consumer of the
|
|
809
|
+
Action**: the comment body reaches `gh` with `-F body=@<file>` (`gh api`'s
|
|
810
|
+
file-read form), never `-f`, which sends the value as a literal string
|
|
811
|
+
instead of reading the file. The offline test suite
|
|
812
|
+
(`scripts/tests/pr-comment.test.mjs`, `scripts/tests/pr-comment-cli.test.mjs`)
|
|
813
|
+
replaces `gh` with a recorder or a shim, and neither can tell `-f` from `-F`
|
|
814
|
+
apart, since both simply accept a `key=value` string and neither actually
|
|
815
|
+
reads the `@file` form. `scripts/tests/pr-comment-smoke.test.mjs` is what
|
|
816
|
+
actually proves the distinction, against a real `gh` binary; it is skipped
|
|
817
|
+
by an ordinary offline `pnpm test` run and only runs with `GH_TOKEN` (or
|
|
818
|
+
`GITHUB_TOKEN`), `CONDUCTOR_PR_COMMENT_SMOKE_REPO`, and
|
|
819
|
+
`CONDUCTOR_PR_COMMENT_SMOKE_ISSUE` set. Run it for real against a scratch
|
|
820
|
+
issue or pull request before any release that touches
|
|
821
|
+
`scripts/lib/pr-comment.mjs` or `scripts/pr-comment.mjs`; the file itself
|
|
822
|
+
documents the exact invocation.
|
|
823
|
+
|
|
824
|
+
**The manual recipe below still has a reason to exist**: a non-sticky
|
|
825
|
+
comment (one per run, never edited), a report you want to post yourself with
|
|
826
|
+
different formatting, or a workflow that would rather not add
|
|
827
|
+
`pull-requests: write` to the same job the gates run in. For the common
|
|
828
|
+
case, `pr-comment: true` is the built-in answer.
|
|
829
|
+
|
|
567
830
|
The SARIF upload produces no alerts on a private repository without GitHub
|
|
568
831
|
Code Security, which is why that step carries `continue-on-error`. A comment
|
|
569
832
|
is free there. Add `pull-requests: write` to the job's `permissions` and this
|
|
@@ -580,19 +843,41 @@ writes SARIF and nothing else, so the job costs roughly twice the gate time;
|
|
|
580
843
|
env:
|
|
581
844
|
GH_TOKEN: ${{ github.token }}
|
|
582
845
|
PR: ${{ github.event.pull_request.number }}
|
|
846
|
+
# The same derivation the Action makes for its own --trust-base.
|
|
847
|
+
# github.base_ref is a BRANCH NAME and is empty outside a pull
|
|
848
|
+
# request, so an empty value has to mean "not a pull request":
|
|
849
|
+
# passing --trust-base unconditionally would hand a push build the
|
|
850
|
+
# literal ref "origin/" and fail it closed.
|
|
851
|
+
BASE: ${{ github.base_ref }}
|
|
583
852
|
# || true: a blocking finding is a non-zero exit, and that verdict
|
|
584
853
|
# belongs to the gates step rather than to this one.
|
|
585
854
|
run: |
|
|
586
|
-
|
|
855
|
+
ARGS=(run --stage ci --format text --verbose --output conductor.txt)
|
|
856
|
+
if [ -n "$BASE" ]; then
|
|
857
|
+
ARGS+=(--trust-base "origin/$BASE")
|
|
858
|
+
fi
|
|
859
|
+
conductor "${ARGS[@]}" || true
|
|
587
860
|
gh pr comment "$PR" --body-file conductor.txt
|
|
588
861
|
```
|
|
589
862
|
|
|
863
|
+
`conductor` and not `node_modules/.bin/conductor`: the gates step put the
|
|
864
|
+
installed one on `PATH`. Reaching into `node_modules` here would report a
|
|
865
|
+
different program's verdict from the one in the uploaded log.
|
|
866
|
+
|
|
867
|
+
`--trust-base` for the same reason, and the two together are what make this
|
|
868
|
+
the run the uploaded log is about: same binary AND same trust base. Without
|
|
869
|
+
it this second run reads the head's own policy file, consults
|
|
870
|
+
`node_modules/.bin` like any local run, and never asks where a gate's program
|
|
871
|
+
came from, so a pull request that plants one gets a clean comment beside a
|
|
872
|
+
SARIF log that refused it.
|
|
873
|
+
|
|
590
874
|
**Mirror whatever you gave the Action**, or the two runs can report different
|
|
591
875
|
contracts. The step above matches the example, which passes neither
|
|
592
|
-
`base-ref` nor `spec`, so both runs read `GITHUB_BASE_REF` and
|
|
593
|
-
line out of the job environment themselves and land on the same
|
|
594
|
-
you set
|
|
595
|
-
|
|
876
|
+
`base-ref`, `trust-base` nor `spec`, so both runs read `GITHUB_BASE_REF` and
|
|
877
|
+
the `Spec:` line out of the job environment themselves and land on the same
|
|
878
|
+
contract and the same ref. If you set any of those inputs on the gates step,
|
|
879
|
+
pass the same values here as `--base`, `--trust-base` and `--spec`; if you do
|
|
880
|
+
not, the comment is a report of a contract source, or of a boundary, the
|
|
596
881
|
uploaded log never used.
|
|
597
882
|
|
|
598
883
|
**On a pull request from a fork the token is read-only**, so `gh pr comment`
|
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
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
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
|
-
|
|
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',
|
package/dist/gate-runner.d.ts
CHANGED
|
@@ -141,6 +141,17 @@ export interface GateOutcome {
|
|
|
141
141
|
* pull-request mode, and what it said was proposed.
|
|
142
142
|
*/
|
|
143
143
|
trustBase?: GateTrustBase;
|
|
144
|
+
/**
|
|
145
|
+
* The `node_modules/.bin` candidate resolution did NOT try, repository
|
|
146
|
+
* relative, on a pull-request run where one was there.
|
|
147
|
+
*
|
|
148
|
+
* Absent outside pull-request mode, and absent inside it when there was
|
|
149
|
+
* nothing to skip: it is a claim that something was there and was declined,
|
|
150
|
+
* not a claim about the mode. Reported so an adopter whose gates are
|
|
151
|
+
* devDependencies learns why the gate came from somewhere else, or from
|
|
152
|
+
* nowhere. Repository-relative because it reaches a published log.
|
|
153
|
+
*/
|
|
154
|
+
nodeModulesSkipped?: string;
|
|
144
155
|
}
|
|
145
156
|
export interface RunGateOptions {
|
|
146
157
|
repoRoot: string;
|
|
@@ -178,6 +189,37 @@ export interface RunGateOptions {
|
|
|
178
189
|
* would have to learn about.
|
|
179
190
|
*/
|
|
180
191
|
export declare function preparationFailed(gate: GatePolicy, detail: string): GateOutcome;
|
|
192
|
+
/**
|
|
193
|
+
* EVERY program this binary would spawn, vetted against the trust base.
|
|
194
|
+
*
|
|
195
|
+
* Two files and not one. `program` is what the gate runs, and
|
|
196
|
+
* `versionProbe.command` can be a DIFFERENT file: for a per-command binary
|
|
197
|
+
* that ignores `--version`, resolution finds the version-safe sibling
|
|
198
|
+
* somewhere else entirely (`versionProbeFor`, src/resolve.ts:238-262). Vetting
|
|
199
|
+
* only the first left the probe free to spawn whatever the head put at the
|
|
200
|
+
* second, and a probe RUNS a program as thoroughly as a scan does.
|
|
201
|
+
*
|
|
202
|
+
* The first refusal wins and the rest is not consulted. The verdict is the
|
|
203
|
+
* same either way, and the sentence a reader has to act on should name one
|
|
204
|
+
* file rather than two.
|
|
205
|
+
*/
|
|
206
|
+
export declare function refuseHeadControlledBinary(repoRoot: string, trustBase: string, binary: ResolvedBinary): string | null;
|
|
207
|
+
/**
|
|
208
|
+
* The outcome for a gate whose program the umbrella declined to run.
|
|
209
|
+
*
|
|
210
|
+
* ONE BUILDER, TWO CALLERS, and that is the point of it being here rather
|
|
211
|
+
* than written out at the return that needs it. `runGate` reaches this before
|
|
212
|
+
* it spawns anything; `runAll` reaches it earlier still, before the intent
|
|
213
|
+
* gate's preparation spawns the same program three times. A second copy of
|
|
214
|
+
* the shape would be a second chance to forget the override below.
|
|
215
|
+
*
|
|
216
|
+
* ENFORCED, whatever the policy says. `enforce: false` is a standing decision
|
|
217
|
+
* about what a gate's FINDINGS are worth, and this gate produced none: the
|
|
218
|
+
* umbrella refused to run a program the pull request chose. Letting an
|
|
219
|
+
* unenforced gate swallow that would let a pull request pick its own judge
|
|
220
|
+
* and keep the run green.
|
|
221
|
+
*/
|
|
222
|
+
export declare function gateProgramRefused(gate: GatePolicy, trustBase: string, refusal: string, binary: ResolvedBinary): GateOutcome;
|
|
181
223
|
/**
|
|
182
224
|
* The arguments the umbrella adds, per product.
|
|
183
225
|
*
|
package/dist/gate-runner.js
CHANGED
|
@@ -20,7 +20,7 @@ import { NormalizeError } from './envelope.js';
|
|
|
20
20
|
import { normalizeDepGuard, normalizeFailedGate, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
|
|
21
21
|
import { renderOptionFlags } from './policy.js';
|
|
22
22
|
import { atLeastVersion, refuseHeadControlledProgram } from './trust-base.js';
|
|
23
|
-
import { ResolveError, candidateNames, resolveGateBinary } from './resolve.js';
|
|
23
|
+
import { ResolveError, candidateNames, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
|
|
24
24
|
/**
|
|
25
25
|
* The first version of each gate that understands `--trust-base`.
|
|
26
26
|
*
|
|
@@ -142,6 +142,66 @@ const EMPTY_RUN = {
|
|
|
142
142
|
diagnostics: [],
|
|
143
143
|
details: {},
|
|
144
144
|
};
|
|
145
|
+
/**
|
|
146
|
+
* EVERY program this binary would spawn, vetted against the trust base.
|
|
147
|
+
*
|
|
148
|
+
* Two files and not one. `program` is what the gate runs, and
|
|
149
|
+
* `versionProbe.command` can be a DIFFERENT file: for a per-command binary
|
|
150
|
+
* that ignores `--version`, resolution finds the version-safe sibling
|
|
151
|
+
* somewhere else entirely (`versionProbeFor`, src/resolve.ts:238-262). Vetting
|
|
152
|
+
* only the first left the probe free to spawn whatever the head put at the
|
|
153
|
+
* second, and a probe RUNS a program as thoroughly as a scan does.
|
|
154
|
+
*
|
|
155
|
+
* The first refusal wins and the rest is not consulted. The verdict is the
|
|
156
|
+
* same either way, and the sentence a reader has to act on should name one
|
|
157
|
+
* file rather than two.
|
|
158
|
+
*/
|
|
159
|
+
export function refuseHeadControlledBinary(repoRoot, trustBase, binary) {
|
|
160
|
+
for (const program of [binary.program, binary.versionProbe?.command]) {
|
|
161
|
+
if (program === undefined) {
|
|
162
|
+
continue;
|
|
163
|
+
}
|
|
164
|
+
const refusal = refuseHeadControlledProgram(repoRoot, trustBase, program);
|
|
165
|
+
if (refusal !== null) {
|
|
166
|
+
return refusal;
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
return null;
|
|
170
|
+
}
|
|
171
|
+
/**
|
|
172
|
+
* The outcome for a gate whose program the umbrella declined to run.
|
|
173
|
+
*
|
|
174
|
+
* ONE BUILDER, TWO CALLERS, and that is the point of it being here rather
|
|
175
|
+
* than written out at the return that needs it. `runGate` reaches this before
|
|
176
|
+
* it spawns anything; `runAll` reaches it earlier still, before the intent
|
|
177
|
+
* gate's preparation spawns the same program three times. A second copy of
|
|
178
|
+
* the shape would be a second chance to forget the override below.
|
|
179
|
+
*
|
|
180
|
+
* ENFORCED, whatever the policy says. `enforce: false` is a standing decision
|
|
181
|
+
* about what a gate's FINDINGS are worth, and this gate produced none: the
|
|
182
|
+
* umbrella refused to run a program the pull request chose. Letting an
|
|
183
|
+
* unenforced gate swallow that would let a pull request pick its own judge
|
|
184
|
+
* and keep the run green.
|
|
185
|
+
*/
|
|
186
|
+
export function gateProgramRefused(gate, trustBase, refusal, binary) {
|
|
187
|
+
return {
|
|
188
|
+
role: gate.role,
|
|
189
|
+
product: gate.product,
|
|
190
|
+
stage: gate.stage,
|
|
191
|
+
enforce: true,
|
|
192
|
+
productVersion: null,
|
|
193
|
+
argv: [],
|
|
194
|
+
binary,
|
|
195
|
+
exitCode: null,
|
|
196
|
+
durationMs: 0,
|
|
197
|
+
stderr: '',
|
|
198
|
+
trustBase: { ref: trustBase, withheld: null, refused: refusal, proposals: [] },
|
|
199
|
+
couldNotRun: { reason: 'gate-program-refused', detail: refusal },
|
|
200
|
+
findings: [normalizeFailedGate(gate.role, gate.product, refusal)],
|
|
201
|
+
run: EMPTY_RUN,
|
|
202
|
+
diagnostics: [],
|
|
203
|
+
};
|
|
204
|
+
}
|
|
145
205
|
/**
|
|
146
206
|
* The arguments the umbrella adds, per product.
|
|
147
207
|
*
|
|
@@ -267,6 +327,31 @@ function messageOf(err) {
|
|
|
267
327
|
}
|
|
268
328
|
return String(err);
|
|
269
329
|
}
|
|
330
|
+
/**
|
|
331
|
+
* The sentence a gate that resolved to nothing gets on a pull-request run.
|
|
332
|
+
*
|
|
333
|
+
* EMPTY OUTSIDE PULL-REQUEST MODE, because outside it nothing about
|
|
334
|
+
* resolution changed and the old message is still the whole story. Inside it
|
|
335
|
+
* the message would otherwise be actively misleading in the common case: an
|
|
336
|
+
* adopter with the gates as devDependencies is looking straight at a
|
|
337
|
+
* node_modules/.bin/<gate> while being told no binary was found.
|
|
338
|
+
*
|
|
339
|
+
* It names `npm install -g` and the Action's own input rather than "install
|
|
340
|
+
* it", because those are the two places the fix actually is: on a runner, the
|
|
341
|
+
* Action installs the gates itself at a version pinned in a workflow file that
|
|
342
|
+
* lives on the base branch, which is the protected side.
|
|
343
|
+
*/
|
|
344
|
+
function missingGateRemedy(product, skipNodeModules, skipped) {
|
|
345
|
+
if (!skipNodeModules) {
|
|
346
|
+
return '';
|
|
347
|
+
}
|
|
348
|
+
return (' On a pull-request run node_modules/.bin is not consulted at all: what is installed there ' +
|
|
349
|
+
'is chosen by the head own manifest and lockfile, so no ref approves it.' +
|
|
350
|
+
(skipped === null ? '' : ` There is a ${skipped}, and it was skipped for that reason.`) +
|
|
351
|
+
` Install the gate outside the tree with npm install -g @vaultcompass/${product}. The ` +
|
|
352
|
+
`conductor Action does exactly that, at the version its ${product}-version input pins, and ` +
|
|
353
|
+
'that pin lives in the workflow file on the base branch.');
|
|
354
|
+
}
|
|
270
355
|
/**
|
|
271
356
|
* Runs one gate. TOTAL: this never throws.
|
|
272
357
|
*
|
|
@@ -337,10 +422,20 @@ export function runGate(gate, options) {
|
|
|
337
422
|
}
|
|
338
423
|
function runGateInner(gate, options, started, progress) {
|
|
339
424
|
const timeoutMs = options.timeoutMs ?? 120_000;
|
|
425
|
+
// ONE PLACE DECIDES WHAT PULL-REQUEST MODE IS, and it is the presence of a
|
|
426
|
+
// trust base. resolve.ts knows nothing about refs, so it is told rather than
|
|
427
|
+
// asked.
|
|
428
|
+
const skipNodeModules = options.trustBase !== undefined;
|
|
429
|
+
const skipped = skipNodeModules ? nodeModulesCandidate(gate, options.repoRoot) : null;
|
|
430
|
+
if (skipped !== null) {
|
|
431
|
+
// Onto `progress` rather than only onto the returns below, so the
|
|
432
|
+
// backstop's view carries it too.
|
|
433
|
+
Object.assign(progress, { nodeModulesSkipped: skipped });
|
|
434
|
+
}
|
|
340
435
|
const base = progress;
|
|
341
436
|
let binary;
|
|
342
437
|
try {
|
|
343
|
-
binary = resolveGateBinary(gate, options.repoRoot, options.pathValue);
|
|
438
|
+
binary = resolveGateBinary(gate, options.repoRoot, options.pathValue, { skipNodeModules });
|
|
344
439
|
}
|
|
345
440
|
catch (err) {
|
|
346
441
|
// A ResolveError is the expected shape here; anything else is still a
|
|
@@ -364,6 +459,7 @@ function runGateInner(gate, options, started, progress) {
|
|
|
364
459
|
};
|
|
365
460
|
}
|
|
366
461
|
if (binary === null) {
|
|
462
|
+
const remedy = missingGateRemedy(gate.product, skipNodeModules, skipped);
|
|
367
463
|
return {
|
|
368
464
|
...base,
|
|
369
465
|
durationMs: Date.now() - started,
|
|
@@ -371,13 +467,19 @@ function runGateInner(gate, options, started, progress) {
|
|
|
371
467
|
reason: 'binary-missing',
|
|
372
468
|
// Named in resolution order, which is the repository's own copy
|
|
373
469
|
// first. Saying PATH first points a reader at the location this
|
|
374
|
-
// tool prefers second, which is the wrong place to install it.
|
|
375
|
-
|
|
470
|
+
// tool prefers second, which is the wrong place to install it. On a
|
|
471
|
+
// pull-request run that order has one entry, because the other one is
|
|
472
|
+
// not a location this run has.
|
|
473
|
+
detail: (skipNodeModules
|
|
474
|
+
? `no ${gate.product} binary on PATH`
|
|
475
|
+
: `no ${gate.product} binary in node_modules/.bin or on PATH`) + remedy,
|
|
376
476
|
},
|
|
377
477
|
// A missing enabled gate is a finding of the umbrella's own, never a
|
|
378
478
|
// silent skip. Skipping is how a gate ends up switched on in the
|
|
379
479
|
// policy file and absent in reality for months.
|
|
380
|
-
findings: [
|
|
480
|
+
findings: [
|
|
481
|
+
normalizeMissingGate(gate.role, gate.product, candidateNames(gate.product), remedy),
|
|
482
|
+
],
|
|
381
483
|
run: EMPTY_RUN,
|
|
382
484
|
diagnostics: [],
|
|
383
485
|
};
|
|
@@ -388,23 +490,16 @@ function runGateInner(gate, options, started, progress) {
|
|
|
388
490
|
// version of this attack and it would have been run before anything checked
|
|
389
491
|
// where it came from.
|
|
390
492
|
if (options.trustBase !== undefined) {
|
|
391
|
-
|
|
493
|
+
// BOTH SPAWNABLE PATHS, not just the program: the probe below can be a
|
|
494
|
+
// different file from binary.program, and it is executed just as
|
|
495
|
+
// thoroughly. The enforce override and the rest of the shape live in
|
|
496
|
+
// gateProgramRefused, which the intent gate's preparation shares.
|
|
497
|
+
const refusal = refuseHeadControlledBinary(options.repoRoot, options.trustBase, binary);
|
|
392
498
|
if (refusal !== null) {
|
|
393
499
|
return {
|
|
394
500
|
...base,
|
|
395
|
-
binary,
|
|
501
|
+
...gateProgramRefused(gate, options.trustBase, refusal, binary),
|
|
396
502
|
durationMs: Date.now() - started,
|
|
397
|
-
// ENFORCED, whatever the policy says. enforce: false is a standing
|
|
398
|
-
// decision about what a gate's FINDINGS are worth, and this gate
|
|
399
|
-
// produced none: the umbrella refused to run a program the pull
|
|
400
|
-
// request chose. Letting an unenforced gate swallow that would let a
|
|
401
|
-
// pull request pick its own judge and keep the run green.
|
|
402
|
-
enforce: true,
|
|
403
|
-
trustBase: { ref: options.trustBase, withheld: null, refused: refusal, proposals: [] },
|
|
404
|
-
couldNotRun: { reason: 'gate-program-refused', detail: refusal },
|
|
405
|
-
findings: [normalizeFailedGate(gate.role, gate.product, refusal)],
|
|
406
|
-
run: EMPTY_RUN,
|
|
407
|
-
diagnostics: [],
|
|
408
503
|
};
|
|
409
504
|
}
|
|
410
505
|
}
|
package/dist/normalize.d.ts
CHANGED
|
@@ -45,7 +45,18 @@ export type GateProblemRule = 'conductor/gate-missing' | 'conductor/gate-output-
|
|
|
45
45
|
* looked. So it is a finding, it blocks, and it says which names were
|
|
46
46
|
* tried, so the fix is in the message rather than in a support thread.
|
|
47
47
|
*/
|
|
48
|
-
export declare function normalizeMissingGate(role: GateRole, product: Product, candidates: string[]
|
|
48
|
+
export declare function normalizeMissingGate(role: GateRole, product: Product, candidates: string[],
|
|
49
|
+
/**
|
|
50
|
+
* A sentence appended to the message, or nothing.
|
|
51
|
+
*
|
|
52
|
+
* Written by the caller rather than decided here, because the only thing
|
|
53
|
+
* that varies is WHY the search came up empty, and that is a fact about the
|
|
54
|
+
* run rather than about the finding. Today the one caller that passes
|
|
55
|
+
* anything is a pull-request run, where node_modules/.bin was never
|
|
56
|
+
* searched and the message would otherwise be misleading in exactly the
|
|
57
|
+
* repository shape this is most likely to happen in.
|
|
58
|
+
*/
|
|
59
|
+
remedy?: string): Finding;
|
|
49
60
|
/**
|
|
50
61
|
* The finding raised when a gate's `command:` names a file that is not
|
|
51
62
|
* there.
|
package/dist/normalize.js
CHANGED
|
@@ -620,10 +620,21 @@ function gateProblem(ruleId, role, product, message, details) {
|
|
|
620
620
|
* looked. So it is a finding, it blocks, and it says which names were
|
|
621
621
|
* tried, so the fix is in the message rather than in a support thread.
|
|
622
622
|
*/
|
|
623
|
-
export function normalizeMissingGate(role, product, candidates
|
|
623
|
+
export function normalizeMissingGate(role, product, candidates,
|
|
624
|
+
/**
|
|
625
|
+
* A sentence appended to the message, or nothing.
|
|
626
|
+
*
|
|
627
|
+
* Written by the caller rather than decided here, because the only thing
|
|
628
|
+
* that varies is WHY the search came up empty, and that is a fact about the
|
|
629
|
+
* run rather than about the finding. Today the one caller that passes
|
|
630
|
+
* anything is a pull-request run, where node_modules/.bin was never
|
|
631
|
+
* searched and the message would otherwise be misleading in exactly the
|
|
632
|
+
* repository shape this is most likely to happen in.
|
|
633
|
+
*/
|
|
634
|
+
remedy = '') {
|
|
624
635
|
return gateProblem('conductor/gate-missing', role, product, `The "${role}" gate is enabled but no ${product} binary was found. ` +
|
|
625
636
|
`Looked for: ${candidates.join(', ')}. Install it, point the gate at a build with an ` +
|
|
626
|
-
`absolute "command:", or set enabled: false to switch the gate off on purpose
|
|
637
|
+
`absolute "command:", or set enabled: false to switch the gate off on purpose.${remedy}`, { candidates });
|
|
627
638
|
}
|
|
628
639
|
/**
|
|
629
640
|
* The finding raised when a gate's `command:` names a file that is not
|
package/dist/output-sarif.js
CHANGED
|
@@ -588,10 +588,11 @@ function proposalNotifications(result) {
|
|
|
588
588
|
/**
|
|
589
589
|
* The trust base the umbrella refused, when it refused one.
|
|
590
590
|
*
|
|
591
|
-
* ERROR LEVEL,
|
|
592
|
-
*
|
|
593
|
-
*
|
|
594
|
-
*
|
|
591
|
+
* ERROR LEVEL, one of the two notifications here that are not notes, and the
|
|
592
|
+
* wider of the two: a refused program says one gate did not run, and this one
|
|
593
|
+
* says the whole run did not. Every other notification in this file says how
|
|
594
|
+
* much of the policy a run covered. These two say what was not covered at
|
|
595
|
+
* all, and a reader must not be able to scroll past either.
|
|
595
596
|
*
|
|
596
597
|
* A NOTIFICATION rather than a result even so, and the reason is the
|
|
597
598
|
* discriminator further down: a result is about a place in somebody's code,
|
|
@@ -686,6 +687,40 @@ function trustBaseWithheldNotifications(result) {
|
|
|
686
687
|
];
|
|
687
688
|
});
|
|
688
689
|
}
|
|
690
|
+
/**
|
|
691
|
+
* The node_modules/.bin candidates a pull-request run declined to take.
|
|
692
|
+
*
|
|
693
|
+
* ONE NOTIFICATION FOR THE RUN, not one per gate. This is a statement about
|
|
694
|
+
* the run's mode: node_modules/.bin is not a location a pull-request run has,
|
|
695
|
+
* and in the repository shape it happens in most, gates installed as
|
|
696
|
+
* devDependencies and nothing else, it is true of every gate at once.
|
|
697
|
+
*
|
|
698
|
+
* A NOTE, by the discriminator above, and not a close call. Nothing went
|
|
699
|
+
* wrong, nobody's code is at fault, and the gates still ran: it says WHERE the
|
|
700
|
+
* program that ran came from, which is a coverage statement in the same shape
|
|
701
|
+
* as the withheld one. When the skip actually cost a gate its run, that gate's
|
|
702
|
+
* own could-not-run result carries the remedy, so a consumer reading only
|
|
703
|
+
* results still learns what to do.
|
|
704
|
+
*/
|
|
705
|
+
function nodeModulesSkippedNotifications(result) {
|
|
706
|
+
const skipped = result.gates.flatMap((gate) => gate.nodeModulesSkipped === undefined
|
|
707
|
+
? []
|
|
708
|
+
: [{ role: gate.role, product: gate.product, path: gate.nodeModulesSkipped }]);
|
|
709
|
+
if (skipped.length === 0) {
|
|
710
|
+
return [];
|
|
711
|
+
}
|
|
712
|
+
return [
|
|
713
|
+
{
|
|
714
|
+
id: 'conductor/node-modules-skipped',
|
|
715
|
+
message: 'Resolution did NOT consult node_modules/.bin on this pull-request run: ' +
|
|
716
|
+
`${skipped.map((entry) => `${entry.role} (${entry.product}) at ${entry.path}`).join(', ')}. ` +
|
|
717
|
+
'What is installed there is chosen by the head own manifest and lockfile, so no ref ' +
|
|
718
|
+
'approves it. Each of those gates was resolved from PATH or from an absolute command: ' +
|
|
719
|
+
'instead, or reported as could-not-run with the install remedy.',
|
|
720
|
+
details: { ref: result.trustBase?.ref ?? null, skipped },
|
|
721
|
+
},
|
|
722
|
+
];
|
|
723
|
+
}
|
|
689
724
|
/**
|
|
690
725
|
* The gates the policy file told not to decide anything, as notifications.
|
|
691
726
|
*
|
|
@@ -799,6 +834,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
799
834
|
...programRefusedNotifications(result),
|
|
800
835
|
...proposalNotifications(result),
|
|
801
836
|
...trustBaseWithheldNotifications(result),
|
|
837
|
+
...nodeModulesSkippedNotifications(result),
|
|
802
838
|
];
|
|
803
839
|
// Notifications earn the run on their own. Before this, the umbrella run
|
|
804
840
|
// existed only when it had findings and a deferred gate was one; without
|
package/dist/output-text.js
CHANGED
|
@@ -245,12 +245,35 @@ function withheldTrustBase(result) {
|
|
|
245
245
|
return reason === undefined || reason === null ? [] : [{ gate, reason }];
|
|
246
246
|
});
|
|
247
247
|
}
|
|
248
|
+
/**
|
|
249
|
+
* The gates whose own node_modules/.bin copy this run declined to take.
|
|
250
|
+
*
|
|
251
|
+
* ONE LINE FOR THE WHOLE RUN rather than one per gate. The fact is about the
|
|
252
|
+
* run's mode, not about any gate's verdict, and in the repository shape it is
|
|
253
|
+
* most likely to happen in, gates installed as devDependencies and nothing
|
|
254
|
+
* else, it is true of all three at once. Three lines saying the same thing
|
|
255
|
+
* would read as three problems.
|
|
256
|
+
*/
|
|
257
|
+
function nodeModulesSkippedLine(result) {
|
|
258
|
+
const skipped = result.gates.flatMap((gate) => gate.nodeModulesSkipped === undefined
|
|
259
|
+
? []
|
|
260
|
+
: [`${gate.role} (${gate.product}) at ${gate.nodeModulesSkipped}`]);
|
|
261
|
+
if (skipped.length === 0) {
|
|
262
|
+
return [];
|
|
263
|
+
}
|
|
264
|
+
return [
|
|
265
|
+
` node_modules/.bin not consulted: ${skipped.join(', ')}. What is installed there is ` +
|
|
266
|
+
'chosen by the head own manifest and lockfile, so no ref approves it; each of those gates ' +
|
|
267
|
+
'was resolved from PATH or from an absolute command: instead, or reported as could-not-run.',
|
|
268
|
+
];
|
|
269
|
+
}
|
|
248
270
|
/**
|
|
249
271
|
* The pull-request-mode block of the full report.
|
|
250
272
|
*
|
|
251
|
-
*
|
|
273
|
+
* Four things in one place, because they answer one question between them:
|
|
252
274
|
* where the rules came from, what this pull request proposes to change them
|
|
253
|
-
* to,
|
|
275
|
+
* to, which gates were not covered by any of it, and where the programs that
|
|
276
|
+
* did run came from.
|
|
254
277
|
*/
|
|
255
278
|
function trustBaseLines(result) {
|
|
256
279
|
if (result.trustBase === null) {
|
|
@@ -265,6 +288,7 @@ function trustBaseLines(result) {
|
|
|
265
288
|
for (const { gate, reason } of withheldTrustBase(result)) {
|
|
266
289
|
lines.push(` NOT in pull-request mode ${gate.role} ${gate.product} ${reason}`);
|
|
267
290
|
}
|
|
291
|
+
lines.push(...nodeModulesSkippedLine(result));
|
|
268
292
|
return lines;
|
|
269
293
|
}
|
|
270
294
|
/**
|
package/dist/resolve.d.ts
CHANGED
|
@@ -41,9 +41,36 @@ export interface ResolvedBinary {
|
|
|
41
41
|
versionProbe: VersionProbe | null;
|
|
42
42
|
}
|
|
43
43
|
export declare const CANDIDATES: Record<Product, Candidate[]>;
|
|
44
|
+
export interface ResolveOptions {
|
|
45
|
+
/**
|
|
46
|
+
* Leave `node_modules/.bin` out of the search entirely.
|
|
47
|
+
*
|
|
48
|
+
* True on a pull-request run and false everywhere else, decided by the
|
|
49
|
+
* caller from whether a trust base is set rather than re-derived here: this
|
|
50
|
+
* module knows nothing about refs, and there must be exactly one place that
|
|
51
|
+
* says what pull-request mode is.
|
|
52
|
+
*/
|
|
53
|
+
skipNodeModules?: boolean;
|
|
54
|
+
}
|
|
44
55
|
export declare class ResolveError extends Error {
|
|
45
56
|
constructor(message: string);
|
|
46
57
|
}
|
|
58
|
+
/**
|
|
59
|
+
* The node_modules/.bin candidate a pull-request run declined to take.
|
|
60
|
+
*
|
|
61
|
+
* Repository-relative, because it goes into a report and a published SARIF
|
|
62
|
+
* log, where an absolute path is somebody's machine layout.
|
|
63
|
+
*
|
|
64
|
+
* Returns null when the policy names a `command:`: that overrides resolution
|
|
65
|
+
* entirely, so no candidate was skipped, and saying one was would send a
|
|
66
|
+
* reader to fix a file that decided nothing.
|
|
67
|
+
*
|
|
68
|
+
* Separate from `resolveGateBinary` rather than a field on its result,
|
|
69
|
+
* because the case that most needs reporting is the one where resolution
|
|
70
|
+
* returns NOTHING: a repository with the gates only as devDependencies, which
|
|
71
|
+
* is the shape this whole change exists for.
|
|
72
|
+
*/
|
|
73
|
+
export declare function nodeModulesCandidate(gate: GatePolicy, repoRoot: string): string | null;
|
|
47
74
|
/**
|
|
48
75
|
* Resolves the binary for one gate.
|
|
49
76
|
*
|
|
@@ -58,6 +85,6 @@ export declare class ResolveError extends Error {
|
|
|
58
85
|
* named one specific file and falling back to something else would run a
|
|
59
86
|
* different tool than the one they asked for.
|
|
60
87
|
*/
|
|
61
|
-
export declare function resolveGateBinary(gate: GatePolicy, repoRoot: string, pathValue: string): ResolvedBinary | null;
|
|
88
|
+
export declare function resolveGateBinary(gate: GatePolicy, repoRoot: string, pathValue: string, options?: ResolveOptions): ResolvedBinary | null;
|
|
62
89
|
/** Every name resolution would try, for the missing-gate finding's message. */
|
|
63
90
|
export declare function candidateNames(product: Product): string[];
|
package/dist/resolve.js
CHANGED
|
@@ -24,6 +24,19 @@
|
|
|
24
24
|
// no say in that; a LOCATION is a statement about which build, and the
|
|
25
25
|
// repository does.
|
|
26
26
|
//
|
|
27
|
+
// 1c. ON A PULL-REQUEST RUN node_modules/.bin IS NOT A LOCATION AT ALL.
|
|
28
|
+
// Rule 1b says a LOCATION is a statement about which build and the
|
|
29
|
+
// repository gets to make it. On a pull request the repository making
|
|
30
|
+
// that statement IS the pull request: what is under node_modules was
|
|
31
|
+
// chosen by the head's own manifest and lockfile, installed by a step
|
|
32
|
+
// that runs before the gates, and git has no record of those bytes at
|
|
33
|
+
// either ref. 0.3.0 let resolution take it and then refused the program,
|
|
34
|
+
// which was safe and made every ordinary pull request in a
|
|
35
|
+
// devDependency-installed repository exit 2 with three refusals. Not
|
|
36
|
+
// trying that location at all is the same safety with the gate still
|
|
37
|
+
// running, from a build the base branch pinned. The skip is never
|
|
38
|
+
// silent: the caller reports the candidate it declined.
|
|
39
|
+
//
|
|
27
40
|
// 2. Only a unified binary is asked for its version. `intent-guard`
|
|
28
41
|
// answers --version; a per-command binary once did not parse the flag at
|
|
29
42
|
// all and RAN THE GATE against the current directory instead, and a
|
|
@@ -104,12 +117,16 @@ function findInNodeModules(name, repoRoot) {
|
|
|
104
117
|
const full = path.join(repoRoot, 'node_modules', '.bin', name);
|
|
105
118
|
return isExecutableFile(full) ? full : null;
|
|
106
119
|
}
|
|
107
|
-
function locate(name, repoRoot, pathValue) {
|
|
120
|
+
function locate(name, repoRoot, pathValue, skipNodeModules) {
|
|
108
121
|
// The repository's own copy first: a project pin beats a global install,
|
|
109
|
-
// which is what "pnpm exec <name>" does in the same repository.
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
122
|
+
// which is what "pnpm exec <name>" does in the same repository. Unless this
|
|
123
|
+
// is a pull-request run, where the repository saying which build to use is
|
|
124
|
+
// the pull request itself (rule 1c at the top of this file).
|
|
125
|
+
if (!skipNodeModules) {
|
|
126
|
+
const local = findInNodeModules(name, repoRoot);
|
|
127
|
+
if (local !== null) {
|
|
128
|
+
return { command: local, source: 'node_modules' };
|
|
129
|
+
}
|
|
113
130
|
}
|
|
114
131
|
const onPath = findOnPath(name, pathValue);
|
|
115
132
|
if (onPath !== null) {
|
|
@@ -117,8 +134,34 @@ function locate(name, repoRoot, pathValue) {
|
|
|
117
134
|
}
|
|
118
135
|
return null;
|
|
119
136
|
}
|
|
137
|
+
/**
|
|
138
|
+
* The node_modules/.bin candidate a pull-request run declined to take.
|
|
139
|
+
*
|
|
140
|
+
* Repository-relative, because it goes into a report and a published SARIF
|
|
141
|
+
* log, where an absolute path is somebody's machine layout.
|
|
142
|
+
*
|
|
143
|
+
* Returns null when the policy names a `command:`: that overrides resolution
|
|
144
|
+
* entirely, so no candidate was skipped, and saying one was would send a
|
|
145
|
+
* reader to fix a file that decided nothing.
|
|
146
|
+
*
|
|
147
|
+
* Separate from `resolveGateBinary` rather than a field on its result,
|
|
148
|
+
* because the case that most needs reporting is the one where resolution
|
|
149
|
+
* returns NOTHING: a repository with the gates only as devDependencies, which
|
|
150
|
+
* is the shape this whole change exists for.
|
|
151
|
+
*/
|
|
152
|
+
export function nodeModulesCandidate(gate, repoRoot) {
|
|
153
|
+
if (gate.command !== undefined) {
|
|
154
|
+
return null;
|
|
155
|
+
}
|
|
156
|
+
for (const candidate of CANDIDATES[gate.product]) {
|
|
157
|
+
if (findInNodeModules(candidate.name, repoRoot) !== null) {
|
|
158
|
+
return `node_modules/.bin/${candidate.name}`;
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
return null;
|
|
162
|
+
}
|
|
120
163
|
/** The candidate whose --version can be asked without running anything. */
|
|
121
|
-
function versionProbeFor(product, resolvedCandidate, resolvedCommand, repoRoot, pathValue) {
|
|
164
|
+
function versionProbeFor(product, resolvedCandidate, resolvedCommand, repoRoot, pathValue, skipNodeModules) {
|
|
122
165
|
if (resolvedCandidate.versionSafe) {
|
|
123
166
|
return { command: resolvedCommand, argv: ['--version'] };
|
|
124
167
|
}
|
|
@@ -126,7 +169,10 @@ function versionProbeFor(product, resolvedCandidate, resolvedCommand, repoRoot,
|
|
|
126
169
|
if (!candidate.versionSafe) {
|
|
127
170
|
continue;
|
|
128
171
|
}
|
|
129
|
-
|
|
172
|
+
// The skip reaches here too, and it has to: a probe RUNS the binary, so
|
|
173
|
+
// resolving the version-safe sibling out of node_modules would execute a
|
|
174
|
+
// head-chosen program in order to answer a question about it.
|
|
175
|
+
const found = locate(candidate.name, repoRoot, pathValue, skipNodeModules);
|
|
130
176
|
if (found !== null) {
|
|
131
177
|
return { command: found.command, argv: ['--version'] };
|
|
132
178
|
}
|
|
@@ -151,8 +197,9 @@ function baseName(file) {
|
|
|
151
197
|
* named one specific file and falling back to something else would run a
|
|
152
198
|
* different tool than the one they asked for.
|
|
153
199
|
*/
|
|
154
|
-
export function resolveGateBinary(gate, repoRoot, pathValue) {
|
|
200
|
+
export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
155
201
|
const table = CANDIDATES[gate.product];
|
|
202
|
+
const skipNodeModules = options.skipNodeModules ?? false;
|
|
156
203
|
if (gate.command !== undefined) {
|
|
157
204
|
if (!existsAsFile(gate.command)) {
|
|
158
205
|
throw new ResolveError(`gates.${gate.role}.command points at "${gate.command}", which is not a file. ` +
|
|
@@ -177,7 +224,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
|
|
|
177
224
|
candidate: candidateName,
|
|
178
225
|
versionProbe: candidate.versionSafe
|
|
179
226
|
? { command: process.execPath, argv: [gate.command, '--version'] }
|
|
180
|
-
: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue),
|
|
227
|
+
: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
|
|
181
228
|
};
|
|
182
229
|
}
|
|
183
230
|
return {
|
|
@@ -186,11 +233,11 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
|
|
|
186
233
|
argvPrefix: prefix,
|
|
187
234
|
source: 'policy',
|
|
188
235
|
candidate: candidateName,
|
|
189
|
-
versionProbe: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue),
|
|
236
|
+
versionProbe: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
|
|
190
237
|
};
|
|
191
238
|
}
|
|
192
239
|
for (const candidate of table) {
|
|
193
|
-
const found = locate(candidate.name, repoRoot, pathValue);
|
|
240
|
+
const found = locate(candidate.name, repoRoot, pathValue, skipNodeModules);
|
|
194
241
|
if (found === null) {
|
|
195
242
|
continue;
|
|
196
243
|
}
|
|
@@ -200,7 +247,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
|
|
|
200
247
|
argvPrefix: [...candidate.prefix],
|
|
201
248
|
source: found.source,
|
|
202
249
|
candidate: candidate.name,
|
|
203
|
-
versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue),
|
|
250
|
+
versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
|
|
204
251
|
};
|
|
205
252
|
}
|
|
206
253
|
return null;
|
package/dist/run.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// One run across every enabled gate.
|
|
2
2
|
import { compareFindings } from './envelope.js';
|
|
3
3
|
import { EXIT_COULD_NOT_RUN, composeExitCode } from './exit-codes.js';
|
|
4
|
-
import { preparationFailed, runGate } from './gate-runner.js';
|
|
4
|
+
import { gateProgramRefused, preparationFailed, refuseHeadControlledBinary, runGate, } from './gate-runner.js';
|
|
5
5
|
import { resolveBaseRef } from './intent-base.js';
|
|
6
6
|
import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
|
|
7
7
|
import { GATE_ROLES, enabledGates, runsAtStage } from './policy.js';
|
|
@@ -23,10 +23,19 @@ function isPullRequestShaped(options, env) {
|
|
|
23
23
|
}
|
|
24
24
|
return resolveBaseRef({ ...(options.base === undefined ? {} : { base: options.base }), env }) !== null;
|
|
25
25
|
}
|
|
26
|
-
/**
|
|
26
|
+
/**
|
|
27
|
+
* The intent-guard binary, or null when there is none to prepare with.
|
|
28
|
+
*
|
|
29
|
+
* SAME SKIP AS runGate's, and it is not decoration: preparation SPAWNS this
|
|
30
|
+
* binary, before runGate has looked at anything. Resolving it out of
|
|
31
|
+
* node_modules on a pull-request run would execute a program the head chose,
|
|
32
|
+
* three times, before the program check the boundary rests on had run once.
|
|
33
|
+
*/
|
|
27
34
|
function intentBinary(gate, options) {
|
|
28
35
|
try {
|
|
29
|
-
return resolveGateBinary(gate, options.repoRoot, options.pathValue
|
|
36
|
+
return resolveGateBinary(gate, options.repoRoot, options.pathValue, {
|
|
37
|
+
skipNodeModules: options.trustBase !== undefined,
|
|
38
|
+
});
|
|
30
39
|
}
|
|
31
40
|
catch (err) {
|
|
32
41
|
// A ResolveError means the policy named a command that is not there.
|
|
@@ -174,6 +183,21 @@ export function runAll(policy, options) {
|
|
|
174
183
|
// twice, once as a failed preparation and once as a missing gate,
|
|
175
184
|
// would read as two problems where there is one.
|
|
176
185
|
if (binary !== null) {
|
|
186
|
+
// BEFORE ANYTHING IS SPAWNED, and that ordering is the whole of it.
|
|
187
|
+
// runGate makes this check for every other gate and makes it first;
|
|
188
|
+
// for this one the preparation gets there earlier and runs the gate
|
|
189
|
+
// three times, so the check has to be made here as well or the
|
|
190
|
+
// boundary begins after the program the pull request chose has
|
|
191
|
+
// already run. Same builder as runGate's, so the enforce override
|
|
192
|
+
// cannot drift between the two places that produce this outcome.
|
|
193
|
+
const trustBaseRef = options.trustBase?.ref;
|
|
194
|
+
if (trustBaseRef !== undefined) {
|
|
195
|
+
const refusal = refuseHeadControlledBinary(options.repoRoot, trustBaseRef, binary);
|
|
196
|
+
if (refusal !== null) {
|
|
197
|
+
outcomes.push(gateProgramRefused(gate, trustBaseRef, refusal, binary));
|
|
198
|
+
continue;
|
|
199
|
+
}
|
|
200
|
+
}
|
|
177
201
|
const prepared = prepareIntent({
|
|
178
202
|
repoRoot: options.repoRoot,
|
|
179
203
|
binary,
|
|
@@ -193,7 +217,15 @@ export function runAll(policy, options) {
|
|
|
193
217
|
continue;
|
|
194
218
|
}
|
|
195
219
|
if (prepared.kind === 'failed') {
|
|
196
|
-
outcomes.push(preparationFailed(
|
|
220
|
+
outcomes.push(preparationFailed(
|
|
221
|
+
// ENFORCED under a trust base, by the same argument as
|
|
222
|
+
// `refusedTrustBase` below: `enforce` is itself a control
|
|
223
|
+
// input, this gate produced no findings for it to be a
|
|
224
|
+
// decision about, and a pull-request run where the intent
|
|
225
|
+
// gate could not be prepared is one where nothing judged the
|
|
226
|
+
// intent. Reading the flag here let a base policy with
|
|
227
|
+
// enforce: false report the failure and still exit 0.
|
|
228
|
+
trustBaseRef === undefined ? gate : { ...gate, enforce: true }, `the intent gate could not be prepared at the ${prepared.step} step: ${prepared.detail}`));
|
|
197
229
|
continue;
|
|
198
230
|
}
|
|
199
231
|
intent = prepared.preparation;
|
package/package.json
CHANGED
|
@@ -1,8 +1,21 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vaultcompass/conductor",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.5",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Umbrella installer and combined report over the independently installable guardrail gates.",
|
|
6
|
+
"keywords": [
|
|
7
|
+
"security",
|
|
8
|
+
"guardrails",
|
|
9
|
+
"sarif",
|
|
10
|
+
"code-scanning",
|
|
11
|
+
"github-actions",
|
|
12
|
+
"pre-commit",
|
|
13
|
+
"supply-chain",
|
|
14
|
+
"secrets-detection",
|
|
15
|
+
"cli"
|
|
16
|
+
],
|
|
17
|
+
"homepage": "https://github.com/marketplace/actions/conductor-guardrail-gates",
|
|
18
|
+
"bugs": "https://github.com/vaultcompasshq/conductor/issues",
|
|
6
19
|
"license": "MIT",
|
|
7
20
|
"repository": {
|
|
8
21
|
"type": "git",
|