aggrega serve
aggrega serve exécute Aggrega en tant que démon compiler-as-service de longue durée pour l’intégration aux IDE. Il communique en JSON-RPC 2.0 sur stdin/stdout et conserve l’état du catalog-resolver, du parse-cache et des diagnostics d’une requête à l’autre, de sorte que les opérations de l’éditeur obtiennent un retour en moins d’une seconde au lieu de payer le coût complet du chargement du catalogue à chaque frappe.
Le démon est normalement lancé comme sous-processus par une extension d’éditeur, et non exécuté à la main. Une extension VS Code est le client de référence ; d’autres éditeurs peuvent s’intégrer en parlant le même protocole.
Le protocole
Le protocole de transmission est JSON-RPC 2.0 avec un framing Content-Length, dans l’espace de noms de méthodes aggrega/. Ce n’est intentionnellement pas le Language Server Protocol — Aggrega a des opérations de domaine (une requête sur le graphe IR, un signal d’invalidation du cache) pour lesquelles LSP n’a pas d’équivalent. Une extension d’éditeur traduit entre les requêtes LSP de l’éditeur et ces méthodes aggrega/* ; les valeurs de position, de plage et d’emplacement au format LSP sont réutilisées là où elles conviennent.
Deux méthodes conservent leurs noms $/ standard du protocole au lieu d’être renommées dans l’espace de noms aggrega/, parce que toutes deux relèvent du transport, ne portent aucune signification propre à Aggrega, et qu’un client parlant déjà le protocole les gère sans rien ajouter : $/cancelRequest, qui arrête une requête dont le client ne veut plus la réponse, et $/progress, par lequel le démon rend compte d’une opération longue pendant son exécution. Toutes deux sont décrites ci-dessous.
🔴 Chaque requête ci-dessous porte workspaceRoot, le chemin absolu de l’espace de travail sur lequel elle agit, et ce n’est pas répété pour chaque méthode. Trois ne le portent pas, car leur objet n’est pas un espace de travail : aggrega/initialize, aggrega/getSchema et aggrega/scaffoldEntity — sauf que aggrega/scaffoldEntity en nomme un lorsqu’il écrit ou liste un exemple exécutable. Voir Chaque requête nomme l’espace de travail qu’elle concerne pour ce qu’obtient une requête qui n’en nomme aucun, et Déclarer l’espace de travail pour lequel vous voulez recevoir les diagnostics pour savoir où vont les diagnostics poussés.
Les structures champ par champ sont publiées sous forme de schéma, et c’est dans la référence des formats de transmission qu’il faut les lire. Cette page indique l’objet de paramètres de chaque méthode, chaque résultat et chaque charge utile de notification — chaque champ avec son type, s’il est obligatoire et ce qu’il contient — ainsi que trois propriétés valables sur toute la surface plutôt que par méthode : les deux champs que chaque requête admet en plus de ceux que déclare sa propre méthode, à savoir workspaceRoot ci-dessus et le workDoneToken de Suivre une opération longue ; le fait qu’un objet params portant une clé que sa méthode n’accepte pas est refusé, l’ensemble accepté étant nommé dans le refus ; et l’endroit où une collection absente arrive sur le fil sous forme de null plutôt que de collection vide. Elle est générée à partir de ce schéma, elle évolue donc quand le contrat évolue.
Cette page porte le protocole, l’autre porte les structures, et elles sont faites pour être lues ensemble. Ici : le framing, à quoi sert chaque méthode, jusqu’où elle porte, ce qu’elle écrit, quels refus elle lève et pourquoi, les codes d’erreur et que faire pour chacun. Là-bas : ce qu’il faut mettre sur le fil, clé par clé. La liste ci-dessous nomme donc chaque méthode et dit ce que signifie l’interroger, et la liste des champs de la requête que vous composez se trouve dans la référence à côté.
Requêtes :
aggrega/initialize— poignée de main. Négocie l’encodage des positions (le serveur préfère UTF-8, puis UTF-16, puis UTF-32, et utilise UTF-16 par défaut), reçoit l’espace de travail que vous déclarez pour les diagnostics poussés, et indique la racine de cet espace de travail, la couche de configuration à partir de laquelle ses paramètres ont été résolus et le marqueur qui l’a résolue. La réponse porte égalementversion, la version du binaire qui répond : la même valeur que celle queaggrega versionindique pour ce binaire. Elle décrit le processus en cours d’exécution ; une fois que le fichier à partir duquel le démon a été lancé a été remplacé — par une recompilation au même chemin, par exemple —,versionnomme donc toujours le démon en cours d’exécution tandis qu’interroger le fichier nomme son remplaçant ; lisez-la ici lorsque la question est de savoir à quelle version vous parlez.workspaceRootest facultatif et déclare un espace de travail plutôt que d’agir sur lui — voir Déclarer l’espace de travail pour lequel vous voulez recevoir les diagnostics. Envoyezcapabilities.window.workDoneProgress: truepour indiquer que votre client sait gérer les notifications de progression ;capabilities.workDoneProgressdans la réponse le reprend, et le champ est absent pour un client qui n’a rien déclaré. Voir Suivre une opération longue.aggrega/validate— valide le contenu d’un fichier ; renvoie des diagnostics.releaseest un chemin relatif à la racine de l’espace de travail qui nomme la Release par rapport à laquelle valider — la même valeur que celle que prendaggrega/irGraph, et la même que celle que prendaggrega build --releaselorsqu’il est exécuté depuis la racine. Il est facultatif et détermine la portée de la réponse : nommez une Release et les vérifications qui en ont besoin s’exécutent par rapport à elle — une entité de catalogue est vérifiée en tant qu’entité unique dans les termes de cette Release, et tout autre document par rapport à la fermeture des dépendances de cette Release ; omettez-le et la réponse couvre ce que l’on peut exiger du document seul, et portecheckedpour l’indiquer. Une valeur présente mais mal formée est refusée dans les deux cas — un chemin absolu, ou un chemin qui se résout hors de la racine de l’espace de travail, est rejeté plutôt que résolu. Voir Validation en direct.aggrega/diagnostics— renvoie les constats conservés pour un fichier. Si une validation de ce même fichier est en cours lorsque la requête arrive, la réponse l’attend et rapporte ce qu’elle a trouvé, de sorte que la réponse n’est jamais un certificat de bonne santé pour un fichier dans lequel le démon est en train de trouver des problèmes. Voir Demander les diagnostics pendant qu’une validation est en cours.aggrega/hover— contenu de survol pour l’entité à une position.releaseest facultatif et répond dans les termes de cette Release — voir Répondre dans les termes d’une Release.aggrega/completion— candidats de complétion à une position. Là où le curseur nomme une entité par type — letyped’un composant, letyped’un rattachement de Feature, une valeurextends:, leimplements:d’une Recipe ou d’une FeatureRecipe —, les candidats sont les noms de ce type que déclarent les documents propres à votre espace de travail et, pour un Component ou une Feature, également les noms que déclarent voscatalog_dirsconfigurés, chacun proposé une fois et par ordre de nom. Un espace de travail qui prend ses Components et ses Features dans un catalogue se les voit donc proposer, et pas seulement ce qu’il a rédigé lui-même. Les Recipes et les FeatureRecipes, proposées à la valeur d’un mappage de Manifest, proviennent des documents propres à l’espace de travail. Une entité que seul le cache d’artefacts ou un registre détient n’est pas proposée : répondre à une complétion ne télécharge jamais rien.releaseest facultatif et répond dans les termes de cette Release — voir Répondre dans les termes d’une Release.aggrega/resolve— résout l’entité référencée à une position (atteindre la définition).releaseest facultatif et répond dans les termes de cette Release — voir Répondre dans les termes d’une Release.aggrega/findReferences/aggrega/findImplementations. Chacune prend unreleasefacultatif et répond dans les termes de cette Release — voir Répondre dans les termes d’une Release.aggrega/irGraph— le graphe IR compilé d’une Release, pour l’introspection dans l’éditeur.releaseest un chemin relatif à la racine de l’espace de travail, qui nomme une Release à l’intérieur de celui-ci — la même valeur que celle que prendaggrega build --releaselorsqu’il est exécuté depuis la racine. Toute autre forme est refusée avec l’erreur standard invalid-params, qui nomme ce qu’il faut envoyer à la place : un chemin absolu, un chemin qui se résout hors de la racine de l’espace de travail — qu’il en sorte tel qu’il est écrit ou par un lien, vers le fichier ou vers un répertoire en chemin — et une valeur vide sont tous rejetés plutôt que résolus, de sorte qu’une requête ne rend jamais compte d’un fichier que l’espace de travail ne contient pas. Une Release que la configuration de votre espace de travail nomme, en tant quebuild.authoring_releaseou clé deworkspace.releases, fait partie de l’espace de travail où que se trouve son fichier ; un lien à l’intérieur de l’espace de travail qui y mène est donc accepté, commeaggrega/releaseCandidatesla liste. Un répertoire de catalogue que lit la Release et qui ne peut pas être parcouru — un répertoire présent mais illisible, par exemple — est refusé comme le refuseaggrega inspect, avant que quoi que ce soit d’autre ne soit lu : l’erreur est1004entity-not-resolvable, son message est le rapport que la ligne de commande affiche pour ce répertoire, sur une ligne ([CATALOG_ERROR] <directory>: catalog load: …), et aucun graphe n’est tracé sur les répertoires restants. Un répertoire que liste la configuration de l’espace de travail et qui n’est pas un répertoire — rien n’existe à cet endroit, par exemple — est refusé de la même manière et au même moment,1004entity-not-resolvable, son message étant le refus que lui oppose chaque commande, qui nomme l’entrée, le fichier et la ligne de configuration qui la listent, et le paramètre (Où les entités locales sont lues). Un répertoire de catalogue contenant un lien qui sort du répertoire dans lequel ses lectures doivent rester — un document ou un répertoire lié depuis ailleurs, sous un répertoire de catalogue à l’intérieur de l’espace de travail ou sous un répertoire que la configuration nomme hors de celui-ci — est refusé de la même manière et au même moment, avec1004et la phrase propre à la condition, qui nomme le lien et l’endroit où il mène : rien n’est lu à travers un tel lien, et un graphe tracé sans lui pourrait résoudre à sa place une autre entité du même nom. Il en va de même pour un lien qui sort des documents situés à côté de la Release, là où la Release nomme son Aggregate ou son Manifest par identité. Un fichier que la Release, son Manifest ou une Release qu’elle étend nomme par un chemin —aggregate:,manifest:,extends:ou un$import:de parameters — et qui sort de l’espace de travail, tel qu’il est écrit ou par un lien, est refusé avec la phrase propre à la condition (fatal-halts.md § « A reference to another file leads out of the directory it must stay inside (Une référence à un autre fichier sort du répertoire à l’intérieur duquel elle doit rester) »), les données de l’erreur le plaçant sur la clé de la Release qui a mené au fichier, et rien n’est lu dans ce fichier ; une Release que la configuration nomme hors de l’espace de travail est tenue de la même manière au répertoire qui la contient, de sorte qu’un chemin écrit par elle ou par une Release vers laquelle mène sa chaîne et qui sort de ce répertoire est refusé lui aussi. Notez queaggrega/releaseCandidatesrépond avec des chemins absolus ; un client qui alimente une surface à partir de l’autre convertit donc entre les deux. Que ce paramètre refuse une graphie que les paramètres par documentfileeturiacceptent est délibéré, et Quelles graphies accepte un paramètre que vous envoyez explique ce qui en décide. Le graphe masque chaque valeur qu’un auteur a déclarée sensible, exactement comme--ir-graphla masque sur la ligne de commande : chacune est remplacée par le marqueur que décritaggrega-inspect« Sortie lisible par machine », et tout le reste est transmis tel que le compilateur l’a enregistré.unredacted: truedemande ces valeurs en clair — la graphie du protocole pour le--unredactedde la ligne de commande, et le seul moyen de les demander ; absent ou àfalse, la réponse les masque. Tout ce que la réponse atteint porte alors les valeurs en clair ; un client ne les demande donc que là où la personne qui l’utilise l’a fait.aggrega/build— compile une Release et écrit ses artefacts dans le répertoire de sortie de l’espace de travail, le même répertoire que celui où écritaggrega buildlorsqu’il est exécuté depuis la racine de l’espace de travail.releaseporte le même contrat que ci-dessus. Il effectue le rendu avec tous les contrôles actifs, de sorte qu’une divergence sur laquelle un build en ligne de commande s’arrêterait l’arrête ici aussi. Un répertoire de catalogue que lit la Release et qui ne peut pas être parcouru — un répertoire présent mais illisible, par exemple — est refusé commeaggrega buildle refuse, avant que quoi que ce soit ne soit écrit : aucun artefact, et aucun lockfile lorsqueautoPullest défini. Il en va de même d’un répertoire que liste la configuration de l’espace de travail et qui n’est pas un répertoire, dans les termes oùaggrega buildle refuse (D’où sont lues les entités locales). Le refus est celui que donneaggrega/irGraphpour le même répertoire,1004entity-not-resolvable avec le rapport de la ligne de commande sur une seule ligne, et un lien qui sort des lectures d’un répertoire de catalogue, ou des documents situés à côté de la Release, est refusé commeaggrega/irGraphle refuse, sans rien écrire. La réponse nomme leoutputDirectorydans lequel il a écrit et lesfilesqu’il a écrits, chacun relatif à ce répertoire et triés, ainsi que les éventuellesnoticessoulevées par l’exécution ; les constats qui portent une position dans un document passent plutôt paraggrega/publishDiagnostics. Une Release qui refuse pendant son rendu reçoit pour réponse ce refus dans les termes du compilateur, toutes causes comprises, et le refus est publié là où il pointe — voir Un refus soulevé pendant le rendu. LorsqueautoPullétait défini, la réponse porte aussidependencyResolution, le même rapport que celui par lequel répondaggrega/resolveDependencies, de sorte qu’un client qui a rempli les dépendances dans le cadre du build lit ce qui a été épinglé sans redemander — ainsi que l’endroit d’où la résolution de ce build a tiré chaque référence, un fait propre à cette exécution que le lockfile n’enregistre pas. Chaque avis porte laclassde la surface qui l’a soulevé —deprecation,catalog,catalog-lint,extends,release-composition, oudependency-resolutionpour une ligne soulevée par la résolution des dépendances décrite plus bas — et uneclassvide lorsque le démon n’a pas de nom pour cette surface, qu’un client affiche alors comme le simpletextplutôt que de deviner la correspondance la plus proche. Les fichiers que l’écriture trouve dans le répertoire de sortie, ou dans un répertoire situé en dessous dans lequel elle a écrit un fichier ou qu’elle a traversé, et que ce build n’a pas écrits sont laissés en place et nommés dans un seul avis après ceux de l’exécution elle-même, sous uneclassvide, dans la phrase par laquelleaggrega buildimprime son avertissement — voir Fichiers que le build n’a pas écrits ;filesne les nomme jamais.outputParentindique où vont les artefacts à l’intérieur de l’espace de travail, et son nom dit tout ce qu’il signifie : c’est le répertoire dans lequel le répertoire de sortie est créé, de sorte qu’envoyerdocsécrit les artefacts dansdocs/distplutôt que dansdocslui-même — exactement ce que produit un build exécuté dansdocsdepuis un terminal. Si vous l’omettez, le build écrit là où écrit une exécution à la racine de l’espace de travail. Il se lit différemment duoutputDirqu’acceptent les autres requêtes d’écriture ici, et c’est délibéré : celles-ci nomment le répertoire dans lequel on écrit, celui-ci nomme le parent de ce répertoire, et les deux portent des noms différents parce que ce sont des choses différentes. Il reste une destination à l’intérieur de l’espace de travail, de sorte qu’une valeur absolue, une valeur qui remonte hors de la racine et une valeur qui en sort par un lien — un répertoire lié hors de la racine, ou un répertoire pas encore créé sous un tel répertoire — sont refusées plutôt que résolues. Le répertoire de sortie créé à l’intérieur, et chaque fichier que le build y écrit, sont eux aussi tenus à l’espace de travail : lorsque l’un d’eux sort de l’espace de travail par un lien, le build est refusé avec1004et la phrase propre à la condition, qui nomme le lien et l’endroit où il mène, et rien n’est vidé ni écrit.autoPullrésout les dépendances de la Release avant le rendu, la même résolution que celle qu’effectueaggrega/resolveDependencies, et est désactivé sauf si une requête le demande, conformément à la valeur par défaut de la ligne de commande elle-même ; sans lui, une Release qui n’a pas de lockfile est refusée avec l’erreur lockfile-absent, qui nomme ce qu’il faut exécuter. AvecautoPulldéfini, cette requête atteint des registres et écrit le lockfile — voir Atteindre un registre, et écrire. Une requête qui résout d’abord ne fait toujours le rendu de la Release qu’une fois : déterminer quelles références distantes une Release consomme est en soi un rendu, de sorte que la résolution a déjà rendu ce sur quoi porte le build, et le build reçoit sa réponse à partir de ce rendu plutôt que de le répéter.policyInputnomme un répertoire à l’intérieur de l’espace de travail, relatif à sa racine, dans lequel le build écrit aussi la charge utile que chaque rôle de gouvernance remet à un plugin qui y est attaché — les fichiers qu’écritaggrega build --policy-input, sous les mêmes noms — que le build aille à son terme ou s’arrête ; lesnoticesde la réponse indiquent alors combien de fichiers ont été écrits et nomment chaque rôle pour lequel aucun fichier n’a été écrit, sous uneclassvide. Pour une requête qui échoue, les fichiers écrits sont sur le disque et ce bilan ne figure pas dans la réponse : l’enveloppe d’erreur ne porte que le refus. C’est une destination, de sorte qu’une valeur absolue ou une valeur qui remonte hors de l’espace de travail est refusée avant que quoi que ce soit ne s’exécute.aggrega/buildPreview— indique ce qu’un build de la Release écrirait, sans rien en écrire.releaseporte le même contrat que ci-dessus. Il exécute le même calcul queaggrega/build, avec les mêmes contrôles, de sorte qu’une Release serait soit refusée par les deux, soit rapportée par les deux — ce qui fait du choix entre les deux un choix portant sur la sortie plutôt que sur la rigueur. Un répertoire de catalogue que lit la Release et qui ne peut pas être parcouru, ou qui contient un lien sortant du répertoire dans lequel ses lectures doivent rester, est refusé de la même manière, avant que quoi que ce soit ne soit rendu, et il en va de même d’un répertoire que liste la configuration de l’espace de travail et qui n’est pas un répertoire, comme pouraggrega/build. La réponse portefiles, les noms relatifs à la sortie qu’un build émettrait, triés, ainsi que les éventuellesnotices; il n’y a pas deoutputDirectory, puisque rien n’a été écrit nulle part qui puisse être nommé. Une Release qui refuse pendant son rendu reçoit sa réponse et est publiée exactement commeaggrega/buildy répond et la publie. Il refuseautoPullavec une erreur invalid-params qui nomme ce qu’il faut envoyer à la place : remplir les dépendances écrit le lockfile, et cette requête n’écrit aucun lockfile. Il n’atteint aucun registre.policyInputest la seule écriture qu’il effectue, et seulement s’il est envoyé : il écrit les charges utiles de gouvernance dans ce répertoire exactement comme le faitaggrega/build— les fichiers qu’écritaggrega build --dry-run --policy-input— en laissant intacts le répertoire de sortie et le lockfile, avec le même bilan dans lesnoticeset la même limite : pour une requête qui échoue, les fichiers écrits sont sur le disque et le bilan ne figure pas dans la réponse.aggrega/resolveDependencies— résout les dépendances de catalogue et de source de la Release dans le cache, épingle les entrées externes que consomme son rendu dans le stockage adressé par contenu, et écrit son lockfile.releaseest un chemin relatif à la racine de l’espace de travail, la même valeur que celle que prendaggrega/irGraph, refusée sous les mêmes formes.upgradeabandonne les épinglages enregistrés et résout de nouveau, en faisant passer chaque dépendance à la version disponible la plus élevée ;targetsrestreint cela aux références d’entités qu’il nomme, en conservant tous les autres épinglages.verifycompare la résolution enregistrée à celle que cette requête effectuerait sans lui, en respectant de la même manière les épinglages enregistrés, et n’écrit ni lockfile, ni enregistrement de confiance des plugins, nientity.lock— le cache est lu et rempli comme il le serait sans lui — en répondantverified: trueet letoolchainqu’enregistre le lockfile.verifyest refusé comme paramètres invalides à côté deupgrade, à côté detargets, et à côté depinSourcesquelle que soit sa valeur, avant que quoi que ce soit ne soit résolu ou qu’une progression ne soit signalée : une mise à niveau abandonne les épinglages qu’une vérification a pour raison d’être de respecter, les cibles nommées ne sont résolues de nouveau que par une mise à niveau, etpinSourcesdécide si une résolution enregistre les épinglages qui manquent à unentity.lockou refuse à cause d’eux, ce que ne fait en aucun cas une comparaison qui n’écrit aucunentity.lock. La ligne de commande et l’outil de l’assistant refusent les mêmes paires. La réponse nomme lelockfilequ’elle a écrit ou auquel elle a comparé et chaque référence qu’elle a épinglée, dansentities,librariesetplugins, chaque entrée portant laversionvers laquelle elle s’est résolue et sasource— l’endroit d’où cette exécution a pris la référence, avec le mot qu’afficheaggrega pull --detailpour la même résolution :fetched-fresh,cache-reuse,local,in-binaryouexternal— ainsi quesourceArtifacts,trustedPlugins,externalInputs— le nombre d’entrées externes que le lockfile épingle une fois l’exécution terminée, en comptant à la fois celles reportées et celles découvertes par cette exécution — et les éventuellesnoticeslevées par la résolution. 🔴 Une réponse réussie ne signifie pas à elle seule que l’épinglage des entrées externes est complet. Lorsque l’exécution a épinglé chaque dépendance mais n’a pas pu achever de déterminer quelles entrées externes consomme la Release, elle répond avecincompleteExternalInputs, qui indique ce qui a arrêté la découverte, et répond tout de même par un succès — les épinglages des dépendances sont complets et sur disque, et signaler l’ensemble de la requête comme un échec vous dirait de refaire un travail déjà correct. Lisez ce champ avant de considérer un lockfile comme entièrement épinglé : il est absent lorsque rien n’est resté non découvert, c’est donc sa présence qui constitue le signal. Il n’existe pas de paramètre de répertoire de catalogue : la pile de recherche est celle que configure l’espace de travail. C’est l’unique requête d’épinglage de la session pour une Release, et c’est là que les entrées externes sont épinglées aussi — les URL que consomme un rendu découlent de ce qu’il rend ; cette requête fait donc le rendu de la Release pour le découvrir, et une requête de build est ensuite servie à partir de ce qu’elle a enregistré. Une Recipe ou une FeatureRecipe que construit la Release et dont leentity.lockn’enregistre aucun épinglage pour une entrée que lit l’entité fait refuser la requête, en nommantaggrega pinet chaque entrée non enregistrée ;pinSources: trueexécute à la place cette étape d’épinglage sur ces entités, en écrivant leentity.lockà côté de chacune — la même étape que celle qu’exécuteaggrega/pin, qui écrit les mêmes octets. En son absence,pinSourcessuit lepin_sources_at_pullde l’espace de travail ; envoyé, il remplace ce paramètre dans les deux sens, de sorte quefalserefuse même dans un espace de travail configuré pour épingler. Cette requête atteint des registres et écrit — voir Atteindre un registre, et écrire.aggrega/pin— enregistre, dans leentity.locksitué à côté d’une Recipe ou d’une FeatureRecipe, l’épinglage de contenu de chaque entrée que l’entité lit hors de son propre document : une source distante dont les coordonnées sont écrites en entier, un fichier qu’importe une entrée artifacts, et chaque fichier qu’une source locale apporte à ce que contient une publication de l’entité. C’est la même étape que celle qu’exécuteaggrega pindans un terminal, et elle écrit les mêmes octets.entityest obligatoire et est un chemin relatif à la racine de l’espace de travail nommant le document de l’entité, refusé sous les trois mêmes formes querelease. Aucune Release n’est nommée : une source distante dont les coordonnées ne contiennent aucun modèle nomme un seul artefact pour chaque Release qui utilise l’entité, donc rien de ce que fournit une Release n’est nécessaire pour l’épingler, tandis qu’une source distante dont les coordonnées proviennent d’un modèle est épinglée par Release paraggrega/resolveDependencies; une source locale écrite sous forme de modèle apporte chaque fichier du répertoire de l’entité, et chacun d’eux est épinglé ici.dryRunrésout les entrées et répond avec le verrou que l’étape écrirait, sous forme decontent, sans rien écrire à côté de l’entité ; le cache de contenu se remplit tout de même. La réponse porteentity,kind,nameetpinnable— false pour un type qui ne lit rien de ce qu’un verrou enregistre, auquel cas rien n’a été touché à côté de l’entité et tous les autres champs sont absents — et sinon lelockqu’elle a écrit,changed(false lorsque le verrou enregistrait déjà chaque épinglage et a été laissé identique octet pour octet),removedlorsque l’entité ne lit désormais plus rien de ce qu’un verrou enregistre et que son verrou a été supprimé, etpins, une entrée par classe d’épinglage avec le nombre que contient le verrou. Le fichier de l’entité lui-même n’est jamais écrit. Cette requête écrit à côté de l’entité, à l’intérieur de l’espace de travail, et atteint les hôtes que nomment les sources de l’entité — voir Atteindre un registre, et écrire.aggrega/cacheStatus— ce que contiennent les caches sur disque : une entrée par élément mis en cache, avec sa taille et, le cas échéant, son digest de contenu, regroupées par classe. Ne prend que l’espace de travail. Chaque classe porte unreach—workspacepour le cache d’artefacts sous le répertoire de cache propre à cet espace de travail,machinepour les stockages de modules compilés, de descriptions de plugins et de bundles de documentation que partagent tous les projets de la machine — etscopenomme directement les classes à l’échelle de la machine. Elle n’écrit rien. Voir Atteindre un registre, et écrire pour savoir pourquoi la portée figure sur une réponse qui ne change rien.aggrega/cachePrune,aggrega/cacheEvict,aggrega/cacheClear— récupèrent l’espace du contenu mis en cache. Un prune supprime ce qu’aucun lockfile d’espace de travail ne référence ; une éviction réduit le stockage des modules compilés àmaxSize, une quantité d’octets écrite comme l’écrit la ligne de commande (5GiB,512MiBou un nombre d’octets) ; un clear vide chaque cache auquel s’adresse cette session. Chaque réponse nomme ce qu’elle a supprimé, chaque suppression portant lereachde la classe dont elle provient, et chacune portescope. Chaque réponse nomme aussi ce qu’elle a laissé en place parce qu’un autre processus l’avait ouvert — Windows refuse de supprimer un fichier ouvert, et l’opération poursuit avec le reste plutôt que d’échouer : un prune ou une éviction liste ces entrées dansheldOpen, et un clear compte, pour chaque cache qu’il a vidé, les fichiers qu’il a laissés dansheldOpenFileset leur taille dansheldOpenBytes. Ailleurs, la liste est vide et les décomptes sont à zéro, et une exécution ultérieure peut récupérer ce qui a été laissé. Ces requêtes portent au-delà de l’espace de travail — voir Atteindre un registre, et écrire.aggrega/registryList— les registres que cet espace de travail est configuré pour atteindre : pour chaque entrée, l’hôte, l’alias facultatif, s’il s’agit du registre par défaut, sa posture de confiance sous forme de champs distincts et la présence ou non d’un identifiant pour cet hôte. Ne prend que l’espace de travail. Elle ne contacte aucun registre. L’état de l’identifiant indique uniquement sa présence — jamais l’identifiant, jamais sa forme, et jamais si le registre l’accepterait, ce qui nécessiterait un aller-retour réseau qu’une liste n’effectue pas — et il est lu dans le magasin d’identifiants à l’échelle de la machine, ce quecredentialStateIsMachineWideindique explicitement.aggrega/search— recherche dans l’index local des registres configurés. Chaque champ restreint la recherche et chacun est facultatif ; un objet params vide demande donc tout ce que contient l’index. Elle ne contacte aucun réseau : l’index est l’instantané hors ligne écrit sous le répertoire de cache propre à cet espace de travail. La version signalée est celle qu’une résolution retiendrait — une version dont le retrait porte une signature à laquelle cet espace de travail fait confiance est exclue et nommée dansretracted— et la réponse porte sa propre provenance :indexesdonne l’âge de l’instantané de chaque registre consulté,stalesignale celui qu’il vaut la peine de rafraîchir, etmissingIndexHostsnomme les registres configurés sans index local, dont le contenu est donc absent de la réponse.aggrega/registryAdd— enregistre un registre et sa politique de confiance des signatures.hostest obligatoire ; tout le reste façonne la politique ou la cible d’écriture.keyPathettrustedRootnomment des fichiers : une valeur absolue — un fichier choisi dans une boîte de dialogue, par exemple — est lue là où elle pointe ; une valeur relative nomme un fichier à l’intérieur de l’espace de travail, résolu par rapport à la racine de l’espace de travail plutôt que par rapport au répertoire dans lequel s’exécute le démon, et une valeur qui remonte hors de la racine ou en sort par un lien est refusée avec l’erreur invalid-params avant que quoi que ce soit ne soit lu ou écrit. UntrustedRootrelatif est enregistré comme le fichier qu’il nomme dans l’espace de travail, de sorte que l’entrée nomme ce fichier quel que soit le répertoire dans lequel s’exécute une vérification ultérieure.fetchTrustvaut true par défaut lorsque la clé est absente, comme sur la ligne de commande, et adopte au premier contact la politique annoncée par le registre lui-même ;trustdans la réponse indique ce qui s’est passé — la politique a été épinglée, le registre n’en annonçait aucune (et, avecunreachableà côté, n’a pas pu être atteint du tout), la base de référence intégrée du hub officiel a été épinglée à sa place, ou aucune récupération n’a été tentée. L’enregistrement est celui qu’effectueaggrega registry add: la même récupération avec la même posture réseau, qui écrit la même entrée octet pour octet. Dans un espace de travail hors ligne, la récupération est refusée avant toute connexion, le registre n’est donc jamais interrogé, et un registre autre que le hub officiel est refusé à moins que la requête ne fournisseidentitiesoukeyPath, qui enregistrent exactement ce qui a été envoyé et n’effectuent aucune récupération : le message de l’erreur est la phrase qu’affiche la ligne de commande, précédée du code court de la conditionE0310— comme le message de chaque refus de cette requête qui nomme une condition commence par son code court — et rien n’est écrit. Le hub officiel est tout de même écrit sur sa base de référence intégrée, avec une réponse portanttrust.baselineà true ettrust.reasonindiquant que le hub n’a pas été interrogé sur sa politique de confiance parce que l’espace de travail est hors ligne — la raison par laquelle commence l’avis de la ligne de commande — et sansnotAdvertised, puisque le hub n’a jamais été interrogé. Cette requête écrit par défaut la configuration globale — voir Atteindre un registre, et écrire.aggrega/registryRemove— supprime l’entrée d’un registre, désigné par son hôte ou son alias convivial. Un jeton qui ne correspond à rien est refusé plutôt que de recevoir une réponse de succès sur une configuration inchangée. Cette requête écrit par défaut la configuration globale — voir Atteindre un registre, et écrire.aggrega/logout— supprime l’identifiant stocké pour un registre, la même suppression que celle qu’effectueaggrega logoutdans un terminal.registryest obligatoire et nomme l’hôte du registre tel que vous vous y êtes authentifié ; il n’y a ici aucun alias convivial à résoudre, car le magasin d’identifiants est indexé par l’adresse auprès de laquelle un client s’authentifie plutôt que par quoi que ce soit que nomme une configuration, de sorte qu’un hôte qu’aucun espace de travail ne configure peut tout de même avoir un identifiant que vous pouvez supprimer. Un hôte pour lequel le magasin ne contient aucun identifiant est supprimé avec succès et rien n’est réécrit — un appelant qui a demandé qu’un hôte n’ait aucun identifiant a obtenu ce qu’il demandait ; c’est donc une réponse plutôt qu’une erreur, et c’est aussi ce que fait la commande du terminal. La réponse porteregistryetscope. Elle ne porte aucune partie de l’identifiant sous aucune forme, et n’indique rien quant à savoir s’il y en avait un : l’établir nécessiterait une seconde lecture du magasin que personne n’a demandée ; interrogez doncaggrega/registryListlorsque la question est la présence. Elle ne contacte aucun registre — supprimer un identifiant stocké est un acte local, et on ne demande pas si ce registre aurait accepté l’identifiant. Cette requête modifie le magasin d’identifiants que partagent tous les projets de la machine — voir Atteindre un registre, et écrire.aggrega/registryUpdate— rafraîchit l’index local consultable que litaggrega/search. Unregistryabsent rafraîchit chaque registre configuré ; en nommer un ne rafraîchit que ce registre.upgraderelit intégralement chaque dépôt, sans rien comparer avec l’index déjà écrit ; un rafraîchissement sans lui relit déjà tout ce qui a changé. La réponse porte le nombre d’enregistrements de chaque hôte, les dépôts qu’elle n’a pas pu lire — chacun avec unereasonqui commence par le type du dernier échec de la lecture lorsqu’il y en a un —,readsRetried, le nombre de ses lectures que le registre a refusées ou interrompues en cours de route et qui ont été redemandées, chacune comptée une fois et zéro compris, les marqueurs de dépréciation rencontrés, l’errord’un hôte en échec — avecunreachableà côté lorsque ce registre n’a pas pu être atteint — etindexRoot, le répertoire sous le cache propre à cet espace de travail dans lequel les index ont été écrits. Cette requête atteint chaque registre qu’elle rafraîchit — voir Atteindre un registre, et écrire.aggrega/publishEntity— empaquette une entité du catalogue et la publie dans un registre.entityest un chemin relatif à la racine du workspace qui nomme le document à publier, refusé sous les trois mêmes formes querelease: absent, absolu, ou résolu hors de la racine. Une entité Plugin nécessite aussiplugin, le même type de chemin, qui nomme l’exécutable publié dans le manifeste propre de l’entité.registryest la destination et vaut par défaut celle configurée pour le workspace.dryRuncalcule le bundle et le digest sur lequel aboutirait sa publication, et ne contacte aucun registre. Omettresignsuit la politique propre du registre de destination, ce que fait la ligne de commande lorsque son flag est absent, tandis que l’envoyer relève du choix de l’appelant — et ni l’un ni l’autre n’assouplit le refus, car une politique de registre ou de workspace qui exige une signature refuse une publication non signée quoi que dise le champ.pinSources: trueexécute l’étape de pin de l’auteur de l’entité sur l’entité avant qu’elle soit empaquetée, de sorte que leentity.lockque l’étape écrit à côté d’elle fait partie de ce qui est publié — la même étape que celle qu’exécuteaggrega/pin. Elle s’exécute avant tout refus qui juge le contenu de l’entité — une politique de signature, la garde d’immuabilité —, de sorte qu’une publication refusée à ce stade laisse tout de même le lock écrit ; un refus portant sur la requête elle-même, comme un workspace hors ligne ou l’absence de destination, intervient en premier et ne pinne rien, de même que le refus d’une entité qui partage son répertoire avec une autre entité, dans lequel l’étape ne doit pas écrire de lock. Absent, il suit le paramètrepin_sources_at_pushdu workspace ; envoyé, il remplace ce paramètre dans les deux sens. SousdryRun, l’étape signale le lock qu’elle écrirait et n’écrit rien. Une publication qui n’exécute pas l’étape refuse une Recipe ou une FeatureRecipe dont leentity.lockn’enregistre aucun pin pour une entrée qu’elle lit, ou un pin auquel l’entrée ne correspond plus, avant que quoi que ce soit soit empaqueté — sousdryRunégalement —, en nommantaggrega pin,pinSourcesetpin_sources_at_push; c’est le refus queaggrega/resolveDependenciessoulève sur le même lock. La réponse contientreference,tag,kind,mediaType, la pairesize, ledigestpublié — sousdryRun, le digest sur lequel aboutirait cette publication, celui qu’afficheaggrega push --dry-run—,signed,alreadyPublished,dryRunetreach;pin— la même réponse que celle que donneaggrega/pin— là où l’étape s’est exécutée ; etwholeDirectorySourcelà où la source locale de l’entité est écrite sous forme de modèle, en nommant cette source telle qu’elle a été rédigée. Une telle source ne choisit son répertoire qu’une fois qu’une Release remplit le modèle, de sorte que la publication emporte chaque fichier du répertoire de l’entité plutôt que seulement les fichiers que l’entité nomme, et ce champ est la manière dont un appelant apprend que c’est le cas — lors d’une exécution à blanc également. Elle contient aussiwindowsUnusableEntrieslà où l’archive emportée par la publication contient des entrées que Windows ne peut pas contenir telles qu’elles sont écrites — un chemin dont une partie porte le nom d’un périphérique, commeCON,AUXouNUL, quelle que soit la casse et quelle que soit l’extension qui suit, ou une partie se terminant par un point ou une espace —, en les nommant chacune, d’abord le nom de fichier du document de l’entité lui-même, puis les fichiers qu’il emporte ; ce champ est absent là où il n’y en a aucune, ce qui inclut une entité publiée sous la forme de son seul document.aggregaexécuté sous Windows refuse de décompresser une telle entrée, de sorte qu’un workspace Windows ne peut pas utiliser la version. Ce sont les entrées au sujet desquellesaggrega pushémet un avertissement, et une requête qui a demandé à être tenue informée lit les mêmes lignes d’avertissement dans la progression de la publication ; ni l’un ni l’autre ne refuse quoi que ce soit, de sorte que la publication se poursuit ou est refusée exactement comme elle le serait sans elles, sousdryRunégalement. Ceci écrit dans un registre et va au-delà de cette machine, et avec l’étape de pin, écrit aussi à côté de l’entité — voir Atteindre un registre et écrire.aggrega/publishArtifact— publie un artefact de données autonome, comme un bundle de documentation.fileest un chemin relatif à la racine du workspace, soumis au même contrat, et ses octets sont publiés tels quels : aucune enveloppe d’entité n’est analysée et aucun aiguillage n’est fait selon un kind.nameettagnomment ce sous quoi il est publié, et tous deux sont obligatoires.mediaTypevaut par défaut le type de bundle de documentation. La réponse contientreference,tag,mediaType, la pairesize, ledigestpublié,alreadyPublished,dryRunetreach. Il ne signe rien — un artefact publié est signé ensuite par référence avecaggrega/signArtifacts, qui n’a besoin que de la référence que signale cette réponse. Ceci écrit dans un registre et va au-delà de cette machine — voir Atteindre un registre et écrire.aggrega/signArtifacts— signe des artefacts déjà publiés et attache chaque signature.referencescontient une ou plusieurs adresses de registre plutôt que des chemins, de sorte qu’elles ne sont soumises à aucun contrat relatif au workspace ; une liste vide, ou une entrée vide dans celle-ci, est refusée. Une seule identité sert l’ensemble du lot et est résolue avant qu’aucune référence ne soit signée, de sorte qu’un lot pour lequel aucun identifiant n’est disponible est refusé dès le début plutôt qu’en cours de route. Il en va de même d’un lot dont les références nécessiteraient des identifiants différents : une requête ne nomme aucune clé, il s’agit donc de la configuration du workspace qui nomme une clé détenue pour le registre d’une référence et aucune, ou une autre clé, pour celui d’une deuxième — rien n’est signé, et le refus nomme les registres de chaque côté, comme le décrit References signed together need different signing credentials (Des références signées ensemble nécessitent des identifiants de signature différents). Signer une référence sous laquelle rien n’a été publié est refusé plutôt qu’attaché à rien, et une référence portant déjà une signature que la politique de confiance de son registre vérifie est laissée telle quelle et comptée comme signée, comme le décritaggrega sign.jobs, facultatif, indique combien de références sont signées à la fois : en son absence, elles sont signées l’une après l’autre, et une valeur inférieure à 1 est refusée avec l’erreur invalid-params avant qu’aucune référence ne soit lue. Chaque référence est tout de même signée exactement comme elle le serait seule, comme le décritaggrega sign, et la progression que signale la requête comme la réponse conservent l’ordre dans lequel les références ont été données. La réponse contientsigned, chaque entrée nommant unereferenceet ledigestpublié sur lequel sa signature s’engage, avecreach; un lot dans lequel une référence quelconque a échoué reçoit pour réponse un échec qui les nomme chacune plutôt qu’un résultat avec une liste écourtée. Ceci écrit dans un registre et va au-delà de cette machine — voir Atteindre un registre et écrire.aggrega/deprecateArtifact— attache un marqueur de dépréciation signé à un artefact déjà publié. Envoyez soit une seulereferenceavec saseverityet sareason, soitfromnommant un fichier de lot relatif à la racine du workspace — envoyer les deux est refusé. Les champs de contenu sont obligatoires plutôt que demandés de manière interactive : personne ne surveille ce flux, de sorte qu’une requête à laquelle il en manque un est refusée en nommant ce qu’il faut envoyer. Ils n’appartiennent qu’à la seulereference: un fichier de lot porte le contenu de chaque marqueur dans ses propres entrées, de sorte qu’uneseverity, unereason, unreplacementou unmessageenvoyé à côté defromest refusé comme paramètre invalide, en nommant chacun de ceux qui ont été envoyés, plutôt qu’ignoré. Les mêmes entrées sans clé qu’acceptent les deux requêtes de signature s’appliquent ici, car le marqueur est signé par son propre digest, et les entrées d’un fichier de lot sont tenues à un seul identifiant exactement comme le sont les références d’un lot de signature. La réponse contientmarked, chaque entrée nommant lareferenceretirée, saseverity, l’horodatageissuedOnet ledigestdu manifeste propre du marqueur — le marqueur est attaché comme referrer sans tag de l’artefact qu’il retire, de sorte que rien d’autre ne l’adresse —, avecreach. Ceci écrit dans un registre et va au-delà de cette machine — voir Atteindre un registre et écrire.aggrega/catalogIndex— l’index des entités : lekind, lename, l’apiVersion, ladescription, leslabels, le fichier source et l’originde chaque entité du workspace nommé par la requête. Accepte le workspace et, de manière facultative,release: l’ensemble est une propriété de cette racine du workspace et des répertoires de catalogue qu’elle configure, ou, avecrelease, des répertoires que la configuration attribue à cette Release — voir Répondre dans les termes d’une Release. Il couvre les deux endroits d’où provient une entité — les documents Aggrega sous la racine du workspace et les Features que contiennent les répertoires de catalogue configurés —, car c’est la surface sur laquelle un client effectue une jointure lorsqu’il a besoin des champs descriptifs d’une entité, et un index qui ne connaîtrait que l’un des deux laisserait une partie de chaque liste de candidats impossible à résoudre. Un document du workspace compte comme une entité lorsqu’il déclare à la fois unkind:et unmetadata.nameet ne déclare aucuneapiVersionappartenant au groupe d’un autre projet, de sorte que le YAML qui se trouve par hasard dans l’arborescence — le fichier de valeurs d’un chart, une configuration de CI, un manifeste Kubernetes rendu — est ignoré plutôt que listé. Un document qui ne déclare aucuneapiVersionest signalé : c’est un document Aggrega auquel il manque un champ, et le voir listé est la manière dont vous découvrez qu’il est là, à corriger. Voir Comment une entité est adressée pour ce que signifientoriginet unfilevide. Aucun document situé derrière un lien menant hors de la racine du workspace n’est lu : un répertoire hors de la racine n’est pas parcouru, et un fichier hors de celle-ci n’est pas lu quoi qu’il déclare, de sorte qu’une entité que votre éditeur affiche sous un tel lien n’est pas listée comme appartenant au workspace — ni proposée paraggrega/attachCandidatesouaggrega/connectionCandidates, qui lisent les mêmes documents, même lorsque votre éditeur a ce document ouvert. Cela vaut quoi que déclare le document. La seule exception est une Release que nomme la configuration de votre workspace — en tant quebuild.authoring_releaseou en tant que clé deworkspace.releases, jugée d’après le fichier auquel mène le lien, de sorte que nommer le lien ou ce fichier revient au même —, qui est lue, depuis le fichier auquel mène le lien, listée à l’emplacement propre du lien, commeaggrega/releaseCandidatesla liste, et non nommée ; un fichier nommé par l’un de ces paramètres qui déclare autre chose qu’une Release n’est pas listé, et son lien est nommé. Les répertoires de catalogue configurés sont la manière dont un workspace lit d’autres entités conservées ailleurs, de sorte qu’un lien vers un répertoire que la configuration liste souscatalog_dirs— pour le workspace ou pour une Release — n’est pas parcouru comme le sont les documents propres du workspace, ni nommé non plus : la configuration l’a atteint, et ses Features sont listées depuis le catalogue, comme le sont celles de chaque répertoire de catalogue configuré. Les Features listées depuis les répertoires de catalogue n’en incluent jamais une située derrière un lien menant hors du répertoire dans lequel les lectures d’un répertoire de catalogue doivent rester — le workspace, pour un répertoire de catalogue qui s’y trouve, ou le répertoire lui-même, pour un répertoire que la configuration nomme hors de celui-ci —, de sorte qu’une entité que la réponse nomme comme située derrière un lien qu’elle n’a pas lu n’est jamais listée en plus à côté de ce nom. La réponse nomme chacun de ces liens dansunreadLinkedDirs, pour un lien vers un répertoire, et dansunreadLinkedFiles, pour un lien dont le nom se termine par.yamlou.ymlet qui mène à un fichier — relativement à la racine, là où se trouve le lien, dans l’ordre dans lequel le workspace est parcouru —, afin qu’un client puisse en expliquer la raison. Un lien que la recherche écarte, par son nom, par son emplacement ou par un.gitignore, n’est pas nommé, et dans une réponse dans les termes d’une Release, un lien situé sous un répertoire de catalogue que seules d’autres Releases lisent ne l’est pas non plus. Un lien situé sous un répertoire de catalogue hors du workspace n’a pas d’emplacement relatif à la racine sous lequel être nommé, et n’est pas nommé. Les deux champs sont toujours présents, et vides lorsqu’il n’existe aucun lien de ce type. Lorsque le fichier de configuration propre du workspace, ou l’overlay géré par la CI à côté de lui, est lui-même un lien menant hors du workspace, ce fichier est nommé dansunreadLinkedFilesquelle que soit la manière dont la recherche le traite, et l’index est la lecture propre du workspace sans rien de configuré — aucun répertoire de catalogue n’est lu pour lui, et un index dans les termes d’une Release est refusé ; voir Racine du workspace et Release active.aggrega/entityDefinition— ce en quoi se résout l’entité nommée : sonkind, son proprenameet saversion, sadescriptionet sonpublishScopelorsqu’elle en a, lefiledans lequel elle a été déclarée, l’authoredLengthdu texte rédigé qui la sous-tend, et sadefinitionsous forme de document YAML avec l’héritage déjà appliqué.fileest signalé pour chaque kind, sous la forme d’un chemin que vous pouvez ouvrir — relatif à la racine du workspace pour un document qui s’y trouve, absolu pour un document situé hors de celle-ci, selon Comment s’écrit un chemin signalé. Il est vide dans un cas : une entité résolue depuis un registre n’a sur cette machine aucun document rédigé à nommer.authoredLengthrépond à une autre question — la quantité de texte rédigé que la résolution a conservée —, et seul un Aggregate est servi avec un tel texte, lisez donc les deux séparément plutôt que comme une paire.nameest l’identité d’une entité, écrite de la manière dont une entité en référence une autre, et peut porter un suffixe de version. C’est la seule requête ici qui part d’un nom plutôt que d’un curseur, c’est donc celle à poser lorsque vous savez déjà de quelle entité il s’agit.releaseest facultatif et résout le nom dans les termes de cette Release — voir Répondre dans les termes d’une Release. Un nom qui ne se résout en rien est refusé plutôt que de recevoir pour réponse un document vide ; voir Distinguer les deux refus par nom.namepeut à la place être une référence de registre —oci://<host>/<repository>:<tag>, ou@<digest>à la place de:<tag>—, et la réponse est alors l’entité publiée à cette coordonnée, lue depuis son registre, avecpublishednommant ce qui a été lu ; voir Interroger une coordonnée.aggrega/releaseClosure— la fermeture des dépendances d’une Release : les entités qu’elle atteint et à quelles versions résolues, dansentities,librariesetplugins, avec les identitésaggregateetmanifestvers lesquelles ses deux pointeurs se sont résolus, les éventuelsmappingDiagnosticssoulevés par la résolution, et lesdeprecationsenregistrées sur ce qu’elle a atteint — dans son lockfile et dans l’enregistrement de confiance des plugins à côté de celui-ci, de sorte qu’un plugin retiré attaché dans un rôle de verdict est nommé comme l’est une référence épinglée retirée.releaseest un chemin relatif à la racine du workspace qui nomme une Release qui s’y trouve, la même valeur que celle qu’accepteaggrega/irGraph, refusée sous les mêmes formes, et elle exige un lockfile pour la même raison. Rien n’est rendu. Ses entrées ne nomment aucunesource: elles disent de quoi dépend la Release, et non ce qu’une exécution a fait, ce que signaleaggrega/resolveDependencies. Voir Une fermeture n’est pas le graphe, car un client qui reçoit déjà le graphe ne dispose pas de ceci.aggrega/attachCandidates— les Features qui peuvent s’attacher à un nœud : celles dont l’applicabilité déclarée est satisfaite par les labels du nœud. Envoyez exactement une coordonnée.nodenomme un document du workspace par sonmetadata.name;graphNodenomme un nœud du graphe compilé derelease, par l’identifiant sous lequel ce graphe l’indexe ;labelstransmet directement un ensemble de labels et ne nomme rien, pour un client qui en détient déjà un. La réponse répète la coordonnée pour laquelle elle a répondu — vide lorsqu’il n’y en avait aucune à répéter —, contientnodeLabels, les paires de labels par rapport auxquelles la correspondance a été évaluée,labelSource, qui indique de quel type d’ensemble de labels il s’agit, et chaque candidat sous la forme dukind, duname, du fichier source et de l’originqui l’adressent. Renvoyer les labels est ce qui rend la réponse vérifiable par elle-même : un client peut expliquer pourquoi une Feature a été proposée sans se forger sa propre idée des labels du nœud, ce qui est la manière dont la réponse d’un client et celle du compilateur divergent. Pour un nœud du graphe, les Features proposées sont celles qu’atteint la Release de ce nœud. À côté degraphNode,connectionnomme une connexion que tire le composant de ce nœud — sonsocketet sonalias—, et la réponse contient alors aussislots, chaque slot que déclare le socket de cette connexion avec les Features qui peuvent le remplir, ounoSlotReasonlà où aucun ne peut être rempli. Voir Ce que vous apprend une réponse sur les candidats à l’attachement.aggrega/connectionCandidates— ce à quoi l’entité nommée peut se connecter.nodeest lemetadata.named’une entité, la même coordonnée que celle qu’accepteaggrega/attachCandidatessous ce nom. Voir Ce que vous apprend une réponse sur les candidats à la connexion ci-dessous, car les deux moitiés de la réponse ne sont pas aussi complètes l’une que l’autre et la réponse indique laquelle est laquelle.aggrega/insertionPoint— l’endroit d’un document rédigé où doit se placer une nouvelle entrée sous un conteneur nommé, exprimé de sorte qu’un client l’applique sans analyser lui-même le document.filenomme un document que contient le workspace, relatif à la racine du workspace, absolu, ou sous la forme de son adressefile://; un document hors de la racine, tel qu’écrit ou via un lien menant hors de celle-ci — vers le fichier, ou vers un répertoire sur le chemin —, est refusé quelle que soit la graphie qui le nomme, et que vous en déteniez une copie ou non ;containerest le chemin structurel depuis la racine du document jusqu’au conteneur dans lequel va l’entrée, chaque élément étant une clé de mapping ou une position de séquence écrite en décimal. C’est vous qui fournissez ce chemin — le démon lit la structure propre du document et ne déduit jamais où quelque chose doit aller à partir de son nom. Voir Ce que vous apprend une réponse sur le point d’insertion, car la position seule ne suffit pas pour appliquer la modification.aggrega/attachmentContainer— le document auquel appartient l’attachement d’une Feature pour un nœud, et le conteneur qui s’y trouve.graphNodenomme un nœud du graphe compilé derelease, par l’identifiant sous lequel ce graphe l’indexe, et les deux sont obligatoires : l’identifiant d’un nœud est une clé du graphe d’une Release et ne signifie rien sans elle. La réponse contientnode,fileetcontainer— une liste de segments exactement sous la forme qu’accepteaggrega/insertionPoint, de sorte que la paire se compose sans rien à déduire entre les deux. Pour un attachement sur une connexion que tire le composant du nœud, ajoutezconnectionavec sonsocket, sonaliaset ledocument—aggregateourelease—, et la réponse nomme le conteneurfeaturespropre à cette connexion dans ce document. Voir Ce que vous apprend une réponse sur le conteneur d’attachement, carfilefait partie de la réponse plutôt que d’être quelque chose que vous connaissez déjà.aggrega/connectionAtPosition— l’entrée de la connexion dans laquelle tombe une position dans un Aggregate ou une Release, la réponse étant donnée dans les termes dans lesquels les deux requêtes ci-dessus acceptent une connexion.filenomme le document de la manière dontaggrega/insertionPointen nomme un, et il est lu d’abord à partir de ce que la session détient pour lui ;positionest l’endroit dans ce document, unelineet uncharactercomptés à partir de zéro dans l’encodage de la session ;releasenomme la Release dont le graphe compilé enregistre les connexions, et il est obligatoire aussi pour une position dans l’Aggregate, car un nœud du graphe et une connexion n’existent que sur un graphe compilé. La réponse contientgraphNodeetconnection— sonsocket, sonaliaset ledocumentdans lequel la position a été lue — à transmettre tels quels àaggrega/attachCandidatesetaggrega/attachmentContainer, ounoConnectionReasonlà où aucune connexion n’est écrite. Voir Ce que vous apprend une réponse sur la connexion à une position.aggrega/editDocument— applique une modification structurée et bornée à un document rédigé, en préservant chaque octet qu’elle ne touche pas. C’est l’autre moitié des deux méthodes de localisation ci-dessus : celles-ci indiquent où va une entrée et vous laissent la composer et l’appliquer, celle-ci en compose une et l’applique.editnomme laquelle des quatre —add-component,attach-feature,wire-edge,set-value—, et une valeur en dehors de celles-ci est refusée plutôt qu’interprétée ;nodeest le chemin structurel depuis la racine du document, une liste de segments exactement sous la forme qu’accepteaggrega/insertionPoint;nameest la clé sous laquelle l’entrée est écrite etvaluece qu’elle contient, dont le sens découle deedit;socketest lu pourwire-edgeet ignoré sinon.dryRunfait tout ce que fait la requête simple sauf écrire, en répondant avec le document modifié sous forme decontent, pour un client qui présente d’abord le résultat à l’auteur ; rien n’est créé dans ce mode etwrittenest vide.filenomme le document relativement à la racine du workspace ou par son chemin absolu, et un document hors de la racine — tel qu’écrit, ou via un lien menant hors de celle-ci, vers le fichier ou vers un répertoire sur le chemin — est refusé sans que rien ne soit lu ni écrit. Ceci écrit le document que vous nommez, à l’intérieur du workspace — il ne résout aucune dépendance, n’atteint aucun registre et ne touche pas au réseau, quel que soit le mode de livraison, et l’écriture est subordonnée à la validation du document composé par rapport au schéma de son propre kind. Voir Ce que vous apprend une réponse de modification de document, car le comportement par défaut est l’écriture et un refus laisse le fichier identique octet pour octet à ce qu’il était.aggrega/releaseCandidates— les documents Release du workspace nommé par la requête, sous forme de chemins absolus. Accepte le workspace et rien d’autre : l’ensemble est une propriété de cette racine du workspace. L’appartenance est décidée par le kind du document — lekind:du fichier estRelease— et non par le nom du fichier, de sorte qu’une Release nommée sans préfixe conventionnel est proposée, tandis qu’un fichier simplement nommé comme une Release ne l’est pas. C’est ce que le sélecteur « quelle Release ? » d’un éditeur doit lister, car c’est le même ensemble dans lequel choisit la cascade de la Release active décrite ci-dessous. La réponse contient aussilockfiles, qui associe chaque Release listée — indexée exactement par la chaîne sous laquellereleasesla liste — au chemin absolu de son lockfile ; il est toujours présent, et c’est un objet vide lorsque le workspace ne contient aucune Release. Elle contient égalementunreadLinkedDirs, qui nomme — relativement à la racine, là où se trouve le lien — chaque lien situé là où le listage lirait un répertoire et menant à un répertoire hors de la racine du workspace : aucun répertoire hors de la racine n’est parcouru, de sorte qu’une Release que votre éditeur affiche dans l’un d’eux n’est pas listée, et ce champ est ce qui permet à un sélecteur d’en expliquer la raison. Un lien vers un répertoire que la configuration de votre workspace liste souscatalog_dirsn’est pas nommé : la configuration l’a atteint, en tant que répertoire de catalogue plutôt qu’en tant qu’endroit où sont conservées des Releases. Il est toujours présent, et vide lorsqu’il n’existe aucun lien de ce type. À côté de lui,unreadLinkedFilesnomme de la même manière chaque lien dont le nom se termine par.yamlou.ymlet qui mène à un fichier hors de la racine du workspace : aucun fichier de ce type n’est lu, quoi qu’il contienne, de sorte qu’une Release atteinte uniquement par l’un de ces liens n’est pas listée, et l’étape de la cascade portant sur une Release unique ne la compte pas. L’exception est un fichier que la configuration de votre workspace nomme comme Release — en tant quebuild.authoring_releaseou en tant que clé deworkspace.releases, jugé d’après le fichier auquel mène le lien, de sorte que nommer le lien ou ce fichier revient au même —, qui est lu et listé à l’emplacement propre du lien, et non nommé, à condition qu’il déclare une Release ; un fichier qui déclare autre chose n’est pas listé, et son lien est nommé. Il est toujours présent, et vide lorsqu’il n’existe aucun lien de ce type. Lorsque le fichier de configuration propre du workspace, ou l’overlay géré par la CI à côté de lui, est lui-même un lien menant hors du workspace, ce fichier est nommé ici quelle que soit la manière dont la recherche le traite, et le listage est lu sans rien de configuré, de sorte qu’une Release que la configuration aurait nommée via un lien n’est pas listée ; voir Racine du workspace et Release active. Voir Où se trouve le lockfile d’une Release.aggrega/activeRelease— la Release vers laquelle pointe le workspace nommé par la requête, sous forme de chemin absolu dans un champrelease, pour un client qui décide de ce qu’il faut sélectionner par défaut. Accepte le workspace et rien d’autre. Le champ est toujours présent, et une valeur vide signifie que le workspace ne pointe vers aucune Release — une réponse réussie plutôt qu’une erreur, de sorte qu’un client qui l’actualise à chaque redémarrage du démon n’est pas contraint de traiter un workspace ordinaire comme un échec. Lorsque la valeur est vide, la réponse contient aussireason, un résumé d’une ligne de ce que la cascade a cherché, ettrace, le compte rendu étape par étape ; tous deux sont omis lorsqu’une Release a été résolue. Lorsqu’une Release a été résolue, la réponse contient à la placelockfile, le chemin absolu du lockfile de cette Release, qui est omis lorsqu’aucune ne l’a été. La Release qu’elle nomme n’est pas nécessairement l’une de celles que listeaggrega/releaseCandidates— un marqueur peut nommer une Release dans un répertoire que ce listage écarte, commevendor/, ou une Release nommée sans extension YAML —, c’est donc dans cette réponse qu’un client lit le lockfile de la Release par défaut. Voir Où se trouve le lockfile d’une Release. Demandez-la plutôt que de déduire la réponse de l’une des entrées de la cascade : une entrée que la cascade n’a finalement pas utilisée nomme une autre Release que celle qu’elle a choisie. La réponse est calculée au moment où vous la demandez, de sorte que la redemander après avoir écrit un marqueur, modifié la configuration ou ajouté un fichier de Release signale la nouvelle réponse plutôt que le workspace tel qu’il était au démarrage du démon.aggrega/setActiveRelease— enregistre une Release comme Release par défaut du workspace nommé par la requête, en écrivant le marqueur.aggrega/active-releasede ce workspace, et répond exactement comme répondaggrega/activeReleaseune fois le marqueur écrit. Accepte le workspace etrelease: un chemin relatif à la racine du workspace qui nomme une Release qui s’y trouve, soumis au même contrat que lereleasedeaggrega/irGraph— un chemin absolu, un chemin qui sort du workspace et une valeur vide sont refusés, de même qu’un chemin qui en sort via un lien, à moins que la configuration de votre workspace ne nomme cette Release. Le marqueur est une ligne qui nomme la Release relativement à la racine, la forme que lit la cascade décrite ci-dessous. Il est écrit à l’intérieur du workspace et nulle part ailleurs : lorsque.aggrega, ou le marqueur lui-même, est un lien menant hors du workspace — que l’endroit vers lequel il mène existe déjà ou non —, la requête est refusée avec l’erreur invalid-params, dont le message est la phrase propre à la condition précédée de son code court,E0320: …(fatal-halts.md §« A path the operation writes leads through a link out of the directory it must stay inside (Un chemin qu’écrit l’opération mène, via un lien, hors du répertoire dans lequel il doit rester) »), nommant le lien et l’endroit vers lequel il mène, et rien n’est écrit ; un lien qui reste à l’intérieur du workspace est suivi pour l’écriture. La réponse nomme ce sur quoi la cascade s’arrête plutôt que de reprendre ce que vous avez envoyé, et les deux diffèrent lorsquebuild.authoring_releasenomme une Release, puisque la configuration l’emporte sur le marqueur. Enregistrez une valeur par défaut de cette manière plutôt que d’écrire le fichier vous-même, afin que l’endroit où aboutit le marqueur soit jugé selon la règle à laquelle est soumis chaque fichier que le produit écrit dans le workspace — voir La frontière du workspace.aggrega/effectiveConfiguration— la configuration en vigueur pour le workspace nommé par la requête, et la couche d’où provient chaque paramètre. Accepte le workspace et rien d’autre : la réponse est une propriété de ce workspace.layersliste les fichiers de configuration et les surcharges d’environnement qui ont contribué, de la priorité la plus basse à la plus haute ;settingscontient chaque paramètre attribué sous la forme de son nom pointé, de sa valeur effective et de lasourcequi l’a déterminé. Unesources’écrit exactement comme l’entrée correspondante danslayers, de sorte que les deux se joignent directement. Voir Ce que couvre la réponse sur la configuration effective pour savoir quelle couche nomme unesourceet quelles sont les limites de ce que signifie une ligne.aggrega/configInit— initialise une configuration fonctionnelle en enregistrant un registre et sa politique de confiance pour les signatures, afin qu’une machine neuve puisse récupérer et vérifier des artefacts signés sans modifier de YAML à la main.registryest facultatif et une valeur absente initialise le hub officiel, la même valeur par défaut que celle deaggrega config init; lehostde la réponse nomme celui qui a été utilisé.globaletworkspacesont les surcharges de la cible d’écriture, et envoyer les deux est refusé. Il refuse d’écraser un fichier de configuration existant, en nommant le fichier — envoyezforcepour poursuivre malgré tout, ce qui fusionne l’entrée du registre dans ce qui existe déjà et préserve les autres paramètres.dryRunfait tout ce que fait la requête simple sauf écrire, en répondant avec la configuration initialisée sous forme decontent, pour un client qui présente le document à l’auteur avant qu’il soit enregistré ; rien n’est créé dans ce mode etwrittenvaut false. Le refus pour fichier existant s’applique aussi sousdryRun, envoyez doncforceen même temps pour recevoir en réponse la fusion que produirait une écriture écrasante. Dans un workspace hors ligne, seul le hub officiel peut être initialisé : cette requête n’accepte ni identités ni clé, de sorte que tout autre registre est refusé exactement comme le refuseaggrega/registryAdd, code court et phrase compris, et doit être ajouté via cette requête avec une politique fournie à la main. La réponse contienthost,scope,trustetwritten, ainsi queexisted, true lorsque le fichier de configuration existait déjà — l’entrée du registre y est alors fusionnée plutôt qu’un nouveau fichier créé — et absent lorsque le fichier est créé. Ceci écrit la configuration globale par défaut — voir Atteindre un registre et écrire.aggrega/configCapture— fige la configuration effective critique pour la build dans le fichier de configuration propre à ce workspace, afin que le workspace se construise de la même manière sans la configuration globale de la machine en dessous. N’accepte aucune cible d’écriture : le figement sert à rendre un workspace autonome, il écrit donc toujours le fichier de ce workspace.allPluginsélargit l’ensemble figé, des sockets qui déterminent la sortie rendue — les liaisons de provider et les attachements de gouvernance de transformation de labels — à chaque socket de plugin, en ajoutant les gates de gouvernance de verdict et de linter ainsi que le socket d’import. La réponse contientconfigFile,workspaceRoot,captured,socketsetcatalogDirs. Voir Ce que laisse une écriture de configuration, car la réponse nomme un document qui existe désormais et l’action suivante d’un client est de l’ouvrir.aggrega/skillsInstall— écrit la skill Aggrega intégrée à ce binaire dans le dossier de skills de chaque assistant que nomme la requête, la même installation que celle qu’effectueaggrega skills installdans un terminal.agentsliste les assistants par identifiant, les identifiants que rapporteaggrega/skillsList; un identifiant donné deux fois est installé une seule fois, et lorsque plusieurs des assistants nommés lisent un même dossier partagé, la skill y est écrite une seule fois. Une installation de projet l’exige. Une requête avecglobalqui n’en nomme aucun installe pour les assistants trouvés sur cette machine, comme le faitaggrega skills install --globalsans--agent— chacun de ceux dont le dossier de configuration se trouve dans le répertoire personnel, ou dont la commande se trouve dans lePATHde l’environnement du démon — et est refusée sans rien écrire lorsqu’aucun n’est trouvé ; rien n’est demandé de manière interactive, etinstallednomme les assistants pour lesquels elle a écrit. Sansglobal, la skill est placée dans le dossier de projet de chaque assistant à l’intérieur de l’espace de travail que nomme la requête, jamais dans le répertoire où le démon a été démarré ; avecglobal: true, elle est placée dans le dossier par utilisateur de chaque assistant sous le répertoire personnel que nomme l’environnement du démon (HOME, ouUSERPROFILEsous Windows). Chaque cible est vérifiée avant toute écriture, de sorte qu’un refus laisse chaque dossier tel qu’il était : un identifiant pour lequel aucun dossier de skills n’est connu est refusé en le nommant ainsi que les identifiants existants, et un fichier situé à une cible qui ne porte pas la ligne de commentaire que porte chaque copie écrite de la skill est refusé en nommant son chemin. Une copie portant cette ligne — écrite par une installation antérieure, ou prise dans le dépôt de skills publié — est remplacée, et c’est ainsi qu’unaggregaplus récent met la skill à sa propre version. Un dossier de projet atteint par un lien qui sort de l’espace de travail est refusé sans rien écrire, comme toute écriture que le démon effectue dans un espace de travail — voir La frontière de l’espace de travail. La réponse porteskill,installed— une entrée par dossier écrit, dans l’ordre où les assistants ont été nommés, chacune avec lesagentsqui le lisent, lefolderabsolu etreplaced— etscope. Avecglobal, ceci écrit des dossiers que lit chaque projet de la machine — voir Atteindre un registre, et écrire.aggrega/skillsList— les skills que fournit ce binaire et chaque assistant pour lequelaggrega/skillsInstallpeut les écrire, la liste qu’afficheaggrega skills list. Prend l’espace de travail et rien d’autre, et n’y lit rien.skillsporte lenameet ladescriptionde chaque skill ;agentsporte l’id, lenameet leprojectFolderde chaque assistant — relatif à la racine d’un projet, qui sur cette surface est l’espace de travail que nomme une requête — ainsi que leuserFolder, relatif au répertoire personnel, tous deux séparés par des barres obliques, triés par identifiant. Il n’écrit rien et n’atteint rien.aggrega/pluginAdd— recherche dans le registre configuré un plugin d’un type nommé et l’ajoute à la configuration.typeetquerysont tous deux obligatoires :typeest l’un deprovider,governance,linter,importeretcli, etqueryest comparé aux noms des plugins de ce type et doit se résoudre en exactement un, de sorte qu’une requête correspondant à plusieurs est refusée avec les candidats plutôt que résolue arbitrairement.capabilitynomme la capacité que sert une liaisonprovideret y est obligatoire ;rolenomme le rôle d’un attachementgovernance—label-transform,ir-verdictourender-verdict— et y est obligatoire ; chacun n’est lu que pour son propre type et refusé pour tout autre, car un champ qui ne ferait rien en silence donnerait l’impression d’avoir fonctionné.acceptCapabilitiesest obligatoire pourcliet confirme les capacités déclarées de ce plugin : la commande en terminal obtient cette décision en la demandant, et cette surface n’a personne à qui demander, c’est donc l’appelant qui l’obtient et l’envoie.globaletworkspacesont les surcharges de la cible d’écriture, et envoyer les deux est refusé.dryRunfait tout ce que fait la requête simple sauf écrire, en répondant avec la configuration résultante sous forme decontent; rien n’est créé ni modifié etwrittenvaut false. Le registre est tout de même interrogé et la version tout de même résolue, car l’identité dans ce contenu est l’identité qu’une écriture aurait épinglée.dryRunest refusé pour le typecli, plutôt qu’ignoré : ce qu’enregistre l’ajout d’une extension de commande est le digest du contenu des octets qu’il a vérifiés, un enregistrement que le compilateur maintient plutôt qu’un contenu que quelqu’un modifie, et l’ajout met ces octets en cache au fur et à mesure — il est donc écrit plutôt que renvoyé. La version est épinglée pour vous — la requête se résout en un plugin, et la version qu’elle nomme sous la forme<name>:<version>, ou à défaut la version publiée la plus élevée du plugin, est écrite dans l’entrée ; une version nommée qu’une rétractation à laquelle cet espace de travail fait confiance a retirée est épinglée malgré tout, et la réponse portewithdrawn: true. Ceci atteint un registre, et un ajout de typecliqui ne nomme aucune des deux portées écrit la configuration globale — voir Atteindre un registre et écrire. Voir Ce que vous apprend une modification de plugin.aggrega/pluginRemove— supprime l’entrée d’un plugin configuré afin qu’il ne participe plus.typeest le même ensemble que celui qu’accepte un ajout, etqueryidentifie l’entrée : le nom court du plugin, sa référence épinglée ou — pourprovider— la capacité que sert la liaison. Les deux sont obligatoires.globaletworkspacesont les mêmes surcharges de la cible d’écriture, refusées ensemble de la même manière. Une requête ne correspondant à aucune entrée est refusée plutôt que de recevoir pour réponse un succès sur une configuration inchangée, de sorte qu’on ne dit jamais à un appelant qu’un plugin a cessé de participer alors que ce n’est pas le cas, et qu’une faute de frappe ne supprime jamais un autre plugin. Il ne contacte aucun registre : une suppression opère sur le seul texte de la configuration. Une suppression de typecliqui ne nomme aucune des deux portées écrit la configuration globale — voir Atteindre un registre et écrire. Voir Ce que vous apprend une modification de plugin.aggrega/pluginSync— aligne les enregistrements gérés par la machine d’une entité Plugin sur son module : l’ensemble des fonctions hôtes dérivé des imports propres du module, et le miroir des commandes lu dans l’auto-description du module. Aucun des deux enregistrements n’est rédigé à la main, car tous deux ont leur source de vérité dans le module. Les deux champs sont obligatoires et aucun n’a de valeur par défaut — les enregistrements sont dérivés du module, de sorte qu’un alignement qui n’en nomme aucun n’a rien sur quoi s’aligner —, et tous deux sont des chemins relatifs à la racine du workspace, refusés lorsqu’ils sont absolus ou se résolvent hors de celle-ci, tels qu’écrits ou via un lien. Seuls ces deux blocs changent : chaque autre octet est conservé tel quel, commentaires, lignes vides et style de guillemets compris, et un fichier qui enregistre déjà ce qu’implique le module est laissé identique octet pour octet et signalé comme inchangé. Ceci écrit le fichier d’entité que vous nommez, à l’intérieur du workspace, et ne contacte aucun registre. Voir Ce que vous apprend une modification de plugin.aggrega/pluginGenCatalog— génère une entité Plugin par invité sélectionné, en fusionnant les champs de contrat dérivés de l’auto-description de l’invité avec un overlay par plugin rédigé à la main.fromEmbeddedetpluginsont les deux modes de sélection et un seul exactement s’applique : chaque invité que contient ce binaire, ou un module au chemin que vous indiquez ; indiquer les deux, ou aucun, est refusé plutôt que résolu.overlayest obligatoire, et c’est un répertoire d’overlays avecfromEmbeddedou un unique fichier d’overlay avecplugin— un overlay est associé à un invité par son identité lorsqu’il y en a plusieurs, et il n’y a rien à associer lorsqu’il n’y en a qu’un.outputDirest obligatoire dans les deux modes de livraison, etdryRunn’en dispense pas : une exécution à blanc change l’endroit où va le contenu, pas le fichier dont il est le contenu, de sorte que chaque document renvoyé indique toujours le chemin auquel il est destiné, et ce chemin est composé à partir de ce répertoire. Les trois chemins ne sont pas jugés de la même façon, et la distinction suit ce que la génération fait de chacun.pluginetoverlaysont lus, et ce sont tous deux des fichiers que vous avez sélectionnés — un module se retrouve dans le répertoire où sa chaîne d’outils le compile, et son overlay est rédigé à côté — de sorte que chacun peut être absolu et est lu là où il se trouve réellement.outputDirest écrit, il est donc relatif à la racine du workspace et refusé lorsqu’il est absolu ou se résout en dehors de celle-ci, tel qu’écrit ou via un lien — un répertoire pas encore créé sous un répertoire lié menant à l’extérieur est refusé comme ce répertoire l’est. Une nouvelle exécution sur des entrées inchangées produit des entités identiques octet pour octet. Ceci écrit les entités générées sousoutputDir, dans le workspace, sauf sidryRunles demande plutôt sous forme de contenu. Voir Ce que vous apprend une modification de plugin.aggrega/getSchema— le JSON Schema d’un type d’entité ou de contrat, lu dans la copie compilée dans le binaire en cours d’exécution.kindest le jeton de schéma en minuscules avec traits d’union —component,aggregate,release,recipe,ir,wasm-provider, etc. — et il est facultatif, car il sélectionne laquelle de deux questions vous posez. Si vous indiquez un type, la réponse contientkindetschema, le schéma sous forme de document JSON plutôt que de chaîne qui en contient un. Si vous n’en indiquez aucun, la réponse contient à la placekindsetentityKinds: les types que vous pouvez indiquer, selon deux largeurs.kindsest chaque jeton qu’on peut demander à ce binaire, dans l’ordre oùaggrega get-schema --listles affiche.entityKindsest l’ensemble plus restreint des types dont un auteur rédige un document, chaque entrée contenant le jetonkindà renvoyer, la valeurdocumentKindqui va dans le champkind:du document lui-même, etacceptedBy, qui indique si la validation d’une entité unique, la publication et l’inspection par nom acceptent un document de ce type. Consultez Quels types vous pouvez proposer à un auteur avant de construire un sélecteur à partir de l’un ou l’autre. La réponse de schéma et l’énumération ne sont jamais combinées, de sorte que la question à laquelle il a été répondu se lit dans la réponse. Un jeton auquel aucun schéma ne correspond est refusé avec l’ensemble valide complet dans le message, de sorte qu’une faute de frappe se corrige sans second appel. Il ne prend rien dans le workspace, ne contacte aucun registry et n’écrit rien, il répond donc dans un workspace qui ne contient rien du tout — c’est ce qui le rend utilisable pour relier l’association de schémas d’un éditeur au binaire que l’éditeur pilote réellement, plutôt qu’à une quelconque copie des schémas installée ailleurs.aggrega/scaffoldEntity— un document de départ pour un type d’entité : exactement les champs qu’exige le schéma de ce type, avec les valeurs fixesapiVersionetkindrenseignées et un espace réservé partout où une valeur est nécessaire.kindest obligatoire et c’est le jeton de schéma en minuscules avec traits d’union —component,aggregate,release,recipe,manifest,feature, etc. ;aggrega/getSchemasanskindindique les jetons que vous pouvez envoyer, et un jeton auquel aucun schéma ne correspond est refusé avec cet ensemble dans le message, de sorte qu’une faute de frappe se corrige sans second appel. Un client qui propose à l’auteur le choix d’un type litentityKindsde cette méthode, c’est-à-dire l’ensemble des types dont on peut rédiger un document.nameest facultatif et initialisemetadata.namepour les types dont le schéma en exige un. La réponse contientkindetskeleton. Voir Ce que vous fournit une réponse de scaffold, car la réponse est un document à écrire et non un document qui a été écrit. Le squelette est dérivé du même schéma que celui que renvoieaggrega/getSchema, de sorte que les deux répondent à partir d’une même source. Lorsqu’on lui envoieexampleau lieu dekind, la méthode écrit l’un des exemples exécutables de la documentation dans un nouveau répertoire de l’espace de travail, comme le faitaggrega scaffold --exampledans un terminal ; lorsqu’on lui envoielist: trueseul, elle répond avec tous les exemples existants et n’écrit rien. Les deux formes ont besoin de l’espace de travail, de sorte qu’une requête de l’une ou de l’autre le nomme dansworkspaceRootet qu’une requête qui n’en nomme aucun est refusée.dirnomme le nouveau répertoire relativement à la racine de l’espace de travail, et vaut par défaut le nom de l’exemple ; une valeur absolue, ou une valeur qui se résout hors de la racine — telle qu’écrite, ou par un lien — est refusée avant toute lecture, et un répertoire qui contient quoi que ce soit est refusé et laissé tel quel. La réponse à une liste porteexamples, chacun avec sonname, sonlevelet sonsummary; la réponse à une écriture porteexample,dir,files— chaque fichier écrit, relatif àdir—,next, les commandes que la page de l’exemple donne pour le construire, absent lorsqu’elle n’en donne aucune, etversion, la version de la documentation dans laquelle l’exemple a été lu. Des champs de deux formes envoyés ensemble —kindavecexample,listavecexampleoukind,nameavecexampleoulist, oudirsansexample— sont refusés avant toute lecture, dans les termes mêmes dans lesquels l’outil de l’assistant les refuse. Une écriture acquiert le paquet de documentation lorsque la machine n’en détient aucune copie qu’admet la vérification de signature propre à l’espace de travail, et écrit à l’intérieur de l’espace de travail — voir Atteindre un registre, et écrire.aggrega/import— transforme la description d’une source externe en brouillons de fichiers de rédaction Aggrega, la même conversion que celle qu’effectueaggrega importdans un terminal.sourceest obligatoire et indique le fichier ou le répertoire à convertir, soit sous forme de chemin absolu, soit relativement à la racine du workspace — une description exportée par un autre outil se trouve là où vous l’avez enregistrée, elle est donc lue là où elle se trouve réellement plutôt qu’uniquement dans le workspace. Un répertoire est lu commeaggrega importen lit un : limité à ceux de ses fichiers que sélectionnent les motifs de fichiers déclarés par l’importeur, à l’exclusion du dossier de sortie de build du workspacedist/, et cantonné à lui-même où qu’il se trouve, de sorte qu’aucun lien qu’il contient n’est suivi vers l’extérieur.outputDirest facultatif et indique le répertoire où vont les brouillons, et il ne suit pas ce contrat : on y écrit, c’est donc un chemin dans le workspace, et une valeur absolue, ou qui se résout hors de la racine — tel qu’écrit, ou via un lien, y compris un répertoire pas encore créé sous celui-ci — est refusée. Si vous l’omettez, les brouillons vont sous la racine du workspace, là oùaggrega importles écrit lorsqu’il n’indique aucune destination — y compris avecdryRun.formatindique explicitement le format de la source ; si vous l’omettez, le format est reconnu par les signatures que déclarent les importeurs — ceux du catalogue du workspace comme les importeurs de base du compilateur — et une source qu’aucun ne reconnaît, ou que reconnaissent des importeurs de plus d’un format, est refusée en demandantformatplutôt que devinée.targetindique une capability de provider, telle quecomposeouhelm— le mot auquel se lie lespec.capabilityd’une Recipe — et produit en brouillon, à côté des brouillons de l’importeur, le Manifest sur lequel la Release en brouillon se construit pour ce provider, exactement comme le faitaggrega import --target:manifest.yaml, qui associe chaque type de composant et chaque type de fonctionnalité dont les brouillons ont besoin — y compris les types d’un Aggregate du catalogue que compose celui en brouillon — à la Recipe ou à la recette de fonctionnalité de cette capability que le catalogue du workspace propose pour lui, par son nom qualifié par la capability et sans version : celle qui existe ou, parmi plusieurs, celle qui porte le nom du type. Lespec.manifestde la Release est défini sur celui-ci ; un type qui n’en a aucune, ou qui en a plusieurs dont aucune ne porte ce nom, reste non associé avec un constatwarnqui le nomme, et une association que l’importeur a lui-même produite est conservée là où le catalogue la propose pour ce type et cette capability, et abandonnée avec un constatwarndans le cas contraire. Untargetauquel aucune Recipe du catalogue ne se lie est refusé avant l’exécution de l’importeur, en le nommant ainsi que les capabilities auxquelles se lient les Recipes du catalogue, et rien n’est écrit ; si vous l’omettez, aucun Manifest n’est produit — sauf avecsync, qui produit le brouillon pour la cible que nomme l’enregistrement de l’importation précédente. Un importeur de base que la machine ne possède pas encore est récupéré par la première importation qui en a besoin — voir Ce que vous apprend une réponse d’importation.dryRunfait tout ce que fait la requête simple sauf écrire, et répond avec les brouillons sous forme de contenu, pour un client qui les présente d’abord à l’auteur ; rien n’est créé dans ce mode etwrittenest vide.syncmet à jour par rapport à la source ce qu’une importation précédente a produit dansoutputDir, en ne modifiant que ce que l’importation a écrit, comme le faitaggrega import --sync; sans lui, une requête dont les brouillons écraseraient un Aggregate déjà présent est refusée. La réponse contientformat,outputDir,written,files,drift,diagnostics,decisionsethalted. Voir Ce que vous apprend une réponse d’importation, car une source que l’importeur n’a pas pu convertir entièrement est une réponse réussie et non une erreur.aggrega/explainError— ce que le compilateur déclare sur la condition que nomme un code, et les entrées publiées qui enseignent la correction à apporter lors de la rédaction.codeest obligatoire et accepte l’un ou l’autre des identifiants d’une condition : le code court qu’un diagnostic porte dansshortCode, ou le code descriptif danscode. C’est le développement d’un code que portent déjà les diagnostics de ce canal, et c’est la même réponse que celle qu’afficheaggrega explaindans un terminal. La réponse contient toujours la condition —shortCode,codeetmessage— car cette partie est déclarée dans le binaire et ne nécessite aucun réseau ;entriescontient le guide pas à pas publié, etnoteindique pourquoi il manque, là où il manque. Ceci acquiert le paquet de documentation lorsque la machine n’en détient aucune copie qu’admette la vérification de signature propre au workspace — voir Atteindre un registry, et écrire. Voir Développer un code qu’un diagnostic portait.aggrega/invalidate— un signal d’invalidation du cache provenant de l’observateur de fichiers de l’éditeur.
Notifications :
$/cancelRequest— du client vers le serveur : arrête la requête en cours envoyée sous cet identifiant. Le daemon annule le travail de cette requête ; une opération constate l’annulation à sa prochaine frontière d’étape plutôt qu’instantanément, de sorte que le travail déjà engagé se poursuit un instant. Annuler un identifiant pour lequel rien n’est en cours est une opération sans effet et sans danger.$/progress— du serveur vers le client : ce que fait une opération longue pendant qu’elle le fait, sur le jeton sur lequel la requête a demandé à recevoir les comptes rendus. Envoyé uniquement pour une requête qui en portait un. Voir Suivre une opération longue.aggrega/shutdown— lance une vidange coopérative : les requêtes en cours se terminent, les nouvelles requêtes sont refusées, puis le daemon se termine.aggrega/publishDiagnostics— un ensemble de diagnostics poussé par le serveur (utilisé pour les avertissements de dérive du lockfile et pour l’état au démarrage). Chaque entrée porte unsourcequi nomme laquelle des couches de diagnostic du daemon l’a émise :aggregapour un constat sur les documents rédigés,aggrega-buildpour un avis émis par un build — chaque avis qu’il a émis, c’est-à-dire le même ensemble que celui qu’afficheaggrega build— etaggrega-lintpour un constat sur les conventions de publication, les mêmes constats que ceux qu’afficheaggrega lint. Le champ est toujours présent dans chaque entrée, de sorte qu’un client peut les regrouper plutôt que d’afficher une seule liste indifférenciée, et n’a jamais à distinguer une source absente de l’une des couches. Une trame n’est envoyée pour un fichier que lorsque son ensemble diffère de celui dont ce client a été informé en dernier, de sorte qu’une requête qui recalcule les mêmes constats n’envoie rien ; la première trame d’un fichier, et une trame qui vide l’ensemble d’un fichier, sont toutes deux des différences et sont toujours envoyées.
Demander au processus lui-même de s’arrêter atteint le daemon dans les mêmes conditions. Une interruption depuis un terminal, ou une demande d’arrêt d’un superviseur ou d’un runtime de conteneurs, lance la vidange que lance aggrega/shutdown : les requêtes en cours se terminent, les nouvelles requêtes sont refusées, puis le daemon se termine. Une seconde demande met fin au processus immédiatement. Un client qui lance le daemon peut l’arrêter de l’une ou l’autre façon, et celui qui l’arrête via le protocole comme celui qui lui envoie un signal obtiennent la même vidange.
Validation en direct
À chaque aggrega/validate, le daemon valide le tampon de l’éditeur par rapport au schéma du document et renvoie des diagnostics pointant vers la clé fautive — le même verdict qu’un build rendrait, sur un contenu non enregistré. Une requête qui n’envoie pas de content porte sur le fichier tel qu’il est sur le disque ; un content envoyé vide est un tampon vide, et non une demande portant sur le fichier. Un fichier envoyé sans son contenu doit être un fichier que contient le workspace et qui peut être lu — un fichier hors du workspace, un fichier atteint via un lien menant à l’extérieur ou un fichier absent est refusé avec le code invalid-params. Les entités de catalogue, les Aggregates, les Manifests et les Releases sont reconnus par leurs apiVersion et kind. Les deux documents qui ne portent pas un tel en-tête — la configuration du workspace .aggrega-config.yaml et le lockfile de la Release que nomme la requête — sont reconnus à la place par leur nom de fichier, de sorte qu’une clé parasite ou mal formée dans l’un ou l’autre est elle aussi soulignée en direct. Les fichiers qui ne sont pas des documents Aggrega — templates de charts Helm, fichiers Compose, manifestes Kubernetes et fichiers .lock d’autres écosystèmes tels que Cargo.lock ou flake.lock — ne reçoivent aucun diagnostic ; le daemon ne signale jamais rien sur les fichiers étrangers.
Un espace réservé encore dû est signalé à sa clé, avec ce qu’il accepte. Une entité de catalogue d’un type que aggrega validate vérifie comme entité unique est aussi lue pour les valeurs obligatoires qu’elle laisse sous forme de chaîne vide, selon la lecture qu’applique cette commande, de sorte que le daemon signale chaque espace réservé que la commande signale pour les mêmes octets. Chaque espace réservé est une entrée : son message indique que la clé est un espace réservé encore dû, son suggest indique ce qu’accepte la valeur, et son keyPath porte le chemin pointé de la clé. L’entrée remplace le constat propre au schéma pour cette valeur vide, et tout autre constat sur le document est signalé comme le signale la vérification du schéma. Un espace réservé que le schéma admet vide est également signalé, bien que la vérification du schéma ne signale rien à son sujet — capability et implements d’une Recipe ou d’une FeatureRecipe en brouillon sont ceux que vous rencontrerez. Là où la vérification du schéma refuse aussi le document, chaque entrée porte le code de cette vérification, E0215, et là où elle l’accepte, les entrées ne portent aucun code : les mêmes identifiants que ceux que porte le rapport de la commande pour ces octets. Une entrée est dessinée sur la clé qui contient la valeur vide, à la ligne où la commande la signale — même pour une clé dont le nom contient un point, comme le label component.aggrega.ai/type, où un constat que la vérification du schéma signale sur cette clé est dessiné sur la clé qui l’englobe — et keyPath nomme la clé en entier. Cela vaut que la requête nomme ou non une Release, car c’est une question à laquelle le document répond par lui-même, et un document qui doit encore une valeur n’est pas encore un document sur lequel on interroge les conventions de publication : cette couche est vidée pour lui, comme elle l’est pour un document dont le schéma refuse la forme.
Chaque requête nomme la Release qui la concerne, et le daemon n’en conserve aucune pour lui-même. Les vérifications sémantiques résolvent la fermeture des dépendances de cette Release et lisent le lockfile de cette Release pour ses épinglages — ou, pour une entité de catalogue, lisent les répertoires de catalogue avec lesquels cette Release se construit, comme le décrit le paragraphe suivant — de sorte que deux requêtes nommant deux Releases reçoivent chacune une réponse sur la Release qu’elle a nommée. Rien n’est conservé de l’une à l’autre : il n’y a pas de Release sélectionnée à changer, et changer la Release par rapport à laquelle vous validez revient à mettre une autre valeur dans la requête suivante, et non à demander au daemon d’oublier quoi que ce soit.
Une entité de catalogue nommée avec une Release est vérifiée comme entité unique, dans les termes de cette Release. Un file contenant un Component, une Feature, une Recipe, une FeatureRecipe ou un Plugin, envoyé avec une release, reçoit la vérification qu’exécute aggrega validate <path> --release <release>, sur le tampon non enregistré de l’éditeur : ses références — le Component qu’implémente une Recipe, une bibliothèque à laquelle se réfère un pilier — se résolvent via les répertoires de catalogue que la configuration du workspace attribue à cette Release, de sorte qu’un même fichier peut être propre dans les termes de la Release qui se construit avec lui et échouer dans les termes d’une Release dont les répertoires ne contiennent pas ce à quoi il se réfère. C’est le verdict que rendent la ligne de commande et l’outil validate d’aggrega mcp pour la même entité aux côtés de la même Release et, comme le leur, il ne parcourt aucune fermeture et ne lit aucun lockfile. Un constat bloquant est une entrée d’erreur dans les propres termes de la vérification et portant ses codes, dessinée sur la clé qu’il nomme dans l’entité et, s’il n’en nomme aucune, sur la clé kind: de l’entité, comme le décrit Ce que porte une entrée de diagnostic — sauf si un build signale déjà ce défaut sur le fichier, auquel cas l’entrée du build est le seul signalement ; un avis que la vérification émet en lisant le catalogue est une entrée d’avertissement placée avant lui ; une vérification propre sur des répertoires tous présents ne renvoie aucune entrée. Une assertion en échec — une assertion qui appelle fail, dans la Recipe ou dans le Component qu’elle implémente — n’est pas ici un constat bloquant mais une entrée d’avertissement, dans les termes de la vérification et portant ses codes, terminée par la phrase A Release must satisfy this assertion before a build of it can pass., et dessinée là où serait le constat bloquant : l’assertion d’une Recipe sur la clé propre à cette assertion sous assertions, celle d’un Component sur la clé kind: de la Recipe. Comme un constat bloquant, elle s’efface devant l’entrée d’un build qui signale le même défaut sur le fichier. La vérification construit l’entité autour d’espaces réservés et de valeurs par défaut du schéma plutôt que des valeurs que définit une Release, elle ne peut donc pas distinguer une assertion qui attend une Release d’une assertion défectueuse, et laisse le verdict à un build, qui signale la même assertion comme une erreur (une assertion en échec est un avertissement). Un répertoire que la configuration du workspace liste pour la Release et qui n’est pas un répertoire — rien n’y existe, par exemple — arrête la vérification : le fichier porte une seule entrée d’erreur au lieu du verdict de la vérification, le refus que chaque commande oppose à ce répertoire, qui nomme l’entrée, le fichier de configuration et la ligne qui la liste, ainsi que le paramètre (D’où sont lues les entités locales). Une release qui ne nomme aucun fichier, ou qui nomme un répertoire, reçoit une réponse sur le fichier avec la phrase par laquelle la ligne de commande la refuse, plutôt que d’être vérifiée dans les termes du workspace. Ce qu’un build d’une seule entité ne peut pas remplacer est jugé comme le juge la ligne de commande, et ce que la ligne de commande écarte ou ne vérifie pas ne produit ici aucune entrée — voir ce que la correction d’une entité unique ne vérifie pas et, pour une Recipe dont le template lit une valeur que seule une arête de la topologie ou un identifiant attaché fournit, la correction d’une entité unique. L’Aggregate propre à la Release, un Manifest, une Release et une bibliothèque ne sont pas vérifiés un par un, car la vérification d’entité unique n’accepte pas ces types ; ils conservent les vérifications de la fermeture décrites plus haut. Un tampon contenant du contenu Workload est lu comme du YAML qui n’est pas un document Aggrega, car ce contenu est écrit dans le champ workload: d’une Recipe ou d’une FeatureRecipe et y est vérifié, là où il se trouve ; la ligne de commande et l’outil validate, à qui l’on remet un fichier Workload par son chemin, en vérifient la forme isolément.
Nommer une Release est facultatif, et la réponse indique laquelle des deux choses vous avez demandée. Si vous en nommez une, vous obtenez tout ce qui précède. Si vous n’en nommez aucune, vous obtenez les vérifications auxquelles un document répond par lui-même — s’il s’analyse, si sa propre forme est admissible et, pour une entité de catalogue d’un type validé comme entité unique, quels espaces réservés il doit encore — sans qu’aucune Release ne soit résolue, aucune fermeture parcourue ni aucun lockfile lu ; la réponse contient alors checked: "document". Si vous nommez une Release, cette clé est absente, car cette réponse est le verdict complet de la méthode et n’a rien à nuancer.
Lisez la clé plutôt que de déduire à partir des diagnostics, car les deux réponses peuvent sembler identiques. Un document bien formé validé sans Release répond avec une liste de diagnostics vide, exactement comme un verdict complet sans défaut, de sorte que checked est la seule chose qui distingue « rien ne va mal » de « rien de ce qui nécessite une Release n’a été examiné ». Une conséquence découle de la même règle : un lockfile est reconnu par sa correspondance avec la Release que nomme la requête, de sorte qu’une requête qui n’en nomme aucune ne reconnaît aucun lockfile et ne signale rien sur un lockfile.
Un workspace qui ne contient aucune Release reçoit une réponse plutôt qu’un refus, et c’est ce qui y maintient le reste du daemon utilisable. La validation est ce qui alimente le cache d’analyse que lit toute autre opération sur les fichiers, de sorte qu’un dépôt ne contenant qu’un catalogue, un squelette à un seul Aggregate ou un répertoire de brouillon obtiennent quand même le survol, la complétion, l’accès à la définition, les références, les implémentations et les diagnostics en cache. Un refus les emporterait tous avec lui, précisément dans les workspaces où un client n’a aucune Release à nommer.
Ce que porte une entrée de diagnostic
Chaque entrée se positionne avec line et column, tous deux à base 1 dans l’encodage de position négocié lors de la poignée de main, et ajoute end_line et end_column lorsqu’elle couvre un jeton entier. message est le texte qu’un client affiche à l’utilisateur, severity le classe, et source nomme laquelle des couches du daemon l’a émise, comme décrit plus haut.
Les couches répondent à des questions différentes sur un même fichier, de sorte qu’une entrée de chacune peut se trouver sur la même ligne sans que l’une soit un doublon de l’autre : l’une dit que le déploiement n’est pas correct, une autre que l’entité n’est pas publiable. Un client qui les afficherait en une seule liste signalerait deux fois un même problème, et c’est la lecture de source qui les sépare.
L’emplacement d’une entrée dépend de ce dont elle traite, et non de la couche qui l’a émise. Un constat sur quelque chose qu’a écrit l’auteur est positionné sur la clé sous laquelle il l’a écrit, de sorte que l’éditeur le dessine là où la modification doit se faire. Un constat sur la forme de la topologie déployée nomme un composant et une clé de livraison plutôt qu’une ligne — ce sont des coordonnées dans la topologie déployée, et non dans le document — il est donc dessiné sur la clé kind: du document et nomme plutôt ses coordonnées dans le message. Les deux sortes atteignent la couche aggrega-build, car un build émet les deux. Un refus qu’un build a émis pendant le rendu atteint aussi cette couche, sur le document que désigne le refus lui-même — un Workload qui ne satisfait pas ses vérifications sur la clé workload de sa Recipe, l’assertion en échec d’une Recipe sur la clé propre à cette assertion, une entrée que la composition du graphe refuse sur la clé sous laquelle la Release ou l’Aggregate l’a écrite, et chaque constat d’un refus qui en réunit plusieurs sur son propre document et sa propre clé — et, lorsqu’il ne désigne aucun document, sur la clé kind: de l’Aggregate ; Un refus émis pendant le rendu le décrit. Un client place donc chaque entrée selon ses propres line et column et ne déduit jamais une position de la couche.
Un constat qui ne nomme aucune clé que contient le document est dessiné sur la clé qui nomme le document. Un constat que les propres vérifications d’un document émettent sur ce qu’il dit, le constat de la vérification d’entité unique, ainsi qu’un avis ou un refus émis par un build, sont chacun dessinés sur la clé qu’ils nomment ; lorsqu’ils n’en nomment aucune, ou une clé que le document ne contient pas, ils sont dessinés sur la clé kind: du document, ou sur son metadata.name lorsqu’il ne déclare aucun kind:, et en tête du fichier uniquement lorsque le document ne déclare ni l’un ni l’autre ou ne s’analyse pas. Un document s’ouvre souvent par un commentaire — chaque fichier de catalogue porte un en-tête de licence — et une entrée dessinée sur sa première ligne se trouverait sur ce commentaire et se lirait comme un défaut de celui-ci, alors que l’identité propre du document est une ligne qu’a écrite son auteur. Une entrée portant sur autre chose que ce que dit le document est placée en tête du fichier : une entrée Dependencies: sur les dépendances de la Release, une étape qui s’est arrêtée sans rien nommer dans le document, un lockfile qui a dérivé, une référence qu’un rendu a dû décliner, une Release qui ne s’est pas chargée — et il en va de même d’une entrée aggrega-lint dont la règle n’a calculé aucune ligne. Lorsqu’une position est indiquée plutôt que dessinée, un constat qui ne nomme aucune clé n’en a toujours aucune : la réponse d’erreur d’un refus qui ne nomme aucune clé porte uniquement le document dans son data.
Le document sur lequel une entrée est publiée découle de la même règle. Une validation qui nomme une Release répond pour l’Aggregate de cette Release, pour la Release elle-même, pour le document de chaque module qu’importe l’Aggregate et pour le Manifest que nomme la Release. Un constat positionné dans la Release — le refus d’une entrée que la Release écrit sur l’une des connexions d’un composant, du dimensionnement qu’elle donne à cette connexion, d’un attachement qu’elle y renseigne ou dimensionne, d’une connexion qu’elle câble, d’une Feature que seule la Release attache à un composant ou à une frontière, ou de l’infra qu’elle donne à un attachement — est publié lorsque le document de la Release est validé, sur la clé de la Release qui l’a écrit, et nullement sur l’Aggregate. Un constat positionné dans le document propre d’un module — le refus de ce que déclare l’un des composants du module, d’un socket que câblent ses attachements, de ses valeurs ou des valeurs sur ses propres connexions — est publié lorsque le document de ce module est validé, sur la clé qui l’y a écrit, et nullement sur l’Aggregate. Un constat sur la table de correspondance du Manifest — une entrée qui fait correspondre un type à une Recipe ou à une FeatureRecipe qui ne l’implémente pas, une entrée dont l’épinglage de version ne peut pas être analysé, ou un type mis en correspondance dont la chaîne extends ne peut pas être suivie — est publié lorsque ce Manifest est validé, sur la clé de l’entrée de correspondance qu’il concerne, et nullement sur l’Aggregate ; lorsque le texte ouvert du Manifest n’écrit pas cette entrée — une entrée dont il hérite par son propre extends, ou une entrée qu’une modification non enregistrée a supprimée —, le constat est publié sur la première ligne du Manifest. Tout autre constat qu’émet la validation de cette Release est publié sur l’Aggregate, notamment les constats au niveau des dépendances qui ne nomment aucun document de votre workspace — une référence ou un plugin retiré, un Component ou une Feature du catalogue dont la chaîne extends ne se résout pas ou dont le schéma est invalide, un plugin de gate auquel l’enregistrement de confiance ne correspond pas, une instance de composant qu’aucune correspondance ne résout, une Recipe ou une FeatureRecipe dont le provider ne peut pas effectuer le rendu d’un type d’entrée qu’elle déclare, et les avis de chevauchement des piliers de schéma et de restriction lors de l’extension. Ainsi, un constat sur ce qu’a écrit l’opérateur apparaît pendant que la Release est ouverte, un constat sur ce que déclare un module pendant que ce module est ouvert, et un constat sur une correspondance pendant que le Manifest est ouvert, quelle que soit l’étape du build qui l’a émis ; un éditeur qui valide chaque document ouvert par rapport à la Release affiche chacun d’eux à cet endroit. Une Release dont les dépendances ne peuvent pas du tout être résolues n’émet aucun de ces constats, et l’échec de leur résolution est une entrée unique en tête du document propre à la Release et de tout autre document validé par rapport à elle que le daemon reconnaît, comme le décrit Validation en direct, et ne vérifie pas comme entité unique — son Aggregate, son Manifest, une bibliothèque, une autre Release, la configuration du workspace — préfixée par Dependencies: et portant le propre compte rendu de la résolution sur ce qui l’a arrêtée. Sur le document propre à la Release, l’entrée est ce compte rendu et rien de plus. Sur tout autre document, elle indique d’abord que le document est vérifié par rapport à cette Release et nomme la Release comme une requête la nomme — Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved: suivi du compte rendu — car rien dans ce document n’indique par rapport à quelle Release il a été vérifié : un éditeur qui vérifie chaque document ouvert par rapport à l’unique Release sélectionnée place l’entrée sur des documents qui n’ont rien à voir avec cette Release, et c’est le nom qui vous indique que la sélection en est la cause. Un fichier que le daemon ne reconnaît pas ne porte aucune entrée de ce genre, quelle que soit la Release nommée avec lui.
Une réponse porte toutes les couches présentes sur le fichier, quel que soit le stade atteint par la validation. La réponse de aggrega/validate est l’état actuel complet du fichier : ce que cette validation a trouvé, les entrées aggrega-build qu’un build, un aperçu ou une requête de graphe a publiées sur le fichier, et ses constats sur les conventions de publication, chacun sous son propre source. Une validation qui s’arrête au tampon — un tampon qui ne s’analyse pas, ou un document dont le schéma refuse l’enveloppe — répond de la même façon : elle signale son propre constat et laisse en place chaque entrée de build sur le fichier, car elle n’a rien appris sur le build. Un client peut donc remplacer ce qu’il détient pour le fichier, couche par couche, à partir de n’importe quelle réponse.
Un défaut est signalé une seule fois. La validation propre d’un document et un build peuvent y trouver le même défaut : la vérification d’entité unique effectue le rendu d’une Recipe dont un build effectue aussi le rendu, la validation compose le graphe que compose un build, et une Release dont les dépendances ne se résolvent pas fait échouer les deux. Tant qu’un build signale un tel défaut sur un document, la validation de ce document ne le signale pas une seconde fois : une entrée aggrega qui nomme la même condition — le même code — que le refus d’un build sur le même document, placée sur la même plage ou sur aucune clé qui lui soit propre — dessinée là où est dessinée une entrée qui ne nomme aucune clé, ou en tête du fichier — est omise de chaque réponse et de chaque publication pour ce document, et le signalement du build reste seul. Le signalement du build est l’entrée du refus sur la couche aggrega-build ; ou, pour aggrega/build, aggrega/buildPreview ou aggrega/irGraph refusés avec 1004 parce qu’une dépendance ne se résout pas, cette réponse elle-même — que rien ne publie — sur le document que nomme son data.file, sinon son data.lockfile, sinon la Release que nomme la requête, la dernière réponse de ce genre pour une Release étant celle qui compte. La validation conserve ce qu’elle a trouvé : dès qu’aucun build ne signale plus le défaut — l’exécution suivante publie la couche sans lui, la réponse suivante de build, d’aperçu ou de graphe pour cette Release est autre chose, ou un client se connecte qui n’a reçu aucune telle réponse 1004 — l’entrée propre du document est de nouveau signalée, et lorsqu’aucun build n’a été exécuté, rien n’est omis. Une entrée aggrega placée sur une clé où ne se trouve aucun refus de build est conservée, même lorsqu’elle nomme la même condition, car il peut s’agir d’un second défaut de ce genre que le build n’a pas signalé.
code est un code stable, comparable par une machine, pour ce que signale l’entrée, de sorte qu’un client peut se brancher dessus sans comparer le texte du message. Une seule clé porte le code, quel que soit celui qui l’a attribué, et source vous indique de quelle sorte il s’agit, car les couches nomment les choses à partir de vocabulaires différents.
- Sur une entrée
aggrega— un constat sur les documents rédigés — le code est la chaîne sous laquelle la condition est enregistrée, écrite comme le paquet déclarant suivi de la règle en kebab-case. C’est la même valeur qu’un consommateur Go lit avecCodeOf, dont la forme et la surface comparable sont décrites dans la référence des sentinelles d’erreur. - Sur une entrée
aggrega-build— un avis émis par un build — le code est celui qu’a attribué l’endroit qui l’a émis, et cette couche porte des avis issus de deux vocabulaires différents, car un build émet des avis sur deux sortes de choses différentes. Un avis sur la forme de la topologie déployée porte un code de classe, tel queunsupported-field, attribué partout où il a été émis, qu’il s’agisse d’un plugin de rendu ou du rendu lui-même ; un code de classe nomme une classe d’avis plutôt qu’une condition enregistrée, il n’a donc pas de ligne dans la référence des sentinelles, et la référence des avertissements décrit la classeunsupported-fieldet l’option qui la fait taire. Un avis sur les documents rédigés — un nom à une modification près d’un nom déclaré, un paramètre que rien ne lit — porte la chaîne sous laquelle sa condition est enregistrée, sous la même forme qu’une entréeaggregaet avec une ligne dans la référence des sentinelles. Dans les deux cas, le code nomme ce qu’est le constat et non qui l’a trouvé, de sorte qu’une même classe vous parvient sous un seul code, quel que soit le nombre d’endroits qui l’émettent, et c’est la lecture du code plutôt que de la couche qui vous indique laquelle des deux sortes vous avez en main. Le refus sur lequel un build s’est arrêté pendant le rendu est la seule entrée ici qui ne soit pas un avis, et il porte de la même façon la chaîne sous laquelle sa condition est enregistrée. - Sur une entrée
aggrega-lint— un constat sur les conventions de publication — le code est l’identité du constat : l’identité de la règle qui l’a produit ou, pour un constat qui ne nomme aucune règle — ce qu’un linter à vous peut signaler sous un code qui lui est propre — ce code. C’est l’identifiant qu’afficheaggrega lintsur la ligne du constat, après le code court lorsqu’il y en a un, et la valeur que porteaggrega lint --output jsonpour ce même constat, en tant queruleId, ou en tant quecodepour un constat qui ne nomme aucune règle. Un constat conserve une seule identité d’une interface à l’autre, de sorte qu’un client qui regroupe ou supprime une règle dans l’éditeur regroupe et supprime la même règle dans le terminal. Chaque règle de l’ensemble de règles du linter de publication que déclare Aggrega est enregistrée comme condition sous cette identité, elle figure donc dans la table de toutes les conditions sous le code court qu’afficheaggrega linten tête de la ligne du même constat et queaggrega lint --output jsony porte en tant queshortCode. Une règle d’un linter à vous que Aggrega ne déclare pas ne nomme aucune condition enregistrée, pas plus qu’un constat qui ne nomme aucune règle, même lorsque son propre code reprend l’identité d’une règle que déclare Aggrega — aucun des deux n’y figure donc. Les règles sont décrites dans la référence deaggrega lint.
Quelle que soit la couche, la clé répond à une seule question — qu’est-ce que c’est, en des termes qu’une machine peut comparer — de sorte qu’une extension d’éditeur qui met en évidence, regroupe ou supprime une classe de constats s’appuie sur le code, et continue de fonctionner lorsque la formulation d’un message change.
Notez quel objet porte quoi : il s’agit ici d’une chaîne dans une entrée de diagnostic, distincte du code numérique d’une enveloppe d’erreur JSON-RPC décrite plus bas sous Codes d’erreur. Une réponse porte l’un ou l’autre, jamais les deux au même endroit.
La clé est omise lorsque rien de ce qui a produit l’entrée n’a attribué de code, et chaque sorte connaît ce cas. Un tampon qu’aucun analyseur YAML ne peut lire signale le texte propre à l’analyseur et aucun code, car aucune condition propre à Aggrega ne se tient derrière ; une étape qui signale un échec sans nommer de condition n’en a de même aucune à signaler ; et un avis auquel son émetteur n’a attribué aucun code arrive sans. Traitez donc code comme facultatif, de la même façon que end_line et end_column, et ne vous branchez dessus que lorsqu’il est présent. Un code est ce que signale un diagnostic et jamais ce qui en sélectionne un : aucune requête n’accepte de code, et en réécrire un dans votre propre code vous donne une chaîne plutôt qu’un moyen de comparer.
L’identifiant qu’un programme compare, et celui qu’une personne cite
Une condition porte deux identifiants, destinés à deux lecteurs différents. code est celui vu plus haut : qualifié et avec traits d’union, de sorte qu’un programme qui se branche dessus se lit comme ce qu’il signifie. shortCode est la lettre E suivie de quatre chiffres — E0164 — et c’est celui qu’une personne peut lire à voix haute, taper dans un champ de recherche ou coller dans un ticket. Les deux nomment la même condition et aucun n’est l’abréviation de l’autre.
Le choix de l’un ou de l’autre dépend de qui lit. Comparez sur code dans votre extension ; présentez shortCode à l’auteur. Une extension qui n’afficherait que code laisserait au lecteur un identifiant destiné à un programme, et une extension qui comparerait sur shortCode comparerait un nombre qui ne dit rien de la condition. C’est cette répartition qui explique que les deux circulent plutôt qu’un seul.
codeDescription est l’endroit où la condition est publiée, porté sous la forme { "href": … }, qui est la structure propre au protocole pour une référence à ouvrir afin d’en savoir plus sur un diagnostic. Un éditeur qui connaît le protocole en fait une option « en savoir plus » sans qu’on ait à lui apprendre quoi que ce soit sur Aggrega, et aucun client n’a besoin d’une copie des explications. L’adresse renvoie à la liste publiée de toutes les conditions, où l’entrée d’un shortCode nomme la condition et se poursuit par le guide pas à pas de la correction à apporter lors de la rédaction.
Le texte explicatif lui-même ne figure pas dans l’entrée, et c’est délibéré. Un diagnostic est émis à chaque modification, de sorte qu’une explication qui voyagerait avec chacun republierait les mêmes paragraphes à chaque frappe pour un lecteur qui les a généralement déjà lus. Un client qui veut le texte le demande une fois, avec aggrega/explainError plus bas ; un client qui peut suivre un lien n’a besoin ni de l’un ni de l’autre.
Les deux clés sont présentes exactement lorsque l’entrée nomme une condition enregistrée, et absentes ensemble sinon. Ce qui en décide est ce qui se tient derrière l’entrée plutôt que la couche qui l’a publiée, lisez donc les clés plutôt que la couche :
- Une entrée qui nomme une condition enregistrée porte les trois.
shortCodese résout, et la référence renvoie à la liste dans laquelle il se résout. - Une entrée dont le code nomme une classe porte uniquement
code. La classe d’un avis de rendu, et l’identité d’un constat de conventions issu d’un linter à vous — une règle que Aggrega ne déclare pas, ou le code que porte un constat qui ne nomme aucune règle — sont de véritables identifiants sur lesquels vous pouvez regrouper et supprimer, et aucun des deux n’est une condition enregistrée — il n’y a donc aucun numéro à citer ni rien à l’adresse qui les décrive. Une référence envoyée malgré tout serait un lien ouvrant une page sans rapport avec le problème du lecteur, c’est pourquoi aucune n’est envoyée. C’est la forme ordinaire sur la coucheaggrega-build, bien qu’un avis de build qui nomme bien une condition enregistrée porte les trois comme n’importe quelle autre. Sur la coucheaggrega-lint, la forme ordinaire est l’ensemble complet : une règle de l’ensemble de règles du linter de publication que déclare Aggrega est une condition enregistrée, son constat porte donc le mêmeshortCodeque celui qu’afficheaggrega linten tête de la ligne du constat, et la référence à côté. - Une entrée qui ne nomme rien ne porte aucun identifiant.
Les trois cas se distinguent donc par les seules clés : pas de code signifie qu’il n’y a rien à nommer, un code sans shortCode à côté signifie un identifiant qui ne se résout pas plus loin, et l’ensemble complet signifie un identifiant avec un endroit où se renseigner. Traitez les deux nouvelles clés comme facultatives, de la même façon que code, et ne proposez au lecteur quelque chose à ouvrir que là où codeDescription est arrivé.
Développer un code qu’un diagnostic portait
aggrega/explainError transforme l’un ou l’autre des identifiants d’une condition en ce que le compilateur déclare à son sujet et en les entrées publiées qui enseignent la correction à apporter lors de la rédaction. C’est le même développement que celui qu’effectue aggrega explain dans un terminal et l’outil explain-error pour un assistant, et tous trois répondent à partir d’un même endroit, de sorte qu’un code développé ici et le même code développé ailleurs donnent une seule réponse plutôt que trois qui se trouvent concorder.
code est obligatoire et accepte l’un ou l’autre des identifiants — le shortCode qu’un diagnostic portait, ou le code à côté — car un client qui détient l’un d’eux n’a aucun moyen d’obtenir l’autre sans le demander. Une valeur vide est refusée en indiquant quoi envoyer.
La réponse porte toujours shortCode, code et message : les deux identifiants de la condition et la phrase par laquelle s’ouvre chaque diagnostic qui la nomme. Ceux-ci sont déclarés dans le binaire, ils arrivent donc sans réseau ni cache, et c’est ce qui permet de répondre même à un workspace qui ne contient aucune documentation. reference est la même adresse que celle que porte le codeDescription d’un diagnostic, pour un client qui préfère renvoyer son lecteur vers la documentation plutôt que d’afficher le texte.
entries porte le guide pas à pas publié, chaque entrée sous la forme du heading qui l’ouvre et du body qui suit, dans l’ordre où la documentation elle-même les associe à la condition. Il est omis lorsque le guide n’a pas pu être ajouté, et note indique alors pourquoi : la page publiée ne documente encore aucune entrée pour cette condition, ou ce workspace ne peut pas lire la documentation — la machine n’en détient aucune copie, ou seulement une que refuse la vérification de signature du workspace. Dans les deux cas, la condition au-dessus reste valable — la réponse n’est pas un échec, et un client affiche ce qui est arrivé avec la note à côté. entries et note n’arrivent jamais ensemble.
Un code que rien ne résout est refusé plutôt que de recevoir pour réponse une condition dont tous les champs sont vides, et chaque refus indique de quel cas il s’agit : un code sous lequel aucune condition n’est enregistrée, un numéro qui a nommé une condition autrefois et n’en nomme jamais une autre, ou un code que ce binaire ne déclare pas alors que la liste publiée n’a pas pu être lue du tout — ce dernier cas laisse les deux corrections ouvertes, car une liste publiée pour une autre version peut nommer une condition que ce binaire ne déclare pas.
La documentation est lue dans le paquet mis en cache pour le workspace que nomme la requête, acquis à la première utilisation lorsqu’il est absent, ce qui est la seule chose pour laquelle cette requête atteint un registry — voir Atteindre un registry, et écrire. Rien n’est écrit dans le workspace. Aucune validation ne le déclenche : un développement a lieu parce qu’une requête l’a demandé, de sorte qu’un registry n’est jamais atteint pendant qu’un document est validé ou inspecté.
Conventions de publication, à la demande et à chaque modification
Le daemon répond à deux questions différentes sur une entité du catalogue, et ce sont les questions auxquelles aggrega validate et aggrega lint répondent dans le terminal : le déploiement est-il correct, et l’entité est-elle publiable selon les conventions du catalogue. Une validation répond toujours à la première. Elle ne répond à la seconde que si vous la demandez.
aggrega/lint la demande explicitement. Envoyez entity pour une seule entité du catalogue, release pour chaque entité qu’atteint la fermeture de dépendances de cette Release, ou ni l’un ni l’autre pour vérifier chaque entité des répertoires de catalogue configurés : ce sont les trois portées de la commande. Envoyer à la fois entity et release désigne deux sujets différents et est refusé. La réponse contient checked, le nombre de documents d’entité couverts par l’exécution, et files, les résultats regroupés par le document qu’ils concernent et triés par chemin, les entrées de chaque fichier ayant la forme de diagnostic décrite plus haut. halted indique si le verdict propre de l’exécution refuse la publication.
N’envoyer ni l’un ni l’autre vérifie tout le catalogue, comme le fait aggrega lint sans argument. Un workspace dont la configuration ne donne aucun répertoire de catalogue de Release qui lui soit propre est vérifié une fois, sur ses propres répertoires, et la réponse est celle décrite plus haut. Un workspace qui nomme des Releases sous workspace.releases est vérifié une fois pour chaque Release qu’il contient, sur les répertoires que lit cette Release, et jamais sur l’ensemble à la fois : ainsi, des variantes de catalogue conservées côte à côte, une par Release, sont chacune vérifiées dans les termes de la Release qui les lit. La réponse contient alors aussi passes, une entrée par passe : releases, les Releases pour lesquelles elle a été exécutée, chacune relative à la racine du workspace, les Releases qui lisent les mêmes répertoires partageant une entrée ; catalogDirs, les répertoires qu’elle a lus, écrits comme files écrit un chemin, et vide pour une Release qui n’en lit aucun, ce qui est signalé au lieu de faire échouer les autres ; et les décomptes et les files propres à cette passe, qui indiquent pour quelle Release un résultat a été trouvé. checked, les décomptes et files qui les entourent couvrent toutes les passes ensemble, de sorte qu’un client qui ne lit pas passes lit tout de même l’exécution entière. Une exécution dans laquelle aucune passe n’a de répertoire à lire est refusée au lieu de recevoir la réponse d’un catalogue sans défaut.
Définissez prePublish avec entity pour comparer cette entité à sa version publiée précédemment et classer par rapport à elle l’incrément de version proposé. C’est ici le seul mode qui atteint un registre, et il s’exécute parce que la requête l’a nommé : ce qui autorise une opération qui sort vers l’extérieur, c’est qu’un appelant l’a demandée. Il n’a de sens qu’avec entity, donc prePublish sans entité est refusé.
aggrega/lint ne publie rien dans la session. Il répond sur le sujet qui lui a été donné, et écrire ses résultats dans la liste des problèmes de l’éditeur remplacerait ce qu’une validation a publié pour des fichiers que la requête n’a jamais couverts. Rien n’est écrit sur le disque, quel que soit le mode.
serve.lint_on_validate exécute les mêmes règles à chaque validation, et il est désactivé tant que vous ne l’activez pas. Activez-le dans .aggrega-config.yaml, dans le workspace sur les entités duquel vous voulez l’avis :
serve: lint_on_validate: trueIl n’existe aucun flag pour cela, car la question à laquelle il répond porte sur le contenu propre d’un workspace, et la personne qui se pose cette question est celle qui rédige le workspace, et non celle qui a lancé le daemon. Lorsqu’il est activé, une validation d’une entité du catalogue publie aussi les résultats relatifs aux conventions sous la source aggrega-lint ; lorsqu’il est désactivé, ce qui est la valeur par défaut, une validation ne signale que les couches de correction et aucun résultat relatif aux conventions ne vous parvient. Une session d’éditeur ne dit rien de la publiabilité d’une entité tant que vous ne demandez pas cette couche.
Trois choses valent sur cette couche, quoi que dise la clé. Seul le mode qui lit le contenu local s’exécute, donc aucun registre n’est consulté, rien n’est récupéré et rien n’est écrit ; la comparaison avant publication s’obtient en envoyant aggrega/lint avec prePublish, jamais par une validation, car une vérification exécutée à chaque modification est précisément l’endroit où un registre ne doit pas être atteint. Les règles sont évaluées sur le tampon que portait la requête plutôt que sur le fichier sur le disque, de sorte qu’un nom que vous corrigez cesse d’être signalé avant que vous n’enregistriez. Et les résultats sont consultatifs : un document qui les suscite est tout de même validé, et sa Release est tout de même résolue et rendue ; cela ajoute donc une couche et jamais un refus.
La clé commande cette couche et rien d’autre. aggrega/lint répond à tout ce qu’on lui demande sous l’une ou l’autre valeur, car un appelant qui l’envoie a demandé la vérification par son nom.
Seuls les kinds publiés dans un catalogue sont vérifiés, car c’est sur eux que portent les conventions. Les documents qui ne sont pas du contenu de catalogue, dont un Aggregate et une Release, sont ignorés, de même que le YAML qui n’est pas du tout un document Aggrega. C’est ce qui maintient une session silencieuse sur les documents dans lesquels un auteur passe la plus grande partie de son temps.
Comment s’écrit un chemin signalé
Lorsqu’une réponse nomme un document que le daemon a localisé pour vous, une seule règle décide de la façon dont ce chemin s’écrit : relatif à la racine du workspace lorsque le document s’y trouve, et le chemin absolu sinon. Cela couvre le file d’une identité d’entité, le file d’une définition d’entité et le file qui sert de clé à chaque groupe dans une réponse de lint. Les deux écritures sont des chemins que vous pouvez ouvrir, la première par rapport à la racine que vous avez indiquée, la seconde telle quelle, et aucune n’est jamais laissée vide en raison de l’endroit où se trouve le document.
La seconde moitié de la règle est ce dont a besoin un répertoire de catalogue configuré. Un workspace peut pointer vers des répertoires de catalogue n’importe où sur la machine, et un document dans l’un d’eux est aussi réel qu’un document sous la racine. Le chemin absolu est ce qui le nomme, et c’est la même écriture que aggrega lint et un diagnostic bloquant affichent pour ce fichier dans un terminal : ainsi, un fichier porte un seul nom, quelle que soit la surface que vous avez interrogée. Ce qui ne vous sera pas donné, c’est un chemin qui remonte au-dessus de la racine, lequel nommerait des fichiers différents selon l’endroit d’où il serait lu.
L’écriture qui vous a été remise se lit dans la valeur : tout ce que votre plateforme lit comme un chemin absolu est la seconde forme, et tout le reste est relatif à la racine du workspace. Vous n’avez pas besoin de le tester pour ouvrir le fichier (joindre un chemin relatif à la racine et ouvrir un chemin absolu tel quel fonctionnent tous deux), mais un client qui regroupe par document du workspace peut distinguer les deux sans demander.
Ce que cette règle ne couvre pas. Un chemin que vous envoyez est régi par le contrat propre à cette requête, énoncé avec la requête plus haut et généralement plus strict : une destination est refusée à moins d’être relative à la racine du workspace et de se résoudre à l’intérieur, liens compris. La notification aggrega/publishDiagnostics porte son file en absolu dans tous les cas, à l’intérieur comme à l’extérieur de la racine, car cette valeur est l’identifiant que vous comparez à vos propres documents ouverts et non une coordonnée dans le workspace : votre éditeur la résout comme un chemin du système de fichiers. aggrega/releaseCandidates et aggrega/activeRelease nomment chaque Release et chaque lockfile par son chemin absolu, comme le disent leurs propres entrées plus haut. Et aggrega/irGraph porte le graphe compilé tel que le compilateur l’a enregistré, en ne retenant que les valeurs qu’un auteur a déclarées sensibles, de sorte que tout chemin enregistré à l’intérieur est celui que le compilateur a enregistré, sous la forme que fixe le contrat propre au graphe, et non un chemin que ce protocole a composé pour vous.
Quelles écritures accepte un paramètre que vous envoyez
C’est ce que nomme un chemin, et non la méthode qui le porte, qui décide des écritures qu’accepte ce paramètre. L’entrée propre à chaque requête plus haut énonce le contrat des paramètres qu’elle accepte ; ce qui suit est le contraste entre elles, et la raison pour laquelle il s’agit d’un contraste et non d’une incohérence à mémoriser méthode par méthode.
Un paramètre qui nomme un document que vous détenez déjà peut s’écrire de trois façons : relatif à la racine du workspace, absolu, ou sous la forme de l’adresse file:// qu’un client de language server envoie pour un document ouvert. Il s’agit du file ou de l’uri de aggrega/validate, aggrega/diagnostics, aggrega/invalidate, aggrega/hover, aggrega/completion, aggrega/resolve, aggrega/findReferences, aggrega/findImplementations, aggrega/insertionPoint et aggrega/connectionAtPosition. Les trois nomment un seul document et reçoivent la même réponse, car chacune est réduite à une écriture canonique unique à la frontière de la requête avant que quoi que ce soit ne la lise : ainsi, un document que vous avez validé sous son chemin est retrouvé sous son adresse, et inversement, et l’écriture que vous envoyez ne change rien à la réponse. Une adresse est lue comme le chemin qu’elle nomme, ses échappements en pourcentage décodés, lorsque son autorité est vide ou localhost ; une adresse qui nomme une autre machine est lue comme le partage réseau de cette machine sur un système qui y ouvre un document de cette façon, et ne nomme rien que le daemon puisse ouvrir ailleurs. Une adresse qui porte en outre une requête, un fragment, des identifiants ou un port ne nomme rien non plus que le daemon puisse ouvrir. Une valeur qui ne commence pas par file://, quelle que soit la casse de ses lettres, n’est jamais lue comme une adresse, et le refus « fichier non validé » nomme la valeur que vous avez envoyée, quelle qu’en soit l’écriture. Parmi elles, aggrega/insertionPoint et aggrega/connectionAtPosition sont les deux qui lisent le document sur le disque lorsque vous n’en détenez pas de copie, et elles ne répondent que pour un document à l’intérieur du workspace : un document hors de la racine (tel qu’écrit, ou par un lien qui en sort, vers le fichier ou vers un répertoire en chemin) est refusé quelle que soit celle des trois écritures qui le nomme, et un document à l’intérieur de la racine reçoit une réponse dans les trois. Les huit autres ne lisent rien sur le disque au chemin qu’elles nomment (aggrega/validate prend les octets du document dans content, et les autres répondent à partir de ce qui a été validé), donc elles répondent pour un document où que vous le déteniez, dans le workspace ou non, et aucun lien qu’elles nomment n’est suivi pour lire un fichier. Un paramètre qui nomme un document que vous avez sélectionné hors du workspace relève du même cas pour la même raison : le source de aggrega/import est lu là où il se trouve réellement, comme le dit sa propre entrée. Ce sont deux exceptions à la frontière du workspace par catégorie (un document que le client tient ouvert, et un fichier qu’une personne a choisi) et La frontière du workspace explique pourquoi chacune en est une.
Un paramètre par lequel le daemon doit localiser un document à l’intérieur du workspace accepte un chemin relatif au workspace et rien d’autre. release est celui à connaître (sur aggrega/irGraph, et sous le même contrat partout ailleurs où il apparaît) et une valeur absolue est refusée avec l’erreur invalid-params, qui énonce le contrat puis nomme le défaut précis. Les requêtes qui écrivent à l’intérieur du workspace soumettent leurs destinations à ce même contrat, comme le dit l’entrée propre à chacune. Chacun de ces chemins est ensuite jugé selon l’endroit où il mène, par une seule règle, que la requête le lise ou l’écrive (la définition de l’intérieur qu’énonce La frontière du workspace) et un chemin qui mène à l’extérieur est refusé avec l’erreur propre à cette requête, qui cite la valeur telle que vous l’avez envoyée, sans que rien ne soit lu ni écrit : un lien vers un fichier extérieur comme un lien vers un répertoire en chemin, ainsi qu’un chemin pas encore créé sous un répertoire lié qui mène à l’extérieur, lequel est refusé pour le lien au lieu d’être écrit, ou cherché à l’extérieur et signalé comme absent. Cela couvre chaque chemin qu’une requête nomme pour que le daemon le lise (release partout où il apparaît, l’entity de aggrega/lint, et entity, plugin, file et from des requêtes de publication), de sorte qu’une requête ne peut pas lire, à travers un lien, un fichier que les listings propres du workspace omettent, ainsi que chaque destination : les répertoires dans lesquels écrivent une génération, un import et une build, l’entité à côté de laquelle aggrega/pin écrit son verrou, le fichier d’entité et le module que aggrega/pluginSync lit et réécrit, et le document que modifie aggrega/editDocument. Une release qui nomme une Release que nomme la configuration de votre workspace est la seule exception, comme le dit l’entrée de aggrega/irGraph.
Les deux diffèrent parce que les défauts diffèrent. Un paramètre qui nomme un document que vous détenez déjà ne laisse qu’une question, à savoir quel document, de sorte que réduire votre écriture à l’écriture canonique ne perd rien, et qu’accepter chacune ne vous coûte rien non plus. Un paramètre qui sélectionne un document au sein du workspace n’est pas dans cette situation : dans les bibliothèques de chemins qu’un client a des chances d’utiliser, joindre une valeur absolue à une racine produit cette valeur absolue au lieu d’une erreur. Une valeur réparée en silence ferait donc lire au daemon (et signaler des résultats sur) un chemin que le workspace n’a jamais contenu, et l’on vous parlerait d’un fichier qui n’existe pas. Refuser est la réponse plutôt que réparer, car un daemon qui réparerait une telle valeur laisserait chaque client qui en envoie une croire que le contrat est facultatif.
Comment une entité est adressée
Chaque entité qu’une réponse nomme est adressée de la même façon : kind, name et file. Faites la jointure sur ces trois clés avec aggrega/catalogIndex pour tout ce que vous voulez afficher : c’est la surface qui porte l’ensemble descriptif complet d’une entité (apiVersion, description et labels), de sorte qu’une réponse qui n’a besoin que de nommer une entité signale les trois clés d’adressage et laisse la description à un seul endroit. Une recherche par nom telle que aggrega/entityDefinition répète les quelques champs descriptifs dont traite sa propre réponse ; l’index reste la surface avec laquelle faire la jointure lorsque vous voulez l’ensemble.
Lorsqu’une réponse peut nommer des entités provenant de plus d’un endroit, chaque identité porte origin à côté de ces trois clés. aggrega/catalogIndex et aggrega/attachCandidates le font toutes deux, car leurs entités proviennent des documents du workspace et des répertoires de catalogue configurés. Une réponse qui puise à un seul endroit ne signale que les trois clés et aucun origin, puisqu’une clé n’ayant qu’une valeur possible ne vous apprend rien : chaque entité que nomme une telle réponse est un document du workspace, et son file est un chemin relatif au workspace que vous pouvez ouvrir. Lisez donc origin là où il est présent plutôt que de l’exiger partout ; les trois clés sont ce sur quoi vous faites la jointure dans les deux cas.
origin appartient à une réponse qui liste des entités, où distinguer les populations est le problème du lecteur. Une réponse par nom telle que aggrega/entityDefinition n’en porte aucun : elle nomme l’unique entité vers laquelle le nom s’est résolu, il n’y a donc pas de populations à séparer. Sa propre puce plus haut indique quand son file est vide ; n’interprétez pas ce vide à travers les valeurs de origin ci-dessous, qui décrivent un listing.
origin indique d’où le daemon a lu l’entité, et c’est ce qui rend file lisible.
workspace— un document Aggrega sous la racine du workspace.fileest son chemin relatif à cette racine, c’est-à-dire un chemin que votre client peut ouvrir.catalog— une entité résolue à partir des répertoires de catalogue configurés.fileest vide dans ce listing, et lenameconstitue l’adresse entière. Il est vide parce que le listing signale ce que la recherche dans le catalogue a énuméré, à savoir une identité et non un document, de sorte que l’entrée n’a aucun chemin à signaler ; il ne s’agit pas d’un chemin retenu en raison de l’endroit où il se trouve. Demandez le même nom àaggrega/entityDefinitionlorsque vous voulez le document : cette requête résout l’entité et signale sonfileselon la règle ci-dessus, de sorte qu’un répertoire de catalogue hors de la racine du workspace y est nommé par son chemin absolu.nameest de toute façon la coordonnée qu’utilisent un Aggregate, une Recipe et la recherche dans le catalogue.
Lisez les deux ensemble plutôt que de tester file seul. Un file vide à lui seul ne pourrait pas vous dire si l’entité n’a pas de chemin dans le workspace ou si un chemin n’a simplement pas été signalé ; origin y répond directement.
Lorsqu’une Feature est accessible des deux façons (la racine du workspace est elle-même l’un des répertoires de catalogue configurés, ce qui est une disposition courante), elle est signalée une seule fois, en tant que document du workspace, car c’est la copie dont vous pouvez ouvrir le fichier.
Ce que vous apprend une réponse attach-candidate
aggrega/attachCandidates répond à une seule question (quelles Features cet ensemble de labels admet-il) et offre trois façons d’indiquer de quel ensemble de labels il s’agit. Envoyez exactement une coordonnée ; en envoyer deux, ou aucune, est refusé au lieu d’être classé.
{node} adresse un document du workspace par son metadata.name et n’a besoin de rien d’autre. La correspondance est évaluée par rapport aux labels que ce document déclare dans metadata.labels, et la réponse signale labelSource: "declared".
{graphNode, release} adresse un nœud d’un graphe compilé. graphNode est l’identifiant sous lequel le graphe range le nœud : le même identifiant que vous lisez dans aggrega/irGraph, y compris la forme qualifiée que porte un nœud fourni par un sous-agrégat. release est un chemin relatif à la racine du workspace qui nomme la Release dont il faut construire le graphe, la même valeur qu’accepte aggrega/irGraph. La correspondance est évaluée par rapport aux labels finalisés du nœud, et la réponse signale labelSource: "resolved".
{labels} porte l’ensemble de labels lui-même et n’adresse rien. C’est la forme sous-jacente aux deux autres : la correspondance est une fonction d’un ensemble de labels et des Features proposées, de sorte qu’un client qui détient déjà un ensemble de labels n’a rien à nommer et rien à attendre. Envoyez un objet JSON de paires de labels ; la réponse signale labelSource: "supplied" et un node vide, car cette requête n’en a adressé aucun. Un objet vide est une coordonnée (il interroge sur un nœud sans aucun label), tandis qu’omettre entièrement la clé, ou envoyer null, n’adresse rien et est refusé.
Les deux coordonnées par nom sont séparées parce que leurs espaces d’identifiants se chevauchent. Un identifiant de nœud du graphe et le metadata.name d’un document peuvent être la même chaîne tout en nommant des choses différentes, de sorte qu’un paramètre unique portant les deux serait ambigu, et un daemon qui devinerait l’espace que vous visez répondrait parfois avec assurance pour le mauvais sujet. Dire quelle question vous posez est ce qui lève l’ambiguïté.
labelSource vous indique jusqu’où porte la réponse, et les trois valeurs ne sont pas interchangeables. declared est une correspondance sur ce qu’un document dit de lui-même, c’est-à-dire ce qu’une lecture de la source peut voir. resolved est une correspondance sur les labels que le nœud finit réellement par porter, c’est-à-dire ce par rapport à quoi une build évalue l’applicabilité : une réponse resolved est donc une affirmation sur ce que déciderait une build, et une réponse declared ne l’est pas. supplied indique que le daemon n’a lu aucun label et a comparé ce que vous avez envoyé ; la solidité de cette réponse dépend entièrement de la provenance de votre ensemble de labels.
C’est pourquoi un client qui détient un graphe devrait envoyer {labels} plutôt qu’un nom. Les labels finalisés d’un nœud sont les labels du type de composant vers lequel il se résout, et non ceux d’un document qui partage par hasard son identifiant, et un attachment label-transform peut ensuite les compléter, les modifier ou les supprimer : les labels qui décident de l’applicabilité d’un nœud ne sont donc pas forcément ceux que déclare un document donné. Un client qui dessine un graphe dispose déjà de cet ensemble grâce à aggrega/irGraph ; le renvoyer aboutit à la même réponse que donne la coordonnée {graphNode, release}, sans reconstruire le graphe pour l’obtenir. Renvoyez un ensemble que le daemon a lui-même signalé (celui d’un nœud depuis aggrega/irGraph, celui d’une entité depuis aggrega/catalogIndex) et votre idée des labels d’un nœud ne peut pas s’écarter de celle du daemon, car l’ensemble n’a jamais quitté sa propre réponse. Si vous en assemblez un vous-même, vous posez une question hypothétique, à laquelle il est répondu honnêtement et qui n’est une affirmation sur aucun nœud que contient le workspace.
Les candidats proviennent du workspace et du catalogue. Un workspace qui conserve ses Features dans un catalogue plutôt que dans sa propre arborescence n’a aucune Feature locale, et ses candidats sont entièrement origin: "catalog". Pour un nœud du graphe, les deux sont lus dans les termes de la Release de ce nœud : les Features du catalogue sont celles que déclarent les répertoires de catalogue que la configuration du workspace attribue à cette Release, et les documents propres au workspace sont proposés à l’exception de ceux situés sous un répertoire de catalogue que seules d’autres Releases lisent. Un workspace qui conserve une variante d’une Feature par Release propose donc au graphe de chaque Release sa propre variante et jamais celle d’une autre, tandis qu’une Feature écrite à côté des catalogues, sous aucun répertoire de catalogue, est proposée pour chaque Release. {node} et {labels} ne nomment aucune Release ; ils puisent donc dans chaque document du workspace et dans les catalog_dirs propres au workspace. Une Feature qui ne déclare aucune applicabilité est candidate pour chaque nœud (une déclaration absente ne pose aucune exigence), tandis qu’une Feature dont la déclaration ne peut pas être lue n’est candidate pour aucun, car traiter un sélecteur illisible comme satisfait laisserait une faute de frappe élargir ce que vous proposez.
Un nom qui ne se résout pas est une erreur, et non une liste vide. Ces deux réponses signifient des choses différentes : un tableau candidates vide indique que ce nœud n’a rien qui puisse s’y attacher, et signaler ainsi un nom mal saisi présenterait une faute de frappe comme une réponse établie. Le refus nomme l’espace dans lequel il a cherché, pour que vous sachiez s’il faut chercher un document du workspace ou un nœud du graphe. {labels} ne présente pas ce risque (il n’y a aucun nom à mal saisir), de sorte qu’un ensemble de labels que rien n’admet revient sous forme de réponse réussie portant un tableau vide, et une requête que le daemon ne peut pas lire est tout de même refusée avant toute correspondance.
La coordonnée de nœud du graphe exige un lockfile ; les deux autres non. Construire un graphe signifie résoudre ce qu’atteint la Release ; cette voie refuse donc avec l’erreur de lockfile absent lorsqu’aucun n’a été généré, en nommant la commande à exécuter : la même précondition que celle de aggrega/irGraph, pour la même raison. Adresser un document du workspace ne construit aucun graphe, et fournir un ensemble de labels ne construit rien du tout ; les deux répondent donc sur un workspace que personne n’a encore préparé.
Elle signale et ne crée jamais. La méthode ne modifie rien, n’écrit rien et ne crée aucun attachment. Composer et appliquer une modification revient à l’éditeur, là où se trouvent le tampon et l’historique d’annulation.
Ce qu’elle résout dépend de la coordonnée, et les trois ne sont pas équivalentes. {node} ne résout rien et n’atteint ni registre ni réseau : les candidats proviennent du workspace et des répertoires de catalogue, tous deux déjà sur le disque. {labels} résout encore moins : il ne recherche rien, car il n’y a rien à rechercher. {graphNode, release} construit le graphe de la Release et résout donc la fermeture de dépendances de cette Release de la même façon que aggrega/irGraph : d’abord depuis les répertoires de catalogue locaux et le cache d’artefacts, puis depuis le registre configuré pour une entité qu’aucun des deux ne contient. Les trois répondent hors ligne pour un workspace dont les entités sont toutes locales ; seule la coordonnée de nœud du graphe peut aller chercher plus loin.
Interroger une connexion
Une connexion que trace un composant peut porter ses propres attachments, qui remplissent les slots que son socket déclare sur le Component consommateur : par exemple un identifiant que le composant présente à ce que la connexion atteint. Envoyez connection à côté de {graphNode, release} pour demander ce qui peut y aller : socket est le socket de dépendance par lequel la connexion est câblée et alias le nom qu’elle porte dans ce socket, tous deux exactement tels que l’auteur les a écrits. Une connexion n’existe que sur un graphe compilé ; connection à côté de node ou labels est donc refusé, de même qu’une connexion qui ne nomme aucun socket ou aucun alias, ou une connexion que le nœud ne trace pas.
La réponse est la réponse du nœud du graphe plus les slots de la connexion. candidates garde son sens (les Features qui peuvent s’attacher au nœud lui-même) et slots s’y ajoute, une entrée par slot que déclare le socket, dans l’ordre dans lequel le Component les déclare :
slot— le nom sous lequel un attachment qui le remplit est écrit dans lesfeaturesde la connexion.selector,required,inject,sensitiveetdescription— le slot exactement tel que le Component le déclare sur le socket, vide ou false là où il ne déclare rien.selectorest la contrainte par laquelle les candidats ont été restreints, de sorte que vous pouvez expliquer un candidat, ou son absence, à partir de la seule réponse.candidates— les Features qui peuvent remplir ce slot sur cette connexion. Une build soumet un tel attachment à deux règles, et les deux sont appliquées : l’applicabilité déclarée de la Feature par rapport aux labels finalisés du nœud, à laquelle est soumis chaque attachment que porte le nœud, et leselectordu slot par rapport aux propres labels de la Feature. Les candidats d’un slot font donc toujours partie de ceux du nœud, restreints par le sélecteur. Une Feature par rapport aux labels de laquelle le sélecteur ne peut pas être évalué n’est pas proposée, car une build la refuse au lieu de l’admettre.
Lorsqu’aucun slot ne peut être rempli, slots est une liste vide et noSlotReason indique pourquoi. Lisez la raison plutôt que de prendre une liste vide pour « aucune Feature ne correspond » : ce serait une réponse différente, et c’est la raison qui les distingue :
feature-created-connection— une Feature a tracé la connexion, depuis son propre bloc de dépendances. Un attachment n’est écrit que sur une connexion que trace un composant ou la Release ; rien ne va donc ici, quoi que déclare le socket.ad-hoc-socket— le socket est un socket que le Component ne déclare pas. L’auteur l’a nommé, ce qui est permis, et un socket non déclaré ne déclare aucun slot.no-slot-declared— le Component déclare le socket sans aucun slot.
noSlotReason est absent partout où un slot existe, et slots et noSlotReason sont tous deux absents de la réponse à une requête qui n’a nommé aucune connexion : ainsi, une requête qui ne nomme aucune connexion reçoit une réponse sans aucun de ces deux champs.
document est accepté et ne change rien ici. Les slots sont ceux du socket et les candidats ceux des Features, les mêmes quel que soit le document dans lequel un attachment est écrit ; l’endroit où il va est la réponse de aggrega/attachmentContainer. Une valeur autre que aggregate ou release est tout de même refusée, car une valeur acceptée puis ignorée apparaît à son expéditeur comme une valeur respectée.
Ce que vous apprend une réponse connection-candidate
aggrega/connectionCandidates répond à deux questions à la fois, et une seule d’entre elles a une réponse complète. Lire la réponse comme une seule liste filtrée conduit à se tromper sur l’autre.
Chaque socket signalé porte targets (les Components locaux au workspace dont les labels déclarés satisfont la contrainte de labels que ce socket déclare sur ce qui peut le satisfaire), ainsi que le selector à partir duquel ces cibles ont été calculées, le flag required que déclare le socket, et declaration. targets est toujours un tableau, vide plutôt qu’absent, de sorte qu’un socket que rien ne satisfait est tout de même signalé comme un socket que déclare l’entité.
La moitié des cibles est complète. L’ensemble est déterminé en évaluant la contrainte déclarée du socket par rapport aux labels déclarés d’un candidat, la même évaluation qu’effectue une build, de sorte que ce que vous proposez est ce que la même contrainte admet pendant une build. Un socket qui ne déclare aucune contrainte laisse ses cibles sans contrainte et signale chaque Component : c’est le sens que le langage de contraintes donne à un sélecteur vide, et non une erreur.
La moitié des sockets est ouverte, et declaration ainsi que adHocSocketsAccepted sont ce qui vous permet de le savoir. L’auteur d’un Aggregate est maître de sa topologie et peut câbler un socket que l’entité de catalogue du composant n’a jamais déclaré ; les sockets que déclare une entité sont donc un ensemble de départ utile et non l’ensemble des noms de socket autorisés. Présentez-les comme des suggestions, et non comme les seuls choix possibles : un sélecteur d’interface qui ne proposerait que les sockets déclarés dirait à l’auteur que sa liberté est plus restreinte qu’elle ne l’est.
declarationvautdeclaredlorsque l’entité adressée liste le socket dans sonusesSchema, etad-hoclorsqu’elle ne le fait pas. Ce sont les deux mêmes valeurs que porte une arête dans le graphe IR, de sorte qu’un seul vocabulaire répond à « d’où vient ce socket » partout où vous rencontrez la question.adHocSocketsAcceptedindique si la surface de l’entité adressée accepte un socket que sa propre déclaration ne liste pas. Ce n’est pas toujours vrai : la surface de dépendances d’un Component en accepte un, et la surface d’attachment d’une Feature non, car un attachment participe à la topologie que déclare la Feature attachée au lieu d’en rédiger une à lui. Un socket ad hoc sur une surface qui n’en accepte pas est signalé sans cibles, car aucune connexion passant par lui ne se construirait.
Nommer un socket dans la requête limite la réponse à ce seul socket, et c’est la seule façon d’interroger sur un socket que l’entité ne déclare pas : un socket non déclaré n’apparaît dans aucune déclaration à énumérer. Omettez-le pour obtenir chaque socket que déclare l’entité, dans l’ordre dans lequel ils sont rédigés.
Ce qu’elle signale est une correspondance sur les labels déclarés. Une build évalue la contrainte d’un socket par rapport aux labels finalisés du nœud situé à l’autre extrémité de l’arête, et ce sont les labels du type de composant vers lequel ce nœud se résout, après que tout attachment label-transform a joué son rôle, et pas nécessairement les labels du document que vous avez nommé. Une réponse positive ici n’est donc pas une promesse sur ce que décidera une build : c’est la même limite que porte aggrega/attachCandidates avec sa source de labels declared.
Elle signale et ne crée jamais. La méthode ne résout rien, n’atteint ni registre ni réseau, et n’écrit rien : elle ne crée aucune arête et ne propose aucun texte. Composer et appliquer la modification revient à l’éditeur, là où se trouvent le tampon et l’historique d’annulation.
Pour les identités d’entité dans targets (kind, name et file), faites la jointure avec aggrega/catalogIndex comme décrit dans Comment une entité est adressée. Les champs descriptifs y sont signalés et délibérément non répétés ici, de sorte que cette réponse ne porte pas de seconde copie susceptible de se désynchroniser. Les cibles sont des Components du workspace, donc chacune a un file que vous pouvez ouvrir et aucune ne porte d’origin : cette réponse puise à un seul endroit, et la jointure se fait sur les trois clés.
Ce que vous apprend une réponse attachment-container
aggrega/attachmentContainer se situe entre les requêtes de candidats ci-dessus et le point d’insertion ci-dessous. Celles-là disent ce qui peut s’attacher à un nœud ; celle-ci dit dans quel conteneur va un attachment pour ce nœud, et dans quel document ; la suivante dit où, dans les octets de ce document, va le texte.
Demandez le conteneur au lieu de le composer. L’identifiant d’un nœud et le chemin du sous-système qui l’englobe s’écrivent tous deux avec des points entre leurs parties, et un point est un caractère autorisé dans un nom que tape un auteur : depuis l’extérieur du document, il est donc impossible de distinguer un point structurel d’un point à l’intérieur d’un nom. Un client qui assemblerait le chemin lui-même produirait quelque chose qui se lit correctement et adresse une clé que personne n’a écrite, et la modification qui suivrait créerait cette clé au lieu d’être refusée. C’est le compilateur qui a composé les deux chemins, c’est donc lui qui les décompose.
Un identifiant de nœud ne porte aucune trace de son sous-système englobant. Un composant rédigé à l’intérieur de subsystems.billing.subsystems.payments est rangé dans le graphe sous ledger, exactement comme le serait un composant de premier niveau, de sorte que l’identifiant n’offre rien sur quoi un client puisse travailler, avec quelque soin qu’il le découpe.
La réponse comporte trois champs.
noderépète le nœud dont traite la réponse, de sorte qu’un client ayant plusieurs requêtes en cours associe chaque réponse à sa question sans tenir d’ordre lui-même.fileest le document dans lequel le nœud a été rédigé, relatif au workspace. Il fait partie de la réponse au lieu d’être quelque chose que vous savez déjà : un nœud fourni par un module importé a été rédigé dans le document propre à ce module sous le nom que le module lui a donné, de sorte que le fichier comme le dernier segment du conteneur diffèrent de tout ce que la requête a nommé.containerest le chemin structurel depuis la racine de ce document, sous forme de liste de segments :["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Chaque niveau d’un sous-système englobant se place de nouveau sous la clésubsystems, ce qui est la façon dont le document l’écrit. Un composant que l’auteur a écrit au premier niveau nomme à la place["spec", "components", "checkout", "features"], car la portée dans laquelle un tel composant est compilé n’est contenue dans aucun fichier.
C’est une liste de segments et jamais une chaîne jointe, et c’est tout l’intérêt de cette forme. Un chemin joint devrait être redécoupé par celui qui le reçoit, ce qui réintroduirait l’ambiguïté ci-dessus un appel plus tard. Passez la liste telle quelle à aggrega/insertionPoint comme son container.
Elle lit la structure et jamais le sens. La réponse est dérivée du document dans lequel le nœud a été rédigé, de la portée dans laquelle il se trouve et du nom que l’auteur a tapé. Rien n’est déduit du nom d’un composant, du type qu’il porte ni de ce que dit un label.
Elle signale et n’écrit jamais. La méthode ne modifie rien et n’écrit rien dans aucun document. Elle ne crée aucun attachment, ne compose aucun texte et n’applique aucune modification ; elle ne statue pas sur ce qui peut s’attacher, ce qui relève de aggrega/attachCandidates.
Une requête qui nomme un nœud que le graphe ne contient pas est refusée au lieu de recevoir une réponse. Les identifiants de nœud sont les clés propres du graphe (lisez-les dans le graphe que renvoie aggrega/irGraph) et un nœud fourni par un module importé porte un identifiant qualifié. Un nœud pour lequel le graphe n’enregistre aucun document est également refusé : l’endroit où va un attachment est un fait relatif à un document, donc un nœud sans document n’a pas de réponse plutôt qu’une réponse vide.
Elle exige un lockfile, pour la même raison que aggrega/irGraph : nommer le conteneur signifie construire le graphe de la Release, et un graphe construit à partir d’octets dont rien ne se porte garant serait signalé exactement comme un graphe vérifié.
Un attachment sur une connexion
Envoyez connection à côté de {graphNode, release} (avec son socket, son alias et son document) et la réponse nomme le conteneur features sur l’entrée propre à cette connexion au lieu de celle du nœud. document est ici obligatoire, car l’un comme l’autre document peut contenir un attachment sur une connexion que l’Aggregate a tracée : le développeur en écrit un sur l’entrée de la connexion dans l’Aggregate, l’opérateur sur l’entrée par arête de la Release qui lui correspond.
aggregatenomme l’entrée de la connexion dans le document dans lequel le nœud a été rédigé :["spec", "components", "gateway", "uses", "models", "gpt", "features"]pour un composant de premier niveau, chaque sous-système englobant étant écrit niveau par niveau comme ci-dessus. Une connexion que la Release a tracée n’a aucune entrée dans l’Aggregate ; elle y est donc refusée.releasenomme l’entrée par arête sous l’entrée propre de la Release pour le nœud (["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"]), que la Release écrive déjà ou non cette entrée par arête. Là où elle ne l’écrit pas,aggrega/insertionPointsignale dansmissingContainerKeysles clés qu’il reste à écrire.fileest alors le document de la Release. Une Release qui n’écrit aucune entrée pour le nœud est refusée : l’emplacement du nœud est à écrire par l’opérateur, et la réponse n’en décide pas.
Une connexion qu’une Feature a tracée est refusée dans l’un comme l’autre document, pour la raison qu’indique feature-created-connection ci-dessus. Le nœud, le socket et l’alias sont comparés exactement tels qu’ils sont écrits, et une connexion que le nœud ne trace pas est refusée au lieu de recevoir un chemin pour réponse. Toutes les autres propriétés ci-dessus restent inchangées : la réponse est une liste de segments, elle lit la structure et jamais le sens, et elle n’écrit rien.
Ce que vous apprend une réponse connection-at-position
aggrega/connectionAtPosition est l’étape qui précède les deux requêtes de connexion ci-dessus, pour un client qui détient un emplacement dans un document plutôt qu’un nœud sur un graphe : par exemple un curseur sur l’entrée d’une connexion. Elle répond à la question quelle connexion est écrite là, dans les coordonnées qu’acceptent ces requêtes, et s’arrête là.
La réponse est l’une de deux moitiés, jamais les deux.
graphNodeetconnection— le nœud dont le composant trace la connexion, par l’identifiant sous lequel le graphe compilé le range, et la connexion par sonsocketet sonalias,documentnommant le document dans lequel la position a été lue :aggregatepour l’Aggregate ou un module qu’il importe,releasepour la Release. PassezgraphNode, la mêmereleaseetconnectionàaggrega/attachCandidatespour les slots que déclare le socket de la connexion, et àaggrega/attachmentContainerpour savoir où va un attachment sur celle-ci ; le conteneur qu’il nomme se trouve à l’intérieur même de l’entrée où tombait la position.noConnectionReason— la raison pour laquelle aucune connexion n’est signalée. L’ensemble est fermé :no-connection-entry— la position ne se trouve sur aucune entrée dans laquelle un attachment est écrit. Une connexion écrite sous forme de liste de cibles (db: [store]) et une connexion que trace le propre bloc de dépendances d’une Feature ne portent pas de telle entrée ; une position sur l’une ou l’autre reçoit donc aussi cette réponse.feature-created-connection— la position se trouve sur l’entrée de la Release pour une connexion qu’une Feature a tracée, laquelle ne porte aucun attachment pour la raison qu’indique la réponse sur les slots ci-dessus. Une Release écrit une telle entrée là où le bloc de dépendances d’une Feature trace à travers un socket que le Component consommateur déclare aussi ; l’entrée se construit, qu’elle ne configure rien ou qu’elle définisse l’infrapar arête de la connexion.unknown-connection— la position se trouve sur une entrée que la Release écrit pour une connexion que le graphe compilé ne contient pas. Une Release qui se construit peut en contenir une : par exemple une entrée sous un alias que rien ne trace et qui ne configure rien (pas detarget, pas d’infra, pas defeatures), ou une entrée pour un composant qu’un commutateuractive:a désactivé, dont les connexions quittent la build avec lui.
Quelles entrées comptent. Dans l’Aggregate, chaque connexion que trace un composant, à son entrée sous l’alias de la connexion dans le document dans lequel le composant a été rédigé (pour un composant fourni par un module importé, le document propre à ce module). Dans la Release, chaque entrée par arête qu’elle écrit, que l’entrée trace sa connexion ou en configure une que l’Aggregate a tracée. L’emplacement de chaque entrée est ce qu’enregistre le graphe compilé, de sorte que le fait qu’une clé soit une connexion n’est jamais déduit de son nom. Un composant qu’un commutateur active: a désactivé ne figure pas dans le graphe compilé ; ses propres entrées dans l’Aggregate répondent donc no-connection-entry, tandis que l’entrée de la Release pour l’une de ses connexions répond unknown-connection.
Une position n’importe où à l’intérieur d’une entrée est à l’intérieur de celle-ci. L’entrée s’étend de sa clé d’alias jusqu’à la dernière ligne indentée sous elle, de sorte qu’une position sur l’alias, sur son target ou à l’intérieur de ses features reçoit la réponse pour cette connexion, et que l’entrée la plus interne l’emporte là où des entrées s’imbriquent. Une position sur la clé propre d’un socket, au-dessus des alias écrits sous elle, n’est à l’intérieur d’aucun d’eux, que le socket contienne un alias ou plusieurs, et il en va de même d’une position dans l’indentation précédant une clé d’alias.
Quel document est lequel découle de la Release. Le fichier propre de la Release est lu pour les entrées qu’elle écrit ; tout autre fichier est lu pour les entrées dans lesquelles le graphe enregistre des composants comme rédigés. Un document dans lequel le graphe de la Release ne lit rien répond no-connection-entry à chaque position.
Elle signale et n’écrit jamais, et elle lit le document comme le fait aggrega/insertionPoint : d’abord depuis la copie de la session, sinon depuis le disque, à l’intérieur du workspace, avec les mêmes refus pour un document situé à l’extérieur, illisible ou qui n’est pas du YAML bien formé. Elle exige un lockfile, pour la raison pour laquelle aggrega/attachmentContainer en exige un, et construit le graphe sans rien rendre.
Ce que vous apprend une réponse sur le point d’insertion
aggrega/insertionPoint est le pendant des deux requêtes de candidats ci-dessus. Celles-ci disent ce qui peut s’attacher ou se connecter ; celle-ci dit où le texte correspondant se place dans un document précis. Elle répond et s’arrête là.
Vous nommez le conteneur ; le daemon le localise. container est un chemin structurel depuis la racine du document — ["spec", "components", "web", "features"] — et c’est votre déclaration de l’endroit où une entrée de ce genre se place dans un document de ce genre. Le daemon ne déduit pas ce chemin du nom d’une entité, du type qu’elle porte ni de ce qu’elle semble signifier. Il lit les octets écrits par l’auteur et indique quels segments du chemin ce document possède déjà, les colonnes où se trouvent ses entrées et la dernière ligne qu’atteint son bloc le plus interne. Savoir quelle clé reste donc l’affaire de l’appelant, et savoir où vont les entrées de cette clé dans ce fichier vient d’ici.
Pour l’attachement d’une Feature à un nœud d’un graphe compilé, l’appelant n’a pas à connaître cette clé par lui-même : demandez à aggrega/attachmentContainer le document et le conteneur, puis transmettez-les tous deux ici sans modification.
La réponse est une position de largeur nulle, plus ce que vous devez écrire autour. file est le document, relatif au workspace. container répète le chemin demandé, de sorte qu’un client ayant plusieurs requêtes en attente associe chaque réponse à sa question sans tenir d’ordre de son côté. position insère au lieu de remplacer : rien de ce qui figure déjà dans le document n’est écrasé ni décalé.
precededByLineBreak— commencez le texte que vous écrivez par un saut de ligne. La position se situe à la fin de la ligne que suit la nouvelle entrée, ce qui reste valide que le fichier se termine ou non par un saut de ligne et ne modifie aucun octet déjà écrit. Elle n’est false que pour un document qui ne contient rien après quoi se placer, auquel cas on écrit depuis le début du fichier.missingContainerKeys— les segments du chemin du conteneur que ce document ne contient pas encore, du plus externe au plus interne. Chacun doit être écrit comme une clé à part entière avant que l’entrée puisse aller dans le plus interne. Il est vide lorsque le chemin entier est déjà présent.entryIndent— la colonne à laquelle commence la première ligne de l’entrée elle-même, comptée en espaces depuis le début de la ligne.indentStep— de combien chaque niveau d’imbrication est indenté en plus.indentStepMeasured— indique si ce pas a été mesuré à partir de l’imbrication propre à ce document. Lorsqu’il est false, le document ne présente aucune imbrication à mesurer et le pas est une valeur de repli, de sorte qu’un client qui préfère imposer le sien sait qu’il est libre de le faire.entryShape—mappingousequence, déduit de ce que le conteneur contient déjà, etunknownlorsque le conteneur n’existe pas encore ou ne contient rien.unknownn’est pas un échec : le document n’a pas dit quelle forme prennent ses entrées, ce choix vous revient donc.
L’appliquer. Écrivez un saut de ligne là où precededByLineBreak est défini. Puis une ligne par entrée de missingContainerKeys, de la plus externe à la plus interne, chacune étant la clé suivie de deux-points — la première indentée à entryIndent moins indentStep fois le nombre de clés manquantes, et chaque suivante indentStep plus loin. Puis l’entrée elle-même, indentée à entryIndent. Lorsque missingContainerKeys est vide, l’entrée est la seule ligne que vous écrivez.
Lisez missingContainerKeys même lorsque vous vous attendez à ce que le conteneur existe. Une position appliquée sans les clés qui doivent la précéder produit un document qui ne s’analyse plus, et c’est le seul échec que cette réponse ne doit pas laisser lire comme absent.
position compte à partir de zéro, contrairement à celle d’un diagnostic. line et character sont tous deux en base 0, comme les valeurs de position de type LSP que ce protocole réutilise, tandis que line et column d’une entrée de diagnostic sont en base 1, comme décrit sous Ce que contient une entrée de diagnostic. Un client qui alimente une surface à partir de l’autre convertit entre les deux.
positionEncoding nomme les unités dans lesquelles character est mesuré, et c’est l’encodage négocié lors du handshake. Il est indiqué dans la réponse plutôt que laissé implicite, car une position dont l’appelant doit deviner les unités est une position qu’il ne peut pas appliquer : des décalages mesurés d’une façon et appliqués à un tampon mesuré d’une autre corrompent le document au premier caractère hors ASCII.
Une requête qui ne désigne pas un endroit où une entrée peut aller est refusée au lieu de recevoir une réponse. Chacun de ces cas est un état de la requête et non du workspace ; il revient donc avec le code invalid-params standard, et une nouvelle tentative ne change rien tant que file ou container ne change pas.
- Le document n’a pas été nommé, ne se trouve pas dans le workspace, n’a pas pu être lu ou n’est pas du YAML bien formé — un document sans structure n’a aucune position à indiquer.
- Le chemin du conteneur ne désigne rien : il n’a aucun segment, ou l’un de ses segments est vide.
- Le chemin traverse une valeur que le document contient sous forme de scalaire. Rien ne peut être ajouté à l’intérieur d’un scalaire, et le remplacer serait une réécriture plutôt qu’une insertion.
- Le chemin atteint une collection que l’auteur a écrite en style flow. Y ajouter une entrée réécrit des octets que l’auteur a déjà écrits au lieu d’ajouter une ligne, ce qui est une modification et non une position.
- Le chemin adresse une séquence en bloc avec quelque chose qui n’est pas l’un de ses indices. Les entrées d’une séquence s’adressent par position ; un nom n’y atteint donc rien et aucune entrée ne peut être créée pour porter ce nom.
Elle lit le tampon que l’éditeur détient, pas seulement le fichier sur disque. Le cache d’analyse du daemon est consulté en premier, de sorte qu’une position est indiquée par rapport au contenu non enregistré lorsqu’il y en a, et par rapport au fichier lui-même lorsque le cache ne contient rien pour lui.
Elle rend compte et n’écrit jamais. La méthode ne modifie rien, ne résout rien, n’atteint aucun registry ni le réseau, et n’écrit rien dans aucun document. Elle ne compose pas le texte d’une entrée et n’en applique aucune. Composer et appliquer la modification revient à l’éditeur, là où se trouvent le tampon et l’historique d’annulation.
Ce que vous apprend une réponse de modification de document
aggrega/editDocument est l’autre moitié de la paire ci-dessus : celles-là disent où une entrée doit aller et vous laissent la composer et l’appliquer ; celle-ci en compose et en applique une, et elle écrit. Les deux restent disponibles, car un client détenant un tampon non enregistré et un client modifiant ce qui est sur disque veulent des moitiés différentes — un éditeur doté de son propre historique d’annulation place le texte lui-même, tandis qu’un client qui préfère que le fichier soit modifié plutôt que de se voir dire où le modifier envoie celle-ci.
Un appel applique une modification, et l’ensemble des modifications est fermé. edit nomme laquelle : add-component ajoute une instance de composant sous un conteneur de composants, attach-feature attache une Feature à un nœud, wire-edge câble une connexion dans l’un des sockets de dépendance d’un nœud, et set-value définit une valeur sur un nœud. Il n’existe aucune modification qui supprime, remplace un bloc déjà écrit, réordonne quoi que ce soit ou écrit tels quels des octets que vous fournissez — ce n’est donc pas un outil d’écriture de fichiers sous un nom plus étroit, et une valeur en dehors des quatre est refusée plutôt qu’interprétée. Le refus liste ce que vous pouvez nommer.
Vous nommez le nœud sous forme de chemin structurel, exactement comme le prennent les deux requêtes ci-dessus. node est le fil d’Ariane depuis la racine du document — ["spec", "components", "web"] — et le conteneur dans lequel va l’entrée découle de edit. Pour add-component, le chemin nomme le conteneur de composants lui-même, car l’entrée ajoutée est le nœud. name est la clé sous laquelle l’entrée est écrite : le nom de l’instance, le nom de l’attachement, l’alias de la connexion ou la clé de la valeur. value est ce que porte cette entrée, et sa signification découle de edit — l’entité que l’entrée demande, le nœud vers lequel pointe une connexion ou le scalaire auquel une valeur est définie. socket est lu pour wire-edge et ignoré sinon.
Un chemin plutôt qu’un nom, pour la raison pour laquelle la requête de localisation en prend un : un nom devrait être recherché, et un nom apparaissant à deux niveaux laisserait le compilateur décider lequel vous vouliez dire. Ainsi, un client qui sait quel nœud il modifie le dit, et un client qui ne le sait pas sait qu’il a une question à résoudre avant de modifier quoi que ce soit.
Chaque octet que la modification ne touche pas est préservé. Le document n’est analysé que pour localiser le conteneur et la ligne où se termine son bloc ; l’entrée est rendue et insérée au niveau des lignes. Commentaires, lignes vides, style de guillemets, scalaires folded et literal, expressions de template et forme du saut de ligne final passent tous sans changement, et le pas d’imbrication est mesuré à partir de l’indentation propre au document plutôt qu’imposé — ainsi une entrée arrive dans le style dans lequel vous écrivez déjà. La même requête sur le même document produit les mêmes octets, de sorte qu’un client peut comparer deux exécutions et qu’une revue lit une modification comme un seul diff.
Le résultat doit être un document que vous auriez pu taper, et c’est de cela que dépend l’écriture. Le document composé est validé par rapport au schéma de son propre type et n’atteint le disque que si cette validation réussit. Une requête qui produirait quelque chose que le schéma de rédaction refuse revient sous la forme E0275 — the edit was refused because the resulting document would not be valid, and nothing was written (la modification a été refusée car le document résultant ne serait pas valide, et rien n’a été écrit) — avec la propriété que le schéma n’admettrait pas et son emplacement. Le fichier reste octet pour octet tel qu’il était, de sorte qu’une modification refusée ne se distingue pas d’une modification jamais tentée et que vous pouvez réessayer une requête corrigée sur le document de départ. C’est aussi pourquoi aucune règle n’est reformulée ici : demander à un document Release de porter une valeur de développeur est refusé par le même schéma qui refuserait le document tapé à la main.
Ce qui est admissible sémantiquement ne se décide pas ici. Savoir si un socket de dépendance est l’un de ceux que déclare le producteur, ou si l’applicabilité d’une Feature est satisfaite, relève de la résolution qu’effectue un build, chacune avec ses propres rapports. Vous pouvez donc nommer une connexion dont cette requête n’a jamais entendu parler, et un Aggregate peut rédiger un socket que son entité de catalogue ne pré-déclare pas ; ce qui peut être consommé à travers un socket reste au producteur de le déclarer. Exécutez aggrega/validate en nommant une Release, ou demandez le graphe, lorsque c’est la question.
La réponse nomme ce qui a été placé et ce qui a atteint le disque, et ce sont deux questions différentes. content porte le document produit par la modification sous les deux modes de livraison. written nomme le fichier qui a atteint le disque, et est vide sous dryRun. container est le chemin structurel du conteneur dans lequel l’entrée a été placée, de sorte que vous pouvez localiser ce que vous venez d’ajouter sans redéduire cette règle. createdContainers nomme les segments que cette modification a écrits parce que le document ne les contenait pas, du plus externe au plus interne — vide dans le cas ordinaire où le chemin entier était déjà là, et le lire permet de distinguer une entrée ajoutée dans un bloc existant d’une entrée qui a fait naître son propre bloc. file et edit renvoient ce que vous avez envoyé, de sorte qu’un client ayant plusieurs requêtes en attente associe chaque réponse à sa question. written, container et createdContainers sont toujours des tableaux, vides plutôt qu’absents.
Sous dryRun, rien n’est créé. written est vide, content porte le document qu’une écriture aurait produit, et le fichier n’est pas touché — ainsi un éditeur peut présenter le résultat à l’auteur pour qu’il l’enregistre, le modifie ou l’abandonne. Le comportement par défaut est l’écriture, car le produit de l’opération est un document modifié et une surface qui en produit un se doit de le livrer : une requête qui ne dit rien de la livraison modifie le fichier.
Tout ce que fait une écriture, une exécution à blanc le fait aussi. Le document composé est validé par rapport au schéma de son propre type dans les deux cas, de sorte qu’une modification qu’une écriture refuserait est refusée aussi sous dryRun, en nommant la même propriété — ce qui signifie que l’erreur que vous obtenez d’une exécution à blanc est l’erreur que l’écriture vous aurait donnée.
Une entrée déjà présente, qui porte ce que vous avez demandé, est une opération sans effet — le document revient inchangé et rien n’est écrit. Une entrée de ce nom portant autre chose est refusée plutôt que remplacée, car remplacer ce qu’un auteur a écrit ne fait pas partie des quatre modifications.
Après une écriture, le daemon relit le document. Ce qu’il détenait pour ce fichier est abandonné et sa vue au niveau du workspace est réinitialisée, de sorte que la prochaine requête de validation, de survol, de complétion ou de graphe reçoit une réponse fondée sur les octets produits par la modification plutôt que sur la version qu’elle a remplacée. La modification elle-même lit le fichier sur disque et non le tampon que vous détenez — contrairement à la requête de localisation ci-dessus, qui consulte d’abord le contenu non enregistré. C’est délibéré : écrire à partir d’un tampon non enregistré mettrait sur la page du contenu que l’auteur n’avait pas enregistré, sous couvert d’appliquer une seule entrée. Enregistrez le tampon, puis modifiez.
Une requête qui ne désigne pas un endroit où une entrée peut aller est refusée au lieu de recevoir une réponse, avec le code invalid-params standard, et une nouvelle tentative ne change rien tant que la requête ne change pas. Le document n’a pas été nommé, ne se trouve pas dans le workspace, n’a pas pu être lu, n’est pas du YAML bien formé ou ne déclare aucun type dont le schéma permettrait de vérifier le résultat ; edit n’a pas été nommé ou ne fait pas partie des quatre ; node ne désigne rien, ou l’un de ses segments est vide ; aucun name n’a été fourni ; wire-edge n’a nommé aucun socket ; set-value a reçu un mapping ou une séquence là où un scalaire est attendu ; le chemin du nœud atteint un scalaire ou une séquence, ou une collection écrite en style flow, là où ajouter une ligne réécrirait des octets déjà présents sur la page ; ou le chemin du nœud n’atteint rien dans le document.
Elle ne résout aucune dépendance, n’atteint aucun registry et ne touche pas au réseau, quel que soit le mode de livraison.
Ce que couvre la réponse sur la configuration effective
aggrega/effectiveConfiguration répond à deux questions : quelle configuration s’applique dans cette session, et quelle couche a décidé chaque paramètre. C’est la même réponse que celle qu’affiche aggrega config show --origin, calculée une seule fois et rapportée sur les deux surfaces, de sorte que les deux ne peuvent pas diverger sur l’origine d’un paramètre.
Une source prend l’une de quatre formes. Le chemin absolu d’un fichier de configuration — y compris le fichier global que lit un daemon démarré par aggrega --config <file> serve, nommé par le chemin qui lui a été donné ; une variable d’environnement derrière un préfixe env:, comme env:AGGREGA_SIGNING_REQUIRED ; un flag global saisi sur la ligne de commande qui a démarré le daemon, nommé comme le flag, comme --offline pour un daemon démarré par aggrega --offline serve ; ou (built-in defaults) pour un paramètre qu’aucune couche ne définit. Les trois premières apparaissent telles quelles dans layers. Les valeurs par défaut non, car les valeurs par défaut ne sont pas une couche qui a contribué — elles sont ce qui s’applique là où aucune couche ne s’est exprimée.
Un paramètre est attribué à la couche de plus haute priorité qui le définit, quelle que soit la valeur qu’elle écrit. Un fichier de configuration qui écrit la valeur par défaut intégrée, ou qui reprend une valeur qu’un fichier inférieur définit déjà, est le fichier nommé : c’est lui qui maintient la valeur en place. Un fichier définit un paramètre en portant sa clé, y compris le compagnon _append d’une liste, et une variable d’environnement en étant exportée avec une valeur non vide. Le fichier de configuration qui appartient à votre pipeline n’est jamais nommé pour une clé qu’il ignore. aggrega config show --origin rend compte selon la même règle.
Chaque paramètre que déclare le schéma de configuration est pris en compte, mais pas chacun avec sa propre ligne. Le compagnon additif _append d’une liste est rapporté sur la ligne de la liste à laquelle il ajoute, de sorte qu’une couche qui ne contribue que par le compagnon est nommée sur la ligne de cette liste et que le compagnon n’a pas de ligne. Un paramètre situé dans les entrées d’une liste — la politique de confiance d’un registry, les entrées d’un attachement de plugin — est couvert par la ligne de cette liste.
Deux limites supplémentaires, chacune rendant une réponse plus grossière qu’elle n’en a l’air.
- Un paramètre de type liste ou map est attribué dans son ensemble, à la couche de plus haute priorité qui le définit. L’attribution par entrée n’est pas suivie ; une liste assemblée à partir de deux couches ne rapporte donc que celle de plus haute priorité, et une entrée apportée par une couche inférieure ne se distingue pas d’une entrée écrite par la couche supérieure.
- L’exigence de signature est attribuée à la première couche qui l’a activée, et non à la dernière qui l’a mentionnée. Ce paramètre se compose de sorte que toute couche qui l’active l’emporte et qu’aucune couche ultérieure ne puisse le désactiver ; la première couche à l’activer est donc celle qui a fait de la valeur effective ce qu’elle est. Une couche qui écrit
required: falsen’active rien ; là où chaque couche qui le mentionne écritfalse, le paramètre rapporte donc(built-in defaults).
Chaque valeur rapportée est la résolution effectuée lorsque ce workspace a été nommé pour la première fois. Modifier un fichier de configuration ne change pas une valeur ici ; redémarrer le daemon, si. C’est délibéré — les valeurs sont la configuration sous laquelle toute autre requête concernant ce workspace reçoit sa réponse, ce qui les rend comparables avec la racine et la couche de configuration que le handshake a rapportées pour lui. Un client qui affiche la configuration à côté d’un fichier que l’utilisateur est en train de modifier devrait dire laquelle des deux il affiche.
L’attribution aux couches est établie au moment où vous la demandez, d’après les fichiers dans leur état actuel. Un fichier de configuration modifié après coup peut donc déplacer une source tandis que la valeur à côté reste telle qu’elle a été résolue. Les deux moitiés répondent à des questions différentes — ce qui est en vigueur, et quelle couche l’a décidé — et seule la première est figée. Redémarrez le daemon pour les remettre en phase.
Elle rend compte et n’écrit jamais. La méthode ne modifie aucune configuration, ne crée aucun fichier et ne résout rien depuis un registry ou le réseau.
Le contenu du fichier d’une seule couche n’est pas servi ici. La ligne de commande peut afficher tels quels les octets propres à une couche, commentaires et mise en forme préservés ; cette méthode rapporte la résolution plutôt que les octets. Un client qui veut le texte d’une couche a le chemin dans layers et peut l’ouvrir.
Ce que laisse derrière elle une écriture de configuration
aggrega/configInit et aggrega/configCapture produisent tous deux un document de configuration, et tous deux l’écrivent. La réponse nomme le fichier ; l’ouvrir est votre prochaine action, pas un substitut à l’écriture. Aucun des deux ne vous remet du contenu à placer vous-même à moins que vous ne le demandiez explicitement, car une capacité dont le produit est un document jamais écrit est une autre capacité portant le même nom.
Les deux diffèrent par leur portée, et chaque réponse dit laquelle. Lisez-la avant d’afficher le résultat.
- L’initialisation écrit, par défaut, la configuration partagée entre tous les workspaces de la machine. Un registry et les identités auxquelles vous faites confiance sur celui-ci sont généralement les mêmes partout où vous travaillez ; c’est donc là que va l’entrée, à moins que la requête n’envoie
workspace: true.scopeporte leconfigFilequi a été écrit etmachineWide, qui indique s’il s’agit du fichier partagé — déduit du fichier vers lequel l’écriture s’est résolue plutôt que de ce que la requête a demandé, de sorte qu’une réponse ne peut pas décrire une modification à l’échelle de la machine comme une modification locale. - Le gel ne va jamais au-delà du workspace. Il ne prend ni cible d’écriture ni substitution : tout son objet est de rendre un projet autonome, il écrit donc toujours le
.aggrega-config.yamlpropre à ce projet. C’est pourquoi sa réponse porteconfigFileetworkspaceRootet ne revendique aucun scope — il n’y a aucune portée à indiquer.
L’initialisation refuse plutôt que d’écraser. Un fichier de configuration qui existe déjà est laissé intact et le refus le nomme, car l’initialisation est destinée à une configuration qui n’existe pas encore, tandis que l’écriture partagée à laquelle elle délègue fusionne par conception. Envoyez force pour écrire malgré tout ; l’entrée du registry est fusionnée avec ce qui est déjà là et les autres paramètres sont préservés. Une requête refusée ne change absolument rien.
trust dit ce qu’a donné la politique publiée par le registry, sous forme d’issues distinctes plutôt que de prose. pinned signifie que le registry a publié une politique et qu’elle a été retenue, identities en comptant les identités. notAdvertised signifie que le registry a été interrogé et n’en a publié aucune, ce qui n’est pas un échec — l’initialisation se poursuit, et reason dit ce qu’a fait le point de terminaison. Un registry qui n’a pas pu être atteint est rapporté de la même façon, puisqu’aucune politique n’est revenue et que l’initialisation se poursuit de même, et porte unreachable à côté lorsque l’échec lui-même montre que le registry n’a jamais été atteint : son nom ne s’est pas résolu, une connexion vers lui a été refusée ou n’a pas pu être ouverte, ou une connexion sécurisée vers lui n’a pas pu être établie. Un registry qui a répondu — par un not-found ou par un statut d’erreur — ne porte jamais unreachable ; lisez donc cette clé plutôt que les mots de reason pour distinguer un registry qui ne publie aucune politique d’un registry qui n’a jamais été interrogé. baseline signifie que la baseline intégrée du hub officiel a été épinglée parce qu’aucune politique publiée n’a été retenue, reason indiquant pourquoi ; l’entrée porte une politique, il n’y a donc rien à épingler à la main. Les deux clés répondent à des questions différentes ; un hub qui a été interrogé et n’a rien publié porte donc les deux, et un hub dans un workspace hors ligne — jamais interrogé — ne porte que baseline, reason indiquant que le workspace est hors ligne. Tout autre registry qui ne publie rien ne porte que notAdvertised, est initialisé sans politique, et le conseil qui suit est d’épingler les identités à la main ; hors ligne, il est refusé au lieu de recevoir une réponse. skipped signifie qu’aucune récupération n’a été tentée. Un client qui traiterait comme une erreur tout ce qui n’est pas pinned signalerait comme défaillante une configuration qui fonctionne.
Sous dryRun, rien n’est créé. written est false, content porte le document qu’une écriture aurait produit, et le fichier auquel ce contenu est destiné est scope.configFile. Aucun répertoire n’est créé et aucun fichier n’est touché, de sorte qu’un éditeur peut présenter le texte à l’auteur et le laisser l’enregistrer, le modifier ou l’abandonner.
Une exécution à blanc ne diffère d’une écriture que sur un seul point — elle n’écrit pas — elle effectue donc tous les refus qu’effectue une écriture. Le refus pour fichier existant est celui qui compte ici : dryRun sur un fichier de configuration qui existe déjà est refusé, en nommant le fichier, exactement comme une écriture. C’est ce qui rend la réponse utilisable comme prédicat — si l’exécution à blanc refuse, l’écriture aurait refusé, pour la même raison et avec le même message. Envoyez force avec dryRun pour recevoir à la place la fusion que produirait une écriture avec écrasement, toujours sans rien écrire. Le registry est interrogé sur sa politique de confiance publiée quel que soit le mode de livraison, car la politique figurant dans ce contenu est la politique qu’une écriture aurait épinglée.
Ce que rapporte un gel est ce qu’il a écrit, et non une description de ce qu’il a écrit. sockets liste chaque socket de plugin qui a été gelé avec les attachements gelés à cet endroit ; catalogDirs porte les répertoires du catalogue. Les deux sont toujours des tableaux, vides plutôt qu’absents.
socketetfieldne sont pas la même chaîne, et la différence n’est pas cosmétique.socketnomme le socket auquel les attachements sont liés ;fieldest la clé sous laquelle ils ont été écrits dans le fichier. Ils ne diffèrent que pour le socket des providers, qui est écrit sous une clé au pluriel — utilisez doncfieldlorsque vous renvoyez un lecteur à une ligne du document, etsocketlorsque vous nommez le socket lui-même.- Chaque attachement porte
uri,capability,functionetrole, présents seulement là où l’attachement en a un. Ils nomment l’attachement plutôt que de le reproduire en entier : les entrées facultatives qu’un attachement reçoit au moment de l’attachement sont gelées telles quelles dans le fichier et ne sont pas répétées dans la réponse. Le fichier est la copie qui fait foi. captured: falseest un succès. Un projet dont la configuration ne participe pas à un build n’a rien de critique pour le build à geler ; le fichier reste donc tel quel et les deux listes reviennent vides. Traiter cela comme une erreur signale comme défaillant un workspace sain.
Par défaut, seul ce qui détermine les octets de sortie est gelé — les liaisons des providers, et les attachements de gouvernance qui transforment les labels. Les contrôles de verdict de la gouvernance et des linters ainsi que le socket d’import sont laissés de côté, car ils sont destinés à varier d’un environnement à l’autre et les geler transporterait les contrôles d’un environnement dans chaque checkout. allPlugins: true étend l’ensemble à chaque socket de plugin. L’appartenance se décide par attachement, et non par socket, de sorte qu’un socket de gouvernance portant un attachement de transformation de labels et un attachement de verdict n’apporte, par défaut, que le premier.
Chaque valeur est gelée à sa valeur effective — ce qui résulte de la fusion de la configuration de la machine et de celle du projet — de sorte qu’une liaison qui aujourd’hui ne vient que de la configuration de la machine est écrite dans le projet et voyage avec lui. Les paramètres d’outillage à l’échelle de la machine, dont la politique de confiance d’un registry, ne sont pas critiques pour le build et restent où ils sont. Geler deux fois une configuration inchangée réécrit les mêmes octets, de sorte qu’un client peut le proposer librement : un second appel laisse le document qu’un lecteur a ouvert exactement tel qu’il était.
Ce que vous apprend une modification de plugin
Les quatre requêtes de plugin écrivent toutes par défaut, et elles se répartissent selon ce qu’elles écrivent : deux modifient un fichier de configuration, et deux produisent des documents dans le workspace. Deux d’entre elles — l’ajout et la génération — acceptent dryRun, qui fait tout ce que fait la requête sauf écrire. Lisez ce que la réponse indique elle-même de l’endroit où la modification a abouti plutôt que de le déduire de la requête — pour l’une d’elles, une requête qui ne dit rien de la portée signifie la portée la plus large.
Un ajout et une suppression portent tous deux scope, déduit du fichier vers lequel l’écriture s’est résolue. configFile est ce fichier, machineWide indique s’il s’agit de celui par lequel se résout chaque workspace de cette machine, et workspaceRoot nomme le workspace sur lequel cette session a été ouverte, de sorte qu’une réponse de portée workspace dit de quel workspace il s’agissait. machineWide est déduit du fichier résolu plutôt que de ce que la requête a demandé, ce qui empêche une réponse de décrire une modification à l’échelle de la machine comme une modification locale.
🔴 Un ajout de type cli qui ne nomme ni global ni workspace enregistre la commande à l’échelle de la machine. Une extension de commande est un outillage à l’échelle de la machine ; sans substitution, elle est donc écrite dans le fichier de configuration global par lequel se résout chaque workspace de cette machine — et la commande qu’elle enregistre devient alors une commande aggrega de premier niveau pour chaque projet de cette machine, y compris des projets que personne dans cette session n’a nommés. Un ajout provider, governance, linter ou importer fonctionne à l’inverse : ceux-ci façonnent le build d’un seul projet ; sans substitution, ils vont donc dans le .aggrega-config.yaml propre à ce projet. Une suppression suit la même règle pour les mêmes types. Envoyez workspace: true pour garder une extension de commande locale, ou global: true pour envoyer l’un quelconque des autres dans le fichier partagé ; envoyer les deux est refusé. Le scope de la réponse est dans tous les cas la déclaration qui fait foi, et un client devrait l’afficher avant d’agir sur le résultat.
Un ajout nomme ce qui a été placé, et exactement l’un de trois champs dit de quel genre de chose il s’agissait. type renvoie le type pour lequel l’entrée a été ajoutée, puis : identity porte l’identité d’entité brute, épinglée à une version, pour un attachement governance, linter ou importer ; uri porte l’adresse d’artefact oci:// du plugin, accompagnée de la capability qu’il sert désormais, pour une liaison provider ; et reference porte la référence épinglée dont les commandes ont été enregistrées, pour une installation cli. Un appelant lit ainsi sur la réponse quel genre d’attachement a été placé plutôt que de le redéduire du type qu’il a envoyé. Une suppression renvoie type et query à côté de son scope, et rien d’autre — il n’y a rien de plus à rapporter sur une entrée qui a disparu.
Un ajout porte aussi written et, sous dryRun, content. written est ce sur quoi un client se branche : true nomme un fichier de configuration désormais sur disque que le client peut ouvrir, et sous dryRun il est false et content porte à la place le document de configuration que l’écriture aurait produit. Les deux ne sont jamais significatifs en même temps, et le fichier auquel content est destiné est scope.configFile ; rien dans la réponse ne porte donc une seconde copie de ce chemin — ce qui importe ici, car le fichier d’un attachement global est celui par lequel se résout chaque workspace de cette machine.
Un plugin sans version publiée est refusé plutôt qu’attaché sans épinglage. Un ajout résout la requête vers un seul plugin et épingle sa version publiée la plus élevée, de sorte que l’entrée qu’il écrit porte une version. Un plugin dont le dépôt ne publie aucune version conforme est refusé en le nommant, et une version qu’une rétractation à laquelle ce workspace fait confiance a retirée est ignorée au profit de la suivante, inférieure.
Une version que nomme la requête est épinglée même lorsqu’elle a été retirée, et withdrawn l’indique. Une query écrite sous la forme <name>:<version> épingle cette version plutôt que la plus récente — pour tous les types sauf provider, qui est lié par son seul nom et refuse une version — et nommer une version constitue la surcharge : là où une rétractation à laquelle cet espace de travail fait confiance l’a retirée, elle est épinglée malgré tout, et la réponse porte withdrawn: true — le fait que aggrega plugin add signale par une ligne retraction: dans le terminal. withdrawn est absent de toute autre réponse, de sorte que sa présence constitue à elle seule tout le signal — et son absence n’affirme pas que la version n’est pas retirée. Là où les marqueurs de retrait d’une version nommée n’ont pas pu être lus, withdrawn est absent et retraction porte unscreened, en indiquant pourquoi, comme pour un ajout qui ne nomme aucune version et rencontre le même échec ; un ajout qui ne nomme aucune version indique plutôt dans retraction ce que la vérification de retrait a conclu au sujet de la version qu’il a choisie.
Un alignement indique s’il a changé quelque chose, et c’est sur ce champ qu’il faut agir. changed distingue une écriture d’un alignement qui a trouvé les enregistrements déjà corrects : un fichier inchangé est laissé identique octet pour octet, de sorte qu’un client qui détient ce document n’a rien à recharger, et exécuter la requête deux fois ne rapporte aucun changement la seconde fois. entity nomme le fichier, hostFunctions porte l’ensemble dérivé, et commands porte le miroir sous forme de valeurs plutôt que sous forme de la ligne qu’affiche un terminal — chaque entrée avec un name, une description facultative et des flags, chaque flag avec son name et ses shorthand, description, type et default facultatifs. L’écriture est atomique, de sorte qu’un client qui lit ce fichier pendant l’alignement n’observe jamais un document partiel.
Une génération remplit exactement une moitié de sa réponse, et le dryRun propre à la réponse dit laquelle. Par défaut, les entités sont écrites et notices porte ce que la génération a dit des écritures qu’elle a effectuées. Sous dryRun, rien n’est créé ni modifié : documents porte chaque entité générée sous la forme du path auquel elle est destinée et de son content, de sorte qu’un client peut les placer dans son propre modèle de document, où elles sont visibles avant d’être enregistrées et peuvent être modifiées ou abandonnées. Les deux moitiés ne sont jamais remplies toutes les deux ; le mode de livraison exécuté se lit donc dans la réponse plutôt que dans ce qui a été demandé.
L’endroit où une requête de plugin ÉCRIT se trouve toujours dans le workspace que cette requête a nommé ; ce qu’elle LIT se décide champ par champ. Une destination absolue, une destination qui remonte hors de la racine et une destination qui en sort par un lien sont refusées plutôt que résolues — ainsi une génération ne peut pas créer d’entités dans une arborescence sur laquelle votre session n’a jamais été ouverte, quoi qu’elle envoie. Un chemin qu’une requête se contente de lire est une question distincte, tranchée champ par champ plutôt que par une règle unique pour tous : aggrega/pluginGenCatalog lit un module et son overlay depuis l’endroit où vous les avez sélectionnés, car un module que vous avez compilé se trouve dans le répertoire de sortie de votre chaîne d’outils, et refuser de l’y lire reviendrait à refuser l’opération dans son objet même. aggrega/pluginSync lit ses deux chemins à l’intérieur du workspace, car cette requête porte sur un fichier que le workspace contient déjà. Les requêtes de localisation ci-dessus acceptent un chemin absolu pour une raison encore différente — un document que le client a déjà ouvert, nommé par la graphie qu’il détient.
Une requête à laquelle il manque quelque chose dont l’opération a besoin est refusée en nommant le champ à envoyer. Un ajout ou une suppression sans type ou query ; un ajout provider sans capability, ou un ajout governance sans role ; un ajout cli sans acceptCapabilities ; un alignement sans entity ou plugin ; une génération qui nomme les deux modes de sélection ou aucun, ou à laquelle il manque overlay ou outputDir. Chacune revient avec le code invalid-params standard, et une nouvelle tentative ne change rien tant que la requête ne change pas. Une suppression dont la requête ne correspond à aucune entrée est refusée aussi, en nommant le type, la requête et le fichier où elle a cherché — celle-ci est un état de la configuration plutôt que de la requête, de sorte que ce qu’il faut corriger peut être l’un ou l’autre.
Rien n’est demandé de façon interactive, et la seule décision qu’on aurait demandée à une personne arrive à la place sous forme de champ. La commande de terminal demande à la personne qui regarde si elle accepte les capacités déclarées d’un plugin d’extension de commande. Personne ne regarde ce flux ; c’est donc à l’appelant d’obtenir et d’envoyer acceptCapabilities, et une requête qui ne le porte pas est refusée en nommant ce qu’il faut envoyer, plutôt que d’installer sur la base d’un consentement que personne n’a donné. Un daemon démarré sans les moyens d’installer une extension de commande refuse purement et simplement un ajout cli, plutôt que de rapporter un succès qui n’a rien installé.
Les types que vous pouvez proposer à un auteur
aggrega/getSchema sans kind indique quels types vous pouvez nommer, et répond à deux largeurs, car un client a besoin de l’une ou de l’autre selon la tâche. Lisez celle que vous demandez.
kinds est chaque jeton auquel le binaire répond. entityKinds est l’ensemble des types dont un auteur écrit un document. La liste large contient la représentation intermédiaire, le lockfile, la configuration du workspace et les contrats des sockets de plugin à côté des types que vous rédigez — de vrais schémas, chacun, mais pas des documents dont quelqu’un écrit un fichier. La liste large est donc celle à partir de laquelle câbler l’association de schémas d’un éditeur, et la liste étroite celle à partir de laquelle construire un sélecteur. Un sélecteur construit à partir de la liste large propose des valeurs qu’aucun schéma de rédaction n’accepte, et l’auteur ne rencontre le refus qu’après en avoir choisi une.
L’ensemble étroit est aussi plus étroit que les types d’entité, et aucun schéma ne vous dit lesquels. Un type appartenant à la plateforme dont le contenu est écrit dans le document d’un autre type n’est pas un document à proposer à un auteur pour commencer. Workload est un tel type : le contenu de workload s’écrit dans le champ workload: d’une Recipe ou d’une FeatureRecipe, soit en ligne, soit depuis un fichier que ce champ importe ; il n’existe donc aucun document de workload à adresser en tant que tel — voir la surface de rédaction du Workload pour savoir où va ce contenu. Son schéma fixe apiVersion et kind exactement comme le fait le schéma d’un type rédigé, car c’est ce qui permet de valider le contenu là où il se trouve ; les valeurs fixes identifient le contenu et ne le rendent pas adressable. Elles ne signalent donc pas qu’un type est à ébaucher. entityKinds porte la réponse, et rien dans les octets du schéma ne la porte.
Chaque entrée de entityKinds porte les deux graphies dont un client a besoin, et aucune ne se déduit de l’autre. kind est le jeton en minuscules avec traits d’union — renvoyez-le comme kind à cette méthode ou à aggrega/scaffoldEntity. documentKind est la valeur que le document lui-même porte dans son champ kind: de premier niveau. Les deux diffèrent par plus que la casse pour un type dont le nom compte plus d’un mot : rien de ce que vous pouvez faire à featurerecipe n’aboutit à FeatureRecipe. Prenez chacune dans l’entrée plutôt que de déduire l’une de l’autre, et il ne reste aucune correspondance à maintenir côté client.
Chaque entrée indique aussi quelles opérations acceptent un document de son type, de sorte qu’un contrôle proposant ces opérations sur un document ne propose que celles qui ne le refusent pas en raison de son type. acceptedBy porte trois booléens, chacun présent dans chaque entrée, et chacun porte sur un document du type nommé pris seul — par son chemin, ou par son nom pour l’inspection — sans rien d’autre envoyé à côté. singleEntityValidation indique si aggrega validate <path> vérifie un document du type, plutôt que de le refuser en nommant la portée du catalogue entier ou de la Release qui le vérifie à la place. publication indique si aggrega/publishEntity nommant le document seul le publie : un Plugin vaut false, car sa publication lie aussi l’exécutable qu’une requête nomme dans plugin, de sorte qu’une requête ne nommant que le document est refusée ; un Manifest et une Release valent false, car aucun de ces deux types n’est publié. inspectionByName indique si aggrega/entityDefinition résout un nom en une entité du type, le nom étant envoyé tel qu’il est écrit là où une entité en référence une autre — un Plugin sous la forme <pluginType>/<name>, et une Recipe ou une FeatureRecipe sous la forme <capability>/<name>, ou par son seul nom là où une seule capacité déclare ce nom. Un true indique que l’opération ne refuse pas le document parce qu’il est de ce type ; elle peut toujours refuser un document particulier pour ce qu’il contient.
Ne tenez aucune liste de votre côté. Les types qui existent sont une propriété du binaire avec lequel vous communiquez ; une liste écrite dans un client est donc juste le jour où elle est écrite et cesse de l’être le jour où un type est ajouté — et ce que voit alors l’auteur, c’est son type absent du seul contrôle qui devait le proposer. Demandez, et la réponse suit le binaire.
Les deux moitiés arrivent ensemble, et seulement lorsque vous ne nommez aucun type. Une requête nommant un type reçoit en réponse le schéma de ce type et ne porte aucune des deux listes, de sorte que la question que vous avez posée se lit dans la réponse. Un jeton auquel aucun schéma ne répond est refusé avec l’ensemble valide complet dans le message, sous le code invalid-params standard, de sorte qu’une faute de frappe est une requête à corriger plutôt qu’une question à poser à une personne.
Elle répond dans un workspace qui ne contient rien. Le vocabulaire est compilé dans le binaire ; cela ne nécessite donc ni document, ni lockfile, ni catalogue — c’est précisément le workspace dans lequel se trouve un auteur qui commence son premier document.
Ce que vous fournit une réponse de scaffold
Cette section porte sur la rédaction d’ébauches. L’autre forme de la méthode écrit un exemple exécutable, et sa réponse est décrite avec la méthode plus haut.
aggrega/scaffoldEntity renvoie du texte. skeleton est du YAML pour le type que vous avez nommé : chaque champ que le schéma de ce type exige, dans l’ordre où le schéma les déclare. Un champ que le schéma fixe à une valeur unique arrive rempli — apiVersion et kind sont ceux que vous remarquerez —, metadata.name porte le name que vous avez envoyé, et chaque autre valeur obligatoire arrive sous forme d’espace réservé typé selon ce que le schéma déclare à cet endroit : une chaîne vide, un zéro, un false, une liste vide, un mapping vide. kind répète le jeton pour lequel le document a été dérivé, de sorte qu’un client ayant plusieurs requêtes en attente attribue une réponse à partir de la réponse elle-même plutôt que de tenir sa propre corrélation.
Il n’écrit rien, et c’est autour de cela qu’il faut concevoir. La méthode ne crée aucun fichier, ne choisit aucun chemin et ne touche aucun répertoire. Ce que vous recevez est un document à écrire, et non un document qui a été écrit — un éditeur place donc le texte dans un nouveau tampon non enregistré que l’auteur peut lire, modifier ou abandonner, et le moment où un nouveau fichier atteint le disque reste là où se trouvent le tampon et l’historique d’annulation. Aucune autre requête ne prend ce document pour le placer quelque part en votre nom ; décider où vit un nouveau document revient à l’éditeur.
Il ne résout rien et n’a besoin de rien de l’espace de travail. Le document est dérivé des schémas que contient le binaire, de sorte que la méthode n’atteint aucun registre ni aucun réseau, ne consulte aucun catalogue et ne lit aucun fichier. Elle répond de la même manière dans chaque espace de travail, y compris un répertoire vide qui ne contient encore aucun document Aggrega — ce qui est exactement l’espace de travail dans lequel se trouve un auteur qui commence son premier document, et où la plupart des autres méthodes décrites ici voudraient d’abord un document ou un lockfile.
La même requête donne les mêmes octets, où qu’elle soit posée. Le document est produit par un seul calcul partagé avec les autres surfaces qui offrent cette capacité, de sorte qu’un éditeur et un assistant à qui l’on demande le même type et le même nom montrent à l’auteur le même texte de départ.
Le squelette porte les champs que son type exige, et ce n’est pas un document fini. Il porte les champs obligatoires et rien d’autre : un champ facultatif que vous souhaitez est un champ que vous ajoutez, et chaque espace réservé est une valeur encore due. Remplissez les espaces réservés, puis exécutez aggrega/validate sur le tampon. Pour une entité de catalogue d’un type que aggrega validate vérifie comme entité unique, cette méthode nomme chaque espace réservé encore dû, chacun à sa clé avec ce qu’il accepte, selon la même lecture que la commande applique au fichier enregistré — y compris un espace réservé que le schéma admet vide, le capability et l’implements d’une Recipe ou FeatureRecipe générée étant ceux que vous rencontrerez. Pour tout autre type, elle soumet le tampon au schéma de son type, de sorte qu’un espace réservé que le schéma refuse vide — une version, par exemple — revient comme constat de ce schéma, et qu’un espace réservé que le schéma admet vide n’en produit aucun. Validation en direct décrit l’entrée sous laquelle arrive chaque espace réservé.
Ce que vous apprend une réponse d’import
aggrega/import convertit une source écrite pour un autre outil en brouillons de documents Aggrega, et il les écrit — contrairement au scaffold ci-dessus, qui vous renvoie du texte. written nomme chaque fichier arrivé sur le disque, relativement à outputDir ; files contient chaque fichier que la requête écrit avec son content, qu’il ait été écrit ou non — chaque brouillon produit par l’importeur, puis l’enregistrement de ce que l’import a écrit, ou sous sync ce que la synchronisation modifie. Les deux répondent à des questions différentes, lisez donc celui qui correspond à votre question : ce qui est maintenant sur le disque, ou ce qui a été produit.
Vous choisissez où vont les brouillons, ou vous laissez faire la racine de l’espace de travail. outputDir est facultatif, comme le sont aggrega import --output-dir et le output_dir de l’outil import de l’assistant : une requête qui n’en nomme aucun crée les brouillons sous la racine de l’espace de travail — là où écrit aggrega import lorsqu’il ne reçoit aucune destination, où qu’il s’exécute — et une requête qui en nomme un les crée à cet endroit. Un répertoire nommé est un chemin à l’intérieur de l’espace de travail, et une valeur relative se résout par rapport à la racine de l’espace de travail plutôt que par rapport à un répertoire où le daemon se trouve par hasard. La source que vous convertissez est l’autre cas et n’est pas confinée ainsi : vous avez sélectionné ce fichier ou ce répertoire, il est donc lu où qu’il se trouve, et le lire là ne change pas l’endroit où arrivent les brouillons. Le répertoire est créé s’il n’existe pas. Sous dryRun, rien n’est écrit, et chaque brouillon nomme tout de même le chemin auquel il est destiné, relativement à l’outputDir que nomme la réponse — le répertoire que vous avez envoyé, ou la racine de l’espace de travail.
Une requête n’écrit jamais par-dessus un Aggregate déjà présent dans outputDir. Un Aggregate est le document qu’un auteur continue de modifier une fois qu’il a été ébauché ; une requête dont l’un des brouillons aboutirait sur un fichier qui se lit comme un Aggregate est donc refusée, en nommant le brouillon et l’emplacement de l’Aggregate, et rien du tout n’est écrit — sous dryRun également, puisqu’une exécution à blanc refuse ce que l’écriture refuse. Envoyez plutôt sync pour le mettre à jour par rapport à la source, ou nommez un autre outputDir pour ébaucher à côté de lui. Tout autre fichier déjà présent à un chemin ébauché est écrasé, et un fichier qu’un import antérieur a ébauché et que celui-ci n’ébauche pas est laissé en place. Toute requête qui ébauche quoi que ce soit écrit aussi .aggrega-import.json dans outputDir, l’enregistrement de ce que l’import a écrit — le target qui lui a été envoyé, lorsqu’elle en a reçu un, l’instantané du catalogue lu, lorsqu’un instantané a été lu, et chaque fichier ébauché et, dans un Aggregate ou une Release ébauchés, chaque clé à toutes les profondeurs, avec un condensé du texte qui y a été écrit, tout autre fichier ébauché étant enregistré en entier — et files et written le portent après les brouillons. Il est au format JSON, si bien que rien de ce qui lit les documents YAML du workspace ne le lit ; sync, comme aggrega import --sync, le lit pour mettre les brouillons à jour par rapport à leur source. Un sync envoyé sans target ébauche pour la cible que nomme l’enregistrement, et ébauche donc le Manifest que l’import antérieur a ébauché ; envoyé avec un target, il ébauche pour celui-ci, et l’enregistrement le nomme alors. Une cible enregistrée à laquelle aucune Recipe du catalogue ne se lie est refusée comme l’est une cible envoyée, le refus indiquant qu’il s’agit de la cible enregistrée. Comme une Release ébauchée est enregistrée clé par clé, l’environnement que son auteur écrit là où l’import a laissé un commentaire à son intention est une clé écrite par l’auteur, et une synchronisation la laisse intacte octet pour octet.
Envoyez sync pour mettre à jour par rapport à la source ce qu’un import précédent a créé en brouillon dans outputDir, en ne modifiant que ce que l’import a écrit. Chaque partie est jugée de trois façons — ce que l’enregistrement indique que l’import y a écrit en dernier, ce qui est sur le disque, et ce que la source produit maintenant. Une partie que la source a laissée telle que l’import l’a écrite en dernier reste exactement telle qu’elle est sur le disque, qu’un auteur l’ait modifiée ou non. Une partie que la source a modifiée est réécrite, une partie qu’elle a abandonnée est supprimée — un fichier en brouillon étant supprimé en entier — et une partie qu’elle a gagnée est ajoutée à côté des parties que le brouillon nomme autour d’elle, chacune uniquement là où ce qui est sur le disque est ce que l’import a écrit en dernier et ne contient rien qu’un auteur ait ajouté. Tout le reste reste identique octet pour octet : une clé qu’un auteur a ajoutée n’importe où — un paramètre, une Feature, y compris sous une instance de Component en brouillon, un autre Component — un commentaire qui n’est pas écrit directement au-dessus d’une clé en brouillon, et tout fichier que l’enregistrement ne liste pas. Une synchronisation dans un répertoire qui ne contient aucun enregistrement et rien à ses chemins de brouillon écrit le brouillon entier, comme le fait une requête sans sync.
drift est ce qu’une synchronisation a mis à jour, et c’est la réponse à « la source a-t-elle bougé ». Il liste chaque partie que la synchronisation a modifiée — ou, sous dryRun, chaque partie qu’elle modifierait — dans l’ordre où le brouillon les nomme, chacune sous la forme change (added, removed ou changed), file, le fichier en brouillon où elle se trouve, relativement à outputDir, et key, les clés qui y mènent dans un Aggregate ou une Release en brouillon sous forme de liste, de sorte qu’une clé contenant un point reste une seule entrée ; key est vide là où la partie est le fichier entier, et c’est ainsi qu’est nommé un fichier en brouillon que la synchronisation supprime. aggrega import affiche les mêmes entrées sur la sortie d’erreur standard sous la forme <change> <key> in <file> ou <change> <file>, et son code de sortie sous --sync --dry-run indique si la source a dérivé ; cette interface n’a pas de code de sortie, envoyez donc sync avec dryRun et regardez si drift est vide. drift est une liste vide pour une requête qui n’est pas une synchronisation, pour une synchronisation en phase avec sa source, et pour une synchronisation dont l’importeur n’a pas pu terminer. Sous sync, files contient chaque fichier en brouillon que la synchronisation modifie, avec le contenu qu’elle lui donne, puis l’enregistrement là où il change aussi, et written nomme ceux qui sont arrivés sur le disque — une synchronisation en phase répond donc aux deux par des listes vides. Un fichier en brouillon que la synchronisation supprime est nommé dans drift et dans aucune des deux listes : son entrée removed, avec une key vide, est la seule mention qu’en fait la réponse, et sous dryRun elle nomme le fichier qu’une écriture supprimerait.
Une synchronisation ne réécrit jamais ce qu’un auteur a écrit, et refuse à la place. Une synchronisation qui modifierait ou supprimerait une partie qu’un auteur a modifiée, ajouterait une partie là où un auteur en a déjà écrit une, ou supprimerait une partie contenant quelque chose qu’un auteur a ajouté est refusée, en nommant chacune de ces parties et la raison sur une ligne à part, dans les termes qu’utilise aggrega import --sync — <file> <key>: <why>, ou <file>: <why> pour un fichier entier — et rien n’est écrit ; un commentaire écrit directement au-dessus d’une clé en brouillon modifie cette clé. Une synchronisation sur un Aggregate qu’aucun enregistrement ne liste est refusée en nommant l’Aggregate et l’enregistrement, de même qu’une synchronisation dont l’enregistrement ne peut pas être lu, puisque sans l’enregistrement ses parties ne peuvent pas être distinguées de celles d’un auteur. Les deux refus reviennent sous forme d’erreur invalid-params, sous dryRun également, et nomment sync. Réconciliez à la main chaque partie nommée, ou rétablissez ce que l’import y avait écrit, et renvoyez la requête.
🔴 halted: true n’est pas une erreur, et le traiter comme tel est l’erreur contre laquelle concevoir. Un importeur qui n’a pas pu tout convertir crée tout de même les brouillons de ce qu’il a pu : la réponse contient ces brouillons, written les nomme, et diagnostics indique ce qui a été laissé de côté. C’est la réponse la plus utile que donne l’opération, et elle arrive comme un résultat plutôt que comme un échec précisément pour que vous puissiez montrer à l’auteur les deux moitiés. Sous sync, la même réponse n’écrit rien — files, written et drift sont vides — car un brouillon partiel se lirait comme une source ayant abandonné chaque partie que l’importeur n’a pas atteinte. Une source que l’importeur n’a pas pu lire du tout est un cas différent et revient bien sous forme d’erreur.
Chaque diagnostic contient severity et message, plus code là où l’importeur en a attribué un. Branchez-vous sur code lorsque vous voulez réagir à une condition précise et montrez message au lecteur ; severity est tiré du même ensemble que celui dans lequel chaque socket de plugin rend compte — halt, warn, info — donc halted est un résumé des entrées plutôt qu’un jugement distinct. files, written, drift, diagnostics et decisions sont toujours des tableaux, vides plutôt qu’absents.
decisions indique où l’import a deviné. Il contient une entrée par nœud source que l’importeur a mappé, dans l’ordre de l’importeur et exactement comme l’importeur l’a rapporté : sourceNode, l’id, le type et le paramsSummary du nœud ; candidates, chaque Component du catalogue que l’importeur a envisagé pour lui, sous la forme componentName, score, tier et signals — ce que chacun de ses signaux a apporté, sous table, category, domainLabels, shape et name ; chosen, la target choisie, le mode dans lequel il l’a écrite — une reference à un Component existant ou un draft — et le tier du choix ; rationale, la justification ; et swapHint, comment choisir autrement. candidates est absent là où l’importeur n’en a envisagé aucun, chosen là où il n’a fait aucun choix, et rationale et swapHint là où il n’en a écrit aucun. Chaque valeur est celle de l’importeur lui-même — la façon dont il note un candidat et l’endroit où tombent ses niveaux sont ses choix — montrez donc une entrée comme son propre compte rendu du mappage plutôt que comme un verdict. Les décisions arrivent sous dryRun comme avec halted à true : les suppositions d’un import partiel sont exactement ce dont a besoin un auteur qui le relit, et un importeur qui n’en rapporte aucune répond par une liste vide. Là où vous les montrez sous forme de texte, aggrega import formule déjà une décision sous la forme mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, le score étant celui du meilleur candidat.
Le format est reconnu à partir de la source, sauf si vous le nommez. La reconnaissance utilise les signatures que déclarent les importeurs — ceux du catalogue de l’espace de travail comme les importeurs de base du compilateur — et que consigne l’entité Plugin de chaque importeur — la syntaxe dans laquelle une source est lue, les noms de fichiers auxquels s’applique une signature, et les chemins que l’arbre analysé doit ou ne doit pas contenir — de sorte que le daemon lui-même ne connaît aucun format et que le format d’un nouvel importeur est reconnu sans rien changer d’autre. La détection ne lit que la source que vous avez envoyée — pour un répertoire, uniquement les fichiers que sélectionnent les motifs de fichiers d’une signature — et aucun réseau, en analysant chaque fichier qu’elle lit avec le parseur que le catalogue de l’espace de travail fournit pour une syntaxe — ou, pour une syntaxe pour laquelle le catalogue ne fournit aucun parseur, celui que le compilateur embarque lui-même — une fois pour chaque syntaxe dans laquelle le lit une signature s’appliquant à son nom ; l’importeur lit ensuite la source avec le même parseur. Une signature qui ne déclare aucun motif de fichier s’applique au fichier que vous avez envoyé, quel que soit son nom, et à aucun fichier d’un répertoire ; les signatures des importeurs Langflow, Flowise et n8n sont de ce type et lisent du JSON, et celle de l’importeur Dify lit du YAML, donc reconnaître un fichier envoyé seul revient à le lire comme JSON et comme YAML, ce qui ne nécessite aucun parseur dans le catalogue de l’espace de travail : le compilateur embarque un parseur JSON et un parseur YAML, et celui que fournit le catalogue est utilisé à sa place. Une source à laquelle ne correspond aucune signature est refusée en demandant format et en nommant les formats qu’annoncent les importeurs — ou, pour un répertoire, en demandant l’un de ses fichiers envoyé seul ou un format dont l’importeur déclare des motifs de fichiers, en ne nommant que ceux-là — sous la condition No importer recognises the source (Aucun importeur ne reconnaît la source) ; une source à laquelle correspondent des signatures de plus d’un format est refusée en les nommant, sous la condition More than one importer recognises the source (Plus d’un importeur reconnaît la source). Le data de chaque refus contient le code et le shortCode de sa condition, de sorte qu’un client demande le format en se fondant sur le code plutôt que sur le texte. Aucun des deux n’est deviné, car un format deviné résout le mauvais importeur et produit des absurdités assurées. format dans la réponse est celui qui a été utilisé, détecté ou nommé, de sorte qu’un client qui l’a omis apprend ce qu’il a obtenu.
Un répertoire que vous envoyez est lu dans les fichiers que nomme son importeur, et un répertoire qu’il ne peut pas lire est une erreur. Là où source nomme un répertoire, l’importeur reçoit ceux de ses fichiers que sélectionnent les motifs de fichiers déclarés par ses signatures, hormis le dossier de sortie de build de l’espace de travail dist/, chacun nommé par son chemin à l’intérieur du répertoire, dans l’ordre trié, à côté des fichiers que son entrée plugins.importer nomme sous with.sources. Un importeur qui ne déclare aucun motif de fichier, un répertoire ne contenant aucun fichier qu’ils sélectionnent, un fichier du répertoire et un fichier de with.sources de même nom, et un lien parmi les fichiers que l’import lirait, ou vers un répertoire, qui mène hors du répertoire, reviennent chacun sous forme d’erreur portant le code de la condition, sans que rien ne soit écrit.
Le choix de l’importeur exécuté revient à l’espace de travail, pas à la requête. Le format se résout vers l’importeur qui l’annonce parmi les plugins du catalogue de l’espace de travail et les importeurs de base du compilateur — celui qu’attache une entrée plugins.importer de la configuration de l’espace de travail, là où elle en attache un — de sorte qu’une requête ne peut ni sélectionner un module ni pointer vers un module sur le disque. Un format qu’aucun importeur n’annonce est refusé en nommant le format, et un format qu’annoncent deux importeurs sans qu’aucun ne soit attaché — parmi lesquels un importeur de base et un importeur d’un autre nom que le catalogue contient pour le même format — est refusé comme ambigu plutôt que résolu arbitrairement.
Un importeur de base que la machine ne possède pas encore est récupéré une fois, par le premier import qui en a besoin. Il provient du registre par défaut de l’espace de travail, limité au module que publie la version du compilateur et vérifié comme un pull vérifie un plugin qu’il récupère — sa signature selon la politique de confiance de ce registre, et les fonctions hôtes qu’il utilise — et il est conservé dans le cache de contenu de l’espace de travail, qui est la seule chose écrite pour lui : aucun lockfile, et aucun registre des plugins de confiance. Chaque import ultérieur le lit à partir de là et n’atteint aucun registre. Un module qui ne passe pas la vérification est une erreur portant le code de sa condition, et rien n’est conservé ; un module qui ne peut pas être récupéré — l’espace de travail est hors ligne, son registre est injoignable, ou le registre ne le contient pas — est une erreur sous A plugin’s .wasm is not on this machine (Le module d’un plugin n’est pas sur cette machine), qui nomme l’importeur, sa version et ce qui place son module sur la machine. La requête elle-même ne nomme aucun registre, et un import dont chaque importeur et le catalogue qu’il lit sont déjà sur la machine n’atteint aucun réseau.
Lorsque l’espace de travail ne nomme aucun dossier de catalogue, l’import lit le catalogue que publie son registre par défaut. Un espace de travail dont ni workspace.catalog_dirs, ni AGGREGA_CATALOG_DIRS, ni la racine ne nomment de dossier de catalogue lit le catalogue de la bibliothèque standard sous la forme d’un unique instantané signé, à catalog/snapshot sur son registre par défaut. Un instantané est récupéré une seule fois : sa signature est vérifiée selon la politique de confiance de ce registre, puis il est conservé dans le cache de contenu de l’espace de travail et lu à cet endroit comme un dossier de catalogue, lié à son condensé, sans qu’aucun registre ne soit de nouveau sollicité pour lui. Quel instantané une requête lit : avec upgrade, le plus récent ; sinon celui que nomme l’enregistrement dans outputDir, récupéré par son condensé là où la machine ne le détient pas ; sinon celui que l’espace de travail a récupéré en dernier comme le plus récent ; sinon le plus récent. L’enregistrement qu’écrit l’import nomme l’instantané lu, par son condensé, de sorte qu’une requête ultérieure dans le même outputDir lit le même catalogue. En posture hors ligne, une requête qui devrait récupérer un instantané est une erreur sous The workspace is offline and the step needs the network (L’espace de travail est hors ligne et l’étape a besoin du réseau), qui nomme ce qu’il faut exécuter, et upgrade est refusé quoi que détienne la machine, puisque seul le registre peut dire quel instantané est le plus récent. Un registre qui ne publie aucun instantané laisse l’import sans catalogue, et une entrée warn dans diagnostics le signale. Un espace de travail qui nomme un dossier de catalogue importe par rapport à celui-ci et ne récupère aucun instantané, et upgrade n’y change rien.
Sous dryRun, rien n’est créé. written est vide, files contient les mêmes fichiers qu’une écriture aurait produits — avec sync, les fichiers que la synchronisation écrirait, à côté du drift qu’elle mettrait à jour — et aucun répertoire n’est créé — de sorte qu’un éditeur peut les présenter à l’auteur pour qu’il les enregistre, les modifie ou les écarte. Tout ce que fait par ailleurs une écriture est fait : le même importeur s’exécute sur la même source et rapporte les mêmes diagnostics, donc une source qu’une écriture refuserait est refusée ici aussi. Un importeur de base ou un instantané du catalogue récupéré sous dryRun est conservé dans le cache de contenu comme lors d’une écriture, car acquérir ce sur quoi l’import s’exécute fait partie de son exécution plutôt que du placement des brouillons.
Un chemin que renvoie l’importeur est maintenu à l’intérieur de outputDir. Les chemins des brouillons viennent de l’importeur et non de vous, donc un chemin qui remonte hors du répertoire de sortie est refusé et rien du tout n’est écrit — pas même les brouillons dont les chemins étaient corrects. Le refus nomme le chemin fautif, et c’est ce qui vous indique que c’est l’importeur qu’il faut corriger et non votre requête.
À quelle question répond chaque requête d’entité
Quatre requêtes vous renseignent ici sur une entité, et elles ne sont pas interchangeables. Le choix entre elles dépend de ce que vous avez en main lorsque vous posez la question.
Vous avez en main un curseur. aggrega/hover et aggrega/resolve prennent un fichier et une position et déterminent quelle entité est visée à partir de ce qui y est écrit. Elles couvrent les formes de référence qu’un document contient réellement — une valeur extends, un type de composant ou de feature, le implements d’une Recipe, les références de recipe d’un Manifest, les deux pointeurs de chemin d’une Release, une cible uses, et le propre metadata.name d’une entité. Utilisez-les lorsque le curseur de l’utilisateur est la coordonnée : l’utilisateur lit un document et veut savoir vers quoi pointe une référence.
Vous avez en main un nom. aggrega/entityDefinition prend directement l’identité. Rien n’a besoin d’être ouvert, aucune position n’intervient, et l’entité n’a pas besoin d’être mentionnée à un endroit que le client peut trouver. Utilisez-la lorsque l’utilisateur a saisi un nom, en a choisi un dans une liste, ou a suivi quelque chose dont votre propre client connaît déjà l’identité — un hover vous oblige d’abord à trouver un endroit où le nom est écrit, un travail que vous n’avez pas à faire.
Vous n’avez encore rien en main. aggrega/catalogIndex énumère ce que contient l’espace de travail, avec les champs descriptifs de chaque entité. Utilisez-la pour alimenter un sélecteur, puis transmettez un nom choisi à aggrega/entityDefinition.
Vous avez en main une Release. aggrega/releaseClosure répond au sujet d’une Release plutôt que d’une seule entité, et c’est l’objet de la section ci-dessous.
La définition que renvoie une requête par nom est l’entité telle que résolue, et non telle qu’un fichier particulier la déclare. Un Component ou une Feature qui étend une base revient avec le contrat de cette base, qui n’apparaît nulle part dans le document qui déclare son nom — la réponse porte donc sur ce qu’est l’entité, et lire le fichier vous-même ne vous donnerait pas la même chose.
Elle arrive sous forme de document YAML plutôt que de structure dans la réponse, et c’est délibéré : un pilier de schéma a plusieurs formes de rédaction — un contenu écrit en entier, une référence à un document partagé, ou le marqueur indiquant que le contenu vient d’une base — et le document reproduit celle à laquelle la résolution a abouti, dans l’ordre des clés propre à l’auteur. Analysez-le comme un document si vous avez besoin de ses champs ; montrez-le tel quel si vous l’affichez dans un panneau.
Distinguer les deux refus par nom
Un nom qui ne se résout en rien est refusé plutôt que de recevoir pour réponse un document vide, car une réponse vide présenterait une faute de frappe comme une entité n’ayant rien à dire d’elle-même. Un nom peut ne se résoudre en rien de deux façons, elles demandent des choses différentes au lecteur, et vous les distinguez par ce que contient le data de l’erreur, et non en lisant le message :
- Aucun
filedansdata. Rien dans l’espace de travail ne déclare ce nom et aucun niveau du catalogue ne le résout. C’est presque toujours la requête qu’il faut corriger — une faute de frappe, ou un nom provenant d’un catalogue que cet espace de travail n’a pas dans son chemin de recherche. - Un
filedansdata. Un document de l’espace de travail déclare bien ce nom, et le catalogue n’a pourtant rien résolu pour lui. L’entité est écrite et quelque chose l’a refusée, ce qui est un état de l’espace de travail qu’une personne répare. Là où exactement un document que le catalogue a lu et refusé déclare ce nom — la cause habituelle — le message commence par ce refus, énoncé une seule fois : sa catégorie et son code court, le document par le chemin sous lequel il est signalé, et ce qui ne va pas, comme la ligne et la contrainte qu’il viole ; puis il indique que le fichier a été ignoré au chargement, et liste tout autre fichier que le chargement a refusé. Sinon, le message nomme le document déclarant, liste les fichiers que le chargement a refusés, et indique d’où cet espace de travail lit les entités locales et ce qu’il faut changer pour que le document soit lu — l’explication qu’il omet là où un document refusé déclare le nom, car ce document se trouve déjà là où lit le catalogue.
Les deux portent le code entity-not-resolvable, branchez-vous donc sur la présence de file plutôt que sur le code.
Interroger une coordonnée
Vous avez en main une référence de registre. Envoyez-la comme name de aggrega/entityDefinition, et la réponse est l’entité publiée à cette coordonnée, dans la même forme de résultat que celle d’un nom, plus published, remplie à partir de ce qui a été publié plutôt qu’à partir de ce qu’un catalogue a résolu :
definitionest le document de l’entité exactement tel qu’il a été publié. Une coordonnée dont l’entité a été publiée avec les fichiers qu’elle déclare contient une archive, et le document en est extrait ; une coordonnée dont l’entité ne déclare aucun fichier contient son document inchangé, et l’entité d’un Plugin est lue depuis son manifeste plutôt que depuis l’exécutable publié avec lui. Aucun héritage n’est appliqué.authoredLengthest la longueur de ce document, car la définition est ici un document rédigé plutôt que le rendu d’un document résolu.fileest vide, car une entité lue depuis un registre n’a sur cette machine aucun document à nommer.publishScopeest omis : vous avez déjà en main la coordonnée, qui est l’endroit où l’entité est publiée.publishedest ce qui a été lu, et il est présent dans cette réponse et dans aucune réponse par nom : lareference;archive, qui indique si ses octets étaient une archive dont le document a été extrait —falselà où la coordonnée contenait le document lui-même ; lemediaTypeque déclare le manifeste ; et lemanifestDigestde ce manifeste, que vous pouvez envoyer après@à la place du tag pour relire exactement les mêmes octets.
La requête atteint le registre que nomme la référence, avec les identifiants de l’utilisateur sous lequel s’exécute ce daemon et la posture réseau de cet espace de travail, donc un espace de travail hors ligne la refuse. Les octets récupérés sont vérifiés par rapport au condensé que le propre manifeste de l’artefact enregistre pour eux et à rien d’autre — aucune signature n’est vérifiée et aucun retrait n’est signalé — et rien n’est écrit. Une référence qui ne peut pas être lue est refusée avec entity-not-resolvable, et le message commence par le code court de la condition qui en donne la raison — les mêmes conditions que signale aggrega inspect — et se termine par ce qu’il faut faire. Une référence qui ne nomme aucun dépôt, ou ni tag ni condensé, est une requête mal formée et est refusée comme paramètres invalides.
Une fermeture n’est pas le graphe
aggrega/irGraph et aggrega/releaseClosure sont dérivés de la même résolution de la même Release et répondent à des questions différentes. Un client qui reçoit déjà le graphe peut raisonnablement supposer qu’il a aussi celle-ci, et ce n’est pas le cas.
Le graphe dit ce que déploie la Release — ses nœuds, les frontières dans lesquelles ils se trouvent, ce qui est relié à quoi, et les valeurs et pièces jointes que porte chaque nœud. C’est l’image.
La fermeture dit ce qui a été intégré pour la construire, et dans quelles versions. Chaque entité qu’atteint la Release, qu’elle soit devenue un nœud ou non ; les documents partagés sur lesquels s’appuient ces entités ; et les plugins qui façonnent la sortie. C’est la nomenclature.
Aucun des deux ne peut être reconstitué à partir de l’autre. Une entité peut être atteinte sans jamais apparaître comme nœud — la Recipe vers laquelle un Manifest mappe un type de composant est atteinte par chaque build et n’est un nœud dans aucun d’eux — et un nœud ne porte pas la version vers laquelle son type s’est résolu. Ainsi, un lecteur qui demande « pourquoi cette version a-t-elle bougé ? », « qu’affecterait une modification de ce document partagé ? » ou « de quoi dépend réellement cette Release ? » demande la fermeture, et un lecteur qui demande « que déploie cette Release ? » demande le graphe.
Ce que ne fait pas la requête de fermeture. Elle n’effectue aucun rendu et ne publie rien de ce qu’elle trouve. En particulier, elle ne lève aucun avertissement de dérive ni aucun avis de rendu : ceux-ci appartiennent à la requête qui les a demandés, et la publication remplace toute une couche de diagnostics, de sorte qu’une liste qui publierait effacerait ce que la requête de graphe avait déjà mis sous les yeux de l’utilisateur. Demandez le graphe lorsque vous voulez le verdict de dérive. La seule chose qu’elle publie n’est pas une constatation qui lui est propre : une requête qui constate que le lockfile a disparu retire l’avertissement de dérive qui s’appuyait sur lui, quelle que soit cette requête — voir Prise en compte du lockfile.
Elle exige un lockfile, comme le graphe. Les versions que rapporte la liste sont celles vers lesquelles cette Release s’est résolue, et un espace de travail que personne n’a préparé ne les a pas encore résolues. Une liste produite sans lockfile rapporterait ce que le catalogue contient par hasard aujourd’hui, ce qui est une autre question que celle de savoir de quoi dépend cette Release. Le refus nomme le lockfile et la Release, de sorte qu’un client peut proposer directement aggrega pull --release <release>.
kind n’est présent dans une entrée de fermeture que là où il est connu. Une référence est collectée à partir d’une position dans un document, et certaines positions indiquent vers quel type d’entité elles pointent tandis que d’autres non. Le champ est rapporté là où le site de référence en a enregistré un et omis là où ce n’est pas le cas, plutôt que deviné à partir de la forme du nom. Il est rapporté sous la forme du mot qu’un auteur écrit en tête d’un document, qui est le même mot que chaque interface rapportant une fermeture utilise pour la même entrée.
Le même mot demande le même document ailleurs. aggrega inspect <release> --closure répond à cette question en ligne de commande, et le mode release de l’outil describe y répond via le protocole d’outils de l’assistant. Les trois exécutent une seule résolution sur la Release, de sorte qu’ils ne peuvent pas en venir à diverger sur ce dont dépend une Release. Voir aggrega inspect, « La fermeture des dépendances ».
Modèle de cache
Les opérations sont pilotées par le cache : appelez aggrega/validate pour un fichier avant hover / completion / resolve / diagnostics sur celui-ci. Cet appel d’amorçage n’a pas besoin d’une Release — une validation qui n’en nomme aucune analyse quand même le tampon et remplit le cache — donc ces opérations fonctionnent dans un espace de travail qui n’a aucune Release à nommer. Le cache d’analyse est comparé à la date de modification sur disque de chaque fichier à chaque lecture, de sorte que les modifications externes (un enregistrement dans l’éditeur, un git checkout) sont prises en compte automatiquement — le aggrega/invalidate de l’éditeur est une optimisation, pas une exigence de correction.
Le cache appartient à l’espace de travail qui l’a amorcé. Un fichier validé dans un espace de travail est mis en cache pour cet espace de travail, donc le même chemin interrogé dans un autre est signalé comme non encore validé plutôt que de recevoir une réponse tirée de l’entrée du premier. C’est ce qui empêche une question portant sur un second espace de travail soit de répondre à tort, soit de coûter au premier son état déjà chaud — et aggrega/invalidate ne vide de même que l’espace de travail qu’il nomme.
Demander des diagnostics pendant qu’une validation est en cours
Une validation amorce deux choses sur un fichier — l’analyse qu’elle transmet aux autres opérations, et les constatations qu’elle rapporte — et elle les amorce à un instant d’intervalle. aggrega/diagnostics est la seule requête qui lit les deux : elle a besoin de l’analyse pour savoir que le fichier est un fichier sur lequel elle peut répondre, et elle répond à partir des constatations. Une requête arrivant entre ces deux instants déciderait donc qu’elle peut répondre alors qu’il n’y a encore rien avec quoi répondre.
Elle attend à la place. Envoyez aggrega/diagnostics pour un fichier en cours de validation, et la réponse arrive lorsque cette validation se termine, avec ce qu’elle a trouvé. Il n’y a qu’une seule réponse correcte pour le fichier quel que soit le moment, et c’est la réponse que vous obtenez — ce n’est jamais une liste vide pour un fichier dont la validation est sur le point de signaler des erreurs, qui est la seule mauvaise réponse dont un client ne peut pas se remettre, car rien ne vous incite à redemander au sujet d’un fichier qu’on vous a dit propre. Les autres opérations fondées sur la position — hover, completion, resolve, findReferences, findImplementations — lisent l’analyse et répondent à partir de l’analyse, elles n’ont donc rien à attendre et n’attendent jamais.
Deux choses mettent fin à l’attente plus tôt, et vous les avez déjà toutes les deux. $/cancelRequest pour l’id de cette requête l’arrête, et un aggrega/shutdown coopératif l’arrête. Aucune des deux n’exige quoi que ce soit de plus dans la requête.
Et l’attente est bornée. Si la validation ne s’est pas terminée dans le budget que le daemon lui accorde, la requête est refusée avec le code validation-in-flight plutôt que de recevoir une réponse vide — voir Codes d’erreur. Ce refus signifie que le travail que vous attendez est réellement en cours, la chose à faire est donc de redemander peu après ; ce n’est pas un signal pour envoyer une autre validation, qui ajouterait du travail et ne répondrait à rien.
Un daemon qui exécute les requêtes une par une y répond dans leur ordre d’arrivée, donc rien ne se chevauche et aucune attente n’a jamais lieu. Un daemon qui les exécute de manière concurrente répond aux mêmes questions de la même manière, et c’est l’attente qui le garantit : la réponse que vous obtenez est celle qu’un ordonnancement en série vous aurait donnée.
Tailles dans une réponse
Une réponse qui rapporte une quantité d’octets la rapporte deux fois : sous forme de nombre, et sous forme de la même quantité écrite en toutes lettres. Le champ écrit est le nom du champ numérique suivi de Text — size et sizeText, totalSize et totalSizeText, reclaimedBytes et reclaimedBytesText, et ainsi de suite dans toute réponse qui contient une taille.
Affichez la forme écrite et calculez avec le nombre. L’intérêt d’envoyer les deux est qu’un client n’a jamais à formuler une taille lui-même : le daemon l’écrit avec le même formateur que celui qu’utilise la ligne de commande, de sorte que aggrega cache status et aggrega/cacheStatus affichent un cache donné de façon identique, jusqu’à l’arrondi. Un client qui composerait son propre texte s’en écarterait la première fois qu’il divergerait sur un seuil.
La forme écrite utilise des unités binaires — 512 B, 1.0 KiB, 5.0 MiB, 3.0 GiB — soit le même vocabulaire que celui qu’accepte aggrega/cacheEvict dans maxSize, de sorte qu’une taille lue dans une réponse peut être renvoyée dans la requête suivante sans être réécrite. Au-delà des octets, le texte comporte une décimale, de sorte qu’il exprime la quantité comme un lecteur veut la voir plutôt qu’à l’octet près ; lorsque vous avez besoin du compte exact, c’est à cela que sert le champ numérique.
Là où le nombre est facultatif, le texte l’est avec lui, et les deux ne sont jamais présents à moitié : la taille du plugin dans une réponse de publication contient pluginSize et pluginSizeText ensemble ou ni l’un ni l’autre.
Chaque requête nomme l’espace de travail qu’elle concerne
Envoyez workspaceRoot dans chaque requête : le chemin absolu de la racine de l’espace de travail sur lequel agit cette requête. Le daemon ne détient aucun espace de travail propre et n’en mémorise aucun d’une requête à l’autre, donc ce sur quoi une requête reçoit une réponse est l’espace de travail qu’elle a nommé et rien d’autre. Deux requêtes nommant deux espaces de travail obtiennent deux réponses, et aucune ne peut voir les entités, les Releases, les analyses en cache ou les diagnostics de l’autre.
Une requête qui n’en nomme aucun est refusée avec l’erreur standard invalid-params qui nomme le paramètre, de même qu’une valeur vide, qui n’indique aucun espace de travail et reçoit la même réponse qu’une valeur manquante. Deux autres formes sont refusées pour la même raison, chacune nommée dans le message : un chemin relatif, car une racine d’espace de travail n’a rien par rapport à quoi être relative ; et un chemin qui n’est pas un répertoire existant, car un espace de travail est une arborescence.
Trois requêtes n’ont pas besoin de workspaceRoot, et chacune parce que son objet n’est pas un espace de travail. aggrega/getSchema et aggrega/scaffoldEntity répondent à partir des schémas compilés dans le binaire en cours d’exécution, de sorte qu’un espace de travail n’apporte rien à aucune des deux — c’est ce qui permet aux deux de répondre dans un répertoire que personne n’a préparé. aggrega/initialize est la troisième, et c’est là que vous déclarez un espace de travail plutôt que d’agir sur l’un d’eux. L’autre forme d’aggrega/scaffoldEntity, qui écrit ou liste les exemples exécutables de la documentation, agit bien sur un espace de travail, et une requête pour celle-ci en nomme un comme toute autre.
L’état en cache de chaque espace de travail est conservé séparément, et en nommer un second ne coûte rien au premier. L’index du catalogue, le cache d’analyse et les diagnostics d’un espace de travail appartiennent à cet espace de travail, de sorte qu’une question posée à propos d’un autre endroit n’évince pas ce qu’un éditeur a accumulé pour le dossier que quelqu’un a ouvert. Deux graphies d’une même racine forment un seul espace de travail, de sorte qu’un chemin contenant un . intérieur ou un séparateur doublé atteint le même état chaud que sa forme simple.
Déclarer l’espace de travail pour lequel vous voulez recevoir les diagnostics en push
Les diagnostics circulent de deux façons : vous les demandez, ou le daemon les pousse. Le daemon ne pousse que pour l’espace de travail que vous avez déclaré lors de la poignée de main. Toute autre requête répond avec ses constatations dans sa propre réponse et ne pousse rien.
Déclarez-le en envoyant workspaceRoot dans aggrega/initialize. C’est tout ce que fait la déclaration — elle n’ancre rien, et aucune requête ultérieure ne reçoit de réponse par rapport à elle.
La raison de cette restriction tient à la finalité d’un diagnostic poussé. La poussée est ce qui maintient à jour la liste des problèmes d’un éditeur pendant que quelqu’un tape, et c’est exactement ce qu’il ne faut pas faire d’une réponse que personne n’a demandé à voir : sans cette règle, une question posée à propos d’un second espace de travail — par un autre outil partageant le daemon, par exemple — remplirait la liste des problèmes d’un lecteur de constatations sur des fichiers qu’il n’a jamais ouverts. Restreindre la poussée maintient la question d’un appelant hors de la liste des problèmes d’un autre appelant.
Le champ est facultatif, et les trois choses que vous pouvez vouloir dire par lui se distinguent :
| ce que vous envoyez | où vont les poussées | ce que rapporte la poignée de main |
|---|---|---|
| rien | l’espace de travail sur lequel le processus a été lancé | cet espace de travail |
| une racine d’espace de travail | cet espace de travail | cet espace de travail |
| la chaîne vide | nulle part — aucun diagnostic n’est jamais poussé | une racine vide |
N’envoyer rien laisse les poussées sur l’espace de travail sur lequel le processus a été lancé, de sorte qu’un client qui ne déclare rien reçoit les diagnostics de cet espace de travail. Envoyer la chaîne vide est la déclaration honnête pour un appelant qui n’est pas un éditeur et n’a aucune liste de problèmes à garder synchronisée : chaque constatation lui parvient tout de même, dans la réponse à la requête qui l’a produite.
Un espace de travail déclaré est résolu exactement comme l’est un espace de travail nommé par une requête, de sorte qu’une déclaration nommant un chemin relatif, ou un chemin qui n’est pas un répertoire, est refusée lors de la poignée de main plutôt que de laisser les poussées dirigées vers un endroit inattendu.
Racine de l’espace de travail et Release active
Le daemon résout chaque espace de travail qu’une requête nomme de la même manière que chaque commande aggrega en résout un, et Configuration indique ce qui ancre une racine et dans quel ordre. Deux conséquences comptent pour un client. Un .aggrega-config.yaml sans bloc workspace: n’ancre pas : il apporte toujours ses paramètres, mais un simple fichier de paramètres ne peut pas faire de chaque répertoire parent une racine d’espace de travail. Et quand rien n’ancre, le répertoire de travail est utilisé — le daemon démarre et les opérations ne résolvent simplement rien, au lieu de refuser de s’exécuter.
Le processus est lui aussi lancé sur un espace de travail, à partir de --workspace-root ou en remontant depuis son répertoire de travail, et cette résolution fait deux choses et aucune autre : elle dimensionne le pool de workers, qui est une propriété du processus et non d’une requête, et elle constitue la déclaration par défaut pour les diagnostics poussés. Aucune requête n’est traitée par rapport à elle.
La configuration est de même la cascade que lit chaque commande, et Configuration est l’endroit où elle est décrite. Ce que le daemon ajoute, c’est seulement que la lecture qu’en fait chaque espace de travail est effectuée une fois, quand cet espace de travail est nommé pour la première fois, puis réutilisée pour chaque requête ultérieure qui le concerne. Un fichier de configuration que cette cascade lirait et qui est un lien menant hors de l’espace de travail — le .aggrega-config.yaml de l’espace de travail lui-même, ou la surcouche appartenant à la CI à côté de lui — n’est pas lu, ici comme dans un terminal, et rien d’autre de ce que ce fichier aurait configuré n’est lu à sa place. Ce qui diffère d’un terminal, c’est ce qui répond malgré tout. Le daemon lancé sur un tel espace de travail démarre, et le signale une fois sur son flux d’erreur ; une requête qui en nomme un reçoit dans tous les cas la réponse suivante. aggrega/releaseCandidates et aggrega/catalogIndex — les deux requêtes qui listent ce que contient un espace de travail — y répondent, en le lisant sans rien de configuré : les documents propres à l’espace de travail sont listés, aucun répertoire de catalogue n’est lu, et le fichier écarté est nommé dans unreadLinkedFiles, que la recherche l’ait rencontré ou non. Ce nom est la manière dont un client sait que la configuration de l’espace de travail mène hors de celui-ci. Toute autre requête nommant l’espace de travail — un build, un graphe, une validation, la Release par défaut, la configuration effective, une écriture, et aggrega/catalogIndex dans les termes d’une Release — dépend de cette configuration ; elle est donc refusée avec l’erreur invalid-params portant E0321 — read-leads-out-of-workspace dans le data de l’erreur — et la phrase nommant le lien et l’endroit où il mène. Le handshake répond aussi pour un tel espace de travail, en indiquant defaults comme son configSource, puisqu’aucun fichier de configuration n’a contribué à ce par quoi les listes répondent. Supprimez le lien, ou faites-le mener à un fichier à l’intérieur de l’espace de travail, et la requête suivante lit la configuration. Sous les fichiers du projet se trouve la couche globale : le fichier que --config nomme sur la ligne de commande qui a lancé le daemon, pour chaque espace de travail qu’il sert ; sinon le fichier que nomme la variable d’environnement AGGREGA_CONFIG lorsqu’elle est définie ; et sinon l’emplacement par défaut — sous Windows aggrega\config.yaml dans le répertoire que nomme la variable d’environnement APPDATA, et ailleurs aggrega/config.yaml dans le répertoire que nomme XDG_CONFIG_HOME, avec repli sur ~/.config/aggrega/config.yaml — chargé s’il est présent. Les valeurs par défaut intégrées se trouvent en dessous.
Les opérations qui agissent sur une Release en reçoivent une en paramètre ; le daemon n’en sélectionne aucune de lui-même. Un espace de travail déclare toujours vers quelle Release il pointe, et une cascade en quatre étapes lit cette déclaration : le champ de configuration build.authoring_release, puis un fichier marqueur .aggrega/active-release, puis une heuristique de Release unique dans l’espace de travail, puis un repli sur l’Aggregate seul. Un marqueur que vous écrivez a donc priorité sur l’heuristique, et un marqueur nommant une Release qui ne peut pas être chargée retombe sur l’heuristique plutôt que sur le repli. Un marqueur nommant une Release hors de l’espace de travail — par un chemin absolu, par un chemin qui remonte au-delà de la racine, ou par un lien qui en sort — n’est pas lu, à moins que la configuration de votre espace de travail ne nomme cette Release comme build.authoring_release ou comme clé de workspace.releases : la configuration est le moyen d’atteindre une Release conservée hors de l’espace de travail, le marqueur ne l’est pas. La cascade continue alors exactement comme pour un marqueur qu’elle ne peut pas charger, et là où elle n’aboutit à rien, trace en donne la raison sur la ligne du marqueur et reason dans sa phrase sur le marqueur.
aggrega/activeRelease indique ce que choisit cette cascade, et c’est une suggestion pour un client plutôt qu’un paramètre sur lequel le daemon agit. Interrogez le daemon plutôt que de lire vous-même les entrées de la cascade : le champ de configuration et le fichier marqueur sont deux des quatre entrées, si bien que celle que vous lisez ne désigne le choix de l’espace de travail que lorsqu’elle se trouve être l’entrée qui l’a emporté. Un marqueur nommant une Release qui ne peut pas être chargée est le cas le plus net — la cascade choisit une tout autre Release, et quelqu’un qui lirait le marqueur indiquerait celle qui a échoué.
La cascade s’exécute quand vous le demandez et pas avant, ce qui a deux conséquences sur lesquelles on peut compter. Le handshake reste rapide quelle que soit la taille de l’arborescence, car il n’attend pas le parcours de l’espace de travail. Et la réponse suit l’espace de travail : écrivez un marqueur — avec aggrega/setActiveRelease, qui répond lui-même avec le nouveau choix — modifiez la configuration, ajoutez ou supprimez un fichier de Release, puis redemandez, et vous obtenez la nouvelle réponse du même daemon. Changer la Release sur laquelle vous travaillez n’exige jamais de redémarrer le daemon — un client envoie un release différent dans sa requête suivante.
Les opérations qui cherchent dans tout l’espace de travail plutôt que dans un seul tampon — completion, hover, resolve, findReferences et findImplementations — énumèrent le YAML sous la racine de l’espace de travail, et cette énumération respecte .gitignore. Chaque .gitignore depuis la racine de l’espace de travail jusqu’au répertoire du fichier lui-même contribue, le plus proche l’emportant, si bien qu’un fichier YAML que votre dépôt ignore n’est pas proposé comme candidat de complétion et n’est pas signalé comme définition ou référence. Un .gitignore qui est un lien menant hors de l’espace de travail n’est pas lu, si bien qu’un fichier situé ailleurs sur la machine ne décide jamais quels documents de l’espace de travail sont parcourus. Les arborescences vendorisées et la sortie générée restent donc hors des résultats inter-fichiers sans aucun paramètre d’exclusion distinct à maintenir — et un document que vous vous attendez à voir trouvé mais que vous avez ignoré n’apparaîtra pas, ce qui est le seul cas à vérifier quand une référence semble manquer. Les Components et les Features que completion propose aussi depuis vos catalog_dirs configurés relèvent d’une autre lecture : ils proviennent de ces répertoires tels que configurés — les mêmes répertoires que lit un build d’une Release quand la configuration ne lui en donne aucun en propre, ou, pour une requête nommant une Release, ceux de cette Release — si bien que les entités d’un répertoire de catalogue sont proposées qu’un .gitignore le couvre ou non — sauf une entité située derrière un lien menant hors du répertoire à l’intérieur duquel les lectures d’un répertoire de catalogue doivent rester, qui n’est ni lue ni proposée.
Une requête qui nomme une Release lit les répertoires de catalogue de cette Release, qui sont ceux que lit un build de celle-ci dans un terminal : les siens, là où la configuration de l’espace de travail lui en donne sous workspace.releases, et sinon les catalog_dirs de l’espace de travail. Cela couvre aggrega/build, aggrega/buildPreview, aggrega/irGraph, aggrega/releaseClosure, aggrega/resolveDependencies, aggrega/validate et aggrega/lint nommant une Release, aggrega/attachCandidates et aggrega/attachmentContainer adressées à un nœud du graphe d’une Release, et aggrega/connectionAtPosition, ainsi que les requêtes que liste la section suivante lorsqu’elles en nomment une. Ainsi une seule session répond pour chaque Release d’un espace de travail qui conserve une variante de catalogue par Release, chacune à partir de sa propre variante, sans rien envoyer d’autre que le chemin de la Release. Une requête qui ne concerne aucune Release en particulier — aggrega/catalogIndex, aggrega/entityDefinition, completion, hover et resolve ne nommant aucune Release, et aggrega/attachCandidates adressée à une entité ou à un ensemble de labels — lit les catalog_dirs de l’espace de travail. aggrega/lint ne nommant ni entité ni Release est l’exception dans un espace de travail qui nomme des Releases sous workspace.releases : il y vérifie le catalogue entier une fois pour chaque Release, chaque passe portant sur les répertoires de cette Release, comme le décrit Publier les conventions, à la demande et à chaque modification. Voir Donner à une Release ses propres répertoires de catalogue.
Répondre dans les termes d’une Release
aggrega/catalogIndex, aggrega/entityDefinition et les cinq requêtes qui partent d’un curseur — aggrega/hover, aggrega/resolve, aggrega/completion, aggrega/findReferences et aggrega/findImplementations — ne concernent aucune Release en particulier, et chacune accepte un release facultatif qui lui fait en concerner une. C’est un chemin relatif à la racine de l’espace de travail, soumis au même contrat que celui des autres requêtes qui acceptent une Release ; une valeur qui ne nomme aucun fichier de Release, ou qui nomme un répertoire, est refusée plutôt que de recevoir une réponse dans les termes de l’espace de travail tout en se lisant comme celle de la Release.
Ce qu’une Release atteint, pour chaque requête ici : les documents de l’espace de travail situés sous les répertoires de catalogue que lit sa pile, et chaque document de l’espace de travail qui ne se trouve sous aucun répertoire de catalogue — une Release, son Aggregate et son Manifest écrits à côté des catalogues. Un document de l’espace de travail situé sous un répertoire de catalogue que seules d’autres Releases lisent ne fait pas partie de sa réponse : ni listé, ni résolu, ni proposé. C’est ce qui empêche de confondre des variantes d’une même entité, conservées côte à côte pour des Releases différentes.
- La liste. Nommer une Release liste les entités que cette Release voit. Les Features listées sont celles que déclarent les répertoires de catalogue de cette Release, et un document de l’espace de travail situé sous un répertoire de catalogue que seules d’autres Releases lisent est écarté — si bien qu’un espace de travail conservant une variante d’une entité par Release liste la seule variante avec laquelle cette Release est construite, plutôt que toutes les variantes côte à côte. Un document qui ne se trouve sous aucun répertoire de catalogue, comme une Release, son Aggregate et son Manifest écrits à côté des catalogues, appartient à la liste de chaque Release.
- Une recherche par nom. Nommer une Release résout le nom à travers les répertoires de catalogue de cette Release, si bien qu’un nom que déclarent plusieurs variantes se résout en la variante avec laquelle cette Release est construite. Un nom que ses répertoires ne résolvent pas est refusé avec une explication nommant l’entrée de cette Release sous
workspace.releases, puisque c’est cette entrée que la recherche a lue. Une référence de registre n’accepte pas de Release, et est refusée si elle en reçoit une : elle est lue depuis le registre qui la publie, quelle que soit la Release nommée. - Survol et accès à la définition. En nommant une Release, la référence sous le curseur est d’abord résolue à travers les répertoires de catalogue de cette Release, dans l’ordre que leur donne la configuration de l’espace de travail — la même résolution qu’effectue une recherche par nom dans les termes de cette Release — si bien que l’entité affichée, et le document ouvert, est la variante en laquelle ces répertoires la résolvent, même là où un document de l’espace de travail situé ailleurs déclare le même nom. C’est seulement là où aucun document sous ces répertoires n’y répond que sont parcourus les documents de l’espace de travail que cette Release atteint. Sans en nommer aucune, l’ordre est inversé : les documents de l’espace de travail sont parcourus en premier, si bien qu’une référence à laquelle répond un document de l’espace de travail conserve cette réponse, et les
catalog_dirspropres à l’espace de travail ne sont consultés que là où aucun document ne déclare le nom — ce qui permet de trouver une entité que seul un répertoire de catalogue configuré contient, y compris un répertoire situé hors de l’arborescence de l’espace de travail. Là où l’éditeur détient une copie non enregistrée du document en lequel se résolvent les répertoires d’une Release, et que cette copie déclare toujours le nom, la réponse est lue depuis la copie, si bien qu’une position tombe sur la ligne que l’éditeur affiche. - Complétion. En nommant une Release, les noms proposés sont ceux que déclarent les documents de l’espace de travail que cette Release atteint, avec les Components et les Features que déclarent les répertoires de catalogue de cette Release.
- Références et implémentations. En nommant une Release, un emplacement dans un document de l’espace de travail que cette Release n’atteint pas n’est pas signalé, si bien qu’une variante conservée pour une autre Release n’est jamais listée comme référence ou implémentation de celle-ci.
- Ce qui peut s’attacher à un nœud du graphe.
aggrega/attachCandidatesadressée à un nœud du graphe d’une Release est toujours dans les termes de cette Release — voir Ce que vous apprend une réponse sur les candidats à l’attachement.
Sans en nommer aucune, la réponse porte sur les répertoires de catalogue propres à l’espace de travail, comme le décrit le paragraphe ci-dessus.
Atteindre un registre, et écrire
La plupart des requêtes ici répondent à partir de l’espace de travail et de ce qui est déjà en cache, et n’écrivent rien. Quelques-unes, nommées, font davantage, et elles se répartissent selon deux axes indépendants : ce qu’une requête atteint, et jusqu’où porte ce qu’elle modifie.
Les requêtes qui s’adressent à un registre se répartissent entre celles qui lisent et celles qui publient. aggrega/resolveDependencies récupère ce dont une Release a besoin, et aggrega/build s’y ajoute lorsque — et seulement lorsque — son champ autoPull lui demande de résoudre d’abord les dépendances, auquel cas il atteint un registre et écrit le lockfile avant d’effectuer le rendu ; aggrega/registryUpdate parcourt chaque registre configuré pour reconstruire l’index de recherche local ; aggrega/pluginAdd cherche dans le registre configuré le plugin qu’une requête nomme et lit ses versions publiées pour en épingler une ; aggrega/registryAdd demande au registre qu’il enregistre la politique de confiance que ce registre annonce, à moins que la requête ne renonce à la récupération ou ne fournisse sa propre politique, et aggrega/configInit demande la même chose au registre qu’il initialise ; aggrega/explainError acquiert le bundle de documentation dans lequel il lit l’explication détaillée d’une condition, une seule fois, là où le cache que partagent tous les projets de la machine ne contient aucune copie qu’admet la vérification de signature propre à l’espace de travail — voir aggrega explain ; aggrega/scaffoldEntity envoyé avec example ou list acquiert le même bundle aux mêmes conditions, et une écriture écrit ensuite l’exemple dans un nouveau répertoire de l’espace de travail ; aggrega/import récupère un importer de base depuis le registre par défaut de l’espace de travail, une seule fois, là où la machine ne le détient pas encore, et, dans un espace de travail qui ne nomme aucun dossier de catalogue, l’instantané publié du catalogue qu’il lit — voir Ce que vous apprend une réponse d’import ; et aggrega/entityDefinition lit l’entité que nomme une référence de registre lorsqu’une telle référence est envoyée comme son name, sans rien écrire. aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts et aggrega/deprecateArtifact écrivent dans un registre — des octets, une signature ou un marqueur de retrait. Une requête n’atteint un registre que lorsqu’elle a été envoyée pour cela : une liste indique ce que la configuration épingle, une recherche lit un instantané hors ligne, et une publication demandée avec dryRun calcule ce qu’elle enverrait et ne contacte personne.
La règle porte sur le moment où une opération s’exécute, non sur la surface qui l’exécute. Une opération qui récupère ou écrit s’exécute parce qu’une requête l’a nommée, et jamais comme effet de bord de la validation d’un document, de l’inspection d’un graphe ou de la liste des entités d’un espace de travail. Ainsi un éditeur qui valide à chaque frappe n’atteint aucun réseau et ne réécrit aucun lockfile, tandis qu’une action « résoudre les dépendances » sur laquelle l’utilisateur clique fait exactement ce que fait aggrega pull — la même résolution, derrière les deux surfaces, qui écrit un lockfile identique octet pour octet et remplit le même cache d’artefacts.
Rien n’est demandé. Personne n’observe ce flux, donc l’identité est résolue à partir d’une source d’identifiants fournie ou présente dans l’environnement, et jamais en posant la question. Là où la commande en terminal aurait posé une question à une personne — un registre qui exige des identifiants, une capacité que sert plus d’un plugin de provider, le texte que doit porter un retrait — la requête échoue avec un message nommant ce qu’il faut fournir, plutôt que de rester bloquée sur une réponse qui n’arrivera jamais. Un refus laisse l’espace de travail exactement tel qu’il était : aucun lockfile n’est écrit et aucun enregistrement partiel n’est laissé derrière, et une publication qui n’a pas pu résoudre un identifiant refuse avant que le moindre octet n’atteigne le registre.
Certaines modifications vont au-delà de cet espace de travail, et la réponse dit lesquelles
Une requête nomme un seul espace de travail, donc une réponse qui n’a rien à dire sur sa propre portée se lit comme portant sur cet espace de travail. Pour plusieurs de ces requêtes, cette lecture serait fausse ; chacune porte donc sa portée, et un client devrait l’afficher avant d’agir sur le résultat.
Publier, signer et retirer vont entièrement au-delà de la machine, ce qui est la plus large portée de tout ce qui figure ici. Les autres écritures ci-dessous changent ce que cette machine résout ; celles-ci changent ce que fait quiconque résout depuis ce registre. Les octets publiés sont ce que reçoit chaque consommateur de ce registre, et republier un contenu différent sur un tag est refusé plutôt que proposé, si bien qu’aucune requête ici ne revient sur une publication — la réponse est de publier une nouvelle version. Une signature et un marqueur de retrait sont attachés à côté de l’artefact plutôt qu’en remplacement, si bien que les octets eux-mêmes restent intacts ; mais quiconque récupère l’artefact par la suite les récupère aussi, et aucun des deux ne peut être rappelé auprès de quelqu’un qui l’a déjà. Un retrait est des trois le plus facile à mal interpréter : la version reste récupérable, tandis qu’une rétractation à laquelle un espace de travail fait confiance la retire de ce qu’une résolution y choisira.
La signature utilise des identifiants, et il vaut la peine de savoir d’où ils viennent avant de brancher un client. La signature sans clé résout un jeton d’identité, dans l’ordre, depuis identityToken dans la requête, puis AGGREGA_IDENTITY_TOKEN dans l’environnement du daemon, puis le point de terminaison OIDC de GitHub Actions présent dans l’environnement là où il est joignable, puis SIGSTORE_ID_TOKEN. Quand aucun de ceux-ci ne fournit de jeton, l’opération refuse et nomme ce qu’il faut envoyer ; elle n’ouvre jamais de navigateur, car personne n’est là pour le regarder. La signature avec clé est l’alternative hors ligne, et une requête ne nomme aucun chemin de clé : ce qu’une requête lit se trouve à l’intérieur de l’espace de travail qu’elle a nommé, et une clé privée n’est jamais conservée à l’intérieur d’un espace de travail, si bien que la clé provient plutôt du bloc signing: de la configuration propre à cet espace de travail. Voir aggrega sign pour les deux modes de signature et ce que chacun contacte.
Chacune des quatre réponses porte reach, qui contient registries — chaque hôte de registre auquel l’appel s’est adressé, chacun nommé une fois, dans l’ordre où l’appel s’est adressé à lui pour la première fois, si bien qu’un lot de signature ou un fichier de lot dont les références couvrent plusieurs registres les nomme tous — et beyondThisMachine, qui est dérivé de ce que l’appel a effectivement attaché plutôt que de ce qu’il a demandé : vrai exactement lorsqu’il a téléversé du contenu ou attaché une signature, une date de publication ou un marqueur de dépréciation, et faux pour une exécution à blanc et pour un appel qui a trouvé déjà présent tout ce qu’il aurait attaché — une publication relancée sur une version déjà complète, ou un lot de signature dont chaque référence portait déjà une signature qui se vérifie. Une exécution à blanc nomme quand même la destination à laquelle elle se serait adressée. Affichez-la avant d’agir sur le résultat.
Enregistrer ou supprimer un registre écrit par défaut la configuration partagée par tous les espaces de travail de la machine. Un registre et les identités auxquelles vous y faites confiance sont généralement les mêmes partout où vous travaillez, c’est donc là que va l’entrée, à moins que la requête n’envoie workspace: true. La conséquence mérite d’être dite clairement : aggrega/registryAdd et aggrega/registryRemove changent ce par quoi chaque projet de cette machine résout, y compris des projets que personne dans cette session n’a nommés. Les deux réponses portent scope, avec le configFile qui a été écrit et machineWide qui indique s’il s’agit du fichier partagé. La suppression est la plus délicate des deux, car réajouter n’est pas le même acte — la politique de confiance qui était épinglée a disparu, et un enregistrement ultérieur épingle ce que le registre annonce alors.
Initialiser une configuration écrit par défaut ce même fichier partagé, et pour la même raison. aggrega/configInit enregistre un registre et sa politique de confiance, qui relèvent de l’outillage à l’échelle de la machine ; sans surcharge, il écrit donc la configuration par laquelle chaque projet de la machine résout — et il atteint ce registre une fois pour lire la politique qu’il annonce. Sa réponse porte la même paire scope que les deux méthodes de registre. Il s’en distingue sur un point sur lequel on peut compter : il refuse plutôt que d’écraser un fichier de configuration existant, si bien qu’il ne peut pas remplacer une configuration à partir de laquelle quelqu’un travaille, à moins que la requête n’envoie force. Figer est le cas inverse : aggrega/configCapture n’accepte aucune surcharge, écrit toujours le fichier de configuration propre au projet et n’atteint aucun registre, si bien que rien de ce qu’il fait n’est visible d’un autre projet. Voir Ce que laisse une écriture de configuration.
🔴 Ajouter ou supprimer un plugin d’extension de commande écrit par défaut ce même fichier partagé, et c’est celui-ci qu’il faut lire attentivement. aggrega/pluginAdd et aggrega/pluginRemove acceptent un type, et c’est le type qui décide où va l’écriture lorsqu’aucune surcharge n’est envoyée. Une entrée provider, governance, linter ou importer façonne le build d’un projet ; elle va donc dans la configuration propre à ce projet. Une entrée cli relève de l’outillage à l’échelle de la machine ; un ajout de type cli ne nommant ni global ni workspace enregistre donc la commande dans le fichier de configuration globale par lequel résout chaque espace de travail de cette machine — la commande devient une commande aggrega de premier niveau pour chaque projet de cette machine, y compris des projets que personne dans cette session n’a nommés, et la retirer est une suppression distincte plutôt qu’une annulation. Envoyez workspace: true pour la garder locale. Les deux réponses portent scope, avec le configFile qui a été écrit et machineWide qui indique s’il s’agit du fichier partagé, dérivé du fichier vers lequel l’écriture s’est résolue. Un ajout atteint aussi le registre dans lequel il a cherché ; il se situe donc sur les deux axes à la fois. Voir Ce que vous apprend une modification de plugin.
Les deux autres requêtes de plugin n’écrivent qu’à l’intérieur de l’espace de travail. aggrega/pluginSync écrit le fichier d’entité Plugin que la requête nomme, et aggrega/pluginGenCatalog écrit les entités générées sous l’outputDir que la requête nomme — toutes deux à l’intérieur de l’espace de travail nommé par la requête, toutes deux refusant une destination absolue ou qui se résout hors de celui-ci, et aucune n’étant visible d’un autre projet. aggrega/pluginGenCatalog lit son module et sa surcouche là où vous les avez sélectionnés, ce qui n’élargit pas l’endroit où il écrit : les deux sont résolus selon des règles différentes, si bien qu’une génération peut lire un module que vous avez construit n’importe où tandis que les entités qu’elle produit atterrissent malgré tout dans l’espace de travail. aggrega/pluginGenCatalog avec dryRun n’écrit rien du tout et renvoie le contenu à la place.
Épingler une entité n’écrit aussi qu’à l’intérieur de l’espace de travail, et atteint les hôtes que nomment ses sources. aggrega/pin écrit l’entity.lock à côté de l’entité que la requête nomme, qui est un chemin à l’intérieur de l’espace de travail, et remplit le cache de contenu de l’espace de travail avec les sources qu’il a récupérées ; rien de ce qu’il écrit n’est visible d’un autre projet. Il va à l’extérieur pour résoudre chaque source distante que l’entité nomme — un dépôt de charts, un hôte Git, une URL — ce qui est la même portée que celle de aggrega/resolveDependencies pour les sources qu’une Release consomme. aggrega/resolveDependencies et aggrega/publishEntity envoyées avec pinSources exécutent cette même étape, si bien que chacune écrit aussi à côté des entités qu’elle épingle ; une publication qui épingle atteint donc l’espace de travail aussi bien que le registre. Une publication qui n’épingle pas n’écrit rien à côté de l’entité, et atteint quand même ces hôtes : comparer le lock avec ce que l’étape enregistrerait implique de récupérer chaque source distante que l’entité écrit en entier.
Installer le skill de l’assistant reste à l’intérieur de l’espace de travail à moins que la requête n’envoie global. aggrega/skillsInstall écrit le dossier de skill de projet de chaque assistant nommé à l’intérieur de l’espace de travail que la requête a nommé, et rien de ce qu’il y écrit n’est visible d’un autre projet ; le scope de sa réponse porte machineWide à false. Avec global: true, il écrit plutôt le dossier par utilisateur de chaque assistant sous le répertoire personnel, que cet assistant lit dans chaque projet de la machine, et machineWide vaut true. Dans les deux cas, il n’atteint aucun registre ni aucun réseau.
Supprimer un identifiant stocké porte plus loin que tout ce qui, ici, s’arrête à cette machine. aggrega/logout modifie le magasin d’identifiants, et ce magasin est partagé non seulement par chaque projet de la machine mais par chaque autre outil qui s’authentifie auprès des mêmes registres — si bien qu’un identifiant supprimé via une session disparaît pour tous, et aggrega/registryList le signalera absent dans chaque autre espace de travail aussi. Sa réponse porte scope avec machineWide, qui vaut toujours true : ce magasin n’a aucune forme limitée à l’espace de travail vers laquelle se résoudre, il n’y a donc aucune surcharge à envoyer et rien à quoi une requête pourrait adhérer. scope ne nomme délibérément aucun fichier, contrairement aux écritures de configuration ci-dessus. Le magasin délègue à l’assistant d’identifiants ou au trousseau du système d’exploitation que la machine a configuré, si bien que la suppression est souvent servie par quelque chose qui n’est pas du tout un fichier, et nommer un chemin vous orienterait vers un emplacement que la suppression n’a pas nécessairement touché.
La suppression n’est pas l’inverse de l’authentification, et un client ne devrait pas la proposer comme telle. Cette surface supprime un identifiant et n’en acquiert pas : récupérer un identifiant implique de s’authentifier à nouveau avec aggrega login dans un terminal, car en stocker un exige un secret saisi par une personne et personne n’observe ce flux. Une « déconnexion » que propose un client est donc, à partir d’ici, à sens unique. Ce qui sépare les deux, c’est le fait que l’opération doive obtenir quelque chose de celui qui la pilote — une suppression porte son unique valeur dans la requête, alors que l’acquisition d’un identifiant non — et non le fait qu’une personne soit impliquée, puisqu’une personne a choisi les deux.
Récupérer l’espace du contenu du cache porte aussi au-delà de l’espace de travail. Les magasins de modules compilés et de descriptions de plugins sont partagés par chaque projet de la machine, si bien que aggrega/cachePrune, aggrega/cacheEvict et aggrega/cacheClear peuvent supprimer du contenu dont dépend un autre projet. Chaque suppression porte le reach de la classe dont elle provient, et chaque réponse porte scope.machineWideClasses. aggrega/cacheStatus porte la même portée sur chaque classe bien qu’il ne change rien, car un client qui décide s’il doit récupérer de l’espace en a besoin avant d’agir.
Actualiser l’index de recherche est le cas inverse. aggrega/registryUpdate atteint chaque registre configuré, et ce qu’il écrit atterrit sous le répertoire de cache configuré propre à cet espace de travail — il ne change donc rien de ce par quoi un autre projet résout. indexRoot dans la réponse nomme ce répertoire.
Une actualisation partielle répond plutôt que d’échouer. Une requête nommant un registre dont l’actualisation a échoué est une erreur, car il n’y a aucune réponse à donner. Une requête actualisant chaque registre configuré réussit même là où certains d’entre eux, ou tous, ont échoué : ceux qui ont été actualisés ont été indexés et écrits, failed nomme les autres, et chaque hôte porte sa propre erreur. Lisez failed plutôt que la présence d’une erreur.
Le fait qu’un registre ait pu être atteint est une clé, pas une lecture du message. Un hôte en échec porte unreachable: true là où le registre n’a jamais été atteint — son nom ne s’est pas résolu, une connexion vers lui a été refusée ou n’a pas pu être ouverte, ou une connexion sécurisée avec lui n’a pas pu être établie — et le refus d’une requête nommant un registre porte la même clé dans son data. Un registre qui a été atteint et a échoué, avec une liste qui se répétait ou un statut d’erreur, ne porte la clé ni dans un cas ni dans l’autre, et son error, ou le message du refus, dit ce qu’il a répondu. La clé est lue à partir de l’échec lui-même, elle ne dépend donc pas de la manière dont le résolveur de cette machine formule un échec, et elle n’est définie que là où l’échec montre que le registre n’a jamais été atteint : un échec qui ne montre rien dans un sens ou dans l’autre, comme un délai écoulé sans trace de l’étape qu’il a interrompue, est signalé sans elle. Désignez un registre comme non atteint d’après la clé, et affichez l’erreur comme raison.
La ligne de commande signale ce même parcours par un code de sortie non nul, et le type de lecteur que vous êtes décide de ce que vaut ce code de sortie. Pour une personne devant un terminal, ce n’est pas le compte rendu complet : aggrega registry update affiche combien des registres sélectionnés il a indexés, ce que chacun a trouvé, lesquels il n’a pas indexés et où l’index a été écrit — le résumé dit donc ce qui s’est passé et le statut de sortie dit seulement si tout a réussi. Pour un script, c’est le compte rendu complet, car cette commande n’offre aucun mode de sortie structurée, si bien que son statut de sortie est le seul verdict lisible par une machine disponible. C’est pourquoi les deux surfaces répondent différemment au même parcours partiel et ont toutes deux raison : celle-ci remet failed à un appelant structuré et réussit, tandis que la ligne de commande n’a qu’un bit à dépenser et le dépense sur « un registre a-t-il été manqué ».
Suivre une opération longue
La plupart des requêtes ici répondent à partir de ce qui est déjà sur le disque et répondent immédiatement. Quelques-unes effectuent d’abord un vrai travail — résoudre les dépendances d’une Release, épingler ses entrées externes, publier, signer, retirer — et l’appelant attend. Celles-ci rapportent ce qu’elles font pendant qu’elles le font, et c’est à activer explicitement par requête.
L’activation se fait en deux étapes, dans cet ordre.
- Déclarez la capacité lors du handshake, et attendez la réponse. Envoyez
capabilities.window.workDoneProgress: truesuraggrega/initialize. N’envoyez rien d’autre tant que cette réponse n’est pas arrivée : les requêtes sont traitées de manière concurrente, si bien qu’une requête écrite avant que le handshake ait répondu peut s’exécuter en même temps que le handshake qui devait négocier pour elle. Chaque client doit déjà cet ordre au protocole ; c’est une chose de plus qui en dépend. - Placez un jeton dans les params de la requête. Ajoutez
workDoneTokenaux params de la requête sur laquelle vous voulez un suivi. La valeur est à votre choix — une chaîne ou un nombre — et c’est elle qui lie les notifications à cet appel. Créez-en un nouveau pour chaque appel.
La notification. Chacune est $/progress avec params.token défini sur votre jeton et params.value portant une charge utile :
value.kind | porte | quand |
|---|---|---|
begin | title — ce qui se passe, en une formule que vous pouvez montrer à un lecteur | une fois, quand le travail commence |
report | message — une ligne du compte rendu que l’opération fait d’elle-même | un nombre quelconque de fois, à mesure que l’opération les écrit |
end | rien au-delà du type | une fois, quand le travail est terminé |
Corrélez sur le jeton, jamais sur l’id de la requête. Une notification ne porte aucun id — ce n’est une réponse à rien — et le jeton est la seule chose en elle qui renvoie à votre appel. C’est délibéré : dans de nombreux clients, l’id de la requête appartient au transport et n’atteint jamais le code qui a émis l’appel, alors que le jeton est une valeur que ce code détient déjà.
Un report porte le texte propre du compilateur. Le message est une ligne que l’opération a écrite pendant son travail, transmise avec les espaces qui l’entourent supprimés et rien d’autre de changé — ni reformulée, ni résumée, ni recomposée — et une ligne que l’opération a écrite vide est abandonnée plutôt que signalée comme message vide. Un client affiche donc ce qu’il reçoit tel quel. C’est la même propriété qu’ont les diagnostics propres à la réponse : une condition garde une seule formulation, quel que soit le nombre de surfaces qui la signalent.
Une étape que l’opération attend est aussi un report. Lorsque l’opération entre dans une étape qu’elle attend — la lecture d’un registre, la récupération d’un artefact, la compilation d’un plugin —, un report porte le nom de l’étape, dans les mots que la ligne de commande affiche à côté de son indicateur d’activité pour la même étape. Seules les étapes commencées entre le begin et le end sont signalées.
Une ligne de sortie est un report. Une opération qui écrit plusieurs lignes à la fois produit une notification par ligne, et une ligne que l’opération écrit en plusieurs morceaux est signalée une fois complète — un message n’est donc jamais une demi-phrase.
Il n’y a ni fraction ni pourcentage, et ce n’est pas un oubli en attente de travail. Les opérations qui rapportent ici parcourent un ensemble dont la taille n’est pas connue au début du travail — combien de références une résolution parcourt, combien de couches une publication téléverse — si bien que toute fraction serait inventée. Affichez un indicateur indéterminé et montrez le dernier message.
Les trames arrivent avant la réponse et jamais après. Un begin arrive une fois que le travail a réellement commencé, si bien qu’une requête refusée à cause de ses params — un chemin absolu, un champ obligatoire manquant — ne produit aucune notification, seulement son erreur. Le end arrive avant la réponse, et le succès ou l’échec de l’opération figure dans la réponse plutôt que d’être répété dans le end.
Arrêter le travail est une notification distincte. Envoyez $/cancelRequest avec l’id sous lequel vous avez envoyé la requête. Le jeton ne joue aucun rôle dans l’annulation, et l’annulation ne supprime pas les trames déjà envoyées.
Quelles requêtes rapportent, et à quoi s’attendre des autres
Exactement celles-ci rapportent : aggrega/resolveDependencies, aggrega/pin, aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact.
Deux choses sont vraies de chacune d’elles, et toutes deux expliquent sa présence dans la liste : elle atteint un registre ou une URL distante en votre nom, si bien que sa durée dépend de quelque chose d’extérieur à la machine ; et elle écrit déjà son propre compte rendu d’elle-même au fur et à mesure — le compte rendu que lit une personne qui observe un terminal. Le suivi vous remet donc ce même compte rendu plutôt qu’un second composé pour le transport, et rien de ce que fait l’opération n’a dû changer pour le produire.
Toute autre requête accepte un jeton et n’envoie rien. En envoyer un est sans effet plutôt qu’une erreur : il est accepté, aucune notification n’arrive, et la réponse est exactement celle que vous auriez obtenue sans lui. Un client peut donc attacher un jeton à ce qu’il veut et simplement ne rien afficher quand rien ne vient.
🔴 N’interprétez pas le silence comme « celle-ci est instantanée ». La plupart des autres répondent effectivement à partir de ce qui est déjà sur le disque — une validation, un survol, une complétion, un graphe, une liste du cache, une lecture de configuration — mais pas toutes : actualiser l’index d’un registre, ajouter un plugin, une vérification avant publication, et la première explication d’un code sur une machine qui ne détient aucune documentation que l’espace de travail puisse lire atteignent toutes un registre, et compiler une Release est un vrai travail. Celles-ci prennent le temps qu’elles prennent et ne rapportent rien aujourd’hui. Affichez un indicateur indéterminé pour toute requête que vous êtes prêt à attendre, et traitez les notifications comme un détail que vous obtenez quand il est disponible plutôt que comme ce qui vous dit qu’un travail est en cours.
Deux refus
Les deux sont des erreurs invalid-params et les deux nomment ce qu’il faut faire, car un jeton qui ne ferait silencieusement rien vous laisserait attendre un flux qui n’allait jamais venir.
- Un jeton provenant d’une session qui n’a déclaré aucune capacité
window.workDoneProgressest refusé, avec le nom de la capacité à déclarer. Déclarez-la lors du handshake, ou omettez le jeton. - Un jeton qui n’est ni une chaîne ni un nombre est refusé, avec le nom des deux formes. Un jeton absent, et un
nullexplicite, ne sont pas des refus — tous deux signifient que vous n’avez demandé aucun suivi.
Prise en compte du lockfile
Le daemon vérifie la dérive d’un lockfile à chaque aggrega/irGraph, par rapport à la Release que cette requête a nommée, et signale la dérive comme un avertissement non bloquant. L’avertissement nomme la commande qui réécrit ce lockfile avec la Release dedans, écrite telle que la requête l’a envoyée — aggrega pull --release suivi du release que vous avez envoyé, ce qui est la manière dont on l’écrit dans un terminal à la racine de l’espace de travail. aggrega/irGraph exige qu’un lockfile soit présent. Il n’y a aucune vérification distincte au démarrage : une requête indique de quelle Release il s’agit, si bien que le verdict est calculé pour cette Release au moment où il est demandé plutôt qu’une seule fois pour une Release choisie à l’avance.
Un avertissement de dérive disparaît quand son lockfile disparaît. L’avertissement est publié sur le lockfile à propos duquel il a été émis, et un lockfile qui n’est plus là n’a plus d’épinglage qui aurait pu dériver — la commande que nomme l’avertissement écrirait un nouveau fichier plutôt que de réparer l’ancien. Ainsi chaque requête qui constate l’absence du lockfile retire l’avertissement avant de refuser avec l’erreur de lockfile absent : aggrega/irGraph, aggrega/releaseClosure, aggrega/build, aggrega/buildPreview, aggrega/attachCandidates et aggrega/attachmentContainer interrogées sur un nœud du graphe, et aggrega/connectionAtPosition. Le retrait arrive sous la forme d’une notification aggrega/publishDiagnostics pour le lockfile portant une liste vide, avant le refus. Il provient de celle de ces requêtes qui apprend la suppression en premier, si bien qu’un client qui signale la suppression puis demande quoi que ce soit sur cette Release voit l’avertissement effacé sans avoir à demander spécifiquement le graphe. Un lockfile toujours présent et toujours en dérive conserve son avertissement à travers chacune de ces requêtes. aggrega/invalidate nommant le lockfile abandonne ce que le daemon détient pour lui mais n’envoie rien ; c’est la requête suivante qui informe le client. Et un lockfile que le daemon ne peut même pas examiner — un lockfile dont il ne peut pas lire le répertoire, par exemple — ne retire rien, car il est peut-être toujours là et l’avertissement est peut-être toujours vrai.
aggrega/build et aggrega/buildPreview en exigent un aussi, et ils y astreignent la Release plutôt que d’avertir — ils effectuent le rendu avec la posture d’une surface qui émet un artefact, si bien qu’un lockfile qui ne correspond plus à ce en quoi la Release se résout les arrête là où il ne ferait qu’avertir lors d’une inspection. Une Release sans lockfile est refusée avec l’erreur de lockfile absent. L’exception est un build dont le champ autoPull lui demande de résoudre d’abord les dépendances : ce build écrit le lockfile puis effectue le rendu par rapport à ce qu’il a écrit, et un lockfile produit de cette manière n’est pas vérifié une seconde fois pour la dérive, car la résolution qui l’a écrit a exécuté la même vérification sur lui avant de l’écrire et n’écrit aucun lockfile que cette vérification refuse.
Un lockfile qui existe mais n’enregistre aucun digest pour un plugin n’arrête pas le graphe — un lockfile absent, si. Ce sont deux conditions, et seule la seconde entraîne un refus. aggrega/irGraph n’astreint pas les octets qu’il résout à leurs digests enregistrés : un épinglage qu’il ne peut pas vérifier est signalé plutôt que refusé, et le graphe est dessiné avec le constat dans le panneau Problems, puisqu’un éditeur qui refuse de dessiner le graphe ne laisse rien au lecteur, là où un rapport lui laisse de quoi agir. Ailleurs, le plugin s’exécute aussi, avec un avertissement indiquant que rien n’a vérifié ses octets. Ce que aggrega/irGraph refuse, c’est le lockfile manquant : il s’arrête avant de résoudre quoi que ce soit et répond avec l’erreur de lockfile absent, en nommant le lockfile qu’il a cherché et la Release, si bien qu’un client peut proposer directement aggrega pull --release <release> — ou envoyer aggrega/resolveDependencies pour cette Release et écrire le lockfile sans quitter la session. Garder les deux séparés est important, car un graphe dessiné est une image sur laquelle un lecteur raisonne ensuite, et un graphe construit à partir d’octets que rien n’a vérifiés est dessiné exactement comme un graphe vérifié, le constat se trouvant quelque part où le lecteur ne regarde pas. Un graphe n’est donc pas un verdict sur les octets qui le sous-tendent — aggrega/build et aggrega/buildPreview sont les surfaces qui astreignent une Release à ses digests enregistrés, s’arrêtant là où l’inspection se contente de signaler.
aggrega/validate, lorsqu’une requête nomme une Release, lit le lockfile de cette Release uniquement pour ses épinglages et ses avis de dépréciation — et n’en lit aucun pour une entité de catalogue qu’il vérifie en tant qu’entité isolée, de même que la ligne de commande n’en lit aucun. Il n’astreint pas les plugins qu’il exécute aux digests enregistrés, et il ne reconstruit pas à partir du lockfile l’ensemble des attachements de plugins de transformation — il valide par rapport à la configuration de l’espace de travail telle qu’elle se présente devant vous, ce qu’un éditeur doit faire pendant que vous modifiez cette configuration. aggrega validate et aggrega build font les deux, et restent les surfaces qui font autorité pour un verdict sur un espace de travail commité.
Ses avis de dépréciation couvrent les deux endroits où un retrait est enregistré. Un marqueur sur une référence épinglée se trouve dans le lockfile ; un marqueur sur un plugin attaché dans un rôle qui renvoie un verdict d’acceptation ou de rejet — un attachement plugins.governance à ir-verdict ou render-verdict, ou un attachement plugins.linter — se trouve dans l’enregistrement de confiance des plugins à côté de lui, de sorte que la validation lit les deux et nomme chaque référence retirée et chaque plugin retiré comme un avertissement en tête de l’Aggregate, dans les termes qu’affiche aggrega build. Un avis ne change aucun verdict. Un enregistrement de confiance présent qui ne peut pas être lu est signalé comme une erreur à la place de la validation, plutôt que d’être lu comme un enregistrement qui ne contient rien. aggrega/releaseClosure indique le même ensemble dans son deprecations.
Où se trouve le lockfile d’une Release
Chaque réponse qui nomme une Release nomme aussi son lockfile, si bien qu’un client n’a jamais à déduire le chemin. aggrega/activeRelease le porte en tant que lockfile à côté de release, aggrega/releaseCandidates en tant que table lockfiles à côté de releases, et l’erreur de lockfile absent en tant que lockfile dans son data. Chacun est le fichier que aggrega pull --release <release> écrit et que aggrega build lit, et le fichier que chaque requête ci-dessus recherche — si bien qu’un client qui surveille le lockfile d’une Release, pour remarquer qu’il est écrit, réécrit ou supprimé, surveille le fichier que le daemon désigne. Le lockfile se trouve à côté de sa Release et prend le nom de la Release, une extension .yaml ou .yml étant remplacée par .lock ; une Release nommée avec toute autre extension garde son nom entier, si bien que le lockfile de release.rel est release.rel.lock. Lisez le chemin dans la réponse plutôt que de le composer à partir de cette description, et les deux ne pourront pas diverger.
Les références externes qu’un rendu demande
Un rendu peut demander du contenu depuis une URL distante — le schéma de valeurs d’un chart avec une référence distante, par exemple. Les entrées externes sont figées pour chaque rendu que ce daemon effectue en réponse à une requête qui demandait seulement à être informée de quelque chose. Une référence que le lockfile de la Release épingle est servie depuis le store adressé par contenu, ce qui est une lecture de contenu déjà présent sur le disque plutôt qu’un téléchargement, et elle est vérifiée par rapport à ce que le lockfile enregistre avant que ses octets ne soient servis — ainsi un rendu ici voit ce qu’un build voit, et soulève les avertissements qu’un build soulève. Une référence que le lockfile n’épingle pas est refusée plutôt que téléchargée : l’acquérir reviendrait à atteindre un réseau et à écrire un blob dans le store, et une session ne fait ni l’un ni l’autre pour une requête qui demandait seulement à être informée de quelque chose. C’est la règle décrite sous Atteindre un registre, et écrire lue du côté du rendu, et elle s’applique quelle que soit la manière dont ce rendu a été atteint.
La requête qui existe pour épingler est l’exception, et c’est la même exception que la règle du registre prévoit déjà. aggrega/resolveDependencies est chargée d’acquérir, donc le rendu qu’elle effectue pour découvrir quelles références cette Release consomme atteint le réseau et écrit ce qu’elle épingle — c’est ce qui fait de son résultat un lockfile plutôt qu’un rapport. Aucun rendu qu’une requête de graphe ou de build effectue pour elle-même ne fait quoi que ce soit de tout cela.
Un build à qui l’on demande de résoudre d’abord reçoit sa réponse de ce rendu même, et c’est pourquoi il effectue le rendu de la Release une seule fois. La résolution a déjà rendu ce dont traite le build, par rapport aux épinglages qu’elle vient d’écrire et sous les contrôles qu’un build exécute, donc le build présente ce rendu plutôt que d’en effectuer un second — et l’acquisition reste du ressort de la résolution plutôt que du build. Seul un rendu qui s’est terminé est utilisé ainsi : lorsqu’une résolution a épinglé ses dépendances mais n’a pas pu finir de découvrir les références externes, le build effectue son propre rendu par rapport aux épinglages qui ont bien été écrits, et une référence non épinglée y est refusée et signalée exactement comme dans un build qui n’a rien résolu.
Le refus est signalé plutôt qu’absorbé, car rien dans un résultat n’indique quelle référence y manquait. Avec les providers que ce binaire embarque, le provider qui a demandé la référence renvoie le refus, de sorte qu’un rendu qui a atteint une référence refusée ne se termine pas. Chaque référence refusée arrive donc comme une entrée distincte sur la couche aggrega-build, nommant la référence et la commande qui l’épingle : aggrega pull --release <release>, ou aggrega/resolveDependencies pour le même travail sans quitter la session. Les entrées sont consultatives plutôt qu’un refus — le graphe est tout de même renvoyé, avec le même statut que l’avertissement de dérive ci-dessus — et elles sont attribuées à l’Aggregate en tête du fichier, car une référence demandée par un rendu ne nomme aucune clé écrite par un auteur. Elles voyagent dans la même publication que les avertissements propres au rendu, qui remplace cette couche en entier, de sorte qu’une référence que vous épinglez ensuite cesse d’être signalée sans que rien n’ait à l’effacer. Un rendu entièrement épinglé ne dit rien de tout cela. Voir Ce que contient une entrée de diagnostic pour la forme que prend chaque entrée.
Sur aggrega/irGraph, cela dépend de l’exécution même de l’étape de rendu. La requête de graphe saute le rendu sauf si --build-on-inspect, ou la clé serve.build_on_inspect qu’il remplace, l’active ; le réglage désactivé, rien ne demande de référence externe et il n’y a rien à refuser. L’activer est ce qui amène dans une session d’éditeur à la fois les avertissements propres au rendu et ceux-ci.
En quoi une session diffère du même gel en ligne de commande. aggrega build fige aussi les entrées externes pour une exécution à blanc, et une référence non épinglée se comporte de la même façon sur les deux surfaces : elle est signalée comme un constat nommant la référence, puis le rendu s’arrête, car le provider qui l’a demandée renvoie le refus. Ce qui diffère, c’est le nouveau téléchargement. En ligne de commande, une référence épinglée dont la copie stockée a disparu est téléchargée à nouveau d’après son digest enregistré ; le rendu qui répond à une requête de graphe ou de build ne retélécharge rien, car ce rendu n’atteint aucun réseau, il ne peut donc pas aller rechercher une référence épinglée que le store ne contient plus — et une telle référence ne fait pas partie des refus décrits ci-dessus, qui nomment ce que le lockfile n’épingle pas. Demander à une session d’épingler est ce qui la récupère : les requêtes nommées ci-dessus atteignent le réseau et remettent en place les octets manquants. Voir aggrega pull pour ce que l’épinglage télécharge et enregistre.
Ce qu’une exécution refusée vous dit malgré tout
Une requête qui refuse répond par une enveloppe d’erreur, et les constats que l’exécution avait déjà faits ne voyagent pas dans cette enveloppe — l’enveloppe ne contient aucun corps de résultat. Ils vous parviennent comme ils vous parviennent lors d’une exécution qui s’est terminée : sous forme de publication de diagnostics sur la couche aggrega-build, décrite sous Ce que contient une entrée de diagnostic. Un client qui traite un refus lit donc l’enveloppe pour savoir quoi changer et sa surface de problèmes pour savoir ce que l’exécution a trouvé, et aucune ne remplace l’autre. Un refus soulevé pendant le rendu est le seul refus qui soit aussi un constat sur ce qu’un auteur a écrit, il atteint donc les deux, comme le décrit la section suivante.
Cette publication a lieu que l’exécution soit allée jusqu’au bout ou non. Une exécution qui s’arrête en cours de route a tout de même trouvé tout ce qui précède le point où elle s’est arrêtée, et un lecteur qui perdrait ces constats devrait relancer l’exécution pour les voir — les avertissements sont donc publiés à partir de ce que l’exécution a atteint, et le refus est renvoyé ensuite. C’est le même ensemble, avec la même fidélité, positionné sur les mêmes clés écrites par l’auteur : un refus ne rétrograde pas un constat en une phrase. Les références externes refusées voyagent dans cette même publication, pour la même raison et par la même voie.
Ce qui la borne, c’est jusqu’où l’exécution est allée, et non ce que la couche peut contenir. Un refus provenant de l’un des contrôles exécutés avant le démarrage du compilateur — la fermeture de la Release n’a pas pu être résolue, le Manifest associe un type à une recette qui ne l’implémente pas, le lockfile ne correspond plus à ce vers quoi la Release se résout, une entrée épinglée dans le cache ne correspond plus au digest enregistré pour elle et aucun répertoire de catalogue ne contient les octets épinglés — n’a aucun avertissement à publier, car aucun n’avait encore été soulevé. La couche ne contient alors rien plutôt que quelque chose de périmé ; et une exécution qui n’est pas allée jusqu’à nommer un document ne publie rien du tout, laissant ce qui se trouve déjà sur votre surface de problèmes exactement tel quel plutôt que d’effacer des entrées dont elle n’a rien appris.
Un refus émis pendant le rendu
Une Release que le compilateur refuse pendant le rendu — un Workload nommant un slot que son Component ne déclare pas, une assertion qui échoue, un template qui ne peut pas être évalué, une réalisation qui ne fournit pas ce qu’elle doit fournir — est signalée là où elle pointe et dans les mots du compilateur, sur chaque requête qui en effectue le rendu : aggrega/build, aggrega/buildPreview, et aggrega/irGraph avec l’étape de rendu activée. La réponse est une enveloppe d’erreur avec le code -32603, dont le message est le refus avec chaque cause en dessous, dans les mots que la ligne de commande imprime pour le même build : le nœud en cours de rendu, puis ce qui, en lui, a refusé, chaque cause après celle qu’elle explique — précédé, lorsque le refus nomme une condition enregistrée, du code court de cette condition, comme l’est tout refus qui en nomme une. Son data nomme le document vers lequel pointe le refus sous file, et l’étendue de la clé dans ce document sous line, column, end_line et end_column, à côté du code et du shortCode de la condition ; un refus ne nommant aucune clé, ou une clé que le document ne contient pas, ne porte que file, et un refus qui ne pointe vers aucun document nomme l’Aggregate de la Release.
Le même refus est publié sur la couche aggrega-build, sur ce document, à cette clé, sous forme d’entrée de gravité error portant le keyPath propre au refus et le message de l’enveloppe sans le code court en tête, et — lorsque le refus nomme une condition enregistrée — le code, le shortCode et le codeDescription de cette condition, le code court voyageant là dans son propre champ. Il voyage dans l’unique publication qui porte les avertissements soulevés par l’exécution avant son arrêt, il remplace donc la couche comme eux : la prochaine exécution de la Release qui effectue le rendu publie la couche sans lui, et le document sur lequel il se trouvait est publié vide, ce qui l’efface de votre surface de problèmes.
L’endroit où pointe un refus est ce que le refus lui-même nomme, et rien de plus précis. Les contrôles d’un Workload jugent le document que son template a produit, et un template peut écrire des lignes qu’aucun auteur n’a écrites — une boucle, une condition, un texte importé d’un fichier ou d’une bibliothèque —, de sorte qu’une ligne du Workload rendu ne correspond pas à une ligne de la Recipe. Un refus concernant un Workload est donc placé sur la clé workload de la Recipe, et les chemins qu’il nomme dans le document rendu restent dans son message. Une assertion qui échoue est placée sur sa propre clé sous assertions dans la Recipe ou la FeatureRecipe qui la déclare ; une assertion qu’un Component ou une Feature déclare est soulevée avant qu’un document ne soit disponible pour être nommé, et elle est placée sur la clé kind: de l’Aggregate. Un refus provenant d’une étape qui nomme un document mais aucune clé est placé sur la clé kind: de ce document.
Un refus qui regroupe plusieurs constats est publié constat par constat. La composition du graphe à partir duquel travaille le rendu refuse avec toutes les violations trouvées dans un seul refus — une entrée nommant une cible à laquelle rien ne répond, deux connexions d’un composant ayant le même alias — et la ligne de commande imprime chacune comme un diagnostic distinct, sous son propre en-tête. Ici, chacune est une entrée distincte sur la couche aggrega-build, sur le document et à la clé que ce constat nomme — la Release là où la Release l’a écrit, l’Aggregate là où l’Aggregate l’a fait — dans ses propres mots et avec ses propres codes. Le message de la réponse porte tous les constats, et son data nomme l’endroit où pointe le premier.
Une valeur qu’un auteur a déclarée sensible est masquée ici exactement comme la ligne de commande la masque. Le texte du refus est le texte que le compilateur a soulevé, rien sur cette surface ne le reformule, et le compilateur masque une valeur déclarée là où le refus est soulevé — <redacted> à sa place —, de sorte que cette réponse, cette entrée et le terminal la portent dans les mêmes mots ; ce qu’un refus dit d’une valeur déclarée explique comment, et quels refus en restent en dehors.
Un refus provenant d’un contrôle exécuté avant le rendu n’est pas cela. Les contrôles énumérés ci-dessus répondent comme le décrit Ce qu’une exécution refusée vous dit malgré tout. Une assertion qu’un Component ou une Feature déclare, et un refus portant sur le graphe composé, se situent entre les deux : chacun est soulevé avant le rendu, par toute requête qui résout le graphe d’une Release, donc aggrega/irGraph le renvoie et le publie comme ci-dessus également avec l’étape de rendu désactivée ; aggrega/releaseClosure, aggrega/attachCandidates et aggrega/attachmentContainer interrogés sur un nœud du graphe, ainsi que aggrega/connectionAtPosition, le renvoient avec la même enveloppe et ne publient rien, car ils ne possèdent aucune surface de problèmes.
Codes d’erreur
Les réponses utilisent les codes d’erreur JSON-RPC standard ainsi qu’une plage propre à l’application dans la tranche 1xxx. Un client d’éditeur peut se brancher sur le code sans analyser le message.
1001file-not-validated (fichier non validé) — le daemon ne détient rien pour le fichier, tel qu’il est à présent, à partir de quoi la requête puisse répondre : aucune analyse de ce fichier, ou, pouraggrega/diagnostics, aucune analyse de ce fichier ou rien de détenu pour le fichier qui soit la réponse d’une validation pour le texte que le daemon détient à présent. Envoyezaggrega/validatepour ce fichier et redemandez.1003lockfile-absent (lockfile absent) — la Release nommée par la requête n’a pas de lockfile, et l’opération demandée en a besoin.1004entity-not-resolvable (entité non résolvable) — le nom ne correspondait à aucune entité dans aucun niveau du catalogue, ni dans la Release nommée par la requête ; ou la référence de registre envoyée comme nom n’a pas pu être lue comme une entité, et le message nomme la condition qui explique pourquoi ; ou le lockfile de la Release est un lien menant hors de l’espace de travail, ce qui est refusé avant que quoi que ce soit ne le lise,datanommant le lockfile et la Release et le message commençant par le code court de la condition,E0321— voir la limite de l’espace de travail.1005shutting-down (arrêt en cours) — le daemon se vide après une notification d’arrêt et refuse les nouvelles requêtes. Ne réessayez pas sur le même sous-processus.1006validation-in-flight (validation en cours) — une validation du fichier est en cours et ne s’est pas terminée dans le délai que la requête en attente lui accordait. Redemandez sous peu et n’envoyez rien.
1002 n’est pas attribué, et il est disponible pour la prochaine condition qui aura besoin d’un code.
File-not-validated et validation-in-flight signalent des états opposés, et l’action que chacun appelle est opposée elle aussi. File-not-validated signifie que le daemon ne détient rien pour le fichier, tel qu’il est à présent, à partir de quoi la requête puisse répondre — aucune analyse de ce fichier, ou, pour aggrega/diagnostics, aucune analyse de ce fichier ou rien de détenu pour le fichier qui soit la réponse d’une validation pour le texte que le daemon détient à présent : envoyez aggrega/validate et redemandez. Une validation annulée en cours de route laisse un fichier dans cette situation, car elle ne stocke rien et ce qu’une validation antérieure a trouvé sur un texte différent n’est pas une réponse pour le texte que le daemon détient à présent ; une réponse antérieure reste valable tant que le texte est celui qu’elle a vérifié. Les constats que le daemon pousse au sujet d’un fichier qu’il a lui-même lu sur le disque — un lockfile qui a dérivé, une Release qui ne se charge pas — ne sont pas une validation du texte que vous détenez, et ne répondent donc pas non plus à cette requête. Deux validations de textes différents envoyées à peu d’intervalle peuvent aussi vous laisser dans cette situation, lorsque celle dont le daemon a conservé le texte s’est terminée la première : la requête est refusée bien que ce texte ait été vérifié, et valider à nouveau y répond. Il est formulé en termes d’analyse plutôt que de fichier parce qu’un tampon qu’aucun analyseur ne lira se trouve exactement dans cette position — la validation s’est exécutée et a signalé ce qu’elle a trouvé, et il n’y a toujours aucune analyse à partir de laquelle répondre. Validation-in-flight signifie qu’une validation de ce fichier est en cours et ne s’est pas terminée dans le délai que la requête en attente lui accordait : redemandez sous peu et n’envoyez rien, car l’état dont vous avez besoin est déjà en route et une seconde validation ne ferait qu’ajouter du travail. Lire les deux comme une seule condition conduit un client à envoyer une validation précisément dans le cas où en envoyer une est la mauvaise décision. Les deux tranches signifient des choses différentes pour un client : un code 1xxx nomme un état de l’espace de travail sur lequel l’utilisateur peut agir — valider le fichier, générer le lockfile — tandis qu’un code standard comme invalid-params nomme une requête malformée, que corrige le client plutôt que l’utilisateur. Une valeur release présente mais malformée — absolue, ou se résolvant hors de la racine de l’espace de travail — relève de la seconde tranche : ce n’est pas l’espace de travail qui est dans un état que l’utilisateur doit réparer, c’est la requête. Omettre release ne relève d’aucune des deux tranches, car ce n’est pas du tout une erreur ; cela sélectionne la plus étroite des deux réponses décrites sous Validation en direct.
Une erreur peut porter un objet data, et chaque clé qu’il contient nomme une chose et seulement celle-là. file est le document source que concerne l’échec — le document en cours de validation, la Release dont le chargement a échoué, le document de l’espace de travail qui déclare un nom que rien n’a résolu, ou le document vers lequel pointe un refus soulevé pendant le rendu — et c’est à l’intérieur de celui-ci que les éventuels line et column qui l’accompagnent localisent une position. Ces deux-là sont eux-mêmes facultatifs : un échec qui concerne un document entier ne porte que file. lockfile est un lockfile. release est la Release que concerne l’erreur, écrite comme la requête l’a nommée, de sorte qu’un client peut composer aggrega pull --release <release> sans avoir à l’extraire du message. unreachable indique que le registre nommé par une requête refusée n’a pas pu être atteint : une actualisation d’index refusée nommant un registre la porte, lue à partir de l’échec lui-même, et un registre qui a répondu la laisse absente. Chaque clé est facultative et présente uniquement lorsque le daemon dispose de cette valeur ; aucune ne remplace une autre, de sorte que ce vers quoi pointe une clé ne dépend jamais du code à côté.
code et shortCode dans data nomment la condition qu’un refus signale, sur chaque refus qui en signale une enregistrée, quel que soit son code numérique : le code descriptif sur lequel un programme se branche et le code court qu’une personne cite, les deux mêmes identifiants, sous les mêmes noms, que porte une entrée de diagnostic pour la même condition, et répertoriés dans la table de toutes les conditions. Branchez-vous sur code. Le code numérique nomme l’état de la requête et reste le même pour de nombreuses conditions — un build refusé parce qu’un lien de catalogue mène à l’extérieur et un build refusé parce qu’un nom ne se résout en rien sont tous deux 1004 — et le message est de la prose qui peut être reformulée, donc ni l’un ni l’autre ne distingue une condition d’une autre. Invalid-params est un tel code partagé : une requête nommant un espace de travail dont le fichier de configuration mène hors de lui le provoque aussi, et là read-leads-out-of-workspace indique que le défaut tient à l’agencement de l’espace de travail, qu’une personne répare, plutôt qu’à la requête. Un refus ne signalant aucune condition enregistrée ne porte aucune des deux clés, et les deux sont présentes ensemble ou pas du tout. Le message d’un refus nommant une condition commence par son code court, E0321: …, une seule fois, ce qui est la forme qu’une personne rencontre en le lisant sur chaque refus de ce genre ; un refus dont le message commence déjà par un en-tête entre crochets portant le code — le rapport sur une ligne d’un document de catalogue que le chargement a refusé — ne le reçoit pas une seconde fois.
Le compte rendu de la façon dont s’est déroulée la cascade de Release de l’espace de travail voyage dans la réponse à aggrega/activeRelease, dans son champ trace, plutôt que dans une erreur : un espace de travail qui ne pointe vers aucune Release est un état ordinaire plutôt qu’une requête en échec. C’est de la prose de diagnostic écrite pour qu’une personne la lise, pas une structure à analyser. Affichez-la telle quelle — écrivez-la dans un journal, ou dans un panneau que l’utilisateur peut ouvrir — et n’y appliquez pas de motifs, n’en extrayez pas de valeurs et ne vous branchez pas sur les libellés qu’elle utilise : sa formulation, sa mise en forme et ces libellés suivent la cascade elle-même et changent chaque fois que la cascade change. Un client qui transmet le texte tel quel continue de fonctionner à travers un tel changement ; un client qui en a appris la forme casse.
Voir aussi
- ../schema/other/serve-wire.md — les formes des messages qu’échange ce protocole, générées à partir du schéma publié : l’objet de paramètres de chaque méthode, chaque résultat et chaque charge utile de notification, champ par champ.
- ./aggrega-build.md — la commande build, dont
aggrega/buildexécute aussi le pipeline du compilateur, les contrôles et la résolution des dépendances, de sorte que les deux surfaces écrivent un seul arbre de sortie plutôt que deux. - ./aggrega-version.md — la commande version qu’une extension d’éditeur utilise pour vérifier la compatibilité du daemon.
- ./aggrega-pull.md — le lockfile que lit la surface de dérive du daemon.
- ./aggrega-lint.md — les conventions de publication que le daemon signale sur demande, et à chaque validation une fois
serve.lint_on_validateactivé.
Synopsis
aggrega serve [flags]Description
Run the Aggrega compiler as a long-running service. The daemonreads JSON-RPC 2.0 messages from stdin and writes responses to stdoutunder the aggrega/ method namespace. State (parsed YAML, diagnostics,resolved catalog) holds across requests so IDE clients can issue manycheap operations without re-paying per-invocation startup cost.
The daemon resolves its workspace root through the same path everyaggrega command uses: --workspace-root when set (used as-is, validatedto exist as a directory), otherwise discovery walking upward from thecurrent working directory. A directory anchors the workspace when itholds a .aggrega-config.yaml carrying a workspace: block, or — as afallback — any of .aggrega/, aggregate*.yaml, release*.yaml,manifest*.yaml.
Configuration is the cascade composition of the .aggrega-config.yamlfiles from the workspace root down to the working directory (neareroverrides farther), beneath which the global config file — the one--config names, else the one the AGGREGA_CONFIG environment variablenames, else the default location when a file is there — and thebuilt-in defaults apply.
The daemon honors the aggrega/shutdown JSON-RPC notification for acooperative cross-platform exit: the daemon completes the in-flighthandler if any, refuses new requests with code 1005, and exitscleanly within a 2-second drain budget.
Asking the process itself to stop — an interrupt from the terminal, ora termination request from a supervisor or container runtime — takesthe same path on the same terms: the first request drains the daemonand it exits cleanly, and a second ends the process at once.Options
| Option | Par défaut | Description |
|---|---|---|
--build-on-inspect | false | Exécute l’étape de rendu des artefacts lors de l’inspection d’un graphe IR, afin que les avertissements que aggrega build soulève pendant le rendu apparaissent aussi comme problèmes dans l’éditeur. N’ajoute aucun des contrôles sur lesquels un build s’arrête. Rien n’est écrit sur le disque : aucun artefact rendu, aucun répertoire de sortie, aucun lockfile. Désactivé par défaut, comme aggrega inspect, qui ne soulève pas non plus ce genre d’avertissement. Lorsqu’il est défini, remplace la clé de configuration serve.build_on_inspect. |