test(api): prevent silent v1 OpenAPI breaking changes

[seonghobae]

Objective

Advance issue #315 with a deterministic v1 compatibility gate so repository-owned OpenAPI changes cannot silently remove an existing operation, rename its operationId, or remove an advertised response status without an explicit version/baseline decision.

Test-first state

This Draft intentionally starts RED at exact test-only commit 163645e8db30e17737ff91818fcccd043deb5507, directly based on protected main 55d7ae8647208e301f282350f076eeddaba61d11. The new script regression imports the not-yet-existing compatibility checker and requires a checked-in v1 baseline, so Buyer-readiness script tests must fail at that exact missing implementation boundary before the narrow checker is added.

Scope

Compatibility checker, immutable v1 baseline manifest, and focused script tests only. It does not change the public OpenAPI document, controllers, DTOs, runtime version negotiation, generated clients, naruon integration, or release schema provenance. It is path-disjoint from #316, #337, and #379.

Acceptance

Observe exact-head RED -> add the smallest offline checker and baseline -> exact-head script/CI verification -> Security/SAST/fuzz where emitted -> current reviews/threads/live-base refetch. Keep Draft until exact-head GREEN evidence exists. Independent non-author approval remains a separate protected-merge gate.

Summary by CodeRabbit

• 새로운 기능

  • OpenAPI v1 호환성 기준선에 분석, 변환, 뷰어 및 아티팩트 링크 관련 API 경로를 추가했습니다.
  • API 작업 식별자와 허용 응답 상태를 기준으로 호환성을 확인할 수 있습니다.

• 버그 수정

  • API 작업 삭제, 식별자 변경, 응답 상태 삭제와 같은 호환성 저하를 자동으로 감지합니다.
  • 새로운 작업이나 응답 상태가 추가되는 경우는 정상적인 변경으로 처리합니다.

[coderabbitai]

Warning

Review limit reached

@seonghobae, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 41 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0f4bef22-6c0d-48d7-8126-a71668db0bda

📥 Commits

Reviewing files that changed from the base of the PR and between e9f8b10 and dbd535b.

📒 Files selected for processing (2)

• scripts/openapi_v1_compatibility_contract.py
• scripts/test_openapi_v1_compatibility_contract.py

📝 Walkthrough

Walkthrough

OpenAPI v1 호환성 기준선에 API 작업 정보를 추가했습니다. YAML 명세를 수집하고 작업, operationId, 응답 상태 코드의 삭제 및 변경을 검사하는 스크립트와 회귀 테스트를 추가했습니다.

Changes

OpenAPI v1 호환성

Layer / File(s)	Summary
기준선 및 호환성 판정 로직 scripts/openapi_v1_compatibility_baseline.json, scripts/openapi_v1_compatibility_contract.py	분석, 변환 작업, 뷰어, 아티팩트 링크 API의 작업과 응답 상태 코드를 기준선에 추가했습니다. YAML에서 작업 정보를 수집하고, 크기 제한과 호환성 위반 판정을 구현했습니다.
호환성 회귀 테스트 scripts/test_openapi_v1_compatibility_contract.py	작업 정보 수집, 작업 삭제, operationId 변경, 응답 삭제를 검증합니다. 응답 및 작업 추가와 저장된 기준선의 유지도 검증합니다.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 v1 OpenAPI 호환성 검사를 추가하여 호환성 변경을 방지하는 PR의 주요 목적을 정확하고 간결하게 설명합니다.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/openapi-v1-compatibility-gate-main-20260811

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/openapi_v1_compatibility_contract.py`:
- Around line 32-82: Update collect_operations to parse the OpenAPI document
structurally as YAML instead of relying on exact indentation and raw string
formats, while preserving extraction of HTTP method, path, operationId, and
response keys. Ensure valid quoted paths, inline operationId comments, and
anchored responses values are handled correctly, and add regression tests
covering these formatting variants.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6994b3cc-c4ea-4703-bcde-83d6b8084ae0

📥 Commits

Reviewing files that changed from the base of the PR and between 55d7ae8 and e9f8b10.

📒 Files selected for processing (3)

• scripts/openapi_v1_compatibility_baseline.json
• scripts/openapi_v1_compatibility_contract.py
• scripts/test_openapi_v1_compatibility_contract.py