@vaultcompass/conductor 0.2.4 → 0.3.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 CHANGED
@@ -54,6 +54,55 @@ export interface SkippedGate {
54
54
  reason: 'no-contract' | 'contract-waived';
55
55
  detail: string;
56
56
  }
57
+ /**
58
+ * One control input this pull request proposes to change.
59
+ *
60
+ * A statement about CONFIGURATION, never a finding. It carries no severity,
61
+ * no fingerprint and no blocking flag, it is not in `findings`, and nothing
62
+ * here reaches the exit code: a pull request is allowed to propose changing
63
+ * the rules, and the whole of the mechanism is that the proposal does not
64
+ * take effect for the run that carries it. What it must do is be VISIBLE, so
65
+ * a reviewer meets "this pull request also proposes to loosen the gate" as
66
+ * one sentence beside the verdict.
67
+ *
68
+ * `line` is the sentence the gate that owns the control input wrote, carried
69
+ * verbatim. The umbrella writes only its own, about its own policy file.
70
+ */
71
+ export interface ControlProposal {
72
+ /** The gate that raised it, or the umbrella for its own policy file. */
73
+ product: Product | 'conductor';
74
+ /** The role that gate fills, or null for the umbrella's own. */
75
+ role: GateRole | null;
76
+ line: string;
77
+ }
78
+ /**
79
+ * Pull-request mode as the whole run saw it.
80
+ *
81
+ * `policyChanged` is decided in one place, before any gate runs, by comparing
82
+ * the policy file at the base ref with the one at the head commit. It is
83
+ * reported and never acted on: the base ref's policy is the one that ran.
84
+ */
85
+ export interface RunTrustBase {
86
+ /** The ref the umbrella took its own policy from. */
87
+ ref: string;
88
+ /** Whether the head commit's own policy file differs from that one. */
89
+ policyChanged: boolean;
90
+ /**
91
+ * Why this ref could not be used at all, or null when it was.
92
+ *
93
+ * A SEPARATE FIELD RATHER THAN AN ABSENT `trustBase`, and it is load-bearing
94
+ * in both renderers. A refusal is the worst outcome this tool has -- nothing
95
+ * was checked, on a run that was supposed to be the gate -- and it has to be
96
+ * the first thing a reader meets rather than something inferred from an exit
97
+ * code. Both reports used to work the number of gates out first, and an
98
+ * inventory naming no gate (every gate `enabled: false` in the head's file,
99
+ * or a head file that will not parse) then printed "no gate ran because none
100
+ * is enabled" in text and `{"runs": []}` in SARIF, with the refusal sentence
101
+ * nowhere. That is reachable on the DEFAULT actions/checkout, which fetches
102
+ * depth 1 and so carries no base ref.
103
+ */
104
+ refusal: string | null;
105
+ }
57
106
  export interface RunResult {
58
107
  schemaVersion: 1;
59
108
  generatedAt: string;
@@ -70,6 +119,14 @@ export interface RunResult {
70
119
  * consumer reads one list instead of three.
71
120
  */
72
121
  findings: Finding[];
122
+ /** Present only on a pull-request run; null means ordinary mode. */
123
+ trustBase: RunTrustBase | null;
124
+ /**
125
+ * Every control input this pull request proposes to change, the umbrella's
126
+ * own policy file first and then each gate's, in gate order. Empty outside
127
+ * pull-request mode, and empty inside it when nothing was proposed.
128
+ */
129
+ proposals: ControlProposal[];
73
130
  summary: {
74
131
  blocking: number;
75
132
  byProduct: Record<string, number>;
@@ -91,6 +148,14 @@ export interface RunOptions {
91
148
  base?: string;
92
149
  /** An explicit spec for the intent gate, outranking every other source. */
93
150
  spec?: string;
151
+ /**
152
+ * Pull-request mode. The policy this run was handed was ALREADY read from
153
+ * this ref by the caller: `runAll` does not read it, because the policy has
154
+ * to be parsed before there is a run to configure. What this carries is the
155
+ * ref, so it can be passed down to every child that can take it, and the
156
+ * one fact the caller established while reading it.
157
+ */
158
+ trustBase?: RunTrustBase;
94
159
  /**
95
160
  * The environment the pull-request defaults are read from.
96
161
  *
@@ -111,4 +176,31 @@ export interface RunOptions {
111
176
  */
112
177
  tempRoot?: string;
113
178
  }
179
+ /**
180
+ * The run that never happened, because the trust base could not be judged
181
+ * against.
182
+ *
183
+ * EVERY ENABLED GATE IS COULD-NOT-RUN, which is the fail-closed half of
184
+ * pull-request mode. A base ref that will not resolve is not a reason to fall
185
+ * back to the head's policy: falling back to the head is the behaviour this
186
+ * release removes, and it would be reachable by anybody who could make the
187
+ * base ref unfetchable.
188
+ *
189
+ * TWO THINGS HERE ARE DELIBERATELY NOT READ OFF THE POLICY, and both are the
190
+ * point rather than shortcuts. The policy handed in is the HEAD's, used only
191
+ * as an inventory so the report can name the gates that did not run; it
192
+ * cannot be trusted, so:
193
+ *
194
+ * - Every synthesized outcome is ENFORCED, whatever the file says. The
195
+ * `enforce` flag is itself a control input, and the file it lives in is
196
+ * the one that could not be read from the base. A head policy setting
197
+ * `enforce: false` everywhere must not be able to turn this into exit 0.
198
+ * - The exit code is written here rather than composed. A head policy
199
+ * enabling NO gate at all would otherwise compose to 0 over an empty list,
200
+ * which would report a run that checked nothing as a clean one.
201
+ */
202
+ export declare function refusedTrustBase(policy: Policy, ref: string, detail: string, options: {
203
+ stage?: GateStage;
204
+ now?: () => Date;
205
+ }): RunResult;
114
206
  export declare function runAll(policy: Policy, options: RunOptions): RunResult;
package/dist/run.js CHANGED
@@ -1,11 +1,12 @@
1
1
  // One run across every enabled gate.
2
2
  import { compareFindings } from './envelope.js';
3
- import { composeExitCode } from './exit-codes.js';
3
+ import { EXIT_COULD_NOT_RUN, composeExitCode } from './exit-codes.js';
4
4
  import { preparationFailed, runGate } from './gate-runner.js';
5
5
  import { resolveBaseRef } from './intent-base.js';
6
- import { prepareIntent } from './intent-prepare.js';
6
+ import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
7
7
  import { GATE_ROLES, enabledGates, runsAtStage } from './policy.js';
8
8
  import { ResolveError, resolveGateBinary } from './resolve.js';
9
+ import { POLICY_PROPOSAL_LINE } from './trust-base.js';
9
10
  /**
10
11
  * Whether this run is the pull-request shaped one.
11
12
  *
@@ -36,13 +37,21 @@ function intentBinary(gate, options) {
36
37
  return null;
37
38
  }
38
39
  }
39
- export function runAll(policy, options) {
40
+ /**
41
+ * The three lists a stage filter and a `--gate` flag produce between them.
42
+ *
43
+ * Factored out because the trust-base refusal below needs the same partition:
44
+ * a run that could not read its policy from the base ref still has to report
45
+ * the gates it did not run and the stage each of them sits at, or the report
46
+ * of the most serious failure this tool has is thinner than the report of an
47
+ * ordinary one.
48
+ */
49
+ function partitionGates(policy, requested) {
40
50
  const enabled = enabledGates(policy);
41
51
  // Partitioned before anything is spawned, and before any binary is even
42
52
  // looked for: a gate that will not run at this stage must not be able to
43
53
  // fail the run by being uninstalled here. An intent gate that lives only
44
54
  // on the CI image is the ordinary case, not an error.
45
- const requested = options.stage;
46
55
  const gates = requested === undefined ? enabled : enabled.filter((gate) => runsAtStage(gate.stage, requested));
47
56
  const deferred = requested === undefined
48
57
  ? []
@@ -52,7 +61,100 @@ export function runAll(policy, options) {
52
61
  // Read off the policy rather than off the enabled list, because these gates
53
62
  // are exactly the ones the override took out of it. In role order, so a
54
63
  // 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 }));
64
+ const excluded = GATE_ROLES.map((role) => policy.gates[role])
65
+ .filter((gate) => gate !== undefined && gate.excludedByCli)
66
+ .map((gate) => ({ role: gate.role, product: gate.product }));
67
+ return { gates, deferred, excluded };
68
+ }
69
+ /**
70
+ * The run that never happened, because the trust base could not be judged
71
+ * against.
72
+ *
73
+ * EVERY ENABLED GATE IS COULD-NOT-RUN, which is the fail-closed half of
74
+ * pull-request mode. A base ref that will not resolve is not a reason to fall
75
+ * back to the head's policy: falling back to the head is the behaviour this
76
+ * release removes, and it would be reachable by anybody who could make the
77
+ * base ref unfetchable.
78
+ *
79
+ * TWO THINGS HERE ARE DELIBERATELY NOT READ OFF THE POLICY, and both are the
80
+ * point rather than shortcuts. The policy handed in is the HEAD's, used only
81
+ * as an inventory so the report can name the gates that did not run; it
82
+ * cannot be trusted, so:
83
+ *
84
+ * - Every synthesized outcome is ENFORCED, whatever the file says. The
85
+ * `enforce` flag is itself a control input, and the file it lives in is
86
+ * the one that could not be read from the base. A head policy setting
87
+ * `enforce: false` everywhere must not be able to turn this into exit 0.
88
+ * - The exit code is written here rather than composed. A head policy
89
+ * enabling NO gate at all would otherwise compose to 0 over an empty list,
90
+ * which would report a run that checked nothing as a clean one.
91
+ */
92
+ export function refusedTrustBase(policy, ref, detail, options) {
93
+ const { gates, deferred, excluded } = partitionGates(policy, options.stage);
94
+ const outcomes = gates.map((gate) => preparationFailed({ ...gate, enforce: true }, `the trust base could not be used: ${detail}`));
95
+ const findings = outcomes.flatMap((outcome) => outcome.findings).sort(compareFindings);
96
+ const byProduct = {};
97
+ const bySeverity = {};
98
+ for (const finding of findings) {
99
+ byProduct[finding.product] = (byProduct[finding.product] ?? 0) + 1;
100
+ bySeverity[finding.severity] = (bySeverity[finding.severity] ?? 0) + 1;
101
+ }
102
+ return {
103
+ schemaVersion: 1,
104
+ generatedAt: (options.now?.() ?? new Date()).toISOString(),
105
+ gates: outcomes,
106
+ deferred,
107
+ skipped: [],
108
+ excluded,
109
+ findings,
110
+ // policyChanged is unknowable: the base side of the comparison is the
111
+ // thing that could not be read. False rather than a third state, because
112
+ // no proposal is reported on a run where nothing was judged. The refusal
113
+ // itself is carried, and it is what both renderers lead with.
114
+ trustBase: { ref, policyChanged: false, refusal: detail },
115
+ proposals: [],
116
+ summary: {
117
+ blocking: findings.filter((finding) => finding.blocking).length,
118
+ byProduct,
119
+ bySeverity,
120
+ },
121
+ exitCode: EXIT_COULD_NOT_RUN,
122
+ };
123
+ }
124
+ /**
125
+ * Every proposed control change, the umbrella's own policy first.
126
+ *
127
+ * The umbrella's line comes first because it is the one that decides what the
128
+ * others even are: a pull request that rewrites `.guardrails.yaml` is
129
+ * proposing to change which gates run at all, and reading that after a gate's
130
+ * own contract line would bury it.
131
+ */
132
+ function collectProposals(outcomes, trustBase) {
133
+ const proposals = [];
134
+ if (trustBase?.policyChanged === true) {
135
+ proposals.push({ product: 'conductor', role: null, line: POLICY_PROPOSAL_LINE });
136
+ }
137
+ for (const outcome of outcomes) {
138
+ for (const line of outcome.trustBase?.proposals ?? []) {
139
+ proposals.push({ product: outcome.product, role: outcome.role, line });
140
+ }
141
+ }
142
+ return proposals;
143
+ }
144
+ /**
145
+ * The `intentContract` option for a run with no preparation, or nothing.
146
+ *
147
+ * A small helper rather than an inline conditional because the spread at the
148
+ * call site is already three lines, and because "nothing" has to be an empty
149
+ * object rather than an undefined property: the option is optional and
150
+ * `exactOptionalPropertyTypes` refuses an explicit undefined.
151
+ */
152
+ function nativeContractOption(repoRoot) {
153
+ const contract = frozenNativeContractPath(repoRoot);
154
+ return contract === null ? {} : { intentContract: contract };
155
+ }
156
+ export function runAll(policy, options) {
157
+ const { gates, deferred, excluded } = partitionGates(policy, options.stage);
56
158
  const env = options.env ?? {};
57
159
  const skipped = [];
58
160
  const cleanups = [];
@@ -104,6 +206,16 @@ export function runAll(policy, options) {
104
206
  pathValue: options.pathValue,
105
207
  ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
106
208
  ...(intent === undefined ? {} : { intent }),
209
+ // For a run with no preparation: which contract the child will read
210
+ // out of the repository itself. Looked up only for the gate it is
211
+ // about, so no other gate pays for the two stat calls.
212
+ ...(intent !== undefined || gate.role !== 'intent'
213
+ ? {}
214
+ : nativeContractOption(options.repoRoot)),
215
+ // Offered to every child. runGate decides which ones can take it,
216
+ // so a gate with no pull-request mode yet is not handed a flag it
217
+ // would reject, and the reason it was withheld is on the outcome.
218
+ ...(options.trustBase === undefined ? {} : { trustBase: options.trustBase.ref }),
107
219
  }));
108
220
  }
109
221
  }
@@ -138,6 +250,8 @@ export function runAll(policy, options) {
138
250
  skipped,
139
251
  excluded,
140
252
  findings,
253
+ trustBase: options.trustBase ?? null,
254
+ proposals: collectProposals(outcomes, options.trustBase),
141
255
  summary: {
142
256
  blocking: findings.filter((finding) => finding.blocking).length,
143
257
  byProduct,
@@ -0,0 +1,142 @@
1
+ /**
2
+ * Why this ref cannot be a trust base, or null when it can.
3
+ *
4
+ * A string rather than a thrown error, because the caller does not print it
5
+ * and stop: every enabled gate becomes could-not-run carrying this sentence,
6
+ * so the report names the gates that did not run rather than only the ref
7
+ * that was wrong.
8
+ *
9
+ * The four sentences mirror intent-guard's own refusals, which the umbrella
10
+ * would otherwise meet second-hand as a child's exit 2. Refusing here means
11
+ * the umbrella never spawns a child at all on a base it has already decided
12
+ * it cannot judge against, and it means the two gates give a user the same
13
+ * answer to the same mistake.
14
+ */
15
+ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): string | null;
16
+ /**
17
+ * The policy file's contents at a ref, or null when that ref carries none.
18
+ *
19
+ * `git show`, never a checkout switch and never a read from the working
20
+ * tree. The `./` is load-bearing for the same reason it is in intent-guard:
21
+ * it makes git resolve the path relative to the working directory, which is
22
+ * the repository root here, rather than to wherever the repository root would
23
+ * be from somewhere else.
24
+ */
25
+ export declare function readPolicyAtRef(repoRoot: string, ref: string): string | null;
26
+ /**
27
+ * Whether two policy files differ in what they SAY.
28
+ *
29
+ * Compared as parsed documents rather than as bytes, so a reflowed list, a
30
+ * changed quote style or an edited comment is not reported as a proposal to
31
+ * change the rules; a report that cries wolf on whitespace is a report
32
+ * reviewers learn to skip. When either side will not parse, the raw text is
33
+ * compared instead, which is the fail-closed direction: an unparseable head
34
+ * policy is reported as a change rather than quietly matching.
35
+ *
36
+ * BOTH SIDES COME FROM `git show`, base and head alike, and that is not an
37
+ * accident of implementation. intent-guard read its head side from the
38
+ * working tree with a call that follows symlinks, so a pull request that
39
+ * replaced a control file with a link compared equal to the base and was
40
+ * reported as changing nothing. One reader for both sides is the only way the
41
+ * two can be compared on equal terms, and it also means an uncommitted local
42
+ * edit is not reported as something the pull request proposes.
43
+ */
44
+ export declare function policyDiffers(base: string | null, head: string | null): boolean;
45
+ /** The one line the report prints when the head proposes a different policy. */
46
+ export declare const POLICY_PROPOSAL_LINE = "policy changed in this pull request";
47
+ /**
48
+ * One path's tree entry at a ref, or null when the ref has no such path.
49
+ *
50
+ * `ls-tree` rather than `git show`, because the BLOB ID is the thing being
51
+ * compared and `show` prints contents without telling you what kind of entry
52
+ * produced them. The mode comes with it, so a regular file can be told from a
53
+ * symlink, a submodule or a directory in the same read.
54
+ */
55
+ export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): {
56
+ mode: string;
57
+ type: string;
58
+ sha: string;
59
+ } | null;
60
+ /**
61
+ * Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
62
+ *
63
+ * Reading the rules from the base ref is worth nothing if the pull request
64
+ * chooses the program that applies them, and it can, three ways that all look
65
+ * ordinary in a diff:
66
+ *
67
+ * - A base policy whose `command:` points INSIDE the repository, at
68
+ * something like `vendor/vault-guard`. The path came from the base and is
69
+ * therefore approved; the FILE AT THAT PATH is whatever the head commit
70
+ * put there. The umbrella then runs the pull request's own program, is
71
+ * told the scan was clean, and reports a clean scan.
72
+ *
73
+ * - No `command:` at all. Resolution prefers the repository's own
74
+ * `node_modules/.bin` over PATH, deliberately, so that a project pin beats
75
+ * a global install. A head that commits `node_modules/.bin/vault-guard`
76
+ * shadows the real gate, and a stub that answers `--version` with a
77
+ * plausible number passes every check the umbrella makes. The composite
78
+ * action installs nothing, so the plant survives an install step.
79
+ *
80
+ * - A base-approved WRAPPER. `vendor/vault-guard` is byte for byte what the
81
+ * base approved and is the path the policy names; it execs
82
+ * `vendor/impl.sh`, which the head rewrote. Nothing in the diff touches
83
+ * the path the policy names, so a per-file check waves it through. This
84
+ * one was found by a reviewer after the first two were closed, and it is
85
+ * why the unit of approval is a directory rather than a file.
86
+ *
87
+ * THE RULE. A program is acceptable when it is outside the working tree
88
+ * entirely: on PATH, or an absolute `command:` somewhere else on the machine.
89
+ * A pull request cannot write those. A program INSIDE the working tree is
90
+ * acceptable only when BOTH hold: it is a tracked regular file whose blob is
91
+ * IDENTICAL at the trust base and at HEAD, AND the tree object id of its
92
+ * CONTAINING DIRECTORY is identical at those two refs. The first is the same
93
+ * base-versus-head test the rules themselves get, applied to the thing that
94
+ * enforces them; the second extends it to everything beside the program,
95
+ * which is what the wrapper shape needs and what a per-file test cannot give.
96
+ *
97
+ * A tree object id covers a whole subtree in one comparison, so this needs no
98
+ * knowledge of what a wrapper calls. WHAT IS VETTED IS THE PROGRAM FILE AND
99
+ * ITS DIRECTORY SUBTREE AND NOTHING ELSE: anything the program reaches
100
+ * outside that directory is not vetted, so an in-repo gate has to be
101
+ * self-contained within its own directory. That limit is stated in the README
102
+ * in those words, because an adopter has to be able to satisfy it.
103
+ *
104
+ * A PROGRAM AT THE REPOSITORY ROOT IS REFUSED. There the containing directory
105
+ * is the whole repository, so the comparison is the root tree and every pull
106
+ * request that changed anything differs, which is every pull request.
107
+ * Refusing with the remedy in the message beats a rule that silently means
108
+ * "no pull request may change anything".
109
+ *
110
+ * NOTHING HERE READS THE WORKING TREE. Both sides come from `git ls-tree`, so
111
+ * an uncommitted local edit cannot make a file look approved and a tracked
112
+ * file cannot be vouched for by a copy on disk that git has never seen.
113
+ *
114
+ * NODE_MODULES IS NEVER BASE-APPROVED, and the reason is worth stating
115
+ * because "but the lockfile is committed" is the obvious objection. What is
116
+ * under `node_modules` is chosen by the head's own manifest and lockfile and
117
+ * installed by a step that runs before this one; git has no record of those
118
+ * bytes at either ref, so `ls-tree` finds nothing and the rule refuses. That
119
+ * is the correct answer rather than a limitation: a pull request that edits
120
+ * its lockfile to pull a different build of a gate has chosen its own judge
121
+ * just as surely as one that commits a stub.
122
+ *
123
+ * BOTH THE PROGRAM'S OWN PATH AND ITS REALPATH ARE VETTED, because a
124
+ * head-committed symlink is a choice of program too. An in-repo symlink is
125
+ * refused on its OWN entry, before its target matters: it is either untracked
126
+ * or its tree entry is a link rather than a regular file, and either refuses.
127
+ * Vetting the target is what catches a link whose own path is outside the
128
+ * tree pointing into it; it never decides the in-repo case.
129
+ */
130
+ export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string): string | null;
131
+ /**
132
+ * Whether a gate's reported version is at least `minimum`.
133
+ *
134
+ * Numeric per component, not a string comparison, or "1.10.0" would sort
135
+ * below "1.4.0". A version that cannot be read at all answers FALSE, which is
136
+ * the safe direction for the one thing this decides: whether to hand a child
137
+ * a flag an older build of it would reject outright. A gate that refused an
138
+ * unknown flag would exit non-zero with no JSON, which the umbrella reports
139
+ * as could-not-run, so guessing high turns a working run into a broken one
140
+ * for every repository pinning an older gate.
141
+ */
142
+ export declare function atLeastVersion(version: string | null, minimum: string): boolean;