@futurelastic/colab-handbook 1.12.0-rc.54 → 1.12.0-rc.56

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/audit/audit.mjs CHANGED
@@ -107,6 +107,8 @@ const migrationGrant = require("../tools/lib/migration-grant.js");
107
107
  const trustHumansLib = require("../tools/lib/trust-humans.js");
108
108
  // #403: the `live-env:` key — read through the same module `colab gate-hermetic` uses.
109
109
  const hermeticLib = require("../tools/lib/hermetic.js");
110
+ // #493: the `tree-reuse:` opt-out — read through the same module `colab ship` reads citations with.
111
+ const treeGreenLib = require("../tools/lib/tree-green.js");
110
112
  // #410: the optional `gate:` block — read through the same module the skills name.
111
113
  const gateLib = require("../tools/lib/gate.js");
112
114
  // #417: CLAUDE.md as a thin shell over AGENTS.md — the @-import resolver and the tool-block table,
@@ -1350,6 +1352,17 @@ function auditRepo(target, ctx) {
1350
1352
  if (!le.valid) fail(le.reason);
1351
1353
  }
1352
1354
 
1355
+ // ---- tree-reuse (#493) ----------------------------------------------------
1356
+ // `tree-reuse: off` makes the CI templates' guard run trunk's full suite even when a green run
1357
+ // of the same workflow already passed an identical tree. tools/lib/tree-green.js parseTreeReuse
1358
+ // is the one reading. An invalid value fails: the guard reads ANY tree-reuse line as off (the
1359
+ // stricter direction), so the repo gets the full suite — but a value nobody defined is not an answer.
1360
+ {
1361
+ const tr = treeGreenLib.parseTreeReuse(cfg);
1362
+ info.treeReuse = tr.declared ? tr.value : null;
1363
+ if (!tr.valid) fail(tr.reason);
1364
+ }
1365
+
1353
1366
  // ---- gate (#410) ----------------------------------------------------------
1354
1367
  // Local = a fast smoke check, branch CI = the one authoritative gate. tools/lib/gate.js
1355
1368
  // parseGate is the one reading. An invalid block fails: the reader falls back to the local full
package/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.54"
30
+ "version": "1.12.0-rc.56"
31
31
  }
@@ -54,6 +54,27 @@ Two things to keep in a copy:
54
54
  `migrations` job checks `needs.build.result == 'success'` explicitly. Add the same pair of
55
55
  conditions to any job you add.
56
56
 
57
+ ### The same job on trunk — why a squash merge's run skips the suite (#493)
58
+
59
+ The `dedupe` job also runs on every push to a trunk ref named in `concurrency` (`main`, `dev`).
60
+ There it asks a different question, because a squash merge lands a **new sha** whose **tree**
61
+ is byte-identical to the tree its branch run passed: does this workflow have a green `push` run,
62
+ on another ref of this repo, whose commit has this exact tree? It reads `.github/project.yml` at
63
+ the pushed sha and acts only when the ref is that file's `trunk:` and no `tree-reuse:` line is
64
+ present. It confirms the candidate's tree through the git object, then skips the suite and
65
+ leaves a `tree-already-green` notice naming the run. `colab ship` and `colab trunk-ci` read that
66
+ notice back and print the run they relied on. Three things to keep in a copy:
67
+
68
+ - **It needs `contents: read`** on top of `actions: read`, to read the descriptor and the
69
+ commit objects.
70
+ - **The trunk refs in its `if:` mirror `concurrency`'s list.** On a repo whose trunk has another
71
+ name, edit both. Until you do, the guard simply never fires on trunk — nothing breaks.
72
+ - **Never put a trunk-only job behind it.** Publish, deploy and release jobs must run whatever
73
+ the guard says. Give them their own `if:` that does not read `needs.dedupe`.
74
+
75
+ Opt out with `tree-reuse: off` (`project.schema.md`) when trunk's run proves something a branch
76
+ run cannot: secrets only trunk gets, `github.ref`-conditional steps, unpinned runner images.
77
+
57
78
  ### Migration round-trip — what the Laravel job proves, and what it cannot
58
79
 
59
80
  `ci-laravel.yml`'s `migrations` job runs every migration **twice per engine**: once from
@@ -119,28 +119,76 @@ jobs:
119
119
  # Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
120
120
  # skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
121
121
  # §4, "Branch CI"). This job is the one that ends green.
122
+ #
123
+ # Already tested at this TREE? (#493) — the squash merge.
124
+ # A ship squash-merges a branch whose green run already contained the current base, so
125
+ # the trunk commit's TREE is byte-identical to the tree that branch run passed — only the
126
+ # sha is new. On a non-creating push to trunk this job therefore also asks: does THIS
127
+ # workflow have a green `push` run, on another ref of this repo, whose commit has THIS
128
+ # exact tree? It confirms the tree through the git object, never only the run listing.
129
+ # Yes → the suite is skipped and the run cites the run it relied on (a
130
+ # `tree-already-green` notice that `colab ship` / `colab trunk-ci` read back). Equal
131
+ # trees cover every committed byte, workflows and lockfiles included — NOT runner images,
132
+ # unpinned downloads, secrets or `github.ref`-conditional steps; a repo whose suite
133
+ # depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
134
+ # descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
135
+ # any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
136
+ # Never put a trunk-only job (publish, deploy, release) behind this gate.
122
137
  dedupe:
123
- name: Already tested at this sha?
124
- if: github.event_name == 'push' && github.event.created
138
+ name: Already tested at this sha or tree?
139
+ # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
140
+ if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
125
141
  runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
126
142
  permissions:
127
143
  actions: read
144
+ contents: read
128
145
  outputs:
129
146
  tested: ${{ steps.check.outputs.tested }}
147
+ cited: ${{ steps.check.outputs.cited }}
130
148
  steps:
131
- - name: Look for a green run of this workflow at this sha
149
+ - name: Look for a green run of this workflow at this sha or tree
132
150
  id: check
133
151
  env:
134
152
  GH_TOKEN: ${{ github.token }}
135
153
  REPO: ${{ github.repository }}
136
154
  RUN_ID: ${{ github.run_id }}
137
155
  SHA: ${{ github.sha }}
156
+ CREATED: ${{ github.event.created }}
157
+ REF_NAME: ${{ github.ref_name }}
138
158
  run: |
139
159
  tested=false
160
+ cited=
140
161
  if ! command -v gh >/dev/null 2>&1; then
141
162
  echo "::notice::gh is not installed on this runner — running the full suite (#418)."
142
163
  elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
143
164
  echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
165
+ elif [ "${CREATED:-}" = "false" ]; then
166
+ # A non-creating push: trunk tree mode (#493). Every branch below but one runs the suite.
167
+ if ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
168
+ echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#493)."
169
+ elif grep -Eq '^tree-reuse[[:space:]]*:' <<< "$DESC"; then
170
+ echo "::notice::tree-reuse is declared in .github/project.yml — running the full suite (#493)."
171
+ elif [ "$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)" != "$REF_NAME" ]; then
172
+ echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
173
+ elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
174
+ echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
175
+ elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
176
+ --jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null)"; then
177
+ echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
178
+ elif [ -z "$CAND" ]; then
179
+ echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
180
+ else
181
+ read -r CSHA URL BR <<< "$CAND"
182
+ if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
183
+ echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
184
+ else
185
+ tested=true
186
+ cited="$URL"
187
+ echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
188
+ echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
189
+ echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
190
+ fi
191
+ fi
144
192
  elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
145
193
  --jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
146
194
  echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
@@ -152,6 +200,7 @@ jobs:
152
200
  echo "No green run of this workflow at $SHA yet — running the full suite."
153
201
  fi
154
202
  echo "tested=$tested" >> "$GITHUB_OUTPUT"
203
+ [ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
155
204
 
156
205
  gitleaks:
157
206
  name: Secret scan (gitleaks)
@@ -84,28 +84,76 @@ jobs:
84
84
  # Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
85
85
  # skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
86
86
  # §4, "Branch CI"). This job is the one that ends green.
87
+ #
88
+ # Already tested at this TREE? (#493) — the squash merge.
89
+ # A ship squash-merges a branch whose green run already contained the current base, so
90
+ # the trunk commit's TREE is byte-identical to the tree that branch run passed — only the
91
+ # sha is new. On a non-creating push to trunk this job therefore also asks: does THIS
92
+ # workflow have a green `push` run, on another ref of this repo, whose commit has THIS
93
+ # exact tree? It confirms the tree through the git object, never only the run listing.
94
+ # Yes → the suite is skipped and the run cites the run it relied on (a
95
+ # `tree-already-green` notice that `colab ship` / `colab trunk-ci` read back). Equal
96
+ # trees cover every committed byte, workflows and lockfiles included — NOT runner images,
97
+ # unpinned downloads, secrets or `github.ref`-conditional steps; a repo whose suite
98
+ # depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
99
+ # descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
100
+ # any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
101
+ # Never put a trunk-only job (publish, deploy, release) behind this gate.
87
102
  dedupe:
88
- name: Already tested at this sha?
89
- if: github.event_name == 'push' && github.event.created
103
+ name: Already tested at this sha or tree?
104
+ # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
105
+ if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
90
106
  runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
91
107
  permissions:
92
108
  actions: read
109
+ contents: read
93
110
  outputs:
94
111
  tested: ${{ steps.check.outputs.tested }}
112
+ cited: ${{ steps.check.outputs.cited }}
95
113
  steps:
96
- - name: Look for a green run of this workflow at this sha
114
+ - name: Look for a green run of this workflow at this sha or tree
97
115
  id: check
98
116
  env:
99
117
  GH_TOKEN: ${{ github.token }}
100
118
  REPO: ${{ github.repository }}
101
119
  RUN_ID: ${{ github.run_id }}
102
120
  SHA: ${{ github.sha }}
121
+ CREATED: ${{ github.event.created }}
122
+ REF_NAME: ${{ github.ref_name }}
103
123
  run: |
104
124
  tested=false
125
+ cited=
105
126
  if ! command -v gh >/dev/null 2>&1; then
106
127
  echo "::notice::gh is not installed on this runner — running the full suite (#418)."
107
128
  elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
108
129
  echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
130
+ elif [ "${CREATED:-}" = "false" ]; then
131
+ # A non-creating push: trunk tree mode (#493). Every branch below but one runs the suite.
132
+ if ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
133
+ echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#493)."
134
+ elif grep -Eq '^tree-reuse[[:space:]]*:' <<< "$DESC"; then
135
+ echo "::notice::tree-reuse is declared in .github/project.yml — running the full suite (#493)."
136
+ elif [ "$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)" != "$REF_NAME" ]; then
137
+ echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
138
+ elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
139
+ echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
140
+ elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
141
+ --jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null)"; then
142
+ echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
143
+ elif [ -z "$CAND" ]; then
144
+ echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
145
+ else
146
+ read -r CSHA URL BR <<< "$CAND"
147
+ if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
148
+ echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
149
+ else
150
+ tested=true
151
+ cited="$URL"
152
+ echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
153
+ echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
154
+ echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
155
+ fi
156
+ fi
109
157
  elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
110
158
  --jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
111
159
  echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
@@ -117,6 +165,7 @@ jobs:
117
165
  echo "No green run of this workflow at $SHA yet — running the full suite."
118
166
  fi
119
167
  echo "tested=$tested" >> "$GITHUB_OUTPUT"
168
+ [ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
120
169
 
121
170
  gitleaks:
122
171
  name: Secret scan (gitleaks)
@@ -98,28 +98,76 @@ jobs:
98
98
  # Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
99
99
  # skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
100
100
  # §4, "Branch CI"). This job is the one that ends green.
101
+ #
102
+ # Already tested at this TREE? (#493) — the squash merge.
103
+ # A ship squash-merges a branch whose green run already contained the current base, so
104
+ # the trunk commit's TREE is byte-identical to the tree that branch run passed — only the
105
+ # sha is new. On a non-creating push to trunk this job therefore also asks: does THIS
106
+ # workflow have a green `push` run, on another ref of this repo, whose commit has THIS
107
+ # exact tree? It confirms the tree through the git object, never only the run listing.
108
+ # Yes → the suite is skipped and the run cites the run it relied on (a
109
+ # `tree-already-green` notice that `colab ship` / `colab trunk-ci` read back). Equal
110
+ # trees cover every committed byte, workflows and lockfiles included — NOT runner images,
111
+ # unpinned downloads, secrets or `github.ref`-conditional steps; a repo whose suite
112
+ # depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
113
+ # descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
114
+ # any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
115
+ # Never put a trunk-only job (publish, deploy, release) behind this gate.
101
116
  dedupe:
102
- name: Already tested at this sha?
103
- if: github.event_name == 'push' && github.event.created
117
+ name: Already tested at this sha or tree?
118
+ # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
119
+ if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
104
120
  runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
105
121
  permissions:
106
122
  actions: read
123
+ contents: read
107
124
  outputs:
108
125
  tested: ${{ steps.check.outputs.tested }}
126
+ cited: ${{ steps.check.outputs.cited }}
109
127
  steps:
110
- - name: Look for a green run of this workflow at this sha
128
+ - name: Look for a green run of this workflow at this sha or tree
111
129
  id: check
112
130
  env:
113
131
  GH_TOKEN: ${{ github.token }}
114
132
  REPO: ${{ github.repository }}
115
133
  RUN_ID: ${{ github.run_id }}
116
134
  SHA: ${{ github.sha }}
135
+ CREATED: ${{ github.event.created }}
136
+ REF_NAME: ${{ github.ref_name }}
117
137
  run: |
118
138
  tested=false
139
+ cited=
119
140
  if ! command -v gh >/dev/null 2>&1; then
120
141
  echo "::notice::gh is not installed on this runner — running the full suite (#418)."
121
142
  elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
122
143
  echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
144
+ elif [ "${CREATED:-}" = "false" ]; then
145
+ # A non-creating push: trunk tree mode (#493). Every branch below but one runs the suite.
146
+ if ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
147
+ echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#493)."
148
+ elif grep -Eq '^tree-reuse[[:space:]]*:' <<< "$DESC"; then
149
+ echo "::notice::tree-reuse is declared in .github/project.yml — running the full suite (#493)."
150
+ elif [ "$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)" != "$REF_NAME" ]; then
151
+ echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
152
+ elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
153
+ echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
154
+ elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
155
+ --jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null)"; then
156
+ echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
157
+ elif [ -z "$CAND" ]; then
158
+ echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
159
+ else
160
+ read -r CSHA URL BR <<< "$CAND"
161
+ if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
162
+ echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
163
+ else
164
+ tested=true
165
+ cited="$URL"
166
+ echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
167
+ echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
168
+ echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
169
+ fi
170
+ fi
123
171
  elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
124
172
  --jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
125
173
  echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
@@ -131,6 +179,7 @@ jobs:
131
179
  echo "No green run of this workflow at $SHA yet — running the full suite."
132
180
  fi
133
181
  echo "tested=$tested" >> "$GITHUB_OUTPUT"
182
+ [ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
134
183
 
135
184
  gitleaks:
136
185
  name: Secret scan (gitleaks)
package/tools/colab CHANGED
@@ -45,6 +45,7 @@ const trustHumans = require('./lib/trust-humans');
45
45
  const ciCure = require('./lib/ci-cure');
46
46
  const ciVerdict = require('./lib/ci-verdict');
47
47
  const baseCiVerdict = require('./lib/base-ci-verdict');
48
+ const treeGreen = require('./lib/tree-green');
48
49
  const staleBase = require('./lib/stale-base');
49
50
  const dirtyOwner = require('./lib/dirty-owner');
50
51
  const scratchDirs = require('./lib/scratch-dirs');
@@ -10467,9 +10468,43 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
10467
10468
  const sub = shipBatchTrunkSubstitute(repoAbs, trunk, run.sha);
10468
10469
  if (sub) return { run, final: true, verdict: sub };
10469
10470
  }
10471
+ if (verdict.ok && target === trunk) verdict = treeGreenVerdict(repoAbs, run, verdict);
10470
10472
  return { run, verdict, final: verdict.ok || verdict.class !== HUMAN_GATED };
10471
10473
  }
10472
10474
 
10475
+ /**
10476
+ * #493: a green trunk read whose suite was SKIPPED because the CI guard found a green run of the
10477
+ * same workflow at an identical tree — name the run it relied on. The run's `success` is already
10478
+ * the verdict (same as #418's sha skip); the citation is the audit pointer, so a citation that
10479
+ * cannot be read leaves the verdict green and says so. One thing turns it red: the cited head is
10480
+ * local and its tree provably differs from trunk's — the skip relied on a run of a DIFFERENT
10481
+ * tree, so trunk is untested (HUMAN_GATED, a person looks). An ordinary green run costs one
10482
+ * check-runs read and keeps its detail byte-identical.
10483
+ */
10484
+ function treeGreenVerdict(repoAbs, run, verdict) {
10485
+ const checks = git.ghCommitCheckRuns(repoAbs, run.sha);
10486
+ const ids = treeGreen.treeSkipCheckRuns(checks);
10487
+ if (!ids || !ids.length) return verdict;
10488
+ const cites = [];
10489
+ let unreadable = 0;
10490
+ const treeOf = (sha) => {
10491
+ const r = git.git(['rev-parse', '--verify', '--quiet', `${sha}^{tree}`], repoAbs);
10492
+ return r.ok ? r.stdout.trim() : null;
10493
+ };
10494
+ const ours = treeOf(run.sha);
10495
+ for (const id of ids) {
10496
+ const cite = treeGreen.parseCitation(git.ghCheckRunAnnotations(repoAbs, id));
10497
+ if (!cite) { unreadable++; continue; }
10498
+ const theirs = treeOf(cite.head);
10499
+ if (ours && theirs && ours !== theirs) {
10500
+ return { ok: false, class: HUMAN_GATED,
10501
+ detail: `${verdict.detail} — but the suite was SKIPPED on a tree-already-green citation (#493) of ${cite.url} (${cite.branch}@${shortSha(cite.head)}), whose tree ${theirs.slice(0, 12)} differs from trunk's ${ours.slice(0, 12)}: trunk is untested at this sha — re-run its CI, and report the guard` };
10502
+ }
10503
+ cites.push({ ...cite, proof: ours && theirs ? 'verified' : 'unverified' });
10504
+ }
10505
+ return { ...verdict, detail: verdict.detail + treeGreen.citationNote(cites, unreadable), treeGreen: cites.map((c) => c.url) };
10506
+ }
10507
+
10473
10508
  /**
10474
10509
  * The SINGLE verdict for one measured CI run (#155 fix 1) — called by BOTH `shipCiCheck` above and
10475
10510
  * `cmdCiGrantCreate`'s `trunkIsRed` below, so the two can no longer independently disagree about
@@ -13631,7 +13666,11 @@ The first output word is one verdict:
13631
13666
  Exemption doors (the cure rule, a ci-grant) are NOT applied: they let one branch past a red
13632
13667
  trunk, they do not make the trunk green, and the red still needs an owner.
13633
13668
 
13634
- --json { verdict, sha, ok, class, detail, trunk }
13669
+ A GREEN whose suite the CI guard skipped because a green run of the same workflow already
13670
+ passed an identical tree (#493) names that run in its detail ("relied on <url>"). If the cited
13671
+ head is local and its tree differs from trunk's, the read is RED: trunk is untested.
13672
+
13673
+ --json { verdict, sha, ok, class, detail, trunk[, cited: [<run url>…] on a #493 skip] }
13635
13674
  Exit 0 whenever a verdict was read (whatever it is); 2 on UNREADABLE.`;
13636
13675
 
13637
13676
  /** Map readCiVerdict's result to the closed trunk-ci vocabulary. Pure — exported for tests. */
@@ -13658,7 +13697,7 @@ function cmdTrunkCi(argv) {
13658
13697
  const verdict = trunkCiToken(r);
13659
13698
  const sha = r.run ? r.run.sha || null : null;
13660
13699
  if (opts.json) {
13661
- print(JSON.stringify({ verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail: r.verdict.detail }, null, 2));
13700
+ print(JSON.stringify({ verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail: r.verdict.detail, ...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}) }, null, 2));
13662
13701
  } else {
13663
13702
  print(`${verdict} ${trunk}${sha ? `@${shortSha(sha)}` : ''} — ${r.verdict.detail}`);
13664
13703
  }
@@ -308,7 +308,80 @@ function listShort(items) {
308
308
  * step 5 becomes the append-only block instead of the thin-shell conversion
309
309
  * (CONVENTIONS.md §9, *A fork of an upstream*)
310
310
  * upstreamAgentFiles — on a fork, the upstream's own agent workflow, named for the precedence line
311
+ * releaseRung — `releaseRungSteps()`'s result (#492): extra step-6 lines on exposure: released
311
312
  */
313
+ const releasePolicy = require('./release-policy.js');
314
+
315
+ const FINAL_TAG = /^v\d+\.\d+\.\d+$/;
316
+
317
+ /**
318
+ * #492 — on `exposure: released`, step 6 is not only CI: the release rung (CONVENTIONS.md §6) has
319
+ * to be wired at adoption too, or the repo never cuts a candidate until someone notices. Measured:
320
+ * six adopters in one fleet sweep with no `release:` block and no release workflow, several more
321
+ * with the workflow but no first final (`release cut` refuses with no final to bump from).
322
+ *
323
+ * Pure: reads the descriptor and what `io` already exposes. Returns step-6 entries (possibly
324
+ * none). Never decides a route on a human's behalf beyond §6's own derivation — the no-production
325
+ * row's choice is PROPOSED (public room -> public-tool, else rapid-app), and the text says so.
326
+ *
327
+ * `ctx`: { cfg, workflowTexts: { [file]: text }, tags: string[]|null, stackFiles: string[] }
328
+ */
329
+ function releaseRungSteps(ctx = {}) {
330
+ const cfg = ctx.cfg || {};
331
+ const def = releasePolicy.deriveDefault(cfg);
332
+ const exposure = axisAuthority.axisOfRecord(cfg).exposure;
333
+ if (exposure !== 'released') return [];
334
+ const steps = [];
335
+ const block = cfg.release && typeof cfg.release === 'object' ? cfg.release : null;
336
+
337
+ // 6a — the release: block.
338
+ if (block && block.route) {
339
+ steps.push({ n: 6, text: `Release rung: \`release.route: ${block.route}\` declared — keep it; confirm \`version-source\` (default \`tag\` where the machine cuts the tag, #484), CONVENTIONS.md §6 *Release routes*` });
340
+ } else if (def.row === 'released-tag' || def.row === 'released-manual') {
341
+ steps.push({ n: 6, text: `Release rung: add a nested \`release:\` block to .github/project.yml with \`route: deploy-tag\` and \`version-source: tag\` (block style — the descriptor reader parses no \`{ }\` flow map) — the tag deploys production (deploy: ${cfg.deploy}), so candidates are automatic and every final is a human click (CONVENTIONS.md §6 *Release routes*, #492)` });
342
+ } else if (def.row === 'released-no-production') {
343
+ const proposed = cfg.room === 'public' ? 'public-tool' : 'rapid-app';
344
+ steps.push({ n: 6, text: `Release rung: add a nested \`release:\` block to .github/project.yml with \`route: ${proposed}\` and \`version-source: tag\` (block style) — PROPOSED from room: ${cfg.room || 'undeclared'} (public CLI/handbook adopters install → public-tool; an app or tool with few installers → rapid-app; a library its consumers pin → library-fast) — confirm with the human, CONVENTIONS.md §6 *Release routes* (#492)` });
345
+ } else {
346
+ steps.push({ n: 6, text: 'Release rung: exposure: released but production/deploy match no §6 row — no route derives, a human tags; fix `deploy:`/`production:` before wiring a release workflow (CONVENTIONS.md §6, #492)' });
347
+ return steps;
348
+ }
349
+
350
+ // 6b — the release workflow.
351
+ const texts = ctx.workflowTexts || {};
352
+ const releaseWf = Object.keys(texts).find((f) => /colab release cut/.test(texts[f] || ''));
353
+ if (releaseWf) {
354
+ steps.push({ n: 6, text: `Release workflow present (.github/workflows/${releaseWf}) — check its \`HANDBOOK_REF\` names a ref the handbook carries (#480) and its \`runs-on\` is the self-hosted label on a private repo` });
355
+ } else {
356
+ steps.push({ n: 6, text: 'Copy the release workflow — `colab template release-auto`, then walk its `# EDIT:` points: `HANDBOOK_REF` (a channel or tag the handbook carries, #480), the test-suite workflow `name:`, and on a PRIVATE repo the self-hosted runner label from ci.yml on every job except `npm` (#492)' });
357
+ }
358
+
359
+ // 6c — a deploy template by stack, only where the tag deploys.
360
+ if (def.row === 'released-tag' || def.row === 'released-manual') {
361
+ const files = new Set(ctx.stackFiles || []);
362
+ const deployWf = Object.keys(texts).find((f) => /^deploy/.test(f));
363
+ const php = files.has('composer.json');
364
+ const container = ['Dockerfile', 'compose.yml', 'compose.yaml', 'docker-compose.yml', 'docker-compose.yaml'].some((f) => files.has(f));
365
+ const tpl = php ? 'deploy-xserver' : container ? 'deploy-container' : null;
366
+ if (deployWf) {
367
+ steps.push({ n: 6, text: `Deploy workflow present (.github/workflows/${deployWf}) — nothing to copy` });
368
+ } else if (tpl) {
369
+ steps.push({ n: 6, text: `Copy the deploy template for this stack — \`colab template ${tpl}\` (${php ? 'PHP: composer.json' : 'container: a Dockerfile/compose file'}) — and keep it DISARMED: leave only its \`workflow_dispatch\` trigger until the operator has set its secrets and arms the \`push: tags\` trigger (#492)` });
370
+ } else {
371
+ steps.push({ n: 6, text: 'No deploy template matches this stack (none for it under templates/) — the deploy stays the runbook\'s, by hand (#492)' });
372
+ }
373
+ }
374
+
375
+ // 6d — the first final.
376
+ const tags = ctx.tags;
377
+ if (tags === null || tags === undefined) {
378
+ steps.push({ n: 6, text: 'First final: tags could not be read — check for a `vX.Y.Z` final; `colab release cut` refuses until one exists (#492)' });
379
+ } else if (!tags.some((t) => FINAL_TAG.test(t))) {
380
+ steps.push({ n: 6, text: 'First final: none yet, and `colab release cut` refuses with no final to bump from — the first final is the operator\'s to set (e.g. `git tag -a v0.1.0 -m "v0.1.0" && git push origin v0.1.0`); an agent tags it only when told to (#492)' });
381
+ }
382
+ return steps;
383
+ }
384
+
312
385
  function remainingSteps(ctx = {}) {
313
386
  const steps = [];
314
387
  if (ctx.migrations) steps.push({ n: 2, text: migrationsStepText(ctx.migrations) });
@@ -327,6 +400,7 @@ function remainingSteps(ctx = {}) {
327
400
  }
328
401
  steps.push(
329
402
  { n: 6, text: "Make sure CI meets §7's outcome — `colab template <name>`, step 6" },
403
+ ...(ctx.releaseRung || []),
330
404
  { n: 7, text: 'Register the repo — `colab register`, step 7' },
331
405
  { n: 8, text: 'Leave existing branches alone — nothing to do, step 8' },
332
406
  { n: 9, text: 'Do not create `dev` unless genuinely Tier A or Tier C — nothing to do, step 9' },
@@ -438,6 +512,13 @@ function detect(io, extra = {}) {
438
512
  ? detectMigrationCandidates(cfg, extra.trackedFiles)
439
513
  : null;
440
514
 
515
+ // #492: on exposure: released, step 6 also wires the release rung.
516
+ const workflowTexts = {};
517
+ for (const f of workflows) workflowTexts[f] = io.readFile(`.github/workflows/${f}`) || '';
518
+ const stackFiles = ['composer.json', 'Dockerfile', 'compose.yml', 'compose.yaml', 'docker-compose.yml', 'docker-compose.yaml']
519
+ .filter((f) => io.readFile(f) !== null);
520
+ const releaseRung = releaseRungSteps({ cfg, workflowTexts, tags: io.tags ? io.tags() : null, stackFiles });
521
+
441
522
  return {
442
523
  descriptorExists: io.readFile('.github/project.yml') !== null,
443
524
  cfg,
@@ -456,7 +537,7 @@ function detect(io, extra = {}) {
456
537
  upstreamAgentFiles,
457
538
  inheritedCodeowners,
458
539
  migrations,
459
- remaining: remainingSteps({ migrations, fork, upstreamAgentFiles }),
540
+ remaining: remainingSteps({ migrations, fork, upstreamAgentFiles, releaseRung }),
460
541
  };
461
542
  }
462
543
 
@@ -1070,6 +1151,7 @@ module.exports = {
1070
1151
  deriveTier,
1071
1152
  deriveConsequences,
1072
1153
  remainingSteps,
1154
+ releaseRungSteps,
1073
1155
  detectUpstreamAgentFiles,
1074
1156
  detectMigrationCandidates,
1075
1157
  detect,
package/tools/lib/git.js CHANGED
@@ -1157,6 +1157,29 @@ function ghRunJobs(repo, runDatabaseId) {
1157
1157
  }));
1158
1158
  }
1159
1159
 
1160
+ /**
1161
+ * Every check run at one commit, flattened for the #493 tree-skip read — `[{id, name, status,
1162
+ * conclusion, suite, annotations}]` (`suite` = check-suite id = one workflow run; `annotations` =
1163
+ * output.annotations_count), or null on a gh/parse failure. One call per green trunk read, made
1164
+ * lazily by readCiVerdict; `{owner}/{repo}` is resolved by gh from the cwd's remote.
1165
+ */
1166
+ function ghCommitCheckRuns(repo, sha) {
1167
+ if (!sha) return null;
1168
+ const r = run('gh', ['api', `repos/{owner}/{repo}/commits/${sha}/check-runs?per_page=100`,
1169
+ '--jq', '[.check_runs[] | {id, name, status, conclusion, suite: .check_suite.id, annotations: .output.annotations_count}]'], { cwd: repo });
1170
+ if (!r.ok) return null;
1171
+ try { const v = JSON.parse(r.stdout); return Array.isArray(v) ? v : null; } catch (_) { return null; }
1172
+ }
1173
+
1174
+ /** One check run's annotations as `[{title, message, level}]`, or null on failure (#493). */
1175
+ function ghCheckRunAnnotations(repo, checkRunId) {
1176
+ if (checkRunId === null || checkRunId === undefined) return null;
1177
+ const r = run('gh', ['api', `repos/{owner}/{repo}/check-runs/${checkRunId}/annotations`,
1178
+ '--jq', '[.[] | {title, message, level: .annotation_level}]'], { cwd: repo });
1179
+ if (!r.ok) return null;
1180
+ try { const v = JSON.parse(r.stdout); return Array.isArray(v) ? v : null; } catch (_) { return null; }
1181
+ }
1182
+
1160
1183
  /**
1161
1184
  * Dispatch `workflowFile` on `ref` (#474) — `gh workflow run <file> --ref <ref> -f k=v…`. Returns
1162
1185
  * `{ok, withInputs, detail}`. If the call with inputs is refused (GitHub can validate inputs against
@@ -1189,6 +1212,7 @@ function ghAssignedIssues(repo) {
1189
1212
  }
1190
1213
 
1191
1214
  module.exports = {
1215
+ ghCommitCheckRuns, ghCheckRunAnnotations,
1192
1216
  run, git, repoRoot, mainRepoRoot, originUrl, remoteInfo, remoteName, remoteFor, remoteUrl, remoteProblem, _resetRemoteCache,
1193
1217
  detectTrunk, branchExists, branchRefs, existingBranchRef,
1194
1218
  claimRemote, remoteHeads,
@@ -0,0 +1,88 @@
1
+ 'use strict';
2
+ /**
3
+ * Trunk "tree already green" (#493) — the pure half of the rule, shared by `colab ship` / `colab
4
+ * trunk-ci` (tools/colab readCiVerdict) and the audit. No gh, no git, no I/O.
5
+ *
6
+ * THE RULE. A ship squash-merges a branch whose green run already contained the current base, so
7
+ * the trunk commit's tree is byte-identical to the tree that branch run passed. The CI templates'
8
+ * `dedupe` guard therefore skips the suite on a trunk push when it finds a green `push` run of the
9
+ * same workflow, on another ref of this repo, at exactly this tree — and leaves a
10
+ * `tree-already-green` notice annotation naming the run it relied on. A run in that shape (the
11
+ * guard succeeded, everything else skipped) concludes `success`, which is already the verdict;
12
+ * this module only lets the reader FIND the citation, and say so.
13
+ *
14
+ * Why read the citation from an annotation: job outputs and step summaries are not readable over
15
+ * the REST API, and a job name cannot carry a step output. An annotation is durable, shows in the
16
+ * UI, and is one call per skip-run. Why not recompute tree equality here instead: a second copy of
17
+ * the guard's matching logic in JavaScript is exactly the drift this repo keeps measuring.
18
+ */
19
+
20
+ const NOTICE_TITLE = 'tree-already-green';
21
+
22
+ /** `tree-reuse:` in project.yml. Absent = reuse on. `off` = the one legal value. */
23
+ function parseTreeReuse(doc) {
24
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, 'tree-reuse');
25
+ if (!has || doc['tree-reuse'] === null || doc['tree-reuse'] === undefined) {
26
+ return { declared: false, valid: true, off: false, value: null, reason: 'tree-reuse absent — trunk may reuse a green run of an identical tree (#493)' };
27
+ }
28
+ const v = doc['tree-reuse'];
29
+ // YAML 1.1 readers turn a bare `off` into boolean false; both spell the same intent.
30
+ if (v === 'off' || v === false) {
31
+ return { declared: true, valid: true, off: true, value: 'off', reason: 'tree-reuse: off — trunk always runs its full suite' };
32
+ }
33
+ return {
34
+ declared: true, valid: false, off: true, value: v,
35
+ reason: `tree-reuse is ${JSON.stringify(v)} — the only defined value is "off"; the CI guard reads ANY tree-reuse line as off, so trunk runs its full suite, but say what you mean`,
36
+ };
37
+ }
38
+
39
+ /**
40
+ * From a commit's check runs (`[{id, name, status, conclusion, suite, annotations}]`), the ids of
41
+ * the check runs that ARE a tree-skip: in one check suite (one workflow run), exactly one job
42
+ * succeeded, it carries at least one annotation, and every other job was skipped (at least one).
43
+ * Name-independent on purpose — adopters rename jobs. Null in, null out (a failed read is not "none").
44
+ */
45
+ function treeSkipCheckRuns(checkRuns) {
46
+ if (!Array.isArray(checkRuns)) return null;
47
+ const bySuite = new Map();
48
+ for (const c of checkRuns) {
49
+ if (!c || c.suite == null) continue;
50
+ if (!bySuite.has(c.suite)) bySuite.set(c.suite, []);
51
+ bySuite.get(c.suite).push(c);
52
+ }
53
+ const ids = [];
54
+ for (const runs of bySuite.values()) {
55
+ const ok = runs.filter((c) => c.status === 'completed' && c.conclusion === 'success');
56
+ const skipped = runs.filter((c) => c.status === 'completed' && c.conclusion === 'skipped');
57
+ if (ok.length === 1 && skipped.length >= 1 && ok.length + skipped.length === runs.length && Number(ok[0].annotations) > 0) {
58
+ ids.push(ok[0].id);
59
+ }
60
+ }
61
+ return ids;
62
+ }
63
+
64
+ /** The citation in a check run's annotations (`[{title, message}]`), or null. */
65
+ function parseCitation(annotations) {
66
+ if (!Array.isArray(annotations)) return null;
67
+ const a = annotations.find((x) => x && x.title === NOTICE_TITLE && typeof x.message === 'string');
68
+ if (!a) return null;
69
+ const m = a.message.trim().match(/^(\S+)\s+tree=([0-9a-f]+)\s+head=([0-9a-f]+)\s+branch=(\S+)$/i);
70
+ if (!m) return null;
71
+ const runId = (m[1].match(/\/runs\/(\d+)/) || [])[1] || null;
72
+ return { url: m[1], runId, tree: m[2], head: m[3], branch: m[4] };
73
+ }
74
+
75
+ /**
76
+ * The verdict suffix for a green trunk read that relied on cited runs. `cites`: [{url, branch,
77
+ * head, proof}] where proof is 'verified' | 'unverified'; `unreadable`: count of skip-runs whose
78
+ * citation could not be read. '' when there is nothing to say (an ordinary green run).
79
+ */
80
+ function citationNote(cites, unreadable = 0) {
81
+ const parts = (cites || []).map((c) =>
82
+ `relied on ${c.url} (${c.branch}@${String(c.head).slice(0, 7)}${c.proof === 'verified' ? ', tree verified locally' : ', tree not verified locally'})`);
83
+ for (let i = 0; i < unreadable; i++) parts.push('cited run unreadable');
84
+ if (!parts.length) return '';
85
+ return ` — tree already green (#493): suite skipped, ${parts.join('; ')}`;
86
+ }
87
+
88
+ module.exports = { NOTICE_TITLE, parseTreeReuse, treeSkipCheckRuns, parseCitation, citationNote };