component-wiring-check

コンポーネント配線チェック

Datex Studio ブランチ上のコンポーネント間参照の契約を監査します。あるコンポーネントから別のコンポーネントへの参照（グリッドをマウントするハブタブ、セレクターを指すハブフィルター、データソースを指すグリッドの datasourceConfig、データソースをバックエンドとするセレクター、$shell.<Package>.open<referenceName>Dialog 経由で開くフォーム）が、契約を完全に満たしているかを検証します。これは読み取り専用の監査スキルです。設定を読み取り、検出事項を報告し、修正を該当する作成スキルに引き継ぎます。ブランチ上の設定を変更することはありません。

関連項目： 作成スキル（hub-creator、grid-creator、form-creator、editor-creator、selector-creator）— 監査で検出された修正のラウンドトリップとプッシュの手順は、それぞれのスキルが担当します。

参照資料

• ../datex-studio-shared/branch-setup.md — ブランチ／接続の選択（スキル間で共有）
• references/component-wiring.md — 配線ルールの正式な参照資料：3 つのサイレント失敗の落とし穴、moduleId ルール、configParameters と inParams のミラーリング、vars／rowVars の宣言ルール
• ../datex-studio-conventions/defaults.md — 新しいコンポーネントのデフォルトパッケージ（既存コンポーネントへの参照には適用されません。両者を混同しないことが重要です）
• ../tailoring-overlay/ — オーバーレイ固有のシャドウマーカールール（「インポート時の契約が古い」という症状は、配線の問題とは別のテーラリング上の問題です）

依存関係

• grid-creator／hub-creator／form-creator／editor-creator／selector-creator スキル — この監査で適用すべき修正が検出された場合、下流で呼び出されます（このスキルは検出事項を報告し、作成スキルがラウンドトリップとプッシュを行います）
• tailoring-overlay スキル — ベースコンポーネントの配線のずれではなく、テーラリングされたオーバーレイで「契約が古い」という症状が見られる場合に呼び出されます
• post-edit-verification／component-validator スキル — 修正が反映された後、適用した作成スキルによって呼び出されます（この監査から直接呼び出すことはありません）

CLI のライフサイクル

コンポーネント配線の監査は読み取り専用です。設定を取得して契約を調べますが、変更をプッシュすることはありません。dxs componentwiringcheck サブコマンドはありません。監査では汎用の dxs configuration get／list プリミティブを使って、比較に必要なコンポーネントを取得します。

検査用に単一のコンポーネントを取得する：

# 1. Fetch — note the envelope wrapper
dxs configuration get <type> <configId> -b <branchId> -O envelope.json
# 2. EXTRACT THE INNER BODY (same envelope-vs-body distinction as the creator skills)
jq .json envelope.json > body.json
# 3. Inspect — read inParams, configParameters, moduleId, vars, rowVars

ブランチ上の候補を見つける：

# List configs of a given type — filter to the components you want to audit
dxs configuration list <type> -b <branchId>

監査で検出された修正は、該当する作成スキル（hub-creator、grid-creator など）が適用します。このスキルがラウンドトリップのルール（get -O envelope.json → jq .json → 編集 → upsert）を担当します。このスキルから dxs configuration upsert を呼び出すことはありません。これを使おうとしている場合は、代わりに作成スキルに引き継いでください。

ワークフロー

[Phase 1: Setup + target components]
Follow branch-setup.md for branch/connection selection
        |
Identify the reference under audit:
  - referencing component (the caller — hub, grid, form, ...)
  - target component (the callee — grid, selector, datasource, form, ...)
  - the reference site (hub filter, hub tab, grid datasourceConfig,
    selector datasource, dialog opener)
        |
[Phase 2: Audit reference contracts]
Walk the three silent-failure traps (see references/component-wiring.md):
  1. moduleId matches the target's package?
  2. configParameters mirrors target inParams one-to-one
     (no missing, no extras)?
  3. vars / rowVars declares every $<component>.vars.<id> /
     $row.vars.<id> used in flow code?
Cross-check tailored overlays separately (see tailoring-overlay)
        |
[Phase 3: Report findings]
For each trap that fires, surface:
  - what's broken (target id / inParam / var)
  - which component file owns the fix (caller vs callee)
  - which creator skill applies it
NO `dxs configuration upsert` from this skill — defer to the
creator skill that owns the component being edited
        |
[Phase 4: Re-audit (optional, after fixes land)]
Re-fetch the same configs and walk the three traps again.
Clean run = no findings.

フェーズの詳細

フェーズ 1：セットアップと対象コンポーネント

1. ブランチと接続の選択については、../datex-studio-shared/branch-setup.md に従ってください。ブランチ ID を決めつけないでください。ユーザーに確認を求めてください。
2. 参照元を特定します。 配線の監査は、必ず特定のコンポーネントのペア（またはチェーン）を対象とします。次の項目を確認してください。
   • 参照元コンポーネント（呼び出し元）：グリッドをマウントするハブ、datasourceConfig がデータソースを指すグリッド、データソースがドロップダウンの候補を提供するセレクター、$shell.<Package>.open<referenceName>Dialog(...) を介してフォームを開くアクション。
   • 参照先コンポーネント（呼び出し先）：参照を受ける側のグリッド、セレクター、データソース、フォーム、またはエディター。
   • 参照箇所：ハブのフィルター（→ セレクター）、ハブのタブの contentConfig（→ グリッドまたはその他のコンポーネント）、グリッドの datasourceConfig（→ データソース）、セレクターの datasourceConfig（→ データソース）、アクション層のダイアログ呼び出し元（→ フォーム／エディター）。
3. dxs configuration get <type> <configId> -b <branchId> -O envelope.json を使って両方のコンポーネントを取得し、それぞれについて jq .json を使って body.json を抽出します。この監査では本文を読み取ります。このスキルによって編集が加えられることはありません。

フェーズ 2：参照コントラクトを監査する

3 つの落とし穴を順番に確認します。それぞれの詳細は references/component-wiring.md に記載されています。以下は監査チェックリストです。

1. moduleId がターゲットのパッケージと一致している。 すべての参照箇所で、moduleId フィールドにはターゲットが属するパッケージを指定します。呼び出し元のパッケージでも、機能フォルダー名でもありません。ターゲットコンポーネントのファイルを開き、パッケージ宣言を直接確認してください（明確でない場合はユーザーに確認してください）。機能フォルダー名や、新しいコンポーネントに対する Utilities の既定値から推測しないでください。この既定値が適用されるのは新しいコンポーネントであり、既存コンポーネントへの参照ではありません。references/component-wiring.md → Cross-Component References Use the Target's Module を参照してください。

2. configParameters がターゲットの inParams を 1 対 1 で反映している。 2 つの配列を比較します。

   • ターゲットの inParams の各エントリについて、参照側の configParameters に一致するエントリ（同じ id／type／isCollection）があることを確認します。未使用のパラメーターも、明示的な value: null／"" とともにコントラクトに残します。エントリが欠けていると、実行時に未定義の入力がエラーなく表面化し、ドロップダウンが空になったり、リストのフィルターが正しく適用されなかったりします。
   • configParameters の各エントリについて、ターゲットの inParams にその id が宣言されていることを確認します。余分なエントリは配線されていない設定です。値はエラーなく破棄され、呼び出し元はデータが渡されていると思い込む一方で、ターゲットには届きません。こちらの方向の不一致のほうが危険です。このルールは、ターゲットの inParam の required: true/false にかかわらず適用されます。

   ターゲットの構成が呼び出し元の必要とする内容に合わない場合（たとえば、ハブがグリッドを project_ids で絞り込みたいのに、グリッドにその inParam がまだ宣言されていない場合）は、呼び出し元に見せかけのエントリを追加するのではなく、ターゲットを拡張してください。references/component-wiring.md → Reference Contracts Include Every Target inParam を参照してください。

3. Vars／rowVars が宣言されている。 フローコードで読み取りまたは書き込みを行う各 $<component>.vars.<id>（$form.vars、$hub.vars、$editor.vars、$grid.vars）について、コンポーネントのトップレベルの vars[] 配列に一致するエントリがあることを確認します。グリッドの場合はさらに、行フロー（on_save_new_row、on_save_existing_row など）内で使用する各 $row.vars.<id> に対し、グリッドの rowVars[] に一致するエントリがあることを確認します。どちらの配列でも、inParam と同じ形式の記述子を使用します。references/component-wiring.md → Component Variables Must Be Declared を参照してください。

4. テーラリング済みオーバーレイは別の問題です。 症状が実行時の不整合ではなく「インポート時のコントラクトが古い」場合、原因はベースコンポーネントの配線の不整合ではなく、テーラリング済みオーバーレイのシャドーマーカーの不整合です。tailoring-overlay スキルに引き継いでください。

フェーズ 3：調査結果を報告する

各トラップが発生した場合は、破損した契約と修正を担当するスキルを組み合わせて、調査結果をまとめます。

トラップ	報告する内容	修正を担当するスキル
moduleId の不一致	呼び出し元コンポーネント + 参照箇所 + 観測された moduleId + 対象の実際のパッケージ	呼び出し元のクリエータースキル（参照は呼び出し元側にあります）
configParameters エントリの不足	呼び出し元コンポーネント + 参照箇所 + ミラーに存在しない対象の inParam id	呼び出し元のクリエータースキル
configParameters エントリの余分な追加	呼び出し元コンポーネント + 参照箇所 + 余分な id + 判断：呼び出し元のエントリを削除するか、対象の inParams を拡張するか	削除する場合：呼び出し元のクリエータースキル。拡張する場合：対象のクリエータースキル。
宣言されていない vars / rowVars	コンポーネント + フローコードで観測された var id + vars[] / rowVars[] に宣言がないこと	フローコードを所有するコンポーネントのクリエータースキル

このスキルでは修正を反映しません。 調査結果を提示し、各修正を担当するクリエータースキルを示したら終了します。クリエータースキルにはラウンドトリップのルール（dxs configuration get -O envelope.json → jq .json envelope.json > body.json → 編集 → dxs configuration upsert）が定められています。監査スキル内から修正を適用すると、この契約を迂回し、設定内容を気づかないうちに破損させるおそれがあります。

フェーズ 4：再監査（任意）

修正が反映されたら、同じコンポーネントを再取得し（dxs configuration get <type> <configId> -b <branchId> -O envelope.json、jq .json で抽出）、3 つのトラップをもう一度確認します。問題がなければ、調査結果はありません。再監査は簡単です。修正が複数のコンポーネントファイルに影響する場合や、最初の監査で 2 件を超える調査結果があった場合は、必ず実施してください。呼び出し元と対象が同時に更新されなかった場合、同じ編集でドリフトが再発する可能性があります。

サイレント障害の症状 — 診断インデックス

既知の契約違反ではなく症状が報告された場合、この表を使って、最初に監査すべきトラップを特定します。仕組みについては references/component-wiring.md を参照してください。

症状	考えられる原因
ドロップダウンが空	セレクターのデータソースに未定義の入力が渡されています（マウント箇所に configParameters エントリがありません）
ドロップダウンに誤った選択肢が表示される	セレクターに実際の inParam の誤った値が渡されています（バインディング式が誤っているか、余分な configParameters エントリが実際のエントリを上書きしています）
グリッドフィルターが機能しない	Hub のフィルター値がグリッドに届いていません（余分な configParameters エントリがある、またはグリッドで inParam が宣言されていません）
Hub のフィルターがタブに反映されない	タブの configParameters にエントリがないか、グリッドに inParam がありません
ダイアログが開かない	$shell.<Package>.open<referenceName>Dialog で誤ったパッケージが使われています（対象フォームのパッケージではありません）
コンポーネントは解決されるが、動作がおかしい	参照の moduleId が誤っています
フローコードで Var が未定義になる	トップレベルの vars[] に宣言がありません（グリッド行のフローでは rowVars[] に宣言がありません）
インポート時に「Outdated contract」と表示される	Tailored overlay の shadow がベースからドリフトしています — tailoring-overlay に引き継いでください

事前チェックリスト

コンポーネント間の参照を監査するときは、こちらを確認してください。チェックリストの完全版はreferences/component-wiring.mdにあります。簡易版は以下のとおりです。

1. moduleId が対象のパッケージと一致している — 対象コンポーネントのファイルを読むか、ユーザーに確認して確かめます。機能フォルダーやUtilitiesの新規コンポーネントのデフォルト値から推測してはいけません。
2. configParameters が対象のinParamsと1対1で一致している — すべてのinParamにエントリーがあり（未使用のものにはvalue: null / ""を設定）、余分なエントリーがないことを確認します。
3. 対象が呼び出し元の必要とする内容に追いついていない場合、呼び出し元に架空のエントリーを追加するのではなく、同じ編集で対象を拡張して修正します。呼び出し元のconfigParametersには、対象が実際に受け付ける内容だけを記述します。
4. フローコードに記述されたすべての$<component>.vars.<id>が、コンポーネントのトップレベルのvars[]配列で宣言されています。
5. グリッドのrowVars[]で、行フローが読み書きするすべての$row.vars.<id>を宣言します。
6. ダイアログのオープナーでは、対象フォームのパッケージを使用します — $shell.<TargetPackage>.open<referenceName>Dialog(...)。<referenceName>はsnake_caseにします（camelCaseは使用しません）。

よくある間違い

間違い	修正方法
moduleIdに対象ではなく呼び出し元のパッケージを設定している	対象コンポーネントファイルのパッケージ宣言を直接読むか、ユーザーに確認します。機能フォルダーを見てはいけません。Utilitiesのデフォルト値も使用しません。
機能フォルダー名からmoduleIdを推測している	機能フォルダーには複数のパッケージが混在します — FootprintManagerのハブとCarriersのセレクターが隣り合っていることもあります。パッケージはコンポーネントごとの属性であり、フォルダーごとの属性ではありません。
タブのconfigParametersが、グリッドでinParamとして宣言されていないIDをバインドしている	バインドが実行時に黙って破棄される、無効な配線です。バインドを削除するか、grid-creatorを使って同じ編集でグリッドのinParams（および基盤となるデータソース）を拡張します。
対象で宣言されているinParamに対するエントリーが、呼び出し元のconfigParametersにない	対象が未定義の入力を黙って解決するため、ドロップダウンが空になったり、リストが誤ってフィルタリングされたりします。エントリーを追加します。呼び出し元でバインドする意図がない場合は、value: null / ""を使用します。
<id>をトップレベルのvars[]に宣言せずに、$form.vars.<id> = ...（または$hub.vars.* / $editor.vars.* / $grid.vars.*）に書き込んでいる	型付きの公開領域にない変数です — インポートで形状が検証されず、下流のコードもそれを前提にできません。すべての変数を宣言してください。
<id>をrowVars[]に宣言せずに、グリッドの行フローで$row.vars.<id>に書き込んでいる	同じ落とし穴の、行スコープ版です。rowVars[]に宣言します（記述子の形式はvars[]と同じです）。
ダイアログのオープナーで、対象フォームではなく呼び出し元のパッケージを使用している	$shell.<Package>.open<referenceName>Dialog(...) — <Package>はフォームのパッケージ、<referenceName>はsnake_caseです。
この監査スキル内で修正を適用し、対応するクリエータースキルを使っていない	このスキルは読み取り専用です — 監査は行いますが、変更は加えません。修正はhub-creator / grid-creator / form-creator / editor-creator / selector-creatorに依頼してください。これらのスキルが、安全なプッシュのためのラウンドトリップルールを管理します。
「インポート時の古いコントラクト」と配線のずれを混同している	その症状は実行時の配線の問題ではなく、テーラリングされたオーバーレイのシャドーマーカーのずれです。tailoring-overlayに引き継いでください。

監査で指摘事項が見つかったら、各指摘に対応するクリエータースキル（grid-creator、hub-creatorなど）に依頼して修正を適用してください。修正が反映された後、このスキルを再実行して、問題なく完了することを確認します。