@vaultcompass/conductor 0.3.0 → 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
  ```
@@ -304,6 +312,27 @@ where a head-committed `node_modules/.bin/<gate>` shadows the real gate,
304
312
  because resolution prefers the repository's own copy over PATH so that a
305
313
  project pin beats a global install.
306
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
+
307
336
  So on a pull-request run a gate's program must be **outside the working tree**
308
337
  (on PATH, or an absolute `command:` elsewhere on the machine), or else meet
309
338
  **both** of these:
@@ -341,12 +370,13 @@ the exit code even where the policy sets `enforce: false`, because the gate
341
370
  produced no findings to un-enforce: the umbrella declined to run a program
342
371
  the pull request chose.
343
372
 
344
- Nothing under `node_modules` is ever base-approved, and that is the right
345
- answer rather than a limitation: what is there is chosen by the head's own
346
- manifest and lockfile and installed by a step that runs before the gates, so
347
- git has no record of those bytes at either ref. A pull request that edits its
348
- lockfile to pull a different build of a gate has chosen its own judge just as
349
- surely as one that commits a stub. **Vendoring a gate still works**, on those
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
350
380
  terms: put it in its own directory, keep everything it needs inside that
351
381
  directory, and leave the whole directory alone in a pull request the gate is
352
382
  meant to judge. Changing it is not forbidden, it just has to land on the base
@@ -489,14 +519,28 @@ no severity threshold of its own here either.
489
519
  `action.yml` at the root is a composite action that runs the gates at the
490
520
  `ci` stage and writes one SARIF log for the caller to upload.
491
521
 
492
- It **installs nothing**, on purpose. It runs the conductor your repository
493
- already depends on, so the version gating your pull requests is the one your
494
- lockfile pins rather than whatever the registry serves that morning; instead
495
- of installing, the action checks for `node_modules/.bin/conductor` and fails
496
- with a sentence saying to add it as a devDependency. `--base` is passed only when the
497
- `base-ref` input names one; left empty, the umbrella reads `GITHUB_BASE_REF`
498
- itself and treats an empty value as "not a pull request", which is what a
499
- 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.
500
544
 
501
545
  On a `pull_request` event the action passes
502
546
  **`--trust-base origin/$GITHUB_BASE_REF`** of its own accord, so the run takes
@@ -537,11 +581,24 @@ jobs:
537
581
  with:
538
582
  node-version: 22
539
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.
540
587
  - run: pnpm install --frozen-lockfile
541
588
  - id: conductor
542
589
  uses: ./
543
590
  with:
544
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
545
602
  - uses: github/codeql-action/upload-sarif@v3
546
603
  # Always: the log is most worth having on the run that failed.
547
604
  if: always()
@@ -580,19 +637,41 @@ writes SARIF and nothing else, so the job costs roughly twice the gate time;
580
637
  env:
581
638
  GH_TOKEN: ${{ github.token }}
582
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 }}
583
646
  # || true: a blocking finding is a non-zero exit, and that verdict
584
647
  # belongs to the gates step rather than to this one.
585
648
  run: |
586
- 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
587
654
  gh pr comment "$PR" --body-file conductor.txt
588
655
  ```
589
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
+
590
668
  **Mirror whatever you gave the Action**, or the two runs can report different
591
669
  contracts. The step above matches the example, which passes neither
592
- `base-ref` nor `spec`, so both runs read `GITHUB_BASE_REF` and the `Spec:`
593
- line out of the job environment themselves and land on the same contract. If
594
- you set either input on the gates step, pass the same values here as `--base`
595
- 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
596
675
  uploaded log never used.
597
676
 
598
677
  **On a pull request from a fork the token is read-only**, so `gh pr comment`
@@ -141,6 +141,17 @@ export interface GateOutcome {
141
141
  * pull-request mode, and what it said was proposed.
142
142
  */
143
143
  trustBase?: GateTrustBase;
144
+ /**
145
+ * The `node_modules/.bin` candidate resolution did NOT try, repository
146
+ * relative, on a pull-request run where one was there.
147
+ *
148
+ * Absent outside pull-request mode, and absent inside it when there was
149
+ * nothing to skip: it is a claim that something was there and was declined,
150
+ * not a claim about the mode. Reported so an adopter whose gates are
151
+ * devDependencies learns why the gate came from somewhere else, or from
152
+ * nowhere. Repository-relative because it reaches a published log.
153
+ */
154
+ nodeModulesSkipped?: string;
144
155
  }
145
156
  export interface RunGateOptions {
146
157
  repoRoot: string;
@@ -178,6 +189,37 @@ export interface RunGateOptions {
178
189
  * would have to learn about.
179
190
  */
180
191
  export declare function preparationFailed(gate: GatePolicy, detail: string): GateOutcome;
192
+ /**
193
+ * EVERY program this binary would spawn, vetted against the trust base.
194
+ *
195
+ * Two files and not one. `program` is what the gate runs, and
196
+ * `versionProbe.command` can be a DIFFERENT file: for a per-command binary
197
+ * that ignores `--version`, resolution finds the version-safe sibling
198
+ * somewhere else entirely (`versionProbeFor`, src/resolve.ts:238-262). Vetting
199
+ * only the first left the probe free to spawn whatever the head put at the
200
+ * second, and a probe RUNS a program as thoroughly as a scan does.
201
+ *
202
+ * The first refusal wins and the rest is not consulted. The verdict is the
203
+ * same either way, and the sentence a reader has to act on should name one
204
+ * file rather than two.
205
+ */
206
+ export declare function refuseHeadControlledBinary(repoRoot: string, trustBase: string, binary: ResolvedBinary): string | null;
207
+ /**
208
+ * The outcome for a gate whose program the umbrella declined to run.
209
+ *
210
+ * ONE BUILDER, TWO CALLERS, and that is the point of it being here rather
211
+ * than written out at the return that needs it. `runGate` reaches this before
212
+ * it spawns anything; `runAll` reaches it earlier still, before the intent
213
+ * gate's preparation spawns the same program three times. A second copy of
214
+ * the shape would be a second chance to forget the override below.
215
+ *
216
+ * ENFORCED, whatever the policy says. `enforce: false` is a standing decision
217
+ * about what a gate's FINDINGS are worth, and this gate produced none: the
218
+ * umbrella refused to run a program the pull request chose. Letting an
219
+ * unenforced gate swallow that would let a pull request pick its own judge
220
+ * and keep the run green.
221
+ */
222
+ export declare function gateProgramRefused(gate: GatePolicy, trustBase: string, refusal: string, binary: ResolvedBinary): GateOutcome;
181
223
  /**
182
224
  * The arguments the umbrella adds, per product.
183
225
  *
@@ -20,7 +20,7 @@ import { NormalizeError } from './envelope.js';
20
20
  import { normalizeDepGuard, normalizeFailedGate, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
21
21
  import { renderOptionFlags } from './policy.js';
22
22
  import { atLeastVersion, refuseHeadControlledProgram } from './trust-base.js';
23
- import { ResolveError, candidateNames, resolveGateBinary } from './resolve.js';
23
+ import { ResolveError, candidateNames, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
24
24
  /**
25
25
  * The first version of each gate that understands `--trust-base`.
26
26
  *
@@ -142,6 +142,66 @@ const EMPTY_RUN = {
142
142
  diagnostics: [],
143
143
  details: {},
144
144
  };
145
+ /**
146
+ * EVERY program this binary would spawn, vetted against the trust base.
147
+ *
148
+ * Two files and not one. `program` is what the gate runs, and
149
+ * `versionProbe.command` can be a DIFFERENT file: for a per-command binary
150
+ * that ignores `--version`, resolution finds the version-safe sibling
151
+ * somewhere else entirely (`versionProbeFor`, src/resolve.ts:238-262). Vetting
152
+ * only the first left the probe free to spawn whatever the head put at the
153
+ * second, and a probe RUNS a program as thoroughly as a scan does.
154
+ *
155
+ * The first refusal wins and the rest is not consulted. The verdict is the
156
+ * same either way, and the sentence a reader has to act on should name one
157
+ * file rather than two.
158
+ */
159
+ export function refuseHeadControlledBinary(repoRoot, trustBase, binary) {
160
+ for (const program of [binary.program, binary.versionProbe?.command]) {
161
+ if (program === undefined) {
162
+ continue;
163
+ }
164
+ const refusal = refuseHeadControlledProgram(repoRoot, trustBase, program);
165
+ if (refusal !== null) {
166
+ return refusal;
167
+ }
168
+ }
169
+ return null;
170
+ }
171
+ /**
172
+ * The outcome for a gate whose program the umbrella declined to run.
173
+ *
174
+ * ONE BUILDER, TWO CALLERS, and that is the point of it being here rather
175
+ * than written out at the return that needs it. `runGate` reaches this before
176
+ * it spawns anything; `runAll` reaches it earlier still, before the intent
177
+ * gate's preparation spawns the same program three times. A second copy of
178
+ * the shape would be a second chance to forget the override below.
179
+ *
180
+ * ENFORCED, whatever the policy says. `enforce: false` is a standing decision
181
+ * about what a gate's FINDINGS are worth, and this gate produced none: the
182
+ * umbrella refused to run a program the pull request chose. Letting an
183
+ * unenforced gate swallow that would let a pull request pick its own judge
184
+ * and keep the run green.
185
+ */
186
+ export function gateProgramRefused(gate, trustBase, refusal, binary) {
187
+ return {
188
+ role: gate.role,
189
+ product: gate.product,
190
+ stage: gate.stage,
191
+ enforce: true,
192
+ productVersion: null,
193
+ argv: [],
194
+ binary,
195
+ exitCode: null,
196
+ durationMs: 0,
197
+ stderr: '',
198
+ trustBase: { ref: trustBase, withheld: null, refused: refusal, proposals: [] },
199
+ couldNotRun: { reason: 'gate-program-refused', detail: refusal },
200
+ findings: [normalizeFailedGate(gate.role, gate.product, refusal)],
201
+ run: EMPTY_RUN,
202
+ diagnostics: [],
203
+ };
204
+ }
145
205
  /**
146
206
  * The arguments the umbrella adds, per product.
147
207
  *
@@ -267,6 +327,31 @@ function messageOf(err) {
267
327
  }
268
328
  return String(err);
269
329
  }
330
+ /**
331
+ * The sentence a gate that resolved to nothing gets on a pull-request run.
332
+ *
333
+ * EMPTY OUTSIDE PULL-REQUEST MODE, because outside it nothing about
334
+ * resolution changed and the old message is still the whole story. Inside it
335
+ * the message would otherwise be actively misleading in the common case: an
336
+ * adopter with the gates as devDependencies is looking straight at a
337
+ * node_modules/.bin/<gate> while being told no binary was found.
338
+ *
339
+ * It names `npm install -g` and the Action's own input rather than "install
340
+ * it", because those are the two places the fix actually is: on a runner, the
341
+ * Action installs the gates itself at a version pinned in a workflow file that
342
+ * lives on the base branch, which is the protected side.
343
+ */
344
+ function missingGateRemedy(product, skipNodeModules, skipped) {
345
+ if (!skipNodeModules) {
346
+ return '';
347
+ }
348
+ return (' On a pull-request run node_modules/.bin is not consulted at all: what is installed there ' +
349
+ 'is chosen by the head own manifest and lockfile, so no ref approves it.' +
350
+ (skipped === null ? '' : ` There is a ${skipped}, and it was skipped for that reason.`) +
351
+ ` Install the gate outside the tree with npm install -g @vaultcompass/${product}. The ` +
352
+ `conductor Action does exactly that, at the version its ${product}-version input pins, and ` +
353
+ 'that pin lives in the workflow file on the base branch.');
354
+ }
270
355
  /**
271
356
  * Runs one gate. TOTAL: this never throws.
272
357
  *
@@ -337,10 +422,20 @@ export function runGate(gate, options) {
337
422
  }
338
423
  function runGateInner(gate, options, started, progress) {
339
424
  const timeoutMs = options.timeoutMs ?? 120_000;
425
+ // ONE PLACE DECIDES WHAT PULL-REQUEST MODE IS, and it is the presence of a
426
+ // trust base. resolve.ts knows nothing about refs, so it is told rather than
427
+ // asked.
428
+ const skipNodeModules = options.trustBase !== undefined;
429
+ const skipped = skipNodeModules ? nodeModulesCandidate(gate, options.repoRoot) : null;
430
+ if (skipped !== null) {
431
+ // Onto `progress` rather than only onto the returns below, so the
432
+ // backstop's view carries it too.
433
+ Object.assign(progress, { nodeModulesSkipped: skipped });
434
+ }
340
435
  const base = progress;
341
436
  let binary;
342
437
  try {
343
- binary = resolveGateBinary(gate, options.repoRoot, options.pathValue);
438
+ binary = resolveGateBinary(gate, options.repoRoot, options.pathValue, { skipNodeModules });
344
439
  }
345
440
  catch (err) {
346
441
  // A ResolveError is the expected shape here; anything else is still a
@@ -364,6 +459,7 @@ function runGateInner(gate, options, started, progress) {
364
459
  };
365
460
  }
366
461
  if (binary === null) {
462
+ const remedy = missingGateRemedy(gate.product, skipNodeModules, skipped);
367
463
  return {
368
464
  ...base,
369
465
  durationMs: Date.now() - started,
@@ -371,13 +467,19 @@ function runGateInner(gate, options, started, progress) {
371
467
  reason: 'binary-missing',
372
468
  // Named in resolution order, which is the repository's own copy
373
469
  // first. Saying PATH first points a reader at the location this
374
- // tool prefers second, which is the wrong place to install it.
375
- detail: `no ${gate.product} binary in node_modules/.bin or on PATH`,
470
+ // tool prefers second, which is the wrong place to install it. On a
471
+ // pull-request run that order has one entry, because the other one is
472
+ // not a location this run has.
473
+ detail: (skipNodeModules
474
+ ? `no ${gate.product} binary on PATH`
475
+ : `no ${gate.product} binary in node_modules/.bin or on PATH`) + remedy,
376
476
  },
377
477
  // A missing enabled gate is a finding of the umbrella's own, never a
378
478
  // silent skip. Skipping is how a gate ends up switched on in the
379
479
  // policy file and absent in reality for months.
380
- findings: [normalizeMissingGate(gate.role, gate.product, candidateNames(gate.product))],
480
+ findings: [
481
+ normalizeMissingGate(gate.role, gate.product, candidateNames(gate.product), remedy),
482
+ ],
381
483
  run: EMPTY_RUN,
382
484
  diagnostics: [],
383
485
  };
@@ -388,23 +490,16 @@ function runGateInner(gate, options, started, progress) {
388
490
  // version of this attack and it would have been run before anything checked
389
491
  // where it came from.
390
492
  if (options.trustBase !== undefined) {
391
- const refusal = refuseHeadControlledProgram(options.repoRoot, options.trustBase, binary.program);
493
+ // BOTH SPAWNABLE PATHS, not just the program: the probe below can be a
494
+ // different file from binary.program, and it is executed just as
495
+ // thoroughly. The enforce override and the rest of the shape live in
496
+ // gateProgramRefused, which the intent gate's preparation shares.
497
+ const refusal = refuseHeadControlledBinary(options.repoRoot, options.trustBase, binary);
392
498
  if (refusal !== null) {
393
499
  return {
394
500
  ...base,
395
- binary,
501
+ ...gateProgramRefused(gate, options.trustBase, refusal, binary),
396
502
  durationMs: Date.now() - started,
397
- // ENFORCED, whatever the policy says. enforce: false is a standing
398
- // decision about what a gate's FINDINGS are worth, and this gate
399
- // produced none: the umbrella refused to run a program the pull
400
- // request chose. Letting an unenforced gate swallow that would let a
401
- // pull request pick its own judge and keep the run green.
402
- enforce: true,
403
- trustBase: { ref: options.trustBase, withheld: null, refused: refusal, proposals: [] },
404
- couldNotRun: { reason: 'gate-program-refused', detail: refusal },
405
- findings: [normalizeFailedGate(gate.role, gate.product, refusal)],
406
- run: EMPTY_RUN,
407
- diagnostics: [],
408
503
  };
409
504
  }
410
505
  }
@@ -45,7 +45,18 @@ export type GateProblemRule = 'conductor/gate-missing' | 'conductor/gate-output-
45
45
  * looked. So it is a finding, it blocks, and it says which names were
46
46
  * tried, so the fix is in the message rather than in a support thread.
47
47
  */
48
- export declare function normalizeMissingGate(role: GateRole, product: Product, candidates: string[]): Finding;
48
+ export declare function normalizeMissingGate(role: GateRole, product: Product, candidates: string[],
49
+ /**
50
+ * A sentence appended to the message, or nothing.
51
+ *
52
+ * Written by the caller rather than decided here, because the only thing
53
+ * that varies is WHY the search came up empty, and that is a fact about the
54
+ * run rather than about the finding. Today the one caller that passes
55
+ * anything is a pull-request run, where node_modules/.bin was never
56
+ * searched and the message would otherwise be misleading in exactly the
57
+ * repository shape this is most likely to happen in.
58
+ */
59
+ remedy?: string): Finding;
49
60
  /**
50
61
  * The finding raised when a gate's `command:` names a file that is not
51
62
  * there.
package/dist/normalize.js CHANGED
@@ -620,10 +620,21 @@ function gateProblem(ruleId, role, product, message, details) {
620
620
  * looked. So it is a finding, it blocks, and it says which names were
621
621
  * tried, so the fix is in the message rather than in a support thread.
622
622
  */
623
- export function normalizeMissingGate(role, product, candidates) {
623
+ export function normalizeMissingGate(role, product, candidates,
624
+ /**
625
+ * A sentence appended to the message, or nothing.
626
+ *
627
+ * Written by the caller rather than decided here, because the only thing
628
+ * that varies is WHY the search came up empty, and that is a fact about the
629
+ * run rather than about the finding. Today the one caller that passes
630
+ * anything is a pull-request run, where node_modules/.bin was never
631
+ * searched and the message would otherwise be misleading in exactly the
632
+ * repository shape this is most likely to happen in.
633
+ */
634
+ remedy = '') {
624
635
  return gateProblem('conductor/gate-missing', role, product, `The "${role}" gate is enabled but no ${product} binary was found. ` +
625
636
  `Looked for: ${candidates.join(', ')}. Install it, point the gate at a build with an ` +
626
- `absolute "command:", or set enabled: false to switch the gate off on purpose.`, { candidates });
637
+ `absolute "command:", or set enabled: false to switch the gate off on purpose.${remedy}`, { candidates });
627
638
  }
628
639
  /**
629
640
  * The finding raised when a gate's `command:` names a file that is not
@@ -588,10 +588,11 @@ function proposalNotifications(result) {
588
588
  /**
589
589
  * The trust base the umbrella refused, when it refused one.
590
590
  *
591
- * ERROR LEVEL, and the only notification here that is not a note. Every other
592
- * one says how much of the policy a run covered; this one says the run did
593
- * not happen. It is the one statement in this file that a reader must not be
594
- * able to scroll past.
591
+ * ERROR LEVEL, one of the two notifications here that are not notes, and the
592
+ * wider of the two: a refused program says one gate did not run, and this one
593
+ * says the whole run did not. Every other notification in this file says how
594
+ * much of the policy a run covered. These two say what was not covered at
595
+ * all, and a reader must not be able to scroll past either.
595
596
  *
596
597
  * A NOTIFICATION rather than a result even so, and the reason is the
597
598
  * discriminator further down: a result is about a place in somebody's code,
@@ -686,6 +687,40 @@ function trustBaseWithheldNotifications(result) {
686
687
  ];
687
688
  });
688
689
  }
690
+ /**
691
+ * The node_modules/.bin candidates a pull-request run declined to take.
692
+ *
693
+ * ONE NOTIFICATION FOR THE RUN, not one per gate. This is a statement about
694
+ * the run's mode: node_modules/.bin is not a location a pull-request run has,
695
+ * and in the repository shape it happens in most, gates installed as
696
+ * devDependencies and nothing else, it is true of every gate at once.
697
+ *
698
+ * A NOTE, by the discriminator above, and not a close call. Nothing went
699
+ * wrong, nobody's code is at fault, and the gates still ran: it says WHERE the
700
+ * program that ran came from, which is a coverage statement in the same shape
701
+ * as the withheld one. When the skip actually cost a gate its run, that gate's
702
+ * own could-not-run result carries the remedy, so a consumer reading only
703
+ * results still learns what to do.
704
+ */
705
+ function nodeModulesSkippedNotifications(result) {
706
+ const skipped = result.gates.flatMap((gate) => gate.nodeModulesSkipped === undefined
707
+ ? []
708
+ : [{ role: gate.role, product: gate.product, path: gate.nodeModulesSkipped }]);
709
+ if (skipped.length === 0) {
710
+ return [];
711
+ }
712
+ return [
713
+ {
714
+ id: 'conductor/node-modules-skipped',
715
+ message: 'Resolution did NOT consult node_modules/.bin on this pull-request run: ' +
716
+ `${skipped.map((entry) => `${entry.role} (${entry.product}) at ${entry.path}`).join(', ')}. ` +
717
+ 'What is installed there is chosen by the head own manifest and lockfile, so no ref ' +
718
+ 'approves it. Each of those gates was resolved from PATH or from an absolute command: ' +
719
+ 'instead, or reported as could-not-run with the install remedy.',
720
+ details: { ref: result.trustBase?.ref ?? null, skipped },
721
+ },
722
+ ];
723
+ }
689
724
  /**
690
725
  * The gates the policy file told not to decide anything, as notifications.
691
726
  *
@@ -799,6 +834,7 @@ export function renderSarif(result, umbrellaVersion) {
799
834
  ...programRefusedNotifications(result),
800
835
  ...proposalNotifications(result),
801
836
  ...trustBaseWithheldNotifications(result),
837
+ ...nodeModulesSkippedNotifications(result),
802
838
  ];
803
839
  // Notifications earn the run on their own. Before this, the umbrella run
804
840
  // existed only when it had findings and a deferred gate was one; without
@@ -245,12 +245,35 @@ function withheldTrustBase(result) {
245
245
  return reason === undefined || reason === null ? [] : [{ gate, reason }];
246
246
  });
247
247
  }
248
+ /**
249
+ * The gates whose own node_modules/.bin copy this run declined to take.
250
+ *
251
+ * ONE LINE FOR THE WHOLE RUN rather than one per gate. The fact is about the
252
+ * run's mode, not about any gate's verdict, and in the repository shape it is
253
+ * most likely to happen in, gates installed as devDependencies and nothing
254
+ * else, it is true of all three at once. Three lines saying the same thing
255
+ * would read as three problems.
256
+ */
257
+ function nodeModulesSkippedLine(result) {
258
+ const skipped = result.gates.flatMap((gate) => gate.nodeModulesSkipped === undefined
259
+ ? []
260
+ : [`${gate.role} (${gate.product}) at ${gate.nodeModulesSkipped}`]);
261
+ if (skipped.length === 0) {
262
+ return [];
263
+ }
264
+ return [
265
+ ` node_modules/.bin not consulted: ${skipped.join(', ')}. What is installed there is ` +
266
+ 'chosen by the head own manifest and lockfile, so no ref approves it; each of those gates ' +
267
+ 'was resolved from PATH or from an absolute command: instead, or reported as could-not-run.',
268
+ ];
269
+ }
248
270
  /**
249
271
  * The pull-request-mode block of the full report.
250
272
  *
251
- * Three things in one place, because they answer one question between them:
273
+ * Four things in one place, because they answer one question between them:
252
274
  * where the rules came from, what this pull request proposes to change them
253
- * to, and which gates were not covered by any of it.
275
+ * to, which gates were not covered by any of it, and where the programs that
276
+ * did run came from.
254
277
  */
255
278
  function trustBaseLines(result) {
256
279
  if (result.trustBase === null) {
@@ -265,6 +288,7 @@ function trustBaseLines(result) {
265
288
  for (const { gate, reason } of withheldTrustBase(result)) {
266
289
  lines.push(` NOT in pull-request mode ${gate.role} ${gate.product} ${reason}`);
267
290
  }
291
+ lines.push(...nodeModulesSkippedLine(result));
268
292
  return lines;
269
293
  }
270
294
  /**
package/dist/resolve.d.ts CHANGED
@@ -41,9 +41,36 @@ export interface ResolvedBinary {
41
41
  versionProbe: VersionProbe | null;
42
42
  }
43
43
  export declare const CANDIDATES: Record<Product, Candidate[]>;
44
+ export interface ResolveOptions {
45
+ /**
46
+ * Leave `node_modules/.bin` out of the search entirely.
47
+ *
48
+ * True on a pull-request run and false everywhere else, decided by the
49
+ * caller from whether a trust base is set rather than re-derived here: this
50
+ * module knows nothing about refs, and there must be exactly one place that
51
+ * says what pull-request mode is.
52
+ */
53
+ skipNodeModules?: boolean;
54
+ }
44
55
  export declare class ResolveError extends Error {
45
56
  constructor(message: string);
46
57
  }
58
+ /**
59
+ * The node_modules/.bin candidate a pull-request run declined to take.
60
+ *
61
+ * Repository-relative, because it goes into a report and a published SARIF
62
+ * log, where an absolute path is somebody's machine layout.
63
+ *
64
+ * Returns null when the policy names a `command:`: that overrides resolution
65
+ * entirely, so no candidate was skipped, and saying one was would send a
66
+ * reader to fix a file that decided nothing.
67
+ *
68
+ * Separate from `resolveGateBinary` rather than a field on its result,
69
+ * because the case that most needs reporting is the one where resolution
70
+ * returns NOTHING: a repository with the gates only as devDependencies, which
71
+ * is the shape this whole change exists for.
72
+ */
73
+ export declare function nodeModulesCandidate(gate: GatePolicy, repoRoot: string): string | null;
47
74
  /**
48
75
  * Resolves the binary for one gate.
49
76
  *
@@ -58,6 +85,6 @@ export declare class ResolveError extends Error {
58
85
  * named one specific file and falling back to something else would run a
59
86
  * different tool than the one they asked for.
60
87
  */
61
- export declare function resolveGateBinary(gate: GatePolicy, repoRoot: string, pathValue: string): ResolvedBinary | null;
88
+ export declare function resolveGateBinary(gate: GatePolicy, repoRoot: string, pathValue: string, options?: ResolveOptions): ResolvedBinary | null;
62
89
  /** Every name resolution would try, for the missing-gate finding's message. */
63
90
  export declare function candidateNames(product: Product): string[];
package/dist/resolve.js CHANGED
@@ -24,6 +24,19 @@
24
24
  // no say in that; a LOCATION is a statement about which build, and the
25
25
  // repository does.
26
26
  //
27
+ // 1c. ON A PULL-REQUEST RUN node_modules/.bin IS NOT A LOCATION AT ALL.
28
+ // Rule 1b says a LOCATION is a statement about which build and the
29
+ // repository gets to make it. On a pull request the repository making
30
+ // that statement IS the pull request: what is under node_modules was
31
+ // chosen by the head's own manifest and lockfile, installed by a step
32
+ // that runs before the gates, and git has no record of those bytes at
33
+ // either ref. 0.3.0 let resolution take it and then refused the program,
34
+ // which was safe and made every ordinary pull request in a
35
+ // devDependency-installed repository exit 2 with three refusals. Not
36
+ // trying that location at all is the same safety with the gate still
37
+ // running, from a build the base branch pinned. The skip is never
38
+ // silent: the caller reports the candidate it declined.
39
+ //
27
40
  // 2. Only a unified binary is asked for its version. `intent-guard`
28
41
  // answers --version; a per-command binary once did not parse the flag at
29
42
  // all and RAN THE GATE against the current directory instead, and a
@@ -104,12 +117,16 @@ function findInNodeModules(name, repoRoot) {
104
117
  const full = path.join(repoRoot, 'node_modules', '.bin', name);
105
118
  return isExecutableFile(full) ? full : null;
106
119
  }
107
- function locate(name, repoRoot, pathValue) {
120
+ function locate(name, repoRoot, pathValue, skipNodeModules) {
108
121
  // The repository's own copy first: a project pin beats a global install,
109
- // which is what "pnpm exec <name>" does in the same repository.
110
- const local = findInNodeModules(name, repoRoot);
111
- if (local !== null) {
112
- return { command: local, source: 'node_modules' };
122
+ // which is what "pnpm exec <name>" does in the same repository. Unless this
123
+ // is a pull-request run, where the repository saying which build to use is
124
+ // the pull request itself (rule 1c at the top of this file).
125
+ if (!skipNodeModules) {
126
+ const local = findInNodeModules(name, repoRoot);
127
+ if (local !== null) {
128
+ return { command: local, source: 'node_modules' };
129
+ }
113
130
  }
114
131
  const onPath = findOnPath(name, pathValue);
115
132
  if (onPath !== null) {
@@ -117,8 +134,34 @@ function locate(name, repoRoot, pathValue) {
117
134
  }
118
135
  return null;
119
136
  }
137
+ /**
138
+ * The node_modules/.bin candidate a pull-request run declined to take.
139
+ *
140
+ * Repository-relative, because it goes into a report and a published SARIF
141
+ * log, where an absolute path is somebody's machine layout.
142
+ *
143
+ * Returns null when the policy names a `command:`: that overrides resolution
144
+ * entirely, so no candidate was skipped, and saying one was would send a
145
+ * reader to fix a file that decided nothing.
146
+ *
147
+ * Separate from `resolveGateBinary` rather than a field on its result,
148
+ * because the case that most needs reporting is the one where resolution
149
+ * returns NOTHING: a repository with the gates only as devDependencies, which
150
+ * is the shape this whole change exists for.
151
+ */
152
+ export function nodeModulesCandidate(gate, repoRoot) {
153
+ if (gate.command !== undefined) {
154
+ return null;
155
+ }
156
+ for (const candidate of CANDIDATES[gate.product]) {
157
+ if (findInNodeModules(candidate.name, repoRoot) !== null) {
158
+ return `node_modules/.bin/${candidate.name}`;
159
+ }
160
+ }
161
+ return null;
162
+ }
120
163
  /** The candidate whose --version can be asked without running anything. */
121
- function versionProbeFor(product, resolvedCandidate, resolvedCommand, repoRoot, pathValue) {
164
+ function versionProbeFor(product, resolvedCandidate, resolvedCommand, repoRoot, pathValue, skipNodeModules) {
122
165
  if (resolvedCandidate.versionSafe) {
123
166
  return { command: resolvedCommand, argv: ['--version'] };
124
167
  }
@@ -126,7 +169,10 @@ function versionProbeFor(product, resolvedCandidate, resolvedCommand, repoRoot,
126
169
  if (!candidate.versionSafe) {
127
170
  continue;
128
171
  }
129
- const found = locate(candidate.name, repoRoot, pathValue);
172
+ // The skip reaches here too, and it has to: a probe RUNS the binary, so
173
+ // resolving the version-safe sibling out of node_modules would execute a
174
+ // head-chosen program in order to answer a question about it.
175
+ const found = locate(candidate.name, repoRoot, pathValue, skipNodeModules);
130
176
  if (found !== null) {
131
177
  return { command: found.command, argv: ['--version'] };
132
178
  }
@@ -151,8 +197,9 @@ function baseName(file) {
151
197
  * named one specific file and falling back to something else would run a
152
198
  * different tool than the one they asked for.
153
199
  */
154
- export function resolveGateBinary(gate, repoRoot, pathValue) {
200
+ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
155
201
  const table = CANDIDATES[gate.product];
202
+ const skipNodeModules = options.skipNodeModules ?? false;
156
203
  if (gate.command !== undefined) {
157
204
  if (!existsAsFile(gate.command)) {
158
205
  throw new ResolveError(`gates.${gate.role}.command points at "${gate.command}", which is not a file. ` +
@@ -177,7 +224,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
177
224
  candidate: candidateName,
178
225
  versionProbe: candidate.versionSafe
179
226
  ? { command: process.execPath, argv: [gate.command, '--version'] }
180
- : versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue),
227
+ : versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
181
228
  };
182
229
  }
183
230
  return {
@@ -186,11 +233,11 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
186
233
  argvPrefix: prefix,
187
234
  source: 'policy',
188
235
  candidate: candidateName,
189
- versionProbe: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue),
236
+ versionProbe: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
190
237
  };
191
238
  }
192
239
  for (const candidate of table) {
193
- const found = locate(candidate.name, repoRoot, pathValue);
240
+ const found = locate(candidate.name, repoRoot, pathValue, skipNodeModules);
194
241
  if (found === null) {
195
242
  continue;
196
243
  }
@@ -200,7 +247,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
200
247
  argvPrefix: [...candidate.prefix],
201
248
  source: found.source,
202
249
  candidate: candidate.name,
203
- versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue),
250
+ versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
204
251
  };
205
252
  }
206
253
  return null;
package/dist/run.js CHANGED
@@ -1,7 +1,7 @@
1
1
  // One run across every enabled gate.
2
2
  import { compareFindings } from './envelope.js';
3
3
  import { EXIT_COULD_NOT_RUN, composeExitCode } from './exit-codes.js';
4
- import { preparationFailed, runGate } from './gate-runner.js';
4
+ import { gateProgramRefused, preparationFailed, refuseHeadControlledBinary, runGate, } from './gate-runner.js';
5
5
  import { resolveBaseRef } from './intent-base.js';
6
6
  import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
7
7
  import { GATE_ROLES, enabledGates, runsAtStage } from './policy.js';
@@ -23,10 +23,19 @@ function isPullRequestShaped(options, env) {
23
23
  }
24
24
  return resolveBaseRef({ ...(options.base === undefined ? {} : { base: options.base }), env }) !== null;
25
25
  }
26
- /** The intent-guard binary, or null when there is none to prepare with. */
26
+ /**
27
+ * The intent-guard binary, or null when there is none to prepare with.
28
+ *
29
+ * SAME SKIP AS runGate's, and it is not decoration: preparation SPAWNS this
30
+ * binary, before runGate has looked at anything. Resolving it out of
31
+ * node_modules on a pull-request run would execute a program the head chose,
32
+ * three times, before the program check the boundary rests on had run once.
33
+ */
27
34
  function intentBinary(gate, options) {
28
35
  try {
29
- return resolveGateBinary(gate, options.repoRoot, options.pathValue);
36
+ return resolveGateBinary(gate, options.repoRoot, options.pathValue, {
37
+ skipNodeModules: options.trustBase !== undefined,
38
+ });
30
39
  }
31
40
  catch (err) {
32
41
  // A ResolveError means the policy named a command that is not there.
@@ -174,6 +183,21 @@ export function runAll(policy, options) {
174
183
  // twice, once as a failed preparation and once as a missing gate,
175
184
  // would read as two problems where there is one.
176
185
  if (binary !== null) {
186
+ // BEFORE ANYTHING IS SPAWNED, and that ordering is the whole of it.
187
+ // runGate makes this check for every other gate and makes it first;
188
+ // for this one the preparation gets there earlier and runs the gate
189
+ // three times, so the check has to be made here as well or the
190
+ // boundary begins after the program the pull request chose has
191
+ // already run. Same builder as runGate's, so the enforce override
192
+ // cannot drift between the two places that produce this outcome.
193
+ const trustBaseRef = options.trustBase?.ref;
194
+ if (trustBaseRef !== undefined) {
195
+ const refusal = refuseHeadControlledBinary(options.repoRoot, trustBaseRef, binary);
196
+ if (refusal !== null) {
197
+ outcomes.push(gateProgramRefused(gate, trustBaseRef, refusal, binary));
198
+ continue;
199
+ }
200
+ }
177
201
  const prepared = prepareIntent({
178
202
  repoRoot: options.repoRoot,
179
203
  binary,
@@ -193,7 +217,15 @@ export function runAll(policy, options) {
193
217
  continue;
194
218
  }
195
219
  if (prepared.kind === 'failed') {
196
- outcomes.push(preparationFailed(gate, `the intent gate could not be prepared at the ${prepared.step} step: ${prepared.detail}`));
220
+ outcomes.push(preparationFailed(
221
+ // ENFORCED under a trust base, by the same argument as
222
+ // `refusedTrustBase` below: `enforce` is itself a control
223
+ // input, this gate produced no findings for it to be a
224
+ // decision about, and a pull-request run where the intent
225
+ // gate could not be prepared is one where nothing judged the
226
+ // intent. Reading the flag here let a base policy with
227
+ // enforce: false report the failure and still exit 0.
228
+ trustBaseRef === undefined ? gate : { ...gate, enforce: true }, `the intent gate could not be prepared at the ${prepared.step} step: ${prepared.detail}`));
197
229
  continue;
198
230
  }
199
231
  intent = prepared.preparation;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "license": "MIT",