@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.
@@ -218,6 +218,79 @@ function skipWording(reason) {
218
218
  function excludedLines(result) {
219
219
  return result.excluded.map((gate) => ` excluded ${gate.role} ${gate.product} did not run here; --gate did not name it`);
220
220
  }
221
+ /**
222
+ * The one sentence the whole of pull-request mode has to fit into.
223
+ *
224
+ * Counted even at ZERO, by the family suppression rule: the number is the
225
+ * answer to "did this pull request also try to change the rules", and leaving
226
+ * it out when the answer is none makes a run in pull-request mode
227
+ * indistinguishable from a run that was never in it.
228
+ */
229
+ function proposalCount(result) {
230
+ return `${result.proposals.length} control change(s) proposed in this pull request`;
231
+ }
232
+ /**
233
+ * The gates the umbrella could not put into pull-request mode.
234
+ *
235
+ * This is the loud half and it must never be silent. A gate here read its own
236
+ * contract, config or baseline out of the tree being judged, which is exactly
237
+ * the hole pull-request mode exists to close, so a run where one gate is
238
+ * still exposed must not read like a run where none is. It is a statement
239
+ * about coverage rather than about anybody's code, so it is a line and a
240
+ * notification rather than a finding, and it never reaches the exit code.
241
+ */
242
+ function withheldTrustBase(result) {
243
+ return result.gates.flatMap((gate) => {
244
+ const reason = gate.trustBase?.withheld;
245
+ return reason === undefined || reason === null ? [] : [{ gate, reason }];
246
+ });
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
+ }
270
+ /**
271
+ * The pull-request-mode block of the full report.
272
+ *
273
+ * Four things in one place, because they answer one question between them:
274
+ * where the rules came from, what this pull request proposes to change them
275
+ * to, which gates were not covered by any of it, and where the programs that
276
+ * did run came from.
277
+ */
278
+ function trustBaseLines(result) {
279
+ if (result.trustBase === null) {
280
+ return [];
281
+ }
282
+ const lines = [
283
+ ` pull-request mode: rules from ${result.trustBase.ref}. ${proposalCount(result)}.`,
284
+ ];
285
+ for (const proposal of result.proposals) {
286
+ lines.push(` proposed ${proposal.product.padEnd(13)} ${proposal.line}`);
287
+ }
288
+ for (const { gate, reason } of withheldTrustBase(result)) {
289
+ lines.push(` NOT in pull-request mode ${gate.role} ${gate.product} ${reason}`);
290
+ }
291
+ lines.push(...nodeModulesSkippedLine(result));
292
+ return lines;
293
+ }
221
294
  /**
222
295
  * What an unenforced gate did, as clauses for a verdict line.
223
296
  *
@@ -244,7 +317,39 @@ function unenforcedClauses(result) {
244
317
  }
245
318
  return clauses;
246
319
  }
320
+ /**
321
+ * The refusal, as the first line of the report and as the verdict.
322
+ *
323
+ * FIRST, and before any question about how many gates there are. The old
324
+ * order asked that question first, and an inventory naming no gate -- every
325
+ * gate `enabled: false` in the head's file, or a head file that will not
326
+ * parse -- fell into the "no gate ran because none is enabled" branch, which
327
+ * printed exit 0 and told the reader to switch a gate on while the process
328
+ * exited 2 and nothing had been checked. The refusal is the whole story of
329
+ * such a run and there is no arrangement of the other clauses that tells it.
330
+ */
331
+ function refusalLines(result) {
332
+ const refusal = result.trustBase?.refusal;
333
+ if (refusal === undefined || refusal === null) {
334
+ return [];
335
+ }
336
+ return [
337
+ `conductor: refused the trust base "${result.trustBase?.ref ?? ''}". Nothing was checked.`,
338
+ ` ${refusal}`,
339
+ ];
340
+ }
247
341
  function verdict(result) {
342
+ const refusal = result.trustBase?.refusal;
343
+ if (refusal !== undefined && refusal !== null) {
344
+ // Written rather than composed, exactly as the exit code is: no gate ran,
345
+ // so there is nothing for the clauses below to count, and every one of
346
+ // them would describe a different run from the one that happened.
347
+ return (`verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
348
+ 'so no gate ran and nothing here is a result of any kind.');
349
+ }
350
+ return verdictForRun(result);
351
+ }
352
+ function verdictForRun(result) {
248
353
  // Counted over ENFORCED gates only. The exit code came from those alone,
249
354
  // so a count taken over all of them describes a different run from the one
250
355
  // the number at the front of the line is about, and the umbrella's own
@@ -478,11 +583,25 @@ function summaryLine(result) {
478
583
  parts.push(gatesReportingIgnored.length === result.gates.length
479
584
  ? `${suppressed} suppressed, ${ignored} ignored across all gates.`
480
585
  : `${suppressed} suppressed across all gates.`);
586
+ // Pull-request mode, on the one line a hook and a pull request comment
587
+ // actually print. A clean run is exactly where this matters most: a pull
588
+ // request that proposes to switch a gate off and carries nothing else
589
+ // produces a clean report, and without this clause the only trace of the
590
+ // attempt would be in a file nobody re-reads.
591
+ if (result.trustBase !== null) {
592
+ parts.push(`Rules from ${result.trustBase.ref}. ${proposalCount(result)}.`);
593
+ const withheld = withheldTrustBase(result);
594
+ if (withheld.length > 0) {
595
+ const names = withheld.map(({ gate }) => `${gate.role} (${gate.product})`).join(', ');
596
+ parts.push(`${withheld.length} gate(s) NOT in pull-request mode: ${names}.`);
597
+ }
598
+ }
481
599
  parts.push('Re-run with --verbose for the full report.');
482
600
  return parts.join(' ');
483
601
  }
484
602
  export function renderText(result, options = {}) {
485
- if (!options.verbose && isFullyClean(result)) {
603
+ const refusal = refusalLines(result);
604
+ if (refusal.length === 0 && !options.verbose && isFullyClean(result)) {
486
605
  return `${summaryLine(result)}\n`;
487
606
  }
488
607
  // Counted over EVERY gate, unenforced ones included, and deliberately not
@@ -494,6 +613,8 @@ export function renderText(result, options = {}) {
494
613
  // different questions, so two numbers, and the section headers and the
495
614
  // "not enforced" lines are what connect them.
496
615
  const lines = [
616
+ ...refusal,
617
+ ...(refusal.length === 0 ? [] : ['']),
497
618
  `conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
498
619
  ];
499
620
  for (const gate of result.gates) {
@@ -503,6 +624,10 @@ export function renderText(result, options = {}) {
503
624
  if (aside.length > 0) {
504
625
  lines.push('', ...aside);
505
626
  }
627
+ const trust = trustBaseLines(result);
628
+ if (trust.length > 0) {
629
+ lines.push('', ...trust);
630
+ }
506
631
  // A derived severity is marked with a trailing asterisk above; say what
507
632
  // that means rather than leaving a reader to guess, and only when one is
508
633
  // actually on screen.
package/dist/policy.js CHANGED
@@ -87,8 +87,15 @@ export const PRODUCT_FOR_ROLE = {
87
87
  * could read in their own policy file.
88
88
  */
89
89
  export const RESERVED_OPTIONS = {
90
- 'dep-guard': ['format', 'staged', 'base'],
91
- 'vault-guard': ['format', 'f', 'staged'],
90
+ // `trust-base` is reserved for all three products, and the umbrella now
91
+ // writes it for all three. It was reserved here before dep-guard's own
92
+ // pull-request mode shipped, deliberately: a policy file is a standing
93
+ // document, and a key that parsed one week and was rejected the next would
94
+ // have broken repositories on an upgrade nobody asked for. The flag it
95
+ // names is the one that decides where a gate reads its rules from, which
96
+ // is the last place to leave a window open.
97
+ 'dep-guard': ['format', 'staged', 'base', 'trust-base'],
98
+ 'vault-guard': ['format', 'f', 'staged', 'trust-base'],
92
99
  // `base` is reserved even though the umbrella never passes it to this gate,
93
100
  // and that is the point. The umbrella works the changed-path set out itself
94
101
  // and hands over `--paths`, because `--project` may be a temporary
@@ -96,7 +103,15 @@ export const RESERVED_OPTIONS = {
96
103
  // sends intent-guard looking for git THERE, and the run exits 2 blaming git
97
104
  // for a line in the policy file. Rejecting the key at load time is the only
98
105
  // place that failure can be explained by the thing that caused it.
99
- 'intent-guard': ['json', 'staged', 'project', 'paths', 'base'],
106
+ // `trust-base` is written by the umbrella on a pull-request run, and only
107
+ // there. It is reserved unconditionally rather than only in that mode,
108
+ // because a policy file is a standing document: a key that is accepted on a
109
+ // push build and rejected on a pull request would be a policy file that
110
+ // parses on one event and not the other, which is the worst place to find
111
+ // out. It is also the one flag where two writers would be a security
112
+ // problem rather than a confusion, since the loser decides where the gate
113
+ // reads its rules from.
114
+ 'intent-guard': ['json', 'staged', 'project', 'paths', 'base', 'trust-base'],
100
115
  };
101
116
  export class PolicyError extends Error {
102
117
  constructor(message) {
@@ -147,6 +162,12 @@ function describeErrors(errors, source) {
147
162
  * so a fourth cannot be added without saying why.
148
163
  */
149
164
  function reservedReason(product, key) {
165
+ if (key === 'trust-base') {
166
+ return ('That flag says where a gate reads its rules from, and on a pull-request run the umbrella ' +
167
+ 'writes it itself, pointing at the base ref it read its own policy from. A value here ' +
168
+ 'would be a second writer of the flag that decides the trust boundary, set in the file ' +
169
+ "the pull request controls. Use the umbrella own --trust-base instead.");
170
+ }
150
171
  if (product === 'intent-guard' && key === 'base') {
151
172
  return ('The umbrella works the changed-path set out itself and passes --paths, because ' +
152
173
  '--project may be a temporary directory holding only a contract. A --base here ' +
package/dist/resolve.d.ts CHANGED
@@ -21,6 +21,17 @@ export interface VersionProbe {
21
21
  export interface ResolvedBinary {
22
22
  /** What to spawn. */
23
23
  command: string;
24
+ /**
25
+ * The FILE whose contents decide what this gate does.
26
+ *
27
+ * Usually the same as `command`, and deliberately not the same when a
28
+ * `.js` build is run through this Node: there `command` is the Node
29
+ * executable and the program is the script after it. Carried explicitly
30
+ * rather than reconstructed from `argvPrefix[0]` by every caller, because
31
+ * getting that wrong means vetting the wrong file, and the one caller that
32
+ * vets it is the pull-request provenance check.
33
+ */
34
+ program: string;
24
35
  /** Arguments placed before the ones the umbrella adds. */
25
36
  argvPrefix: string[];
26
37
  source: ResolutionSource;
@@ -30,9 +41,36 @@ export interface ResolvedBinary {
30
41
  versionProbe: VersionProbe | null;
31
42
  }
32
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
+ }
33
55
  export declare class ResolveError extends Error {
34
56
  constructor(message: string);
35
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;
36
74
  /**
37
75
  * Resolves the binary for one gate.
38
76
  *
@@ -47,6 +85,6 @@ export declare class ResolveError extends Error {
47
85
  * named one specific file and falling back to something else would run a
48
86
  * different tool than the one they asked for.
49
87
  */
50
- 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;
51
89
  /** Every name resolution would try, for the missing-gate finding's message. */
52
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. ` +
@@ -170,33 +217,37 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
170
217
  if (!isExecutableFile(gate.command) && /\.(?:js|mjs|cjs)$/.test(gate.command)) {
171
218
  return {
172
219
  command: process.execPath,
220
+ // Node is the command; the script is what actually decides anything.
221
+ program: gate.command,
173
222
  argvPrefix: [gate.command, ...prefix],
174
223
  source: 'policy',
175
224
  candidate: candidateName,
176
225
  versionProbe: candidate.versionSafe
177
226
  ? { command: process.execPath, argv: [gate.command, '--version'] }
178
- : versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue),
227
+ : versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
179
228
  };
180
229
  }
181
230
  return {
182
231
  command: gate.command,
232
+ program: gate.command,
183
233
  argvPrefix: prefix,
184
234
  source: 'policy',
185
235
  candidate: candidateName,
186
- versionProbe: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue),
236
+ versionProbe: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
187
237
  };
188
238
  }
189
239
  for (const candidate of table) {
190
- const found = locate(candidate.name, repoRoot, pathValue);
240
+ const found = locate(candidate.name, repoRoot, pathValue, skipNodeModules);
191
241
  if (found === null) {
192
242
  continue;
193
243
  }
194
244
  return {
195
245
  command: found.command,
246
+ program: found.command,
196
247
  argvPrefix: [...candidate.prefix],
197
248
  source: found.source,
198
249
  candidate: candidate.name,
199
- versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue),
250
+ versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
200
251
  };
201
252
  }
202
253
  return null;
package/dist/run.d.ts CHANGED
@@ -54,6 +54,55 @@ export interface SkippedGate {
54
54
  reason: 'no-contract' | 'contract-waived';
55
55
  detail: string;
56
56
  }
57
+ /**
58
+ * One control input this pull request proposes to change.
59
+ *
60
+ * A statement about CONFIGURATION, never a finding. It carries no severity,
61
+ * no fingerprint and no blocking flag, it is not in `findings`, and nothing
62
+ * here reaches the exit code: a pull request is allowed to propose changing
63
+ * the rules, and the whole of the mechanism is that the proposal does not
64
+ * take effect for the run that carries it. What it must do is be VISIBLE, so
65
+ * a reviewer meets "this pull request also proposes to loosen the gate" as
66
+ * one sentence beside the verdict.
67
+ *
68
+ * `line` is the sentence the gate that owns the control input wrote, carried
69
+ * verbatim. The umbrella writes only its own, about its own policy file.
70
+ */
71
+ export interface ControlProposal {
72
+ /** The gate that raised it, or the umbrella for its own policy file. */
73
+ product: Product | 'conductor';
74
+ /** The role that gate fills, or null for the umbrella's own. */
75
+ role: GateRole | null;
76
+ line: string;
77
+ }
78
+ /**
79
+ * Pull-request mode as the whole run saw it.
80
+ *
81
+ * `policyChanged` is decided in one place, before any gate runs, by comparing
82
+ * the policy file at the base ref with the one at the head commit. It is
83
+ * reported and never acted on: the base ref's policy is the one that ran.
84
+ */
85
+ export interface RunTrustBase {
86
+ /** The ref the umbrella took its own policy from. */
87
+ ref: string;
88
+ /** Whether the head commit's own policy file differs from that one. */
89
+ policyChanged: boolean;
90
+ /**
91
+ * Why this ref could not be used at all, or null when it was.
92
+ *
93
+ * A SEPARATE FIELD RATHER THAN AN ABSENT `trustBase`, and it is load-bearing
94
+ * in both renderers. A refusal is the worst outcome this tool has -- nothing
95
+ * was checked, on a run that was supposed to be the gate -- and it has to be
96
+ * the first thing a reader meets rather than something inferred from an exit
97
+ * code. Both reports used to work the number of gates out first, and an
98
+ * inventory naming no gate (every gate `enabled: false` in the head's file,
99
+ * or a head file that will not parse) then printed "no gate ran because none
100
+ * is enabled" in text and `{"runs": []}` in SARIF, with the refusal sentence
101
+ * nowhere. That is reachable on the DEFAULT actions/checkout, which fetches
102
+ * depth 1 and so carries no base ref.
103
+ */
104
+ refusal: string | null;
105
+ }
57
106
  export interface RunResult {
58
107
  schemaVersion: 1;
59
108
  generatedAt: string;
@@ -70,6 +119,14 @@ export interface RunResult {
70
119
  * consumer reads one list instead of three.
71
120
  */
72
121
  findings: Finding[];
122
+ /** Present only on a pull-request run; null means ordinary mode. */
123
+ trustBase: RunTrustBase | null;
124
+ /**
125
+ * Every control input this pull request proposes to change, the umbrella's
126
+ * own policy file first and then each gate's, in gate order. Empty outside
127
+ * pull-request mode, and empty inside it when nothing was proposed.
128
+ */
129
+ proposals: ControlProposal[];
73
130
  summary: {
74
131
  blocking: number;
75
132
  byProduct: Record<string, number>;
@@ -91,6 +148,14 @@ export interface RunOptions {
91
148
  base?: string;
92
149
  /** An explicit spec for the intent gate, outranking every other source. */
93
150
  spec?: string;
151
+ /**
152
+ * Pull-request mode. The policy this run was handed was ALREADY read from
153
+ * this ref by the caller: `runAll` does not read it, because the policy has
154
+ * to be parsed before there is a run to configure. What this carries is the
155
+ * ref, so it can be passed down to every child that can take it, and the
156
+ * one fact the caller established while reading it.
157
+ */
158
+ trustBase?: RunTrustBase;
94
159
  /**
95
160
  * The environment the pull-request defaults are read from.
96
161
  *
@@ -111,4 +176,31 @@ export interface RunOptions {
111
176
  */
112
177
  tempRoot?: string;
113
178
  }
179
+ /**
180
+ * The run that never happened, because the trust base could not be judged
181
+ * against.
182
+ *
183
+ * EVERY ENABLED GATE IS COULD-NOT-RUN, which is the fail-closed half of
184
+ * pull-request mode. A base ref that will not resolve is not a reason to fall
185
+ * back to the head's policy: falling back to the head is the behaviour this
186
+ * release removes, and it would be reachable by anybody who could make the
187
+ * base ref unfetchable.
188
+ *
189
+ * TWO THINGS HERE ARE DELIBERATELY NOT READ OFF THE POLICY, and both are the
190
+ * point rather than shortcuts. The policy handed in is the HEAD's, used only
191
+ * as an inventory so the report can name the gates that did not run; it
192
+ * cannot be trusted, so:
193
+ *
194
+ * - Every synthesized outcome is ENFORCED, whatever the file says. The
195
+ * `enforce` flag is itself a control input, and the file it lives in is
196
+ * the one that could not be read from the base. A head policy setting
197
+ * `enforce: false` everywhere must not be able to turn this into exit 0.
198
+ * - The exit code is written here rather than composed. A head policy
199
+ * enabling NO gate at all would otherwise compose to 0 over an empty list,
200
+ * which would report a run that checked nothing as a clean one.
201
+ */
202
+ export declare function refusedTrustBase(policy: Policy, ref: string, detail: string, options: {
203
+ stage?: GateStage;
204
+ now?: () => Date;
205
+ }): RunResult;
114
206
  export declare function runAll(policy: Policy, options: RunOptions): RunResult;