ci: gate releases on tests, build, docs sync and runnable examples (#13)

[adrianbrowning]

Part of #13. Leave #13 open until #3 settles the package name: its brief says publishing targets @gcmdev/mdcode, and this PR still publishes mdcode-ts.

Summary

The release path already existed (bumpy-release.yml: bump files open a Version Packages PR, and merging it publishes over npm OIDC). This PR adds a gates job that both release jobs need:

 plan
+  gates            # read-only token, no id-token: it runs Markdown code
+    type check → lint → build → tests → docs in sync → runnable examples
+    on failure: annotation + job summary naming the failed gate
-  version-pr       (needs: plan)
+  version-pr       (needs: plan, gates)
-  publish          (needs: plan)
+  publish          (needs: plan, gates)

The same docs checks run in pnpm check (pre-push) and the CI workflow, so drift normally fails the PR that caused it:

• pnpm docs:check runs examples/ci/check-docs-sync.mjs over README.md, packages/mdcode/README.md, examples/CLI_EXAMPLES.md, TESTING.md and the two tests/examples READMEs.
• pnpm docs:examples runs examples/ci/validate-snippets.mjs on the runnable=true blocks, extracted into packages/mdcode/.mdcode-tmp. There, import … from 'mdcode-ts' resolves to the built dist/.
• scripts/bin/mdcode puts the workspace build on PATH. pnpm links a workspace bin only if dist/ exists at install time, and CI installs before it builds. Without the shim, my machine picked up a stale global mdcode.

Package README changes needed so the gates can pass:

• I removed 96 top-level file=block-N.* attributes left over from an old extract --update-source (7708299). None of those files exist, so mdcode update failed on the README with read_failed. Nested illustrative fences are unchanged.
• I marked six examples runnable=true: the quick start, both transformers, the named imports, parse() and update().
• The parse() and update() examples were broken. Unescaped backticks inside their template literals made them a SyntaxError for anyone who copied them, and update() failed reading a file=test.spec.js that doesn't exist. I restored the escaped backticks from before 7708299 and made the transform example self-contained.

RELEASING.md covers the trigger, the gates, one-time setup (npm trusted publisher, publish environment, BUMPY_GH_TOKEN) and recovery. The package is still mdcode-ts until #3 is settled.

Evidence

• Before: node examples/ci/check-docs-sync.mjs packages/mdcode/README.md → ! could not be checked, 96 × read_failed, exit 2. Running validate-snippets on the parse()/update() examples gave SyntaxError [ERR_INVALID_TYPESCRIPT_SYNTAX].
  After: pnpm check passes: 6 document(s) in sync., 6 runnable block(s) passed.
• Drift fails the gate. Editing fibonacci.js → ✗ …/fibonacci/README.md: out of sync / line 28, pnpm docs:check exit 1.
• A broken example fails the gate: import { nope } from "mdcode-ts" → ✗ … line 1: block-1.ts … exited 1, exit 1.
• Failure report script, given a failed docs-sync step → ::error title=Release blocked::Release gate failed: docs-sync. Nothing was published.
• act -l job graph: plan (stage 0) → gates (1) → publish, version-pr (2).
• In a temp clone, an empty bump file plus an unpublished version still gives bumpy ci plan → mode: publish. That is the recovery path RELEASING.md documents.

Merge Danger

Door: two-way

Blast Radius: releases

The first push to main after merge runs the gates before opening the Version Packages PR. If a gate fails in CI and not locally (for example a Node 22 vs local Node difference), releases stop until it's fixed. Nothing is published early.

[github-actions]

The changes in this PR will be included in the next version bump.

Patch releases

• mdcode-ts 0.0.4 → 0.0.5

Bump files in this PR

• release-gates.md (view diff) (edit)

Click here if you want to add another bump file to this PR

---

This comment is maintained by bumpy.

[github-actions]

⚠️ ESLint Check Warnings

Click to see details

Style

> mdcode@0.0.1 lint:s /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:s

Scope: 2 of 3 workspace projects
packages/mdcode lint:s$ eslint --config .eslintrc.style.json "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:s: Done
packages/usage lint:s$ eslint --config .eslintrc.style.json "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:s: Done

Correctness

> mdcode@0.0.1 lint:esl /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:esl

Scope: 2 of 3 workspace projects
packages/mdcode lint:esl$ eslint "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:esl: Done
packages/usage lint:esl$ eslint "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:esl: Done

View workflow run

[github-actions]

⚠️ ESLint Check Warnings

Click to see details

Style

> mdcode@0.0.1 lint:s /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:s

Scope: 2 of 3 workspace projects
packages/mdcode lint:s$ eslint --config .eslintrc.style.json "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:s: Done
packages/usage lint:s$ eslint --config .eslintrc.style.json "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:s: Done

Correctness

> mdcode@0.0.1 lint:esl /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:esl

Scope: 2 of 3 workspace projects
packages/mdcode lint:esl$ eslint "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:esl: Done
packages/usage lint:esl$ eslint "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:esl: Done

View workflow run