@vaultcompass/conductor 0.8.1 → 0.10.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.
@@ -22,7 +22,7 @@
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
26
  import { CONDUCTOR_OWN_REASONS, cleanOutputLine, conductorStatedReason, } from './gate-runner.js';
27
27
  import { isLegacyContractPath } from './intent-prepare.js';
28
28
  function subjectLabel(finding) {
@@ -40,14 +40,157 @@ function subjectLabel(finding) {
40
40
  return '';
41
41
  }
42
42
  }
43
- function findingLines(finding) {
43
+ /**
44
+ * The findings of one section, as the entries a reader sees.
45
+ *
46
+ * For osv-scanner one entry per ADVISORY ON ONE INSTALLED PACKAGE, however
47
+ * many lockfiles carry it: a repository with a dozen lockfiles pinning the
48
+ * same lodash printed the same advisory a dozen times, and the one fact that
49
+ * differed between those lines, the lockfile, is what --verbose lists. Every
50
+ * other gate keeps one entry per finding. Presentation only: the findings
51
+ * themselves, their count, SARIF and the exit decision are all untouched.
52
+ */
53
+ function findingEntries(gate) {
54
+ const sorted = [...gate.findings].sort(compareFindings);
55
+ if (gate.product !== 'osv-scanner') {
56
+ return sorted.map((finding) => [finding]);
57
+ }
58
+ const groups = new Map();
59
+ for (const finding of sorted) {
60
+ const name = finding.subject.kind === 'package' ? finding.subject.name : '';
61
+ const key = JSON.stringify([
62
+ finding.ruleId,
63
+ name,
64
+ finding.details.version ?? null,
65
+ finding.blocking,
66
+ finding.severity,
67
+ finding.details.baseline ?? null,
68
+ ]);
69
+ groups.set(key, [...(groups.get(key) ?? []), finding]);
70
+ }
71
+ return [...groups.values()];
72
+ }
73
+ function isDev(finding) {
74
+ const groups = finding.details.dependencyGroups;
75
+ return Array.isArray(groups) && groups.includes('dev');
76
+ }
77
+ /** The osv-scanner head-line subject: package@installed, the lockfile or the count, the fix, dev. */
78
+ function osvSubject(entry) {
79
+ const first = entry[0];
80
+ const name = first.subject.kind === 'package' ? first.subject.name : '';
81
+ const installed = typeof first.details.version === 'string' ? first.details.version : '';
82
+ const where = entry.length === 1 && first.subject.kind === 'package'
83
+ ? `(${first.subject.manifest})`
84
+ : `${entry.length} lockfiles`;
85
+ const fixed = typeof first.details.fixedVersion === 'string' ? `fix ${first.details.fixedVersion}` : 'no fix listed';
86
+ const dev = entry.filter(isDev).length;
87
+ const devLabel = dev === 0 ? '' : dev === entry.length ? ' dev' : ` dev in ${dev} of ${entry.length}`;
88
+ return `${name}@${installed} ${where} ${fixed}${devLabel}`;
89
+ }
90
+ function shortCommit(value) {
91
+ return typeof value === 'string' && value.length > 0 ? value.slice(0, 7) : null;
92
+ }
93
+ /** gitleaks' own identity for a finding: the commit it was seen in and its fingerprint. */
94
+ function gitleaksLines(finding) {
95
+ const commit = shortCommit(finding.details.commit);
96
+ const parts = [
97
+ ...(commit === null ? [] : [`commit ${commit}`]),
98
+ ...(finding.fingerprint === null ? [] : [`fingerprint ${finding.fingerprint.value}`]),
99
+ ];
100
+ const alsoIn = Array.isArray(finding.details.alsoIn)
101
+ ? finding.details.alsoIn.map(shortCommit).filter((value) => value !== null)
102
+ : [];
103
+ if (alsoIn.length > 0) {
104
+ parts.push(`also in ${alsoIn.join(', ')}`);
105
+ }
106
+ const lines = parts.length === 0 ? [] : [` ${parts.join(' ')}`];
107
+ const twins = finding.details.possiblySameSecretAs;
108
+ if (Array.isArray(twins) && twins.length > 0) {
109
+ lines.push(` possibly the same secret as ${twins.join(', ')} (same rule, file, columns and entropy; ` +
110
+ 'a merge reports a moved line again)');
111
+ }
112
+ return lines;
113
+ }
114
+ /**
115
+ * The umbrella's own finding for a gate that did not complete, whose message
116
+ * is that gate's detail plus its stderr: both already printed in the section
117
+ * just above it. gate-missing is not one, its message carries the install
118
+ * remedy, which the section does not print anywhere else.
119
+ */
120
+ function isRepeatedProblem(finding) {
121
+ return (finding.product === 'conductor' &&
122
+ (finding.ruleId === 'conductor/gate-failed' || finding.ruleId === 'conductor/gate-output-unparseable'));
123
+ }
124
+ function findingLines(entry, verbose, shortProblem) {
125
+ const finding = entry[0];
44
126
  const marker = finding.blocking ? 'BLOCKING' : ' report';
45
127
  const severity = finding.severityIsDerived ? `${finding.severity}*` : finding.severity;
46
- const subject = subjectLabel(finding);
47
- const head = ` ${marker} ${severity.padEnd(9)} ${finding.ruleId}${subject === '' ? '' : ` ${subject}`}`;
48
- return [head, ` ${finding.message}`];
128
+ const subject = finding.product === 'osv-scanner' && finding.subject.kind === 'package' ? osvSubject(entry) : subjectLabel(finding);
129
+ // The vulnerabilities gate's base-comparison label, on a compared
130
+ // pull-request run only: the label is set nowhere else.
131
+ const baseline = finding.details.baseline;
132
+ const label = baseline === 'introduced' || baseline === 'present-on-base' ? ` ${baseline}` : '';
133
+ const head = ` ${marker} ${severity.padEnd(9)} ${finding.ruleId}${subject === '' ? '' : ` ${subject}`}${label}`;
134
+ // A gate that could not run already printed its reason, and the gate's own
135
+ // output, in the lines above this one. The umbrella's finding carries the
136
+ // same two again for SARIF, where they are the only record; here they were
137
+ // the second and third copy of one failure.
138
+ // The unparseable finding keeps the one sentence the section above does not
139
+ // say: whose side the problem is on.
140
+ const message = !shortProblem
141
+ ? finding.message
142
+ : finding.ruleId === 'conductor/gate-output-unparseable'
143
+ ? 'Nothing was verified by this gate; the reason is above. This is the umbrella being out of date with that gate, not a problem in your code.'
144
+ : 'Nothing was verified by this gate; the reason is above.';
145
+ const lines = [head, ` ${message}`];
146
+ if (finding.product === 'gitleaks') {
147
+ lines.push(...gitleaksLines(finding));
148
+ }
149
+ if (verbose && entry.length > 1) {
150
+ const manifests = entry.map((each) => (each.subject.kind === 'package' ? each.subject.manifest : ''));
151
+ lines.push(` lockfiles: ${manifests.join(', ')}`);
152
+ }
153
+ return lines;
154
+ }
155
+ /**
156
+ * How many entries a section prints before it rolls the rest up into one
157
+ * line, unless --verbose. A full-history gitleaks scan or an osv-scanner run
158
+ * over an old lockfile printed six hundred lines on one repository, which
159
+ * buries the verdict and every other gate. Findings past the cap are still
160
+ * findings: they are counted in every number on the report, they are in the
161
+ * SARIF log, --verbose prints them, and the exit code never reads this.
162
+ */
163
+ export const FINDINGS_SHOWN_PER_GATE = 20;
164
+ /**
165
+ * The base comparison under the vulnerabilities gate's threshold line: the
166
+ * ref, the two counts, the base policy and what it means here, then one line
167
+ * per lockfile the comparison was unavailable for. Nothing on a run with no
168
+ * comparison.
169
+ */
170
+ function baseComparisonLines(gate) {
171
+ const comparison = gate.baseComparison;
172
+ if (comparison === undefined) {
173
+ return [];
174
+ }
175
+ const meaning = comparison.policy === 'report' ? 'report (not blocking)' : 'block (blocking)';
176
+ return [
177
+ ` base comparison ${comparison.ref} introduced ${comparison.introduced} ` +
178
+ `present-on-base ${comparison.presentOnBase} present-on-base: ${meaning}`,
179
+ ...comparison.unavailable.map((entry) => ` base comparison unavailable for ${entry.path}: ${entry.reason}; counted as introduced`),
180
+ ];
49
181
  }
50
- function header(gate) {
182
+ /**
183
+ * How many present-on-base findings were reported and NOT blocking, across
184
+ * the gates: the vulnerabilities gate under present-on-base: report. The
185
+ * number on the report's third line and in the exit-0 verdict clause.
186
+ */
187
+ function presentOnBaseReported(result) {
188
+ return result.gates
189
+ .filter((gate) => gate.baseComparison?.policy === 'report')
190
+ .flatMap((gate) => gate.findings)
191
+ .filter((finding) => finding.details.baseline === 'present-on-base' && !finding.blocking).length;
192
+ }
193
+ function header(gate, verbose) {
51
194
  const version = gate.productVersion === null ? '(version unknown)' : gate.productVersion;
52
195
  // On the header line rather than only at the bottom of the section: a
53
196
  // reader scanning headers for the gate that refused their commit has to
@@ -57,7 +200,10 @@ function header(gate) {
57
200
  return `${gate.role} ${gate.product} ${version} DID NOT RUN (${gate.couldNotRun.reason})${enforcement}`;
58
201
  }
59
202
  const source = gate.binary === null ? '' : ` via ${gate.binary.candidate} on ${gate.binary.source}`;
60
- return `${gate.role} ${gate.product} ${version} exit ${gate.exitCode ?? '?'} ${gate.durationMs}ms${source}${enforcement}`;
203
+ // Only with --verbose, and only a limit the policy set: a default is the
204
+ // same on every run and says nothing about this repository.
205
+ const limit = verbose && gate.timeLimit?.source === 'policy' ? ` limit ${Math.round(gate.timeLimit.ms / 1000)}s (policy)` : '';
206
+ return `${gate.role} ${gate.product} ${version} exit ${gate.exitCode ?? '?'} ${gate.durationMs}ms${limit}${source}${enforcement}`;
61
207
  }
62
208
  /**
63
209
  * The line that keeps a green exit from being a surprise.
@@ -75,7 +221,7 @@ function enforcementNote(gate) {
75
221
  'so it is a note here rather than a failed run. Nothing was checked by it.');
76
222
  }
77
223
  const blocking = gate.findings.filter((finding) => finding.blocking).length;
78
- if (blocking > 0 || (gate.exitCode ?? 0) !== 0) {
224
+ if (blocking > 0 || gateExitBlocks(gate)) {
79
225
  return (` not enforced: this gate reported ${blocking} blocking finding(s) and exited ` +
80
226
  `${gate.exitCode ?? '?'}, and enforce is false for it in .guardrails.yaml, so the commit ` +
81
227
  'proceeds. Set enforce: true there to make it block.');
@@ -108,8 +254,21 @@ function contractLine(gate) {
108
254
  const base = gate.intent.baseRef === null ? 'base: none, the git index' : `base: ${gate.intent.baseRef}`;
109
255
  return ` contract: ${where} ${base}`;
110
256
  }
111
- function gateSection(gate) {
112
- const lines = ['', header(gate)];
257
+ function gateSection(gate, verbose, refusedOnTerminal = false) {
258
+ // A gate the refused trust base stopped, on a terminal: the refusal is at
259
+ // the top of the report once, so the section is one line and no more.
260
+ // Every other caller (a file, a pipe, a pull request comment) keeps the full
261
+ // section, byte for byte.
262
+ if (refusedOnTerminal) {
263
+ return [` ${gate.role} ${gate.product} did not run: the trust base was refused (above)`];
264
+ }
265
+ const lines = ['', header(gate, verbose)];
266
+ // Under the header, on every outcome that carries it: gitleaks' own
267
+ // --timeout is not conductor's limit, and the gate-error it produces is the
268
+ // outcome a reader most needs this on.
269
+ if (gate.gateOwnOption !== undefined) {
270
+ lines.push(` note conductor/option-is-gate-own: ${gate.gateOwnOption}`);
271
+ }
113
272
  const contract = contractLine(gate);
114
273
  if (contract !== null) {
115
274
  lines.push(contract);
@@ -123,6 +282,11 @@ function gateSection(gate) {
123
282
  lines.push(` gate said: "${gate.couldNotRun.gateSaid}"`);
124
283
  }
125
284
  if (gate.stderr.trim().length > 0) {
285
+ if (gate.couldNotRun.reason === 'timed-out') {
286
+ // What a stopped gate printed is often a warning that has nothing to
287
+ // do with the stop; the line above is the reason.
288
+ lines.push(' (printed by the gate before it was stopped; not the reason it stopped)');
289
+ }
126
290
  for (const line of gate.stderr.trim().split('\n')) {
127
291
  lines.push(` | ${cleanOutputLine(line)}`);
128
292
  }
@@ -130,9 +294,17 @@ function gateSection(gate) {
130
294
  }
131
295
  // Sorted here rather than relying on the order the gate happened to emit:
132
296
  // blocking first, then by severity. A section whose first line is a low
133
- // finding buries the one that just refused a commit.
134
- for (const finding of [...gate.findings].sort(compareFindings)) {
135
- lines.push(...findingLines(finding));
297
+ // finding buries the one that just refused a commit. The cap keeps that
298
+ // order, so what it rolls up is always the least severe.
299
+ const entries = findingEntries(gate);
300
+ const shown = verbose ? entries : entries.slice(0, FINDINGS_SHOWN_PER_GATE);
301
+ for (const entry of shown) {
302
+ lines.push(...findingLines(entry, verbose, gate.couldNotRun !== null && isRepeatedProblem(entry[0])));
303
+ }
304
+ const hidden = entries.slice(shown.length).reduce((total, entry) => total + entry.length, 0);
305
+ if (hidden > 0) {
306
+ lines.push(` ${hidden} more finding(s) in this gate, not shown here: re-run with --verbose, or read the ` +
307
+ 'SARIF report (--format sarif). They count toward everything on this report.');
136
308
  }
137
309
  if (gate.couldNotRun === null) {
138
310
  const threshold = gate.run.failOn === null ? 'threshold not reported' : `threshold ${gate.run.failOn}`;
@@ -143,6 +315,7 @@ function gateSection(gate) {
143
315
  ? 'ignored not reported'
144
316
  : `ignored ${gate.run.ignored}`;
145
317
  lines.push(` ${threshold} suppressed ${gate.run.suppressed} ${ignored}`);
318
+ lines.push(...baseComparisonLines(gate));
146
319
  // The gate's own run facts: what it scanned, with what, against what.
147
320
  // These were being collected and then dropped.
148
321
  //
@@ -225,6 +398,13 @@ function skipWording(reason) {
225
398
  function excludedLines(result) {
226
399
  return result.excluded.map((gate) => ` excluded ${gate.role} ${gate.product} did not run here; --gate did not name it`);
227
400
  }
401
+ /**
402
+ * One line per gate the policy file switches off with enabled: false, so an
403
+ * adopter sees what is not running at all. Absent when none is.
404
+ */
405
+ function disabledLines(result) {
406
+ return (result.disabled ?? []).map((gate) => ` disabled ${gate.role} ${gate.product} enabled: false in .guardrails.yaml; it did not run`);
407
+ }
228
408
  /**
229
409
  * One line per gate skipped because the head tree equals the trust base's
230
410
  * (issue #69).
@@ -348,7 +528,7 @@ function unenforcedClauses(result) {
348
528
  // blocking finding" reports the same gate as having blocked AND as having
349
529
  // failed to run, which are opposite claims.
350
530
  const blocked = unenforced.filter((gate) => gate.couldNotRun === null &&
351
- ((gate.exitCode ?? 0) !== 0 || gate.findings.some((finding) => finding.blocking)));
531
+ (gateExitBlocks(gate) || gate.findings.some((finding) => finding.blocking)));
352
532
  const broken = unenforced.filter((gate) => gate.couldNotRun !== null);
353
533
  const clauses = [];
354
534
  if (blocked.length > 0) {
@@ -434,7 +614,17 @@ export function jobLogSummary(result) {
434
614
  * Describes, decides nothing: every word is read off the outcomes the exit
435
615
  * code was already composed from. Same plain ASCII as the rest of this file.
436
616
  */
437
- export function gateLogLines(result) {
617
+ export function gateLogLines(result, options = {}) {
618
+ // On a terminal a refused run's per-gate lines are the refusal sentence once
619
+ // per gate, under a report that already led with it. One line instead; a
620
+ // job log (never a terminal) keeps one line per gate.
621
+ const refusal = result.trustBase?.refusal;
622
+ if (options.terminal === true && refusal !== undefined && refusal !== null && result.gates.length > 0) {
623
+ return [
624
+ `conductor: the trust base was refused, so no gate ran: ` +
625
+ `${result.gates.map((gate) => `${gate.role} (${gate.product})`).join(', ')}; could-not-run, no exit code`,
626
+ ];
627
+ }
438
628
  const lines = [];
439
629
  for (const gate of result.gates) {
440
630
  const version = gate.productVersion === null ? 'version unknown' : gate.productVersion;
@@ -452,6 +642,11 @@ export function gateLogLines(result) {
452
642
  const blocking = gate.findings.filter((finding) => finding.blocking).length;
453
643
  outcome =
454
644
  total === 0 && (gate.exitCode ?? 0) === 0 ? 'ok' : `findings (${total}, ${blocking} blocking)`;
645
+ // Only when the gate said so; the outcome word above is unchanged.
646
+ const coverage = deadlineCoverage(gate);
647
+ if (coverage !== null) {
648
+ outcome += `, ${coverage}`;
649
+ }
455
650
  }
456
651
  // conductor's own refusals (a git below the floor, a path list it cannot
457
652
  // pass, a PATH or git-directory failure, a gate below its minimum) carry
@@ -516,7 +711,7 @@ function blockingCount(gate) {
516
711
  return 0;
517
712
  }
518
713
  const blocking = gate.findings.filter((finding) => finding.blocking).length;
519
- return blocking === 0 && (gate.exitCode ?? 0) !== 0 ? 1 : blocking;
714
+ return blocking === 0 && gateExitBlocks(gate) ? 1 : blocking;
520
715
  }
521
716
  /**
522
717
  * The verdict token: a label for the umbrella's OWN exit decision, in a
@@ -524,8 +719,11 @@ function blockingCount(gate) {
524
719
  * the state without parsing the verdict sentence.
525
720
  *
526
721
  * pass exit 0 and nothing was hidden by it
527
- * nothing-checked exit 0, but no gate ran at all (none enabled,
528
- * or every one deferred, tree-unchanged or skipped)
722
+ * nothing-checked exit 0, but nothing was checked: no gate ran at
723
+ * all (none enabled, or every one deferred,
724
+ * tree-unchanged or skipped), or every gate that
725
+ * ran checked nothing (nothing to scan, or no
726
+ * contract; audit finding F4)
529
727
  * advisory-blocked (N) exit 1 that --advisory turned into exit 0
530
728
  * unenforced-findings (N) exit 0, but enforce: false gates blocked or
531
729
  * could not run
@@ -574,7 +772,49 @@ export function verdictToken(result, advisory) {
574
772
  const unenforced = result.gates
575
773
  .filter((gate) => !gate.enforce)
576
774
  .reduce((total, gate) => total + (gate.couldNotRun !== null ? 1 : blockingCount(gate)), 0);
577
- return unenforced > 0 ? `unenforced-findings (${unenforced})` : 'pass';
775
+ if (unenforced > 0) {
776
+ return `unenforced-findings (${unenforced})`;
777
+ }
778
+ // Exit 0 where every gate that RAN checked nothing (audit finding F4): the
779
+ // vulnerabilities gate with no lockfile it reads, an intent gate with no
780
+ // contract. Gates ran, so the rule above does not fire, but nothing was
781
+ // examined, and a pass here is the same false statement as a pass with no
782
+ // gate at all. Same token, same exit code (0), same predicate the verdict
783
+ // sentence uses, so the two cannot disagree.
784
+ return result.gates.every(gateCheckedNothing) ? 'nothing-checked' : 'pass';
785
+ }
786
+ /**
787
+ * A gate that ran and examined nothing: osv-scanner with nothing to scan,
788
+ * osv-scanner whose every handed lockfile parsed to no packages (exit 128,
789
+ * marked `packages-read 0`; a sole lockfile rewritten to {} is exactly the
790
+ * same news as no lockfile), or an intent gate that found no contract to
791
+ * check against. The one predicate behind both the verdict token and the
792
+ * verdict sentence's list of what was not checked.
793
+ *
794
+ * NOT the partial-empty case: `conductor/lockfiles-empty` is also raised
795
+ * when osv-scanner read packages from other lockfiles (audit finding F2),
796
+ * and that gate checked something. Only the `packages-read` marker, which
797
+ * the exit-128 branch alone writes, tells the two apart.
798
+ */
799
+ function readNoPackages(gate) {
800
+ return gate.run.details['packages-read'] === 0;
801
+ }
802
+ function gateCheckedNothing(gate) {
803
+ if (gate.couldNotRun !== null) {
804
+ return false;
805
+ }
806
+ return (gate.diagnostics.some((d) => d.code === 'conductor/nothing-to-scan') ||
807
+ readNoPackages(gate) ||
808
+ (gate.role === 'intent' && gate.run.details.contractFound === false));
809
+ }
810
+ /** How the verdict sentence names a gate that ran and checked nothing. */
811
+ function checkedNothingWording(gate) {
812
+ if (gate.role === 'intent') {
813
+ return `${gate.role} ran but found no contract to check against`;
814
+ }
815
+ return readNoPackages(gate)
816
+ ? `${gate.role} read no packages from its lockfiles`
817
+ : `${gate.role} had nothing to scan`;
578
818
  }
579
819
  function verdict(result, advisory) {
580
820
  const refusal = result.trustBase?.refusal;
@@ -685,7 +925,7 @@ function verdictForRun(result, advisory) {
685
925
  // explicitly says there is none of, so it gets its own, narrower
686
926
  // wording that is true here and says nothing about findings at all.
687
927
  const names = enforcedGates
688
- .filter((gate) => (gate.exitCode ?? 0) !== 0)
928
+ .filter((gate) => gateExitBlocks(gate))
689
929
  .map((gate) => `${gate.role} (exit ${gate.exitCode ?? '?'})`)
690
930
  .join(', ');
691
931
  const base = `and no finding here is marked blocking. Enforced gate(s) that exited ` +
@@ -695,19 +935,52 @@ function verdictForRun(result, advisory) {
695
935
  ? `verdict: exit 0, ${base} This run was advisory, so exit 1 became exit 0.`
696
936
  : `verdict: exit 1, ${base}`;
697
937
  }
698
- const base = `${blocking} blocking finding(s) across ${enforcedGates.length} gate(s).${aside}`;
938
+ // Gates that blocked out of gates that could have, not a bare count of
939
+ // the enforced ones, which read as if every one of them had blocked.
940
+ const blockedGates = enforcedGates.filter((gate) => blockingCount(gate) > 0).length;
941
+ const base = `${blocking} blocking finding(s) in ${blockedGates} of ${enforcedGates.length} ` +
942
+ `enforced gate(s).${aside}`;
699
943
  return advisory
700
944
  ? `verdict: exit 0, ${base} Findings were advisory and did not block, so this run exits 0 rather than 1.`
701
945
  : `verdict: exit 1, ${base}`;
702
946
  }
947
+ // Known advisories already on the base branch, reported and not blocking
948
+ // (the vulnerabilities gate under present-on-base: report). Said on the
949
+ // exit-0 verdict, so a pass that carries them never reads as spotless.
950
+ const reported = presentOnBaseReported(result);
951
+ const presentClause = reported === 0
952
+ ? ''
953
+ : `; ${reported} known ${reported === 1 ? 'vulnerability' : 'vulnerabilities'} already on the ` +
954
+ `base ${reported === 1 ? 'was' : 'were'} reported, not blocking (vulnerabilities: present-on-base: report)`;
703
955
  // Exit 0 with red on the screen above it. The verdict is the one line
704
956
  // somebody reads when they read nothing else, so it is the line that has
705
957
  // to carry the reason rather than leaving it to the sections.
706
958
  if (clauses.length > 0) {
707
- return (`verdict: exit 0, but ${clauses.join(' and ')}. ` +
959
+ return (`verdict: exit 0, but ${clauses.join(' and ')}${presentClause}. ` +
708
960
  'Those gates have enforce: false in .guardrails.yaml, so nothing here failed the run.');
709
961
  }
710
- return `verdict: exit 0, every enabled gate ran and none blocked.`;
962
+ // "Every enabled gate ran" is only true when each one actually checked
963
+ // something. A gate that was held back, left out, skipped, or found nothing
964
+ // to scan did not, and the sentence a reader reads alone must say so.
965
+ const unchecked = [
966
+ ...result.deferred.map((gate) => `${gate.role} deferred to stage ${gate.stage}`),
967
+ ...result.excluded.map((gate) => `${gate.role} left out by --gate`),
968
+ ...result.treeUnchanged.map((gate) => `${gate.role} skipped, head tree equals the base tree`),
969
+ ...result.skipped.map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`),
970
+ // A gate with nothing to scan, or the intent gate with require-frozen:
971
+ // false running with no contract: it ran and checked nothing.
972
+ ...result.gates.filter(gateCheckedNothing).map(checkedNothingWording),
973
+ ];
974
+ // Every gate that ran checked nothing: the token is nothing-checked (audit
975
+ // finding F4), and the sentence says what the token says.
976
+ if (result.gates.every(gateCheckedNothing)) {
977
+ return `verdict: exit 0, nothing was checked: ${unchecked.join('; ')}.`;
978
+ }
979
+ if (unchecked.length > 0) {
980
+ return ('verdict: exit 0, no gate blocked, but not every enabled gate checked something: ' +
981
+ `${unchecked.join('; ')}${presentClause}.`);
982
+ }
983
+ return `verdict: exit 0, every enabled gate ran and none blocked${presentClause}.`;
711
984
  }
712
985
  /**
713
986
  * Whether this run has nothing at all to report.
@@ -739,7 +1012,9 @@ function verdictForRun(result, advisory) {
739
1012
  * confusion this family exists to prevent.
740
1013
  */
741
1014
  function isFullyClean(result) {
742
- if (result.exitCode !== 0 || result.gates.length === 0) {
1015
+ // Every gate that ran checked nothing is the nothing-checked token's state
1016
+ // (audit finding F4), and a line opening "clean" would contradict it.
1017
+ if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing)) {
743
1018
  return false;
744
1019
  }
745
1020
  return result.gates.every((gate) => gate.couldNotRun === null &&
@@ -750,6 +1025,32 @@ function isFullyClean(result) {
750
1025
  gate.intent?.note === undefined &&
751
1026
  !gate.findings.some((finding) => finding.blocking));
752
1027
  }
1028
+ /**
1029
+ * dep-guard's own diagnostic code for an online budget that ran out before
1030
+ * every lookup was made (dep-guard core, online/deadline.ts,
1031
+ * ONLINE_DEADLINE_CODE). Read, never minted: the umbrella only repeats it.
1032
+ */
1033
+ export const DEP_GUARD_DEADLINE_CODE = 'online-deadline-exceeded';
1034
+ /**
1035
+ * The coverage clause for a dep-guard run whose online lookups were cut short
1036
+ * by its own deadline, or null. Not a verdict: dep-guard still exits 0 for
1037
+ * this and so does the run; the clause exists because a summary that read
1038
+ * "ok" while some names were never looked up overstated what was checked.
1039
+ */
1040
+ function deadlineCoverage(gate) {
1041
+ if (gate.product !== 'dep-guard' || gate.couldNotRun !== null) {
1042
+ return null;
1043
+ }
1044
+ const said = gate.run.diagnostics.some((diagnostic) => diagnostic.code === DEP_GUARD_DEADLINE_CODE);
1045
+ const skipped = gate.run.details['skipped-by-deadline'];
1046
+ const count = typeof skipped === 'number' ? skipped : null;
1047
+ if (!said && (count === null || count === 0)) {
1048
+ return null;
1049
+ }
1050
+ return count === null || count === 0
1051
+ ? `online lookups incomplete (${DEP_GUARD_DEADLINE_CODE})`
1052
+ : `online lookups incomplete, ${count} skipped by the deadline (${DEP_GUARD_DEADLINE_CODE})`;
1053
+ }
753
1054
  /**
754
1055
  * The gates' own notes, and only those.
755
1056
  *
@@ -842,6 +1143,13 @@ function summaryLine(result) {
842
1143
  else {
843
1144
  parts.push('0 gate(s) not enforced.');
844
1145
  }
1146
+ // Gates the policy file switches off. Only when there are some: a count of
1147
+ // zero here would be noise on the line a hook prints on every commit.
1148
+ const disabled = result.disabled ?? [];
1149
+ if (disabled.length > 0) {
1150
+ const names = disabled.map((gate) => `${gate.role} (${gate.product})`).join(', ');
1151
+ parts.push(`Disabled (enabled: false in .guardrails.yaml): ${names}.`);
1152
+ }
845
1153
  // Non-blocking findings are counted rather than hidden, for the same reason
846
1154
  // the full report prints the suppressed and ignored counts at zero: they
847
1155
  // are things the gates actually said, and a summary that omitted them would
@@ -857,6 +1165,14 @@ function summaryLine(result) {
857
1165
  if (counts.length > 0) {
858
1166
  parts.push(`${counts.join(', ')}.`);
859
1167
  }
1168
+ // A clean run whose dependency gate did not finish its online lookups is
1169
+ // still exit 0, and still this line, but it says so in words.
1170
+ for (const gate of result.gates) {
1171
+ const coverage = deadlineCoverage(gate);
1172
+ if (coverage !== null) {
1173
+ parts.push(`${gate.role} (${gate.product}): ${coverage}.`);
1174
+ }
1175
+ }
860
1176
  // The suppressed and ignored counts the gates reported, summed across them
861
1177
  // and printed even at zero. The full report prints these per gate for the
862
1178
  // same reason, so a quiet report is not mistaken for a clean one; the clean
@@ -937,20 +1253,31 @@ export function renderText(result, options = {}) {
937
1253
  // question, what failed the run, and that one is enforced gates only. Two
938
1254
  // different questions, so two numbers, and the section headers and the
939
1255
  // "not enforced" lines are what connect them.
1256
+ // The fixed third line (osv design, section 4.4), printed only when known
1257
+ // advisories were reported and not blocking. The Action copies it to the
1258
+ // job summary when, and only when, line 3 is exactly this shape, so a pass
1259
+ // that carries them does not read as spotless there either.
1260
+ const reported = presentOnBaseReported(result);
940
1261
  const lines = [
941
1262
  ...headerLines(result, options),
1263
+ ...(reported === 0 ? [] : [`present-on-base: ${reported} reported, not blocking`]),
942
1264
  ...refusal,
943
1265
  ...(refusal.length === 0 ? [] : ['']),
944
1266
  `conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
945
1267
  ];
1268
+ const refusedOnTerminal = options.terminal === true && refusal.length > 0;
1269
+ if (refusedOnTerminal && result.gates.length > 0) {
1270
+ lines.push('');
1271
+ }
946
1272
  for (const gate of result.gates) {
947
- lines.push(...gateSection(gate));
1273
+ lines.push(...gateSection(gate, Boolean(options.verbose), refusedOnTerminal));
948
1274
  }
949
1275
  const aside = [
950
1276
  ...deferredLines(result),
951
1277
  ...skippedLines(result),
952
1278
  ...excludedLines(result),
953
1279
  ...treeUnchangedLines(result),
1280
+ ...disabledLines(result),
954
1281
  ];
955
1282
  if (aside.length > 0) {
956
1283
  lines.push('', ...aside);
@@ -962,7 +1289,8 @@ export function renderText(result, options = {}) {
962
1289
  // A derived severity is marked with a trailing asterisk above; say what
963
1290
  // that means rather than leaving a reader to guess, and only when one is
964
1291
  // actually on screen.
965
- if (result.findings.some((finding) => finding.severityIsDerived)) {
1292
+ // A compact terminal refusal prints no finding line at all, so no asterisk.
1293
+ if (!refusedOnTerminal && result.findings.some((finding) => finding.severityIsDerived)) {
966
1294
  lines.push('', '* severity assigned by the umbrella; that gate reports no per-finding severity.');
967
1295
  }
968
1296
  lines.push('', verdict(result, Boolean(options.advisory)));
package/dist/policy.d.ts CHANGED
@@ -83,7 +83,25 @@ 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;
94
+ /**
95
+ * conductor's own time limit for this gate, in whole seconds (10 to 21600,
96
+ * the schema's bounds). Set only when the policy names the key; absent
97
+ * means the product's profile default (src/products.ts). Gate-level beside
98
+ * `enforce`, never under `options`. Resolved, with the test hook, by
99
+ * `resolveTimeLimit` in src/gate-runner.ts and nowhere else.
100
+ */
101
+ timeoutSeconds?: number;
86
102
  }
103
+ /** The two values of the vulnerabilities gate's present-on-base key. */
104
+ export type PresentOnBase = 'block' | 'report';
87
105
  export interface Policy {
88
106
  version: 1;
89
107
  gates: Partial<Record<GateRole, GatePolicy>>;