mandrel-platform 0.28.0 → 0.29.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.
Files changed (3) hide show
  1. package/package.json +1 -1
  2. package/scripts/resolve-diff-range.sh +96 -0
  3. package/scripts/resolve-diff-range.test.mjs +151 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel-platform",
3
- "version": "0.28.0",
3
+ "version": "0.29.0",
4
4
  "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
5
5
  "license": "MIT",
6
6
  "repository": {
package/scripts/resolve-diff-range.sh ADDED
@@ -0,0 +1,96 @@
1
+ #!/usr/bin/env bash
2
+ # resolve-diff-range.sh — the SINGLE, event-agnostic base/head SHA derivation
3
+ # shared by every diff-scoped tier of pr-quality.yml (Story #314).
4
+ #
5
+ # WHY THIS EXISTS
6
+ # ---------------
7
+ # The diff-scoped security tiers (gitleaks secret scan + Semgrep SAST) must
8
+ # scope their scan to the commits the triggering event INTRODUCED, so a
9
+ # pre-existing finding never blocks. Each event exposes that base/head pair
10
+ # under a different context path:
11
+ #
12
+ # pull_request → github.event.pull_request.base.sha / .head.sha
13
+ # merge_group → github.event.merge_group.base_sha / .head_sha
14
+ # push → github.event.before / github.sha
15
+ #
16
+ # Under a `merge_group` (merge-queue) event `github.event.pull_request.*` is
17
+ # empty, so without this derivation the tiers degrade to a FULL-TREE scan and
18
+ # surface pre-existing findings unrelated to the queued commits — bouncing the
19
+ # whole queue batch. Deriving base/head from the merge_group context instead
20
+ # keeps the queue diff-scoped. This file is the one place that classification
21
+ # lives, so gitleaks and SAST cannot drift apart.
22
+ #
23
+ # CONTRACT
24
+ # --------
25
+ # SOURCE this file (do NOT exec it) from a `shell: bash` step, after the repo
26
+ # has been checked out with `fetch-depth: 0`. It reads the env vars below (all
27
+ # optional; an absent context evaluates to the empty string in a GitHub
28
+ # expression, so nothing here can `startup_failure` on a missing context) and
29
+ # sets three variables in the CALLER's shell:
30
+ #
31
+ # Inputs (wire each to the matching context in the step's `env:` block):
32
+ # PR_BASE_SHA = github.event.pull_request.base.sha
33
+ # PR_HEAD_SHA = github.event.pull_request.head.sha
34
+ # MERGE_GROUP_BASE_SHA = github.event.merge_group.base_sha
35
+ # MERGE_GROUP_HEAD_SHA = github.event.merge_group.head_sha
36
+ # EVENT_NAME = github.event_name
37
+ # PUSH_BEFORE_SHA = github.event.before
38
+ # PUSH_HEAD_SHA = github.sha
39
+ #
40
+ # Outputs (set on the caller's shell):
41
+ # RESOLVED_EVENT_MODE = pull_request | merge_group | push | none
42
+ # RESOLVED_BASE_SHA = <base commit> (empty when mode = none)
43
+ # RESOLVED_HEAD_SHA = <head commit> (empty when mode = none)
44
+ #
45
+ # Each consumer applies its own shaping to the raw pair: gitleaks builds a
46
+ # `base..head` git-log range (`..` already excludes base-branch drift, so no
47
+ # explicit merge-base is needed); SAST needs a single `--baseline-commit`, and
48
+ # for pull_request derives the merge base of base..head (M8: base.sha is the
49
+ # live base-branch tip and drifts past the fork point once main advances),
50
+ # while for merge_group / push the base is already the exact fork point.
51
+ #
52
+ # `mode = none` means "no ranged base is resolvable" → the consumer falls back
53
+ # to a full-tree scan. This is reached by an absent context (queue no-op, or a
54
+ # branch-creation push whose `before` is the zero SHA / an unreachable commit).
55
+
56
+ resolve_diff_range() {
57
+ local zero_sha="0000000000000000000000000000000000000000"
58
+ RESOLVED_EVENT_MODE="none"
59
+ RESOLVED_BASE_SHA=""
60
+ RESOLVED_HEAD_SHA=""
61
+
62
+ if [ -n "${PR_BASE_SHA:-}" ] && [ -n "${PR_HEAD_SHA:-}" ]; then
63
+ # pull_request — the base-branch tip / PR head. Highest precedence so a
64
+ # caller that (unusually) exposes both PR and push context stays PR-scoped.
65
+ RESOLVED_EVENT_MODE="pull_request"
66
+ RESOLVED_BASE_SHA="${PR_BASE_SHA}"
67
+ RESOLVED_HEAD_SHA="${PR_HEAD_SHA}"
68
+ elif [ -n "${MERGE_GROUP_BASE_SHA:-}" ] && [ -n "${MERGE_GROUP_HEAD_SHA:-}" ]; then
69
+ # merge_group — the merge queue built base_sha..head_sha; head_sha is the
70
+ # temporary merge commit of the queued PR(s) on top of base_sha (the exact
71
+ # fork point, so no drift to correct for).
72
+ RESOLVED_EVENT_MODE="merge_group"
73
+ RESOLVED_BASE_SHA="${MERGE_GROUP_BASE_SHA}"
74
+ RESOLVED_HEAD_SHA="${MERGE_GROUP_HEAD_SHA}"
75
+ elif [ "${EVENT_NAME:-}" = "push" ] && [ -n "${PUSH_BEFORE_SHA:-}" ] && \
76
+ [ "${PUSH_BEFORE_SHA}" != "${zero_sha}" ] && \
77
+ git cat-file -e "${PUSH_BEFORE_SHA}^{commit}" 2>/dev/null; then
78
+ # push — the commits this push added (before..sha). `before` is the zero
79
+ # SHA on a branch-creation push, and may be unreachable after a
80
+ # force-push / shallow fetch; either case falls through to `none`.
81
+ RESOLVED_EVENT_MODE="push"
82
+ RESOLVED_BASE_SHA="${PUSH_BEFORE_SHA}"
83
+ RESOLVED_HEAD_SHA="${PUSH_HEAD_SHA}"
84
+ fi
85
+ }
86
+
87
+ resolve_diff_range
88
+
89
+ # When EXECUTED directly (not sourced) — e.g. by the unit test — echo the
90
+ # resolution as `KEY=value` lines so the truth table is assertable without a
91
+ # GitHub runner. `BASH_SOURCE[0] == $0` iff the file was run, not sourced.
92
+ if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
93
+ printf 'RESOLVED_EVENT_MODE=%s\n' "${RESOLVED_EVENT_MODE}"
94
+ printf 'RESOLVED_BASE_SHA=%s\n' "${RESOLVED_BASE_SHA}"
95
+ printf 'RESOLVED_HEAD_SHA=%s\n' "${RESOLVED_HEAD_SHA}"
96
+ fi
package/scripts/resolve-diff-range.test.mjs ADDED
@@ -0,0 +1,151 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * resolve-diff-range.test.mjs — node:test suite for the single, event-agnostic
4
+ * base/head SHA derivation shared by every diff-scoped tier of pr-quality.yml
5
+ * (Story #314).
6
+ *
7
+ * The workflow's gitleaks and SAST resolvers both `source` this shell script,
8
+ * so its truth table IS the derived range each tier scans. This suite executes
9
+ * the script directly (it echoes `RESOLVED_*=…` lines when run rather than
10
+ * sourced) with per-event env fixtures and asserts the derived base/head for
11
+ * each of the three events plus the full-tree fallbacks — the "self-test
12
+ * showing the derived range for each event" half of the Story's Verify.
13
+ *
14
+ * Run: node scripts/resolve-diff-range.test.mjs (or `node --test scripts/`)
15
+ */
16
+
17
+ import assert from "node:assert/strict";
18
+ import { execFileSync } from "node:child_process";
19
+ import { fileURLToPath } from "node:url";
20
+ import { dirname, join } from "node:path";
21
+ import { test } from "node:test";
22
+
23
+ const HERE = dirname(fileURLToPath(import.meta.url));
24
+ const SCRIPT = join(HERE, "resolve-diff-range.sh");
25
+ // The repo root is a git repo, so the push-mode reachability guard
26
+ // (`git cat-file -e <before>`) can resolve a real ancestor commit.
27
+ const REPO_ROOT = join(HERE, "..");
28
+
29
+ // A real, reachable commit for exercising the push reachability guard, and its
30
+ // parent (also reachable) to stand in as the "before" SHA.
31
+ const HEAD_SHA = execFileSync("git", ["rev-parse", "HEAD"], {
32
+ cwd: REPO_ROOT,
33
+ encoding: "utf8",
34
+ }).trim();
35
+ const PARENT_SHA = execFileSync("git", ["rev-parse", "HEAD~1"], {
36
+ cwd: REPO_ROOT,
37
+ encoding: "utf8",
38
+ }).trim();
39
+
40
+ const ZERO_SHA = "0000000000000000000000000000000000000000";
41
+ // A syntactically-valid 40-hex SHA that is not an object in this repo.
42
+ const UNREACHABLE_SHA = "dead0000dead0000dead0000dead0000dead0000";
43
+
44
+ // Run the derivation with the given env and parse its `KEY=value` output.
45
+ function resolve(env) {
46
+ const out = execFileSync("bash", [SCRIPT], {
47
+ cwd: REPO_ROOT,
48
+ encoding: "utf8",
49
+ // Start from a clean slate so the ambient CI env (which may itself set
50
+ // GITHUB_* / EVENT_NAME) cannot leak into the fixture.
51
+ env: { PATH: process.env.PATH, ...env },
52
+ });
53
+ const parsed = {};
54
+ for (const line of out.split("\n")) {
55
+ const eq = line.indexOf("=");
56
+ if (eq === -1) continue;
57
+ parsed[line.slice(0, eq)] = line.slice(eq + 1);
58
+ }
59
+ return parsed;
60
+ }
61
+
62
+ test("pull_request: derives base.sha/head.sha directly", () => {
63
+ const r = resolve({
64
+ PR_BASE_SHA: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
65
+ PR_HEAD_SHA: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
66
+ EVENT_NAME: "pull_request",
67
+ });
68
+ assert.equal(r.RESOLVED_EVENT_MODE, "pull_request");
69
+ assert.equal(r.RESOLVED_BASE_SHA, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
70
+ assert.equal(r.RESOLVED_HEAD_SHA, "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");
71
+ });
72
+
73
+ test("merge_group: derives merge_group.base_sha/head_sha", () => {
74
+ const r = resolve({
75
+ MERGE_GROUP_BASE_SHA: "cccccccccccccccccccccccccccccccccccccccc",
76
+ MERGE_GROUP_HEAD_SHA: "dddddddddddddddddddddddddddddddddddddddd",
77
+ EVENT_NAME: "merge_group",
78
+ });
79
+ assert.equal(r.RESOLVED_EVENT_MODE, "merge_group");
80
+ assert.equal(r.RESOLVED_BASE_SHA, "cccccccccccccccccccccccccccccccccccccccc");
81
+ assert.equal(r.RESOLVED_HEAD_SHA, "dddddddddddddddddddddddddddddddddddddddd");
82
+ });
83
+
84
+ test("pull_request takes precedence over a co-present merge_group context", () => {
85
+ const r = resolve({
86
+ PR_BASE_SHA: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
87
+ PR_HEAD_SHA: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
88
+ MERGE_GROUP_BASE_SHA: "cccccccccccccccccccccccccccccccccccccccc",
89
+ MERGE_GROUP_HEAD_SHA: "dddddddddddddddddddddddddddddddddddddddd",
90
+ });
91
+ assert.equal(r.RESOLVED_EVENT_MODE, "pull_request");
92
+ assert.equal(r.RESOLVED_BASE_SHA, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
93
+ });
94
+
95
+ test("merge_group takes precedence over a co-present push context", () => {
96
+ const r = resolve({
97
+ MERGE_GROUP_BASE_SHA: "cccccccccccccccccccccccccccccccccccccccc",
98
+ MERGE_GROUP_HEAD_SHA: "dddddddddddddddddddddddddddddddddddddddd",
99
+ EVENT_NAME: "push",
100
+ PUSH_BEFORE_SHA: PARENT_SHA,
101
+ PUSH_HEAD_SHA: HEAD_SHA,
102
+ });
103
+ assert.equal(r.RESOLVED_EVENT_MODE, "merge_group");
104
+ assert.equal(r.RESOLVED_BASE_SHA, "cccccccccccccccccccccccccccccccccccccccc");
105
+ });
106
+
107
+ test("push: derives event.before/sha when before is a reachable commit", () => {
108
+ const r = resolve({
109
+ EVENT_NAME: "push",
110
+ PUSH_BEFORE_SHA: PARENT_SHA,
111
+ PUSH_HEAD_SHA: HEAD_SHA,
112
+ });
113
+ assert.equal(r.RESOLVED_EVENT_MODE, "push");
114
+ assert.equal(r.RESOLVED_BASE_SHA, PARENT_SHA);
115
+ assert.equal(r.RESOLVED_HEAD_SHA, HEAD_SHA);
116
+ });
117
+
118
+ test("push with zero before (branch creation) → none/full-tree", () => {
119
+ const r = resolve({
120
+ EVENT_NAME: "push",
121
+ PUSH_BEFORE_SHA: ZERO_SHA,
122
+ PUSH_HEAD_SHA: HEAD_SHA,
123
+ });
124
+ assert.equal(r.RESOLVED_EVENT_MODE, "none");
125
+ assert.equal(r.RESOLVED_BASE_SHA, "");
126
+ assert.equal(r.RESOLVED_HEAD_SHA, "");
127
+ });
128
+
129
+ test("push with an unreachable before (force-push/shallow) → none/full-tree", () => {
130
+ const r = resolve({
131
+ EVENT_NAME: "push",
132
+ PUSH_BEFORE_SHA: UNREACHABLE_SHA,
133
+ PUSH_HEAD_SHA: HEAD_SHA,
134
+ });
135
+ assert.equal(r.RESOLVED_EVENT_MODE, "none");
136
+ });
137
+
138
+ test("no event context at all → none/full-tree (never a startup_failure)", () => {
139
+ const r = resolve({});
140
+ assert.equal(r.RESOLVED_EVENT_MODE, "none");
141
+ assert.equal(r.RESOLVED_BASE_SHA, "");
142
+ assert.equal(r.RESOLVED_HEAD_SHA, "");
143
+ });
144
+
145
+ test("merge_group with only base_sha (partial context) → none", () => {
146
+ const r = resolve({
147
+ MERGE_GROUP_BASE_SHA: "cccccccccccccccccccccccccccccccccccccccc",
148
+ EVENT_NAME: "merge_group",
149
+ });
150
+ assert.equal(r.RESOLVED_EVENT_MODE, "none");
151
+ });