project-validator

Project Validator

Datex Studio のブランチ全体を対象とするリンターです。ブランチが信頼できる情報源です。バリデーターは dxs source explore configs でブランチの設定を列挙し、dxs source document build（CLI のオフライン分析パス）で使い捨ての一時ディレクトリに一括エクスポートしたうえで、その一時エクスポートに対して 5 つのコンポーネント横断チェックを実行します。これらは、ファイル単位の検証では個別に確認できないチェックです。チェックの種類ごとにまとめられた、構造化された読み取り専用の要確認項目リストを返します。ブランチは変更せず、ローカルの src/ チェックアウトを信頼できる情報源として扱うこともありません。

これはプロジェクトレベルのバリデーターです。ファイル単位の検証を補完します。component-validator は、コンポーネントファイルを 1 つ、タイプ固有のルールシートに照らして最初から最後まで監査します。このスキルは、プロジェクト全体（またはスコープのサブセット）を監査し、ファイルを横断して確認した場合にのみ現れる問題（壊れた objectType 参照、実際のスキーマに一致しない OData クエリ、宣言済み outParams と乖離したデータソースのクエリオプションなど）を検出します。この 2 つのスキルは併用するよう設計されています。各ファイルの作成後には component-validator を、複数ファイルのマージやリリースの出荷前には project-validator を使用してください。

関連項目： component-validator — タイプごとの作成ルールシートに照らした単一ファイルの監査です。コンポーネントを作成または変更した後に使用してください。このスキルと対になるプロジェクトレベルのスキルです。

関連項目： component-wiring-check — 特定のコンポーネント横断参照の契約を追跡します。このスキルはプロジェクト全体を対象により広範（5 カテゴリー）ですが、より浅い（詳細な配線追跡ではなく、リンター相当）チェックを行います。

関連項目： post-edit-verification — 単一ファイルへの書き込み後に行う簡易チェックです。このスキルとは対象範囲が異なり、より軽量です。

依存関係

• datex-studio-conventions — defaults.md（説明は 100 文字以下、説明は必須）、file-format.md（configurationTypeId テーブル、拡張子のルール）、naming-conventions.md（タイプ識別子のルール）。以下のチェックで適用するルールです。
• datex-studio-shared ／ datex-studio-runtime — ブランチ設定の基本機能と、フローコードの解釈時に使用するプラットフォームランタイムのグローバル変数（例：$flow.inParams.<name> および $flow.outParams.<name> 参照の解決）。
• component-validator — ファイル単位の補完スキルです。同じ階層のスコープです。プロジェクトバリデーターで検出されたファイル固有の違反について、作成スキルのルールシートに詳しい説明がある場合は、詳細な監査を行うため、呼び出し元を component-validator に案内してください。
• schema-explorer — OData の事前チェック（チェック 4）で呼び出されます。プロジェクトバリデーターは、生のスキーマドキュメントを呼び出し元のコンテキストに読み込んではいけません。エンティティ、プロパティ、ナビゲーションの参照は、必ず schema-explorer に委任してください。
• codebase-research — 検出事項の確認に、根拠に基づいた読み取り専用のコンテキスト調査が必要な場合に呼び出されます（例：ブランチから *-customType 設定を取得して列挙値の許容値を確認する）。任意で、必要に応じて使用します。

モード

これは読み取り専用のプロジェクトリンターです。ファイルを変更してはいけません。ブランチの状態を変更するコマンド（upsert、--fix、書き込み）は実行してはいけません。バリデーターは検出事項を報告し、呼び出し元が対応を判断したうえで、修正を該当する作成・編集スキルに依頼します。

ワークフロー

1. スコープの解決

バリデーターは常にブランチに対して実行します（ブランチ ID を確立するには datex-studio-shared/branch-setup.md に従い、決して推測してはいけません）。呼び出し元は、さらに次のいずれかを指定します。

• all（デフォルト）— ブランチ上で所有するすべての設定。
• チェック名 — descriptions、schema、types、metadata、result-shapes。指定したチェックのみをプロジェクト全体で実行します。
• スコープのサブセット — 1 つ以上の設定タイプ（例：grid、datasource）または名前パターン。指定したサブセット内でのみ、5 つのチェックすべて（または指定されたチェック）を適用します。

呼び出し元の指定が曖昧な場合（例：「プロジェクトを検証して」とだけ指定された場合）は、ブランチ上で所有するすべての設定を対象に all を実行し、選択したスコープを出力に記載します。

2. 対象の設定を列挙してエクスポートする（ブランチから）

ブランチを信頼できる唯一の情報源とします。ローカルの src/ チェックアウトを走査してはいけません。CLI で設定を取得してください。

# List what's on the branch (optionally filter by type / owned-only / scope)
dxs source explore configs --branch <branchId> --owned-only

# Bulk-export every config to a THROWAWAY temp dir for offline analysis
dxs source document build --branch <branchId> --include-summaries -o "$TMP/dxs-validate"

document build は、設定ごとに $TMP/dxs-validate/<App>/<branchId>/local/<type>/<referenceName>.yaml の下へファイルを書き込みます。この一時エクスポートだけをチェックで読み取ったり検索したりします。取得したばかりの一時ファイルを検索するのは承認された方法ですが、永続的な src/ ツリーを grep するのは認められていません。完了したら一時ディレクトリを削除してください。

dxs 0.5.4 未満では、このエクスポートは通知なく不完全でした。dxs ≥ 0.5.4 が必要です。 ライブラリの検出は applicationId をキーにしていましたが、settings/references→AppConfig への移行時に、すべての reference 行からこの値が削除されていました。そのため、document build が走査するのはブランチ自体だけでした。各ブランチの処理では設計上、外部設定が除外されるため、ライブラリの設定はすべてエクスポートに含まれませんでした。しかも終了コードは 0 で、警告もありませんでした。名前を参照先パッケージに解決するチェック（types、schema、result-shapes）では、その欠落が「コンポーネントがない」と解釈され、誤った失敗が出力されます。古いビルドで正常終了しても、情報がないのであって、問題がないということではありません。アップグレードしてください（dxs update）。0.5.4 以降は、エクスポートにライブラリのブランチが含まれ、解決できなかったライブラリごとに Warning: could not resolve library '<name>' to a branch が出力されます。今回も同じ欠落を示す行ですが、今度はその場で報告されるため、該当するチェックの範囲を適切に設定してください。

エクスポートされた設定を種類ごとにグループ化します（エクスポートはすでに種類ごとのフォルダーに整理されており、各設定には configurationTypeId が含まれています）。

• footprintflow — アクション（*-footprintFlow）
• flow — 関数（*-flow）
• customtype — インターフェース／列挙型（*-customType）
• footprintdatasource — Footprint 階層の OData データソース
• datasource — クラウド階層のデータソース（OData またはフローを使用）
• selector、storage、grid、form、editor、hub、backendtest

種類が表の項目と一致しない設定は unknown component type として記録し、スキップします（実行を中断してはいけません）。

3. 5 つのチェックを実行する

列挙されたファイルを対象に各チェックを実行します。順序は問いません。コストが最も低いチェックから実行してください。結果は構造化されたリストに集約し、ファイルを直接編集してはいけません。

4. 報告する

以下の 出力形式 セクションに従って、対応事項のリストを作成します。結果はチェックの種類ごとにまとめます。最後に 1 行の要約（total files checked、passes、warnings、failures）を記載してください。1 行の簡潔な参照先を除き、修正方法を提案してはいけません。

5 つのチェック

1. 説明の検証（descriptions）

対象： すべてのコンポーネントファイル（上記のすべてのサフィックス）。

ルール（datex-studio-conventions/defaults.md および file-format.md に基づく）：

• description を null にしてはいけません。
• description を ""（空文字列）にしてはいけません。
• description は 100 文字以下である必要があります。これは Footprint 側の SQL 列の上限であり、超過するとインポート時に SQL の切り詰めエラーが発生します。

重大度：

• description が null または "" → 失敗。
• description が 100 文字を超える → 失敗（警告ではありません。インポートが失敗します）。
• description が設定され、上限以内 → 合格。

出力行：

[pass] i_awi_configuration-customType.json — "Allocation config interface" (35 chars)
[FAIL] my_action-footprintFlow.json — description is null
[FAIL] orders_grid-grid.json — description is 137 chars (cap is 100)

2. スキーマとコードの整合性（schema）

スキャン対象： アクションファイル（*-footprintFlow.json）と関数ファイル（*-flow.json）。

チェック内容： 宣言された inParams／outParams の JSON 定義と、nodes[0].stepConfig.executeCodeConfig.code に格納された TypeScript コードを照合します（codebase-research に記載されたパターンに従います。フローコードは JSON の先頭ではなく、JSON 内に格納されています）。

手順：

1. JSON から inParams[] と outParams[] を解析します。
2. 埋め込みコード文字列を抽出します（複数ステップのフローでは nodes[*] を順に処理します）。
3. 宣言された各 inParam.id と、コード内の $flow.inParams.<id> 参照をヒューリスティックに照合します。
4. 宣言された各 outParam.id と、コード内の $flow.outParams.<id> 参照をヒューリスティックに照合します。
5. 対応する宣言がない $flow.inParams.<name> または $flow.outParams.<name> のコード内参照を探します。

重大度：

• 宣言された inParam がコードで参照されていない → 警告（後方互換性のために維持されている、将来使う予定がある、または外部で接続されているなど、意図的な場合があります）。
• 宣言された outParam がコード内で一度も代入されていない → 警告。
• 対応する宣言のない $flow.inParams.<name>／$flow.outParams.<name> をコードが参照している → 失敗（実行時エラー、または暗黙の undefined が発生します）。

注意事項： これは文字列のヒューリスティック照合であり、TypeScript コンパイラーではありません。警告として提示される場合は、誤検知があっても問題ありません。各警告が実際に問題かどうかは呼び出し側が判断します。ソースコードに基づく根拠なしに、警告を失敗へ引き上げないでください。

出力行：

[warn] plan_inventory_consumption_action — inParam 'unused_param' declared but not referenced in code
[FAIL] commit_allocation_plan_action — code references $flow.inParams.foo but 'foo' is not declared in inParams

3. 型の解決（types）

スキャン対象： すべてのコンポーネントファイル。JSON 内の任意の場所にある "objectType": "<Package>.<TypeName>" の値を検索します（一般的には inParams[*].objectType、outParams[*].objectType、objectTypeDef.properties[*].objectType、およびネストされたデータソースの形状内にあります）。

ルール： 参照されるすべての <Package>.<TypeName> は、次のいずれかに解決できる必要があります。

• ブランチ上で現在のパッケージが所有する <TypeName> customType 設定（一時エクスポート内の customtype/<TypeName>-customType.* エントリー。同等の検索コマンドは dxs source explore configs --branch <id> --type customtype --search <TypeName>）、または
• プロジェクトが依存する別のパッケージが所有する型（呼び出し側がパッケージ間の参照を追跡するよう明示的に依頼していない限り、不明なパッケージは「スコープ外、報告しない」として扱います）。

手順：

1. 現在のパッケージを特定します（パッケージのコンポーネントファイルのいずれかから読み取り、フォルダーの命名規則で照合します）。
2. スキャン対象のすべてのコンポーネントファイルから、各 objectType 文字列を収集します。
3. パッケージ内の参照ごとに、ブランチ上に一致する <TypeName> customType 設定が存在することを確認します（一時エクスポートの customtype/ フォルダー内）。高速解決のショートカット： ブランチの命名レジストリを一度取得します。dxs configuration nomenclature -b <branchId> は、列挙型のメンバーを constantValues に含むフラットな <Package>.<Type> カタログを返します。これを使ってすべての objectType を一括で照合すれば、型ごとに dxs source explore を実行する必要はありません。../datex-studio-shared/context-navigation.md#discovering-custom-types-and-enum-members を参照してください。
4. 解決できない参照を報告します。

重大度：

• 現在のパッケージ内の型を参照しているが、ブランチ上に一致する customType 設定がない → 失敗。
• プロジェクト内で不明なパッケージに属する型を参照している → 警告（タイプミスの可能性もあれば、正当な外部パッケージである可能性もあります）。

出力行：

[FAIL] orders_grid-grid.json — references `Allocations.i_unknown_type`, no i_unknown_type-customType.json found
[warn] import_orders_action-footprintFlow.json — references `ExternalPkg.i_thing`; ExternalPkg is unknown to this project

4. OData スキーマの事前チェック（metadata）

スキャン対象： OData データソースファイル（*-footprintDatasource.json、および type が "oDataQuery" の *-datasource.json ファイル）。フローに依存するデータソースはスキップします。

手順：

1. 接続を特定します。 各データソースは接続（接続 ID または接続名）を参照します。ファイルから接続を特定してください。曖昧な場合は、どの接続に対して検証するか呼び出し元に確認してください。
2. すべてのエンティティ／プロパティ／ナビゲーションの照会を schema-explorer に委任します。生の OData メタデータドキュメントを親コンテキストに読み込まないでください。schema-explorer は簡潔で構造化された回答を返し、接続の解決と FootPrintApi 固有の例外処理を行います。
3. 各 OData データソースについて、次の項目を確認します。
   • paths[0].entitySet の entitySet が OData スキーマに存在すること。
   • queryOptions.selects 内のすべてのプロパティがエンティティ型に存在すること。
   • queryOptions.filters で参照されるすべてのプロパティ（フィルター式のオペランド）がエンティティ型に存在すること。
   • queryOptions.expands 内のすべてのナビゲーションプロパティがエンティティ型に存在すること。
4. 不一致を報告します。

重大度：

• エンティティセットが存在しない → 失敗。
• select／filter プロパティが存在しない → 失敗。
• expand のナビゲーションが存在しない → 失敗。
• スキーマの照会に失敗（接続に到達できない、スキーマが読み込まれていない） → このファイルではチェックを実行できなかった旨を添えて 警告。到達不能な接続が 1 つあっても実行全体を失敗にせず、警告を記録して続行します。

出力行：

[FAIL] fpds_get_material-footprintDatasource.json — entitySet 'Materials' not found in schema (did you mean 'Material'?)
[FAIL] ds_orders_grid-datasource.json — selects: property 'CustomeName' not on entity 'Orders' (typo?)
[warn] ds_legacy_thing-datasource.json — could not reach connection 'LegacyProd'; check skipped

5. 結果形状の同期（result-shapes）

スキャン対象： すべてのデータソースファイル（OData とフロー依存の両方を含む *-datasource.json および *-footprintDatasource.json）。

ルール： データソースのクエリ側の形状（queryOptionsObjectTypeDef）と、コンシューマー向けの形状（outParams[0].objectTypeDef）は一致している必要があります。一方の各プロパティには、もう一方に同じ id かつ同じ type の項目が対応していなければなりません。この 2 つの宣言の不一致は、「Studio のプレビューではデータソースが動作するのに、コンシューマーでは動作しない」という典型的な失敗モードです。

手順：

1. ファイルから queryOptionsObjectTypeDef.properties[] を読み取ります。
2. ファイルから outParams[0].objectTypeDef.properties[] を読み取ります。
3. id でプロパティを対応付けます。
4. 一方にあってもう一方に対応する項目がないプロパティ、または type が異なる id の組み合わせを指摘します。

重大度：

• 一方にプロパティがあり、もう一方にない → 失敗。
• プロパティの組み合わせで type が一致しない → 失敗。
• id と type は一致するが、順序／メタデータが異なるプロパティの組み合わせ → 軽微な指摘。

出力行：

[FAIL] ds_open_orders-datasource.json — `queryOptionsObjectTypeDef.OrderId` is `int32`, `outParams[0].objectTypeDef.OrderId` is `string`
[FAIL] fpds_lots-footprintDatasource.json — `outParams[0].objectTypeDef` declares property `LotCode`, missing from `queryOptionsObjectTypeDef`

出力形式

検出結果はチェックの種類ごとに、上記 5 つのチェックの順にまとめます。各グループ内では、失敗、警告、軽微な指摘の順に列挙します。合格行は省略可能です。呼び出し元が詳細な実行を求めた場合は含め、既定の lint サマリーでは省略します。必ず最後に 1 行のサマリーを記載してください。

## 1. Description Validation
  [FAIL] my_action-footprintFlow.json — description is null
  [FAIL] orders_grid-grid.json — description is 137 chars (cap is 100)
  [pass] i_awi_configuration-customType.json — "Allocation config interface" (35 chars)
  ...

## 2. Schema-Code Alignment
  [FAIL] commit_allocation_plan_action — code references $flow.inParams.foo but 'foo' is not declared in inParams
  [warn] plan_inventory_consumption_action — inParam 'unused_param' declared but not referenced

## 3. Type Resolution
  [FAIL] orders_grid-grid.json — references `Allocations.i_unknown_type`, no i_unknown_type-customType.json found

## 4. OData Schema Pre-Flight
  [FAIL] fpds_get_material-footprintDatasource.json — entitySet 'Materials' not found (did you mean 'Material'?)
  [warn] ds_legacy_thing-datasource.json — could not reach connection 'LegacyProd'; check skipped

## 5. Result-Shape Sync
  [FAIL] ds_open_orders-datasource.json — `OrderId` type drift: query=int32, outParams=string

## Summary
  files checked: 142
  passes: 128
  warnings: 7
  failures: 7
  scope: all

チェックを実行して検出結果がなかった場合は、その見出しの下に (no issues) と記載し、省略しないでください。明示的に空であることを示すほうが、何も記載しないより分かりやすくなります。

ルール

• 読み取り専用です。 ファイルを変更しないでください。自動修正しないでください。変更を伴う dxs コマンドを実行しないでください。バリデーターの役割は報告することです。対応するかどうかは親（またはユーザー）が判断します。
• 書き換えではなく、修正項目リストにしてください。 指摘は、ファイルパスと簡潔な根拠を添えた1行の引用にします。長いコードの提案や、提案する JSON は含めないでください。修正方法が明白でない場合は、修正そのものではなく、対応する作成スキルの名前（例：「datasource-creator に回す」）を示してください。
• OData スキーマは schema-explorer に委任してください。 生の OData メタデータを親のコンテキストに読み込まないでください。これは Datex Studio の作業で最も重大なコンテキスト汚染のアンチパターンです。
• ヒューリスティックチェックでは警告を出しても、失敗にしてはいけません。 特に、スキーマとコードの整合性チェックは文字列照合によるリントであり、コンパイラーではありません。「実際の問題かもしれない」場合は warning を使用し、根拠が明白な場合に限って fail を使用してください。
• スコープを厳守してください。 呼び出し元がチェック名を指定した場合は、そのチェックだけを実行してください。サブツリーを指定した場合は、そのサブツリーだけを調べてください。独自の判断でスコープを広げないでください。
• 意図を推測しないでください。 違反が意図的な可能性がある場合（外部接続用に残された inParam や、将来への備えとしてクエリより広く宣言された outParams など）は、失敗ではなく、注記を添えた警告として指摘してください。
• 1回の呼び出しにつき、実行は1回だけです。 「問題なし」になるまでバリデーターを繰り返し実行しないでください。修正項目リストを提示し、繰り返すかどうかは親に判断を委ねてください。
• ブランチを正としてください。 dxs source explore configs / dxs source document build を使って、ブランチから設定を列挙・エクスポートしてください。ローカルの src/ チェックアウトを信頼できる情報源として読み込まないでください。
• ブランチには書き込まず、修正パッチも作成しないでください。 ローカルに作成できる成果物は、一時的な dxs source document build のエクスポートのみです。チェックではこれを読み込み、完了後に削除してください。レポートは応答本文で返します。references/、ログ、パッチファイルは作成しないでください。