Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler 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ções, disciplina de autoria de esquemas e dimensão do incremento de versão. Tem três modos, selecionados pelo seu argumento, que aplicam a mesma disciplina de convenções em três âmbitos: o catálogo completo (sem argumento), o fecho de dependências de uma única Release (--release) e um ficheiro de entidade (um caminho de entidade, com um controlo de publicação --pre-publish opcional). Cada âmbito responde à mesma pergunta — «este conteúdo segue a disciplina de publicação do catálogo?» — sobre uma parte diferente do catálogo.

As convenções são distintas da correção. aggrega lint nunca verifica se o conteúdo está bem formado ou se compilaria — isso cabe a aggrega validate, que reproduz os mesmos três âmbitos para o esquema, os pilares, a resolução de referências, extends, a capacidade dos tipos de entrada e a renderização. Um seletor de socket ou de slot que a gramática de seletores não consegue ler é uma falha de correção, pelo que lint nada reporta sobre ele: validate recusa-o, sobre todo o catálogo ou sobre um Component ou uma Feature — consulte seletores declarados. Os dois comandos são complementares: validate indica se o conteúdo está correto; lint indica se é publicável segundo as convenções do catálogo.

aggrega lint é opcional. O próprio compilador mantém-se sem opiniões próprias quanto à disciplina do catálogo; estas regras vivem num plugin separado que se escolhe executar. Um espaço de trabalho que nunca executa aggrega lint continua a compilar e a publicar.

O caminho da entidade pode ser dado como argumento posicional ou com --entity <path>. --release é mutuamente exclusiva com um argumento de entidade — selecionam âmbitos diferentes; passar ambos faz parar.

Convenções do catálogo completo (sem argumento)

aggrega lint sem argumento executa as regras estruturais de disciplina de publicação sobre todas as entidades de catálogo encontradas nos diretórios de catálogo configurados. As conclusões são consultivas — reportadas com a severidade warn, nunca fazem parar apenas por uma conclusão de convenção. Use-o para percorrer um catálogo à procura de desvios de nomenclatura, de diretório de categoria e de prefixo de anotações. Um Aggregate, um Manifest, uma Release ou um Workload num diretório de catálogo é ignorado em vez de verificado: a passagem contabiliza cada um desses tipos numa linha not checked: a seguir ao seu resumo e remete para o modo de entidade, que verifica um documento de qualquer tipo.

Um ficheiro YAML sob um diretório de catálogo é um documento Aggrega quando uma das suas linhas começa, sem indentação, por apiVersion: e um valor que começa por 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 invólucro de uma entidade assume — um metadata escrito como lista, por exemplo — interrompe a execução com E0175 depois de lidos os diretórios, nomeando cada um desses ficheiros com o motivo que a leitura ou o analisador deu; nada passa pelo lint e não é impressa nenhuma linha conventions checked. Um que é carregado e declara um kind que nenhum catálogo contém — um Componnent mal escrito, 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 interrompe-se da mesma forma perante um documento destes sob os seus diretórios de catálogo.

Os diretórios que lê dependem da forma do espaço de trabalho:

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

  • Um espaço de trabalho 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 sobre todas elas leria todas as variantes ao mesmo tempo — com a entidade de uma variante a ocultar a de outra. Por isso, é verificado uma vez por cada Release que o espaço de trabalho contém, sobre os diretórios que essa Release lê, com os diretórios --catalog em primeiro lugar em cada passagem; uma Release que a configuração não nomeia lê a lista do espaço de trabalho. Cada passagem é reportada sob uma linha que nomeia a sua Release e os diretórios que leu, seguida das conclusões 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)

    As Releases que leem exatamente os mesmos diretórios partilham uma passagem, que nomeia cada uma delas, pelo que uma conclusão aí é reportada uma vez. Uma Release que não lê nenhum diretório — a sua entrada escreve catalog_dirs: [] — é reportada como não tendo nada a verificar, e as outras passagens são executadas normalmente. Com -o json, o documento contém também passes: os releases, catalogDirs, findings e summary de cada passagem, enquanto os findings e summary de nível superior abrangem todas as passagens em conjunto. As Releases que um espaço de trabalho contém são os seus documentos de Release — ficheiros YAML cujo kind é Release, em qualquer local sob a raiz do espaço de trabalho, fora dos diretórios ocultos e de node_modules, vendor e dist.

Uma execução sem nada para ler em nenhuma passagem é recusada em vez de reportada como um catálogo limpo: coloque as entidades em catalog/, passe --catalog ou defina workspace.catalog_dirs — ou, num espaço de trabalho que nomeia Releases, os catalog_dirs próprios de uma Release em workspace.releases. Nunca enumera implicitamente o diretório de trabalho atual.

Uma ligação sob um diretório de catálogo que sai do espaço de trabalho — ou de um diretório nomeado fora dele — não é lida, e a execução para aí, nomeando a ligação, em vez de reportar como limpo um catálogo com um documento que não conseguiu ler; uma compilação sobre os mesmos diretórios para na mesma ligação. A fronteira do espaço de trabalho enuncia a regra e as suas soluções.

Convenções numa Release (--release)

aggrega lint --release <release-path> executa as mesmas regras estruturais sobre os ficheiros de entidade de catálogo que o fecho resolvido de uma única Release alcança, em vez do catálogo completo ou de uma entidade. Calcula o fecho através do mesmo mecanismo que uma compilação usa e depois aplica o lint ao ficheiro de catálogo de cada entidade pertencente ao autor. Uma entidade fixada a partir de um registo e guardada numa posição da cache não tem nenhum ficheiro local a verificar e é ignorada — as regras de publicação aplicam-se a ficheiros escritos localmente. Tal como no modo de catálogo completo, as conclusões são consultivas e nunca fazem parar apenas por uma conclusão de convenção.

É também o único âmbito que tem uma Release completa à mão, pelo que é aí que são executadas as regras que leem uma — a regra de credenciais de ligação descrita em As regras de disciplina. Uma regra destas é executada uma vez por verificação, depois das regras por entidade, sobre três documentos: o Aggregate que a Release implementa, tal como o seu autor o escreveu; a Release, com a sua cadeia extends incorporada, para que uma Release filha contenha o que herda; e, para cada componente que o Aggregate declara, o Component de que esse componente é instância, tal como o catálogo o resolve. Nenhum valor de parâmetro está entre eles, como em todos os âmbitos: a Release chega sem o seu bloco parameters, incluindo os valores que herda de uma base, e o Aggregate sem as suas predefinições nem os valores que passa a cada módulo que importa — consulte O que é entregue a um plugin de linter. As suas conclusões são reportadas sob o ficheiro da Release.

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

Os linters que este âmbito executa são confrontados com o registo de identidades de plugins de confiança ao lado da Release, tal como uma compilação os confronta. Antes de qualquer um deles ser executado, --release compara as anexações plugins.linter configuradas com o registo de confiança dos plugins: um plugin registado que a configuração já não anexa — um linter ou um controlo — faz parar a passagem, e um linter lido a partir da cache cujo artefacto não é o registado é recusado em vez de executado. Um linter lido a partir da cache é também confrontado com a sua assinatura registada quando é carregado: quando a sua entrada regista uma assinatura verificada, o material de assinatura que esse facto nomeia na cache é verificado novamente, e a passagem para com E0144 quando está em falta 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; quando a configuração de confiança do espaço de trabalho exige uma assinatura, uma entrada que não regista nenhuma — ou a ausência de entrada para o linter, incluindo um registo eliminado — para a passagem com E0331, nas mesmas definições que levariam aggrega pull a recusá-lo sem assinatura. Cada uma das três nomeia a sua solução, aggrega pull --release <release>, que verifica a assinatura do linter no seu registo, a regista e coloca em cache o pacote que ela nomeia, reescrevendo uma cópia em cache que já não corresponda ao seu digest. Um linter servido a partir da cópia incluída no binário do compilador nunca é sujeito ao requisito. Estas são falhas da passagem, não conclusões de convenção, pelo que fazem parar onde uma conclusão não o faria. Os âmbitos de catálogo completo e de entidade única não nomeiam nenhuma Release e não leem nenhum registo, pelo que um linter que leiam a partir da cache é verificado apenas contra o seu manifesto em cache. Antes de tudo isso, --release nomeia todas as retiradas registadas contra aquilo de que a Release depende, como uma linha deprecation: nas palavras que aggrega build imprime — tanto um marcador que o lockfile regista contra uma referência fixada como um que o registo de confiança regista contra um linter ou um controlo —, pelo que a passagem o indica mesmo quando uma das recusas acima a faz parar. Uma retirada não altera nenhuma conclusão nem nenhum código de saída, e um registo de confiança que existe e não pode ser lido faz parar a passagem em vez de passar por um que não regista nada.

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

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

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

Um incremento excessivo é sempre permitido; um incremento insuficiente faz parar. A primeira publicação de uma entidade (sem versão anterior no registo) ignora a verificação do incremento e apresenta um aviso a indicar que não foi efetuada nenhuma verificação.

Que tipos o modo de entidade verifica

O modo de entidade aplica o lint ao documento que indicar, qualquer que seja o seu tipo, e entrega-o a todas as regras que leem uma entidade. Cada regra decide por si que tipos descreve, e uma regra que recebe um tipo que não descreve nada reporta. Assim, indicar um Aggregate, um Manifest, uma Release ou um Workload — tipos que a passagem sobre todo o catálogo ignora e lista na sua linha not checked: — também executa as regras sobre ele, e só as regras que descrevem esse tipo podem reportar:

RegraTipos sobre os quais reporta no modo de entidade
Prefixo de anotaçãoQualquer tipo: lê metadata.annotations qualquer que seja o tipo do documento.
Extensões x-aggrega-* diretasQualquer tipo: lê spec.schema qualquer que seja o tipo do documento.
Forma 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 predefinidos do PluginPlugin.
A comparação de incremento de versão (--pre-publish)Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate e Plugin (um plugin incorporado no compilador não é comparado); uma alteração a qualquer outro tipo é classificada como MAJOR.
A credencial da conexão corresponde à chave do destinoNenhum: lê uma Release inteira, pelo que só é executada com --release.

Um Aggregate, um Manifest, uma Release e um Workload não declaram metadata.annotations nem spec.schema nos seus esquemas, pelo que um documento de um deles que corresponda ao esquema do seu tipo não suscita nenhuma conclusão das duas regras que leem qualquer tipo; essas duas só reportam sobre ele quando contém mesmo assim uma das chaves, o que o esquema do seu tipo recusa como propriedade inesperada. O que indicar um Aggregate acrescenta é a comparação de incremento de versão com --pre-publish, que o compara com a sua versão publicada como descreve a rubrica abaixo.

A grelha de incremento de versão

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

  • PATCH — alterações apenas de documentação ou de comentários.
  • MINOR — alterações estritamente aditivas (um novo campo opcional, uma nova entrada).
  • MAJOR — remoções, restrição de tipos ou um campo anteriormente opcional que passa a ser obrigatório.

A comparação é feita por tipo de entidade: Component, Feature e SchemaLibrary são comparados tendo em conta os seus campos que contêm esquemas; MappingLibrary é comparada ao nível das chaves de entrada (os corpos das entradas são opacos, pelo que um corpo alterado é tratado de forma conservadora como MAJOR); Recipe e FeatureRecipe são comparadas nos seus campos determinantes. Um Aggregate é comparado nas suas declarações de parâmetros, nos seus componentes e nos seus subsistemas; a predefinição de um parâmetro não chega à comparação, tal como nenhum outro valor de parâmetro (consulte O que é entregue a um plugin de linter), pelo que uma alteração limitada a uma predefinição — acrescentá-la, alterá-la ou removê-la — não faz parte dela, nem uma alteração a uma chave fora do vocabulário de posições de parâmetros. Um incremento insuficiente faz parar com um diagnóstico que nomeia o incremento exigido.

As regras de disciplina

A maioria das regras tem uma definição por espaço de trabalho em lint.publishing_discipline em .aggrega-config.yaml e uma substituição correspondente na CLI, cada substituição com uma contrapartida --no-. A precedência é --no-<flag> sobre --<flag> sobre o valor da configuração do espaço de trabalho, em todos os âmbitos: o catálogo completo, uma Release e uma entidade. Todas as regras estão ativas por predefinição, e cada predefinição assenta no mecanismo da plataforma ou numa convenção documentada do catálogo; as definições são opções de exclusão para um espaço de trabalho que tenha uma razão para relaxar uma delas.

As regras que não têm definição indicam-no na sua entrada abaixo, e a razão é a mesma em todos os casos: reportam um facto sobre a entidade e deixam a decisão ao autor, pelo que não há nenhum juízo a relaxar. A grelha de incremento de versão descrita acima também não tem nenhuma — compara o conteúdo proposto com a versão publicada e reporta o que a alteração exige, o que é uma propriedade da alteração e não uma preferência do espaço de trabalho.

  • Prefixo de anotações — os espaços de nomes reservados (aggrega.ai/ e feature.aggrega.ai/ fora de uma Feature) pertencem à plataforma e são rejeitados noutras chaves. Ativa por predefinição; exclua-a com allow_aggrega_ai_prefix.
  • Forma do nome — cada tipo de entidade tem uma convenção de forma de nome (número de segmentos para os tipos cloud-native; PascalCase para os tipos de biblioteca). Ativa por predefinição; exclua-a 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 as consegue resolver). Ativa por predefinição; exclua-a com allow_dynamic_refs.
  • Substituições de id — as entradas de uma SchemaLibrary não podem declarar o seu próprio $id (a plataforma deriva o $id canónico). Ativa por predefinição; exclua-a com allow_id_overrides.
  • A categoria corresponde ao diretório — a etiqueta component.aggrega.ai/category de um Component tem de corresponder ao primeiro segmento de diretório sob core/, retirado do conjunto fechado de categorias (ai-agent, ai-model, ai-tool, ai-pipeline, datastore, gateway, mesh, network, messaging, storage, compute, observability, security, bigdata, devtool). Ativa por predefinição para entidades sob um caminho core/; exclua-a com allow_category_mismatches.
  • Extensões x-aggrega-* diretas — escrever diretamente chaves x-aggrega-* num esquema de Component ou de Feature é desaconselhado em favor do caminho de autoria de primeira classe. Ativa por predefinição; exclua-a 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, que chaves o tipo expõe. É com essa declaração que uma referência inject from: é verificada, pelo que uma chave que uma Recipe publica sem que o Component a declare é produzida e depois recusada onde um consumidor a liga. Publicar para além do contrato declarado é aceite no momento da compilação, e é por isso que a conclusão é consultiva e não uma rejeição. Ativa por predefinição para Recipes; exclua-a com allow_undeclared_recipe_provides.
  • Limites predefinidos de Plugin — o spec.runtime de um Plugin contém maxMemoryPages e timeoutMs, os dois limites que o anfitrião aplica quando carrega e executa o plugin. Um Plugin que não fixa nenhum deles é executado com as predefinições da plataforma, o que é um resultado seguro e não um erro, pelo que a regra reporta que as predefinições estão em vigor e que há limites explícitos disponíveis para fixar. Ativa por predefinição para entidades Plugin; não tem definição.
  • Uma posição de segredo declara sensibilidade — uma posição de anexação pode fixar, através do seu seletor de etiquetas, o tipo de Feature que a preenche como secret, e pode declarar separadamente sensitive: true para registar que aquilo que a preencher lida com material secreto. O seletor indica que preenchimentos são admissíveis; o marcador indica o tratamento. Uma posição que fixa o tipo e não declara nenhum marcador deixa esse tratamento para ser deduzido de novo a partir do seletor em vez de lido diretamente. A regra lê todas as posições que uma entidade declara: as do seu próprio bloco de anexações em spec.featuresSchema e, num Component, as que cada socket de dependência declara em spec.usesSchema.<socket>.featuresSchema para as ligações estabelecidas através dele — uma conclusão sobre a posição de um socket nomeia o socket bem como a posição. Ativa por predefinição para Components e Features; não tem definição.
  • A credencial da ligação corresponde à chave do alvo (connection-credential-matches-target-key) — um servidor que verifica uma chave guarda a chave que verifica numa posição do seu próprio Component, e um chamador apresenta uma chave na ligação através da qual chega ao servidor. Nenhuma das extremidades vê as anexações da outra, pelo que as duas só contêm uma mesma chave porque os seus autores a escrevem em ambas as extremidades — normalmente fazendo com que ambas as anexações leiam um mesmo parâmetro — e uma compilação nunca as compara. Esta regra compara-as, e é a única regra que lê uma Release completa, pelo que é executada com --release e em nenhum outro âmbito. Encontra ambas as extremidades pelos nomes que o catálogo padrão lhes dá: a chave do alvo é a posição api_key que o seu Component declara em spec.featuresSchema, e a do chamador é a posição credential na ligação, escrita em uses.<socket>.<alias>.features.credential no Aggregate ou numa ligação que a Release estabelece. Para cada ligação cujo alvo declara api_key e não está etiquetado como gerido, reporta uma ligação que transporta uma credencial para um alvo cuja posição de chave não está preenchida, uma posição de chave preenchida sem credencial na ligação, e duas extremidades que nomeiam o seu segredo de forma diferente. O que compara é o localizador de cada extremidade — a origin que uma anexação escreve, em values no Aggregate ou em infra na Release — tal como o autor o escreveu, pelo que duas extremidades que leem um mesmo parâmetro são iguais e dois literais são comparados pelo seu texto; nada é resolvido, e uma conclusão nomeia o componente, a ligação, o alvo e as duas posições, mas nunca cita nenhum dos localizadores, já que o texto aí escrito pode ser o próprio segredo. Um alvo que não declara nenhuma posição api_key não origina nada, e uma posição que não seja a chave do chamador, como o token de pull de registo de um servidor de modelos, nunca é lida. Também não é avaliado um alvo cujo Component esteja etiquetado component.aggrega.ai/hosting: managed, seja o que for que a sua posição api_key contenha: um Component destes representa um serviço que o seu fornecedor executa, pelo que nada do que a Release executa verifica uma chave nele, e quando declara api_key — a chave de uma API de modelos alojada, por exemplo, sob o nome que o produto do fornecedor lhe dá — a posição contém a chave que a Release apresenta a esse fornecedor, nunca uma que os seus chamadores apresentem. Um alvo etiquetado self-hosted, external ou mixed, ou sem etiqueta de alojamento, é avaliado. Uma ligação no socket scrape_target — o nome que o catálogo padrão dá ao socket através do qual um recolhedor de métricas chega aos seus alvos — é uma recolha, e se a credencial de uma recolha deve ser a chave de chamador do alvo depende do produto do alvo: alguns servem as suas métricas sem credencial, alguns colocam-nas por detrás da chave que todos os chamadores apresentam e alguns usam um token próprio. Por isso, para uma recolha, a regra lê o que o Component do alvo declara na sua anotação observability.aggrega.ai/metrics-credential: com none, a recolha não é de todo avaliada; com separate-token, a sua credencial nunca é comparada com a api_key do alvo, pelo que nenhuma das três conclusões é reportada sobre ela; com target-key, é avaliada como qualquer outra ligação. A regra lê apenas esses três valores, pelo que uma recolha para um alvo sem a anotação, ou com qualquer outro valor, é avaliada como qualquer outra ligação — e todas as ligações noutro socket, incluindo uma ligação a um modelo, a uma ferramenta ou a um repositório de dados, são avaliadas da mesma forma, seja o que for que a anotação do alvo diga. Lê as anexações escritas no alvo e na ligação: uma anexação api_key que chegue ao alvo a partir de um subsistema ou de uma fronteira deixa essa ligação por avaliar, uma que uma anotação acrescente não está entre elas, pelo que uma posição de chave preenchida apenas dessa forma é lida como não preenchida, uma extremidade cuja anexação não escreve nenhum localizador só é comparada quanto a estar ou não preenchida, e um componente com que um módulo importado contribui não é lido. Como os nomes das posições, a etiqueta de alojamento, o nome do socket de recolha e a anotação de métricas são convenções do catálogo que nenhuma palavra-chave de esquema marca, um catálogo que nomeie as posições de forma diferente não origina nada, um socket de recolha com outro nome é avaliado como qualquer outro socket, e um Component que guarde a chave de um fornecedor numa posição chamada api_key sem a etiqueta de gerido é lido como um alvo que verifica essa chave, já que o nome da posição, a etiqueta e a anotação são tudo o que a regra lê do Component de um alvo. Ativa por predefinição; exclua-a com allow_connection_credential_mismatches.
  • A anotação de credencial de métricas corresponde aos provides (metrics-credential-annotation-matches-provides) — um Component pode declarar dois factos sobre as suas métricas. A sua anotação observability.aggrega.ai/metrics-credential declara como as métricas do produto se autenticam: none, são servidas sem credencial; target-key, usam a chave que o Component exige a todos os chamadores, aquela que a sua posição api_key contém; separate-token, usam um token próprio. A chave de provides metrics_credential_required, declarada no pilar provides do seu spec.schema, é o que cada uma das suas Recipes publica para indicar se as métricas de uma instância precisam de credencial — o que pode depender da forma como a instância está configurada, já que as métricas por detrás da chave de chamador só precisam de uma enquanto houver uma chave anexada, pelo que a anotação não a pode substituir. Os dois declaram um mesmo facto sobre o produto, pelo que esta regra exige que concordem: um Component anotado com none que declare a chave, e um anotado com target-key ou separate-token que não a declare, são cada um reportados, e a conclusão nomeia o Component, o valor da anotação e a chave que está a mais ou em falta. Um Component sem a anotação, ou com qualquer outro valor, não origina nada. Lê o Component tal como foi escrito, pelo que um Component que estende outro — cujo esquema é o da sua base — não origina nada e a sua base é lida onde é declarada, e um pilar provides escrito como referência, composição ou corpo escapado escrito como texto não é um que consiga enumerar, pelo que esse Component também não origina nada. Ativa por predefinição para Components; não tem definição.

A imutabilidade dos artefactos não é uma destas regras e não tem definição. Um name:version publicado é definitivo: aggrega push compara o digest já publicado nessa tag com o digest que o conteúdo prestes a ser enviado produziria, e recusa substituí-lo por conteúdo diferente. Voltar a enviar conteúdo idêntico byte a byte não carrega nada e só anexa o que ainda falte a essa publicação — a sua data de publicação e, quando o push assina, a sua assinatura. Nenhuma flag e nenhuma definição da configuração do espaço de trabalho relaxa isto, porque o registo não expõe nenhuma via de substituição que um operador possa ativar. O conteúdo alterado é publicado sob uma nova versão; --pre-publish é o que verifica esse incremento em relação à versão anterior.

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

Momento da compilação e momento da publicação

A regra que desaconselha x-aggrega-* também é executada durante aggrega build, onde surge como aviso; aggrega lint --pre-publish eleva a mesma conclusão a erro. As compilações locais mostram o aviso; o controlo de publicação aplica-o.

Durante a autoria, no editor

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

Está desativado a menos que seja ativado. Ative-o com serve.lint_on_validate no .aggrega-config.yaml do espaço de trabalho sobre cujas entidades se pretende o conselho:

serve:
lint_on_validate: true

Não há nenhuma flag de linha de comandos para isso, e é deliberado: a pergunta diz respeito ao próprio conteúdo de um espaço de trabalho específico, e o utilizador é quem escreve nesse espaço de trabalho e não quem lança o servidor de linguagem — é o editor que o faz.

Com ele ativo, cada entidade validada contém também estas conclusões, cada uma a nomear a regra que a produziu, ao lado das de correção. Daí decorrem três coisas, e são elas que o tornam utilizável durante a escrita:

  • As conclusões continuam a ser consultivas. Uma entidade que viola uma convenção continua a ser validada, e a sua Release continua a ser resolvida e renderizada. Ativar a definição acrescenta uma camada de conselho; nunca faz o editor recusar-se a funcionar.
  • É possível distinguir as duas. Cada problema publicado nomeia a camada que o gerou, pelo que um problema de nomenclatura e uma falha de resolução no mesmo ficheiro são lidos como duas coisas diferentes e não como um único problema reportado duas vezes.
  • O que foi escrito é o que é verificado. As regras leem o buffer e não o ficheiro em disco, pelo que um nome corrigido deixa de ser reportado antes de se guardar.

Só o modo de conteúdo local é executado nessa camada: nenhum registo é consultado, nada é obtido, nada é escrito. A comparação de --pre-publish é obtida pedindo-a — o editor envia um pedido para ela, da mesma forma que se escreve --pre-publish no terminal — e nunca editando a definição acima. Uma verificação que é executada sempre que se toca num documento é precisamente onde um registo não pode ser contactado, pelo que esse modo continua a ser algo que se invoca e não algo que vem por arrasto.

Pedir a verificação diretamente funciona seja qual for a definição, nos três âmbitos acima. Assim, um espaço de trabalho que nunca ativou a camada por edição pode continuar a pedir ao seu editor que percorra o catálogo, o fecho de uma Release ou uma entidade — e obter as mesmas conclusões que este comando imprime. A definição decide apenas se a verificação também é executada onde não foi pedida pelo nome.

Os detalhes do protocolo estão repartidos por duas páginas: o que o pedido significa e quando o enviar estão em a referência de aggrega serve, e os seus parâmetros e a forma da sua resposta, campo a campo, estão em a referência da forma de transmissão.

Escolher o linter

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

Um espaço de trabalho pode anexar mais do que um linter em plugins.linter, e todas as anexações são executadas: pela ordem em que as anexações estão escritas, cada uma na sua própria função de entrada, com todas as suas conclusões reportadas em conjunto. É isso que permite a um catálogo manter as regras padrão e acrescentar as suas ao lado delas em vez de escolher entre as duas. --plugin é a exceção — executa exatamente um artefacto a partir de um caminho no sistema de ficheiros em vez das anexações configuradas, o que a torna útil durante o desenvolvimento de uma regra.

Uma anexação nomeia o 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, pelo que a configuração é recusada ao ser lida, com E0224, nomeando o ficheiro e a posição da entrada na sua lista — acrescente o uri do plugin que exporta a função. Uma entrada que não nomeia nenhum dos dois não anexa nada e é ignorada; quando é a única entrada, o linter padrão é executado na sua própria função de entrada predefinida, tal como sem nenhum plugins.linter.

O que é entregue a um plugin de linter

Nenhum valor de parâmetro chega a um plugin de linter, em nenhum âmbito. O valor de um parâmetro pode ser ele próprio uma credencial — a origin de uma anexação de segredo pode ser um template que lê um parâmetro que a Release preenche, e o segredo é então o valor desse parâmetro — e o plugin que um espaço de trabalho anexa pode ser um que não escreveu, pelo que cada documento é entregue com os seus valores de parâmetros ocultados:

  • Um Aggregate mantém cada declaração de parâmetro, contendo apenas as chaves com que uma declaração é escrita — o vocabulário de posições de parâmetros: o seu tipo, a sua descrição e as suas restrições — e todas as declarações aninhadas nos seus properties, items e valuesType são sujeitas ao mesmo. O default da declaração é ocultado em todos os níveis, removendo a chave em vez de a esvaziar, pelo que um plugin não consegue saber se uma declaração tem uma. Uma chave fora desse vocabulário é ocultada com tudo o que contém, em todos os níveis: a compilação não atribui nenhum significado a uma chave dessas, e um rascunho que escreva mal uma chave pode transportar um segredo sob ela. Uma entrada em parameters que não seja uma declaração é ocultada por inteiro.
  • Cada módulo listado em aggregates de um Aggregate perde o seu bloco parameters, que contém os valores passados a esse módulo.
  • Uma Release perde o seu bloco parameters, quer escreva os valores inline quer os importe com $import.
  • Qualquer outro documento que contenha um bloco parameters em spec perde-o por inteiro; nenhum outro tipo declara um.

Isto aplica-se à entidade nomeada na linha de comandos, à versão publicada com a qual --pre-publish a compara, a todas as entidades que as passagens de catálogo completo e de --release percorrem e aos documentos que uma regra que lê uma Release completa recebe. Um template que lê um parâmetro não é um valor e mantém o seu texto, pelo que uma regra continua a ver que parâmetro um valor escrito lê.

Exemplos

Percorrer o catálogo completo à procura de desvios das convenções:

aggrega lint --catalog ./catalog

Aplicar o lint localmente a uma entidade durante a autoria:

aggrega lint core/datastore/postgres/component.yaml

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

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

Relaxar uma regra numa única execução:

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

Ver também

  • ./aggrega-validate.md — a contrapartida de correção nos mesmos três âmbitos.
  • ./aggrega-build.md — valida como parte da compilação; apresenta o aviso de x-aggrega-* com a severidade warn.
  • ./aggrega-push.md — publica uma entidade no registo; aggrega lint --pre-publish é o controlo que o precede.
  • ./aggrega-pull.md — resolve e fixa as dependências.
  • ./aggrega-serve.md — o servidor de linguagem que reporta estas conclusões no editor, e a definição que ativa a camada por edição.
  • ../errors/warnings.md — avisos não fatais, incluindo as conclusões de lint do 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

FlagPredefiniçãoDescrição
--allow-aggrega-ai-prefixfalseForçar allow_aggrega_ai_prefix=true
--allow-category-mismatchesfalseForçar allow_category_mismatches=true
--allow-connection-credential-mismatchesfalseForçar allow_connection_credential_mismatches=true
--allow-direct-x-aggrega-extensionsfalseForçar allow_direct_x_aggrega_extensions=true
--allow-dynamic-refsfalseForçar allow_dynamic_refs=true nesta invocação
--allow-id-overridesfalseForçar allow_id_overrides=true nesta invocação
--allow-nonstandard-namesfalseForçar allow_nonstandard_names=true
--allow-undeclared-recipe-providesfalseForçar allow_undeclared_recipe_provides=true
--baseline—Comparar a verificação de evolução de pré-publicação com esta versão específica já publicada em vez da versão mais alta selecionada automaticamente abaixo da que está a ser publicada; tem de ser uma tag SemVer estrita presente no registo (requer —pre-publish)
--catalog[]Diretório de catálogo; repetível. Cada —catalog <dir> é colocado no início da pilha de pesquisa de catálogos (a primeira correspondência prevalece): os catalog_dirs do espaço de trabalho ou, para uma Release à qual a configuração do espaço de trabalho atribui diretórios próprios em workspace.releases, os dessa Release; a pilha termina com o diretório chamado catalog na raiz do espaço de trabalho, quando existe. Uma lista catalog_dirs escrita vazia não lê nenhum catálogo local. Usado pelas passagens de convenções de catálogo completo e de —release.
--entity—Caminho para o YAML da entidade a verificar (em alternativa, passe-o como argumento posicional)
--no-allow-aggrega-ai-prefixfalseForçar allow_aggrega_ai_prefix=false
--no-allow-category-mismatchesfalseForçar allow_category_mismatches=false
--no-allow-connection-credential-mismatchesfalseForçar allow_connection_credential_mismatches=false
--no-allow-direct-x-aggrega-extensionsfalseForçar allow_direct_x_aggrega_extensions=false
--no-allow-dynamic-refsfalseForçar allow_dynamic_refs=false nesta invocação
--no-allow-id-overridesfalseForçar allow_id_overrides=false nesta invocação
--no-allow-nonstandard-namesfalseForçar allow_nonstandard_names=false
--no-allow-undeclared-recipe-providesfalseForçar allow_undeclared_recipe_provides=false
--output, -otextFormato de saída: text|json.
--plugin—Caminho no sistema de ficheiros para o artefacto .wasm do linter de publicação (executa este artefacto em vez das anexações plugins.linter do espaço de trabalho)
--pre-publishfalseObter a versão anterior do registo e verificar o incremento proposto contra a classificação de evolução do esquema
--release—Caminho para um YAML de Release cujo fecho de dependências resolvido deve ser verificado quanto às convenções (mutuamente exclusivo com um argumento de entidade). Um caminho relativo é resolvido em relação ao diretório em que o comando é executado, não em relação à raiz do espaço de trabalho. Quando esse diretório não está em nenhum espaço de trabalho e nenhuma raiz é nomeada, um caminho absoluto encontra o espaço de trabalho a partir da própria pasta da Release