ApexLibrarian
Apex クラスの司書。org が剥がしたディレクトリ構造を、クラス自身の宣言から復元する。
Salesforce の org には Apex クラスのフォルダという概念がありません。 retrieve するたびにリポジトリの階層は失われ、ファイルは classes/ 直下に フラットに落ちてきます。ApexLibrarian は置き場所をクラスの doc コメントに宣言させ、 コマンド 1 つで全クラスをあるべき棚に戻します。
/** * 商談の値引き額を明細から再計算する。 * @directory Usecases/opportunity */public with sharing class ReconcileDiscount {doc コメントはクラス本体の一部なので、@directory タグは org との往復を何度でも生き延びます。
retrieve で失われた階層が、1 コマンドで戻る
Apex Stem の 4 フレームワークを Unlocked Package でインストールし、sf project retrieve で取得した直後の実例です。 95 クラスすべてが submodule 導入時と同一の階層に戻ります。
classes/ ├── AbstractEntry.cls ├── ApexBlueprintException.cls ├── CountClause.cls ├── Eloquent.cls ├── MockEntry.cls ├── SBlueprint.cls ├── Scribe.cls ├── Trace.cls ├── TraceFlow.cls ├── TriggerHandler.cls └── … 全 95 クラスがフラット
npx apex-librarian arrange→classes/ ├── ApexBlueprint/ │ ├── SBlueprint.cls │ └── tests/ ├── ApexEloquent/ │ ├── Scribe.cls │ ├── AggregateClauses/ │ │ └── CountClause.cls │ ├── Eloquents/ │ │ └── Eloquent.cls │ └── Entries/ │ └── MockEntry.cls ├── ApexTrace/ │ ├── Trace.cls │ └── TraceFlow.cls └── ApexTools/ └── TriggerHandler/ └── TriggerHandler.cls
.cls-meta.xml は必ずクラスとペアで移動します。 移動はすべて単純な rename なので、git status で全容が見え、git checkout . で取り消せます。
タグが宣言、ファイルシステムが現実
3 つのコマンドが、宣言と現実のズレをそれぞれ一方向に解消します。
check比較のみ
宣言と現実のズレを検出し、あれば exit 1。CI や pre-commit に置いて、階層の崩れを機械的に止めます。
arrangeタグ → 配置
retrieve のあとに。タグの示すディレクトリへファイルを移動します。移動先が埋まっていれば決して上書きせず、報告してスキップします。
stamp配置 → タグ
既存プロジェクトへの導入時に。いまの配置を全クラスの doc コメントに一度だけ書き込みます。意図的な git mv のあとにも。
Apex Stem の全クラスは刻印済み
Apex Stem の 4 フレームワーク (ApexEloquent v3.7.0 / ApexBlueprint v2.1.0 / ApexTrace v1.5.0 / ApexTools v1.1.0 以降) は、 全クラスが @directory タグを持った状態で配布されています。 Unlocked Package でインストールしても、retrieve して arrange を 1 回叩けば、 submodule 導入とまったく同じ階層になります。