Patchlogr v0.1 TODO

🧭 Patchlogr v0.1 TODO

Phase 0. 프로젝트 세팅 (기초)

• 리포지토리 생성
• 패키지 매니저 결정 (pnpm / yarn / npm)
• Node.js 버전 고정 (.nvmrc)
• TypeScript 설정 (tsconfig.json)
• ESLint / Prettier 설정
• 기본 CLI 엔트리 파일 생성 (bin/patchlogr.ts)
• 실행 명령 정의 (patchlogr diff ...)

---

Phase 1. OpenAPI 로딩 & 검증

목표: “OpenAPI 3.0.x 문서를 안전하게 읽는다”

• @apidevtools/swagger-parser 설치
• JSON / YAML 파일 로딩 지원
• $ref dereference 처리
• OpenAPI 버전 검사
  • openapi 필드 존재 여부
  • 3.0.x 아닌 경우 에러 처리
• invalid spec 에러 메시지 정리

✅ 결과물 → loadOpenApi(filePath) → ResolvedOpenAPISpec

---

Phase 2. Canonicalization 표준화 (핵심)

목표: “비교 가능한 표준 구조(Canonical Model) 생성”

2.1 Canonical 타입 정의

• CanonicalKey 타입 정의 (METHOD path)
• CanonicalOperation 인터페이스 정의
• CanonicalSpec (operation map) 정의

---

2.2 Operation 추출

• paths 순회
• HTTP method 필터링 (get/post/put/patch/delete)
• Canonical Key 생성
• operationId 추출
• tags / security 추출

---

2.3 Parameters Canonicalization

• parameter 종류 구분 (path / query / header / cookie)
• parameter 정렬 (name + in 기준)
• required / schema fingerprint 추출

---

2.4 RequestBody Canonicalization

• requestBody 존재 여부 확인
• content-type 순회
• schema fingerprint 생성
• content-type 정렬

---

2.5 Response Canonicalization

• status code 순회
• content-type 순회
• schema fingerprint 생성
• status code 정렬

---

2.6 Schema Fingerprint

• schema → fingerprint 문자열 변환 함수

• 포함 요소

  • type
  • format
  • required
  • enum
  • properties key 목록

• 순서 무관하게 deterministic 하게 생성

✅ 결과물 → canonicalize(openApiSpec) → CanonicalSpec

---

Phase 3. Diff 엔진

목표: “두 CanonicalSpec의 차이를 구조적으로 계산”

• addedOperations 계산

• removedOperations 계산

• modifiedOperations 계산

  • parameters diff
  • requestBody diff
  • responses diff
  • metadata diff

• 변경 이유(reason) 구조화

✅ 결과물 → diffSpecs(oldSpec, newSpec) → DiffResult

---

Phase 4. Breaking Change 판별

목표: “깨질 수 있는 변경을 정확히 분류”

• operation 삭제 → breaking

• method 삭제 → breaking

• path parameter 변경 → breaking

• required 필드 추가 → breaking

• 필드 삭제 → breaking

• type / format 변경 → breaking

• enum 값 제거 → breaking

• response status 제거 → breaking

• breaking flag 계산

• breaking 이유(reason) 수집

---

Phase 5. Semantic Versioning 계산 ⭐️

목표: “이번 변경이 major / minor / patch 중 무엇인지 자동 산출”

5.1 규칙 매핑

• MAJOR 조건 매핑
• MINOR 조건 매핑
• PATCH 조건 매핑
• NONE 조건 처리

---

5.2 우선순위 적용

• major > minor > patch > none
• 이유(reason) 목록 정리

✅ 결과물 → calculateVersionBump(diffResult) → VersioningResult

---

Phase 6. Diff JSON 출력

목표: “머신이 읽을 수 있는 결과물 생성”

• summary 계산

  • added / removed / modified / breaking count

• versioning 결과 포함

• JSON 파일 출력 옵션

• stdout 출력 옵션

---

Phase 7. Markdown Reporter

목표: “사람이 읽을 수 있는 리뷰 결과”

• 변경 요약 섹션
• 권장 버전 bump 표시
• Breaking Changes 섹션
• Operation별 변경 요약
• Markdown 템플릿 정리

---

Phase 8. CLI 완성

• CLI 옵션 정의

  • --base
  • --head
  • --out

• exit code 규칙

  • breaking 있으면 exit 1 (옵션)

• help / usage 문구 작성

---

Phase 9. 테스트 & 안정화

• canonicalization 단위 테스트
• diff 엔진 테스트
• versioning 판정 테스트
• 실제 OAS 샘플 테스트
• deterministic output 검증

---

Phase 10. 문서화

• README 작성
• 사용 예제
• versioning 규칙 설명
• 한계점 명시