@vaultcompass/conductor 0.2.3 → 0.3.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,55 @@ 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 pull-request-mode block of the full report.
250
+ *
251
+ * Three things in one place, because they answer one question between them:
252
+ * 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.
254
+ */
255
+ function trustBaseLines(result) {
256
+ if (result.trustBase === null) {
257
+ return [];
258
+ }
259
+ const lines = [
260
+ ` pull-request mode: rules from ${result.trustBase.ref}. ${proposalCount(result)}.`,
261
+ ];
262
+ for (const proposal of result.proposals) {
263
+ lines.push(` proposed ${proposal.product.padEnd(13)} ${proposal.line}`);
264
+ }
265
+ for (const { gate, reason } of withheldTrustBase(result)) {
266
+ lines.push(` NOT in pull-request mode ${gate.role} ${gate.product} ${reason}`);
267
+ }
268
+ return lines;
269
+ }
221
270
  /**
222
271
  * What an unenforced gate did, as clauses for a verdict line.
223
272
  *
@@ -244,7 +293,39 @@ function unenforcedClauses(result) {
244
293
  }
245
294
  return clauses;
246
295
  }
296
+ /**
297
+ * The refusal, as the first line of the report and as the verdict.
298
+ *
299
+ * FIRST, and before any question about how many gates there are. The old
300
+ * order asked that question first, and an inventory naming no gate -- every
301
+ * gate `enabled: false` in the head's file, or a head file that will not
302
+ * parse -- fell into the "no gate ran because none is enabled" branch, which
303
+ * printed exit 0 and told the reader to switch a gate on while the process
304
+ * exited 2 and nothing had been checked. The refusal is the whole story of
305
+ * such a run and there is no arrangement of the other clauses that tells it.
306
+ */
307
+ function refusalLines(result) {
308
+ const refusal = result.trustBase?.refusal;
309
+ if (refusal === undefined || refusal === null) {
310
+ return [];
311
+ }
312
+ return [
313
+ `conductor: refused the trust base "${result.trustBase?.ref ?? ''}". Nothing was checked.`,
314
+ ` ${refusal}`,
315
+ ];
316
+ }
247
317
  function verdict(result) {
318
+ const refusal = result.trustBase?.refusal;
319
+ if (refusal !== undefined && refusal !== null) {
320
+ // Written rather than composed, exactly as the exit code is: no gate ran,
321
+ // so there is nothing for the clauses below to count, and every one of
322
+ // them would describe a different run from the one that happened.
323
+ return (`verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
324
+ 'so no gate ran and nothing here is a result of any kind.');
325
+ }
326
+ return verdictForRun(result);
327
+ }
328
+ function verdictForRun(result) {
248
329
  // Counted over ENFORCED gates only. The exit code came from those alone,
249
330
  // so a count taken over all of them describes a different run from the one
250
331
  // the number at the front of the line is about, and the umbrella's own
@@ -417,9 +498,15 @@ function summaryLine(result) {
417
498
  // is the easiest of the three to lose: a --gate run is usually somebody
418
499
  // narrowing a run on purpose, and a log of it that says nothing about the
419
500
  // narrowing is the log that gets uploaded and read as a full run later.
501
+ // Counted even at zero for the same suppression reason as the enforcement
502
+ // count above: a gate the command line dropped had no vote, and "0 gate(s)
503
+ // left out by --gate" says the run was not narrowed.
420
504
  if (result.excluded.length > 0) {
421
505
  const names = result.excluded.map((gate) => `${gate.role} (${gate.product})`).join(', ');
422
- parts.push(`Left out by --gate: ${names}.`);
506
+ parts.push(`${result.excluded.length} gate(s) left out by --gate: ${names}.`);
507
+ }
508
+ else {
509
+ parts.push('0 gate(s) left out by --gate.');
423
510
  }
424
511
  // A gate that ran with enforce: false could not have failed this run
425
512
  // whatever it found. Naming it among the gates that ran and then saying
@@ -428,10 +515,19 @@ function summaryLine(result) {
428
515
  // full report says this in the line under that gate's findings; on a clean
429
516
  // run there are no findings, so the summary line is the only place left to
430
517
  // say it.
518
+ //
519
+ // Printed as a count even when it is zero. This is the family suppression
520
+ // rule: a gate that can be turned off is the user's decision, and a clean
521
+ // line that says nothing about enforcement lets a repository read as fully
522
+ // gated when a gate's result did not move the exit code. "0 gate(s) not
523
+ // enforced" is the umbrella saying every gate that ran had a vote.
431
524
  const unenforced = result.gates.filter((gate) => !gate.enforce);
432
525
  if (unenforced.length > 0) {
433
526
  const names = unenforced.map((gate) => `${gate.role} (${gate.product})`).join(', ');
434
- parts.push(`Could not have blocked, enforce: false in .guardrails.yaml: ${names}.`);
527
+ parts.push(`${unenforced.length} gate(s) not enforced, could not have blocked, enforce: false in .guardrails.yaml: ${names}.`);
528
+ }
529
+ else {
530
+ parts.push('0 gate(s) not enforced.');
435
531
  }
436
532
  // Non-blocking findings are counted rather than hidden, for the same reason
437
533
  // the full report prints the suppressed and ignored counts at zero: they
@@ -448,11 +544,40 @@ function summaryLine(result) {
448
544
  if (counts.length > 0) {
449
545
  parts.push(`${counts.join(', ')}.`);
450
546
  }
547
+ // The suppressed and ignored counts the gates reported, summed across them
548
+ // and printed even at zero. The full report prints these per gate for the
549
+ // same reason, so a quiet report is not mistaken for a clean one; the clean
550
+ // summary line is the one a hook and a pull request comment actually print,
551
+ // and it is where a repository baselining findings without saying so would
552
+ // otherwise read as clean. Suppressed always shows because it is always a
553
+ // number the gate reported. Ignored shows only when every gate that ran
554
+ // reported it: a gate that drops ignored files before its own output has no
555
+ // count to give, and "0 ignored" there would state a fact no gate stated.
556
+ const suppressed = result.gates.reduce((total, gate) => total + gate.run.suppressed, 0);
557
+ const gatesReportingIgnored = result.gates.filter((gate) => gate.run.details.ignoredReported !== false);
558
+ const ignored = gatesReportingIgnored.reduce((total, gate) => total + gate.run.ignored, 0);
559
+ parts.push(gatesReportingIgnored.length === result.gates.length
560
+ ? `${suppressed} suppressed, ${ignored} ignored across all gates.`
561
+ : `${suppressed} suppressed across all gates.`);
562
+ // Pull-request mode, on the one line a hook and a pull request comment
563
+ // actually print. A clean run is exactly where this matters most: a pull
564
+ // request that proposes to switch a gate off and carries nothing else
565
+ // produces a clean report, and without this clause the only trace of the
566
+ // attempt would be in a file nobody re-reads.
567
+ if (result.trustBase !== null) {
568
+ parts.push(`Rules from ${result.trustBase.ref}. ${proposalCount(result)}.`);
569
+ const withheld = withheldTrustBase(result);
570
+ if (withheld.length > 0) {
571
+ const names = withheld.map(({ gate }) => `${gate.role} (${gate.product})`).join(', ');
572
+ parts.push(`${withheld.length} gate(s) NOT in pull-request mode: ${names}.`);
573
+ }
574
+ }
451
575
  parts.push('Re-run with --verbose for the full report.');
452
576
  return parts.join(' ');
453
577
  }
454
578
  export function renderText(result, options = {}) {
455
- if (!options.verbose && isFullyClean(result)) {
579
+ const refusal = refusalLines(result);
580
+ if (refusal.length === 0 && !options.verbose && isFullyClean(result)) {
456
581
  return `${summaryLine(result)}\n`;
457
582
  }
458
583
  // Counted over EVERY gate, unenforced ones included, and deliberately not
@@ -464,6 +589,8 @@ export function renderText(result, options = {}) {
464
589
  // different questions, so two numbers, and the section headers and the
465
590
  // "not enforced" lines are what connect them.
466
591
  const lines = [
592
+ ...refusal,
593
+ ...(refusal.length === 0 ? [] : ['']),
467
594
  `conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
468
595
  ];
469
596
  for (const gate of result.gates) {
@@ -473,6 +600,10 @@ export function renderText(result, options = {}) {
473
600
  if (aside.length > 0) {
474
601
  lines.push('', ...aside);
475
602
  }
603
+ const trust = trustBaseLines(result);
604
+ if (trust.length > 0) {
605
+ lines.push('', ...trust);
606
+ }
476
607
  // A derived severity is marked with a trailing asterisk above; say what
477
608
  // that means rather than leaving a reader to guess, and only when one is
478
609
  // 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;
package/dist/resolve.js CHANGED
@@ -170,6 +170,8 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
170
170
  if (!isExecutableFile(gate.command) && /\.(?:js|mjs|cjs)$/.test(gate.command)) {
171
171
  return {
172
172
  command: process.execPath,
173
+ // Node is the command; the script is what actually decides anything.
174
+ program: gate.command,
173
175
  argvPrefix: [gate.command, ...prefix],
174
176
  source: 'policy',
175
177
  candidate: candidateName,
@@ -180,6 +182,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
180
182
  }
181
183
  return {
182
184
  command: gate.command,
185
+ program: gate.command,
183
186
  argvPrefix: prefix,
184
187
  source: 'policy',
185
188
  candidate: candidateName,
@@ -193,6 +196,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue) {
193
196
  }
194
197
  return {
195
198
  command: found.command,
199
+ program: found.command,
196
200
  argvPrefix: [...candidate.prefix],
197
201
  source: found.source,
198
202
  candidate: candidate.name,
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;
package/dist/run.js CHANGED
@@ -1,11 +1,12 @@
1
1
  // One run across every enabled gate.
2
2
  import { compareFindings } from './envelope.js';
3
- import { composeExitCode } from './exit-codes.js';
3
+ import { EXIT_COULD_NOT_RUN, composeExitCode } from './exit-codes.js';
4
4
  import { preparationFailed, runGate } from './gate-runner.js';
5
5
  import { resolveBaseRef } from './intent-base.js';
6
- import { prepareIntent } from './intent-prepare.js';
6
+ import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
7
7
  import { GATE_ROLES, enabledGates, runsAtStage } from './policy.js';
8
8
  import { ResolveError, resolveGateBinary } from './resolve.js';
9
+ import { POLICY_PROPOSAL_LINE } from './trust-base.js';
9
10
  /**
10
11
  * Whether this run is the pull-request shaped one.
11
12
  *
@@ -36,13 +37,21 @@ function intentBinary(gate, options) {
36
37
  return null;
37
38
  }
38
39
  }
39
- export function runAll(policy, options) {
40
+ /**
41
+ * The three lists a stage filter and a `--gate` flag produce between them.
42
+ *
43
+ * Factored out because the trust-base refusal below needs the same partition:
44
+ * a run that could not read its policy from the base ref still has to report
45
+ * the gates it did not run and the stage each of them sits at, or the report
46
+ * of the most serious failure this tool has is thinner than the report of an
47
+ * ordinary one.
48
+ */
49
+ function partitionGates(policy, requested) {
40
50
  const enabled = enabledGates(policy);
41
51
  // Partitioned before anything is spawned, and before any binary is even
42
52
  // looked for: a gate that will not run at this stage must not be able to
43
53
  // fail the run by being uninstalled here. An intent gate that lives only
44
54
  // on the CI image is the ordinary case, not an error.
45
- const requested = options.stage;
46
55
  const gates = requested === undefined ? enabled : enabled.filter((gate) => runsAtStage(gate.stage, requested));
47
56
  const deferred = requested === undefined
48
57
  ? []
@@ -52,7 +61,100 @@ export function runAll(policy, options) {
52
61
  // Read off the policy rather than off the enabled list, because these gates
53
62
  // are exactly the ones the override took out of it. In role order, so a
54
63
  // report's ordering never depends on the order the flags were typed.
55
- const excluded = GATE_ROLES.map((role) => policy.gates[role]).filter((gate) => gate !== undefined && gate.excludedByCli).map((gate) => ({ role: gate.role, product: gate.product }));
64
+ const excluded = GATE_ROLES.map((role) => policy.gates[role])
65
+ .filter((gate) => gate !== undefined && gate.excludedByCli)
66
+ .map((gate) => ({ role: gate.role, product: gate.product }));
67
+ return { gates, deferred, excluded };
68
+ }
69
+ /**
70
+ * The run that never happened, because the trust base could not be judged
71
+ * against.
72
+ *
73
+ * EVERY ENABLED GATE IS COULD-NOT-RUN, which is the fail-closed half of
74
+ * pull-request mode. A base ref that will not resolve is not a reason to fall
75
+ * back to the head's policy: falling back to the head is the behaviour this
76
+ * release removes, and it would be reachable by anybody who could make the
77
+ * base ref unfetchable.
78
+ *
79
+ * TWO THINGS HERE ARE DELIBERATELY NOT READ OFF THE POLICY, and both are the
80
+ * point rather than shortcuts. The policy handed in is the HEAD's, used only
81
+ * as an inventory so the report can name the gates that did not run; it
82
+ * cannot be trusted, so:
83
+ *
84
+ * - Every synthesized outcome is ENFORCED, whatever the file says. The
85
+ * `enforce` flag is itself a control input, and the file it lives in is
86
+ * the one that could not be read from the base. A head policy setting
87
+ * `enforce: false` everywhere must not be able to turn this into exit 0.
88
+ * - The exit code is written here rather than composed. A head policy
89
+ * enabling NO gate at all would otherwise compose to 0 over an empty list,
90
+ * which would report a run that checked nothing as a clean one.
91
+ */
92
+ export function refusedTrustBase(policy, ref, detail, options) {
93
+ const { gates, deferred, excluded } = partitionGates(policy, options.stage);
94
+ const outcomes = gates.map((gate) => preparationFailed({ ...gate, enforce: true }, `the trust base could not be used: ${detail}`));
95
+ const findings = outcomes.flatMap((outcome) => outcome.findings).sort(compareFindings);
96
+ const byProduct = {};
97
+ const bySeverity = {};
98
+ for (const finding of findings) {
99
+ byProduct[finding.product] = (byProduct[finding.product] ?? 0) + 1;
100
+ bySeverity[finding.severity] = (bySeverity[finding.severity] ?? 0) + 1;
101
+ }
102
+ return {
103
+ schemaVersion: 1,
104
+ generatedAt: (options.now?.() ?? new Date()).toISOString(),
105
+ gates: outcomes,
106
+ deferred,
107
+ skipped: [],
108
+ excluded,
109
+ findings,
110
+ // policyChanged is unknowable: the base side of the comparison is the
111
+ // thing that could not be read. False rather than a third state, because
112
+ // no proposal is reported on a run where nothing was judged. The refusal
113
+ // itself is carried, and it is what both renderers lead with.
114
+ trustBase: { ref, policyChanged: false, refusal: detail },
115
+ proposals: [],
116
+ summary: {
117
+ blocking: findings.filter((finding) => finding.blocking).length,
118
+ byProduct,
119
+ bySeverity,
120
+ },
121
+ exitCode: EXIT_COULD_NOT_RUN,
122
+ };
123
+ }
124
+ /**
125
+ * Every proposed control change, the umbrella's own policy first.
126
+ *
127
+ * The umbrella's line comes first because it is the one that decides what the
128
+ * others even are: a pull request that rewrites `.guardrails.yaml` is
129
+ * proposing to change which gates run at all, and reading that after a gate's
130
+ * own contract line would bury it.
131
+ */
132
+ function collectProposals(outcomes, trustBase) {
133
+ const proposals = [];
134
+ if (trustBase?.policyChanged === true) {
135
+ proposals.push({ product: 'conductor', role: null, line: POLICY_PROPOSAL_LINE });
136
+ }
137
+ for (const outcome of outcomes) {
138
+ for (const line of outcome.trustBase?.proposals ?? []) {
139
+ proposals.push({ product: outcome.product, role: outcome.role, line });
140
+ }
141
+ }
142
+ return proposals;
143
+ }
144
+ /**
145
+ * The `intentContract` option for a run with no preparation, or nothing.
146
+ *
147
+ * A small helper rather than an inline conditional because the spread at the
148
+ * call site is already three lines, and because "nothing" has to be an empty
149
+ * object rather than an undefined property: the option is optional and
150
+ * `exactOptionalPropertyTypes` refuses an explicit undefined.
151
+ */
152
+ function nativeContractOption(repoRoot) {
153
+ const contract = frozenNativeContractPath(repoRoot);
154
+ return contract === null ? {} : { intentContract: contract };
155
+ }
156
+ export function runAll(policy, options) {
157
+ const { gates, deferred, excluded } = partitionGates(policy, options.stage);
56
158
  const env = options.env ?? {};
57
159
  const skipped = [];
58
160
  const cleanups = [];
@@ -104,6 +206,16 @@ export function runAll(policy, options) {
104
206
  pathValue: options.pathValue,
105
207
  ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
106
208
  ...(intent === undefined ? {} : { intent }),
209
+ // For a run with no preparation: which contract the child will read
210
+ // out of the repository itself. Looked up only for the gate it is
211
+ // about, so no other gate pays for the two stat calls.
212
+ ...(intent !== undefined || gate.role !== 'intent'
213
+ ? {}
214
+ : nativeContractOption(options.repoRoot)),
215
+ // Offered to every child. runGate decides which ones can take it,
216
+ // so a gate with no pull-request mode yet is not handed a flag it
217
+ // would reject, and the reason it was withheld is on the outcome.
218
+ ...(options.trustBase === undefined ? {} : { trustBase: options.trustBase.ref }),
107
219
  }));
108
220
  }
109
221
  }
@@ -138,6 +250,8 @@ export function runAll(policy, options) {
138
250
  skipped,
139
251
  excluded,
140
252
  findings,
253
+ trustBase: options.trustBase ?? null,
254
+ proposals: collectProposals(outcomes, options.trustBase),
141
255
  summary: {
142
256
  blocking: findings.filter((finding) => finding.blocking).length,
143
257
  byProduct,