@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.
@@ -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
  *
@@ -17,8 +17,21 @@ export declare function normalizeVaultGuard(raw: unknown, version: string | null
17
17
  * interpolates an error message, and they are enumerated in a test against
18
18
  * the real strings, so an upstream rewording turns that test red instead of
19
19
  * silently dropping a reason out of every report.
20
+ *
21
+ * THE NO-CONTRACT SENTENCE INTERPOLATES THE STATE DIRECTORY NAME, so it has
22
+ * two spellings and needs two entries. The gate builds it as
23
+ * `No ${STATE_DIR}/intent-contract.yaml found.`, and 1.3.0 renamed STATE_DIR
24
+ * from `.conductor` to `.intent-guard`. Matching only the old name left this
25
+ * classifier DEAD against every gate anybody can install today: the reason
26
+ * fell through to the unattributed backstop, so the finding said
27
+ * `kind: unattributed` where a consumer filters on `contract-missing`, and a
28
+ * run that also had a budget violation dropped the no-contract reason out of
29
+ * the report entirely, since the backstop only fires when nothing else
30
+ * blocked. Both names stay, because the umbrella reads both state
31
+ * directories elsewhere and a repository on either version has to be
32
+ * classified the same way.
20
33
  */
21
- export declare const GATE_STATE_REASON_KINDS: readonly ["contract-invalid", "contract-missing", "contract-unfrozen"];
34
+ export declare const GATE_STATE_REASON_KINDS: readonly ["contract-invalid", "contract-missing", "contract-unfrozen", "self-approval-refused", "control-input-refused"];
22
35
  export type GateStateReasonKind = (typeof GATE_STATE_REASON_KINDS)[number];
23
36
  /** Which gate-state reason this is, or null when it is a budget or drift reason. */
24
37
  export declare function classifyGateStateReason(reason: string): GateStateReasonKind | null;
package/dist/normalize.js CHANGED
@@ -117,6 +117,7 @@ export function normalizeDepGuard(raw, version) {
117
117
  const root = needRecord(raw, product, 'the output');
118
118
  const run = needRecord(root.run, product, 'run');
119
119
  const threshold = optionalString(run.failOn, product, 'run.failOn') ?? null;
120
+ const trustBase = readTrustBase(root.trustBase, product);
120
121
  const diagnostics = [];
121
122
  const findings = needArray(root.findings, product, 'findings').map((entry, index) => {
122
123
  const where = `findings[${index}]`;
@@ -154,6 +155,11 @@ export function normalizeDepGuard(raw, version) {
154
155
  reconcileBlocking(findings, typeof run.blockingMatches === 'number' ? run.blockingMatches : undefined, threshold, product, diagnostics);
155
156
  return {
156
157
  findings,
158
+ // Third gate, same key, same two fields read. dep-guard carries three
159
+ // changed flags and three shape changes, one pair about .npmrc, which
160
+ // the other two have no equivalent of; none of it is read here. The
161
+ // sentences are that gate's claims about its own control files.
162
+ ...(trustBase === undefined ? {} : { trustBase }),
157
163
  run: {
158
164
  failOn: threshold,
159
165
  suppressed: typeof root.suppressed === 'number' ? root.suppressed : 0,
@@ -180,6 +186,7 @@ export function normalizeVaultGuard(raw, version) {
180
186
  // because the latter ignores the threshold. A sibling tool in this family
181
187
  // read summary.secrets and that is the bug not to copy.
182
188
  const threshold = optionalString(run.fail_on, product, 'run.fail_on') ?? null;
189
+ const trustBase = readTrustBase(root.trustBase, product);
183
190
  const diagnostics = [];
184
191
  const findings = [];
185
192
  const results = needArray(root.results, product, 'results');
@@ -265,6 +272,14 @@ export function normalizeVaultGuard(raw, version) {
265
272
  reconcileBlocking(findings, typeof run.blocking_matches === 'number' ? run.blocking_matches : undefined, threshold, product, diagnostics);
266
273
  return {
267
274
  findings,
275
+ // vault-guard 1.7.0 puts its pull-request summary at the TOP LEVEL, the
276
+ // same place intent-guard puts its own, and carries more fields than the
277
+ // umbrella reads (configChanged, baselineChanged, and a shape change for
278
+ // each). Only `ref` and `proposals` are read, which is the passthrough
279
+ // rule applied to a second gate: the sentences are that gate's claims
280
+ // about its own control files, and this package has no standing to
281
+ // rewrite them or to act on the structured half.
282
+ ...(trustBase === undefined ? {} : { trustBase }),
268
283
  run: {
269
284
  failOn: threshold,
270
285
  suppressed: typeof run.baseline_suppressed === 'number' ? run.baseline_suppressed : 0,
@@ -329,16 +344,49 @@ const DRIFT_SEVERITY = {
329
344
  * interpolates an error message, and they are enumerated in a test against
330
345
  * the real strings, so an upstream rewording turns that test red instead of
331
346
  * silently dropping a reason out of every report.
347
+ *
348
+ * THE NO-CONTRACT SENTENCE INTERPOLATES THE STATE DIRECTORY NAME, so it has
349
+ * two spellings and needs two entries. The gate builds it as
350
+ * `No ${STATE_DIR}/intent-contract.yaml found.`, and 1.3.0 renamed STATE_DIR
351
+ * from `.conductor` to `.intent-guard`. Matching only the old name left this
352
+ * classifier DEAD against every gate anybody can install today: the reason
353
+ * fell through to the unattributed backstop, so the finding said
354
+ * `kind: unattributed` where a consumer filters on `contract-missing`, and a
355
+ * run that also had a budget violation dropped the no-contract reason out of
356
+ * the report entirely, since the backstop only fires when nothing else
357
+ * blocked. Both names stay, because the umbrella reads both state
358
+ * directories elsewhere and a repository on either version has to be
359
+ * classified the same way.
332
360
  */
333
361
  export const GATE_STATE_REASON_KINDS = [
334
362
  'contract-invalid',
335
363
  'contract-missing',
336
364
  'contract-unfrozen',
365
+ /**
366
+ * The two pull-request-mode refusals, from intent-guard 1.4.0.
367
+ *
368
+ * They are here rather than left to the backstop for the reason the whole
369
+ * list exists. The backstop fires only when NOTHING ELSE BLOCKED, so a pull
370
+ * request that forged a contract approval AND breached a change budget
371
+ * reported only the budget breach: the run still failed, but the report
372
+ * never said the approval was self-granted, which is the single most
373
+ * important sentence pull-request mode produces. Found by running the real
374
+ * gate against a crafted pull request rather than by reading the code.
375
+ */
376
+ 'self-approval-refused',
377
+ 'control-input-refused',
337
378
  ];
338
379
  const GATE_STATE_REASON_PREFIXES = [
339
380
  ['Intent contract is invalid:', 'contract-invalid'],
381
+ ['No .intent-guard/intent-contract.yaml found', 'contract-missing'],
340
382
  ['No .conductor/intent-contract.yaml found', 'contract-missing'],
341
383
  ['Intent contract exists but is not frozen', 'contract-unfrozen'],
384
+ // Copied from intent-guard's own trust-base.ts, where both are exported
385
+ // constants for exactly this: SELF_APPROVAL_REASON_PREFIX and
386
+ // CONTROL_INPUT_REASON_PREFIX. Prefixes, because each interpolates the ref
387
+ // and the path.
388
+ ['Self-approval refused:', 'self-approval-refused'],
389
+ ['Control input refused:', 'control-input-refused'],
342
390
  ];
343
391
  /** Which gate-state reason this is, or null when it is a budget or drift reason. */
344
392
  export function classifyGateStateReason(reason) {
@@ -349,12 +397,39 @@ export function classifyGateStateReason(reason) {
349
397
  }
350
398
  return null;
351
399
  }
400
+ /**
401
+ * The pull-request-mode summary intent-guard 1.4.0 puts on its check output,
402
+ * or undefined when the run was not in pull-request mode.
403
+ *
404
+ * ABSENCE IS THE SIGNAL, and it is the gate's own: the field is present only
405
+ * on a run that was given `--trust-base`, so an ordinary run has nothing here
406
+ * and no report has to guess. Validated element by element like everything
407
+ * else, because a malformed proposal reaching String() would put
408
+ * "[object Object]" on the one line a reviewer reads.
409
+ *
410
+ * The proposal SENTENCES are the gate's, carried verbatim and never
411
+ * rewritten. Every one of them is a claim about that gate's own control
412
+ * files, which the umbrella does not read and has no standing to describe.
413
+ */
414
+ function readTrustBase(raw, product) {
415
+ if (raw === undefined || raw === null) {
416
+ return undefined;
417
+ }
418
+ const record = needRecord(raw, product, 'trustBase');
419
+ return {
420
+ ref: needString(record.ref, product, 'trustBase.ref'),
421
+ proposals: record.proposals === undefined
422
+ ? []
423
+ : needStringArray(record.proposals, product, 'trustBase.proposals'),
424
+ };
425
+ }
352
426
  export function normalizeIntentGuard(raw, version) {
353
427
  const product = 'intent-guard';
354
428
  const root = needRecord(raw, product, 'the output');
355
429
  if (root.status !== 'blocked' && root.status !== 'ok') {
356
430
  fail(product, 'status', 'either "ok" or "blocked"');
357
431
  }
432
+ const trustBase = readTrustBase(root.trustBase, product);
358
433
  const findings = [];
359
434
  const budget = root.budget === undefined ? undefined : needRecord(root.budget, product, 'budget');
360
435
  const drift = root.drift === undefined ? undefined : needRecord(root.drift, product, 'drift');
@@ -492,6 +567,7 @@ export function normalizeIntentGuard(raw, version) {
492
567
  }
493
568
  return {
494
569
  findings,
570
+ ...(trustBase === undefined ? {} : { trustBase }),
495
571
  run: {
496
572
  // intent-guard has no threshold flag and no reported threshold: its
497
573
  // drift thresholds live in its own config file and its budget rules
@@ -1,3 +1,4 @@
1
+ import type { GateOutcome } from './gate-runner.js';
1
2
  import type { RunResult } from './run.js';
2
3
  export declare const UMBRELLA_DRIVER_NAME = "conductor";
3
4
  /** The partialFingerprints key for a product's own fingerprint. */
@@ -24,6 +25,16 @@ export type ArtifactPlacement =
24
25
  * through a whole rendered log.
25
26
  */
26
27
  export declare function placeArtifact(rawPath: string): ArtifactPlacement;
28
+ /**
29
+ * The file a result with no location of its own is filed against.
30
+ *
31
+ * A real, repository-relative path, never a placeholder: the policy file is
32
+ * where every gate is enabled and where a reader goes to change what ran, and
33
+ * for the intent gate the frozen contract is the file its gate-state findings
34
+ * are literally about. Both exist in the repository whenever a run happened at
35
+ * all, so this never points at nothing.
36
+ */
37
+ export declare function fallbackLocationFor(gate: GateOutcome | null): string;
27
38
  /**
28
39
  * Renders a whole run as one SARIF log.
29
40
  *
@@ -88,6 +88,24 @@
88
88
  // Everything genuinely inside keeps the relative, forward-slashed,
89
89
  // `%SRCROOT%`-based spelling that GitHub code scanning wants.
90
90
  //
91
+ // - EVERY RESULT CARRIES AT LEAST ONE LOCATION, and the fallback is a real
92
+ // file rather than an invented one. GitHub code scanning rejects a whole
93
+ // uploaded log with "locationFromSarifResult: expected at least one
94
+ // location" the moment any single result has none, so one location-less
95
+ // result loses the entire report rather than one alert. That happened on
96
+ // every main-branch run of a sibling repository's guardrails job, and the
97
+ // offender was `intent-guard/gate-blocked`, whose subject is `none`.
98
+ //
99
+ // This does NOT weaken the two rules above it. A location the gate gave is
100
+ // never overwritten, no region is invented, and no path is fabricated: the
101
+ // fallback is the CONTROL FILE this result is a statement about, which is
102
+ // a file that exists in the repository and is the one a reader would open.
103
+ // For the umbrella's own results and for the two gates whose control files
104
+ // the umbrella does not read, that is the policy file, which is where the
105
+ // gate that produced the result is enabled. For the intent gate it is the
106
+ // frozen contract, when the run recorded which of the two state
107
+ // directories answered.
108
+ //
91
109
  // - A REGION ONLY WHEN A REAL POSITION IS KNOWN. One of the three gates
92
110
  // reports a line and a column; the other two report no position at all.
93
111
  // An invented startLine annotates an unrelated line of somebody's file
@@ -99,6 +117,7 @@
99
117
  // normalize.ts, which is where the omission would stop mattering if the
100
118
  // field were ever carried.
101
119
  import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
120
+ import { POLICY_FILE_NAME } from './policy.js';
102
121
  const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
103
122
  export const UMBRELLA_DRIVER_NAME = 'conductor';
104
123
  /**
@@ -242,7 +261,41 @@ function locationsFor(finding) {
242
261
  return undefined;
243
262
  }
244
263
  }
245
- function toResult(finding) {
264
+ /**
265
+ * The file a result with no location of its own is filed against.
266
+ *
267
+ * A real, repository-relative path, never a placeholder: the policy file is
268
+ * where every gate is enabled and where a reader goes to change what ran, and
269
+ * for the intent gate the frozen contract is the file its gate-state findings
270
+ * are literally about. Both exist in the repository whenever a run happened at
271
+ * all, so this never points at nothing.
272
+ */
273
+ export function fallbackLocationFor(gate) {
274
+ const source = gate?.intent?.contractSource;
275
+ if (source !== undefined && source.kind === 'native') {
276
+ return source.path;
277
+ }
278
+ return POLICY_FILE_NAME;
279
+ }
280
+ /**
281
+ * The locations for one result, with the fallback filled in where a real one
282
+ * is missing.
283
+ *
284
+ * TWO SEPARATE CASES, and conflating them would lose information. A finding
285
+ * with no locations at all gets one made of the fallback. A finding that has
286
+ * a LOGICAL location and no physical one (a drift finding's contract
287
+ * category, a package whose manifest could not be placed) keeps the logical
288
+ * one and gains the physical fallback beside it, because the logical location
289
+ * is what a consumer groups on and replacing it would drop that.
290
+ */
291
+ function withFallbackLocation(locations, fallbackUri) {
292
+ const physicalLocation = { artifactLocation: { uri: fallbackUri, uriBaseId: '%SRCROOT%' } };
293
+ if (locations === undefined || locations.length === 0) {
294
+ return [{ physicalLocation }];
295
+ }
296
+ return locations.map((location) => location.physicalLocation === undefined ? { ...location, physicalLocation } : location);
297
+ }
298
+ function toResult(finding, fallbackUri) {
246
299
  // A path that escapes the source root gets no physical location, so the
247
300
  // path itself is carried here instead. Dropping a location is honest;
248
301
  // dropping the information as well would just lose the finding's subject.
@@ -265,10 +318,9 @@ function toResult(finding) {
265
318
  if (finding.fingerprint !== null) {
266
319
  entry.partialFingerprints = { [fingerprintKey(finding.fingerprint.scope)]: finding.fingerprint.value };
267
320
  }
268
- const locations = locationsFor(finding);
269
- if (locations !== undefined) {
270
- entry.locations = locations;
271
- }
321
+ // Unconditional. The old code omitted the key when there was nothing
322
+ // honest to say, and one such result makes GitHub reject the whole log.
323
+ entry.locations = withFallbackLocation(locationsFor(finding), fallbackUri);
272
324
  return entry;
273
325
  }
274
326
  function ruleDeclarations(findings) {
@@ -286,10 +338,7 @@ function toNotification(notification) {
286
338
  // filed under when it was a result, so a consumer that had rules for
287
339
  // these still recognises them.
288
340
  descriptor: { id: notification.id },
289
- // Note, always. A statement about coverage is never an error about the
290
- // code, and a notification that arrived as a warning would push these
291
- // straight back into the alert list they were moved out of.
292
- level: 'note',
341
+ level: notification.level ?? 'note',
293
342
  message: { text: notification.message },
294
343
  properties: { details: notification.details },
295
344
  };
@@ -298,7 +347,9 @@ function notificationDeclarations(notifications) {
298
347
  const ids = [...new Set(notifications.map((notification) => notification.id))].sort();
299
348
  return ids.map((id) => ({ id, name: id.slice(id.indexOf('/') + 1) }));
300
349
  }
301
- function makeRun(name, version, findings, properties, invocation) {
350
+ function makeRun(name, version, findings,
351
+ /** The artifact a result with no location of its own is filed against. */
352
+ fallbackUri, properties, invocation) {
302
353
  const notifications = invocation?.notifications ?? [];
303
354
  return {
304
355
  tool: {
@@ -316,7 +367,7 @@ function makeRun(name, version, findings, properties, invocation) {
316
367
  : { notifications: notificationDeclarations(notifications) }),
317
368
  },
318
369
  },
319
- results: findings.map(toResult),
370
+ results: findings.map((finding) => toResult(finding, fallbackUri)),
320
371
  ...(invocation === undefined
321
372
  ? {}
322
373
  : {
@@ -500,6 +551,141 @@ function skippedNotifications(result) {
500
551
  details: { role: gate.role, product: gate.product, reason: gate.reason },
501
552
  }));
502
553
  }
554
+ /**
555
+ * The control inputs this pull request proposes to change, as notifications.
556
+ *
557
+ * A NOTIFICATION and never a result, decided by the rule at
558
+ * skippedNotifications below rather than by a fresh judgment. A proposed
559
+ * control change is a statement about CONFIGURATION in the purest form that
560
+ * rule describes: nothing went wrong, nobody's code is at fault, the
561
+ * proposal did not take effect, and it is true of every run of this pull
562
+ * request until it merges or the file is reverted. As a result it would be a
563
+ * fingerprint-less alert reappearing on every push to the branch, which is
564
+ * how a code scanning tab becomes something nobody reads.
565
+ *
566
+ * The id is the UMBRELLA'S, even for a line a gate wrote, and that is a
567
+ * deliberate departure from skippedNotifications, which uses the gate's
568
+ * namespace. The statement here is the umbrella's summing: it is the one
569
+ * place a reviewer sees that a pull request tried to change three gates'
570
+ * rules at once, which is the sentence the whole wave exists to produce. The
571
+ * gate that raised each line is in the details.
572
+ */
573
+ function proposalNotifications(result) {
574
+ return result.proposals.map((proposal) => ({
575
+ id: 'conductor/control-change-proposed',
576
+ message: `This pull request proposes a control change that did NOT take effect for this run: ` +
577
+ `${proposal.line} (${proposal.product}). The rules came from ` +
578
+ `${result.trustBase?.ref ?? 'the base ref'}; the proposed change decides what runs once ` +
579
+ 'it is on the base branch.',
580
+ details: {
581
+ product: proposal.product,
582
+ role: proposal.role,
583
+ proposal: proposal.line,
584
+ ref: result.trustBase?.ref ?? null,
585
+ },
586
+ }));
587
+ }
588
+ /**
589
+ * The trust base the umbrella refused, when it refused one.
590
+ *
591
+ * ERROR LEVEL, and the only notification here that is not a note. Every other
592
+ * one says how much of the policy a run covered; this one says the run did
593
+ * not happen. It is the one statement in this file that a reader must not be
594
+ * able to scroll past.
595
+ *
596
+ * A NOTIFICATION rather than a result even so, and the reason is the
597
+ * discriminator further down: a result is about a place in somebody's code,
598
+ * and this is about a ref. The could-not-run RESULTS for whatever gates the
599
+ * inventory named sit beside it in the same run and carry the same sentence,
600
+ * so a consumer that reads only results still learns that nothing ran.
601
+ */
602
+ function trustBaseRefusedNotifications(result) {
603
+ const refusal = result.trustBase?.refusal;
604
+ if (refusal === undefined || refusal === null) {
605
+ return [];
606
+ }
607
+ return [
608
+ {
609
+ id: 'conductor/trust-base-refused',
610
+ level: 'error',
611
+ message: `conductor refused the trust base "${result.trustBase?.ref ?? ''}", so no gate ran and ` +
612
+ `NOTHING WAS CHECKED by this run. ${refusal}`,
613
+ details: { ref: result.trustBase?.ref ?? null, reason: refusal },
614
+ },
615
+ ];
616
+ }
617
+ /**
618
+ * The gates whose PROGRAM the umbrella refused to run.
619
+ *
620
+ * ERROR level, beside the refused trust base and for the same reason: this is
621
+ * not a statement about how much of the policy a run covered. A pull request
622
+ * put a file where the gate's binary resolves and the umbrella declined to
623
+ * execute it, which a reviewer has to meet rather than scroll past.
624
+ *
625
+ * The gate's could-not-run RESULT carries the same sentence, so a consumer
626
+ * reading only results still learns the gate did not run. This adds the
627
+ * structured half: which gate, which program, and which ref it was measured
628
+ * against.
629
+ */
630
+ function programRefusedNotifications(result) {
631
+ return result.gates.flatMap((gate) => {
632
+ if (gate.couldNotRun?.reason !== 'gate-program-refused') {
633
+ return [];
634
+ }
635
+ return [
636
+ {
637
+ id: 'conductor/gate-program-refused',
638
+ level: 'error',
639
+ message: `The ${gate.role} gate (${gate.product}) did NOT run: its program is a file this pull ` +
640
+ `request controls, so running it would let the pull request choose the program that ` +
641
+ `judges it. ${gate.couldNotRun.detail}`,
642
+ details: {
643
+ role: gate.role,
644
+ product: gate.product,
645
+ program: gate.binary?.program ?? null,
646
+ ref: gate.trustBase?.ref ?? null,
647
+ reason: gate.couldNotRun.detail,
648
+ },
649
+ },
650
+ ];
651
+ });
652
+ }
653
+ /**
654
+ * The gates the umbrella could not put into pull-request mode.
655
+ *
656
+ * The loud half of the same mode, and by the discriminator below it is a
657
+ * close call that lands on notification: nothing went wrong with the run, and
658
+ * the fact is true of the configuration (an older gate is installed) rather
659
+ * than of this change, so it is identical on every run until somebody
660
+ * upgrades. What it says is how much of the pull-request boundary this run
661
+ * actually had, which is a coverage statement.
662
+ *
663
+ * It is still the most important notification in the log. A gate here read
664
+ * its own control inputs out of the tree under judgment.
665
+ */
666
+ function trustBaseWithheldNotifications(result) {
667
+ return result.gates.flatMap((gate) => {
668
+ const withheld = gate.trustBase?.withheld;
669
+ if (withheld === undefined || withheld === null) {
670
+ return [];
671
+ }
672
+ return [
673
+ {
674
+ id: 'conductor/trust-base-not-passed',
675
+ message: `The ${gate.role} gate (${gate.product}) did NOT run in pull-request mode, so it read ` +
676
+ `its own control inputs from the tree being judged rather than from ` +
677
+ `${gate.trustBase?.ref ?? 'the base ref'}. ${withheld}`,
678
+ details: {
679
+ role: gate.role,
680
+ product: gate.product,
681
+ productVersion: gate.productVersion,
682
+ ref: gate.trustBase?.ref ?? null,
683
+ reason: withheld,
684
+ },
685
+ },
686
+ ];
687
+ });
688
+ }
503
689
  /**
504
690
  * The gates the policy file told not to decide anything, as notifications.
505
691
  *
@@ -582,7 +768,7 @@ export function renderSarif(result, umbrellaVersion) {
582
768
  // and one measured against a contract somebody approved by hand are
583
769
  // different claims, and so are one over a branch diff and one over an
584
770
  // index.
585
- runs.push(makeRun(gate.product, gate.productVersion, own, {
771
+ runs.push(makeRun(gate.product, gate.productVersion, own, fallbackLocationFor(gate), {
586
772
  enforced: gate.enforce,
587
773
  stage: gate.stage,
588
774
  ...(gate.intent === undefined
@@ -609,18 +795,43 @@ export function renderSarif(result, umbrellaVersion) {
609
795
  ...skippedNotifications(result),
610
796
  ...unenforcedNotifications(result),
611
797
  ...legacyStateDirNotifications(result),
798
+ ...trustBaseRefusedNotifications(result),
799
+ ...programRefusedNotifications(result),
800
+ ...proposalNotifications(result),
801
+ ...trustBaseWithheldNotifications(result),
612
802
  ];
613
803
  // Notifications earn the run on their own. Before this, the umbrella run
614
804
  // existed only when it had findings and a deferred gate was one; without
615
805
  // this clause a commit-stage log would say nothing whatever about the gate
616
806
  // that did not run there.
617
- if (umbrellaFindings.length > 0 || notifications.length > 0) {
618
- runs.push(makeRun(UMBRELLA_DRIVER_NAME, umbrellaVersion, umbrellaFindings, undefined, {
619
- // A claim about whether the analysis completed, taken from the gates
620
- // rather than from the exit code: an unenforced gate that could not
621
- // run leaves the run at exit 0, and nothing was checked by it either
622
- // way. Written whenever this run is written, in both directions.
623
- executionSuccessful: result.gates.every((gate) => gate.couldNotRun === null),
807
+ //
808
+ // A REFUSAL EARNS IT UNCONDITIONALLY, and that clause is not redundant with
809
+ // the two beside it even though a refusal always adds a notification: it
810
+ // says out loud that the worst run this tool can have is the one case where
811
+ // an empty log is not acceptable. `{"runs": []}` was the output when the
812
+ // base ref could not be read and the head's inventory named no gate, and an
813
+ // empty log uploads cleanly and is indistinguishable from a repository
814
+ // nobody scanned.
815
+ if (umbrellaFindings.length > 0 ||
816
+ notifications.length > 0 ||
817
+ (result.trustBase?.refusal ?? null) !== null) {
818
+ runs.push(makeRun(UMBRELLA_DRIVER_NAME, umbrellaVersion, umbrellaFindings, POLICY_FILE_NAME,
819
+ // On the umbrella's run rather than on any gate's, because it is a
820
+ // fact about the whole run: every gate that could take the flag was
821
+ // handed this same ref. A consumer reading only the log can then tell
822
+ // a pull-request run from an ordinary one without parsing sentences.
823
+ result.trustBase === null ? undefined : { trustBase: result.trustBase }, {
824
+ // A claim about whether the analysis completed, taken from the
825
+ // gates rather than from the exit code: an unenforced gate that
826
+ // could not run leaves the run at exit 0, and nothing was checked
827
+ // by it either way. Written whenever this run is written, in both
828
+ // directions.
829
+ // A refusal is false whatever the gate list says, and with an
830
+ // empty inventory `every` over nothing is vacuously true, which
831
+ // would have claimed the analysis completed on the one run where
832
+ // nothing was even attempted.
833
+ executionSuccessful: (result.trustBase?.refusal ?? null) === null &&
834
+ result.gates.every((gate) => gate.couldNotRun === null),
624
835
  notifications,
625
836
  }));
626
837
  }