해시트리 구축 및 OpenAPI Spec Diff 로직 구현

[toothlessdev]

📎 Related issues

• resolve Implement compute diff with hash tree traversal #16

📦 Scope

• @patchlogr/core
• @patchlogr/cli
• @patchlogr/oas
• @patchlogr/inspector
• @patchlogr/types
• docs, examples
• tests
• ci / cd / infra
• other (아래에 명시)

📌 Summary

• 표준화된 Open API Spec 을 해시(sha256) 트리로 변환
• 변환된 해시트리 순회로 변경사항을 changeSet 에 추가

🔍 Changes

• partitionByTag : swagger 의 tags[0] 기반 파티셔닝
• partitionByMethod : http method 기반 파티셔닝
• diffSpec : base, head 스펙에 대한 SpecChangeSet 반환

⚠️ Impact

• No Breaking Changes
• Breaking Change
• Versioning 영향 있음 (major)
• 내부 리팩토링만 포함

✅ Checklist

• 요구사항 명세 충족
• 테스트 추가 / 수정
• deterministic output 확인

✍️ Todo

• 추후 partitionByTag, partitionByMethod 및 diffSpec 에 대한 문서화 필요
• 파티셔닝 시 메타데이터만 저장하고 해당 해시값에 해당하는 실제 spec 은 외부 blob storage 로 분리하는 로직 필요 (dynamodb, s3, filesystem)

[gemini-code-assist]

Summary of Changes

Hello @toothlessdev, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

이 PR은 Open API Specification(OAS)의 변경사항을 효율적으로 감지하고 추적하기 위한 기반 시스템을 구축합니다. OAS 문서를 해시 기반의 트리 구조로 변환하고, 이 트리 간의 차이를 식별하여 추가, 삭제, 수정, 타입 변경 등의 상세한 변경 내역을 제공하는 diff 로직을 구현했습니다. 이는 향후 OAS 버전 관리 및 변경 로그 생성 기능의 핵심 구성 요소가 될 것입니다.

Highlights

• OAS Spec Diff 로직 구현: 표준화된 Open API Spec을 해시 트리로 변환하고, 이 해시 트리를 순회하여 변경사항을 감지하고 changeSet에 추가하는 핵심 로직이 구현되었습니다. 이는 added, removed, modified, type_changed와 같은 다양한 변경 유형을 식별합니다.
• 해시 트리 구조 및 생성 유틸리티: OAS 스펙을 효율적으로 비교하기 위한 해시 트리 구조가 정의되었으며, createHashedLeaf 및 createHashedNode와 같은 헬퍼 함수를 통해 각 노드와 리프에 SHA256 해시를 부여하여 변경 감지의 기반을 마련했습니다. 기존 HashNode 타입 정의도 간소화되었습니다.
• 파티셔닝 로직 개선: partitionByTag 및 partitionByMethod 함수가 OAS 스펙을 태그 또는 HTTP 메서드 기준으로 파티셔닝하는 로직을 포함하며, 이 과정에서 해시 트리 생성을 위한 새로운 유틸리티 함수들이 활용됩니다.
• 테스트 코드 개선 및 현지화: 새롭게 추가된 diff 로직에 대한 광범위한 테스트 케이스가 추가되었으며, 기존 patchlogr-core 및 patchlogr-oas 패키지의 여러 테스트 파일에서 테스트 설명이 한국어로 번역되어 가독성이 향상되었습니다.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

Test Results

104 tests   104 ✅  1s ⏱️
 20 suites    0 💤
  3 files      0 ❌

Results for commit a02c00b.

♻️ This comment has been updated with latest results.

[gemini-code-assist]

Code Review

안녕하세요. 이번 PR에서 구현하신 해시 트리 기반의 OAS Spec Diff 로직을 잘 살펴보았습니다. 전체적으로 구조가 잘 잡혀있고, 변경 사항을 감지하는 로직이 체계적으로 구현된 점이 인상적입니다. 특히 added, removed, modified, type_changed 등 다양한 시나리오를 고려한 점과, 이를 뒷받침하는 테스트 코드를 충실하게 작성해주신 덕분에 코드의 신뢰성이 높아졌습니다.

몇 가지 개선점을 제안드리고자 합니다. 타입 안정성을 높이기 위한 HashNode 타입 구조 변경, diffNode 함수의 재귀 호출 효율성 개선, 그리고 diffChildNodes 함수 내 Map 초기화 코드 간소화에 대한 의견을 리뷰 코멘트로 남겼습니다. 검토해보시고 더 나은 방향으로 코드를 개선하는 데 도움이 되길 바랍니다.

훌륭한 기여에 감사드립니다!