Diagnostics JSON Zero : erreurs de compilation structurées pour les agents

La fonctionnalité phare

La fonctionnalité la plus distinctive de Zero n'est pas un morceau de syntaxe. C'est la façon dont le compilateur parle à qui — ou à quoi — lit sa sortie.

Passez un programme cassé dans zero check --json et vous obtenez un flux qu'un agent peut lire directement :

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier",
            "line": 3,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

C'est un petit blob, mais chargé. Décortiquons chaque champ et les choix de conception derrière.

L'anatomie d'un diagnostic

Un diagnostic est un objet structuré qui décrit un problème dans la source. Les champs canoniques :

• code — un identifiant stable (par exemple NAM003). Signifie toujours la même chose, peu importe la version du compilateur.
• message — une description lisible par un humain. La formulation peut changer d'une version à l'autre ; le sens est fixé par code, pas par le message.
• line (et autres champs d'emplacement) — où se trouve le problème.
• repair — métadonnées structurées optionnelles décrivant une correction que le compilateur estime susceptible de résoudre le diagnostic. La forme de ce champ est elle-même documentée et stable.

La forme de premier niveau inclut un booléen ok pour la session dans son ensemble et un tableau diagnostics ; même quand la session réussit, le tableau peut contenir des avertissements ou des notes.

Codes d'erreur stables

Le contrat sur code est la partie la plus susceptible de vous surprendre. NAM003 signifie « identifiant inconnu » aujourd'hui. NAM003 le mois prochain et l'année prochaine signifiera aussi « identifiant inconnu ». Les agents (et les humains) peuvent compter là-dessus.

Ça compte parce que les modèles de langage et l'outillage tendent à mettre en cache ou à mémoriser ce qu'ils ont vu. Si la signification de NAM003 dérivait à chaque version, chaque consultation en cache serait risquée. Épingler le code maintient :

• Les données d'entraînement des agents valides d'une version à l'autre.
• La documentation indexable par code.
• Les pipelines d'outillage stables.

Le message lisible par un humain est libre de changer à mesure que l'équipe affine la formulation. Le code est l'identifiant porteur.

Métadonnées de réparation

Le champ repair, quand il est présent, dit au consommateur quel type de correction le compilateur estime susceptible de fonctionner :

{
    "code": "NAM003",
    "message": "unknown identifier",
    "line": 3,
    "repair": { "id": "declare-missing-symbol" }
}

declare-missing-symbol ici est le type de réparation — l'intention de haut niveau. Pour obtenir les éditions concrètes, appelez zero fix --plan --json. Ça retourne un plan qui inclut le chemin du fichier, les plages d'octets à modifier et le nouveau texte :

{
    "diagnostic": { "code": "NAM003", "line": 3 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

(Les noms de champs et la forme exacte peuvent différer dans la version de votre chaîne d'outils — le principe est « des données structurées, pas de la prose ».)

Un agent qui lit le plan a plusieurs choix :

1. Appliquer les éditions telles quelles.
2. Appliquer les éditions avec des modifications.
3. Rejeter le plan et tendre vers une correction différente.

Dans tous les cas, l'agent opère sur des données structurées au lieu d'essayer d'interpréter une suggestion en anglais. C'est la différence entre les plans de réparation et les « vous vouliez peut-être dire... ? » d'un compilateur classique.

Comment un agent utilise vraiment ça

Une boucle de bout en bout simplifiée qu'un agent pourrait exécuter :

1. Générer ou modifier un fichier Zero.
2. Lancer zero check --json dessus.
3. Si le résultat est { "ok": true, ... }, passer à la suite.
4. Sinon, pour chaque diagnostic :
   • Chercher le code pour comprendre ce qui cloche (avec zero explain ou une table locale).
   • Si un repair est proposé et paraît sûr, appeler zero fix --plan --json pour les éditions.
   • Appliquer (ou simuler) les éditions.
5. Retourner à l'étape 2.

Comparez ça au fait de travailler à partir d'un message en prose : l'agent doit parser de l'anglais, extraire un numéro de ligne probable, deviner le type de correction et inférer le texte d'insertion ou de remplacement exact. Chaque étape est floue. Le chemin JSON remplace chaque étape par une consultation contre un schéma documenté.

Au-delà des erreurs : graphe et taille

--json n'est pas que pour les diagnostics. D'autres commandes exposent des données structurées de la même façon :

• zero graph --json — émet le graphe de dépendances d'un package sous forme de données structurées. Utile pour comprendre ce qui dépend de quoi, et pour les agents qui veulent raisonner sur les sites d'appel avant d'y toucher.
• zero size --json — rapporte la taille sur disque des artefacts compilés, ventilée par cible. Les données sont les mêmes que ce que les humains voient dans zero size, juste parsable.

Ces formes font partie de la conception : à chaque fois que le compilateur a des données utiles, elles sont disponibles en JSON pour que les outils les consomment sans gratter l'écran.

À quoi ressemble le schéma

Les noms de champs et les formes exactes sont documentés dans le dépôt Zero et évolueront tant que le projet est en pré-1.0. Les catégories auxquelles vous pouvez vous attendre :

• Métadonnées de session — ok, version, timing.
• Diagnostics — code, message, emplacement (fichier/ligne/colonne/plages d'octets), sévérité (erreur/avertissement/note), repair optionnel.
• Plans de réparation — quand récupérés, la liste d'éditions structurée.

Si vous construisez de l'outillage contre cette surface, le motif sûr consiste à lire les champs que vous connaissez, à ignorer gracieusement les champs inconnus, et à vous baser sur code pour les décisions comportementales.

Un parcours rapide de bout en bout

Supposez que votre source utilise un identifiant qui n'est pas déclaré :

pub fun main(world: World) -> Void raises {
    check world.out.write(answer())   // 'answer' n'est défini nulle part
}

Lancer zero check --json produit quelque chose comme :

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier 'answer'",
            "line": 2,
            "column": 27,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

zero fix --plan --json retourne l'édition :

{
    "diagnostic": { "code": "NAM003", "line": 2 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

zero fix (sans --plan) applique l'édition sur place, après quoi zero check retourne ok: true. Chaque étape est une transaction discrète et inspectable.

Pourquoi ça compte au-delà des agents

Les mêmes propriétés — sortie structurée, codes stables, plans de réparation — facilitent aussi la vie de :

• Éditeurs et IDEs. Soulignements et ampoules qui agissent sur les identifiants repair plutôt que sur du texte parsé.
• Pipelines de CI. Échecs journalisés avec code pour faciliter le grep et les tableaux de bord.
• Outils de code-mod. Corrections en masse qui ciblent un code, pas un regex sur des messages.

Le système a été conçu en pensant aux agents, mais l'outillage destiné aux humains profite des mêmes bénéfices.

La suite : conception agent-first

Le système de diagnostics est l'exemple le plus concret de la philosophie agent-first de Zero. Le prochain document, conception agent-first, prend du recul vers les principes sous-jacents — petite surface, outillage déterministe, effets explicites — et explique comment chacun gagne sa place.