aggrega explain
Explicar a condição de interrupção que um código nomeia
Sinopse
aggrega explain <code>Descrição
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.O que faz
Uma compilação que para imprime um cabeçalho entre parênteses retos que nomeia a categoria a que a falha é imputável e o código curto da condição — a letra E e quatro dígitos:
[CATALOG_ERROR E0209] Recipe: valuesMapping requires source ...aggrega explain E0209 transforma esse código na condição que nomeia e no percurso guiado da correção de autoria:
aggrega explain E0209A resposta começa com os dois identificadores da condição e a frase fixa com que os seus diagnósticos começam, e depois reproduz a entrada que explica o que causa a condição e o que alterar — a mesma entrada publicada em fatal-halts.md.
O código a passar
É aceite qualquer um dos dois códigos da condição, porque cada um deles chega ao utilizador numa superfície diferente.
O código curto é o que um terminal mostra, e é aquele a usar quando tudo o que se tem é a saída impressa. Um número é atribuído uma vez e depois fica fixo, pelo que um código curto colado num relatório há um ano continua a nomear a condição que nomeava então.
O código descritivo é o código com hífenes que um diagnóstico estruturado contém como campo próprio, e sobre o qual um programa toma decisões. Nomeia a condição por palavras e não tem prefixo, pelo que se mantém fixo mesmo quando o compilador é reorganizado à sua volta. Se for esse o que tem, passe-o em vez do outro — a condição acima está registada como recipe-values-mapping-requires-source:
aggrega explain recipe-values-mapping-requires-sourceOs dois códigos de uma condição nomeiam a mesma condição, pelo que ambas as grafias têm a mesma resposta. O código curto é comparado sem distinção entre maiúsculas e minúsculas, já que é um valor que se lê num ecrã e se volta a escrever.
sentinels.md explica os três identificadores que uma condição contém e quando usar cada um.
De onde vem a resposta
Cada condição que este binário declara é respondida a partir do binário. Os seus dois códigos e a frase com que os seus diagnósticos começam estão declarados dentro do compilador, pelo que isso não precisa de rede, de cache nem de configuração.
Um código que este binário não declara é procurado na referência publicada. Um plugin reporta uma interrupção escolhendo uma condição que o compilador declara, pelo que nenhuma condição é declarada em mais lado nenhum. A referência publicada, sentinels.md, lista todas as condições que o produto declara, e pode ter sido publicada para uma versão diferente da do binário que está a executar — pelo que um código citado de um relatório feito com uma versão mais recente ou mais antiga pode ainda ser resolvido aí.
O percurso guiado é também documentação publicada, lida a partir de fatal-halts.md. Ambas as páginas vêm do pacote de documentação, que é guardado uma vez por máquina na cache que todos os projetos Aggrega partilham, uma cópia por cada registo e versão — consulte aggrega cache. O pacote lido é o publicado para a versão de aggrega em execução; quando nenhum está publicado para essa versão, é o mais recente publicado para uma versão anterior — a mesma escolha que aggrega scaffold --example faz, pelo que os dois nunca leem documentação diferente. Um código que a referência de uma versão anterior não contém pode nomear uma condição declarada entretanto, pelo que é recusado como indeterminado e não como um código que não nomeia nada, e a recusa indica de que versão foi lida a referência. O espaço de trabalho decide de que registo vem o pacote, o seu registo predefinido, e se uma cópia já presente na máquina pode ser lida: antes de uma página ser servida, as assinaturas guardadas ao lado da cópia são verificadas novamente segundo a própria verificação de assinaturas do espaço de trabalho para esse registo, a mesma verificação a que uma obtenção do pacote está sujeita. Essa verificação também é executada offline. Quando fixa uma chave ou uma raiz de confiança, lê apenas essas; quando não fixa nenhuma, como faz a verificação incorporada do hub oficial, verifica contra a raiz de confiança pública do Sigstore, que um espaço de trabalho offline não consegue obter — pelo que, offline, verifica contra a raiz de confiança que uma obtenção online anterior nesta máquina deixou em .sigstore no diretório pessoal, e não obtém nada. Quando a máquina não tem nenhuma cópia, ou nenhuma que a verificação admita, o comando obtém uma segundo essa verificação, uma vez, e lê depois a partir da cache. A mesma cópia serve a documentação que um assistente lê através de aggrega mcp e as explicações que um editor mostra através de aggrega serve.
Há três respostas que vale a pena reconhecer, porque cada uma pede algo diferente ao utilizador.
Uma condição ainda sem entrada. Os códigos e a frase são reportados, e uma nota indica que a página de condições de paragem não contém nenhum percurso guiado para essa condição. Todas as condições continuam listadas em sentinels.md.
Nenhuma documentação disponível. Para uma condição que o compilador declara, os códigos e a frase continuam a ser reportados e uma nota nomeia o pacote e a versão que não puderam ser lidos. Para um código que este binário não declara não resta nada com que responder, pelo que o código é recusado — e a recusa indica que a referência não pôde ser lida, porque sem ela um código de outra versão não pode ser distinguido de um erro de escrita, e deixa abertas ambas as correções: corrigir o código ou obter a documentação. Um espaço de trabalho fixado como offline, ou um que nunca chegou ao seu registo, é a causa habitual. Quando a máquina contém uma cópia que a verificação de assinaturas do espaço de trabalho não admite — uma que outro projeto obteve com uma definição mais permissiva, ou uma que um espaço de trabalho offline não consegue verificar porque esta máquina nunca obteve a raiz de confiança pública contra a qual a sua verificação valida — a nota indica que a cópia foi recusada e não que está em falta, e porquê. Quando nenhum pacote está publicado para a sua versão e o mais recente anterior está num formato que esta versão de aggrega já não lê — uma versão candidata executada antes de a sua própria documentação ser publicada, por exemplo — a nota indica ambas as coisas numa só 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.mdUm número retirado. Um número que nomeava uma condição e já não o faz é respondido como retirado, com o que nomeava, e não como um código que nunca existiu — e nunca é respondido com uma condição diferente, porque um número retirado não volta a ser atribuído.
Exemplos
Explicar um código vindo diretamente de uma compilação falhada:
aggrega build --release release.yaml || aggrega explain E0209Explicar um código sobre o qual um programa fez correspondência:
aggrega explain plugin-value-not-representableA mesma resposta a partir de um assistente
Um assistente de IA ligado através de aggrega mcp chega a esta mesma expansão através da ferramenta explain-error. Entregue-lhe o texto do diagnóstico em vez de um código isolado — um assistente tem o que a compilação imprimiu — e, quando esse texto começa com um código curto, a resposta contém a condição, a frase com que os seus diagnósticos começam e o percurso guiado publicado da correção de autoria, compostos da mesma forma que a resposta acima. Contém também o código descritivo, para que o assistente possa tomar decisões com base nele e não na redação de uma mensagem, e o endereço em que a condição está publicada.
Tudo o que as secções acima dizem sobre um percurso guiado em falta aplica-se também aí: uma condição para a qual a página não documenta nenhuma entrada, e um espaço de trabalho que não consegue ler a documentação, deixam ambos a condição respondida com uma nota que indica qual dos casos foi. Um número retirado é também aí respondido como retirado, com o que nomeava, para que um assistente a quem é entregue um diagnóstico antigo saiba que o número já não está em uso em vez de ser enviado para uma página sobre outra coisa. A superfície do assistente obtém a documentação uma vez quando a sessão abre, pelo que uma expansão lê o que já está em cache.
O daemon responde à mesma pergunta para um editor, a partir de um código e não de um diagnóstico. Os três são uma única expansão em três apresentações e não três respostas que por acaso coincidem.