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

警告とリンター出力

コンパイラがコンパイル中に出力する、致命的ではない警告です。警告はビルドを停止しません。警告が示すのは、記述上の問題の兆候、コンパイラが選択した決定的なタイブレーク、そして開発者のテンプレートが一度も消費しなかったリソースです。各検出結果は、その種類を示すプレフィックス(どのパスが発生させたかに応じて warning:、lint:、または notice:)を付けて stderr に出力されるため、CI パイプラインはそれらを捕捉して再提示できます。レンダリングされた成果物は、警告の有無にかかわらず生成されます。

致命的なコンパイル停止(ビルドを停止する診断)については、fatal-halts.md を参照してください。

すべての advisory(短いコード順)

コンパイラがビルドを停止せずに報告するもののうち、一部はそれ自体が condition です。condition は短いコード(停止する診断が出力するものと同じ 4 桁の識別子)と、メッセージの冒頭に置かれる固定の文を持ちます。以下の表はその一方から他方を引けるようにしたもので、手元にあるコードから、読んでいる行が停止ではなく警告であっても、その検出が何についてのものかを確認できます。

ここに載るかどうかを決めるのは記述ではなく宣言です。 コンパイラが評価するすべてのルールは、違反時の動作(ビルドを停止するか、検出を報告してビルドを完了させるか)を宣言しており、以下の行は後者です。そのため、コンパイラに追加された advisory は手作業で行を書かなくてもここに現れ、停止する condition になったものはここから外れます。

表が対象とする範囲には 2 つの限界があり、コードが欠けていると判断する前に両方を知っておく価値があります。

  • このページのすべてがこれに当たるわけではありません。 以下で説明する検出のいくつかは、宣言されたルールではなく独自のパスによって発生し、condition をまったく持たないものもあります。それらが出力する行は各セクションで説明したとおりですが、引くべきコードがないため表の行もありません。unsupported-field クラスコードがその典型的な形で、condition ではなく検出のクラスを表します。
  • ここに行があっても、以下にセクションがあるとは限りません。 レンダリングの後半で発生する advisory は説明ではなく一覧として記載されるため、コードがここで文に対応し、より詳しい説明は fatal-halts.md の「Conditions that do not halt a build」にある場合があります。そこにはビルドを停止せずにコードを持つすべての condition が一覧されています。

sentinels.md は、ビルドが出力するあらゆる短いコードを、advisory か停止かを問わず引けるページです。手元のコードがどちらの種類か分からない場合は、ここから始めてください。

短いコード冒頭の文
E0004annotation contribution overridden by an explicit value
E0037cross-boundary link between endpoints rendered by different providers is not supported
E0149attachment name is a near miss for a declared slot
E0167Recipe publishes a provides key its Component does not declare
E0173declared parameter is read by no reference in the Aggregate
E0174uses socket name is a near miss for a declared socket
E0256annotation binding declares one path in both pillar lists
E0297inherited boundary directory carries no template variable, so it resolves to the path the extended Release writes to

Schema-pillar-overlap lint

発火条件: Component または Feature が、spec.schema: ブロックの values: と infra: の両方のピラーに、同じネストの深さで同じプロパティ名を宣言した場合です。両方のピラーに同じフィールド名を置くスキーマ作成者は、通常どちらか一方に置くつもりでいます。この lint は重複を指摘し、どちらのピラーがそのフィールドを所有するかを作成者が解決できるようにします。

パイプライン上の位置。 この lint は、スキーマ統合の後、トポロジー構築の前に検証パスで実行されます。コンパクト形式の展開後のスキーマを、$ref: をたどらずに走査し(後述のソフトスキップの規律を参照)、重複する各プロパティを個別の警告として報告します。

出力形式:

notice: LINT: Component "core/compute/web-server:1.0.0" at ./catalog/component/core/compute/web-server/1.0.0/component.yaml declares property "storage_size" in both values: and infra: pillars (path: storage_size)

ネストされたプロパティの場合、パスはピラーのルートからそのプロパティまでのドット区切りパスです。

notice: LINT: Feature "core/db-pool:1.0.0" at ./catalog/feature/core/db-pool/1.0.0/feature.yaml declares property "timeout" in both values: and infra: pillars (path: connection.timeout)

カタログ全体の読み込み(引数なしの aggrega validate)では、上記のように各エンティティを名前とバージョン、および読み込み元のファイルで示します。ビルド、または 1 つの Release の検証では、その Release が到達するエンティティのみを読み込み、各エンティティを名前とバージョンで示します(at core/db-pool:1.0.0)。Release 内のいくつの参照がそのエンティティに到達しても、報告はエンティティごとに 1 回です。Feature を素の名前で指定する Aggregate と、それを名前とバージョンでマッピングする Manifest は 1 つの Feature に到達し、その Feature は 1 回だけ報告されます。

エディタでの表示。 この検出結果は言語サーバーを通じて警告の重大度でエディタの診断に届き、キーの上ではなくファイルの先頭に表示されます。検出結果は編集中のドキュメント内の位置ではなくカタログのエンティティを示すため、マーカーを置く作成用のキーがないからです。成果物のレンダリング段階より前に発生するため、設定は不要です。serve.build_on_inspect が有効かどうかにかかわらず、エディタのセッションに表示されます。

ソフトスキップの方針。 スキーマの分岐が、プロパティ集合を静的に導出できなくする JSON Schema 2020-12 のエスケープハッチのいずれかを持つ場合、ウォーカーは警告を出さずに終了します。対象は $ref(ドキュメント間またはドキュメント内の参照)、patternProperties(キーの形に基づくプロパティ宣言)、true またはスキーマに設定された additionalProperties(分岐が名前を挙げずに受け入れるプロパティ)、および合成演算子 oneOf / anyOf / allOf(分岐ごとに異なるプロパティ集合を宣言しうる選言と連言)です。これらの分岐を走査するには、参照先または合成されたスキーマを lint 時に評価する必要があるか(lint が行わない種類の処理です)、ある分岐の values: プロパティ名が別の分岐の infra: プロパティ名とたまたま衝突した場合に誤検出を生じることになります。lint は該当するネストの深さについて警告を出しません。同じスキーマのより深い階層は引き続き走査され、lint の対象になります。

作成上の注意。 コンパイラはピラー名の重複を拒否しません。この lint は助言的なものです。両方のピラーに storage_size を持つ Component はコンパイルされます。開発者側の values.storage_size と運用者側の infra.storage_size はそれぞれのピラーのスキーマで独立して検証され、Recipe の valuesMapping: テンプレートがどちらのピラーの値をレンダリング出力に流すかを選択します。この lint が存在するのは、この作成パターンがほぼ常に誤りだからです。意図的なピラー間の重複はまれであり、本当にそれを望む作成者は警告を無視できます。ピラー間の仕組み全般(意図的なピラー間の受け渡しが正当化されるまれなケースを含む)については、vocabulary/data-pillars.md の「Cross-pillar mechanics」を参照してください。

Binding-map-overlap lint

発生条件: Manifest のアノテーションバインディングが、同じドット区切りパスを maps.infra リストと maps.values リストの両方で宣言している場合です。このパスは両方のピラーを経由することになりますが、コンパイラの決定的なタイブレークによって infra: を経由して送られるため、values: 側には Aggregate から到達できなくなります。この lint はこの状況を明示し、作成者がバインディングを単一のピラーに絞り込むか、infra 側のみのルーティングを意識的に受け入れるかを選べるようにします。

パイプライン上の位置。 この lint は、Manifest が解決された後、アノテーションの展開が実行される前に実行されます。そのため、Aggregate のアノテーションがそのバインディングに到達するかどうかにかかわらず、ビルドは重複したバインディングを報告します。lint は mappings.features.annotations 配下のバインディングを記述された順に走査し、各バインディングの maps.infra リストと maps.values リストの共通部分を求め、重複するパスごとに 1 件の検出結果を報告します。1 つのバインディング内では、重複するパスはそのバインディングの maps.values リストが宣言する順序、つまり記述した順序で報告されるため、同一の入力に対して繰り返し実行しても同一の順序で報告されます。

出力形式:

lint: annotation binding declares one path in both pillar lists (Manifest, at .spec.mappings.features.annotations, "compliance.aggrega.ai/data-class", on Feature "core/pii-redaction", at path "classifier_endpoint", which the routing tie-break sends through the pillar "infra", declare a second binding under another annotation key to route it through "values")
lint: annotation binding declares one path in both pillar lists (Manifest, at .spec.mappings.features.annotations.audit-scope, "audit-scope", on Feature "core/pii-redaction", at path "retention_endpoint", which the routing tie-break sends through the pillar "infra", declare a second binding under another annotation key to route it through "values")

この 2 行は 1 つの Manifest に対する 1 回のビルドから出力されたもので、ロケーターの違いはアノテーションキーの形によるものです。ロケーターはドキュメントをドット区切りパスで指し示すため、それ自体にピリオドを含む最初のセグメントで止まります。audit-scope はピリオドを含まないのでロケーターはバインディングまで到達しますが、compliance.aggrega.ai/data-class は含むため、ロケーターはそれを保持する annotations ブロックを示します。問題のキーがすべての検出結果で最初に引用される値でもあるのはこのためです。ロケーターが常に保持できるとは限らない唯一の部分だからです。

エディターでの表示。 この検出結果は言語サーバーを通じてエディターの診断にも警告の重大度で表示され、ロケーターが到達する位置に配置されます。通常のキーではバインディング自体に、ピリオドを含むキーでは囲んでいる annotations ブロックに表示されます。ターミナル出力を読まない作成者にも見えます。成果物のレンダリング段階より前に発生するため、設定は不要です。エディターセッションは serve.build_on_inspect が有効かどうかにかかわらずこれを表示します。

プログラムによる照合。 この検出結果は pkg/resolver の ErrAnnotationBindingPillarOverlap を保持しているため、利用側はメッセージテキストの照合ではなく errors.Is でこの種別を認識できます。他のすべての勧告センチネルと同様に、ビルドの判定には影響しません。アクセサーと条件のコードについては sentinels.md を参照してください。

決定的なタイブレーク。 ランタイムは、パスを infra: ピラーのみを経由させることで衝突を解決します。この選択はビルド間で一貫しており、作成者はこれに依存できます。values: 側はバインディングの実効的なルーティングから除外されます。そのパスに到達しようとする Aggregate 側のアノテーションはルーティング先を得られず、ビルドは展開時に Aggregate 側で停止します。この停止については fatal-halts.md の「An annotation routes through a pillar its authoring side may not use(アノテーションが、その記述側が使用できないピラーを経由している)」を参照してください。lint は早期警告の手段であり、その停止が強制の手段です。

記述上の注意。 schema-pillar-overlap lint と同様に、この lint は勧告にとどまります。バインディングはコンパイルされ、ランタイムのタイブレークによって決定的な出力が生成されます。この lint が発生するのは、この記述パターンがほとんどの場合意図しないものだからです。両方のピラーで同じパスをルーティングすることを本当に望むバインディング作成者であれば、異なるアノテーションキーを持つ 2 つの別々のバインディングを記述するはずです。

アタッチメントスロットのニアミス lint

発生条件: component インスタンスが、その Component 型で宣言された featuresSchema スロットのいずれでもない名前で Feature をアタッチしており、その名前があるスロットから 1 編集以内(1 文字の挿入、削除、置換、または隣接する 2 文字の入れ替え)にあり、かつアタッチされた Feature がそのスロットの selector を満たさない場合です。これはスロット名のタイプミスが取る形であり、lint は両方の綴りを示すので、作成者はその組を確認できます。

存在理由: スロットを宣言しても、アタッチメントの対象範囲は閉じられません。どのスロットも宣言していない名前でのアタッチメントは正当です。この開放性によって、1 つのカタログエンティティが、スロットを埋めるアタッチメントと、より広いスコープで共有される認証情報の両方を担えるからです。その代償として、綴りを誤ったスロット名は、作成者が意図したスロットを埋めるのではなく、暗黙のうちに 自由なアタッチメント となります。ビルドは成功し、スロットは単に空のままになります。lint は、まさにそのケースに対する公開された緩和策です。

パイプライン上の位置: lint は解決時に、カタログを考慮するセマンティックガードと同じパスで、解決済みの Aggregate に対して実行されます。各 component インスタンスのアタッチメント名を、そのインスタンスの Component 型で宣言されたスロット名と照合し、ニアミスの組ごとに 1 件の警告を出力します。

出力形式:

lint: attachment name is a near miss for a declared slot (Aggregate nearmiss, at .spec.components.db.features.app_user_passwrod, "app_user_passwrod", on component type "core/datastore/postgres", near the declared slot "app_user_password")

最初の引用値はアタッチメントが記述された名前であり、警告の冒頭の文はこれについて述べています。続く 2 つは、それが何であるかを示す語に導かれています。アタッチメントが置かれている Component 型と、そのアタッチメントが 1 編集以内にある宣言済みスロットです。

エディタでの表示: この警告は言語サーバーを通じてエディタの診断にも、警告の重大度で、問題のアタッチメントキーの位置に表示されます。ターミナル出力を読まない作成者にもその組が見えます。アーティファクトのレンダリング段階より前に発生するため、設定は不要です。serve.build_on_inspect がオンかどうかにかかわらず、エディタセッションに表示されます。

しきい値とそのトレードオフ: lint は、1 編集の距離にある名前だけを、しかも両方の名前が 4 文字以上の場合にのみ組にします。それより短いと、ほぼすべての短い名前が互いに 1 編集以内に収まるため、組にしてもシグナルではなくノイズになります。1 編集を超えると、組はタイプミスに似なくなります。文字の入れ替えは 2 編集ではなく 1 編集と数えます。隣接する 2 文字の入れ替えは最もよくある誤りであり、より厳密な数え方ではそれを見逃すからです。

作成上の注意: lint は助言的なものであり、ビルドの判定を変えることはありません。コンパイラは、作成者がアタッチメントにどのような名前を付けるかを取り締まりません。スロットに似た名前で意図的に Feature をアタッチする作成者は、警告を無視できます。アタッチメントは記述したとおりに動作します。

Feature がスロットに適合する場合は対象外: アタッチされた Feature が selector を満たすスロットから 1 編集の名前には警告は出ません。その組は、タイプミスした自由なアタッチメントではなく、別の名前で記述されたスロットの充填であり、それが問題になるかどうかはスロットが最終的に空になるかどうかにかかっています。これは、すべてのスコープが畳み込まれて初めて判明します。スロットが空のまま残る場合、ビルドは停止してアタッチメントとスロットを示します(fatal-halts.md の「An attachment written under another name fits a slot its component leaves empty(別の名前で記述されたアタッチメントが、component が空のままにしているスロットに適合する)」を参照)。そのため、報告される所見はその停止のみであり、それと並んで警告が出ることはありません。別のものがスロットを束縛する場合、そのアタッチメントは通常の追加アタッチメントであり、何も報告されません。selector を宣言していないスロットにはどの Feature も適合しないため、そのようなスロットに近い名前には常に警告が出ます。

接続は対象外: lint は、component 自身の features: ブロックを読みます。このブロックは開放されています。接続が持つアタッチメントは、そのソケットが宣言するスロットによってのみキー付けされるため、それらのスロットから 1 編集の名前はそこでは正当ではありません。代わりにビルドが停止し、その停止は同じ文の中で、名前が近いスロットを示します。それと並んで警告が出ることはありません。fatal-halts.md の「A connection carries an attachment under a name its socket declares no slot for(接続が、そのソケットがスロットを宣言していない名前でアタッチメントを持っている)」を参照してください。

Uses-socket near-miss lint

発生条件: コンポーネント自身の uses: ブロックが、その Component 型で宣言された usesSchema ソケットのいずれでもないソケットを指定しているものの、そのうちの 1 つと 1 編集以内の差しかない場合です。1 編集とは、1 文字の挿入、削除、置換、または隣接する 2 文字の入れ替えを指します。これはソケット名のタイプミスが取る形であり、作成者がその組を確認できるよう、lint は両方の綴りを示します。

存在理由: ソケットを宣言しても、開発者自身のコンポーネントにおける uses: の対象範囲は閉じられません。どの usesSchema エントリも宣言していないソケット名は合法です。カタログがあるソケットについて何も述べていないことは、その接続が禁止されているのではなく想定されていなかったことを意味し、Aggregate のトポロジーは開発者が所有するからです。その代償として、綴りを誤ったソケット名は、作成者が意図したソケットを配線するのではなく、それ自体が アドホック接続 になります。ビルドは成功し、意図したソケットは配線されないまま残り、アドホックなエッジにはセレクターもエッジごとの契約もありません。この lint は、まさにその場合に対する、明示された緩和策です。アドホックなソケットが何を失い何を保持するかについては、entities/component.md の「Topology Sockets: usesSchema」を参照してください。

対象範囲: コンポーネント自身の uses: ブロックのみです。これは、宣言されていないソケット名が受け入れられる唯一の箇所です。Feature のアタッチメントの uses: は、アタッチされた Feature が宣言するソケットしか指定できず、Release のエッジごとの uses: は、消費側の Component が宣言するソケットしか指定できません。これらのいずれかで名前を誤るとすでにビルドが停止するため、警告が付け加えるものはありません。

パイプライン上の位置: この lint は解決時に、カタログを考慮するセマンティックガードと同じパスで、解決済みの Aggregate に対して実行されます。すべてのコンポーネントインスタンス自身のソケット名を、そのインスタンスの Component 型で宣言されたソケット名と照合し、近似ミスの組ごとに警告を 1 つ出力します。サブアグリゲートから来たコンポーネントは対象外です。その内部のコンポーネントは、このパスの実行後にグラフへ畳み込まれるためです。

出力形式:

lint: uses socket name is a near miss for a declared socket (Aggregate aggregate, at .spec.components.web, "databses", on component type "core/devtool/adminer", near the declared socket "databases")

最初に引用される値は作成者が書いたソケット名であり、警告の冒頭の文が述べている対象です。続く 2 つは、それが何であるかを示す語によって導入されます。ソケットが指定された Component 型と、そのソケットが 1 編集以内にある宣言済みソケットです。警告が明示しない帰結は、上で説明したとおりです。綴りを誤った名前はアドホック接続になるため、セレクターもエッジごとの契約も持たず、作成者が意図したソケットは配線されないまま残ります。

エディターでの表示: この警告は言語サーバーを通じてエディターの診断にも、警告の重大度で届き、問題の名前を含む uses: ブロックを持つコンポーネント上に配置されます。ターミナル出力を読まない作成者でも、その組を確認できます。成果物のレンダリング段階より前に発生するため、設定は不要です。serve.build_on_inspect が有効かどうかにかかわらず、エディターのセッションに表示されます。

しきい値とそのトレードオフ: この lint は、1 編集の距離にある名前同士で、かつ両方の名前が 4 文字以上の場合にのみ組にします。これは attachment-slot near-miss lint と同じ境界であり、理由も同じです。それより短いと、ほぼすべての短い名前が互いに 1 編集以内に収まるため、組にしても有用な信号ではなくノイズになります。1 編集を超えると、その組はタイプミスらしく見えなくなります。入れ替えは 2 編集ではなく 1 編集と数えます。隣接する 2 文字の入れ替えは最もよくある誤りであり、より厳密な数え方ではそれを見逃すためです。

作成時の注意: この lint は助言であり、ビルドの判定を変えることはありません。コンパイラは、作成者がソケットに付ける名前を取り締まりません。宣言済みのソケットに似た名前で意図的にアドホック接続を描く作成者(宣言済みの caches ソケットとは別の目的で cache 接続を並べる場合など)は、警告を無視できます。エッジは書かれたとおりに動作します。警告を抑制するフラグはなく、必要もありません。判定に影響を持たないためです。

Undeclared-provides-key lint(未宣言の provides キーの lint)

発生条件: コンポーネントインスタンスにバインドされた Recipe が、その provides: の下に、インスタンスの Component 型が spec.schema.provides: コントラクトで宣言していないキーを公開した場合です。

存在理由: Component が宣言する以上のものを公開することは正当であり、今後も正当です。provides コントラクトはサブセットが必須でスーパーセットが許可されるため、Component のコントラクトを満たしたうえで追加のキーも出力する Recipe は、そのコントラクトを満たす Recipe です。この lint が指摘するのは、どちらの側からも本来は見えない帰結です。uses: エッジ越しに読み取るコンシューマーは、ターゲットの Recipe がたまたま出力するものではなく、ターゲットの 宣言された コントラクトを参照します。これにより Recipes の交換可能性が保たれます。1 つの Component を実現する 2 つの Recipes はコンシューマーに同じ表面を提示し、それらを入れ替えても、コンシューマーが依存するようになったキーが黙って取り除かれることはありません。そのため、未宣言のキーはエッジ越しに渡されず、それを読み取るコンシューマー側のテンプレートは失敗せずに空の値をレンダリングします。

この検出結果は、その原因、つまりキーを公開した Recipe の位置で報告されます。そこでなら名前を挙げられるからです。コンシューマー側では、そのキーはコンパイラが特定のターゲットに帰属させられないテンプレート参照であり、推測による診断は診断がないよりも悪くなります。そのため、両者は意図的に同じ場所に置かれていません。空の値はコンシューマー側に現れ、説明はここに現れ、どちらも同じビルド出力に現れます。

比較される組み合わせ: バインドされた Recipe が記述した provides: キーと、Component 型が宣言した spec.schema.provides: キーです。この宣言済みの集合は、inject: ブロック内の from: キーがチェックされる集合と同じであるため、両者は Component が何を宣言しているかについて一致します。比較は類似性テストではなく完全一致であるため、前述の 2 つの near-miss lint とは異なり、しきい値を持たず、名前の組み合わせも行いません。

比較される Recipe は、インスタンスが実際にバインドされているものであり、レンダリングがバインドに用いるのと同じインスタンス名とカタログ型で照合されます。そのため、Manifest でのインスタンスごとの Recipe のオーバーライドは平均化されることなく尊重されます。型がカタログのどの Component にも解決されないコンポーネントインスタンスはスキップされます。宣言が読み取られなかったことは、何も宣言しないことと同じではないからです。

パイプライン上の位置。 この lint は解決時に、カタログを認識するセマンティックガードと同じパスで、解決済みの Aggregate に対して実行されます。レンダリングより前に実行されるため、aggrega build だけでなく aggrega validate --release からも表示されます。Aggregate のルートで宣言された Components と、サブシステム内にネストされたコンポーネントの両方が対象です。サブアグリゲートから来るコンポーネントは対象外です。その内部のコンポーネントはこのパスの実行後にグラフへ畳み込まれるため、そのようなコンポーネントの未宣言キーは引き続きコンシューマーから隠されますが、それを指摘するアドバイザリは出ません。

出力形式: コンポーネントインスタンスとキーごとに 1 行で、キーを公開した Recipe と、それを宣言していない Component を示します。

lint: Recipe publishes a provides key its Component does not declare (Recipe broker-with-region, at .spec.provides.region, "region", on component type "core/ai-model/openai-compatible", bound to component instance "gateway")

検出結果はそれを持つインスタンスに属するため、1 つの Component 型の 10 個のインスタンスが同じ未宣言のキーを公開すると、1 行ではなく 10 行が出力され、それぞれが自身のインスタンスを示します。各行はキーを公開した Recipe に帰属します。それが解決のために編集するドキュメントだからです。走査は決定的であるため、同じ入力からは毎回同じ勧告の並びが生成されます。

エディタでの表示: この勧告は言語サーバーを通じてエディタの診断にも警告の重大度で表示され、type: が Recipe をバインドしているコンポーネントインスタンスの位置に示されます。ターミナル出力を読まない作成者にも表示されます。アーティファクトのレンダリング段階より前に発生するため、設定は不要です。serve.build_on_inspect がオンかどうかにかかわらず、エディタのセッションに表示されます。

作成時の注意: この lint は勧告であり、ビルドの判定を変えることはありません。Component が宣言する以上のものを公開する Recipe も問題なくビルドされます。修正方法は 2 つのうちのいずれかで、どちらが正しいかは作成者の判断です。コンシューマーに読み取らせる意図があるなら Component でそのキーを宣言し、それが Recipe 自身の作業用の状態であるなら未宣言のままにします。その場合、そのような状態の置き場所は locals: です。逆のケースは勧告ではありません。Recipe が公開しないキーを Component が宣言すると、コントラクトが満たされず、ビルドは停止します。

Ghost Infrastructure Tracker の警告

発生条件: 作成者が宣言したキーがノードに到達し、バインドされた Recipe が宣言するどのテンプレートもそのキーを参照しない場合です。読まれないキーはサイレントなインフラストラクチャになります。つまり、開発者やオペレーターが求めた設定を、Recipe がレンダリング出力へ一切配線しない状態です。トラッカーはこれらを表面化させ、作成された内容と出力が含む内容との食い違いを、サイレントにせず可視化します。

比較される作成キー: ノードごとに 3 つのグループです。

  • .values — ノード自身の開発者側の柱です。
  • .infra — ノード自身のオペレーター側の柱です。
  • .context.uses.<alias>.values — ノードが消費に用いる各 uses: エッジに載る接続ごとの値です。このグループは自然にコンシューマースコープになります。ノードの uses マップはそのノードが始点であるエッジのみを保持するため、読まれない接続ごとの値は常にそれを作成したノードに帰属し、エッジのターゲットに帰属することはありません。

収集される参照: バインドされた Recipe が宣言するすべてのテンプレートです。この警告はキーが何にも読まれないと述べるもので、Recipe 全体についての主張です。そのため Recipe 全体より狭い範囲では、近似ではなく誤りになります。source: 座標が消費するキーが、そのキーが指定したバージョンを取得した当の実行によって未読と報告されてしまうからです。読まれるブロックは次のとおりです。

  • valuesMapping:。provider に渡される values オーバーレイです。
  • source: — 単一の文字列として作成されている場合はフィールド全体、オブジェクトとして作成されている場合はその文字列値のフィールドすべてです。source 座標は消費するインスタンスごとに評価されるテンプレートであるため、.values や .infra から選ばれたバージョン、チャート名、git 参照、モジュールのサブディレクトリは、それらのキーを読みます。
  • locals: と provides: の各エントリです。
  • assertions: の各エントリです。
  • workload:。合成される Workload の本体です。
  • artifacts:。各エントリの内容です。
  • pipeline:。各ステップの with: 入力と when: ゲートです。

これには 3 つの制限が伴い、3 つとも選択ではなく、正直に主張できる範囲の限界です。いずれも読み取りを広げるのではなく黙らせる方向に働き、それが最もコストの低い方向です。報告されないキーは、Recipe を読めば見つけられるアドバイザリを 1 件読者から失わせるだけですが、誤って報告されたキーは、機能している設定が無視されたと読者に告げてしまいます。

  • インラインの valuesMapping: を持たない Recipe はまったく読まれません。他のテンプレートが何をしていても、そのキーは報告されずスキップされます。
  • Recipe がファイルやライブラリ参照からインポートするブロックはこの時点で手元にないため、その参照は収集できません。ノードのキーは報告されず、完全にスキップされます。これはインポートされた valuesMapping:、インポートされた workload:、インポートされた artifacts: エントリのいずれにも同様に当てはまります。
  • パースに失敗したテンプレートは参照セットをまったく生成しません。すべてのキーを未読と報告すると、同じテンプレートに対して評価が出すパース診断が埋もれてしまうため、代わりに何も報告しません。artifacts: エントリは標準の {{ }} 区切り文字で読まれますが、これはすべての provider がそのフィールドに宣言する組とは限りません。誤った組で読むと、そのような本体は作成者が書いていない参照を生じるか、パースできないかのどちらかであり、どちらの結果も警告を黙らせる方向にしか働きません。

ソケットの valueSchema が指摘されることはありません。 usesSchema.<socket>.valueSchema は、接続ごとの値が満たすべき契約を宣言します。これはスキーマであって作成されたインスタンスではなく、比較対象の入力にも含まれないため、報告されることはありません。ソケットの宣言済みデフォルトが生成するものは他と同じインスタンスであり、それ自体の状況に応じて読まれたり読まれなかったりします。

柱全体を指す参照は、その配下のすべてのキーを読まれたものとして数えます。 {{ .infra.port }} は port を読まれたものとし、柱の他のキーは警告の対象のまま残します。{{ optional .infra `port` 8080 }} は .infra マップ全体を関数に渡すため、収集される参照は配下のキーではなく柱を指し、その柱のすべてのキーが読まれたものとして数えられ、柱は何も報告しません。柱を range で反復する場合や、index で uses エントリの 1 つに到達する場合も同様です。キーごとのカバレッジを求める Recipe 作成者は、キーごとの参照を書きます。

これは上記のすべてのブロックに及ぶため、静かな柱を警告の見逃しと読む前に知っておく価値があります。source: のバージョンを {{ optional .infra `source_version` "1.2.3" }} と書いた Recipe は .infra マップ全体を関数に渡しているため、その Recipe はレンダリングするどのノードのどの .infra キーについても何も報告しません。.values の柱は影響を受けません。2 つは別々に数えられます。

パイプライン上の位置: トラッカーはベースレンダリング時に、テンプレート評価と並行して実行されます。Recipe の各テンプレートはパースされて走査され、参照するドット修飾のフィールドパス(.values.port、.infra.replicas、.context.uses.<alias>.values.retry_budget)が収集されます。各グループの解決済みキーセットがそれらの参照の和集合と比較され、その差分が未読セットです。走査されるのは作成されたままの Recipe です。source: 座標は、そのテンプレートがこのインスタンスに対して生成した値ではなく、テンプレートのテキストとして読まれます。

出力形式: 未読キーごとに 1 行で、ノード、グループのパス、キー、およびどのテンプレートもそのキーを読まない Recipe を示します。

warning: node "data.main-db": .values key "database_name" is read by no template in recipe "helm-postgres-sourced-with-artifacts" — correct the spelling, or remove the key
warning: node "data.main-db": .infra key "storage_class" is read by no template in recipe "helm-postgres-sourced-with-artifacts" — correct the spelling, or remove the key
warning: node "frontend": .context.uses.my-api.values key "retry_budget" is read by no template in recipe "helm-web-ui-sourced-with-artifacts" — correct the spelling, or remove the key

この行は Recipe のフィールドを示しませんが、これは意図的です。キーを作成したのは開発者、オペレーター、またはそのキーが載る uses: エッジの作成者であり、いずれも Recipe を編集しません。参照を探したブロックを示すと、その読者が開かないドキュメント内の座標を渡すことになります。この行が示す 2 つの対処は、読者が実行できる 2 つです。キーのスペルミスがよくある原因であり、読まれる予定のなかったキーは削除する価値があります。

順序は固定です。ノードの .values、次に .infra、次にエッジが出力された順の各 uses エイリアスで、各グループ内ではキーがソートされます。したがって同じ入力は、毎回の実行で同じ警告の並びを生成します。

エディタでの表示: この警告がエディタの診断に届くのは、言語サーバーが IR グラフの検査中に成果物レンダリング段階を実行する場合に限られます。すなわち aggrega serve --build-on-inspect、またはそれが上書きする serve.build_on_inspect 設定キー(デフォルトはオフ)です。この設定は、ビルドがレンダリング中に出すアドバイザリを追加するもので、ビルドが停止するチェックは一切追加しません。このエントリは作成キーではなくノードを示すため、Aggregate の kind: キー上に描画されます。

致命的な停止ではなく警告である理由: 開発者は条件付きのテンプレートロジックで、正当に異なる .values のサブセットを消費することがあります。テンプレートが .values.mode で分岐する Recipe は mode を読みますが、.values.replication_password は mode == "replication" の場合にのみ条件付きで読みます。静的な走査では、参照されないキーが無関係なのかバグなのかを判別できません。トラッカーの目的は食い違いを取り締まることではなく可視化することであり、トラッカーが防ぐ障害モードはサイレントな欠落です。

Recipe 作成者の対応: Recipe 作成者が、Recipe に消費させるつもりだったキーについて Ghost Infrastructure 警告を見た場合は、そのキーをテンプレートに配線するのが修正です。未読キーが意図的な省略である場合(チャートがサポートしない機能、Recipe が意図的に無視する作成上の便宜など)は、作成者は Recipe のヘッダーコメントにその省略を記載し、将来の読者が食い違いが意図的であることを分かるようにできます。

読まれない宣言済みパラメーターの警告

発生条件: Aggregate が spec.parameters: の下にエントリを宣言し、その Aggregate 自身のテキスト内のどの {{ .parameters.<key> }} 参照もそれを読まない場合です。

宣言されたパラメーターは、Release ごとに 1 つの値を変化させるためのオーサリング面です。Release が宣言を満たし、参照がその満たされた値を、それが属するコンポーネントの値へ運びます。何も読まない宣言は、その変化の行き場を失わせます。Release が何を供給しても、レンダリングされる出力は同じです。これは、何も消費しないオーサリングされた values キーが持つのと同じ問題の、パラメーター版です。

デフォルトは免除になりません。 どの参照も読まないデフォルトは、Release が供給する値と同様に出力へ届かないため、デフォルト付きの宣言もデフォルトのない宣言とまったく同じように報告されます。

収集される参照。 Aggregate 自身のテキストのみで、それ以外は含みません。次の 3 つの帰結があります。

  • Component スキーマの validate: 述語からのみ参照されるパラメーターは、ここでは見えません。そのような述語は、Aggregate 内のドット区切りの参照ではなく、解決済みのパラメーターマップを通じてパラメーターを指すため、述語が読んでいても宣言は読まれていないと報告されます。
  • テンプレートとして解析できないテキストからは、参照の集合は得られません。すべての宣言を読まれていないと報告すると、同じテキストに対して補間が出す診断が埋もれてしまうため、代わりに何も報告しません。
  • parameters マップ全体を指す参照(マップを反復する、または index で 1 つのエントリに到達する)は、すべての宣言を読まれたものとみなします。その場合、収集された参照はその下のキーではなくマップを指し、キーごとの判断ができないためです。

パイプライン上の位置。 この読み取りは、レンダリングの前の解決段階で、Aggregate の生のテキストと宣言されたパラメーター契約に対して実行されます。そのため、aggrega build だけでなく aggrega validate からも表示されます。

出力形式。 読まれない宣言ごとに 1 行で、Aggregate と宣言のロケーターを示します。

lint: declared parameter is read by no reference in the Aggregate (Aggregate fullstack-app, at .spec.parameters.unread_probe, "unread_probe")

検出結果は Aggregate がパラメーターを宣言した順に出力されるため、同じ Aggregate は毎回同じ順序を生成します。各結果は宣言のロケーターを持ち、それが問題のキーを示します。メッセージもキーを示すため、ロケーターも表示するターミナルの行ではキーが 2 回現れます。エディタは配置した位置にメッセージを表示し、ロケーターのテキストは表示しないため、キーを含まないメッセージでは、読まれないすべての宣言が同じ表示になってしまうからです。

エディタでの表示。 このアドバイザリは言語サーバーを通じてエディタの診断にも警告の重大度で届き、Aggregate 全体ではなく、ロケーターが示す宣言の位置に配置されます。アーティファクトのレンダリング段階より前に発生するため、設定の切り替えは不要です。エディタのセッションでは、serve.build_on_inspect が有効かどうかにかかわらず表示されます。

致命的な停止ではなく警告である理由。 パラメーターは、それを読む参照より先に宣言される場合があり、静的な走査ではそれを誤りと区別できません。これは、オーサリングされたキーの読み取りが常に助言にとどまるのと同じ理由です。コンパイラは、作成者がどの設定項目を公開するかを取り締まりません。

Provider バインディングの未提供ケイパビリティ警告

発生条件:ワークスペース設定の plugins.providers 配下のエントリが capability を指定し uri を指定しておらず、ビルドが読み込むプロバイダープラグインのいずれもそのケイパビリティを提供していない場合です。ビルドが読み込むプラグインとは、カタログディレクトリ内のプラグイン、コンパイラに組み込まれたプロバイダー、およびロックファイルに記録されたプラグインです。

存在理由:バインディングは、Recipe の capability: がそのケイパビリティを要求したときにのみ読み込まれます。また、プラグインを指定しないエントリは、それがなくてもケイパビリティの解決が選択するもの以外を何も選択しません。そのため、ケイパビリティの綴りを誤ったエントリ(helm を hlem とするなど)はどこからも参照されず何も変えません。この警告がなければ、そのことを知らせるものは何もありません。

警告であり致命的な停止ではない理由。 バインディングはワークスペース全体に対して一度だけ記述されますが、ビルドは 1 つの Release を対象とします。その capability を提供するプラグインは、ワークスペース内の別の Release だけが読み込むものである可能性があり、このビルドからはそれが見えません。そのため、ここで停止すると、推測に基づいて正当なワークスペースを拒否することになります。プラグインも指定しているエントリは別のケースです。pull は Recipe が使用するかどうかにかかわらずそのようなエントリをすべて解決するため、ビルドはそのプラグインを保持しており、それが何を提供するかを把握しています。そのプラグインが提供しない capability は停止します。fatal-halts.md の「A plugins.providers binding names a plugin that does not serve the capability(バインディングが、その capability を提供しないプラグインを指定している)」を参照してください。ビルドが読み込むいずれかのプラグインが実際に提供する capability のエントリは、この Release 内の Recipe が使用するかどうかにかかわらず、何も報告されません。

パイプライン上の位置。 Release のビルドと検証はいずれも、Release のグラフが解析される前に、合成されたワークスペース設定(各レイヤーとそれに付随する providers_append を合わせたもの)の各エントリを読み込みます。そのため、この警告は aggrega build だけでなく aggrega validate --release からも表示され、さらに aggrega pull からも表示されます。pull は、そのビルドが取得する外部入力を把握するために、これから書き込むロックファイルに対して Release を一度レンダリングします。この判定は、どのプラグインが Recipe をレンダリングするかには何も影響しません。それはロックファイルから読み込まれます。

出力形式:合成されたリストに並ぶ順序で、エントリごとに 1 行を出力します。ケイパビリティ名と、1 編集距離の範囲に提供済みのケイパビリティがあればその名前を示します。

warning: plugins.providers entry names a capability no provider-rendering plugin the build reads serves: capability "hlem", which is one edit from "helm"; the entry names no plugin, so it selects nothing a Recipe would not resolve without it, and none of the plugins this build reads — in the catalog directories, inside the compiler, or among those the lockfile records — serves the capability: correct its spelling, or keep it where the plugin serving it is one only another Release reads

しきい値:綴りの候補は、編集距離が 1 で、かつ両方の名前が 4 文字以上の場合にのみ提示されます。これは上記のニアミス lint と同じ基準であり、理由も同じです。

エディターでの表示:この警告は、言語サーバーを通じて警告の重大度でエディターの診断に表示されます。エントリは編集中のドキュメントではなく設定ファイル内にあるため、キーの位置ではなくそのドキュメントの先頭に配置されます。

エンティティごとのメタデータ対応状況

どのエンティティのエンベロープが metadata.labels と metadata.annotations を持つかは、種類によって異なります。Component、Feature およびライブラリ種別は両方を持ちます。Aggregate はラベルのみを持ちます。Recipe、FeatureRecipe、Manifest、Release、Plugin は、エンベロープのレベルでどちらのキーも受け付けません。エンティティごとの状況は Status of the Language にまとめられており、参照すべき情報源はこのページです。

エディタでの表示。 どの設定でも、これを扱うアドバイザリはありません。報告すべきことがないためです。エンティティはこれらのキーを持つか、受け付けないかのどちらかであり、ある種類が受け付けないキーは、レンダリング段階が後から報告するものではなく、ドキュメントの読み込み時にそのスキーマが判定するものです。作成者は警告を待つのではなく、ステータスページを確認してください。

未サポートフィールドの警告

作成した内容のうちターゲットが反映できないものは、すべて 1 つのクラスで扱われます。このクラスには 2 つのメンバーがあります。ターゲットが表現できない Workload フィールドと、ターゲットが処理しない aggrega.ai/ アノテーションです。両者は 1 つのクラスコードと 1 つの抑制フラグを共有します。「このターゲットが無視するもの」を抑制したい作成者は、スイッチを 1 つずつ切り替えるのではなく、それらをまとめて抑制したいと考えるからです。

ターゲットが表現できない Workload フィールド

ターゲットごとに忠実度は異なります。あるターゲットがネイティブに表現できる Workload フィールドに、別のターゲットでは相当するものがない場合があります。たとえば Docker Compose には、スケジューリング制約、サービスアカウント、優先度クラスという概念がありません。Workload がそのようなフィールドを宣言し、ターゲットがそれを表現できない場合、そのフィールドは警告付きで省略され、作成したフィールド 1 つにつき 1 つの警告が出ます。黙って破棄されることも、致命的なエラーとして扱われることもありません。

致命的な停止との違いは粒度です。サポートされない形式は、ビルドを明示的に停止させます。ターゲットがその形のワークロードをまったく生成できないためです。サポートされる形式が表現できないフィールドを持つ場合は、そのフィールドを除いてレンダリングされ、その旨が報告されます。

compose ターゲットでは、このクラスは現在 scheduling、serviceAccount、replicas、runtimeClassName、priorityClassName、imagePullSecrets、dnsPolicy、dnsConfig.options、コンテナの runAsNonRoot、および nvidia.com/gpu 以外のすべての拡張リソースキー(たとえば amd.com/gpu)を対象とします。これは、そのキーが NVIDIA GPU 用に予約されているためです。以下のケースでは同じクラスの部分的なバリアントが出力され、フィールドは削除されるのではなく縮小されます。

  • persistentTemplate — レプリカごとのボリュームテンプレートは利用できないため、ボリュームは消えるのではなく、共有される単一の永続ボリュームにまとめられます。
  • as: env を持つコンテナの attachments エントリ — compose はアタッチメントから環境変数を取得できないため、その変数は空の値で出力されます。警告はエントリを作成時の座標(containers.<name>.attachments.<KEY>、または位置指定の init エントリの場合は initContainers[<i>].attachments.<KEY>)で示すため、どの変数が空で届き、どのコンテナに属するかが明確になります。as: file を持つエントリは通常どおりバインドマウントされ、何も報告されません。
  • どのコンテナもマウントしない volumes エントリ — 警告はボリュームを作成時の座標(volumes.<name>)で示します。出力に何が届くかはバリアントによって異なります。persistent または persistentTemplate のボリュームは引き続き名前付きボリュームとして宣言され、作成されたまま使われません。一方、configmap、secret、ephemeral のボリュームはコンテナのマウントポイントを通じてのみ出力に届くため、マウントするものがなければ宣言は何も出力しません。いずれにしても、作成したボリュームは何の役にも立っていません。コンテナからマウントするか、削除してください。init コンテナを含め、ワークロードのすべてのコンテナがマウント元として数えられるため、init コンテナだけがマウントするボリュームでは何も報告されません。
  • 複数のプローブスロットを宣言する health ブロック — compose サービスは healthcheck を 1 つしか持たないため、優先順位 live > ready > startup によって 1 つのスロットが残り、宣言された他のスロットは出力のどこにも届きません。警告はブロックを作成時の座標(containers.<name>.health、または位置指定の init エントリの場合は initContainers[<i>].health)で示し、変換されたスロットと破棄されたスロットの両方を挙げるため、出力でどのプローブが有効で、どの作成意図が効果を持たないかが明確になります。スロットを 1 つだけ宣言するブロックは欠損なく変換され、何も報告されません。
  • initContainers も宣言するワークロード上の hostNetwork — ワークロード自身のサービスはノードのネットワーク上で動作しますが、各 init コンテナはそれぞれ独立したサービスとなり、独自にバウンダリネットワークに参加します。メインサービスの名前空間を共有すると、メインサービスによる init コンテナの待機が循環してしまうためです。これはすべてのコンテナが 1 つの名前空間を共有する、モデル化対象の Pod の形より狭いため、実行時に発見されるままにせず、その違いが明示されます。init コンテナなしで hostNetwork を宣言するワークロードは欠損なく変換され、何も報告されません。

ターゲットが処理しないアノテーション

aggrega.ai/ アノテーションは、provider が読み取り、レンダリングする対象に適用するプラットフォームディレクティブです(名前空間、レジストリプレフィックス、サービスアカウントなど)。provider がそのうちどれを読み取るかは、その provider 自身が入力種別ごとに宣言します。自ら合成するデプロイ単位のすべてのフィールドを所有する provider でも、ベンダリングされたアーティファクトをレンダリングする際には同じ値を置く場所がないことが多いためです。Well-Known Annotations がその対応表です。

ノード自身の Recipe と、そのノードにアタッチされた各 feature は別々にレンダリングされます。それぞれ、自身の capability: が指定するターゲットを通じて、自身の source:、workload:、artifacts: が宣言する入力種別でレンダリングされます。そのようなアノテーションがいずれかのレンダリングに届き、解決されたターゲットの宣言がそのレンダリングの宣言する入力種別のどれについてもそのキーを対象としていない場合、ターゲットはそのキーに対して何も適用せず、ビルドはキー、ターゲット、およびそのレンダリングが宣言するすべての入力種別を挙げて警告でその旨を報告します。

warning: node "frontend" (provider "helm-chart"): target "helm-chart" does not support annotation aggrega.ai/namespace on sourced input and ignored it

以下の帰結は、アノテーションがレンダリングに届く仕組みから生じるもので、いずれも意図的なものです。

  • 作成した 1 行から複数の警告が生じることがあります。 バウンダリのアノテーションはその配下のすべての component にカスケードし、それらの component は異なるターゲットや異なる入力種別でレンダリングされることがあります。各警告は 1 つのレンダリングについての正しい記述であるため、そのキーを処理できないレンダリングごとに 1 つの警告が出ます。これにより、出力のどの部分が影響を受けるかもわかります。
  • ノードにアタッチされた feature は、ノードの Recipe ではなく、自身の FeatureRecipe に基づいて判定されます。 独自のリソースを生成するアタッチメントは、その FeatureRecipe が指定するターゲットを通じて、その FeatureRecipe が宣言する入力種別でリソースをレンダリングします。そのため、ノード自身のターゲットが適用するアノテーションがアタッチメントのファイルには何も届かないことがあり、その逆も起こります。それぞれは別のファイルなので、個別に報告されます。名前付き component ではなくバウンダリにアタッチされた feature についても同様です。FeatureRecipe が source:、workload:、artifacts: のいずれも宣言しないアタッチメントは独自のファイルをレンダリングしません。値の注入、その Feature が持つ uses エッジ、または他の何かが出力したドキュメントに対するパイプラインによって寄与します。そのため、アノテーションが欠ける対象となる独自の出力がなく、それについて警告されることはありません。
  • 複数の入力種別を宣言するレンダリングは、そのすべてに基づいて判定されます。 宣言された種別は加算で合成され、それらの出力は足し合わされるため、いずれか 1 つの種別でキーを読み取るターゲットはそれを適用し、値はレンダリングされた出力に現れます。この場合は報告すべきことがないため、何も警告されません。警告が出るのは、宣言されたすべての種別がキーを欠く場合だけで、その警告はそれらすべてを挙げます(on sourced or synthesized input)。
  • チェックされるのは素の aggrega.ai/ キーだけです。 サブプレフィックス付きのキー(compliance.aggrega.ai/data-class や独自の acme.aggrega.ai/team など)は利用者自身の語彙であり、コンパイラは解釈せずにそのまま渡します。それについて警告されることは決してありません。
  • サポートの宣言をまったく持たないターゲットでは、何も報告されません。 警告は、作成した内容を provider が読み取ると宣言した内容と比較します。何も宣言していない provider では比較対象がなく、沈黙から拒否を推測すると、provider の作成者が一度もしていない主張を報告することになります。キーを 1 つも読み取らない provider は、terraform のように readsNoWellKnownAnnotations: true でそれを表明し、その場合はそのレンダリングのいずれかに到達するすべての素のキーについて警告されます。

停止ではなく警告である理由。 異種のターゲット上の component に正当にまたがるバウンダリでは、特定のキーを処理できないノードが必ず存在します。これは複数のターゲットにまたがる Release の通常の形であり、誤りではありません。そのためビルドを拒否すると、正しい Releases を拒否することになります。値はそのまま渡され、警告がその旨を伝えます。

クラスコードと帯域外の保証

各警告は、安定した機械照合可能なクラスコード unsupported-field を持つため、ツールはメッセージテキストを解析するのではなくクラスを照合できます。このクラスのすべてのメンバー(完全に省略されたフィールド、縮小された形式のフィールド、作用されないアノテーション)がこの 1 つのコードを持ち、これにより単一のフィルタでクラス全体を抑制できます。警告はレンダリングされたアーティファクトとは帯域外で伝達されるため、警告が表示されるかどうかにかかわらず、レンダリングされたバイトはバイト単位で同一です。警告を抑制しても出力は変わりません。

エディタでの表示。 このクラスのすべてのメンバーがエディタの診断に届くのは、言語サーバーが IR グラフの検査中にアーティファクトのレンダリング段階を実行する場合に限られます。これは aggrega serve --build-on-inspect、またはそれが上書きする設定キー serve.build_on_inspect(デフォルトでは無効)で指定します。この設定は、ビルドがレンダリング中に発する助言を追加するものであり、ビルドが停止する検査は一切追加しません。上記のクラスコードは、ターミナルの行と同様に公開される診断にも付与されるため、エディタクライアントは作成者が読むのと同じクラスを照合します。各エントリは作成キーではなくノードとターゲットを示すため、Aggregate の kind: キーの位置に表示されます。

クラスの抑制

レンダリングを行う両方のコマンドは --no-unsupported-field-warnings を受け付けます。これはこのクラスのみを抑制し、その他のレンダリング警告はすべて引き続き表示されます。

Terminal window
aggrega build --release release.yaml --no-unsupported-field-warnings
aggrega validate ./catalog/recipe/compose/mariadb/1.0.0/recipe.yaml --no-unsupported-field-warnings

このフラグは表示のみに作用し、レンダリングされた出力は変更しません。aggrega lint にはレンダリングパスがないため、同等のフラグはありません。このコマンドは公開に関する慣例のみを検査するため、レンダリング警告が発生することはありません。

このフラグは、忠実度の低下を意図的に受け入れた場合に使用します。たとえば、ローカル開発に使用する compose ターゲットで、本番用 Workload のスケジューリングやサービスアカウントのフィールドが作用しないことが想定されている場合です。それ以外の場合は無効のままにしてください。作成したフィールドがターゲットに届いていないことは、この警告によって知ることができます。

機密と宣言された値がリテラルとして渡される

発生条件: アタッチメントが、スキーマで機密と宣言されたデータを、ターゲットがデプロイ時に解決する参照としてではなく、リテラル値として配信キーに渡すことでスロットを埋めた場合です。

出力形式。 配信キーごとに 1 行で、アタッチメントインスタンス、キーが配置される配信メカニズム、キー自体を示し、それをレンダリングしたノードとターゲットに帰属させます:

warning: node "db" (provider "compose"): attachment "user_password" delivers a value declared sensitive to env delivery key "MARIADB_PASSWORD" as a literal; where the target supports it, fill the slot with an attachment that delivers a reference instead

クラスコード。 この勧告は、安定した機械照合可能なクラスコード sensitive-by-value を持つため、ツールはメッセージテキストを解析するのではなくクラスで照合できます。このコードはターミナルの行にも、言語サーバーが公開する構造化された診断にも含まれるため、作成者とエディタクライアントは同じクラスを読み取ります。ただし、言語サーバーがこの勧告をそもそも公開するかどうかは、後述のエディタでの表示条件によって決まります。

エディタでの表示。 この勧告がエディタの診断に表示されるのは、言語サーバーが IR グラフの検査中にアーティファクトのレンダリング段階を実行する場合のみです。これは aggrega serve --build-on-inspect、またはそれが上書きする設定キー serve.build_on_inspect(デフォルトでは無効)で有効になります。この設定によって追加されるのは、ビルドがレンダリング中に発行する勧告であり、ビルドを停止させるチェックは一切含まれません。このエントリは作成用のキーではなくノードとターゲットを示すため、Aggregate の kind: キー上に表示されます。

これは独立したクラスであり、--no-unsupported-field-warnings の対象外です。 このフラグは前述の unsupported-field クラスを抑制しますが、この勧告はそれと並んで引き続き表示されます。この勧告を抑制するフラグはありません。

ビルドは成功し、レンダリングされたバイトは変わりません。 この勧告は unsupported-field クラスと同様に、レンダリングされたアーティファクトとは別経路で伝えられるため、行が表示されるかどうかにかかわらず出力に届く内容は同じです。

sensitive と宣言された値が values マッピングを経由してターゲットに届く

発生条件: source: からのレンダリングがターゲットに valuesMapping: の出力を渡し、かつそのマッピングが読み取る values を持つエンティティが values のリーフを sensitive と宣言している場合です。つまり、Component が宣言するリーフに対する Recipe のマッピング、または component にアタッチされた Feature について、その Feature が宣言するリーフに対する FeatureRecipe のマッピングです。マッピングは 1 つのテンプレートであり、その出力キーはテンプレート自身が作り出すものなので、どの宣言もそれらのキーを名指ししません。そのためターゲットは、そのリーフについてキーごとの sensitive マーキングを受け取りません。これは、宣言がどのレンダリング済みキーにも届かない一方で、作成者がなおそれを制御する手段を持っている唯一のレンダリング形態です。

出力形式: 宣言されたリーフごとに 1 行を出力し、作成時の座標でリーフを示すとともに、結合を左右するマッピングを持つ Recipe または FeatureRecipe を示し、それをレンダリングしたノードとターゲットに帰属させます。アタッチされた Feature の行は、その Feature がアタッチされた名前で始まります。1 つの component が 1 つの Feature のアタッチメントを複数持つことがあり、そうしなければそれらの行が同一になってしまうためです。以下の 2 行目は、component api に token としてアタッチされた Feature です:

warning: node "api" (provider "terraform"): "values.token" is declared sensitive, but recipe "terraform/api" maps its values through a valuesMapping whose output keys no declaration names, so the target receives no per-key sensitivity marking for it; where the mapping reads it, the mapping's whole output is marked as carrying a value declared sensitive instead; a recipe declaring no valuesMapping renders the declared leaf paths as its own keys, and the per-key marking travels with them
warning: node "api" (provider "terraform"): attachment "token": "values.token" is declared sensitive, but FeatureRecipe "terraform/api-token" maps its values through a valuesMapping whose output keys no declaration names, so the target receives no per-key sensitivity marking for it; where the mapping reads it, the mapping's whole output is marked as carrying a value declared sensitive instead; a FeatureRecipe declaring no valuesMapping renders the declared leaf paths as its own keys, and the per-key marking travels with them

制御手段とは何か: マッピングがない場合、source レンダリングが受け取る values は宣言されたリーフのパスそのものをキーとするため、宣言はレンダリング済みキーと正確に結合し、マーキングもそれとともに伝わります。Terraform ターゲットでは、これは Declared-sensitive module inputs で説明している生成されるオーバーライドファイルです。マッピングがある場合、実際に届くマーキングはマッピングの出力全体を対象とし、しかもマッピングが宣言された値を読み取る場合に限られます。このマーキングは、プラグインが拒否または警告する際に組み立てるテキストを左右するものであり、レンダリング済みのバイトは一切変更しません。

3 つの形態は意図的に警告を出しません。 artifacts のみのレンダリングと workload のみのレンダリングは、ターゲットに values マップをまったく渡さないため、そこでは values のリーフはどのように作成されていても、マークするレンダリング済みキーを持ちません。boundary にアタッチされた Feature も、その FeatureRecipe が何をマッピングしていても警告を出しません。boundary は values: ブロックを持たないため、そのようなアタッチメントは空の values ピラーに対してレンダリングされ、その Feature の values リーフはいずれもそこでデータを持つことができず、マッピングを削除しても何もマークされません。いずれも作成者が変更できるものではなく、その形態の恒久的な性質であるため、それに関する警告はすべてのビルドで発生し、しかも取るべき対処を何も示せません。この上限については、代わりに Declaring a leaf sensitive で説明しています。valuesMapping: のない source: からのレンダリングも警告を出しません。その場合はマーキングが届くためです。

クラスコード: このアドバイザリは、安定した機械照合可能なクラスコード sensitivity-not-conveyed を持つため、ツールはメッセージテキストを解析するのではなくクラスで照合できます。アシスタントの build ツールは、各検出結果をこのコードとともに advisories の下に列挙します。このコードは登録された条件ではなく検出結果のクラスを示すものであるため、このページ冒頭の表には行がありません。

エディタでの表示: このアドバイザリは、言語サーバーが Release をレンダリングするとき(要求されたビルドまたはビルドプレビュー、あるいは aggrega serve --build-on-inspect による IR グラフの検査、またはこのフラグが上書きする設定キー serve.build_on_inspect(デフォルトはオフ)による場合)には常に、警告の重大度で、ターミナルでのビルドが出力するのと同じ行を伴ってエディタの診断に表示されます。このエントリは作成時のキーではなくノードとターゲットを示すため、Aggregate の kind: キー上に表示されます。

これは独立したクラスであり、--no-unsupported-field-warnings の対象外です。 このフラグはターゲットの忠実度に関する通知を抑制するもので、それは異なる理由による異なる判断です。このアドバイザリはそれと並んで引き続き表示されます。このアドバイザリを抑制するフラグはありません。

ビルドは成功し、レンダリングされたバイトは変更されません。 このアドバイザリは欠落、つまりどのレンダリング済みキーもマーキングを持たないことを報告するものであり、マッピングは通常のサポートされた形態です。そのため停止する理由はなく、この行が表示されるかどうかにかかわらず、出力の内容は何も変わりません。

エンジンが初期化時に取得する Terraform モジュール呼び出し

発生する条件:ビルドがベンダリングする Terraform モジュール、または Recipe に記述された Terraform 本体が module ブロックを宣言し、その source を Terraform がビルドの配置したファイルから読むのではなく、設定の初期化時にダウンロードする場合です。対象は、レジストリアドレス、git・Mercurial・HTTP のアーカイブ URL、S3 または GCS のバケット、絶対パス、あるいはベンダリングされたモジュールの外へ上るローカルパス(ビルドがベンダリングしていないファイルを指します)です。ロックはベンダリングされたモジュールのコミットとアーカイブダイジェストを固定し、Terraform 自身の依存関係ロックファイルはプロバイダーしか記録しません。そのため、こうした呼び出しが指すモジュールはエンジンがその時点で選ぶ任意のバージョンで取得され、このビルドが記録するものはそれをカバーしません。

読み取る対象:モジュールが呼び出されたときにエンジンが読み込む設定ファイル、つまりモジュール自身のディレクトリ直下のファイルと、そこからローカルの source が到達する各ディレクトリ内のファイルです。どこからも呼び出されないディレクトリ内のものは読まないため、モジュールの examples/ や tests/ ディレクトリに書かれた呼び出しは報告されません。読むのは source の記述内容であり、その source が指すモジュールは読みません。Recipe の spec.boundary.artifacts 配下のファイルはコンパイラ自身が評価して書き出し、どのプロバイダーにも渡さないため、そこに書かれた module ブロックは読まれず、警告も出ません。規則の全体はプロバイダーのページの Structural input validation(構造的な入力検証)に記載されています。

出力形式:呼び出しごとに 1 行で、ノードとプロバイダー、次にブロック、それが置かれたファイルと行、記述どおりの source を示します。モジュールの外へ上る source の場合は、ダウンロード先の代わりにその旨を示します。

warning: node "app" (provider "terraform"): module "vpc" (main.tf, line 2) has the source "terraform-aws-modules/vpc/aws", which Terraform downloads when the configuration is initialised, at whatever version it then selects, so no commit or digest this build records covers that module
warning: node "app" (provider "terraform"): module "shared" (main.tf, line 2) has the local source "../shared", which resolves outside the module this build placed, so Terraform reads whatever sits at that path when the configuration is initialised rather than files this build vendored

呼び出しはエンジンが到達する順に並びます。まずモジュール自身のディレクトリ、次にローカルの source が最初に到達した順の各ディレクトリ、ファイル内ではブロックの記述順です。そのため、同じ入力は毎回同じ順序を生成します。レンダリングを行うすべての実行でこれらが出力されます。aggrega build、Release のビルドが何を取得するかを調べるために Release を一度レンダリングする aggrega pull、そしてワークスペースがモジュールを保持している Recipe に対する aggrega validate(その Recipe を単独でレンダリングします)です。

クラスコード:各警告は、安定した機械照合可能なクラスコード module-fetched-at-init を持ちます。そのため、ツールはメッセージ本文を解析せずにクラスで照合できます。このコードは構造化された診断に付随します。アシスタントの build ツールは各検出結果をこのコードとともに advisories の下に列挙し、言語サーバーは各エントリにこのコードを付けて公開します。これは登録済みの条件ではなく検出結果のクラスを示すものなので、このページ冒頭の表には行がありません。

エディターでの表示:この警告は、言語サーバーが Release をレンダリングするたびに、aggrega-build レイヤー上で警告の重大度としてエディターの診断に届きます。レンダリングが行われるのは、要求されたビルドやビルドプレビュー、aggrega serve --build-on-inspect による IR グラフの検査、またはこのフラグが上書きする設定キー serve.build_on_inspect(デフォルトはオフ)の場合です。エントリは記述キーではなくノードを示すため、Aggregate の kind: キー上に表示されます。

これは独立したクラスであり、どのフラグでも抑止できません。--no-unsupported-field-warnings は unsupported-field クラスを抑止しますが、このクラスはカバーしません。

**ビルドは成功し、レンダリングされたバイトは変わりません。**この警告はレンダリングされた成果物とは別経路で伝わるため、ベンダリングされたモジュール、記述された本体、ルート設定は、警告が表示されるかどうかにかかわらずバイト単位で同一です。

停止ではなく警告である理由:別のモジュールを呼び出すモジュールは正当な入力です。Terraform は呼び出されたモジュールを取得し、設定は動作します。作成者が手放すのはそのモジュールに対するビルドの固定であり、これは拒否すべき欠陥ではなく報告すべき事実です。その取得を許容するかどうかは作成者の判断です。

A plugin ran with no recorded digest to check it against(照合する記録済みダイジェストがないままプラグインが実行された)

発生条件: コンパイラがプラグインを実行しようとしており、そのプラグインのバイト列を記録済みダイジェストで管理することになっているにもかかわらず、ワークスペースにそのダイジェストが記録されていない場合です。プラグインは実行されます。この警告は、実行されたバイト列と誰かがレビューしたバイト列とを何も照合していないことを知らせるためのものです。

aggrega pull は、取得したすべてのプラグインのダイジェストを Release のロックファイルに書き込み、以降の解決はすべて、見つけたバイト列をそのダイジェストと照合します。まだ pull されていないワークスペースや、設定が後からアタッチしたプラグインよりもロックファイルが古いワークスペースには、そのプラグインのダイジェストがありません。そのため照合する対象がなく、この行がなければ照合は何事もなく通過してしまいます。

パイプラインのステップ、プロバイダ、または判定ロールにアタッチされたプラグインで、その Plugin エンティティが自分のカタログディレクトリのいずれかで作成されているものにもダイジェストはなく、pull してもダイジェストは付与されません。pull はそのようなエンティティを固定せず、ビルドは毎回その .wasm を新たに読み込みます(通常はエンティティの隣から読み込みます)。pull が記録したものとの照合は行いません。例外は、変換ロールにアタッチされ、そこで作成されたプラグインです。そのバイト列はレンダリング出力を左右するため、pull はそのプラグインについて見つけた .wasm のダイジェストを記録します。記録された後は、ビルドがそのプラグインをダイジェストと照合し、この行はそのプラグインについては出力されません。

warning: plugin "governance/label-injector:1.0.0" resolved from cache with no recorded digest to check it against, so it runs unverified; run `aggrega pull --release <release>` to record it
warning: plugin "pipeline-step/patch" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recorded

これは、ビルド、プル、または検証がほかの警告とともに表示する行です。そのような実行の外でプラグインを解決するコマンド(ワークスペース独自のコマンドラインプラグインのインストール、一覧表示、実行、または lint に使うプラグインを解決する aggrega lint)は、同じ文をインデントなしの独立した行に表示します。

この行は、バイト列の取得元(aggrega pull と aggrega plugin list が使用するのと同じ語)を示し、その取得元に当てはまる内容で終わります。コンテンツキャッシュからのバイト列の場合、対処法は Release を pull することです。これによりダイジェストが記録され、以降そのプラグインの実行はすべて照合されるようになります。カタログディレクトリ内の Plugin エンティティの隣から読み込まれたバイト列の場合、pull がダイジェストを記録するのは変換ロールにアタッチされたプラグインのみで、行にもそのように示されます。そこで作成されたそれ以外のプラグインについては、pull しても状況は変わりません。記録済みダイジェストの管理下に置くには、プラグインを公開し、公開されたエンティティを参照します。

コマンドがそのプラグインを何回解決しても、表示はコマンドごとにプラグインあたり 1 回です。 レンダリングはノードごとにプロバイダを 1 回解決し、自身のロックファイルを埋めるビルドは Release を複数回レンダリングすることがあります。毎回この行を繰り返すと埋もれてしまいます。エディタサービスは、実行している間に 1 回だけ自身のエラーストリームにこれを表示する一方、応答するすべてのリクエストでこれを改めてエディタに報告します。そのため、エディタがどの応答を参照しても、その実行が検証なしで使ったプラグインがわかります。

エディタでの表示: この警告は、実行のほかの助言とともに、警告の重大度でエディタの診断に表示されます。Release の検証ではその Release の Aggregate 上に表示され、エディタが要求したビルドまたはビルドプレビューでは aggrega-build レイヤーに表示されます。記述したキーではなくプラグインを示すため、ファイルの先頭に配置されます。各実行は解決したものを報告するため、このエントリは、実行がプラグインを検証なしで解決している間は残り、そうでない最初の実行で消えます。この警告は判定を変えず、解決を失敗させることもないため、セッションの応答は表示されるかどうかにかかわらず同じです。

2 つの解決では何も出力されません。どちらも見落としではありません:

  • コンパイラが内部に持つプラグイン。 aggrega pull は取得したものを記録しますが、バイナリに同梱されたバイト列には取得するものがありません。そのためダイジェストが記録されることはなく、それを変えるために実行できるものもありません。バイナリそのものがそのバイト列の同一性です。コンパイラ自身のプラグインとそのバージョンは aggrega plugin list で一覧表示され、ロックファイルの toolchain セクションに記録されます。
  • ダイジェストの適用がそもそも想定されていない解決。 aggrega validate --plugin ./some.wasm はコマンドラインで指定したファイルを対象とし、aggrega lint はまさにチェック対象のアーティファクトを検査します。どちらの場合も、プラグインは信頼されるツールではなく検査の対象であるため、照合すべき記録はありません。

停止ではなく警告である理由: ドキュメントの読み取りは、まだ誰も準備していないワークスペースでも行う価値があります。誰かが aggrega pull を実行するまで検証や lint を拒否すると、報告用のコマンドが最も役立つまさにその時点で使えなくなります。aggrega build はロックファイルがまったくない場合にはアーティファクトを生成しないため、ビルドでこの警告が出るのは、ロックファイルにダイジェストが記録されていないプラグインの場合のみです。通常は、カタログディレクトリ内でエンティティの隣から読み込まれるプラグインがこれに当たります。

ロックファイルがない場合は代わりに拒否されるケース: エディタがコンパイラサービスに Release のグラフを要求し、ワークスペースにロックファイルがまったくない場合、サービスはグラフを描画せずに停止し、ロックファイルを要求します。ロックファイルが存在し、単にプラグインのダイジェストが記録されていないだけの場合は前述のケースに当たります。プラグインは実行され、この警告によってそれがわかります。描画されたグラフは読み手がそれをもとに推論するものであり、検証されていないバイト列から構築されたグラフは、照合済みのものとまったく同じに見えてしまいます。aggrega serve を参照してください。

A published archive carries an entry Windows cannot use(公開されたアーカイブに Windows で使用できないエントリが含まれている)

発生条件: aggrega push(またはその --dry-run)が公開するアーカイブのいずれかのエントリに、Windows がそのままの形では保持できないパートが含まれている場合です。具体的には、CON、PRN、AUX、NUL、COM1、LPT1 のように Windows がデバイス用に予約している名前(大文字・小文字を問わず、後に続く拡張子も問いません)か、ピリオドまたはスペースで終わるパートです。aux/x.yaml はディレクトリにそのようなパートを含み、report. と COM1.yaml はファイル名に含みます。Windows 上では aggrega はそのようなエントリの展開を拒否するため、Windows のワークスペースではそのバージョンをまったく使用できません。公開物はそれを pull するすべての人のためのものなので、この警告はすべてのプラットフォームで発生します。これにより、作成者は Windows のユーザーより先にこの問題を知ることができます。

読み取る対象: アーカイブが保持する名前です。まずエンティティのドキュメント自身のファイル名、次にエンティティがその横に指定する各ファイル(Bundling に挙げられているファイル)です。したがって、スキーマファイルをインポートする con.yaml というドキュメントは、自身の名前について警告を受けます。何も指定しないエンティティはドキュメント単体として公開され、利用側は作成時の名前ではなく製品が選んだ名前で配置するため、ファイル名が何であっても警告されることはありません。Plugin はアーカイブを公開しないため、これも警告されることはありません。

出力形式: エントリごとに 1 行を標準エラーに出力します。順序は名前が構成される順(まずドキュメント、次にそれが含むファイルを辞書順)で、標準出力へのドライランまたは公開自体の報告より前に出力されます。

warning: an entry this publication carries cannot be used on Windows (the entry "aux/x.yaml", its segment "aux"). Windows reserves device names such as CON, PRN, AUX, NUL, COM1 and LPT1, in any letter case and whatever extension follows, and does not hold a segment ending in a full stop or a space as written, so a workspace on Windows refuses to unpack the entry. This warning does not stop the publication; rename that segment to publish a version Windows can use

最初の引用値は、アーカイブが名付けたとおりのエントリです。2 番目は、そのセグメント(スラッシュで区切られたパート)のうち Windows が保持できない最初のもので、これが名前を変更すべきパートです。行はこの条件の固定文で始まります。この警告はビルドが評価するルールではなく公開によって発生するため、このページ冒頭の表には行がありません。すべての条件の表では E0344 として掲載されています。

何も拒否しません。 push またはそのドライランは、警告がない場合とまったく同じように実行されるか拒否され、同じように終了します。

ほかに届く先: アシスタントの publish-entity ツールは同じエントリを windows_unusable_entries として返し、aggrega serve は aggrega/publishEntity に対してそれらを windowsUnusableEntries として返します。該当がない場合、いずれも存在しません。aggrega mcp と aggrega serve を参照してください。また、サービスは報告を求めたリクエストに対して、公開の報告の他の内容とともに警告行そのものも渡します。

エディターでの表示: 診断としては表示されません。公開はビルドではないため、ここで問題リストに届くものはありません。サービス経由で公開するエディターは、応答の windowsUnusableEntries を読み取ります。

停止ではなく警告である理由: このような名前は正当なものであり、Linux と macOS ではそのファイルを名前どおりに使用できます。そのため公開を拒否すると、誰が pull するかという推測に基づいて動作するエンティティを拒否することになります。名前を変更するかどうかは作成者の判断です。