fix(ci): make the typecheck pass and run it on pull requests

[claude]

Requested by Elliot Hesp, Mike Hardy · Slack thread

Summary

Spin-off from #544 at the request of Mike Hardy: if there is a typecheck, and it is failing on main, then there is A) a CI problem and B) a types problem. Address both.

What was broken. bun run typecheck in packages/cli fails on main today with four errors. Nobody saw it, because that script is only ever invoked by the CLI publish workflow (on a cli-v* tag) and never by the pull-request workflow. Type breakage could land on main and only surface at release time.

Errors on main:

src/lib/docs-config.test.ts(1,40): error TS2307: Cannot find module bun:test or its corresponding type declarations.
../mdx-bundler/src/docs-ir/github-alert.ts(52,7): error TS18048: first is possibly undefined.
../mdx-bundler/src/docs-ir/github-alert.ts(56,51): error TS2345: Argument of type MdastNode | undefined is not assignable to parameter of type MdastNode.
../mdx-bundler/src/docs-ir/github-alert.ts(94,59): error TS2345: Argument of type MdastNode | undefined is not assignable to parameter of type MdastNode.

What changed — three commits:

1. packages/mdx-bundler/src/docs-ir/github-alert.ts — the three real type errors. The CLI package sets noUncheckedIndexedAccess, and it typechecks the bundler through the workspace import, so indexing into the children of a blockquote is MdastNode | undefined there even though the tsconfig of the bundler itself does not flag it. Fixed by narrowing: first?.type !== ... (matching the optional-chaining style already used elsewhere in the same file) plus an explicit guard at the stripAlertMarkerFromParagraph call site. Both indexes are already proven non-empty by their callers, so runtime behaviour is unchanged. No any, no ts-ignore, no excluded files.

2. packages/cli — types for the built-in Bun test module. The CLI typechecks its test files but had nothing declaring bun:test, so tsc skipped it as a URI-like specifier and errored. Fixed the way the repo already does it in packages/mdx-bundler: an @types/bun devDependency plus a types: [bun] entry in compilerOptions. Scoped to the one package that needed it.

3. .github/workflows/pull_request.yaml — a new typecheck job next to the existing quality (biome) and test jobs, using the same checkout / setup-bun / bun install steps and the per-package working-directory style already used in publish-cli.yml. It runs bun run typecheck for packages/mdx-bundler and packages/cli.

Scope

• app/ (hosted site, MCP, Ask AI)
• packages/cli/
• packages/mdx-bundler/
• docs/ (product documentation)
• Repo / CI / other

Type of change

• Bug fix
• New feature
• Documentation
• Refactor / chore

Test plan

Commands run locally, with exact results:

command	before	after
bun run typecheck in packages/cli	exit 2, four errors	exit 0
bun run typecheck in packages/mdx-bundler	exit 0	exit 0
bunx @biomejs/biome ci . at root	exit 0	exit 0, 252 files checked
bun test at root	118 pass / 0 fail	118 pass / 0 fail

The new CI job was verified to actually fail, not merely to run: a deliberate type error was appended to packages/cli/src/index.ts and then to packages/mdx-bundler/src/index.ts, bun run typecheck reported the error and exited 2 in each package, and both probes were removed (working tree confirmed clean before committing).

• bun run check passes locally
• Tested locally (bun dev, CLI command, or other relevant command)
• Updated docs/ (if user-facing)
• Verified on a docs.page URL or local preview (if rendering/routing changed)

Notes for reviewers

• No behaviour change. The bundler edits only add guards on paths the callers already make unreachable, and the GitHub-alert tests pass unchanged.
• bun.lock picks up @types/bun@1.3.14 for packages/cli, pinned to the same version app/ already uses, so the diff is purely additive with no unrelated resolution churn.
• Deliberately out of scope: app/ has no typecheck script and its tsconfig excludes test files. Adding a Next.js typecheck to CI would need a new script plus, most likely, a round of real fixes across the app, which is a bigger job than this spin-off. Happy to open a follow-up if you want it covered.
• Also out of scope: neither packages/mdx-bundler nor app/ typechecks its own test files, since both tsconfigs exclude them, so test-only type errors there stay invisible. Tightening that is a separate change.
• No root-level typecheck script was added. The workflow calls each package directly, matching what publish-cli.yml already does. Say the word if you would rather have a root aggregate script.

🤖 Generated with Claude Code

https://claude.ai/code/session_015ENoNC4NzabSZT7yBWy6fn

[railway-app]

🚅 Deployed to the docs.page-pr-545 environment in docs.page

Service	Status	Web	Updated
docs.page	✅ Success (View Logs)	Web	Sep 4, 2026 at 10:21 am UTC

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}