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 build

aggrega build compila um par Aggregate + Release em artefatos nativos dos providers (manifestos Helm, charts Helm redistribuíveis, YAML do docker-compose) em dist/ na raiz do workspace, conforme Saída descreve. A Release é o único ponto de entrada: ela nomeia o Aggregate e o Manifest, declara limites e roteia componentes para providers.

Flags comuns

Duas flags têm um comportamento que a referência de flags abaixo não consegue transmitir sozinha:

  • --catalog <dir> — um diretório que contém entidades de catálogo — os tipos de escrita Component, Feature, Recipe e FeatureRecipe junto com os tipos de biblioteca, Aggregates e Plugins —, carregado de forma recursiva. Cada diretório --catalog é pesquisado antes dos configurados, na ordem fornecida. Para pesquisar um catálogo local do projeto junto com um compartilhado, passe ambos (--catalog ./catalog --catalog ../shared-catalog) ou liste-os em catalog_dirs. Com --detail, qualquer entidade que um diretório de maior precedência sombreie é informada no stderr, junto com os demais avisos do build. Um diretório --catalog que não existe interrompe o build, nomeando-o. O mesmo acontece com um diretório listado em catalog_dirs que não é um diretório, antes que qualquer coisa seja lida ou gravada, nomeando a entrada e o arquivo de configuração e a linha que a listam — veja De onde as entidades locais são lidas. Um build que é interrompido porque uma referência não foi resolvida para nada nomeia, na nota abaixo da interrupção, cada arquivo nesses diretórios que declara uma apiVersion do Aggrega — uma linha que começa, sem recuo, com apiVersion: e um valor iniciado por aggrega.ai/ — e que não pôde ser carregado, por exemplo um que não é analisado como YAML, com o motivo dado pelo próprio parser, entre os arquivos de catálogo ignorados no carregamento; um arquivo YAML que declara outra apiVersion, ou nenhuma, não é um documento do Aggrega e nunca é nomeado ali.
  • --detail — relata o que a etapa de pull fez, o mesmo diagnóstico transitório de eventos de pull que aggrega pull --detail emite. O que decide se há algo a relatar é se uma etapa de pull foi solicitada — com --auto-pull, ou habilitando auto_pull — e não se um lockfile já está presente: uma etapa de pull solicitada é executada de qualquer forma, preenchendo um lockfile ausente e respeitando os pins de um existente. Quando nenhuma etapa de pull é executada, a flag imprime uma nota de uma linha no stdout e prossegue — ela nunca inventa um nível de resolução que o lockfile commitado não contém. Para o estado de resolução pós-pull das dependências de uma Release, use aggrega inspect.

--dry-run é tratada em Visualizar um build sem gravá-lo, e --trace e --trace-unredacted em Saída de trace e Mostrar os valores retidos abaixo.

Preencher o lockfile como parte do build

Por padrão, o build é somente leitura em relação às dependências: ele precisa de um lockfile e não grava nenhum. --auto-pull e a configuração de workspace auto_pull adicionam a etapa de pull ao build, de modo que um único comando resolve as dependências da Release e compila com base no que resolveu.

Uma edição na Release é algo que o lockfile percebe. O lockfile registra a Release — e cada Release que ela estende — pelo digest do seu conteúdo, então um build somente leitura sobre uma Release editada desde o pull é interrompido antes de qualquer renderização, nomeando o arquivo e dizendo para você executar aggrega pull --release <release>, que registra a edição respeitando todos os outros pins. Um comentário ou uma alteração de espaços em branco conta, porque o digest cobre os bytes como eles são. Um build com auto-pull executa ele mesmo essa etapa de pull, então registra a edição e faz o build.

A Release é renderizada uma única vez. Quais entradas externas uma Release consome decorre de renderizá-la, e não de algo que seus documentos declaram, então a etapa de pull renderiza a Release para descobrir — e essa renderização é a do build. Um build com auto-pull custa, portanto, uma renderização, o mesmo que um build simples sobre um lockfile que já existe.

As flags que moldam uma renderização se aplicam a ela. --trace, --verify-determinism, --disable-plugin-cache e --no-unsupported-field-warnings alcançam a renderização que um build com auto-pull executa nas mesmas condições em que alcançam a de um build simples, então pedir um trace ou uma verificação de determinismo em um build de comando único faz com que você o obtenha. --dry-run é a exceção, e é uma recusa em vez de um silêncio: um dry run não grava nada, enquanto a etapa de pull grava, então a combinação é interrompida antes de qualquer trabalho (veja Visualizar um build sem gravá-lo).

Como um build lê o que o lockfile fixa

Um pin do lockfile nomeia um conteúdo — um digest — e não um local. Para uma entidade, é o digest do que uma publicação dela contém, seu documento e os arquivos que ele nomeia, então uma cópia de uma entidade em um diretório de catálogo e uma entrada de cache que contém sua publicação carregam o mesmo pin, como O lockfile descreve. Um build lê cada dependência fixada a partir das fontes que já estão na máquina: primeiro os diretórios de catálogo, como em todos os outros lugares, depois o cache de conteúdo em .aggrega/cache. Lê-las não consulta nenhum registry; apenas a etapa de pull, onde um build executa uma, faz download.

Uma entrada de cache que não contém mais o seu pin é ignorada. Uma entidade editada no local — um novo corpo sob a mesma version — deixa no cache de conteúdo o corpo anterior sob esse nome e essa versão. Onde um diretório de catálogo contém uma cópia cujo conteúdo tem o pin como digest, o build lê essa cópia e nunca a entrada, e informa isso no erro padrão, nomeando a entrada e os dois digests:

reuse: cache entry for <name>:<version> holds <digest the entry holds>, not the pinned <pinned digest>; passed over for <catalog file>, which holds the pinned bytes

Onde nenhum diretório de catálogo contém a entidade, uma entrada de cache completa contendo exatamente os bytes fixados é lida como a dependência, de modo que uma entidade removida do seu diretório de catálogo depois que sua cópia publicada foi baixada ainda é compilada a partir dessa cópia.

Onde nenhuma fonte contém os bytes fixados, o build é interrompido antes de qualquer renderização, com E0135 — ou E0133 onde o manifesto da entrada de cache não é o que o lockfile fixa. A interrupção nomeia o pin, a entrada de cache e o digest que ela contém, e cada cópia da entidade em diretório de catálogo com seu digest, ou que nenhum diretório de catálogo a contém. A solução é um pull com um registry acessível, que baixa novamente a versão fixada e confere o que baixa com o pin; veja Respeitar vs. atualizar para saber o que o pull faz quando o registry não serve mais esses bytes.

A renderização que aggrega pull executa para descobrir entradas externas, e um build ou uma visualização por meio de aggrega serve ou aggrega mcp, leem seus pins da mesma forma.

Entradas externas em tempo de build

Uma renderização pode solicitar conteúdo de uma URL remota — o schema de valores de um chart com uma referência remota, por exemplo — e um build nunca baixa uma para adicioná-la ao que a renderização pode ler. Uma solicitação de uma URL que o lockfile já fixa é atendida a partir do armazenamento de entradas do workspace e verificada em relação ao digest registrado antes que qualquer byte chegue à renderização. Uma solicitação de uma URL não fixada é interrompida, nomeando a URL e a etapa que a fixa; não há configuração que transforme essa interrupção em download, porque ampliar silenciosamente o conjunto de entradas que um build lê é a única coisa que um build reproduzível não pode fazer.

Onde a cópia de uma entrada fixada no armazenamento desapareceu, apenas essa entrada é baixada novamente pelo digest que o lockfile já registra e conferida com ele antes que qualquer coisa seja gravada ou retornada. Isso não pode mudar o que a renderização vê — o digest foi definido quando a entrada foi fixada —, então repara o armazenamento em vez de ampliar o fechamento, e o lockfile permanece inalterado byte a byte. No modo offline não há transporte nem para isso, e a cópia ausente causa uma interrupção, que nomeia o modo.

A fixação acontece quando as dependências da Release são resolvidas, de modo que o que um build pode ler fica definido antes que o build comece. aggrega pull é essa etapa, e é a única.

O registro de confiança de plugins

Vários comportamentos de um build dependem de plugins-trust.yaml, o arquivo commitado ao lado do lockfile da Release que registra para qual plugin cada vinculação que retorna veredito foi resolvida — uma vinculação plugins.governance em um papel ir-verdict ou render-verdict, e toda vinculação plugins.linter. aggrega pull o grava e o schema do registro de confiança de plugins descreve seus campos; o que segue trata apenas do que um build em si faz com ele.

Um build é confrontado com o registro antes que qualquer um desses plugins seja executado. Um plugin servido a partir do cache cujo digest de artefato não é o registrado é recusado em vez de executado — essa é a resolução que uma vinculação desse tipo normalmente assume, e aggrega pull descreve quais outras formas de resolvê-la o digest registrado não rege. E uma entrada registrada da qual nenhuma vinculação em .aggrega-config.yaml dá conta mais interrompe o build: remover um controle não altera nenhum byte renderizado, então uma saída produzida sem um controle revisado tem exatamente a mesma aparência de uma saída que esse controle aprovou. A interrupção nomeia o plugin e oferece as duas soluções que diferem pelo que você pretendia — vinculá-lo de novo se a remoção foi um engano, ou solicitar a remoção explicitamente se não foi — e imprime o comando pronto para executar. Uma vinculação que o registro ainda não contém é uma primeira ocorrência, e nenhuma das duas comparações é interrompida por ela.

Um build confronta cada um desses plugins com a assinatura que sua entrada registra, exatamente como confronta uma entrada do lockfile com a que essa entrada registra. Onde uma entrada registra uma signature verificada, o build recalcula o hash do bundle de assinatura que esse fato nomeia no cache antes de qualquer renderização, e para com E0144 onde o bundle está ausente ou difere. Para um plugin que lê do cache de conteúdo, ele também lê desse bundle para qual artefato a assinatura foi feita, e para com E0332 onde ela foi feita para um plugin diferente daquele que o build leu — que é a aparência de uma signature copiada de outra entrada —, independentemente do que diga o requisito de assinatura. Para um plugin servido pelo cache de conteúdo, qualquer uma das recusas nomeia aggrega pull --release <release>: o próximo pull verifica novamente a assinatura do plugin, registra a do próprio plugin e armazena em cache o bundle que ela nomeia, regravando uma cópia em cache que não corresponde mais ao seu digest. Onde a configuração de confiança do workspace exige uma assinatura para um plugin que o build lê do cache de conteúdo — sob as mesmas configurações que fariam aggrega pull recusá-lo sem assinatura, de modo que skip_signature_verification e um registry advisory deixam o build prosseguir como deixam o pull prosseguir —, uma entrada que não registra nenhuma assinatura, ou a ausência de qualquer entrada para o plugin, interrompe o build com E0331, nomeando o plugin, plugins-trust.yaml e as configurações que exigem a assinatura. A solução é aggrega pull --release <release>, que verifica a assinatura do plugin no seu registry a cada execução e a registra. 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 a esse requisito. Como o restante do build, isso lê arquivos que já estão na máquina e não consulta nada a nenhum registry.

Um build nomeia cada retirada que o registro contém, ao lado de cada uma que o lockfile contém. Um marcador que aggrega pull registrou para um desses plugins é informado como uma linha deprecation: que nomeia o plugin, a severidade registrada e a mensagem do publicador, em qualquer severidade, e build.halt_on_deprecated_severity decide se ele também interrompe o build, pela mesma regra que aplica a uma referência fixada. Todas as outras superfícies que informam sobre uma Release nomeiam o mesmo conjunto com as mesmas palavras, e nenhuma delas é interrompida por isso: aggrega validate --release, aggrega lint --release, aggrega inspect --closure, a validação e a resposta de fechamento do servidor de linguagem, e as ferramentas describe e validate do assistente. Um registro que existe e não pode ser lido interrompe o build em vez de passar por um que não registra nada.

aggrega build --upgrade regrava esse arquivo. Ele implica --auto-pull e executa uma atualização completa sem argumentos, que resolve novamente cada dependência e, portanto, resolve novamente e regrava cada identidade registrada, e descarta cada entrada da qual nenhuma vinculação dá conta. Então, se este arquivo aparecer modificado após um build de upgrade, esse é o motivo: o alcance da flag é cada dependência, e as identidades registradas fazem parte do que é resolvido novamente, embora não sejam pins do lockfile. Diferentemente de aggrega pull --upgrade, a flag do build não aceita um alvo, então não pode ser restrita a um único plugin: para adotar ou descartar uma única identidade, execute em vez disso aggrega pull --upgrade --release <release> <plugin>, que deixa intactos todos os outros pins e todas as outras identidades registradas.

Como seu alcance é tudo, ele pergunta antes de começar. aggrega build --upgrade confirma a atualização nas mesmas condições que o aggrega pull --upgrade sem argumentos — os dois são o mesmo ato, então fazem a mesma pergunta. Passe --yes para responder antecipadamente em uso não interativo; se a entrada padrão não for um terminal e não houver --yes, o build recusa em vez de esperar por uma resposta que ninguém pode dar. Um build que não atualiza não pergunta nada.

Resolução do workspace e determinismo

A referência manifest: da Release, exigida pelo schema, é resolvida em relação ao arquivo da Release. Uma entrada catalog_dirs relativa (e um caminho relativo de plugin no sistema de arquivos) é resolvida em relação ao diretório do .aggrega-config.yaml que a declarou — “relativo” sempre significa relativo ao arquivo em que você o escreveu, então um caminho significa a mesma coisa de onde quer que você invoque aggrega. Uma flag --catalog, que não tem arquivo declarante, é resolvida em relação ao diretório de trabalho atual. Referências de registry (oci://…, uma referência de hub) são mantidas como estão.

A raiz do workspace é o diretório do .aggrega-config.yaml ancestral mais próximo que contém um bloco workspace:, ou o diretório que --workspace-root nomeia. Quando a raiz é fixada dessa forma, um build é independente do local de invocação: executar aggrega build a partir da raiz do projeto e a partir de um subdiretório produz IR e artefatos renderizados idênticos byte a byte, porque o catálogo pesquisado e os caminhos de origem registrados na saída não mudam com o diretório de trabalho. (Sem o marcador workspace: e sem --workspace-root, o diretório de trabalho é a raiz, então a saída fica ancorada ali — a menos que o diretório de trabalho não ancore nada e --release nomeie a Release por um caminho absoluto: a raiz é então descoberta novamente a partir da própria pasta da Release, de modo que o catálogo pesquisado e os caminhos registrados na saída são os do projeto ao qual a Release pertence, de onde quer que você execute o comando. Veja configuration.md.) Onde nenhum workspace é encontrado dessa forma também e nada nomeia um, o build avisa no erro padrão que a pasta usada como raiz não está dentro de nenhum workspace e nomeia o comando que a transforma em um; um build solicitado a resolver primeiro suas dependências é recusado antes que qualquer coisa seja baixada, porque o cache que essa resolução preenche seria gravado nessa pasta e a transformaria em um workspace. Um build que não resolve nada antes ainda renderiza, mas pelo mesmo motivo uma entrada externa que o lockfile fixa e que o cache não contém mais não é baixada novamente: o plugin que a solicita recebe em seu lugar a frase da recusa, como recebe a do modo offline, e o build relata o que esse plugin faz com isso. Um --workspace-root ou AGGREGA_WORKSPACE_ROOT que nomeia uma pasta inexistente é recusado antes que o build faça qualquer outra coisa, nomeando qual dos dois o forneceu.

Variáveis de ambiente

As configurações de workspace que o build lê podem ser substituídas pelo ambiente, acima da configuração commitada e abaixo de qualquer flag: AGGREGA_OFFLINE, AGGREGA_AUTO_PULL, AGGREGA_CATALOG_DIRS (separadas conforme a lista de caminhos do sistema operacional; forneça caminhos absolutos), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY e AGGREGA_WORKSPACE_ROOT. Veja environment-variables.md para a lista completa e o modelo de precedência.

Saída

Os artefatos renderizados ficam em dist/ sob a raiz do workspace, seja qual for a pasta a partir da qual o comando é executado — a própria raiz, uma pasta abaixo dela ou uma pasta em outro lugar com a raiz nomeada por --workspace-root ou AGGREGA_WORKSPACE_ROOT —, e a linha final nomeia esse diretório por completo:

Build completed: 4 files written to <workspace>/dist

<workspace> representa aqui a raiz do workspace, que a linha escreve como caminho completo. Onde nenhum workspace é encontrado e nada nomeia um, a pasta a partir da qual o comando foi executado é a raiz, então dist/ é gravado ali. Um dist que é um link que leva para fora do workspace é recusado antes que qualquer coisa nele seja removida ou gravada. Uma Release que não declara limites grava por provider: dist/<provider>/<files>. Um limite declarado sem directory: grava por limite e por provider: dist/boundaries/<boundary-path>/<provider>/<files>. As substituições directory: e subDirectory: escritas pelo operador nos limites da Release alteram o caminho de destino; o colapso por (path, provider) mescla os contribuidores que se resolvem para o mesmo caminho avaliado.

Arquivos que o build não gravou

Um build grava os próprios arquivos e não remove nada que não tenha gravado, com uma exceção: dist/boundaries/, que um build regenera por inteiro, é esvaziado antes da gravação, para que um arquivo deixado ali por um build de outra variante não sobreviva em uma árvore que não o produz mais. Todo o resto em dist/ fica como está — um arquivo que um build anterior gravou e que este não produz mais, um arquivo que o directory: de um boundary colocou ali em uma execução anterior e um arquivo que você mesmo colocou ali, igualmente —, porque o build não consegue distinguir uma sobra de um arquivo que você mantém ali de propósito.

O que ele faz em vez disso é avisar você. Depois que seus arquivos são gravados, o build olha no próprio dist/ e em cada diretório abaixo dele no qual gravou um arquivo ou pelo qual passou para gravar um mais fundo, e nomeia cada arquivo ali que não gravou nesta execução, em um único aviso no erro padrão. Os arquivos são nomeados pelos seus caminhos relativos a dist/, ordenados, para que a mesma árvore seja informada da mesma forma em toda execução:

warning: the output directory holds 2 file(s) this build did not write, in directories it wrote into; nothing was removed, so they sit beside this build's output: "app/stale-from-earlier-run.yaml", "beside-the-tree.txt"

A linha de encerramento então os conta:

Build completed: 1 file written to <workspace>/dist, beside 2 files this build did not write

Um diretório no qual o build não gravou nada, nem diretamente nem abaixo, não é examinado, então uma pasta sua mantida em dist/ não é listada arquivo por arquivo. Um build que não encontra nenhum arquivo assim não imprime aviso, e sua linha de encerramento é a mostrada em Saída. De qualquer forma, os arquivos que o build grava são os mesmos bytes. Para comparar dois builds, ou para começar do zero, remova dist/ antes do build.

A requisição aggrega/build de aggrega serve e a ferramenta build do assistente (aggrega mcp) gravam pela mesma etapa, então nomeiam os mesmos arquivos na mesma frase: o daemon como um dos notices da sua resposta, e a ferramenta como o último dos seus advisories. Uma execução de simulação não grava nada, então não informa nada disso.

Indentação YAML

Todo artefato YAML renderizado — arquivos docker-compose, templates e valores de charts Helm e manifestos Kubernetes — é emitido com uma largura de indentação uniforme. A largura é definida por build.yaml_indent em .aggrega-config.yaml e o padrão é 2 (a largura convencional para esses formatos):

build:
yaml_indent: 2 # default; accepts 2 through 9

A largura é aplicada em um único ponto de serialização compartilhado por todos os renderizadores, de modo que a saída permanece idêntica byte a byte entre execuções com a mesma entrada. Valores fora do intervalo [2, 9] são rejeitados pela validação do schema de configuração.

Devolver o grafo compilado

--ir-graph grava na saída padrão, como JSON, o grafo que este build resolveu. É aditiva: os artefatos continuam sendo gravados em dist/, o resumo continua sendo impresso e os bytes renderizados não mudam. O grafo sai antes de tudo o mais que o build imprime ali — um documento JSON e uma quebra de linha final —, de modo que um consumidor que decodifica o fluxo o lê e para.

O grafo devolvido é aquele que a renderização consumiu, então ele descreve exatamente o build que produziu os artefatos ao lado dele, e não uma segunda resolução da mesma Release. Ela se combina com --dry-run: o grafo é gravado e o relatório de artefatos vem em seguida, sem nada gravado em disco.

Os valores que um autor declarou sensíveis são retidos nele — incluindo os values e infra de uma conexão, quando o socket do componente consumidor declara uma folha sensível —, na forma estruturada descrita em aggrega inspect. --unredacted junto com --ir-graph os imprime em vez disso, nas condições que aggrega inspect --unredacted estabelece: ela alcança o grafo e nada mais — os arquivos de trace têm a sua própria --trace-unredacted, e os artefatos renderizados nunca são retidos — e tudo o que a saída alcançar passa a conter esses valores em texto claro. Passada sem --ir-graph, ela é recusada, porque não haveria nada para revelar.

A mesma flag, com o mesmo significado, está em aggrega inspect e aggrega validate.

Visualizar um build sem gravá-lo

--dry-run executa a mesma compilação que um build executa — as mesmas verificações de dependências, a mesma renderização, os mesmos providers — e imprime o que emitiria em vez de gravar. Cada artefato é relatado com o caminho que ocuparia e o conteúdo que teria:

aggrega build --release releases/production.yaml --dry-run
==> <workspace>/dist/main/helm/webapp-configmap-webapp.yaml <==
apiVersion: v1
kind: ConfigMap
...
Total build time: 2.5s
Dry run: 1 file would be written to <workspace>/dist; nothing was written

Os artefatos são relatados na ordem em que um build os grava, de modo que a mesma entrada relata os mesmos bytes na mesma sequência, e o caminho relatado é o caminho em que um build gravaria — sob a raiz do workspace, escrito por completo onde <workspace> aparece acima.

O que não é gravado. O diretório de saída fica exatamente como está — ele também não é limpo, então a saída de um build anterior sobrevive intacta a um dry run. O lockfile não é gravado. Nada é gravado em .trace/.

Entradas externas se comportam exatamente como em um build comum, nas condições que Entradas externas em tempo de build descreve. Um dry run, portanto, lê o mesmo fechamento fixado que o build que ele representa leria, e o que ele mostra é o que esse build gravaria.

Onde uma referência foi recusada, a execução nomeia cada uma que não conseguiu alcançar e aponta para o comando que as fixa:

note: the lockfile does not pin every external reference this render requested, so the following were declined and the render stopped short of the artifacts it would otherwise emit:
- https://charts.example.com/values-schema.json
Run `aggrega pull --release releases/production.yaml` to pin the inputs the render needs, then run the dry run again

Execute aggrega pull uma vez e o dry run terá tudo de que precisa; nada mais muda nele.

Um dry run precisa de um lockfile e nunca preenche um. O build é somente leitura por padrão, e um dry run se mantém assim seja qual for a forma como um preenchimento foi solicitado. --auto-pull e --upgrade são recusadas de imediato (abaixo); a configuração de workspace auto_pull é ignorada nessa única invocação, de modo que um workspace que preenche por padrão ainda pode ser visualizado. Sem lockfile, um dry run é interrompido com a mesma solução que um build comum somente leitura dá: execute primeiro aggrega pull.

As flags que ele recusa. Três flags gravam, então combiná-las com um dry run não tem resultado honesto — ignorar a gravação faria um preenchimento solicitado desaparecer, e respeitá-la quebraria a única promessa que o dry run faz. Cada combinação é interrompida antes de qualquer trabalho, nomeando a flag que você passou e a etapa a executar em seu lugar:

Combinada comPor que é recusada
--auto-pullpreenche o lockfile; execute aggrega pull como uma etapa própria
--upgraderesolve novamente cada dependência e regrava o lockfile; execute aggrega pull --upgrade como uma etapa própria
--tracegrava arquivos por nó em .trace/; execute o build com trace sem --dry-run

Todo o resto se combina normalmente. --verify-determinism renderiza cada nó duas vezes e compara os bytes sem gravar nenhum deles, e --catalog, --quiet, --progress, --debug e os filtros de avisos se comportam exatamente como em um build que grava.

Para que serve e para que não serve. Um dry run responde a “o que esta Release emitiria”, uma pergunta que só uma renderização pode responder — portanto, não substitui aggrega validate, que verifica a correção sem renderizar, nem aggrega inspect, que consulta o grafo antes da renderização. Recorra a um dry run quando a resposta que você quer são os próprios artefatos: revisar o que uma alteração na Release faz com a saída, ou verificar uma edição de Recipe antes de commitar qualquer coisa em dist/.

Saída de trace

A flag --trace ativa um dump de depuração por nó que captura cada estado intermediário do compilador. A saída fica em .trace/ sob a raiz do workspace, ao lado de dist/ (nunca dentro dele; o layout lado a lado segue a convenção de .git/, .terraform/, node_modules/ e mantém dist/ puramente implantável).

O layout de diretórios é por limite e por instância:

.trace/
└── boundaries/
└── <boundary-path>/
└── <instance-id>/
├── 01-pillars-initial.yaml
├── 02-provides-evaluation.yaml
├── 03-inject-hydration.yaml
├── 04-inject-mapping.yaml
├── 05-source-resolution.yaml
├── 06-source-locals.yaml
├── 07-values-mapping.yaml
├── 08-workload-synthesis.yaml
├── 09-artifact-evaluation/
│ └── <per-artifact-file>.yaml
├── 09b-feature-rendering-boundary.yaml
├── 10-engine-synthesis/
│ └── <per-synthesized-file>.yaml
├── 11-engine-emission.log
└── 12-labels-injected.log

Cada slot captura um estado específico do compilador:

  • 01-pillars-initial.yaml — o snapshot por nó do contexto que um template lê, tirado após a resolução e antes de qualquer mutação por estágio. Contém .values, .infra, .context, .parameters, .metadata.
  • 02-provides-evaluation.yaml — as saídas provides: resolvidas após a avaliação de provides.
  • 03-inject-hydration.yaml — o pipe .context.inject mesclado após a hidratação de inject (visão do lado do consumidor dos provides upstream).
  • 04-inject-mapping.yaml — o pipe .context.inject após as reescritas injectMapping da FeatureRecipe.
  • 05-source-resolution.yaml — o conteúdo source: analisado que o provider vai consumir. Presente apenas quando a Recipe declara source:.
  • 06-source-locals.yaml — o bloco locals: resolvido. A resolução da origem publica .locals antes de avaliar o template source:, e é por isso que este slot é gravado quer a Recipe declare source: ou não.
  • 07-values-mapping.yaml — a saída renderizada de valuesMapping: (o dicionário que o provider recebe). Presente apenas quando a Recipe declara valuesMapping:.
  • 08-workload-synthesis.yaml — o contexto como estava quando o template workload: foi avaliado e sua saída analisada. Presente apenas quando a Recipe declara workload: (inline ou carregado com $import:). O Workload analisado em si não está neste slot: ele aparece a partir de 09-artifact-evaluation/, quando já está definido e não mais em andamento.
  • 09-artifact-evaluation/ — um arquivo por artefato avaliado. Presente apenas quando a Recipe declara artifacts: (com entradas inline ou carregadas por entrada com $import:).
  • 09b-feature-rendering-boundary.yaml — o contexto como fica ao final da renderização do nó, depois que as FeatureRecipes anexadas a ele geraram seus recursos, com o workload analisado ao lado. Gravado para cada nó.
  • 10-engine-synthesis/ — um arquivo por manifesto sintetizado que o provider produziu a partir do Workload (modo workload de helm/compose). Presente apenas quando o provider executou um caminho de síntese.
  • 11-engine-emission.log — o resumo pós-emissão (contagem de arquivos, caminhos de saída) do nó.
  • 12-labels-injected.log — os labels e as anotações de proveniência gravados na saída renderizada do nó.

A partir de 03-inject-hydration.yaml, um slot que mostra o contexto do nó contém o bloco .context.inject sempre que o pipe que ele captura entrega pelo menos uma chave, por qualquer mecanismo: env, file, arg, ou um mecanismo de outro nome no qual um mapeamento inject, o injectMapping de uma FeatureRecipe ou o próprio bloco inject: do componente grava. Um nó cuja única entrega é um desses mecanismos personalizados também mostra o bloco, com esse mecanismo sob o próprio nome e suas chaves em all, e um valor declarado sensível aparece como <redacted> nos dois lugares. Um slot capturado enquanto o pipe não entrega nada não tem bloco .context.inject.

O gravador de trace não é bloqueante: o trace é gravado em disco em paralelo à compilação, e não no caminho dela. A latência de compilação não é afetada pela E/S do trace — a mesma compilação termina no mesmo tempo real, com --trace ativada ou não.

Valores declarados sensíveis no trace

Um dado que um autor declarou sensível — uma folha de schema que carrega sensitive: true, ou uma chave de entrega cujo material veio de uma chave provides que o carrega — é gravado no trace como o texto fixo <redacted>. A chave é mantida e apenas o valor é substituído, de modo que um slot ainda mostra quais folhas e quais chaves de entrega um nó carrega. Um irmão não declarado no mesmo bloco imprime seu valor literalmente; a substituição segue a declaração e nada mais.

Um valor que uma FeatureRecipe entrega por meio do seu próprio injectMapping também é retido. Essa é a via à qual um slot que declara uma lista inject vazia confia a entrega, e a via que uma realização de credenciais apenas por inject segue. A chave de entrega que um mapeamento desse tipo grava é ela mesma um template, então nenhuma declaração a nomeia; o que é lido em vez disso é o próprio texto do mapeamento. Quando esse texto referencia uma folha values ou infra que a Feature vinculada declara sensitive: true, cada chave de entrega que o mapeamento produziu é lida como <redacted> — inclusive uma chave que não carrega nada sensível, já que a leitura é por vinculação, e não por chave. Um mapeamento que não referencia nada declarado imprime suas chaves literalmente.

Um valor que um template calculou a partir de um dado declarado sensível também é retido, embora sua própria chave não carregue nenhuma declaração. O que o identifica é a referência que o autor escreveu: uma entrada locals: cujo template lê uma folha declarada sensível é retida, assim como um campo source: que o faz. A leitura é conservadora — um template que alcança um objeto inteiro alcança cada folha declarada sob ele, então {{ range $k, $v := .values.creds }} retém sua saída quando qualquer coisa sob creds está declarada — e uma entrada locals: que lê um irmão já retido é retida por sua vez. Uma entrada irmã de mesma forma que não lê nada declarado é impressa literalmente.

Um valor que percorre uma aresta uses é retido de acordo com as declarações do alvo, não do nó consumidor, e é retido nas duas superfícies para as quais a aresta o leva. .context.uses.<alias>.provides reproduz o que o componente alvo publicou, então o que rege esses valores é o schema do alvo: uma chave provides que o alvo declarou sensível é lida como <redacted> no slot do consumidor mesmo quando o consumidor não declara absolutamente nada. Quando o próprio bloco inject da aresta roteia essa chave para uma chave de entrega do componente consumidor, .context.inject retém também essa chave de entrega — a mesma regra que o mapeamento inject de uma vinculação já segue, lendo a mesma declaração. A retenção é por aresta, então duas arestas que publicam o mesmo nome de chave provides se resolvem de forma independente: aquela cujo alvo a declarou é retida e a outra é impressa literalmente. O restante da aresta — seu alvo, seu socket, seus labels e os nomes de chave do próprio mapeamento inject — não é o que uma declaração provides do alvo rege, e é impresso literalmente.

Os values e infra por conexão escritos na própria aresta são regidos, em vez disso, pelo socket do componente consumidor: o valueSchema e o infraSchema que esse socket declara, que são os contratos com base nos quais essa configuração é validada. Uma folha que qualquer um dos dois contratos declara sensitive: true é lida como <redacted> em .context.uses.<alias>.values ou .context.uses.<alias>.infra, com a chave mantida, e o mesmo vale para uma folha que está em um valor padrão declarado pelo contrato; um elemento irmão não declarado é impresso literalmente. As declarações do alvo não têm papel aqui, e a retenção é por conexão, então uma folha de mesmo nome em uma conexão cujo socket a declara legível é impressa literalmente.

As vinculações escritas em uma conexão são mostradas sob a aresta dessa conexão, em .context.uses.<alias>.features.<slot>, e cada uma é retida de acordo com as declarações da sua própria Feature — as mesmas que regem essa Feature quando um componente a mantém diretamente. Uma folha values ou infra que a Feature declara sensitive: true é lida como <redacted>, assim como uma chave dos provides resolvidos da vinculação que a Feature declara sensível; cada chave é mantida. O tipo, a versão e os labels da vinculação, e cada folha e chave provides que sua Feature deixa sem declarar, são impressos literalmente, de modo que um localizador publicado permanece legível ao lado do material que ele localiza. A retenção é por conexão e slot, então a mesma Feature escrita em duas conexões se resolve em cada uma. Um slot que declara sensitive: true — no componente ou no seu socket — diz que a vinculação lida com material secreto e não retém nenhuma folha por conta própria: quais folhas são retidas cabe à Feature declarar. As vinculações próprias de um componente não estão entre os blocos que um slot mostra, já que o trace não carrega nenhum bloco .features; o que um template workload: lê de uma delas é coberto pela nova renderização descrita abaixo.

O Workload analisado é uma nova renderização, não uma captura do documento que o build emitiu, e os slots que o carregam — 09-artifact-evaluation/, 10-engine-synthesis/ e 09b-feature-rendering-boundary.yaml — dizem isso em uma entrada workload_note ao lado dele. Um documento renderizado não registra nada sobre de qual declaração veio um determinado caractere, então não há nenhuma chave na qual substituir dentro dele. O que o trace mostra em vez disso é o mesmo template workload: avaliado uma segunda vez, sobre um contexto cujos dados declarados sensíveis já são lidos como <redacted>. Como o template vê uma string onde havia uma string, o resultado mantém a forma do documento emitido: os mesmos campos, nos mesmos lugares, com <redacted> na própria posição do dado retido e o texto literal ao redor inalterado.

Duas maneiras pelas quais essa nova renderização difere do que foi emitido, ambas indicadas na nota:

  • Um template que se ramifica com base no conteúdo de um valor renderiza de forma diferente. Um eq contra um valor específico, um teste de comprimento, um hash ou uma codificação dele: cada um vê <redacted> e produz um resultado diferente — outro ramo, outro comprimento, outro digest. É por isso que o trace nunca afirma mostrar o documento emitido.
  • Dados que nenhuma declaração nomeia passam sem alteração. A substituição cobre o que o eixo nomeia — uma folha values / infra declarada, uma chave de entrega marcada, uma chave provides que o próprio Component do componente declara sensível, os provides declarados de um alvo consumido, uma folha dos values ou infra próprios de uma conexão que o seu socket declara sensível, uma folha ou chave provides declarada de uma vinculação que o próprio componente mantém (lida em .features.<name>) ou de uma escrita em uma conexão, e um valor locals: ou source: calculado a partir de um deles. São os mesmos dados pelos quais uma recusa gerada pelo template é retida. Um dado que chega ao template por qualquer outro meio, como uma chave provides que nenhuma declaração nomeia e cujo valor uma Recipe calculou a partir de uma folha declarada, aparece na nova renderização exatamente como aparece no documento emitido.

Quando a nova renderização não pode ser produzida de forma alguma, o slot mantém a chave workload: e substitui o documento por uma linha que informa isso e nomeia --trace-unredacted. A indicação é deliberada: uma projeção que simplesmente sumisse seria indistinguível de uma Recipe que não declara nenhum workload:.

Vale a pena ler um limite antes de tratar .trace/ como seguro: dist/ não é ocultado. Os artefatos renderizados são emitidos exatamente como a renderização os produziu, porque são o que se implanta, e a nova renderização do trace nunca os alcança — a mesma entrada renderiza de forma idêntica byte a byte, com --trace ativada ou não.

Trate .trace/ como portador de material sensível e lide com ele da mesma forma que se lida com dist/.

Mostrar os valores ocultados

--trace-unredacted, junto com --trace, grava nos arquivos de trace os valores declarados sensíveis em vez do texto que os substitui. Ele existe porque às vezes o valor ocultado é justamente o que está sendo depurado — uma credencial que chega do anexo errado parece idêntica à correta quando ambas aparecem como ocultadas.

É também a forma de capturar o documento que o build realmente emitiu: sem nada ocultado não há nada a substituir, então os slots workload: contêm o documento emitido em vez de uma nova renderização dele, e a entrada workload_note fica ausente.

Três propriedades o delimitam:

  • Todo arquivo que ele grava diz o que é. Cada arquivo de trace que a execução produz começa com um comentário que nomeia a flag e informa que os valores declarados sensíveis aparecem em texto claro mais abaixo, de modo que um arquivo anexado depois a um relatório de bug ou deixado em um diretório compartilhado carrega o próprio aviso. O comentário é válido no formato do próprio arquivo, então o arquivo continua podendo ser analisado.
  • Ele alcança .trace/ e nada mais. Os artefatos renderizados são idênticos byte a byte com e sem ele — ele muda o que um arquivo de depuração mostra, nunca o que um build produz — e os layouts de aggrega inspect e o texto de diagnóstico que um build com falha imprime são idênticos nos dois estados.
  • Ele existe apenas na invocação. Não há nenhuma configuração para ele, então ele não pode ser ativado uma vez e deixado ativo para todos que fizerem o build do workspace depois. Solicitá-lo sem --trace interrompe o build com uma mensagem que nomeia as duas flags, em vez de aceitar uma solicitação que ele não pode atender.

Independentemente do trace, um build imprime um aviso para cada chave de entrega que carrega material declarado sensível como valor literal, nomeando o componente, o destino, o anexo e a chave de entrega. Ele nunca interrompe o build e --no-unsupported-field-warnings não o silencia — essa flag cobre o que um destino não consegue atender daquilo que você escreveu, uma classe diferente.

A palavra-chave, seus dois locais de escrita, o texto exato do aviso e o limite completo do que declará-la consegue estão em vocabulary/compact-form-authoring.md, “Declarar uma folha como sensível”.

Quando usar --trace

  • Diagnosticar por que um manifesto renderizado não contém um valor esperado: percorra os dumps por passagem para encontrar o primeiro slot em que o valor está ausente.
  • Verificar o determinismo após uma atualização do compilador: duas compilações da mesma entrada com --trace produzem dumps de trace idênticos byte a byte; qualquer diferença por slot localiza a regressão.
  • Iteração na escrita do catálogo: comparar os snapshots 04-inject-mapping.yaml e 06-source-locals.yaml mostra o que os templates da Recipe veem no momento da avaliação.

Exemplos

Compilar uma Release com o catálogo local:

aggrega build --release releases/production.yaml

Compilar com um diretório de catálogo separado:

aggrega build --release releases/production.yaml --catalog ../platform-catalog/

Ver o que uma Release emitiria sem gravar nada:

aggrega build --release releases/production.yaml --dry-run

Compilar com dumps de trace para depuração:

aggrega build --release releases/production.yaml --trace

Após a compilação, inspecione .trace/boundaries/<boundary>/<instance>/ para ver o estado de cada passagem. O diretório .trace/ é sobrescrito a cada execução com --trace; o estado de trace anterior não é preservado entre compilações.

Referências cruzadas

  • aggrega-pull — busca entidades de catálogo de um registry OCI para o catálogo local.
  • aggrega-validate — verifica a correção do catálogo, do fechamento da Release ou de uma única entidade sem emitir artefatos; a validação de dependências que um build executa, sem a renderização.
  • aggrega-lint — verifica as convenções de publicação do catálogo nos mesmos três escopos.
  • aggrega-inspect — consulta o grafo IR após a finalização do grafo sem prosseguir para a renderização.
  • Erros — o formato categorizado de apresentação de erros que aparece na CLI.

Sinopse

aggrega build [flags]

Descrição

Compile an Aggregate and Release pair into provider-native artifacts under each
boundary's output directory.
The Release is the single entry point: it names the Aggregate and the Manifest,
declares the boundaries, and routes each component to a provider. What a
provider emits is the provider's own shape — Helm manifests, a redistributable
Helm chart, docker-compose YAML — so the output directory holds whatever the
providers this Release routes to produce.
The output directory is dist/ beneath the workspace root, whichever folder the
command is run from, and the closing line names it in full. A run that finds no
workspace uses the folder it was run from as the root, and writes dist/ there.
Build is read-only by default and needs a lockfile. Run "aggrega pull" first to
create one, or pass --auto-pull to fill it in-process for this build.
Given identical input, build writes byte-identical output, which is what makes
the rendered tree reviewable as a diff.

Flags

FlagPadrãoDescrição
--auto-pullfalseExecuta a etapa de pull antes do build: resolve as dependências da Release no lockfile e no cache dentro do processo e então faz o build com elas. É o mesmo preenchimento dentro do processo que a configuração auto_pull do workspace realiza, ativado para um único build sem editar a configuração do workspace. Sozinho, é um preenchimento incremental — os pins existentes são respeitados, e as referências sem pin são resolvidas e adicionadas
--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.
--debugfalseEmite em stderr diagnósticos detalhados legíveis por pessoas — tempo real por fase e contagens de entidades/dependências. Prevalece sobre —quiet: a saída detalhada é sempre emitida. Diferente de —trace, que grava arquivos intermediários por nó legíveis por máquina em .trace/
--detailfalseO build é somente leitura por padrão e não imprime detalhes de resolução. Quando a etapa de pull é executada — porque —auto-pull foi passado ou o workspace habilita auto_pull —, o build preenche o lockfile dentro do processo, exista ou não um, e esta flag imprime, para cada entidade resolvida, o que esse preenchimento fez: buscada do zero em um registry, reutilizou um slot do cache, encontrada em um catálogo local, servida de dentro do binário do compilador ou externa (o Aggregate ou o Manifest da própria Release, lido do arquivo ou da entrada que a Release nomeia). Quando nenhuma etapa de pull é executada, imprime uma linha dizendo isso em vez das linhas por entidade. Somente stdout; não persistido
--disable-plugin-cachefalseIgnora o cache persistente em disco de compilação de plugins para este build e compila os guests de plugins do zero em um cache em memória que é descartado quando o build termina. Desativado por padrão, o que reutiliza o cache compartilhado em disco entre builds. Não altera a saída renderizada
--dry-runfalseRenderiza a Release e imprime o que ela emitiria em vez de gravá-lo: o caminho previsto de cada artefato e seu conteúdo vão para stdout, e o diretório de saída e o lockfile permanecem intocados. As entradas externas se comportam exatamente como em um build comum — as entradas com pin são servidas do armazenamento endereçado por conteúdo (e reabastecidas pelo digest quando o blob está ausente), e uma renderização que solicita uma URL externa sem pin é interrompida nomeando-a —, de modo que o que um dry run mostra é o que um build gravaria. Recusa ser combinado com —auto-pull, —upgrade ou —trace, cada um dos quais grava — execute o preenchimento de dependências, ou um build com trace, como uma etapa própria. Combina-se com —policy-input, cujos arquivos passam a ser a única coisa que ele grava
--ir-graphfalseTambém grava em stdout, como JSON, o grafo IR que esta execução calculou, além de tudo o que este comando já produz. Os valores que um autor declarou sensíveis são ocultados nele; passe —unredacted para imprimi-los em vez disso. Os artefatos continuam sendo gravados e o resumo continua sendo impresso; o grafo é gravado antes de ambos
--no-unsupported-field-warningsfalseSilencia a classe de avisos de campos não suportados: os avisos que um destino emite para algo que você escreveu e que ele não consegue atender — um campo do Workload que ele não consegue expressar (como acontece com um destino 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 demais avisos de renderização continuam aparecendo. Apenas exibição; não altera a saída renderizada
--policy-input—Grava, neste diretório, o payload que cada papel de governança entrega a um plugin conectado ali, como uma linha de JSON: exatamente o que o build entrega ao plugin, com cada valor que o build oculta dele também oculto aqui. Para annotation-transform, label-transform e ir-verdict, o arquivo é o documento input que uma política nesse papel lê. Para render-verdict, o mecanismo de políticas remodela o payload antes que uma política o leia — os documents de cada artefato são analisados a partir dele —, então uma política render-verdict em um mecanismo integrado é testada em um build, conectada de modo a reportar em warn ou info; para um plugin cujo .wasm você mesmo compilou, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json o executa sobre esse arquivo. Um papel sem nada conectado também é gravado, como o payload que uma conexão sem fontes e sem configurações receberia, para que uma política possa ser escrita antes de ser conectada. Cada papel é gravado em <role>.json (annotation-transform, label-transform, ir-verdict, render-verdict); quando as conexões de um mesmo papel recebem payloads diferentes — uma carrega fontes ou configurações próprias, ou uma transformação muda o que a seguinte lê —, cada uma é gravada em <role>.<position>.<plugin>.json, em que position conta as conexões desse papel a partir de 1 na ordem em que a configuração do workspace as lista e plugin é o último segmento da referência do plugin sem a versão, com escape de todo caractere que um nome de arquivo não pode conter. Arquivos com esses nomes já presentes no diretório são substituídos e nada mais ali é tocado. Os arquivos são gravados quer o build termine, quer pare, e um build que para antes de um papel ser executado nomeia cada papel para o qual não gravou nenhum arquivo. Solicitá-los não altera nenhum artefato nem nenhum veredito. Combina-se com —dry-run, que então grava esses arquivos e nada mais: o diretório de saída e o lockfile permanecem intocados
--progressfalseForça a exibição do progresso do build mesmo quando stderr não é um terminal, imprimindo uma linha simples por etapa à medida que ela é concluída, com seu tempo. O padrão é auto: a checklist interativa de fases só é mostrada quando stderr é um terminal que interpreta sequências de escape, um terminal que não as interpreta recebe as mesmas linhas simples, e a saída redirecionada ou em pipe não recebe nenhuma. —quiet e —debug prevalecem ambos sobre —progress
--quietfalseSilencia a exibição do progresso do build em stderr. Não afeta stdout. Tem precedência sobre —progress
--release—Caminho para o arquivo YAML da Release (obrigatório). 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 é informada, um caminho absoluto encontra o workspace a partir da pasta da própria Release
--tracefalsegrava arquivos intermediários por nó em .trace/ sob a raiz do workspace, ao lado de dist/, para inspeção post-mortem
--trace-unredactedfalseGrava os valores declarados sensíveis nos arquivos .trace/ em vez do texto que os substitui, e marca cada arquivo que o trace grava com um cabeçalho que informa isso. Requer —trace. Alcança .trace/ e nada mais: artefatos renderizados, a saída de aggrega inspect e o texto de diagnóstico são idênticos com e sem ele. Apenas na invocação — não há nenhuma configuração do workspace para ele, então ele nunca pode ficar ativado para um build posterior
--unredactedfalseImprime os valores que um autor declarou sensíveis em vez de ocultá-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 grava e nada mais, então requer —ir-graph; os arquivos .trace/ usam —trace-unredacted em vez disso
--upgradefalseTorna a etapa de auto-pull uma atualização completa: descarta o lockfile existente e resolve novamente cada dependência a partir do estado atual do registry, levando cada uma à versão mais alta disponível em vez de respeitar os pins existentes. Implica —auto-pull — sozinho, executa um pull de atualização completa antes do build. Não aceita um destino, então não pode ser restrito a uma única dependência: para adotar ou remover um único pin, execute aggrega pull —upgrade —release em vez disso, que mantém todos os outros pins inalterados. Como descarta todos os pins registrados, pede confirmação primeiro; —yes responde antecipadamente, e com um stdin não interativo recusa em vez de esperar uma resposta que ninguém pode dar
--verify-determinismfalseRenderiza cada nó duas vezes e compara os bytes emitidos, interrompendo o build se as duas renderizações de algum nó forem diferentes. Desativado por padrão. Use-o para confirmar que um provider renderiza de forma determinística — entrada idêntica gera saída idêntica byte a byte —, algo em que se baseiam as garantias de diff do GitOps e de saída idêntica byte a byte
--yesfalseResponde antecipadamente à confirmação de —upgrade, para uso não interativo. Alcança essa única pergunta e nada mais: um build que não faz atualização não pergunta nada, então passá-lo ali não muda nenhum comportamento