ci(docs): pkgs/docs のビルドに型チェックを組み込む

[shinagawa-web]

概要

pkgs/docs の build スクリプトを docusaurus build から tsc && docusaurus build に変更。

pkgs/docs には typecheck (tsc) スクリプトが存在するが、CI で呼ばれておらず、型エラーがあっても気づけない状態だった。

examples/vite (tsc && vite build) や examples/vite-react-openapi (tsc -b && vite build) は既に build 側で型チェックを行っており、それに合わせる形で修正。

きっかけ

#297 (react 18→19 bump) のレビューで、@types/react@19 により JSX.Element グローバル namespace が廃止され、pkgs/docs 内 3 箇所が型エラーになることが判明。pkgs/docs の CI では検知できていなかった。

スコープ外

• JSX.Element → ReactNode への実際の修正は chore(deps): bump the react group across 1 directory with 4 updates #297 側で対応

[shinagawa-web]

@claude
SKILLは以下を参考にしてください。
https://raw.githubusercontent.com/shokai/agent-skills/refs/heads/main/plugins/sanity-review/skills/sanity-review/SKILL.md

PRのレビューをしてください

[claude]

Claude finished @shinagawa-web's task in 2m 2s —— View job

---

PR レビュー結果

• SKILL.md (sanity-review) を取得して確認
• PR の差分と関連ファイルを確認
• pkgs/docs の CI 設定・型エラーの状況を確認
• pkgs/docs/tsconfig.json の設定を確認
• レビューコメントを投稿

---

総合判定: Approve 相当 ✅

最小限の1行変更で明確に問題を解決しており、既存の examples/* のビルドスクリプトと整合的です。バグや副作用のリスクは検出されませんでした。

---

変更内容

pkgs/docs/package.json:8

- "build": "docusaurus build",
+ "build": "tsc && docusaurus build",

概要欄の品質

• 変更前の状態 (型エラーが CI で検知できていなかった) が明示されている ✅
• 問題 → 解決の構造で書かれている ✅
• きっかけ (chore(deps): bump the react group across 1 directory with 4 updates #297 のレビューで発覚) が明記されており、意思決定の背景が追える ✅
• スコープ外 (JSX.Element → ReactNode の実修正は chore(deps): bump the react group across 1 directory with 4 updates #297 側) が明記されており、この PR で「やらない判断」の理由が明確 ✅

実装と説明の整合性

• 既存の CI (.github/workflows/all.yaml:24, .github/workflows/doc.yaml:35) は npm run build -w pkgs/docs を呼んでいるため、この変更により pull_request イベントで型チェックが必ず走るようになります。目的達成 ✅
• examples/vite (tsc && vite build) / examples/vite-react-openapi (tsc -b && vite build) と同一パターンで、リポジトリ内の一貫性が保たれています ✅

副作用チェック

• @docusaurus/tsconfig は noEmit: true を設定しているため、tsc はファイル emit を行わず型チェックのみ実行されます。.js ファイルがソースツリーに散乱するリスクはありません ✅
• tsc && docusaurus build は tsc が失敗すると docusaurus build はスキップされます。意図通り ✅
• ビルド時間は数秒増える程度で無視できるレベル ✅

---

任意の改善点 (Nits・マージブロッカーではない)

1. pkgs/docs/tsconfig.json のコメントとの整合性 (低優先度)

pkgs/docs/tsconfig.json:2 に

// This file is not used in compilation. It is here just for a nice editor experience.

というコメントがあります。この PR 後は build 時に tsc から参照されるようになります。厳密には noEmit: true なので "compilation" (emit) はしていないため、コメントの技術的な意味は今も正しいと解釈可能ですが、読み手を惑わせる可能性はあります。

Docusaurus template 由来のコメントなので、コミュニティ慣習に従うなら残す判断も妥当です。もし修正するなら、例えば "Used for type checking during build; no emit" のような一行に置き換えると意図が明確になります。

2. build スクリプト内で typecheck を再利用する選択肢 (好みの問題)

typecheck が既に定義されているため、次のようにも書けます:

"build": "npm run typecheck && docusaurus build"

意図 (「まず型チェックしてからビルド」) がより明示的になる一方、examples/* の書き方 (tsc && vite build) との一貫性は失われます。リポジトリ内一貫性を優先するなら現状のままで OK です。

---

まとめ

• CI で pkgs/docs の型エラーを継続的に検知できるようになる、意義のある改善です。
• スコープが 1 行に絞られており、副作用も無く、追加の変更提案もありません。
• そのままマージ可能と判断します。
  | branch: ci/docs-typecheck

[yokotaso]

LGTM

• CIのみのためテストが通ればOK