Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

aggrega validate

aggrega validate verifica la correttezza — schema, struttura dei pilastri, risoluzione dei riferimenti tra documenti, catene extends, capacità del provider rispetto al tipo di input e (per un’entità che esegue un rendering) che il rendering riesca davvero. Ha tre modalità, selezionate dal suo argomento, che applicano la stessa disciplina di correttezza a tre ambiti: l’intero catalogo (nessun argomento), la chiusura delle dipendenze di una singola Release (--release) e il file di una sola entità (un percorso di entità). Ogni ambito risponde alla stessa domanda — «questo contenuto è corretto?» — su una porzione diversa del catalogo.

La correttezza è distinta dalle convenzioni. aggrega validate chiede se il contenuto è ben formato e compilerebbe; aggrega lint chiede se il contenuto segue la disciplina di pubblicazione del catalogo (denominazione, allineamento con la directory di categoria, entità dell’incremento di versione e il resto). I due comandi rispecchiano l’uno i tre ambiti dell’altro, così puoi controllare l’una o l’altra dimensione alla granularità di cui hai bisogno.

aggrega validate non scrive nulla su disco e non legge alcuno stato di runtime. Esegue la stessa risoluzione e la stessa validazione di una build, fermandosi prima del rendering (o, per una singola entità, isolandolo).

Un percorso di entità può essere fornito come argomento posizionale. --release fornito accanto a un percorso di entità non seleziona l’ambito della Release: l’entità viene comunque verificata da sola, nei termini di quella Release — vedi Verificare un’entità nei termini di una Release.

Correttezza dell’intero catalogo (nessun argomento)

aggrega validate senza argomenti carica ogni entità di catalogo nelle directory di catalogo configurate e la verifica da cima a fondo. Prima di caricare qualsiasi cosa legge ogni file YAML in esse, e un documento Aggrega tra questi che non riesce a caricare arresta l’esecuzione, come descritto più avanti. Poi:

  • Struttura dei pilastri dello schema — il blocco spec.schema: di ogni Component e di ogni Feature viene espanso e validato (lo stesso controllo dei pilastri dello schema applicato dalla build), inclusa l’espansione della forma compatta.
  • Risoluzione dei riferimenti tra documenti — i riferimenti $ref e $import verso le voci di una SchemaLibrary vengono risolti, e una SchemaLibrary che non può essere risolta o che non è valida per altri motivi viene rifiutata.
  • Catene extends — ogni entità che dichiara extends si risolve rispetto al proprio padre, e viene verificata la forma unita padre+figlio. Un padre che le directory di catalogo non contengono viene letto dove lo legge una build: dalla cache degli artefatti, secondo il pin che il lockfile di una Release registra per esso — i lockfile delle Releases per cui viene eseguito il passaggio, oppure di ogni Release che il workspace contiene, quando questo viene validato in un unico passaggio. Così una base pubblicata in un registry viene validata non appena aggrega pull l’ha recuperata e fissata, e un padre che nessuno dei due contiene arresta l’esecuzione, indicando aggrega pull --release <release>. Non viene recuperato nulla.
  • Selettori dichiarati — ogni selettore di etichette che un documento Component o Feature dichiara su un socket di dipendenza sotto spec.usesSchema, o su uno slot di allegato sotto spec.featuresSchema — compresi, su un Component, gli slot che un socket dichiara — viene letto rispetto alla grammatica dei selettori, che qualcosa cabli o meno il socket o compili o meno lo slot. Vedi selettori dichiarati.
  • Collisioni di posizione OCI — due identità di catalogo distinte che pubblicherebbero nella stessa posizione del registry vengono rifiutate in modo esplicito, così una build non sovrascrive mai silenziosamente i byte pubblicati di un’entità con quelli di un’altra.
  • Capacità di tipo di input del Provider — una Recipe o una FeatureRecipe che dichiara un blocco workload: associato a un provider che non è in grado di sintetizzare viene segnalata come errore, perché non può mai essere compilata.

Questa è la controparte, a livello dell’intero catalogo, della validazione per Release di una build: il punto in cui un’entità di catalogo difettosa deve emergere, prima che una Release la raggiunga. Si arresta in modo esplicito su un documento Aggrega che non riesce a caricare, e su qualsiasi violazione dei pilastri dello schema, libreria irrisolvibile o non valida, errore di risoluzione di extends, selettore dichiarato che la grammatica rifiuta, collisione di posizione o errore di capacità rispetto al tipo di input. Le segnalazioni di sovrapposizione dei pilastri dello schema e di restringimento in estensione, e ogni parola chiave x-aggrega-* che un Component o una Feature scrive inline nel proprio contenuto di schema, sono righe notice: informative che non cambiano mai il codice di uscita.

Un documento Aggrega che non può essere caricato arresta l’esecuzione. Un file YAML in una directory di catalogo è un documento Aggrega quando una delle sue righe inizia, senza rientro, con apiVersion: e un valore che comincia con aggrega.ai/, tra virgolette o no. Un documento che non può essere letto, il cui YAML non viene analizzato, o il cui kind o metadata non ha la forma dell’envelope di un’entità — un metadata scritto come elenco, per esempio — arresta l’esecuzione con E0175 una volta lette le directory, nominando ogni file di questo tipo con il motivo indicato dalla lettura o dal parser; non viene verificato nulla e non viene stampata alcuna riga catalog validation passed. Un documento che viene caricato e dichiara un kind che nessun catalogo contiene — un Componnent scritto male, per esempio, o nessun kind — arresta la stessa esecuzione con E0371, nominato accanto a quelli con il tipo che dichiara; un Manifest, una Release e un Workload che una Recipe importa dalla propria directory vengono ignorati. Qualsiasi altro YAML — i template di un chart Helm, che non vengono analizzati finché non sono renderizzati, i valori di un chart, le definizioni di workflow — viene ignorato.

Le directory che legge dipendono dalla forma del workspace:

  • Un workspace la cui configurazione non assegna ad alcuna Release directory di catalogo proprie viene validato una sola volta, sul suo stack di ricerca: le directory --catalog, poi workspace.catalog_dirs, poi la directory catalog alla radice del workspace, quando esiste.

  • Un workspace che nomina Releases in workspace.releases può tenere un catalogo in più varianti affiancate, ciascuna letta dalla propria Release, e caricarle tutte insieme metterebbe ogni variante in un unico catalogo, con l’entità di una variante che oscura quella di un’altra. Viene quindi validato una volta per ogni Release contenuta nel workspace, sulle directory che quella Release legge, con le directory --catalog per prime in ogni passata; una Release che la configurazione non nomina legge l’elenco del workspace. Ogni passata viene riportata sotto una riga che ne nomina la Release e le directory lette, seguita dal risultato di quella passata:

    Release release-compose.yaml reads catalog-compose
    catalog validation passed (schema-pillar + library + extends + oci-location)
    Release release-helm-synth.yaml reads catalog-helm-synth
    catalog validation passed (schema-pillar + library + extends + oci-location)

    Le Releases che leggono esattamente le stesse directory condividono un’unica passata, che le nomina tutte. Una Release che non legge alcuna directory — la sua voce scrive catalog_dirs: [] — viene riportata come priva di elementi da verificare, e le altre passate vengono eseguite normalmente. Ogni passata viene riportata qualunque cosa abbia trovato una precedente, poiché un’entità difettosa in una variante non dice nulla di un’altra, e il comando fallisce quando una qualsiasi passata fallisce, nominando le Releases le cui directory hanno fallito. Le Releases contenute in un workspace sono i suoi documenti Release — file YAML il cui kind è Release, ovunque sotto la radice del workspace al di fuori delle directory nascoste e di node_modules, vendor e dist.

Un’esecuzione che non ha nulla da leggere in alcuna passata viene rifiutata anziché riportata come catalogo pulito: metti le entità in catalog/, passa --catalog o imposta workspace.catalog_dirs — oppure, in un workspace che nomina Releases, le catalog_dirs proprie di una Release in workspace.releases. Non enumera mai implicitamente la directory di lavoro corrente, quindi non include mai alberi non correlati.

Lo strumento validate di aggrega mcp, quando gli si chiede l’intero catalogo, valida le stesse passate; in un workspace che nomina Releases la sua risposta riporta ciascuna in passes — le Releases, le directory lette e il verdetto proprio di quella passata — accanto al verdetto complessivo su tutte.

Una libreria che solo la cache degli artefatti contiene

La cache degli artefatti contiene ciò che un fetch vi ha messo, e una SchemaLibrary in cache conta come contenuto di catalogo solo dove una voce nel lockfile di una Release ne garantisce il digest — vedi Che cos’è la cache, e che cosa non è. Quando un $ref: non si risolve in nulla mentre la cache contiene una libreria che nessuna voce di lockfile fissa e che nessuna directory di catalogo letta dal controllo fornisce, il rapporto è seguito da una riga remediation: che nomina ciascuna di queste librerie e l’azione che funziona per l’ambito che non è riuscito:

  • Senza argomenti, e con il percorso di un’entità indipendentemente dal fatto che venga indicato --release, validate legge le librerie solo dalle directory di catalogo, mai attraverso una voce di lockfile, quindi una voce registrata non cambierebbe il suo verdetto. La riga lo dice, e rimanda a scrivere la libreria in una directory di catalogo, oppure ad aggrega pull --release <release> seguito da aggrega validate --release <release>, che verifica la Release rispetto alle librerie fissate dal suo lockfile.
  • Con il solo --release, validate legge il lockfile della Release, quindi la riga nomina aggrega pull --release <release>, che risolve la libreria e ne registra la voce, oppure la scrittura della libreria in una directory di catalogo.

La riga non cambia né il verdetto né il codice di uscita.

Selettori dichiarati

Un Component o una Feature vincola ciò che può essere cablato ai propri socket di dipendenza, e ciò che può compilare i propri slot di allegato, con selettori di etichette — il selector: di ogni voce di spec.usesSchema e di ogni voce di spec.featuresSchema e, su un Component, il selector: di ogni slot che un socket dichiara sotto il proprio featuresSchema. Una build legge un selettore solo dove qualcosa lo raggiunge: un arco tracciato attraverso il socket, un allegato che compila lo slot. Perciò l’ambito dell’intero catalogo e l’ambito della singola entità leggono ogni selettore che un documento Component o Feature dichiara, che qualcosa cabli o meno il socket o compili o meno lo slot, e un selettore che la grammatica rifiuta — una lista di valori a cui manca la parentesi di chiusura, una virgola doppia, una chiave che contiene = o ! — fa fallire il controllo. La grammatica è quella descritta nella grammatica delle stringhe.

Il rifiuto è quello che una build riporta quando raggiunge lo stesso selettore, con lo stesso codice e con le stesse parole: E0007 per il selettore di un socket e E0008 per quello di uno slot, indicando il selettore, il socket o lo slot che lo dichiara e il motivo per cui la grammatica non è riuscita a leggerlo. Viene registrato come difetto del catalogo sul file dell’entità:

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. (violazione del selettore: un selettore dichiarato su un socket che non è stato possibile valutare. Correggi il selettore nella dichiarazione del socket nell’usesSchema del tipo di componente.)

Ogni documento viene letto come l’ha scritto il suo autore, quindi un selettore dichiarato da un’entità base viene riportato una sola volta, sul file stesso della base, anziché una volta per ogni entità che la estende. appliesTo e appliesToAnyOf di una Feature non vengono letti qui: vengono letti ovunque si valuti un allegato della Feature.

L’ambito dell’intero catalogo riporta ogni selettore rifiutato su una propria riga selector: e fallisce indicandone il numero; l’ambito della singola entità li riporta come fallimento del suo livello di forma — con o senza --release accanto al percorso dell’entità, perché quella forma è l’ambito della singola entità eseguito nei termini di una Release (vedi verificare un’entità nei termini di una Release). --release da solo, che valida la chiusura delle dipendenze di una Release, e una build leggono un selettore solo dove lo raggiunge un arco o un riempimento, e lì si arrestano su di esso.

Correttezza limitata a una Release (--release)

aggrega validate --release <release-path> valida esattamente le entità raggiunte dalle dipendenze risolte di una singola Release, anziché l’intero catalogo o una sola entità. Calcola la chiusura attraverso lo stesso meccanismo usato da una build, quindi le entità che verifica sono esattamente quelle che una build di quella Release risolverebbe, e su tale chiusura:

  • risolve le catene extends limitate alla chiusura, fallendo in caso di errore di risoluzione;
  • valida i pilastri dello schema di ogni entità risolta (limitatamente alla chiusura), fallendo in caso di errore nei pilastri dello schema;
  • esegue la stessa verifica di conformità dei valori pre-render eseguita da una build — risolve i parametri della Release nei valori scritti dall’autore (così un valore {{ .parameters.* }} viene verificato come risolto, non come template) e valida il risultato rispetto agli schemi composti della chiusura, inclusa la conformità rispetto allo schema composto genitore+figlio per un’entità che usa extends. Un valore che viola il proprio schema fallisce con un codice di uscita diverso da zero;
  • valuta ogni asserzione di Recipe e FeatureRecipe rispetto ai valori in cui la Release si risolve, come una build le valuta prima di renderizzare: la Recipe di ogni componente viene associata come la mappa il Manifest, i suoi locals e provides vengono risolti, e la prima asserzione che fallisce — una che chiama fail, o una il cui template si ferma su una chiave che non trova — fa fallire la validazione con la condizione e la frase con cui una build si arresta. Anche un template locals o provides che non può essere valutato la fa fallire, come fa fallire una build. Al provider attraverso cui ogni Recipe renderizza viene chiesto il nome che dà alle risorse di quel componente, come lo chiede una build, perché i provides di una Recipe possono leggere quel nome; non viene renderizzato nulla. Queste asserzioni vengono valutate solo quando nulla di quanto sopra è già fallito, quindi una Release riporta il primo errore su cui una build si arresterebbe;
  • fa emergere le segnalazioni di sovrapposizione dei pilastri dello schema e di restringimento in estensione come righe notice: informative che non cambiano mai il codice di uscita;
  • mostra ogni parola chiave x-aggrega-* che un’entità da esso letta scrive inline nel proprio contenuto di schema come riga warning:, una volta per entità, come la mostra una build — e nemmeno questa cambia mai il codice di uscita.

Questo rende --release un vero controllo pre-build: intercetta ciò che una build rifiuterebbe, prima della build — la validazione delle dipendenze della build senza il render. Non esegue alcun render e non avvia alcun pull di rete: la chiusura si risolve dal catalogo locale (e dai pin del lockfile della Release, se presente); un insieme di dipendenze fissate a un registry che richiede un lockfile fa emergere un onesto errore di riferimento irrisolvibile anziché scaricare. Il restringimento viene segnalato come consiglio, mai imposto.

Un lockfile che non corrisponde più a ciò a cui la Release si risolve fa rifiutare la validazione con l’arresto che stampa aggrega build. Dove accanto alla Release si trova un lockfile, --release lo confronta con ciò a cui la Release si risolve, con il confronto di drift che una build esegue prima del rendering, non appena le dipendenze della Release si risolvono e prima che venga eseguito qualsiasi controllo descritto sopra. Un lockfile da cui un’entità fissata, una libreria, un plugin o il file stesso della Release si sono discostati ferma la validazione con il rifiuto E0130 della build — ogni voce che si è discostata, poi l’aggrega pull --release <release> che lo risolve — e un codice di uscita diverso da zero, così una validazione non lascia mai passare un lockfile che la build rifiuta per drift. Senza argomenti, e con un percorso di entità, validate non è vincolato a un lockfile: il controllo dell’intero catalogo legge i pin del lockfile solo per trovare un padre di extends, e il controllo di una singola entità non legge alcun lockfile.

Poiché esegue gli stessi controlli di una build, esegue anche gli stessi plugin di gate collegati — quindi è vincolato allo stesso registro delle identità dei plugin attendibili a cui è vincolata una build. Un workspace che collega un plugin che restituisce un verdetto di accettazione o rifiuto ha un registro di attendibilità dei plugin accanto alla propria Release, e --release confronta la configurazione con esso prima che uno qualsiasi di quei plugin venga eseguito: un gate registrato che la configurazione non collega più arresta la validazione, e un plugin risolto dalla cache popolata da aggrega pull il cui artefatto non è quello registrato viene rifiutato anziché eseguito. Un workspace che non ha registrato nulla non ha alcun registro, il che non cambia nulla per quel confronto. --release nomina inoltre ogni ritiro registrato contro ciò da cui la Release dipende, sullo standard error, come riga deprecation: con le parole che stampa aggrega build: tanto un marcatore che il lockfile registra contro un riferimento fissato quanto uno che il registro di attendibilità registra contro un plugin collegato in un ruolo di verdetto. Un ritiro non cambia né il verdetto né il codice di uscita, e un registro di attendibilità presente che non può essere letto arresta la validazione anziché passare per uno che non registra nulla.

Un plugin letto dalla cache è vincolato anche alla firma che la sua voce registra, come lo vincola una build, nel momento in cui viene caricato. Dove la sua voce registra una firma verificata, il materiale di firma che quel fatto indica nella cache viene verificato di nuovo, e un plugin il cui materiale manca o differisce viene rifiutato — così come uno il cui materiale è stato creato per un plugin diverso da quello letto, che è l’aspetto di una signature copiata da un’altra voce, qualunque cosa dica il requisito di firma. Dove la configurazione di attendibilità del workspace richiede una firma, un plugin letto dalla cache la cui voce non ne registra nessuna — o per il quale il registro non contiene alcuna voce, compreso un registro eliminato — viene anch’esso rifiutato, con le stesse impostazioni che farebbero rifiutare a aggrega pull un plugin non firmato, quindi skip_signature_verification e un registry advisory ne consentono l’esecuzione. Un rifiuto fa fallire la validazione e viene riportato tra le sue diagnostiche, nominando il plugin e aggrega pull --release <release>, il comando che verifica la firma presso il suo registry, la registra e mette in cache il bundle che essa indica, riscrivendo una copia in cache che non corrisponde più al suo digest; un plugin servito da una delle tue directory di catalogo, o dalla copia interna al binario del compilatore, non è mai vincolato al requisito. Gli altri due ambiti non sono vincolati a nulla di tutto ciò: non leggono i collegamenti dei plugin del workspace, quindi nessun plugin del genere viene eseguito in essi.

Lo stesso vale per i plugin che modificano il grafo anziché giudicarlo. Un collegamento label-transform o annotation-transform determina quale sarebbe l’output renderizzato, quindi il lockfile fissa sia la sua identità sia i file sorgente che legge — e --release esegue tali collegamenti come li esegue una build: ricostruiti dal lockfile, vincolando ciascuno al digest registrato e leggendo il contenuto sorgente portato dal lockfile anziché il file su disco. Vale la pena conoscere due conseguenze prima di incontrarle:

  • Collegare un plugin di trasformazione in .aggrega-config.yaml non cambia ciò che fa --release finché non esegui un pull. È la stessa regola seguita da una build, e per lo stesso motivo: l’insieme dei collegamenti è un input che determina i byte, quindi viene adottato al pull anziché nel momento in cui viene modificato.
  • Un plugin in cache i cui byte non corrispondono più al digest registrato dal lockfile viene rifiutato, esattamente come accadrebbe durante una build.

Se la Release non ha un lockfile, --release valida comunque — avvisa che non ha potuto verificare l’identità di un plugin e indica cosa eseguire, anziché rifiutare. Vedi avvisi.

Restituire il grafo compilato

--ir-graph scrive sullo standard output, come JSON, il grafo risolto da questa validazione, prima della riga del verdetto. È additivo: vengono eseguiti gli stessi controlli, vengono scritte le stesse diagnostiche e il codice di uscita è lo stesso che si avrebbe senza. Il grafo restituito è quello su cui è stata eseguita la validazione, quindi non può descrivere una risoluzione diversa da quella su cui riferisce il verdetto.

Si applica solo a questo ambito — gli ambiti dell’intero catalogo e della singola entità guidano un harness sintetizzato anziché una Release, e non risolvono alcun grafo — e richiederlo altrove viene rifiutato anziché ignorato silenziosamente. Se l’esecuzione si ferma prima che il grafo sia risolto, sullo standard output non viene scritto nulla e le diagnostiche del comando stesso dicono cosa l’ha fermata.

Nota il flag accanto. --response-format stabilisce quanta parte del report di questo comando viene scritta (detailed o concise); --ir-graph chiede un secondo documento accanto a quel report. Uno riguarda il volume, l’altro l’oggetto, e nessuno dei due cambia il verdetto.

I valori che un autore ha dichiarato sensibili vengono omessi dal grafo — compresi i values e gli infra di una connessione, dove il socket del componente consumatore dichiara sensibile una foglia — nella forma strutturata descritta in aggrega inspect. --unredacted accanto a --ir-graph li stampa invece, alle condizioni indicate da aggrega inspect --unredacted: raggiunge il grafo e nient’altro di ciò che questo comando scrive, e qualunque destinazione raggiunta dall’output riporta allora quei valori in chiaro. Passato senza --ir-graph viene rifiutato, perché non ci sarebbe nulla da rivelare.

Correttezza di una singola entità (un percorso di entità)

aggrega validate <entity-path> verifica un singolo file di entità di catalogo. Applica una serie di controlli a livelli, arrestandosi al primo errore bloccante così che un errore di schema emerga in modo esplicito prima di qualsiasi lavoro sul catalogo:

  • Segnaposto (ogni tipo) — un valore richiesto dal tipo che il file lascia come stringa vuota. Vengono riportati tutti insieme, prima degli altri controlli, ciascuno con ciò che accetta; vedi segnaposto ancora dovuti.
  • Envelope dello schema (ogni tipo) — l’esatto controllo JSON-Schema per entità che il loader del catalogo esegue a ogni confine di parsing.
  • Forma (ogni tipo) — la validazione strutturale specifica del tipo. Per un Component o una Feature comprende la lettura di ogni selettore di etichette che il file dichiara su un socket di dipendenza o su uno slot di allegato rispetto alla grammatica dei selettori; vedi selettori dichiarati.
  • Struttura dei pilastri (Component e Feature) — il controllo dei pilastri spec.schema:, che usa le SchemaLibraries del catalogo per l’espansione dei $ref tra documenti.

Un Component o una Feature si ferma qui: envelope dello schema, forma e struttura dei pilastri. Un Component isolato non ha values o infra scritti dall’autore da renderizzare in isolamento, quindi non c’è nulla da renderizzare — la sua correttezza è interamente coperta dai livelli di schema e pilastri. Ogni parola chiave x-aggrega-* che il suo contenuto di schema scrive inline viene riportata tra le note informative sullo standard error come riga warning: che nomina la parola chiave, il punto in cui si trova e la tabella dichiarativa da scrivere al suo posto; non cambia mai il verdetto né il codice di uscita.

Una Recipe inoltre viene renderizzata in isolamento. Questo è un aspetto della correttezza della singola entità, non il suo elemento principale: dopo che i livelli di schema e forma sono superati, validate risolve dal catalogo il Component indicato da implements della Recipe, sintetizza un Aggregate, un Manifest e una Release minimi attorno a una singola istanza di quel Component legata alla Recipe in esame, ed esegue su di essi la vera pipeline di compilazione — prima la risoluzione e le guardie (con il render saltato), poi un vero render dell’output isolato. Ogni valore obbligatorio e ogni campo infra obbligatorio privo di default viene riempito con un segnaposto del tipo dichiarato — i valori nell’Aggregate sintetizzato, l’infra nella Release sintetizzata — e ogni altro valore e campo infra prende il default dello schema tramite il resolver; la Release instrada l’istanza in un boundary predefinito sintetizzato e non dichiara alcun values: né alcuna risorsa di calcolo che l’Aggregate non abbia dichiarato. Un segnaposto è un valore accettato dai vincoli dichiarati del campo stesso: la costante o il primo valore elencato da un enum, un numero entro i suoi limiti, una stringa della sua lunghezza e nel suo format, una versione semantica dove il suo pattern ne chiede una, tanti elementi di lista quanti ne richiede, e ogni proprietà richiesta da un oggetto. Qualsiasi altro pattern, una condizione validate: o when:, una composizione di schemi e un vincolo su quali elementi contiene una lista non vengono consultati, quindi un campo che si basa su uno di essi può comunque rifiutare il proprio segnaposto; validate riporta allora quel rifiuto con le parole dello schema stesso. Gli artefatti renderizzati vengono stampati così che un autore veda l’output isolato prima di collegare l’entità a un Aggregate completo. Poiché un harness per una singola entità riempie solo quei campi obbligatori, non collega alcuna connessione e non attacca alcuna Feature, una Recipe i cui template leggono un valore fornito solo da una connessione o da una Feature attaccata non può essere renderizzata in isolamento; validate riporta un render del genere come non tentato anziché fallito. Un’asserzione che chiama fail viene riportata come avviso anziché far fallire il controllo — vedi un’asserzione fallita è un avviso. Un render che si ferma per qualsiasi altro motivo non è stato completato, e validate lo riporta con la diagnostica di render sottostante fino alla frase che nomina ciò che lo ha fermato.

Una Recipe il cui source: deve essere scaricato non viene renderizzata affatto, e una Recipe il cui render si ferma mentre legge un valore fornito solo da una connessione o da una Feature attaccata vede quel render messo da parte — vedi più avanti cosa la correttezza della singola entità non verifica.

Una FeatureRecipe viene verificata per schema e forma; il suo render viene saltato, perché una FeatureRecipe viene renderizzata solo quando è attaccata a un componente host, e non si tenta di sintetizzare un host che superi le guardie per una Feature arbitraria.

Verificare un’entità nei termini di una Release

Un workspace può assegnare a ogni Release directory di catalogo proprie — vedi Assegnare a una Release directory di catalogo proprie — e tenere così affiancate una variante di catalogo per Release. Un percorso di entità indicato da solo viene verificato sulle directory di catalogo del workspace, dove un riferimento a una di quelle varianti — il Component implementato da una Recipe, una SchemaLibrary a cui rimanda un pilastro — non viene trovato. Indica --release accanto al percorso dell’entità e gli stessi controlli vengono eseguiti nei termini di quella Release: i riferimenti dell’entità si risolvono attraverso le directory di catalogo che la configurazione del workspace assegna a quella Release, con eventuali --catalog anteposte, che sono le directory lette da una build di quella Release.

L’esempio MariaDB + Adminer mantiene quattro varianti di questo tipo. Il Component della sua variante synth trae le impostazioni di archiviazione da una SchemaLibrary che solo le varianti synth e chart contengono, quindi viene validato nei termini della Release che compila con esso:

$ aggrega validate catalog-helm-synth/component/mariadb.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/component/mariadb.yaml
Kind: Component
Schema: valid
Pillars: valid

e fallisce, nominando la libreria che non è riuscito a risolvere, nei termini di una Release le cui directory non la contengono — --release release-compose.yaml, oppure nessun --release in un workspace che non elenca directory di catalogo proprie.

Una Recipe viene verificata allo stesso modo. La Recipe della variante synth implementa core/datastore/mariadb, che le directory di catalogo del workspace non contengono, quindi indicata da sola fallisce con render: implements target "core/datastore/mariadb" not found in catalog. Indicando la Release che compila con essa, risolve il Component di quella Release e viene renderizzata in isolamento:

$ aggrega validate catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
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.
Resolution: valid
Render: 3 artifact(s)

seguito dai tre artefatti renderizzati. Ogni variante di quell’esempio dichiara core/datastore/mariadb, quindi la Recipe viene validata nei termini di ciascuna delle sue quattro Releases; nei termini di una Release le cui directory di catalogo non contengono un Component del genere fallisce nominando il target, come accade senza --release. Le righe Attachments: sono spiegate in uno slot di collegamento obbligatorio o un mandato di presenza.

Si tratta sempre dell’ambito della singola entità. I controlli, il report e il codice di uscita sono quelli descritti in questa sezione — un Component o una Feature con un selettore di socket o di slot che la grammatica rifiuta fallisce qui esattamente come senza --release, vedi selettori dichiarati — e nessuna chiusura viene validata: --release nomina la Release attraverso le cui directory di catalogo vengono letti i riferimenti dell’entità, non una chiusura da verificare, ed è per questo che --ir-graph viene rifiutato accanto a un percorso di entità. Un --release che nomina un file inesistente, o una directory, viene rifiutato prima di qualsiasi verifica.

Una directory elencata dalla configurazione del workspace che non è una directory — dove non esiste nulla, per esempio — per quella Release, o per il workspace quando non viene indicato --release, viene rifiutata prima che venga verificato qualsiasi cosa, come la rifiuta ogni comando che legge quel catalogo (Da dove vengono lette le entità locali): il rifiuto nomina la voce, il file di configurazione e la riga che la elenca e l’impostazione, e non viene dato alcun verdetto. Il controllo delle entità dell’editor tramite aggrega serve dà lo stesso rifiuto come unica voce sul file dell’entità, al livello di errore, e lo strumento validate di aggrega mcp rifiuta la chiamata con esso.

Segnaposto ancora dovuti

Un valore richiesto dal tipo che il file lascia come stringa vuota è un segnaposto, e validate lo riporta prima di ogni altra cosa. Un documento abbozzato da aggrega scaffold ne contiene uno ovunque il suo tipo richieda un valore che solo tu puoi fornire, quindi è qui che scopri quali restano. Ecco una FeatureRecipe abbozzata con solo la versione compilata:

Entity: my-feature-recipe.yaml
Kind: FeatureRecipe
2 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).

Tutti i segnaposto nel file vengono nominati insieme, nell’ordine del documento, con la loro riga e colonna e con ciò che accettano. Ciò che accettano viene letto dallo schema stesso del tipo: i valori accettati dove lo schema li elenca, una versione semantica come 1.0.0 dove lo schema ne chiede una, e altrimenti la prima frase della descrizione del campo data dallo schema stesso.

Anche quali valori contano viene letto dallo schema. Un valore conta quando il tipo lo richiede al livello superiore del documento, o all’interno di un oggetto anch’esso richiesto dal tipo, e il file lo imposta alla stringa vuota. Una chiave che il file omette del tutto viene riportata dal controllo dello schema come proprietà mancante. Un campo facoltativo lasciato vuoto non è un segnaposto, né lo è un campo richiesto solo all’interno di una lista o di una mappa che hai scelto di scrivere. Dove lo schema stesso elenca la stringa vuota tra i valori che un campo accetta, una stringa vuota è un valore anziché un segnaposto.

Un valore è dovuto anche dove lo schema lo accetterebbe vuoto. Lo schema ammette una stringa vuota per capability e implements di una Recipe o di una FeatureRecipe, ma una stringa vuota non nomina alcun provider né alcun tipo, quindi validate riporta entrambi come segnaposto come qualsiasi altro. Dove anche il controllo dello schema rifiuta lo stesso file — una versione vuota, un’etichetta di tipo senza valore — il report riporta il codice di quel controllo, E0215, come mostra l’esempio in aggrega scaffold; dove il controllo dello schema lo accetta, come sopra, il report non riporta alcun codice. Una segnalazione nello stesso file che non riguarda un valore vuoto viene comunque riportata, con le parole del controllo dello schema, prima dell’elenco.

Questa lettura appartiene alla validazione della singola entità, con o senza --release accanto al percorso dell’entità. Un’esecuzione sull’intero catalogo che incontra lo stesso documento riporta ciò che riporta il controllo dello schema, quindi una FeatureRecipe con un implements vuoto in una directory di catalogo la supera; nemmeno l’ambito della Release e aggrega build applicano questa lettura.

Un tipo che questo ambito non accetta

La validazione della singola entità accetta Component, Feature, Recipe, FeatureRecipe, Workload e Plugin. Un file di qualsiasi altro tipo viene rifiutato, e il rifiuto nomina i tipi accettati e, per un tipo di entità, l’ambito che verifica effettivamente un documento di quel tipo:

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 it

L’ambito dell’intero catalogo è un’esecuzione senza argomenti, e l’ambito della Release è --release senza percorso di entità:

TipoVerificato da
Aggregateun’esecuzione sull’intero catalogo, quando si trova in una directory di catalogo; --release su una Release che lo distribuisce
Manifest--release su una Release che lo nomina
Release--release <release-path>
SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibraryun’esecuzione sull’intero catalogo, quando si trova in una directory di catalogo

Un’esecuzione sull’intero catalogo legge solo ciò che si trova nelle directory di catalogo configurate, quindi un Aggregate tenuto alla radice del workspace accanto alla sua Release viene verificato tramite --release su quella Release.

Un’asserzione fallita è un avviso

Un’asserzione che chiama fail — dichiarata dalla Recipe o dal Component indicato dal suo implements — viene riportata come avviso, e il controllo non fallisce per essa. La Release sintetizzata contiene segnaposto e default dello schema al posto dei valori impostati da una vera Release, quindi un’asserzione su un tale valore, un’immagine o la presenza di un prerequisito, fallisce qui che la Recipe sia corretta o meno, e validate non può distinguere un’asserzione che attende una Release da una che è difettosa. Il verdetto sull’asserzione è lasciato a una build, che ha sempre una Release.

L’avviso viene scritto sullo standard error, aperto da warning:, dopo eventuali note informative. Riporta il messaggio completo dell’asserzione — l’entità, l’istanza, il nome dell’asserzione e la frase scritta dal suo autore — chiuso da un’ulteriore frase:

A Release must satisfy this assertion before a build of it can pass.

Il report sullo standard output dice dove si è fermata l’esecuzione, e il comando esce con 0. L’asserzione propria di una Recipe ferma il render, quindi il report riporta Render: stopped on a failed assertion, reported as a warning dopo Resolution: valid. L’asserzione di un Component viene valutata prima che qualsiasi cosa venga renderizzata, quindi il report riporta Resolution: stopped on a failed assertion, reported as a warning, seguito da Render: not attempted (the run stopped on that assertion). In entrambi i casi non viene renderizzato nulla, quindi non viene stampato alcun artefatto.

Solo un’asserzione che chiama fail è un avviso. Un’asserzione che si ferma su una chiave che legge ma non trova, o che non viene analizzata, è un difetto nel testo stesso dell’asserzione anziché un’asserzione fallita, ed è giudicata come qualsiasi altro arresto. Ogni altro difetto mantiene il proprio posto come verdetto del controllo.

aggrega build di una Release che non soddisfa l’asserzione si arresta su di essa con un errore, nominando l’asserzione e riportando la frase del suo autore, come sempre, e aggrega validate --release su quella Release fallisce su di essa con lo stesso errore. Il controllo delle entità dell’editor tramite aggrega serve dà lo stesso avviso, posizionato sulla chiave stessa dell’asserzione dove la Recipe la dichiara, e lo strumento validate di aggrega mcp risponde valid: true con l’avviso tra le sue notices.

Cosa la correttezza della singola entità non verifica

Quattro controlli di una vera build sono fuori portata per una build di una sola entità, e validate rinuncia a ciascuno anziché riportare una segnalazione che non può sostenere.

Un sorgente che deve essere scaricato

La validazione di una singola entità non legge alcun lockfile, non legge né scrive alcuna cache e non effettua alcuna richiesta di rete. Una Recipe il cui source: nomina qualcosa recuperato tramite un trasporto — un repository di chart OCI o HTTPS, un repository Git — non ha quindi alcun codice di infrastruttura da cui renderizzare: il chart o il modulo non esiste in nessun luogo raggiungibile dall’esecuzione, e nulla nel file in esame è in difetto. Validate lo dice, lo stampa come esito distinto da un render ed esce con 0:

Entity: catalog/recipe/helm/openbao/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Resolution: valid
Render: 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.

Tutto ciò che si trova sopra quella riga è stato verificato ed è riportato come valido. Il significato del codice di uscita per una tale Recipe è quindi più ristretto rispetto a una che è stata renderizzata — schema, forma e risoluzione reggono; il render non è dimostrato — e il report dichiara quale dei due stai leggendo.

Un sorgente che il workspace già contiene non viene escluso. Un source: ./module relativo non richiede alcun download, quindi il suo render viene tentato come qualsiasi altro, e un fallimento in esso è una vera segnalazione riportata come Render: not completed in isolation con un codice di uscita diverso da zero. La riga sopra compare solo per un sorgente che deve essere recuperato.

Per renderizzare davvero una Recipe con sorgente scaricato, esegui aggrega build su una Release che distribuisce un componente implementato dalla Recipe: una build risolve il sorgente tramite il lockfile della Release e la cache locale, che è ciò che fornisce i byte che validate non ha modo di ottenere.

Un socket uses obbligatorio

Il secondo è se i socket uses required: true del Component indicato da implements sono popolati.

Un socket obbligatorio viene popolato collegando un arco a un altro componente — dal blocco uses dell’Aggregate stesso, o da una Release che collega un socket dichiarato dal Component. L’harness sintetizzato contiene una sola istanza, quindi non contiene alcun secondo componente verso cui un tale arco possa puntare, e nessuna scrittura dei documenti sintetizzati può produrne uno: inventare un peer significherebbe inventare risorse di calcolo che l’harness non ha mai dichiarato. Validate quindi nomina i socket che non ha verificato e prosegue con la risoluzione e il render:

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.

La riga compare solo quando il Component dichiara almeno un socket obbligatorio, e nomina solo quelli obbligatori — un socket facoltativo non viene mai elencato, perché lasciarlo non collegato non è una segnalazione in nessun ambito. Una Recipe il cui Component non dichiara alcun socket obbligatorio non produce una riga del genere, e il suo report resta invariato.

La regola in sé non viene né allentata né duplicata; viene posta nell’ambito che può rispondere. aggrega build la applica integralmente sulle superfici degli archi dell’Aggregate e della Release insieme, e si arresta su un socket obbligatorio che nulla collega. Quindi una Recipe che supera la validazione della singola entità deve comunque soddisfare la regola dei socket obbligatori quando il suo Component viene distribuito, e il report lo dice anziché lasciare una differenza silenziosa tra ciò che validate ha verificato e ciò che verificherà una build.

Uno slot di collegamento obbligatorio o un mandato di presenza

Il terzo è se gli slot di collegamento required: true del Component indicato da implements — i punti di binding con nome dichiarati dal suo featuresSchema — sono riempiti, e se è presente un collegamento di ogni tipo di Feature richiesto dai suoi mandati di presenza.

Uno slot obbligatorio viene riempito attaccando una Feature con quel nome, nell’Aggregate o nella Release, sul componente o in un ambito superiore — dove il Component viene distribuito, non nella Recipe. L’harness sintetizzato non attacca alcuna Feature, quindi nulla di ciò che costruisce può riempire uno slot del genere. Validate quindi nomina gli slot che non ha verificato e prosegue con la risoluzione e il render, esattamente come fa per i socket obbligatori:

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.

La riga compare solo quando il Component dichiara almeno uno slot obbligatorio, e nomina solo quelli obbligatori; una Recipe il cui Component non ne dichiara alcuno non produce una riga del genere. Viene messo da parte solo il requisito: il vincolo di etichetta di uno slot e i suoi meccanismi di consegna consentiti restano come dichiarati. Un template che non viene analizzato fa comunque fallire l’esecuzione, e così un difetto proprio della Recipe come un Workload che il provider non può sintetizzare — a meno che la Recipe legga anche un valore fornito solo da una connessione o da una Feature attaccata, come descrive la sezione successiva.

Un mandato di presenza — un’annotazione features.aggrega.ai/requiredType.<label> sul Component, che richiede che qualche collegamento porti il tipo di Feature che nomina — viene messo da parte per lo stesso motivo: l’harness non attacca nulla, quindi nulla di ciò che costruisce può portare quel tipo. Validate nomina ogni mandato che non ha verificato con la sua etichetta e il tipo che richiede, e prosegue con la risoluzione e il render. example/compute/service della libreria standard ne dichiara uno, quindi la sua Recipe riporta, prima dei suoi due artefatti renderizzati:

$ aggrega validate aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml --catalog aggrega-catalog
Entity: aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: 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: valid
Render: 2 artifact(s)

Un mandato la cui dichiarazione non può essere valutata — il prefisso dell’annotazione senza un’etichetta dopo, o un valore che non è un tipo di Feature — non viene messo da parte: è un difetto proprio del Component, che nessun collegamento ripara, e validate fa fallire l’esecuzione su di esso come fa una build.

Ogni regola viene posta dove può trovare risposta. aggrega pull, aggrega build e aggrega validate --release le valutano entrambe sui collegamenti reali della Release, e ciascuno si arresta su uno slot obbligatorio che nulla riempie e su un tipo imposto che nessun collegamento porta.

Un valore fornito solo da una connessione o da una Feature attaccata

Il quarto è se una Recipe viene renderizzata una volta che le sue connessioni e le sue Features attaccate forniscono ciò che i suoi template leggono.

I template di una Recipe leggono ciò che una connessione consegna in .context.inject e .context.uses, e ciò che una Feature attaccata consegna in .features. L’harness sintetizzato non collega alcuna connessione e non attacca alcuna Feature, quindi ognuna di queste letture non trova nulla: una lettura in .context.inject.env incontra un canale di consegna vuoto, e un range su .context.uses non incontra alcuna connessione. Validate renderizza prima la Recipe, e un render che si completa viene riportato come di consueto. Quando il render si ferma e i template della Recipe — inclusi i file e le voci di libreria che importano — leggono qualcosa sotto quei tre, validate riporta il render come non tentato, nomina i valori che la Recipe legge lì, stampa la frase su cui il render si è fermato ed esce con 0. La variante chart dell’esempio MariaDB + Adminer legge le credenziali del database dal canale di consegna riempito dai suoi due segreti attaccati:

$ aggrega validate catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml --release release-helm-chart.yaml
Entity: catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
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.
Resolution: valid
Render: 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_PASSWORD

Una lettura che non trova nulla e non ferma nulla non viene messa da parte: un range su .context.uses che non renderizza nulla, in un render che si completa, viene riportato come il render che è stato.

A decidere è ciò che la Recipe legge, non ciò su cui il render si è fermato, e questo ha una conseguenza che vale la pena conoscere prima di incontrarla: un difetto proprio della Recipe in una Recipe che legge anche un tale valore — una chiave scritta male, per esempio — viene riportato come non tentato insieme al resto, non come un fallimento. La riga The render stopped: riporta la frase del render stesso così che tu possa vedere di quale si trattava, e una build di una Release che distribuisce il Component giudica il render per intero.

Due difetti fanno comunque fallire l’esecuzione qualunque cosa la Recipe legga, perché nessuna connessione o Feature li cambia: un template che non viene analizzato, e un riferimento che il render rifiuta — una radice che il contesto di render non definisce, o una chiave scritta male sotto una radice la cui forma è fissa, come .context.instance_idd. Un’asserzione dichiarata dalla Recipe che chiama fail non è né messa da parte né un fallimento, qualunque cosa la Recipe legga: viene riportata come l’avviso che un’asserzione fallita è sempre. Una Recipe i cui template non leggono nessuno dei tre ha il proprio render giudicato per intero, e un render che si ferma fallisce con la frase che ne nomina la causa.

Lo strumento validate di aggrega mcp dà lo stesso verdetto sulla stessa Recipe: un render messo da parte in questo modo risponde come valido senza nulla nelle sue diagnostiche, e le righe sopra si trovano nel testo che restituisce accanto ad esse.

Il caricamento del catalogo nella modalità a singola entità è tollerante: un’entità difettosa non correlata altrove nel catalogo viene saltata anziché interrompere il controllo, quindi non impedisce mai di validare il target in isolamento.

Un file saltato spiega comunque un Component che risulta mancante a causa sua. Dove la destinazione implements di una Recipe non viene trovata ed esattamente un file saltato dichiara quel Component, il resoconto si apre con il rifiuto proprio di quel file — il suo percorso, il vincolo che viola e il codice breve della condizione nell’intestazione — seguito da una note: che dice che il file è stato saltato al caricamento, per cui il catalogo non contiene nulla sotto l’identità che esso dichiara, e poi dal fallimento implements target … not found in catalog come motivo per cui il file era necessario. Dove nessun file saltato dichiara quel Component, o più di uno lo dichiara, il fallimento di mancato ritrovamento viene per primo e ogni file saltato è elencato sotto di esso nella sezione note: catalog files skipped at load. Questo è il resoconto che aggrega build dà di un file che ha saltato, e lo danno anche il controllo delle entità dell’editor tramite aggrega serve e lo strumento validate di aggrega mcp. Un catalogo da cui non è stato saltato nulla produce esattamente il resoconto che produrrebbe altrimenti.

Come validate si rapporta a lint e build

I tre comandi coprono tre domande diverse:

  • aggrega validate — è corretto? Schema, pilastri, riferimenti, extends, capacità rispetto al tipo di input e render isolato. Non legge alcuno stato di runtime e non emette artefatti.
  • aggrega lint — segue le convenzioni di pubblicazione del catalogo? Denominazione, allineamento tra categoria e directory, prefissi delle annotazioni, entità dell’incremento di versione e il resto della disciplina di pubblicazione opzionale. Lint rispecchia i tre ambiti di validate ma non verifica mai la correttezza.
  • aggrega build — compila un deployment completo. Build richiede una chiusura completa Aggregate + Manifest + Release ed emette artefatti nativi del provider. Valida la propria chiusura di dipendenze come parte della compilazione, poi esegue il render. aggrega validate --release è quella validazione delle dipendenze da sola, senza il render; validate su singola entità isola il render di una singola Recipe senza un Aggregate completo.

Esempi

Validare l’intero catalogo:

aggrega validate --catalog ./catalog

Validare esattamente ciò da cui dipende una Release, prima di compilarla:

aggrega validate --release releases/production.yaml

Validare una singola entità e — per una Recipe — vederne l’output renderizzato isolato:

aggrega validate core/datastore/postgres/recipes/helm.yaml

Validare una singola entità nei termini di una Release a cui la configurazione del workspace assegna directory di catalogo proprie:

aggrega validate core/datastore/postgres/recipes/helm.yaml --release releases/production.yaml

Vedi anche

  • ./aggrega-lint.md — la controparte per le convenzioni negli stessi tre ambiti.
  • ./aggrega-build.md — compila un Aggregate + Release completo in artefatti; valida la propria chiusura di dipendenze come parte della compilazione.
  • ./aggrega-inspect.md — interroga il grafo IR dopo la risoluzione senza procedere al render.
  • ../errors/warnings.md — le segnalazioni informative che validate fa emergere come righe notice:.

Sinossi

aggrega validate [entity-path] [flags]

Descrizione

Check CORRECTNESS across three symmetric scopes.
With no argument, validate checks the WHOLE catalog: schema-pillar
structure, cross-document library resolution, extends chains, and provider
input-kind capabilities, over every catalog entity. Where the workspace
configuration gives its Releases catalog directories of their own under
workspace.releases, it checks the catalog 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, validate checks the entities a Release's dependency closure
reaches: closure-scoped pillars, extends, and pre-render authored-value
conformance — the same correctness a build applies, scoped to that Release.
It then evaluates the Recipe and FeatureRecipe assertions against the values
that Release resolves to, as a build does before it renders, and reports a
failing assertion as a build reports it. Nothing is rendered.
With an entity path, validate checks one entity file. The kinds it accepts
as a single-entity target are Component, Feature, Recipe, FeatureRecipe,
Workload and Plugin. A value the kind requires that the file leaves empty is
reported first, as a placeholder still owed: every one is named at once, with
what it takes, read from the kind's own schema. That reading is this scope's
alone; 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 compile
against a minimal generated harness, so its resolution, its guards and a
render of its output are all exercised. Where that Recipe's source is one
that 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 cache
and makes no network request, so the chart or module it names is never
retrieved and there is nothing to render from. A render that stops while the
Recipe's templates read what only a connection or an attached Feature
supplies — anything under .context.inject, .context.uses or .features — is
reported as not attempted too: the generated harness wires no connection and
attaches no Feature, so that render cannot be judged there, and a fault of
the Recipe's own beside such a read is set aside with it. A template that
does not parse and a reference the render refuses still fail. An assertion
that calls fail, the Recipe's own or one its Component declares, is printed
as a warning closed by a sentence saying a Release must satisfy it before a
build can pass, and does not fail the check: the generated harness sets none
of a real Release's values, so it cannot tell an assertion waiting on one from
one that is broken, and a build still halts on it. Any other kind is refused here
today, and the refusal names the scope that checks it instead: a whole-catalog
run reaches an Aggregate and the library kinds when they sit in a catalog
directory, and --release reaches a Release, the Manifest it names and the
Aggregate it deploys.
With an entity path and --release together, the entity is checked in that
Release's terms: its references — the Component a Recipe implements, a
library a pillar refers to — resolve through the catalog directories the
workspace configuration gives that Release rather than the workspace's own,
so a workspace keeping one catalog variant per Release checks an entity
against the variant that Release builds with. The checks are the entity
path's; no closure is validated.
The command writes nothing to disk.

Flag

FlagPredefinitoDescrizione
--catalog[]Directory del catalogo; ripetibile. Ogni —catalog <dir> viene anteposto allo stack di ricerca del catalogo (vince la prima corrispondenza): le catalog_dirs del workspace oppure, per una Release a cui la configurazione del workspace assegna directory proprie in workspace.releases, quelle di tale Release; lo stack termina con la directory chiamata catalog alla radice del workspace, quando esiste. Un elenco catalog_dirs scritto vuoto non legge alcun catalogo locale.
--ir-graphfalseScrive anche su stdout, come JSON, il grafo IR calcolato da questa esecuzione, in aggiunta a tutto ciò che questo comando produce già. I valori che un autore ha dichiarato sensibili vengono omessi; passa —unredacted per stamparli invece. Si applica all’ambito —release, l’unico ambito che risolve una Release in un grafo. Seleziona un DOCUMENTO, mentre —response-format stabilisce quanta parte del report di questo comando viene scritta; nessuno dei due influisce sul verdetto o sul codice di uscita
--no-unsupported-field-warningsfalseSilenzia la classe di avvisi sui campi non supportati: le notifiche che un target emette per qualcosa che hai scritto e che non può rispettare — un campo Workload che non può esprimere (come accade per un target a fedeltà inferiore come compose), o un’annotazione aggrega.ai/ su cui non agisce per il tipo di input del nodo. Gli altri avvisi di render continuano a emergere. Solo visualizzazione; non cambia l’output renderizzato. Si applica all’ambito dell’entità, l’unico ambito che esegue il render
--plugin—Percorso di un .wasm grezzo da validare rispetto al suo auto-report describe() — il controllo di authoring prima della pubblicazione. Da solo richiede —type; con un argomento entità Plugin confronta il binario con il tipo dichiarato dall’entità, la dichiarazione di capacità, il mirror dei comandi e il registro delle funzioni host.
--release—Percorso di un YAML di Release. Da solo, valida sulla sua chiusura di dipendenze risolta; con un argomento entità, verifica quell’entità nei termini della Release, con i suoi riferimenti risolti attraverso le directory di catalogo che la configurazione del workspace assegna a quella Release. Un percorso relativo si risolve rispetto alla directory in cui esegui il comando, non rispetto alla radice del workspace. Dove quella directory non appartiene ad alcun workspace e non viene indicata alcuna radice, un percorso assoluto trova il workspace a partire dalla cartella della Release stessa
--response-formatdetailedVolume dell’output per l’ambito —release, la chiusura di una Release senza argomento entità: detailed (predefinito) riporta ogni diagnostica più le righe informative; concise riporta il numero di diagnostiche e solo la prima diagnostica. Il verdetto e il codice di uscita sono identici per entrambi.
--type—Tipo di plugin per un controllo —plugin solo sul binario, verificato rispetto al tipo auto-dichiarato dal binario. Ha senso solo con —plugin; quando un’entità Plugin fornisce il tipo, omettilo (un valore discordante causa un arresto).
--unredactedfalseStampa i valori che un autore ha dichiarato sensibili invece di ometterli. Qualsiasi destinazione raggiunta dall’output — un terminale, una pipe, un file, una registrazione dello schermo — riporta allora quei valori in chiaro. Raggiunge il grafo scritto da —ir-graph e nient’altro, quindi richiede —ir-graph