Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Schéma du cœur d’Aggrega (Plugin)

Référence générée. Ne pas modifier à la main — régénérer à partir du JSON Schema publié.

Identifiant du schéma : https://aggrega.ai/schemas/plugin-v1beta1.schema.json

Un plugin Wasm : un module WebAssembly publié dans un registre OCI et identifié par son metadata.pluginType — le socket qu’il implémente — plus son metadata.name nu, qui déclare la version d’ABI qu’il cible, un pointeur de signature facultatif et un bloc runtime facultatif. L’entité et son .wasm sont publiés sous la forme d’un seul manifeste OCI tagué par metadata.version — le YAML de l’entité comme blob de configuration du manifeste, le .wasm comme couche inline, signés une seule fois. L’identité est la coordonnée metadata.pluginType/metadata.name plus la metadata.version de l’entité ; l’emplacement du .wasm est dérivé de cette coordonnée plus le registre configuré, et le digest de contenu résolu se trouve dans le fichier de verrouillage, non dans l’entité. Le fichier de verrouillage enregistre le digest, et la politique de confiance propre à chaque registre vérifie la signature de l’artefact lors du pull. Le compilateur n’interprète pas le comportement du plugin — il route la référence ; le runtime WebAssembly exécute les octets.

Consultez la référence de rédaction du Plugin pour des conseils rédigés sur l’écriture des entités Plugin ; cette page documente le schéma structurel que décrit cette référence.

Type de premier niveau : object

Propriétés

PropriétéTypeObligatoireDescription
apiVersionconst “aggrega.ai/v1beta1”ouiConstante : "aggrega.ai/v1beta1"
kindconst “Plugin”ouiConstante : "Plugin"
metadataobjectoui
specobjectouiLa version d’ABI que cible le plugin, un pointeur de signature facultatif et un bloc runtime facultatif. L’emplacement du .wasm du plugin est dérivé de l’identité du plugin — son metadata.pluginType (le socket) plus son metadata.name nu — et du registre configuré ; il n’est pas porté dans la spec.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.metadata

PropriétéTypeObligatoireDescription
namestringouiAu moins 1 caractère.
versionstringouiVersionnage sémantique strict de l’entité Plugin (par ex. 1.0.0). Motif : ^(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-]+)*))?$.
pluginTypestring (enum)ouiLe type de socket que ce plugin implémente. Un plugin implémente exactement un type de socket, pris dans la taxonomie des types de plugins que reconnaît le runtime : provider (rend les nœuds de l’IR en artefacts natifs du fournisseur), linter (inspecte le contenu rédigé et émet des diagnostics), pipeline-step (une étape du pipeline: d’une FeatureRecipe ou d’une Recipe qui applique des patchs à l’ensemble de documents rendus), governance (sert les rôles de gouvernance du pipeline de build — transformer les labels des nœuds lors de la construction de la topologie, ou rendre un verdict d’acceptation/rejet sur le graphe de l’IR lors de l’analyse statique ou sur les artefacts rendus lors du rendu ; c’est le rôle auquel il est rattaché, et non son type, qui détermine ce qu’il peut émettre), cli (ajoute une sous-commande runtime aggrega <cmd> qu’un opérateur invoque en ligne de commande — un socket de runtime, distinct des sockets de rendu et de pipeline au moment de la compilation), parser (transforme un texte source externe en un arbre structuré canonique afin qu’un consommateur lise l’arbre sans embarquer son propre parseur du langage, en annonçant les formats qu’il gère sous forme de capacités parse:<format>), importer (transforme une source externe d’infrastructure ou de définition d’agent en brouillons de fichiers de rédaction Aggrega, en annonçant les formats qu’il gère sous forme de capacités import:<format>). Valeurs autorisées : "provider", "linter", "pipeline-step", "governance", "cli", "parser", "importer"
descriptionstringnonCe qu’est cette entité et à quoi elle sert, écrit pour quelqu’un qui décide s’il va l’utiliser. Commencez par une phrase qui nomme la chose, puis ajoutez ce dont un lecteur a besoin pour la choisir et l’utiliser correctement — ce qu’elle attend du build qui l’exécute, et tout ce que son comportement a de surprenant. Un court paragraphe est la longueur habituelle.
maintainersobject[]nonListe des mainteneurs responsables de cette entité.
licensestringnonIdentifiant SPDX de la licence du logiciel que décrit cette entité, par exemple MIT ou AGPL-3.0. Il consigne les conditions de ce logiciel, pas celles de ce fichier.
repositorystringnonL’URL du dépôt Git où se trouvent les fichiers source.
homestringnonL’URL de la page d’accueil, du wiki ou de la documentation de cette entité.
keywordsstring[]nonUne liste de mots-clés descriptifs pour la découvrabilité dans l’interface utilisateur.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.metadata.maintainers[]
PropriétéTypeObligatoireDescription
namestringoui
emailstringnon
urlstringnon

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec

La version d’ABI que cible le plugin, un pointeur de signature facultatif et un bloc runtime facultatif. L’emplacement du .wasm du plugin est dérivé de l’identité du plugin — son metadata.pluginType (le socket) plus son metadata.name nu — et du registre configuré ; il n’est pas porté dans la spec.

PropriétéTypeObligatoireDescription
abiVersionstring (enum)ouiLa version d’ABI hôte/guest que cible le plugin. v1beta1 est la seule valeur acceptée ; un Plugin déclarant une version d’ABI que ce compilateur ne parle plus est refusé, avec le nom de la version pour laquelle reconstruire le plugin. Valeurs autorisées : "v1beta1"
signatureobjectnonUn pointeur descriptif facultatif vers la signature attachée du plugin. Ce bloc n’est que de la documentation — il indique aux lecteurs du catalogue où se trouve la signature et comment elle a été produite ; il ne filtre ni n’admet lui-même le plugin. Le contrôle qui fait foi est la politique de confiance propre à chaque registre appliquée lors du pull : une signature est récupérée comme referrer OCI, vérifiée par rapport aux identités de confiance ou à la clé épinglée du registre, et enregistrée comme fait vérifié dans le fichier de verrouillage. Un registre qui exige des signatures arrête le pull lorsqu’une signature requise est manquante, non fiable ou invalide.
runtimeobjectnonContraintes d’exécution facultatives que l’hôte applique lors du chargement et de l’exécution du plugin. L’accès réseau sortant n’est pas un champ de rédaction : un plugin n’atteint jamais le réseau au moment du build (la limite ahead-of-time), il n’y a donc ici aucun champ de liste d’hôtes autorisés à rédiger.
exportsobject[]nonLes exports que ce plugin propose, chacun avec sa capacité déclarée. Un export est un point d’entrée nommé vers lequel l’hôte aiguille les appels (par exemple render_node, lint_naming, step) ; le bloc de capacité par export est la déclaration rédigée de ce que fait cet export, que l’hôte compare à l’auto-déclaration du plugin lors de la publication et du chargement. Les entrées conservent l’ordre de l’auteur. S’il est absent, aucune surface d’export rédigée n’est déclarée.
commandsobject[]nonGéré par la machine, à ne pas rédiger : enregistré par aggrega plugin sync (ou aggrega plugin gen-catalog) à partir de l’auto-déclaration du plugin. Les verbes de premier niveau aggrega <command> qu’ajoute un plugin CLI sont lus dans l’auto-déclaration du plugin et enregistrés ici dans l’ordre où l’auto-déclaration les déclare, de sorte que la surface de commandes sous laquelle un plugin CLI s’installe est lisible depuis l’entité sans charger le plugin. Un plugin non CLI n’ajoute aucune commande et enregistre une liste vide. L’hôte installe exactement cet ensemble ; un ensemble enregistré qui diverge de l’auto-déclaration du plugin provoque un arrêt au chargement, et la publication refuse un ensemble désynchronisé du binaire et invite l’auteur à l’enregistrer de nouveau.
providerobjectnonLe bloc du socket fournisseur pour un plugin pluginType: provider : les capacités qu’il sert, la façon dont il traduit le type Workload aggrega.ai/v1beta1, les annotations natives de la plateforme qu’il lit, et son contrat de comportement de rendu. Présent uniquement sur les plugins de rendu de fournisseur ; absent sur tout autre type de plugin.
pipelineStepobjectnonLe bloc pipeline-step pour un plugin pluginType: pipeline-step : les capacités de fournisseur avec lesquelles son étape est compatible. Présent uniquement sur les plugins pipeline-step ; absent sur tout autre type de plugin.
parserobjectnonLe bloc parser pour un plugin pluginType: parser : les formats source qu’il transforme en arbre structuré canonique. Présent uniquement sur les plugins parser ; absent sur tout autre type de plugin.
importerobjectnonLe bloc importer pour un plugin pluginType: importer : les formats source externes qu’il transforme en brouillons de fichiers de rédaction Aggrega, et les signatures auxquelles on reconnaît une source dans ces formats. Présent uniquement sur les plugins importer ; absent sur tout autre type de plugin.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.signature

Un pointeur descriptif facultatif vers la signature attachée du plugin. Ce bloc n’est que de la documentation — il indique aux lecteurs du catalogue où se trouve la signature et comment elle a été produite ; il ne filtre ni n’admet lui-même le plugin. Le contrôle qui fait foi est la politique de confiance propre à chaque registre appliquée lors du pull : une signature est récupérée comme referrer OCI, vérifiée par rapport aux identités de confiance ou à la clé épinglée du registre, et enregistrée comme fait vérifié dans le fichier de verrouillage. Un registre qui exige des signatures arrête le pull lorsqu’une signature requise est manquante, non fiable ou invalide.

PropriétéTypeObligatoireDescription
typeconst “sigstore-cosign”ouiLe schéma de signature. sigstore-cosign est le schéma pris en charge. Constante : "sigstore-cosign"
signatureRefstringnonLa référence du referrer OCI du bundle de signature attaché, à des fins de documentation et de découverte. Absente lorsque la signature est découverte par énumération des referrers lors du pull au lieu d’être épinglée ici.
publicKeyRefstringnonUn pointeur vers la clé publique avec laquelle la signature a été produite, pour une signature par clé. Son absence indique une signature sans clé (identité OIDC), vérifiée par rapport aux identités de confiance du registre.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.runtime

Contraintes d’exécution facultatives que l’hôte applique lors du chargement et de l’exécution du plugin. L’accès réseau sortant n’est pas un champ de rédaction : un plugin n’atteint jamais le réseau au moment du build (la limite ahead-of-time), il n’y a donc ici aucun champ de liste d’hôtes autorisés à rédiger.

PropriétéTypeObligatoireDescription
maxMemoryPagesintegernonPlafonne la mémoire linéaire du plugin en pages Wasm (64 KiB par page). Zéro ou une absence applique le plafond par défaut de la plateforme, de sorte qu’un chargement n’est jamais illimité ; un rattachement qui a besoin de plus relève cette valeur. Minimum : 0.
timeoutMsintegernonPlafonne la durée pendant laquelle le code propre du plugin peut s’exécuter au cours d’un appel, en millisecondes, sans compter le temps passé dans les fonctions hôtes qu’il appelle. Sous Linux, la mesure est le temps processeur, de sorte que le temps passé à attendre un processeur sur une machine chargée ne compte pas ; sur les autres systèmes, c’est le temps écoulé. Le premier appel à un plugin fraîchement chargé compte aussi le démarrage propre du plugin. Zéro ou une absence applique le plafond par défaut de la plateforme, de sorte qu’un appel n’est jamais impossible à annuler ; un rattachement qui s’exécute plus longtemps relève cette valeur. Minimum : 0.
hostFunctionsstring[]nonGéré par la machine, à ne pas rédiger : les fonctions hôtes que le plugin importe, lues dans la section d’import du .wasm par aggrega plugin sync (ou aggrega plugin gen-catalog) et enregistrées ici sous forme canonique (triée, dédupliquée). La publication les redérive du binaire et refuse une entité dont l’enregistrement diffère ; le pull les redérive et les vérifie de nouveau. L’hôte enregistre exactement cet ensemble dérivé et valide chaque entrée par rapport à la liste d’autorisation organisée.
configKVmap de stringnonConfiguration propre au Plugin que le runtime transmet au plugin au démarrage, sous forme de paires clé/valeur de chaîne à chaîne. Les entrées conservent l’ordre de l’auteur afin que l’enregistrement émis soit identique octet pour octet d’une exécution à l’autre. Son absence laisse en vigueur la configuration vide par défaut du runtime.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.exports[]
PropriétéTypeObligatoireDescription
namestringouiLe nom ABI de l’export — le nom vers lequel l’hôte aiguille les appels (par exemple render_node, lint_naming, step). Au moins 1 caractère.
operatesstring (enum)nonL’opération de pipeline qu’effectue cet export : patch (modifier un document rendu existant) ou emit (ajouter un nouveau document). S’il est absent, aucune opération n’est déclarée. Valeurs autorisées : "patch", "emit"
scopestring (enum)nonLa racine de documents sur laquelle opère cet export : own (les documents rendus propres au nœud) ou host (les documents du composant auquel est rattachée une FeatureRecipe de portée composant). S’il est absent, aucune portée n’est déclarée. Valeurs autorisées : "own", "host"
selectorstringnonUne description libre et lisible par un humain de ce sur quoi agit l’export (par exemple workloads carrying a pod template). Documentation pour les lecteurs du catalogue ; le compilateur ne l’interprète pas.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.commands[]
PropriétéTypeObligatoireDescription
namestringouiLe verbe de commande que l’hôte enregistre — le jeton aggrega <name> qu’un opérateur invoque, et le discriminant que l’hôte transmet au plugin lors de l’invocation afin qu’un plugin unique qui prend en charge plusieurs commandes route selon la commande appelée. Au moins 1 caractère.
descriptionstringnonLe texte d’aide court, sur une ligne, de la commande, affiché dans la liste des commandes et dans la sortie d’aide. Documentation uniquement ; l’hôte n’en tient pas compte.
flagsobject[]nonLes flags de la commande, dans l’ordre déclaré. Chaque entrée ajoute un flag que l’hôte enregistre sur la commande afin que la commande aggrega help l’affiche comme le flag d’une commande intégrée. Une commande sans flags laisse la liste vide. Au sein d’une commande, chaque nom de flag et chaque forme abrégée n’apparaît qu’une fois, et aucun ne réutilise un flag que possède déjà toute commande aggrega — --help, -h et les flags globaux ; l’hôte le vérifie lorsqu’il ajoute les commandes du plugin, et un plugin dont les déclarations échouent n’est pas ajouté, avec un avertissement.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.commands[].flags[]
PropriétéTypeObligatoireDescription
namestringouiLe nom long du flag — le jeton —name qu’un opérateur passe sur la ligne de commande. Chaque flag déclaré doit l’indiquer. Au moins 1 caractère.
shorthandstringnonL’alias court facultatif du flag — la forme -x qu’un opérateur peut passer à la place du nom long — sous la forme d’une seule lettre ou d’un seul chiffre ASCII. Son absence signifie que le flag n’a pas d’alias court. Motif : ^[A-Za-z0-9]$.
descriptionstringnonLe texte d’aide d’une ligne du flag, affiché dans la sortie d’aide de la commande. C’est une documentation facultative ; l’hôte ne la valide pas et n’agit pas en fonction d’elle.
typestring (enum)nonLe type de valeur du flag — string, bool ou int — et le genre de flag sous lequel l’aide l’affiche. S’il est absent, il est affiché comme un flag de type chaîne. Valeurs autorisées : "string", "bool", "int"
defaultstringnonLa valeur par défaut du flag lorsque l’opérateur ne le passe pas, exprimée sous forme de chaîne. Pour un flag bool ou int, c’est une valeur de ce type. Si elle est absente, le flag ne déclare aucune valeur par défaut.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.provider

Le bloc du socket fournisseur pour un plugin pluginType: provider : les capacités qu’il sert, la façon dont il traduit le type Workload aggrega.ai/v1beta1, les annotations natives de la plateforme qu’il lit, et son contrat de comportement de rendu. Présent uniquement sur les plugins de rendu de fournisseur ; absent sur tout autre type de plugin.

PropriétéTypeObligatoireDescription
capabilitiesstring[]nonEnregistrée à partir de l’auto-déclaration du .wasm du plugin par aggrega plugin gen-catalog, de sorte que le plugin est la source de cette liste. Un auteur peut la restreindre avant la publication, en retirant une entrée que cette entité ne doit pas proposer, et ne peut en ajouter aucune que l’auto-déclaration ne nomme pas : la publication, et aggrega validate auquel on fournit le .wasm du plugin avec --plugin, refusent une liste qui nomme une capacité que l’auto-déclaration ne nomme pas. La publication envoie l’entité telle qu’elle est écrite, sans jamais réécrire cette liste, et signale chaque capacité que nomme l’auto-déclaration et que la liste laisse de côté. Les capacités que sert ce fournisseur — des noms de capacités comme helm ou compose — dont il rend la forme de sortie. Un fournisseur est générique pour les artefacts qui partagent la forme de sortie d’une capacité, et non pour toutes les capacités, de sorte que la liste est une déclaration explicite de compatibilité testée plutôt qu’une aspiration. Les entrées conservent l’ordre de l’auteur. La cible de fournisseur demandée par une Recipe se résout vers le plugin fournisseur dont la liste contient cette cible ; une cible listée par plus d’un plugin fournisseur provoque un arrêt pour ambiguïté, sauf si la sélection plugins.providers de la configuration de l’espace de travail indique quel plugin utiliser. Une liste vide ou absente ne déclare aucune capacité, de sorte que le plugin ne sert aucune cible.
workloadSchemastringnonJSON Schema 2020-12 documentant la façon dont ce fournisseur traduit le type Workload aggrega.ai/v1beta1 en manifestes natifs du fournisseur. Lorsqu’il est présent, le fournisseur prend en charge les Recipes qui déclarent un bloc workload: (mode synthétisé) — le fournisseur traduit le Workload en manifestes natifs du fournisseur, en s’appuyant sur ce schéma comme documentation/contrat. La prise en charge d’une Recipe workload: est déterminée par la capacité de synthèse du fournisseur lié, et non par la présence de ce champ : une Recipe en mode synthétisé liée à un fournisseur qui ne peut pas synthétiser s’arrête de façon bien visible au moment du rendu. Le catalogue de la bibliothèque standard déclare workloadSchema sur les fournisseurs qui synthétisent comme contrat documenté, tenu en phase avec cette capacité. Le champ est le contrat documenté : le corps est compilé en JSON Schema 2020-12 au chargement pour vérifier qu’il est bien formé, et rien d’autre ne le lit.
wellKnownAnnotationsobject[]nonLa déclaration de prise en charge du fournisseur : les clés d’annotation bien connues natives de la plateforme (le namespace aggrega.ai/) que lit ce fournisseur, chacune avec la portée à laquelle elle est lue et le comportement appliqué lorsqu’elle est absente. Ne déclarez une clé que là où le fournisseur la lit — la matrice de prise en charge publiée est rendue à partir de ces déclarations, de sorte qu’une clé listée ici est une clé dont un auteur peut attendre qu’elle modifie la sortie rendue à la portée qu’elle nomme. Le compilateur lit la déclaration de deux façons : un scope nommant un type d’entrée que le contract.inputKinds propre au fournisseur ne revendique pas contredit une déclaration voisine dans la même entité, et le build s’arrête en nommant la clé et la contradiction ; et un build avertit d’une annotation aggrega.ai/ qui atteint un rendu via ce fournisseur lorsqu’aucune entrée ne la couvre sur l’un quelconque des types d’entrée que ce rendu déclare. Elle est distincte de la règle qui régit la liaison d’une valeur sous le préfixe réservé aggrega.ai/. Son absence ne déclare aucune prise en charge, et aucun avertissement de ce genre n’est émis pour ce fournisseur ; un fournisseur qui ne lit aucune de ces clés déclare readsNoWellKnownAnnotations au lieu de cette liste. Les entrées forment une liste ordonnée et conservent l’ordre de l’auteur.
readsNoWellKnownAnnotationsconst truenonDéclare que ce fournisseur ne lit aucune des clés d’annotation natives de la plateforme dans le namespace aggrega.ai/, les clés que wellKnownAnnotations listerait sinon : une déclaration de prise en charge ne couvrant aucune clé, qui est une affirmation là où omettre à la fois ce champ et wellKnownAnnotations est un silence. Un build avertit alors de chaque annotation aggrega.ai/ qui atteint un rendu via ce fournisseur, en nommant la clé, le fournisseur et les types d’entrée que ce rendu déclare ; la valeur passe tout de même sans modification et le build ne s’arrête pas. Seul true peut être écrit, de sorte qu’omettre le champ reste la seule façon de ne rien dire. Il ne peut pas être écrit avec wellKnownAnnotations : un fournisseur qui lit certaines des clés liste plutôt celles-ci là-bas. Constante : true
contractobjectnonLe contrat de comportement de rendu auto-déclaré du fournisseur : les types d’entrée qu’il rend, la façon dont il assemble la sortie par nœud d’un groupe d’aiguillage et sous quels répertoires cette sortie se trouve, la paire de délimiteurs de template qu’il applique aux fichiers d’artefacts importés, si une seule instance chargée peut servir chaque franchissement, s’il câble des arêtes inter-frontières, s’il respecte les entrées d’exclusion, s’il accepte les fichiers qu’une Recipe apporte à la sortie partagée de sa frontière, et quels fichiers son écosystème ne livre jamais à côté d’une source. C’est l’enregistrement, au moment de la publication, de l’auto-déclaration du plugin fournisseur, que l’hôte compare à cette même auto-déclaration lors de la publication et du chargement. Son absence ne déclare aucun contrat de comportement de rendu, et la comparaison ne porte que sur les déclarations par export.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.provider.wellKnownAnnotations[]
PropriétéTypeObligatoireDescription
keystringouiLa clé d’annotation bien connue native de la plateforme que lit le fournisseur (par ex. aggrega.ai/namespace). Elle se trouve sous le namespace d’annotations aggrega.ai/ réservé à la plateforme — les directives de plateforme lues par le fournisseur. Motif : ^aggrega\.ai/.+.
purposestringouiCe que contrôle l’annotation — le comportement de rendu qu’elle influence lorsqu’elle est présente.
defaultBehaviorstringnonLe comportement que le fournisseur applique lorsque cette annotation est absente.
scopestring (enum)[]nonOù ce fournisseur lit la clé. Les trois premières valeurs sont les types d’entrée de la Recipe et nomment le chemin de rendu sur lequel la clé est lue — sourced un ensemble de fichiers vendorisés, synthesized un Workload que le fournisseur matérialise, artifactsStandalone un nœud dont toute la sortie est constituée de documents d’artefacts importés. Chacune d’elles doit être un type d’entrée que revendique le contract.inputKinds de ce fournisseur ; en nommer une qu’il ne revendique pas arrête le build. boundary sert à une clé résolue une fois par frontière plutôt que par nœud — le nom d’un artefact assemblé, ou le contexte de placement à partir duquel une référence inter-frontières est formée — là où le type d’entrée n’est pas un axe pertinent, de sorte qu’elle n’est pas comparée à contract.inputKinds. Une clé lue sur plus d’un chemin les liste tous. Son absence ne fait aucune déclaration par chemin : rien n’est vérifié, et la clé indique seulement que le fournisseur la lit quelque part. Au moins 1 entrée. Aucune entrée ne peut apparaître deux fois. Valeurs autorisées pour chaque entrée : "sourced", "synthesized", "artifactsStandalone", "boundary".

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.provider.contract

Le contrat de comportement de rendu auto-déclaré du fournisseur : les types d’entrée qu’il rend, la façon dont il assemble la sortie par nœud d’un groupe d’aiguillage et sous quels répertoires cette sortie se trouve, la paire de délimiteurs de template qu’il applique aux fichiers d’artefacts importés, si une seule instance chargée peut servir chaque franchissement, s’il câble des arêtes inter-frontières, s’il respecte les entrées d’exclusion, s’il accepte les fichiers qu’une Recipe apporte à la sortie partagée de sa frontière, et quels fichiers son écosystème ne livre jamais à côté d’une source. C’est l’enregistrement, au moment de la publication, de l’auto-déclaration du plugin fournisseur, que l’hôte compare à cette même auto-déclaration lors de la publication et du chargement. Son absence ne déclare aucun contrat de comportement de rendu, et la comparaison ne porte que sur les déclarations par export.

PropriétéTypeObligatoireDescription
inputKindsobjectnonLesquels des trois types d’entrée de Recipe ce plugin rend : un ensemble de fichiers avec source, une charge de travail synthétisée et un nœud autonome composé uniquement d’artefacts. Chaque champ est une déclaration indépendante.
boundaryAssemblystring (enum)nonComment le plugin combine la sortie de rendu par nœud d’un groupe d’aiguillage : none écrit la sortie de chaque nœud directement au chemin d’aiguillage ; merge fusionne les fragments par nœud en un seul document ; nest place la sortie de chaque nœud à sa propre position dans une structure parapluie. S’il est absent, il ne porte aucune déclaration d’assemblage. Valeurs autorisées : "none", "merge", "nest"
artifactDelimitersobjectnonLa paire de délimiteurs de template Go que le plugin applique aux fichiers d’artefacts importés. S’il est absent, la paire par défaut {{/}} s’applique ; un plugin dont la syntaxe cible entre en collision avec cette paire déclare ici une paire alternative.
assemblyNameAnnotationobjectnonL’annotation de frontière dont la valeur résolue nomme l’artefact que le plugin assemble à partir d’un groupe d’aiguillage. Un plugin qui réunit les frontières contributrices d’un groupe en un seul assemblage nommé déclare la clé d’annotation qu’il lit et indique si chaque frontière contributrice doit s’accorder sur la valeur résolue de cette annotation. S’il est absent, le plugin nomme son assemblage à partir du seul chemin d’aiguillage.
reusableInstancebooléennonIndique si une seule instance chargée du plugin peut servir chaque franchissement de rendu, d’assemblage et de validation d’un build plutôt qu’une nouvelle instance par franchissement. À déclarer true uniquement lorsque le plugin ne conserve aucun état d’un franchissement à l’autre — une fonction pure de son entrée par franchissement — de sorte qu’une seule instance produit une sortie identique octet pour octet, qu’elle soit réutilisée ou chargée à neuf. S’il est absent (false), une nouvelle instance est chargée par franchissement, ce qui isole par construction un plugin qui porte un état.
crossBoundaryLinkingbooléennonIndique si le plugin câble une arête uses inter-frontières — une arête uses dont les extrémités consommatrice et consommée sont assemblées dans des groupes d’aiguillage différents — en émettant un câblage de références croisées natif du fournisseur au moyen d’un contrat d’export apparié link_publish/link_resolve. À déclarer true uniquement lorsque le plugin exporte les deux ; une déclaration qui ne correspond pas à la paire d’exports provoque un arrêt au chargement. S’il est absent (false), aucune liaison inter-frontières n’est déclarée, de sorte que l’hôte n’achemine aucun franchissement de liaison vers le plugin.
omitsbooléennonIndique si le fournisseur respecte les entrées d’exclusion — des entrées qui nomment des unités rendues à exclure de la sortie d’un nœud : il exclut de ce qu’il rend chaque unité à laquelle une entrée correspond, et indique à combien d’unités chaque entrée a correspondu. C’est l’enregistrement, au moment de la publication, de la déclaration omits que fait l’auto-déclaration du fournisseur, et une valeur qui diffère de cette auto-déclaration provoque un arrêt au chargement. S’il est absent (false), aucune prise en charge de ce type n’est déclarée.
boundaryArtifactsbooléennonIndique si le fournisseur accepte les fichiers qu’une Recipe apporte à la sortie partagée de la frontière dans laquelle elle est rendue, sous le spec.boundary.artifacts de la Recipe : le compilateur écrit chacun de ces fichiers une seule fois, dans le répertoire qui contient la sortie assemblée de la frontière, et la cible du fournisseur le traite comme faisant partie de cette sortie. C’est l’enregistrement, au moment de la publication, de la déclaration boundary_artifacts que fait l’auto-déclaration du fournisseur, et une valeur qui diffère de cette auto-déclaration provoque un arrêt au chargement. S’il est absent (false), aucune prise en charge de ce type n’est déclarée, et une Recipe qui déclare le bloc pour ce fournisseur est refusée avant que quoi que ce soit ne soit rendu.
nestSegmentstringnonLe répertoire sous lequel la cible de ce fournisseur place le sous-répertoire propre de chaque contributeur, pour un fournisseur dont le boundaryAssembly est nest — charts pour un chart parapluie, modules pour un module racine. Le compilateur joint ce répertoire, le nom du contributeur et le chemin propre de chaque fichier. N’est lu que pour un fournisseur qui imbrique. S’il est absent, le sous-répertoire de chaque contributeur est placé directement dans le répertoire propre de la frontière. La valeur nomme un seul répertoire et jamais un chemin.
sourceIgnoreobjectnonLes fichiers que l’écosystème de ce fournisseur ne livre jamais à côté d’une source qu’il rend, sous forme de règles ignore en syntaxe gitignore — l’enregistrement, au moment de la publication, des règles source_ignore que déclare son auto-déclaration. Lorsqu’un auteur épingle une Recipe ou une FeatureRecipe dont ce fournisseur sert la capacité pour lui, ces règles sont composées avec le .aggregaignore propre de l’auteur et enregistrées dans l’entity.lock à côté de l’entité, avec le nom de ce plugin, et chaque publication, comparaison et rendu ultérieur de la source locale de l’entité applique les règles enregistrées. Lorsqu’il est présent, il doit être égal à ce que déclare l’auto-déclaration, et le chargement refuse un plugin dont l’auto-déclaration diffère ; absent, il ne déclare rien et n’est pas comparé.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.provider.contract.inputKinds

Lesquels des trois types d’entrée de Recipe ce plugin rend : un ensemble de fichiers avec source, une charge de travail synthétisée et un nœud autonome composé uniquement d’artefacts. Chaque champ est une déclaration indépendante.

PropriétéTypeObligatoireDescription
sourcedbooléennonRend un ensemble de fichiers avec source (un chart, un module, un fichier compose).
synthesizedbooléennonRend une charge de travail synthétisée en artefacts natifs du fournisseur.
artifactsStandalonebooléennonRend un nœud autonome composé uniquement d’artefacts — un nœud qui porte des documents d’artefacts importés et ni source ni charge de travail.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.provider.contract.artifactDelimiters

La paire de délimiteurs de template Go que le plugin applique aux fichiers d’artefacts importés. S’il est absent, la paire par défaut {{/}} s’applique ; un plugin dont la syntaxe cible entre en collision avec cette paire déclare ici une paire alternative.

PropriétéTypeObligatoireDescription
leftstringouiLe délimiteur ouvrant.
rightstringouiLe délimiteur fermant.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.provider.contract.assemblyNameAnnotation

L’annotation de frontière dont la valeur résolue nomme l’artefact que le plugin assemble à partir d’un groupe d’aiguillage. Un plugin qui réunit les frontières contributrices d’un groupe en un seul assemblage nommé déclare la clé d’annotation qu’il lit et indique si chaque frontière contributrice doit s’accorder sur la valeur résolue de cette annotation. S’il est absent, le plugin nomme son assemblage à partir du seul chemin d’aiguillage.

PropriétéTypeObligatoireDescription
annotationstringouiLa clé d’annotation de frontière à partir de laquelle le plugin lit le nom de l’artefact assemblé.
requireUniquebooléennonIndique si chaque frontière qui contribue à un même groupe d’aiguillage doit s’accorder sur la valeur résolue de l’annotation. Lorsqu’il vaut true, un groupe dont les frontières contributrices résolvent l’annotation en valeurs différentes arrête le build ; lorsqu’il vaut false, le plugin accepte la première valeur résolue.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.provider.contract.sourceIgnore

Les fichiers que l’écosystème de ce fournisseur ne livre jamais à côté d’une source qu’il rend, sous forme de règles ignore en syntaxe gitignore — l’enregistrement, au moment de la publication, des règles source_ignore que déclare son auto-déclaration. Lorsqu’un auteur épingle une Recipe ou une FeatureRecipe dont ce fournisseur sert la capacité pour lui, ces règles sont composées avec le .aggregaignore propre de l’auteur et enregistrées dans l’entity.lock à côté de l’entité, avec le nom de ce plugin, et chaque publication, comparaison et rendu ultérieur de la source locale de l’entité applique les règles enregistrées. Lorsqu’il est présent, il doit être égal à ce que déclare l’auto-déclaration, et le chargement refuse un plugin dont l’auto-déclaration diffère ; absent, il ne déclare rien et n’est pas comparé.

PropriétéTypeObligatoireDescription
patternsstring[]nonLes motifs ignore propres à l’écosystème, chacun limité à la racine du répertoire de la source locale, dans l’ordre où ils s’appliquent.
filesstring[]nonLes noms des fichiers ignore que l’écosystème respecte à l’intérieur d’une source — .helmignore pour un chart. Les lignes de chacun de ces fichiers sont des motifs supplémentaires, limités au répertoire qui le contient.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.pipelineStep

Le bloc pipeline-step pour un plugin pluginType: pipeline-step : les capacités de fournisseur avec lesquelles son étape est compatible. Présent uniquement sur les plugins pipeline-step ; absent sur tout autre type de plugin.

PropriétéTypeObligatoireDescription
capabilitiesstring[]nonEnregistrée à partir de l’auto-déclaration du .wasm du plugin par aggrega plugin gen-catalog, de sorte que le plugin est la source de cette liste. Un auteur peut la restreindre avant la publication, en retirant une entrée que cette entité ne doit pas proposer, et ne peut en ajouter aucune que l’auto-déclaration ne nomme pas : la publication, et aggrega validate auquel on fournit le .wasm du plugin avec --plugin, refusent une liste qui nomme une capacité que l’auto-déclaration ne nomme pas. La publication envoie l’entité telle qu’elle est écrite, sans jamais réécrire cette liste, et signale chaque capacité que nomme l’auto-déclaration et que la liste laisse de côté. Les capacités de fournisseur avec lesquelles l’étape de pipeline de ce plugin est compatible — les noms de capacités de fournisseur, comme helm ou compose, dont l’étape sait transformer la sortie rendue. Une étape est écrite pour la forme de sortie d’un seul fournisseur à la fois, de sorte que la liste est une déclaration explicite de compatibilité testée plutôt qu’une aspiration. Les entrées conservent l’ordre de l’auteur. C’est l’enregistrement lisible par le catalogue de cette déclaration ; le build lit la même déclaration depuis le plugin lorsqu’une étape touche une portée et s’arrête lorsque le fournisseur qui rend les documents de cette portée n’en fait pas partie. Une liste vide ou absente ne déclare aucune compatibilité, de sorte qu’aucune portée n’admet l’étape.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.parser

Le bloc parser pour un plugin pluginType: parser : les formats source qu’il transforme en arbre structuré canonique. Présent uniquement sur les plugins parser ; absent sur tout autre type de plugin.

PropriétéTypeObligatoireDescription
capabilitiesstring[]nonEnregistrée à partir de l’auto-déclaration du .wasm du plugin par aggrega plugin gen-catalog, de sorte que le plugin est la source de cette liste. Un auteur peut la restreindre avant la publication, en retirant une entrée que cette entité ne doit pas proposer, et ne peut en ajouter aucune que l’auto-déclaration ne nomme pas : la publication, et aggrega validate auquel on fournit le .wasm du plugin avec --plugin, refusent une liste qui nomme une capacité que l’auto-déclaration ne nomme pas. La publication envoie l’entité telle qu’elle est écrite, sans jamais réécrire cette liste, et signale chaque capacité que nomme l’auto-déclaration et que la liste laisse de côté. Les formats de source que ce parser transforme en un arbre structuré canonique, chacun écrit sous la forme parse:<format> — par exemple parse:yaml. Le préfixe fait partie de l’entrée, de sorte qu’un plugin qui annonce plusieurs formats liste une entrée par format. Les entrées conservent l’ordre de l’auteur. Un format demandé se résout vers le parser dont la liste contient l’entrée correspondante ; un format qu’aucun parser n’annonce arrête le build, et un format annoncé par plus d’un plugin parser provoque un arrêt pour ambiguïté. Une liste vide ou absente ne déclare aucun format, de sorte que le plugin n’analyse rien.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.importer

Le bloc importer pour un plugin pluginType: importer : les formats source externes qu’il transforme en brouillons de fichiers de rédaction Aggrega, et les signatures auxquelles on reconnaît une source dans ces formats. Présent uniquement sur les plugins importer ; absent sur tout autre type de plugin.

PropriétéTypeObligatoireDescription
capabilitiesstring[]nonEnregistrée à partir de l’auto-déclaration du .wasm du plugin par aggrega plugin gen-catalog, de sorte que le plugin est la source de cette liste. Un auteur peut la restreindre avant la publication, en retirant une entrée que cette entité ne doit pas proposer, et ne peut en ajouter aucune que l’auto-déclaration ne nomme pas : la publication, et aggrega validate auquel on fournit le .wasm du plugin avec --plugin, refusent une liste qui nomme une capacité que l’auto-déclaration ne nomme pas. La publication envoie l’entité telle qu’elle est écrite, sans jamais réécrire cette liste, et signale chaque capacité que nomme l’auto-déclaration et que la liste laisse de côté. Les formats de source externes que cet importeur transforme en fichiers de rédaction Aggrega à l’état de brouillon, chacun écrit sous la forme import:<format> — par exemple import:terraform. Le préfixe fait partie de l’entrée, de sorte qu’un plugin qui annonce plusieurs formats liste une entrée par format. Les entrées conservent l’ordre de l’auteur. Un format d’import demandé se résout vers l’importeur dont la liste contient l’entrée correspondante ; un format qu’aucun importeur n’annonce arrête l’import, et un format annoncé par plus d’un plugin importeur provoque un arrêt pour ambiguïté, sauf si une entrée plugins.importer de la configuration de l’espace de travail en rattache un, qui s’exécute alors. Une liste vide ou absente ne déclare aucun format, de sorte que le plugin n’importe rien.
detectobject[]nonGéré par la machine, à ne pas rédiger : dérivé de l’auto-déclaration du .wasm du plugin lorsque l’entité est générée à partir de celui-ci, et enregistré ici dans l’ordre où l’auto-déclaration les déclare. Les signatures auxquelles on reconnaît une source des formats de cet importeur lorsqu’un import ne nomme aucun format. aggrega import lit les signatures de chaque importeur que contient le catalogue de l’espace de travail, toutes versions comprises, et des importeurs du cœur du compilateur, les compare à la source sans savoir ce qu’est un format, et lit la source comme le format de l’unique importeur dont la signature correspond ; une source à laquelle aucune signature ne correspond est refusée avec une demande du format, et une source à laquelle correspondent des signatures de plus d’un format est refusée en les nommant. Un importeur qui reconnaît une source la reconnaît comme chacun des formats qu’il annonce, de sorte que, pour un importeur qui annonce plus d’un format, chaque correspondance est refusée pour ambiguïté. Lorsqu’elle est présente, la liste doit être égale à ce que déclare l’auto-déclaration du plugin, entrée par entrée et dans l’ordre, et le chargement et la publication refusent un plugin dont l’auto-déclaration diffère, en nommant ce champ. Absente, elle ne déclare rien et n’est pas comparée, et les formats de l’importeur ne sont alors accessibles qu’en les nommant.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.importer.detect[]
PropriétéTypeObligatoireDescription
syntaxstringouiLe format syntaxique dans lequel la source est analysée — json ou yaml, par exemple — qui est le format qu’un plugin parser annonce sous la forme parse:<syntax>. La source est analysée par le parser que le catalogue de l’espace de travail fournit pour cette syntaxe ou, pour une syntaxe pour laquelle le catalogue n’en fournit aucun, par celui qu’embarque le compilateur, au plus une fois quel que soit le nombre de signatures qui nomment la syntaxe, et une source qui ne s’analyse pas dans celle-ci ne correspond à aucune signature qui la nomme. Une syntaxe pour laquelle ni l’un ni l’autre ne fournit de parser arrête la reconnaissance en nommant l’absence de ce parser. Au moins 1 caractère.
filesstring[]nonLes motifs de nom de fichier auxquels s’applique la signature, comparés à la fin du nom de la source, ses séparateurs étant lus comme des barres obliques : un motif d’un seul segment au nom propre du fichier, et un motif de plusieurs segments séparés par des barres obliques à autant de segments finaux de son chemin, de sorte que .vscode/mcp.json correspond à un fichier nommé mcp.json dans un répertoire nommé .vscode. À l’intérieur d’un segment, * correspond à toute suite de caractères, ? à un caractère et [...] à un caractère d’une classe. La signature s’applique lorsqu’un motif quelconque correspond. Absent ou vide, il l’applique à une source qui est un seul fichier, quel que soit son nom, et à aucun fichier d’un répertoire. Les motifs des signatures d’un importeur sont aussi ce qui décide quels fichiers d’un répertoire aggrega import lui transmet.
matchobject[]nonLes prédicats que l’arbre analysé doit satisfaire, tous, dans l’ordre déclaré. Absent ou vide, il n’exige rien de l’arbre au-delà de son analyse dans la syntaxe.

Les propriétés supplémentaires ne sont pas autorisées.

plugin.spec.importer.detect[].match[]
PropriétéTypeObligatoireDescription
pathstringouiL’endroit de l’arbre où regarde le prédicat, écrit sous forme de clés jointes par des points depuis le sommet de l’arbre : data.nodes nomme le membre nodes de l’objet data de premier niveau. Un segment écrit comme un nombre entier, 0 ou plus, sélectionne cette position d’un tableau en comptant à partir de zéro, de sorte que nodes.0.type nomme le type du premier nœud ; tout autre segment sélectionne un membre d’un objet. Au moins 1 caractère.
isstring (enum)ouiCe que le chemin doit atteindre : present est vérifié lorsqu’il atteint une valeur de n’importe quel type, null compris ; absent est vérifié lorsqu’il n’atteint rien ; object, array, string, number et boolean sont chacun vérifiés lorsqu’il atteint une valeur de ce type. Valeurs autorisées : "present", "absent", "object", "array", "string", "number", "boolean"
equalsstringnonUne chaîne à laquelle la valeur atteinte par le chemin doit être exactement égale ; une valeur qui n’est pas une chaîne ne lui est jamais égale. Au plus l’un de equals et prefix est déclaré sur un prédicat. Au moins 1 caractère.
prefixstringnonUne chaîne par laquelle la valeur atteinte par le chemin doit commencer ; une valeur qui n’est pas une chaîne ne commence jamais par elle. Au plus l’un de equals et prefix est déclaré sur un prédicat. Au moins 1 caractère.

Les propriétés supplémentaires ne sont pas autorisées.