コンテンツにスキップ

@ritsubi/contract generated 配置移行設計と実施履歴

目的

@ritsubi/contract の codegen 生成物を packages/contract/generated/ に置き、src/ 直下の generated artifact 例外をなくす。

現行では packages/contract/generated/*.ts を tracked 正本として扱う。runtime / codegen の安定性を壊さずに、package root ベースの公開面で維持する。

実施状況

  • 完了:
  • Phase 0: package root entrypoint（index.ts / paths.ts / validation/common.ts）を追加
  • Phase 1: consumer の source alias を packages/contract/src から package root へ切替
  • Phase 2: codegen 正本を packages/contract/generated/*.ts へ移動
  • Phase 3: packages/contract/src/index.ts / src/paths.ts の互換層を削除
  • 継続運用:
  • packages/contract/generated/*.ts を tracked 正本とする
  • src/ 配下の emitted JS / declaration artifact は tracked 正本にしない
  • 別件として残るもの:
  • ritsubi-vendure-server:codegen の flaky は @ritsubi/plugins build / dist 解決系の不安定として別トピックで扱う

現行状態

  • tracked 正本:
  • packages/contract/generated/*.ts
  • package 公開面:
  • packages/contract/package.json の main / types / exports は dist/ を正本にする
  • compile-time alias:
  • root tsconfig.json
  • apps/storefront/tsconfig.json
  • apps/vendure-server/tsconfig.typecheck.json
  • packages/plugins/tsconfig*.json などが packages/contract/src を直接参照している
  • runtime / codegen:
  • vendure-server は runtime と tsx 実行の都合で dist 正本を維持する必要がある

最終形の方針

公開面

  • 手書き契約: packages/contract/src/**
  • generated 正本: packages/contract/generated/*.ts
  • workspace 向け source entrypoint: packages/contract/ 直下
  • index.ts
  • paths.ts
  • validation/common.ts
  • runtime / package export: dist/

目標

  • consumer が packages/contract/src を alias 正本として見ない状態にする
  • generated の物理配置を src/ 外へ移し、src artifact guard と整合させる
  • @ritsubi/contract/paths の runtime 振る舞いは維持する

非目標

  • @ritsubi/contract を別 package に分割しない
  • runtime / codegen を source 直接解決に寄せない
  • vendure-server の runtime / typecheck 分離を今回なくさない

推奨移行フェーズ

Phase 0: package root entrypoint を追加する

目的

consumer 側が src/ を直接見なくても source 解決できる土台を先に作る。

変更対象

  • packages/contract/index.ts（新設）
  • packages/contract/paths.ts（新設）
  • packages/contract/validation/common.ts（新設）
  • packages/contract/tsconfig.json
  • packages/contract/tsconfig.build.json
  • packages/contract/project.json
  • 必要に応じて packages/contract/package.json

受け入れ条件

  • pnpm exec nx run @ritsubi/contract:codegen
  • pnpm exec nx run @ritsubi/contract:build
  • pnpm exec nx run @ritsubi/contract:typecheck
  • @ritsubi/contract/paths の runtime 解決が変わらない

Phase 1: source alias を src/ から package root へ切り替える

目的

generated 移動前に、consumer 側の src 直依存を断つ。

主な変更対象

  • tsconfig.json
  • apps/storefront/tsconfig.json
  • apps/vendure-server/tsconfig.typecheck.json
  • packages/plugins/tsconfig.json
  • packages/plugins/tsconfig.typecheck.json
  • packages/sdk/shop/tsconfig.json
  • apps/storefront/vite.config.ts
  • apps/storefront/vitest.config.ts
  • apps/storefront/playwright.ct.config.ts
  • apps/vendure-server/vitest.integration.config.ts
  • packages/plugins/vitest*.ts

変更方針

  • @ritsubi/contract → packages/contract/index.ts
  • @ritsubi/contract/* → packages/contract/*

受け入れ条件

  • grep で packages/contract/src を alias 正本にしている consumer 設定が解消される
  • storefront / plugins / vendure-server の typecheck / build / test alias が維持される

Phase 2: generated を src/ から generated/ へ移動する

目的

tracked codegen 正本を src/ 外へ出し、artifact ルールと一致させる。

主な変更対象

  • packages/contract/codegen.ts
  • packages/contract/index.ts
  • packages/contract/tsconfig.json
  • packages/contract/tsconfig.build.json
  • packages/contract/project.json
  • nx.json
  • .github/workflows/_ci-pr-core-quality.yml
  • scripts/dev/ci-local.sh
  • scripts/hooks/hook-common.sh
  • .oxfmtrc.json
  • AGENTS.md
  • packages/contract/AGENTS.md
  • docs/development-guide.md
  • docs/development-standards.md

変更方針

  • codegen 出力先を src/generated/*.ts から generated/*.ts へ変更
  • root entrypoint の generated export を ./generated/*.js に切替
  • Nx / CI / hook の outputs / clean-check を新パスへ追従

受け入れ条件

  • packages/contract/src/generated/** が再生成されない
  • packages/contract/generated/*.ts が codegen 正本として更新される
  • pnpm run lint:tracked-src-artifacts が通る
  • dependent build / codegen / typecheck が維持される

Phase 3: 互換層を掃除する

目的

移行後に不要になった src 前提の互換コードとコメントを消す。

受け入れ条件

  • workspace 全体で packages/contract/src を alias 正本として参照しない
  • package root entrypoint が source 正本として定着している

リスク

  1. @ritsubi/contract/paths の runtime パス解決が崩れる
  2. Vite / Vitest / Playwright の alias と tsconfig paths が不整合になる
  3. Nx outputs と CI clean-check の更新漏れで false red が出る
  4. vendure-server の runtime/dist と typecheck/source の分離を壊す

ロールバック方針

  • Phase 0 失敗時:
  • package root entrypoint の追加を戻す
  • Phase 1 失敗時:
  • alias 設定群のみ元へ戻す
  • Phase 2 失敗時:
  • codegen 出力先を src/generated/*.ts に戻す
  • CI / hook / docs の参照パスを戻す

検証コマンド

pnpm exec nx run @ritsubi/contract:codegen
pnpm exec nx run @ritsubi/contract:build
pnpm exec nx run @ritsubi/contract:typecheck
pnpm -C packages/plugins build
pnpm exec nx run ritsubi-vendure-server:codegen
pnpm exec nx run ritsubi-vendure-server:typecheck
pnpm exec nx run ritsubi-vendure-server:build
pnpm run lint:tracked-src-artifacts

現行運用との関係

この文書は移行設計であり、現行正本を直ちに変更するものではない。移行着手までは以下を維持する。

  • packages/contract/generated/*.ts を tracked 正本とする
  • src/ 配下の *.js / *.d.ts / *.map は tracked 正本にしない

移行の各フェーズで green を確認しながら、現行ルールを段階的に置き換える。