aggrega serve
aggrega serve は、IDE 統合のために Aggrega を長時間稼働するサービスとしてのコンパイラのデーモンとして実行します。stdin/stdout 上で JSON-RPC 2.0 を話し、カタログリゾルバ、パースキャッシュ、診断の状態をリクエスト間で保持します。そのため、エディタの操作はキー入力のたびにカタログ読み込みの全コストを払うことなく、1 秒未満でフィードバックを得られます。
デーモンは通常、手動で実行するのではなく、エディタ拡張機能がサブプロセスとして起動します。VS Code 拡張機能がリファレンスクライアントです。その他のエディタも同じプロトコルを話すことで統合できます。
プロトコル
ワイヤープロトコルは Content-Length フレーミングを用いる JSON-RPC 2.0 で、aggrega/ メソッド名前空間の下にあります。これは意図的に Language Server Protocol ではありません。Aggrega には LSP に相当するもののないドメイン操作(IR グラフのクエリ、キャッシュ無効化のシグナル)があるためです。エディタ拡張は、エディタの LSP リクエストとこれらの aggrega/* メソッドとの間を変換します。LSP 形式の position、range、location の値は、適合する箇所では再利用されます。
2 つのメソッドは、aggrega/ 名前空間に名前を変えず、プロトコル標準の $/ 名を保持します。どちらも Aggrega としての意味を持たないトランスポート上の事項であり、すでにこのプロトコルを話すクライアントは何も追加せずに扱えるためです。$/cancelRequest はクライアントが回答を必要としなくなったリクエストを停止し、$/progress はデーモンが長い操作を実行中に報告する手段です。どちらも以下で説明します。
🔴 以下のすべてのリクエストは、対象とするワークスペースの絶対パスである workspaceRoot を持ち、メソッドごとには繰り返し記載しません。対象がワークスペースではないため、aggrega/initialize、aggrega/getSchema、aggrega/scaffoldEntity の 3 つは持ちません。ただし、実行可能なサンプルを書き出す、または一覧表示する aggrega/scaffoldEntity はワークスペースを指定します。ワークスペースを指定しないリクエストがどうなるかは すべてのリクエストは対象のワークスペースを指定する を、プッシュされる診断の送り先は 診断をプッシュしてほしいワークスペースの宣言 を参照してください。
フィールドごとの形はスキーマとして公開されており、ワイヤー形式リファレンス で読むことができます。 そのページには、すべてのメソッドのパラメーターオブジェクト、すべての結果、すべての通知ペイロードが記載されています。各フィールドの型、必須かどうか、何を運ぶかに加え、メソッドごとではなく全体にわたって成り立つ 3 つの性質も記載されています。すなわち、各メソッド自身が宣言するフィールド以外にすべてのリクエストが受け付ける 2 つのフィールド(上記の workspaceRoot と、長い操作の監視 の workDoneToken)、メソッドが受け付けないキーを持つ params オブジェクトは拒否され、その拒否の中で受け付けられるキーの集合が示されること、そして存在しないコレクションが空ではなく null としてワイヤーに現れる箇所です。このページはそのスキーマから生成されるため、契約が変わればこのページも変わります。
このページはプロトコルを、あのページは形を扱い、両者は併せて読むことを想定しています。 こちらには、フレーミング、各メソッドの目的、その及ぶ範囲、書き込む内容、発生させる拒否とその理由、エラーコードとそれぞれへの対処を記載します。あちらには、ワイヤーに何を載せるかをキーごとに記載します。そのため以下の一覧では各メソッドを挙げてその問い合わせが何を意味するかを述べ、作成中のリクエストのフィールド一覧はその隣のリファレンスにあります。
リクエスト:
aggrega/initialize— ハンドシェイク。位置エンコーディングをネゴシエートし(サーバーは UTF-8、次に UTF-16、次に UTF-32 を優先し、デフォルトは UTF-16)、プッシュされる診断のために宣言されたワークスペースを受け取り、そのワークスペースのルート、設定が解決された設定レイヤー、およびそれを解決したマーカーを報告します。応答には、応答しているバイナリのバージョンであるversionも含まれます。これはそのバイナリについてaggrega versionが報告するのと同じ値です。これは実行中のプロセスを表すため、デーモンの起動元ファイルが置き換えられた後(たとえば同じパスへの再ビルド)でも、versionは実行中のデーモンを示し、ファイルに問い合わせるとその置き換え後のものを示します。どのバージョンと通信しているかを知りたい場合はここで読んでください。workspaceRootは省略可能で、ワークスペースに作用するのではなくワークスペースを宣言します。診断をプッシュしてほしいワークスペースの宣言 を参照してください。クライアントが進捗通知を扱えることを示すにはcapabilities.window.workDoneProgress: trueを送信します。応答のcapabilities.workDoneProgressがそれを返し、何も宣言しなかったクライアントではこのフィールドは存在しません。長い操作の監視 を参照してください。aggrega/validate— ファイルの内容を検証し、診断を返します。releaseは検証対象の Release を示すワークスペースルートからの相対パスで、aggrega/irGraphが受け取るのと同じ値、またルートから実行した場合にaggrega build --releaseが受け取るのと同じ値です。省略可能で、回答の及ぶ範囲を選択します。Release を指定すると、Release を必要とするチェックがそれに対して実行されます。カタログエンティティはその Release の観点で単一のエンティティとしてチェックされ、その他のドキュメントはその Release の依存関係クロージャに対してチェックされます。省略すると、回答はドキュメント単独で求められる範囲を対象とし、そのことを示すcheckedを含みます。値が存在しても不正な形式であれば、いずれの場合も拒否されます。絶対パスや、ワークスペースルートの外に解決されるパスは、解決されずに拒否されます。ライブ検証 を参照してください。aggrega/diagnostics— ファイルについて保持されている検出結果を返します。リクエスト到着時にそのファイルの検証が実行中であれば、回答はその完了を待って検出内容を報告します。そのため、デーモンが問題を検出している最中のファイルについて、問題なしという応答が返ることはありません。検証の実行中に診断を要求する を参照してください。aggrega/hover— 位置にあるエンティティのホバー内容。releaseは省略可能で、指定するとその Release の観点で回答します。1 つの Release の観点での回答 を参照してください。aggrega/completion— 位置における補完候補。カーソルが種類によってエンティティを指す箇所(コンポーネントのtype、Feature アタッチメントのtype、extends:の値、Recipe または FeatureRecipe のimplements:)では、候補はワークスペース自身のドキュメントが宣言するその種類の名前であり、Component または Feature の場合は設定されたcatalog_dirsが宣言する名前も含まれます。それぞれ 1 回ずつ、名前順に提示されます。したがって、Components と Features をカタログから取得するワークスペースには、自身で作成したものだけでなくそれらも提示されます。Manifest マッピングの値で提示される Recipes と FeatureRecipes は、ワークスペース自身のドキュメントから取得されます。アーティファクトキャッシュまたはレジストリのみが保持するエンティティは提示されません。補完への応答でフェッチが行われることはありません。releaseは省略可能で、指定するとその Release の観点で回答します。1 つの Release の観点での回答 を参照してください。aggrega/resolve— 位置で参照されているエンティティを解決します(定義へ移動)。releaseは省略可能で、指定するとその Release の観点で回答します。1 つの Release の観点での回答 を参照してください。aggrega/findReferences/aggrega/findImplementations。それぞれ省略可能なreleaseを受け取り、その Release の観点で回答します。1 つの Release の観点での回答 を参照してください。aggrega/irGraph— エディタからの内部調査用に、Release のコンパイル済み IR グラフを返します。releaseはワークスペースルートからの相対パスで、その内部にある Release を指定します。ルートから実行したときにaggrega build --releaseが受け取るのと同じ値です。それ以外の形式は、代わりに送るべきものを示す標準の invalid-params エラーで拒否されます。絶対パス、ワークスペースルートの外に解決されるパス(記述どおりに外へ出る場合も、ファイルや途中のディレクトリへのリンクを通じて外へ出る場合も含みます)、空の値はいずれも解決されずに拒否されるため、リクエストがワークスペースの保持しないファイルについて報告することはありません。ワークスペース設定がbuild.authoring_releaseとして、またはworkspace.releasesのキーとして指定する Release は、そのファイルがどこにあってもワークスペースが保持するものとみなされるため、そこへ通じるワークスペース内のリンクは、aggrega/releaseCandidatesがそれを列挙するのと同様に受け入れられます。Release が読み込むカタログディレクトリを走査できない場合(たとえば存在するが読み取れない場合)は、aggrega inspectが拒否するのと同様に、他の何かを読み込む前に拒否されます。エラーは1004entity-not-resolvable で、そのメッセージはコマンドラインがそのディレクトリについて出力するレポートを 1 行にしたもの([CATALOG_ERROR] <directory>: catalog load: …)であり、残りのディレクトリからグラフが描かれることはありません。ワークスペース設定に列挙されているがディレクトリではないもの(たとえばそこに何も存在しない場合)も、同じ方法かつ同じ時点で拒否されます。エラーは1004entity-not-resolvable で、そのメッセージはすべてのコマンドがそれに対して返す拒否であり、そのエントリ、それを列挙している設定ファイルと行、および設定項目を示します(ローカルエンティティの読み込み元)。読み込みがその内部にとどまるべきディレクトリの外へ通じるリンクを保持するカタログディレクトリ(ワークスペース内のカタログディレクトリの下、または設定がワークスペース外に指定するカタログディレクトリの下に、他の場所からリンクされたドキュメントやディレクトリがある場合)も、同じ方法かつ同じ時点で、1004と、リンクとその行き先を示すその条件固有の文で拒否されます。そのようなリンクを通じては何も読み込まれません。それを除いて描かれたグラフでは、同名の別のエンティティがその代わりに解決される可能性があるためです。Release がその Aggregate や Manifest を識別子で指定している場合に、Release と並ぶドキュメントの中から外へ通じるリンクも同様です。Release、その Manifest、またはそれが継承する Release がパス(aggregate:、manifest:、extends:、またはパラメータの$import:)で指定するファイルが、記述どおりに、またはリンクを通じてワークスペースの外へ通じる場合は、その条件固有の文(fatal-halts.md §「A reference to another file leads out of the directory it must stay inside(別のファイルへの参照が、その内部にとどまるべきディレクトリの外へ通じています)」)で拒否されます。エラーのデータは、そのファイルへ通じた Release 内のキーを位置として示し、そのファイルからは何も読み込まれません。設定がワークスペース外に指定する Release は、それを保持するディレクトリに対して同様に制約されるため、それ自身またはその継承チェーン上の Release が記述するパスがそのディレクトリを出る場合も拒否されます。aggrega/releaseCandidatesは絶対パスで応答するため、一方のインターフェースの出力を他方に渡すクライアントは両者の間で変換する必要があることに注意してください。このパラメータが、ドキュメント単位のfileおよびuriパラメータが受け入れる表記を拒否するのは意図的であり、その判断基準は送信するパラメータが受け入れる表記で説明しています。グラフは、作成者が機密と宣言したすべての値を、コマンドラインで--ir-graphが伏せるのとまったく同じように伏せます。各値はaggrega-inspectの「Machine-readable output」が説明するマーカーに置き換えられ、それ以外はすべてコンパイラが記録したとおりに渡されます。unredacted: trueはそれらの値を平文で要求します。これはコマンドラインの--unredactedのプロトコル上の表記であり、要求する唯一の方法です。指定がない場合またはfalseの場合、応答はそれらの値を伏せます。この場合、応答が届く先にはすべて値が平文で渡るため、クライアントがそれを要求するのは、利用者自身が要求した場合に限ります。aggrega/build— Release をコンパイルし、その成果物をワークスペースの出力ディレクトリに書き込みます。これは、ワークスペースルートから実行したときにaggrega buildが書き込むのと同じディレクトリです。releaseは上記と同じ契約に従います。すべてのゲートを有効にしてレンダリングするため、コマンドラインのビルドが停止する不一致はここでも停止します。Release が読み込むカタログディレクトリを走査できない場合(たとえば存在するが読み取れない場合)は、aggrega buildが拒否するのと同様に、何かを書き込む前に拒否されます。成果物は書き込まれず、autoPullが設定されている場合もロックファイルは書き込まれません。ワークスペース設定がディレクトリとして列挙しているがディレクトリではないものも同様で、aggrega buildが拒否するときと同じ文言で拒否されます(ローカルエンティティの読み込み元)。拒否はaggrega/irGraphが同じディレクトリに対して返すものと同じで、1004entity-not-resolvable とコマンドラインのレポートを 1 行にしたものです。カタログディレクトリの読み込み範囲の外、または Release と並ぶドキュメントの外へ通じるリンクは、aggrega/irGraphが拒否するのと同様に拒否され、何も書き込まれません。応答は、書き込み先のoutputDirectoryと、書き込んだfiles(それぞれそのディレクトリからの相対パスで、ソート済み)を、実行中に発生したnoticesとともに示します。ドキュメント上の位置を持つ検出結果は、代わりにaggrega/publishDiagnosticsで送られます。レンダリング中に拒否される Release には、コンパイラの言葉によるその拒否が、すべての原因を含めて応答され、その拒否は指し示す位置に公開されます。レンダリング中に発生した拒否を参照してください。autoPullが設定されていた場合、応答にはdependencyResolutionも含まれます。これはaggrega/resolveDependenciesが応答するのと同じレポートであり、ビルドの一部として依存関係を埋めたクライアントは、改めて問い合わせることなく何が固定されたかを読み取れます。また、このビルドの解決が各参照をどこから取得したかも読み取れます。これはその実行に関する事実であり、ロックファイルには記録されません。各通知には、それを発生させた箇所のclass(deprecation、catalog、catalog-lint、extends、release-composition、または後述の依存関係解決が発生させた行の場合はdependency-resolution)が含まれます。デーモンがその箇所の名前を持たない場合は空のclassとなり、クライアントは最も近いものを推測せずに、そのままのtextとして表示します。書き込み時に出力ディレクトリ、またはその配下でファイルを書き込んだか通過したディレクトリで見つかった、このビルドが書き込んでいないファイルは、そのまま残され、実行自身の通知の後に続く 1 つの通知の中で、空のclassとして、aggrega buildが警告を出力するときと同じ文で示されます。ビルドが書き込まなかったファイルを参照してください。filesがそれらを示すことはありません。outputParentは成果物がワークスペース内のどこに置かれるかを示し、その名前がそのまま意味のすべてです。これは出力ディレクトリが作成される親ディレクトリであるため、docsを送ると成果物はdocs自体ではなくdocs/distに書き込まれます。これは、ターミナルでdocs内でビルドを実行した場合の結果とまったく同じです。省略すると、ビルドはワークスペースルートで実行した場合と同じ場所に書き込みます。これは、ここで他の書き込みリクエストが受け取るoutputDirとは意味が異なり、それは意図的です。 それらは書き込み先のディレクトリを指定し、こちらはそのディレクトリの親を指定します。両者は異なるものであるため、異なる名前を持ちます。それでもワークスペース内の書き込み先であることに変わりはないため、絶対値、ルートの外へ出る値、リンクを通じてルートの外へ通じる値(ルート外にリンクされたディレクトリや、その下にまだ作成されていないディレクトリ)は、解決されずに拒否されます。その中に作成される出力ディレクトリと、ビルドがそこに書き込むすべてのファイルも、同様にワークスペース内に制約されます。そのいずれかがリンクを通じてワークスペースの外へ通じる場合、ビルドは1004と、リンクとその行き先を示すその条件固有の文で拒否され、何も消去も書き込みもされません。autoPullはレンダリングの前に Release の依存関係を解決します。これはaggrega/resolveDependenciesが行うのと同じ解決であり、コマンドライン自身のデフォルトに合わせて、リクエストが要求しない限り無効です。これがない場合、ロックファイルを持たない Release は、実行すべきものを示す lockfile-absent エラーで拒否されます。autoPullを設定すると、このリクエストはレジストリにアクセスし、ロックファイルを書き込みます。レジストリへのアクセスと書き込みを参照してください。先に解決を行うリクエストでも、Release のレンダリングは一度だけです。Release がどのリモート参照を消費するかを調べること自体がレンダリングであるため、解決の時点でビルド対象はすでにレンダリングされており、ビルドはそれを繰り返さずにそのレンダリング結果から応答されます。policyInputはワークスペース内のディレクトリをそのルートからの相対パスで指定します。ビルドが完了しても停止しても、ビルドは各ガバナンスロールがそこにアタッチされたプラグインに渡すペイロードもそのディレクトリに書き込みます。これはaggrega build --policy-inputが同じ名前で書き込むファイルです。その後、応答のnoticesが書き込まれたファイルの数を示し、ファイルが 1 つも書き込まれなかった各ロールを空のclassで示します。失敗したリクエストでは、書き込まれたファイルはディスク上に残り、その報告は応答に含まれません。 エラーエンベロープには拒否だけが含まれます。これは書き込み先であるため、絶対値やワークスペースの外へ出る値は、何かが実行される前に拒否されます。aggrega/buildPreview— Release のビルドが何を書き込むはずかを、何も書き込まずに報告します。releaseは上記と同じ契約に従います。aggrega/buildと同じ計算を同じゲートのもとで実行するため、Release は両方で拒否されるか、両方で報告されるかのいずれかです。そのため、両者の選択は厳密さではなく出力についての選択になります。Release が読み込むカタログディレクトリを走査できない場合、またはその読み込みがその内部にとどまるべきディレクトリの外へ通じるリンクを保持する場合は、何かをレンダリングする前に同じ方法で拒否されます。aggrega/buildと同様に、ワークスペース設定がディレクトリとして列挙しているがディレクトリではないものも同じく拒否されます。応答には、ビルドが出力するはずの出力ディレクトリからの相対名をソートしたfilesが、noticesとともに含まれます。どこにも何も書き込まれていないため、outputDirectoryはありません。レンダリング中に拒否される Release は、aggrega/buildとまったく同じように応答され、公開されます。このリクエストは、代わりに送るべきものを示す invalid-params エラーでautoPullを拒否します。依存関係を埋めるとロックファイルが書き込まれますが、このリクエストはロックファイルを書き込まないためです。レジストリにはアクセスしません。policyInputはこのリクエストが行う唯一の書き込みであり、送信された場合にのみ行われます。aggrega/buildとまったく同じようにガバナンスペイロードをそのディレクトリに書き込み(aggrega build --dry-run --policy-inputが書き込むファイル)、出力ディレクトリとロックファイルには手を触れず、noticesに同じ報告を含め、同じ制約に従います。失敗したリクエストでは、書き込まれたファイルはディスク上に残り、その報告は応答に含まれません。aggrega/resolveDependencies— Release のカタログ依存関係とソース依存関係をキャッシュへ解決し、そのレンダリングが消費する外部入力をコンテンツアドレス指定ストアに固定し、ロックファイルを書き込みます。releaseはワークスペースルートからの相対パスで、aggrega/irGraphが受け取る値と同じであり、同じ形で拒否されます。upgradeは記録済みの固定を破棄して再解決し、各依存関係を利用可能な最上位バージョンまで引き上げます。targetsはそれを指定したエンティティ参照に絞り込み、それ以外の固定はすべて保持します。verifyは、記録済みの解決結果を、このリクエストがそれなしで行う解決と比較します。記録済みの固定は同じように尊重し、ロックファイル、プラグイン信頼レコード、entity.lockのいずれも書き込みません(キャッシュは、それなしの場合と同様に読み取られ、埋められます)。そしてverified: trueと、ロックファイルが記録するtoolchainを返します。verifyは、upgrade、targets、および値にかかわらずpinSourcesと併用されると、何かを解決したり進捗を報告したりする前に、無効なパラメータとして拒否されます。アップグレードは検証が尊重するための固定を破棄し、指定したターゲットはアップグレードによってのみ再解決されます。また、pinSourcesは、解決がentity.lockに欠けている固定を記録するか、それを理由に拒否するかを決めるものであり、entity.lockを書き込まない比較はそのどちらも行いません。コマンドラインとアシスタントツールも同じ組み合わせを拒否します。応答は、書き込んだ、または比較対象としたlockfileと、固定したすべての参照をentities、libraries、pluginsに示します。各エントリは解決先のversionとそのsourceを持ちます。これはこの実行が参照をどこから取得したかを、同じ解決に対してaggrega pull --detailが表示する語、つまりfetched-fresh、cache-reuse、local、in-binary、externalのいずれかで示すものです。あわせてsourceArtifacts、trustedPlugins、externalInputs(実行完了時点でロックファイルが固定している外部入力の数で、引き継がれたものとこの実行で発見されたものの両方を数えます)、および解決が発生させたnoticesも含みます。🔴 成功の応答だけでは、外部入力の固定が完了したことを意味しません。 すべての依存関係を固定したものの、Release がどの外部入力を消費するかを特定しきれなかった場合、発見を止めた原因を示すincompleteExternalInputsを返したうえで、成功として応答します。依存関係の固定は完了してディスク上にあるため、リクエスト全体を失敗として報告すると、すでに正しい作業のやり直しを促すことになるからです。ロックファイルを完全に固定済みとして扱う前に、このフィールドを確認してください。 未発見のものがなければこのフィールドは存在しないため、存在すること自体がシグナルです。カタログディレクトリのパラメータはありません。検索スタックはワークスペースが設定するものです。これはセッションにおける Release の唯一の固定リクエストであり、外部入力もここで固定されます。 レンダリングがどの URL を消費するかはレンダリング対象によって決まるため、このリクエストは Release をレンダリングしてそれを特定し、その後のビルドリクエストは記録された内容から提供されます。Release がビルドする Recipe または FeatureRecipe のうち、エンティティが読み取る入力の固定をentity.lockが記録していないものがあると、リクエストは拒否され、aggrega pinと未記録の各入力が示されます。pinSources: trueを指定すると、代わりにそれらのエンティティに対して固定ステップを実行し、各エンティティの隣にentity.lockを書き込みます。これはaggrega/pinが実行するステップと同じで、同じバイト列を書き込みます。省略した場合、pinSourcesはワークスペースのpin_sources_at_pullに従います。送信した場合はその設定を両方向に上書きするため、falseは固定するよう設定されたワークスペースでも拒否します。このリクエストはレジストリにアクセスし、書き込みを行います。レジストリへのアクセスと書き込みを参照してください。aggrega/pin— Recipe または FeatureRecipe の隣にあるentity.lockに、エンティティが自身のドキュメント外から読み取るすべての入力のコンテンツ固定を記録します。対象は、座標が完全に記述されたリモートソース、artifacts エントリがインポートするファイル、そしてローカルソースがエンティティの公開物に寄与する各ファイルです。これはターミナルでaggrega pinが実行するステップと同じで、同じバイト列を書き込みます。entityは必須で、エンティティドキュメントを指すワークスペースルートからの相対パスであり、releaseと同じ 3 つの形で拒否されます。Release は指定しません。座標にテンプレートを含まないリモートソースは、そのエンティティを使うすべての Release に対して 1 つのアーティファクトを指すため、固定に Release が提供するものは不要です。一方、座標がテンプレートに由来するリモートソースは、aggrega/resolveDependenciesによって Release ごとに固定されます。テンプレートとして記述されたローカルソースはエンティティのディレクトリ内のすべてのファイルを寄与し、それらはそれぞれここで固定されます。dryRunは入力を解決し、ステップが書き込むはずのロックをcontentとして返しますが、エンティティの隣には何も書き込みません。コンテンツキャッシュは引き続き埋められます。応答はentity、kind、name、pinnableを含みます。後者はロックが記録する対象を何も読み取らない種類では false となり、その場合エンティティの隣には何も触れられず、他のフィールドはすべて存在しません。それ以外の場合は、書き込んだlock、changed(ロックがすでにすべての固定を記録しており、バイト単位で同一のまま残された場合は false)、エンティティがロックの記録する対象を何も読み取らなくなりロックが削除された場合のremoved、そして固定のクラスごとに 1 エントリでロックが保持する数を示すpinsを含みます。エンティティファイル自体が書き込まれることはありません。これはワークスペース内のエンティティの隣に書き込み、エンティティのソースが指定するホストにアクセスします。 レジストリへのアクセスと書き込みを参照してください。aggrega/cacheStatus— ディスク上のキャッシュの内容を返します。キャッシュされた要素ごとに 1 エントリで、サイズと、ある場合はコンテンツダイジェストを持ち、種類ごとにまとめられます。ワークスペースのみを受け取ります。各種類はreachを持ちます。このワークスペース自身のキャッシュディレクトリ配下にあるアーティファクトキャッシュはworkspace、マシン上のすべてのプロジェクトが共有するコンパイル済みモジュール、plugin-describe、ドキュメントバンドルの各ストアはmachineです。scopeはマシン全体の種類を直接示します。何も書き込みません。何も変更しない応答に reach がある理由については、レジストリへの到達と書き込みを参照してください。aggrega/cachePrune、aggrega/cacheEvict、aggrega/cacheClear— キャッシュされたコンテンツを回収します。prune はどのワークスペースのロックファイルも参照していないものを削除します。eviction はコンパイル済みモジュールストアをmaxSizeまで縮小します。これはコマンドラインと同じ表記のバイト量(5GiB、512MiB、またはバイト数)です。clear はこのセッションが対象とするすべてのキャッシュを消去します。各応答は削除したものを示し、各削除項目はその由来となったクラスのreachを持ち、各応答はscopeを含みます。各応答は、別のプロセスが開いていたために残したものも示します。Windows は開いているファイルの削除を拒否し、操作は失敗せずに残りの処理を続けます。prune と eviction はそれらのエントリをheldOpenに列挙し、clear は空にした各キャッシュについて、残したファイル数をheldOpenFilesに、そのサイズをheldOpenBytesに数えます。それ以外の環境ではリストは空、カウントはゼロであり、残ったものは後の実行で回収できます。これらはワークスペースの外にまで及びます。 レジストリへのアクセスと書き込みを参照してください。aggrega/registryList— このワークスペースが到達するよう設定されているレジストリを返します。各エントリは、ホスト、任意のエイリアス、デフォルトかどうか、個別のフィールドとしての信頼ポスチャ、そのホストの認証情報が存在するかどうかを持ちます。ワークスペースのみを受け取ります。どのレジストリにも接続しません。認証情報の状態は存在のみを報告します。認証情報そのもの、その形式、レジストリがそれを受け入れるかどうかは決して報告しません(最後のものは、一覧取得では行わないネットワークの往復を必要とします)。また、この状態はマシン全体の認証情報ストアから読み込まれ、そのことをcredentialStateIsMachineWideが明示します。aggrega/search— 設定済みレジストリのローカルインデックスを検索します。すべてのフィールドは絞り込み条件で、いずれも省略可能なため、空の params オブジェクトはインデックスが保持するすべてを要求します。ネットワークには接続しません。インデックスは、このワークスペース自身のキャッシュディレクトリ配下に書き込まれたオフラインのスナップショットです。報告されるバージョンは解決時に採用されるものです。このワークスペースが信頼する署名付きの撤回があるバージョンは除外され、retractedに記載されます。また、回答は自身の出所を示します。indexesは検索した各レジストリのスナップショットの経過時間を示し、staleは更新すべきものを示し、missingIndexHostsはローカルインデックスを持たない設定済みレジストリを示します。これらのレジストリの内容は回答に含まれません。aggrega/registryAdd— レジストリとその署名信頼ポリシーを登録します。hostは必須で、それ以外はポリシーまたは書き込み先を形作ります。keyPathとtrustedRootはファイルを指定します。絶対パスの値(たとえばダイアログで選択したファイル)は指定どおりの場所から読み込まれます。相対パスの値はワークスペース内のファイルを指し、デーモンが実行されているディレクトリではなくワークスペースルートを基準に解決されます。ルートの外へ上がるもの、またはリンクを通じてルートの外へ出るものは、何かを読み書きする前に invalid-params エラーで拒否されます。相対パスのtrustedRootはワークスペース内で指すファイルとして記録されるため、後の検証がどのディレクトリで実行されても、エントリはそのファイルを指します。fetchTrustはキーがない場合 true がデフォルトで、コマンドラインと一致し、初回接続時にレジストリ自身が公開するポリシーを採用します。回答のtrustは何が起きたかを示します。ポリシーが固定された、レジストリが何も公開していなかった(その横にunreachableがある場合は、そもそも到達できなかった)、代わりに公式ハブの組み込みベースラインが固定された、またはフェッチが試みられなかった、のいずれかです。この登録はaggrega registry addが行うものと同じで、同じネットワーク方針のもとで同じフェッチを行い、同じエントリをバイト単位で同一に書き込みます。オフラインのワークスペースでは、接続する前にフェッチが拒否されるため、レジストリに問い合わせることはありません。また、リクエストがidentitiesまたはkeyPathを指定しない限り、公式ハブ以外のレジストリは拒否されます。これらを指定した場合は送信された内容がそのまま登録され、フェッチは行われません。エラーのメッセージはコマンドラインが出力する文で、その前に条件の短いコードE0310が付きます(条件を示すこのリクエストの拒否のメッセージはすべて、その短いコードで始まります)。何も書き込まれません。公式ハブは引き続き組み込みベースラインで書き込まれ、回答ではtrust.baselineが true となり、trust.reasonはワークスペースがオフラインのためハブに信頼ポリシーを問い合わせなかったことを示します(コマンドラインの通知の冒頭と同じ理由です)。ハブには一度も問い合わせていないため、notAdvertisedはありません。これはデフォルトでグローバル設定に書き込みます — レジストリへの到達と書き込みを参照してください。aggrega/registryRemove— ホストまたはフレンドリーエイリアスで指定したレジストリのエントリを削除します。何にも一致しないトークンは、変更のない設定に対する成功として回答されるのではなく、拒否されます。これはデフォルトでグローバル設定に書き込みます — レジストリへの到達と書き込みを参照してください。aggrega/logout— レジストリの保存済み認証情報を削除します。ターミナルでaggrega logoutが行う削除と同じです。registryは必須で、認証したときのレジストリホストを指定します。ここで解決するフレンドリーエイリアスはありません。認証情報ストアは、設定が指定するものではなく、クライアントが認証するアドレスをキーとしているためです。そのため、どのワークスペースも設定していないホストにも、削除できる認証情報がある場合があります。ストアに認証情報がないホストは正常に削除され、何も書き換えられません。ホストに認証情報がない状態を求めた呼び出し元は求めたものを得ているため、これはエラーではなく回答となり、ターミナルのコマンドも同じ動作をします。回答にはregistryとscopeが含まれます。認証情報はいかなる形でも含まれず、認証情報が存在していたかどうかも報告しません。それを確かめるには誰も求めていないストアの再読み込みが必要になるため、存在を知りたい場合はaggrega/registryListに問い合わせてください。レジストリには接続しません。保存済み認証情報の削除はローカルな操作であり、そのレジストリが認証情報を受け入れたかどうかは問い合わせません。これはマシン上のすべてのプロジェクトが共有する認証情報ストアを変更します — レジストリへの到達と書き込みを参照してください。aggrega/registryUpdate—aggrega/searchが読み込む、検索可能なローカルインデックスを更新します。registryがない場合は設定済みのすべてのレジストリを更新し、指定した場合はそのレジストリのみを更新します。upgradeは、すでに書き込まれたインデックスとは何も比較せずに、すべてのリポジトリを完全に読み直します。これがなくても、更新は変更されたものをすでに読み直します。回答には、各ホストのレコード数、読み込めなかったリポジトリ(それぞれreasonを持ち、読み込みの最後の失敗の種類がある場合はそれで始まります)、readsRetried(レジストリが途中で拒否または切断し、再度要求された読み込みの数で、それぞれ 1 回として数え、0 の場合も含まれます)、検出した非推奨マーカー、失敗したホストのerror(そのレジストリに到達できなかった場合はその横にunreachable)、およびインデックスが書き込まれた、このワークスペース自身のキャッシュ配下のディレクトリであるindexRootが含まれます。これは更新するすべてのレジストリに到達します — レジストリへの到達と書き込みを参照してください。aggrega/publishEntity— カタログのエンティティをバンドルし、レジストリに公開します。entityは公開するドキュメントを指すワークスペースルートからの相対パスで、releaseと同じ 3 つの形(指定なし、絶対パス、ルートの外に解決されるもの)で拒否されます。Plugin エンティティにはpluginも必要です。これは同じ種類のパスで、エンティティ自身のマニフェスト内に公開される実行ファイルを指します。registryは公開先で、既定ではワークスペースに設定されたレジストリです。dryRunはバンドルと、その公開で得られるダイジェストを計算し、どのレジストリにも接続しません。signを省略すると公開先レジストリ自身のポリシーに従います。これはフラグがないときにコマンドラインが行う動作と同じです。一方、送信した場合は呼び出し側の選択になります。ただし、どちらも拒否を緩めることはありません。署名を要求するレジストリまたはワークスペースのポリシーは、このフィールドの値にかかわらず署名のない公開を拒否するためです。pinSources: trueは、バンドルの前にエンティティ作成者のピン留めステップをエンティティに対して実行します。そのため、このステップがエンティティの隣に書き込むentity.lockも公開対象に含まれます。これはaggrega/pinが実行するのと同じステップです。このステップは、エンティティの内容を判定する拒否(署名ポリシー、不変性ガード)より前に実行されるため、そこで拒否された公開でもロックは書き込まれたまま残ります。オフラインのワークスペースや公開先がないことなど、リクエスト自体に関する拒否は先に行われ、何もピン留めしません。別のエンティティとディレクトリを共有するエンティティの拒否も同様で、このステップはそこにロックを書き込んではなりません。指定しない場合はワークスペースのpin_sources_at_pushに従い、指定した場合はどちらの方向にもその設定を上書きします。dryRunのもとでは、このステップは書き込むはずのロックを報告し、何も書き込みません。ステップを実行しない公開は、読み取る入力のピンをentity.lockに記録していない Recipe または FeatureRecipe を拒否します。入力がピンと一致しなくなったものも同様で、いずれもバンドルの前に(dryRunのもとでも)拒否され、aggrega pin、pinSources、pin_sources_at_pushを示します。これは同じロックに対してaggrega/resolveDependenciesが出す拒否と同じです。応答にはreference、tag、kind、mediaType、sizeの組、公開されたdigest(dryRunのもとでは、その公開で得られるダイジェストで、aggrega push --dry-runが出力するもの)、signed、alreadyPublished、dryRun、reachが含まれます。ステップが実行された場合はpin(aggrega/pinが返すのと同じ応答)が、エンティティのローカルソースがテンプレートとして記述されている場合は、そのソースを記述どおりに示すwholeDirectorySourceが含まれます。このようなソースは Release がテンプレートを埋めて初めてディレクトリが決まるため、公開にはエンティティが指定するファイルだけでなく、エンティティのディレクトリ内のすべてのファイルが含まれます。このフィールドによって、呼び出し側はそうなったことを知ることができます(ドライランでも同様です)。また、公開に含まれるアーカイブに、Windows がそのままの形では保持できないエントリ(大文字小文字や後に続く拡張子にかかわらず、CON、AUX、NULなどのデバイス名を持つ部分を含むパス、またはピリオドや空白で終わる部分を含むパス)がある場合はwindowsUnusableEntriesも含まれ、エンティティドキュメント自身のファイル名を先頭に、続いてそれが含むファイルの順に、それぞれを示します。該当するものがない場合は存在せず、ドキュメントのみとして公開されるエンティティもこれに含まれます。Windows 上で動作するaggregaはこのようなエントリの展開を拒否するため、Windows のワークスペースではそのバージョンを使用できません。これらはaggrega pushが警告するエントリであり、報告を求めたリクエストは公開の進捗の中で同じ警告行を受け取ります。どちらも何も拒否しないため、公開はこれらがない場合とまったく同じように進行するか拒否されます(dryRunのもとでも同様です)。これはレジストリに書き込み、このマシンの外部に到達します。また、ピン留めステップを伴う場合はエンティティの隣にも書き込みます。レジストリへの到達と書き込みを参照してください。aggrega/publishArtifact— ドキュメントバンドルなどの単独のデータアーティファクトを公開します。fileはワークスペースルートからの相対パスで、同じ取り決めに従い、そのバイト列はそのまま公開されます。エンティティのエンベロープは解析されず、kind による振り分けも行われません。nameとtagは公開時の名前を示し、どちらも必須です。mediaTypeの既定値はドキュメントバンドルのタイプです。応答にはreference、tag、mediaType、sizeの組、公開されたdigest、alreadyPublished、dryRun、reachが含まれます。これは何も署名しません。公開されたアーティファクトは、後からaggrega/signArtifactsで参照により署名します。これに必要なのは、この応答が報告する参照だけです。これはレジストリに書き込み、このマシンの外部に到達します。レジストリへの到達と書き込みを参照してください。aggrega/signArtifacts— 公開済みのアーティファクトに署名し、それぞれに署名を添付します。referencesはパスではなく 1 つ以上のレジストリアドレスを持つため、ワークスペース相対の取り決めは適用されません。空のリスト、またはリスト内の空のエントリは拒否されます。バッチ全体で 1 つのアイデンティティが使われ、どの参照に署名するよりも前に解決されるため、利用できる資格情報がまったくないバッチは途中ではなく最初に拒否されます。参照ごとに異なる資格情報が必要になるバッチも同様です。リクエストは鍵を指定しないため、これはワークスペースの設定が、ある参照のレジストリには保持されている鍵を指定し、別の参照のレジストリには鍵を指定しないか別の鍵を指定している場合です。何も署名されず、References signed together need different signing credentials(同時に署名される参照に異なる署名資格情報が必要です)で説明するとおり、拒否はそれぞれの側のレジストリを示します。何も公開されていない参照への署名は、何もないものに添付されるのではなく拒否されます。また、レジストリのトラストポリシーで検証される署名をすでに持つ参照は、aggrega signで説明するとおり、そのまま残され、署名済みとして数えられます。jobsは省略可能で、同時に署名する参照の数を指定します。省略すると参照は 1 つずつ順に署名され、1 未満の値はどの参照も読み取る前に invalid-params エラーで拒否されます。各参照は、aggrega signで説明するとおり、単独で署名する場合とまったく同じように署名され、リクエストが報告する進捗と応答はどちらも参照が渡された順序を保ちます。応答にはsignedが含まれ、各エントリはreferenceと、その署名が対象とする公開済みのdigestを示します。あわせてreachも含まれます。いずれかの参照が失敗したバッチは、短いリストを持つ結果としてではなく、失敗した各参照を示す失敗として応答されます。これはレジストリに書き込み、このマシンの外部に到達します。レジストリへの到達と書き込みを参照してください。aggrega/deprecateArtifact— 公開済みのアーティファクトに、署名付きの非推奨マーカーを添付します。severityとreasonを伴う単一のreference、またはワークスペースルートからの相対パスでバッチファイルを指定するfromのどちらかを送信します。両方を送信すると拒否されます。内容のフィールドは入力を促されるのではなく必須です。このストリームを見ている人はいないため、いずれかが欠けたリクエストは、送信すべきものを示して拒否されます。これらのフィールドは単一のreferenceにのみ属します。バッチファイルは各マーカーの内容をそれぞれのエントリに持つため、fromとともに送信されたseverity、reason、replacement、messageは無視されるのではなく、送信されたそれぞれを示して無効なパラメータとして拒否されます。マーカーはそれ自身のダイジェストで署名されるため、2 つの署名リクエストが受け取るのと同じキーレスの入力がここでも適用されます。また、バッチファイルのエントリは、署名バッチの参照とまったく同じように 1 つの資格情報に限定されます。応答にはmarkedが含まれ、各エントリは非推奨にされたreference、そのseverity、issuedOnのタイムスタンプ、マーカー自身のマニフェストのdigestを示します(マーカーは非推奨にするアーティファクトのタグなしの referrer として添付されるため、ほかに参照する手段はありません)。あわせてreachも含まれます。これはレジストリに書き込み、このマシンの外部に到達します。レジストリへの到達と書き込みを参照してください。aggrega/catalogIndex— エンティティインデックスです。リクエストが指定したワークスペース内のすべてのエンティティのkind、name、apiVersion、description、labels、ソースファイル、originを返します。ワークスペースと、任意でreleaseを受け取ります。この集合はそのワークスペースルートと、それが設定するカタログディレクトリの性質であり、releaseを指定した場合は、設定がその Release に与えるディレクトリの性質です。1 つの Release の観点での応答を参照してください。インデックスはエンティティの出所となる 2 つの場所、つまりワークスペースルート配下の Aggrega ドキュメントと、設定されたカタログディレクトリが持つ Features の両方にまたがります。これは、クライアントがエンティティの記述的フィールドを必要とするときに結合する対象であり、どちらか一方しか知らないインデックスでは、あらゆる候補リストの一部が解決できなくなるためです。ワークスペースのドキュメントは、kind:とmetadata.nameの両方を宣言し、かつ他のプロジェクトのグループに属するapiVersionを宣言していない場合にエンティティとみなされます。そのため、たまたまツリー内にある YAML(チャートの values ファイル、CI の設定、レンダリング済みの Kubernetes マニフェストなど)は一覧に含まれず、スキップされます。apiVersionをまったく宣言していないドキュメントは報告されます。これはフィールドが欠けた Aggrega ドキュメントであり、一覧に表示されることで修正すべきものがあると分かります。originと空のfileの意味については、エンティティのアドレス指定方法を参照してください。ワークスペースルートの外へ出るリンクの先にあるドキュメントは読み込まれません。ルート外のディレクトリは検索されず、ルート外のファイルは何を宣言していても読み込まれません。そのため、エディタがそのようなリンクの下に表示するエンティティは、ワークスペース自身のものとして一覧に含まれません。同じドキュメントを読むaggrega/attachCandidatesやaggrega/connectionCandidatesからも、エディタがそのドキュメントを開いている間であっても提示されません。これはドキュメントが何を宣言していても同じです。唯一の例外は、ワークスペース設定がbuild.authoring_releaseとして、またはworkspace.releasesのキーとして指定する Release です(リンク先のファイルで判定されるため、リンクを指定してもそのファイルを指定しても同様に扱われます)。これはリンク先のファイルから読み込まれ、aggrega/releaseCandidatesが一覧にするのと同様にリンク自身の場所に一覧され、名前は挙げられません。これらの設定のいずれかが指定するファイルが Release 以外のものを宣言している場合は一覧に含まれず、そのリンクの名前が挙げられます。設定されたカタログディレクトリは、ワークスペースが別の場所に保管された他のエンティティを読み込む手段です。そのため、設定がcatalog_dirsの下に(ワークスペース用でも Release 用でも)列挙するディレクトリへのリンクは、ワークスペース自身のドキュメントのようには検索されず、名前も挙げられません。設定がそこに到達しているため、その Features は、設定されたすべてのカタログディレクトリと同様にカタログから一覧されます。カタログディレクトリから一覧される Features には、カタログディレクトリの読み込みがとどまるべきディレクトリ(ワークスペース内のカタログディレクトリならワークスペース、設定がワークスペース外に指定するものならそのディレクトリ自体)の外へ出るリンクの先にあるものは決して含まれません。そのため、応答が読み込まなかったリンクの先にあると名前を挙げたエンティティが、その名前と並んで一覧されることもありません。応答は、そのようなリンクを、ディレクトリへのリンクであればunreadLinkedDirsに、リンク自身の名前が.yamlまたは.ymlで終わりファイルに至るリンクであればunreadLinkedFilesに、リンクが置かれた場所のルートからの相対パスで、ワークスペースの検索順に挙げます。これによりクライアントは理由を説明できます。名前、置かれた場所、または.gitignoreによって検索から除外されるリンクは挙げられず、Release の観点での応答では、他の Releases だけが読むカタログディレクトリ配下のリンクも挙げられません。ワークスペース外のカタログディレクトリ配下のリンクには、ルートからの相対的な場所がないため、挙げられません。両フィールドは常に存在し、該当するリンクがない場合は空です。ワークスペース自身の設定ファイル、またはその隣にある CI 管理のオーバーレイ自体がワークスペースの外へ出るリンクである場合、検索での扱いにかかわらずそのファイルはunreadLinkedFilesに挙げられ、インデックスは何も設定されていない状態でのワークスペース自身の読み込みになります。カタログディレクトリは読み込まれず、Release の観点でのインデックスは拒否されます。ワークスペースルートとアクティブな Release を参照してください。aggrega/entityDefinition— 指定したエンティティが何に解決されるかを返します。そのkind、自身のnameとversion、存在する場合はdescriptionとpublishScope、宣言されたfile、その背後にある記述テキストのauthoredLength、そして継承が適用済みの YAML ドキュメントとしてのdefinitionです。fileはすべての種類について、開くことのできるパスとして報告されます。報告されるパスの表記方法に従い、ワークスペース内のドキュメントはワークスペースルートからの相対パス、外のドキュメントは絶対パスです。空になるのは 1 つの場合だけで、レジストリから解決されたエンティティには、このマシン上に指し示せる記述ドキュメントがありません。authoredLengthは別の問い、つまり解決がどれだけの記述テキストを保持したかに答えるもので、それを伴って提供されるのは Aggregate だけです。そのため、2 つを組としてではなく別々に読んでください。nameはエンティティの識別子で、あるエンティティが別のエンティティを参照するときと同じ形で書かれ、バージョンのサフィックスを含むことがあります。ここでカーソルではなく名前から始まるリクエストはこれだけなので、どのエンティティを指すかがすでに分かっているときに使います。releaseは任意で、その Release の観点で名前を解決します。1 つの Release の観点での応答を参照してください。何にも解決されない名前は、空のドキュメントで応答されるのではなく拒否されます。名前による 2 つの拒否の見分け方を参照してください。nameには代わりにレジストリ参照(oci://<host>/<repository>:<tag>、または:<tag>の代わりに@<digest>)を指定することもでき、その場合の応答はその座標で公開されたエンティティをレジストリから読み込んだもので、publishedが読み込んだものを示します。座標についての問い合わせを参照してください。aggrega/releaseClosure— Release の依存関係クロージャです。どのエンティティにどの解決済みバージョンで到達するかをentities、libraries、pluginsに示し、あわせて 2 つのポインタが解決されたaggregateとmanifestの識別子、解決が発生させたmappingDiagnostics、および到達したものに対してロックファイルとその隣にあるプラグイン信頼記録に記録されたdeprecationsを返します。そのため、判定ロールでアタッチされた撤回済みのプラグインも、撤回済みのピン留めされた参照と同じように示されます。releaseはワークスペース内の Release を指すワークスペースルートからの相対パスで、aggrega/irGraphが受け取るのと同じ値であり、同じ形の場合に拒否され、同じ理由でロックファイルを必要とします。何もレンダリングされません。エントリはsourceを示しません。エントリが述べるのは Release が何に依存するかであり、1 回の実行が何をしたかではありません。後者はaggrega/resolveDependenciesが報告します。すでにグラフを受け取っているクライアントもこれは持っていないため、クロージャはグラフではないを参照してください。aggrega/attachCandidates— ノードにアタッチできる Features、すなわち宣言された適用条件をノードのラベルが満たすものを返します。座標はちょうど 1 つ送ります。nodeはワークスペースのドキュメントをそのmetadata.nameで指定します。graphNodeはreleaseのコンパイル済みグラフ上のノードを、そのグラフがキーとする id で指定します。labelsはラベルセットをそのまま渡すもので、何も指定せず、すでにラベルセットを保持しているクライアント向けです。レスポンスは応答対象の座標を繰り返し(繰り返すものがなければ空)、マッチの評価に使われたラベルのペアであるnodeLabels、それがどの種類のラベルセットかを示すlabelSource、そして各候補をそれを指定するkind、name、ソースファイル、originとして含みます。ラベルを返すことで、回答はそれ自体で監査可能になります。クライアントはノードのラベルについて独自の解釈を持たずに、ある Feature が提示された理由を説明できます。独自の解釈を持つことこそ、クライアントの回答とコンパイラの回答が食い違う原因です。グラフノードの場合、提示される Features はそのノードの Release が到達するものです。graphNodeと並べて、connectionはそのノードの component が描く接続の 1 つ(そのsocketとalias)を指定し、その場合回答にはslotsも含まれます。これはその接続のソケットが宣言する各スロットと、それを埋められる Features です。どれも埋められない場合はnoSlotReasonが含まれます。アタッチ候補のレスポンスからわかることを参照してください。aggrega/connectionCandidates— 指定されたエンティティが接続できる先を返します。nodeはエンティティのmetadata.nameで、aggrega/attachCandidatesが同じ名前で受け取る座標と同じです。回答の 2 つの部分は同等に完全ではなく、どちらがどちらかはレスポンスが示すため、後述の接続候補のレスポンスからわかることを参照してください。aggrega/insertionPoint— 作成済みドキュメント内で、指定されたコンテナの下の新しいエントリがどこに入るかを、クライアントがドキュメント自体をパースせずに適用できる形で返します。fileはワークスペースが持つドキュメントを、ワークスペースルートからの相対パス、絶対パス、またはそのfile://アドレスで指定します。ルート外のドキュメントは、記述のとおりであれ、ルート外へ通じるリンク(ファイルへのリンク、または途中のディレクトリへのリンク)経由であれ、どの表記で指定されても、またそのコピーを保持しているかどうかにかかわらず拒否されます。containerはドキュメントルートからエントリを入れるコンテナまでの構造的パスで、各要素はマッピングキーまたは 10 進数で書いたシーケンス位置です。このパスは呼び出し側が指定します。デーモンはドキュメント自身の構造を読み取り、何かがどこに入るべきかを名前から推測することはありません。位置だけでは編集を適用するのに十分ではないため、挿入位置のレスポンスからわかることを参照してください。aggrega/attachmentContainer— あるノードへの Feature のアタッチメントがどのドキュメントに属し、その中のどのコンテナに入るかを返します。graphNodeはreleaseのコンパイル済みグラフ上のノードを、そのグラフがキーとして使う ID で指定します。両方とも必須です。ノード ID は 1 つの Release のグラフのキーであり、それなしでは意味を持たないためです。回答にはnode、file、containerが含まれます。これはaggrega/insertionPointが受け取るのとまったく同じ形のセグメントのリストであり、この 2 つは間で何かを導き出す必要なく組み合わせられます。ノードのコンポーネントが描く 1 つの接続へのアタッチメントの場合は、そのsocket、alias、document(aggregateまたはrelease)を持つconnectionを追加します。すると回答は、そのドキュメント内にあるその接続自身のfeaturesコンテナを指定します。fileは既に分かっているものではなく回答の一部であるため、attachment-container レスポンスからわかることを参照してください。aggrega/connectionAtPosition— Aggregate または Release 内の位置がどの接続のエントリ内にあるかを、上の 2 つのリクエストが接続を受け取る形で返します。fileはaggrega/insertionPointと同じ方法でドキュメントを指定し、まずセッションがそのドキュメントについて保持している内容から読み取られます。positionはその中の場所で、セッションのエンコーディングで 0 から数えたlineとcharacterです。releaseは接続を記録するコンパイル済みグラフを持つ Release を指定します。グラフノードと接続はコンパイル済みグラフ上にのみ存在するため、Aggregate 内の位置に対しても必須です。回答にはgraphNodeとconnection(そのsocket、alias、位置が読み取られたdocument)が含まれ、そのままaggrega/attachCandidatesとaggrega/attachmentContainerに渡せます。そこに接続が書かれていない場合はnoConnectionReasonが含まれます。位置にある接続のレスポンスからわかることを参照してください。aggrega/editDocument— 作成済みドキュメントに範囲の限られた構造化編集を 1 つ適用し、触れないバイトはすべて保持します。これは上の 2 つの位置特定メソッドのもう半分です。それらはエントリがどこに入るかを示し、組み立てと適用は呼び出し側に任せますが、こちらは 1 つを組み立てて適用します。editはadd-component、attach-feature、wire-edge、set-valueの 4 つのうちどれかを指定し、それ以外の値は解釈されずに拒否されます。nodeはドキュメントルートからの構造的パスで、aggrega/insertionPointが受け取るのとまったく同じ形のセグメントのリストです。nameはエントリが書かれるキー、valueはその内容で、意味はeditによって決まります。socketはwire-edgeの場合に読み取られ、それ以外では無視されます。dryRunは書き込み以外は通常のリクエストと同じことをすべて行い、編集後のドキュメントをcontentとして返します。結果をまず作成者に見せるクライアント向けです。このとき何も作成されず、writtenは空です。fileはワークスペースルートからの相対パスまたは絶対パスでドキュメントを指定し、ルート外のドキュメントは、記述のとおりであれ、ルート外へ通じるリンク(ファイルへのリンク、または途中のディレクトリへのリンク)経由であれ、何も読み書きされずに拒否されます。これはワークスペース内の指定したドキュメントに書き込みます。依存関係は解決せず、レジストリにアクセスせず、どちらの配信方式でもネットワークに触れません。書き込みは、組み立てたドキュメントがその kind 自身のスキーマに対して検証を通ることを条件とします。デフォルトは書き込みであり、拒否された場合ファイルはバイト単位で元のままであるため、ドキュメント編集のレスポンスからわかることを参照してください。aggrega/releaseCandidates— リクエストが指定したワークスペースの Release ドキュメントを絶対パスで返します。ワークスペース以外は何も受け取りません。この集合はそのワークスペースルートの性質です。所属はファイル名ではなくドキュメントの種類、つまりファイルのkind:がReleaseであるかどうかで決まります。そのため、慣例的な接頭辞なしで命名された Release も候補に含まれ、単にそれらしい名前が付いているだけのファイルは含まれません。エディタの「どの Release?」ピッカーが一覧表示すべきなのはこの集合です。後述のアクティブ Release のカスケードが選択する集合と同じだからです。応答にはlockfilesも含まれます。これは一覧に含まれる各 Release を、releasesがその Release を列挙する文字列とまったく同じキーで、そのロックファイルの絶対パスに対応付けます。このフィールドは常に存在し、ワークスペースに Release がない場合は空のオブジェクトになります。応答にはunreadLinkedDirsも含まれます。これは、一覧作成時にディレクトリとして読まれる位置にあり、かつワークスペースルートの外にあるディレクトリへ通じる各リンクを、リンクがある場所としてルートからの相対パスで示します。ルートの外のディレクトリは検索されないため、エディタがそうしたディレクトリ内に表示する Release は一覧に含まれません。このフィールドにより、ピッカーはその理由を示せます。ワークスペース設定がcatalog_dirsに列挙しているディレクトリへのリンクは示されません。設定がそのディレクトリに、Releases を置く場所としてではなくカタログディレクトリとして到達しているためです。このフィールドも常に存在し、該当するリンクがない場合は空になります。その隣にあるunreadLinkedFilesは、自身の名前が.yamlまたは.ymlで終わり、ワークスペースルートの外のファイルへ通じる各リンクを同じ方法で示します。そうしたファイルは内容にかかわらず読まれないため、これらのリンクを通じてのみ到達する Release は一覧に含まれず、後述のカスケードの単一 Release のステップでも数えられません。例外は、ワークスペース設定が Release として指定しているファイルです。build.authoring_releaseとして、またはworkspace.releasesのキーとして指定されたもので、リンクの通じる先のファイルで判定されるため、リンクを指定してもそのファイルを指定しても同じに扱われます。このファイルは Release を宣言していればリンク自身の場所で読まれて一覧に含まれ、リンクは示されません。それ以外を宣言している場合は一覧に含まれず、そのリンクが示されます。このフィールドも常に存在し、該当するリンクがない場合は空になります。ワークスペース自身の設定ファイル、またはその隣にある CI 所有のオーバーレイ自体がワークスペースの外へ通じるリンクである場合、検索での扱いにかかわらずそのファイルがここに示され、一覧は何も設定されていない状態で読まれます。そのため、設定がリンクを通じて指定するはずだった Release は一覧に含まれません。ワークスペースルートとアクティブ Release を参照してください。Release のロックファイルの場所 も参照してください。aggrega/activeRelease— リクエストが指定したワークスペースがどの Release を指しているかを、releaseフィールドの絶対パスとして返します。既定で何を選択するかを決めるクライアントのためのものです。ワークスペース以外は何も受け取りません。このフィールドは常に存在し、空の値はワークスペースがどの Release も指していないことを意味します。これはエラーではなく正常な応答であり、デーモンの再起動のたびにこれを更新するクライアントが、通常のワークスペースを失敗として扱わされることはありません。値が空の場合、応答にはカスケードが何を探したかの一行の要約であるreasonと、そのステップごとの記録であるtraceも含まれます。どちらも Release が解決された場合は省略されます。Release が解決された場合、応答には代わりにその Release のロックファイルの絶対パスであるlockfileが含まれ、解決されなかった場合は省略されます。ここで示される Release はaggrega/releaseCandidatesが一覧に含めるものである必要はありません。マーカーは、その一覧が除外するディレクトリ(vendor/など)にある Release や、YAML の拡張子なしで命名された Release を指すことがあります。そのため、クライアントは既定の Release のロックファイルをこの応答から読み取ります。Release のロックファイルの場所 を参照してください。カスケードの入力のいずれかから応答を導き出すのではなく、このリクエストで問い合わせてください。カスケードが最終的に使わなかった入力は、カスケードが選んだものとは別の Release を指しています。応答は問い合わせた時点で計算されるため、マーカーを書き込んだ後、設定を編集した後、または Release ファイルを追加した後に再度問い合わせると、デーモン起動時のワークスペースの状態ではなく新しい応答が返されます。aggrega/setActiveRelease— リクエストが指定したワークスペースの.aggrega/active-releaseマーカーを書き込むことで、ある Release をそのワークスペースのデフォルトとして記録し、マーカーの書き込み後にaggrega/activeReleaseが返すのとまったく同じ形で応答します。ワークスペースとreleaseを受け取ります。これはワークスペースルートからの相対パスで、その内部の Release を指します。aggrega/irGraphのreleaseと同じ契約に従い、絶対パス、ワークスペースの外へ上るパス、空の値は拒否されます。ワークスペース設定がその Release を指定していない限り、リンクを通じて外へ出るパスも拒否されます。マーカーは Release をルートからの相対で指す 1 行で、後述のカスケードが読む形式です。マーカーはワークスペースの内部にだけ書き込まれます。.aggregaまたはマーカー自体がワークスペースの外へ出るリンクである場合(リンク先がまだ存在するかどうかにかかわらず)、リクエストは invalid-params エラーで拒否されます。そのメッセージは、条件自身の文の前に短いコードを付けたE0320: …で(fatal-halts.md §「A path the operation writes leads through a link out of the directory it must stay inside(操作が書き込むパスが、留まるべきディレクトリの外へリンクを通じて出ています)」)、リンクとそのリンク先を示し、何も書き込まれません。ワークスペースの内部に留まるリンクは、そのリンクを通じて書き込まれます。応答は送信した内容をそのまま返すのではなく、カスケードが最終的に選ぶものを示します。build.authoring_releaseが Release を指定している場合は設定がマーカーより優先されるため、両者は異なります。デフォルトはファイルを自分で書き込むのではなくこの方法で記録してください。そうすることで、マーカーが書き込まれる場所は、製品がワークスペースに書き込むすべてのファイルに適用される規則によって判断されます。The workspace boundary を参照してください。aggrega/effectiveConfiguration— リクエストが指定したワークスペースに対して有効な設定と、各設定項目がどのレイヤーから来たかを返します。ワークスペース以外は何も受け取りません。応答はそのワークスペースの性質です。layersは寄与した設定ファイルと環境変数による上書きを、優先度の低いものから順に列挙します。settingsは、出所が特定された各設定項目を、ドット区切りの名前、有効な値、それを決定したsourceとして示します。sourceはlayersの対応するエントリとまったく同じ表記になるため、両者をそのまま結合できます。sourceがどのレイヤーを示すか、および各行が意味する内容の範囲については、effective-configuration 応答が対象とする範囲 を参照してください。aggrega/configInit— レジストリとその署名の信頼ポリシーを登録して、動作する設定を初期化します。これにより、新しいマシンでも YAML を手で編集せずに署名済みアーティファクトを取得して検証できます。registryは省略可能で、値がない場合は公式ハブで初期化されます。これはaggrega config initと同じデフォルトです。応答のhostは実際に使われたものを示します。globalとworkspaceは書き込み先の上書き指定で、両方を送ると拒否されます。既存の設定ファイルは上書きせずに拒否し、そのファイルを示します。それでも続行するにはforceを送ります。その場合、レジストリのエントリが既存の内容にマージされ、他の設定は保持されます。dryRunは書き込み以外は通常のリクエストと同じ処理をすべて行い、初期化された設定をcontentとして返します。これは保存前に作成者にドキュメントを提示するクライアント向けです。この場合は何も作成されず、writtenは false になります。既存ファイルの拒否はdryRunでも適用されるため、上書きする書き込みが生成するマージ結果を得るには、forceを併せて送ってください。オフラインのワークスペースでは公式ハブのみ初期化できます。このリクエストは ID も鍵も受け取らないため、他のレジストリはaggrega/registryAddが拒否するのとまったく同じように、短いコードと文も含めて拒否されます。そうしたレジストリは、代わりに手動でポリシーを指定してそのリクエストで追加します。応答にはhost、scope、trust、writtenが含まれます。また、設定ファイルがすでに存在していた場合(新しいファイルを作成するのではなく、レジストリのエントリがそのファイルにマージされた場合)に true となり、ファイルが作成された場合は存在しないexistedも含まれます。これはデフォルトでグローバル設定に書き込みます — レジストリへの接続と書き込みを参照してください。aggrega/configCapture— 有効なビルドに不可欠な設定をこのワークスペース自身の設定ファイルに固定し、下にマシンのグローバル設定がなくてもワークスペースが同じようにビルドされるようにします。書き込み先は指定しません。固定は 1 つのワークスペースを自己完結させるためのものなので、常にそのワークスペースのファイルに書き込みます。allPluginsは、固定する対象を、レンダリング出力を決定するソケット(provider バインディングと label-transform のガバナンスアタッチメント)から、すべてのプラグインソケットへと広げ、verdict のガバナンスゲートとリンターゲート、およびインポートソケットを加えます。回答にはconfigFile、workspaceRoot、captured、sockets、catalogDirsが含まれます。回答は新たに存在するようになったドキュメントを示し、クライアントの次の操作はそれを開くことになるため、設定の書き込み後に残るものを参照してください。aggrega/skillsInstall— このバイナリに組み込まれた Aggrega スキルを、リクエストが指定する各アシスタントのスキルフォルダーに書き込みます。これはaggrega skills installがターミナルで行うのと同じインストールです。agentsはアシスタントを識別子(aggrega/skillsListが報告する識別子)で列挙します。2 回指定された識別子は 1 回だけインストールされ、指定されたアシスタントのうち複数が 1 つの共有フォルダーを読む場合、スキルはそこに 1 回だけ書き込まれます。プロジェクトへのインストールではこれが必須です。アシスタントを何も指定しないglobalリクエストは、--agentなしのaggrega skills install --globalと同様に、このマシンで見つかったアシスタント(設定フォルダーがホームディレクトリにあるもの、またはコマンドがデーモンの環境のPATH上にあるもの)向けにインストールし、1 つも見つからない場合は何も書き込まずに拒否されます。入力を求めることはなく、installedが書き込んだ対象のアシスタントを示します。globalがない場合、スキルは各アシスタントの、リクエストが指定するワークスペース内のプロジェクトフォルダーに置かれ、デーモンが起動されたディレクトリに置かれることはありません。global: trueの場合は、デーモンの環境が示すホームディレクトリ(HOME、Windows ではUSERPROFILE)の下にある各アシスタントのユーザー単位のフォルダーに置かれます。何かを書き込む前にすべての書き込み先が確認されるため、拒否された場合はすべてのフォルダーが元のまま残ります。スキルフォルダーが不明な識別子は、その識別子と既知の識別子を示して拒否されます。書き込み先にあるファイルが、書き込まれるスキルのすべてのコピーが持つコメント行を持たない場合は、そのパスを示して拒否されます。その行を持つコピー(以前のインストールが書き込んだもの、または公開されているスキルリポジトリから取得したもの)は置き換えられます。新しいaggregaはこの方法でスキルを自身のバージョンに更新します。ワークスペースの外へ通じるリンクを経由して到達するプロジェクトフォルダーは、デーモンがワークスペースで行うすべての書き込みと同様に、何も書き込まれずに拒否されます。ワークスペースの境界を参照してください。応答にはskill、installed(書き込まれたフォルダーごとに 1 エントリで、アシスタントが指定された順に並び、それぞれそのフォルダーを読むagents、絶対パスのfolder、replacedを持つ)、およびscopeが含まれます。globalを指定すると、マシン上のすべてのプロジェクトが読むフォルダーに書き込みます。レジストリへのアクセスと書き込みを参照してください。aggrega/skillsList— このバイナリが同梱するスキルと、aggrega/skillsInstallがそれらを書き込めるすべてのアシスタントです。aggrega skills listが出力する一覧と同じです。ワークスペースのみを受け取り、ワークスペースからは何も読みません。skillsは各スキルのnameとdescriptionを持ちます。agentsは各アシスタントのid、name、projectFolder(プロジェクトのルートからの相対パスで、このインターフェースではプロジェクトのルートはリクエストが指定するワークスペース)、userFolder(ホームディレクトリからの相対パス)を持ち、どちらもスラッシュ区切りで、識別子順に並びます。何も書き込まず、どこにもアクセスしません。aggrega/pluginAdd— 設定されたレジストリから指定した種類のプラグインを検索し、設定に追加します。typeとqueryはどちらも必須です。typeはprovider、governance、linter、importer、cliのいずれかで、queryはその種類のプラグイン名と照合され、ちょうど 1 つに解決される必要があります。そのため、複数に一致するクエリは任意に解決されるのではなく、候補とともに拒否されます。capabilityはproviderバインディングが提供する機能を指定し、その場合は必須です。roleはgovernanceアタッチメントのロール(label-transform、ir-verdict、render-verdict)を指定し、その場合は必須です。それぞれ自身の種類に対してのみ読み取られ、他の種類では拒否されます。黙って何もしないフィールドは、うまく動作したかのように見えてしまうためです。acceptCapabilitiesはcliで必須であり、そのプラグインが宣言した機能を承認します。ターミナルコマンドは問い合わせてその判断を得ますが、このインターフェースには問い合わせる相手がいないため、呼び出し側がその判断を得て送信します。globalとworkspaceは書き込み先の上書き指定で、両方を送ると拒否されます。dryRunは書き込み以外は通常のリクエストと同じ処理を行い、結果の設定をcontentとして返します。何も作成・変更されず、writtenは false になります。その内容に含まれる ID は書き込み時に固定されるはずの ID であるため、レジストリの検索とバージョンの解決は引き続き行われます。dryRunはcliの種類では無視されるのではなく拒否されます。コマンド拡張の追加が記録するのは検証したバイト列のコンテンツダイジェストであり、これは誰かが編集する内容ではなくコンパイラが管理する記録です。また、追加処理はその過程でそれらのバイト列をキャッシュします。そのため、内容を返すのではなく書き込みます。バージョンは自動的に固定されます。クエリは 1 つのプラグインに解決され、クエリが<name>:<version>として指定したバージョン、指定がない場合はそのプラグインの最新の公開バージョンがエントリに書き込まれます。指定されたバージョンは、このワークスペースが信頼する撤回によって取り下げられていてもそのまま固定され、応答にはwithdrawn: trueが含まれます。これはレジストリに接続し、どちらのスコープも指定しないcliの種類の追加はグローバル設定に書き込みます — レジストリへの接続と書き込みを参照してください。プラグインの変更からわかることも参照してください。aggrega/pluginRemove— 設定済みプラグインのエントリを削除し、関与しないようにします。typeは追加で受け付けるものと同じ集合で、queryはエントリを特定します。プラグインの短い名前、固定された参照、またはproviderの場合はバインディングが提供する機能です。どちらも必須です。globalとworkspaceは同じ書き込み先の上書き指定で、同様に両方を送ると拒否されます。どのエントリにも一致しないクエリは、変更のない設定に対して成功として回答されるのではなく拒否されます。そのため、呼び出し側が、実際には関与し続けているプラグインについて関与しなくなったと伝えられることはなく、タイプミスによって別のプラグインが削除されることもありません。レジストリには接続しません。削除は設定のテキストだけを対象とします。どちらのスコープも指定しないcliの種類の削除はグローバル設定に書き込みます — レジストリへの接続と書き込みを参照してください。プラグインの変更からわかることも参照してください。aggrega/pluginSync— Plugin エンティティのマシン管理の記録を、そのモジュールに合わせます。対象は、モジュール自身のインポートから導出されるホスト関数の集合と、モジュールの自己報告から読み取られるコマンドミラーです。どちらの記録も、モジュール内にある事実そのものであるため、手で記述するものではありません。両フィールドとも必須で、どちらにもデフォルトはありません。記録はモジュールから導出されるため、何も指定しない調整には合わせる対象がないからです。どちらもワークスペースルートからの相対パスで、絶対パスの場合や、記述どおりまたはリンク経由でルートの外に解決される場合は拒否されます。変更されるのはこの 2 つのブロックだけです。それ以外のバイトはコメント、空行、引用符のスタイルも含めてそのまま引き継がれ、すでにモジュールの内容どおりの記録を持つファイルはバイト単位で同一のまま残され、変更なしとして報告されます。これは指定したエンティティファイルにワークスペース内で書き込み、レジストリには接続しません。プラグインの変更からわかることを参照してください。aggrega/pluginGenCatalog— 選択した guest ごとに Plugin エンティティを 1 つ生成し、guest の自己報告から導出したコントラクトフィールドと、作成者が記述したプラグインごとのオーバーレイをマージします。fromEmbeddedとpluginは 2 つの選択モードで、適用されるのはちょうど 1 つです。このバイナリが持つすべての guest か、指定したパスにある 1 つのモジュールです。両方を指定した場合も、どちらも指定しない場合も、解決されずに拒否されます。overlayは必須で、fromEmbeddedではオーバーレイのディレクトリ、pluginでは単一のオーバーレイファイルです。複数ある場合はオーバーレイが ID によって guest に照合され、1 つの場合は照合するものはありません。outputDirはどちらの配信方法でも必須で、dryRunでも省略できません。ドライランが変えるのは内容の行き先であり、それがどのファイルの内容かではないため、返される各ドキュメントは対象のパスを示し、そのパスはこのディレクトリから組み立てられます。ここでの 3 つのパスは同じようには判定されず、その違いは生成処理が各パスをどう扱うかに従います。pluginとoverlayは読み取られ、どちらも選択したファイルです。モジュールはツールチェーンのビルド先ディレクトリに置かれ、そのオーバーレイはその隣に記述されるため、どちらも絶対パスでよく、実際にある場所から読み取られます。outputDirは書き込み先であるため、ワークスペースルートからの相対パスであり、絶対パスの場合や、そのまま、またはリンクを経由してルートの外に解決される場合は拒否されます。外へ向かうリンクされたディレクトリの下にある未作成のディレクトリは、そのディレクトリと同様に拒否されます。変更のない入力で再実行すると、バイト単位で同一のエンティティが生成されます。これは、dryRunで内容として要求しない限り、生成したエンティティをワークスペース内のoutputDirの下に書き込みます。プラグインの変更からわかることを参照してください。aggrega/getSchema— エンティティまたはコントラクトの種類の JSON Schema で、実行中のバイナリにコンパイルされたコピーから読み取られます。kindは小文字ハイフン区切りのスキーマトークン(component、aggregate、release、recipe、ir、wasm-providerなど)で、2 つの問いのどちらを尋ねるかを選ぶため省略可能です。種類を指定すると、レスポンスはkindとschemaを持ち、スキーマはそれを含む文字列ではなく JSON ドキュメントとして返されます。指定しない場合、レスポンスは代わりにkindsとentityKindsを持ちます。これは指定できる種類を 2 つの範囲で示します。kindsはこのバイナリに要求できるすべてのトークンで、aggrega get-schema --listが出力するのと同じ順序です。entityKindsは作成者がドキュメントを書く対象となる、より狭い集合で、各エントリは送り返すkindトークン、ドキュメント自身のkind:フィールドに入るdocumentKindの値、そして単一エンティティの検証、公開、名前による検査がその種類のドキュメントを受け付けるかを示すacceptedByを持ちます。どちらかから選択 UI を構築する前に、作成者に提示できる種類を参照してください。スキーマの回答と列挙は組み合わされることがないため、どちらの問いに答えたかはレスポンスから読み取れます。どのスキーマにも該当しないトークンは、有効な集合全体をメッセージに含めて拒否されるため、2 回目の呼び出しなしに誤字を修正できます。ワークスペースから何も取得せず、レジストリにも接続せず、何も書き込まないため、何も含まないワークスペースでも応答します。これにより、他の場所にインストールされたスキーマのコピーではなく、エディタが実際に駆動しているバイナリに対してエディタのスキーマ関連付けを設定するのに使用できます。aggrega/scaffoldEntity— エンティティの種類のひな形ドキュメントです。その種類のスキーマが必須とするフィールドだけを含み、固定のapiVersionとkindが記入され、値が必要な箇所にはすべてプレースホルダーが入ります。kindは必須で、小文字ハイフン区切りのスキーマトークン(component、aggregate、release、recipe、manifest、featureなど)です。kindを指定しないaggrega/getSchemaは送信できるトークンを報告し、どのスキーマにも該当しないトークンはその集合をメッセージに含めて拒否されるため、2 回目の呼び出しなしに誤字を修正できます。作成者に種類の選択肢を提示するクライアントは、そのメソッドのentityKindsを読みます。これはドキュメントを書くことのできる種類の集合です。nameは省略可能で、スキーマがmetadata.nameを必須とする種類ではその初期値になります。レスポンスはkindとskeletonを持ちます。回答は書き込まれたドキュメントではなく、これから書くドキュメントであるため、スキャフォールドのレスポンスが提供するものを参照してください。スケルトンはaggrega/getSchemaが報告するのと同じスキーマから導出されるため、両者は 1 つの情報源から応答します。kindの代わりにexampleを送ると、ドキュメントの実行可能なサンプルの 1 つをワークスペースの新しいディレクトリに書き出します。これはaggrega scaffold --exampleがターミナルで行うのと同じです。list: trueだけを送ると、存在するすべてのサンプルを返し、何も書き出しません。どちらの形式もワークスペースを必要とするため、いずれのリクエストもworkspaceRootでワークスペースを指定し、指定しないリクエストは拒否されます。dirは新しいディレクトリをワークスペースルートからの相対パスで指定し、デフォルトはサンプルの名前です。絶対パスの値や、ルートの外に解決される値(書かれたとおりでも、リンクを経由してでも)は何かを読み込む前に拒否され、何かを含むディレクトリは拒否されてそのまま残されます。一覧への回答はexamplesを持ち、各要素はname、level、summaryを持ちます。書き出しへの回答はexample、dir、files(書き出された各ファイルで、dirからの相対パス)、next(サンプルのページが示すビルド用のコマンドで、示されていない場合は存在しません)、version(サンプルを読み込んだドキュメントのバージョン)を持ちます。2 つの形式のフィールドを一緒に送ると(kindとexample、listとexampleまたはkind、nameとexampleまたはlist、あるいはexampleなしのdir)、何かを読み込む前に、アシスタントのツールが拒否するのと同じ文言で拒否されます。書き出しは、ワークスペース自身の署名検証が認めるコピーがマシン上にない場合にドキュメントバンドルを取得し、ワークスペース内に書き込みます。レジストリへのアクセスと書き込みを参照してください。aggrega/import— 外部のソース記述を Aggrega の作成用ファイルの下書きに変換します。端末でaggrega importが行うのと同じ変換です。sourceは必須で、変換するファイルまたはディレクトリを、絶対パスまたはワークスペースルートからの相対パスで指定します。別のツールがエクスポートした記述は保存した場所にあるため、ワークスペース内に限らず実際にある場所から読み取られます。ディレクトリはaggrega importと同じように読み取られます。つまり、インポーターが宣言したファイルパターンが選択するファイルが、ワークスペースのビルド出力フォルダーdist/を除いて読み込まれ、どこにあってもそのディレクトリ内に限定されるため、内部のリンクをたどって外に出ることはありません。outputDirは省略可能で、下書きを置くディレクトリを指定しますが、この扱いは受けません。書き込み先であるため、ワークスペース内のパスでなければならず、絶対パスの値や、ルートの外に解決される値(そのまま、またはリンクを経由して。その下にある未作成のディレクトリも含む)は拒否されます。省略すると、下書きはワークスペースルートの下に置かれます。これはaggrega importが出力先を指定しない場合に書き込む場所で、dryRunでも同様です。formatはソース形式を明示的に指定します。省略すると、インポーターが宣言するシグネチャ(ワークスペースのカタログのものとコンパイラのコアインポーターのもの)によって形式が認識されます。どれも認識しないソースや、複数の形式のインポーターが認識するソースは、推測されずにformatを求めて拒否されます。targetはcomposeやhelmなどのプロバイダーのケイパビリティ(Recipe のspec.capabilityが結び付く語)を指定し、インポーターの下書きに加えて、下書きされた Release がそのプロバイダー向けにビルドする Manifest を、aggrega import --targetとまったく同じように下書きします。これはmanifest.yamlで、下書きが必要とする各コンポーネントタイプと各機能タイプ(下書きされた Aggregate が構成するカタログの Aggregate のタイプも含む)を、ワークスペースのカタログがそのタイプに提供するそのケイパビリティの Recipe または機能レシピに、バージョンなしのケイパビリティ修飾名でマッピングします。対象は、1 つしかなければそれ、複数あればそのタイプにちなんだ名前を持つものです。Release のspec.manifestはそれに設定されます。該当するものがないタイプや、複数あってもそのように名付けられたものがないタイプは、それを示すwarnの検出結果とともにマッピングされないまま残されます。また、インポーター自身が下書きしたマッピングは、カタログがそのタイプとケイパビリティに対して提供している場合は保持され、そうでない場合はwarnの検出結果とともに破棄されます。カタログ内のどの Recipe も結び付かないtargetは、インポーターの実行前に、それとカタログの Recipes が結び付くケイパビリティを示して拒否され、何も書き込まれません。省略すると Manifest は下書きされません。ただしsyncでは、以前のインポートの記録が示すターゲット向けに下書きされます。マシンがまだ持っていないコアインポーターは、それを必要とする最初のインポートで取得されます。インポートのレスポンスからわかることを参照してください。dryRunは書き込み以外は通常のリクエストと同じ処理をすべて行い、下書きを内容として返します。これは先に作成者に下書きを提示するクライアント向けです。この場合は何も作成されず、writtenは空です。syncは、以前のインポートがoutputDirに下書きしたものを、インポートが書いた部分だけを変更してソースに合わせて更新します。aggrega import --syncと同じ動作です。これを指定しない場合、下書きが既存の Aggregate を上書きすることになるリクエストは拒否されます。回答はformat、outputDir、written、files、drift、diagnostics、decisions、haltedを持ちます。インポーターが完全に変換できなかったソースはエラーではなく成功した回答になるため、インポートのレスポンスからわかることを参照してください。aggrega/explainError— コードが示す状態についてコンパイラが宣言している内容と、作成時の修正方法を説明する公開済みエントリです。codeは必須で、状態の識別子のどちらでも受け付けます。診断がshortCodeに持つ短いコードか、codeに持つ説明的なコードです。これはこのワイヤ上の診断がすでに持っているコードの展開であり、aggrega explainがターミナルで出力するものと同じ回答です。回答には常に状態 (shortCode、code、message) が含まれます。これはバイナリ内で宣言されており、ネットワークを必要としないためです。entriesには公開済みのウォークスルーが含まれ、それが欠けている場合はnoteがその理由を示します。マシンが、ワークスペース自身の署名検査が認めるコピーを保持していない場合、これはドキュメントバンドルを取得します。 レジストリへの到達と書き込みを参照してください。診断が持っていたコードの展開も参照してください。aggrega/invalidate— エディタのファイルウォッチャーからのキャッシュ無効化シグナルです。
通知:
$/cancelRequest— クライアントからサーバーへ: その id で送信された処理中のリクエストを停止します。デーモンはそのリクエストの処理をキャンセルします。操作はキャンセルを即座にではなく次のステップ境界で検知するため、すでに進行中の処理はしばらく続きます。何も実行されていない id をキャンセルしても、安全に何も起こりません。$/progress— サーバーからクライアントへ: 長い操作が実行中に何をしているかを、リクエストが報告先として指定したトークンで伝えます。トークンを持つリクエストに対してのみ送信されます。長い操作の監視を参照してください。aggrega/shutdown— 協調的なドレインを開始します。処理中のリクエストは完了し、新しいリクエストは拒否され、その後デーモンが終了します。aggrega/publishDiagnostics— サーバーからプッシュされる診断セットです (lockfile のドリフト警告と起動時の状態に使用されます)。各エントリは、デーモンのどの診断レイヤーがそれを発したかを示すsourceを持ちます。作成されたドキュメントに関する検出結果にはaggrega、ビルドが発したアドバイザリにはaggrega-build(ビルドが発したすべてのアドバイザリで、aggrega buildが出力するものと同じセットです)、公開の慣例に関する検出結果にはaggrega-lint(aggrega lintが出力するものと同じ検出結果です) が使われます。このフィールドはすべてのエントリに常に存在するため、クライアントは区別のない一覧を表示する代わりにそれらをグループ化でき、source がない場合といずれかのレイヤーの場合を区別する必要はありません。フレームは、ファイルのセットがこのクライアントに最後に伝えたものと異なる場合にのみ送信されるため、同じ検出結果を再計算するリクエストは何も送信しません。ファイルの最初のフレームと、ファイルのセットを空にするフレームはどちらも差分であり、常に送信されます。
プロセス自体に停止を求めた場合も、同じ条件でデーモンに伝わります。 ターミナルからの割り込み、またはスーパーバイザーやコンテナランタイムからの終了要求は、aggrega/shutdown が開始するのと同じドレインを開始します。処理中のリクエストは完了し、新しいリクエストは拒否され、その後デーモンが終了します。2 回目の要求はプロセスを即座に終了させます。デーモンを起動するクライアントはどちらの方法でも停止でき、ワイヤ経由で停止するクライアントとシグナルを送るクライアントは同じドレインを得ます。
ライブ検証
aggrega/validate を受け取るたびに、デーモンはエディタのバッファをそのドキュメントのスキーマに照らして検証し、問題のあるキーを指す診断を返します。これは、保存されていない内容に対してビルドが下すのと同じ判定です。content を送らないリクエストは、ディスク上にあるままのファイルについて問い合わせます。空で送られた content は空のバッファであり、ファイルの要求ではありません。内容なしで送られるファイルは、ワークスペースが持ち、かつ読み取れるものでなければなりません。ワークスペース外のファイル、ワークスペースの外へ通じるリンクを経由して到達するファイル、存在しないファイルは、invalid-params コードで拒否されます。カタログエンティティ、Aggregates、Manifests、Releases は、その apiVersion と kind によって認識されます。そのようなヘッダーを持たない 2 つのドキュメント、すなわち .aggrega-config.yaml ワークスペース設定と、リクエストが指定した Release のロックファイルは、代わりにファイル名で認識されるため、いずれかに不正なキーや形の崩れたキーがあれば、それもライブで波線が表示されます。Aggrega ドキュメントではないファイル、すなわち Helm チャートテンプレート、Compose ファイル、Kubernetes マニフェスト、Cargo.lock や flake.lock のような他のエコシステムの .lock ファイルには診断は付きません。デーモンが外部のファイルについて報告することはありません。
まだ埋められていないプレースホルダーは、そのキーの位置で、取るべき値とともに示されます。 aggrega validate が単一エンティティとして検査する種類のカタログエンティティは、空文字列のまま残している必須値についても、そのコマンドが適用するのと同じ読み方で読まれます。そのため、デーモンは同じバイト列に対してコマンドが示すすべてのプレースホルダーを示します。各プレースホルダーは 1 つのエントリです。その message はキーがまだ埋められていないプレースホルダーであることを述べ、suggest はその値が取るものを述べ、keyPath はキーのドット区切りのパスを持ちます。このエントリは、その空の値に対するスキーマ自身の検出結果の代わりとなり、ドキュメント上のその他の検出結果はすべてスキーマ検査が報告するとおりに報告されます。スキーマが空を許容するプレースホルダーも、スキーマ検査はそれについて何も報告しませんが、示されます。下書きの Recipe や FeatureRecipe の capability と implements がよく見かけるものです。スキーマ検査もドキュメントを拒否する場合、各エントリはその検査のコード E0215 を持ち、ドキュメントを受け入れる場合、エントリはコードを持ちません。これは、そのバイト列に対してコマンドのレポートが持つのと同じ識別子です。エントリは空の値を保持するキーの位置、コマンドがそれを示す行に描画されます。component.aggrega.ai/type ラベルのように名前自体にドットを含むキーであっても同様です。そのキーについてスキーマ検査が報告する検出結果は、それを囲むキーの位置に描画されますが、keyPath はキーを完全な形で示します。これはリクエストが Release を指定するかどうかにかかわらず成り立ちます。ドキュメント自体が答える問いであり、まだ値を埋めていないドキュメントは、公開の慣例について問われる段階にはまだないからです。そのレイヤーは、スキーマが形を拒否するドキュメントの場合と同様に、このドキュメントについてはクリアされます。
各リクエストは対象とする Release を指定し、デーモンは独自の Release を保持しません。 セマンティック検査は、その Release の依存関係のクロージャを解決し、ピンのためにその Release のロックファイルを読み取ります。カタログエンティティの場合は、次の段落で説明するとおり、その Release がビルドに使うカタログディレクトリを読み取ります。そのため、2 つの Releases を指定する 2 つのリクエストには、それぞれが指定した Release について答えが返されます。リクエスト間で引き継がれるものはありません。変更すべき選択済みの Release はなく、どの Release に対して検証するかを変えることは、次のリクエストで別の値を送ることであり、デーモンに何かを忘れるよう伝える必要はありません。
Release とともに指定されたカタログエンティティは、その Release の観点で単一エンティティとして検査されます。 Component、Feature、Recipe、FeatureRecipe、Plugin のいずれかを保持する file が release とともに送られると、aggrega validate <path> --release <release> が実行する検査を、エディタの未保存バッファに対して受けます。その参照、すなわち Recipe が実装する Component や、ピラーが参照するライブラリは、ワークスペース設定がその Release に与えるカタログディレクトリを通じて解決されます。そのため、1 つのファイルが、それを使ってビルドする Release の観点ではクリーンで、参照先をディレクトリが保持していない Release の観点では失敗することがあります。これは、同じ Release のもとで同じエンティティに対してコマンドラインと aggrega mcp の validate ツールが下す判定と同じであり、それらと同様に、クロージャをたどることもロックファイルを読むこともありません。ブロッキングとなる検出結果は、検査自身の文言でそのコードを持つ 1 つのエラーエントリとなり、診断エントリが持つもの で説明するとおり、エンティティ内でそれが示すキーの位置に、何も示さない場合はエンティティの kind: キーの位置に描画されます。ただし、ビルドがそのファイルについてすでにその不具合を報告している場合は、ビルドのエントリが唯一の報告となります。検査がカタログの読み取り中に出すアドバイザリは、その前に置かれる警告エントリとなります。すべてのディレクトリが存在する状態でのクリーンな検査では、エントリは返されません。失敗したアサーション、すなわち Recipe 内またはそれが実装する Component 内で fail を呼ぶアサーションは、ここではブロッキングとなる検出結果ではなく警告エントリとなります。検査の文言でそのコードを持ち、A Release must satisfy this assertion before a build of it can pass. という文で締めくくられ、ブロッキングとなる検出結果が置かれる場所に描画されます。Recipe のアサーションは assertions の下にあるそのアサーション自身のキーの位置に、Component のアサーションは Recipe の kind: キーの位置に描画されます。ブロッキングとなる検出結果と同様に、そのファイルについて同じ不具合を報告するビルドのエントリがあればそちらに譲ります。検査は、Release が設定する値ではなくプレースホルダーとスキーマのデフォルトを使ってエンティティを組み立てるため、Release を待っているアサーションと壊れているアサーションを区別できず、判定をビルドに委ねます。ビルドは同じアサーションをエラーとして報告します(失敗したアサーションは警告です)。ワークスペース設定がその Release について列挙しているディレクトリがディレクトリでない場合(たとえばそこに何も存在しない場合)、検査はそこから先に進みません。ファイルには検査の判定の代わりに 1 つのエラーエントリが付きます。これはすべてのコマンドがそのディレクトリに対して返す拒否であり、そのエントリ、それを列挙している設定ファイルと行、および設定項目を示します(ローカルエンティティの読み取り元)。ファイルを指していない、またはディレクトリを指している release には、ワークスペースの観点で検査されるのではなく、コマンドラインがそれを拒否するときの文がファイル上で返されます。単体のビルドでは代替できないものはコマンドラインが判断するとおりに判断され、コマンドラインが除外するもの、または検査しないものについては、ここでエントリは返されません。単一エンティティの正しさが検査しないもの を参照してください。また、トポロジーのエッジまたはアタッチされた認証情報だけが届ける値をテンプレートが読み取る Recipe については、単一エンティティの正しさ を参照してください。Release 自身の Aggregate、Manifest、Release、ライブラリは 1 つずつ検査されません。単一エンティティ検査はこれらの種類を受け付けないためです。これらには上記のクロージャの検査が引き続き適用されます。Workload の内容を保持するバッファは、Aggrega ドキュメントではない YAML として読まれます。その内容は Recipe や FeatureRecipe の workload: フィールドの中に書かれ、置かれているその場所で検査されるためです。コマンドラインと validate ツールは、パスで Workload ファイルを渡されると、その形を単独で検査します。
Release の指定は任意で、応答はどちらを求めたかを示します。 指定すれば上記のすべてが得られます。指定しなければ、ドキュメントが単独で答えられるチェック、すなわちパースできるか、自身の形が許容されるか、そして単一エンティティとして検証される種類のカタログエンティティであれば、まだ未設定のプレースホルダーはどれか、が得られます。このとき Release は解決されず、クロージャは辿られず、ロックファイルも読まれません。応答には checked: "document" が含まれます。Release を指定した場合、このキーはありません。その応答はメソッドの完全な判定であり、限定すべきことがないためです。
診断から推測せず、このキーを読んでください。2 つの応答は同一に見えることがあるためです。Release なしで検証された整形式のドキュメントは空の診断リストを返し、これは問題のない完全な判定が返すものとまったく同じです。そのため、「何も問題がない」と「Release を必要とするものは何も調べられていない」を区別するのは checked だけです。同じ規則から 1 つの帰結が導かれます。ロックファイルはリクエストが指定した Release との対応によって認識されるため、Release を指定しないリクエストはロックファイルを認識せず、それについて何も報告しません。
Release を持たないワークスペースは拒否されずに応答され、それがそこでデーモンの他の機能を使える状態に保ちます。 検証は、他のすべてのファイル操作が読むパースキャッシュを初期化するものです。そのため、カタログのみのリポジトリ、単一 Aggregate のスキャフォールド、作業用ディレクトリでも、ホバー、補完、定義へのジャンプ、参照、実装、キャッシュされた診断が得られます。拒否すれば、クライアントが指定すべき Release を持たないまさにそのワークスペースで、これらすべてが失われます。
診断エントリが持つもの
各エントリは line と column で位置を示し、どちらもハンドシェイクで取り決めた位置エンコーディングで 1 始まりです。トークン全体にわたる場合は end_line と end_column を加えます。message はクライアントがユーザーに表示するテキスト、severity はその分類、source は上述のとおり、デーモンのどのレイヤーがそれを出したかを示します。
レイヤーは 1 つのファイルについて異なる問いに答えるため、各レイヤーのエントリが同じ行に並んでも、互いの重複ではありません。一方はデプロイメントが正しくないと述べ、もう一方はエンティティが公開可能でないと述べます。それらを 1 つのリストとして表示するクライアントは、1 つの問題を 2 回報告することになり、両者を区別するのは source を読むことです。
エントリの位置は、どのレイヤーが出したかではなく、何についてのものかで決まります。 作成者が書いたものについての検出結果は、それを書いたキーに配置されるため、エディターは編集すべき場所にそれを描画します。デプロイされたトポロジの形についての検出結果は、行ではなくコンポーネントとデリバリーキーを示します。これらはドキュメントではなくデプロイされたトポロジ内の座標です。そのため、ドキュメントの kind: キーに描画され、座標は代わりにメッセージ内で示されます。ビルドはどちらも出すため、どちらの種類も aggrega-build レイヤーに届きます。ビルドがレンダリング中に出した拒否もこのレイヤーに届き、拒否自体が指すドキュメント上に置かれます。チェックを満たさない Workload はその Recipe の workload キーに、Recipe の失敗したアサーションはそのアサーション自身のキーに、グラフの合成が拒否するエントリは Release または Aggregate がそれを書いたキーに、複数をまとめる拒否の各検出結果はそれぞれ自身のドキュメントとキーに置かれます。どのドキュメントも指さない場合は、Aggregate の kind: キーに置かれます。詳しくは A refusal raised while rendering(レンダリング中に出された拒否) を参照してください。したがって、クライアントは各エントリを自身の line と column で配置し、レイヤーから位置を推測してはいけません。
ドキュメントが持つキーを示さない検出結果は、ドキュメントを示すキーに描画されます。 ドキュメント自身のチェックがその内容について出す検出結果、単一エンティティチェックの検出結果、ビルドが出すアドバイザリや拒否は、それぞれが示すキーに描画されます。キーを示さない場合、またはドキュメントが持たないキーを示す場合は、ドキュメントの kind: キーに、kind: を宣言していない場合はその metadata.name に描画され、どちらも宣言していないかパースできない場合に限ってファイルの先頭に描画されます。ドキュメントはコメントで始まることが多く(どのカタログファイルもライセンスヘッダーを持ちます)、最初の行に描画されたエントリはそのコメント上に置かれ、コメントの不備のように読めてしまいます。一方、ドキュメント自身の識別情報は作成者が書いた行です。ドキュメントの内容以外についてのエントリはファイルの先頭に置かれます。Release の依存関係についての Dependencies: エントリ、ドキュメント内の何も示さずに停止したステージ、ずれたロックファイル、レンダリングが断念せざるを得なかった参照、読み込めなかった Release がそれにあたり、行を算出しなかったルールの aggrega-lint エントリも同様です。位置が描画されるのではなく記述される場合も、キーを示さない検出結果は位置を持ちません。キーを示さない拒否のエラー応答は、その data にドキュメントのみを持ちます。
エントリがどのドキュメントに公開されるかも同じ規則に従います。 Release を指定した検証は、その Release の Aggregate、Release 自体、Aggregate がインポートする各モジュールのドキュメント、および Release が指定する Manifest に答えます。Release 内に位置づけられる検出結果、つまり Release がコンポーネントの接続の 1 つに書くエントリ、その接続に与えるサイジング、そこで埋めるかサイジングするアタッチメント、配線する接続、Release だけがコンポーネントや境界にアタッチする Feature、あるいはアタッチメントに与える infra の拒否は、Release ドキュメントが検証されたときに、それを書いた Release 内のキーに公開され、Aggregate にはまったく公開されません。モジュール自身のドキュメント内に位置づけられる検出結果、つまりモジュールのコンポーネントの 1 つが宣言するもの、そのアタッチメントが配線するソケット、その値、またはその自身の接続上の値の拒否は、そのモジュールのドキュメントが検証されたときに、そこでそれを書いたキーに公開され、Aggregate にはまったく公開されません。Manifest のマッピングテーブルについての検出結果、つまり型をその型を実装していない Recipe または FeatureRecipe にマッピングするエントリ、バージョンのピンを解析できないエントリ、または extends チェーンをたどれないマッピング対象の型についての検出結果は、その Manifest が検証されたときに、対象となるマッピングエントリのキーに公開され、Aggregate にはまったく公開されません。Manifest の開いているテキストがそのエントリを書いていない場合(自身の extends を通じて継承するエントリや、未保存の編集で削除されたエントリなど)、検出結果は Manifest の 1 行目に公開されます。その Release の検証が出すその他の検出結果はすべて Aggregate に公開されます。その中には、ワークスペースのどのドキュメントも示さない依存関係レベルの検出結果、つまり撤回された参照やプラグイン、extends チェーンを解決できないかスキーマが無効なカタログの Component や Feature、信頼記録と一致しないゲートプラグイン、どのマッピングでも解決されないコンポーネントインスタンス、宣言している入力種別をプロバイダーがレンダリングできない Recipe や FeatureRecipe、そしてスキーマピラーの重複と extend 時の絞り込みに関する助言が含まれます。したがって、ビルドのどのステージが出したかにかかわらず、オペレーターが書いたものについての検出結果は Release を開いている間に、モジュールが宣言するものについての検出結果はそのモジュールを開いている間に、マッピングについての検出結果は Manifest を開いている間に表示されます。開いているすべてのドキュメントを Release に対して検証するエディターでは、それぞれがそこに表示されます。依存関係をまったく解決できない Release はそれらの検出結果を出さず、解決の失敗は 1 つのエントリとして、Release 自身のドキュメントの先頭と、それに対して検証される他のすべてのドキュメントのうち、Live validation で説明するとおりデーモンが認識し、単一エンティティとしてはチェックしないもの(その Aggregate、その Manifest、ライブラリ、別の Release、ワークスペース設定)の先頭に置かれます。このエントリは Dependencies: で始まり、何が解決を止めたかについての解決処理自身の説明を持ちます。Release 自身のドキュメントでは、エントリはその説明だけです。他のすべてのドキュメントでは、まずそのドキュメントがその Release に対してチェックされていることを述べ、リクエストが指定するとおりに Release を示します。Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved: の後に説明が続きます。そのドキュメント内には、どの Release に対してチェックされたかを示すものが何もないためです。選択された 1 つの Release に対して開いているすべてのドキュメントをチェックするエディターは、その Release と無関係なドキュメントにもこのエントリを置くことになり、名前があることで選択が原因だとわかります。デーモンが認識しないファイルは、どの Release が指定されていても、このようなエントリを持ちません。
応答は、検証がどこまで進んだかにかかわらず、ファイルに存在するすべてのレイヤーを持ちます。 aggrega/validate の応答はファイルの現在の状態全体です。今回の検証が見つけたもの、ビルド、プレビュー、グラフリクエストがファイルに公開した aggrega-build エントリ、そして公開の慣例に関する検出結果が、それぞれ自身の source の下に含まれます。バッファの段階で停止する検証、つまりパースできないものや、エンベロープをスキーマが拒否するドキュメントも同じように応答します。自身の検出結果を報告し、ファイル上のビルドエントリはすべてそのまま残します。ビルドについては何も知り得なかったためです。したがって、クライアントはどの応答からでも、ファイルについて保持しているものをレイヤーごとに置き換えられます。
1 つの不具合は 1 回だけ報告されます。 ドキュメント自身の検証とビルドが、そのドキュメント内で同じ不具合を見つけることがあります。単一エンティティのチェックはビルドもレンダリングする Recipe をレンダリングし、検証はビルドが構成するグラフを構成し、依存関係が解決しない Release は両方で失敗します。ビルドがあるドキュメントでそのような不具合を報告している間、そのドキュメントの検証はそれを再度報告しません。同じドキュメント上のビルドの拒否と同じ条件(同じ code)を示す aggrega エントリで、同じ範囲に置かれるか、独自のキーを持たない位置(キーを示さないエントリが描画される位置、またはファイルの先頭)に置かれるものは、そのドキュメントのすべての応答とすべての公開から除外され、ビルドの報告だけが残ります。ビルドの報告とは、aggrega-build レイヤー上の拒否のエントリです。あるいは、依存関係が解決しないために 1004 で拒否された aggrega/build、aggrega/buildPreview、aggrega/irGraph の場合は、その応答そのもの(何も公開しません)であり、その data.file が示すドキュメント、なければ data.lockfile、なければリクエストが指定した Release 上のものです。ある Release についてはそのような応答のうち最新のものが有効です。検証は見つけたものを保持します。どのビルドもその不具合を報告しなくなると(次の実行がその不具合を含まないレイヤーを公開する、その Release に対する次のビルド、プレビュー、グラフの応答がそれ以外のものになる、またはそのような 1004 を返されていないクライアントが接続する)、ドキュメント自身のエントリが再び報告されます。ビルドが一度も実行されていない場合は何も除外されません。どのビルドの拒否も置かれていないキーに置かれた aggrega エントリは、同じ条件を示していても残ります。ビルドがまだ報告していない、同種の 2 つ目の不具合である可能性があるためです。
code は、エントリが報告する内容を示す安定した機械照合可能なコードであり、クライアントはメッセージテキストを照合せずにこれで分岐できます。誰が割り当てたかにかかわらず、1 つのキーがコードを運びます。 レイヤーごとに異なる語彙で名前を付けるため、どの種類のコードを保持しているかは source が示します。
aggregaエントリ(作成されたドキュメントに関する指摘)では、コードは条件が登録されている文字列であり、宣言するパッケージに続けてルールをケバブケースで記述したものです。これは Go の利用者がCodeOfで読み取る値と同じであり、その形式と照合可能な範囲はエラーセンチネルのリファレンスで説明しています。aggrega-buildエントリ(ビルドが発した勧告)では、コードは発生元が割り当てたものです。ビルドは 2 種類の異なる対象について勧告を発するため、このレイヤーは 2 つの異なる語彙の勧告を運びます。デプロイされたトポロジの形状に関する勧告は、unsupported-fieldのようなクラスコードを持ち、レンダリングプラグインであれレンダー自体であれ、発生した場所で割り当てられます。クラスコードは登録された条件ではなく勧告のクラスを示すため、センチネルのリファレンスに行はありません。unsupported-fieldクラスとそれを抑止するフラグは警告のリファレンスで説明しています。作成されたドキュメントに関する勧告(宣言された名前と 1 文字違いの名前、何も読まないパラメーターなど)は、その条件が登録されている文字列を、aggregaエントリと同じ形式で持ち、センチネルのリファレンスに行があります。いずれの場合も、コードは誰が見つけたかではなく指摘が何であるかを示すため、1 つのクラスは何か所で発生しても 1 つのコードで届きます。どちらを保持しているかを示すのはレイヤーではなくコードです。ビルドがレンダリング中に停止した拒否は、ここで勧告ではない唯一のエントリであり、同様にその条件が登録されている文字列を持ちます。aggrega-lintエントリ(公開時の慣例に関する指摘)では、コードは指摘の識別子です。つまり、それを生成したルールの識別子、またはルールを示さない指摘(独自のリンターが独自のコードで報告することがあります)の場合はそのコードです。これはaggrega lintが指摘の行に、短縮コードがある場合はその後に出力する識別子であり、aggrega lint --output jsonがその同じ指摘についてruleId、またはルールを示さない指摘についてはcodeとして運ぶ値です。1 つの指摘は各インターフェースで 1 つの識別子を保つため、エディターであるルールをグループ化または抑止するクライアントは、ターミナルでも同じルールをグループ化および抑止します。Aggrega が宣言する公開リンターのルールセットの各ルールは、その識別子で条件として登録されているため、すべての条件の表に、aggrega lintが同じ指摘の行の先頭に出力し、aggrega lint --output jsonがshortCodeとして運ぶ短縮コードで掲載されています。Aggrega が宣言しない独自のリンターのルールは登録された条件を示さず、ルールを示さない指摘も、そのコードが Aggrega の宣言するルールの識別子と同じ綴りであっても条件を示さないため、どちらもそこには掲載されません。ルールはaggrega lintのリファレンスで説明しています。
どのレイヤーでも、このキーは 1 つの問い、つまり機械が照合できる形でこれは何か、に答えます。そのため、あるクラスの指摘を強調表示、グループ化、抑止するエディター拡張機能はコードをキーにし、メッセージの文言が変わっても動作し続けます。
どのオブジェクトが何を運ぶかに注意してください。これは診断エントリ上の文字列であり、後述のエラーコードで説明する JSON-RPC エラーエンベロープ上の数値の code とは別物です。応答はどちらか一方を運び、1 か所に両方を持つことはありません。
エントリを生成したものがコードを割り当てなかった場合、このキーは省略され、どの種類にもその場合があります。YAML パーサーが読み込めないバッファーは、Aggrega 自身の条件が背後にないため、パーサー自身のテキストをコードなしで報告します。条件を示さずに失敗を報告するステージも同様に報告するコードを持たず、発生元がコードを割り当てなかった勧告もコードなしで届きます。そのため、code は end_line や end_column と同様に省略可能なものとして扱い、存在する場合にのみそれで分岐してください。コードは診断が報告するものであり、診断を選択するものではありません。コードを受け取るリクエストはなく、独自のコードにコードを書き戻しても、照合の手段ではなく単なる文字列が得られるだけです。
プログラムが照合する識別子と、人が引用する識別子
条件は 2 つの識別子を持ち、それぞれ異なる読み手のためのものです。 code は上で説明したもので、修飾されハイフンで区切られているため、それで分岐するプログラムは意味どおりに読めます。shortCode は文字 E と 4 桁の数字(E0164)で、人が読み上げたり、検索ボックスに入力したり、issue に貼り付けたりできるものです。どちらも同じ条件を指し、一方が他方の略称というわけではありません。
どちらを使うかは、誰が読むかで決まります。 拡張機能では code で照合し、作成者には shortCode を提示します。code だけを表示する拡張機能は、プログラム向けの識別子を読み手に渡すことになり、shortCode で照合する拡張機能は、条件について何も表さない番号で照合していることになります。この役割分担があるため、一方ではなく両方が送られます。
codeDescription は条件が公開されている場所であり、{ "href": … } として送られます。これは、診断についてさらに詳しく知るために開く参照を表すプロトコル自身の構造です。プロトコルに対応したエディタは、Aggrega について何も教えられなくても、これを「詳細を見る」機能に変換します。また、どのクライアントも説明のコピーを持つ必要がありません。このアドレスはすべての条件の公開リストを指し、そこでは shortCode の項目が条件を示し、作成時の修正手順の解説へと続きます。
説明文そのものはエントリに含まれません。これは意図的です。 診断は編集のたびに出力されるため、各診断に説明を載せると、たいていすでに読んでいる読み手に対して、キー入力のたびに同じ段落を再公開することになります。本文が必要なクライアントは、後述の aggrega/explainError で一度だけ要求します。リンクをたどれるクライアントにはどちらも不要です。
両方のキーは、エントリが登録済みの条件を指す場合にのみ存在し、それ以外の場合はどちらも存在しません。 これを決めるのは、どのレイヤーがエントリを公開したかではなく、エントリの背後に何があるかです。そのため、レイヤーではなくキーを読んでください。
- 登録済みの条件を指すエントリは 3 つすべてを持ちます。
shortCodeは解決でき、参照はそれが解決されるリストを指します。 - コードがクラスを指すエントリは
codeだけを持ちます。 レンダリングのアドバイザリのクラスや、独自のリンターによる慣例の検出結果の識別情報(Aggrega が宣言していないルール、またはルールを指さない検出結果が持つコード)は、グループ化や抑制に使える実際の識別子ですが、どちらも登録済みの条件ではありません。そのため、引用する番号はなく、そのアドレスにもそれらを説明するものはありません。それでも参照を送ると、読み手の問題とは関係のないページを開くリンクになってしまうため、送られません。これはaggrega-buildレイヤーでの通常の形ですが、登録済みの条件を指すビルドのアドバイザリは、他と同様に 3 つすべてを持ちます。aggrega-lintレイヤーでは完全なセットが通常の形です。Aggrega が宣言する公開リンターのルールセットのルールは登録済みの条件であるため、その検出結果は、aggrega lintが検出結果の行の先頭に出力するのと同じshortCodeと、その横の参照を持ちます。 - 何も指さないエントリは、識別子を一切持ちません。
したがって、3 つの場合はキーだけで区別できます。code がなければ指すものがないことを、code があって横に shortCode がなければそれ以上解決されない識別子であることを、完全なセットがあれば詳しく読める場所を持つ識別子であることを意味します。2 つの新しいキーは code と同様に省略可能なものとして扱い、codeDescription が届いた場合にのみ、読み手に開くものを提示してください。
診断が持つコードを展開する
aggrega/explainError は、条件のどちらかの識別子を、コンパイラがその条件について宣言している内容と、作成時の修正方法を解説する公開エントリに変換します。これは aggrega explain がターミナルで、explain-error ツールがアシスタント向けに行うのと同じ展開であり、3 つとも同じ場所から回答します。そのため、ここで展開したコードと別の場所で展開した同じコードは、たまたま一致する 3 つの回答ではなく、1 つの回答です。
code は必須で、どちらの識別子も受け付けます(診断が持っていた shortCode、またはその横の code)。一方を持つクライアントは、問い合わせずにもう一方を得る方法がないためです。空の値は、何を送るべきかを示して拒否されます。
回答には常に shortCode、code、message が含まれます。これらは条件の 2 つの識別子と、その条件を指すすべての診断の冒頭の文です。これらはバイナリ内で宣言されているため、ネットワークもキャッシュもなしで届きます。これにより、ドキュメントを持たないワークスペースにも回答できます。reference は診断の codeDescription が持つのと同じアドレスで、説明文を表示するよりも読み手をドキュメントに案内したいクライアント向けです。
entries は公開された解説を持ち、各エントリは、それを始める heading とその下の body として、ドキュメント自体が条件と対応付けている順序で並びます。解説を追加できなかった場合は省略され、その理由を note が示します。公開ページにこの条件のエントリがまだない場合か、このワークスペースがドキュメントを読めない場合(マシンにコピーがない、またはワークスペースの署名チェックが拒否するコピーしかない)です。いずれの場合も上記の条件は有効です。回答は失敗ではなく、クライアントは届いた内容とその横の注記を表示します。entries と note が両方届くことはありません。
何にも解決されないコードは、すべてのフィールドが空の条件で回答されるのではなく拒否され、各拒否はそれがどの場合かを示します。どの条件も登録されていないコード、かつて条件を指し今後別の条件を指すことのない番号、または公開リストをまったく読めなかった場合にこのバイナリが宣言していないコードです。最後の場合は両方の修正方法が残ります。別のバージョン向けに公開されたリストには、このバイナリが宣言していない条件が含まれる可能性があるためです。
ドキュメントは、リクエストが指定するワークスペース用にキャッシュされたバンドルから読み込まれ、存在しない場合は初回使用時に取得されます。これが、このリクエストがレジストリにアクセスする唯一の理由です。レジストリへのアクセスと書き込みを参照してください。ワークスペースには何も書き込まれません。検証がこれを引き起こすことはありません。展開はリクエストが要求したときに行われるため、ドキュメントの検証中や検査中にレジストリにアクセスすることはありません。
公開の慣例:リクエスト時と編集のたびに
デーモンはカタログエンティティについて 2 つの異なる問いに答えます。これはターミナルで aggrega validate と aggrega lint が答える問いと同じです。すなわち、デプロイメントが正しいかどうか、そしてエンティティがカタログの慣例に照らして公開可能かどうかです。検証は常に前者に答えます。後者には、求めた場合にのみ答えます。
aggrega/lint はそれを直接求めます。 1 つのカタログエンティティには entity を、その Release の依存クロージャが到達するすべてのエンティティには release を送り、どちらも送らなければ設定されたカタログディレクトリ配下のすべてのエンティティを検査します。これがコマンドの持つ 3 つのスコープです。entity と release を両方送ると 2 つの異なる対象を指定することになり、拒否されます。応答には、実行が対象としたエンティティドキュメントの数である checked と、検出結果を対象ドキュメントごとにまとめてパス順に並べた files が含まれ、各ファイルのエントリは前述の診断の形をとります。halted は、実行自体の判定が公開を拒否するかどうかを示します。
どちらも送らない場合、引数なしの aggrega lint と同様にカタログ全体を検査します。 設定が独自の Release カタログディレクトリを与えていないワークスペースは、自身のディレクトリに対して 1 回検査され、応答は前述のとおりです。workspace.releases の下で Releases を指定しているワークスペースは、その中の各 Release について、その Release が読むディレクトリに対して 1 回ずつ検査され、すべてをまとめて検査することはありません。そのため、Release ごとに並べて保持されたカタログのバリアントは、それぞれを読む Release の条件で検査されます。この場合、応答にはパスごとに 1 エントリを持つ passes も含まれます。各エントリには、そのパスを実行した Releases をそれぞれワークスペースルートからの相対で示す releases(同じディレクトリを読む Releases は 1 つのエントリを共有します)、読んだディレクトリを files と同じパス表記で示す catalogDirs(ディレクトリを読まない Release では空になり、他を失敗させるのではなく報告されます)、そしてそのパス自身のカウントと files が含まれ、これらが検出結果がどの Release について見つかったかを示します。外側の checked、カウント、files はすべてのパスをまとめて対象とするため、passes を読まないクライアントでも実行全体を読み取れます。どのパスにも読むディレクトリがない実行は、問題のないカタログとして答えるのではなく拒否されます。
entity とともに prePublish を設定すると、そのエンティティを以前に公開されたバージョンと比較し、提案されたバージョンの引き上げをそれに対して分類します。これはここでレジストリに到達する唯一のモードであり、リクエストが指定したから実行されます。外部に到達する操作を許可するのは、呼び出し元がそれを求めたという事実です。これは entity とともにのみ意味を持つため、エンティティのない prePublish は拒否されます。
aggrega/lint はセッションに何も公開しません。与えられた対象について答えるものであり、その検出結果をエディタの問題一覧に書き込むと、リクエストが対象としなかったファイルについて検証が公開した内容を置き換えてしまいます。どのモードでもディスクには何も書き込まれません。
serve.lint_on_validate は検証のたびに同じルールを実行し、有効にしない限りオフです。 助言を得たいエンティティのあるワークスペースの .aggrega-config.yaml で有効にします。
serve: lint_on_validate: trueこれに対応するフラグはありません。この設定が答える問いはワークスペース自身の内容に関するものであり、その問いを持つのはデーモンを起動した人ではなく、ワークスペースを作成している人だからです。オンにすると、カタログエンティティの検証は慣例の検出結果も aggrega-lint ソースの下に公開します。オフ(デフォルト)では、検証は正しさのレイヤーのみを報告し、慣例の検出結果は届きません。エディタセッションは、そのレイヤーを求めるまで、エンティティが公開可能かどうかについて何も示しません。
キーの値にかかわらず、そのレイヤーでは 3 つのことが成り立ちます。ローカルの内容を読むモードのみが実行されるため、レジストリは参照されず、何も取得されず、何も書き込まれません。公開前の比較には prePublish を付けて aggrega/lint を送ることで到達し、検証によって到達することはありません。編集のたびに実行される検査こそ、レジストリに到達してはならない場所だからです。ルールはディスク上のファイルではなくリクエストが運んだバッファに対して評価されるため、修正した名前は保存前に報告されなくなります。そして検出結果は助言です。検出結果が出たドキュメントも検証に通り、その Release も解決とレンダリングが行われます。したがってこれはレイヤーを追加するものであり、拒否を追加することはありません。
このキーが制御するのはそのレイヤーだけです。aggrega/lint はどちらの値でも求められたことに答えます。それを送る呼び出し元は、名前を指定して検査を求めているからです。
検査されるのはカタログに公開される種類のみです。慣例はそれを対象としているからです。カタログの内容ではないドキュメント(Aggregate や Release など)は対象外であり、Aggrega のドキュメントではない YAML も同様です。これにより、作成者が大半の時間を費やすドキュメントについて、セッションは静かに保たれます。
報告されるパスの表記
デーモンが特定したドキュメントを応答が示す場合、そのパスの表記は 1 つのルールで決まります。ドキュメントがワークスペースルート内にあればルートからの相対パス、そうでなければ絶対パスです。 これは、エンティティ識別子の file、エンティティ定義の file、lint 応答の各グループのキーとなる file に適用されます。どちらの表記も開くことができるパスであり(前者は指定したルートを基準に、後者はそのまま)、ドキュメントの場所を理由に空のままにされることはありません。
ルールの後半は、設定されたカタログディレクトリのために必要です。ワークスペースはマシン上の任意の場所にあるカタログディレクトリを指すことができ、そこにあるドキュメントもルート配下のドキュメントと同じく実在するものです。それを示すのは絶対パスであり、これはターミナルで aggrega lint や停止を伴う診断がそのファイルに対して出力するのと同じ表記です。そのため、どの経路で尋ねても 1 つのファイルには 1 つの名前が付きます。ルールより上へ遡るパスが渡されることはありません。そのようなパスは、どこから読むかによって異なるファイルを指してしまうためです。
どちらの表記が渡されたかは値から判別できます。プラットフォームが絶対パスとして読むものはすべて後者の形式で、それ以外はワークスペースルートからの相対パスです。ファイルを開くために判定する必要はありません(相対パスをルートに結合して開く方法も、絶対パスをそのまま開く方法も機能します)が、ワークスペースドキュメントごとにグループ化するクライアントは、問い合わせることなく両者を区別できます。
このルールが及ばないもの。 送信するパスは、そのリクエスト自身の契約に従います。契約は上記の各リクエストとともに記載されており、通常はより厳格です。送信先は、ワークスペースルートからの相対パスであり、リンクを含めてルート内に解決されるものでない限り拒否されます。aggrega/publishDiagnostics 通知は、ルートの内外を問わず常に file を絶対パスで伝えます。この値はワークスペース内の座標ではなく、開いている自分のドキュメントと照合するための識別子であり、エディタはそれをファイルシステムのパスとして解決するためです。aggrega/releaseCandidates と aggrega/activeRelease は、上記の各項目に記載のとおり、すべての Release とロックファイルを絶対パスで示します。また aggrega/irGraph は、コンパイル済みグラフをコンパイラが記録したとおりに伝え(作成者が機密と宣言した値のみを除きます)、その中に記録されたパスはコンパイラが記録したもので、グラフ自身の契約が定める形式に従います。このプロトコルが組み立てたものではありません。
送信するパラメータが受け付ける表記
パラメータが受け付ける表記を決めるのは、どのメソッドがそれを運ぶかではなく、パスが何を示すかです。 各リクエストが受け取るパラメータの契約は上記の各項目に記載されています。以下では両者の対比と、それがメソッドごとに覚えなければならない不整合ではなく対比である理由を説明します。
すでに保持しているドキュメントを示すパラメータは、3 通りの表記を使えます。ワークスペースルートからの相対パス、絶対パス、または言語サーバーのクライアントが開いているドキュメントに対して送信する file:// アドレスです。 これは aggrega/validate、aggrega/diagnostics、aggrega/invalidate、aggrega/hover、aggrega/completion、aggrega/resolve、aggrega/findReferences、aggrega/findImplementations、aggrega/insertionPoint、aggrega/connectionAtPosition の file または uri です。3 つはいずれも 1 つのドキュメントを示し、同じように応答されます。いずれも何かが読み取る前に、リクエストの境界で 1 つの正規表記に変換されるためです。そのため、パスで検証したドキュメントはアドレスでも見つかり、その逆も同様で、どの表記を送っても応答は変わりません。アドレスは、オーソリティが空または localhost の場合、パーセントエスケープをデコードしたうえで、それが示すパスとして読まれます。別のマシンを示すアドレスは、そのようにドキュメントを開くシステムではそのマシンのネットワーク共有として読まれ、それ以外の環境ではデーモンが開けるものを何も示しません。クエリ、フラグメント、認証情報、ポートを含むアドレスも、デーモンが開けるものを何も示しません。大文字小文字を問わず file:// で始まらない値はアドレスとして読まれることはなく、file-not-validated による拒否は、どの表記であっても送信された値をそのまま示します。このうち aggrega/insertionPoint と aggrega/connectionAtPosition の 2 つは、コピーを保持していない場合にドキュメントをディスクから読み取るもので、ワークスペース内のドキュメントに対してのみ応答します。ルート外のドキュメント(記述そのものが外にある場合、またはファイルや途中のディレクトリへのリンクを通じて外へ出る場合)は、3 つのどの表記で示しても拒否され、ルート内のドキュメントは 3 つすべてで応答されます。残りの 8 つは、示されたパスのディスクから何も読み取りません(aggrega/validate はドキュメントのバイトを content から受け取り、その他は検証済みの内容から応答します)。そのため、ワークスペースの内外を問わず、保持している場所にあるドキュメントに応答し、示されたリンクをたどってファイルを読むこともありません。ワークスペースの外から選択したドキュメントを示すパラメータも、同じ理由で同じ扱いです。aggrega/import の source は、その項目に記載のとおり、実際にある場所から読み取られます。どちらも種類としてワークスペース境界の例外であり(クライアントが開いているドキュメントと、人が選んだファイル)、それぞれが例外である理由は The workspace boundary で説明しています。
デーモンがワークスペース内のドキュメントを特定するためのパラメータは、ワークスペース相対パスのみを受け付けます。 覚えておくべきは release です(aggrega/irGraph にあり、他に現れる箇所でも同じ契約に従います)。絶対値は invalid-params エラーで拒否され、そのエラーは契約を述べたうえで具体的な誤りを示します。ワークスペース内に書き込むリクエストも、それぞれの項目に記載のとおり、送信先を同じ契約に従わせます。そのようなパスはすべて、読み取りか書き込みかにかかわらず 1 つのルールで、行き着く先によって判定されます(内側の定義は The workspace boundary に記載)。外へ出るパスはそのリクエスト自身のエラーで拒否され、送信された値がそのまま引用され、何も読み書きされません。外部のファイルへのリンクも途中のディレクトリへのリンクも同様で、外へ出るリンク付きディレクトリの下にまだ作られていないパスも、書き込まれたり外部で探されて存在しないと報告されたりするのではなく、リンクを理由に拒否されます。これは、リクエストがデーモンに読み取らせるすべてのパス(あらゆる箇所の release、aggrega/lint の entity、公開リクエストの entity、plugin、file、from)に適用されるため、ワークスペース自身の一覧が除外しているファイルをリクエストがリンク経由で読むことはできません。また、すべての送信先にも適用されます。生成、インポート、ビルドが書き込むディレクトリ、aggrega/pin がロックを横に書き込むエンティティ、aggrega/pluginSync が読み取って書き換えるエンティティファイルとモジュール、aggrega/editDocument が編集するドキュメントです。ワークスペース設定が指定する Release を示す release は唯一の例外で、aggrega/irGraph の項目に記載のとおりです。
両者が異なるのは、起こりうる誤りが異なるためです。 すでに保持しているドキュメントを示すパラメータに残る問いは、どのドキュメントかという 1 つだけです。そのため表記を正規のものに変換しても何も失われず、どの表記を受け付けても損はありません。ワークスペースの中からドキュメントを選ぶパラメータは、そうはいきません。クライアントが使っていそうなパスライブラリでは、絶対値をルートに結合するとエラーではなくその絶対値がそのまま得られます。そのため値を黙って修正すると、デーモンはワークスペースが保持したことのないパスを読み取り、それに対する結果を報告することになり、存在しないファイルについて知らされることになります。修正ではなく拒否で応答するのは、そのような値を修正するデーモンでは、それを送るすべてのクライアントに契約は任意だと思い込ませてしまうためです。
エンティティの指定方法
レスポンスが名指しするエンティティは、すべて同じ方法でアドレス指定されます。kind、name、file の 3 つです。表示したい情報があれば、この 3 つをキーにして aggrega/catalogIndex と結合してください。エンティティの記述的な情報一式(apiVersion、description、labels)を持つのはこのサーフェスです。そのため、エンティティを名指しするだけでよいレスポンスは 3 つのアドレスキーを報告し、記述は 1 か所に任せます。aggrega/entityDefinition のような名前による検索は、その回答自体が扱う少数の記述フィールドを繰り返しますが、情報一式が必要な場合に結合する先は引き続きインデックスです。
レスポンスが複数の場所からエンティティを名指しできる場合、各アイデンティティはこの 3 つのキーに加えて origin を持ちます。カタログインデックスと aggrega/attachCandidates はいずれもこれに該当します。エンティティがワークスペースのドキュメントと、設定されたカタログディレクトリの両方から得られるためです。1 か所のみを参照するレスポンスは 3 つのキーだけを報告し、origin は含みません。取りうる値が 1 つしかないキーは何の情報ももたらさないからです。そのようなレスポンスが名指しするエンティティはすべてワークスペースのドキュメントであり、その file は開くことのできるワークスペース相対パスです。したがって、どこでも必須とするのではなく、存在する場合に origin を読んでください。いずれの場合も、結合に使うのは 3 つのキーです。なお、この点は aggrega/catalogIndex にも当てはまります。
origin は、エンティティを一覧するレスポンス、つまり母集団を区別することが読み手の課題となるレスポンスに属します。aggrega/entityDefinition のような名前による回答はこれを持ちません。名前が解決された 1 つのエンティティを名指しするため、区別すべき母集団がないからです。その file が空になる場合については、上記の該当項目が説明しています。その空であることを、一覧を説明する下記の origin の値を通して解釈しないでください。
origin は、デーモンがエンティティをどこから読み取ったかを示し、これによって file を解釈できるようになります。
workspace— ワークスペースルート配下の Aggrega ドキュメントです。fileはそのルートからの相対パスで、クライアントが開くことのできるパスです。catalog— 設定されたカタログディレクトリから解決されたエンティティです。この一覧ではfileは空であり、nameがアドレスのすべてです。空なのは、一覧がカタログ検索で列挙されたもの、つまりドキュメントではなく識別情報を報告するため、エントリに報告すべきパスがないからです。置かれた場所を理由にパスが伏せられたわけではありません。ドキュメントが必要な場合は、同じ名前でaggrega/entityDefinitionを要求してください。このリクエストはエンティティを解決し、そのfileを上記の規則に従って報告します。そのため、ワークスペースルート外のカタログディレクトリはそこで絶対パスによって示されます。いずれにせよ、nameは Aggregate、Recipe、カタログ検索のすべてが使う座標です。
file だけを調べるのではなく、2 つを合わせて読んでください。空の file だけでは、エンティティにワークスペースパスがないのか、単に報告されなかったのかを判別できません。origin がそれに直接答えます。
Feature が両方の経路から到達可能な場合(ワークスペースルート自体が設定されたカタログディレクトリの 1 つである場合で、よくある構成です)、その Feature はワークスペースのドキュメントとして 1 回だけ報告されます。ファイルを開くことができるのはそのコピーだからです。
attach-candidate レスポンスからわかること
aggrega/attachCandidates が答えるのは、このラベルセットがどの Features を受け入れるか、という 1 つの問いだけです。どのラベルセットを指すかを示す方法は 3 通りあります。座標はちょうど 1 つだけ送ってください。2 つ送った場合や 1 つも送らなかった場合は、順位付けされるのではなく拒否されます。
{node} はワークスペースのドキュメントを指定します。その metadata.name で指定し、ほかには何も必要ありません。マッチはそのドキュメントが metadata.labels で宣言するラベルに対して評価され、レスポンスは labelSource: "declared" を報告します。
{graphNode, release} はコンパイル済みグラフ上のノードを指定します。 graphNode はグラフがそのノードをキーとして登録する ID で、aggrega/irGraph から読み取るものと同じ ID です。sub-aggregate が提供したノードが持つ修飾形式も含みます。release はワークスペースルートからの相対パスで、グラフを構築する Release を指定します。aggrega/irGraph が受け取るのと同じ値です。マッチはノードの確定済みラベルに対して評価され、レスポンスは labelSource: "resolved" を報告します。
{labels} はラベルセットそのものを運び、何も指定しません。 これはほかの 2 つの根底にある形です。マッチはラベルセットと提供されている Features の関数なので、すでにラベルセットを保持しているクライアントには、名前を指定する必要も待つ必要もありません。ラベルのペアを JSON オブジェクトとして送ってください。レスポンスは labelSource: "supplied" と空の node を報告します。このリクエストは何も指定していないためです。空のオブジェクトは座標であり、ラベルを持たないノードについて問い合わせます。一方、キーを完全に省略した場合や null を送った場合は何も指定しておらず、拒否されます。
2 つの名前の座標が分かれているのは、識別子の空間が重なっているためです。 グラフのノード ID とドキュメントの metadata.name は、異なるものを指しながら同じ文字列になることがあります。そのため、両方を運ぶ 1 つのパラメーターは曖昧になり、どちらの空間を意図したかを推測するデーモンは、ときに誤った対象について自信を持って答えてしまいます。どの問いをしているかを明示することで、曖昧さがなくなります。
labelSource は答えがどこまで及ぶかを示し、3 つの値は互いに置き換えられません。 declared は 1 つのドキュメントが自身について述べている内容に対するマッチで、ソースを読むことで見える範囲です。resolved はノードが最終的に持つラベルに対するマッチで、ビルドが適用可能性を評価する対象です。そのため、resolved の答えはビルドが何を決定するかについての言明ですが、declared の答えはそうではありません。supplied は、デーモンがラベルをまったく読まず、送られたものに対してマッチしたことを示します。その答えの確かさは、ラベルセットの出所に完全に依存します。
だからこそ、グラフを保持しているクライアントは名前ではなく {labels} を送るべきです。 ノードの確定済みラベルは、そのノードが解決される component type のラベルであり、たまたま同じ ID を持つドキュメントのラベルではありません。さらに label-transform アタッチメントがそれらを追加、変更、削除することがあります。そのため、ノードの適用可能性を決めるラベルは、どれか 1 つのドキュメントが宣言するラベルと一致するとは限りません。グラフを描画するクライアントは、そのセットをすでに aggrega/irGraph から得ています。それを送り返すと、グラフを再構築することなく、{graphNode, release} 座標が返すのと同じ答えが得られます。デーモン自身が報告したセット(ノードのものは aggrega/irGraph から、エンティティのものは aggrega/catalogIndex から)を送り返せば、ノードのラベルについての認識がデーモンの認識からずれることはありません。そのセットはデーモン自身の答えから一度も離れていないためです。自分でセットを組み立てた場合は仮定の問いをしていることになり、それには正直に答えが返されますが、ワークスペースが保持するいずれかのノードについての言明ではありません。
候補はワークスペースとカタログから得られます。 Features を自身のツリーではなくカタログに置いているワークスペースにはローカルの Feature がまったくなく、その候補はすべて origin: "catalog" になります。グラフノードの場合、どちらもそのノードの Release の観点で読み取られます。 カタログの Features は、ワークスペース設定がその Release に与えるカタログディレクトリが宣言するものであり、ワークスペース自身のドキュメントは、ほかの Releases だけが読むカタログディレクトリ配下のものを除いて提供されます。したがって、Release ごとに Feature のバリアントを持つワークスペースは、各 Release のグラフにそれ自身のバリアントを提供し、ほかのものは決して提供しません。一方、カタログの横に、どのカタログディレクトリにも属さずに書かれた Feature は、すべての Release に提供されます。{node} と {labels} は Release を指定しないため、すべてのワークスペースドキュメントとワークスペース自身の catalog_dirs を利用します。適用可能性をまったく宣言していない Feature はすべてのノードの候補になります。宣言がないことは何の要件も述べていないためです。一方、宣言を読み取れない Feature はどのノードの候補にもなりません。読み取れないセレクターを満たされたものとして扱うと、タイプミスによって提供対象が広がってしまうためです。
解決できない名前は空のリストではなくエラーになります。 この 2 つの答えは意味が異なります。空の candidates 配列は、このノードにはアタッチできるものが何もないことを示します。打ち間違えた名前をそのように報告すると、タイプミスが確定した答えとして示されてしまいます。拒否は検索した空間を示すので、ワークスペースのドキュメントを探すべきか、グラフノードを探すべきかがわかります。{labels} にはこのような危険はありません。打ち間違える名前がないためです。そのため、何も受け入れないラベルセットは空の配列を持つ成功レスポンスとして返されます。ただし、デーモンが読み取れないリクエストは、マッチングが実行される前に引き続き拒否されます。
グラフノードの座標にはロックファイルが必要ですが、ほかの 2 つには不要です。 グラフの構築とは Release が到達するものを解決することなので、ロックファイルが生成されていない場合、その経路はロックファイル不在のエラーで拒否し、実行すべきコマンドを示します。これは aggrega/irGraph が持つのと同じ前提条件で、理由も同じです。ワークスペースのドキュメントの指定はグラフを構築せず、ラベルセットの提供は何も構築しないため、どちらもまだ誰も準備していないワークスペースで答えます。
報告するだけで、作成は一切しません。 このメソッドは何も変更せず、何も書き込まず、アタッチメントも作成しません。編集の組み立てと適用はエディターの役割であり、バッファーと元に戻す履歴はエディター側にあります。
何を解決するかは座標によって異なり、3 つは同じではありません。 {node} は何も解決せず、レジストリにもネットワークにも到達しません。候補はワークスペースとカタログディレクトリから得られ、どちらもすでにディスク上にあります。{labels} はさらに解決するものが少なく、何も検索しません。検索するものがないためです。{graphNode, release} は Release のグラフを構築するため、aggrega/irGraph と同じ方法でその Release の依存関係のクロージャを解決します。まずローカルのカタログディレクトリとアーティファクトキャッシュから、そしてそのどちらにもないエンティティについては設定されたレジストリから解決します。エンティティがすべてローカルにあるワークスペースでは、3 つともオフラインで答えます。さらに外部を探しに行けるのはグラフノードの座標だけです。
接続について問い合わせる
component が引く接続は、それ自体のアタッチメントを持つことができ、そのソケットが消費側の Component 上で宣言するスロットを埋めます。たとえば、接続の先にあるものに対して component が提示する認証情報です。そこに何を置けるかを問い合わせるには、{graphNode, release} と並べて connection を送ります。socket は接続が配線されている依存ソケット、alias はそのソケット内で接続が持つ名前で、どちらも作成者が書いたとおりに指定します。接続はコンパイル済みのグラフ上にしか存在しないため、node や labels と並べた connection は拒否されます。ソケットまたはエイリアスを指定しない接続や、ノードが引いていない接続も同様に拒否されます。
応答は、グラフノードに対する応答に接続のスロットを加えたものです。 candidates の意味は変わらず、ノード自体にアタッチできる Features を表します。これに slots が加わり、ソケットが宣言するスロットごとに 1 つのエントリが、Component が宣言する順に並びます。
slot— そのスロットを埋めるアタッチメントが、接続のfeatures内で記述される名前です。selector、required、inject、sensitive、description— Component がソケット上で宣言したとおりのスロットで、何も宣言していない箇所は空または false になります。selectorは候補を絞り込んだ制約であるため、候補があることも、ないことも、応答だけから説明できます。candidates— この接続上でこのスロットを埋めることができる Features です。ビルドはこのようなアタッチメントに 2 つの規則を課し、両方が適用されます。1 つは Feature が宣言した適用条件をノードの確定済みラベルに対して評価するもので、ノードが持つすべてのアタッチメントに課されます。もう 1 つはスロットのselectorを Feature 自身のラベルに対して評価するものです。したがって、スロットの候補は常にノードの候補の中から、セレクタによって絞り込まれたものになります。セレクタを評価できないラベルを持つ Feature は提示されません。ビルドがそれを受け入れずに拒否するためです。
埋められるスロットがない場合、slots は空のリストになり、noSlotReason がその理由を示します。 空のリストを「一致する Feature がなかった」と受け取らず、理由を読んでください。それは別の応答であり、両者を区別するのが理由です。
feature-created-connection— Feature が自身の依存ブロックから接続を引いています。アタッチメントは component または Release が引く接続上にしか記述されないため、ソケットが何を宣言していても、ここには何も置けません。ad-hoc-socket— ソケットが Component の宣言していないものです。作成者がそれを指定したことは正当ですが、宣言されていないソケットはスロットを宣言しません。no-slot-declared— Component がソケットを宣言していますが、そのソケットにスロットがありません。
スロットが存在する場合は noSlotReason は含まれず、接続を指定しない要求への応答には slots と noSlotReason のどちらも含まれません。そのため、接続を指定しない要求には、どちらのフィールドも含まない応答が返されます。
document は受け付けられますが、ここでは何も変えません。 スロットはソケットのもの、候補は Features のものであり、アタッチメントがどのドキュメントに記述されても同じです。どこに記述されるかは aggrega/attachmentContainer が答えます。aggregate または release 以外の値は引き続き拒否されます。受け付けて無視された値は、送信者には反映された値のように見えてしまうためです。
connection-candidate レスポンスが伝えること
aggrega/connectionCandidates は 2 つの問いに同時に答えますが、完全な答えを持つのはそのうち 1 つだけです。レスポンスを 1 つのフィルタ済みリストとして読むと、もう一方を誤って解釈します。
報告される各ソケットは targets(そのソケットが、自身を満たし得るものについて宣言するラベル制約を、宣言済みラベルが満たすワークスペースローカルの Components)に加え、それらのターゲットの算出元となった selector、ソケットが宣言する required フラグ、および declaration を持ちます。targets は常に配列であり、存在しないのではなく空になるため、何も満たさないソケットも、エンティティが宣言するソケットとして引き続き報告されます。
ターゲット側は完全です。 この集合は、ソケットの宣言済み制約を候補の宣言済みラベルに対して評価することで決まります。これはビルドが行うのと同じ評価なので、提示するものは、ビルド中に同じ制約が受け入れるものと一致します。制約を宣言しないソケットはターゲットを制約せず、すべての Component を報告します。これは空のセレクタに対する制約言語の意味であり、エラーではありません。
ソケット側は開いており、declaration と adHocSocketsAccepted によってそれを見分けます。 Aggregate の作者はそのトポロジーを所有しており、そのコンポーネントのカタログエンティティが一度も宣言していないソケットを配線することもできます。そのため、エンティティが宣言するソケットは役に立つ出発点の集合であり、正当なソケット名の集合ではありません。それらを唯一の選択肢としてではなく、候補として提示してください。宣言済みソケットだけを提示するピッカーは、作者の自由が実際より狭いと伝えてしまいます。
declarationは、対象のエンティティがそのソケットを自身のusesSchemaに列挙している場合はdeclared、列挙していない場合はad-hocです。これらは IR グラフのエッジが持つのと同じ 2 つの値なので、「このソケットはどこから来たのか」という問いには、どこで出会っても 1 つの語彙で答えられます。adHocSocketsAcceptedは、対象エンティティのサーフェスが、自身の宣言に列挙されていないソケットを受け入れるかどうかを報告します。これは常に true ではありません。Component 自身の依存サーフェスは受け入れますが、Feature のアタッチメントサーフェスは受け入れません。アタッチメントは独自のトポロジーを記述するのではなく、アタッチされた Feature が宣言するトポロジーに参加するためです。受け入れないサーフェス上のアドホックソケットは、それを経由する接続がビルドされないため、ターゲットなしで報告されます。
リクエストで socket を指定すると、答えはその 1 つのソケットに限定されます。また、エンティティが宣言していないソケットについて問い合わせる方法はこれだけです。宣言されていないソケットは、列挙できるどの宣言にも現れないためです。省略すると、エンティティが宣言するすべてのソケットが、記述された順に得られます。
報告されるのは宣言済みラベルに対する一致です。 ビルドはソケットの制約を、エッジの向こう端にあるノードの確定済みラベルに対して評価します。それは、label-transform アタッチメントが作用した後の、そのノードが解決されるコンポーネントの型のラベルであり、指定したドキュメントのラベルとは限りません。したがって、ここでの肯定的な答えは、ビルドが何を決定するかの約束ではありません。これは aggrega/attachCandidates が declared ラベルソースの下で持つのと同じ限界です。
報告するだけで、作成はしません。 このメソッドは何も解決せず、レジストリやネットワークにも到達せず、何も書き込みません。エッジを作成することも、テキストを提案することもありません。編集の組み立てと適用はエディタの役割であり、バッファと undo 履歴もそこにあります。
targets 内のエンティティ識別子(kind、name、file)については、エンティティの指定方法で説明するとおり、aggrega/catalogIndex と結合してください。説明用のフィールドはそちらで報告され、意図的にここでは繰り返していません。そのため、このレスポンスには食い違いを生じうる 2 つ目のコピーがありません。ターゲットはワークスペースの Components なので、どれも開くことのできる file を持ち、origin を持つものはありません。このレスポンスは単一の場所に基づいており、結合は 3 つのキーで行います。
attachment-container レスポンスが示すこと
aggrega/attachmentContainer は、上記の候補リクエストと下記の挿入位置の間に位置します。前者はノードに何がアタッチできるかを示し、これはノードのためのアタッチメントがどのコンテナに、どのドキュメント内で属するかを示し、次のものはテキストがそのドキュメントのバイト列のどこに入るかを示します。
コンテナは自分で組み立てず、問い合わせてください。 ノードの id とそれを囲むサブシステムのパスはどちらも各部分をドットで区切って書かれ、ドットは作成者が入力する名前の中でも有効な文字です。そのため、ドキュメントの外からは構造上のドットと名前の中のドットを区別する方法がありません。パスを自分で組み立てたクライアントは、正しく見えるものの誰も書いていないキーを指すパスを生成し、それに続く編集は拒否されるのではなく、そのキーを作成してしまいます。両方のパスを組み立てたのはコンパイラなので、それを分解するのもコンパイラです。
ノード id には、それを囲むサブシステムの痕跡がまったく含まれません。 subsystems.billing.subsystems.payments の中に作成されたコンポーネントは、トップレベルのコンポーネントとまったく同じようにグラフ上で ledger というキーを持ちます。そのため、どれほど注意深く分割しても、クライアントが手がかりにできるものは id の中にありません。
回答は 3 つのフィールドです。
nodeは回答の対象となるノードを繰り返します。これにより、複数のリクエストを未処理のまま抱えるクライアントも、独自に順序を保持することなく各回答をその問いと対応付けられます。fileはノードが作成されたドキュメントで、ワークスペース相対です。これは既知の情報ではなく回答の一部です。インポートされたモジュールが提供したノードは、そのモジュール自身のドキュメント内で、モジュールが付けた名前で作成されているため、ファイルとコンテナの最後のセグメントの両方が、リクエストで指定したものとは異なります。containerは、そのドキュメントのルートからの構造パスで、セグメントのリストとして表されます(["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"])。囲むサブシステムの各階層は再びsubsystemsキーの下に置かれ、これはドキュメントでの書き方と同じです。作成者がトップレベルに書いたコンポーネントは代わりに["spec", "components", "checkout", "features"]を示します。そのようなコンポーネントがコンパイルされるスコープは、どのファイルにも含まれないためです。
これはセグメントのリストであり、決して連結された文字列ではありません。それがこの形の要点です。連結されたパスは受け取った側で再び分割しなければならず、上記の曖昧さが 1 回後の呼び出しで再発します。リストはそのまま aggrega/insertionPoint の container として渡してください。
構造を読み取り、意味は決して読み取りません。 回答は、ノードが作成されたドキュメント、ノードが置かれたスコープ、作成者が入力した名前から導かれます。コンポーネントの名前、持つ型、ラベルの内容からは何も読み取りません。
報告するだけで、書き込みは決して行いません。 このメソッドは何も変更せず、どのドキュメントにも何も書き込みません。アタッチメントを作成せず、テキストを組み立てず、編集を適用しません。また、何がアタッチできるかは判断しません。それは aggrega/attachCandidates の役割です。
グラフに存在しないノードを指定したリクエストは、回答されずに拒否されます。 ノード id はグラフ自身のキーです。aggrega/irGraph が返すグラフから読み取ってください。インポートされたモジュールが提供したノードは修飾された id を持ちます。グラフがドキュメントを記録していないノードも拒否されます。アタッチメントの所属先はドキュメントに関する事実であるため、ドキュメントを持たないノードには空の回答ではなく、回答そのものがありません。
ロックファイルが必要です。理由は aggrega/irGraph と同じです。コンテナを示すには Release のグラフを構築する必要があり、何も保証しないバイト列から構築したグラフは、検証済みのグラフとまったく同じように報告されてしまいます。
接続上のアタッチメント
{graphNode, release} と並べて connection(その socket、alias、document)を送ると、回答はノードのものではなく、その接続自身のエントリ上の features コンテナを示します。ここでは document が必須です。Aggregate が引いた接続上のアタッチメントは、どちらのドキュメントにも置けるためです。開発者は Aggregate 内の接続のエントリに、オペレーターは Release 内のその接続のエッジ単位のエントリに書きます。
aggregateは、ノードが作成されたドキュメント内の接続のエントリを示します。トップレベルのコンポーネントでは["spec", "components", "gateway", "uses", "models", "gpt", "features"]となり、囲むサブシステムがあれば上記と同様に階層ごとに記述されます。Release が引いた接続は Aggregate にエントリを持たないため、こちらでは拒否されます。releaseは、ノードに対する Release 自身のエントリの下にあるエッジ単位のエントリを示します(["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"])。Release がそのエッジ単位のエントリをまだ書いているかどうかは問いません。書いていない場合、aggrega/insertionPointがまだ書くべきキーをmissingContainerKeysで報告します。このときfileは Release のドキュメントです。ノードに対するエントリをまったく書いていない Release は拒否されます。ノードをどこに配置するかはオペレーターが書くものであり、回答はそれを決めません。
Feature が引いた接続は、上記の feature-created-connection が示す理由により、どちらのドキュメントでも拒否されます。ノード、ソケット、エイリアスは書かれたとおりに厳密に照合され、ノードが引いていない接続はパスで回答されずに拒否されます。上記のその他の性質はすべてそのまま成り立ちます。回答はセグメントのリストであり、構造を読み取り意味は決して読み取らず、何も書き込みません。
connection-at-position レスポンスが示すもの
aggrega/connectionAtPosition は、上記の 2 つの接続リクエストの前段にあたるステップで、グラフ上のノードではなくドキュメント内の位置(たとえば接続のエントリ上のカーソル)を持つクライアント向けのものです。そこにどの接続が書かれているかを、それらのリクエストが受け取る座標で答え、そこで終わります。
回答は 2 つの半分のどちらか一方であり、両方になることはありません。
graphNodeとconnection— その接続を引くコンポーネントを持つノードを、コンパイル済みグラフがキーとする id で示し、接続をそのsocketとaliasで示します。documentは位置が読み取られたドキュメントを示し、Aggregate またはそれがインポートするモジュールならaggregate、Release ならreleaseです。接続のソケットが宣言するスロットを得るにはgraphNode、同じrelease、connectionをaggrega/attachCandidatesに渡し、その接続へのアタッチメントの置き場所を得るにはaggrega/attachmentContainerに渡します。そこで示されるコンテナは、位置が含まれていたエントリそのものの内側にあります。noConnectionReason— 接続が報告されない理由です。この集合は閉じています。no-connection-entry— 位置が、アタッチメントを書くどのエントリ上にもありません。ターゲットのリストとして書かれた接続(db: [store])や、Feature 自身の依存ブロックが引く接続にはそのようなエントリがないため、それらの上の位置もこれを返します。feature-created-connection— 位置が、Feature が引いた接続に対する Release のエントリ上にあります。このエントリは、上記のスロットの回答が示す理由によりアタッチメントを持ちません。Release は、Feature の依存ブロックが、それを利用する Component も宣言しているソケットを通じて接続を引く場合に、そのようなエントリを書きます。このエントリは、何も設定しない場合でも、接続のエッジごとのinfraを設定する場合でもビルドされます。unknown-connection— 位置が、コンパイル済みグラフが持たない接続に対して Release が書いたエントリ上にあります。ビルドが通る Release でもこれを含むことがあります。たとえば、何も引いていないエイリアスの下にある何も設定しないエントリ(targetもinfraもfeaturesもない)や、active:トグルで無効化されたコンポーネントのエントリです。後者の接続はそのコンポーネントとともにビルドから外れます。
対象となるエントリ。 Aggregate では、コンポーネントが引くすべての接続が対象で、そのコンポーネントが記述されたドキュメント内の、接続のエイリアスの下のエントリにあります。インポートされたモジュールが提供するコンポーネントの場合は、そのモジュール自身のドキュメントです。Release では、Release が書くすべてのエッジごとのエントリが対象で、そのエントリが自ら接続を引くか、Aggregate が引いた接続を設定するかは問いません。各エントリの位置はコンパイル済みグラフが記録しているものであり、キーが接続であるかどうかがその名前から推測されることはありません。active: トグルで無効化されたコンポーネントはコンパイル済みグラフに含まれないため、Aggregate 内のそのコンポーネント自身のエントリは no-connection-entry を返し、その接続の 1 つに対する Release のエントリは unknown-connection を返します。
エントリ内のどこにある位置も、そのエントリの内側です。 エントリはエイリアスのキーから、その下にインデントされた最後の行までにわたります。そのため、エイリアス上、その target 上、またはその features の内側の位置は、その接続について回答され、エントリが入れ子になる場合は最も内側のエントリが優先されます。ソケット自身のキー上、つまりその下に書かれたエイリアスより上の位置は、ソケットが持つエイリアスが 1 つでも複数でも、どのエントリの内側でもありません。エイリアスのキーの前のインデント部分にある位置も同様です。
どのドキュメントがどれにあたるかは Release から決まります。 Release 自身のファイルは、それが書くエントリについて読み取られます。それ以外のファイルは、グラフがコンポーネントの記述場所として記録しているエントリについて読み取られます。Release のグラフが何も読み取らないドキュメントは、すべての位置で no-connection-entry を返します。
報告するだけで、書き込むことはありません。 また、ドキュメントの読み取り方は aggrega/insertionPoint と同じです。まずセッションのコピーから、なければディスクから、ワークスペース内で読み取り、ワークスペース外のドキュメント、読み取れないドキュメント、整形式の YAML でないドキュメントに対しては同じ拒否を返します。aggrega/attachmentContainer と同じ理由でロックファイルを必要とし、何もレンダリングせずにグラフをビルドします。
insertion-point レスポンスからわかること
aggrega/insertionPoint は、上記の 2 つの候補リクエストに対応するものです。それらは何がアタッチまたは接続できるかを示し、こちらはそのためのテキストが特定の 1 つのドキュメントのどこに入るかを示します。答えを返し、そこで終わります。
コンテナを指定するのは呼び出し側で、デーモンはその位置を特定します。 container はドキュメントのルートからの構造パス(["spec", "components", "web", "features"])であり、この種類のエントリがこの種類のドキュメントのどこに入るかについての呼び出し側の表明です。デーモンは、エンティティの名前、持つ型、意味するように見える内容からそのパスを導出しません。作成者が書いたバイトを読み、このドキュメントにパスのどのセグメントが既に存在するか、そのエントリが置かれている列、最も内側のブロックが達する最後の行を報告します。したがって、どのキーかを知るのは呼び出し側の役割のままで、そのキーのエントリがこのファイルのどこに入るかはここから得られます。
コンパイル済みグラフのノードへの Feature のアタッチメントについては、呼び出し側がそのキーを自分で知っている必要はありません。aggrega/attachmentContainer にドキュメントとコンテナを問い合わせ、両方をそのままここに渡します。
答えは幅ゼロの位置と、その周囲に書く必要があるものです。 file はワークスペース相対のドキュメントです。container は問い合わせたパスを繰り返すため、複数のリクエストを未完了のまま抱えるクライアントは、独自に順序を保持しなくても各回答を質問と対応付けられます。position は置換ではなく挿入を表します。ドキュメントに既にあるものは上書きもずれもしません。
precededByLineBreak:書くテキストを改行で始めます。位置は新しいエントリが続く行の末尾にあり、ファイルが改行で終わるかどうかにかかわらず範囲内で、既に書かれたバイトを乱しません。これが false になるのは、後に続けるものを何も持たないドキュメントの場合だけで、その場合はファイルの先頭から書きます。missingContainerKeys:このドキュメントがまだ持っていないコンテナパスのセグメントで、最も外側が先です。エントリを最も内側のキーの中に入れる前に、それぞれを独立したキーとして書く必要があります。パス全体が既に存在する場合は空です。entryIndent:エントリ自身の最初の行が始まる列で、行頭からのスペース数で数えます。indentStep:ネストのレベルごとにさらにどれだけインデントするか。indentStepMeasured:そのステップがこのドキュメント自身のネストから測定されたかどうか。false の場合、ドキュメントには測定できるネストがなく、ステップはフォールバック値です。そのため、独自の値を使いたいクライアントは自由にそうできるとわかります。entryShape:コンテナが既に保持しているものから読み取ったmappingまたはsequenceで、コンテナがまだ存在しないか何も保持していない場合はunknownです。unknownは失敗ではありません。ドキュメントがエントリの形をまだ示していないので、その選択は呼び出し側に委ねられます。
適用方法。 precededByLineBreak が設定されていれば改行を書きます。次に missingContainerKeys のエントリごとに 1 行ずつ、最も外側から順に、キーの後にコロンを続けて書きます。最初の行は entryIndent から indentStep に欠けているキーの数を掛けたものを引いた位置にインデントし、続く各行はさらに indentStep ずつ深くします。その後、エントリ自体を entryIndent の位置にインデントして書きます。missingContainerKeys が空の場合、書くのはエントリの行だけです。
コンテナが存在すると予想している場合でも missingContainerKeys を読んでください。前に置く必要があるキーなしで位置を適用すると、パースできなくなったドキュメントが生じます。これは、この答えを読み飛ばしてはならない唯一の失敗です。
position は診断のものとは異なり、ゼロから数えます。 line と character はどちらも 0 始まりで、このプロトコルが再利用する LSP 形式の位置の値に合わせています。一方、診断エントリの line と column は、What a diagnostic entry carries で説明するとおり 1 始まりです。一方の面から他方へ値を渡すクライアントは、両者の間で変換します。
positionEncoding は character を測る単位を示し、ハンドシェイクで取り決めたエンコーディングです。暗黙にせず回答で報告するのは、呼び出し側が単位を推測しなければならない位置は適用できない位置だからです。ある方法で測ったオフセットを別の方法で測るバッファに適用すると、ASCII 外の最初の文字でドキュメントが壊れます。
エントリを置ける場所を指していないリクエストは、回答されずに拒否されます。 以下はいずれもワークスペースではなくリクエストの状態なので、標準の invalid-params コードで返され、file または container が変わるまで再試行しても何も変わりません。
- ドキュメントが指定されていない、ワークスペース内にない、読み取れなかった、または整形式の YAML でない。構造のないドキュメントには報告する位置がありません。
- コンテナパスが何も指していない。セグメントを持たないか、セグメントのいずれかが空です。
- パスが、ドキュメントでスカラーとして保持されている値を通っている。スカラーの中には何も追加できず、置き換えれば挿入ではなく書き換えになります。
- パスが、作成者がフロースタイルで書いたコレクションに達している。そこへのエントリ追加は行の追加ではなく作成者が既に書いたバイトの書き換えになり、それは位置ではなく編集です。
- パスが、ブロックシーケンスをそのインデックスではないもので指している。シーケンスのエントリは位置で指定されるため、名前はその中の何にも達せず、その名前を持つエントリを作成することもできません。
ディスク上のファイルだけでなく、エディタが保持しているバッファも読みます。 デーモンのパースキャッシュが最初に参照されるため、未保存の内容があればそれに対して位置が報告され、キャッシュに何もなければファイル自体に対して報告されます。
報告するだけで、書き込みは行いません。 このメソッドは何も変更せず、何も解決せず、レジストリやネットワークにアクセスせず、どのドキュメントにも何も書き込みません。エントリのテキストを組み立てることも適用することもしません。編集の組み立てと適用はエディタの役割で、バッファと元に戻す履歴もそこにあります。
ドキュメント編集レスポンスが伝えること
aggrega/editDocument は上記のペアのもう一方です。上記のリクエストはエントリがどこに属するかを示し、その作成と適用は呼び出し側に任せます。このリクエストはエントリを 1 つ作成して適用し、書き込みを行います。どちらも引き続き利用できます。未保存のバッファを保持するクライアントと、ディスク上の内容を編集するクライアントとでは、必要とする側が異なるためです。独自の undo 履歴を持つエディタはテキストを自ら配置し、どこを編集すべきかを知らされるよりファイルを編集してもらうことを望むクライアントはこのリクエストを送ります。
1 回の呼び出しで 1 つの編集を適用し、編集の種類は閉じた集合です。 edit がどれかを指定します。add-component は components コンテナの下に component インスタンスを追加し、attach-feature はノードに Feature をアタッチし、wire-edge はノードの依存ソケットの 1 つの中に接続を配線し、set-value はノードに 1 つの値を設定します。削除、既に書かれたブロックの置き換え、並べ替え、あるいは渡されたバイトをそのまま書き込む編集はありません。したがって、これは名前を狭めただけのファイルライターではなく、4 つ以外の値は解釈されずに拒否されます。拒否には指定できる値の一覧が示されます。
ノードは構造パスとして指定します。上記の 2 つのリクエストが受け取るのとまったく同じです。 node はドキュメントルートからのパンくず(["spec", "components", "web"])であり、エントリが入るコンテナは edit から決まります。add-component の場合、パスは components コンテナそのものを指定します。追加されるエントリがノードそのものだからです。name はエントリを書き込むキーで、インスタンス名、アタッチメントの名前、接続のエイリアス、または値のキーです。value はそのエントリが持つ内容で、その意味は edit から決まります。エントリが要求するエンティティ、接続が指すノード、または値として設定するスカラーのいずれかです。socket は wire-edge の場合に読まれ、それ以外では無視されます。
名前ではなくパスを使うのは、位置特定リクエストがパスを受け取るのと同じ理由です。名前は検索しなければならず、2 つの階層に現れる名前があれば、どちらを意図したかをコンパイラが判断することになります。そのため、編集対象のノードを知っているクライアントはそれを明示し、知らないクライアントは何かを編集する前に答えるべき問いがあることを認識します。
編集が触れないすべてのバイトはそのまま残ります。 ドキュメントは、コンテナとそのブロックが終わる行を特定するためだけにパースされ、エントリは行単位でレンダリングされて挿入されます。コメント、空行、クォートのスタイル、folded および literal スカラー、テンプレート式、末尾改行の形はすべて変更されずに引き継がれ、ネストの幅は押し付けられるのではなくドキュメント自身のインデントから測定されます。そのため、エントリは既に書かれているスタイルで配置されます。同じドキュメントに対する同じリクエストは同じバイトを生成します。そのため、クライアントは 2 回の実行を比較でき、レビューでは 1 つの編集が 1 つの diff として読めます。
結果は手で入力できたはずのドキュメントでなければならず、書き込みはそれを条件とします。 作成されたドキュメントはそれ自身の kind のスキーマに対して検証され、検証に通った場合にのみディスクに書き込まれます。オーサリングスキーマが拒否するものを生成するリクエストは E0275(結果のドキュメントが有効でないため編集は拒否され、何も書き込まれませんでした)として返され、スキーマが受け入れなかったプロパティとその場所が含まれます。ファイルはバイト単位で元のまま残ります。そのため、拒否された編集は一度も試みられなかった編集と区別がつかず、開始時のドキュメントに対して修正したリクエストを再試行できます。ここで規則を改めて述べないのもそのためです。Release ドキュメントに開発者向けの値を持たせようとする要求は、手入力のドキュメントを拒否するのと同じスキーマによって拒否されます。
意味的に許容されるかどうかはここでは判断されません。 依存ソケットがプロデューサーの宣言するものかどうか、Feature の適用条件が満たされているかどうかは、ビルドが行う解決に属し、それぞれ独自の報告があります。そのため、このリクエストが一度も聞いたことのない接続を指定することもでき、Aggregate はそのカタログエンティティが事前宣言していないソケットを記述できます。ソケットを介して何が消費できるかは、引き続きプロデューサーが宣言するものです。それが問いであるときは、Release を指定して aggrega/validate を実行するか、グラフを要求してください。
応答は何が反映されたかと何がディスクに書き込まれたかを示し、この 2 つは別の問いです。 content はどちらの配信方法でも、編集が生成したドキュメントを保持します。written はディスクに書き込まれたファイルを示し、dryRun では空です。container はエントリが配置されたコンテナの構造パスで、そのルールを導き直さずに追加したものの位置を特定できます。createdContainers は、ドキュメントに存在しなかったためにこの編集が書き込んだセグメントを外側から順に示します。パス全体が既に存在する通常の場合は空であり、これを読むことで、既存のブロック内に追加されたエントリと、自身のブロックを新たに作ったエントリを区別できます。file と edit は送信した内容をそのまま返すため、複数のリクエストを未処理のまま抱えるクライアントは各応答をその問いと対応付けられます。written、container、createdContainers は常に配列であり、存在しないのではなく空になります。
dryRun では何も作成されません。 written は空で、content は書き込みを行った場合に生成されたはずのドキュメントを保持し、ファイルには触れません。そのため、エディタは結果を作成者に示して、保存、修正、破棄を選ばせることができます。既定は書き込みです。この操作の成果物は編集されたドキュメントであり、それを生成するインターフェースはそれを提供する責任があるためです。配信について何も指定しないリクエストはファイルを編集します。
書き込みが行うその他すべてのことは、ドライランでも行われます。 作成されたドキュメントはどちらの場合もそれ自身の kind のスキーマに対して検証されるため、書き込みで拒否される編集は dryRun でも同じプロパティを示して拒否されます。つまり、ドライランで得られるエラーは書き込みで得られたはずのエラーと同じです。
要求した内容を持つエントリが既に存在する場合は何も行われません。ドキュメントは変更されずに返され、何も書き込まれません。その名前のエントリが別の内容を持つ場合は、置き換えられずに拒否されます。作成者が書いたものを置き換えることは 4 つの編集のいずれでもないためです。
書き込みの後、デーモンはドキュメントを読み直します。 そのファイルについて保持していた内容は破棄され、ワークスペースレベルのビューはリセットされます。そのため、次の検証、ホバー、補完、グラフのリクエストには、置き換えられたバージョンではなく編集が生成したバイトから応答します。編集自体は保持しているバッファではなくディスク上のファイルを読みます。未保存の内容を先に参照する上記の位置特定リクエストとは異なります。これは意図的なものです。未保存のバッファから書き込むと、エントリを 1 つ適用するという名目で、作成者が保存していない内容をページに書き込むことになります。バッファを保存してから編集してください。
エントリを配置できる場所を指していないリクエストは、応答されずに拒否されます。標準の invalid-params コードが返され、リクエストが変わるまで再試行しても何も変わりません。該当するのは次の場合です。ドキュメントが指定されていない、ワークスペース内にない、読み取れない、整形式の YAML でない、または結果を検証できるスキーマを持つ kind を宣言していない。edit が指定されていない、または 4 つのいずれでもない。node が何も指していない、またはそのセグメントのいずれかが空である。name が指定されていない。wire-edge で socket が指定されていない。set-value でスカラーが入るべき場所にマッピングまたはシーケンスが指定された。ノードパスがスカラー、シーケンス、またはフロースタイルで書かれたコレクションに到達し、行を追加するとページ上の既存のバイトを書き換えることになる。またはノードパスがドキュメント内の何にも到達しない。
どちらの配信方法でも、依存関係の解決、レジストリへのアクセス、ネットワークへのアクセスは一切行いません。
effective-configuration レスポンスが対象とする範囲
aggrega/effectiveConfiguration は 2 つの問いに答えます。このセッションでどの設定が適用されるか、そして各設定をどのレイヤーが決定したかです。これは aggrega config show --origin が出力するのと同じ答えであり、一度だけ計算されて両方の窓口で報告されるため、設定の出どころについて両者が食い違うことはありません。
source は 4 つの形のいずれかです。 設定ファイルの絶対パス(aggrega --config <file> serve として起動したデーモンが読むグローバルファイルも含み、与えられたパスとして示されます)、env: 接頭辞の後に続く環境変数(env:AGGREGA_SIGNING_REQUIRED など)、デーモンを起動したコマンドラインで指定されたグローバルフラグ(フラグとして示され、aggrega --offline serve として起動したデーモンなら --offline など)、またはどのレイヤーも設定していない設定に対する (built-in defaults) です。最初の 3 つは layers にそのまま現れます。デフォルトは現れません。デフォルトは寄与したレイヤーではなく、どのレイヤーも指定しなかった箇所に適用されるものだからです。
設定は、それを設定している最も優先順位の高いレイヤーに帰属します。そのレイヤーがどのような値を書いているかは問いません。 組み込みのデフォルトを書いている設定ファイルや、下位のファイルがすでに設定している値を再記述している設定ファイルも、そのファイルとして示されます。値をその位置に保持しているのはそのファイルだからです。ファイルはキーを持つことで設定を行い(リストの _append コンパニオンも含みます)、環境変数は空でない値でエクスポートされることで設定を行います。パイプラインが所有する設定ファイルが、無視しているキーについて示されることはありません。aggrega config show --origin も同じ規則に従って報告します。
設定スキーマが宣言するすべての設定が報告対象になりますが、それぞれに独自の行があるわけではありません。 リストの追加用 _append コンパニオンは、追加先のリストの行で報告されます。そのため、コンパニオンを通じてのみ寄与するレイヤーはそのリストの行に示され、コンパニオン自体は行を持ちません。リストのエントリ内の設定(レジストリのトラストポリシーやプラグインアタッチメントの入力など)は、そのリストの行に含まれます。
さらに 2 つの制約があり、いずれも答えを見かけより粗いものにします。
- リストやマップの設定は全体として、それを設定している最も優先順位の高いレイヤーに帰属します。エントリ単位の帰属は追跡されないため、2 つのレイヤーから組み立てられたリストは優先順位の高い方のみを報告し、下位のレイヤーが寄与したエントリは上位のレイヤーが書いたものと区別できません。
- 署名要件は、それを最後に言及したレイヤーではなく、最初に有効にしたレイヤーに帰属します。 この設定は、いずれかのレイヤーが有効にすればそれが優先され、以降のレイヤーは無効にできないように合成されます。そのため、最初に有効にしたレイヤーが実効値を決定したレイヤーです。
required: falseを書いているレイヤーは何も有効にしないため、言及しているすべてのレイヤーがfalseを書いている場合、この設定は(built-in defaults)を報告します。
報告されるすべての値は、そのワークスペースが最初に指定された時点での解決結果です。 設定ファイルを編集してもここでの値は変わらず、デーモンを再起動すると変わります。これは意図的なものです。これらの値は、そのワークスペースに関する他のすべてのリクエストが応答される際の設定であり、それによってハンドシェイクがそのワークスペースについて報告したルートや設定レイヤーと比較できるようになります。ユーザーが編集中のファイルと並べて設定を表示するクライアントは、2 つのうちどちらを表示しているかを明示する必要があります。
レイヤーの帰属は、問い合わせた時点で、その時点のファイルに対して算出されます。 そのため、後から編集された設定ファイルによって source が変わる一方で、その横の値は解決された時点のまま残ることがあります。この 2 つは異なる問い(何が有効か、どのレイヤーがそれを決定したか)に答えており、固定されているのは前者のみです。両者を一致させるにはデーモンを再起動してください。
報告のみを行い、書き込みは一切行いません。 このメソッドは設定を変更せず、ファイルを作成せず、レジストリやネットワークから何も解決しません。
単一レイヤーのファイル内容はここでは提供されません。 コマンドラインでは、コメントや書式を保ったまま 1 つのレイヤー自体のバイト列をそのまま出力できますが、このメソッドはバイト列ではなく解決結果を報告します。レイヤーのテキストが必要なクライアントは、layers にあるパスを使って開くことができます。
設定の書き込みが残すもの
aggrega/configInit と aggrega/configCapture はどちらも設定ドキュメントを生成し、どちらもそれを書き込みます。応答はファイルを示します。それを開くのは次の操作であり、書き込みの代わりではありません。明示的に求めない限り、どちらも自分で配置するための内容を渡しません。書き込まれなかったドキュメントを成果物とする機能は、同じ名前をまとった別の機能だからです。
**2 つは影響の及ぶ範囲が異なり、各応答がそれを示します。**結果を表示する前に確認してください。
- **シーディングは、デフォルトでマシン上のすべてのワークスペースで共有される設定に書き込みます。**レジストリとそこで信頼する ID は通常どこで作業しても同じなので、リクエストが
workspace: trueを送らない限り、エントリはそこに入ります。scopeは書き込まれたconfigFileと、それが共有ファイルかどうかを示すmachineWideを持ちます。これはリクエストが求めた内容ではなく書き込みが解決されたファイルから導かれるため、応答がマシン全体の変更をローカルの変更として記述することはありません。 - **フリーズはワークスペースの外には及びません。**書き込み先もオーバーライドも受け取りません。その目的は 1 つのプロジェクトを自己完結させることなので、常にそのプロジェクト自身の
.aggrega-config.yamlに書き込みます。そのため応答はconfigFileとworkspaceRootを持ち、スコープを主張しません。示すべき範囲がないからです。
**シーディングは上書きせずに拒否します。**既に存在する設定ファイルには手を付けず、拒否でそのファイルを示します。シーディングはまだ存在しない設定のためのものであり、委譲先の共有書き込みは設計上マージを行うからです。それでも書き込むには force を送ります。レジストリのエントリは既存の内容にマージされ、他の設定は保持されます。拒否されたリクエストは何も変更しません。
trust は、レジストリが公開するポリシーがどうなったかを、文章ではなく個別の結果として示します。pinned はレジストリがポリシーを公開し、それが採用されたことを意味し、identities がその数を示します。notAdvertised はレジストリに問い合わせたが何も公開されていなかったことを意味し、これは失敗ではありません。シーディングは続行され、reason がエンドポイントの動作を示します。到達できなかったレジストリもこのように報告されます。ポリシーが返らず、シーディングも同様に続行されるためです。さらに、障害そのものがレジストリに一度も到達しなかったことを示す場合、つまり名前が解決されなかった、接続が拒否されたか開けなかった、またはセキュアな接続を確立できなかった場合は、その横に unreachable を持ちます。not-found やエラーステータスで応答したレジストリが unreachable を持つことはありません。そのため、ポリシーを公開していないレジストリと一度も問い合わせられなかったレジストリを区別するには、reason の文言ではなくこのキーを読んでください。baseline は、公開ポリシーが採用されなかったため公式ハブの組み込みベースラインがピン留めされたことを意味し、reason がその理由を示します。エントリはポリシーを持つため、手動でピン留めするものはありません。2 つのキーは別々の問いに答えるので、問い合わせたが何も公開していなかったハブは両方を持ち、オフラインのワークスペースにあるハブ(一度も問い合わせられていない)は baseline のみを持ち、reason がワークスペースがオフラインであることを示します。何も公開していないその他のレジストリは notAdvertised のみを持ち、ポリシーなしでシーディングされ、続く助言は ID を手動でピン留めすることです。オフラインでは応答されず拒否されます。skipped は取得が試みられなかったことを意味します。pinned 以外をエラーとして扱うクライアントは、動作する設定を壊れていると報告することになります。
dryRun では何も作成されません。written は false で、content は書き込みが生成したはずのドキュメントを持ち、その内容の対象ファイルは scope.configFile です。ディレクトリは作成されず、ファイルにも触れないため、エディタはそのテキストを作成者に示し、保存、修正、破棄を任せることができます。
**ドライランが書き込みと異なるのはただ 1 点、書き込まないことだけです。そのため、書き込みが行う拒否はすべてドライランも行います。**ここで重要なのは既存ファイルの拒否です。既に存在する設定ファイルに対する dryRun は、書き込みとまったく同じくそのファイルを示して拒否されます。これにより応答を述語として使えます。ドライランが拒否すれば、書き込みも同じ理由、同じメッセージで拒否したはずです。dryRun と一緒に force を送ると、上書きする書き込みが生成するマージ結果が代わりに返され、やはり何も書き込まれません。どちらの配信方法でも、公開された信頼ポリシーを得るためにレジストリへ問い合わせます。その内容のポリシーは、書き込みがピン留めしたはずのポリシーだからです。
フリーズが報告するのは書き込んだものそのものであり、その説明ではありません。sockets はフリーズされた各プラグインソケットを、そこでフリーズされたアタッチメントとともに列挙します。catalogDirs はカタログディレクトリを持ちます。どちらも常に配列であり、存在しない代わりに空になります。
socketとfieldは同じ文字列ではなく、その違いは見た目だけのものではありません。socketはアタッチメントがバインドされているソケットを示し、fieldはそれらがファイル内で書き込まれたキーです。両者が異なるのは provider ソケットだけで、これは複数形のキーで書き込まれます。そのため、ドキュメント内の行を読み手に示すときはfieldを、ソケット自体を示すときはsocketを使ってください。- **各アタッチメントは
uri、capability、function、roleを持ち、それぞれアタッチメントにある場合にのみ存在します。**これらはアタッチメントの全体を再現するのではなく、アタッチメントを識別します。アタッチメントの任意のアタッチ時入力はファイルにそのままフリーズされ、応答では繰り返されません。ファイルが正式なコピーです。 - **
captured: falseは成功です。**ビルドが設定に関与しないプロジェクトにはフリーズすべきビルドに重要なものがないため、ファイルはそのまま残され、両方のリストが空で返ります。これをエラーとして扱うと、正常なワークスペースを壊れていると報告することになります。
デフォルトでは、出力バイトを決定するものだけをフリーズします。つまり provider バインディングと、ラベルを変換するガバナンスアタッチメントです。判定を行うガバナンスとリンターのゲート、およびインポートソケットは除外されます。これらは環境ごとに異なることを意図しており、フリーズすると 1 つの環境のゲートがすべてのチェックアウトに持ち込まれるからです。allPlugins: true は対象をすべてのプラグインソケットに広げます。対象の判定はソケット単位ではなくアタッチメント単位です。そのため、ラベル変換アタッチメントと判定アタッチメントを 1 つずつ持つガバナンスソケットは、デフォルトでは前者のみを含めます。
すべての値は実効値でフリーズされます。つまりマシンの設定とプロジェクト自身の設定をマージして解決される値です。そのため、現在マシンの設定からのみ得られているバインディングもプロジェクトに書き込まれ、プロジェクトとともに持ち運ばれます。マシン全体のツール設定(レジストリの信頼ポリシーを含む)はビルドに重要ではなく、元の場所に残ります。変更のない設定に対して 2 回フリーズすると同じバイトが書き直されます。そのためクライアントは自由にこれを提供できます。2 回目の呼び出しは、読み手が保持しているドキュメントをまったく同じ状態のまま残します。
プラグインの変更が伝えること
4 つのプラグインリクエストはすべてデフォルトで書き込みを行い、何を書き込むかで分かれます。2 つは設定ファイルを変更し、2 つはワークスペース内にドキュメントを生成します。そのうち 2 つ(追加と生成)は dryRun を受け付け、これはリクエストが行う他のすべてを実行し、何も書き込みません。変更がどこに反映されたかはリクエストから推測するのではなく、回答自体の記述を読んでください。そのうちの 1 つでは、リクエストがスコープについて何も指定しないことが最も広い範囲を意味します。
追加と削除はどちらも scope を持ち、これは書き込みが解決されたファイルから導出されます。 configFile はそのファイルであり、machineWide はそれがこのマシン上のすべてのワークスペースが解決に使うファイルかどうかを示し、workspaceRoot はこのセッションが開かれたワークスペースを示すため、ワークスペーススコープの回答はどのワークスペースであったかを示します。machineWide はリクエストが求めた内容ではなく解決されたファイルから読み取られます。これにより、回答がマシン全体の変更をローカルの変更として記述することが防がれます。
🔴 global も workspace も指定しない cli タイプの追加は、コマンドをマシン全体に登録します。 コマンド拡張はマシン全体のツールであるため、オーバーライドがない場合、このマシン上のすべてのワークスペースが解決に使うグローバル設定ファイルに書き込まれます。そして登録されたコマンドは、このセッションで誰も指定していないプロジェクトを含め、そのマシン上のすべてのプロジェクトにおけるトップレベルの aggrega コマンドになります。provider、governance、linter、importer の追加はその逆です。これらは 1 つのプロジェクトのビルドを形作るため、オーバーライドがない場合はそのプロジェクト自身の .aggrega-config.yaml に書き込まれます。削除も同じタイプについて同じ規則に従います。コマンド拡張をローカルに留めるには workspace: true を、それ以外を共有ファイルに出すには global: true を送信してください。両方を送信すると拒否されます。いずれの場合も回答の scope が正式な記述であり、クライアントは結果に基づいて動作する前にそれを表示すべきです。
追加は反映されたものを示し、3 つのフィールドのうちちょうど 1 つがそれが何の種類であったかを示します。 type はエントリが追加されたタイプをそのまま返し、さらに次のようになります。governance、linter、importer のアタッチメントでは、identity がバージョン固定された素のエンティティ ID を持ちます。provider バインディングでは、uri がプラグインの oci:// アーティファクトアドレスを、現在提供する capability とともに持ちます。cli のインストールでは、reference がコマンドを登録した固定済みの参照を持ちます。したがって呼び出し側は、送信したタイプから再導出するのではなく、回答からどの種類のアタッチメントが反映されたかを読み取ります。削除は scope とともに type と query を返すだけで、それ以外は何も返しません。消えたエントリについてそれ以上報告することはないためです。
追加は written も持ち、dryRun の下では content も持ちます。 written はクライアントが分岐に使うものです。true は、クライアントが開けるディスク上の設定ファイルが存在することを示し、dryRun の下では false となり、代わりに content が書き込みによって生成されたはずの設定ドキュメントを持ちます。両者が同時に意味を持つことはなく、content の対象ファイルは scope.configFile であるため、回答のどこにもそのパスの 2 つ目のコピーはありません。これはここで重要です。global アタッチメントのファイルは、このマシン上のすべてのワークスペースが解決に使うファイルだからです。
公開バージョンのないプラグインは、固定なしでアタッチされるのではなく拒否されます。 追加はクエリを 1 つのプラグインに解決し、その最も高い公開バージョンに固定するため、書き込まれるエントリはバージョンを持ちます。リポジトリが適合するバージョンを公開していないプラグインはその名前を示して拒否され、このワークスペースが信頼する撤回によって取り下げられたバージョンは飛ばされ、その次に低いバージョンが選ばれます。
クエリで指定したバージョンは、取り下げられていても固定され、withdrawn がそのことを示します。 <name>:<version> として書かれた query は、最新版ではなくそのバージョンを固定します(名前のみでバインドされ、バージョンを拒否する provider を除くすべての種類で)。バージョンを指定することが上書き指定にあたります。このワークスペースが信頼する撤回によってそのバージョンが取り下げられていても、そのまま固定され、応答には withdrawn: true が含まれます。これは aggrega plugin add がターミナル上で retraction: 行として示す事実です。withdrawn はそれ以外のすべての応答には含まれないため、その存在がシグナルのすべてです。ただし、それがないことは、そのバージョンが取り下げられていないことを示すものではありません。指定されたバージョンの取り下げマーカーを読み取れなかった場合、withdrawn は含まれず、retraction が unscreened を持ち、その理由を示します。これは、バージョンを指定しない追加が同じ失敗に遭遇した場合と同じです。バージョンを指定しない追加は、代わりに、選んだバージョンについて取り下げチェックが下した結論を retraction で報告します。
アラインメントは何かを変更したかどうかを報告し、それが動作の根拠にすべきフィールドです。 changed は、書き込みと、記録がすでに正しいことを確認したアラインメントとを区別します。変更されなかったファイルはバイト単位で同一のまま残されるため、そのドキュメントを保持しているクライアントは再読み込みの必要がなく、リクエストを 2 回実行すると 2 回目は変更なしと報告されます。entity はファイルを示し、hostFunctions は導出されたセットを持ち、commands はターミナルが出力する行ではなく値としてミラーを持ちます。各エントリは name、任意の description、flags を持ち、各フラグは name と、任意の shorthand、description、type、default を持ちます。書き込みはアトミックであるため、アラインメントの実行中にそのファイルを読むクライアントが不完全なドキュメントを目にすることはありません。
生成は回答のちょうど半分だけを埋め、どちらかは回答自体の dryRun が示します。 デフォルトではエンティティが書き込まれ、notices は生成が実行した書き込みについて述べた内容を持ちます。dryRun の下では何も作成も変更もされません。documents は生成された各エンティティを、その対象の path とその content として持つため、クライアントはそれらを自身のドキュメントモデルに置くことができ、保存前に確認でき、修正や破棄もできます。2 つの半分が両方とも埋まることはないため、どちらの配信が実行されたかは、要求された内容ではなくレスポンスから読み取れます。
プラグインリクエストが書き込む場所は常にそのリクエストが指定したワークスペース内であり、読み取る対象はフィールドごとに決まります。 絶対パスの書き込み先、ルートの外へ上る書き込み先、リンクを通じてルートの外へ出る書き込み先は、解決されるのではなく拒否されます。したがって生成は、何を送信しても、セッションが開かれていないツリーにエンティティを作成することはできません。リクエストが読み取るだけのパスは別の問題であり、すべてに対する 1 つの規則ではなくフィールドごとに判断されます。aggrega/pluginGenCatalog は、モジュールとそのオーバーレイを選択した場所から読み取ります。ビルドしたモジュールはツールチェーンの出力ディレクトリにあり、そこから読むことを拒否すれば、その操作の目的そのものを拒否することになるためです。aggrega/pluginSync は 2 つのパスをワークスペース内から読み取ります。このリクエストはワークスペースがすでに持つファイルに関するものだからです。前述の位置特定リクエストが絶対パスを受け付けるのは、さらに別の理由によります。クライアントがすでに開いているドキュメントを、クライアントが保持しているとおりの表記で指定するためです。
操作に必要なものが欠けているリクエストは、送信すべきフィールドを示して拒否されます。 type または query のない追加や削除、capability のない provider の追加、role のない governance の追加、acceptCapabilities のない cli の追加、entity または plugin のないアラインメント、選択モードを両方指定するかどちらも指定しない生成、あるいは overlay または outputDir のない生成がこれに当たります。いずれも標準の invalid-params コードで返され、リクエストを変えるまで再試行しても何も変わりません。クエリがどのエントリにも一致しない削除も、タイプ、クエリ、検索したファイルを示して拒否されます。これはリクエストではなく設定の状態であるため、修正すべきものはどちらでもありえます。
何もプロンプトで尋ねられず、人に尋ねられるはずだった唯一の判断は代わりにフィールドとして届きます。 ターミナルコマンドは、見ている人に、コマンド拡張プラグインが宣言した機能を受け入れるかどうかを尋ねます。このストリームは誰も見ていないため、acceptCapabilities は呼び出し側が取得して送信するものであり、それを持たないリクエストは、誰も与えていない同意に基づいてインストールするのではなく、送信すべきものを示して拒否されます。コマンド拡張をインストールする手段なしで起動されたデーモンは、何もインストールしていない成功を報告するのではなく、cli の追加をそのまま拒否します。
作成者に提示してよい種別
kind を指定しない aggrega/getSchema は、指定できる種別を返します。クライアントは用途に応じて異なる範囲を必要とするため、回答は 2 つの範囲で返されます。求めている方を読んでください。
kinds は、バイナリが応答するすべてのトークンです。entityKinds は、作成者がドキュメントを書く種別の集合です。 広いリストには、作成する種別と並んで、中間表現、ロックファイル、ワークスペース設定、プラグインのソケット契約が含まれます。いずれも実在するスキーマですが、誰かがファイルとして書くドキュメントではありません。したがって、エディタのスキーマ関連付けには広いリストを使い、選択肢の一覧には狭いリストを使います。広いリストから作った選択肢の一覧は、どの作成用スキーマも受け付けない値を提示してしまい、作成者はそれを選んだ後で初めて拒否に直面します。
狭い集合はエンティティ種別よりもさらに狭く、どれが除かれるかをスキーマは示しません。 内容が別の種別のドキュメント内に書かれる、プラットフォーム所有の種別は、作成者に新規作成を提示するドキュメントではありません。Workload はそのような種別です。workload の内容は Recipe または FeatureRecipe の workload: フィールドに、インラインで、またはそのフィールドがインポートするファイルから書かれるため、単独で扱える workload ドキュメントは存在しません。その内容をどこに書くかは Workload の作成インターフェースを参照してください。そのスキーマは、作成される種別のスキーマと同様に apiVersion と kind を厳密に固定しています。これにより内容をその場所で検証できるからです。固定値は内容を識別するものであり、内容を単独で扱えるようにするものではありません。したがって、それらはその種別が下書き対象であることを示すものではありません。答えを持っているのは entityKinds であり、スキーマのバイト列にはありません。
各 entityKinds エントリは、クライアントが必要とする 2 つの表記を両方持ち、どちらも他方から導出できません。 kind は小文字ハイフン区切りのトークンで、このメソッドまたは aggrega/scaffoldEntity に kind としてそのまま送り返します。documentKind は、ドキュメント自体がトップレベルの kind: フィールドに持つ値です。名前が複数語からなる種別では、両者は大文字小文字以上に異なります。featurerecipe をどう加工しても FeatureRecipe にはなりません。一方から他方を導出せず、それぞれをエントリから取得すれば、クライアントが保持すべき対応表は残りません。
各エントリは、その種別のドキュメントを受け付ける操作も示します。これにより、ドキュメントに対してそれらの操作を提示するコントロールは、その種別を理由に拒否しない操作だけを提示できます。 acceptedBy は 3 つの真偽値を持ち、いずれもすべてのエントリに存在します。それぞれは、その種別のドキュメントをパスで、または検査の場合は名前で単独に指定し、ほかに何も添えずに送った場合についてのものです。singleEntityValidation は、aggrega validate <path> がその種別のドキュメントを検査するか、それとも拒否して代わりに検査するカタログ全体または Release のスコープを示すかです。publication は、ドキュメントのみを指定した aggrega/publishEntity がそれを公開するかです。Plugin は false です。その公開ではリクエストが plugin で指定する実行ファイルも結び付けるため、ドキュメントのみを指定したリクエストは拒否されます。Manifest と Release は、どちらの種別も公開されないため false です。inspectionByName は、aggrega/entityDefinition が名前をその種別のエンティティに解決するかです。名前は、あるエンティティが別のエンティティを参照するときの書き方で送ります。Plugin は <pluginType>/<name>、Recipe または FeatureRecipe は <capability>/<name>、あるいはその名前を宣言する capability が 1 つだけの場合は名前のみです。true は、その種別であることを理由に操作がドキュメントを拒否しないことを示します。個々のドキュメントを、その記述内容を理由に拒否することはありえます。
独自のリストを保持しないでください。 どの種別が存在するかは通信相手のバイナリの性質です。クライアントに書き込んだリストは、書いた日には一致しますが、種別が追加された日に一致しなくなります。そのとき作成者が目にするのは、その種別を提示するはずだった唯一のコントロールから自分の種別が欠けている状態です。問い合わせれば、回答はバイナリに従います。
両方の範囲は一緒に、そして種別を指定しない場合にのみ返されます。 種別を指定したリクエストはその種別のスキーマで応答し、どちらのリストも含みません。そのため、どちらの問いをしたかはレスポンスから読み取れます。どのスキーマも応答しないトークンは、有効な集合全体をメッセージに含めて、標準の invalid-params コードで拒否されます。したがって、タイプミスは人に尋ねる事柄ではなく、修正すべきリクエストです。
何も含まないワークスペースでも応答します。 語彙はバイナリにコンパイルされているため、ドキュメントもロックファイルもカタログも必要ありません。最初のドキュメントを書き始める作成者がいるのは、まさにそのようなワークスペースです。
スキャフォールドのレスポンスが返すもの
このセクションはドラフトの作成について説明します。このメソッドのもう 1 つの形式は実行可能なサンプルを書き出し、その回答は上記のメソッドの説明で述べています。
aggrega/scaffoldEntity はテキストを返します。skeleton は指定した kind の YAML で、その kind のスキーマが必須とするすべてのフィールドを、スキーマが宣言する順序で含みます。スキーマが単一の固定値に固定しているフィールドは値が埋められた状態で届きます(目に付くのは apiVersion と kind です)。metadata.name には送信した name が入り、その他の必須値はすべて、スキーマがその位置で宣言する型に合わせたプレースホルダーとして届きます。空文字列、ゼロ、false、空のリスト、空のマッピングです。kind はドキュメントの導出元となったトークンを繰り返すため、複数のリクエストを処理待ちにしているクライアントは、独自の対応付けを保持せずに、応答そのものから応答の帰属を判断できます。
このメソッドは何も書き込みません。設計上考慮すべきなのはこの点です。 このメソッドはファイルを作成せず、パスを選ばず、ディレクトリにも触れません。受け取るのは書き込むべきドキュメントであり、書き込まれたドキュメントではありません。したがってエディタはそのテキストを、作成者が読み、編集し、破棄できる未保存の新しいバッファに入れます。新しいファイルがディスクに書き込まれるタイミングは、バッファと元に戻す履歴がある側に委ねられます。このドキュメントを受け取って代わりにどこかへ配置するリクエストはほかにありません。新しいドキュメントの置き場所を決めるのはエディタです。
このメソッドは何も解決せず、ワークスペースから何も必要としません。 ドキュメントはバイナリが持つスキーマから導出されるため、このメソッドはレジストリにもネットワークにもアクセスせず、カタログを参照せず、ファイルも読みません。まだ Aggrega ドキュメントが 1 つもない空のディレクトリを含め、どのワークスペースでも同じように応答します。これはまさに最初のドキュメントを書き始める作成者がいるワークスペースであり、ここで説明するほかのほとんどのメソッドがまずドキュメントやロックファイルを必要とする場所です。
同じリクエストは、どこで問い合わせても同じバイト列を返します。 ドキュメントは、この機能を提供するほかのインターフェースと共有される 1 つの計算によって生成されます。そのため、同じ kind と同じ名前を求められたエディタとアシスタントは、作成者に同じ初期テキストを示します。
スケルトンはその kind が必須とするフィールドを含みますが、完成したドキュメントではありません。 含まれるのは必須フィールドだけです。必要な任意フィールドは自分で追加するものであり、すべてのプレースホルダーはまだ埋める必要のある値です。プレースホルダーを埋めてから、バッファに対して aggrega/validate を実行します。aggrega validate が単一エンティティとしてチェックする kind のカタログエンティティについては、このメソッドは、保存済みファイルにコマンドが適用するのと同じ読み取り方で、まだ埋められていないすべてのプレースホルダーを、そのキーの位置で、何を受け付けるかとともに示します。スキーマが空を許容するプレースホルダーも含まれ、下書きした Recipe や FeatureRecipe の capability と implements がよく出会うものです。その他の kind については、バッファをその kind のスキーマに照らして検証するため、スキーマが空を拒否するプレースホルダー(たとえばバージョン)はそのスキーマの検出結果として返り、スキーマが空を許容するものは何も返しません。各プレースホルダーがどのようなエントリとして届くかは Live validation で説明しています。
import レスポンスからわかること
aggrega/import は、別のツール向けに書かれたソースをドラフトの Aggrega ドキュメントに変換し、それらを書き込みます。テキストを返すだけの前述の scaffold とは異なります。written は、ディスクに書き込まれた各ファイルを outputDir からの相対パスで示します。files は、リクエストが書き込むすべてのファイルを、実際に書き込まれたかどうかにかかわらず、その content とともに保持します。内容は、インポーターが生成したすべてのドラフト、続いてインポートが書き込んだものの記録、あるいは sync の場合は同期が変更するものです。この二つは異なる問いに答えるため、問いに応じたほうを読んでください。今ディスクに何があるのか、それとも何が生成されたのか、です。
ドラフトの配置先は指定することも、ワークスペースルートに任せることもできます。 outputDir は、aggrega import --output-dir やアシスタントの import ツールの output_dir と同様に省略可能です。何も指定しないリクエストはワークスペースルートの下にドラフトを作成します。これは、配置先を与えられなかった aggrega import が、どこで実行されても書き込む場所です。指定したリクエストはそこにドラフトを作成します。指定するディレクトリはワークスペース内のパスであり、相対値は、デーモンがたまたま置かれているディレクトリではなく、ワークスペースルートを基準に解決されます。変換する source はこれとは別で、このような制限を受けません。そのファイルやディレクトリは利用者が選択したものなので、どこにあってもその場所で読み込まれ、そこで読み込んでもドラフトの配置先は変わりません。ディレクトリが存在しない場合は作成されます。dryRun では何も書き込まれず、各ドラフトは、レスポンスが示す outputDir(送信したディレクトリ、またはワークスペースルート)からの相対パスで、対象とするパスを示します。
リクエストが outputDir にすでにある Aggregate を上書きすることはありません。 Aggregate は、ドラフト作成後も作成者が編集を続けるドキュメントです。そのため、ドラフトのいずれかが Aggregate として読めるファイルに配置されることになるリクエストは拒否され、そのドラフトと Aggregate の場所が示され、何も書き込まれません。ドライランは書き込みが拒否するものを拒否するため、dryRun の場合も同様です。代わりに sync を送信してソースに合わせて最新化するか、別の outputDir を指定してその横にドラフトを作成してください。ドラフトのパスにすでにあるその他のファイルはすべて上書きされ、以前のインポートがドラフトとして作成し、今回のインポートが作成しないファイルはそのまま残ります。何かをドラフトとして作成するリクエストはすべて、outputDir に .aggrega-import.json も書き込みます。これはインポートが書き込んだものの記録で、送信された target(送信された場合)と、読み取ったカタログスナップショット(読み取った場合)と、ドラフトとして作成された各ファイル、そしてドラフトの Aggregate または Release ではあらゆる深さの各キーを、そこに書き込まれたテキストのダイジェストとともに記録します。その他のドラフトファイルはファイル全体として記録されます。files と written は、ドラフトの後にこれを含みます。これは JSON であるため、ワークスペースの YAML ドキュメントを読むものはこれを読みません。sync は、aggrega import --sync と同様に、これを読んでドラフトをソースに合わせて最新化します。target を送信しない sync は記録が示すターゲット向けにドラフトを作成するため、以前のインポートが作成した Manifest をドラフトとして作成します。target を送信したものはそのターゲット向けに作成し、その後は記録がそれを示します。カタログ内のどの Recipe もバインドしない記録済みターゲットは、送信されたターゲットと同様に拒否され、その拒否はターゲットが記録済みのものであることを示します。ドラフトの Release はキー単位で記録されるため、インポートがコメントを残した箇所に作成者が書いた環境は作成者が書いたキーであり、同期はそれをバイト単位でそのまま残します。
sync を送信すると、以前のインポートが outputDir に作成したドラフトをソースに合わせて最新化します。変更するのはインポートが書き込んだものだけです。各部分は三つの観点で判断されます。記録上インポートが最後にそこへ書き込んだもの、ディスク上にあるもの、そしてソースが今ドラフトとして作成するものです。ソースがインポートの最後の書き込みのまま残している部分は、作成者が編集したかどうかにかかわらず、ディスク上の状態のまま保たれます。ソースが変更した部分は新たに書き込まれ、削除した部分は取り除かれ(ドラフトファイルの場合はファイル全体が削除されます)、追加した部分は、ドラフトがその周囲に示す部分の横に追加されます。いずれも、ディスク上の内容がインポートの最後の書き込みと一致し、作成者が追加したものを含まない場合に限ります。それ以外はすべてバイト単位でそのまま残ります。作成者がどこかに追加したキー(パラメーター、Feature、ドラフトの Component インスタンスの下にあるものも含む、別の Component)、ドラフトのキーの直上に書かれていないコメント、そして記録に載っていないすべてのファイルです。記録がなく、ドラフトのパスに何もないディレクトリへの同期は、sync なしのリクエストと同様にドラフト全体を書き込みます。
drift は同期が最新化したものであり、「ソースは変わったか」への答えです。 同期が変更した各部分(dryRun の場合は変更するはずの各部分)を、ドラフトが示す順序で列挙します。各項目は、change(added、removed または changed)、file(その部分を含むドラフトファイル、outputDir からの相対パス)、key(ドラフトの Aggregate または Release でその部分に至るキーのリスト。そのため、ピリオドを含むキーも一つの要素のままです)からなります。部分がファイル全体の場合、key は空です。同期が削除するドラフトファイルはこのように示されます。aggrega import は同じ項目を標準エラーに <change> <key> in <file> または <change> <file> として出力し、--sync --dry-run での終了ステータスはソースがずれたかどうかを示します。このインターフェースには終了ステータスがないため、sync を dryRun とともに送信し、drift が空かどうかを確認してください。同期ではないリクエスト、ソースと一致している同期、インポーターが完了できなかった同期では、drift は空のリストです。sync の場合、files は同期が変更する各ドラフトファイルをその新しい内容とともに含み、記録も変更される場合はその後に記録を含みます。written はそのうちディスクに書き込まれたものを示します。そのため、一致している同期では両方とも空のリストです。同期が削除するドラフトファイルは drift に示され、どちらのリストにも含まれません。空の key を持つその removed 項目が、回答におけるそのファイルの唯一の記述であり、dryRun の場合は書き込みが削除するはずのファイルを示します。
同期は作成者が書いたものを書き換えることはなく、その代わりに拒否します。 作成者が編集した部分を変更または削除する、作成者がすでに書いた場所に部分を追加する、あるいは作成者が追加したものを含む部分を削除することになる同期は拒否されます。その際、該当する各部分とその理由が、aggrega import --sync と同じ文言で 1 行ずつ示され(<file> <key>: <why>、ファイル全体の場合は <file>: <why>)、何も書き込まれません。ドラフトのキーの直上に書かれたコメントは、そのキーを編集したものとみなされます。記録に載っていない Aggregate への同期は、その Aggregate と記録を示して拒否されます。記録を読み込めない同期も同様です。記録がなければ、その部分を作成者のものと区別できないためです。どちらの拒否も、dryRun の場合も含めて invalid-params エラーとして返され、sync を示します。示された各部分を手作業で調整するか、インポートがそこに書き込んだものを元に戻してから、リクエストを再送信してください。
🔴 halted: true はエラーではなく、エラーとして扱うことこそ避けるべき誤りです。 すべてを変換できなかったインポーターも、変換できたものはドラフトとして作成します。レスポンスはそれらのドラフトを含み、written がそれらを示し、diagnostics が何が除外されたかを示します。これはこの操作が返す最も有用な回答であり、作成者に両方を示せるよう、あえて失敗ではなく結果として返されます。sync の場合、同じ回答は何も書き込みません(files、written、drift は空です)。部分的なドラフトは、インポーターが到達しなかったすべての部分をソースが削除したかのように読めてしまうためです。インポーターがまったく読み込めなかったソースは別のケースであり、エラーとして返されます。
各診断は severity と message を持ち、インポーターが割り当てた場合は code も持ちます。 特定の状況に対応したい場合は code で分岐し、読者には message を表示してください。severity は、すべてのプラグインソケットが報告に使うものと同じ集合(halt、warn、info)から取られます。そのため halted は、別個の判断ではなく項目の要約です。files、written、drift、diagnostics、decisions は常に配列であり、存在しない代わりに空になります。
decisions は、インポートが推測した箇所を示します。 インポーターがマッピングしたソースノードごとに 1 つのエントリを、インポーターの順序で、インポーターが報告したとおりに持ちます。sourceNode はノードの id、type、paramsSummary です。candidates は、インポーターがそのノードについて検討した各カタログ Component で、componentName、score、tier、signals(各シグナルが寄与した内容で、table、category、domainLabels、shape、name の下にあります)として示されます。chosen は、選んだ target、それを書き出した mode(既存の Component への reference または draft)、および選択の tier です。rationale はその理由、swapHint は別の選択をする方法です。インポーターが何も検討しなかった場合は candidates が、選択しなかった場合は chosen が、何も書かなかった場合は rationale と swapHint が省略されます。すべての値はインポーター自身のものです。候補をどう採点し、ティアがどこで区切られるかはインポーターの選択です。そのため、エントリは判定としてではなく、マッピングについてのインポーターの説明として表示してください。decisions は dryRun の下でも、halted が true の場合でも同様に返されます。部分的なインポートの推測こそ、それをレビューする作成者が必要とするものであり、何も報告しないインポーターは空のリストを返します。テキストとして表示する場合、aggrega import はすでに 1 つの決定を mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score> と表現しており、score は最良の候補のものです。
フォーマットは、指定しない限りソースから認識されます。 認識には、インポーターが宣言するシグネチャを使います。ワークスペースのカタログのインポーターも、コンパイラのコアインポーターも同様で、各インポーターの Plugin エンティティがそれを記録しています。シグネチャには、ソースを読む構文、シグネチャが適用されるファイル名、およびパース済みツリーが持たなければならない、または持ってはならないパスが含まれます。そのため、デーモン自体はどのフォーマットも知らず、新しいインポーターのフォーマットは他に何も変更せずに認識されます。検出は送信されたソースだけを読み(ディレクトリの場合は、シグネチャのファイルパターンが選択するファイルだけ)、ネットワークには接続しません。読む各ファイルは、ワークスペースのカタログがその構文に提供するパーサー(カタログがパーサーを提供しない構文では、コンパイラ自体が持つパーサー)で、そのファイル名に適用されるシグネチャが読む構文ごとに 1 回パースされます。その後、インポーターは同じパーサーでソースを読みます。ファイルパターンを宣言しないシグネチャは、名前にかかわらず送信されたファイルに適用され、ディレクトリ内のどのファイルにも適用されません。Langflow、Flowise、n8n のインポーターのシグネチャはこの種類で JSON を読み、Dify のインポーターのシグネチャは YAML を読みます。そのため、単独で送信されたファイルを認識する際には JSON と YAML の両方として読みますが、ワークスペースのカタログにパーサーは必要ありません。コンパイラは JSON と YAML のパーサーを持ち、カタログが提供するパーサーがあればその代わりに使われます。どのシグネチャにも一致しないソースは、format を求め、インポーターが公開しているフォーマットを挙げて(ディレクトリの場合は、そのファイルの 1 つを単独で送信するか、インポーターがファイルパターンを宣言している format を指定するよう求め、それらのフォーマットだけを挙げて)、No importer recognises the source(ソースを認識するインポーターがありません) の条件で拒否されます。複数のフォーマットのシグネチャに一致するソースは、それらを挙げて、More than one importer recognises the source(複数のインポーターがソースを認識しています) の条件で拒否されます。各拒否の data は条件の code と shortCode を持つため、クライアントは文言ではなくコードに基づいてフォーマットを尋ねます。どちらの場合も推測はしません。推測したフォーマットは誤ったインポーターを解決し、もっともらしい誤った結果を生むからです。レスポンスの format は、検出されたものか指定されたものかにかかわらず実際に使われたもので、省略したクライアントは何が使われたかを知ることができます。
送信したディレクトリはインポーターが指定するファイルとして読み込まれ、読めないディレクトリはエラーになります。 source がディレクトリを指す場合、インポーターには、そのシグネチャが宣言するファイルパターンが選択するディレクトリ内のファイルが、ワークスペースのビルド出力フォルダー dist/ を除いて、ディレクトリ内のパスで名前付けされ、ソート順で、その plugins.importer エントリが with.sources の下で指定するファイルと並べて渡されます。ファイルパターンを宣言しないインポーター、パターンが選択するファイルを含まないディレクトリ、同じ名前のディレクトリ内ファイルと with.sources ファイル、およびインポートが読むファイルの中にあるリンクやディレクトリへのリンクでディレクトリの外に出るものは、いずれも条件のコードを持つエラーとして返され、何も書き込まれません。
どのインポーターを実行するかは、リクエストではなくワークスペースが決めます。 フォーマットは、ワークスペースのカタログプラグインとコンパイラのコアインポーターの中でそのフォーマットを公開するインポーターに解決されます。ワークスペース設定の plugins.importer エントリがそのうちの 1 つをアタッチしている場合は、そのインポーターです。そのため、リクエストがモジュールを選んだり、ディスク上のモジュールを指したりすることはできません。どのインポーターも公開していないフォーマットは、そのフォーマットを挙げて拒否されます。2 つのインポーターが公開し、どちらもアタッチされていないフォーマット(コアインポーターと、カタログが同じフォーマットについて持つ別名のインポーターの組み合わせを含みます)は、任意に解決されるのではなく、曖昧であるとして拒否されます。
マシンにまだ存在しないコアインポーターは、それを必要とする最初のインポートによって一度だけ取得されます。 取得元はワークスペースのデフォルトレジストリで、コンパイラのリリースが公開するモジュールに固定され、pull が取得するプラグインを検証するのと同じ方法で検証されます。つまり、そのレジストリのトラストポリシーに基づく署名と、使用するホスト関数が検証されます。取得したモジュールはワークスペースのコンテンツキャッシュに保持され、これがそのために書き込まれる唯一のものです。lockfile も、信頼済みプラグインの記録も書き込まれません。以降のインポートはすべてそこから読み込み、レジストリには到達しません。検証に失敗したモジュールはその条件のコードを伴うエラーとなり、何も保持されません。取得できないモジュール(ワークスペースがオフラインである、レジストリに到達できない、またはレジストリがそれを保持していない場合)は、A plugin’s .wasm is not on this machine(プラグインの wasm ファイルがこのマシンにありません) のもとでのエラーとなり、インポーター、そのバージョン、およびそのモジュールをマシンに配置する方法が示されます。リクエスト自体はレジストリを指定せず、必要なすべてのインポーターと読み取るカタログがマシン上にあるインポートはネットワークにまったく到達しません。
ワークスペースがカタログフォルダーを指定していない場合、インポートはデフォルトレジストリが公開するカタログを読み取ります。 workspace.catalog_dirs、AGGREGA_CATALOG_DIRS、ルートのいずれもカタログフォルダーを指定していないワークスペースは、標準ライブラリのカタログを、デフォルトレジストリ上の catalog/snapshot にある 1 つの署名付きスナップショットとして読み取ります。スナップショットは一度だけ取得されます。その署名はそのレジストリのトラストポリシーに基づいて検証され、スナップショットはワークスペースのコンテンツキャッシュに保持されて、そこでダイジェストに固定されたカタログフォルダーとして読み取られ、再びレジストリに問い合わせることはありません。リクエストが読み取るスナップショットは、upgrade を指定した場合は最新のもの、そうでなければ outputDir 内の記録が示すもの(マシンが保持していない場合はダイジェストで取得)、そうでなければワークスペースが最後に最新として取得したもの、そうでなければ最新のものです。インポートが書き込む記録は、読み取ったスナップショットをダイジェストで示すため、同じ outputDir への後続のリクエストは同じカタログを読み取ります。オフラインモードでは、スナップショットを取得する必要があるリクエストは The workspace is offline and the step needs the network(ワークスペースがオフラインで、このステップにはネットワークが必要です) のもとでのエラーとなり、実行すべきものが示されます。また、どのスナップショットが最新かを示せるのはレジストリだけなので、マシンが何を保持していても upgrade は拒否されます。スナップショットを公開しないレジストリではインポートにカタログがなくなり、diagnostics 内の warn エントリがその旨を示します。カタログフォルダーを指定しているワークスペースはそのフォルダーに対してインポートし、スナップショットを取得しません。そこでは upgrade は何も変えません。
dryRun の下では何も作成されません。 written は空で、files は書き込みが生成したはずのものと同じファイルを持ちます(sync の場合は、同期が書き込むファイルを、同期が最新にする drift と並べて持ちます)。ディレクトリも作成されません。そのため、エディタはそれらを作成者に提示し、保存、修正、破棄を選ばせることができます。書き込みが行うそれ以外のことはすべて行われます。同じインポーターが同じソースに対して実行され、同じ診断を報告するため、書き込みで拒否されるソースはここでも拒否されます。dryRun の下で取得されたコアインポーターやカタログスナップショットは、書き込みの場合と同様にコンテンツキャッシュに保持されます。インポートの実行に必要なものの取得は、ドラフトの配置ではなくインポートの実行の一部だからです。
インポーターが返すパスは outputDir の内側に限定されます。 ドラフトのパスはリクエストではなくインポーターから来るため、出力ディレクトリの外に出るパスは拒否され、何も書き込まれません。パスに問題のなかったドラフトも書き込まれません。拒否は問題のパスを示し、それによって修正すべきはリクエストではなくインポーターであることがわかります。
各エンティティリクエストが答える問い
ここではエンティティについて教えてくれるリクエストが 4 つありますが、互いに置き換えられるものではありません。どれを選ぶかは、問い合わせる時点で何を手にしているかによります。
カーソルを手にしている場合。 aggrega/hover と aggrega/resolve はファイルと位置を受け取り、そこに書かれている内容からどのエンティティを指しているかを判断します。これらは、ドキュメントに実際に現れる参照の形をカバーします。すなわち extends の値、component または feature の型、Recipe の implements、Manifest の recipe 参照、Release の 2 つのパスポインタ、uses のターゲット、そしてエンティティ自身の metadata.name です。ユーザーのカーソルが座標となる場合、つまりユーザーがドキュメントを読んでいて、ある参照が何を指しているかを知りたい場合に使います。
名前を手にしている場合。 aggrega/entityDefinition は識別子をそのまま受け取ります。何かを開いている必要はなく、位置も関係せず、クライアントが見つけられる場所でエンティティが言及されている必要もありません。ユーザーが名前を入力した場合、リストから選んだ場合、またはクライアント自身がすでに識別子を知っているものをたどった場合に使います。hover では、まず名前が書かれている場所を見つける必要があり、それは本来不要な作業です。
まだ何も手にしていない場合。 aggrega/catalogIndex はワークスペースが保持するものを、各エンティティの説明用フィールドとともに列挙します。ピッカーを埋めるのに使い、選ばれた名前を aggrega/entityDefinition に渡します。
Release を手にしている場合。 aggrega/releaseClosure は 1 つのエンティティではなく Release について答えます。これについては次のセクションで説明します。
名前によるリクエストが返す定義は、いずれかのファイルが宣言しているとおりのものではなく、解決された状態のエンティティです。ベースを extends する Component や Feature は、そのベースのコントラクトを含んだ状態で返されます。これはその名前を宣言しているドキュメントのどこにも現れません。したがって、答えはエンティティが実際に何であるかについてのものであり、ファイルを自分で読んでも同じものは得られません。
定義はレスポンス内の構造としてではなく YAML ドキュメントとして届きますが、これは意図的なものです。スキーマの柱には、内容を直接書く、共有ドキュメントを参照する、内容がベースから来ることを示すマーカーを置く、という複数の記述形式があり、ドキュメントは解決がたどり着いた形式を、作成者自身のキー順序のまま再現します。フィールドが必要であればドキュメントとしてパースし、パネルに表示するのであればそのまま表示してください。
名前による 2 種類の拒否を見分ける
何にも解決されない名前は、空のドキュメントで答えられるのではなく拒否されます。空の答えでは、タイプミスが自身について何も語ることのないエンティティとして報告されてしまうからです。名前が何にも解決されないケースは 2 つあり、読み手に求められる対応も異なります。両者はメッセージを読むのではなく、エラーの data に何が含まれているかで見分けます:
dataにfileがない場合。 ワークスペース内のどこもその名前を宣言しておらず、どのカタログ階層もそれを解決しません。ほとんどの場合、修正すべきはリクエストのほうです。タイプミスか、このワークスペースの検索パスにないカタログの名前です。dataにfileがある場合。 ワークスペースのドキュメントがその名前を宣言しているにもかかわらず、カタログはそれに対して何も解決しませんでした。エンティティは書かれているものの何かがそれを拒否したということであり、これは人が修復すべきワークスペースの状態です。カタログが読み込んで拒否したドキュメントのうち、ちょうど 1 つがその名前を宣言している場合(通常の原因)、メッセージはその拒否を一度だけ述べることから始まります。すなわちカテゴリとショートコード、報告されるパスでのドキュメント、そしてどこに問題があるか(行や違反している制約など)です。続いて、そのファイルがロード時にスキップされたことを示し、ロードで拒否されたほかのファイルを列挙します。それ以外の場合、メッセージは宣言しているドキュメントを示し、ロードで拒否されたファイルを列挙し、このワークスペースがローカルエンティティをどこから読み込むか、そしてドキュメントが読み込まれるようにするには何を変更すればよいかを説明します。拒否されたドキュメントがその名前を宣言している場合にこの説明が省かれるのは、そのドキュメントがすでにカタログの読み込む場所にあるためです。
どちらも entity-not-resolvable コードを持つため、コードではなく file の有無で分岐してください。
座標について問い合わせる
レジストリ参照を手にしている場合。 それを aggrega/entityDefinition の name として送ると、その座標で公開されているエンティティが返されます。結果の形は名前の場合と同じで、published が追加されます。値はカタログが解決したものではなく、公開されたものから埋められます:
definitionは公開されたとおりのエンティティドキュメントです。宣言するファイルとともにエンティティが公開された座標はアーカイブを持ち、ドキュメントはそこから展開されます。ファイルを宣言しないエンティティの座標はドキュメントをそのまま持ちます。Plugin のエンティティは、一緒に公開された実行ファイルからではなく、そのマニフェストから読み込まれます。継承は適用されません。authoredLengthはそのドキュメントの長さです。ここでの定義は、解決されたドキュメントのレンダリングではなく、作成されたドキュメントそのものだからです。fileは空です。レジストリから読み込まれたエンティティには、このマシン上で示すべきドキュメントがないためです。publishScopeは省略されます。エンティティが公開されている場所である座標を、すでに手にしているためです。publishedは読み取られた内容で、この応答にのみ含まれ、名前による応答には含まれません。その内容は、reference、archive(その bytes が、ドキュメントの展開元となったアーカイブであったかどうか。座標がドキュメントそのものを保持していた場合はfalse)、マニフェストが宣言するmediaType、そしてそのマニフェストのmanifestDigestです。このダイジェストをタグの代わりに@の後ろに付けて送ると、同じ bytes を正確にもう一度読み取れます。
リクエストは、このデーモンを実行しているユーザーの認証情報と、このワークスペースのネットワーク設定のもとで、参照が示すレジストリに到達します。そのため、オフラインのワークスペースではこのリクエストは拒否されます。取得したバイト列は、アーティファクト自身のマニフェストが記録するダイジェストに対してのみ照合されます。署名は検証されず、取り下げも報告されず、何も書き込まれません。読み込めない参照は entity-not-resolvable で拒否され、メッセージはその理由を示す条件のショートコードで始まり(aggrega inspect が報告するのと同じ条件です)、対処方法で終わります。リポジトリを示さない参照、またはタグもダイジェストも示さない参照は不正なリクエストであり、invalid params として拒否されます。
クロージャはグラフではない
aggrega/irGraph と aggrega/releaseClosure は、同じ Release の同じ解決から導出されますが、答える問いは異なります。すでにグラフを受け取っているクライアントは、こちらも持っていると考えがちですが、そうではありません。
グラフは Release が何をデプロイするかを示します。つまり、ノード、それらが置かれる境界、何が何に接続されているか、そして各ノードが持つ値とアタッチメントです。これは全体像です。
クロージャは、それを構築するために何がどのバージョンで取り込まれたかを示します。 Release が到達するすべてのエンティティ(ノードになったかどうかを問わない)、それらのエンティティが利用する共有ドキュメント、そして出力を形作るプラグインです。これは部品表です。
どちらも、もう一方から復元することはできません。エンティティはノードとして一度も現れずに到達されることがあります。Manifest がコンポーネント型をマッピングする先の Recipe は、すべてのビルドで到達されますが、どのビルドでもノードにはなりません。また、ノードはその型が解決されたバージョンを持ちません。したがって、「なぜこのバージョンが変わったのか」「この共有ドキュメントを変更すると何に影響するのか」「この Release は実際に何に依存しているのか」を尋ねる読者が求めているのはクロージャであり、「この Release は何をデプロイするのか」を尋ねる読者が求めているのはグラフです。
クロージャリクエストが行わないこと。 何もレンダリングせず、見つけたものを何も公開しません。特に、ドリフト警告もレンダリングに関する勧告も出しません。それらはそれを求めたリクエストに属するものであり、公開は診断レイヤー全体を置き換えるため、公開を行う一覧は、グラフリクエストがすでにユーザーに提示していた内容を消してしまいます。ドリフトの判定が必要な場合はグラフを要求してください。唯一公開するものは、それ自身の検出結果ではありません。lockfile が失われていることを見つけたリクエストは、どのリクエストであっても、それに基づくドリフト警告を取り下げます。Lockfile の認識を参照してください。
グラフと同様に、lockfile が必要です。 一覧が報告するバージョンは、この Release が解決したバージョンであり、誰も準備していないワークスペースはまだそれらを解決していません。lockfile なしで作成された一覧は、カタログがたまたま現在保持しているものを報告することになり、それはこの Release が何に依存しているかとは別の問いです。拒否はその lockfile と Release を示すため、クライアントは aggrega pull --release <release> を直接提示できます。
クロージャのエントリの kind は、判明している場合にのみ存在します。 参照はドキュメント内の位置から収集され、指す種類を示す位置もあれば、示さない位置もあります。このフィールドは、参照箇所が種類を記録している場合に報告され、記録していない場合には省略されます。名前の形から推測されることはありません。報告される値は、作成者がドキュメントの先頭に書く語であり、クロージャを報告するすべてのインターフェースが同じエントリに対して使う語と同じです。
同じ語で、他の場所でも同じドキュメントを要求できます。 aggrega inspect <release> --closure はコマンドラインでこの問いに答え、describe ツールの release モードはアシスタントツールプロトコル上でこの問いに答えます。3 つはいずれも Release に対して 1 回の解決を実行するため、Release が何に依存しているかについて食い違うことはありません。aggrega inspect の「依存関係のクロージャ」を参照してください。
キャッシュモデル
各操作はキャッシュに基づいて動作します。ファイルに対して hover / completion / resolve / diagnostics を呼び出す前に、そのファイルについて aggrega/validate を呼び出してください。このシード用の呼び出しには Release は必要ありません。Release を指定しない検証でもバッファは解析され、キャッシュに格納されます。そのため、これらの操作は指定できる Release がないワークスペースでも動作します。解析キャッシュは読み取りのたびに各ファイルのディスク上の更新時刻と照合されるため、外部での編集(エディタでの保存や git checkout)は自動的に反映されます。エディタからの aggrega/invalidate は最適化であり、正しさのために必要なものではありません。
キャッシュは、それをシードしたワークスペースに属します。 あるワークスペースで検証されたファイルはそのワークスペース用にキャッシュされるため、同じパスを別のワークスペースで問い合わせると、最初のワークスペースのエントリから回答されるのではなく、まだ検証されていないと報告されます。これにより、2 つ目のワークスペースについての問い合わせが誤った回答をすることも、最初のワークスペースのウォームな状態を失わせることも防がれます。同様に、aggrega/invalidate も指定したワークスペースのみをクリアします。
検証の実行中に診断を要求する
検証はファイルについて 2 つのもの、つまり他の操作に渡す解析結果と、報告する検出結果をシードし、それらは少し時間をずらしてシードされます。 aggrega/diagnostics はその両方を読む唯一のリクエストです。このリクエストは、そのファイルが回答可能なものであることを知るために解析結果を必要とし、検出結果から回答します。そのため、この 2 つの時点の間に到着したリクエストは、回答に使うものがまだ何もないのに回答できると判断してしまうことになります。
そこで、代わりに待機します。 まさに検証中のファイルに対して aggrega/diagnostics を送信すると、その検証が完了した時点で、検出された内容を含む応答が届きます。タイミングにかかわらずファイルに対する正しい回答は 1 つであり、得られるのはその回答です。これから検証でエラーが報告されるファイルに対して空のリストが返ることはありません。それはクライアントが回復できない唯一の誤った回答です。問題がないと伝えられたファイルについて再度問い合わせるきっかけは何もないからです。その他の位置ベースの操作(hover、completion、resolve、findReferences、findImplementations)は解析結果を読み、解析結果から回答するため、待つ対象がなく、決して待機しません。
待機を早期に終了させるものは 2 つあり、どちらもすでに手元にあるものです。 そのリクエストの id に対する $/cancelRequest で停止し、協調的な aggrega/shutdown でも停止します。どちらもリクエストに追加の指定は必要ありません。
また、待機には上限があります。 デーモンが定めた時間内に検証が完了しない場合、リクエストは空の回答を返すのではなく、検証実行中を示すコードで拒否されます。エラーコードを参照してください。この拒否は、待っている処理が実際に進行中であることを意味するため、少し後に再度問い合わせてください。これは別の検証を送信せよという合図ではありません。そうすると処理が増えるだけで、何の回答にもなりません。
リクエストを 1 つずつ実行するデーモンは到着順に回答するため、重なりが生じることはなく、待機も発生しません。リクエストを並行して実行するデーモンも同じ質問に同じように回答し、それを成り立たせているのが待機です。得られる回答は、逐次的な順序で処理した場合に得られたはずの回答と同じです。
応答内のサイズ
バイト量を報告する応答は、それを 2 回報告します。数値として、そして同じ量を書き表したものとしてです。
書き表したフィールドの名前は、数値フィールドの名前に Text を付けたものです。size と
sizeText、totalSize と totalSizeText、reclaimedBytes と reclaimedBytesText のように、
サイズを含むすべての応答で同様です。
表示には書き表した形式を使い、計算には数値を使ってください。両方を送る目的は、クライアントが
サイズを自分で表記する必要を一切なくすことです。デーモンはコマンドラインと同じフォーマッタでサイズを書くので、
aggrega cache status と aggrega/cacheStatus は、あるキャッシュを丸めに至るまで同一に表示します。
独自にテキストを組み立てるクライアントは、境界値の扱いが食い違った時点で
その表示からずれていきます。
書き表した形式は 2 進単位を使います(512 B、1.0 KiB、5.0 MiB、3.0 GiB)。これは
aggrega/cacheEvict が maxSize で受け付けるのと同じ表記なので、ある応答から読み取ったサイズを
書き直さずに次のリクエストで送り返せます。バイトより大きい単位では、テキストは小数点以下 1 桁を持つので、
バイト単位ではなく、読み手が見たい形で量を示します。正確な値が必要な場合は、
数値フィールドがそのためにあります。
数値が省略可能な場合はテキストもそれに伴って省略可能であり、両者が片方だけ存在することはありません。
publish の応答におけるプラグインサイズは、pluginSize と pluginSizeText を両方とも含むか、
どちらも含まないかのいずれかです。
すべてのリクエストは対象のワークスペースを指定します
すべてのリクエストで workspaceRoot を送信します。これは、そのリクエストが対象とするワークスペースルートの絶対パスです。 デーモンは独自のワークスペースを持たず、リクエスト間でワークスペースを記憶しないため、リクエストへの回答は、そのリクエストが指定したワークスペースについてのものであり、それ以外のものではありません。2 つのワークスペースを指定する 2 つのリクエストは 2 つの回答を受け取り、どちらも相手のエンティティ、Releases、キャッシュされたパース結果、診断を参照できません。
ワークスペースを指定しないリクエストは、そのパラメーターを示す標準の invalid-params エラーで拒否されます。空の値も同様に拒否されます。空の値はワークスペースを示さないため、指定がない場合として応答されます。同じ理由で、ほかに 2 つの形も拒否され、それぞれメッセージで示されます。ワークスペースルートには相対の基準となるものがないため相対パス、そしてワークスペースはツリーであるため既存のディレクトリではないパスです。
3 つのリクエストは workspaceRoot を必要としません。いずれも、その対象がワークスペースではないためです。 aggrega/getSchema と aggrega/scaffoldEntity は実行中のバイナリに組み込まれたスキーマから回答するため、ワークスペースはどちらにも何も寄与しません。これにより、どちらも誰も準備していないディレクトリで回答できます。3 つ目は aggrega/initialize で、これはワークスペースに対して操作するのではなく、ワークスペースを宣言する場所です。aggrega/scaffoldEntity のもう 1 つの形式、つまりドキュメントの実行可能なサンプルの書き出しや一覧表示はワークスペースに対して操作するため、そのリクエストは他のリクエストと同様にワークスペースを指定します。
各ワークスペースのキャッシュされた状態は別々に保持され、2 つ目のワークスペースを指定しても 1 つ目には何の影響もありません。 ワークスペースのカタログインデックス、パースキャッシュ、診断はそのワークスペースに属するため、別の場所について尋ねた質問によって、誰かが開いているフォルダーについてエディターが蓄積してきたものが追い出されることはありません。1 つのルートの 2 通りの表記は 1 つのワークスペースであるため、途中に . や重複した区切り文字を含むパスは、その素の形と同じウォームな状態に到達します。
診断をプッシュしてほしいワークスペースの宣言
診断は 2 つの方法で届きます。要求するか、デーモンがプッシュするかです。デーモンは、ハンドシェイクで宣言したワークスペースについてのみプッシュします。 ほかのすべてのリクエストは、その結果を自身のレスポンスで返し、何もプッシュしません。
宣言するには、aggrega/initialize で workspaceRoot を送信します。宣言が行うのはそれだけです。何かをアンカーすることはなく、以降のリクエストがこれに基づいて回答されることもありません。
これを限定する理由は、プッシュされる診断の目的にあります。プッシュは、誰かが入力している間にエディターの問題リストを最新に保つためのものであり、誰も見ることを求めていない回答に対して行うのはまさに誤りです。この規則がなければ、たとえばデーモンを共有する別のツールによって 2 つ目のワークスペースについて尋ねられた質問が、読み手の問題リストを、開いてもいないファイルについての結果で埋めてしまいます。プッシュを限定することで、ある呼び出し元の質問が別の呼び出し元の問題リストに入り込まないようにします。
このフィールドは省略可能で、これによって意図できる 3 つの内容は区別できます。
| 送信するもの | プッシュ先 | ハンドシェイクが報告するもの |
|---|---|---|
| 何も送信しない | プロセスの起動時に対象となったワークスペース | そのワークスペース |
| ワークスペースルート | そのワークスペース | そのワークスペース |
| 空文字列 | どこにもプッシュされない — 診断は一切プッシュされません | 空のルート |
何も送信しない場合、プッシュはプロセスが起動されたワークスペースに対して行われるため、何も宣言しないクライアントはそのワークスペースの診断を受け取ります。空文字列の送信は、エディターではなく同期すべき問題リストを持たない呼び出し元にとって正直な宣言です。すべての結果は、それを生成したリクエストへのレスポンスで引き続き届きます。
宣言されたワークスペースは、リクエストで指定されたワークスペースとまったく同じように解決されます。そのため、相対パスやディレクトリではないパスを指定する宣言は、プッシュを予期しない場所に向けたままにするのではなく、ハンドシェイクの時点で拒否されます。
ワークスペースルートとアクティブな Release
デーモンは、リクエストが指定する各ワークスペースを、すべての aggrega コマンドがワークスペースを解決するのと同じ方法で解決します。何がルートをアンカーし、どの順序で行われるかは Configuration に記載されています。クライアントにとって重要な帰結が 2 つあります。workspace: ブロックを持たない .aggrega-config.yaml はアンカーしません。設定は引き続き寄与しますが、単なる設定ファイルによってすべての親ディレクトリがワークスペースルートになることはありません。また、何もアンカーしない場合は作業ディレクトリが使用されます。デーモンは実行を拒否するのではなく起動し、操作は単に何も解決しません。
プロセスもまた、--workspace-root から、または作業ディレクトリから上位へたどることで、あるワークスペースを対象に起動されます。この解決が行うのは 2 つのことだけです。ワーカープールのサイズを決めること(これはどのリクエストでもなくプロセスの性質です)と、プッシュされる診断の既定の宣言となることです。どのリクエストもこれに基づいて回答されることはありません。
設定も同様に、すべてのコマンドが読むのと同じカスケードであり、その説明は Configuration にあります。デーモンが加えるのは、各ワークスペースについての読み取りを、そのワークスペースが最初に指定されたときに一度だけ行い、以降のそのワークスペースに関するすべてのリクエストで再利用することだけです。カスケードが読むはずの設定ファイルがワークスペースの外へ通じるリンクである場合(ワークスペース自身の .aggrega-config.yaml、またはその隣にある CI 所有のオーバーレイ)、ターミナルの場合と同様にここでも読まれず、そのファイルが設定するはずだった他のものも代わりに読まれることはありません。ターミナルと異なるのは、それでも何が回答するかです。そのようなワークスペースを対象に起動されたデーモンは起動し、エラーストリームでその旨を一度伝えます。そのようなワークスペースを指定するリクエストは、どちらの場合も次のように回答されます。aggrega/releaseCandidates と aggrega/catalogIndex(ワークスペースが保持するものを一覧する 2 つのリクエスト)は、何も設定されていない状態で読み取って回答します。ワークスペース自身のドキュメントが一覧され、カタログディレクトリは読まれず、保留されたファイルは、探索がそれに出会ったかどうかにかかわらず unreadLinkedFiles に示されます。この名前によって、クライアントはワークスペースの設定がその外へ通じていることを判別できます。そのワークスペースを指定するほかのすべてのリクエスト(ビルド、グラフ、検証、既定の Release、有効な設定、書き込み、および Release の観点での aggrega/catalogIndex)はその設定によって決まるため、E0321(エラーの data では read-leads-out-of-workspace)と、リンクとその行き先を示す文を含む invalid-params エラーで拒否されます。ハンドシェイクもそのようなワークスペースについて回答し、一覧が回答に使う内容にどの設定ファイルも寄与していないため、configSource として defaults を報告します。リンクを削除するか、ワークスペース内のファイルを指すようにすれば、次のリクエストで設定が読まれます。プロジェクトのファイルの下にはグローバルレイヤーがあります。デーモンを起動したコマンドラインで --config が指定したファイルが、そのデーモンが扱うすべてのワークスペースに適用されます。それがなければ、設定されている場合は AGGREGA_CONFIG 環境変数が指定するファイル、さらにそれもなければ既定の場所です。既定の場所は、Windows では APPDATA 環境変数が指定するディレクトリ内の aggrega\config.yaml、それ以外では XDG_CONFIG_HOME が指定するディレクトリ内の aggrega/config.yaml で、フォールバックは ~/.config/aggrega/config.yaml です。これらは存在する場合に読み込まれます。その下に組み込みの既定値があります。
Release に対して動作する操作は、Release をパラメーターとして受け取ります。デーモンが独自に選択することはありません。 それでもワークスペースはどの Release を指すかを宣言しており、4 段階のカスケードがその宣言を読みます。build.authoring_release 設定フィールド、次に .aggrega/active-release マーカーファイル、次にワークスペース内に Release が 1 つだけという経験則、最後に Aggregate のみのフォールバックです。したがって、書き込んだマーカーは経験則より優先され、読み込めない Release を指定するマーカーはフォールバックではなく経験則へと進みます。ワークスペース外の Release を指定するマーカー(絶対パス、ルートの外へ上るパス、またはその外へ通じるリンクによるもの)は読まれません。ただし、ワークスペースの設定がその Release を build.authoring_release として、または workspace.releases のキーとして指定している場合は除きます。ワークスペース外に置かれた Release に到達する方法は設定であり、マーカーではありません。その後カスケードは、読み込めないマーカーの場合とまったく同じように進み、何にも決まらない場合は、trace がマーカーの行で、reason がマーカーについての文でその理由を示します。
aggrega/activeRelease はそのカスケードが選んだものを報告します。これはクライアントへの提案であり、デーモンが従う設定ではありません。カスケードの入力を自分で読むのではなく、デーモンに尋ねてください。設定フィールドとマーカーファイルは 4 つの入力のうちの 2 つにすぎないため、どちらを読んでも、それがワークスペースの選択を示すのは、たまたまそれが採用された入力である場合だけです。読み込めない Release を指定するマーカーが最もわかりやすい例です。カスケードはまったく別の Release を選びますが、マーカーを読んだ側は失敗した Release を報告してしまいます。
カスケードは尋ねられたときに実行され、それより前には実行されません。これには頼りにできる帰結が 2 つあります。ハンドシェイクはワークスペースの走査を待たないため、ツリーのサイズにかかわらず高速なままです。また、回答はワークスペースに追従します。マーカーを書き込む(aggrega/setActiveRelease を使うと、新しい選択そのものが回答されます)、設定を編集する、Release ファイルを追加または削除する、そして再度尋ねると、同じデーモンから新しい回答が得られます。作業対象の Release を変更するためにデーモンを再起動する必要はありません。 クライアントは次のリクエストで別の release を送信します。
1 つのバッファーではなくワークスペース全体を検索する操作(completion、hover、resolve、findReferences、findImplementations)は、ワークスペースルート以下の YAML を列挙し、その列挙は .gitignore に従います。ワークスペースルートからファイル自身のディレクトリまでのすべての .gitignore が寄与し、最も近いものが優先されます。そのため、リポジトリが無視する YAML ファイルは補完候補として提示されず、定義や参照としても報告されません。ワークスペースの外へ通じるリンクである .gitignore は読まれないため、マシン上の別の場所にあるファイルが、ワークスペースのどのドキュメントを検索するかを決めることはありません。したがって、ベンダリングされたツリーや生成された出力は、別途の除外設定を管理しなくてもファイル横断の結果から除かれます。一方、見つかるはずなのに無視しているドキュメントは表示されません。参照が見つからないように見えるときに確認すべきなのはこの 1 つのケースです。completion が設定済みの catalog_dirs からも提示する Components と Features は別の読み取りです。これらは設定されたとおりのディレクトリから取得されます(設定がその Release に独自のディレクトリを与えていない場合に Release のビルドが読むのと同じディレクトリ、または Release を指定するリクエストではその Release 自身のディレクトリ)。そのため、カタログディレクトリのエンティティは .gitignore がそれを対象にしているかどうかにかかわらず提示されます。ただし、カタログディレクトリの読み取りがとどまるべきディレクトリの外へ通じるリンクの先にあるエンティティは例外で、読まれず提示もされません。
Release を指定するリクエストは、その Release のカタログディレクトリを読み込みます。これは、ターミナルでその Release をビルドする際に読み込まれるものと同じです。ワークスペース設定が workspace.releases の下でその Release 固有のディレクトリを与えている場合はそれを、そうでない場合はワークスペースの catalog_dirs を読み込みます。対象となるのは、Release を指定した aggrega/build、aggrega/buildPreview、aggrega/irGraph、aggrega/releaseClosure、aggrega/resolveDependencies、aggrega/validate および aggrega/lint、Release のグラフのノードを宛先とする aggrega/attachCandidates および aggrega/attachmentContainer、aggrega/connectionAtPosition、そして次のセクションで挙げるリクエストのうち Release を指定したものです。したがって、Release ごとにカタログのバリアントを持つワークスペースでは、1 つのセッションがワークスペース内のすべての Release に対し、それぞれ固有のバリアントから応答します。Release のパス以外に送るものはありません。単一の Release に関係しないリクエスト、すなわち aggrega/catalogIndex、aggrega/entityDefinition、Release を指定しない completion、hover および resolve、エンティティまたはラベルセットを宛先とする aggrega/attachCandidates は、ワークスペースの catalog_dirs を読み込みます。workspace.releases の下で Releases を指定しているワークスペースでは、エンティティも Release も指定しない aggrega/lint が例外です。この場合、Publishing conventions, on request and on every edit で説明するとおり、Release ごとにカタログ全体を 1 回ずつ検査し、各パスはその Release のディレクトリを対象とします。Giving a Release its own catalog directories を参照してください。
1 つの Release の観点での応答
aggrega/catalogIndex、aggrega/entityDefinition、およびカーソルを起点とする 5 つのリクエスト(aggrega/hover、aggrega/resolve、aggrega/completion、aggrega/findReferences、aggrega/findImplementations)は単一の Release に関係しませんが、それぞれ省略可能な release を受け取り、これを指定すると 1 つの Release に関係するものになります。これはワークスペースルートからの相対パスで、Release を受け取る他のリクエストと同じ規約に従います。Release ファイルを指さない値やディレクトリを指す値は、Release の観点に見せかけてワークスペースの観点で応答されるのではなく、拒否されます。
ここでのすべてのリクエストにおいて、Release が到達するものは次のとおりです。そのスタックが読み込むカタログディレクトリの下にあるワークスペースドキュメントと、どのカタログディレクトリの下にもないすべてのワークスペースドキュメント(カタログと並べて書かれた Release、その Aggregate、その Manifest など)です。他の Releases だけが読み込むカタログディレクトリの下にあるワークスペースドキュメントは、その応答に含まれません。一覧にも出ず、解決もされず、候補にもなりません。これにより、異なる Releases 向けに並べて保持された 1 つのエンティティのバリアントが混同されることを防ぎます。
- 一覧。 Release を指定すると、その Release から見えるエンティティが一覧されます。一覧される Features は、その Release のカタログディレクトリが宣言するものであり、他の Releases だけが読み込むカタログディレクトリの下にあるワークスペースドキュメントは除外されます。そのため、Release ごとに 1 つのエンティティのバリアントを保持するワークスペースでは、すべてのバリアントが並ぶのではなく、その Release がビルドに使う 1 つのバリアントが一覧されます。カタログと並べて書かれた Release、その Aggregate、その Manifest など、どのカタログディレクトリの下にもないドキュメントは、すべての Release の一覧に含まれます。
- 名前による検索。 Release を指定すると、名前はその Release のカタログディレクトリを通じて解決されるため、複数のバリアントが宣言する名前は、その Release がビルドに使うバリアントに解決されます。そのディレクトリで解決できない名前は、
workspace.releasesの下にあるその Release のエントリを示す説明とともに拒否されます。検索が読み込んだのはそのエントリだからです。レジストリ参照は Release を受け取らず、Release を伴う場合は拒否されます。レジストリ参照は、どの Release が指定されていても、それを公開しているレジストリから読み込まれます。 - ホバーと定義へ移動。 Release を指定すると、カーソル位置の参照はまず、ワークスペース設定が与える順序でその Release のカタログディレクトリを通じて解決されます(その Release の観点での名前による検索と同じ解決です)。そのため、別の場所のワークスペースドキュメントが同じ名前を宣言していても、表示されるエンティティと開かれるドキュメントは、それらのディレクトリが解決するバリアントになります。それらのディレクトリの下のどのドキュメントも該当しない場合に限り、その Release が到達するワークスペースドキュメントが検索されます。Release を指定しない場合は順序が逆になります。まずワークスペースドキュメントが検索されるため、ワークスペースドキュメントが該当する参照はその結果を保ち、ワークスペース自身の
catalog_dirsは、どのドキュメントもその名前を宣言していない場合にのみ参照されます。これにより、設定されたカタログディレクトリだけが保持するエンティティ(ワークスペースツリー外のものを含む)が見つかります。Release のディレクトリが解決するドキュメントについてエディタが未保存のコピーを保持しており、そのコピーがまだその名前を宣言している場合、応答はコピーから読み込まれるため、位置はエディタに表示されている行に一致します。 - 補完。 Release を指定すると、候補となる名前は、その Release が到達するワークスペースドキュメントが宣言するものと、その Release のカタログディレクトリが宣言する Components および Features です。
- 参照と実装。 Release を指定すると、その Release が到達しないワークスペースドキュメント内の位置は報告されません。そのため、別の Release 向けに保持されたバリアントが、この Release の参照や実装として一覧されることはありません。
- グラフノードに接続できるもの。 Release のグラフのノードを宛先とする
aggrega/attachCandidatesは、常にその Release の観点で応答します。What an attach-candidate response tells you を参照してください。
Release を指定しない場合は、上の段落で説明したとおり、ワークスペース自身のカタログディレクトリに基づいて応答します。
レジストリへの到達と書き込み
ここにあるほとんどのリクエストは、ワークスペースとすでにキャッシュされている内容から応答し、何も書き込みません。 名前の挙がった少数のリクエストはそれ以上のことを行い、それらは互いに独立した 2 つの軸で分かれます。リクエストが何に到達するか、そして それが変更する内容がどこまで及ぶかです。
レジストリに出ていくリクエストは、読み取るものと公開するものに分かれます。aggrega/resolveDependencies は Release が必要とするものを取得し、aggrega/build は、その autoPull フィールドが先に依存関係の解決を求める場合に限り、これに加わります。その場合はレンダリングの前にレジストリに到達し、ロックファイルを書き込みます。aggrega/registryUpdate はローカルの検索インデックスを再構築するために、設定されたすべてのレジストリを巡回します。aggrega/pluginAdd は、リクエストが指定するプラグインを設定されたレジストリで検索し、その公開済みバージョンを読み取って 1 つを固定します。aggrega/registryAdd は、リクエストが取得を断るか独自のポリシーを渡さない限り、登録するレジストリに、そのレジストリが告知するトラストポリシーを問い合わせます。aggrega/configInit も、シードするレジストリに同じものを問い合わせます。aggrega/explainError は、条件の解説を読み取るドキュメントバンドルを、マシン上のすべてのプロジェクトが共有するキャッシュに、ワークスペース自身の署名検証が認めるコピーがない場合に一度だけ取得します。aggrega explain を参照してください。aggrega/scaffoldEntity は、example または list を送られた場合に同じ条件で同じバンドルを取得し、書き出しの場合はその後、サンプルをワークスペースの新しいディレクトリに書き出します。aggrega/import は、マシンがまだ保持していない場合にコアインポーターをワークスペースのデフォルトレジストリから一度だけ取得し、カタログフォルダーを指定していないワークスペースでは、読み取る公開済みのカタログスナップショットも取得します。import レスポンスからわかることを参照してください。aggrega/entityDefinition は、その name としてレジストリ参照が送られた場合に、その参照が指すエンティティを読み取り、何も書き込みません。aggrega/publishEntity、aggrega/publishArtifact、aggrega/signArtifacts、aggrega/deprecateArtifact はレジストリに書き込みます。書き込むのはバイト列、署名、または取り下げマーカーです。リクエストがレジストリに到達するのは、それを行うために送られた場合だけです。一覧は設定が固定しているものを報告し、検索はオフラインのスナップショットを読み取り、dryRun を指定して求められた公開は送信する内容を計算するだけで、どこにも接続しません。
この規則は、操作がいつ実行されるかについてのものであり、どのサーフェスが実行するかについてのものではありません。
取得や書き込みを行う操作は、リクエストがそれを指定したから実行されるのであり、ドキュメントの検証、グラフの検査、ワークスペースのエンティティの一覧表示の副作用として実行されることはありません。
そのため、キー入力のたびに検証するエディタはネットワークに到達せず、ロックファイルも書き換えません。一方、ユーザーがクリックする「依存関係を解決」アクションは
aggrega pull とまったく同じことを行います。両方のサーフェスの背後で同じ解決が行われ、
バイト単位で同一のロックファイルを書き込み、同じアーティファクトキャッシュを埋めます。
入力を求めることはありません。 このストリームを見ている人はいないため、ID は渡された または周囲の認証情報ソースから解決され、問い合わせによって解決されることはありません。ターミナルのコマンドであれば人に質問していた場面、 つまり認証情報を必要とするレジストリ、複数の provider プラグインが提供する機能、 取り下げに添えるテキストなどでは、リクエストは決して届かない回答を待ってブロックするのではなく、 渡すべきものを示すメッセージとともに失敗します。拒否はワークスペースをまったく元のままに残します。 ロックファイルは書き込まれず、部分的な記録も残らず、認証情報を解決できなかった公開は、 バイト列がレジストリに届く前に拒否されます。
このワークスペースを越えて及ぶ変更があり、応答はそれがどれかを示します
リクエストは 1 つのワークスペースを指定するため、自身の及ぶ範囲について何も述べない応答は、 そのワークスペースについてのものと読まれます。これらのリクエストのいくつかでは、その読み方は誤りになるため、それぞれが 自身のスコープを持ち、クライアントは結果に基づいて動作する前にそれを表示する必要があります。
公開、署名、取り下げはマシンを完全に越えて及び、これはここで最も広い到達範囲です。 以下の他の書き込みはこのマシンが解決するものを変更しますが、これらはそのレジストリから解決するすべての人が行うことを変更します。公開されたバイト列は、そのレジストリのすべての利用者が受け取るものであり、 タグの上に異なる内容を再公開することは提供されず拒否されます。そのため、ここにあるどのリクエストも公開を取り消すことはなく、 対応策は新しいバージョンを公開することです。署名と取り下げマーカーはアーティファクトを置き換えるのではなく、その兄弟として付加されるため、 バイト列そのものは変更されません。しかし、その後にアーティファクトを取得する人はそれらも取得し、 すでに取得した人からはどちらも回収できません。取り下げは 3 つのうち最も誤読しやすいものです。 そのバージョンは引き続き取得可能であり、一方でワークスペースが信頼する撤回は、そのワークスペースでの解決が選ぶ対象からそのバージョンを外します。
署名は認証情報を使用し、その出どころはクライアントを組み込む前に知っておく価値があります。
キーレス署名は ID トークンを、リクエストの identityToken、次にデーモンの環境の
AGGREGA_IDENTITY_TOKEN、次に到達可能であれば周囲の GitHub Actions OIDC エンドポイント、
最後に SIGSTORE_ID_TOKEN の順に解決します。いずれからもトークンが得られない場合、操作は
拒否され、送るべきものを示します。見る人がいないため、ブラウザを開くことはありません。
キー付き署名はオフラインの代替手段であり、リクエストはキーのパスを指定しません。リクエストが読み取るものは
そのリクエストが指定したワークスペース内にあり、秘密鍵がワークスペース内に置かれることはないため、
キーは代わりにそのワークスペース自身の設定の signing: ブロックから得られます。2 つの署名モードとそれぞれの接続先については
aggrega sign を参照してください。
4 つの応答はいずれも reach を持ちます。これは registries、つまり呼び出しが
宛てたすべてのレジストリホストを、それぞれ一度ずつ、呼び出しが最初に宛てた順に保持するため、参照が複数のレジストリにまたがる署名バッチやバッチ
ファイルはそれぞれのレジストリを示します。そして beyondThisMachine を保持します。これは呼び出しが求めたものではなく、
実際に付加したものから導かれます。内容をアップロードした場合、または署名、公開日、非推奨マーカーを付加した場合にちょうど true になり、
ドライランの場合と、付加するはずのものがすべてすでに存在していた呼び出しの場合は false になります。
後者は、すでに完全なバージョンに対して再実行された公開や、すべての参照がすでに検証可能な署名を持っていた署名バッチです。
ドライランでも、宛てるはずだった宛先は示されます。結果に基づいて動作する前に
それを表示してください。
レジストリの登録または削除は、デフォルトでは、マシン上のすべてのワークスペースで共有される設定に書き込みます。
レジストリとそこで信頼する ID は、通常どこで作業しても同じであるため、リクエストが workspace: true を送らない限り、
エントリはそこに書き込まれます。その帰結は
はっきり述べておく価値があります。aggrega/registryAdd と aggrega/registryRemove は、そのマシン上の
すべてのプロジェクトが解決に使うものを変更し、このセッションで誰も指定していないプロジェクトも含まれます。どちらの
応答も scope を持ち、書き込まれた configFile と、それが共有ファイルかどうかを示す machineWide を含みます。
削除は 2 つのうちより影響の大きいものです。再追加は同じ行為ではないからです。固定されていたトラスト
ポリシーは失われ、後の登録はその時点でレジストリが告知するものを固定します。
設定のシードも、同じ理由で、デフォルトではその同じ共有ファイルに書き込みます。 aggrega/configInit はレジストリとそのトラストポリシーを登録します。これはマシン全体のツールであるため、上書き指定がなければ、マシン上のすべてのプロジェクトが解決に使う設定に書き込み、そのレジストリが告知するポリシーを読み取るためにレジストリに一度到達します。その応答は、2 つのレジストリメソッドと同じ scope の組を持ちます。これらとは、頼りにしてよい点が 1 つ異なります。既存の設定ファイルを上書きせずに拒否するため、リクエストが force を送らない限り、誰かが使っている設定を置き換えることはありません。固定化は反対のケースです。 aggrega/configCapture は上書き指定を一切受け取らず、常にプロジェクト自身の設定ファイルに書き込み、レジストリには到達しないため、その動作が他のプロジェクトから見えることはありません。設定の書き込みが残すものを参照してください。
🔴 コマンド拡張プラグインの追加または削除も、デフォルトでは同じ共有ファイルに書き込みます。これは注意深く読むべき項目です。 aggrega/pluginAdd と aggrega/pluginRemove は type を受け取り、オーバーライドが送られない場合、書き込み先はこの型によって決まります。provider、governance、linter、importer のエントリは 1 つのプロジェクトのビルドを形作るため、そのプロジェクト自身の設定に書き込まれます。cli エントリはマシン全体のツールであるため、global も workspace も指定しない型 cli の追加は、このマシン上のすべてのワークスペースが解決に用いるグローバル設定ファイルにコマンドを登録します。そのコマンドは、このセッションで誰も名前を挙げていないプロジェクトも含め、マシン上のすべてのプロジェクトでトップレベルの aggrega コマンドとなり、取り消すには元に戻す操作ではなく別途の削除が必要です。ローカルに留めるには workspace: true を送信します。どちらの応答も scope を持ち、書き込まれた configFile と、それが共有ファイルかどうかを示す machineWide を含みます。後者は書き込みの解決先となったファイルから導出されます。追加は検索したレジストリにもアクセスするため、両方の軸に同時に該当します。プラグインの変更が伝えることを参照してください。
その他 2 つのプラグインリクエストは、ワークスペース内にのみ書き込みます。 aggrega/pluginSync はリクエストが指定する Plugin エンティティファイルに書き込み、aggrega/pluginGenCatalog は生成したエンティティをリクエストが指定する outputDir の下に書き込みます。どちらもリクエストが指定したワークスペース内に書き込み、絶対パスやワークスペースの外に解決される書き込み先は拒否し、他のプロジェクトからは見えません。aggrega/pluginGenCatalog はモジュールとオーバーレイを選択された場所から読み込みますが、それによって書き込み先が広がることはありません。両者は異なる規則で解決されるため、生成処理はどこでビルドしたモジュールでも読み込めますが、生成されるエンティティは必ずワークスペース内に置かれます。dryRun を指定した aggrega/pluginGenCatalog は何も書き込まず、代わりに内容を返します。
エンティティのピン留めもワークスペース内にのみ書き込み、そのソースが指定するホストに到達します。 aggrega/pin はリクエストが指定するエンティティの隣にある entity.lock(ワークスペース内のパス)に書き込み、取得したソースでワークスペースのコンテンツキャッシュを埋めます。書き込む内容は他のプロジェクトからは見えません。エンティティが指定する各リモートソース(チャートリポジトリ、Git ホスト、URL)を解決するために外部に到達し、これは Release が使用するソースに対して aggrega/resolveDependencies が持つ到達範囲と同じです。pinSources を送られた aggrega/resolveDependencies と aggrega/publishEntity は同じ手順を実行するため、それぞれピン留めするエンティティの隣にも書き込みます。したがって、ピン留めを行う公開はレジストリだけでなくワークスペースにも及びます。ピン留めを行わない公開はエンティティの隣に何も書き込みませんが、それでもそれらのホストには到達します。ロックとこの手順が記録する内容を比較するには、エンティティが書き出す各リモートソースを完全に取得する必要があるためです。
アシスタントスキルのインストールは、リクエストが global を送らない限りワークスペース内にとどまります。 aggrega/skillsInstall は、指定された各アシスタントのプロジェクトスキルフォルダーを、リクエストが指定するワークスペース内に書き込みます。そこに書き込むものは他のプロジェクトからは見えず、応答の scope は false の machineWide を持ちます。global: true の場合は、代わりにホームディレクトリの下にある各アシスタントのユーザー単位のフォルダーに書き込みます。このフォルダーはそのアシスタントがマシン上のすべてのプロジェクトで読むもので、machineWide は true になります。いずれの場合も、レジストリにもネットワークにもアクセスしません。
保存された認証情報の削除は、このマシン内に留まる操作の中で最も広い範囲に及びます。 aggrega/logout は認証情報ストアを変更します。このストアはマシン上のすべてのプロジェクトだけでなく、同じレジストリに認証する他のすべてのツールとも共有されています。そのため、セッションを通じて削除された認証情報はそれらすべてから失われ、aggrega/registryList は他のすべてのワークスペースでもそれを存在しないと報告します。応答は machineWide を含む scope を持ち、その値は常に true です。このストアには解決先となるワークスペース単位の形態がないため、送るべきオーバーライドも、リクエストがオプトインするものもありません。上記の設定の書き込みとは異なり、scope は意図的にファイルを示しません。ストアはマシンに設定されている認証情報ヘルパーや OS のキーチェーンに処理を委ねるため、削除はファイルではないものによって行われることが多く、パスを示すと、削除が必ずしも触れていない場所を指してしまうからです。
削除は認証の逆操作ではなく、クライアントはそのように提示すべきではありません。 このインターフェースは認証情報を削除しますが、取得はしません。認証情報を取り戻すには、ターミナルで aggrega login を使って再度認証する必要があります。認証情報の保存には人が入力するシークレットが必要で、このストリームを見ている人はいないためです。したがって、クライアントが提供する「ログアウト」は、ここからは一方通行です。両者を分けるのは、操作を実行している側から何かを取得する必要があるかどうかです。削除はその 1 つの値をリクエストに含みますが、認証情報の取得はそうではありません。人が関与するかどうかではありません。どちらも人が選んだものだからです。
キャッシュ内容の回収もワークスペースの外に及びます。 コンパイル済みモジュールとプラグイン記述のストアはマシン上のすべてのプロジェクトで共有されているため、aggrega/cachePrune、aggrega/cacheEvict、aggrega/cacheClear は他のプロジェクトが依存する内容を削除する可能性があります。各削除には、その由来となるクラスの reach が付き、各応答には scope.machineWideClasses が含まれます。aggrega/cacheStatus は何も変更しませんが、すべてのクラスに同じ到達範囲を付けます。回収するかどうかを判断するクライアントは、行動する前にそれを必要とするからです。
検索インデックスの更新はその逆です。 aggrega/registryUpdate は設定されたすべてのレジストリに到達しますが、書き込む内容はこのワークスペース自身に設定されたキャッシュディレクトリの下に置かれます。そのため、他のプロジェクトが解決に使うものは何も変更しません。応答の indexRoot がそのディレクトリを示します。
部分的な更新は失敗せずに応答します。 1 つのレジストリを指定したリクエストでその更新が失敗した場合は、返すべき応答がないためエラーになります。設定されたすべてのレジストリを更新するリクエストは、その一部またはすべてが失敗しても成功します。更新できたものはインデックス化されて書き込まれ、failed が残りを示し、各ホストがそれぞれのエラーを持ちます。エラーの有無ではなく failed を読んでください。
レジストリに到達できたかどうかは、メッセージの解釈ではなくキーで判断します。 失敗したホストは、レジストリに一度も到達しなかった場合(名前が解決されなかった、接続が拒否されたか開けなかった、またはセキュアな接続を確立できなかった場合)に unreachable: true を持ち、1 つのレジストリを指定したリクエストの拒否もその data に同じキーを持ちます。到達したうえで失敗したレジストリ(リストが繰り返された、またはエラーステータスが返された場合)はどちらも持たず、その error、または拒否のメッセージが、レジストリの応答内容を示します。このキーは失敗そのものから読み取られるため、このマシンのリゾルバーが失敗をどう表現するかには左右されず、レジストリに一度も到達しなかったことを失敗が示す場合にのみ設定されます。どちらとも示さない失敗、たとえばどの手順を中断したかの記録がないまま制限時間が切れた場合は、このキーなしで報告されます。到達しなかったレジストリはこのキーに基づいて示し、エラーを理由として表示してください。
コマンドラインは同じ巡回を 0 以外の終了ステータスとして報告し、読み手が誰かによってその終了ステータスの意味が変わります。 ターミナルの前にいる人にとって、それはすべての説明ではありません。aggrega registry update は、選択したレジストリのうちいくつをインデックス化したか、それぞれが何を見つけたか、どれをインデックス化しなかったか、インデックスをどこに書き込んだかを出力します。つまり、要約が何が起きたかを伝え、終了ステータスはすべてが成功したかどうかだけを伝えます。スクリプトにとっては、それがすべての説明です。このコマンドには構造化出力モードがないため、終了ステータスが利用できる唯一の機械可読な判定だからです。このため、2 つのインターフェースは同じ部分的な巡回に異なる応答をし、どちらも正しいのです。こちらは構造化された呼び出し元に failed を渡して成功し、コマンドラインは使える 1 ビットを「見落としたレジストリがあるか」に使います。
長時間の操作を監視する
ここにあるほとんどのリクエストは、すでにディスク上にあるものから即座に応答します。一部のリクエストは先に実際の作業を行い(Release の依存関係の解決、外部入力のピン留め、公開、署名、取り下げ)、その間呼び出し側は待機します。これらは作業中に何をしているかを報告し、それはリクエストごとのオプトインです。
オプトインには 2 つの手順が必要で、この順序で行います。
- ハンドシェイクで機能を宣言し、応答を待ちます。
aggrega/initializeでcapabilities.window.workDoneProgress: trueを送信します。その応答が届くまでは他に何も送信しないでください。リクエストは並行して処理されるため、ハンドシェイクの応答前に書き込まれたリクエストは、そのリクエストのためにネゴシエートするはずだったハンドシェイクと並行して実行される可能性があります。どのクライアントもすでにプロトコルに対してこの順序を守る義務があり、これはそれに依存するものがもう 1 つ増えるということです。 - リクエストの params にトークンを入れます。 報告を受けたいリクエストの params に
workDoneTokenを追加します。値は文字列または数値で自由に選べ、通知をその呼び出しに結び付けるものになります。呼び出しごとに新しいものを発行してください。
通知。 各通知は $/progress で、params.token にはトークンが設定され、params.value は 1 つのペイロードを持ちます。
value.kind | 内容 | タイミング |
|---|---|---|
begin | title — 何が行われているかを、読み手にそのまま見せられる語句で表したもの | 作業の開始時に 1 回 |
report | message — 操作自身による自らの説明の 1 行 | 操作が書き出すたびに、何回でも |
end | 種類以外には何もなし | 作業の終了時に 1 回 |
対応付けはトークンで行い、リクエスト ID では決して行いません。 通知は ID を持たず(何かへの応答ではないため)、トークンが呼び出しを指し示す唯一のものです。これは意図的です。多くのクライアントではリクエスト ID はトランスポートに属し、呼び出しを発行したコードには届きませんが、トークンはそのコードがすでに保持している値です。
report はコンパイラ自身のテキストを持ちます。 メッセージは操作が作業中に書き出した 1 行で、前後の空白が除去される以外は何も変更されずに渡されます(言い換えも要約も再構成もされません)。操作が空のまま書き出した行は、空のメッセージとして報告されるのではなく破棄されます。したがって、クライアントは与えられたものをそのまま表示します。これはレスポンス自身の診断と同じ性質です。1 つの条件は、いくつのサーフェスが報告しても 1 つの文言を保ちます。
操作が待機するステップも report です。 操作が待機するステップ — レジストリの読み取り、アーティファクトの取得、プラグインのコンパイル — に入ると、report がそのステップ名を、コマンドラインが同じステップについてスピナーの横に表示するのと同じ言葉で伝えます。報告されるのは、begin と end の間に入ったステップだけです。
出力の 1 行が 1 つの report です。 一度に複数行を書き出す操作は行ごとに 1 つの通知を生成し、操作が分割して書き出す行は完成した時点で報告されます。そのため、メッセージが文の途中で切れることはありません。
割合もパーセンテージもありませんが、それは対応待ちの欠落ではありません。 ここで報告する操作は、作業開始時にサイズがわからない集合を処理します(解決がたどる参照の数、公開でアップロードされるレイヤーの数など)。そのため、どのような割合も作り事になります。不確定のインジケーターを表示し、最新の message を表示してください。
フレームはレスポンスの前に届き、後には決して届きません。 begin は作業が実際に開始された時点で届くため、params で拒否されたリクエスト(絶対パス、必須フィールドの欠落など)は通知を一切生成せず、エラーのみを返します。end はレスポンスの前に届き、操作が成功したかどうかは end で繰り返されるのではなくレスポンスに示されます。
作業の停止は別の通知です。 リクエストを送信したときの ID を付けて $/cancelRequest を送信します。トークンはキャンセルには関与せず、キャンセルしてもすでに送信されたフレームは取り消されません。
報告するリクエストと、それ以外に期待すること
報告するのは正確に次のものです: aggrega/resolveDependencies、aggrega/pin、aggrega/publishEntity、aggrega/publishArtifact、aggrega/signArtifacts、aggrega/deprecateArtifact。
これらのすべてに 2 つのことが当てはまり、どちらもリストに載っている理由です。代わりにレジストリまたはリモート URL にアクセスするため、所要時間はマシン外の何かによって決まります。そして、進行に合わせてすでに自らの説明を書き出していることです(ターミナルを見ている人が読む説明です)。したがって、報告では通信用に別途作成された説明ではなく、その同じ説明が渡され、それを生成するために操作の動作を何も変える必要はありませんでした。
その他のリクエストはすべてトークンを受け付け、何も送信しません。 トークンを送信してもエラーにはならず無害です。受け付けられ、通知は届かず、応答はトークンなしで得られたはずの応答とまったく同じです。そのため、クライアントは任意のリクエストにトークンを付け、何も届かなければ単に何も表示しなくてかまいません。
🔴 沈黙を「これは即時に終わる」と解釈しないでください。 残りのほとんどは確かにすでにディスク上にあるものから応答します(検証、ホバー、補完、グラフ、キャッシュの一覧、設定の読み取り)。しかし、すべてではありません。レジストリインデックスの更新、プラグインの追加、公開前チェック、ワークスペースが読み取れるドキュメントを持たないマシンでのコードの初回展開はいずれもレジストリにアクセスし、Release のコンパイルは実際の作業です。これらは必要なだけ時間がかかり、現時点では何も報告しません。待つつもりのあるリクエストには不確定のインジケーターを表示し、通知は作業が進行中であることを知らせるものとしてではなく、利用可能なときに得られる詳細として扱ってください。
2 つの拒否
どちらも invalid-params エラーで、どちらも何をすべきかを示します。黙って何もしないトークンでは、決して来ないストリームを待ち続けることになるためです。
window.workDoneProgress機能を宣言していないセッションからのトークンは拒否され、宣言すべき機能が示されます。ハンドシェイクで宣言するか、トークンを省いてください。- 文字列でも数値でもないトークンは拒否され、2 つの形式が示されます。トークンがない場合や明示的な
nullは拒否されません。どちらも報告を求めていないことを意味します。
ロックファイルの認識
デーモンは aggrega/irGraph のたびに、そのリクエストが指定した Release に照らしてロックファイルのドリフトを検査し、ドリフトをブロックしない警告として表示します。警告には、その Release を含むロックファイルを書き直すコマンドが、リクエストが送ったとおりの表記で示されます。つまり aggrega pull --release の後に送信した release を続けたもので、これはワークスペースルートのターミナルで書く形です。aggrega/irGraph はロックファイルが存在することを必要とします。起動時の個別の検査はありません。リクエストはどの Release についてのものかを示すため、判定はあらかじめ選んだ 1 つの Release について一度だけ行うのではなく、問い合わせがあった時点でその Release について計算されます。
ドリフト警告は、そのロックファイルがなくなると消えます。 警告は発生元のロックファイルに対して公開されます。存在しなくなったロックファイルにはドリフトしうるピンが残っておらず、警告が示すコマンドは古いファイルを修復するのではなく新しいファイルを書き込むことになります。そのため、ロックファイルが見つからないことを検出したリクエストはすべて、ロックファイル不在エラーで拒否する前に警告を取り下げます。対象は aggrega/irGraph、aggrega/releaseClosure、aggrega/build、aggrega/buildPreview、グラフノードについて問い合わせた aggrega/attachCandidates と aggrega/attachmentContainer、そして aggrega/connectionAtPosition です。取り下げは、拒否に先立ち、そのロックファイルに対する空のリストを持つ aggrega/publishDiagnostics 通知として届きます。取り下げはこれらのリクエストのうち最初に削除を知ったものから送られるため、削除を報告してからその Release について何かを問い合わせたクライアントは、特にグラフを要求しなくても警告が消去されます。まだ存在し、まだドリフトしているロックファイルは、これらのどのリクエストを経ても警告を保持します。ロックファイルを指定した aggrega/invalidate は、デーモンがそのロックファイルについて保持している情報を破棄しますが、何も送信しません。クライアントに伝えるのはその後に続くリクエストです。また、デーモンが調べることすらできないロックファイル(たとえば、ディレクトリの読み取りが許可されていないもの)は何も取り下げません。まだ存在している可能性があり、警告がまだ正しい可能性があるためです。
aggrega/build と aggrega/buildPreview もロックファイルを必要とし、警告にとどめずに Release をロックファイルに従わせます。 これらはアーティファクトを出力するサーフェスの姿勢でレンダリングするため、Release の解決結果と一致しなくなったロックファイルは、検査であれば警告にとどまるところで、これらを停止させます。ロックファイルのない Release はロックファイル不在エラーで拒否されます。例外は、autoPull フィールドで先に依存関係の解決を求めるビルドです。そのビルドはロックファイルを書き込んでから、書き込んだ内容に対してレンダリングします。この方法で生成されたロックファイルが二度目のドリフト検査を受けることはありません。それを書き込んだ解決処理が書き込む前に同じ検査を実行しており、その検査が拒否するロックファイルは書き込まないためです。
ロックファイルが存在していてもプラグインのダイジェストを記録していない場合はグラフを止めませんが、ロックファイルが存在しない場合は止めます。 これらは 2 つの別の状態であり、拒否するのは後者だけです。aggrega/irGraph は解決したバイト列を記録済みのダイジェストに従わせません。検証できないピンは拒否されずに報告され、グラフは指摘を Problems パネルに表示したうえで描画されます。グラフの描画を拒むエディタは読み手に何も残しませんが、報告であれば対処の手がかりが残るためです。それ以外の場面でもプラグインは実行され、そのバイト列を誰も検査していないことを示す警告が出ます。aggrega/irGraph が拒否するのはロックファイルの不在です。何かを解決する前に停止し、探したロックファイルと Release を示すロックファイル不在エラーで応答します。そのため、クライアントは aggrega pull --release <release> を直接提示することも、その Release について aggrega/resolveDependencies を送信してセッションを離れずにロックファイルを書き込むこともできます。この 2 つを区別することは重要です。描画されたグラフは読み手がその後の推論の拠り所とする図であり、誰も検査していないバイト列から作られたグラフも、検査済みのものとまったく同じように描画され、指摘は読み手が見ていない場所に置かれるからです。したがって、グラフはその背後のバイト列に対する判定ではありません。Release を記録済みのダイジェストに従わせるサーフェスは aggrega/build と aggrega/buildPreview であり、検査が報告にとどまるところで停止します。
aggrega/validate は、リクエストが Release を指定した場合、その Release のロックファイルからピンと非推奨の通知だけを読み取ります。単一のエンティティとして検査するカタログエンティティについては、コマンドラインと同様にロックファイルを読みません。 実行するプラグインを記録済みのダイジェストに従わせることはなく、変換プラグインのアタッチメントセットをロックファイルから再構築することもありません。目の前にある現在のワークスペース設定に対して検証します。これは、設定を編集している最中にエディタが行う必要があることです。aggrega validate と aggrega build はその両方を行い、コミット済みのワークスペースに対する判定の権威あるサーフェスであり続けます。
その非推奨通知は、撤回が記録される両方の場所を対象とします。 ピン留めされた参照に対するマーカーはロックファイルにあります。受理または拒否の判定を返すロールでアタッチされたプラグイン(ir-verdict または render-verdict の plugins.governance アタッチメント、あるいは plugins.linter アタッチメント)に対するマーカーは、その隣にあるプラグイン信頼記録にあります。そのため検証は両方を読み、撤回された各参照と撤回された各プラグインを、aggrega build が出力するのと同じ文言で、Aggregate の先頭に警告として示します。通知によって判定が変わることはありません。存在するものの読み取れない信頼記録は、何も記録していない記録として読まれるのではなく、検証の代わりにエラーとして報告されます。aggrega/releaseClosure は同じ集合を deprecations で報告します。
Release のロックファイルの場所
Release を示す応答はすべてそのロックファイルも示すため、クライアントがパスを導き出す必要はありません。 aggrega/activeRelease は release の隣に lockfile として、aggrega/releaseCandidates は releases の隣に lockfiles マップとして、ロックファイル不在エラーは data 内の lockfile としてこれを持ちます。いずれも aggrega pull --release <release> が書き込み、aggrega build が読み取るファイルであり、上記の各リクエストが検査するファイルです。そのため、書き込み、書き直し、削除を検知するために Release のロックファイルを監視するクライアントは、デーモンが意図するファイルを監視することになります。ロックファイルは Release の隣に置かれ、Release の名前の .yaml または .yml 拡張子を .lock に置き換えた名前を持ちます。それ以外の拡張子を持つ Release は名前全体を保持するため、release.rel のロックファイルは release.rel.lock です。この説明からパスを組み立てるのではなく応答からパスを読み取れば、両者が食い違うことはありません。
レンダリングが要求する外部参照
レンダリングは、リモート URL からのコンテンツを要求することがあります。たとえば、リモート参照を含むチャートの values スキーマです。情報を伝えることだけを求めたリクエストに応じてこのデーモンが実行するすべてのレンダリングでは、外部入力が凍結されます。 Release の lockfile が固定している参照は、コンテンツアドレス指定ストアから提供されます。これはフェッチではなく、すでにディスク上にあるコンテンツの読み取りであり、そのバイト列は提供される前に lockfile の記録と照合されます。そのため、ここでのレンダリングはビルドと同じものを見て、ビルドが発する勧告を同じように発します。lockfile が固定していない参照は、フェッチされずに拒否されます。それを取得するにはネットワークに到達し、ストアに blob を書き込む必要がありますが、セッションは情報を伝えることだけを求めたリクエストに対してそのどちらも行いません。これは レジストリへの到達と書き込み にある規則をレンダリングの側から読んだものであり、そのようなレンダリングにどのような経路で到達したかにかかわらず成り立ちます。
固定するために存在するリクエストは例外であり、それはレジストリの規則がすでに持つ例外と同じものです。 aggrega/resolveDependencies は取得を求められているため、この Release がどの参照を使用するかを見つけるために実行するレンダリングはネットワークに到達し、固定したものを書き込みます。これにより、その結果はレポートではなく lockfile になります。グラフやビルドのリクエストが自身のために実行するレンダリングは、そのいずれも行いません。
先に解決するよう求められたビルドは、まさにそのレンダリングから応答されるため、Release のレンダリングは一度だけです。 解決の処理は、書き込んだばかりの固定に対し、ビルドが実行するゲートのもとで、ビルドの対象をすでにレンダリングしています。そのためビルドは 2 回目のレンダリングを行わずにそのレンダリングを提示し、取得はビルドではなく引き続き解決に属します。このように使われるのは完了したレンダリングだけです。解決が依存関係を固定したものの外部参照の発見を完了できなかった場合、ビルドは実際に書き込まれた固定に対して自らレンダリングし、固定されていない参照は、何も解決しなかったビルドの場合とまったく同じように拒否されてそこで報告されます。
拒否は吸収されずに報告されます。結果のどこにも、どの参照が欠けていたかは示されないためです。このバイナリが同梱する Providers では、参照を要求した provider が拒否を返すため、拒否された参照に到達したレンダリングは完了しません。そのため、拒否された各参照は aggrega-build レイヤー上の個別のエントリとして届き、その参照と、それを固定するコマンド aggrega pull --release <release>、またはセッションを離れずに同じ作業を行う aggrega/resolveDependencies を示します。これらのエントリは拒否ではなく勧告です。グラフは引き続き返され、上記のドリフト警告と同じ扱いです。また、レンダリングが要求した参照は作成者が書いたどのキーも示さないため、ファイル先頭の Aggregate に帰属されます。これらはレンダリング自身の勧告と同じパブリケーションで届き、そのパブリケーションはレイヤー全体を置き換えるため、後で固定した参照は、何かがそれをクリアしなくても報告されなくなります。すべてが固定されたレンダリングは、これについて何も示しません。各エントリの形式については 診断エントリが持つもの を参照してください。
aggrega/irGraph では、これはレンダリング段階がそもそも実行されるかどうかに依存します。 グラフのリクエストは、--build-on-inspect、またはそれが上書きする serve.build_on_inspect キーが有効にしない限り、レンダリングをスキップします。この設定がオフの場合、外部参照を要求するものはなく、拒否するものもありません。これをオンにすることで、レンダリング自身の勧告とこれらのエントリの両方がエディターセッションに届くようになります。
セッションがコマンドラインでの同じ凍結と異なる点。 aggrega build もドライランでは外部入力を凍結し、固定されていない参照はどちらの環境でも同じように振る舞います。その参照を示す検出結果として報告され、参照を要求した provider が拒否を返すため、レンダリングはその後停止します。異なるのは再フェッチです。コマンドラインでは、保存されたコピーが失われた固定済みの参照は、記録されたダイジェストによって再びフェッチされます。グラフやビルドのリクエストに応答するレンダリングはネットワークに到達しないため何も再フェッチせず、ストアがもはや保持していない固定済みの参照を取りに戻ることはできません。また、そのような参照は、lockfile が固定していないものを示す上記の拒否には含まれません。それを回復するのは、セッションに固定を求めることです。上記のリクエストはネットワークに到達し、欠けているバイト列を戻します。固定によって何がフェッチされ記録されるかについては aggrega pull を参照してください。
拒否された実行がそれでも伝えること
拒否したリクエストはエラーエンベロープで応答し、実行がすでに得ていた検出結果はそのエンベロープの中には含まれません。エンベロープには結果本体がまったく含まれないためです。検出結果は、完了した実行の場合と同じ経路で届きます。すなわち、What a diagnostic entry carries で説明する、aggrega-build レイヤー上の診断パブリケーションとして届きます。したがって、拒否を処理するクライアントは、何を変更すべきかをエンベロープから読み取り、実行が何を見つけたかを問題表示面から読み取ります。どちらも他方の代わりにはなりません。レンダリング中に発生した拒否は、作成者が書いた内容についての検出結果でもある唯一の拒否であるため、次のセクションで説明するとおり、両方に届きます。
そのパブリケーションは、実行が最後まで到達したかどうかにかかわらず行われます。 途中で停止した実行も、停止した地点より前のすべてを検出しており、その検出結果を失った読者はそれを見るために再度実行しなければならなくなります。そのため、アドバイザリは実行が到達したところまでの内容から公開され、拒否はその後に返されます。これは同じ忠実度の同じ集合であり、同じ作成キーに位置付けられます。拒否によって検出結果が一文に格下げされることはありません。辞退された外部参照も、同じ理由と同じ経路で、同じパブリケーションに含まれて届きます。
その範囲を決めるのは、レイヤーが運べる内容ではなく、実行がどこまで進んだかです。 コンパイラの開始前に実行されるチェックのいずれかによる拒否(Release のクロージャを解決できなかった、Manifest がある型をそれを実装していない recipe にマッピングしている、lockfile が Release の解決結果とすでに一致しない、キャッシュ内のピン留めされたエントリがそれについて記録されたダイジェストとすでに一致せず、ピン留めされたバイトを保持するカタログディレクトリもない)には、公開すべきアドバイザリがありません。まだ何も発生していないためです。その場合、レイヤーは古い内容ではなく何も含みません。また、ドキュメントを特定するところまで進まなかった実行は何も公開せず、問題表示面にすでにあるものを、何も知り得なかったエントリを消去することなく、そのままの状態で残します。
レンダリング中に発生した拒否
コンパイラがレンダリング中に拒否する Release(Component が宣言していないスロットを指定する Workload、失敗するアサーション、評価できないテンプレート、提供すべきものに満たない realization)は、それをレンダリングするすべてのリクエストで、それが指し示す場所に、コンパイラ自身の言葉で報告されます: aggrega/build、aggrega/buildPreview、およびレンダリングステージを有効にした aggrega/irGraph です。応答は -32603 コードを持つエラーエンベロープで、その message は、同じビルドに対してコマンドラインが出力するのと同じ言葉による、その下のすべての原因を含む拒否です。つまり、レンダリング中のノード、次にその中で拒否したもの、そして各原因がそれが説明する原因の後に続きます。拒否が登録済みの条件を指定する場合は、条件を指定するすべての拒否と同様に、先頭にその条件の短縮コードが付きます。その data は、拒否が指し示すドキュメントを file として、そこでのキーの範囲を line、column、end_line、end_column として、条件の code と shortCode と並べて示します。キーを指定しない拒否、またはドキュメントが保持しないキーを指定する拒否は file のみを含み、どのドキュメントも指し示さない拒否は Release の Aggregate を示します。
同じ拒否は、aggrega-build レイヤー上で、そのドキュメントの、そのキーに公開されます。 これは重大度 error のエントリで、拒否自身の keyPath と、先頭の短縮コードを除いたエンベロープの message を含み、拒否が登録済みの条件を指定する場合はその条件の code、shortCode、codeDescription を含みます。そこでは短縮コードは独自のフィールドで運ばれます。このエントリは、実行が停止する前に発生したアドバイザリを運ぶ単一のパブリケーションに含まれるため、それらと同様にレイヤーを置き換えます。Release の次のレンダリング実行ではこのエントリを含まないレイヤーが公開され、それが置かれていたドキュメントは空として公開されます。これにより、問題表示面からこのエントリが消去されます。
拒否が指し示す場所は、拒否自身が指定するものであり、それより細かくはなりません。 Workload のチェックはテンプレートが生成したドキュメントを判定し、テンプレートは作成者が書いていない行(ループ、条件、ファイルやライブラリから取り込んだテキスト)を書き出すことがあるため、レンダリングされた Workload の行は Recipe の行に対応しません。したがって、Workload に関する拒否は Recipe の workload キーに置かれ、レンダリングされたドキュメント内で指定するパスはそのメッセージ内に残ります。失敗するアサーションは、それを宣言する Recipe または FeatureRecipe の assertions 配下にある自身のキーに置かれます。Component または Feature が宣言するアサーションは、指定できるドキュメントが手元にそろう前に発生するため、Aggregate の kind: キーに置かれます。ドキュメントを指定するもののキーを指定しないステップからの拒否は、そのドキュメントの kind: キーに置かれます。
複数の検出結果をまとめた拒否は、検出結果ごとに公開されます。 レンダリングの基になるグラフの合成は、見つけたすべての違反を 1 つの拒否にまとめて拒否します(何も応答しないターゲットを指定するエントリ、1 つの component の 2 つの接続に同じエイリアスが与えられている場合など)。コマンドラインはそれぞれを独自の見出しの下に個別の診断として出力します。ここでは、それぞれが aggrega-build レイヤー上の個別のエントリとなり、その検出結果が指定するドキュメントとキーに(Release が書いた場合は Release、Aggregate が書いた場合は Aggregate に)、独自の言葉と独自のコードで置かれます。応答の message はすべての検出結果を含み、その data は最初の検出結果が指し示す場所を示します。
作成者が機密と宣言した値は、ここでもコマンドラインとまったく同じように伏せられます。 拒否のテキストはコンパイラが発生させたテキストであり、この面でそれを言い換えるものはありません。コンパイラは拒否を発生させる時点で宣言された値を伏せ(代わりに <redacted> となります)、そのためこの応答、このエントリ、ターミナルは同じ言葉でそれを伝えます。その方法と、どの拒否がその対象外となるかは、宣言された値について拒否が述べることで説明しています。
レンダリングの前に実行されるゲートからの拒否は、これには当たりません。 上に挙げたチェックは、拒否された実行がそれでも伝えることで説明するとおりに応答します。Component または Feature が宣言するアサーションと、合成されたグラフに対する拒否は、その中間に位置します。いずれもレンダリングの前に、Release のグラフを解決するすべてのリクエストによって発生するため、aggrega/irGraph はレンダリングステージが無効の場合でも、上記のとおり応答し公開します。グラフノードについて問い合わせた aggrega/releaseClosure、aggrega/attachCandidates、aggrega/attachmentContainer、および aggrega/connectionAtPosition は、同じエンベロープで応答し、何も公開しません。これらは問題表示面を持たないためです。
エラーコード
レスポンスは標準の JSON-RPC エラーコードに加え、1xxx 帯のアプリケーションレベルの範囲を使用します。エディタクライアントはメッセージを解析せずにコードで分岐できます。
1001file-not-validated — デーモンは、現時点のそのファイルについて、リクエストが応答の基にできるものを何も保持していません。つまり、そのファイルの解析結果がないか、aggrega/diagnosticsの場合は、そのファイルの解析結果がないか、デーモンが現在保持しているテキストに対する検証の応答となるものをそのファイルについて何も保持していません。そのファイルについてaggrega/validateを送信し、再度問い合わせてください。1003lockfile-absent — リクエストが指定した Release にロックファイルがなく、要求された操作にはロックファイルが必要です。1004entity-not-resolvable — 名前がどのカタログ階層のエンティティにも、リクエストが指定した Release 内のエンティティにも一致しませんでした。または、名前として送られたレジストリ参照をエンティティとして読み取れず、その理由を示す条件がメッセージに記されています。または、Release のロックファイルがワークスペース外へ通じるリンクであり、読み取られる前に拒否されました。この場合、dataはロックファイルと Release を示し、メッセージはその条件の短縮コードE0321で始まります。ワークスペースの境界を参照してください。1005shutting-down — デーモンはシャットダウン通知の後で処理を終えつつあり、新しいリクエストを拒否します。同じサブプロセスに対して再試行しないでください。1006validation-in-flight — そのファイルの検証が実行中で、待機中のリクエストが許容した時間内に完了しませんでした。何も送信せず、少し後に再度問い合わせてください。
1002 は割り当てられておらず、コードを必要とする次の条件のために空いています。
file-not-validated と validation-in-flight は正反対の状態を報告し、それぞれが求める対応も正反対です。 file-not-validated は、現時点のそのファイルについて、リクエストが応答の基にできるものをデーモンが何も保持していないことを意味します。つまり、そのファイルの解析結果がないか、aggrega/diagnostics の場合は、そのファイルの解析結果がないか、デーモンが現在保持しているテキストに対する検証の応答となるものをそのファイルについて何も保持していない状態です。aggrega/validate を送信し、再度問い合わせてください。途中でキャンセルされた検証は、ファイルをこの状態のままにします。その検証は何も保存せず、以前の検証が別のテキストについて見つけたものは、デーモンが現在保持しているテキストに対する応答ではないからです。以前の応答は、テキストがその応答の検査したものである間は引き続き有効です。デーモンが自らディスクから読み込んだファイルについてプッシュする検出結果(ずれが生じたロックファイル、読み込めない Release)は、手元のテキストの検証ではないため、このリクエストへの応答にもなりません。異なるテキストに対する 2 つの検証を立て続けに送信した場合も、デーモンが保持したテキストの検証が先に完了したときには、この状態になることがあります。そのテキストは検査済みであるにもかかわらずリクエストは拒否され、もう一度検証すれば応答が得られます。これがファイルではなく解析結果の観点で述べられているのは、どのパーサも読まないバッファがまさにその状態にあるためです。検証は実行されて見つけたものを報告しましたが、応答の基になる解析結果は依然としてありません。validation-in-flight は、そのファイルの検証が実行中で、待機中のリクエストが許容した時間内に完了しなかったことを意味します。何も送信せず、少し後に再度問い合わせてください。必要な状態はすでに用意されつつあり、2 回目の検証は作業を増やすだけだからです。この 2 つを同じ条件として扱うと、検証を送るべきでない場面でクライアントが検証を送ることになります。2 つの帯域はクライアントにとって異なる意味を持ちます。1xxx のコードはユーザーが対処できるワークスペースの状態(ファイルを検証する、ロックファイルを生成する)を示し、invalid-params のような標準コードは不正な形式のリクエストを示し、それはユーザーではなくクライアントが修正します。存在するものの不正な形式の release 値(絶対パス、またはワークスペースルートの外に解決されるもの)は 2 番目の帯域に該当します。ユーザーが修復すべき状態にあるのはワークスペースではなく、リクエストです。release の省略はどちらの帯域にも該当しません。エラーではまったくないからです。これは Live validation で説明する 2 つの応答のうち、範囲の狭いほうを選択します。
エラーは data オブジェクトを持つことがあり、その中の各キーはただ 1 つのものだけを示します。file は失敗の対象となるソースドキュメントです。検証中のドキュメント、読み込みに失敗した Release、何にも解決されなかった名前を宣言しているワークスペースドキュメント、またはレンダリング中に発生した拒否が指すドキュメントであり、付随する line と column はその中の位置を示します。この 2 つ自体は省略可能で、ドキュメント全体に関する失敗は file のみを持ちます。lockfile はロックファイルです。release はエラーの対象となる Release で、リクエストが指定したとおりに表記されるため、クライアントはメッセージから解析し直すことなく aggrega pull --release <release> を組み立てられます。unreachable は、拒否されたリクエストが指定したレジストリに到達できなかったことを示します。1 つのレジストリを指定したインデックス更新が拒否された場合にこれが含まれ、失敗そのものから読み取られます。応答したレジストリの場合は含まれません。どのキーも省略可能で、デーモンがその値を把握している場合にのみ存在します。あるキーが別のキーの代わりになることはないため、キーが指すものが隣のコードに左右されることはありません。
data 内の code と shortCode は、拒否が報告する条件を示します。 登録済みの条件を報告するすべての拒否に、数値コードにかかわらず含まれます。プログラムが分岐に使う説明的なコードと、人が引用する短縮コードであり、同じ条件について診断エントリが持つものと同じ 2 つの識別子が同じ名前で含まれ、すべての条件の表に掲載されています。分岐には code を使用してください。数値コードはリクエストの状態を示し、多くの条件で同じ値のままです。カタログのリンクが外部へ通じるために拒否されたビルドも、名前が何にも解決されないために拒否されたビルドも、どちらも 1004 です。また、メッセージは言い回しが変わりうる文章であるため、どちらも条件を区別しません。invalid-params もそうした共有コードの 1 つです。設定ファイルがワークスペースの外へ通じているワークスペースを指定したリクエストもこれを受け取り、その場合 read-leads-out-of-workspace は、問題がリクエストではなく、人が修復するワークスペースの構成にあることを示します。登録済みの条件を報告しない拒否はどちらのキーも持たず、2 つは必ず揃って存在するか、どちらも存在しないかのいずれかです。条件を示す拒否のメッセージは短縮コードで 1 回だけ始まり(E0321: …)、これがそうした拒否のすべてで読み手が目にする形式です。メッセージがすでにコードを含む角括弧の見出しで始まっている拒否(読み込みが拒否したカタログドキュメントの 1 行レポート)には、重ねて付けられません。
ワークスペースの Release カスケードがどのように実行されたかの説明は、エラーではなく aggrega/activeRelease の応答の trace フィールドで伝えられます。Release を指していないワークスペースは、失敗したリクエストではなく通常の状態だからです。これは人が読むために書かれた診断用の文章であり、解析するための構造ではありません。 そのまま表示してください(ログに書き出す、またはユーザーが開けるパネルに表示する)。パターンを照合したり、値を抜き出したり、使われているラベルで分岐したりしないでください。文言、レイアウト、ラベルはカスケード自体に追随し、カスケードが変わるたびに変わります。テキストをそのまま渡すクライアントはそうした変更があっても動作し続けますが、その形を学習したクライアントは壊れます。
関連項目
- ../schema/other/serve-wire.md — このプロトコルがやり取りするメッセージの形を、公開されたスキーマから生成したものです。各メソッドのパラメータオブジェクト、各結果、各通知のペイロードをフィールドごとに示します。
- ./aggrega-build.md — build コマンドです。そのコンパイラパイプライン、ゲート、依存関係の解決を
aggrega/buildも同様に実行するため、2 つのインターフェースは 2 つではなく 1 つの出力ツリーを書き込みます。 - ./aggrega-version.md — エディタ拡張機能がデーモンの互換性を確認するために使う version コマンドです。
- ./aggrega-pull.md — デーモンのドリフト検出機能が読み取るロックファイルです。
- ./aggrega-lint.md — デーモンが要求に応じて報告し、
serve.lint_on_validateが有効な場合はすべての検証時にも報告する公開の慣例です。
概要
aggrega serve [flags]説明
Run the Aggrega compiler as a long-running service. The daemonreads JSON-RPC 2.0 messages from stdin and writes responses to stdoutunder the aggrega/ method namespace. State (parsed YAML, diagnostics,resolved catalog) holds across requests so IDE clients can issue manycheap operations without re-paying per-invocation startup cost.
The daemon resolves its workspace root through the same path everyaggrega command uses: --workspace-root when set (used as-is, validatedto exist as a directory), otherwise discovery walking upward from thecurrent working directory. A directory anchors the workspace when itholds a .aggrega-config.yaml carrying a workspace: block, or — as afallback — any of .aggrega/, aggregate*.yaml, release*.yaml,manifest*.yaml.
Configuration is the cascade composition of the .aggrega-config.yamlfiles from the workspace root down to the working directory (neareroverrides farther), beneath which the global config file — the one--config names, else the one the AGGREGA_CONFIG environment variablenames, else the default location when a file is there — and thebuilt-in defaults apply.
The daemon honors the aggrega/shutdown JSON-RPC notification for acooperative cross-platform exit: the daemon completes the in-flighthandler if any, refuses new requests with code 1005, and exitscleanly within a 2-second drain budget.
Asking the process itself to stop — an interrupt from the terminal, ora termination request from a supervisor or container runtime — takesthe same path on the same terms: the first request drains the daemonand it exits cleanly, and a second ends the process at once.フラグ
| フラグ | デフォルト | 説明 |
|---|---|---|
--build-on-inspect | false | IR グラフの検査中にアーティファクトのレンダリングステージを実行し、aggrega build がレンダリング中に発するアドバイザリもエディタの問題として表示されるようにします。ビルドを停止させるチェックは一切追加しません。ディスクには何も書き込まれません。レンダリングされたアーティファクトも、出力ディレクトリも、ロックファイルも書き込まれません。デフォルトでは無効で、同様のアドバイザリを発しない aggrega inspect と同じ動作です。設定した場合、serve.build_on_inspect 設定キーより優先されます。 |