Zero CLI｜check・run・build・test・fix・explain の使い方

CLI が提供するもの

zero バイナリは、開発ツールチェーンのすべてです。別のパッケージマネージャー、フォーマッター、リンター、テストランナーは存在しません——すべて zero のサブコマンドです。表面を小さく予測可能に保つ、というのがポイントです。

最もよく触るコマンドの短いメニューです。

コマンド	役割
zero check	実行ファイルを生成せずにソースを型検査する。
zero run	1 ステップでコンパイルして実行する。
zero build	ネイティブ実行ファイルにコンパイルする。
zero test	パッケージのテストターゲットを実行する。
zero fix	構造化された修復プランを適用またはプレビューする。
zero explain	診断コードに対する散文の説明を参照する。
zero new	新しいパッケージをスキャフォールドする。
zero --version	ツールチェーンのバージョンを表示する。

これらすべてが --json を受け付け、人間向け整形テキストの代わりに機械可読な出力を出します。

zero check

主力です。zero check はコンパイラーの静的検査——パース、型検査、ケイパビリティとエフェクトの推論、不足インポートの検出——を実行し、コード生成の前で停止します。高速なのは重要で、エージェントやエディタが頻繁に呼び出すからです。

zero check hello.0

クリーンな出力（何も表示されず、終了コードは 0）はファイルが整っていることを意味します。エラーはデフォルトでは人間可読なテキストとして出てきます。--json を付けるとエージェントが消費する構造化形式になります。

zero check hello.0 --json

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

診断の形は JSON 診断 で完全にドキュメント化されています。安定した code フィールドに注目してください——NAM003 はコンパイラーバージョンに関わらず常に「unknown identifier」を意味します。

check には単一ファイルではなくパッケージディレクトリを向けることもできます。

zero check ./my-package

zero.json を読み、ソースツリーを走査し、すべてのターゲットにわたるすべての問題を報告します。

zero run

run は 1 ステップでコンパイルして実行します。小さなプログラムでイテレーションしていて、ディスク上のバイナリを残す必要がないときに最適です。

zero run hello.0

zero build を実行してから生成されたバイナリを呼び出すのと等価ですが、成果物は破棄されます。プログラムからの標準出力は端末の標準出力に転送されます——プログラムの world.out.write の呼び出しが画面に届くわけです。

プログラムに引数が必要な場合は、-- の後ろに渡します。

zero run greet.0 -- Alice

ランタイムは、I/O を公開するのと同じ World ケイパビリティを通じて、プログラムにこれらの引数へのアクセスを与えます。

zero build

成果物が欲しいときは build を使います。

zero build hello.0

コンパイラーはソースファイルの隣にネイティブ実行ファイルを生成します（パッケージで作業している場合はパッケージのビルドディレクトリの下）。他のプログラムと同じように実行できます——Zero バイナリは自己完結しているので、別のランタイムは不要です。

Zero バイナリは小さいです。プロジェクトの設計目標は、自明なプログラムで 10KB 未満の実行ファイルです。これは LLVM ツールチェーンをスキップしてコンパクトなコードパスを直接出力することで実現しています。

zero test

パッケージのテストターゲットを実行します。

zero test

テストは src/ 配下のソースの隣に住み、パッケージの zero.json でテストターゲットとして宣言されます。ランナーがそれらを発見し、それぞれを実行し、pass/fail を出力します。--json を付けると、出力はテストごとに構造化されます——名前、ステータス、所要時間、キャプチャされた診断——エージェントや CI ツール向けに。

Zero パッケージ で、zero.json でテストターゲットを宣言する方法を解説しています。

zero fix

fix は、check --json が生成する修復メタデータを消費します。モードは 2 つです。

zero fix --plan --json   # 構造化プランを表示するだけ、適用はしない
zero fix                 # プランをその場で適用する

プランはおおむね次のような見た目です（形は例示）。

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

発想は、エージェントがプランを取得し、信頼するかどうかを判断し、直接適用するか、より高水準の推論ステップに渡す、というものです。プランはデータです。エージェントは行動するために散文を解釈する必要がありません。

zero explain

explain は診断システムの散文側です。

zero explain NAM003

エラーコードの人間可読な説明——それが何を意味するか、コンパイラーがそれを出す理由、典型的な修正の見た目——を表示します。次の場面で役立ちます。

• 人間がデバッグしていて、インラインメッセージより長い回答が欲しいとき。
• エージェントが訓練データになかった診断コードに当たり、追加のコンテキストが欲しいとき。

コード自体はコンパイラーバージョン間で安定なので、キャッシュされた説明は有効性を保ちます。

zero new

新しいパッケージをスキャフォールドします。

zero new cli hello

これで hello/ ディレクトリが作られ、zero.json マニフェストと初期の src/main.0 が入ります。最初の引数（ここでは cli）はテンプレートを選びます——この場合は実行可能なコマンドラインアプリです。Zero パッケージ でレイアウトを詳しく説明しています。

--json の習慣

ほぼすべてのコマンドが --json をサポートします。Zero まわりのツール、エージェントハーネス、CI パイプラインを構築するなら、デフォルトを JSON 形式にしましょう。その理由は、

• 安定。 スキーマはバージョン管理され、チームはこれをコントラクトとして扱います。
• 完全。 人間出力にはないフィールド（正確なスパン、修復プラン ID、依存グラフデータ）が得られます。
• パース可能。 行番号を抽出するために英語の散文に対する正規表現を書く必要がありません。

人間向けには --json を外しておきましょう——端末では整形テキストの方が欲しい形です。

その他の便利なコマンド

頻度は低めでも、知っておくと役立つコマンドがあります。

• zero graph --json——パッケージの依存グラフを構造化データとして出力します。何が何に依存しているかを把握したり、エージェントが呼び出し箇所について推論したりするのに役立ちます。
• zero size --json——コンパイル済み成果物のディスク上のサイズを、ターゲット別に分けてレポートします。バイナリのフットプリント（Zero の設計目標）を気にするときに役立ちます。
• zero --version——ツールチェーンのバージョンを表示します。チームで作業しているならどこかにピンしておきましょう——Zero は pre-1.0 で、破壊的変更は実際に入ります。

次回: Zero パッケージ

ひとつの .0 ファイルは hello-world には十分です。実プロジェクトでは、zero.json マニフェストと src/ ディレクトリを持つパッケージを使います。Zero パッケージ で、そのスキャフォールド方法と各フィールドを解説します。