aggrega lint
aggrega lint は公開に関する慣例、すなわち命名、カテゴリとディレクトリの対応、アノテーションの接頭辞、スキーマ記述の規律、バージョン引き上げの大きさを検査します。引数によって選ばれる 3 つのモードがあり、同じ慣例の規律を 3 つの範囲で適用します。カタログ全体(引数なし)、単一の Release の依存閉包(--release)、そして 1 つのエンティティファイル(エンティティのパスを指定し、任意で --pre-publish による公開ゲートを付けます)です。どの範囲も、カタログの異なる部分に対して「このコンテンツはカタログの公開に関する規律に従っているか」という同じ問いに答えます。
慣例は正しさとは別のものです。aggrega lint は、コンテンツが正しい形式であるか、コンパイルできるかを検査することはありません。それは aggrega validate の役割であり、こちらは同じ 3 つの範囲に対して、スキーマ、ピラー、参照の解決、extends、入力種別の機能、レンダリングを検査します。セレクター文法で読み取れないソケットやスロットのセレクターは正しさの欠陥であるため、lint はそれについて何も報告しません。カタログ全体に対しても、1 つの Component や Feature に対しても、validate がそれを拒否します。宣言されたセレクターを参照してください。2 つのコマンドは補完し合う関係にあります。validate はコンテンツが正しいかどうかを示し、lint はカタログの慣例に照らして公開できるかどうかを示します。
aggrega lint はオプトインです。コンパイラ自体はカタログの規律について主張を持たないままであり、これらのルールは実行を選択する別のプラグインにあります。aggrega lint を一度も実行しないワークスペースでも、ビルドと公開は行えます。
エンティティのパスは、位置引数として、または --entity <path> で指定できます。--release はエンティティ引数と同時に指定できません。両者は異なる範囲を選択するため、両方を渡すと停止します。
カタログ全体の慣例(引数なし)
引数なしの aggrega lint は、設定されたカタログディレクトリの下で見つかるすべてのカタログエンティティに対して、構造的な公開規律のルールを実行します。検出結果は助言的なものです。warn の重大度で報告され、慣例に関する検出結果だけで停止することはありません。カタログ内の命名、カテゴリディレクトリ、アノテーション接頭辞のずれを一掃するために使用します。カタログディレクトリ内の Aggregate、Manifest、Release、Workload はチェックされずに読み飛ばされます。この処理は、そのような種類ごとの件数をサマリーの後の not checked: 行に示し、どの種類のドキュメントもチェックするエンティティモードを案内します。
カタログディレクトリ配下の YAML ファイルは、いずれかの行がインデントなしで apiVersion: から始まり、その値が aggrega.ai/ で始まる場合(引用符の有無は問いません)、Aggrega ドキュメントです。読み取れない Aggrega ドキュメント、YAML を解析できないもの、または kind、metadata、spec がエンティティのエンベロープの形になっていないもの(たとえばリストとして書かれた metadata)は、ディレクトリの読み込みが終わった時点で E0175 により実行を停止させ、そのようなファイルをすべて、読み込みまたはパーサーが示した理由とともに挙げます。何もリントされず、conventions checked 行も出力されません。読み込めても、どのカタログも保持しない kind を宣言しているドキュメント(たとえば綴りを誤った Componnent、あるいは kind がまったくないもの)は、同じ実行を E0371 により停止させ、宣言している種類とともに上記のファイルと並べて挙げられます。Manifest、Release、および Recipe が自身のディレクトリからインポートする Workload は読み飛ばされます。それ以外の YAML(レンダリングされるまで解析できない Helm チャートのテンプレート、チャートの values、ワークフロー定義)は読み飛ばされます。--release も、そのカタログディレクトリ配下にあるこのようなドキュメントで同様に停止します。
どのディレクトリを読むかは、ワークスペースの形によって異なります。
-
設定が独自の Release カタログディレクトリを指定していないワークスペースは、その検索スタックに対して一度だけチェックされます。検索スタックは、
--catalogディレクトリ、次にworkspace.catalog_dirs、そしてワークスペースルートにcatalogディレクトリがある場合はそのディレクトリです。 -
workspace.releasesの下で Releases を指定するワークスペースは、カタログを複数のバリアントとして並べて保持し、それぞれを独自の Release が読むことができます。そのすべてを一度に処理すると、すべてのバリアントを同時に読むことになり、あるバリアントのエンティティが別のバリアントのエンティティを覆い隠してしまいます。そのため、ワークスペースが保持する Release ごとに一度ずつ、その Release が読むディレクトリに対してチェックされ、どのパスでも--catalogディレクトリが先頭になります。設定が指定していない Release は、ワークスペースのリストを読みます。各パスは、その Release と読んだディレクトリを示す行の下に報告され、その後にそのパスの検出結果と独自のサマリーが続きます。Release release-compose.yaml reads catalog-composeconventions checked: 7 entities, 0 advisory finding(s)Release release-helm-synth.yaml reads catalog-helm-synthconventions checked: 8 entities, 0 advisory finding(s)まったく同じディレクトリを読む Releases は 1 つのパスを共有し、そのパスはそれぞれの名前を示すため、そこでの検出結果は一度だけ報告されます。どのディレクトリも読まない Release(そのエントリが
catalog_dirs: []と記述しているもの)は、チェック対象がないものとして報告され、他のパスは通常どおり実行されます。-o jsonを指定すると、ドキュメントにはpassesも含まれます。これは各パスのreleases、catalogDirs、findings、summaryであり、トップレベルのfindingsとsummaryはすべてのパスをまとめて扱います。ワークスペースが保持する Releases とは、その Release ドキュメントのことです。つまり、kindがReleaseである YAML ファイルで、ワークスペースルート配下のうち、隠しディレクトリとnode_modules、vendor、distの外側にあるものです。
どのパスにも読む対象がない実行は、クリーンなカタログとして報告されるのではなく、拒否されます。エンティティを catalog/ の下に置くか、--catalog を渡すか、workspace.catalog_dirs を設定してください。Releases を指定するワークスペースでは、workspace.releases の下で Release 独自の catalog_dirs を設定することもできます。カレントワーキングディレクトリを暗黙的に列挙することはありません。
カタログディレクトリの下にあり、ワークスペースの外(またはワークスペース外で指定したディレクトリの外)へ通じるリンクは読まれません。実行はそこで停止してリンクを示し、読めなかったドキュメントを含むカタログをクリーンとして報告することはありません。同じディレクトリに対するビルドも同じリンクで停止します。ワークスペースの境界に、このルールとその対処法が記載されています。
Release 全体にわたる慣例(--release)
aggrega lint --release <release-path> は、カタログ全体や単一のエンティティではなく、ひとつの Release の解決済みクロージャが到達するカタログエンティティファイルに対して、同じ構造ルールを実行します。ビルドと同じ仕組みでクロージャを計算し、その後、各エンティティの作成者が所有するカタログファイルを lint します。レジストリで固定され、キャッシュスロットに置かれたエンティティには lint 対象のローカルファイルがないため、スキップされます。公開のルールはローカルで作成されたファイルに適用されます。カタログ全体モードと同様に、検出結果は助言的なものであり、慣例の検出結果だけで停止することはありません。
これは Release 全体を手元に持つ唯一のスコープでもあるため、ひとつの実行を読むルール、つまり The discipline rules で説明している接続資格情報のルールはここで実行されます。このようなルールは、エンティティごとのルールの後に、チェックごとに一度、3 つのドキュメントに対して実行されます。Release がデプロイする Aggregate(作成者が書いたとおりのもの)、extends チェーンを畳み込んだ Release(子の Release は継承したものを持ちます)、そして Aggregate が宣言する各 component について、その component がインスタンスである Component(カタログが解決したもの)です。どのスコープでも同じく、パラメーター値はこれらに含まれません。Release は parameters ブロック(ベースから継承する値を含む)なしで渡され、Aggregate はデフォルト値や、インポートする各モジュールに渡す値なしで渡されます。What a linter plugin is handed を参照してください。その検出結果は Release ファイルの下に報告されます。
これは、同じクロージャの正しさをチェックする aggrega validate --release に対応する、慣例側のコマンドです。
このスコープが実行するリンターは、ビルドと同様に、Release の隣にある信頼済みプラグイン ID の記録に照らして検証されます。いずれかのリンターを実行する前に、--release は設定された plugins.linter のアタッチメントをプラグイン信頼記録と比較します。記録されているプラグイン(リンターまたはゲート)を設定がもうアタッチしていない場合はパスが停止し、キャッシュから読み込んだリンターのアーティファクトが記録されたものでない場合は、実行されずに拒否されます。キャッシュから読み込んだリンターは、ロード時に記録された署名に対しても検証されます。エントリに検証済みの署名が記録されている場合、その事実が示すキャッシュ内の署名データが再度チェックされ、署名の要件にかかわらず、それが欠落しているか異なる場合は E0144 で、読み込んだリンターとは別のプラグインに対して作成されたもの(別のエントリからコピーされた signature)である場合は E0332 でパスが停止します。ワークスペースの信頼設定が署名を要求する場合、署名を記録していないエントリ、またはリンターのエントリがないこと(記録が削除された場合を含む)は、aggrega pull が未署名として拒否するのと同じ設定のもとで、E0331 でパスを停止させます。3 つのいずれも対処法として aggrega pull --release <release> を示します。これはレジストリでリンターの署名を検証して記録し、それが示すバンドルをキャッシュし、ダイジェストと一致しなくなったキャッシュ済みのコピーを書き換えます。コンパイラバイナリ内のコピーから提供されるリンターが、この要件に照らして検証されることはありません。これらは慣例の検出結果ではなくパスの失敗であるため、検出結果では停止しない場合でも停止します。カタログ全体および単一エンティティのスコープは Release を指定せず記録も読まないため、これらのスコープがキャッシュから読み込むリンターは、キャッシュされたマニフェストのみに照らしてチェックされます。これらすべてに先立って、--release は Release が依存するものに対して記録されたすべての撤回を、aggrega build が出力するのと同じ文言の deprecation: 行として示します。ロックファイルがピン留めされた参照に対して記録するマーカーも、信頼記録がリンターまたはゲートに対して記録するマーカーも同様です。そのため、上記の拒否によってパスが停止する場合でも、パスはその旨を伝えます。撤回によって検出結果や終了コードが変わることはなく、存在するものの読み取れない信頼記録は、何も記録していない記録として通過するのではなく、パスを停止させます。
エンティティの規律: ローカルと公開ゲート
エンティティパスモードは、2 つの重大度のいずれかで実行されます。
- デフォルト(ローカル)。 ローカルのエンティティ内容に対して、規律ルールを
warnの重大度で実行します。レジストリへのアクセスは行わず、バージョンバンプのチェックはスキップされます。オーサリング中に使用します。 --pre-publish(公開ゲート)。 エンティティの最新の公開済み非プレリリースバージョンをレジストリから取得し、同じルールをhaltの重大度で実行します。さらに、変更をPATCH/MINOR/MAJORに分類し、提案されたmetadata.versionのバンプが変更に必要な大きさより小さい場合は停止します。公開フローの中で、aggrega pushの前に使用します。--pre-publishは単一エンティティの形式にのみ適用されます。
必要以上のバンプは常に許可されますが、不足するバンプは停止します。エンティティの初回公開(レジストリに以前のバージョンがない場合)ではバンプのチェックがスキップされ、検証が行われなかったことを示す警告が表示されます。
エンティティモードがチェックする種類
エンティティモードは、指定したドキュメントを種類にかかわらず lint し、1 つのエンティティを読み取るすべてのルールに渡します。各ルールは自分がどの種類を対象とするかを自ら決め、対象としない種類を渡されたルールは何も報告しません。そのため、Aggregate、Manifest、Release、Workload(カタログ全体の処理が読み飛ばし、not checked: 行に挙げる種類)を指定しても同様にルールが実行され、その種類を対象とするルールだけが報告できます:
| ルール | エンティティモードで報告対象となる種類 |
|---|---|
| アノテーション接頭辞 | 任意の種類:ドキュメントの種類にかかわらず metadata.annotations を読み取ります。 |
x-aggrega-* 拡張の直接記述 | 任意の種類:ドキュメントの種類にかかわらず spec.schema を読み取ります。 |
| 名前の形式 | Component、Feature、Recipe、FeatureRecipe、SchemaLibrary、MappingLibrary、WorkloadLibrary、ArtifactLibrary。 |
| カテゴリがディレクトリと一致する | Component。 |
| シークレットスロットが sensitive を宣言している | Component と Feature。 |
| メトリクス資格情報のアノテーションが provides と一致する | Component。 |
| Provides が Component で宣言されている | Recipe。 |
| 動的参照、Id の上書き | SchemaLibrary。 |
| Plugin のデフォルト制限 | Plugin。 |
バージョンバンプの比較(--pre-publish) | Component、Feature、Recipe、FeatureRecipe、SchemaLibrary、MappingLibrary、Aggregate、Plugin(コンパイラに組み込まれたプラグインは比較されません)。その他の種類への変更は MAJOR に分類されます。 |
| 接続の資格情報がターゲットのキーと一致する | なし:Release 全体を読み取るため、--release でのみ実行されます。 |
Aggregate、Manifest、Release、Workload は、いずれもスキーマで metadata.annotations も spec.schema も宣言しません。そのため、これらの種類のドキュメントのうち自身の種類のスキーマに適合するものについて、任意の種類を読み取る 2 つのルールは何も報告しません。この 2 つのルールがそのドキュメントについて報告するのは、それでもいずれかのキーを持っている場合だけであり、そのキーは種類のスキーマによって想定外のプロパティとして拒否されます。Aggregate を指定することで加わるのは --pre-publish でのバージョンバンプの比較であり、後述の基準で説明するとおり、公開済みのバージョンと比較します。
バージョンバンプの基準
--pre-publish モードでは、変更は前回公開されたバージョンと比較され、次のように分類されます。
PATCH— ドキュメントまたはコメントのみの変更。MINOR— 純粋に追加のみの変更(新しい任意フィールド、新しいエントリ)。MAJOR— 削除、型の絞り込み、または以前は任意だったフィールドが必須になる変更。
比較はエンティティの種類ごとに行われます。Component、Feature、SchemaLibrary はスキーマを持つフィールドを考慮して比較されます。MappingLibrary はエントリキーのレベルで比較されます(エントリの本体は不透明なため、本体の変更は保守的に MAJOR として扱われます)。Recipe と FeatureRecipe は、その重要なフィールドで比較されます。Aggregate は、パラメーター宣言、コンポーネント、サブシステムで比較されます。パラメーターのデフォルト値は、他のパラメーター値と同様に比較の対象にはならないため(What a linter plugin is handed を参照)、デフォルト値のみに限られる変更(追加、変更、削除)は比較に含まれず、パラメータースロットの語彙に含まれないキーへの変更も同様に含まれません。バンプが不足している場合は、必要なバンプを示す診断とともに停止します。
規律ルール
ほとんどのルールには、.aggrega-config.yaml の lint.publishing_discipline 以下にワークスペースごとの設定と、それに対応する CLI オーバーライドがあり、各オーバーライドには --no- を付けた対になるフラグがあります。優先順位は、カタログ全体、Release、1 つのエンティティというすべてのスコープで、--no-<flag> が --<flag> より優先され、それがワークスペース設定の値より優先されます。すべてのルールはデフォルトで有効であり、各デフォルトはプラットフォームの仕組みか、文書化されたカタログの慣例のいずれかに基づいています。これらの設定は、ルールを緩和する理由があるワークスペースのためのオプトアウトです。
設定を持たないルールは、以下の各項目でその旨を記載しています。理由はいずれの場合も同じで、これらのルールはエンティティに関する事実を報告し、判断を作成者に委ねるため、緩めるべき判断がありません。上述のバージョンアップの基準も設定を持ちません。これは提案された内容を公開済みのバージョンと比較し、その変更が要求するものを報告するもので、ワークスペースの好みではなく変更そのものの性質だからです。
- アノテーションのプレフィックス — 予約された名前空間(
aggrega.ai/、および Feature 以外でのfeature.aggrega.ai/)はプラットフォームが所有しており、それ以外のキーでは拒否されます。デフォルトで有効です。allow_aggrega_ai_prefixでオプトアウトできます。 - 名前の形式 — 各エンティティ種別には名前の形式に関する慣例があります(クラウドネイティブ種別ではセグメント数、ライブラリ種別では PascalCase)。デフォルトで有効です。
allow_nonstandard_namesでオプトアウトできます。 - 動的参照 — SchemaLibrary のエントリでは
$dynamicAnchor/$dynamicRefを使用できません(プラットフォームのコンパイル時の$ref展開ではこれらを解決できません)。デフォルトで有効です。allow_dynamic_refsでオプトアウトできます。 - Id の上書き — SchemaLibrary のエントリは独自の
$idを宣言できません(プラットフォームが正規の$idを導出します)。デフォルトで有効です。allow_id_overridesでオプトアウトできます。 - カテゴリとディレクトリの一致 — Component の
component.aggrega.ai/categoryラベルは、core/配下の最初のディレクトリセグメントと一致する必要があり、閉じたカテゴリ集合(ai-agent、ai-model、ai-tool、ai-pipeline、datastore、gateway、mesh、network、messaging、storage、compute、observability、security、bigdata、devtool)から選ばれます。core/パス配下のエンティティではデフォルトで有効です。allow_category_mismatchesでオプトアウトできます。 x-aggrega-*拡張の直接記述 — Component または Feature のスキーマにx-aggrega-*キーを直接記述することは推奨されず、ファーストクラスの記述方法が推奨されます。デフォルトで有効です。allow_direct_x_aggrega_extensionsでオプトアウトできます。- Component による provides の宣言 — Recipe の
spec.providesはエントリごとに 1 つのキーを公開し、その Recipe が実装する Component は、spec.schemaのprovidesの柱で、その型が公開するキーを宣言します。injectのfrom:参照が照合されるのはこの宣言であるため、Component が宣言していないキーを Recipe が公開すると、そのキーは生成されたうえで、利用側が配線する箇所で拒否されます。宣言された契約を超える公開はビルド時には受け入れられるため、この検出は拒否ではなく助言です。Recipes ではデフォルトで有効です。allow_undeclared_recipe_providesでオプトアウトできます。 - Plugin のデフォルト上限 — Plugin の
spec.runtimeにはmaxMemoryPagesとtimeoutMsがあり、これはホストがプラグインを読み込んで実行する際に適用する 2 つの上限です。どちらも固定しない Plugin はプラットフォームのデフォルトで実行されます。これは安全な結果でありエラーではないため、このルールはデフォルトが適用されていること、および明示的な上限を固定できることを報告します。Plugin エンティティではデフォルトで有効です。設定はありません。 - シークレットスロットによる sensitive の宣言 — アタッチメントスロットは、ラベルセレクタを通じて、そのスロットを埋める Feature の種類を
secretに固定でき、さらに別途sensitive: trueを宣言して、そこを埋めるものが何であれシークレット情報を扱うことを記録できます。セレクタはどの埋め方が許容されるかを示し、マーカーは取り扱いを示します。種類を固定してもマーカーを宣言しないスロットでは、その取り扱いを直接読み取るのではなく、セレクタから導出し直すことになります。このルールは、エンティティが宣言するすべてのスロットを読み取ります。すなわち、spec.featuresSchema配下にある自身のアタッチメントブロックのスロット、および Component の場合は、各依存ソケットが、そこを通じて配線される接続のためにspec.usesSchema.<socket>.featuresSchema配下で宣言するスロットです。ソケットのスロットに関する検出では、スロットに加えてソケットも示されます。Components と Features ではデフォルトで有効です。設定はありません。 - Connection credential matches target key(
connection-credential-matches-target-key)— キーを検査するサーバーは、検証するキーを自身の Component のスロットに保持し、呼び出し側はサーバーへ到達する接続上でキーを提示します。どちらの端も相手のアタッチメントを参照しないため、両者が同じキーを保持するのは作成者が両端に同じキーを書いた場合に限られます。通常は両方のアタッチメントに同じパラメーターを読ませることでこれを実現しますが、ビルドがそれらを比較することはありません。このルールは比較を行い、Release 全体を読む唯一のルールであるため、--releaseの下でのみ実行され、他のスコープでは実行されません。このルールは、標準カタログが両端に付ける名前によって両端を特定します。ターゲット側のキーは、その Component がspec.featuresSchemaで宣言するスロットapi_keyであり、呼び出し側のキーは接続上のスロットcredentialです。後者は Aggregate 内のuses.<socket>.<alias>.features.credential、または Release が配線する接続上に書かれます。ターゲットがapi_keyを宣言し、かつ managed のラベルが付いていない各接続について、キースロットが埋められていないターゲットへクレデンシャルを運ぶ接続、接続上にクレデンシャルのない埋められたキースロット、そしてシークレットの名前が異なる両端を報告します。比較するのは各端のロケーター、すなわちアタッチメントが書くorigin(Aggregate ではvalues、Release ではinfraに書かれます)を作成者が書いたとおりの形で比較します。そのため、同じパラメーターを読む両端は等しいと判定され、2 つのリテラルはテキストで比較されます。何も解決されず、検出結果はコンポーネント、接続、ターゲット、2 つのスロットを示しますが、そこに書かれたテキストがシークレットそのものである可能性があるため、どちらのロケーターも引用しません。api_keyスロットを宣言しないターゲットは何も検出されず、モデルサーバーのレジストリ pull トークンのように呼び出し側キーではないスロットは読まれません。また、Component にcomponent.aggrega.ai/hosting: managedのラベルが付いたターゲットは、そのapi_keyスロットが何を保持していても判定されません。このような Component はベンダーが運用するサービスを表すため、Release が実行するものがそのサービス上でキーを検査することはありません。そのような Component がapi_keyを宣言している場合(たとえば、ベンダーの製品が付ける名前で示されるホスト型モデル API のキー)、そのスロットが保持するのは Release がそのベンダーに提示するキーであり、呼び出し側が提示するキーではありません。self-hosted、external、mixedのラベルが付いたターゲット、またはホスティングラベルのないターゲットは判定されます。ソケットscrape_target(標準カタログが、メトリクススクレイパーがターゲットへ到達するソケットに付ける名前)上の接続はスクレイプであり、スクレイプのクレデンシャルがターゲットの呼び出し側キーであるべきかどうかはターゲットの製品によって異なります。クレデンシャルなしでメトリクスを提供する製品、すべての呼び出し側が提示するキーの背後にメトリクスを置く製品、独自のトークンを使う製品があります。そのため、スクレイプについては、ターゲットの Component がアノテーションobservability.aggrega.ai/metrics-credentialで示す内容を読みます。noneの場合、スクレイプはまったく判定されません。separate-tokenの場合、そのクレデンシャルはターゲットのapi_keyと比較されないため、3 つの検出結果のいずれも報告されません。target-keyの場合は、他の接続と同様に判定されます。ルールはこの 3 つの値のみを読むため、アノテーションのないターゲット、または他の値を持つターゲットへのスクレイプは他の接続と同様に判定されます。また、別のソケット上のすべての接続(モデル、ツール、データストアへの接続を含む)は、ターゲットのアノテーションが何を示していても同じように判定されます。ルールはターゲット上と接続上に書かれたアタッチメントを読みます。サブシステムや境界からターゲットに届くapi_keyアタッチメントがある場合、その接続は判定されません。アノテーションが追加するアタッチメントは対象に含まれないため、その方法でのみ埋められたキースロットは未設定として扱われます。ロケーターを書かないアタッチメントを持つ端は、埋められているかどうかのみが比較されます。インポートされたモジュールが提供するコンポーネントは読まれません。スロット名、ホスティングラベル、スクレイプソケットの名前、メトリクスアノテーションは、どのスキーマキーワードも示さないカタログの慣例であるため、スロットに異なる名前を付けるカタログでは何も検出されず、異なる名前のスクレイプ用ソケットは他のソケットと同様に判定されます。また、managed ラベルなしでapi_keyという名前のスロットにベンダーのキーを保持する Component は、そのキーを検査するターゲットとして読まれます。スロットの名前、ラベル、アノテーションが、ルールがターゲットの Component から読むもののすべてだからです。デフォルトで有効です。allow_connection_credential_mismatchesで無効にできます。 - Metrics credential annotation matches provides(
metrics-credential-annotation-matches-provides)— Component は自身のメトリクスについて 2 つの事実を記述できます。アノテーションobservability.aggrega.ai/metrics-credentialは、製品のメトリクスの認証方法を記述します。noneはクレデンシャルなしで提供されること、target-keyは Component がすべての呼び出し元に要求するキー、つまりapi_keyスロットが保持するキーを受け付けること、separate-tokenは独自のトークンを受け付けることを表します。spec.schemaのprovidesの柱で宣言される provides キーmetrics_credential_requiredは、その Component の各 Recipes が、あるインスタンスのメトリクスにクレデンシャルが必要かどうかを示すために公開するものです。これはインスタンスの設定によって変わり得ます。呼び出し元キーの背後にあるメトリクスは、キーがアタッチされている間だけクレデンシャルを必要とするため、アノテーションがその代わりになることはできません。両者は製品についての 1 つの事実を記述するため、このルールは両者の一致を求めます。noneとアノテーションされていながらこのキーを宣言する Component、およびtarget-keyまたはseparate-tokenとアノテーションされていながらこのキーを宣言しない Component は、それぞれ報告されます。検出結果には Component、アノテーションの値、余分または不足しているキーが示されます。アノテーションがない Component、またはそれ以外の値を持つ Component は何も検出されません。このルールは Component を記述されたとおりに読むため、別の Component を拡張する Component(スキーマがベースのものであるもの)は何も検出されず、そのベースは宣言された場所で読まれます。また、参照、合成、またはテキストとして記述されたエスケープ済みの本体として書かれたprovidesの柱は列挙できないため、その Component も何も検出されません。Components に対してデフォルトで有効です。設定はありません。
アーティファクトの不変性はこれらのルールの 1 つではなく、設定もありません。 公開済みの name:version は確定したものです。aggrega push は、そのタグですでに公開されているダイジェストと、これからプッシュするコンテンツが生成するダイジェストを比較し、異なるコンテンツで上書きすることを拒否します。バイト単位で同一のコンテンツを再プッシュしても何もアップロードされず、その公開にまだ欠けているもの(公開日と、プッシュが署名する場合はその署名)だけが付与されます。レジストリにはオペレーターが選択できる上書きの手段がないため、これを緩めるフラグやワークスペース設定はありません。変更されたコンテンツは新しいバージョンで公開します。そのバージョンアップを前のリリースに対して検証するのが --pre-publish です。
ルールごとのオーバーライドフラグは呼び出しごとのゲートであり、意図的に環境変数を持ちません。これらはすでに .aggrega-config.yaml の lint.publishing_discipline の下で設定によって裏付けられているためです。一般的な AGGREGA_* の優先順位モデルについては environment-variables.md を参照してください。
ビルド時と公開時
x-aggrega-* の使用を推奨しないルールは aggrega build の実行中にも動作し、そこでは 警告 として表示されます。aggrega lint --pre-publish は同じ検出結果を エラー に引き上げます。ローカルビルドは助言として示し、公開ゲートはそれを強制します。
エディタでの作成中
エディタはカタログのエンティティについて 2 つの異なる問いを発します。このページの冒頭で挙げた 2 つです。エンティティは正しいか、つまりパースでき、ピラーが解決され、レンダリングできるか。これは aggrega validate の役割で、エディタのセッションは常にこれに答えます。エンティティは公開可能か、つまり名前が慣例に従っているか、ファイルがそのカテゴリの想定するディレクトリにあるか、アノテーションのプレフィックスが正しいか。これがここで説明するルールの役割で、エディタのセッションは求められた場合にのみこれに答えます。
有効にしない限り無効です。 助言を受けたいエンティティを含むワークスペースの .aggrega-config.yaml で serve.lint_on_validate を設定して有効にします。
serve: lint_on_validate: trueこれに対応するコマンドラインフラグはありませんが、これは意図的なものです。この問いは特定のワークスペース自身の内容に関するものであり、ユーザーはそのワークスペースを作成する側であって、言語サーバーを起動する側ではありません。言語サーバーを起動するのはエディタです。
有効にすると、検証するすべてのエンティティに、正しさに関する検出結果と並んで、これらの検出結果も付き、それぞれがそれを生成したルールを示します。そこから 3 つのことが導かれ、それらが入力中の利用を実用的なものにしています。
- 検出結果は助言にとどまります。 慣例に反するエンティティも検証に通り、その Release も引き続き解決・レンダリングされます。この設定を有効にすると助言のレイヤーが加わるだけで、エディタが動作を拒否することはありません。
- 両者を区別できます。 公開されるすべての問題は、それを報告したレイヤーを示します。そのため、同じファイルの命名の問題と解決の失敗は、1 つの問題が 2 回報告されたものではなく、2 つの別々の事柄として読み取れます。
- 入力した内容がそのままチェックされます。 ルールはディスク上のファイルではなくバッファを読むため、修正した名前は保存する前に報告されなくなります。
このレイヤーで実行されるのはローカルコンテンツモードだけです。レジストリは参照されず、何も取得されず、何も書き込まれません。--pre-publish の比較は、明示的に求めたときに実行されます。エディタがそのためのリクエストを送信し、これはターミナルで --pre-publish を入力するのと同じです。上記の設定を編集しても実行されることはありません。ドキュメントに触れるたびに実行されるチェックこそ、レジストリにアクセスしてはならない場所です。そのため、このモードは自動的に付随して実行されるものではなく、明示的に呼び出すものとなっています。
チェックを直接求める場合は、設定にかかわらず、上記の 3 つのスコープのいずれでも動作します。そのため、編集ごとのレイヤーを一度も有効にしていないワークスペースでも、エディタにカタログ全体、Release のクロージャ、または 1 つのエンティティの走査を求めることができ、このコマンドが出力するものと同じ検出結果を得られます。設定が決めるのは、名前を指定して求めていない場所でもチェックを実行するかどうかだけです。
プロトコルの詳細は 2 つのページに分かれています。リクエストの意味と送信すべきタイミングは aggrega serve リファレンスに、そのパラメータと応答の形式のフィールドごとの説明はワイヤー形式リファレンスにあります。
リンターの選択
これらのルールは、標準のパブリッシング用リンター Wasm プラグインとして提供されます。ルールはコンパイラではなくプラグインに置かれているため、企業はコンパイラを変更することなく aggrega lint を別のプラグインに向け、独自のカタログの規律を適用できます。
ワークスペースは plugins.linter の下に複数のリンターをアタッチでき、すべてのアタッチメントが実行されます。アタッチメントが記述された順に、それぞれ固有のエントリ関数で実行され、すべての検出結果がまとめて報告されます。これにより、カタログは標準ルールとどちらかを選ぶのではなく、標準ルールを維持したまま独自のルールを並べて追加できます。--plugin は例外です。設定されたアタッチメントの代わりに、ファイルシステムのパスから成果物を 1 つだけ実行します。これがルールの開発中に役立つ理由です。
アタッチメントは uri: でプラグインを指定し、function: はそのプラグイン上のエントリ関数を指定します。function: を指定していて uri: を指定していないエントリは、どのプラグインにも属さない関数を指定していることになるため、設定は読み込まれた時点で E0224 として拒否され、ファイルとリスト内でのエントリの位置が示されます。その関数をエクスポートするプラグインの uri を追加してください。どちらも指定していないエントリは何もアタッチせず、読み飛ばされます。それが唯一のエントリである場合は、plugins.linter がまったくない場合と同様に、標準のリンターが自身のデフォルトのエントリ関数で実行されます。
リンタープラグインに渡されるもの
パラメータの値は、どのスコープであってもリンタープラグインには渡されません。パラメータの値はそれ自体が認証情報である場合があります。シークレットのアタッチメントの origin は Release が満たすパラメータを読み取るテンプレートであることがあり、その場合シークレットはそのパラメータの値になります。また、ワークスペースがアタッチするプラグインは、そのワークスペースが書いたものではない可能性があります。そのため、すべてのドキュメントはパラメータの値を除いた状態で渡されます。
- Aggregate では各パラメータ宣言が保持されますが、保持されるのは宣言に記述できるキー、すなわちパラメータスロットの語彙(型、説明、制約)のみです。
properties、items、valuesTypeの下にネストされたすべての宣言にも同じことが適用されます。宣言のdefaultはすべての階層で除かれます。キーを空にするのではなくキーごと削除するため、プラグインは宣言がデフォルトを与えているかどうかを判別できません。この語彙に含まれないキーは、その内容ごとすべての階層で除かれます。ビルドはそのようなキーに意味を与えず、キーのスペルを誤ったドラフトはその下にシークレットを含んでいる可能性があるためです。parametersの下にある宣言ではないエントリは、丸ごと除かれます。 - Aggregate の
aggregatesの下に列挙された各モジュールからは、そのモジュールに渡される値を保持するparametersブロックが除かれます。 - Release からは、値をインラインで記述しているか
$importでインポートしているかにかかわらず、parametersブロックが除かれます。 specの下にparametersブロックを持つその他のドキュメントからは、そのブロックが丸ごと除かれます。他の種類でこれを宣言するものはありません。
これは、コマンドラインで指定されたエンティティ、--pre-publish がそれと比較する公開済みバージョン、カタログ全体のパスと --release のパスが走査するすべてのエンティティ、そして Release 全体を読むルールが受け取るドキュメントに適用されます。パラメータを読み取るテンプレートは値ではないため、そのテキストは保持されます。そのため、ルールは記述された値がどのパラメータを読み取るかを引き続き確認できます。
例
カタログ全体を走査して慣例からの逸脱を検出します:
aggrega lint --catalog ./catalog作成中にエンティティをローカルで lint します:
aggrega lint core/datastore/postgres/component.yaml新しいバージョンを公開する前に公開ゲートを実行します:
aggrega lint core/datastore/postgres/component.yaml --pre-publish1 回の実行に限り 1 つのルールを緩和します:
aggrega lint core/datastore/postgres/component.yaml --pre-publish --allow-nonstandard-names関連項目
- ./aggrega-validate.md — 同じ 3 つのスコープにわたって正しさを検査する対応コマンドです。
- ./aggrega-build.md — コンパイルの一部として検証を行い、
x-aggrega-*のアドバイザリをwarnの重大度で表示します。 - ./aggrega-push.md — エンティティをレジストリに公開します。
aggrega lint --pre-publishはその前に実行するゲートです。 - ./aggrega-pull.md — 依存関係を解決し、固定します。
- ./aggrega-serve.md — これらの検出結果をエディタに報告する言語サーバーと、編集ごとのレイヤーを有効にする設定です。
- ../errors/warnings.md — ローカルモードの lint の検出結果を含む、致命的でない警告です。
概要
aggrega lint [entity-path] [flags]説明
aggrega lint checks publishing CONVENTIONS — naming, category-directoryalignment, annotation prefixes, and the rest of the publishing-linterdiscipline. It does not check correctness (schema, pillars, resolution,render): that is aggrega validate.
Three invocation shapes, mirroring validate:
aggrega lint conventions across every catalog entity aggrega lint --release <path> conventions across a Release's dependency closure aggrega lint <entity> publishing discipline for one entity
Without an entity argument, lint runs the structural conventions rulesover every catalog entity found under the catalog directories. Where theworkspace configuration gives its Releases catalog directories of their ownunder workspace.releases, it runs them once for each Release, over thedirectories that Release reads, and reports each pass under a line namingits Releases and those directories; Releases reading the same directoriesshare one pass. With --release it runs them over the entities thatRelease's closure reaches, and also runs the rules that read a wholeRelease: once, over the Aggregate it deploys, the Release and theComponents the Aggregate's components are instances of, with everyparameter value removed. In both, findings are advisory (warn severity)and never halt.
With an entity path, lint runs the publishing-linter rule set againstthat one entity. In default mode the rules run at warn severity overlocal content without consulting any registry. With --pre-publish theprevious registry version is fetched and the schema-evolutionclassification is compared against the proposed version bump; mismatcheshalt. --pre-publish applies to the single-entity shape only. Per-workspacepolicy flags from .aggrega-config.yaml's lint.publishing_discipline blockcan be overridden per invocation via the --allow-*/--no-allow-* flag pairs,in all three shapes.
All three shapes accept -o json, which replaces the human report on standardoutput with one structured document: every finding with its severity, the rulethat produced it, its short code (the code printed at the head of its row inthe human report, which aggrega explain expands), its message, and the entityfile it concerns, plus counts by severity. A finding from a rule Aggrega doesnot declare, one a linter of your own adds, carries no short code, as its rowprints none. A finding carries a line and column only when the rule thatproduced it located the issue that precisely; otherwise the file alone locatesit. The message is the rule's own text, carried through unchanged, so thestructured and human renderings never word a finding differently. The exitstatus is the same under either format.フラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--allow-aggrega-ai-prefix | false | allow_aggrega_ai_prefix=true を強制します |
--allow-category-mismatches | false | allow_category_mismatches=true を強制します |
--allow-connection-credential-mismatches | false | allow_connection_credential_mismatches=true を強制します |
--allow-direct-x-aggrega-extensions | false | allow_direct_x_aggrega_extensions=true を強制します |
--allow-dynamic-refs | false | この実行に限り allow_dynamic_refs=true を強制します |
--allow-id-overrides | false | この実行に限り allow_id_overrides=true を強制します |
--allow-nonstandard-names | false | allow_nonstandard_names=true を強制します |
--allow-undeclared-recipe-provides | false | allow_undeclared_recipe_provides=true を強制します |
--baseline | — | 公開前の進化チェックの差分を、公開対象より下で自動選択される最も高いバージョンではなく、指定した公開済みのバージョンに対して取ります。レジストリに存在する厳密な SemVer タグである必要があります(—pre-publish が必要) |
--catalog | [] | カタログディレクトリ。繰り返し指定できます。各 —catalog <dir> はカタログ検索スタックの先頭に追加されます(最初に一致したものが優先)。スタックはワークスペースの catalog_dirs、またはワークスペース設定が workspace.releases の下で独自のディレクトリを与えている Release の場合はその Release のディレクトリで、ワークスペースのルートに catalog という名前のディレクトリがあれば、それがスタックの最後になります。空として書かれた catalog_dirs リストは、ローカルカタログを一切読み込みません。カタログ全体のパスと —release の慣例のパスで使用されます。 |
--entity | — | lint するエンティティ YAML へのパス(位置引数として渡すこともできます) |
--no-allow-aggrega-ai-prefix | false | allow_aggrega_ai_prefix=false を強制します |
--no-allow-category-mismatches | false | allow_category_mismatches=false を強制します |
--no-allow-connection-credential-mismatches | false | allow_connection_credential_mismatches=false を強制します |
--no-allow-direct-x-aggrega-extensions | false | allow_direct_x_aggrega_extensions=false を強制します |
--no-allow-dynamic-refs | false | この実行に限り allow_dynamic_refs=false を強制します |
--no-allow-id-overrides | false | この実行に限り allow_id_overrides=false を強制します |
--no-allow-nonstandard-names | false | allow_nonstandard_names=false を強制します |
--no-allow-undeclared-recipe-provides | false | allow_undeclared_recipe_provides=false を強制します |
--output, -o | text | 出力形式: text|json。 |
--plugin | — | 公開用リンターの .wasm アーティファクトへのファイルシステムパス(ワークスペースの plugins.linter のアタッチメントの代わりにこのアーティファクトを実行します) |
--pre-publish | false | レジストリから前のバージョンを取得し、提案されたバージョンアップをスキーマ進化の分類に照らして検証します |
--release | — | 解決済みの依存関係の閉包に対して慣例をチェックする Release YAML へのパス(エンティティ引数とは同時に指定できません)。相対パスは、ワークスペースのルートではなく、コマンドを実行したディレクトリを基準に解決されます。そのディレクトリがどのワークスペースにも属さず、ルートも指定されていない場合、絶対パスでは Release 自身のフォルダからワークスペースを探します |