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"를 의미합니다. 다음 달과 내년에도 NAM003은 같은 것을 의미할 거예요. 에이전트와 사람 모두 그것을 의지할 수 있습니다.

언어 모델과 도구는 본 것을 캐싱하거나 기억하는 경향이 있기 때문에 이게 중요해요. 만약 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 저장소에 문서화되어 있고, 프로젝트가 1.0 이전인 동안 진화할 것입니다. 예상할 수 있는 분류는:

• 실행 메타데이터 — ok, version, 타이밍.
• 진단 — code, message, 위치(파일/줄/열/바이트 범위), 심각도(에러/경고/노트), 선택적 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 파이프라인. 손쉬운 grep과 대시보드를 위한 code로 로깅되는 실패.
• 코드 모드 도구. 메시지에 대한 정규식이 아니라 코드를 타겟으로 하는 대량 수정.

시스템은 에이전트를 염두에 두고 설계되었지만, 사람용 도구도 같은 이점을 얻습니다.

다음 글: 에이전트 우선 설계

진단 시스템은 Zero의 에이전트 우선 철학을 가장 구체적으로 보여주는 예입니다. 다음 문서 에이전트 우선 설계에서는 작은 표면, 결정론적 도구, 명시적 효과 같은 근본 원칙들과 각각이 어떻게 자리를 얻는지로 다시 줌아웃합니다.