@vaultcompass/conductor 0.8.0 → 0.9.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.
Files changed (44) hide show
  1. package/README.md +263 -77
  2. package/dist/cli.js +152 -30
  3. package/dist/envelope.d.ts +8 -0
  4. package/dist/exit-codes.d.ts +52 -2
  5. package/dist/exit-codes.js +64 -14
  6. package/dist/external-config.d.ts +2 -1
  7. package/dist/external-config.js +33 -18
  8. package/dist/gate-runner.d.ts +141 -17
  9. package/dist/gate-runner.js +537 -83
  10. package/dist/git.d.ts +95 -0
  11. package/dist/git.js +244 -0
  12. package/dist/init-policy.js +38 -2
  13. package/dist/init.js +40 -3
  14. package/dist/intent-base.d.ts +35 -1
  15. package/dist/intent-base.js +124 -64
  16. package/dist/intent-prepare.d.ts +33 -2
  17. package/dist/intent-prepare.js +443 -34
  18. package/dist/intent-spec.d.ts +28 -0
  19. package/dist/intent-spec.js +22 -5
  20. package/dist/normalize.d.ts +11 -0
  21. package/dist/normalize.js +60 -6
  22. package/dist/osv-baseline.d.ts +84 -0
  23. package/dist/osv-baseline.js +325 -0
  24. package/dist/osv-coverage.d.ts +80 -0
  25. package/dist/osv-coverage.js +223 -0
  26. package/dist/output-sarif.js +55 -15
  27. package/dist/output-text.d.ts +53 -2
  28. package/dist/output-text.js +287 -27
  29. package/dist/policy.d.ts +10 -0
  30. package/dist/policy.js +21 -7
  31. package/dist/products.d.ts +32 -10
  32. package/dist/products.js +73 -9
  33. package/dist/requirements-pin.d.ts +47 -0
  34. package/dist/requirements-pin.js +256 -0
  35. package/dist/resolve.d.ts +1 -0
  36. package/dist/resolve.js +1 -1
  37. package/dist/run.d.ts +21 -0
  38. package/dist/run.js +74 -15
  39. package/dist/trust-base.d.ts +101 -20
  40. package/dist/trust-base.js +219 -73
  41. package/dist/unread-manifests.d.ts +14 -0
  42. package/dist/unread-manifests.js +69 -0
  43. package/package.json +1 -1
  44. package/schema/guardrails.schema.json +4 -0
@@ -22,7 +22,8 @@
22
22
  // CI logs, and in pasted issue reports, and the plainest thing that works
23
23
  // everywhere is worth more here than a nicer-looking terminal.
24
24
  import { compareFindings } from './envelope.js';
25
- import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN } from './exit-codes.js';
25
+ import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, gateExitBlocks } from './exit-codes.js';
26
+ import { CONDUCTOR_OWN_REASONS, cleanOutputLine, conductorStatedReason, } from './gate-runner.js';
26
27
  import { isLegacyContractPath } from './intent-prepare.js';
27
28
  function subjectLabel(finding) {
28
29
  const subject = finding.subject;
@@ -43,9 +44,42 @@ function findingLines(finding) {
43
44
  const marker = finding.blocking ? 'BLOCKING' : ' report';
44
45
  const severity = finding.severityIsDerived ? `${finding.severity}*` : finding.severity;
45
46
  const subject = subjectLabel(finding);
46
- const head = ` ${marker} ${severity.padEnd(9)} ${finding.ruleId}${subject === '' ? '' : ` ${subject}`}`;
47
+ // The vulnerabilities gate's base-comparison label, on a compared
48
+ // pull-request run only: the label is set nowhere else.
49
+ const baseline = finding.details.baseline;
50
+ const label = baseline === 'introduced' || baseline === 'present-on-base' ? ` ${baseline}` : '';
51
+ const head = ` ${marker} ${severity.padEnd(9)} ${finding.ruleId}${subject === '' ? '' : ` ${subject}`}${label}`;
47
52
  return [head, ` ${finding.message}`];
48
53
  }
54
+ /**
55
+ * The base comparison under the vulnerabilities gate's threshold line: the
56
+ * ref, the two counts, the base policy and what it means here, then one line
57
+ * per lockfile the comparison was unavailable for. Nothing on a run with no
58
+ * comparison.
59
+ */
60
+ function baseComparisonLines(gate) {
61
+ const comparison = gate.baseComparison;
62
+ if (comparison === undefined) {
63
+ return [];
64
+ }
65
+ const meaning = comparison.policy === 'report' ? 'report (not blocking)' : 'block (blocking)';
66
+ return [
67
+ ` base comparison ${comparison.ref} introduced ${comparison.introduced} ` +
68
+ `present-on-base ${comparison.presentOnBase} present-on-base: ${meaning}`,
69
+ ...comparison.unavailable.map((entry) => ` base comparison unavailable for ${entry.path}: ${entry.reason}; counted as introduced`),
70
+ ];
71
+ }
72
+ /**
73
+ * How many present-on-base findings were reported and NOT blocking, across
74
+ * the gates: the vulnerabilities gate under present-on-base: report. The
75
+ * number on the report's third line and in the exit-0 verdict clause.
76
+ */
77
+ function presentOnBaseReported(result) {
78
+ return result.gates
79
+ .filter((gate) => gate.baseComparison?.policy === 'report')
80
+ .flatMap((gate) => gate.findings)
81
+ .filter((finding) => finding.details.baseline === 'present-on-base' && !finding.blocking).length;
82
+ }
49
83
  function header(gate) {
50
84
  const version = gate.productVersion === null ? '(version unknown)' : gate.productVersion;
51
85
  // On the header line rather than only at the bottom of the section: a
@@ -74,7 +108,7 @@ function enforcementNote(gate) {
74
108
  'so it is a note here rather than a failed run. Nothing was checked by it.');
75
109
  }
76
110
  const blocking = gate.findings.filter((finding) => finding.blocking).length;
77
- if (blocking > 0 || (gate.exitCode ?? 0) !== 0) {
111
+ if (blocking > 0 || gateExitBlocks(gate)) {
78
112
  return (` not enforced: this gate reported ${blocking} blocking finding(s) and exited ` +
79
113
  `${gate.exitCode ?? '?'}, and enforce is false for it in .guardrails.yaml, so the commit ` +
80
114
  'proceeds. Set enforce: true there to make it block.');
@@ -112,12 +146,18 @@ function gateSection(gate) {
112
146
  const contract = contractLine(gate);
113
147
  if (contract !== null) {
114
148
  lines.push(contract);
149
+ if (gate.intent?.note !== undefined) {
150
+ lines.push(` note: ${gate.intent.note}`);
151
+ }
115
152
  }
116
153
  if (gate.couldNotRun !== null) {
117
154
  lines.push(` ${gate.couldNotRun.detail}`);
155
+ if (gate.couldNotRun.gateSaid !== undefined) {
156
+ lines.push(` gate said: "${gate.couldNotRun.gateSaid}"`);
157
+ }
118
158
  if (gate.stderr.trim().length > 0) {
119
159
  for (const line of gate.stderr.trim().split('\n')) {
120
- lines.push(` | ${line}`);
160
+ lines.push(` | ${cleanOutputLine(line)}`);
121
161
  }
122
162
  }
123
163
  }
@@ -136,6 +176,7 @@ function gateSection(gate) {
136
176
  ? 'ignored not reported'
137
177
  : `ignored ${gate.run.ignored}`;
138
178
  lines.push(` ${threshold} suppressed ${gate.run.suppressed} ${ignored}`);
179
+ lines.push(...baseComparisonLines(gate));
139
180
  // The gate's own run facts: what it scanned, with what, against what.
140
181
  // These were being collected and then dropped.
141
182
  //
@@ -218,6 +259,13 @@ function skipWording(reason) {
218
259
  function excludedLines(result) {
219
260
  return result.excluded.map((gate) => ` excluded ${gate.role} ${gate.product} did not run here; --gate did not name it`);
220
261
  }
262
+ /**
263
+ * One line per gate the policy file switches off with enabled: false, so an
264
+ * adopter sees what is not running at all. Absent when none is.
265
+ */
266
+ function disabledLines(result) {
267
+ return (result.disabled ?? []).map((gate) => ` disabled ${gate.role} ${gate.product} enabled: false in .guardrails.yaml; it did not run`);
268
+ }
221
269
  /**
222
270
  * One line per gate skipped because the head tree equals the trust base's
223
271
  * (issue #69).
@@ -237,19 +285,39 @@ function treeUnchangedLines(result) {
237
285
  * answer to "did this pull request also try to change the rules", and leaving
238
286
  * it out when the answer is none makes a run in pull-request mode
239
287
  * indistinguishable from a run that was never in it.
288
+ *
289
+ * NEVER A COUNT THAT TREATS A GATE THAT COULD NOT RUN AS ZERO. A gate that
290
+ * was put into pull-request mode and could not run reported no summary the
291
+ * umbrella reads, so its proposals are not known rather than none. The
292
+ * sentence then names those gates and counts only what the others proposed.
293
+ * On a run with a trust base that includes a gate that stopped before its
294
+ * pull-request mode was even decided (it carries no trustBase: a preparation
295
+ * that failed, a git older than the floor, a missing binary), because it was
296
+ * meant to run in that mode and reported nothing either.
240
297
  */
241
- function proposalCount(result) {
242
- return `${result.proposals.length} control change(s) proposed in this pull request`;
298
+ export function proposalCount(result) {
299
+ const unknown = result.gates.filter((gate) => gate.couldNotRun !== null &&
300
+ (gate.trustBase === undefined
301
+ ? result.trustBase !== null
302
+ : gate.trustBase.withheld === null && gate.trustBase.refused === null));
303
+ if (unknown.length === 0) {
304
+ return `${result.proposals.length} control change(s) proposed in this pull request`;
305
+ }
306
+ const names = unknown.map((gate) => `${gate.role} (${gate.product})`).join(', ');
307
+ return (`${result.proposals.length} control change(s) proposed by the gates that ran; ` +
308
+ `${names} could not run, so the proposals of ${unknown.length === 1 ? 'that gate are' : 'those gates are'} not known`);
243
309
  }
244
310
  /**
245
- * The gates the umbrella could not put into pull-request mode.
311
+ * The gates the umbrella did not hand the trust base to.
246
312
  *
247
- * This is the loud half and it must never be silent. A gate here read its own
248
- * contract, config or baseline out of the tree being judged, which is exactly
249
- * the hole pull-request mode exists to close, so a run where one gate is
250
- * still exposed must not read like a run where none is. It is a statement
251
- * about coverage rather than about anybody's code, so it is a line and a
252
- * notification rather than a finding, and it never reaches the exit code.
313
+ * This is the loud half and it must never be silent: a run where one gate was
314
+ * not handed the base ref must not read like a run where every gate was. A
315
+ * gate below its pull-request-mode minimum is never here (it is
316
+ * could-not-run); what is left is an intent gate judging a contract imported
317
+ * from the base for this run, and a product with no pull-request mode at all.
318
+ * It is a statement about coverage rather than about anybody's code, so it is
319
+ * a line and a notification rather than a finding, and it never reaches the
320
+ * exit code.
253
321
  */
254
322
  function withheldTrustBase(result) {
255
323
  return result.gates.flatMap((gate) => {
@@ -291,6 +359,9 @@ function trustBaseLines(result) {
291
359
  if (result.trustBase === null) {
292
360
  return [];
293
361
  }
362
+ if (result.trustBase.notGiven === true) {
363
+ return [' pull-request mode: no trust base was given, so no rules were read.'];
364
+ }
294
365
  const lines = [
295
366
  ` pull-request mode: rules from ${result.trustBase.ref}. ${proposalCount(result)}.`,
296
367
  ];
@@ -318,7 +389,7 @@ function unenforcedClauses(result) {
318
389
  // blocking finding" reports the same gate as having blocked AND as having
319
390
  // failed to run, which are opposite claims.
320
391
  const blocked = unenforced.filter((gate) => gate.couldNotRun === null &&
321
- ((gate.exitCode ?? 0) !== 0 || gate.findings.some((finding) => finding.blocking)));
392
+ (gateExitBlocks(gate) || gate.findings.some((finding) => finding.blocking)));
322
393
  const broken = unenforced.filter((gate) => gate.couldNotRun !== null);
323
394
  const clauses = [];
324
395
  if (blocked.length > 0) {
@@ -346,7 +417,9 @@ function refusalLines(result) {
346
417
  return [];
347
418
  }
348
419
  return [
349
- `conductor: refused the trust base "${result.trustBase?.ref ?? ''}". Nothing was checked.`,
420
+ result.trustBase?.notGiven === true
421
+ ? 'conductor: this is a pull-request job and no trust base was given, so no rules were read. Nothing was checked.'
422
+ : `conductor: refused the trust base "${result.trustBase?.ref ?? ''}". Nothing was checked.`,
350
423
  ` ${refusal}`,
351
424
  ];
352
425
  }
@@ -378,10 +451,97 @@ function refusalLines(result) {
378
451
  export function jobLogSummary(result) {
379
452
  const refusal = result.trustBase?.refusal;
380
453
  if (refusal !== undefined && refusal !== null) {
381
- return `refused the trust base "${result.trustBase?.ref ?? ''}": ${refusal.replace(/\.+\s*$/, '')}`;
454
+ return result.trustBase?.notGiven === true
455
+ ? `pull-request job with no trust base, no rules read: ${refusal.replace(/\.+\s*$/, '')}`
456
+ : `refused the trust base "${result.trustBase?.ref ?? ''}": ${refusal.replace(/\.+\s*$/, '')}`;
382
457
  }
383
458
  return `${result.gates.length} gate(s), ${result.findings.length} finding(s)`;
384
459
  }
460
+ /**
461
+ * One plain line per gate, for the job log: which gate, which version, what
462
+ * happened, and the exit code. Written to stderr by cli.ts on EVERY run, so
463
+ * an adopter reading the log learns which gate did what without opening a
464
+ * report (the SARIF log, the text report file or the pull request comment).
465
+ *
466
+ * Outcomes, in the words the lines use: `ok`, `findings (N, M blocking)`,
467
+ * `could-not-run (reason)` with the gate's own stated reason when it gave
468
+ * one, or conductor's own reason when the refusal was conductor's (both
469
+ * cleaned, one line, capped and quoted), `missing (reason)` for a gate that
470
+ * was not found, and `skipped (why)`
471
+ * for a gate that was enabled and never spawned (deferred by stage, left out
472
+ * by --gate, no contract, tree unchanged). A gate with no process behind it
473
+ * says `no exit code`, never a made-up one.
474
+ *
475
+ * Describes, decides nothing: every word is read off the outcomes the exit
476
+ * code was already composed from. Same plain ASCII as the rest of this file.
477
+ */
478
+ export function gateLogLines(result) {
479
+ const lines = [];
480
+ for (const gate of result.gates) {
481
+ const version = gate.productVersion === null ? 'version unknown' : gate.productVersion;
482
+ const exit = gate.exitCode === null ? 'no exit code' : `exit ${gate.exitCode}`;
483
+ let outcome;
484
+ if (gate.couldNotRun !== null) {
485
+ const reason = gate.couldNotRun.reason;
486
+ outcome =
487
+ reason === 'binary-missing' || reason === 'configured-command-missing'
488
+ ? `missing (${reason})`
489
+ : `could-not-run (${reason})`;
490
+ }
491
+ else {
492
+ const total = gate.findings.length;
493
+ const blocking = gate.findings.filter((finding) => finding.blocking).length;
494
+ outcome =
495
+ total === 0 && (gate.exitCode ?? 0) === 0 ? 'ok' : `findings (${total}, ${blocking} blocking)`;
496
+ }
497
+ // conductor's own refusals (a git below the floor, a path list it cannot
498
+ // pass, a PATH or git-directory failure, a gate below its minimum) carry
499
+ // their reason the same way, since no gate said anything for them.
500
+ const conductorSaid = gate.couldNotRun !== null &&
501
+ gate.couldNotRun.gateSaid === undefined &&
502
+ CONDUCTOR_OWN_REASONS.has(gate.couldNotRun.reason)
503
+ ? conductorStatedReason(gate.couldNotRun.detail)
504
+ : null;
505
+ lines.push(`conductor: gate ${gate.role} (${gate.product} ${version}): ${outcome}, ${exit}` +
506
+ (gate.enforce ? '' : ', not enforced') +
507
+ (gate.couldNotRun?.gateSaid === undefined ? '' : `, gate said: "${gate.couldNotRun.gateSaid}"`) +
508
+ (conductorSaid === null ? '' : `, conductor said: "${conductorSaid}"`));
509
+ }
510
+ const notRun = (role, product, why) => `conductor: gate ${role} (${product}): skipped (${why}), no exit code`;
511
+ for (const gate of result.deferred) {
512
+ lines.push(notRun(gate.role, gate.product, `deferred to stage ${gate.stage}`));
513
+ }
514
+ for (const gate of result.skipped) {
515
+ lines.push(notRun(gate.role, gate.product, skipWording(gate.reason).line));
516
+ }
517
+ for (const gate of result.excluded) {
518
+ lines.push(notRun(gate.role, gate.product, '--gate did not name it'));
519
+ }
520
+ for (const gate of result.treeUnchanged) {
521
+ lines.push(notRun(gate.role, gate.product, 'head tree equals the base tree'));
522
+ }
523
+ return lines;
524
+ }
525
+ /**
526
+ * One warning per gate that was found on PATH at a version other than the one
527
+ * this run expected (the Action's pin).
528
+ *
529
+ * For the job log only: it names where the binary was found, and an absolute
530
+ * path has no business in a published SARIF log or a pull request comment, so
531
+ * this is never part of either report. A warning and nothing more. Resolution
532
+ * is unchanged and the gate ran (or was refused) exactly as it would have
533
+ * without it.
534
+ */
535
+ export function versionSkewWarnings(result) {
536
+ return result.gates.flatMap((gate) => gate.versionSkew === undefined
537
+ ? []
538
+ : [
539
+ `conductor: warning: ${gate.product} resolved from PATH reports version ${gate.versionSkew.found}, ` +
540
+ `but this run expects ${gate.versionSkew.expected} (the version the action pinned). ` +
541
+ `It was found at ${gate.versionSkew.path}. Resolution is unchanged and that binary was used. ` +
542
+ `Fix: remove the other ${gate.product} from PATH, or install ${gate.versionSkew.expected}.`,
543
+ ]);
544
+ }
385
545
  /**
386
546
  * How many blocking findings one gate that RAN is carrying, for the token.
387
547
  *
@@ -397,7 +557,7 @@ function blockingCount(gate) {
397
557
  return 0;
398
558
  }
399
559
  const blocking = gate.findings.filter((finding) => finding.blocking).length;
400
- return blocking === 0 && (gate.exitCode ?? 0) !== 0 ? 1 : blocking;
560
+ return blocking === 0 && gateExitBlocks(gate) ? 1 : blocking;
401
561
  }
402
562
  /**
403
563
  * The verdict token: a label for the umbrella's OWN exit decision, in a
@@ -405,8 +565,11 @@ function blockingCount(gate) {
405
565
  * the state without parsing the verdict sentence.
406
566
  *
407
567
  * pass exit 0 and nothing was hidden by it
408
- * nothing-checked exit 0, but no gate ran at all (none enabled,
409
- * or every one deferred, tree-unchanged or skipped)
568
+ * nothing-checked exit 0, but nothing was checked: no gate ran at
569
+ * all (none enabled, or every one deferred,
570
+ * tree-unchanged or skipped), or every gate that
571
+ * ran checked nothing (nothing to scan, or no
572
+ * contract; audit finding F4)
410
573
  * advisory-blocked (N) exit 1 that --advisory turned into exit 0
411
574
  * unenforced-findings (N) exit 0, but enforce: false gates blocked or
412
575
  * could not run
@@ -455,7 +618,49 @@ export function verdictToken(result, advisory) {
455
618
  const unenforced = result.gates
456
619
  .filter((gate) => !gate.enforce)
457
620
  .reduce((total, gate) => total + (gate.couldNotRun !== null ? 1 : blockingCount(gate)), 0);
458
- return unenforced > 0 ? `unenforced-findings (${unenforced})` : 'pass';
621
+ if (unenforced > 0) {
622
+ return `unenforced-findings (${unenforced})`;
623
+ }
624
+ // Exit 0 where every gate that RAN checked nothing (audit finding F4): the
625
+ // vulnerabilities gate with no lockfile it reads, an intent gate with no
626
+ // contract. Gates ran, so the rule above does not fire, but nothing was
627
+ // examined, and a pass here is the same false statement as a pass with no
628
+ // gate at all. Same token, same exit code (0), same predicate the verdict
629
+ // sentence uses, so the two cannot disagree.
630
+ return result.gates.every(gateCheckedNothing) ? 'nothing-checked' : 'pass';
631
+ }
632
+ /**
633
+ * A gate that ran and examined nothing: osv-scanner with nothing to scan,
634
+ * osv-scanner whose every handed lockfile parsed to no packages (exit 128,
635
+ * marked `packages-read 0`; a sole lockfile rewritten to {} is exactly the
636
+ * same news as no lockfile), or an intent gate that found no contract to
637
+ * check against. The one predicate behind both the verdict token and the
638
+ * verdict sentence's list of what was not checked.
639
+ *
640
+ * NOT the partial-empty case: `conductor/lockfiles-empty` is also raised
641
+ * when osv-scanner read packages from other lockfiles (audit finding F2),
642
+ * and that gate checked something. Only the `packages-read` marker, which
643
+ * the exit-128 branch alone writes, tells the two apart.
644
+ */
645
+ function readNoPackages(gate) {
646
+ return gate.run.details['packages-read'] === 0;
647
+ }
648
+ function gateCheckedNothing(gate) {
649
+ if (gate.couldNotRun !== null) {
650
+ return false;
651
+ }
652
+ return (gate.diagnostics.some((d) => d.code === 'conductor/nothing-to-scan') ||
653
+ readNoPackages(gate) ||
654
+ (gate.role === 'intent' && gate.run.details.contractFound === false));
655
+ }
656
+ /** How the verdict sentence names a gate that ran and checked nothing. */
657
+ function checkedNothingWording(gate) {
658
+ if (gate.role === 'intent') {
659
+ return `${gate.role} ran but found no contract to check against`;
660
+ }
661
+ return readNoPackages(gate)
662
+ ? `${gate.role} read no packages from its lockfiles`
663
+ : `${gate.role} had nothing to scan`;
459
664
  }
460
665
  function verdict(result, advisory) {
461
666
  const refusal = result.trustBase?.refusal;
@@ -465,8 +670,11 @@ function verdict(result, advisory) {
465
670
  // them would describe a different run from the one that happened. A
466
671
  // refusal is a could-not-run outcome (exit 2), which --advisory never
467
672
  // touches, so this branch reads advisory or not exactly the same.
468
- return (`verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
469
- 'so no gate ran and nothing here is a result of any kind.');
673
+ return result.trustBase?.notGiven === true
674
+ ? 'verdict: exit 2, this is a pull-request job and no trust base was given, so no rules ' +
675
+ 'were read, no gate ran and nothing here is a result of any kind.'
676
+ : `verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
677
+ 'so no gate ran and nothing here is a result of any kind.';
470
678
  }
471
679
  return verdictForRun(result, advisory);
472
680
  }
@@ -563,7 +771,7 @@ function verdictForRun(result, advisory) {
563
771
  // explicitly says there is none of, so it gets its own, narrower
564
772
  // wording that is true here and says nothing about findings at all.
565
773
  const names = enforcedGates
566
- .filter((gate) => (gate.exitCode ?? 0) !== 0)
774
+ .filter((gate) => gateExitBlocks(gate))
567
775
  .map((gate) => `${gate.role} (exit ${gate.exitCode ?? '?'})`)
568
776
  .join(', ');
569
777
  const base = `and no finding here is marked blocking. Enforced gate(s) that exited ` +
@@ -573,19 +781,52 @@ function verdictForRun(result, advisory) {
573
781
  ? `verdict: exit 0, ${base} This run was advisory, so exit 1 became exit 0.`
574
782
  : `verdict: exit 1, ${base}`;
575
783
  }
576
- const base = `${blocking} blocking finding(s) across ${enforcedGates.length} gate(s).${aside}`;
784
+ // Gates that blocked out of gates that could have, not a bare count of
785
+ // the enforced ones, which read as if every one of them had blocked.
786
+ const blockedGates = enforcedGates.filter((gate) => blockingCount(gate) > 0).length;
787
+ const base = `${blocking} blocking finding(s) in ${blockedGates} of ${enforcedGates.length} ` +
788
+ `enforced gate(s).${aside}`;
577
789
  return advisory
578
790
  ? `verdict: exit 0, ${base} Findings were advisory and did not block, so this run exits 0 rather than 1.`
579
791
  : `verdict: exit 1, ${base}`;
580
792
  }
793
+ // Known advisories already on the base branch, reported and not blocking
794
+ // (the vulnerabilities gate under present-on-base: report). Said on the
795
+ // exit-0 verdict, so a pass that carries them never reads as spotless.
796
+ const reported = presentOnBaseReported(result);
797
+ const presentClause = reported === 0
798
+ ? ''
799
+ : `; ${reported} known ${reported === 1 ? 'vulnerability' : 'vulnerabilities'} already on the ` +
800
+ `base ${reported === 1 ? 'was' : 'were'} reported, not blocking (vulnerabilities: present-on-base: report)`;
581
801
  // Exit 0 with red on the screen above it. The verdict is the one line
582
802
  // somebody reads when they read nothing else, so it is the line that has
583
803
  // to carry the reason rather than leaving it to the sections.
584
804
  if (clauses.length > 0) {
585
- return (`verdict: exit 0, but ${clauses.join(' and ')}. ` +
805
+ return (`verdict: exit 0, but ${clauses.join(' and ')}${presentClause}. ` +
586
806
  'Those gates have enforce: false in .guardrails.yaml, so nothing here failed the run.');
587
807
  }
588
- return `verdict: exit 0, every enabled gate ran and none blocked.`;
808
+ // "Every enabled gate ran" is only true when each one actually checked
809
+ // something. A gate that was held back, left out, skipped, or found nothing
810
+ // to scan did not, and the sentence a reader reads alone must say so.
811
+ const unchecked = [
812
+ ...result.deferred.map((gate) => `${gate.role} deferred to stage ${gate.stage}`),
813
+ ...result.excluded.map((gate) => `${gate.role} left out by --gate`),
814
+ ...result.treeUnchanged.map((gate) => `${gate.role} skipped, head tree equals the base tree`),
815
+ ...result.skipped.map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`),
816
+ // A gate with nothing to scan, or the intent gate with require-frozen:
817
+ // false running with no contract: it ran and checked nothing.
818
+ ...result.gates.filter(gateCheckedNothing).map(checkedNothingWording),
819
+ ];
820
+ // Every gate that ran checked nothing: the token is nothing-checked (audit
821
+ // finding F4), and the sentence says what the token says.
822
+ if (result.gates.every(gateCheckedNothing)) {
823
+ return `verdict: exit 0, nothing was checked: ${unchecked.join('; ')}.`;
824
+ }
825
+ if (unchecked.length > 0) {
826
+ return ('verdict: exit 0, no gate blocked, but not every enabled gate checked something: ' +
827
+ `${unchecked.join('; ')}${presentClause}.`);
828
+ }
829
+ return `verdict: exit 0, every enabled gate ran and none blocked${presentClause}.`;
589
830
  }
590
831
  /**
591
832
  * Whether this run has nothing at all to report.
@@ -617,12 +858,17 @@ function verdictForRun(result, advisory) {
617
858
  * confusion this family exists to prevent.
618
859
  */
619
860
  function isFullyClean(result) {
620
- if (result.exitCode !== 0 || result.gates.length === 0) {
861
+ // Every gate that ran checked nothing is the nothing-checked token's state
862
+ // (audit finding F4), and a line opening "clean" would contradict it.
863
+ if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing)) {
621
864
  return false;
622
865
  }
623
866
  return result.gates.every((gate) => gate.couldNotRun === null &&
624
867
  (gate.exitCode ?? 0) === 0 &&
625
868
  gate.diagnostics.length === 0 &&
869
+ // A note about an input this run did not use is never folded into the
870
+ // one-line summary, where nobody would see it.
871
+ gate.intent?.note === undefined &&
626
872
  !gate.findings.some((finding) => finding.blocking));
627
873
  }
628
874
  /**
@@ -717,6 +963,13 @@ function summaryLine(result) {
717
963
  else {
718
964
  parts.push('0 gate(s) not enforced.');
719
965
  }
966
+ // Gates the policy file switches off. Only when there are some: a count of
967
+ // zero here would be noise on the line a hook prints on every commit.
968
+ const disabled = result.disabled ?? [];
969
+ if (disabled.length > 0) {
970
+ const names = disabled.map((gate) => `${gate.role} (${gate.product})`).join(', ');
971
+ parts.push(`Disabled (enabled: false in .guardrails.yaml): ${names}.`);
972
+ }
720
973
  // Non-blocking findings are counted rather than hidden, for the same reason
721
974
  // the full report prints the suppressed and ignored counts at zero: they
722
975
  // are things the gates actually said, and a summary that omitted them would
@@ -812,8 +1065,14 @@ export function renderText(result, options = {}) {
812
1065
  // question, what failed the run, and that one is enforced gates only. Two
813
1066
  // different questions, so two numbers, and the section headers and the
814
1067
  // "not enforced" lines are what connect them.
1068
+ // The fixed third line (osv design, section 4.4), printed only when known
1069
+ // advisories were reported and not blocking. The Action copies it to the
1070
+ // job summary when, and only when, line 3 is exactly this shape, so a pass
1071
+ // that carries them does not read as spotless there either.
1072
+ const reported = presentOnBaseReported(result);
815
1073
  const lines = [
816
1074
  ...headerLines(result, options),
1075
+ ...(reported === 0 ? [] : [`present-on-base: ${reported} reported, not blocking`]),
817
1076
  ...refusal,
818
1077
  ...(refusal.length === 0 ? [] : ['']),
819
1078
  `conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
@@ -826,6 +1085,7 @@ export function renderText(result, options = {}) {
826
1085
  ...skippedLines(result),
827
1086
  ...excludedLines(result),
828
1087
  ...treeUnchangedLines(result),
1088
+ ...disabledLines(result),
829
1089
  ];
830
1090
  if (aside.length > 0) {
831
1091
  lines.push('', ...aside);
package/dist/policy.d.ts CHANGED
@@ -83,7 +83,17 @@ export interface GatePolicy {
83
83
  args?: string[];
84
84
  /** Handed to the gate unchanged. */
85
85
  options: Record<string, OptionValue>;
86
+ /**
87
+ * The vulnerabilities gate only, and always set there: whether a finding
88
+ * that is also on the base branch blocks (`block`, the default when the key
89
+ * is absent) or is reported without blocking (`report`). Gate-level beside
90
+ * `enforce`, never under `options`, which are a pure passthrough. Absent on
91
+ * every other gate; a reader of an absent value treats it as `block`.
92
+ */
93
+ presentOnBase?: PresentOnBase;
86
94
  }
95
+ /** The two values of the vulnerabilities gate's present-on-base key. */
96
+ export type PresentOnBase = 'block' | 'report';
87
97
  export interface Policy {
88
98
  version: 1;
89
99
  gates: Partial<Record<GateRole, GatePolicy>>;
package/dist/policy.js CHANGED
@@ -195,13 +195,15 @@ function describeErrors(errors, source) {
195
195
  * Why one reserved key is reserved.
196
196
  *
197
197
  * The general sentence, at the bottom, is that the umbrella writes that exact
198
- * flag itself, and it is true of most of these keys. Three of them are
199
- * reserved for other reasons, and a message giving the wrong reason sends
200
- * somebody to the wrong fix: they go looking in the command line for a flag
201
- * the umbrella never writes, find nothing, and conclude the rejection is a
202
- * bug in this tool. A test in policy.test.ts derives the flags gateArgs
203
- * actually writes and holds this list of exceptions to exactly those three,
204
- * so a fourth cannot be added without saying why.
198
+ * flag itself, and it is true of most of these keys. Two keys are reserved
199
+ * although the umbrella writes no such flag, and that is what
200
+ * policy.test.ts pins: format on vault-guard, and base on intent-guard. The
201
+ * test derives the flags gateArgs actually writes and holds that
202
+ * reserved-without-writing list to exactly those two, so another one cannot
203
+ * be added without saying why. trust-base, and base on dep-guard, get their
204
+ * own messages as well, because the umbrella writes those flags only on some
205
+ * runs and the general sentence would send somebody looking for a flag that
206
+ * is not on the command line of the run they are debugging.
205
207
  */
206
208
  function reservedReason(product, key) {
207
209
  if (key === 'trust-base') {
@@ -313,6 +315,15 @@ export function parsePolicy(text, source) {
313
315
  reservedReason(product, key));
314
316
  }
315
317
  }
318
+ // Only the vulnerabilities gate has a base comparison to apply the key to.
319
+ // On another gate it would read as a promise nothing keeps, so it is
320
+ // refused rather than ignored.
321
+ const presentOnBase = entry['present-on-base'];
322
+ if (presentOnBase !== undefined && role !== 'vulnerabilities') {
323
+ throw new PolicyError(`${source}: gates.${role}.present-on-base is set, but only the vulnerabilities gate ` +
324
+ '(osv-scanner) compares a pull request with its base, so the key has nothing to decide ' +
325
+ `on the ${role} gate. Remove it there.`);
326
+ }
316
327
  const command = entry.command;
317
328
  if (command !== undefined && !path.isAbsolute(command)) {
318
329
  throw new PolicyError(`${source}: gates.${role}.command must be an absolute path, got "${command}". ` +
@@ -336,6 +347,9 @@ export function parsePolicy(text, source) {
336
347
  ...(command === undefined ? {} : { command }),
337
348
  ...(entry.args === undefined ? {} : { args: entry.args }),
338
349
  options,
350
+ // Absent means block: a policy written before the key existed blocks
351
+ // on every known vulnerability, so no policy is loosened by an upgrade.
352
+ ...(role === 'vulnerabilities' ? { presentOnBase: presentOnBase ?? 'block' } : {}),
339
353
  };
340
354
  }
341
355
  return {
@@ -56,11 +56,13 @@ export interface ProductProfile {
56
56
  */
57
57
  stderrError: RegExp | null;
58
58
  /**
59
- * File names the tool is handed one by one, from the repository's tracked
60
- * files, instead of being pointed at a directory to walk. Null for a tool
61
- * that is not handed files.
59
+ * Which tracked files the tool is handed one by one, by base name, instead
60
+ * of being pointed at a directory to walk, and how: `bare` as the path
61
+ * itself, `requirements` as a pip requirements file that must first pass
62
+ * the pin check (src/requirements-pin.ts). Null for a tool that is not
63
+ * handed files.
62
64
  */
63
- lockfileNames: readonly string[] | null;
65
+ lockfileMatcher: ((file: string) => LockfileKind | null) | null;
64
66
  /**
65
67
  * The config can name another file (`[extend] path`) that the tool reads
66
68
  * relative to its working directory. On a pull request every such file is
@@ -84,20 +86,40 @@ export interface ProductProfile {
84
86
  */
85
87
  readsHistory: boolean;
86
88
  }
89
+ /** How a matched file is handed over: as its own path, or as a requirements file. */
90
+ export type LockfileKind = 'bare' | 'requirements';
87
91
  /**
88
- * The lockfiles osv-scanner is handed, matched by base name at any depth
89
- * among the repository's TRACKED files (`git ls-files`).
92
+ * The lockfiles osv-scanner is handed as a bare path, matched by base name at
93
+ * any depth among the repository's TRACKED files (`git ls-files`).
90
94
  *
91
95
  * By name, not by walking the tree, for three reasons: osv-scanner's own walk
92
96
  * skips anything .gitignore matches, tracked or not, so a pull request could
93
97
  * hide a committed lockfile from it with one ignore line; the walk can reach
94
98
  * into node_modules; and an untracked lockfile is not part of what is being
95
- * judged. Only the npm family is listed, because that is the ecosystem this
96
- * family's own dependency gate knows (npm, pnpm, yarn, bun); osv-scanner
97
- * supports more, and a repository whose only lockfile is another ecosystem's
98
- * gets nothing-to-scan until a name is added here.
99
+ * judged.
100
+ *
101
+ * Every name here was handed to osv-scanner 2.4.0 with --lockfile and read
102
+ * (the 2026-10-11 osv design under docs/superpowers/specs, section 2.1). go.sum is deliberately absent: 2.4.0
103
+ * rejects it ("could not determine extractor", exit 127), which would make
104
+ * every Go pull request could-not-run, and go.mod is what it reads for Go.
105
+ *
106
+ * The second group was added on 2026-10-13 (audit finding F3: a tracked
107
+ * mix.lock was neither scanned nor named), each measured the same way
108
+ * against 2.4.0 and read with one or more packages. Measured and NOT added,
109
+ * because 2.4.0 exits 127 on them: Podfile.lock and deno.lock (both are
110
+ * named by the unread-manifests note instead). gradle's
111
+ * verification-metadata.xml is read only inside a `gradle` directory and is
112
+ * matched by `osvLockfileKind` rather than listed here.
99
113
  */
100
114
  export declare const OSV_LOCKFILE_NAMES: readonly string[];
115
+ /**
116
+ * What osv-scanner is handed for a tracked file, or null. Takes the
117
+ * repository-relative path (a bare base name works for every name but one):
118
+ * gradle's verification-metadata.xml is read by osv-scanner 2.4.0 only when
119
+ * its parent directory is `gradle`, and anywhere else it exits 127, so the
120
+ * parent is part of the match for that one file.
121
+ */
122
+ export declare function osvLockfileKind(file: string): LockfileKind | null;
101
123
  /**
102
124
  * The npm gates print a bare version. No capture group on purpose: the runner
103
125
  * has always reported the whole first line minus a leading v, prerelease