TS7.0移行: ドキュメントツール — typedoc 対応検討

[9c5s]

概要

typedoc の TypeScript compiler API (Strada) 依存と tsgo (Corsa API) 非互換への対応を検討する。

影響度: 大

背景

typedoc は TypeScript compiler API (Strada) に依存。tsgo の Corsa API 対応ロードマップなし。
現在 typedoc v0.28.18 が typescript 5.9.3 と共存して動作しているが、公式 peerDependencies の上限は要確認。

選択肢

戦略	メリット	デメリット
typedoc + TS6.0 並行維持	安定、変更不要	TS6.0 を長期維持する必要
api-extractor + api-documenter	Microsoft 製、大規模対応	学習コスト、カスタムタグ対応
Corsa API 対応 typedoc を待つ	最小変更	時期不明

現在の typedoc 利用状況

• @category タグ: 128件以上 (API カテゴリ分類に多用)
• @internal タグ: 内部 API 除外に使用
• @remarks, @example, @see タグ使用
• typedoc.json でバリデーション設定済み

チェックリスト

• typedoc の Corsa API 対応 issue 追跡
• typedoc v0.28.x の公式 peerDependencies 範囲確認 (TS 5.9/6.0 対応状況)
• api-extractor での node-tcnet 評価 (@category 等カスタムタグ互換性)
• TS 6.0 並行維持のコスト評価
• ドキュメント生成の品質比較

[coderabbitai]

Coding Plan

Summary

• typedoc の Corsa API 対応状況を GitHub Issues で追跡し、peerDependencies 互換性（現状 TS 5.9.x まで対応、6.0 未対応）を正式に文書化する
• api-extractor による代替評価を PoC ベースで実施し、@category タグ非互換（40件の書き換え必要）等の移行コストを明確化する
• 3つの戦略を短期・中期・長期の観点で比較評価し、推奨戦略を決定・文書化する
• 実際の移行実装は本チケットの範囲外とし、評価結果に基づいて別チケットを起票する

Design Choices

Design Choice 1: チケット記載のタグ使用状況と実際の乖離について

Options Considered:

1. チケット記載の数値を基準に評価を進める
2. 実際のコードベース探索結果を正として評価を進める

Chosen Option: 2

Rationale: 実際のコードベース探索結果を正とする。評価の正確性を担保するため、実データに基づいて api-extractor 互換性等を評価する。

チケットでは「@category タグ: 128件以上」「@remarks, @example, @see タグ使用」と記載されているが、コードベース探索では @category が40件、@remarks/@example/@see は0件であることが判明。

Design Choice 2: 評価の深度について

Options Considered:

1. 調査・文書化のみを行い、移行実装は別チケットで対応
2. 評価と同時に移行も実施する

Chosen Option: 1

Rationale: 本チケットでは調査・評価・推奨戦略の文書化までを範囲とし、実際の移行作業は決定後の別チケットで対応する。

本チケットは「検討」チケットであり、実際の移行実装は含まない。

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: typedoc 互換性調査とイシュー追跡設定

typedoc の Corsa API 対応状況を追跡するための情報収集と、peerDependencies の互換性を正式に文書化する。

Task 1: Task 1.1: typedoc Corsa API 対応イシュー追跡

typedoc の公式リポジトリで Corsa API / tsgo 対応に関するイシューを特定し、追跡体制を整える。

• TypeDoc GitHub リポジトリ (TypeStrong/typedoc) の Issues で "Corsa"、"tsgo"、"native"、"TypeScript 6" 等のキーワードでイシューを検索
• 関連イシューが存在しない場合は、Feature Request として新規イシューを作成することを検討
• 発見したイシューを docs/wiki/ 配下の技術ドキュメントに記録し、定期的な確認ポイントとして管理

Task 2: Task 1.2: peerDependencies 互換性の文書化

Web 検索結果と公式情報を照合し、typedoc の TypeScript バージョン対応状況を正式に文書化する。

• typedoc 0.28.17/0.28.18 の package.json から peerDependencies.typescript の正確な範囲を確認（Web 検索では 5.9.x まで対応、6.0 は未対応と判明）
• TypeScript 6.0 RC の API 互換性に関する Microsoft 公式発表との整合性を確認
• 現状の動作確認: npm ls typescript typedoc で実際のバージョン解決状況を記録
• 互換性マトリクスを docs/wiki/ に作成

🤖 Prompt for AI agents

フェーズ1では、typedoc の Corsa API 対応状況の調査と peerDependencies 互換性情報の文書化を行う。

**Task 1.1: typedoc Corsa API 対応イシュー追跡**
- TypeDoc GitHub リポジトリ (TypeStrong/typedoc) の Issues を
"Corsa"、"tsgo"、"native"、"TypeScript 6" 等のキーワードで検索し、関連イシューを特定する
- 関連イシューが存在しない場合は、Feature Request として新規イシューの作成を検討する
- 発見したイシューを `docs/wiki/` 配下の技術ドキュメントに記録し、定期的な確認ポイントとして管理できるよう文書化する

**Task 1.2: peerDependencies 互換性の文書化**
- typedoc 0.28.17/0.28.18 の `peerDependencies.typescript` の正確なバージョン範囲を確認する（5.9.x
まで対応、6.0 は未対応）
- TypeScript 6.0 RC の API 互換性に関する Microsoft 公式発表との整合性を確認する
- `npm ls typescript typedoc` を実行し、実際のバージョン解決状況を記録する
- 上記の情報をまとめた互換性マトリクスを `docs/wiki/` に作成・配置する

Phase 2: api-extractor 代替評価

Microsoft 製 api-extractor + api-documenter の導入可能性を実際にテストし、node-tcnet プロジェクトとの互換性を評価する。

Task 1: Task 2.1: api-extractor 環境構築とPoC実行

api-extractor を一時的に導入し、現在のコードベースでドキュメント生成を試行する。

• devDependencies に @microsoft/api-extractor と @microsoft/api-documenter を追加（評価用ブランチで実施）
• プロジェクトルートに api-extractor.json 設定ファイルを作成
• src/index.ts をエントリーポイントとして API レポート生成を実行
• ビルド済み .d.ts ファイルに対して api-extractor を実行し、エラー・警告を記録

Task 2: Task 2.2: タグ互換性と出力品質の評価

api-extractor/api-documenter の出力と現行 typedoc 出力を比較し、互換性と品質を評価する。

• @category タグの扱い: api-extractor は @category を標準サポートしないため、代替手段（@packageDocumentation、TSDoc @remarks 等）での分類方法を調査
• @internal タグの扱い: api-extractor の @internal サポート状況と stripInternal 連携を確認
• 生成されたドキュメントの構造・ナビゲーション・検索性を typedoc 出力と比較
• 移行コスト見積もり: 40件の @category タグ書き換え工数、CI/CD 修正工数を概算

🤖 Prompt for AI agents

フェーズ2では、api-extractor を評価用ブランチに導入し、現行コードベースでの動作確認と出力品質の比較評価を行う。

**Task 2.1: api-extractor 環境構築とPoC実行**
- 評価用ブランチを作成し、devDependencies に `@microsoft/api-extractor` と
`@microsoft/api-documenter` を追加する
- プロジェクトルートに `api-extractor.json` 設定ファイルを作成する
- `src/index.ts` をエントリーポイントとして設定し、API レポート生成を実行する
- ビルド済み `.d.ts` ファイルに対して api-extractor を実行し、発生するエラー・警告を記録する

**Task 2.2: タグ互換性と出力品質の評価**
- `@category` タグ（40件）について、api-extractor が標準サポートしないことを確認し、`@packageDocumentation`
や TSDoc `@remarks` 等の代替手段での分類方法を調査する
- `@internal` タグ（4件）について、api-extractor の `@internal` サポート状況と `stripInternal`
連携を確認する
- api-documenter で生成したドキュメントの構造・ナビゲーション・検索性を現行の typedoc 出力と比較する
- 40件の `@category` タグ書き換え工数および CI/CD 修正工数を概算し、移行コストを見積もる

Phase 3: 戦略評価と推奨決定

収集した情報を総合し、プロジェクトに最適な戦略を決定・文書化する。

Task 1: Task 3.1: TS 6.0 並行維持コスト分析

typedoc + TS 6.0 並行維持戦略のコストとリスクを分析する。

• TypeScript 6.0 を tsgo と並行してプロジェクトに維持する場合の構成案を検討
• ビルドツール（tsup）、テストツール（vitest）、リンター（typescript-eslint）の TS 6.0 対応状況を確認
• CI/CD での並行ビルド（本番は tsgo、ドキュメントは TS 6.0）の実現可能性を評価
• 長期的な保守負担（セキュリティパッチ、依存関係更新）を概算

Task 2: Task 3.2: 推奨戦略の決定と文書化

すべての評価結果を統合し、推奨戦略を決定・文書化する。

• 3つの戦略（typedoc + TS6.0 並行維持、api-extractor 移行、Corsa 対応 typedoc 待ち）の比較表を作成
• 短期（〜6ヶ月）、中期（6ヶ月〜1年）、長期（1年〜）のロードマップ案を策定
• 推奨戦略とその根拠を docs/wiki/ に文書化
• 必要に応じて後続の実装チケットを作成するための要件を整理

Task 3: Task 3.3: プロジェクトドキュメント更新

評価結果と決定事項をプロジェクトドキュメントに反映する。

• docs/wiki/ 配下に TS 7.0 移行計画ドキュメントを作成または更新
• README.MD の「ドキュメント」セクションに現状の制約・今後の計画を追記（必要な場合）
• 追跡が必要なイシュー・リンクを一元管理するセクションを設置

🤖 Prompt for AI agents

フェーズ3では、フェーズ1・2で収集した情報を統合して戦略を比較評価し、推奨戦略の決定とプロジェクトドキュメントへの反映を行う。

**Task 3.1: TS 6.0 並行維持コスト分析**
- TypeScript 6.0 を tsgo と並行してプロジェクトに維持する場合の構成案を検討する
- ビルドツール（tsup）、テストツール（vitest）、リンター（typescript-eslint）の TS 6.0 対応状況を確認する
- CI/CD での並行ビルド（本番は tsgo、ドキュメントは TS 6.0）の実現可能性を評価する
- 長期的な保守負担（セキュリティパッチ、依存関係更新）を概算する

**Task 3.2: 推奨戦略の決定と文書化**
- 以下3つの戦略の比較表を作成する:
  1. typedoc + TS6.0 並行維持
  2. api-extractor 移行
  3. Corsa 対応 typedoc 待ち
- 短期（〜6ヶ月）、中期（6ヶ月〜1年）、長期（1年〜）のロードマップ案を策定する
- 推奨戦略とその根拠を `docs/wiki/` に文書化する
- 後続の実装チケット作成に必要な要件を整理する

**Task 3.3: プロジェクトドキュメント更新**
- `docs/wiki/` 配下に TS 7.0 移行計画ドキュメントを作成または更新する
- 必要に応じて `README.MD` の「ドキュメント」セクションに現状の制約・今後の計画を追記する
- 追跡が必要なイシュー・リンクを一元管理するセクションを設置する

Research

本プロジェクトは TypeScript 5.9.3 + typedoc 0.28.18 でAPIドキュメントを自動生成しており、docs-dist/ に出力後 GitHub Pages へデプロイする CI/CD が整備済み。ソースコード全体で @category タグが40件、@internal タグが4件使用されている（チケット記載の128件は過大評価の可能性）。@remarks、@example、@see タグは実際には使用されていない。typedoc.json でバリデーション設定が有効化されており、ビルドエラーは CI でブロックされる。

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

フェーズ1では、typedoc の Corsa API 対応状況の調査と peerDependencies 互換性情報の文書化を行う。

**Task 1.1: typedoc Corsa API 対応イシュー追跡**
- TypeDoc GitHub リポジトリ (TypeStrong/typedoc) の Issues を
"Corsa"、"tsgo"、"native"、"TypeScript 6" 等のキーワードで検索し、関連イシューを特定する
- 関連イシューが存在しない場合は、Feature Request として新規イシューの作成を検討する
- 発見したイシューを `docs/wiki/` 配下の技術ドキュメントに記録し、定期的な確認ポイントとして管理できるよう文書化する

**Task 1.2: peerDependencies 互換性の文書化**
- typedoc 0.28.17/0.28.18 の `peerDependencies.typescript` の正確なバージョン範囲を確認する（5.9.x
まで対応、6.0 は未対応）
- TypeScript 6.0 RC の API 互換性に関する Microsoft 公式発表との整合性を確認する
- `npm ls typescript typedoc` を実行し、実際のバージョン解決状況を記録する
- 上記の情報をまとめた互換性マトリクスを `docs/wiki/` に作成・配置する
===============================================================================

Task: 2

フェーズ2では、api-extractor を評価用ブランチに導入し、現行コードベースでの動作確認と出力品質の比較評価を行う。

**Task 2.1: api-extractor 環境構築とPoC実行**
- 評価用ブランチを作成し、devDependencies に `@microsoft/api-extractor` と
`@microsoft/api-documenter` を追加する
- プロジェクトルートに `api-extractor.json` 設定ファイルを作成する
- `src/index.ts` をエントリーポイントとして設定し、API レポート生成を実行する
- ビルド済み `.d.ts` ファイルに対して api-extractor を実行し、発生するエラー・警告を記録する

**Task 2.2: タグ互換性と出力品質の評価**
- `@category` タグ（40件）について、api-extractor が標準サポートしないことを確認し、`@packageDocumentation`
や TSDoc `@remarks` 等の代替手段での分類方法を調査する
- `@internal` タグ（4件）について、api-extractor の `@internal` サポート状況と `stripInternal`
連携を確認する
- api-documenter で生成したドキュメントの構造・ナビゲーション・検索性を現行の typedoc 出力と比較する
- 40件の `@category` タグ書き換え工数および CI/CD 修正工数を概算し、移行コストを見積もる
===============================================================================

Task: 3

フェーズ3では、フェーズ1・2で収集した情報を統合して戦略を比較評価し、推奨戦略の決定とプロジェクトドキュメントへの反映を行う。

**Task 3.1: TS 6.0 並行維持コスト分析**
- TypeScript 6.0 を tsgo と並行してプロジェクトに維持する場合の構成案を検討する
- ビルドツール（tsup）、テストツール（vitest）、リンター（typescript-eslint）の TS 6.0 対応状況を確認する
- CI/CD での並行ビルド（本番は tsgo、ドキュメントは TS 6.0）の実現可能性を評価する
- 長期的な保守負担（セキュリティパッチ、依存関係更新）を概算する

**Task 3.2: 推奨戦略の決定と文書化**
- 以下3つの戦略の比較表を作成する:
  1. typedoc + TS6.0 並行維持
  2. api-extractor 移行
  3. Corsa 対応 typedoc 待ち
- 短期（〜6ヶ月）、中期（6ヶ月〜1年）、長期（1年〜）のロードマップ案を策定する
- 推奨戦略とその根拠を `docs/wiki/` に文書化する
- 後続の実装チケット作成に必要な要件を整理する

**Task 3.3: プロジェクトドキュメント更新**
- `docs/wiki/` 配下に TS 7.0 移行計画ドキュメントを作成または更新する
- 必要に応じて `README.MD` の「ドキュメント」セクションに現状の制約・今後の計画を追記する
- 追跡が必要なイシュー・リンクを一元管理するセクションを設置する

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

🔗 Related PRs

#39 - feat: TypeDocによるAPIドキュメント自動生成 (#6) [merged]
#41 - refactor: TypeScript 5.xモダナイゼーション (#35) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!