Diagnostica JSON in Zero: errori strutturati per gli agenti

La funzionalità principale

La caratteristica più distintiva di Zero non è un elemento della sintassi. È il modo in cui il compilatore parla con chiunque, persona o programma, legga il suo output.

Passa un programma con errori a zero check --json e ottieni un flusso di dati che un agente può leggere direttamente:

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

È un blocco piccolo ma denso. Analizziamo ogni campo e le scelte di design che ci stanno dietro.

Anatomia di una diagnostica

Una diagnostica è un oggetto strutturato che descrive un problema nel sorgente. I campi principali:

• code: un identificatore stabile (per esempio NAM003). Significa sempre la stessa cosa, qualunque sia la versione del compilatore.
• message: una descrizione leggibile. La formulazione può cambiare tra le versioni; il significato è fissato da code, non dal messaggio.
• line (e altri campi di posizione): dove si trova il problema.
• repair: metadati strutturati facoltativi che descrivono una correzione che secondo il compilatore risolverebbe la diagnostica. Anche la struttura di questo campo è documentata e stabile.

La struttura di primo livello include un booleano ok per l'esecuzione nel suo insieme e un array diagnostics; anche quando l'esecuzione riesce, l'array potrebbe contenere avvisi o note.

Codici di errore stabili

Il contratto su code è la parte che più probabilmente ti sorprenderà. NAM003 oggi significa "identificatore sconosciuto". NAM003 il mese prossimo e l'anno prossimo significherà ancora "identificatore sconosciuto". Agenti (e persone) possono contarci.

Questo conta perché i modelli linguistici e gli strumenti tendono a memorizzare o salvare ciò che hanno visto. Se il significato di NAM003 cambiasse a ogni versione, ogni ricerca salvata sarebbe inaffidabile. Fissare il codice mantiene:

• Validi tra una versione e l'altra i dati di addestramento degli agenti.
• La documentazione indicizzabile per codice.
• Stabili le pipeline degli strumenti.

Il message leggibile è libero di cambiare man mano che il team migliora la formulazione. Il code è l'identificatore su cui si regge tutto.

Metadati di correzione

Il campo repair, quando c'è, dice a chi legge che tipo di correzione secondo il compilatore funzionerebbe:

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

declare-missing-symbol qui è il tipo di correzione, cioè l'intenzione di alto livello. Per ottenere le modifiche vere e proprie, chiama zero fix --plan --json. Restituisce un piano che include il percorso del file, gli intervalli di byte da modificare e il nuovo testo:

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

(I nomi esatti dei campi e la struttura possono variare nella tua versione della toolchain: il principio è "dati strutturati, non prosa".)

Un agente che legge il piano ha alcune possibilità:

1. Applicare le modifiche così come sono.
2. Applicare le modifiche con qualche variazione.
3. Rifiutare il piano e cercare un'altra correzione.

In ogni caso, l'agente lavora su dati strutturati invece di cercare di interpretare un suggerimento in inglese. È questa la differenza tra i piani di correzione e i suggerimenti "forse intendevi ...?" di un compilatore tipico.

Come lo usa davvero un agente

Un ciclo semplificato dall'inizio alla fine che un agente potrebbe eseguire:

1. Generare o modificare un file Zero.
2. Eseguire zero check --json su quel file.
3. Se il risultato è { "ok": true, ... }, passare oltre.
4. Altrimenti, per ogni diagnostica:
   • Cercare il code per capire cosa non va (con zero explain o con una tabella locale).
   • Se viene offerto un repair che sembra sicuro, chiamare zero fix --plan --json per ottenere le modifiche.
   • Applicare (o simulare) le modifiche.
5. Tornare al passo 2.

Confrontalo con il lavorare su un messaggio in prosa: l'agente deve interpretare l'inglese, estrarre un probabile numero di riga, indovinare il tipo di correzione e dedurre il testo esatto da inserire o sostituire. Ogni passaggio è approssimativo. Il percorso JSON sostituisce ogni passaggio con una ricerca su uno schema documentato.

Oltre gli errori: grafo e dimensioni

--json non serve solo per la diagnostica. Altri comandi espongono dati strutturati allo stesso modo:

• zero graph --json: emette il grafo delle dipendenze di un pacchetto come dati strutturati. Utile per capire cosa dipende da cosa, e per gli agenti che vogliono ragionare sui punti di chiamata prima di toccarli.
• zero size --json: riporta la dimensione su disco degli artefatti compilati, suddivisa per target. Sono gli stessi dati che le persone vedono con zero size, solo in formato analizzabile.

Queste strutture fanno parte del design: ogni volta che il compilatore ha dati utili, li rende disponibili in JSON perché gli strumenti possano usarli senza dover estrarre testo dallo schermo.

Com'è fatto lo schema

I nomi dei campi e le strutture esatte sono documentati nel repository di Zero e cambieranno finché il progetto è pre-1.0. Le categorie che puoi aspettarti:

• Metadati dell'esecuzione: ok, version, tempi.
• Diagnostica: code, message, posizione (file/riga/colonna/intervalli di byte), gravità (errore/avviso/nota), repair facoltativo.
• Piani di correzione: quando vengono richiesti, l'elenco strutturato delle modifiche.

Se stai costruendo strumenti su questa interfaccia, lo schema sicuro è leggere i campi che conosci, ignorare con eleganza i campi sconosciuti e basare le decisioni di comportamento su code.

Un rapido esempio dall'inizio alla fine

Supponi che il tuo sorgente usi un identificatore non dichiarato:

pub fun main(world: World) -> Void raises {
    check world.out.write(answer())   // 'answer' non è definito da nessuna parte
}

Eseguire zero check --json produce qualcosa del genere:

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

zero fix --plan --json restituisce la modifica:

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

zero fix (senza --plan) applica la modifica sul posto, dopodiché zero check restituisce ok: true. Ogni passaggio è una transazione separata e ispezionabile.

Perché conta anche al di là degli agenti

Le stesse proprietà, cioè output strutturato, codici stabili e piani di correzione, semplificano la vita anche a:

• Editor e IDE. Sottolineature e lampadine che agiscono sugli ID di repair invece che su testo interpretato.
• Pipeline di CI. Errori registrati con il loro code, facili da cercare con grep e da mostrare nelle dashboard.
• Strumenti di code-mod. Correzioni in blocco che puntano a un codice, non a un'espressione regolare sui messaggi.

Il sistema è stato progettato pensando agli agenti, ma gli strumenti rivolti alle persone ottengono gli stessi vantaggi.

Prossimo passo: design agent-first

Il sistema di diagnostica è l'esempio più concreto della filosofia agent-first di Zero. La prossima pagina, design agent-first, torna a guardare il quadro generale dei principi di fondo, cioè superficie piccola, strumenti deterministici ed effetti espliciti, e spiega come ciascuno si guadagna il suo posto.