여러 언어용 네이티브 라이브러리 래퍼를 만드는 코드 생성기 고치고 테스트하기

## 작업별 가이드를 먼저 읽고 생성 파일이 아닌 입력 쪽 고치기 ### 작업별 지침부터 시작하세요 코드를 변경하거나 전문 명령을 실행하기 전에 저장소의 짧은 작업별 가이드를 찾으세요. 포괄적인 개요에서 절차를 다시 구성하지 말고 현재 작업에 맞는 가이드를 읽으세요. 일반적인 가이드는 다음을 다룹니다. - 전체 테스트 모음, 하나의 대상 언어 테스트 모음, 또는 하나의 테스트 사례 실행 - 컴파일러 디버깅, 구문 분석 트리 검사, 메모리 결함 추적 - 사용자 설명서 편집과 구조 검증 - 소스 형식, 주석, 기여 규칙, 커밋 메시지 - 지속적 통합에서만 발생하는 실패 재현 이러한 집중 가이드가 정확한 명령, 옵션 또는 규칙을 제공하면 정본으로 취급하세요. 검색용 별칭이나 심볼릭 링크가 같은 가이드를 여러 도구별 위치에 표시한다면 정본은 하나만 유지하고, 기여자의 플랫폼에서 링크가 올바르게 생성되는지 확인하세요. ### 편집하기 전에 시스템을 이해하세요 이 저장소는 컴파일러형 생성기를 구현합니다. 네이티브 선언과 인터페이스 설명을 읽은 다음, 여러 대상 언어에서 네이티브 라이브러리를 사용할 수 있도록 래퍼를 생성합니다. 이 모델에는 세 가지 실무적 결과가 있습니다. - 생성 파일은 산출물이며 동작을 수정하는 주된 위치가 아닙니다. - 언어 공통 동작은 공유 인터페이스 입력에 두고, 대상별 런타임 검사는 해당 대상 테스트 디렉터리에 두어야 합니다. - 구문 분석, 타입 해석, 소유권, 래퍼 생성에 대한 변경은 보고된 증상이 한 백엔드에만 나타나더라도 여러 백엔드에 영향을 줄 수 있습니다. 저장소 자체의 가이드, 빌드 파일, 테스트를 근거로 사용하세요. 익숙해 보이는 디렉터리 이름이나 다른 프로젝트의 규칙만으로 작업 흐름을 추론하지 마세요. ## CI와 같은 빌드 시스템으로 빌드하고 가장 작은 유효한 테스트 고르기 ### 올바른 소스 형태에서 빌드하세요 지속적 통합이 사용하는 기본 빌드 시스템을 사용하세요. 버전 관리에서 가져온 작업 사본은 설정 파일을 생성하기 위한 초기화 단계가 필요할 수 있지만, 릴리스 압축본에는 해당 파일이 이미 포함될 수 있습니다. 일반적인 순서는 필요할 때 초기화하고, 설정한 다음, 빌드하는 것입니다. 설치 경로 접두사와 선택적 의존성 제어 같은 지원되는 설정 옵션을 유지하세요. 보조 빌드 시스템이 있을 수 있지만 기본 파이프라인의 실패를 진단할 때 알리지 않고 대체하지 마세요. 테스트와 예시는 런타임을 방금 빌드한 라이브러리 디렉터리로 지정하는 미설치 작업 트리용 실행기를 호출할 수 있습니다. 설치된 사본이 아니라 현재 작업 사본을 테스트하도록 이 실행기를 사용하세요. 보조 컴파일러 캐시 구성 요소가 기본 빌드 및 테스트 그래프에 포함된다면 정식 가이드가 실행 범위를 명시적으로 좁히지 않는 한 함께 포함하세요. ### 의미 있는 최소 테스트를 선택하세요 명령을 변경 범위에 맞추세요. - 국소 동작을 반복 확인할 때는 생성 래퍼 테스트 하나를 실행하세요. - 백엔드 동작이 바뀌면 영향을 받는 대상 언어의 전체 테스트 모음을 실행하세요. - 파서, 타입 시스템, 소유권 또는 공통 생성 로직이 바뀌면 공유 테스트 모음을 실행하세요. - 저장소가 지원하는 경우에만 병렬 실행을 사용하세요. - 넓은 범위의 실행에서 첫 실패 시 중단하는 것보다 모든 실패를 수집하는 편이 유용하면 계속 실행 모드를 사용하세요. 테스트 대상 이름은 네이티브 언어 모드, 객체 지향 모드, 다중 모듈 모드처럼 소스 형태를 나타내는 경우가 많습니다. 사례에 맞는 접미사를 사용하고, 오래된 생성 산출물을 새 실패로 판단하기 전에 해당 정리 대상을 실행하세요. ### 자동화에서 사용하는 동일한 경로를 검증하세요 실패가 지속적 통합에서만 발생한다면 저장소가 유지하는 컨테이너 이미지와 실제 설치 스크립트로 실행 환경을 재현하세요. 임시로 만든 환경보다 호스팅 실행 환경을 재현하는 도우미를 우선하세요. 차이를 소스 코드 탓으로 돌리기 전에 의존성 버전, 환경 변수, 빌드 모드, 테스트 대상이 같은지 확인하세요. 버그 수정이나 기능에는 일반적으로 회귀 테스트를 포함해야 합니다. 컴파일러 빌드에 성공했다는 이유만으로 변경이 검증되었다고 주장하지 마세요. 래퍼 생성, 생성 코드의 컴파일, 대상 언어의 런타임 동작은 서로 다른 검사 지점입니다. ## 버그가 시작되는 파이프라인 단계를 찾고 파서를 중첩 호출하지 않기 ### 처리 단계를 순서대로 따르세요 파이프라인을 따라 순서대로 동작을 추적하세요. 1. 전처리기가 인터페이스 입력과 조건부 지시문을 확장합니다. 2. 스캐너가 입력 텍스트를 토큰으로 변환합니다. 3. 파서가 문법을 적용하고 속성을 가진 노드의 트리를 생성합니다. 4. 타입 시스템이 이름, 동등 관계, 템플릿, 변환을 해석합니다. 5. 트리 수준 패스가 이후 단계에 필요한 정보를 추가하거나 정규화합니다. 6. 대상 언어 백엔드가 트리를 순회하고 래퍼 코드를 생성합니다. 실제 상태가 예상 상태에서 처음 벗어나는 단계를 찾으세요. 잘못된 래퍼가 백엔드의 결함을 증명하지는 않습니다. 백엔드가 이전 단계에서 만들어진 잘못된 구문 분석 노드, 타입, 소유권 플래그 또는 변환 규칙을 그대로 반영하고 있을 수 있습니다. ### 모델의 핵심 추상화를 사용하세요 구문 분석 노드는 키-값 객체처럼 동작하며 공유 패스와 언어 백엔드가 순회합니다. 속성이 생성되는 지점과 소비되는 지점에서 각각 검사하세요. 타입 변환 맵은 네이티브 값이 경계를 넘어 대상 언어 값으로 바뀌는 방식을 제어합니다. 변환 동작이 잘못되었다면 생성 텍스트를 수정하기 전에 선택 우선순위와 타입 동등성을 확인하세요. 템플릿 인스턴스화는 같은 타입 동등성 메커니즘에 의존하므로 특수화 매칭과 래퍼 형식화를 분리해 분석하세요. 백엔드에 국한된 수명 주기 우회책을 추가하기 전에 공유 소유권 및 할당 분석을 확인하세요. ### 비재진입 파서 경계를 지키세요 구현이 반대 사실을 입증하지 않는 한 파서는 비재진입이라고 가정하세요. 파서를 감싸는 진입점은 현재 입력 위치, 의미 값, 미리보기를 포함한 전역 파서 상태를 덮어쓸 수 있습니다. 문법 동작 내부에서 이러한 진입점을 절대 재귀 호출하지 마세요. 문법 규칙에서 새 매개변수 목록이나 관련 하위 구문을 만들어야 한다면 중첩 파싱을 시작하지 말고, 진행 중인 파싱 안에서 기존 문법 생성 규칙을 재사용하세요. 해당 문법 기능을 도입한 가장 오래된 언어 표준의 회귀 사례로 변경을 검증하세요. ### 지원되는 디버깅 기능을 사용하세요 저장소에 문서화된 디버그 옵션, 텍스트 또는 구조화 트리 덤프, 디버거 도우미, 실행 래퍼, 기능 선택 변수, 메모리 풀 진단을 사용하세요. 자동화에서만 발생하는 실패라면 계측을 확대하기 전에 자동화 환경을 재현하세요. 진단용 변경은 일시적으로 유지하고, 필요성을 보여 주는 실패 테스트 없이 국소 우회책을 프로덕션 동작으로 바꾸지 마세요. ## 회귀 테스트를 공유 입력과 언어별 스크립트에 나눠 두기 ### 동작을 올바른 계층에 배치하세요 테스트는 일반적으로 생성을 구동하는 공유 인터페이스 입력과 생성된 래퍼를 실행하는 선택적 대상 언어 런타임 스크립트로 구성됩니다. 언어 독립적인 문법과 래퍼 요구 사항은 공유 입력에 두세요. 대상 언어 구문, 런타임 어설션, 언어별 경계 사례는 해당 런타임 스크립트에 두세요. 새 사례는 실제 범위에 맞는 테스트 모음 그룹에 등록하세요. 언어 표준과 연결된 테스트 이름 접두사는 편리한 예시가 사용하는 더 새로운 표준이 아니라 해당 문법 기능을 도입한 가장 오래된 표준을 나타내야 합니다. 기능을 단독으로 확인한 다음 맞는 표준 그룹에 테스트를 배치하세요. ### 실패를 관찰할 수 있게 만드세요 최적화된 런타임 모드에서도 활성 상태를 유지하는 어설션 도우미를 사용하세요. 대상 언어가 최적화 중에 내장 어설션 문을 제거할 수 있다면 회귀 범위를 그 문에 절대 의존시키지 마세요. 실패 시 유용한 값을 보고하는 명시적 동등성, 조건, 예상 예외 도우미를 사용하세요. 테스트 주석은 짧게 유지하고 명백하지 않은 내용만 담으세요. 컴파일러 우회책이나 의미상 함정을 간결한 한 줄로 설명하고 코드가 이미 보여 주는 내용을 되풀이하지 마세요. 회귀 테스트는 수정 전에는 실패하고 수정 후에는 통과해야 하며, 우연히 사용되는 내부 도우미가 아니라 공개 동작을 검사해야 합니다. ### 공유 영향을 검증하세요 파서나 공통 타입 시스템이 변경되었고 영향을 받는 경로가 공유된다면 원래 실패한 백엔드 외의 백엔드도 테스트하세요. 백엔드 전용 동작에서는 근거 없이 실행 범위를 넓히지 마세요. 실질적으로 다른 테스트 설정 사이에는 생성 파일을 정리하고, 보고서에서 생성 실패, 네이티브 컴파일 실패, 런타임 실패를 구분하세요. ## 커밋에 관계없는 변경을 섞지 않고 사용자에게 보이는 변경을 변경 로그에 쓰기 ### 소스와 주석 규칙을 따르세요 관련 없는 코드를 수동으로 정규화하지 말고 저장소의 형식 검사와 포매터를 사용하세요. 확립된 네이티브 언어 주석 스타일, 토큰 인용 방식, 줄 너비, 함수 헤더 규칙을 따르세요. 문법 파일은 새 코드에 더 엄격한 규칙을 적용할 수 있습니다. 해당 규칙을 따르고 프로덕션 파서를 변경하는 동안 관련 없는 리팩터링을 피하세요. 커밋하기 전에 diff에서 생성 파일, 실수로 이루어진 광범위한 치환, 의도한 하위 시스템 밖의 변경을 확인하세요. 커밋 문구는 평이하고 간결하며 정확해야 합니다. 자동화 도구를 공동 작성자로 표시하지 마세요. 프로젝트가 중요한 자동화 지원 공개를 요구한다면 이메일 신원 없이 승인된 지원 트레일러를 사용하세요. ### 사용자에게 보이는 변경을 기록하세요 사용자에게 보이는 모든 버그 수정, 기능, 동작 변경, 경고 변경, 사용 중단 예정 처리는 현재 변경 로그에 항목을 추가해야 합니다. 내부 도우미 이름이나 리팩터링 세부 정보가 아니라 사용자가 관찰하는 내용을 설명하세요. 저장소의 날짜 및 issue 형식을 따르고 새 항목을 예상 순서에 배치하며 호환성 위험을 명시적으로 표시하세요. 관찰 가능한 영향이 없는 순수 내부 변경에는 사용자용 항목이 필요하지 않습니다. ### 개발자 및 사용자 문서를 유지하세요 설명서를 편집할 때 자동 생성 숫자 앵커 대신 안정적이고 설명적인 제목 앵커를 유지하세요. 코드, 대상 언어 예시, shell 세션, 다이어그램에는 문서화된 콘텐츠 클래스를 사용하세요. 문서 간 링크가 안정적인 대상을 가리키게 한 다음 목차 생성기와 문서 검사를 실행하세요. 개발자 문서는 내부 객체 모델, 트리 속성, 타입 시스템, 확장 경로를 설명해야 합니다. 사용자 문서는 지원되는 구문과 관찰 가능한 동작에 집중해야 합니다. 렌더링된 구조와 링크 대상을 모두 검증하세요. 소스 편집에 성공했다는 사실만으로 설명서의 탐색 가능성이 유지되었다고 볼 수는 없습니다.