feat(content-references): reference フィールドを参照先コンテンツへ展開するパッケージを追加

[atsushifujikawa]

概要

reference フィールドの参照先を展開するパッケージ @craft-cross-cms/content-references を追加します。

設計の経緯と Craft Studio 側の利用計画: plaidev/karte-io-systems#170508（設計コメント: https://github.com/plaidev/karte-io-systems/issues/170508#issuecomment-5633998193）の PR0 に相当します。

背景

xcms の配信 API は reference フィールドを参照先 ID（multiple なら ID の配列）のまま返します。CDN API 自体に depth を持たせるとフォーマット・asset 解決の再帰と client/server 契約が増えるため、CDN は薄いまま、「参照先をどう展開するか」のルールと実装を SDK パッケージとして 1 箇所に置き、管理画面・サイト生成（Craft Studio）・利用者のコードで共有します。

内容

• buildCmsReferencePlan(fields): 管理 API が返すモデル定義の fields から、reference フィールドの plan（field / refModel / multiple）を導出。refModel が無いフィールドは対象外
• resolveCmsReferences(items, plan, { fetchByIds, chunkSize?, concurrency? }): ID をモデルごとに収集・重複排除し、$in 上限の 50 件ずつ・同時実行数 4 で fetchByIds を呼び、参照先コンテンツを書き戻す
• 解決ルール（README「Resolution rules」が正本）
  • 単一参照: 参照先コンテンツ。未公開・削除など取得できなければ null（ID は残さない）
  • multiple: 元の順序の配列。取得できない要素は落とす。null / 未設定は []
  • 参照先の中の reference は ID のまま（1 階層のみ、再帰しない）
  • fetchByIds が throw したら全体 reject（部分結果を返すと「未公開」と区別できないため）
  • 入力は変更しない
• 依存ゼロ・fetch 注入なので Node / ブラウザ両対応。rich-text-core と同じ tsup の ESM / CJS dual ビルド
• changeset（patch → 0.0.1）、ルート README / CLAUDE.md にパッケージを追記

検証

• pnpm lint（eslint / knip / secretlint / prettier）、pnpm build、pnpm test（18 tests）すべて通過
• ビルド成果物を ESM (import) / CJS (require) の両方から読み込んで動作確認

確認したい点

• パッケージ名 @craft-cross-cms/content-references で問題ないか
• 「multiple で取得できない要素は落とす」（null を残さない）で問題ないか

🤖 Generated with Claude Code

https://claude.ai/code/session_01Lo53z71NvuSbRrZ82nW6eY

[atsushifujikawa]

方針転換のためクローズします。depth 解決のロジックは obel の @craft-studio/runtime-utils/collection に置き、web-api と builder（生成サイト）で共有する形にします。

理由:

• 一般ユーザーが自前実装できる範囲の utils だけを公開してもメリットがほぼ無く、使われるとメンテ負荷が増える
• ロジックは本来 systems/cms 側に置きたいが、特定 system の内部パッケージ（@plaidev/*）を他 system に公開する運用は現状想定されていない
• builder が解決できる形にするには @plaidev/* パッケージでも追加対応が要る
• @craft-cross-cms/* を増やすには社内プロセスを通す必要がある可能性がある

設計の正本: plaidev/karte-io-systems#170508 の設計コメント（更新予定）