@vaultcompass/conductor 0.16.0 → 0.18.0
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/gate-runner.d.ts +1 -0
- package/dist/gate-runner.js +14 -7
- package/dist/intent-prepare.js +3 -6
- package/dist/normalize.js +42 -2
- package/dist/output-sarif.js +69 -3
- package/dist/output-text.d.ts +35 -2
- package/dist/output-text.js +98 -12
- package/dist/policy.d.ts +21 -1
- package/dist/policy.js +58 -2
- package/dist/resolve.d.ts +23 -4
- package/dist/resolve.js +64 -43
- package/dist/run.d.ts +11 -1
- package/dist/trust-base.d.ts +59 -10
- package/dist/trust-base.js +296 -33
- 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@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.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.18.
|
|
232
|
+
such as `conductor: gate dependencies (dep-guard 0.18.2): 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.0
|
|
241
241
|
verdict-token: blocked (1)
|
|
242
242
|
conductor run: 2 gate(s), 1 finding(s)
|
|
243
243
|
|
|
244
|
-
dependencies dep-guard 0.18.
|
|
244
|
+
dependencies dep-guard 0.18.2 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.1 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.17.0 that way, as
|
|
546
|
+
`vaultcompasshq/conductor@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.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@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.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@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.0
|
|
658
668
|
with:
|
|
659
669
|
output: conductor.sarif
|
|
660
|
-
#
|
|
661
|
-
#
|
|
662
|
-
#
|
|
663
|
-
#
|
|
664
|
-
#
|
|
665
|
-
#
|
|
666
|
-
#
|
|
667
|
-
#
|
|
668
|
-
|
|
669
|
-
vault-guard-version: 1.13.0
|
|
670
|
-
intent-guard-version: 1.10.3
|
|
671
|
-
- uses: github/codeql-action/upload-sarif@v3
|
|
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@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.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@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.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@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.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@f5c68efe4dd3f17738e72b19411fea0e829bc2b8 # v0.17.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/gate-runner.d.ts
CHANGED
package/dist/gate-runner.js
CHANGED
|
@@ -31,7 +31,7 @@ import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals,
|
|
|
31
31
|
import { osvLockfileKind, profileFor } from './products.js';
|
|
32
32
|
import { unreadManifestsNote } from './unread-manifests.js';
|
|
33
33
|
import { escapeNonAscii } from './policy-diff.js';
|
|
34
|
-
import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledData, refuseHeadControlledProgram, } from './trust-base.js';
|
|
34
|
+
import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledData, refuseHeadControlledProgram, writtenInsideWorkingTree, } from './trust-base.js';
|
|
35
35
|
import { ResolveError, argumentCandidates, candidateNames, codeArguments, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
|
|
36
36
|
/** The longest excerpt of a gate's own reason that is carried. */
|
|
37
37
|
export const GATE_SAID_MAX_CHARS = 160;
|
|
@@ -675,8 +675,9 @@ export function refuseHeadControlledBinary(repoRoot, trustBase, binary) {
|
|
|
675
675
|
return refusal;
|
|
676
676
|
}
|
|
677
677
|
}
|
|
678
|
+
const fromOptions = new Set(binary.optionArgumentPaths ?? []);
|
|
678
679
|
for (const argument of binary.argumentPaths) {
|
|
679
|
-
const refusal = refuseHeadControlledArgument(repoRoot, trustBase, argument);
|
|
680
|
+
const refusal = refuseHeadControlledArgument(repoRoot, trustBase, argument, fromOptions.has(argument) ? "the gate's options:" : "the gate's args:");
|
|
680
681
|
if (refusal !== null) {
|
|
681
682
|
return refusal;
|
|
682
683
|
}
|
|
@@ -770,7 +771,7 @@ changeBase,
|
|
|
770
771
|
* after its enables, so the appended flag wins.
|
|
771
772
|
*/
|
|
772
773
|
preview = false) {
|
|
773
|
-
const passthrough = renderOptionFlags(gate.options);
|
|
774
|
+
const passthrough = renderOptionFlags(gate.options, gate.product);
|
|
774
775
|
const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
|
|
775
776
|
const config = external.configPath === undefined ? [] : ['--config', external.configPath];
|
|
776
777
|
switch (gate.product) {
|
|
@@ -946,7 +947,7 @@ preview = false) {
|
|
|
946
947
|
...lockfiles,
|
|
947
948
|
...(noResolve ? ['--no-resolve'] : []),
|
|
948
949
|
...callAnalysis,
|
|
949
|
-
...renderOptionFlags(options),
|
|
950
|
+
...renderOptionFlags(options, gate.product),
|
|
950
951
|
...(preview ? ['--no-call-analysis=all'] : []),
|
|
951
952
|
];
|
|
952
953
|
}
|
|
@@ -1216,7 +1217,7 @@ export function runGate(gate, options) {
|
|
|
1216
1217
|
intent: {
|
|
1217
1218
|
contractSource: options.intent.contractSource,
|
|
1218
1219
|
baseRef: options.intent.baseRef,
|
|
1219
|
-
...(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 }),
|
|
1220
1221
|
},
|
|
1221
1222
|
}
|
|
1222
1223
|
: options.intentContract === undefined
|
|
@@ -1304,7 +1305,11 @@ function previewRefusal(gate, repoRoot) {
|
|
|
1304
1305
|
detail: "the preview does not run call analysis, because it would build the head's code",
|
|
1305
1306
|
};
|
|
1306
1307
|
}
|
|
1307
|
-
|
|
1308
|
+
// Inside by its real path OR as written: a directory on the written path
|
|
1309
|
+
// that is a link out of the tree is the head's choice too (audit
|
|
1310
|
+
// 2026-11-01, MB2), and the primary rule judges every path as written.
|
|
1311
|
+
if (gate.command !== undefined &&
|
|
1312
|
+
(realPathInside(repoRoot, gate.command) || writtenInsideWorkingTree(repoRoot, gate.command))) {
|
|
1308
1313
|
return {
|
|
1309
1314
|
reason: 'gate-program-refused',
|
|
1310
1315
|
detail: `preview under the proposed rules: the base command ${gate.command} is inside the working tree, so this gate was not run`,
|
|
@@ -1327,7 +1332,9 @@ function previewRefusal(gate, repoRoot) {
|
|
|
1327
1332
|
// on every preview spawn, an option-value directory included (review B1).
|
|
1328
1333
|
for (const arg of codeArguments(gate)) {
|
|
1329
1334
|
const candidates = argumentCandidates(arg, repoRoot);
|
|
1330
|
-
if (candidates.some((named) => realPathInside(repoRoot, named) ||
|
|
1335
|
+
if (candidates.some((named) => realPathInside(repoRoot, named) ||
|
|
1336
|
+
realPathInside(repoRoot, path.dirname(named)) ||
|
|
1337
|
+
writtenInsideWorkingTree(repoRoot, named))) {
|
|
1331
1338
|
return {
|
|
1332
1339
|
reason: 'gate-program-refused',
|
|
1333
1340
|
detail: `preview under the proposed rules: the base args entry ${arg} names a path inside the working tree, so this gate was not run`,
|
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/normalize.js
CHANGED
|
@@ -533,8 +533,15 @@ function readTrustBase(raw, product) {
|
|
|
533
533
|
export function normalizeIntentGuard(raw, version) {
|
|
534
534
|
const product = 'intent-guard';
|
|
535
535
|
const root = needRecord(raw, product, 'the output');
|
|
536
|
-
|
|
537
|
-
|
|
536
|
+
// "skipped" is accepted ahead of the gate using it (issue 103): intent-guard
|
|
537
|
+
// 1.10.4 says "nothing was checked" as status ok plus skipReason, because
|
|
538
|
+
// anything else would have been unparseable to every conductor up to this
|
|
539
|
+
// one, and a later release can move to a status of its own once its pin
|
|
540
|
+
// floor is above this version. It is the one value added; every other
|
|
541
|
+
// status is still refused, and readSkipReason refuses a skipped status
|
|
542
|
+
// that names no reason or that carries a finding.
|
|
543
|
+
if (root.status !== 'blocked' && root.status !== 'ok' && root.status !== 'skipped') {
|
|
544
|
+
fail(product, 'status', 'one of "ok", "blocked" or "skipped"');
|
|
538
545
|
}
|
|
539
546
|
const trustBase = readTrustBase(root.trustBase, product);
|
|
540
547
|
const warnings = readIntentWarnings(root.warnings);
|
|
@@ -678,6 +685,7 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
678
685
|
: 'The intent gate blocked without stating a reason.', 'unattributed'));
|
|
679
686
|
}
|
|
680
687
|
}
|
|
688
|
+
const skipReason = readSkipReason(root, findings, product);
|
|
681
689
|
return {
|
|
682
690
|
findings,
|
|
683
691
|
...(trustBase === undefined ? {} : { trustBase }),
|
|
@@ -700,11 +708,43 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
700
708
|
driftCategories: drift?.categories ?? null,
|
|
701
709
|
budgetAction: budget?.action ?? null,
|
|
702
710
|
reasons,
|
|
711
|
+
// Present only when the gate said it checked nothing. The report
|
|
712
|
+
// surfaces read it through intentCheckedNothing in output-text.ts.
|
|
713
|
+
...(skipReason === null ? {} : { skipReason }),
|
|
703
714
|
},
|
|
704
715
|
},
|
|
705
716
|
diagnostics: [],
|
|
706
717
|
};
|
|
707
718
|
}
|
|
719
|
+
/**
|
|
720
|
+
* The gate's own statement that it checked nothing, or null (issue 103).
|
|
721
|
+
*
|
|
722
|
+
* intent-guard 1.10.4 puts a top-level `skipReason` string on a result whose
|
|
723
|
+
* status is still "ok" when require-frozen is off and there is no contract;
|
|
724
|
+
* a future status "skipped" means the same. Read only on those two
|
|
725
|
+
* statuses: a blocked result stays blocked whatever else it says, which is
|
|
726
|
+
* the fail-closed reading of a contradiction. An empty string is no reason.
|
|
727
|
+
*
|
|
728
|
+
* Refused as unparseable, never guessed at: a skipReason that is not a
|
|
729
|
+
* string, a status "skipped" that names no reason, and a skip that carries
|
|
730
|
+
* any finding. "Nothing was checked" beside a finding is a contradiction,
|
|
731
|
+
* and reading it as a skip would hide the finding, so the gate is reported
|
|
732
|
+
* as one whose output could not be read.
|
|
733
|
+
*/
|
|
734
|
+
function readSkipReason(root, findings, product) {
|
|
735
|
+
if (root.status === 'blocked') {
|
|
736
|
+
return null;
|
|
737
|
+
}
|
|
738
|
+
const said = optionalString(root.skipReason ?? undefined, product, 'skipReason');
|
|
739
|
+
const reason = said === undefined || said === '' ? null : said;
|
|
740
|
+
if (root.status === 'skipped' && reason === null) {
|
|
741
|
+
fail(product, 'skipReason', 'a non-empty string when status is "skipped"');
|
|
742
|
+
}
|
|
743
|
+
if (reason !== null && findings.length > 0) {
|
|
744
|
+
fail(product, 'findings', 'empty when the gate says it checked nothing (skipReason)');
|
|
745
|
+
}
|
|
746
|
+
return reason;
|
|
747
|
+
}
|
|
708
748
|
// -- gitleaks (external, git history mode) -------------------------------
|
|
709
749
|
//
|
|
710
750
|
// The report is a JSON array written to a file, one entry per leak, with
|
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, 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,
|
|
@@ -587,6 +587,27 @@ function treeUnchangedNotifications(result) {
|
|
|
587
587
|
* keep answering it the same way.
|
|
588
588
|
*/
|
|
589
589
|
function skippedNotifications(result) {
|
|
590
|
+
return [...preparedSkipNotifications(result), ...ranAndCheckedNothingNotifications(result)];
|
|
591
|
+
}
|
|
592
|
+
/**
|
|
593
|
+
* An intent gate that RAN and checked nothing (issue 103): intent-guard
|
|
594
|
+
* 1.10.4's skipReason on a directly spawned run, or, before it, no contract
|
|
595
|
+
* found with require-frozen off. Filed under the same id as the
|
|
596
|
+
* pull-request path's no-contract skip, with the same message shape and the
|
|
597
|
+
* gate's own sentence as the detail, because it is the same state and a
|
|
598
|
+
* consumer filtering on intent-guard/no-contract should see both. The same
|
|
599
|
+
* predicate the text report reads (intentCheckedNothing), so the two agree.
|
|
600
|
+
* The gate's own run is still in the log, since it did run.
|
|
601
|
+
*/
|
|
602
|
+
function ranAndCheckedNothingNotifications(result) {
|
|
603
|
+
return result.gates.filter(intentCheckedNothing).map((gate) => ({
|
|
604
|
+
id: `${gate.product}/no-contract`,
|
|
605
|
+
message: `The ${gate.role} gate (${gate.product}) checked nothing on this branch. ` +
|
|
606
|
+
(intentSkipReason(gate) ?? 'It found no contract to check against.'),
|
|
607
|
+
details: { role: gate.role, product: gate.product, reason: 'no-contract' },
|
|
608
|
+
}));
|
|
609
|
+
}
|
|
610
|
+
function preparedSkipNotifications(result) {
|
|
590
611
|
return result.skipped.map((gate) => ({
|
|
591
612
|
// The reason IS the second half of the id, which keeps
|
|
592
613
|
// intent-guard/no-contract exactly where consumers already have it and
|
|
@@ -1068,7 +1089,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
1068
1089
|
...deferredNotifications(result),
|
|
1069
1090
|
...excludedNotifications(result),
|
|
1070
1091
|
...treeUnchangedNotifications(result),
|
|
1071
|
-
...skippedNotifications(result),
|
|
1092
|
+
...skippedNotifications(result), ...emptyChangeSetNotifications(result), ...nothingToScanNotifications(result), ...baseMovedNotifications(result),
|
|
1072
1093
|
...unenforcedNotifications(result),
|
|
1073
1094
|
...legacyStateDirNotifications(result),
|
|
1074
1095
|
...weakMatchNotifications(result),
|
|
@@ -1125,3 +1146,48 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
1125
1146
|
}
|
|
1126
1147
|
return JSON.stringify({ $schema: SARIF_SCHEMA, version: '2.1.0', runs }, null, 2);
|
|
1127
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
|
|
@@ -177,6 +177,21 @@ export declare function versionSkewSummaryLines(result: RunResult): string[];
|
|
|
177
177
|
* not a pass.
|
|
178
178
|
*/
|
|
179
179
|
export declare function verdictToken(result: RunResult, advisory: boolean): string;
|
|
180
|
+
/**
|
|
181
|
+
* The gate's own skipReason (intent-guard 1.10.4, issue 103), or null. Put
|
|
182
|
+
* in the run details by normalizeIntentGuard only when non-empty.
|
|
183
|
+
*/
|
|
184
|
+
export declare function intentSkipReason(gate: GateOutcome): string | null;
|
|
185
|
+
/**
|
|
186
|
+
* An intent gate that RAN and checked nothing: it said so with skipReason,
|
|
187
|
+
* or (before 1.10.4) it reported no contract found. The one predicate the
|
|
188
|
+
* text report, its one-line summary and the SARIF notification all read, so
|
|
189
|
+
* a directly spawned run reports this state on the same surfaces as the
|
|
190
|
+
* pull-request path's no-contract skip (issue 103). Never for a gate that
|
|
191
|
+
* could not run or that blocked: a missing contract under require-frozen is
|
|
192
|
+
* a block, not a skip.
|
|
193
|
+
*/
|
|
194
|
+
export declare function intentCheckedNothing(gate: GateOutcome): boolean;
|
|
180
195
|
export interface TextOptions {
|
|
181
196
|
/**
|
|
182
197
|
* Print the full report even when the run is fully clean.
|
|
@@ -252,4 +267,22 @@ export declare const INTENT_SPEC_LINES: readonly ["intent-spec: none chosen, two
|
|
|
252
267
|
*/
|
|
253
268
|
export declare const DEP_GUARD_DEADLINE_CODE = "online-deadline-exceeded";
|
|
254
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[];
|
|
255
288
|
export {};
|