[tnunamak]

What

Fixes two failures found while verifying a dependency bump on origin/main, both reproducible on a fresh checkout:

1. pnpm --dir apps/site run verify (this repo's combined typecheck/test/lint/build command for the public documentation site under apps/site/) failed with TS2307: Cannot find module '@generated-docs/dynamic.ts'.
2. pnpm generated-artifacts:check (a script that recompiles a small set of TypeScript sources and asserts the checked-in compiled .js/.mjs output is byte-identical, so no one hand-edits generated files) failed with drift in apps/site/scripts/sync-spec-docs.mjs.

Why

Bug 1 is a stale path mapping. apps/site generates its documentation-page source (via the fumadocs-mdx library) into a directory controlled by the PDPP_SITE_SOURCE_DIR environment variable, isolated per run mode (.source-dev for pnpm dev, .source-verify for pnpm verify) so concurrent dev/verify runs cannot clobber each other's output. apps/site/next.config.mjs's webpack and Turbopack (Next.js's alternate, opt-in bundler) aliases both read that variable correctly. apps/site/tsconfig.json's paths entry for the same @generated-docs/* import alias does not; it was hardcoded to the default ./.source/* and never updated when the per-mode isolation was added. TypeScript's tsc, invoked directly in types:check, has no way to read an environment variable from paths, so it always looked in .source, which a verify run never populates. No CI workflow in this repository ran apps/site's verify or types:check, so nothing caught this.

The first fix here listed all three mode directories (.source, .source-verify, .source-dev) in paths as fallbacks, on the assumption that tsc would resolve whichever one the current run populated. That is unsound: tsc resolves the first listed directory that exists, not the one the current run generated, so a .source left behind by an unrelated next build/next dev run would mask a real type error in verify's own .source-verify output. Reproduced by seeding a valid .source, then breaking docs-source.ts's import against a freshly regenerated .source-verify: tsc --noEmit against the fallback list still exited 0. Fixed by giving verify a dedicated tsconfig.verify.json that resolves @generated-docs/* against .source-verify only, selected by a new PDPP_SITE_TSCONFIG env var. next build's own internal type-check pass also reads tsconfig.json directly, separately from the bundler aliases, so next.config.mjs now sets typescript.tsconfigPath from the same variable. The base tsconfig.json keeps a single .source path for the editor and a plain types:check. Re-ran the repro against the fix: with the same stale .source present, the per-mode tsc pass correctly fails on the broken .source-verify.

Bug 2 is real generated-artifact drift, not a tooling gap. apps/site/scripts/sync-spec-docs.mjs is compiled output; its source is sync-spec-docs.mts, and scripts/check-generated-artifacts.ts is the check that keeps them in sync. PR #366 added stale-file cleanup logic (removing a leftover .md page that an earlier revision of this script used to write, which otherwise collides with the .mdx page of the same name and fails the site build) by editing the compiled .mjs file directly, without making the matching change in the .mts source. generated-artifacts:check only runs in .github/workflows/semantic-release.yml, gated on semantic-release deciding a new version will actually publish, so it was not a required PR check and this drift shipped unnoticed. Fixed by porting the same cleanup logic into sync-spec-docs.mts and regenerating sync-spec-docs.mjs from it; the regenerated file is byte-identical to what was already committed, confirming the port is faithful.

Neither bug was caught by the CI check named "root/site spec drift" (.github/workflows/spec-check.yml, job spec-check): that job runs pnpm spec:check, which only diffs generated markdown against the root specs and never invokes tsc or generated-artifacts:check.

Fixed the remaining verify failure. ultracite check (the linter step inside apps/site's check/verify; it runs Biome, a Rust-based JS/TS linter, under the hood) failed on scripts/style-differ.mjs's import { chromium } from "playwright", flagged as an unresolved import. playwright is a real, declared dependency, and the import resolves cleanly under both TypeScript and Node at runtime. The failure is Biome's own documented resolver gap: playwright re-exports from playwright-core, an indirect (not directly declared) dependency here, which pnpm's isolated node_modules layout hides from Biome's resolver even though Node itself resolves it fine. apps/site/biome.jsonc already carries a scoped waiver for this exact upstream gap (biomejs/biome#9143, #6464) covering src/**; style-differ.mjs sits outside src/, so a second, narrowly scoped override was added for this one file. style-differ.mjs itself is unmodified: it's a real, actively used computed-style diff tool, not dead code.

Added a PR-time gate. Added .github/workflows/site-generated-docs-check.yml, path-scoped to apps/site/** the same way react-doctor.yml (this repo's existing apps/site-only PR check, a React-health regression scan) is scoped. It runs types:check in verify mode (PDPP_SITE_SOURCE_DIR=.source-verify PDPP_SITE_TSCONFIG=tsconfig.verify.json) and generated-artifacts:check, the two commands that would have caught both bugs above. It runs those two commands specifically, not the full verify script: verify also runs the test suite and a production next build, real coverage but roughly double the wall time for no extra coverage against these two bug classes.

Verification

• pnpm --dir apps/site run verify: passes end to end (exit 0), covering types:check, 250/250 tests (3 new, covering the per-mode tsconfig selection), ultracite check (0 errors, 4 pre-existing unrelated warnings), generated-artifacts:check (7 byte-identical artifacts), and next build (log confirms Using tsconfig file: tsconfig.verify.json).
• pnpm generated-artifacts:check and pnpm spec:check: both pass, unaffected.
• The new workflow's two steps, run standalone from the repo root with the same env it sets, both pass.

Not verified: whether the pre-existing scope of the playwright/ultracite resolver gap extends to other files beyond style-differ.mjs; not audited beyond the one file this PR touches.

Assisted-by: AI

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
pdpp	Ready	Preview	Sep 23, 2026 3:35pm UTC