@vaultcompass/conductor 0.2.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.
@@ -0,0 +1,105 @@
1
+ export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
2
+ /** Highest first. Used only for report ordering, never to decide blocking. */
3
+ export declare const SEVERITY_ORDER: readonly Severity[];
4
+ /**
5
+ * The four-level ladder dep-guard and vault-guard share, plus the
6
+ * thresholds they both accept. `info` is the umbrella's own fifth level and
7
+ * never appears in either product's own output, so it is not on this ladder.
8
+ */
9
+ export declare const SHARED_LADDER: readonly string[];
10
+ export type FingerprintStability = 'stable' | 'positional' | 'none';
11
+ export interface Fingerprint {
12
+ /** The product's own value, verbatim and unhashed. */
13
+ value: string;
14
+ /** Which product's namespace the value lives in. */
15
+ scope: string;
16
+ stability: FingerprintStability;
17
+ }
18
+ export type Subject = {
19
+ kind: 'package';
20
+ name: string;
21
+ manifest: string;
22
+ lockfile?: string;
23
+ }
24
+ /** `column` and `endColumn` are 1-based here even where the source is 0-based. */
25
+ | {
26
+ kind: 'location';
27
+ file: string;
28
+ line: number;
29
+ column: number;
30
+ endColumn?: number;
31
+ } | {
32
+ kind: 'paths';
33
+ paths: string[];
34
+ } | {
35
+ kind: 'contract';
36
+ category?: string;
37
+ }
38
+ /** No subject exists. Used for findings about a gate rather than about code. */
39
+ | {
40
+ kind: 'none';
41
+ };
42
+ export interface Finding {
43
+ schemaVersion: 1;
44
+ /** The gate that produced it, or "conductor" for the umbrella's own findings. */
45
+ product: string;
46
+ /** Read from the binary's --version, or null when it could not be asked. */
47
+ productVersion: string | null;
48
+ ruleId: string;
49
+ severity: Severity;
50
+ severityIsDerived: boolean;
51
+ /**
52
+ * Whether this finding is one the GATE would fail a build over.
53
+ *
54
+ * The draft this package was built from says "copied from the product,
55
+ * never recomputed". That turned out not to be literally available:
56
+ * neither dep-guard nor vault-guard marks findings individually, they
57
+ * report a threshold and a count of matches at or above it. So this is
58
+ * reconstructed from the threshold the gate itself reported, using that
59
+ * gate's own documented ladder, and then CHECKED against the count the
60
+ * gate reported. A disagreement is a diagnostic and every finding in that
61
+ * gate drops to false, because the umbrella reporting "blocking" about a
62
+ * finding the gate did not block on is the failure the rule exists to
63
+ * prevent.
64
+ *
65
+ * Nothing about the composed exit code depends on this field. That comes
66
+ * from each child's own exit code, which is the only number the gate
67
+ * actually decided.
68
+ */
69
+ blocking: boolean;
70
+ message: string;
71
+ subject: Subject;
72
+ /** Null when the product emits no fingerprint for this kind of finding. */
73
+ fingerprint: Fingerprint | null;
74
+ /** The product's own payload, verbatim. */
75
+ details: Record<string, unknown>;
76
+ }
77
+ export interface Diagnostic {
78
+ code: string;
79
+ message: string;
80
+ }
81
+ /** Everything a gate's report section needs that is not a finding. */
82
+ export interface RunSummary {
83
+ /** The threshold the gate reported using, when it reports one. */
84
+ failOn: string | null;
85
+ /** Findings the gate's own baseline removed. The user's earlier decisions. */
86
+ suppressed: number;
87
+ /** Findings the gate's own ignore rules removed. */
88
+ ignored: number;
89
+ diagnostics: Diagnostic[];
90
+ /** Product-specific run facts with nowhere else to go. */
91
+ details: Record<string, unknown>;
92
+ }
93
+ export interface NormalizedGateOutput {
94
+ findings: Finding[];
95
+ run: RunSummary;
96
+ /** Problems with the normalization itself, not with the scanned code. */
97
+ diagnostics: Diagnostic[];
98
+ }
99
+ export declare class NormalizeError extends Error {
100
+ constructor(message: string);
101
+ }
102
+ /** True when `severity` is at or above `threshold` on the shared four-level ladder. */
103
+ export declare function atOrAboveThreshold(severity: string, threshold: string): boolean;
104
+ /** Orders findings for a report: blocking first, then by severity, then stably. */
105
+ export declare function compareFindings(a: Finding, b: Finding): number;
@@ -0,0 +1,75 @@
1
+ // The internal finding envelope.
2
+ //
3
+ // This shape is NOT published. SARIF is the family's published finding
4
+ // format, and every field here exists to make one SARIF mapping decision
5
+ // possible without the mapping having to know which of the three gates it
6
+ // is looking at. Keeping it internal is what lets it change when a gate
7
+ // changes, without anybody's pipeline breaking.
8
+ //
9
+ // The parts that are decisions rather than plumbing:
10
+ //
11
+ // - `ruleId` is product-namespaced, always. Two of the three products have
12
+ // open rule vocabularies (a user's own extra patterns in one, contract
13
+ // text in another), so a bare id could collide on an ordinary word like
14
+ // "dependencies" at any time. Namespacing costs nothing now and cannot
15
+ // be retrofitted once anyone has written a suppression against a bare id.
16
+ //
17
+ // - `severityIsDerived` is not decoration. Two products share a four-level
18
+ // scale exactly, so their severities map by identity and the flag is
19
+ // false. The third has no per-finding severity at all: it scores a
20
+ // weighted rubric and emits two budget outcomes, so any level the
21
+ // umbrella prints for it is the umbrella's own invention. Saying which
22
+ // is which lets a consumer choose to trust the product's own action out
23
+ // of `details` instead.
24
+ //
25
+ // - `fingerprint.stability` is the honest version of "we have a shared
26
+ // fingerprint". Each product's fingerprint is carried verbatim and
27
+ // namespaced by product; nothing is hashed together with anything else,
28
+ // because a new digest would match no existing baseline file and would
29
+ // silently invalidate every one in the wild. `stability` records what
30
+ // the value is actually worth: `stable` survives edits elsewhere in the
31
+ // file, `positional` does not, `none` means there is no id to keep.
32
+ //
33
+ // - `subject` is a union rather than a lowest common denominator. One
34
+ // product's subject is a package in a manifest, another's is a byte
35
+ // position in a file, the third's is a set of changed paths or a
36
+ // contract with no position at all. Flattening those into file-and-line
37
+ // would mean inventing a line number, and an invented line number is
38
+ // indistinguishable from a real one once it reaches a code-scanning UI.
39
+ /** Highest first. Used only for report ordering, never to decide blocking. */
40
+ export const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low', 'info'];
41
+ /**
42
+ * The four-level ladder dep-guard and vault-guard share, plus the
43
+ * thresholds they both accept. `info` is the umbrella's own fifth level and
44
+ * never appears in either product's own output, so it is not on this ladder.
45
+ */
46
+ export const SHARED_LADDER = ['low', 'medium', 'high', 'critical'];
47
+ export class NormalizeError extends Error {
48
+ constructor(message) {
49
+ super(message);
50
+ this.name = 'NormalizeError';
51
+ }
52
+ }
53
+ /** True when `severity` is at or above `threshold` on the shared four-level ladder. */
54
+ export function atOrAboveThreshold(severity, threshold) {
55
+ if (threshold === 'none') {
56
+ return false;
57
+ }
58
+ const severityIndex = SHARED_LADDER.indexOf(severity);
59
+ const thresholdIndex = SHARED_LADDER.indexOf(threshold);
60
+ if (severityIndex < 0 || thresholdIndex < 0) {
61
+ return false;
62
+ }
63
+ return severityIndex >= thresholdIndex;
64
+ }
65
+ /** Orders findings for a report: blocking first, then by severity, then stably. */
66
+ export function compareFindings(a, b) {
67
+ if (a.blocking !== b.blocking) {
68
+ return a.blocking ? -1 : 1;
69
+ }
70
+ const bySeverity = SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity);
71
+ if (bySeverity !== 0) {
72
+ return bySeverity;
73
+ }
74
+ return a.ruleId.localeCompare(b.ruleId);
75
+ }
@@ -0,0 +1,30 @@
1
+ export declare const EXIT_OK = 0;
2
+ export declare const EXIT_BLOCKED = 1;
3
+ export declare const EXIT_COULD_NOT_RUN = 2;
4
+ export interface ExitInput {
5
+ /** Non-null when this gate did not produce a usable result. */
6
+ couldNotRun: {
7
+ reason: string;
8
+ } | null;
9
+ /** The child's own exit code, or null when there was no child. */
10
+ exitCode: number | null;
11
+ /** Whether any finding from this gate is one the gate itself blocks on. */
12
+ hasBlockingFinding: boolean;
13
+ /**
14
+ * Whether this gate's verdict counts here at all.
15
+ *
16
+ * REQUIRED rather than defaulted, deliberately. A caller that forgets it
17
+ * should not compile, because the two possible mistakes are not
18
+ * symmetrical: silently defaulting to false would drop a real gate's
19
+ * verdict on the floor, and even the safe default would hide the fact
20
+ * that a call site had never thought about the question.
21
+ *
22
+ * An unenforced gate is filtered out of this decision entirely. It is not
23
+ * downgraded, and its findings are not marked non-blocking: the report
24
+ * still says exactly what the gate said. The only thing enforce: false
25
+ * changes is which number this function returns.
26
+ */
27
+ enforce: boolean;
28
+ }
29
+ export declare function composeExitCode(gates: ExitInput[]): number;
30
+ export declare function describeExitCode(code: number): string;
@@ -0,0 +1,67 @@
1
+ // How the composed exit code is decided.
2
+ //
3
+ // Not the numeric maximum of the children's codes, because the three
4
+ // products do not mean the same thing by the same number. dep-guard has a
5
+ // third code, 2, for "could not run the checks at all"; the other two have
6
+ // only 0 and 1, and both use 1 for a rejected config as well as for a real
7
+ // finding. Taking a maximum would flatten dep-guard's distinction away and
8
+ // would call a broken config a policy violation.
9
+ //
10
+ // 2 an enabled gate could not run: its binary is missing, it exited 2,
11
+ // it was rejected its own config, or its output could not be parsed.
12
+ // This outranks everything, because a gate that did not run has not
13
+ // verified anything, and a report that says "clean" when nothing
14
+ // looked is the failure this whole family exists to prevent.
15
+ //
16
+ // 1 every enabled gate ran, and at least one of them blocked.
17
+ //
18
+ // 0 every enabled gate ran, and none blocked.
19
+ //
20
+ // Two consequences worth stating rather than leaving to be discovered.
21
+ // First, 2 covers cases the products themselves report as 1, so the
22
+ // umbrella has to tell them apart from the child's OUTPUT and not from its
23
+ // exit code alone: "exited 1 and printed nothing parseable" is the reliable
24
+ // signal for a rejected config, and it is treated as could-not-run rather
25
+ // than as clean. Second, the composed code can therefore differ from the
26
+ // maximum of the children's, and that is deliberate.
27
+ //
28
+ // The umbrella never overrules a gate's own blocking decision. A gate that
29
+ // exited non-zero produces a non-zero composed code, full stop. The
30
+ // per-finding `blocking` flag can only ADD to that, never subtract: it
31
+ // exists so a gate whose exit code somehow said clean while its own report
32
+ // carried a blocking finding still fails the run.
33
+ //
34
+ // The ONE exception, and it is the repository's own written decision rather
35
+ // than a judgment made here: a gate carrying `enforce: false` in the policy
36
+ // file is left out of this composition entirely. That is the adoption ramp,
37
+ // so a gate can be switched on and read for a few weeks before it is
38
+ // allowed to refuse anybody's commit. It is not a downgrade: the gate still
39
+ // runs, its findings keep their own levels, its blocking flags are
40
+ // untouched, and both output formats say plainly that it blocked and was
41
+ // not enforced. Nothing here reads a gate's output and decides to ignore
42
+ // it; it reads a line somebody wrote in their own policy file.
43
+ export const EXIT_OK = 0;
44
+ export const EXIT_BLOCKED = 1;
45
+ export const EXIT_COULD_NOT_RUN = 2;
46
+ export function composeExitCode(gates) {
47
+ const enforced = gates.filter((gate) => gate.enforce);
48
+ if (enforced.some((gate) => gate.couldNotRun !== null)) {
49
+ return EXIT_COULD_NOT_RUN;
50
+ }
51
+ if (enforced.some((gate) => (gate.exitCode ?? 0) !== 0 || gate.hasBlockingFinding)) {
52
+ return EXIT_BLOCKED;
53
+ }
54
+ return EXIT_OK;
55
+ }
56
+ export function describeExitCode(code) {
57
+ switch (code) {
58
+ case EXIT_OK:
59
+ return 'every enabled gate ran and none blocked';
60
+ case EXIT_BLOCKED:
61
+ return 'every enabled gate ran and at least one blocked';
62
+ case EXIT_COULD_NOT_RUN:
63
+ return 'an enabled gate could not run, so nothing here is a clean result';
64
+ default:
65
+ return 'unknown';
66
+ }
67
+ }
@@ -0,0 +1,97 @@
1
+ import type { Diagnostic, Finding, RunSummary } from './envelope.js';
2
+ import type { ContractSource, IntentPreparation } from './intent-prepare.js';
3
+ import type { GatePolicy, GateRole, GateStage, Product } from './policy.js';
4
+ import type { ResolvedBinary } from './resolve.js';
5
+ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing' | 'spawn-failed' | 'gate-error' | 'unparseable-output'
6
+ /**
7
+ * The gate was never spawned because the run could not be set up for it:
8
+ * an unresolvable base ref, or a spec that would not import. Distinct from
9
+ * gate-error on purpose, since the gate itself said nothing at all.
10
+ */
11
+ | 'preparation-failed';
12
+ export interface CouldNotRun {
13
+ reason: CouldNotRunReason;
14
+ detail: string;
15
+ }
16
+ export interface GateOutcome {
17
+ role: GateRole;
18
+ product: Product;
19
+ /** The stage this gate is configured for, carried so the report can say it. */
20
+ stage: GateStage;
21
+ /**
22
+ * Whether this gate's verdict reaches the exit code. Carried on the
23
+ * outcome rather than looked up again from the policy, so a report never
24
+ * has to be handed the policy file to explain its own exit code.
25
+ */
26
+ enforce: boolean;
27
+ /** From the binary's --version, or null when there was no safe way to ask. */
28
+ productVersion: string | null;
29
+ /** The command line actually run, for the report header. */
30
+ argv: string[];
31
+ binary: ResolvedBinary | null;
32
+ exitCode: number | null;
33
+ durationMs: number;
34
+ couldNotRun: CouldNotRun | null;
35
+ findings: Finding[];
36
+ run: RunSummary;
37
+ /** Problems with the run or the normalization, not with the scanned code. */
38
+ diagnostics: Diagnostic[];
39
+ /** Kept so the report can show why a gate that could not run said no. */
40
+ stderr: string;
41
+ /**
42
+ * Present only on the intent gate, and only for a pull-request shaped run.
43
+ * Where its contract came from and what the change set was measured
44
+ * against: the two facts that decide what the gate's verdict is even about.
45
+ */
46
+ intent?: {
47
+ contractSource: ContractSource;
48
+ baseRef: string | null;
49
+ };
50
+ }
51
+ export interface RunGateOptions {
52
+ repoRoot: string;
53
+ staged: boolean;
54
+ /** PATH to search. Injected so tests never depend on the machine. */
55
+ pathValue: string;
56
+ /** Wall-clock limit per gate. */
57
+ timeoutMs?: number;
58
+ /** The contract and change set prepared for the intent gate, when there is one. */
59
+ intent?: IntentPreparation;
60
+ }
61
+ /**
62
+ * A gate that never got as far as being spawned.
63
+ *
64
+ * The preparation for the intent gate happens before any child process, and
65
+ * a failure there has to compose exactly like any other could-not-run: exit 2
66
+ * for an enforced gate and a note for an unenforced one. So it is expressed
67
+ * as an ordinary GateOutcome rather than as a fourth kind of thing the report
68
+ * would have to learn about.
69
+ */
70
+ export declare function preparationFailed(gate: GatePolicy, detail: string): GateOutcome;
71
+ /**
72
+ * The arguments the umbrella adds, per product.
73
+ *
74
+ * These are the reserved options the policy schema refuses to let a user
75
+ * set, and this is the only place they are written. The passthrough block
76
+ * goes last so a gate's own flags are visible at the end of the command
77
+ * line in the report, where they read as the user's own additions.
78
+ *
79
+ * Exported so a test can DERIVE the flags this writes and hold
80
+ * RESERVED_OPTIONS in policy.ts against them. The two lists are otherwise
81
+ * parallel and hand-maintained, and a flag added here and forgotten there
82
+ * would let a policy file write the same flag a second time, with the winner
83
+ * decided by that gate's own argument parser rather than by anything the
84
+ * user could read in their own policy file.
85
+ */
86
+ export declare function gateArgs(gate: GatePolicy, staged: boolean, intent: IntentPreparation | undefined): string[];
87
+ /**
88
+ * Runs one gate. TOTAL: this never throws.
89
+ *
90
+ * That is a contract, not a hope. The caller maps over the enabled gates in
91
+ * order, so an escaping error does not just lose this gate's report, it
92
+ * loses every gate after it, and it surfaces as a stack trace with exit 1,
93
+ * which the pre-commit hook reports as "a gate blocked". Everything that can
94
+ * go wrong here is a could-not-run for THIS gate, composing to exit 2, with
95
+ * a finding of the umbrella's own saying so.
96
+ */
97
+ export declare function runGate(gate: GatePolicy, options: RunGateOptions): GateOutcome;