aggrega validate
aggrega validate prüft die Korrektheit — Schema, Säulenstruktur, Auflösung dokumentübergreifender Referenzen, extends-Ketten, die Eingabeart-Fähigkeit des Providers und (bei einer rendernden Entität), dass sie tatsächlich rendert. Es hat drei Modi, ausgewählt durch sein Argument, die dieselbe Korrektheitsdisziplin auf drei Ebenen anwenden: den gesamten Katalog (kein Argument), die Abhängigkeits-Closure einer einzelnen Release (--release) und die Datei einer Entität (ein Entitätspfad). Jede Ebene beantwortet dieselbe Frage — „Ist dieser Inhalt korrekt?“ — über einen anderen Ausschnitt des Katalogs.
Korrektheit ist etwas anderes als Konventionen. aggrega validate fragt, ob Inhalt wohlgeformt ist und kompilieren würde; aggrega lint fragt, ob Inhalt der Veröffentlichungsdisziplin des Katalogs folgt (Benennung, Ausrichtung an Kategorieverzeichnissen, Umfang der Versionserhöhung und der Rest). Die beiden Befehle spiegeln gegenseitig ihre drei Ebenen, sodass Sie jede der beiden Dimensionen in der Granularität prüfen können, die Sie benötigen.
aggrega validate schreibt nichts auf die Festplatte und liest keinen Laufzeitzustand. Es führt dieselbe Auflösung und Validierung aus wie ein Build und hält vor dem Rendering an (bzw. isoliert es bei einer einzelnen Entität).
Ein Entitätspfad kann positionsbezogen angegeben werden. --release neben einem Entitätspfad wählt nicht die Release-Ebene: Die Entität wird weiterhin für sich geprüft, in den Begriffen dieser Release — siehe Eine Entität in den Begriffen einer Release prüfen.
Korrektheit des gesamten Katalogs (kein Argument)
aggrega validate ohne Argument lädt jede Katalog-Entität unter den konfigurierten Katalogverzeichnissen und prüft sie durchgängig. Bevor es etwas lädt, liest es jede YAML-Datei darunter, und ein Aggrega-Dokument darunter, das es nicht laden kann, hält den Lauf an, wie unten beschrieben. Dann:
- Struktur der Schema-Säulen — der
spec.schema:-Block jeder Component und jedes Feature wird expandiert und validiert (dieselbe Schema-Säulen-Prüfung, die der Build anwendet), einschließlich der Expansion der Kompaktform. - Auflösung dokumentübergreifender Referenzen —
$ref- und$import-Referenzen auf Einträge einer SchemaLibrary werden aufgelöst, und eine SchemaLibrary, die sich nicht auflösen lässt oder anderweitig ungültig ist, wird abgelehnt. extends-Ketten — jede Entität, dieextendsdeklariert, wird gegen ihre übergeordnete Entität aufgelöst, und die zusammengeführte Form aus übergeordneter und untergeordneter Entität wird geprüft. Eine übergeordnete Entität, die die Katalogverzeichnisse nicht enthalten, wird dort gelesen, wo ein Build sie liest: aus dem Artefakt-Cache, unter dem Pin, den das Lockfile eines Release für sie verzeichnet — den Lockfiles der Releases, für die der Durchlauf ausgeführt wird, oder dem jedes Release, das der Workspace enthält, wenn er in einem einzigen Durchlauf validiert wird. Eine in einer Registry veröffentlichte Basis wird daher validiert, sobaldaggrega pullsie abgerufen und gepinnt hat, und eine übergeordnete Entität, die keiner von beiden enthält, bricht den Lauf ab und nenntaggrega pull --release <release>. Es wird nichts abgerufen.- Deklarierte Selektoren — jeder Label-Selektor, den ein Component- oder Feature-Dokument an einem Abhängigkeits-Socket unter
spec.usesSchemaoder an einem Anhang-Slot unterspec.featuresSchemadeklariert — bei einer Component einschließlich der Slots, die ein Socket deklariert —, wird gegen die Selektorgrammatik gelesen, unabhängig davon, ob etwas den Socket verdrahtet oder den Slot füllt. Siehe deklarierte Selektoren. - OCI-Ortskollisionen — zwei verschiedene Katalog-Identitäten, die an denselben Registry-Ort veröffentlichen würden, werden lautstark abgelehnt, sodass ein Build niemals stillschweigend die veröffentlichten Bytes einer Entität mit denen einer anderen überschreibt.
- Eingabeart-Fähigkeit des Providers — ein Recipe oder FeatureRecipe, das einen
workload:-Block deklariert, der an einen Provider gebunden ist, der nicht synthetisieren kann, wird als Fehler gemeldet, weil es niemals gebaut werden kann.
Dies ist das katalogweite Gegenstück zur Validierung pro Release eines Builds — die Stelle, an der eine defekte Katalog-Entität sichtbar werden soll, bevor ein Release sie erreicht. Es hält lautstark an bei einem Aggrega-Dokument, das es nicht laden kann, und bei jeder Verletzung der Schema-Säulen, jeder nicht auflösbaren oder ungültigen Bibliothek, jedem Fehler bei der extends-Auflösung, jedem deklarierten Selektor, den die Grammatik ablehnt, jeder Ortskollision und jedem Eingabeart-Fähigkeitsfehler. Befunde zu Überschneidungen von Schema-Säulen und zur Einengung beim Erweitern sowie jedes x-aggrega-*-Schlüsselwort, das eine Component oder ein Feature inline in ihrem Schemainhalt verfasst, sind beratende notice:-Zeilen, die den Exit-Code nie ändern.
Ein Aggrega-Dokument, das nicht geladen werden kann, hält den Lauf an. Eine YAML-Datei unter einem Katalogverzeichnis ist ein Aggrega-Dokument, wenn eine ihrer Zeilen ohne Einrückung mit apiVersion: und einem Wert beginnt, der mit aggrega.ai/ anfängt, in Anführungszeichen oder nicht. Ein solches Dokument, das nicht gelesen werden kann, dessen YAML sich nicht parsen lässt oder dessen kind oder metadata nicht die Form hat, die der Umschlag einer Entität annimmt — etwa ein als Liste geschriebenes metadata —, hält den Lauf mit E0175 an, sobald die Verzeichnisse gelesen wurden, und nennt jede solche Datei mit dem Grund, den das Lesen oder der Parser angegeben hat; es wird nichts geprüft und keine catalog validation passed-Zeile ausgegeben. Ein Dokument, das geladen wird und einen kind deklariert, den kein Katalog enthält — etwa ein falsch geschriebenes Componnent oder gar kein kind —, hält denselben Lauf mit E0371 an und wird neben jenen mit der Art genannt, die es deklariert; ein Manifest, ein Release und eine Workload, die ein Recipe aus seinem eigenen Verzeichnis importiert, werden übergangen. Jedes andere YAML — die Templates eines Helm-Charts, die sich erst nach dem Rendern parsen lassen, Chart-Werte, Workflow-Definitionen — wird übergangen.
Welche Verzeichnisse es liest, hängt von der Form des Workspace ab:
-
Ein Workspace, dessen Konfiguration keinem Release eigene Katalogverzeichnisse gibt, wird einmal validiert, über seinen Suchstapel: die
--catalog-Verzeichnisse, dannworkspace.catalog_dirs, dann das Verzeichniscatalogim Workspace-Stammverzeichnis, sofern es eines gibt. -
Ein Workspace, der unter
workspace.releasesReleases benennt, kann einen Katalog in mehreren Varianten nebeneinander halten, die jeweils von ihrem eigenen Release gelesen werden, und sie alle auf einmal zu laden, würde jede Variante in einen einzigen Katalog legen, wobei die Entität einer Variante die einer anderen überdeckt. Daher wird er einmal für jedes Release validiert, das der Workspace enthält, über die Verzeichnisse, die dieses Release liest, mit den--catalog-Verzeichnissen zuerst in jedem Durchlauf; ein Release, das die Konfiguration nicht benennt, liest die Liste des Workspace. Jeder Durchlauf wird unter einer Zeile gemeldet, die sein Release und die gelesenen Verzeichnisse nennt, gefolgt vom Ergebnis dieses Durchlaufs:Release release-compose.yaml reads catalog-composecatalog validation passed (schema-pillar + library + extends + oci-location)Release release-helm-synth.yaml reads catalog-helm-synthcatalog validation passed (schema-pillar + library + extends + oci-location)Releases, die genau dieselben Verzeichnisse lesen, teilen sich einen Durchlauf, der jedes von ihnen nennt. Ein Release, das kein Verzeichnis liest — sein Eintrag schreibt
catalog_dirs: []—, wird als ohne Prüfgegenstand gemeldet, und die anderen Durchläufe laufen wie gewohnt. Jeder Durchlauf wird gemeldet, unabhängig davon, was ein früherer gefunden hat, da eine defekte Entität in einer Variante nichts über eine andere aussagt, und der Befehl schlägt fehl, wenn irgendein Durchlauf fehlschlägt, und nennt die Releases, deren Verzeichnisse fehlgeschlagen sind. Die Releases, die ein Workspace enthält, sind seine Release-Dokumente — YAML-Dateien, derenkindReleaseist, irgendwo unter dem Workspace-Stammverzeichnis außerhalb versteckter Verzeichnisse und außerhalb vonnode_modules,vendorunddist.
Ein Lauf, der in keinem Durchlauf etwas zu lesen hat, wird abgelehnt, statt als sauberer Katalog gemeldet zu werden: Legen Sie die Entitäten unter catalog/ ab, übergeben Sie --catalog oder setzen Sie workspace.catalog_dirs — oder, in einem Workspace, der Releases benennt, die eigenen catalog_dirs eines Release unter workspace.releases. Er zählt nie implizit das aktuelle Arbeitsverzeichnis auf und zieht daher nie fremde Verzeichnisbäume hinein.
Das validate-Tool von aggrega mcp validiert, wenn es nach dem gesamten Katalog gefragt wird, dieselben Durchläufe; in einem Workspace, der Releases benennt, enthält seine Antwort jeden davon unter passes — die Releases, die gelesenen Verzeichnisse und das eigene Urteil dieses Durchlaufs — neben dem Urteil über alle zusammen.
Eine Bibliothek, die nur der Artefakt-Cache enthält
Der Artefakt-Cache enthält, was ein Abruf dort abgelegt hat, und eine zwischengespeicherte SchemaLibrary zählt nur dann als Kataloginhalt, wenn ein Eintrag in der Lockfile eines Release für ihren Digest bürgt — siehe Was der Cache ist und was nicht. Wenn sich eine $ref: zu nichts auflöst, während der Cache eine Bibliothek enthält, die kein Lockfile-Eintrag pinnt und die kein von der Prüfung gelesenes Katalogverzeichnis liefert, folgt auf den Bericht eine remediation:-Zeile, die jede solche Bibliothek nennt und die Maßnahme, die für den fehlgeschlagenen Umfang funktioniert:
- Ohne Argument sowie mit einem Entitätspfad, ob
--releaseangegeben ist oder nicht, liest validate Bibliotheken nur aus Katalogverzeichnissen, nie über einen Lockfile-Eintrag, sodass ein verzeichneter Eintrag sein Urteil nicht ändern würde. Die Zeile sagt dies und verweist darauf, die Bibliothek unter einem Katalogverzeichnis zu verfassen, oder aufaggrega pull --release <release>gefolgt vonaggrega validate --release <release>, das das Release gegen die Bibliotheken prüft, die seine Lockfile pinnt. - Mit
--releaseallein liest validate die Lockfile des Release, daher nennt die Zeileaggrega pull --release <release>, das die Bibliothek auflöst und ihren Eintrag verzeichnet, oder das Verfassen der Bibliothek unter einem Katalogverzeichnis.
Die Zeile ändert weder das Urteil noch den Exit-Code.
Deklarierte Selektoren
Eine Component oder ein Feature schränkt mit Label-Selektoren ein, was an ihre Abhängigkeits-Sockets verdrahtet werden und was ihre Anhang-Slots füllen darf — der selector: jedes Eintrags in spec.usesSchema und jedes Eintrags in spec.featuresSchema und bei einer Component der selector: jedes Slots, den ein Socket unter seinem eigenen featuresSchema deklariert. Ein Build liest einen Selektor nur dort, wo etwas ihn erreicht: eine durch den Socket gezogene Kante, ein Anhang, der den Slot füllt. Daher lesen der Geltungsbereich des gesamten Katalogs und der Geltungsbereich der einzelnen Entität jeden Selektor, den ein Component- oder Feature-Dokument deklariert, unabhängig davon, ob etwas den Socket verdrahtet oder den Slot füllt, und ein Selektor, den die Grammatik ablehnt — eine Werteliste ohne schließende Klammer, ein doppeltes Komma, ein Schlüssel, der = oder ! enthält —, lässt die Prüfung fehlschlagen. Die Grammatik ist die in der String-Grammatik erläuterte.
Die Ablehnung ist die, die ein Build meldet, wenn er denselben Selektor erreicht, unter demselben Code und mit denselben Worten: E0007 für den Selektor eines Sockets und E0008 für den eines Slots, mit Angabe des Selektors, des Sockets oder Slots, der ihn deklariert, und des Grundes, warum die Grammatik ihn nicht lesen konnte. Sie wird als Katalogfehler an der Datei der Entität erfasst:
selector violation (
"<selector>", declared on socket"<socket>", which could not be evaluated:"<why it could not be read>"). Correct the selector on the socket’s declaration in the component type’s usesSchema. (Selektorverletzung: ein an einem Socket deklarierter Selektor, der nicht ausgewertet werden konnte. Korrigieren Sie den Selektor in der Deklaration des Sockets im usesSchema des Komponententyps.)
Jedes Dokument wird so gelesen, wie sein Autor es geschrieben hat, daher wird ein Selektor, den eine Basisentität deklariert, einmal gemeldet, an der eigenen Datei der Basis, statt einmal für jede Entität, die sie erweitert. appliesTo und appliesToAnyOf eines Feature werden hier nicht gelesen: Sie werden überall dort gelesen, wo ein Anhang des Feature ausgewertet wird.
Der Geltungsbereich des gesamten Katalogs meldet jeden abgelehnten Selektor in einer eigenen Zeile selector: und schlägt mit ihrer Anzahl fehl; der Geltungsbereich der einzelnen Entität meldet sie als Fehlschlag seiner Formstufe — mit oder ohne --release neben dem Entitätspfad, da diese Form der Geltungsbereich der einzelnen Entität ist, ausgeführt in den Begriffen eines Release (siehe eine Entität in den Begriffen eines Release prüfen). --release allein, das den Abhängigkeitsabschluss eines Release validiert, und ein Build lesen einen Selektor nur dort, wo eine Kante oder eine Füllung ihn erreicht, und halten dort bei ihm an.
Auf ein Release begrenzte Korrektheit (--release)
aggrega validate --release <release-path> validiert genau die Entitäten, die die aufgelösten Abhängigkeiten eines einzelnen Release erreichen, statt des gesamten Katalogs oder einer einzelnen Entität. Es berechnet die Hülle über dieselbe Mechanik, die ein Build verwendet, sodass die geprüften Entitäten genau die sind, die ein Build dieses Release auflösen würde, und über diese Hülle:
- löst es die auf die Hülle begrenzten
extends-Ketten auf und schlägt bei einem Auflösungsfehler fehl; - validiert es die Schema-Säulen jeder aufgelösten Entität (auf die Hülle begrenzt) und schlägt bei einem Schema-Säulen-Fehler fehl;
- führt es dieselbe Wertekonformitätsprüfung vor dem Rendern aus, die ein Build ausführt — es löst die Parameter des Release in die verfassten Werte auf (sodass ein
{{ .parameters.* }}-Wert als aufgelöst geprüft wird, nicht als Template) und validiert das Ergebnis gegen die zusammengesetzten Schemas der Hülle, einschließlich der Konformität gegen das zusammengesetzte Schema aus Eltern- und Kindelement für eine Entität mitextends. Ein Wert, der sein Schema verletzt, schlägt mit einem Exit-Code ungleich null fehl; - wertet es jede Recipe- und FeatureRecipe-Assertion gegen die Werte aus, zu denen das Release aufgelöst wird, so wie ein Build sie vor dem Rendern auswertet: Das Recipe jeder Komponente wird so gebunden, wie das Manifest es zuordnet, seine
localsundprovideswerden aufgelöst, und die erste fehlschlagende Assertion — eine, diefailaufruft, oder eine, deren Template an einem Schlüssel anhält, den es nicht findet — lässt die Validierung mit der Bedingung und dem Satz fehlschlagen, mit denen ein Build anhält. Auch einlocals- oderprovides-Template, das nicht ausgewertet werden kann, lässt sie fehlschlagen, wie es einen Build fehlschlagen lässt. Der Provider, über den jedes Recipe rendert, wird nach dem Namen gefragt, den er den Ressourcen dieser Komponente gibt, so wie ein Build ihn fragt, weil dieprovideseines Recipe diesen Namen lesen können; gerendert wird nichts. Diese Assertions werden nur ausgewertet, wenn nichts von dem oben Genannten bereits fehlgeschlagen ist, sodass ein Release den frühesten Fehler meldet, an dem ein Build anhalten würde; - macht es Befunde zu Überschneidungen von Schema-Säulen und zur Einengung beim Erweitern als informative
notice:-Zeilen sichtbar, die den Exit-Code nie ändern; - zeigt es jedes
x-aggrega-*-Schlüsselwort, das eine von ihm gelesene Entität inline in ihrem Schemainhalt verfasst, alswarning:-Zeile an, einmal pro Entität, so wie ein Build es anzeigt — auch dies ändert den Exit-Code nie.
Das macht --release zu einer echten Prüfung vor dem Build: Es fängt ab, was ein Build ablehnen würde, noch vor dem Build — die Abhängigkeitsvalidierung des Builds ohne das Rendern. Es rendert nicht und löst keinen Netzwerk-Pull aus: Die Hülle wird aus dem lokalen Katalog aufgelöst (und aus den Lockfile-Pins des Release, sofern vorhanden); eine an eine Registry gepinnte Abhängigkeitsmenge, die ein Lockfile benötigt, liefert einen ehrlichen Fehler wegen nicht auflösbarer Referenz, statt etwas abzurufen. Einengung wird als Hinweis gemeldet, nie erzwungen.
Ein Lockfile, das nicht mehr zu dem passt, wozu das Release aufgelöst wird, lässt die Validierung mit dem Abbruch scheitern, den aggrega build ausgibt. Wo ein Lockfile neben dem Release liegt, gleicht --release es mit dem ab, wozu das Release aufgelöst wird, mit dem Drift-Vergleich, den ein Build vor dem Rendern ausführt, sobald die Abhängigkeiten des Release aufgelöst sind und bevor eine der obigen Prüfungen läuft. Ein Lockfile, von dem eine gepinnte Entität, eine Bibliothek, ein Plug-in oder die Release-Datei selbst abgewichen ist, stoppt die Validierung mit der E0130-Ablehnung des Builds — jeder abgewichene Eintrag, dann das aggrega pull --release <release>, das sie behebt — und einem Exit-Code ungleich null, sodass eine Validierung nie ein Lockfile durchgehen lässt, das der Build als abgewichen ablehnt. Ohne Argument und mit einem Entitätspfad ist validate an kein Lockfile gebunden: Die Prüfung des gesamten Katalogs liest Lockfile-Pins nur, um eine übergeordnete extends-Entität zu finden, und die Prüfung einer einzelnen Entität liest kein Lockfile.
Da es dieselben Prüfungen wie ein Build ausführt, führt es auch dieselben angehängten Gate-Plugins aus — und unterliegt daher demselben Verzeichnis vertrauenswürdiger Plugin-Identitäten wie ein Build. Ein Workspace, der ein Plugin anhängt, das ein Urteil aus Annahme oder Ablehnung zurückgibt, hat ein Plugin-Vertrauensverzeichnis neben seinem Release, und --release vergleicht die Konfiguration damit, bevor eines dieser Plugins läuft: Ein verzeichnetes Gate, das die Konfiguration nicht mehr anhängt, hält die Validierung an, und ein aus dem von aggrega pull befüllten Cache aufgelöstes Plugin, dessen Artefakt nicht das verzeichnete ist, wird abgelehnt statt ausgeführt. Ein Workspace, der nichts verzeichnet hat, hat kein Verzeichnis, was für diesen Vergleich nichts ändert. --release nennt außerdem jede Rücknahme, die gegen das verzeichnet ist, wovon das Release abhängt, auf der Standardfehlerausgabe als deprecation:-Zeile in den Worten, die aggrega build ausgibt: eine Markierung, die die Lockfile gegen eine gepinnte Referenz verzeichnet, ebenso wie eine, die das Vertrauensverzeichnis gegen ein in einer Urteilsrolle angehängtes Plugin verzeichnet. Eine Rücknahme ändert weder das Urteil noch den Exit-Code, und ein vorhandenes Vertrauensverzeichnis, das nicht gelesen werden kann, hält die Validierung an, statt als eines durchzugehen, das nichts verzeichnet.
Ein aus dem Cache gelesenes Plugin unterliegt außerdem der Signatur, die sein Eintrag verzeichnet, so wie ein Build es daran bindet, und zwar in dem Moment, in dem es geladen wird. Wo sein Eintrag eine verifizierte Signatur verzeichnet, wird das Signaturmaterial, das dieser Eintrag im Cache benennt, erneut geprüft, und ein Plugin, dessen Material fehlt oder abweicht, wird abgelehnt — ebenso eines, dessen Material für ein anderes Plugin als das gelesene erstellt wurde, so wie eine aus einem anderen Eintrag kopierte signature aussieht, unabhängig davon, was die Signaturanforderung sagt. Wo die Vertrauenskonfiguration des Workspace eine Signatur verlangt, wird ein aus dem Cache gelesenes Plugin, dessen Eintrag keine verzeichnet — oder für das das Verzeichnis keinen Eintrag enthält, ein gelöschtes Verzeichnis eingeschlossen —, ebenfalls abgelehnt, unter denselben Einstellungen, unter denen aggrega pull es unsigniert ablehnen würde, sodass skip_signature_verification und eine advisory-Registry es laufen lassen. Eine Ablehnung lässt die Validierung fehlschlagen und wird unter ihren Diagnosen gemeldet, mit dem Namen des Plugins und aggrega pull --release <release>, dem Befehl, der seine Signatur bei seiner Registry verifiziert, sie verzeichnet und das benannte Bundle cacht, wobei eine gecachte Kopie neu geschrieben wird, die nicht mehr zu ihrem Digest passt; ein Plugin, das aus einem Ihrer Katalogverzeichnisse oder aus der Kopie im Compiler-Binary bereitgestellt wird, unterliegt der Anforderung nie. Die anderen beiden Geltungsbereiche unterliegen nichts davon: Sie lesen die Plugin-Anhänge des Workspace nicht, sodass in ihnen kein solches Plugin läuft.
Dasselbe gilt für die Plugins, die den Graphen verändern, statt ihn zu beurteilen. Ein label-transform- oder annotation-transform-Anhang formt, wie die gerenderte Ausgabe aussehen würde, daher pinnt das Lockfile sowohl seine Identität als auch die Quelldateien, die er liest — und --release führt diese Anhänge so aus, wie ein Build sie ausführt: aus dem Lockfile rekonstruiert, jeden an seinen verzeichneten Digest gebunden, und mit dem Quellinhalt, den das Lockfile enthält, statt der Datei auf der Festplatte. Zwei Folgen sollten Sie kennen, bevor Sie ihnen begegnen:
- Das Anhängen eines Transform-Plugins in
.aggrega-config.yamländert nicht, was--releasetut, bis Sie einen Pull ausführen. Das ist dieselbe Regel, der ein Build folgt, und aus demselben Grund: Die Menge der Anhänge ist eine bytebestimmende Eingabe, daher wird sie beim Pull übernommen und nicht in dem Moment, in dem sie bearbeitet wird. - Ein gecachtes Plugin, dessen Bytes nicht mehr zu dem im Lockfile verzeichneten Digest passen, wird abgelehnt, genau wie es während eines Builds der Fall wäre.
Hat das Release kein Lockfile, validiert --release trotzdem — es warnt, dass es die Identität eines Plugins nicht prüfen konnte, und nennt, was auszuführen ist, statt abzulehnen. Siehe Warnungen.
Den kompilierten Graphen zurückgeben
--ir-graph schreibt den von dieser Validierung aufgelösten Graphen als JSON auf die Standardausgabe, vor der Urteilszeile. Es ist additiv: Dieselben Prüfungen laufen, dieselben Diagnosen werden geschrieben, und der Exit-Code ist derselbe wie ohne. Der zurückgegebene Graph ist der, über den die Validierung ausgeführt wurde, daher kann er keine andere Auflösung beschreiben als die, über die das Urteil berichtet.
Es gilt nur für diesen Geltungsbereich — die Geltungsbereiche des gesamten Katalogs und der einzelnen Entität treiben ein synthetisiertes Harness statt eines Release an und lösen keinen Graphen auf —, und eine Anforderung an anderer Stelle wird abgelehnt, statt stillschweigend ignoriert zu werden. Hält der Lauf an, bevor der Graph aufgelöst ist, wird nichts auf die Standardausgabe geschrieben, und die eigenen Diagnosen des Befehls sagen, was ihn angehalten hat.
Beachten Sie das Flag daneben. --response-format legt fest, wie viel vom eigenen Bericht dieses Befehls geschrieben wird (detailed oder concise); --ir-graph fordert ein zweites Dokument neben diesem Bericht an. Das eine betrifft den Umfang, das andere den Gegenstand, und keines von beiden verändert das Urteil.
Werte, die ein Autor als sensibel deklariert hat, werden aus dem Graphen zurückgehalten — einschließlich der values und infra einer Verbindung, wo der Socket der konsumierenden Komponente ein Blatt als sensibel deklariert —, in der strukturierten Form, die unter aggrega inspect beschrieben ist. --unredacted neben --ir-graph gibt sie stattdessen aus, zu den Bedingungen, die aggrega inspect --unredacted nennt: Es erreicht den Graphen und nichts anderes, was dieser Befehl schreibt, und was immer die Ausgabe erreicht, enthält diese Werte dann im Klartext. Ohne --ir-graph übergeben, wird es abgelehnt, weil es nichts gäbe, was es offenlegen könnte.
Korrektheit einer einzelnen Entität (ein Entitätspfad)
aggrega validate <entity-path> prüft eine einzelne Katalog-Entitätsdatei. Es wendet eine gestufte Reihe von Prüfungen an und hält beim ersten blockierenden Fehler an, sodass ein Schemafehler lautstark sichtbar wird, bevor irgendeine Katalogarbeit beginnt:
- Platzhalter (jede Art) — ein Wert, den die Art verlangt und den die Datei als leeren String belässt. Alle werden auf einmal gemeldet, vor den anderen Prüfungen, jeweils mit dem, was sie annehmen; siehe noch ausstehende Platzhalter.
- Schema-Umschlag (jede Art) — genau die JSON-Schema-Prüfung pro Entität, die der Katalog-Loader an jeder Parse-Grenze ausführt.
- Form (jede Art) — die artspezifische strukturelle Validierung. Bei einer Component oder einem Feature gehört dazu, jeden Label-Selektor, den die Datei an einem Abhängigkeits-Socket oder einem Anhang-Slot deklariert, gegen die Selektorgrammatik zu lesen; siehe deklarierte Selektoren.
- Säulenstruktur (Component und Feature) — die
spec.schema:-Säulenprüfung, die die SchemaLibraries des Katalogs für die dokumentübergreifende$ref-Expansion verwendet.
Eine Component oder ein Feature endet hier: Schema-Umschlag, Form und Säulenstruktur. Eine einzelne Component hat keine verfassten values oder infra, die isoliert gerendert werden könnten, also gibt es nichts zu rendern — ihre Korrektheit ist durch die Schema- und Säulenstufen vollständig abgedeckt. Jedes x-aggrega-*-Schlüsselwort, das ihr Schemainhalt inline verfasst, wird unter den beratenden Hinweisen auf der Standardfehlerausgabe als warning:-Zeile gemeldet, die das Schlüsselwort nennt, die Stelle, an der es steht, und die deklarative Tabelle, die stattdessen zu verfassen ist; es ändert nie das Urteil oder den Exit-Code.
Ein Recipe wird zusätzlich isoliert gerendert. Das ist eine Facette der Korrektheit einer einzelnen Entität, nicht ihr Kern: Nachdem die Schema- und Formstufen bestanden sind, löst validate die implements-Component des Recipe aus dem Katalog auf, synthetisiert ein minimales Aggregate, Manifest und Release um eine einzelne Instanz dieser Component, die an das zu prüfende Recipe gebunden ist, und lässt die echte Kompilierungspipeline darüber laufen — zuerst Auflösung und Guards (mit übersprungenem Rendern), dann ein echtes Rendern der isolierten Ausgabe. Jeder erforderliche Wert und jedes erforderliche Infra-Feld ohne Standardwert wird mit einem Platzhalter seines deklarierten Typs gefüllt — die Werte im synthetisierten Aggregate, die Infra im synthetisierten Release —, und jeder andere Wert und jedes andere Infra-Feld erhält über den Resolver seinen Schema-Standardwert; das Release leitet die Instanz in eine synthetisierte Standard-Boundary und deklariert keine values: und keine Rechenressourcen, die das Aggregate nicht deklariert hat. Ein Platzhalter ist ein Wert, den die eigenen deklarierten Einschränkungen des Feldes akzeptieren: die Konstante oder der erste Wert, den ein enum aufführt, eine Zahl innerhalb seiner Grenzen, ein String seiner Länge und in seinem format, eine semantische Version, wo sein pattern eine verlangt, so viele Listenelemente, wie es verlangt, und jede Eigenschaft, die ein Objekt verlangt. Jedes andere pattern, eine validate:- oder when:-Bedingung, eine Komposition von Schemas und eine Einschränkung, welche Elemente eine Liste enthält, werden nicht herangezogen, sodass ein Feld, das sich auf eine davon stützt, seinen Platzhalter dennoch ablehnen kann; validate meldet diese Ablehnung dann in den eigenen Worten des Schemas. Die gerenderten Artefakte werden ausgegeben, damit ein Autor die isolierte Ausgabe sieht, bevor er die Entität in ein vollständiges Aggregate einbindet. Da ein Harness für eine einzelne Entität nur diese erforderlichen Felder füllt, keine Verbindung herstellt und kein Feature anhängt, kann ein Recipe, dessen Templates einen Wert lesen, den nur eine Verbindung oder ein angehängtes Feature liefert, nicht isoliert gerendert werden; validate meldet ein solches Rendern als nicht versucht statt als fehlgeschlagen. Eine Assertion, die fail aufruft, wird als Warnung gemeldet, statt die Prüfung fehlschlagen zu lassen — siehe eine fehlgeschlagene Assertion ist eine Warnung. Ein Rendern, das aus einem anderen Grund anhält, wurde nicht abgeschlossen, und validate meldet es mit der zugrunde liegenden Render-Diagnose bis hin zu dem Satz, der nennt, was es angehalten hat.
Ein Recipe, dessen source: abgerufen werden muss, wird überhaupt nicht gerendert, und bei einem Recipe, dessen Rendern anhält, während es einen Wert liest, den nur eine Verbindung oder ein angehängtes Feature liefert, wird dieses Rendern zurückgestellt — siehe unten was die Korrektheit einer einzelnen Entität nicht prüft.
Ein FeatureRecipe wird auf Schema und Form geprüft; sein Rendern wird übersprungen, weil ein FeatureRecipe nur gerendert wird, wenn es an eine Host-Komponente angehängt ist, und das Synthetisieren eines Hosts, der die Guards für ein beliebiges Feature besteht, wird nicht versucht.
Eine Entität im Kontext eines Release prüfen
Ein Workspace kann jedem Release eigene Katalogverzeichnisse geben — siehe Einem Release eigene Katalogverzeichnisse geben — und so eine Katalogvariante pro Release nebeneinander halten. Ein allein angegebener Entitätspfad wird über die eigenen Katalogverzeichnisse des Workspace geprüft, wo eine Referenz in eine dieser Varianten — die Component, die ein Recipe implementiert, eine SchemaLibrary, auf die eine Säule verweist — nicht gefunden wird. Geben Sie --release neben dem Entitätspfad an, und dieselben Prüfungen laufen im Kontext dieses Release: Die Referenzen der Entität werden über die Katalogverzeichnisse aufgelöst, die die Workspace-Konfiguration diesem Release gibt, mit allen vorangestellten --catalog, und das sind die Verzeichnisse, die ein Build dieses Release liest.
Das MariaDB + Adminer-Beispiel hält vier solche Varianten. Die Component seiner synth-Variante bezieht ihre Speichereinstellungen aus einer SchemaLibrary, die nur die synth- und die chart-Variante enthalten, daher wird sie im Kontext des Release validiert, das mit ihr baut:
$ aggrega validate catalog-helm-synth/component/mariadb.yaml --release release-helm-synth.yamlEntity: catalog-helm-synth/component/mariadb.yamlKind: ComponentSchema: validPillars: validund schlägt fehl, wobei sie die Bibliothek nennt, die sie nicht auflösen konnte, im Kontext eines Release, dessen Verzeichnisse sie nicht enthalten — --release release-compose.yaml oder gar kein --release in einem Workspace, der keine eigenen Katalogverzeichnisse aufführt.
Ein Recipe wird auf dieselbe Weise geprüft. Das Recipe der synth-Variante implementiert core/datastore/mariadb, das die eigenen Katalogverzeichnisse des Workspace nicht enthalten, daher schlägt es, allein angegeben, mit render: implements target "core/datastore/mariadb" not found in catalog fehl. Mit dem Release angegeben, das mit ihm baut, löst es die Component dieses Release auf und wird isoliert gerendert:
$ aggrega validate catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml --release release-helm-synth.yamlEntity: catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validAttachments: required attachment slots not checked (root_password) Validating a Recipe on its own places its Component in a build that attaches no Feature, so nothing exists to fill a required slot. Whether each of these slots is filled is checked when a Release that deploys the Component is built.Resolution: validRender: 3 artifact(s)gefolgt von den drei gerenderten Artefakten. Jede Variante dieses Beispiels deklariert core/datastore/mariadb, daher wird das Recipe im Kontext jedes seiner vier Releases validiert; im Kontext eines Release, dessen Katalogverzeichnisse keine solche Component enthalten, schlägt es fehl und nennt das Ziel, wie es ohne --release der Fall ist. Die Attachments:-Zeilen werden unter ein erforderlicher Anhangsslot oder ein Präsenzmandat erklärt.
Dies ist weiterhin der Geltungsbereich der einzelnen Entität. Die Prüfungen, der Bericht und der Exit-Code sind die, die dieser Abschnitt beschreibt — eine Component oder ein Feature mit einem Socket- oder Slot-Selektor, den die Grammatik ablehnt, schlägt hier genauso fehl wie ohne --release, siehe deklarierte Selektoren —, und es wird keine Hülle validiert: --release nennt das Release, über dessen Katalogverzeichnisse die Referenzen der Entität gelesen werden, keine zu prüfende Hülle, weshalb --ir-graph neben einem Entitätspfad abgelehnt wird. Ein --release, das eine nicht existierende Datei oder ein Verzeichnis nennt, wird abgelehnt, bevor irgendetwas geprüft wird.
Ein Verzeichnis, das die Workspace-Konfiguration aufführt und das kein Verzeichnis ist — weil dort etwa nichts existiert —, für dieses Release oder, wenn kein --release angegeben ist, für den Workspace, wird abgelehnt, bevor irgendetwas geprüft wird, so wie jeder Befehl, der diesen Katalog liest, es ablehnt (Woher lokale Entitäten gelesen werden): Die Ablehnung nennt den Eintrag, die Konfigurationsdatei und die Zeile, die ihn aufführen, sowie die Einstellung, und es wird kein Urteil abgegeben. Die Entitätsprüfung des Editors über aggrega serve gibt dieselbe Ablehnung als einzigen Eintrag zur Datei der Entität aus, auf der Fehlerstufe, und das validate-Tool von aggrega mcp lehnt den Aufruf damit ab.
Noch ausstehende Platzhalter
Ein Wert, den die Art verlangt und den die Datei als leeren String belässt, ist ein Platzhalter, und validate meldet ihn vor allem anderen. Ein von aggrega scaffold entworfenes Dokument enthält überall dort einen, wo seine Art einen Wert braucht, den nur Sie liefern können, daher erfahren Sie hier, welche noch übrig sind. Hier ist ein entworfenes FeatureRecipe, bei dem nur die Version ausgefüllt ist:
Entity: my-feature-recipe.yamlKind: FeatureRecipe2 placeholders still owed in my-feature-recipe.yaml; an empty required value is not a value, so each of these needs one before the document validates: 7:3: spec.capability takes what its schema describes: The explicit provider capability this recipe binds to (e.g., 'helm', 'terraform', 'compose') — the provider kind that renders it. 8:3: spec.implements takes what its schema describes: Declares which catalog Feature type this recipe is able to implement (including credential Features labeled feature.aggrega.ai/kind: secret; exact version, major-compatible range '^', or unversioned).Alle Platzhalter in der Datei werden auf einmal genannt, in Dokumentreihenfolge, mit Zeile und Spalte und mit dem, was sie annehmen. Was sie annehmen, wird aus dem eigenen Schema der Art gelesen: die akzeptierten Werte, wo das Schema sie aufführt, eine semantische Version wie 1.0.0, wo das Schema eine verlangt, und andernfalls der erste Satz der eigenen Beschreibung des Feldes im Schema.
Welche Werte zählen, wird ebenfalls aus dem Schema gelesen. Ein Wert zählt, wenn die Art ihn auf oberster Ebene des Dokuments verlangt oder innerhalb eines Objekts, das die Art ebenfalls verlangt, und die Datei ihn auf den leeren String setzt. Ein Schlüssel, den die Datei ganz weglässt, wird von der Schemaprüfung als fehlende Eigenschaft gemeldet. Ein leer gelassenes optionales Feld ist kein Platzhalter, und ebenso wenig ein Feld, das nur innerhalb einer Liste oder einer Map verlangt wird, die Sie zu schreiben gewählt haben. Wo das Schema selbst den leeren String unter den Werten aufführt, die ein Feld akzeptiert, ist ein leerer ein Wert und kein Platzhalter.
Ein Wert steht auch dort aus, wo das Schema ihn leer annehmen würde. Das Schema lässt einen leeren String für capability und implements eines Recipe oder FeatureRecipe zu, aber ein leerer nennt keinen Provider und keinen Typ, daher meldet validate beide wie jeden anderen als Platzhalter. Wo die Schemaprüfung dieselbe Datei ebenfalls ablehnt — eine leere Version, ein Typ-Label ohne Wert —, enthält der Bericht den Code dieser Prüfung, E0215, wie das Beispiel unter aggrega scaffold zeigt; wo die Schemaprüfung sie akzeptiert, wie oben, enthält der Bericht keinen Code. Ein Befund in derselben Datei, der keinen leeren Wert betrifft, wird dennoch gemeldet, in den eigenen Worten der Schemaprüfung, vor der Liste.
Diese Lesart gehört zur Validierung einer einzelnen Entität, mit oder ohne --release neben dem Entitätspfad. Ein Lauf über den gesamten Katalog, der auf dasselbe Dokument trifft, meldet, was die Schemaprüfung meldet, sodass ein FeatureRecipe mit leerem implements in einem Katalogverzeichnis ihn besteht; auch der Release-Geltungsbereich und aggrega build wenden diese Lesart nicht an.
Eine Art, die dieser Geltungsbereich nicht annimmt
Die Validierung einer einzelnen Entität nimmt Component, Feature, Recipe, FeatureRecipe, Workload und Plugin an. Eine Datei jeder anderen Art wird abgelehnt, und die Ablehnung nennt die akzeptierten Arten und, für eine Entitätsart, den Geltungsbereich, der ein Dokument dieser Art tatsächlich prüft:
kind "Aggregate" in "aggregate.yaml" is not a single-entity validation target; the kinds this scope accepts are Component, Feature, Recipe, FeatureRecipe, Workload and Plugin. An Aggregate is checked by the whole-catalog scope when it sits in a catalog directory, and by the Release scope over a Release that deploys itDer Geltungsbereich des gesamten Katalogs ist ein Lauf ohne Argument, und der Release-Geltungsbereich ist --release ohne Entitätspfad:
| Art | Geprüft durch |
|---|---|
| Aggregate | einen Lauf über den gesamten Katalog, wenn es in einem Katalogverzeichnis liegt; --release über ein Release, das es bereitstellt |
| Manifest | --release über ein Release, das es nennt |
| Release | --release <release-path> |
| SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary | einen Lauf über den gesamten Katalog, wenn es in einem Katalogverzeichnis liegt |
Ein Lauf über den gesamten Katalog liest nur, was innerhalb der konfigurierten Katalogverzeichnisse liegt, daher wird ein Aggregate, das im Workspace-Stammverzeichnis neben seinem Release liegt, über --release über dieses Release geprüft.
Eine fehlgeschlagene Assertion ist eine Warnung
Eine Assertion, die fail aufruft — eine, die das Recipe deklariert, oder eine, die seine implements-Component deklariert —, wird als Warnung gemeldet, und die Prüfung schlägt ihretwegen nicht fehl. Das synthetisierte Release enthält Platzhalter und Schema-Standardwerte anstelle der Werte, die ein echtes Release setzt, daher schlägt eine Assertion über einen solchen Wert, ein Image oder das Vorhandensein einer Voraussetzung hier fehl, ob das Recipe stimmig ist oder nicht, und validate kann eine Assertion, die auf ein Release wartet, nicht von einer defekten unterscheiden. Das Urteil über die Assertion bleibt einem Build überlassen, der immer ein Release hat.
Die Warnung wird auf die Standardfehlerausgabe geschrieben, eingeleitet durch warning:, nach etwaigen beratenden Hinweisen. Sie enthält die vollständige Meldung der Assertion — die Entität, die Instanz, den Namen der Assertion und den Satz, den ihr Autor geschrieben hat —, abgeschlossen durch einen weiteren Satz:
A Release must satisfy this assertion before a build of it can pass.Der Bericht auf der Standardausgabe sagt, wo der Lauf angehalten hat, und der Befehl endet mit 0. Die eigene Assertion eines Recipe hält das Rendern an, daher lautet der Bericht Render: stopped on a failed assertion, reported as a warning nach Resolution: valid. Die Assertion einer Component wird ausgewertet, bevor etwas gerendert wird, daher lautet der Bericht Resolution: stopped on a failed assertion, reported as a warning, gefolgt von Render: not attempted (the run stopped on that assertion). In beiden Fällen wird nichts gerendert, daher wird kein Artefakt ausgegeben.
Nur eine Assertion, die fail aufruft, ist eine Warnung. Eine Assertion, die an einem Schlüssel anhält, den sie liest, aber nicht findet, oder die sich nicht parsen lässt, ist ein Fehler im eigenen Text der Assertion und keine fehlgeschlagene Assertion, und sie wird wie jeder andere Abbruch beurteilt. Jeder andere Fehler behält seinen Platz als Urteil der Prüfung.
aggrega build eines Release, das die Assertion nicht erfüllt, hält daran mit einem Fehler an, nennt die Assertion und enthält den Satz ihres Autors, wie immer, und aggrega validate --release über dieses Release schlägt daran mit demselben Fehler fehl. Die Entitätsprüfung des Editors über aggrega serve gibt dieselbe Warnung aus, gezeichnet am eigenen Schlüssel der Assertion, wo das Recipe sie deklariert, und das validate-Tool von aggrega mcp antwortet valid: true mit der Warnung unter seinen notices.
Was die Korrektheit einer einzelnen Entität nicht prüft
Vier Prüfungen eines echten Builds sind für einen Build einer einzelnen Entität außer Reichweite, und validate verzichtet auf jede davon, statt einen Befund zu melden, für den es nicht einstehen kann.
Eine Quelle, die abgerufen werden muss
Die Validierung einer einzelnen Entität liest kein Lockfile, liest und schreibt keinen Cache und stellt keine Netzwerkanfrage. Ein Recipe, dessen source: etwas nennt, das über einen Transport abgerufen wird — ein OCI- oder HTTPS-Chart-Repository, ein Git-Repository —, hat daher keinen Infrastrukturcode, aus dem gerendert werden könnte: Das Chart oder Modul existiert nirgends, wo der Lauf es erreichen kann, und nichts in der geprüften Datei ist fehlerhaft. Validate sagt das, gibt es als ein vom Rendern unterschiedenes Ergebnis aus und endet mit 0:
Entity: catalog/recipe/helm/openbao/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validResolution: validRender: not attempted (this Recipe's source is fetched) Validating one entity on its own reads no lockfile, reads and writes no cache, and makes no network request, so the chart or module this Recipe names is never retrieved and there is nothing to render from. To render it, build a Release that deploys a component this Recipe implements.Alles oberhalb dieser Zeile wurde geprüft und wird als gültig gemeldet. Was der Exit-Code für ein solches Recipe bedeutet, ist daher enger als für eines, das gerendert wurde — Schema, Form und Auflösung halten; das Rendern ist unbewiesen —, und der Bericht gibt an, welches der beiden Sie lesen.
Eine Quelle, die der Workspace bereits enthält, wird nicht zurückgestellt. Ein relatives source: ./module braucht keinen Abruf, daher wird sein Rendern wie jedes andere versucht, und ein Fehlschlag darin ist ein echter Befund, der als Render: not completed in isolation mit einem Exit-Code ungleich null gemeldet wird. Die obige Zeile erscheint nur für eine Quelle, die abgerufen werden muss.
Um ein Recipe mit abgerufener Quelle wirklich zu rendern, führen Sie aggrega build über ein Release aus, das eine Komponente bereitstellt, die das Recipe implementiert: Ein Build löst die Quelle über das Lockfile des Release und den lokalen Cache auf, und das ist es, was die Bytes liefert, die validate nicht beschaffen kann.
Ein erforderlicher uses-Socket
Die zweite ist, ob die required: true-uses-Sockets der implements-Component belegt sind.
Ein erforderlicher Socket wird belegt, indem eine Kante zu einer anderen Komponente verdrahtet wird — aus dem eigenen uses-Block des Aggregate oder von einem Release, das einen von der Component deklarierten Socket verdrahtet. Das synthetisierte Harness enthält eine einzige Instanz, also keine zweite Komponente, auf die eine solche Kante zielen könnte, und keine Gestaltung der synthetisierten Dokumente kann eine erzeugen: Einen Peer zu erfinden, hieße Rechenressourcen zu erfinden, die das Harness nie deklariert hat. Validate nennt daher die Sockets, die es nicht geprüft hat, und fährt mit Auflösung und Rendern fort:
Sockets: required uses sockets not checked (backend, cache, registry) Validating a Recipe on its own places its Component in a build of one, so no other component exists for a required socket to be wired to. Whether each of these sockets is populated is checked when the Component is deployed in an Aggregate.Die Zeile erscheint nur, wenn die Component mindestens einen erforderlichen Socket deklariert, und sie nennt nur die erforderlichen — ein optionaler Socket wird nie aufgeführt, weil ihn unverdrahtet zu lassen in keinem Geltungsbereich ein Befund ist. Ein Recipe, dessen Component keinen erforderlichen Socket deklariert, erzeugt keine solche Zeile, und sein Bericht bleibt unverändert.
Die Regel selbst wird weder gelockert noch dupliziert; sie wird in dem Geltungsbereich gestellt, der sie beantworten kann. aggrega build wendet sie vollständig über die Kantenflächen des Aggregate und des Release zusammen an und hält bei einem erforderlichen Socket an, den nichts verdrahtet. Ein Recipe, das die Validierung einer einzelnen Entität besteht, muss also dennoch die Regel für erforderliche Sockets erfüllen, wenn seine Component bereitgestellt wird, und der Bericht sagt das, statt einen stillen Unterschied zwischen dem zu lassen, was validate geprüft hat, und dem, was ein Build prüfen wird.
Ein erforderlicher Anhangsslot oder ein Präsenzmandat
Die dritte ist, ob die required: true-Anhangsslots der implements-Component — die benannten Bindungspunkte, die ihr featuresSchema deklariert — gefüllt sind und ob ein Anhang jedes Feature-Typs vorhanden ist, den ihre Präsenzmandate verlangen.
Ein erforderlicher Slot wird gefüllt, indem ein Feature unter diesem Namen angehängt wird, im Aggregate oder im Release, an der Komponente oder in einem Geltungsbereich darüber — dort, wo die Component bereitgestellt wird, nicht im Recipe. Das synthetisierte Harness hängt kein Feature an, daher kann nichts, was es baut, einen solchen Slot füllen. Validate nennt daher die Slots, die es nicht geprüft hat, und fährt mit Auflösung und Rendern fort, genau wie bei erforderlichen Sockets:
Attachments: required attachment slots not checked (root_password) Validating a Recipe on its own places its Component in a build that attaches no Feature, so nothing exists to fill a required slot. Whether each of these slots is filled is checked when a Release that deploys the Component is built.Die Zeile erscheint nur, wenn die Component mindestens einen erforderlichen Slot deklariert, und sie nennt nur die erforderlichen; ein Recipe, dessen Component keinen deklariert, erzeugt keine solche Zeile. Nur die Anforderung wird zurückgestellt: Die Label-Einschränkung eines Slots und seine zulässigen Bereitstellungsmechanismen bleiben wie deklariert. Ein Template, das sich nicht parsen lässt, lässt den Lauf dennoch fehlschlagen, ebenso ein eigener Fehler des Recipe wie eine Workload, die der Provider nicht synthetisieren kann — es sei denn, das Recipe liest auch einen Wert, den nur eine Verbindung oder ein angehängtes Feature liefert, wie der nächste Abschnitt beschreibt.
Ein Präsenzmandat — eine features.aggrega.ai/requiredType.<label>-Annotation an der Component, die verlangt, dass irgendein Anhang den von ihr genannten Feature-Typ trägt — wird aus demselben Grund zurückgestellt: Das Harness hängt nichts an, daher kann nichts, was es baut, den Typ tragen. Validate nennt jedes Mandat, das es nicht geprüft hat, mit seinem Label und dem verlangten Typ und fährt mit Auflösung und Rendern fort. example/compute/service der Standardbibliothek deklariert eines, daher meldet sein Recipe vor seinen zwei gerenderten Artefakten:
$ aggrega validate aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml --catalog aggrega-catalogEntity: aggrega-catalog/recipe/helm/service/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validAttachments: presence mandates not checked (monitoring: core/prometheus-exporter) Validating a Recipe on its own places its Component in a build that attaches no Feature, so nothing exists to carry a type the Component requires. Whether an attachment of each of these types is present is checked when a Release that deploys the Component is built.Resolution: validRender: 2 artifact(s)Ein Mandat, dessen Deklaration nicht ausgewertet werden kann — das Präfix der Annotation ohne nachfolgendes Label oder ein Wert, der kein Feature-Typ ist —, wird nicht zurückgestellt: Es ist ein eigener Fehler der Component, den kein Anhang behebt, und validate lässt den Lauf daran fehlschlagen, wie ein Build es tut.
Jede Regel wird dort gestellt, wo sie beantwortet werden kann. aggrega pull, aggrega build und aggrega validate --release werten beide über die echten Anhänge des Release aus, und jeder hält bei einem erforderlichen Slot an, den nichts füllt, und bei einem vorgeschriebenen Typ, den kein Anhang trägt.
Ein Wert, den nur eine Verbindung oder ein angehängtes Feature liefert
Die vierte ist, ob ein Recipe gerendert wird, sobald seine Verbindungen und seine angehängten Features liefern, was seine Templates lesen.
Die Templates eines Recipe lesen, was eine Verbindung unter .context.inject und .context.uses liefert, und was ein angehängtes Feature unter .features liefert. Das synthetisierte Harness stellt keine Verbindung her und hängt kein Feature an, daher findet jeder solche Lesezugriff nichts: Ein Lesezugriff unter .context.inject.env trifft auf eine leere Lieferleitung, und ein range über .context.uses trifft auf keine Verbindung. Validate rendert zuerst das Recipe, und ein Rendern, das abgeschlossen wird, wird wie gewohnt gemeldet. Wenn das Rendern anhält und die Templates des Recipe — einschließlich der Dateien und Bibliothekseinträge, die sie importieren — irgendetwas unter diesen dreien lesen, meldet validate das Rendern als nicht versucht, nennt die Werte, die das Recipe dort liest, gibt den Satz aus, an dem das Rendern angehalten hat, und endet mit 0. Die chart-Variante des MariaDB + Adminer-Beispiels liest ihre Datenbank-Anmeldedaten aus der Lieferleitung, die ihre zwei angehängten Secrets füllen:
$ aggrega validate catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml --release release-helm-chart.yamlEntity: catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validAttachments: required attachment slots not checked (root_password) Validating a Recipe on its own places its Component in a build that attaches no Feature, so nothing exists to fill a required slot. Whether each of these slots is filled is checked when a Release that deploys the Component is built.Resolution: validRender: not attempted (this Recipe reads values a build of one cannot supply) Validating a Recipe on its own places its Component in a build that wires no connection and attaches no Feature, so nothing supplies what its templates read under .context.inject, .context.uses or .features. Its render stopped, and whether on one of those values or on a fault of its own is not judged here. To render it, build a Release that deploys a component this Recipe implements. Reads: .context.inject.env.MARIADB_PASSWORD, .context.inject.env.MARIADB_ROOT_PASSWORD The render stopped: rendering: [CATALOG_ERROR] instance instance: rendering node "instance": [CATALOG_ERROR] catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml: recipe "mariadb-chart" valuesMapping: [CATALOG_ERROR] valuesMapping[mariadb-chart]: template "valuesMapping[mariadb-chart]" execute: template: valuesMapping[mariadb-chart]:7:30: executing "valuesMapping[mariadb-chart]" at <.context.inject.env.MARIADB_ROOT_PASSWORD>: nil pointer evaluating interface {}.MARIADB_ROOT_PASSWORDEin Lesezugriff, der nichts findet und nichts anhält, wird nicht zurückgestellt: Ein range über .context.uses, das nichts rendert, in einem Rendern, das abgeschlossen wird, wird als das Rendern gemeldet, das es war.
Entscheidend ist, was das Recipe liest, nicht, woran das Rendern angehalten hat, und das hat eine Folge, die Sie kennen sollten, bevor Sie ihr begegnen: Ein eigener Fehler des Recipe in einem Recipe, das auch einen solchen Wert liest — etwa ein falsch geschriebener Schlüssel —, wird zusammen mit dem Rest als nicht versucht gemeldet, nicht als Fehlschlag. Die Zeile The render stopped: enthält den eigenen Satz des Renderns, sodass Sie sehen können, was es war, und ein Build eines Release, das die Component bereitstellt, beurteilt das Rendern vollständig.
Zwei Fehler lassen den Lauf dennoch fehlschlagen, gleichgültig, was das Recipe liest, weil keine Verbindung und kein Feature sie ändert: ein Template, das sich nicht parsen lässt, und eine Referenz, die das Rendern ablehnt — eine Wurzel, die der Render-Kontext nicht definiert, oder ein falsch geschriebener Schlüssel unter einer Wurzel mit fester Form, etwa .context.instance_idd. Eine vom Recipe deklarierte Assertion, die fail aufruft, wird weder zurückgestellt noch ist sie ein Fehlschlag, gleichgültig, was das Recipe liest: Sie wird als die Warnung gemeldet, die eine fehlgeschlagene Assertion immer ist. Bei einem Recipe, dessen Templates keines der drei lesen, wird das Rendern vollständig beurteilt, und ein Rendern, das anhält, schlägt mit dem Satz fehl, der die Ursache nennt.
Das validate-Tool von aggrega mcp fällt über dasselbe Recipe dasselbe Urteil: Ein auf diese Weise zurückgestelltes Rendern antwortet als gültig ohne Einträge in seinen Diagnosen, und die obigen Zeilen stehen in dem Text, den es daneben zurückgibt.
Das Laden des Katalogs im Modus für eine einzelne Entität ist tolerant: Eine nicht zusammenhängende defekte Entität an anderer Stelle im Katalog wird übersprungen, statt die Prüfung abzubrechen, sodass sie die isolierte Validierung des Ziels nie blockiert.
Eine übersprungene Datei erklärt dennoch eine Component, die ihretwegen fehlt. Wo das implements-Ziel eines Recipe nicht gefunden wird und genau eine übersprungene Datei diese Component deklariert, beginnt der Bericht mit der eigenen Zurückweisung dieser Datei — ihrem Pfad, der Einschränkung, gegen die sie verstößt, und dem Kurzcode der Bedingung in der Kopfzeile —, gefolgt von einer note:, die besagt, dass die Datei beim Laden übersprungen wurde, sodass der Katalog unter der von ihr deklarierten Identität nichts enthält, und dann vom Fehler implements target … not found in catalog als Grund, weshalb die Datei benötigt wurde. Wo keine übersprungene Datei diese Component deklariert oder mehr als eine, steht der Nicht-gefunden-Fehler an erster Stelle, und jede übersprungene Datei wird darunter unter note: catalog files skipped at load aufgeführt. Dies ist die Darstellung, die aggrega build von einer übersprungenen Datei gibt, und auch die Entitätsprüfung des Editors über aggrega serve und das Tool validate von aggrega mcp geben sie. Ein Katalog, aus dem nichts übersprungen wurde, meldet genau so, wie er es sonst täte.
Wie validate sich zu lint und build verhält
Die drei Befehle decken drei verschiedene Fragen ab:
aggrega validate— ist das korrekt? Schema, Säulen, Referenzen,extends, Eingabeart-Fähigkeit und isoliertes Rendern. Es liest keinen Laufzeitzustand und erzeugt keine Artefakte.aggrega lint— folgt das den Veröffentlichungskonventionen des Katalogs? Benennung, Ausrichtung von Kategorie und Verzeichnis, Annotationspräfixe, Größe des Versionssprungs und der Rest der optionalen Veröffentlichungsdisziplin. Lint spiegelt die drei Geltungsbereiche von validate, prüft aber nie die Korrektheit.aggrega build— ein vollständiges Deployment kompilieren. Build braucht eine vollständige Hülle aus Aggregate + Manifest + Release und erzeugt Provider-native Artefakte. Es validiert als Teil des Kompilierens seine eigene Abhängigkeitshülle und rendert dann.aggrega validate --releaseist diese Abhängigkeitsvalidierung für sich, ohne das Rendern; validate für eine einzelne Entität isoliert das Rendern eines einzelnen Recipe ohne ein vollständiges Aggregate.
Beispiele
Den gesamten Katalog validieren:
aggrega validate --catalog ./catalogGenau das validieren, wovon ein Release abhängt, bevor es gebaut wird:
aggrega validate --release releases/production.yamlEine einzelne Entität validieren und — bei einem Recipe — ihre isoliert gerenderte Ausgabe ansehen:
aggrega validate core/datastore/postgres/recipes/helm.yamlEine einzelne Entität im Kontext eines Release validieren, dem die Workspace-Konfiguration eigene Katalogverzeichnisse gibt:
aggrega validate core/datastore/postgres/recipes/helm.yaml --release releases/production.yamlSiehe auch
- ./aggrega-lint.md — das Gegenstück für Konventionen über dieselben drei Geltungsbereiche.
- ./aggrega-build.md — kompiliert ein vollständiges Aggregate + Release zu Artefakten; validiert seine Abhängigkeitshülle als Teil des Kompilierens.
- ./aggrega-inspect.md — den IR-Graphen nach der Auflösung abfragen, ohne zum Rendern überzugehen.
- ../errors/warnings.md — die beratenden Befunde, die validate als
notice:-Zeilen ausgibt.
Übersicht
aggrega validate [entity-path] [flags]Beschreibung
Check CORRECTNESS across three symmetric scopes.
With no argument, validate checks the WHOLE catalog: schema-pillarstructure, cross-document library resolution, extends chains, and providerinput-kind capabilities, over every catalog entity. Where the workspaceconfiguration gives its Releases catalog directories of their own underworkspace.releases, it checks the catalog once for each Release, over thedirectories that Release reads, and reports each pass under a line namingits Releases and those directories; Releases reading the same directoriesshare one pass.
With --release, validate checks the entities a Release's dependency closurereaches: closure-scoped pillars, extends, and pre-render authored-valueconformance — the same correctness a build applies, scoped to that Release.It then evaluates the Recipe and FeatureRecipe assertions against the valuesthat Release resolves to, as a build does before it renders, and reports afailing assertion as a build reports it. Nothing is rendered.
With an entity path, validate checks one entity file. The kinds it acceptsas a single-entity target are Component, Feature, Recipe, FeatureRecipe,Workload and Plugin. A value the kind requires that the file leaves empty isreported first, as a placeholder still owed: every one is named at once, withwhat it takes, read from the kind's own schema. That reading is this scope'salone; a whole-catalog run, a Release's closure and a build do not apply it.Each kind then has its schema checked, then the checks its own kind carries:pillar structure for a Component or Feature; shape for a Workload,FeatureRecipe or Plugin; and for a Recipe, shape plus an end-to-end compileagainst a minimal generated harness, so its resolution, its guards and arender of its output are all exercised. Where that Recipe's source is onethat has to be fetched, the render is reported as not attempted instead:validating one entity on its own reads no lockfile, reads and writes no cacheand makes no network request, so the chart or module it names is neverretrieved and there is nothing to render from. A render that stops while theRecipe's templates read what only a connection or an attached Featuresupplies — anything under .context.inject, .context.uses or .features — isreported as not attempted too: the generated harness wires no connection andattaches no Feature, so that render cannot be judged there, and a fault ofthe Recipe's own beside such a read is set aside with it. A template thatdoes not parse and a reference the render refuses still fail. An assertionthat calls fail, the Recipe's own or one its Component declares, is printedas a warning closed by a sentence saying a Release must satisfy it before abuild can pass, and does not fail the check: the generated harness sets noneof a real Release's values, so it cannot tell an assertion waiting on one fromone that is broken, and a build still halts on it. Any other kind is refused heretoday, and the refusal names the scope that checks it instead: a whole-catalogrun reaches an Aggregate and the library kinds when they sit in a catalogdirectory, and --release reaches a Release, the Manifest it names and theAggregate it deploys.
With an entity path and --release together, the entity is checked in thatRelease's terms: its references — the Component a Recipe implements, alibrary a pillar refers to — resolve through the catalog directories theworkspace configuration gives that Release rather than the workspace's own,so a workspace keeping one catalog variant per Release checks an entityagainst the variant that Release builds with. The checks are the entitypath's; no closure is validated.
The command writes nothing to disk.Flags
| Flag | Standard | Beschreibung |
|---|---|---|
--catalog | [] | Katalogverzeichnis; wiederholbar. Jedes —catalog <dir> wird dem Katalog-Suchstapel vorangestellt (der erste Treffer gewinnt): den catalog_dirs des Workspace oder, für ein Release, dem die Workspace-Konfiguration unter workspace.releases eigene Verzeichnisse gibt, denen dieses Release; der Stapel endet mit dem Verzeichnis namens catalog im Workspace-Stammverzeichnis, sofern es eines gibt. Eine leer geschriebene catalog_dirs-Liste liest überhaupt keinen lokalen Katalog. |
--ir-graph | false | Schreibt zusätzlich den von diesem Lauf berechneten IR-Graphen als JSON auf stdout, ergänzend zu allem, was dieser Befehl bereits erzeugt. Werte, die ein Autor als sensibel deklariert hat, werden darin zurückgehalten; übergeben Sie —unredacted, um sie stattdessen auszugeben. Gilt für den Geltungsbereich —release, den einzigen Geltungsbereich, der ein Release zu einem Graphen auflöst. Es wählt ein DOKUMENT aus, während —response-format festlegt, wie viel vom eigenen Bericht dieses Befehls geschrieben wird; keines von beiden beeinflusst das Urteil oder den Exit-Code |
--no-unsupported-field-warnings | false | Unterdrückt die Warnklasse für nicht unterstützte Felder: die Hinweise, die ein Ziel für etwas ausgibt, das Sie verfasst haben und das es nicht berücksichtigen kann — ein Workload-Feld, das es nicht ausdrücken kann (wie es bei einem Ziel geringerer Treue wie compose der Fall ist), oder eine aggrega.ai/-Annotation, auf die es für die Eingabeart des Knotens nicht reagiert. Andere Render-Warnungen erscheinen weiterhin. Nur für die Anzeige; ändert die gerenderte Ausgabe nicht. Gilt für den Entitäts-Geltungsbereich, den einzigen Geltungsbereich, der rendert |
--plugin | — | Pfad zu einer rohen .wasm, die gegen ihre describe()-Selbstauskunft validiert wird — die Authoring-Prüfung vor der Veröffentlichung. Allein benötigt es —type; mit einem Plugin-Entitätsargument gleicht es die Binärdatei mit dem deklarierten Typ der Entität, dem Fähigkeitsanspruch, dem Befehlsspiegel und dem Verzeichnis der Host-Funktionen ab. |
--release | — | Pfad zu einer Release-YAML. Allein wird über ihre aufgelöste Abhängigkeitshülle validiert; mit einem Entitätsargument wird diese Entität im Kontext des Release geprüft, wobei ihre Referenzen über die Katalogverzeichnisse aufgelöst werden, die die Workspace-Konfiguration diesem Release gibt. Ein relativer Pfad wird gegen das Verzeichnis aufgelöst, in dem Sie den Befehl ausführen, nicht gegen das Workspace-Stammverzeichnis. Wo dieses Verzeichnis in keinem Workspace liegt und kein Stammverzeichnis genannt ist, findet ein absoluter Pfad den Workspace vom eigenen Ordner des Release aus |
--response-format | detailed | Ausgabeumfang für den Geltungsbereich —release, die Hülle eines Release ohne Entitätsargument: detailed (Standard) meldet jede Diagnose plus beratende Zeilen; concise meldet die Anzahl der Diagnosen und nur die erste Diagnose. Urteil und Exit-Code sind bei beiden identisch. |
--type | — | Plugin-Typ für eine reine Binärprüfung mit —plugin, verifiziert gegen den selbst gemeldeten Typ der Binärdatei. Nur mit —plugin sinnvoll; wenn eine Plugin-Entität den Typ liefert, lassen Sie ihn weg (ein abweichender Wert führt zum Abbruch). |
--unredacted | false | Gibt die Werte, die ein Autor als sensibel deklariert hat, aus, statt sie zurückzuhalten. Alles, was die Ausgabe erreicht — ein Terminal, eine Pipe, eine Datei, eine Bildschirmaufnahme —, enthält diese Werte dann im Klartext. Erreicht den Graphen, den —ir-graph schreibt, und nichts anderes, daher erfordert es —ir-graph |