@vaultcompass/conductor 0.7.0 → 0.8.1

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.
@@ -154,7 +154,7 @@ function exists(repoRoot, relative) {
154
154
  * the failure actually had: "superpowers" beat
155
155
  * "1.2.1-base-and-superpowers" by being shorter and vaguer.
156
156
  */
157
- function bestMatch(names, target) {
157
+ export function bestMatch(names, target) {
158
158
  return names
159
159
  .filter((name) => stemMatches(normalizeStem(name), target))
160
160
  .sort((a, b) => {
@@ -192,7 +192,18 @@ function planFor(repoRoot, specPath) {
192
192
  const specStem = normalizeStem(path.basename(specPath));
193
193
  const matches = markdownFilesIn(repoRoot, PLAN_DIR).filter((name) => normalizeStem(name) === specStem);
194
194
  const newest = matches[matches.length - 1];
195
- return newest === undefined ? null : `${PLAN_DIR}/${newest}`;
195
+ if (newest === undefined) {
196
+ return { plan: null };
197
+ }
198
+ const plan = `${PLAN_DIR}/${newest}`;
199
+ // Held to the repository like the convention spec: a plans directory
200
+ // linked out of the checkout is refused, never read and never dropped.
201
+ return resolvesInsideRoot(repoRoot, plan) ? { plan } : { escaped: plan };
202
+ }
203
+ /** A found spec with its plan, or the refusal for a plan that escapes. */
204
+ function withPlan(repoRoot, kind, spec) {
205
+ const found = planFor(repoRoot, spec);
206
+ return 'escaped' in found ? { kind: 'escaped', path: found.escaped } : { kind, spec, plan: found.plan };
196
207
  }
197
208
  /** Normalizes a user-supplied path to a repository-relative one. */
198
209
  function relativeToRoot(repoRoot, candidate) {
@@ -253,7 +264,7 @@ export function discoverSpec(options) {
253
264
  if (!exists(repoRoot, relative)) {
254
265
  return { kind: 'missing-flag', spec: relative };
255
266
  }
256
- return { kind: 'flag', spec: relative, plan: planFor(repoRoot, relative) };
267
+ return withPlan(repoRoot, 'flag', relative);
257
268
  }
258
269
  if (options.prBody !== undefined) {
259
270
  const named = specFromPrBody(options.prBody);
@@ -274,7 +285,7 @@ export function discoverSpec(options) {
274
285
  // Containment subsumes existence here, since a path that does not
275
286
  // resolve is not contained.
276
287
  if (resolvesInsideRoot(repoRoot, relative)) {
277
- return { kind: 'pr-body', spec: relative, plan: planFor(repoRoot, relative) };
288
+ return withPlan(repoRoot, 'pr-body', relative);
278
289
  }
279
290
  }
280
291
  }
@@ -282,7 +293,13 @@ export function discoverSpec(options) {
282
293
  const best = bestMatch(markdownFilesIn(repoRoot, SPEC_DIR), branchSlug(options.branch));
283
294
  if (best !== undefined) {
284
295
  const relative = `${SPEC_DIR}/${best}`;
285
- return { kind: 'convention', spec: relative, plan: planFor(repoRoot, relative) };
296
+ // The convention spec is held to the repository too: a specs directory
297
+ // linked out of the checkout is refused, never imported. Only --spec is
298
+ // exempt, as a path a person typed.
299
+ if (!resolvesInsideRoot(repoRoot, relative)) {
300
+ return { kind: 'escaped', path: relative };
301
+ }
302
+ return withPlan(repoRoot, 'convention', relative);
286
303
  }
287
304
  }
288
305
  return { kind: 'none' };
@@ -54,6 +54,15 @@ roots?: readonly string[],
54
54
  /** The lockfiles the umbrella passed with --lockfile, repository-relative. */
55
55
  lockfiles?: readonly string[]): NormalizedGateOutput;
56
56
  export type GateProblemRule = 'conductor/gate-missing' | 'conductor/gate-output-unparseable' | 'conductor/gate-failed';
57
+ /**
58
+ * What to install for a product, spelled so it cannot be mistaken for
59
+ * another package. The three npm gates are published under the
60
+ * @vaultcompass scope only: the unscoped dep-guard and intent-guard names are
61
+ * unclaimed on npm, so a reader (or an agent) told to install the bare name
62
+ * could install a squatted package. The external tools are not npm packages
63
+ * of this family and keep their own names.
64
+ */
65
+ export declare function installName(product: Product): string;
57
66
  /**
58
67
  * The finding raised when an ENABLED gate's binary cannot be found.
59
68
  *
package/dist/normalize.js CHANGED
@@ -14,6 +14,7 @@
14
14
  // own reported count says otherwise.
15
15
  import { createHash } from 'node:crypto';
16
16
  import { NormalizeError, atOrAboveThreshold, } from './envelope.js';
17
+ import { profileFor } from './products.js';
17
18
  const BLOCKING_MISMATCH = 'conductor/blocking-count-mismatch';
18
19
  const THRESHOLD_UNKNOWN = 'conductor/blocking-threshold-unknown';
19
20
  function isRecord(value) {
@@ -336,10 +337,12 @@ export function normalizeVaultGuard(raw, version) {
336
337
  run: {
337
338
  failOn: threshold,
338
339
  suppressed: typeof run.baseline_suppressed === 'number' ? run.baseline_suppressed : 0,
339
- // vault-guard does not report an ignore count separately; ignored
340
- // files never reach the output at all. Reporting 0 here would claim a
341
- // fact the gate did not state, so the report says "not reported"
342
- // instead, driven by this null.
340
+ // This normalizer reads no ignore count out of vault-guard's run object
341
+ // (which does carry config_ignored_files; it is not mapped here), so 0
342
+ // is a placeholder and not a claim that nothing was ignored. What makes
343
+ // the report say "ignored not reported" is not this number: it is
344
+ // `ignoredReported: false` in `details` below, which output-text.ts and
345
+ // the summary line read in its place.
343
346
  ignored: 0,
344
347
  // vault-guard's diagnostics carry a context object rather than a
345
348
  // message, so the context is rendered as one. Validated the same way
@@ -1045,6 +1048,17 @@ function gateProblem(ruleId, role, product, message, details) {
1045
1048
  details: { role, product, ...details },
1046
1049
  };
1047
1050
  }
1051
+ /**
1052
+ * What to install for a product, spelled so it cannot be mistaken for
1053
+ * another package. The three npm gates are published under the
1054
+ * @vaultcompass scope only: the unscoped dep-guard and intent-guard names are
1055
+ * unclaimed on npm, so a reader (or an agent) told to install the bare name
1056
+ * could install a squatted package. The external tools are not npm packages
1057
+ * of this family and keep their own names.
1058
+ */
1059
+ export function installName(product) {
1060
+ return profileFor(product).managed ? `@vaultcompass/${product}` : product;
1061
+ }
1048
1062
  /**
1049
1063
  * The finding raised when an ENABLED gate's binary cannot be found.
1050
1064
  *
@@ -1066,7 +1080,7 @@ export function normalizeMissingGate(role, product, candidates,
1066
1080
  */
1067
1081
  remedy = '') {
1068
1082
  return gateProblem('conductor/gate-missing', role, product, `The "${role}" gate is enabled but no ${product} binary was found. ` +
1069
- `Looked for: ${candidates.join(', ')}. Install it, point the gate at a build with an ` +
1083
+ `Looked for: ${candidates.join(', ')}. Install ${installName(product)}, point the gate at a build with an ` +
1070
1084
  `absolute "command:", or set enabled: false to switch the gate off on purpose.${remedy}`, { candidates });
1071
1085
  }
1072
1086
  /**
@@ -660,7 +660,9 @@ function trustBaseRefusedNotifications(result) {
660
660
  {
661
661
  id: 'conductor/trust-base-refused',
662
662
  level: 'error',
663
- message: `conductor refused the trust base "${result.trustBase?.ref ?? ''}", so no gate ran and ` +
663
+ message: (result.trustBase?.notGiven === true
664
+ ? 'this is a pull-request job and no trust base was given, so no rules were read, no gate ran and '
665
+ : `conductor refused the trust base "${result.trustBase?.ref ?? ''}", so no gate ran and `) +
664
666
  `NOTHING WAS CHECKED by this run. ${refusal}`,
665
667
  details: { ref: result.trustBase?.ref ?? null, reason: refusal },
666
668
  },
@@ -703,17 +705,15 @@ function programRefusedNotifications(result) {
703
705
  });
704
706
  }
705
707
  /**
706
- * The gates the umbrella could not put into pull-request mode.
708
+ * The gates the umbrella did not hand the trust base to.
707
709
  *
708
710
  * The loud half of the same mode, and by the discriminator below it is a
709
- * close call that lands on notification: nothing went wrong with the run, and
710
- * the fact is true of the configuration (an older gate is installed) rather
711
- * than of this change, so it is identical on every run until somebody
712
- * upgrades. What it says is how much of the pull-request boundary this run
713
- * actually had, which is a coverage statement.
714
- *
715
- * It is still the most important notification in the log. A gate here read
716
- * its own control inputs out of the tree under judgment.
711
+ * close call that lands on notification: nothing went wrong with the run.
712
+ * What it says is how much of the pull-request boundary this run actually
713
+ * had, which is a coverage statement. A gate below its pull-request-mode
714
+ * minimum never lands here: it is could-not-run. What is left is an intent
715
+ * gate judging a contract imported for this run from the base, and a
716
+ * product with no pull-request mode at all (none today).
717
717
  */
718
718
  function trustBaseWithheldNotifications(result) {
719
719
  return result.gates.flatMap((gate) => {
@@ -724,9 +724,8 @@ function trustBaseWithheldNotifications(result) {
724
724
  return [
725
725
  {
726
726
  id: 'conductor/trust-base-not-passed',
727
- message: `The ${gate.role} gate (${gate.product}) did NOT run in pull-request mode, so it read ` +
728
- `its own control inputs from the tree being judged rather than from ` +
729
- `${gate.trustBase?.ref ?? 'the base ref'}. ${withheld}`,
727
+ message: `The ${gate.role} gate (${gate.product}) did NOT run in pull-request mode: it was not ` +
728
+ `handed --trust-base ${gate.trustBase?.ref ?? 'the base ref'}. ${withheld}`,
730
729
  details: {
731
730
  role: gate.role,
732
731
  product: gate.product,
@@ -1,4 +1,22 @@
1
1
  import type { RunResult } from './run.js';
2
+ /**
3
+ * The one sentence the whole of pull-request mode has to fit into.
4
+ *
5
+ * Counted even at ZERO, by the family suppression rule: the number is the
6
+ * answer to "did this pull request also try to change the rules", and leaving
7
+ * it out when the answer is none makes a run in pull-request mode
8
+ * indistinguishable from a run that was never in it.
9
+ *
10
+ * NEVER A COUNT THAT TREATS A GATE THAT COULD NOT RUN AS ZERO. A gate that
11
+ * was put into pull-request mode and could not run reported no summary the
12
+ * umbrella reads, so its proposals are not known rather than none. The
13
+ * sentence then names those gates and counts only what the others proposed.
14
+ * On a run with a trust base that includes a gate that stopped before its
15
+ * pull-request mode was even decided (it carries no trustBase: a preparation
16
+ * that failed, a git older than the floor, a missing binary), because it was
17
+ * meant to run in that mode and reported nothing either.
18
+ */
19
+ export declare function proposalCount(result: RunResult): string;
2
20
  /**
3
21
  * The one-line summary a `--output` run prints to the job log after writing
4
22
  * its report to a file (see cli.ts). Refused first, exactly like every other
@@ -25,12 +43,44 @@ import type { RunResult } from './run.js';
25
43
  * not change.
26
44
  */
27
45
  export declare function jobLogSummary(result: RunResult): string;
46
+ /**
47
+ * One plain line per gate, for the job log: which gate, which version, what
48
+ * happened, and the exit code. Written to stderr by cli.ts on EVERY run, so
49
+ * an adopter reading the log learns which gate did what without opening a
50
+ * report (the SARIF log, the text report file or the pull request comment).
51
+ *
52
+ * Outcomes, in the words the lines use: `ok`, `findings (N, M blocking)`,
53
+ * `could-not-run (reason)` with the gate's own stated reason when it gave
54
+ * one, or conductor's own reason when the refusal was conductor's (both
55
+ * cleaned, one line, capped and quoted), `missing (reason)` for a gate that
56
+ * was not found, and `skipped (why)`
57
+ * for a gate that was enabled and never spawned (deferred by stage, left out
58
+ * by --gate, no contract, tree unchanged). A gate with no process behind it
59
+ * says `no exit code`, never a made-up one.
60
+ *
61
+ * Describes, decides nothing: every word is read off the outcomes the exit
62
+ * code was already composed from. Same plain ASCII as the rest of this file.
63
+ */
64
+ export declare function gateLogLines(result: RunResult): string[];
65
+ /**
66
+ * One warning per gate that was found on PATH at a version other than the one
67
+ * this run expected (the Action's pin).
68
+ *
69
+ * For the job log only: it names where the binary was found, and an absolute
70
+ * path has no business in a published SARIF log or a pull request comment, so
71
+ * this is never part of either report. A warning and nothing more. Resolution
72
+ * is unchanged and the gate ran (or was refused) exactly as it would have
73
+ * without it.
74
+ */
75
+ export declare function versionSkewWarnings(result: RunResult): string[];
28
76
  /**
29
77
  * The verdict token: a label for the umbrella's OWN exit decision, in a
30
78
  * closed set, so a person or a script reading a report or a job summary gets
31
79
  * the state without parsing the verdict sentence.
32
80
  *
33
81
  * pass exit 0 and nothing was hidden by it
82
+ * nothing-checked exit 0, but no gate ran at all (none enabled,
83
+ * or every one deferred, tree-unchanged or skipped)
34
84
  * advisory-blocked (N) exit 1 that --advisory turned into exit 0
35
85
  * unenforced-findings (N) exit 0, but enforce: false gates blocked or
36
86
  * could not run
@@ -51,8 +101,8 @@ export declare function jobLogSummary(result: RunResult): string;
51
101
  *
52
102
  * A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
53
103
  * than result.gates, is neither a blocking finding nor a could-not-run, and
54
- * so does not by itself move the token off pass. The verdict sentence is
55
- * where "nothing was checked" is said.
104
+ * so does not by itself move the token off pass when another gate ran. When
105
+ * NO gate ran, the token is nothing-checked, matching the verdict sentence.
56
106
  *
57
107
  * Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
58
108
  * not a pass.
@@ -23,6 +23,7 @@
23
23
  // everywhere is worth more here than a nicer-looking terminal.
24
24
  import { compareFindings } from './envelope.js';
25
25
  import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN } 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;
@@ -112,12 +113,18 @@ function gateSection(gate) {
112
113
  const contract = contractLine(gate);
113
114
  if (contract !== null) {
114
115
  lines.push(contract);
116
+ if (gate.intent?.note !== undefined) {
117
+ lines.push(` note: ${gate.intent.note}`);
118
+ }
115
119
  }
116
120
  if (gate.couldNotRun !== null) {
117
121
  lines.push(` ${gate.couldNotRun.detail}`);
122
+ if (gate.couldNotRun.gateSaid !== undefined) {
123
+ lines.push(` gate said: "${gate.couldNotRun.gateSaid}"`);
124
+ }
118
125
  if (gate.stderr.trim().length > 0) {
119
126
  for (const line of gate.stderr.trim().split('\n')) {
120
- lines.push(` | ${line}`);
127
+ lines.push(` | ${cleanOutputLine(line)}`);
121
128
  }
122
129
  }
123
130
  }
@@ -237,19 +244,39 @@ function treeUnchangedLines(result) {
237
244
  * answer to "did this pull request also try to change the rules", and leaving
238
245
  * it out when the answer is none makes a run in pull-request mode
239
246
  * indistinguishable from a run that was never in it.
247
+ *
248
+ * NEVER A COUNT THAT TREATS A GATE THAT COULD NOT RUN AS ZERO. A gate that
249
+ * was put into pull-request mode and could not run reported no summary the
250
+ * umbrella reads, so its proposals are not known rather than none. The
251
+ * sentence then names those gates and counts only what the others proposed.
252
+ * On a run with a trust base that includes a gate that stopped before its
253
+ * pull-request mode was even decided (it carries no trustBase: a preparation
254
+ * that failed, a git older than the floor, a missing binary), because it was
255
+ * meant to run in that mode and reported nothing either.
240
256
  */
241
- function proposalCount(result) {
242
- return `${result.proposals.length} control change(s) proposed in this pull request`;
257
+ export function proposalCount(result) {
258
+ const unknown = result.gates.filter((gate) => gate.couldNotRun !== null &&
259
+ (gate.trustBase === undefined
260
+ ? result.trustBase !== null
261
+ : gate.trustBase.withheld === null && gate.trustBase.refused === null));
262
+ if (unknown.length === 0) {
263
+ return `${result.proposals.length} control change(s) proposed in this pull request`;
264
+ }
265
+ const names = unknown.map((gate) => `${gate.role} (${gate.product})`).join(', ');
266
+ return (`${result.proposals.length} control change(s) proposed by the gates that ran; ` +
267
+ `${names} could not run, so the proposals of ${unknown.length === 1 ? 'that gate are' : 'those gates are'} not known`);
243
268
  }
244
269
  /**
245
- * The gates the umbrella could not put into pull-request mode.
270
+ * The gates the umbrella did not hand the trust base to.
246
271
  *
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.
272
+ * This is the loud half and it must never be silent: a run where one gate was
273
+ * not handed the base ref must not read like a run where every gate was. A
274
+ * gate below its pull-request-mode minimum is never here (it is
275
+ * could-not-run); what is left is an intent gate judging a contract imported
276
+ * from the base for this run, and a product with no pull-request mode at all.
277
+ * It is a statement about coverage rather than about anybody's code, so it is
278
+ * a line and a notification rather than a finding, and it never reaches the
279
+ * exit code.
253
280
  */
254
281
  function withheldTrustBase(result) {
255
282
  return result.gates.flatMap((gate) => {
@@ -291,6 +318,9 @@ function trustBaseLines(result) {
291
318
  if (result.trustBase === null) {
292
319
  return [];
293
320
  }
321
+ if (result.trustBase.notGiven === true) {
322
+ return [' pull-request mode: no trust base was given, so no rules were read.'];
323
+ }
294
324
  const lines = [
295
325
  ` pull-request mode: rules from ${result.trustBase.ref}. ${proposalCount(result)}.`,
296
326
  ];
@@ -346,7 +376,9 @@ function refusalLines(result) {
346
376
  return [];
347
377
  }
348
378
  return [
349
- `conductor: refused the trust base "${result.trustBase?.ref ?? ''}". Nothing was checked.`,
379
+ result.trustBase?.notGiven === true
380
+ ? 'conductor: this is a pull-request job and no trust base was given, so no rules were read. Nothing was checked.'
381
+ : `conductor: refused the trust base "${result.trustBase?.ref ?? ''}". Nothing was checked.`,
350
382
  ` ${refusal}`,
351
383
  ];
352
384
  }
@@ -378,10 +410,97 @@ function refusalLines(result) {
378
410
  export function jobLogSummary(result) {
379
411
  const refusal = result.trustBase?.refusal;
380
412
  if (refusal !== undefined && refusal !== null) {
381
- return `refused the trust base "${result.trustBase?.ref ?? ''}": ${refusal.replace(/\.+\s*$/, '')}`;
413
+ return result.trustBase?.notGiven === true
414
+ ? `pull-request job with no trust base, no rules read: ${refusal.replace(/\.+\s*$/, '')}`
415
+ : `refused the trust base "${result.trustBase?.ref ?? ''}": ${refusal.replace(/\.+\s*$/, '')}`;
382
416
  }
383
417
  return `${result.gates.length} gate(s), ${result.findings.length} finding(s)`;
384
418
  }
419
+ /**
420
+ * One plain line per gate, for the job log: which gate, which version, what
421
+ * happened, and the exit code. Written to stderr by cli.ts on EVERY run, so
422
+ * an adopter reading the log learns which gate did what without opening a
423
+ * report (the SARIF log, the text report file or the pull request comment).
424
+ *
425
+ * Outcomes, in the words the lines use: `ok`, `findings (N, M blocking)`,
426
+ * `could-not-run (reason)` with the gate's own stated reason when it gave
427
+ * one, or conductor's own reason when the refusal was conductor's (both
428
+ * cleaned, one line, capped and quoted), `missing (reason)` for a gate that
429
+ * was not found, and `skipped (why)`
430
+ * for a gate that was enabled and never spawned (deferred by stage, left out
431
+ * by --gate, no contract, tree unchanged). A gate with no process behind it
432
+ * says `no exit code`, never a made-up one.
433
+ *
434
+ * Describes, decides nothing: every word is read off the outcomes the exit
435
+ * code was already composed from. Same plain ASCII as the rest of this file.
436
+ */
437
+ export function gateLogLines(result) {
438
+ const lines = [];
439
+ for (const gate of result.gates) {
440
+ const version = gate.productVersion === null ? 'version unknown' : gate.productVersion;
441
+ const exit = gate.exitCode === null ? 'no exit code' : `exit ${gate.exitCode}`;
442
+ let outcome;
443
+ if (gate.couldNotRun !== null) {
444
+ const reason = gate.couldNotRun.reason;
445
+ outcome =
446
+ reason === 'binary-missing' || reason === 'configured-command-missing'
447
+ ? `missing (${reason})`
448
+ : `could-not-run (${reason})`;
449
+ }
450
+ else {
451
+ const total = gate.findings.length;
452
+ const blocking = gate.findings.filter((finding) => finding.blocking).length;
453
+ outcome =
454
+ total === 0 && (gate.exitCode ?? 0) === 0 ? 'ok' : `findings (${total}, ${blocking} blocking)`;
455
+ }
456
+ // conductor's own refusals (a git below the floor, a path list it cannot
457
+ // pass, a PATH or git-directory failure, a gate below its minimum) carry
458
+ // their reason the same way, since no gate said anything for them.
459
+ const conductorSaid = gate.couldNotRun !== null &&
460
+ gate.couldNotRun.gateSaid === undefined &&
461
+ CONDUCTOR_OWN_REASONS.has(gate.couldNotRun.reason)
462
+ ? conductorStatedReason(gate.couldNotRun.detail)
463
+ : null;
464
+ lines.push(`conductor: gate ${gate.role} (${gate.product} ${version}): ${outcome}, ${exit}` +
465
+ (gate.enforce ? '' : ', not enforced') +
466
+ (gate.couldNotRun?.gateSaid === undefined ? '' : `, gate said: "${gate.couldNotRun.gateSaid}"`) +
467
+ (conductorSaid === null ? '' : `, conductor said: "${conductorSaid}"`));
468
+ }
469
+ const notRun = (role, product, why) => `conductor: gate ${role} (${product}): skipped (${why}), no exit code`;
470
+ for (const gate of result.deferred) {
471
+ lines.push(notRun(gate.role, gate.product, `deferred to stage ${gate.stage}`));
472
+ }
473
+ for (const gate of result.skipped) {
474
+ lines.push(notRun(gate.role, gate.product, skipWording(gate.reason).line));
475
+ }
476
+ for (const gate of result.excluded) {
477
+ lines.push(notRun(gate.role, gate.product, '--gate did not name it'));
478
+ }
479
+ for (const gate of result.treeUnchanged) {
480
+ lines.push(notRun(gate.role, gate.product, 'head tree equals the base tree'));
481
+ }
482
+ return lines;
483
+ }
484
+ /**
485
+ * One warning per gate that was found on PATH at a version other than the one
486
+ * this run expected (the Action's pin).
487
+ *
488
+ * For the job log only: it names where the binary was found, and an absolute
489
+ * path has no business in a published SARIF log or a pull request comment, so
490
+ * this is never part of either report. A warning and nothing more. Resolution
491
+ * is unchanged and the gate ran (or was refused) exactly as it would have
492
+ * without it.
493
+ */
494
+ export function versionSkewWarnings(result) {
495
+ return result.gates.flatMap((gate) => gate.versionSkew === undefined
496
+ ? []
497
+ : [
498
+ `conductor: warning: ${gate.product} resolved from PATH reports version ${gate.versionSkew.found}, ` +
499
+ `but this run expects ${gate.versionSkew.expected} (the version the action pinned). ` +
500
+ `It was found at ${gate.versionSkew.path}. Resolution is unchanged and that binary was used. ` +
501
+ `Fix: remove the other ${gate.product} from PATH, or install ${gate.versionSkew.expected}.`,
502
+ ]);
503
+ }
385
504
  /**
386
505
  * How many blocking findings one gate that RAN is carrying, for the token.
387
506
  *
@@ -405,6 +524,8 @@ function blockingCount(gate) {
405
524
  * the state without parsing the verdict sentence.
406
525
  *
407
526
  * 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)
408
529
  * advisory-blocked (N) exit 1 that --advisory turned into exit 0
409
530
  * unenforced-findings (N) exit 0, but enforce: false gates blocked or
410
531
  * could not run
@@ -425,8 +546,8 @@ function blockingCount(gate) {
425
546
  *
426
547
  * A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
427
548
  * than result.gates, is neither a blocking finding nor a could-not-run, and
428
- * so does not by itself move the token off pass. The verdict sentence is
429
- * where "nothing was checked" is said.
549
+ * so does not by itself move the token off pass when another gate ran. When
550
+ * NO gate ran, the token is nothing-checked, matching the verdict sentence.
430
551
  *
431
552
  * Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
432
553
  * not a pass.
@@ -443,6 +564,13 @@ export function verdictToken(result, advisory) {
443
564
  .reduce((total, gate) => total + blockingCount(gate), 0);
444
565
  return advisory ? `advisory-blocked (${count})` : `blocked (${count})`;
445
566
  }
567
+ // Exit 0 with no gate having run at all (none enabled, every one deferred,
568
+ // tree-unchanged or skipped): the exit code stays 0, since nothing failed,
569
+ // but the label must not say pass. It is the same condition the verdict
570
+ // sentence words as "nothing was checked".
571
+ if (result.gates.length === 0) {
572
+ return 'nothing-checked';
573
+ }
446
574
  const unenforced = result.gates
447
575
  .filter((gate) => !gate.enforce)
448
576
  .reduce((total, gate) => total + (gate.couldNotRun !== null ? 1 : blockingCount(gate)), 0);
@@ -456,8 +584,11 @@ function verdict(result, advisory) {
456
584
  // them would describe a different run from the one that happened. A
457
585
  // refusal is a could-not-run outcome (exit 2), which --advisory never
458
586
  // touches, so this branch reads advisory or not exactly the same.
459
- return (`verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
460
- 'so no gate ran and nothing here is a result of any kind.');
587
+ return result.trustBase?.notGiven === true
588
+ ? 'verdict: exit 2, this is a pull-request job and no trust base was given, so no rules ' +
589
+ 'were read, no gate ran and nothing here is a result of any kind.'
590
+ : `verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
591
+ 'so no gate ran and nothing here is a result of any kind.';
461
592
  }
462
593
  return verdictForRun(result, advisory);
463
594
  }
@@ -614,6 +745,9 @@ function isFullyClean(result) {
614
745
  return result.gates.every((gate) => gate.couldNotRun === null &&
615
746
  (gate.exitCode ?? 0) === 0 &&
616
747
  gate.diagnostics.length === 0 &&
748
+ // A note about an input this run did not use is never folded into the
749
+ // one-line summary, where nobody would see it.
750
+ gate.intent?.note === undefined &&
617
751
  !gate.findings.some((finding) => finding.blocking));
618
752
  }
619
753
  /**
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') {
package/dist/products.js CHANGED
@@ -39,7 +39,7 @@ function managedRemedy(product) {
39
39
  ? `Install the gate outside the tree with npm install -g @vaultcompass/${product}. The ` +
40
40
  `conductor Action does exactly that, at the version its ${product}-version input pins, and ` +
41
41
  'that pin lives in the workflow file on the base branch.'
42
- : `Install it with npm install -g @vaultcompass/${product}, or add it to the repository's devDependencies.`;
42
+ : `The package is @vaultcompass/${product}, never the unscoped name: install it with npm install -g @vaultcompass/${product}, or add @vaultcompass/${product} to the repository's devDependencies.`;
43
43
  }
44
44
  function managedProfile(product) {
45
45
  return {
package/dist/resolve.d.ts CHANGED
@@ -55,6 +55,7 @@ export interface ResolveOptions {
55
55
  export declare class ResolveError extends Error {
56
56
  constructor(message: string);
57
57
  }
58
+ export declare function findOnPath(name: string, pathValue: string): string | null;
58
59
  /**
59
60
  * The node_modules/.bin candidate a pull-request run declined to take.
60
61
  *
package/dist/resolve.js CHANGED
@@ -106,7 +106,7 @@ function existsAsFile(candidate) {
106
106
  return false;
107
107
  }
108
108
  }
109
- function findOnPath(name, pathValue) {
109
+ export function findOnPath(name, pathValue) {
110
110
  for (const dir of pathValue.split(path.delimiter)) {
111
111
  if (dir.length === 0) {
112
112
  continue;
package/dist/run.d.ts CHANGED
@@ -137,6 +137,13 @@ export interface RunTrustBase {
137
137
  * instead of being spawned.
138
138
  */
139
139
  treeUnchanged?: boolean;
140
+ /**
141
+ * True on the refusal for a pull-request job that gave no trust base at
142
+ * all (GITHUB_ACTIONS and GITHUB_BASE_REF set, no --trust-base). `ref` is
143
+ * then empty, and the reports say no trust base was given and no rules
144
+ * were read, rather than naming a ref.
145
+ */
146
+ notGiven?: boolean;
140
147
  }
141
148
  export interface RunResult {
142
149
  schemaVersion: 1;
@@ -242,5 +249,6 @@ export interface RunOptions {
242
249
  export declare function refusedTrustBase(policy: Policy, ref: string, detail: string, options: {
243
250
  stage?: GateStage;
244
251
  now?: () => Date;
252
+ notGiven?: boolean;
245
253
  }): RunResult;
246
254
  export declare function runAll(policy: Policy, options: RunOptions): RunResult;