@vaultcompass/conductor 0.2.4 → 0.4.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 CHANGED
@@ -56,6 +56,14 @@ become the annoying part:
56
56
  npm install -g @vaultcompass/conductor
57
57
  ```
58
58
 
59
+ **Globally, and that is the guidance for CI too.** A devDependency is fine
60
+ beside it for your own pre-commit hook, and nothing about a local run changed.
61
+ It is not what gates your pull requests: on a pull-request run the umbrella
62
+ never looks in `node_modules/.bin` at all, because what is installed there is
63
+ chosen by the head's own manifest and lockfile. The Action installs all four
64
+ packages itself, globally, at versions pinned in your workflow file. See "The
65
+ pull-request trust boundary" and "The Action" below.
66
+
59
67
  From the repository root, look before you write:
60
68
 
61
69
  ```
@@ -248,6 +256,12 @@ proceeds normally without mentioning them.
248
256
  - `--base <ref>` measures the intent gate against what this branch changed
249
257
  since `<ref>`, rather than against the index. See "Intent at a pull
250
258
  request" below.
259
+ - `--trust-base <ref>` reads the **rules** from `<ref>` instead of from the
260
+ tree being judged: this repository's own `.guardrails.yaml`, and every
261
+ control input of the gates that support it. See "The pull-request trust
262
+ boundary" below. `--base` and `--trust-base` are independent and a
263
+ pull-request run passes both: `--base` decides which paths are judged,
264
+ `--trust-base` decides what they are judged by.
251
265
  - `--spec <path>` names the spec the intent gate imports its contract from.
252
266
  - `--output <path>` writes the report to a file instead of to stdout, for a
253
267
  CI step that uploads it. One line still goes to stdout, because a job whose
@@ -270,6 +284,149 @@ proceeds normally without mentioning them.
270
284
  stdout, which is what a rejected config file looks like from two of the
271
285
  three.
272
286
 
287
+ ## The pull-request trust boundary
288
+
289
+ Every gate reads its own rules out of the repository it is judging. On a pull
290
+ request the author controls that repository, so without this a pull request
291
+ could turn a gate off in the same commit that carries the thing the gate
292
+ exists to catch, and the report would say the run was clean. For the umbrella
293
+ the sharpest version is `command:`, which names a program to run: a pull
294
+ request could point a gate at a script it added in the same commit.
295
+
296
+ **On a pull-request run the rules come from the base branch.** With
297
+ `--trust-base <ref>` the umbrella reads `.guardrails.yaml` from that ref with
298
+ `git show` and judges the head tree against it. A `.guardrails.yaml` in the
299
+ pull request never takes effect for that run, `command:` and `args:`
300
+ included, so **a pull request cannot change the rules it is judged by, and
301
+ cannot choose the program that judges it, as long as that program is
302
+ self-contained** (see the directory rule below). The same ref is passed
303
+ down to every gate that supports it, so their contracts, configs and
304
+ baselines come from the base branch too.
305
+
306
+ **The program is checked as well as the rules.** Reading the rules from the
307
+ base ref is worth nothing if the pull request supplies the binary that
308
+ applies them, and without this it could, two ways that both look ordinary in
309
+ a diff: a base `command:` pointing at a path inside the repository, where the
310
+ head replaces the file behind the approved path; and no `command:` at all,
311
+ where a head-committed `node_modules/.bin/<gate>` shadows the real gate,
312
+ because resolution prefers the repository's own copy over PATH so that a
313
+ project pin beats a global install.
314
+
315
+ **On a pull-request run `node_modules/.bin` is not consulted at all.** That
316
+ second shape is closed one step earlier than the first, and this is why: what
317
+ is installed there is chosen by the head's own manifest and lockfile, so it is
318
+ never approved by any ref, and a repository whose gates are devDependencies
319
+ would otherwise meet the program refusal on every ordinary pull request. So
320
+ that location is simply not searched when a trust base is set. PATH and an
321
+ absolute `command:` remain, and both still go through the program check below.
322
+ The skip is never silent: one line in the full report and one
323
+ `conductor/node-modules-skipped` note in the SARIF log name each gate and the
324
+ copy that was not taken, and a gate with nothing on PATH either is
325
+ could-not-run with `npm install -g` and the Action's version input named as
326
+ the remedy. **Outside pull-request mode nothing changes**: your own checkout
327
+ and your pre-commit hook still run the pin, which is what `pnpm exec` does in
328
+ the same repository.
329
+
330
+ **The versions that judge a pull request are pinned in the workflow file**,
331
+ which on a `pull_request` event is read from the base branch. That is the
332
+ protected side, and it is the point: the pull request can change its own
333
+ lockfile, and cannot change the pin that decides which conductor and which
334
+ gates run over it.
335
+
336
+ So on a pull-request run a gate's program must be **outside the working tree**
337
+ (on PATH, or an absolute `command:` elsewhere on the machine), or else meet
338
+ **both** of these:
339
+
340
+ - it is a **tracked regular file whose contents are identical** at the base
341
+ ref and at the head commit; and
342
+ - **the tree object id of its containing directory is identical** at those
343
+ two refs, which is to say the pull request changed nothing anywhere in that
344
+ directory's subtree.
345
+
346
+ Both are compared with `git ls-tree` on both refs and never read from the
347
+ working tree. The second is not belt and braces. A vendored gate is rarely
348
+ one file: `vendor/vault-guard` execs `vendor/impl.sh`, and a pull request
349
+ that leaves the wrapper byte for byte alone and rewrites the helper beside it
350
+ passes a per-file check while running its own code. Comparing the directory
351
+ covers every file under it at once, without this tool having to know what a
352
+ wrapper calls.
353
+
354
+ **What is and is not vetted**, exactly: the program file and everything in
355
+ its directory subtree. Anything the program reaches **outside** that
356
+ directory is not vetted at all, so an in-repo gate must be **self-contained
357
+ within its own directory**. A program at the repository ROOT is refused, and
358
+ the message says to give it a directory: at the root the containing directory
359
+ is the whole repository, so the rule would mean "no pull request may change
360
+ anything".
361
+
362
+ A symlink inside the repository is refused on **its own entry**, before its
363
+ target is considered: it is either untracked, or its tree entry is a link
364
+ rather than a regular file, and either refuses. (A symlink whose own path is
365
+ outside the tree but which points into it has its target vetted; that is the
366
+ case following the link exists for.)
367
+
368
+ Anything else is could-not-run for that gate, naming the path, and it reaches
369
+ the exit code even where the policy sets `enforce: false`, because the gate
370
+ produced no findings to un-enforce: the umbrella declined to run a program
371
+ the pull request chose.
372
+
373
+ Nothing under `node_modules` is ever base-approved, which is why the rule
374
+ above does not look there at all. Were it to look, the answer would always be
375
+ the same refusal: what is there is chosen by the head's own manifest and
376
+ lockfile and installed by a step that runs before the gates, so git has no
377
+ record of those bytes at either ref. A pull request that edits its lockfile to
378
+ pull a different build of a gate has chosen its own judge just as surely as
379
+ one that commits a stub. **Vendoring a gate still works**, on those
380
+ terms: put it in its own directory, keep everything it needs inside that
381
+ directory, and leave the whole directory alone in a pull request the gate is
382
+ meant to judge. Changing it is not forbidden, it just has to land on the base
383
+ branch first, like any other rule change.
384
+
385
+ **A change to the rules is not refused, it is proposed.** Rules legitimately
386
+ change, and a gate that blocked every such pull request would train people to
387
+ bypass it. So a policy file that differs from the base ref's is reported as
388
+ one line, `policy changed in this pull request`, the run continues under the
389
+ base ref's rules, and the change takes effect **after merge**, on the first
390
+ run whose base branch carries it. The gates' own proposals are summed with it
391
+ into one sentence, `N control change(s) proposed in this pull request`, on the
392
+ one-line summary and on the verdict, with a line each under `--verbose` and a
393
+ `conductor/control-change-proposed` notification each in the SARIF log. A
394
+ reflow, a re-quote or an edited comment is not a proposal: the two files are
395
+ compared as parsed documents.
396
+
397
+ **It fails closed.** A `--trust-base` that does not resolve is not a reason to
398
+ fall back to the pull request's own file, because that fallback is the hole:
399
+ the run exits 2 and the report **leads with the refusal**, naming the ref and
400
+ the remedy, whether or not it can name any gate. That last part matters: with
401
+ no base ref there is no base policy, so the only list of gates available is
402
+ the head's, and a head that switches every gate off leaves it empty. So is a
403
+ base ref that resolves to the head commit, or to a different commit carrying
404
+ the head's tree, both of which would put the rules back inside the tree being
405
+ judged while still reporting pull-request mode as on. Pass the base
406
+ **branch**, never a SHA: on a `pull_request` event `github.sha` is the merge
407
+ commit, which is HEAD. If the base branch has no `.guardrails.yaml` at all,
408
+ the run has no rules and exits 2 rather than using the pull request's; the
409
+ file the pull request adds decides what runs once it is on the base branch.
410
+
411
+ **Which gates are covered.** All three: dep-guard from **0.6.0**,
412
+ intent-guard from **1.4.0**, vault-guard from **1.7.0**.
413
+
414
+ The umbrella asks each gate its version and passes the flag only to a build
415
+ that understands it, so an older gate is not handed a flag it would reject. A
416
+ gate that was not put into pull-request mode read its own rules out of the
417
+ tree being judged, which is the thing this exists to prevent, so it is never
418
+ silent: it gets a line in the report, a clause on the clean one-line summary,
419
+ and a `conductor/trust-base-not-passed` notification in the SARIF log. For a
420
+ gate that IS in the table, a version that cannot be read at all is
421
+ could-not-run rather than a quiet downgrade: the umbrella cannot establish
422
+ that the gate would take its rules from the base ref, and running it anyway
423
+ would put it outside the boundary on exactly the runs where something is
424
+ already wrong.
425
+
426
+ Outside pull-request mode nothing changes. A pre-commit hook and a direct run
427
+ on your own checkout are already inside the trust boundary, and neither passes
428
+ the flag.
429
+
273
430
  ## Intent at a pull request
274
431
 
275
432
  The intent gate is the only one of the three with any ceremony: its native
@@ -362,14 +519,43 @@ no severity threshold of its own here either.
362
519
  `action.yml` at the root is a composite action that runs the gates at the
363
520
  `ci` stage and writes one SARIF log for the caller to upload.
364
521
 
365
- It **installs nothing**, on purpose. It runs the conductor your repository
366
- already depends on, so the version gating your pull requests is the one your
367
- lockfile pins rather than whatever the registry serves that morning; instead
368
- of installing, the action checks for `node_modules/.bin/conductor` and fails
369
- with a sentence saying to add it as a devDependency. `--base` is passed only when the
370
- `base-ref` input names one; left empty, the umbrella reads `GITHUB_BASE_REF`
371
- itself and treats an empty value as "not a pull request", which is what a
372
- push build wants.
522
+ It **installs all four packages itself**, and outside the workspace. Until
523
+ 0.4.0 it installed nothing and ran the `node_modules/.bin/conductor` your
524
+ repository already had, which put every program in the family inside the tree
525
+ under judgment: the install step runs the head's lockfile, so a pull request
526
+ could repoint any gate, or the umbrella itself, at a build it controls while
527
+ leaving the version number alone.
528
+
529
+ Now four inputs name exact versions, `conductor-version`,
530
+ `dep-guard-version`, `vault-guard-version` and `intent-guard-version`, each
531
+ defaulting to the version this release pins. A validate step refuses anything
532
+ that is not an exact version, a range and `latest` included: the version that
533
+ judges a pull request has to be a decision taken on the base branch rather
534
+ than one the registry takes on the morning of the run. An install step then
535
+ runs `npm install -g` under the runner temp, never into the workspace, and
536
+ prepends that bin directory to `PATH`, so the run step invokes `conductor` off
537
+ `PATH` and each gate resolves by name the same way. The install is
538
+ **unconditional**, on push and `pull_request` alike, so there is one code path
539
+ rather than one that matters and one that nobody exercises.
540
+
541
+ `--base` is passed only when the `base-ref` input names one; left empty, the
542
+ umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
543
+ pull request", which is what a push build wants.
544
+
545
+ On a `pull_request` event the action passes
546
+ **`--trust-base origin/$GITHUB_BASE_REF`** of its own accord, so the run takes
547
+ its configuration from the base branch and the pull request cannot change the
548
+ rules it is judged by; a change to the rules shows as a proposal line and
549
+ takes effect after merge. See "The pull-request trust boundary" above. On any
550
+ other event it passes nothing and behaviour is unchanged. The `trust-base`
551
+ input names the ref explicitly, for a platform where `GITHUB_BASE_REF` is not
552
+ set.
553
+
554
+ There is deliberately **no input that turns pull-request mode off**.
555
+ Base-ref judging is the floor rather than a knob, and on a `pull_request`
556
+ event the workflow file itself runs from the pull request's own ref, so an
557
+ opt-out here would be settable by the very pull request the mode exists to
558
+ judge: the knob and the thing it protects against would be the same file.
373
559
 
374
560
  ```yaml
375
561
  name: guardrails
@@ -384,19 +570,35 @@ jobs:
384
570
  steps:
385
571
  - uses: actions/checkout@v4
386
572
  with:
387
- # Required. Without it there is no merge base to diff against, and
388
- # the intent gate fails closed rather than checking an empty set.
573
+ # Required, for two reasons now. Without it there is no merge base
574
+ # to diff against, and the intent gate fails closed rather than
575
+ # checking an empty set. And the base ref itself has to be in the
576
+ # clone, because on a pull request the rules are read from it: a
577
+ # base ref that will not resolve is exit 2 for every enabled gate.
389
578
  fetch-depth: 0
390
579
  - uses: pnpm/action-setup@v4
391
580
  - uses: actions/setup-node@v4
392
581
  with:
393
582
  node-version: 22
394
583
  cache: pnpm
584
+ # Your own dependencies. The gates are NOT among the things this has to
585
+ # install: the action installs those itself, globally, at the versions
586
+ # pinned below.
395
587
  - run: pnpm install --frozen-lockfile
396
588
  - id: conductor
397
589
  uses: ./
398
590
  with:
399
591
  output: conductor.sarif
592
+ # Exact versions, never a range and never "latest". On a
593
+ # pull_request event this file is read from the base branch, so
594
+ # these four lines are the protected side: a pull request can change
595
+ # its own lockfile and cannot change which programs judge it.
596
+ # Bump them like any other pin, in a pull request, on the base
597
+ # branch first.
598
+ conductor-version: 0.4.0
599
+ dep-guard-version: 0.6.0
600
+ vault-guard-version: 1.7.0
601
+ intent-guard-version: 1.4.0
400
602
  - uses: github/codeql-action/upload-sarif@v3
401
603
  # Always: the log is most worth having on the run that failed.
402
604
  if: always()
@@ -435,19 +637,41 @@ writes SARIF and nothing else, so the job costs roughly twice the gate time;
435
637
  env:
436
638
  GH_TOKEN: ${{ github.token }}
437
639
  PR: ${{ github.event.pull_request.number }}
640
+ # The same derivation the Action makes for its own --trust-base.
641
+ # github.base_ref is a BRANCH NAME and is empty outside a pull
642
+ # request, so an empty value has to mean "not a pull request":
643
+ # passing --trust-base unconditionally would hand a push build the
644
+ # literal ref "origin/" and fail it closed.
645
+ BASE: ${{ github.base_ref }}
438
646
  # || true: a blocking finding is a non-zero exit, and that verdict
439
647
  # belongs to the gates step rather than to this one.
440
648
  run: |
441
- node_modules/.bin/conductor run --stage ci --format text --verbose --output conductor.txt || true
649
+ ARGS=(run --stage ci --format text --verbose --output conductor.txt)
650
+ if [ -n "$BASE" ]; then
651
+ ARGS+=(--trust-base "origin/$BASE")
652
+ fi
653
+ conductor "${ARGS[@]}" || true
442
654
  gh pr comment "$PR" --body-file conductor.txt
443
655
  ```
444
656
 
657
+ `conductor` and not `node_modules/.bin/conductor`: the gates step put the
658
+ installed one on `PATH`. Reaching into `node_modules` here would report a
659
+ different program's verdict from the one in the uploaded log.
660
+
661
+ `--trust-base` for the same reason, and the two together are what make this
662
+ the run the uploaded log is about: same binary AND same trust base. Without
663
+ it this second run reads the head's own policy file, consults
664
+ `node_modules/.bin` like any local run, and never asks where a gate's program
665
+ came from, so a pull request that plants one gets a clean comment beside a
666
+ SARIF log that refused it.
667
+
445
668
  **Mirror whatever you gave the Action**, or the two runs can report different
446
669
  contracts. The step above matches the example, which passes neither
447
- `base-ref` nor `spec`, so both runs read `GITHUB_BASE_REF` and the `Spec:`
448
- line out of the job environment themselves and land on the same contract. If
449
- you set either input on the gates step, pass the same values here as `--base`
450
- and `--spec`; if you do not, the comment is a report of a contract source the
670
+ `base-ref`, `trust-base` nor `spec`, so both runs read `GITHUB_BASE_REF` and
671
+ the `Spec:` line out of the job environment themselves and land on the same
672
+ contract and the same ref. If you set any of those inputs on the gates step,
673
+ pass the same values here as `--base`, `--trust-base` and `--spec`; if you do
674
+ not, the comment is a report of a contract source, or of a boundary, the
451
675
  uploaded log never used.
452
676
 
453
677
  **On a pull request from a fork the token is read-only**, so `gh pr comment`
package/dist/cli.js CHANGED
@@ -14,8 +14,9 @@ import { EXIT_COULD_NOT_RUN } from './exit-codes.js';
14
14
  import { applyInit, planInit, renderInitHuman, renderRevertHuman, revertInit, } from './init.js';
15
15
  import { renderSarif } from './output-sarif.js';
16
16
  import { renderText } from './output-text.js';
17
- import { GATE_ROLES, GATE_STAGES, PolicyError, applyCliOverrides, loadPolicy } from './policy.js';
18
- import { runAll } from './run.js';
17
+ import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
18
+ import { refusedTrustBase, runAll } from './run.js';
19
+ import { policyDiffers, readPolicyAtRef, refuseTrustBaseRef } from './trust-base.js';
19
20
  const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
20
21
  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
21
22
  /**
@@ -64,6 +65,74 @@ function repoRoot(cwd) {
64
65
  throw new Error(`git could not be run to find the repository root: ${err.message}`);
65
66
  }
66
67
  }
68
+ /**
69
+ * Reads the policy for one run, from the base ref in pull-request mode.
70
+ *
71
+ * THE HEAD'S POLICY FILE IS NEVER PARSED INTO A RUN IN PULL-REQUEST MODE, and
72
+ * that is the whole of the fix. A pull request that rewrites `.guardrails.yaml`
73
+ * to point a gate's `command:` at a script it added, or to switch off the gate
74
+ * that would have caught what else is in the commit, gets the base ref's
75
+ * policy and a line saying its own was proposed.
76
+ *
77
+ * The head's file is read for exactly two things, neither of which can change
78
+ * what runs: it is compared with the base's so the difference can be
79
+ * reported, and, when the trust base itself cannot be used, it names the
80
+ * gates the report says did not run.
81
+ */
82
+ function policyForRun(root, trustBase, overrides) {
83
+ if (trustBase === undefined) {
84
+ return { kind: 'policy', policy: applyCliOverrides(loadPolicy(root), overrides) };
85
+ }
86
+ const refusal = refuseTrustBaseRef(root, trustBase);
87
+ if (refusal !== null) {
88
+ // An inventory, and only an inventory: a list of gate NAMES for the
89
+ // report, taken from the one file available when the base ref cannot be
90
+ // read. It is head-controlled, so it can be SHORTER as well as longer
91
+ // than the base's -- every gate `enabled: false`, or a file that will not
92
+ // parse at all, leaves it empty -- and an earlier comment here claimed
93
+ // only the longer direction, which is how the empty case went unnoticed.
94
+ //
95
+ // Neither direction can weaken the verdict, and that is the property this
96
+ // rests on rather than on the inventory being right. refusedTrustBase
97
+ // enforces every gate it names and writes exit 2 itself, and the refusal
98
+ // is carried on the result so both renderers lead with it whether the
99
+ // inventory names three gates or none. A longer list makes the report
100
+ // longer; a shorter one makes it shorter; the verdict is the same
101
+ // sentence either way.
102
+ //
103
+ // An unreadable head file leaves the list empty rather than replacing the
104
+ // refusal with a policy error: the ref is what went wrong, and reporting
105
+ // the head's malformed file would send the reader to the wrong fix on a
106
+ // run that would have ignored that file anyway.
107
+ let inventory = { version: 1, gates: {}, report: { format: 'text' } };
108
+ try {
109
+ inventory = applyCliOverrides(loadPolicy(root), overrides);
110
+ }
111
+ catch {
112
+ inventory = { version: 1, gates: {}, report: { format: 'text' } };
113
+ }
114
+ return { kind: 'refused', ref: trustBase, detail: refusal, inventory };
115
+ }
116
+ const baseText = readPolicyAtRef(root, trustBase);
117
+ const headText = readPolicyAtRef(root, 'HEAD');
118
+ if (baseText === null) {
119
+ throw new PolicyError(`No ${POLICY_FILE_NAME} on "${trustBase}". On a pull-request run every rule comes from the ` +
120
+ 'base ref, so this run has no policy at all and nothing was checked. ' +
121
+ (headText === null
122
+ ? `Run "conductor init" on the base branch.`
123
+ : `The ${POLICY_FILE_NAME} in this pull request is a proposal: it decides what runs ` +
124
+ 'once it is on the base branch, and never on the pull request that adds it.'));
125
+ }
126
+ return {
127
+ kind: 'policy',
128
+ policy: applyCliOverrides(parsePolicy(baseText, `${trustBase}:${POLICY_FILE_NAME}`), overrides),
129
+ trustBase: {
130
+ ref: trustBase,
131
+ policyChanged: policyDiffers(baseText, headText),
132
+ refusal: null,
133
+ },
134
+ };
135
+ }
67
136
  function parseFormat(value) {
68
137
  if (value !== 'text' && value !== 'sarif') {
69
138
  throw new PolicyError(`--format must be "text" or "sarif", got "${value}".`);
@@ -171,6 +240,7 @@ export function buildProgram() {
171
240
  .option('--format <format>', 'output format: text or sarif')
172
241
  .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.`)
173
242
  .option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to origin/<GITHUB_BASE_REF> when it is set.')
243
+ .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 passes origin/<GITHUB_BASE_REF> on a pull_request event.')
174
244
  .option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
175
245
  .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')
176
246
  .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.')
@@ -183,22 +253,29 @@ export function buildProgram() {
183
253
  // and the catch below is what turns any of its three sentences into
184
254
  // one line on stderr and the could-not-run exit code.
185
255
  const root = repoRoot(cwd);
186
- const policy = applyCliOverrides(loadPolicy(root), {
256
+ const overrides = {
187
257
  ...(parseRoles(options.gate) === undefined
188
258
  ? {}
189
259
  : { gates: parseRoles(options.gate) }),
190
- });
191
- const format = parseFormat(options.format ?? policy.report.format);
260
+ };
192
261
  const stage = parseStage(options.stage);
193
- const result = runAll(policy, {
194
- repoRoot: root,
195
- staged: Boolean(options.staged),
196
- pathValue: process.env.PATH ?? '',
197
- env: process.env,
198
- ...(stage === undefined ? {} : { stage }),
199
- ...(options.base === undefined ? {} : { base: options.base }),
200
- ...(options.spec === undefined ? {} : { spec: options.spec }),
201
- });
262
+ const source = policyForRun(root, options.trustBase, overrides);
263
+ const policy = source.kind === 'policy' ? source.policy : source.inventory;
264
+ const format = parseFormat(options.format ?? policy.report.format);
265
+ const result = source.kind === 'refused'
266
+ ? refusedTrustBase(source.inventory, source.ref, source.detail, {
267
+ ...(stage === undefined ? {} : { stage }),
268
+ })
269
+ : runAll(source.policy, {
270
+ repoRoot: root,
271
+ staged: Boolean(options.staged),
272
+ pathValue: process.env.PATH ?? '',
273
+ env: process.env,
274
+ ...(stage === undefined ? {} : { stage }),
275
+ ...(options.base === undefined ? {} : { base: options.base }),
276
+ ...(options.spec === undefined ? {} : { spec: options.spec }),
277
+ ...(source.trustBase === undefined ? {} : { trustBase: source.trustBase }),
278
+ });
202
279
  const rendered = format === 'sarif'
203
280
  ? `${renderSarif(result, pkg.version)}\n`
204
281
  : renderText(result, { verbose: Boolean(options.verbose) });
@@ -95,6 +95,22 @@ export interface NormalizedGateOutput {
95
95
  run: RunSummary;
96
96
  /** Problems with the normalization itself, not with the scanned code. */
97
97
  diagnostics: Diagnostic[];
98
+ /**
99
+ * What the gate said about pull-request mode, when it was in it.
100
+ *
101
+ * NOT findings, and deliberately not folded into `run.details`. A proposed
102
+ * control change is a statement about the configuration this pull request
103
+ * would like to have, so it must never reach a severity, a fingerprint, a
104
+ * blocking count or an exit code; it is summed by the umbrella and printed
105
+ * as one sentence. `run.details` is rendered as loose scalars in the text
106
+ * report, which would scatter these across a line instead.
107
+ */
108
+ trustBase?: {
109
+ /** The ref that gate took its control inputs from, as it reported it. */
110
+ ref: string;
111
+ /** One line per control input the head proposes to change. */
112
+ proposals: string[];
113
+ };
98
114
  }
99
115
  export declare class NormalizeError extends Error {
100
116
  constructor(message: string);