문법 오류와 UNKNOWN 읽기

Gooo의 실패 메시지를 읽을 때 가장 먼저 볼 것은 무엇을 확인했고, 무엇은 아직 확인하지 못했는가입니다.

문법이 틀렸다는 관측과, 검증에 필요한 입력이 없다는 상태는 다릅니다. 둘 다 다음 단계로 진행하지 못할 수 있지만 해결 방법까지 같지는 않습니다. Gooo는 이 차이를 소스 위치, 검증 범위, 보존된 증거로 설명하는 방향으로 개발되고 있습니다.

1. 먼저 작은 프로그램을 검사하기

설치한 CLI에서는 다음처럼 소스를 검사합니다.

gooo check examples/billing/main.gooo

설치와 정상 예제는 시작하기에서 이어집니다. 아래 예제는 사용법을 보여주는 정상 프로그램이 아니라, 문법 오류를 읽기 위한 의도적인 반례입니다.

package invalid
namespace invalid

unknown Thing

이 입력을 임시 프로젝트의 examples/billing/main.gooo에 넣은 실험에서는 다음 진단이 남았습니다.

examples/billing/main.gooo:4:1-4:8: error parse.unexpected-token: expected entity, activity, policy, or binding

메시지는 세 부분으로 읽으면 됩니다.

부분	알려주는 것	다음 행동
파일과 4:1-4:8	문제가 관측된 소스 범위	해당 입력의 4행을 연다
parse.unexpected-token	파서가 인식한 오류 종류	선언 문법을 확인한다
expected entity, activity, policy, or binding	이 위치에서 허용되는 선언 종류	표현하려던 의미에 맞는 선언을 선택한다

이 메시지가 unknown Thing을 자동으로 entity Thing으로 바꾸라는 뜻은 아닙니다. 파서는 허용된 문법을 알지만, 사용자가 어떤 의미를 선언하려 했는지까지 이 오류만으로 결정할 수는 없습니다.

2. 틀린 입력과 부족한 증거를 구분하기

아래 표는 문법 왕복 검증기의 구조화된 보고서를 읽는 법입니다. 모든 Gooo 명령이 같은 JSON 형식을 반환한다는 뜻은 아닙니다.

보고서에서 관측한 상태	의미	해서는 안 되는 해석
PASS	고정된 해당 검사의 조건을 만족했다	언어 전체나 실제 서비스가 완성되었다
FAIL_CLOSED + EXACT + SYNTAX_ROUNDTRIP_MISMATCH	확인 가능한 입력에서 구체적인 불일치를 찾았다	증거가 없어서 막연히 기다리는 상태다
FAIL_CLOSED + LOWER_RESOLUTION + SYNTAX_ROUNDTRIP_EVIDENCE_UNKNOWN	필요한 입력이나 연결을 충분히 확인하지 못했다	원래 프로그램의 의미가 틀렸다고 증명했다

FAIL_CLOSED는 다음 단계를 허용하지 않는다는 뜻이지, 모든 경우에 같은 원인이라는 뜻이 아닙니다.

구체적인 문법 반례라면 소스와 진단을 따라갑니다. 증거 부족이라면 레지스트리, 대상 입력, 개념 산출물의 연결부터 복원합니다. 두 경우 모두 오류를 성공으로 바꾸거나 검사 대상을 줄여 통과시키는 것이 해결은 아닙니다.

3. 실제 반례는 무엇을 보존하는가

소스가 연결된 문법 반례 실험에서는 정상으로 등록된 billing 입력 하나를 위의 잘못된 문법으로 바꿨습니다. 변경은 원본 저장소가 아니라 별도 임시 입력에서 수행했습니다.

검증 흐름은 다음과 같습니다.

정상 입력과 고정된 검사 정의
    → 임시 입력의 문법 한 곳 변경
    → 변경된 입력에서 개념 산출물 다시 생성
    → 문법 검증 생산자가 실패 보고서 저장
    → 재실행이 같은 실패 바이트 생성
    → 소비자가 그 보고서를 성공으로 채택하지 않음

기존 실험 원본에서 확인된 관측은 다음과 같습니다.

관측 항목	정확한 범위
검사 정의	기존 문법 코퍼스 60개를 유지
결과	만족 59개, 불만족 1개, 미해결 0개
구체적인 불만족	billing의 4행 문법 진단
생산자 / 재실행 / 소비자 종료 코드	1 / 1 / 1
첫 보고서와 재실행 보고서	같은 바이트
입력 연결	변경된 입력에서 만든 개념 산출물과 변경하지 않은 레지스트리 사용

59/60은 Gooo의 완성률도, 이 변경의 개선 점수도 아닙니다. 정상 입력 하나를 의도적으로 깨뜨렸을 때 그 한 곳을 놓치지 않았다는 제한된 관측입니다. 같은 바이트가 다시 나왔다는 사실은 재현성이지, 독립적인 의미 증명이나 사용자 효용의 증거는 아닙니다.

원본은 Actions 실행과 상세 산출물에서 추적할 수 있습니다. 이 기록은 실험 커밋 020bcaddabfb2199624b04d280369138c45b518f에 속합니다. 입력 보고서의 0으로 채운 head는 명시적으로 합성한 식별자이며 실제 저장소 커밋의 내용이라고 주장하지 않습니다.

해당 실험의 기능 검증 성공과 PR의 전체 승인 여부는 별개입니다. 이후 커밋의 상태는 PR에서 확인해야 하며, 예전 실행을 새 커밋의 합격 증거로 재사용할 수는 없습니다. Actions 산출물은 보존 기한이 있을 수 있습니다.

4. 실패하면 어디부터 확인하는가

실패가 생긴 곳	먼저 확인할 것	다음 작업
문법 분석	정확한 파일, 위치, 오류 코드	소스가 표현하려는 선언과 문법을 맞춘다
입력과 증거의 연결	입력 식별자, 레지스트리, 개념 산출물	빠진 입력을 제공하거나 변경된 입력에서 다시 생성한다
변환 후보 생성	지원하지 못한 변환 조건과 보존 의무	지원 범위를 좁혀 설명하거나 변환기를 확장한다
소비자 검증	보고서가 속한 입력과 현재 입력의 차이	실제 현재 입력에서 다시 검증한다
CI 승인 경계	기능 검사와 별도로 실패한 승인 조건	승인 증거를 확인한다. 기능 성공을 승인으로 대신하지 않는다

변환기가 지원하지 못하는 코드라고 해서 원래 프로그램이 잘못된 것은 아닙니다. 예를 들어 호출의 부수 효과를 보존할 수 있는지 증명하지 못했다면, 그 사실을 설명하고 변환을 보류해야 합니다. 이 경계는 소스 변환과 효과에서 더 자세히 설명합니다.

5. 증거가 생기면 주장은 사라지는가

주장의 기록을 지우는 대신, 어떤 입력과 조건에서 지지되었거나 반박되었는지를 연결하는 것이 중요합니다.

• 소스가 바뀌면 예전 판정이 새 소스까지 자동으로 설명하지 않습니다.
• 보고서를 저장했다고 해서 실패가 성공으로 바뀌지 않습니다.
• UNKNOWN을 해소하려면 부족했던 근거를 채워 같은 조건으로 다시 판단해야 합니다.
• 반례를 발견했다면 누락 증거와 섞어 감추지 않고, 구체적인 반례를 보존해야 합니다.

이 연결이 개발 과정의 provenance입니다. 사람이 문제를 고치는 일, 에이전트가 후보를 생성하는 일, 시스템이 후보를 기각하는 일 모두 무엇을 근거로 다음 상태로 이동했는지 남겨야 합니다. 다만 모든 도구가 이미 하나의 통일된 오류·원인 API를 제공하는 것은 아닙니다. 실제 지원 범위와 실험 중인 설계를 구분해서 읽어 주세요.

더 깊이 읽기

• 테스트와 증거 재사용: 같은 검사를 다시 실행해야 하는 경계
• Provenance와 결정: 주장, 실행, 산출물, 결정의 관계
• 고정 목표로 정책 선택: 후보가 자기 평가 기준을 바꿔 통과하지 못하게 하는 실험
• 개발자 경험 설계: 요약에서 원인과 원본으로 내려가는 문서 구조
• 현재 상태와 지원 범위: 구현된 기능과 아직 보장하지 않는 것