레이어가 있는 이미지 파일을 데이터 손실 없이 읽고 쓰는 라이브러리 만들기

## 작업에 필요한 의존성만 설치하고 프로젝트 명령으로 작업하기 코드를 변경하기 전에 기여자 문서를 읽는다. 관련 없는 런타임에서 도구를 직접 실행하지 말고 저장소의 환경 관리자와 작업 명령을 사용한다. 작업에 필요한 의존성 그룹만 설정한다. - 파싱과 시험에는 기본 개발 의존성을 설치한다. - 합성이나 래스터화가 관련되면 선택적 렌더링 그룹을 추가한다. - 문서를 빌드할 때만 문서화 그룹을 포함한다. - 새로운 런타임과 운영 체제의 일부 조합에서는 선택적 과학 계산 또는 그리기 패키지를 사용할 수 없다고 예상한다. 표준 명령을 사용해 다음을 수행한다. - 컴파일된 확장 모듈과 배포 산출물을 빌드한다. - 커버리지를 포함한 전체 시험 모음을 실행한다. - 노드 식별자로 단일 시험을 실행한다. - 특정 동작을 측정할 때는 커버리지 없이 시험을 실행한다. - 린트 검사, 형식 검사, 정적 타입 검사를 실행한다. - HTML 문서를 빌드하고 문서에 명시된 산출 디렉터리를 확인한다. 선택적 렌더링 의존성을 핵심 파싱 요구사항으로 취급하지 않는다. 의존성이 없는 상태에서 선택적 작업이 요청되면 명확한 설치 방법을 안내한다. ## 저수준 이진 읽기·쓰기와 사용자용 API 나누기 저수준 이진 파싱과 고수준 사용자 API를 분리한다. 저수준 계층은 다음을 수행한다. - 사양에 따라 원시 이진 형식을 읽고 쓴다. - 헤더, 레코드, 태그 블록, 디스크립터, 이미지 리소스, 마스크, 채널, 압축 데이터를 모델링한다. - 명시적인 `read(fp)` 및 `write(fp)` 직렬화 메서드를 제공한다. - 아직 해석할 수 없는 알 수 없는 데이터를 보존한다. 고수준 계층은 다음을 수행한다. - 저수준 문서 구조를 사용하기 편한 인터페이스로 감싼다. - 평면 이진 레코드에서 사용자에게 보이는 객체 트리를 재구성한다. - 계층 유형, 효과, 마스크, 렌더링, 문서 작업을 제공한다. - 계약에서 허용하는 경우 데이터에 접근할 때까지 비용이 큰 파싱을 미룬다. 내부 코드는 저수준의 구체적인 정의를 그 정의가 선언된 모듈에서 가져와야 한다. 공개 사용자는 지원되는 패키지 내보내기를 사용해야 한다. 호환성상 이유가 없다면 저수준 표현의 세부 사항을 공개 메서드에 노출하지 않는다. ## 파일 구역을 순서대로 읽고 쓰며 알 수 없는 데이터 남기기 구역 순서, 길이, 시그니처, 숫자 너비를 파일 형식 계약의 일부로 취급한다. 일반적인 계층형 이미지 파일은 순서대로 이어지는 다섯 구역으로 구성된다. 1. 시그니처, 버전, 크기, 채널, 색상 모드를 포함하는 고정 크기 파일 헤더. 2. 인덱스 팔레트 같은 색상 모드 데이터. 3. 색상 프로필, 안내선, 미리보기 같은 이미지 리소스. 4. 계층 레코드, 채널 데이터, 태그 블록을 포함하는 계층 및 마스크 정보. 5. 평면화된 합성 이미지 데이터. 사양에서 요구하는 경우 26바이트와 같은 고정 헤더 크기를 검증한다. 구역은 순서대로 읽고 쓴다. 메모리 안에서 다루기 편한 객체를 기준으로 경계를 추론하지 않는다. 호출자가 크기 계산을 검증할 수 있도록 직렬화 메서드에서 기록한 바이트 수를 반환한다. 알 수 없는 페이로드는 버리지 말고 왕복 과정에서 바이트로 보존한다. ## 평면 레코드 목록에서 레이어 그룹 다시 만들기 형식이 계층 구조를 평면 목록으로 저장한다면, 인접 관계만 가정하지 말고 명시적인 경계 레코드를 해석한다. 그룹 시작 및 그룹 종료 표식을 인식하고 스택이나 그에 준하는 검증된 상태 머신로 부모-자식 관계를 재구성한다. 최소한 다음 항목을 시험한다. - 그룹 밖의 일반 레코드. - 여러 자식을 포함한 하나의 그룹. - 중첩 그룹. - 빈 그룹. - 잘못되었거나 균형이 맞지 않는 경계 표식. - 원래 레코드 순서의 보존. 직렬화를 위해 평면 저수준 레코드 목록을 유지하면서 고수준 API에서는 트리를 제공한다. 트리 재구성 과정에서 관련 없는 이진 레코드를 변경하지 않는다. ## 태그 블록을 레지스트리로 추가하고 미지원 블록은 그대로 두기 이진 구조에 클래스 수준 읽기와 인스턴스 수준 쓰기를 포함한 공통 기본 계약을 부여한다. 작은 기본 요소를 재귀적으로 조합해 복잡한 구조를 만든다. 타입이 지정된 데이터 클래스 기능을 다음 항목에 일관되게 사용한다. - 자동 생성 초기화 함수. - 필드 검증. - 타입 힌트. - 통제된 표현. - 필요한 경우 예측 가능한 튜플 또는 시퀀스 변환. 검증기를 타입 주석과 일치시키고, 연속 호출 또는 클래스 인식 생성자에는 동일 인스턴스 반환 타입을 사용한다. 확장 가능한 태그 블록에는 다음 원칙을 적용한다. - 고정 너비 태그 키와 연결된 페이로드를 사용한다. - 레지스트리를 통해 알려진 태그를 처리기 클래스에 대응시킨다. - 타입이 지정된 데이터를 읽기 전에 해당 태그가 있는지 확인한다. - 지원하지 않는 블록은 나중에 다시 기록할 수 있도록 온전하게 유지한다. - 공개 편의 접근과 내부 레코드 접근을 분리한다. 충실하게 다시 기록할 수 없는 바이트를 소비하는 처리기는 등록하지 않는다. ## 압축과 픽셀 계산을 빠르게 하면서 대체 경로는 깨뜨리지 않기 최적화하기 전에 성능에 민감한 경로를 측정한다. 비용이 큰 압축이나 압축 해제에는 사용할 수 있는 경우 컴파일된 코덱을 쓰되, 순수 언어로 작성한 올바른 대체 구현을 유지한다. 지연 파싱이 의미를 보존하는 경우 마스크, 효과, 채널 데이터에 지연 로딩을 사용한다. 처리량을 높일 수 있다면 대규모 픽셀 및 혼합 모드 계산에 배열 벡터화를 사용한다. 모든 최적화는 다음을 보존해야 한다. - 이진 산출물 호환성. - 오류 동작. - 결정론적 결과. - 최적화되지 않은 대체 구현. - 컴파일된 의존성이나 선택적 의존성을 사용할 수 없는 환경에 대한 지원. 최적화 구현과 대체 구현을 동일한 시험 데이터에 적용해 검증한다. 속도를 높이기 위해 결과를 몰래 바꾸지 않는다. ## 읽기·쓰기·다시 읽기 테스트로 변경을 확인하고 타입 힌트 붙이기 시험 구성을 패키지 구조와 대응시키고, 저수준 이진 시험과 고수준 API 시험을 분리한다. 대표적인 이진 시험 데이터를 전용 디렉터리에 보관하고 여러 파일을 매개변수화해 시험한다. 왕복 검증을 주요 불변 조건으로 사용한다. 1. 이진 파일을 읽는다. 2. 통제된 필드를 수정한다. 3. 파일을 쓴다. 4. 결과를 다시 읽는다. 5. 의도한 변경과 관련 없는 데이터의 보존을 검증한다. 새 함수의 모든 시그니처에 적절한 타입 힌트를 추가한다. 데이터 클래스 검증기를 주석으로 지정한 타입과 일치시킨다. 자신이 속한 클래스의 인스턴스를 반환하는 메서드에는 프로젝트의 호환 타입을 사용한다. 개발 중에는 범위를 좁힌 시험을 실행하고, 완료 전에는 관련 전체 시험 모음, 린트 검사, 형식 검사, 타입 검사를 실행한다. 커버리지 비율만 정확성의 증거로 사용하지 말고 커버리지 변화를 검토한다. ## 자동화된 절차로 출시하고 지원하지 않는 기능은 분명히 밝히기 최종 버전, 사전 출시 버전, 출시 후 버전 형식을 포함해 프로젝트에 문서화된 버전 관리 표준에 따라 출시 버전을 선택한다. 이전 태그 이후의 변경 사항을 새 버전 제목 아래 변경 기록에 요약한다. 자동 태그 지정에 필요한 정확한 출시 브랜치 패턴을 사용한다. 주 브랜치를 대상으로 출시 요청을 열고 승인된 후에만 병합한다. 설정된 자동화가 병합된 정확한 커밋에 태그를 지정하고, 배포 파일을 빌드하고, 호스팅된 출시 항목을 만들고, 패키지 레지스트리에 게시하게 한다. 출시 작업 절차가 태그 지정을 담당한다면 수동 태그를 만들지 않는다. 자동화 자격 증명에는 후속 작업 절차를 실행하는 데 필요한 최소 권한만 부여하고 절대 노출하지 않는다. 기능이 작동한다고 주장하기 전에 다음과 같이 문서화된 한계를 확인한다. - 글꼴 엔진이 없을 때의 텍스트 렌더링. - 지원되거나 지원되지 않는 조정 작업. - 구현된 계층 효과의 범위. - 내장 객체의 추출과 편집의 차이. - 알 수 없는 데이터를 해석하지 않고 보존하는 동작. 지원하지 않는 동작을 몰래 근사하지 말고 명시적으로 밝힌다. 마지막으로 실행한 시험, 실행하지 않은 선택적 경로, 호환성 위험, 요청한 변경에 영향을 주는 한계를 보고한다.