grid-validator

Grid Validator

単一の Datex Studio グリッドファイル（*-grid.json）を、グリッド固有の作成ルールに照らして監査します。grid-creator がグリッドを作成または変更した後、ブランチに変更をアップサートする前に行う必須の最終ゲートです。このスキルはグリッド専用です。汎用の component-validator では検出できない注意点（エンベロープと本文の形状、テキスト表示の強制変換、5 か所での動的フィルターの同期、命令型セル API の不一致、テーラリング済みかカスタムかの出自）を扱います。グリッド以外のコンポーネントファイルには、代わりに component-validator を使用してください。

このバリデーターは読み取り専用で、編集は行いません。構造化された修正項目リスト（Blockers / Warnings / Nits）を返します。書き換えは行いません。修正は親（通常は grid-creator、またはユーザー自身）が担当します。

関連項目： component-validator — グリッド以外のコンポーネントファイル（actions、functions、forms、editors、hubs、storage、selectors、customTypes、backendTests、datasources）を対象とする汎用ディスパッチャーです。grid-validator を利用できない場合、グリッドについては grid-creator/references/grids.md を参照します。ただし、この汎用ディスパッチャーには、以下に示すグリッド固有の注意点は含まれていません。

関連項目： component-wiring-check — コンポーネント間の参照契約（あるコンポーネントから別のコンポーネントへの参照）を確認します。このバリデーターは、単一のグリッドファイルのみを個別に監査します。そのファイル内で確認できる明らかな配線のずれ（例：ファイル自身の inParams を反映していない configParameters ブロック）は指摘しますが、外部参照を追跡することはありません。

References

• ../grid-creator/references/grids.md — 権威あるグリッドリファレンス（エンベロープの形状、列、データソース、queryOptions、動的フィルター、命令型セル API）
• ../tailoring-overlay/references/tailoring.md — グリッドがテーラリング済みのバリアント（tailored_*-grid.json）である場合の、オーバーレイのシャドーマーカーのルール
• ../datasource-creator/references/odata-datasources.md — datasources[0] に埋め込まれたバックエンドデータソースの OData エンベロープルール
• ../datasource-creator/references/flow-datasources.md — フローベースのデータソースのエンベロープルール（グリッドが OData ではなく関数をバックエンドに使用する場合）
• ../component-wiring-check/references/component-wiring.md — configParameters と inParams のミラールール、および moduleId の適合性
• ../datex-studio-conventions/file-format.md — configurationTypeId の表、1 行の最小化 JSON ルール、TypeScript 式のエンコード（'literal' の引用、バッククォートでのラップ）
• ../datex-studio-conventions/naming-conventions.md — サフィックスの表、referenceName とファイル名（拡張子を除く）のルール、tailored_ / custom_ プレフィックスの適合性
• ../datex-studio-runtime/runtime-globals.md — グリッドの TS 式で使用できる $grid.*、$row.*、$col.* ランタイムグローバル
• ../collection-filter-authoring/SKILL.md — ネストされたフィルターの契約、量化子モード、ランタイム実行、検証済みの CLI 動作と残るライブチェック

依存関係

• grid-creator — 作成スキルです。references/grids.md が、このバリデーターの監査基準となる正式なルールブックです。このドキュメントを更新すれば、バリデーターにも新しいルールが自動的に反映されます。
• tailoring-overlay — グリッドがベースグリッドではなく、テーラリングされたバリアントの場合に適用する、オーバーレイ固有のシャドウマーカールールです。
• datasource-creator — 埋め込みの datasources[0] ブロックに適用する、データソース（OData とフロー）のルールです。
• component-wiring-check — パンチリストに配線の不整合が見つかり、親がさらに詳しく調査する場合に実行する、コンポーネント間の監査です。
• datex-studio-conventions — グリッド固有のチェックリストに加えて適用される、汎用的な横断ルール（ファイル形式、命名、デフォルト値）です。
• datex-studio-shared / datex-studio-runtime — グリッドのルールドキュメントで参照される、ブランチ設定の基本要素とプラットフォームランタイムのグローバル変数です。
• component-validator — グリッド以外のコンポーネントファイルを処理する、同種の汎用ディスパッチャーです。相互排他的です。グリッドファイルは grid-validator の担当範囲で、それ以外の拡張子は component-validator に振り分けます。

ワークフロー

このスキルは通常、grid-creator が作成ループの最後に呼び出すか、ユーザーが「マージ前にこのグリッドを監査して」と直接呼び出します。呼び出しパターンは Task ツールによるサブエージェントのディスパッチです。以下の ## Sub-agent セクションにあるプロンプトテンプレートを、対象ファイルのパスとともにサブエージェントに渡します。

呼び出し（オーケストレーター側）

1. 対象がグリッド本体であることを確認する — 親が直近で作成または変更したグリッドを対象にします。ブランチが信頼できる情報源です。そのため、対象は dxs configuration upsert する直前のステージ済みスクラッチ body.json、または新たに取得したファイル（dxs source explore config <referenceName> --branch <id>、または dxs configuration get grid <id> -b <id> -O envelope.json && jq .json envelope.json > body.json）のいずれかです。referenceName は -grid（またはオーバーレイバリアントの場合は tailored_*-grid / custom_*-grid）で終わる必要があります。それ以外のコンポーネントタイプの場合は、処理を中止し、代わりに component-validator に振り分けます。永続的なローカルの src/ コピーを信頼できる情報源として監査してはいけません。
2. サブエージェントをディスパッチする — ## Sub-agent セクションのプロンプトテンプレートを使って Task ツールを実行します。サブエージェントには Read、Grep、Glob のアクセス権がありますが、編集はできません。
3. パンチリストに対応する — サブエージェントは、重要度別にまとめた Markdown のパンチリストを返します。各指摘には次のように対応します。
   • ブロッカー — upsert の前に必ず修正します。修正を grid-creator に差し戻します。
   • 警告 — 内容を確認して判断します。意図的な場合もありますが、サブエージェントが意図を推測することはありません。
   • 軽微な指摘 — 任意のクリーンアップです。親が該当箇所をすでに変更している場合を除き、対応を保留します。
4. 修正後に再検証する — ブロッカーを修正した場合は、バリデーターを再実行します。バリデーターの実行コストは低く（Read 1 回とルールドキュメントの Grep 1 回）、push の直前に実行する最後の手順にします。

対象範囲の規律（バリデーターの契約）

• バリデーターは読み取りのみを行い、編集はしません。修正は親が担当します。
• バリデーターはパンチリストを返し、書き換えは行いません。
• バリデーターが監査するのは単一のグリッドファイルです。コンポーネント間の参照は追跡しません（その担当は component-wiring-check です）。
• バリデーターは生の OData スキーマドキュメントを読み込みません。埋め込みのデータソースについて、ライブスキーマに照らしてエンティティやプロパティの検証が必要な場合は、親に schema-explorer を別途呼び出すよう推奨します。
• バリデーターは意図を推測しません。ルール違反が意図的な可能性がある場合は、ブロッカーではなく、注記付きの警告として報告します。

サブエージェント

以下のプロンプトテンプレートは、オーケストレーターが Task ツールによるサブエージェントのディスパッチ時に渡すものです。サブエージェントは読み取り専用です（Read、Grep、Glob）。

---

Datex Studio のグリッドコンポーネントファイル（*-grid.json）1 つを、プラットフォームのグリッド作成ルールに照らして検証します。ファイルは編集しません。パンチリストを返します。

ワークフロー

1. 対象のグリッドボディを読み込みます。 親から、単一の JSON ファイルのパスが渡されます。これは、アップサート用にステージされた一時的な body.json、またはブランチから取得した設定ファイルです（referenceName は <name>-grid、tailored_<name>-grid、または custom_<name>-grid です）。これは使い捨ての一時ファイルであり、永続的な信頼できる情報源のコピーではありません。ファイル全体を読み込んでください。最小化された JSON エンベロープを、チェックリストに照らして監査します。

2. グリッドのルールブックを読み込みます。 ../grid-creator/references/grids.md を読みます。各チェックリストのセクションがルールブックです。ファイルがテーラリングまたはカスタム由来のオーバーレイである場合は、../tailoring-overlay/references/tailoring.md も読みます。ドキュメントには各ルールの 理由 が説明されています。記憶を頼りに再導出しないでください。

3. チェックリストを項目ごとに確認します。 問題ごとに、次の内容を記録します。

   • 重要度 — blocker（実行時のサイレントな失敗、インポートエラー、または明確なルール違反）、warning（影響があるかどうか不明な逸脱や不整合）、nit（スタイル、命名、または任意の整理）。
   • ルール — 対応するチェックリスト項目。
   • 場所 — <filename>:<line> または JSON パス（例：datasources[0].queryOptionsObjectTypeDef）。
   • 証拠 — 短い引用または説明。

4. グリッドが OData をバックエンドとしている場合、 queryOptions.selects に、エンティティ形状の各場所で宣言されているすべてのフィールドが含まれていることを確認します。OData エンベロープのルールについては、../datasource-creator/references/odata-datasources.md を参照してください。親が schema-explorer スキルの呼び出しを許可している場合は、それを使用して、ライブ OData スキーマに照らしてエンティティ名、プロパティ名、ナビゲーション名を確認します。許可されていない場合は、未検証の名前を警告として報告します。

   グリッドがフローをバックエンドとしている場合（バックエンドのデータソースが OData エンティティではなく関数に解決される場合）は、フローデータソースのエンベロープルールについて、../datasource-creator/references/flow-datasources.md を参照してください。

5. グリッド固有の次の失敗モードは必ず明示的に確認してください。 これらはチェックリストをざっと確認しただけでは見つからず、汎用の component-validator でも検出されません。

   a. 埋め込みデータソースのコンポーネント識別エンベロープ（エンベロープの形状）。 datasources[0] に、../datex-studio-conventions/file-format.md に従って、referenceName（datasourceConfig.configId と完全一致する必要があります）、title、description、hasKey、hasResult、id、linkedDatasources、customColumns、inParams、outParams、vars、events、accessModifier、正しい configurationTypeId がすべて含まれていることを確認します。また、datasourceConfigs 配列と componentReference（存在する場合）が、グリッド独自のエンベロープと整合していることも確認します。referenceName がない場合は blocker です。これは Invalid contract. Referenced own configuration <name> does not exist or has been renamed を発生させ、インポート時に Cannot find name 'get'/'getList'/'inParams'/'refresh' という TS エラーを連鎖的に引き起こします。

   b. テキスト表示の文字列型への強制変換。 displayControl.type: "text" を持ち、textConfig.value が $row.entity.<Field> を参照する各列について、確定済みの outParams[result].objectTypeDef で <Field> の宣言型を確認します。型が string 以外の場合、バインディングで型変換する必要があります（数値の場合は "$row.entity.Id?.toString()"、合成値の場合はテンプレートリテラルでバッククォートを使用、日付の場合は $utils.date.format(...) など）。文字列型に変換されていないバインディングは blocker です。インポート時に Type '<number|boolean|...>' is not assignable to type 'string' で失敗します。../datex-studio-conventions/file-format.md の TS 式エンコード規則を適用してください。リテラルテキストを指定する宣言的な文字列スロットでは 'literal' のようにシングルクォートで囲み、合成値はバッククォートで囲む必要があります。 c. エンティティ形状の5か所同期。 グリッド内のどこかでベースエンティティフィールドがバインドされている場合は、grids.md → データソースの配線 — 5か所を同期させるに従い、次の5か所すべてにフィールドがあることを確認します。(1) datasources[0].queryOptionsObjectTypeDef、(2) datasources[0].outParams[result].objectTypeDef、(3) datasources[0].getListFlow.outParams[result].objectTypeDef、(4) datasources[0].getByKeysFlow.outParams[result].objectTypeDef、(5) datasourceConfig.configOutParameters[result].objectTypeDef。OData ベースのデータソースでは、3と4は null です。その場合は確認を省略できますが、フィールドは datasources[0].queryOptions.selects にも含まれている必要があります（実際に取得する、ランタイム専用の6か所目）。必須箇所のいずれかに不整合がある場合はブロッカーです。$row.entity 上のフィールドが undefined になるか、コントラクトエラーでインポートに失敗します。

   リンクされた出力フィールドやカスタム出力フィールドについては、派生フィールドをベースエンティティに挿入するのではなく、最終的な公開結果とそのコンシューマースナップショットをoutput-contracts.mdと照合してください。メソッドの結果形状の確認には、サーバー生成コンテキストを使用してください。フローのページネーションに関する totalCount は getListFlow に属し、最上位のコンポーネント／リファレンスには属しません。

   d. 動的フィルター／ソート登録の同期。 列で動的フィルターまたはソートを宣言している場合は、grids.md → 動的フィルターとソートの両方の要件を満たしていることを確認します。(1) フィールドが最上位の両方の箇所、つまり datasources[0].dynamicFilters／dynamicOrderBys（埋め込みデータソース側）と datasourceConfig.dynamicFilters／dynamicOrderBys（コンシューマー側）に同一のエントリーとして登録されていること、(2) 列に列ごとの配線（dynamicFilter、dynamicOrderBy、dynamicFilterType、dynamicFilterControl）があり、dynamicFilter が登録済みのプレーンなプロパティパス（例：Lines.Quantity）を使用し、dynamicOrderBy がスカラーのソート登録／コンテキストと一致していることです。コレクションナビゲーションのフィルターについては、collection-filter-authoringに従い、ネストしたオブジェクトの境界、保持されたフラグ、生成された量化子定数、グリッドモード、実際のフロー実行を確認してください。生成された $any／$all ランタイム定数は永続化されるプロパティ ID や、グリッド列のプレーンパスの dynamicFilter に含めないでください。2つの登録箇所に不整合がある場合はブロッカーです。インポートに失敗し、Outdated contract. Type mismatch for dynamic filtering/sorting が表示されます。inParams リストに $filter／$orderby がないことは指摘しないでください。これらは登録情報から自動挿入されるため、手動で追加すること自体がバグです。

   e. 命令型セル API の不一致。 セルクリック用に配線された列は、その onCellClickFlowConfig で指定されたフロー（通常は rowFlows の下にあります）を実行します。そのフローがグリッドの flows／rowFlows ブロック（またはリンクされたフローファイル）に存在することを確認してください。行／グリッドのフローで命令型の書き込みを行う場合は、grids.md → 命令型セル APIに記載されたセルのサーフェスを使用します。具体的には、$row.cells.<col>.displayControl.text／.displayControl.value、$row.cells.<col>.editControl.value、読み取り専用の $row.cells.<col>.editControl.isChanged です。対応する定義のないセルクリックフロー参照はブロッカーです。存在しないセルのサーフェスまたは列への命令型書き込みは警告です。 f. tailored と custom の由来ルールへの準拠。 ファイル名の先頭が tailored_ の場合、そのファイルはオーバーレイであり、ベースグリッドのチェックリストに加えて、../tailoring-overlay/references/tailoring.md のシャドウマーカールールが適用されます。ファイル名の先頭が custom_ の場合、そのファイルは顧客固有のバリアントであり、../datex-studio-conventions/naming-conventions.md の custom_ に関する由来ルールが適用されます。2つのプレフィックスを混在させる（例：tailored_custom_foo-grid.json）、または tailored バリアントでプレフィックスを省略することは、ブロッカーです。

   g. $grid.* のランタイムでの使用。 グリッドが TS 式内で $grid.* / $row.* / $col.* グローバルを使用している場合、../datex-studio-runtime/runtime-globals.md に従って、グローバルが存在し、適切に使用されていることを確認します。不明なグローバル識別子はブロッカーです（インポート時に TS エラーが発生）。非推奨のグローバルは警告です。

6. グリッドのチェックリストに記載がなくても、分野横断的に共通する障害要因を必ず確認してください。 これらは ../datex-studio-conventions/universal-checklist.md にまとめられています。そのリストを確認してください（description ≤ 100 chars、accessModifier の設定、referenceName ↔ ファイル名の本体、1行の最小化 JSON、正しい configurationTypeId、新規 inParams / outParams ID の snake_case、完全新規の場合は id: 0）。加えて、グリッドに関連する配線チェックを1つ行います。

   • configParameters ブロックがある場合は、../component-wiring-check/references/component-wiring.md に従って、ファイル自身の inParams と一致していることを確認します。グリッドファイルだけでバリデーターが検出できる不一致は警告です（コンポーネント間の完全な監査については、親に component-wiring-check の実行を推奨します）。

7. 報告。 重要度別にグループ化した、短い Markdown の問題リストを返します。各項目は1〜2行にしてください。前置き、書き換え、1行のポインターを超えるコードの提案は不要です。問題がなければ No issues found. と返してください。

対象範囲の制約

• 読み取りのみです。編集はしません。
• 問題リストを返します。書き換えたファイルは返しません。
• 他のコンポーネントファイルまで参照先をたどらないでください。コンポーネント間の配線は component-wiring-check の担当です。グリッドだけで明らかな配線の問題があれば報告し、フォローアップするかどうかは親に委ねてください。
• 生の OData スキーマ文書は読み込まないでください。エンティティ／プロパティ／ナビゲーションの検証が必要な場合は、親に schema-explorer スキルを別途実行するよう推奨してください。
• 意図を推測しないでください。ルール違反が意図的である可能性がある場合（例：正当な命令型の設定である displayControl.value の空値）は、ブロッカーではなく、注記を添えた警告として報告してください。
• ファイルがグリッドでない場合（サフィックスが -grid.json ではなく、tailored_*-grid.json / custom_*-grid.json のオーバーレイバリアントでもない場合）は、Cannot validate: file is not a grid. Route to component-validator instead. と返して終了してください。

出力形式

## Blockers
- [`datasources[0].queryOptionsObjectTypeDef`] `warehouse_id` missing (present in locations 2, 3, 4, 5). Entity-shape five-location sync drift.
- [`datasourceConfig.dynamicFilters`] `warehouse_id` registered on `datasources[0].dynamicFilters` but missing here. Dynamic-filter registration drift.
- [`columns[2].textConfig.value`] `$row.entity.OrderTotal` is `number`; needs `.toString()` coercion or template-literal wrapping.

## Warnings
- [`columns[3].dynamicFilter`] targets `accounts` (primitive array) directly; needs a scalar sidecar for joined-display matching. Object-collection scalar leaves use the quantified-filter workflow instead.
- [`columns[5].onCellClickFlowConfig`] references flow `confirmDelete`, which is not defined in `flows` / `rowFlows`.

## Nits
- [`description`] 118 chars — exceeds the ≤100-char soft limit.
- [`title`] equals `referenceName`; a human-readable title is more discoverable in Datex Studio listings.

空のカテゴリは省略します。3つのカテゴリがすべて空の場合は No issues found. と返してください。