@vaultcompass/conductor 0.9.0 → 0.11.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.
@@ -24,7 +24,8 @@
24
24
  import { compareFindings } from './envelope.js';
25
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
- import { isLegacyContractPath } from './intent-prepare.js';
27
+ import { isLegacyContractPath, legacyChangedSentence } from './intent-prepare.js';
28
+ import { SPEC_DIR } from './intent-spec.js';
28
29
  function subjectLabel(finding) {
29
30
  const subject = finding.subject;
30
31
  switch (subject.kind) {
@@ -40,17 +41,127 @@ function subjectLabel(finding) {
40
41
  return '';
41
42
  }
42
43
  }
43
- function findingLines(finding) {
44
+ /**
45
+ * The findings of one section, as the entries a reader sees.
46
+ *
47
+ * For osv-scanner one entry per ADVISORY ON ONE INSTALLED PACKAGE, however
48
+ * many lockfiles carry it: a repository with a dozen lockfiles pinning the
49
+ * same lodash printed the same advisory a dozen times, and the one fact that
50
+ * differed between those lines, the lockfile, is what --verbose lists. Every
51
+ * other gate keeps one entry per finding. Presentation only: the findings
52
+ * themselves, their count, SARIF and the exit decision are all untouched.
53
+ */
54
+ function findingEntries(gate) {
55
+ const sorted = [...gate.findings].sort(compareFindings);
56
+ if (gate.product !== 'osv-scanner') {
57
+ return sorted.map((finding) => [finding]);
58
+ }
59
+ const groups = new Map();
60
+ for (const finding of sorted) {
61
+ const name = finding.subject.kind === 'package' ? finding.subject.name : '';
62
+ const key = JSON.stringify([
63
+ finding.ruleId,
64
+ name,
65
+ finding.details.version ?? null,
66
+ finding.blocking,
67
+ finding.severity,
68
+ finding.details.baseline ?? null,
69
+ ]);
70
+ groups.set(key, [...(groups.get(key) ?? []), finding]);
71
+ }
72
+ return [...groups.values()];
73
+ }
74
+ function isDev(finding) {
75
+ const groups = finding.details.dependencyGroups;
76
+ return Array.isArray(groups) && groups.includes('dev');
77
+ }
78
+ /** The osv-scanner head-line subject: package@installed, the lockfile or the count, the fix, dev. */
79
+ function osvSubject(entry) {
80
+ const first = entry[0];
81
+ const name = first.subject.kind === 'package' ? first.subject.name : '';
82
+ const installed = typeof first.details.version === 'string' ? first.details.version : '';
83
+ const where = entry.length === 1 && first.subject.kind === 'package'
84
+ ? `(${first.subject.manifest})`
85
+ : `${entry.length} lockfiles`;
86
+ const fixed = typeof first.details.fixedVersion === 'string' ? `fix ${first.details.fixedVersion}` : 'no fix listed';
87
+ const dev = entry.filter(isDev).length;
88
+ const devLabel = dev === 0 ? '' : dev === entry.length ? ' dev' : ` dev in ${dev} of ${entry.length}`;
89
+ return `${name}@${installed} ${where} ${fixed}${devLabel}`;
90
+ }
91
+ function shortCommit(value) {
92
+ return typeof value === 'string' && value.length > 0 ? value.slice(0, 7) : null;
93
+ }
94
+ /** gitleaks' own identity for a finding: the commit it was seen in and its fingerprint. */
95
+ function gitleaksLines(finding) {
96
+ const commit = shortCommit(finding.details.commit);
97
+ const parts = [
98
+ ...(commit === null ? [] : [`commit ${commit}`]),
99
+ ...(finding.fingerprint === null ? [] : [`fingerprint ${finding.fingerprint.value}`]),
100
+ ];
101
+ const alsoIn = Array.isArray(finding.details.alsoIn)
102
+ ? finding.details.alsoIn.map(shortCommit).filter((value) => value !== null)
103
+ : [];
104
+ if (alsoIn.length > 0) {
105
+ parts.push(`also in ${alsoIn.join(', ')}`);
106
+ }
107
+ const lines = parts.length === 0 ? [] : [` ${parts.join(' ')}`];
108
+ const twins = finding.details.possiblySameSecretAs;
109
+ if (Array.isArray(twins) && twins.length > 0) {
110
+ lines.push(` possibly the same secret as ${twins.join(', ')} (same rule, file, columns and entropy; ` +
111
+ 'a merge reports a moved line again)');
112
+ }
113
+ return lines;
114
+ }
115
+ /**
116
+ * The umbrella's own finding for a gate that did not complete, whose message
117
+ * is that gate's detail plus its stderr: both already printed in the section
118
+ * just above it. gate-missing is not one, its message carries the install
119
+ * remedy, which the section does not print anywhere else.
120
+ */
121
+ function isRepeatedProblem(finding) {
122
+ return (finding.product === 'conductor' &&
123
+ (finding.ruleId === 'conductor/gate-failed' || finding.ruleId === 'conductor/gate-output-unparseable'));
124
+ }
125
+ function findingLines(entry, verbose, shortProblem) {
126
+ const finding = entry[0];
44
127
  const marker = finding.blocking ? 'BLOCKING' : ' report';
45
128
  const severity = finding.severityIsDerived ? `${finding.severity}*` : finding.severity;
46
- const subject = subjectLabel(finding);
129
+ const subject = finding.product === 'osv-scanner' && finding.subject.kind === 'package' ? osvSubject(entry) : subjectLabel(finding);
47
130
  // The vulnerabilities gate's base-comparison label, on a compared
48
131
  // pull-request run only: the label is set nowhere else.
49
132
  const baseline = finding.details.baseline;
50
133
  const label = baseline === 'introduced' || baseline === 'present-on-base' ? ` ${baseline}` : '';
51
134
  const head = ` ${marker} ${severity.padEnd(9)} ${finding.ruleId}${subject === '' ? '' : ` ${subject}`}${label}`;
52
- return [head, ` ${finding.message}`];
135
+ // A gate that could not run already printed its reason, and the gate's own
136
+ // output, in the lines above this one. The umbrella's finding carries the
137
+ // same two again for SARIF, where they are the only record; here they were
138
+ // the second and third copy of one failure.
139
+ // The unparseable finding keeps the one sentence the section above does not
140
+ // say: whose side the problem is on.
141
+ const message = !shortProblem
142
+ ? finding.message
143
+ : finding.ruleId === 'conductor/gate-output-unparseable'
144
+ ? '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.'
145
+ : 'Nothing was verified by this gate; the reason is above.';
146
+ const lines = [head, ` ${message}`];
147
+ if (finding.product === 'gitleaks') {
148
+ lines.push(...gitleaksLines(finding));
149
+ }
150
+ if (verbose && entry.length > 1) {
151
+ const manifests = entry.map((each) => (each.subject.kind === 'package' ? each.subject.manifest : ''));
152
+ lines.push(` lockfiles: ${manifests.join(', ')}`);
153
+ }
154
+ return lines;
53
155
  }
156
+ /**
157
+ * How many entries a section prints before it rolls the rest up into one
158
+ * line, unless --verbose. A full-history gitleaks scan or an osv-scanner run
159
+ * over an old lockfile printed six hundred lines on one repository, which
160
+ * buries the verdict and every other gate. Findings past the cap are still
161
+ * findings: they are counted in every number on the report, they are in the
162
+ * SARIF log, --verbose prints them, and the exit code never reads this.
163
+ */
164
+ export const FINDINGS_SHOWN_PER_GATE = 20;
54
165
  /**
55
166
  * The base comparison under the vulnerabilities gate's threshold line: the
56
167
  * ref, the two counts, the base policy and what it means here, then one line
@@ -80,7 +191,7 @@ function presentOnBaseReported(result) {
80
191
  .flatMap((gate) => gate.findings)
81
192
  .filter((finding) => finding.details.baseline === 'present-on-base' && !finding.blocking).length;
82
193
  }
83
- function header(gate) {
194
+ function header(gate, verbose) {
84
195
  const version = gate.productVersion === null ? '(version unknown)' : gate.productVersion;
85
196
  // On the header line rather than only at the bottom of the section: a
86
197
  // reader scanning headers for the gate that refused their commit has to
@@ -90,7 +201,10 @@ function header(gate) {
90
201
  return `${gate.role} ${gate.product} ${version} DID NOT RUN (${gate.couldNotRun.reason})${enforcement}`;
91
202
  }
92
203
  const source = gate.binary === null ? '' : ` via ${gate.binary.candidate} on ${gate.binary.source}`;
93
- return `${gate.role} ${gate.product} ${version} exit ${gate.exitCode ?? '?'} ${gate.durationMs}ms${source}${enforcement}`;
204
+ // Only with --verbose, and only a limit the policy set: a default is the
205
+ // same on every run and says nothing about this repository.
206
+ const limit = verbose && gate.timeLimit?.source === 'policy' ? ` limit ${Math.round(gate.timeLimit.ms / 1000)}s (policy)` : '';
207
+ return `${gate.role} ${gate.product} ${version} exit ${gate.exitCode ?? '?'} ${gate.durationMs}ms${limit}${source}${enforcement}`;
94
208
  }
95
209
  /**
96
210
  * The line that keeps a green exit from being a surprise.
@@ -141,14 +255,80 @@ function contractLine(gate) {
141
255
  const base = gate.intent.baseRef === null ? 'base: none, the git index' : `base: ${gate.intent.baseRef}`;
142
256
  return ` contract: ${where} ${base}`;
143
257
  }
144
- function gateSection(gate) {
145
- const lines = ['', header(gate)];
258
+ /** The convention match behind a gate's contract, when the branch name chose it. */
259
+ export function conventionMatch(gate) {
260
+ const source = gate.intent?.contractSource;
261
+ return source?.kind === 'imported' && source.match !== undefined ? source.match : null;
262
+ }
263
+ /**
264
+ * The weak-match line, printed under the contract line in every report.
265
+ *
266
+ * The shared words are charset-restricted tokens (isSignificant in
267
+ * intent-spec.ts), so nothing the branch was called beyond them reaches this
268
+ * line, and the runner-up is a filename the specs directory listed.
269
+ */
270
+ function weakMatchLine(match) {
271
+ const words = (list) => list.map((word) => `"${word}"`).join(', ');
272
+ const why = match.weakBecause.includes('length-tiebreak') && match.runnerUp !== null
273
+ ? `the branch name shares ${words(match.shared)} with this spec and ` +
274
+ `${words(match.runnerUpShared)} with ${SPEC_DIR}/${match.runnerUp}; the longer word decided it.`
275
+ : `the branch name shares only ${words(match.shared)} with this spec's name.`;
276
+ const remedy = match.remedy === 'pr-body'
277
+ ? 'To be sure this is the right contract, add a "Spec: <path>" line to the pull request body ' +
278
+ "or rename the branch to the spec's name."
279
+ : "To be sure this is the right contract, pass --spec <path> or rename the branch to the spec's name.";
280
+ return ` match: weak, ${why} ${remedy}`;
281
+ }
282
+ /**
283
+ * The lines a convention match adds to the gate block: the weak line and the
284
+ * changed-winner note, printed in every report, and the chosen-by line,
285
+ * printed for every strength under --verbose so a strong or exact choice is
286
+ * visible too.
287
+ */
288
+ function conventionLines(gate) {
289
+ const match = conventionMatch(gate);
290
+ if (match === null) {
291
+ return { under: [], chosenBy: null };
292
+ }
293
+ const under = [];
294
+ if (match.strength === 'weak') {
295
+ under.push(weakMatchLine(match));
296
+ }
297
+ if (match.legacy !== null) {
298
+ under.push(` note: ${legacyChangedSentence(match.legacy)}`);
299
+ }
300
+ const chosenBy = ` chosen by: branch name, ${match.strength}, shared: ${match.shared.join(' ')}` +
301
+ (match.runnerUp === null ? '' : `, runner-up ${SPEC_DIR}/${match.runnerUp}`);
302
+ return { under, chosenBy };
303
+ }
304
+ function gateSection(gate, verbose, refusedOnTerminal = false) {
305
+ // A gate the refused trust base stopped, on a terminal: the refusal is at
306
+ // the top of the report once, so the section is one line and no more.
307
+ // Every other caller (a file, a pipe, a pull request comment) keeps the full
308
+ // section, byte for byte.
309
+ if (refusedOnTerminal) {
310
+ return [` ${gate.role} ${gate.product} did not run: the trust base was refused (above)`];
311
+ }
312
+ const lines = ['', header(gate, verbose)];
313
+ // Under the header, on every outcome that carries it: gitleaks' own
314
+ // --timeout is not conductor's limit, and the gate-error it produces is the
315
+ // outcome a reader most needs this on.
316
+ if (gate.gateOwnOption !== undefined) {
317
+ lines.push(` note conductor/option-is-gate-own: ${gate.gateOwnOption}`);
318
+ }
146
319
  const contract = contractLine(gate);
147
320
  if (contract !== null) {
148
321
  lines.push(contract);
322
+ // The weak line and the changed-winner note sit directly under the
323
+ // contract line; the chosen-by line, --verbose only, after any other note.
324
+ const convention = conventionLines(gate);
325
+ lines.push(...convention.under);
149
326
  if (gate.intent?.note !== undefined) {
150
327
  lines.push(` note: ${gate.intent.note}`);
151
328
  }
329
+ if (verbose && convention.chosenBy !== null) {
330
+ lines.push(convention.chosenBy);
331
+ }
152
332
  }
153
333
  if (gate.couldNotRun !== null) {
154
334
  lines.push(` ${gate.couldNotRun.detail}`);
@@ -156,6 +336,11 @@ function gateSection(gate) {
156
336
  lines.push(` gate said: "${gate.couldNotRun.gateSaid}"`);
157
337
  }
158
338
  if (gate.stderr.trim().length > 0) {
339
+ if (gate.couldNotRun.reason === 'timed-out') {
340
+ // What a stopped gate printed is often a warning that has nothing to
341
+ // do with the stop; the line above is the reason.
342
+ lines.push(' (printed by the gate before it was stopped; not the reason it stopped)');
343
+ }
159
344
  for (const line of gate.stderr.trim().split('\n')) {
160
345
  lines.push(` | ${cleanOutputLine(line)}`);
161
346
  }
@@ -163,9 +348,17 @@ function gateSection(gate) {
163
348
  }
164
349
  // Sorted here rather than relying on the order the gate happened to emit:
165
350
  // blocking first, then by severity. A section whose first line is a low
166
- // finding buries the one that just refused a commit.
167
- for (const finding of [...gate.findings].sort(compareFindings)) {
168
- lines.push(...findingLines(finding));
351
+ // finding buries the one that just refused a commit. The cap keeps that
352
+ // order, so what it rolls up is always the least severe.
353
+ const entries = findingEntries(gate);
354
+ const shown = verbose ? entries : entries.slice(0, FINDINGS_SHOWN_PER_GATE);
355
+ for (const entry of shown) {
356
+ lines.push(...findingLines(entry, verbose, gate.couldNotRun !== null && isRepeatedProblem(entry[0])));
357
+ }
358
+ const hidden = entries.slice(shown.length).reduce((total, entry) => total + entry.length, 0);
359
+ if (hidden > 0) {
360
+ lines.push(` ${hidden} more finding(s) in this gate, not shown here: re-run with --verbose, or read the ` +
361
+ 'SARIF report (--format sarif). They count toward everything on this report.');
169
362
  }
170
363
  if (gate.couldNotRun === null) {
171
364
  const threshold = gate.run.failOn === null ? 'threshold not reported' : `threshold ${gate.run.failOn}`;
@@ -236,17 +429,27 @@ function skippedLines(result) {
236
429
  return result.skipped.map((gate) => ` skipped ${gate.role} ${gate.product} ${skipWording(gate.reason).line}: ${gate.detail}`);
237
430
  }
238
431
  function skipWording(reason) {
239
- return reason === 'contract-waived'
240
- ? {
432
+ if (reason === 'contract-waived') {
433
+ return {
241
434
  line: 'spec waived',
242
435
  verdict: 'had its spec waived by the pull request body',
243
436
  summary: 'Spec waived by the pull request body',
244
- }
245
- : {
246
- line: 'no contract',
247
- verdict: 'had no contract to check against',
248
- summary: 'Nothing to check against',
249
437
  };
438
+ }
439
+ if (reason === 'spec-ambiguous') {
440
+ // A spec exists; two or more matched equally. Never "nothing to check
441
+ // against", which tells a reader to go and write one.
442
+ return {
443
+ line: 'spec ambiguous',
444
+ verdict: 'matched two or more specs equally, so none was chosen',
445
+ summary: 'No spec chosen, two or more matched the branch equally',
446
+ };
447
+ }
448
+ return {
449
+ line: 'no contract',
450
+ verdict: 'had no contract to check against',
451
+ summary: 'Nothing to check against',
452
+ };
250
453
  }
251
454
  /**
252
455
  * One line per gate the --gate flag left out.
@@ -475,7 +678,17 @@ export function jobLogSummary(result) {
475
678
  * Describes, decides nothing: every word is read off the outcomes the exit
476
679
  * code was already composed from. Same plain ASCII as the rest of this file.
477
680
  */
478
- export function gateLogLines(result) {
681
+ export function gateLogLines(result, options = {}) {
682
+ // On a terminal a refused run's per-gate lines are the refusal sentence once
683
+ // per gate, under a report that already led with it. One line instead; a
684
+ // job log (never a terminal) keeps one line per gate.
685
+ const refusal = result.trustBase?.refusal;
686
+ if (options.terminal === true && refusal !== undefined && refusal !== null && result.gates.length > 0) {
687
+ return [
688
+ `conductor: the trust base was refused, so no gate ran: ` +
689
+ `${result.gates.map((gate) => `${gate.role} (${gate.product})`).join(', ')}; could-not-run, no exit code`,
690
+ ];
691
+ }
479
692
  const lines = [];
480
693
  for (const gate of result.gates) {
481
694
  const version = gate.productVersion === null ? 'version unknown' : gate.productVersion;
@@ -493,6 +706,11 @@ export function gateLogLines(result) {
493
706
  const blocking = gate.findings.filter((finding) => finding.blocking).length;
494
707
  outcome =
495
708
  total === 0 && (gate.exitCode ?? 0) === 0 ? 'ok' : `findings (${total}, ${blocking} blocking)`;
709
+ // Only when the gate said so; the outcome word above is unchanged.
710
+ const coverage = deadlineCoverage(gate);
711
+ if (coverage !== null) {
712
+ outcome += `, ${coverage}`;
713
+ }
496
714
  }
497
715
  // conductor's own refusals (a git below the floor, a path list it cannot
498
716
  // pass, a PATH or git-directory failure, a gate below its minimum) carry
@@ -863,14 +1081,81 @@ function isFullyClean(result) {
863
1081
  if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing)) {
864
1082
  return false;
865
1083
  }
1084
+ // A tie the convention refused to guess, or a skip whose branch 0.10.0
1085
+ // bound to a spec, carries a sentence the one-line summary would drop.
1086
+ if (result.skipped.some((gate) => gate.reason === 'spec-ambiguous' || (gate.selection?.legacy ?? null) !== null)) {
1087
+ return false;
1088
+ }
866
1089
  return result.gates.every((gate) => gate.couldNotRun === null &&
867
1090
  (gate.exitCode ?? 0) === 0 &&
868
1091
  gate.diagnostics.length === 0 &&
869
1092
  // A note about an input this run did not use is never folded into the
870
1093
  // one-line summary, where nobody would see it.
871
1094
  gate.intent?.note === undefined &&
1095
+ // Nor a weak convention match, or a winner that changed this release.
1096
+ conventionMatch(gate)?.strength !== 'weak' &&
1097
+ (conventionMatch(gate)?.legacy ?? null) === null &&
872
1098
  !gate.findings.some((finding) => finding.blocking));
873
1099
  }
1100
+ /**
1101
+ * The intent-spec header line: a CLOSED SET of four strings, in precedence
1102
+ * order, naming no branch, no file and no token. The Action copies one to the
1103
+ * step summary only on a whole-line match, so nothing the repository or the
1104
+ * head branch carries can reach that summary through it.
1105
+ */
1106
+ export const INTENT_SPEC_LINES = [
1107
+ 'intent-spec: none chosen, two or more specs matched the branch equally',
1108
+ 'intent-spec: none chosen, this branch chose a spec before conductor 0.11.0',
1109
+ 'intent-spec: a different spec chosen than before conductor 0.11.0, see the report',
1110
+ 'intent-spec: weak match, see the intent gate in the report',
1111
+ ];
1112
+ /** The first of the four lines that applies to this run, or null. */
1113
+ function intentSpecLine(result) {
1114
+ const misses = result.skipped.flatMap((gate) => (gate.selection === undefined ? [] : [gate.selection]));
1115
+ const matches = result.gates.flatMap((gate) => {
1116
+ const match = conventionMatch(gate);
1117
+ return match === null ? [] : [match];
1118
+ });
1119
+ if (misses.some((miss) => miss.why === 'ambiguous')) {
1120
+ return INTENT_SPEC_LINES[0];
1121
+ }
1122
+ if (misses.some((miss) => miss.legacy !== null)) {
1123
+ return INTENT_SPEC_LINES[1];
1124
+ }
1125
+ if (matches.some((match) => match.legacy !== null)) {
1126
+ return INTENT_SPEC_LINES[2];
1127
+ }
1128
+ if (matches.some((match) => match.strength === 'weak')) {
1129
+ return INTENT_SPEC_LINES[3];
1130
+ }
1131
+ return null;
1132
+ }
1133
+ /**
1134
+ * dep-guard's own diagnostic code for an online budget that ran out before
1135
+ * every lookup was made (dep-guard core, online/deadline.ts,
1136
+ * ONLINE_DEADLINE_CODE). Read, never minted: the umbrella only repeats it.
1137
+ */
1138
+ export const DEP_GUARD_DEADLINE_CODE = 'online-deadline-exceeded';
1139
+ /**
1140
+ * The coverage clause for a dep-guard run whose online lookups were cut short
1141
+ * by its own deadline, or null. Not a verdict: dep-guard still exits 0 for
1142
+ * this and so does the run; the clause exists because a summary that read
1143
+ * "ok" while some names were never looked up overstated what was checked.
1144
+ */
1145
+ function deadlineCoverage(gate) {
1146
+ if (gate.product !== 'dep-guard' || gate.couldNotRun !== null) {
1147
+ return null;
1148
+ }
1149
+ const said = gate.run.diagnostics.some((diagnostic) => diagnostic.code === DEP_GUARD_DEADLINE_CODE);
1150
+ const skipped = gate.run.details['skipped-by-deadline'];
1151
+ const count = typeof skipped === 'number' ? skipped : null;
1152
+ if (!said && (count === null || count === 0)) {
1153
+ return null;
1154
+ }
1155
+ return count === null || count === 0
1156
+ ? `online lookups incomplete (${DEP_GUARD_DEADLINE_CODE})`
1157
+ : `online lookups incomplete, ${count} skipped by the deadline (${DEP_GUARD_DEADLINE_CODE})`;
1158
+ }
874
1159
  /**
875
1160
  * The gates' own notes, and only those.
876
1161
  *
@@ -985,6 +1270,14 @@ function summaryLine(result) {
985
1270
  if (counts.length > 0) {
986
1271
  parts.push(`${counts.join(', ')}.`);
987
1272
  }
1273
+ // A clean run whose dependency gate did not finish its online lookups is
1274
+ // still exit 0, and still this line, but it says so in words.
1275
+ for (const gate of result.gates) {
1276
+ const coverage = deadlineCoverage(gate);
1277
+ if (coverage !== null) {
1278
+ parts.push(`${gate.role} (${gate.product}): ${coverage}.`);
1279
+ }
1280
+ }
988
1281
  // The suppressed and ignored counts the gates reported, summed across them
989
1282
  // and printed even at zero. The full report prints these per gate for the
990
1283
  // same reason, so a quiet report is not mistaken for a clean one; the clean
@@ -1070,15 +1363,24 @@ export function renderText(result, options = {}) {
1070
1363
  // job summary when, and only when, line 3 is exactly this shape, so a pass
1071
1364
  // that carries them does not read as spotless there either.
1072
1365
  const reported = presentOnBaseReported(result);
1366
+ // The intent-spec line follows it, so the present-on-base line, when
1367
+ // present, stays line 3 and every report without an intent-spec line keeps
1368
+ // the shape the Action already reads.
1369
+ const specLine = intentSpecLine(result);
1073
1370
  const lines = [
1074
1371
  ...headerLines(result, options),
1075
1372
  ...(reported === 0 ? [] : [`present-on-base: ${reported} reported, not blocking`]),
1373
+ ...(specLine === null ? [] : [specLine]),
1076
1374
  ...refusal,
1077
1375
  ...(refusal.length === 0 ? [] : ['']),
1078
1376
  `conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
1079
1377
  ];
1378
+ const refusedOnTerminal = options.terminal === true && refusal.length > 0;
1379
+ if (refusedOnTerminal && result.gates.length > 0) {
1380
+ lines.push('');
1381
+ }
1080
1382
  for (const gate of result.gates) {
1081
- lines.push(...gateSection(gate));
1383
+ lines.push(...gateSection(gate, Boolean(options.verbose), refusedOnTerminal));
1082
1384
  }
1083
1385
  const aside = [
1084
1386
  ...deferredLines(result),
@@ -1097,7 +1399,8 @@ export function renderText(result, options = {}) {
1097
1399
  // A derived severity is marked with a trailing asterisk above; say what
1098
1400
  // that means rather than leaving a reader to guess, and only when one is
1099
1401
  // actually on screen.
1100
- if (result.findings.some((finding) => finding.severityIsDerived)) {
1402
+ // A compact terminal refusal prints no finding line at all, so no asterisk.
1403
+ if (!refusedOnTerminal && result.findings.some((finding) => finding.severityIsDerived)) {
1101
1404
  lines.push('', '* severity assigned by the umbrella; that gate reports no per-finding severity.');
1102
1405
  }
1103
1406
  lines.push('', verdict(result, Boolean(options.advisory)));
package/dist/policy.d.ts CHANGED
@@ -91,6 +91,14 @@ export interface GatePolicy {
91
91
  * every other gate; a reader of an absent value treats it as `block`.
92
92
  */
93
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;
94
102
  }
95
103
  /** The two values of the vulnerabilities gate's present-on-base key. */
96
104
  export type PresentOnBase = 'block' | 'report';
package/dist/policy.js CHANGED
@@ -107,6 +107,17 @@ export const PRODUCT_FOR_ROLE = {
107
107
  * depend on that CLI's argument parser rather than on anything the user
108
108
  * could read in their own policy file.
109
109
  */
110
+ //
111
+ // Two keys are reserved for a different reason: they name conductor's OWN
112
+ // setting, written in the wrong place. `timeout-seconds` is the gate-level
113
+ // time limit, beside `enforce`; no tool has a --timeout-seconds flag, so the
114
+ // only way to write it under options is to mean conductor's key. `timeout`
115
+ // is reserved on the four tools that have no --timeout flag (each rejects
116
+ // it, so no working policy can contain it), and NOT on gitleaks, whose
117
+ // --timeout is its own deadline and works: reserving it there would refuse
118
+ // policies that pass it today. Neither reservation is a trust control: they
119
+ // match exact option keys only, and on a pull request only the base policy is
120
+ // read anyway.
110
121
  export const RESERVED_OPTIONS = {
111
122
  // `trust-base` is reserved for all three products, and the umbrella now
112
123
  // writes it for all three. It was reserved here before dep-guard's own
@@ -115,8 +126,8 @@ export const RESERVED_OPTIONS = {
115
126
  // have broken repositories on an upgrade nobody asked for. The flag it
116
127
  // names is the one that decides where a gate reads its rules from, which
117
128
  // is the last place to leave a window open.
118
- 'dep-guard': ['format', 'staged', 'base', 'trust-base'],
119
- 'vault-guard': ['format', 'f', 'staged', 'trust-base'],
129
+ 'dep-guard': ['format', 'staged', 'base', 'trust-base', 'timeout-seconds', 'timeout'],
130
+ 'vault-guard': ['format', 'f', 'staged', 'trust-base', 'timeout-seconds', 'timeout'],
120
131
  // `base` is reserved even though the umbrella never passes it to this gate,
121
132
  // and that is the point. The umbrella works the changed-path set out itself
122
133
  // and hands over `--paths`, because `--project` may be a temporary
@@ -132,7 +143,7 @@ export const RESERVED_OPTIONS = {
132
143
  // out. It is also the one flag where two writers would be a security
133
144
  // problem rather than a confusion, since the loser decides where the gate
134
145
  // reads its rules from.
135
- 'intent-guard': ['json', 'staged', 'project', 'paths', 'base', 'trust-base'],
146
+ 'intent-guard': ['json', 'staged', 'project', 'paths', 'base', 'trust-base', 'timeout-seconds', 'timeout'],
136
147
  // The umbrella writes every one of these for gitleaks: the report goes to a
137
148
  // file it owns, the exit code for a leak is moved off 1 so an error and a
138
149
  // leak stop sharing a number, history is scoped by --log-opts so one
@@ -149,12 +160,16 @@ export const RESERVED_OPTIONS = {
149
160
  'redact',
150
161
  'no-banner',
151
162
  'log-level',
163
+ // Conductor's own setting; `timeout` stays a passthrough here (see above).
164
+ 'timeout-seconds',
152
165
  ],
153
166
  // osv-scanner: the umbrella owns the format (json to stdout), the config on
154
167
  // a pull-request run, and which lockfiles are scanned (every tracked one,
155
168
  // by name; there is no directory walk and so no --recursive).
156
- 'osv-scanner': ['format', 'config', 'lockfile'],
169
+ 'osv-scanner': ['format', 'config', 'lockfile', 'timeout-seconds', 'timeout'],
157
170
  };
171
+ /** The keys reserved under options because they name conductor's own time limit. */
172
+ const CONDUCTOR_SETTING_KEYS = new Set(['timeout-seconds', 'timeout']);
158
173
  export class PolicyError extends Error {
159
174
  constructor(message) {
160
175
  super(message);
@@ -205,7 +220,14 @@ function describeErrors(errors, source) {
205
220
  * runs and the general sentence would send somebody looking for a flag that
206
221
  * is not on the command line of the run they are debugging.
207
222
  */
208
- function reservedReason(product, key) {
223
+ function reservedReason(product, role, key) {
224
+ if (CONDUCTOR_SETTING_KEYS.has(key)) {
225
+ return key === 'timeout-seconds'
226
+ ? "timeout-seconds is conductor's own limit for this gate. Set it beside enforce, as " +
227
+ `gates.${role}.timeout-seconds, not under options.`
228
+ : "This gate has no --timeout flag; conductor's own limit is " +
229
+ `gates.${role}.timeout-seconds, beside enforce.`;
230
+ }
209
231
  if (key === 'trust-base') {
210
232
  return ('That flag says where a gate reads its rules from, and on a pull-request run the umbrella ' +
211
233
  'writes it itself, pointing at the base ref it read its own policy from. A value here ' +
@@ -312,7 +334,7 @@ export function parsePolicy(text, source) {
312
334
  for (const key of Object.keys(options)) {
313
335
  if (RESERVED_OPTIONS[product].includes(key)) {
314
336
  throw new PolicyError(`${source}: "${key}" under gates.${role}.options is reserved. ` +
315
- reservedReason(product, key));
337
+ reservedReason(product, role, key));
316
338
  }
317
339
  }
318
340
  // Only the vulnerabilities gate has a base comparison to apply the key to.
@@ -350,6 +372,11 @@ export function parsePolicy(text, source) {
350
372
  // Absent means block: a policy written before the key existed blocks
351
373
  // on every known vulnerability, so no policy is loosened by an upgrade.
352
374
  ...(role === 'vulnerabilities' ? { presentOnBase: presentOnBase ?? 'block' } : {}),
375
+ // Only when the key is present: an absent key is the profile default,
376
+ // decided in resolveTimeLimit, never a value frozen in here.
377
+ ...(entry['timeout-seconds'] === undefined
378
+ ? {}
379
+ : { timeoutSeconds: entry['timeout-seconds'] }),
353
380
  };
354
381
  }
355
382
  return {
@@ -1,4 +1,4 @@
1
- import type { Product } from './policy.js';
1
+ import type { GateRole, Product } from './policy.js';
2
2
  export type OutputSource = {
3
3
  kind: 'stdout';
4
4
  } | {
@@ -27,7 +27,14 @@ export interface ProductProfile {
27
27
  versionProbe: VersionProbeSpec | null;
28
28
  output: OutputSource;
29
29
  exit: ExitSemantics;
30
+ /** The time limit when the policy sets no timeout-seconds for this gate. */
30
31
  timeoutMs: number;
32
+ /**
33
+ * What to do about a gate stopped at its limit: the sentence the timed-out
34
+ * detail carries. Never a bounded history window or a default size cap,
35
+ * which would narrow coverage without anybody deciding to.
36
+ */
37
+ timeoutRemedies: (role: GateRole) => string;
31
38
  /** Oldest version whose command line this runner speaks; null means any. */
32
39
  minVersion: string | null;
33
40
  /** Config file the tool auto-loads from the scanned tree; read from the base ref on a pull request. */
package/dist/products.js CHANGED
@@ -7,6 +7,11 @@
7
7
  // consults it. The three npm profiles below restate exactly what the runner
8
8
  // did before profiles existed; changing one of them changes a gate that
9
9
  // adopters already run.
10
+ /** The first half of every timed-out remedy: where the limit is raised. */
11
+ function raiseTheLimit(role) {
12
+ return (`Raise the limit with gates.${role}.timeout-seconds in .guardrails.yaml (on a pull request, on ` +
13
+ 'the base branch).');
14
+ }
10
15
  /**
11
16
  * The lockfiles osv-scanner is handed as a bare path, matched by base name at
12
17
  * any depth among the repository's TRACKED files (`git ls-files`).
@@ -113,6 +118,8 @@ function managedProfile(product) {
113
118
  output: { kind: 'stdout' },
114
119
  exit: NPM_EXIT,
115
120
  timeoutMs: 120_000,
121
+ timeoutRemedies: (role) => `${raiseTheLimit(role)} A family gate that needs more than two minutes is unusual, so the ` +
122
+ "gate's own output below is worth reading first.",
116
123
  minVersion: null,
117
124
  configFile: null,
118
125
  neutralConfig: null,
@@ -140,7 +147,12 @@ const PROFILES = {
140
147
  exit: { clean: [0], blocked: [3], nothingToScan: [] },
141
148
  // A full-history scan on a large repository outlives the npm gates' two
142
149
  // minutes; could-not-run on every pull request is the failure to avoid.
150
+ // This is the default when the policy sets no timeout-seconds.
143
151
  timeoutMs: 600_000,
152
+ timeoutRemedies: (role) => `${raiseTheLimit(role)} A history scan grows with the repository's history and the size of ` +
153
+ 'what was committed: scan full history on a schedule and let pull requests scan only their ' +
154
+ 'own range, or pass max-target-megabytes under options, which skips every file larger than ' +
155
+ 'the cap without saying which, so a secret in such a file is not found.',
144
156
  minVersion: '8.19.0',
145
157
  configFile: '.gitleaks.toml',
146
158
  neutralConfig: '[extend]\nuseDefault = true\n',
@@ -175,6 +187,8 @@ const PROFILES = {
175
187
  // lockfile has nothing to scan, which is clean, not an error.
176
188
  exit: { clean: [0], blocked: [1], nothingToScan: [128] },
177
189
  timeoutMs: 300_000,
190
+ timeoutRemedies: (role) => `${raiseTheLimit(role)} osv-scanner queries osv.dev over the network, so a slow or ` +
191
+ 'unreachable service shows up as a timeout too.',
178
192
  minVersion: '2.0.0',
179
193
  configFile: 'osv-scanner.toml',
180
194
  neutralConfig: '',