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

aggrega explain

Expliquer la condition d’arrêt que nomme un code

Synopsis

aggrega explain <code>

Description

Explain the halting condition a code names.
A halting diagnostic opens with the category the failure is attributable to and the condition's short code — the letter E and four digits, as in [CATALOG_ERROR E0209]. That short code is the one to pass here; it is fixed once a condition is published, so a code quoted out of an old report still names the same condition.
aggrega explain E0209
The descriptive code is accepted too — the hyphenated one naming the condition in words, which a structured diagnostic carries as a field of its own. A condition's two codes name the same condition and reach different readers, so either is a code you may be holding, and the condition above is registered under recipe-values-mapping-requires-source:
aggrega explain recipe-values-mapping-requires-source
Every condition is declared inside this binary, so the identifiers and the sentence are reported without a network or a cache. The published reference supplies the walk-through of the authoring fix for every condition, and nothing else is resolved against it. It is read from the documentation bundle published for this version of aggrega on the default registry — or, where none is published for it, the newest one published for an earlier version — kept in the cache every project on this machine shares, acquired on first use when that cache holds no copy this workspace's signature check admits. Where it cannot be acquired, the condition is still reported and the reason the walk-through is missing is stated.
A number that named a condition and no longer does is reported as retired, with what it named, so a code quoted from an old report is never answered with a different condition.

Fonctionnement

Un build qui s’arrête affiche un en-tête entre crochets nommant la catégorie à laquelle l’échec est imputable et le code court de la condition — la lettre E suivie de quatre chiffres :

[CATALOG_ERROR E0209] Recipe: valuesMapping requires source ...

aggrega explain E0209 transforme ce code en la condition qu’il nomme et en la marche à suivre pour corriger la rédaction :

Terminal window
aggrega explain E0209

La réponse s’ouvre sur les deux identifiants de la condition et la phrase fixe par laquelle commencent ses diagnostics, puis reproduit l’entrée qui explique ce qui cause la condition et ce qu’il faut changer — la même entrée que celle publiée dans fatal-halts.md.

Le code à passer

L’un ou l’autre des deux codes de la condition est accepté, car chacun vous parvient sur une interface différente.

Le code court est celui qu’affiche un terminal, et c’est celui à utiliser lorsque vous n’avez que la sortie affichée. Un numéro est attribué une fois puis figé, de sorte qu’un code court collé dans un rapport il y a un an nomme toujours la condition qu’il nommait alors.

Le code descriptif est celui avec des traits d’union qu’un diagnostic structuré porte dans un champ à part, et sur lequel un programme se branche. Il nomme la condition en toutes lettres et ne porte aucun préfixe, de sorte qu’il reste figé même lorsque le compilateur est réorganisé autour de lui. Si c’est celui que vous avez sous la main, passez-le à la place — la condition ci-dessus est enregistrée sous recipe-values-mapping-requires-source :

Terminal window
aggrega explain recipe-values-mapping-requires-source

Les deux codes d’une condition nomment la même condition, donc les deux graphies obtiennent une réponse identique. Le code court est comparé sans tenir compte de la casse, puisque c’est une valeur que vous lisez sur un écran et que vous ressaisissez.

sentinels.md présente les trois identifiants que porte une condition et quand utiliser chacun.

D’où vient la réponse

Toute condition que ce binaire déclare obtient sa réponse du binaire. Ses deux codes et la phrase par laquelle s’ouvrent ses diagnostics sont déclarés dans le compilateur, si bien que cela ne nécessite ni réseau, ni cache, ni configuration.

Un code que ce binaire ne déclare pas est recherché dans la référence publiée. Un plugin signale un arrêt en choisissant une condition que déclare le compilateur, si bien qu’aucune condition n’est déclarée ailleurs. La référence publiée, sentinels.md, liste toutes les conditions que déclare le produit, et elle peut avoir été publiée pour une version différente du binaire que vous exécutez — de sorte qu’un code cité dans un rapport produit avec une version plus récente ou plus ancienne peut quand même y être résolu.

La marche à suivre est elle aussi de la documentation publiée, lue depuis fatal-halts.md. Les deux pages proviennent du bundle de documentation, conservé une fois par machine dans le cache que partagent tous les projets Aggrega, une copie par registre et par version — voir aggrega cache. Le bundle lu est celui publié pour la version d’aggrega que vous exécutez ; lorsqu’aucun n’est publié pour cette version, c’est le plus récent publié pour une version antérieure — le même choix que fait aggrega scaffold --example, de sorte que les deux ne lisent jamais une documentation différente. Un code que la référence d’une version antérieure ne contient pas peut nommer une condition déclarée depuis ; il est donc refusé comme indéterminé plutôt que comme un code qui ne nomme rien, et le refus indique la version dont la référence a été lue. Votre workspace décide de quel registre provient le bundle, à savoir son registre par défaut, et si une copie déjà présente sur la machine peut être lue : avant qu’une page ne soit servie, les signatures conservées à côté de la copie sont de nouveau vérifiées selon le contrôle de signature de votre workspace pour ce registre, le même contrôle auquel est soumise une récupération du bundle. Ce contrôle s’exécute aussi hors ligne. Là où il épingle une clé ou une racine de confiance, il ne lit que celles-ci ; là où il n’épingle ni l’une ni l’autre, comme le contrôle intégré du hub officiel, il vérifie par rapport à la racine de confiance publique de Sigstore, qu’un workspace hors ligne ne peut pas récupérer — hors ligne, il vérifie donc par rapport à la racine de confiance qu’une récupération en ligne antérieure sur cette machine a laissée sous .sigstore dans votre répertoire personnel, et ne récupère rien. Lorsque la machine n’a aucune copie, ou aucune que votre contrôle admet, la commande en acquiert une selon ce contrôle, une seule fois, et lit ensuite depuis le cache. La même copie fournit la documentation qu’un assistant lit via aggrega mcp et les explications qu’un éditeur affiche via aggrega serve.

Trois réponses méritent d’être reconnues, car chacune attend de vous quelque chose de différent.

Une condition encore sans entrée. Les codes et la phrase sont indiqués, et une note précise que la page des conditions d’arrêt ne contient aucune marche à suivre pour cette condition. Chaque condition reste listée dans sentinels.md.

Aucune documentation disponible. Pour une condition que déclare le compilateur, les codes et la phrase sont toujours indiqués et une note nomme le bundle et la version qui n’ont pas pu être lus. Pour un code que ce binaire ne déclare pas, il ne reste rien pour répondre, donc le code est refusé — et le refus indique que la référence n’a pas pu être lue, car sans elle un code d’une autre version ne peut pas être distingué d’une faute de frappe, et laisse les deux corrections possibles : corriger le code, ou obtenir la documentation. La cause habituelle est un workspace épinglé hors ligne, ou un workspace qui n’a jamais atteint son registre. Lorsque la machine détient une copie que le contrôle de signature de votre workspace n’admet pas — une copie récupérée par un autre projet avec un réglage plus souple, ou une copie qu’un workspace hors ligne ne peut pas vérifier parce que cette machine n’a jamais récupéré la racine de confiance publique par rapport à laquelle son contrôle vérifie — la note indique que la copie a été refusée plutôt qu’absente, et pourquoi. Lorsqu’aucun bundle n’est publié pour votre version et que le plus récent antérieur est dans un format que cette version d’aggrega ne lit plus — une version candidate exécutée avant la publication de sa propre documentation, par exemple — la note indique les deux en une seule phrase :

hub.aggrega.ai/docs/aggrega-docs publishes no documentation bundle for 0.9.1-rc.1, and the newest earlier one, 0.8.11, is in a format this version of aggrega no longer reads, so the walk-through is not shown here; every condition, including the ones a provider declares, is published at aggrega-docs/language-reference/errors/sentinels.md, and the walk-through of each authoring fix at aggrega-docs/language-reference/errors/fatal-halts.md

Un numéro retiré. Un numéro qui nommait une condition et ne la nomme plus obtient une réponse le signalant comme retiré, avec ce qu’il nommait, plutôt que comme un code qui n’a jamais existé — et il n’obtient jamais en réponse une condition différente, car un numéro retiré n’est pas réattribué.

Exemples

Expliquer un code tiré directement d’un build en échec :

Terminal window
aggrega build --release release.yaml || aggrega explain E0209

Expliquer un code sur lequel un programme a fait une correspondance :

Terminal window
aggrega explain plugin-value-not-representable

La même réponse depuis un assistant

Un assistant IA connecté via aggrega mcp accède à cette même explication via l’outil explain-error. Donnez-lui le texte du diagnostic plutôt qu’un code seul — un assistant détient ce que le build a affiché — et lorsque ce texte s’ouvre sur un code court, la réponse porte la condition, la phrase par laquelle s’ouvrent ses diagnostics et la marche à suivre publiée pour la correction, composées de la même manière que la réponse ci-dessus. Elle porte aussi le code descriptif, afin que l’assistant puisse se brancher sur celui-ci plutôt que sur la formulation d’un message, ainsi que l’adresse à laquelle la condition est publiée.

Tout ce que les sections ci-dessus disent d’une marche à suivre manquante s’y applique aussi : une condition pour laquelle la page ne documente aucune entrée, et un workspace qui ne peut pas lire la documentation, laissent chacun la condition avec une réponse accompagnée d’une note indiquant de quel cas il s’agit. Un numéro retiré y obtient aussi une réponse le signalant comme retiré, avec ce qu’il nommait, de sorte qu’un assistant à qui l’on remet un ancien diagnostic apprend que le numéro n’est plus utilisé au lieu d’être envoyé vers une page traitant d’autre chose. L’interface de l’assistant obtient la documentation une fois à l’ouverture de la session, de sorte qu’une explication lit ce qui est déjà en cache.

Le daemon répond à la même question pour un éditeur, à partir d’un code plutôt que d’un diagnostic. Les trois sont une seule explication sous trois rendus, et non trois réponses qui se trouvent concorder.