機能仕様書: Node/Unityパッケージversion不一致検出

[akiojin]

Spec

機能仕様書: Node/Unityパッケージversion不一致検出

機能ID: SPEC-f9db125c
作成日: 2025-12-17
ステータス: 実装完了
入力: ユーザー説明: "Node/Unityのバージョンが一致しない場合、警告またはエラーを表示してもらいたい。"

ユーザーシナリオ＆テスト (必須)

ユーザーストーリー1 - 不一致時に警告を出して継続 (優先度: P1)

Node側パッケージとUnity側パッケージのversionが一致しない場合、ユーザーがすぐ気づけるように警告を表示したい。ただし作業を継続できるよう、デフォルトは「警告のみ」とする。

この優先度の理由: バージョン齟齬はツール不具合の典型原因であり、早期に気づけることがユーザー体験に直結する。一方で、ユーザーが意図的に組み合わせを試すケースもあるため、デフォルトで実行を止めない。

独立テスト: Unity応答に含まれるpackage versionがNode側のversionと異なる場合に、警告ログが1回出力され、コマンド結果は成功すること。

受け入れシナリオ:

1. 前提 Node/Unityが接続済み、実行 任意のコマンドを実行、結果 version不一致が検出され警告が出力される（実行は継続する）
2. 前提 すでに1回不一致警告が出ている、実行 別コマンドを実行、結果 同一接続中は同じ警告が繰り返し出ない

---

ユーザーストーリー2 - 不一致時に即エラー（fail fast） (優先度: P1)

運用ポリシーとして「不一致は危険」と判断するユーザー向けに、不一致が検出された時点でコマンドを失敗させたい。

この優先度の理由: 互換性が崩れると誤動作の原因になりうるため、CI/本番運用では早期失敗が有効。

独立テスト: UNITY_CLI_VERSION_MISMATCH=error の場合に、最初の検出でエラー（識別可能なcode）になり、以後のコマンドも同様に失敗すること。

受け入れシナリオ:

1. 前提 UNITY_CLI_VERSION_MISMATCH=error、実行 任意のコマンドを実行、結果 version不一致を理由に失敗する
2. 前提 不一致により失敗済み、実行 別コマンドを実行、結果 同じ理由で即時失敗する

---

ユーザーストーリー3 - チェックの無効化 (優先度: P2)

特殊な検証や互換性検証のために、versionチェックを無効化したい。

この優先度の理由: デバッグ/検証用途での柔軟性を確保する。

独立テスト: UNITY_CLI_VERSION_MISMATCH=off の場合に、不一致でも警告もエラーも出ないこと。

受け入れシナリオ:

1. 前提 UNITY_CLI_VERSION_MISMATCH=off、実行 任意のコマンドを実行、結果 version不一致でも警告・エラーが出ない

---

エッジケース

• Unity応答にversion情報が含まれない場合、チェックは実行できない（警告/エラーは出ない）
• Unity応答のversionが "unknown" の場合、チェックは実行しない
• version情報の格納場所が異なる（例: version / editorState.version）場合でも検出できる

要件 (必須)

機能要件

• FR-001: システムはNode側パッケージversionとUnity側パッケージversionの不一致を検出できる必要がある
• FR-002: システムは不一致時の挙動を warn / error / off から選択できる必要がある
• FR-003: デフォルト挙動は warn（警告のみ）である必要がある
• FR-004: error の場合、不一致を識別できるエラーコードを提供する必要がある
• FR-005: 警告/エラーはユーザーが解決策（どちらを更新すべきか）を理解できる内容である必要がある

成功基準 (必須)

測定可能な成果

• SC-001: 不一致がある状態でユーザーが気づけずに調査に時間を使うケースが減る
• SC-002: error 設定により、不一致状態での運用を確実に防止できる

Plan

実装計画: Node/Unityパッケージversion不一致検出

機能ID: SPEC-f9db125c | ステータス: 実装完了

概要

Node側とUnity側のパッケージversionを比較し、不一致時に警告またはエラーを出す。挙動は環境変数で warn / error / off を切り替える。

実装状況

• ✅ Node: UNITY_CLI_VERSION_MISMATCH を設定として追加
• ✅ Node: Unity応答に含まれるversionを受信し、不一致を検出して通知
• ✅ Unity: 応答に含めるpackage version取得の安定性を向上
• ✅ Tests: 代表ケース（warn/error/off相当）のユニットテスト追加
• ✅ Docs: 設定項目の追加

---

本ドキュメントは実装完了後に作成されました

Tasks

タスク: Node/Unityパッケージversion不一致検出

機能ID: SPEC-f9db125c | ステータス: 完了

完了済みタスク

• 不一致時の挙動（warn/error/off）を定義
• Node側でversion不一致を検出して警告/エラーを出力
• Unity側でpackage version取得の安定性を改善
• ユニットテスト追加（代表ケース）
• 設定ドキュメント更新

---

本ドキュメントは実装完了後に作成されました

TDD

TODO

Research

TODO

Data Model

TODO

Quickstart

TODO

Contracts

Artifact files under contracts/ are managed in issue comments with contract:<name> entries.

Checklists

Artifact files under checklists/ are managed in issue comments with checklist:<name> entries.

Acceptance Checklist

• Add acceptance checklist