@vaultcompass/conductor 0.4.7 → 0.6.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/resolve.js CHANGED
@@ -61,6 +61,7 @@
61
61
  // reported missing.
62
62
  import { accessSync, constants, statSync } from 'node:fs';
63
63
  import path from 'node:path';
64
+ import { profileFor } from './products.js';
64
65
  export const CANDIDATES = {
65
66
  'dep-guard': [{ name: 'dep-guard', prefix: ['scan'], versionSafe: true }],
66
67
  'vault-guard': [{ name: 'vault-guard', prefix: ['scan'], versionSafe: true }],
@@ -74,6 +75,10 @@ export const CANDIDATES = {
74
75
  { name: 'intent-guard', prefix: ['check'], versionSafe: true },
75
76
  { name: 'intent-guard-check', prefix: [], versionSafe: false },
76
77
  ],
78
+ // The two external tools. Each has one name, and both version probes
79
+ // (gitleaks version, osv-scanner --version) print and exit without scanning.
80
+ gitleaks: [{ name: 'gitleaks', prefix: ['git'], versionSafe: true }],
81
+ 'osv-scanner': [{ name: 'osv-scanner', prefix: ['scan', 'source'], versionSafe: true }],
77
82
  };
78
83
  export class ResolveError extends Error {
79
84
  constructor(message) {
@@ -162,8 +167,14 @@ export function nodeModulesCandidate(gate, repoRoot) {
162
167
  }
163
168
  /** The candidate whose --version can be asked without running anything. */
164
169
  function versionProbeFor(product, resolvedCandidate, resolvedCommand, repoRoot, pathValue, skipNodeModules) {
170
+ // How to ask is the product's (src/products.ts); whether this particular
171
+ // binary can be asked safely is the candidate's, per rule 2 above.
172
+ const spec = profileFor(product).versionProbe;
173
+ if (spec === null) {
174
+ return null;
175
+ }
165
176
  if (resolvedCandidate.versionSafe) {
166
- return { command: resolvedCommand, argv: ['--version'] };
177
+ return { command: resolvedCommand, argv: [...spec.argv] };
167
178
  }
168
179
  for (const candidate of CANDIDATES[product]) {
169
180
  if (!candidate.versionSafe) {
@@ -174,7 +185,7 @@ function versionProbeFor(product, resolvedCandidate, resolvedCommand, repoRoot,
174
185
  // head-chosen program in order to answer a question about it.
175
186
  const found = locate(candidate.name, repoRoot, pathValue, skipNodeModules);
176
187
  if (found !== null) {
177
- return { command: found.command, argv: ['--version'] };
188
+ return { command: found.command, argv: [...spec.argv] };
178
189
  }
179
190
  }
180
191
  return null;
@@ -222,8 +233,11 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
222
233
  argvPrefix: [gate.command, ...prefix],
223
234
  source: 'policy',
224
235
  candidate: candidateName,
225
- versionProbe: candidate.versionSafe
226
- ? { command: process.execPath, argv: [gate.command, '--version'] }
236
+ versionProbe: candidate.versionSafe && profileFor(gate.product).versionProbe !== null
237
+ ? {
238
+ command: process.execPath,
239
+ argv: [gate.command, ...(profileFor(gate.product).versionProbe?.argv ?? [])],
240
+ }
227
241
  : versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
228
242
  };
229
243
  }
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 = [];
@@ -248,6 +285,9 @@ export function runAll(policy, options) {
248
285
  // so a gate with no pull-request mode yet is not handed a flag it
249
286
  // would reject, and the reason it was withheld is on the outcome.
250
287
  ...(options.trustBase === undefined ? {} : { trustBase: options.trustBase.ref }),
288
+ // Where an external gate's working directory goes (its report file,
289
+ // its config from the base ref). The runner removes what it makes.
290
+ ...(options.tempRoot === undefined ? {} : { tempRoot: options.tempRoot }),
251
291
  }));
252
292
  }
253
293
  }
@@ -281,6 +321,7 @@ export function runAll(policy, options) {
281
321
  deferred,
282
322
  skipped,
283
323
  excluded,
324
+ treeUnchanged,
284
325
  findings,
285
326
  trustBase: options.trustBase ?? null,
286
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.4.7",
3
+ "version": "0.6.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
  }
@@ -18,7 +18,9 @@
18
18
  "properties": {
19
19
  "dependencies": { "$ref": "#/$defs/gate" },
20
20
  "secrets": { "$ref": "#/$defs/gate" },
21
- "intent": { "$ref": "#/$defs/gate" }
21
+ "intent": { "$ref": "#/$defs/gate" },
22
+ "secrets-history": { "$ref": "#/$defs/gate" },
23
+ "vulnerabilities": { "$ref": "#/$defs/gate" }
22
24
  }
23
25
  },
24
26
  "report": {
@@ -39,8 +41,8 @@
39
41
  "required": ["product"],
40
42
  "properties": {
41
43
  "product": {
42
- "description": "Which product currently fills this role.",
43
- "enum": ["dep-guard", "vault-guard", "intent-guard"]
44
+ "description": "Which product currently fills this role. gitleaks and osv-scanner are installed by the adopter, never by conductor.",
45
+ "enum": ["dep-guard", "vault-guard", "intent-guard", "gitleaks", "osv-scanner"]
44
46
  },
45
47
  "enabled": {
46
48
  "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.",
@@ -53,7 +55,7 @@
53
55
  "default": true
54
56
  },
55
57
  "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.",
58
+ "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, secrets-history and vulnerabilities: the intent gate carries per-task ceremony, and a history scan or a registry lookup is pull-request work. A run with no --stage runs every enabled gate whatever its stage.",
57
59
  "enum": ["commit", "push", "ci"]
58
60
  },
59
61
  "command": {
@@ -67,7 +69,7 @@
67
69
  "items": { "type": "string" }
68
70
  },
69
71
  "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.",
72
+ "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 five products do not share one severity scale.",
71
73
  "type": "object",
72
74
  "propertyNames": { "pattern": "^[a-z0-9][a-z0-9-]*$" },
73
75
  "additionalProperties": {