Repository navigation
Commit 295699d
chore(scripts): refuse a workflow expression naming a context its key cannot see (#27242)
Fixes #27227
Clause-②: no
Metadata-protocol: none
## 维护者速读
- 改了什么:新增仓库门禁 `scripts/check-workflow-context-availability.mjs`,拒收在
GitHub「上下文可用性」表不允许的工作流键里引用上下文的表达式(如 job 级 `env:` 里写 `runner.temp`)。
- 为什么改:这类写法会让 GitHub 整个拒收 workflow 文件、不建 run,PR
的检查列表因此「看着全绿」而门禁根本没跑;#27212 就踩过一次。
- 风险与回滚:只加一个脚本并串进已有的 `check:workflow-status-functions` 命令,不碰
workflow;误报只会让该门禁红,回滚即删脚本与 package.json 里那一段。
- 先看:`scripts/check-workflow-context-availability.mjs` 的
`CONTEXT_AVAILABILITY` 表(逐行抄自 GitHub 文档)与 `rowFor()`;其次 `package.json` 第
163 行。
- 两分钟验证:`pnpm check:workflow-status-functions`,预期四行全过,最后一行是
`check-workflow-context-availability: OK (... judged 1017 expression(s)
...)`。
- 需要你做的:无,席位落地。
## What changes
- **New gate** `scripts/check-workflow-context-availability.mjs`, with
its own `--self-test` (battery roster + floor + verdict handshake,
copied from the sibling per AGENTS.md "Writing a `--self-test`").
- **Wiring:** chained into the SAME `check:workflow-status-functions`
line in `package.json`, so the existing `Lint & Repo Gates` step runs
it. No `.github/workflows/**` edit; the PR stays off the governed
surface.
**Where it lives — option (b), a new script, and why.** The sibling's
header draws its scope deliberately narrow (job-level `if:` ×
`needs.*.outputs.*`, no skip-list) and its self-test pins that boundary.
This rule judges every key in a 34-row table, at every depth, in both
`${{ }}` and implicit-`if:` form. Folding it in would blur the sibling's
documented boundary and share one battery roster between two unrelated
verdicts. A separate file keeps each header the authority on one rule;
the shared `package.json` line keeps one CI step.
**The table is GitHub's, transcribed.** `CONTEXT_AVAILABILITY` is the
"Context availability" table from the Contexts reference, row for row.
It was read from the docs source in github/docs,
`content/actions/reference/workflows-and-actions/contexts.md`, on
2026-10-28. docs.github.com itself is outside this container's network
allow-list. The most specific matching row governs, so
`jobs.*.container.env.*` beats `jobs.*.container`. The special-function
column is encoded too, because "unless listed, a function can be used
anywhere".
**One reading differs from the card's wording.** The card says `matrix`
is allowed in job-level
`runs-on`/`env`/`timeout-minutes`/`continue-on-error` *when the job has
a `strategy.matrix`*. The table lists `matrix` for those keys with no
such condition, so the gate imposes none: it encodes the table, not a
memory of it. The table forbids `matrix` in job-level `if:` and
`strategy`, and both refuse.
## Tests
`node scripts/check-workflow-context-availability.mjs --self-test`: 53
assertions in 9 batteries, all through the real `scan()` path.
1. **The PR #27212 head `191e9d5e` shape is refused.**
`LIVE_BACKEND_DIR: ${{ runner.temp }}/live-backend` in job-level `env:`
gives exactly 1 violation. The context is `runner`, the row is
`jobs.*.env`, and the line points at the value. The annotation is one
line.
2. **The same key at step-level `env:` passes,** and the step expression
is counted as judged, not skipped.
3. **The issue's minimum grid,** `runner`/`steps`/`job`/`matrix` ×
job-level `env`/`if`/`timeout-minutes`/`runs-on`. Each of the 16 cells
is asserted against the table. 13 refuse; 3 (`matrix` in
`env`/`timeout-minutes`/`runs-on`) pass.
4. **The `matrix` exceptions** in `runs-on`, `timeout-minutes`,
`continue-on-error` and `env` pass under a `strategy.matrix`, with all
four judged. `matrix` in a job-level `if:` still refuses.
5. **Expression reading.** These are not contexts: a property after `.`,
a `'...'` literal, a `}}` inside a literal, function names, and the
literals true/false/null. The index spelling still counts, and context
names are case-insensitive. An `if:` without `${{ }}` is read as an
expression. A name that is no context is refused as unknown.
6. **Special functions.** `hashFiles()` in job-level `env:` refuses, and
in step `env:`/`if:` it passes. A status function outside an `if:`
refuses.
7. **Workflow-level rows.** `secrets` in `run-name` and `runner` in
top-level `env:` refuse. `secrets` in top-level `env:` and `jobs` in a
`workflow_call` output pass.
8. **Missing input goes red:** no directory, an empty directory, an
unparseable file, no `jobs:`, or an unterminated `${{`.
9. **The real tree:** no input problems, and more than 0 expressions
judged.
<details><summary>Teeth: one-shot mutation (not committed)</summary>
The mutation widens the `jobs.*.env` row to also list `runner`, in a
throwaway copy of the script under `scripts/` that a `trap` removes.
Proof that it landed: `grep -c "secrets, inputs, runner'"` gives 1. The
mutant `--self-test` exits 1 with 6 failures. Five are in battery 1
("the specimen is flagged once, got 0", …), and one is the grid cell
"runner.x in job-level env: expected refuse, got pass". The real
script's self-test then prints `✓ … 53 assertions`, exit 0, and `git
status` is clean.
</details>
## Acceptance notes
- **Live tree: 0 findings.** The gate scanned 30 workflow files and 78
jobs, and judged 1017 expressions. The raw `${{` count is 863, 11 of
them in comments; the rest of the 1017 are implicit job- and step-`if:`
bodies. An ad-hoc probe found no expression-bearing scalar outside a
table key in today's workflows, so the "keys the table does not name are
not judged" boundary leaves nothing unjudged on this tree.
- Not covered: whether the table changes upstream. The header names the
source path and read date, and says to change rows and their pins
together.
## Verification
All readings below are on head `73f898eb`, which is `c444d24b` with
`origin/main` merged in. Each exit code was captured before any pipe.
- `pnpm check:workflow-status-functions`: exit 0. The sibling's
self-test passes 34 assertions and its live scan is OK. This gate's
self-test passes 53 assertions, and its live scan reads `OK (scanned 30
workflow file(s), 78 job(s); judged 1017 expression(s) …)`.
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 41 commands. All 41 were run, plus 5
roster gates under `scripts/` that the derivation marks with ⛔.
- `--ran` reconciliation: `✓ dispatch-gates --ran: 41 derived famil(ies)
accounted for — 37 run, 4 NOT-MEASURED (4 DERIVED from a recorded exit
3).`
- **NOT MEASURED**, reason PREREQUISITE NOT MET (exit 3): these gates
read built `dist/`, and this diff touches no package, so no build
closure was made. CI's build lanes run them: `check:dts-closure`,
`check:dual-build-cjs-loads`, `check:lean-entry-closure`,
`check:sourcemap-no-sources-content`, and the roster gate
`check:published-readme-exports`.
- No `skills/**`, no `packages/**` and no workflow edit.
`skip-changeset`: the PR touches only repo scripts and the root
`package.json` script line, and nothing in it is published.
<details><summary>Run record (42 exit 0 · 5 exit 3)</summary>
```
node scripts/check-closing-keyword-parity.mjs :: exit 0
node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0
node scripts/check-declaration-mirrors.mjs :: exit 0
node scripts/check-declaration-mirrors.mjs --self-test :: exit 0
node scripts/check-dts-emitted.mjs --self-test :: exit 0
node scripts/check-self-test-wired.mjs :: exit 0
node scripts/check-self-test-wired.mjs --self-test :: exit 0
node scripts/check-self-test-workflow-commands.mjs :: exit 0
node scripts/check-self-test-workflow-commands.mjs --self-test :: exit 0
node scripts/check-whole-set-label-write.mjs :: exit 0
node scripts/check-whole-set-label-write.mjs --self-test :: exit 0
node scripts/ci/assert-turbo-remote-cache.mjs --self-test :: exit 0
node scripts/ci/plan-test-core-shards.mjs --self-test :: exit 0
node scripts/ci/prune-turbo-cache.mjs --self-test :: exit 0
node scripts/pm/bare-root-worklist.mjs --self-test :: exit 0
pnpm check:agent-test-spelling :: exit 0
pnpm check:bash32-floor :: exit 0
pnpm check:ci-filter-parity :: exit 0
pnpm check:cli-command-ids :: exit 0
pnpm check:cross-package-test-inputs :: exit 0
pnpm check:driver-memory-census :: exit 0
pnpm check:dts-closure :: exit 3
pnpm check:dual-build-cjs-loads :: exit 3
pnpm check:entry-guard :: exit 0
pnpm check:gitlink-declared :: exit 0
pnpm check:lean-entry-closure :: exit 3
pnpm check:manifest-repository-directory :: exit 0
pnpm check:merge-driver :: exit 0
pnpm check:nul-bytes :: exit 0
pnpm check:parse-guard :: exit 0
pnpm check:pnpm-filter-targets :: exit 0
pnpm check:pnpm-flag-spellings :: exit 0
pnpm check:ratchet-remedy-authority :: exit 0
pnpm check:refd-timer-probe :: exit 0
pnpm check:scripts-symbol-anchors :: exit 0
pnpm check:sourcemap-no-sources-content :: exit 3
pnpm check:turbo-task-graph :: exit 0
pnpm check:watch-hint-literal :: exit 0
pnpm check:workflow-status-functions :: exit 0
node scripts/check-published-list-mirrors.mjs :: exit 0
pnpm check:engine-double-contract :: exit 0
pnpm check:i18n-stale-fill :: exit 0
pnpm check:published-readme-exports :: exit 3
node scripts/check-dts-references.mjs --self-test :: exit 0
node scripts/check-nul-bytes.mjs :: exit 0
pnpm check:pm-dispatch-gates :: exit 0
node scripts/check-comment-mask-corpus.mjs :: exit 0
```
</details>
---
_Generated by [Claude
Code](https://claude.ai/code/session_01QSeKYkorXJzrG4kmSQV2Y7)_
Co-authored-by: Claude <noreply@anthropic.com>1 parent 9c12140 commit 295699d
2 files changed
Lines changed: 711 additions & 1 deletion
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
160 | 160 | | |
161 | 161 | | |
162 | 162 | | |
163 | | - | |
| 163 | + | |
164 | 164 | | |
165 | 165 | | |
166 | 166 | | |
| |||
0 commit comments