Zero の JSON 診断｜エージェント向け構造化コンパイラーエラー

看板機能

Zero の最も特徴的な機能は、構文の一片ではありません。コンパイラーが、誰——あるいは何——が出力を読んでいてもそれに語りかける、その語り方です。

壊れたプログラムを zero check --json に通すと、エージェントが直接読めるフィードが返ってきます。

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

小さいけれど中身の詰まった塊です。フィールドと、その背後にある設計判断をひとつずつ見ていきましょう。

診断の解剖

診断は、ソース上のひとつの問題を記述する構造化オブジェクトです。標準的なフィールドは次の通りです。

• code——安定した識別子（例: NAM003）。コンパイラーバージョンに関わらず常に同じ意味です。
• message——人間可読な説明。バージョンで言い回しが変わる場合があります。意味はメッセージではなく code で固定されます。
• line（および他の位置フィールド）——問題のある場所。
• repair——任意の構造化メタデータで、診断を解消すると思われる修正を記述します。このフィールドの形自体もドキュメント化され安定しています。

トップレベルの形には、実行全体に対する ok ブーリアンと diagnostics 配列が含まれます。実行が成功した場合でも、配列には警告や注意が含まれることがあります。

安定したエラーコード

code に関するコントラクトは、最も意外に感じる部分かもしれません。NAM003 は今日「unknown identifier」を意味し、翌月も翌年も「unknown identifier」のままです。エージェント（と人間）はそれを頼りにできます。

これが重要なのは、言語モデルやツールが、見たものをキャッシュしたり記憶したりしがちだからです。NAM003 の意味がリリースごとにドリフトすると、キャッシュされた参照はすべて不安全になります。コードを固定することで次が保たれます。

• エージェントの訓練データがバージョンをまたいで有効。
• ドキュメントがコードでインデックス可能。
• ツールパイプラインが安定。

人間可読な message は、チームが言い回しを改善するにつれて自由に変更できます。荷重を担う識別子は code です。

修復メタデータ

repair フィールドが存在するとき、コンパイラーが効くと考える修正の 種類 を消費者に伝えます。

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

ここでの declare-missing-symbol は修復の 種類——高水準の意図です。実際の編集を取得するには zero fix --plan --json を呼びます。これはファイルパス、変更するバイト範囲、新しいテキストを含むプランを返します。

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

（正確なフィールド名と形はお使いのツールチェーンのバージョンで異なる場合があります——原則は「散文ではなく構造化データ」です。）

プランを読むエージェントには選択肢がいくつかあります。

1. 編集をそのまま適用する。
2. 編集を修正して適用する。
3. プランを拒否し、別の修正を取りに行く。

どの場合も、エージェントは英語の提案を解釈しようとするのではなく、構造化データに対して動作します。これが、修復プランと、典型的なコンパイラーの「もしかして…？」のヒントとの違いです。

エージェントは実際にこれをどう使うか

エージェントが回しそうな、簡略化したエンドツーエンドのループです。

1. Zero ファイルを生成または変更する。
2. それに対して zero check --json を実行する。
3. 結果が { "ok": true, ... } なら、次に進む。
4. そうでない場合、各診断に対して、
   • code を参照して何が悪いかを把握する（zero explain またはローカルテーブルで）。
   • repair が提示されて安全そうなら、編集のために zero fix --plan --json を呼ぶ。
   • 編集を適用する（あるいはシミュレートする）。
5. 手順 2 に戻る。

散文メッセージから作業する場合と比べてみてください。エージェントは英語をパースし、それらしい行番号を抽出し、修正の種類を推測し、正確な挿入や置換のテキストを推論する必要があります。各ステップがあいまいです。JSON のパスは、各ステップをドキュメント化されたスキーマに対するルックアップに置き換えます。

エラーを超えて: グラフとサイズ

--json は診断専用ではありません。他のコマンドも同じ形で構造化データを公開します。

• zero graph --json——パッケージの依存グラフを構造化データとして出力します。何が何に依存しているかを把握したり、エージェントが触る前に呼び出し箇所を推論したりするのに役立ちます。
• zero size --json——コンパイル済み成果物のディスク上のサイズを、ターゲット別に分けてレポートします。zero size で人間が見るのと同じデータですが、パース可能です。

これらの形は設計の一部です。コンパイラーが有用なデータを持つときは常に、画面スクレイピングなしにツールが消費できる JSON として利用可能になっています。

スキーマの見た目

フィールド名と正確な形は Zero リポジトリでドキュメント化されており、プロジェクトが pre-1.0 のうちは進化していきます。期待できるカテゴリは次の通りです。

• 実行メタデータ——ok、version、タイミング。
• 診断——code、message、位置（ファイル/行/列/バイト範囲）、重大度（error/warning/note）、任意の repair。
• 修復プラン——取得時の、構造化された編集リスト。

この面に対してツールを構築するなら、知っているフィールドを読み、未知のフィールドを優雅に無視し、振る舞いの判断は code をキーにする、というのが安全なパターンです。

クイックなエンドツーエンドの例

ソースが宣言されていない識別子を使うとします。

pub fun main(world: World) -> Void raises {
    check world.out.write(answer())   // 'answer' はどこにも定義されていない
}

zero check --json の出力はおおむね次のようになります。

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

zero fix --plan --json は編集を返します。

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

zero fix（--plan なし）はその場で編集を適用し、その後 zero check は ok: true を返します。各ステップは独立した、検査可能なトランザクションです。

エージェントを超えた重要性

同じ性質——構造化された出力、安定したコード、修復プラン——は、次の人たちにも生活を楽にします。

• エディタと IDE。 repair ID に基づいて動く波線や電球。テキストをパースする代わりにそれを使う。
• CI パイプライン。 code でログ収集してダッシュボード化しやすい失敗。
• コードモッドツール。 メッセージへの正規表現ではなく、コードをターゲットにする一括修正。

このシステムはエージェントを念頭に設計されましたが、人間向けのツールも同じ恩恵を受けます。

次回: エージェント・ファースト設計

診断システムは、Zero のエージェント・ファースト哲学の最も具体的な例です。続くドキュメント エージェント・ファースト設計 は、原則の側にズームアウトします——小さな表面、決定論的なツール、明示的なエフェクト、そしてそれぞれがその場所を獲得する理由を扱います。