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

aggrega explain

Spiega la condizione di arresto nominata da un codice

Sinossi

aggrega explain <code>

Descrizione

Explain the halting condition a code names.
A halting diagnostic opens with the category the failure is attributable to and the condition's short code — the letter E and four digits, as in [CATALOG_ERROR E0209]. That short code is the one to pass here; it is fixed once a condition is published, so a code quoted out of an old report still names the same condition.
aggrega explain E0209
The descriptive code is accepted too — the hyphenated one naming the condition in words, which a structured diagnostic carries as a field of its own. A condition's two codes name the same condition and reach different readers, so either is a code you may be holding, and the condition above is registered under recipe-values-mapping-requires-source:
aggrega explain recipe-values-mapping-requires-source
Every condition is declared inside this binary, so the identifiers and the sentence are reported without a network or a cache. The published reference supplies the walk-through of the authoring fix for every condition, and nothing else is resolved against it. It is read from the documentation bundle published for this version of aggrega on the default registry — or, where none is published for it, the newest one published for an earlier version — kept in the cache every project on this machine shares, acquired on first use when that cache holds no copy this workspace's signature check admits. Where it cannot be acquired, the condition is still reported and the reason the walk-through is missing is stated.
A number that named a condition and no longer does is reported as retired, with what it named, so a code quoted from an old report is never answered with a different condition.

Cosa fa

Una build che si arresta stampa un’intestazione tra parentesi quadre che indica la categoria a cui è attribuibile l’errore e il codice breve della condizione — la lettera E e quattro cifre:

[CATALOG_ERROR E0209] Recipe: valuesMapping requires source ...

aggrega explain E0209 trasforma quel codice nella condizione che indica e nella spiegazione passo passo della correzione da apportare:

Terminal window
aggrega explain E0209

La risposta si apre con entrambi gli identificatori della condizione e la frase fissa con cui iniziano i suoi diagnostici, e poi riproduce la voce che spiega cosa causa la condizione e cosa cambiare — la stessa voce pubblicata in fatal-halts.md.

Il codice da passare

È accettato l’uno o l’altro dei due codici della condizione, perché ciascuno ti raggiunge su una superficie diversa.

Il codice breve è quello che ti mostra un terminale, ed è quello a cui ricorrere quando hai solo l’output stampato. Un numero viene assegnato una volta e poi resta fisso, quindi un codice breve che hai incollato in un report un anno fa indica ancora la condizione che indicava allora.

Il codice descrittivo è quello con i trattini che un diagnostico strutturato porta come campo a sé, e su cui un programma si dirama. Indica la condizione a parole e non ha prefisso, quindi resta fisso anche quando il compilatore viene riorganizzato attorno a esso. Se è quello che hai in mano, passa quello — la condizione qui sopra è registrata come recipe-values-mapping-requires-source:

Terminal window
aggrega explain recipe-values-mapping-requires-source

I due codici di una condizione indicano la stessa condizione, quindi entrambe le grafie ricevono una risposta identica. Il codice breve viene confrontato senza distinzione tra maiuscole e minuscole, perché è un valore che leggi da uno schermo e riscrivi.

sentinels.md illustra i tre identificatori di una condizione e quando ricorrere a ciascuno.

Da dove viene la risposta

Ogni condizione dichiarata da questo binario riceve risposta dal binario. I suoi due codici e la frase con cui si aprono i suoi diagnostici sono dichiarati all’interno del compilatore, quindi per questo non servono rete, cache né configurazione.

Un codice che questo binario non dichiara viene cercato nel riferimento pubblicato. Un plugin segnala un arresto scegliendo una condizione dichiarata dal compilatore, quindi nessuna condizione è dichiarata altrove. Il riferimento pubblicato, sentinels.md, elenca ogni condizione dichiarata dal prodotto, e può essere stato pubblicato per una versione diversa da quella del binario che stai eseguendo — così un codice citato da un report prodotto con una versione più recente o più vecchia può comunque essere risolto lì.

Anche la spiegazione passo passo è documentazione pubblicata, letta da fatal-halts.md. Entrambe le pagine provengono dal bundle della documentazione, che viene conservato una sola volta per macchina nella cache condivisa da ogni progetto Aggrega, una copia per ogni registry e versione — vedi aggrega cache. Il bundle letto è quello pubblicato per la versione di aggrega che stai eseguendo; dove per quella versione non ne è pubblicato nessuno, è il più recente pubblicato per un rilascio precedente — la stessa scelta che fa aggrega scaffold --example, così i due non leggono mai documentazione diversa. Un codice che il riferimento di un rilascio precedente non contiene può nominare una condizione dichiarata in seguito, quindi viene rifiutato come non determinabile anziché come un codice che non nomina nulla, e il rifiuto dice di quale versione è stato letto il riferimento. Il tuo workspace decide da quale registry proviene il bundle, il suo registry predefinito, e se una copia già presente sulla macchina possa essere letta: prima che una pagina venga servita, le firme conservate accanto alla copia vengono verificate di nuovo con il controllo delle firme del tuo workspace per quel registry, lo stesso controllo a cui è soggetto un fetch del bundle. Quel controllo viene eseguito anche offline. Dove fissa una chiave o una trust root legge solo quelle; dove non fissa né l’una né l’altra, come fa il controllo integrato dell’hub ufficiale, verifica rispetto alla trust root pubblica di Sigstore, che un workspace offline non può scaricare — quindi offline verifica rispetto alla trust root lasciata in .sigstore nella tua home directory da un precedente fetch online su questa macchina, e non scarica nulla. Quando la macchina non ha alcuna copia, o nessuna ammessa dal tuo controllo, il comando ne acquisisce una con quel controllo, una volta sola, e in seguito legge dalla cache. La stessa copia serve la documentazione che un assistente legge tramite aggrega mcp e le spiegazioni che un editor mostra tramite aggrega serve.

Vale la pena riconoscere tre risposte, perché ciascuna ti chiede qualcosa di diverso.

Una condizione ancora senza voce. Vengono riportati i codici e la frase, e una nota dice che la pagina delle condizioni di arresto non contiene alcuna spiegazione passo passo per quella condizione. Ogni condizione resta comunque elencata in sentinels.md.

Nessuna documentazione disponibile. Per una condizione dichiarata dal compilatore, i codici e la frase vengono comunque riportati e una nota indica il bundle e la versione che non è stato possibile leggere. Per un codice che questo binario non dichiara non resta nulla con cui rispondere, quindi il codice viene rifiutato — e il rifiuto dice che non è stato possibile leggere il riferimento, perché senza di esso un codice di una versione diversa non può essere distinto da un refuso, e lascia aperte entrambe le correzioni: correggere il codice o procurarsi la documentazione. La causa abituale è un workspace fissato offline, o uno che non ha mai raggiunto il suo registry. Dove la macchina contiene una copia che il controllo delle firme del tuo workspace non ammette — una scaricata da un altro progetto con un’impostazione più permissiva, o una che un workspace offline non può verificare perché questa macchina non ha mai scaricato la trust root pubblica rispetto a cui verifica il suo controllo — la nota dice che la copia è stata rifiutata anziché essere mancante, e perché. Dove per la tua versione non è pubblicato alcun bundle e il più recente tra i precedenti è in un formato che questa versione di aggrega non legge più — per esempio una release candidate eseguita prima che sia pubblicata la sua documentazione — la nota dice entrambe le cose in una sola frase:

hub.aggrega.ai/docs/aggrega-docs publishes no documentation bundle for 0.9.1-rc.1, and the newest earlier one, 0.8.11, is in a format this version of aggrega no longer reads, so the walk-through is not shown here; every condition, including the ones a provider declares, is published at aggrega-docs/language-reference/errors/sentinels.md, and the walk-through of each authoring fix at aggrega-docs/language-reference/errors/fatal-halts.md

Un numero ritirato. Un numero che indicava una condizione e non la indica più riceve risposta come ritirato, con ciò che indicava, anziché come un codice mai esistito — e non riceve mai come risposta una condizione diversa, perché un numero ritirato non viene riassegnato.

Esempi

Spiega un codice preso direttamente da una build non riuscita:

Terminal window
aggrega build --release release.yaml || aggrega explain E0209

Spiega un codice su cui un programma ha fatto corrispondenza:

Terminal window
aggrega explain plugin-value-not-representable

La stessa risposta da un assistente

Un assistente AI connesso tramite aggrega mcp raggiunge questa stessa espansione tramite lo strumento explain-error. Passagli il testo del diagnostico invece di un codice nudo — un assistente ha ciò che la build ha stampato — e dove quel testo si apre con un codice breve, la risposta contiene la condizione, la frase con cui si aprono i suoi diagnostici e la spiegazione pubblicata della correzione, composte allo stesso modo della risposta qui sopra. Contiene anche il codice descrittivo, così l’assistente può diramarsi su quello invece che sulla formulazione di un messaggio, e l’indirizzo a cui la condizione è pubblicata.

Tutto ciò che le sezioni precedenti dicono su una spiegazione mancante vale anche lì: una condizione per cui la pagina non documenta alcuna voce, e un workspace che non può leggere la documentazione, lasciano ciascuno la condizione con una risposta accompagnata da una nota che dice di quale caso si tratta. Anche lì un numero ritirato riceve risposta come ritirato, con ciò che indicava, così un assistente a cui viene passato un vecchio diagnostico apprende che il numero non è più in uso invece di essere mandato a una pagina che parla d’altro. La superficie dell’assistente ottiene la documentazione una volta all’apertura della sessione, quindi un’espansione legge ciò che è già in cache.

Il daemon risponde alla stessa domanda per un editor, a partire da un codice anziché da un diagnostico. Tutte e tre sono un’unica espansione in tre rese, non tre risposte che si trovano a coincidere.