Partition canonical api spec output

[toothlessdev]

📎 Related issues

• resolve Partition canonical api spec output #11
• https://www.toothlessdev.com/posts/CS/DataStructure/content-addressable-store.html

📦 Scope

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

📌 Summary

• 표준화된 api spec 을 key strategy 별로 파티셔닝해서 저장, 조회, 비교 효율성을 개선하는 전략 도입
• 파티셔닝시에 operationKey 만 참조하고, 추후 chunk 단계에서 파일시스템에 저장하면서 manifest, metadata 저장

🧠 Context

• @patchlogr/oas 에서 openapi 문서를 canonical spec 으로 변환
• 이때 표준화된 스펙을 하나의 json 형태로 저장, 로드, 비교
  • diff 실행시 전체 spec 을 매번 로드 및 비교 해야함
  • oas 규모가 커질수록 diff 비용 증가
  • 중복제거 정규화 및 캐싱하기 어려움
• ui 로 보여줄때 swagger 에서는 tag[0] 를 기반으로 분류 하기에 tag, domain 별 파티셔닝 전략 채택

Strategy	Key
by Operation	GET /pets, POST /users/:id
by Tag/Domain	Pets, User, Billing
by Path Prefix	/api/v1/pets/*
by Method	GET, POST

⚠️ Impact

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

✅ Checklist

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

[github-actions]

Test Results

16 tests   16 ✅  0s ⏱️
 5 suites   0 💤
 2 files     0 ❌

Results for commit dc6ab81.

♻️ This comment has been updated with latest results.

[toothlessdev]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a new partitioning strategy for canonical API specifications, which is a valuable improvement for enhancing the efficiency of storing, retrieving, and comparing OpenAPI specs. The changes include new utility functions for stable stringification and hashing, along with partitioning logic based on HTTP methods and tags. While the overall approach is sound, there are a few areas that could be improved for correctness and maintainability, particularly regarding the stableStringify utility and the tag-based partitioning logic.

[Copilot]

Pull request overview

This PR introduces a partitioning strategy for canonical API specifications to improve storage, retrieval, and comparison efficiency as OpenAPI documents scale. The approach partitions operations by different strategies (tag, method, path prefix) rather than storing everything as a single JSON blob.

Changes:

• Added utility functions for stable JSON stringification and SHA256 hashing to support deterministic operation hashing
• Implemented two partitioning strategies: partitionByTag (groups by first tag with fallback to DEFAULT) and partitionByMethod (groups by HTTP method)
• Removed "type": "module" from package.json and added @types/node dependency to support Node.js crypto module

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
packages/patchlogr-core/src/utils/stableStringify.ts	Utility to stringify JSON with sorted keys for deterministic output
packages/patchlogr-core/src/utils/createHash.ts	Utility to generate SHA256 hashes from strings
packages/patchlogr-core/src/utils/tests/stableStringify.test.ts	Unit tests for stable stringification
packages/patchlogr-core/src/partition/partition.ts	Type definitions for partitions and partitioned specs
packages/patchlogr-core/src/partition/partitionByTag.ts	Implementation of tag-based partitioning strategy
packages/patchlogr-core/src/partition/partitionByMethod.ts	Implementation of HTTP method-based partitioning strategy
packages/patchlogr-core/src/partition/tests/partitionByTag.test.ts	Tests for tag-based partitioning
packages/patchlogr-core/src/partition/tests/partitionByMethod.test.ts	Tests for method-based partitioning
packages/patchlogr-core/package.json	Updated module type and dependencies
yarn.lock	Added @types/node dependency

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.