Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

Disciplina de tradução de erros

O pipeline de compilação da Aggrega emite erros a partir de muitas superfícies — validadores de esquema, o resolvedor, o construtor do IR, os fornecedores, o motor de templates Go e as bibliotecas YAML / Helm / docker-compose subjacentes que os fornecedores envolvem. Os erros que chegam à CLI começam com um cabeçalho entre parênteses retos que indica até duas coisas — uma categoria, que diz que preocupação analisar (para a maioria dos valores, a superfície de autoria em causa), e o código curto da condição que interrompeu a compilação — seguido de um ponteiro de origem e de uma mensagem. Quando foi um plugin a levantar a condição, o código é qualificado pelo plugin que a levantou, porque mais do que um plugin pode comunicar a mesma condição. Esta página documenta a forma dessa saída para que os autores interpretem diretamente as mensagens de erro.

Para o catálogo por erro (todas as interrupções fatais com orientações sobre como corrigir), consulte fatal-halts.md. Para as quatro camadas de validação de esquema e a forma como as suas formas de erro interagem, consulte vocabulary/validation-surface.md.

As categorias de erro

Uma etiqueta de categoria diz que preocupação analisar. A maioria indica a superfície de autoria onde está a correção; as restantes indicam uma preocupação que não é um erro de autoria de ninguém — a obtenção de um artefacto, um veredicto de governação, ou confiança e assinatura — e o código curto do cabeçalho, ao lado da categoria, é o que identifica a condição específica em todos os casos:

  • [DEVELOPER_ERROR] — a falha diz respeito à autoria do Aggregate. A correção está no YAML do Aggregate ou na parte do catálogo escrita pelo programador (values do Component, sockets uses, anexos de Feature). Superfícies de exemplo: interrupções do resolvedor por problemas do lado do Aggregate; violações de seletores e de appliesTo naquilo que o Aggregate escreveu.
  • [OPS_ERROR] — a falha diz respeito aos documentos próprios do operador, a Release e o Manifest. A correção está no YAML da Release (topologia de fronteiras, valores de parâmetros, anexos de Feature ao nível da Release) ou no YAML do Manifest (através de que Recipe um tipo é implementado, e as associações de anotações escritas ao lado). Superfícies de exemplo: validação do esquema da Release; avaliação de templates de caminhos de fronteira; colisões de subDirectory entre providers; recusas de mapeamentos e de associações de anotações do Manifest; uma regra que recusa uma ligação que a Release faz, ou um anexo que ela preenche numa ligação — o seletor de um socket, o seletor de um slot, um slot que um socket declara obrigatório; uma regra que recusa uma Feature que só a Release anexa, a um componente ou a uma fronteira — o appliesTo da Feature, o seletor de um slot, o seu esquema declarado.
  • [CATALOG_ERROR] — a falha diz respeito a uma entidade de catálogo (Recipe, FeatureRecipe, Component, Feature, Plugin). A correção está no conteúdo do catálogo. Superfícies de exemplo: regras de forma das Recipes; verificações cruzadas do featuresSchema do Workload; erros de análise de templates em templates escritos no catálogo.
  • [TRANSLATION_ERROR] — a falha diz respeito à síntese do lado do fornecedor (um plugin de fornecedor a tentar traduzir um Workload, a saída de um valuesMapping ou uma sobreposição com source em artefactos nativos do fornecedor). A correção está normalmente na forma services / containers / volumes do Workload, na saída do template valuesMapping da Recipe ou na estrutura da sobreposição em modo com source.
  • [FETCH_ERROR] — a falha diz respeito à obtenção de uma dependência fixada a partir de um registo ou de uma origem remota, e não a nenhuma superfície de autoria. A correção é normalmente operacional: autenticar-se no registo (docker login <registry>), restaurar a conectividade ou voltar a fixar um artefacto que divergiu ou foi adulterado (aggrega pull --upgrade --release <release>). Superfícies de exemplo: uma entidade de catálogo ou chart não encontrado no registo; autenticação necessária ou falhada; rede inacessível; o digest de um artefacto em cache que não corresponde ao lockfile. Os erros de obtenção contêm na mensagem uma indicação concreta de correção.
  • [POLICY_ERROR] — a compilação foi rejeitada por um plugin de políticas anexado num papel de veredicto de governação. Não é uma falha de superfície de autoria: a entrada está bem formada, mas falha uma regra de governação (conformidade, FinOps ou segurança) que o plugin impõe. A correção é pôr aquilo que escreveu em conformidade com a política imposta, ou reconsiderar o anexo da política. A mensagem indica o plugin que rejeitou e contém a mensagem da regra que ele forneceu.
  • [TRUST_ERROR] — a camada de confiança e assinatura recusou a operação. Esta categoria indica uma preocupação e não uma superfície de autoria, e abrange duas soluções que se distinguem pelo código curto ao lado. A configuração de confiança está errada: uma política de confiança que não pode ser lida, uma raiz de confiança fixada que não pode ser carregada, uma política keyless que não declara nenhuma identidade de confiança, uma política de assinatura que exige uma assinatura para o tipo de artefacto a publicar, ou um plugin registado como de confiança para um anexo de veredicto que a configuração já não anexa. Este artefacto falhou a verificação: uma assinatura que não é verificada contra a âncora de confiança, um artefacto sem assinatura onde é exigida uma, uma assinatura de um signatário real mas não de confiança, ou um plugin cuja identidade de confiança registada já não corresponde ao que é resolvido. A correção, no primeiro caso, está na configuração ou no registo de confiança com commit; no segundo, é uma decisão sobre o artefacto — restaurar o que foi revisto, ou rever e voltar a registar o que mudou.

Uma constatação sobre um anexo de Feature segue o documento que o escreveu

Uma Feature pode ser anexada em qualquer dos documentos — o Aggregate anexa-a num componente ou num subsistema, a Release na sua entrada para um componente ou numa fronteira — pelo que a categoria de uma constatação sobre um anexo é lida a partir do local onde o anexo foi escrito, e não do componente a que chega. A constatação é posicionada na entrada features: que escreveu o anexo, nesse documento, e é atribuída ao autor desse documento: um anexo que só a Release cria é reportado no caminho da própria Release como [OPS_ERROR], e um que o Aggregate cria no caminho do Aggregate como [DEVELOPER_ERROR].

[OPS_ERROR E0007] release.yaml at .spec.boundaries.main.components.app.features.metrics
selector violation ("component.aggrega.ai/type in (server, worker)", declared by Feature "core/prometheus-exporter", not satisfied by the labels of "app"). Add the labels the Feature's appliesTo requires to this component's type, or attach a Feature whose applicability the component already satisfies.

Quando ambos os documentos escrevem um anexo — o Aggregate a indicar a sua Feature, a Release a dimensioná-lo — uma constatação sobre o anexo como um todo é posicionada onde a sua Feature é indicada, que é o Aggregate. Uma constatação sobre uma parte da sua configuração é posicionada onde essa parte foi escrita: os seus values são do programador, no Aggregate, e o seu infra do operador, na Release. Um anexo produzido pela expansão orientada por anotações não foi escrito por nenhuma entrada features:, pelo que uma constatação sobre ele é posicionada no componente, no documento que declara o componente, como [DEVELOPER_ERROR].

Um slot obrigatório deixado vazio é o único caso que nenhum documento escreveu. Não há nenhum anexo para onde apontar, pelo que a constatação fica no componente no Aggregate e é registada como [DEVELOPER_ERROR], e a sua solução indica ambos os documentos, porque qualquer um deles pode preencher o slot: «Anexe uma Feature com esse nome, no Aggregate ou na Release, no componente ou num âmbito acima dele.»

O editor lê a mesma colocação: uma constatação posicionada na Release é mostrada no documento da Release, na chave que a escreveu, e não aparece de todo no do Aggregate; uma constatação posicionada no documento de um módulo que o Aggregate importa é mostrada da mesma forma no documento desse módulo.

Forma da saída

Um diagnóstico impresso começa com o cabeçalho entre parênteses retos e o ponteiro de origem, e coloca a mensagem numa linha indentada própria:

[CATEGORY SHORTCODE] <source>
<message>

O cabeçalho contém dois tokens, e eles respondem a perguntas diferentes. A categoria é uma das acima e diz que preocupação analisar. O código curto é a letra E seguida de quatro dígitos, e indica a condição exata que interrompeu a compilação: cite-o num relatório, escreva-o numa pesquisa ou resolva-o na tabela de todas as condições em sentinels.md. Nenhum é derivável do outro, e é por isso que ambos são impressos — e, quando uma categoria abrange mais do que uma solução, como acontece com [TRUST_ERROR], é o código curto que indica qual delas se aplica.

Um código levantado por um plugin é qualificado pelo plugin que o levantou

Cada código curto designa uma condição que a Aggrega declara, e duas condições nunca partilham um: uma condição declarada sob um número que outra condição já detém é recusada antes de o compilador ler qualquer entrada. Um plugin não atribui códigos próprios. Quando reporta uma falha, designa uma das condições que a Aggrega declara — uma das poucas condições gerais que descrevem a forma como um plugin falhou, ou uma mais específica quando houver uma adequada — e fornece a frase que diz o que realmente aconteceu. Assim, dois plugins podem reportar o mesmo código curto e, quando o fazem, estão a reportar a mesma condição.

O que o código não consegue dizer é qual o plugin que encontrou a condição, e um cabeçalho que reporte uma condição levantada por um plugin contém a identidade do plugin imediatamente antes do código:

[CATEGORY PLUGIN/SHORTCODE] <source>
<message>

O código curto é sempre o segmento final — a letra E e quatro dígitos, depois da última /. A identidade de um plugin contém separadores próprios e pode conter uma versão, pelo que ler a partir do fim, e não a partir da primeira /, é o que torna o código recuperável a partir de qualquer cabeçalho. Tudo o que está antes desse segmento final é o plugin.

O segmento final resolve-se como qualquer outro código curto, seja qual for o plugin que o levantou: a tabela de todas as condições em sentinels.md lista-o, e aggrega explain resolve-o. Cite apenas o segmento final — o qualificador diz qual o plugin que encontrou a condição, não qual é a condição. Um plugin que indique um código que a Aggrega não declara — um número que nenhuma condição detém, ou um código retirado — não vê esse código impresso: a compilação para em E0293, qualificado por esse plugin, e a sua mensagem cita o código que o plugin ofereceu, indica essas condições gerais e mantém a frase do próprio plugin.

Um cabeçalho que imprima um código curto simples está a reportar uma condição levantada pela própria Aggrega, o que inclui o caso em que um plugin falhou sem indicar nenhuma condição própria. Nesse caso, foi a condição genérica de falha de plugin do compilador que interrompeu a compilação, e a mensagem do plugin contém o detalhe.

Qualquer dos tokens pode estar ausente, e um token ausente é omitido

Nada substitui um token que o diagnóstico não tem — nenhum marcador, nenhuns parênteses retos vazios. Há três formas de um cabeçalho ser mais curto, e cada uma diz alguma coisa:

  • Sem código curto. A falha não indica nenhuma condição própria da Aggrega — na maioria dos casos, uma falha reportada por uma biblioteca que o compilador envolve. O cabeçalho imprime apenas a categoria, pelo que continua a saber-se que superfície analisar.
  • Sem categoria. A falha não tem nenhuma preocupação para onde encaminhar, pelo que nenhuma é adivinhada. O cabeçalho imprime apenas o código curto, e é o código que se resolve. Há duas situações que o produzem, e leem-se da mesma forma porque, para o efeito pretendido, são iguais — nenhuma diz onde procurar, e o código diz o que aconteceu. Uma é uma falha no próprio compilador, em que a mensagem o diz e pede que seja reportada; o caso que surge é o de as próprias visões do catálogo do compilador divergirem entre si. A outra é uma falha que indica uma condição mas nunca passou por uma superfície que a atribua a uma preocupação, que é a forma habitual de uma recusa levantada na fronteira do comando. Nunca se inventa uma categoria para preencher a lacuna, e é esse o objetivo da omissão, e não uma limitação dela: a categoria responde a «que preocupação analiso», e uma resposta dada onde a pergunta não tem nenhuma não é uma resposta prudente, mas sim errada, e é a primeira a ser seguida. Vale também a pena dizer que a inferência inversa não se verifica: um cabeçalho que contém uma categoria nem sempre aponta para algo que foi escrito pelo utilizador, porque [FETCH_ERROR], [POLICY_ERROR] e [TRUST_ERROR] indicam cada uma uma preocupação e não uma superfície de autoria.
  • Nenhum dos dois. Os parênteses retos são totalmente omitidos e o diagnóstico é a sua mensagem. Trata-se de uma falha que não indica nenhuma condição própria da Aggrega e não tem nenhuma preocupação para onde encaminhar: um comando que recusa os seus argumentos, um ficheiro que não consegue ler, um cancelamento, ou uma falha reportada por uma biblioteca que o compilador envolve sem nenhuma condição nossa por baixo. Não há nada a resolver em sentinels.md, e a mensagem é tudo o que a falha tem a dizer.

O mesmo erro reduzido a uma linha, a forma adequada para saída de logs e não para um terminal, contém a categoria e descarta o código curto:

[CATEGORY] <source>: <message>

Uma categoria ausente do cabeçalho também está ausente aqui, incluindo os parênteses retos, pelo que esta linha nunca é [] <source>: <message>. A forma de uma linha é novamente envolvida em frames envolventes à medida que a falha sobe, pelo que uma etiqueta vazia seria transportada para cada um deles.

A origem é um ponteiro estruturado — normalmente <file>:<line>:<column> quando está disponível uma posição YAML, ou um identificador lógico (o nome da entidade de catálogo, o nome da Release, o caminho da fronteira) quando não se aplica nenhuma posição de ficheiro. Uma terceira forma, <file> at <key>, aparece quando o ponteiro conhece tanto o documento como a chave de autoria dentro dele, mas nenhuma posição de byte: o ficheiro é o que se abre, e a chave é o que se procura depois de aberto. A mensagem é o diagnóstico de cada superfície.

Uma falha relativa a uma instância da compilação — um componente, um componente fornecido por um módulo ou o próprio módulo — indica essa instância depois da posição, como (instance <name>), pelo que aggregate.yaml (instance shop) é o Aggregate que declara o módulo shop. Quando a falha não tem nenhum documento para onde apontar, a instância surge sozinha como instance <name>: um fornecedor que falha ao renderizar o componente adminer imprime [TRANSLATION_ERROR E0082] instance adminer, e as linhas abaixo trazem o resto da falha, incluindo qualquer documento que indique. O nome é aquele sob o qual o Aggregate declara o componente; um componente fornecido por um módulo é nomeado pelo seu caminho através do módulo, como shop.cart. Uma instância nunca é impressa onde deveria estar um ficheiro, pelo que aquilo com que a origem começa é sempre um documento que se pode abrir, ou um dos identificadores lógicos acima.

Uma regra avaliada sobre o grafo concluído reporta nessa terceira forma, e a chave é o que distingue duas constatações quando a mensagem, por si só, não consegue. Uma regra deste tipo indica o tipo de componente que declara, e não a instância, pelo que dois componentes de um tipo que falham a mesma regra têm a mesma mensagem sobre o mesmo ficheiro:

[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.checkout
missing required feature: attach a Feature of the required type to the component ("core/observability/monitoring", required by component type "core/compute/api-server", under the requirement label "monitoring")
---
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.inventory
missing required feature: attach a Feature of the required type to the component ("core/observability/monitoring", required by component type "core/compute/api-server", under the requirement label "monitoring")

A chave é a única parte que difere, e é o que indica qual dos dois componentes editar. Ambas as constatações têm o mesmo código curto porque ambas são a mesma condição, encontrada duas vezes — o código curto indica a regra, e a chave indica a ocorrência.

Há mais duas linhas que fazem parte da forma, para uma falha que tenha o contexto para as preencher — a expressão de template que falhou e um instantâneo dos pilares no âmbito onde falhou:

[CATEGORY SHORTCODE] <source>
<message>
expression: <the template excerpt that triggered the failure>
active pillars:
<one line per top-level pillar key in scope at the point of failure>

A linha expression: contém o excerto de template que desencadeou a falha. O bloco active pillars: lista as chaves de pilares de nível superior disponíveis no ponto da falha, para que os autores vejam o que era consultável. Ambos são omitidos quando a falha não contém nenhum deles.

Frames de contexto aninhados

Um erro atravessa muitas vezes mais do que uma superfície até chegar à CLI: uma fase de carregamento envolve a falha da entidade específica, que por sua vez envolve um sentinel que explica a regra. Todos os frames com categoria de uma cadeia destas são apresentados — o mais exterior como cabeçalho na forma acima, cada frame aninhado como uma continuação indentada caused by: com a sua própria etiqueta de categoria, ponteiro de origem e mensagem. O frame mais interior com ponteiro para ficheiro está sempre visível:

[CATALOG_ERROR E0094] aggrega-catalog
catalog load
caused by: [CATALOG_ERROR] aggrega-catalog/recipe/compose/mariadb-copy/1.0.0/recipe.yaml
duplicate entity identity within a single catalog directory (recipe identity "compose/mariadb:1.0.0")

Só o cabeçalho contém um código curto, e as continuações contêm apenas a sua categoria. A condição é indicada uma vez, no ponto em que o leitor encontra a falha; os frames abaixo de um marcador caused by: são essa mesma falha vista mais de dentro, pelo que repetir o seu identificador em cada um acrescentaria linhas sem acrescentar factos. Um bloco note: não é uma continuação e não segue esta regra — reporta condições de outros documentos e não a mesma vista mais de dentro; a secção abaixo trata disso. O código que o cabeçalho imprime é o que a cadeia indica — aqui, a regra no fundo — pelo que um frame de contexto de fase no topo continua a identificar a condição por baixo dele.

Lendo de cima para baixo: a fase que falhou, depois a entidade (com o caminho do ficheiro) que a causou, depois a regra que violou. Um frame aninhado que não acrescenta nada para além do seu pai (mesma categoria, mesma origem, uma mensagem que o pai já contém) é eliminado por duplicação em vez de ser repetido, e uma explicação terminal só é apresentada quando os frames acima ainda não contêm o seu texto.

Uma cadeia é mais profunda sempre que uma falha atravessa mais superfícies ao sair, e a regra mantém-se a qualquer profundidade. Um template recusado dentro do Workload sintetizado de uma Recipe atravessa três — o nó a ser renderizado, a superfície de templates da Recipe e o próprio template:

[CATALOG_ERROR E0060] instance db
rendering node "db"
caused by: [CATALOG_ERROR]
recipe "mariadb" workload template
caused by: [CATALOG_ERROR] workload[mariadb]
template references a root the render context does not define (template "workload[mariadb]" references ".nosuchroot.database", the render context defines .context, .values, .infra, .locals, .provides, .features, .metadata, .attachment_name, .inject, .inject_raw, .steps, .source, .workload, .boundary)

Leia-a de cima para baixo como antes, e repare em três coisas que a profundidade extra torna visíveis. O código curto aparece uma vez, no cabeçalho, independentemente de quantas continuações se lhe seguem. O frame mais interior é onde está a frase da própria condição, pelo que a linha mais profunda é tanto aquela com que fazer correspondência como aquela que diz o que mudar. E um frame sem ponteiro de origem imprime apenas a sua categoria: o frame do meio acima indica, na sua mensagem, a superfície em que falhou, porque essa superfície é um template e não um ficheiro e não tem nenhuma posição para onde apontar.

Quando a falha se ramifica abaixo de um frame — uma fase que recolheu várias violações independentes antes de interromper — a continuação contém uma contagem, e todas as falhas recolhidas são apresentadas abaixo dela, separadas pela mesma linha --- que as cadeias de vários erros abaixo usam:

[OPS_ERROR E0099]
recipe resolution
caused by (2):
[OPS_ERROR] .spec.components.edge
no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.edge, "edge", of type "example/gateway/nginx-reviewed"). no recipe in the catalog implements this type; write one, then map the type to it
---
[OPS_ERROR] .spec.components.internal
no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.internal, "internal", of type "example/gateway/nginx-reviewed"). no recipe in the catalog implements this type; write one, then map the type to it

As falhas recolhidas abaixo da contagem também são continuações, pelo que nenhuma delas repete o código curto do cabeçalho — é isso que impede que uma ramificação de uma dúzia de violações imprima o mesmo identificador uma dúzia de vezes.

Aplica-se uma única gramática de separadores: --- entre falhas irmãs, caused by: entre frames de contexto aninhados.

Um ficheiro de catálogo recusado e a falha que ele explica

O carregamento de um catálogo para resolver aquilo de que uma Release depende é tolerante de propósito: um ficheiro que não pode ser lido, ou um documento Aggrega que não pode ser analisado ou indexado, é recusado e registado, em vez de abortar todo o carregamento. É isso que impede que uma entidade defeituosa em que a Release nunca toca faça falhar uma compilação não relacionada.

A consequência é que um ficheiro recusado desaparece silenciosamente do catálogo — e, se a Release chegar a ele, o que falha é a tentativa de resolver uma referência ao que esse ficheiro declarava. Essa falha é uma consequência da recusa e não a própria recusa, pelo que o relatório coloca as duas por ordem causal sempre que consegue indicar a recusa com exatidão:

[CATALOG_ERROR E0215] catalog/recipes/helm/server.yaml
document envelope validation failed (Recipe, at catalog/recipes/helm/server.yaml); 6:1: spec.implements: missing required property: implements. correct the document to match its kind's schema
note: this file was skipped at load, so the catalog holds nothing under the identity it declares.
This Release reaches that identity, so what failed is the attempt to resolve the reference to it:
resolve entity "server-recipe:1.0.0": catalog: tier-3 pull server-recipe:1.0.0: recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI location: "server-recipe"

A recusa vem primeiro, com a sua própria categoria e o seu próprio código curto, porque indica aquilo sobre que se pode agir: a correção é um implements: em falta numa Recipe, e não algo relacionado com a forma como uma referência é procurada num registo. A falha de resolução continua a ser reportada, abaixo dela, porque é o que diz por que razão esse documento era necessário.

Uma recusa só vem primeiro quando exatamente um ficheiro recusado declara a identidade que a referência que falhou indica. A correspondência é feita com a identidade que cada documento declara para si próprio — o seu kind, o seu nome, a sua versão e, para uma recipe, o spec.capability que a delimita — pelo que um ficheiro recusado que declare o que a referência pede é o ficheiro para o qual essa referência teria sido resolvida. Daí decorrem duas consequências. Uma referência que indique um intervalo de versões em vez de uma versão não indica nenhum documento único, pelo que não destaca nada. E um documento demasiado mal formado para que o seu cabeçalho seja lido não declara nenhuma identidade, pelo que nunca é indicado como causa de nada.

Quando nenhum ficheiro recusado declara essa identidade, ou mais do que um a declara, o relatório é o que seria sem nenhum registo de recusa: a falha vem primeiro, e todas as recusas são listadas abaixo dela para avaliação. Indicar o ficheiro errado como causa seria pior do que não indicar nenhum, porque se agiria com base nisso.

[E0105]
resolve entity "server-recipe:1.0.0": catalog: tier-3 pull server-recipe:1.0.0: recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI location: "server-recipe"
note: catalog files skipped at load. A refusal outside this Release's closure is tolerated and never fails a build,
so this failure is explained only by a refusal naming something this Release reaches:
- Recipe "server-recipe" (catalog/recipes/helm/server.yaml): [CATALOG_ERROR E0215] catalog/recipes/helm/server.yaml: document envelope validation failed (Recipe, at catalog/recipes/helm/server.yaml); 6:1: spec.implements: missing required property: implements. correct the document to match its kind's schema

Vale a pena conhecer alguns aspetos dessa segunda forma, porque cada um responde a uma pergunta que o bloco, de outra forma, suscitaria.

O cabeçalho indica a falha, não uma recusa. O código curto no topo é o que a falha de resolução levantou, porque é essa falha que vem primeiro aqui — nenhum ficheiro recusado foi destacado, pelo que nenhum deles encabeça a linha. Não tem nenhuma categoria ao lado porque nada neste percurso atribuiu a falha a uma preocupação. O cabeçalho próprio de cada recusa está na sua entrada abaixo, que é onde se lê.

Todas as recusas são listadas, não apenas a que importou. Chegar a esta forma significa que o registo não conseguiu destacar uma, pelo que a nota indica a distinção em vez de adivinhar: uma recusa fora do fecho desta Release é tolerada e não pode ser o que falhou, o que deixa uma recusa que indique algo a que a Release chega como a única entrada que a explica. Leia as entradas tendo em conta o que a Release efetivamente usa.

Cada entrada contém o seu próprio cabeçalho entre parênteses retos — a sua própria categoria e o seu próprio código curto. Este é o único local em que um código curto aparece abaixo do cabeçalho do diagnóstico, e não é uma exceção à regra das continuações acima, mas sim uma consequência dela: uma entrada sob note: não é a mesma falha vista mais de dentro, é uma condição diferente levantada por um documento diferente. Indicar a sua condição é o que permite procurar a recusa e corrigir o ficheiro, que é a ação que o bloco existe para permitir.

Um ficheiro recusado cujo cabeçalho estava demasiado malformado para recuperar a identidade que declara é listado apenas pelo caminho. Essa é a leitura honesta de um documento que nada conseguiu espreitar, e o caminho continua a bastar para abrir o ficheiro. Um ficheiro demasiado malformado até para que o seu tipo seja lido — um que não é analisado como YAML, por exemplo — é listado desta forma quando declara uma apiVersion da Aggrega, através de uma linha que começa, sem indentação, por apiVersion: e um valor que começa por aggrega.ai/, com o motivo dado pelo próprio analisador: a linha, e o que o analisador esperava ali. Um ficheiro YAML que declare outra apiVersion, ou nenhuma, não é um documento Aggrega — o template de um chart, por exemplo, ou um ficheiro de configuração guardado ao lado das entidades —, pelo que nunca é listado, por mais malformado que esteja.

Um ficheiro que declara um tipo que nenhum catálogo contém só é indicado onde explica a falha. Um documento que declara uma apiVersion da Aggrega e um kind que nenhum catálogo contém — um Componnent mal escrito, por exemplo — é ignorado por todos os carregamentos, pelo que não é uma recusa e não é listado entre elas. Quando a referência que falha pede o nome que esse ficheiro declara, e a versão quando a referência indica uma, o relatório indica-o numa nota própria abaixo da falha, seja qual for o tipo com que a referência foi recolhida — em cada superfície listada abaixo, e em aggrega build, quer leia um lockfile existente, quer preencha primeiro um:

[E0114]
resolve: no entity in the catalog matches this URI: entity "<reference>" (referenced from <referring paths>)
note: a catalog file declares the name this reference asks for under a kind a catalog does not hold,
so the load skipped it:
- Componnent "<name>" (<path>): [CATALOG_ERROR E0371] <path>: catalog document declares a kind a catalog does not hold (kind "Componnent"). a catalog holds Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary, Aggregate and Plugin documents, and passes over a Workload, a Manifest or a Release; correct the kind, or move the file out of the catalog directories

A falha continua a vir primeiro: o tipo que o ficheiro declara não designa nenhuma identidade, pelo que o ficheiro nunca é destacado como a recusa com que o relatório começa. A explicação de onde as entidades locais são lidas fica de fora desse relatório, porque o ficheiro já está onde o catálogo lê e movê-lo não ajudaria. Um ficheiro de um tipo que nenhum catálogo contém e que declara outro nome não explica nada sobre esta falha e não é mencionado. aggrega serve, cujas mensagens ocupam uma linha, contém a mesma nota nessa linha — note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it: seguida da recusa do ficheiro — e nunca lista um ficheiro desses entre os ficheiros ignorados no carregamento; a ferramenta describe de aggrega mcp, quando consultada sobre um nome nos termos de uma Release, também o indica em vez dessa explicação. aggrega validate e aggrega lint sobre o catálogo inteiro reportam cada um desses ficheiros, quer algo o alcance, quer não — consulte fatal-halts.md §«A catalog document declares a kind a catalog does not hold (Um documento de catálogo declara um tipo que um catálogo não contém)».

Seja qual for a forma obtida, a falha mantém a sua própria identidade. A nota é acrescentada à falha em vez de ser apresentada por cima dela, e começar por uma recusa altera apenas o que se lê primeiro — pelo que a condição que a falha levantou permanece intacta em qualquer dos casos: o seu código curto continua a ser resolvido, e uma ferramenta que faça correspondência com a condição continua a fazê-la.

Quando o documento recusado é ele próprio o que um comando reporta, a recusa é indicada uma vez. aggrega inspect <name> carrega o catálogo de forma estrita, pelo que um documento que o carregamento recusa para-o, e o que imprime é a recusa desse documento como um único diagnóstico: o cabeçalho com a categoria e o código curto da recusa, o documento como origem e, abaixo, o que está errado no documento — para uma violação de esquema, as chaves violadas com as suas linhas e colunas, e o conselho. O carregamento que a levantou passou pelo diretório que estava a percorrer e pelo passo que leu o ficheiro, e estes não são impressos como frames próprios, porque cada um voltaria a indicar o mesmo documento sem acrescentar nenhum facto. aggrega serve, quando lhe perguntam a que se refere um nome que um documento recusado declara, responde com a mesma recusa, nas mesmas palavras, numa linha, seguida da nota de que o ficheiro foi ignorado no carregamento. Tal como acima, a condição da recusa continua a permitir correspondência em qualquer dos casos.

Ambas as formas chegam onde quer que essa resolução seja executada. aggrega build, aggrega pull, aggrega validate --release e aggrega inspect --closure produzem-nas num terminal, tal como aggrega validate sobre uma Recipe cujo destino implements não é encontrado, e um assistente de IA ligado através de aggrega mcp recebe o mesmo relato das ferramentas build e validate, e a recusa que vem primeiro, numa única linha, de uma leitura catalog:// de uma entidade que um ficheiro recusado declara. A superfície a que se pergunta não altera em nada o ficheiro que se é enviado a abrir — um chamador que alcance aggrega mcp por HTTP recebe-o relativamente à raiz do workspace, e não lhe é indicado um fora do workspace que esse servidor serve — e, quando uma recusa vem primeiro, o contrato de autoria para que a resposta aponta é o do kind que esse documento recusado declara — e não o kind da referência que falhou.

A classe de falhas do envelope do documento

Todos os documentos de entidade — entidades do catálogo, Aggregates, Manifests, Releases — são validados face ao esquema JSON publicado do seu tipo quando são carregados, antes da análise tipada. Um documento que viola o seu envelope (uma chave desconhecida, um campo obrigatório em falta, um valor com a forma errada, uma construção proibida como values: numa Release) interrompe a compilação de forma explícita com um diagnóstico que nomeia primeiro a condição, depois o tipo de entidade e o ficheiro, depois cada chave ou forma infratora com a linha e a coluna em que se encontra e, por fim, o que fazer:

[OPS_ERROR E0215] release.yaml
document envelope validation failed (Release, at release.yaml); 12:7: spec.boundaries.main.values: against /$defs/boundary: unexpected property: "values". correct the document to match its kind's schema

O diagnóstico começa pela condição, nomeia o tipo e o ficheiro e termina com o que fazer; cada violação entre eles indica apenas line:column, uma vez que o cabeçalho já nomeou o ficheiro. Cada chave infratora é comunicada na sua própria posição, e não na posição do bloco que a contém, para que a linha e a coluna apontem para a chave que é preciso alterar. Quando a forma da posição provém de uma definição reutilizável do esquema, o diagnóstico nomeia essa definição a seguir à palavra against — against /$defs/boundary acima — para que fique claro face a que contrato a chave foi medida e para que a definição não se leia como mais um passo ao longo do caminho de chaves escrito. Um documento com várias violações enumera cada uma na sua própria posição, por ordem de chave, e o relatório termina após quatro com a contagem das restantes.

Vale a pena saber duas coisas sobre o local para onde uma posição aponta, porque ambas são úteis em vez de surpreendentes:

  • Uma chave obrigatória em falta não tem posição própria — por definição, está ausente do documento. A violação aponta, em vez disso, para a chave que a envolve, que é onde a entrada em falta deve ficar. Assim, spec.capability: missing required property aponta para spec:, e é aí que se acrescenta.
  • Uma chave cujo próprio nome contém um ponto — cada etiqueta component.aggrega.ai/… e cada anotação features.aggrega.ai/… — é comunicada no bloco que a contém, e não na própria entrada, uma vez que os pontos se leem como passos para dentro do documento. Uma violação numa etiqueta aponta para labels:.

Quando uma violação nomeia uma chave que não existe em parte alguma do documento — um bloco metadata: inteiro omitido, por exemplo — a posição é omitida em vez de adivinhada, e a violação lê-se apenas como o caminho da chave e a mensagem. Uma posição de que se teria de desconfiar é pior do que nenhuma.

A categoria segue a superfície de autoria: [CATALOG_ERROR] para entidades do catálogo, [DEVELOPER_ERROR] para Aggregates, [OPS_ERROR] para Releases e Manifests. A mesma verificação é executada em todas as superfícies que carregam entidades — aggrega build, aggrega lint, aggrega validate e os diagnósticos do editor que aggrega serve publica — pelo que uma chave a mais ou mal escrita é rejeitada onde quer que o documento seja lido pela primeira vez, em vez de ser descartada silenciosamente. Cada uma destas superfícies resolve a posição da mesma forma, pelo que apontam para a mesma chave, e cada uma lê a frase da condição a partir da própria condição: a linha que o editor sublinha é a linha que o terminal nomeia, e a frase com que abre a entrada do editor é a frase com que abre o terminal. O que as duas superfícies não partilham é a mensagem completa, e isso é deliberado — o terminal agrupa todas as constatações sob um único cabeçalho e termina com a recomendação para o caminho, enquanto o editor emite uma entrada por constatação, posicionada na sua própria chave, sem repetir nem o ficheiro ao qual já está associada nem uma recomendação que, de outro modo, repetiria em cada sublinhado. Assim, a parte que converge é aquela pela qual se reconhece a condição.

Cadeias de múltiplos erros

Quando uma única compilação deteta várias violações independentes (mais frequentemente durante a análise estática, em que todas as violações de seletor e de appliesTo são recolhidas antes de qualquer uma interromper a compilação), os erros são unidos numa única cadeia. A CLI percorre a cadeia e apresenta cada suberro de forma independente, separados por uma linha horizontal:

[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge.uses.reviewed_upstream.internal
selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.
---
[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge2.uses.reviewed_upstream.internal
selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.

O separador --- é literal — os leitores e as ferramentas a jusante podem dividir por ele para enumerar os erros unidos. Cada suberro é uma falha por direito próprio e não um pormenor do seu vizinho, pelo que cada um tem um cabeçalho próprio: a sua própria categoria e o seu próprio código curto, cada um onde existir, como descreve a secção sobre tokens ausentes. Duas violações da mesma regra nomeiam o mesmo código curto, como acima; duas violações de regras diferentes nomeiam códigos diferentes.

Ler um erro do princípio ao fim

Na maioria dos contextos de autoria, o prefixo de categoria e o ponteiro para a origem identificam em conjunto o que corrigir:

CategoriaOnde está a correçãoSuperfícies de exemplo
[DEVELOPER_ERROR]YAML do AggregateViolações de seletor / appliesTo no que o Aggregate escreveu; incompatibilidade do socket uses do lado do Aggregate; interrupções do resolvedor na autoria do programador.
[OPS_ERROR]YAML da Release / YAML do ManifestO modelo de caminho da fronteira referencia um campo não suportado; subDirectory provoca uma colisão de caminhos; interrupções do resolvedor na autoria da Release; uma ligação que a Release estabelece, ou um anexo que preenche numa ligação, recusados pelas regras do socket ou do slot; uma Feature que apenas a Release anexa, a um componente ou a uma fronteira, recusada pelas regras da Feature ou do slot; um mapeamento ou uma associação de anotação de um Manifest é recusado.
[CATALOG_ERROR]Recipe / FeatureRecipe / Component / Feature / PluginRegras de forma da Recipe; o modelo da FeatureRecipe referencia um campo exclusivo de cada componente com executionScope: boundary; a verificação cruzada de featuresSchema do Workload falha.
[TRANSLATION_ERROR]Workload / saída de valuesMapping / overlay de origemResolução da porta de sonda do Helm; colisão de nomes de serviço do compose entre fronteiras; dois contribuidores do compose a declarar o mesmo nome de volume ou de config de nível superior com corpos em conflito; incompatibilidade do nome do chart no umbrella helm-chart.
[FETCH_ERROR]Obtenção a partir do registry / origem remota (operacional, não de autoria)Artefacto não encontrado no registry; autenticação necessária; rede inacessível; digest em cache incompatível com o ficheiro de bloqueio. Correção: autenticar-se, restabelecer a conectividade ou aggrega pull --upgrade --release <release>.
[POLICY_ERROR]Plugin de política (regra de governação)Um plugin de política anexado num papel de veredicto de governação rejeitou a compilação montada com base numa regra que impõe. Correção: cumprir a política imposta ou reconsiderar o anexo.
[TRUST_ERROR]Configuração de confiança, ou a própria assinatura do artefacto (uma preocupação, não uma superfície de autoria)Uma política de confiança ou uma raiz de confiança fixada ilegível; uma política keyless que não declara nenhuma identidade fidedigna; uma política de assinatura que exige uma assinatura para o tipo a publicar; um controlo de anexo de veredicto registado que a configuração já não anexa. Ou: uma assinatura que não se verifica; um artefacto sem nenhuma onde uma é exigida; um signatário não fidedigno; um plugin cuja identidade fidedigna registada já não corresponde. Correção: corrigir a configuração ou o registo de confiança versionado, ou decidir sobre o artefacto — o código curto indica qual.

Os prefixos de contexto por fornecedor (helm: node "<id>": ..., compose: node "<id>": ...) aparecem dentro da parte da mensagem das saídas [TRANSLATION_ERROR] e [CATALOG_ERROR] para localizar o fornecedor que falha quando está em jogo mais do que um fornecedor.

Erros nativos das bibliotecas

Os erros com origem numa biblioteca subjacente (erros de carregamento de charts do SDK do Helm, erros do parser YAML do docker-compose, erros de E/S de ficheiros devidos a um caminho de origem em falta) são encapsulados com o prefixo de contexto por fornecedor e surgem sob [TRANSLATION_ERROR] ou [CATALOG_ERROR], consoante tenham ocorrido na síntese ou no carregamento do conteúdo do catálogo. A mensagem encapsulada da biblioteca preserva literalmente o diagnóstico da ferramenta original, para que os autores a possam comparar com a própria documentação da ferramenta.

Referências cruzadas

  • fatal-halts.md — catálogo, erro a erro, de todas as interrupções fatais com a mensagem pretendida e como corrigi-las.
  • warnings.md — avisos não fatais que o compilador emite.
  • vocabulary/validation-surface.md — as quatro camadas de validação de esquema e a forma como as suas formas de erro interagem.