@vaultcompass/conductor 0.5.0 → 0.7.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
@@ -31,6 +31,24 @@ export interface ExcludedGate {
31
31
  role: GateRole;
32
32
  product: Product;
33
33
  }
34
+ /**
35
+ * An enabled gate skipped because the head tree equals the trust base's tree
36
+ * (issue #69).
37
+ *
38
+ * Only reachable when `RunTrustBase.treeUnchanged` is true, which itself only
39
+ * happens on the one accepted equal-tree shape (see trust-base.ts): a merge
40
+ * commit whose first parent is the base. In that shape a tree-reading gate
41
+ * has nothing to judge that the base ref did not already judge, so it is
42
+ * recorded here rather than run, exactly the way DeferredGate and
43
+ * ExcludedGate record a gate that did not run rather than reporting it as
44
+ * clean. NOT a GateOutcome, for the same reason those two are not one: no
45
+ * binary was looked for, nothing was spawned, and there is no exit code to
46
+ * report.
47
+ */
48
+ export interface TreeUnchangedGate {
49
+ role: GateRole;
50
+ product: Product;
51
+ }
34
52
  /**
35
53
  * An enabled gate that had nothing to check.
36
54
  *
@@ -102,6 +120,23 @@ export interface RunTrustBase {
102
120
  * depth 1 and so carries no base ref.
103
121
  */
104
122
  refusal: string | null;
123
+ /**
124
+ * Whether HEAD's tree is byte-identical to this ref's tree, on a run that
125
+ * was not refused (issue #69).
126
+ *
127
+ * OPTIONAL, and read as false wherever absent, rather than a required
128
+ * field: most `RunTrustBase` values in this codebase's own tests are built
129
+ * by hand for a run where the trees plainly differ, and a required field
130
+ * would be a mechanical edit to every one of them for a fact that is false
131
+ * in all of them. The one place this is actually computed is `policyForRun`
132
+ * in cli.ts, which calls `headTreeEqualsBase` (trust-base.ts) right after
133
+ * `refuseTrustBaseRef` returns null, on the one shape that check accepts
134
+ * despite an identical tree. `runAll` reads it to decide which enabled
135
+ * gates run: every gate whose profile says `readsHistory` runs as usual,
136
+ * and every other enabled gate is recorded in `RunResult.treeUnchanged`
137
+ * instead of being spawned.
138
+ */
139
+ treeUnchanged?: boolean;
105
140
  }
106
141
  export interface RunResult {
107
142
  schemaVersion: 1;
@@ -113,6 +148,11 @@ export interface RunResult {
113
148
  skipped: SkippedGate[];
114
149
  /** Gates the --gate flag left out. Empty with no --gate. */
115
150
  excluded: ExcludedGate[];
151
+ /**
152
+ * Enabled gates skipped because the head tree equals the trust base's tree
153
+ * (issue #69). Always empty outside that one shape.
154
+ */
155
+ treeUnchanged: TreeUnchangedGate[];
116
156
  /**
117
157
  * Every finding, flat across products, ordered blocking-first. Which gate
118
158
  * produced a finding is IN the finding rather than in the structure, so a
package/dist/run.js CHANGED
@@ -5,6 +5,7 @@ import { gateProgramRefused, preparationFailed, refuseHeadControlledBinary, runG
5
5
  import { resolveBaseRef } from './intent-base.js';
6
6
  import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
7
7
  import { GATE_ROLES, enabledGates, runsAtStage } from './policy.js';
8
+ import { profileFor } from './products.js';
8
9
  import { ResolveError, resolveGateBinary } from './resolve.js';
9
10
  import { POLICY_PROPOSAL_LINE } from './trust-base.js';
10
11
  /**
@@ -115,6 +116,9 @@ export function refusedTrustBase(policy, ref, detail, options) {
115
116
  deferred,
116
117
  skipped: [],
117
118
  excluded,
119
+ // Always empty here: the equal-tree exception only ever applies to a run
120
+ // that was NOT refused, and this whole function is the refused path.
121
+ treeUnchanged: [],
118
122
  findings,
119
123
  // policyChanged is unknowable: the base side of the comparison is the
120
124
  // thing that could not be read. False rather than a third state, because
@@ -162,8 +166,41 @@ function nativeContractOption(repoRoot) {
162
166
  const contract = frozenNativeContractPath(repoRoot);
163
167
  return contract === null ? {} : { intentContract: contract };
164
168
  }
169
+ /**
170
+ * Splits the gates a stage and a --gate flag left in two: the ones this run
171
+ * actually spawns, and the ones it records as tree-unchanged instead
172
+ * (issue #69).
173
+ *
174
+ * A no-op, returning `gates` unchanged with an empty second list, whenever
175
+ * `treeUnchanged` is not true -- which is every run outside the one accepted
176
+ * equal-tree shape (`headTreeEqualsBase`, called from `policyForRun` in
177
+ * cli.ts right after `refuseTrustBaseRef` returns null). Inside that shape a
178
+ * tree-reading gate has nothing to judge that the base ref did not already
179
+ * judge, so only the gates whose profile says `readsHistory` -- gitleaks
180
+ * today, see src/products.ts -- are kept to run with their ordinary
181
+ * arguments; gitleaks already gets `--log-opts <base>..HEAD`
182
+ * (src/gate-runner.ts, gateArgs), which is the range that still holds
183
+ * whatever was committed and backed out.
184
+ */
185
+ function splitOnTreeUnchanged(gates, trustBase) {
186
+ if (trustBase?.treeUnchanged !== true) {
187
+ return { toRun: gates, treeUnchanged: [] };
188
+ }
189
+ const toRun = [];
190
+ const treeUnchanged = [];
191
+ for (const gate of gates) {
192
+ if (profileFor(gate.product).readsHistory) {
193
+ toRun.push(gate);
194
+ }
195
+ else {
196
+ treeUnchanged.push({ role: gate.role, product: gate.product });
197
+ }
198
+ }
199
+ return { toRun, treeUnchanged };
200
+ }
165
201
  export function runAll(policy, options) {
166
- const { gates, deferred, excluded } = partitionGates(policy, options.stage);
202
+ const { gates: partitioned, deferred, excluded } = partitionGates(policy, options.stage);
203
+ const { toRun: gates, treeUnchanged } = splitOnTreeUnchanged(partitioned, options.trustBase);
167
204
  const env = options.env ?? {};
168
205
  const skipped = [];
169
206
  const cleanups = [];
@@ -284,6 +321,7 @@ export function runAll(policy, options) {
284
321
  deferred,
285
322
  skipped,
286
323
  excluded,
324
+ treeUnchanged,
287
325
  findings,
288
326
  trustBase: options.trustBase ?? null,
289
327
  proposals: collectProposals(outcomes, options.trustBase),
@@ -1,3 +1,16 @@
1
+ /**
2
+ * Whether HEAD's tree is byte-identical to the trust base's tree.
3
+ *
4
+ * Exported separately from `refuseTrustBaseRef` rather than folded into its
5
+ * return value, so that function's return type stays the simple `string |
6
+ * null` every other caller and test already reads. The one caller that needs
7
+ * this fact (`policyForRun` in cli.ts) calls it AFTER the refusal check has
8
+ * already passed, on the one shape that is accepted despite an identical
9
+ * tree: a merge commit whose first parent is the base. In that shape every
10
+ * tree-reading gate still has nothing to judge, and the caller uses this to
11
+ * decide which gates run.
12
+ */
13
+ export declare function headTreeEqualsBase(repoRoot: string, ref: string): boolean;
1
14
  /**
2
15
  * Why this ref cannot be a trust base, or null when it can.
3
16
  *
@@ -11,8 +24,63 @@
11
24
  * the umbrella never spawns a child at all on a base it has already decided
12
25
  * it cannot judge against, and it means the two gates give a user the same
13
26
  * answer to the same mistake.
27
+ *
28
+ * The identical-tree refusal carries ONE exception (issue #69): when HEAD is
29
+ * a merge commit and this ref is HEAD's first parent, this returns null
30
+ * rather than refusing, because that is precisely the shape GitHub's own
31
+ * merge ref takes on a pull request whose net diff is empty. See the header
32
+ * comment above and `headTreeEqualsBase` below, which is how the caller
33
+ * learns the trees matched even on this accepted path.
14
34
  */
15
35
  export declare function refuseTrustBaseRef(repoRoot: string, ref: string): string | null;
36
+ /**
37
+ * Why an explicit --trust-base cannot be honoured on a pull request, or null.
38
+ *
39
+ * Issue #58. The refusal above only refuses a ref that resolves to HEAD's own
40
+ * commit or to HEAD's own tree, which covers HEAD itself and an UNMOVED
41
+ * origin/<pr-branch>. Once the base branch has moved, origin/<pr-branch> no
42
+ * longer matches either test, so a same-repo pull request could set
43
+ * trust-base to its own branch, in its own workflow file, and have this
44
+ * package read .guardrails.yaml from the pull request after all -- at which
45
+ * point the pull request controls the whole policy, which is the one thing
46
+ * pull-request mode exists to prevent.
47
+ *
48
+ * action.yml's validate step now refuses an explicit trust-base input
49
+ * outright on a pull_request or pull_request_target event, the stronger line
50
+ * dep-guard's own base input took in 0.8.0. This function is the CLI's own
51
+ * line of defence for anyone invoking it directly in CI, bypassing that step.
52
+ *
53
+ * GITHUB_BASE_REF IS ACTIONS' OWN PULL-REQUEST SIGNAL: the base branch's
54
+ * NAME on a pull_request or pull_request_target event, and empty everywhere
55
+ * else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
56
+ * a platform that never sets it. When it is set, the given ref is accepted
57
+ * only when it resolves to the SAME COMMIT as origin/<githubBaseRef>, which
58
+ * is exactly what the composite action itself always passes
59
+ * (`--trust-base "origin/$GITHUB_BASE_REF"` in action.yml's gates step). So
60
+ * an ordinary pull-request run sees the given ref and the expected ref as the
61
+ * identical spelling and this returns null immediately, before
62
+ * refuseTrustBaseRef's own checks -- HEAD, and the equal-tree exception from
63
+ * issue #69/#73 -- ever run: this check is narrower than those and says
64
+ * nothing about HEAD or about tree equality, only about whether the given ref
65
+ * agrees with the one Actions says this run must use. A ref naming the pull
66
+ * request's own branch, or anything else that disagrees, is refused with both
67
+ * refs and both commits named.
68
+ *
69
+ * FAILS CLOSED when origin/<githubBaseRef> itself does not resolve, naming
70
+ * it: reachable on the default actions/checkout (fetch-depth: 1), which does
71
+ * not carry the base branch at all. The README already asks for
72
+ * fetch-depth: 0, and a checkout that does not carry the base branch is not a
73
+ * reason to skip the comparison.
74
+ *
75
+ * When the GIVEN ref does not resolve at all, this returns null rather than
76
+ * refusing: refuseTrustBaseRef is the function with its own sentence for an
77
+ * unresolvable ref, and repeating it here under a second name would only
78
+ * confuse which check actually fired.
79
+ *
80
+ * A no-op -- always null -- when githubBaseRef is undefined or empty, which
81
+ * is every push, schedule, workflow_dispatch, merge_group and local run.
82
+ */
83
+ export declare function refuseTrustBaseForPullRequest(repoRoot: string, ref: string, githubBaseRef: string | undefined): string | null;
16
84
  /**
17
85
  * The policy file's contents at a ref, or null when that ref carries none.
18
86
  *
@@ -40,6 +40,30 @@
40
40
  // on a pull_request event `github.sha` IS the merge commit, and what
41
41
  // GitHub publishes as the merge ref carries the head branch's tree
42
42
  // whenever the base has not moved since the fork.
43
+ //
44
+ // ONE NARROW EXCEPTION to the tree rule, added for issue #69. When a pull
45
+ // request's net diff is empty -- a value committed and then backed out in
46
+ // the same pull request -- the merge ref GitHub builds has a tree
47
+ // byte-identical to the base's, and the refusal above would stop
48
+ // secrets-history (gitleaks) from running on exactly the shape it exists
49
+ // to catch: the value is gone from the tree but still in the history
50
+ // between the base and HEAD. The discriminator is FIRST-PARENT IDENTITY,
51
+ // not ancestry: GitHub always builds the merge ref with the base branch as
52
+ // the first parent and the pull request's own head as the second, so a
53
+ // trust base that resolves to HEAD's first parent is the base the merge
54
+ // ref was actually built from, while HEAD's second parent is the pull
55
+ // request's own branch -- also an ancestor of HEAD, also carrying the
56
+ // same tree, and exactly the ref this rule must keep refusing, because
57
+ // trusting it would put the policy back inside the tree being judged. An
58
+ // ancestry check cannot tell those two apart; first-parent identity can.
59
+ // The exception applies ONLY when HEAD has two or more parents (a real
60
+ // merge commit) and the ref resolves to the first one; every other
61
+ // equal-tree shape -- a non-merge HEAD, the second parent, any other
62
+ // ancestor -- keeps refusing exactly as before. And the exception does not
63
+ // change what a tree-reading gate is told: it changes only whether the
64
+ // RUN proceeds, so the caller can still learn the trees matched
65
+ // (`headTreeEqualsBase` below) and run only the gates whose input is
66
+ // history rather than the tree.
43
67
  import { spawnSync } from 'node:child_process';
44
68
  import { realpathSync } from 'node:fs';
45
69
  import path from 'node:path';
@@ -63,6 +87,47 @@ function resolveRev(repoRoot, rev, kind) {
63
87
  const value = (child.stdout ?? '').trim();
64
88
  return value === '' ? null : value;
65
89
  }
90
+ /**
91
+ * HEAD's own parent commits, in order, or an empty list when they cannot be
92
+ * read.
93
+ *
94
+ * `git rev-list --parents -n 1 HEAD` prints one line, HEAD's own sha
95
+ * followed by each parent's, in order. The first entry is dropped here so
96
+ * this returns parents only: for an ordinary commit that is one entry, for a
97
+ * merge commit two or more, and GitHub's merge ref always puts the base
98
+ * branch first and the pull request's own head second.
99
+ */
100
+ function headParents(repoRoot) {
101
+ const child = spawnSync('git', ['rev-list', '--parents', '-n', '1', 'HEAD'], {
102
+ cwd: repoRoot,
103
+ encoding: 'utf8',
104
+ });
105
+ if (child.error !== undefined || child.status !== 0) {
106
+ return [];
107
+ }
108
+ const line = (child.stdout ?? '').trim();
109
+ if (line === '') {
110
+ return [];
111
+ }
112
+ return line.split(/\s+/).slice(1);
113
+ }
114
+ /**
115
+ * Whether HEAD's tree is byte-identical to the trust base's tree.
116
+ *
117
+ * Exported separately from `refuseTrustBaseRef` rather than folded into its
118
+ * return value, so that function's return type stays the simple `string |
119
+ * null` every other caller and test already reads. The one caller that needs
120
+ * this fact (`policyForRun` in cli.ts) calls it AFTER the refusal check has
121
+ * already passed, on the one shape that is accepted despite an identical
122
+ * tree: a merge commit whose first parent is the base. In that shape every
123
+ * tree-reading gate still has nothing to judge, and the caller uses this to
124
+ * decide which gates run.
125
+ */
126
+ export function headTreeEqualsBase(repoRoot, ref) {
127
+ const baseTree = resolveRev(repoRoot, ref, 'tree');
128
+ const headTree = resolveRev(repoRoot, 'HEAD', 'tree');
129
+ return baseTree !== null && headTree !== null && baseTree === headTree;
130
+ }
66
131
  /**
67
132
  * Why this ref cannot be a trust base, or null when it can.
68
133
  *
@@ -76,6 +141,13 @@ function resolveRev(repoRoot, rev, kind) {
76
141
  * the umbrella never spawns a child at all on a base it has already decided
77
142
  * it cannot judge against, and it means the two gates give a user the same
78
143
  * answer to the same mistake.
144
+ *
145
+ * The identical-tree refusal carries ONE exception (issue #69): when HEAD is
146
+ * a merge commit and this ref is HEAD's first parent, this returns null
147
+ * rather than refusing, because that is precisely the shape GitHub's own
148
+ * merge ref takes on a pull request whose net diff is empty. See the header
149
+ * comment above and `headTreeEqualsBase` below, which is how the caller
150
+ * learns the trees matched even on this accepted path.
79
151
  */
80
152
  export function refuseTrustBaseRef(repoRoot, ref) {
81
153
  const base = resolveRev(repoRoot, ref, 'commit');
@@ -100,6 +172,16 @@ export function refuseTrustBaseRef(repoRoot, ref) {
100
172
  const baseTree = resolveRev(repoRoot, ref, 'tree');
101
173
  const headTree = resolveRev(repoRoot, 'HEAD', 'tree');
102
174
  if (baseTree !== null && headTree !== null && baseTree === headTree) {
175
+ // THE ONE EXCEPTION: HEAD is a real merge commit (two or more parents)
176
+ // and this ref resolves to HEAD's FIRST parent, which is the base
177
+ // GitHub's merge ref was actually built from. Checked by identity against
178
+ // `base` above, never by ancestry: HEAD's SECOND parent -- the pull
179
+ // request's own branch -- is an ancestor too and carries the same tree,
180
+ // and trusting it would be exactly the hole this rule closes.
181
+ const parents = headParents(repoRoot);
182
+ if (parents.length >= 2 && parents[0] === base) {
183
+ return null;
184
+ }
103
185
  return (`refusing "${ref}" as the trust base: it is a different commit from HEAD but carries an ` +
104
186
  `identical tree (${headTree}), so the policy would come from the tree being judged and ` +
105
187
  'there would be nothing for pull-request mode to compare. A pull request merge ref looks ' +
@@ -108,6 +190,76 @@ export function refuseTrustBaseRef(repoRoot, ref) {
108
190
  }
109
191
  return null;
110
192
  }
193
+ /**
194
+ * Why an explicit --trust-base cannot be honoured on a pull request, or null.
195
+ *
196
+ * Issue #58. The refusal above only refuses a ref that resolves to HEAD's own
197
+ * commit or to HEAD's own tree, which covers HEAD itself and an UNMOVED
198
+ * origin/<pr-branch>. Once the base branch has moved, origin/<pr-branch> no
199
+ * longer matches either test, so a same-repo pull request could set
200
+ * trust-base to its own branch, in its own workflow file, and have this
201
+ * package read .guardrails.yaml from the pull request after all -- at which
202
+ * point the pull request controls the whole policy, which is the one thing
203
+ * pull-request mode exists to prevent.
204
+ *
205
+ * action.yml's validate step now refuses an explicit trust-base input
206
+ * outright on a pull_request or pull_request_target event, the stronger line
207
+ * dep-guard's own base input took in 0.8.0. This function is the CLI's own
208
+ * line of defence for anyone invoking it directly in CI, bypassing that step.
209
+ *
210
+ * GITHUB_BASE_REF IS ACTIONS' OWN PULL-REQUEST SIGNAL: the base branch's
211
+ * NAME on a pull_request or pull_request_target event, and empty everywhere
212
+ * else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
213
+ * a platform that never sets it. When it is set, the given ref is accepted
214
+ * only when it resolves to the SAME COMMIT as origin/<githubBaseRef>, which
215
+ * is exactly what the composite action itself always passes
216
+ * (`--trust-base "origin/$GITHUB_BASE_REF"` in action.yml's gates step). So
217
+ * an ordinary pull-request run sees the given ref and the expected ref as the
218
+ * identical spelling and this returns null immediately, before
219
+ * refuseTrustBaseRef's own checks -- HEAD, and the equal-tree exception from
220
+ * issue #69/#73 -- ever run: this check is narrower than those and says
221
+ * nothing about HEAD or about tree equality, only about whether the given ref
222
+ * agrees with the one Actions says this run must use. A ref naming the pull
223
+ * request's own branch, or anything else that disagrees, is refused with both
224
+ * refs and both commits named.
225
+ *
226
+ * FAILS CLOSED when origin/<githubBaseRef> itself does not resolve, naming
227
+ * it: reachable on the default actions/checkout (fetch-depth: 1), which does
228
+ * not carry the base branch at all. The README already asks for
229
+ * fetch-depth: 0, and a checkout that does not carry the base branch is not a
230
+ * reason to skip the comparison.
231
+ *
232
+ * When the GIVEN ref does not resolve at all, this returns null rather than
233
+ * refusing: refuseTrustBaseRef is the function with its own sentence for an
234
+ * unresolvable ref, and repeating it here under a second name would only
235
+ * confuse which check actually fired.
236
+ *
237
+ * A no-op -- always null -- when githubBaseRef is undefined or empty, which
238
+ * is every push, schedule, workflow_dispatch, merge_group and local run.
239
+ */
240
+ export function refuseTrustBaseForPullRequest(repoRoot, ref, githubBaseRef) {
241
+ if (githubBaseRef === undefined || githubBaseRef === '') {
242
+ return null;
243
+ }
244
+ const expectedRef = `origin/${githubBaseRef}`;
245
+ const expectedCommit = resolveRev(repoRoot, expectedRef, 'commit');
246
+ if (expectedCommit === null) {
247
+ return (`cannot verify "${ref}" as the trust base: "${expectedRef}" does not resolve to a commit ` +
248
+ 'in this repository, so there is nothing to compare it against. Nothing was checked. In ' +
249
+ 'CI, fetch the base branch (actions/checkout with fetch-depth: 0) before running the gates.');
250
+ }
251
+ const givenCommit = resolveRev(repoRoot, ref, 'commit');
252
+ if (givenCommit === null) {
253
+ return null;
254
+ }
255
+ if (givenCommit === expectedCommit) {
256
+ return null;
257
+ }
258
+ return (`refusing "${ref}" as the trust base: GITHUB_BASE_REF is set to "${githubBaseRef}", so this ` +
259
+ 'run is a pull request, and on a pull request the trust base must be the base branch and ' +
260
+ `nothing else. "${ref}" resolves to ${givenCommit}, and "${expectedRef}" resolves to ` +
261
+ `${expectedCommit}, a different commit. Pass ${expectedRef} instead. Nothing was checked.`);
262
+ }
111
263
  /**
112
264
  * The policy file's contents at a ref, or null when that ref carries none.
113
265
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.5.0",
3
+ "version": "0.7.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [
@@ -49,7 +49,8 @@
49
49
  "pretest": "pnpm build",
50
50
  "test": "NODE_OPTIONS=--experimental-vm-modules jest",
51
51
  "typecheck": "tsc -b && tsc --noEmit -p tsconfig.test.json",
52
- "lint": "pnpm check:public-hygiene",
53
- "check:public-hygiene": "node scripts/check-public-hygiene.mjs"
52
+ "lint": "pnpm check:public-hygiene && pnpm check:invariant-citations",
53
+ "check:public-hygiene": "node scripts/check-public-hygiene.mjs",
54
+ "check:invariant-citations": "node scripts/check-invariant-citations.mjs"
54
55
  }
55
56
  }