@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.
- package/README.md +153 -14
- package/dist/cli.js +36 -3
- package/dist/init-hook-detect.d.ts +195 -0
- package/dist/init-hook-detect.js +315 -0
- package/dist/init-manifest.d.ts +64 -0
- package/dist/init-manifest.js +127 -0
- package/dist/init-policy.d.ts +12 -0
- package/dist/init-policy.js +103 -0
- package/dist/init.d.ts +7 -42
- package/dist/init.js +17 -539
- package/dist/output-text.d.ts +43 -0
- package/dist/output-text.js +56 -8
- package/package.json +1 -1
package/dist/output-text.d.ts
CHANGED
|
@@ -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;
|
package/dist/output-text.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
}
|