atlas_lint_easy_explainer.md

hexa-lang 새 방향, 쉽게 풀어쓰기

기술 RFC: RFC-017 (atlas 내장 + strict lint), RFC-018 (직접 codegen), RFC-019 (에러 메시지) 이 문서는 같은 내용을 요리책 비유로 풀어 쓴 일반인용 설명입니다.

---

0. 등장인물 비유

기술 용어	비유
hexa-lang	요리 언어. 요리법(코드)을 적는 방식
atlas.n6	공식 사전 + 표준 레시피집. "이 재료, 이 조리법, 이 법칙" 모두 정리된 한 권의 책
P / C / L 노드	사전 안의 항목 — P는 재료(소금, 물), C는 연결(소금+물=소금물), L은 법칙(가열하면 끓는다)
hexa interp (현 인터프리터)	요리 안내원. 요리법을 한 줄씩 읽어주면서 옆에서 시키는 사람
native 컴파일러	셰프 자체. 요리법을 머릿속에 외워서 바로 만드는 사람
lint	품질 검사관. 요리 시작 전에 재료/단위 점검
정적 내장	사전을 셰프 머릿속에 통째로 넣어두기

---

1. 첫 번째 결정 — "사전을 어디에 둘까?"

지금 상황

atlas.n6이라는 공식 사전이 따로 있습니다. 4.2 MB짜리, 60,760줄, 매일 업데이트됩니다.

지금까지는 요리할 때마다 도서관 가서 사전을 빌려옵니다. 한 번에 약 0.2초가 걸립니다.

한 번이면 0.2초니까 괜찮은데, 100번 반복하면 20초, 5000번이면 17분. 자동 검사(CI)나 코드 편집기(LSP)는 매 키 입력마다 사전을 봐야 해서 사실상 불가능.

세 가지 선택지

선택지	비유	시간
매번 도서관 가기	사전 매번 빌림	0.2초/회 — CI 17분
책상에 사본 두기	mtime cache	0.001초/회 — 빠름
셰프가 통째로 외움	정적 내장	0초 — 거의 즉시

결정

셰프가 사전을 통째로 외운다 (정적 내장).

근데 사전이 매일 바뀌잖아요? → 그러면 매일 셰프를 새로 교육시킵니다 (CI가 매일 컴파일러 자동 재빌드). 일반 요리사들(사용자)은 셰프 새 버전 받으면 자기 요리법도 새로 점검만 하면 됩니다.

---

2. 두 번째 결정 — "안내원 → 셰프"

지금 상황 (인터프리터)

요리법(.hexa 파일)을 적으면, 안내원(hexa interp)이 한 줄씩 읽어주면서 진행합니다.

안내원: "음, 첫 줄이 '소금 1g 넣기' 네요. 넣었어요?"
당신:   "네."
안내원: "이제 두 번째 줄... 어? 이 재료가 사전에 없는데요?"

장점: 즉석에서 고치기 쉬움 단점: 매번 사전을 들춰야 해서 느림. 큰 공장(CI)에서는 안 통함.

새 방향 (native 컴파일러)

요리법을 한 번에 셰프에게 통째로 넘깁니다. 셰프는 머릿속 사전이랑 대조해서

• 재료 빠진 거 있나?
• 단위 안 맞는 거 있나?
• 법칙 위반인가?

다 검사한 다음, 이상 없으면 요리법을 외워서 자동으로 동작하는 로봇으로 만듭니다 (= 실행 가능한 바이너리).

이상이 있으면? 로봇 자체를 안 만듦. 즉, 요리 시작도 못 함.

이건 TypeScript 의 tsc strict 와 같은 모델입니다. "타입 검사 통과 못 하면 그냥 빌드 실패, 실행 자체가 불가능."

---

3. 세 번째 결정 — "검사를 얼마나 빡세게?"

Python처럼 문법 틀리면 즉시 실패하는 정도가 아니라, 사전과 단위까지 다 맞아야 실행됩니다.

검사 사다리 (8단)

단계	무엇을 검사?	비유
S0	문법 (괄호, 세미콜론)	글씨 자체가 읽히나?
S1	사전에 있는 재료인가?	"신선초란?" — 그런 거 사전에 없어요
S2	변수 선언했나?	"그릇 X" 라는데 X가 뭐죠?
S3	타입 맞나?	숫자에 글자 더하기 안 됨
S4	도메인 (음수/양수/정수)?	"사람 −3명"?
S5	단위가 맞나?	"거리 + 시간"? 그런 덧셈 없어요
S6	공식이 맞나? (선택)	E = mc² 이라면서 본문은 E = m+c
S7	수학적 증명? (선택)	Z3 같은 도구로 정식 증명
S8	출처 인용했나?	공식 쓸 때 "아인슈타인의 법칙" 인용 누락

S0~S5, S8은 항상 켬. S6, S7은 사용자가 @verify/@prove 라고 표시한 부분만 켬.

우회 가능한가?

거의 안 됨. 명령줄 옵션으로 끄는 건 없고, 코드에 기한 만료 라벨만 허용:

@allow_unverified("legacy migration", until="2026-06-01")
fn old_thing() { ... }

→ 6월 1일 지나면 자동으로 다시 검사 강제. "급해서 일단 통과시키되, 진짜 곧 고쳐라"라는 의미.

---

4. 네 번째 결정 — "셰프를 어떻게 만들까?"

셰프(=native 컴파일러) 만드는 데 세 가지 길이 있습니다.

후보	비유	장단점
LLVM	거대한 공용 주방 빌려쓰기	강력하지만 무겁고, 우리 사전 인지 어려움
C 변환	일단 C로 번역해서 C셰프에게 넘기기	의존성 사슬, 디버깅 어려움
직접 만들기	우리 주방을 처음부터 짓기	무겁지만 100% 우리 통제

결정: 직접 만들기

이유: hexa-lang의 핵심은 "사전(atlas)과 수식 검증". 외부 도구는 이 정보를 중간에 잃어버림. 우리 도구로 처음부터 끝까지 사전을 인식해야 함.

어떻게 짓나?

요리법이 셰프 안에서 거쳐가는 단계:

1. 요리법 글자 읽기 (lex)
2. 문법 구조로 정리 (parse)
3. 사전과 대조 검사 (resolve, check)  ← 여기서 틀리면 abort
4. 머릿속 단순한 형태로 정리 (HIR/MIR)
5. 손동작 명령으로 변환 (LIR)
6. 실제 동작 가능한 로봇으로 출력 (binary)

크기: 셰프 자체 ≤ 2MB (사전 4.2MB 압축해서 1~2MB로). 외부 도구 의존 0.

셰프를 처음 어떻게 만들지?

닭과 달걀 문제. 셰프를 만들려면 셰프가 필요하잖아요?

해결: 4단계 부트스트랩

1. Stage 0: 지금 있는 안내원(인터프리터)이 셰프 만드는 법(소스코드) 읽고 실행
2. Stage 1: 그 결과물 = 1세대 셰프
3. Stage 2: 1세대 셰프가 자기 자신을 다시 만듦 = 2세대
4. Stage 3: 2세대가 자기 자신을 만든 결과 == 2세대 → 정착

3세대와 2세대가 똑같으면 "안정"이라는 뜻. 이때부터 안내원은 은퇴.

---

5. 다섯 번째 결정 — "에러 메시지를 어떻게 잘 보여줄까?"

좋은 에러 메시지의 모범

• Rust: 코드+위치+화살표+힌트
• TypeScript: 모아 보여주기, 정확한 타입 차이
• Elm: 가장 친절, 예시 동봉
• Python: 짧고 명료

→ hexa는 Rust + Elm 친절함 결합.

보이는 모습

HexaError [HX1042] example/foo.hexa:42:11–28
    let p = P[einstien-mass-energy]
                ^^^^^^^^^^^^^^^^^^^   atlas 노드 없음

    원인: atlas a3f9...c2 에 P 노드 `einstien-mass-energy` 없음
    추천: P[einstein-mass-energy]    (오타 1글자 차이)
    수정: hexa fix --apply HX1042 example/foo.hexa
    설명: hexa explain HX1042

핵심 5요소

1. 에러 코드 (HX1042) — 검색 가능
2. 정확한 위치 — 라인:열, 화살표
3. 원인 — 무엇이 왜 틀렸는지
4. 추천 — "혹시 이걸 의미하셨나요?"
5. 자동 수정 — hexa fix 명령 한 줄로 해결

"hexa-lang이 이걸 빠르게 흡수할 수 있나요?" — 사용자 질문 직접 답

예. 5축으로 가능합니다:

축	의미	비유
A. atlas E 노드	에러도 사전 항목	"실수 사례" 도 사전이 관리
B. catalog가 hexa로 작성	새 에러 = 파일 한 줄	셰프가 자기 실수 노트를 갖고 있음
C. i18n 분리	메시지 텍스트와 로직 분리	한국어/영어 파일만 갈아끼움
D. snapshot 회귀	메시지 변경 자동 감지	실수 노트 바뀌면 알림
E. fix-it API	자동 수정 가능	"이건 1키로 자동 고침" 표시

새 에러 1건 추가 비용: 5~7 파일 수정 / 약 5분.

---

6. 전체 그림 (한 장)

┌─────────────────────────────────────────┐
│  공식 사전 (atlas.n6, 4.2MB, 매일 갱신)  │
│  P 재료 / C 연결 / L 법칙 / E 에러       │
└──────┬──────────────────────────────────┘
       │ 매일 자동 합쳐서
       ▼
┌─────────────────────────────────────────┐
│  셰프 (hexa native 컴파일러)              │
│  머릿속에 사전 통째로 외움 (정적 내장)    │
│  외부 도구 의존 0                         │
└──────┬──────────────────────────────────┘
       │ 사용자 요리법(.hexa)을 받으면
       ▼
┌─────────────────────────────────────────┐
│  검사 8단 (S0~S8)                        │
│  문법/사전/타입/단위/공식/인용 모두 검사 │
│  단 1건 위반 → 빌드 실패, 결과물 X       │
└──────┬──────────────────────────────────┘
       │ 다 통과하면
       ▼
┌─────────────────────────────────────────┐
│  요리 로봇 (실행 바이너리)                │
│  실행 시 사전 다시 열 필요 없음 (0ms)     │
│  단일 파일, 어디서든 실행                 │
└─────────────────────────────────────────┘

---

7. 사용자가 일상에서 만나게 되는 차이

상황	지금 (인터프리터)	새 방향 (native + 정적 내장)
코드 한 번 실행	"잠깐, 사전 좀 볼게요" 0.2초 대기	즉시 시작
100개 파일 검사	20초	거의 즉시
CI 5000개 파일	17분	수초
코드 에디터 자동완성	200ms 지연(체감 명확)	즉시
사전 업데이트 후	즉시 반영	컴파일러 자동 재빌드 한 번 후 반영
다른 사람에게 배포	사전 파일 동봉 필요	단일 바이너리 하나면 끝
에러 났을 때	한 줄짜리 메시지	위치+원인+추천+자동수정

---

8. 잠재적 우려 / 솔직한 트레이드오프

우려	대응
사전 매일 바뀌는데 컴파일러도 매일 새로?	CI가 자동. 사용자는 컴파일러 받기만 함 (Rust deps update 모델)
검사가 너무 빡세서 코드가 안 컴파일됨	기존 코드는 @allow_unverified(until="...") 부여, 점진 마이그레이션
컴파일러 직접 만들기? 너무 큰 일?	단계별 부트스트랩, 1차 타겟은 x86_64-linux + arm64-darwin만
인터프리터 즉석성 잃음	hexa run (인터프리터 모드)은 stage0로 잠시 유지, dev 친화

---

9. 한 줄 요약

사전(atlas)을 셰프(컴파일러) 머릿속에 통째로 넣고, 셰프가 요리법(코드)을 받으면 사전·문법·단위·공식·출처를 다 확인한 뒤 한 건이라도 틀리면 요리 자체를 시작하지 않는다.

이러면 빠르고(런타임 0초), 안전하고(틀린 코드 실행 불가), 자율적(외부 도구 의존 0)인 언어가 됩니다.