コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

aggrega validate

aggrega validate は正しさを検査します。対象は、スキーマ、ピラー構造、ドキュメント間の参照解決、extends チェーン、provider の入力種別の対応能力、そして(レンダリングを行うエンティティについては)実際にレンダリングできるかどうかです。引数によって選ばれる 3 つのモードがあり、同じ正しさの検査を 3 つの範囲に適用します。カタログ全体(引数なし)、単一の Release の依存関係の閉包(--release)、そして 1 つのエンティティファイル(エンティティのパス)です。どの範囲も、カタログの異なる部分を対象に「このコンテンツは正しいか」という同じ問いに答えます。

正しさは慣例とは別のものです。aggrega validate はコンテンツが整形式でありコンパイルできるかどうかを問い、aggrega lint はコンテンツがカタログの公開の規律(命名、カテゴリとディレクトリの対応、バージョンの上げ幅など)に従っているかどうかを問います。2 つのコマンドは互いに同じ 3 つの範囲を持つため、どちらの観点も必要な粒度で検査できます。

aggrega validate はディスクに何も書き込まず、ランタイムの状態も読みません。ビルドと同じ解決と検証を実行し、レンダリングの手前で停止します(単一のエンティティの場合は、レンダリングを切り離して実行します)。

エンティティのパスは位置引数として指定できます。エンティティのパスと一緒に --release を指定しても、Release の範囲は選択されません。エンティティはその Release の条件のもとで、単独で検査されます。Release の条件でエンティティを検査するを参照してください。

カタログ全体の正しさ(引数なし)

引数なしの aggrega validate は、設定されたカタログディレクトリ配下のすべてのカタログエンティティを読み込み、エンドツーエンドで検査します。何かを読み込む前に、それらの配下にあるすべての YAML ファイルを読み取り、その中に読み込めない Aggrega ドキュメントがあれば、後述のとおり実行を停止します。そのうえで次を行います。

  • スキーマピラーの構造 — 各 Component と Feature の spec.schema: ブロックを展開して検証します(ビルドが適用するのと同じスキーマピラー検査)。コンパクト形式の展開も含みます。
  • ドキュメント間参照の解決 — SchemaLibrary のエントリへの $ref および $import 参照が解決されることを確認し、解決できない、またはその他の理由で無効な SchemaLibrary は拒否されます。
  • extends チェーン — extends を宣言するすべてのエンティティが親に対して解決され、親と子をマージした形が検査されます。カタログディレクトリにない親は、ビルドが読む場所から読まれます。つまり、Release のロックファイルがその親について記録しているピンに従って、アーティファクトキャッシュから読まれます。使われるのは、その回の検証が対象とする Releases のロックファイル、またはワークスペースを 1 回でまとめて検証する場合は、ワークスペースが持つすべての Release のロックファイルです。そのため、レジストリに公開されたベースは、aggrega pull がそれを取得してピン留めすれば検証を通り、どちらにもない親は aggrega pull --release <release> を示して実行を停止させます。何も取得されません。
  • 宣言されたセレクター — Component または Feature のドキュメントが spec.usesSchema の下の依存関係ソケット、または spec.featuresSchema の下のアタッチメントスロット(Component ではソケットが宣言するスロットも含む)に宣言するすべてのラベルセレクターを、ソケットに何かが配線されているか、スロットが埋められているかにかかわらず、セレクター文法に照らして読み取ります。宣言されたセレクターを参照してください。
  • OCI ロケーションの衝突 — 同じレジストリロケーションに公開されることになる 2 つの異なるカタログ ID は明示的に拒否されます。これにより、ビルドがあるエンティティの公開済みバイトを別のエンティティのもので黙って上書きすることはありません。
  • Provider の入力種別ケイパビリティ — 合成を行えない provider にバインドされた workload: ブロックを宣言する Recipe または FeatureRecipe は、決してビルドできないため、エラーとして報告されます。

これは、ビルドが Release ごとに行う検証に対応するカタログ全体版です。壊れたカタログエンティティが、いずれかの Release に届く前に表面化することを意図した場所です。読み込めない Aggrega ドキュメント、およびスキーマピラー違反、解決できない、または無効なライブラリ、extends の解決失敗、文法が拒否する宣言済みセレクター、ロケーションの衝突、入力種別の対応能力エラーのいずれかがあれば、明示的に停止します。スキーマピラーの重複や extend 時の絞り込みに関する指摘、および Component または Feature がスキーマ内容にインラインで記述した各 x-aggrega-* キーワードは、助言的な notice: 行であり、終了コードを変えることはありません。

読み込めない Aggrega ドキュメントは実行を停止させます。 カタログディレクトリ配下の YAML ファイルは、いずれかの行がインデントなしで apiVersion: から始まり、その値が aggrega.ai/ で始まる場合 (引用符の有無は問いません)、Aggrega ドキュメントです。そのようなファイルが読み取れない場合、YAML がパースできない場合、または kind や metadata がエンティティのエンベロープの形をしていない場合 (たとえばリストとして書かれた metadata)、ディレクトリの読み取りが終わった時点で E0175 により実行が停止し、該当するすべてのファイルが、読み取りまたはパーサーが示した理由とともに示されます。何も検査されず、catalog validation passed 行も出力されません。読み込めても、どのカタログも保持しない kind を宣言しているドキュメント (たとえば綴りを誤った Componnent、あるいは kind がまったくないもの) は、同じ実行を E0371 により停止させ、宣言している種類とともに上記のファイルと並べて示されます。Manifest、Release、および Recipe が自身のディレクトリからインポートする Workload は読み飛ばされます。それ以外の YAML (レンダリングされるまでパースできない Helm チャートのテンプレート、チャートの values、ワークフロー定義など) は読み飛ばされます。

どのディレクトリを読むかは、ワークスペースの形によって異なります。

  • 設定に独自の Release カタログディレクトリを持たないワークスペースは、検索スタック全体に対して 1 回検証されます。検索スタックは、--catalog のディレクトリ、次に workspace.catalog_dirs、そしてワークスペースのルートに catalog ディレクトリがあればそれ、の順です。

  • workspace.releases 配下で Releases を指定するワークスペースは、カタログの複数のバリアントを並べて保持し、それぞれを専用の Release が読むことがあります。それらをすべて一度に読み込むと、すべてのバリアントが 1 つのカタログに入り、あるバリアントのエンティティが別のバリアントのものを覆い隠してしまいます。そのため、ワークスペースが保持する Release ごとに、その Release が読むディレクトリに対して 1 回ずつ検証され、どのパスでも --catalog のディレクトリが先頭に来ます。設定が指定していない Release は、ワークスペースのリストを読みます。各パスは、その Release と読んだディレクトリを示す行の下に報告され、続いてそのパスの結果が示されます。

    Release release-compose.yaml reads catalog-compose
    catalog validation passed (schema-pillar + library + extends + oci-location)
    Release release-helm-synth.yaml reads catalog-helm-synth
    catalog validation passed (schema-pillar + library + extends + oci-location)

    まったく同じディレクトリを読む Releases は 1 つのパスを共有し、そのパスにはそれぞれの名前が示されます。ディレクトリを 1 つも読まない Release(そのエントリに catalog_dirs: [] と書かれているもの)は、検査対象がないと報告され、他のパスは通常どおり実行されます。あるバリアントの壊れたエンティティは別のバリアントについて何も示さないため、先のパスの結果にかかわらずすべてのパスが報告されます。いずれかのパスが失敗するとコマンドは失敗し、ディレクトリが失敗した Releases の名前を示します。ワークスペースが保持する Releases とは、その Release ドキュメント、つまり kind が Release である YAML ファイルで、ワークスペースのルート配下にあり、隠しディレクトリおよび node_modules、vendor、dist の外にあるものです。

どのパスにも読むものがない実行は、クリーンなカタログとして報告されるのではなく拒否されます。エンティティを catalog/ の下に置くか、--catalog を渡すか、workspace.catalog_dirs を設定してください。Releases を指定するワークスペースでは、workspace.releases 配下の Release 自身の catalog_dirs を設定することもできます。現在の作業ディレクトリを暗黙に列挙することはないため、無関係なツリーを取り込むことはありません。

aggrega mcp の validate ツールは、カタログ全体を求められると同じパスを検証します。Releases を指定するワークスペースでは、その応答に、すべてのパスに対する判定と並んで、各パスが passes の下に含まれます(Releases、読んだディレクトリ、そのパス自身の判定)。

アーティファクトキャッシュにしかないライブラリ

アーティファクトキャッシュには取得処理が置いたものが保持され、キャッシュされた SchemaLibrary がカタログの内容として扱われるのは、Release のロックファイル内のエントリがそのダイジェストを保証している場合に限られます。キャッシュとは何か、何ではないかを参照してください。$ref: が何にも解決されず、しかもどのロックファイルエントリも固定しておらず、検査が読み込むどのカタログディレクトリも提供していないライブラリがキャッシュにある場合、レポートの後に remediation: 行が続き、そのような各ライブラリと、失敗したスコープに有効な対処が示されます:

  • 引数なしの場合、およびエンティティパスを指定した場合(--release の有無にかかわらず)、validate はカタログディレクトリからのみライブラリを読み込み、ロックファイルのエントリを介して読み込むことはないため、記録されたエントリがあっても判定は変わりません。この行はそのことを述べ、カタログディレクトリの下でライブラリを作成するか、aggrega pull --release <release> を実行してから aggrega validate --release <release> を実行するよう案内します。後者は、Release のロックファイルが固定しているライブラリに照らしてその Release を検査します。
  • --release のみの場合、validate は Release のロックファイルを読み込むため、この行は、ライブラリを解決してそのエントリを記録する aggrega pull --release <release> か、カタログディレクトリの下でライブラリを作成することを示します。

この行は判定も終了コードも変更しません。

宣言されたセレクター

Component または Feature は、依存関係ソケットに何を配線できるか、アタッチメントスロットを何で埋められるかを、ラベルセレクターで制約します。これは、各 spec.usesSchema エントリと各 spec.featuresSchema エントリの selector:、そして Component では、ソケットが自身の featuresSchema の下で宣言する各スロットの selector: です。ビルドがセレクターを読み取るのは、何かがそこに到達する場合、つまりソケットを通るエッジが引かれる場合や、アタッチメントがスロットを埋める場合だけです。そのため、カタログ全体のスコープと単一エンティティのスコープは、ソケットに何かが配線されているか、スロットが埋められているかにかかわらず、Component または Feature のドキュメントが宣言するすべてのセレクターを読み取り、文法が拒否するセレクター(閉じ括弧のない値リスト、重複したカンマ、= や ! を含むキーなど)があればチェックは失敗します。この文法は文字列文法で説明しているものです。

この拒否は、ビルドが同じセレクターに到達したときに報告するものと同じで、コードも文言も同じです。ソケットのセレクターには E0007、スロットのセレクターには E0008 が使われ、セレクター、それを宣言するソケットまたはスロット、そして文法がそれを読み取れなかった理由を示します。これはカタログの欠陥としてエンティティのファイルに記録されます:

selector violation ("<selector>", declared on socket "<socket>", which could not be evaluated: "<why it could not be read>"). Correct the selector on the socket’s declaration in the component type’s usesSchema.(セレクター違反:ソケットに宣言されたセレクターを評価できませんでした。コンポーネント型の usesSchema にあるソケットの宣言で、セレクターを修正してください。)

各ドキュメントは作成者が書いたとおりに読み取られるため、ベースエンティティが宣言するセレクターは、それを拡張するエンティティごとに報告されるのではなく、ベース自身のファイルに対して 1 回だけ報告されます。Feature の appliesTo と appliesToAnyOf はここでは読み取られません。これらは、その Feature のアタッチメントが評価される場所で読み取られます。

カタログ全体のスコープは、拒否された各セレクターをそれぞれの selector: 行で報告し、その件数とともに失敗します。単一エンティティのスコープは、それらを形状の段階の失敗として報告します。これはエンティティパスと並べて --release を指定するかどうかにかかわりません。その形式は、Release の条件で実行される単一エンティティのスコープだからです(Release の条件でエンティティをチェックするを参照)。Release の依存関係クロージャを検証する単独の --release とビルドは、エッジまたはスロットの充填が到達する場所でのみセレクターを読み取り、そこで停止します。

Release スコープの正しさ(--release)

aggrega validate --release <release-path> は、カタログ全体や単一のエンティティではなく、1 つの Release の解決済み依存関係が到達するエンティティだけを検証します。クロージャはビルドが使うのと同じ仕組みで計算されるため、検査されるエンティティはその Release のビルドが解決するエンティティとまったく同じです。そのクロージャに対して、次を行います。

  • クロージャに限定した extends チェーンを解決し、解決エラーがあれば失敗します。
  • 解決済みの各エンティティのスキーマピラーを(クロージャに限定して)検証し、スキーマピラーのエラーがあれば失敗します。
  • ビルドが実行するのと同じレンダリング前の値適合性検査を実行します。Release のパラメータを記述された値に解決し(そのため {{ .parameters.* }} の値はテンプレートとしてではなく解決後の値として検査されます)、その結果をクロージャの合成済みスキーマに対して検証します。extends するエンティティについては、合成された親+子のスキーマへの適合性も含みます。スキーマに違反する値は、ゼロ以外の終了コードで失敗します。
  • すべての Recipe および FeatureRecipe のアサーションを、Release が解決した値に対して、ビルドがレンダリング前に評価するのと同じように評価します。各コンポーネントの Recipe は Manifest のマッピングどおりにバインドされ、その locals と provides が解決されます。そして最初に失敗したアサーション(fail を呼び出すもの、またはテンプレートが見つからないキーで停止するもの)が、ビルドが停止するときと同じ条件と文で検証を失敗させます。評価できない locals または provides のテンプレートも、ビルドを失敗させるのと同様に検証を失敗させます。各 Recipe がレンダリングに使うプロバイダーには、ビルドと同様に、そのコンポーネントのリソースに付ける名前が問い合わせられます。Recipe の provides がその名前を読む場合があるためです。何もレンダリングされません。これらのアサーションは、上記のいずれもまだ失敗していない場合にのみ評価されるため、Release はビルドが停止する最も早い障害を報告します;
  • スキーマピラーの重複と extend 時の絞り込みに関する所見を、終了コードを決して変えない情報提供の notice: 行として表示します;
  • 読み込むエンティティがスキーマ内容にインラインで記述した各 x-aggrega-* キーワードを、ビルドと同様に、エンティティごとに 1 回、warning: 行として表示します。これも終了コードを変えることはありません。

これにより --release は真のビルド前検査になります。ビルドが拒否するものを、ビルドの前に検出します。つまり、レンダリングを伴わないビルドの依存関係検証です。レンダリングは実行せず、ネットワークからの取得も発生させません。クロージャはローカルカタログ(および存在する場合は Release のロックファイルのピン)から解決されます。ロックファイルを必要とするレジストリにピン留めされた依存関係の集合は、取得を行う代わりに、正直に解決不能な参照のエラーを表示します。絞り込みは助言として表示され、強制されることはありません。

Release の解決結果ともはや一致しないロックファイルは、aggrega build が出力する停止によって検証を拒否します。 Release の隣にロックファイルがある場合、--release は、Release の依存関係が解決されるとすぐ、上記のいずれのチェックよりも前に、ビルドがレンダリング前に行うドリフト比較によって、そのロックファイルを Release の解決結果と照合します。ピン留めされたエンティティ、ライブラリ、プラグイン、または Release ファイル自体がロックファイルからドリフトしている場合、検証はビルドの E0130 による拒否(ドリフトしたすべてのエントリと、それを解消する aggrega pull --release <release>)と 0 以外の終了コードで停止します。そのため、ビルドがドリフトとして拒否するロックファイルを検証が見過ごすことはありません。引数なしの場合とエンティティパスを指定した場合、validate はロックファイルに従いません。カタログ全体のチェックは extends の親を見つけるためだけにロックファイルのピンを読み、単一エンティティのチェックはロックファイルを読みません。

ビルドが実行するのと同じ検査を実行するため、同じアタッチ済みのゲートプラグインも実行します。そのため、ビルドと同じ信頼済みプラグイン ID の記録に従います。受理または拒否の判定を返すプラグインをアタッチするワークスペースは、Release の隣にプラグイン信頼記録を持ち、--release はそれらのプラグインのいずれかを実行する前に、設定をその記録と照合します。記録されたゲートを設定がもはやアタッチしていない場合は検証が停止し、aggrega pull が投入するキャッシュから解決されたプラグインのアーティファクトが記録されたものでない場合は、実行されずに拒否されます。何も記録していないワークスペースには記録がなく、この照合については何も変わりません。--release はまた、Release が依存するものに対して記録されたすべての取り下げを、標準エラーに deprecation: 行として、aggrega build が出力するのと同じ文言で示します。ロックファイルが固定済みの参照に対して記録するマーカーも、信頼記録が判定ロールでアタッチされたプラグインに対して記録するマーカーも同様です。取り下げは判定も終了コードも変更しません。また、存在するのに読み取れない信頼記録は、何も記録していない記録として通過するのではなく、検証を停止させます。

キャッシュから読み込まれたプラグインは、ビルドと同様に、読み込まれた時点でそのエントリが記録する署名にも従います。エントリが検証済みの署名を記録している場合、その事実が指すキャッシュ内の署名素材が再度検査され、素材が欠けているか異なるプラグインは拒否されます。また、素材が読み込まれたものとは別のプラグインのために作られたものも拒否されます。これは別のエントリからコピーされた signature がとる形であり、署名要件の内容にかかわらず拒否されます。ワークスペースの信頼設定が署名を要求する場合、キャッシュから読み込まれたプラグインで、エントリが署名を記録していないもの、または記録にエントリがないもの(削除された記録を含む)も拒否されます。これは aggrega pull が未署名として拒否するのと同じ設定の下で行われるため、skip_signature_verification と advisory なレジストリでは実行が許可されます。拒否は検証を失敗させ、その診断の中で報告されます。報告ではプラグインと、aggrega pull --release <release> が示されます。これはレジストリでその署名を検証し、記録し、それが指すバンドルをキャッシュし、ダイジェストと一致しなくなったキャッシュ済みのコピーを書き直すコマンドです。カタログディレクトリのいずれかから提供されるプラグイン、またはコンパイラバイナリ内のコピーから提供されるプラグインは、この要件に従うことはありません。他の 2 つのスコープはこれらのいずれにも従いません。ワークスペースのプラグインアタッチメントを読まないため、そのようなプラグインはそこでは実行されません。

グラフを判定するのではなく変更するプラグインについても同じことが当てはまります。label-transform または annotation-transform のアタッチメントはレンダリング出力の内容を形作るため、ロックファイルはその ID と読み込むソースファイルの両方をピン留めします。そして --release は、ビルドと同じ方法でそれらのアタッチメントを実行します。ロックファイルから再構築し、それぞれを記録されたダイジェストに従わせ、ディスク上のファイルではなくロックファイルが持つソース内容を読み込みます。遭遇する前に知っておくべき帰結が 2 つあります。

  • **.aggrega-config.yaml で transform プラグインをアタッチしても、pull するまで --release の動作は変わりません。**これはビルドが従うのと同じルールであり、理由も同じです。アタッチメントの集合はバイトを決定する入力であるため、編集された時点ではなく pull の時点で採用されます。
  • **バイトがロックファイルに記録されたダイジェストと一致しなくなったキャッシュ済みプラグインは拒否されます。**ビルド中とまったく同じです。

Release にロックファイルがない場合でも、--release は検証を行います。拒否する代わりに、プラグインの ID を検査できなかったことを警告し、実行すべきものを示します。警告を参照してください。

コンパイル済みグラフの受け渡し

--ir-graph は、この検証が解決したグラフを、判定行の前に JSON として標準出力に書き出します。これは追加的なものです。同じ検査が実行され、同じ診断が書き出され、終了コードもこのフラグがない場合と同じです。返されるグラフは検証が行われた対象そのものであるため、判定が報告するものと異なる解決を記述することはありません。

これはこのスコープにのみ適用されます。カタログ全体と単一エンティティのスコープは Release ではなく合成されたハーネスを駆動し、グラフを解決しません。それ以外の場所で要求すると、黙って無視されるのではなく拒否されます。グラフが解決される前に実行が停止した場合、標準出力には何も書き出されず、コマンド自身の診断が停止の原因を示します。

隣にあるフラグに注意してください。--response-format はこのコマンド自身のレポートをどれだけ書き出すか(detailed または concise)を設定し、--ir-graph はそのレポートとは別の第 2 のドキュメントを要求します。一方は量、もう一方は対象であり、どちらも判定を変えません。

作成者が機密と宣言した値は、aggrega inspect で説明されている構造化された形式でグラフから除外されます。消費側のコンポーネントのソケットがリーフを機密と宣言している場合は、接続の values と infra も除外の対象です。--ir-graph とともに --unredacted を指定すると、aggrega inspect --unredacted が述べる条件の下で、代わりにそれらの値が出力されます。これはグラフにのみ及び、このコマンドが書き出す他のものには及びません。そして出力が届く先はすべて、それらの値を平文で持つことになります。--ir-graph なしで指定すると、明らかにするものが何もないため拒否されます。

単一エンティティの正しさ(エンティティパス)

aggrega validate <entity-path> は、カタログのエンティティファイルを 1 つチェックします。段階的な一連のチェックを適用し、最初のブロッキングな失敗で停止するため、スキーマの破損はカタログの処理より前に明確に表面化します。

  • プレースホルダー(すべての種別)— 種別が必須とする値のうち、ファイルが空文字列のままにしているもの。すべてが他のチェックより前に一度に報告され、それぞれに何を受け付けるかが示されます。未記入のプレースホルダーを参照してください。
  • スキーマエンベロープ(すべての種別)— カタログローダーが各パース境界で実行するものと同一の、エンティティごとの JSON-Schema チェック。
  • 形状(すべての種類)— 種類固有の構造検証です。Component または Feature の場合、これにはファイルが依存関係ソケットまたはアタッチメントスロットに宣言するすべてのラベルセレクターを、セレクター文法に照らして読み取ることが含まれます。宣言されたセレクターを参照してください。
  • ピラー構造(Component と Feature)— spec.schema: のピラーチェック。ドキュメントをまたぐ $ref の展開にはカタログの SchemaLibraries を使用します。

Component または Feature はここで終わります。スキーマエンベロープ、形状、ピラー構造です。単独の Component には単独でレンダリングするための記述済みの values や infra がないため、レンダリングするものはありません。その正しさはスキーマとピラーの段階で完全にカバーされます。スキーマ内容にインラインで記述された各 x-aggrega-* キーワードは、標準エラーの助言的な注記の中で、キーワード、その位置、代わりに記述すべき宣言的なテーブルを示す warning: 行として報告されます。判定や終了コードを変えることはありません。

Recipe はさらに単独でレンダリングされます。これは単一エンティティの正しさの一側面であり、その主眼ではありません。スキーマと形状の段階を通過した後、validate は Recipe の implements Component をカタログから解決し、テスト対象の Recipe にバインドされたその Component の単一インスタンスを中心に最小限の Aggregate、Manifest、Release を合成し、それに対して実際のコンパイルパイプラインを実行します。まず解決とガード(レンダリングはスキップ)、次に単独出力の実際のレンダリングです。デフォルトを持たない必須の値と必須の infra フィールドは、それぞれ宣言された型のプレースホルダーで埋められます。値は合成された Aggregate に、infra は合成された Release に入ります。その他の値と infra フィールドはすべてリゾルバーを通じてスキーマのデフォルトを取ります。Release はインスタンスを合成されたデフォルト境界にルーティングし、values: を宣言せず、Aggregate が宣言していないコンピュートも宣言しません。プレースホルダーは、フィールド自身が宣言した制約が受け付ける値です。定数または enum が列挙する最初の値、範囲内の数値、その長さで format に沿った文字列、pattern が求める場合はセマンティックバージョン、必要な数のリスト項目、そしてオブジェクトが必須とするすべてのプロパティです。それ以外の pattern、validate: や when: の条件、スキーマの合成、リストがどの項目を保持するかに関する制約は参照されないため、それらに依存するフィールドはプレースホルダーを拒否する場合があります。その場合、validate はその拒否をスキーマ自身の言葉で報告します。レンダリングされたアーティファクトは出力されるため、作成者はエンティティを完全な Aggregate に組み込む前に単独の出力を確認できます。単一エンティティのハーネスはこれらの必須フィールドのみを埋め、接続を配線せず、Feature もアタッチしないため、接続またはアタッチされた Feature のみが提供する値をテンプレートが読み取る Recipe は単独でレンダリングできません。validate はそのようなレンダリングを失敗ではなく未試行として報告します。fail を呼び出すアサーションは、チェックを失敗させるのではなく警告として報告されます。失敗したアサーションは警告になるを参照してください。その他の理由で停止したレンダリングは完了しておらず、validate は停止の原因を示す文に至るまで、基になるレンダリング診断とともにそれを報告します。

source: をフェッチする必要がある Recipe はまったくレンダリングされず、接続またはアタッチされた Feature のみが提供する値を読み取る途中でレンダリングが停止する Recipe は、そのレンダリングが保留扱いになります。後述の単一エンティティの正しさがチェックしないものを参照してください。

FeatureRecipe はスキーマと形状がチェックされます。そのレンダリングはスキップされます。FeatureRecipe はホストコンポーネントにアタッチされたときにのみレンダリングされ、任意の Feature に対してガードを通過するホストを合成することは試みられないためです。

Release の条件でエンティティをチェックする

ワークスペースは各 Release に独自のカタログディレクトリを与えることができ(Release に独自のカタログディレクトリを与えるを参照)、それにより Release ごとに 1 つのカタログバリアントを並べて保持できます。単独で指定されたエンティティパスはワークスペース自身のカタログディレクトリに対してチェックされ、そこではそれらのバリアントのいずれかへの参照(Recipe が実装する Component、ピラーが参照する SchemaLibrary)は見つかりません。エンティティパスと並べて --release を指定すると、同じチェックがその Release の条件で実行されます。エンティティの参照は、ワークスペース設定がその Release に与えるカタログディレクトリ(--catalog があれば先頭に追加)を通じて解決され、これはその Release のビルドが読み取るディレクトリです。

MariaDB + Adminer の例は、このようなバリアントを 4 つ保持しています。その synth バリアントの Component は、synth と chart のバリアントのみが持つ SchemaLibrary からストレージ設定を取得するため、それを使ってビルドする Release の条件では検証に成功します。

$ aggrega validate catalog-helm-synth/component/mariadb.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/component/mariadb.yaml
Kind: Component
Schema: valid
Pillars: valid

そして、そのライブラリを持たないディレクトリの Release の条件(--release release-compose.yaml、または独自のカタログディレクトリを列挙していないワークスペースで --release をまったく指定しない場合)では、解決できなかったライブラリを示して失敗します。

Recipe も同じ方法でチェックされます。synth バリアントの Recipe は core/datastore/mariadb を実装しますが、ワークスペース自身のカタログディレクトリはこれを保持していないため、単独で指定すると render: implements target "core/datastore/mariadb" not found in catalog で失敗します。それを使ってビルドする Release を指定すると、その Release の Component を解決し、単独でレンダリングします。

$ aggrega validate catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.
Resolution: valid
Render: 3 artifact(s)

その後に 3 つのレンダリングされたアーティファクトが続きます。この例のすべてのバリアントが core/datastore/mariadb を宣言しているため、Recipe は 4 つの Releases それぞれの条件で検証に成功します。そのような Component を保持しないカタログディレクトリの Release の条件では、--release なしの場合と同様に、ターゲットを示して失敗します。Attachments: の行については必須のアタッチメントスロットまたは存在の義務で説明しています。

これは依然として単一エンティティのスコープです。チェック、レポート、終了コードはこのセクションで説明するものです。文法が拒否するソケットまたはスロットのセレクターを持つ Component や Feature は、--release なしの場合とまったく同じようにここで失敗します(宣言されたセレクターを参照)。また、クロージャは検証されません。--release は、エンティティの参照を読み取るカタログディレクトリを持つ Release を指定するものであり、チェック対象のクロージャを指定するものではありません。そのため、エンティティパスと並べた --ir-graph は拒否されます。存在しないファイルやディレクトリを指定する --release は、何もチェックされる前に拒否されます。

ワークスペース設定が列挙するディレクトリがディレクトリでない場合(たとえばそこに何も存在しない場合)、その Release について、または --release が指定されていない場合はワークスペースについて、何もチェックされる前に拒否されます。これは、そのカタログを読み込むすべてのコマンドが拒否するのと同じです(ローカルエンティティの読み取り元)。拒否はエントリ、それを列挙している設定ファイルと行、および設定項目を示し、判定は示されません。aggrega serve を通じたエディタのエンティティチェックは、同じ拒否をエンティティのファイル上の唯一のエントリとしてエラーレベルで示し、aggrega mcp の validate ツールはそれによって呼び出しを拒否します。

未入力のプレースホルダー

種別が必須とする値のうち、ファイルが空文字列のまま残しているものはプレースホルダーであり、validate はそれを他の何よりも先に報告します。aggrega scaffold が下書きしたドキュメントは、その種別が作成者にしか与えられない値を必要とする箇所すべてにプレースホルダーを持つため、どれが残っているかはここでわかります。以下は、バージョンだけを埋めた下書きの FeatureRecipe です。

Entity: my-feature-recipe.yaml
Kind: FeatureRecipe
2 placeholders still owed in my-feature-recipe.yaml; an empty required value is not a value, so each of these needs one before the document validates:
7:3: spec.capability takes what its schema describes: The explicit provider capability this recipe binds to (e.g., 'helm', 'terraform', 'compose') — the provider kind that renders it.
8:3: spec.implements takes what its schema describes: Declares which catalog Feature type this recipe is able to implement (including credential Features labeled feature.aggrega.ai/kind: secret; exact version, major-compatible range '^', or unversioned).

ファイル内のすべてのプレースホルダーが、ドキュメント順に、行と列、そして何を受け付けるかとともに一度に示されます。何を受け付けるかは種別自身のスキーマから読み取られます。スキーマが値を列挙している場合は受け付ける値、スキーマが求める場合は 1.0.0 のようなセマンティックバージョン、それ以外の場合はそのフィールドについてのスキーマ自身の説明の最初の文です。

どの値が対象になるかもスキーマから読み取られます。種別がドキュメントの最上位で、または種別が同じく必須とするオブジェクトの内部で値を必須とし、ファイルがそれを空文字列に設定している場合に、その値が対象になります。ファイルがキー自体を省略している場合は、スキーマチェックが欠落したプロパティとして報告します。空のままの任意フィールドはプレースホルダーではなく、自分で書くことを選んだリストやマップの内部でのみ必須となるフィールドも同様です。スキーマ自体がフィールドの受け付ける値に空文字列を含めている場合、空の値はプレースホルダーではなく値です。

スキーマが空を受け付ける場合でも値は必要です。 スキーマは Recipe や FeatureRecipe の capability と implements に空文字列を認めますが、空のものはプロバイダーも型も指定しないため、validate はどちらも他と同様にプレースホルダーとして報告します。スキーマチェックも同じファイルを拒否する場合(空のバージョン、値のない型ラベルなど)、aggrega scaffold の例が示すように、報告にはそのチェックのコード E0215 が付きます。上の例のようにスキーマチェックが受け付ける場合、報告にコードは付きません。同じファイル内の空の値に関するものではない指摘も、スキーマチェック自身の文言で、一覧の前に報告されます。

この読み取りは単一エンティティの検証に属し、エンティティパスの横に --release があってもなくても適用されます。同じドキュメントに出会ったカタログ全体の実行はスキーマチェックが報告する内容を報告するため、カタログディレクトリ内の implements が空の FeatureRecipe はそれを通過します。Release スコープと aggrega build もこの読み取りを適用しません。

このスコープが受け付けない種別

単一エンティティの検証は Component、Feature、Recipe、FeatureRecipe、Workload、Plugin を受け付けます。それ以外の種別のファイルは拒否され、拒否のメッセージは受け付ける種別と、エンティティ種別の場合はその種別のドキュメントを実際にチェックするスコープを示します。

kind "Aggregate" in "aggregate.yaml" is not a single-entity validation target; the kinds this scope accepts are Component, Feature, Recipe, FeatureRecipe, Workload and Plugin. An Aggregate is checked by the whole-catalog scope when it sits in a catalog directory, and by the Release scope over a Release that deploys it

カタログ全体のスコープは引数なしの実行であり、Release スコープはエンティティパスなしの --release です。

種別チェックするもの
Aggregateカタログディレクトリ内にある場合はカタログ全体の実行、それをデプロイする Release に対する --release
Manifestそれを指定する Release に対する --release
Release--release <release-path>
SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibraryカタログディレクトリ内にある場合はカタログ全体の実行

カタログ全体の実行は設定されたカタログディレクトリ内にあるものだけを読み取るため、ワークスペースのルートに Release と並べて置かれた Aggregate は、その Release に対する --release でチェックされます。

失敗したアサーションは警告になる

fail を呼び出すアサーション(Recipe が宣言するもの、またはその implements Component が宣言するもの)は警告として報告され、チェックはそれによって失敗しません。合成された Release は、実際の Release が設定する値の代わりにプレースホルダーとスキーマのデフォルトを持つため、そうした値、イメージ、前提条件の存在に対するアサーションは、Recipe が健全かどうかにかかわらずここで失敗します。validate は、Release を待っているアサーションと壊れているアサーションを区別できません。アサーションの判定は、常に Release を持つビルドに委ねられます。

警告は標準エラーに、アドバイザリーの注記の後に、warning: で始まって書き出されます。警告はアサーションの完全なメッセージ(エンティティ、インスタンス、アサーションの名前、作成者が書いた文)を含み、最後にもう一文が続きます。

A Release must satisfy this assertion before a build of it can pass.

標準出力の報告は実行がどこで止まったかを示し、コマンドは 0 で終了します。Recipe 自身のアサーションはレンダリングを停止させるため、報告は Resolution: valid の後に Render: stopped on a failed assertion, reported as a warning となります。Component のアサーションは何かがレンダリングされる前に評価されるため、報告は Resolution: stopped on a failed assertion, reported as a warning となり、その後に Render: not attempted (the run stopped on that assertion) が続きます。いずれの場合も何もレンダリングされないため、成果物は出力されません。

警告になるのは fail を呼び出すアサーションだけです。読み取るキーが見つからずに停止するアサーションや、パースできないアサーションは、失敗したアサーションではなくアサーション自身のテキストの不具合であり、他の停止と同様に判定されます。それ以外の不具合はすべて、引き続きチェックの判定となります。

アサーションを満たさない Release の aggrega build は、常にそうであるように、アサーションを名指しし作成者の文を含むエラーで停止します。その Release に対する aggrega validate --release も、同じエラーで失敗します。aggrega serve によるエディターのエンティティチェックは同じ警告を示し、Recipe がアサーションを宣言している場合はそのアサーション自身のキーの上に表示します。aggrega mcp の validate ツールは valid: true を返し、警告を notices に含めます。

単一エンティティの正しさがチェックしないもの

実際のビルドが行うチェックのうち 4 つは、単一のビルドでは手が届きません。validate は、裏付けのない指摘を報告する代わりに、それぞれを見送ります。

取得が必要なソース

単一エンティティの検証は、ロックファイルを読まず、キャッシュの読み書きをせず、ネットワーク要求も行いません。そのため、source: がトランスポート経由で取得するもの(OCI や HTTPS のチャートリポジトリ、Git リポジトリ)を指定する Recipe には、レンダリング元となるインフラストラクチャコードがありません。チャートやモジュールは実行が到達できる場所のどこにも存在せず、チェック対象のファイルには何の問題もありません。validate はそのことを伝え、レンダリングとは別の結果として出力し、0 で終了します。

Entity: catalog/recipe/helm/openbao/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Resolution: valid
Render: not attempted (this Recipe's source is fetched)
Validating one entity on its own reads no lockfile, reads and writes no
cache, and makes no network request, so the chart or module this Recipe
names is never retrieved and there is nothing to render from. To render
it, build a Release that deploys a component this Recipe implements.

その行より上のものはすべてチェックされ、有効として報告されています。したがって、このような Recipe に対する終了コードの意味は、レンダリングされたものより狭くなります。スキーマ、形状、解決は成り立っていますが、レンダリングは未証明です。報告はそのどちらを読んでいるのかを明示します。

ワークスペースがすでに保持しているソースは見送られません。 相対パスの source: ./module は取得を必要としないため、他と同様にレンダリングが試みられ、その失敗は実際の指摘として、ゼロ以外の終了コードとともに Render: not completed in isolation と報告されます。上の行は、取得が必要なソースの場合にのみ表示されます。

取得が必要なソースを持つ Recipe を実際にレンダリングするには、その Recipe が実装するコンポーネントをデプロイする Release に対して aggrega build を実行します。ビルドは Release のロックファイルとローカルキャッシュを通じてソースを解決し、それによって validate には入手する手段のないバイトが供給されます。

必須の uses ソケット

2 つ目は、implements Component の required: true な uses ソケットが埋まっているかどうかです。

必須ソケットは、別のコンポーネントへのエッジを配線することで埋まります。配線元は Aggregate 自身の uses ブロック、または Component が宣言するソケットを配線する Release です。合成されたハーネスは単一のインスタンスしか持たないため、そのようなエッジの対象となる 2 つ目のコンポーネントは含まれず、合成されたドキュメントをどう記述しても生み出すことはできません。相手を作り出すことは、ハーネスが宣言していないコンピュートを作り出すことを意味するからです。そのため validate は、チェックしなかったソケットを示したうえで、解決とレンダリングへ進みます。

Sockets: required uses sockets not checked (backend, cache, registry)
Validating a Recipe on its own places its Component in a build of one,
so no other component exists for a required socket to be wired to. Whether
each of these sockets is populated is checked when the Component is deployed
in an Aggregate.

この行は Component が必須ソケットを少なくとも 1 つ宣言している場合にのみ表示され、示されるのは必須のものだけです。任意のソケットは決して列挙されません。未配線のままにしても、どのスコープでも指摘事項にはならないためです。Component が必須ソケットを宣言していない Recipe ではこの行は出力されず、レポートは変わりません。

ルール自体は緩められることも重複することもなく、それに答えられるスコープで問われます。aggrega build は Aggregate と Release のエッジ面をあわせてこのルールを完全に適用し、何も配線されていない必須ソケットで停止します。したがって、単一エンティティの検証に合格した Recipe も、その Component がデプロイされる際には必須ソケットのルールを満たす必要があり、レポートは validate がチェックした内容とビルドがチェックする内容の違いを黙って残さず、そのことを明記します。

必須のアタッチメントスロットまたは存在の義務付け

3 つ目は、implements Component の required: true なアタッチメントスロット(その featuresSchema が宣言する名前付きのバインディングポイント)が埋まっているかどうか、そしてその存在の義務付けが要求する各 Feature 型のアタッチメントが存在するかどうかです。

必須スロットは、その名前で Feature をアタッチすることで埋まります。アタッチは Aggregate または Release で、コンポーネント上またはその上位のスコープで行います。つまり Recipe ではなく、Component がデプロイされる場所です。合成されたハーネスは Feature をアタッチしないため、それが構築するものでこのようなスロットを埋めることはできません。そのため validate は、必須ソケットの場合とまったく同様に、チェックしなかったスロットを示したうえで解決とレンダリングへ進みます。

Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.

この行は Component が必須スロットを少なくとも 1 つ宣言している場合にのみ表示され、示されるのは必須のものだけです。必須スロットを宣言していない Component の Recipe ではこの行は出力されません。保留されるのは必須要件だけで、スロットのラベル制約と許可された配信メカニズムは宣言どおりに維持されます。パースできないテンプレートは引き続き実行を失敗させ、provider が合成できない Workload のような Recipe 自身の不備も同様です。ただし、次のセクションで説明するとおり、Recipe が接続またはアタッチされた Feature だけが供給する値も読み取っている場合は例外です。

存在の義務付け、すなわち Component 上の features.aggrega.ai/requiredType.<label> アノテーションで、いずれかのアタッチメントがそこで指定された Feature 型を持つことを要求するものも、同じ理由で保留されます。ハーネスは何もアタッチしないため、それが構築するもので その型を持つことはできません。validate はチェックしなかった各義務付けをそのラベルと要求する型で示し、解決とレンダリングへ進みます。標準ライブラリの example/compute/service はこれを 1 つ宣言しているため、その Recipe は 2 つのレンダリング済みアーティファクトの前に次のように報告します。

$ aggrega validate aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml --catalog aggrega-catalog
Entity: aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: presence mandates not checked (monitoring: core/prometheus-exporter)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to carry a type the Component requires. Whether
an attachment of each of these types is present is checked when a Release
that deploys the Component is built.
Resolution: valid
Render: 2 artifact(s)

宣言を評価できない義務付け(ラベルが後に続かないアノテーションのプレフィックスや、Feature 型ではない値)は保留されません。それはどのアタッチメントでも修正できない Component 自身の不備であり、validate はビルドと同様にそれで実行を失敗させます。

各ルールは、答えられる場所で問われます。aggrega pull、aggrega build、aggrega validate --release は Release の実際のアタッチメントに対して両方を評価し、何も埋めていない必須スロットや、どのアタッチメントも持たない義務付けられた型でそれぞれ停止します。

接続またはアタッチされた Feature だけが供給する値

4 つ目は、接続とアタッチされた Features がテンプレートの読み取る値を供給したときに Recipe がレンダリングされるかどうかです。

Recipe のテンプレートは、接続が .context.inject と .context.uses の下に配信するもの、およびアタッチされた Feature が .features の下に配信するものを読み取ります。合成されたハーネスは接続を配線せず Feature もアタッチしないため、そうした読み取りはすべて何も見つけません。.context.inject.env の下の読み取りは空の配信パイプに出会い、.context.uses に対する range は接続に出会いません。validate はまず Recipe をレンダリングし、完了したレンダリングは通常どおり報告されます。レンダリングが停止し、かつ Recipe のテンプレート (それらがインポートするファイルやライブラリエントリを含む) がこの 3 つのいずれかの下を読み取っている場合、validate はレンダリングを未実施として報告し、Recipe がそこで読み取る値を示し、レンダリングが停止した文を出力して、0 で終了します。MariaDB + Adminer の例のチャート版は、アタッチされた 2 つのシークレットが埋める配信パイプからデータベースの認証情報を読み取ります。

$ aggrega validate catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml --release release-helm-chart.yaml
Entity: catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.
Resolution: valid
Render: not attempted (this Recipe reads values a build of one cannot supply)
Validating a Recipe on its own places its Component in a build that wires
no connection and attaches no Feature, so nothing supplies what its
templates read under .context.inject, .context.uses or .features. Its
render stopped, and whether on one of those values or on a fault of its
own is not judged here. To render it, build a Release that deploys a
component this Recipe implements.
Reads: .context.inject.env.MARIADB_PASSWORD, .context.inject.env.MARIADB_ROOT_PASSWORD
The render stopped: rendering: [CATALOG_ERROR] instance instance: rendering node "instance": [CATALOG_ERROR] catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml: recipe "mariadb-chart" valuesMapping: [CATALOG_ERROR] valuesMapping[mariadb-chart]: template "valuesMapping[mariadb-chart]" execute: template: valuesMapping[mariadb-chart]:7:30: executing "valuesMapping[mariadb-chart]" at <.context.inject.env.MARIADB_ROOT_PASSWORD>: nil pointer evaluating interface {}.MARIADB_ROOT_PASSWORD

何も見つけず、何も停止させない読み取りは保留されません。完了したレンダリングの中で何もレンダリングしない .context.uses に対する range は、そのレンダリングのとおりに報告されます。

判断を決めるのは Recipe が何を読み取るかであり、レンダリングが何で停止したかではありません。このことには、出会う前に知っておく価値のある帰結があります。そのような値も読み取る Recipe における Recipe 自身の不備(たとえばキーのスペルミス)は、失敗としてではなく、他と一緒に未実施として報告されます。The render stopped: 行にはレンダリング自身の文が含まれるので、どちらだったかを確認でき、その Component をデプロイする Release のビルドがレンダリングを完全に判定します。

接続や Feature によって変わらないため、Recipe が何を読み取るかにかかわらず実行を失敗させる不備が 2 つあります。パースできないテンプレートと、レンダリングが拒否する参照 (レンダリングコンテキストが定義していないルート、または .context.instance_idd のように形が固定されたルートの下の誤入力されたキー) です。Recipe が宣言する fail を呼び出すアサーションは、Recipe が何を読み取るかにかかわらず、保留も失敗もされず、失敗したアサーションが常にそうであるように警告として報告されます。テンプレートが 3 つのいずれも読み取らない Recipe はレンダリングが完全に判定され、停止したレンダリングは原因を示す文とともに失敗します。

validate ツールを備える aggrega mcp も、同じ Recipe に対して同じ判定を返します。このように除外されたレンダーは、診断に何も含まない有効な結果として応答し、上記の行は診断と並んで返されるテキストに含まれます。

単一エンティティモードのカタログ読み込みは寛容です。カタログ内の別の場所にある無関係な壊れたエンティティはチェックを中断させずにスキップされるため、対象を単独で検証することを妨げることはありません。

スキップされたファイルは、それが原因で見つからなくなった Component についても説明します。Recipe の implements のターゲットが見つからず、その Component を宣言するスキップされたファイルがちょうど 1 つある場合、レポートはそのファイル自身の拒否(そのパス、違反している制約、見出し内の条件の短いコード)から始まります。続いて、そのファイルが読み込み時にスキップされたため、カタログにはそれが宣言する ID の下に何も存在しないことを示す note: が続き、さらにそのファイルが必要だった理由として implements target … not found in catalog の失敗が続きます。その Component を宣言するスキップされたファイルがない場合、または複数ある場合は、not-found の失敗が先頭に来て、スキップされたすべてのファイルがその下の note: catalog files skipped at load に列挙されます。これは aggrega build がスキップしたファイルについて示す説明であり、aggrega serve を介したエディタのエンティティチェックと、aggrega mcp の validate ツールも同じ説明を示します。何もスキップされなかったカタログは、通常とまったく同じように報告します。

validate と lint および build の関係

3 つのコマンドは、それぞれ異なる 3 つの問いを扱います。

  • aggrega validate — これは正しいか? スキーマ、ピラー、参照、extends、入力種別のケイパビリティ、および分離されたレンダリングを検査します。ランタイムの状態は読み取らず、成果物も出力しません。
  • aggrega lint — これはカタログ公開の慣例に従っているか? 命名、カテゴリディレクトリとの整合、アノテーションのプレフィックス、バージョン引き上げの大きさ、その他オプトインの公開規律を検査します。lint は validate の 3 つのスコープを踏襲しますが、正しさは一切検査しません。
  • aggrega build — 完全なデプロイメントをコンパイルする。 build には Aggregate + Manifest + Release の完全な閉包が必要で、Provider ネイティブの成果物を出力します。コンパイルの一部として自身の依存閉包を検証し、その後レンダリングします。aggrega validate --release は、その依存関係の検証をレンダリングなしで単独に行うものです。単一エンティティの validate は、完全な Aggregate なしで単一の Recipe のレンダリングを分離して行います。

例

カタログ全体を検証します:

aggrega validate --catalog ./catalog

1 つの Release が依存するものだけを、ビルドする前に検証します:

aggrega validate --release releases/production.yaml

1 つのエンティティを検証し、Recipe の場合はその分離されたレンダリング出力を確認します:

aggrega validate core/datastore/postgres/recipes/helm.yaml

ワークスペース設定が独自のカタログディレクトリを与えている Release の観点で、1 つのエンティティを検証します:

aggrega validate core/datastore/postgres/recipes/helm.yaml --release releases/production.yaml

関連項目

  • ./aggrega-lint.md — 同じ 3 つのスコープにわたって慣例を扱う対応コマンドです。
  • ./aggrega-build.md — 完全な Aggregate + Release をアーティファクトにコンパイルします。コンパイルの一部として、その依存関係の閉包を検証します。
  • ./aggrega-inspect.md — レンダリングに進まずに、解決後の IR グラフを照会します。
  • ../errors/warnings.md — validate が notice: 行として表示する助言的な指摘です。

概要

aggrega validate [entity-path] [flags]

説明

Check CORRECTNESS across three symmetric scopes.
With no argument, validate checks the WHOLE catalog: schema-pillar
structure, cross-document library resolution, extends chains, and provider
input-kind capabilities, over every catalog entity. Where the workspace
configuration gives its Releases catalog directories of their own under
workspace.releases, it checks the catalog once for each Release, over the
directories that Release reads, and reports each pass under a line naming
its Releases and those directories; Releases reading the same directories
share one pass.
With --release, validate checks the entities a Release's dependency closure
reaches: closure-scoped pillars, extends, and pre-render authored-value
conformance — the same correctness a build applies, scoped to that Release.
It then evaluates the Recipe and FeatureRecipe assertions against the values
that Release resolves to, as a build does before it renders, and reports a
failing assertion as a build reports it. Nothing is rendered.
With an entity path, validate checks one entity file. The kinds it accepts
as a single-entity target are Component, Feature, Recipe, FeatureRecipe,
Workload and Plugin. A value the kind requires that the file leaves empty is
reported first, as a placeholder still owed: every one is named at once, with
what it takes, read from the kind's own schema. That reading is this scope's
alone; a whole-catalog run, a Release's closure and a build do not apply it.
Each kind then has its schema checked, then the checks its own kind carries:
pillar structure for a Component or Feature; shape for a Workload,
FeatureRecipe or Plugin; and for a Recipe, shape plus an end-to-end compile
against a minimal generated harness, so its resolution, its guards and a
render of its output are all exercised. Where that Recipe's source is one
that has to be fetched, the render is reported as not attempted instead:
validating one entity on its own reads no lockfile, reads and writes no cache
and makes no network request, so the chart or module it names is never
retrieved and there is nothing to render from. A render that stops while the
Recipe's templates read what only a connection or an attached Feature
supplies — anything under .context.inject, .context.uses or .features — is
reported as not attempted too: the generated harness wires no connection and
attaches no Feature, so that render cannot be judged there, and a fault of
the Recipe's own beside such a read is set aside with it. A template that
does not parse and a reference the render refuses still fail. An assertion
that calls fail, the Recipe's own or one its Component declares, is printed
as a warning closed by a sentence saying a Release must satisfy it before a
build can pass, and does not fail the check: the generated harness sets none
of a real Release's values, so it cannot tell an assertion waiting on one from
one that is broken, and a build still halts on it. Any other kind is refused here
today, and the refusal names the scope that checks it instead: a whole-catalog
run reaches an Aggregate and the library kinds when they sit in a catalog
directory, and --release reaches a Release, the Manifest it names and the
Aggregate it deploys.
With an entity path and --release together, the entity is checked in that
Release's terms: its references — the Component a Recipe implements, a
library a pillar refers to — resolve through the catalog directories the
workspace configuration gives that Release rather than the workspace's own,
so a workspace keeping one catalog variant per Release checks an entity
against the variant that Release builds with. The checks are the entity
path's; no closure is validated.
The command writes nothing to disk.

フラグ

フラグデフォルト説明
--catalog[]カタログディレクトリです。複数回指定できます。各 —catalog <dir> はカタログ検索スタックの先頭に追加されます(最初に一致したものが優先されます)。スタックはワークスペースの catalog_dirs、またはワークスペース設定が workspace.releases の下で独自のディレクトリを与えている Release の場合はその Release のディレクトリで構成され、ワークスペースルートに catalog という名前のディレクトリがある場合はそれで終わります。空として書かれた catalog_dirs リストは、ローカルカタログをまったく読み込みません。
--ir-graphfalseこのコマンドが既に出力するすべてに加えて、この実行で計算した IR グラフを JSON として stdout にも書き出します。作成者が機密として宣言した値はそこから除外されます。代わりにそれらを出力するには —unredacted を渡します。Release をグラフに解決する唯一のスコープである —release スコープに適用されます。これはドキュメントを選択するもので、—response-format はこのコマンド自身のレポートをどの程度書き出すかを設定します。どちらも判定や終了コードには影響しません
--no-unsupported-field-warningsfalseunsupported-field 警告クラスを抑止します。これは、作成したものをターゲットが反映できない場合にターゲットが発する通知です。たとえば、ターゲットが表現できない Workload フィールド(compose のような忠実度の低いターゲットの場合)や、ノードの入力種別に対してターゲットが処理しない aggrega.ai/ アノテーションなどです。その他のレンダリング警告は引き続き表示されます。表示のみに作用し、レンダリング出力は変更しません。レンダリングを行う唯一のスコープであるエンティティスコープに適用されます
--plugin—describe() の自己報告に対して検証する生の .wasm へのパスです。公開前の作成時チェックです。単独では —type が必要です。Plugin エンティティ引数と併用すると、バイナリをエンティティの宣言された型、ケイパビリティの主張、コマンドミラー、ホスト関数レコードと照合します。
--release—Release YAML へのパスです。単独では、解決済みの依存関係の閉包に対して検証します。エンティティ引数と併用すると、そのエンティティを Release の観点でチェックし、その参照はワークスペース設定がその Release に与えるカタログディレクトリを通じて解決されます。相対パスは、ワークスペースルートではなく、コマンドを実行したディレクトリを基準に解決されます。そのディレクトリがどのワークスペースにも属さず、ルートも指定されていない場合、絶対パスは Release 自身のフォルダからワークスペースを見つけます
--response-formatdetailed—release スコープ(エンティティ引数なしの Release の閉包)の出力量です。detailed(デフォルト)はすべての診断と助言行を報告し、concise は診断の件数と最初の診断のみを報告します。判定と終了コードはどちらでも同一です。
--type—バイナリのみの —plugin チェックで用いる Plugin の型で、バイナリが自己報告する型と照合されます。—plugin と併用する場合にのみ意味を持ちます。Plugin エンティティが型を与える場合は省略します(一致しない値を指定すると停止します)。
--unredactedfalse作成者が機密として宣言した値を、除外せずに出力します。その場合、出力が到達するもの(ターミナル、パイプ、ファイル、画面録画)はすべて、それらの値を平文で保持します。—ir-graph が書き出すグラフにのみ作用し、それ以外には作用しないため、—ir-graph が必要です