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

aggrega validate

aggrega validate vérifie la correction — schéma, structure des piliers, résolution des références entre documents, chaînes extends, capacité du provider vis-à-vis du type d’entrée et (pour une entité qui effectue un rendu) le fait qu’elle effectue réellement son rendu. Elle a trois modes, sélectionnés par son argument, qui appliquent la même discipline de correction à trois portées : le catalogue entier (aucun argument), la fermeture des dépendances d’une seule Release (--release) et le fichier d’une seule entité (un chemin d’entité). Chaque portée répond à la même question — « ce contenu est-il correct ? » — sur une tranche différente du catalogue.

La correction est distincte des conventions. aggrega validate demande si le contenu est bien formé et compilerait ; aggrega lint demande si le contenu suit la discipline de publication du catalogue (nommage, alignement sur les répertoires de catégorie, ampleur de l’incrément de version, et le reste). Les deux commandes reflètent mutuellement leurs trois portées, de sorte que vous pouvez vérifier l’une ou l’autre dimension à la granularité dont vous avez besoin.

aggrega validate n’écrit rien sur le disque et ne lit aucun état d’exécution. Elle exécute la même résolution et la même validation qu’un build, en s’arrêtant avant le rendu (ou, pour une entité unique, en l’isolant).

Un chemin d’entité peut être donné en argument positionnel. --release donné à côté d’un chemin d’entité ne sélectionne pas la portée Release : l’entité est toujours vérifiée seule, dans les termes de cette Release — voir Vérifier une entité dans les termes d’une Release.

Exactitude du catalogue entier (sans argument)

aggrega validate sans argument charge chaque entité de catalogue sous les répertoires de catalogue configurés et la vérifie de bout en bout. Avant de charger quoi que ce soit, il lit chaque fichier YAML qu’ils contiennent, et un document Aggrega parmi eux qu’il ne peut pas charger arrête l’exécution, comme décrit ci-dessous. Ensuite :

  • Structure des piliers de schéma — le bloc spec.schema: de chaque Component et de chaque Feature est développé et validé (la même vérification des piliers de schéma que celle appliquée par la build), y compris le développement de la forme compacte.
  • Résolution des références entre documents — les références $ref et $import vers des entrées d’une SchemaLibrary sont résolues, et une SchemaLibrary qui ne peut pas être résolue ou qui est invalide pour une autre raison est rejetée.
  • Chaînes extends — chaque entité qui déclare extends est résolue par rapport à son parent, et la forme fusionnée parent+enfant est vérifiée. Un parent que les répertoires de catalogue ne contiennent pas est lu là où un build le lit : depuis le cache d’artefacts, sous l’épinglage que le lockfile d’une Release enregistre pour lui — les lockfiles des Releases pour lesquelles la passe est exécutée, ou de chaque Release que contient l’espace de travail lorsque celui-ci est validé en une seule passe. Ainsi, une base publiée dans un registre est validée dès que aggrega pull l’a récupérée et épinglée, et un parent que ni l’un ni l’autre ne contient arrête l’exécution, en nommant aggrega pull --release <release>. Rien n’est récupéré.
  • Sélecteurs déclarés — chaque sélecteur de labels qu’un document Component ou Feature déclare sur un socket de dépendance sous spec.usesSchema, ou sur un slot d’attachement sous spec.featuresSchema — y compris, sur un Component, les slots qu’un socket déclare — est lu par rapport à la grammaire des sélecteurs, que quelque chose câble ou non le socket ou remplisse ou non le slot. Voir sélecteurs déclarés.
  • Collisions d’emplacement OCI — deux identités de catalogue distinctes qui publieraient au même emplacement de registry sont rejetées ostensiblement, de sorte qu’une build n’écrase jamais silencieusement les octets publiés d’une entité par ceux d’une autre.
  • Capacité de type d’entrée du Provider — une Recipe ou une FeatureRecipe qui déclare un bloc workload: lié à un provider incapable de synthétiser est signalée comme une erreur, car elle ne peut jamais être construite.

C’est le pendant, à l’échelle du catalogue entier, de la validation par Release d’une build — l’endroit où une entité de catalogue défectueuse est censée apparaître, avant qu’une Release ne l’atteigne. Il s’arrête ostensiblement sur un document Aggrega qu’il ne peut pas charger, et sur toute violation des piliers de schéma, bibliothèque non résoluble ou invalide, échec de résolution d’extends, sélecteur déclaré que la grammaire refuse, collision d’emplacement ou erreur de capacité selon le type d’entrée. Les constats de chevauchement des piliers de schéma et de restriction lors de l’extension, ainsi que chaque mot-clé x-aggrega-* qu’un Component ou une Feature écrit en ligne dans son contenu de schéma, sont des lignes notice: informatives qui ne modifient jamais le code de sortie.

Un document Aggrega qui ne peut pas être chargé arrête l’exécution. Un fichier YAML sous un répertoire de catalogue est un document Aggrega lorsque l’une de ses lignes commence, sans indentation, par apiVersion: et une valeur commençant par aggrega.ai/, entre guillemets ou non. Un tel document qui ne peut pas être lu, dont le YAML ne s’analyse pas, ou dont le kind ou les metadata n’ont pas la forme que prend l’enveloppe d’une entité — des metadata écrites sous forme de liste, par exemple — arrête l’exécution avec E0175 une fois les répertoires lus, en nommant chacun de ces fichiers avec la raison donnée par la lecture ou par le parseur ; rien n’est vérifié et aucune ligne catalog validation passed n’est affichée. Un document qui se charge et déclare un kind qu’aucun catalogue ne contient — un Componnent mal orthographié, par exemple, ou aucun kind — arrête la même exécution avec E0371, et il est nommé à côté d’eux avec le type qu’il déclare ; un Manifest, une Release et un Workload qu’une Recipe importe depuis son propre répertoire sont ignorés. Tout autre YAML — les templates d’un chart Helm, qui ne s’analysent qu’une fois rendus, les valeurs d’un chart, les définitions de workflow — est ignoré.

Les répertoires qu’il lit dépendent de la forme du workspace :

  • Un workspace dont la configuration n’attribue à aucune Release ses propres répertoires de catalogue est validé une seule fois, sur sa pile de recherche : les répertoires --catalog, puis workspace.catalog_dirs, puis le répertoire catalog à la racine du workspace lorsqu’il existe.

  • Un workspace qui nomme des Releases sous workspace.releases peut conserver un catalogue en plusieurs variantes côte à côte, chacune lue par sa propre Release, et les charger toutes à la fois placerait chaque variante dans un seul catalogue, l’entité d’une variante masquant celle d’une autre. Il est donc validé une fois pour chaque Release que contient le workspace, sur les répertoires que lit cette Release, avec les répertoires --catalog en premier dans chaque passe ; une Release que la configuration ne nomme pas lit la liste du workspace. Chaque passe est rapportée sous une ligne qui nomme sa Release et les répertoires lus, suivie du résultat de cette passe :

    Release release-compose.yaml reads catalog-compose
    catalog validation passed (schema-pillar + library + extends + oci-location)
    Release release-helm-synth.yaml reads catalog-helm-synth
    catalog validation passed (schema-pillar + library + extends + oci-location)

    Les Releases qui lisent exactement les mêmes répertoires partagent une même passe, qui nomme chacune d’elles. Une Release qui ne lit aucun répertoire — son entrée écrit catalog_dirs: [] — est rapportée comme n’ayant rien à vérifier, et les autres passes s’exécutent normalement. Chaque passe est rapportée quoi qu’ait trouvé une passe précédente, car une entité défectueuse dans une variante ne dit rien d’une autre, et la commande échoue lorsqu’une passe quelconque échoue, en nommant les Releases dont les répertoires ont échoué. Les Releases que contient un workspace sont ses documents Release — des fichiers YAML dont le kind est Release, n’importe où sous la racine du workspace en dehors des répertoires cachés et de node_modules, vendor et dist.

Une exécution qui n’a rien à lire dans aucune passe est refusée plutôt que rapportée comme un catalogue sain : placez les entités sous catalog/, passez --catalog ou définissez workspace.catalog_dirs — ou, dans un workspace qui nomme des Releases, les catalog_dirs propres d’une Release sous workspace.releases. Elle n’énumère jamais implicitement le répertoire de travail courant, et n’entraîne donc jamais d’arborescences sans rapport.

L’outil validate de aggrega mcp, interrogé sur le catalogue entier, valide les mêmes passes ; dans un workspace qui nomme des Releases, sa réponse porte chacune d’elles sous passes — les Releases, les répertoires lus et le verdict propre à cette passe — à côté du verdict sur l’ensemble.

Une bibliothèque que seul le cache d’artefacts contient

Le cache d’artefacts contient ce qu’une récupération y a placé, et une SchemaLibrary mise en cache ne compte comme contenu de catalogue que là où une entrée du lockfile d’une Release garantit son digest — voir Ce qu’est le cache, et ce qu’il n’est pas. Lorsqu’un $ref: ne se résout en rien alors que le cache contient une bibliothèque qu’aucune entrée de lockfile n’épingle et qu’aucun répertoire de catalogue lu par la vérification ne fournit, le rapport est suivi d’une ligne remediation: qui nomme chacune de ces bibliothèques et l’action qui fonctionne pour la portée en échec :

  • Sans argument, et avec un chemin d’entité, que --release soit donné ou non, validate lit les bibliothèques uniquement dans les répertoires de catalogue, jamais par l’intermédiaire d’une entrée de lockfile, de sorte qu’une entrée enregistrée ne changerait pas son verdict. La ligne le dit et renvoie à l’écriture de la bibliothèque sous un répertoire de catalogue, ou à aggrega pull --release <release> suivi de aggrega validate --release <release>, qui vérifie la Release par rapport aux bibliothèques qu’épingle son lockfile.
  • Avec --release seul, validate lit le lockfile de la Release, la ligne nomme donc aggrega pull --release <release>, qui résout la bibliothèque et enregistre son entrée, ou l’écriture de la bibliothèque sous un répertoire de catalogue.

La ligne ne modifie ni le verdict ni le code de sortie.

Sélecteurs déclarés

Un Component ou une Feature contraint ce qui peut être câblé à ses sockets de dépendance, et ce qui peut remplir ses slots d’attachement, au moyen de sélecteurs de labels — le selector: de chaque entrée de spec.usesSchema et de chaque entrée de spec.featuresSchema, et, sur un Component, le selector: de chaque slot qu’un socket déclare sous son propre featuresSchema. Un build ne lit un sélecteur que là où quelque chose l’atteint : une arête tracée à travers le socket, un attachement qui remplit le slot. Ainsi, la portée catalogue entier et la portée entité unique lisent chaque sélecteur qu’un document Component ou Feature déclare, que quelque chose câble ou non le socket ou remplisse ou non le slot, et un sélecteur que la grammaire refuse — une liste de valeurs à laquelle manque sa parenthèse fermante, une virgule doublée, une clé portant = ou ! — fait échouer la vérification. La grammaire est celle qu’enseigne la grammaire des chaînes.

Le refus est celui qu’un build signale lorsqu’il atteint le même sélecteur, sous le même code et dans les mêmes termes : E0007 pour le sélecteur d’un socket et E0008 pour celui d’un slot, en nommant le sélecteur, le socket ou le slot qui le déclare, et la raison pour laquelle la grammaire n’a pas pu le lire. Il est classé comme défaut du catalogue sur le fichier de l’entité :

selector violation ("<selector>", declared on socket "<socket>", which could not be evaluated: "<why it could not be read>"). Correct the selector on the socket’s declaration in the component type’s usesSchema. (violation de sélecteur : sélecteur déclaré sur un socket, qui n’a pas pu être évalué. Corrigez le sélecteur dans la déclaration du socket, dans l’usesSchema du type de composant.)

Chaque document est lu tel que son auteur l’a écrit, de sorte qu’un sélecteur que déclare une entité de base est signalé une seule fois, sur le fichier propre de la base, plutôt qu’une fois pour chaque entité qui l’étend. Les appliesTo et appliesToAnyOf d’une Feature ne sont pas lus ici : ils sont lus partout où un attachement de la Feature est évalué.

La portée catalogue entier signale chaque sélecteur refusé sur sa propre ligne selector: et échoue en indiquant leur nombre ; la portée entité unique les signale comme l’échec de son niveau de forme — avec ou sans --release à côté du chemin d’entité, puisque cette forme est la portée entité unique exécutée dans les termes d’une Release (voir vérifier une entité dans les termes d’une Release). --release seul, qui valide la fermeture des dépendances d’une Release, et un build ne lisent un sélecteur que là où une arête ou un remplissage l’atteint, et s’arrêtent là sur ce sélecteur.

Exactitude limitée à une Release (--release)

aggrega validate --release <release-path> valide exactement les entités qu’atteignent les dépendances résolues d’une seule Release, plutôt que le catalogue entier ou une seule entité. Il calcule la fermeture au moyen du même mécanisme qu’utilise une build, de sorte que les entités qu’il vérifie sont exactement celles qu’une build de cette Release résoudrait, et sur cette fermeture :

  • résout les chaînes extends limitées à la fermeture, en échouant sur une erreur de résolution ;
  • valide les piliers de schéma de chaque entité résolue (limités à la fermeture), en échouant sur une erreur de pilier de schéma ;
  • exécute la même vérification de conformité des valeurs avant rendu qu’exécute une build — il résout les paramètres de la Release dans les valeurs écrites par l’auteur (de sorte qu’une valeur {{ .parameters.* }} est vérifiée une fois résolue, et non comme template) et valide le résultat par rapport aux schémas composés de la fermeture, y compris la conformité au schéma composé parent+enfant pour une entité qui utilise extends. Une valeur qui viole son schéma échoue avec un code de sortie non nul ;
  • évalue chaque assertion de Recipe et de FeatureRecipe par rapport aux valeurs vers lesquelles la Release se résout, comme une build les évalue avant de rendre : la Recipe de chaque composant est liée comme le Manifest la mappe, ses locals et ses provides sont résolus, et la première assertion qui échoue — une qui appelle fail, ou une dont le template s’arrête sur une clé qu’il ne trouve pas — fait échouer la validation avec la condition et la phrase sur lesquelles une build s’arrête. Un template locals ou provides qui ne peut pas être évalué la fait également échouer, comme il fait échouer une build. Le provider à travers lequel chaque Recipe effectue son rendu est interrogé sur le nom qu’il donne aux ressources de ce composant, comme une build l’interroge, car les provides d’une Recipe peuvent lire ce nom ; rien n’est rendu. Ces assertions ne sont évaluées que si rien de ce qui précède n’a déjà échoué, de sorte qu’une Release signale la première faute sur laquelle une build s’arrêterait ;
  • fait apparaître les constats de chevauchement des piliers de schéma et de restriction lors de l’extension sous forme de lignes notice: informatives qui ne modifient jamais le code de sortie ;
  • affiche chaque mot-clé x-aggrega-* qu’une entité qu’il lit écrit en ligne dans son contenu de schéma sous forme de ligne warning:, une fois par entité, comme une build l’affiche — cela ne modifie jamais non plus le code de sortie.

Cela fait de --release une véritable vérification avant build : il intercepte ce qu’une build rejetterait, avant la build — la validation des dépendances de la build sans le rendu. Il n’effectue aucun rendu et ne déclenche aucun pull réseau : la fermeture se résout à partir du catalogue local (et des pins du lockfile de la Release, s’il est présent) ; un ensemble de dépendances épinglées à un registry qui nécessite un lockfile fait apparaître une erreur honnête de référence non résoluble plutôt que de télécharger. La restriction est signalée comme un conseil, jamais imposée.

Un lockfile qui ne correspond plus à ce vers quoi la Release se résout fait refuser la validation avec l’arrêt qu’affiche aggrega build. Lorsqu’un lockfile se trouve à côté de la Release, --release le confronte à ce vers quoi la Release se résout, avec la comparaison de dérive qu’un build exécute avant le rendu, dès que les dépendances de la Release se résolvent et avant qu’aucune des vérifications ci-dessus ne s’exécute. Un lockfile dont une entité épinglée, une bibliothèque, un plugin ou le fichier de Release lui-même a dérivé arrête la validation avec le refus E0130 du build — chaque entrée qui a dérivé, puis l’aggrega pull --release <release> qui le lève — et un code de sortie non nul, de sorte qu’une validation ne laisse jamais passer un lockfile que le build refuse pour dérive. Sans argument, et avec un chemin d’entité, validate n’est tenu à aucun lockfile : la vérification de l’ensemble du catalogue ne lit les épinglages du lockfile que pour trouver un parent extends, et la vérification d’une seule entité ne lit aucun lockfile.

Comme il exécute les mêmes vérifications qu’une build, il exécute aussi les mêmes plugins de contrôle rattachés — il est donc soumis au même registre des identités de plugins de confiance qu’une build. Un workspace qui rattache un plugin renvoyant un verdict d’acceptation ou de rejet possède un registre de confiance des plugins à côté de sa Release, et --release compare la configuration à celui-ci avant que l’un de ces plugins ne s’exécute : un contrôle enregistré que la configuration ne rattache plus arrête la validation, et un plugin résolu depuis le cache que remplit aggrega pull dont l’artefact n’est pas celui enregistré est refusé plutôt qu’exécuté. Un workspace qui n’a rien enregistré n’a pas de registre, ce qui ne change rien pour cette comparaison. --release nomme aussi chaque retrait enregistré contre ce dont dépend la Release, sur la sortie d’erreur standard, sous forme de ligne deprecation: dans les termes qu’affiche aggrega build : un marqueur que le lockfile enregistre contre une référence épinglée comme un marqueur que le registre de confiance enregistre contre un plugin rattaché dans un rôle de verdict. Un retrait ne modifie ni le verdict ni le code de sortie, et un registre de confiance présent qui ne peut pas être lu arrête la validation au lieu de passer pour un registre qui n’enregistre rien.

Un plugin lu depuis le cache est aussi soumis à la signature que consigne son entrée, comme une build l’y soumet, au moment où il est chargé. Lorsque son entrée consigne une signature vérifiée, le matériel de signature que ce fait désigne dans le cache est vérifié à nouveau, et un plugin dont le matériel est absent ou diffère est refusé — de même qu’un plugin dont le matériel a été produit pour un autre plugin que celui lu, ce à quoi ressemble une signature copiée depuis une autre entrée, quoi que dise l’exigence de signature. Lorsque la configuration de confiance du workspace exige une signature, un plugin lu depuis le cache dont l’entrée n’en consigne aucune — ou pour lequel le registre ne contient aucune entrée, registre supprimé compris — est également refusé, avec les mêmes paramètres qui feraient refuser à aggrega pull un plugin non signé, de sorte que skip_signature_verification et un registry advisory le laissent s’exécuter. Un refus fait échouer la validation et est rapporté parmi ses diagnostics, en nommant le plugin et aggrega pull --release <release>, la commande qui vérifie sa signature auprès de son registry, la consigne et met en cache le bundle qu’elle désigne, en réécrivant une copie en cache qui ne correspond plus à son condensé ; un plugin servi depuis l’un de vos répertoires de catalogue, ou depuis la copie intégrée au binaire du compilateur, n’est jamais soumis à cette exigence. Les deux autres portées ne sont soumises à rien de tout cela : elles ne lisent pas les rattachements de plugins du workspace, donc aucun plugin de ce genre ne s’y exécute.

Il en va de même pour les plugins qui modifient le graphe plutôt que de le juger. Un rattachement label-transform ou annotation-transform façonne ce que serait la sortie rendue, de sorte que le lockfile épingle à la fois son identité et les fichiers source qu’il lit — et --release exécute ces rattachements comme une build les exécute : reconstruits à partir du lockfile, chacun soumis à son condensé enregistré, et en lisant le contenu source que porte le lockfile plutôt que le fichier sur disque. Deux conséquences méritent d’être connues avant de les rencontrer :

  • Rattacher un plugin de transformation dans .aggrega-config.yaml ne change pas ce que fait --release tant que vous n’avez pas effectué de pull. C’est la même règle que suit une build, et pour la même raison : l’ensemble des rattachements est une entrée qui détermine les octets, il est donc adopté au pull plutôt qu’au moment où il est modifié.
  • Un plugin en cache dont les octets ne correspondent plus au condensé enregistré par le lockfile est refusé, exactement comme il le serait pendant une build.

Si la Release n’a pas de lockfile, --release valide quand même — il avertit qu’il n’a pas pu vérifier l’identité d’un plugin et indique quoi exécuter, plutôt que de refuser. Voir avertissements.

Restituer le graphe compilé

--ir-graph écrit sur la sortie standard, en JSON, le graphe que cette validation a résolu, avant la ligne du verdict. Il est additif : les mêmes vérifications s’exécutent, les mêmes diagnostics sont écrits, et le code de sortie est le même que sans lui. Le graphe renvoyé est celui sur lequel la validation a été effectuée, il ne peut donc pas décrire une résolution différente de celle dont rend compte le verdict.

Il ne s’applique qu’à cette portée — les portées catalogue entier et entité unique pilotent un harnais synthétisé plutôt qu’une Release, et ne résolvent aucun graphe — et le demander ailleurs est refusé plutôt que silencieusement ignoré. Si l’exécution s’arrête avant que le graphe ne soit résolu, rien n’est écrit sur la sortie standard et les propres diagnostics de la commande indiquent ce qui l’a arrêtée.

Notez l’option voisine. --response-format définit la part du propre rapport de cette commande qui est écrite (detailed ou concise) ; --ir-graph demande un second document à côté de ce rapport. L’un concerne le volume, l’autre le sujet, et aucun des deux ne modifie le verdict.

Les valeurs qu’un auteur a déclarées sensibles sont retenues hors du graphe — y compris les values et l’infra d’une connexion, là où le socket du composant consommateur déclare une feuille sensible — sous la forme structurée décrite dans aggrega inspect. --unredacted à côté de --ir-graph les affiche à la place, aux conditions qu’énonce aggrega inspect --unredacted : il atteint le graphe et rien d’autre de ce qu’écrit cette commande, et tout ce qu’atteint la sortie porte alors ces valeurs en clair. Passé sans --ir-graph, il est refusé, car il n’y aurait rien à révéler.

Exactitude d’une entité unique (un chemin d’entité)

aggrega validate <entity-path> vérifie un seul fichier d’entité de catalogue. Il applique un ensemble de vérifications par niveaux, en s’arrêtant au premier échec bloquant afin qu’une erreur de schéma apparaisse ostensiblement avant tout travail sur le catalogue :

  • Espaces réservés (tous les kinds) — une valeur que le kind exige et que le fichier laisse sous forme de chaîne vide. Ils sont tous rapportés d’un coup, avant les autres vérifications, chacun avec ce qu’il accepte ; voir espaces réservés encore dus.
  • Enveloppe de schéma (tous les kinds) — la vérification JSON-Schema exacte par entité qu’exécute le chargeur du catalogue à chaque frontière d’analyse.
  • Forme (tout type) — la validation structurelle propre au type. Pour un Component ou une Feature, elle comprend la lecture de chaque sélecteur de labels que le fichier déclare sur un socket de dépendance ou un slot d’attachement par rapport à la grammaire des sélecteurs ; voir sélecteurs déclarés.
  • Structure des piliers (Component et Feature) — la vérification des piliers spec.schema:, qui utilise les SchemaLibraries du catalogue pour le développement des $ref entre documents.

Un Component ou une Feature s’arrête là : enveloppe de schéma, forme et structure des piliers. Un Component isolé n’a ni values ni infra écrits par l’auteur à rendre isolément, il n’y a donc rien à rendre — son exactitude est entièrement couverte par les niveaux de schéma et de piliers. Chaque mot-clé x-aggrega-* que son contenu de schéma écrit en ligne est signalé parmi les notes informatives sur la sortie d’erreur standard sous forme de ligne warning: qui nomme le mot-clé, l’endroit où il se trouve et la table déclarative à écrire à la place ; cela ne modifie jamais le verdict ni le code de sortie.

Une Recipe est en outre rendue isolément. C’est une facette de l’exactitude d’une entité unique, pas son point principal : une fois les niveaux de schéma et de forme passés, validate résout depuis le catalogue le Component désigné par implements de la Recipe, synthétise un Aggregate, un Manifest et une Release minimaux autour d’une seule instance de ce Component liée à la Recipe testée, et fait passer sur eux le véritable pipeline de compilation — d’abord la résolution et les gardes (rendu ignoré), puis un véritable rendu de la sortie isolée. Chaque valeur requise et chaque champ infra requis sans valeur par défaut est rempli d’un espace réservé de son type déclaré — les valeurs dans l’Aggregate synthétisé, l’infra dans la Release synthétisée — et toute autre valeur et tout autre champ infra prend sa valeur par défaut de schéma via le résolveur ; la Release achemine l’instance dans une frontière par défaut synthétisée et ne déclare aucun values: ni aucune ressource de calcul que l’Aggregate n’a pas déclarée. Un espace réservé est une valeur qu’acceptent les contraintes déclarées du champ lui-même : la constante ou la première valeur que liste un enum, un nombre dans ses bornes, une chaîne de sa longueur et dans son format, une version sémantique là où son pattern en demande une, autant d’éléments de liste qu’il en exige, et chaque propriété qu’exige un objet. Tout autre pattern, une condition validate: ou when:, une composition de schémas et une contrainte sur les éléments que contient une liste ne sont pas consultés, de sorte qu’un champ qui s’appuie sur l’un d’eux peut tout de même refuser son espace réservé ; validate rapporte alors ce refus dans les propres termes du schéma. Les artefacts rendus sont affichés afin qu’un auteur voie la sortie isolée avant de câbler l’entité dans un Aggregate complet. Comme un harnais d’entité unique ne remplit que ces champs requis, ne câble aucune connexion et ne rattache aucune Feature, une Recipe dont les templates lisent une valeur que seule une connexion ou une Feature rattachée fournit ne peut pas être rendue isolément ; validate rapporte un tel rendu comme non tenté plutôt qu’échoué. Une assertion qui appelle fail est rapportée comme un avertissement plutôt que de faire échouer la vérification — voir une assertion échouée est un avertissement. Un rendu qui s’arrête pour toute autre raison ne s’est pas terminé, et validate le rapporte avec le diagnostic de rendu sous-jacent jusqu’à la phrase qui nomme ce qui l’a arrêté.

Une Recipe dont la source: doit être récupérée n’est pas rendue du tout, et une Recipe dont le rendu s’arrête pendant qu’elle lit une valeur que seule une connexion ou une Feature rattachée fournit voit ce rendu mis de côté — voir ce que l’exactitude d’une entité unique ne vérifie pas ci-dessous.

Une FeatureRecipe est vérifiée sur le schéma et la forme ; son rendu est ignoré, car une FeatureRecipe n’est rendue que lorsqu’elle est rattachée à un composant hôte, et la synthèse d’un hôte passant les gardes pour une Feature arbitraire n’est pas tentée.

Vérifier une entité dans les termes d’une Release

Un workspace peut attribuer à chaque Release ses propres répertoires de catalogue — voir Attribuer à une Release ses propres répertoires de catalogue — et conserver ainsi une variante de catalogue par Release côte à côte. Un chemin d’entité donné seul est vérifié sur les propres répertoires de catalogue du workspace, où une référence vers l’une de ces variantes — le Component qu’implémente une Recipe, une SchemaLibrary à laquelle renvoie un pilier — est introuvable. Donnez --release à côté du chemin d’entité et les mêmes vérifications s’exécutent dans les termes de cette Release : les références de l’entité se résolvent via les répertoires de catalogue que la configuration du workspace attribue à cette Release, précédés des éventuels --catalog, qui sont les répertoires que lit une build de cette Release.

L’exemple MariaDB + Adminer conserve quatre variantes de ce type. Le Component de sa variante synth tire ses paramètres de stockage d’une SchemaLibrary que seules les variantes synth et chart contiennent, il est donc validé dans les termes de la Release qui construit avec lui :

$ aggrega validate catalog-helm-synth/component/mariadb.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/component/mariadb.yaml
Kind: Component
Schema: valid
Pillars: valid

et échoue, en nommant la bibliothèque qu’il n’a pas pu résoudre, dans les termes d’une Release dont les répertoires ne la contiennent pas — --release release-compose.yaml, ou aucun --release dans un workspace qui ne liste aucun répertoire de catalogue propre.

Une Recipe est vérifiée de la même manière. La Recipe de la variante synth implémente core/datastore/mariadb, que les propres répertoires de catalogue du workspace ne contiennent pas, donc donnée seule elle échoue avec render: implements target "core/datastore/mariadb" not found in catalog. Avec la Release qui construit avec elle, elle résout le Component de cette Release et est rendue isolément :

$ aggrega validate catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.
Resolution: valid
Render: 3 artifact(s)

suivi des trois artefacts rendus. Chaque variante de cet exemple déclare core/datastore/mariadb, donc la Recipe est validée dans les termes de chacune de ses quatre Releases ; dans les termes d’une Release dont les répertoires de catalogue ne contiennent aucun Component de ce type, elle échoue en nommant la cible, comme sans --release. Les lignes Attachments: sont expliquées sous un emplacement de rattachement requis ou un mandat de présence.

Il s’agit toujours de la portée entité unique. Les vérifications, le rapport et le code de sortie sont ceux que décrit cette section — un Component ou une Feature portant un sélecteur de socket ou de slot que la grammaire refuse échoue ici exactement comme sans --release, voir sélecteurs déclarés — et aucune fermeture n’est validée : --release nomme la Release via les répertoires de catalogue de laquelle les références de l’entité sont lues, et non une fermeture à vérifier, c’est pourquoi --ir-graph est refusé à côté d’un chemin d’entité. Un --release qui nomme un fichier inexistant, ou un répertoire, est refusé avant toute vérification.

Un répertoire que liste la configuration du workspace et qui n’est pas un répertoire — rien n’existe à cet endroit, par exemple —, pour cette Release, ou pour le workspace lorsqu’aucun --release n’est donné, est refusé avant toute vérification, comme le refuse chaque commande qui lit ce catalogue (D’où sont lues les entités locales) : le refus nomme l’entrée, le fichier de configuration et la ligne qui la listent, ainsi que le paramètre, et aucun verdict n’est donné. La vérification d’entité de l’éditeur via aggrega serve donne le même refus comme unique entrée sur le fichier de l’entité, au niveau erreur, et l’outil validate d’aggrega mcp refuse l’appel avec lui.

Espaces réservés encore dus

Une valeur que le kind exige et que le fichier laisse sous forme de chaîne vide est un espace réservé, et validate le rapporte avant toute autre chose. Un document ébauché par aggrega scaffold en contient un partout où son kind a besoin d’une valeur que vous seul pouvez fournir, c’est donc ici que vous apprenez lesquels restent. Voici une FeatureRecipe ébauchée dont seule la version est renseignée :

Entity: my-feature-recipe.yaml
Kind: FeatureRecipe
2 placeholders still owed in my-feature-recipe.yaml; an empty required value is not a value, so each of these needs one before the document validates:
7:3: spec.capability takes what its schema describes: The explicit provider capability this recipe binds to (e.g., 'helm', 'terraform', 'compose') — the provider kind that renders it.
8:3: spec.implements takes what its schema describes: Declares which catalog Feature type this recipe is able to implement (including credential Features labeled feature.aggrega.ai/kind: secret; exact version, major-compatible range '^', or unversioned).

Tous les espaces réservés du fichier sont nommés d’un coup, dans l’ordre du document, avec leur ligne et leur colonne et avec ce qu’ils acceptent. Ce qu’ils acceptent est lu dans le propre schéma du kind : les valeurs acceptées là où le schéma les liste, une version sémantique telle que 1.0.0 là où le schéma en demande une, et sinon la première phrase de la propre description du champ par le schéma.

Les valeurs qui comptent sont également lues dans le schéma. Une valeur compte lorsque le kind l’exige au niveau supérieur du document, ou à l’intérieur d’un objet que le kind exige aussi, et que le fichier la définit à la chaîne vide. Une clé que le fichier omet complètement est rapportée par la vérification de schéma comme une propriété manquante. Un champ facultatif laissé vide n’est pas un espace réservé, pas plus qu’un champ requis seulement à l’intérieur d’une liste ou d’une map que vous avez choisi d’écrire. Là où le schéma lui-même liste la chaîne vide parmi les valeurs qu’accepte un champ, une chaîne vide est une valeur plutôt qu’un espace réservé.

Une valeur est due même là où le schéma l’accepterait vide. Le schéma admet une chaîne vide pour capability et implements d’une Recipe ou d’une FeatureRecipe, mais une chaîne vide ne nomme aucun provider ni aucun type, donc validate rapporte les deux comme des espaces réservés comme les autres. Là où la vérification de schéma refuse aussi le même fichier — une version vide, une étiquette de type sans valeur — le rapport porte le code de cette vérification, E0215, comme le montre l’exemple sur aggrega scaffold ; là où la vérification de schéma l’accepte, comme ci-dessus, le rapport ne porte aucun code. Un constat dans le même fichier qui ne concerne pas une valeur vide est tout de même rapporté, dans les propres termes de la vérification de schéma, avant la liste.

Cette lecture appartient à la validation d’une entité unique, avec ou sans --release à côté du chemin d’entité. Une exécution sur le catalogue entier qui rencontre le même document rapporte ce que rapporte la vérification de schéma, de sorte qu’une FeatureRecipe avec un implements vide dans un répertoire de catalogue la passe ; la portée Release et aggrega build n’appliquent pas non plus cette lecture.

Un kind que cette portée n’accepte pas

La validation d’une entité unique accepte Component, Feature, Recipe, FeatureRecipe, Workload et Plugin. Un fichier de tout autre kind est refusé, et le refus nomme les kinds acceptés et, pour un kind d’entité, la portée qui vérifie effectivement un document de ce kind :

kind "Aggregate" in "aggregate.yaml" is not a single-entity validation target; the kinds this scope accepts are Component, Feature, Recipe, FeatureRecipe, Workload and Plugin. An Aggregate is checked by the whole-catalog scope when it sits in a catalog directory, and by the Release scope over a Release that deploys it

La portée catalogue entier est une exécution sans argument, et la portée Release est --release sans chemin d’entité :

TypeVérifié par
Aggregateune exécution sur le catalogue entier, lorsqu’il se trouve dans un répertoire de catalogue ; --release sur une Release qui le déploie
Manifest--release sur une Release qui le nomme
Release--release <release-path>
SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibraryune exécution sur le catalogue entier, lorsqu’il se trouve dans un répertoire de catalogue

Une exécution sur le catalogue entier ne lit que ce qui se trouve dans les répertoires de catalogue configurés, de sorte qu’un Aggregate conservé à la racine du workspace à côté de sa Release est vérifié via --release sur cette Release.

Une assertion échouée est un avertissement

Une assertion qui appelle fail — déclarée par la Recipe ou par le Component désigné par son implements — est rapportée comme un avertissement, et la vérification n’échoue pas à cause d’elle. La Release synthétisée porte des espaces réservés et des valeurs par défaut de schéma à la place des valeurs que définit une véritable Release, de sorte qu’une assertion sur une telle valeur, une image ou la présence d’un prérequis échoue ici que la Recipe soit correcte ou non, et validate ne peut pas distinguer une assertion qui attend une Release d’une assertion défectueuse. Le verdict sur l’assertion est laissé à une build, qui a toujours une Release.

L’avertissement est écrit sur la sortie d’erreur standard, introduit par warning:, après les éventuelles notes informatives. Il porte le message complet de l’assertion — l’entité, l’instance, le nom de l’assertion et la phrase écrite par son auteur — terminé par une phrase supplémentaire :

A Release must satisfy this assertion before a build of it can pass.

Le rapport sur la sortie standard indique où l’exécution s’est arrêtée, et la commande se termine avec 0. L’assertion propre d’une Recipe arrête le rendu, de sorte que le rapport indique Render: stopped on a failed assertion, reported as a warning après Resolution: valid. L’assertion d’un Component est évaluée avant tout rendu, de sorte que le rapport indique Resolution: stopped on a failed assertion, reported as a warning, suivi de Render: not attempted (the run stopped on that assertion). Dans les deux cas rien n’est rendu, donc aucun artefact n’est affiché.

Seule une assertion qui appelle fail est un avertissement. Une assertion qui s’arrête sur une clé qu’elle lit mais ne trouve pas, ou qui ne s’analyse pas, est un défaut dans le texte même de l’assertion plutôt qu’une assertion échouée, et elle est jugée comme tout autre arrêt. Tout autre défaut garde sa place comme verdict de la vérification.

aggrega build d’une Release qui ne satisfait pas l’assertion s’arrête sur elle avec une erreur, en nommant l’assertion et en portant la phrase de son auteur, comme toujours, et aggrega validate --release sur cette Release échoue sur elle avec la même erreur. La vérification d’entité de l’éditeur via aggrega serve donne le même avertissement, placé sur la clé même de l’assertion là où la Recipe la déclare, et l’outil validate d’aggrega mcp répond valid: true avec l’avertissement parmi ses notices.

Ce que l’exactitude d’une entité unique ne vérifie pas

Quatre vérifications d’une véritable build sont hors de portée d’une build d’une seule entité, et validate renonce à chacune plutôt que de rapporter un constat qu’il ne peut pas soutenir.

Une source qui doit être récupérée

La validation d’une seule entité ne lit aucun lockfile, ne lit ni n’écrit aucun cache et n’effectue aucune requête réseau. Une Recipe dont la source: nomme quelque chose récupéré via un transport — un dépôt de charts OCI ou HTTPS, un dépôt Git — n’a donc aucun code d’infrastructure à partir duquel effectuer le rendu : le chart ou le module n’existe nulle part où l’exécution peut l’atteindre, et rien dans le fichier vérifié n’est en faute. Validate le dit, l’affiche comme un résultat distinct d’un rendu, et se termine avec 0 :

Entity: catalog/recipe/helm/openbao/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Resolution: valid
Render: not attempted (this Recipe's source is fetched)
Validating one entity on its own reads no lockfile, reads and writes no
cache, and makes no network request, so the chart or module this Recipe
names is never retrieved and there is nothing to render from. To render
it, build a Release that deploys a component this Recipe implements.

Tout ce qui se trouve au-dessus de cette ligne a été vérifié et est rapporté comme valide. Ce que signifie le code de sortie pour une telle Recipe est donc plus restreint que pour une Recipe qui a été rendue — le schéma, la forme et la résolution tiennent ; le rendu n’est pas démontré — et le rapport indique lequel des deux vous lisez.

Une source que le workspace contient déjà n’est pas écartée. Une source: ./module relative ne nécessite aucune récupération, son rendu est donc tenté comme n’importe quel autre, et un échec dans celui-ci est un véritable constat rapporté comme Render: not completed in isolation avec un code de sortie non nul. La ligne ci-dessus n’apparaît que pour une source qui doit être récupérée.

Pour rendre réellement une Recipe à source récupérée, exécutez aggrega build sur une Release qui déploie un composant qu’implémente la Recipe : une build résout la source via le lockfile de la Release et le cache local, ce qui fournit les octets que validate n’a aucun moyen d’obtenir.

Un socket uses requis

La deuxième consiste à savoir si les sockets uses required: true du Component désigné par implements sont alimentés.

Un socket requis est alimenté en câblant une arête vers un autre composant — depuis le bloc uses propre à l’Aggregate, ou depuis une Release qui câble un socket que déclare le Component. Le harnais synthétisé contient une seule instance, il ne contient donc aucun second composant que viserait une telle arête, et aucune rédaction des documents synthétisés ne peut en produire un : inventer un pair reviendrait à inventer des ressources de calcul que le harnais n’a jamais déclarées. Validate nomme donc les sockets qu’il n’a pas vérifiés et poursuit avec la résolution et le rendu :

Sockets: required uses sockets not checked (backend, cache, registry)
Validating a Recipe on its own places its Component in a build of one,
so no other component exists for a required socket to be wired to. Whether
each of these sockets is populated is checked when the Component is deployed
in an Aggregate.

La ligne n’apparaît que lorsque le Component déclare au moins un socket requis, et elle ne nomme que les sockets requis — un socket facultatif n’est jamais listé, car le laisser non câblé n’est un constat dans aucune portée. Une Recipe dont le Component ne déclare aucun socket requis ne produit pas de telle ligne, et son rapport est inchangé.

La règle elle-même n’est ni assouplie ni dupliquée ; elle est posée dans la portée qui peut y répondre. aggrega build l’applique intégralement sur les surfaces d’arêtes de l’Aggregate et de la Release ensemble, et s’arrête sur un socket requis que rien ne câble. Une Recipe qui passe la validation d’entité unique doit donc tout de même satisfaire la règle des sockets requis lorsque son Component est déployé, et le rapport le dit plutôt que de laisser une différence silencieuse entre ce que validate a vérifié et ce que vérifiera une build.

Un emplacement de rattachement requis ou un mandat de présence

La troisième consiste à savoir si les emplacements de rattachement required: true du Component désigné par implements — les points de liaison nommés que déclare son featuresSchema — sont remplis, et si un rattachement de chaque type de Feature qu’exigent ses mandats de présence est présent.

Un emplacement requis est rempli en rattachant une Feature sous ce nom, dans l’Aggregate ou dans la Release, sur le composant ou dans une portée au-dessus de lui — là où le Component est déployé, et non dans la Recipe. Le harnais synthétisé ne rattache aucune Feature, donc rien de ce qu’il construit ne peut remplir un tel emplacement. Validate nomme donc les emplacements qu’il n’a pas vérifiés et poursuit avec la résolution et le rendu, exactement comme pour les sockets requis :

Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.

La ligne n’apparaît que lorsque le Component déclare au moins un emplacement requis, et elle ne nomme que les emplacements requis ; une Recipe dont le Component n’en déclare aucun ne produit pas de telle ligne. Seule l’exigence est mise de côté : la contrainte d’étiquette d’un emplacement et ses mécanismes de livraison autorisés sont conservés tels que déclarés. Un template qui ne s’analyse pas fait tout de même échouer l’exécution, tout comme un défaut propre à la Recipe tel qu’un Workload que le provider ne peut pas synthétiser — sauf si la Recipe lit aussi une valeur que seule une connexion ou une Feature rattachée fournit, comme le décrit la section suivante.

Un mandat de présence — une annotation features.aggrega.ai/requiredType.<label> sur le Component, exigeant qu’un rattachement porte le type de Feature qu’elle nomme — est mis de côté pour la même raison : le harnais ne rattache rien, donc rien de ce qu’il construit ne peut porter ce type. Validate nomme chaque mandat qu’il n’a pas vérifié par son étiquette et le type qu’il exige, et poursuit avec la résolution et le rendu. example/compute/service de la bibliothèque standard en déclare un, de sorte que sa Recipe rapporte, avant ses deux artefacts rendus :

$ aggrega validate aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml --catalog aggrega-catalog
Entity: aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: presence mandates not checked (monitoring: core/prometheus-exporter)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to carry a type the Component requires. Whether
an attachment of each of these types is present is checked when a Release
that deploys the Component is built.
Resolution: valid
Render: 2 artifact(s)

Un mandat dont la déclaration ne peut pas être évaluée — le préfixe de l’annotation sans étiquette après lui, ou une valeur qui n’est pas un type de Feature — n’est pas mis de côté : c’est un défaut propre au Component, qu’aucun rattachement ne répare, et validate fait échouer l’exécution sur lui comme le fait une build.

Chaque règle est posée là où il est possible d’y répondre. aggrega pull, aggrega build et aggrega validate --release évaluent les deux sur les rattachements réels de la Release, et chacun s’arrête sur un emplacement requis que rien ne remplit et sur un type imposé qu’aucun rattachement ne porte.

Une valeur que seule une connexion ou une Feature rattachée fournit

La quatrième consiste à savoir si une Recipe est rendue une fois que ses connexions et ses Features rattachées fournissent ce que lisent ses templates.

Les templates d’une Recipe lisent ce qu’une connexion livre sous .context.inject et .context.uses, et ce qu’une Feature rattachée livre sous .features. Le harnais synthétisé ne câble aucune connexion et ne rattache aucune Feature, de sorte que chacune de ces lectures ne trouve rien : une lecture sous .context.inject.env rencontre un canal de livraison vide, et un range sur .context.uses ne rencontre aucune connexion. Validate rend d’abord la Recipe, et un rendu qui se termine est rapporté comme d’habitude. Lorsque le rendu s’arrête et que les templates de la Recipe — y compris les fichiers et les entrées de bibliothèque qu’ils importent — lisent quoi que ce soit sous ces trois chemins, validate rapporte le rendu comme non tenté, nomme les valeurs que la Recipe y lit, affiche la phrase sur laquelle le rendu s’est arrêté, et se termine avec 0. La variante chart de l’exemple MariaDB + Adminer lit ses identifiants de base de données depuis le canal de livraison que remplissent ses deux secrets rattachés :

$ aggrega validate catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml --release release-helm-chart.yaml
Entity: catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.
Resolution: valid
Render: not attempted (this Recipe reads values a build of one cannot supply)
Validating a Recipe on its own places its Component in a build that wires
no connection and attaches no Feature, so nothing supplies what its
templates read under .context.inject, .context.uses or .features. Its
render stopped, and whether on one of those values or on a fault of its
own is not judged here. To render it, build a Release that deploys a
component this Recipe implements.
Reads: .context.inject.env.MARIADB_PASSWORD, .context.inject.env.MARIADB_ROOT_PASSWORD
The render stopped: rendering: [CATALOG_ERROR] instance instance: rendering node "instance": [CATALOG_ERROR] catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml: recipe "mariadb-chart" valuesMapping: [CATALOG_ERROR] valuesMapping[mariadb-chart]: template "valuesMapping[mariadb-chart]" execute: template: valuesMapping[mariadb-chart]:7:30: executing "valuesMapping[mariadb-chart]" at <.context.inject.env.MARIADB_ROOT_PASSWORD>: nil pointer evaluating interface {}.MARIADB_ROOT_PASSWORD

Une lecture qui ne trouve rien et n’arrête rien n’est pas mise de côté : un range sur .context.uses qui ne rend rien, dans un rendu qui se termine, est rapporté comme le rendu qu’il a été.

Ce qui décide, c’est ce que lit la Recipe, et non ce sur quoi le rendu s’est arrêté, et cela a une conséquence qu’il vaut mieux connaître avant de la rencontrer : un défaut propre à la Recipe dans une Recipe qui lit aussi une telle valeur — une clé mal orthographiée, par exemple — est rapporté comme non tenté avec le reste, et non comme un échec. La ligne The render stopped: porte la propre phrase du rendu afin que vous puissiez voir de quoi il s’agissait, et une build d’une Release qui déploie le Component juge le rendu dans son intégralité.

Deux défauts font tout de même échouer l’exécution quoi que lise la Recipe, car aucune connexion ni aucune Feature ne les modifie : un template qui ne s’analyse pas, et une référence que le rendu refuse — une racine que le contexte de rendu ne définit pas, ou une clé mal saisie sous une racine dont la forme est fixe, telle que .context.instance_idd. Une assertion déclarée par la Recipe qui appelle fail n’est ni mise de côté ni un échec, quoi que lise la Recipe : elle est rapportée comme l’avertissement qu’est toujours une assertion échouée. Une Recipe dont les templates ne lisent aucun des trois voit son rendu jugé dans son intégralité, et un rendu qui s’arrête échoue avec la phrase qui en nomme la cause.

L’outil validate d’aggrega mcp rend le même verdict sur la même Recipe : un rendu mis de côté de cette manière répond comme valide sans rien dans ses diagnostics, et les lignes ci-dessus figurent dans le texte qu’il renvoie à côté.

Le chargement du catalogue en mode entité unique est tolérant : une entité défectueuse sans rapport ailleurs dans le catalogue est ignorée plutôt que d’interrompre la vérification, de sorte qu’elle n’empêche jamais de valider la cible isolément.

Un fichier ignoré explique tout de même un Component qui manque à cause de lui. Lorsque la cible implements d’une Recipe est introuvable et qu’exactement un fichier ignoré déclare ce Component, le rapport commence par le refus propre à ce fichier — son chemin, la contrainte qu’il enfreint et le code court de la condition dans l’en-tête — suivi d’une note: indiquant que le fichier a été ignoré au chargement, de sorte que le catalogue ne contient rien sous l’identité qu’il déclare, puis de l’échec implements target … not found in catalog comme raison pour laquelle le fichier était nécessaire. Lorsqu’aucun fichier ignoré ne déclare ce Component, ou que plusieurs le déclarent, l’échec d’introuvabilité vient en premier et chaque fichier ignoré est listé en dessous sous note: catalog files skipped at load. C’est le compte rendu que aggrega build donne d’un fichier qu’il a ignoré, et la vérification d’entité de l’éditeur via aggrega serve ainsi que l’outil validate de aggrega mcp le donnent aussi. Un catalogue dont rien n’a été ignoré produit exactement le rapport qu’il produirait sinon.

Comment validate se rapporte à lint et à build

Les trois commandes couvrent trois questions différentes :

  • aggrega validate — est-ce correct ? Schéma, piliers, références, extends, capacité selon le type d’entrée et rendu isolé. Il ne lit aucun état d’exécution et n’émet aucun artefact.
  • aggrega lint — cela suit-il les conventions de publication du catalogue ? Nommage, alignement entre catégorie et répertoire, préfixes d’annotation, ampleur de l’incrément de version, et le reste de la discipline de publication facultative. Lint reflète les trois portées de validate mais ne vérifie jamais l’exactitude.
  • aggrega build — compiler un déploiement complet. Build a besoin d’une fermeture complète Aggregate + Manifest + Release et émet des artefacts natifs du provider. Il valide sa propre fermeture de dépendances dans le cadre de la compilation, puis effectue le rendu. aggrega validate --release est cette validation des dépendances à elle seule, sans le rendu ; validate sur une entité unique isole le rendu d’une seule Recipe sans Aggregate complet.

Exemples

Valider le catalogue entier :

aggrega validate --catalog ./catalog

Valider exactement ce dont dépend une Release, avant de la construire :

aggrega validate --release releases/production.yaml

Valider une seule entité et — pour une Recipe — voir sa sortie rendue isolément :

aggrega validate core/datastore/postgres/recipes/helm.yaml

Valider une seule entité dans les termes d’une Release à laquelle la configuration du workspace attribue ses propres répertoires de catalogue :

aggrega validate core/datastore/postgres/recipes/helm.yaml --release releases/production.yaml

Voir aussi

  • ./aggrega-lint.md — le pendant pour les conventions sur les trois mêmes portées.
  • ./aggrega-build.md — compile un Aggregate + Release complet en artefacts ; valide sa fermeture de dépendances dans le cadre de la compilation.
  • ./aggrega-inspect.md — interroger le graphe IR après la résolution sans passer au rendu.
  • ../errors/warnings.md — les constats informatifs que validate fait apparaître sous forme de lignes notice:.

Synopsis

aggrega validate [entity-path] [flags]

Description

Check CORRECTNESS across three symmetric scopes.
With no argument, validate checks the WHOLE catalog: schema-pillar
structure, cross-document library resolution, extends chains, and provider
input-kind capabilities, over every catalog entity. Where the workspace
configuration gives its Releases catalog directories of their own under
workspace.releases, it checks the catalog once for each Release, over the
directories that Release reads, and reports each pass under a line naming
its Releases and those directories; Releases reading the same directories
share one pass.
With --release, validate checks the entities a Release's dependency closure
reaches: closure-scoped pillars, extends, and pre-render authored-value
conformance — the same correctness a build applies, scoped to that Release.
It then evaluates the Recipe and FeatureRecipe assertions against the values
that Release resolves to, as a build does before it renders, and reports a
failing assertion as a build reports it. Nothing is rendered.
With an entity path, validate checks one entity file. The kinds it accepts
as a single-entity target are Component, Feature, Recipe, FeatureRecipe,
Workload and Plugin. A value the kind requires that the file leaves empty is
reported first, as a placeholder still owed: every one is named at once, with
what it takes, read from the kind's own schema. That reading is this scope's
alone; a whole-catalog run, a Release's closure and a build do not apply it.
Each kind then has its schema checked, then the checks its own kind carries:
pillar structure for a Component or Feature; shape for a Workload,
FeatureRecipe or Plugin; and for a Recipe, shape plus an end-to-end compile
against a minimal generated harness, so its resolution, its guards and a
render of its output are all exercised. Where that Recipe's source is one
that has to be fetched, the render is reported as not attempted instead:
validating one entity on its own reads no lockfile, reads and writes no cache
and makes no network request, so the chart or module it names is never
retrieved and there is nothing to render from. A render that stops while the
Recipe's templates read what only a connection or an attached Feature
supplies — anything under .context.inject, .context.uses or .features — is
reported as not attempted too: the generated harness wires no connection and
attaches no Feature, so that render cannot be judged there, and a fault of
the Recipe's own beside such a read is set aside with it. A template that
does not parse and a reference the render refuses still fail. An assertion
that calls fail, the Recipe's own or one its Component declares, is printed
as a warning closed by a sentence saying a Release must satisfy it before a
build can pass, and does not fail the check: the generated harness sets none
of a real Release's values, so it cannot tell an assertion waiting on one from
one that is broken, and a build still halts on it. Any other kind is refused here
today, and the refusal names the scope that checks it instead: a whole-catalog
run reaches an Aggregate and the library kinds when they sit in a catalog
directory, and --release reaches a Release, the Manifest it names and the
Aggregate it deploys.
With an entity path and --release together, the entity is checked in that
Release's terms: its references — the Component a Recipe implements, a
library a pillar refers to — resolve through the catalog directories the
workspace configuration gives that Release rather than the workspace's own,
so a workspace keeping one catalog variant per Release checks an entity
against the variant that Release builds with. The checks are the entity
path's; no closure is validated.
The command writes nothing to disk.

Options

OptionPar défautDescription
--catalog[]Répertoire de catalogue ; répétable. Chaque —catalog <dir> est ajouté en tête de la pile de recherche du catalogue (la première correspondance l’emporte) : les catalog_dirs du workspace ou, pour une Release à laquelle la configuration du workspace attribue ses propres répertoires sous workspace.releases, ceux de cette Release ; la pile se termine par le répertoire nommé catalog à la racine du workspace lorsqu’il existe. Une liste catalog_dirs écrite vide ne lit aucun catalogue local.
--ir-graphfalseÉcrit aussi sur stdout, en JSON, le graphe IR calculé par cette exécution, en plus de tout ce que produit déjà cette commande. Les valeurs qu’un auteur a déclarées sensibles en sont retenues ; passez —unredacted pour les afficher à la place. S’applique à la portée —release, la seule portée qui résout une Release en graphe. Il sélectionne un DOCUMENT, là où —response-format définit la part du propre rapport de cette commande qui est écrite ; aucun des deux n’affecte le verdict ni le code de sortie
--no-unsupported-field-warningsfalseFait taire la classe d’avertissements sur les champs non pris en charge : les notices qu’une cible émet pour quelque chose que vous avez écrit et qu’elle ne peut pas honorer — un champ Workload qu’elle ne peut pas exprimer (comme c’est le cas d’une cible de moindre fidélité telle que compose), ou une annotation aggrega.ai/ sur laquelle elle n’agit pas pour le type d’entrée du nœud. Les autres avertissements de rendu continuent d’apparaître. Affichage uniquement ; ne modifie pas la sortie rendue. S’applique à la portée entité, la seule portée qui effectue un rendu
--plugin—Chemin vers un .wasm brut à valider par rapport à son auto-déclaration describe() — la vérification d’écriture avant publication. Seul, il nécessite —type ; avec un argument d’entité Plugin, il confronte le binaire au type déclaré de l’entité, à sa revendication de capacité, à son miroir de commandes et à son registre de fonctions hôtes.
--release—Chemin vers un YAML de Release. Seul, valide sur sa fermeture de dépendances résolue ; avec un argument d’entité, vérifie cette entité dans les termes de la Release, ses références étant résolues via les répertoires de catalogue que la configuration du workspace attribue à cette Release. Un chemin relatif se résout par rapport au répertoire dans lequel vous exécutez la commande, et non par rapport à la racine du workspace. Lorsque ce répertoire n’appartient à aucun workspace et qu’aucune racine n’est nommée, un chemin absolu trouve le workspace à partir du dossier propre de la Release
--response-formatdetailedVolume de sortie pour la portée —release, la fermeture d’une Release sans argument d’entité : detailed (par défaut) rapporte chaque diagnostic plus les lignes informatives ; concise rapporte le nombre de diagnostics et uniquement le premier diagnostic. Le verdict et le code de sortie sont identiques dans les deux cas.
--type—Type de plugin pour une vérification —plugin portant uniquement sur le binaire, vérifié par rapport au type auto-déclaré du binaire. N’a de sens qu’avec —plugin ; lorsqu’une entité Plugin fournit le type, omettez-le (une valeur discordante provoque un arrêt).
--unredactedfalseAffiche les valeurs qu’un auteur a déclarées sensibles au lieu de les retenir. Tout ce qu’atteint la sortie — un terminal, un pipe, un fichier, un enregistrement d’écran — porte alors ces valeurs en clair. N’atteint que le graphe qu’écrit —ir-graph et rien d’autre, il nécessite donc —ir-graph