@vaultcompass/conductor 0.8.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.
@@ -15,6 +15,16 @@ export type SpecDiscovery =
15
15
  /** The pull request body said `Spec: none`: there is nothing to import. */
16
16
  | {
17
17
  kind: 'waived';
18
+ }
19
+ /**
20
+ * The convention spec, or the plan for any spec, resolves outside the
21
+ * repository (its directory is a symlink pointing out of the checkout).
22
+ * Refused rather than read, and rather than dropped: the gate is reported
23
+ * as unable to run, never as having nothing to check.
24
+ */
25
+ | {
26
+ kind: 'escaped';
27
+ path: string;
18
28
  } | {
19
29
  kind: 'none';
20
30
  };
@@ -72,4 +82,22 @@ export declare function stemMatches(stem: string, slug: string): boolean;
72
82
  export declare function specFromPrBody(body: string): string | null;
73
83
  /** `pull_request.body` out of a GitHub event payload, or null. */
74
84
  export declare function prBodyFromEvent(eventPath: string): string | null;
85
+ /**
86
+ * The best of the candidates whose stem relates to `target`, or undefined.
87
+ *
88
+ * `stemMatches` decides who is a CANDIDATE; this decides who wins, and the
89
+ * two are different questions. Ranking on the lexically newest filename alone
90
+ * was answering the second with the first: a loose candidate carrying a later
91
+ * date beat the spec whose stem was the branch slug exactly, and an undated
92
+ * name beat everything because it sorts after every date. A pull request was
93
+ * then measured against a different feature's requirements, with nothing in
94
+ * the report saying so, since naming the spec it used is exactly what the
95
+ * report does.
96
+ *
97
+ * So: an exact stem first, then the most specific stem, and only then the
98
+ * newest name. Specificity is stem LENGTH, which is crude but is the property
99
+ * the failure actually had: "superpowers" beat
100
+ * "1.2.1-base-and-superpowers" by being shorter and vaguer.
101
+ */
102
+ export declare function bestMatch(names: string[], target: string): string | undefined;
75
103
  export declare function discoverSpec(options: SpecDiscoveryOptions): SpecDiscovery;
@@ -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' };
package/dist/normalize.js CHANGED
@@ -337,10 +337,12 @@ export function normalizeVaultGuard(raw, version) {
337
337
  run: {
338
338
  failOn: threshold,
339
339
  suppressed: typeof run.baseline_suppressed === 'number' ? run.baseline_suppressed : 0,
340
- // vault-guard does not report an ignore count separately; ignored
341
- // files never reach the output at all. Reporting 0 here would claim a
342
- // fact the gate did not state, so the report says "not reported"
343
- // 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.
344
346
  ignored: 0,
345
347
  // vault-guard's diagnostics carry a context object rather than a
346
348
  // message, so the context is rendered as one. Validated the same way
@@ -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,6 +43,36 @@ 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
@@ -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
  *
@@ -465,8 +584,11 @@ function verdict(result, advisory) {
465
584
  // them would describe a different run from the one that happened. A
466
585
  // refusal is a could-not-run outcome (exit 2), which --advisory never
467
586
  // touches, so this branch reads advisory or not exactly the same.
468
- return (`verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
469
- 'so no gate ran and nothing here is a result of any kind.');
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.';
470
592
  }
471
593
  return verdictForRun(result, advisory);
472
594
  }
@@ -623,6 +745,9 @@ function isFullyClean(result) {
623
745
  return result.gates.every((gate) => gate.couldNotRun === null &&
624
746
  (gate.exitCode ?? 0) === 0 &&
625
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 &&
626
751
  !gate.findings.some((finding) => finding.blocking));
627
752
  }
628
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/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;