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

aggrega build

aggrega build compila una coppia Aggregate + Release in artefatti nativi dei provider (manifest Helm, chart Helm ridistribuibili, YAML docker-compose) sotto dist/ nella radice del workspace, come illustrato in Output. La Release è l’unico punto d’ingresso: indica l’Aggregate e il Manifest, dichiara i confini e instrada i componenti verso i provider.

Flag comuni

Due flag hanno un comportamento che il riferimento dei flag riportato di seguito non riesce a trasmettere da solo:

  • --catalog <dir> — una directory contenente entità del catalogo — i tipi di authoring Component, Feature, Recipe e FeatureRecipe insieme ai tipi di libreria, agli Aggregates e ai Plugins — caricata in modo ricorsivo. Ogni directory --catalog viene cercata prima di quelle configurate, nell’ordine indicato. Per cercare un catalogo locale al progetto accanto a uno condiviso, passali entrambi (--catalog ./catalog --catalog ../shared-catalog) o elencali in catalog_dirs. Con --detail, ogni entità oscurata da una directory con precedenza più alta viene segnalata su stderr, insieme agli altri avvisi della build. Una directory --catalog che non esiste arresta la build, indicandola. Lo stesso fa una directory elencata in catalog_dirs che non è una directory, prima che venga letto o scritto alcunché, indicando la voce, il file di configurazione e la riga che la elencano — vedi Da dove vengono lette le entità locali. Una build che si arresta perché un riferimento non si è risolto in nulla indica, nella nota sotto l’arresto, ogni file in quelle directory che dichiara un apiVersion di Aggrega — una riga che inizia, senza rientro, con apiVersion: e un valore che comincia con aggrega.ai/ — e che non è stato possibile caricare, ad esempio uno che non viene analizzato come YAML, con il motivo fornito dal parser stesso, tra i file del catalogo saltati al caricamento; un file YAML che dichiara un altro apiVersion, o nessuno, non è un documento Aggrega e non viene mai indicato lì.
  • --detail — segnala cosa ha fatto il passaggio di pull, la stessa diagnostica transitoria degli eventi di pull che emette aggrega pull --detail. Ciò che decide se c’è qualcosa da segnalare è se un passaggio di pull è stato richiesto — con --auto-pull o abilitando auto_pull — e non se un lockfile è già presente: un passaggio di pull richiesto viene eseguito in entrambi i casi, riempiendo un lockfile mancante e rispettando i pin di uno esistente. Quando non viene eseguito alcun passaggio di pull, il flag stampa una nota di una riga su stdout e prosegue — non inventa mai un livello di risoluzione che il lockfile committato non contiene. Per lo stato di risoluzione post-pull delle dipendenze di una Release, usa aggrega inspect.

--dry-run è trattato in Anteprima di una build senza scriverla, e --trace e --trace-unredacted in Output di trace e Mostrare i valori nascosti più avanti.

Riempire il lockfile come parte della build

Per impostazione predefinita la build è in sola lettura per quanto riguarda le dipendenze: ha bisogno di un lockfile e non ne scrive nessuno. --auto-pull e l’impostazione del workspace auto_pull aggiungono il passaggio di pull alla build, così un solo comando risolve le dipendenze della Release e compila sulla base di ciò che ha risolto.

Una modifica alla Release è qualcosa che il lockfile rileva. Il lockfile registra la Release — e ogni Release che essa estende — tramite il digest del suo contenuto, quindi una build in sola lettura su una Release modificata dopo il pull si arresta prima di qualsiasi rendering, indicando il file e chiedendoti di eseguire aggrega pull --release <release>, che registra la modifica rispettando ogni altro pin. Conta anche un commento o una modifica degli spazi, perché il digest copre i byte così come sono. Una build con auto-pull esegue da sé quel passaggio di pull, quindi registra la modifica ed esegue la build.

Il rendering della Release avviene una sola volta. Quali input esterni una Release consuma dipende dal suo rendering e non da qualcosa che i suoi documenti dichiarano, quindi il passaggio di pull esegue il rendering della Release per scoprirlo, e quel rendering è quello della build. Una build con auto-pull costa quindi un solo rendering, come una build semplice su un lockfile già presente.

I flag che influenzano un rendering si applicano a esso. --trace, --verify-determinism, --disable-plugin-cache e --no-unsupported-field-warnings raggiungono il rendering eseguito da una build con auto-pull alle stesse condizioni con cui raggiungono quello di una build semplice, quindi se chiedi un trace o un controllo di determinismo in una build a comando singolo lo ottieni. --dry-run è l’eccezione, ed è un rifiuto anziché un silenzio: un dry run non scrive nulla mentre il passaggio di pull scrive, quindi la combinazione si arresta prima di qualsiasi lavoro (vedi Anteprima di una build senza scriverla).

Come una build legge ciò che il lockfile fissa

Un pin del lockfile indica un contenuto — un digest — anziché un luogo. Per un’entità è il digest di ciò che una sua pubblicazione contiene, il suo documento e i file che nomina, quindi una copia di un’entità in una directory di catalogo e una voce della cache che contiene la sua pubblicazione hanno lo stesso pin, come descrive Il lockfile. Una build legge ogni dipendenza fissata dalle fonti già presenti sulla macchina: prima le directory di catalogo, come ovunque, poi la cache dei contenuti sotto .aggrega/cache. Leggerle non interroga alcun registry; solo il passaggio di pull, dove una build ne esegue uno, scarica.

Una voce della cache che non contiene più il proprio pin viene ignorata. Un’entità modificata sul posto — un nuovo corpo con la stessa version — lascia nella cache dei contenuti il corpo precedente con quel nome e quella versione. Dove una directory di catalogo contiene una copia il cui contenuto ha come digest il pin, la build legge quella copia e non legge mai la voce, e lo segnala sullo standard error, indicando la voce ed entrambi i digest:

reuse: cache entry for <name>:<version> holds <digest the entry holds>, not the pinned <pinned digest>; passed over for <catalog file>, which holds the pinned bytes

Dove nessuna directory di catalogo contiene l’entità, una voce della cache completa che contiene esattamente i byte fissati viene letta come la dipendenza, quindi un’entità rimossa dalla sua directory di catalogo dopo che la sua copia pubblicata è stata scaricata viene comunque compilata da quella copia.

Dove nessuna fonte contiene i byte fissati, la build si arresta prima di qualsiasi rendering, con E0135 — o E0133 dove il manifest della voce della cache non è quello fissato dal lockfile. L’arresto indica il pin, la voce della cache e il digest che contiene, e ogni copia dell’entità nelle directory di catalogo con il suo digest, oppure che nessuna directory di catalogo la contiene. Il rimedio è un pull con un registry raggiungibile, che scarica di nuovo la versione fissata e verifica ciò che scarica rispetto al pin; vedi Rispettare o aggiornare per sapere cosa fa il pull quando il registry non serve più quei byte.

Il rendering che aggrega pull esegue per scoprire gli input esterni, e una build o un’anteprima tramite aggrega serve o aggrega mcp, leggono i propri pin allo stesso modo.

Input esterni al momento della build

Un rendering può richiedere contenuto da un URL remoto — per esempio lo schema dei valori di un chart con un riferimento remoto — e una build non ne scarica mai uno per aggiungerlo a ciò che il rendering può leggere. Una richiesta per un URL che il lockfile fissa già viene servita dall’archivio degli input del workspace e verificata rispetto al digest registrato prima che qualsiasi byte raggiunga il rendering. Una richiesta per un URL non fissato si arresta, indicando l’URL e il passaggio che lo fissa; non esiste un’impostazione che trasformi quell’arresto in un download, perché ampliare silenziosamente l’insieme degli input che una build legge è l’unica cosa che una build riproducibile non deve fare.

Dove la copia di un input fissato nell’archivio è andata persa, solo quell’input viene scaricato di nuovo tramite il digest che il lockfile registra già, e verificato rispetto a esso prima che qualcosa venga scritto o restituito. Questo non può cambiare ciò che il rendering vede — il digest è stato stabilito quando l’input è stato fissato — quindi ripara l’archivio anziché ampliare la chiusura, e il lockfile resta invariato byte per byte. Con la postura offline non esiste un trasporto nemmeno per questo, e la copia mancante provoca invece un arresto, che indica la postura.

Il pinning avviene quando le dipendenze della Release vengono risolte, quindi ciò che una build può leggere è stabilito prima che la build inizi. aggrega pull è quel passaggio, ed è l’unico.

Il registro di fiducia dei plugin

Diversi comportamenti di una build dipendono da plugins-trust.yaml, il file committato accanto al lockfile della Release che registra a quale plugin si è risolto ciascun collegamento che restituisce un verdetto: un collegamento plugins.governance in un ruolo ir-verdict o render-verdict, e ogni collegamento plugins.linter. aggrega pull lo scrive e lo schema del registro di fiducia dei plugin ne descrive i campi; quanto segue riguarda solo ciò che una build stessa ne fa.

Una build è vincolata al registro prima che venga eseguito uno qualsiasi di quei plugin. Un plugin servito dalla cache il cui digest dell’artefatto non è quello registrato viene rifiutato anziché eseguito — è la risoluzione che un tale collegamento assume normalmente, e aggrega pull illustra quali altri modi di risolverne uno non sono governati dal digest registrato. Inoltre, una voce registrata di cui nessun collegamento in .aggrega-config.yaml rende più conto arresta la build: rimuovere un controllo non cambia alcun byte del rendering, quindi l’output prodotto senza un controllo revisionato appare esattamente come l’output che quel controllo ha approvato. L’arresto indica il plugin e offre i due rimedi che differiscono a seconda di ciò che intendevi — collegarlo di nuovo se la rimozione è stata un errore, o chiedere esplicitamente la rimozione se non lo è stata — e stampa il comando pronto da eseguire. Un collegamento che il registro non contiene ancora è un primo avvistamento, e nessuno dei due confronti si arresta su di esso.

Una build vincola ciascuno di quei plugin alla firma registrata nella sua voce, esattamente come vincola una voce del lockfile a quella registrata in quella voce. Dove una voce registra una signature verificata, la build ricalcola l’hash del bundle di firma indicato da quel fatto nella cache prima di qualsiasi rendering, e si arresta con E0144 dove il bundle manca o differisce. Per un plugin che legge dalla cache dei contenuti, legge anche da quel bundle per quale artefatto è stata creata la firma, e si arresta con E0332 dove è stata creata per un plugin diverso da quello letto dalla build — che è l’aspetto di una signature copiata da un’altra voce — qualunque cosa dica il requisito di firma. Per un plugin servito dalla cache dei contenuti, entrambi i rifiuti indicano aggrega pull --release <release>: il pull successivo verifica di nuovo la firma del plugin, registra quella del plugin stesso e mette in cache il bundle che essa indica, riscrivendo una copia in cache che non corrisponde più al suo digest. Dove la configurazione di fiducia del workspace richiede una firma per un plugin che la build legge dalla cache dei contenuti — con le stesse impostazioni che farebbero rifiutare a aggrega pull il plugin non firmato, quindi skip_signature_verification e un registry advisory lasciano procedere la build come lasciano procedere il pull — una voce che non registra alcuna firma, o l’assenza di qualsiasi voce per il plugin, arresta la build con E0331, indicando il plugin, plugins-trust.yaml e le impostazioni che richiedono la firma. Il rimedio è aggrega pull --release <release>, che verifica la firma del plugin nel suo registry a ogni esecuzione e la registra. Un plugin servito da una delle tue directory di catalogo, o dalla copia all’interno del binario del compilatore, non è mai soggetto a quel requisito. Come il resto della build, questo legge file già presenti sulla macchina e non interroga alcun registry.

Una build indica ogni ritiro che il registro riporta, accanto a ogni ritiro che riporta il lockfile. Un marcatore che aggrega pull ha registrato per uno di quei plugin viene segnalato come riga deprecation: che indica il plugin, la severità registrata e il messaggio di chi l’ha pubblicato, a ogni severità, e build.halt_on_deprecated_severity decide se arresta anche la build, con la stessa regola che applica a un riferimento fissato. Ogni altra superficie che riferisce su una Release indica lo stesso insieme con le stesse parole, e nessuna di esse si arresta per questo: aggrega validate --release, aggrega lint --release, aggrega inspect --closure, la validazione e la risposta sulla chiusura del language server, e gli strumenti describe e validate dell’assistente. Un registro presente che non può essere letto arresta la build invece di passare per uno che non registra nulla.

aggrega build --upgrade riscrive quel file. Implica --auto-pull ed esegue un aggiornamento completo senza argomenti, che risolve di nuovo ogni dipendenza e quindi risolve di nuovo e riscrive ogni identità registrata, ed elimina ogni voce di cui nessun collegamento rende conto. Quindi, se dopo una build di upgrade questo file risulta modificato, il motivo è questo: la portata del flag è ogni dipendenza, e le identità registrate fanno parte di ciò che viene risolto di nuovo anche se non sono pin del lockfile. A differenza di aggrega pull --upgrade, il flag della build non accetta un target, quindi non può essere ristretto a un solo plugin: per adottare o eliminare una singola identità, esegui invece aggrega pull --upgrade --release <release> <plugin>, che lascia invariati ogni altro pin e ogni altra identità registrata.

Poiché la sua portata è tutto, chiede conferma prima di iniziare. aggrega build --upgrade conferma l’aggiornamento alle stesse condizioni del semplice aggrega pull --upgrade — i due sono lo stesso atto, quindi pongono la stessa domanda. Passa --yes per rispondere in anticipo nell’uso non interattivo; se lo standard input non è un terminale e manca --yes, la build rifiuta anziché attendere una risposta che nessuno può dare. Una build che non esegue l’aggiornamento non chiede nulla.

Risoluzione del workspace e determinismo

Il riferimento manifest: richiesto dallo schema della Release viene risolto relativamente al file della Release. Una voce catalog_dirs relativa (e un percorso relativo di plugin sul filesystem) viene risolta rispetto alla directory del .aggrega-config.yaml che l’ha dichiarata — «relativo» significa sempre relativo al file in cui l’hai scritto, quindi un percorso significa la stessa cosa ovunque tu invochi aggrega. Un flag --catalog, che non ha un file dichiarante, viene risolto rispetto alla directory di lavoro corrente. I riferimenti a registry (oci://…, un riferimento hub) restano invariati.

La radice del workspace è la directory del .aggrega-config.yaml antenato più vicino che contiene un blocco workspace:, oppure la directory indicata da --workspace-root. Quando la radice è fissata in questo modo, una build è indipendente dal punto di invocazione: eseguire aggrega build dalla radice del progetto e da una sottodirectory produce IR e artefatti di rendering identici byte per byte, perché il catalogo cercato e i percorsi sorgente registrati nell’output non cambiano con la directory di lavoro. (Senza il marcatore workspace: e senza --workspace-root, la radice è la directory di lavoro, quindi l’output è ancorato lì — a meno che la directory di lavoro non ancori nulla e --release indichi la Release con un percorso assoluto: la radice viene allora individuata di nuovo a partire dalla cartella della Release stessa, quindi il catalogo cercato e i percorsi registrati nell’output sono quelli del progetto a cui appartiene la Release, da qualunque punto tu esegua il comando. Vedi configuration.md.) Dove nemmeno così viene trovato un workspace e nulla ne indica uno, la build avverte sullo standard error che la cartella usata come radice non si trova all’interno di un workspace, e indica il comando che la rende tale; una build a cui è chiesto di risolvere prima le proprie dipendenze viene rifiutata prima che venga scaricato qualcosa, perché la cache che quella risoluzione riempie verrebbe scritta in quella cartella e la renderebbe un workspace. Una build che prima non risolve nulla esegue comunque il rendering, ma per lo stesso motivo un input esterno che il lockfile fissa e che la cache non contiene più non viene scaricato di nuovo: al plugin che lo richiede viene comunicata al suo posto la frase del rifiuto, come gli viene comunicata quella della postura offline, e la build riporta cosa ne fa quel plugin. Un --workspace-root o un AGGREGA_WORKSPACE_ROOT che indica una cartella inesistente viene rifiutato prima che la build faccia qualsiasi altra cosa, indicando quale dei due l’ha fornito.

Variabili d’ambiente

Le impostazioni del workspace che la build legge possono essere sovrascritte tramite l’ambiente, sopra la configurazione committata e sotto qualsiasi flag: AGGREGA_OFFLINE, AGGREGA_AUTO_PULL, AGGREGA_CATALOG_DIRS (separate secondo l’elenco di percorsi del sistema operativo; fornisci percorsi assoluti), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY e AGGREGA_WORKSPACE_ROOT. Vedi environment-variables.md per l’elenco completo e il modello di precedenza.

Output

Gli artefatti di rendering finiscono sotto dist/ nella radice del workspace, da qualunque cartella venga eseguito il comando — la radice stessa, una cartella al suo interno o una cartella altrove con la radice indicata da --workspace-root o AGGREGA_WORKSPACE_ROOT — e la riga finale indica quella directory per intero:

Build completed: 4 files written to <workspace>/dist

<workspace> sta qui per la radice del workspace, che la riga riporta come percorso completo. Dove non viene trovato alcun workspace e nulla ne indica uno, la radice è la cartella da cui è stato eseguito il comando, quindi dist/ viene scritto lì. Un dist che è un collegamento che porta fuori dal workspace viene rifiutato prima che qualcosa al suo interno venga rimosso o scritto. Una Release che non dichiara confini scrive per provider: dist/<provider>/<files>. Un confine dichiarato senza directory: scrive per confine e per provider: dist/boundaries/<boundary-path>/<provider>/<files>. Gli override directory: e subDirectory: scritti dall’operatore sui confini della Release cambiano il percorso di destinazione; il collasso per (path, provider) unisce i contributori che si risolvono nello stesso percorso valutato.

File che la build non ha scritto

Una build scrive i propri file e non rimuove nulla che non abbia scritto, con un’eccezione: dist/boundaries/, che una build rigenera per intero, viene svuotata prima della scrittura, così un file lasciato lì da una build di un’altra variante non sopravvive in un albero che non lo produce più. Tutto il resto in dist/ resta com’è — un file scritto da una build precedente che questa non produce più, un file che il directory: di un boundary ha posto lì in un’esecuzione precedente e un file che hai messo lì tu stesso, allo stesso modo — perché la build non può distinguere un residuo da un file che tieni lì di proposito.

Ciò che fa invece è dirtelo. Una volta scritti i propri file, la build guarda in dist/ stessa e in ogni directory sotto di essa in cui ha scritto un file o che ha attraversato per scriverne uno più in profondità, e indica ogni file lì presente che non ha scritto in questa esecuzione, in un unico avviso su standard error. I file sono indicati con i loro percorsi relativi a dist/, ordinati, così lo stesso albero viene segnalato allo stesso modo a ogni esecuzione:

warning: the output directory holds 2 file(s) this build did not write, in directories it wrote into; nothing was removed, so they sit beside this build's output: "app/stale-from-earlier-run.yaml", "beside-the-tree.txt"

La riga di chiusura poi li conta:

Build completed: 1 file written to <workspace>/dist, beside 2 files this build did not write

Una directory in cui la build non ha scritto nulla, né direttamente né più in basso, non viene esaminata, così una tua cartella tenuta sotto dist/ non viene elencata file per file. Una build che non trova alcun file di questo tipo non stampa alcun avviso, e la sua riga di chiusura è quella mostrata in Output. In entrambi i casi i file che la build scrive sono gli stessi byte. Per confrontare due build, o per partire da zero, rimuovi dist/ prima della build.

La richiesta aggrega/build di aggrega serve e lo strumento build dell’assistente (aggrega mcp) scrivono attraverso lo stesso passaggio, quindi indicano gli stessi file con la stessa frase: il daemon come uno dei notices della sua risposta, e lo strumento come l’ultimo dei suoi advisories. Un dry run non scrive nulla, quindi non segnala nulla di tutto ciò.

Indentazione YAML

Ogni artefatto YAML di rendering — file docker-compose, template e valori dei chart Helm e manifest Kubernetes — viene emesso con una larghezza di indentazione uniforme. La larghezza è impostata da build.yaml_indent in .aggrega-config.yaml e il valore predefinito è 2 (la larghezza convenzionale per quei formati):

build:
yaml_indent: 2 # default; accepts 2 through 9

La larghezza viene applicata in un unico punto di serializzazione condiviso da tutti i renderer, quindi l’output resta identico byte per byte tra esecuzioni con lo stesso input. I valori fuori dall’intervallo [2, 9] vengono rifiutati dalla validazione dello schema di configurazione.

Restituire il grafo compilato

--ir-graph scrive su standard output, in JSON, il grafo che questa build ha risolto. È additivo: gli artefatti vengono comunque scritti in dist/, il riepilogo viene comunque stampato e i byte di rendering restano invariati. Il grafo esce prima di tutto ciò che la build stampa lì — un documento JSON e un carattere di nuova riga finale — così un consumatore che decodifica il flusso lo legge e si ferma.

Il grafo restituito è quello consumato dal rendering, quindi descrive esattamente la build che ha prodotto gli artefatti accanto a esso anziché una seconda risoluzione della stessa Release. Si combina con --dry-run: il grafo viene scritto e il rapporto sugli artefatti lo segue, senza scrivere nulla su disco.

I valori che un autore ha dichiarato sensibili vi sono nascosti — inclusi i values e infra di una connessione, dove il socket del componente consumatore dichiara sensibile una foglia — nella forma strutturata descritta in aggrega inspect. --unredacted accanto a --ir-graph li stampa invece, alle condizioni indicate da aggrega inspect --unredacted: raggiunge il grafo e nient’altro — i file di trace hanno il proprio --trace-unredacted, e gli artefatti di rendering non vengono mai nascosti — e qualunque cosa l’output raggiunga riporta poi quei valori in chiaro. Passato senza --ir-graph viene rifiutato, perché non ci sarebbe nulla da rivelare.

Lo stesso flag, con lo stesso significato, è presente in aggrega inspect e aggrega validate.

Anteprima di una build senza scriverla

--dry-run esegue la stessa compilazione di una build — gli stessi controlli sulle dipendenze, lo stesso rendering, gli stessi provider — e stampa ciò che emetterebbe invece di scriverlo. Ogni artefatto viene riportato con il percorso che occuperebbe e il contenuto che avrebbe:

aggrega build --release releases/production.yaml --dry-run
==> <workspace>/dist/main/helm/webapp-configmap-webapp.yaml <==
apiVersion: v1
kind: ConfigMap
...
Total build time: 2.5s
Dry run: 1 file would be written to <workspace>/dist; nothing was written

Gli artefatti vengono riportati nell’ordine in cui una build li scrive, quindi lo stesso input riporta gli stessi byte nella stessa sequenza, e il percorso riportato è quello in cui una build scriverebbe — sotto la radice del workspace, riportato per intero dove sopra compare <workspace>.

Cosa non viene scritto. La directory di output resta esattamente com’è — non viene nemmeno ripulita, quindi l’output di una build precedente sopravvive intatto a un dry run. Il lockfile non viene scritto. Nulla viene scritto in .trace/.

Gli input esterni si comportano esattamente come in una build normale, alle condizioni illustrate in Input esterni al momento della build. Un dry run legge quindi la stessa chiusura fissata che leggerebbe la build che rappresenta, e ciò che mostra è ciò che quella build scriverebbe.

Dove un riferimento è stato rifiutato, l’esecuzione indica tutti quelli che non ha potuto raggiungere e rimanda al comando che li fissa:

note: the lockfile does not pin every external reference this render requested, so the following were declined and the render stopped short of the artifacts it would otherwise emit:
- https://charts.example.com/values-schema.json
Run `aggrega pull --release releases/production.yaml` to pin the inputs the render needs, then run the dry run again

Esegui aggrega pull una volta e il dry run ha tutto ciò che gli serve; nient’altro cambia.

Un dry run ha bisogno di un lockfile e non ne riempie mai uno. Per impostazione predefinita la build è in sola lettura, e un dry run mantiene questo comportamento in qualunque modo sia stato richiesto un riempimento. --auto-pull e --upgrade vengono rifiutati del tutto (vedi sotto); l’impostazione del workspace auto_pull viene ignorata per quella singola invocazione, così un workspace che per impostazione predefinita riempie il lockfile può comunque essere visualizzato in anteprima. Senza lockfile un dry run si arresta con lo stesso rimedio di una normale build in sola lettura: esegui prima aggrega pull.

I flag che rifiuta. Tre flag scrivono, quindi combinarli con un dry run non ha un esito onesto — ignorare la scrittura farebbe svanire un riempimento richiesto, e rispettarla infrangerebbe l’unica promessa che il dry run fa. Ogni combinazione si arresta prima di qualsiasi lavoro, indicando il flag passato e il passaggio da eseguire invece:

Combinato conPerché viene rifiutato
--auto-pullriempie il lockfile; esegui aggrega pull come passaggio a sé
--upgraderisolve di nuovo ogni dipendenza e riscrive il lockfile; esegui aggrega pull --upgrade come passaggio a sé
--tracescrive file per nodo in .trace/; esegui la build con trace senza --dry-run

Tutto il resto si combina normalmente. --verify-determinism esegue il rendering di ogni nodo due volte e confronta i byte senza scriverne nessuno, e --catalog, --quiet, --progress, --debug e i filtri degli avvisi si comportano esattamente come in una build che scrive.

A cosa serve e a cosa non serve. Un dry run risponde a «cosa emetterebbe questa Release», una domanda a cui solo un rendering può rispondere — quindi non sostituisce aggrega validate, che verifica la correttezza senza rendering, né aggrega inspect, che interroga il grafo prima del rendering. Ricorri a un dry run quando la risposta che vuoi sono gli artefatti stessi: per esaminare cosa una modifica alla Release fa all’output, o per verificare una modifica a una Recipe prima di committare qualcosa in dist/.

Output di trace

Il flag --trace attiva un dump di debug per nodo che cattura ogni stato intermedio del compilatore. L’output si trova in .trace/ sotto la radice del workspace, accanto a dist/ (mai al suo interno; la disposizione affiancata segue la convenzione di .git/, .terraform/, node_modules/ e mantiene dist/ puramente distribuibile).

La struttura delle directory è per confine e per istanza:

.trace/
└── boundaries/
└── <boundary-path>/
└── <instance-id>/
├── 01-pillars-initial.yaml
├── 02-provides-evaluation.yaml
├── 03-inject-hydration.yaml
├── 04-inject-mapping.yaml
├── 05-source-resolution.yaml
├── 06-source-locals.yaml
├── 07-values-mapping.yaml
├── 08-workload-synthesis.yaml
├── 09-artifact-evaluation/
│ └── <per-artifact-file>.yaml
├── 09b-feature-rendering-boundary.yaml
├── 10-engine-synthesis/
│ └── <per-synthesized-file>.yaml
├── 11-engine-emission.log
└── 12-labels-injected.log

Ogni slot cattura uno specifico stato del compilatore:

  • 01-pillars-initial.yaml — lo snapshot per nodo del contesto che un template legge, preso dopo la risoluzione e prima di qualsiasi mutazione per fase. Contiene .values, .infra, .context, .parameters, .metadata.
  • 02-provides-evaluation.yaml — gli output provides: risolti dopo la valutazione dei provides.
  • 03-inject-hydration.yaml — la pipe .context.inject unita dopo l’idratazione degli inject (vista lato consumatore dei provides a monte).
  • 04-inject-mapping.yaml — la pipe .context.inject dopo le riscritture injectMapping della FeatureRecipe.
  • 05-source-resolution.yaml — il contenuto source: analizzato che il provider consumerà. Presente solo quando la Recipe dichiara source:.
  • 06-source-locals.yaml — il blocco locals: risolto. La risoluzione della sorgente pubblica .locals prima di valutare il template source:, ed è per questo che questo slot viene scritto indipendentemente dal fatto che la Recipe dichiari source:.
  • 07-values-mapping.yaml — l’output di rendering di valuesMapping: (il dizionario che il provider riceve). Presente solo quando la Recipe dichiara valuesMapping:.
  • 08-workload-synthesis.yaml — il contesto così com’era quando il template workload: è stato valutato e il suo output analizzato. Presente solo quando la Recipe dichiara workload: (inline o caricato con $import:). Il Workload analizzato non si trova in questo slot: compare da 09-artifact-evaluation/ in poi, una volta stabilizzato anziché ancora in corso.
  • 09-artifact-evaluation/ — un file per ogni artefatto valutato. Presente solo quando la Recipe dichiara artifacts: (con voci inline o caricate singolarmente con $import:).
  • 09b-feature-rendering-boundary.yaml — il contesto com’è alla fine del rendering del nodo, una volta che le FeatureRecipes collegate a esso hanno generato le proprie risorse, con accanto il workload analizzato. Scritto per ogni nodo.
  • 10-engine-synthesis/ — un file per ogni manifest sintetizzato che il provider ha prodotto dal Workload (modalità workload di helm/compose). Presente solo quando il provider ha eseguito un percorso di sintesi.
  • 11-engine-emission.log — il riepilogo post-emissione (numero di file, percorsi di output) per il nodo.
  • 12-labels-injected.log — le label e le annotazioni di provenienza scritte sull’output di rendering per il nodo.

A partire da 03-inject-hydration.yaml, uno slot che mostra il contesto del nodo riporta il blocco .context.inject ogni volta che la pipe che cattura consegna almeno una chiave, con qualsiasi meccanismo: env, file, arg, o un meccanismo con un altro nome in cui scrive una mappatura inject, l’injectMapping di una FeatureRecipe o il blocco inject: del componente stesso. Anche un nodo la cui unica consegna è un tale meccanismo personalizzato mostra il blocco, con quel meccanismo sotto il proprio nome e le sue chiavi in all, e un valore dichiarato sensibile si legge come <redacted> in entrambi i punti. Uno slot catturato mentre la pipe non consegna nulla non ha alcun blocco .context.inject.

Lo scrittore del trace non è bloccante: il trace viene scritto su disco in parallelo alla compilazione anziché lungo il suo percorso. La latenza di compilazione non è influenzata dall’I/O del trace — la stessa compilazione termina nello stesso tempo reale che --trace sia attivo o meno.

Valori dichiarati sensibili nel trace

Un dato che un autore ha dichiarato sensibile — una foglia di schema che riporta sensitive: true, o una chiave di consegna il cui materiale proviene da una chiave provides che lo riporta — viene scritto nel trace come il testo fisso <redacted>. La chiave viene mantenuta e solo il valore viene sostituito, quindi uno slot mostra comunque quali foglie e quali chiavi di consegna ha un nodo. Un elemento affine non dichiarato nello stesso blocco stampa il proprio valore alla lettera; la sostituzione segue la dichiarazione e nient’altro.

Anche un valore che una FeatureRecipe consegna tramite il proprio injectMapping viene nascosto. È la via a cui uno slot che dichiara un elenco inject vuoto affida la consegna, e la via che segue una realizzazione di credenziali solo tramite inject. La chiave di consegna che una tale mappatura scrive è essa stessa un template, quindi nessuna dichiarazione la nomina; ciò che viene letto invece è il testo stesso della mappatura. Quando quel testo fa riferimento a una foglia values o infra che la Feature collegata dichiara sensitive: true, ogni chiave di consegna prodotta dalla mappatura si legge come <redacted> — inclusa una chiave che non contiene nulla di sensibile, poiché la lettura è per collegamento anziché per chiave. Una mappatura che non fa riferimento a nulla di dichiarato stampa le proprie chiavi alla lettera.

Anche un valore che un template ha calcolato da un dato dichiarato sensibile viene nascosto, sebbene la sua chiave non porti alcuna dichiarazione. Ciò che lo identifica è il riferimento scritto dall’autore: una voce locals: il cui template legge una foglia dichiarata sensibile viene nascosta, e così un campo source: che lo fa. La lettura è conservativa — un template che raggiunge un intero oggetto raggiunge ogni foglia dichiarata al suo interno, quindi {{ range $k, $v := .values.creds }} nasconde il proprio output quando qualcosa sotto creds è dichiarato — e una voce locals: che legge un elemento affine già nascosto viene a sua volta nascosta. Una voce affine della stessa forma che non legge nulla di dichiarato stampa alla lettera.

Un valore che attraversa un arco uses viene nascosto in base alle dichiarazioni del target, non del nodo consumatore, e viene nascosto su entrambe le superfici a cui l’arco lo porta. .context.uses.<alias>.provides riproduce ciò che il componente target ha pubblicato, quindi ciò che governa quei valori è lo schema del target: una chiave provides che il target ha dichiarato sensibile si legge come <redacted> nello slot del consumatore anche quando il consumatore non dichiara nulla. Quando il blocco inject dell’arco stesso instrada quella chiave su una chiave di consegna del componente consumatore, .context.inject nasconde anche quella chiave di consegna — la stessa regola che segue già la mappatura inject di un collegamento, leggendo la stessa dichiarazione. Il nascondimento è per arco, quindi due archi che pubblicano lo stesso nome di chiave provides si risolvono in modo indipendente: quello il cui target l’ha dichiarata viene nascosto e l’altro stampa alla lettera. Il resto dell’arco — il suo target, il suo socket, le sue label e i nomi delle chiavi della mappatura inject — non è ciò che governa una dichiarazione provides del target, e stampa alla lettera.

I values e infra per connessione scritti sull’arco stesso sono invece governati dal socket del componente consumatore: il valueSchema e l’infraSchema che quel socket dichiara, che sono i contratti rispetto ai quali quella configurazione viene validata. Una foglia che uno dei due contratti dichiara sensitive: true si legge come <redacted> in .context.uses.<alias>.values o .context.uses.<alias>.infra, con la chiave mantenuta, e così anche una foglia che si trova a un valore predefinito dichiarato dal contratto; un elemento fratello non dichiarato stampa alla lettera. Le dichiarazioni del target qui non hanno alcun ruolo, e il nascondimento è per connessione, quindi una foglia con lo stesso nome su una connessione il cui socket la dichiara leggibile stampa alla lettera.

I collegamenti scritti su una connessione sono mostrati sotto l’arco di quella connessione, in .context.uses.<alias>.features.<slot>, e ciascuno viene nascosto in base alle dichiarazioni della propria Feature — le stesse che governano quella Feature quando un componente la detiene direttamente. Una foglia values o infra che la Feature dichiara sensitive: true si legge come <redacted>, e lo stesso vale per una chiave dei provides risolti del collegamento che la Feature dichiara sensibile; ogni chiave viene mantenuta. Il tipo, la versione e le label del collegamento, e ogni foglia e chiave provides che la sua Feature lascia non dichiarata, stampano alla lettera, così un locator pubblicato resta leggibile accanto al materiale che individua. Il nascondimento è per connessione e per slot, quindi la stessa Feature scritta su due connessioni si risolve su ciascuna. Uno slot che dichiara sensitive: true — sul componente o sul suo socket — indica che il collegamento gestisce materiale segreto e non nasconde da sé alcuna foglia: quali foglie vengono nascoste spetta alla Feature dichiararlo. I collegamenti propri di un componente non sono tra i blocchi che uno slot mostra, poiché il trace non contiene alcun blocco .features; ciò che un template workload: legge da uno di essi è trattato dal re-rendering descritto più avanti.

Il Workload analizzato è un re-rendering, non una cattura del documento emesso dalla build, e gli slot che lo contengono — 09-artifact-evaluation/, 10-engine-synthesis/ e 09b-feature-rendering-boundary.yaml — lo dichiarano in una voce workload_note accanto a esso. Un documento di rendering non registra nulla su quale dichiarazione abbia originato un dato carattere, quindi al suo interno non c’è alcuna chiave in cui sostituire. Ciò che il trace mostra invece è lo stesso template workload: valutato una seconda volta, su un contesto i cui dati dichiarati sensibili si leggono già come <redacted>. Poiché il template vede una stringa dove c’era una stringa, il risultato mantiene la forma del documento emesso: gli stessi campi, negli stessi punti, con <redacted> nella posizione stessa del dato nascosto e il testo letterale intorno invariato.

Due modi in cui quel re-rendering differisce da ciò che è stato emesso, entrambi indicati dalla nota:

  • Un template che si dirama in base al contenuto di un valore produce un rendering diverso. Un eq su un valore specifico, un test di lunghezza, un hash o una codifica del valore: ciascuno vede <redacted> e produce un risultato diverso — un ramo diverso, una lunghezza diversa, un digest diverso. Per questo il trace non afferma mai di mostrare il documento emesso.
  • I dati che nessuna dichiarazione nomina vengono riportati invariati. La sostituzione copre ciò che l’asse nomina — una foglia values / infra dichiarata, una chiave di consegna marcata, una chiave provides che il Component del componente stesso dichiara sensibile, i provides dichiarati di un target consumato, una foglia dei values o infra propri di una connessione che il suo socket dichiara sensibile, una foglia o una chiave provides dichiarata di un collegamento che il componente detiene direttamente (letto in .features.<name>) o di uno scritto su una connessione, e un valore locals: o source: calcolato da uno di essi. Sono gli stessi dati per cui viene nascosto un rifiuto sollevato dal template. Un dato che raggiunge il template per qualsiasi altra via, come una chiave provides che nessuna dichiarazione nomina il cui valore una Recipe ha calcolato da una foglia dichiarata, compare nel re-rendering esattamente come compare nel documento emesso.

Quando il re-rendering non può essere prodotto affatto, lo slot mantiene la chiave workload: e sostituisce il documento con una riga che lo dichiara e indica --trace-unredacted. L’indicazione è intenzionale: una proiezione semplicemente scomparsa sarebbe indistinguibile da una Recipe che non dichiara alcun workload:.

Un limite merita di essere letto prima di considerare .trace/ sicuro: dist/ non è oscurato. Gli artefatti di rendering vengono emessi esattamente come li ha prodotti il rendering, perché sono ciò che si distribuisce, e il re-rendering del trace non li raggiunge mai — lo stesso input produce un rendering identico byte per byte che --trace sia attivo o meno.

Tratta .trace/ come qualcosa che contiene materiale sensibile e gestiscilo come si gestisce dist/.

Mostrare i valori oscurati

--trace-unredacted, insieme a --trace, scrive nei file di trace i valori dichiarati sensibili invece del testo che li sostituisce. Esiste perché a volte il valore oscurato è proprio quello di cui si sta facendo il debug — una credenziale che arriva dall’attachment sbagliato appare identica a quella giusta quando entrambe risultano oscurate.

È anche il modo per catturare il documento che la build ha effettivamente emesso: senza nulla di oscurato non c’è nulla da sostituire, quindi gli slot workload: contengono il documento emesso anziché un suo re-render, e la voce workload_note è assente.

Tre proprietà lo delimitano:

  • Ogni file che scrive dichiara che cosa è. Ogni file di trace prodotto dall’esecuzione si apre con un commento che nomina il flag e indica che più sotto i valori dichiarati sensibili compaiono in chiaro, così un file allegato in seguito a una segnalazione di bug o lasciato in una directory condivisa porta con sé il proprio avviso. Il commento è valido nel formato del file stesso, quindi il file resta analizzabile.
  • Raggiunge .trace/ e nient’altro. Gli artifact renderizzati sono identici byte per byte con e senza di esso — cambia ciò che mostra un file di debug, mai ciò che produce una build — e i layout di aggrega inspect e il testo diagnostico stampato da una build fallita sono identici in entrambi gli stati.
  • Vive solo nell’invocazione. Non esiste alcuna impostazione di configurazione per esso, quindi non può essere attivato una volta e lasciato attivo per chiunque esegua in seguito la build del workspace. Richiederlo senza --trace arresta la build con un messaggio che nomina entrambi i flag, anziché accettare una richiesta che non può onorare.

Separatamente dal trace, una build stampa un avviso per ogni chiave di consegna che trasporta materiale dichiarato sensibile come valore letterale, nominando il componente, il target, l’attachment e la chiave di consegna. Non arresta mai la build e --no-unsupported-field-warnings non lo silenzia — quel flag riguarda ciò che un target non può onorare di quanto hai scritto, una classe diversa.

La parola chiave, i suoi due punti di scrittura, la formulazione esatta dell’avviso e il limite completo di ciò che dichiararla consente di ottenere si trovano in vocabulary/compact-form-authoring.md, «Dichiarare una foglia sensibile».

Quando usare --trace

  • Diagnosticare perché un manifest renderizzato non contiene un valore atteso: percorri i dump per passata per trovare il primo slot in cui il valore manca.
  • Verificare il determinismo dopo un aggiornamento del compilatore: due compilazioni dello stesso input con --trace producono dump di trace identici byte per byte; qualsiasi differenza per slot localizza la regressione.
  • Iterazione nella scrittura del catalogo: confrontare gli snapshot 04-inject-mapping.yaml e 06-source-locals.yaml mostra ciò che i template della Recipe vedono al momento della valutazione.

Esempi

Compilare una Release rispetto al catalogo locale:

aggrega build --release releases/production.yaml

Compilare con una directory di catalogo separata:

aggrega build --release releases/production.yaml --catalog ../platform-catalog/

Vedere che cosa emetterebbe una Release senza scriverne nulla:

aggrega build --release releases/production.yaml --dry-run

Compilare con i dump di trace per il debug:

aggrega build --release releases/production.yaml --trace

Dopo la compilazione, ispeziona .trace/boundaries/<boundary>/<instance>/ per lo stato di ogni passata. La directory .trace/ viene sovrascritta a ogni esecuzione con --trace; lo stato di trace precedente non viene conservato tra una compilazione e l’altra.

Riferimenti incrociati

  • aggrega-pull — recupera le entità del catalogo da un registry OCI nel catalogo locale.
  • aggrega-validate — verifica la correttezza del catalogo, della chiusura della Release o di una singola entità senza emettere artifact; la validazione delle dipendenze che una build esegue, senza il render.
  • aggrega-lint — verifica le convenzioni di pubblicazione del catalogo negli stessi tre ambiti.
  • aggrega-inspect — interroga il grafo IR dopo la finalizzazione del grafo senza procedere al render.
  • Errori — il formato categorizzato di presentazione degli errori che emerge nella CLI.

Sinossi

aggrega build [flags]

Descrizione

Compile an Aggregate and Release pair into provider-native artifacts under each
boundary's output directory.
The Release is the single entry point: it names the Aggregate and the Manifest,
declares the boundaries, and routes each component to a provider. What a
provider emits is the provider's own shape — Helm manifests, a redistributable
Helm chart, docker-compose YAML — so the output directory holds whatever the
providers this Release routes to produce.
The output directory is dist/ beneath the workspace root, whichever folder the
command is run from, and the closing line names it in full. A run that finds no
workspace uses the folder it was run from as the root, and writes dist/ there.
Build is read-only by default and needs a lockfile. Run "aggrega pull" first to
create one, or pass --auto-pull to fill it in-process for this build.
Given identical input, build writes byte-identical output, which is what makes
the rendered tree reviewable as a diff.

Flag

FlagPredefinitoDescrizione
--auto-pullfalseEsegue il passaggio di pull prima della build: risolve le dipendenze della Release nel lockfile e nella cache all’interno del processo, quindi esegue la build su di esse. È lo stesso riempimento nel processo eseguito dall’impostazione auto_pull del workspace, attivato per una singola build senza modificare la configurazione del workspace. Da solo è un riempimento incrementale — i pin esistenti vengono rispettati, e i riferimenti senza pin vengono risolti e aggiunti
--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.
--debugfalseEmette su stderr una diagnostica dettagliata leggibile — tempi reali per fase e conteggi di entità/dipendenze. Prevale su —quiet: l’output dettagliato viene sempre emesso. Diverso da —trace, che scrive in .trace/ file intermedi per nodo leggibili dalle macchine
--detailfalseLa build è di sola lettura per impostazione predefinita e non stampa dettagli di risoluzione. Quando viene eseguito il passaggio di pull — perché è stato passato —auto-pull o il workspace abilita auto_pull — la build riempie il lockfile nel processo, che ne esista già uno o no, e questo flag stampa per ogni entità risolta che cosa ha fatto quel riempimento: recuperata ex novo da un registry, riutilizzato uno slot della cache, trovata in un catalogo locale, servita dall’interno del binario del compilatore, oppure esterna (l’Aggregate o il Manifest della Release stessa, letto dal file o dalla voce che la Release indica). Quando non viene eseguito alcun passaggio di pull, stampa invece una riga che lo dice al posto delle righe per entità. Solo stdout; non persistito
--disable-plugin-cachefalseSalta la cache persistente su disco della compilazione dei plugin per questa build e compila i guest dei plugin da zero in una cache in memoria che viene scartata al termine della build. Disattivato per impostazione predefinita, il che riutilizza la cache condivisa su disco tra le build. Non modifica l’output renderizzato
--dry-runfalseEsegue il render della Release e stampa ciò che emetterebbe invece di scriverlo: il percorso previsto di ogni artifact e il suo contenuto vanno su stdout, e la directory di output e il lockfile restano intatti. Gli input esterni si comportano esattamente come in una build ordinaria — gli input con pin vengono serviti dallo store indirizzato per contenuto (e riforniti tramite digest quando il blob manca), e un render che richiede un URL esterno senza pin si arresta nominandolo — quindi ciò che mostra un dry run è ciò che una build scriverebbe. Rifiuta di combinarsi con —auto-pull, —upgrade o —trace, ognuno dei quali scrive — esegui il riempimento delle dipendenze, o una build con trace, come passaggio a sé. Si combina con —policy-input, i cui file sono allora l’unica cosa che scrive
--ir-graphfalseScrive inoltre su stdout, come JSON, il grafo IR calcolato da questa esecuzione, in aggiunta a tutto ciò che questo comando produce già. I valori che un autore ha dichiarato sensibili vi sono oscurati; passa —unredacted per stamparli invece. Gli artifact vengono comunque scritti e il riepilogo viene comunque stampato; il grafo viene scritto prima di entrambi
--no-unsupported-field-warningsfalseSilenzia la classe di avvisi sui campi non supportati: le notifiche che un target solleva per qualcosa che hai scritto e che non può onorare — un campo del Workload che non può esprimere (come accade a un target a fedeltà inferiore quale compose), o un’annotazione aggrega.ai/ su cui non agisce per il tipo di input del nodo. Gli altri avvisi di render continuano a comparire. Solo visualizzazione; non modifica l’output renderizzato
--policy-input—Scrive, in questa directory, il payload che ciascun ruolo di governance consegna a un plugin collegato lì, come una riga di JSON: esattamente ciò che la build consegna al plugin, con ogni valore che la build gli nasconde nascosto anche qui. Per annotation-transform, label-transform e ir-verdict il file è il documento input che legge una policy in quel ruolo. Per render-verdict il motore di policy rimodella il payload prima che una policy lo legga — i documents di ciascun artifact vengono analizzati a partire da esso — quindi una policy render-verdict su un motore integrato si verifica in una build, collegata in modo che riporti a livello warn o info; per un plugin il cui .wasm hai compilato tu, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json lo esegue su quel file. Viene scritto anche un ruolo a cui non è collegato nulla, come il payload che riceverebbe un collegamento senza sorgenti e senza impostazioni, così una policy può essere scritta prima di essere collegata. Ogni ruolo viene scritto in <role>.json (annotation-transform, label-transform, ir-verdict, render-verdict); dove i collegamenti di uno stesso ruolo ricevono payload diversi — uno porta sorgenti o impostazioni proprie, o una trasformazione cambia ciò che legge il successivo — ciascuno viene invece scritto in <role>.<position>.<plugin>.json, dove position conta i collegamenti di quel ruolo a partire da 1 nell’ordine in cui li elenca la configurazione del workspace e plugin è l’ultimo segmento del riferimento del plugin senza la versione, con l’escape di ogni carattere che un nome di file non può contenere. I file con quei nomi già presenti nella directory vengono sostituiti e nient’altro lì viene toccato. I file vengono scritti sia che la build finisca sia che si fermi, e una build che si ferma prima che un ruolo venga eseguito nomina ogni ruolo per cui non ha scritto alcun file. Richiederli non cambia alcun artifact né alcun verdetto. Si combina con —dry-run, che allora scrive questi file e nient’altro: la directory di output e il lockfile restano intatti
--progressfalseForza l’attivazione dell’indicatore di avanzamento della build anche quando stderr non è un terminale, stampando una semplice riga per ogni passaggio man mano che si completa, con il relativo tempo. Il valore predefinito è auto: la checklist interattiva delle fasi viene mostrata solo quando stderr è un terminale che interpreta le sequenze di escape, un terminale che non le interpreta riceve le stesse righe semplici, e l’output reindirizzato o in pipe non ne riceve nessuna. —quiet e —debug prevalgono entrambi su —progress
--quietfalseSilenzia l’indicatore di avanzamento della build su stderr. Non influisce su stdout. Ha la precedenza su —progress
--release—Percorso del file YAML della Release (obbligatorio). Un percorso relativo viene risolto 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
--tracefalsescrive file intermedi per nodo in .trace/ sotto la radice del workspace, accanto a dist/, per l’ispezione post-mortem
--trace-unredactedfalseScrive i valori dichiarati sensibili nei file .trace/ invece del testo che li sostituisce, e marca ogni file scritto dal trace con un’intestazione che lo dichiara. Richiede —trace. Raggiunge .trace/ e nient’altro: gli artifact renderizzati, l’output di aggrega inspect e il testo diagnostico sono identici con e senza di esso. Solo per l’invocazione — non esiste alcuna impostazione della configurazione del workspace per esso, quindi non può mai restare attivo per una build successiva
--unredactedfalseStampa i valori che un autore ha dichiarato sensibili invece di oscurarli. Tutto ciò che l’output raggiunge — un terminale, una pipe, un file, una registrazione dello schermo — contiene quindi quei valori in chiaro. Raggiunge il grafo scritto da —ir-graph e nient’altro, quindi richiede —ir-graph; i file .trace/ usano invece —trace-unredacted
--upgradefalseRende il passaggio di auto-pull un aggiornamento completo: scarta il lockfile esistente e risolve di nuovo ogni dipendenza dallo stato attuale del registry, portando ciascuna alla versione più alta disponibile invece di rispettare i pin esistenti. Implica —auto-pull — da solo esegue un pull di aggiornamento completo prima della build. Non accetta un target, quindi non può essere ristretto a una sola dipendenza: per adottare o eliminare un singolo pin, esegui invece aggrega pull —upgrade —release , che mantiene invariato ogni altro pin. Poiché elimina ogni pin registrato, chiede prima conferma; —yes risponde in anticipo, e su uno stdin non interattivo rifiuta anziché attendere una risposta che nessuno può dare
--verify-determinismfalseEsegue il render di ogni nodo due volte e confronta i byte emessi, arrestando la build se i due render di un nodo differiscono. Disattivato per impostazione predefinita. Usalo per confermare che un provider esegue il render in modo deterministico — un input identico produce un output identico byte per byte — su cui si basano le garanzie di diff GitOps e di output identico byte per byte
--yesfalseRisponde in anticipo alla conferma di —upgrade, per l’uso non interattivo. Raggiunge quel solo prompt e nient’altro: una build che non esegue l’aggiornamento non chiede nulla, quindi passarlo lì non modifica alcun comportamento