Esquema do núcleo do Aggrega (Plugin)
Referência gerada. Não editar à mão — gerar novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/plugin-v1beta1.schema.json
Um plugin Wasm: um módulo WebAssembly publicado num registo OCI e identificado pelo seu metadata.pluginType — o socket que implementa — mais o seu metadata.name simples, que declara a versão de ABI a que se destina, um ponteiro de assinatura opcional e um bloco de runtime opcional. A entidade e o seu .wasm são publicados como um único manifesto OCI com a tag metadata.version — o YAML da entidade como blob de configuração do manifesto, o .wasm como uma camada inline, assinados uma única vez. A identidade é a coordenada metadata.pluginType/metadata.name mais a metadata.version da entidade; a localização do .wasm é derivada dessa coordenada mais o registo configurado, e o digest do conteúdo resolvido reside no ficheiro de bloqueio, não na entidade. O ficheiro de bloqueio regista o digest, e a política de confiança por registo verifica a assinatura do artefacto no pull. O compilador não interpreta o comportamento do plugin — encaminha a referência; o runtime WebAssembly executa os bytes.
Consulte-se a referência de autoria do Plugin para orientações em prosa sobre como escrever entidades Plugin; esta página documenta o esquema estrutural que essa referência descreve.
Tipo de nível superior: object
Propriedades
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | sim | Constante: "aggrega.ai/v1beta1" |
kind | const “Plugin” | sim | Constante: "Plugin" |
metadata | objeto | sim | |
spec | objeto | sim | A versão de ABI a que o plugin se destina, um ponteiro opcional para uma assinatura e um bloco runtime opcional. A localização do .wasm do plugin é derivada da identidade do plugin — o seu metadata.pluginType (o socket) mais o seu metadata.name simples — e do registo configurado; não consta da spec. |
Não são permitidas propriedades adicionais.
plugin.metadata
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | Pelo menos 1 carácter. |
version | string | sim | Versionamento semântico estrito da entidade Plugin (por exemplo, 1.0.0). Padrão: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
pluginType | string (enum) | sim | O tipo de socket que este plugin implementa. Um plugin implementa exatamente um tipo de socket, retirado da taxonomia de tipos de plugin que o runtime reconhece: provider (renderiza nós da IR em artefactos nativos do fornecedor), linter (inspeciona o conteúdo criado pelos autores e emite diagnósticos), pipeline-step (um passo no pipeline: de uma FeatureRecipe ou de uma Recipe que aplica patches ao conjunto de documentos renderizados), governance (serve os papéis de governação do pipeline de compilação — transformando as etiquetas dos nós na construção da topologia, ou emitindo um veredicto de aceitação/rejeição sobre o grafo da IR na análise estática ou sobre os artefactos renderizados na renderização; é o papel a que está anexado, e não o seu tipo, que determina o que pode emitir), cli (contribui com um subcomando de runtime aggrega <cmd> que um operador invoca na linha de comandos — um socket de runtime, distinto dos sockets de renderização e de pipeline em tempo de compilação), parser (transforma um texto de origem externo numa árvore estruturada canónica para que um consumidor leia a árvore sem ter de trazer o seu próprio parser da linguagem, anunciando os formatos que trata como capacidades parse:<format>), importer (transforma uma fonte externa de infraestrutura ou de definição de agentes em ficheiros de criação Aggrega provisórios, anunciando os formatos que trata como capacidades import:<format>). Valores permitidos: "provider", "linter", "pipeline-step", "governance", "cli", "parser", "importer" |
description | string | não | O que esta entidade é e para que serve, escrito para quem está a decidir se a vai usar. Convém começar por uma frase que nomeie a coisa e acrescentar depois o que um leitor precisa para a escolher e usar corretamente — o que espera da compilação que a executa, e tudo o que seja surpreendente no seu comportamento. Um parágrafo curto é a extensão habitual. |
maintainers | object[] | não | Lista dos responsáveis pela manutenção desta entidade. |
license | string | não | Identificador SPDX da licença do software que esta entidade descreve, como MIT ou AGPL-3.0. Regista os termos desse software, não os termos deste ficheiro. |
repository | string | não | O URL do repositório Git onde se encontram os ficheiros de origem. |
home | string | não | O URL da página inicial, da wiki ou da documentação desta entidade. |
keywords | string[] | não | Uma lista de palavras-chave descritivas para facilitar a descoberta na interface do utilizador. |
Não são permitidas propriedades adicionais.
plugin.metadata.maintainers[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | |
email | string | não | |
url | string | não |
Não são permitidas propriedades adicionais.
plugin.spec
A versão de ABI a que o plugin se destina, um ponteiro opcional para uma assinatura e um bloco runtime opcional. A localização do .wasm do plugin é derivada da identidade do plugin — o seu metadata.pluginType (o socket) mais o seu metadata.name simples — e do registo configurado; não consta da spec.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
abiVersion | string (enum) | sim | A versão de ABI host/guest a que o plugin se destina. v1beta1 é o único valor aceite; um Plugin que declare uma versão de ABI que este compilador já não fala é recusado, com a indicação da versão para a qual recompilar o plugin. Valores permitidos: "v1beta1" |
signature | objeto | não | Um ponteiro descritivo opcional para a assinatura anexada do plugin. Este bloco é apenas documentação — regista, para os leitores do catálogo, onde está a assinatura e como foi produzida; não bloqueia nem admite, por si só, o plugin. A verificação que efetivamente se aplica é a política de confiança por registo aplicada no pull: uma assinatura é obtida como referrer OCI, verificada face às identidades de confiança ou à chave fixada do registo, e registada como um facto verificado no ficheiro de bloqueio. Um registo que exige assinaturas interrompe o pull quando uma assinatura exigida está em falta, não é de confiança ou é inválida. |
runtime | objeto | não | Restrições de execução opcionais que o anfitrião aplica ao carregar e executar o plugin. O acesso de saída à rede não é um campo de autoria: um plugin nunca acede à rede em tempo de compilação (o limite ahead-of-time), pelo que não há aqui nenhum campo de lista de anfitriões permitidos a preencher. |
exports | object[] | não | As exportações que este plugin oferece, cada uma com a sua capacidade declarada. Uma exportação é um ponto de entrada com nome para o qual o anfitrião despacha (por exemplo, render_node, lint_naming, step); o bloco de capacidade por exportação é a afirmação criada sobre o que essa exportação faz, que o anfitrião verifica face ao autorrelatório do plugin na publicação e no carregamento. As entradas preservam a ordem de criação. A ausência não declara nenhuma superfície de exportação criada. |
commands | object[] | não | Gerido pela máquina, não deve ser escrito à mão: registado por aggrega plugin sync (ou aggrega plugin gen-catalog) a partir do autorrelatório do plugin. Os verbos de nível superior aggrega <command> com que um plugin de CLI contribui são lidos do autorrelatório do plugin e registados aqui pela ordem em que o autorrelatório os declara, pelo que a superfície de comandos com que um plugin de CLI se instala pode ser lida a partir da entidade sem carregar o plugin. Um plugin que não é de CLI não contribui com comandos e regista uma lista vazia. O anfitrião instala exatamente este conjunto; um conjunto registado que diverge do autorrelatório do plugin interrompe o carregamento, e a publicação recusa um conjunto dessincronizado do binário e indica ao autor que o volte a registar. |
provider | objeto | não | O bloco do socket de fornecedor de um plugin pluginType: provider: as capacidades que serve, como traduz o tipo Workload de aggrega.ai/v1beta1, que anotações nativas da plataforma lê e o seu contrato de comportamento de renderização. Só está presente em plugins de renderização de fornecedor; está ausente em qualquer outro tipo de plugin. |
pipelineStep | objeto | não | O bloco de pipeline-step de um plugin pluginType: pipeline-step: as capacidades do fornecedor com as quais o seu passo é compatível. Só está presente em plugins de pipeline-step; está ausente em qualquer outro tipo de plugin. |
parser | objeto | não | O bloco de parser de um plugin pluginType: parser: os formatos de origem que transforma numa árvore estruturada canónica. Só está presente em plugins de parser; está ausente em qualquer outro tipo de plugin. |
importer | objeto | não | O bloco de importador de um plugin pluginType: importer: os formatos de origem externos que transforma em ficheiros de criação Aggrega provisórios, e as assinaturas pelas quais se reconhece uma fonte nesses formatos. Só está presente em plugins de importador; está ausente em qualquer outro tipo de plugin. |
Não são permitidas propriedades adicionais.
plugin.spec.signature
Um ponteiro descritivo opcional para a assinatura anexada do plugin. Este bloco é apenas documentação — regista, para os leitores do catálogo, onde está a assinatura e como foi produzida; não bloqueia nem admite, por si só, o plugin. A verificação que efetivamente se aplica é a política de confiança por registo aplicada no pull: uma assinatura é obtida como referrer OCI, verificada face às identidades de confiança ou à chave fixada do registo, e registada como um facto verificado no ficheiro de bloqueio. Um registo que exige assinaturas interrompe o pull quando uma assinatura exigida está em falta, não é de confiança ou é inválida.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
type | const “sigstore-cosign” | sim | O esquema de assinatura. sigstore-cosign é o esquema suportado. Constante: "sigstore-cosign" |
signatureRef | string | não | A referência de referrer OCI do bundle de assinatura anexado, para documentação e descoberta. Ausente quando a assinatura é descoberta pela enumeração de referrers no pull, em vez de ser fixada aqui. |
publicKeyRef | string | não | Um ponteiro para a chave pública com que a assinatura foi produzida, para uma assinatura com chave. A ausência indica uma assinatura sem chave (identidade OIDC), verificada face às identidades de confiança do registo. |
Não são permitidas propriedades adicionais.
plugin.spec.runtime
Restrições de execução opcionais que o anfitrião aplica ao carregar e executar o plugin. O acesso de saída à rede não é um campo de autoria: um plugin nunca acede à rede em tempo de compilação (o limite ahead-of-time), pelo que não há aqui nenhum campo de lista de anfitriões permitidos a preencher.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
maxMemoryPages | integer | não | Limita a memória linear do plugin em páginas Wasm (64 KiB por página). Zero ou a ausência aplica o limite máximo predefinido da plataforma, pelo que um carregamento nunca é ilimitado; um anexo que precise de mais aumenta este valor. Mínimo: 0. |
timeoutMs | integer | não | Limita durante quanto tempo o próprio código do plugin pode ser executado numa chamada, em milissegundos, sem contar o tempo passado dentro das funções do anfitrião que chama. Em Linux, a medida é o tempo de processador, pelo que o tempo passado à espera de um processador numa máquina ocupada não conta; noutros sistemas, é o tempo decorrido. A primeira chamada a um plugin acabado de carregar conta também o próprio arranque do plugin. Zero ou a ausência aplica o limite máximo predefinido da plataforma, pelo que uma chamada nunca é impossível de cancelar; um anexo que seja executado durante mais tempo aumenta este valor. Mínimo: 0. |
hostFunctions | string[] | não | Gerido pela máquina, não deve ser escrito à mão: as funções do anfitrião que o plugin importa, lidas da secção de importação do .wasm por aggrega plugin sync (ou aggrega plugin gen-catalog) e registadas aqui em forma canónica (ordenada, sem duplicados). A publicação volta a derivá-las do binário e recusa uma entidade cujo registo difira; o pull volta a derivá-las e verifica-as novamente. O anfitrião regista exatamente este conjunto derivado e valida cada entrada face à allowlist curada. |
configKV | mapa de string | não | Configuração específica do Plugin que o runtime entrega ao plugin no arranque, como pares chave/valor de string para string. As entradas preservam a ordem de criação, pelo que o registo emitido é idêntico byte a byte entre execuções. A ausência mantém em vigor a configuração vazia predefinida do runtime. |
Não são permitidas propriedades adicionais.
plugin.spec.exports[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | O nome ABI da exportação — o nome para o qual o anfitrião despacha (por exemplo, render_node, lint_naming, step). Pelo menos 1 carácter. |
operates | string (enum) | não | A operação de pipeline que esta exportação realiza: patch (modificar um documento renderizado existente) ou emit (acrescentar um novo documento). A ausência não contém nenhuma afirmação sobre a operação. Valores permitidos: "patch", "emit" |
scope | string (enum) | não | A raiz de documentos sobre a qual esta exportação opera: own (os documentos renderizados próprios do nó) ou host (os documentos do componente a que está anexada uma FeatureRecipe com âmbito de componente). A ausência não contém nenhuma afirmação sobre o âmbito. Valores permitidos: "own", "host" |
selector | string | não | Uma descrição livre e legível por pessoas daquilo sobre que a exportação atua (por exemplo, workloads carrying a pod template). Documentação para os leitores do catálogo; o compilador não a interpreta. |
Não são permitidas propriedades adicionais.
plugin.spec.commands[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | O verbo de comando que o anfitrião regista — o token aggrega <name> que um operador invoca, e o discriminador que o anfitrião entrega ao plugin na invocação para que um único plugin que suporta vários comandos encaminhe consoante o comando chamado. Pelo menos 1 carácter. |
description | string | não | O texto de ajuda breve do comando, numa linha, mostrado na listagem de comandos e na saída da ajuda. Apenas documentação; o host não age com base nele. |
flags | object[] | não | As flags do comando, pela ordem declarada. Cada entrada contribui com uma flag que o anfitrião regista no comando para que aggrega help --help, -h e as flags globais; o anfitrião verifica isto quando acrescenta os comandos do plugin, e um plugin cujas declarações falhem não é acrescentado, com um aviso. |
Não são permitidas propriedades adicionais.
plugin.spec.commands[].flags[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | O nome longo da flag — o token —name que um operador passa na linha de comandos. Todas as flags declaradas têm de o indicar. Pelo menos 1 carácter. |
shorthand | string | não | O alias curto opcional da flag — a forma -x que um operador pode passar em vez do nome longo — como uma única letra ou um único algarismo ASCII. A ausência significa que a flag não tem alias curto. Padrão: ^[A-Za-z0-9]$. |
description | string | não | O texto de ajuda de uma linha da flag, apresentado na saída de ajuda do comando. É documentação opcional; o anfitrião não o valida nem age com base nele. |
type | string (enum) | não | O tipo de valor da flag — string, bool ou int — e o tipo de flag como o qual a ajuda a apresenta. A ausência apresenta-a como uma flag de string. Valores permitidos: "string", "bool", "int" |
default | string | não | O valor predefinido da flag quando o operador não a passa, expresso como string. Para uma flag bool ou int, é um valor desse tipo. Se ausente, a flag não declara valor predefinido. |
Não são permitidas propriedades adicionais.
plugin.spec.provider
O bloco do socket de fornecedor de um plugin pluginType: provider: as capacidades que serve, como traduz o tipo Workload de aggrega.ai/v1beta1, que anotações nativas da plataforma lê e o seu contrato de comportamento de renderização. Só está presente em plugins de renderização de fornecedor; está ausente em qualquer outro tipo de plugin.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
capabilities | string[] | não | Registada a partir do autorrelatório do .wasm do plugin por aggrega plugin gen-catalog, pelo que o plugin é a origem desta lista. Um autor pode restringi-la antes de publicar, removendo uma entrada que esta entidade não deva oferecer, e não pode acrescentar nenhuma que o autorrelatório não nomeie: a publicação, e aggrega validate quando recebe o .wasm do plugin com --plugin, recusam uma lista que nomeie uma capacidade que o autorrelatório não nomeia. A publicação envia a entidade tal como está escrita, sem nunca reescrever esta lista, e assinala cada capacidade que o autorrelatório nomeia e que a lista deixa de fora. As capacidades que este fornecedor serve — nomes de capacidade como helm ou compose — cuja forma de saída renderiza. Um fornecedor é genérico entre artefactos que partilham a forma de saída de uma capacidade, não entre todas as capacidades, pelo que a lista é uma afirmação explícita de compatibilidade testada, e não uma aspiração. As entradas preservam a ordem de criação. O destino de fornecedor pedido por uma Recipe é resolvido para o plugin de fornecedor cuja lista contém esse destino; um destino listado por mais de um plugin de fornecedor interrompe a compilação por ambiguidade, a menos que a seleção plugins.providers da configuração do espaço de trabalho indique que plugin usar. Uma lista vazia ou ausente não declara nenhuma capacidade, pelo que o plugin não serve nenhum destino. |
workloadSchema | string | não | JSON Schema 2020-12 que documenta como este fornecedor traduz o tipo Workload de aggrega.ai/v1beta1 em manifestos nativos do fornecedor. Quando presente, o fornecedor suporta Recipes que declaram um bloco workload: (modo sintetizado) — o fornecedor traduz o Workload em manifestos nativos do fornecedor, orientado por este esquema como documentação/contrato. Se uma Recipe com workload: é suportada é determinado pela capacidade de síntese do fornecedor associado, e não pela presença deste campo: uma Recipe em modo sintetizado associada a um fornecedor que não consegue sintetizar é interrompida de forma bem visível no momento da renderização. O catálogo da biblioteca padrão declara workloadSchema nos fornecedores que sintetizam como o contrato documentado, mantido em sincronia com essa capacidade. O campo é o contrato documentado: o corpo é compilado para JSON Schema 2020-12 no carregamento para verificar se está bem formado, e nada mais o lê. |
wellKnownAnnotations | object[] | não | A declaração de suporte do fornecedor: as chaves de anotação bem conhecidas nativas da plataforma (o namespace aggrega.ai/) que este fornecedor lê, cada uma com o âmbito em que é lida e o comportamento aplicado quando está ausente. Convém declarar uma chave apenas onde o fornecedor a lê — a matriz de suporte publicada é renderizada a partir destas declarações, pelo que uma chave listada aqui é uma chave que um autor pode esperar que altere a saída renderizada no âmbito que nomeia. O compilador lê a declaração de duas formas: um scope que nomeie um tipo de entrada que o próprio contract.inputKinds do fornecedor não declara contradiz uma afirmação adjacente na mesma entidade, e a compilação é interrompida, nomeando a chave e a contradição; e uma compilação emite um aviso sobre uma anotação aggrega.ai/ que chega a uma renderização através deste fornecedor quando nenhuma entrada a cobre em nenhum tipo de entrada que essa renderização declare. É distinta da regra que rege a associação de um valor sob o prefixo reservado aggrega.ai/. A ausência não declara nenhum suporte, e não é emitido nenhum aviso desse tipo para este fornecedor; um fornecedor que não lê nenhuma destas chaves declara readsNoWellKnownAnnotations em vez desta lista. As entradas são uma lista ordenada e preservam a ordem de criação. |
readsNoWellKnownAnnotations | const true | não | Declara que este fornecedor não lê nenhuma das chaves de anotação nativas da plataforma no namespace aggrega.ai/, as chaves que wellKnownAnnotations listaria de outro modo: uma declaração de suporte que não cobre nenhuma chave, o que é uma afirmação, ao passo que omitir tanto este campo como wellKnownAnnotations é silêncio. Uma compilação emite então um aviso sobre cada anotação aggrega.ai/ que chega a uma renderização através deste fornecedor, nomeando a chave, o fornecedor e os tipos de entrada que essa renderização declara; o valor passa mesmo assim intacto e a compilação não é interrompida. Só se pode escrever true, pelo que omitir o campo continua a ser a única forma de não dizer nada. Não pode ser escrito juntamente com wellKnownAnnotations: um fornecedor que lê algumas das chaves lista-as aí em vez disso. Constante: true |
contract | objeto | não | O contrato de comportamento de renderização autodeclarado do fornecedor: os tipos de entrada que renderiza, como monta a saída por nó de um grupo de despacho e sob que diretórios essa saída fica, o par de delimitadores de template que aplica aos ficheiros de artefactos importados, se uma única instância carregada pode servir cada travessia, se liga arestas entre fronteiras, se respeita as entradas de omissão, se aceita os ficheiros com que uma Recipe contribui para a saída partilhada da sua fronteira, e que ficheiros o seu ecossistema nunca entrega junto a uma fonte. É o registo, no momento da publicação, do autorrelatório do plugin de fornecedor, que o anfitrião verifica face a esse mesmo autorrelatório na publicação e no carregamento. A ausência não declara nenhum contrato de comportamento de renderização, e a verificação cruzada compara apenas as afirmações por exportação. |
Não são permitidas propriedades adicionais.
plugin.spec.provider.wellKnownAnnotations[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
key | string | sim | A chave de anotação bem conhecida nativa da plataforma que o fornecedor lê (por exemplo, aggrega.ai/namespace). Fica sob o namespace de anotações aggrega.ai/ reservado à plataforma — as diretivas de plataforma lidas pelo fornecedor. Padrão: ^aggrega\.ai/.+. |
purpose | string | sim | O que a anotação controla — o comportamento de renderização que influencia quando está presente. |
defaultBehavior | string | não | O comportamento que o fornecedor aplica quando esta anotação está ausente. |
scope | string (enum)[] | não | Onde este fornecedor lê a chave. Os três primeiros valores são os tipos de entrada da Recipe e nomeiam o caminho de renderização em que a chave é lida — sourced um conjunto de ficheiros vendorizados, synthesized um Workload que o fornecedor materializa, artifactsStandalone um nó cuja saída inteira são documentos de artefactos importados. Cada um deles tem de ser um tipo de entrada que o contract.inputKinds deste fornecedor declara; nomear um que não declara interrompe a compilação. boundary destina-se a uma chave resolvida uma vez por fronteira em vez de por nó — o nome de um artefacto montado, ou o contexto de posicionamento a partir do qual se forma uma referência entre fronteiras —, onde o tipo de entrada não é um eixo significativo, pelo que não é comparada com contract.inputKinds. Uma chave lida em mais de um caminho lista-os todos. A ausência não faz nenhuma afirmação por caminho: nada é verificado, e a chave afirma apenas que o fornecedor a lê algures. Pelo menos 1 entrada. Nenhuma entrada pode aparecer duas vezes. Valores permitidos para cada entrada: "sourced", "synthesized", "artifactsStandalone", "boundary". |
Não são permitidas propriedades adicionais.
plugin.spec.provider.contract
O contrato de comportamento de renderização autodeclarado do fornecedor: os tipos de entrada que renderiza, como monta a saída por nó de um grupo de despacho e sob que diretórios essa saída fica, o par de delimitadores de template que aplica aos ficheiros de artefactos importados, se uma única instância carregada pode servir cada travessia, se liga arestas entre fronteiras, se respeita as entradas de omissão, se aceita os ficheiros com que uma Recipe contribui para a saída partilhada da sua fronteira, e que ficheiros o seu ecossistema nunca entrega junto a uma fonte. É o registo, no momento da publicação, do autorrelatório do plugin de fornecedor, que o anfitrião verifica face a esse mesmo autorrelatório na publicação e no carregamento. A ausência não declara nenhum contrato de comportamento de renderização, e a verificação cruzada compara apenas as afirmações por exportação.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
inputKinds | objeto | não | Quais dos três tipos de entrada de Recipe este plugin renderiza: um conjunto de ficheiros com fonte, uma carga de trabalho sintetizada e um nó autónomo só de artefactos. Cada campo é uma afirmação independente. |
boundaryAssembly | string (enum) | não | Como o plugin combina a saída de renderização por nó de um grupo de despacho: none escreve a saída de cada nó diretamente no caminho de despacho; merge funde os fragmentos por nó num único documento; nest coloca a saída de cada nó na sua própria posição dentro de uma estrutura guarda-chuva. Se estiver ausente, não contém nenhuma afirmação de montagem. Valores permitidos: "none", "merge", "nest" |
artifactDelimiters | objeto | não | O par de delimitadores de template Go que o plugin aplica aos ficheiros de artefactos importados. Se estiver ausente, vale o par predefinido {{/}}; um plugin cuja sintaxe de destino colide com esse par declara aqui um par alternativo. |
assemblyNameAnnotation | objeto | não | A anotação de fronteira cujo valor resolvido nomeia o artefacto que o plugin monta a partir de um grupo de despacho. Um plugin que reúne as fronteiras contribuintes de um grupo numa única montagem com nome declara a chave de anotação que lê e se cada fronteira contribuinte tem de concordar quanto ao valor resolvido dessa anotação. Se estiver ausente, o plugin dá nome à sua montagem apenas a partir do caminho de despacho. |
reusableInstance | booleana | não | Se uma única instância carregada do plugin pode servir cada travessia de renderização, montagem e validação de uma compilação, em vez de uma instância nova por travessia. Declara-se true apenas quando o plugin não mantém estado entre travessias — uma função pura da sua entrada por travessia —, de modo que uma única instância produz uma saída idêntica byte a byte, quer seja reutilizada quer seja carregada de novo. Se estiver ausente (false), é carregada uma instância nova por travessia, o que isola por construção um plugin que contém estado. |
crossBoundaryLinking | booleana | não | Se o plugin liga uma aresta uses entre fronteiras — uma aresta uses cujas extremidades consumidora e consumida são montadas em grupos de despacho diferentes — ao emitir uma ligação de referências cruzadas nativa do fornecedor através de um contrato de exportação emparelhado link_publish/link_resolve. Declara-se true apenas quando o plugin exporta ambos; uma afirmação que não corresponde ao par de exportações interrompe o carregamento. Se estiver ausente (false), não declara nenhuma ligação entre fronteiras, pelo que o anfitrião não encaminha nenhuma travessia de ligação para o plugin. |
omits | booleana | não | Se o fornecedor respeita as entradas de omissão — entradas que nomeiam unidades renderizadas a deixar de fora da saída de um nó: deixa de fora daquilo que renderiza cada unidade a que uma entrada corresponde, e reporta a quantas unidades cada entrada correspondeu. É o registo, no momento da publicação, da afirmação omits que o autorrelatório do fornecedor faz, e um valor que difere desse autorrelatório interrompe o carregamento. Se estiver ausente (false), não declara tal suporte. |
boundaryArtifacts | booleana | não | Se o fornecedor aceita os ficheiros com que uma Recipe contribui para a saída partilhada da fronteira em que é renderizada, sob o spec.boundary.artifacts da Recipe: o compilador escreve cada um desses ficheiros uma única vez, no diretório que contém a saída montada da fronteira, e o destino do fornecedor trata-o como parte dessa saída. É o registo, no momento da publicação, da afirmação boundary_artifacts que o autorrelatório do fornecedor faz, e um valor que difere desse autorrelatório interrompe o carregamento. Se estiver ausente (false), não declara tal suporte, e uma Recipe que declara o bloco para este fornecedor é recusada antes de qualquer coisa ser renderizada. |
nestSegment | string | não | O diretório sob o qual o destino deste fornecedor coloca o subdiretório próprio de cada contribuidor, para um fornecedor cujo boundaryAssembly é nest — charts para um chart guarda-chuva, modules para um módulo raiz. O compilador junta este diretório, o nome do contribuidor e o caminho próprio de cada ficheiro. Só é lido para um fornecedor que aninha. Se estiver ausente, o subdiretório de cada contribuidor é colocado diretamente no diretório próprio da fronteira. O valor nomeia um único diretório e nunca um caminho. |
sourceIgnore | objeto | não | Os ficheiros que o ecossistema deste fornecedor nunca entrega junto a uma fonte que renderiza, como regras ignore em sintaxe gitignore — o registo, no momento da publicação, das regras source_ignore que o seu autorrelatório declara. Quando um autor fixa uma Recipe ou uma FeatureRecipe cuja capacidade este fornecedor serve para ele, essas regras são compostas com o .aggregaignore próprio do autor e registadas no entity.lock junto à entidade, juntamente com o nome deste plugin, e cada publicação, comparação e renderização posterior da fonte local da entidade aplica as regras registadas. Quando presente, tem de ser igual ao que o autorrelatório declara, e o carregamento recusa um plugin cujo autorrelatório difere; se estiver ausente, não afirma nada e não é comparado. |
Não são permitidas propriedades adicionais.
plugin.spec.provider.contract.inputKinds
Quais dos três tipos de entrada de Recipe este plugin renderiza: um conjunto de ficheiros com fonte, uma carga de trabalho sintetizada e um nó autónomo só de artefactos. Cada campo é uma afirmação independente.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
sourced | booleana | não | Renderiza um conjunto de ficheiros com fonte (um chart, um módulo, um ficheiro compose). |
synthesized | booleana | não | Renderiza uma carga de trabalho sintetizada em artefactos nativos do fornecedor. |
artifactsStandalone | booleana | não | Renderiza um nó autónomo só de artefactos — um que contém documentos de artefactos importados e nenhuma fonte nem carga de trabalho. |
Não são permitidas propriedades adicionais.
plugin.spec.provider.contract.artifactDelimiters
O par de delimitadores de template Go que o plugin aplica aos ficheiros de artefactos importados. Se estiver ausente, vale o par predefinido {{/}}; um plugin cuja sintaxe de destino colide com esse par declara aqui um par alternativo.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
left | string | sim | O delimitador de abertura. |
right | string | sim | O delimitador de fecho. |
Não são permitidas propriedades adicionais.
plugin.spec.provider.contract.assemblyNameAnnotation
A anotação de fronteira cujo valor resolvido nomeia o artefacto que o plugin monta a partir de um grupo de despacho. Um plugin que reúne as fronteiras contribuintes de um grupo numa única montagem com nome declara a chave de anotação que lê e se cada fronteira contribuinte tem de concordar quanto ao valor resolvido dessa anotação. Se estiver ausente, o plugin dá nome à sua montagem apenas a partir do caminho de despacho.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
annotation | string | sim | A chave da anotação de fronteira a partir da qual o plugin lê o nome do artefacto montado. |
requireUnique | booleana | não | Se cada fronteira que contribui para um mesmo grupo de despacho tem de concordar quanto ao valor resolvido da anotação. Quando true, um grupo cujas fronteiras contribuintes resolvem a anotação para valores diferentes interrompe a compilação; quando false, o plugin aceita o primeiro valor resolvido. |
Não são permitidas propriedades adicionais.
plugin.spec.provider.contract.sourceIgnore
Os ficheiros que o ecossistema deste fornecedor nunca entrega junto a uma fonte que renderiza, como regras ignore em sintaxe gitignore — o registo, no momento da publicação, das regras source_ignore que o seu autorrelatório declara. Quando um autor fixa uma Recipe ou uma FeatureRecipe cuja capacidade este fornecedor serve para ele, essas regras são compostas com o .aggregaignore próprio do autor e registadas no entity.lock junto à entidade, juntamente com o nome deste plugin, e cada publicação, comparação e renderização posterior da fonte local da entidade aplica as regras registadas. Quando presente, tem de ser igual ao que o autorrelatório declara, e o carregamento recusa um plugin cujo autorrelatório difere; se estiver ausente, não afirma nada e não é comparado.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
patterns | string[] | não | Os padrões ignore próprios do ecossistema, cada um com âmbito na raiz do diretório da fonte local, pela ordem em que se aplicam. |
files | string[] | não | Os nomes dos ficheiros ignore que o ecossistema respeita dentro de uma fonte — .helmignore para um chart. As linhas de cada um desses ficheiros são padrões adicionais, com âmbito no diretório que o contém. |
Não são permitidas propriedades adicionais.
plugin.spec.pipelineStep
O bloco de pipeline-step de um plugin pluginType: pipeline-step: as capacidades do fornecedor com as quais o seu passo é compatível. Só está presente em plugins de pipeline-step; está ausente em qualquer outro tipo de plugin.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
capabilities | string[] | não | Registada a partir do autorrelatório do .wasm do plugin por aggrega plugin gen-catalog, pelo que o plugin é a origem desta lista. Um autor pode restringi-la antes de publicar, removendo uma entrada que esta entidade não deva oferecer, e não pode acrescentar nenhuma que o autorrelatório não nomeie: a publicação, e aggrega validate quando recebe o .wasm do plugin com --plugin, recusam uma lista que nomeie uma capacidade que o autorrelatório não nomeia. A publicação envia a entidade tal como está escrita, sem nunca reescrever esta lista, e assinala cada capacidade que o autorrelatório nomeia e que a lista deixa de fora. As capacidades de fornecedor com as quais o passo de pipeline deste plugin é compatível — os nomes de capacidades de fornecedor, como helm ou compose, cuja saída renderizada o passo sabe transformar. Um passo é escrito para a forma de saída de um único fornecedor de cada vez, pelo que a lista é uma afirmação explícita de compatibilidade testada, e não uma aspiração. As entradas preservam a ordem de criação. É o registo legível pelo catálogo dessa afirmação; a compilação lê a mesma afirmação a partir do plugin quando um passo toca num âmbito e é interrompida quando o fornecedor que renderiza os documentos desse âmbito não está entre elas. Uma lista vazia ou ausente não declara nenhuma compatibilidade, pelo que nenhum âmbito admite o passo. |
Não são permitidas propriedades adicionais.
plugin.spec.parser
O bloco de parser de um plugin pluginType: parser: os formatos de origem que transforma numa árvore estruturada canónica. Só está presente em plugins de parser; está ausente em qualquer outro tipo de plugin.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
capabilities | string[] | não | Registada a partir do autorrelatório do .wasm do plugin por aggrega plugin gen-catalog, pelo que o plugin é a origem desta lista. Um autor pode restringi-la antes de publicar, removendo uma entrada que esta entidade não deva oferecer, e não pode acrescentar nenhuma que o autorrelatório não nomeie: a publicação, e aggrega validate quando recebe o .wasm do plugin com --plugin, recusam uma lista que nomeie uma capacidade que o autorrelatório não nomeia. A publicação envia a entidade tal como está escrita, sem nunca reescrever esta lista, e assinala cada capacidade que o autorrelatório nomeia e que a lista deixa de fora. Os formatos de origem que este parser transforma numa árvore estruturada canónica, cada um escrito como parse:<format> — por exemplo parse:yaml. O prefixo faz parte da entrada, pelo que um plugin que anuncia vários formatos lista uma entrada por formato. As entradas preservam a ordem de criação. Um formato pedido é resolvido para o parser cuja lista contém a entrada correspondente; um formato que nenhum parser anuncia interrompe a compilação, e um formato anunciado por mais de um plugin parser interrompe a compilação por ambiguidade. Uma lista vazia ou ausente não declara nenhum formato, pelo que o plugin não analisa nada. |
Não são permitidas propriedades adicionais.
plugin.spec.importer
O bloco de importador de um plugin pluginType: importer: os formatos de origem externos que transforma em ficheiros de criação Aggrega provisórios, e as assinaturas pelas quais se reconhece uma fonte nesses formatos. Só está presente em plugins de importador; está ausente em qualquer outro tipo de plugin.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
capabilities | string[] | não | Registada a partir do autorrelatório do .wasm do plugin por aggrega plugin gen-catalog, pelo que o plugin é a origem desta lista. Um autor pode restringi-la antes de publicar, removendo uma entrada que esta entidade não deva oferecer, e não pode acrescentar nenhuma que o autorrelatório não nomeie: a publicação, e aggrega validate quando recebe o .wasm do plugin com --plugin, recusam uma lista que nomeie uma capacidade que o autorrelatório não nomeia. A publicação envia a entidade tal como está escrita, sem nunca reescrever esta lista, e assinala cada capacidade que o autorrelatório nomeia e que a lista deixa de fora. Os formatos de origem externos que este importador transforma em ficheiros de criação Aggrega provisórios, cada um escrito como import:<format> — por exemplo import:terraform. O prefixo faz parte da entrada, pelo que um plugin que anuncia vários formatos lista uma entrada por formato. As entradas preservam a ordem de criação. Um formato de importação pedido é resolvido para o importador cuja lista contém a entrada correspondente; um formato que nenhum importador anuncia interrompe a importação, e um formato anunciado por mais de um plugin importador interrompe a importação por ambiguidade, a menos que uma entrada plugins.importer na configuração do espaço de trabalho associe um deles, que é então executado. Uma lista vazia ou ausente não declara nenhum formato, pelo que o plugin não importa nada. |
detect | object[] | não | Gerido pela máquina, não deve ser escrito à mão: derivado do autorrelatório do .wasm do plugin quando a entidade é gerada a partir dele, e registado aqui pela ordem em que o autorrelatório as declara. As assinaturas pelas quais se reconhece uma fonte dos formatos deste importador quando uma importação não nomeia nenhum formato. aggrega import lê as assinaturas de cada importador que o catálogo do espaço de trabalho contém, todas as versões incluídas, e dos importadores do núcleo do compilador, compara-as com a fonte sem saber o que é qualquer formato, e lê a fonte como o formato do único importador cuja assinatura corresponde; uma fonte à qual nenhuma assinatura corresponde é recusada com um pedido do formato, e uma fonte à qual correspondem assinaturas de mais de um formato é recusada com a indicação desses formatos. Um importador que reconhece uma fonte reconhece-a como cada formato que anuncia, pelo que, para um importador que anuncia mais de um formato, toda a correspondência é recusada por ambiguidade. Quando presente, a lista tem de ser igual ao que o autorrelatório do plugin declara, entrada a entrada e pela mesma ordem, e o carregamento e a publicação recusam um plugin cujo autorrelatório difere, nomeando este campo. Se estiver ausente, não afirma nada e não é comparada, e os formatos do importador só são então alcançados quando nomeados. |
Não são permitidas propriedades adicionais.
plugin.spec.importer.detect[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
syntax | string | sim | O formato sintático como o qual a fonte é analisada — json ou yaml, por exemplo —, que é o formato que um plugin parser anuncia como parse:<syntax>. A fonte é analisada pelo parser que o catálogo do espaço de trabalho oferece para essa sintaxe ou, para uma sintaxe para a qual o catálogo não oferece nenhum, por aquele que o compilador traz consigo, no máximo uma vez, seja qual for o número de assinaturas que nomeiam a sintaxe, e uma fonte que não pode ser analisada nela não corresponde a nenhuma assinatura que a nomeie. Uma sintaxe para a qual nenhum dos dois oferece um parser interrompe o reconhecimento, nomeando a ausência desse parser. Pelo menos 1 carácter. |
files | string[] | não | Os padrões de nome de ficheiro aos quais a assinatura se aplica, comparados com o final do nome da fonte com os seus separadores lidos como barras: um padrão de um único segmento com o nome próprio do ficheiro, e um padrão de vários segmentos separados por barras com o mesmo número de segmentos finais do seu caminho, de modo que .vscode/mcp.json corresponde a um ficheiro chamado mcp.json num diretório chamado .vscode. Dentro de um segmento, * corresponde a qualquer sequência de caracteres, ? a um carácter e [...] a um carácter de uma classe. A assinatura aplica-se quando qualquer padrão corresponde. Se estiver ausente ou vazio, a assinatura aplica-se a uma fonte que é um único ficheiro, seja qual for o seu nome, e a nenhum ficheiro de um diretório. Os padrões das assinaturas de um importador são também o que decide que ficheiros de um diretório aggrega import lhe passa. |
match | object[] | não | Os predicados que a árvore analisada tem de satisfazer, todos eles, pela ordem declarada. Se estiver ausente ou vazio, não exige nada da árvore além de ser analisável na sintaxe. |
Não são permitidas propriedades adicionais.
plugin.spec.importer.detect[].match[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
path | string | sim | O ponto da árvore onde o predicado procura, escrito como chaves unidas por pontos a partir do topo da árvore: data.nodes nomeia o membro nodes do objeto data de nível superior. Um segmento escrito como número inteiro, 0 ou maior, seleciona essa posição de um array a contar a partir de zero, de modo que nodes.0.type nomeia o tipo do primeiro nó; qualquer outro segmento seleciona um membro de um objeto. Pelo menos 1 carácter. |
is | string (enum) | sim | O que o caminho tem de alcançar: present é satisfeito quando alcança um valor de qualquer tipo, null incluído; absent é satisfeito quando não alcança nada; object, array, string, number e boolean são satisfeitos, cada um, quando alcança um valor desse tipo. Valores permitidos: "present", "absent", "object", "array", "string", "number", "boolean" |
equals | string | não | Uma string à qual o valor alcançado pelo caminho tem de ser exatamente igual; um valor que não é uma string nunca é igual a ela. No máximo um de entre equals e prefix é declarado num predicado. Pelo menos 1 carácter. |
prefix | string | não | Uma string pela qual o valor alcançado pelo caminho tem de começar; um valor que não é uma string nunca começa por ela. No máximo um de entre equals e prefix é declarado num predicado. Pelo menos 1 carácter. |
Não são permitidas propriedades adicionais.