@vaultcompass/conductor 0.10.0 → 0.12.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 +131 -21
- package/dist/cli.js +27 -2
- package/dist/envelope.d.ts +7 -1
- package/dist/gate-runner.d.ts +36 -10
- package/dist/gate-runner.js +202 -19
- package/dist/intent-prepare.d.ts +33 -1
- package/dist/intent-prepare.js +137 -33
- package/dist/intent-spec.d.ts +108 -22
- package/dist/intent-spec.js +226 -55
- package/dist/normalize.js +28 -3
- package/dist/osv-baseline.d.ts +65 -0
- package/dist/osv-baseline.js +105 -1
- package/dist/osv-coverage.d.ts +18 -2
- package/dist/osv-coverage.js +47 -10
- package/dist/output-sarif.js +90 -1
- package/dist/output-text.d.ts +39 -7
- package/dist/output-text.js +205 -19
- package/dist/run.d.ts +9 -1
- package/dist/run.js +1 -0
- package/dist/unread-manifests.js +4 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -166,7 +166,7 @@ required.
|
|
|
166
166
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
167
167
|
|
|
168
168
|
```
|
|
169
|
-
conductor 0.
|
|
169
|
+
conductor 0.12.0
|
|
170
170
|
verdict-token: blocked (1)
|
|
171
171
|
conductor run: 2 gate(s), 1 finding(s)
|
|
172
172
|
|
|
@@ -359,11 +359,17 @@ gates:
|
|
|
359
359
|
secrets-history:
|
|
360
360
|
product: gitleaks
|
|
361
361
|
enabled: true
|
|
362
|
+
# Enabled because gitleaks was found on the machine that ran init. CI must
|
|
363
|
+
# install gitleaks itself (conductor does not); without it this gate
|
|
364
|
+
# reports conductor/gate-missing and the run exits 2.
|
|
362
365
|
stage: ci
|
|
363
366
|
enforce: true
|
|
364
367
|
vulnerabilities:
|
|
365
368
|
product: osv-scanner
|
|
366
369
|
enabled: true
|
|
370
|
+
# Enabled because osv-scanner was found on the machine that ran init. CI must
|
|
371
|
+
# install osv-scanner itself (conductor does not); without it this gate
|
|
372
|
+
# reports conductor/gate-missing and the run exits 2.
|
|
367
373
|
stage: ci
|
|
368
374
|
enforce: true
|
|
369
375
|
present-on-base: report
|
|
@@ -721,7 +727,12 @@ code and the `enforce` flags the run already had.
|
|
|
721
727
|
vulnerabilities already on the base branch, reported and not blocking;
|
|
722
728
|
the report's third line then says `present-on-base: N reported, not
|
|
723
729
|
blocking`, the verdict sentence says the same, and the Action copies that
|
|
724
|
-
line to the job summary under the token.
|
|
730
|
+
line to the job summary under the token. When the intent gate's spec was
|
|
731
|
+
chosen weakly, differently than before 0.11.0, or not at all because of a
|
|
732
|
+
tie or a branch 0.10.0 bound, the line after the token (after the
|
|
733
|
+
present-on-base line, when there is one) is one of four fixed
|
|
734
|
+
`intent-spec:` lines naming no branch or file, and the Action copies that
|
|
735
|
+
one too.
|
|
725
736
|
- `nothing-checked`: exit 0, but nothing was checked. Either no gate ran at
|
|
726
737
|
all (none is enabled, or every enabled one was deferred to a later stage,
|
|
727
738
|
had nothing to judge, or was skipped), or every gate that ran examined
|
|
@@ -1088,6 +1099,29 @@ gate (gitleaks) enabled, because conductor hands it `git log --diff-merges`,
|
|
|
1088
1099
|
which arrived in git 2.31. Only that gate checks: an older git makes it
|
|
1089
1100
|
could-not-run, naming the version, and the other gates run.
|
|
1090
1101
|
|
|
1102
|
+
### Trying pull-request mode locally
|
|
1103
|
+
|
|
1104
|
+
To see roughly what CI would say about a branch, check it out and name the
|
|
1105
|
+
base as the trust base:
|
|
1106
|
+
|
|
1107
|
+
```
|
|
1108
|
+
conductor run --trust-base refs/remotes/origin/main --verbose
|
|
1109
|
+
```
|
|
1110
|
+
|
|
1111
|
+
`--trust-base` takes any ref git resolves in your clone, so use a clone with
|
|
1112
|
+
the base branch present (the CI recipes use `fetch-depth: 0` for the same
|
|
1113
|
+
reason). With no `GITHUB_BASE_REF` set, as on a laptop, the change set for the
|
|
1114
|
+
intent gate is measured from the trust base, so `--base` is optional; add
|
|
1115
|
+
`--base <ref>` to measure from a different ref. Add `--stage ci` to run at
|
|
1116
|
+
the stage the Action runs at.
|
|
1117
|
+
|
|
1118
|
+
The gotcha is the same locally as in CI: the policy and the other control
|
|
1119
|
+
files are read from the base ref, not from your working tree. A local edit to
|
|
1120
|
+
`.guardrails.yaml` has no effect on a `--trust-base` run until the change is
|
|
1121
|
+
on the base; it shows up as a proposal line in the report instead. To preview
|
|
1122
|
+
a policy edit, run `conductor run` without `--trust-base`, as in "Adopting
|
|
1123
|
+
conductor" above.
|
|
1124
|
+
|
|
1091
1125
|
## Intent at a pull request
|
|
1092
1126
|
|
|
1093
1127
|
The intent gate is the only one of the five with any ceremony: its native
|
|
@@ -1180,12 +1214,24 @@ itself and needs an administrator to merge it.
|
|
|
1180
1214
|
token is exact and lowercase, a frozen contract at rule 2 still wins over
|
|
1181
1215
|
it, and `--spec` at rule 1 still overrides it.
|
|
1182
1216
|
4. A markdown file **directly under** `docs/superpowers/specs` whose name
|
|
1183
|
-
|
|
1184
|
-
segment (`feat/`, `fix/`) removed; a filename is reduced by
|
|
1185
|
-
`YYYY-MM-DD-` prefix and a trailing `-design
|
|
1186
|
-
|
|
1187
|
-
|
|
1188
|
-
|
|
1217
|
+
matches the branch on **whole words**. The branch slug is the branch name
|
|
1218
|
+
with its first segment (`feat/`, `fix/`) removed; a filename is reduced by
|
|
1219
|
+
stripping a `YYYY-MM-DD-` prefix and a trailing `-design`. Both have their
|
|
1220
|
+
ASCII letters lower-cased and are split into words on `-`, `_`, `/` and
|
|
1221
|
+
spaces. A spec is a candidate when one name's words appear, in order and
|
|
1222
|
+
together, inside the other's, and at least one shared word is three or
|
|
1223
|
+
more characters, contains a letter, and is not a common branch word
|
|
1224
|
+
(`fix`, `feat`, `wip`, `docs`, and the rest of the list in
|
|
1225
|
+
`src/intent-spec.ts`). Candidates are ranked by an equal name first, then
|
|
1226
|
+
the most shared words, then the longest shared word, then the lexically
|
|
1227
|
+
greatest filename among files with the same name (the newest date when
|
|
1228
|
+
every spec is dated `YYYY-MM-DD-`, so **date every spec** in that form).
|
|
1229
|
+
Two different specs that tie are **not** guessed between: the gate is
|
|
1230
|
+
skipped as `intent-guard/spec-ambiguous`, naming both. A spec chosen on
|
|
1231
|
+
one shared word, or on word length alone, is used and the report says the
|
|
1232
|
+
match is weak. Branch names like `pr` or `fix/wip` choose nothing. When
|
|
1233
|
+
the choice matters, say it: a `Spec:` line in the pull request body, or a
|
|
1234
|
+
branch named after the spec.
|
|
1189
1235
|
|
|
1190
1236
|
**A branch with neither** is a third state beside deferred and could-not-run:
|
|
1191
1237
|
the gate is switched on, it ran, and it had nothing to check. It gets one
|
|
@@ -1197,7 +1243,9 @@ repository. A waived pull request lands in the same state and is reported
|
|
|
1197
1243
|
under its own `intent-guard/contract-waived` id, with its own wording on the
|
|
1198
1244
|
skipped line, in the verdict and on the one-line summary of a clean run, so a
|
|
1199
1245
|
reader can tell "nobody has written one" from "somebody decided against one"
|
|
1200
|
-
wherever they meet it.
|
|
1246
|
+
wherever they meet it. An ambiguous branch, one two specs match equally,
|
|
1247
|
+
lands in the same advisory state under its own `intent-guard/spec-ambiguous`
|
|
1248
|
+
id, and never reaches the exit code either.
|
|
1201
1249
|
|
|
1202
1250
|
**A repository with no contract yet is not a repository this gate can act
|
|
1203
1251
|
on**, and the no-contract skip line names `docs/superpowers/specs`, which is
|
|
@@ -1222,7 +1270,8 @@ gate does not run at all on that pull request, and budget breaches are the
|
|
|
1222
1270
|
thing this gate blocks on. The one thing a waiver cannot override is a frozen
|
|
1223
1271
|
native contract, under either of the two paths above, which is checked first:
|
|
1224
1272
|
a repository that wants the gate to be non-waivable freezes a native contract
|
|
1225
|
-
and keeps it committed.
|
|
1273
|
+
and keeps it committed. The branch-name convention is not a control either:
|
|
1274
|
+
whoever names the branch chooses among the base's specs.
|
|
1226
1275
|
|
|
1227
1276
|
**What blocks is unchanged.** Blocking stays where intent-guard puts it:
|
|
1228
1277
|
budget breaches block, subject to `enforce`. Drift on its own is reported and
|
|
@@ -1268,7 +1317,11 @@ runs `npm install -g --ignore-scripts` under the runner temp, never into the
|
|
|
1268
1317
|
workspace, and prepends that bin directory to `PATH`, so the run step invokes
|
|
1269
1318
|
`conductor` off `PATH` and each gate resolves by name the same way. The install
|
|
1270
1319
|
is **unconditional**, on push and `pull_request` alike, so there is one code
|
|
1271
|
-
path rather than one that matters and one that nobody exercises.
|
|
1320
|
+
path rather than one that matters and one that nobody exercises. On a push
|
|
1321
|
+
run, though, a repository's own devDependency on a gate in
|
|
1322
|
+
`node_modules/.bin` outranks that install and shadows the action's pin; when
|
|
1323
|
+
its version differs from the pin, conductor now warns in the job log, as a
|
|
1324
|
+
`::warning::` annotation and in the step summary, and still runs it.
|
|
1272
1325
|
|
|
1273
1326
|
**On a pull request those four inputs may not pin backward.** The shape check
|
|
1274
1327
|
asks whether an input is an exact version; it says nothing about which one, and
|
|
@@ -1358,7 +1411,7 @@ request being judged, and the version-pin protection described above
|
|
|
1358
1411
|
"protects nothing" against a tree that controls its own judge (the
|
|
1359
1412
|
validate step's own comment in `action.yml` says so in those words). A tag
|
|
1360
1413
|
moves when someone pushes it. Name this action by owner and the full commit
|
|
1361
|
-
SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.
|
|
1414
|
+
SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.12.0.
|
|
1362
1415
|
|
|
1363
1416
|
```yaml
|
|
1364
1417
|
name: guardrails
|
|
@@ -1380,7 +1433,7 @@ jobs:
|
|
|
1380
1433
|
with:
|
|
1381
1434
|
node-version: '22.11.0'
|
|
1382
1435
|
- id: conductor
|
|
1383
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1436
|
+
uses: vaultcompasshq/conductor@v0.12.0
|
|
1384
1437
|
with:
|
|
1385
1438
|
output: conductor.sarif
|
|
1386
1439
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1455,7 +1508,7 @@ jobs:
|
|
|
1455
1508
|
# installs those itself, globally. Leave conductor-version unset so the
|
|
1456
1509
|
# umbrella is the default in the pinned action.yml.
|
|
1457
1510
|
- id: conductor
|
|
1458
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1511
|
+
uses: vaultcompasshq/conductor@v0.12.0
|
|
1459
1512
|
with:
|
|
1460
1513
|
output: conductor.sarif
|
|
1461
1514
|
# Exact versions, never a range and never "latest". These three
|
|
@@ -1466,9 +1519,9 @@ jobs:
|
|
|
1466
1519
|
# request of their own. On a pull request the action refuses a pin
|
|
1467
1520
|
# below what the pinned action.yml ships, and the three lines can
|
|
1468
1521
|
# be left out entirely to take that action's own versions.
|
|
1469
|
-
dep-guard-version: 0.
|
|
1470
|
-
vault-guard-version: 1.
|
|
1471
|
-
intent-guard-version: 1.
|
|
1522
|
+
dep-guard-version: 0.15.0
|
|
1523
|
+
vault-guard-version: 1.12.1
|
|
1524
|
+
intent-guard-version: 1.10.1
|
|
1472
1525
|
- uses: github/codeql-action/upload-sarif@v3
|
|
1473
1526
|
# Always: the log is most worth having on the run that failed.
|
|
1474
1527
|
if: always()
|
|
@@ -1661,7 +1714,7 @@ jobs:
|
|
|
1661
1714
|
node-version: '22.11.0'
|
|
1662
1715
|
- id: conductor
|
|
1663
1716
|
timeout-minutes: 5
|
|
1664
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1717
|
+
uses: vaultcompasshq/conductor@v0.12.0
|
|
1665
1718
|
with:
|
|
1666
1719
|
pr-comment: true
|
|
1667
1720
|
advisory: true
|
|
@@ -1797,7 +1850,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1797
1850
|
# the pull request runs before the action in this job: no install, build
|
|
1798
1851
|
# or test step here; those belong in a separate job. ...
|
|
1799
1852
|
- id: conductor
|
|
1800
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1853
|
+
uses: vaultcompasshq/conductor@v0.12.0
|
|
1801
1854
|
with:
|
|
1802
1855
|
output: conductor.sarif
|
|
1803
1856
|
pr-comment: true
|
|
@@ -1876,12 +1929,12 @@ per pull request.
|
|
|
1876
1929
|
|
|
1877
1930
|
```yaml
|
|
1878
1931
|
- id: conductor-package-a
|
|
1879
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1932
|
+
uses: vaultcompasshq/conductor@v0.12.0
|
|
1880
1933
|
with:
|
|
1881
1934
|
pr-comment: true
|
|
1882
1935
|
pr-comment-marker: 'package-a'
|
|
1883
1936
|
- id: conductor-package-b
|
|
1884
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1937
|
+
uses: vaultcompasshq/conductor@v0.12.0
|
|
1885
1938
|
with:
|
|
1886
1939
|
pr-comment: true
|
|
1887
1940
|
pr-comment-marker: 'package-b'
|
|
@@ -1981,6 +2034,63 @@ is one snapshot of one run: no per-finding state, nothing to dismiss, no
|
|
|
1981
2034
|
history between runs, and a new comment every time rather than an alert that
|
|
1982
2035
|
closes when the finding goes away.
|
|
1983
2036
|
|
|
2037
|
+
## Upgrading
|
|
2038
|
+
|
|
2039
|
+
An adopter pins two numbers, and they control different things.
|
|
2040
|
+
|
|
2041
|
+
- **The action ref**, `uses: vaultcompasshq/conductor@<tag or SHA>`, picks
|
|
2042
|
+
which `action.yml` runs. That file carries the defaults for the four
|
|
2043
|
+
version inputs and the constants the pull-request backward-pin rule
|
|
2044
|
+
measures a pin against.
|
|
2045
|
+
- **The `conductor-version` input** picks which `@vaultcompass/conductor`
|
|
2046
|
+
the install step installs. The same step installs the three gates at
|
|
2047
|
+
`dep-guard-version`, `vault-guard-version` and `intent-guard-version`.
|
|
2048
|
+
Each input defaults to the version the tag shipped.
|
|
2049
|
+
|
|
2050
|
+
**The recommended shape is to leave all four version inputs unset** and move
|
|
2051
|
+
only the action ref. On a pull request, the validate step refuses an input
|
|
2052
|
+
naming a version below the one the tag ships, so an explicit old pin breaks
|
|
2053
|
+
the day you upgrade the ref (see "The Action" above). Outside a pull request
|
|
2054
|
+
an explicit pin is unaffected, which is how a stale pin can sit unnoticed
|
|
2055
|
+
until the first pull request after the upgrade.
|
|
2056
|
+
|
|
2057
|
+
**Pin the action ref to a full commit SHA** with the tag as a comment, for
|
|
2058
|
+
example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.12.0`. To
|
|
2059
|
+
find the SHA for a tag, run
|
|
2060
|
+
`gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
|
|
2061
|
+
the Releases page.
|
|
2062
|
+
|
|
2063
|
+
**Dependabot or Renovate bumping that SHA changes the action ref only.** It
|
|
2064
|
+
does not touch a `dep-guard-version`, `vault-guard-version`,
|
|
2065
|
+
`intent-guard-version` or `conductor-version` you set by hand, so such a pin
|
|
2066
|
+
must be raised or removed by hand in the same pull request, or that pull
|
|
2067
|
+
request is refused by the rule above.
|
|
2068
|
+
|
|
2069
|
+
**An action-only tag moves the tag while the npm package stays.** The
|
|
2070
|
+
CHANGELOG marks these as "An action-only release" and says which
|
|
2071
|
+
`conductor-version` default stays. `@vaultcompass/conductor` does not change
|
|
2072
|
+
on those, so `conductor-version` need not change either; the gate defaults
|
|
2073
|
+
may.
|
|
2074
|
+
|
|
2075
|
+
Defaults per tag, taken only from CHANGELOG.md entries that state them. A
|
|
2076
|
+
tag with no row here has an entry that does not state its defaults; read
|
|
2077
|
+
`action.yml` at that tag.
|
|
2078
|
+
|
|
2079
|
+
| Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
|
|
2080
|
+
| --- | --- | --- | --- |
|
|
2081
|
+
| v0.12.0 | package | 0.12.0 | vault-guard 1.12.1 (from 1.12.0), intent-guard 1.10.1 (from 1.10.0) |
|
|
2082
|
+
| v0.11.1 | action-only | 0.11.0 | dep-guard 0.15.0 (from 0.14.0), vault-guard 1.12.0 (from 1.11.0) |
|
|
2083
|
+
| v0.11.0 | package | 0.11.0 | dep-guard 0.14.0, intent-guard 1.10.0 |
|
|
2084
|
+
| v0.10.0 | package | 0.10.0 | dep-guard 0.13.0, vault-guard 1.11.0 |
|
|
2085
|
+
| v0.8.2 | action-only | 0.8.1 | dep-guard 0.11.1 (from 0.10.1) |
|
|
2086
|
+
| v0.8.1 | package | 0.8.1 | dep-guard 0.10.1, vault-guard 1.9.1, intent-guard 1.8.1 |
|
|
2087
|
+
| v0.8.0 | package | 0.8.0 | dep-guard 0.10.0, vault-guard 1.9.0, intent-guard 1.8.0 |
|
|
2088
|
+
| v0.7.0 | package | 0.7.0 | none |
|
|
2089
|
+
| v0.6.0 | package | 0.6.0 | dep-guard 0.9.0 (from 0.8.0), intent-guard 1.7.0 (from 1.6.0) |
|
|
2090
|
+
| v0.5.1 | action-only | 0.5.0 | dep-guard 0.8.0 (from 0.7.0), intent-guard 1.6.0 (from 1.5.2) |
|
|
2091
|
+
| v0.4.4 | action-only | 0.4.0 | dep-guard 0.7.0 (from 0.6.0), vault-guard 1.8.0 (from 1.7.0) |
|
|
2092
|
+
| v0.4.3 | action-only | 0.4.0 | intent-guard 1.5.2 (from 1.4.0) |
|
|
2093
|
+
|
|
1984
2094
|
## What is in and what is out
|
|
1985
2095
|
|
|
1986
2096
|
In: the policy file and its schema, `init` with dry-run, revert, and adopt,
|
package/dist/cli.js
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
// parses arguments and prints. That split is what lets every one of those
|
|
7
7
|
// decisions be tested without a subprocess.
|
|
8
8
|
import { Command, CommanderError } from 'commander';
|
|
9
|
-
import { closeSync, constants as fsConstants, lstatSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from 'node:fs';
|
|
9
|
+
import { appendFileSync, closeSync, constants as fsConstants, lstatSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from 'node:fs';
|
|
10
10
|
import os from 'node:os';
|
|
11
11
|
import path from 'node:path';
|
|
12
12
|
import { fileURLToPath } from 'node:url';
|
|
@@ -14,7 +14,7 @@ import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
|
|
|
14
14
|
import { absolutePathEntries, createGitShim, pinGitOutside, pinnedGitInside, realPathInside, removeGitShim, runGit, tempInsideTreeMessage, workTreeAbove, } from './git.js';
|
|
15
15
|
import { applyInit, planInit, renderInitHuman, renderRevertHuman, revertInit, } from './init.js';
|
|
16
16
|
import { renderSarif } from './output-sarif.js';
|
|
17
|
-
import { gateLogLines, jobLogSummary, renderText, verdictToken, versionSkewWarnings, } from './output-text.js';
|
|
17
|
+
import { gateLogLines, jobLogSummary, renderText, verdictToken, versionSkewAnnotations, versionSkewSummaryLines, versionSkewWarnings, } from './output-text.js';
|
|
18
18
|
import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
|
|
19
19
|
import { refusedTrustBase, runAll } from './run.js';
|
|
20
20
|
import { headTreeEqualsBase, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
|
|
@@ -708,6 +708,31 @@ export function buildProgram() {
|
|
|
708
708
|
if (logLines.length > 0) {
|
|
709
709
|
process.stderr.write(`${logLines.join('\n')}\n`);
|
|
710
710
|
}
|
|
711
|
+
// IN GITHUB ACTIONS, A VERSION SKEW IS ALSO AN ANNOTATION AND A
|
|
712
|
+
// STEP-SUMMARY LINE, so a run on a stale gate is visible on the run's
|
|
713
|
+
// page without anybody opening the log (audit 2026-10-18: every guard
|
|
714
|
+
// repository's own push runs used a stale devDependency for weeks and
|
|
715
|
+
// only the log said which version ran). Reporting only. The
|
|
716
|
+
// annotation goes to stdout when stdout is not the report (--output
|
|
717
|
+
// given, which is how the Action runs), and to stderr otherwise. A
|
|
718
|
+
// summary that cannot be written is skipped: it never changes the
|
|
719
|
+
// exit code.
|
|
720
|
+
if (process.env.GITHUB_ACTIONS === 'true') {
|
|
721
|
+
const annotations = versionSkewAnnotations(result);
|
|
722
|
+
if (annotations.length > 0) {
|
|
723
|
+
(options.output !== undefined ? process.stdout : process.stderr).write(`${annotations.join('\n')}\n`);
|
|
724
|
+
}
|
|
725
|
+
const summaryFile = process.env.GITHUB_STEP_SUMMARY;
|
|
726
|
+
const summaryLines = versionSkewSummaryLines(result);
|
|
727
|
+
if (summaryFile !== undefined && summaryFile !== '' && summaryLines.length > 0) {
|
|
728
|
+
try {
|
|
729
|
+
appendFileSync(summaryFile, summaryLines.map((line) => `${line}\n\n`).join(''));
|
|
730
|
+
}
|
|
731
|
+
catch {
|
|
732
|
+
// The annotation and the log line above already say it.
|
|
733
|
+
}
|
|
734
|
+
}
|
|
735
|
+
}
|
|
711
736
|
process.exitCode = applyAdvisory(result.exitCode, advisory);
|
|
712
737
|
}
|
|
713
738
|
catch (err) {
|
package/dist/envelope.d.ts
CHANGED
|
@@ -21,7 +21,13 @@ export type Subject = {
|
|
|
21
21
|
manifest: string;
|
|
22
22
|
lockfile?: string;
|
|
23
23
|
}
|
|
24
|
-
/**
|
|
24
|
+
/**
|
|
25
|
+
* `column` and `endColumn` are 1-based here even where the source is
|
|
26
|
+
* 0-based (SARIF 2.1.0 sets a minimum of 1 on both). The gitleaks
|
|
27
|
+
* normalizer enforces it: a column below 1 becomes 1, and an `endColumn`
|
|
28
|
+
* is kept only when it is at least `column` and on the same line.
|
|
29
|
+
* vault-guard's is its 0-based column plus one, with no `endColumn`.
|
|
30
|
+
*/
|
|
25
31
|
| {
|
|
26
32
|
kind: 'location';
|
|
27
33
|
file: string;
|
package/dist/gate-runner.d.ts
CHANGED
|
@@ -2,7 +2,7 @@ import type { Diagnostic, Finding, RunSummary } from './envelope.js';
|
|
|
2
2
|
import type { ContractSource, IntentPreparation } from './intent-prepare.js';
|
|
3
3
|
import type { GatePolicy, GateRole, GateStage, Product } from './policy.js';
|
|
4
4
|
import { type BaseComparison } from './osv-baseline.js';
|
|
5
|
-
import type { ResolvedBinary } from './resolve.js';
|
|
5
|
+
import type { ResolutionSource, ResolvedBinary } from './resolve.js';
|
|
6
6
|
export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing' | 'spawn-failed' | 'gate-error' | 'unparseable-output'
|
|
7
7
|
/**
|
|
8
8
|
* The gate was never spawned because the run could not be set up for it:
|
|
@@ -58,7 +58,22 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
|
|
|
58
58
|
* Raised for the version probe, the scan, and the intent gate's
|
|
59
59
|
* preparation steps; `timedOut.step` says which spawn was stopped.
|
|
60
60
|
*/
|
|
61
|
-
| 'timed-out'
|
|
61
|
+
| 'timed-out'
|
|
62
|
+
/**
|
|
63
|
+
* The vulnerabilities gate on a decided trust base: a handed lockfile read
|
|
64
|
+
* no packages at the head, or a base lockfile is gone from the head with
|
|
65
|
+
* no populated replacement in its directory, and the base copy had
|
|
66
|
+
* packages, so the dependency set the head removed cannot be judged.
|
|
67
|
+
* Fail closed by design
|
|
68
|
+
* (docs/superpowers/specs/2026-10-18-emptied-lockfile-under-trust-base.md).
|
|
69
|
+
*/
|
|
70
|
+
| 'lockfile-emptied'
|
|
71
|
+
/**
|
|
72
|
+
* The same check could not clear the head: a base copy unreadable, a base
|
|
73
|
+
* run that failed or printed no count, a command-line mismatch, or a head
|
|
74
|
+
* run whose stderr carries no package count (a lowered verbosity).
|
|
75
|
+
*/
|
|
76
|
+
| 'lockfile-emptied-unverified';
|
|
62
77
|
/** Where a gate's time limit came from: the test hook, the policy, or the product default. */
|
|
63
78
|
export type TimeLimitSource = 'override' | 'policy' | 'default';
|
|
64
79
|
export interface TimeLimit {
|
|
@@ -66,7 +81,7 @@ export interface TimeLimit {
|
|
|
66
81
|
source: TimeLimitSource;
|
|
67
82
|
}
|
|
68
83
|
/** Which of a gate's spawns was stopped at the limit. The intent gate's check is `scan`. */
|
|
69
|
-
export type TimedOutStep = 'version-probe' | 'scan' | 'import-spec' | 'freeze';
|
|
84
|
+
export type TimedOutStep = 'version-probe' | 'scan' | 'import-spec' | 'freeze' | 'base-check';
|
|
70
85
|
export interface TimedOut {
|
|
71
86
|
step: TimedOutStep;
|
|
72
87
|
limitSeconds: number;
|
|
@@ -308,15 +323,25 @@ export interface GateOutcome {
|
|
|
308
323
|
*/
|
|
309
324
|
nodeModulesSkipped?: string;
|
|
310
325
|
/**
|
|
311
|
-
* Present only when this gate
|
|
312
|
-
*
|
|
313
|
-
*
|
|
314
|
-
* statement for a warning, never an input to a decision:
|
|
315
|
-
* trust-base handling and the exit code are all settled
|
|
326
|
+
* Present only when the version this gate reported differs from the one
|
|
327
|
+
* the run was told to expect (the Action's pin, handed over as an
|
|
328
|
+
* environment variable), and both are known, WHEREVER the binary was
|
|
329
|
+
* resolved from. A statement for a warning, never an input to a decision:
|
|
330
|
+
* resolution, trust-base handling and the exit code are all settled
|
|
331
|
+
* without it.
|
|
332
|
+
*
|
|
333
|
+
* Every location, not only PATH (audit 2026-10-18, the intent-guard
|
|
334
|
+
* audit's MB3). Outside a pull request a repository's own devDependency in
|
|
335
|
+
* node_modules/.bin outranks the Action's global install by design, and
|
|
336
|
+
* recording PATH alone left every guard repository's own push runs on
|
|
337
|
+
* stale gates with the pins set and nothing said. `path` is
|
|
338
|
+
* repository-relative when the binary is inside the repository (it
|
|
339
|
+
* reaches a published log through the reports), and absolute otherwise.
|
|
316
340
|
*/
|
|
317
341
|
versionSkew?: {
|
|
318
342
|
expected: string;
|
|
319
343
|
found: string;
|
|
344
|
+
source: ResolutionSource;
|
|
320
345
|
path: string;
|
|
321
346
|
};
|
|
322
347
|
/**
|
|
@@ -347,8 +372,9 @@ export interface GateOutcome {
|
|
|
347
372
|
export interface RunGateOptions {
|
|
348
373
|
/**
|
|
349
374
|
* The version this run expects of the gate, when something says so (the
|
|
350
|
-
* Action passes its pin). Compared with what the
|
|
351
|
-
* warning only. Absent means no expectation,
|
|
375
|
+
* Action passes its pin). Compared with what the resolved binary reports,
|
|
376
|
+
* wherever it was found, for a warning only. Absent means no expectation,
|
|
377
|
+
* which is every local run.
|
|
352
378
|
*/
|
|
353
379
|
expectedVersion?: string;
|
|
354
380
|
repoRoot: string;
|