@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.
@@ -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;
@@ -32,7 +45,18 @@ export type GateProblemRule = 'conductor/gate-missing' | 'conductor/gate-output-
32
45
  * looked. So it is a finding, it blocks, and it says which names were
33
46
  * tried, so the fix is in the message rather than in a support thread.
34
47
  */
35
- export declare function normalizeMissingGate(role: GateRole, product: Product, candidates: string[]): Finding;
48
+ export declare function normalizeMissingGate(role: GateRole, product: Product, candidates: string[],
49
+ /**
50
+ * A sentence appended to the message, or nothing.
51
+ *
52
+ * Written by the caller rather than decided here, because the only thing
53
+ * that varies is WHY the search came up empty, and that is a fact about the
54
+ * run rather than about the finding. Today the one caller that passes
55
+ * anything is a pull-request run, where node_modules/.bin was never
56
+ * searched and the message would otherwise be misleading in exactly the
57
+ * repository shape this is most likely to happen in.
58
+ */
59
+ remedy?: string): Finding;
36
60
  /**
37
61
  * The finding raised when a gate's `command:` names a file that is not
38
62
  * there.
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
@@ -544,10 +620,21 @@ function gateProblem(ruleId, role, product, message, details) {
544
620
  * looked. So it is a finding, it blocks, and it says which names were
545
621
  * tried, so the fix is in the message rather than in a support thread.
546
622
  */
547
- export function normalizeMissingGate(role, product, candidates) {
623
+ export function normalizeMissingGate(role, product, candidates,
624
+ /**
625
+ * A sentence appended to the message, or nothing.
626
+ *
627
+ * Written by the caller rather than decided here, because the only thing
628
+ * that varies is WHY the search came up empty, and that is a fact about the
629
+ * run rather than about the finding. Today the one caller that passes
630
+ * anything is a pull-request run, where node_modules/.bin was never
631
+ * searched and the message would otherwise be misleading in exactly the
632
+ * repository shape this is most likely to happen in.
633
+ */
634
+ remedy = '') {
548
635
  return gateProblem('conductor/gate-missing', role, product, `The "${role}" gate is enabled but no ${product} binary was found. ` +
549
636
  `Looked for: ${candidates.join(', ')}. Install it, point the gate at a build with an ` +
550
- `absolute "command:", or set enabled: false to switch the gate off on purpose.`, { candidates });
637
+ `absolute "command:", or set enabled: false to switch the gate off on purpose.${remedy}`, { candidates });
551
638
  }
552
639
  /**
553
640
  * The finding raised when a gate's `command:` names a file that is not
@@ -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,176 @@ 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, one of the two notifications here that are not notes, and the
592
+ * wider of the two: a refused program says one gate did not run, and this one
593
+ * says the whole run did not. Every other notification in this file says how
594
+ * much of the policy a run covered. These two say what was not covered at
595
+ * all, and a reader must not be able to scroll past either.
596
+ *
597
+ * A NOTIFICATION rather than a result even so, and the reason is the
598
+ * discriminator further down: a result is about a place in somebody's code,
599
+ * and this is about a ref. The could-not-run RESULTS for whatever gates the
600
+ * inventory named sit beside it in the same run and carry the same sentence,
601
+ * so a consumer that reads only results still learns that nothing ran.
602
+ */
603
+ function trustBaseRefusedNotifications(result) {
604
+ const refusal = result.trustBase?.refusal;
605
+ if (refusal === undefined || refusal === null) {
606
+ return [];
607
+ }
608
+ return [
609
+ {
610
+ id: 'conductor/trust-base-refused',
611
+ level: 'error',
612
+ message: `conductor refused the trust base "${result.trustBase?.ref ?? ''}", so no gate ran and ` +
613
+ `NOTHING WAS CHECKED by this run. ${refusal}`,
614
+ details: { ref: result.trustBase?.ref ?? null, reason: refusal },
615
+ },
616
+ ];
617
+ }
618
+ /**
619
+ * The gates whose PROGRAM the umbrella refused to run.
620
+ *
621
+ * ERROR level, beside the refused trust base and for the same reason: this is
622
+ * not a statement about how much of the policy a run covered. A pull request
623
+ * put a file where the gate's binary resolves and the umbrella declined to
624
+ * execute it, which a reviewer has to meet rather than scroll past.
625
+ *
626
+ * The gate's could-not-run RESULT carries the same sentence, so a consumer
627
+ * reading only results still learns the gate did not run. This adds the
628
+ * structured half: which gate, which program, and which ref it was measured
629
+ * against.
630
+ */
631
+ function programRefusedNotifications(result) {
632
+ return result.gates.flatMap((gate) => {
633
+ if (gate.couldNotRun?.reason !== 'gate-program-refused') {
634
+ return [];
635
+ }
636
+ return [
637
+ {
638
+ id: 'conductor/gate-program-refused',
639
+ level: 'error',
640
+ message: `The ${gate.role} gate (${gate.product}) did NOT run: its program is a file this pull ` +
641
+ `request controls, so running it would let the pull request choose the program that ` +
642
+ `judges it. ${gate.couldNotRun.detail}`,
643
+ details: {
644
+ role: gate.role,
645
+ product: gate.product,
646
+ program: gate.binary?.program ?? null,
647
+ ref: gate.trustBase?.ref ?? null,
648
+ reason: gate.couldNotRun.detail,
649
+ },
650
+ },
651
+ ];
652
+ });
653
+ }
654
+ /**
655
+ * The gates the umbrella could not put into pull-request mode.
656
+ *
657
+ * The loud half of the same mode, and by the discriminator below it is a
658
+ * close call that lands on notification: nothing went wrong with the run, and
659
+ * the fact is true of the configuration (an older gate is installed) rather
660
+ * than of this change, so it is identical on every run until somebody
661
+ * upgrades. What it says is how much of the pull-request boundary this run
662
+ * actually had, which is a coverage statement.
663
+ *
664
+ * It is still the most important notification in the log. A gate here read
665
+ * its own control inputs out of the tree under judgment.
666
+ */
667
+ function trustBaseWithheldNotifications(result) {
668
+ return result.gates.flatMap((gate) => {
669
+ const withheld = gate.trustBase?.withheld;
670
+ if (withheld === undefined || withheld === null) {
671
+ return [];
672
+ }
673
+ return [
674
+ {
675
+ id: 'conductor/trust-base-not-passed',
676
+ message: `The ${gate.role} gate (${gate.product}) did NOT run in pull-request mode, so it read ` +
677
+ `its own control inputs from the tree being judged rather than from ` +
678
+ `${gate.trustBase?.ref ?? 'the base ref'}. ${withheld}`,
679
+ details: {
680
+ role: gate.role,
681
+ product: gate.product,
682
+ productVersion: gate.productVersion,
683
+ ref: gate.trustBase?.ref ?? null,
684
+ reason: withheld,
685
+ },
686
+ },
687
+ ];
688
+ });
689
+ }
690
+ /**
691
+ * The node_modules/.bin candidates a pull-request run declined to take.
692
+ *
693
+ * ONE NOTIFICATION FOR THE RUN, not one per gate. This is a statement about
694
+ * the run's mode: node_modules/.bin is not a location a pull-request run has,
695
+ * and in the repository shape it happens in most, gates installed as
696
+ * devDependencies and nothing else, it is true of every gate at once.
697
+ *
698
+ * A NOTE, by the discriminator above, and not a close call. Nothing went
699
+ * wrong, nobody's code is at fault, and the gates still ran: it says WHERE the
700
+ * program that ran came from, which is a coverage statement in the same shape
701
+ * as the withheld one. When the skip actually cost a gate its run, that gate's
702
+ * own could-not-run result carries the remedy, so a consumer reading only
703
+ * results still learns what to do.
704
+ */
705
+ function nodeModulesSkippedNotifications(result) {
706
+ const skipped = result.gates.flatMap((gate) => gate.nodeModulesSkipped === undefined
707
+ ? []
708
+ : [{ role: gate.role, product: gate.product, path: gate.nodeModulesSkipped }]);
709
+ if (skipped.length === 0) {
710
+ return [];
711
+ }
712
+ return [
713
+ {
714
+ id: 'conductor/node-modules-skipped',
715
+ message: 'Resolution did NOT consult node_modules/.bin on this pull-request run: ' +
716
+ `${skipped.map((entry) => `${entry.role} (${entry.product}) at ${entry.path}`).join(', ')}. ` +
717
+ 'What is installed there is chosen by the head own manifest and lockfile, so no ref ' +
718
+ 'approves it. Each of those gates was resolved from PATH or from an absolute command: ' +
719
+ 'instead, or reported as could-not-run with the install remedy.',
720
+ details: { ref: result.trustBase?.ref ?? null, skipped },
721
+ },
722
+ ];
723
+ }
503
724
  /**
504
725
  * The gates the policy file told not to decide anything, as notifications.
505
726
  *
@@ -582,7 +803,7 @@ export function renderSarif(result, umbrellaVersion) {
582
803
  // and one measured against a contract somebody approved by hand are
583
804
  // different claims, and so are one over a branch diff and one over an
584
805
  // index.
585
- runs.push(makeRun(gate.product, gate.productVersion, own, {
806
+ runs.push(makeRun(gate.product, gate.productVersion, own, fallbackLocationFor(gate), {
586
807
  enforced: gate.enforce,
587
808
  stage: gate.stage,
588
809
  ...(gate.intent === undefined
@@ -609,18 +830,44 @@ export function renderSarif(result, umbrellaVersion) {
609
830
  ...skippedNotifications(result),
610
831
  ...unenforcedNotifications(result),
611
832
  ...legacyStateDirNotifications(result),
833
+ ...trustBaseRefusedNotifications(result),
834
+ ...programRefusedNotifications(result),
835
+ ...proposalNotifications(result),
836
+ ...trustBaseWithheldNotifications(result),
837
+ ...nodeModulesSkippedNotifications(result),
612
838
  ];
613
839
  // Notifications earn the run on their own. Before this, the umbrella run
614
840
  // existed only when it had findings and a deferred gate was one; without
615
841
  // this clause a commit-stage log would say nothing whatever about the gate
616
842
  // 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),
843
+ //
844
+ // A REFUSAL EARNS IT UNCONDITIONALLY, and that clause is not redundant with
845
+ // the two beside it even though a refusal always adds a notification: it
846
+ // says out loud that the worst run this tool can have is the one case where
847
+ // an empty log is not acceptable. `{"runs": []}` was the output when the
848
+ // base ref could not be read and the head's inventory named no gate, and an
849
+ // empty log uploads cleanly and is indistinguishable from a repository
850
+ // nobody scanned.
851
+ if (umbrellaFindings.length > 0 ||
852
+ notifications.length > 0 ||
853
+ (result.trustBase?.refusal ?? null) !== null) {
854
+ runs.push(makeRun(UMBRELLA_DRIVER_NAME, umbrellaVersion, umbrellaFindings, POLICY_FILE_NAME,
855
+ // On the umbrella's run rather than on any gate's, because it is a
856
+ // fact about the whole run: every gate that could take the flag was
857
+ // handed this same ref. A consumer reading only the log can then tell
858
+ // a pull-request run from an ordinary one without parsing sentences.
859
+ result.trustBase === null ? undefined : { trustBase: result.trustBase }, {
860
+ // A claim about whether the analysis completed, taken from the
861
+ // gates rather than from the exit code: an unenforced gate that
862
+ // could not run leaves the run at exit 0, and nothing was checked
863
+ // by it either way. Written whenever this run is written, in both
864
+ // directions.
865
+ // A refusal is false whatever the gate list says, and with an
866
+ // empty inventory `every` over nothing is vacuously true, which
867
+ // would have claimed the analysis completed on the one run where
868
+ // nothing was even attempted.
869
+ executionSuccessful: (result.trustBase?.refusal ?? null) === null &&
870
+ result.gates.every((gate) => gate.couldNotRun === null),
624
871
  notifications,
625
872
  }));
626
873
  }