aggrega serve
aggrega serve führt Aggrega als langlebigen Compiler-as-Service-Daemon für die IDE-Integration aus. Er spricht JSON-RPC 2.0 über stdin/stdout und hält den Zustand von Catalog-Resolver, Parse-Cache und Diagnosen über Anfragen hinweg, sodass Editor-Operationen Rückmeldung in weniger als einer Sekunde erhalten, statt bei jedem Tastendruck die vollen Kosten für das Laden des Katalogs zu tragen.
Der Daemon wird normalerweise von einer Editor-Erweiterung als Unterprozess gestartet und nicht von Hand ausgeführt. Eine VS-Code-Erweiterung ist der Referenz-Client; andere Editoren können sich integrieren, indem sie dasselbe Protokoll sprechen.
Das Protokoll
Das Übertragungsprotokoll ist JSON-RPC 2.0 mit Content-Length-Framing im Methoden-Namespace aggrega/. Es ist bewusst nicht das Language Server Protocol — Aggrega hat Domänenoperationen (eine Abfrage des IR-Graphen, ein Signal zur Cache-Invalidierung), für die LSP keine Entsprechung hat. Eine Editor-Erweiterung übersetzt zwischen den LSP-Anfragen des Editors und diesen aggrega/*-Methoden; Positions-, Bereichs- und Location-Werte in LSP-Form werden wiederverwendet, wo sie passen.
Zwei Methoden behalten ihre protokollüblichen $/-Namen, statt in den Namespace aggrega/ umbenannt zu werden, weil beide Transportbelange sind, die keine Aggrega-Bedeutung tragen, und ein Client, der das Protokoll bereits spricht, sie ohne Zusätze verarbeitet: $/cancelRequest, das eine Anfrage beendet, auf die der Client keine Antwort mehr möchte, und $/progress, über das der Daemon einen langen Vorgang meldet, während er läuft. Beide werden unten beschrieben.
🔴 Jede der folgenden Anfragen enthält workspaceRoot, den absoluten Pfad des Workspace, auf den sie wirkt, und dies wird nicht für jede Methode wiederholt. Drei enthalten ihn nicht, weil ihr Gegenstand kein Workspace ist: aggrega/initialize, aggrega/getSchema und aggrega/scaffoldEntity — außer dass aggrega/scaffoldEntity einen nennt, wenn es ein ausführbares Beispiel schreibt oder auflistet. Unter Jede Anfrage benennt den Workspace, auf den sie sich bezieht steht, was eine Anfrage erhält, die keinen benennt, und unter Den Workspace angeben, für den Diagnosen gepusht werden sollen, wohin gepushte Diagnosen gehen.
Die Strukturen Feld für Feld sind als Schema veröffentlicht, und die Wire-Format-Referenz ist der Ort, an dem Sie sie nachlesen. Diese Seite gibt das Parameterobjekt jeder Methode, jedes Ergebnis und jede Benachrichtigungs-Payload an — jedes Feld mit seinem Typ, ob es erforderlich ist und was es enthält — zusammen mit drei Eigenschaften, die für die gesamte Oberfläche statt pro Methode gelten: die zwei Felder, die jede Anfrage über die von ihrer eigenen Methode deklarierten hinaus zulässt, nämlich workspaceRoot oben und das workDoneToken aus Einen langen Vorgang beobachten; dass ein Params-Objekt mit einem Schlüssel, den seine Methode nicht akzeptiert, abgelehnt wird, wobei die akzeptierte Menge in der Ablehnung genannt wird; und wo eine fehlende Collection als null statt als leere auf der Leitung ankommt. Sie wird aus diesem Schema generiert und ändert sich daher, wenn sich der Vertrag ändert.
Diese Seite enthält das Protokoll, jene enthält die Strukturen, und beide sind dazu gedacht, zusammen gelesen zu werden. Hier: das Framing, wofür jede Methode da ist, wie weit sie reicht, was sie schreibt, welche Ablehnungen sie auslöst und warum, die Fehlercodes und was jeweils zu tun ist. Dort: was auf die Leitung gehört, Schlüssel für Schlüssel. Die folgende Liste nennt daher jede Methode und sagt, was es bedeutet, sie aufzurufen, und die Feldliste für die Anfrage, die Sie zusammenstellen, steht in der Referenz daneben.
Anfragen:
aggrega/initialize— Handshake. Handelt die Positionskodierung aus (der Server bevorzugt UTF-8, dann UTF-16, dann UTF-32, und verwendet standardmäßig UTF-16), empfängt den Workspace, den Sie für gepushte Diagnosen deklarieren, und meldet die Wurzel dieses Workspace, die Konfigurationsebene, aus der seine Einstellungen aufgelöst wurden, und den Marker, der sie aufgelöst hat. Die Antwort enthält außerdemversion, die Version der antwortenden Binärdatei: denselben Wert, denaggrega versionfür diese Binärdatei meldet. Sie beschreibt den laufenden Prozess; sobald also die Datei, aus der der Daemon gestartet wurde, ersetzt worden ist — etwa durch einen Neubau unter demselben Pfad —, nenntversionweiterhin den laufenden Daemon, während eine Abfrage der Datei deren Ersatz nennt; lesen Sie den Wert hier, wenn die Frage lautet, mit welcher Version Sie sprechen.workspaceRootist optional und deklariert einen Workspace, statt auf ihn zu wirken — siehe Den Workspace angeben, für den Diagnosen gepusht werden sollen. Senden Siecapabilities.window.workDoneProgress: true, um anzugeben, dass Ihr Client Fortschrittsbenachrichtigungen verarbeiten kann;capabilities.workDoneProgressin der Antwort gibt dies wieder, und das Feld fehlt bei einem Client, der nichts deklariert hat. Siehe Einen langen Vorgang beobachten.aggrega/validate— validiert den Inhalt einer Datei; gibt Diagnosen zurück.releaseist ein Pfad relativ zur Workspace-Wurzel, der das Release nennt, gegen das validiert werden soll — derselbe Wert, denaggrega/irGraphannimmt, und derselbe Wert, denaggrega build --releaseannimmt, wenn es von der Wurzel aus ausgeführt wird. Er ist optional und bestimmt, wie weit die Antwort reicht: Nennen Sie ein Release, laufen die Prüfungen, die eines benötigen, gegen dieses — eine Katalogentität wird als einzelne Entität in den Begriffen dieses Release geprüft, jedes andere Dokument gegen die Abhängigkeitshülle dieses Release; lassen Sie ihn weg, deckt die Antwort ab, woran das Dokument für sich allein gemessen werden kann, und enthältchecked, um das anzuzeigen. Ein Wert, der vorhanden, aber fehlerhaft ist, wird in beiden Fällen abgelehnt — ein absoluter Pfad oder einer, der außerhalb der Workspace-Wurzel aufgelöst wird, wird zurückgewiesen statt aufgelöst. Siehe Live-Validierung.aggrega/diagnostics— gibt die für eine Datei vorgehaltenen Befunde zurück. Läuft beim Eintreffen der Anfrage gerade eine Validierung derselben Datei, wartet die Antwort darauf und meldet, was sie gefunden hat, sodass die Antwort nie ein Unbedenklichkeitszeugnis für eine Datei ist, in der der Daemon gerade Probleme findet. Siehe Diagnosen anfordern, während eine Validierung läuft.aggrega/hover— Hover-Inhalt für die Entität an einer Position.releaseist optional und antwortet in den Begriffen dieses Release — siehe Antworten in den Begriffen eines Release.aggrega/completion— Vervollständigungskandidaten an einer Position. Wo der Cursor eine Entität nach Art benennt — dertypeeiner Komponente, dertypeeiner Feature-Anbindung, einextends:-Wert, dasimplements:eines Recipe oder FeatureRecipe —, sind die Kandidaten die Namen dieser Art, die die eigenen Dokumente Ihres Workspace deklarieren, und bei einer Component oder einem Feature außerdem die Namen, die Ihre konfiguriertencatalog_dirsdeklarieren, jeweils einmal und in Namensreihenfolge angeboten. Einem Workspace, der seine Components und Features aus einem Katalog bezieht, werden diese daher angeboten, nicht nur das, was er selbst verfasst hat. Recipes und FeatureRecipes, die am Wert einer Manifest-Zuordnung angeboten werden, stammen aus den eigenen Dokumenten des Workspace. Eine Entität, die nur der Artefakt-Cache oder eine Registry enthält, wird nicht angeboten: Das Beantworten einer Vervollständigung lädt nie etwas herunter.releaseist optional und antwortet in den Begriffen dieses Release — siehe Antworten in den Begriffen eines Release.aggrega/resolve— löst die an einer Position referenzierte Entität auf (Gehe zu Definition).releaseist optional und antwortet in den Begriffen dieses Release — siehe Antworten in den Begriffen eines Release.aggrega/findReferences/aggrega/findImplementations. Jede nimmt ein optionalesreleasean und antwortet in den Begriffen dieses Release — siehe Antworten in den Begriffen eines Release.aggrega/irGraph— der kompilierte IR-Graph eines Release, zur Introspektion im Editor.releaseist ein Pfad relativ zur Workspace-Wurzel, der ein Release darin nennt — derselbe Wert, denaggrega build --releaseannimmt, wenn es von der Wurzel aus ausgeführt wird. Jede andere Form wird mit dem Standardfehler invalid-params abgelehnt, der nennt, was stattdessen zu senden ist: Ein absoluter Pfad, ein Pfad, der außerhalb der Workspace-Wurzel aufgelöst wird — ob er wie geschrieben hinausführt oder über einen Link, zur Datei oder zu einem Verzeichnis auf dem Weg — und ein leerer Wert werden allesamt zurückgewiesen statt aufgelöst, sodass eine Anfrage nie über eine Datei berichtet, die der Workspace nicht enthält. Ein Release, das Ihre Workspace-Konfiguration alsbuild.authoring_releaseoder als Schlüssel vonworkspace.releasesnennt, gehört zum Workspace, wo auch immer seine Datei liegt; ein Link innerhalb des Workspace, der dorthin führt, wird daher akzeptiert, so wieaggrega/releaseCandidateses auflistet. Ein Katalogverzeichnis, das das Release liest und das sich nicht durchlaufen lässt — etwa eines, das vorhanden ist und nicht gelesen werden kann —, wird so abgelehnt, wieaggrega inspectes ablehnt, bevor irgendetwas anderes gelesen wird: Der Fehler ist1004entity-not-resolvable, seine Meldung ist der Bericht, den die Befehlszeile für dieses Verzeichnis ausgibt, in einer Zeile ([CATALOG_ERROR] <directory>: catalog load: …), und über die verbleibenden Verzeichnisse wird kein Graph gezeichnet. Ein Verzeichnis, das die Workspace-Konfiguration aufführt und das kein Verzeichnis ist — an dessen Stelle etwa nichts existiert —, wird auf dieselbe Weise und im selben Moment abgelehnt,1004entity-not-resolvable, mit der Ablehnung als Meldung, die jeder Befehl dafür gibt und die den Eintrag, die Konfigurationsdatei und die Zeile, die ihn aufführen, sowie die Einstellung nennt (Wo lokale Entitäten gelesen werden). Ein Katalogverzeichnis, das einen Link enthält, der aus dem Verzeichnis hinausführt, innerhalb dessen seine Lesevorgänge bleiben müssen — ein von anderswo verlinktes Dokument oder Verzeichnis, unterhalb eines Katalogverzeichnisses innerhalb des Workspace oder unterhalb eines, das die Konfiguration außerhalb davon nennt —, wird auf dieselbe Weise und im selben Moment abgelehnt, mit1004und dem eigenen Satz der Bedingung, der den Link und sein Ziel nennt: Über einen solchen Link wird nichts gelesen, und ein ohne ihn gezeichneter Graph könnte an seiner Stelle eine andere Entität desselben Namens auflösen. Dasselbe gilt für einen Link, der aus den Dokumenten neben dem Release hinausführt, wo das Release sein Aggregate oder sein Manifest über die Identität nennt. Eine Datei, die das Release, sein Manifest oder ein Release, das es erweitert, über einen Pfad nennt —aggregate:,manifest:,extends:oder ein$import:in parameters — und die aus dem Workspace hinausführt, wie geschrieben oder über einen Link, wird mit dem eigenen Satz der Bedingung abgelehnt (fatal-halts.md §„A reference to another file leads out of the directory it must stay inside (Ein Verweis auf eine andere Datei führt aus dem Verzeichnis hinaus, innerhalb dessen er bleiben muss)“), wobei die Daten des Fehlers sie dem Schlüssel im Release zuordnen, der zur Datei geführt hat, und aus dieser Datei wird nichts gelesen; ein Release, das die Konfiguration außerhalb des Workspace nennt, wird auf dieselbe Weise an das Verzeichnis gebunden, das es enthält, sodass auch ein Pfad abgelehnt wird, den es oder ein Release, zu dem seine Kette führt, schreibt und der dieses Verzeichnis verlässt. Beachten Sie, dassaggrega/releaseCandidatesmit absoluten Pfaden antwortet; ein Client, der die eine Oberfläche aus der anderen speist, konvertiert also zwischen beiden. Dass dieser Parameter eine Schreibweise ablehnt, die die dokumentbezogenen Parameterfileunduriakzeptieren, ist beabsichtigt, und Welche Schreibweisen ein gesendeter Parameter akzeptiert erklärt, was darüber entscheidet. Der Graph hält jeden Wert zurück, den ein Autor als sensibel deklariert hat, genau so, wie--ir-graphihn auf der Befehlszeile zurückhält: Jeder wird durch den Marker ersetzt, denaggrega-inspectunter „Maschinenlesbare Ausgabe“ beschreibt, und alles andere wird so übermittelt, wie der Compiler es erfasst hat.unredacted: truefordert diese Werte im Klartext an — die Schreibweise des Protokolls für das--unredactedder Befehlszeile und der einzige Weg, sie anzufordern; fehlt es oder ist esfalse, hält die Antwort sie zurück. Alles, was die Antwort erreicht, enthält die Werte dann im Klartext; ein Client fordert sie daher nur dort an, wo die Person, die ihn verwendet, dies getan hat.aggrega/build— kompiliert ein Release und schreibt seine Artefakte in das Ausgabeverzeichnis des Workspace, dasselbe Verzeichnis, in dasaggrega buildschreibt, wenn es aus dem Stammverzeichnis des Workspace ausgeführt wird. Fürreleasegilt derselbe Vertrag wie oben. Es rendert mit allen Prüfungen aktiv, sodass eine Abweichung, bei der ein Build auf der Kommandozeile anhalten würde, auch hier anhält. Ein Katalogverzeichnis, das das Release liest und das sich nicht durchlaufen lässt — etwa eines, das vorhanden ist und nicht gelesen werden kann —, wird abgelehnt, wieaggrega buildes ablehnt, bevor irgendetwas geschrieben wird: kein Artefakt und keine Lockfile, wennautoPullgesetzt ist. Ebenso ein Verzeichnis, das die Workspace-Konfiguration aufführt und das kein Verzeichnis ist, mit den Worten, mit denenaggrega buildes ablehnt (Woher lokale Entitäten gelesen werden). Die Ablehnung ist dieselbe, dieaggrega/irGraphfür dasselbe Verzeichnis gibt,1004entity-not-resolvable mit dem Bericht der Kommandozeile in einer Zeile, und ein Link, der aus den Lesevorgängen eines Katalogverzeichnisses oder aus den Dokumenten neben dem Release hinausführt, wird abgelehnt, wieaggrega/irGraphihn ablehnt, ohne dass etwas geschrieben wird. Die Antwort nennt dasoutputDirectory, in das geschrieben wurde, und die geschriebenenfiles, jeweils relativ zu diesem Verzeichnis und sortiert, zusammen mit allennotices, die der Lauf erzeugt hat; Befunde, die eine Dokumentposition tragen, werden stattdessen überaggrega/publishDiagnosticsübermittelt. Ein Release, das beim Rendern ablehnt, wird mit dieser Ablehnung in den Worten des Compilers beantwortet, mit jeder Ursache, und die Ablehnung wird dort veröffentlicht, wohin sie zeigt — siehe Eine beim Rendern ausgelöste Ablehnung. WennautoPullgesetzt war, enthält die Antwort außerdemdependencyResolution, denselben Bericht, mit demaggrega/resolveDependenciesantwortet, sodass ein Client, der Abhängigkeiten als Teil des Builds befüllt hat, liest, was gepinnt wurde, ohne erneut zu fragen — und woher die Auflösung dieses Builds jede Referenz genommen hat, eine Tatsache über diesen Lauf, die die Lockfile nicht festhält. Jeder Hinweis trägt dieclassder Oberfläche, die ihn erzeugt hat —deprecation,catalog,catalog-lint,extends,release-compositionoderdependency-resolutionfür eine Zeile, die die unten beschriebene Abhängigkeitsauflösung erzeugt hat — und eine leereclass, wo der Daemon keinen Namen für diese Oberfläche hat; ein Client zeigt ihn dann als bloßentextan, statt eine nächstliegende Entsprechung zu erraten. Die Dateien, die der Schreibvorgang im Ausgabeverzeichnis oder in einem Verzeichnis darunter findet, in das er eine Datei geschrieben oder das er durchlaufen hat, und die dieser Build nicht geschrieben hat, bleiben, wo sie sind, und werden in einem einzigen Hinweis nach denen des Laufs selbst genannt, unter einer leerenclass, in dem Satz, mit demaggrega buildseine Warnung ausgibt — siehe Dateien, die der Build nicht geschrieben hat;filesnennt sie nie.outputParentgibt an, wohin innerhalb des Workspace die Artefakte gehen, und sein Name ist alles, was er bedeutet: Es ist das Verzeichnis, in dem das Ausgabeverzeichnis angelegt wird, sodass das Senden vondocsdie Artefakte nachdocs/distschreibt statt indocsselbst — genau das, was ein indocsan einem Terminal ausgeführter Build erzeugt. Lassen Sie es weg, schreibt der Build dorthin, wohin ein im Stammverzeichnis des Workspace ausgeführter Build schreibt. Es ist anders zu lesen als dasoutputDir, das die anderen schreibenden Anfragen hier entgegennehmen, und zwar mit Absicht: Jene nennen das Verzeichnis, in das geschrieben wird, dieses nennt das übergeordnete Verzeichnis davon, und die beiden tragen verschiedene Namen, weil sie verschiedene Dinge sind. Es ist dennoch ein Ziel innerhalb des Workspace, sodass ein absoluter Wert, einer, der aus dem Stammverzeichnis hinaufsteigt, und einer, der über einen Link hinausführt — ein verlinktes Verzeichnis außerhalb des Stammverzeichnisses oder ein noch nicht angelegtes Verzeichnis darunter —, abgelehnt statt aufgelöst werden. Das darin angelegte Ausgabeverzeichnis und jede Datei, die der Build dort schreibt, sind ebenfalls an den Workspace gebunden: Wo eines davon über einen Link aus dem Workspace hinausführt, wird der Build mit1004und dem eigenen Satz der Bedingung abgelehnt, der den Link und sein Ziel nennt, und nichts wird geleert oder geschrieben.autoPulllöst die Abhängigkeiten des Release vor dem Rendern auf, dieselbe Auflösung, dieaggrega/resolveDependenciesdurchführt, und ist aus, sofern eine Anfrage es nicht verlangt, passend zum eigenen Standard der Kommandozeile; ohne es wird ein Release, das keine Lockfile hat, mit dem lockfile-absent-Fehler abgelehnt, der nennt, was auszuführen ist. Mit gesetztemautoPullerreicht diese Anfrage Registrys und schreibt die Lockfile — siehe Eine Registry erreichen und schreiben. Eine Anfrage, die zuerst auflöst, rendert das Release dennoch nur einmal: Herauszufinden, welche entfernten Referenzen ein Release verbraucht, ist selbst ein Rendern, sodass die Auflösung bereits gerendert hat, worum es beim Build geht, und der Build aus diesem Rendern beantwortet wird, statt es zu wiederholen.policyInputnennt ein Verzeichnis innerhalb des Workspace, relativ zu dessen Stammverzeichnis, in das der Build zusätzlich die Nutzdaten schreibt, die jede Governance-Rolle einem dort angehängten Plugin übergibt — die Dateien, dieaggrega build --policy-inputschreibt, unter denselben Namen —, ob der Build abschließt oder anhält; dienoticesder Antwort sagen dann, wie viele geschrieben wurden, und nennen jede Rolle, für die keine Datei geschrieben wurde, unter einer leerenclass. Bei einer fehlschlagenden Anfrage liegen die geschriebenen Dateien auf der Festplatte, und diese Aufstellung ist nicht in der Antwort enthalten: Der Fehlerumschlag trägt allein die Ablehnung. Es ist ein Ziel, sodass ein absoluter Wert oder einer, der aus dem Workspace hinaufsteigt, abgelehnt wird, bevor irgendetwas läuft.aggrega/buildPreview— meldet, was ein Build des Release schreiben würde, ohne etwas davon zu schreiben. Fürreleasegilt derselbe Vertrag wie oben. Es führt dieselbe Berechnung wieaggrega/buildunter denselben Prüfungen aus, sodass ein Release entweder bei beiden abgelehnt oder von beiden gemeldet würde — was die Wahl zwischen ihnen zu einer Wahl über die Ausgabe statt über die Strenge macht. Ein Katalogverzeichnis, das das Release liest und das sich nicht durchlaufen lässt oder das einen Link enthält, der aus dem Verzeichnis hinausführt, innerhalb dessen seine Lesevorgänge bleiben müssen, wird auf dieselbe Weise abgelehnt, bevor irgendetwas gerendert wird, ebenso ein Verzeichnis, das die Workspace-Konfiguration aufführt und das kein Verzeichnis ist, wie beiaggrega/build. Die Antwort enthältfiles, die ausgaberelativen Namen, die ein Build erzeugen würde, sortiert, zusammen mit allennotices; es gibt keinoutputDirectory, weil nirgendwo etwas geschrieben wurde, das zu nennen wäre. Ein Release, das beim Rendern ablehnt, wird genau so beantwortet und veröffentlicht, wieaggrega/buildes beantwortet und veröffentlicht. Es lehntautoPullab mit einem invalid-params-Fehler, der nennt, was stattdessen zu senden ist: Das Befüllen von Abhängigkeiten schreibt die Lockfile, und diese Anfrage schreibt keine Lockfile. Sie erreicht keine Registry.policyInputist der einzige Schreibvorgang, den sie ausführt, und nur, wenn es gesendet wird: Sie schreibt die Governance-Nutzdaten genau so in dieses Verzeichnis, wieaggrega/buildes tut — die Dateien, dieaggrega build --dry-run --policy-inputschreibt —, und lässt das Ausgabeverzeichnis und die Lockfile unberührt, mit derselben Aufstellung in dennoticesund derselben Grenze: Bei einer fehlschlagenden Anfrage liegen die geschriebenen Dateien auf der Festplatte, und die Aufstellung ist nicht in der Antwort enthalten.aggrega/resolveDependencies— löst die Katalog- und Quellabhängigkeiten des Release in den Cache auf, pinnt die externen Eingaben, die sein Rendern verbraucht, in den inhaltsadressierten Speicher und schreibt seine Lockfile.releaseist ein Pfad relativ zur Workspace-Wurzel, derselbe Wert, denaggrega/irGraphannimmt, und wird in denselben Formen abgelehnt.upgradeverwirft die erfassten Pins und löst neu auf, wobei jede Abhängigkeit auf die höchste verfügbare Version angehoben wird;targetsbeschränkt das auf die Entitätsreferenzen, die es nennt, und behält jeden anderen Pin.verifyprüft die erfasste Auflösung gegen diejenige, die diese Anfrage ohne es durchführen würde, wobei die erfassten Pins auf dieselbe Weise berücksichtigt werden, und schreibt weder Lockfile noch Plugin-Vertrauensdatensatz nochentity.lock— der Cache wird gelesen und befüllt, wie es ohne es geschähe — und antwortet mitverified: trueund dertoolchain, die die Lockfile erfasst.verifywird als ungültige Parameter abgelehnt nebenupgrade, nebentargetsund nebenpinSources, gleich welchen Wert es trägt, bevor irgendetwas aufgelöst oder ein Fortschritt gemeldet wird: Ein Upgrade verwirft die Pins, die ein Verify berücksichtigen soll, benannte Ziele werden nur durch ein Upgrade neu aufgelöst, undpinSourcesentscheidet, ob eine Auflösung die Pins erfasst, die einerentity.lockfehlen, oder ihretwegen ablehnt, und beides tut ein Vergleich, der keineentity.lockschreibt, nicht. Die Befehlszeile und das Assistenten-Werkzeug lehnen dieselben Paare ab. Die Antwort nennt dielockfile, die geschrieben oder mit der verglichen wurde, und jede gepinnte Referenz inentities,librariesundplugins, wobei jeder Eintrag dieversionenthält, zu der er aufgelöst wurde, und seinesource— woher dieser Lauf die Referenz genommen hat, mit dem Wort, dasaggrega pull --detailfür dieselbe Auflösung ausgibt:fetched-fresh,cache-reuse,local,in-binaryoderexternal—, zusammen mitsourceArtifacts,trustedPlugins,externalInputs— wie viele externe Eingaben die Lockfile nach dem Lauf pinnt, gezählt sowohl die übernommenen als auch die von diesem Lauf entdeckten — und allennotices, die die Auflösung ausgelöst hat. 🔴 Eine erfolgreiche Antwort bedeutet für sich allein nicht, dass das Pinnen der externen Eingaben vollständig ist. Wo der Lauf jede Abhängigkeit gepinnt hat, aber nicht vollständig ermitteln konnte, welche externen Eingaben das Release verbraucht, antwortet er mitincompleteExternalInputs, das angibt, was die Ermittlung angehalten hat, und antwortet dennoch als Erfolg — die Abhängigkeits-Pins sind vollständig und auf der Festplatte, und die gesamte Anfrage als fehlgeschlagen zu melden, würde Sie auffordern, bereits korrekte Arbeit zu wiederholen. Lesen Sie dieses Feld, bevor Sie eine Lockfile als vollständig gepinnt behandeln: Es fehlt, wenn nichts unentdeckt geblieben ist, sodass sein Vorhandensein das Signal ist. Es gibt keinen Parameter für Katalogverzeichnisse: Der Suchstapel ist derjenige, den der Workspace konfiguriert. Dies ist die einzige Pinning-Anfrage der Sitzung für ein Release, und hier werden auch externe Eingaben gepinnt — welche URLs ein Rendern verbraucht, ergibt sich aus dem, was es rendert; diese Anfrage rendert daher das Release, um es herauszufinden, und eine Build-Anfrage wird danach aus dem bedient, was sie erfasst hat. Ein Recipe oder FeatureRecipe, das das Release baut und dessenentity.lockkeinen Pin für eine Eingabe erfasst, die die Entität liest, lässt die Anfrage ablehnen, wobeiaggrega pinund jede nicht erfasste Eingabe genannt werden;pinSources: trueführt stattdessen diesen Pin-Schritt über diese Entitäten aus und schreibt dieentity.lockneben jede — derselbe Schritt, denaggrega/pinausführt, mit denselben Bytes. FehltpinSources, folgt es dempin_sources_at_pulldes Workspace; wird es gesendet, überschreibt es diese Einstellung in beide Richtungen, sodassfalseselbst in einem Workspace ablehnt, der zum Pinnen konfiguriert ist. Diese Anfrage erreicht Registries und schreibt — siehe Eine Registry erreichen und schreiben.aggrega/pin— erfasst in derentity.lockneben einem Recipe oder FeatureRecipe den Inhalts-Pin für jede Eingabe, die die Entität von außerhalb ihres eigenen Dokuments liest: eine entfernte Quelle, deren Koordinaten vollständig ausgeschrieben sind, eine Datei, die ein artifacts-Eintrag importiert, und jede Datei, die eine lokale Quelle zu dem beiträgt, was eine Veröffentlichung der Entität enthält. Es ist derselbe Schritt, denaggrega pinan einem Terminal ausführt, und er schreibt dieselben Bytes.entityist erforderlich und ist ein Pfad relativ zur Workspace-Wurzel, der das Entitätsdokument nennt, und wird in denselben drei Formen abgelehnt wierelease. Es wird kein Release genannt: Eine entfernte Quelle, deren Koordinaten keine Vorlage enthalten, nennt ein einziges Artefakt für jedes Release, das die Entität verwendet, sodass nichts, was ein Release liefert, zum Pinnen nötig ist, während eine entfernte Quelle, deren Koordinaten aus einer Vorlage stammen, pro Release vonaggrega/resolveDependenciesgepinnt wird; eine als Vorlage geschriebene lokale Quelle trägt jede Datei im Verzeichnis der Entität bei, und jede davon wird hier gepinnt.dryRunlöst die Eingaben auf und antwortet mit der Lock-Datei, die der Schritt schreiben würde, alscontent, ohne etwas neben die Entität zu schreiben; der Inhalts-Cache wird trotzdem befüllt. Die Antwort enthältentity,kind,nameundpinnable— false bei einer Art, die nichts liest, was eine Lock-Datei erfasst; in diesem Fall wurde nichts neben der Entität angefasst, und jedes andere Feld fehlt — und andernfalls die geschriebenelock,changed(false, wenn die Lock-Datei bereits jeden Pin erfasst hatte und byte-identisch belassen wurde),removed, wo die Entität nun nichts mehr liest, was eine Lock-Datei erfasst, und ihre Lock-Datei gelöscht wurde, undpins, einen Eintrag pro Pin-Klasse mit der Anzahl, die die Lock-Datei enthält. Die Entitätsdatei selbst wird nie geschrieben. Dies schreibt neben die Entität, innerhalb des Workspace, und erreicht die Hosts, die die Quellen der Entität nennen — siehe Eine Registry erreichen und schreiben.aggrega/cacheStatus— was die Caches auf der Festplatte enthalten: ein Eintrag pro zwischengespeichertem Element mit seiner Größe und, sofern vorhanden, seinem Inhalts-Digest, gruppiert nach Klasse. Nimmt den Workspace an und sonst nichts. Jede Klasse enthält einreach—workspacefür den Artefakt-Cache unter dem eigenen Cache-Verzeichnis dieses Workspace,machinefür die Speicher der kompilierten Module, der Plugin-Beschreibungen und der Dokumentationspakete, die jedes Projekt auf dem Rechner teilt — undscopenennt die rechnerweiten Klassen direkt. Es schreibt nichts. Unter Eine Registry erreichen und schreiben steht, warum die Reichweite in einer Antwort steht, die nichts ändert.aggrega/cachePrune,aggrega/cacheEvict,aggrega/cacheClear— geben zwischengespeicherte Inhalte frei. Ein Prune entfernt, worauf keine Lockfile eines Workspace verweist; eine Eviction kürzt den Speicher der kompilierten Module aufmaxSize, eine Bytemenge, die so geschrieben wird, wie die Befehlszeile sie schreibt (5GiB,512MiBoder eine Byteanzahl); ein Clear leert jeden Cache, den diese Sitzung adressiert. Jede Antwort nennt, was entfernt wurde, wobei jede Entfernung dasreachder Klasse trägt, aus der sie stammt, und jede enthältscope. Jede Antwort nennt außerdem, was an Ort und Stelle belassen wurde, weil ein anderer Prozess es geöffnet hatte — Windows verweigert das Entfernen einer geöffneten Datei, und der Vorgang fährt mit dem Rest fort, statt fehlzuschlagen: Ein Prune oder eine Eviction listet diese Einträge inheldOpenauf, und ein Clear zählt für jeden geleerten Cache die belassenen Dateien inheldOpenFilesund ihre Größe inheldOpenBytes. Andernorts ist die Liste leer und die Zählungen sind null, und ein späterer Lauf kann freigeben, was übrig geblieben ist. Diese reichen über den Workspace hinaus — siehe Eine Registry erreichen und schreiben.aggrega/registryList— die Registries, die dieser Workspace erreichen soll: für jeden Eintrag der Host, ein optionaler Alias, ob er der Standard ist, seine Vertrauenshaltung als einzelne Felder und ob für diesen Host ein Zugangsnachweis vorhanden ist. Nimmt den Workspace an und sonst nichts. Es kontaktiert keine Registry. Der Zustand des Zugangsnachweises meldet nur das Vorhandensein — nie den Zugangsnachweis, nie seine Form und nie, ob die Registry ihn akzeptieren würde, was einen Netzwerk-Roundtrip erfordern würde, den eine Auflistung nicht durchführt —, und er wird aus dem rechnerweiten Speicher für Zugangsnachweise gelesen, wascredentialStateIsMachineWideausdrücklich angibt.aggrega/search— durchsucht den lokalen Index der konfigurierten Registries. Jedes Feld schränkt ein, und jedes ist optional, sodass ein leeres Params-Objekt alles anfordert, was der Index enthält. Es kontaktiert kein Netzwerk: Der Index ist der Offline-Snapshot, der unter dem eigenen Cache-Verzeichnis dieses Workspace geschrieben wurde. Die gemeldete Version ist diejenige, die eine Auflösung wählen würde — eine Version, deren Rückzug eine Signatur trägt, der dieser Workspace vertraut, wird ausgeschlossen und inretractedgenannt —, und die Antwort enthält ihre eigene Herkunft:indexesgibt das Alter des Snapshots jeder durchsuchten Registry an,stalemarkiert einen, dessen Aktualisierung lohnt, undmissingIndexHostsnennt konfigurierte Registries ohne lokalen Index, deren Inhalte daher in der Antwort fehlen.aggrega/registryAdd— registriert eine Registry und ihre Signatur-Vertrauensrichtlinie.hostist erforderlich; alles andere gestaltet die Richtlinie oder das Schreibziel.keyPathundtrustedRootnennen Dateien: Ein absoluter Wert — etwa eine in einem Dialog ausgewählte Datei — wird dort gelesen, wohin er zeigt; ein relativer nennt eine Datei innerhalb des Workspace, aufgelöst gegen die Workspace-Wurzel statt gegen das Verzeichnis, in dem der Daemon läuft, und einer, der aus der Wurzel hinaufsteigt oder über einen Link daraus hinausführt, wird mit dem invalid-params-Fehler abgelehnt, bevor irgendetwas gelesen oder geschrieben wird. Ein relativertrustedRootwird als die Datei erfasst, die er im Workspace nennt, sodass der Eintrag diese Datei nennt, gleich in welchem Verzeichnis eine spätere Verifizierung läuft.fetchTrustist standardmäßig true, wenn der Schlüssel fehlt, entsprechend der Befehlszeile, und übernimmt beim ersten Kontakt die eigene, von der Registry angebotene Richtlinie;trustin der Antwort gibt an, was geschehen ist — die Richtlinie wurde gepinnt, die Registry hat keine angeboten (und war, mitunreachabledaneben, überhaupt nicht erreichbar), stattdessen wurde die eingebaute Baseline des offiziellen Hubs gepinnt, oder es wurde kein Abruf versucht. Die Registrierung ist dieselbe, dieaggrega registry adddurchführt: derselbe Abruf unter derselben Netzwerkhaltung, der denselben Eintrag Byte für Byte schreibt. In einem Offline-Workspace wird der Abruf abgelehnt, bevor irgendeine Verbindung aufgebaut wird, sodass die Registry nie gefragt wird, und eine andere Registry als der offizielle Hub wird abgelehnt, sofern die Anfrage nichtidentitiesoderkeyPathliefert, die genau das registrieren, was gesendet wurde, und keinen Abruf durchführen: Die Meldung des Fehlers ist der Satz, den die Befehlszeile ausgibt, mit vorangestelltem Kurzcode der BedingungE0310— so wie die Meldung jeder Ablehnung dieser Anfrage, die eine Bedingung nennt, mit deren Kurzcode beginnt —, und nichts wird geschrieben. Der offizielle Hub wird weiterhin mit seiner eingebauten Baseline geschrieben, beantwortet mittrust.baselinetrue undtrust.reason, das besagt, dass der Hub nicht nach seiner Vertrauensrichtlinie gefragt wurde, weil der Workspace offline ist — der Grund, mit dem der Hinweis der Befehlszeile beginnt —, und ohnenotAdvertised, weil der Hub nie gefragt wurde. Dies schreibt standardmäßig die globale Konfiguration — siehe Eine Registry erreichen und schreiben.aggrega/registryRemove— entfernt den Eintrag einer Registry, adressiert über Host oder Anzeigealias. Ein Token, das auf nichts passt, wird abgelehnt, statt als Erfolg über einer unveränderten Konfiguration beantwortet zu werden. Dies schreibt standardmäßig die globale Konfiguration — siehe Eine Registry erreichen und schreiben.aggrega/logout— entfernt den gespeicherten Zugangsnachweis für eine Registry, dieselbe Entfernung, dieaggrega logoutan einem Terminal durchführt.registryist erforderlich und nennt den Registry-Host so, wie Sie sich bei ihm authentifiziert haben; hier gibt es keinen Anzeigealias aufzulösen, weil der Speicher für Zugangsnachweise nach der Adresse geschlüsselt ist, bei der sich ein Client authentifiziert, statt nach etwas, das eine Konfiguration nennt, sodass ein Host, den kein Workspace konfiguriert, dennoch einen Zugangsnachweis haben kann, den Sie entfernen können. Ein Host, für den der Speicher keinen Zugangsnachweis enthält, wird erfolgreich entfernt, und nichts wird neu geschrieben — ein Aufrufer, der verlangt hat, dass ein Host keinen Zugangsnachweis hat, hat bekommen, was er verlangt hat; das ist also eine Antwort und kein Fehler, und auch der Terminalbefehl verhält sich so. Die Antwort enthältregistryundscope. Sie enthält keinen Teil des Zugangsnachweises in irgendeiner Form und meldet nichts darüber, ob einer vorhanden war: Das festzustellen, würde ein zweites Lesen des Speichers erfordern, um das niemand gebeten hat; fragen Sie daheraggrega/registryList, wenn es um das Vorhandensein geht. Es kontaktiert keine Registry — das Entfernen eines gespeicherten Zugangsnachweises ist ein lokaler Vorgang, und ob diese Registry den Zugangsnachweis akzeptiert hätte, wird nicht gefragt. Dies ändert den Speicher für Zugangsnachweise, den jedes Projekt auf dem Rechner teilt — siehe Eine Registry erreichen und schreiben.aggrega/registryUpdate— aktualisiert den lokalen durchsuchbaren Index, denaggrega/searchliest. Ein fehlendesregistryaktualisiert jede konfigurierte; wird eine genannt, wird nur diese Registry aktualisiert.upgradeliest jedes Repository vollständig neu und vergleicht nichts mit dem bereits geschriebenen Index; eine Aktualisierung ohne diese Option liest ohnehin alles neu, was sich geändert hat. Die Antwort enthält die Datensatzanzahl jedes Hosts, die Repositorys, die nicht gelesen werden konnten — jedes mit einemreason, der, wo es einen gibt, mit der Art des letzten Fehlschlags des Lesevorgangs beginnt —,readsRetried, wie viele ihrer Lesevorgänge die Registry zwischendurch abgelehnt oder abgebrochen hat und erneut angefragt wurden, jeder einmal gezählt und null eingeschlossen, die angetroffenen Deprecation-Marker, denerroreines fehlgeschlagenen Hosts — mitunreachabledaneben, wo diese Registry nicht erreicht werden konnte — undindexRoot, das Verzeichnis unter dem eigenen Cache dieses Workspace, in das die Indizes geschrieben wurden. Dies erreicht jede Registry, die es aktualisiert — siehe Eine Registry erreichen und schreiben.aggrega/publishEntity— bündelt eine Katalogentität und veröffentlicht sie in einer Registry.entityist ein Pfad relativ zum Workspace-Root, der das zu veröffentlichende Dokument benennt, und wird in denselben drei Formen abgelehnt wierelease: fehlend, absolut oder außerhalb des Roots aufgelöst. Eine Plugin-Entität benötigt zusätzlichplugin, dieselbe Art von Pfad, der die ausführbare Datei benennt, die im eigenen Manifest der Entität veröffentlicht wird.registryist das Ziel und ist standardmäßig die im Workspace konfigurierte Registry.dryRunberechnet das Bundle und den Digest, auf dem eine Veröffentlichung davon landen würde, und kontaktiert keine Registry. Wirdsignweggelassen, gilt die eigene Richtlinie der Ziel-Registry, was die Befehlszeile tut, wenn ihr Flag fehlt, während das Senden die Entscheidung des Aufrufers ist – und keines von beiden lockert die Ablehnung, denn eine Registry- oder Workspace-Richtlinie, die eine Signatur verlangt, lehnt eine unsignierte Veröffentlichung ab, was auch immer das Feld besagt.pinSources: trueführt den Pin-Schritt des Entitätsautors auf der Entität aus, bevor sie gebündelt wird, sodass dieentity.lock, die der Schritt daneben schreibt, Teil dessen ist, was veröffentlicht wird – derselbe Schritt, denaggrega/pinausführt. Er läuft vor jeder Ablehnung, die den Inhalt der Entität beurteilt – einer Signaturrichtlinie, dem Unveränderlichkeitsschutz –, sodass eine dort abgelehnte Veröffentlichung das Lock dennoch geschrieben hinterlässt; eine Ablehnung, die die Anfrage selbst betrifft, etwa ein Offline-Workspace oder ein fehlendes Ziel, kommt zuerst und pinnt nichts, ebenso die Ablehnung einer Entität, die ihr Verzeichnis mit einer anderen Entität teilt, in das der Schritt kein Lock schreiben darf. Fehlt das Feld, folgt es der Workspace-Einstellungpin_sources_at_push; wird es gesendet, überschreibt es diese Einstellung in beide Richtungen. UnterdryRunmeldet der Schritt das Lock, das er schreiben würde, und schreibt nichts. Eine Veröffentlichung, die den Schritt nicht ausführt, lehnt ein Recipe oder FeatureRecipe ab, dessenentity.lockkeinen Pin für eine gelesene Eingabe verzeichnet, oder einen, dem die Eingabe nicht mehr entspricht, bevor etwas gebündelt wird – auch unterdryRun– und nennt dabeiaggrega pin,pinSourcesundpin_sources_at_push; es ist die Ablehnung, dieaggrega/resolveDependenciesüber dasselbe Lock auslöst. Die Antwort enthältreference,tag,kind,mediaType, dassize-Paar, den veröffentlichtendigest– unterdryRunden Digest, auf dem diese Veröffentlichung landen würde, also den, denaggrega push --dry-runausgibt –,signed,alreadyPublished,dryRunundreach;pin– dieselbe Antwort, dieaggrega/pingibt –, wo der Schritt ausgeführt wurde; undwholeDirectorySource, wo die lokale Quelle der Entität als Vorlage geschrieben ist, wobei diese Quelle so benannt wird, wie sie verfasst wurde. Eine solche Quelle wählt ihr Verzeichnis erst, wenn ein Release die Vorlage ausfüllt, sodass die Veröffentlichung jede Datei im Verzeichnis der Entität mitführt statt nur der Dateien, die die Entität benennt, und dieses Feld ist die Art, wie ein Aufrufer erfährt, dass dies geschehen ist – auch bei einem Probelauf. Sie enthält außerdemwindowsUnusableEntries, wo das von der Veröffentlichung mitgeführte Archiv Einträge enthält, die Windows in der geschriebenen Form nicht aufnehmen kann – einen Pfad mit einem Teil, der nach einem Gerät benannt ist, etwaCON,AUXoderNUL, in beliebiger Groß- und Kleinschreibung und mit beliebiger nachfolgender Erweiterung, oder einen Teil, der auf einen Punkt oder ein Leerzeichen endet –, und benennt jeden davon, zuerst den Dateinamen des Entitätsdokuments selbst, dann die mitgeführten Dateien; das Feld fehlt, wo es keinen solchen gibt, was eine allein als Dokument veröffentlichte Entität einschließt.aggregalehnt es unter Windows ab, einen solchen Eintrag zu entpacken, sodass ein Windows-Workspace die Version nicht verwenden kann. Dies sind die Einträge, vor denenaggrega pushwarnt, und eine Anfrage, die um Fortschrittsmeldungen gebeten hat, liest dieselben Warnzeilen im Fortschritt der Veröffentlichung; keines von beiden lehnt etwas ab, sodass die Veröffentlichung genau so fortgesetzt oder abgelehnt wird, wie es ohne sie der Fall wäre, auch unterdryRun. Dies schreibt in eine Registry und reicht über diesen Rechner hinaus, und mit dem Pin-Schritt schreibt es auch neben die Entität – siehe Eine Registry erreichen und schreiben.aggrega/publishArtifact— veröffentlicht ein eigenständiges Datenartefakt, etwa ein Dokumentations-Bundle.fileist ein Pfad relativ zum Workspace-Root, der demselben Vertrag unterliegt, und seine Bytes werden unverändert veröffentlicht: Es wird keine Entitätshülle geparst und nicht nach einem Kind verzweigt.nameundtagbenennen, als was es veröffentlicht wird, und beide sind erforderlich.mediaTypeist standardmäßig der Typ des Dokumentations-Bundles. Die Antwort enthältreference,tag,mediaType, dassize-Paar, den veröffentlichtendigest,alreadyPublished,dryRunundreach. Es signiert nichts – ein veröffentlichtes Artefakt wird anschließend per Referenz mitaggrega/signArtifactssigniert, das nur die Referenz benötigt, die diese Antwort meldet. Dies schreibt in eine Registry und reicht über diesen Rechner hinaus – siehe Eine Registry erreichen und schreiben.aggrega/signArtifacts— signiert bereits veröffentlichte Artefakte und hängt jede Signatur an.referencesenthält eine oder mehrere Registry-Adressen statt Pfaden, sodass für sie kein workspace-relativer Vertrag gilt; eine leere Liste oder ein leerer Eintrag darin wird abgelehnt. Eine einzige Identität dient dem gesamten Batch und wird aufgelöst, bevor irgendeine Referenz signiert wird, sodass ein Batch, für den überhaupt keine Anmeldedaten verfügbar sind, zu Beginn abgelehnt wird statt mittendrin. Dasselbe gilt für einen Batch, dessen Referenzen unterschiedliche Anmeldedaten benötigen würden: Eine Anfrage nennt keinen Schlüssel, also ist das die Workspace-Konfiguration, die für die Registry einer Referenz einen vorhandenen Schlüssel nennt und für die einer zweiten keinen oder einen anderen – es wird nichts signiert, und die Ablehnung nennt die Registries auf jeder Seite, wie References signed together need different signing credentials (Gemeinsam signierte Referenzen benötigen unterschiedliche Signatur-Anmeldedaten) beschreibt. Das Signieren einer Referenz, unter der nichts veröffentlicht wurde, wird abgelehnt, statt an nichts angehängt zu werden, und eine Referenz, die bereits eine Signatur trägt, die die Vertrauensrichtlinie ihrer Registry verifiziert, bleibt unverändert und wird als signiert gezählt, wieaggrega signbeschreibt.jobs, das optional ist, gibt an, wie viele Referenzen gleichzeitig signiert werden: Fehlt es, werden sie nacheinander signiert, und ein Wert unter 1 wird mit dem invalid-params-Fehler abgelehnt, bevor irgendeine Referenz gelesen wird. Jede Referenz wird dennoch genau so signiert, wie sie allein signiert würde, wieaggrega signbeschreibt, und sowohl der Fortschritt, den die Anfrage meldet, als auch die Antwort behalten die Reihenfolge bei, in der die Referenzen angegeben wurden. Die Antwort enthältsigned, wobei jeder Eintrag einereferenceund den veröffentlichtendigestnennt, auf den sich ihre Signatur festlegt, nebenreach; ein Batch, in dem irgendeine Referenz fehlgeschlagen ist, wird als Fehler beantwortet, der jede davon nennt, statt als Ergebnis mit einer verkürzten Liste. Dies schreibt in eine Registry und reicht über diesen Rechner hinaus – siehe Eine Registry erreichen und schreiben.aggrega/deprecateArtifact— hängt eine signierte Deprecation-Markierung an ein bereits veröffentlichtes Artefakt an. Senden Sie entweder eine einzelnereferencemit ihrerseverityund ihremreasonoderfrom, das eine Batch-Datei relativ zum Workspace-Root nennt – das Senden beider wird abgelehnt. Die Inhaltsfelder sind erforderlich, statt abgefragt zu werden: Niemand beobachtet diesen Stream, sodass eine Anfrage, der eines fehlt, mit Angabe dessen abgelehnt wird, was zu senden ist. Sie gehören nur zur einzelnenreference: Eine Batch-Datei trägt den Inhalt jeder Markierung in ihren eigenen Einträgen, sodass eineseverity, einreason, einreplacementoder einemessage, die nebenfromgesendet werden, als ungültiger Parameter abgelehnt werden – unter Nennung jedes gesendeten –, statt ignoriert zu werden. Hier gelten dieselben schlüssellosen Eingaben, die die beiden Signieranfragen akzeptieren, denn die Markierung wird über ihren eigenen Digest signiert, und die Einträge einer Batch-Datei sind genau so an eine einzige Anmeldung gebunden wie die Referenzen eines Signier-Batches. Die Antwort enthältmarked, wobei jeder Eintrag die zurückgezogenereference, ihreseverity, den ZeitstempelissuedOnund dendigestdes eigenen Manifests der Markierung nennt – die Markierung wird als nicht getaggter Referrer des Artefakts angehängt, das sie zurückzieht, sodass nichts anderes sie adressiert –, nebenreach. Dies schreibt in eine Registry und reicht über diesen Rechner hinaus – siehe Eine Registry erreichen und schreiben.aggrega/catalogIndex— der Entitätsindex:kind,name,apiVersion,description,labels, Quelldatei undoriginjeder Entität in dem Workspace, den die Anfrage benannt hat. Nimmt den Workspace und optionalreleaseentgegen: Die Menge ist eine Eigenschaft dieses Workspace-Roots und der Katalogverzeichnisse, die er konfiguriert, oder, mitrelease, der Verzeichnisse, die die Konfiguration diesem Release gibt – siehe In den Begriffen eines Release antworten. Er umfasst beide Orte, von denen eine Entität stammt – die Aggrega-Dokumente unter dem Workspace-Root und die Features, die die konfigurierten Katalogverzeichnisse enthalten –, denn dies ist die Oberfläche, gegen die ein Client joint, wenn er die beschreibenden Felder einer Entität benötigt, und ein Index, der nur einen der beiden kennt, ließe einen Teil jeder Kandidatenliste unauflösbar. Ein Workspace-Dokument zählt als Entität, wenn es sowohl einkind:als auch einenmetadata.namedeklariert und keineapiVersiondeklariert, die zur Gruppe eines anderen Projekts gehört, sodass YAML, das zufällig im Baum liegt – die Values-Datei eines Charts, eine CI-Konfiguration, ein gerendertes Kubernetes-Manifest –, übersprungen statt aufgelistet wird. Ein Dokument, das überhaupt keineapiVersiondeklariert, wird gemeldet: Es ist ein Aggrega-Dokument, dem ein Feld fehlt, und es aufgelistet zu sehen, ist die Art, wie Sie erfahren, dass es dort zu korrigieren ist. Siehe Wie eine Entität adressiert wird für die Bedeutung vonoriginund einem leerenfile. Kein Dokument hinter einem Link, der aus dem Workspace-Root hinausführt, wird gelesen: Ein Verzeichnis außerhalb des Roots wird nicht durchsucht, und eine Datei außerhalb davon wird nicht gelesen, was auch immer sie deklariert, sodass eine Entität, die Ihr Editor unter einem solchen Link anzeigt, nicht als eigene des Workspace aufgelistet wird – und auch nicht vonaggrega/attachCandidatesoderaggrega/connectionCandidatesangeboten wird, die dieselben Dokumente lesen, selbst wenn Ihr Editor dieses Dokument geöffnet hat. Das gilt, was auch immer das Dokument deklariert. Die einzige Ausnahme ist ein Release, das Ihre Workspace-Konfiguration nennt – alsbuild.authoring_releaseoder als Schlüssel vonworkspace.releases, beurteilt nach der Datei, zu der der Link führt, sodass das Nennen des Links oder dieser Datei gleich zählt –, das aus der Datei gelesen wird, zu der der Link führt, an der eigenen Stelle des Links aufgelistet wird, so wieaggrega/releaseCandidateses auflistet, und nicht genannt wird; eine von einer dieser Einstellungen genannte Datei, die etwas anderes als ein Release deklariert, wird nicht aufgelistet, und ihr Link wird genannt. Die konfigurierten Katalogverzeichnisse sind die Art, wie ein Workspace andere, anderswo aufbewahrte Entitäten liest, sodass ein Link zu einem Verzeichnis, das die Konfiguration untercatalog_dirsaufführt – für den Workspace oder für ein Release –, nicht so durchsucht wird wie die eigenen Dokumente des Workspace und auch nicht genannt wird: Die Konfiguration hat es erreicht, und seine Features werden aus dem Katalog aufgelistet, wie die jedes konfigurierten Katalogverzeichnisses. Die aus den Katalogverzeichnissen aufgelisteten Features enthalten niemals eines hinter einem Link, der aus dem Verzeichnis hinausführt, innerhalb dessen die Lesevorgänge eines Katalogverzeichnisses bleiben müssen – der Workspace für ein Katalogverzeichnis darin oder das Verzeichnis selbst für eines, das die Konfiguration außerhalb davon nennt –, sodass eine Entität, die die Antwort als hinter einem nicht gelesenen Link liegend nennt, niemals zusätzlich neben diesem Namen aufgelistet wird. Die Antwort nennt jeden solchen Link inunreadLinkedDirsfür einen Link zu einem Verzeichnis und inunreadLinkedFilesfür einen Link, dessen eigener Name auf.yamloder.ymlendet und der zu einer Datei führt – relativ zum Root, dort, wo der Link liegt, in der Reihenfolge, in der der Workspace durchsucht wird –, damit ein Client den Grund nennen kann. Ein Link, den die Suche ausschließt, durch seinen Namen, durch seine Lage oder durch eine.gitignore, wird nicht genannt, und in einer Antwort in den Begriffen eines Release ebenso wenig einer unter einem Katalogverzeichnis, das nur andere Releases lesen. Ein Link unterhalb eines Katalogverzeichnisses außerhalb des Workspace hat keine Stelle relativ zum Root, an der er genannt werden könnte, und wird nicht genannt. Beide Felder sind immer vorhanden und leer, wenn es keinen solchen Link gibt. Wo die eigene Konfigurationsdatei des Workspace oder das CI-eigene Overlay daneben selbst ein Link ist, der aus dem Workspace hinausführt, wird diese Datei inunreadLinkedFilesgenannt, wie auch immer die Suche sie behandelt, und der Index ist der eigene Lesevorgang des Workspace ohne jede Konfiguration – kein Katalogverzeichnis wird dafür gelesen, und ein Index in den Begriffen eines Release wird abgelehnt; siehe Workspace-Root und aktives Release.aggrega/entityDefinition— worauf die benannte Entität aufgelöst wird: ihrkind, ihr eigenernameund ihreversion, ihredescriptionund ihrpublishScope, sofern vorhanden, diefile, in der sie deklariert wurde, dieauthoredLengthdes dahinterstehenden verfassten Texts und ihredefinitionals YAML-Dokument mit bereits angewandter Vererbung.filewird für jedes Kind gemeldet, als Pfad, den Sie öffnen können – relativ zum Workspace-Root für ein Dokument darin, absolut für eines außerhalb, gemäß Wie ein gemeldeter Pfad geschrieben wird. In einem Fall ist es leer: Eine aus einer Registry aufgelöste Entität hat auf diesem Rechner kein verfasstes Dokument, das genannt werden könnte.authoredLengthbeantwortet eine andere Frage – wie viel verfassten Text die Auflösung behalten hat –, und nur ein Aggregate wird mit solchem Text ausgeliefert, lesen Sie die beiden also getrennt statt als Paar.nameist die Identität einer Entität, so geschrieben, wie eine Entität eine andere referenziert, und kann ein Versionssuffix tragen. Dies ist die einzige Anfrage hier, die von einem Namen statt von einem Cursor ausgeht, also ist sie diejenige, die Sie stellen, wenn Sie bereits wissen, welche Entität Sie meinen.releaseist optional und löst den Namen in den Begriffen dieses Release auf – siehe In den Begriffen eines Release antworten. Ein Name, der auf nichts aufgelöst wird, wird abgelehnt, statt mit einem leeren Dokument beantwortet zu werden; siehe Die beiden Ablehnungen nach Namen unterscheiden.namekann stattdessen eine Registry-Referenz sein –oci://<host>/<repository>:<tag>oder@<digest>anstelle von:<tag>–, und die Antwort ist dann die an dieser Koordinate veröffentlichte Entität, gelesen aus ihrer Registry, wobeipublishednennt, was gelesen wurde; siehe Nach einer Koordinate fragen.aggrega/releaseClosure— die Abhängigkeitshülle eines Release: welche Entitäten es erreicht und in welchen aufgelösten Versionen, inentities,librariesundplugins, neben den Identitätenaggregateundmanifest, auf die seine beiden Zeiger aufgelöst wurden, allenmappingDiagnostics, die die Auflösung ausgelöst hat, und dendeprecations, die für das Erreichte verzeichnet sind — in seinem Lockfile und im Plugin-Vertrauensdatensatz daneben, sodass ein zurückgezogenes Plugin, das in einer Verdikt-Rolle angehängt ist, so genannt wird, wie eine zurückgezogene gepinnte Referenz genannt wird.releaseist ein Pfad relativ zum Workspace-Root, der ein Release darin benennt, derselbe Wert, denaggrega/irGraphentgegennimmt, und wird in denselben Formen abgelehnt; er erfordert aus demselben Grund ein Lockfile. Es wird nichts gerendert. Seine Einträge nennen keinesource: Sie sagen, wovon das Release abhängt, nicht, was ein Lauf getan hat, wasaggrega/resolveDependenciesmeldet. Siehe Eine Hülle ist nicht der Graph, denn ein Client, der bereits den Graphen erhält, hat dies nicht.aggrega/attachCandidates— welche Features an einen Knoten angehängt werden dürfen: diejenigen, deren deklarierte Anwendbarkeit die Labels des Knotens erfüllen. Senden Sie genau eine Koordinate.nodebenennt ein Workspace-Dokument über seinenmetadata.name;graphNodebenennt einen Knoten im kompilierten Graphen vonreleaseüber die ID, unter der dieser Graph ihn führt;labelsübergibt direkt eine Label-Menge und benennt nichts, für einen Client, der bereits eine besitzt. Die Antwort wiederholt die Koordinate, für die sie geantwortet hat – leer, wenn es keine zu wiederholen gab –, enthältnodeLabels, die Label-Paare, gegen die der Abgleich ausgewertet wurde,labelSource, das angibt, welche Art von Label-Menge das ist, und jeden Kandidaten alskind,name, Quelldatei undorigin, die ihn adressieren. Die Rückgabe der Labels macht die Antwort aus sich selbst heraus überprüfbar: Ein Client kann erklären, warum ein Feature angeboten wurde, ohne sich eine eigene Vorstellung von den Labels des Knotens zu bilden, denn genau so laufen die Antwort eines Clients und die des Compilers auseinander. Für einen Graphknoten sind die angebotenen Features diejenigen, die das Release dieses Knotens erreicht. NebengraphNodebenenntconnectioneine Verbindung, die die Komponente dieses Knotens zieht – ihrensocketund ihrenalias–, und die Antwort enthält dann auchslots, jeden Slot, den der Socket dieser Verbindung deklariert, mit den Features, die ihn füllen dürfen, odernoSlotReason, wo keiner gefüllt werden darf. Siehe Was Ihnen eine Antwort zu Anhängekandidaten sagt.aggrega/connectionCandidates— womit sich die benannte Entität verbinden darf.nodeist dermetadata.nameeiner Entität, dieselbe Koordinate, dieaggrega/attachCandidatesunter diesem Namen entgegennimmt. Siehe Was Ihnen eine Antwort zu Verbindungskandidaten sagt weiter unten, denn die beiden Hälften der Antwort sind nicht gleich vollständig, und die Antwort sagt, welche welche ist.aggrega/insertionPoint— wohin in einem verfassten Dokument ein neuer Eintrag unter einem benannten Container gehört, so ausgedrückt, dass ein Client ihn anwenden kann, ohne das Dokument selbst zu parsen.filebenennt ein Dokument, das der Workspace enthält, relativ zum Workspace-Root, absolut oder als seinefile://-Adresse; ein Dokument außerhalb des Roots, wie geschrieben oder über einen Link, der aus ihm hinausführt – zur Datei oder zu einem Verzeichnis auf dem Weg –, wird abgelehnt, mit welcher Schreibweise auch immer es benannt wird und ob Sie eine Kopie davon besitzen oder nicht;containerist der strukturelle Pfad vom Dokument-Root zu dem Container, in den der Eintrag gehört, wobei jedes Element ein Mapping-Schlüssel oder eine dezimal geschriebene Sequenzposition ist. Diesen Pfad liefern Sie – der Daemon liest die eigene Struktur des Dokuments und leitet nie aus der Benennung von etwas ab, wohin es gehört. Siehe Was Ihnen eine Antwort zum Einfügepunkt sagt, denn die Position allein reicht nicht aus, um die Bearbeitung anzuwenden.aggrega/attachmentContainer— in welches Dokument ein Feature-Anhang für einen Knoten gehört und in welchen Container darin.graphNodebenennt einen Knoten im kompilierten Graphen vonreleaseüber die ID, unter der dieser Graph ihn führt, und beide sind erforderlich: Eine Knoten-ID ist ein Schlüssel des Graphen eines Release und bedeutet ohne ihn nichts. Die Antwort enthältnode,fileundcontainer– eine Liste von Segmenten genau in der Form, dieaggrega/insertionPointentgegennimmt, sodass sich das Paar ohne Zwischenschritt zusammensetzen lässt. Für einen Anhang an einer Verbindung, die die Komponente des Knotens zieht, fügen Sieconnectionmit ihremsocket, ihremaliasund demdocumenthinzu –aggregateoderrelease–, und die Antwort nennt den eigenenfeatures-Container dieser Verbindung in diesem Dokument. Siehe Was Ihnen eine Antwort zum Anhang-Container sagt, dennfileist Teil der Antwort und nicht etwas, das Sie bereits kennen.aggrega/connectionAtPosition— in den Eintrag welcher Verbindung eine Position in einem Aggregate oder einem Release fällt, beantwortet in den Begriffen, in denen die beiden obigen Anfragen eine Verbindung entgegennehmen.filebenennt das Dokument so, wieaggrega/insertionPointeines benennt, und es wird zuerst aus dem gelesen, was die Sitzung dafür vorhält;positionist die Stelle darin, einelineund eincharacter, von null an gezählt in der Kodierung der Sitzung;releasebenennt das Release, dessen kompilierter Graph die Verbindungen verzeichnet, und ist auch für eine Position im Aggregate erforderlich, denn ein Graphknoten und eine Verbindung existieren nur in einem kompilierten Graphen. Die Antwort enthältgraphNodeundconnection– ihrensocket, ihrenaliasund dasdocument, in dem die Position gelesen wurde –, um sie unverändert anaggrega/attachCandidatesundaggrega/attachmentContainerweiterzugeben, odernoConnectionReason, wo dort keine Verbindung geschrieben ist. Siehe Was Ihnen eine Antwort zur Verbindung an einer Position sagt.aggrega/editDocument— wendet eine begrenzte strukturierte Bearbeitung auf ein verfasstes Dokument an und bewahrt dabei jedes Byte, das sie nicht berührt. Sie ist die andere Hälfte der beiden obigen Lokalisierungsmethoden: Jene sagen, wohin ein Eintrag gehört, und überlassen Ihnen das Zusammensetzen und Anwenden, diese setzt einen zusammen und wendet ihn an.editnennt, welche der vier –add-component,attach-feature,wire-edge,set-value–, und ein Wert außerhalb davon wird abgelehnt statt interpretiert;nodeist der strukturelle Pfad vom Dokument-Root, eine Liste von Segmenten genau in der Form, dieaggrega/insertionPointentgegennimmt;nameist der Schlüssel, unter dem der Eintrag geschrieben wird, undvaluedas, was er enthält, dessen Bedeutung sich auseditergibt;socketwird fürwire-edgegelesen und sonst ignoriert.dryRuntut alles, was die einfache Anfrage tut, außer zu schreiben, und antwortet mit dem bearbeiteten Dokument alscontent, für einen Client, der das Ergebnis zuerst dem Autor vorlegt; dabei wird nichts erstellt, undwrittenist leer.filebenennt das Dokument relativ zum Workspace-Root oder über seinen absoluten Pfad, und ein Dokument außerhalb des Roots – wie geschrieben oder über einen Link, der aus ihm hinausführt, zur Datei oder zu einem Verzeichnis auf dem Weg – wird abgelehnt, ohne dass etwas gelesen oder geschrieben wird. Dies schreibt das Dokument, das Sie benennen, innerhalb des Workspace – es löst keine Abhängigkeit auf, erreicht keine Registry und berührt bei keiner der beiden Zustellarten das Netzwerk, und das Schreiben setzt voraus, dass das zusammengesetzte Dokument gegen das Schema seines eigenen Kinds validiert. Siehe Was Ihnen eine Antwort zur Dokumentbearbeitung sagt, denn der Standard ist das Schreiben, und eine Ablehnung lässt die Datei Byte für Byte so, wie sie war.aggrega/releaseCandidates— die Release-Dokumente des Workspace, den die Anfrage benannt hat, als absolute Pfade. Nimmt den Workspace und sonst nichts entgegen: Die Menge ist eine Eigenschaft dieses Workspace-Roots. Die Zugehörigkeit wird durch das Kind des Dokuments entschieden – daskind:der Datei istRelease– und nicht durch den Dateinamen, sodass ein Release, das ohne konventionelles Präfix benannt ist, angeboten wird, eine Datei, die lediglich wie eines benannt ist, dagegen nicht. Dies ist das, was die Auswahl „Welches Release?“ eines Editors auflisten sollte, denn es ist dieselbe Menge, aus der die unten beschriebene Kaskade für das aktive Release wählt. Die Antwort enthält auchlockfiles, das jedes aufgelistete Release – mit genau der Zeichenkette als Schlüssel, unter derreleaseses aufführt – dem absoluten Pfad seines Lockfiles zuordnet; es ist immer vorhanden und ein leeres Objekt, wenn der Workspace kein Release enthält. Sie enthält außerdemunreadLinkedDirs, das – relativ zum Root, dort, wo der Link liegt – jeden Link nennt, der an einer Stelle steht, an der die Auflistung ein Verzeichnis lesen würde, und zu einem Verzeichnis außerhalb des Workspace-Roots führt: Kein Verzeichnis außerhalb des Roots wird durchsucht, sodass ein Release, das Ihr Editor darin anzeigt, nicht aufgelistet wird, und dieses Feld ermöglicht es einer Auswahl, den Grund zu nennen. Ein Link zu einem Verzeichnis, das Ihre Workspace-Konfiguration untercatalog_dirsaufführt, wird nicht genannt: Die Konfiguration hat es erreicht, als Katalogverzeichnis und nicht als Ort, an dem Releases aufbewahrt werden. Es ist immer vorhanden und leer, wenn es keinen solchen Link gibt. Daneben nenntunreadLinkedFilesauf dieselbe Weise jeden Link, dessen eigener Name auf.yamloder.ymlendet und der zu einer Datei außerhalb des Workspace-Roots führt: Keine solche Datei wird gelesen, was auch immer sie enthält, sodass ein Release, das nur über einen dieser Links erreicht wird, nicht aufgelistet wird, und der Einzel-Release-Schritt der unten beschriebenen Kaskade zählt es nicht. Die Ausnahme ist eine Datei, die Ihre Workspace-Konfiguration als Release nennt – alsbuild.authoring_releaseoder als Schlüssel vonworkspace.releases, beurteilt nach der Datei, zu der der Link führt, sodass das Nennen des Links oder dieser Datei gleich zählt –, die gelesen und an der eigenen Stelle des Links aufgelistet und nicht genannt wird, sofern sie ein Release deklariert; eine, die etwas anderes deklariert, wird nicht aufgelistet, und ihr Link wird genannt. Es ist immer vorhanden und leer, wenn es keinen solchen Link gibt. Wo die eigene Konfigurationsdatei des Workspace oder das CI-eigene Overlay daneben selbst ein Link ist, der aus dem Workspace hinausführt, wird diese Datei hier genannt, wie auch immer die Suche sie behandelt, und die Auflistung wird ohne jede Konfiguration gelesen, sodass ein Release, das die Konfiguration über einen Link genannt hätte, nicht aufgelistet wird; siehe Workspace-Root und aktives Release. Siehe Wo das Lockfile eines Release liegt.aggrega/activeRelease— auf welches Release der von der Anfrage benannte Workspace verweist, als absoluter Pfad in einemrelease-Feld, für einen Client, der entscheidet, was standardmäßig ausgewählt wird. Nimmt den Workspace und sonst nichts entgegen. Das Feld ist immer vorhanden, und ein leerer Wert bedeutet, dass der Workspace auf keines verweist – eine erfolgreiche Antwort und kein Fehler, sodass ein Client, der dies bei jedem Neustart des Daemons aktualisiert, nicht gezwungen wird, einen gewöhnlichen Workspace als Fehlschlag zu behandeln. Ist der Wert leer, enthält die Antwort außerdemreason, eine einzeilige Zusammenfassung dessen, wonach die Kaskade gesucht hat, undtrace, die schrittweise Darstellung davon; beide entfallen, wenn ein Release aufgelöst wurde. Wurde ein Release aufgelöst, enthält die Antwort stattdessenlockfile, den absoluten Pfad des Lockfiles dieses Release, das entfällt, wenn keines aufgelöst wurde. Das genannte Release muss nicht eines sein, dasaggrega/releaseCandidatesauflistet – eine Markierung kann ein Release in einem Verzeichnis nennen, das diese Auflistung auslässt, etwavendor/, oder eines, das ohne YAML-Erweiterung benannt ist –, daher ist diese Antwort der Ort, an dem ein Client das Lockfile des Standard-Release liest. Siehe Wo das Lockfile eines Release liegt. Fragen Sie danach, statt die Antwort aus einer der Eingaben der Kaskade abzuleiten: Eine Eingabe, die die Kaskade letztlich nicht verwendet hat, nennt ein anderes Release als das gewählte. Die Antwort wird berechnet, wenn Sie fragen, sodass eine erneute Anfrage nach dem Schreiben einer Markierung, dem Bearbeiten der Konfiguration oder dem Hinzufügen einer Release-Datei die neue Antwort meldet statt des Workspace in dem Zustand, in dem er beim Start des Daemons war.aggrega/setActiveRelease— legt ein Release als Standard des von der Anfrage benannten Workspace fest, indem die Markierung.aggrega/active-releasedieses Workspace geschrieben wird, und antwortet genau so, wieaggrega/activeReleaseantwortet, sobald die Markierung geschrieben ist. Nimmt den Workspace undreleaseentgegen: einen Pfad relativ zum Workspace-Root, der ein Release darin benennt und demselben Vertrag unterliegt wie dasreleasevonaggrega/irGraph– ein absoluter Pfad, einer, der aus dem Workspace hinaussteigt, und ein leerer Wert werden abgelehnt, ebenso einer, der über einen Link hinausführt, es sei denn, Ihre Workspace-Konfiguration nennt dieses Release. Die Markierung ist eine Zeile, die das Release relativ zum Root nennt, in der Form, die die unten beschriebene Kaskade liest. Sie wird innerhalb des Workspace geschrieben und nirgendwo sonst: Wo.aggregaoder die Markierung selbst ein Link ist, der aus dem Workspace hinausführt – ob der Ort, zu dem er führt, bereits existiert oder nicht –, wird die Anfrage mit dem Fehler invalid-params abgelehnt, dessen Meldung der eigene Satz der Bedingung mit vorangestelltem Kurzcode ist,E0320: …(fatal-halts.md §„A path the operation writes leads through a link out of the directory it must stay inside (Ein Pfad, den die Operation schreibt, führt über einen Link aus dem Verzeichnis hinaus, in dem er bleiben muss)“), die den Link nennt und wohin er führt, und es wird nichts geschrieben; durch einen Link, der innerhalb des Workspace bleibt, wird hindurch geschrieben. Die Antwort nennt, worauf sich die Kaskade festlegt, statt das Gesendete zu wiederholen, und beides unterscheidet sich dort, wobuild.authoring_releaseein Release nennt, da die Konfiguration Vorrang vor der Markierung hat. Legen Sie einen Standard auf diese Weise fest, statt die Datei selbst zu schreiben, damit der Ort, an dem die Markierung landet, nach der Regel beurteilt wird, der jede Datei unterliegt, die das Produkt in den Workspace schreibt – siehe Die Workspace-Grenze.aggrega/effectiveConfiguration— die für den von der Anfrage benannten Workspace geltende Konfiguration und die Ebene, aus der jede Einstellung stammt. Nimmt den Workspace und sonst nichts entgegen: Die Antwort ist eine Eigenschaft dieses Workspace.layerslistet die Konfigurationsdateien und Umgebungsüberschreibungen auf, die beigetragen haben, mit der niedrigsten Priorität zuerst;settingsenthält jede zugeordnete Einstellung mit ihrem gepunkteten Namen, ihrem effektiven Wert und dersource, die sie bestimmt hat. Einesourcewird genau wie der passende Eintrag inlayersgeschrieben, sodass sich beide direkt verknüpfen lassen. Siehe Was die Antwort zur effektiven Konfiguration abdeckt dazu, welche Ebene einesourcenennt und welche Grenzen für die Bedeutung einer Zeile gelten.aggrega/configInit— legt eine funktionsfähige Konfiguration an, indem eine Registry und ihre Vertrauensrichtlinie für Signaturen registriert werden, sodass ein neuer Rechner signierte Artefakte abrufen und verifizieren kann, ohne YAML von Hand zu bearbeiten.registryist optional, und ein fehlender Wert legt den offiziellen Hub an, denselben Standard, denaggrega config initverwendet;hostin der Antwort nennt, welcher verwendet wurde.globalundworkspacesind die Überschreibungen des Schreibziels, und das Senden beider wird abgelehnt. Es lehnt es ab, eine vorhandene Konfigurationsdatei zu überschreiben, und nennt die Datei – senden Sieforce, um trotzdem fortzufahren, was den Registry-Eintrag in das Vorhandene einfügt und die übrigen Einstellungen bewahrt.dryRuntut alles, was die einfache Anfrage tut, außer zu schreiben, und antwortet mit der angelegten Konfiguration alscontent, für einen Client, der das Dokument dem Autor vorlegt, bevor es gespeichert wird; dabei wird nichts erstellt, undwrittenist false. Die Ablehnung wegen einer vorhandenen Datei gilt auch unterdryRun, senden Sie alsoforcezusammen damit, um die Zusammenführung als Antwort zu erhalten, die ein überschreibendes Schreiben erzeugen würde. In einem Offline-Workspace kann nur der offizielle Hub angelegt werden: Diese Anfrage nimmt keine Identitäten und keinen Schlüssel entgegen, sodass jede andere Registry genau so abgelehnt wird, wieaggrega/registryAddsie ablehnt, Kurzcode und Satz eingeschlossen, und stattdessen über diese Anfrage mit einer von Hand angegebenen Richtlinie hinzugefügt wird. Die Antwort enthälthost,scope,trustundwrittensowieexisted, true, wo die Konfigurationsdatei bereits vorhanden war – sodass der Registry-Eintrag in sie eingefügt statt eine neue Datei erstellt wird –, und fehlend, wo die Datei erstellt wird. Dies schreibt standardmäßig die globale Konfiguration – siehe Eine Registry erreichen und schreiben.aggrega/configCapture— friert die effektive build-kritische Konfiguration in die eigene Konfigurationsdatei dieses Workspace ein, sodass der Workspace ohne die darunterliegende globale Konfiguration des Rechners gleich gebaut wird. Nimmt kein Schreibziel entgegen: Das Einfrieren dient dazu, einen Workspace in sich geschlossen zu machen, daher schreibt es immer die Datei dieses Workspace.allPluginserweitert die eingefrorene Menge von den Sockets, die die gerenderte Ausgabe bestimmen – den Provider-Bindungen und den Governance-Anhängen für Label-Transformationen –, auf jeden Plugin-Socket und fügt die Verdict-Governance- und Linter-Gates sowie den Import-Socket hinzu. Die Antwort enthältconfigFile,workspaceRoot,captured,socketsundcatalogDirs. Siehe Was ein Schreiben der Konfiguration hinterlässt, denn die Antwort nennt ein Dokument, das nun existiert, und der nächste Schritt eines Clients ist, es zu öffnen.aggrega/skillsInstall— schreibt den in dieses Binary eingebauten Aggrega-Skill in den Skill-Ordner jedes Assistenten, den die Anfrage nennt, dieselbe Installation, dieaggrega skills installan einem Terminal durchführt.agentslistet die Assistenten nach Bezeichner auf, den Bezeichnern, dieaggrega/skillsListmeldet; ein zweimal angegebener Bezeichner wird einmal installiert, und wo mehrere der genannten Assistenten einen gemeinsamen Ordner lesen, wird der Skill dort einmal geschrieben. Eine Projektinstallation erfordert es. Eine Anfrage mitglobal, die keinen nennt, installiert für die auf diesem Rechner gefundenen Assistenten, wie esaggrega skills install --globalohne--agenttut — für jeden, dessen Konfigurationsordner im Home-Verzeichnis liegt oder dessen Befehl imPATHder Umgebung des Daemons steht —, und wird abgelehnt, ohne dass etwas geschrieben wird, wo keiner gefunden wird; es wird nichts abgefragt, undinstallednennt die Assistenten, für die sie geschrieben hat. Ohnegloballandet der Skill im Projektordner jedes Assistenten innerhalb des Workspace, den die Anfrage nennt, nie in dem Verzeichnis, in dem der Daemon gestartet wurde; mitglobal: truelandet er im benutzerspezifischen Ordner jedes Assistenten unter dem Home-Verzeichnis, das die Umgebung des Daemons nennt (HOMEoder unter WindowsUSERPROFILE). Jedes Ziel wird geprüft, bevor irgendetwas geschrieben wird, sodass eine Ablehnung jeden Ordner so lässt, wie er war: Ein Bezeichner, für den kein Skill-Ordner bekannt ist, wird abgelehnt, wobei er und die vorhandenen Bezeichner genannt werden, und eine Datei an einem Ziel, die nicht die Kommentarzeile trägt, die jede geschriebene Kopie des Skills trägt, wird unter Nennung ihres Pfads abgelehnt. Eine Kopie, die diese Zeile trägt — eine, die eine frühere Installation geschrieben hat, oder eine aus dem veröffentlichten Skills-Repository —, wird ersetzt; so bringt ein neueresaggregaden Skill auf seine eigene Version. Ein Projektordner, der über einen aus dem Workspace hinausführenden Link erreicht wird, wird abgelehnt, ohne dass etwas geschrieben wird, wie jeder Schreibvorgang, den der Daemon in einem Workspace ausführt — siehe Die Workspace-Grenze. Die Antwort enthältskill,installed— einen Eintrag pro geschriebenem Ordner, in der Reihenfolge, in der die Assistenten genannt wurden, jeweils mit denagents, die ihn lesen, dem absolutenfolderundreplaced— sowiescope. Mitglobalschreibt dies Ordner, die jedes Projekt auf dem Rechner liest — siehe Eine Registry erreichen und schreiben.aggrega/skillsList— die Skills, die dieses Binary mitliefert, und jeder Assistent, für denaggrega/skillsInstallsie schreiben kann, die Auflistung, dieaggrega skills listausgibt. Nimmt den Workspace und sonst nichts entgegen und liest nichts daraus.skillsenthältnameunddescriptionjedes Skills;agentsenthält für jeden Assistentenid,name,projectFolder— relativ zur Wurzel eines Projekts, die auf dieser Oberfläche der Workspace ist, den eine Anfrage nennt — unduserFolder, relativ zum Home-Verzeichnis, beide durch Schrägstriche getrennt, sortiert nach Bezeichner. Es schreibt nichts und erreicht nichts.aggrega/pluginAdd— durchsucht die konfigurierte Registry nach einem Plugin eines benannten Typs und fügt es der Konfiguration hinzu.typeundquerysind beide erforderlich:typeist einer vonprovider,governance,linter,importerundcli, undquerywird mit den Plugin-Namen dieses Typs abgeglichen und muss auf genau einen aufgelöst werden, sodass eine Abfrage, die auf mehrere passt, unter Angabe der Kandidaten abgelehnt wird, statt willkürlich aufgelöst zu werden.capabilitynennt die Capability, die eineprovider-Bindung bedient, und ist dort erforderlich;rolenennt die Rolle einesgovernance-Anhangs –label-transform,ir-verdictoderrender-verdict– und ist dort erforderlich; jedes wird nur für seinen eigenen Typ gelesen und bei jedem anderen abgelehnt, denn ein Feld, das stillschweigend nichts täte, sähe so aus, als hätte es funktioniert.acceptCapabilitiesist fürclierforderlich und bestätigt die deklarierten Capabilities dieses Plugins: Der Terminalbefehl erhält diese Entscheidung durch Nachfragen, und diese Oberfläche hat niemanden, den sie fragen könnte, also holt der Aufrufer sie ein und sendet sie.globalundworkspacesind die Überschreibungen des Schreibziels, und das Senden beider wird abgelehnt.dryRuntut alles, was die einfache Anfrage tut, außer zu schreiben, und antwortet mit der resultierenden Konfiguration alscontent; es wird nichts erstellt oder geändert, undwrittenist false. Die Registry wird trotzdem durchsucht und die Version trotzdem aufgelöst, denn die Identität in diesem Inhalt ist die Identität, die ein Schreiben festgelegt hätte.dryRunwird beim Typcliabgelehnt, statt ignoriert zu werden: Was das Hinzufügen einer Befehlserweiterung verzeichnet, ist der Inhalts-Digest der Bytes, die es verifiziert hat, ein Eintrag, den der Compiler pflegt, statt eines Inhalts, den jemand bearbeitet, und das Hinzufügen legt diese Bytes dabei im Cache ab – daher wird es geschrieben statt zurückgegeben. Die Version wird für Sie festgelegt – die Abfrage wird auf ein Plugin aufgelöst, und in den Eintrag wird die Version geschrieben, die sie als<name>:<version>nennt, oder andernfalls die höchste veröffentlichte Version des Plugins; eine genannte Version, die eine Rücknahme, der dieser Workspace vertraut, zurückgezogen hat, wird trotzdem festgelegt, und die Antwort enthältwithdrawn: true. Dies erreicht eine Registry, und ein Hinzufügen vom Typcli, das keinen der beiden Geltungsbereiche nennt, schreibt die globale Konfiguration – siehe Eine Registry erreichen und schreiben. Siehe Was Ihnen eine Plugin-Änderung sagt.aggrega/pluginRemove— entfernt den Eintrag eines konfigurierten Plugins, sodass es nicht mehr beteiligt ist.typeist dieselbe Menge, die ein Hinzufügen entgegennimmt, undqueryidentifiziert den Eintrag: den Kurznamen des Plugins, seine festgelegte Referenz oder – fürprovider– die Capability, die die Bindung bedient. Beide sind erforderlich.globalundworkspacesind dieselben Überschreibungen des Schreibziels und werden zusammen auf dieselbe Weise abgelehnt. Eine Abfrage, die auf keinen Eintrag passt, wird abgelehnt, statt als Erfolg über einer unveränderten Konfiguration beantwortet zu werden, sodass einem Aufrufer nie mitgeteilt wird, ein Plugin sei nicht mehr beteiligt, wenn dem nicht so ist, und ein Tippfehler nie ein anderes Plugin entfernt. Es kontaktiert keine Registry: Ein Entfernen arbeitet allein auf dem Konfigurationstext. Ein Entfernen vom Typcli, das keinen der beiden Geltungsbereiche nennt, schreibt die globale Konfiguration – siehe Eine Registry erreichen und schreiben. Siehe Was Ihnen eine Plugin-Änderung sagt.aggrega/pluginSync— gleicht die maschinenverwalteten Einträge einer Plugin-Entität mit ihrem Modul ab: die Menge der Host-Funktionen, abgeleitet aus den eigenen Importen des Moduls, und das Befehlsabbild, gelesen aus der Selbstauskunft des Moduls. Keiner der beiden Einträge wird von Hand verfasst, denn beide haben ihre maßgebliche Quelle im Modul. Beide Felder sind erforderlich, und keines hat einen Standardwert – die Einträge werden aus dem Modul abgeleitet, sodass ein Abgleich, der keines nennt, nichts hat, woran er abgleichen könnte –, und beide sind Pfade relativ zum Workspace-Root, die abgelehnt werden, wenn sie absolut sind oder außerhalb davon aufgelöst werden, wie geschrieben oder über einen Link. Nur diese beiden Blöcke ändern sich: Jedes andere Byte wird unverändert übernommen, Kommentare, Leerzeilen und Anführungsstil eingeschlossen, und eine Datei, die bereits verzeichnet, was das Modul impliziert, bleibt Byte für Byte identisch und wird als unverändert gemeldet. Dies schreibt die Entitätsdatei, die Sie benennen, innerhalb des Workspace, und es kontaktiert keine Registry. Siehe Was Ihnen eine Plugin-Änderung sagt.aggrega/pluginGenCatalog— erzeugt eine Plugin-Entität pro ausgewähltem Guest und führt dabei die aus der Selbstauskunft des Guests abgeleiteten Vertragsfelder mit einem von Hand geschriebenen Overlay pro Plugin zusammen.fromEmbeddedundpluginsind die beiden Auswahlmodi, und genau einer davon gilt: jeder Guest, den dieses Binary enthält, oder ein Modul unter einem von Ihnen angegebenen Pfad; beide oder keinen anzugeben wird abgelehnt statt aufgelöst.overlayist erforderlich und ist beifromEmbeddedein Verzeichnis mit Overlays oder beiplugineine einzelne Overlay-Datei — gibt es mehrere, wird ein Overlay einem Guest anhand seiner Identität zugeordnet, und gibt es nur einen, ist nichts zuzuordnen.outputDirist bei beiden Auslieferungsarten erforderlich, unddryRunentbindet nicht davon: Ein Probelauf ändert, wohin der Inhalt geht, nicht, für welche Datei er Inhalt ist, sodass jedes zurückgegebene Dokument weiterhin den Pfad nennt, für den es bestimmt ist, und dieser Pfad aus diesem Verzeichnis gebildet wird. Die drei Pfade werden hier nicht gleich beurteilt, und die Unterscheidung folgt dem, was die Generierung mit jedem tut.pluginundoverlaywerden gelesen, und beide sind Dateien, die Sie ausgewählt haben — ein Modul landet in dem Verzeichnis, in das seine Toolchain baut, und sein Overlay wird daneben geschrieben —, daher darf jeder absolut sein und wird dort gelesen, wo er tatsächlich liegt. InoutputDirwird geschrieben, daher ist es relativ zum Workspace-Stammverzeichnis und wird abgelehnt, wenn es absolut ist oder außerhalb davon aufgelöst wird, so wie geschrieben oder über einen Link — ein noch nicht angelegtes Verzeichnis unterhalb eines verlinkten Verzeichnisses, das nach außen führt, wird so abgelehnt wie dieses Verzeichnis. Ein erneuter Lauf über unveränderte Eingaben erzeugt byteidentische Entitäten. Dies schreibt die erzeugten Entitäten unteroutputDirinnerhalb des Workspace, soferndryRunsie nicht stattdessen als Inhalt anfordert. Siehe Was Ihnen eine Plugin-Änderung mitteilt.aggrega/getSchema— das JSON Schema für eine Entitäts- oder Vertragsart, gelesen aus der in das laufende Binary kompilierten Kopie.kindist das kleingeschriebene, mit Bindestrichen verbundene Schema-Token —component,aggregate,release,recipe,ir,wasm-providerund so weiter — und ist optional, weil es auswählt, welche von zwei Fragen Sie stellen. Nennen Sie eine Art, enthält die Antwortkindundschema, das Schema als JSON-Dokument statt als Zeichenkette, die eines enthält. Nennen Sie keine, enthält die Antwort stattdessenkindsundentityKinds: welche Arten Sie nennen dürfen, in zwei Breiten.kindsist jedes Token, nach dem dieses Binary gefragt werden kann, in derselben Reihenfolge, in deraggrega get-schema --listsie ausgibt.entityKindsist die engere Menge der Arten, von denen ein Autor ein Dokument schreibt; jeder Eintrag enthält daskind-Token, das zurückzusenden ist, den WertdocumentKind, der in das eigenekind:-Feld des Dokuments gehört, undacceptedBy, das angibt, ob die Validierung einer einzelnen Entität, die Veröffentlichung und die Inspektion nach Namen ein Dokument dieser Art akzeptieren. Lesen Sie Welche Arten Sie einem Autor anbieten dürfen, bevor Sie aus einer der beiden eine Auswahl bauen. Die Schema-Antwort und die Aufzählung werden nie kombiniert, sodass sich aus der Antwort ablesen lässt, welche Frage beantwortet wurde. Ein Token, dem kein Schema entspricht, wird mit der gesamten gültigen Menge in der Meldung abgelehnt, sodass ein Tippfehler ohne zweiten Aufruf korrigiert wird. Es nimmt nichts aus dem Workspace, kontaktiert keine Registry und schreibt nichts, daher antwortet es auch in einem völlig leeren Workspace — und genau das macht es nutzbar, um die Schema-Zuordnung eines Editors an das Binary zu binden, das der Editor tatsächlich ansteuert, statt an irgendeine anderswo installierte Kopie der Schemas.aggrega/scaffoldEntity— ein Startdokument für eine Entitätsart: genau die Felder, die das Schema dieser Art verlangt, mit ausgefüllten festen WertenapiVersionundkindund einem Platzhalter überall dort, wo ein Wert benötigt wird.kindist erforderlich und ist das kleingeschriebene, mit Bindestrichen verbundene Schema-Token —component,aggregate,release,recipe,manifest,featureund so weiter;aggrega/getSchemaohnekindgibt an, welche Token Sie senden dürfen, und ein Token, dem kein Schema entspricht, wird mit dieser Menge in der Meldung abgelehnt, sodass ein Tippfehler ohne zweiten Aufruf korrigiert wird. Ein Client, der dem Autor die Wahl einer Art anbietet, liestentityKindsdieser Methode, also die Menge der Arten, von denen sich ein Dokument schreiben lässt.nameist optional und belegtmetadata.namevor für Arten, deren Schema einen verlangt. Die Antwort enthältkindundskeleton. Siehe Was Ihnen eine Scaffold-Antwort liefert, denn die Antwort ist ein zu schreibendes Dokument und kein bereits geschriebenes. Das Gerüst wird aus demselben Schema abgeleitet, dasaggrega/getSchemameldet, sodass beide aus einer Quelle antworten. Wirdexamplestattkindgesendet, schreibt die Methode eines der ausführbaren Beispiele der Dokumentation in ein neues Verzeichnis des Workspace, wie esaggrega scaffold --examplean einem Terminal tut; wirdlist: trueallein gesendet, antwortet sie mit allen vorhandenen Beispielen und schreibt nichts. Beide Formen benötigen den Workspace, daher nennt eine Anfrage für eine der beiden ihn inworkspaceRoot, und eine, die keinen nennt, wird abgelehnt.dirnennt das neue Verzeichnis relativ zum Workspace-Root und ist standardmäßig der Name des Beispiels; ein absoluter Wert oder einer, der außerhalb des Roots aufgelöst wird — wie geschrieben oder über einen Link —, wird abgelehnt, bevor irgendetwas gelesen wird, und ein Verzeichnis, das irgendetwas enthält, wird abgelehnt und so belassen, wie es ist. Die Antwort auf eine Auflistung enthältexamples, jedes mit seinemname,levelundsummary; die Antwort auf einen Schreibvorgang enthältexample,dir,files— jede geschriebene Datei, relativ zudir—,next, die Befehle, die die Seite des Beispiels für seinen Build angibt, fehlend, wo sie keine angibt, undversion, die Dokumentationsversion, aus der das Beispiel gelesen wurde. Felder zweier Formen, die zusammen gesendet werden —kindmitexample,listmitexampleoderkind,namemitexampleoderlistoderdirohneexample—, werden abgelehnt, bevor irgendetwas gelesen wird, mit den Worten, mit denen das Assistenten-Tool sie ablehnt. Ein Schreibvorgang beschafft das Dokumentations-Bundle, wo der Rechner keine Kopie hält, die die eigene Signaturprüfung des Workspace zulässt, und schreibt innerhalb des Workspace — siehe Eine Registry erreichen und schreiben.aggrega/import— wandelt eine fremde Quellbeschreibung in Entwürfe von Aggrega-Authoring-Dateien um, dieselbe Umwandlung, dieaggrega importim Terminal durchführt.sourceist erforderlich und nennt die zu konvertierende Datei oder das Verzeichnis, entweder als absoluten Pfad oder relativ zum Workspace-Stammverzeichnis — eine von einem anderen Werkzeug exportierte Beschreibung liegt dort, wo Sie sie gespeichert haben, daher wird sie dort gelesen, wo sie tatsächlich liegt, statt nur innerhalb des Workspace. Ein Verzeichnis wird so gelesen, wieaggrega importeines liest: die Dateien darin, die die deklarierten Dateimuster des Importers auswählen, ohne den Build-Ausgabeordnerdist/des Workspace, und auf sich selbst beschränkt, wo immer es liegt, sodass keinem Link darin nach außen gefolgt wird.outputDirist optional und nennt das Verzeichnis, in das die Entwürfe gehen, und es folgt diesem Vertrag nicht: Hinein wird geschrieben, daher ist es ein Pfad innerhalb des Workspace, und ein absoluter Wert oder einer, der außerhalb des Stammverzeichnisses aufgelöst wird — so wie geschrieben oder über einen Link, einschließlich eines noch nicht angelegten Verzeichnisses darunter —, wird abgelehnt. Lassen Sie es weg, gehen die Entwürfe unter das Workspace-Stammverzeichnis, wohinaggrega importsie schreibt, wenn es kein Ziel nennt — auch unterdryRun.formatnennt das Quellformat ausdrücklich; lassen Sie es weg, wird das Format an den Signaturen erkannt, die die Importer deklarieren — die des Workspace-Katalogs ebenso wie die Core-Importer des Compilers —, und eine Quelle, die keiner erkennt oder die Importer mehrerer Formate erkennen, wird mit der Bitte umformatabgelehnt, statt geraten zu werden.targetnennt eine Provider-Capability wiecomposeoderhelm— das Wort, an dasspec.capabilityeines Recipe bindet — und entwirft neben den Entwürfen des Importers das Manifest, gegen das das entworfene Release für diesen Provider baut, genau wieaggrega import --target:manifest.yaml, das jeden Komponententyp und jeden Funktionstyp, den die Entwürfe benötigen — einschließlich der Typen eines Katalog-Aggregate, aus dem sich das entworfene zusammensetzt —, dem Recipe oder Funktionsrezept dieser Capability zuordnet, das der Katalog des Workspace dafür anbietet, über seinen Capability-qualifizierten Namen ohne Version: dem einzigen vorhandenen oder, unter mehreren, dem nach dem Typ benannten.spec.manifestdes Release wird darauf gesetzt; ein Typ ohne eines davon oder mit mehreren, von denen keines so benannt ist, bleibt unzugeordnet, mit einemwarn-Befund, der ihn nennt, und eine Zuordnung, die ein Importer selbst entworfen hat, bleibt erhalten, wo der Katalog sie für diesen Typ und diese Capability anbietet, und wird andernfalls mit einemwarn-Befund verworfen. Eintarget, an das kein Recipe im Katalog bindet, wird abgelehnt, bevor der Importer läuft, unter Nennung des Targets und der Capabilities, an die die Recipes des Katalogs binden, und es wird nichts geschrieben; lassen Sie es weg, wird kein Manifest entworfen — außer untersync, das für das Target entwirft, das der Datensatz des früheren Imports nennt. Ein Core-Importer, den die Maschine noch nicht hat, wird vom ersten Import geholt, der ihn braucht — siehe Was Ihnen eine Import-Antwort mitteilt.dryRuntut alles, was die einfache Anfrage tut, außer zu schreiben, und antwortet mit den Entwürfen als Inhalt, für einen Client, der sie dem Autor zuerst vorlegt; dabei wird nichts angelegt, undwrittenist leer.syncbringt das, was ein früherer Import inoutputDirentworfen hat, auf den Stand der Quelle und ändert nur, was der Import geschrieben hat, wieaggrega import --sync; ohne es wird eine Anfrage abgelehnt, deren Entwürfe ein bereits vorhandenes Aggregate überschreiben würden. Die Antwort enthältformat,outputDir,written,files,drift,diagnostics,decisionsundhalted. Siehe Was Ihnen eine Import-Antwort mitteilt, denn eine Quelle, die der Importer nicht vollständig konvertieren konnte, ist eine erfolgreiche Antwort und kein Fehler.aggrega/explainError— was der Compiler über die Bedingung deklariert, die ein Code nennt, und die veröffentlichten Einträge, die die Korrektur im Authoring erklären.codeist erforderlich und nimmt einen der beiden Bezeichner einer Bedingung an: den Kurzcode, den eine Diagnose inshortCodeenthält, oder den beschreibenden incode. Es ist die Erweiterung eines Codes, den die Diagnosen auf dieser Verbindung bereits enthalten, und es ist dieselbe Antwort, dieaggrega explainim Terminal ausgibt. Die Antwort enthält immer die Bedingung —shortCode,codeundmessage—, denn so viel ist im Binary deklariert und braucht kein Netzwerk;entriesenthält die veröffentlichte Schritt-für-Schritt-Anleitung, undnotesagt, warum sie fehlt, wo sie fehlt. Dies beschafft das Dokumentationspaket, wenn die Maschine keine Kopie hat, die die eigene Signaturprüfung des Workspace zulässt — siehe Eine Registry erreichen und schreiben. Siehe Einen Code erweitern, den eine Diagnose enthielt.aggrega/invalidate— ein Cache-Invalidierungssignal vom Datei-Watcher des Editors.
Benachrichtigungen:
$/cancelRequest— vom Client zum Server: beendet die laufende Anfrage, die unter dieser ID gesendet wurde. Der Daemon bricht die Arbeit dieser Anfrage ab; eine Operation bemerkt den Abbruch an ihrer nächsten Schrittgrenze statt sofort, sodass bereits laufende Arbeit noch einen Moment weiterläuft. Eine ID abzubrechen, unter der nichts läuft, ist eine sichere Nulloperation.$/progress— vom Server zum Client: was eine lange Operation gerade tut, während sie es tut, auf dem Token, auf dem die Anfrage berichtet werden wollte. Wird nur für eine Anfrage gesendet, die eines enthielt. Siehe Eine lange Operation beobachten.aggrega/shutdown— beginnt ein kooperatives Leerlaufen: laufende Anfragen werden abgeschlossen, neue Anfragen werden abgelehnt, dann beendet sich der Daemon.aggrega/publishDiagnostics— eine vom Server gepushte Menge von Diagnosen (verwendet für Warnungen zu Lockfile-Abweichungen und für den Zustand beim Start). Jeder Eintrag enthält einsource, das nennt, welche der Diagnoseschichten des Daemons ihn ausgelöst hat:aggregafür einen Befund zu den geschriebenen Dokumenten,aggrega-buildfür einen Hinweis, den ein Build ausgelöst hat — jeden Hinweis, den er ausgelöst hat, also dieselbe Menge, dieaggrega buildausgibt —, undaggrega-lintfür einen Befund zu den Veröffentlichungskonventionen, dieselben Befunde, dieaggrega lintausgibt. Das Feld ist in jedem Eintrag immer vorhanden, sodass ein Client sie gruppieren kann, statt eine einzige undifferenzierte Liste anzuzeigen, und nie eine fehlende Quelle von einer der Schichten unterscheiden muss. Ein Frame wird für eine Datei nur gesendet, wenn sich ihre Menge von der unterscheidet, die diesem Client zuletzt mitgeteilt wurde, sodass eine Anfrage, die dieselben Befunde neu berechnet, nichts sendet; der erste Frame einer Datei und ein Frame, der die Menge einer Datei leert, sind beide Unterschiede und werden immer gesendet.
Den Prozess selbst zum Anhalten aufzufordern, erreicht den Daemon zu denselben Bedingungen. Ein Interrupt aus einem Terminal oder eine Beendigungsanforderung von einem Supervisor oder einer Container-Runtime beginnt das Leerlaufen, das aggrega/shutdown beginnt: laufende Anfragen werden abgeschlossen, neue Anfragen werden abgelehnt, dann beendet sich der Daemon. Eine zweite Anforderung beendet den Prozess sofort. Ein Client, der den Daemon startet, kann ihn auf beide Arten anhalten, und einer, der ihn über das Protokoll anhält, und einer, der ihm ein Signal sendet, erhalten dasselbe Leerlaufen.
Live-Validierung
Bei jedem aggrega/validate validiert der Daemon den Editorpuffer gegen das Schema des Dokuments und gibt Diagnosen zurück, die auf den fehlerhaften Schlüssel zeigen — dasselbe Urteil, das ein Build fällen würde, auf ungespeichertem Inhalt. Eine Anfrage, die kein content sendet, fragt nach der Datei, wie sie auf der Festplatte liegt; ein leer gesendetes content ist ein leerer Puffer, keine Anfrage nach der Datei. Eine ohne ihren Inhalt gesendete Datei muss eine sein, die der Workspace enthält und die gelesen werden kann — eine Datei außerhalb des Workspace, eine über einen nach außen führenden Link erreichte oder eine nicht vorhandene wird mit dem Code invalid-params abgelehnt. Katalogentitäten, Aggregates, Manifests und Releases werden an ihrem apiVersion und kind erkannt. Die beiden Dokumente ohne einen solchen Kopf — die Workspace-Konfiguration .aggrega-config.yaml und das Lockfile des Release, das die Anfrage nennt — werden stattdessen am Dateinamen erkannt, sodass auch ein unsinniger oder fehlgeformter Schlüssel in einem von beiden live unterkringelt wird. Dateien, die keine Aggrega-Dokumente sind — Helm-Chart-Templates, Compose-Dateien, Kubernetes-Manifeste und .lock-Dateien anderer Ökosysteme wie Cargo.lock oder flake.lock —, erhalten keine Diagnosen; der Daemon meldet nie etwas zu fremden Dateien.
Ein noch ausstehender Platzhalter wird an seinem Schlüssel genannt, zusammen mit dem, was er annimmt. Eine Katalogentität einer Art, die aggrega validate als einzelne Entität prüft, wird auch auf die erforderlichen Werte gelesen, die sie als leere Zeichenkette lässt, nach der Lesart, die dieser Befehl anwendet, sodass der Daemon jeden Platzhalter nennt, den der Befehl für dieselben Bytes nennt. Jeder Platzhalter ist ein Eintrag: Sein message sagt, dass der Schlüssel ein noch ausstehender Platzhalter ist, sein suggest sagt, was der Wert annimmt, und sein keyPath enthält den punktierten Pfad des Schlüssels. Der Eintrag tritt an die Stelle des eigenen Befunds des Schemas für diesen leeren Wert, und jeder andere Befund zum Dokument wird so gemeldet, wie die Schemaprüfung ihn meldet. Ein Platzhalter, den das Schema leer zulässt, wird ebenfalls genannt, obwohl die Schemaprüfung nichts dazu meldet — capability und implements eines entworfenen Recipe oder FeatureRecipe sind diejenigen, denen Sie begegnen werden. Wo die Schemaprüfung das Dokument ebenfalls ablehnt, trägt jeder Eintrag den Code dieser Prüfung, E0215, und wo sie es akzeptiert, tragen die Einträge keinen Code: dieselben Bezeichner, die der Bericht des Befehls für diese Bytes trägt. Ein Eintrag wird an dem Schlüssel gezeichnet, der den leeren Wert enthält, in der Zeile, in der der Befehl ihn nennt — auch bei einem Schlüssel, dessen eigener Name einen Punkt enthält, wie dem Label component.aggrega.ai/type, wo ein Befund, den die Schemaprüfung zu diesem Schlüssel meldet, am umschließenden Schlüssel gezeichnet wird —, und keyPath nennt den Schlüssel vollständig. Dies gilt unabhängig davon, ob die Anfrage ein Release nennt, denn es ist eine Frage, die das Dokument selbst beantwortet, und zu einem Dokument, das noch einen Wert schuldet, werden die Veröffentlichungskonventionen noch nicht befragt: Diese Schicht wird für es geleert, wie für ein Dokument, dessen Form das Schema ablehnt.
Jede Anfrage nennt das Release, um das es geht, und der Daemon hält kein eigenes. Die semantischen Prüfungen lösen den Abhängigkeitsabschluss dieses Release auf und lesen das Lockfile dieses Release für seine Pins — oder lesen bei einer Katalogentität die Katalogverzeichnisse, mit denen dieses Release baut, wie der nächste Absatz beschreibt —, sodass zwei Anfragen, die zwei Releases nennen, jeweils zu dem Release beantwortet werden, das sie genannt haben. Nichts wird zwischen ihnen übertragen: Es gibt kein ausgewähltes Release, das zu ändern wäre, und das Release zu wechseln, gegen das Sie validieren, ist ein anderer Wert in der nächsten Anfrage, nicht etwas, das der Daemon vergessen müsste.
Eine zusammen mit einem Release genannte Katalogentität wird als einzelne Entität geprüft, in den Begriffen dieses Release. Ein file, das eine Component, ein Feature, ein Recipe, ein FeatureRecipe oder ein Plugin enthält und mit einem release gesendet wird, erhält die Prüfung, die aggrega validate <path> --release <release> ausführt, über den ungespeicherten Puffer des Editors: Seine Referenzen — die Component, die ein Recipe implementiert, eine Bibliothek, auf die eine Säule verweist — werden über die Katalogverzeichnisse aufgelöst, die die Workspace-Konfiguration diesem Release gibt, sodass eine Datei in den Begriffen des Release, das mit ihr baut, sauber sein und in den Begriffen eines Release scheitern kann, dessen Verzeichnisse nicht enthalten, worauf sie verweist. Das ist das Urteil, das die Befehlszeile und das validate-Werkzeug von aggrega mcp für dieselbe Entität neben demselben Release fällen, und wie deren Prüfung durchläuft sie keinen Abschluss und liest kein Lockfile. Ein blockierender Befund ist ein Fehlereintrag in den eigenen Worten der Prüfung und mit ihren Codes, gezeichnet an dem Schlüssel, den er in der Entität nennt, und, wo er keinen nennt, am kind:-Schlüssel der Entität, wie Was ein Diagnoseeintrag enthält beschreibt — es sei denn, ein Build meldet diesen Fehler bereits für die Datei; dann ist der Eintrag des Builds die einzige Meldung; ein Hinweis, den die Prüfung beim Lesen des Katalogs auslöst, ist ein Warnungseintrag davor; eine saubere Prüfung über Verzeichnisse, die alle vorhanden sind, liefert keinen Eintrag. Eine fehlgeschlagene Assertion — eine, die fail aufruft, im Recipe oder in der Component, die es implementiert — ist hier kein blockierender Befund, sondern ein Warnungseintrag in den Worten der Prüfung und mit ihren Codes, abgeschlossen durch den Satz A Release must satisfy this assertion before a build of it can pass. und dort gezeichnet, wo der blockierende Befund stünde: die Assertion eines Recipe am eigenen Schlüssel dieser Assertion unter assertions, die einer Component am kind:-Schlüssel des Recipe. Wie ein blockierender Befund tritt er hinter den Eintrag eines Builds zurück, der denselben Fehler für die Datei meldet. Die Prüfung baut die Entität um Platzhalter und Schema-Standardwerte statt um die Werte, die ein Release setzt, daher kann sie eine Assertion, die auf ein Release wartet, nicht von einer defekten unterscheiden und überlässt das Urteil einem Build, der dieselbe Assertion als Fehler meldet (eine fehlgeschlagene Assertion ist eine Warnung). Ein Verzeichnis, das die Workspace-Konfiguration für das Release auflistet und das kein Verzeichnis ist — dort existiert etwa nichts —, beendet die Prüfung an dieser Stelle: Die Datei trägt statt des Urteils der Prüfung einen einzigen Fehlereintrag, die Ablehnung, die jeder Befehl für dieses Verzeichnis ausgibt und die den Eintrag, die Konfigurationsdatei und die Zeile, die ihn auflistet, sowie die Einstellung nennt (Woher lokale Entitäten gelesen werden). Ein release, das keine Datei oder ein Verzeichnis nennt, wird für die Datei mit dem Satz beantwortet, mit dem die Befehlszeile es ablehnt, statt in den Begriffen des Workspace geprüft zu werden. Was ein Build einer einzelnen Entität nicht ersetzen kann, wird so beurteilt, wie die Befehlszeile es beurteilt, und was die Befehlszeile beiseitelässt oder nicht prüft, liefert hier keinen Eintrag — siehe was die Korrektheit einer einzelnen Entität nicht prüft und, für ein Recipe, dessen Template einen Wert liest, den nur eine Kante der Topologie oder ein angehängter Berechtigungsnachweis liefert, Korrektheit einer einzelnen Entität. Das eigene Aggregate des Release, ein Manifest, ein Release und eine Bibliothek werden nicht einzeln geprüft, weil die Einzelentitätsprüfung diese Arten nicht annimmt; für sie bleiben die oben beschriebenen Prüfungen des Abschlusses. Ein Puffer mit Workload-Inhalt wird als YAML gelesen, das kein Aggrega-Dokument ist, denn dieser Inhalt wird im workload:-Feld eines Recipe oder eines FeatureRecipe geschrieben und dort geprüft, wo er steht; die Befehlszeile und das validate-Werkzeug prüfen, wenn ihnen eine Workload-Datei per Pfad übergeben wird, deren Form für sich allein.
Ein Release zu nennen ist optional, und die Antwort sagt, welche der beiden Varianten Sie angefragt haben. Nennen Sie eines, erhalten Sie alles oben Beschriebene. Nennen Sie keines, erhalten Sie die Prüfungen, die ein Dokument für sich selbst beantwortet — ob es sich parsen lässt, ob seine eigene Form zulässig ist und, bei einer Katalogentität einer als einzelne Entität validierten Art, welche Platzhalter es noch schuldet —, ohne dass ein Release aufgelöst, ein Abschluss durchlaufen oder ein Lockfile gelesen wird; die Antwort enthält dann checked: "document". Nennen Sie ein Release, fehlt dieser Schlüssel, weil diese Antwort das vollständige Urteil der Methode ist und nichts einzuschränken hat.
Lesen Sie den Schlüssel, statt aus den Diagnosen zu schließen, denn die beiden Antworten können identisch aussehen. Ein wohlgeformtes Dokument, das ohne Release validiert wird, antwortet mit einer leeren Diagnoseliste, genau wie ein sauberes vollständiges Urteil, sodass checked das Einzige ist, das „nichts ist falsch“ von „nichts, was ein Release braucht, wurde betrachtet“ unterscheidet. Aus derselben Regel folgt eine Konsequenz: Ein Lockfile wird an seiner Zuordnung zu dem Release erkannt, das die Anfrage nennt, daher erkennt eine Anfrage, die keines nennt, kein Lockfile und meldet nichts zu einem.
Ein Workspace ohne Release wird beantwortet statt abgelehnt, und das hält den Rest des Daemon dort nutzbar. Die Validierung ist das, was den Parse-Cache füllt, den jede andere Dateioperation liest, sodass ein reines Katalog-Repository, ein Gerüst mit einem einzelnen Aggregate oder ein Testverzeichnis trotzdem Hover, Vervollständigung, Gehe-zu-Definition, Referenzen, Implementierungen und zwischengespeicherte Diagnosen erhalten. Eine Ablehnung würde sie alle mitnehmen, genau in den Workspaces, in denen ein Client kein Release zu nennen hat.
Was ein Diagnoseeintrag enthält
Jeder Eintrag positioniert sich mit line und column, beide 1-basiert in der beim Handshake ausgehandelten Positionskodierung, und fügt end_line und end_column hinzu, wenn er ein ganzes Token umfasst. message ist der Text, den ein Client dem Benutzer anzeigt, severity klassifiziert ihn, und source nennt, welche der Schichten des Daemons ihn ausgelöst hat, wie oben beschrieben.
Die Schichten beantworten verschiedene Fragen zu einer Datei, daher kann ein Eintrag aus jeder in derselben Zeile stehen, ohne dass einer ein Duplikat des anderen ist: Einer sagt, dass das Deployment nicht korrekt ist, ein anderer, dass die Entität nicht veröffentlichbar ist. Ein Client, der sie als eine Liste anzeigte, würde ein einziges Problem doppelt melden, und das Lesen von source ist es, was sie trennt.
Wo ein Eintrag steht, hängt davon ab, worum es geht, nicht davon, welche Schicht ihn ausgelöst hat. Ein Befund zu etwas, das der Autor geschrieben hat, wird an dem Schlüssel positioniert, unter dem er es geschrieben hat, sodass der Editor ihn dort zeichnet, wo die Bearbeitung hingehört. Ein Befund zur Form der bereitgestellten Topologie nennt eine Komponente und einen Auslieferungsschlüssel statt einer Zeile — das sind Koordinaten in der bereitgestellten Topologie, nicht im Dokument —, daher wird er am kind:-Schlüssel des Dokuments gezeichnet und nennt seine Koordinaten stattdessen in der Meldung. Beide Arten erreichen die Schicht aggrega-build, weil ein Build beide auslöst. Auch eine Ablehnung, die ein Build beim Rendern ausgelöst hat, erreicht diese Schicht, an dem Dokument, auf das die Ablehnung selbst zeigt — eine Workload, die ihre Prüfungen nicht erfüllt, am workload-Schlüssel ihres Recipe, die fehlschlagende Assertion eines Recipe am eigenen Schlüssel dieser Assertion, ein Eintrag, den die Komposition des Graphen ablehnt, an dem Schlüssel, unter dem das Release oder das Aggregate ihn geschrieben hat, und jeder Befund einer Ablehnung, die mehrere zusammenfasst, an seinem eigenen Dokument und Schlüssel — und, wo sie auf kein Dokument zeigt, am kind:-Schlüssel des Aggregate; Eine beim Rendern ausgelöste Ablehnung beschreibt das. Ein Client platziert also jeden Eintrag anhand seiner eigenen line und column und leitet nie eine Position aus der Schicht ab.
Ein Befund, der keinen im Dokument vorhandenen Schlüssel nennt, wird an dem Schlüssel gezeichnet, der das Dokument benennt. Ein Befund, den die eigenen Prüfungen eines Dokuments zu dessen Aussagen auslösen, der Befund der Einzelentitätsprüfung sowie ein Hinweis oder eine Ablehnung, die ein Build auslöst, werden jeweils an dem Schlüssel gezeichnet, den sie nennen; wo sie keinen nennen oder einen, den das Dokument nicht enthält, werden sie am kind:-Schlüssel des Dokuments gezeichnet, oder an seinem metadata.name, wo es kein kind: deklariert, und nur dann am Anfang der Datei, wenn das Dokument keines von beiden deklariert oder sich nicht parsen lässt. Ein Dokument beginnt häufig mit einem Kommentar — jede Katalogdatei trägt einen Lizenzkopf —, und ein in seiner ersten Zeile gezeichneter Eintrag säße auf diesem Kommentar und läse sich wie ein Fehler darin, während die eigene Identität des Dokuments eine Zeile ist, die sein Autor geschrieben hat. Ein Eintrag zu etwas anderem als dem, was das Dokument aussagt, wird am Anfang der Datei platziert: ein Dependencies:-Eintrag zu den Abhängigkeiten des Release, eine Phase, die angehalten hat, ohne etwas im Dokument zu nennen, ein abweichendes Lockfile, eine Referenz, die ein Render ablehnen musste, ein Release, das nicht geladen wurde — und ebenso ein aggrega-lint-Eintrag, dessen Regel keine Zeile berechnet hat. Wo eine Position angegeben statt gezeichnet wird, hat ein Befund, der keinen Schlüssel nennt, weiterhin keinen: Die Fehlerantwort einer Ablehnung, die keinen Schlüssel nennt, enthält in ihrem data nur das Dokument.
An welchem Dokument ein Eintrag veröffentlicht wird, folgt aus derselben Regel. Eine Validierung, die ein Release nennt, beantwortet das Aggregate dieses Release, das Release selbst, das Dokument jedes Moduls, das das Aggregate importiert, und das Manifest, das das Release nennt. Ein im Release positionierter Befund — die Ablehnung eines Eintrags, den das Release an eine der Verbindungen einer Komponente schreibt, der Dimensionierung, die es dieser Verbindung gibt, eines Anhangs, den es dort füllt oder dimensioniert, einer Verbindung, die es verdrahtet, eines Feature, das nur das Release an eine Komponente oder an eine Grenze anhängt, oder der infra, die es einem Anhang gibt — wird veröffentlicht, wenn das Release-Dokument validiert wird, an dem Schlüssel im Release, der ihn geschrieben hat, und am Aggregate überhaupt nicht. Ein im eigenen Dokument eines Moduls positionierter Befund — die Ablehnung dessen, was eine der Komponenten des Moduls deklariert, eines Sockets, den seine Anhänge verdrahten, seiner Werte oder der Werte an seinen eigenen Verbindungen — wird veröffentlicht, wenn das Dokument dieses Moduls validiert wird, an dem Schlüssel dort, der ihn geschrieben hat, und am Aggregate überhaupt nicht. Ein Befund zur Zuordnungstabelle des Manifest — ein Eintrag, der einen Typ einem Recipe oder FeatureRecipe zuordnet, das ihn nicht implementiert, ein Eintrag, dessen Versions-Pin sich nicht parsen lässt, oder ein zugeordneter Typ, dessen extends-Kette sich nicht verfolgen lässt — wird veröffentlicht, wenn dieses Manifest validiert wird, an dem Schlüssel des Zuordnungseintrags, den er betrifft, und am Aggregate überhaupt nicht; wo der geöffnete Text des Manifest diesen Eintrag nicht schreibt — ein Eintrag, den es über sein eigenes extends erbt, oder einer, den eine ungespeicherte Bearbeitung entfernt hat —, wird der Befund in der ersten Zeile des Manifest veröffentlicht. Jeder andere Befund, den die Validierung dieses Release auslöst, wird am Aggregate veröffentlicht, darunter die Befunde auf Abhängigkeitsebene, die kein Dokument Ihres Workspace nennen — eine zurückgezogene Referenz oder ein zurückgezogenes Plug-in, eine Component oder ein Feature des Katalogs, deren extends-Kette sich nicht auflöst oder deren Schema ungültig ist, ein Gate-Plug-in, zu dem der Vertrauenseintrag nicht passt, eine Komponenteninstanz, die keine Zuordnung auflöst, ein Recipe oder FeatureRecipe, dessen Provider eine von ihm deklarierte Eingabeart nicht rendern kann, sowie die beratenden Hinweise zu Überschneidungen von Schema-Säulen und zur Einengung beim Erweitern. Ein Befund zu dem, was der Betreiber geschrieben hat, erscheint also, während das Release geöffnet ist, einer zu dem, was ein Modul deklariert, während dieses Modul geöffnet ist, und einer zu einer Zuordnung, während das Manifest geöffnet ist, gleich welche Phase des Builds ihn ausgelöst hat; ein Editor, der jedes geöffnete Dokument gegen das Release validiert, zeigt jeden davon dort an. Ein Release, dessen Abhängigkeiten sich überhaupt nicht auflösen lassen, löst keinen dieser Befunde aus, und das Scheitern ihrer Auflösung ist ein einziger Eintrag am Anfang des eigenen Dokuments des Release und jedes anderen dagegen validierten Dokuments, das der Daemon erkennt, wie Live-Validierung beschreibt, und nicht als einzelne Entität prüft — sein Aggregate, sein Manifest, eine Bibliothek, ein anderes Release, die Workspace-Konfiguration —, mit dem Präfix Dependencies: und mit dem eigenen Bericht der Auflösung darüber, was sie angehalten hat. Am eigenen Dokument des Release ist der Eintrag dieser Bericht und nichts weiter. An jedem anderen Dokument sagt er zuerst, dass das Dokument gegen dieses Release geprüft wird, und nennt das Release so, wie eine Anfrage es nennt — Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved:, gefolgt von dem Bericht —, weil nichts in diesem Dokument sagt, gegen welches Release es geprüft wurde: Ein Editor, der jedes geöffnete Dokument gegen das eine ausgewählte Release prüft, setzt den Eintrag auf Dokumente, die nichts mit diesem Release zu tun haben, und der Name ist das, was Ihnen sagt, dass die Auswahl die Ursache ist. Eine Datei, die der Daemon nicht erkennt, trägt keinen solchen Eintrag, gleich welches Release mit ihr genannt wurde.
Eine Antwort enthält jede Schicht, die auf der Datei steht, wie weit die Validierung auch gekommen ist. Die Antwort von aggrega/validate ist der gesamte aktuelle Zustand der Datei: was diese Validierung gefunden hat, die aggrega-build-Einträge, die ein Build, eine Vorschau oder eine Graph-Anfrage für die Datei veröffentlicht hat, und ihre Befunde zu den Veröffentlichungskonventionen, jeweils unter ihrem eigenen source. Eine Validierung, die am Puffer stehen bleibt — einer, der sich nicht parsen lässt, oder ein Dokument, dessen Hülle das Schema ablehnt —, antwortet auf dieselbe Weise: Sie meldet ihren eigenen Befund und lässt jeden Build-Eintrag für die Datei bestehen, weil sie nichts über den Build erfahren hat. Ein Client kann also aus jeder Antwort das, was er für die Datei hält, Schicht für Schicht ersetzen.
Ein Fehler wird einmal gemeldet. Die eigene Validierung eines Dokuments und ein Build können denselben Fehler darin finden: Die Einzelentitätsprüfung rendert ein Recipe, das auch ein Build rendert, die Validierung setzt den Graphen zusammen, den ein Build zusammensetzt, und ein Release, dessen Abhängigkeiten sich nicht auflösen, lässt beide scheitern. Solange ein Build einen solchen Fehler für ein Dokument meldet, meldet die Validierung dieses Dokuments ihn nicht ein zweites Mal: Ein aggrega-Eintrag, der dieselbe Bedingung nennt — denselben code — wie die Ablehnung eines Builds am selben Dokument und an derselben Spanne oder an keinem eigenen Schlüssel platziert ist — dort gezeichnet, wo ein Eintrag ohne Schlüssel gezeichnet wird, oder am Anfang der Datei —, wird aus jeder Antwort und jeder Veröffentlichung für dieses Dokument weggelassen, und die Meldung des Builds steht allein. Die Meldung des Builds ist der Eintrag der Ablehnung auf der Schicht aggrega-build; oder, bei aggrega/build, aggrega/buildPreview oder aggrega/irGraph, die mit 1004 abgelehnt wurden, weil sich eine Abhängigkeit nicht auflöst, diese Antwort selbst — die nichts veröffentlicht — an dem Dokument, das ihr data.file nennt, sonst ihr data.lockfile, sonst an dem Release, das die Anfrage nennt, wobei für ein Release die letzte solche Antwort zählt. Die Validierung behält, was sie gefunden hat: Sobald kein Build den Fehler mehr meldet — der nächste Lauf veröffentlicht die Schicht ohne ihn, die nächste Build-, Vorschau- oder Graph-Antwort für dieses Release ist etwas anderes, oder es verbindet sich ein Client, der keine solche 1004-Antwort erhalten hat —, wird der eigene Eintrag des Dokuments wieder gemeldet, und wo kein Build gelaufen ist, wird nichts weggelassen. Ein aggrega-Eintrag an einem Schlüssel, an dem keine Build-Ablehnung steht, bleibt, auch wenn er dieselbe Bedingung nennt, weil er ein zweiter Fehler dieser Art sein kann, den der Build nicht gemeldet hat.
code ist ein stabiler, maschinell abgleichbarer Code für das, was der Eintrag meldet, sodass ein Client darauf verzweigen kann, ohne den Meldungstext abzugleichen. Ein Schlüssel trägt den Code, gleich wer ihn vergeben hat, und source sagt Ihnen, welche Art Sie vor sich haben, weil die Schichten Dinge aus verschiedenen Vokabularen benennen.
- Bei einem
aggrega-Eintrag — einem Befund zu den geschriebenen Dokumenten — ist der Code die Zeichenkette, unter der die Bedingung registriert ist, geschrieben als deklarierendes Paket, gefolgt von der Regel in Kebab-Case. Es ist derselbe Wert, den ein Go-Konsument mitCodeOfliest, dessen Form und abgleichbare Oberfläche in der Referenz der Fehler-Sentinels beschrieben sind. - Bei einem
aggrega-build-Eintrag — einem Hinweis, den ein Build ausgelöst hat — ist der Code das, was die auslösende Stelle vergeben hat, und diese Schicht trägt Hinweise aus zwei verschiedenen Vokabularen, weil ein Build Hinweise zu zwei verschiedenen Arten von Dingen auslöst. Ein Hinweis zur Form der bereitgestellten Topologie trägt einen Klassencode wieunsupported-field, vergeben, wo immer er ausgelöst wurde, ob in einem Rendering-Plugin oder im Render selbst; ein Klassencode benennt eine Klasse von Hinweisen statt einer registrierten Bedingung, daher hat er keine Zeile in der Sentinel-Referenz, und die Referenz der Warnungen beschreibt die Klasseunsupported-fieldund das Flag, das sie stummschaltet. Ein Hinweis zu den geschriebenen Dokumenten — ein Name, der eine Bearbeitung von einem deklarierten entfernt ist, ein Parameter, den nichts liest — trägt die Zeichenkette, unter der seine Bedingung registriert ist, in derselben Form wie einaggrega-Eintrag und mit einer Zeile in der Sentinel-Referenz. In beiden Fällen benennt der Code, was der Befund ist, und nicht, wer ihn gefunden hat, sodass eine einzelne Klasse Sie unter einem Code erreicht, wie viele Stellen sie auch auslösen, und das Lesen des Codes statt der Schicht ist es, was Ihnen sagt, welche der beiden Arten Sie vor sich haben. Die Ablehnung, bei der ein Build beim Rendern angehalten hat, ist der einzige Eintrag hier, der kein Hinweis ist, und sie trägt auf dieselbe Weise die Zeichenkette, unter der ihre Bedingung registriert ist. - Bei einem
aggrega-lint-Eintrag — einem Befund zu den Veröffentlichungskonventionen — ist der Code die Identität des Befunds: die Identität der Regel, die ihn erzeugt hat, oder, bei einem Befund, der keine Regel nennt — was ein eigener Linter unter einem eigenen Code melden kann —, dieser Code. Es ist der Bezeichner, denaggrega lintin der Zeile des Befunds ausgibt, nach dem Kurzcode, wo es einen gibt, und der Wert, denaggrega lint --output jsonfür denselben Befund enthält, alsruleIdoder alscodebei einem Befund, der keine Regel nennt. Ein Befund behält über die Oberflächen hinweg eine Identität, sodass ein Client, der eine Regel im Editor gruppiert oder unterdrückt, dieselbe Regel im Terminal gruppiert und unterdrückt. Jede Regel des Regelsatzes des Veröffentlichungs-Linters, den Aggrega deklariert, ist unter dieser Identität als Bedingung registriert, daher ist sie in der Tabelle aller Bedingungen unter dem Kurzcode aufgeführt, denaggrega lintam Anfang der Zeile desselben Befunds ausgibt und denaggrega lint --output jsondarin alsshortCodeenthält. Eine Regel aus einem eigenen Linter, die Aggrega nicht deklariert, nennt keine registrierte Bedingung, und ebenso wenig ein Befund, der keine Regel nennt, selbst wenn sein eigener Code die Identität einer von Aggrega deklarierten Regel buchstabiert — daher ist keiner von beiden dort aufgeführt. Die Regeln sind in der Referenz zuaggrega lintbeschrieben.
Unabhängig von der Schicht beantwortet der Schlüssel eine Frage — was ist das, in Begriffen, die eine Maschine abgleichen kann —, daher richtet sich eine Editor-Erweiterung, die eine Klasse von Befunden hervorhebt, gruppiert oder unterdrückt, nach dem Code und funktioniert weiter, wenn sich der Wortlaut einer Meldung ändert.
Beachten Sie, welches Objekt was enthält: Dies ist eine Zeichenkette in einem Diagnoseeintrag, verschieden vom numerischen code in einer JSON-RPC-Fehlerhülle, die unten unter Fehlercodes beschrieben ist. Eine Antwort enthält das eine oder das andere, nie beides an einer Stelle.
Der Schlüssel wird weggelassen, wo nichts, was den Eintrag erzeugt hat, einen Code vergeben hat, und jede Art kennt diesen Fall. Ein Puffer, den kein YAML-Parser liest, meldet den eigenen Text des Parsers und keinen Code, weil keine eigene Bedingung von Aggrega dahintersteht; eine Phase, die einen Fehler meldet, ohne eine Bedingung zu nennen, hat ebenso keine zu melden; und ein Hinweis, dessen Auslöser keinen Code vergeben hat, kommt ohne an. Behandeln Sie code also als optional, genauso wie end_line und end_column, und verzweigen Sie nur darauf, wenn er vorhanden ist. Ein Code ist das, was eine Diagnose meldet, und nie das, was eine auswählt: Keine Anfrage nimmt einen Code an, und einen in Ihren eigenen Code zurückzuschreiben, gibt Ihnen eine Zeichenkette statt einer Möglichkeit zum Abgleich.
Der Bezeichner, den ein Programm abgleicht, und der, den ein Mensch zitiert
Eine Bedingung trägt zwei Bezeichner, und sie sind für zwei verschiedene Leser bestimmt. code ist der obige: qualifiziert und mit Bindestrichen, sodass sich ein Programm, das darauf verzweigt, so liest, wie es gemeint ist. shortCode ist der Buchstabe E und vier Ziffern — E0164 — und ist derjenige, den ein Mensch vorlesen, in ein Suchfeld tippen oder in ein Issue einfügen kann. Beide benennen dieselbe Bedingung, und keiner ist eine Kurzform des anderen.
Welcher zu verwenden ist, hängt davon ab, wer liest. Gleichen Sie in Ihrer Erweiterung auf code ab; zeigen Sie dem Autor shortCode. Eine Erweiterung, die nur code anzeigte, ließe einen Leser mit einem für ein Programm gedachten Bezeichner zurück, und eine, die auf shortCode abgliche, gliche eine Nummer ab, die nichts über die Bedingung aussagt. Diese Aufteilung ist der Grund, warum beide übertragen werden statt nur einer.
codeDescription ist der Ort, an dem die Bedingung veröffentlicht ist, übertragen als { "href": … }, die eigene Struktur des Protokolls für einen Verweis, der geöffnet werden kann, um mehr über eine Diagnose zu erfahren. Ein protokollkundiger Editor macht daraus eine „Mehr erfahren“-Möglichkeit, ohne dass man ihm etwas über Aggrega beibringen muss, und kein Client braucht eine Kopie der Erklärungen. Die Adresse führt zur veröffentlichten Liste aller Bedingungen, wo der Eintrag für einen shortCode die Bedingung nennt und zur Schritt-für-Schritt-Anleitung der Korrektur im Authoring weiterführt.
Der erklärende Text selbst steht nicht im Eintrag, und das ist Absicht. Eine Diagnose wird bei jeder Bearbeitung ausgegeben, sodass eine Erklärung, die mit jeder mitreiste, bei jedem Tastendruck dieselben Absätze erneut veröffentlichen würde, für einen Leser, der sie meist schon gelesen hat. Ein Client, der den Text möchte, fragt einmal danach, mit aggrega/explainError weiter unten; ein Client, der einem Link folgen kann, braucht keines von beiden.
Beide Schlüssel sind genau dann vorhanden, wenn der Eintrag eine registrierte Bedingung nennt, und andernfalls gemeinsam abwesend. Darüber entscheidet, was hinter dem Eintrag steht, nicht welche Schicht ihn veröffentlicht hat, also lesen Sie die Schlüssel statt der Schicht:
- Ein Eintrag, der eine registrierte Bedingung nennt, enthält alle drei.
shortCodewird aufgelöst, und der Verweis führt zu der Liste, in der er aufgelöst wird. - Ein Eintrag, dessen Code eine Klasse nennt, enthält nur
code. Die Klasse eines Render-Hinweises und die Identität eines Konventionsbefunds aus einem eigenen Linter — einer Regel, die Aggrega nicht deklariert, oder der Code, den ein Befund ohne Regel trägt — sind echte Bezeichner, nach denen Sie gruppieren und unterdrücken können, und keiner von beiden ist eine registrierte Bedingung — daher gibt es keine Nummer zu zitieren und nichts unter der Adresse, das sie beschreibt. Ein dennoch gesendeter Verweis wäre ein Link, der eine Seite öffnet, die nicht vom Problem des Lesers handelt, und deshalb wird keiner gesendet. Dies ist die gewöhnliche Form auf der Schichtaggrega-build, wobei ein Build-Hinweis, der doch eine registrierte Bedingung nennt, wie jeder andere alle drei enthält. Auf der Schichtaggrega-lintist die gewöhnliche Form der vollständige Satz: Eine Regel des Regelsatzes des Veröffentlichungs-Linters, den Aggrega deklariert, ist eine registrierte Bedingung, daher trägt ihr Befund denselbenshortCode, denaggrega lintam Anfang der Zeile des Befunds ausgibt, und den Verweis daneben. - Ein Eintrag, der nichts nennt, enthält überhaupt keinen Bezeichner.
Die drei Fälle lassen sich also allein an den Schlüsseln unterscheiden: kein code bedeutet, dass nichts zu benennen ist, ein code ohne shortCode daneben bedeutet einen Bezeichner, der sich nicht weiter auflöst, und der vollständige Satz bedeutet einen Bezeichner mit einem Ort, an dem man darüber lesen kann. Behandeln Sie die beiden neuen Schlüssel genauso als optional wie code, und bieten Sie einem Leser nur dort etwas zum Öffnen an, wo codeDescription angekommen ist.
Einen Code erweitern, den eine Diagnose enthielt
aggrega/explainError macht aus einem der beiden Bezeichner einer Bedingung das, was der Compiler über sie deklariert, und die veröffentlichten Einträge, die die Korrektur im Authoring erklären. Es ist dieselbe Erweiterung, die aggrega explain im Terminal und das Werkzeug explain-error für einen Assistenten durchführt, und alle drei antworten aus einer Quelle, sodass ein hier erweiterter Code und derselbe dort erweiterte Code eine Antwort sind und nicht drei, die zufällig übereinstimmen.
code ist erforderlich und nimmt einen der beiden Bezeichner an — den shortCode, den eine Diagnose enthielt, oder den code daneben —, weil ein Client, der einen davon hat, den anderen nicht erhalten kann, ohne zu fragen. Ein leerer Wert wird unter Angabe dessen abgelehnt, was zu senden ist.
Die Antwort enthält immer shortCode, code und message: die beiden Bezeichner der Bedingung und den Satz, mit dem jede Diagnose beginnt, die sie nennt. Diese sind im Binary deklariert, daher kommen sie ohne Netzwerk und ohne Cache an, und genau das erlaubt es, auch einen Workspace ohne Dokumentation zu beantworten. reference ist dieselbe Adresse, die das codeDescription einer Diagnose enthält, für einen Client, der seinen Leser lieber zur Dokumentation schickt, als Text darzustellen.
entries enthält die veröffentlichte Schritt-für-Schritt-Anleitung, jeden Eintrag als die heading, die ihn eröffnet, und den body darunter, in der Reihenfolge, in der die Dokumentation selbst sie der Bedingung zuordnet. Es wird weggelassen, wo die Anleitung nicht hinzugefügt werden konnte, und note sagt dann, warum: Die veröffentlichte Seite dokumentiert noch keinen Eintrag für diese Bedingung, oder dieser Workspace kann die Dokumentation nicht lesen — die Maschine hat keine Kopie oder nur eine, die die Signaturprüfung des Workspace ablehnt. In beiden Fällen bleibt die Bedingung darüber bestehen — die Antwort ist kein Fehlschlag, und ein Client zeigt an, was angekommen ist, mit der Notiz daneben. entries und note kommen nie beide an.
Ein Code, den nichts auflöst, wird abgelehnt, statt mit einer Bedingung beantwortet zu werden, deren Felder alle leer sind, und jede Ablehnung sagt, welcher Fall vorliegt: ein Code, unter dem keine Bedingung registriert ist, eine Nummer, die einmal eine Bedingung benannt hat und nie eine andere benennt, oder ein Code, den dieses Binary nicht deklariert, wenn die veröffentlichte Liste überhaupt nicht gelesen werden konnte — der letzte Fall lässt beide Korrekturen offen, da eine für eine andere Version veröffentlichte Liste eine Bedingung nennen kann, die dieses Binary nicht deklariert.
Die Dokumentation wird aus dem Paket gelesen, das für den von der Anfrage genannten Workspace zwischengespeichert ist, und bei der ersten Verwendung beschafft, wenn es fehlt, was das Einzige ist, wofür diese Anfrage eine Registry erreicht — siehe Eine Registry erreichen und schreiben. In den Workspace wird nichts geschrieben. Keine Validierung löst es aus: Eine Erweiterung geschieht, weil eine Anfrage sie verlangt hat, daher wird nie eine Registry erreicht, während ein Dokument validiert oder inspiziert wird.
Veröffentlichungskonventionen, auf Anfrage und bei jeder Bearbeitung
Der Daemon beantwortet zwei verschiedene Fragen zu einer Katalog-Entität, und es sind die Fragen, die aggrega validate und aggrega lint im Terminal beantworten: ob das Deployment korrekt ist und ob die Entität nach den Konventionen des Katalogs veröffentlichbar ist. Eine Validierung beantwortet immer die erste. Die zweite beantwortet sie nur, wenn Sie danach fragen.
aggrega/lint fragt ausdrücklich danach. Senden Sie entity für eine einzelne Katalog-Entität, release für jede Entität, die der Abhängigkeitsabschluss dieses Release erreicht, oder keines von beiden, um jede Entität unter den konfigurierten Katalogverzeichnissen zu prüfen – die drei Geltungsbereiche, die der Befehl hat. Das Senden von entity und release zugleich benennt zwei verschiedene Gegenstände und wird abgelehnt. Die Antwort enthält checked, die Anzahl der Entitätsdokumente, die der Lauf abgedeckt hat, und files, die Befunde, gruppiert nach dem Dokument, das sie jeweils betreffen, und nach Pfad sortiert, wobei die Einträge jeder Datei die oben beschriebene Diagnoseform haben. halted gibt an, ob das eigene Urteil des Laufs die Veröffentlichung verweigert.
Wenn Sie keines von beiden senden, wird der gesamte Katalog so geprüft, wie es aggrega lint ohne Argument tut. Ein Workspace, dessen Konfiguration keine eigenen Release-Katalogverzeichnisse angibt, wird einmal über seine eigenen Verzeichnisse geprüft, und die Antwort ist die oben beschriebene. Ein Workspace, der unter workspace.releases Releases benennt, wird für jedes Release darin einmal geprüft, über die Verzeichnisse, die dieses Release liest, und nie über alle zusammen – so werden nebeneinander gehaltene Katalogvarianten, eine pro Release, jeweils in den Begriffen des Release geprüft, das sie liest. Die Antwort enthält dann außerdem passes, einen Eintrag pro Durchgang: releases, die Releases, für die er ausgeführt wurde, jeweils relativ zum Workspace-Stammverzeichnis, wobei Releases, die dieselben Verzeichnisse lesen, sich einen Eintrag teilen; catalogDirs, die Verzeichnisse, die er gelesen hat, geschrieben so, wie files einen Pfad schreibt, und leer für ein Release, das keine liest, was gemeldet wird, statt die anderen scheitern zu lassen; sowie die eigenen Zählwerte und files dieses Durchgangs, die angeben, für welches Release ein Befund gefunden wurde. checked, die Zählwerte und files darum herum decken alle Durchgänge zusammen ab, sodass ein Client, der passes nicht liest, dennoch den gesamten Lauf liest. Ein Lauf, bei dem kein Durchgang ein Verzeichnis zum Lesen hat, wird abgelehnt, statt als sauberer Katalog beantwortet zu werden.
Setzen Sie prePublish zusammen mit entity, um diese Entität mit ihrer zuvor veröffentlichten Version zu vergleichen und die vorgeschlagene Versionserhöhung daran zu klassifizieren. Das ist hier der einzige Modus, der eine Registry erreicht, und er läuft, weil die Anfrage ihn benannt hat: Was eine nach außen gerichtete Operation zulässt, ist, dass ein Aufrufer sie angefordert hat. Er ist nur mit entity sinnvoll, daher wird prePublish ohne Entität abgelehnt.
aggrega/lint veröffentlicht nichts in die Sitzung. Es antwortet zu dem Gegenstand, den es erhalten hat, und seine Befunde in die Problemliste des Editors zu schreiben, würde ersetzen, was eine Validierung für Dateien veröffentlicht hat, die die Anfrage nie abgedeckt hat. In keinem Modus wird etwas auf die Festplatte geschrieben.
serve.lint_on_validate führt dieselben Regeln bei jeder Validierung aus und ist ausgeschaltet, sofern Sie es nicht einschalten. Schalten Sie es in .aggrega-config.yaml ein, in dem Workspace, zu dessen Entitäten Sie die Hinweise erhalten möchten:
serve: lint_on_validate: trueDafür gibt es kein Flag, weil die Frage, die es beantwortet, den eigenen Inhalt eines Workspace betrifft, und die Person, die diese Frage hat, diejenige ist, die den Workspace verfasst, und nicht diejenige, die den Daemon gestartet hat. Ist es eingeschaltet, veröffentlicht eine Validierung einer Katalog-Entität zusätzlich die Konventionsbefunde unter der Quelle aggrega-lint; ist es ausgeschaltet – die Voreinstellung –, meldet eine Validierung nur die Korrektheitsebenen, und kein Konventionsbefund erreicht Sie. Eine Editor-Sitzung sagt nichts darüber, ob eine Entität veröffentlichbar ist, bis Sie nach dieser Ebene fragen.
Auf dieser Ebene gelten drei Dinge, unabhängig davon, was der Schlüssel sagt. Es läuft nur der Modus, der lokale Inhalte liest, daher wird keine Registry befragt, nichts abgerufen und nichts geschrieben; der Vergleich vor der Veröffentlichung wird erreicht, indem aggrega/lint mit prePublish gesendet wird, nie durch eine Validierung, denn eine Prüfung, die bei jeder Bearbeitung läuft, ist genau die Stelle, an der keine Registry erreicht werden darf. Die Regeln werden gegen den Puffer ausgewertet, den die Anfrage mitgebracht hat, statt gegen die Datei auf der Festplatte, sodass ein Name, den Sie korrigieren, nicht mehr gemeldet wird, bevor Sie speichern. Und die Befunde sind beratend – ein Dokument, das sie auslöst, wird dennoch validiert, und sein Release wird dennoch aufgelöst und gerendert –, sodass sie eine Ebene hinzufügen und nie eine Ablehnung.
Der Schlüssel steuert diese Ebene und sonst nichts. aggrega/lint beantwortet unter beiden Werten alles, wonach es gefragt wird, weil ein Aufrufer, der es sendet, die Prüfung namentlich angefordert hat.
Geprüft werden nur die Arten, die in einem Katalog veröffentlicht werden, denn darum geht es bei den Konventionen. Dokumente, die kein Kataloginhalt sind – darunter ein Aggregate und ein Release –, werden übergangen, ebenso YAML, das überhaupt kein Aggrega-Dokument ist. Das hält eine Sitzung ruhig in Bezug auf die Dokumente, in denen ein Autor die meiste Zeit verbringt.
Wie ein gemeldeter Pfad geschrieben wird
Wenn eine Antwort ein Dokument benennt, das der Daemon für Sie gefunden hat, entscheidet eine einzige Regel, wie dieser Pfad geschrieben wird: relativ zum Workspace-Stammverzeichnis, wenn das Dokument darin liegt, und als absoluter Pfad, wenn nicht. Das umfasst die file einer Entitätsidentität, die file einer Entitätsdefinition und die file, nach der jede Gruppe in einer Lint-Antwort geschlüsselt ist. Beide Schreibweisen sind Pfade, die Sie öffnen können – die erste relativ zum angegebenen Stammverzeichnis, die zweite so, wie sie steht –, und keine wird je wegen des Ortes, an dem das Dokument liegt, leer gelassen.
Die zweite Hälfte der Regel ist das, was ein konfiguriertes Katalogverzeichnis braucht. Ein Workspace kann auf Katalogverzeichnisse an beliebiger Stelle auf dem Rechner verweisen, und ein Dokument in einem davon ist ebenso real wie ein Dokument unter dem Stammverzeichnis. Der absolute Pfad ist das, was es benennt, und es ist dieselbe Schreibweise, die aggrega lint und eine abbrechende Diagnose für diese Datei im Terminal ausgeben – so hat eine Datei einen Namen, gleich welche Oberfläche Sie gefragt haben. Was Sie nicht erhalten, ist ein Pfad, der über das Stammverzeichnis hinaufsteigt und je nachdem, von wo aus er gelesen würde, verschiedene Dateien benennen würde.
Welche Schreibweise Sie erhalten haben, ist am Wert ablesbar: Alles, was Ihre Plattform als absoluten Pfad liest, ist die zweite Form, und alles andere ist relativ zum Workspace-Stammverzeichnis. Sie müssen das nicht prüfen, um die Datei zu öffnen – einen relativen Pfad an das Stammverzeichnis anzuhängen und einen absoluten so zu öffnen, wie er steht, funktioniert beides –, aber ein Client, der nach Workspace-Dokument gruppiert, kann die beiden unterscheiden, ohne nachzufragen.
Was diese Regel nicht erfasst. Ein Pfad, den Sie senden, unterliegt dem eigenen Vertrag dieser Anfrage, der bei der Anfrage oben angegeben ist und meist strenger ist: Ein Ziel wird abgelehnt, sofern es nicht relativ zum Workspace-Stammverzeichnis ist und sich innerhalb davon auflöst, einschließlich seiner Links. Die Benachrichtigung aggrega/publishDiagnostics trägt ihre file in jedem Fall absolut, innerhalb und außerhalb des Stammverzeichnisses, weil dieser Wert der Bezeichner ist, den Sie mit Ihren eigenen geöffneten Dokumenten abgleichen, und keine Koordinate im Workspace – Ihr Editor löst ihn als Dateisystempfad auf. aggrega/releaseCandidates und aggrega/activeRelease benennen jedes Release und jede Lockfile mit ihrem absoluten Pfad, wie ihre eigenen Einträge oben sagen. Und aggrega/irGraph trägt den kompilierten Graphen so, wie der Compiler ihn aufgezeichnet hat – wobei nur die Werte zurückgehalten werden, die ein Autor als sensibel deklariert hat –, sodass jeder darin aufgezeichnete Pfad derjenige ist, den der Compiler aufgezeichnet hat, in der Form, die der eigene Vertrag des Graphen festlegt, und nicht einer, den dieses Protokoll für Sie zusammengesetzt hat.
Welche Schreibweisen ein gesendeter Parameter akzeptiert
Was ein Pfad benennt – nicht, welche Methode ihn trägt –, entscheidet, welche Schreibweisen dieser Parameter akzeptiert. Der eigene Eintrag jeder Anfrage oben nennt den Vertrag für die Parameter, die sie entgegennimmt; was folgt, ist der Gegensatz zwischen ihnen und warum es ein Gegensatz ist und keine Inkonsistenz, die Sie sich pro Methode merken müssten.
Ein Parameter, der ein Dokument benennt, das Sie bereits haben, kann auf drei Arten geschrieben werden: relativ zum Workspace-Stammverzeichnis, absolut oder als die file://-Adresse, die ein Language-Server-Client für ein geöffnetes Dokument sendet. Das ist die file oder uri von aggrega/validate, aggrega/diagnostics, aggrega/invalidate, aggrega/hover, aggrega/completion, aggrega/resolve, aggrega/findReferences, aggrega/findImplementations, aggrega/insertionPoint und aggrega/connectionAtPosition. Alle drei benennen ein Dokument und werden gleich beantwortet, weil jede an der Anfragegrenze auf eine kanonische Schreibweise reduziert wird, bevor irgendetwas sie liest – so wird ein Dokument, das Sie unter seinem Pfad validiert haben, unter seiner Adresse gefunden und umgekehrt, und welche Schreibweise Sie senden, ändert nichts an der Antwort. Eine Adresse wird als der Pfad gelesen, den sie benennt, mit dekodierten Prozent-Escapes, wenn ihre Authority leer oder localhost ist; eine, die einen anderen Rechner benennt, wird als Netzwerkfreigabe dieses Rechners gelesen auf einem System, das ein Dokument dort auf diese Weise öffnet, und benennt anderswo nichts, was der Daemon öffnen kann. Eine Adresse, die außerdem eine Query, ein Fragment, Anmeldedaten oder einen Port enthält, benennt ebenfalls nichts, was der Daemon öffnen kann. Ein Wert, der nicht mit file:// beginnt, in welcher Groß- und Kleinschreibung auch immer, wird nie als Adresse gelesen, und die Ablehnung „Datei nicht validiert“ nennt den Wert, den Sie gesendet haben, gleich in welcher Schreibweise. Von diesen sind aggrega/insertionPoint und aggrega/connectionAtPosition die beiden, die das Dokument von der Festplatte lesen, wenn Sie keine Kopie davon haben, und sie antworten nur für ein Dokument innerhalb des Workspace: Eines außerhalb des Stammverzeichnisses – so wie geschrieben oder über einen Link, der hinausführt, zur Datei oder zu einem Verzeichnis auf dem Weg – wird abgelehnt, gleich welche der drei Schreibweisen es benennt, und ein Dokument innerhalb des Stammverzeichnisses wird in allen dreien beantwortet. Die anderen acht lesen nichts von der Festplatte unter dem Pfad, den sie benennen – aggrega/validate nimmt die Bytes des Dokuments aus content, und die übrigen antworten aus dem, was validiert wurde –, daher antworten sie für ein Dokument, wo auch immer Sie es haben, innerhalb des Workspace oder nicht, und keinem Link, den sie benennen, wird gefolgt, um eine Datei zu lesen. Ein Parameter, der ein Dokument benennt, das Sie außerhalb des Workspace ausgewählt haben, ist aus demselben Grund derselbe Fall: Die source von aggrega/import wird dort gelesen, wo sie tatsächlich liegt, wie ihr eigener Eintrag sagt. Beide sind Ausnahmen von der Workspace-Grenze ihrer Klasse nach – ein Dokument, das der Client geöffnet hält, und eine Datei, die eine Person ausgewählt hat –, und Die Workspace-Grenze erklärt, warum jede eine ist.
Ein Parameter, über den der Daemon ein Dokument innerhalb des Workspace finden muss, nimmt einen workspace-relativen Pfad und nichts anderes. release ist der, den Sie kennen sollten – bei aggrega/irGraph und unter demselben Vertrag, wo immer er sonst vorkommt –, und ein absoluter Wert wird mit dem Fehler invalid-params abgelehnt, der den Vertrag nennt und dann den konkreten Fehler benennt. Die Anfragen, die innerhalb des Workspace schreiben, halten ihre Ziele an denselben Vertrag, wie es jeweils ihr eigener Eintrag sagt. Jeder solche Pfad wird dann danach beurteilt, wohin er führt, nach einer einzigen Regel, ob die Anfrage ihn liest oder schreibt – der Definition von innen, die Die Workspace-Grenze angibt –, und ein Pfad, der hinausführt, wird mit dem eigenen Fehler dieser Anfrage abgelehnt, der den Wert so zitiert, wie Sie ihn gesendet haben, ohne dass etwas gelesen oder geschrieben wird: ein Link zu einer Datei außerhalb und ein Link zu einem Verzeichnis auf dem Weg gleichermaßen, sowie ein noch nicht angelegter Pfad unter einem verlinkten Verzeichnis, das hinausführt, der wegen des Links abgelehnt wird, statt dass in ihn geschrieben oder außerhalb nach ihm gesucht und er als fehlend gemeldet wird. Das umfasst jeden Pfad, den eine Anfrage dem Daemon zum Lesen nennt – release, wo immer er vorkommt, entity von aggrega/lint und entity, plugin, file und from der Veröffentlichungsanfragen –, sodass eine Anfrage über einen Link keine Datei lesen kann, die die eigenen Auflistungen des Workspace auslassen, und jedes Ziel: die Verzeichnisse, in die eine Generierung, ein Import und ein Build schreiben, die Entität, neben die aggrega/pin seine Sperre schreibt, die Entitätsdatei und das Modul, die aggrega/pluginSync liest und neu schreibt, und das Dokument, das aggrega/editDocument bearbeitet. Ein release, das ein Release benennt, das Ihre Workspace-Konfiguration benennt, ist die einzige Ausnahme, wie der Eintrag von aggrega/irGraph sagt.
Die beiden unterscheiden sich, weil sich die Fehler unterscheiden. Ein Parameter, der ein Dokument benennt, das Sie bereits haben, lässt nur eine Frage offen – welches Dokument –, sodass das Reduzieren Ihrer Schreibweise auf die kanonische nichts verliert und das Akzeptieren jeder einzelnen Sie ebenfalls nichts kostet. Ein Parameter, der ein Dokument aus dem Workspace auswählt, ist nicht in dieser Lage: In den Pfadbibliotheken, die ein Client wahrscheinlich verwendet, ergibt das Anhängen eines absoluten Werts an ein Stammverzeichnis diesen absoluten Wert statt eines Fehlers. Ein stillschweigend reparierter Wert würde den Daemon also einen Pfad lesen lassen – und Befunde dazu melden –, den der Workspace nie enthielt, und man würde Ihnen von einer Datei berichten, die nicht existiert. Ablehnen ist die Antwort statt Reparieren, denn ein Daemon, der einen solchen Wert reparierte, würde jeden Client, der einen sendet, im Glauben lassen, der Vertrag sei optional.
Wie eine Entität adressiert wird
Jede Entität, die eine Antwort benennt, wird auf dieselbe Weise adressiert: kind, name und file. Verknüpfen Sie über diese drei mit aggrega/catalogIndex, wenn Sie etwas anzeigen möchten: Es ist die Oberfläche, die den vollständigen beschreibenden Satz einer Entität trägt – apiVersion, description und labels –, sodass eine Antwort, die eine Entität nur benennen muss, die drei Adressierungsschlüssel meldet und das Beschreiben einer einzigen Stelle überlässt. Eine Suche nach Namen wie aggrega/entityDefinition wiederholt die wenigen beschreibenden Felder, um die es in ihrer eigenen Antwort geht; der Index bleibt die Oberfläche, mit der Sie verknüpfen, wenn Sie den Satz möchten.
Wo eine Antwort Entitäten von mehr als einer Stelle benennen kann, trägt jede Identität origin neben diesen drei Schlüsseln. aggrega/catalogIndex und aggrega/attachCandidates tun das beide, weil ihre Entitäten aus den Workspace-Dokumenten und aus den konfigurierten Katalogverzeichnissen stammen. Eine Antwort, die nur aus einer Stelle schöpft, meldet nur die drei Schlüssel und kein origin, da ein Schlüssel mit nur einem möglichen Wert Ihnen nichts sagt – jede Entität, die eine solche Antwort benennt, ist ein Workspace-Dokument, und ihre file ist ein workspace-relativer Pfad, den Sie öffnen können. Lesen Sie origin also dort, wo es vorhanden ist, statt es überall zu verlangen; die drei Schlüssel sind in jedem Fall das, worüber Sie verknüpfen.
origin gehört zu einer Antwort, die Entitäten auflistet, wo das Unterscheiden der Populationen das Problem des Lesers ist. Eine Antwort nach Namen wie aggrega/entityDefinition trägt keines: Sie benennt die eine Entität, zu der der Name aufgelöst wurde, sodass es keine Populationen zu trennen gibt. Ihr eigener Aufzählungspunkt oben sagt, wann ihre file leer ist; lesen Sie diese Leere nicht durch die unten beschriebenen origin-Werte, die eine Auflistung beschreiben.
origin sagt, woher der Daemon die Entität gelesen hat, und macht file lesbar.
workspace– ein Aggrega-Dokument unter dem Workspace-Stammverzeichnis.fileist sein Pfad relativ zu diesem Stammverzeichnis, also ein Pfad, den Ihr Client öffnen kann.catalog– eine Entität, die aus den konfigurierten Katalogverzeichnissen aufgelöst wurde.fileist in dieser Auflistung leer, und dernameist die gesamte Adresse. Sie ist leer, weil die Auflistung meldet, was die Katalogsuche aufgezählt hat, und das ist eine Identität und kein Dokument, sodass der Eintrag keinen Pfad zu melden hat – nicht etwa einen Pfad, der wegen seines Ortes zurückgehalten wurde. Fragen Sieaggrega/entityDefinitionnach demselben Namen, wenn Sie das Dokument möchten: Diese Anfrage löst die Entität auf und meldet ihrefilenach der Regel oben, sodass ein Katalogverzeichnis außerhalb des Workspace-Stammverzeichnisses dort mit seinem absoluten Pfad benannt wird.nameist ohnehin die Koordinate, die ein Aggregate, ein Recipe und die Katalogsuche alle verwenden.
Lesen Sie die beiden zusammen, statt nur file zu prüfen. Eine leere file allein könnte Ihnen nicht sagen, ob die Entität keinen Workspace-Pfad hat oder ob einfach keiner gemeldet wurde; origin beantwortet das direkt.
Wo ein Feature auf beiden Wegen erreichbar ist – das Workspace-Stammverzeichnis ist selbst eines der konfigurierten Katalogverzeichnisse, was ein gängiges Layout ist –, wird es einmal gemeldet, als Workspace-Dokument, weil das die Kopie ist, deren Datei Sie öffnen können.
Was Ihnen eine Attach-Candidate-Antwort sagt
aggrega/attachCandidates beantwortet eine einzige Frage – welche Features dieser Label-Satz zulässt – und bietet drei Möglichkeiten, anzugeben, welchen Label-Satz Sie meinen. Senden Sie genau eine Koordinate; zwei oder keine zu senden, wird abgelehnt, statt in eine Rangfolge gebracht zu werden.
{node} adressiert ein Workspace-Dokument über seinen metadata.name und braucht sonst nichts. Der Abgleich wird gegen die Labels ausgewertet, die dieses Dokument unter metadata.labels deklariert, und die Antwort meldet labelSource: "declared".
{graphNode, release} adressiert einen Knoten in einem kompilierten Graphen. graphNode ist die ID, unter der der Graph den Knoten schlüsselt – dieselbe ID, die Sie aus aggrega/irGraph lesen, einschließlich der qualifizierten Form, die ein von einem Sub-Aggregat beigesteuerter Knoten trägt. release ist ein Pfad relativ zum Workspace-Stammverzeichnis, der das Release benennt, dessen Graph gebaut werden soll, derselbe Wert, den aggrega/irGraph entgegennimmt. Der Abgleich wird gegen die finalisierten Labels des Knotens ausgewertet, und die Antwort meldet labelSource: "resolved".
{labels} trägt den Label-Satz selbst und adressiert nichts. Es ist die Form, die den beiden anderen zugrunde liegt: Der Abgleich ist eine Funktion eines Label-Satzes und der angebotenen Features, sodass ein Client, der bereits einen Label-Satz hat, nichts zu benennen und auf nichts zu warten hat. Senden Sie ein JSON-Objekt aus Label-Paaren; die Antwort meldet labelSource: "supplied" und einen leeren node, weil diese Anfrage keinen adressiert hat. Ein leeres Objekt ist eine Koordinate – es fragt nach einem Knoten ohne Labels –, während das vollständige Weglassen des Schlüssels oder das Senden von null nichts adressiert und abgelehnt wird.
Die beiden Namenskoordinaten sind getrennt, weil sich ihre Bezeichnerräume überschneiden. Eine Graphknoten-ID und der metadata.name eines Dokuments können dieselbe Zeichenkette sein und doch Verschiedenes benennen, sodass ein Parameter, der beides trägt, mehrdeutig wäre, und ein Daemon, der erriete, welchen Raum Sie meinen, manchmal selbstsicher für den falschen Gegenstand antworten würde. Anzugeben, welche Frage Sie stellen, beseitigt die Mehrdeutigkeit.
labelSource sagt Ihnen, wie weit die Antwort reicht, und die drei Werte sind nicht austauschbar. declared ist ein Abgleich über das, was ein Dokument über sich selbst sagt, also das, was ein Lesen des Quelltexts sehen kann. resolved ist ein Abgleich über die Labels, die der Knoten tatsächlich am Ende trägt, also das, wogegen ein Build die Anwendbarkeit auswertet – eine resolved-Antwort ist daher eine Aussage darüber, was ein Build entscheiden würde, eine declared-Antwort nicht. supplied sagt, dass der Daemon überhaupt keine Labels gelesen und das abgeglichen hat, was Sie gesendet haben; wie belastbar diese Antwort ist, hängt ganz davon ab, woher Ihr Label-Satz stammt.
Deshalb sollte ein Client, der einen Graphen hat, {labels} statt eines Namens senden. Die finalisierten Labels eines Knotens sind die Labels des Komponenten-Typs, zu dem er aufgelöst wird, nicht die eines Dokuments, das zufällig seine ID teilt, und ein label-transform-Attachment kann sie anschließend ergänzen, ändern oder entfernen – sodass die Labels, die über die Anwendbarkeit eines Knotens entscheiden, nicht die Labels sein müssen, die irgendein einzelnes Dokument deklariert. Ein Client, der einen Graphen zeichnet, hat diesen Satz bereits aus aggrega/irGraph; ihn zurückzugeben, erreicht dieselbe Antwort, die die Koordinate {graphNode, release} liefert, ohne den Graphen dafür neu zu bauen. Geben Sie einen Satz zurück, den der Daemon selbst gemeldet hat – den eines Knotens aus aggrega/irGraph, den einer Entität aus aggrega/catalogIndex –, dann kann Ihre Vorstellung von den Labels eines Knotens nicht von der des Daemons abweichen, weil der Satz dessen eigene Antwort nie verlassen hat. Stellen Sie selbst einen zusammen, so stellen Sie eine hypothetische Frage, die ehrlich beantwortet wird und keine Aussage über einen Knoten ist, den der Workspace enthält.
Kandidaten stammen aus dem Workspace und aus dem Katalog. Ein Workspace, der seine Features in einem Katalog statt in seinem eigenen Baum hält, hat überhaupt kein lokales Feature, und seine Kandidaten sind ausschließlich origin: "catalog". Für einen Graphknoten werden beide in den Begriffen des Release dieses Knotens gelesen: Die Katalog-Features sind diejenigen, die die Katalogverzeichnisse deklarieren, die die Workspace-Konfiguration diesem Release zuweist, und die eigenen Dokumente des Workspace werden angeboten, abzüglich derer unter einem Katalogverzeichnis, das nur andere Releases lesen. Ein Workspace, der eine Variante eines Feature pro Release hält, bietet dem Graphen jedes Release daher dessen eigene Variante und nie die eines anderen an, während ein neben den Katalogen geschriebenes Feature, unter gar keinem Katalogverzeichnis, für jedes Release angeboten wird. {node} und {labels} benennen kein Release, daher schöpfen sie aus jedem Workspace-Dokument und aus den eigenen catalog_dirs des Workspace. Ein Feature, das überhaupt keine Anwendbarkeit deklariert, ist ein Kandidat für jeden Knoten – eine fehlende Deklaration stellt keine Anforderung –, während eines, dessen Deklaration nicht gelesen werden kann, ein Kandidat für keinen ist, denn einen unlesbaren Selektor als erfüllt zu behandeln, würde einen Tippfehler das erweitern lassen, was Sie anbieten.
Ein Name, der sich nicht auflöst, ist ein Fehler und keine leere Liste. Diese beiden Antworten bedeuten Verschiedenes: Ein leeres candidates-Array sagt, dass dieser Knoten nichts hat, was an ihn angehängt werden darf, und einen falsch getippten Namen so zu melden, würde einen Tippfehler als feststehende Antwort darstellen. Die Ablehnung nennt den Raum, den sie durchsucht hat, sodass Sie wissen, ob Sie nach einem Workspace-Dokument oder einem Graphknoten suchen müssen. {labels} hat diese Gefahr nicht – es gibt keinen Namen, den man falsch tippen könnte –, daher kommt ein Label-Satz, den nichts zulässt, als erfolgreiche Antwort mit einem leeren Array zurück, und eine Anfrage, die der Daemon nicht lesen kann, wird dennoch abgelehnt, bevor irgendein Abgleich läuft.
Die Graphknoten-Koordinate braucht eine Lockfile, die anderen beiden nicht. Einen Graphen zu bauen bedeutet, aufzulösen, was das Release erreicht, daher lehnt dieser Weg mit dem Fehler für eine fehlende Lockfile ab, wenn keine erzeugt wurde, und nennt den auszuführenden Befehl – dieselbe Vorbedingung, die aggrega/irGraph hat, aus demselben Grund. Das Adressieren eines Workspace-Dokuments baut keinen Graphen, und das Liefern eines Label-Satzes baut überhaupt nichts, daher antworten beide in einem Workspace, den noch niemand vorbereitet hat.
Sie meldet und erzeugt nie. Die Methode verändert nichts, schreibt nichts und erzeugt kein Attachment. Das Zusammenstellen und Anwenden einer Bearbeitung ist Sache des Editors, denn dort befinden sich der Puffer und der Rückgängig-Verlauf.
Was sie auflöst, hängt von der Koordinate ab, und die drei sind nicht gleich. {node} löst nichts auf und erreicht keine Registry und kein Netzwerk – die Kandidaten stammen aus dem Workspace und aus den Katalogverzeichnissen, die beide bereits auf der Festplatte liegen. {labels} löst noch weniger auf: Es sucht nichts nach, weil es nichts nachzusuchen gibt. {graphNode, release} baut den Graphen des Release und löst daher den Abhängigkeitsabschluss dieses Release auf dieselbe Weise auf wie aggrega/irGraph: zuerst aus den lokalen Katalogverzeichnissen und dem Artefakt-Cache und aus der konfigurierten Registry für eine Entität, die keines von beiden enthält. Alle drei antworten offline für einen Workspace, dessen Entitäten alle lokal sind; nur die Graphknoten-Koordinate kann weiter suchen.
Nach einer Verbindung fragen
Eine Verbindung, die eine Komponente zieht, kann eigene Attachments tragen, die die Slots füllen, die ihr Socket auf der konsumierenden Component deklariert – etwa eine Anmeldeinformation, die die Komponente dem vorlegt, was die Verbindung erreicht. Senden Sie connection neben {graphNode, release}, um zu fragen, was dort hinein darf: socket ist der Abhängigkeits-Socket, über den die Verbindung verdrahtet ist, und alias der Name, den sie innerhalb dieses Sockets trägt, beide genau so, wie der Autor sie geschrieben hat. Eine Verbindung existiert nur in einem kompilierten Graphen, daher wird connection neben node oder labels abgelehnt, ebenso eine Verbindung, die keinen Socket oder keinen Alias benennt, oder eine, die der Knoten nicht zieht.
Die Antwort ist die Graphknoten-Antwort plus die Slots der Verbindung. candidates behält seine Bedeutung – die Features, die an den Knoten selbst angehängt werden dürfen –, und slots kommt hinzu, ein Eintrag pro Slot, den der Socket deklariert, in der Reihenfolge, in der die Component sie deklariert:
slot– der Name, unter dem ein Attachment, das ihn füllt, in denfeaturesder Verbindung geschrieben wird.selector,required,inject,sensitiveunddescription– der Slot genau so, wie die Component ihn auf dem Socket deklariert, leer oder false, wo sie nichts deklariert.selectorist die Einschränkung, nach der die Kandidaten eingegrenzt wurden, sodass Sie einen Kandidaten oder sein Fehlen allein aus der Antwort erklären können.candidates– die Features, die diesen Slot auf dieser Verbindung füllen dürfen. Ein Build unterwirft ein solches Attachment zwei Regeln, und beide werden angewendet: die deklarierte Anwendbarkeit des Feature gegen die finalisierten Labels des Knotens, der jedes Attachment des Knotens unterliegt, und derselectordes Slots gegen die eigenen Labels des Feature. Die Kandidaten eines Slots sind also immer unter denen des Knotens, eingegrenzt durch den Selektor. Ein Feature, gegen dessen Labels der Selektor nicht ausgewertet werden kann, wird nicht angeboten, weil ein Build es ablehnt, statt es zuzulassen.
Wo kein Slot gefüllt werden darf, ist slots eine leere Liste, und noSlotReason sagt, warum. Lesen Sie den Grund, statt eine leere Liste als „kein Feature hat gepasst“ zu verstehen – das wäre eine andere Antwort, und der Grund ist das, was die beiden unterscheidet:
feature-created-connection– ein Feature hat die Verbindung gezogen, aus seinem eigenen Abhängigkeitsblock. Ein Attachment wird nur auf einer Verbindung geschrieben, die eine Komponente oder das Release zieht, daher kommt hier nichts hin, gleich was der Socket deklariert.ad-hoc-socket– der Socket ist einer, den die Component nicht deklariert. Der Autor hat ihn benannt, was zulässig ist, und ein nicht deklarierter Socket deklariert keinen Slot.no-slot-declared– die Component deklariert den Socket ohne Slot.
noSlotReason fehlt überall dort, wo ein Slot existiert, und slots und noSlotReason fehlen beide in der Antwort auf eine Anfrage, die keine Verbindung benannt hat – so wird eine Anfrage, die keine Verbindung benennt, ohne eines der beiden Felder beantwortet.
document wird akzeptiert und ändert hier nichts. Die Slots sind die des Sockets und die Kandidaten die der Features, gleich in welchem Dokument ein Attachment geschrieben wird; wohin es gehört, ist die Antwort von aggrega/attachmentContainer. Ein anderer Wert als aggregate oder release wird dennoch abgelehnt, weil ein akzeptierter und ignorierter Wert für seinen Absender wie einer wirkt, der berücksichtigt wurde.
Was Ihnen eine Connection-Candidate-Antwort sagt
aggrega/connectionCandidates beantwortet zwei Fragen auf einmal, und nur eine davon hat eine vollständige Antwort. Wer die Antwort als eine einzige gefilterte Liste liest, versteht die andere falsch.
Jeder gemeldete Socket trägt targets – die workspace-lokalen Components, deren deklarierte Labels die Label-Einschränkung erfüllen, die dieser Socket darüber deklariert, was ihn erfüllen darf –, dazu den selector, aus dem diese Ziele berechnet wurden, das Flag required, das der Socket deklariert, und declaration. targets ist immer ein Array, leer statt fehlend, sodass ein Socket, den nichts erfüllt, dennoch als Socket gemeldet wird, den die Entität deklariert.
Die Zielhälfte ist vollständig. Die Menge wird entschieden, indem die deklarierte Einschränkung des Sockets gegen die deklarierten Labels eines Kandidaten ausgewertet wird, dieselbe Auswertung, die ein Build vornimmt, sodass das, was Sie anbieten, das ist, was dieselbe Einschränkung während eines Builds zulässt. Ein Socket, der keine Einschränkung deklariert, lässt seine Ziele uneingeschränkt und meldet jede Component – das ist die Bedeutung, die die Einschränkungssprache einem leeren Selektor gibt, kein Fehler.
Die Socket-Hälfte ist offen, und an declaration und adHocSocketsAccepted erkennen Sie das. Der Autor eines Aggregate verantwortet dessen Topologie und darf einen Socket verdrahten, den die Katalog-Entität der Komponente nie deklariert hat, daher sind die Sockets, die eine Entität deklariert, eine hilfreiche Ausgangsmenge und nicht die Menge der zulässigen Socket-Namen. Präsentieren Sie sie als Vorschläge, nicht als die einzigen Möglichkeiten – eine Auswahl, die nur deklarierte Sockets anböte, würde dem Autor sagen, seine Freiheit sei enger, als sie ist.
declarationistdeclared, wenn die adressierte Entität den Socket in ihremusesSchemaaufführt, undad-hoc, wenn nicht. Das sind dieselben zwei Werte, die eine Kante im IR-Graphen trägt, sodass ein einziges Vokabular „woher kommt dieser Socket“ beantwortet, wo immer Ihnen die Frage begegnet.adHocSocketsAcceptedmeldet, ob die Oberfläche der adressierten Entität einen Socket akzeptiert, den ihre eigene Deklaration nicht aufführt. Das ist nicht immer wahr: Die Abhängigkeitsoberfläche einer Component akzeptiert einen, die Attachment-Oberfläche eines Feature nicht, weil ein Attachment an der Topologie teilnimmt, die das angehängte Feature deklariert, statt eine eigene zu verfassen. Ein Ad-hoc-Socket auf einer Oberfläche, die keinen akzeptiert, wird ohne Ziele gemeldet, weil keine Verbindung darüber gebaut würde.
Einen socket in der Anfrage zu benennen, beschränkt die Antwort auf diesen einen Socket, und es ist die einzige Möglichkeit, nach einem Socket zu fragen, den die Entität nicht deklariert – ein nicht deklarierter Socket erscheint in keiner Deklaration, die man aufzählen könnte. Lassen Sie ihn weg, um jeden Socket zu erhalten, den die Entität deklariert, in der Reihenfolge, in der sie verfasst sind.
Was sie meldet, ist ein Abgleich über deklarierte Labels. Ein Build wertet die Einschränkung eines Sockets gegen die finalisierten Labels des Knotens am anderen Ende der Kante aus, und das sind die Labels des Komponenten-Typs, zu dem dieser Knoten aufgelöst wird, nachdem jedes label-transform-Attachment seinen Beitrag geleistet hat – nicht unbedingt die Labels des Dokuments, das Sie benannt haben. Eine positive Antwort hier ist also kein Versprechen darüber, was ein Build entscheiden wird – dieselbe Grenze, die aggrega/attachCandidates unter seiner Label-Quelle declared hat.
Sie meldet und erzeugt nie. Die Methode löst nichts auf, erreicht keine Registry und kein Netzwerk und schreibt nichts: Sie erzeugt keine Kante und schlägt keinen Text vor. Das Zusammenstellen und Anwenden der Bearbeitung ist Sache des Editors, denn dort befinden sich der Puffer und der Rückgängig-Verlauf.
Verknüpfen Sie die Entitätsidentitäten in targets – kind, name und file – mit aggrega/catalogIndex, wie unter Wie eine Entität adressiert wird beschrieben. Die beschreibenden Felder werden dort gemeldet und hier bewusst nicht wiederholt, sodass diese Antwort keine zweite Kopie davon trägt, die aus dem Takt geraten könnte. Ziele sind Workspace-Components, daher hat jedes eine file, die Sie öffnen können, und keines trägt ein origin: Diese Antwort schöpft aus einer einzigen Stelle, und verknüpft wird über die drei Schlüssel.
Was Ihnen eine Attachment-Container-Antwort sagt
aggrega/attachmentContainer steht zwischen den Kandidatenanfragen oben und dem Einfügepunkt unten. Jene sagen, was an einen Knoten angehängt werden darf; diese sagt, in welchen Container ein Attachment dafür gehört und in welches Dokument; die nächste sagt, wo in den Bytes dieses Dokuments der Text hingehört.
Fragen Sie nach dem Container, statt ihn zusammenzusetzen. Die ID eines Knotens und der Pfad des Subsystems, das ihn umschließt, werden beide mit Punkten zwischen ihren Teilen geschrieben, und ein Punkt ist ein zulässiges Zeichen in einem Namen, den ein Autor tippt – von außerhalb des Dokuments lässt sich ein struktureller Punkt also nicht von einem innerhalb eines Namens unterscheiden. Ein Client, der den Pfad selbst zusammensetzte, würde etwas erzeugen, das korrekt aussieht und einen Schlüssel adressiert, den niemand geschrieben hat, und die anschließende Bearbeitung würde diesen Schlüssel anlegen, statt abgelehnt zu werden. Der Compiler hat beide Pfade zusammengesetzt, also ist es der Compiler, der sie zerlegt.
Eine Knoten-ID trägt überhaupt keine Spur ihres umschließenden Subsystems. Eine Komponente, die innerhalb von subsystems.billing.subsystems.payments verfasst wurde, ist im Graphen als ledger geschlüsselt, genau wie es eine Komponente auf oberster Ebene wäre, sodass die ID einem Client nichts bietet, womit er arbeiten könnte, wie sorgfältig er sie auch zerlegt.
Die Antwort besteht aus drei Feldern.
nodewiederholt den Knoten, um den es in der Antwort geht, sodass ein Client mit mehreren offenen Anfragen jede Antwort ihrer Frage zuordnet, ohne eine eigene Reihenfolge zu führen.fileist das Dokument, in dem der Knoten verfasst wurde, workspace-relativ. Es ist Teil der Antwort und nicht etwas, das Sie bereits wissen: Ein Knoten, den ein importiertes Modul beigesteuert hat, wurde im eigenen Dokument dieses Moduls unter dem Namen verfasst, den das Modul ihm gegeben hat, sodass sich sowohl die Datei als auch das letzte Segment des Containers von allem unterscheiden, was die Anfrage benannt hat.containerist der strukturelle Pfad vom Stamm dieses Dokuments, als Liste von Segmenten –["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Jede Ebene eines umschließenden Subsystems steht erneut unter dem Schlüsselsubsystems, so wie das Dokument es schreibt. Eine Komponente, die der Autor auf oberster Ebene geschrieben hat, benennt stattdessen["spec", "components", "checkout", "features"], weil der Geltungsbereich, in den eine solche Komponente kompiliert wird, keiner ist, den eine Datei enthält.
Es ist eine Liste von Segmenten und nie eine zusammengefügte Zeichenkette, und genau darum geht es bei dieser Form. Ein zusammengefügter Pfad müsste von demjenigen, der ihn empfängt, erneut zerlegt werden, womit die obige Mehrdeutigkeit einen Aufruf später wieder eingeführt wäre. Übergeben Sie die Liste unverändert als container an aggrega/insertionPoint.
Sie liest Struktur und nie Bedeutung. Die Antwort wird aus dem Dokument abgeleitet, in dem der Knoten verfasst wurde, aus dem Geltungsbereich, in dem er steht, und aus dem Namen, den der Autor getippt hat. Nichts wird daraus gelesen, wie eine Komponente heißt, welchen Typ sie trägt oder was ein Label sagt.
Sie meldet und schreibt nie. Die Methode verändert nichts und schreibt nichts in ein Dokument. Sie erzeugt kein Attachment, stellt keinen Text zusammen und wendet keine Bearbeitung an; sie entscheidet nicht darüber, was angehängt werden darf, das ist aggrega/attachCandidates.
Eine Anfrage, die einen Knoten benennt, den der Graph nicht enthält, wird abgelehnt statt beantwortet. Knoten-IDs sind die eigenen Schlüssel des Graphen – lesen Sie sie aus dem Graphen, den aggrega/irGraph zurückgibt –, und ein Knoten, den ein importiertes Modul beigesteuert hat, trägt eine qualifizierte ID. Auch ein Knoten, für den der Graph kein Dokument aufzeichnet, wird abgelehnt: Wohin ein Attachment gehört, ist eine Tatsache über ein Dokument, daher hat ein Knoten ohne Dokument keine Antwort statt einer leeren.
Sie erfordert eine Lockfile, aus demselben Grund wie aggrega/irGraph: Den Container zu benennen bedeutet, den Graphen des Release zu bauen, und ein Graph, der aus Bytes gebaut wurde, für die nichts bürgt, würde genau so gemeldet wie einer, der geprüft wurde.
Ein Attachment auf einer Verbindung
Senden Sie connection neben {graphNode, release} – mit ihrem socket, ihrem alias und ihrem document –, und die Antwort benennt den features-Container auf dem eigenen Eintrag dieser Verbindung statt auf dem des Knotens. document ist hier erforderlich, weil jedes der beiden Dokumente ein Attachment auf einer Verbindung enthalten kann, die das Aggregate gezogen hat: Der Entwickler schreibt eines auf den Eintrag der Verbindung im Aggregate, der Betreiber auf den kantenbezogenen Eintrag des Release dafür.
aggregatebenennt den Eintrag der Verbindung in dem Dokument, in dem der Knoten verfasst wurde –["spec", "components", "gateway", "uses", "models", "gpt", "features"]für eine Komponente auf oberster Ebene, wobei jedes umschließende Subsystem wie oben Ebene für Ebene ausgeschrieben wird. Eine Verbindung, die das Release gezogen hat, hat keinen Eintrag im Aggregate und wird dort daher abgelehnt.releasebenennt den kantenbezogenen Eintrag unter dem eigenen Eintrag des Release für den Knoten –["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"]–, ob das Release diesen kantenbezogenen Eintrag bereits schreibt oder nicht. Wo es ihn nicht schreibt, meldetaggrega/insertionPointdie noch zu schreibenden Schlüssel inmissingContainerKeys.fileist dann das Release-Dokument. Ein Release, das überhaupt keinen Eintrag für den Knoten schreibt, wird abgelehnt: Wo der Knoten platziert wird, hat der Betreiber zu schreiben, und die Antwort entscheidet es nicht.
Eine Verbindung, die ein Feature gezogen hat, wird in beiden Dokumenten abgelehnt, aus dem Grund, den feature-created-connection oben angibt. Der Knoten, der Socket und der Alias werden genau so abgeglichen, wie sie geschrieben sind, und eine Verbindung, die der Knoten nicht zieht, wird abgelehnt, statt mit einem Pfad beantwortet zu werden. Jede andere Eigenschaft von oben gilt unverändert: Die Antwort ist eine Liste von Segmenten, sie liest Struktur und nie Bedeutung, und sie schreibt nichts.
Was Ihnen eine Connection-at-Position-Antwort sagt
aggrega/connectionAtPosition ist der Schritt vor den beiden Verbindungsanfragen oben, für einen Client, der eine Stelle in einem Dokument statt eines Knotens in einem Graphen hat – etwa einen Cursor auf dem Eintrag einer Verbindung. Sie beantwortet, welche Verbindung dort geschrieben ist, in den Koordinaten, die jene Anfragen entgegennehmen, und hört dann auf.
Die Antwort ist eine von zwei Hälften, nie beide.
graphNodeundconnection– der Knoten, dessen Komponente die Verbindung zieht, über die ID, unter der der kompilierte Graph ihn schlüsselt, und die Verbindung über ihrensocketund ihrenalias, wobeidocumentdas Dokument benennt, in dem die Position gelesen wurde:aggregatefür das Aggregate oder ein Modul, das es importiert,releasefür das Release. Übergeben SiegraphNode, dasselbereleaseundconnectionanaggrega/attachCandidatesfür die Slots, die der Socket der Verbindung deklariert, und anaggrega/attachmentContainerdafür, wohin ein Attachment darauf gehört; der Container, den sie benennt, liegt innerhalb genau des Eintrags, in den die Position fiel.noConnectionReason– warum keine Verbindung gemeldet wird. Die Menge ist abgeschlossen:no-connection-entry– die Position liegt auf keinem Eintrag, in den ein Attachment geschrieben wird. Eine als Liste von Zielen geschriebene Verbindung (db: [store]) und eine, die der eigene Abhängigkeitsblock eines Feature zieht, tragen keinen solchen Eintrag, daher ergibt auch eine Position auf einer der beiden diese Antwort.feature-created-connection– die Position liegt auf dem Eintrag des Release für eine Verbindung, die ein Feature gezogen hat, der aus dem Grund, den die Slot-Antwort oben angibt, kein Attachment trägt. Ein Release schreibt einen solchen Eintrag dort, wo der Abhängigkeitsblock eines Feature über einen Socket zieht, den auch die konsumierende Component deklariert; der Eintrag wird gebaut, ob er nichts konfiguriert oder das kantenbezogeneinfrader Verbindung setzt.unknown-connection– die Position liegt auf einem Eintrag, den das Release für eine Verbindung schreibt, die der kompilierte Graph nicht enthält. Ein Release, das gebaut wird, kann einen solchen enthalten – etwa einen Eintrag unter einem Alias, den nichts zieht, und der nichts konfiguriert (keintarget, keininfra, keinefeatures), oder einen Eintrag für eine Komponente, die einactive:-Schalter ausgeschaltet hat und deren Verbindungen mit ihr aus dem Build verschwinden.
Welche Einträge zählen. Im Aggregate jede Verbindung, die eine Komponente zieht, an ihrem Eintrag unter dem Alias der Verbindung in dem Dokument, in dem die Komponente verfasst wurde – für eine Komponente, die ein importiertes Modul beisteuert, das eigene Dokument dieses Moduls. Im Release jeder kantenbezogene Eintrag, den es schreibt, ob der Eintrag seine Verbindung zieht oder eine konfiguriert, die das Aggregate gezogen hat. Wo jeder Eintrag steht, zeichnet der kompilierte Graph auf, sodass nie daraus abgeleitet wird, wie ein Schlüssel heißt, ob er eine Verbindung ist. Eine Komponente, die ein active:-Schalter ausgeschaltet hat, ist nicht im kompilierten Graphen, daher antworten ihre eigenen Einträge im Aggregate mit no-connection-entry, während der Eintrag des Release für eine ihrer Verbindungen mit unknown-connection antwortet.
Eine Position irgendwo innerhalb eines Eintrags liegt in ihm. Der Eintrag reicht von seinem Alias-Schlüssel bis zur letzten darunter eingerückten Zeile, sodass eine Position auf dem Alias, auf seinem target oder innerhalb seiner features für diese Verbindung beantwortet wird, und wo Einträge verschachtelt sind, gewinnt der innerste. Eine Position auf dem eigenen Schlüssel eines Sockets, oberhalb der darunter geschriebenen Aliase, liegt in keinem von ihnen – ob der Socket einen Alias oder mehrere enthält –, und ebenso wenig eine Position in der Einrückung vor einem Alias-Schlüssel.
Welches Dokument welches ist, ergibt sich aus dem Release. Die eigene Datei des Release wird für die Einträge gelesen, die es schreibt; jede andere Datei wird für die Einträge gelesen, in denen der Graph Komponenten als verfasst aufzeichnet. Ein Dokument, aus dem der Graph des Release nichts liest, antwortet an jeder Position mit no-connection-entry.
Sie meldet und schreibt nie, und sie liest das Dokument so, wie aggrega/insertionPoint es tut: zuerst aus der Kopie der Sitzung und andernfalls von der Festplatte, innerhalb des Workspace, mit denselben Ablehnungen für ein Dokument, das außerhalb davon liegt, unlesbar ist oder kein wohlgeformtes YAML ist. Sie erfordert eine Lockfile, aus dem Grund, aus dem aggrega/attachmentContainer eine erfordert, und baut den Graphen, ohne etwas zu rendern.
Was Ihnen eine Einfügepunkt-Antwort sagt
aggrega/insertionPoint ist das Gegenstück zu den beiden Kandidatenanfragen oben. Jene sagen, was angehängt oder verbunden werden darf; diese sagt, wohin der Text dafür in einem bestimmten Dokument gehört. Sie antwortet und hört dort auf.
Sie benennen den Container; der Daemon findet ihn. container ist ein struktureller Pfad ab der Dokumentwurzel — ["spec", "components", "web", "features"] — und er ist Ihre Aussage darüber, wohin ein Eintrag dieser Art in einem Dokument dieser Art gehört. Der Daemon leitet diesen Pfad nicht daraus ab, wie eine Entität heißt, welchen Typ sie trägt oder was sie zu bedeuten scheint. Er liest die Bytes, die der Autor geschrieben hat, und meldet, welche Segmente des Pfads dieses Dokument bereits hat, in welchen Spalten seine Einträge stehen und welche letzte Zeile sein innerster Block erreicht. Das Wissen, welcher Schlüssel es ist, bleibt also beim Aufrufer, und das Wissen, wohin die Einträge dieses Schlüssels in dieser Datei gehören, kommt von hier.
Für das Anhängen eines Feature an einen Knoten eines kompilierten Graphen muss der Aufrufer diesen Schlüssel nicht selbst kennen: Fragen Sie aggrega/attachmentContainer nach dem Dokument und dem Container, und übergeben Sie beide unverändert hier.
Die Antwort ist eine Position der Breite null plus das, was Sie um sie herum schreiben müssen. file ist das Dokument, relativ zum Workspace. container wiederholt den angefragten Pfad, sodass ein Client mit mehreren offenen Anfragen jede Antwort ihrer Frage zuordnet, ohne selbst eine Reihenfolge zu führen. position fügt ein, statt zu ersetzen: Nichts, was bereits im Dokument steht, wird überschrieben oder verschoben.
precededByLineBreak— beginnen Sie den Text, den Sie schreiben, mit einem Zeilenumbruch. Die Position liegt am Ende der Zeile, auf die der neue Eintrag folgt; sie liegt im gültigen Bereich, ob die Datei mit einem Zeilenumbruch endet oder nicht, und verändert kein bereits geschriebenes Byte. Sie ist nur dann false, wenn ein Dokument nichts enthält, wonach sie stehen könnte; dann schreiben Sie ab dem Anfang der Datei.missingContainerKeys— die Segmente des Containerpfads, die dieses Dokument noch nicht enthält, das äußerste zuerst. Jedes muss als eigener Schlüssel geschrieben werden, bevor der Eintrag in das innerste hineingehen kann. Es ist leer, wenn der ganze Pfad bereits vorhanden ist.entryIndent— die Spalte, in der die erste Zeile des Eintrags selbst beginnt, gezählt in Leerzeichen ab dem Zeilenanfang.indentStep— um wie viel weiter jede Verschachtelungsebene eingerückt ist.indentStepMeasured— ob dieser Schritt an der eigenen Verschachtelung dieses Dokuments gemessen wurde. Ist er false, zeigt das Dokument keine Verschachtelung, die sich messen ließe, und der Schritt ist ein Ersatzwert, sodass ein Client, der lieber seinen eigenen vorgibt, weiß, dass er das darf.entryShape—mappingodersequence, abgelesen an dem, was der Container bereits enthält, undunknown, wenn der Container noch nicht vorhanden ist oder nichts enthält.unknownist kein Fehler: Das Dokument hat nicht festgelegt, welche Form seine Einträge haben, also liegt diese Wahl bei Ihnen.
Anwenden. Schreiben Sie einen Zeilenumbruch, wo precededByLineBreak gesetzt ist. Dann eine Zeile pro Eintrag in missingContainerKeys, den äußersten zuerst, jeweils der Schlüssel gefolgt von einem Doppelpunkt — der erste eingerückt um entryIndent minus indentStep mal die Anzahl der fehlenden Schlüssel, und jeder weitere um indentStep mehr. Dann den Eintrag selbst, eingerückt um entryIndent. Ist missingContainerKeys leer, ist der Eintrag die einzige Zeile, die Sie schreiben.
Lesen Sie missingContainerKeys auch dann, wenn Sie erwarten, dass der Container vorhanden ist. Eine Position, die ohne die ihr vorangehenden Schlüssel angewendet wird, erzeugt ein Dokument, das sich nicht mehr parsen lässt — und das ist der eine Fehler, den man aus dieser Antwort nicht als ausgeschlossen lesen darf.
position zählt ab null, anders als die einer Diagnose. Sowohl line als auch character sind 0-basiert, passend zu den LSP-förmigen Positionswerten, die dieses Protokoll wiederverwendet, während line und column eines Diagnoseeintrags 1-basiert sind, wie unter Was ein Diagnoseeintrag enthält beschrieben. Ein Client, der die eine Schnittstelle aus der anderen speist, rechnet zwischen beiden um.
positionEncoding benennt die Einheiten, in denen character gemessen wird, und ist die beim Handshake ausgehandelte Kodierung. Sie wird in der Antwort gemeldet, statt implizit zu bleiben, weil eine Position, deren Einheiten der Aufrufer raten muss, eine Position ist, die er nicht anwenden kann: Offsets, die auf eine Weise gemessen und in einen anders gemessenen Puffer angewendet werden, beschädigen das Dokument beim ersten Zeichen außerhalb von ASCII.
Eine Anfrage, die keine Stelle adressiert, an die ein Eintrag gehen kann, wird abgelehnt statt beantwortet. Jeder dieser Fälle ist ein Zustand der Anfrage und nicht des Workspace, daher kommt er mit dem standardmäßigen invalid-params-Code zurück, und ein erneuter Versuch ändert nichts, bis sich file oder container ändert.
- Das Dokument wurde nicht benannt, liegt nicht im Workspace, konnte nicht gelesen werden oder ist kein wohlgeformtes YAML — ein Dokument ohne Struktur hat keine Position, die gemeldet werden könnte.
- Der Containerpfad benennt nichts: Er hat keine Segmente, oder eines seiner Segmente ist leer.
- Der Pfad führt durch einen Wert, den das Dokument als Skalar enthält. In einen Skalar kann nichts angehängt werden, und ihn zu ersetzen wäre ein Umschreiben statt eines Einfügens.
- Der Pfad erreicht eine Collection, die der Autor im Flow-Stil geschrieben hat. Einen Eintrag daran anzuhängen schreibt Bytes um, die der Autor bereits geschrieben hat, statt eine Zeile hinzuzufügen — das ist eine Bearbeitung und keine Position.
- Der Pfad adressiert eine Block-Sequenz mit etwas, das keiner ihrer Indizes ist. Die Einträge einer Sequenz werden über ihre Position adressiert, daher erreicht ein Name in ihr nichts, und es lässt sich kein Eintrag anlegen, der diesen Namen trägt.
Gelesen wird der Puffer, den der Editor hält, nicht nur die Datei auf der Festplatte. Der Parse-Cache des Daemons wird zuerst befragt, sodass eine Position gegenüber ungespeichertem Inhalt gemeldet wird, wo es welchen gibt, und gegenüber der Datei selbst, wo der Cache nichts für sie enthält.
Die Methode meldet und schreibt nie. Sie verändert nichts, löst nichts auf, erreicht keine Registry und kein Netzwerk und schreibt nichts in ein Dokument. Sie stellt weder den Text eines Eintrags zusammen noch wendet sie einen an. Das Zusammenstellen und Anwenden der Bearbeitung ist Sache des Editors, denn dort liegen der Puffer und der Undo-Verlauf.
Was Ihnen eine Dokumentbearbeitungs-Antwort sagt
aggrega/editDocument ist die andere Hälfte des Paares oben: Jene sagen, wohin ein Eintrag gehört, und überlassen Ihnen das Zusammenstellen und Anwenden; diese stellt einen zusammen und wendet ihn an, und sie schreibt. Beide bleiben verfügbar, weil ein Client mit einem ungespeicherten Puffer und ein Client, der bearbeitet, was auf der Festplatte liegt, unterschiedliche Hälften wollen — ein Editor mit eigenem Undo-Verlauf platziert den Text selbst, während ein Client, der die Datei lieber bearbeitet haben möchte, als gesagt zu bekommen, wo er sie bearbeiten soll, diese Anfrage sendet.
Ein Aufruf wendet eine Bearbeitung an, und die Menge der Bearbeitungen ist abgeschlossen. edit benennt, welche: add-component fügt eine Komponenteninstanz unter einem Komponenten-Container hinzu, attach-feature hängt ein Feature an einen Knoten an, wire-edge verdrahtet eine Verbindung in einem der Abhängigkeits-Sockets eines Knotens, und set-value setzt einen Wert an einem Knoten. Es gibt keine Bearbeitung, die löscht, einen bereits geschriebenen Block ersetzt, etwas umordnet oder von Ihnen gelieferte Bytes wörtlich schreibt — dies ist also kein Dateischreiber unter einem engeren Namen, und ein Wert außerhalb der vier wird abgelehnt statt interpretiert. Die Ablehnung listet auf, was Sie benennen dürfen.
Sie benennen den Knoten als strukturellen Pfad, genau so, wie die beiden Anfragen oben einen entgegennehmen. node ist der Pfad ab der Dokumentwurzel — ["spec", "components", "web"] — und der Container, in den der Eintrag geht, ergibt sich aus edit. Bei add-component benennt der Pfad den Komponenten-Container selbst, weil der hinzugefügte Eintrag der Knoten ist. name ist der Schlüssel, unter dem der Eintrag geschrieben wird: der Instanzname, der Name des Anhangs, der Alias der Verbindung oder der Schlüssel des Werts. value ist das, was dieser Eintrag enthält, und was es bedeutet, ergibt sich aus edit — die Entität, die der Eintrag anfordert, der Knoten, auf den eine Verbindung zeigt, oder der Skalar, auf den ein Wert gesetzt wird. socket wird für wire-edge gelesen und sonst ignoriert.
Ein Pfad statt eines Namens, aus demselben Grund, aus dem die lokalisierende Anfrage einen entgegennimmt: Ein Name müsste gesucht werden, und ein Name, der auf zwei Ebenen vorkommt, würde den Compiler entscheiden lassen, welchen Sie gemeint haben. Ein Client, der weiß, welchen Knoten er bearbeitet, sagt es also, und ein Client, der es nicht weiß, weiß, dass er eine Frage zu beantworten hat, bevor er irgendetwas bearbeitet.
Jedes Byte, das die Bearbeitung nicht berührt, bleibt erhalten. Das Dokument wird nur geparst, um den Container und die Zeile zu finden, an der sein Block endet; der Eintrag wird gerendert und auf Zeilenebene eingefügt. Kommentare, Leerzeilen, Anführungsstil, Folded- und Literal-Skalare, Template-Ausdrücke und die Form des abschließenden Zeilenumbruchs bleiben unverändert erhalten, und der Verschachtelungsschritt wird an der eigenen Einrückung des Dokuments gemessen statt vorgegeben — so landet ein Eintrag in dem Stil, in dem Sie bereits schreiben. Dieselbe Anfrage gegen dasselbe Dokument erzeugt dieselben Bytes, sodass ein Client zwei Läufe vergleichen kann und ein Review eine Bearbeitung als einen Diff liest.
Das Ergebnis muss ein Dokument sein, das Sie auch selbst hätten tippen können, und davon hängt das Schreiben ab. Das zusammengestellte Dokument wird gegen das Schema seiner eigenen Art validiert und erreicht die Festplatte nur, wenn das gelingt. Eine Anfrage, die etwas erzeugen würde, das das Authoring-Schema ablehnt, kommt als E0275 zurück — the edit was refused because the resulting document would not be valid, and nothing was written (die Bearbeitung wurde abgelehnt, weil das resultierende Dokument nicht gültig wäre, und es wurde nichts geschrieben) — und enthält die Eigenschaft, die das Schema nicht zulassen würde, samt ihrer Stelle. Die Datei bleibt Byte für Byte, wie sie war, sodass eine abgelehnte Bearbeitung nicht von einer nie versuchten zu unterscheiden ist und Sie eine korrigierte Anfrage gegen das Dokument wiederholen können, mit dem Sie begonnen haben. Deshalb wird hier auch keine Regel wiederholt: Die Anforderung, ein Release-Dokument solle einen Entwicklerwert enthalten, wird von demselben Schema abgelehnt, das auch das von Hand getippte Dokument ablehnen würde.
Was semantisch zulässig ist, wird hier nicht entschieden. Ob ein Abhängigkeits-Socket einer ist, den der Producer deklariert, oder ob die Anwendbarkeit eines Feature erfüllt ist, gehört zur Auflösung, die ein Build durchführt, jeweils mit eigener Berichterstattung. Sie dürfen also eine Verbindung benennen, von der diese Anfrage nie gehört hat, und ein Aggregate darf einen Socket verfassen, den seine Katalogentität nicht vorab deklariert; was über einen Socket konsumiert werden darf, bleibt Sache des Producers. Führen Sie aggrega/validate mit einem Release aus oder fragen Sie den Graphen ab, wenn das die Frage ist.
Die Antwort benennt, was gelandet ist und was die Festplatte erreicht hat, und das sind verschiedene Fragen. content enthält das von der Bearbeitung erzeugte Dokument bei beiden Auslieferungsarten. written benennt die Datei, die die Festplatte erreicht hat, und ist bei dryRun leer. container ist der strukturelle Pfad des Containers, in dem der Eintrag gelandet ist, sodass Sie das gerade Hinzugefügte finden können, ohne diese Regel erneut herzuleiten. createdContainers benennt die Segmente, die diese Bearbeitung geschrieben hat, weil das Dokument sie nicht enthielt, das äußerste zuerst — leer im gewöhnlichen Fall, in dem der ganze Pfad bereits vorhanden war; daran erkennen Sie, ob ein Eintrag in einen bestehenden Block eingefügt wurde oder seinen eigenen Block mitgebracht hat. file und edit geben zurück, was Sie gesendet haben, sodass ein Client mit mehreren offenen Anfragen jede Antwort ihrer Frage zuordnet. written, container und createdContainers sind immer Arrays, leer statt fehlend.
Bei dryRun wird nichts angelegt. written ist leer, content enthält das Dokument, das ein Schreibvorgang erzeugt hätte, und die Datei bleibt unberührt — so kann ein Editor dem Autor das Ergebnis zum Speichern, Ändern oder Verwerfen vorlegen. Standard ist das Schreiben, weil das Produkt der Operation ein bearbeitetes Dokument ist und eine Schnittstelle, die eines erzeugt, es auch liefern muss: Eine Anfrage, die nichts über die Auslieferung sagt, bearbeitet die Datei.
Alles andere, was ein Schreibvorgang tut, tut auch ein Probelauf. Das zusammengestellte Dokument wird in beiden Fällen gegen das Schema seiner eigenen Art validiert, sodass eine Bearbeitung, die ein Schreibvorgang ablehnen würde, auch bei dryRun abgelehnt wird, unter Nennung derselben Eigenschaft — der Fehler, den Sie aus einem Probelauf erhalten, ist also der Fehler, den Ihnen der Schreibvorgang gegeben hätte.
Ein Eintrag, der bereits vorhanden ist und enthält, was Sie angefordert haben, ist ein No-op — das Dokument kommt unverändert zurück, und nichts wird geschrieben. Ein Eintrag dieses Namens mit anderem Inhalt wird abgelehnt statt ersetzt, weil das Ersetzen dessen, was ein Autor geschrieben hat, keine der vier Bearbeitungen ist.
Nach einem Schreibvorgang liest der Daemon das Dokument neu ein. Was er für diese Datei vorhielt, wird verworfen, und seine Sicht auf Workspace-Ebene wird zurückgesetzt, sodass die nächste Validierungs-, Hover-, Vervollständigungs- oder Graph-Anfrage anhand der von der Bearbeitung erzeugten Bytes beantwortet wird statt anhand der ersetzten Version. Die Bearbeitung selbst liest die Datei auf der Festplatte und nicht den Puffer, den Sie halten — anders als die lokalisierende Anfrage oben, die zuerst ungespeicherten Inhalt befragt. Das ist beabsichtigt: Aus einem ungespeicherten Puffer zu schreiben, würde Inhalt, den der Autor nicht gespeichert hat, unter dem Vorwand, einen Eintrag anzuwenden, auf die Seite bringen. Speichern Sie den Puffer, dann bearbeiten Sie.
Eine Anfrage, die keine Stelle adressiert, an die ein Eintrag gehen kann, wird abgelehnt statt beantwortet, mit dem standardmäßigen invalid-params-Code, und ein erneuter Versuch ändert nichts, bis sich die Anfrage ändert. Das Dokument wurde nicht benannt, liegt nicht im Workspace, konnte nicht gelesen werden, ist kein wohlgeformtes YAML oder deklariert keine Art, gegen deren Schema das Ergebnis geprüft werden könnte; edit wurde nicht benannt oder ist keine der vier; node benennt nichts, oder eines seiner Segmente ist leer; es wurde kein name angegeben; wire-edge hat keinen socket benannt; set-value erhielt ein Mapping oder eine Sequenz, wo ein Skalar hingehört; der Knotenpfad erreicht einen Skalar oder eine Sequenz oder eine im Flow-Stil geschriebene Collection, wo das Hinzufügen einer Zeile bereits vorhandene Bytes umschreiben würde; oder der Knotenpfad erreicht nichts im Dokument.
Sie löst keine Abhängigkeit auf, erreicht keine Registry und berührt bei keiner der beiden Auslieferungsarten das Netzwerk.
Was die Antwort zur effektiven Konfiguration abdeckt
aggrega/effectiveConfiguration beantwortet zwei Fragen: welche Konfiguration in dieser Sitzung gilt und welche Ebene jede Einstellung entschieden hat. Es ist dieselbe Antwort, die aggrega config show --origin ausgibt, einmal berechnet und auf beiden Schnittstellen gemeldet, sodass die beiden sich nicht darüber widersprechen können, woher eine Einstellung stammt.
Eine source hat eine von vier Formen. Der absolute Pfad einer Konfigurationsdatei — einschließlich der globalen Datei, die ein als aggrega --config <file> serve gestarteter Daemon liest, benannt mit dem Pfad, der ihm übergeben wurde; eine Umgebungsvariable hinter einem env:-Präfix, etwa env:AGGREGA_SIGNING_REQUIRED; ein globales Flag, das auf der Befehlszeile eingegeben wurde, die den Daemon gestartet hat, benannt als das Flag, etwa --offline für einen als aggrega --offline serve gestarteten Daemon; oder (built-in defaults) für eine Einstellung, die keine Ebene setzt. Die ersten drei erscheinen wörtlich in layers. Die Standardwerte nicht, weil die Standardwerte keine Ebene sind, die etwas beigetragen hat — sie sind das, was gilt, wo keine Ebene etwas festgelegt hat.
Eine Einstellung wird der Ebene mit dem höchsten Vorrang zugeschrieben, die sie setzt, unabhängig davon, welchen Wert diese Ebene schreibt. Eine Konfigurationsdatei, die den eingebauten Standardwert schreibt oder einen Wert wiederholt, den eine darunterliegende Datei bereits setzt, ist die benannte Datei: Sie ist diejenige, die den Wert festhält. Eine Datei setzt eine Einstellung, indem sie deren Schlüssel enthält, einschließlich des _append-Begleiters einer Liste, und eine Umgebungsvariable, indem sie mit einem nicht leeren Wert exportiert wird. Die Konfigurationsdatei, die Ihrer Pipeline gehört, wird nie für einen Schlüssel benannt, den sie ignoriert. aggrega config show --origin meldet nach derselben Regel.
Jede Einstellung, die das Konfigurationsschema deklariert, wird berücksichtigt, wenn auch nicht jede mit einer eigenen Zeile. Der additive _append-Begleiter einer Liste wird in der Zeile der Liste gemeldet, zu der er hinzufügt, sodass eine Ebene, die nur über den Begleiter beiträgt, in der Zeile dieser Liste benannt wird und der Begleiter keine eigene Zeile hat. Eine Einstellung innerhalb der Einträge einer Liste — die Vertrauensrichtlinie einer Registry, die Eingaben eines Plugin-Anhangs — ist durch die Zeile dieser Liste abgedeckt.
Zwei weitere Grenzen, von denen jede eine Antwort gröber macht, als sie aussieht.
- Eine Listen- oder Map-Einstellung wird als Ganzes zugeschrieben, der Ebene mit dem höchsten Vorrang, die sie setzt. Eine Zuschreibung pro Eintrag wird nicht verfolgt, sodass eine aus zwei Ebenen zusammengesetzte Liste nur die mit dem höheren Vorrang meldet und ein von einer niedrigeren Ebene beigetragener Eintrag nicht von einem zu unterscheiden ist, den die höhere Ebene geschrieben hat.
- Die Signaturanforderung wird der ersten Ebene zugeschrieben, die sie eingeschaltet hat, nicht der letzten, die sie erwähnt hat. Diese Einstellung wird so zusammengesetzt, dass jede Ebene, die sie einschaltet, gewinnt und keine spätere Ebene sie ausschalten kann; die erste Ebene, die sie einschaltet, ist also diejenige, die den effektiven Wert zu dem gemacht hat, was er ist. Eine Ebene, die
required: falseschreibt, schaltet nichts ein; wo also jede Ebene, die sie erwähnt,falseschreibt, meldet die Einstellung(built-in defaults).
Jeder gemeldete Wert ist die Auflösung, die vorgenommen wurde, als dieser Workspace zum ersten Mal benannt wurde. Das Bearbeiten einer Konfigurationsdatei ändert hier keinen Wert; ein Neustart des Daemons schon. Das ist beabsichtigt — die Werte sind die Konfiguration, unter der jede andere Anfrage zu diesem Workspace beantwortet wird, und das macht sie vergleichbar mit der Wurzel und der Konfigurationsebene, die der Handshake dafür gemeldet hat. Ein Client, der die Konfiguration neben einer Datei anzeigt, die der Benutzer gerade bearbeitet, sollte sagen, welche der beiden er anzeigt.
Die Zuschreibung zu den Ebenen wird ermittelt, wenn Sie fragen, anhand der Dateien in ihrem aktuellen Zustand. Eine danach bearbeitete Konfigurationsdatei kann also eine source verschieben, während der Wert daneben so bleibt, wie er aufgelöst wurde. Die beiden Hälften beantworten verschiedene Fragen — was gilt und welche Ebene es entschieden hat — und nur die erste ist fest. Starten Sie den Daemon neu, um sie wieder in Einklang zu bringen.
Die Methode meldet und schreibt nie. Sie ändert keine Konfiguration, legt keine Datei an und löst nichts aus einer Registry oder dem Netzwerk auf.
Der Inhalt der Datei einer einzelnen Ebene wird hier nicht geliefert. Die Befehlszeile kann die eigenen Bytes einer Ebene wörtlich ausgeben, mit erhaltenen Kommentaren und Formatierung; diese Methode meldet die Auflösung statt der Bytes. Ein Client, der den Text einer Ebene möchte, hat den Pfad in layers und kann ihn öffnen.
Was ein Konfigurations-Schreibvorgang hinterlässt
aggrega/configInit und aggrega/configCapture erzeugen beide ein Konfigurationsdokument, und beide schreiben es. Die Antwort benennt die Datei; sie zu öffnen ist Ihr nächster Schritt, kein Ersatz für das Schreiben. Keine der beiden übergibt Ihnen Inhalt, den Sie selbst platzieren, es sei denn, Sie fordern das ausdrücklich an, denn eine Fähigkeit, deren Produkt ein nie geschriebenes Dokument ist, ist eine andere Fähigkeit unter demselben Namen.
Die beiden unterscheiden sich darin, wie weit sie reichen, und jede Antwort sagt, wie weit. Lesen Sie das, bevor Sie das Ergebnis anzeigen.
- Das Initialisieren schreibt standardmäßig die Konfiguration, die von allen Workspaces auf der Maschine geteilt wird. Eine Registry und die Identitäten, denen Sie dort vertrauen, sind in der Regel überall dieselben, wo Sie arbeiten, daher geht der Eintrag dorthin, sofern die Anfrage nicht
workspace: truesendet.scopeenthält die geschriebeneconfigFileundmachineWide, das angibt, ob es die geteilte ist — abgeleitet aus der Datei, zu der der Schreibvorgang aufgelöst wurde, statt aus dem, was die Anfrage verlangt hat, sodass eine Antwort eine maschinenweite Änderung nicht als lokale beschreiben kann. - Das Einfrieren reicht nie über den Workspace hinaus. Es nimmt weder ein Schreibziel noch eine Überschreibung entgegen: Sein ganzer Zweck ist es, ein Projekt eigenständig zu machen, daher schreibt es immer die eigene
.aggrega-config.yamldieses Projekts. Deshalb enthält seine AntwortconfigFileundworkspaceRootund beansprucht keinen Scope — es gibt keine Reichweite anzugeben.
Das Initialisieren lehnt ab, statt zu überschreiben. Eine bereits vorhandene Konfigurationsdatei bleibt unberührt, und die Ablehnung benennt sie, denn das Initialisieren ist für eine Konfiguration gedacht, die noch nicht existiert, während der geteilte Schreibvorgang, an den es delegiert, absichtlich zusammenführt. Senden Sie force, um trotzdem zu schreiben; der Registry-Eintrag wird mit dem bereits Vorhandenen zusammengeführt, und die übrigen Einstellungen bleiben erhalten. Eine abgelehnte Anfrage ändert überhaupt nichts.
trust sagt, was die von der Registry veröffentlichte Richtlinie bewirkt hat, als getrennte Ergebnisse statt als Fließtext. pinned bedeutet, dass die Registry eine Richtlinie veröffentlicht hat und diese übernommen wurde, wobei identities die Identitäten zählt. notAdvertised bedeutet, dass die Registry gefragt wurde und keine veröffentlicht hat, was kein Fehler ist — das Initialisieren läuft weiter, und reason sagt, was der Endpunkt getan hat. Eine Registry, die nicht erreicht werden konnte, wird ebenso gemeldet, da keine Richtlinie zurückkam und das Initialisieren gleichermaßen weiterläuft, und trägt daneben unreachable, wo der Fehler selbst zeigt, dass die Registry nie erreicht wurde: Ihr Name ließ sich nicht auflösen, eine Verbindung zu ihr wurde abgelehnt oder konnte nicht geöffnet werden, oder eine sichere Verbindung zu ihr konnte nicht hergestellt werden. Eine Registry, die geantwortet hat — mit einem Not-found oder mit einem Fehlerstatus —, trägt nie unreachable; lesen Sie also diesen Schlüssel statt des Wortlauts von reason, um eine Registry, die keine Richtlinie veröffentlicht, von einer zu unterscheiden, die nie gefragt wurde. baseline bedeutet, dass die eingebaute Baseline des offiziellen Hubs gepinnt wurde, weil keine veröffentlichte Richtlinie übernommen wurde, wobei reason sagt, warum; der Eintrag enthält eine Richtlinie, es gibt also nichts von Hand zu pinnen. Die beiden Schlüssel beantworten verschiedene Fragen, daher trägt ein Hub, der gefragt wurde und nichts veröffentlicht hat, beide, und ein Hub in einem Offline-Workspace — nie gefragt — trägt nur baseline, wobei reason sagt, dass der Workspace offline ist. Jede andere Registry, die nichts veröffentlicht, trägt nur notAdvertised, wird ohne Richtlinie initialisiert, und der folgende Rat lautet, Identitäten von Hand zu pinnen; offline wird sie abgelehnt statt beantwortet. skipped bedeutet, dass kein Abruf versucht wurde. Ein Client, der alles außer pinned als Fehler behandelte, würde eine funktionierende Konfiguration als defekt melden.
Bei dryRun wird nichts angelegt. written ist false, content enthält das Dokument, das ein Schreibvorgang erzeugt hätte, und die Datei, für die dieser Inhalt bestimmt ist, ist scope.configFile. Es wird kein Verzeichnis angelegt und keine Datei berührt, sodass ein Editor dem Autor den Text vorlegen und ihn speichern, ändern oder verwerfen lassen kann.
Ein Probelauf unterscheidet sich von einem Schreibvorgang in genau einer Hinsicht — er schreibt nicht —, daher führt er jede Ablehnung durch, die ein Schreibvorgang durchführt. Die Ablehnung wegen einer vorhandenen Datei ist hier die entscheidende: dryRun über eine bereits vorhandene Konfigurationsdatei wird abgelehnt, unter Nennung der Datei, genau wie ein Schreibvorgang. Das macht die Antwort als Prädikat verwendbar — lehnt der Probelauf ab, hätte der Schreibvorgang abgelehnt, aus demselben Grund und mit derselben Meldung. Senden Sie force zusammen mit dryRun, um stattdessen die Zusammenführung zu erhalten, die ein überschreibender Schreibvorgang erzeugen würde, weiterhin ohne etwas zu schreiben. Die Registry wird bei beiden Auslieferungsarten nach ihrer veröffentlichten Vertrauensrichtlinie gefragt, weil die Richtlinie in diesem Inhalt die Richtlinie ist, die ein Schreibvorgang gepinnt hätte.
Was ein Einfrieren meldet, ist das, was es geschrieben hat, keine Beschreibung davon. sockets listet jeden eingefrorenen Plugin-Socket mit den dort eingefrorenen Anhängen auf; catalogDirs enthält die Katalogverzeichnisse. Beide sind immer Arrays, leer statt fehlend.
socketundfieldsind nicht derselbe String, und der Unterschied ist nicht kosmetisch.socketbenennt den Socket, an den die Anhänge gebunden sind;fieldist der Schlüssel, unter dem sie in der Datei geschrieben wurden. Sie unterscheiden sich allein beim Provider-Socket, der unter einem Schlüssel im Plural geschrieben wird — verwenden Sie alsofield, wenn Sie einen Leser auf eine Zeile im Dokument verweisen, undsocket, wenn Sie den Socket selbst benennen.- Jeder Anhang enthält
uri,capability,functionundrole, jeweils nur, wo der Anhang eines davon hat. Sie benennen den Anhang, statt ihn vollständig wiederzugeben: Die optionalen Eingaben eines Anhangs zum Zeitpunkt des Anhängens werden wörtlich in die Datei eingefroren und in der Antwort nicht wiederholt. Die Datei ist die maßgebliche Kopie. captured: falseist ein Erfolg. Ein Projekt, an dessen Konfiguration ein Build nicht beteiligt ist, hat nichts Build-Kritisches einzufrieren, daher bleibt die Datei, wie sie ist, und beide Listen kommen leer zurück. Wer das als Fehler behandelt, meldet einen gesunden Workspace als defekt.
Standardmäßig wird nur eingefroren, was die Ausgabe-Bytes bestimmt — die Provider-Bindungen und die Governance-Anhänge, die Labels transformieren. Die Verdict-Gates von Governance und Lintern und der Import-Socket bleiben außen vor, weil sie zwischen Umgebungen variieren sollen und ihr Einfrieren die Gates einer Umgebung in jeden Checkout tragen würde. allPlugins: true erweitert die Menge auf jeden Plugin-Socket. Die Zugehörigkeit gilt pro Anhang, nicht pro Socket, sodass ein Governance-Socket mit einem Label-Transformations-Anhang und einem Verdict-Anhang standardmäßig nur den ersten beiträgt.
Jeder Wert wird mit seinem effektiven Wert eingefroren — dem, was sich aus der Konfiguration der Maschine und der des Projekts zusammengeführt ergibt —, sodass eine Bindung, die heute nur aus der Konfiguration der Maschine stammt, in das Projekt geschrieben wird und mit ihm wandert. Maschinenweite Werkzeugeinstellungen, darunter die Vertrauensrichtlinie einer Registry, sind nicht Build-kritisch und bleiben, wo sie sind. Zweimaliges Einfrieren über einer unveränderten Konfiguration schreibt dieselben Bytes neu, sodass ein Client es frei anbieten kann: Ein zweiter Aufruf lässt das Dokument, das ein Leser offen hat, genau so, wie es war.
Was Ihnen eine Plugin-Änderung sagt
Die vier Plugin-Anfragen schreiben alle standardmäßig, und sie teilen sich danach auf, was sie schreiben: Zwei ändern eine Konfigurationsdatei, und zwei erzeugen Dokumente im Workspace. Zwei davon — das Hinzufügen und das Generieren — nehmen dryRun entgegen, das alles andere tut, was die Anfrage tut, und nichts schreibt. Lesen Sie die eigene Angabe der Antwort dazu, wo die Änderung gelandet ist, statt sie aus der Anfrage abzuleiten — bei einer von ihnen bedeutet eine Anfrage, die nichts zur Reichweite sagt, die größte Reichweite.
Ein Hinzufügen und ein Entfernen enthalten beide scope, abgeleitet aus der Datei, zu der der Schreibvorgang aufgelöst wurde. configFile ist diese Datei, machineWide sagt, ob es diejenige ist, über die jeder Workspace auf dieser Maschine auflöst, und workspaceRoot benennt den Workspace, über dem diese Sitzung geöffnet wurde, sodass eine Workspace-bezogene Antwort sagt, um welchen Workspace es ging. machineWide wird an der aufgelösten Datei abgelesen statt an dem, was die Anfrage verlangt hat — das verhindert, dass eine Antwort eine maschinenweite Änderung als lokale beschreibt.
🔴 Ein Hinzufügen vom Typ cli, das weder global noch workspace benennt, registriert den Befehl maschinenweit. Eine Befehlserweiterung ist maschinenweites Werkzeug, daher wird sie ohne Überschreibung in die globale Konfigurationsdatei geschrieben, über die jeder Workspace auf dieser Maschine auflöst — und der Befehl, den sie registriert, ist dann ein aggrega-Befehl der obersten Ebene für jedes Projekt auf dieser Maschine, einschließlich Projekten, die in dieser Sitzung niemand benannt hat. Ein Hinzufügen vom Typ provider, governance, linter oder importer verhält sich umgekehrt: Diese prägen den Build eines Projekts, daher gehen sie ohne Überschreibung in die eigene .aggrega-config.yaml dieses Projekts. Ein Entfernen folgt für dieselben Typen derselben Regel. Senden Sie workspace: true, um eine Befehlserweiterung lokal zu halten, oder global: true, um einen der anderen in die geteilte Datei auszulagern; beides zu senden wird abgelehnt. Der scope in der Antwort ist in jedem Fall die maßgebliche Aussage, und ein Client sollte ihn anzeigen, bevor er auf das Ergebnis reagiert.
Ein Hinzufügen benennt, was gelandet ist, und genau eines von drei Feldern sagt, welche Art von Ding es war. type gibt den Typ zurück, für den der Eintrag hinzugefügt wurde, und dann: identity enthält die reine, versionsgepinnte Entitätsidentität für einen governance-, linter- oder importer-Anhang; uri enthält die oci://-Artefaktadresse des Plugins, zusammen mit der capability, die es nun bedient, für eine provider-Bindung; und reference enthält die gepinnte Referenz, deren Befehle registriert wurden, für eine cli-Installation. Ein Aufrufer liest also an der Antwort ab, welche Art von Anhang gelandet ist, statt sie aus dem gesendeten Typ erneut herzuleiten. Ein Entfernen gibt type und query neben seinem scope zurück und sonst nichts — über einen Eintrag, der weg ist, gibt es nichts weiter zu melden.
Ein Hinzufügen enthält außerdem written und, bei dryRun, content. written ist das, worauf ein Client verzweigt: true benennt eine nun auf der Festplatte liegende Konfigurationsdatei, die der Client öffnen kann, und bei dryRun ist es false, und content enthält stattdessen das Konfigurationsdokument, das der Schreibvorgang erzeugt hätte. Die beiden sind nie zugleich aussagekräftig, und die Datei, für die content bestimmt ist, ist scope.configFile, sodass nichts in der Antwort eine zweite Kopie dieses Pfads enthält — was hier wichtig ist, weil die Datei eines global-Anhangs diejenige ist, über die jeder Workspace auf dieser Maschine auflöst.
Ein Plugin ohne veröffentlichte Version wird abgelehnt, statt ungepinnt angehängt zu werden. Ein Hinzufügen löst die Abfrage zu einem Plugin auf und pinnt dessen höchste veröffentlichte Version, sodass der geschriebene Eintrag eine Version trägt. Ein Plugin, dessen Repository keine konforme Version veröffentlicht, wird unter Nennung abgelehnt, und eine Version, die eine Retraction, der dieser Workspace vertraut, zurückgezogen hat, wird zugunsten der nächstniedrigeren übergangen.
Eine Version, die die Abfrage nennt, wird auch dann festgelegt, wenn sie zurückgezogen wurde, und withdrawn zeigt das an. Eine als <name>:<version> geschriebene query legt diese Version statt der neuesten fest – bei jedem Typ außer provider, der allein über den Namen gebunden wird und eine Version ablehnt –, und das Nennen einer Version ist die Überschreibung: Wo eine Rücknahme, der dieser Workspace vertraut, sie zurückgezogen hat, wird sie trotzdem festgelegt, und die Antwort enthält withdrawn: true – die Tatsache, die aggrega plugin add im Terminal als retraction:-Zeile ausgibt. withdrawn fehlt in jeder anderen Antwort, sodass sein Vorhandensein das ganze Signal ist – und sein Fehlen keine Aussage darüber, dass die Version nicht zurückgezogen ist. Wo die Rückzugsmarkierungen einer genannten Version nicht gelesen werden konnten, fehlt withdrawn, und retraction enthält unscreened mit der Begründung, wie bei einem Hinzufügen ohne genannte Version, das auf denselben Fehler stößt; ein Hinzufügen ohne genannte Version meldet stattdessen in retraction, zu welchem Ergebnis die Rückzugsprüfung für die von ihm gewählte Version gekommen ist.
Ein Abgleich meldet, ob er etwas geändert hat, und das ist das Feld, nach dem man handelt. changed trennt einen Schreibvorgang von einem Abgleich, der die Einträge bereits korrekt vorgefunden hat: Eine unveränderte Datei bleibt Byte für Byte identisch, sodass ein Client, der dieses Dokument hält, nichts neu zu laden hat, und eine zweimal ausgeführte Anfrage beim zweiten Mal keine Änderung meldet. entity benennt die Datei, hostFunctions enthält die abgeleitete Menge, und commands enthält die Spiegelung als Werte statt als die Zeile, die ein Terminal ausgibt — jeder Eintrag ein name, eine optionale description und flags, jedes Flag mit seinem name und seinen optionalen shorthand, description, type und default. Der Schreibvorgang ist atomar, sodass ein Client, der diese Datei liest, während der Abgleich läuft, nie ein unvollständiges Dokument sieht.
Ein Generieren füllt genau eine Hälfte seiner Antwort, und das eigene dryRun der Antwort sagt, welche. Standardmäßig werden die Entitäten geschrieben, und notices enthält, was das Generieren zu den durchgeführten Schreibvorgängen gesagt hat. Bei dryRun wird nichts angelegt oder geändert: documents enthält jede generierte Entität als den path, für den sie bestimmt ist, und ihren content, sodass ein Client sie in sein eigenes Dokumentmodell übernehmen kann, wo sie sichtbar sind, bevor sie gespeichert werden, und geändert oder verworfen werden können. Die beiden Hälften sind nie beide gefüllt, sodass sich an der Antwort ablesen lässt, welche Auslieferungsart gelaufen ist, statt an dem, was angefordert wurde.
Wohin eine Plugin-Anfrage SCHREIBT, liegt immer innerhalb des Workspace, den diese Anfrage benannt hat; was sie LIEST, wird pro Feld entschieden. Ein absolutes Ziel, eines, das aus der Wurzel herausklettert, und eines, das über einen Link aus ihr herausführt, werden abgelehnt statt aufgelöst — so kann ein Generieren keine Entitäten in einem Baum anlegen, über dem Ihre Sitzung nie geöffnet wurde, was immer es sendet. Ein Pfad, den eine Anfrage nur liest, ist eine eigene Frage, die Feld für Feld beantwortet wird statt mit einer Regel für alle: aggrega/pluginGenCatalog liest ein Modul und sein Overlay von dort, wo Sie sie ausgewählt haben, weil ein von Ihnen gebautes Modul im Ausgabeverzeichnis Ihrer Toolchain liegt und die Weigerung, es dort zu lesen, die Operation in ihrem ganzen Zweck verweigern würde. aggrega/pluginSync liest seine beiden Pfade innerhalb des Workspace, weil es bei dieser Anfrage um eine Datei geht, die der Workspace bereits enthält. Die lokalisierenden Anfragen oben akzeptieren einen absoluten Pfad aus wiederum einem anderen Grund — ein Dokument, das der Client bereits geöffnet hat, benannt in der Schreibweise, die er hält.
Eine Anfrage, der etwas fehlt, das die Operation braucht, wird unter Nennung des zu sendenden Felds abgelehnt. Ein Hinzufügen oder Entfernen ohne type oder query; ein provider-Hinzufügen ohne capability oder ein governance-Hinzufügen ohne role; ein cli-Hinzufügen ohne acceptCapabilities; ein Abgleich ohne entity oder plugin; ein Generieren, das beide Auswahlmodi oder keinen benennt oder dem overlay oder outputDir fehlt. Jede kommt mit dem standardmäßigen invalid-params-Code zurück, und ein erneuter Versuch ändert nichts, bis sich die Anfrage ändert. Ein Entfernen, dessen Abfrage auf keinen Eintrag passt, wird ebenfalls abgelehnt, unter Nennung des Typs, der Abfrage und der Datei, in der gesucht wurde — das ist ein Zustand der Konfiguration statt der Anfrage, sodass das zu Korrigierende das eine oder das andere sein kann.
Nichts wird interaktiv abgefragt, und die eine Entscheidung, nach der eine Person gefragt worden wäre, kommt stattdessen als Feld. Der Terminalbefehl fragt, wer gerade zusieht, ob die deklarierten Capabilities eines Befehlserweiterungs-Plugins akzeptiert werden. Diesem Stream sieht niemand zu, daher ist es Sache des Aufrufers, acceptCapabilities einzuholen und zu senden, und eine Anfrage, die es nicht enthält, wird unter Nennung dessen, was zu senden ist, abgelehnt, statt auf Grundlage einer Zustimmung zu installieren, die niemand gegeben hat. Ein Daemon, der ohne die Mittel zum Installieren einer Befehlserweiterung gestartet wurde, lehnt ein cli-Hinzufügen rundweg ab, statt einen Erfolg zu melden, der nichts installiert hat.
Welche Arten Sie einem Autor anbieten dürfen
aggrega/getSchema ohne kind beantwortet, welche Arten Sie benennen dürfen, und antwortet in zwei Breiten, weil ein Client für unterschiedliche Aufgaben unterschiedliche braucht. Lesen Sie die, nach der Sie fragen.
kinds ist jedes Token, auf das die Binärdatei antwortet. entityKinds ist die Menge, von der ein Autor ein Dokument schreibt. Die breite Liste enthält die Zwischendarstellung, die Lockfile, die Workspace-Konfiguration und die Plugin-Socket-Verträge neben den Arten, die Sie verfassen — jede davon ein echtes Schema, aber keine Dokumente, von denen jemand eine Datei schreibt. Die breite Liste ist also die, aus der man die Schema-Zuordnung eines Editors verdrahtet, und die schmale ist die, aus der man eine Auswahl baut. Eine aus der breiten Liste gebaute Auswahl bietet Werte an, die kein Authoring-Schema akzeptiert, und der Autor stößt erst auf die Ablehnung, nachdem er einen gewählt hat.
Die schmale Menge ist auch schmaler als die Entitätsarten, und kein Schema sagt Ihnen, welche. Eine plattformeigene Art, deren Inhalt im Dokument einer anderen Art geschrieben wird, ist kein Dokument, das man einem Autor zum Beginnen anbietet. Workload ist eine solche Art: Workload-Inhalt wird im Feld workload: eines Recipe oder eines FeatureRecipe geschrieben, entweder inline oder aus einer Datei, die dieses Feld importiert, daher gibt es kein eigenständig adressierbares Workload-Dokument — siehe die Authoring-Oberfläche der Workload dazu, wohin dieser Inhalt gehört. Ihr Schema legt apiVersion und kind genau so fest wie das Schema einer verfassten Art, weil das die Validierung des Inhalts dort ermöglicht, wo er steht; die festen Werte identifizieren den Inhalt und machen ihn nicht adressierbar. Sie sind also kein Signal dafür, dass eine Art zum Entwerfen gedacht ist. entityKinds enthält die Antwort, und nichts in den Bytes des Schemas tut das.
Jeder Eintrag in entityKinds enthält beide Schreibweisen, die ein Client braucht, und keine ist aus der anderen ableitbar. kind ist das kleingeschriebene, mit Bindestrichen versehene Token — senden Sie es als kind an diese Methode oder an aggrega/scaffoldEntity zurück. documentKind ist der Wert, den das Dokument selbst in seinem kind:-Feld der obersten Ebene trägt. Bei einer Art, deren Name aus mehr als einem Wort besteht, unterscheiden sich die beiden in mehr als der Groß- und Kleinschreibung: Nichts, was Sie mit featurerecipe tun können, ergibt FeatureRecipe. Nehmen Sie jede aus dem Eintrag, statt die eine aus der anderen herzuleiten, dann bleibt für den Client keine Zuordnung zu pflegen.
Jeder Eintrag sagt außerdem, welche Operationen ein Dokument seiner Art akzeptieren, sodass ein Steuerelement, das diese Operationen für ein Dokument anbietet, nur die anbietet, die es nicht wegen seiner Art ablehnen. acceptedBy enthält drei Booleans, jeder in jedem Eintrag vorhanden, und jeder betrifft ein Dokument der benannten Art für sich allein — über seinen Pfad oder, zur Inspektion, über seinen Namen —, ohne dass daneben etwas anderes gesendet wird. singleEntityValidation gibt an, ob aggrega validate <path> ein Dokument der Art prüft, statt es abzulehnen und den Gesamtkatalog- oder Release-Bereich zu nennen, der es stattdessen prüft. publication gibt an, ob aggrega/publishEntity mit nur dem Dokument es veröffentlicht: Ein Plugin ist false, weil seine Veröffentlichung auch die ausführbare Datei bindet, die eine Anfrage in plugin benennt, sodass eine Anfrage, die nur das Dokument benennt, abgelehnt wird; ein Manifest und ein Release sind false, weil keine der beiden Arten veröffentlicht wird. inspectionByName gibt an, ob aggrega/entityDefinition einen Namen zu einer Entität der Art auflöst, wobei der Name so gesendet wird, wie er geschrieben wird, wo eine Entität auf eine andere verweist — ein Plugin als <pluginType>/<name> und ein Recipe oder ein FeatureRecipe als <capability>/<name> oder nur mit seinem Namen, wo nur eine Capability diesen Namen deklariert. Ein true besagt, dass die Operation das Dokument nicht wegen seiner Art ablehnt; ein bestimmtes Dokument kann sie trotzdem wegen dessen Inhalt ablehnen.
Führen Sie keine eigene Liste. Welche Arten es gibt, ist eine Eigenschaft der Binärdatei, mit der Sie sprechen; eine in einen Client geschriebene Liste stimmt also an dem Tag, an dem sie geschrieben wird, und hört an dem Tag auf zu stimmen, an dem eine Art hinzukommt — und was der Autor dann sieht, ist, dass seine Art in genau dem Steuerelement fehlt, das sie anbieten sollte. Fragen Sie, und die Antwort folgt der Binärdatei.
Beide Hälften kommen zusammen, und nur, wenn Sie keine Art benennen. Eine Anfrage, die eine Art benennt, wird mit dem Schema dieser Art beantwortet und enthält keine der beiden Listen, sodass sich an der Antwort ablesen lässt, welche Frage Sie gestellt haben. Ein Token, auf das kein Schema antwortet, wird mit der vollständigen gültigen Menge in der Meldung abgelehnt, unter dem standardmäßigen invalid-params-Code, sodass ein Tippfehler eine zu korrigierende Anfrage ist statt etwas, wonach man eine Person fragen müsste.
Sie antwortet in einem Workspace, der nichts enthält. Das Vokabular ist in die Binärdatei kompiliert, daher braucht dies kein Dokument, keine Lockfile und keinen Katalog — und genau in einem solchen Workspace sitzt ein Autor, der sein erstes Dokument beginnt.
Was Ihnen eine Scaffold-Antwort liefert
Dieser Abschnitt behandelt das Entwerfen. Die andere Form der Methode schreibt ein ausführbares Beispiel, und ihre Antwort wird zusammen mit der Methode weiter oben beschrieben.
aggrega/scaffoldEntity gibt Text zurück. skeleton ist YAML für die Art, die Sie genannt haben: jedes Feld, das das Schema dieser Art verlangt, in der Reihenfolge, in der das Schema sie deklariert. Ein Feld, das das Schema auf einen einzigen festen Wert festlegt, kommt ausgefüllt an — apiVersion und kind sind die, die Ihnen auffallen werden —, metadata.name trägt den name, den Sie gesendet haben, und jeder andere erforderliche Wert kommt als Platzhalter an, typisiert nach dem, was das Schema dort deklariert: eine leere Zeichenkette, eine Null, ein false, eine leere Liste, eine leere Zuordnung. kind wiederholt das Token, für das das Dokument abgeleitet wurde, sodass ein Client mit mehreren ausstehenden Anfragen eine Antwort anhand der Antwort selbst zuordnet, statt eine eigene Korrelation zu führen.
Es schreibt nichts, und darauf ist das Design auszurichten. Die Methode erstellt keine Datei, wählt keinen Pfad und berührt kein Verzeichnis. Was Sie erhalten, ist ein zu schreibendes Dokument, kein geschriebenes — daher legt ein Editor den Text in einen neuen, ungespeicherten Puffer, den der Autor lesen, bearbeiten oder verwerfen kann, und der Moment, in dem eine neue Datei auf die Festplatte gelangt, bleibt dort, wo der Puffer und der Rückgängig-Verlauf sind. Keine andere Anfrage nimmt dieses Dokument und legt es in Ihrem Namen irgendwo ab; zu entscheiden, wo ein neues Dokument liegt, ist Sache des Editors.
Es löst nichts auf und braucht nichts vom Workspace. Das Dokument wird aus den Schemas abgeleitet, die das Binary enthält, daher erreicht die Methode keine Registry und kein Netzwerk, konsultiert keinen Katalog und liest keine Datei. Sie antwortet in jedem Workspace gleich, auch in einem leeren Verzeichnis, das noch kein Aggrega-Dokument enthält — genau der Workspace, in dem ein Autor sitzt, der sein erstes Dokument beginnt, und in dem die meisten anderen Methoden hier zuerst ein Dokument oder eine Lockfile verlangen würden.
Dieselbe Anfrage liefert dieselben Bytes, wo immer sie gestellt wird. Das Dokument wird von einer einzigen Berechnung erzeugt, die mit den anderen Oberflächen geteilt wird, die diese Fähigkeit anbieten, sodass ein Editor und ein Assistent, nach derselben Art und demselben Namen gefragt, dem Autor denselben Ausgangstext zeigen.
Das Skelett trägt die Felder, die seine Art verlangt, und es ist kein fertiges Dokument. Es trägt die erforderlichen Felder und sonst nichts: Ein optionales Feld, das Sie möchten, fügen Sie selbst hinzu, und jeder Platzhalter ist ein noch offener Wert. Füllen Sie die Platzhalter aus und führen Sie dann aggrega/validate auf dem Puffer aus. Für eine Katalog-Entität einer Art, die aggrega validate als einzelne Entität prüft, nennt diese Methode jeden noch offenen Platzhalter, jeweils an seinem Schlüssel mit dem, was er annimmt, nach derselben Lesart, die der Befehl auf die gespeicherte Datei anwendet — einschließlich eines Platzhalters, den das Schema leer zulässt; capability und implements eines entworfenen Recipe oder FeatureRecipe sind diejenigen, denen Sie begegnen werden. Für jede andere Art misst sie den Puffer am Schema seiner Art, sodass ein Platzhalter, den das Schema leer ablehnt — etwa eine Version —, als Befund dieses Schemas zurückkommt, und einer, den das Schema leer zulässt, keinen erzeugt. Live-Validierung beschreibt den Eintrag, als der jeder Platzhalter ankommt.
Was Ihnen eine Import-Antwort sagt
aggrega/import wandelt eine für ein anderes Werkzeug geschriebene Quelle in Entwürfe von Aggrega-Dokumenten um, und es schreibt sie — anders als das Scaffold oben, das Ihnen Text zurückgibt. written nennt jede Datei, die auf die Festplatte gelangt ist, relativ zu outputDir; files enthält jede Datei, die die Anfrage schreibt, mit ihrem content, ob sie geschrieben wurde oder nicht — jeden Entwurf, den der Importer erzeugt hat, dann die Aufzeichnung dessen, was der Import geschrieben hat, oder unter sync das, was die Synchronisierung ändert. Die beiden beantworten unterschiedliche Fragen, lesen Sie also dasjenige, das zu Ihrer Frage passt: was jetzt auf der Festplatte liegt oder was erzeugt wurde.
Sie wählen, wohin die Entwürfe kommen, oder überlassen es dem Workspace-Stamm. outputDir ist optional, so wie aggrega import --output-dir und output_dir des import-Werkzeugs des Assistenten: Eine Anfrage, die keines nennt, legt die Entwürfe unterhalb des Workspace-Stamms an — dort, wo aggrega import schreibt, wenn es kein Ziel erhält, wo auch immer es läuft —, und eine Anfrage, die eines nennt, legt sie dort an. Ein genanntes Verzeichnis ist ein Pfad innerhalb des Workspace, und ein relativer Wert wird gegen den Workspace-Stamm aufgelöst statt gegen ein Verzeichnis, in dem sich der Daemon gerade befindet. Die source, die Sie umwandeln, ist der andere Fall und wird nicht so eingeschränkt: Diese Datei oder dieses Verzeichnis haben Sie ausgewählt, daher wird sie gelesen, wo immer sie liegt, und das Lesen dort ändert nicht, wo die Entwürfe landen. Das Verzeichnis wird angelegt, wenn es nicht existiert. Unter dryRun wird nichts geschrieben, und jeder Entwurf nennt trotzdem den Pfad, für den er bestimmt ist, relativ zu dem outputDir, das die Antwort nennt — dem Verzeichnis, das Sie gesendet haben, oder dem Workspace-Stamm.
Eine Anfrage überschreibt nie ein Aggregate, das bereits in outputDir liegt. Ein Aggregate ist das Dokument, das ein Autor nach dem Entwurf weiter bearbeitet, daher wird eine Anfrage, bei der einer der Entwürfe auf einer Datei landen würde, die sich als Aggregate liest, abgelehnt, wobei der Entwurf und der Ort des Aggregate genannt werden, und es wird überhaupt nichts geschrieben — auch unter dryRun, da ein Probelauf ablehnt, was das Schreiben ablehnt. Senden Sie stattdessen sync, um es mit der Quelle abzugleichen, oder nennen Sie ein anderes outputDir, um daneben zu entwerfen. Jede andere Datei, die bereits unter einem Entwurfspfad liegt, wird überschrieben, und eine Datei, die ein früherer Import entworfen hat und dieser nicht entwirft, bleibt, wo sie ist. Jede Anfrage, die irgendetwas entwirft, schreibt außerdem .aggrega-import.json in outputDir, die Aufzeichnung dessen, was der Import geschrieben hat — das target, das ihm gesendet wurde, sofern eines gesendet wurde, den Katalog-Snapshot, den er gelesen hat, sofern er einen gelesen hat, und jede entworfene Datei und, in einem entworfenen Aggregate oder Release, jeden Schlüssel in jeder Tiefe, mit einem Digest des dort geschriebenen Textes, wobei jede andere entworfene Datei als Ganzes aufgezeichnet wird —, und files und written enthalten sie nach den Entwürfen. Sie ist JSON, daher liest nichts, was die YAML-Dokumente des Workspace liest, sie; sync liest sie wie aggrega import --sync, um die Entwürfe mit ihrer Quelle abzugleichen. Ein sync ohne target entwirft für das Ziel, das die Aufzeichnung nennt, und entwirft also das Manifest, das der frühere Import entworfen hat; einer mit einem target entwirft für dieses, und die Aufzeichnung nennt dann dieses. Ein aufgezeichnetes Ziel, an das sich keine Recipe im Katalog bindet, wird abgelehnt wie ein gesendetes, wobei die Ablehnung sagt, dass es sich um das aufgezeichnete Ziel handelt. Da ein entworfenes Release Schlüssel für Schlüssel aufgezeichnet wird, ist die Umgebung, die sein Autor dort schreibt, wo der Import einen Kommentar dafür hinterlassen hat, ein vom Autor geschriebener Schlüssel, und eine Synchronisierung lässt ihn Byte für Byte unverändert.
Senden Sie sync, um das, was ein früherer Import in outputDir entworfen hat, mit der Quelle abzugleichen, wobei nur geändert wird, was der Import geschrieben hat. Jeder Teil wird auf drei Arten beurteilt — was der Import laut Aufzeichnung zuletzt dorthin geschrieben hat, was auf der Festplatte liegt und was die Quelle jetzt entwirft. Ein Teil, den die Quelle so belassen hat, wie der Import ihn zuletzt geschrieben hat, bleibt genau so, wie er auf der Festplatte steht, ob ein Autor ihn bearbeitet hat oder nicht. Ein Teil, den die Quelle geändert hat, wird neu geschrieben, ein Teil, den sie weggelassen hat, wird entfernt — eine entworfene Datei wird als Ganzes gelöscht —, und ein Teil, den sie hinzugewonnen hat, wird neben den Teilen eingefügt, die der Entwurf um ihn herum nennt, jeweils nur dort, wo das auf der Festplatte Liegende das ist, was der Import zuletzt geschrieben hat, und nichts enthält, was ein Autor hinzugefügt hat. Alles andere bleibt Byte für Byte erhalten: ein Schlüssel, den ein Autor irgendwo hinzugefügt hat — ein Parameter, ein Feature, auch unter einer entworfenen Component-Instanz, eine weitere Component —, ein Kommentar, der nicht direkt über einem entworfenen Schlüssel steht, und jede Datei, die die Aufzeichnung nicht aufführt. Eine Synchronisierung in ein Verzeichnis, das keine Aufzeichnung und nichts unter seinen Entwurfspfaden enthält, schreibt den ganzen Entwurf, wie es eine Anfrage ohne sync tut.
drift ist das, was eine Synchronisierung abgeglichen hat, und es ist die Antwort auf „hat sich die Quelle verändert“. Es führt jeden Teil auf, den die Synchronisierung geändert hat — oder unter dryRun jeden Teil, den sie ändern würde —, in der Reihenfolge, in der der Entwurf sie nennt, jeweils als change (added, removed oder changed), file, die entworfene Datei, in der er liegt, relativ zu outputDir, und key, die Schlüssel, die in einem entworfenen Aggregate oder Release zu ihm führen, als Liste, sodass ein Schlüssel mit einem Punkt ein einziger Eintrag bleibt; key ist leer, wo der Teil die ganze Datei ist, und so wird eine entworfene Datei benannt, die die Synchronisierung löscht. aggrega import gibt dieselben Einträge auf der Standardfehlerausgabe als <change> <key> in <file> oder <change> <file> aus, und sein Exit-Status unter --sync --dry-run sagt, ob die Quelle abgewichen ist; diese Schnittstelle hat keinen Exit-Status, senden Sie also sync mit dryRun und prüfen Sie, ob drift leer ist. drift ist eine leere Liste für eine Anfrage, die keine Synchronisierung ist, für eine Synchronisierung, die mit ihrer Quelle übereinstimmt, und für eine Synchronisierung, deren Importer nicht zu Ende kam. Unter sync enthält files jede entworfene Datei, die die Synchronisierung ändert, mit dem Inhalt, den sie ihr gibt, dann die Aufzeichnung, wo auch diese sich ändert, und written nennt diejenigen, die auf die Festplatte gelangt sind — eine übereinstimmende Synchronisierung beantwortet beide also mit leeren Listen. Eine entworfene Datei, die die Synchronisierung löscht, wird in drift genannt und in keiner der beiden Listen: Ihr removed-Eintrag mit leerem key ist die einzige Auskunft der Antwort über sie und nennt unter dryRun die Datei, die ein Schreibvorgang löschen würde.
Eine Synchronisierung überschreibt nie, was ein Autor geschrieben hat, sondern lehnt stattdessen ab. Eine Synchronisierung, die einen von einem Autor bearbeiteten Teil ändern oder entfernen, einen Teil dort hinzufügen würde, wo ein Autor bereits einen geschrieben hat, oder einen Teil entfernen würde, der etwas von einem Autor Hinzugefügtes enthält, wird abgelehnt, wobei jeder solche Teil und der Grund in einer eigenen Zeile genannt werden, in den Worten, die aggrega import --sync verwendet — <file> <key>: <why> oder <file>: <why> für eine ganze Datei —, und es wird nichts geschrieben; ein Kommentar direkt über einem entworfenen Schlüssel bearbeitet diesen Schlüssel. Eine Synchronisierung über ein Aggregate, das keine Aufzeichnung aufführt, wird abgelehnt, wobei das Aggregate und die Aufzeichnung genannt werden, ebenso eine, deren Aufzeichnung nicht gelesen werden kann, da sich ohne die Aufzeichnung ihre Teile nicht von denen eines Autors unterscheiden lassen. Beide Ablehnungen kommen als invalid-params-Fehler zurück, auch unter dryRun, und nennen sync. Gleichen Sie jeden genannten Teil von Hand ab oder stellen Sie wieder her, was der Import dort geschrieben hat, und senden Sie die Anfrage erneut.
🔴 halted: true ist kein Fehler, und es als solchen zu behandeln, ist der Irrtum, gegen den Sie entwerfen sollten. Ein Importer, der nicht alles umwandeln konnte, entwirft trotzdem, was er konnte: Die Antwort enthält diese Entwürfe, written nennt sie, und diagnostics sagt, was ausgelassen wurde. Das ist die nützlichste Antwort, die die Operation gibt, und sie kommt als Ergebnis statt als Fehlschlag, gerade damit Sie dem Autor beide Hälften zeigen können. Unter sync schreibt dieselbe Antwort nichts — files, written und drift sind leer —, weil ein Teilentwurf sich wie eine Quelle lesen würde, die jeden Teil weggelassen hat, den der Importer nicht erreicht hat. Eine Quelle, die der Importer überhaupt nicht lesen konnte, ist ein anderer Fall und kommt tatsächlich als Fehler zurück.
Jede Diagnose enthält severity und message, dazu code, wo der Importer einen vergeben hat. Verzweigen Sie anhand von code, wenn Sie auf eine bestimmte Bedingung reagieren wollen, und zeigen Sie dem Leser message; severity stammt aus derselben Menge, in der jeder Plugin-Socket berichtet — halt, warn, info —, daher ist halted eine Zusammenfassung der Einträge und kein eigenes Urteil. files, written, drift, diagnostics und decisions sind immer Arrays, leer statt fehlend.
decisions sagt, wo der Import geraten hat. Es enthält einen Eintrag pro Quellknoten, den der Importer abgebildet hat, in der Reihenfolge des Importers und genau so, wie der Importer ihn gemeldet hat: sourceNode, id, type und paramsSummary des Knotens; candidates, jede Katalog-Component, die der Importer dafür abgewogen hat, als componentName, score, tier und signals — was jedes seiner Signale beigetragen hat, unter table, category, domainLabels, shape und name; chosen, das gewählte target, der mode, in dem er es geschrieben hat — eine reference auf eine bestehende Component oder ein draft —, und der tier der Wahl; rationale, die Begründung; und swapHint, wie man anders wählt. candidates fehlt, wo der Importer keine abgewogen hat, chosen, wo er keine Wahl getroffen hat, und rationale und swapHint, wo er keine geschrieben hat. Jeder Wert ist der des Importers selbst — wie er einen Kandidaten bewertet und wo seine Stufen liegen, entscheidet er —, zeigen Sie einen Eintrag also als seine Darstellung der Abbildung statt als Urteil. Die Entscheidungen kommen unter dryRun wie auch mit halted gleich true: Die Vermutungen eines Teilimports sind genau das, was ein Autor braucht, der ihn prüft, und ein Importer, der keine meldet, antwortet mit einer leeren Liste. Wo Sie sie als Text zeigen, formuliert aggrega import eine Entscheidung bereits als mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, wobei der Score der des besten Kandidaten ist.
Das Format wird an der Quelle erkannt, sofern Sie es nicht nennen. Die Erkennung verwendet die Signaturen, die die Importer deklarieren — die des Workspace-Katalogs ebenso wie die der Core-Importer des Compilers —, die die Plugin-Entität jedes Importers aufzeichnet — die Syntax, in der eine Quelle gelesen wird, die Dateinamen, für die eine Signatur gilt, und die Pfade, die der geparste Baum enthalten muss oder nicht enthalten darf —, sodass der Daemon selbst kein Format kennt und das Format eines neuen Importers erkannt wird, ohne dass sich sonst etwas ändert. Die Erkennung liest nur die Quelle, die Sie gesendet haben — bei einem Verzeichnis nur die Dateien, die die Dateimuster einer Signatur auswählen — und kein Netzwerk, wobei jede gelesene Datei mit dem Parser geparst wird, den der Katalog des Workspace für eine Syntax bereitstellt — oder, für eine Syntax, für die der Katalog keinen Parser bereitstellt, mit dem, den der Compiler selbst mitbringt —, einmal für jede Syntax, in der eine auf ihren Namen zutreffende Signatur sie liest; der Importer liest die Quelle dann mit demselben Parser. Eine Signatur, die kein Dateimuster deklariert, gilt für die von Ihnen gesendete Datei, wie auch immer sie heißt, und für keine Datei eines Verzeichnisses; die Signaturen der Importer für Langflow, Flowise und n8n sind von dieser Art und lesen JSON, und die des Dify-Importers liest YAML, daher liest das Erkennen einer einzeln gesendeten Datei diese als JSON und als YAML, was keinen Parser im Katalog des Workspace erfordert: Der Compiler bringt einen JSON- und einen YAML-Parser mit, und einer, den der Katalog bereitstellt, wird an seiner Stelle verwendet. Eine Quelle, auf die keine Signatur passt, wird abgelehnt, wobei nach format gefragt wird und die Formate genannt werden, die die Importer anbieten — oder, bei einem Verzeichnis, nach einer seiner Dateien, einzeln gesendet, oder nach einem format, dessen Importer Dateimuster deklariert, wobei nur diese genannt werden —, unter der Bedingung No importer recognises the source (Kein Importer erkennt die Quelle); eine Quelle, auf die Signaturen mehr als eines Formats passen, wird abgelehnt, wobei diese genannt werden, unter der Bedingung More than one importer recognises the source (Mehr als ein Importer erkennt die Quelle). Das data jeder Ablehnung enthält code und shortCode ihrer Bedingung, sodass ein Client anhand des Codes statt anhand des Wortlauts nach dem Format fragt. Keines von beiden wird erraten, weil ein geratenes Format den falschen Importer auflöst und selbstbewussten Unsinn erzeugt. format in der Antwort ist das verwendete, erkannte oder genannte Format, sodass ein Client, der es weggelassen hat, erfährt, was er bekommen hat.
Ein gesendetes Verzeichnis wird in die Dateien eingelesen, die sein Importer nennt, und eines, das sich nicht lesen lässt, ist ein Fehler. Wo source ein Verzeichnis nennt, erhält der Importer die Dateien darin, die die von seinen Signaturen deklarierten Dateimuster auswählen, ohne den Build-Ausgabeordner dist/ des Workspace, jede benannt mit ihrem Pfad innerhalb des Verzeichnisses, in sortierter Reihenfolge, neben den Dateien, die sein plugins.importer-Eintrag unter with.sources nennt. Ein Importer, der keine Dateimuster deklariert, ein Verzeichnis, das keine von ihnen ausgewählte Datei enthält, eine Verzeichnisdatei und eine with.sources-Datei gleichen Namens sowie ein Link unter den Dateien, die der Import lesen würde, oder auf ein Verzeichnis, der aus dem Verzeichnis hinausführt, kommen jeweils als Fehler mit dem Code der Bedingung zurück, ohne dass etwas geschrieben wird.
Welcher Importer läuft, entscheidet der Workspace, nicht die Anfrage. Das Format wird zu dem Importer aufgelöst, der es unter den Katalog-Plugins des Workspace und den Core-Importern des Compilers anbietet — zu dem, den ein plugins.importer-Eintrag in der Workspace-Konfiguration einbindet, sofern er einen davon einbindet —, daher kann eine Anfrage kein Modul auswählen und auf keines auf der Festplatte verweisen. Ein Format, das kein Importer anbietet, wird unter Nennung des Formats abgelehnt, und ein Format, das zwei Importer anbieten, ohne dass einer davon eingebunden ist — darunter ein Core-Importer und ein Importer anderen Namens, den der Katalog für dasselbe Format enthält —, wird als mehrdeutig abgelehnt, statt willkürlich aufgelöst zu werden.
Ein Core-Importer, den die Maschine noch nicht hat, wird einmal abgerufen, durch den ersten Import, der ihn braucht. Er stammt aus der Standard-Registry des Workspace, gebunden an das Modul, das das Release des Compilers veröffentlicht, und so verifiziert, wie ein Pull ein abgerufenes Plugin verifiziert — seine Signatur gemäß der Vertrauensrichtlinie dieser Registry und die Host-Funktionen, die er verwendet —, und er wird im Inhalts-Cache des Workspace abgelegt, was das Einzige ist, was für ihn geschrieben wird: kein Lockfile und kein Verzeichnis vertrauenswürdiger Plugins. Jeder spätere Import liest ihn von dort und erreicht keine Registry. Ein Modul, das die Verifikation nicht besteht, ist ein Fehler mit dem Code seiner Bedingung, und nichts wird abgelegt; eines, das nicht abgerufen werden kann — der Workspace ist offline, seine Registry ist nicht erreichbar oder die Registry enthält es nicht —, ist ein Fehler unter A plugin’s .wasm is not on this machine (Das Modul eines Plugins befindet sich nicht auf dieser Maschine), der den Importer, seine Version und das nennt, was sein Modul auf die Maschine bringt. Die Anfrage selbst nennt keine Registry, und ein Import, für den jeder Importer und der Katalog, den er liest, bereits auf der Maschine liegen, erreicht überhaupt kein Netzwerk.
Wo der Workspace keinen Katalogordner nennt, liest der Import den Katalog, den seine Standard-Registry veröffentlicht. Ein Workspace, dessen workspace.catalog_dirs, AGGREGA_CATALOG_DIRS und Stammverzeichnis keinen Katalogordner nennen, liest den Katalog der Standardbibliothek als einen einzigen signierten Snapshot, unter catalog/snapshot in seiner Standard-Registry. Ein Snapshot wird einmal abgerufen: Seine Signatur wird gemäß der Vertrauensrichtlinie dieser Registry verifiziert, und er wird im Inhalts-Cache des Workspace abgelegt und dort als Katalogordner gelesen, gebunden an seinen Digest, ohne dass eine Registry erneut danach gefragt wird. Welchen Snapshot eine Anfrage liest: mit upgrade den neuesten; andernfalls den, den die Aufzeichnung in outputDir nennt, über seinen Digest abgerufen, wo die Maschine ihn nicht hat; andernfalls den, den der Workspace zuletzt als neuesten abgerufen hat; andernfalls den neuesten. Die Aufzeichnung, die der Import schreibt, nennt den gelesenen Snapshot über seinen Digest, sodass eine spätere Anfrage in dasselbe outputDir denselben Katalog liest. Im Offline-Betrieb ist eine Anfrage, die einen Snapshot abrufen müsste, ein Fehler unter The workspace is offline and the step needs the network (Der Workspace ist offline und der Schritt benötigt das Netzwerk), der nennt, was auszuführen ist, und upgrade wird abgelehnt, gleich was die Maschine hat, da nur die Registry sagen kann, welcher Snapshot der neueste ist. Eine Registry, die keinen Snapshot veröffentlicht, lässt den Import ohne Katalog, und ein Eintrag warn in diagnostics sagt das. Ein Workspace, der einen Katalogordner nennt, importiert gegen diesen und ruft keinen Snapshot ab, und upgrade ändert dort nichts.
Unter dryRun wird nichts angelegt. written ist leer, files enthält dieselben Dateien, die ein Schreibvorgang erzeugt hätte — mit sync die Dateien, die die Synchronisierung schreiben würde, neben dem drift, den sie abgleichen würde —, und kein Verzeichnis wird erstellt — sodass ein Editor sie dem Autor zum Speichern, Ändern oder Verwerfen vorlegen kann. Alles andere, was ein Schreibvorgang tut, wird getan: Derselbe Importer läuft über dieselbe Quelle und meldet dieselben Diagnosen, daher wird eine Quelle, die ein Schreibvorgang ablehnen würde, auch hier abgelehnt. Ein unter dryRun abgerufener Core-Importer oder Katalog-Snapshot wird wie bei einem Schreibvorgang im Inhalts-Cache abgelegt, weil das Beschaffen dessen, worauf der Import läuft, zu seiner Ausführung gehört und nicht zum Ablegen der Entwürfe.
Ein Pfad, den der Importer zurückgibt, wird innerhalb von outputDir gehalten. Die Pfade der Entwürfe stammen vom Importer statt von Ihnen, daher wird ein Pfad, der aus dem Ausgabeverzeichnis hinausführt, abgelehnt und es wird überhaupt nichts geschrieben — nicht einmal die Entwürfe, deren Pfade in Ordnung waren. Die Ablehnung nennt den betreffenden Pfad, und daran erkennen Sie, dass der Importer zu korrigieren ist und nicht Ihre Anfrage.
Welche Frage jede Entitätsanfrage beantwortet
Vier Anfragen geben Ihnen hier Auskunft über eine Entität, und sie sind nicht austauschbar. Die Wahl zwischen ihnen hängt davon ab, was Sie in der Hand haben, wenn Sie fragen.
Sie haben einen Cursor in der Hand. aggrega/hover und aggrega/resolve nehmen eine Datei und eine Position und ermitteln aus dem, was dort geschrieben steht, welche Entität gemeint ist. Sie decken die Referenzformen ab, die ein Dokument tatsächlich enthält — einen extends-Wert, einen Komponenten- oder Feature-Typ, das implements einer Recipe, die Recipe-Referenzen eines Manifest, die zwei Pfadzeiger eines Release, ein uses-Ziel und den eigenen metadata.name einer Entität. Greifen Sie zu diesen, wenn der Cursor des Benutzers die Koordinate ist: Der Benutzer liest ein Dokument und will wissen, worauf eine Referenz zeigt.
Sie haben einen Namen in der Hand. aggrega/entityDefinition nimmt die Identität direkt. Es muss nichts geöffnet sein, keine Position ist beteiligt, und die Entität muss nirgends erwähnt sein, wo der Client sie finden kann. Greifen Sie dazu, wenn der Benutzer einen Namen eingegeben, einen aus einer Liste ausgewählt oder etwas verfolgt hat, dessen Identität Ihr eigener Client bereits kennt — ein Hover verlangt, dass Sie zuerst eine Stelle finden, an der der Name steht, und diese Arbeit müssen Sie nicht leisten.
Sie haben noch nichts in der Hand. aggrega/catalogIndex zählt auf, was der Workspace enthält, mit den beschreibenden Feldern jeder Entität. Greifen Sie dazu, um eine Auswahlliste zu füllen, und übergeben Sie dann einen ausgewählten Namen an aggrega/entityDefinition.
Sie haben ein Release in der Hand. aggrega/releaseClosure gibt Auskunft über ein Release statt über eine einzelne Entität, und davon handelt der folgende Abschnitt.
Die Definition, die eine Anfrage nach Namen zurückgibt, ist die Entität wie aufgelöst, nicht wie eine einzelne Datei sie deklariert. Eine Component oder ein Feature, das eine Basis erweitert, kommt mit dem Vertrag dieser Basis zurück, der nirgends in dem Dokument erscheint, das ihren Namen deklariert — die Antwort handelt also davon, was die Entität ist, und das Lesen der Datei würde Ihnen nicht dasselbe liefern.
Sie kommt als YAML-Dokument statt als Struktur innerhalb der Antwort, und das ist Absicht: Eine Schema-Säule hat mehrere Formen der Erstellung — ausgeschriebenen Inhalt, eine Referenz auf ein gemeinsam genutztes Dokument oder die Markierung, dass der Inhalt aus einer Basis stammt —, und das Dokument gibt diejenige wieder, bei der die Auflösung angekommen ist, in der eigenen Schlüsselreihenfolge des Autors. Parsen Sie es als Dokument, wenn Sie seine Felder brauchen; zeigen Sie es unverändert, wenn Sie es in einem Panel darstellen.
Die zwei Ablehnungen nach Namen unterscheiden
Ein Name, der sich zu nichts auflöst, wird abgelehnt, statt mit einem leeren Dokument beantwortet zu werden, weil eine leere Antwort einen Tippfehler als Entität ausgeben würde, die nichts über sich zu sagen hat. Es gibt zwei Arten, wie sich ein Name zu nichts auflöst, sie verlangen vom Leser Unterschiedliches, und Sie unterscheiden sie daran, was das data des Fehlers enthält, nicht durch Lesen der Meldung:
- Kein
fileindata. Nichts im Workspace deklariert diesen Namen, und keine Katalogstufe löst ihn auf. Fast immer ist die Anfrage zu korrigieren — ein Tippfehler oder ein Name aus einem Katalog, den dieser Workspace nicht in seinem Suchpfad hat. - Ein
fileindata. Ein Workspace-Dokument deklariert diesen Namen sehr wohl, und der Katalog hat trotzdem nichts dafür aufgelöst. Die Entität ist niedergeschrieben, und etwas hat sie abgelehnt — ein Zustand des Workspace, den ein Mensch behebt. Wo genau ein Dokument, das der Katalog gelesen und abgelehnt hat, diesen Namen deklariert — die übliche Ursache —, beginnt die Meldung mit dieser Ablehnung, einmal angegeben: ihre Kategorie und ihr Kurzcode, das Dokument unter dem Pfad, unter dem es gemeldet wird, und was daran falsch ist, etwa die Zeile und die Einschränkung, die sie verletzt; dann vermerkt sie, dass die Datei beim Laden übersprungen wurde, und führt jede andere Datei auf, die das Laden abgelehnt hat. Andernfalls nennt die Meldung das deklarierende Dokument, führt die Dateien auf, die das Laden abgelehnt hat, und sagt, woher dieser Workspace lokale Entitäten liest und was zu ändern ist, damit das Dokument gelesen wird — die Erläuterung, die sie weglässt, wo ein abgelehntes Dokument den Namen deklariert, weil dieses Dokument bereits dort liegt, wo der Katalog liest.
Beide tragen den Code entity-not-resolvable, verzweigen Sie also anhand des Vorhandenseins von file statt anhand des Codes.
Nach einer Koordinate fragen
Sie haben eine Registry-Referenz in der Hand. Senden Sie sie als name von aggrega/entityDefinition, und die Antwort ist die unter dieser Koordinate veröffentlichte Entität, in derselben Ergebnisform, die ein Name erhält, plus published, gefüllt aus dem, was veröffentlicht wurde, statt aus dem, was ein Katalog aufgelöst hat:
definitionist das Entitätsdokument genau so, wie es veröffentlicht wurde. Eine Koordinate, deren Entität mit den von ihr deklarierten Dateien veröffentlicht wurde, enthält ein Archiv, und das Dokument wird daraus entpackt; eine, deren Entität keine Datei deklariert, enthält ihr Dokument unverändert, und die Entität eines Plugin wird aus seinem Manifest gelesen statt aus der mit ihm veröffentlichten ausführbaren Datei. Es wird keine Vererbung angewendet.authoredLengthist die Länge dieses Dokuments, weil die Definition hier ein verfasstes Dokument ist und nicht die Darstellung eines aufgelösten.fileist leer, weil eine aus einer Registry gelesene Entität auf dieser Maschine kein Dokument hat, das sich nennen ließe.publishScopewird weggelassen: Sie haben die Koordinate bereits in der Hand, und dort ist die Entität veröffentlicht.publishedist das, was gelesen wurde, und es ist in dieser Antwort vorhanden und in keiner nach Namen: diereference;archive, ob ihre Bytes ein Archiv waren, aus dem das Dokument entpackt wurde —false, wo die Koordinate das Dokument selbst enthielt; dermediaType, den das Manifest deklariert; und dermanifestDigestdieses Manifests, den Sie nach@anstelle des Tags senden können, um genau dieselben Bytes erneut zu lesen.
Die Anfrage erreicht die Registry, die die Referenz nennt, mit den Anmeldedaten des Benutzers, unter dem dieser Daemon läuft, und der Netzwerkhaltung dieses Workspace, daher lehnt ein Offline-Workspace sie ab. Die abgerufenen Bytes werden gegen den Digest geprüft, den das eigene Manifest des Artefakts für sie aufzeichnet, und gegen nichts anderes — keine Signatur wird verifiziert und kein Rückzug gemeldet —, und es wird nichts geschrieben. Eine Referenz, die nicht gelesen werden kann, wird mit entity-not-resolvable abgelehnt, und die Meldung beginnt mit dem Kurzcode der Bedingung, die den Grund nennt — dieselben Bedingungen, die aggrega inspect meldet —, und endet damit, was dagegen zu tun ist. Eine Referenz, die kein Repository oder weder ein Tag noch einen Digest nennt, ist eine fehlerhafte Anfrage und wird als ungültige Parameter abgelehnt.
Eine Hülle ist nicht der Graph
aggrega/irGraph und aggrega/releaseClosure werden aus derselben Auflösung desselben Release abgeleitet und beantworten unterschiedliche Fragen. Ein Client, der den Graphen bereits erhält, kann vernünftigerweise annehmen, dass er auch diese hat, und das ist nicht der Fall.
Der Graph sagt, was das Release bereitstellt — seine Knoten, die Grenzen, in denen sie liegen, was mit was verbunden ist, und die Werte und Anhänge, die jeder Knoten trägt. Er ist das Bild.
Die Hülle sagt, was zum Erstellen herangezogen wurde, und in welchen Versionen. Jede Entität, die das Release erreicht, ob sie zu einem Knoten wurde oder nicht; die gemeinsam genutzten Dokumente, auf die diese Entitäten zurückgreifen; und die Plugins, die die Ausgabe formen. Sie ist die Stückliste.
Keines lässt sich aus dem anderen wiederherstellen. Eine Entität kann erreicht werden, ohne je als Knoten zu erscheinen — die Recipe, auf die ein Manifest einen Komponententyp abbildet, wird von jedem Build erreicht und ist in keinem davon ein Knoten —, und ein Knoten trägt nicht die Version, zu der sein Typ aufgelöst wurde. Ein Leser, der fragt: „Warum hat sich diese Version bewegt?“, „Was würde eine Änderung dieses gemeinsam genutzten Dokuments betreffen?“ oder „Wovon hängt dieses Release tatsächlich ab?“, fragt also nach der Hülle, und ein Leser, der fragt: „Was stellt dieses Release bereit?“, fragt nach dem Graphen.
Was die Hüllen-Anfrage nicht tut. Sie rendert nichts und veröffentlicht nichts von dem, was sie findet. Insbesondere löst sie keine Drift-Warnung und keinen Rendering-Hinweis aus: Diese gehören zu der Anfrage, die nach ihnen gefragt hat, und das Veröffentlichen ersetzt eine ganze Diagnoseschicht, sodass eine Auflistung, die veröffentlichen würde, löschen würde, was die Graph-Anfrage dem Benutzer bereits vorgelegt hatte. Fragen Sie nach dem Graphen, wenn Sie das Drift-Urteil wollen. Das Einzige, was sie doch veröffentlicht, ist kein eigener Befund: Eine Anfrage, die feststellt, dass das Lockfile verschwunden ist, zieht die darauf beruhende Drift-Warnung zurück, welche Anfrage es auch sei — siehe Lockfile-Bewusstsein.
Sie erfordert ein Lockfile, wie der Graph. Die Versionen, die die Auflistung meldet, sind die, zu denen dieses Release aufgelöst wurde, und ein Workspace, den niemand vorbereitet hat, hat sie noch nicht aufgelöst. Eine ohne Lockfile erzeugte Auflistung würde melden, was der Katalog heute zufällig enthält, und das ist eine andere Frage als die, wovon dieses Release abhängt. Die Ablehnung nennt das Lockfile und das Release, sodass ein Client direkt aggrega pull --release <release> anbieten kann.
kind ist in einem Hülleneintrag nur vorhanden, wo es bekannt ist. Eine Referenz wird von einer Position in einem Dokument gesammelt, und manche Positionen sagen, auf welche Art von Entität sie zeigen, andere nicht. Das Feld wird gemeldet, wo die Referenzstelle eine Art aufgezeichnet hat, und weggelassen, wo nicht, statt aus der Form des Namens geraten zu werden. Es wird als das Wort gemeldet, das ein Autor an den Kopf eines Dokuments schreibt, und das ist dasselbe Wort, das jede Schnittstelle, die eine Hülle meldet, für denselben Eintrag verwendet.
Dasselbe Wort fragt andernorts nach demselben Dokument. aggrega inspect <release> --closure beantwortet diese Frage auf der Befehlszeile, und der Release-Modus des describe-Werkzeugs beantwortet sie über das Werkzeugprotokoll des Assistenten. Alle drei führen eine einzige Auflösung über das Release aus, sodass sie nicht zu unterschiedlichen Ergebnissen darüber kommen können, wovon ein Release abhängt. Siehe aggrega inspect, „Die Abhängigkeitshülle“.
Cache-Modell
Operationen sind cache-gesteuert: Rufen Sie aggrega/validate für eine Datei auf, bevor Sie hover / completion / resolve / diagnostics darauf anwenden. Dieser initialisierende Aufruf braucht kein Release — eine Validierung, die keines nennt, parst den Puffer trotzdem und füllt den Cache —, daher funktionieren diese Operationen in einem Workspace, der kein Release zu nennen hat. Der Parse-Cache wird bei jedem Lesen mit dem Änderungszeitpunkt jeder Datei auf der Festplatte abgeglichen, sodass externe Änderungen (ein Speichern im Editor, ein git checkout) automatisch erkannt werden — das aggrega/invalidate des Editors ist eine Optimierung, keine Voraussetzung für Korrektheit.
Der Cache gehört dem Workspace, der ihn initialisiert hat. Eine unter einem Workspace validierte Datei wird für diesen Workspace zwischengespeichert, daher wird derselbe Pfad, wenn unter einem anderen danach gefragt wird, als noch nicht validiert gemeldet, statt aus dem Eintrag des ersten beantwortet zu werden. Das verhindert, dass eine Frage zu einem zweiten Workspace entweder falsch beantwortet wird oder den ersten seinen warmen Zustand kostet — und aggrega/invalidate leert ebenso nur den Workspace, den es nennt.
Diagnosen anfordern, während eine Validierung läuft
Eine Validierung initialisiert zwei Dinge zu einer Datei — den Parse, den sie an die anderen Operationen übergibt, und die Befunde, die sie meldet — und sie initialisiert sie einen Moment auseinander. aggrega/diagnostics ist die einzige Anfrage, die beides liest: Sie braucht den Parse, um zu wissen, dass die Datei eine ist, zu der sie antworten kann, und sie antwortet aus den Befunden. Eine Anfrage, die zwischen diesen beiden Momenten eintrifft, würde also entscheiden, dass sie antworten kann, während es noch nichts gibt, womit sie antworten könnte.
Sie wartet stattdessen. Senden Sie aggrega/diagnostics für eine Datei, die gerade validiert wird, und die Antwort kommt, wenn diese Validierung abgeschlossen ist, mit dem, was sie gefunden hat. Es gibt unabhängig vom Zeitpunkt eine einzige korrekte Antwort für die Datei, und das ist die Antwort, die Sie erhalten — es ist nie eine leere Liste für eine Datei, deren Validierung gleich Fehler melden wird, was die eine falsche Antwort ist, von der sich ein Client nicht erholen kann, weil nichts Sie veranlasst, erneut nach einer Datei zu fragen, die Ihnen als sauber gemeldet wurde. Die anderen positionsbasierten Operationen — hover, completion, resolve, findReferences, findImplementations — lesen den Parse und antworten aus dem Parse, daher haben sie nichts, worauf sie warten müssten, und warten nie.
Zwei Dinge beenden das Warten vorzeitig, und beide haben Sie bereits. $/cancelRequest für die ID dieser Anfrage beendet es, und ein kooperatives aggrega/shutdown beendet es. Keines von beiden braucht etwas Zusätzliches in der Anfrage.
Und das Warten ist begrenzt. Ist die Validierung nicht innerhalb des Zeitbudgets abgeschlossen, das der Daemon ihr gewährt, wird die Anfrage mit dem Code validation-in-flight abgelehnt, statt leer beantwortet zu werden — siehe Fehlercodes. Diese Ablehnung bedeutet, dass die Arbeit, auf die Sie warten, tatsächlich im Gange ist, das Richtige ist also, in Kürze erneut zu fragen; sie ist kein Signal, eine weitere Validierung zu senden, die Arbeit hinzufügen und nichts beantworten würde.
Ein Daemon, der Anfragen nacheinander ausführt, beantwortet sie in der Reihenfolge ihres Eintreffens, sodass sich nichts überschneidet und nie gewartet wird. Ein Daemon, der sie nebenläufig ausführt, beantwortet dieselben Fragen auf dieselbe Weise, und das Warten ist es, was das sicherstellt: Die Antwort, die Sie erhalten, ist die Antwort, die eine serielle Reihenfolge Ihnen gegeben hätte.
Größen in einer Antwort
Eine Antwort, die eine Bytemenge meldet, meldet sie zweimal: als Zahl und als dieselbe Menge in ausgeschriebener Form. Das ausgeschriebene Feld ist der Name des numerischen Feldes mit angehängtem Text — size und sizeText, totalSize und totalSizeText, reclaimedBytes und reclaimedBytesText und so weiter in jeder Antwort, die eine Größe enthält.
Zeigen Sie die ausgeschriebene Form an und rechnen Sie mit der Zahl. Der Sinn, beides zu senden, ist, dass ein Client eine Größe nie selbst formulieren muss: Der Daemon schreibt sie mit demselben Formatierer, den die Befehlszeile verwendet, sodass aggrega cache status und aggrega/cacheStatus einen bestimmten Cache identisch anzeigen, bis hin zur Rundung. Ein Client, der seinen eigenen Text zusammensetzt, würde davon abweichen, sobald er sich das erste Mal bei einer Grenze anders entscheidet.
Die ausgeschriebene Form verwendet binäre Einheiten — 512 B, 1.0 KiB, 5.0 MiB, 3.0 GiB —, also dasselbe Vokabular, das aggrega/cacheEvict in maxSize akzeptiert, sodass eine aus einer Antwort gelesene Größe in der nächsten Anfrage zurückgesendet werden kann, ohne umgeschrieben zu werden. Oberhalb von Bytes trägt der Text eine Nachkommastelle, sodass er die Menge so nennt, wie ein Leser sie sehen will, statt auf das Byte genau; wenn Sie die exakte Anzahl brauchen, ist das numerische Feld dafür da.
Wo die Zahl optional ist, ist der Text mit ihr optional, und die beiden sind nie nur halb vorhanden: Die Plugin-Größe in einer Publish-Antwort enthält pluginSize und pluginSizeText zusammen oder keines von beiden.
Jede Anfrage nennt den Workspace, um den es geht
Senden Sie workspaceRoot mit jeder Anfrage: den absoluten Pfad des Workspace-Stamms, auf den diese Anfrage wirkt. Der Daemon hat keinen eigenen Workspace und merkt sich zwischen Anfragen keinen, daher ist das, worüber eine Anfrage Auskunft erhält, der Workspace, den sie genannt hat, und nichts anderes. Zwei Anfragen, die zwei Workspaces nennen, erhalten zwei Antworten, und keine kann die Entitäten, Releases, zwischengespeicherten Parses oder Diagnosen der anderen sehen.
Eine Anfrage, die keinen nennt, wird mit dem standardmäßigen invalid-params-Fehler abgelehnt, der den Parameter nennt, und ebenso ein leerer Wert, der keinen Workspace angibt und wie ein fehlender beantwortet wird. Zwei weitere Formen werden aus demselben Grund abgelehnt, jede in der Meldung genannt: ein relativer Pfad, weil ein Workspace-Stamm nichts hat, wozu er relativ sein könnte; und ein Pfad, der kein existierendes Verzeichnis ist, weil ein Workspace ein Baum ist.
Drei Anfragen brauchen kein workspaceRoot, und jede, weil ihr Gegenstand kein Workspace ist. aggrega/getSchema und aggrega/scaffoldEntity antworten aus den Schemas, die in die laufende Binärdatei kompiliert sind, sodass ein Workspace zu keiner von beiden etwas beiträgt — und das erlaubt beiden, in einem Verzeichnis zu antworten, das niemand vorbereitet hat. aggrega/initialize ist die dritte, und dort deklarieren Sie einen Workspace, statt auf einen zu wirken. Die andere Form von aggrega/scaffoldEntity, die die ausführbaren Beispiele der Dokumentation schreibt oder auflistet, wirkt dagegen auf einen Workspace, und eine Anfrage dafür nennt einen wie jede andere.
Der zwischengespeicherte Zustand jedes Workspace wird getrennt gehalten, und einen zweiten zu nennen kostet den ersten nichts. Der Katalogindex, der Parse-Cache und die Diagnosen eines Workspace gehören diesem Workspace, daher verdrängt eine Frage zu einem anderen Ort nicht, was ein Editor für den Ordner angesammelt hat, den jemand geöffnet hat. Zwei Schreibweisen eines Stamms sind ein Workspace, sodass ein Pfad mit einem inneren . oder einem doppelten Trennzeichen denselben warmen Zustand erreicht wie seine einfache Form.
Den Workspace deklarieren, für den Diagnosen gepusht werden sollen
Diagnosen gelangen auf zwei Wegen zu Ihnen: Sie fordern sie an, oder der Daemon pusht sie. Der Daemon pusht nur für den Workspace, den Sie beim Handshake deklariert haben. Jede andere Anfrage antwortet mit ihren Befunden in ihrer eigenen Antwort und pusht nichts.
Deklarieren Sie ihn, indem Sie workspaceRoot mit aggrega/initialize senden. Das ist alles, was die Deklaration bewirkt — sie verankert nichts, und keine spätere Anfrage wird in Bezug auf sie beantwortet.
Der Grund für die Einschränkung liegt darin, wofür eine gepushte Diagnose da ist. Pushen hält die Problemliste eines Editors aktuell, während jemand tippt, und es ist genau das Falsche für eine Antwort, die niemand sehen wollte: Ohne die Regel würde eine Frage zu einem zweiten Workspace — etwa von einem anderen Werkzeug, das sich den Daemon teilt — die Problemliste eines Lesers mit Befunden zu Dateien füllen, die er nie geöffnet hat. Die Einschränkung des Pushs hält die Frage eines Aufrufers aus der Problemliste eines anderen Aufrufers heraus.
Das Feld ist optional, und die drei Dinge, die Sie damit meinen können, sind unterscheidbar:
| was Sie senden | wohin Pushes gehen | was der Handshake meldet |
|---|---|---|
| nichts | der Workspace, über dem der Prozess gestartet wurde | dieser Workspace |
| ein Workspace-Stamm | dieser Workspace | dieser Workspace |
| die leere Zeichenkette | nirgendwohin — es wird nie eine Diagnose gepusht | ein leerer Stamm |
Nichts zu senden belässt die Pushes bei dem Workspace, über dem der Prozess gestartet wurde, sodass ein Client, der nichts deklariert, die Diagnosen für diesen Workspace erhält. Die leere Zeichenkette zu senden ist die ehrliche Deklaration für einen Aufrufer, der kein Editor ist und keine Problemliste synchron zu halten hat: Jeder Befund erreicht ihn trotzdem, in der Antwort auf die Anfrage, die ihn hervorgebracht hat.
Ein deklarierter Workspace wird genau so aufgelöst wie einer, den eine Anfrage nennt, daher wird eine Deklaration, die einen relativen Pfad oder einen Pfad nennt, der kein Verzeichnis ist, beim Handshake abgelehnt, statt die Pushes auf einen unerwarteten Ort gerichtet zu lassen.
Workspace-Root und aktives Release
Der Daemon löst jeden Workspace, den eine Anfrage nennt, auf dieselbe Weise auf, wie jeder aggrega-Befehl einen auflöst, und Konfiguration beschreibt, was einen Root verankert und in welcher Reihenfolge. Zwei Folgen sind für einen Client wichtig. Eine .aggrega-config.yaml ohne einen workspace:-Block verankert nicht: Sie trägt weiterhin ihre Einstellungen bei, aber eine bloße Einstellungsdatei kann nicht jedes übergeordnete Verzeichnis zu einem Workspace-Root machen. Und wenn nichts verankert, wird das Arbeitsverzeichnis verwendet — der Daemon startet, und Operationen lösen einfach nichts auf, statt die Ausführung zu verweigern.
Auch der Prozess wird über einem Workspace gestartet, aus --workspace-root oder indem von seinem Arbeitsverzeichnis aus nach oben gegangen wird, und diese Auflösung bewirkt zwei Dinge und keine anderen: Sie bemisst den Worker-Pool, der eine Eigenschaft des Prozesses und nicht einer Anfrage ist, und sie ist die Standarddeklaration für gepushte Diagnosen. Keine Anfrage wird anhand von ihr beantwortet.
Die Konfiguration ist ebenso dieselbe Kaskade, die jeder Befehl liest, und Konfiguration ist der Ort, an dem sie beschrieben wird. Der Daemon fügt nur hinzu, dass die Lesung jedes Workspaces einmal erfolgt, wenn dieser Workspace zum ersten Mal genannt wird, und für jede spätere Anfrage zu ihm wiederverwendet wird. Eine Konfigurationsdatei, die diese Kaskade lesen würde und die ein Link ist, der aus dem Workspace herausführt — die eigene .aggrega-config.yaml des Workspaces oder das CI-eigene Overlay daneben —, wird nicht gelesen, hier wie an einem Terminal, und nichts anderes, was diese Datei konfiguriert hätte, wird an ihrer Stelle gelesen. Was sich von einem Terminal unterscheidet, ist, was trotzdem antwortet. Der über einem solchen Workspace gestartete Daemon startet und meldet dies einmal auf seinem Fehlerstrom; eine Anfrage, die einen solchen nennt, wird in jedem Fall wie folgt beantwortet. aggrega/releaseCandidates und aggrega/catalogIndex — die beiden Anfragen, die auflisten, was ein Workspace enthält — beantworten sie, gelesen ohne jede Konfiguration: Die eigenen Dokumente des Workspaces werden aufgelistet, kein Katalogverzeichnis wird gelesen, und die zurückgehaltene Datei wird in unreadLinkedFiles genannt, ob die Suche auf sie gestoßen ist oder nicht. An diesem Namen erkennt ein Client, dass die Konfiguration des Workspaces aus ihm herausführt. Jede andere Anfrage, die den Workspace nennt — ein Build, ein Graph, eine Validierung, das Standard-Release, die effektive Konfiguration, ein Schreibvorgang und aggrega/catalogIndex im Sinne eines Release —, wird von dieser Konfiguration entschieden und daher mit dem invalid-params-Fehler abgelehnt, der E0321 trägt — read-leads-out-of-workspace im data des Fehlers — sowie den Satz, der den Link nennt und wohin er führt. Auch der Handshake antwortet für einen solchen Workspace und meldet defaults als seine configSource, da keine Konfigurationsdatei etwas beigetragen hat, womit die Auflistungen antworten. Entfernen Sie den Link oder lassen Sie ihn auf eine Datei innerhalb des Workspaces führen, und die nächste Anfrage liest die Konfiguration. Unter den Dateien des Projekts liegt die globale Ebene: die Datei, die --config auf der Befehlszeile nennt, mit der der Daemon gestartet wurde, für jeden Workspace, den er bedient; andernfalls die Datei, die die Umgebungsvariable AGGREGA_CONFIG nennt, wenn sie gesetzt ist; und andernfalls der Standardort — unter Windows aggrega\config.yaml in dem Verzeichnis, das die Umgebungsvariable APPDATA nennt, und anderswo aggrega/config.yaml in dem Verzeichnis, das XDG_CONFIG_HOME nennt, mit ~/.config/aggrega/config.yaml als Rückfall —, geladen, wenn vorhanden. Darunter liegen die eingebauten Standardwerte.
Operationen, die auf ein Release wirken, erhalten eines als Parameter; der Daemon wählt selbst keines aus. Ein Workspace deklariert weiterhin, auf welches Release er zeigt, und eine vierstufige Kaskade liest diese Deklaration: das Konfigurationsfeld build.authoring_release, dann eine Markerdatei .aggrega/active-release, dann eine Heuristik für ein einzelnes Release im Workspace, dann ein Rückfall nur auf das Aggregate. Ein Marker, den Sie schreiben, hat daher Vorrang vor der Heuristik, und ein Marker, der ein Release nennt, das nicht geladen werden kann, fällt auf die Heuristik zurück statt auf den Rückfall. Ein Marker, der ein Release außerhalb des Workspaces nennt — über einen absoluten Pfad, über einen Pfad, der aus dem Root heraussteigt, oder über einen Link, der aus ihm herausführt —, wird nicht gelesen, es sei denn, Ihre Workspace-Konfiguration nennt dieses Release als build.authoring_release oder als Schlüssel von workspace.releases: Die Konfiguration ist der Weg, ein außerhalb des Workspaces gehaltenes Release zu erreichen, der Marker ist es nicht. Die Kaskade geht dann genau so weiter wie bei einem Marker, den sie nicht laden kann, und wo sie bei nichts landet, sagt trace in der Zeile des Markers und reason in seinem Satz über den Marker, warum.
aggrega/activeRelease meldet, was diese Kaskade wählt, und ist eher ein Vorschlag für einen Client als eine Einstellung, nach der der Daemon handelt. Fragen Sie den Daemon, statt die Eingaben der Kaskade selbst zu lesen: Das Konfigurationsfeld und die Markerdatei sind zwei von vier Eingaben, sodass jede von ihnen, die Sie lesen, die Wahl des Workspaces nur dann nennt, wenn sie zufällig die Eingabe ist, die gewonnen hat. Ein Marker, der ein Release nennt, das nicht geladen werden kann, ist der deutlichste Fall — die Kaskade wählt ein ganz anderes Release, und wer den Marker liest, würde das melden, das fehlgeschlagen ist.
Die Kaskade läuft, wenn Sie fragen, und nicht vorher, was zwei Folgen hat, auf die man sich verlassen kann. Der Handshake bleibt schnell, unabhängig von der Größe des Baums, weil er nicht auf das Durchlaufen des Workspaces wartet. Und die Antwort folgt dem Workspace: Schreiben Sie einen Marker — mit aggrega/setActiveRelease, das selbst mit der neuen Wahl antwortet —, bearbeiten Sie die Konfiguration, fügen Sie eine Release-Datei hinzu oder entfernen Sie eine, fragen Sie dann erneut, und Sie erhalten die neue Antwort vom selben Daemon. Das Release zu wechseln, an dem Sie arbeiten, erfordert nie einen Neustart des Daemons — ein Client sendet bei seiner nächsten Anfrage ein anderes release.
Die Operationen, die den gesamten Workspace statt eines einzelnen Puffers durchsuchen — completion, hover, resolve, findReferences und findImplementations —, zählen das YAML unter dem Workspace-Root auf, und diese Aufzählung beachtet .gitignore. Jede .gitignore vom Workspace-Root bis zum eigenen Verzeichnis der Datei trägt bei, wobei die nächstgelegene gewinnt, sodass eine YAML-Datei, die Ihr Repository ignoriert, nicht als Vervollständigungskandidat angeboten und nicht als Definition oder Referenz gemeldet wird. Eine .gitignore, die ein Link ist, der aus dem Workspace herausführt, wird nicht gelesen, sodass eine Datei an anderer Stelle auf dem Rechner nie darüber entscheidet, welche Dokumente des Workspaces durchsucht werden. Vendorte Bäume und generierte Ausgaben bleiben daher aus dateiübergreifenden Ergebnissen heraus, ohne dass eine separate Ausschlusseinstellung gepflegt werden muss — und ein Dokument, das Sie gefunden haben möchten, aber ignoriert haben, erscheint nicht, was der eine Fall ist, den es zu prüfen lohnt, wenn eine Referenz zu fehlen scheint. Die Components und Features, die completion zusätzlich aus Ihren konfigurierten catalog_dirs anbietet, sind eine andere Lesung: Sie stammen aus diesen Verzeichnissen, wie sie konfiguriert sind — denselben Verzeichnissen, die ein Build eines Release liest, wenn die Konfiguration diesem Release keine eigenen gibt, oder, bei einer Anfrage, die ein Release nennt, denen dieses Release —, sodass die Entitäten eines Katalogverzeichnisses angeboten werden, ob eine .gitignore es abdeckt oder nicht — außer einer Entität hinter einem Link, der aus dem Verzeichnis herausführt, innerhalb dessen die Lesevorgänge eines Katalogverzeichnisses bleiben müssen; sie wird weder gelesen noch angeboten.
Eine Anfrage, die ein Release nennt, liest die Katalogverzeichnisse dieses Release, also diejenigen, die ein Build davon an einem Terminal liest: seine eigenen, wo die Workspace-Konfiguration ihm unter workspace.releases welche gibt, und andernfalls die catalog_dirs des Workspaces. Das betrifft aggrega/build, aggrega/buildPreview, aggrega/irGraph, aggrega/releaseClosure, aggrega/resolveDependencies, aggrega/validate und aggrega/lint, wenn sie ein Release nennen, aggrega/attachCandidates und aggrega/attachmentContainer, wenn sie an einen Knoten des Graphen eines Release gerichtet sind, und aggrega/connectionAtPosition sowie die Anfragen, die der nächste Abschnitt aufführt, wenn sie eines nennen. So beantwortet eine Sitzung jedes Release in einem Workspace, der pro Release eine Katalogvariante hält, jedes aus seiner eigenen Variante, ohne dass mehr als der Pfad des Release gesendet wird. Eine Anfrage, die kein einzelnes Release betrifft — aggrega/catalogIndex, aggrega/entityDefinition, completion, hover und resolve ohne Nennung eines Release sowie aggrega/attachCandidates, gerichtet an eine Entität oder eine Label-Menge —, liest die catalog_dirs des Workspaces. aggrega/lint, das weder eine Entität noch ein Release nennt, ist die Ausnahme in einem Workspace, der Releases unter workspace.releases nennt: Dort prüft es den gesamten Katalog einmal für jedes Release, jeder Durchlauf über die Verzeichnisse dieses Release, wie Konventionen veröffentlichen, auf Anfrage und bei jeder Bearbeitung beschreibt. Siehe Einem Release eigene Katalogverzeichnisse geben.
Antworten im Sinne eines Release
aggrega/catalogIndex, aggrega/entityDefinition und die fünf Anfragen, die von einem Cursor ausgehen — aggrega/hover, aggrega/resolve, aggrega/completion, aggrega/findReferences und aggrega/findImplementations —, betreffen kein einzelnes Release, und jede nimmt ein optionales release an, das sie ein Release betreffen lässt. Es ist ein Pfad relativ zum Workspace-Root und unterliegt demselben Vertrag wie bei den anderen Anfragen, die ein Release annehmen; ein Wert, der keine Release-Datei nennt oder ein Verzeichnis nennt, wird abgelehnt, statt im Sinne des Workspaces beantwortet zu werden, während er sich wie die Antwort des Release liest.
Was ein Release erreicht, für jede Anfrage hier: die Workspace-Dokumente unter den Katalogverzeichnissen, die sein Stack liest, und jedes Workspace-Dokument, das unter gar keinem Katalogverzeichnis liegt — ein Release, sein Aggregate und sein Manifest, neben den Katalogen geschrieben. Ein Workspace-Dokument unter einem Katalogverzeichnis, das nur andere Releases lesen, gehört nicht zu seiner Antwort: nicht aufgelistet, nicht aufgelöst, nicht angeboten. Das verhindert, dass Varianten einer Entität, die für verschiedene Releases nebeneinander gehalten werden, vermengt werden.
- Die Auflistung. Die Nennung eines Release listet die Entitäten auf, die dieses Release sieht. Die aufgelisteten Features sind diejenigen, die die Katalogverzeichnisse dieses Release deklarieren, und ein Workspace-Dokument unter einem Katalogverzeichnis, das nur andere Releases lesen, wird ausgelassen — sodass ein Workspace, der pro Release eine Variante einer Entität hält, die eine Variante auflistet, mit der dieses Release gebaut wird, statt alle Varianten nebeneinander. Ein Dokument, das unter gar keinem Katalogverzeichnis liegt, etwa ein Release, sein Aggregate und sein Manifest, neben den Katalogen geschrieben, gehört zur Auflistung jedes Release.
- Eine Suche nach Name. Wird ein Release genannt, wird der Name über die Katalogverzeichnisse dieses Release aufgelöst, sodass ein Name, den mehrere Varianten deklarieren, zu der Variante aufgelöst wird, mit der dieses Release gebaut wird. Ein Name, den seine Verzeichnisse nicht auflösen, wird mit einer Erklärung abgelehnt, die den Eintrag dieses Release unter
workspace.releasesnennt, da dieser Eintrag das ist, was die Suche gelesen hat. Eine Registry-Referenz nimmt kein Release an und wird abgelehnt, wenn sie eines erhält: Sie wird aus der Registry gelesen, die sie veröffentlicht, welches Release auch immer genannt wird. - Hover und Gehe zu Definition. Wird ein Release genannt, wird die Referenz am Cursor zuerst über die Katalogverzeichnisse dieses Release aufgelöst, in der Reihenfolge, die die Workspace-Konfiguration ihnen gibt — dieselbe Auflösung, die eine Suche nach Name im Sinne dieses Release durchführt —, sodass die angezeigte Entität und das geöffnete Dokument die Variante ist, zu der diese Verzeichnisse sie auflösen, selbst wo ein Workspace-Dokument an anderer Stelle denselben Namen deklariert. Nur wo kein Dokument unter diesen Verzeichnissen für sie antwortet, werden die Workspace-Dokumente durchsucht, die dieses Release erreicht. Wird keines genannt, ist die Reihenfolge umgekehrt: Die Workspace-Dokumente werden zuerst durchsucht, sodass eine Referenz, die ein Workspace-Dokument beantwortet, diese Antwort behält, und die eigenen
catalog_dirsdes Workspaces werden nur herangezogen, wo kein Dokument den Namen deklariert — was eine Entität findet, die nur ein konfiguriertes Katalogverzeichnis enthält, einschließlich einer außerhalb des Workspace-Baums. Wo der Editor eine ungespeicherte Kopie des Dokuments hält, zu dem die Verzeichnisse eines Release auflösen, und diese Kopie den Namen noch deklariert, wird die Antwort aus der Kopie gelesen, sodass eine Position auf der Zeile landet, die der Editor anzeigt. - Vervollständigung. Wird ein Release genannt, sind die angebotenen Namen diejenigen, die die Workspace-Dokumente deklarieren, die dieses Release erreicht, zusammen mit den Components und Features, die die Katalogverzeichnisse dieses Release deklarieren.
- Referenzen und Implementierungen. Wird ein Release genannt, wird eine Stelle in einem Workspace-Dokument, das dieses Release nicht erreicht, nicht gemeldet, sodass eine für ein anderes Release gehaltene Variante nie als Referenz oder Implementierung dieses Release aufgeführt wird.
- Was sich an einen Graphknoten anhängen darf.
aggrega/attachCandidates, gerichtet an einen Knoten des Graphen eines Release, ist immer im Sinne dieses Release — siehe Was Ihnen eine Antwort zu Anhängekandidaten sagt.
Wird keines genannt, wird über die eigenen Katalogverzeichnisse des Workspaces geantwortet, wie der obige Absatz beschreibt.
Eine Registry erreichen, und schreiben
Die meisten Anfragen hier antworten aus dem Workspace und aus dem, was bereits zwischengespeichert ist, und schreiben nichts. Einige benannte tun mehr, und sie teilen sich entlang zweier unabhängiger Achsen auf: was eine Anfrage erreicht und wie weit das reicht, was sie ändert.
Die Anfragen, die sich an eine Registry wenden, teilen sich in die, die lesen, und die, die veröffentlichen. aggrega/resolveDependencies holt, was ein Release braucht, und aggrega/build kommt hinzu, wenn — und nur wenn — sein Feld autoPull es auffordert, zuerst die Abhängigkeiten aufzulösen; in diesem Fall erreicht es eine Registry und schreibt das Lockfile, bevor es rendert; aggrega/registryUpdate durchläuft jede konfigurierte Registry, um den lokalen Suchindex neu aufzubauen; aggrega/pluginAdd durchsucht die konfigurierte Registry nach dem Plugin, das eine Anfrage nennt, und liest seine veröffentlichten Versionen, um eine davon festzulegen; aggrega/registryAdd fragt die Registry, die es registriert, nach der Vertrauensrichtlinie, die diese Registry ankündigt, es sei denn, die Anfrage lehnt den Abruf ab oder liefert eine eigene Richtlinie, und aggrega/configInit fragt die Registry, die es einrichtet, nach derselben; aggrega/explainError beschafft das Dokumentationspaket, aus dem es die ausführliche Erläuterung einer Bedingung liest, einmalig, wo der Cache, den alle Projekte auf dem Rechner teilen, keine Kopie hält, die die eigene Signaturprüfung des Workspaces zulässt — siehe aggrega explain; aggrega/scaffoldEntity, mit example oder list gesendet, beschafft dasselbe Paket unter denselben Bedingungen, und ein Schreibvorgang schreibt das Beispiel dann in ein neues Verzeichnis des Workspaces; aggrega/import holt einen Core-Importer aus der Standard-Registry des Workspaces, einmalig, wo der Rechner ihn noch nicht hat, und, in einem Workspace, der keinen Katalogordner nennt, den veröffentlichten Katalog-Snapshot, den es liest — siehe Was Ihnen eine Import-Antwort sagt; und aggrega/entityDefinition liest die Entität, die eine Registry-Referenz nennt, wenn eine als sein name gesendet wird, und schreibt nichts. aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts und aggrega/deprecateArtifact schreiben in eine — Bytes, eine Signatur oder eine Rückzugsmarkierung. Eine Anfrage erreicht eine Registry nur, wenn sie dafür gesendet wurde: Eine Auflistung meldet, was die Konfiguration festlegt, eine Suche liest einen Offline-Schnappschuss, und eine mit dryRun angeforderte Veröffentlichung berechnet, was sie senden würde, und kontaktiert niemanden.
Die Regel betrifft, wann eine Operation läuft, nicht, welche Oberfläche sie ausführt. Eine Operation, die abruft oder schreibt, läuft, weil eine Anfrage sie genannt hat, und nie als Nebeneffekt davon, ein Dokument zu validieren, einen Graphen zu untersuchen oder die Entitäten eines Workspaces aufzulisten. Ein Editor, der bei jedem Tastendruck validiert, erreicht also kein Netzwerk und schreibt kein Lockfile neu, während eine vom Benutzer angeklickte Aktion „Abhängigkeiten auflösen“ genau das tut, was aggrega pull tut — dieselbe Auflösung hinter beiden Oberflächen, die ein byteidentisches Lockfile schreibt und denselben Artefakt-Cache füllt.
Es wird nach nichts gefragt. Niemand beobachtet diesen Strom, daher wird die Identität aus einer übergebenen oder in der Umgebung vorhandenen Credential-Quelle aufgelöst und nie durch Nachfragen. Wo der Terminalbefehl einer Person eine Frage gestellt hätte — eine Registry, die Zugangsdaten braucht, eine Fähigkeit, die mehr als ein Provider-Plugin bedient, der Text, den ein Rückzug tragen soll —, schlägt die Anfrage mit einer Meldung fehl, die nennt, was zu liefern ist, statt auf eine Antwort zu warten, die nie kommen wird. Eine Ablehnung lässt den Workspace genau so, wie er war: Es wird kein Lockfile geschrieben und kein unvollständiger Datensatz hinterlassen, und eine Veröffentlichung, die kein Credential auflösen konnte, lehnt ab, bevor irgendwelche Bytes die Registry erreichen.
Manche Änderungen reichen über diesen Workspace hinaus, und die Antwort sagt, welche
Eine Anfrage nennt einen Workspace, daher liest sich eine Antwort, die nichts über ihre eigene Reichweite sagt, als bezöge sie sich auf diesen Workspace. Für mehrere dieser Anfragen wäre diese Lesart falsch, daher trägt jede ihren Geltungsbereich, und ein Client sollte ihn anzeigen, bevor er auf das Ergebnis hin handelt.
Veröffentlichen, Signieren und Zurückziehen reichen ganz über den Rechner hinaus, was die größte Reichweite von allem hier ist. Die anderen Schreibvorgänge unten ändern, was dieser Rechner auflöst; diese ändern, was jeder tut, der aus dieser Registry auflöst. Veröffentlichte Bytes sind das, was jeder Konsument dieser Registry erhält, und das erneute Veröffentlichen anderer Inhalte über einen Tag wird abgelehnt statt angeboten, daher nimmt keine Anfrage hier eine Veröffentlichung zurück — die Antwort ist, eine neue Version zu veröffentlichen. Eine Signatur und eine Rückzugsmarkierung werden als Geschwister des Artefakts angehängt, statt es zu ersetzen, sodass die Bytes selbst unberührt bleiben; aber wer das Artefakt danach abruft, ruft sie ebenfalls ab, und keines von beiden kann von jemandem zurückgeholt werden, der es bereits hat. Ein Rückzug ist von den dreien am leichtesten falsch zu verstehen: Die Version bleibt abrufbar, während ein Widerruf, dem ein Workspace vertraut, sie aus dem herausnimmt, was eine Auflösung dort wählen wird.
Das Signieren verwendet Zugangsdaten, und woher sie kommen, sollten Sie wissen, bevor Sie einen Client anbinden. Schlüsselloses Signieren löst ein Identitätstoken der Reihe nach auf: aus identityToken in der Anfrage, dann aus AGGREGA_IDENTITY_TOKEN in der Umgebung des Daemons, dann aus dem in der Umgebung vorhandenen OIDC-Endpunkt von GitHub Actions, wo einer erreichbar ist, dann aus SIGSTORE_ID_TOKEN. Wenn keine dieser Quellen ein Token liefert, lehnt die Operation ab und nennt, was zu senden ist; sie öffnet nie einen Browser, weil niemand da ist, der hinsieht. Signieren mit Schlüssel ist die Offline-Alternative, und eine Anfrage nennt keinen Schlüsselpfad: Was eine Anfrage liest, befindet sich innerhalb des Workspaces, den sie genannt hat, und ein privater Schlüssel wird nie innerhalb eines Workspaces gehalten, daher kommt der Schlüssel stattdessen aus dem signing:-Block der eigenen Konfiguration dieses Workspaces. Siehe aggrega sign für die beiden Signiermodi und was jeder kontaktiert.
Jede der vier Antworten trägt reach mit registries — jedem Registry-Host, den der Aufruf angesprochen hat, jeder einmal genannt, in der Reihenfolge, in der der Aufruf ihn zuerst angesprochen hat, sodass ein Signier-Batch oder eine Batch-Datei, deren Referenzen sich über mehrere Registries erstrecken, jede davon nennt — und beyondThisMachine, das aus dem abgeleitet wird, was der Aufruf tatsächlich angehängt hat, statt aus dem, was er angefordert hat: wahr genau dann, wenn er Inhalte hochgeladen oder eine Signatur, ein Veröffentlichungsdatum oder eine Veraltungsmarkierung angehängt hat, und falsch für einen Probelauf und für einen Aufruf, der alles, was er angehängt hätte, bereits vorgefunden hat — eine Veröffentlichung, die erneut über eine bereits vollständige Version läuft, oder ein Signier-Batch, bei dem jede Referenz bereits eine verifizierbare Signatur trug. Ein Probelauf nennt dennoch das Ziel, das er angesprochen hätte. Zeigen Sie es an, bevor Sie auf das Ergebnis hin handeln.
Das Registrieren oder Entfernen einer Registry schreibt standardmäßig die Konfiguration, die von allen Workspaces auf dem Rechner geteilt wird. Eine Registry und die Identitäten, denen Sie darauf vertrauen, sind meist überall gleich, wo Sie arbeiten, daher landet der Eintrag dort, es sei denn, die Anfrage sendet workspace: true. Die Folge sollte man klar aussprechen: aggrega/registryAdd und aggrega/registryRemove ändern, worüber jedes Projekt auf diesem Rechner auflöst, einschließlich Projekten, die niemand in dieser Sitzung genannt hat. Beide Antworten tragen scope, mit der geschriebenen configFile und machineWide, das angibt, ob es die geteilte ist. Das Entfernen ist das heiklere der beiden, weil erneutes Hinzufügen nicht derselbe Vorgang ist — die festgelegte Vertrauensrichtlinie ist weg, und eine spätere Registrierung legt fest, was die Registry dann ankündigt.
Das Anlegen einer Konfiguration schreibt standardmäßig dieselbe geteilte Datei, und aus demselben Grund. aggrega/configInit registriert eine Registry und ihre Vertrauensrichtlinie, was rechnerweites Werkzeug ist, daher schreibt es ohne Override die Konfiguration, über die jedes Projekt auf dem Rechner auflöst — und erreicht diese Registry einmal, um die Richtlinie zu lesen, die sie ankündigt. Seine Antwort trägt dasselbe scope-Paar wie die beiden Registry-Methoden. Es unterscheidet sich von ihnen in einem Punkt, auf den man sich verlassen kann: Es lehnt ab, statt zu überschreiben, wenn eine Konfigurationsdatei bereits existiert, sodass es eine Konfiguration, mit der jemand arbeitet, nur ersetzen kann, wenn die Anfrage force sendet. Das Einfrieren ist der umgekehrte Fall: aggrega/configCapture nimmt überhaupt keinen Override an, schreibt immer die eigene Konfigurationsdatei des Projekts und erreicht keine Registry, sodass nichts, was es tut, für ein anderes Projekt sichtbar ist. Siehe Was ein Konfigurationsschreibvorgang hinterlässt.
🔴 Das Hinzufügen oder Entfernen eines Plugins zur Befehlserweiterung schreibt standardmäßig dieselbe geteilte Datei, und dies ist der Fall, den man genau lesen sollte. aggrega/pluginAdd und aggrega/pluginRemove nehmen einen type an, und der Typ entscheidet, wohin der Schreibvorgang geht, wenn kein Override gesendet wird. Ein provider-, governance-, linter- oder importer-Eintrag prägt den Build eines Projekts, daher geht er in die eigene Konfiguration dieses Projekts. Ein cli-Eintrag ist rechnerweites Werkzeug, daher registriert ein Hinzufügen vom Typ cli, das weder global noch workspace nennt, den Befehl in der globalen Konfigurationsdatei, über die jeder Workspace auf diesem Rechner auflöst — der Befehl wird zu einem aggrega-Befehl der obersten Ebene für jedes Projekt auf diesem Rechner, einschließlich Projekten, die niemand in dieser Sitzung genannt hat, und ihn zurückzunehmen ist ein separates Entfernen statt eines Rückgängigmachens. Senden Sie workspace: true, um ihn lokal zu halten. Beide Antworten tragen scope, mit der geschriebenen configFile und machineWide, das angibt, ob es die geteilte ist, abgeleitet aus der Datei, zu der der Schreibvorgang aufgelöst wurde. Ein Hinzufügen erreicht außerdem die Registry, die es durchsucht hat, liegt also auf beiden Achsen zugleich. Siehe Was Ihnen eine Plugin-Änderung sagt.
Die anderen beiden Plugin-Anfragen schreiben nur innerhalb des Workspaces. aggrega/pluginSync schreibt die Plugin-Entitätsdatei, die die Anfrage nennt, und aggrega/pluginGenCatalog schreibt die generierten Entitäten unter das outputDir, das die Anfrage nennt — beide innerhalb des Workspaces, den die Anfrage genannt hat, beide lehnen ein Ziel ab, das absolut ist oder außerhalb davon aufgelöst wird, und keine ist für ein anderes Projekt sichtbar. aggrega/pluginGenCatalog liest sein Modul und sein Overlay von dort, wo Sie sie ausgewählt haben, was nicht erweitert, wohin es schreibt: Die beiden werden nach unterschiedlichen Regeln aufgelöst, sodass eine Generierung ein Modul lesen kann, das Sie irgendwo gebaut haben, während die Entitäten, die sie erzeugt, trotzdem innerhalb des Workspaces landen. aggrega/pluginGenCatalog mit dryRun schreibt überhaupt nichts und gibt stattdessen den Inhalt zurück.
Auch das Festlegen einer Entität schreibt nur innerhalb des Workspaces und erreicht die Hosts, die ihre Quellen nennen. aggrega/pin schreibt die entity.lock neben die Entität, die die Anfrage nennt, was ein Pfad innerhalb des Workspaces ist, und füllt den Inhalts-Cache des Workspaces mit den Quellen, die es abgerufen hat; nichts, was es schreibt, ist für ein anderes Projekt sichtbar. Es greift nach außen, um jede entfernte Quelle aufzulösen, die die Entität nennt — ein Chart-Repository, einen Git-Host, eine URL —, was dieselbe Reichweite ist, die aggrega/resolveDependencies für die Quellen hat, die ein Release verwendet. aggrega/resolveDependencies und aggrega/publishEntity, mit pinSources gesendet, führen denselben Schritt aus, sodass jede von ihnen ebenfalls neben die Entitäten schreibt, die sie festlegt; eine Veröffentlichung, die festlegt, erreicht daher sowohl den Workspace als auch die Registry. Eine Veröffentlichung, die nicht festlegt, schreibt nichts neben die Entität und erreicht diese Hosts dennoch: Den Lock mit dem zu vergleichen, was der Schritt aufzeichnen würde, bedeutet, jede entfernte Quelle abzurufen, die die Entität vollständig ausschreibt.
Die Installation des Assistenten-Skills bleibt innerhalb des Workspaces, es sei denn, die Anfrage sendet global. aggrega/skillsInstall schreibt den Projekt-Skill-Ordner jedes genannten Assistenten innerhalb des Workspaces, den die Anfrage genannt hat, und nichts, was es dort schreibt, ist für ein anderes Projekt sichtbar; das scope seiner Antwort trägt machineWide false. Mit global: true schreibt es stattdessen den benutzerbezogenen Ordner jedes Assistenten unter dem Home-Verzeichnis, den dieser Assistent in jedem Projekt auf dem Rechner liest, und machineWide ist true. In beiden Fällen erreicht es keine Registry und kein Netzwerk.
Das Entfernen eines gespeicherten Credentials reicht weiter als alles andere hier, das an diesem Rechner endet. aggrega/logout ändert den Credential-Speicher, und dieser Speicher wird nicht nur von jedem Projekt auf dem Rechner geteilt, sondern von jedem anderen Werkzeug, das sich bei denselben Registries authentifiziert — ein über eine Sitzung entferntes Credential ist also für alle weg, und aggrega/registryList meldet es auch in jedem anderen Workspace als nicht vorhanden. Seine Antwort trägt scope mit machineWide, das immer true ist: Dieser Speicher hat keine Workspace-bezogene Form, zu der er aufgelöst werden könnte, daher gibt es keinen Override zu senden und nichts, wofür sich eine Anfrage entscheiden könnte. scope nennt bewusst keine Datei, anders als die Konfigurationsschreibvorgänge oben. Der Speicher delegiert an den Credential-Helper oder Betriebssystem-Schlüsselbund, den der Rechner konfiguriert hat, daher wird das Entfernen häufig von etwas bedient, das gar keine Datei ist, und einen Pfad zu nennen, würde Sie auf einen Ort verweisen, den das Entfernen nicht unbedingt berührt hat.
Entfernen ist nicht die Umkehrung des Authentifizierens, und ein Client sollte es nicht als solche anbieten. Diese Oberfläche entfernt ein Credential und beschafft keines: Ein Credential zurückzubekommen bedeutet, sich erneut mit aggrega login an einem Terminal zu authentifizieren, weil das Speichern eines solchen ein von einer Person eingegebenes Geheimnis erfordert und niemand diesen Strom beobachtet. Ein „Abmelden“, das ein Client anbietet, ist von hier aus also eine Einbahnstraße. Was die beiden trennt, ist, ob die Operation etwas von demjenigen beschaffen muss, der sie steuert — ein Entfernen trägt seinen einen Wert in der Anfrage, während das Beschaffen eines Credentials das nicht tut —, und nicht, ob eine Person beteiligt ist, da eine Person beides gewählt hat.
Das Freigeben von Cache-Inhalten reicht ebenfalls über den Workspace hinaus. Die Speicher für kompilierte Module und Plugin-Beschreibungen werden von jedem Projekt auf dem Rechner geteilt, daher können aggrega/cachePrune, aggrega/cacheEvict und aggrega/cacheClear Inhalte entfernen, von denen ein anderes Projekt abhängt. Jede Entfernung trägt die reach der Klasse, aus der sie stammt, und jede Antwort trägt scope.machineWideClasses. aggrega/cacheStatus trägt dieselbe Reichweite auf jeder Klasse, obwohl es nichts ändert, weil ein Client, der entscheidet, ob er Speicher freigibt, sie bevor er handelt braucht.
Das Aktualisieren des Suchindex ist der umgekehrte Fall. aggrega/registryUpdate erreicht jede konfigurierte Registry, und was es schreibt, landet unter dem eigenen konfigurierten Cache-Verzeichnis dieses Workspaces — es ändert also nichts, worüber ein anderes Projekt auflöst. indexRoot in der Antwort nennt dieses Verzeichnis.
Eine teilweise Aktualisierung antwortet, statt fehlzuschlagen. Eine Anfrage, die eine einzelne Registry nennt, deren Aktualisierung fehlgeschlagen ist, ist ein Fehler, weil es keine Antwort zu geben gibt. Eine Anfrage, die jede konfigurierte Registry aktualisiert, ist erfolgreich, selbst wo einige davon oder alle fehlgeschlagen sind: Die aktualisierten wurden indiziert und geschrieben, failed nennt die übrigen, und jeder Host trägt seinen eigenen Fehler. Lesen Sie failed statt des Vorhandenseins eines Fehlers.
Ob eine Registry erreicht werden konnte, ist ein Schlüssel, keine Deutung der Meldung. Ein fehlgeschlagener Host trägt unreachable: true, wo die Registry nie erreicht wurde — ihr Name wurde nicht aufgelöst, eine Verbindung zu ihr wurde abgelehnt oder konnte nicht geöffnet werden, oder eine sichere Verbindung zu ihr konnte nicht hergestellt werden —, und die Ablehnung einer Anfrage, die eine einzelne Registry nennt, trägt denselben Schlüssel in ihrem data. Eine Registry, die erreicht wurde und fehlgeschlagen ist, mit einer Auflistung, die sich wiederholte, oder einem Fehlerstatus, trägt ihn in keinem der beiden Fälle, und ihr error oder die Meldung der Ablehnung sagt, was sie geantwortet hat. Der Schlüssel wird aus dem Fehlschlag selbst gelesen, hängt also nicht davon ab, wie der Resolver dieses Rechners einen Fehlschlag formuliert, und wird nur gesetzt, wo der Fehlschlag zeigt, dass die Registry nie erreicht wurde: Ein Fehlschlag, der in keine Richtung etwas zeigt, etwa ein abgelaufenes Zeitlimit ohne Aufzeichnung, welchen Schritt es unterbrochen hat, wird ohne ihn gemeldet. Bezeichnen Sie eine Registry anhand des Schlüssels als nicht erreicht, und zeigen Sie den Fehler als Grund an.
Die Befehlszeile meldet denselben Durchlauf als Exit-Code ungleich null, und welche Art von Leser Sie sind, entscheidet, was dieser Exit-Code wert ist. Für eine Person an einem Terminal ist er nicht die ganze Auskunft: aggrega registry update gibt aus, wie viele der ausgewählten Registries es indiziert hat, was jede gefunden hat, welche es nicht indiziert hat und wohin der Index geschrieben wurde — die Zusammenfassung sagt also, was passiert ist, und der Exit-Status sagt nur, ob alles erfolgreich war. Für ein Skript ist er die ganze Auskunft, weil dieser Befehl keinen strukturierten Ausgabemodus bietet, sein Exit-Status also das einzige maschinenlesbare Urteil ist, das verfügbar ist. Deshalb beantworten die beiden Oberflächen denselben teilweisen Durchlauf unterschiedlich, und beide haben recht: Diese übergibt einem strukturierten Aufrufer failed und ist erfolgreich, während die Befehlszeile ein Bit zu vergeben hat und es für „wurde eine Registry verfehlt“ ausgibt.
Eine lange Operation verfolgen
Die meisten Anfragen hier antworten aus dem, was bereits auf der Festplatte liegt, und antworten sofort. Einige leisten zuerst echte Arbeit — die Abhängigkeiten eines Release auflösen, seine externen Eingaben festlegen, veröffentlichen, signieren, zurückziehen —, und der Aufrufer wartet. Diese melden, was sie tun, während sie es tun, und das wird pro Anfrage aktiviert.
Die Aktivierung erfordert zwei Schritte, in dieser Reihenfolge.
- Deklarieren Sie die Fähigkeit beim Handshake, und warten Sie auf die Antwort. Senden Sie
capabilities.window.workDoneProgress: truebeiaggrega/initialize. Senden Sie nichts anderes, bis diese Antwort eingetroffen ist: Anfragen werden nebenläufig bearbeitet, sodass eine Anfrage, die geschrieben wurde, bevor der Handshake geantwortet hat, neben dem Handshake laufen kann, der für sie verhandeln sollte. Jeder Client schuldet dem Protokoll diese Reihenfolge bereits; dies ist eine weitere Sache, die von ihr abhängt. - Legen Sie ein Token in die params der Anfrage. Fügen Sie
workDoneTokenzu den params der Anfrage hinzu, über die Sie Meldungen erhalten möchten. Den Wert wählen Sie selbst — eine Zeichenkette oder eine Zahl —, und er verknüpft die Benachrichtigungen mit diesem Aufruf. Erzeugen Sie für jeden Aufruf ein neues.
Die Benachrichtigung. Jede ist $/progress, mit params.token auf Ihr Token gesetzt und params.value, das eine Nutzlast trägt:
value.kind | trägt | wann |
|---|---|---|
begin | title — was geschieht, in einer Formulierung, die Sie einem Leser zeigen können | einmal, wenn die Arbeit beginnt |
report | message — eine Zeile aus dem eigenen Bericht der Operation über sich selbst | beliebig oft, wie die Operation sie schreibt |
end | nichts außer der Art | einmal, wenn die Arbeit vorbei ist |
Korrelieren Sie über das Token, nie über die Anfrage-ID. Eine Benachrichtigung trägt keine ID — sie ist keine Antwort auf irgendetwas —, und das Token ist das Einzige darin, das auf Ihren Aufruf zurückverweist. Das ist beabsichtigt: In vielen Clients gehört die Anfrage-ID zum Transport und erreicht nie den Code, der den Aufruf abgesetzt hat, während das Token ein Wert ist, den dieser Code bereits hält.
Ein report trägt den eigenen Text des Compilers. Die Meldung ist eine Zeile, die die Operation während ihrer Arbeit geschrieben hat, durchgereicht mit entferntem umgebendem Leerraum und sonst unverändert — nicht umformuliert, nicht zusammengefasst, nicht neu zusammengesetzt —, und eine Zeile, die die Operation leer geschrieben hat, wird verworfen, statt als leere Meldung gemeldet zu werden. Ein Client zeigt also, was er erhält, so wie es ist. Es ist dieselbe Eigenschaft, die die eigenen Diagnosen der Antwort haben: Eine Bedingung behält einen Wortlaut, wie viele Oberflächen sie auch melden.
Auch ein Schritt, auf den die Operation wartet, ist ein report. Wenn die Operation in einen Schritt eintritt, auf den sie wartet – das Lesen einer Registry, das Abrufen eines Artefakts, das Kompilieren eines Plugins –, trägt ein report den Namen des Schritts, in den Worten, die die Befehlszeile für denselben Schritt neben ihrer Fortschrittsanzeige zeigt. Nur Schritte, in die zwischen begin und end eingetreten wird, werden gemeldet.
Eine Ausgabezeile ist ein report. Eine Operation, die mehrere Zeilen auf einmal schreibt, erzeugt eine Benachrichtigung pro Zeile, und eine Zeile, die die Operation in Teilen schreibt, wird gemeldet, sobald sie vollständig ist — eine Meldung ist also nie ein halber Satz.
Es gibt keinen Bruchteil und keinen Prozentsatz, und das ist keine Lücke, die auf Arbeit wartet. Die Operationen, die hier melden, arbeiten eine Menge ab, deren Größe beim Start der Arbeit nicht bekannt ist — wie viele Referenzen eine Auflösung durchläuft, wie viele Layer eine Veröffentlichung hochlädt —, daher wäre jeder Bruchteil erfunden. Zeichnen Sie einen unbestimmten Indikator, und zeigen Sie die neueste message an.
Frames kommen vor der Antwort an und nie danach. Ein begin kommt an, sobald die Arbeit tatsächlich begonnen hat, sodass eine Anfrage, die wegen ihrer params abgelehnt wird — ein absoluter Pfad, ein fehlendes Pflichtfeld —, keine Benachrichtigung erzeugt, nur ihren Fehler. Das end kommt vor der Antwort an, und ob die Operation erfolgreich war, steht in der Antwort, statt im end wiederholt zu werden.
Das Anhalten der Arbeit ist eine separate Benachrichtigung. Senden Sie $/cancelRequest mit der ID, unter der Sie die Anfrage gesendet haben. Das Token spielt beim Abbrechen keine Rolle, und das Abbrechen unterdrückt die bereits gesendeten Frames nicht.
Welche Anfragen melden, und was von den übrigen zu erwarten ist
Genau diese melden: aggrega/resolveDependencies, aggrega/pin, aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact.
Zwei Dinge gelten für jede von ihnen, und beide sind der Grund, warum sie auf der Liste steht: Sie erreicht in Ihrem Auftrag eine Registry oder eine entfernte URL, sodass ihre Dauer von etwas außerhalb des Rechners bestimmt wird; und sie schreibt bereits während ihres Ablaufs ihren eigenen Bericht über sich selbst — den Bericht, den eine Person liest, die ein Terminal beobachtet. Die Meldung übergibt Ihnen also denselben Bericht statt eines zweiten, für die Leitung verfassten, und an dem, was die Operation tut, musste nichts geändert werden, um ihn zu erzeugen.
Jede andere Anfrage nimmt ein Token an und sendet nichts. Eines zu senden ist harmlos statt ein Fehler: Es wird angenommen, keine Benachrichtigung kommt an, und die Antwort ist genau die, die Sie ohne es bekommen hätten. Ein Client darf also an beliebige Anfragen ein Token anhängen und einfach nichts zeichnen, wenn nichts kommt.
🔴 Deuten Sie die Stille nicht als „diese ist sofort fertig“. Die meisten der übrigen antworten tatsächlich aus dem, was bereits auf der Festplatte liegt — eine Validierung, ein Hover, eine Vervollständigung, ein Graph, eine Cache-Auflistung, ein Lesen der Konfiguration —, aber nicht alle: Das Aktualisieren eines Registry-Index, das Hinzufügen eines Plugins, eine Prüfung vor der Veröffentlichung und die erste Erläuterung eines Codes auf einem Rechner, der keine Dokumentation hält, die der Workspace lesen darf, erreichen alle eine Registry, und das Kompilieren eines Release ist echte Arbeit. Diese dauern so lange, wie sie dauern, und melden heute nichts. Zeigen Sie für jede Anfrage, auf die Sie zu warten bereit sind, einen unbestimmten Indikator an, und behandeln Sie Benachrichtigungen als Details, die Sie erhalten, wenn sie verfügbar sind, statt als das, was Ihnen sagt, dass Arbeit im Gange ist.
Zwei Ablehnungen
Beide sind invalid-params-Fehler, und beide nennen, was zu tun ist, weil ein Token, das stillschweigend nichts bewirkt, Sie auf einen Strom warten ließe, der nie kommen würde.
- Ein Token aus einer Sitzung, die keine
window.workDoneProgress-Fähigkeit deklariert hat, wird abgelehnt, wobei die zu deklarierende Fähigkeit genannt wird. Deklarieren Sie sie beim Handshake, oder lassen Sie das Token weg. - Ein Token, das weder eine Zeichenkette noch eine Zahl ist, wird abgelehnt, wobei die beiden Formen genannt werden. Ein fehlendes Token und ein explizites
nullsind keine Ablehnungen — beide bedeuten, dass Sie keine Meldungen angefordert haben.
Lockfile-Bewusstsein
Der Daemon prüft bei jedem aggrega/irGraph ein Lockfile auf Drift, gegen das Release, das diese Anfrage genannt hat, und meldet Drift als nicht blockierende Warnung. Die Warnung nennt den Befehl, der dieses Lockfile mit dem Release darin neu schreibt, so geschrieben, wie die Anfrage es gesendet hat — aggrega pull --release, gefolgt von dem release, das Sie gesendet haben, so wie es an einem Terminal im Workspace-Root geschrieben wird. aggrega/irGraph erfordert, dass ein Lockfile vorhanden ist. Es gibt keine separate Prüfung beim Start: Eine Anfrage sagt, um welches Release es geht, daher wird das Urteil für dieses Release berechnet, wenn danach gefragt wird, statt einmal für ein im Voraus gewähltes Release.
Eine Drift-Warnung verschwindet, wenn ihr Lockfile verschwindet. Die Warnung wird auf dem Lockfile veröffentlicht, gegen das sie erhoben wurde, und ein Lockfile, das nicht mehr da ist, hat keine Pins mehr, die gedriftet sein könnten — der Befehl, den die Warnung nennt, würde eine neue Datei schreiben, statt die alte zu reparieren. Daher zieht jede Anfrage, die das Lockfile als fehlend vorfindet, die Warnung zurück, bevor sie mit dem Fehler für ein fehlendes Lockfile ablehnt: aggrega/irGraph, aggrega/releaseClosure, aggrega/build, aggrega/buildPreview, aggrega/attachCandidates und aggrega/attachmentContainer, wenn nach einem Graphknoten gefragt wird, und aggrega/connectionAtPosition. Der Rückzug kommt als aggrega/publishDiagnostics-Benachrichtigung für das Lockfile mit einer leeren Liste an, vor der Ablehnung. Er stammt von derjenigen dieser Anfragen, die zuerst von der Löschung erfährt, sodass bei einem Client, der die Löschung meldet und dann irgendetwas zu diesem Release fragt, die Warnung entfernt wird, ohne dass er eigens nach dem Graphen fragen muss. Ein Lockfile, das noch vorhanden und noch gedriftet ist, behält seine Warnung über jede dieser Anfragen hinweg. aggrega/invalidate, das das Lockfile nennt, verwirft, was der Daemon dafür hält, sendet aber nichts; die nachfolgende Anfrage ist das, was den Client informiert. Und ein Lockfile, das der Daemon nicht einmal untersuchen kann — etwa eines, dessen Verzeichnis er nicht lesen darf —, zieht nichts zurück, weil es noch da sein kann und die Warnung noch zutreffen kann.
aggrega/build und aggrega/buildPreview erfordern ebenfalls eines, und sie halten das Release daran fest, statt zu warnen — sie rendern mit der Haltung einer Oberfläche, die ein Artefakt ausgibt, sodass ein Lockfile, das nicht mehr zu dem passt, wozu das Release aufgelöst wird, sie anhält, wo es bei einer Inspektion nur eine Warnung auslösen würde. Ein Release ohne Lockfile wird mit dem Fehler für ein fehlendes Lockfile abgelehnt. Die Ausnahme ist ein Build, dessen Feld autoPull ihn auffordert, zuerst die Abhängigkeiten aufzulösen: Dieser Build schreibt das Lockfile und rendert dann gegen das, was er geschrieben hat, und ein auf diese Weise erzeugtes Lockfile wird kein zweites Mal auf Drift geprüft, weil die Auflösung, die es geschrieben hat, dieselbe Prüfung vor dem Schreiben dagegen ausgeführt hat und kein Lockfile schreibt, das diese Prüfung ablehnt.
Ein Lockfile, das existiert, aber keinen Digest für ein Plugin aufzeichnet, hält den Graphen nicht an — ein fehlendes Lockfile schon. Das sind zwei Bedingungen, und nur die zweite führt zur Ablehnung. aggrega/irGraph hält die Bytes, die es auflöst, nicht an ihre aufgezeichneten Digests: Ein Pin, den es nicht verifizieren kann, wird gemeldet statt abgelehnt, und der Graph wird mit dem Befund im Problems-Panel gezeichnet, da ein Editor, der sich weigert, den Graphen zu zeichnen, dem Leser nichts lässt, wo ein Bericht ihm etwas lässt, auf das er reagieren kann. Anderswo läuft das Plugin ebenfalls, mit einer Warnung, die sagt, dass nichts seine Bytes geprüft hat. Was aggrega/irGraph ablehnt, ist das fehlende Lockfile: Es hält an, bevor es irgendetwas auflöst, und antwortet mit dem Fehler für ein fehlendes Lockfile, wobei es das Lockfile, nach dem es gesucht hat, und das Release nennt, sodass ein Client direkt aggrega pull --release <release> anbieten kann — oder aggrega/resolveDependencies für dieses Release senden und das Lockfile schreiben kann, ohne die Sitzung zu verlassen. Die beiden auseinanderzuhalten ist wichtig, weil ein gezeichneter Graph ein Bild ist, über das ein Leser dann nachdenkt, und einer, der aus ungeprüften Bytes gebaut wurde, genau so gezeichnet wird wie ein geprüfter, während der Befund irgendwo steht, wo der Leser nicht hinsieht. Ein Graph ist also kein Urteil über die Bytes dahinter — aggrega/build und aggrega/buildPreview sind die Oberflächen, die ein Release an seine aufgezeichneten Digests halten und anhalten, wo die Inspektion nur meldet.
aggrega/validate liest, wenn eine Anfrage ein Release nennt, das Lockfile dieses Release nur für seine Pins und seine Veraltungshinweise — und liest keines für eine Katalog-Entität, die es als einzelne Entität prüft, so wie die Befehlszeile keines liest. Es hält die Plugins, die es ausführt, nicht an die aufgezeichneten Digests, und es baut die Attachment-Menge der Transform-Plugins nicht aus dem Lockfile neu auf — es validiert gegen die Workspace-Konfiguration, wie sie vor Ihnen liegt, was ein Editor tun muss, während Sie diese Konfiguration bearbeiten. aggrega validate und aggrega build tun beides und bleiben die maßgeblichen Oberflächen für ein Urteil über einen committeten Workspace.
Ihre Veraltungshinweise decken beide Orte ab, an denen ein Rückzug festgehalten wird. Eine Markierung an einer festgelegten Referenz steht im Lockfile; eine Markierung an einem Plugin, das in einer Rolle angehängt ist, die ein Urteil aus Annahme oder Ablehnung liefert — ein plugins.governance-Anhang bei ir-verdict oder render-verdict oder ein plugins.linter-Anhang —, steht im Plugin-Vertrauensdatensatz daneben, daher liest die Validierung beide und nennt jede zurückgezogene Referenz und jedes zurückgezogene Plugin als Warnung am Anfang des Aggregate, in den Worten, die aggrega build ausgibt. Ein Hinweis ändert kein Urteil. Ein Vertrauensdatensatz, der vorhanden ist und nicht gelesen werden kann, wird anstelle der Validierung als Fehler gemeldet, statt als einer gelesen zu werden, der nichts festhält. aggrega/releaseClosure meldet dieselbe Menge in seinem deprecations.
Wo das Lockfile eines Release liegt
Jede Antwort, die ein Release nennt, nennt auch sein Lockfile, sodass ein Client den Pfad nie selbst ermitteln muss. aggrega/activeRelease trägt es als lockfile neben release, aggrega/releaseCandidates als die Map lockfiles neben releases, und der Fehler für ein fehlendes Lockfile als lockfile in seinem data. Jedes ist die Datei, die aggrega pull --release <release> schreibt und aggrega build liest, und die Datei, nach der jede Anfrage oben sucht — ein Client, der das Lockfile eines Release beobachtet, um zu bemerken, dass es geschrieben, neu geschrieben oder gelöscht wird, beobachtet also die Datei, die der Daemon meint. Das Lockfile liegt neben seinem Release und übernimmt den Namen des Release, wobei eine Erweiterung .yaml oder .yml durch .lock ersetzt wird; ein Release mit einer anderen Erweiterung behält seinen ganzen Namen, sodass das Lockfile von release.rel release.rel.lock ist. Lesen Sie den Pfad aus der Antwort ab, statt ihn aus dieser Beschreibung zusammenzusetzen, dann können die beiden nicht auseinanderlaufen.
Die externen Referenzen, die ein Rendering anfordert
Ein Rendering kann Inhalte von einer entfernten URL anfordern — etwa das Werteschema eines Charts mit einer entfernten Referenz. Externe Eingaben sind für jedes Rendering eingefroren, das dieser Daemon als Antwort auf eine Anfrage ausführt, die nur darum bat, etwas mitgeteilt zu bekommen. Eine Referenz, die das Lockfile der Release pinnt, wird aus dem inhaltsadressierten Store bereitgestellt, was ein Lesen von bereits auf der Festplatte liegendem Inhalt ist und kein Abruf, und sie wird mit dem abgeglichen, was das Lockfile verzeichnet, bevor ihre Bytes bereitgestellt werden — so sieht ein Rendering hier, was ein Build sieht, und meldet die Hinweise, die ein Build meldet. Eine Referenz, die das Lockfile nicht pinnt, wird abgelehnt statt abgerufen: Sie zu beschaffen hieße, ein Netzwerk zu erreichen und einen Blob in den Store zu schreiben, und eine Sitzung tut keines von beiden auf eine Anfrage hin, die nur darum bat, etwas mitgeteilt zu bekommen. Das ist die Regel unter Eine Registry erreichen und schreiben, von der Seite des Renderings aus gelesen, und sie gilt, wie auch immer ein solches Rendering erreicht wurde.
Die Anfrage, deren Zweck das Pinnen ist, ist die Ausnahme, und es ist dieselbe Ausnahme, die die Registry-Regel bereits enthält. aggrega/resolveDependencies wird zum Beschaffen aufgefordert, sodass das Rendering, das sie ausführt, um herauszufinden, welche Referenzen diese Release verwendet, das Netzwerk erreicht und schreibt, was sie pinnt — und genau das macht ihr Ergebnis zu einem Lockfile statt zu einem Bericht. Kein Rendering, das eine Graph- oder Build-Anfrage für sich selbst ausführt, tut irgendetwas davon.
Ein Build, der zuerst auflösen soll, wird aus genau diesem Rendering beantwortet, weshalb er die Release nur einmal rendert. Die Auflösung hat bereits gerendert, worum es dem Build geht, gegen die Pins, die sie gerade geschrieben hat, und unter den Prüfungen, die ein Build ausführt, sodass der Build dieses Rendering vorlegt, statt ein zweites auszuführen — und die Beschaffung gehört weiterhin zur Auflösung und nicht zum Build. Nur ein Rendering, das abgeschlossen wurde, wird so verwendet: Wo eine Auflösung ihre Abhängigkeiten gepinnt hat, die Ermittlung der externen Referenzen aber nicht abschließen konnte, rendert der Build selbst gegen die Pins, die tatsächlich geschrieben wurden, und eine nicht gepinnte Referenz wird dort genauso abgelehnt und gemeldet wie bei einem Build, der nichts aufgelöst hat.
Das Ablehnen wird gemeldet statt geschluckt, weil nichts an einem Ergebnis verrät, welche Referenz darin gefehlt hat. Mit den Providern, die dieses Binary mitbringt, gibt der Provider, der die Referenz angefordert hat, die Ablehnung zurück, sodass ein Rendering, das eine abgelehnte Referenz erreicht hat, nicht abgeschlossen wird. Jede abgelehnte Referenz kommt daher als eigener Eintrag auf der Ebene aggrega-build an und nennt die Referenz und den Befehl, der sie pinnt: aggrega pull --release <release>, oder aggrega/resolveDependencies für dieselbe Arbeit, ohne die Sitzung zu verlassen. Die Einträge sind Hinweise und keine Ablehnung — der Graph wird trotzdem zurückgegeben, mit demselben Stellenwert wie die Drift-Warnung oben — und sie werden dem Aggregate am Anfang der Datei zugeordnet, weil eine Referenz, die ein Rendering angefordert hat, keinen Schlüssel nennt, den ein Autor geschrieben hat. Sie reisen in derselben Veröffentlichung wie die eigenen Hinweise des Renderings, die diese Ebene vollständig ersetzt, sodass eine Referenz, die Sie anschließend pinnen, nicht mehr gemeldet wird, ohne dass etwas sie löschen muss. Ein vollständig gepinntes Rendering sagt zu alldem nichts. Siehe Was ein Diagnoseeintrag enthält für die Form jedes Eintrags.
Bei aggrega/irGraph hängt dies davon ab, dass die Rendering-Phase überhaupt ausgeführt wird. Die Graph-Anfrage überspringt das Rendering, sofern es nicht --build-on-inspect oder der Schlüssel serve.build_on_inspect, den es überschreibt, einschaltet; ist der Schalter aus, fordert nichts eine externe Referenz an, und es gibt nichts abzulehnen. Ihn einzuschalten bringt sowohl die eigenen Hinweise des Renderings als auch diese in eine Editor-Sitzung.
Worin sich eine Sitzung vom selben Einfrieren auf der Kommandozeile unterscheidet. aggrega build friert externe Eingaben auch für einen Probelauf ein, und eine nicht gepinnte Referenz verhält sich auf beiden Oberflächen gleich: Sie wird als Befund gemeldet, der die Referenz nennt, und das Rendering wird dann angehalten, weil der Provider, der sie angefordert hat, die Ablehnung zurückgibt. Was sich unterscheidet, ist der erneute Abruf. Auf der Kommandozeile wird eine gepinnte Referenz, deren gespeicherte Kopie verloren gegangen ist, anhand ihres verzeichneten Digests erneut abgerufen; das Rendering, das eine Graph- oder Build-Anfrage beantwortet, ruft nichts erneut ab, weil dieses Rendering kein Netzwerk erreicht, und kann daher eine gepinnte Referenz, die der Store nicht mehr enthält, nicht nachholen — und eine solche Referenz gehört nicht zu den oben beschriebenen Ablehnungen, die nennen, was das Lockfile nicht pinnt. Eine Sitzung zum Pinnen aufzufordern ist das, was sie wiederherstellt: Die oben genannten Anfragen erreichen das Netzwerk und legen die fehlenden Bytes zurück. Siehe aggrega pull dazu, was das Pinnen abruft und verzeichnet.
Was ein abgelehnter Lauf Ihnen trotzdem mitteilt
Eine Anfrage, die ablehnt, antwortet mit einem Fehler-Envelope, und die Befunde, die der Lauf bereits gemacht hatte, reisen nicht in diesem Envelope — der Envelope enthält überhaupt keinen Ergebnisrumpf. Sie erreichen Sie auf demselben Weg wie bei einem abgeschlossenen Lauf: als Diagnoseveröffentlichung auf der Ebene aggrega-build, beschrieben unter Was ein Diagnoseeintrag enthält. Ein Client, der eine Ablehnung behandelt, liest also den Envelope für das, was zu ändern ist, und seine Problemansicht für das, was der Lauf gefunden hat, und keines ersetzt das andere. Eine beim Rendering ausgelöste Ablehnung ist die einzige Ablehnung, die zugleich ein Befund über das ist, was ein Autor geschrieben hat, sodass sie beide erreicht, wie der nächste Abschnitt beschreibt.
Diese Veröffentlichung erfolgt unabhängig davon, ob der Lauf sein Ende erreicht hat. Ein Lauf, der mittendrin anhält, hat dennoch alles vor der Stelle gefunden, an der er anhielt, und ein Leser, der diese Befunde verlöre, müsste erneut ausführen, um sie zu sehen — daher werden die Hinweise aus dem veröffentlicht, was der Lauf erreicht hat, und die Ablehnung wird danach zurückgegeben. Es ist dieselbe Menge in derselben Genauigkeit, auf denselben Authoring-Schlüsseln positioniert: Eine Ablehnung stuft einen Befund nicht zu einem Satz herab. Die abgelehnten externen Referenzen reisen in derselben Veröffentlichung, aus demselben Grund und auf demselben Weg.
Begrenzt wird sie dadurch, wie weit der Lauf gekommen ist, nicht dadurch, was die Ebene tragen kann. Eine Ablehnung durch eine der Prüfungen, die laufen, bevor der Compiler startet — die Closure der Release konnte nicht aufgelöst werden, das Manifest bildet einen Typ auf ein Rezept ab, das ihn nicht implementiert, das Lockfile stimmt nicht mehr mit dem überein, wozu die Release aufgelöst wird, ein gepinnter Eintrag im Cache stimmt nicht mehr mit dem für ihn verzeichneten Digest überein und kein Katalogverzeichnis enthält die gepinnten Bytes —, hat keine Hinweise zu veröffentlichen, weil noch keine ausgelöst worden waren. Die Ebene enthält dann nichts statt etwas Veraltetem; und ein Lauf, der nicht so weit kam, ein Dokument zu benennen, veröffentlicht überhaupt nichts und lässt, was bereits in Ihrer Problemansicht steht, genau so, wie es war, statt Einträge zu löschen, über die er nichts erfahren hat.
Eine beim Rendern ausgelöste Ablehnung
Eine Release, die der Compiler beim Rendern ablehnt — eine Workload, die einen Slot nennt, den ihre Component nicht deklariert, eine fehlschlagende Assertion, ein Template, das nicht ausgewertet werden kann, eine Realisierung, die nicht liefert, was sie liefern muss —, wird dort gemeldet, wohin sie zeigt, und mit den Worten des Compilers, bei jeder Anfrage, die sie rendert: aggrega/build, aggrega/buildPreview und aggrega/irGraph mit eingeschalteter Rendering-Phase. Die Antwort ist ein Fehler-Envelope mit dem Code -32603, dessen message die Ablehnung mit jeder Ursache darunter ist, in den Worten, die die Kommandozeile für denselben Build ausgibt: der gerenderte Knoten, dann was darin abgelehnt hat, jede Ursache nach derjenigen, die sie erklärt — angeführt, wo die Ablehnung eine registrierte Bedingung nennt, vom Kurzcode dieser Bedingung, wie es jede Ablehnung, die eine nennt, ist. Ihr data nennt das Dokument, auf das die Ablehnung zeigt, als file und den Bereich des Schlüssels darin als line, column, end_line und end_column, neben code und shortCode der Bedingung; eine Ablehnung, die keinen Schlüssel nennt oder einen, den das Dokument nicht enthält, trägt nur file, und eine, die auf kein Dokument zeigt, nennt das Aggregate der Release.
Dieselbe Ablehnung wird auf der Ebene aggrega-build veröffentlicht, an diesem Dokument, an diesem Schlüssel, als Eintrag mit Schweregrad error, der den eigenen keyPath der Ablehnung und die message des Envelopes ohne vorangestellten Kurzcode trägt, und — wo die Ablehnung eine registrierte Bedingung nennt — code, shortCode und codeDescription dieser Bedingung, wobei der Kurzcode dort in einem eigenen Feld reist. Sie reist in der einen Veröffentlichung, die die Hinweise trägt, die der Lauf vor seinem Anhalten ausgelöst hat, und ersetzt die Ebene daher so wie diese: Der nächste Lauf der Release, der rendert, veröffentlicht die Ebene ohne sie, und das Dokument, an dem sie stand, wird leer veröffentlicht, was sie aus Ihrer Problemansicht entfernt.
Wohin eine Ablehnung zeigt, ist das, was die Ablehnung selbst nennt, und nicht feiner. Die Prüfungen einer Workload beurteilen das Dokument, das ihr Template erzeugt hat, und ein Template kann Zeilen schreiben, die kein Autor geschrieben hat — eine Schleife, eine Bedingung, einen aus einer Datei oder Bibliothek importierten Text —, sodass eine Zeile der gerenderten Workload keiner Zeile des Recipe entspricht. Eine Ablehnung zu einer Workload wird daher auf den Schlüssel workload des Recipe gesetzt, und die Pfade, die sie innerhalb des gerenderten Dokuments nennt, bleiben in ihrer Meldung. Eine fehlschlagende Assertion wird auf ihren eigenen Schlüssel unter assertions im Recipe oder FeatureRecipe gesetzt, das sie deklariert; eine Assertion, die eine Component oder ein Feature deklariert, wird ausgelöst, bevor ein Dokument zum Benennen vorliegt, und wird auf den Schlüssel kind: des Aggregate gesetzt. Eine Ablehnung aus einem Schritt, der ein Dokument, aber keinen Schlüssel nennt, wird auf den Schlüssel kind: dieses Dokuments gesetzt.
Eine Ablehnung, die mehrere Befunde vereint, wird Befund für Befund veröffentlicht. Die Komposition des Graphen, mit dem das Rendering arbeitet, lehnt mit jeder gefundenen Verletzung in einer einzigen Ablehnung ab — ein Eintrag, der ein Ziel nennt, dem nichts entspricht, zwei Verbindungen einer Komponente mit demselben Alias — und die Kommandozeile gibt jede als eigene Diagnose unter eigener Überschrift aus. Hier ist jede ein eigener Eintrag auf der Ebene aggrega-build, an dem Dokument und an dem Schlüssel, den dieser Befund nennt — die Release, wo die Release ihn geschrieben hat, das Aggregate, wo das Aggregate es tat —, in eigenen Worten und mit eigenen Codes. Die message der Antwort trägt jeden Befund, und ihr data nennt, wohin der erste zeigt.
Ein Wert, den ein Autor als sensibel deklariert hat, wird hier genau so zurückgehalten, wie die Kommandozeile ihn zurückhält. Der Text der Ablehnung ist der Text, den der Compiler ausgelöst hat, nichts auf dieser Oberfläche formuliert ihn um, und der Compiler hält einen deklarierten Wert dort zurück, wo die Ablehnung ausgelöst wird — <redacted> an seiner Stelle —, sodass diese Antwort, dieser Eintrag und das Terminal ihn mit denselben Worten tragen; was eine Ablehnung über einen deklarierten Wert sagt erklärt, wie, und welche Ablehnungen außerhalb davon liegen.
Eine Ablehnung durch eine Prüfung, die vor dem Rendering läuft, ist nicht dies. Die oben aufgeführten Prüfungen antworten so, wie Was ein abgelehnter Lauf Ihnen trotzdem mitteilt beschreibt. Eine Assertion, die eine Component oder ein Feature deklariert, und eine Ablehnung über den komponierten Graphen liegen dazwischen: Jede wird vor dem Rendering ausgelöst, von jeder Anfrage, die den Graphen einer Release auflöst, sodass aggrega/irGraph sie auch bei ausgeschalteter Rendering-Phase wie oben beantwortet und veröffentlicht; aggrega/releaseClosure, aggrega/attachCandidates und aggrega/attachmentContainer, nach einem Graphknoten gefragt, sowie aggrega/connectionAtPosition beantworten sie mit demselben Envelope und veröffentlichen nichts, weil sie keine Problemansicht besitzen.
Fehlercodes
Antworten verwenden die Standard-Fehlercodes von JSON-RPC sowie einen anwendungsspezifischen Bereich im 1xxx-Band. Ein Editor-Client kann anhand des Codes verzweigen, ohne die Meldung zu parsen.
1001file-not-validated (Datei nicht validiert) — der Daemon hält für die Datei in ihrem jetzigen Stand nichts, woraus die Anfrage beantwortet werden kann: kein Parse-Ergebnis davon oder, füraggrega/diagnostics, kein Parse-Ergebnis davon oder nichts für die Datei Gehaltenes, das die Antwort einer Validierung für den Text ist, den der Daemon jetzt hält. Senden Sieaggrega/validatedafür und fragen Sie erneut.1003lockfile-absent (Lockfile fehlt) — die Release, die die Anfrage nennt, hat kein Lockfile, und die angeforderte Operation benötigt eines.1004entity-not-resolvable (Entität nicht auflösbar) — der Name passte zu keiner Entität in irgendeiner Katalogebene, auch nicht in der Release, die die Anfrage nennt; oder die als Name gesendete Registry-Referenz konnte nicht als Entität gelesen werden, und die Meldung nennt die Bedingung, die den Grund angibt; oder das Lockfile der Release ist ein Link, der aus dem Workspace hinausführt, was abgelehnt wird, bevor irgendetwas es liest, wobeidatadas Lockfile und die Release nennt und die Meldung mit dem Kurzcode der Bedingung beginnt,E0321— siehe die Workspace-Grenze.1005shutting-down (wird heruntergefahren) — der Daemon leert sich nach einer Shutdown-Benachrichtigung und lehnt neue Anfragen ab. Wiederholen Sie nicht gegen denselben Unterprozess.1006validation-in-flight (Validierung läuft) — eine Validierung der Datei läuft und wurde nicht innerhalb des Zeitbudgets fertig, das die wartende Anfrage ihr eingeräumt hat. Fragen Sie in Kürze erneut und senden Sie nichts.
1002 ist nicht vergeben und steht für die nächste Bedingung zur Verfügung, die einen Code benötigt.
File-not-validated und validation-in-flight melden entgegengesetzte Zustände, und auch die jeweils erforderliche Aktion ist entgegengesetzt. File-not-validated bedeutet, dass der Daemon für die Datei in ihrem jetzigen Stand nichts hält, woraus die Anfrage beantwortet werden kann — kein Parse-Ergebnis davon oder, für aggrega/diagnostics, kein Parse-Ergebnis davon oder nichts für die Datei Gehaltenes, das die Antwort einer Validierung für den Text ist, den der Daemon jetzt hält: Senden Sie aggrega/validate und fragen Sie erneut. Eine mittendrin abgebrochene Validierung hinterlässt eine Datei in diesem Zustand, weil sie nichts speichert und das, was eine frühere Validierung über einen anderen Text gefunden hat, keine Antwort für den Text ist, den der Daemon jetzt hält; eine frühere Antwort bleibt gültig, solange der Text derjenige ist, den sie geprüft hat. Befunde, die der Daemon über eine Datei übermittelt, die er selbst von der Festplatte gelesen hat — ein abgewichenes Lockfile, ein Release, das sich nicht laden lässt —, sind keine Validierung des Textes, den Sie halten, und beantworten diese Anfrage daher ebenfalls nicht. Auch zwei kurz nacheinander gesendete Validierungen unterschiedlicher Texte können Sie in diesen Zustand bringen, wenn diejenige, deren Text der Daemon behalten hat, zuerst fertig wurde: Die Anfrage wird abgelehnt, obwohl dieser Text geprüft wurde, und eine erneute Validierung beantwortet sie. Es ist in Bezug auf das Parse-Ergebnis statt auf die Datei formuliert, weil sich ein Puffer, den kein Parser lesen wird, genau in dieser Lage befindet — die Validierung lief und meldete, was sie fand, und es gibt immer noch kein Parse-Ergebnis, aus dem geantwortet werden kann. Validation-in-flight bedeutet, dass eine Validierung davon läuft und nicht innerhalb des Zeitbudgets fertig wurde, das die wartende Anfrage ihr eingeräumt hat: Fragen Sie in Kürze erneut und senden Sie nichts, denn der benötigte Zustand ist bereits unterwegs, und eine zweite Validierung würde nur Arbeit hinzufügen. Wer die beiden als eine Bedingung liest, verleitet einen Client dazu, eine Validierung genau in dem Fall zu senden, in dem das der falsche Schritt ist. Die beiden Bänder bedeuten für einen Client Verschiedenes: Ein 1xxx-Code nennt einen Zustand des Workspace, auf den der Benutzer reagieren kann — die Datei validieren, das Lockfile erzeugen —, während ein Standardcode wie invalid-params eine fehlerhafte Anfrage nennt, die der Client korrigiert und nicht der Benutzer. Ein release-Wert, der vorhanden, aber fehlerhaft ist — absolut oder außerhalb der Workspace-Wurzel aufgelöst —, fällt in das zweite Band: Nicht der Workspace ist in einem Zustand, den der Benutzer reparieren muss, sondern die Anfrage. release wegzulassen fällt in keines der Bänder, weil es überhaupt kein Fehler ist; es wählt die engere der beiden Antworten, die unter Live-Validierung beschrieben sind.
Ein Fehler kann ein data-Objekt tragen, und jeder Schlüssel darin nennt genau eine Sache und nur diese. file ist das Quelldokument, um das es beim Fehler geht — das gerade validierte Dokument, die Release, deren Laden fehlschlug, das Workspace-Dokument, das einen Namen deklariert, den nichts aufgelöst hat, oder das Dokument, auf das eine beim Rendering ausgelöste Ablehnung zeigt —, und es ist das, innerhalb dessen begleitende line und column eine Position angeben. Diese beiden sind ihrerseits optional: Ein Fehler, der ein ganzes Dokument betrifft, trägt nur file. lockfile ist ein Lockfile. release ist die Release, um die es beim Fehler geht, so geschrieben, wie die Anfrage sie genannt hat, damit ein Client aggrega pull --release <release> zusammensetzen kann, ohne es aus der Meldung herauszuparsen. unreachable besagt, dass die Registry, die eine abgelehnte Anfrage nannte, nicht erreicht werden konnte: Eine abgelehnte Index-Aktualisierung, die eine Registry nennt, trägt es, aus dem Fehler selbst gelesen, und eine Registry, die geantwortet hat, lässt es weg. Jeder Schlüssel ist optional und nur vorhanden, wenn der Daemon diesen Wert zur Hand hat; keiner steht für einen anderen, sodass das, worauf ein Schlüssel zeigt, nie vom Code daneben abhängt.
code und shortCode in data nennen die Bedingung, die eine Ablehnung meldet, bei jeder Ablehnung, die eine registrierte meldet, unabhängig von ihrem numerischen Code: der beschreibende Code, anhand dessen ein Programm verzweigt, und der Kurzcode, den ein Mensch zitiert — dieselben zwei Bezeichner unter denselben Namen, die ein Diagnoseeintrag für dieselbe Bedingung trägt, und aufgeführt in der Tabelle aller Bedingungen. Verzweigen Sie anhand von code. Der numerische Code nennt den Zustand der Anfrage und bleibt für viele Bedingungen derselbe — ein Build, der abgelehnt wird, weil ein Katalog-Link hinausführt, und ein Build, der abgelehnt wird, weil ein Name sich zu nichts auflöst, sind beide 1004 —, und die Meldung ist Prosa, die umformuliert werden kann, sodass keines von beiden eine Bedingung von einer anderen unterscheidet. Invalid-params ist ein solcher geteilter Code: Eine Anfrage, die einen Workspace nennt, dessen Konfigurationsdatei aus ihm hinausführt, löst ihn ebenfalls aus, und dort besagt read-leads-out-of-workspace, dass der Fehler im Aufbau des Workspace liegt, den ein Mensch repariert, und nicht in der Anfrage. Eine Ablehnung, die keine registrierte Bedingung meldet, trägt keinen der beiden Schlüssel, und die beiden sind entweder zusammen vorhanden oder gar nicht. Die Meldung einer Ablehnung, die eine Bedingung nennt, beginnt einmal mit ihrem Kurzcode, E0321: …, in der Form, der ein Mensch beim Lesen bei jeder solchen Ablehnung begegnet; eine Ablehnung, deren Meldung bereits mit einem eingeklammerten Kopf beginnt, der den Code trägt — der einzeilige Bericht über ein Katalogdokument, das das Laden abgelehnt hat —, erhält ihn nicht noch einmal.
Der Bericht darüber, wie die Release-Kaskade des Workspace abgelaufen ist, reist in der Antwort auf aggrega/activeRelease, in deren Feld trace, statt in einem Fehler: Ein Workspace, der auf keine Release zeigt, ist ein gewöhnlicher Zustand und keine fehlgeschlagene Anfrage. Es ist Diagnoseprosa, geschrieben, damit ein Mensch sie liest, keine zu parsende Struktur. Zeigen Sie sie so an, wie sie ist — schreiben Sie sie in ein Log oder in ein Panel, das der Benutzer öffnen kann —, und gleichen Sie keine Muster gegen sie ab, entnehmen Sie ihr keine Werte und verzweigen Sie nicht anhand der Bezeichnungen, die sie verwendet: Ihr Wortlaut, ihr Aufbau und diese Bezeichnungen folgen der Kaskade selbst und ändern sich, wann immer sich die Kaskade ändert. Ein Client, der den Text durchreicht, funktioniert über eine solche Änderung hinweg weiter; einer, der seine Form gelernt hat, bricht daran.
Siehe auch
- ../schema/other/serve-wire.md — die Nachrichtenformen, die dieses Protokoll austauscht, aus dem veröffentlichten Schema generiert: das Parameterobjekt jeder Methode, jedes Ergebnis und jede Benachrichtigungs-Payload, Feld für Feld.
- ./aggrega-build.md — der Build-Befehl, dessen Compiler-Pipeline, Prüfungen und Abhängigkeitsauflösung auch
aggrega/buildausführt, sodass die beiden Oberflächen einen einzigen Ausgabebaum schreiben statt zwei. - ./aggrega-version.md — der Versionsbefehl, mit dem eine Editor-Erweiterung die Kompatibilität des Daemons prüft.
- ./aggrega-pull.md — das Lockfile, das die Drift-Erkennung des Daemons liest.
- ./aggrega-lint.md — die Veröffentlichungskonventionen, die der Daemon auf Anfrage meldet, und bei jeder Validierung, sobald
serve.lint_on_validateeingeschaltet ist.
Übersicht
aggrega serve [flags]Beschreibung
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.Flags
| Flag | Standard | Beschreibung |
|---|---|---|
--build-on-inspect | false | Führt beim Inspizieren eines IR-Graphen die Phase des Artefakt-Renderings aus, sodass die Hinweise, die aggrega build beim Rendern meldet, auch als Editor-Probleme erscheinen. Fügt keine der Prüfungen hinzu, bei denen ein Build abbricht. Es wird nichts auf die Festplatte geschrieben: keine gerenderten Artefakte, kein Ausgabeverzeichnis, kein Lockfile. Standardmäßig aus, entsprechend aggrega inspect, das ebenfalls keinen solchen Hinweis meldet. Wenn gesetzt, überschreibt es den Konfigurationsschlüssel serve.build_on_inspect. |