@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.
package/dist/run.d.ts ADDED
@@ -0,0 +1,100 @@
1
+ import { type Finding } from './envelope.js';
2
+ import { type GateOutcome } from './gate-runner.js';
3
+ import type { GateRole, GateStage, Policy, Product } from './policy.js';
4
+ /**
5
+ * An enabled gate the stage filter held back.
6
+ *
7
+ * Recorded rather than dropped. A gate that is switched on and did not run
8
+ * has to be visible somewhere, or a run at `commit` reads exactly like a
9
+ * run that checked everything, which is the confusion this whole family
10
+ * exists to prevent. It is deliberately NOT a GateOutcome: no binary was
11
+ * looked for, nothing was spawned, and there is no exit code to report.
12
+ */
13
+ export interface DeferredGate {
14
+ role: GateRole;
15
+ product: Product;
16
+ /** The earliest stage at which this gate will run. */
17
+ stage: GateStage;
18
+ }
19
+ /**
20
+ * A gate `--gate` left out of this run.
21
+ *
22
+ * Recorded for the same reason a deferred gate is, and it is deliberately the
23
+ * same shape minus the stage: there is no stage at which this one comes back,
24
+ * only another command line. A gate switched on in the policy file that did
25
+ * not run has to be visible somewhere, or a `--gate secrets` run reads exactly
26
+ * like a run that checked the whole policy. It is NOT a GateOutcome for the
27
+ * same reason DeferredGate is not: no binary was looked for, nothing was
28
+ * spawned, and there is no exit code to report.
29
+ */
30
+ export interface ExcludedGate {
31
+ role: GateRole;
32
+ product: Product;
33
+ }
34
+ /**
35
+ * An enabled gate that had nothing to check.
36
+ *
37
+ * Exactly one thing produces this today: an intent gate on a branch with no
38
+ * frozen contract and no spec to import. It is not a deferred gate (nobody
39
+ * asked for a different stage), it is not a could-not-run (nothing broke),
40
+ * and it must never reach the exit code, enforced or not. A branch that has
41
+ * no spec is a branch this gate has no opinion about, and turning that into
42
+ * a failed build is how a gate gets switched off repository-wide.
43
+ */
44
+ export interface SkippedGate {
45
+ role: GateRole;
46
+ product: Product;
47
+ reason: 'no-contract';
48
+ detail: string;
49
+ }
50
+ export interface RunResult {
51
+ schemaVersion: 1;
52
+ generatedAt: string;
53
+ gates: GateOutcome[];
54
+ /** Enabled gates the requested stage held back. Empty with no --stage. */
55
+ deferred: DeferredGate[];
56
+ /** Enabled gates that ran at this stage and found nothing to check. */
57
+ skipped: SkippedGate[];
58
+ /** Gates the --gate flag left out. Empty with no --gate. */
59
+ excluded: ExcludedGate[];
60
+ /**
61
+ * Every finding, flat across products, ordered blocking-first. Which gate
62
+ * produced a finding is IN the finding rather than in the structure, so a
63
+ * consumer reads one list instead of three.
64
+ */
65
+ findings: Finding[];
66
+ summary: {
67
+ blocking: number;
68
+ byProduct: Record<string, number>;
69
+ bySeverity: Record<string, number>;
70
+ };
71
+ exitCode: number;
72
+ }
73
+ export interface RunOptions {
74
+ repoRoot: string;
75
+ staged: boolean;
76
+ pathValue: string;
77
+ timeoutMs?: number;
78
+ /**
79
+ * Which stopping point this run is. Absent means every enabled gate runs,
80
+ * which is what v0.1 did and what a bare `conductor run` still does.
81
+ */
82
+ stage?: GateStage;
83
+ /** The ref to measure the intent gate's change set against. */
84
+ base?: string;
85
+ /** An explicit spec for the intent gate, outranking every other source. */
86
+ spec?: string;
87
+ /**
88
+ * The environment the pull-request defaults are read from.
89
+ *
90
+ * Injected rather than read off `process`, exactly like `pathValue`, and it
91
+ * defaults to EMPTY rather than to `process.env`. A run is then a function
92
+ * of its arguments: without this, running this package's own suite inside a
93
+ * pull request build would put every gate into the pull-request flow,
94
+ * because Actions sets GITHUB_BASE_REF for the whole job.
95
+ */
96
+ env?: NodeJS.ProcessEnv;
97
+ /** Injected in tests so a run's output is comparable between runs. */
98
+ now?: () => Date;
99
+ }
100
+ export declare function runAll(policy: Policy, options: RunOptions): RunResult;
package/dist/run.js ADDED
@@ -0,0 +1,147 @@
1
+ // One run across every enabled gate.
2
+ import { compareFindings } from './envelope.js';
3
+ import { composeExitCode } from './exit-codes.js';
4
+ import { preparationFailed, runGate } from './gate-runner.js';
5
+ import { resolveBaseRef } from './intent-base.js';
6
+ import { prepareIntent } from './intent-prepare.js';
7
+ import { GATE_ROLES, enabledGates, runsAtStage } from './policy.js';
8
+ import { ResolveError, resolveGateBinary } from './resolve.js';
9
+ /**
10
+ * Whether this run is the pull-request shaped one.
11
+ *
12
+ * The whole intent-at-pull-request flow engages on a resolved base ref or an
13
+ * explicit `--spec`, and on nothing else. Without one of those, the intent
14
+ * gate keeps exactly the command line v0.1 gave it: a developer running
15
+ * `conductor run` on their own machine has not asked for a contract to be
16
+ * imported, and importing one anyway would change what a local run means
17
+ * without anybody having written that down.
18
+ */
19
+ function isPullRequestShaped(options, env) {
20
+ if (options.spec !== undefined) {
21
+ return true;
22
+ }
23
+ return resolveBaseRef({ ...(options.base === undefined ? {} : { base: options.base }), env }) !== null;
24
+ }
25
+ /** The intent-guard binary, or null when there is none to prepare with. */
26
+ function intentBinary(gate, options) {
27
+ try {
28
+ return resolveGateBinary(gate, options.repoRoot, options.pathValue);
29
+ }
30
+ catch (err) {
31
+ // A ResolveError means the policy named a command that is not there.
32
+ // runGate reports that properly; preparation just has nothing to run.
33
+ if (err instanceof ResolveError) {
34
+ return null;
35
+ }
36
+ return null;
37
+ }
38
+ }
39
+ export function runAll(policy, options) {
40
+ const enabled = enabledGates(policy);
41
+ // Partitioned before anything is spawned, and before any binary is even
42
+ // looked for: a gate that will not run at this stage must not be able to
43
+ // fail the run by being uninstalled here. An intent gate that lives only
44
+ // on the CI image is the ordinary case, not an error.
45
+ const requested = options.stage;
46
+ const gates = requested === undefined ? enabled : enabled.filter((gate) => runsAtStage(gate.stage, requested));
47
+ const deferred = requested === undefined
48
+ ? []
49
+ : enabled
50
+ .filter((gate) => !runsAtStage(gate.stage, requested))
51
+ .map((gate) => ({ role: gate.role, product: gate.product, stage: gate.stage }));
52
+ // Read off the policy rather than off the enabled list, because these gates
53
+ // are exactly the ones the override took out of it. In role order, so a
54
+ // report's ordering never depends on the order the flags were typed.
55
+ const excluded = GATE_ROLES.map((role) => policy.gates[role]).filter((gate) => gate !== undefined && gate.excludedByCli).map((gate) => ({ role: gate.role, product: gate.product }));
56
+ const env = options.env ?? {};
57
+ const skipped = [];
58
+ const cleanups = [];
59
+ // Sequential, not concurrent. Three Node process starts is real overhead
60
+ // in a pre-commit hook and running them at once would hide most of it,
61
+ // but interleaved stderr from three gates is unreadable exactly when a
62
+ // commit has just been refused, and v0.1's job is to be legible. This is
63
+ // the obvious thing to revisit with a measurement rather than a guess.
64
+ const outcomes = [];
65
+ try {
66
+ for (const gate of gates) {
67
+ let intent;
68
+ if (gate.role === 'intent' && isPullRequestShaped(options, env)) {
69
+ const binary = intentBinary(gate, options);
70
+ // A gate with no binary is left to runGate, which raises the
71
+ // umbrella's own gate-missing finding. Reporting the same absence
72
+ // twice, once as a failed preparation and once as a missing gate,
73
+ // would read as two problems where there is one.
74
+ if (binary !== null) {
75
+ const prepared = prepareIntent({
76
+ repoRoot: options.repoRoot,
77
+ binary,
78
+ env,
79
+ ...(options.base === undefined ? {} : { base: options.base }),
80
+ ...(options.spec === undefined ? {} : { spec: options.spec }),
81
+ ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
82
+ });
83
+ if (prepared.kind === 'skip') {
84
+ skipped.push({
85
+ role: gate.role,
86
+ product: gate.product,
87
+ reason: prepared.reason,
88
+ detail: prepared.detail,
89
+ });
90
+ continue;
91
+ }
92
+ if (prepared.kind === 'failed') {
93
+ outcomes.push(preparationFailed(gate, `the intent gate could not be prepared at the ${prepared.step} step: ${prepared.detail}`));
94
+ continue;
95
+ }
96
+ intent = prepared.preparation;
97
+ cleanups.push(prepared.preparation.cleanup);
98
+ }
99
+ }
100
+ outcomes.push(runGate(gate, {
101
+ repoRoot: options.repoRoot,
102
+ staged: options.staged,
103
+ pathValue: options.pathValue,
104
+ ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
105
+ ...(intent === undefined ? {} : { intent }),
106
+ }));
107
+ }
108
+ }
109
+ finally {
110
+ // Once every gate has run, and whatever happened while they did. runGate
111
+ // is total and nothing in the loop is expected to throw, which is exactly
112
+ // why the try is worth two lines: the cost of being wrong about that is
113
+ // one leaked directory per pull request on a shared CI runner, with
114
+ // nothing in any report pointing at the cause.
115
+ for (const cleanup of cleanups) {
116
+ cleanup();
117
+ }
118
+ }
119
+ const findings = outcomes.flatMap((outcome) => outcome.findings).sort(compareFindings);
120
+ const byProduct = {};
121
+ const bySeverity = {};
122
+ for (const finding of findings) {
123
+ byProduct[finding.product] = (byProduct[finding.product] ?? 0) + 1;
124
+ bySeverity[finding.severity] = (bySeverity[finding.severity] ?? 0) + 1;
125
+ }
126
+ const exitCode = composeExitCode(outcomes.map((outcome) => ({
127
+ couldNotRun: outcome.couldNotRun,
128
+ exitCode: outcome.exitCode,
129
+ hasBlockingFinding: outcome.findings.some((finding) => finding.blocking),
130
+ enforce: outcome.enforce,
131
+ })));
132
+ return {
133
+ schemaVersion: 1,
134
+ generatedAt: (options.now?.() ?? new Date()).toISOString(),
135
+ gates: outcomes,
136
+ deferred,
137
+ skipped,
138
+ excluded,
139
+ findings,
140
+ summary: {
141
+ blocking: findings.filter((finding) => finding.blocking).length,
142
+ byProduct,
143
+ bySeverity,
144
+ },
145
+ exitCode,
146
+ };
147
+ }
package/package.json ADDED
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "@vaultcompass/conductor",
3
+ "version": "0.2.0",
4
+ "type": "module",
5
+ "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
+ "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/vaultcompasshq/conductor.git"
10
+ },
11
+ "packageManager": "pnpm@9.15.9",
12
+ "engines": {
13
+ "node": ">=22"
14
+ },
15
+ "bin": {
16
+ "conductor": "dist/cli.js"
17
+ },
18
+ "files": [
19
+ "dist",
20
+ "schema"
21
+ ],
22
+ "scripts": {
23
+ "build": "tsc -b && chmod +x dist/cli.js",
24
+ "pretest": "pnpm build",
25
+ "test": "NODE_OPTIONS=--experimental-vm-modules jest",
26
+ "typecheck": "tsc -b && tsc --noEmit -p tsconfig.test.json",
27
+ "lint": "pnpm check:public-hygiene",
28
+ "check:public-hygiene": "node scripts/check-public-hygiene.mjs"
29
+ },
30
+ "dependencies": {
31
+ "ajv": "^8.17.1",
32
+ "commander": "^12.1.0",
33
+ "yaml": "^2.9.0"
34
+ },
35
+ "devDependencies": {
36
+ "@jest/globals": "^30.4.1",
37
+ "@types/jest": "^30.0.0",
38
+ "@types/node": "^22.19.0",
39
+ "jest": "^30.4.2",
40
+ "ts-jest": "^29.4.12",
41
+ "typescript": "^5.9.3"
42
+ }
43
+ }
@@ -0,0 +1,88 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://vaultcompass.io/schema/guardrails-1.json",
4
+ "title": "Guardrail policy file",
5
+ "description": "One policy file for a repository's guardrail gates. Gates are keyed by the ROLE they fill, not by the product that currently fills it, so replacing or renaming a product is a one-line edit rather than a schema break.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": ["version", "gates"],
9
+ "properties": {
10
+ "version": {
11
+ "description": "Policy schema version. Only 1 exists.",
12
+ "const": 1
13
+ },
14
+ "gates": {
15
+ "type": "object",
16
+ "additionalProperties": false,
17
+ "minProperties": 1,
18
+ "properties": {
19
+ "dependencies": { "$ref": "#/$defs/gate" },
20
+ "secrets": { "$ref": "#/$defs/gate" },
21
+ "intent": { "$ref": "#/$defs/gate" }
22
+ }
23
+ },
24
+ "report": {
25
+ "type": "object",
26
+ "additionalProperties": false,
27
+ "properties": {
28
+ "format": {
29
+ "description": "Default output format for `conductor run`. The --format flag overrides it.",
30
+ "enum": ["text", "sarif"]
31
+ }
32
+ }
33
+ }
34
+ },
35
+ "$defs": {
36
+ "gate": {
37
+ "type": "object",
38
+ "additionalProperties": false,
39
+ "required": ["product"],
40
+ "properties": {
41
+ "product": {
42
+ "description": "Which product currently fills this role.",
43
+ "enum": ["dep-guard", "vault-guard", "intent-guard"]
44
+ },
45
+ "enabled": {
46
+ "description": "Whether this gate runs. Defaults to true. A gate that is enabled but whose binary cannot be found is a blocking finding, never a silent skip.",
47
+ "type": "boolean",
48
+ "default": true
49
+ },
50
+ "enforce": {
51
+ "description": "Whether this gate's verdict reaches the exit code. Defaults to true. A gate with enforce false runs, reports, and appears in the text and SARIF output exactly as an enforced gate does, and never raises the exit code: neither its blocking findings nor its failure to run at all. This is the adoption ramp for a gate a repository is not ready to block on yet.",
52
+ "type": "boolean",
53
+ "default": true
54
+ },
55
+ "stage": {
56
+ "description": "When this gate runs. Stages are cumulative in the order commit, push, ci: a gate runs at its own stage and at every later one, so a run at ci runs everything enabled. Defaults to commit for dependencies and secrets, and to ci for intent, because only the intent gate carries per-task ceremony. A run with no --stage runs every enabled gate whatever its stage.",
57
+ "enum": ["commit", "push", "ci"]
58
+ },
59
+ "command": {
60
+ "description": "Absolute path to the gate's executable, overriding binary resolution. Use it to point at a build that is not on PATH.",
61
+ "type": "string",
62
+ "minLength": 1
63
+ },
64
+ "args": {
65
+ "description": "Argument prefix placed before the arguments the umbrella adds. Only meaningful alongside `command`; without it the prefix is inferred from the resolved binary's name.",
66
+ "type": "array",
67
+ "items": { "type": "string" }
68
+ },
69
+ "options": {
70
+ "description": "Handed to this gate unchanged. Each key is one of that gate's own long-flag spellings without the leading dashes; true renders as --key, false as --no-key, a scalar as --key value, and an array as one --key value pair per entry. The umbrella does not interpret any of them. Per-gate thresholds live here; there is deliberately no shared threshold, because the three products do not share one severity scale.",
71
+ "type": "object",
72
+ "propertyNames": { "pattern": "^[a-z0-9][a-z0-9-]*$" },
73
+ "additionalProperties": {
74
+ "oneOf": [
75
+ { "type": "string" },
76
+ { "type": "number" },
77
+ { "type": "boolean" },
78
+ {
79
+ "type": "array",
80
+ "items": { "oneOf": [{ "type": "string" }, { "type": "number" }] }
81
+ }
82
+ ]
83
+ }
84
+ }
85
+ }
86
+ }
87
+ }
88
+ }