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

[9c5s]

概要

tsgo 導入に伴う CI パイプラインと開発環境の最適化。

影響度: 中

CI 現状

現在の CI ワークフローにはビルド、lint、フォーマットチェック、ドキュメントビルドのステップがある (テストステップは未含有)。
tsgo 統合を機に CI パイプライン全体を最適化する。

チェックリスト

CI パイプライン:

• CI にテストステップ (npm run test) の追加検討
• tsgo 型チェックの CI ジョブ追加
• tsc / tsgo 並行実行による差異検出
• ビルド時間のベンチマーク

開発環境:

• VS Code 拡張 @typescript/native-preview 導入手順の文書化
• lefthook への tsgo 統合検討

Node.js TypeScript strip:

• --experimental-strip-types の examples 実行での活用検討
• (確認済み) enum/namespace は未使用のため strip-types の制約に該当しない

[coderabbitai]

Coding Plan

Summary

• CI パイプラインにテストステップと tsgo 型チェックを追加し、tsc との並行実行で移行期間中の差異検出を可能にする
• lefthook で tsc と tsgo を並列実行し、ローカル開発でも差異を検出できるようにする
• @typescript/native-preview の導入手順を文書化し、チーム全体での tsgo 活用を促進する
• Node.js の --experimental-strip-types を examples に導入し、tsx 依存を段階的に削減する選択肢を提供する

Design Choices

Design Choice 1: lefthook での tsgo 統合方法

Options Considered:

1. tsc を tsgo に完全置換
2. tsc と tsgo を並行実行して差異検出
3. tsgo のみ追加し、tsc も残す

Chosen Option: 2

Rationale: 移行期間中は両方実行することで差異を検出し、tsgo の安定性を検証できる。

Design Choice 2: examples での strip-types 導入方法

Options Considered:

1. tsx を --experimental-strip-types に完全置換
2. 新しい npm script として追加し、tsx 版も残す

Chosen Option: 2

Rationale: Node.js 22.6.0+ が必要なため、互換性を考慮して両方のスクリプトを用意する。

💡 User Tips

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

Implementation Steps

Phase 1: CI パイプライン強化

CI ワークフローにテストステップを追加し、tsgo による型チェック、tsc との差異検出、ビルド時間ベンチマークを実装する。

Task 1: テストステップの追加

CI ワークフローにユニットテスト実行ステップを追加する。

• .github/workflows/ci.yml の「ビルド」ステップの後に npm run test ステップを追加
• ステップ名は既存の日本語命名規則に従い「テスト」とする
• E2E テストは別途検討として、まずユニットテストのみを対象とする

Task 2: tsgo 型チェックジョブの追加

@typescript/native-preview を導入し、tsgo による型チェックを CI に追加する。

• package.json の devDependencies に @typescript/native-preview を追加
• package.json の scripts に以下を追加:
  • typecheck: tsc --noEmit（従来の型チェック）
  • typecheck:tsgo: tsgo --noEmit（tsgo による型チェック）
• .github/workflows/ci.yml に「型チェック (tsgo)」ステップを追加（npm run typecheck:tsgo）

Task 3: tsc/tsgo 並行実行による差異検出

移行期間中、両方の型チェッカーを実行して出力の差異を検出する仕組みを構築する。

• package.json の scripts に typecheck:compare を追加
  • tsc と tsgo の両方を実行し、終了コードの差異を検出
  • 例: npm run typecheck && npm run typecheck:tsgo
• .github/workflows/ci.yml に「型チェック比較」ステップを追加
  • tsc と tsgo の両方を実行し、いずれかが失敗した場合は CI を失敗させる
  • 将来的に tsgo が安定したら tsc ステップを削除可能

Task 4: ビルド時間ベンチマーク

CI でビルド時間を計測・記録する仕組みを追加する。

• .github/workflows/ci.yml のビルド関連ステップに時間計測を追加
  • GitHub Actions の SECONDS 環境変数または date コマンドを使用
  • ステップのログに型チェック時間（tsc / tsgo それぞれ）を出力
• 型チェック比較ステップで両者の実行時間を比較表示
• ジョブサマリーにベンチマーク結果を出力（$GITHUB_STEP_SUMMARY を使用）

🤖 Prompt for AI agents

CI パイプラインを強化するフェーズ。`.github/workflows/ci.yml` と `package.json` を更新し、テストステップ・tsgo
型チェック・差異検出・ビルド時間ベンチマークを追加する。

**`package.json` の更新:**
- `devDependencies` に `@typescript/native-preview` を追加
- `scripts` に以下を追加:
  - `typecheck`: `tsc --noEmit`
  - `typecheck:tsgo`: `tsgo --noEmit`
  - `typecheck:compare`: `npm run typecheck && npm run typecheck:tsgo`

**`.github/workflows/ci.yml` の更新:**
- 「ビルド」ステップの後に `npm run test` を実行する「テスト」ステップを追加（既存の日本語命名規則に従う）
- 「型チェック (tsgo)」ステップを追加（`npm run typecheck:tsgo` を実行）
- 「型チェック比較」ステップを追加:
  - tsc と tsgo の両方を実行し、いずれかが失敗した場合は CI を失敗させる
  - 将来的に tsgo が安定したら tsc ステップを削除可能
- ビルド関連ステップに時間計測を追加:
  - GitHub Actions の `SECONDS` 環境変数または `date` コマンドを使用
  - ステップのログに型チェック時間（tsc / tsgo それぞれ）を出力
  - 型チェック比較ステップで両者の実行時間を比較表示
  - `$GITHUB_STEP_SUMMARY` を使用してジョブサマリーにベンチマーク結果を出力

Phase 2: 開発環境の最適化

ローカル開発環境に tsgo を統合し、開発者向けドキュメントを整備する。

Task 1: lefthook への tsgo 統合

pre-commit フックで tsgo を tsc と並行実行し、差異を検出できるようにする。

• lefthook.yml の typecheck コマンドを更新
  • 現在の npx tsc --noEmit に加えて npx tsgo --noEmit を並行実行
  • 両方の型チェッカーを実行することで移行期間中の差異を検出
• typecheck を group 化し、tsc と tsgo を並列実行する構成に変更

  typecheck:
    parallel: true
    commands:
      tsc:
        run: npx tsc --noEmit
      tsgo:
        run: npx tsgo --noEmit
  

Task 2: VS Code 拡張導入手順の文書化

TypeScript Native Preview 拡張の導入手順をドキュメント化する。

• docs/wiki/ ディレクトリに開発環境セットアップガイドを作成（または既存ドキュメントに追記）
• 以下の内容を含める:
  • VS Code Marketplace から「TypeScript (Native Preview)」拡張のインストール手順
  • 拡張の有効化設定（typescript.experimental.useTsgo 等）
  • tsgo を使用する際の注意事項（プレビュー段階のため一部機能制限あり）
  • トラブルシューティング（tsgo と tsc の出力差異が発生した場合の対応）

🤖 Prompt for AI agents

ローカル開発環境を最適化するフェーズ。`lefthook.yml` を更新して tsgo を並列実行に対応させ、VS Code
拡張の導入手順ドキュメントを作成する。

**`lefthook.yml` の更新:**
- `typecheck` コマンドを group 化し、tsc と tsgo を並列実行する構成に変更:
  ```
  typecheck:
    parallel: true
    commands:
      tsc:
        run: npx tsc --noEmit
      tsgo:
        run: npx tsgo --noEmit
  ```

**ドキュメントの作成:**
- `docs/wiki/` ディレクトリに開発環境セットアップガイドを作成（または既存ドキュメントに追記）
- 以下の内容を含める:
  - VS Code Marketplace から「TypeScript (Native Preview)」拡張のインストール手順
  - 拡張の有効化設定（`typescript.experimental.useTsgo` 等）
  - tsgo を使用する際の注意事項（プレビュー段階のため一部機能制限あり）
  - トラブルシューティング（tsgo と tsc の出力差異が発生した場合の対応）

Phase 3: Examples 実行環境の最適化

Node.js の --experimental-strip-types を活用し、examples の実行方法を最適化する。

--experimental-strip-types の導入

tsx の代わりに Node.js ネイティブの型ストリップ機能を使用するオプションを追加する。

• 前提条件の確認（完了済み）:
  • enum/namespace 未使用のため strip-types の制約に該当しない
  • tsconfig.json は NodeNext モジュールで互換性あり
• package.json の scripts に新しいスクリプトを追加:
  • example:native: node --experimental-strip-types examples/index.ts
  • 既存の example スクリプト（tsx 使用）は互換性のため残す
• examples/index.ts のインポートパスを確認:
  • 現在 from "../src" となっているが、strip-types では拡張子が必要
  • from "../src/index.ts" への変更を検討
  • または --experimental-strip-types と --experimental-transform-types の組み合わせを検討
• README または docs にネイティブ実行方法を記載

🤖 Prompt for AI agents

Node.js の `--experimental-strip-types` を examples に導入するフェーズ。`package.json`
へのスクリプト追加、`examples/index.ts` のインポートパス確認・修正、ドキュメント更新を行う。

**`package.json` の更新:**
- `scripts` に `example:native`: `node --experimental-strip-types
examples/index.ts` を追加
- 既存の `example` スクリプト（tsx 使用）は互換性のため残す

**`examples/index.ts` のインポートパス確認:**
- 現在 `from "../src"` となっているが、strip-types では拡張子が必要
- `from "../src/index.ts"` への変更を検討
- または `--experimental-strip-types` と `--experimental-transform-types` の組み合わせを検討

**ドキュメントの更新:**
- README または docs にネイティブ実行方法（`example:native` スクリプト）を記載
- Node.js 22.6.0+ が必要である旨を明記

Research

本プロジェクトは TCNet プロトコルの Node.js クライアントライブラリ。CI は .github/workflows/ci.yml で単一ジョブ構成（build, lint, format:check, docs）だが、テストステップは未含有。型チェックは lefthook の pre-commit で tsc --noEmit として実行されているが、package.json に専用スクリプトはない。tsconfig.json は target: ES2022, module: NodeNext, strict: true で tsgo 互換。examples は tsx を使用した ESM インポートで実行される。

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

CI パイプラインを強化するフェーズ。`.github/workflows/ci.yml` と `package.json` を更新し、テストステップ・tsgo
型チェック・差異検出・ビルド時間ベンチマークを追加する。

**`package.json` の更新:**
- `devDependencies` に `@typescript/native-preview` を追加
- `scripts` に以下を追加:
  - `typecheck`: `tsc --noEmit`
  - `typecheck:tsgo`: `tsgo --noEmit`
  - `typecheck:compare`: `npm run typecheck && npm run typecheck:tsgo`

**`.github/workflows/ci.yml` の更新:**
- 「ビルド」ステップの後に `npm run test` を実行する「テスト」ステップを追加（既存の日本語命名規則に従う）
- 「型チェック (tsgo)」ステップを追加（`npm run typecheck:tsgo` を実行）
- 「型チェック比較」ステップを追加:
  - tsc と tsgo の両方を実行し、いずれかが失敗した場合は CI を失敗させる
  - 将来的に tsgo が安定したら tsc ステップを削除可能
- ビルド関連ステップに時間計測を追加:
  - GitHub Actions の `SECONDS` 環境変数または `date` コマンドを使用
  - ステップのログに型チェック時間（tsc / tsgo それぞれ）を出力
  - 型チェック比較ステップで両者の実行時間を比較表示
  - `$GITHUB_STEP_SUMMARY` を使用してジョブサマリーにベンチマーク結果を出力
===============================================================================

Task: 2

ローカル開発環境を最適化するフェーズ。`lefthook.yml` を更新して tsgo を並列実行に対応させ、VS Code
拡張の導入手順ドキュメントを作成する。

**`lefthook.yml` の更新:**
- `typecheck` コマンドを group 化し、tsc と tsgo を並列実行する構成に変更:
  ```
  typecheck:
    parallel: true
    commands:
      tsc:
        run: npx tsc --noEmit
      tsgo:
        run: npx tsgo --noEmit
  ```

**ドキュメントの作成:**
- `docs/wiki/` ディレクトリに開発環境セットアップガイドを作成（または既存ドキュメントに追記）
- 以下の内容を含める:
  - VS Code Marketplace から「TypeScript (Native Preview)」拡張のインストール手順
  - 拡張の有効化設定（`typescript.experimental.useTsgo` 等）
  - tsgo を使用する際の注意事項（プレビュー段階のため一部機能制限あり）
  - トラブルシューティング（tsgo と tsc の出力差異が発生した場合の対応）
===============================================================================

Task: 3

Node.js の `--experimental-strip-types` を examples に導入するフェーズ。`package.json`
へのスクリプト追加、`examples/index.ts` のインポートパス確認・修正、ドキュメント更新を行う。

**`package.json` の更新:**
- `scripts` に `example:native`: `node --experimental-strip-types
examples/index.ts` を追加
- 既存の `example` スクリプト（tsx 使用）は互換性のため残す

**`examples/index.ts` のインポートパス確認:**
- 現在 `from "../src"` となっているが、strip-types では拡張子が必要
- `from "../src/index.ts"` への変更を検討
- または `--experimental-strip-types` と `--experimental-transform-types` の組み合わせを検討

**ドキュメントの更新:**
- README または docs にネイティブ実行方法（`example:native` スクリプト）を記載
- Node.js 22.6.0+ が必要である旨を明記

💡 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

#1 - ci: lefthookによるローカルCI環境を構築 [merged]
#16 - feat(ci): changeset ファイルの検証フックを追加 [merged]
#27 - feat: GitHub Packagesへの同時publishとワークフロー改善 [merged]
#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!