From fb35fed627ef072517121eb518d3fcbddc633d94 Mon Sep 17 00:00:00 2001 From: Peter Todd Date: Tue, 11 Aug 2026 11:24:32 +0100 Subject: [PATCH 1/3] Fix the docs typecheck script so it actually runs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `docs/package.json` had `"typecheck": "tsc"`, but the workspace catalog maps `typescript` to `npm:@typescript/typescript6`, whose bin is `tsc6`. The script had never run — it failed with `sh: tsc: command not found`, and nothing in `.github/workflows/docs.yml` invoked it, so nobody noticed. Point it at `tsc6` rather than at the TS 7 `@typescript/native` the package build scripts use: `@docusaurus/tsconfig@3.10.2` sets `baseUrl` in its own compilerOptions, and TS 7 removed the option outright (TS5102). An inherited option cannot be unset, so TS 7 here would mean dropping `extends` and inlining Docusaurus's config — no benefit for a `noEmit` check that publishes nothing, and permanent drift from upstream. `tsc6` also matches the catalog's stated split: TS 6 for tooling, `@typescript/native` for declaration emit. With the script running, two real errors surfaced: - `TS7016` on `react` — docs depends on `react` but never declared `@types/react`. - `TS2307` on `@spatialdata/vis` — the workspace packages resolve types through `dist/index.d.ts`, so the typecheck requires `pnpm build` first. Hence the ordering of the new step in the Docs workflow. `baseUrl` has to stay in `docs/tsconfig.json`: it is what anchors the inherited `@site/*` mapping to `docs/` instead of to the `@docusaurus/tsconfig` package directory. TS 6 only deprecates it, so `ignoreDeprecations: "6.0"` covers it until Docusaurus drops it upstream. Co-Authored-By: Claude Opus 5 --- .github/workflows/docs.yml | 1 + docs/package.json | 3 ++- docs/tsconfig.json | 7 ++++++- pnpm-lock.yaml | 3 +++ 4 files changed, 12 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8c10bffd..140a4564 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -34,6 +34,7 @@ jobs: - run: | pnpm install --frozen-lockfile pnpm build + pnpm --filter docs typecheck pnpm docs:build - uses: actions/upload-pages-artifact@v5 with: diff --git a/docs/package.json b/docs/package.json index 0f365672..a3d63fc7 100644 --- a/docs/package.json +++ b/docs/package.json @@ -13,7 +13,7 @@ "serve": "docusaurus serve", "write-translations": "docusaurus write-translations", "write-heading-ids": "docusaurus write-heading-ids", - "typecheck": "tsc" + "typecheck": "tsc6" }, "dependencies": { "@docusaurus/core": "3.10.2", @@ -33,6 +33,7 @@ "@docusaurus/module-type-aliases": "3.10.2", "@docusaurus/tsconfig": "3.10.2", "@docusaurus/types": "3.10.2", + "@types/react": "catalog:", "typescript": "catalog:" }, "browserslist": { diff --git a/docs/tsconfig.json b/docs/tsconfig.json index 920d7a65..a009e6f3 100644 --- a/docs/tsconfig.json +++ b/docs/tsconfig.json @@ -2,7 +2,12 @@ // This file is not used in compilation. It is here just for a nice editor experience. "extends": "@docusaurus/tsconfig", "compilerOptions": { - "baseUrl": "." + // `baseUrl` is what anchors the inherited `@site/*` path mapping to this + // directory, so it has to stay until @docusaurus/tsconfig drops its own + // `baseUrl`. TS 6 deprecates the option (TS 7 removes it outright), hence the + // opt-out below and the `tsc6` typecheck script. + "baseUrl": ".", + "ignoreDeprecations": "6.0" }, "exclude": [".docusaurus", "build"] } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c3272f67..683a1d85 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -200,6 +200,9 @@ importers: '@docusaurus/types': specifier: 3.10.2 version: 3.10.2(@swc/core@1.15.47)(@swc/html@1.15.47)(clean-css@5.3.3)(cssnano@6.1.2(postcss@8.5.26))(csso@5.0.5)(html-minifier-terser@7.2.0)(lightningcss@1.33.0)(postcss@8.5.26)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(supports-color@8.1.1) + '@types/react': + specifier: 'catalog:' + version: 19.2.18 typescript: specifier: 'catalog:' version: '@typescript/typescript6@6.0.2' From 82c1b558781b24580066fb044caff68d7795cba1 Mon Sep 17 00:00:00 2001 From: Peter Todd Date: Tue, 11 Aug 2026 11:24:39 +0100 Subject: [PATCH 2/3] Gate PRs on the docs typecheck MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Docs workflow now runs `pnpm --filter docs typecheck`, but it triggers only on push to main, so a type error in the docs site still lands and only fails on the way out to Pages. `pnpm build` and `pnpm test` both filter docs out, so no PR check compiled it at all. Add a `docs-typecheck` job to the Test workflow, which runs on pull_request. It builds the workspace packages first — docs imports `@spatialdata/vis` and the packages resolve types through `dist/index.d.ts`, so the typecheck cannot run against a bare install. Verified with actionlint 1.7.12, the same pin the Workflow Lint job uses. Co-Authored-By: Claude Opus 5 --- .github/workflows/test.yml | 39 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index ed73b9d5..eb6bd6b5 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -80,6 +80,45 @@ jobs: - name: Biome lint/format (packages/*/src) run: pnpm lint:biome + docs-typecheck: + runs-on: ubuntu-latest + permissions: + contents: read + # The docs site is excluded from `pnpm build` and `pnpm test`, so nothing on a + # PR used to compile it. Its own `typecheck` script was broken for long enough + # to go unnoticed (it called `tsc`, which the TS 6 compat package does not + # provide), and the Docs workflow that would have caught it only runs on main — + # by which point a type error is already deploying. + steps: + - name: Check out repository (docs-typecheck) + uses: actions/checkout@v7 + with: + persist-credentials: false + + - name: Setup pnpm + uses: pnpm/action-setup@v6 + with: + run_install: false + + - name: Setup Node + uses: actions/setup-node@v7 + with: + node-version: '24.14.1' + cache: 'pnpm' + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + # Required, not incidental: docs imports `@spatialdata/vis`, and the + # workspace packages resolve types through `dist/index.d.ts`, which only + # exists after their build. Without this the typecheck fails on a bare + # "Cannot find module '@spatialdata/vis'". + - name: Build packages + run: pnpm build + + - name: Typecheck docs site + run: pnpm --filter docs typecheck + test: runs-on: ubuntu-latest steps: From d95d8b459755e7df8b6e472cef3363fc8e9b1353 Mon Sep 17 00:00:00 2001 From: Peter Todd Date: Tue, 11 Aug 2026 11:28:06 +0100 Subject: [PATCH 3/3] Build the docs site on PRs too, and widen the job to `docs` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The typecheck gate does not compile the site, so broken MDX, a dead internal link, or a Docusaurus config regression still reached main and failed only on the way out to Pages — which is how the 3.10 upgrade was validated. `pnpm docs:build` reuses the `pnpm build` the job already runs, so the marginal cost is the Docusaurus build alone. It runs after the typecheck so the cheap check reports first, matching the Docs workflow's Build job — which this job is now a copy of, minus the deploy. Renamed `docs-typecheck` to `docs` accordingly. The old name never ran, so no branch protection rule can be referencing it yet. Verified with actionlint 1.7.12; both commands run clean locally. Co-Authored-By: Claude Opus 5 --- .github/workflows/test.yml | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index eb6bd6b5..6c5d128f 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -80,7 +80,7 @@ jobs: - name: Biome lint/format (packages/*/src) run: pnpm lint:biome - docs-typecheck: + docs: runs-on: ubuntu-latest permissions: contents: read @@ -88,9 +88,11 @@ jobs: # PR used to compile it. Its own `typecheck` script was broken for long enough # to go unnoticed (it called `tsc`, which the TS 6 compat package does not # provide), and the Docs workflow that would have caught it only runs on main — - # by which point a type error is already deploying. + # by which point the failure is already blocking a Pages deploy. This job is + # that workflow's Build steps minus the deploy, so the same breakage fails on + # the PR instead. steps: - - name: Check out repository (docs-typecheck) + - name: Check out repository (docs) uses: actions/checkout@v7 with: persist-credentials: false @@ -119,6 +121,12 @@ jobs: - name: Typecheck docs site run: pnpm --filter docs typecheck + # Catches what the typecheck cannot: broken MDX, dead internal links, and + # Docusaurus config/plugin regressions. Kept after the typecheck so the + # cheap check reports first. Same order as the Docs workflow's Build job. + - name: Build docs site + run: pnpm docs:build + test: runs-on: ubuntu-latest steps: