PJR-EA20 docs-site のビルドが docs/en のないリポジトリで失敗する
1. 課題内容
公開済みの @specdojo/docs-site 0.2.0 は、docs/en がないと sidebar の走査で The path to scan does not exist になり build と dev が止まる。config init は docs/ja だけを作るため、README の手順どおりに導入した利用者が最初のビルドで失敗する
2. 影響範囲
| 観点 | 影響 |
|---|---|
| スコープ | packages/docs-site/.vitepress/config.mts の sidebar の生成（makeSidebar("en")） |
| スケジュール | v0.3.0 の公開前に直す（2026-10-13、利用者の判断）。修正は @specdojo/docs-site 0.2.1 として公開する |
| コスト | config init から始めた利用者は、npx specdojo-docs-site build . と dev . が必ず失敗する。回避には空の docs/en を作る必要があり、README に記載がない |
| 品質 | 本リポジトリは docs/en を持つため、開発時の確認では表に出ない |
| 関係者 | docs-site を導入する利用者 |
3. 対応方針
| 項目 | 内容 |
|---|---|
| 原因 | config.mts が ja と en の両方について vitepress-sidebar の generateSidebar を無条件に呼ぶ。scanStartPath の docs/en が存在しないと generateSidebar が例外を投げ、設定の読み込みごと失敗する |
| 対応策 | locale のフォルダー（docs/<locale>）が workspace に存在しない場合は、その locale の sidebar の走査を行わず空として扱う。docs/ja がない場合も同じ扱いとし、どちらかの locale だけを持つリポジトリでビルドできるようにする |
| 依存事項 | なし。prj-0001:pjr-ca0s-docs-site-output-in-node-modules と同じ config.mts を変えるため、続けて実行する |
| 完了条件 | 下記の完了条件を満たす |
3.1. 完了条件
docs/enのない workspace でspecdojo-docs-site buildとdevの設定の読み込みが失敗しない。docs/jaのない workspace でも同じである。docs/enを持つ本リポジトリでは、enの sidebar がこれまでどおり生成される。- locale のフォルダーがない場合に走査を飛ばすことを確かめる unit test を
tests/packages/docs-site/に追加している。設定ファイル全体の読み込みが重い場合は、判定を関数に切り出してその関数を検証してよい。 - 本リポジトリで
npm run docs:buildが通る。 packages/docs-site/package.jsonの版は変えない（0.2.1 への版上げは公開の準備でまとめて行う）。
4. 対応結果
| 項目 | 内容 |
|---|---|
| 解決内容 | packages/docs-site/.vitepress/locale-sidebar.ts に docs/<locale> の存在を判定する shouldScanLocaleSidebar と、存在するときだけ走査する scanLocaleSidebar を追加した。config.mts の makeSidebar はこれを経由し、フォルダーがない locale の sidebar を空として扱う |
| 判定の基準 | generateSidebar は走査先を process.cwd() から解決するため、存在判定も process.cwd() を基準にした。specdojo-docs-site の起動スクリプトは workspace を cwd にして VitePress を起動する |
| 確認結果 | docs/ja だけ、docs/en だけの workspace をそれぞれ用意し、specdojo-docs-site build が設定の読み込みを含めて完了することを確かめた |
| 再発防止策 | 判定を関数に切り出し、tests/packages/docs-site/locale-sidebar.test.ts で、フォルダーがない locale を走査しないことと、ある locale はこれまでどおり走査することを検証する |
| 残課題 | なし。本リポジトリでの npm run docs:build は agent の実行環境では heap 上限で確認できなかったが、統合後に orchestrator が本体の作業場所で、deploy.yml と同じ NODE_OPTIONS=--max-old-space-size=4096 を付けて実行し、en を含めて完了することを確かめた（2026-10-13、約 1 分 54 秒）。heap を指定しない場合は以前から OOM で止まり、本件の修正とは関係しない |
| 版 | packages/docs-site/package.json の版は変えていない |
5. 関連ドキュメント
- prj-0001:pjr-cbqv-docs-site-npm-publish: docs-site の npm への公開。導入の確認で本件が見つかった。
packages/docs-site/.vitepress/config.mts、packages/docs-site/README.md