@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.
@@ -8,11 +8,100 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
8
8
  * an unresolvable base ref, or a spec that would not import. Distinct from
9
9
  * gate-error on purpose, since the gate itself said nothing at all.
10
10
  */
11
- | 'preparation-failed';
11
+ | 'preparation-failed'
12
+ /**
13
+ * On a pull-request run, the umbrella could not establish that this gate
14
+ * would take its rules from the base ref, so it was not spawned. Raised for
15
+ * a gate in `TRUST_BASE_MIN_VERSION` whose version could not be read.
16
+ * Distinct from `preparation-failed`, which is about the run rather than
17
+ * about this gate, and from `binary-missing`, since the binary was found.
18
+ */
19
+ | 'trust-base-unverified'
20
+ /**
21
+ * On a pull-request run, the gate's PROGRAM is a file the head controls, so
22
+ * it was not run. Its own reason rather than a shape of
23
+ * `trust-base-unverified`, because the two send a reader to different
24
+ * places: one is a packaging problem with the installed gate, and this one
25
+ * is a pull request choosing the program that judges it.
26
+ */
27
+ | 'gate-program-refused';
12
28
  export interface CouldNotRun {
13
29
  reason: CouldNotRunReason;
14
30
  detail: string;
15
31
  }
32
+ /**
33
+ * The first version of each gate that understands `--trust-base`.
34
+ *
35
+ * A TABLE rather than a boolean, because the three gates get pull-request
36
+ * mode in three separate releases and the umbrella has to keep working
37
+ * against every combination in the meantime. A product missing from this
38
+ * table has no pull-request mode yet and is never handed the flag; a product
39
+ * in it is handed the flag only when the installed build says it is at least
40
+ * this version. Both directions matter: handing an older build a flag it does
41
+ * not parse makes it exit non-zero with no JSON, which the umbrella correctly
42
+ * reports as could-not-run, so a wrong guess here turns a working repository's
43
+ * pull requests red rather than merely leaving a gate un-hardened.
44
+ *
45
+ * The umbrella is deliberately NOT the place a version pin lives otherwise
46
+ * (nothing here imports any gate's package), and this is the one exception:
47
+ * it is a statement about a command-line flag, which is the only interface
48
+ * this package has to those tools.
49
+ */
50
+ export declare const TRUST_BASE_MIN_VERSION: Partial<Record<Product, string>>;
51
+ /**
52
+ * Pull-request mode as it applied to ONE gate.
53
+ *
54
+ * Carried on the outcome rather than worked out again by each reporter,
55
+ * because two different things have to be visible and neither is derivable
56
+ * from the other: whether this gate was actually put into pull-request mode,
57
+ * and what it said about the control inputs the head proposes to change.
58
+ *
59
+ * `withheld` is the half that must never be silent. A gate the umbrella could
60
+ * not put into pull-request mode read its own control inputs out of the tree
61
+ * under judgment, which is the whole hole this release exists to close, and a
62
+ * run where that happened must not look like a run where it did not.
63
+ */
64
+ export interface GateTrustBase {
65
+ /** The ref the umbrella took its own policy from, and offered to this gate. */
66
+ ref: string;
67
+ /**
68
+ * Null when the flag was passed; otherwise the reason it was not, for a
69
+ * gate that was never going to be inside the boundary in the first place.
70
+ * The run continues: that gate read its own control inputs from the tree
71
+ * being judged, and the report says so.
72
+ */
73
+ withheld: string | null;
74
+ /**
75
+ * Set when the umbrella could not ESTABLISH that this gate would be in
76
+ * pull-request mode, which is could-not-run rather than a downgrade.
77
+ *
78
+ * The distinction is the whole point and it is not symmetry with
79
+ * `withheld`. A gate outside the table was never going to get the flag, so
80
+ * nothing is unknown about it. A gate INSIDE the table is one this
81
+ * repository expects to be inside the boundary, and a version probe that
82
+ * fails leaves that unestablished for an unexplained reason. Falling back
83
+ * to running it anyway would put it quietly outside the boundary on the
84
+ * exact runs where something is already wrong.
85
+ */
86
+ refused: string | null;
87
+ /** The control-input changes this gate reported as proposed. */
88
+ proposals: string[];
89
+ }
90
+ /**
91
+ * Whether this gate can be handed `--trust-base`, and why not when it cannot.
92
+ *
93
+ * Exported so the decision can be tested directly rather than only through a
94
+ * spawned child, and so there is exactly one copy of it.
95
+ *
96
+ * THE PROJECT DIRECTORY IS THE FIRST TEST, not the version. The flag names a
97
+ * git ref, and intent-guard resolves it against its own `--project`. On a
98
+ * run with an imported contract that directory is a temporary one the
99
+ * umbrella made, holding a contract and nothing else, with no repository in
100
+ * it: the child would exit 2 on a ref it could not resolve, and the gate that
101
+ * was working a moment ago would report could-not-run. So the flag goes only
102
+ * where `--project` is the repository itself.
103
+ */
104
+ export declare function decideTrustBase(gate: GatePolicy, intent: IntentPreparation | undefined, trustBase: string | undefined, productVersion: string | null): GateTrustBase | undefined;
16
105
  export interface GateOutcome {
17
106
  role: GateRole;
18
107
  product: Product;
@@ -47,6 +136,22 @@ export interface GateOutcome {
47
136
  contractSource: ContractSource;
48
137
  baseRef: string | null;
49
138
  };
139
+ /**
140
+ * Present only on a pull-request run. Whether this gate was put into
141
+ * pull-request mode, and what it said was proposed.
142
+ */
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;
50
155
  }
51
156
  export interface RunGateOptions {
52
157
  repoRoot: string;
@@ -57,6 +162,22 @@ export interface RunGateOptions {
57
162
  timeoutMs?: number;
58
163
  /** The contract and change set prepared for the intent gate, when there is one. */
59
164
  intent?: IntentPreparation;
165
+ /**
166
+ * The repository's own frozen contract, for a run with NO preparation.
167
+ *
168
+ * A plain `conductor run` never prepares anything, but the intent gate
169
+ * still judges against the contract in the repository, resolved by the
170
+ * child from `--project .`. Recording it makes that visible: the report
171
+ * says which contract, and the SARIF fallback files the gate's own results
172
+ * against the contract they are about rather than against the policy file.
173
+ * Ignored when `intent` is set, which already carries the same fact.
174
+ */
175
+ intentContract?: string;
176
+ /**
177
+ * The ref the umbrella took its own policy from, on a pull-request run.
178
+ * Offered to every child; `decideTrustBase` says which ones can take it.
179
+ */
180
+ trustBase?: string;
60
181
  }
61
182
  /**
62
183
  * A gate that never got as far as being spawned.
@@ -68,6 +189,37 @@ export interface RunGateOptions {
68
189
  * would have to learn about.
69
190
  */
70
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;
71
223
  /**
72
224
  * The arguments the umbrella adds, per product.
73
225
  *
@@ -83,7 +235,13 @@ export declare function preparationFailed(gate: GatePolicy, detail: string): Gat
83
235
  * decided by that gate's own argument parser rather than by anything the
84
236
  * user could read in their own policy file.
85
237
  */
86
- export declare function gateArgs(gate: GatePolicy, staged: boolean, intent: IntentPreparation | undefined): string[];
238
+ export declare function gateArgs(gate: GatePolicy, staged: boolean, intent: IntentPreparation | undefined,
239
+ /**
240
+ * The trust base to hand THIS gate, or undefined. Already decided by
241
+ * `decideTrustBase`; nothing here re-decides it, so a gate that cannot take
242
+ * the flag is never handed one by a second opinion written in this switch.
243
+ */
244
+ trustBase?: string): string[];
87
245
  /**
88
246
  * Runs one gate. TOTAL: this never throws.
89
247
  *
@@ -19,7 +19,95 @@ import { spawnSync } from 'node:child_process';
19
19
  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
- import { ResolveError, candidateNames, resolveGateBinary } from './resolve.js';
22
+ import { atLeastVersion, refuseHeadControlledProgram } from './trust-base.js';
23
+ import { ResolveError, candidateNames, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
24
+ /**
25
+ * The first version of each gate that understands `--trust-base`.
26
+ *
27
+ * A TABLE rather than a boolean, because the three gates get pull-request
28
+ * mode in three separate releases and the umbrella has to keep working
29
+ * against every combination in the meantime. A product missing from this
30
+ * table has no pull-request mode yet and is never handed the flag; a product
31
+ * in it is handed the flag only when the installed build says it is at least
32
+ * this version. Both directions matter: handing an older build a flag it does
33
+ * not parse makes it exit non-zero with no JSON, which the umbrella correctly
34
+ * reports as could-not-run, so a wrong guess here turns a working repository's
35
+ * pull requests red rather than merely leaving a gate un-hardened.
36
+ *
37
+ * The umbrella is deliberately NOT the place a version pin lives otherwise
38
+ * (nothing here imports any gate's package), and this is the one exception:
39
+ * it is a statement about a command-line flag, which is the only interface
40
+ * this package has to those tools.
41
+ */
42
+ export const TRUST_BASE_MIN_VERSION = {
43
+ 'intent-guard': '1.4.0',
44
+ 'vault-guard': '1.7.0',
45
+ 'dep-guard': '0.6.0',
46
+ // All three products are in. The table stays a table rather than becoming
47
+ // a boolean: a fourth role can arrive without one, and the "no
48
+ // pull-request mode yet" branch below is what keeps that gate from being
49
+ // handed a flag it would reject.
50
+ };
51
+ /**
52
+ * Whether this gate can be handed `--trust-base`, and why not when it cannot.
53
+ *
54
+ * Exported so the decision can be tested directly rather than only through a
55
+ * spawned child, and so there is exactly one copy of it.
56
+ *
57
+ * THE PROJECT DIRECTORY IS THE FIRST TEST, not the version. The flag names a
58
+ * git ref, and intent-guard resolves it against its own `--project`. On a
59
+ * run with an imported contract that directory is a temporary one the
60
+ * umbrella made, holding a contract and nothing else, with no repository in
61
+ * it: the child would exit 2 on a ref it could not resolve, and the gate that
62
+ * was working a moment ago would report could-not-run. So the flag goes only
63
+ * where `--project` is the repository itself.
64
+ */
65
+ export function decideTrustBase(gate, intent, trustBase, productVersion) {
66
+ if (trustBase === undefined) {
67
+ return undefined;
68
+ }
69
+ const withheld = (reason) => ({
70
+ ref: trustBase,
71
+ withheld: reason,
72
+ refused: null,
73
+ proposals: [],
74
+ });
75
+ const refused = (reason) => ({
76
+ ref: trustBase,
77
+ withheld: null,
78
+ refused: reason,
79
+ proposals: [],
80
+ });
81
+ if (intent !== undefined && intent.contractSource.kind !== 'native') {
82
+ return withheld('the intent gate is running against a contract imported for this run, which lives in a ' +
83
+ 'temporary directory with no repository in it, so there is no ref there to read control ' +
84
+ 'inputs from. The contract it is judging against came from a spec in the head tree.');
85
+ }
86
+ const minimum = TRUST_BASE_MIN_VERSION[gate.product];
87
+ if (minimum === undefined) {
88
+ return withheld(`${gate.product} has no pull-request mode yet, so it read its own configuration from the ` +
89
+ 'tree being judged.');
90
+ }
91
+ // An UNREADABLE version is refused, not withheld, and only for a product in
92
+ // the table. The old code folded the two together and interpolated the
93
+ // missing version straight into the sentence, which read "intent-guard
94
+ // reported no version does not understand --trust-base": not a sentence,
95
+ // and it named a version that does not exist. Worse than the wording, it
96
+ // said the gate had been left outside the boundary on purpose when what had
97
+ // actually happened is that the umbrella could not tell.
98
+ if (productVersion === null) {
99
+ return refused(`${gate.product} is expected to run in pull-request mode from ${minimum} onwards, and its ` +
100
+ 'version could not be read, so the umbrella cannot establish that this gate would take ' +
101
+ 'its rules from the base ref. Nothing was checked by it. Running it anyway would put it ' +
102
+ 'quietly outside the trust boundary on exactly the runs where something is already wrong.');
103
+ }
104
+ if (!atLeastVersion(productVersion, minimum)) {
105
+ return withheld(`${gate.product} ${productVersion} does not understand --trust-base, which arrived in ` +
106
+ `${minimum}, so it read its own control inputs from the tree being judged. Upgrade it to ` +
107
+ 'put this gate into pull-request mode.');
108
+ }
109
+ return { ref: trustBase, withheld: null, refused: null, proposals: [] };
110
+ }
23
111
  /**
24
112
  * A gate that never got as far as being spawned.
25
113
  *
@@ -54,6 +142,66 @@ const EMPTY_RUN = {
54
142
  diagnostics: [],
55
143
  details: {},
56
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
+ }
57
205
  /**
58
206
  * The arguments the umbrella adds, per product.
59
207
  *
@@ -69,19 +217,41 @@ const EMPTY_RUN = {
69
217
  * decided by that gate's own argument parser rather than by anything the
70
218
  * user could read in their own policy file.
71
219
  */
72
- export function gateArgs(gate, staged, intent) {
220
+ export function gateArgs(gate, staged, intent,
221
+ /**
222
+ * The trust base to hand THIS gate, or undefined. Already decided by
223
+ * `decideTrustBase`; nothing here re-decides it, so a gate that cannot take
224
+ * the flag is never handed one by a second opinion written in this switch.
225
+ */
226
+ trustBase) {
73
227
  const passthrough = renderOptionFlags(gate.options);
228
+ const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
74
229
  switch (gate.product) {
75
230
  case 'dep-guard':
76
- return [...(staged ? ['--staged'] : []), '--format', 'json', ...passthrough];
231
+ // `scan` takes --trust-base from 0.6.0. It sits beside whatever the
232
+ // umbrella already passes rather than replacing it: --trust-base says
233
+ // where the RULES come from and the mode flags say what is scanned,
234
+ // and a pull-request run passes both.
235
+ return [...(staged ? ['--staged'] : []), '--format', 'json', ...trust, ...passthrough];
77
236
  case 'vault-guard':
78
237
  // No path argument: the CLI defaults it to "." and the umbrella runs
79
238
  // with cwd at the repository root anyway. Passing one would also risk
80
239
  // a passthrough value being read as the positional.
81
- return [...(staged ? ['--staged'] : []), '-f', 'json', ...passthrough];
240
+ //
241
+ // `scan` takes --trust-base from 1.7.0, and on exit 2 it prints one
242
+ // line on stderr and NO document at all, which the could-not-run path
243
+ // above already handles before JSON.parse is reached.
244
+ return [...(staged ? ['--staged'] : []), '-f', 'json', ...trust, ...passthrough];
82
245
  case 'intent-guard': {
83
246
  if (intent === undefined) {
84
- return ['--project', '.', ...(staged ? ['--staged'] : []), '--json', ...passthrough];
247
+ return [
248
+ '--project',
249
+ '.',
250
+ ...(staged ? ['--staged'] : []),
251
+ ...trust,
252
+ '--json',
253
+ ...passthrough,
254
+ ];
85
255
  }
86
256
  // A prepared run replaces --staged entirely rather than adding to it.
87
257
  // The two path sources are ADDITIVE in intent-guard, so leaving
@@ -99,6 +269,10 @@ export function gateArgs(gate, staged, intent) {
99
269
  ? ['--staged']
100
270
  : []
101
271
  : ['--paths', intent.paths.join(',')]),
272
+ // Beside --paths on purpose, and they are independent: --trust-base
273
+ // says where the RULES come from, --paths says which paths are
274
+ // judged. A pull-request run passes both.
275
+ ...trust,
102
276
  '--json',
103
277
  ...passthrough,
104
278
  ];
@@ -153,6 +327,31 @@ function messageOf(err) {
153
327
  }
154
328
  return String(err);
155
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
+ }
156
355
  /**
157
356
  * Runs one gate. TOTAL: this never throws.
158
357
  *
@@ -178,14 +377,25 @@ export function runGate(gate, options) {
178
377
  // Carried on every return path below, including the failures: which
179
378
  // contract a gate WOULD have used is exactly as interesting when it could
180
379
  // not run as when it could.
181
- ...(options.intent === undefined
182
- ? {}
183
- : {
380
+ ...(options.intent !== undefined
381
+ ? {
184
382
  intent: {
185
383
  contractSource: options.intent.contractSource,
186
384
  baseRef: options.intent.baseRef,
187
385
  },
188
- }),
386
+ }
387
+ : options.intentContract === undefined
388
+ ? {}
389
+ : {
390
+ // No preparation, but the repository has a frozen contract and
391
+ // the child will read it from `--project .`. Same shape, and the
392
+ // base is null because nothing was diffed: this run is the index
393
+ // or the working tree, not a branch against a ref.
394
+ intent: {
395
+ contractSource: { kind: 'native', path: options.intentContract },
396
+ baseRef: null,
397
+ },
398
+ }),
189
399
  };
190
400
  const started = Date.now();
191
401
  try {
@@ -212,10 +422,20 @@ export function runGate(gate, options) {
212
422
  }
213
423
  function runGateInner(gate, options, started, progress) {
214
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
+ }
215
435
  const base = progress;
216
436
  let binary;
217
437
  try {
218
- binary = resolveGateBinary(gate, options.repoRoot, options.pathValue);
438
+ binary = resolveGateBinary(gate, options.repoRoot, options.pathValue, { skipNodeModules });
219
439
  }
220
440
  catch (err) {
221
441
  // A ResolveError is the expected shape here; anything else is still a
@@ -239,6 +459,7 @@ function runGateInner(gate, options, started, progress) {
239
459
  };
240
460
  }
241
461
  if (binary === null) {
462
+ const remedy = missingGateRemedy(gate.product, skipNodeModules, skipped);
242
463
  return {
243
464
  ...base,
244
465
  durationMs: Date.now() - started,
@@ -246,19 +467,81 @@ function runGateInner(gate, options, started, progress) {
246
467
  reason: 'binary-missing',
247
468
  // Named in resolution order, which is the repository's own copy
248
469
  // first. Saying PATH first points a reader at the location this
249
- // tool prefers second, which is the wrong place to install it.
250
- 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,
251
476
  },
252
477
  // A missing enabled gate is a finding of the umbrella's own, never a
253
478
  // silent skip. Skipping is how a gate ends up switched on in the
254
479
  // policy file and absent in reality for months.
255
- findings: [normalizeMissingGate(gate.role, gate.product, candidateNames(gate.product))],
480
+ findings: [
481
+ normalizeMissingGate(gate.role, gate.product, candidateNames(gate.product), remedy),
482
+ ],
256
483
  run: EMPTY_RUN,
257
484
  diagnostics: [],
258
485
  };
259
486
  }
487
+ // BEFORE the version probe, and that ordering is the whole of it: the probe
488
+ // RUNS the program, so asking a head-controlled binary for its version is
489
+ // already executing it. A planted stub answering "1.7.0" is the cheapest
490
+ // version of this attack and it would have been run before anything checked
491
+ // where it came from.
492
+ if (options.trustBase !== undefined) {
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);
498
+ if (refusal !== null) {
499
+ return {
500
+ ...base,
501
+ ...gateProgramRefused(gate, options.trustBase, refusal, binary),
502
+ durationMs: Date.now() - started,
503
+ };
504
+ }
505
+ }
260
506
  const version = probeVersion(binary, options.repoRoot, timeoutMs);
261
- const argv = [...binary.argvPrefix, ...gateArgs(gate, options.staged, options.intent)];
507
+ // AFTER the version probe and BEFORE the command line is built, because the
508
+ // decision reads the version. That ordering is the whole capability gate:
509
+ // an intent-guard older than 1.4.0 must not be handed a flag it would
510
+ // reject, and a gate IN the table whose version could not be read is
511
+ // refused rather than run outside the boundary.
512
+ const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version);
513
+ if (trustBase !== undefined && trustBase.refused !== null) {
514
+ return {
515
+ ...base,
516
+ productVersion: version,
517
+ binary,
518
+ durationMs: Date.now() - started,
519
+ // ENFORCED, whatever the policy says, for the same reason a refused
520
+ // program is: the gate produced no findings for `enforce: false` to be
521
+ // a decision about, and this is the umbrella saying it could not
522
+ // establish that the gate was inside the boundary.
523
+ //
524
+ // Reachable now only as a PACKAGING problem, not as an attack: the
525
+ // program check above runs first, and with its directory-subtree rule a
526
+ // pull request can no longer put a program here whose version probe it
527
+ // controls. Before that rule it could, through the wrapper shape: a
528
+ // head-replaced inner script exiting 3 on --version landed exactly
529
+ // here, with enforce false and exit 0. A packaging quirk that
530
+ // fails a build loudly is the better failure: the alternative is a
531
+ // boundary that quietly downgrades itself on the runs where something
532
+ // is already wrong, which is the shape of every bug in this file.
533
+ enforce: true,
534
+ trustBase,
535
+ couldNotRun: { reason: 'trust-base-unverified', detail: trustBase.refused },
536
+ findings: [normalizeFailedGate(gate.role, gate.product, trustBase.refused)],
537
+ run: EMPTY_RUN,
538
+ diagnostics: [],
539
+ };
540
+ }
541
+ const argv = [
542
+ ...binary.argvPrefix,
543
+ ...gateArgs(gate, options.staged, options.intent, trustBase === undefined || trustBase.withheld !== null ? undefined : trustBase.ref),
544
+ ];
262
545
  const child = spawnSync(binary.command, argv, {
263
546
  cwd: options.repoRoot,
264
547
  encoding: 'utf8',
@@ -272,6 +555,12 @@ function runGateInner(gate, options, started, progress) {
272
555
  binary,
273
556
  durationMs: Date.now() - started,
274
557
  stderr: child.stderr ?? '',
558
+ // Carried on every return path below, the failures included: WHETHER
559
+ // this gate was in pull-request mode is exactly as interesting when it
560
+ // could not run as when it could, and the withheld reason is the only
561
+ // place a report can say a gate read its own rules out of the tree under
562
+ // judgment.
563
+ ...(trustBase === undefined ? {} : { trustBase }),
275
564
  };
276
565
  // Keep the backstop's view current, so an unexpected throw below still
277
566
  // reports which binary ran and what it printed.
@@ -339,6 +628,14 @@ function runGateInner(gate, options, started, progress) {
339
628
  findings: normalized.findings,
340
629
  run: normalized.run,
341
630
  diagnostics: normalized.diagnostics,
631
+ // The gate's own answer about the control inputs, folded onto the
632
+ // decision the umbrella made before spawning it. A gate that was NOT
633
+ // put into pull-request mode reports no proposals, and its trustBase
634
+ // keeps the withheld reason rather than being overwritten with an
635
+ // empty list that would read as "nothing was proposed".
636
+ ...(trustBase === undefined || normalized.trustBase === undefined
637
+ ? {}
638
+ : { trustBase: { ...trustBase, proposals: normalized.trustBase.proposals } }),
342
639
  };
343
640
  }
344
641
  catch (err) {
@@ -118,4 +118,20 @@ export interface IntentPrepareOptions {
118
118
  */
119
119
  tempRoot?: string;
120
120
  }
121
+ /**
122
+ * The repository's own frozen contract, or null, for a run with no
123
+ * preparation at all.
124
+ *
125
+ * The whole of `prepareIntent` only runs on a pull-request shaped run. A
126
+ * plain `conductor run` against a repository that HAS a frozen contract still
127
+ * judges against that contract -- the child resolves it from `--project .` --
128
+ * but the umbrella recorded nothing about it, so both reports had to say
129
+ * nothing and the SARIF fallback filed the gate's own results against the
130
+ * policy file rather than against the contract they are actually about.
131
+ *
132
+ * Exported for that one caller. It is deliberately the same predicate the
133
+ * preparation uses, FROZEN rather than present, so the two cannot disagree
134
+ * about which file the gate will read.
135
+ */
136
+ export declare function frozenNativeContractPath(repoRoot: string): string | null;
121
137
  export declare function prepareIntent(options: IntentPrepareOptions): IntentPrepareResult;
@@ -133,6 +133,24 @@ function contractIsFrozenAt(absolutePath) {
133
133
  function frozenNativeContracts(repoRoot) {
134
134
  return NATIVE_CONTRACT_PATHS.filter((relative) => contractIsFrozenAt(path.join(repoRoot, relative)));
135
135
  }
136
+ /**
137
+ * The repository's own frozen contract, or null, for a run with no
138
+ * preparation at all.
139
+ *
140
+ * The whole of `prepareIntent` only runs on a pull-request shaped run. A
141
+ * plain `conductor run` against a repository that HAS a frozen contract still
142
+ * judges against that contract -- the child resolves it from `--project .` --
143
+ * but the umbrella recorded nothing about it, so both reports had to say
144
+ * nothing and the SARIF fallback filed the gate's own results against the
145
+ * policy file rather than against the contract they are actually about.
146
+ *
147
+ * Exported for that one caller. It is deliberately the same predicate the
148
+ * preparation uses, FROZEN rather than present, so the two cannot disagree
149
+ * about which file the gate will read.
150
+ */
151
+ export function frozenNativeContractPath(repoRoot) {
152
+ return frozenNativeContracts(repoRoot)[0] ?? null;
153
+ }
136
154
  /**
137
155
  * The files only intent-guard writes into its state directory.
138
156
  *