TS7.0 (tsgo) 移行トラッカー

[9c5s]

概要

TypeScript 7.0 (tsgo) 環境への移行に向けた影響分析と移行計画の全体トラッカー。
TS 6.0 を TS 7.0 へのステッピングストーンとして位置づけ、最終的に tsgo を主力コンパイラとする。

TS 6.0 を経由する理由

TS 7.0 (tsgo) は TS 6.0 より先にリリースされているが、以下の理由から TS 6.0 をブリッジとして経由する:

1. ツールチェーン依存: typescript-eslint, typedoc は Strada API に依存、tsgo の Corsa API は未対応
2. 破壊的変更の段階的消化: TS 6.0 で非推奨オプション削除・デフォルト値変更に先に対応
3. 並行運用: TS 6.0 + @typescript/native-preview で段階的に移行可能

移行フェーズ

Phase 1 と Phase 2 は独立しており並行着手可能。Phase 3 は Phase 1, 2 の両方に依存する。

Phase 1 (TS 6.0 移行) ──┐
                          ├──> Phase 3 (TS 7.0 完全移行)
Phase 2 (tsgo 並行導入) ─┘

Phase	内容	ブロッカー	他Phaseとの関係
Phase 1	TS 6.0 移行	typescript-eslint PR #12124, typedoc 対応	Phase 2 と並行可能
Phase 2	tsgo 並行導入	なし	Phase 1 と並行可能、即座に着手可能
Phase 3	TS 7.0 完全移行	Corsa API 成熟	Phase 1, 2 完了後

サブ Issue

Phase 1:

• TS7.0移行: tsconfig.json / ソースコード移行 #43 tsconfig.json / ソースコード移行
• TS7.0移行: リンター移行 — eslint → oxlint 検討 #45 リンター移行 — eslint → oxlint 検討
• TS7.0移行: ドキュメントツール — typedoc 対応検討 #46 ドキュメントツール — typedoc 対応検討

Phase 2:

• TS7.0移行: ビルドパイプライン — tsgo 統合 #44 ビルドパイプライン — tsgo 統合

Phase 1 & 2 共通:

• TS7.0移行: CI / 開発環境の最適化 #47 CI / 開発環境の最適化

ツールチェーン対応タイムライン (推定)

ツール	TS 6.0 対応	tsgo (Corsa API) 対応
typescript-eslint	PR #12124 進行中	1-2年先
typedoc	要確認	不明
tsup	実影響小 (esbuild 依存)	N/A (独立動作)
vitest	実影響小 (型チェック非依存)	N/A (独立動作)
oxlint + tsgolint	N/A	対応済み (tsgo 専用設計)

参考

• Announcing TypeScript 6.0
• Progress on TypeScript 7 - December 2025
• typescript-eslint TS6 Support Issue #12123

[coderabbitai]

Coding Plan

Summary

• TS 6.0 をステッピングストーンとし、Phase 1 (TS 6.0 移行) と Phase 2 (tsgo 並行導入) を並行して進める構成
• リンターは typescript-eslint の TS 6.0 対応を待つより oxlint に先行移行し、将来の tsgolint 統合への道筋を確保
• tsgo は @typescript/native-preview として並行導入し、CI では初期段階で失敗を許容しつつ安定性を検証
• Phase 3 (TS 7.0 完全移行) は Corsa API の成熟度に依存するため、Phase 1 & 2 完了後に詳細計画を策定

Design Choices

Design Choice 1: リンター移行戦略: oxlint への移行 vs typescript-eslint TS 6.0 対応待ち

Options Considered:

1. typescript-eslint を TS 6.0 対応版にアップグレードし、現行構成を維持
2. oxlint に移行し、tsgo 移行完了後に tsgolint を追加

Chosen Option: 2

Rationale: 現行の ESLint 構成は型情報を使わない軽量構成であり、oxlint への移行コストが低い。Phase 3 での tsgolint 統合を見据え、先行して oxlint に移行することで将来の技術負債を回避。

Design Choice 2: TypeDoc の TS 6.0 対応方針

Options Considered:

1. TypeDoc の TS 6.0 対応版リリースを待機
2. 代替ドキュメントツール (api-extractor + api-documenter) への移行を検討
3. TS 6.0 移行と TypeDoc アップグレードを分離し、TypeDoc は TS 5.x 互換モードで維持

Chosen Option: 1

Rationale: TypeDoc は Strada API に深く依存しており、TS 6.0 対応は上流で進行中と想定。代替ツールへの移行は学習コストが高く、現時点では待機が妥当。ブロッカーとなる場合は Option 3 を検討。

💡 User Tips

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

Implementation Steps

Phase 1: TS 6.0 移行 (tsconfig.json / ソースコード / リンター / ドキュメント)

本フェーズでは TypeScript 5.x から 6.0 への移行を実施。コンパイラオプションの非推奨項目削除、新規必須オプション追加、周辺ツールのアップグレードを行う。Phase 2 と並行して着手可能。

Task 1: tsconfig.json の TS 6.0 対応 (Sub-issue `#43`)

TypeScript 6.0 で削除・変更されるコンパイラオプションを更新し、新しいデフォルト値に対応する。

• tsconfig.json から forceConsistentCasingInFileNames: true を削除 (TS 6.0 でデフォルト化)
• isolatedModules: true を追加 (esbuild/tsup との互換性を明示)
• verbatimModuleSyntax: true を追加 (import type の厳格なセマンティクスを保証)
• module: "NodeNext" と moduleResolution: "NodeNext" の動作変更を確認し、必要に応じて調整
• package.json の typescript バージョンを ^6.0.0 にバンプ

Task 2: ソースコードの TS 6.0 互換性確認 (Sub-issue `#43`)

現行コードは import type / export type を適切に使用しており、大規模な変更は不要だが、verbatimModuleSyntax 有効化に伴う検証を行う。

• src/ 配下の全ファイルで verbatimModuleSyntax 違反がないことを確認
• import 文で型のみをインポートしている箇所が import type または inline type 修飾子を使用していることを検証
• examples/index.ts の型インポートパターンを確認
• TS 6.0 で新たに strict デフォルト化される項目があれば対応

Task 3: oxlint への移行 (Sub-issue `#45`)

typescript-eslint から oxlint への移行を実施。現行構成は型情報を使わない軽量 lint のため、移行コストは低い。

• package.json から eslint, typescript-eslint, eslint-plugin-jsdoc を削除
• oxlint を devDependencies に追加
• eslint.config.mjs を削除し、oxlint.config.json (または .oxlintrc.json) を新規作成
• 現行の lint ルール (no-unused-vars, no-empty-function, no-explicit-any, JSDoc ルール) を oxlint 相当に移植
• package.json の lint スクリプトを oxlint . に変更
• lefthook.yml の pre-commit lint コマンドを更新

Task 4: TypeDoc TS 6.0 対応 (Sub-issue `#46`)

TypeDoc の TS 6.0 対応版リリースを追跡し、リリース後にアップグレードする。

• TypeDoc GitHub リポジトリの TS 6.0 対応 Issue/PR を追跡
• 対応版リリース後、package.json の typedoc バージョンをバンプ
• typedoc.json の設定項目で TS 6.0 に伴う変更が必要な箇所を確認
• npm run docs でドキュメント生成が正常に動作することを検証
• treatValidationWarningsAsErrors: true による新規エラーが発生しないことを確認

🤖 Prompt for AI agents

TypeScript 5.x から 6.0 への移行を実施するフェーズ。コンパイラオプションの更新、ソースコードの互換性検証、リンターの oxlint
移行、TypeDoc のアップグレード対応を行う。

**タスク 1.1: tsconfig.json の更新**
- `tsconfig.json` から `forceConsistentCasingInFileNames: true` を削除する (TS 6.0
でデフォルト化)
- `isolatedModules: true` を追加する (esbuild/tsup との互換性を明示)
- `verbatimModuleSyntax: true` を追加する (`import type` の厳格なセマンティクスを保証)
- `module: "NodeNext"` と `moduleResolution: "NodeNext"` の動作変更を確認し、必要に応じて調整する
- `package.json` の `typescript` バージョンを `^6.0.0` にバンプする

**タスク 1.2: ソースコードの TS 6.0 互換性確認**
- `src/` 配下の全ファイルで `verbatimModuleSyntax` 違反がないことを確認する
- `import` 文で型のみをインポートしている箇所が `import type` または inline `type` 修飾子を使用していることを検証する
- `examples/index.ts` の型インポートパターンを確認する
- TS 6.0 で新たに strict デフォルト化される項目があれば対応する

**タスク 1.3: oxlint への移行**
- `package.json` から `eslint`、`typescript-eslint`、`eslint-plugin-jsdoc` を削除する
- `oxlint` を devDependencies に追加する
- `eslint.config.mjs` を削除する
- `oxlint.config.json` (または `.oxlintrc.json`) を新規作成し、現行ルール
(`no-unused-vars`、`no-empty-function`、`no-explicit-any`、JSDoc ルール) を oxlint
相当に移植する
- `package.json` の `lint` スクリプトを `oxlint .` に変更する
- `lefthook.yml` の pre-commit lint コマンドを更新する

**タスク 1.4: TypeDoc TS 6.0 対応**
- TypeDoc GitHub リポジトリの TS 6.0 対応 Issue/PR を追跡する
- 対応版リリース後、`package.json` の `typedoc` バージョンをバンプする
- `typedoc.json` の設定項目で TS 6.0 に伴う変更が必要な箇所を確認する
- `npm run docs` でドキュメント生成が正常に動作することを検証する
- `treatValidationWarningsAsErrors: true` による新規エラーが発生しないことを確認する

Phase 2: tsgo 並行導入 (ビルドパイプライン統合)

本フェーズでは @typescript/native-preview (tsgo) を導入し、既存の TS 6.0 環境と並行して型チェックを実行できる体制を構築する。Phase 1 と並行して即座に着手可能。

Task 1: tsgo のインストールと初期設定 (Sub-issue `#44`)

tsgo を開発依存として追加し、基本的な型チェックが通ることを確認する。

• package.json に @typescript/native-preview を devDependencies として追加
• tsgo --version で正常にインストールされていることを確認
• tsgo コマンドで src/ 配下の型チェックを実行し、エラーがないことを確認
• tsgo 固有の診断メッセージや挙動の差異を記録

Task 2: 並行型チェックスクリプトの追加 (Sub-issue `#44`)

既存の tsc と tsgo の両方で型チェックを実行できるスクリプトを追加する。

• package.json に typecheck:tsc スクリプト (tsc --noEmit) を追加
• package.json に typecheck:tsgo スクリプト (tsgo --noEmit) を追加
• package.json に typecheck スクリプト (両方を実行) を追加
• watch スクリプトの tsgo 対応版を検討 (tsgo の watch モード対応状況による)

Task 3: tsup ビルドへの tsgo 統合検討 (Sub-issue `#44`)

tsup の dts 生成が tsgo で動作するかを検証し、将来の移行パスを確立する。

• tsup の dts: true が内部で使用する rollup-plugin-dts が tsgo の出力を処理できるか検証
• tsgo の declaration 出力 (--declaration) のフォーマットを確認
• 必要に応じて tsup.config.ts の dts 設定を調整、または別途 dts 生成ステップを追加する方針を決定
• tsup が esbuild に依存しており tsgo とは独立動作することを確認

🤖 Prompt for AI agents

`@typescript/native-preview` (tsgo) を devDependencies として導入し、既存の TS 6.0
環境と並行して型チェックを実行できる体制を構築するフェーズ。

**タスク 2.1: tsgo のインストールと初期設定**
- `package.json` の devDependencies に `@typescript/native-preview` を追加する
- `tsgo --version` でインストールの確認ができるようにする
- `tsgo` コマンドで `src/` 配下の型チェックを実行し、エラーの有無を確認する
- tsgo 固有の診断メッセージや挙動の差異を記録する

**タスク 2.2: 並行型チェックスクリプトの追加**
- `package.json` に以下のスクリプトを追加する:
  - `typecheck:tsc`: `tsc --noEmit` を実行
  - `typecheck:tsgo`: `tsgo --noEmit` を実行
  - `typecheck`: 上記両方を実行
- `watch` スクリプトの tsgo 対応版を検討する (tsgo の watch モード対応状況による)

**タスク 2.3: tsup ビルドへの tsgo 統合検討**
- tsup の `dts: true` が内部で使用する rollup-plugin-dts が tsgo の出力を処理できるか検証する
- tsgo の declaration 出力 (`--declaration`) のフォーマットを確認する
- 必要に応じて `tsup.config.ts` の `dts` 設定を調整する、または別途 `dts` 生成ステップを追加する方針を決定する
- tsup が esbuild に依存しており tsgo とは独立動作することを確認する

Phase 3: CI / 開発環境の最適化 (Phase 1 & 2 共通)

本フェーズでは CI パイプラインと開発環境を TS 6.0 + tsgo 並行運用に最適化する。Phase 1 と Phase 2 の進捗に応じて段階的に実施。

Task 1: CI ワークフローへの tsgo 統合 (Sub-issue `#47`)

GitHub Actions CI に tsgo による型チェックを追加し、既存の TS 6.0 型チェックと並行実行する。

• .github/workflows/ci.yml に typecheck:tsgo ステップを追加
• 初期段階では tsgo チェックを continue-on-error: true で実行し、失敗をブロッカーにしない
• tsgo の安定性が確認できた段階で continue-on-error を解除
• ビルド時間の変化をモニタリングし、tsgo の高速性を検証

Task 2: Node.js バージョンと依存関係の整理 (Sub-issue `#47`)

TS 6.0 と tsgo の動作要件に合わせて Node.js バージョンと依存関係を整理する。

• package.json に engines フィールドを追加し、対応 Node.js バージョンを明示
• .nvmrc または .node-version ファイルを追加して開発環境の Node.js バージョンを固定
• @types/node のバージョンを Node.js 24.x 互換のものに維持
• 不要になった devDependencies (eslint 関連など) を削除

Task 3: 開発者向けドキュメント更新 (Sub-issue `#47`)

移行後の開発フローを docs/wiki に反映する。

• docs/wiki/Contributing.md に tsgo 並行運用時の開発フローを追記
• lint コマンドの変更 (eslint → oxlint) を反映
• 型チェックコマンド (npm run typecheck, npm run typecheck:tsgo) の説明を追加
• トラブルシューティングセクションに tsgo 固有の注意点を記載

🤖 Prompt for AI agents

CI パイプラインと開発環境を TS 6.0 + tsgo 並行運用に最適化するフェーズ。Phase 1 と Phase 2
の完了後、または進捗に応じて段階的に実施する。

**タスク 3.1: CI ワークフローへの tsgo 統合**
- `.github/workflows/ci.yml` に `typecheck:tsgo` ステップを追加する
- 初期段階では `continue-on-error: true` を設定し、tsgo チェックの失敗をブロッカーにしない
- tsgo の安定性が確認できた段階で `continue-on-error` を解除する
- ビルド時間の変化をモニタリングし、tsgo の高速性を検証する

**タスク 3.2: Node.js バージョンと依存関係の整理**
- `package.json` に `engines` フィールドを追加し、対応 Node.js バージョンを明示する
- `.nvmrc` または `.node-version` ファイルを追加して開発環境の Node.js バージョンを固定する
- `@types/node` のバージョンを Node.js 24.x 互換のものに維持する
- 不要になった devDependencies (eslint 関連など) を削除する

**タスク 3.3: 開発者向けドキュメント更新**
- `docs/wiki/Contributing.md` に tsgo 並行運用時の開発フローを追記する
- lint コマンドの変更 (eslint → oxlint) を反映する
- 型チェックコマンド (`npm run typecheck`、`npm run typecheck:tsgo`) の説明を追加する
- トラブルシューティングセクションに tsgo 固有の注意点を記載する

Phase 4: TS 7.0 完全移行 (将来フェーズ)

本フェーズは Phase 1 と Phase 2 の完了後、Corsa API の成熟を待って実施する。現時点では計画のみ記載。

Task 1: Corsa API 成熟度の追跡

typescript-eslint や typedoc 等のツールが Corsa API に対応するまでの進捗を追跡する。

• typescript-eslint の Corsa API 対応 Issue を監視
• typedoc の tsgo/Corsa API 対応状況を追跡
• tsgolint の機能成熟度を評価
• Corsa API が十分に安定した段階で TS 7.0 完全移行の詳細計画を策定

Task 2: TS 6.0 (Strada API) からの完全移行

Corsa API 対応が整った段階で、TS 6.0 依存を完全に tsgo に置き換える。

• package.json から typescript (Strada) を削除
• @typescript/native-preview を正式版 typescript に置き換え (バージョン 7.x)
• typescript-eslint を tsgolint に完全移行 (Phase 1 で oxlint 移行済みの場合は tsgolint 追加のみ)
• CI から TS 6.0 型チェックステップを削除し、tsgo のみに統一

🤖 Prompt for AI agents

Phase 1 と Phase 2 の完了後、Corsa API の成熟を待って実施する将来フェーズ。現時点では計画のみ記載。

**タスク 4.1: Corsa API 成熟度の追跡**
- typescript-eslint の Corsa API 対応 Issue を監視する
- typedoc の tsgo/Corsa API 対応状況を追跡する
- tsgolint の機能成熟度を評価する
- Corsa API が十分に安定した段階で TS 7.0 完全移行の詳細計画を策定する

**タスク 4.2: TS 6.0 (Strada API) からの完全移行**
- `package.json` から `typescript` (Strada) を削除する
- `@typescript/native-preview` を正式版 `typescript` に置き換える (バージョン 7.x)
- typescript-eslint を tsgolint に完全移行する (Phase 1 で oxlint 移行済みの場合は tsgolint 追加のみ)
- CI から TS 6.0 型チェックステップを削除し、tsgo のみに統一する

Research

本プロジェクトは TypeScript 5.9.3 ベースの Node.js ライブラリで、tsup による CJS/ESM デュアルビルド、typescript-eslint による lint、typedoc による API ドキュメント生成を行う。tsconfig.json は module: "NodeNext" を採用し、as const + satisfies パターンで enum を回避する近代的な TypeScript 構文を使用。CI は GitHub Actions (Node 24.x) で build/lint/format/docs を実行、Changesets でリリース管理を行う。ESLint は型情報を使わない recommended プリセットのため、TS 6.0 移行の影響は比較的軽微。

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

TypeScript 5.x から 6.0 への移行を実施するフェーズ。コンパイラオプションの更新、ソースコードの互換性検証、リンターの oxlint
移行、TypeDoc のアップグレード対応を行う。

**タスク 1.1: tsconfig.json の更新**
- `tsconfig.json` から `forceConsistentCasingInFileNames: true` を削除する (TS 6.0
でデフォルト化)
- `isolatedModules: true` を追加する (esbuild/tsup との互換性を明示)
- `verbatimModuleSyntax: true` を追加する (`import type` の厳格なセマンティクスを保証)
- `module: "NodeNext"` と `moduleResolution: "NodeNext"` の動作変更を確認し、必要に応じて調整する
- `package.json` の `typescript` バージョンを `^6.0.0` にバンプする

**タスク 1.2: ソースコードの TS 6.0 互換性確認**
- `src/` 配下の全ファイルで `verbatimModuleSyntax` 違反がないことを確認する
- `import` 文で型のみをインポートしている箇所が `import type` または inline `type` 修飾子を使用していることを検証する
- `examples/index.ts` の型インポートパターンを確認する
- TS 6.0 で新たに strict デフォルト化される項目があれば対応する

**タスク 1.3: oxlint への移行**
- `package.json` から `eslint`、`typescript-eslint`、`eslint-plugin-jsdoc` を削除する
- `oxlint` を devDependencies に追加する
- `eslint.config.mjs` を削除する
- `oxlint.config.json` (または `.oxlintrc.json`) を新規作成し、現行ルール
(`no-unused-vars`、`no-empty-function`、`no-explicit-any`、JSDoc ルール) を oxlint
相当に移植する
- `package.json` の `lint` スクリプトを `oxlint .` に変更する
- `lefthook.yml` の pre-commit lint コマンドを更新する

**タスク 1.4: TypeDoc TS 6.0 対応**
- TypeDoc GitHub リポジトリの TS 6.0 対応 Issue/PR を追跡する
- 対応版リリース後、`package.json` の `typedoc` バージョンをバンプする
- `typedoc.json` の設定項目で TS 6.0 に伴う変更が必要な箇所を確認する
- `npm run docs` でドキュメント生成が正常に動作することを検証する
- `treatValidationWarningsAsErrors: true` による新規エラーが発生しないことを確認する
===============================================================================

Task: 2

`@typescript/native-preview` (tsgo) を devDependencies として導入し、既存の TS 6.0
環境と並行して型チェックを実行できる体制を構築するフェーズ。

**タスク 2.1: tsgo のインストールと初期設定**
- `package.json` の devDependencies に `@typescript/native-preview` を追加する
- `tsgo --version` でインストールの確認ができるようにする
- `tsgo` コマンドで `src/` 配下の型チェックを実行し、エラーの有無を確認する
- tsgo 固有の診断メッセージや挙動の差異を記録する

**タスク 2.2: 並行型チェックスクリプトの追加**
- `package.json` に以下のスクリプトを追加する:
  - `typecheck:tsc`: `tsc --noEmit` を実行
  - `typecheck:tsgo`: `tsgo --noEmit` を実行
  - `typecheck`: 上記両方を実行
- `watch` スクリプトの tsgo 対応版を検討する (tsgo の watch モード対応状況による)

**タスク 2.3: tsup ビルドへの tsgo 統合検討**
- tsup の `dts: true` が内部で使用する rollup-plugin-dts が tsgo の出力を処理できるか検証する
- tsgo の declaration 出力 (`--declaration`) のフォーマットを確認する
- 必要に応じて `tsup.config.ts` の `dts` 設定を調整する、または別途 `dts` 生成ステップを追加する方針を決定する
- tsup が esbuild に依存しており tsgo とは独立動作することを確認する
===============================================================================

Task: 3

CI パイプラインと開発環境を TS 6.0 + tsgo 並行運用に最適化するフェーズ。Phase 1 と Phase 2
の完了後、または進捗に応じて段階的に実施する。

**タスク 3.1: CI ワークフローへの tsgo 統合**
- `.github/workflows/ci.yml` に `typecheck:tsgo` ステップを追加する
- 初期段階では `continue-on-error: true` を設定し、tsgo チェックの失敗をブロッカーにしない
- tsgo の安定性が確認できた段階で `continue-on-error` を解除する
- ビルド時間の変化をモニタリングし、tsgo の高速性を検証する

**タスク 3.2: Node.js バージョンと依存関係の整理**
- `package.json` に `engines` フィールドを追加し、対応 Node.js バージョンを明示する
- `.nvmrc` または `.node-version` ファイルを追加して開発環境の Node.js バージョンを固定する
- `@types/node` のバージョンを Node.js 24.x 互換のものに維持する
- 不要になった devDependencies (eslint 関連など) を削除する

**タスク 3.3: 開発者向けドキュメント更新**
- `docs/wiki/Contributing.md` に tsgo 並行運用時の開発フローを追記する
- lint コマンドの変更 (eslint → oxlint) を反映する
- 型チェックコマンド (`npm run typecheck`、`npm run typecheck:tsgo`) の説明を追加する
- トラブルシューティングセクションに tsgo 固有の注意点を記載する
===============================================================================

Task: 4

Phase 1 と Phase 2 の完了後、Corsa API の成熟を待って実施する将来フェーズ。現時点では計画のみ記載。

**タスク 4.1: Corsa API 成熟度の追跡**
- typescript-eslint の Corsa API 対応 Issue を監視する
- typedoc の tsgo/Corsa API 対応状況を追跡する
- tsgolint の機能成熟度を評価する
- Corsa API が十分に安定した段階で TS 7.0 完全移行の詳細計画を策定する

**タスク 4.2: TS 6.0 (Strada API) からの完全移行**
- `package.json` から `typescript` (Strada) を削除する
- `@typescript/native-preview` を正式版 `typescript` に置き換える (バージョン 7.x)
- typescript-eslint を tsgolint に完全移行する (Phase 1 で oxlint 移行済みの場合は tsgolint 追加のみ)
- CI から TS 6.0 型チェックステップを削除し、tsgo のみに統一する

💡 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!