impact-analysis

影響分析

Datex Studio ブランチで設定を変更または削除する際の影響を評価します。このスキルは依存関係のみを分析し、変更は行いません。

使用するタイミング

• 設定の入出力パラメーターを変更する前
• ブランチから設定の名前を変更または削除する前
• ストレージに required: true フィールドを追加する前、またはストレージの列の形状を変更する前
• その他、契約を破壊する変更を行う前
• 呼び出し元のスキルが契約変更の安全性を確認する必要がある場合。例：
  • function-creator — 関数の入出力パラメーターを変更する前
  • datasource-creator — データソースの形状を変更する前
  • storage-creator — 列の名前を変更または削除する前、あるいは必須フィールドを追加する前
  • type-definition-creator — _dd / i_* / e_* 型を削除または再構成する前
  • db-query / action-creator — ストレージスキーマを変更する前、または契約に関するバグを診断するとき

ワークフロー

ブランチの選択。 ブランチ／接続の選択には ../datex-studio-shared/branch-setup.md に従ってください。ブランチ ID を決めつけず、必ずユーザーに確認するか、最初にフィーチャーブランチを一覧表示してください。

Step 1: 呼び出し元を見つける

dxs source explore reverse-trace <reference_name> --branch <branch_id>

これにより、対象を参照しているすべての設定が返されます。設定の種類がわかっている場合は、--type <type> を使うと検索を高速化できます（例：--type flow、--type datasource）。

Step 2: 結果を解釈する

参照している設定を種類ごとに分類します。

• フロー／関数 — $flows.* を介して対象を呼び出します
• データソース — $datasources.* を介して参照します
• フォーム／グリッド／エディター — 対象にバインドされる UI コンポーネントです
• レポート — $reports.* を介して参照します

ストレージ列の名前変更、削除、または必須フィールドの追加を行う場合は、呼び出し元をさらに次のように分類します。

• 書き込み側の呼び出し元 — ストレージに対して insert / update / patch を行う設定です（必須フィールドまたは名前変更の際に最もリスクが高く、ストレージの変更と同時に更新しないと実行時に失敗します）
• 読み取り側の呼び出し元 — ストレージをクエリまたは読み取るだけの設定です（リスクは低く、フィルターやプロジェクションに古いフィールド名が残る可能性があります）

参照が曖昧な呼び出し元（たとえば、参照のように見えるもののインラインコンテンツの可能性もある文字列リテラル）は、実際の呼び出し元として数えず、「要確認」として扱います。呼び出し元のスキルまたはユーザーが曖昧さを解消できるようにしてください。

列単位の詳細度（ストレージの形状変更）。 reverse-trace は設定レベルのエッジを報告します。つまり、どの設定がストレージに書き込むかはわかりますが、各設定がどの列を設定するかはわかりません。特定の列を変更する場合（名前変更、削除、または required: true の設定）は、ブランチから各書き込み側の呼び出し元の本文を取得し（dxs source explore config <caller_ref> --branch <id>）、埋め込みコード内の $db.<Pkg>.<storage>.insert/update/patch ペイロードで対象の列を確認してください。これにより、ローカルツリーを検索せずに、設定レベルのトレースだけでは得られない列単位の書き込み側分析を行えます。

Step 3: 判断ゲート

• 呼び出し元が見つからない — 安全に進められます。呼び出し元のスキル／ユーザーに伝えてください。
• 呼び出し元が存在する — 次の情報を含む完全な一覧をユーザーに提示します。
  • 各呼び出し元の参照名と種類
  • どのような問題が起きるか（例：「この 3 つのフローは 2 つの引数で fn_sum を呼び出しています。引数を 3 つに変更すると、これらは動作しなくなります」）
  • 続行する前に、明示的な確認を求めます

Step 4: 呼び出し元に結果を返す

判断結果を呼び出し元のスキルに報告します。

• 安全 — 呼び出し元はありません。変更を進めてください
• 承認済み — 呼び出し元は存在しますが、ユーザーが承認しました。呼び出し元のスキルは変更の一環として、影響を受けるすべての呼び出し元を更新する必要があります
• 却下 — ユーザーは続行しないことを決定しました

追加コマンド

コマンド	使用するタイミング
dxs source explore trace <name> --branch <id>	対象が何に依存しているかを把握する場合（順方向の依存関係）
dxs source explore graph <name> --branch <id>	依存関係の全体像を可視化する場合（両方向）

対象範囲の境界

• このスキルは分析のみを行い、設定を変更することはありません
• 影響を受ける呼び出し元の更新は、呼び出し側のスキルが担当します
• 参照名の変更は対象外です。削除して再作成する必要があるため、手動での操作としてユーザーに伝えてください
• 1 階層のみです。 対象の直接の呼び出し元を報告してください。推移的な影響（「この関数は X から呼び出され、X は Y から呼び出される」など）を追跡しないでください。推移的な分析を行うかどうかは、呼び出し側のスキルまたはユーザーが判断します。呼び出し関係の全体を確認する必要がある場合は、代わりに dxs source explore graph <name> --branch <id> を使用してください。
• 曖昧な一致を推測で判断しないでください。 参照が曖昧な場合（文字列リテラルか実際のバインディングか、コメントか設定フィールドかなど）は、実際の呼び出し元として分類せず、確認が必要な項目として示してください。
• 呼び出し元が 0 件なら終了してください。 reverse-trace が呼び出し元を返さない場合は、その旨を明確に報告して終了してください。似た参照名を提案したり、検索範囲を広げたりしないでください。