@vaultcompass/conductor 0.5.0 → 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.
@@ -118,6 +118,7 @@
118
118
  // normalize.ts, which is where the omission would stop mattering if the
119
119
  // field were ever carried.
120
120
  import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
121
+ import { INTENT_WARNING } from './normalize.js';
121
122
  import { POLICY_FILE_NAME } from './policy.js';
122
123
  const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
123
124
  export const UMBRELLA_DRIVER_NAME = 'conductor';
@@ -499,6 +500,25 @@ function excludedNotifications(result) {
499
500
  details: { role: gate.role, product: gate.product },
500
501
  }));
501
502
  }
503
+ /**
504
+ * The gates skipped because the head tree equals the trust base's tree, as
505
+ * notifications (issue #69).
506
+ *
507
+ * Same discriminator as excludedNotifications just above: how much of the
508
+ * policy this run covered is a statement about the run, not about anybody's
509
+ * code, so it is a NOTE and never a result. Reachable only on the one
510
+ * accepted equal-tree shape (a merge commit whose first parent is the trust
511
+ * base; see trust-base.ts), where every enabled gate whose profile does not
512
+ * say readsHistory is recorded here instead of being spawned.
513
+ */
514
+ function treeUnchangedNotifications(result) {
515
+ return result.treeUnchanged.map((gate) => ({
516
+ id: 'conductor/tree-unchanged',
517
+ message: `The ${gate.role} gate (${gate.product}) did not run: the head tree is identical to the ` +
518
+ 'base tree, so there is no change for this gate to judge.',
519
+ details: { role: gate.role, product: gate.product },
520
+ }));
521
+ }
502
522
  /**
503
523
  * The gates that had nothing to check, as notifications.
504
524
  *
@@ -552,6 +572,36 @@ function skippedNotifications(result) {
552
572
  details: { role: gate.role, product: gate.product, reason: gate.reason },
553
573
  }));
554
574
  }
575
+ /**
576
+ * intent-guard 1.7.0's own advance-notice warnings, as notifications.
577
+ *
578
+ * A frozen contract's protected_paths or allowed_paths entry that no git
579
+ * path can ever match is a statement about that contract's own
580
+ * configuration, in the same sense skippedNotifications above already
581
+ * describes: nothing went wrong with this commit, nobody's code is at
582
+ * fault, and the statement is true of every run against this contract until
583
+ * it is edited. As a result it belongs beside no-contract and the rest, a
584
+ * notification rather than a result, so it never gains a severity, a
585
+ * fingerprint, or a place in the exit code.
586
+ *
587
+ * Read off `run.diagnostics` rather than `diagnostics`, deliberately: this
588
+ * repository's `diagnostics` field is the umbrella's OWN fixed set of ids
589
+ * (see AGENTS.md), and intent-guard/warning is not one of them. It is the
590
+ * gate's own statement, carried through unchanged, the same way
591
+ * dep-guard's online-deadline-exceeded diagnostic already prints under the
592
+ * gate in the text report; this is the SARIF half of that same channel,
593
+ * scoped to intent-guard's own warning code so a future run-diagnostic on
594
+ * another gate does not silently start appearing here too.
595
+ */
596
+ function intentWarningNotifications(result) {
597
+ return result.gates.flatMap((gate) => gate.run.diagnostics
598
+ .filter((diagnostic) => diagnostic.code === INTENT_WARNING)
599
+ .map((diagnostic) => ({
600
+ id: diagnostic.code,
601
+ message: diagnostic.message,
602
+ details: { role: gate.role, product: gate.product },
603
+ })));
604
+ }
555
605
  /**
556
606
  * The control inputs this pull request proposes to change, as notifications.
557
607
  *
@@ -810,6 +860,12 @@ export function renderSarif(result, umbrellaVersion) {
810
860
  ...(gate.intent === undefined
811
861
  ? {}
812
862
  : { contractSource: gate.intent.contractSource, baseRef: gate.intent.baseRef }),
863
+ // The gate's own run facts (issue #72: the lockfiles the umbrella
864
+ // handed osv-scanner, and dep-guard's online-lookup reporting), the
865
+ // same bag the text report renders as scalars. Carried verbatim and
866
+ // only when there is something in it, so a gate that reports none of
867
+ // this keeps the properties shape it had before.
868
+ ...(Object.keys(gate.run.details).length === 0 ? {} : { details: gate.run.details }),
813
869
  }));
814
870
  }
815
871
  // Still RESULTS, deliberately, and the asymmetry with the three above is
@@ -828,6 +884,7 @@ export function renderSarif(result, umbrellaVersion) {
828
884
  const notifications = [
829
885
  ...deferredNotifications(result),
830
886
  ...excludedNotifications(result),
887
+ ...treeUnchangedNotifications(result),
831
888
  ...skippedNotifications(result),
832
889
  ...unenforcedNotifications(result),
833
890
  ...legacyStateDirNotifications(result),
@@ -836,6 +893,7 @@ export function renderSarif(result, umbrellaVersion) {
836
893
  ...proposalNotifications(result),
837
894
  ...trustBaseWithheldNotifications(result),
838
895
  ...nodeModulesSkippedNotifications(result),
896
+ ...intentWarningNotifications(result),
839
897
  ];
840
898
  // Notifications earn the run on their own. Before this, the umbrella run
841
899
  // existed only when it had findings and a deferred gate was one; without
@@ -218,6 +218,18 @@ function skipWording(reason) {
218
218
  function excludedLines(result) {
219
219
  return result.excluded.map((gate) => ` excluded ${gate.role} ${gate.product} did not run here; --gate did not name it`);
220
220
  }
221
+ /**
222
+ * One line per gate skipped because the head tree equals the trust base's
223
+ * (issue #69).
224
+ *
225
+ * Modeled on deferredLines and excludedLines just above: nothing ran for
226
+ * these gates either, so there is no header, no exit code and no duration to
227
+ * put in a section, and the reason has to be on screen or a run in this shape
228
+ * reads exactly like a run that judged every enabled gate's tree.
229
+ */
230
+ function treeUnchangedLines(result) {
231
+ return result.treeUnchanged.map((gate) => ` tree-unchanged ${gate.role} ${gate.product} did not run: the head tree is identical to the base tree, so there is no change for this gate to judge`);
232
+ }
221
233
  /**
222
234
  * The one sentence the whole of pull-request mode has to fit into.
223
235
  *
@@ -392,25 +404,40 @@ function verdictForRun(result, advisory) {
392
404
  const blocking = enforcedGates
393
405
  .flatMap((gate) => gate.findings)
394
406
  .filter((finding) => finding.blocking).length;
395
- if (result.gates.length === 0 && result.deferred.length > 0) {
396
- // Distinct from "none is enabled" below. A policy file with everything
397
- // switched off and a stage with nothing to do at it are two different
398
- // states, and telling somebody to set enabled: true is the wrong advice
399
- // for the second one.
400
- const names = result.deferred.map((gate) => `${gate.role} at stage ${gate.stage}`).join(', ');
401
- return `verdict: exit 0, nothing ran at this stage: every enabled gate is deferred (${names}).`;
402
- }
403
- if (result.gates.length === 0 && result.skipped.length > 0) {
404
- // A third distinct state, and telling somebody to switch a gate on is
405
- // wrong advice here too: the gate IS on, it ran, and it had nothing to
406
- // check. What to do about that is NOT the same in both cases, which is
407
- // why the clause comes from the skip reason rather than being written
408
- // here: for a missing spec the fix is to write one, and for a waiver
409
- // there is nothing to fix, because a person decided it.
410
- const clauses = result.skipped
411
- .map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`)
412
- .join(', ');
413
- return `verdict: exit 0, nothing was checked: ${clauses}.`;
407
+ if (result.gates.length === 0 &&
408
+ (result.deferred.length > 0 || result.treeUnchanged.length > 0 || result.skipped.length > 0)) {
409
+ // Three distinct states can each leave result.gates empty, and a run can
410
+ // land in more than one of them at once: a stage that deferred one gate
411
+ // while another was tree-unchanged (issue #69) is a real shape, not a
412
+ // hypothetical, so this names EVERY one that applies rather than the
413
+ // first one found. Naming only "every enabled gate is deferred" when a
414
+ // tree-unchanged gate was also in the mix would be false: not every gate
415
+ // was deferred, some had nothing to judge for a different reason. All
416
+ // three are also distinct from "none is enabled" below, and each needs
417
+ // its own fix: set enabled: true is wrong for all three of them, since
418
+ // every gate named here IS enabled.
419
+ const clauses = [];
420
+ if (result.deferred.length > 0) {
421
+ // Never "every enabled gate is deferred" here: that claim is only true
422
+ // when nothing else in this branch fired, and a mix with a
423
+ // tree-unchanged or skipped gate makes it false.
424
+ const names = result.deferred.map((gate) => `${gate.role} at stage ${gate.stage}`).join(', ');
425
+ clauses.push(`deferred to a later stage (${names})`);
426
+ }
427
+ if (result.treeUnchanged.length > 0) {
428
+ // The head tree is identical to the trust base's, so there is nothing
429
+ // for these gates to judge (issue #69).
430
+ const names = result.treeUnchanged.map((gate) => gate.role).join(', ');
431
+ clauses.push(`the head tree is identical to the base tree, so there is no change for these gates to judge (${names})`);
432
+ }
433
+ if (result.skipped.length > 0) {
434
+ // What to do about this is NOT the same for every reason, which is why
435
+ // the clause comes from the skip reason rather than being written
436
+ // here: for a missing spec the fix is to write one, and for a waiver
437
+ // there is nothing to fix, because a person decided it.
438
+ clauses.push(result.skipped.map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`).join(', '));
439
+ }
440
+ return `verdict: exit 0, nothing was checked: ${clauses.join('; ')}.`;
414
441
  }
415
442
  if (result.gates.length === 0) {
416
443
  // Exit 0 with an empty report is indistinguishable from a clean run at a
@@ -552,6 +579,13 @@ function summaryLine(result) {
552
579
  .join(', ');
553
580
  parts.push(`Deferred to a later stage: ${names}.`);
554
581
  }
582
+ // Same reasoning as the deferred clause, for the equal-tree shape
583
+ // (issue #69): these gates are enabled and did not run, so a clean run in
584
+ // this shape must not read like a run that judged their tree too.
585
+ if (result.treeUnchanged.length > 0) {
586
+ const names = result.treeUnchanged.map((gate) => `${gate.role} (${gate.product})`).join(', ');
587
+ parts.push(`Tree unchanged from the trust base, skipped: ${names}.`);
588
+ }
555
589
  // Same reasoning as the deferred clause. A gate that ran and had nothing to
556
590
  // check covered none of this commit, and silence there makes a branch with
557
591
  // no spec read as a branch that passed the intent gate.
@@ -700,7 +734,12 @@ export function renderText(result, options = {}) {
700
734
  for (const gate of result.gates) {
701
735
  lines.push(...gateSection(gate));
702
736
  }
703
- const aside = [...deferredLines(result), ...skippedLines(result), ...excludedLines(result)];
737
+ const aside = [
738
+ ...deferredLines(result),
739
+ ...skippedLines(result),
740
+ ...excludedLines(result),
741
+ ...treeUnchangedLines(result),
742
+ ];
704
743
  if (aside.length > 0) {
705
744
  lines.push('', ...aside);
706
745
  }
@@ -67,6 +67,22 @@ export interface ProductProfile {
67
67
  * materialised from the base ref and the tool is run from that directory.
68
68
  */
69
69
  followsConfigExtend: boolean;
70
+ /**
71
+ * Whether this gate's INPUT is git history rather than the tree being
72
+ * judged.
73
+ *
74
+ * True only for gitleaks. Every other gate here reads the tree (vault-guard
75
+ * and dep-guard scan files, intent-guard reads a diff of paths) or a
76
+ * lockfile in it (osv-scanner), so when the head tree is byte-identical to
77
+ * the trust base's -- issue #69's shape, a value committed and then backed
78
+ * out inside one pull request -- those gates have nothing to judge that the
79
+ * base ref did not already judge, and the umbrella skips them rather than
80
+ * reporting a clean scan of a change that is not there. gitleaks' report is
81
+ * about commits between the base and HEAD, not about either tree, so it is
82
+ * the one gate an equal tree does not blind: see `decideTrustBase` and the
83
+ * equal-tree branch in `runAll` (src/run.ts).
84
+ */
85
+ readsHistory: boolean;
70
86
  }
71
87
  /**
72
88
  * The lockfiles osv-scanner is handed, matched by base name at any depth
package/dist/products.js CHANGED
@@ -57,6 +57,7 @@ function managedProfile(product) {
57
57
  stderrError: null,
58
58
  lockfileNames: null,
59
59
  followsConfigExtend: false,
60
+ readsHistory: false,
60
61
  };
61
62
  }
62
63
  const PROFILES = {
@@ -94,6 +95,11 @@ const PROFILES = {
94
95
  stderrError: /^\S+\s+ERR\s/,
95
96
  lockfileNames: null,
96
97
  followsConfigExtend: true,
98
+ // gitleaks reads git history (--log-opts), never the tree, which is
99
+ // exactly what makes it the one gate an equal-tree pull request does not
100
+ // blind (issue #69): the history between the base and HEAD still holds
101
+ // whatever was committed and backed out, even when the two trees match.
102
+ readsHistory: true,
97
103
  },
98
104
  'osv-scanner': {
99
105
  product: 'osv-scanner',
@@ -116,6 +122,9 @@ const PROFILES = {
116
122
  stderrError: null,
117
123
  lockfileNames: OSV_LOCKFILE_NAMES,
118
124
  followsConfigExtend: false,
125
+ // osv-scanner reads the tracked lockfiles it is handed, which are the
126
+ // tree being judged, not history.
127
+ readsHistory: false,
119
128
  },
120
129
  };
121
130
  export function profileFor(product) {
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
  *