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

aggrega explain

コードが示す停止条件を説明します

概要

aggrega explain <code>

説明

Explain the halting condition a code names.
A halting diagnostic opens with the category the failure is attributable to and the condition's short code — the letter E and four digits, as in [CATALOG_ERROR E0209]. That short code is the one to pass here; it is fixed once a condition is published, so a code quoted out of an old report still names the same condition.
aggrega explain E0209
The descriptive code is accepted too — the hyphenated one naming the condition in words, which a structured diagnostic carries as a field of its own. A condition's two codes name the same condition and reach different readers, so either is a code you may be holding, and the condition above is registered under recipe-values-mapping-requires-source:
aggrega explain recipe-values-mapping-requires-source
Every condition is declared inside this binary, so the identifiers and the sentence are reported without a network or a cache. The published reference supplies the walk-through of the authoring fix for every condition, and nothing else is resolved against it. It is read from the documentation bundle published for this version of aggrega on the default registry — or, where none is published for it, the newest one published for an earlier version — kept in the cache every project on this machine shares, acquired on first use when that cache holds no copy this workspace's signature check admits. Where it cannot be acquired, the condition is still reported and the reason the walk-through is missing is stated.
A number that named a condition and no longer does is reported as retired, with what it named, so a code quoted from an old report is never answered with a different condition.

動作

停止したビルドは、失敗の原因となったカテゴリと、その条件の短いコード(文字 E と 4 桁の数字)を示す角括弧付きの見出しを出力します。

[CATALOG_ERROR E0209] Recipe: valuesMapping requires source ...

aggrega explain E0209 は、そのコードを、それが示す条件と、記述側での修正手順の解説に変換します。

Terminal window
aggrega explain E0209

応答は、条件の両方の識別子と、その診断の冒頭に置かれる固定の文から始まり、続いて条件の原因と変更すべき点を説明するエントリを再現します。これは fatal-halts.md で公開されているものと同じエントリです。

渡すコード

条件の 2 つのコードはどちらも受け付けられます。それぞれが異なる場面で目に入るためです。

短いコードはターミナルに表示されるもので、手元に出力しかない場合に使うコードです。番号は一度割り当てられると固定されるため、1 年前にレポートに貼り付けた短いコードは、今でも当時と同じ条件を示します。

説明的なコードは、構造化された診断が独立したフィールドとして持つハイフン区切りのコードで、プログラムが分岐に使うものです。条件を言葉で示し、接頭辞を持たないため、周囲でコンパイラが再編成されても変わりません。手元にあるのがこちらであれば、代わりにこれを渡します。上記の条件は recipe-values-mapping-requires-source として登録されています。

Terminal window
aggrega explain recipe-values-mapping-requires-source

条件の 2 つのコードは同じ条件を示すため、どちらの表記でも同じ応答が返ります。短いコードは画面から読み取って入力し直す値なので、大文字と小文字を区別せずに照合されます。

sentinels.md では、条件が持つ 3 つの識別子と、それぞれをどのような場合に使うかを説明しています。

応答の取得元

このバイナリが宣言するすべての条件は、バイナリから応答されます。 2 つのコードと診断の冒頭の文はコンパイラ内部で宣言されているため、その部分にはネットワークもキャッシュも設定も必要ありません。

このバイナリが宣言していないコードは、公開リファレンスで検索されます。 プラグインはコンパイラが宣言する条件を選択して停止を報告するため、条件がほかの場所で宣言されることはありません。公開リファレンス sentinels.md は製品が宣言するすべての条件を列挙しており、実行中のバイナリとは異なるバージョン向けに公開されている場合があります。そのため、より新しいリリースや古いリリースで作成されたレポートから引用したコードでも、そこで解決できることがあります。

修正手順の解説も公開ドキュメントであり、fatal-halts.md から読み取られます。どちらのページもドキュメントバンドルから取得されます。バンドルは、すべての Aggrega プロジェクトが共有するキャッシュにマシンごとに一度だけ、レジストリとバージョンごとに 1 部ずつ保持されます。aggrega cache を参照してください。読み取られるバンドルは、実行中の aggrega のバージョン向けに公開されたものです。そのバージョン向けに公開されたものがない場合は、それより前のバージョン向けに公開された最新のものになります。これは aggrega scaffold --example が行うのと同じ選択であり、そのため両者が異なるドキュメントを読むことはありません。以前のバージョンのリファレンスに含まれていないコードは、その後に宣言された条件を指している可能性があるため、何も指さないコードとしてではなく判定できないコードとして拒否され、その拒否ではどのバージョンのリファレンスを読み取ったかが示されます。バンドルをどのレジストリ(ワークスペースのデフォルトレジストリ)から取得するかはワークスペースが決め、マシン上に既にあるコピーを読み取ってよいかもワークスペースが決めます。ページを提供する前に、コピーの横に保持された署名が、そのレジストリに対するワークスペース自身の署名チェックで改めて検証されます。これはバンドルの取得時に適用されるのと同じチェックです。このチェックはオフラインでも実行されます。チェックが鍵またはトラストルートを固定している場合はそれだけを読み取ります。公式ハブの組み込みチェックのようにどちらも固定していない場合は、公開の Sigstore トラストルートに照らして検証しますが、オフラインのワークスペースはこれを取得できません。そのためオフラインでは、このマシンで以前にオンラインで取得した際にホームディレクトリの .sigstore に残されたトラストルートに照らして検証し、何も取得しません。マシンにコピーがない場合、またはチェックが認めるコピーがない場合、コマンドはそのチェックのもとで一度だけ取得し、以降はキャッシュから読み取ります。同じコピーが、アシスタントが aggrega mcp を通じて読むドキュメントと、エディタが aggrega serve を通じて表示する説明にも使われます。

次の 3 つの応答は、それぞれ求められる対応が異なるため、見分けられるようにしておく価値があります。

まだエントリのない条件。 コードと文は報告され、停止条件のページにその条件の解説がないことを示す注記が付きます。すべての条件は引き続き sentinels.md に一覧されています。

利用できるドキュメントがない。 コンパイラが宣言する条件については、コードと文は引き続き報告され、読み取れなかったバンドルとバージョンを示す注記が付きます。このバイナリが宣言していないコードについては応答に使えるものが何も残らないため、コードは拒否されます。その拒否では、リファレンスを読み取れなかったことが示されます。リファレンスがなければ、別のバージョンのコードをタイプミスと区別できないためです。また、コードを修正するか、ドキュメントを入手するかという両方の対処が残されています。通常の原因は、オフラインに固定されたワークスペース、またはレジストリに一度も到達したことのないワークスペースです。マシンにワークスペースの署名チェックが認めないコピーがある場合(別のプロジェクトがより緩い設定で取得したコピーや、チェックの検証に使う公開トラストルートをこのマシンが一度も取得していないためにオフラインのワークスペースが確認できないコピーなど)、注記は、コピーが存在しないのではなく拒否されたこととその理由を示します。使用しているバージョン向けにバンドルが公開されておらず、それより前の最新のバンドルがこのバージョンの aggrega ではもう読み取れない形式である場合(たとえば、自身のドキュメントが公開される前に実行されたリリース候補など)、注記はその両方を 1 つの文で示します:

hub.aggrega.ai/docs/aggrega-docs publishes no documentation bundle for 0.9.1-rc.1, and the newest earlier one, 0.8.11, is in a format this version of aggrega no longer reads, so the walk-through is not shown here; every condition, including the ones a provider declares, is published at aggrega-docs/language-reference/errors/sentinels.md, and the walk-through of each authoring fix at aggrega-docs/language-reference/errors/fatal-halts.md

廃止された番号。 かつて条件を示していたが現在は示していない番号は、存在しなかったコードとしてではなく、廃止済みとして、かつて示していた内容とともに応答されます。廃止された番号は再び割り当てられないため、別の条件で応答されることはありません。

例

失敗したビルドから得たコードをそのまま説明します。

Terminal window
aggrega build --release release.yaml || aggrega explain E0209

プログラムが照合したコードを説明します。

Terminal window
aggrega explain plugin-value-not-representable

アシスタントからの同じ応答

aggrega mcp を通じて接続した AI アシスタントは、explain-error ツールを通じてこれと同じ展開にアクセスします。単独のコードではなく診断テキストを渡します(アシスタントが持っているのはビルドが出力した内容だからです)。そのテキストが短いコードで始まる場合、応答には、条件、その診断の冒頭の文、そして記述側での修正手順を解説した公開済みの説明が含まれ、上記の応答と同じ構成になります。説明的なコードも含まれるため、アシスタントはメッセージの文言ではなくそれに基づいて分岐できます。また、条件が公開されているアドレスも含まれます。

解説がない場合について上の節で述べたことは、ここでもすべて当てはまります。ページにエントリがない条件の場合も、ドキュメントを読み取れないワークスペースの場合も、条件は応答され、どちらであったかを示す注記が付きます。廃止された番号もここで同様に、かつて示していた内容とともに廃止済みとして応答されます。そのため、古い診断を渡されたアシスタントは、無関係なページに誘導されるのではなく、その番号がもう使われていないことを知ることができます。アシスタント向けの機能はセッション開始時にドキュメントを一度取得するため、展開は既にキャッシュされたものを読み取ります。

デーモンは、診断ではなくコードから、エディタに対して同じ問いに応答します。この 3 つは、たまたま一致する 3 つの応答ではなく、1 つの展開を 3 通りに表示したものです。