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 lint

aggrega lint verifica as convenções de publicação — nomenclatura, alinhamento entre categoria e diretório, prefixos de anotação, disciplina na escrita de schemas e tamanho do incremento de versão. Ele tem três modos, selecionados pelo seu argumento, que aplicam a mesma disciplina de convenções 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, com um portão de publicação --pre-publish opcional). Cada escopo responde à mesma pergunta — “este conteúdo segue a disciplina de publicação do catálogo?” — sobre uma fatia diferente do catálogo.

Convenções são diferentes de correção. aggrega lint nunca verifica se o conteúdo está bem formado ou se compilaria — isso é papel do aggrega validate, que espelha os mesmos três escopos para schema, pilares, resolução de referências, extends, capacidade do tipo de entrada e renderização. Um seletor de socket ou de slot que a gramática de seletores não consegue ler é uma falha de correção, então lint não informa nada sobre ele: validate o recusa, sobre o catálogo inteiro ou sobre um único Component ou Feature — veja seletores declarados. Os dois comandos são complementares: validate diz se o conteúdo está correto; lint diz se ele é publicável segundo as convenções do catálogo.

aggrega lint é opcional. O próprio compilador permanece sem opiniões próprias sobre a disciplina do catálogo; essas regras ficam em um plugin separado que você escolhe executar. Um workspace que nunca executa aggrega lint continua sendo construído e publicado.

O caminho da entidade pode ser fornecido de forma posicional ou com --entity <path>. --release é mutuamente exclusivo com um argumento de entidade — eles selecionam escopos diferentes; passar ambos causa uma interrupção.

Convenções no catálogo inteiro (sem argumento)

aggrega lint sem argumento executa as regras estruturais de disciplina de publicação sobre cada entidade do catálogo encontrada nos diretórios de catálogo configurados. Os achados são consultivos — informados com severidade warn, eles nunca interrompem a execução apenas por um achado de convenção. Use-o para varrer um catálogo em busca de desvios de nomenclatura, de categoria e diretório e de prefixo de anotação. Um Aggregate, um Manifest, uma Release ou um Workload em um diretório de catálogo é ignorado em vez de verificado: a passagem conta cada um desses tipos em uma linha not checked: após seu resumo e indica a você o modo de entidade, que verifica um documento de qualquer tipo.

Um arquivo YAML sob um diretório de catálogo é um documento Aggrega quando uma de suas linhas começa, sem recuo, com apiVersion: e um valor que começa com aggrega.ai/, entre aspas ou não. Um documento Aggrega que não pode ser lido, cujo YAML não pode ser analisado, ou cujo kind, metadata ou spec 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 foram lidos, nomeando cada um desses arquivos com o motivo que a leitura ou o parser deu; nada passa pelo lint e nenhuma linha conventions checked é impressa. Um que é carregado e declara um kind que nenhum catálogo contém — um Componnent com erro de digitação, por exemplo, ou nenhum kind — interrompe a mesma execução com E0371, 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 do Helm, que só podem ser analisados depois de renderizados, os values de um chart, definições de workflow — é ignorado. --release é interrompido da mesma forma diante de um documento assim sob seus diretórios de catálogo.

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

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

  • 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 uma única passagem por todas leria todas as variantes ao mesmo tempo — com a entidade de uma variante sombreando a de outra. Por isso, ele é verificado uma vez para cada Release que o workspace contém, sobre os diretórios que essa Release lê, com os diretórios --catalog primeiro em cada passagem; uma Release que a configuração não nomeia lê a lista do workspace. Cada passagem é informada sob uma linha que nomeia sua Release e os diretórios que leu, seguida dos achados dessa passagem e do seu próprio resumo:

    Release release-compose.yaml reads catalog-compose
    conventions checked: 7 entities, 0 advisory finding(s)
    Release release-helm-synth.yaml reads catalog-helm-synth
    conventions checked: 8 entities, 0 advisory finding(s)

    Releases que leem exatamente os mesmos diretórios compartilham uma passagem, que nomeia cada uma delas, de modo que um achado ali é informado uma única vez. Uma Release que não lê nenhum diretório — sua entrada escreve catalog_dirs: [] — é informada como não tendo nada a verificar, e as outras passagens são executadas normalmente. Com -o json, o documento também carrega passes: os releases, catalogDirs, findings e summary de cada passagem, enquanto findings e summary de nível superior abrangem todas as passagens juntas. As Releases que um workspace contém são seus documentos de 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 passagem é recusada em vez de ser informada como um catálogo limpo: coloque as entidades em catalog/, passe --catalog ou defina workspace.catalog_dirs — ou, em um workspace que nomeia Releases, o catalog_dirs próprio de uma Release em workspace.releases. Ele nunca enumera implicitamente o diretório de trabalho atual.

Um link sob um diretório de catálogo que leva para fora do workspace — ou para fora de um diretório que você nomeou fora dele — não é lido, e a execução para ali, nomeando o link, em vez de informar como limpo um catálogo do qual não conseguiu ler um dos documentos; um build sobre os mesmos diretórios para no mesmo link. A fronteira do workspace apresenta a regra e suas soluções.

Convenções em uma Release (--release)

aggrega lint --release <release-path> executa as mesmas regras estruturais sobre os arquivos de entidade do catálogo que o fechamento resolvido de uma única Release alcança, em vez do catálogo inteiro ou de uma única entidade. Ele calcula o fechamento com a mesma maquinaria que um build usa e então aplica o lint ao arquivo de catálogo de propriedade do autor de cada entidade. Uma entidade fixada por um registry que reside em um slot do cache não tem nenhum arquivo local para o lint e é ignorada — as regras de publicação se aplicam a arquivos escritos localmente. Assim como no modo de catálogo inteiro, os achados são consultivos e nunca interrompem a execução apenas por um achado de convenção.

Este também é o único escopo que tem em mãos uma Release inteira, então é aqui que são executadas as regras que leem uma — a regra de credenciais de conexão descrita em As regras de disciplina. Uma regra desse tipo é executada uma vez por verificação, depois das regras por entidade, sobre três documentos: o Aggregate que a Release implanta, como seu autor o escreveu; a Release, com sua cadeia extends incorporada, de modo que uma Release filha carregue o que herda; e, para cada componente que o Aggregate declara, o Component do qual esse componente é uma instância, como o catálogo o resolve. Nenhum valor de parâmetro está entre eles, como em todos os escopos: a Release chega sem seu bloco parameters, incluindo os valores que herda de uma base, e o Aggregate sem seus valores padrão nem os valores que passa para cada módulo que importa — veja O que um plugin de linter recebe. Seus achados são informados sob o arquivo da Release.

Esta é a contraparte, em termos de convenções, do aggrega validate --release, que verifica a correção do mesmo fechamento.

Os linters que este escopo executa ficam sujeitos ao registro de identidades de plugins confiáveis ao lado da Release, assim como um build os sujeita. Antes que qualquer um deles seja executado, --release compara as vinculações plugins.linter configuradas com o registro de confiança de plugins: um plugin registrado que a configuração não vincula mais — um linter ou um portão — interrompe a passagem, e um linter lido do cache cujo artefato não é o registrado é recusado em vez de ser executado. Um linter lido do cache também fica sujeito à sua assinatura registrada, quando é carregado: onde sua entrada registra uma assinatura verificada, o material de assinatura que esse fato nomeia no cache é verificado novamente, e a passagem para com E0144 quando ele está ausente ou é diferente, e com E0332 quando foi feito para um plugin diferente do linter lido — 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, uma entrada que não registra nenhuma — ou nenhuma entrada para o linter, incluindo um registro excluído — para a passagem com E0331, sob as mesmas configurações que fariam o aggrega pull recusá-lo por não estar assinado. Cada um dos três nomeia sua solução, aggrega pull --release <release>, que verifica a assinatura do linter no seu 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 linter servido a partir da cópia incluída no binário do compilador nunca fica sujeito ao requisito. Essas são falhas da passagem, não achados de convenção, por isso interrompem a execução onde um achado não o faria. Os escopos de catálogo inteiro e de entidade única não nomeiam nenhuma Release e não leem nenhum registro, então um linter que eles leem do cache é verificado apenas em relação ao seu manifesto em cache. Antes de tudo isso, --release nomeia cada retirada registrada sobre aquilo de que a Release depende, 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 linter ou um portão —, de modo que a passagem o informa mesmo onde uma das recusas acima a interrompe. Uma retirada não muda nenhum achado nem nenhum código de saída, e um registro de confiança que existe e não pode ser lido interrompe a passagem em vez de passar por um que não registra nada.

Disciplina de entidades: local e portão de publicação

O modo de caminho de entidade é executado com uma de duas severidades:

  • Padrão (local). Executa as regras de disciplina sobre o conteúdo local da entidade com severidade warn. Sem acesso ao registry; a verificação do incremento de versão é ignorada. Use-o durante a escrita.
  • --pre-publish (portão de publicação). Busca no registry a versão publicada mais recente da entidade que não seja pré-lançamento, executa as mesmas regras com severidade halt e, além disso, classifica a mudança como PATCH / MINOR / MAJOR e interrompe se o incremento proposto de metadata.version for menor do que a mudança exige. Use-o no fluxo de publicação, antes de aggrega push. --pre-publish se aplica apenas à forma de entidade única.

Um incremento excessivo é sempre permitido; um incremento insuficiente causa uma interrupção. A primeira publicação de uma entidade (sem versão anterior no registry) ignora a verificação do incremento e exibe um aviso informando que nenhuma verificação foi realizada.

Quais tipos o modo de entidade verifica

O modo de entidade aplica o lint ao documento que você nomeia, seja qual for o tipo dele, e o entrega a cada regra que lê uma entidade. Cada regra decide por si mesma quais tipos descreve, e uma regra que recebe um tipo que não descreve não informa nada. Assim, nomear um Aggregate, um Manifest, uma Release ou um Workload — tipos que a passagem sobre o catálogo inteiro ignora e lista na sua linha not checked: — também executa as regras sobre ele, e somente as regras que descrevem esse tipo podem informar algo:

RegraTipos sobre os quais ela informa no modo de entidade
Prefixo de anotaçãoQualquer tipo: ela lê metadata.annotations seja qual for o tipo do documento.
Extensões x-aggrega-* diretasQualquer tipo: ela lê spec.schema seja qual for o tipo do documento.
Formato do nomeComponent, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary e ArtifactLibrary.
A categoria corresponde ao diretórioComponent.
O slot de segredo declara sensitiveComponent e Feature.
A anotação de credencial de métricas corresponde a providesComponent.
Provides declarados pelo ComponentRecipe.
Referências dinâmicas, substituições de IdSchemaLibrary.
Limites padrão do PluginPlugin.
A comparação de incremento de versão (--pre-publish)Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate e Plugin (um plugin embutido no compilador não é comparado); uma alteração em qualquer outro tipo é classificada como MAJOR.
A credencial da conexão corresponde à chave do destinoNenhum: ela lê uma Release inteira, por isso só é executada com --release.

Um Aggregate, um Manifest, uma Release e um Workload não declaram metadata.annotations nem spec.schema em seus schemas, então um documento de um deles que corresponde ao schema do seu tipo não recebe nenhum achado das duas regras que leem qualquer tipo; essas duas só informam sobre ele quando ele traz uma dessas chaves mesmo assim, o que o schema do seu tipo recusa como propriedade inesperada. O que nomear um Aggregate acrescenta é a comparação de incremento de versão sob --pre-publish, que o compara com sua versão publicada como descreve a rubrica abaixo.

A rubrica do incremento de versão

No modo --pre-publish, a mudança é comparada com a versão publicada anterior e classificada:

  • PATCH — mudanças apenas na documentação ou nos comentários.
  • MINOR — mudanças estritamente aditivas (um novo campo opcional, uma nova entrada).
  • MAJOR — remoções, estreitamento de tipos ou um campo antes opcional que se torna obrigatório.

A comparação depende do tipo de entidade: Component, Feature e SchemaLibrary são comparados levando em conta seus campos que contêm schemas; MappingLibrary é comparada no nível da chave de entrada (os corpos das entradas são opacos, então um corpo alterado é tratado de forma conservadora como MAJOR); Recipe e FeatureRecipe são comparadas em seus campos essenciais. Um Aggregate é comparado em suas declarações de parâmetros, seus componentes e seus subsistemas; o valor padrão de um parâmetro não chega à comparação mais do que qualquer outro valor de parâmetro (veja O que um plugin de linter recebe), então uma mudança restrita a um valor padrão — adicioná-lo, alterá-lo ou removê-lo — não faz parte dela, nem uma mudança em uma chave fora do vocabulário de slots de parâmetros. Um incremento insuficiente causa uma interrupção com um diagnóstico que nomeia o incremento exigido.

As regras de disciplina

A maioria das regras tem uma configuração por workspace em lint.publishing_discipline no .aggrega-config.yaml e uma substituição de CLI correspondente, cada substituição com uma contraparte --no-. A precedência é --no-<flag> sobre --<flag> sobre o valor da configuração do workspace, em todos os escopos: o catálogo inteiro, uma Release e uma entidade. Todas as regras ficam ativadas por padrão, e cada padrão se baseia na maquinaria da plataforma ou em uma convenção de catálogo documentada; as configurações são opções de desativação para um workspace que tenha um motivo para relaxar alguma delas.

As regras que não têm nenhuma configuração dizem isso na sua entrada abaixo, e o motivo é o mesmo em cada caso: elas informam um fato sobre a entidade e deixam a decisão com o autor, então não há nenhum julgamento a relaxar. A rubrica do incremento de versão descrita acima também não tem nenhuma — ela compara o conteúdo proposto com a versão publicada e informa o que a mudança exige, o que é uma propriedade da mudança e não uma preferência do workspace.

  • Prefixo de anotação — os namespaces reservados (aggrega.ai/, e feature.aggrega.ai/ fora de uma Feature) pertencem à plataforma e são rejeitados em outras chaves. Ativada por padrão; desative com allow_aggrega_ai_prefix.
  • Forma do nome — cada tipo de entidade tem uma convenção de forma de nome (quantidade de segmentos para os tipos cloud-native; PascalCase para os tipos de biblioteca). Ativada por padrão; desative com allow_nonstandard_names.
  • Referências dinâmicas — as entradas de uma SchemaLibrary não podem usar $dynamicAnchor / $dynamicRef (a expansão de $ref em tempo de compilação da plataforma não consegue resolvê-las). Ativada por padrão; desative com allow_dynamic_refs.
  • Substituições de id — as entradas de uma SchemaLibrary não podem declarar seu próprio $id (a plataforma deriva o $id canônico). Ativada por padrão; desative com allow_id_overrides.
  • A categoria corresponde ao diretório — o rótulo component.aggrega.ai/category de um Component deve corresponder ao primeiro segmento de diretório sob core/, tirado do conjunto fechado de categorias (ai-agent, ai-model, ai-tool, ai-pipeline, datastore, gateway, mesh, network, messaging, storage, compute, observability, security, bigdata, devtool). Ativada por padrão para entidades sob um caminho core/; desative com allow_category_mismatches.
  • Extensões x-aggrega-* diretas — escrever diretamente chaves x-aggrega-* em um schema de Component ou de Feature é desaconselhado em favor do caminho de escrita de primeira classe. Ativada por padrão; desative com allow_direct_x_aggrega_extensions.
  • Provides declarados pelo Component — o spec.provides de uma Recipe publica uma chave por entrada, e o Component que a Recipe implementa declara, no pilar provides do seu spec.schema, quais chaves o tipo expõe. É com essa declaração que uma referência inject from: é verificada, de modo que uma chave que uma Recipe publica sem que o Component a declare é produzida e depois recusada onde um consumidor a liga. Publicar além do contrato declarado é aceito em tempo de build, e é por isso que o achado é consultivo, e não uma rejeição. Ativada por padrão para Recipes; desative com allow_undeclared_recipe_provides.
  • Limites padrão do Plugin — o spec.runtime de um Plugin carrega maxMemoryPages e timeoutMs, os dois limites que o host aplica ao carregar e executar o plugin. Um Plugin que não fixa nenhum dos dois é executado com os padrões da plataforma, o que é um resultado seguro e não um erro, então a regra informa que os padrões estão em vigor e que há limites explícitos disponíveis para fixar. Ativada por padrão para entidades Plugin; não tem nenhuma configuração.
  • O slot de segredo declara a sensibilidade — um slot de vinculação pode fixar, pelo seu seletor de rótulos, o tipo de Feature que o preenche como secret, e pode declarar separadamente sensitive: true para registrar que o que quer que o preencha lida com material secreto. O seletor indica quais preenchimentos são admissíveis; o marcador indica o tratamento. Um slot que fixa o tipo e não declara nenhum marcador deixa esse tratamento para ser deduzido novamente a partir do seletor, em vez de lido diretamente. A regra lê cada slot que uma entidade declara: os do seu próprio bloco de vinculações em spec.featuresSchema e, em um Component, os que cada socket de dependência declara em spec.usesSchema.<socket>.featuresSchema para as conexões que passam por ele — um achado sobre o slot de um socket nomeia o socket além do slot. Ativada por padrão para Components e Features; não tem nenhuma configuração.
  • A credencial da conexão corresponde à chave do destino (connection-credential-matches-target-key) — um servidor que verifica uma chave mantém a chave que verifica em um slot do seu próprio Component, e um chamador apresenta uma chave na conexão pela qual alcança o servidor. Nenhuma das duas pontas vê os anexos da outra, então as duas mantêm uma mesma chave apenas porque seus autores a escrevem nas duas pontas — geralmente fazendo os dois anexos lerem um mesmo parâmetro — e um build nunca as compara. Esta regra compara, e é a única regra que lê uma Release inteira, por isso é executada sob --release e em nenhum outro escopo. Ela encontra as duas pontas pelos nomes que o catálogo padrão lhes dá: a chave do destino é o slot api_key que seu Component declara em spec.featuresSchema, e a do chamador é o slot credential na conexão, escrito em uses.<socket>.<alias>.features.credential no Aggregate ou em uma conexão que a Release conecta. Para cada conexão cujo destino declara api_key e não está rotulado como managed, ela relata uma conexão que leva uma credencial a um destino cujo slot de chave não está preenchido, um slot de chave preenchido sem credencial na conexão, e duas pontas que nomeiam seu segredo de forma diferente. O que ela compara é o localizador de cada ponta — o origin que um anexo escreve, em values no Aggregate ou em infra na Release — tal como o autor o escreveu, de modo que duas pontas que leem um mesmo parâmetro são consideradas iguais e dois literais são comparados pelo seu texto; nada é resolvido, e uma constatação nomeia o componente, a conexão, o destino e os dois slots, mas nunca cita nenhum dos dois localizadores, já que o texto escrito ali pode ser o próprio segredo. Um destino que não declara nenhum slot api_key não produz nada, e um slot que não é a chave do chamador, como o token de pull do registry de um servidor de modelos, nunca é lido. Tampouco é julgado um destino cujo Component está rotulado como component.aggrega.ai/hosting: managed, seja o que for que seu slot api_key contenha: um Component assim representa um serviço que seu fornecedor opera, então nada do que a Release executa verifica uma chave nele, e onde ele declara api_key — a chave de uma API de modelos hospedada, por exemplo, com o nome que o produto do fornecedor lhe dá — o slot contém a chave que a Release apresenta a esse fornecedor, nunca uma que seus chamadores apresentem. Um destino rotulado como self-hosted, external ou mixed, ou sem rótulo de hospedagem, é julgado. Uma conexão no socket scrape_target — o nome que o catálogo padrão dá ao socket pelo qual um scraper de métricas alcança seus destinos — é um scrape, e se a credencial de um scrape deve ser a chave de chamador do destino depende do produto do destino: alguns servem suas métricas sem credencial, alguns as colocam atrás da chave que todo chamador apresenta, e alguns aceitam um token próprio. Então, para um scrape, a regra lê o que o Component do destino declara em sua anotação observability.aggrega.ai/metrics-credential: com none, o scrape não é julgado de forma alguma; com separate-token, sua credencial nunca é comparada com a api_key do destino, então nenhuma das três constatações é relatada sobre ele; com target-key, ele é julgado como qualquer outra conexão. A regra lê apenas esses três valores, então um scrape para um destino sem a anotação, ou com qualquer outro valor, é julgado como qualquer outra conexão — e toda conexão em outro socket, incluindo uma conexão a um modelo, a uma ferramenta ou a um datastore, é julgada da mesma forma, diga o que disser a anotação do destino. Ela lê os anexos escritos no destino e na conexão: um anexo api_key que chega ao destino a partir de um subsistema ou de uma fronteira deixa, em vez disso, essa conexão sem julgamento, um que uma anotação adiciona não está entre eles, então um slot de chave preenchido apenas dessa forma é lido como não preenchido, uma ponta cujo anexo não escreve nenhum localizador é comparada apenas quanto a estar preenchida, e um componente que um módulo importado fornece não é lido. Como os nomes dos slots, o rótulo de hospedagem, o nome do socket de scrape e a anotação de métricas são convenções do catálogo que nenhuma palavra-chave do schema marca, um catálogo que nomeia os slots de outra forma não produz nada, um socket de scraping com outro nome é julgado como qualquer outro socket, e um Component que mantém a chave de um fornecedor em um slot chamado api_key sem o rótulo managed é lido como um destino que verifica essa chave, já que o nome do slot, o rótulo e a anotação são tudo o que a regra lê do Component de um destino. Ativada por padrão; desative com allow_connection_credential_mismatches.
  • A anotação de credencial de métricas corresponde a provides (metrics-credential-annotation-matches-provides) — um Component pode declarar dois fatos sobre suas métricas. Sua anotação observability.aggrega.ai/metrics-credential declara como as métricas do produto se autenticam: none, elas são servidas sem credencial; target-key, elas aceitam a chave que o Component exige de todo chamador, a que seu slot api_key contém; separate-token, elas aceitam um token próprio. A chave provides metrics_credential_required, declarada no pilar provides do seu spec.schema, é o que cada uma das suas Recipes publica para dizer se as métricas de uma instância precisam de uma credencial — o que pode depender de como a instância está configurada, já que métricas atrás da chave do chamador só precisam de uma enquanto uma chave estiver anexada, então a anotação não pode substituí-la. As duas declaram um único fato sobre o produto, então esta regra exige que concordem: um Component anotado com none que declara a chave, e um anotado com target-key ou separate-token que não a declara, são cada um relatados, e a constatação nomeia o Component, o valor da anotação e a chave que sobra ou falta. Um Component sem a anotação, ou com qualquer outro valor, não produz nada. A regra lê o Component tal como está escrito, então um Component que estende outro — cujo schema é o da sua base — não produz nada e sua base é lida onde está declarada, e um pilar provides escrito como referência, como composição ou como corpo escapado escrito como texto não é um que ela consiga enumerar, então esse Component também não produz nada. Ativada por padrão para Components; não tem nenhuma configuração.

A imutabilidade de artefatos não é uma dessas regras, e não tem nenhuma configuração. Um name:version publicado é definitivo: aggrega push compara o digest já publicado naquela tag com o digest que o conteúdo prestes a ser enviado produziria, e se recusa a sobrescrevê-lo com conteúdo diferente. Reenviar conteúdo idêntico byte a byte não envia nada e anexa apenas o que ainda falta àquela publicação — sua data de publicação, e sua assinatura onde o push assina. Nenhum flag e nenhuma configuração do workspace relaxa isso, porque o registry não expõe nenhum caminho de sobrescrita que um operador possa optar por habilitar. Conteúdo alterado é publicado sob uma nova versão; --pre-publish é o que verifica esse incremento em relação à release anterior.

Os flags de substituição por regra valem por invocação e intencionalmente não têm variável de ambiente — eles já são respaldados pela configuração em .aggrega-config.yaml sob lint.publishing_discipline. O modelo geral de precedência AGGREGA_* é descrito em environment-variables.md.

Tempo de build e tempo de publicação

A regra que desaconselha x-aggrega-* também é executada durante aggrega build, onde aparece como aviso; aggrega lint --pre-publish eleva a mesma constatação a erro. Builds locais trazem o aviso; o portão de publicação o impõe.

Enquanto você escreve, no seu editor

Seu editor faz duas perguntas diferentes sobre uma entidade do catálogo, e são as duas com que esta página começa. A entidade está correta — ela é analisada, os pilares se resolvem, ela é renderizada? Isso é aggrega validate, e uma sessão do editor sempre responde a isso. A entidade é publicável — o nome segue a convenção, o arquivo está no diretório que sua categoria espera, os prefixos das anotações estão certos? Isso são estas regras, e uma sessão do editor só responde a isso quando você pede.

Fica desativado a menos que você o ative. Ative-o com serve.lint_on_validate no .aggrega-config.yaml do workspace sobre cujas entidades você quer receber as orientações:

serve:
lint_on_validate: true

Não há nenhum flag de linha de comando para isso, e é deliberado: a pergunta é sobre o conteúdo próprio de um workspace específico, e você é quem escreve esse workspace, não quem inicia o language server — quem faz isso é o seu editor.

Com ele ativado, cada entidade que você valida também traz essas constatações, cada uma nomeando a regra que a produziu, junto com as de correção. Três coisas decorrem disso, e são elas que o tornam utilizável enquanto você digita:

  • As constatações continuam sendo orientações. Uma entidade que quebra uma convenção ainda é validada, e sua Release ainda é resolvida e renderizada. Ativar a configuração adiciona uma camada de orientações; ela nunca faz seu editor se recusar a funcionar.
  • Você consegue distinguir as duas. Cada problema publicado nomeia a camada que o gerou, então um problema de nomenclatura e uma falha de resolução no mesmo arquivo são lidos como duas coisas diferentes em vez de como um único problema relatado duas vezes.
  • O que você digitou é o que é verificado. As regras leem o buffer em vez do arquivo em disco, então um nome que você corrige deixa de ser relatado antes de você salvar.

Apenas o modo de conteúdo local é executado nessa camada: nenhum registry é consultado, nada é buscado, nada é escrito. A comparação --pre-publish é alcançada pedindo-a — seu editor envia uma solicitação para ela, da mesma forma que você digita --pre-publish no terminal — e nunca editando a configuração acima. Uma verificação que é executada toda vez que você toca em um documento é justamente onde um registry não deve ser alcançado, então esse modo continua sendo algo que você invoca em vez de algo que vai junto automaticamente.

Pedir a verificação explicitamente funciona independentemente do que diga a configuração, nos três escopos acima. Então um workspace que nunca ativou a camada por edição ainda pode pedir ao seu editor que percorra o catálogo, o fechamento de uma Release ou uma única entidade — e obter as mesmas constatações que este comando imprime. A configuração decide apenas se a verificação também é executada onde você não a pediu pelo nome.

Os detalhes do protocolo estão distribuídos em duas páginas: o que a solicitação significa e quando enviá-la estão na página aggrega serve da referência, e seus parâmetros e o formato de sua resposta, campo a campo, estão na referência do formato wire.

Escolhendo o linter

As regras são distribuídas como um plugin Wasm padrão de linter de publicação. Como as regras ficam em um plugin e não no compilador, uma empresa pode apontar aggrega lint para outro plugin para impor sua própria disciplina de catálogo sem alterar o compilador.

Um workspace pode anexar mais de um linter sob plugins.linter, e cada anexo é executado: na ordem em que os anexos estão escritos, cada um em sua própria função de entrada, com todas as suas constatações relatadas juntas. É isso que permite a um catálogo manter as regras padrão e adicionar as suas ao lado delas em vez de escolher entre as duas. --plugin é a exceção — ele executa exatamente um artefato a partir de um caminho do sistema de arquivos no lugar dos anexos configurados, o que o torna útil durante o desenvolvimento de uma regra.

Um vínculo nomeia seu plugin com uri:, e function: nomeia uma função de entrada nesse plugin. Uma entrada que nomeia uma function: e nenhum uri: nomeia uma função de nenhum plugin, então a configuração é recusada ao ser lida, sob E0224, nomeando o arquivo e a posição da entrada na sua lista — adicione o uri do plugin que exporta a função. Uma entrada que não nomeia nenhum dos dois não vincula nada e é ignorada; quando é a única entrada, o linter padrão é executado na sua própria função de entrada padrão, como acontece sem nenhum plugins.linter.

O que um plugin de linter recebe

Nenhum valor de parâmetro chega a um plugin de linter, em nenhum escopo. O valor de um parâmetro pode ser ele próprio uma credencial — o origin de um anexo secreto pode ser um template que lê um parâmetro que a Release satisfaz, e o segredo é então o valor desse parâmetro — e o plugin que um workspace anexa pode ser um que ele não escreveu, então cada documento é entregue com seus valores de parâmetros retidos:

  • Um Aggregate mantém cada declaração de parâmetro, conservando apenas as chaves com que uma declaração é escrita — o vocabulário de slots de parâmetro: seu tipo, sua descrição e suas restrições — e cada declaração aninhada sob seus properties, items e valuesType recebe o mesmo tratamento. O default da declaração é retido em todos os níveis, removendo a chave em vez de esvaziá-la, então um plugin não consegue saber se uma declaração fornece um. Uma chave fora desse vocabulário é retida com tudo o que contém, em todos os níveis: o build não dá nenhum significado a uma chave assim, e um rascunho que escreve uma chave errado pode levar um segredo sob ela. Uma entrada sob parameters que não é uma declaração é retida por inteiro.
  • Cada módulo listado sob aggregates de um Aggregate perde seu bloco parameters, que contém os valores passados a esse módulo.
  • Uma Release perde seu bloco parameters, quer escreva os valores inline, quer os importe com $import.
  • Qualquer outro documento que tenha um bloco parameters sob spec o perde por inteiro; nenhum outro tipo declara um.

Isso vale para a entidade nomeada na linha de comando, para a versão publicada com a qual --pre-publish a compara, para cada entidade que as passagens sobre o catálogo inteiro e com --release percorrem, e para os documentos que uma regra que lê uma Release inteira recebe. Um template que lê um parâmetro não é um valor e mantém seu texto, então uma regra ainda vê qual parâmetro um valor escrito pelo autor lê.

Exemplos

Percorrer o catálogo inteiro em busca de desvios das convenções:

aggrega lint --catalog ./catalog

Executar o lint de uma entidade localmente enquanto você a escreve:

aggrega lint core/datastore/postgres/component.yaml

Executar o portão de publicação antes de publicar uma nova versão:

aggrega lint core/datastore/postgres/component.yaml --pre-publish

Relaxar uma regra para uma única execução:

aggrega lint core/datastore/postgres/component.yaml --pre-publish --allow-nonstandard-names

Veja também

  • ./aggrega-validate.md — a contraparte de correção nos mesmos três escopos.
  • ./aggrega-build.md — valida como parte da compilação; exibe o aviso de x-aggrega-* com severidade warn.
  • ./aggrega-push.md — publica uma entidade no registry; aggrega lint --pre-publish é o portão que o precede.
  • ./aggrega-pull.md — resolve e fixa dependências.
  • ./aggrega-serve.md — o language server que relata essas constatações no seu editor, e a configuração que ativa a camada por edição.
  • ../errors/warnings.md — avisos não fatais, incluindo as constatações de lint no modo local.

Sinopse

aggrega lint [entity-path] [flags]

Descrição

aggrega lint checks publishing CONVENTIONS — naming, category-directory
alignment, annotation prefixes, and the rest of the publishing-linter
discipline. It does not check correctness (schema, pillars, resolution,
render): that is aggrega validate.
Three invocation shapes, mirroring validate:
aggrega lint conventions across every catalog entity
aggrega lint --release <path> conventions across a Release's dependency closure
aggrega lint <entity> publishing discipline for one entity
Without an entity argument, lint runs the structural conventions rules
over every catalog entity found under the catalog directories. Where the
workspace configuration gives its Releases catalog directories of their own
under workspace.releases, it runs them 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 it runs them over the entities that
Release's closure reaches, and also runs the rules that read a whole
Release: once, over the Aggregate it deploys, the Release and the
Components the Aggregate's components are instances of, with every
parameter value removed. In both, findings are advisory (warn severity)
and never halt.
With an entity path, lint runs the publishing-linter rule set against
that one entity. In default mode the rules run at warn severity over
local content without consulting any registry. With --pre-publish the
previous registry version is fetched and the schema-evolution
classification is compared against the proposed version bump; mismatches
halt. --pre-publish applies to the single-entity shape only. Per-workspace
policy flags from .aggrega-config.yaml's lint.publishing_discipline block
can be overridden per invocation via the --allow-*/--no-allow-* flag pairs,
in all three shapes.
All three shapes accept -o json, which replaces the human report on standard
output with one structured document: every finding with its severity, the rule
that produced it, its short code (the code printed at the head of its row in
the human report, which aggrega explain expands), its message, and the entity
file it concerns, plus counts by severity. A finding from a rule Aggrega does
not declare, one a linter of your own adds, carries no short code, as its row
prints none. A finding carries a line and column only when the rule that
produced it located the issue that precisely; otherwise the file alone locates
it. The message is the rule's own text, carried through unchanged, so the
structured and human renderings never word a finding differently. The exit
status is the same under either format.

Flags

FlagPadrãoDescrição
--allow-aggrega-ai-prefixfalseForça allow_aggrega_ai_prefix=true
--allow-category-mismatchesfalseForça allow_category_mismatches=true
--allow-connection-credential-mismatchesfalseForça allow_connection_credential_mismatches=true
--allow-direct-x-aggrega-extensionsfalseForça allow_direct_x_aggrega_extensions=true
--allow-dynamic-refsfalseForça allow_dynamic_refs=true para esta invocação
--allow-id-overridesfalseForça allow_id_overrides=true para esta invocação
--allow-nonstandard-namesfalseForça allow_nonstandard_names=true
--allow-undeclared-recipe-providesfalseForça allow_undeclared_recipe_provides=true
--baseline—Compara a verificação de evolução pré-publicação com esta versão específica já publicada em vez da versão mais alta selecionada automaticamente abaixo da que está sendo publicada; deve ser uma tag SemVer estrita presente no registry (requer —pre-publish)
--catalog[]Diretório de catálogo; repetível. Cada —catalog <dir> é adicionado no início da pilha de busca de catálogos (a primeira correspondência vence): os catalog_dirs do workspace ou, para uma Release à qual a configuração do workspace dá diretórios próprios sob workspace.releases, os dessa Release; a pilha termina com o diretório chamado catalog na raiz do workspace, quando existe um. Uma lista catalog_dirs escrita vazia não lê nenhum catálogo local. Usado pelas passagens de convenções sobre o catálogo inteiro e com —release.
--entity—Caminho para o YAML da entidade a ser analisada pelo lint (como alternativa, passe-o como argumento posicional)
--no-allow-aggrega-ai-prefixfalseForça allow_aggrega_ai_prefix=false
--no-allow-category-mismatchesfalseForça allow_category_mismatches=false
--no-allow-connection-credential-mismatchesfalseForça allow_connection_credential_mismatches=false
--no-allow-direct-x-aggrega-extensionsfalseForça allow_direct_x_aggrega_extensions=false
--no-allow-dynamic-refsfalseForça allow_dynamic_refs=false para esta invocação
--no-allow-id-overridesfalseForça allow_id_overrides=false para esta invocação
--no-allow-nonstandard-namesfalseForça allow_nonstandard_names=false
--no-allow-undeclared-recipe-providesfalseForça allow_undeclared_recipe_provides=false
--output, -otextFormato de saída: text|json.
--plugin—Caminho no sistema de arquivos para o artefato .wasm do linter de publicação (executa este artefato em vez dos anexos plugins.linter do workspace)
--pre-publishfalseBusca a versão anterior no registry e verifica o incremento proposto em relação à classificação de evolução do schema
--release—Caminho para um YAML de Release cujas convenções são verificadas sobre o fechamento das suas dependências resolvidas (mutuamente exclusivo com um argumento de entidade). Um caminho relativo é resolvido em relação ao diretório em que você executa o comando, não em relação à raiz do workspace. Quando esse diretório não está em nenhum workspace e nenhuma raiz é indicada, um caminho absoluto encontra o workspace a partir da própria pasta da Release