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

aggrega lint

aggrega lint verifica le convenzioni di pubblicazione — nomenclatura, allineamento tra categoria e directory, prefissi delle annotazioni, disciplina nella scrittura degli schemi e dimensione dell’incremento di versione. Ha tre modalità, selezionate dal suo argomento, che applicano la stessa disciplina delle convenzioni 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à, con un gate di pubblicazione --pre-publish opzionale). Ogni ambito risponde alla stessa domanda — «questo contenuto segue la disciplina di pubblicazione del catalogo?» — su una porzione diversa del catalogo.

Le convenzioni sono distinte dalla correttezza. aggrega lint non verifica mai se il contenuto è ben formato o se verrebbe compilato — questo è compito di aggrega validate, che rispecchia gli stessi tre ambiti per schema, pilastri, risoluzione dei riferimenti, extends, capacità del tipo di input e rendering. Un selettore di socket o di slot che la grammatica dei selettori non riesce a leggere è un difetto di correttezza, quindi lint non ne riporta nulla: validate lo rifiuta, sull’intero catalogo o su un singolo Component o una singola Feature — vedi selettori dichiarati. I due comandi sono complementari: validate ti dice se il contenuto è corretto; lint ti dice se è pubblicabile secondo le convenzioni del catalogo.

aggrega lint è facoltativo. Il compilatore stesso resta privo di opinioni sulla disciplina del catalogo; queste regole vivono in un plugin separato che scegli di eseguire. Un workspace che non esegue mai aggrega lint continua comunque a fare build e a pubblicare.

Il percorso dell’entità può essere fornito come argomento posizionale o con --entity <path>. --release è mutuamente esclusivo con un argomento di entità — selezionano ambiti diversi; passarli entrambi provoca un arresto.

Convenzioni sull’intero catalogo (nessun argomento)

aggrega lint senza argomenti esegue le regole strutturali di disciplina di pubblicazione su ogni entità del catalogo trovata nelle directory del catalogo configurate. I rilievi sono consultivi — riportati con severità warn, non arrestano mai l’esecuzione per un solo rilievo di convenzione. Usalo per passare al setaccio un catalogo alla ricerca di derive di nomenclatura, di categoria e directory e di prefisso delle annotazioni. Un Aggregate, un Manifest, una Release o un Workload in una directory del catalogo viene saltato anziché verificato: il passaggio conta ciascuno di questi tipi su una riga not checked: dopo il proprio riepilogo e ti rimanda alla modalità per entità, che verifica un documento di qualsiasi tipo.

Un file YAML sotto una directory del 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 meno. Un documento Aggrega che non può essere letto, il cui YAML non si riesce ad analizzare, o il cui kind, metadata o spec non ha la forma che assume l’involucro di un’entità — un metadata scritto come elenco, ad esempio — arresta l’esecuzione con E0175 una volta lette le directory, nominando ogni file di questo tipo con il motivo fornito dalla lettura o dal parser; non viene verificato nulla e non viene stampata alcuna riga conventions checked. Un documento che si carica e dichiara un kind che nessun catalogo contiene — un Componnent scritto male, ad 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 si possono analizzare finché non vengono renderizzati, i values di un chart, le definizioni di workflow — viene ignorato. --release si arresta allo stesso modo su un documento di questo tipo sotto le sue directory del catalogo.

Le directory che legge dipendono dalla forma del workspace:

  • Un workspace la cui configurazione non assegna a nessuna Release directory di catalogo proprie viene verificato una sola volta, sul suo stack di ricerca: le directory --catalog, poi workspace.catalog_dirs, poi la directory catalog nella radice del workspace, se esiste.

  • Un workspace che nomina delle Releases in workspace.releases può tenere un catalogo in diverse varianti affiancate, ciascuna letta dalla propria Release, e un singolo passaggio su tutte leggerebbe ogni variante insieme — con l’entità di una variante che oscura quella di un’altra. Per questo viene verificato una volta per ogni Release che il workspace contiene, sulle directory che quella Release legge, con le directory --catalog per prime in ogni passaggio; una Release che la configurazione non nomina legge l’elenco del workspace. Ogni passaggio viene riportato sotto una riga che nomina la sua Release e le directory che ha letto, seguita dai rilievi di quel passaggio e dal suo riepilogo:

    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)

    Le Releases che leggono esattamente le stesse directory condividono un solo passaggio, che le nomina tutte, quindi un rilievo lì viene riportato una sola volta. Una Release che non legge alcuna directory — la sua voce scrive catalog_dirs: [] — viene riportata come priva di contenuti da verificare, e gli altri passaggi vengono eseguiti normalmente. Con -o json, il documento riporta anche passes: i releases, catalogDirs, findings e summary di ogni passaggio, mentre findings e summary di primo livello coprono tutti i passaggi insieme. Le Releases contenute in un workspace sono i suoi documenti di 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 alcun passaggio viene rifiutata invece di essere riportata come catalogo pulito: metti le entità in catalog/, passa --catalog o imposta workspace.catalog_dirs — oppure, in un workspace che nomina delle Releases, il catalog_dirs proprio di una Release in workspace.releases. Non enumera mai implicitamente la directory di lavoro corrente.

Un link sotto una directory del catalogo che porta fuori dal workspace — o fuori da una directory che hai indicato al di fuori di esso — non viene letto, e l’esecuzione si ferma lì, nominando il link, invece di riportare come pulito un catalogo di cui non ha potuto leggere uno dei documenti; una build sulle stesse directory si ferma sullo stesso link. Il confine del workspace espone la regola e i relativi rimedi.

Convenzioni su una Release (--release)

aggrega lint --release <release-path> esegue le stesse regole strutturali sui file delle entità del catalogo raggiunti dalla chiusura risolta di una singola Release, invece che sull’intero catalogo o su una sola entità. Calcola la chiusura con gli stessi meccanismi usati da una build, poi esegue il lint del file di catalogo di proprietà dell’autore di ciascuna entità. Un’entità fissata da un registry che risiede in uno slot della cache non ha alcun file locale da sottoporre a lint e viene saltata — le regole di pubblicazione si applicano ai file scritti localmente. Come nella modalità sull’intero catalogo, i rilievi sono consultivi e non arrestano mai l’esecuzione per un solo rilievo di convenzione.

Questo è anche l’unico ambito che ha in mano un’intera Release, quindi è qui che vengono eseguite le regole che ne leggono una — la regola sulle credenziali delle connessioni descritta in Le regole di disciplina. Una regola di questo tipo viene eseguita una volta per verifica, dopo le regole per entità, su tre documenti: l’Aggregate che la Release distribuisce, così come lo ha scritto il suo autore; la Release, con la sua catena extends incorporata, così che una Release figlia porti ciò che eredita; e, per ogni componente che l’Aggregate dichiara, il Component di cui quel componente è un’istanza, così come lo risolve il catalogo. Tra essi non c’è alcun valore di parametro, come in ogni ambito: la Release arriva senza il suo blocco parameters, compresi i valori che eredita da una base, e l’Aggregate senza i suoi valori predefiniti né i valori che passa a ciascun modulo che importa — vedi Cosa riceve un plugin di linter. I suoi rilievi vengono riportati sotto il file della Release.

Questa è la controparte, sul piano delle convenzioni, di aggrega validate --release, che verifica la correttezza della stessa chiusura.

I linter eseguiti in questo ambito sono vincolati al registro delle identità dei plugin attendibili accanto alla Release, come li vincola una build. Prima che uno qualsiasi di essi venga eseguito, --release confronta gli agganci plugins.linter configurati con il registro di attendibilità dei plugin: un plugin registrato che la configurazione non aggancia più — un linter o un gate — arresta il passaggio, e un linter letto dalla cache il cui artefatto non è quello registrato viene rifiutato invece di essere eseguito. Un linter letto dalla cache è vincolato anche alla sua firma registrata, quando viene caricato: dove la sua voce registra una firma verificata, il materiale di firma che quel fatto nomina nella cache viene verificato di nuovo, e il passaggio si ferma con E0144 se manca o è diverso, e con E0332 se è stato creato per un plugin diverso dal linter letto — una signature copiata da un’altra voce — qualunque cosa dica il requisito di firma; dove la configurazione di attendibilità del workspace richiede una firma, una voce che non ne registra alcuna — o nessuna voce per il linter, compreso un registro eliminato — ferma il passaggio con E0331, con le stesse impostazioni che farebbero rifiutare a aggrega pull un linter non firmato. Ciascuno dei tre nomina il suo rimedio, aggrega pull --release <release>, che verifica la firma del linter nel suo registry, la registra e mette in cache il bundle che nomina, riscrivendo una copia in cache che non corrisponde più al suo digest. Un linter servito dalla copia contenuta nel binario del compilatore non è mai vincolato al requisito. Questi sono errori del passaggio, non rilievi di convenzione, quindi arrestano l’esecuzione dove un rilievo non lo farebbe. Gli ambiti sull’intero catalogo e sulla singola entità non nominano alcuna Release e non leggono alcun registro, quindi un linter che leggono dalla cache viene verificato solo rispetto al suo manifest in cache. Prima di tutto ciò, --release nomina ogni ritiro registrato su ciò da cui dipende la Release, come una riga deprecation: con le stesse parole che stampa aggrega build — tanto un marcatore che il lockfile registra su un riferimento fissato quanto uno che il registro di attendibilità registra su un linter o su un gate — così il passaggio lo segnala anche dove un rifiuto descritto sopra lo arresta. Un ritiro non cambia alcun rilievo né alcun codice di uscita, e un registro di attendibilità che c’è ma non può essere letto arresta il passaggio anziché passare per uno che non registra nulla.

Disciplina delle entità: locale e gate di pubblicazione

La modalità con percorso di entità viene eseguita con una di due severità:

  • Predefinita (locale). Esegue le regole di disciplina sul contenuto locale dell’entità con severità warn. Nessun accesso al registry; il controllo dell’incremento di versione viene saltato. Usala durante la scrittura.
  • --pre-publish (gate di pubblicazione). Recupera dal registry l’ultima versione pubblicata non di pre-release dell’entità, esegue le stesse regole con severità halt e inoltre classifica la modifica come PATCH / MINOR / MAJOR, arrestandosi se l’incremento proposto di metadata.version è minore di quanto richiesto dalla modifica. Usalo nel flusso di pubblicazione, prima di aggrega push. --pre-publish si applica solo alla forma con singola entità.

Un incremento eccessivo è sempre consentito; un incremento insufficiente provoca un arresto. La prima pubblicazione di un’entità (nessuna versione precedente nel registry) salta il controllo dell’incremento e mostra un avviso che segnala che non è stata eseguita alcuna verifica.

Quali tipi verifica la modalità per entità

La modalità per entità esegue il lint del documento che indichi, qualunque sia il suo tipo, e lo passa a ogni regola che legge una singola entità. Ogni regola decide da sé quali tipi descrive, e una regola a cui viene passato un tipo che non descrive non riporta nulla. Quindi indicare un Aggregate, un Manifest, una Release o un Workload — tipi che il passaggio sull’intero catalogo salta ed elenca sulla sua riga not checked: — esegue le regole anche su di esso, e solo le regole che descrivono quel tipo possono riportare qualcosa:

RegolaTipi su cui riporta nella modalità per entità
Prefisso delle annotazioniQualsiasi tipo: legge metadata.annotations qualunque sia il tipo del documento.
Estensioni x-aggrega-* diretteQualsiasi tipo: legge spec.schema qualunque sia il tipo del documento.
Forma del nomeComponent, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary e ArtifactLibrary.
Categoria corrispondente alla directoryComponent.
Slot segreto che dichiara sensitiveComponent e Feature.
Annotazione delle credenziali delle metriche corrispondente a providesComponent.
Provides dichiarati dal ComponentRecipe.
Ref dinamici, override di IdSchemaLibrary.
Limiti predefiniti del PluginPlugin.
Il confronto dell’incremento di versione (--pre-publish)Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate e Plugin (un plugin integrato nel compilatore non viene confrontato); una modifica a qualsiasi altro tipo viene classificata MAJOR.
Credenziale della connessione corrispondente alla chiave di destinazioneNessuno: legge un’intera Release, quindi viene eseguita solo con --release.

Un Aggregate, un Manifest, una Release e un Workload non dichiarano né metadata.annotations né spec.schema nei loro schemi, quindi un documento di uno di questi tipi conforme allo schema del proprio tipo non riceve nulla dalle due regole che leggono qualsiasi tipo; queste due riportano qualcosa su di esso solo quando porta comunque una di quelle chiavi, che lo schema del suo tipo rifiuta come proprietà inattesa. Ciò che aggiunge indicare un Aggregate è il confronto dell’incremento di versione con --pre-publish, che lo confronta con la sua versione pubblicata come descrivono i criteri qui sotto.

La griglia dell’incremento di versione

In modalità --pre-publish la modifica viene confrontata con la versione pubblicata precedente e classificata:

  • PATCH — modifiche alla sola documentazione o ai soli commenti.
  • MINOR — modifiche strettamente additive (un nuovo campo opzionale, una nuova voce).
  • MAJOR — rimozioni, restringimento dei tipi o un campo prima opzionale che diventa obbligatorio.

Il confronto dipende dal tipo di entità: Component, Feature e SchemaLibrary vengono confrontati tenendo conto dei loro campi che contengono schemi; MappingLibrary viene confrontata a livello di chiave delle voci (i corpi delle voci sono opachi, quindi un corpo modificato viene trattato in modo conservativo come MAJOR); Recipe e FeatureRecipe vengono confrontate sui loro campi portanti. Un Aggregate viene confrontato sulle sue dichiarazioni di parametri, sui suoi componenti e sui suoi sottosistemi; il valore predefinito di un parametro non raggiunge il confronto più di quanto lo raggiunga qualsiasi altro valore di parametro (vedi Cosa riceve un plugin di linter), quindi una modifica limitata a un valore predefinito — aggiungerlo, cambiarlo o rimuoverlo — non ne fa parte, e nemmeno una modifica a una chiave al di fuori del vocabolario degli slot dei parametri. Un incremento insufficiente provoca un arresto con una diagnostica che nomina l’incremento richiesto.

Le regole di disciplina

La maggior parte delle regole ha un’impostazione per workspace sotto lint.publishing_discipline in .aggrega-config.yaml e un override CLI corrispondente, ciascun override con una controparte --no-. La precedenza è --no-<flag> su --<flag> sul valore della configurazione del workspace, in ogni ambito: l’intero catalogo, una Release e una singola entità. Ogni regola è attiva per impostazione predefinita, e ogni valore predefinito si fonda o sui meccanismi della piattaforma o su una convenzione documentata del catalogo; le impostazioni sono opzioni di disattivazione per un workspace che ha un motivo per allentarne una.

Le regole che non hanno alcuna impostazione lo dicono nella loro voce qui sotto, e il motivo è lo stesso in ogni caso: riportano un fatto sull’entità e lasciano la decisione all’autore, quindi non c’è alcun giudizio da allentare. Nemmeno la griglia dell’incremento di versione descritta sopra ne ha una — confronta il contenuto proposto con la versione pubblicata e riporta ciò che la modifica richiede, che è una proprietà della modifica e non una preferenza del workspace.

  • Prefisso delle annotazioni — gli spazi dei nomi riservati (aggrega.ai/, e feature.aggrega.ai/ al di fuori di una Feature) sono di proprietà della piattaforma e vengono rifiutati su altre chiavi. Attiva per impostazione predefinita; disattivabile con allow_aggrega_ai_prefix.
  • Forma del nome — ogni tipo di entità ha una convenzione sulla forma del nome (numero di segmenti per i tipi cloud-native; PascalCase per i tipi di libreria). Attiva per impostazione predefinita; disattivabile con allow_nonstandard_names.
  • Riferimenti dinamici — le voci di una SchemaLibrary non possono usare $dynamicAnchor / $dynamicRef (l’espansione di $ref in fase di compilazione della piattaforma non può risolverli). Attiva per impostazione predefinita; disattivabile con allow_dynamic_refs.
  • Override dell’id — le voci di una SchemaLibrary non possono dichiarare un proprio $id (la piattaforma ricava il $id canonico). Attiva per impostazione predefinita; disattivabile con allow_id_overrides.
  • La categoria corrisponde alla directory — l’etichetta component.aggrega.ai/category di un Component deve corrispondere al primo segmento di directory sotto core/, tratto dall’insieme chiuso di categorie (ai-agent, ai-model, ai-tool, ai-pipeline, datastore, gateway, mesh, network, messaging, storage, compute, observability, security, bigdata, devtool). Attiva per impostazione predefinita per le entità sotto un percorso core/; disattivabile con allow_category_mismatches.
  • Estensioni x-aggrega-* dirette — scrivere direttamente chiavi x-aggrega-* in uno schema di Component o di Feature è sconsigliato a favore del percorso di scrittura di prima classe. Attiva per impostazione predefinita; disattivabile con allow_direct_x_aggrega_extensions.
  • Provides dichiarati dal Component — lo spec.provides di una Recipe pubblica una chiave per voce, e il Component che la Recipe implementa dichiara, nel pilastro provides del suo spec.schema, quali chiavi espone il tipo. È rispetto a quella dichiarazione che viene verificato un riferimento inject from:, quindi una chiave che una Recipe pubblica senza che il Component la dichiari viene prodotta e poi rifiutata nel punto in cui un consumatore la collega. Pubblicare oltre il contratto dichiarato è accettato in fase di build, ed è per questo che il rilievo è consultivo anziché un rifiuto. Attiva per impostazione predefinita per le Recipes; disattivabile con allow_undeclared_recipe_provides.
  • Limiti predefiniti del Plugin — lo spec.runtime di un Plugin riporta maxMemoryPages e timeoutMs, i due limiti che l’host applica quando carica ed esegue il plugin. Un Plugin che non fissa nessuno dei due viene eseguito con i valori predefiniti della piattaforma, il che è un esito sicuro e non un errore, quindi la regola riporta che sono in vigore i valori predefiniti e che sono disponibili limiti espliciti da fissare. Attiva per impostazione predefinita per le entità Plugin; non ha alcuna impostazione.
  • Lo slot segreto dichiara la sensibilità — uno slot di aggancio può fissare, tramite il suo selettore di etichette, il tipo di Feature che lo riempie a secret, e può dichiarare separatamente sensitive: true per registrare che qualunque cosa lo riempia gestisce materiale segreto. Il selettore indica quali riempimenti sono ammissibili; il marcatore indica la gestione. Uno slot che fissa il tipo e non dichiara alcun marcatore lascia che quella gestione venga ricavata di nuovo dal selettore invece di essere letta direttamente. La regola legge ogni slot che un’entità dichiara: quelli del proprio blocco di agganci sotto spec.featuresSchema e, su un Component, quelli che ogni socket di dipendenza dichiara sotto spec.usesSchema.<socket>.featuresSchema per le connessioni collegate attraverso di esso — un rilievo su uno slot di un socket nomina il socket oltre allo slot. Attiva per impostazione predefinita per i Components e le Features; non ha alcuna impostazione.
  • La credenziale della connessione corrisponde alla chiave del target (connection-credential-matches-target-key) — un server che verifica una chiave tiene la chiave che verifica in uno slot del proprio Component, e un chiamante presenta una chiave sulla connessione attraverso cui raggiunge il server. Nessuna delle due estremità vede gli allegati dell’altra, quindi le due tengono un’unica chiave solo perché i loro autori la scrivono a entrambe le estremità — di solito facendo leggere a entrambi gli allegati uno stesso parametro — e una build non le confronta mai. Questa regola lo fa, ed è l’unica regola che legge un’intera Release, quindi viene eseguita con --release e in nessun altro ambito. Trova entrambe le estremità tramite i nomi che il catalogo standard dà loro: la chiave del target è lo slot api_key che il suo Component dichiara in spec.featuresSchema, e quella del chiamante è lo slot credential sulla connessione, scritto in uses.<socket>.<alias>.features.credential nell’Aggregate o su una connessione che la Release collega. Per ogni connessione il cui target dichiara api_key e non è etichettato managed, segnala una connessione che porta una credenziale verso un target il cui slot della chiave non è riempito, uno slot della chiave riempito senza credenziale sulla connessione, e due estremità che nominano il proprio segreto in modo diverso. Ciò che confronta è il locatore di ciascuna estremità — l’origin che un allegato scrive, in values nell’Aggregate o in infra nella Release — così come l’autore lo ha scritto, quindi due estremità che leggono uno stesso parametro risultano uguali e due letterali si confrontano per il loro testo; nulla viene risolto, e un rilievo nomina il componente, la connessione, il target e i due slot ma non cita mai nessuno dei due locatori, poiché il testo scritto lì può essere il segreto stesso. Un target che non dichiara alcuno slot api_key non produce nulla, e uno slot che non è la chiave del chiamante, come il token di pull dal registry di un server di modelli, non viene mai letto. Né viene giudicato un target il cui Component è etichettato component.aggrega.ai/hosting: managed, qualunque cosa contenga il suo slot api_key: un tale Component rappresenta un servizio gestito dal suo fornitore, quindi nulla di ciò che la Release esegue verifica una chiave su di esso, e dove dichiara api_key — la chiave di un’API di modelli ospitata, ad esempio, con il nome che le dà il prodotto del fornitore — lo slot contiene la chiave che la Release presenta a quel fornitore, mai una che presentano i suoi chiamanti. Un target etichettato self-hosted, external o mixed, o privo di etichetta di hosting, viene giudicato. Una connessione sul socket scrape_target — il nome che il catalogo standard dà al socket attraverso cui uno scraper di metriche raggiunge i suoi target — è uno scrape, e se la credenziale di uno scrape debba essere la chiave del chiamante del target dipende dal prodotto del target: alcuni servono le proprie metriche senza credenziale, alcuni le mettono dietro la chiave che ogni chiamante presenta, e alcuni accettano un token proprio. Quindi per uno scrape la regola legge ciò che il Component del target dichiara nella sua annotazione observability.aggrega.ai/metrics-credential: con none lo scrape non viene giudicato affatto; con separate-token la sua credenziale non viene mai confrontata con l’api_key del target, quindi nessuno dei tre rilievi viene segnalato su di esso; con target-key viene giudicato come qualsiasi altra connessione. La regola legge solo questi tre valori, quindi uno scrape verso un target senza l’annotazione, o con qualsiasi altro valore, viene giudicato come qualsiasi altra connessione — e ogni connessione su un altro socket, inclusa una connessione a un modello, a uno strumento o a un datastore, viene giudicata allo stesso modo qualunque cosa dica l’annotazione del target. Legge gli allegati scritti sul target e sulla connessione: un allegato api_key che raggiunge il target da un sottosistema o da un confine lascia invece quella connessione non giudicata, uno aggiunto da un’annotazione non è tra questi, quindi uno slot della chiave riempito solo in quel modo risulta non riempito, un’estremità il cui allegato non scrive alcun locatore viene confrontata solo per verificare se è riempita, e un componente fornito da un modulo importato non viene letto. Poiché i nomi degli slot, l’etichetta di hosting, il nome del socket di scrape e l’annotazione delle metriche sono convenzioni del catalogo che nessuna parola chiave dello schema contrassegna, un catalogo che nomina gli slot in modo diverso non produce nulla, un socket di scraping con un nome diverso viene giudicato come qualsiasi altro socket, e un Component che tiene la chiave di un fornitore in uno slot chiamato api_key senza l’etichetta managed viene letto come un target che verifica quella chiave, poiché il nome dello slot, l’etichetta e l’annotazione sono tutto ciò che la regola legge del Component di un target. Attiva per impostazione predefinita; disattivabile con allow_connection_credential_mismatches.
  • L’annotazione della credenziale delle metriche corrisponde ai provides (metrics-credential-annotation-matches-provides) — un Component può dichiarare due fatti sulle proprie metriche. La sua annotazione observability.aggrega.ai/metrics-credential indica come si autenticano le metriche del prodotto: none, sono servite senza credenziale; target-key, accettano la chiave che il Component richiede a ogni chiamante, quella contenuta nel suo slot api_key; separate-token, accettano un token proprio. La chiave provides metrics_credential_required, dichiarata nel pilastro provides del suo spec.schema, è ciò che ciascuna delle sue Recipes pubblica per dire se le metriche di un’istanza richiedono una credenziale — il che può dipendere da come l’istanza è configurata, poiché le metriche dietro la chiave del chiamante ne richiedono una solo mentre una chiave è allegata, quindi l’annotazione non può sostituirla. Le due esprimono un unico fatto sul prodotto, quindi questa regola le obbliga a concordare: un Component annotato none che dichiara la chiave, e uno annotato target-key o separate-token che non la dichiara, vengono ciascuno segnalati, e il rilievo nomina il Component, il valore dell’annotazione e la chiave in eccesso o mancante. Un Component senza l’annotazione, o con qualsiasi altro valore, non produce nulla. La regola legge il Component così come è scritto, quindi un Component che ne estende un altro — il cui schema è quello della sua base — non produce nulla e la sua base viene letta dove è dichiarata, e un pilastro provides scritto come riferimento, come composizione o come corpo con escape scritto come testo non è uno che possa enumerare, quindi neanche quel Component produce nulla. Attiva per impostazione predefinita sui Components; non ha alcuna impostazione.

L’immutabilità degli artefatti non è una di queste regole, e non ha alcuna impostazione. Un name:version pubblicato è definitivo: aggrega push confronta il digest già pubblicato con quel tag con il digest che produrrebbe il contenuto in procinto di essere caricato, e si rifiuta di sovrascriverlo con un contenuto diverso. Ricaricare un contenuto identico byte per byte non carica nulla e allega solo ciò che manca ancora a quella pubblicazione — la sua data di pubblicazione, e la sua firma dove il push firma. Nessun flag e nessuna impostazione della configurazione del workspace allenta questo vincolo, perché il registry non espone alcun percorso di sovrascrittura che un operatore possa scegliere di abilitare. Il contenuto modificato viene pubblicato con una nuova versione; --pre-publish è ciò che verifica quell’incremento rispetto alla release precedente.

I flag di override per regola valgono per singola invocazione e intenzionalmente non hanno alcuna variabile d’ambiente — sono già supportati dalla configurazione in .aggrega-config.yaml sotto lint.publishing_discipline. Il modello generale di precedenza AGGREGA_* è descritto in environment-variables.md.

Fase di build e fase di pubblicazione

La regola che scoraggia x-aggrega-* viene eseguita anche durante aggrega build, dove emerge come avviso; aggrega lint --pre-publish eleva lo stesso rilievo a errore. Le build locali riportano l’avviso; il gate di pubblicazione lo impone.

Mentre scrivi, nel tuo editor

Il tuo editor pone due domande diverse su un’entità del catalogo, e sono le due con cui si apre questa pagina. L’entità è corretta — viene analizzata, i pilastri si risolvono, viene renderizzata? Questo è aggrega validate, e una sessione dell’editor risponde sempre a questa domanda. L’entità è pubblicabile — il nome segue la convenzione, il file si trova nella directory che la sua categoria si aspetta, i prefissi delle annotazioni sono corretti? Queste sono le regole qui descritte, e una sessione dell’editor risponde a questa domanda solo quando lo chiedi.

È disattivato a meno che tu non lo attivi. Attivalo con serve.lint_on_validate nel .aggrega-config.yaml del workspace sulle cui entità vuoi ricevere i consigli:

serve:
lint_on_validate: true

Non esiste alcun flag da riga di comando per questo, ed è una scelta deliberata: la domanda riguarda il contenuto proprio di un particolare workspace, e sei tu a scrivere quel workspace, non chi avvia il language server — lo fa il tuo editor.

Quando è attivo, ogni entità che convalidi riporta anche questi rilievi, ciascuno con il nome della regola che lo ha prodotto, accanto a quelli di correttezza. Ne seguono tre cose, e sono ciò che lo rende utilizzabile mentre scrivi:

  • I rilievi restano consultivi. Un’entità che viola una convenzione viene comunque convalidata, e la sua Release continua a risolversi e a essere renderizzata. Attivare l’impostazione aggiunge un livello di consigli; non fa mai rifiutare al tuo editor di funzionare.
  • Puoi distinguere le due cose. Ogni problema pubblicato nomina il livello che lo ha sollevato, quindi un problema di denominazione e un errore di risoluzione sullo stesso file si leggono come due cose diverse anziché come un unico problema segnalato due volte.
  • Viene controllato ciò che hai digitato. Le regole leggono il buffer anziché il file su disco, quindi un nome che correggi smette di essere segnalato prima che tu salvi.

Su quel livello viene eseguita solo la modalità sul contenuto locale: non si consulta alcun registry, non si scarica nulla, non si scrive nulla. Al confronto --pre-publish si arriva chiedendolo — il tuo editor invia una richiesta apposita, nello stesso modo in cui digiti --pre-publish nel terminale — e mai modificando l’impostazione sopra. Un controllo eseguito ogni volta che tocchi un documento è proprio il punto in cui un registry non deve essere raggiunto, quindi quella modalità resta qualcosa che invochi anziché qualcosa che si aggiunge da sé.

Chiedere esplicitamente il controllo funziona qualunque cosa dica l’impostazione, in tutti e tre gli ambiti sopra. Quindi un workspace che non ha mai attivato il livello per modifica può comunque chiedere al proprio editor di esaminare il catalogo, la chiusura di una Release o una singola entità — e ottenere gli stessi rilievi che stampa questo comando. L’impostazione decide solo se il controllo viene eseguito anche dove non lo hai chiesto per nome.

I dettagli del protocollo sono distribuiti su due pagine: cosa significa la richiesta e quando inviarla è spiegato nella voce aggrega serve del riferimento, mentre i suoi parametri e la forma della sua risposta, campo per campo, sono nel riferimento del formato wire.

Scegliere il linter

Le regole sono distribuite come plugin Wasm standard di linter di pubblicazione. Poiché le regole risiedono in un plugin anziché nel compilatore, un’azienda può indirizzare aggrega lint verso un plugin diverso per imporre la propria disciplina del catalogo senza modificare il compilatore.

Un workspace può allegare più di un linter sotto plugins.linter, e ogni allegato viene eseguito: nell’ordine in cui gli allegati sono scritti, ciascuno con la propria funzione di ingresso, con tutti i loro rilievi riportati insieme. È questo che permette a un catalogo di mantenere le regole standard e aggiungere le proprie accanto a esse invece di scegliere tra le due. --plugin è l’eccezione — esegue esattamente un artefatto da un percorso del filesystem al posto degli allegati configurati, ed è ciò che lo rende utile mentre si sviluppa una regola.

Un aggancio nomina il proprio plugin con uri:, e function: nomina una funzione di ingresso su quel plugin. Una voce che nomina una function: e nessun uri: nomina una funzione su nessun plugin, quindi la configurazione viene rifiutata non appena viene letta, con E0224, nominando il file e la posizione della voce nel suo elenco — aggiungi l’uri del plugin che esporta la funzione. Una voce che non nomina né l’uno né l’altra non aggancia nulla e viene ignorata; dove è l’unica voce, il linter standard viene eseguito con la propria funzione di ingresso predefinita, come avviene senza alcun plugins.linter.

Cosa riceve un plugin di linter

Nessun valore di parametro raggiunge un plugin di linter, in nessun ambito. Il valore di un parametro può essere esso stesso una credenziale — l’origin di un allegato segreto può essere un template che legge un parametro che la Release soddisfa, e il segreto è allora il valore di quel parametro — e il plugin che un workspace allega può essere uno che non ha scritto, quindi ogni documento viene consegnato con i valori dei parametri trattenuti:

  • Un Aggregate mantiene ogni dichiarazione di parametro, conservando solo le chiavi con cui si scrive una dichiarazione — il vocabolario degli slot dei parametri: il tipo, la descrizione e i vincoli — e ogni dichiarazione annidata sotto properties, items e valuesType è trattata allo stesso modo. Il default della dichiarazione viene trattenuto a ogni livello, rimuovendo la chiave anziché svuotarla, quindi un plugin non può sapere se una dichiarazione ne fornisce uno. Una chiave fuori da quel vocabolario viene trattenuta con qualunque cosa contenga, a ogni livello: la build non attribuisce alcun significato a una tale chiave, e una bozza che scrive male una chiave può portare un segreto sotto di essa. Una voce sotto parameters che non è una dichiarazione viene trattenuta per intero.
  • Ogni modulo elencato sotto aggregates di un Aggregate perde il proprio blocco parameters, che contiene i valori passati a quel modulo.
  • Una Release perde il proprio blocco parameters, sia che scriva i valori inline sia che li importi con $import.
  • Qualsiasi altro documento che abbia un blocco parameters sotto spec lo perde per intero; nessun altro tipo ne dichiara uno.

Questo vale per l’entità nominata sulla riga di comando, per la versione pubblicata con cui --pre-publish la confronta, per ogni entità che percorrono i passaggi sull’intero catalogo e con --release, e per i documenti che riceve una regola che legge un’intera Release. Un template che legge un parametro non è un valore e mantiene il proprio testo, quindi una regola vede comunque quale parametro legge un valore scritto dall’autore.

Esempi

Esaminare l’intero catalogo alla ricerca di deviazioni dalle convenzioni:

aggrega lint --catalog ./catalog

Eseguire il lint di un’entità in locale durante la scrittura:

aggrega lint core/datastore/postgres/component.yaml

Eseguire il gate di pubblicazione prima di pubblicare una nuova versione:

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

Allentare una regola per una singola esecuzione:

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

Vedi anche

  • ./aggrega-validate.md — la controparte di correttezza negli stessi tre ambiti.
  • ./aggrega-build.md — convalida come parte della compilazione; fa emergere l’avviso su x-aggrega-* con severità warn.
  • ./aggrega-push.md — pubblica un’entità nel registry; aggrega lint --pre-publish è il gate che lo precede.
  • ./aggrega-pull.md — risolve e fissa le dipendenze.
  • ./aggrega-serve.md — il language server che riporta questi rilievi nel tuo editor, e l’impostazione che attiva il livello per modifica.
  • ../errors/warnings.md — avvisi non fatali, inclusi i rilievi di lint in modalità locale.

Sinossi

aggrega lint [entity-path] [flags]

Descrizione

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.

Flag

FlagPredefinitoDescrizione
--allow-aggrega-ai-prefixfalseForza allow_aggrega_ai_prefix=true
--allow-category-mismatchesfalseForza allow_category_mismatches=true
--allow-connection-credential-mismatchesfalseForza allow_connection_credential_mismatches=true
--allow-direct-x-aggrega-extensionsfalseForza allow_direct_x_aggrega_extensions=true
--allow-dynamic-refsfalseForza allow_dynamic_refs=true per questa invocazione
--allow-id-overridesfalseForza allow_id_overrides=true per questa invocazione
--allow-nonstandard-namesfalseForza allow_nonstandard_names=true
--allow-undeclared-recipe-providesfalseForza allow_undeclared_recipe_provides=true
--baseline—Esegue il diff del controllo di evoluzione pre-publish rispetto a questa specifica versione già pubblicata invece della versione più alta selezionata automaticamente al di sotto di quella in pubblicazione; deve essere un tag SemVer rigoroso presente nel registry (richiede —pre-publish)
--catalog[]Directory del catalogo; ripetibile. Ogni —catalog <dir> viene anteposto allo stack di ricerca del catalogo (vince la prima corrispondenza): i catalog_dirs del workspace oppure, per una Release a cui la configurazione del workspace assegna directory proprie sotto workspace.releases, quelle della Release; lo stack termina con la directory denominata catalog nella radice del workspace, quando esiste. Un elenco catalog_dirs scritto vuoto non legge alcun catalogo locale. Usato dai passaggi delle convenzioni sull’intero catalogo e con —release.
--entity—Percorso dello YAML dell’entità su cui eseguire il lint (in alternativa, passalo come argomento posizionale)
--no-allow-aggrega-ai-prefixfalseForza allow_aggrega_ai_prefix=false
--no-allow-category-mismatchesfalseForza allow_category_mismatches=false
--no-allow-connection-credential-mismatchesfalseForza allow_connection_credential_mismatches=false
--no-allow-direct-x-aggrega-extensionsfalseForza allow_direct_x_aggrega_extensions=false
--no-allow-dynamic-refsfalseForza allow_dynamic_refs=false per questa invocazione
--no-allow-id-overridesfalseForza allow_id_overrides=false per questa invocazione
--no-allow-nonstandard-namesfalseForza allow_nonstandard_names=false
--no-allow-undeclared-recipe-providesfalseForza allow_undeclared_recipe_provides=false
--output, -otextFormato di output: text|json.
--plugin—Percorso nel filesystem dell’artefatto .wasm del linter di pubblicazione (esegue questo artefatto invece degli allegati plugins.linter del workspace)
--pre-publishfalseRecupera la versione precedente dal registry e verifica l’incremento proposto rispetto alla classificazione dell’evoluzione dello schema
--release—Percorso di uno YAML di Release su cui verificare le convenzioni lungo la chiusura delle sue dipendenze risolte (mutuamente esclusivo con un argomento entità). 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