@vaultcompass/conductor 0.11.0 → 0.13.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 +113 -13
- package/dist/cli.js +28 -2
- package/dist/envelope.d.ts +7 -1
- package/dist/gate-runner.d.ts +66 -10
- package/dist/gate-runner.js +271 -23
- package/dist/normalize.js +28 -3
- package/dist/osv-baseline.d.ts +74 -0
- package/dist/osv-baseline.js +138 -2
- package/dist/osv-coverage.d.ts +18 -2
- package/dist/osv-coverage.js +47 -10
- package/dist/output-sarif.js +37 -0
- package/dist/output-text.d.ts +23 -7
- package/dist/output-text.js +72 -12
- package/dist/products.d.ts +47 -0
- package/dist/products.js +64 -28
- package/dist/run.js +6 -4
- package/dist/unread-manifests.js +4 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -92,7 +92,9 @@ required.
|
|
|
92
92
|
|
|
93
93
|
**Globally, and that is the guidance for CI too.** A devDependency is
|
|
94
94
|
fine beside it for your own pre-commit hook, and nothing about a local
|
|
95
|
-
run changed
|
|
95
|
+
run changed, but under the Action keep it at the Action's pin or a push
|
|
96
|
+
run is could-not-run (see "The Action" below). It is not what gates
|
|
97
|
+
your pull requests: on a pull-request
|
|
96
98
|
run the umbrella never looks in `node_modules/.bin` at all, because what
|
|
97
99
|
is installed there is chosen by the head's own manifest and lockfile. The
|
|
98
100
|
Action installs all four packages itself, globally, at versions pinned in
|
|
@@ -166,7 +168,7 @@ required.
|
|
|
166
168
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
167
169
|
|
|
168
170
|
```
|
|
169
|
-
conductor 0.
|
|
171
|
+
conductor 0.13.0
|
|
170
172
|
verdict-token: blocked (1)
|
|
171
173
|
conductor run: 2 gate(s), 1 finding(s)
|
|
172
174
|
|
|
@@ -359,11 +361,17 @@ gates:
|
|
|
359
361
|
secrets-history:
|
|
360
362
|
product: gitleaks
|
|
361
363
|
enabled: true
|
|
364
|
+
# Enabled because gitleaks was found on the machine that ran init. CI must
|
|
365
|
+
# install gitleaks itself (conductor does not); without it this gate
|
|
366
|
+
# reports conductor/gate-missing and the run exits 2.
|
|
362
367
|
stage: ci
|
|
363
368
|
enforce: true
|
|
364
369
|
vulnerabilities:
|
|
365
370
|
product: osv-scanner
|
|
366
371
|
enabled: true
|
|
372
|
+
# Enabled because osv-scanner was found on the machine that ran init. CI must
|
|
373
|
+
# install osv-scanner itself (conductor does not); without it this gate
|
|
374
|
+
# reports conductor/gate-missing and the run exits 2.
|
|
367
375
|
stage: ci
|
|
368
376
|
enforce: true
|
|
369
377
|
present-on-base: report
|
|
@@ -1093,6 +1101,29 @@ gate (gitleaks) enabled, because conductor hands it `git log --diff-merges`,
|
|
|
1093
1101
|
which arrived in git 2.31. Only that gate checks: an older git makes it
|
|
1094
1102
|
could-not-run, naming the version, and the other gates run.
|
|
1095
1103
|
|
|
1104
|
+
### Trying pull-request mode locally
|
|
1105
|
+
|
|
1106
|
+
To see roughly what CI would say about a branch, check it out and name the
|
|
1107
|
+
base as the trust base:
|
|
1108
|
+
|
|
1109
|
+
```
|
|
1110
|
+
conductor run --trust-base refs/remotes/origin/main --verbose
|
|
1111
|
+
```
|
|
1112
|
+
|
|
1113
|
+
`--trust-base` takes any ref git resolves in your clone, so use a clone with
|
|
1114
|
+
the base branch present (the CI recipes use `fetch-depth: 0` for the same
|
|
1115
|
+
reason). With no `GITHUB_BASE_REF` set, as on a laptop, the change set for the
|
|
1116
|
+
intent gate is measured from the trust base, so `--base` is optional; add
|
|
1117
|
+
`--base <ref>` to measure from a different ref. Add `--stage ci` to run at
|
|
1118
|
+
the stage the Action runs at.
|
|
1119
|
+
|
|
1120
|
+
The gotcha is the same locally as in CI: the policy and the other control
|
|
1121
|
+
files are read from the base ref, not from your working tree. A local edit to
|
|
1122
|
+
`.guardrails.yaml` has no effect on a `--trust-base` run until the change is
|
|
1123
|
+
on the base; it shows up as a proposal line in the report instead. To preview
|
|
1124
|
+
a policy edit, run `conductor run` without `--trust-base`, as in "Adopting
|
|
1125
|
+
conductor" above.
|
|
1126
|
+
|
|
1096
1127
|
## Intent at a pull request
|
|
1097
1128
|
|
|
1098
1129
|
The intent gate is the only one of the five with any ceremony: its native
|
|
@@ -1288,7 +1319,18 @@ runs `npm install -g --ignore-scripts` under the runner temp, never into the
|
|
|
1288
1319
|
workspace, and prepends that bin directory to `PATH`, so the run step invokes
|
|
1289
1320
|
`conductor` off `PATH` and each gate resolves by name the same way. The install
|
|
1290
1321
|
is **unconditional**, on push and `pull_request` alike, so there is one code
|
|
1291
|
-
path rather than one that matters and one that nobody exercises.
|
|
1322
|
+
path rather than one that matters and one that nobody exercises. On a push
|
|
1323
|
+
run, though, a repository's own devDependency on a gate in
|
|
1324
|
+
`node_modules/.bin` outranks that install and shadows the action's pin. Since
|
|
1325
|
+
0.13.0, when a gate's version differs from the pin, wherever it was found
|
|
1326
|
+
(`node_modules/.bin`, `PATH` or a policy `command:`), conductor does not run
|
|
1327
|
+
it: the gate is could-not-run, reason `version-skew`, and the run exits 2,
|
|
1328
|
+
whatever the policy's `enforce` and whatever `advisory` say. It is named in
|
|
1329
|
+
the job log, as a `::error::` annotation, in the step summary and in the
|
|
1330
|
+
reports. A gate whose version cannot be read under the Action is
|
|
1331
|
+
could-not-run too, reason `version-unverified`. The fix is to bump the
|
|
1332
|
+
devDependency to the pin or remove it. A plain `conductor run` outside the
|
|
1333
|
+
Action sets no pin and is unchanged.
|
|
1292
1334
|
|
|
1293
1335
|
**On a pull request those four inputs may not pin backward.** The shape check
|
|
1294
1336
|
asks whether an input is an exact version; it says nothing about which one, and
|
|
@@ -1378,7 +1420,7 @@ request being judged, and the version-pin protection described above
|
|
|
1378
1420
|
"protects nothing" against a tree that controls its own judge (the
|
|
1379
1421
|
validate step's own comment in `action.yml` says so in those words). A tag
|
|
1380
1422
|
moves when someone pushes it. Name this action by owner and the full commit
|
|
1381
|
-
SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.
|
|
1423
|
+
SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.13.0.
|
|
1382
1424
|
|
|
1383
1425
|
```yaml
|
|
1384
1426
|
name: guardrails
|
|
@@ -1400,7 +1442,7 @@ jobs:
|
|
|
1400
1442
|
with:
|
|
1401
1443
|
node-version: '22.11.0'
|
|
1402
1444
|
- id: conductor
|
|
1403
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1445
|
+
uses: vaultcompasshq/conductor@v0.13.0
|
|
1404
1446
|
with:
|
|
1405
1447
|
output: conductor.sarif
|
|
1406
1448
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1475,7 +1517,7 @@ jobs:
|
|
|
1475
1517
|
# installs those itself, globally. Leave conductor-version unset so the
|
|
1476
1518
|
# umbrella is the default in the pinned action.yml.
|
|
1477
1519
|
- id: conductor
|
|
1478
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1520
|
+
uses: vaultcompasshq/conductor@v0.13.0
|
|
1479
1521
|
with:
|
|
1480
1522
|
output: conductor.sarif
|
|
1481
1523
|
# Exact versions, never a range and never "latest". These three
|
|
@@ -1486,9 +1528,9 @@ jobs:
|
|
|
1486
1528
|
# request of their own. On a pull request the action refuses a pin
|
|
1487
1529
|
# below what the pinned action.yml ships, and the three lines can
|
|
1488
1530
|
# be left out entirely to take that action's own versions.
|
|
1489
|
-
dep-guard-version: 0.
|
|
1490
|
-
vault-guard-version: 1.
|
|
1491
|
-
intent-guard-version: 1.10.
|
|
1531
|
+
dep-guard-version: 0.15.0
|
|
1532
|
+
vault-guard-version: 1.12.1
|
|
1533
|
+
intent-guard-version: 1.10.1
|
|
1492
1534
|
- uses: github/codeql-action/upload-sarif@v3
|
|
1493
1535
|
# Always: the log is most worth having on the run that failed.
|
|
1494
1536
|
if: always()
|
|
@@ -1681,7 +1723,7 @@ jobs:
|
|
|
1681
1723
|
node-version: '22.11.0'
|
|
1682
1724
|
- id: conductor
|
|
1683
1725
|
timeout-minutes: 5
|
|
1684
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1726
|
+
uses: vaultcompasshq/conductor@v0.13.0
|
|
1685
1727
|
with:
|
|
1686
1728
|
pr-comment: true
|
|
1687
1729
|
advisory: true
|
|
@@ -1817,7 +1859,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1817
1859
|
# the pull request runs before the action in this job: no install, build
|
|
1818
1860
|
# or test step here; those belong in a separate job. ...
|
|
1819
1861
|
- id: conductor
|
|
1820
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1862
|
+
uses: vaultcompasshq/conductor@v0.13.0
|
|
1821
1863
|
with:
|
|
1822
1864
|
output: conductor.sarif
|
|
1823
1865
|
pr-comment: true
|
|
@@ -1896,12 +1938,12 @@ per pull request.
|
|
|
1896
1938
|
|
|
1897
1939
|
```yaml
|
|
1898
1940
|
- id: conductor-package-a
|
|
1899
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1941
|
+
uses: vaultcompasshq/conductor@v0.13.0
|
|
1900
1942
|
with:
|
|
1901
1943
|
pr-comment: true
|
|
1902
1944
|
pr-comment-marker: 'package-a'
|
|
1903
1945
|
- id: conductor-package-b
|
|
1904
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1946
|
+
uses: vaultcompasshq/conductor@v0.13.0
|
|
1905
1947
|
with:
|
|
1906
1948
|
pr-comment: true
|
|
1907
1949
|
pr-comment-marker: 'package-b'
|
|
@@ -2001,6 +2043,64 @@ is one snapshot of one run: no per-finding state, nothing to dismiss, no
|
|
|
2001
2043
|
history between runs, and a new comment every time rather than an alert that
|
|
2002
2044
|
closes when the finding goes away.
|
|
2003
2045
|
|
|
2046
|
+
## Upgrading
|
|
2047
|
+
|
|
2048
|
+
An adopter pins two numbers, and they control different things.
|
|
2049
|
+
|
|
2050
|
+
- **The action ref**, `uses: vaultcompasshq/conductor@<tag or SHA>`, picks
|
|
2051
|
+
which `action.yml` runs. That file carries the defaults for the four
|
|
2052
|
+
version inputs and the constants the pull-request backward-pin rule
|
|
2053
|
+
measures a pin against.
|
|
2054
|
+
- **The `conductor-version` input** picks which `@vaultcompass/conductor`
|
|
2055
|
+
the install step installs. The same step installs the three gates at
|
|
2056
|
+
`dep-guard-version`, `vault-guard-version` and `intent-guard-version`.
|
|
2057
|
+
Each input defaults to the version the tag shipped.
|
|
2058
|
+
|
|
2059
|
+
**The recommended shape is to leave all four version inputs unset** and move
|
|
2060
|
+
only the action ref. On a pull request, the validate step refuses an input
|
|
2061
|
+
naming a version below the one the tag ships, so an explicit old pin breaks
|
|
2062
|
+
the day you upgrade the ref (see "The Action" above). Outside a pull request
|
|
2063
|
+
an explicit pin is unaffected, which is how a stale pin can sit unnoticed
|
|
2064
|
+
until the first pull request after the upgrade.
|
|
2065
|
+
|
|
2066
|
+
**Pin the action ref to a full commit SHA** with the tag as a comment, for
|
|
2067
|
+
example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.13.0`. To
|
|
2068
|
+
find the SHA for a tag, run
|
|
2069
|
+
`gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
|
|
2070
|
+
the Releases page.
|
|
2071
|
+
|
|
2072
|
+
**Dependabot or Renovate bumping that SHA changes the action ref only.** It
|
|
2073
|
+
does not touch a `dep-guard-version`, `vault-guard-version`,
|
|
2074
|
+
`intent-guard-version` or `conductor-version` you set by hand, so such a pin
|
|
2075
|
+
must be raised or removed by hand in the same pull request, or that pull
|
|
2076
|
+
request is refused by the rule above.
|
|
2077
|
+
|
|
2078
|
+
**An action-only tag moves the tag while the npm package stays.** The
|
|
2079
|
+
CHANGELOG marks these as "An action-only release" and says which
|
|
2080
|
+
`conductor-version` default stays. `@vaultcompass/conductor` does not change
|
|
2081
|
+
on those, so `conductor-version` need not change either; the gate defaults
|
|
2082
|
+
may.
|
|
2083
|
+
|
|
2084
|
+
Defaults per tag, taken only from CHANGELOG.md entries that state them. A
|
|
2085
|
+
tag with no row here has an entry that does not state its defaults; read
|
|
2086
|
+
`action.yml` at that tag.
|
|
2087
|
+
|
|
2088
|
+
| Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
|
|
2089
|
+
| --- | --- | --- | --- |
|
|
2090
|
+
| v0.13.0 | package | 0.13.0 | none (gate defaults unchanged) |
|
|
2091
|
+
| 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) |
|
|
2092
|
+
| 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) |
|
|
2093
|
+
| v0.11.0 | package | 0.11.0 | dep-guard 0.14.0, intent-guard 1.10.0 |
|
|
2094
|
+
| v0.10.0 | package | 0.10.0 | dep-guard 0.13.0, vault-guard 1.11.0 |
|
|
2095
|
+
| v0.8.2 | action-only | 0.8.1 | dep-guard 0.11.1 (from 0.10.1) |
|
|
2096
|
+
| v0.8.1 | package | 0.8.1 | dep-guard 0.10.1, vault-guard 1.9.1, intent-guard 1.8.1 |
|
|
2097
|
+
| v0.8.0 | package | 0.8.0 | dep-guard 0.10.0, vault-guard 1.9.0, intent-guard 1.8.0 |
|
|
2098
|
+
| v0.7.0 | package | 0.7.0 | none |
|
|
2099
|
+
| 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) |
|
|
2100
|
+
| 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) |
|
|
2101
|
+
| 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) |
|
|
2102
|
+
| v0.4.3 | action-only | 0.4.0 | intent-guard 1.5.2 (from 1.4.0) |
|
|
2103
|
+
|
|
2004
2104
|
## What is in and what is out
|
|
2005
2105
|
|
|
2006
2106
|
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,32 @@ 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). Since 0.13.0 that gate is
|
|
716
|
+
// could-not-run, decided in runGate; these lines only say so. The
|
|
717
|
+
// annotation goes to stdout when stdout is not the report (--output
|
|
718
|
+
// given, which is how the Action runs), and to stderr otherwise. A
|
|
719
|
+
// summary that cannot be written is skipped: it never changes the
|
|
720
|
+
// exit code.
|
|
721
|
+
if (process.env.GITHUB_ACTIONS === 'true') {
|
|
722
|
+
const annotations = versionSkewAnnotations(result);
|
|
723
|
+
if (annotations.length > 0) {
|
|
724
|
+
(options.output !== undefined ? process.stdout : process.stderr).write(`${annotations.join('\n')}\n`);
|
|
725
|
+
}
|
|
726
|
+
const summaryFile = process.env.GITHUB_STEP_SUMMARY;
|
|
727
|
+
const summaryLines = versionSkewSummaryLines(result);
|
|
728
|
+
if (summaryFile !== undefined && summaryFile !== '' && summaryLines.length > 0) {
|
|
729
|
+
try {
|
|
730
|
+
appendFileSync(summaryFile, summaryLines.map((line) => `${line}\n\n`).join(''));
|
|
731
|
+
}
|
|
732
|
+
catch {
|
|
733
|
+
// The annotation and the log line above already say it.
|
|
734
|
+
}
|
|
735
|
+
}
|
|
736
|
+
}
|
|
711
737
|
process.exitCode = applyAdvisory(result.exitCode, advisory);
|
|
712
738
|
}
|
|
713
739
|
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,35 @@ 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 run was told which version of this gate must judge it (the Action's
|
|
73
|
+
* pin, `RunGateOptions.expectedVersion`) and the resolved binary reports
|
|
74
|
+
* another one, from whichever location resolution took it. The gate's
|
|
75
|
+
* check was not run. Design:
|
|
76
|
+
* docs/superpowers/specs/2026-10-18-version-skew-could-not-run.md.
|
|
77
|
+
*/
|
|
78
|
+
| 'version-skew'
|
|
79
|
+
/**
|
|
80
|
+
* The same expectation, and the resolved binary's version could not be
|
|
81
|
+
* read, so it is not known to be the expected one. Fail closed.
|
|
82
|
+
*/
|
|
83
|
+
| 'version-unverified'
|
|
84
|
+
/**
|
|
85
|
+
* The same check could not clear the head: a base copy unreadable, a base
|
|
86
|
+
* run that failed or printed no count, a command-line mismatch, or a head
|
|
87
|
+
* run whose stderr carries no package count (a lowered verbosity).
|
|
88
|
+
*/
|
|
89
|
+
| 'lockfile-emptied-unverified';
|
|
62
90
|
/** Where a gate's time limit came from: the test hook, the policy, or the product default. */
|
|
63
91
|
export type TimeLimitSource = 'override' | 'policy' | 'default';
|
|
64
92
|
export interface TimeLimit {
|
|
@@ -66,7 +94,7 @@ export interface TimeLimit {
|
|
|
66
94
|
source: TimeLimitSource;
|
|
67
95
|
}
|
|
68
96
|
/** 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';
|
|
97
|
+
export type TimedOutStep = 'version-probe' | 'scan' | 'import-spec' | 'freeze' | 'base-check';
|
|
70
98
|
export interface TimedOut {
|
|
71
99
|
step: TimedOutStep;
|
|
72
100
|
limitSeconds: number;
|
|
@@ -105,6 +133,22 @@ export declare function breakWorkflowMarkers(text: string): string;
|
|
|
105
133
|
* it, as opposed to something the gate itself said or did.
|
|
106
134
|
*/
|
|
107
135
|
export declare const CONDUCTOR_OWN_REASONS: ReadonlySet<CouldNotRunReason>;
|
|
136
|
+
/**
|
|
137
|
+
* A probed version as it may be printed. The probe for the family gates
|
|
138
|
+
* accepts anything after x.y.z on the first line, and the text reaches a
|
|
139
|
+
* workflow command, the step summary and the reports, so only version
|
|
140
|
+
* characters are kept.
|
|
141
|
+
*/
|
|
142
|
+
export declare function versionCharacters(raw: string): string;
|
|
143
|
+
/** Where a resolved binary came from, in words. Never a machine path. */
|
|
144
|
+
export declare function resolutionPlace(source: ResolutionSource): string;
|
|
145
|
+
/**
|
|
146
|
+
* The remedy for a gate that is not at the expected version, which depends
|
|
147
|
+
* on where the binary came from. THE ONE PLACE it is written: the
|
|
148
|
+
* could-not-run detail and every version-skew line in src/output-text.ts
|
|
149
|
+
* call this.
|
|
150
|
+
*/
|
|
151
|
+
export declare function versionSkewRemedy(product: string, source: ResolutionSource, expected: string): string;
|
|
108
152
|
/**
|
|
109
153
|
* A gate's time limit, and where it came from. THE ONE PLACE the precedence
|
|
110
154
|
* is written: the test hook (`RunGateOptions.timeoutMs`, which no CLI path
|
|
@@ -308,15 +352,25 @@ export interface GateOutcome {
|
|
|
308
352
|
*/
|
|
309
353
|
nodeModulesSkipped?: string;
|
|
310
354
|
/**
|
|
311
|
-
* Present only when this gate
|
|
312
|
-
*
|
|
313
|
-
*
|
|
314
|
-
*
|
|
315
|
-
*
|
|
355
|
+
* Present only when the version this gate reported differs from the one
|
|
356
|
+
* the run was told to expect (the Action's pin, handed over as an
|
|
357
|
+
* environment variable), and both are known, WHEREVER the binary was
|
|
358
|
+
* resolved from. Since 0.13.0 it is present exactly on a `version-skew`
|
|
359
|
+
* could-not-run, and carries the facts the warning surfaces print; it is
|
|
360
|
+
* the outcome, not this record, that the exit code reads.
|
|
361
|
+
*
|
|
362
|
+
* Every location, not only PATH (audit 2026-10-18, the intent-guard
|
|
363
|
+
* audit's MB3). Outside a pull request a repository's own devDependency in
|
|
364
|
+
* node_modules/.bin outranks the Action's global install by design, and
|
|
365
|
+
* recording PATH alone left every guard repository's own push runs on
|
|
366
|
+
* stale gates with the pins set and nothing said. `path` is
|
|
367
|
+
* repository-relative when the binary is inside the repository (it
|
|
368
|
+
* reaches a published log through the reports), and absolute otherwise.
|
|
316
369
|
*/
|
|
317
370
|
versionSkew?: {
|
|
318
371
|
expected: string;
|
|
319
372
|
found: string;
|
|
373
|
+
source: ResolutionSource;
|
|
320
374
|
path: string;
|
|
321
375
|
};
|
|
322
376
|
/**
|
|
@@ -347,8 +401,10 @@ export interface GateOutcome {
|
|
|
347
401
|
export interface RunGateOptions {
|
|
348
402
|
/**
|
|
349
403
|
* The version this run expects of the gate, when something says so (the
|
|
350
|
-
* Action passes its pin). Compared with what the
|
|
351
|
-
*
|
|
404
|
+
* Action passes its pin). Compared with what the resolved binary reports,
|
|
405
|
+
* wherever it was found: another version is `version-skew` and an
|
|
406
|
+
* unreadable one `version-unverified`, both could-not-run (0.13.0). Absent
|
|
407
|
+
* means no expectation, which is every local run, and changes nothing.
|
|
352
408
|
*/
|
|
353
409
|
expectedVersion?: string;
|
|
354
410
|
repoRoot: string;
|