Fix the docs typecheck script, and gate the docs site on PRs

[xinaesthete]

docs/package.json had "typecheck": "tsc", but the workspace catalog maps typescript to npm:@typescript/typescript6, whose bin is tsc6. The script had never once run — it failed with sh: tsc: command not found. Nothing in .github/workflows/docs.yml invoked it, which is why that went unnoticed.

Pre-existing; unrelated to the Docusaurus 3.10 upgrade in #139, just found next to it.

Why tsc6 and not TS 7

@docusaurus/tsconfig@3.10.2 sets baseUrl in its own compilerOptions, and TS 7 removed the option outright:

tsconfig.json(4,3): error TS5102: Option 'baseUrl' has been removed. Please remove it from your configuration.

An inherited option can't be unset, only overridden, so using @typescript/native here would mean dropping extends and inlining Docusaurus's config — a hand-copied snapshot of their target/lib/moduleResolution that silently stops tracking upstream, in exchange for nothing on a noEmit check that publishes no declarations. tsc6 also matches the catalog's stated split: TS 6 for tooling, @typescript/native for declaration emit.

I did verify TS 7 works: with the config inlined it typechecks the site with zero errors, and @site/* resolves correctly under paths-without-baseUrl. It's deliberately left for the Docusaurus v4 upgrade, where it costs nothing — upstream removed baseUrl in facebook/docusaurus#11915 (merged, v4 milestone, not in 3.x), moving the @site alias and excludes into the base config. At that point docs/tsconfig.json collapses to { "extends": "@docusaurus/tsconfig" }, the ignoreDeprecations line goes away, and the script moves to tsc with no local fork of upstream's config at any point.

Real errors the working script surfaced

• TS7016 on react — docs depends on react but never declared @types/react. Added from the catalog. (@types/react-dom turned out not to be needed; checked, left out.)
• TS2307 on @spatialdata/vis — the workspace packages resolve types through dist/index.d.ts, so the typecheck needs pnpm build first. That's why the new steps are ordered the way they are, and it is not incidental: on a bare install the check cannot run at all.

baseUrl has to stay in docs/tsconfig.json — it is what anchors the inherited @site/* mapping to docs/ rather than to the @docusaurus/tsconfig package directory. TS 6 only deprecates it, so ignoreDeprecations: "6.0" covers the gap.

Gating

The Docs workflow triggers only on push to main, so a failure there is already blocking a Pages deploy by the time anyone sees it — and pnpm build and pnpm test both filter docs out, so no PR check compiled the site at all. That is how the 3.10 upgrade got validated.

New docs job in the Test workflow, which runs on pull_request. It is the Docs workflow's Build job minus the deploy: install → pnpm build → typecheck → pnpm docs:build. The site build catches what the typecheck cannot — broken MDX, dead internal links, Docusaurus config and plugin regressions — and reuses the pnpm build already in the job, so the marginal cost is the Docusaurus build alone. Typecheck runs first so the cheap check reports first.

Verification

• pnpm --filter docs typecheck — exit 0
• pnpm docs:build — exit 0, [SUCCESS] Generated static files
• actionlint 1.7.12 on all workflow files — exit 0, same pin the Workflow Lint job uses

The one warning in the docs build output is the pre-existing web-worker critical-dependency notice, unchanged by any of this.

Note for whoever merges

If branch protection lists required checks by name, the new docs check won't be required until it's added to that set — it will run and can fail without blocking merge. That's a repo-settings change, not something in this diff.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved documentation build validation by adding type checking before site generation.
  • Added automated checks to build and verify the documentation site in CI.

• Chores

  • Updated documentation tooling for TypeScript 6 compatibility.
  • Added required React type definitions and adjusted TypeScript configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e42a5354-ad69-4b7d-ba2b-a3a6c50bfb1d

📥 Commits

Reviewing files that changed from the base of the PR and between 0a03129 and d95d8b4.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (4)

• .github/workflows/docs.yml
• .github/workflows/test.yml
• docs/package.json
• docs/tsconfig.json

---

📝 Walkthrough

Walkthrough

The PR updates the docs package for TypeScript 6 and adds docs typecheck and build validation to GitHub Actions workflows.

Changes

Documentation CI validation

Layer / File(s)	Summary
TypeScript 6 documentation setup docs/package.json, docs/tsconfig.json	The docs package uses tsc6, adds @types/react, retains baseUrl, and sets ignoreDeprecations to "6.0".
Documentation workflow checks .github/workflows/test.yml, .github/workflows/docs.yml	The workflows install and build workspace packages, typecheck the docs package, and build the documentation site.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• Taylor-CCB-Group/SpatialData.js#82: Adds the TypeScript 6 compatibility package used by the docs tooling.
• Taylor-CCB-Group/SpatialData.js#105: Adds documentation content and build fixes validated by these workflow changes.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the documentation typecheck fix and the addition of pull request validation for the docs site.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/strange-zhukovsky-fa1aec

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}