@vaultcompass/conductor 0.13.0 → 0.14.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 +72 -13
- package/dist/cli.d.ts +38 -0
- package/dist/cli.js +77 -6
- package/dist/gate-runner.d.ts +86 -4
- package/dist/gate-runner.js +350 -78
- package/dist/output-sarif.d.ts +2 -2
- package/dist/output-sarif.js +47 -2
- package/dist/output-text.d.ts +37 -1
- package/dist/output-text.js +111 -21
- package/dist/policy-diff.d.ts +34 -0
- package/dist/policy-diff.js +173 -0
- package/dist/run.d.ts +63 -0
- package/dist/run.js +164 -22
- package/package.json +1 -1
- package/schema/guardrails.schema.json +1 -1
package/README.md
CHANGED
|
@@ -168,7 +168,7 @@ required.
|
|
|
168
168
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
169
169
|
|
|
170
170
|
```
|
|
171
|
-
conductor 0.
|
|
171
|
+
conductor 0.14.0
|
|
172
172
|
verdict-token: blocked (1)
|
|
173
173
|
conductor run: 2 gate(s), 1 finding(s)
|
|
174
174
|
|
|
@@ -889,7 +889,11 @@ branch first, like any other rule change.
|
|
|
889
889
|
**A change to the rules is not refused, it is proposed.** Rules legitimately
|
|
890
890
|
change, and a gate that blocked every such pull request would train people to
|
|
891
891
|
bypass it. So a policy file that differs from the base ref's is reported as
|
|
892
|
-
one line
|
|
892
|
+
one line per changed key, `policy: gates.<role>.<key> <old> -> <new>`, counted
|
|
893
|
+
as one proposal each; a head `.guardrails.yaml` that is absent or does not
|
|
894
|
+
parse gives one line saying its changes are not known, and when no effective
|
|
895
|
+
key differs (a default spelled out, or the YAML reordered) the old single line,
|
|
896
|
+
`policy changed in this pull request`, is kept. The run continues under the
|
|
893
897
|
base ref's rules, and the change takes effect **after merge**, on the first
|
|
894
898
|
run whose base branch carries it. The gates' own proposals are summed with it
|
|
895
899
|
into one sentence, `N control change(s) proposed in this pull request`, on the
|
|
@@ -1124,6 +1128,51 @@ on the base; it shows up as a proposal line in the report instead. To preview
|
|
|
1124
1128
|
a policy edit, run `conductor run` without `--trust-base`, as in "Adopting
|
|
1125
1129
|
conductor" above.
|
|
1126
1130
|
|
|
1131
|
+
Where the proposals appear under the Action: the job log gets a
|
|
1132
|
+
`conductor: N control change(s) proposed in this pull request.` line followed
|
|
1133
|
+
by one `conductor: proposed <product> <line>` line per proposal, and the step
|
|
1134
|
+
summary gets the same count and up to 50 proposed lines under `control
|
|
1135
|
+
changes:` in a text block, with a `(n more in the report)` line when there are
|
|
1136
|
+
more. This does not depend on `pr-comment`. A proposed line that holds a
|
|
1137
|
+
backtick or a character outside printable ASCII is replaced by a placeholder.
|
|
1138
|
+
|
|
1139
|
+
### The preview under the proposed rules
|
|
1140
|
+
|
|
1141
|
+
A pull request that switches a gate on or off, or moves its `stage`, is judged
|
|
1142
|
+
under the base's rules, so the author would not otherwise see what the
|
|
1143
|
+
proposed rules say until after merge. With the preview, each role whose
|
|
1144
|
+
`enabled` or `stage` changed runs once more (a role the head switches off is skipped), after the verdict, under the base
|
|
1145
|
+
policy with only `enabled`, `stage` and `enforce` taken from the head. Every
|
|
1146
|
+
other head value, `command:`, `args:`, `options` and `timeout-seconds`
|
|
1147
|
+
included, never reaches it: the base's command and the base's limit are what
|
|
1148
|
+
run, and a base `command:` that resolves inside the working tree is refused
|
|
1149
|
+
there. A gate's own config is another matter: in the preview, dep-guard and
|
|
1150
|
+
vault-guard read their own `.dep-guard.json` and `.vault-guard.json` from the
|
|
1151
|
+
head, because previewing the proposed rules means their rules too, while
|
|
1152
|
+
gitleaks and osv-scanner keep the base's config. osv-scanner call analysis is
|
|
1153
|
+
refused in the preview, because it would build the head's code. The intent
|
|
1154
|
+
gate is deferred and not previewed.
|
|
1155
|
+
|
|
1156
|
+
**The preview decides nothing.** The exit code, the verdict token and the SARIF
|
|
1157
|
+
results are those of the run under the base rules, whatever the preview finds
|
|
1158
|
+
or however it fails. In the full report (`--verbose`, the form the Action
|
|
1159
|
+
reads) the first four lines are untouched; in the one-line clean form the
|
|
1160
|
+
primary report is a byte-for-byte prefix and the preview follows it. It prints after
|
|
1161
|
+
the verdict under `Preview under the proposed rules (does not affect the
|
|
1162
|
+
verdict)`, as `conductor: preview ...` lines in the job log, as note-level
|
|
1163
|
+
`conductor/preview-under-proposed-rules` notifications on the umbrella's SARIF
|
|
1164
|
+
run, and as one `preview: N gate(s), M finding(s), K could-not-run` line in
|
|
1165
|
+
the step summary. The whole preview has a hard deadline of 300 seconds; a
|
|
1166
|
+
gate reached with no budget left is listed as over budget, and one that starts and is killed at the deadline is could-not-run (timed-out). A gate section in the preview
|
|
1167
|
+
uses the same words as a primary section, so a finding may read `BLOCKING`
|
|
1168
|
+
there: it means the finding would block under the proposed rules, and it does
|
|
1169
|
+
not affect this run. A pull-request comment is cut at 60000 characters, the
|
|
1170
|
+
preview block first.
|
|
1171
|
+
|
|
1172
|
+
Ask for it with `--preview` on `conductor run`, or with the Action's `preview`
|
|
1173
|
+
input, which defaults to `true`; any other value turns it off. There is no
|
|
1174
|
+
preview when the head `.guardrails.yaml` does not parse.
|
|
1175
|
+
|
|
1127
1176
|
## Intent at a pull request
|
|
1128
1177
|
|
|
1129
1178
|
The intent gate is the only one of the five with any ceremony: its native
|
|
@@ -1420,7 +1469,7 @@ request being judged, and the version-pin protection described above
|
|
|
1420
1469
|
"protects nothing" against a tree that controls its own judge (the
|
|
1421
1470
|
validate step's own comment in `action.yml` says so in those words). A tag
|
|
1422
1471
|
moves when someone pushes it. Name this action by owner and the full commit
|
|
1423
|
-
SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.
|
|
1472
|
+
SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.14.0.
|
|
1424
1473
|
|
|
1425
1474
|
```yaml
|
|
1426
1475
|
name: guardrails
|
|
@@ -1442,7 +1491,7 @@ jobs:
|
|
|
1442
1491
|
with:
|
|
1443
1492
|
node-version: '22.11.0'
|
|
1444
1493
|
- id: conductor
|
|
1445
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1494
|
+
uses: vaultcompasshq/conductor@v0.14.0
|
|
1446
1495
|
with:
|
|
1447
1496
|
output: conductor.sarif
|
|
1448
1497
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1517,7 +1566,7 @@ jobs:
|
|
|
1517
1566
|
# installs those itself, globally. Leave conductor-version unset so the
|
|
1518
1567
|
# umbrella is the default in the pinned action.yml.
|
|
1519
1568
|
- id: conductor
|
|
1520
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1569
|
+
uses: vaultcompasshq/conductor@v0.14.0
|
|
1521
1570
|
with:
|
|
1522
1571
|
output: conductor.sarif
|
|
1523
1572
|
# Exact versions, never a range and never "latest". These three
|
|
@@ -1528,7 +1577,7 @@ jobs:
|
|
|
1528
1577
|
# request of their own. On a pull request the action refuses a pin
|
|
1529
1578
|
# below what the pinned action.yml ships, and the three lines can
|
|
1530
1579
|
# be left out entirely to take that action's own versions.
|
|
1531
|
-
dep-guard-version: 0.
|
|
1580
|
+
dep-guard-version: 0.16.1
|
|
1532
1581
|
vault-guard-version: 1.12.1
|
|
1533
1582
|
intent-guard-version: 1.10.1
|
|
1534
1583
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1698,7 +1747,12 @@ caused that; `continue-on-error` is the thing that let it happen, so the two
|
|
|
1698
1747
|
do not belong in the same recipe. Set a step `timeout-minutes` as well: the
|
|
1699
1748
|
Action already caps each gate's own subprocess at 120 seconds and reports one
|
|
1700
1749
|
that exceeds it as could-not-run, so the timeout is an outer bound around the
|
|
1701
|
-
whole run rather than the primary control.
|
|
1750
|
+
whole run rather than the primary control. Make it at least what the primary
|
|
1751
|
+
run needs plus 300 seconds (5 minutes), because the preview under the
|
|
1752
|
+
proposed rules can use up to that much on a pull request that changes a
|
|
1753
|
+
gate's `enabled` or `stage`; a step killed mid-preview has no verdict. Check
|
|
1754
|
+
out with `persist-credentials: false` so the gates never run with a token
|
|
1755
|
+
left in the checkout's git config.
|
|
1702
1756
|
|
|
1703
1757
|
A complete copy-paste job, rather than the one step above in isolation:
|
|
1704
1758
|
|
|
@@ -1718,12 +1772,14 @@ jobs:
|
|
|
1718
1772
|
# From 0.8.0 a shallow checkout on a pull-request run is
|
|
1719
1773
|
# could-not-run for the history gate.
|
|
1720
1774
|
fetch-depth: 0
|
|
1775
|
+
persist-credentials: false
|
|
1721
1776
|
- uses: actions/setup-node@v7
|
|
1722
1777
|
with:
|
|
1723
1778
|
node-version: '22.11.0'
|
|
1724
1779
|
- id: conductor
|
|
1725
|
-
|
|
1726
|
-
|
|
1780
|
+
# The primary run's need (here 5 minutes) plus 300 seconds.
|
|
1781
|
+
timeout-minutes: 10
|
|
1782
|
+
uses: vaultcompasshq/conductor@v0.14.0
|
|
1727
1783
|
with:
|
|
1728
1784
|
pr-comment: true
|
|
1729
1785
|
advisory: true
|
|
@@ -1859,7 +1915,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1859
1915
|
# the pull request runs before the action in this job: no install, build
|
|
1860
1916
|
# or test step here; those belong in a separate job. ...
|
|
1861
1917
|
- id: conductor
|
|
1862
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1918
|
+
uses: vaultcompasshq/conductor@v0.14.0
|
|
1863
1919
|
with:
|
|
1864
1920
|
output: conductor.sarif
|
|
1865
1921
|
pr-comment: true
|
|
@@ -1938,12 +1994,12 @@ per pull request.
|
|
|
1938
1994
|
|
|
1939
1995
|
```yaml
|
|
1940
1996
|
- id: conductor-package-a
|
|
1941
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1997
|
+
uses: vaultcompasshq/conductor@v0.14.0
|
|
1942
1998
|
with:
|
|
1943
1999
|
pr-comment: true
|
|
1944
2000
|
pr-comment-marker: 'package-a'
|
|
1945
2001
|
- id: conductor-package-b
|
|
1946
|
-
uses: vaultcompasshq/conductor@v0.
|
|
2002
|
+
uses: vaultcompasshq/conductor@v0.14.0
|
|
1947
2003
|
with:
|
|
1948
2004
|
pr-comment: true
|
|
1949
2005
|
pr-comment-marker: 'package-b'
|
|
@@ -2064,7 +2120,7 @@ an explicit pin is unaffected, which is how a stale pin can sit unnoticed
|
|
|
2064
2120
|
until the first pull request after the upgrade.
|
|
2065
2121
|
|
|
2066
2122
|
**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.
|
|
2123
|
+
example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.14.0`. To
|
|
2068
2124
|
find the SHA for a tag, run
|
|
2069
2125
|
`gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
|
|
2070
2126
|
the Releases page.
|
|
@@ -2087,6 +2143,9 @@ tag with no row here has an entry that does not state its defaults; read
|
|
|
2087
2143
|
|
|
2088
2144
|
| Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
|
|
2089
2145
|
| --- | --- | --- | --- |
|
|
2146
|
+
| v0.14.0 | package | 0.14.0 | none (gate defaults unchanged) |
|
|
2147
|
+
| v0.13.2 | package | 0.13.2 | none (gate defaults unchanged) |
|
|
2148
|
+
| v0.13.1 | action-only | 0.13.0 | dep-guard 0.16.1 (from 0.15.0) |
|
|
2090
2149
|
| v0.13.0 | package | 0.13.0 | none (gate defaults unchanged) |
|
|
2091
2150
|
| 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
2151
|
| 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) |
|
package/dist/cli.d.ts
CHANGED
|
@@ -1,9 +1,47 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import { Command } from 'commander';
|
|
3
|
+
import type { CliOverrides, Policy } from './policy.js';
|
|
4
|
+
import type { RunTrustBase } from './run.js';
|
|
3
5
|
/**
|
|
4
6
|
* Whether the text report is rendered for a terminal: only when it goes to
|
|
5
7
|
* stdout (no --output) and stdout is a TTY. A file, a pipe and the
|
|
6
8
|
* --text-report copy never are, so they stay byte for byte as before.
|
|
7
9
|
*/
|
|
8
10
|
export declare function rendersToTerminal(output: string | undefined, stdoutIsTTY: boolean | undefined): boolean;
|
|
11
|
+
/**
|
|
12
|
+
* The policy for one run, and where it came from.
|
|
13
|
+
*
|
|
14
|
+
* Two shapes rather than one, because a run that could not use its trust base
|
|
15
|
+
* is not a run with a different policy: it is a run with NO policy, and it
|
|
16
|
+
* has to report every enabled gate as could-not-run rather than fall back to
|
|
17
|
+
* the head's file.
|
|
18
|
+
*/
|
|
19
|
+
type PolicyForRun = {
|
|
20
|
+
kind: 'policy';
|
|
21
|
+
policy: Policy;
|
|
22
|
+
trustBase?: RunTrustBase;
|
|
23
|
+
/**
|
|
24
|
+
* The policy of the preview under the proposed rules, built here from
|
|
25
|
+
* the parsed head, which itself is never returned. Null without a trust
|
|
26
|
+
* base, when the head does not parse, and when no role's `enabled` or
|
|
27
|
+
* `stage` changed.
|
|
28
|
+
*/
|
|
29
|
+
previewPolicy: Policy | null;
|
|
30
|
+
}
|
|
31
|
+
/** The trust base could not be judged against. `inventory` only names gates. */
|
|
32
|
+
| {
|
|
33
|
+
kind: 'refused';
|
|
34
|
+
ref: string;
|
|
35
|
+
detail: string;
|
|
36
|
+
inventory: Policy;
|
|
37
|
+
notGiven?: boolean;
|
|
38
|
+
};
|
|
39
|
+
/**
|
|
40
|
+
* Exported so a test can see that no preview policy is built unless one was
|
|
41
|
+
* asked for (`preview`): a run without --preview never reaches that code.
|
|
42
|
+
*/
|
|
43
|
+
export declare function policyForRun(root: string, trustBase: string | undefined, overrides: CliOverrides, githubBaseRef: string | undefined, githubActions: string | undefined,
|
|
44
|
+
/** Whether this run asked for the preview under the proposed rules. */
|
|
45
|
+
preview?: boolean): PolicyForRun;
|
|
9
46
|
export declare function buildProgram(): Command;
|
|
47
|
+
export {};
|
package/dist/cli.js
CHANGED
|
@@ -14,8 +14,9 @@ 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, versionSkewAnnotations, versionSkewSummaryLines, versionSkewWarnings, } from './output-text.js';
|
|
17
|
+
import { gateLogLines, jobLogSummary, previewLogLines, proposalLogLines, 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
|
+
import { diffPolicies, previewPolicy, previewRoles } from './policy-diff.js';
|
|
19
20
|
import { refusedTrustBase, runAll } from './run.js';
|
|
20
21
|
import { headTreeEqualsBase, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
|
|
21
22
|
const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
|
|
@@ -244,7 +245,13 @@ function inventoryFromHead(root, overrides) {
|
|
|
244
245
|
return { version: 1, gates: {}, report: { format: 'text' } };
|
|
245
246
|
}
|
|
246
247
|
}
|
|
247
|
-
|
|
248
|
+
/**
|
|
249
|
+
* Exported so a test can see that no preview policy is built unless one was
|
|
250
|
+
* asked for (`preview`): a run without --preview never reaches that code.
|
|
251
|
+
*/
|
|
252
|
+
export function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions,
|
|
253
|
+
/** Whether this run asked for the preview under the proposed rules. */
|
|
254
|
+
preview = false) {
|
|
248
255
|
if (trustBase === undefined) {
|
|
249
256
|
// A PULL-REQUEST JOB WITH NO TRUST BASE would take its rules from the
|
|
250
257
|
// tree being judged. In Actions (GITHUB_ACTIONS and GITHUB_BASE_REF both
|
|
@@ -269,7 +276,11 @@ function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions)
|
|
|
269
276
|
process.stderr.write(`conductor: ${why} Outside GitHub Actions the run goes on with the working tree policy; ` +
|
|
270
277
|
'in Actions it is refused. Pass --trust-base for pull-request mode.\n');
|
|
271
278
|
}
|
|
272
|
-
return {
|
|
279
|
+
return {
|
|
280
|
+
kind: 'policy',
|
|
281
|
+
policy: applyCliOverrides(loadPolicy(root), overrides),
|
|
282
|
+
previewPolicy: null,
|
|
283
|
+
};
|
|
273
284
|
}
|
|
274
285
|
// DEFENCE IN DEPTH, ISSUE #58. action.yml's validate step already refuses
|
|
275
286
|
// an explicit trust-base input outright on a pull_request event; this is
|
|
@@ -351,15 +362,42 @@ function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions)
|
|
|
351
362
|
inventory: inventoryFromHead(root, overrides),
|
|
352
363
|
};
|
|
353
364
|
}
|
|
365
|
+
// Parsed once, before applyCliOverrides, so a --gate override never shows up
|
|
366
|
+
// as a policy change. The parsed head is never handed to a run: the
|
|
367
|
+
// comparison reads it, and the preview policy below takes only enabled,
|
|
368
|
+
// stage and enforce from it.
|
|
369
|
+
const baseParsed = parsePolicy(baseText, `${trustBase}:${POLICY_FILE_NAME}`);
|
|
370
|
+
const policyChanged = headRead.kind === 'error' ? true : policyDiffers(baseText, headText);
|
|
371
|
+
let headPolicy = null;
|
|
372
|
+
if (headText !== null) {
|
|
373
|
+
try {
|
|
374
|
+
headPolicy = parsePolicy(headText, `HEAD:${POLICY_FILE_NAME}`);
|
|
375
|
+
}
|
|
376
|
+
catch (error) {
|
|
377
|
+
if (!(error instanceof PolicyError))
|
|
378
|
+
throw error;
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
// The preview under the proposed rules: only the roles whose enabled or
|
|
382
|
+
// stage the head changes, and only enabled, stage and enforce from the
|
|
383
|
+
// head (previewPolicy). A head that does not parse gets none (spec 5.2,
|
|
384
|
+
// finding 8). The same --gate overrides, restricted to the roles the
|
|
385
|
+
// preview holds: a --gate role it does not hold leaves its roles excluded.
|
|
386
|
+
// Built only when the run asked for a preview, so nothing here can fail a
|
|
387
|
+
// run that did not.
|
|
388
|
+
const roles = !preview || headPolicy === null ? [] : previewRoles(diffPolicies(baseParsed, headPolicy));
|
|
389
|
+
const proposed = headPolicy === null || roles.length === 0 ? null : previewPolicy(baseParsed, headPolicy, roles);
|
|
354
390
|
return {
|
|
355
391
|
kind: 'policy',
|
|
356
|
-
policy: applyCliOverrides(
|
|
392
|
+
policy: applyCliOverrides(baseParsed, overrides),
|
|
393
|
+
previewPolicy: proposed === null ? null : previewWithOverrides(proposed, overrides),
|
|
357
394
|
trustBase: {
|
|
358
395
|
ref: trustBase,
|
|
359
396
|
// A head file git could not read is reported as a change, the
|
|
360
397
|
// fail-closed direction: it is never taken to match the base.
|
|
361
|
-
policyChanged
|
|
398
|
+
policyChanged,
|
|
362
399
|
refusal: null,
|
|
400
|
+
...(policyChanged ? { policyChanges: diffPolicies(baseParsed, headPolicy) } : {}),
|
|
363
401
|
// Computed AFTER refuseTrustBaseRef has already returned null, on the
|
|
364
402
|
// one shape that check accepts despite an identical tree: a merge
|
|
365
403
|
// commit whose first parent is this ref (issue #69). runAll reads this
|
|
@@ -369,6 +407,27 @@ function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions)
|
|
|
369
407
|
},
|
|
370
408
|
};
|
|
371
409
|
}
|
|
410
|
+
/**
|
|
411
|
+
* The --gate overrides on the preview policy. Restricted to the roles it
|
|
412
|
+
* holds, so a --gate role it does not hold leaves its roles excluded rather
|
|
413
|
+
* than throwing. And a role the head switched off stays off: applyCliOverrides
|
|
414
|
+
* turns a named role on, and the preview of a role switched off is not a run
|
|
415
|
+
* of it, so runPreview lists it as disabled.
|
|
416
|
+
*/
|
|
417
|
+
function previewWithOverrides(preview, overrides) {
|
|
418
|
+
if (overrides.gates === undefined) {
|
|
419
|
+
return preview;
|
|
420
|
+
}
|
|
421
|
+
const applied = applyCliOverrides(preview, {
|
|
422
|
+
...overrides,
|
|
423
|
+
gates: overrides.gates.filter((role) => preview.gates[role] !== undefined),
|
|
424
|
+
});
|
|
425
|
+
const gates = {};
|
|
426
|
+
for (const [role, gate] of Object.entries(applied.gates)) {
|
|
427
|
+
gates[role] = preview.gates[role]?.enabled === false ? { ...gate, enabled: false, excludedByCli: false } : gate;
|
|
428
|
+
}
|
|
429
|
+
return { ...applied, gates };
|
|
430
|
+
}
|
|
372
431
|
/**
|
|
373
432
|
* On a run with a trust base: removes every PATH entry that resolves against
|
|
374
433
|
* the working directory, for this process and for every child it starts,
|
|
@@ -569,6 +628,7 @@ export function buildProgram() {
|
|
|
569
628
|
.command('run')
|
|
570
629
|
.description('Run every enabled gate and print one combined report.')
|
|
571
630
|
.option('--staged', 'gate the git index against HEAD, the way the pre-commit hook does')
|
|
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.')
|
|
572
632
|
.option('--format <format>', 'output format: text or sarif')
|
|
573
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.`)
|
|
574
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 branch (refs/conductor/trust-base, else refs/remotes/origin/<GITHUB_BASE_REF>, as a commit id) when GITHUB_BASE_REF is set.')
|
|
@@ -613,7 +673,7 @@ export function buildProgram() {
|
|
|
613
673
|
: { gates: parseRoles(options.gate) }),
|
|
614
674
|
};
|
|
615
675
|
const stage = parseStage(options.stage);
|
|
616
|
-
const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF, process.env.GITHUB_ACTIONS);
|
|
676
|
+
const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF, process.env.GITHUB_ACTIONS, options.preview === true && options.staged !== true);
|
|
617
677
|
const policy = source.kind === 'policy' ? source.policy : source.inventory;
|
|
618
678
|
const format = parseFormat(options.format ?? policy.report.format);
|
|
619
679
|
// BEFORE ANY GATE RUNS. With --format text the text report already is
|
|
@@ -638,6 +698,15 @@ export function buildProgram() {
|
|
|
638
698
|
...(options.base === undefined ? {} : { base: options.base }),
|
|
639
699
|
...(options.spec === undefined ? {} : { spec: options.spec }),
|
|
640
700
|
...(source.trustBase === undefined ? {} : { trustBase: source.trustBase }),
|
|
701
|
+
// Only on request, never on --staged, and only with a trust
|
|
702
|
+
// base and a preview policy: a head that parsed and changed
|
|
703
|
+
// at least one role's enabled or stage.
|
|
704
|
+
...(options.preview === true &&
|
|
705
|
+
options.staged !== true &&
|
|
706
|
+
source.trustBase !== undefined &&
|
|
707
|
+
source.previewPolicy !== null
|
|
708
|
+
? { preview: { policy: source.previewPolicy } }
|
|
709
|
+
: {}),
|
|
641
710
|
});
|
|
642
711
|
const advisory = Boolean(options.advisory);
|
|
643
712
|
// SARIF carries no verdict line, so --advisory has nothing to say
|
|
@@ -703,6 +772,8 @@ export function buildProgram() {
|
|
|
703
772
|
// for an unwritable file.
|
|
704
773
|
const logLines = [
|
|
705
774
|
...gateLogLines(result, process.stderr.isTTY === true ? { terminal: true } : {}),
|
|
775
|
+
...proposalLogLines(result),
|
|
776
|
+
...previewLogLines(result),
|
|
706
777
|
...versionSkewWarnings(result),
|
|
707
778
|
];
|
|
708
779
|
if (logLines.length > 0) {
|
package/dist/gate-runner.d.ts
CHANGED
|
@@ -87,8 +87,12 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
|
|
|
87
87
|
* run whose stderr carries no package count (a lowered verbosity).
|
|
88
88
|
*/
|
|
89
89
|
| 'lockfile-emptied-unverified';
|
|
90
|
-
/**
|
|
91
|
-
|
|
90
|
+
/**
|
|
91
|
+
* Where a gate's time limit came from: the test hook, the policy, the product
|
|
92
|
+
* default, or, in the preview under the proposed rules, what was left of the
|
|
93
|
+
* preview's own budget when that was the smaller limit.
|
|
94
|
+
*/
|
|
95
|
+
export type TimeLimitSource = 'override' | 'policy' | 'default' | 'preview-budget';
|
|
92
96
|
export interface TimeLimit {
|
|
93
97
|
ms: number;
|
|
94
98
|
source: TimeLimitSource;
|
|
@@ -285,6 +289,12 @@ export interface GateTrustBase {
|
|
|
285
289
|
/** The control-input changes this gate reported as proposed. */
|
|
286
290
|
proposals: string[];
|
|
287
291
|
}
|
|
292
|
+
/**
|
|
293
|
+
* Why dep-guard and vault-guard are not handed `--trust-base` in the preview
|
|
294
|
+
* under the proposed rules: the preview shows what the head's rules would do,
|
|
295
|
+
* and their own control files are part of those rules.
|
|
296
|
+
*/
|
|
297
|
+
export declare const PREVIEW_WITHHELD = "preview under the proposed rules: this gate read its own control files from the head";
|
|
288
298
|
/**
|
|
289
299
|
* Whether this gate can be handed `--trust-base`, and why not when it cannot.
|
|
290
300
|
*
|
|
@@ -299,7 +309,14 @@ export interface GateTrustBase {
|
|
|
299
309
|
* was working a moment ago would report could-not-run. So the flag goes only
|
|
300
310
|
* where `--project` is the repository itself.
|
|
301
311
|
*/
|
|
302
|
-
export declare function decideTrustBase(gate: GatePolicy, intent: IntentPreparation | undefined, trustBase: string | undefined, productVersion: string | null
|
|
312
|
+
export declare function decideTrustBase(gate: GatePolicy, intent: IntentPreparation | undefined, trustBase: string | undefined, productVersion: string | null,
|
|
313
|
+
/**
|
|
314
|
+
* The preview under the proposed rules. dep-guard and vault-guard then read
|
|
315
|
+
* their own control files from the head, so the flag is withheld from them;
|
|
316
|
+
* the trust base itself stays set on the run, and every other product is
|
|
317
|
+
* decided exactly as without it.
|
|
318
|
+
*/
|
|
319
|
+
preview?: boolean): GateTrustBase | undefined;
|
|
303
320
|
export interface GateOutcome {
|
|
304
321
|
role: GateRole;
|
|
305
322
|
product: Product;
|
|
@@ -441,7 +458,34 @@ export interface RunGateOptions {
|
|
|
441
458
|
* inject one so they can see that nothing is left behind.
|
|
442
459
|
*/
|
|
443
460
|
tempRoot?: string;
|
|
461
|
+
/**
|
|
462
|
+
* Set only in the preview under the proposed rules. Every spawn of this
|
|
463
|
+
* gate then takes its timeout, kill signal and environment from
|
|
464
|
+
* `previewSpawnOptions`, and two refusals run before any spawn.
|
|
465
|
+
*/
|
|
466
|
+
preview?: PreviewSpawn;
|
|
467
|
+
}
|
|
468
|
+
/** The preview's hard deadline, its clock, and its private cache directory. */
|
|
469
|
+
export interface PreviewSpawn {
|
|
470
|
+
/** In the clock's own units (milliseconds): the whole preview ends here. */
|
|
471
|
+
deadline: number;
|
|
472
|
+
clock: () => number;
|
|
473
|
+
/** XDG_CACHE_HOME for every preview spawn, removed when the preview ends. */
|
|
474
|
+
cacheDir: string;
|
|
444
475
|
}
|
|
476
|
+
/** The smaller of a spawn's own limit and what is left of the preview budget, never negative. */
|
|
477
|
+
export declare function previewSpawnTimeout(limitMs: number, preview: PreviewSpawn): number;
|
|
478
|
+
/**
|
|
479
|
+
* The spawn options of every preview spawn: the timeout above, SIGKILL, so a
|
|
480
|
+
* child that traps SIGTERM cannot outlive the budget, and the spawn's own
|
|
481
|
+
* environment with XDG_CACHE_HOME pointed at the preview's private cache, so
|
|
482
|
+
* nothing the head's rules fetched persists on a shared runner.
|
|
483
|
+
*/
|
|
484
|
+
export declare function previewSpawnOptions(limitMs: number, preview: PreviewSpawn, env: NodeJS.ProcessEnv): {
|
|
485
|
+
timeout: number;
|
|
486
|
+
killSignal: 'SIGKILL';
|
|
487
|
+
env: NodeJS.ProcessEnv;
|
|
488
|
+
};
|
|
445
489
|
/**
|
|
446
490
|
* A gate that never got as far as being spawned.
|
|
447
491
|
*
|
|
@@ -554,7 +598,45 @@ external?: ExternalArgs,
|
|
|
554
598
|
* For the intent gate on a prepared run: hand it this base with its own
|
|
555
599
|
* `--base` in place of `--paths`. Decided by `intentChangeChannel`.
|
|
556
600
|
*/
|
|
557
|
-
intentBase?: string
|
|
601
|
+
intentBase?: string,
|
|
602
|
+
/**
|
|
603
|
+
* dep-guard's `--base` when `trustBase` is withheld from it in the preview
|
|
604
|
+
* under the proposed rules: the change is still measured against the base
|
|
605
|
+
* ref, only the rules are the head's. Ignored when `trustBase` is set, and
|
|
606
|
+
* by every other product.
|
|
607
|
+
*/
|
|
608
|
+
changeBase?: string,
|
|
609
|
+
/**
|
|
610
|
+
* True for a spawn of the preview under the proposed rules. osv-scanner
|
|
611
|
+
* then gets `--no-call-analysis=all` appended after the base's own options,
|
|
612
|
+
* whatever they say: call analysis builds the project it scans, which in
|
|
613
|
+
* the preview is the head's code, and osv-scanner applies its disables
|
|
614
|
+
* after its enables, so the appended flag wins.
|
|
615
|
+
*/
|
|
616
|
+
preview?: boolean): string[];
|
|
617
|
+
/**
|
|
618
|
+
* The expected-version decision for the intent gate, made BEFORE its
|
|
619
|
+
* preparation (residual 3, 2026-10-20).
|
|
620
|
+
*
|
|
621
|
+
* The preparation spawns the resolved binary for import-spec and freeze, and
|
|
622
|
+
* a failed or timed-out preparation ends the gate there, so without this the
|
|
623
|
+
* version check in runGate was never reached: an off-pin build whose
|
|
624
|
+
* preparation failed on a run with no trust base and `enforce: false` read
|
|
625
|
+
* preparation-failed, not enforced, exit 0, where runGate would have said
|
|
626
|
+
* version-skew, exit 2. Here the same probe and the same builder as runGate's
|
|
627
|
+
* decide first, and only the probe is spawned.
|
|
628
|
+
*
|
|
629
|
+
* Null when the version is the expected one: the preparation and runGate then
|
|
630
|
+
* go on as before, and runGate probes again (one cheap spawn) and reaches the
|
|
631
|
+
* same answer. The caller only calls this when an expectation is set; a run
|
|
632
|
+
* without one never reaches it, and nothing about it changes.
|
|
633
|
+
*/
|
|
634
|
+
export declare function expectedVersionBeforePreparation(gate: GatePolicy, binary: ResolvedBinary, options: {
|
|
635
|
+
repoRoot: string;
|
|
636
|
+
expectedVersion: string;
|
|
637
|
+
timeoutMs?: number;
|
|
638
|
+
trustBase?: string;
|
|
639
|
+
}): GateOutcome | null;
|
|
558
640
|
/**
|
|
559
641
|
* Runs one gate. TOTAL: this never throws.
|
|
560
642
|
*
|