@vaultcompass/conductor 0.4.5 → 0.4.7

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.
@@ -8,5 +8,48 @@ export interface TextOptions {
8
8
  * wants their own terminal to be is not that.
9
9
  */
10
10
  verbose?: boolean;
11
+ /**
12
+ * The umbrella's own package version, printed as the first line of the
13
+ * full report. This text report is also the pull-request comment body,
14
+ * and without this line nothing on it says which conductor produced it.
15
+ *
16
+ * Left out of the one-line clean summary on purpose: that line is kept to
17
+ * one line by design, and the version is not the fact a clean run needs to
18
+ * lead with. Omitted entirely (no line at all) when no version is given,
19
+ * so a caller that does not pass one sees the same report as before.
20
+ */
21
+ version?: string;
22
+ /**
23
+ * Renders a short body instead of the full report when the trust base was
24
+ * refused and no gate ran: the version, the verdict sentence, and every
25
+ * refusal detail line the full report would have printed for this case
26
+ * (`refusalLines`) -- which is the reason and, when the base ref carries
27
+ * no policy file at all, the remedy that reason names. There is no
28
+ * pointer at a step log: a fork's read-only token cannot even show the
29
+ * commenter that log, so the reason has to be ON the comment rather than
30
+ * behind a link to one.
31
+ *
32
+ * Built for the pull-request-comment step. Its whole point is otherwise a
33
+ * full sticky comment whose only content is "the trust base was refused,
34
+ * nothing was checked" -- true, but not worth the ceremony of the full
35
+ * per-gate report on every push. Every other run is unaffected: this only
36
+ * fires when the trust base was actually refused, whatever --verbose says.
37
+ */
38
+ compact?: boolean;
39
+ /**
40
+ * Maps an EXIT_BLOCKED verdict to exit 0 in the printed verdict line, and
41
+ * says so in words. This never touches the RunResult passed in: the exit
42
+ * code composed for this run (`result.exitCode`) is unchanged, and so is
43
+ * every finding's own `blocking` marker in the sections above the verdict.
44
+ * `cli.ts` is what actually maps the PROCESS exit code, from the same
45
+ * `result.exitCode` this option reads; this flag exists so the one line a
46
+ * reader is most likely to read alone does not contradict the exit code
47
+ * the process is about to produce.
48
+ *
49
+ * Has no effect on any other verdict shape: a could-not-run run (exit 2)
50
+ * reads the same whatever this says, because advisory is about a finding
51
+ * that did not block, never about a gate that did not run.
52
+ */
53
+ advisory?: boolean;
11
54
  }
12
55
  export declare function renderText(result: RunResult, options?: TextOptions): string;
@@ -338,18 +338,20 @@ function refusalLines(result) {
338
338
  ` ${refusal}`,
339
339
  ];
340
340
  }
341
- function verdict(result) {
341
+ function verdict(result, advisory) {
342
342
  const refusal = result.trustBase?.refusal;
343
343
  if (refusal !== undefined && refusal !== null) {
344
344
  // Written rather than composed, exactly as the exit code is: no gate ran,
345
345
  // so there is nothing for the clauses below to count, and every one of
346
- // them would describe a different run from the one that happened.
346
+ // them would describe a different run from the one that happened. A
347
+ // refusal is a could-not-run outcome (exit 2), which --advisory never
348
+ // touches, so this branch reads advisory or not exactly the same.
347
349
  return (`verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
348
350
  'so no gate ran and nothing here is a result of any kind.');
349
351
  }
350
- return verdictForRun(result);
352
+ return verdictForRun(result, advisory);
351
353
  }
352
- function verdictForRun(result) {
354
+ function verdictForRun(result, advisory) {
353
355
  // Counted over ENFORCED gates only. The exit code came from those alone,
354
356
  // so a count taken over all of them describes a different run from the one
355
357
  // the number at the front of the line is about, and the umbrella's own
@@ -410,16 +412,37 @@ function verdictForRun(result) {
410
412
  // on the one line somebody reads when they read nothing else contradicts
411
413
  // the exit code printed beside it, and sends a reader looking for a
412
414
  // finding that this report deliberately does not claim.
415
+ //
416
+ // ADVISORY ONLY EVER REWRITES THIS ONE BRANCH. The process's own exit
417
+ // code is decided in cli.ts by mapping EXIT_BLOCKED to EXIT_OK when
418
+ // --advisory was given; this function never changes result.exitCode
419
+ // itself, so a could-not-run verdict a few lines up is untouched
420
+ // whatever `advisory` says. The findings above this line still print
421
+ // with their BLOCKING marker: advisory changes what the exit code
422
+ // claims, never what a gate found.
413
423
  if (blocking === 0) {
424
+ // The mismatch branch: composeExitCode also lands here when an
425
+ // enforced gate exited non-zero but nothing reconciled as a blocking
426
+ // finding (conductor/blocking-count-mismatch or
427
+ // conductor/blocking-threshold-unknown; see normalize.ts). "Findings
428
+ // were advisory and did not block" would claim a finding this branch
429
+ // explicitly says there is none of, so it gets its own, narrower
430
+ // wording that is true here and says nothing about findings at all.
414
431
  const names = enforcedGates
415
432
  .filter((gate) => (gate.exitCode ?? 0) !== 0)
416
433
  .map((gate) => `${gate.role} (exit ${gate.exitCode ?? '?'})`)
417
434
  .join(', ');
418
- return (`verdict: exit 1, and no finding here is marked blocking. Enforced gate(s) that exited ` +
435
+ const base = `and no finding here is marked blocking. Enforced gate(s) that exited ` +
419
436
  `non-zero: ${names}. The umbrella could not reconcile a blocking count with what those ` +
420
- `gates reported, so the gate exit code decided the run.${aside}`);
437
+ `gates reported, so the gate exit code decided the run.${aside}`;
438
+ return advisory
439
+ ? `verdict: exit 0, ${base} This run was advisory, so exit 1 became exit 0.`
440
+ : `verdict: exit 1, ${base}`;
421
441
  }
422
- return `verdict: exit 1, ${blocking} blocking finding(s) across ${enforcedGates.length} gate(s).${aside}`;
442
+ const base = `${blocking} blocking finding(s) across ${enforcedGates.length} gate(s).${aside}`;
443
+ return advisory
444
+ ? `verdict: exit 0, ${base} Findings were advisory and did not block, so this run exits 0 rather than 1.`
445
+ : `verdict: exit 1, ${base}`;
423
446
  }
424
447
  // Exit 0 with red on the screen above it. The verdict is the one line
425
448
  // somebody reads when they read nothing else, so it is the line that has
@@ -599,8 +622,32 @@ function summaryLine(result) {
599
622
  parts.push('Re-run with --verbose for the full report.');
600
623
  return parts.join(' ');
601
624
  }
625
+ /**
626
+ * The version line, as the first line of every report that carries one.
627
+ *
628
+ * One function rather than one literal at each of the two call sites below:
629
+ * the compact body and the full report both lead with it, and a change to
630
+ * the line's wording only needs one edit to stay in sync between them.
631
+ */
632
+ function versionLine(version) {
633
+ return version === undefined ? [] : [`conductor ${version}`];
634
+ }
602
635
  export function renderText(result, options = {}) {
603
636
  const refusal = refusalLines(result);
637
+ if (options.compact === true && refusal.length > 0) {
638
+ // The version, then the verdict sentence, then EVERY refusal detail
639
+ // line the full report would have printed for this case -- refusalLines
640
+ // itself, which already carries the base-ref-specific remedy (running
641
+ // "conductor init", or reading the pull request's own file as a
642
+ // proposal) as part of the same sentence. Nothing here points at a step
643
+ // log: the reason has to be readable on the comment itself.
644
+ const lines = [
645
+ ...versionLine(options.version),
646
+ verdict(result, Boolean(options.advisory)),
647
+ ...refusal,
648
+ ];
649
+ return `${lines.join('\n')}\n`;
650
+ }
604
651
  if (refusal.length === 0 && !options.verbose && isFullyClean(result)) {
605
652
  return `${summaryLine(result)}\n`;
606
653
  }
@@ -613,6 +660,7 @@ export function renderText(result, options = {}) {
613
660
  // different questions, so two numbers, and the section headers and the
614
661
  // "not enforced" lines are what connect them.
615
662
  const lines = [
663
+ ...versionLine(options.version),
616
664
  ...refusal,
617
665
  ...(refusal.length === 0 ? [] : ['']),
618
666
  `conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
@@ -634,6 +682,6 @@ export function renderText(result, options = {}) {
634
682
  if (result.findings.some((finding) => finding.severityIsDerived)) {
635
683
  lines.push('', '* severity assigned by the umbrella; that gate reports no per-finding severity.');
636
684
  }
637
- lines.push('', verdict(result));
685
+ lines.push('', verdict(result, Boolean(options.advisory)));
638
686
  return `${lines.join('\n')}\n`;
639
687
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.4.5",
3
+ "version": "0.4.7",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [