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

aggrega validate

aggrega validate verifica a correção — schema, estrutura de pilares, resolução de referências entre documentos, cadeias extends, capacidade do provider em relação ao tipo de entrada e (para uma entidade que renderiza) se ela de fato renderiza. Ele tem três modos, selecionados pelo seu argumento, que aplicam a mesma disciplina de correção em três escopos: o catálogo inteiro (sem argumento), o fechamento de dependências de uma única Release (--release) e o arquivo de uma entidade (um caminho de entidade). Cada escopo responde à mesma pergunta — “este conteúdo está correto?” — sobre uma fatia diferente do catálogo.

Correção é diferente de convenções. aggrega validate pergunta se o conteúdo é bem formado e compilaria; aggrega lint pergunta se o conteúdo segue a disciplina de publicação do catálogo (nomenclatura, alinhamento com o diretório de categoria, tamanho do incremento de versão e o restante). Os dois comandos espelham os três escopos um do outro, para que você possa verificar qualquer uma das dimensões na granularidade de que precisar.

aggrega validate não grava nada em disco e não lê nenhum estado de runtime. Ele executa a mesma resolução e validação que uma build executa, parando antes da renderização (ou, para uma única entidade, isolando-a).

Um caminho de entidade pode ser fornecido como argumento posicional. --release fornecido ao lado de um caminho de entidade não seleciona o escopo de Release: a entidade continua sendo verificada sozinha, nos termos dessa Release — veja Verificar uma entidade nos termos de uma Release.

Correção do catálogo inteiro (sem argumento)

aggrega validate sem argumento carrega cada entidade de catálogo nos diretórios de catálogo configurados e a verifica de ponta a ponta. Antes de carregar qualquer coisa, ele lê cada arquivo YAML neles, e um documento Aggrega entre eles que ele não consegue carregar interrompe a execução, como descrito abaixo. Depois:

  • Estrutura dos pilares do esquema — o bloco spec.schema: de cada Component e de cada Feature é expandido e validado (a mesma verificação de pilares do esquema que o build aplica), incluindo a expansão da forma compacta.
  • Resolução de referências entre documentos — as referências $ref e $import a entradas de uma SchemaLibrary são resolvidas, e uma SchemaLibrary que não pode ser resolvida ou que é inválida por outro motivo é rejeitada.
  • Cadeias extends — toda entidade que declara extends é resolvida em relação ao seu pai, e a forma mesclada pai+filho é verificada. Um pai que os diretórios de catálogo não contêm é lido onde um build o lê: do cache de artefatos, sob a fixação que o lockfile de uma Release registra para ele — os lockfiles das Releases para as quais a passada é executada, ou de cada Release que o espaço de trabalho contém, quando ele é validado em uma única passada. Assim, uma base publicada em um registry é validada assim que aggrega pull a tiver buscado e fixado, e um pai que nenhum dos dois contém interrompe a execução, nomeando aggrega pull --release <release>. Nada é buscado.
  • Seletores declarados — todo seletor de rótulos que um documento de Component ou Feature declara em um socket de dependência sob spec.usesSchema, ou em um slot de anexo sob spec.featuresSchema — incluindo, em um Component, os slots que um socket declara — é lido de acordo com a gramática de seletores, haja ou não algo que ligue o socket ou preencha o slot. Veja seletores declarados.
  • Colisões de localização OCI — duas identidades de catálogo distintas que publicariam no mesmo local do registry são rejeitadas de forma explícita, para que um build nunca sobrescreva silenciosamente os bytes publicados de uma entidade com os de outra.
  • Capacidade de tipo de entrada do Provider — uma Recipe ou FeatureRecipe que declara um bloco workload: vinculado a um provider que não consegue sintetizar é sinalizada como erro, porque nunca pode ser compilada.

Esta é a contraparte, no nível do catálogo inteiro, da validação por Release de um build — o lugar onde uma entidade de catálogo com defeito deve aparecer, antes que qualquer Release chegue a ela. Ele para de forma explícita diante de um documento Aggrega que não consegue carregar, e diante de qualquer violação de pilar do esquema, biblioteca irresolúvel ou inválida, falha de resolução de extends, seletor declarado que a gramática recusa, colisão de localização ou erro de capacidade por tipo de entrada. As constatações de sobreposição de pilares do esquema e de estreitamento na extensão, e cada palavra-chave x-aggrega-* que um Component ou uma Feature escreve inline no conteúdo do seu esquema, são linhas notice: informativas que nunca alteram o código de saída.

Um documento Aggrega que não pode ser carregado interrompe a execução. Um arquivo YAML em um diretório de catálogo é um documento Aggrega quando uma de suas linhas começa, sem recuo, com apiVersion: e um valor iniciado por aggrega.ai/, entre aspas ou não. Um documento desse tipo que não pode ser lido, cujo YAML não pode ser analisado, ou cujo kind ou metadata não tem a forma que o envelope de uma entidade assume — um metadata escrito como lista, por exemplo — interrompe a execução com E0175 depois que os diretórios são lidos, nomeando cada arquivo desse tipo com o motivo informado pela leitura ou pelo parser; nada é verificado e nenhuma linha catalog validation passed é impressa. Um documento que é carregado e declara um kind que nenhum catálogo contém — um Componnent digitado errado, por exemplo, ou nenhum kind — interrompe a mesma execução com E0371, sendo nomeado ao lado deles com o tipo que declara; um Manifest, uma Release e um Workload que uma Recipe importa do seu próprio diretório são ignorados. Qualquer outro YAML — os templates de um chart Helm, que só podem ser analisados depois de renderizados, valores de chart, definições de workflow — é ignorado.

Os diretórios que ele lê dependem da forma do workspace:

  • Um workspace cuja configuração não atribui diretórios de catálogo próprios a nenhuma Release é validado uma única vez, sobre sua pilha de busca: os diretórios --catalog, depois workspace.catalog_dirs, depois o diretório catalog na raiz do workspace, quando houver um.

  • Um workspace que nomeia Releases em workspace.releases pode manter um catálogo em várias variantes lado a lado, cada uma lida pela sua própria Release, e carregá-las todas de uma vez colocaria todas as variantes em um único catálogo, com a entidade de uma variante sombreando a de outra. Por isso ele é validado uma vez para cada Release que o workspace contém, sobre os diretórios que essa Release lê, com os diretórios --catalog em primeiro lugar em cada passada; uma Release que a configuração não nomeia lê a lista do workspace. Cada passada é relatada sob uma linha que nomeia sua Release e os diretórios que ela leu, seguida do resultado dessa passada:

    Release release-compose.yaml reads catalog-compose
    catalog validation passed (schema-pillar + library + extends + oci-location)
    Release release-helm-synth.yaml reads catalog-helm-synth
    catalog validation passed (schema-pillar + library + extends + oci-location)

    Releases que leem exatamente os mesmos diretórios compartilham uma passada, que nomeia cada uma delas. Uma Release que não lê nenhum diretório — sua entrada escreve catalog_dirs: [] — é relatada como sem nada a verificar, e as outras passadas são executadas normalmente. Cada passada é relatada independentemente do que uma anterior tenha encontrado, já que uma entidade com defeito em uma variante não diz nada sobre outra, e o comando falha quando qualquer passada falha, nomeando as Releases cujos diretórios falharam. As Releases que um workspace contém são seus documentos Release — arquivos YAML cujo kind é Release, em qualquer lugar sob a raiz do workspace fora de diretórios ocultos e de node_modules, vendor e dist.

Uma execução sem nada a ler em nenhuma passada é recusada em vez de relatada como um catálogo limpo: coloque as entidades em catalog/, passe --catalog ou defina workspace.catalog_dirs — ou, em um workspace que nomeia Releases, os catalog_dirs próprios de uma Release em workspace.releases. Ele nunca enumera implicitamente o diretório de trabalho atual, então nunca puxa árvores não relacionadas.

A ferramenta validate de aggrega mcp, quando solicitada para o catálogo inteiro, valida as mesmas passadas; em um workspace que nomeia Releases, sua resposta traz cada uma em passes — as Releases, os diretórios lidos e o veredito próprio dessa passada — ao lado do veredito sobre todas elas.

Uma biblioteca que só o cache de artefatos contém

O cache de artefatos contém o que um fetch colocou ali, e uma SchemaLibrary em cache só conta como conteúdo de catálogo quando uma entrada no lockfile de uma Release garante o seu digest — veja O que o cache é, e o que ele não é. Quando um $ref: não se resolve em nada enquanto o cache contém uma biblioteca que nenhuma entrada de lockfile fixa e que nenhum diretório de catálogo lido pela verificação fornece, o relatório é seguido de uma linha remediation: que nomeia cada uma dessas bibliotecas e a ação que funciona para o escopo que falhou:

  • Sem argumento, e com um caminho de entidade, com ou sem --release, validate lê bibliotecas apenas dos diretórios de catálogo, nunca por meio de uma entrada de lockfile, de modo que uma entrada registrada não mudaria o seu veredito. A linha diz isso e indica escrever a biblioteca em um diretório de catálogo, ou aggrega pull --release <release> seguido de aggrega validate --release <release>, que verifica a Release em relação às bibliotecas que seu lockfile fixa.
  • Apenas com --release, validate lê o lockfile da Release, então a linha nomeia aggrega pull --release <release>, que resolve a biblioteca e registra sua entrada, ou a escrita da biblioteca em um diretório de catálogo.

A linha não altera nem o veredito nem o código de saída.

Seletores declarados

Um Component ou uma Feature restringe o que pode ser ligado aos seus sockets de dependência, e o que pode preencher seus slots de anexo, com seletores de rótulos — o selector: de cada entrada de spec.usesSchema e de cada entrada de spec.featuresSchema, e, em um Component, o selector: de cada slot que um socket declara sob seu próprio featuresSchema. Um build lê um seletor apenas onde algo o alcança: uma aresta traçada através do socket, um anexo que preenche o slot. Por isso, o escopo do catálogo inteiro e o escopo de entidade única leem todo seletor que um documento de Component ou Feature declara, haja ou não algo que ligue o socket ou preencha o slot, e um seletor que a gramática recusa — uma lista de valores sem o parêntese de fechamento, uma vírgula duplicada, uma chave contendo = ou ! — faz a verificação falhar. A gramática é a ensinada em a gramática de strings.

A recusa é a mesma que um build informa quando alcança o mesmo seletor, com o mesmo código e nas mesmas palavras: E0007 para o seletor de um socket e E0008 para o de um slot, nomeando o seletor, o socket ou slot que o declara e por que a gramática não conseguiu lê-lo. Ela é registrada como falha de catálogo no arquivo da entidade:

selector violation ("<selector>", declared on socket "<socket>", which could not be evaluated: "<why it could not be read>"). Correct the selector on the socket’s declaration in the component type’s usesSchema. (violação de seletor: o seletor declarado no socket não pôde ser avaliado. Corrija o seletor na declaração do socket no usesSchema do tipo de componente.)

Cada documento é lido como seu autor o escreveu, então um seletor que uma entidade base declara é informado uma única vez, no próprio arquivo da base, e não uma vez para cada entidade que a estende. Os appliesTo e appliesToAnyOf de uma Feature não são lidos aqui: são lidos onde quer que um anexo da Feature seja avaliado.

O escopo do catálogo inteiro informa cada seletor recusado em sua própria linha selector: e falha com a contagem deles; o escopo de entidade única os informa como falha do seu nível de forma — com ou sem --release ao lado do caminho da entidade, já que essa forma é o escopo de entidade única executado nos termos de uma Release (veja verificar uma entidade nos termos de uma Release). --release sozinho, que valida o fechamento de dependências de uma Release, e um build leem um seletor apenas onde uma aresta ou um preenchimento o alcança, e param nele ali.

Correção limitada a uma Release (--release)

aggrega validate --release <release-path> valida exatamente as entidades que as dependências resolvidas de uma única Release alcançam, em vez do catálogo inteiro ou de uma única entidade. Ele calcula o fechamento pelo mesmo mecanismo que um build usa, de modo que as entidades que ele verifica são exatamente as que um build dessa Release resolveria, e sobre esse fechamento:

  • resolve as cadeias extends limitadas ao fechamento, falhando em caso de erro de resolução;
  • valida os pilares do esquema de cada entidade resolvida (limitados ao fechamento), falhando em caso de erro de pilar do esquema;
  • executa a mesma verificação de conformidade de valores pré-renderização que um build executa — resolve os parâmetros da Release nos valores escritos pelo autor (assim um valor {{ .parameters.* }} é verificado já resolvido, não como template) e valida o resultado em relação aos esquemas compostos do fechamento, incluindo a conformidade com o esquema composto pai+filho para uma entidade que usa extends. Um valor que viola seu esquema falha com código de saída diferente de zero;
  • avalia cada asserção de Recipe e FeatureRecipe em relação aos valores em que a Release se resolve, como um build as avalia antes de renderizar: a Recipe de cada componente é vinculada como o Manifest a mapeia, seus locals e provides são resolvidos, e a primeira asserção que falha — uma que chama fail, ou uma cujo template para em uma chave que não encontra — faz a validação falhar com a condição e a frase com que um build para. Um template locals ou provides que não pode ser avaliado também a faz falhar, como faz um build falhar. O provider pelo qual cada Recipe renderiza é consultado sobre o nome que dá aos recursos desse componente, como um build o consulta, porque os provides de uma Recipe podem ler esse nome; nada é renderizado. Essas asserções só são avaliadas quando nada acima já falhou, de modo que uma Release informa a falha mais antiga em que um build pararia;
  • exibe as constatações de sobreposição de pilares do esquema e de estreitamento na extensão como linhas notice: informativas que nunca alteram o código de saída;
  • mostra cada palavra-chave x-aggrega-* que uma entidade lida por ele escreve inline no conteúdo do seu esquema como uma linha warning:, uma vez por entidade, como um build a mostra — isso também nunca altera o código de saída.

Isso torna --release uma verdadeira verificação pré-build: ele detecta o que um build rejeitaria, antes do build — a validação de dependências do build sem a renderização. Ele não renderiza nada e não dispara nenhum pull de rede: o fechamento é resolvido a partir do catálogo local (e dos pins do lockfile da Release, quando presente); um conjunto de dependências fixadas em um registry que precisa de um lockfile exibe um erro honesto de referência irresolúvel em vez de baixar. O estreitamento é exibido como recomendação, nunca imposto.

Um lockfile que não corresponde mais àquilo para o que a Release é resolvida recusa a validação com a parada que aggrega build imprime. Quando há um lockfile ao lado da Release, --release o confronta com aquilo para o que a Release é resolvida, com a comparação de desvio que um build executa antes de renderizar, assim que as dependências da Release são resolvidas e antes que qualquer verificação acima seja executada. Um lockfile do qual uma entidade fixada, uma biblioteca, um plugin ou o próprio arquivo da Release se desviou interrompe a validação com a recusa E0130 do build — cada entrada que se desviou e, em seguida, o aggrega pull --release <release> que resolve a situação — e um código de saída diferente de zero, de modo que uma validação nunca deixa passar um lockfile que o build recusa por desvio. Sem argumento, e com um caminho de entidade, validate não fica sujeito a um lockfile: a verificação do catálogo inteiro lê as fixações do lockfile apenas para encontrar um pai de extends, e a verificação de uma única entidade não lê nenhum lockfile.

Como ele executa as mesmas verificações que um build, também executa os mesmos plugins de controle anexados — e por isso está sujeito ao mesmo registro de identidades de plugins confiáveis ao qual um build está sujeito. Um workspace que anexa um plugin que retorna um veredito de aceitação ou rejeição tem um registro de confiança de plugins ao lado de sua Release, e --release compara a configuração com ele antes que qualquer um desses plugins seja executado: um controle registrado que a configuração não anexa mais interrompe a validação, e um plugin resolvido a partir do cache que aggrega pull preenche cujo artefato não é o registrado é recusado em vez de executado. Um workspace que não registrou nada não tem registro, o que não muda nada para essa comparação. --release também nomeia cada retirada registrada contra aquilo de que a Release depende, na saída de erro padrão, como uma linha deprecation: nas palavras que aggrega build imprime: tanto um marcador que o lockfile registra contra uma referência fixada quanto um que o registro de confiança registra contra um plugin anexado em um papel de veredito. Uma retirada não altera nem o veredito nem o código de saída, e um registro de confiança que existe e não pode ser lido interrompe a validação em vez de passar como um que não registra nada.

Um plugin lido do cache também está sujeito à assinatura que sua entrada registra, assim como um build o sujeita, no momento em que é carregado. Onde sua entrada registra uma assinatura verificada, o material de assinatura que esse fato nomeia no cache é verificado novamente, e um plugin cujo material está ausente ou difere é recusado — assim como um cujo material foi feito para um plugin diferente do lido, que é a aparência de uma signature copiada de outra entrada, independentemente do que diga o requisito de assinatura. Onde a configuração de confiança do workspace exige uma assinatura, um plugin lido do cache cuja entrada não registra nenhuma — ou para o qual o registro não contém nenhuma entrada, incluindo um registro excluído — também é recusado, sob as mesmas configurações que fariam aggrega pull recusá-lo sem assinatura, de modo que skip_signature_verification e um registry advisory permitem que ele seja executado. Uma recusa faz a validação falhar e é relatada entre seus diagnósticos, nomeando o plugin e aggrega pull --release <release>, o comando que verifica sua assinatura no registry, a registra e armazena em cache o bundle que ela nomeia, reescrevendo uma cópia em cache que não corresponde mais ao seu digest; um plugin servido a partir de um dos seus diretórios de catálogo, ou da cópia dentro do binário do compilador, nunca está sujeito ao requisito. Os outros dois escopos não estão sujeitos a nada disso: eles não leem os anexos de plugins do workspace, então nenhum plugin desse tipo é executado neles.

O mesmo vale para os plugins que alteram o grafo em vez de julgá-lo. Um anexo label-transform ou annotation-transform molda como seria a saída renderizada, então o lockfile fixa tanto sua identidade quanto os arquivos-fonte que ele lê — e --release executa esses anexos da forma como um build os executa: reconstruídos a partir do lockfile, sujeitando cada um ao seu digest registrado e lendo o conteúdo-fonte que o lockfile carrega em vez do arquivo em disco. Vale a pena conhecer duas consequências antes de encontrá-las:

  • Anexar um plugin de transformação em .aggrega-config.yaml não muda o que --release faz até que você execute um pull. É a mesma regra que um build segue, e pelo mesmo motivo: o conjunto de anexos é uma entrada que determina os bytes, então ele é adotado no pull, e não no momento em que é editado.
  • Um plugin em cache cujos bytes não correspondem mais ao digest que o lockfile registrou é recusado, exatamente como seria durante um build.

Se a Release não tiver lockfile, --release valida mesmo assim — ele avisa que não conseguiu verificar a identidade de um plugin e indica o que executar, em vez de recusar. Veja avisos.

Devolver o grafo compilado

--ir-graph escreve na saída padrão, como JSON, o grafo que esta validação resolveu, antes da linha do veredito. Ele é aditivo: as mesmas verificações são executadas, os mesmos diagnósticos são escritos e o código de saída é o mesmo que seria sem ele. O grafo devolvido é aquele sobre o qual a validação foi realizada, então ele não pode descrever uma resolução diferente daquela sobre a qual o veredito informa.

Ele se aplica apenas a este escopo — os escopos de catálogo inteiro e de entidade única acionam um harness sintetizado em vez de uma Release, e não resolvem nenhum grafo — e solicitá-lo em outro lugar é recusado em vez de ignorado silenciosamente. Se a execução parar antes de o grafo ser resolvido, nada é escrito na saída padrão e os próprios diagnósticos do comando dizem o que a interrompeu.

Observe a flag ao lado. --response-format define quanto do próprio relatório deste comando é escrito (detailed ou concise); --ir-graph pede um segundo documento ao lado desse relatório. Uma é volume, a outra é assunto, e nenhuma altera o veredito.

Valores que um autor declarou sensíveis são retidos do grafo — incluindo os values e o infra de uma conexão, quando o socket do componente consumidor declara uma folha como sensível —, na forma estruturada descrita em aggrega inspect. --unredacted ao lado de --ir-graph os imprime em vez disso, nos termos que aggrega inspect --unredacted estabelece: ele alcança o grafo e nada mais do que este comando escreve, e tudo o que a saída alcança passa então a conter esses valores em texto claro. Passado sem --ir-graph, ele é recusado, porque não haveria nada para revelar.

Correção de uma única entidade (um caminho de entidade)

aggrega validate <entity-path> verifica um único arquivo de entidade de catálogo. Ele aplica um conjunto escalonado de verificações, parando na primeira falha bloqueante para que um erro de esquema apareça de forma explícita antes de qualquer trabalho no catálogo:

  • Placeholders (todo tipo) — um valor que o tipo exige e que o arquivo deixa como string vazia. Todos são relatados de uma vez, antes das outras verificações, cada um com o que aceita; veja placeholders ainda pendentes.
  • Envelope do esquema (todo tipo) — a verificação exata de JSON-Schema por entidade que o carregador do catálogo executa em cada fronteira de análise.
  • Forma (todos os tipos) — a validação estrutural específica do tipo. Para um Component ou uma Feature, isso inclui ler todo seletor de rótulos que o arquivo declara em um socket de dependência ou em um slot de anexo de acordo com a gramática de seletores; veja seletores declarados.
  • Estrutura de pilares (Component e Feature) — a verificação de pilares spec.schema:, usando as SchemaLibraries do catálogo para a expansão de $ref entre documentos.

Um Component ou uma Feature para aí: envelope do esquema, forma e estrutura de pilares. Um Component isolado não tem values nem infra escritos pelo autor para renderizar isoladamente, então não há nada a renderizar — sua correção é totalmente coberta pelos níveis de esquema e pilares. Cada palavra-chave x-aggrega-* que o conteúdo do seu esquema escreve inline é informada entre as notas informativas na saída de erro padrão como uma linha warning: que nomeia a palavra-chave, onde ela está e a tabela declarativa a escrever em seu lugar; isso nunca altera o veredito nem o código de saída.

Uma Recipe é, além disso, renderizada isoladamente. Essa é uma faceta da correção de uma única entidade, não seu ponto principal: depois que os níveis de esquema e forma passam, validate resolve a partir do catálogo o Component de implements da Recipe, sintetiza um Aggregate, um Manifest e uma Release mínimos em torno de uma única instância desse Component vinculada à Recipe em teste, e executa sobre eles o pipeline de compilação real — primeiro a resolução e as guardas (com a renderização ignorada), depois uma renderização real da saída isolada. Cada valor obrigatório e cada campo infra obrigatório sem valor padrão é preenchido com um placeholder do seu tipo declarado — os valores no Aggregate sintetizado, a infra na Release sintetizada — e todos os outros valores e campos infra recebem o padrão do esquema por meio do resolvedor; a Release encaminha a instância para um boundary padrão sintetizado e não declara nenhum values: nem nenhum recurso de computação que o Aggregate não tenha declarado. Um placeholder é um valor que as restrições declaradas do próprio campo aceitam: a constante ou o primeiro valor que um enum lista, um número dentro de seus limites, uma string do seu comprimento e no seu format, uma versão semântica onde seu pattern pede uma, tantos itens de lista quantos ele exige, e cada propriedade que um objeto exige. Qualquer outro pattern, uma condição validate: ou when:, uma composição de esquemas e uma restrição sobre quais itens uma lista contém não são consultados, de modo que um campo que dependa de um deles ainda pode recusar seu placeholder; validate então relata essa recusa nas próprias palavras do esquema. Os artefatos renderizados são impressos para que o autor veja a saída isolada antes de conectar a entidade a um Aggregate completo. Como um harness de entidade única preenche apenas esses campos obrigatórios, não estabelece nenhuma conexão e não anexa nenhuma Feature, uma Recipe cujos templates leem um valor que apenas uma conexão ou uma Feature anexada fornece não pode ser renderizada isoladamente; validate relata essa renderização como não tentada em vez de falha. Uma asserção que chama fail é relatada como aviso em vez de fazer a verificação falhar — veja uma asserção com falha é um aviso. Uma renderização que para por qualquer outro motivo não foi concluída, e validate a relata com o diagnóstico de renderização subjacente até a frase que nomeia o que a interrompeu.

Uma Recipe cujo source: precisa ser baixado não é renderizada de forma alguma, e uma Recipe cuja renderização para enquanto lê um valor que apenas uma conexão ou uma Feature anexada fornece tem essa renderização posta de lado — veja o que a correção de uma única entidade não verifica abaixo.

Uma FeatureRecipe é verificada quanto a esquema e forma; sua renderização é ignorada, porque uma FeatureRecipe só é renderizada quando anexada a um componente hospedeiro, e não se tenta sintetizar um hospedeiro que passe nas guardas para uma Feature arbitrária.

Verificar uma entidade nos termos de uma Release

Um workspace pode atribuir a cada Release diretórios de catálogo próprios — veja Atribuir a uma Release diretórios de catálogo próprios — e assim manter uma variante de catálogo por Release lado a lado. Um caminho de entidade informado sozinho é verificado sobre os diretórios de catálogo do próprio workspace, onde uma referência a uma dessas variantes — o Component que uma Recipe implementa, uma SchemaLibrary a que um pilar se refere — não é encontrada. Informe --release ao lado do caminho da entidade e as mesmas verificações são executadas nos termos dessa Release: as referências da entidade são resolvidas pelos diretórios de catálogo que a configuração do workspace atribui a essa Release, com qualquer --catalog colocado antes, que são os diretórios que um build dessa Release lê.

O exemplo MariaDB + Adminer mantém quatro variantes desse tipo. O Component da sua variante synth obtém suas configurações de armazenamento de uma SchemaLibrary que apenas as variantes synth e chart contêm, então ele é validado nos termos da Release que compila com ele:

$ aggrega validate catalog-helm-synth/component/mariadb.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/component/mariadb.yaml
Kind: Component
Schema: valid
Pillars: valid

e falha, nomeando a biblioteca que não conseguiu resolver, nos termos de uma Release cujos diretórios não a contêm — --release release-compose.yaml, ou nenhum --release em um workspace que não lista diretórios de catálogo próprios.

Uma Recipe é verificada da mesma forma. A Recipe da variante synth implementa core/datastore/mariadb, que os diretórios de catálogo do próprio workspace não contêm, então, informada sozinha, ela falha com render: implements target "core/datastore/mariadb" not found in catalog. Informada com a Release que compila com ela, ela resolve o Component dessa Release e é renderizada isoladamente:

$ aggrega validate catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.
Resolution: valid
Render: 3 artifact(s)

seguido dos três artefatos renderizados. Cada variante desse exemplo declara core/datastore/mariadb, então a Recipe é validada nos termos de cada uma das suas quatro Releases; nos termos de uma Release cujos diretórios de catálogo não contêm tal Component, ela falha nomeando o alvo, como acontece sem --release. As linhas Attachments: são explicadas em um slot de anexo obrigatório ou um mandato de presença.

Este continua sendo o escopo de entidade única. As verificações, o relatório e o código de saída são os que esta seção descreve — um Component ou uma Feature que traz um seletor de socket ou de slot que a gramática recusa falha aqui exatamente como falha sem --release, veja seletores declarados — e nenhum fechamento é validado: --release nomeia a Release por cujos diretórios de catálogo as referências da entidade são lidas, não um fechamento a verificar, e é por isso que --ir-graph é recusado ao lado de um caminho de entidade. Um --release que nomeia um arquivo que não existe, ou um diretório, é recusado antes que qualquer coisa seja verificada.

Um diretório que a configuração do workspace lista e que não é um diretório — porque nada existe ali, por exemplo —, para essa Release, ou para o workspace quando nenhum --release é informado, é recusado antes de qualquer verificação, assim como todo comando que lê esse catálogo o recusa (De onde as entidades locais são lidas): a recusa nomeia a entrada, o arquivo de configuração e a linha que a listam e a configuração, e nenhum veredito é dado. A verificação de entidades do editor por meio de aggrega serve dá a mesma recusa como a única entrada no arquivo da entidade, no nível de erro, e a ferramenta validate de aggrega mcp recusa a chamada com ela.

Placeholders ainda pendentes

Um valor que o tipo exige e que o arquivo deixa como string vazia é um placeholder, e validate o relata antes de qualquer outra coisa. Um documento rascunhado por aggrega scaffold contém um onde quer que seu tipo precise de um valor que só você pode fornecer, então é aqui que você descobre quais restam. Aqui está uma FeatureRecipe rascunhada com apenas a versão preenchida:

Entity: my-feature-recipe.yaml
Kind: FeatureRecipe
2 placeholders still owed in my-feature-recipe.yaml; an empty required value is not a value, so each of these needs one before the document validates:
7:3: spec.capability takes what its schema describes: The explicit provider capability this recipe binds to (e.g., 'helm', 'terraform', 'compose') — the provider kind that renders it.
8:3: spec.implements takes what its schema describes: Declares which catalog Feature type this recipe is able to implement (including credential Features labeled feature.aggrega.ai/kind: secret; exact version, major-compatible range '^', or unversioned).

Todos os placeholders do arquivo são nomeados de uma vez, na ordem do documento, com sua linha e coluna e com o que aceitam. O que aceitam é lido do próprio esquema do tipo: os valores que ele aceita onde o esquema os lista, uma versão semântica como 1.0.0 onde o esquema pede uma, e caso contrário a primeira frase da própria descrição do campo no esquema.

Quais valores contam também é lido do esquema. Um valor conta quando o tipo o exige no nível superior do documento, ou dentro de um objeto que o tipo também exige, e o arquivo o define como string vazia. Uma chave que o arquivo omite por completo é relatada pela verificação de esquema como propriedade ausente. Um campo opcional deixado vazio não é um placeholder, nem um campo obrigatório apenas dentro de uma lista ou de um mapa que você escolheu escrever. Onde o próprio esquema lista a string vazia entre os valores que um campo aceita, uma string vazia é um valor e não um placeholder.

Um valor está pendente mesmo onde o esquema o aceitaria vazio. O esquema admite uma string vazia para capability e implements de uma Recipe ou FeatureRecipe, mas uma string vazia não nomeia nenhum provider nem nenhum tipo, então validate relata ambos como placeholders como qualquer outro. Onde a verificação de esquema também recusa o mesmo arquivo — uma versão vazia, um rótulo de tipo sem valor — o relatório traz o código dessa verificação, E0215, como mostra o exemplo em aggrega scaffold; onde a verificação de esquema o aceita, como acima, o relatório não traz código. Uma constatação no mesmo arquivo que não diz respeito a um valor vazio ainda é relatada, nas próprias palavras da verificação de esquema, antes da lista.

Essa leitura pertence à validação de entidade única, com ou sem --release ao lado do caminho da entidade. Uma execução de catálogo inteiro que encontra o mesmo documento relata o que a verificação de esquema relata, de modo que uma FeatureRecipe com um implements vazio dentro de um diretório de catálogo passa por ela; o escopo de Release e aggrega build também não aplicam essa leitura.

Um tipo que este escopo não aceita

A validação de entidade única aceita Component, Feature, Recipe, FeatureRecipe, Workload e Plugin. Um arquivo de qualquer outro tipo é recusado, e a recusa nomeia os tipos que ela aceita e, para um tipo de entidade, o escopo que de fato verifica um documento desse tipo:

kind "Aggregate" in "aggregate.yaml" is not a single-entity validation target; the kinds this scope accepts are Component, Feature, Recipe, FeatureRecipe, Workload and Plugin. An Aggregate is checked by the whole-catalog scope when it sits in a catalog directory, and by the Release scope over a Release that deploys it

O escopo de catálogo inteiro é uma execução sem argumento, e o escopo de Release é --release sem caminho de entidade:

TipoVerificado por
Aggregateuma execução de catálogo inteiro, quando está em um diretório de catálogo; --release sobre uma Release que o implanta
Manifest--release sobre uma Release que o nomeia
Release--release <release-path>
SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibraryuma execução de catálogo inteiro, quando está em um diretório de catálogo

Uma execução de catálogo inteiro lê apenas o que está dentro dos diretórios de catálogo configurados, então um Aggregate mantido na raiz do workspace ao lado de sua Release é verificado por meio de --release sobre essa Release.

Uma asserção com falha é um aviso

Uma asserção que chama fail — uma que a Recipe declara, ou uma que seu Component de implements declara — é relatada como aviso, e a verificação não falha por causa dela. A Release sintetizada contém placeholders e padrões do esquema no lugar dos valores que uma Release real define, então uma asserção sobre um desses valores, uma imagem ou a presença de um pré-requisito falha aqui quer a Recipe esteja correta ou não, e validate não consegue distinguir uma asserção que aguarda uma Release de uma que está quebrada. O veredito sobre a asserção fica para um build, que sempre tem uma Release.

O aviso é escrito na saída de erro padrão, iniciado por warning:, depois de quaisquer notas informativas. Ele traz a mensagem completa da asserção — a entidade, a instância, o nome da asserção e a frase que seu autor escreveu — encerrada por mais uma frase:

A Release must satisfy this assertion before a build of it can pass.

O relatório na saída padrão diz onde a execução parou, e o comando sai com 0. A própria asserção de uma Recipe interrompe a renderização, então o relatório mostra Render: stopped on a failed assertion, reported as a warning depois de Resolution: valid. A asserção de um Component é avaliada antes que qualquer coisa seja renderizada, então o relatório mostra Resolution: stopped on a failed assertion, reported as a warning, seguido de Render: not attempted (the run stopped on that assertion). Em ambos os casos nada é renderizado, então nenhum artefato é impresso.

Apenas uma asserção que chama fail é um aviso. Uma asserção que para em uma chave que lê mas não encontra, ou que não pode ser analisada, é uma falha no próprio texto da asserção e não uma asserção com falha, e é julgada como qualquer outra parada. Toda outra falha mantém seu lugar como veredito da verificação.

aggrega build de uma Release que não satisfaz a asserção para nela com um erro, nomeando a asserção e trazendo a frase de seu autor, como sempre, e aggrega validate --release sobre essa Release falha nela com o mesmo erro. A verificação de entidades do editor por meio de aggrega serve dá o mesmo aviso, desenhado na própria chave da asserção onde a Recipe a declara, e a ferramenta validate de aggrega mcp responde valid: true com o aviso entre suas notices.

O que a correção de uma única entidade não verifica

Quatro verificações de um build real estão fora do alcance de um build de uma única entidade, e validate abre mão de cada uma em vez de relatar uma constatação que não pode sustentar.

Uma origem que precisa ser baixada

Validar uma única entidade não lê nenhum lockfile, não lê nem escreve nenhum cache e não faz nenhuma requisição de rede. Uma Recipe cujo source: nomeia algo obtido por um transporte — um repositório de charts OCI ou HTTPS, um repositório Git — portanto não tem nenhum código de infraestrutura a partir do qual renderizar: o chart ou o módulo não existe em nenhum lugar que a execução possa alcançar, e nada no arquivo verificado está errado. Validate diz isso, imprime como um resultado distinto de uma renderização e sai com 0:

Entity: catalog/recipe/helm/openbao/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Resolution: valid
Render: not attempted (this Recipe's source is fetched)
Validating one entity on its own reads no lockfile, reads and writes no
cache, and makes no network request, so the chart or module this Recipe
names is never retrieved and there is nothing to render from. To render
it, build a Release that deploys a component this Recipe implements.

Tudo acima dessa linha foi verificado e é relatado como válido. O que o código de saída significa para uma Recipe assim é, portanto, mais restrito do que para uma que foi renderizada — esquema, forma e resolução se sustentam; a renderização não está comprovada — e o relatório informa qual dos dois você está lendo.

Uma origem que o workspace já contém não é posta de lado. Um source: ./module relativo não precisa ser baixado, então sua renderização é tentada como qualquer outra, e uma falha nela é uma constatação real relatada como Render: not completed in isolation com código de saída diferente de zero. A linha acima aparece apenas para uma origem que precisa ser obtida.

Para renderizar de verdade uma Recipe com origem baixada, execute aggrega build sobre uma Release que implanta um componente que a Recipe implementa: um build resolve a origem pelo lockfile da Release e pelo cache local, que é o que fornece os bytes que validate não tem como obter.

Um socket uses obrigatório

A segunda é se os sockets uses required: true do Component de implements estão preenchidos.

Um socket obrigatório é preenchido conectando uma aresta a outro componente — a partir do próprio bloco uses do Aggregate, ou de uma Release que conecta um socket que o Component declara. O harness sintetizado contém uma única instância, então não contém nenhum segundo componente para o qual tal aresta possa apontar, e nenhuma escrita dos documentos sintetizados pode produzir um: inventar um par significaria inventar recursos de computação que o harness nunca declarou. Validate, portanto, nomeia os sockets que não verificou e continua com a resolução e a renderização:

Sockets: required uses sockets not checked (backend, cache, registry)
Validating a Recipe on its own places its Component in a build of one,
so no other component exists for a required socket to be wired to. Whether
each of these sockets is populated is checked when the Component is deployed
in an Aggregate.

A linha aparece apenas quando o Component declara pelo menos um socket obrigatório, e nomeia apenas os obrigatórios — um socket opcional nunca é listado, porque deixá-lo desconectado não é uma constatação em nenhum escopo. Uma Recipe cujo Component não declara nenhum socket obrigatório não produz essa linha, e seu relatório não muda.

A regra em si não é relaxada nem duplicada; ela é feita no escopo que pode respondê-la. aggrega build a aplica integralmente sobre as superfícies de arestas do Aggregate e da Release juntas, e para em um socket obrigatório que nada conecta. Assim, uma Recipe que passa na validação de entidade única ainda precisa satisfazer a regra de sockets obrigatórios quando seu Component é implantado, e o relatório diz isso em vez de deixar uma diferença silenciosa entre o que validate verificou e o que um build verificará.

Um slot de anexo obrigatório ou um mandato de presença

A terceira é se os slots de anexo required: true do Component de implements — os pontos de vinculação nomeados que seu featuresSchema declara — estão preenchidos, e se está presente um anexo de cada tipo de Feature que seus mandatos de presença exigem.

Um slot obrigatório é preenchido anexando uma Feature com esse nome, no Aggregate ou na Release, no componente ou em um escopo acima dele — onde o Component é implantado, não na Recipe. O harness sintetizado não anexa nenhuma Feature, então nada do que ele constrói pode preencher tal slot. Validate, portanto, nomeia os slots que não verificou e continua com a resolução e a renderização, exatamente como faz para sockets obrigatórios:

Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.

A linha aparece apenas quando o Component declara pelo menos um slot obrigatório, e nomeia apenas os obrigatórios; uma Recipe cujo Component não declara nenhum não produz essa linha. Apenas o requisito é posto de lado: a restrição de rótulo de um slot e seus mecanismos de entrega permitidos são mantidos como declarados. Um template que não pode ser analisado ainda faz a execução falhar, assim como uma falha da própria Recipe, como um Workload que o provider não consegue sintetizar — a menos que a Recipe também leia um valor que apenas uma conexão ou uma Feature anexada fornece, como descreve a próxima seção.

Um mandato de presença — uma anotação features.aggrega.ai/requiredType.<label> no Component, exigindo que algum anexo carregue o tipo de Feature que ela nomeia — é posto de lado pelo mesmo motivo: o harness não anexa nada, então nada do que ele constrói pode carregar o tipo. Validate nomeia cada mandato que não verificou pelo seu rótulo e pelo tipo que exige, e continua com a resolução e a renderização. O example/compute/service da biblioteca padrão declara um, então sua Recipe relata, antes de seus dois artefatos renderizados:

$ aggrega validate aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml --catalog aggrega-catalog
Entity: aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: presence mandates not checked (monitoring: core/prometheus-exporter)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to carry a type the Component requires. Whether
an attachment of each of these types is present is checked when a Release
that deploys the Component is built.
Resolution: valid
Render: 2 artifact(s)

Um mandato cuja declaração não pode ser avaliada — o prefixo da anotação sem rótulo depois dele, ou um valor que não é um tipo de Feature — não é posto de lado: é uma falha do próprio Component, que nenhum anexo corrige, e validate faz a execução falhar por causa dele, como um build faz.

Cada regra é feita onde pode ser respondida. aggrega pull, aggrega build e aggrega validate --release avaliam ambas sobre os anexos reais da Release, e cada um para em um slot obrigatório que nada preenche e em um tipo exigido que nenhum anexo carrega.

Um valor que apenas uma conexão ou uma Feature anexada fornece

A quarta é se uma Recipe é renderizada depois que suas conexões e suas Features anexadas fornecem o que seus templates leem.

Os templates de uma Recipe leem o que uma conexão entrega em .context.inject e .context.uses, e o que uma Feature anexada entrega em .features. O harness sintetizado não estabelece nenhuma conexão e não anexa nenhuma Feature, então todas essas leituras não encontram nada: uma leitura em .context.inject.env encontra um canal de entrega vazio, e um range sobre .context.uses não encontra nenhuma conexão. Validate renderiza primeiro a Recipe, e uma renderização que é concluída é relatada normalmente. Quando a renderização para e os templates da Recipe — incluindo os arquivos e as entradas de biblioteca que eles importam — leem qualquer coisa sob esses três, validate relata a renderização como não tentada, nomeia os valores que a Recipe lê ali, imprime a frase em que a renderização parou e sai com 0. A variante chart do exemplo MariaDB + Adminer lê suas credenciais de banco de dados do canal de entrega que seus dois segredos anexados preenchem:

$ aggrega validate catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml --release release-helm-chart.yaml
Entity: catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.
Resolution: valid
Render: not attempted (this Recipe reads values a build of one cannot supply)
Validating a Recipe on its own places its Component in a build that wires
no connection and attaches no Feature, so nothing supplies what its
templates read under .context.inject, .context.uses or .features. Its
render stopped, and whether on one of those values or on a fault of its
own is not judged here. To render it, build a Release that deploys a
component this Recipe implements.
Reads: .context.inject.env.MARIADB_PASSWORD, .context.inject.env.MARIADB_ROOT_PASSWORD
The render stopped: rendering: [CATALOG_ERROR] instance instance: rendering node "instance": [CATALOG_ERROR] catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml: recipe "mariadb-chart" valuesMapping: [CATALOG_ERROR] valuesMapping[mariadb-chart]: template "valuesMapping[mariadb-chart]" execute: template: valuesMapping[mariadb-chart]:7:30: executing "valuesMapping[mariadb-chart]" at <.context.inject.env.MARIADB_ROOT_PASSWORD>: nil pointer evaluating interface {}.MARIADB_ROOT_PASSWORD

Uma leitura que não encontra nada e não interrompe nada não é posta de lado: um range sobre .context.uses que não renderiza nada, em uma renderização que é concluída, é relatado como a renderização que foi.

O que decide é o que a Recipe lê, não aquilo em que a renderização parou, e isso tem uma consequência que vale a pena conhecer antes de encontrá-la: uma falha da própria Recipe em uma Recipe que também lê um valor desse tipo — uma chave escrita errada, por exemplo — é relatada como não tentada junto com o resto, não como uma falha. A linha The render stopped: traz a própria frase da renderização para que você possa ver qual era, e um build de uma Release que implanta o Component julga a renderização por completo.

Duas falhas ainda fazem a execução falhar independentemente do que a Recipe leia, porque nenhuma conexão ou Feature as altera: um template que não pode ser analisado, e uma referência que a renderização recusa — uma raiz que o contexto de renderização não define, ou uma chave digitada errado sob uma raiz cuja forma é fixa, como .context.instance_idd. Uma asserção que a Recipe declara e que chama fail não é posta de lado nem é uma falha, independentemente do que a Recipe leia: ela é relatada como o aviso que uma asserção com falha sempre é. Uma Recipe cujos templates não leem nenhum dos três tem sua renderização julgada por completo, e uma renderização que para falha com a frase que nomeia a causa.

A ferramenta validate de aggrega mcp dá o mesmo veredito sobre a mesma Recipe: uma renderização posta de lado dessa forma responde como válida sem nada em seus diagnósticos, e as linhas acima estão no texto que ela retorna ao lado deles.

O carregamento do catálogo no modo de entidade única é tolerante: uma entidade com defeito não relacionada em outro ponto do catálogo é ignorada em vez de abortar a verificação, então ela nunca impede a validação isolada do alvo.

Um arquivo ignorado ainda explica um Component que desaparece por causa dele. Quando o destino implements de uma Recipe não é encontrado e exatamente um arquivo ignorado declara esse Component, o relatório começa pela recusa desse próprio arquivo — seu caminho, a restrição que ele viola e o código curto da condição no cabeçalho —, seguida de uma note: dizendo que o arquivo foi ignorado no carregamento, de modo que o catálogo não contém nada sob a identidade que ele declara, e depois pela falha implements target … not found in catalog como o motivo pelo qual o arquivo era necessário. Quando nenhum arquivo ignorado declara esse Component, ou mais de um declara, a falha de não encontrado vem primeiro e todos os arquivos ignorados são listados abaixo dela sob note: catalog files skipped at load. Esta é a explicação que aggrega build dá de um arquivo que ignorou, e a verificação de entidades do editor por meio de aggrega serve e a ferramenta validate de aggrega mcp também a dão. Um catálogo do qual nada foi ignorado relata exatamente como relataria de outra forma.

Como validate se relaciona com lint e build

Os três comandos cobrem três perguntas diferentes:

  • aggrega validate — isto está correto? Esquema, pilares, referências, extends, capacidade por tipo de entrada e renderização isolada. Ele não lê nenhum estado de runtime e não emite artefatos.
  • aggrega lint — isto segue as convenções de publicação do catálogo? Nomenclatura, alinhamento entre categoria e diretório, prefixos de anotação, tamanho do incremento de versão e o restante da disciplina de publicação opcional. Lint espelha os três escopos de validate, mas nunca verifica a correção.
  • aggrega build — compilar uma implantação completa. Build precisa de um fechamento completo de Aggregate + Manifest + Release e emite artefatos nativos do provider. Ele valida seu próprio fechamento de dependências como parte da compilação e depois renderiza. aggrega validate --release é essa validação de dependências por si só, sem a renderização; validate de entidade única isola a renderização de uma única Recipe sem um Aggregate completo.

Exemplos

Validar o catálogo inteiro:

aggrega validate --catalog ./catalog

Validar exatamente aquilo de que uma Release depende, antes de compilá-la:

aggrega validate --release releases/production.yaml

Validar uma entidade e — para uma Recipe — ver sua saída renderizada isoladamente:

aggrega validate core/datastore/postgres/recipes/helm.yaml

Validar uma entidade nos termos de uma Release à qual a configuração do workspace atribui diretórios de catálogo próprios:

aggrega validate core/datastore/postgres/recipes/helm.yaml --release releases/production.yaml

Veja também

  • ./aggrega-lint.md — a contraparte de convenções nos mesmos três escopos.
  • ./aggrega-build.md — compila um Aggregate + Release completo em artefatos; valida seu fechamento de dependências como parte da compilação.
  • ./aggrega-inspect.md — consultar o grafo IR após a resolução sem prosseguir para a renderização.
  • ../errors/warnings.md — as constatações informativas que validate exibe como linhas notice:.

Sinopse

aggrega validate [entity-path] [flags]

Descrição

Check CORRECTNESS across three symmetric scopes.
With no argument, validate checks the WHOLE catalog: schema-pillar
structure, cross-document library resolution, extends chains, and provider
input-kind capabilities, over every catalog entity. Where the workspace
configuration gives its Releases catalog directories of their own under
workspace.releases, it checks the catalog once for each Release, over the
directories that Release reads, and reports each pass under a line naming
its Releases and those directories; Releases reading the same directories
share one pass.
With --release, validate checks the entities a Release's dependency closure
reaches: closure-scoped pillars, extends, and pre-render authored-value
conformance — the same correctness a build applies, scoped to that Release.
It then evaluates the Recipe and FeatureRecipe assertions against the values
that Release resolves to, as a build does before it renders, and reports a
failing assertion as a build reports it. Nothing is rendered.
With an entity path, validate checks one entity file. The kinds it accepts
as a single-entity target are Component, Feature, Recipe, FeatureRecipe,
Workload and Plugin. A value the kind requires that the file leaves empty is
reported first, as a placeholder still owed: every one is named at once, with
what it takes, read from the kind's own schema. That reading is this scope's
alone; a whole-catalog run, a Release's closure and a build do not apply it.
Each kind then has its schema checked, then the checks its own kind carries:
pillar structure for a Component or Feature; shape for a Workload,
FeatureRecipe or Plugin; and for a Recipe, shape plus an end-to-end compile
against a minimal generated harness, so its resolution, its guards and a
render of its output are all exercised. Where that Recipe's source is one
that has to be fetched, the render is reported as not attempted instead:
validating one entity on its own reads no lockfile, reads and writes no cache
and makes no network request, so the chart or module it names is never
retrieved and there is nothing to render from. A render that stops while the
Recipe's templates read what only a connection or an attached Feature
supplies — anything under .context.inject, .context.uses or .features — is
reported as not attempted too: the generated harness wires no connection and
attaches no Feature, so that render cannot be judged there, and a fault of
the Recipe's own beside such a read is set aside with it. A template that
does not parse and a reference the render refuses still fail. An assertion
that calls fail, the Recipe's own or one its Component declares, is printed
as a warning closed by a sentence saying a Release must satisfy it before a
build can pass, and does not fail the check: the generated harness sets none
of a real Release's values, so it cannot tell an assertion waiting on one from
one that is broken, and a build still halts on it. Any other kind is refused here
today, and the refusal names the scope that checks it instead: a whole-catalog
run reaches an Aggregate and the library kinds when they sit in a catalog
directory, and --release reaches a Release, the Manifest it names and the
Aggregate it deploys.
With an entity path and --release together, the entity is checked in that
Release's terms: its references — the Component a Recipe implements, a
library a pillar refers to — resolve through the catalog directories the
workspace configuration gives that Release rather than the workspace's own,
so a workspace keeping one catalog variant per Release checks an entity
against the variant that Release builds with. The checks are the entity
path's; no closure is validated.
The command writes nothing to disk.

Flags

FlagPadrãoDescrição
--catalog[]Diretório de catálogo; repetível. Cada —catalog <dir> é colocado no início da pilha de busca do catálogo (a primeira correspondência vence): os catalog_dirs do workspace ou, para uma Release à qual a configuração do workspace atribui diretórios próprios em workspace.releases, os dessa Release; a pilha termina com o diretório chamado catalog na raiz do workspace, quando houver um. Uma lista catalog_dirs escrita vazia não lê nenhum catálogo local.
--ir-graphfalseTambém escreve em stdout, como JSON, o grafo IR que esta execução calculou, além de tudo o que este comando já produz. Valores que um autor declarou sensíveis são retidos dele; passe —unredacted para imprimi-los em vez disso. Aplica-se ao escopo —release, o único escopo que resolve uma Release em um grafo. Ele seleciona um DOCUMENTO, enquanto —response-format define quanto do próprio relatório deste comando é escrito; nenhum dos dois afeta o veredito nem o código de saída
--no-unsupported-field-warningsfalseSilencia a classe de avisos de campo não suportado: os avisos que um alvo emite para algo que você escreveu e que ele não consegue respeitar — um campo de Workload que ele não consegue expressar (como faz um alvo de menor fidelidade, como compose), ou uma anotação aggrega.ai/ sobre a qual ele não age para o tipo de entrada do nó. Os outros avisos de renderização continuam aparecendo. Apenas de exibição; não altera a saída renderizada. Aplica-se ao escopo de entidade, o único escopo que renderiza
--plugin—Caminho para um .wasm bruto a ser validado em relação ao seu autorrelato describe() — a verificação de autoria antes da publicação. Sozinho, precisa de —type; com um argumento de entidade Plugin, confronta o binário com o tipo declarado da entidade, a declaração de capacidade, o espelho de comandos e o registro de funções do host.
--release—Caminho para um YAML de Release. Sozinho, valida sobre seu fechamento de dependências resolvido; com um argumento de entidade, verifica essa entidade nos termos da Release, com suas referências resolvidas pelos diretórios de catálogo que a configuração do workspace atribui a essa Release. Um caminho relativo é resolvido em relação ao diretório em que você executa o comando, não à raiz do workspace. Onde esse diretório não está em nenhum workspace e nenhuma raiz é nomeada, um caminho absoluto encontra o workspace a partir da própria pasta da Release
--response-formatdetailedVolume de saída para o escopo —release, o fechamento de uma Release sem argumento de entidade: detailed (padrão) relata cada diagnóstico mais as linhas informativas; concise relata a contagem de diagnósticos e apenas o primeiro diagnóstico. O veredito e o código de saída são idênticos para ambos.
--type—Tipo de plugin para uma verificação —plugin apenas do binário, verificado em relação ao tipo autodeclarado do binário. Só faz sentido com —plugin; quando uma entidade Plugin fornece o tipo, omita-o (um valor divergente causa uma parada).
--unredactedfalseImprime os valores que um autor declarou sensíveis em vez de retê-los. Tudo o que a saída alcança — um terminal, um pipe, um arquivo, uma gravação de tela — passa então a conter esses valores em texto claro. Alcança o grafo que —ir-graph escreve e nada mais, por isso exige —ir-graph