Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

aggrega lint

aggrega lint prüft Veröffentlichungskonventionen — Benennung, Übereinstimmung von Kategorie und Verzeichnis, Annotationspräfixe, Disziplin beim Verfassen von Schemas und Umfang der Versionserhöhung. Es hat drei Modi, die über sein Argument gewählt werden und dieselbe Konventionsdisziplin auf drei Geltungsbereiche anwenden: den gesamten Katalog (kein Argument), den Abhängigkeitsabschluss eines einzelnen Release (--release) und die Datei einer Entität (ein Entitätspfad, mit optionalem Veröffentlichungs-Gate --pre-publish). Jeder Geltungsbereich beantwortet dieselbe Frage — „Folgt dieser Inhalt der Veröffentlichungsdisziplin des Katalogs?“ — für einen anderen Ausschnitt des Katalogs.

Konventionen sind etwas anderes als Korrektheit. aggrega lint prüft nie, ob Inhalt wohlgeformt ist oder kompilieren würde — das übernimmt aggrega validate, das dieselben drei Geltungsbereiche für Schema, Säulen, Referenzauflösung, extends, Fähigkeit der Eingabeart und Rendering abbildet. Ein Socket- oder Slot-Selektor, den die Selektorgrammatik nicht lesen kann, ist ein Korrektheitsfehler, daher meldet lint nichts dazu: validate lehnt ihn ab, über den gesamten Katalog oder über eine einzelne Component oder ein einzelnes Feature — siehe deklarierte Selektoren. Die beiden Befehle ergänzen sich: validate sagt Ihnen, ob Inhalt korrekt ist; lint sagt Ihnen, ob er nach den Konventionen des Katalogs veröffentlichbar ist.

aggrega lint ist optional. Der Compiler selbst bleibt meinungslos in Bezug auf die Katalogdisziplin; diese Regeln befinden sich in einem separaten Plug-in, das Sie ausführen können, wenn Sie es wählen. Ein Workspace, der aggrega lint nie ausführt, wird trotzdem gebaut und veröffentlicht.

Der Entitätspfad kann positionell oder mit --entity <path> angegeben werden. --release schließt ein Entitätsargument aus — sie wählen unterschiedliche Geltungsbereiche; die Übergabe beider führt zum Abbruch.

Konventionen für den gesamten Katalog (kein Argument)

aggrega lint ohne Argument führt die strukturellen Regeln der Veröffentlichungsdisziplin für jede Katalogentität aus, die unter den konfigurierten Katalogverzeichnissen gefunden wird. Befunde sind beratend — sie werden mit dem Schweregrad warn gemeldet und führen allein aufgrund eines Konventionsbefunds nie zum Abbruch. Verwenden Sie es, um einen Katalog auf Abweichungen bei Benennung, Kategorie-Verzeichnis-Zuordnung und Annotationspräfixen zu durchsuchen. Ein Aggregate, ein Manifest, ein Release oder eine Workload in einem Katalogverzeichnis wird übergangen statt geprüft: Der Durchlauf zählt jede solche Art in einer Zeile not checked: nach seiner Zusammenfassung und verweist Sie auf den Entitätsmodus, der ein Dokument jeder Art prüft.

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, ob in Anführungszeichen oder nicht. Ein Aggrega-Dokument, das nicht gelesen werden kann, dessen YAML sich nicht parsen lässt oder dessen kind, metadata oder spec nicht die Form hat, die die Hülle 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; nichts wird gelintet, und keine Zeile conventions checked wird ausgegeben. Eines, das sich laden lässt 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 ihnen 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-Values, Workflow-Definitionen – wird übergangen. --release hält bei einem solchen Dokument unter seinen Katalogverzeichnissen auf dieselbe Weise an.

Welche Verzeichnisse es liest, hängt von der Form des Workspace ab:

  • Ein Workspace, dessen Konfiguration keinem Release eigene Katalogverzeichnisse zuweist, wird einmal über seinen Suchstapel geprüft: die --catalog-Verzeichnisse, dann workspace.catalog_dirs, dann das Verzeichnis catalog im Workspace-Stammverzeichnis, sofern vorhanden.

  • Ein Workspace, der unter workspace.releases Releases benennt, kann einen Katalog in mehreren Varianten nebeneinander halten, die jeweils von ihrem eigenen Release gelesen werden, und ein einziger Durchlauf über alle würde jede Variante gleichzeitig lesen — wobei die Entität einer Variante die einer anderen verdeckt. Daher wird er einmal für jedes Release geprüft, 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 von den Befunden und der eigenen Zusammenfassung dieses Durchlaufs:

    Release release-compose.yaml reads catalog-compose
    conventions checked: 7 entities, 0 advisory finding(s)
    Release release-helm-synth.yaml reads catalog-helm-synth
    conventions checked: 8 entities, 0 advisory finding(s)

    Releases, die genau dieselben Verzeichnisse lesen, teilen sich einen Durchlauf, der jedes von ihnen nennt, sodass ein Befund dort einmal gemeldet wird. 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. Mit -o json trägt das Dokument außerdem passes: die releases, catalogDirs, findings und summary jedes Durchlaufs, während findings und summary auf oberster Ebene alle Durchläufe zusammen abdecken. Die Releases, die ein Workspace enthält, sind seine Release-Dokumente — YAML-Dateien, deren kind Release ist, irgendwo unter dem Workspace-Stammverzeichnis außerhalb versteckter Verzeichnisse sowie node_modules, vendor und dist.

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. Das aktuelle Arbeitsverzeichnis wird nie implizit durchsucht.

Ein Link unterhalb eines Katalogverzeichnisses, der aus dem Workspace hinausführt — oder aus einem Verzeichnis außerhalb davon, das Sie angegeben haben —, wird nicht gelesen, und der Lauf hält dort an und nennt den Link, statt einen Katalog als sauber zu melden, von dem eines seiner Dokumente nicht gelesen werden konnte; ein Build über dieselben Verzeichnisse hält am selben Link an. Die Workspace-Grenze beschreibt die Regel und ihre Abhilfen.

Konventionen über ein Release (--release)

aggrega lint --release <release-path> führt dieselben strukturellen Regeln für die Entitätsdateien des Katalogs aus, die der aufgelöste Abschluss eines einzelnen Release erreicht, statt für den gesamten Katalog oder eine einzelne Entität. Es berechnet den Abschluss mit derselben Mechanik, die ein Build verwendet, und lintet dann die vom Autor verantwortete Katalogdatei jeder Entität. Eine über eine Registry gepinnte Entität, die in einem Cache-Slot liegt, hat keine lokale Datei zum Linten und wird übersprungen — die Veröffentlichungsregeln gelten für lokal verfasste Dateien. Wie beim Modus für den gesamten Katalog sind Befunde beratend und führen allein aufgrund eines Konventionsbefunds nie zum Abbruch.

Dies ist auch der einzige Geltungsbereich, der ein ganzes Release zur Hand hat, und daher der Ort, an dem die Regeln laufen, die eines lesen — die unter Die Disziplinregeln beschriebene Regel zu Verbindungs-Berechtigungsnachweisen. Eine solche Regel läuft einmal pro Prüfung, nach den Regeln pro Entität, über drei Dokumente: das Aggregate, das das Release bereitstellt, so wie sein Autor es geschrieben hat; das Release mit eingefalteter extends-Kette, sodass ein abgeleitetes Release trägt, was es erbt; und für jede Komponente, die das Aggregate deklariert, die Component, deren Instanz diese Komponente ist, so wie der Katalog sie auflöst. Kein Parameterwert ist darunter, wie in jedem Geltungsbereich: Das Release kommt ohne seinen parameters-Block an, einschließlich der Werte, die es von einer Basis erbt, und das Aggregate ohne seine Standardwerte und ohne die Werte, die es an jedes importierte Modul übergibt — siehe Was ein Linter-Plug-in übergeben bekommt. Ihre Befunde werden unter der Release-Datei gemeldet.

Dies ist das Konventions-Gegenstück zu aggrega validate --release, das denselben Abschluss auf Korrektheit prüft.

Die Linter, die dieser Geltungsbereich ausführt, werden an den Eintrag der vertrauenswürdigen Plug-in-Identitäten neben dem Release gebunden, so wie ein Build sie bindet. Bevor einer von ihnen läuft, vergleicht --release die konfigurierten plugins.linter-Anbindungen mit dem Plug-in-Vertrauenseintrag: Ein eingetragenes Plug-in, das die Konfiguration nicht mehr anbindet — ein Linter oder ein Gate —, bricht den Durchlauf ab, und ein aus dem Cache gelesener Linter, dessen Artefakt nicht das eingetragene ist, wird abgelehnt, statt ausgeführt zu werden. Ein aus dem Cache gelesener Linter wird beim Laden auch an seine eingetragene Signatur gebunden: Wo sein Eintrag eine verifizierte Signatur festhält, wird das Signaturmaterial, das dieser Fakt im Cache nennt, erneut geprüft, und der Durchlauf stoppt mit E0144, wenn es fehlt oder abweicht, und mit E0332, wenn es für ein anderes Plug-in als den gelesenen Linter erstellt wurde — eine aus einem anderen Eintrag kopierte signature —, unabhängig davon, was die Signaturanforderung besagt; wo die Vertrauenskonfiguration des Workspace eine Signatur verlangt, stoppt ein Eintrag ohne Signatur — oder kein Eintrag für den Linter, einschließlich eines gelöschten Eintrags — den Durchlauf mit E0331, unter denselben Einstellungen, unter denen aggrega pull ihn als unsigniert ablehnen würde. Jeder der drei nennt seine Abhilfe, aggrega pull --release <release>, das die Signatur des Linters in seiner Registry verifiziert, sie einträgt und das Bundle, das sie nennt, in den Cache legt, wobei eine zwischengespeicherte Kopie, die nicht mehr zu ihrem Digest passt, neu geschrieben wird. Ein Linter, der aus der Kopie im Compiler-Binary bereitgestellt wird, wird nie an die Anforderung gebunden. Dies sind Fehler des Durchlaufs, keine Konventionsbefunde, daher führen sie zum Abbruch, wo ein Befund es nicht täte. Die Geltungsbereiche gesamter Katalog und einzelne Entität nennen kein Release und lesen keinen Eintrag, daher wird ein Linter, den sie aus dem Cache lesen, nur gegen sein zwischengespeichertes Manifest geprüft. Vor alledem nennt --release jeden Rückzug, der für das festgehalten ist, wovon das Release abhängt, als deprecation:-Zeile in den Worten, die aggrega build ausgibt — eine Markierung, die die Lockfile gegen eine gepinnte Referenz festhält, ebenso wie eine, die der Vertrauenseintrag gegen einen Linter oder ein Gate festhält —, sodass der Durchlauf es auch dort meldet, wo eine der obigen Ablehnungen ihn stoppt. Ein Rückzug ändert keinen Befund und keinen Exit-Code, und ein Vertrauenseintrag, der vorhanden ist und nicht gelesen werden kann, stoppt den Durchlauf, statt als einer durchzugehen, der nichts festhält.

Entitätsdisziplin: lokal und Veröffentlichungs-Gate

Der Entitätspfad-Modus läuft mit einem von zwei Schweregraden:

  • Standard (lokal). Führt die Disziplinregeln für den lokalen Entitätsinhalt mit dem Schweregrad warn aus. Kein Registry-Zugriff; die Prüfung der Versionserhöhung wird übersprungen. Verwenden Sie dies beim Verfassen.
  • --pre-publish (Veröffentlichungs-Gate). Ruft die neueste veröffentlichte Nicht-Vorabversion der Entität aus der Registry ab, führt dieselben Regeln mit dem Schweregrad halt aus, klassifiziert zusätzlich die Änderung als PATCH / MINOR / MAJOR und bricht ab, wenn die vorgeschlagene Erhöhung von metadata.version kleiner ist, als die Änderung erfordert. Verwenden Sie dies im Veröffentlichungsablauf vor aggrega push. --pre-publish gilt nur für die Form mit einer einzelnen Entität.

Eine zu große Erhöhung ist immer erlaubt; eine zu kleine führt zum Abbruch. Die erste Veröffentlichung einer Entität (keine vorherige Version in der Registry) überspringt die Erhöhungsprüfung und gibt eine Warnung aus, dass keine Überprüfung durchgeführt wurde.

Welche Arten der Entitätsmodus prüft

Der Entitätsmodus lintet das Dokument, das Sie nennen, unabhängig von seiner Art, und übergibt es jeder Regel, die eine einzelne Entität liest. Jede Regel entscheidet selbst, welche Arten sie beschreibt, und eine Regel, der eine Art übergeben wird, die sie nicht beschreibt, meldet nichts. Wenn Sie also ein Aggregate, ein Manifest, ein Release oder eine Workload nennen — Arten, die der Durchlauf über den gesamten Katalog übergeht und in seiner Zeile not checked: aufführt —, laufen die Regeln auch darüber, und nur die Regeln, die diese Art beschreiben, können etwas melden:

RegelArten, zu denen sie im Entitätsmodus meldet
AnnotationspräfixJede Art: Sie liest metadata.annotations unabhängig von der Art des Dokuments.
Direkte x-aggrega-*-ErweiterungenJede Art: Sie liest spec.schema unabhängig von der Art des Dokuments.
NamensformComponent, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary und ArtifactLibrary.
Kategorie entspricht dem VerzeichnisComponent.
Geheimnis-Slot deklariert sensitiveComponent und Feature.
Annotation der Metrik-Anmeldedaten entspricht providesComponent.
Von der Component deklarierte ProvidesRecipe.
Dynamische Refs, Id-ÜberschreibungenSchemaLibrary.
Standardgrenzen des PluginPlugin.
Der Vergleich der Versionserhöhung (--pre-publish)Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate und Plugin (ein in den Compiler eingebautes Plug-in wird nicht verglichen); eine Änderung an jeder anderen Art wird als MAJOR eingestuft.
Verbindungs-Anmeldedaten entsprechen dem ZielschlüsselKeine: Sie liest ein ganzes Release und läuft daher nur unter --release.

Ein Aggregate, ein Manifest, ein Release und eine Workload deklarieren in ihren Schemas weder metadata.annotations noch spec.schema, daher erhält ein Dokument einer dieser Arten, das dem Schema seiner Art entspricht, von den beiden Regeln, die jede Art lesen, keinen Befund; diese beiden melden etwas dazu nur, wenn es trotzdem einen dieser Schlüssel trägt, den das Schema seiner Art als unerwartete Eigenschaft ablehnt. Was das Nennen eines Aggregate hinzufügt, ist der Vergleich der Versionserhöhung unter --pre-publish, der es mit seiner veröffentlichten Version vergleicht, wie das Bewertungsschema unten beschreibt.

Das Bewertungsschema für Versionserhöhungen

Im Modus --pre-publish wird die Änderung mit der vorherigen veröffentlichten Version verglichen und klassifiziert:

  • PATCH — Änderungen nur an Dokumentation oder Kommentaren.
  • MINOR — rein additive Änderungen (ein neues optionales Feld, ein neuer Eintrag).
  • MAJOR — Entfernungen, Typeinschränkungen oder ein zuvor optionales Feld, das erforderlich wird.

Der Vergleich erfolgt pro Entitätsart: Component, Feature und SchemaLibrary werden unter Berücksichtigung ihrer schematragenden Felder verglichen; MappingLibrary wird auf Ebene der Eintragsschlüssel verglichen (Eintragsinhalte sind opak, daher wird ein geänderter Inhalt vorsichtshalber als MAJOR behandelt); Recipe und FeatureRecipe werden anhand ihrer tragenden Felder verglichen. Ein Aggregate wird anhand seiner Parameterdeklarationen, seiner Komponenten und seiner Subsysteme verglichen; der Standardwert eines Parameters erreicht den Vergleich ebenso wenig wie jeder andere Parameterwert (siehe Was ein Linter-Plug-in übergeben bekommt), daher ist eine Änderung, die sich auf einen Standardwert beschränkt — ihn hinzuzufügen, zu ändern oder zu entfernen —, nicht Teil davon, und ebenso wenig eine Änderung an einem Schlüssel außerhalb des Vokabulars der Parameter-Slots. Eine zu kleine Erhöhung führt zum Abbruch mit einer Diagnose, die die erforderliche Erhöhung nennt.

Die Disziplinregeln

Die meisten Regeln haben eine Workspace-Einstellung unter lint.publishing_discipline in .aggrega-config.yaml und eine passende CLI-Überschreibung, wobei jede Überschreibung ein --no--Gegenstück hat. Die Rangfolge ist --no-<flag> vor --<flag> vor dem Wert der Workspace-Konfiguration, in jedem Geltungsbereich: gesamter Katalog, ein Release und eine einzelne Entität. Jede Regel ist standardmäßig aktiv, und jeder Standard beruht entweder auf Plattformmechanik oder auf einer dokumentierten Katalogkonvention; die Einstellungen sind Opt-outs für einen Workspace, der einen Grund hat, eine davon zu lockern.

Die Regeln ohne Einstellung sagen dies in ihrem Eintrag unten, und der Grund ist jeweils derselbe: Sie melden einen Fakt über die Entität und überlassen die Entscheidung dem Autor, sodass es kein Urteil zu lockern gibt. Auch das oben beschriebene Bewertungsschema für Versionserhöhungen hat keine — es vergleicht den vorgeschlagenen Inhalt mit der veröffentlichten Version und meldet, was die Änderung erfordert, was eine Eigenschaft der Änderung ist und keine Präferenz des Workspace.

  • Annotationspräfix — reservierte Namensräume (aggrega.ai/ sowie feature.aggrega.ai/ außerhalb eines Feature) gehören der Plattform und werden bei anderen Schlüsseln abgelehnt. Standardmäßig aktiv; Opt-out mit allow_aggrega_ai_prefix.
  • Namensform — jede Entitätsart hat eine Konvention für die Namensform (Segmentanzahl für die Cloud-nativen Arten; PascalCase für Bibliotheksarten). Standardmäßig aktiv; Opt-out mit allow_nonstandard_names.
  • Dynamische Referenzen — SchemaLibrary-Einträge dürfen $dynamicAnchor / $dynamicRef nicht verwenden (die $ref-Expansion der Plattform zur Kompilierzeit kann sie nicht auflösen). Standardmäßig aktiv; Opt-out mit allow_dynamic_refs.
  • Id-Überschreibungen — SchemaLibrary-Einträge dürfen keine eigene $id deklarieren (die Plattform leitet die kanonische $id ab). Standardmäßig aktiv; Opt-out mit allow_id_overrides.
  • Kategorie entspricht Verzeichnis — das Label component.aggrega.ai/category einer Component muss dem ersten Verzeichnissegment unter core/ entsprechen, aus der geschlossenen Kategoriemenge (ai-agent, ai-model, ai-tool, ai-pipeline, datastore, gateway, mesh, network, messaging, storage, compute, observability, security, bigdata, devtool). Standardmäßig aktiv für Entitäten unter einem core/-Pfad; Opt-out mit allow_category_mismatches.
  • Direkte x-aggrega-*-Erweiterungen — das direkte Verfassen von x-aggrega-*-Schlüsseln in einem Component- oder Feature-Schema wird zugunsten des erstklassigen Verfassungswegs nicht empfohlen. Standardmäßig aktiv; Opt-out mit allow_direct_x_aggrega_extensions.
  • Von der Component deklarierte Provides — das spec.provides eines Recipe veröffentlicht einen Schlüssel pro Eintrag, und die Component, die das Recipe implementiert, deklariert in der provides-Säule ihres spec.schema, welche Schlüssel der Typ bereitstellt. Gegen diese Deklaration wird eine inject-from:-Referenz geprüft, sodass ein Schlüssel, den ein Recipe veröffentlicht, ohne dass die Component ihn deklariert, erzeugt und dann dort abgelehnt wird, wo ein Konsument ihn verdrahtet. Eine Veröffentlichung über den deklarierten Vertrag hinaus wird zur Build-Zeit akzeptiert, weshalb der Befund beratend und keine Ablehnung ist. Standardmäßig aktiv für Recipes; Opt-out mit allow_undeclared_recipe_provides.
  • Standardlimits eines Plugin — das spec.runtime eines Plugin trägt maxMemoryPages und timeoutMs, die beiden Obergrenzen, die der Host anwendet, wenn er das Plug-in lädt und ausführt. Ein Plugin, das keine der beiden festlegt, läuft unter den Plattformstandards, was ein sicheres Ergebnis und kein Fehler ist; die Regel meldet daher, dass die Standards gelten und dass explizite Obergrenzen zum Festlegen verfügbar sind. Standardmäßig aktiv für Plugin-Entitäten; sie hat keine Einstellung.
  • Geheimnis-Slot deklariert Sensibilität — ein Anbindungs-Slot kann über seinen Label-Selektor die Art des Feature, das ihn füllt, auf secret festlegen und separat sensitive: true deklarieren, um festzuhalten, dass alles, was ihn füllt, geheimes Material verarbeitet. Der Selektor gibt an, welche Füllungen zulässig sind; die Markierung gibt die Verarbeitung an. Ein Slot, der die Art festlegt und keine Markierung deklariert, überlässt es, diese Verarbeitung aus dem Selektor neu abzuleiten, statt sie direkt zu lesen. Die Regel liest jeden Slot, den eine Entität deklariert: die ihres eigenen Anbindungsblocks unter spec.featuresSchema und, bei einer Component, die, die jeder Abhängigkeits-Socket unter spec.usesSchema.<socket>.featuresSchema für die über ihn geführten Verbindungen deklariert — ein Befund zu einem Slot eines Sockets nennt neben dem Slot auch den Socket. Standardmäßig aktiv für Components und Features; sie hat keine Einstellung.
  • Verbindungs-Credential entspricht dem Schlüssel des Ziels (connection-credential-matches-target-key) — ein Server, der einen Schlüssel prüft, hält den Schlüssel, den er verifiziert, in einem Slot seiner eigenen Component, und ein Aufrufer präsentiert einen Schlüssel auf der Verbindung, über die er den Server erreicht. Keines der beiden Enden sieht die Anhänge des anderen, sodass die beiden nur deshalb einen gemeinsamen Schlüssel halten, weil ihre Autoren ihn an beiden Enden schreiben — meist, indem beide Anhänge denselben Parameter lesen —, und ein Build vergleicht sie nie. Diese Regel tut es, und sie ist die einzige Regel, die ein ganzes Release liest, daher läuft sie unter --release und in keinem anderen Geltungsbereich. Sie findet beide Enden über die Namen, die der Standardkatalog ihnen gibt: Der Schlüssel des Ziels ist der Slot api_key, den seine Component in spec.featuresSchema deklariert, und der des Aufrufers ist der Slot credential auf der Verbindung, geschrieben unter uses.<socket>.<alias>.features.credential im Aggregate oder auf einer Verbindung, die das Release verdrahtet. Für jede Verbindung, deren Ziel api_key deklariert und nicht als managed gekennzeichnet ist, meldet sie eine Verbindung, die ein Credential an ein Ziel trägt, dessen Schlüssel-Slot nicht befüllt ist, einen befüllten Schlüssel-Slot ohne Credential auf der Verbindung sowie zwei Enden, die ihr Geheimnis unterschiedlich benennen. Verglichen wird der Locator jedes Endes — der origin, den ein Anhang schreibt, in values im Aggregate oder in infra im Release — so, wie der Autor ihn geschrieben hat, sodass zwei Enden, die denselben Parameter lesen, als gleich gelten und zwei Literale nach ihrem Text verglichen werden; nichts wird aufgelöst, und ein Befund nennt die Komponente, die Verbindung, das Ziel und die beiden Slots, zitiert aber nie einen der beiden Locator, da der dort geschriebene Text das Geheimnis selbst sein kann. Ein Ziel, das keinen api_key-Slot deklariert, erzeugt nichts, und ein Slot, der nicht der Aufruferschlüssel ist, etwa das Registry-Pull-Token eines Modellservers, wird nie gelesen. Ebenso wenig wird ein Ziel beurteilt, dessen Component mit component.aggrega.ai/hosting: managed gekennzeichnet ist, was auch immer sein api_key-Slot enthält: Eine solche Component steht für einen Dienst, den ihr Anbieter betreibt, sodass nichts, was das Release ausführt, einen Schlüssel an ihr prüft, und wo sie api_key deklariert — etwa den Schlüssel zu einer gehosteten Modell-API unter dem Namen, den das Produkt des Anbieters ihm gibt —, hält der Slot den Schlüssel, den das Release diesem Anbieter präsentiert, nie einen, den ihre Aufrufer präsentieren. Ein Ziel, das als self-hosted, external oder mixed gekennzeichnet ist oder kein Hosting-Label trägt, wird beurteilt. Eine Verbindung auf dem Socket scrape_target — dem Namen, den der Standardkatalog dem Socket gibt, über den ein Metrik-Scraper seine Ziele erreicht — ist ein Scrape, und ob das Credential eines Scrapes der Aufruferschlüssel des Ziels sein sollte, hängt vom Produkt des Ziels ab: Manche liefern ihre Metriken ohne Credential aus, manche stellen sie hinter den Schlüssel, den jeder Aufrufer präsentiert, und manche verlangen ein eigenes Token. Für einen Scrape liest die Regel daher, was die Component des Ziels in ihrer Annotation observability.aggrega.ai/metrics-credential angibt: Bei none wird der Scrape überhaupt nicht beurteilt; bei separate-token wird sein Credential nie mit dem api_key des Ziels verglichen, sodass keiner der drei Befunde für ihn gemeldet wird; bei target-key wird er wie jede andere Verbindung beurteilt. Die Regel liest nur diese drei Werte, sodass ein Scrape zu einem Ziel ohne die Annotation oder mit einem anderen Wert wie jede andere Verbindung beurteilt wird — und jede Verbindung auf einem anderen Socket, einschließlich einer Modell-, Tool- oder Datastore-Verbindung, wird gleich beurteilt, was auch immer die Annotation des Ziels besagt. Sie liest die Anhänge, die am Ziel und an der Verbindung geschrieben sind: Ein api_key-Anhang, der das Ziel stattdessen von einem Subsystem oder einer Grenze aus erreicht, lässt diese Verbindung unbeurteilt, einer, den eine Annotation hinzufügt, gehört nicht dazu, sodass ein nur auf diese Weise befüllter Schlüssel-Slot als unbefüllt gilt, ein Ende, dessen Anhang keinen Locator schreibt, wird nur darauf verglichen, ob es befüllt ist, und eine Komponente, die ein importiertes Modul beisteuert, wird nicht gelesen. Da die Slot-Namen, das Hosting-Label, der Name des Scrape-Sockets und die Metrik-Annotation Katalogkonventionen sind, die kein Schema-Schlüsselwort kennzeichnet, erzeugt ein Katalog, der die Slots anders benennt, nichts, ein anders benannter Scraping-Socket wird wie jeder andere Socket beurteilt, und eine Component, die den Schlüssel eines Anbieters in einem Slot namens api_key ohne das managed-Label hält, wird als Ziel gelesen, das diesen Schlüssel prüft, da der Name des Slots, das Label und die Annotation alles sind, was die Regel von der Component eines Ziels liest. Standardmäßig aktiv; abschaltbar mit allow_connection_credential_mismatches.
  • Metrik-Credential-Annotation entspricht provides (metrics-credential-annotation-matches-provides) — eine Component kann zwei Tatsachen über ihre Metriken angeben. Ihre Annotation observability.aggrega.ai/metrics-credential gibt an, wie sich die Metriken des Produkts authentifizieren: none, sie werden ohne Credential ausgeliefert; target-key, sie verlangen den Schlüssel, den die Component von jedem Aufrufer verlangt, den ihr api_key-Slot hält; separate-token, sie verlangen ein eigenes Token. Der provides-Schlüssel metrics_credential_required, deklariert in der provides-Säule ihres spec.schema, ist das, was jede ihrer Recipes veröffentlicht, um anzugeben, ob die Metriken einer Instanz ein Credential benötigen — was davon abhängen kann, wie die Instanz konfiguriert ist, da Metriken hinter dem Aufruferschlüssel nur eines benötigen, solange ein Schlüssel angehängt ist, sodass die Annotation ihn nicht ersetzen kann. Die beiden geben eine einzige Tatsache über das Produkt an, daher verlangt diese Regel, dass sie übereinstimmen: Eine mit none annotierte Component, die den Schlüssel deklariert, und eine mit target-key oder separate-token annotierte, die ihn nicht deklariert, werden jeweils gemeldet, und der Befund nennt die Component, den Wert der Annotation und den Schlüssel, der überzählig ist oder fehlt. Eine Component ohne die Annotation oder mit einem anderen Wert erzeugt nichts. Die Regel liest die Component so, wie sie geschrieben ist, sodass eine Component, die eine andere erweitert — deren Schema das ihrer Basis ist —, nichts erzeugt und ihre Basis dort gelesen wird, wo sie deklariert ist, und eine provides-Säule, die als Referenz, als Komposition oder als als Text geschriebener maskierter Körper geschrieben ist, kann sie nicht aufzählen, sodass auch diese Component nichts erzeugt. Standardmäßig aktiv für Components; sie hat keine Einstellung.

Die Unveränderlichkeit von Artefakten ist keine dieser Regeln, und sie hat keine Einstellung. Ein veröffentlichtes name:version ist endgültig: aggrega push vergleicht den unter diesem Tag bereits veröffentlichten Digest mit dem Digest, den der zu pushende Inhalt ergeben würde, und weigert sich, ihn mit anderem Inhalt zu überschreiben. Ein erneuter Push byteidentischen Inhalts lädt nichts hoch und hängt nur an, was dieser Veröffentlichung noch fehlt — ihr Veröffentlichungsdatum und, wo der Push signiert, ihre Signatur. Kein Flag und keine Einstellung der Workspace-Konfiguration lockert dies, weil die Registry keinen Überschreibpfad bereitstellt, für den sich ein Betreiber entscheiden könnte. Geänderter Inhalt wird unter einer neuen Version veröffentlicht; --pre-publish ist das, was diese Versionserhöhung gegen das vorherige Release prüft.

Die Override-Flags pro Regel gelten pro Aufruf und haben bewusst keine Umgebungsvariable — sie sind bereits in .aggrega-config.yaml unter lint.publishing_discipline durch die Konfiguration abgedeckt. Das allgemeine AGGREGA_*-Vorrangmodell ist in environment-variables.md beschrieben.

Build-Zeit und Veröffentlichungszeit

Die Regel, die von x-aggrega-* abrät, läuft auch während aggrega build, wo sie als Warnung erscheint; aggrega lint --pre-publish stuft denselben Befund zu einem Fehler hoch. Lokale Builds tragen den Hinweis; das Veröffentlichungs-Gate setzt ihn durch.

Während Sie schreiben, in Ihrem Editor

Ihr Editor stellt zwei verschiedene Fragen zu einer Katalogentität, und es sind die beiden, mit denen diese Seite beginnt. Ist die Entität korrekt — lässt sie sich parsen, lösen sich die Säulen auf, lässt sie sich rendern? Das ist aggrega validate, und eine Editorsitzung beantwortet diese Frage immer. Ist die Entität veröffentlichbar — folgt der Name der Konvention, liegt die Datei in dem Verzeichnis, das ihre Kategorie erwartet, stimmen die Annotationspräfixe? Das sind diese Regeln, und eine Editorsitzung beantwortet diese Frage nur, wenn Sie danach fragen.

Es ist ausgeschaltet, sofern Sie es nicht einschalten. Schalten Sie es mit serve.lint_on_validate in der .aggrega-config.yaml des Workspaces ein, zu dessen Entitäten Sie die Hinweise erhalten möchten:

serve:
lint_on_validate: true

Dafür gibt es kein Befehlszeilen-Flag, und das ist Absicht: Die Frage betrifft den eigenen Inhalt eines bestimmten Workspaces, und Sie sind derjenige, der diesen Workspace verfasst, nicht derjenige, der den Language Server startet — das tut Ihr Editor.

Ist es eingeschaltet, trägt jede Entität, die Sie validieren, neben den Korrektheitsbefunden auch diese Befunde, jeweils mit dem Namen der Regel, die ihn erzeugt hat. Daraus folgen drei Dinge, und sie machen es während des Tippens nutzbar:

  • Die Befunde bleiben Hinweise. Eine Entität, die eine Konvention verletzt, wird trotzdem validiert, und ihr Release wird weiterhin aufgelöst und gerendert. Das Einschalten der Einstellung fügt eine Ebene von Hinweisen hinzu; es bringt Ihren Editor nie dazu, die Arbeit zu verweigern.
  • Sie können die beiden unterscheiden. Jedes veröffentlichte Problem nennt die Ebene, die es gemeldet hat, sodass ein Benennungsproblem und ein Auflösungsfehler in derselben Datei als zwei verschiedene Dinge erscheinen statt als ein einziges, zweimal gemeldetes Problem.
  • Geprüft wird, was Sie getippt haben. Die Regeln lesen den Puffer statt der Datei auf der Festplatte, sodass ein Name, den Sie korrigieren, nicht mehr gemeldet wird, bevor Sie speichern.

Auf dieser Ebene läuft nur der Modus für lokalen Inhalt: Es wird keine Registry abgefragt, nichts abgerufen, nichts geschrieben. Der --pre-publish-Vergleich wird erreicht, indem man ihn anfordert — Ihr Editor sendet eine Anfrage dafür, so wie Sie --pre-publish im Terminal eingeben — und nie durch Ändern der obigen Einstellung. Eine Prüfung, die bei jeder Berührung eines Dokuments läuft, ist genau der Ort, an dem keine Registry erreicht werden darf, daher bleibt dieser Modus etwas, das Sie aufrufen, statt etwas, das automatisch mitläuft.

Die Prüfung ausdrücklich anzufordern funktioniert unabhängig von der Einstellung, in allen drei obigen Geltungsbereichen. Ein Workspace, der die Ebene pro Bearbeitung nie eingeschaltet hat, kann seinen Editor also dennoch bitten, den Katalog, die Hülle eines Release oder eine einzelne Entität zu durchsuchen — und erhält dieselben Befunde, die dieser Befehl ausgibt. Die Einstellung entscheidet nur, ob die Prüfung auch dort läuft, wo Sie sie nicht namentlich angefordert haben.

Die Protokolldetails verteilen sich auf zwei Seiten: Was die Anfrage bedeutet und wann sie zu senden ist, steht in der aggrega serve-Referenz, und ihre Parameter sowie die Form ihrer Antwort, Feld für Feld, stehen in der Referenz des Wire-Formats.

Den Linter auswählen

Die Regeln werden als standardmäßiges Publishing-Linter-Wasm-Plugin ausgeliefert. Da die Regeln in einem Plugin statt im Compiler liegen, kann ein Unternehmen aggrega lint auf ein anderes Plugin richten, um seine eigene Katalogdisziplin durchzusetzen, ohne den Compiler zu ändern.

Ein Workspace kann unter plugins.linter mehr als einen Linter anhängen, und jeder Anhang läuft: in der Reihenfolge, in der die Anhänge geschrieben sind, jeder an seiner eigenen Einstiegsfunktion, wobei alle ihre Befunde gemeinsam gemeldet werden. Das ermöglicht es einem Katalog, die Standardregeln beizubehalten und eigene daneben hinzuzufügen, statt zwischen beiden zu wählen. --plugin ist die Ausnahme — es führt genau ein Artefakt aus einem Dateisystempfad anstelle der konfigurierten Anhänge aus, was es beim Entwickeln einer Regel nützlich macht.

Eine Anbindung nennt ihr Plug-in mit uri:, und function: nennt eine Einstiegsfunktion in diesem Plug-in. Ein Eintrag, der eine function: und keine uri: nennt, nennt eine Funktion in keinem Plug-in, daher wird die Konfiguration beim Lesen abgelehnt, unter E0224, mit Angabe der Datei und der Position des Eintrags in seiner Liste — fügen Sie die uri des Plug-ins hinzu, das die Funktion exportiert. Ein Eintrag, der keines von beiden nennt, bindet nichts an und wird übergangen; ist er der einzige Eintrag, läuft der Standard-Linter mit seiner eigenen Standard-Einstiegsfunktion, wie ganz ohne plugins.linter.

Was ein Linter-Plugin übergeben bekommt

Kein Parameterwert erreicht ein Linter-Plugin, in keinem Geltungsbereich. Der Wert eines Parameters kann selbst ein Credential sein — der origin eines geheimen Anhangs kann ein Template sein, das einen Parameter liest, den das Release erfüllt, und das Geheimnis ist dann der Wert dieses Parameters —, und das Plugin, das ein Workspace anhängt, kann eines sein, das er nicht geschrieben hat, daher wird jedes Dokument mit zurückgehaltenen Parameterwerten übergeben:

  • Ein Aggregate behält jede Parameterdeklaration und hält darin nur die Schlüssel, mit denen eine Deklaration geschrieben wird — das Parameter-Slot-Vokabular: ihr Typ, ihre Beschreibung und ihre Einschränkungen —, und für jede unter ihren properties, items und valuesType verschachtelte Deklaration gilt dasselbe. Der default der Deklaration wird auf jeder Ebene zurückgehalten, indem der Schlüssel entfernt statt geleert wird, sodass ein Plugin nicht erkennen kann, ob eine Deklaration einen angibt. Ein Schlüssel außerhalb dieses Vokabulars wird mit allem, was er enthält, auf jeder Ebene zurückgehalten: Der Build gibt einem solchen Schlüssel keine Bedeutung, und ein Entwurf, der einen Schlüssel falsch schreibt, kann darunter ein Geheimnis tragen. Ein Eintrag unter parameters, der keine Deklaration ist, wird vollständig zurückgehalten.
  • Jedes Modul, das unter aggregates eines Aggregate aufgeführt ist, verliert seinen parameters-Block, der die an dieses Modul übergebenen Werte enthält.
  • Ein Release verliert seinen parameters-Block, ob es die Werte inline schreibt oder mit $import importiert.
  • Jedes andere Dokument, das unter spec einen parameters-Block trägt, verliert ihn vollständig; keine andere Art deklariert einen.

Dies gilt für die auf der Befehlszeile genannte Entität, für die veröffentlichte Version, mit der --pre-publish sie vergleicht, für jede Entität, die die Durchläufe über den ganzen Katalog und mit --release durchlaufen, und für die Dokumente, die eine Regel erhält, die ein ganzes Release liest. Ein Template, das einen Parameter liest, ist kein Wert und behält seinen Text, sodass eine Regel weiterhin sieht, welchen Parameter ein verfasster Wert liest.

Beispiele

Den ganzen Katalog auf Abweichungen von Konventionen durchsuchen:

aggrega lint --catalog ./catalog

Eine Entität beim Verfassen lokal linten:

aggrega lint core/datastore/postgres/component.yaml

Das Veröffentlichungs-Gate vor der Veröffentlichung einer neuen Version ausführen:

aggrega lint core/datastore/postgres/component.yaml --pre-publish

Eine Regel für einen einzelnen Lauf lockern:

aggrega lint core/datastore/postgres/component.yaml --pre-publish --allow-nonstandard-names

Siehe auch

  • ./aggrega-validate.md — das Gegenstück zur Korrektheit über dieselben drei Geltungsbereiche.
  • ./aggrega-build.md — validiert als Teil der Kompilierung; zeigt den x-aggrega-*-Hinweis mit Schweregrad warn an.
  • ./aggrega-push.md — veröffentlicht eine Entität in der Registry; aggrega lint --pre-publish ist das Gate, das dem vorausgeht.
  • ./aggrega-pull.md — löst Abhängigkeiten auf und pinnt sie.
  • ./aggrega-serve.md — der Language Server, der diese Befunde in Ihrem Editor meldet, und die Einstellung, die die Ebene pro Bearbeitung einschaltet.
  • ../errors/warnings.md — nicht fatale Warnungen, einschließlich der Lint-Befunde im lokalen Modus.

Übersicht

aggrega lint [entity-path] [flags]

Beschreibung

aggrega lint checks publishing CONVENTIONS — naming, category-directory
alignment, annotation prefixes, and the rest of the publishing-linter
discipline. It does not check correctness (schema, pillars, resolution,
render): that is aggrega validate.
Three invocation shapes, mirroring validate:
aggrega lint conventions across every catalog entity
aggrega lint --release <path> conventions across a Release's dependency closure
aggrega lint <entity> publishing discipline for one entity
Without an entity argument, lint runs the structural conventions rules
over every catalog entity found under the catalog directories. Where the
workspace configuration gives its Releases catalog directories of their own
under workspace.releases, it runs them once for each Release, over the
directories that Release reads, and reports each pass under a line naming
its Releases and those directories; Releases reading the same directories
share one pass. With --release it runs them over the entities that
Release's closure reaches, and also runs the rules that read a whole
Release: once, over the Aggregate it deploys, the Release and the
Components the Aggregate's components are instances of, with every
parameter value removed. In both, findings are advisory (warn severity)
and never halt.
With an entity path, lint runs the publishing-linter rule set against
that one entity. In default mode the rules run at warn severity over
local content without consulting any registry. With --pre-publish the
previous registry version is fetched and the schema-evolution
classification is compared against the proposed version bump; mismatches
halt. --pre-publish applies to the single-entity shape only. Per-workspace
policy flags from .aggrega-config.yaml's lint.publishing_discipline block
can be overridden per invocation via the --allow-*/--no-allow-* flag pairs,
in all three shapes.
All three shapes accept -o json, which replaces the human report on standard
output with one structured document: every finding with its severity, the rule
that produced it, its short code (the code printed at the head of its row in
the human report, which aggrega explain expands), its message, and the entity
file it concerns, plus counts by severity. A finding from a rule Aggrega does
not declare, one a linter of your own adds, carries no short code, as its row
prints none. A finding carries a line and column only when the rule that
produced it located the issue that precisely; otherwise the file alone locates
it. The message is the rule's own text, carried through unchanged, so the
structured and human renderings never word a finding differently. The exit
status is the same under either format.

Flags

FlagStandardBeschreibung
--allow-aggrega-ai-prefixfalseErzwingt allow_aggrega_ai_prefix=true
--allow-category-mismatchesfalseErzwingt allow_category_mismatches=true
--allow-connection-credential-mismatchesfalseErzwingt allow_connection_credential_mismatches=true
--allow-direct-x-aggrega-extensionsfalseErzwingt allow_direct_x_aggrega_extensions=true
--allow-dynamic-refsfalseErzwingt allow_dynamic_refs=true für diesen Aufruf
--allow-id-overridesfalseErzwingt allow_id_overrides=true für diesen Aufruf
--allow-nonstandard-namesfalseErzwingt allow_nonstandard_names=true
--allow-undeclared-recipe-providesfalseErzwingt allow_undeclared_recipe_provides=true
--baseline—Vergleicht die Evolutionsprüfung vor der Veröffentlichung mit dieser bestimmten, bereits veröffentlichten Version statt mit der automatisch ausgewählten höchsten Version unterhalb der zu veröffentlichenden; muss ein striktes SemVer-Tag sein, das in der Registry vorhanden ist (erfordert —pre-publish)
--catalog[]Katalogverzeichnis; wiederholbar. Jedes —catalog <dir> wird dem Katalog-Suchstapel vorangestellt (der erste Treffer gewinnt): den catalog_dirs des Workspaces 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-Stamm, sofern es eines gibt. Eine leer geschriebene catalog_dirs-Liste liest überhaupt keinen lokalen Katalog. Wird von den Konventionsdurchläufen über den ganzen Katalog und mit —release verwendet.
--entity—Pfad zur Entitäts-YAML, die gelintet werden soll (alternativ als Positionsargument übergeben)
--no-allow-aggrega-ai-prefixfalseErzwingt allow_aggrega_ai_prefix=false
--no-allow-category-mismatchesfalseErzwingt allow_category_mismatches=false
--no-allow-connection-credential-mismatchesfalseErzwingt allow_connection_credential_mismatches=false
--no-allow-direct-x-aggrega-extensionsfalseErzwingt allow_direct_x_aggrega_extensions=false
--no-allow-dynamic-refsfalseErzwingt allow_dynamic_refs=false für diesen Aufruf
--no-allow-id-overridesfalseErzwingt allow_id_overrides=false für diesen Aufruf
--no-allow-nonstandard-namesfalseErzwingt allow_nonstandard_names=false
--no-allow-undeclared-recipe-providesfalseErzwingt allow_undeclared_recipe_provides=false
--output, -otextAusgabeformat: text|json.
--plugin—Dateisystempfad zum .wasm-Artefakt des Publishing-Linters (führt dieses Artefakt anstelle der plugins.linter-Anhänge des Workspaces aus)
--pre-publishfalseRuft die vorherige Registry-Version ab und prüft die vorgeschlagene Versionserhöhung gegen die Klassifizierung der Schema-Evolution
--release—Pfad zu einer Release-YAML, deren Konventionen über die aufgelöste Abhängigkeitshülle geprüft werden (schließt ein Entitätsargument aus). Ein relativer Pfad wird gegen das Verzeichnis aufgelöst, in dem Sie den Befehl ausführen, nicht gegen den Workspace-Stamm. Liegt dieses Verzeichnis in keinem Workspace und wird kein Stamm angegeben, findet ein absoluter Pfad den Workspace vom eigenen Ordner des Release aus