@vaultcompass/conductor 0.17.0 → 0.18.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 +60 -47
- package/dist/cli.js +5 -5
- package/dist/escape.d.ts +9 -0
- package/dist/escape.js +14 -0
- package/dist/gate-runner.d.ts +1 -0
- package/dist/gate-runner.js +1 -1
- package/dist/intent-prepare.js +3 -6
- package/dist/osv-coverage.js +6 -5
- package/dist/output-sarif.js +48 -3
- package/dist/output-text.d.ts +20 -2
- package/dist/output-text.js +55 -10
- package/dist/policy-diff.d.ts +2 -9
- package/dist/policy-diff.js +4 -11
- package/dist/rule-ids.d.ts +41 -0
- package/dist/rule-ids.js +98 -0
- package/dist/run.d.ts +11 -1
- package/dist/trust-base.d.ts +24 -6
- package/dist/trust-base.js +41 -9
- package/dist/unread-manifests.d.ts +1 -1
- package/dist/unread-manifests.js +25 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -60,7 +60,7 @@ jobs:
|
|
|
60
60
|
gates:
|
|
61
61
|
runs-on: ubuntu-latest
|
|
62
62
|
steps:
|
|
63
|
-
- uses: actions/checkout@v7
|
|
63
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
64
64
|
with:
|
|
65
65
|
fetch-depth: 0
|
|
66
66
|
- name: Install gitleaks and osv-scanner
|
|
@@ -76,8 +76,8 @@ jobs:
|
|
|
76
76
|
echo "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108 $bin/osv-scanner" | sha256sum -c -
|
|
77
77
|
chmod +x "$bin/osv-scanner"
|
|
78
78
|
echo "$bin" >> "$GITHUB_PATH"
|
|
79
|
-
- uses: vaultcompasshq/conductor@
|
|
80
|
-
- uses: github/codeql-action/upload-sarif@v4
|
|
79
|
+
- uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
|
|
80
|
+
- uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
|
|
81
81
|
if: always()
|
|
82
82
|
with:
|
|
83
83
|
sarif_file: conductor.sarif
|
|
@@ -151,7 +151,7 @@ required.
|
|
|
151
151
|
product: osv-scanner
|
|
152
152
|
```
|
|
153
153
|
|
|
154
|
-
**
|
|
154
|
+
**Install globally; that is the guidance for CI too.** A devDependency is
|
|
155
155
|
fine beside it for your own pre-commit hook, and nothing about a local
|
|
156
156
|
run changed, but under the Action keep it at the Action's pin or a push
|
|
157
157
|
run is could-not-run (see "The Action" below). It is not what gates
|
|
@@ -229,7 +229,7 @@ required.
|
|
|
229
229
|
|
|
230
230
|
Your terminal also shows one status line per gate, written to stderr so a
|
|
231
231
|
CI job log has a per-gate record even when the report goes to a file,
|
|
232
|
-
such as `conductor: gate dependencies (dep-guard 0.
|
|
232
|
+
such as `conductor: gate dependencies (dep-guard 0.20.0): ok, exit 0` or
|
|
233
233
|
a `skipped (deferred to stage ci)` line for a deferred gate. They carry
|
|
234
234
|
nothing the summary does not; to see only the summary, redirect stderr
|
|
235
235
|
(`conductor run --staged --stage commit 2>/dev/null` in the hook).
|
|
@@ -237,15 +237,15 @@ required.
|
|
|
237
237
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
238
238
|
|
|
239
239
|
```
|
|
240
|
-
conductor 0.
|
|
240
|
+
conductor 0.18.1
|
|
241
241
|
verdict-token: blocked (1)
|
|
242
242
|
conductor run: 2 gate(s), 1 finding(s)
|
|
243
243
|
|
|
244
|
-
dependencies dep-guard 0.
|
|
244
|
+
dependencies dep-guard 0.20.0 exit 0 153ms via dep-guard on path
|
|
245
245
|
threshold medium suppressed 0 ignored 0
|
|
246
246
|
mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online false lookups 0 skipped-by-deadline 0
|
|
247
247
|
|
|
248
|
-
secrets vault-guard 1.13.
|
|
248
|
+
secrets vault-guard 1.13.3 exit 1 105ms via vault-guard on path
|
|
249
249
|
BLOCKING critical vault-guard/anthropic jest.config.mjs:14:12
|
|
250
250
|
Possible secret of type 'anthropic'
|
|
251
251
|
threshold medium suppressed 0 ignored not reported
|
|
@@ -287,8 +287,8 @@ required.
|
|
|
287
287
|
|
|
288
288
|
2. **Open the first pull request in advisory mode.** Add `.guardrails.yaml`
|
|
289
289
|
and the workflow together, with `advisory: true` and `pr-comment: true`
|
|
290
|
-
on the conductor step
|
|
291
|
-
advisory check" below is a complete copy-paste job
|
|
290
|
+
on the conductor step (the recipe under "Running the gates as an
|
|
291
|
+
advisory check" below is a complete copy-paste job), and leave the check
|
|
292
292
|
out of branch protection for this one pull request. The step still exits
|
|
293
293
|
2 on this pull request even with `advisory: true`: the base branch has no
|
|
294
294
|
policy yet, so the run has no rules, and `advisory` never touches that
|
|
@@ -305,7 +305,7 @@ required.
|
|
|
305
305
|
|
|
306
306
|
4. **Go required.** Once a few ordinary pull requests have shown the report
|
|
307
307
|
reads the way you expect, remove `advisory: true` from the conductor step
|
|
308
|
-
and require the job's own check context in branch protection
|
|
308
|
+
and require the job's own check context in branch protection: `gates`
|
|
309
309
|
in the recipes below, the job name, never the context the SARIF-upload
|
|
310
310
|
step reports under. That is the whole of turning this from an advisory
|
|
311
311
|
job into the one required check.
|
|
@@ -382,8 +382,11 @@ it is what makes a team switch a hook off.
|
|
|
382
382
|
It is not a sixth gate. It finds no bugs of its own and scans nothing.
|
|
383
383
|
Every finding about your code came from one of the five gates and is
|
|
384
384
|
labelled with which one. The only findings it adds are about the gates
|
|
385
|
-
themselves, and they are labelled `conductor
|
|
386
|
-
|
|
385
|
+
themselves, and they are labelled `conductor`. Three can fail a run; the rest
|
|
386
|
+
are non-blocking notes, all listed under "What is in and what is out" below.
|
|
387
|
+
The main ones are a gate that is switched on and could not run, and a gate
|
|
388
|
+
whose output it could not read.
|
|
389
|
+
Those exist
|
|
387
390
|
because a report that reads clean when nothing looked is the failure this
|
|
388
391
|
whole family exists to prevent.
|
|
389
392
|
|
|
@@ -505,7 +508,14 @@ its configuration from the base branch and the pull request cannot change the
|
|
|
505
508
|
rules it is judged by; a change to the rules shows as a proposal line and
|
|
506
509
|
takes effect after merge. See
|
|
507
510
|
[The pull-request trust boundary](docs/pull-request-trust-boundary.md). On any
|
|
508
|
-
other event it passes nothing and behaviour is unchanged.
|
|
511
|
+
other event it passes nothing and behaviour is unchanged. One shape passes a
|
|
512
|
+
different commit: when the base branch has moved to a commit with the exact
|
|
513
|
+
tree of the run's merge ref, as when a pull request lands while its job is
|
|
514
|
+
queued, that commit cannot judge the run, so the step moves the private ref to
|
|
515
|
+
the commit the merge ref was built from and prints a notice naming both. That
|
|
516
|
+
needs a full clone (`fetch-depth: 0`) and every control file listed in
|
|
517
|
+
[The pull-request trust boundary](docs/pull-request-trust-boundary.md) the same
|
|
518
|
+
at both commits; otherwise the run stays could-not-run, exit 2. The `trust-base`
|
|
509
519
|
input names the ref explicitly, for a platform where `GITHUB_BASE_REF` is not
|
|
510
520
|
set. **On a `pull_request` or `pull_request_target` event this input is
|
|
511
521
|
refused outright, in the validate step** (issue #58). On `pull_request` the
|
|
@@ -532,8 +542,8 @@ request being judged, and the version-pin protection described above
|
|
|
532
542
|
"protects nothing" against a tree that controls its own judge (the
|
|
533
543
|
validate step's own comment in `action.yml` says so in those words). A tag
|
|
534
544
|
moves when someone pushes it. Name this action by owner and the full commit
|
|
535
|
-
SHA instead. The recipes in this README name v0.
|
|
536
|
-
`vaultcompasshq/conductor@
|
|
545
|
+
SHA instead. The recipes in this README name v0.18.0 that way, as
|
|
546
|
+
`vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0`.
|
|
537
547
|
|
|
538
548
|
```yaml
|
|
539
549
|
name: guardrails
|
|
@@ -546,7 +556,7 @@ jobs:
|
|
|
546
556
|
contents: read
|
|
547
557
|
security-events: write
|
|
548
558
|
steps:
|
|
549
|
-
- uses: actions/checkout@v7
|
|
559
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
550
560
|
with:
|
|
551
561
|
# From 0.8.0 a shallow checkout on a pull-request run is
|
|
552
562
|
# could-not-run for the history gate.
|
|
@@ -555,10 +565,10 @@ jobs:
|
|
|
555
565
|
with:
|
|
556
566
|
node-version: '22.23.4'
|
|
557
567
|
- id: conductor
|
|
558
|
-
uses: vaultcompasshq/conductor@
|
|
568
|
+
uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
|
|
559
569
|
with:
|
|
560
570
|
output: conductor.sarif
|
|
561
|
-
- uses: github/codeql-action/upload-sarif@
|
|
571
|
+
- uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
|
|
562
572
|
if: always()
|
|
563
573
|
continue-on-error: true
|
|
564
574
|
with:
|
|
@@ -599,8 +609,8 @@ refuses a pin below them, and that bump's own pull request goes red with
|
|
|
599
609
|
nothing wrong in it. The fix is in the same pull request: raise each pinned
|
|
600
610
|
line to the new tag's default (the CHANGELOG entry for the tag lists them,
|
|
601
611
|
and so does the table in [Upgrading](docs/upgrading.md)), or delete it. The
|
|
602
|
-
|
|
603
|
-
|
|
612
|
+
example below leaves them out for that reason; add an exact forward pin when
|
|
613
|
+
a workflow needs one, and accept that it then has to be raised by hand.
|
|
604
614
|
|
|
605
615
|
**The gates the Action installs are as new as the tag** (issue 146). A
|
|
606
616
|
tag's defaults can reach npm the same day the tag does, so they can be
|
|
@@ -625,7 +635,7 @@ jobs:
|
|
|
625
635
|
contents: read
|
|
626
636
|
security-events: write
|
|
627
637
|
steps:
|
|
628
|
-
- uses: actions/checkout@v7
|
|
638
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
629
639
|
with:
|
|
630
640
|
# Required. From 0.8.0 a shallow checkout on a pull-request run is
|
|
631
641
|
# could-not-run for the history gate. Without a full history there
|
|
@@ -654,21 +664,18 @@ jobs:
|
|
|
654
664
|
# installs those itself, globally. Leave conductor-version unset so the
|
|
655
665
|
# umbrella is the default in the pinned action.yml.
|
|
656
666
|
- id: conductor
|
|
657
|
-
uses: vaultcompasshq/conductor@
|
|
667
|
+
uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
|
|
658
668
|
with:
|
|
659
669
|
output: conductor.sarif
|
|
660
|
-
#
|
|
661
|
-
#
|
|
662
|
-
#
|
|
663
|
-
#
|
|
664
|
-
#
|
|
665
|
-
#
|
|
666
|
-
#
|
|
667
|
-
#
|
|
668
|
-
|
|
669
|
-
vault-guard-version: 1.13.1
|
|
670
|
-
intent-guard-version: 1.10.4
|
|
671
|
-
- uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
|
|
670
|
+
# The gate versions are left out on purpose: the defaults travel
|
|
671
|
+
# with the tag above, so a bump of that line moves the gates with it.
|
|
672
|
+
# To pin a gate forward, add an exact version such as
|
|
673
|
+
# `dep-guard-version: x.y.z`, never a range and never "latest". A
|
|
674
|
+
# pin decides which gate program judges a pull request, so it is
|
|
675
|
+
# only as protected as this file is: require review on
|
|
676
|
+
# .github/workflows in your branch protection. On a pull request the
|
|
677
|
+
# action refuses a pin below what the pinned action.yml ships.
|
|
678
|
+
- uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
|
|
672
679
|
# Always: the log is most worth having on the run that failed.
|
|
673
680
|
if: always()
|
|
674
681
|
# The sarif path is published BEFORE the gates run, so on the exit 2
|
|
@@ -687,7 +694,7 @@ jobs:
|
|
|
687
694
|
build:
|
|
688
695
|
runs-on: ubuntu-latest
|
|
689
696
|
steps:
|
|
690
|
-
- uses: actions/checkout@v7
|
|
697
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
691
698
|
- uses: pnpm/action-setup@v4
|
|
692
699
|
- uses: actions/setup-node@v7
|
|
693
700
|
with:
|
|
@@ -710,8 +717,12 @@ keeping pull-request code out of the job covers the rest: `GITHUB_ENV`
|
|
|
710
717
|
(`NODE_OPTIONS=--require`, `GIT_CONFIG_*`, `GIT_DIR`), `GITHUB_PATH`,
|
|
711
718
|
`.git/config` changes (a remote URL, `url.insteadOf`, `core.fsmonitor`,
|
|
712
719
|
credential helpers, `core.sshCommand`), git hooks such as
|
|
713
|
-
`reference-transaction`, and replace refs or grafts.
|
|
714
|
-
|
|
720
|
+
`reference-transaction`, and replace refs or grafts. (The action's fetch, gates
|
|
721
|
+
and fallback render steps set `GIT_NO_REPLACE_OBJECTS=1` for themselves and
|
|
722
|
+
for the gates they run, which narrows replace refs. The fetch step alone also
|
|
723
|
+
reads through a graft file, for its decision to move the trust base; the gates
|
|
724
|
+
and the CLI still see one.)
|
|
725
|
+
Say it plainly: package.json lifecycle scripts (`preinstall`, `install`, `postinstall`,
|
|
715
726
|
`prepare`) run by an install bypass "require review on `.github/workflows`",
|
|
716
727
|
because the pull request supplies them, not the workflow file. Branch
|
|
717
728
|
protection on the workflow directory does not stop them, so the gates must
|
|
@@ -862,7 +873,7 @@ jobs:
|
|
|
862
873
|
contents: read
|
|
863
874
|
pull-requests: write
|
|
864
875
|
steps:
|
|
865
|
-
- uses: actions/checkout@v7
|
|
876
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
866
877
|
with:
|
|
867
878
|
# From 0.8.0 a shallow checkout on a pull-request run is
|
|
868
879
|
# could-not-run for the history gate.
|
|
@@ -876,7 +887,7 @@ jobs:
|
|
|
876
887
|
# seconds) plus 300 seconds for the preview, rounded up. A step
|
|
877
888
|
# timeout below that can kill a full gitleaks scan and leave no verdict.
|
|
878
889
|
timeout-minutes: 30
|
|
879
|
-
uses: vaultcompasshq/conductor@
|
|
890
|
+
uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
|
|
880
891
|
with:
|
|
881
892
|
pr-comment: true
|
|
882
893
|
advisory: true
|
|
@@ -1012,7 +1023,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1012
1023
|
# the pull request runs before the action in this job: no install, build
|
|
1013
1024
|
# or test step here; those belong in a separate job. ...
|
|
1014
1025
|
- id: conductor
|
|
1015
|
-
uses: vaultcompasshq/conductor@
|
|
1026
|
+
uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
|
|
1016
1027
|
with:
|
|
1017
1028
|
output: conductor.sarif
|
|
1018
1029
|
pr-comment: true
|
|
@@ -1091,12 +1102,12 @@ per pull request.
|
|
|
1091
1102
|
|
|
1092
1103
|
```yaml
|
|
1093
1104
|
- id: conductor-package-a
|
|
1094
|
-
uses: vaultcompasshq/conductor@
|
|
1105
|
+
uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
|
|
1095
1106
|
with:
|
|
1096
1107
|
pr-comment: true
|
|
1097
1108
|
pr-comment-marker: 'package-a'
|
|
1098
1109
|
- id: conductor-package-b
|
|
1099
|
-
uses: vaultcompasshq/conductor@
|
|
1110
|
+
uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
|
|
1100
1111
|
with:
|
|
1101
1112
|
pr-comment: true
|
|
1102
1113
|
pr-comment-marker: 'package-b'
|
|
@@ -1214,12 +1225,14 @@ binary (the adopter installs gitleaks and osv-scanner), and any finding of
|
|
|
1214
1225
|
the umbrella's own about
|
|
1215
1226
|
anybody's CODE. The findings it does raise are all about the gates
|
|
1216
1227
|
themselves: `conductor/gate-missing`, `conductor/gate-output-unparseable`
|
|
1217
|
-
and `conductor/gate-failed`,
|
|
1218
|
-
`conductor/blocking-count-mismatch` and
|
|
1219
|
-
`conductor/blocking-threshold-unknown
|
|
1228
|
+
and `conductor/gate-failed`, which count toward the exit code, and diagnostics
|
|
1229
|
+
that never do: `conductor/blocking-count-mismatch` and
|
|
1230
|
+
`conductor/blocking-threshold-unknown`, plus the `conductor/` notes on what the
|
|
1231
|
+
vulnerabilities gate was handed and how it was run, such as
|
|
1232
|
+
`conductor/lockfiles-empty`.
|
|
1220
1233
|
|
|
1221
1234
|
Also out: intent at the cohesion level, which is what a merge or a
|
|
1222
|
-
promotion would want
|
|
1235
|
+
promotion would want; and anything that
|
|
1223
1236
|
runs inside an agent session or on save, which intent-guard's own optional
|
|
1224
1237
|
session hooks already cover.
|
|
1225
1238
|
|
package/dist/cli.js
CHANGED
|
@@ -18,7 +18,7 @@ import { gateLogLines, jobLogSummary, previewLogLines, proposalLogLines, renderT
|
|
|
18
18
|
import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
|
|
19
19
|
import { diffPolicies, previewPolicy, previewRoles } from './policy-diff.js';
|
|
20
20
|
import { refusedTrustBase, runAll } from './run.js';
|
|
21
|
-
import { headTreeEqualsBase, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
|
|
21
|
+
import { headTreeEqualsBase, withMovedBaseTip, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
|
|
22
22
|
const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
|
|
23
23
|
const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
|
|
24
24
|
/**
|
|
@@ -631,10 +631,10 @@ export function buildProgram() {
|
|
|
631
631
|
.option('--preview', 'pull-request mode only: when the pull request changes a gate\'s enabled or stage, run those gates once more under the proposed values, as a preview that never changes the exit code or the verdict. Every other policy key still comes from the base ref, and so do the gitleaks and osv-scanner configs; dep-guard and vault-guard read their own config files from the head. Not on --staged.')
|
|
632
632
|
.option('--format <format>', 'output format: text or sarif')
|
|
633
633
|
.option('--stage <stage>', `which stopping point this run is: ${GATE_STAGES.join(', ')}. Stages are cumulative, so a gate runs at its own stage and every later one. Omit it to run every enabled gate.`)
|
|
634
|
-
.option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to the base
|
|
635
|
-
.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.')
|
|
634
|
+
.option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to the base the action resolved (refs/conductor/trust-base, else refs/remotes/origin/<GITHUB_BASE_REF>, as a commit id) when GITHUB_BASE_REF is set.')
|
|
635
|
+
.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, or the commit the merge ref was built from when the fetched tip has the merge ref\'s exact tree.')
|
|
636
636
|
.option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
|
|
637
|
-
.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 nothing was checked: no gate ran, or every gate that ran had nothing to scan, read no packages,
|
|
637
|
+
.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 nothing was checked: no gate ran, or every gate that ran had nothing to scan, read no packages, had no contract, or was handed an empty change set), 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).')
|
|
638
638
|
.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')
|
|
639
639
|
.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.')
|
|
640
640
|
.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.')
|
|
@@ -697,7 +697,7 @@ export function buildProgram() {
|
|
|
697
697
|
...(stage === undefined ? {} : { stage }),
|
|
698
698
|
...(options.base === undefined ? {} : { base: options.base }),
|
|
699
699
|
...(options.spec === undefined ? {} : { spec: options.spec }),
|
|
700
|
-
...(source.trustBase === undefined ? {} : { trustBase: source.trustBase }),
|
|
700
|
+
...(source.trustBase === undefined ? {} : { trustBase: withMovedBaseTip(root, source.trustBase, process.env.CONDUCTOR_BASE_TIP) }),
|
|
701
701
|
// Only on request, never on --staged, and only with a trust
|
|
702
702
|
// base and a preview policy: a head that parsed and changed
|
|
703
703
|
// at least one role's enabled or stage.
|
package/dist/escape.d.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Every character outside printable ASCII as a \uXXXX escape (an astral
|
|
3
|
+
* character as its two surrogate escapes), so head-chosen text cannot smuggle
|
|
4
|
+
* a bidi override or a zero-width character into the report. Used for a head
|
|
5
|
+
* policy value (renderValue, src/policy-diff.ts), and for every preview line
|
|
6
|
+
* (cleanPreviewLine, src/gate-runner.ts), whose gate text the head's own
|
|
7
|
+
* control files can choose (audit 2026-10-27, N3).
|
|
8
|
+
*/
|
|
9
|
+
export declare function escapeNonAscii(text: string): string;
|
package/dist/escape.js
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
// Pure text sanitizers with no dependency on any other module here, so a
|
|
2
|
+
// renderer or the gate runner can import them without importing the policy
|
|
3
|
+
// diff or anything heavier.
|
|
4
|
+
/**
|
|
5
|
+
* Every character outside printable ASCII as a \uXXXX escape (an astral
|
|
6
|
+
* character as its two surrogate escapes), so head-chosen text cannot smuggle
|
|
7
|
+
* a bidi override or a zero-width character into the report. Used for a head
|
|
8
|
+
* policy value (renderValue, src/policy-diff.ts), and for every preview line
|
|
9
|
+
* (cleanPreviewLine, src/gate-runner.ts), whose gate text the head's own
|
|
10
|
+
* control files can choose (audit 2026-10-27, N3).
|
|
11
|
+
*/
|
|
12
|
+
export function escapeNonAscii(text) {
|
|
13
|
+
return text.replace(/[^\x20-\x7e]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
|
|
14
|
+
}
|
package/dist/gate-runner.d.ts
CHANGED
package/dist/gate-runner.js
CHANGED
|
@@ -1217,7 +1217,7 @@ export function runGate(gate, options) {
|
|
|
1217
1217
|
intent: {
|
|
1218
1218
|
contractSource: options.intent.contractSource,
|
|
1219
1219
|
baseRef: options.intent.baseRef,
|
|
1220
|
-
...(options.intent.note === undefined ? {} : { note: options.intent.note }),
|
|
1220
|
+
...(options.intent.note === undefined ? {} : { note: options.intent.note }), ...(options.intent.paths === null ? {} : { changedPaths: options.intent.paths.length }),
|
|
1221
1221
|
},
|
|
1222
1222
|
}
|
|
1223
1223
|
: options.intentContract === undefined
|
package/dist/intent-prepare.js
CHANGED
|
@@ -1078,10 +1078,7 @@ function prepareAgainstTrustBase(options, trustBase) {
|
|
|
1078
1078
|
proposals.push(`${headSpec} is a spec in this pull request but not on "${trustBase}": it is a proposal, ` +
|
|
1079
1079
|
'and pull requests are judged against it once it is on the base branch.');
|
|
1080
1080
|
}
|
|
1081
|
-
return noSpecChosen(branch, atBase.selection, `No contract on the base: "${trustBase}"
|
|
1082
|
-
`${
|
|
1083
|
-
|
|
1084
|
-
'intent contract comes from the base ref only, so nothing in this pull request can ' +
|
|
1085
|
-
'become it; once a contract or spec is on the base branch, the next pull request is ' +
|
|
1086
|
-
'judged against it.', proposals, trustBase);
|
|
1081
|
+
return noSpecChosen(branch, atBase.selection, `No contract on the base: "${trustBase}" has no frozen contract or spec for ` +
|
|
1082
|
+
`${branch === null ? 'this branch' : `branch "${branch}"`}. See ` +
|
|
1083
|
+
'https://github.com/vaultcompasshq/conductor/blob/main/docs/intent-at-a-pull-request.md', proposals, trustBase);
|
|
1087
1084
|
}
|
package/dist/osv-coverage.js
CHANGED
|
@@ -9,6 +9,7 @@ import path from 'node:path';
|
|
|
9
9
|
import { runGit } from './git.js';
|
|
10
10
|
import { osvLockfileKind } from './products.js';
|
|
11
11
|
import { checkRequirementsPins, describePinProblem, } from './requirements-pin.js';
|
|
12
|
+
import { LOCKFILE_NO_LONGER_SCANNED, REQUIREMENTS_DIRECT_ONLY, REQUIREMENTS_NOT_PINNED, REQUIREMENTS_NOT_SCANNED, } from './rule-ids.js';
|
|
12
13
|
import { readFileAtRefBytes } from './trust-base.js';
|
|
13
14
|
/**
|
|
14
15
|
* A reader over the head: a TRACKED regular file on disk. On disk because
|
|
@@ -102,7 +103,7 @@ export function selectOsvInputs(args) {
|
|
|
102
103
|
suffix = ' Newly pinned in this pull request.';
|
|
103
104
|
}
|
|
104
105
|
}
|
|
105
|
-
notes.push({ code:
|
|
106
|
+
notes.push({ code: REQUIREMENTS_DIRECT_ONLY, message: `${file}: ${DIRECT_ONLY}${suffix}` });
|
|
106
107
|
continue;
|
|
107
108
|
}
|
|
108
109
|
if (base !== null) {
|
|
@@ -116,18 +117,18 @@ export function selectOsvInputs(args) {
|
|
|
116
117
|
? 'Its copy on the base is pinned, so the file stays scanned under the ratchet; the lines named are read as written.'
|
|
117
118
|
: 'Its copy on the base could not be read, so the file stays scanned; the lines named are read as written.';
|
|
118
119
|
diagnostics.push({
|
|
119
|
-
code:
|
|
120
|
+
code: REQUIREMENTS_NOT_PINNED,
|
|
120
121
|
message: `${file} is scanned although ${lines}. ${why}`,
|
|
121
122
|
});
|
|
122
123
|
notes.push({
|
|
123
|
-
code:
|
|
124
|
+
code: REQUIREMENTS_DIRECT_ONLY,
|
|
124
125
|
message: `${file}: ${DIRECT_ONLY} ${baseCheck.pinned ? 'Pinned on the base; scanned under the ratchet.' : 'Base copy unreadable; scanned under the ratchet.'}`,
|
|
125
126
|
});
|
|
126
127
|
continue;
|
|
127
128
|
}
|
|
128
129
|
}
|
|
129
130
|
notScanned.push(file);
|
|
130
|
-
diagnostics.push({ code:
|
|
131
|
+
diagnostics.push({ code: REQUIREMENTS_NOT_SCANNED, message: notScannedMessage(file, headCheck) });
|
|
131
132
|
}
|
|
132
133
|
return { handed: handed.sort(), notScanned, diagnostics, notes, closures };
|
|
133
134
|
}
|
|
@@ -142,7 +143,7 @@ export function selectOsvInputs(args) {
|
|
|
142
143
|
*/
|
|
143
144
|
export function noLongerScanned(repoRoot, ref, tracked) {
|
|
144
145
|
return (noLongerScannedFiles(repoRoot, ref, tracked) ?? []).map((file) => ({
|
|
145
|
-
code:
|
|
146
|
+
code: LOCKFILE_NO_LONGER_SCANNED,
|
|
146
147
|
message: `${file} is tracked on the base and not in this pull request, so it is no longer scanned ` +
|
|
147
148
|
'(by either run). Its removal is visible in the diff.',
|
|
148
149
|
}));
|
package/dist/output-sarif.js
CHANGED
|
@@ -121,7 +121,7 @@ import { gateExitBlocks } from './exit-codes.js';
|
|
|
121
121
|
import { cleanPreviewLine } from './gate-runner.js';
|
|
122
122
|
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
123
123
|
import { INTENT_WARNING } from './normalize.js';
|
|
124
|
-
import { gateOutcomeWords, intentCheckedNothing, intentSkipReason, skewFound, skewPlace, } from './output-text.js';
|
|
124
|
+
import { baseMovedSentences, gateOutcomeWords, intentEmptyChangeSet, intentNothingWording, intentCheckedNothing, intentSkipReason, skewFound, skewPlace, } from './output-text.js';
|
|
125
125
|
import { POLICY_FILE_NAME } from './policy.js';
|
|
126
126
|
import { policyChangeLine } from './policy-diff.js';
|
|
127
127
|
import { guardPreview } from './run.js';
|
|
@@ -426,7 +426,7 @@ fallbackUri, properties, invocation) {
|
|
|
426
426
|
* summary or an exit code.
|
|
427
427
|
*/
|
|
428
428
|
function diagnosticFindings(result) {
|
|
429
|
-
return result.gates.flatMap((gate) => gate.diagnostics.map((diagnostic) => ({
|
|
429
|
+
return result.gates.flatMap((gate) => gate.diagnostics.filter((diagnostic) => diagnostic.code !== NOTHING_TO_SCAN).map((diagnostic) => ({
|
|
430
430
|
schemaVersion: 1,
|
|
431
431
|
product: UMBRELLA_DRIVER_NAME,
|
|
432
432
|
productVersion: null,
|
|
@@ -1089,7 +1089,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
1089
1089
|
...deferredNotifications(result),
|
|
1090
1090
|
...excludedNotifications(result),
|
|
1091
1091
|
...treeUnchangedNotifications(result),
|
|
1092
|
-
...skippedNotifications(result),
|
|
1092
|
+
...skippedNotifications(result), ...emptyChangeSetNotifications(result), ...nothingToScanNotifications(result), ...baseMovedNotifications(result),
|
|
1093
1093
|
...unenforcedNotifications(result),
|
|
1094
1094
|
...legacyStateDirNotifications(result),
|
|
1095
1095
|
...weakMatchNotifications(result),
|
|
@@ -1146,3 +1146,48 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
1146
1146
|
}
|
|
1147
1147
|
return JSON.stringify({ $schema: SARIF_SCHEMA, version: '2.1.0', runs }, null, 2);
|
|
1148
1148
|
}
|
|
1149
|
+
/**
|
|
1150
|
+
* The base branch moved past the merge ref, as a notification: what this run
|
|
1151
|
+
* was judged against is a statement about the run. The same sentence as the
|
|
1152
|
+
* text report.
|
|
1153
|
+
*/
|
|
1154
|
+
function baseMovedNotifications(result) {
|
|
1155
|
+
return baseMovedSentences(result).map((message) => ({
|
|
1156
|
+
id: 'conductor/base-moved',
|
|
1157
|
+
message,
|
|
1158
|
+
details: { ref: result.trustBase?.ref ?? null, baseTip: result.trustBase?.baseTip ?? null },
|
|
1159
|
+
}));
|
|
1160
|
+
}
|
|
1161
|
+
/**
|
|
1162
|
+
* An intent gate that ran with a contract on no changed paths, as a notification:
|
|
1163
|
+
* how much a run covered, by the rule at skippedNotifications. In the gate's own
|
|
1164
|
+
* namespace, like its no-contract skip, with the words of the verdict sentence. A
|
|
1165
|
+
* gate with no contract is left to that skip, which already says it checked nothing.
|
|
1166
|
+
*/
|
|
1167
|
+
function emptyChangeSetNotifications(result) {
|
|
1168
|
+
return result.gates
|
|
1169
|
+
.filter((gate) => intentEmptyChangeSet(gate) && !intentCheckedNothing(gate))
|
|
1170
|
+
.map((gate) => ({
|
|
1171
|
+
id: `${gate.product}/empty-change-set`,
|
|
1172
|
+
message: `${intentNothingWording(gate)}.`,
|
|
1173
|
+
details: { role: gate.role, product: gate.product, reason: 'empty-change-set' },
|
|
1174
|
+
}));
|
|
1175
|
+
}
|
|
1176
|
+
/** The gate diagnostic the log carries as a notification, never a result. */
|
|
1177
|
+
const NOTHING_TO_SCAN = 'conductor/nothing-to-scan';
|
|
1178
|
+
/**
|
|
1179
|
+
* A gate with nothing to scan, as a notification.
|
|
1180
|
+
*
|
|
1181
|
+
* True on every run until somebody adds a lockfile, so by the rule at
|
|
1182
|
+
* skippedNotifications it says how much a run covered and is not a result. The
|
|
1183
|
+
* sentence is the gate's diagnostic, unchanged, which the text report prints too.
|
|
1184
|
+
*/
|
|
1185
|
+
function nothingToScanNotifications(result) {
|
|
1186
|
+
return result.gates.flatMap((gate) => gate.diagnostics
|
|
1187
|
+
.filter((diagnostic) => diagnostic.code === NOTHING_TO_SCAN)
|
|
1188
|
+
.map((diagnostic) => ({
|
|
1189
|
+
id: diagnostic.code,
|
|
1190
|
+
message: diagnostic.message,
|
|
1191
|
+
details: { role: gate.role, product: gate.product },
|
|
1192
|
+
})));
|
|
1193
|
+
}
|
package/dist/output-text.d.ts
CHANGED
|
@@ -148,8 +148,8 @@ export declare function versionSkewSummaryLines(result: RunResult): string[];
|
|
|
148
148
|
* nothing-checked exit 0, but nothing was checked: no gate ran at
|
|
149
149
|
* all (none enabled, or every one deferred,
|
|
150
150
|
* tree-unchanged or skipped), or every gate that
|
|
151
|
-
* ran checked nothing (nothing to scan,
|
|
152
|
-
*
|
|
151
|
+
* ran checked nothing (nothing to scan, no contract,
|
|
152
|
+
* or an empty change set; audit finding F4)
|
|
153
153
|
* advisory-blocked (N) exit 1 that --advisory turned into exit 0
|
|
154
154
|
* unenforced-findings (N) exit 0, but enforce: false gates blocked or
|
|
155
155
|
* could not run
|
|
@@ -267,4 +267,22 @@ export declare const INTENT_SPEC_LINES: readonly ["intent-spec: none chosen, two
|
|
|
267
267
|
*/
|
|
268
268
|
export declare const DEP_GUARD_DEADLINE_CODE = "online-deadline-exceeded";
|
|
269
269
|
export declare function renderText(result: RunResult, options?: TextOptions): string;
|
|
270
|
+
/**
|
|
271
|
+
* An intent gate that ran with a contract on a change set of no paths: a branch
|
|
272
|
+
* the base it was measured against already carries, or a net-empty one. The
|
|
273
|
+
* gate says it is clean and it is, about nothing. Never for a gate that could
|
|
274
|
+
* not run or that blocked: every could-not-run outcome carries a blocking finding,
|
|
275
|
+
* so the one clause covers both. It does its work in the SARIF notification, which
|
|
276
|
+
* reads this directly; the text report sorts those gates out before it gets here.
|
|
277
|
+
*/
|
|
278
|
+
export declare function intentEmptyChangeSet(gate: GateOutcome): boolean;
|
|
279
|
+
/** How the verdict sentence names an intent gate that ran and checked nothing. */
|
|
280
|
+
export declare function intentNothingWording(gate: GateOutcome): string;
|
|
281
|
+
/**
|
|
282
|
+
* Why the rules commit is not the base branch's tip, on a run the Action moved
|
|
283
|
+
* past it, as a list of one, or of none. Says what happened and never that
|
|
284
|
+
* anything merged: the same shape occurs on an open pull request. The text
|
|
285
|
+
* report and the SARIF log read this one sentence, so they cannot disagree.
|
|
286
|
+
*/
|
|
287
|
+
export declare function baseMovedSentences(result: RunResult): string[];
|
|
270
288
|
export {};
|
package/dist/output-text.js
CHANGED
|
@@ -605,7 +605,7 @@ function trustBaseLines(result) {
|
|
|
605
605
|
for (const { gate, reason } of withheldTrustBase(result)) {
|
|
606
606
|
lines.push(` NOT in pull-request mode ${gate.role} ${gate.product} ${reason}`);
|
|
607
607
|
}
|
|
608
|
-
lines.push(...nodeModulesSkippedLine(result));
|
|
608
|
+
lines.push(...baseMovedSentences(result).map((moved) => ` ${moved}`), ...nodeModulesSkippedLine(result));
|
|
609
609
|
return lines;
|
|
610
610
|
}
|
|
611
611
|
/**
|
|
@@ -722,7 +722,7 @@ export function gateOutcomeWords(gate) {
|
|
|
722
722
|
}
|
|
723
723
|
const total = gate.findings.length;
|
|
724
724
|
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
725
|
-
let outcome = total === 0 && (gate.exitCode ?? 0) === 0 ?
|
|
725
|
+
let outcome = total === 0 && (gate.exitCode ?? 0) === 0 ? intentCleanWords(gate) : `findings (${total}, ${blocking} blocking)`;
|
|
726
726
|
// Only when the gate said so; the outcome word above is unchanged.
|
|
727
727
|
const coverage = deadlineCoverage(gate);
|
|
728
728
|
if (coverage !== null) {
|
|
@@ -956,8 +956,8 @@ function blockingCount(gate) {
|
|
|
956
956
|
* nothing-checked exit 0, but nothing was checked: no gate ran at
|
|
957
957
|
* all (none enabled, or every one deferred,
|
|
958
958
|
* tree-unchanged or skipped), or every gate that
|
|
959
|
-
* ran checked nothing (nothing to scan,
|
|
960
|
-
*
|
|
959
|
+
* ran checked nothing (nothing to scan, no contract,
|
|
960
|
+
* or an empty change set; audit finding F4)
|
|
961
961
|
* advisory-blocked (N) exit 1 that --advisory turned into exit 0
|
|
962
962
|
* unenforced-findings (N) exit 0, but enforce: false gates blocked or
|
|
963
963
|
* could not run
|
|
@@ -1021,8 +1021,8 @@ export function verdictToken(result, advisory) {
|
|
|
1021
1021
|
* A gate that ran and examined nothing: osv-scanner with nothing to scan,
|
|
1022
1022
|
* osv-scanner whose every handed lockfile parsed to no packages (exit 128,
|
|
1023
1023
|
* marked `packages-read 0`; a sole lockfile rewritten to {} is exactly the
|
|
1024
|
-
* same news as no lockfile), or an intent gate
|
|
1025
|
-
*
|
|
1024
|
+
* same news as no lockfile), or an intent gate with no contract to check
|
|
1025
|
+
* against or no changed path. The one predicate behind both the verdict token and the
|
|
1026
1026
|
* verdict sentence's list of what was not checked.
|
|
1027
1027
|
*
|
|
1028
1028
|
* NOT the partial-empty case: `conductor/lockfiles-empty` is also raised
|
|
@@ -1039,7 +1039,7 @@ function gateCheckedNothing(gate) {
|
|
|
1039
1039
|
}
|
|
1040
1040
|
return (gate.diagnostics.some((d) => d.code === 'conductor/nothing-to-scan') ||
|
|
1041
1041
|
readNoPackages(gate) ||
|
|
1042
|
-
intentCheckedNothing(gate));
|
|
1042
|
+
intentCheckedNothing(gate) || intentEmptyChangeSet(gate));
|
|
1043
1043
|
}
|
|
1044
1044
|
/**
|
|
1045
1045
|
* The gate's own skipReason (intent-guard 1.10.4, issue 103), or null. Put
|
|
@@ -1067,7 +1067,7 @@ export function intentCheckedNothing(gate) {
|
|
|
1067
1067
|
/** How the verdict sentence names a gate that ran and checked nothing. */
|
|
1068
1068
|
function checkedNothingWording(gate) {
|
|
1069
1069
|
if (gate.role === 'intent') {
|
|
1070
|
-
return
|
|
1070
|
+
return intentNothingWording(gate);
|
|
1071
1071
|
}
|
|
1072
1072
|
return readNoPackages(gate)
|
|
1073
1073
|
? `${gate.role} read no packages from its lockfiles`
|
|
@@ -1271,7 +1271,7 @@ function verdictForRun(result, advisory) {
|
|
|
1271
1271
|
function isFullyClean(result) {
|
|
1272
1272
|
// Every gate that ran checked nothing is the nothing-checked token's state
|
|
1273
1273
|
// (audit finding F4), and a line opening "clean" would contradict it.
|
|
1274
|
-
if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing)) {
|
|
1274
|
+
if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing) || result.gates.some(intentEmptyChangeSet)) {
|
|
1275
1275
|
return false;
|
|
1276
1276
|
}
|
|
1277
1277
|
// A tie the convention refused to guess, or a skip whose branch 0.10.0
|
|
@@ -1501,7 +1501,7 @@ function summaryLine(result) {
|
|
|
1501
1501
|
// produces a clean report, and without this clause the only trace of the
|
|
1502
1502
|
// attempt would be in a file nobody re-reads.
|
|
1503
1503
|
if (result.trustBase !== null) {
|
|
1504
|
-
parts.push(`Rules from ${result.trustBase.ref}. ${proposalCount(result)}
|
|
1504
|
+
parts.push(`Rules from ${result.trustBase.ref}. ${proposalCount(result)}.`, ...baseMovedSentences(result));
|
|
1505
1505
|
const withheld = withheldTrustBase(result);
|
|
1506
1506
|
if (withheld.length > 0) {
|
|
1507
1507
|
const names = withheld.map(({ gate }) => `${gate.role} (${gate.product})`).join(', ');
|
|
@@ -1613,3 +1613,48 @@ export function renderText(result, options = {}) {
|
|
|
1613
1613
|
lines.push('', verdict(result, Boolean(options.advisory)));
|
|
1614
1614
|
return withPreview(`${lines.join('\n')}\n`);
|
|
1615
1615
|
}
|
|
1616
|
+
/**
|
|
1617
|
+
* An intent gate that ran with a contract on a change set of no paths: a branch
|
|
1618
|
+
* the base it was measured against already carries, or a net-empty one. The
|
|
1619
|
+
* gate says it is clean and it is, about nothing. Never for a gate that could
|
|
1620
|
+
* not run or that blocked: every could-not-run outcome carries a blocking finding,
|
|
1621
|
+
* so the one clause covers both. It does its work in the SARIF notification, which
|
|
1622
|
+
* reads this directly; the text report sorts those gates out before it gets here.
|
|
1623
|
+
*/
|
|
1624
|
+
export function intentEmptyChangeSet(gate) {
|
|
1625
|
+
return (gate.role === 'intent' &&
|
|
1626
|
+
!gate.findings.some((finding) => finding.blocking) &&
|
|
1627
|
+
gate.intent?.changedPaths === 0);
|
|
1628
|
+
}
|
|
1629
|
+
/** How the verdict sentence names an intent gate that ran and checked nothing. */
|
|
1630
|
+
export function intentNothingWording(gate) {
|
|
1631
|
+
return intentCheckedNothing(gate)
|
|
1632
|
+
? `${gate.role} ran but found no contract to check against`
|
|
1633
|
+
: `${gate.role} ran on an empty change set, so no path was judged against its contract`;
|
|
1634
|
+
}
|
|
1635
|
+
/**
|
|
1636
|
+
* The outcome word on a gate's log line when it found nothing and exited 0. An
|
|
1637
|
+
* intent gate with no contract gets the words of the pull-request path's skipped
|
|
1638
|
+
* line for the same state, though it did run and so has an exit code to give.
|
|
1639
|
+
*/
|
|
1640
|
+
function intentCleanWords(gate) {
|
|
1641
|
+
if (intentCheckedNothing(gate)) {
|
|
1642
|
+
return `skipped (${skipWording('no-contract').line})`;
|
|
1643
|
+
}
|
|
1644
|
+
return intentEmptyChangeSet(gate) ? 'ok, empty change set' : 'ok';
|
|
1645
|
+
}
|
|
1646
|
+
/**
|
|
1647
|
+
* Why the rules commit is not the base branch's tip, on a run the Action moved
|
|
1648
|
+
* past it, as a list of one, or of none. Says what happened and never that
|
|
1649
|
+
* anything merged: the same shape occurs on an open pull request. The text
|
|
1650
|
+
* report and the SARIF log read this one sentence, so they cannot disagree.
|
|
1651
|
+
*/
|
|
1652
|
+
export function baseMovedSentences(result) {
|
|
1653
|
+
const trust = result.trustBase;
|
|
1654
|
+
return trust === null || trust.baseTip === undefined
|
|
1655
|
+
? []
|
|
1656
|
+
: [
|
|
1657
|
+
`The base branch moved past the merge ref this run is on, to ${trust.baseTip}, which has ` +
|
|
1658
|
+
`the same tree, so the rules are from ${trust.ref}, the commit the merge ref was built from.`,
|
|
1659
|
+
];
|
|
1660
|
+
}
|
package/dist/policy-diff.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { escapeNonAscii } from './escape.js';
|
|
1
2
|
import type { GateRole, Policy } from './policy.js';
|
|
2
3
|
export interface PolicyKeyChange {
|
|
3
4
|
/** The gate role the key belongs to, or null for a key outside any gate. */
|
|
@@ -14,15 +15,7 @@ export declare const HEAD_POLICY_KEY = ".guardrails.yaml";
|
|
|
14
15
|
* file's. A null head (absent or unparseable) is one change that says so.
|
|
15
16
|
*/
|
|
16
17
|
export declare function diffPolicies(base: Policy, head: Policy | null): PolicyKeyChange[];
|
|
17
|
-
|
|
18
|
-
* Every character outside printable ASCII as a \uXXXX escape (an astral
|
|
19
|
-
* character as its two surrogate escapes), so head-chosen text cannot smuggle
|
|
20
|
-
* a bidi override or a zero-width character into the report. Used for a head
|
|
21
|
-
* policy value here, and for every preview line (cleanPreviewLine,
|
|
22
|
-
* src/gate-runner.ts), whose gate text the head's own control files can
|
|
23
|
-
* choose (audit 2026-10-27, N3).
|
|
24
|
-
*/
|
|
25
|
-
export declare function escapeNonAscii(text: string): string;
|
|
18
|
+
export { escapeNonAscii };
|
|
26
19
|
/** One proposal line for one changed key. */
|
|
27
20
|
export declare function policyChangeLine(change: PolicyKeyChange): string;
|
|
28
21
|
/**
|
package/dist/policy-diff.js
CHANGED
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
// verdict. The one place a head value goes further is `previewPolicy`, which
|
|
9
9
|
// takes only `enabled`, `stage` and `enforce` from it for the preview under
|
|
10
10
|
// the proposed rules, a run that decides nothing.
|
|
11
|
+
import { escapeNonAscii } from './escape.js';
|
|
11
12
|
import { GATE_ROLES, PRODUCT_FOR_ROLE, parsePolicy } from './policy.js';
|
|
12
13
|
export const HEAD_POLICY_KEY = '.guardrails.yaml';
|
|
13
14
|
const MAX_VALUE_LENGTH = 80;
|
|
@@ -92,17 +93,9 @@ export function diffPolicies(base, head) {
|
|
|
92
93
|
}
|
|
93
94
|
return changes;
|
|
94
95
|
}
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
* a bidi override or a zero-width character into the report. Used for a head
|
|
99
|
-
* policy value here, and for every preview line (cleanPreviewLine,
|
|
100
|
-
* src/gate-runner.ts), whose gate text the head's own control files can
|
|
101
|
-
* choose (audit 2026-10-27, N3).
|
|
102
|
-
*/
|
|
103
|
-
export function escapeNonAscii(text) {
|
|
104
|
-
return text.replace(/[^\x20-\x7e]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
|
|
105
|
-
}
|
|
96
|
+
// escapeNonAscii lives in src/escape.ts, a dependency-free leaf; it is
|
|
97
|
+
// re-exported here so existing importers keep working unchanged.
|
|
98
|
+
export { escapeNonAscii };
|
|
106
99
|
function renderValue(value) {
|
|
107
100
|
if (value === undefined)
|
|
108
101
|
return '(absent)';
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
export type RuleIdClass = 'finding' | 'diagnostic' | 'notification';
|
|
2
|
+
export declare const GATE_MISSING = "conductor/gate-missing";
|
|
3
|
+
export declare const GATE_FAILED = "conductor/gate-failed";
|
|
4
|
+
export declare const GATE_OUTPUT_UNPARSEABLE = "conductor/gate-output-unparseable";
|
|
5
|
+
export declare const INTENT_GATE_BLOCKED = "intent-guard/gate-blocked";
|
|
6
|
+
export declare const BLOCKING_COUNT_MISMATCH = "conductor/blocking-count-mismatch";
|
|
7
|
+
export declare const BLOCKING_THRESHOLD_UNKNOWN = "conductor/blocking-threshold-unknown";
|
|
8
|
+
export declare const NOTHING_TO_SCAN = "conductor/nothing-to-scan";
|
|
9
|
+
export declare const LOCKFILES_EMPTY = "conductor/lockfiles-empty";
|
|
10
|
+
export declare const LOCKFILE_NO_LONGER_SCANNED = "conductor/lockfile-no-longer-scanned";
|
|
11
|
+
export declare const MANIFESTS_NOT_HANDED = "conductor/manifests-not-handed";
|
|
12
|
+
export declare const OPTION_OVERRIDDEN = "conductor/option-overridden";
|
|
13
|
+
export declare const BASE_COMPARISON_UNAVAILABLE = "conductor/base-comparison-unavailable";
|
|
14
|
+
export declare const REQUIREMENTS_DIRECT_ONLY = "conductor/requirements-direct-only";
|
|
15
|
+
export declare const REQUIREMENTS_NOT_PINNED = "conductor/requirements-not-pinned";
|
|
16
|
+
export declare const REQUIREMENTS_NOT_SCANNED = "conductor/requirements-not-scanned";
|
|
17
|
+
export declare const INTENT_WARNING = "intent-guard/warning";
|
|
18
|
+
export declare const GATE_DEFERRED = "conductor/gate-deferred";
|
|
19
|
+
export declare const GATE_EXCLUDED = "conductor/gate-excluded";
|
|
20
|
+
export declare const GATE_NOT_ENFORCED = "conductor/gate-not-enforced";
|
|
21
|
+
export declare const TREE_UNCHANGED = "conductor/tree-unchanged";
|
|
22
|
+
export declare const BASE_MOVED = "conductor/base-moved";
|
|
23
|
+
export declare const CONTROL_CHANGE_PROPOSED = "conductor/control-change-proposed";
|
|
24
|
+
export declare const PREVIEW_UNDER_PROPOSED_RULES = "conductor/preview-under-proposed-rules";
|
|
25
|
+
export declare const TRUST_BASE_REFUSED = "conductor/trust-base-refused";
|
|
26
|
+
export declare const TRUST_BASE_NOT_PASSED = "conductor/trust-base-not-passed";
|
|
27
|
+
export declare const GATE_PROGRAM_REFUSED = "conductor/gate-program-refused";
|
|
28
|
+
export declare const NODE_MODULES_SKIPPED = "conductor/node-modules-skipped";
|
|
29
|
+
export declare const VERSION_SKEW = "conductor/version-skew";
|
|
30
|
+
export declare const OPTION_IS_GATE_OWN = "conductor/option-is-gate-own";
|
|
31
|
+
export declare const INTENT_LEGACY_STATE_DIR = "intent-guard/legacy-state-dir";
|
|
32
|
+
export declare const INTENT_NO_CONTRACT = "intent-guard/no-contract";
|
|
33
|
+
export declare const INTENT_CONTRACT_WAIVED = "intent-guard/contract-waived";
|
|
34
|
+
export declare const INTENT_SPEC_AMBIGUOUS = "intent-guard/spec-ambiguous";
|
|
35
|
+
export declare const INTENT_SPEC_WEAK_MATCH = "intent-guard/spec-weak-match";
|
|
36
|
+
export declare const INTENT_EMPTY_CHANGE_SET = "intent-guard/empty-change-set";
|
|
37
|
+
/** Every id above, with its class. */
|
|
38
|
+
export declare const RULE_IDS: ReadonlyArray<{
|
|
39
|
+
id: string;
|
|
40
|
+
class: RuleIdClass;
|
|
41
|
+
}>;
|
package/dist/rule-ids.js
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
// Every rule id the umbrella writes, as a named constant with its class.
|
|
2
|
+
// tests/rule-ids.test.ts holds this to every id literal under src in any
|
|
3
|
+
// quote style, every template id of the form product/suffix, and every
|
|
4
|
+
// skip reason that becomes the second half of an id.
|
|
5
|
+
//
|
|
6
|
+
// These strings are frozen public surface: they are SARIF rule and
|
|
7
|
+
// notification ids, and the codes of the umbrella's diagnostics, and a
|
|
8
|
+
// consumer matches on them. A value here never changes; a new id is added,
|
|
9
|
+
// never renamed in place.
|
|
10
|
+
//
|
|
11
|
+
// The class says what kind of record carries the id when the umbrella
|
|
12
|
+
// writes it, not where a renderer later files it:
|
|
13
|
+
// - finding: a Finding the umbrella raises itself (src/normalize.ts).
|
|
14
|
+
// - diagnostic: a Diagnostic record, an umbrella diagnostic or a run note,
|
|
15
|
+
// which never counts toward the exit code.
|
|
16
|
+
// - notification: a SARIF tool-execution notification on the umbrella's run.
|
|
17
|
+
//
|
|
18
|
+
// Call sites are moving to these constants one file at a time; a site that
|
|
19
|
+
// still writes the literal must write exactly the value here.
|
|
20
|
+
// Findings.
|
|
21
|
+
export const GATE_MISSING = 'conductor/gate-missing';
|
|
22
|
+
export const GATE_FAILED = 'conductor/gate-failed';
|
|
23
|
+
export const GATE_OUTPUT_UNPARSEABLE = 'conductor/gate-output-unparseable';
|
|
24
|
+
export const INTENT_GATE_BLOCKED = 'intent-guard/gate-blocked';
|
|
25
|
+
// Diagnostics.
|
|
26
|
+
export const BLOCKING_COUNT_MISMATCH = 'conductor/blocking-count-mismatch';
|
|
27
|
+
export const BLOCKING_THRESHOLD_UNKNOWN = 'conductor/blocking-threshold-unknown';
|
|
28
|
+
export const NOTHING_TO_SCAN = 'conductor/nothing-to-scan';
|
|
29
|
+
export const LOCKFILES_EMPTY = 'conductor/lockfiles-empty';
|
|
30
|
+
export const LOCKFILE_NO_LONGER_SCANNED = 'conductor/lockfile-no-longer-scanned';
|
|
31
|
+
export const MANIFESTS_NOT_HANDED = 'conductor/manifests-not-handed';
|
|
32
|
+
export const OPTION_OVERRIDDEN = 'conductor/option-overridden';
|
|
33
|
+
export const BASE_COMPARISON_UNAVAILABLE = 'conductor/base-comparison-unavailable';
|
|
34
|
+
export const REQUIREMENTS_DIRECT_ONLY = 'conductor/requirements-direct-only';
|
|
35
|
+
export const REQUIREMENTS_NOT_PINNED = 'conductor/requirements-not-pinned';
|
|
36
|
+
export const REQUIREMENTS_NOT_SCANNED = 'conductor/requirements-not-scanned';
|
|
37
|
+
export const INTENT_WARNING = 'intent-guard/warning';
|
|
38
|
+
// Notifications.
|
|
39
|
+
export const GATE_DEFERRED = 'conductor/gate-deferred';
|
|
40
|
+
export const GATE_EXCLUDED = 'conductor/gate-excluded';
|
|
41
|
+
export const GATE_NOT_ENFORCED = 'conductor/gate-not-enforced';
|
|
42
|
+
export const TREE_UNCHANGED = 'conductor/tree-unchanged';
|
|
43
|
+
export const BASE_MOVED = 'conductor/base-moved';
|
|
44
|
+
export const CONTROL_CHANGE_PROPOSED = 'conductor/control-change-proposed';
|
|
45
|
+
export const PREVIEW_UNDER_PROPOSED_RULES = 'conductor/preview-under-proposed-rules';
|
|
46
|
+
export const TRUST_BASE_REFUSED = 'conductor/trust-base-refused';
|
|
47
|
+
export const TRUST_BASE_NOT_PASSED = 'conductor/trust-base-not-passed';
|
|
48
|
+
export const GATE_PROGRAM_REFUSED = 'conductor/gate-program-refused';
|
|
49
|
+
export const NODE_MODULES_SKIPPED = 'conductor/node-modules-skipped';
|
|
50
|
+
export const VERSION_SKEW = 'conductor/version-skew';
|
|
51
|
+
export const OPTION_IS_GATE_OWN = 'conductor/option-is-gate-own';
|
|
52
|
+
export const INTENT_LEGACY_STATE_DIR = 'intent-guard/legacy-state-dir';
|
|
53
|
+
// These five are written in src/output-sarif.ts as a template on the gate's
|
|
54
|
+
// product, which only an intent gate reaches, so the value written is the
|
|
55
|
+
// one here. The skip reasons are SkippedGate.reason in src/run.ts.
|
|
56
|
+
export const INTENT_NO_CONTRACT = 'intent-guard/no-contract';
|
|
57
|
+
export const INTENT_CONTRACT_WAIVED = 'intent-guard/contract-waived';
|
|
58
|
+
export const INTENT_SPEC_AMBIGUOUS = 'intent-guard/spec-ambiguous';
|
|
59
|
+
export const INTENT_SPEC_WEAK_MATCH = 'intent-guard/spec-weak-match';
|
|
60
|
+
export const INTENT_EMPTY_CHANGE_SET = 'intent-guard/empty-change-set';
|
|
61
|
+
/** Every id above, with its class. */
|
|
62
|
+
export const RULE_IDS = [
|
|
63
|
+
{ id: GATE_MISSING, class: 'finding' },
|
|
64
|
+
{ id: GATE_FAILED, class: 'finding' },
|
|
65
|
+
{ id: GATE_OUTPUT_UNPARSEABLE, class: 'finding' },
|
|
66
|
+
{ id: INTENT_GATE_BLOCKED, class: 'finding' },
|
|
67
|
+
{ id: BLOCKING_COUNT_MISMATCH, class: 'diagnostic' },
|
|
68
|
+
{ id: BLOCKING_THRESHOLD_UNKNOWN, class: 'diagnostic' },
|
|
69
|
+
{ id: NOTHING_TO_SCAN, class: 'diagnostic' },
|
|
70
|
+
{ id: LOCKFILES_EMPTY, class: 'diagnostic' },
|
|
71
|
+
{ id: LOCKFILE_NO_LONGER_SCANNED, class: 'diagnostic' },
|
|
72
|
+
{ id: MANIFESTS_NOT_HANDED, class: 'diagnostic' },
|
|
73
|
+
{ id: OPTION_OVERRIDDEN, class: 'diagnostic' },
|
|
74
|
+
{ id: BASE_COMPARISON_UNAVAILABLE, class: 'diagnostic' },
|
|
75
|
+
{ id: REQUIREMENTS_DIRECT_ONLY, class: 'diagnostic' },
|
|
76
|
+
{ id: REQUIREMENTS_NOT_PINNED, class: 'diagnostic' },
|
|
77
|
+
{ id: REQUIREMENTS_NOT_SCANNED, class: 'diagnostic' },
|
|
78
|
+
{ id: INTENT_WARNING, class: 'diagnostic' },
|
|
79
|
+
{ id: GATE_DEFERRED, class: 'notification' },
|
|
80
|
+
{ id: GATE_EXCLUDED, class: 'notification' },
|
|
81
|
+
{ id: GATE_NOT_ENFORCED, class: 'notification' },
|
|
82
|
+
{ id: TREE_UNCHANGED, class: 'notification' },
|
|
83
|
+
{ id: BASE_MOVED, class: 'notification' },
|
|
84
|
+
{ id: CONTROL_CHANGE_PROPOSED, class: 'notification' },
|
|
85
|
+
{ id: PREVIEW_UNDER_PROPOSED_RULES, class: 'notification' },
|
|
86
|
+
{ id: TRUST_BASE_REFUSED, class: 'notification' },
|
|
87
|
+
{ id: TRUST_BASE_NOT_PASSED, class: 'notification' },
|
|
88
|
+
{ id: GATE_PROGRAM_REFUSED, class: 'notification' },
|
|
89
|
+
{ id: NODE_MODULES_SKIPPED, class: 'notification' },
|
|
90
|
+
{ id: VERSION_SKEW, class: 'notification' },
|
|
91
|
+
{ id: OPTION_IS_GATE_OWN, class: 'notification' },
|
|
92
|
+
{ id: INTENT_LEGACY_STATE_DIR, class: 'notification' },
|
|
93
|
+
{ id: INTENT_NO_CONTRACT, class: 'notification' },
|
|
94
|
+
{ id: INTENT_CONTRACT_WAIVED, class: 'notification' },
|
|
95
|
+
{ id: INTENT_SPEC_AMBIGUOUS, class: 'notification' },
|
|
96
|
+
{ id: INTENT_SPEC_WEAK_MATCH, class: 'notification' },
|
|
97
|
+
{ id: INTENT_EMPTY_CHANGE_SET, class: 'notification' },
|
|
98
|
+
];
|
package/dist/run.d.ts
CHANGED
|
@@ -109,7 +109,7 @@ export interface ControlProposal {
|
|
|
109
109
|
* the policy file at the base ref with the one at the head commit. It is
|
|
110
110
|
* reported and never acted on: the base ref's policy is the one that ran.
|
|
111
111
|
*/
|
|
112
|
-
export interface RunTrustBase {
|
|
112
|
+
export interface RunTrustBase extends BaseTipForDisplay {
|
|
113
113
|
/** The ref the umbrella took its own policy from. */
|
|
114
114
|
ref: string;
|
|
115
115
|
/** Whether the head commit's own policy file differs from that one. */
|
|
@@ -340,3 +340,13 @@ export declare function guardPreview<T>(work: () => T, fallback: (message: strin
|
|
|
340
340
|
*/
|
|
341
341
|
export declare function runPreview(policy: Policy, options: RunOptions): RunPreview;
|
|
342
342
|
export declare function runAll(policy: Policy, options: RunOptions): RunResult;
|
|
343
|
+
/** The part of a trust base only the reports read. */
|
|
344
|
+
interface BaseTipForDisplay {
|
|
345
|
+
/**
|
|
346
|
+
* The base branch's tip, when the Action moved this trust base past it
|
|
347
|
+
* (`withMovedBaseTip`, trust-base.ts). Printed by the reports and read by
|
|
348
|
+
* nothing else.
|
|
349
|
+
*/
|
|
350
|
+
baseTip?: string;
|
|
351
|
+
}
|
|
352
|
+
export {};
|
package/dist/trust-base.d.ts
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The private, fully spelled ref the composite action fetches the base branch
|
|
3
|
-
* into
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
3
|
+
* into, or moves to the merge ref's first parent on issue 159's one shape
|
|
4
|
+
* (action.yml, fetch-base step). Nothing else writes it and no short name can
|
|
5
|
+
* shadow it: git resolves origin/main through refs/tags/ BEFORE refs/remotes/,
|
|
6
|
+
* so a tag pushed by anyone able to push tags would choose the rules' commit.
|
|
7
7
|
*/
|
|
8
8
|
export declare const PRIVATE_TRUST_BASE_REF = "refs/conductor/trust-base";
|
|
9
9
|
/** What a fully spelled ref names: nothing, an object, or an answer git could not give. */
|
|
@@ -120,8 +120,8 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
|
|
|
120
120
|
* else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
|
|
121
121
|
* a platform that never sets it. When it is set, the given ref is accepted
|
|
122
122
|
* only when it is the FULL COMMIT ID the composite action's "Fetch the trust
|
|
123
|
-
* base" step published (
|
|
124
|
-
* authority, or refs/remotes/origin/<githubBaseRef>, both
|
|
123
|
+
* base" step published, the tip or on one shape its first parent (it must equal
|
|
124
|
+
* refs/conductor/trust-base, the authority, or refs/remotes/origin/<githubBaseRef>, both via show-ref),
|
|
125
125
|
* or is that private ref itself, or -- for an explicit trust base -- resolves
|
|
126
126
|
* to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
|
|
127
127
|
* pull-request run through the action returns null here, before
|
|
@@ -446,3 +446,21 @@ export declare function refuseHeadControlledData(repoRoot: string, trustBase: st
|
|
|
446
446
|
entry?: string;
|
|
447
447
|
from?: 'options';
|
|
448
448
|
}): string | null;
|
|
449
|
+
/**
|
|
450
|
+
* The trust base with the base branch's tip to name in the report, when the
|
|
451
|
+
* Action moved the trust base past it. FOR DISPLAY ONLY: nothing that decides
|
|
452
|
+
* anything reads `baseTip`. The value comes from the environment, so it is
|
|
453
|
+
* honored only when the repository bears it out: a full id of a commit that is
|
|
454
|
+
* neither HEAD nor the trust base, with HEAD's tree, and the trust base is HEAD's
|
|
455
|
+
* first parent. Anything else is ignored without a word: the sentence is the only
|
|
456
|
+
* thing it could change, and leaving it out is true.
|
|
457
|
+
*
|
|
458
|
+
* The CLI cannot work this out alone. It sees the private ref at HEAD's first
|
|
459
|
+
* parent, which is also what every ordinary pull-request run looks like, and it
|
|
460
|
+
* never sees the tip the Action moved away from. It can only check what it is told.
|
|
461
|
+
*/
|
|
462
|
+
export declare function withMovedBaseTip<T extends {
|
|
463
|
+
ref: string;
|
|
464
|
+
}>(repoRoot: string, trustBase: T, value: string | undefined): T & {
|
|
465
|
+
baseTip?: string;
|
|
466
|
+
};
|
package/dist/trust-base.js
CHANGED
|
@@ -77,10 +77,10 @@ import { parse as parseYaml } from 'yaml';
|
|
|
77
77
|
import { gitComplaint, runGit, runGitBytes } from './git.js';
|
|
78
78
|
/**
|
|
79
79
|
* The private, fully spelled ref the composite action fetches the base branch
|
|
80
|
-
* into
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
80
|
+
* into, or moves to the merge ref's first parent on issue 159's one shape
|
|
81
|
+
* (action.yml, fetch-base step). Nothing else writes it and no short name can
|
|
82
|
+
* shadow it: git resolves origin/main through refs/tags/ BEFORE refs/remotes/,
|
|
83
|
+
* so a tag pushed by anyone able to push tags would choose the rules' commit.
|
|
84
84
|
*/
|
|
85
85
|
export const PRIVATE_TRUST_BASE_REF = 'refs/conductor/trust-base';
|
|
86
86
|
/**
|
|
@@ -332,9 +332,9 @@ export function refuseTrustBaseRef(repoRoot, ref) {
|
|
|
332
332
|
`identical tree (${headTree}), so the policy would come from the tree being judged and ` +
|
|
333
333
|
'there would be nothing for pull-request mode to compare. Likely cause: the base already ' +
|
|
334
334
|
'carries this tree, which usually means the pull request was merged while this job was ' +
|
|
335
|
-
'queued
|
|
336
|
-
|
|
337
|
-
'
|
|
335
|
+
'queued. ' +
|
|
336
|
+
`${EQUAL_TREE_ADVICE} ` +
|
|
337
|
+
'Nothing was checked.');
|
|
338
338
|
}
|
|
339
339
|
return null;
|
|
340
340
|
}
|
|
@@ -360,8 +360,8 @@ export function refuseTrustBaseRef(repoRoot, ref) {
|
|
|
360
360
|
* else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
|
|
361
361
|
* a platform that never sets it. When it is set, the given ref is accepted
|
|
362
362
|
* only when it is the FULL COMMIT ID the composite action's "Fetch the trust
|
|
363
|
-
* base" step published (
|
|
364
|
-
* authority, or refs/remotes/origin/<githubBaseRef>, both
|
|
363
|
+
* base" step published, the tip or on one shape its first parent (it must equal
|
|
364
|
+
* refs/conductor/trust-base, the authority, or refs/remotes/origin/<githubBaseRef>, both via show-ref),
|
|
365
365
|
* or is that private ref itself, or -- for an explicit trust base -- resolves
|
|
366
366
|
* to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
|
|
367
367
|
* pull-request run through the action returns null here, before
|
|
@@ -1370,3 +1370,35 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
|
|
|
1370
1370
|
}
|
|
1371
1371
|
return null;
|
|
1372
1372
|
}
|
|
1373
|
+
/** What a run refused for carrying HEAD's tree tells the reader to do. */
|
|
1374
|
+
const EQUAL_TREE_ADVICE = 'A pull request that landed gets no later push, so nothing re-runs this check: this run stays ' +
|
|
1375
|
+
'red and its changes went unchecked here. One still open re-runs on its next push. The Action judges this shape against the commit the merge ref was ' +
|
|
1376
|
+
'built from only on a full clone (fetch-depth: 0) with the same control files at both commits. ' +
|
|
1377
|
+
'If neither case applies, the trust base names the head or merge commit: pass the base branch ' +
|
|
1378
|
+
'(for example origin/main) instead.';
|
|
1379
|
+
/**
|
|
1380
|
+
* The trust base with the base branch's tip to name in the report, when the
|
|
1381
|
+
* Action moved the trust base past it. FOR DISPLAY ONLY: nothing that decides
|
|
1382
|
+
* anything reads `baseTip`. The value comes from the environment, so it is
|
|
1383
|
+
* honored only when the repository bears it out: a full id of a commit that is
|
|
1384
|
+
* neither HEAD nor the trust base, with HEAD's tree, and the trust base is HEAD's
|
|
1385
|
+
* first parent. Anything else is ignored without a word: the sentence is the only
|
|
1386
|
+
* thing it could change, and leaving it out is true.
|
|
1387
|
+
*
|
|
1388
|
+
* The CLI cannot work this out alone. It sees the private ref at HEAD's first
|
|
1389
|
+
* parent, which is also what every ordinary pull-request run looks like, and it
|
|
1390
|
+
* never sees the tip the Action moved away from. It can only check what it is told.
|
|
1391
|
+
*/
|
|
1392
|
+
export function withMovedBaseTip(repoRoot, trustBase, value) {
|
|
1393
|
+
if (value === undefined || !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(value)) {
|
|
1394
|
+
return trustBase;
|
|
1395
|
+
}
|
|
1396
|
+
const base = resolveRev(repoRoot, trustBase.ref, 'commit');
|
|
1397
|
+
const borneOut = base !== null &&
|
|
1398
|
+
value !== base &&
|
|
1399
|
+
resolveRev(repoRoot, value, 'commit') === value &&
|
|
1400
|
+
value !== resolveRev(repoRoot, 'HEAD', 'commit') &&
|
|
1401
|
+
headTreeEqualsBase(repoRoot, value) &&
|
|
1402
|
+
headParents(repoRoot)[0] === base;
|
|
1403
|
+
return borneOut ? { ...trustBase, baseTip: value } : trustBase;
|
|
1404
|
+
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Tracked
|
|
2
|
+
* Tracked dependency files that were not handed to `product`, sorted, as
|
|
3
3
|
* one sentence fragment, or null when there are none.
|
|
4
4
|
*
|
|
5
5
|
* `handed` are the repository-relative paths the gate was actually handed,
|
package/dist/unread-manifests.js
CHANGED
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
// given. A repository whose only manifests are a pyproject.toml, a Dockerfile
|
|
6
6
|
// and a workflow gets a green vulnerabilities gate that looked at none of
|
|
7
7
|
// them, and "treated as clean" on its own reads as a statement about the code.
|
|
8
|
+
import { OSV_LOCKFILE_ECOSYSTEMS } from './products.js';
|
|
8
9
|
const EXACT_NAMES = new Set([
|
|
9
10
|
'pyproject.toml',
|
|
10
11
|
'Pipfile',
|
|
@@ -46,7 +47,28 @@ function isManifest(file) {
|
|
|
46
47
|
(file.startsWith('.github/workflows/') && /\.ya?ml$/.test(base)));
|
|
47
48
|
}
|
|
48
49
|
/**
|
|
49
|
-
*
|
|
50
|
+
* A package.json no JavaScript lockfile the gate was handed could have resolved:
|
|
51
|
+
* none sits in its directory or an ancestor. Under one it is what that lockfile
|
|
52
|
+
* resolved, a workspace member under a root lockfile included, and naming it
|
|
53
|
+
* would put a note on every such run. Any other ecosystem's lockfile says
|
|
54
|
+
* nothing about it.
|
|
55
|
+
*/
|
|
56
|
+
function isUnresolvedPackageJson(file, handed) {
|
|
57
|
+
if (file.slice(file.lastIndexOf('/') + 1) !== 'package.json') {
|
|
58
|
+
return false;
|
|
59
|
+
}
|
|
60
|
+
const directory = file.includes('/') ? file.slice(0, file.lastIndexOf('/')) : '';
|
|
61
|
+
return ![...handed].some((lockfile) => {
|
|
62
|
+
const base = lockfile.slice(lockfile.lastIndexOf('/') + 1);
|
|
63
|
+
if (OSV_LOCKFILE_ECOSYSTEMS[base] !== 'javascript') {
|
|
64
|
+
return false;
|
|
65
|
+
}
|
|
66
|
+
const lockDirectory = lockfile.includes('/') ? lockfile.slice(0, lockfile.lastIndexOf('/')) : '';
|
|
67
|
+
return lockDirectory === '' || directory === lockDirectory || directory.startsWith(`${lockDirectory}/`);
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Tracked dependency files that were not handed to `product`, sorted, as
|
|
50
72
|
* one sentence fragment, or null when there are none.
|
|
51
73
|
*
|
|
52
74
|
* `handed` are the repository-relative paths the gate was actually handed,
|
|
@@ -62,12 +84,12 @@ export function unreadManifestsNote(tracked, handed, product) {
|
|
|
62
84
|
const unread = tracked
|
|
63
85
|
.filter((file) => !file.split('/').some((segment) => SKIPPED_DIRS.has(segment)))
|
|
64
86
|
.filter((file) => !handed.has(file))
|
|
65
|
-
.filter(isManifest)
|
|
87
|
+
.filter((file) => isManifest(file) || isUnresolvedPackageJson(file, handed))
|
|
66
88
|
.sort();
|
|
67
89
|
if (unread.length === 0) {
|
|
68
90
|
return null;
|
|
69
91
|
}
|
|
70
92
|
const listed = unread.slice(0, MAX_LISTED).join(', ');
|
|
71
93
|
const more = unread.length > MAX_LISTED ? `, and ${unread.length - MAX_LISTED} more` : '';
|
|
72
|
-
return `Tracked
|
|
94
|
+
return `Tracked dependency files not handed to ${product}: ${listed}${more}.`;
|
|
73
95
|
}
|