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

aggrega lint

aggrega lint vérifie les conventions de publication — nommage, alignement entre catégorie et répertoire, préfixes d’annotation, discipline de rédaction des schémas et ampleur de l’incrément de version. Il a trois modes, sélectionnés par son argument, qui appliquent la même discipline de conventions à trois portées : le catalogue entier (aucun argument), la fermeture des dépendances d’une seule Release (--release) et le fichier d’une entité (un chemin d’entité, avec une porte de publication --pre-publish facultative). Chaque portée répond à la même question — « ce contenu suit-il la discipline de publication du catalogue ? » — sur une tranche différente du catalogue.

Les conventions sont distinctes de l’exactitude. aggrega lint ne vérifie jamais si le contenu est bien formé ou se compilerait — c’est le rôle d’aggrega validate, qui reprend les trois mêmes portées pour le schéma, les piliers, la résolution des références, extends, la capacité du type d’entrée et le rendu. Un sélecteur de socket ou de slot que la grammaire des sélecteurs ne peut pas lire est un défaut d’exactitude, donc lint ne signale rien à son sujet : validate le refuse, sur le catalogue entier ou sur un seul Component ou une seule Feature — voir sélecteurs déclarés. Les deux commandes sont complémentaires : validate vous dit si le contenu est correct ; lint vous dit s’il est publiable selon les conventions du catalogue.

aggrega lint est facultatif. Le compilateur lui-même reste sans parti pris quant à la discipline du catalogue ; ces règles résident dans un plugin distinct que vous choisissez d’exécuter. Un workspace qui n’exécute jamais aggrega lint se construit et se publie quand même.

Le chemin de l’entité peut être donné en argument positionnel ou avec --entity <path>. --release est mutuellement exclusif avec un argument d’entité — ils sélectionnent des portées différentes ; passer les deux provoque un arrêt.

Conventions sur le catalogue entier (aucun argument)

aggrega lint sans argument exécute les règles structurelles de discipline de publication sur chaque entité du catalogue trouvée sous les répertoires de catalogue configurés. Les constats sont consultatifs — signalés avec la sévérité warn, ils n’interrompent jamais l’exécution sur un seul constat de convention. Utilisez-le pour passer un catalogue au crible à la recherche de dérives de nommage, de catégorie-répertoire et de préfixe d’annotation. Un Aggregate, un Manifest, une Release ou un Workload placé dans un répertoire de catalogue est ignoré plutôt que vérifié : la passe compte chacun de ces types sur une ligne not checked: après son résumé et vous renvoie au mode entité, qui vérifie un document de n’importe quel type.

Un fichier YAML situé 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 document Aggrega qui ne peut pas être lu, dont le YAML ne s’analyse pas, ou dont le kind, le metadata ou le spec n’a pas la forme que prend l’enveloppe d’une entité — un metadata écrit 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 l’analyseur ; rien n’est linté et aucune ligne conventions checked 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, 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 values d’un chart, les définitions de workflow — est ignoré. --release s’arrête de la même manière sur un tel document sous ses répertoires de catalogue.

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

  • Un workspace dont la configuration n’attribue à aucune Release de répertoires de catalogue propres est vérifié 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 s’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 une seule passe sur toutes lirait chaque variante à la fois — l’entité d’une variante masquant celle d’une autre. Il est donc vérifié 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 signalée sous une ligne nommant sa Release et les répertoires qu’elle a lus, suivie des constats de cette passe et de son propre résumé :

    Release release-compose.yaml reads catalog-compose
    conventions checked: 7 entities, 0 advisory finding(s)
    Release release-helm-synth.yaml reads catalog-helm-synth
    conventions checked: 8 entities, 0 advisory finding(s)

    Les Releases qui lisent exactement les mêmes répertoires partagent une seule passe, qui nomme chacune d’elles, de sorte qu’un constat y est signalé une seule fois. Une Release qui ne lit aucun répertoire — son entrée écrit catalog_dirs: [] — est signalée comme n’ayant rien à vérifier, et les autres passes s’exécutent normalement. Avec -o json, le document porte aussi passes : les releases, catalogDirs, findings et summary de chaque passe, tandis que les findings et summary de premier niveau couvrent toutes les passes ensemble. Les Releases que contient un workspace sont ses documents de 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 au lieu d’être signalée comme un catalogue propre : placez les entités sous catalog/, passez --catalog ou définissez workspace.catalog_dirs — ou, dans un workspace qui nomme des Releases, le catalog_dirs propre d’une Release sous workspace.releases. Il n’énumère jamais implicitement le répertoire de travail courant.

Un lien situé sous un répertoire de catalogue qui mène hors du workspace — ou hors d’un répertoire que vous avez nommé en dehors de celui-ci — n’est pas lu, et l’exécution s’arrête là, en nommant le lien, au lieu de signaler comme propre un catalogue dont elle n’a pas pu lire l’un des documents ; un build sur les mêmes répertoires s’arrête sur le même lien. La frontière du workspace expose la règle et ses remèdes.

Conventions sur une Release (--release)

aggrega lint --release <release-path> exécute les mêmes règles structurelles sur les fichiers d’entités du catalogue qu’atteint la fermeture résolue d’une seule Release, plutôt que sur le catalogue entier ou sur une seule entité. Il calcule la fermeture avec la même mécanique qu’un build, puis analyse le fichier de catalogue dont l’auteur de chaque entité est propriétaire. Une entité épinglée depuis un registry et résidant dans un emplacement du cache n’a aucun fichier local à analyser et est ignorée — les règles de publication s’appliquent aux fichiers rédigés localement. Comme pour le mode catalogue entier, les constats sont consultatifs et n’interrompent jamais l’exécution sur un seul constat de convention.

C’est aussi la seule portée qui dispose d’une Release entière, c’est donc là que s’exécutent les règles qui en lisent une — la règle sur les identifiants de connexion décrite dans Les règles de discipline. Une telle règle s’exécute une fois par vérification, après les règles par entité, sur trois documents : l’Aggregate que la Release déploie, tel que son auteur l’a écrit ; la Release, avec sa chaîne extends intégrée, de sorte qu’une Release enfant porte ce dont elle hérite ; et, pour chaque composant que l’Aggregate déclare, le Component dont ce composant est une instance, tel que le catalogue le résout. Aucune valeur de paramètre n’en fait partie, comme à chaque portée : la Release arrive sans son bloc parameters, y compris les valeurs dont elle hérite d’une base, et l’Aggregate sans ses valeurs par défaut ni les valeurs qu’il transmet à chaque module qu’il importe — voir Ce que reçoit un plugin de linter. Ses constats sont signalés sous le fichier de la Release.

C’est le pendant, côté conventions, d’aggrega validate --release, qui vérifie l’exactitude de la même fermeture.

Les linters qu’exécute cette portée sont soumis à l’enregistrement des identités de plugins de confiance situé à côté de la Release, comme un build les y soumet. Avant que l’un d’eux ne s’exécute, --release compare les rattachements plugins.linter configurés avec l’enregistrement de confiance des plugins : un plugin enregistré que la configuration ne rattache plus — un linter ou une porte — interrompt la passe, et un linter lu depuis le cache dont l’artefact n’est pas celui enregistré est refusé au lieu d’être exécuté. Un linter lu depuis le cache est aussi soumis à sa signature enregistrée, au moment de son chargement : lorsque son entrée enregistre une signature vérifiée, le matériel de signature que ce fait nomme dans le cache est vérifié de nouveau, et la passe s’arrête avec E0144 s’il est absent ou différent, et avec E0332 s’il a été créé pour un autre plugin que le linter lu — 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, une entrée n’en enregistrant aucune — ou l’absence d’entrée pour le linter, y compris un enregistrement supprimé — arrête la passe avec E0331, avec les mêmes paramètres qui feraient refuser à aggrega pull un linter non signé. Chacun des trois nomme son remède, aggrega pull --release <release>, qui vérifie la signature du linter auprès de son registry, l’enregistre et met en cache le bundle qu’elle nomme, en réécrivant une copie en cache qui ne correspond plus à son digest. Un linter servi depuis la copie intégrée au binaire du compilateur n’est jamais soumis à l’exigence. Ce sont des échecs de la passe, pas des constats de convention, ils interrompent donc l’exécution là où un constat ne le ferait pas. Les portées catalogue entier et entité unique ne nomment aucune Release et ne lisent aucun enregistrement, de sorte qu’un linter qu’elles lisent depuis le cache n’est vérifié que par rapport à son manifeste en cache. Avant tout cela, --release nomme chaque retrait enregistré sur ce dont dépend la Release, sous la forme d’une ligne deprecation: dans les termes qu’affiche aggrega build — aussi bien un marqueur que le lockfile enregistre contre une référence épinglée qu’un marqueur que l’enregistrement de confiance enregistre contre un linter ou une porte —, de sorte que la passe le signale même là où un refus décrit ci-dessus l’arrête. Un retrait ne change aucun constat ni aucun code de sortie, et un enregistrement de confiance qui existe et ne peut pas être lu arrête la passe au lieu de passer pour un enregistrement qui n’enregistre rien.

Discipline des entités : local et porte de publication

Le mode chemin d’entité s’exécute avec l’une de deux sévérités :

  • Par défaut (local). Exécute les règles de discipline sur le contenu local de l’entité avec la sévérité warn. Aucun accès au registry ; la vérification de l’incrément de version est ignorée. Utilisez-le pendant la rédaction.
  • --pre-publish (porte de publication). Récupère depuis le registry la dernière version publiée hors préversion de l’entité, exécute les mêmes règles avec la sévérité halt, classe en outre la modification comme PATCH / MINOR / MAJOR et s’interrompt si l’incrément proposé de metadata.version est inférieur à ce que la modification exige. Utilisez-le dans le flux de publication, avant aggrega push. --pre-publish ne s’applique qu’à la forme à entité unique.

Un incrément excessif est toujours autorisé ; un incrément insuffisant provoque un arrêt. La première publication d’une entité (aucune version antérieure dans le registry) ignore la vérification de l’incrément et affiche un avertissement indiquant qu’aucune vérification n’a été effectuée.

Quels types le mode entité vérifie

Le mode entité applique le lint au document que vous nommez, quel que soit son type, et le transmet à chaque règle qui lit une seule entité. Chaque règle décide elle-même des types qu’elle décrit, et une règle à laquelle est transmis un type qu’elle ne décrit pas ne signale rien. Ainsi, nommer un Aggregate, un Manifest, une Release ou un Workload — des types que la passe sur le catalogue entier ignore et liste sur sa ligne not checked: — exécute aussi les règles sur ce document, et seules les règles qui décrivent ce type peuvent signaler quelque chose :

RègleTypes sur lesquels elle signale en mode entité
Préfixe d’annotationTout type : elle lit metadata.annotations quel que soit le type du document.
Extensions x-aggrega-* directesTout type : elle lit spec.schema quel que soit le type du document.
Forme du nomComponent, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary et ArtifactLibrary.
Catégorie correspondant au répertoireComponent.
Slot secret déclarant sensitiveComponent et Feature.
Annotation d’identifiants de métriques correspondant à providesComponent.
Provides déclarés par le ComponentRecipe.
Refs dynamiques, redéfinitions d’IdSchemaLibrary.
Limites par défaut du PluginPlugin.
La comparaison de l’incrément de version (--pre-publish)Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate et Plugin (un plugin intégré au compilateur n’est pas comparé) ; une modification de tout autre type est classée MAJOR.
Identifiant de connexion correspondant à la clé cibleAucun : elle lit une Release entière, elle ne s’exécute donc que sous --release.

Un Aggregate, un Manifest, une Release et un Workload ne déclarent ni metadata.annotations ni spec.schema dans leurs schémas, de sorte qu’un document de l’un d’eux conforme au schéma de son type ne suscite rien de la part des deux règles qui lisent n’importe quel type ; ces deux règles ne signalent quelque chose à son sujet que lorsqu’il porte malgré tout l’une de ces clés, que le schéma de son type refuse comme propriété inattendue. Ce qu’ajoute le fait de nommer un Aggregate, c’est la comparaison de l’incrément de version sous --pre-publish, qui le compare à sa version publiée comme le décrit la grille ci-dessous.

La grille d’incrément de version

En mode --pre-publish, la modification est comparée à la version publiée précédente et classée :

  • PATCH — modifications portant uniquement sur la documentation ou les commentaires.
  • MINOR — modifications strictement additives (un nouveau champ facultatif, une nouvelle entrée).
  • MAJOR — suppressions, restriction de type, ou un champ auparavant facultatif devenant obligatoire.

La comparaison dépend du type d’entité : Component, Feature et SchemaLibrary sont comparés en tenant compte de leurs champs porteurs de schéma ; MappingLibrary est comparée au niveau des clés d’entrée (les corps d’entrée sont opaques, de sorte qu’un corps modifié est traité de manière conservatrice comme MAJOR) ; Recipe et FeatureRecipe sont comparées sur leurs champs porteurs. Un Aggregate est comparé sur ses déclarations de paramètres, ses composants et ses sous-systèmes ; la valeur par défaut d’un paramètre n’atteint pas davantage la comparaison que toute autre valeur de paramètre (voir Ce que reçoit un plugin de linter), de sorte qu’une modification limitée à une valeur par défaut — l’ajouter, la modifier ou la supprimer — n’en fait pas partie, pas plus qu’une modification d’une clé hors du vocabulaire des slots de paramètre. Un incrément insuffisant provoque un arrêt avec un diagnostic nommant l’incrément requis.

Les règles de discipline

La plupart des règles ont un paramètre par workspace sous lint.publishing_discipline dans .aggrega-config.yaml et une surcharge CLI correspondante, chaque surcharge ayant un pendant --no-. La priorité est --no-<flag> sur --<flag> sur la valeur de la configuration du workspace, à chaque portée : le catalogue entier, une Release et une entité. Chaque règle est active par défaut, et chaque valeur par défaut est fondée soit sur la mécanique de la plateforme, soit sur une convention de catalogue documentée ; les paramètres sont des désactivations pour un workspace qui a une raison d’assouplir l’une d’elles.

Les règles qui n’ont aucun paramètre l’indiquent dans leur entrée ci-dessous, et la raison est la même dans chaque cas : elles signalent un fait sur l’entité et laissent la décision à l’auteur, il n’y a donc aucun jugement à assouplir. La grille d’incrément de version décrite ci-dessus n’en a pas non plus — elle compare le contenu proposé à la version publiée et signale ce que la modification exige, ce qui est une propriété de la modification plutôt qu’une préférence du workspace.

  • Préfixe d’annotation — les espaces de noms réservés (aggrega.ai/, et feature.aggrega.ai/ en dehors d’une Feature) appartiennent à la plateforme et sont rejetés sur les autres clés. Active par défaut ; désactivable avec allow_aggrega_ai_prefix.
  • Forme du nom — chaque type d’entité a une convention de forme de nom (nombre de segments pour les types cloud-native ; PascalCase pour les types de bibliothèque). Active par défaut ; désactivable avec allow_nonstandard_names.
  • Références dynamiques — les entrées d’une SchemaLibrary ne peuvent pas utiliser $dynamicAnchor / $dynamicRef (l’expansion de $ref à la compilation par la plateforme ne peut pas les résoudre). Active par défaut ; désactivable avec allow_dynamic_refs.
  • Surcharges d’id — les entrées d’une SchemaLibrary ne peuvent pas déclarer leur propre $id (la plateforme dérive le $id canonique). Active par défaut ; désactivable avec allow_id_overrides.
  • La catégorie correspond au répertoire — le label component.aggrega.ai/category d’un Component doit correspondre au premier segment de répertoire sous core/, choisi dans l’ensemble fermé de catégories (ai-agent, ai-model, ai-tool, ai-pipeline, datastore, gateway, mesh, network, messaging, storage, compute, observability, security, bigdata, devtool). Active par défaut pour les entités sous un chemin core/ ; désactivable avec allow_category_mismatches.
  • Extensions x-aggrega-* directes — rédiger directement des clés x-aggrega-* dans un schéma de Component ou de Feature est déconseillé au profit du chemin de rédaction de premier plan. Active par défaut ; désactivable avec allow_direct_x_aggrega_extensions.
  • Provides déclarés par le Component — le spec.provides d’une Recipe publie une clé par entrée, et le Component que la Recipe implémente déclare, dans le pilier provides de son spec.schema, les clés que le type expose. C’est par rapport à cette déclaration qu’une référence inject from: est vérifiée, de sorte qu’une clé qu’une Recipe publie sans que le Component la déclare est produite puis refusée là où un consommateur la relie. Publier au-delà du contrat déclaré est accepté au moment du build, c’est pourquoi le constat est consultatif plutôt qu’un rejet. Active par défaut pour les Recipes ; désactivable avec allow_undeclared_recipe_provides.
  • Limites par défaut d’un Plugin — le spec.runtime d’un Plugin porte maxMemoryPages et timeoutMs, les deux plafonds que l’hôte applique lorsqu’il charge et exécute le plugin. Un Plugin qui ne fixe ni l’un ni l’autre s’exécute avec les valeurs par défaut de la plateforme, ce qui est un résultat sûr et non une erreur ; la règle signale donc que les valeurs par défaut sont en vigueur et que des plafonds explicites peuvent être fixés. Active par défaut pour les entités Plugin ; elle n’a aucun paramètre.
  • Un slot de secret déclare la sensibilité — un slot de rattachement peut fixer, par son sélecteur de labels, le type de Feature qui le remplit à secret, et peut déclarer séparément sensitive: true pour indiquer que tout ce qui le remplit manipule du matériel secret. Le sélecteur indique quels remplissages sont admissibles ; le marqueur indique le traitement. Un slot qui fixe le type sans déclarer de marqueur laisse ce traitement à redéduire du sélecteur au lieu d’être lu directement. La règle lit chaque slot qu’une entité déclare : ceux de son propre bloc de rattachements sous spec.featuresSchema et, sur un Component, ceux que chaque socket de dépendance déclare sous spec.usesSchema.<socket>.featuresSchema pour les connexions qui passent par lui — un constat sur le slot d’un socket nomme le socket en plus du slot. Active par défaut pour les Components et les Features ; elle n’a aucun paramètre.
  • Le credential de la connexion correspond à la clé de la cible (connection-credential-matches-target-key) — un serveur qui vérifie une clé conserve la clé qu’il vérifie dans un slot de son propre Component, et un appelant présente une clé sur la connexion par laquelle il atteint le serveur. Aucune des deux extrémités ne voit les attachements de l’autre, de sorte que les deux ne détiennent une même clé que parce que leurs auteurs l’écrivent aux deux extrémités — généralement en faisant lire un même paramètre aux deux attachements — et un build ne les compare jamais. Cette règle le fait, et c’est la seule règle qui lit une Release entière, elle s’exécute donc sous --release et dans aucune autre portée. Elle trouve les deux extrémités par les noms que leur donne le catalogue standard : la clé de la cible est le slot api_key que son Component déclare dans spec.featuresSchema, et celle de l’appelant est le slot credential sur la connexion, écrit à uses.<socket>.<alias>.features.credential dans l’Aggregate ou sur une connexion que la Release câble. Pour chaque connexion dont la cible déclare api_key et n’est pas étiquetée managed, elle signale une connexion portant un credential vers une cible dont le slot de clé n’est pas rempli, un slot de clé rempli sans credential sur la connexion, et deux extrémités qui nomment leur secret différemment. Ce qu’elle compare, c’est le localisateur de chaque extrémité — l’origin qu’écrit un attachement, dans values dans l’Aggregate ou dans infra dans la Release — tel que l’auteur l’a écrit, de sorte que deux extrémités lisant un même paramètre sont considérées comme égales et que deux littéraux se comparent par leur texte ; rien n’est résolu, et un constat nomme le composant, la connexion, la cible et les deux slots mais ne cite jamais aucun des deux localisateurs, puisque le texte qui y est écrit peut être le secret lui-même. Une cible ne déclarant aucun slot api_key ne produit rien, et un slot qui n’est pas la clé de l’appelant, comme le jeton de pull de registry d’un serveur de modèles, n’est jamais lu. N’est pas non plus jugée une cible dont le Component est étiqueté component.aggrega.ai/hosting: managed, quel que soit le contenu de son slot api_key : un tel Component représente un service que son fournisseur exploite, donc rien de ce que la Release exécute ne vérifie une clé sur lui, et là où il déclare api_key — la clé d’une API de modèles hébergée, par exemple, sous le nom que lui donne le produit du fournisseur — le slot contient la clé que la Release présente à ce fournisseur, jamais une clé que présentent ses appelants. Une cible étiquetée self-hosted, external ou mixed, ou ne portant aucune étiquette d’hébergement, est jugée. Une connexion sur le socket scrape_target — le nom que le catalogue standard donne au socket par lequel un scraper de métriques atteint ses cibles — est un scrape, et la question de savoir si le credential d’un scrape doit être la clé d’appelant de la cible dépend du produit de la cible : certains servent leurs métriques sans credential, certains les placent derrière la clé que présente chaque appelant, et certains acceptent un jeton qui leur est propre. Pour un scrape, la règle lit donc ce que le Component de la cible déclare dans son annotation observability.aggrega.ai/metrics-credential : avec none, le scrape n’est pas jugé du tout ; avec separate-token, son credential n’est jamais comparé à l’api_key de la cible, de sorte qu’aucun des trois constats n’est signalé à son sujet ; avec target-key, il est jugé comme toute autre connexion. La règle ne lit que ces trois valeurs, de sorte qu’un scrape vers une cible sans l’annotation, ou avec toute autre valeur, est jugé comme toute autre connexion — et chaque connexion sur un autre socket, y compris une connexion vers un modèle, un outil ou un datastore, est jugée de la même façon quoi que dise l’annotation de la cible. Elle lit les attachements écrits sur la cible et sur la connexion : un attachement api_key atteignant la cible depuis un sous-système ou une frontière laisse au contraire cette connexion non jugée, un attachement qu’ajoute une annotation n’en fait pas partie, de sorte qu’un slot de clé rempli uniquement de cette façon est lu comme non rempli, une extrémité dont l’attachement n’écrit aucun localisateur n’est comparée que sur le fait d’être remplie, et un composant qu’apporte un module importé n’est pas lu. Comme les noms des slots, l’étiquette d’hébergement, le nom du socket de scrape et l’annotation des métriques sont des conventions de catalogue qu’aucun mot-clé de schéma ne marque, un catalogue qui nomme les slots différemment ne produit rien, un socket de scraping nommé différemment est jugé comme tout autre socket, et un Component qui conserve la clé d’un fournisseur dans un slot nommé api_key sans l’étiquette managed est lu comme une cible vérifiant cette clé, puisque le nom du slot, l’étiquette et l’annotation sont tout ce que la règle lit du Component d’une cible. Activée par défaut ; désactivable avec allow_connection_credential_mismatches.
  • L’annotation du credential des métriques correspond aux provides (metrics-credential-annotation-matches-provides) — un Component peut énoncer deux faits sur ses métriques. Son annotation observability.aggrega.ai/metrics-credential indique comment s’authentifient les métriques du produit : none, elles sont servies sans credential ; target-key, elles acceptent la clé que le Component exige de chaque appelant, celle que contient son slot api_key ; separate-token, elles acceptent un jeton qui leur est propre. La clé provides metrics_credential_required, déclarée dans le pilier provides de son spec.schema, est ce que chacune de ses Recipes publie pour dire si les métriques d’une instance nécessitent un credential — ce qui peut dépendre de la configuration de l’instance, puisque des métriques derrière la clé d’appelant n’en nécessitent un que tant qu’une clé est attachée, de sorte que l’annotation ne peut pas la remplacer. Les deux énoncent un même fait sur le produit, donc cette règle exige qu’ils concordent : un Component annoté none qui déclare la clé, et un Component annoté target-key ou separate-token qui ne la déclare pas, sont chacun signalés, et le constat nomme le Component, la valeur de l’annotation et la clé en trop ou manquante. Un Component sans l’annotation, ou avec toute autre valeur, ne produit rien. La règle lit le Component tel qu’il est écrit, de sorte qu’un Component qui en étend un autre — dont le schéma est celui de sa base — ne produit rien et que sa base est lue là où elle est déclarée, et qu’un pilier provides écrit comme une référence, une composition ou un corps échappé écrit sous forme de texte n’est pas un pilier qu’elle peut énumérer, de sorte que ce Component ne produit rien non plus. Activée par défaut pour les Components ; elle n’a aucun paramètre.

L’immuabilité des artefacts ne fait pas partie de ces règles, et elle n’a aucun paramètre. Un name:version publié est définitif : aggrega push compare le digest déjà publié sous ce tag au digest que produirait le contenu sur le point d’être poussé, et refuse de l’écraser avec un contenu différent. Pousser à nouveau un contenu identique octet pour octet ne téléverse rien et n’attache que ce qui manque encore à cette publication — sa date de publication, et sa signature là où le push signe. Aucun flag ni aucun paramètre de la configuration du workspace n’assouplit cela, car le registry n’expose aucun chemin d’écrasement qu’un opérateur pourrait choisir d’activer. Un contenu modifié est publié sous une nouvelle version ; c’est --pre-publish qui vérifie cette montée de version par rapport à la release précédente.

Les flags de surcharge par règle s’appliquent à une seule invocation et n’ont intentionnellement aucune variable d’environnement — ils sont déjà adossés à la configuration dans .aggrega-config.yaml sous lint.publishing_discipline. Le modèle général de priorité AGGREGA_* est décrit dans environment-variables.md.

Au moment du build et au moment de la publication

La règle qui déconseille x-aggrega-* s’exécute aussi pendant aggrega build, où elle apparaît comme un avertissement ; aggrega lint --pre-publish élève le même constat au rang d’erreur. Les builds locaux portent l’avertissement ; la porte de publication l’impose.

Pendant que vous rédigez, dans votre éditeur

Votre éditeur pose deux questions différentes sur une entité du catalogue, et ce sont les deux par lesquelles s’ouvre cette page. L’entité est-elle correcte — s’analyse-t-elle, les piliers se résolvent-ils, se rend-elle ? C’est aggrega validate, et une session d’éditeur y répond toujours. L’entité est-elle publiable — le nom suit-il la convention, le fichier se trouve-t-il dans le répertoire qu’attend sa catégorie, les préfixes d’annotation sont-ils corrects ? Ce sont ces règles, et une session d’éditeur n’y répond que lorsque vous le demandez.

C’est désactivé tant que vous ne l’activez pas. Activez-le avec serve.lint_on_validate dans le .aggrega-config.yaml du workspace sur les entités duquel vous voulez recevoir les conseils :

serve:
lint_on_validate: true

Il n’existe aucun flag de ligne de commande pour cela, et c’est délibéré : la question porte sur le contenu propre d’un workspace particulier, et c’est vous qui rédigez ce workspace, et non vous qui lancez le language server — c’est votre éditeur qui le fait.

Une fois activé, chaque entité que vous validez porte aussi ces constats, chacun nommant la règle qui l’a produit, à côté des constats de correction. Trois choses en découlent, et ce sont elles qui le rendent utilisable pendant la saisie :

  • Les constats restent des conseils. Une entité qui enfreint une convention est tout de même validée, et sa Release se résout et se rend toujours. Activer le paramètre ajoute une couche de conseils ; cela n’amène jamais votre éditeur à refuser de fonctionner.
  • Vous pouvez distinguer les deux. Chaque problème publié nomme la couche qui l’a soulevé, de sorte qu’un problème de nommage et un échec de résolution sur le même fichier se lisent comme deux choses différentes plutôt que comme un seul problème signalé deux fois.
  • C’est ce que vous avez saisi qui est vérifié. Les règles lisent le buffer plutôt que le fichier sur le disque, de sorte qu’un nom que vous corrigez cesse d’être signalé avant que vous n’enregistriez.

Seul le mode sur le contenu local s’exécute sur cette couche : aucun registry n’est consulté, rien n’est récupéré, rien n’est écrit. On atteint la comparaison --pre-publish en la demandant — votre éditeur envoie une requête à cet effet, de la même façon que vous tapez --pre-publish dans le terminal — et jamais en modifiant le paramètre ci-dessus. Une vérification qui s’exécute chaque fois que vous touchez un document est précisément l’endroit où un registry ne doit pas être atteint, ce mode reste donc quelque chose que vous invoquez plutôt que quelque chose qui s’exécute d’office.

Demander explicitement la vérification fonctionne quel que soit le paramètre, dans les trois portées ci-dessus. Ainsi, un workspace qui n’a jamais activé la couche par modification peut tout de même demander à son éditeur de passer en revue le catalogue, la fermeture d’une Release ou une seule entité — et obtenir les mêmes constats que ceux qu’affiche cette commande. Le paramètre décide seulement si la vérification s’exécute aussi là où vous ne l’avez pas demandée nommément.

Les détails du protocole sont répartis sur deux pages : ce que signifie la requête et quand l’envoyer se trouvent dans la page aggrega serve de la référence, et ses paramètres ainsi que la forme de sa réponse, champ par champ, se trouvent dans la référence du format wire.

Choisir le linter

Les règles sont livrées sous la forme d’un plugin Wasm standard de linter de publication. Comme les règles résident dans un plugin plutôt que dans le compilateur, une entreprise peut diriger aggrega lint vers un autre plugin pour imposer sa propre discipline de catalogue sans modifier le compilateur.

Un workspace peut attacher plus d’un linter sous plugins.linter, et chaque attachement s’exécute : dans l’ordre où les attachements sont écrits, chacun à sa propre fonction d’entrée, tous leurs constats étant signalés ensemble. C’est ce qui permet à un catalogue de conserver les règles standard et d’ajouter les siennes à côté au lieu de choisir entre les deux. --plugin est l’exception — il exécute exactement un artefact depuis un chemin du système de fichiers à la place des attachements configurés, ce qui le rend utile pendant le développement d’une règle.

Un rattachement nomme son plugin avec uri:, et function: nomme une fonction d’entrée de ce plugin. Une entrée qui nomme une function: et aucun uri: nomme une fonction d’aucun plugin, de sorte que la configuration est refusée dès sa lecture, sous E0224, en nommant le fichier et la place de l’entrée dans sa liste — ajoutez l’uri du plugin qui exporte la fonction. Une entrée qui ne nomme ni l’un ni l’autre ne rattache rien et est ignorée ; lorsqu’elle est la seule entrée, le linter standard s’exécute à sa propre fonction d’entrée par défaut, comme sans aucun plugins.linter.

Ce que reçoit un plugin de linter

Aucune valeur de paramètre n’atteint un plugin de linter, dans aucune portée. La valeur d’un paramètre peut être elle-même un credential — l’origin d’un attachement secret peut être un template lisant un paramètre que la Release satisfait, et le secret est alors la valeur de ce paramètre — et le plugin qu’attache un workspace peut être un plugin qu’il n’a pas écrit, de sorte que chaque document est transmis avec ses valeurs de paramètres retenues :

  • Un Aggregate conserve chaque déclaration de paramètre, en ne gardant que les clés avec lesquelles une déclaration s’écrit — le vocabulaire des slots de paramètre : son type, sa description et ses contraintes — et chaque déclaration imbriquée sous ses properties, items et valuesType est traitée de la même façon. Le default de la déclaration est retenu à chaque niveau, en supprimant la clé plutôt qu’en la vidant, de sorte qu’un plugin ne peut pas savoir si une déclaration en donne un. Une clé hors de ce vocabulaire est retenue avec tout ce qu’elle contient, à chaque niveau : le build ne donne aucun sens à une telle clé, et un brouillon qui orthographie mal une clé peut porter un secret sous celle-ci. Une entrée sous parameters qui n’est pas une déclaration est retenue entièrement.
  • Chaque module listé sous aggregates d’un Aggregate perd son bloc parameters, qui contient les valeurs passées à ce module.
  • Une Release perd son bloc parameters, qu’elle écrive les valeurs en ligne ou les importe avec $import.
  • Tout autre document qui porte un bloc parameters sous spec le perd entièrement ; aucun autre type n’en déclare.

Cela vaut pour l’entité nommée sur la ligne de commande, pour la version publiée à laquelle --pre-publish la compare, pour chaque entité que parcourent les passes sur le catalogue entier et sous --release, et pour les documents que reçoit une règle lisant une Release entière. Un template qui lit un paramètre n’est pas une valeur et conserve son texte, de sorte qu’une règle voit toujours quel paramètre lit une valeur rédigée.

Exemples

Passer en revue le catalogue entier à la recherche d’écarts par rapport aux conventions :

aggrega lint --catalog ./catalog

Exécuter le lint d’une entité en local pendant la rédaction :

aggrega lint core/datastore/postgres/component.yaml

Exécuter la porte de publication avant de publier une nouvelle version :

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

Assouplir une règle pour une seule exécution :

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

Voir aussi

  • ./aggrega-validate.md — le pendant de correction sur les trois mêmes portées.
  • ./aggrega-build.md — valide dans le cadre de la compilation ; fait apparaître l’avertissement sur x-aggrega-* avec la gravité warn.
  • ./aggrega-push.md — publie une entité dans le registry ; aggrega lint --pre-publish est la porte qui le précède.
  • ./aggrega-pull.md — résout et épingle les dépendances.
  • ./aggrega-serve.md — le language server qui signale ces constats dans votre éditeur, et le paramètre qui active la couche par modification.
  • ../errors/warnings.md — avertissements non fatals, y compris les constats de lint en mode local.

Synopsis

aggrega lint [entity-path] [flags]

Description

aggrega lint checks publishing CONVENTIONS — naming, category-directory
alignment, annotation prefixes, and the rest of the publishing-linter
discipline. It does not check correctness (schema, pillars, resolution,
render): that is aggrega validate.
Three invocation shapes, mirroring validate:
aggrega lint conventions across every catalog entity
aggrega lint --release <path> conventions across a Release's dependency closure
aggrega lint <entity> publishing discipline for one entity
Without an entity argument, lint runs the structural conventions rules
over every catalog entity found under the catalog directories. Where the
workspace configuration gives its Releases catalog directories of their own
under workspace.releases, it runs them once for each Release, over the
directories that Release reads, and reports each pass under a line naming
its Releases and those directories; Releases reading the same directories
share one pass. With --release it runs them over the entities that
Release's closure reaches, and also runs the rules that read a whole
Release: once, over the Aggregate it deploys, the Release and the
Components the Aggregate's components are instances of, with every
parameter value removed. In both, findings are advisory (warn severity)
and never halt.
With an entity path, lint runs the publishing-linter rule set against
that one entity. In default mode the rules run at warn severity over
local content without consulting any registry. With --pre-publish the
previous registry version is fetched and the schema-evolution
classification is compared against the proposed version bump; mismatches
halt. --pre-publish applies to the single-entity shape only. Per-workspace
policy flags from .aggrega-config.yaml's lint.publishing_discipline block
can be overridden per invocation via the --allow-*/--no-allow-* flag pairs,
in all three shapes.
All three shapes accept -o json, which replaces the human report on standard
output with one structured document: every finding with its severity, the rule
that produced it, its short code (the code printed at the head of its row in
the human report, which aggrega explain expands), its message, and the entity
file it concerns, plus counts by severity. A finding from a rule Aggrega does
not declare, one a linter of your own adds, carries no short code, as its row
prints none. A finding carries a line and column only when the rule that
produced it located the issue that precisely; otherwise the file alone locates
it. The message is the rule's own text, carried through unchanged, so the
structured and human renderings never word a finding differently. The exit
status is the same under either format.

Options

OptionPar défautDescription
--allow-aggrega-ai-prefixfalseForce allow_aggrega_ai_prefix=true
--allow-category-mismatchesfalseForce allow_category_mismatches=true
--allow-connection-credential-mismatchesfalseForce allow_connection_credential_mismatches=true
--allow-direct-x-aggrega-extensionsfalseForce allow_direct_x_aggrega_extensions=true
--allow-dynamic-refsfalseForce allow_dynamic_refs=true pour cette invocation
--allow-id-overridesfalseForce allow_id_overrides=true pour cette invocation
--allow-nonstandard-namesfalseForce allow_nonstandard_names=true
--allow-undeclared-recipe-providesfalseForce allow_undeclared_recipe_provides=true
--baseline—Compare la vérification d’évolution avant publication à cette version déjà publiée précise au lieu de la version la plus élevée sélectionnée automatiquement en dessous de celle en cours de publication ; doit être un tag SemVer strict présent dans le registry (nécessite —pre-publish)
--catalog[]Répertoire de catalogue ; répétable. Chaque —catalog <dir> est ajouté en tête de la pile de recherche de catalogues (la première correspondance l’emporte) : les catalog_dirs du workspace ou, pour une Release à laquelle la configuration du workspace donne 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 en existe un. Une liste catalog_dirs écrite vide ne lit aucun catalogue local. Utilisé par les passes de conventions sur le catalogue entier et sous —release.
--entity—Chemin du YAML de l’entité à analyser par le lint (sinon, passez-le comme argument positionnel)
--no-allow-aggrega-ai-prefixfalseForce allow_aggrega_ai_prefix=false
--no-allow-category-mismatchesfalseForce allow_category_mismatches=false
--no-allow-connection-credential-mismatchesfalseForce allow_connection_credential_mismatches=false
--no-allow-direct-x-aggrega-extensionsfalseForce allow_direct_x_aggrega_extensions=false
--no-allow-dynamic-refsfalseForce allow_dynamic_refs=false pour cette invocation
--no-allow-id-overridesfalseForce allow_id_overrides=false pour cette invocation
--no-allow-nonstandard-namesfalseForce allow_nonstandard_names=false
--no-allow-undeclared-recipe-providesfalseForce allow_undeclared_recipe_provides=false
--output, -otextFormat de sortie : text|json.
--plugin—Chemin du système de fichiers vers l’artefact .wasm du linter de publication (exécute cet artefact au lieu des attachements plugins.linter du workspace)
--pre-publishfalseRécupère la version précédente du registry et vérifie la montée de version proposée par rapport à la classification de l’évolution du schéma
--release—Chemin d’un YAML de Release dont on vérifie les conventions sur la fermeture de ses dépendances résolues (mutuellement exclusif avec un argument d’entité). 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 indiquée, un chemin absolu trouve le workspace à partir du dossier propre de la Release