prelude

TypeScript の Prelude を準備する

Prelude は、アンビエントなヘルパーと型のために明示的にインポートするモジュールです。広く使われる、ドメインに依存しない構成要素のうち、より適切なオーナーが存在しないものをまとめます。同梱の prelude.ts を基盤として使用し、対象リポジトリから得られる根拠に合わせて調整してください。全体を通して ../coding-standards/SKILL.md を適用してください。

アンビエントとは、ヘルパーの役割を表すものであり、TypeScript のグローバルを指すものではありません。Prelude のエクスポートは通常のインポート経由で利用できるようにし、グローバル宣言やグローバル拡張は追加しないでください。

1. リポジトリを調査する

リポジトリの指示、パッケージマニフェスト、TypeScript の設定、ソースの配置、インポート規約を確認してください。次のものを特定してください。

• 既存の Prelude、または同等の共有モジュール
• utils、helpers、common、types、result、errors などの名前を持つファイル
• 複数のモジュールで繰り返し使われている汎用型エイリアスや小さな汎用関数
• Result、スキーマ、秘匿化、ブランディング、コレクション、網羅的なマッチングに使われている既存ライブラリ
• アンビエントである可能性のあるヘルパーを呼び出すすべての箇所

ファイル名と概念の両方を使って検索してください。コーディング規約にある、広く使われる汎用ヘルパーや型のカテゴリを検索語の候補にし、名前だけで分類せず、定義と呼び出し箇所を確認してください。

完了条件： リポジトリ全体を対象に、ファイル名、シンボル、重複の各観点から検索して見つかった、アンビエントである可能性のある定義をすべて洗い出し、それぞれのオーナー、呼び出し箇所、依存関係、現在の挙動を記録していること。

2. 候補をすべて分類する

次の条件をすべて満たすシンボルは Prelude に含めます。

• ドメインに依存せず、互いに無関係な複数のモジュールで役立つ
• ドメイン、アプリケーションサービス、アダプター、プロトコル、または用途を絞った汎用モジュールのほうが、より適切なオーナーではない
• 集約することで重複が減るか、広く使われる概念に標準的な実装をひとつ設けられる
• 依存関係が最小限かつ安定しており、プロジェクトですでに必要性が認められている
• インポート箇所で理解できるほど挙動が小さいか、または正確な型によって隠蔽されている

ドメイン上の意味、アプリケーションのポリシー、境界での変換、フレームワークの挙動、I/O、または文字列の大文字・小文字変換や複雑なコレクション操作といったまとまりのある汎用概念を表すシンボルは、用途に合ったオーナーに残してください。ローカルな重複実装より、既存ライブラリを優先してください。Prelude は厳選された基盤であり、バレルでも雑多なものの置き場でもありません。

候補ごとに、既存ライブラリを使う、現在のオーナーに残す、Prelude に移す、テンプレート内のシンボルと統合する、未使用の重複として削除する、のいずれかを決定してください。

完了条件： 洗い出したすべての候補について、その意味と呼び出し箇所に基づく判断がひとつずつ記録されており、ファイル名やシンボル名だけで分類された候補が残っていないこと。

3. テンプレートを基にする

同梱の prelude.ts を最後まで読んでください。プロジェクトで確立されている共有モジュールの配置先にコピーし、出発点として使用してください。すでに Prelude がある場合は、上書きせず、意図的に統合してください。

失敗を表す値の基盤として、次のいずれかを必ずひとつだけ選んでください。

1. プロジェクトが Effect を使用している場合は、Effect の結果・エラー処理機能を使い、テンプレートのローカルな Result フォールバックを削除します。
2. プロジェクトが better-result を使用している場合は、それを使い、ローカルなフォールバックを削除します。
3. プロジェクトがどちらも使用していない場合は、better-result をインストールするか確認します。
   • 承認された場合はインストールし、ローカルなフォールバックを削除します。
   • 承認されなかった場合は、テンプレートのローカルな Result 型とヘルパーを有効にします。

テンプレートのほかの各エクスポートは、リポジトリでの使用状況、コーディング規約、または指定された基盤によって正当化される場合にのみ残してください。同等のヘルパーを統合する場合は、互換性のある既存の挙動を維持してください。意味上の競合がある場合は、いずれかの実装を黙って選ぶのではなく、明示してください。

完了条件： 対象ファイルがテンプレートを基盤とし、Result の戦略がひとつだけ採用されており、残したテンプレートの各エクスポートに明確な根拠があること。

4. 環境ヘルパーと型を統合する

承認済みのリポジトリ候補をプレリュードに移動または統合します。移動するシンボルごとに、次の点を守ってください。

• 動作変更が求められていない限り、動作を維持する；
• 公開名と型の契約を維持するか、意図的に移行する；
• すべての呼び出し元を更新し、プレリュードから直接インポートするようにする；
• 必要な JSDoc、安全性に関するコメント、対象を絞った lint の抑制を維持する；
• 呼び出し元の移行後、置き換えられた定義と互換性のための再エクスポートを削除する。

結果としてできるモジュールは、副作用のない状態に保ってください。設定の読み込み、リソースの取得、ハンドラーの登録、I/O の実行、ドメイン／アプリケーションのポリシーの実装、無関係なモジュールの再エクスポートを行ってはなりません。

完了基準： 承認済みの候補はすべて定義元が一つに統一され、すべての呼び出し元がそれを使用し、削除したソースが第二の信頼できる情報源として残っていないこと。

5. 基盤を検証する

リポジトリのフォーマッター、型チェッカー、リンター、および対象を絞ったテストを実行します。古いシンボル、重複定義、古いインポートパス、棚卸しの対象となった広範なユーティリティファイルを再度検索します。プレリュードのすべてのエクスポートについて、現在の使用状況、または基盤として明示的に必要な理由を確認します。

次の内容を報告してください。

• 選択した結果戦略；
• 維持または削除したテンプレートのエクスポート；
• 移動、統合、現状維持、または削除したリポジトリのヘルパー；
• 検証コマンドと結果。

完了基準： リポジトリのチェックがすべて成功し、棚卸しにおけるすべての判断がコードに反映され、重複する環境定義がなく、プレリュードのすべてのエクスポートに正当な理由があること。