@vaultcompass/conductor 0.8.0 → 0.8.1
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 +127 -50
- package/dist/cli.js +151 -29
- package/dist/external-config.d.ts +2 -1
- package/dist/external-config.js +33 -18
- package/dist/gate-runner.d.ts +119 -16
- package/dist/gate-runner.js +328 -60
- package/dist/git.d.ts +80 -0
- package/dist/git.js +224 -0
- package/dist/init.js +40 -3
- package/dist/intent-base.d.ts +35 -1
- package/dist/intent-base.js +124 -64
- package/dist/intent-prepare.d.ts +33 -2
- package/dist/intent-prepare.js +443 -34
- package/dist/intent-spec.d.ts +28 -0
- package/dist/intent-spec.js +22 -5
- package/dist/normalize.js +6 -4
- package/dist/output-sarif.js +12 -13
- package/dist/output-text.d.ts +48 -0
- package/dist/output-text.js +139 -14
- package/dist/policy.js +9 -7
- package/dist/resolve.d.ts +1 -0
- package/dist/resolve.js +1 -1
- package/dist/run.d.ts +8 -0
- package/dist/run.js +63 -13
- package/dist/trust-base.d.ts +82 -20
- package/dist/trust-base.js +190 -73
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -610,7 +610,12 @@ request could point a gate at a script it added in the same commit.
|
|
|
610
610
|
|
|
611
611
|
**On a pull-request run the rules come from the base branch.** With
|
|
612
612
|
`--trust-base <ref>` the umbrella reads `.guardrails.yaml` from that ref with
|
|
613
|
-
|
|
613
|
+
git and judges the head tree against it. A trusted file at the base that git
|
|
614
|
+
cannot read as a regular file (a symlink, a directory, a submodule, or a file
|
|
615
|
+
below a symlinked or submodule directory) is could-not-run, never replaced by
|
|
616
|
+
a default. Clear it by making the file a regular file on the base branch; the
|
|
617
|
+
pull request that does so is judged against that same base, so it has to be
|
|
618
|
+
merged by someone allowed to merge without this check passing. A `.guardrails.yaml` in the
|
|
614
619
|
pull request never takes effect for that run, `command:` and `args:`
|
|
615
620
|
included, so **a pull request cannot change the rules it is judged by, and
|
|
616
621
|
cannot choose the program that judges it, as long as that program is
|
|
@@ -823,10 +828,11 @@ choose its own judge on exactly the repositories that have no rules yet. See
|
|
|
823
828
|
"Adopting conductor" below for the sequence and for how to see what your
|
|
824
829
|
policy will do before you merge it.
|
|
825
830
|
|
|
826
|
-
**Which gates are covered.** All five: dep-guard from **0.
|
|
827
|
-
intent-guard from **1.
|
|
831
|
+
**Which gates are covered.** All five: dep-guard from **0.10.1**,
|
|
832
|
+
intent-guard from **1.8.1**, vault-guard from **1.9.1**, and the two
|
|
828
833
|
external gates at their command-line floors, gitleaks **8.19.0** and
|
|
829
|
-
osv-scanner **2.0.0**.
|
|
834
|
+
osv-scanner **2.0.0**. On a pull-request run an older family gate is
|
|
835
|
+
could-not-run rather than run outside pull-request mode.
|
|
830
836
|
|
|
831
837
|
**The external gates get their pull-request mode from the umbrella.**
|
|
832
838
|
Neither tool has a `--trust-base`, and both auto-load a config from the tree
|
|
@@ -884,22 +890,50 @@ in the diff. Only the root `osv-scanner.toml` is read from the base and
|
|
|
884
890
|
passed with `--config`, which overrides any nested one for the run; a
|
|
885
891
|
nested one the pull request adds or edits is reported as a proposal.
|
|
886
892
|
|
|
887
|
-
The umbrella asks each gate its version
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
893
|
+
The umbrella asks each gate its version before it runs it. On a run with a
|
|
894
|
+
trust base, a gate older than its pull-request-mode minimum (intent-guard
|
|
895
|
+
1.8.1, vault-guard 1.9.1, dep-guard 0.10.1) is could-not-run (exit 2),
|
|
896
|
+
never run without the flag: without it the gate would take its rules from
|
|
897
|
+
the tree being judged. The fix is to install that minimum or newer, or to
|
|
898
|
+
remove an explicit older version pin. A version that cannot be read at all
|
|
899
|
+
is could-not-run too: the umbrella cannot establish that the gate would
|
|
900
|
+
take its rules from the base ref. The one gate that runs without the flag
|
|
901
|
+
is an intent gate judging a contract imported from the base for the run,
|
|
902
|
+
whose project is a temporary directory with no repository to resolve a ref
|
|
903
|
+
in; that is never silent: it gets a line in the report, a clause on the
|
|
904
|
+
clean one-line summary, and a `conductor/trust-base-not-passed`
|
|
905
|
+
notification in the SARIF log.
|
|
898
906
|
|
|
899
907
|
Outside pull-request mode nothing changes. A pre-commit hook and a direct run
|
|
900
908
|
on your own checkout are already inside the trust boundary, and neither passes
|
|
901
909
|
the flag.
|
|
902
910
|
|
|
911
|
+
**In CI, pull-request mode needs a trust base.** A run in GitHub Actions with
|
|
912
|
+
`GITHUB_BASE_REF` set and no `--trust-base` is could-not-run (exit 2): its
|
|
913
|
+
rules have to come from the base branch, and no base was named. Pass `--trust-base
|
|
914
|
+
refs/remotes/origin/<base branch>` with `fetch-depth: 0`, or use the Action,
|
|
915
|
+
which always passes one. A pre-commit hook run inside a pull-request job hits
|
|
916
|
+
this too: skip the hook in CI, or pass the trust base to it.
|
|
917
|
+
|
|
918
|
+
**On a pull-request run PATH holds only absolute entries, and conductor's own
|
|
919
|
+
git comes from outside the repository.** Empty and relative entries are
|
|
920
|
+
removed for conductor and every gate it starts, with one notice naming them,
|
|
921
|
+
and conductor runs the first git on PATH that lives outside the repository's
|
|
922
|
+
work tree; with none, the run is could-not-run and says to put git's own
|
|
923
|
+
directory on PATH. A gate found only through a removed entry is reported
|
|
924
|
+
missing; put it on an absolute PATH entry or name it with an absolute
|
|
925
|
+
`command:`. Every gate conductor starts, and everything a gate starts, gets
|
|
926
|
+
a PATH whose first entry is a private directory outside the repository
|
|
927
|
+
holding only that same git, so a gate that runs git by name runs it too; on
|
|
928
|
+
Windows no such directory is made and the gates look git up through the
|
|
929
|
+
cleaned PATH, and a system temp directory inside the repository is
|
|
930
|
+
could-not-run until TMPDIR names one outside it.
|
|
931
|
+
|
|
932
|
+
**git 2.31 or later** is needed on a pull-request run with the secrets-history
|
|
933
|
+
gate (gitleaks) enabled, because conductor hands it `git log --diff-merges`,
|
|
934
|
+
which arrived in git 2.31. Only that gate checks: an older git makes it
|
|
935
|
+
could-not-run, naming the version, and the other gates run.
|
|
936
|
+
|
|
903
937
|
## Intent at a pull request
|
|
904
938
|
|
|
905
939
|
The intent gate is the only one of the five with any ceremony: its native
|
|
@@ -915,7 +949,9 @@ With no `--base`, `GITHUB_BASE_REF` is used when it is set, spelled in full:
|
|
|
915
949
|
`refs/conductor/trust-base` (the Action's private fetch of the base) if that
|
|
916
950
|
exists, else `refs/remotes/origin/<value>`, so a tag of that name cannot
|
|
917
951
|
shadow it. The text report says which. An explicit `--base` that matches both
|
|
918
|
-
a tag and a branch is refused as ambiguous. With neither
|
|
952
|
+
a tag and a branch is refused as ambiguous. With neither but a `--trust-base`
|
|
953
|
+
(merge_group, workflow_dispatch, a CLI run), the change set is measured from
|
|
954
|
+
the trust base. With none of the three, the intent gate runs the way
|
|
919
955
|
it does at a commit: against the staged index, or the paths you name.
|
|
920
956
|
|
|
921
957
|
**This is why a local preview and a pull-request run can disagree about a
|
|
@@ -938,12 +974,31 @@ fallback to an empty path set, because an empty path set is what a passing
|
|
|
938
974
|
gate looks like. In Actions this is almost always a shallow checkout, so
|
|
939
975
|
**`actions/checkout` needs `fetch-depth: 0`** for the merge base to exist.
|
|
940
976
|
|
|
977
|
+
**On a pull-request run the base decides.** With `--trust-base`, whether a
|
|
978
|
+
frozen contract governs the pull request is read from the base ref alone. A
|
|
979
|
+
frozen contract on the base is used, ahead of everything in the list below,
|
|
980
|
+
`--spec` included (the report says so when `--spec` was given), and the gate
|
|
981
|
+
judges any edit to it against the base copy. That holds for every
|
|
982
|
+
intent-guard that can run on a pull-request run, since one older than its
|
|
983
|
+
pull-request-mode minimum is could-not-run rather than run without the base
|
|
984
|
+
ref. With no frozen contract on the
|
|
985
|
+
base, nothing in the pull request becomes the contract: a spec on the base,
|
|
986
|
+
found by rules 1, 3 and 4 below, is imported from its base copy (so on such a
|
|
987
|
+
run `--spec` must be a plain path inside the repository that the base
|
|
988
|
+
carries), and otherwise
|
|
989
|
+
the gate is skipped with "No contract on the base". A contract or spec the
|
|
990
|
+
pull request adds is reported as a proposal, so adopting the intent gate
|
|
991
|
+
merges, and the next pull request is judged against it. Retiring or replacing
|
|
992
|
+
a frozen contract through a judged pull request is refused by the intent gate
|
|
993
|
+
itself and needs an administrator to merge it.
|
|
994
|
+
|
|
941
995
|
**Where the contract comes from**, in order:
|
|
942
996
|
|
|
943
997
|
1. `--spec <path>` on the umbrella's own command line. Typed just now, so it
|
|
944
|
-
outranks everything, and a path here that is not on
|
|
945
|
-
rather than replaced: running a different contract than
|
|
946
|
-
named is the wrong kindness.
|
|
998
|
+
outranks everything else in this list, and a path here that is not on
|
|
999
|
+
disk is reported rather than replaced: running a different contract than
|
|
1000
|
+
the one somebody named is the wrong kindness. On a pull-request run it is
|
|
1001
|
+
read from the base, and a frozen contract on the base takes precedence.
|
|
947
1002
|
2. `<repo>/.intent-guard/intent-contract.yaml`, when it is **frozen**, and
|
|
948
1003
|
`<repo>/.conductor/intent-contract.yaml` after it. The native flow wins
|
|
949
1004
|
wherever a team has done it. Frozen is the test rather than present: an
|
|
@@ -1107,7 +1162,8 @@ provenance even though all four packages publish it.
|
|
|
1107
1162
|
> sigstore outage has the same effect. The audit is retried once after a short
|
|
1108
1163
|
> pause before the step fails, to absorb a one-off registry hiccup. It fails
|
|
1109
1164
|
> closed on purpose, so that is a red gate rather than a skipped check; pin to
|
|
1110
|
-
>
|
|
1165
|
+
> `45d2ecc2213244408495c22d0b8da1dc0f1ed288` (v0.4.0), which does not verify,
|
|
1166
|
+
> if it blocks you.
|
|
1111
1167
|
|
|
1112
1168
|
`--base` is passed only when the `base-ref` input names one; left empty, the
|
|
1113
1169
|
umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
|
|
@@ -1140,14 +1196,16 @@ event the workflow file itself runs from the pull request's own ref, so an
|
|
|
1140
1196
|
opt-out here would be settable by the very pull request the mode exists to
|
|
1141
1197
|
judge: the knob and the thing it protects against would be the same file.
|
|
1142
1198
|
|
|
1143
|
-
**
|
|
1199
|
+
**Pin the action by full commit SHA, with the version in a trailing comment, not by tag and not by path.** `uses: ./` reads
|
|
1144
1200
|
`action.yml` out of whichever tree the workflow runs against, which is
|
|
1145
1201
|
correct only for this repository's own workflows testing themselves; on a
|
|
1146
1202
|
pull request from anywhere else it would read `action.yml` out of the pull
|
|
1147
1203
|
request being judged, and the version-pin protection described above
|
|
1148
1204
|
"protects nothing" against a tree that controls its own judge (the
|
|
1149
|
-
validate step's own comment in `action.yml` says so in those words).
|
|
1150
|
-
this action by owner and
|
|
1205
|
+
validate step's own comment in `action.yml` says so in those words). A tag
|
|
1206
|
+
moves when someone pushes it. Name this action by owner and the full commit
|
|
1207
|
+
SHA instead. The recipes in this README pin the v0.8.0 commit and are
|
|
1208
|
+
updated to the v0.8.1 commit after that release is tagged.
|
|
1151
1209
|
|
|
1152
1210
|
```yaml
|
|
1153
1211
|
name: guardrails
|
|
@@ -1162,12 +1220,14 @@ jobs:
|
|
|
1162
1220
|
steps:
|
|
1163
1221
|
- uses: actions/checkout@v7
|
|
1164
1222
|
with:
|
|
1223
|
+
# From 0.8.0 a shallow checkout on a pull-request run is
|
|
1224
|
+
# could-not-run for the history gate.
|
|
1165
1225
|
fetch-depth: 0
|
|
1166
1226
|
- uses: actions/setup-node@v7
|
|
1167
1227
|
with:
|
|
1168
1228
|
node-version: '22.11.0'
|
|
1169
1229
|
- id: conductor
|
|
1170
|
-
uses: vaultcompasshq/conductor@v0.8.0
|
|
1230
|
+
uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
|
|
1171
1231
|
with:
|
|
1172
1232
|
output: conductor.sarif
|
|
1173
1233
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1177,6 +1237,10 @@ jobs:
|
|
|
1177
1237
|
sarif_file: ${{ steps.conductor.outputs.sarif }}
|
|
1178
1238
|
```
|
|
1179
1239
|
|
|
1240
|
+
The job has `permissions: contents: read`. Add `pull-requests: write` only
|
|
1241
|
+
where the recipe posts a comment. `security-events: write` is there because
|
|
1242
|
+
the upload step publishes the SARIF log.
|
|
1243
|
+
|
|
1180
1244
|
The examples leave the trigger unnarrowed on purpose, so the job runs for a
|
|
1181
1245
|
pull request into any branch. If you narrow it with a `branches:` filter,
|
|
1182
1246
|
include every branch whose merges reach users, release branches and the
|
|
@@ -1185,11 +1249,20 @@ production]`. The pull request that promotes a release is where a bad
|
|
|
1185
1249
|
dependency or a leaked secret actually ships, and a job that is not triggered
|
|
1186
1250
|
leaves no red check and no report to notice.
|
|
1187
1251
|
|
|
1188
|
-
|
|
1189
|
-
|
|
1190
|
-
|
|
1191
|
-
|
|
1192
|
-
|
|
1252
|
+
A job marked `continue-on-error` always concludes green, so a crash of the
|
|
1253
|
+
action is invisible unless someone opens the log. A workflow triggered only
|
|
1254
|
+
on pull requests to main never runs on a stacked pull request whose base is
|
|
1255
|
+
another branch, and no comment on such a pull request does not mean clean.
|
|
1256
|
+
|
|
1257
|
+
Omit `conductor-version`. Left unset, the action installs the default in the
|
|
1258
|
+
pinned `action.yml`, which is the version that commit ships, so the installed
|
|
1259
|
+
umbrella follows the pin and a Dependabot bump is the one `uses` line. If the
|
|
1260
|
+
input is set and is older than the constants in that pinned action.yml, a
|
|
1261
|
+
pull request run is refused and the validate step says to remove the input. A
|
|
1262
|
+
newer value is accepted and is what gets installed. The three gate version
|
|
1263
|
+
inputs can be left out too: each one then takes the default in the pinned
|
|
1264
|
+
action.yml. The spelled-out example below names them when a workflow wants
|
|
1265
|
+
that transparency.
|
|
1193
1266
|
|
|
1194
1267
|
```yaml
|
|
1195
1268
|
name: guardrails
|
|
@@ -1204,11 +1277,13 @@ jobs:
|
|
|
1204
1277
|
steps:
|
|
1205
1278
|
- uses: actions/checkout@v7
|
|
1206
1279
|
with:
|
|
1207
|
-
# Required
|
|
1208
|
-
#
|
|
1209
|
-
#
|
|
1210
|
-
#
|
|
1211
|
-
#
|
|
1280
|
+
# Required. From 0.8.0 a shallow checkout on a pull-request run is
|
|
1281
|
+
# could-not-run for the history gate. Without a full history there
|
|
1282
|
+
# is no merge base to diff against, and the intent gate fails closed
|
|
1283
|
+
# rather than checking an empty set. And the base ref itself has to
|
|
1284
|
+
# be in the clone, because on a pull request the rules are read from
|
|
1285
|
+
# it: a base ref that will not resolve is exit 2 for every enabled
|
|
1286
|
+
# gate.
|
|
1212
1287
|
fetch-depth: 0
|
|
1213
1288
|
- uses: actions/setup-node@v7
|
|
1214
1289
|
with:
|
|
@@ -1224,20 +1299,20 @@ jobs:
|
|
|
1224
1299
|
# policy is read from, before the gates ever start. Your own
|
|
1225
1300
|
# dependencies, build and tests belong in a separate job (see below).
|
|
1226
1301
|
# The gates are not among the things that job has to install: the action
|
|
1227
|
-
# installs those itself, globally
|
|
1302
|
+
# installs those itself, globally. Leave conductor-version unset so the
|
|
1303
|
+
# umbrella is the default in the pinned action.yml.
|
|
1228
1304
|
- id: conductor
|
|
1229
|
-
uses: vaultcompasshq/conductor@v0.8.0
|
|
1305
|
+
uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
|
|
1230
1306
|
with:
|
|
1231
1307
|
output: conductor.sarif
|
|
1232
|
-
# Exact versions, never a range and never "latest". These
|
|
1233
|
-
# lines decide which programs judge a pull request, so a pull
|
|
1308
|
+
# Exact versions, never a range and never "latest". These three
|
|
1309
|
+
# lines decide which gate programs judge a pull request, so a pull
|
|
1234
1310
|
# request's own lockfile no longer does. They are only as protected
|
|
1235
1311
|
# as this file is: require review on .github/workflows in your
|
|
1236
1312
|
# branch protection. Bump them like any other pin, in a pull
|
|
1237
|
-
# request of their own.
|
|
1238
|
-
#
|
|
1239
|
-
# left out entirely to take that
|
|
1240
|
-
conductor-version: 0.8.0
|
|
1313
|
+
# request of their own. On a pull request the action refuses a pin
|
|
1314
|
+
# below what the pinned action.yml ships, and the three lines can
|
|
1315
|
+
# be left out entirely to take that action's own versions.
|
|
1241
1316
|
dep-guard-version: 0.10.0
|
|
1242
1317
|
vault-guard-version: 1.9.0
|
|
1243
1318
|
intent-guard-version: 1.8.0
|
|
@@ -1290,12 +1365,12 @@ because the pull request supplies them, not the workflow file. Branch
|
|
|
1290
1365
|
protection on the workflow directory does not stop them, so the gates must
|
|
1291
1366
|
not share a job with head code that runs first.
|
|
1292
1367
|
|
|
1293
|
-
**With gitleaks enabled the checkout must be `fetch-depth: 0`.**
|
|
1368
|
+
**With gitleaks enabled the checkout must be `fetch-depth: 0`.** From 0.8.0 a
|
|
1369
|
+
shallow checkout on a pull-request run is could-not-run for the history gate,
|
|
1370
|
+
naming `fetch-depth: 0` (exit 2, whatever `enforce` says). At the default
|
|
1294
1371
|
depth of 1 the checkout is shallow, the range from the base to HEAD holds one
|
|
1295
1372
|
grafted commit, and a secret added and then removed inside the pull request
|
|
1296
|
-
would never be seen. conductor
|
|
1297
|
-
history gate as could-not-run, naming `fetch-depth: 0` (exit 2 on a pull
|
|
1298
|
-
request, whatever `enforce` says). It does not deepen the checkout for you.
|
|
1373
|
+
would never be seen. conductor does not deepen the checkout for you.
|
|
1299
1374
|
|
|
1300
1375
|
**The two external gates are installed by your workflow, not by the
|
|
1301
1376
|
Action.** The Action still installs exactly its four npm packages and has no
|
|
@@ -1370,13 +1445,15 @@ jobs:
|
|
|
1370
1445
|
steps:
|
|
1371
1446
|
- uses: actions/checkout@v7
|
|
1372
1447
|
with:
|
|
1448
|
+
# From 0.8.0 a shallow checkout on a pull-request run is
|
|
1449
|
+
# could-not-run for the history gate.
|
|
1373
1450
|
fetch-depth: 0
|
|
1374
1451
|
- uses: actions/setup-node@v7
|
|
1375
1452
|
with:
|
|
1376
1453
|
node-version: '22.11.0'
|
|
1377
1454
|
- id: conductor
|
|
1378
1455
|
timeout-minutes: 5
|
|
1379
|
-
uses: vaultcompasshq/conductor@v0.8.0
|
|
1456
|
+
uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
|
|
1380
1457
|
with:
|
|
1381
1458
|
pr-comment: true
|
|
1382
1459
|
advisory: true
|
|
@@ -1512,7 +1589,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1512
1589
|
# the pull request runs before the action in this job: no install, build
|
|
1513
1590
|
# or test step here; those belong in a separate job. ...
|
|
1514
1591
|
- id: conductor
|
|
1515
|
-
uses: vaultcompasshq/conductor@v0.8.0
|
|
1592
|
+
uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
|
|
1516
1593
|
with:
|
|
1517
1594
|
output: conductor.sarif
|
|
1518
1595
|
pr-comment: true
|
|
@@ -1584,12 +1661,12 @@ per pull request.
|
|
|
1584
1661
|
|
|
1585
1662
|
```yaml
|
|
1586
1663
|
- id: conductor-package-a
|
|
1587
|
-
uses: vaultcompasshq/conductor@v0.8.0
|
|
1664
|
+
uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
|
|
1588
1665
|
with:
|
|
1589
1666
|
pr-comment: true
|
|
1590
1667
|
pr-comment-marker: 'package-a'
|
|
1591
1668
|
- id: conductor-package-b
|
|
1592
|
-
uses: vaultcompasshq/conductor@v0.8.0
|
|
1669
|
+
uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
|
|
1593
1670
|
with:
|
|
1594
1671
|
pr-comment: true
|
|
1595
1672
|
pr-comment-marker: 'package-b'
|
package/dist/cli.js
CHANGED
|
@@ -6,17 +6,18 @@
|
|
|
6
6
|
// parses arguments and prints. That split is what lets every one of those
|
|
7
7
|
// decisions be tested without a subprocess.
|
|
8
8
|
import { Command, CommanderError } from 'commander';
|
|
9
|
-
import { execFileSync } from 'node:child_process';
|
|
10
9
|
import { closeSync, constants as fsConstants, lstatSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from 'node:fs';
|
|
10
|
+
import os from 'node:os';
|
|
11
11
|
import path from 'node:path';
|
|
12
12
|
import { fileURLToPath } from 'node:url';
|
|
13
13
|
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
|
|
14
|
+
import { absolutePathEntries, createGitShim, pinGitOutside, pinnedGitInside, realPathInside, removeGitShim, runGit, tempInsideTreeMessage, workTreeAbove, } from './git.js';
|
|
14
15
|
import { applyInit, planInit, renderInitHuman, renderRevertHuman, revertInit, } from './init.js';
|
|
15
16
|
import { renderSarif } from './output-sarif.js';
|
|
16
|
-
import { jobLogSummary, renderText, verdictToken } from './output-text.js';
|
|
17
|
+
import { gateLogLines, jobLogSummary, renderText, verdictToken, versionSkewWarnings, } from './output-text.js';
|
|
17
18
|
import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
|
|
18
19
|
import { refusedTrustBase, runAll } from './run.js';
|
|
19
|
-
import { headTreeEqualsBase, policyDiffers,
|
|
20
|
+
import { headTreeEqualsBase, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
|
|
20
21
|
const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
|
|
21
22
|
const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
|
|
22
23
|
/**
|
|
@@ -94,31 +95,21 @@ function writeReportFile(target, what, body) {
|
|
|
94
95
|
* the path's spelling.
|
|
95
96
|
*/
|
|
96
97
|
function isGitDirectory(cwd) {
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
cwd,
|
|
100
|
-
encoding: 'utf8',
|
|
101
|
-
stdio: ['ignore', 'pipe', 'ignore'],
|
|
102
|
-
}).trim() === 'true');
|
|
103
|
-
}
|
|
104
|
-
catch {
|
|
105
|
-
return false;
|
|
106
|
-
}
|
|
98
|
+
const result = runGit(cwd, ['rev-parse', '--is-inside-git-dir']);
|
|
99
|
+
return result.error === undefined && result.status === 0 && result.stdout.trim() === 'true';
|
|
107
100
|
}
|
|
108
101
|
function repoRoot(cwd) {
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
encoding: 'utf8',
|
|
113
|
-
stdio: ['ignore', 'pipe', 'ignore'],
|
|
114
|
-
}).trim();
|
|
102
|
+
const result = runGit(cwd, ['rev-parse', '--show-toplevel']);
|
|
103
|
+
if (result.error === undefined && result.status === 0) {
|
|
104
|
+
return result.stdout.trim();
|
|
115
105
|
}
|
|
116
|
-
|
|
117
|
-
|
|
106
|
+
{
|
|
107
|
+
const err = result.error;
|
|
108
|
+
if (err?.code === 'ENOENT') {
|
|
118
109
|
throw new Error('git is not on PATH, so the repository root could not be found. Install git, or ' +
|
|
119
110
|
'run conductor from a shell that has it.');
|
|
120
111
|
}
|
|
121
|
-
if (typeof
|
|
112
|
+
if (err === undefined && typeof result.status === 'number') {
|
|
122
113
|
// git ran and refused. The directory is named because it is the one
|
|
123
114
|
// thing the reader has to check, and it is the directory they typed
|
|
124
115
|
// the command in rather than anything internal to this tool.
|
|
@@ -132,7 +123,7 @@ function repoRoot(cwd) {
|
|
|
132
123
|
// git is there and never got as far as an exit code: a permissions
|
|
133
124
|
// problem, or a machine out of processes. Neither of the two sentences
|
|
134
125
|
// above would be true, so this says what actually happened.
|
|
135
|
-
throw new Error(`git could not be run to find the repository root: ${err
|
|
126
|
+
throw new Error(`git could not be run to find the repository root: ${err?.message ?? 'it did not exit normally'}`);
|
|
136
127
|
}
|
|
137
128
|
}
|
|
138
129
|
/**
|
|
@@ -245,8 +236,31 @@ function inventoryFromHead(root, overrides) {
|
|
|
245
236
|
return { version: 1, gates: {}, report: { format: 'text' } };
|
|
246
237
|
}
|
|
247
238
|
}
|
|
248
|
-
function policyForRun(root, trustBase, overrides, githubBaseRef) {
|
|
239
|
+
function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions) {
|
|
249
240
|
if (trustBase === undefined) {
|
|
241
|
+
// A PULL-REQUEST JOB WITH NO TRUST BASE would take its rules from the
|
|
242
|
+
// tree being judged. In Actions (GITHUB_ACTIONS and GITHUB_BASE_REF both
|
|
243
|
+
// set) that is refused, could-not-run, naming the two ways to clear it.
|
|
244
|
+
// Outside Actions one notice line, and the run goes on as before: a local
|
|
245
|
+
// shell that happens to export GITHUB_BASE_REF is the user's own tree.
|
|
246
|
+
if (githubBaseRef !== undefined && githubBaseRef !== '') {
|
|
247
|
+
const why = `GITHUB_BASE_REF is set to "${githubBaseRef}", so this is a pull-request job, and no ` +
|
|
248
|
+
'--trust-base was given: the policy would come from the tree being judged.';
|
|
249
|
+
if (githubActions === 'true') {
|
|
250
|
+
return {
|
|
251
|
+
kind: 'refused',
|
|
252
|
+
ref: '',
|
|
253
|
+
notGiven: true,
|
|
254
|
+
detail: `${why} Pass --trust-base refs/remotes/origin/${githubBaseRef} (check out with ` +
|
|
255
|
+
'fetch-depth: 0), or use the Action, which passes it. A pre-commit hook run inside ' +
|
|
256
|
+
'a pull-request job (conductor run --staged) hits this too: skip the hook in CI, ' +
|
|
257
|
+
'or pass --trust-base to it. Nothing was checked.',
|
|
258
|
+
inventory: inventoryFromHead(root, overrides),
|
|
259
|
+
};
|
|
260
|
+
}
|
|
261
|
+
process.stderr.write(`conductor: ${why} Outside GitHub Actions the run goes on with the working tree policy; ` +
|
|
262
|
+
'in Actions it is refused. Pass --trust-base for pull-request mode.\n');
|
|
263
|
+
}
|
|
250
264
|
return { kind: 'policy', policy: applyCliOverrides(loadPolicy(root), overrides) };
|
|
251
265
|
}
|
|
252
266
|
// DEFENCE IN DEPTH, ISSUE #58. action.yml's validate step already refuses
|
|
@@ -269,8 +283,24 @@ function policyForRun(root, trustBase, overrides, githubBaseRef) {
|
|
|
269
283
|
inventory: inventoryFromHead(root, overrides),
|
|
270
284
|
};
|
|
271
285
|
}
|
|
272
|
-
const
|
|
273
|
-
const
|
|
286
|
+
const baseRead = readFileAtRef(root, trustBase, POLICY_FILE_NAME);
|
|
287
|
+
const headRead = readFileAtRef(root, 'HEAD', POLICY_FILE_NAME);
|
|
288
|
+
if (baseRead.kind === 'error') {
|
|
289
|
+
// UNREADABLE IS NOT ABSENT. The base may carry a policy, and nothing was
|
|
290
|
+
// judged against it, so this is the could-not-run refusal with git's own
|
|
291
|
+
// reason, never the "run conductor init" sentence below and never a run
|
|
292
|
+
// under any other policy.
|
|
293
|
+
return {
|
|
294
|
+
kind: 'refused',
|
|
295
|
+
ref: trustBase,
|
|
296
|
+
detail: `cannot read ${POLICY_FILE_NAME} at "${trustBase}": ${baseRead.detail}. On a pull-request ` +
|
|
297
|
+
`run every rule comes from the base ref, so nothing was checked. ` +
|
|
298
|
+
unreadableBaseRemedy(POLICY_FILE_NAME),
|
|
299
|
+
inventory: inventoryFromHead(root, overrides),
|
|
300
|
+
};
|
|
301
|
+
}
|
|
302
|
+
const baseText = baseRead.kind === 'file' ? baseRead.text : null;
|
|
303
|
+
const headText = headRead.kind === 'file' ? headRead.text : null;
|
|
274
304
|
if (baseText === null) {
|
|
275
305
|
// CONFIG ABSENT ON THE BASE, not a policy error thrown from here. The old
|
|
276
306
|
// shape threw a PolicyError, which the run command's catch prints as one
|
|
@@ -318,7 +348,9 @@ function policyForRun(root, trustBase, overrides, githubBaseRef) {
|
|
|
318
348
|
policy: applyCliOverrides(parsePolicy(baseText, `${trustBase}:${POLICY_FILE_NAME}`), overrides),
|
|
319
349
|
trustBase: {
|
|
320
350
|
ref: trustBase,
|
|
321
|
-
|
|
351
|
+
// A head file git could not read is reported as a change, the
|
|
352
|
+
// fail-closed direction: it is never taken to match the base.
|
|
353
|
+
policyChanged: headRead.kind === 'error' ? true : policyDiffers(baseText, headText),
|
|
322
354
|
refusal: null,
|
|
323
355
|
// Computed AFTER refuseTrustBaseRef has already returned null, on the
|
|
324
356
|
// one shape that check accepts despite an identical tree: a merge
|
|
@@ -329,6 +361,63 @@ function policyForRun(root, trustBase, overrides, githubBaseRef) {
|
|
|
329
361
|
},
|
|
330
362
|
};
|
|
331
363
|
}
|
|
364
|
+
/**
|
|
365
|
+
* On a run with a trust base: removes every PATH entry that resolves against
|
|
366
|
+
* the working directory, for this process and for every child it starts,
|
|
367
|
+
* says what it removed, and pins git to the first git on PATH whose real path
|
|
368
|
+
* is outside the repository's work tree.
|
|
369
|
+
*
|
|
370
|
+
* Nearly every child runs with the repository root as its working directory,
|
|
371
|
+
* and that tree is the one under judgment, so every PATH lookup resolves
|
|
372
|
+
* against an absolute directory, and conductor's own git is never a program
|
|
373
|
+
* inside that tree. An absolute PATH entry inside the tree is kept: a gate
|
|
374
|
+
* installed as a dependency is reached that way, and the program check
|
|
375
|
+
* (refuseHeadControlledProgram) governs it. Runs without a trust base keep
|
|
376
|
+
* PATH exactly as given: a local hook commonly relies on a relative entry,
|
|
377
|
+
* and the tree there is the user's own. A gate that can no longer be found
|
|
378
|
+
* is the ordinary gate-missing outcome, cleared with an absolute PATH entry
|
|
379
|
+
* or an absolute command:.
|
|
380
|
+
*
|
|
381
|
+
* The work tree is found without running git (`workTreeAbove`), from the
|
|
382
|
+
* directory the run starts in; the caller checks the pinned git again
|
|
383
|
+
* against the root git then reports.
|
|
384
|
+
*
|
|
385
|
+
* Then puts a private directory first on PATH for this process and every
|
|
386
|
+
* child (`createGitShim`): a directory outside the tree holding only a link
|
|
387
|
+
* named git to the pinned program, so a gate, or anything a gate starts, that
|
|
388
|
+
* looks git up by name runs the pinned git even when an absolute PATH entry
|
|
389
|
+
* inside the tree holds a git of its own. Returns that directory, for the
|
|
390
|
+
* caller to remove when the run ends, or null on Windows, where none is made.
|
|
391
|
+
*/
|
|
392
|
+
function pinPathForTrustBase(start) {
|
|
393
|
+
const { value, removed } = absolutePathEntries(process.env.PATH ?? '');
|
|
394
|
+
if (removed.length > 0) {
|
|
395
|
+
process.env.PATH = value;
|
|
396
|
+
process.stderr.write(`conductor: pull-request mode removed ${removed.length} PATH ` +
|
|
397
|
+
`${removed.length === 1 ? 'entry' : 'entries'} that resolve against the working ` +
|
|
398
|
+
`directory (${removed.map((entry) => JSON.stringify(entry)).join(', ')}), which on a ` +
|
|
399
|
+
'pull-request run is the tree being judged. Use absolute PATH entries for any tool a ' +
|
|
400
|
+
'gate needs.\n');
|
|
401
|
+
}
|
|
402
|
+
const workTree = workTreeAbove(start);
|
|
403
|
+
const excluded = workTree === null ? [start] : [workTree];
|
|
404
|
+
const pinned = pinGitOutside(value, excluded);
|
|
405
|
+
if (pinned === null) {
|
|
406
|
+
throw new Error(noGitOutsideMessage());
|
|
407
|
+
}
|
|
408
|
+
const shim = createGitShim(pinned, os.tmpdir(), excluded);
|
|
409
|
+
if (shim !== null) {
|
|
410
|
+
// Never a trailing separator: an empty entry would mean the working
|
|
411
|
+
// directory, which is the tree being judged.
|
|
412
|
+
process.env.PATH = value === '' ? shim : `${shim}${path.delimiter}${value}`;
|
|
413
|
+
}
|
|
414
|
+
return shim;
|
|
415
|
+
}
|
|
416
|
+
function noGitOutsideMessage() {
|
|
417
|
+
return ('no git outside the repository was found on PATH. On a pull-request run conductor runs ' +
|
|
418
|
+
'git only from a directory outside the tree being judged. Put the directory that holds ' +
|
|
419
|
+
'your git installation on PATH as an absolute entry. Nothing was checked.');
|
|
420
|
+
}
|
|
332
421
|
function parseFormat(value) {
|
|
333
422
|
if (value !== 'text' && value !== 'sarif') {
|
|
334
423
|
throw new PolicyError(`--format must be "text" or "sarif", got "${value}".`);
|
|
@@ -478,7 +567,7 @@ export function buildProgram() {
|
|
|
478
567
|
.option('--trust-base <ref>', 'pull-request mode: read .guardrails.yaml from this ref instead of from the tree being judged, and pass the same ref to every gate that supports it. A policy change in the pull request is reported as a proposal and never takes effect for the run, so a pull request cannot change the rules it is judged by. In Actions the composite action fetches the base branch and passes its full commit id on a pull_request event.')
|
|
479
568
|
.option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
|
|
480
569
|
.option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, nothing-checked (exit 0 but no gate ran), advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
|
|
481
|
-
.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')
|
|
570
|
+
.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. On a pull-request run (--trust-base) the spec is read from the base ref, and a frozen contract on the base takes precedence over it')
|
|
482
571
|
.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.')
|
|
483
572
|
.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.')
|
|
484
573
|
.option('--gate <role>', 'restrict the run to this role; repeatable', (value, previous = []) => [...previous, value])
|
|
@@ -488,19 +577,35 @@ export function buildProgram() {
|
|
|
488
577
|
.action((options) => {
|
|
489
578
|
const cwd = process.cwd();
|
|
490
579
|
let textReportPath;
|
|
580
|
+
// The private git directory of a trust-base run, removed in the
|
|
581
|
+
// finally below on every way out of this action.
|
|
582
|
+
let gitShim = null;
|
|
491
583
|
try {
|
|
584
|
+
// BEFORE ANY GIT CALL, including the one that finds the repository.
|
|
585
|
+
if (options.trustBase !== undefined) {
|
|
586
|
+
gitShim = pinPathForTrustBase(options.project === undefined ? cwd : path.resolve(cwd, options.project));
|
|
587
|
+
}
|
|
492
588
|
// Inside the try, because resolveProjectRoot (like repoRoot before
|
|
493
589
|
// it) reports rather than guesses, and the catch below is what turns
|
|
494
590
|
// any of its sentences into one line on stderr and the could-not-run
|
|
495
591
|
// exit code.
|
|
496
592
|
const root = resolveProjectRoot(cwd, options.project);
|
|
593
|
+
// And once more against the root git reported, which is the tree the
|
|
594
|
+
// gates judge: the pinned git is never a program inside it.
|
|
595
|
+
if (options.trustBase !== undefined && pinnedGitInside(root)) {
|
|
596
|
+
throw new Error(noGitOutsideMessage());
|
|
597
|
+
}
|
|
598
|
+
// The same for the private git directory: never inside that tree.
|
|
599
|
+
if (gitShim !== null && realPathInside(root, gitShim)) {
|
|
600
|
+
throw new Error(tempInsideTreeMessage(os.tmpdir()));
|
|
601
|
+
}
|
|
497
602
|
const overrides = {
|
|
498
603
|
...(parseRoles(options.gate) === undefined
|
|
499
604
|
? {}
|
|
500
605
|
: { gates: parseRoles(options.gate) }),
|
|
501
606
|
};
|
|
502
607
|
const stage = parseStage(options.stage);
|
|
503
|
-
const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF);
|
|
608
|
+
const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF, process.env.GITHUB_ACTIONS);
|
|
504
609
|
const policy = source.kind === 'policy' ? source.policy : source.inventory;
|
|
505
610
|
const format = parseFormat(options.format ?? policy.report.format);
|
|
506
611
|
// BEFORE ANY GATE RUNS. With --format text the text report already is
|
|
@@ -514,6 +619,7 @@ export function buildProgram() {
|
|
|
514
619
|
const result = source.kind === 'refused'
|
|
515
620
|
? refusedTrustBase(source.inventory, source.ref, source.detail, {
|
|
516
621
|
...(stage === undefined ? {} : { stage }),
|
|
622
|
+
...(source.notGiven === true ? { notGiven: true } : {}),
|
|
517
623
|
})
|
|
518
624
|
: runAll(source.policy, {
|
|
519
625
|
repoRoot: root,
|
|
@@ -576,6 +682,17 @@ export function buildProgram() {
|
|
|
576
682
|
process.stdout.write(`conductor run: ${jobLogSummary(result)}; verdict-token ${verdictToken(result, advisory)}; ` +
|
|
577
683
|
`${format} report written to ${options.output}\n`);
|
|
578
684
|
}
|
|
685
|
+
// One plain line per gate on stderr, on every run and after the report
|
|
686
|
+
// is out, so the job log says which gate did what and why without
|
|
687
|
+
// anybody opening a report. stderr rather than stdout so that stdout
|
|
688
|
+
// stays exactly the report (SARIF or text) for a caller that pipes it.
|
|
689
|
+
// Written after the report file, so a failure above still takes the
|
|
690
|
+
// catch below and these lines never describe a run that then exits 2
|
|
691
|
+
// for an unwritable file.
|
|
692
|
+
const logLines = [...gateLogLines(result), ...versionSkewWarnings(result)];
|
|
693
|
+
if (logLines.length > 0) {
|
|
694
|
+
process.stderr.write(`${logLines.join('\n')}\n`);
|
|
695
|
+
}
|
|
579
696
|
process.exitCode = applyAdvisory(result.exitCode, advisory);
|
|
580
697
|
}
|
|
581
698
|
catch (err) {
|
|
@@ -606,6 +723,11 @@ export function buildProgram() {
|
|
|
606
723
|
? err.message
|
|
607
724
|
: `conductor: ${err instanceof Error ? err.message : String(err)}`);
|
|
608
725
|
}
|
|
726
|
+
finally {
|
|
727
|
+
if (gitShim !== null) {
|
|
728
|
+
removeGitShim(gitShim);
|
|
729
|
+
}
|
|
730
|
+
}
|
|
609
731
|
});
|
|
610
732
|
return program;
|
|
611
733
|
}
|
|
@@ -41,7 +41,8 @@ export declare function extendPath(config: string): string | null;
|
|
|
41
41
|
* a nested file added or edited by the pull request has no effect on the run
|
|
42
42
|
* (measured against 2.6.0: a nested file ignoring lodash passes without
|
|
43
43
|
* --config and blocks with it). It is still a change to how the tool behaves
|
|
44
|
-
* once merged, so it is reported the way the root config is.
|
|
44
|
+
* once merged, so it is reported the way the root config is. A base copy git
|
|
45
|
+
* could not read throws ExternalConfigError, like every other base read here.
|
|
45
46
|
*/
|
|
46
47
|
export declare function nestedConfigProposals(repoRoot: string, trustBase: string, trackedFiles: readonly string[], configFile: string): string[];
|
|
47
48
|
export declare function materializeExternalConfig(args: {
|