aggrega inspect
aggrega inspect produce una vista leggibile di qualsiasi entità Aggrega — un Component di catalogo, un file di entità scritto da te, un’entità pubblicata in un registry o una Release completamente risolta. È la superficie di debug canonica per capire cosa produrrà il compilatore: quali Components estendono quali basi, quale Recipe corrisponde a ciascun tipo, quali Features si agganciano a ciascun nodo, e da dove provengono esattamente i contributi di ciascuna Feature.
Ogni tipo di entità ha una vista naturale di «contratto». inspect mostra quel contratto — lo schema che un Component pubblica, le mappature che un Manifest dichiara, la topologia che un Aggregate costruisce, gli allegati di Feature per nodo in cui si risolve una Release. Il materiale didattico e concettuale si trova altrove; inspect risponde a «in cosa si risolve effettivamente questa entità?»
Un singolo argomento posizionale viene instradato in base alla forma del contenuto; non serve alcun sottocomando. Il comando smista secondo la seguente euristica:
| Forma dell’identificatore | Smistamento | Output |
|---|---|---|
Inizia con ./, ../ o /, oppure termina con .yaml / .yml | Ramo file | Ispezione per file basata sull’intestazione kind: del file. |
Inizia con oci:// | Ramo registry | L’entità pubblicata a quella coordinata, letta dal suo registry e resa con la vista che riceve un file del suo tipo. Vedi Leggere un’entità pubblicata. |
| Qualsiasi altra cosa | Ramo catalogo | Cerca l’identificatore nello stack di ricerca del catalogo in tutti i tipi di entità; risolve le catene extends:; rende la vista propria del tipo trovato. |
Tre livelli di dettaglio
--list, il livello predefinito e --detail formano una disciplina uniforme di verbosità a tre livelli che ogni tipo rispetta. --list e --detail si escludono a vicenda — passarli entrambi viene rifiutato invece di essere risolto silenziosamente.
--list— solo identificatori. Un Component elenca il suo nome e i nomi dei suoi socket uses; una MappingLibrary elenca i nomi delle sue mappature; un Aggregate elenca i nomi dei suoi componenti con i loro tipi.- predefinito — una panoramica strutturata pensata per l’uso interattivo. Si apre con l’identità dell’entità e, per ogni tipo tranne un Manifest e una Release, con la sua descrizione, dove l’entità ne scrive una; un’entità senza descrizione non ne stampa alcuna invece di stampare una riga vuota. Il resto della forma dipende dal tipo: un Component mostra il suo schema e i suoi socket; un Aggregate mostra i componenti, i loro valori e gli archi con gli allegati che ciascuna connessione porta, e il grafo delle dipendenze; una Release mostra l’albero dei nodi per boundary con gli allegati di Feature, ciascuno di quelli scritti su una connessione elencato sotto quella connessione.
--detail— corpi completi dei campi. Tutto ciò che il tipo contiene: un Component aggiunge i suoi meccanismi di self-inject, le Features richieste e le label; una MappingLibrary espande il corpo completo del template di ciascuna mappatura; una Recipe aggiunge il corpo del suo workload, i provides e le asserzioni.
Alcuni tipi usano i livelli per far emergere progressivamente una parte maggiore di un corpo scritto. Una MappingLibrary a --list mostra i nomi delle mappature; al livello predefinito aggiunge l’esempio d’uso sintetizzato di ciascuna mappatura; a --detail espande il corpo completo del template.
Risoluzione: --raw e --resolved
Ogni tipo ha una profondità di risoluzione predefinita naturale (vedi la tabella sotto). --raw e --resolved sono override sempre disponibili, e si escludono a vicenda — passarli entrambi viene rifiutato invece di essere risolto silenziosamente:
--rawesclude qualsiasi risoluzione — l’entità viene emessa così come è stata scritta, direttamente dal file.--resolvedattiva la profondità di risoluzione completa del tipo.
Per i tipi che per impostazione predefinita sono così come scritti, --raw non ha effetto e --resolved attiva la risoluzione che il tipo supporta. Per i tipi che per impostazione predefinita sono risolti, --raw è il bypass verso la forma scritta.
--raw riproduce il file, quindi un valore che un autore ha dichiarato sensibile vi compare esattamente come è stato scritto. Questo è il contratto, non una lacuna — una vista così come scritta che nascondesse silenziosamente parte di sé non sarebbe così come scritta. Tratta l’output di --raw come tratti il file di entità da cui proviene. --output yaml riproduce il file allo stesso modo, per ogni tipo, Release inclusa.
Una Release risponde a due ulteriori domande, e ciascuna è un documento diverso con il proprio flag. Il grafo compilato in cui si risolve una Release è --ir-graph; la sua chiusura delle dipendenze è --closure. Vedi Output leggibile da una macchina e La chiusura delle dipendenze: --closure più sotto.
Valori predefiniti per tipo
inspect conosce i tipi ispezionabili autonomamente elencati nella tabella seguente. I tipi di catalogo vengono resi così come scritti per impostazione predefinita — i loro file sono contratti autosufficienti. I tipi di istanza hanno per impostazione predefinita una vista risolta, perché il loro YAML scritto è solo il punto di partenza di una cascata o di una pipeline.
| Tipo | Predefinito | Cosa significa «risolto» |
|---|---|---|
| Component | così come scritto | Il file è un contratto autosufficiente; la risoluzione avviene rispetto a un binding del Manifest, mostrata tramite --show-implements. |
| Feature | così come scritto | Come per Component. |
| Recipe | così come scritto | --show-implements risolve il riferimento al Component in spec.implements. |
| FeatureRecipe | così come scritto | --show-implements risolve il riferimento alla Feature in spec.implements. |
| MappingLibrary | così come scritto | Le voci sono stringhe di Go template opache; il rendering avviene al momento del consumo. |
| SchemaLibrary | così come scritto | Le voci sono definizioni riutilizzabili di schema e template risolte al momento del consumo. |
| WorkloadLibrary | così come scritto | Le voci sono corpi di Workload riutilizzabili che una Recipe importa, valutati al momento del consumo. |
| ArtifactLibrary | così come scritto | Le voci sono bundle di artefatti riutilizzabili che una Recipe importa, renderizzati al momento del consumo. |
| Plugin | così come scritto | Il file è un contratto di plugin autosufficiente: tipi di socket, capacità per export, vincoli di runtime e puntatore alla firma. Indirizzabile tramite percorso del file, o tramite la sua coordinata <pluginType>/<name> rispetto al catalogo. |
| Manifest | risolto | Viene applicata la catena extends:; vengono esposte le mappature risolte di componenti e feature. |
| Aggregate | risolto | Viene costruita la topologia — vengono calcolati il grafo uses e l’ordinamento. |
| Release | risolto | Viene eseguita la pipeline completa: risoluzione, espansione delle annotazioni, esecuzione delle guardie, costruzione della topologia, costruzione dell’IR. |
Un file il cui kind: è Workload viene rifiutato: un Workload esiste solo incorporato in una Recipe e non è un’entità ispezionabile autonomamente. Ispeziona una Recipe per vederne il Workload.
Profondità di risoluzione per tipo
La maggior parte dei tipi non ha una pipeline — inspect legge il file e lo rende. Tre tipi di istanza si risolvono in modo significativo:
- Manifest applica la sua catena
extends:— seguendo le importazioni di file — e rende le mappature unite di componenti e feature.--rawmostra il file così come è stato scritto. - Aggregate costruisce la sua topologia: viene costruito il grafo uses e calcolato l’ordinamento delle dipendenze. La vista predefinita mostra i componenti con i loro valori e archi, seguiti dal grafo delle dipendenze.
--rawmostra l’albero dei sottosistemi così come scritto. - Release esegue l’intera pipeline di compilazione fino all’IR — risoluzione, espansione delle annotazioni, esecuzione delle guardie, costruzione della topologia, costruzione dell’IR — e rende l’albero dei nodi per boundary con gli allegati di Feature di ciascun nodo e la loro provenienza. Gli allegati di governance che danno forma al grafo vengono eseguiti in quella pipeline anziché essere saltati per una vista, quindi ciò che leggi riflette ciò che hanno deciso: le label di un allegato
label-transformsono già al loro posto prima che qualcosa venga confrontato con esse, e le annotazioni iniettate da un allegatoannotation-transformsi espandono in allegati di Feature esattamente come un’annotazione scritta da te. Un allegato il cui plugin questo comando non riesce a risolvere lo arresta, invece di lasciarti un grafo disegnato senza le decisioni di quel plugin. Una Release che ne estende un’altra viene disegnata, in questa vista e in--ir-graph, come la Release in cui si compone la sua catenaextends:— quella che legge una sua build — quindi una Release che nomina solo la propria Release padre mostra l’Aggregate, il Manifest e i boundary di quest’ultima sotto il proprio nome. Anche il Manifest nominato da una Release viene composto attraverso la propria catenaextends:, che la Release estenda qualcosa o meno, quindi un allegato la cui mappatura è ereditata da quel Manifest mostra la realizzazione usata da una build.--rawemette il file della Release testualmente senza pipeline.--closurepone una domanda diversa sulla stessa Release e non esegue alcuna pipeline; vedi La chiusura delle dipendenze:--closure.
Non esiste un flag separato per la profondità; il commutatore --raw / --resolved è l’unico controllo della risoluzione, sovrapposto al valore predefinito naturale di ciascun tipo.
Comportamento in caso di errore
Un file correlato referenziato che non si carica arresta subito il comando — una Release che punta a un Aggregate mancante, un’entità di catalogo danneggiata nello stack di ricerca. Si arresta con un messaggio chiaro invece di rendere un output parziale, e non esiste una modalità continue-on-error per un errore di caricamento: una volta che un documento necessario alla risoluzione è illeggibile, non c’è altro da risolvere. Dove la risoluzione di un nome si arresta su un documento di catalogo che il caricamento rifiuta, il messaggio dichiara quel rifiuto una volta sola: un’intestazione che porta la categoria e, dove il rifiuto indica una condizione, il suo codice breve, poi il documento, poi cosa c’è che non va — per un documento che lo schema del suo tipo rifiuta, la riga e il vincolo che viola. Non contiene alcun suggerimento di spostare il file — il catalogo lo ha letto, ed è per questo che è stato rifiutato.
Una Release la cui composizione viene respinta dai controlli del compilatore viene rifiutata invece di essere resa. La risoluzione di una Release costruisce il grafo, e i controlli che una build esegue sul grafo finito — un arco uses: il cui target non soddisfa il selector: del suo socket, una Feature allegata a un componente che il suo appliesTo: non ammette, e gli altri — vengono eseguiti anche qui, con il diagnostico che stampa una build degli stessi documenti. Il rifiuto indica ogni rilievo in un’unica esecuzione invece di fermarsi al primo, così un solo passaggio ti mostra l’intero elenco da correggere invece della sua prima voce. È questo che mantiene il comando onesto su un deployment: una vista che rendesse una composizione rifiutata dalla build segnalerebbe come a posto un workspace che non lo è. Le selezioni che non risolvono nulla non sono interessate — --raw, --output yaml e --closure riproducono o risolvono ciò che hai scritto senza costruire un grafo.
Una Release il cui lockfile non corrisponde più a ciò in cui si risolve viene rifiutata con l’arresto che stampa aggrega build. Dove accanto alla Release si trova un lockfile, ogni selezione che risolve la Release — la vista predefinita, --resolved, --ir-graph e --closure — lo confronta con ciò in cui la Release si risolve, con il confronto di deriva che una build esegue prima di renderizzare. Un lockfile che non corrisponde più arresta il comando con il rifiuto E0130 della build: ogni voce che ha subito una deriva, poi l’aggrega pull --release <release> che la risolve. Nulla viene scritto sull’output standard e il comando termina con un codice diverso da zero, perché una rappresentazione tratta dal catalogo nel suo stato attuale mostrerebbe ciò che nessuna build di quella Release renderizza. --raw e --output yaml da soli non leggono né il lockfile né il catalogo, e non ne sono vincolati. Una Release senza lockfile accanto viene risolta sul catalogo nel suo stato attuale.
Un file il cui kind: non è riconosciuto riporta il tipo sconosciuto e il file da cui proviene. Un file Workload riporta che il tipo esiste solo incorporato e indica l’entità in cui è incorporato. Un identificatore oci:// che non può essere letto viene rifiutato con la condizione che ne indica il motivo; Leggere un’entità pubblicata le elenca.
Risoluzione del catalogo
Lo stack di ricerca del catalogo viene assemblato con una precedenza a strati: prima i flag --catalog (anteposti, in ordine), poi i catalog_dirs del workspace da .aggrega-config.yaml — per una Release a cui la configurazione assegna directory proprie sotto workspace.releases, quelle della Release al loro posto — poi la directory catalog alla radice del workspace, che viene letta indipendentemente dal fatto che qualcosa la indichi. Un workspace il cui catalog_dirs è scritto come lista vuota non legge alcun catalogo locale. Lo stack è first-win — la prima directory a dichiarare un’identità di entità ne è proprietaria; la copia di una directory successiva viene oscurata. Il ramo catalogo risolve l’identificatore rispetto a questo stack in tutti i tipi di entità, con una precedenza fissa, e rende la prima corrispondenza con la vista propria di quel tipo; i rami file e release caricano da esso le entità di catalogo referenziate quando occorre risolvere una mappatura del Manifest o un genitore extends:. Un genitore extends: che lo stack non contiene viene letto dove lo legge una build: dalla cache degli artifact, sotto il pin che il lockfile di una Release registra per esso — quello della Release indicata, o di ogni Release presente nel workspace quando non ne viene indicata nessuna. Così una base pubblicata in un registry si risolve qui una volta che aggrega pull l’ha recuperata e fissata con un pin, e prima di allora il comando viene rifiutato indicando aggrega pull --release <release>. Non viene recuperato nulla.
Cercare un nome nei termini di una Release
Un nome indicato da solo viene cercato nello stack proprio del workspace. Indica --release <release-path> accanto a esso e il nome viene invece cercato nello stack di quella Release — le directory che la configurazione del workspace assegna a quella Release, con eventuali --catalog anteposti — che è ciò che legge una build di quella Release. Un workspace che conserva una variante di catalogo per Release, ciascuna delle quali dichiara la stessa entità, risponde quindi a un nome con la variante con cui viene compilata quella Release:
aggrega inspect core/datastore/mariadb --release release-helm-synth.yamlUn nome che lo stack di quella Release non risolve viene rifiutato, e il resoconto di dove vengono lette le entità locali indica la voce di quella Release sotto workspace.releases, poiché è quella voce che la ricerca ha letto. --release sceglie lo stack in cui viene cercato un nome, quindi si applica solo a un nome: un percorso di file e un riferimento a un registry vengono letti così come sono e lo rifiutano. Un --release che indica un file inesistente, o una directory, viene rifiutato prima di cercare qualsiasi cosa.
Leggere un’entità pubblicata
aggrega inspect oci://<host>/<repository>:<tag> legge l’entità pubblicata a quella coordinata; @<digest> al posto di :<tag> indica esattamente un manifest. È il modo per esaminare un’entità che esiste solo in un registry — il repository è il segmento del tipo seguito dall’identità dell’entità, come illustra il §6 di Catalogo e registry, e aggrega push stampa il riferimento a cui ha pubblicato, che qui si legge con oci:// davanti.
Ciò che vedi è l’entità così come è stata pubblicata. Un’entità pubblicata con i file che dichiara — una Recipe con il suo chart locale o il suo lock, un Component con uno schema che importa — viene distribuita come archivio, e l’entità ne viene estratta: il documento alla radice dell’archivio che dichiara un tipo pubblicabile, così un template di chart o un frammento compose distribuito accanto a esso non viene scambiato per l’entità. Un’entità che non dichiara alcun file viene distribuita come il suo documento invariato, e l’entità di un Plugin viene letta dal suo manifest invece che dall’eseguibile pubblicato con esso. Il documento viene poi reso con la stessa vista che riceve un file di quel tipo, con gli stessi livelli di dettaglio e gli stessi --raw e --output yaml. Non viene applicata alcuna ereditarietà: la vista riguarda ciò che il publisher ha messo a quella coordinata. I layout leggibili terminano con ciò che è stato letto: la coordinata, se conteneva l’entità come archivio o come documento stesso, il media type dichiarato dal suo manifest e il digest di quel manifest, che rilegge gli stessi byte quando è scritto come @<digest> al posto di :<tag>; --output yaml stampa il documento e nient’altro dopo.
Cosa verifica, e cosa no. I byte scaricati vengono verificati rispetto al digest che il manifest dell’artefatto registra per essi, il che stabilisce che sono i byte indicati da quel manifest. È una verifica rispetto a ciò che il registry ha servito, non rispetto a qualcosa registrato in precedenza: nessuna firma allegata all’artefatto viene verificata, e nessun ritiro registrato a suo carico viene riportato. Non viene scritto nulla — nessuna voce di cache e nessun lockfile — quindi leggere una coordinata non cambia nulla di ciò che una build successiva risolve.
Raggiunge la rete. Il registry viene contattato con le credenziali che questa macchina conserva per esso, dallo stesso archivio letto da aggrega push e aggrega pull, e un registry su questa macchina viene contattato via HTTP semplice. Un workspace offline rifiuta la lettura prima di qualsiasi connessione.
Una lettura che non può rispondere esce con un codice diverso da zero e non stampa nulla sullo standard output. Ogni errore qui sotto indica la sua condizione insieme a cosa fare; un registry che non può essere raggiunto affatto viene segnalato con l’errore di rete che ha interrotto la lettura:
| Cosa è successo | Condizione |
|---|---|
| Nulla è pubblicato sotto il riferimento | E0137 |
| Il registry ha rifiutato la credenziale, oppure non ne è memorizzata alcuna | E0138 |
| Il workspace è offline | E0125 |
| L’artefatto è un archivio che non può essere estratto | E0300 |
| L’archivio non contiene alcun documento di entità alla sua radice | E0298 |
| L’archivio contiene più di un documento di entità alla sua radice | E0299 |
| Il documento non è un’entità di un tipo che un registry pubblica | E0301 |
Ogni codice è elencato nel riferimento degli errori. Un riferimento che non indica alcun repository, o né un tag né un digest, viene rifiutato con la forma da scrivere al suo posto. --ir-graph e --closure vengono rifiutati prima di scaricare qualsiasi cosa, perché nessun tipo pubblicato da un registry è una Release.
Avvisi di deprecazione e di ritiro
Un publisher può registrare un marcatore su un artefatto dopo averlo pubblicato, dichiarando che la versione pubblicata è deprecata o ritirata. Quando il ramo catalogo risolve un’entità, inspect riporta un tale marcatore sotto la vista dell’entità stessa — per ogni tipo che risolve per nome, non solo per un Component.
L’avviso indica la gravità registrata dal publisher — warning, error o retracted — insieme alla versione su cui il marcatore è stato registrato, il motivo, la sostituzione dove ne è indicata una e la data di emissione. Vengono riportate tutte e tre le gravità. È un insieme più ampio di quello che cambia ciò in cui una build si risolve: una versione marcata retracted è esclusa dalla selezione delle versioni, mentre warning ed error sono consultive e vengono comunque selezionate. inspect ti mostra cosa ha detto un publisher; non decide cosa ottieni.
L’avviso viene letto dall’indice locale del registry da cui l’entità si risolve, costruito da aggrega registry update — quindi non richiede la rete e funziona in un workspace offline. Poiché l’indice è un’istantanea, l’avviso termina dichiarando quando è stata presa quell’istantanea e indica il comando che la aggiorna. Un workspace senza indice costruito non riporta nulla, e un avviso assente significa quindi «nulla registrato in questa istantanea» anziché «nulla registrato».
Un marcatore viene riportato solo quando la sua firma viene verificata rispetto ai firmatari riconosciuti dalla trust policy del registry. Un marcatore non firmato, o uno la cui firma non viene verificata, non viene riportato: un’affermazione che non può essere autenticata non viene presentata come un fatto.
L’avviso accompagna le viste leggibili dalle persone. Né --output yaml né --ir-graph ne aggiungono uno, quindi un consumatore che analizza l’uno o l’altro riceve un documento e nient’altro.
Esempi pratici
Ricerca di un Component nel catalogo
$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0Schema: | values: { port?: int | *8080 }Uses sockets: db: selector="component.aggrega.ai/type=stateful-server"La vista predefinita mostra la descrizione del Component, se ne definisce una, poi lo schema risolto (dopo l’eventuale merge di extends:) e gli uses-socket dichiarati. Il Component qui sopra non definisce alcuna descrizione, ed è per questo che la trascrizione si apre direttamente sullo schema. --detail aggiunge i meccanismi di self-inject, le Features richieste e le etichette; --list mostra solo l’identificatore del Component e i nomi dei suoi socket.
Feature
$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0Schema: | values: { port?: int | *9090 }Uses sockets: backend: selector="component.aggrega.ai/type=stateful-server" inject: [env]Secret slots: token (required)Targeting: appliesTo: component.aggrega.ai/type=serverLabels: feature.aggrega.ai/category: observabilityRecipe con --show-implements
La vista predefinita di una Recipe mostra una sezione per ogni modalità di input che dichiara, la sua capacità e la sua mappatura dei valori. --show-implements risolve il riferimento spec.implements rispetto al catalogo e rende il Component vincolato, insieme agli agganci che quel Component richiede:
$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0Implements: core/api-server:1.0.0Capability: helm## Synthesized workload: inlinevaluesMapping: (none)Implements Component: core/api-server:1.0.0 requires attachment (observability): core/metricsRecipe che dichiara più modalità di input
Le modalità di input di una Recipe si compongono per addizione: un source: da renderizzare, un workload: da sintetizzare e una mappa artifacts: contribuiscono ciascuno all’output, e una Recipe può dichiararne qualsiasi combinazione. inspect riporta ogni modalità dichiarata dalla Recipe invece di sceglierne una, quindi ciò che vedi è l’insieme che hai scritto:
$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0Implements: core/api-server:1.0.0Capability: helm## Sourced source: oci://charts.example.com/api-server:2.1.0## Synthesized workload: inlinevaluesMapping: inline templateArtifacts: 2 - servicemonitor.yaml - networkpolicy.yamlLe sezioni sono ordinate source: → workload: → artifacts:, lo stesso ordine che una build applica quando risolve una Recipe in un unico nome di modalità e quando riporta quale modalità dichiarata il provider vincolato non può rispettare — quindi questa vista e la diagnostica di una build nominano le modalità nello stesso ordine. Una Recipe che non dichiara né un source: né un workload: viene riportata come solo artifacts, che è l’unico caso in cui la vista nomina una singola modalità.
Manifest (risolto per impostazione predefinita)
$ aggrega inspect ./prod-manifest.yaml
Manifest: prod-manifest:1.0.0
Component Mappings: Type → Recipe core/compute/api-server helm-api-server-synthesized-with-artifacts:1.0.0 core/compute/web-ui helm-web-ui-synthesized-with-artifacts:1.0.0 core/datastore/postgres helm-postgres-synthesized-with-artifacts:1.0.0
Feature Mappings: Type → FeatureRecipe core/k8s-dns-resolver k8s-dns-patcher:1.0.0
Annotation Bindings: (none)La vista predefinita applica la catena extends: del Manifest e presenta le mappature risolte di componenti e funzionalità insieme ai binding delle annotazioni. --raw mostra il file così come è stato scritto, prima della risoluzione di extends.
Aggregate (risolto per impostazione predefinita)
$ aggrega inspect ./fullstack-app.yaml
Aggregate: fullstack-app:1.0.0
Components: backend (type: core/compute/api-server) Values: (none) Uses: databases: - data.main-db frontend (type: core/compute/web-ui) Values: (none) Uses: apis: - my-api → backend main-db (type: core/datastore/postgres) Values: database_name: app_production Uses: (none)
Dependency Graph: data.main-db ↑ backend backend ↑ frontendLa vista predefinita costruisce la topologia e mostra ogni componente con i suoi valori e i suoi archi uses, seguiti dal grafo delle dipendenze calcolato. L’albero dei sottosistemi è reso con l’annidamento; --flat rende una sezione per nodo, ciascuna identificata dal suo percorso completo con i punti.
Una connessione scritta nella forma estesa è seguita dagli agganci che trasporta, ciascuno sotto il nome che assume sul componente consumatore — l’alias della connessione e lo slot uniti da un punto — con il tipo di Feature che nomina e una clausola che indica lo slot che riempie e se gestisce materiale dichiarato sensibile:
gateway (type: conn/gateway) Values: region: eu Uses: models: - gpt → model - gpt.credential (feature.conn/token) [slot: credential, sensitive]Lo slot e il contrassegno sono i fatti che una build di una Release che distribuisce questo Aggregate registra per l’aggancio, letti nello stesso modo in cui li legge la vista della Release (vedi Connessione, slot e clausola di sensibilità dell’aggancio); provengono dalla dichiarazione dello slot del socket e da quella della Feature stessa, quindi non dipendono da quale Release distribuisce l’Aggregate. Un Aggregate non nomina alcun Manifest, quindi la realizzazione che il Manifest di una Release sceglie per l’aggancio non viene mostrata qui. Questa vista elenca le connessioni di un componente e ciò che trasportano; gli agganci del blocco proprio di un componente compaiono nella vista della Release.
Release (risolta per impostazione predefinita)
La vista della Release è l’ispezione con la posta in gioco più alta. Esegue l’intera pipeline e rende, per ogni confine, ogni nodo Component, i suoi archi uses e ogni Feature agganciata a quel nodo — quella scritta su una connessione sotto l’arco di quella connessione — ciascuna con lo slot di aggancio che riempie, se gestisce materiale dichiarato sensibile e la FeatureRecipe che la realizza, più una parentesi di provenienza che rivela da dove proviene l’aggancio:
$ aggrega inspect ./prod-release.yaml --catalog ./catalog
Release: prod-release:1.0.0
Boundary: backend-ns Directory: ./dist/backend Annotations (provider-consumed): aggrega.ai/namespace: backend-zone Component: backend (type: core/compute/api-server:1.0.0) Uses: data.main-db → data.main-db [cross-boundary] Features: (none)
Boundary: frontend-ns Directory: ./dist/frontend Annotations (provider-consumed): aggrega.ai/namespace: frontend-zone Component: frontend (type: core/compute/web-ui:1.0.0) Uses: my-api → backend [cross-boundary] Features: - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]
Boundary: data-ns Directory: ./dist/data Annotations (provider-consumed): aggrega.ai/namespace: database-zone Component: data.main-db (type: core/datastore/postgres:1.0.0) Features: (none)Ogni confine riporta la sua directory di output e le sue annotazioni consumate dal provider; ogni componente sotto un confine riporta il suo tipo di componente dell’Aggregate, i suoi archi uses (con gli archi tra confini contrassegnati), ciascuno seguito dagli agganci che quella connessione trasporta, e i propri agganci di Feature, ogni aggancio con la sua clausola dei fatti e la sua parentesi di provenienza. --flat comprime l’albero dei confini in una sezione per confine identificata dal suo percorso completo. --raw emette il file della Release alla lettera, senza pipeline.
Output YAML
$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/server version: 1.0.0 labels: component.aggrega.ai/type: serverspec: usesSchema: db: selector: component.aggrega.ai/type=stateful-server schema: values: port: {type: integer, default: 8080}Un Component indicato per nome dal catalogo viene stampato come l’entità risolta dal catalogo, quindi dopo un merge extends: vedi l’entità risultante dal merge anziché il file scritto; un file di Component viene stampato così come è stato scritto.
Output leggibile dalle macchine
Due flag producono output leggibile dalle macchine, e rispondono a domande diverse. --output sceglie un formato per il documento che questo comando già rende; --ir-graph chiede un documento diverso — il grafo compilato in cui si risolve una Release — in aggiunta a esso. Sono indipendenti: passandoli entrambi ottieni il grafo e lo YAML così come è stato scritto, ciascuno una volta.
--output yaml emette l’entità così come è stata scritta, adatta al piping e al diff. Quell’output è letterale, e ciò include i valori che un autore ha dichiarato sensibili — un output che afferma di riprodurre l’input non può ometterne una parte e continuare a riprodurlo. Invialo in pipe, conservalo e condividilo come faresti con il file dell’entità da cui proviene.
Il grafo compilato: --ir-graph
aggrega inspect <release> --ir-graph scrive su standard output, come JSON, il grafo in cui si è risolta l’esecuzione, prima della vista che il comando rende comunque. Un solo documento JSON, un solo a capo finale, così un consumatore che decodifica il flusso legge il grafo e si ferma.
Si applica a una Release, che è l’unico tipo che si risolve in un grafo. Se richiesto per qualsiasi altro tipo, o per un’entità del catalogo per nome, il comando rifiuta e lo dice, invece di rendere la vista propria di quell’entità e scartare silenziosamente la richiesta.
Una composizione che i controlli del compilatore rifiutano non produce alcun grafo. Il rifiuto descritto in Comportamento in caso di errore avviene prima che qualcosa venga scritto su questo flusso, quindi una pipeline che lo legge non riceve mai un grafo che una build degli stessi documenti rifiuterebbe — riceve gli stessi rilievi che una build riporterebbe, e un codice di uscita diverso da zero.
Lo stesso flag, con lo stesso significato, è presente su aggrega build e aggrega validate: ciascuno restituisce il grafo calcolato da quell’esecuzione, in aggiunta a qualunque altra cosa produca quel comando. Un’integrazione con l’editor legge lo stesso grafo tramite il protocollo del daemon.
--output yaml non emette il grafo. Riproduce la Release scritta, esattamente come fa per ogni altro tipo. Una pipeline che vuole il grafo lo legge invece da --ir-graph, e riceve JSON anziché YAML.
Il grafo omette i valori. Non è un file scritto da qualcuno — è ciò che la compilazione ha calcolato dall’Aggregate, dalla Release e dal catalogo — quindi non c’è alcun contratto di fedeltà allo scritto da rispettare, e le stesse dichiarazioni che governano i layout leggibili governano anche il grafo. Ovunque il grafo riporti una foglia che un autore ha dichiarato sensibile, il valore viene sostituito da un oggetto con una sola chiave che lo indica come omesso:
"values": { "secretName": "db-creds", "vault": { "token": { "aggrega_withheld": "declared" } }}La chiave sopravvive, quindi il grafo risponde ancora alla domanda su quali foglie portino un nodo e i suoi agganci; scompare solo il valore. Un elemento fratello non dichiarato nello stesso payload viene emesso così come è stato scritto — secretName qui sopra è un localizzatore pubblico che il suo autore ha lasciato non dichiarato, e viene stampato. Il motivo che accompagna il marcatore dice perché il valore è assente: declared per una foglia coperta da una dichiarazione, e unreadable quando il payload è arrivato in una forma che questo comando non ha potuto leggere, nel qual caso viene omesso l’intero payload invece di indovinarne una parte.
La configurazione propria di una connessione viene omessa allo stesso modo. I values per connessione che un Aggregate scrive su una voce uses e l’infra per connessione che una Release vi scrive sono governati dal socket del componente consumatore — il valueSchema e l’infraSchema che dichiara, i contratti rispetto ai quali quella configurazione viene validata — mai dalle dichiarazioni del target. Una foglia che uno dei due contratti dichiara sensitive: true viene sostituita dal marcatore nei values e nell’infra dell’arco, e nella voce uses del nodo consumatore, che contiene i valori come li ha scritti l’autore; ogni arco elenca le foglie che omette in sensitive_payload_leaves, il campo che un nodo usa per le proprie. Una foglia con lo stesso nome su una connessione il cui socket la dichiara leggibile viene emessa così come è scritta.
Passa --unredacted quando una pipeline ha davvero bisogno dei valori, e tratta ciò che produce come tratti i file delle entità stessi. aggrega build e aggrega validate accettano lo stesso flag accanto a --ir-graph, alle stesse condizioni: il grafo che restituiscono omette i valori a meno che il flag non venga passato.
Il protocollo del daemon fornisce lo stesso grafo secondo la stessa regola. aggrega/irGraph risponde con questi valori omessi, e li restituisce in chiaro solo a una richiesta che imposta il suo campo unredacted — la forma di questo flag nel protocollo. Così ciò che disegna un pannello dell’editor segue le stesse dichiarazioni, e un client che mostra i valori lo fa perché li ha chiesti.
La chiusura delle dipendenze: --closure
aggrega inspect <release> --closure riporta la chiusura delle dipendenze della Release: ogni entità del catalogo che raggiunge, alla versione in cui ciascuna si è risolta, insieme alle identità dell’Aggregate e del Manifest in cui si sono risolti i suoi due puntatori e ai documenti condivisi a cui attingono quelle entità. Non viene reso nulla e non viene prodotto alcun artefatto — la chiusura viene risolta, non costruita, quindi nessun provider viene caricato per calcolarla.
La chiusura e la vista risolta sono documenti diversi, e nessuno dei due si può ricavare dall’altro. La vista risolta — ciò che questo comando rende per impostazione predefinita per una Release — dice com’è fatto il deployment: i suoi confini, i suoi nodi di componente, cosa è collegato a cosa e cosa è agganciato a ciascun nodo. La chiusura dice cosa è stato coinvolto per costruirlo, e a quali versioni. Un’entità può essere raggiunta senza mai comparire come nodo — la Recipe a cui un Manifest mappa un tipo di componente è raggiunta da ogni build e non è un nodo in nessuna di esse — e un nodo registra il tipo di componente con cui è stato dichiarato, non la versione in cui quel tipo si è risolto. Quindi un lettore che chiede «perché questa versione è cambiata?», «cosa influenzerebbe la modifica di questo documento condiviso?» o «da cosa dipende davvero questo deployment?» sta chiedendo la chiusura, e un lettore che ha la vista risolta non la ottiene leggendola con più attenzione.
La stessa parola chiede lo stesso documento su ogni superficie. --closure qui, aggrega/releaseClosure tramite il protocollo del daemon (vedi aggrega serve, «Una chiusura non è il grafo») e la modalità release dello strumento describe tramite il protocollo degli strumenti dell’assistente rispondono tutti a questa domanda su una Release; un nome di Release su uno qualsiasi di essi raggiunge la stessa risoluzione, quindi i tre non possono arrivare a dissentire su ciò da cui dipende una Release. Su un lockfile che non corrisponde più a ciò a cui la Release si risolve, questo comando e lo strumento describe rifiutano con l’arresto per drift della build; il daemon, che serve un editor durante la modifica, risponde.
È un solo documento, quindi si chiede da solo. --closure seleziona la chiusura al posto della vista risolta, e non può essere combinato con --raw, --resolved, --output o --ir-graph — ciascuno di questi chiede un documento diverso sulla stessa Release, e un comando che accettasse due richieste dovrebbe rispondere silenziosamente a una sola. Combinarli viene rifiutato, nominando la coppia.
Si applica a una Release e a nient’altro. Un’entità del catalogo, un file di Aggregate, un Manifest — nessuno di essi risolve una chiusura, quindi la richiesta viene rifiutata invece di ricevere una risposta che rende la vista propria di quel soggetto e la scarta. Una richiesta scartata appare a chi chiama esattamente come un soggetto la cui chiusura è vuota.
Ogni esito è distinto dagli altri. A una Release che si risolve si risponde con l’elenco. Un percorso di Release che non nomina alcun file viene rifiutato, dicendo che il file non c’è. Una Release che c’è e la cui chiusura non può essere risolta viene rifiutata indicando cosa non è stato possibile risolvere e da dove proveniva il riferimento, seguito dagli eventuali file rifiutati dal caricamento del catalogo — perché un file rifiutato è il motivo abituale per cui un’entità raggiunta dalla Release è venuta a mancare. Un registro di attendibilità dei plugin accanto alla Release che c’è ma non può essere letto viene rifiutato indicando cosa non è stato possibile leggere, perché un elenco che lo avesse tralasciato non riporterebbe alcun plugin ritirato là dove non è stato possibile verificarne nessuno. Una Release il cui lockfile non corrisponde più a ciò a cui si risolve viene rifiutata con l’arresto per drift che stampa una build, come descrive Comportamento in caso di errore, perché le versioni elencate sarebbero versioni che nessuna build di quella Release usa. Un elenco vuoto non è mai la risposta a nessuno di questi casi: riporterebbe un percorso digitato male, o un workspace rotto, come una Release che non dipende da nulla.
I tre livelli di dettaglio si applicano come per ogni tipo. --list stampa solo i riferimenti, uno per riga, per il piping. Il livello predefinito aggiunge le identità risolte, la versione in cui si è risolto ogni riferimento, i documenti condivisi utilizzati, ogni mappatura del Manifest il cui target non implementa il tipo a cui è mappato e ogni avviso di deprecazione o ritiro registrato su ciò da cui dipende la Release — nel suo lockfile, su un riferimento fissato, e nel registro di attendibilità dei plugin accanto a essa, su un plugin collegato in un ruolo che restituisce un verdetto di accettazione o rifiuto — con le stesse parole che aggrega build stampa per lo stesso marcatore. --detail aggiunge il tipo di ogni riferimento quando il punto del riferimento ne ha registrato uno — alcune posizioni in un documento dicono a che tipo puntano e altre no, quindi viene riportato dove è noto invece di essere dedotto dalla forma del nome.
$ aggrega inspect ./release.yaml --catalog ./catalog --closure
Release: prod-release:1.0.0 Aggregate: fullstack-app Manifest: prod-manifest Environment: production
Entities (11): ./aggregate.yaml ./manifest.yaml core/compute/api-server (1.0.0) core/compute/web-ui (1.0.0) core/datastore/postgres (1.0.0) core/k8s-dns-resolver (1.0.0) db-module (1.0.0) helm-api-server-synthesized-with-artifacts:1.0.0 (1.0.0) helm-postgres-synthesized-with-artifacts:1.0.0 (1.0.0) helm-web-ui-synthesized-with-artifacts:1.0.0 (1.0.0) k8s-dns-patcher:1.0.0 (1.0.0)Quando un workspace ha registrato in quali versioni si risolve una Release, quel registro alimenta la risoluzione, quindi le versioni riportate sono quelle da cui è costruito questo deployment e non quelle che il catalogo contiene oggi. Un workspace senza tale registro risolve sul catalogo così com’è.
Connessione, slot e clausola di sensibilità dell’aggancio
Ogni aggancio di Feature nella vista della Release riporta una clausola che nomina i fatti che il compilatore registra sull’aggancio stesso: quale slot di aggancio riempie, se gestisce materiale dichiarato sensibile e la FeatureRecipe che lo realizza — e, per un aggancio scritto su una delle connessioni del componente, la connessione su cui è stato scritto. La clausola si trova tra il nome dell’aggancio e la sua parentesi di provenienza, e si legge in modo identico in entrambe le forme di provenienza descritte sotto.
Un aggancio scritto su una connessione è elencato sotto la riga di quella connessione in Uses:, non sotto Features:, quindi Features: contiene solo gli agganci propri del componente. La riga sopra di esso nomina la connessione tramite il suo alias e il componente che raggiunge, e la sua clausola dice il resto:
[socket: <socket>]— il socket attraverso cui è collegata la connessione, che la riga della connessione non nomina. Apre la clausola perché cambia il modo in cui si legge il resto: la metà dello slot che segue nomina uno slot dichiarato dal socket della connessione, non uno che il componente dichiara per i propri agganci.[connection: <alias> through socket <socket>]— lo stesso fatto per un aggancio la cui connessione non ha alcuna riga nel bloccoUses:, che viene quindi elencato sottoFeatures:e nomina qui la sua connessione. In entrambi i casi una connessione viene nominata una volta per aggancio, mai due.[slot: <name>]— l’aggancio riempie lo slot chiamato<name>. Uno slot si riempie agganciando una Feature con il nome dello slot stesso, quindi<name>è il nome con cui è stato scritto l’aggancio, confrontato con gli slot dichiarati: ilfeaturesSchemadel Component ospite per uno dei suoi agganci, e ilfeaturesSchemache il socket della connessione dichiara per un aggancio scritto su una connessione.[free]— l’aggancio non riempie alcuno slot dichiarato: il Component risolto non dichiara alcuno slotfeaturesSchemacon quel nome. Questo è un rilievo, non una diagnostica. Un aggancio in forma libera è accettato, e un operatore che vuole vietarlo lo esprime come policy di governance invece di affidarsi allo strumento per rifiutarlo.[sensitive]— l’aggancio gestisce materiale che un autore ha dichiarato sensibile, perché la Feature agganciata dichiara una foglia sensibile, perché lo slot che riempie dichiarasensitive: true, o per entrambi i motivi.[realization: <name>:<version>]— la FeatureRecipe che il Manifest della Release vincola per l’aggancio: tramite il nome proprio dell’aggancio quando il Manifest mappa quel nome — per un aggancio scritto su una connessione, l’alias e lo slot uniti da un punto — altrimenti tramite il suo tipo di Feature. È la realizzazione con cui una build degli stessi documenti rende l’aggancio, e lo stesso valore che il grafo compilato riporta sull’aggancio comerealization(vedi--ir-graph), quindi questa vista e il grafo non possono nominarne di diverse. Viene per ultima nella clausola.
Quando si applicano più fatti, condividono una clausola. core/storage/s3-object-store dichiara uno slot secret_access_key contrassegnato sensitive: true, quindi una credenziale agganciata con quel nome riporta entrambi i fatti, mentre una Feature agganciata con un nome per cui il Component non dichiara alcuno slot non riporta né lo slot né la sensibilità. Con un Manifest che mappa ogni tipo di Feature a una FeatureRecipe, ogni riga nomina anche la sua realizzazione:
Features: - secret_access_key (core/generated-secret:1.0.0) [slot: secret_access_key, sensitive, realization: generated-secret:1.0.0] [explicit] - cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]Un componente il cui socket models dichiara uno slot credential contrassegnato sensitive: true, e che collega una connessione con l’alias gpt che lo riempie, elenca quell’aggancio sotto la connessione — accanto a una propria credenziale, che resta sotto Features::
Uses: gpt → model - gpt.credential (feature.conn/token:1.0.0) [socket: models, slot: credential, sensitive, realization: conn-token-compose:1.0.0] [explicit] Features: - db_password (feature.conn/token:1.0.0) [slot: db_password, sensitive, realization: conn-token-compose:1.0.0] [explicit]Un aggancio scritto su una connessione non riporta mai [free]: un socket ammette solo gli slot che dichiara, e una connessione che porta qualsiasi altro nome viene rifiutata quando la build viene caricata.
La clausola viene omessa del tutto quando nessuno dei fatti si applica, e ogni metà viene omessa in modo indipendente:
- Nessuna metà socket o connessione significa che l’aggancio è stato scritto sul blocco proprio del componente, oppure lo ha raggiunto da un ambito più ampio o tramite espansione guidata dalle annotazioni.
- Nessuna metà slot significa che non è stato possibile risolvere l’insieme degli slot dichiarati del Component ospite — ad esempio, il suo tipo non corrisponde ad alcuna entità del catalogo. Questo è deliberatamente distinto da
[free]:[free]risponde «nessuno slot con quel nome è dichiarato», mentre una metà assente significa che non è stato possibile rispondere affatto alla domanda. - Nessun
sensitiveregistra che nessuna dichiarazione ha contrassegnato l’aggancio. È più ristretto di un verdetto secondo cui l’aggancio non trasporta nulla di segreto; l’asse riporta dichiarazioni, e nulla viene dedotto dal nome di un campo o dal suo valore. - Nessuna metà realizzazione significa che il Manifest non vincola l’aggancio ad alcuna FeatureRecipe presente nel catalogo.
Uno slot il cui nome dichiarato è letteralmente free viene reso anch’esso come [free], indistinguibile da un aggancio in forma libera — nulla riserva quella parola rispetto allo spazio dei nomi degli slot.
Grammatica della parentesi di provenienza dell’IR
Ogni aggancio di Feature nella vista della Release riporta una parentesi di provenienza. La parentesi può assumere una forma compatta (una parentesi per Feature quando la provenienza dell’aggancio è uniforme su tutte le foglie) o una forma per foglia (una parentesi per foglia quando le foglie dell’aggancio provengono da fonti eterogenee). Esistono tre corpi di parentesi; si applicano in modo identico a entrambe le forme.
I tre corpi di parentesi
-
[explicit]— l’aggancio di Feature è dichiarato dall’autore. L’Aggregate o la Release ha nominato esplicitamente la Feature sul nodo interessato. Gli agganci espliciti sono la fonte con la priorità più alta; prevalgono sempre sui contributi guidati dalle annotazioni sulla stessa foglia. -
[annotation: <key> from <source>]— l’aggancio di Feature è guidato dalle annotazioni. Il compilatore lo ha sintetizzato perché un’annotazione su<source>corrispondeva a un binding del Manifest che dichiara questa Feature.<key>è la chiave di annotazione che ha attivato il binding (ad es.business.aggrega.ai/team);<source>è l’entità che portava l’annotazione (aggregate,release,componentomanifest). L’aggancio sintetizzato è strutturalmente identico a uno esplicito — il rendering a valle li tratta allo stesso modo — ma la parentesi di provenienza li distingue affinché il debugging resti decidibile. -
[explicit; overrides annotation: <key> from <source>]— una forma per foglia che si attiva quando una dichiarazione esplicita dell’autore su una foglia sopprime un contributo di annotazione che altrimenti avrebbe impostato la stessa foglia. La composizione tra lati produce questo caso: un’annotazione dell’Aggregate potrebbe fornire il pilastrovalues:di una Feature, un’annotazione della Release ne fornisce il pilastroinfra:, e una dichiarazione esplicita della Release sulla stessa Feature sovrascrive una foglia infra. La parentesi della foglia registra sia l’autore esplicito sia l’annotazione soppressa; l’annotazione soppressa non contribuisce all’output reso, ma la sua presenza compare nella vista di inspect, così l’operatore può vedere quale annotazione è stata sovrascritta e dove.
Forma compatta e forma per foglia
Il compilatore sceglie tra il rendering compatto e quello per foglia percorrendo la provenienza per foglia dell’aggancio e verificandone l’uniformità. La provenienza di un aggancio è uniforme quando ogni foglia popolata (nei pilastri values: e infra: della Feature) condivide la stessa origine (esplicita o annotazione), la stessa chiave di annotazione se guidata dalle annotazioni, la stessa entità sorgente, e nessuna foglia porta un marcatore «overrides annotation». Quando la provenienza è uniforme, il compilatore emette una parentesi per aggancio:
- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]Quando la provenienza diverge — un caso tipico è la composizione tra lati, in cui un’annotazione dell’Aggregate fornisce values: e un’annotazione della Release fornisce infra: sulla stessa Feature — il compilatore emette una parentesi per ogni foglia popolata:
- core/pii-redaction values.fields_to_mask: ["ssn", "card_number"] [annotation: compliance.aggrega.ai/data-class from aggregate] values.classifier_endpoint: "redact-v2" [explicit; overrides annotation: compliance.aggrega.ai/data-class from aggregate] infra.audit_bucket: "s3://..." [annotation: compliance.aggrega.ai/audit-bucket from release]L’ordine di percorrenza è prima il pilastro values (nell’ordine dell’autore), poi il pilastro infra (con la stessa disciplina). Il prefisso del pilastro (values. / infra.) e il percorso con i punti all’interno del pilastro individuano esattamente quale foglia annota ciascuna parentesi.
Valori dichiarati sensibili
Una foglia il cui schema dichiara sensitive: true stampa il testo fisso <redacted> al posto del suo valore. La chiave, il prefisso del pilastro e la parentesi di provenienza vengono tutti mantenuti — viene sostituito solo il valore — quindi il layout risponde ancora alla domanda su quali foglie porti un’entità e da dove provenga ciascuna. Sono interessate due superfici leggibili: il blocco Values: per nodo di un Aggregate e il blocco degli agganci per foglia di una Release risolta — compreso un aggancio scritto su una connessione, stampato sotto la riga di quella connessione, che omette esattamente le foglie che la stessa Feature omette quando è il componente stesso a contenerla. Il grafo compilato di una Release con --ir-graph omette le stesse foglie nella forma strutturata descritta in Output leggibile dalle macchine.
Components: app (type: core/app) Values: appName: demo dbPassword: <redacted> tuning.poolSize: 25 tuning.adminToken: <redacted>Viene omessa solo una foglia dichiarata, e la clausola [sensitive] a livello di aggancio non è un’istruzione di omissione: dice che l’aggancio gestisce materiale segreto, non quali delle sue foglie lo portino. I localizzatori pubblicati di una Feature di credenziale — il nome della risorsa e la chiave dei dati — sono pubblici e sono deliberatamente lasciati non dichiarati nel catalogo della libreria standard, quindi vengono stampati in chiaro accanto al materiale che non lo è:
- credentials (feature.test/db-credential) values.secretName: db-creds [explicit] values.literalPassword: <redacted> [annotation: feature.test/pw from aggregate.yaml:components.app.annotations.feature.test/pw]Nulla viene dedotto dal nome di un campo: un campo chiamato password che non porta alcuna dichiarazione stampa il suo valore, e un campo dichiarato chiamato key no. L’oscuramento riguarda ciò che lo strumento stampa; non raggiunge mai un artefatto reso, e dist/ viene emesso esattamente come lo ha prodotto il rendering. La parola chiave e il limite completo di ciò che dichiararla ottiene si trovano in vocabulary/compact-form-authoring.md, «Dichiarare sensibile una foglia».
Mostrare i valori oscurati
--unredacted stampa i valori dichiarati sensibili invece di ometterli, su ogni superficie di inspect contemporaneamente — i layout leggibili descritti sopra e il grafo compilato di una Release allo stesso modo. Esiste perché il valore omesso è talvolta proprio quello oggetto di indagine: una credenziale che arriva dall’aggancio sbagliato appare identica a quella giusta quando entrambe risultano omesse.
Il suo ambito è il comando a cui viene passato. Anche aggrega build e aggrega validate lo accettano, dove raggiunge il grafo restituito da --ir-graph e nient’altro, e lo rifiutano quando non è stato chiesto alcun grafo. aggrega build --trace-unredacted è la stessa idea applicata ai file di trace della build, e nessuno dei due flag della build raggiunge l’output dell’altro; un artefatto reso sotto dist/ non è influenzato da nessuno di essi, perché viene emesso esattamente come lo ha prodotto il rendering, qualunque cosa venga passata.
Qualunque cosa raggiunga l’output porta quindi quei valori in chiaro — un terminale, una pipe, un file, una registrazione dello schermo, una segnalazione di bug incollata. A differenza dei file di trace, ciascuno dei quali si apre con un’intestazione che dice che sono stati acquisiti senza oscuramento, l’output su un terminale non porta alcun contrassegno di questo tipo: solo la riga di comando dice che il flag è stato passato.
Quando ricorrere a inspect
- Debugging di «perché questa Feature è qui?» — gli agganci guidati dalle annotazioni sono invisibili nei file YAML dell’Aggregate e della Release (le annotazioni ci sono, ma gli agganci di Feature che sintetizzano esistono solo nell’IR). Inspect li fa emergere con la loro provenienza.
- Verificare l’ereditarietà dello schema —
aggrega inspect <ComponentName>mostra lo schema unito dopo la risoluzione della catenaextends:; il file scritto, da solo, mostra solo il delta locale. - Diagnosticare sorprese della composizione tra lati — quando un’annotazione dell’Aggregate e un’annotazione della Release forniscono entrambe payload di pilastro sulla stessa Feature, le foglie risolte possono essere difficili da ricostruire mentalmente. La forma della parentesi per foglia rende esplicita la risoluzione.
- Controllo di verifica prima del deployment —
aggrega inspect ./prod-release.yamlelenca ogni Feature su ogni Component prima cheaggrega buildproduca gli artefatti; l’operatore può confermare che la topologia corrisponde all’intento prima di fare il commit dei manifest resi in GitOps.
Per i meccanismi sottostanti — come le annotazioni si propagano a cascata, come la partizione tra lato e pilastro instrada i valori delle annotazioni nei pilastri della Feature e come la disciplina per cui prevale l’aggancio esplicito interagisce con i contributi guidati dalle annotazioni — vedi providers/well-known-annotations.md e entities/manifest.md, «Binding di Feature guidati dalle annotazioni».
Sinossi
aggrega inspect [identifier] [flags]Descrizione
Render a readable view of any Aggrega entity — a catalog entity by name, anauthored entity file by path, an entity published in a registry, or afully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extendwhich bases, which Recipe maps to each type, which Features attach to each node,and where each Feature's contributions came from.
A single argument routes by its shape. A path — anything starting with ./, ../or /, or ending in .yaml or .yml — is read as a file and inspected by its ownkind: header. A registry reference — oci://<host>/<repository>:<tag>, or@<digest> in place of :<tag> — is read from the registry that publishes it.Anything else is looked up by name in the catalog search stack: theworkspace's own, or, with --release, the one the workspace configurationgives that Release, so a name several catalog variants declare, one perRelease, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpackedfrom the archive its kind is published as where it is one, and rendered by thesame view a file of that kind gets. Reading it reaches the network, using thecredentials this machine holds for that registry, and an offline workspacerefuses it. The fetched bytes are checked against the digest the artifact'sown manifest records for them, which establishes that they are the bytes thatmanifest names and nothing more: no signature attached to the artifact isverified, no withdrawal recorded against it is reported, and nothing iswritten — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, thedefault for a structured overview, and --detail for full field bodies. --listand --detail are mutually exclusive. Resolution depth has its own pair, --rawfor the entity exactly as authored and --resolved for the kind's full depth,also mutually exclusive.
Note that --raw reproduces the file as written, so a value the author declaredsensitive appears as authored. That is what as-authored means; handle suchoutput as you would the entity file itself. --output yaml reproduces the filethe same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag becauseneither answer contains the other. --ir-graph asks for the IR graph a Releaseresolves to — what the Release looks like, as JSON on stdout in addition towhatever else this command produces. --closure asks for the Release's dependencyclosure — every catalog entity it reaches and the version each resolved to,which is what was pulled in to build the Release. An entity can be reachedwithout appearing as a node, and a node does not carry the version its typeresolved to, so holding one of the two is not holding the other.
--ir-graph is orthogonal to --output, which picks the format of the command'sown view. Values an author declared sensitive are withheld from the graph, asthey are from the readable layouts. Pass --unredacted to print them instead.Flag
| Flag | Predefinito | Descrizione |
|---|---|---|
--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. |
--closure | false | Riporta la chiusura delle dipendenze della Release — ogni entità del catalogo che raggiunge, alla versione in cui ciascuna si è risolta — al posto della vista dei nodi risolti. Si applica a una Release, che è l’unico tipo che risolve una chiusura; qualsiasi altro tipo rifiuta la richiesta invece di scartarla silenziosamente. |
--color | auto | Colora l’output: auto|always|never. |
--detail | false | Rende i corpi completi dei campi. |
--flat | false | Rende un’entità ad albero (Aggregate, Release) come elenco piatto, con ogni nodo preceduto dal suo percorso completo con i punti. Nessun effetto sui tipi tabellari. |
--ir-graph | false | Scrive anche su stdout, come JSON, il grafo IR calcolato da questa esecuzione, in aggiunta a tutto ciò che questo comando già produce. I valori che un autore ha dichiarato sensibili vengono omessi; passa —unredacted per stamparli. Si applica a una Release, l’unico tipo che si risolve in un grafo; qualsiasi altro tipo rifiuta la richiesta invece di scartarla silenziosamente |
--list | false | Rende solo gli identificatori. |
--no-color | false | Disattiva l’output colorato (alias di —color=never). |
--output, -o | text | Formato di output: text|yaml. |
--plugin | — | Percorso nel filesystem di un artefatto <file.wasm> grezzo; ricava e stampa le funzioni host che importa, prima che aggrega plugin sync le registri in un’entità Plugin. Non accetta alcun argomento identificatore. |
--raw | false | Rende l’entità così come è stata scritta, senza risoluzione. |
--release | — | Cerca un nome del catalogo nei termini di questo file di Release: attraverso le directory del catalogo che la configurazione del workspace assegna a quella Release, con —catalog anteposto. Si applica a un nome; un file o un riferimento a un registry viene ispezionato così com’è e lo rifiuta. Un percorso relativo si risolve rispetto alla directory in cui esegui il comando, non rispetto alla radice del workspace. Quando quella directory non è in alcun workspace e non viene indicata alcuna radice, un percorso assoluto trova il workspace a partire dalla cartella della Release stessa |
--resolved | false | Rende l’entità completamente risolta. |
--show-implements | false | Per una Recipe o una FeatureRecipe, risolve spec.implements rispetto al catalogo e rende il Component o la Feature vincolati. |
--unredacted | false | Stampa i valori che un autore ha dichiarato sensibili invece di ometterli. Qualunque cosa raggiunga l’output — un terminale, una pipe, un file, una registrazione dello schermo — porta quindi quei valori in chiaro. |