Skip to content

fix: report package compatibility train policy - #1291

Merged
kang-heewon merged 2 commits into
trunkfrom
fix/1227-package-compatibility-train
Jul 7, 2026
Merged

fix: report package compatibility train policy#1291
kang-heewon merged 2 commits into
trunkfrom
fix/1227-package-compatibility-train

Conversation

@kang-heewon

@kang-heewon kang-heewon commented Jul 6, 2026

Copy link
Copy Markdown
Member

Fixes #1227.

Summary

  • Defines a shared internal Croco compatibility policy for manifest normalization and package-quality reporting: internal @croco/* ranges stay on workspace:* except checked peer semver exceptions with reason, owner, and compatibility rationale.
  • Exposes the create-croco-app generated Croco version set and makes package-quality:report compare template workspace rows, actual emitted semver ranges, and expected workspace package ranges.
  • Reports compatibility train drift, checked peer exceptions, spine package membership, generated app dependency ranges, and the Changesets fixed/linked decision in the dashboard and release docs.
  • Adds a patch changeset for create-croco-app.

Verification

  • pnpm package-manifests:check
  • pnpm exec vitest run scripts/tests/normalize-packages.spec.ts scripts/tests/package-quality-report.spec.ts --reporter=verbose
  • pnpm --filter create-croco-app exec vitest run src/tests/croco-ranges.spec.ts --reporter=verbose
  • pnpm package-quality:report
  • pnpm check
  • pnpm typecheck
  • pnpm test
  • pnpm --filter create-croco-app build
  • pnpm changeset-required:check -- --base origin/trunk --head HEAD
  • git diff --check
  • Pre-push hook passed: auto-changeset, repo-wide test (225/225 Turbo tasks), and repo-wide typecheck (224/224 Turbo tasks).

Self-review gates

  • Correctness/regression: PASS. The report now fails stale generated app ranges with generatedAppRangeDriftCount, and focused tests cover pass, stale-range failure, and legacy exception schema rejection.
  • API/compatibility/release: PASS. create-croco-app gets additive exported range-set metadata and a patch changeset; fixed/linked groups stay intentionally empty and documented.
  • Maintainability/minimality: PASS. The old manifest-range validation moved into one shared helper used by both gates, with no new dependencies.

Review and QA

  • Code review: PASS, no findings after the generated-app version-set audit was wired into the report.
  • QA: PASS. Full local gates and pre-push test/typecheck completed successfully.
  • Residual risk: CI will rerun the full remote gate set on this PR.

Summary by CodeRabbit

  • New Features

    • 호환성 트레인 점검이 추가되어, 생성 앱과 내부 패키지 간 버전 범위 일치 여부를 더 쉽게 확인할 수 있게 됐습니다.
    • 패키지 품질 보고서에 호환성 상태와 실패 원인이 포함됩니다.
  • Bug Fixes

    • 내부 의존성 범위 예외 검증이 강화되어, 잘못된 예외 설정이나 오래된 형식이 더 명확하게 실패합니다.
    • 생성 앱의 의존성 범위가 기준과 어긋날 때 감지 정확도가 높아졌습니다.
  • Documentation

    • 릴리스 및 품질 검사 기준이 업데이트되어, 호환성 검증 절차와 요구사항이 더 분명해졌습니다.

@coderabbitai

coderabbitai Bot commented Jul 6, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

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

Next review available in: 26 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

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: ASSERTIVE

Plan: Pro

Run ID: b573e118-07da-418c-8f0d-2953c5d47185

📥 Commits

Reviewing files that changed from the base of the PR and between 85fc67b and 2769f23.

📒 Files selected for processing (5)
  • packages/create-croco-app/src/helpers/catalog-spine.ts
  • packages/create-croco-app/src/tests/croco-ranges.spec.ts
  • scripts/alpha-release-smoke.mts
  • scripts/package-quality-report.mts
  • scripts/tests/package-quality-report.spec.ts
📝 Walkthrough

Walkthrough

내부 @croco/* 의존성 range 정책과 peer 예외 스키마를 공용 모듈(internal-croco-compatibility-policy.mjs)로 분리하고, normalize-packages.mjs가 이를 위임하도록 리팩터링했다. create-croco-app은 테스트된 생성 앱 Croco 버전 세트를 노출하고, package-quality-report.mts는 호환성 트레인 상태(내부 range drift, peer 예외, 생성 앱 의존성, fixed/linked 결정)를 리포트/대시보드에 통합했다. 관련 릴리스 문서도 갱신되었다.

Changes

Compatibility Train Policy & Reporting

Layer / File(s) Summary
내부 peer 의존성 range 정책 모듈 신설
scripts/internal-croco-compatibility-policy.mjs
예외 JSON 읽기/검증, semver compatibility range 파싱, 정책 위반 검사, 예외 키/포맷 유틸 함수를 신규 정의.
normalize-packages.mjs 정책 모듈 위임
scripts/normalize-packages.mjs, scripts/tests/normalize-packages.spec.ts
기존 인라인 구현을 제거하고 정책 모듈 함수를 import하여 사용하며, 테스트 예외 스키마를 reason/owner/compatibilityRationale 필드로 갱신.
create-croco-app 버전 세트 노출
packages/create-croco-app/src/helpers/croco-ranges.ts, packages/create-croco-app/src/tests/croco-ranges.spec.ts, .changeset/generated-app-compatibility-train.md
GeneratedAppCrocoVersionSet 타입/함수를 추가하고, 스파인 카탈로그 대비 템플릿 의존성 정합성 테스트를 추가.
package-quality-report 호환성 트레인 통합
scripts/package-quality-report.mts, scripts/tests/package-quality-report.spec.ts
CompatibilityTrainReport 산출 로직, 대시보드 섹션, 게이트 요약, CLI 실패 조건을 추가.
릴리스/대시보드 문서 갱신
RELEASING.md, docs/release/croco-1.0-spine.md, docs/release/package-entrypoint-contract.md, docs/release/package-quality-dashboard.md
Compatibility Train Policy 섹션, 게이트 매핑, 예외 메타데이터 요구사항을 문서화.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI as package-quality-report CLI
  participant Policy as internal-croco-compatibility-policy.mjs
  participant CrocoRanges as croco-ranges.ts
  participant Report as CompatibilityTrainReport

  CLI->>Policy: readInternalPeerDependencyRangeExceptions
  CLI->>CrocoRanges: getGeneratedAppCrocoVersionSet
  CLI->>Report: 내부 range drift, peer 예외, 생성 앱 비교, fixed/linked 결정 종합
  Report-->>CLI: pass/fail 상태 + 대시보드 마크다운
  CLI->>CLI: status === "fail" 시 process.exit(1)
Loading

Possibly related PRs

  • croco-dev/framework#1194: 동일한 내부 @croco/* 의존성 range 정책과 checked peer 전용 예외 스키마를 normalize-packages.mjs 및 관련 정책 로직을 통해 구현/강제한다.

Suggested reviewers: ddarkr

🚥 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 제목이 패키지 호환성 트레인 정책 보고/검증 추가라는 주요 변경을 간결하게 요약합니다.
Linked Issues check ✅ Passed 내부 범위 workspace:* 정책, 예외 메타데이터, 생성 앱 버전셋, 리포트/문서 반영, spine fixed/linked 결정 명시가 모두 반영됩니다.
Out of Scope Changes check ✅ Passed 변경은 정책 검증, 리포트, 문서, 테스트, changeset에 한정되며 제공된 목표 밖의 별도 기능 추가는 보이지 않습니다.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/1227-package-compatibility-train

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

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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 85fc67b837

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/package-quality-report.mts Outdated
@github-actions

github-actions Bot commented Jul 6, 2026

Copy link
Copy Markdown

📊 Benchmark Results

✅ All benchmarks passed

Benchmark p75 Threshold Baseline vs Baseline Status Notes
CrocoApp constructor 8.2μs 30.0ms 8.2μs +0.9% -
CrocoApp lambdaHandler (10 controllers) 290.8μs 50.0ms 258.4μs +12.5% -
Lambda cold-start simulation 476.0μs 80.0ms 418.1μs +13.9% -
Lambda cold-start with headers 385.5μs 80.0ms 369.7μs +4.3% -
Lambda cold-start with binary body 363.2μs 80.0ms 339.1μs +7.1% -
Lambda cold-start with query params 317.8μs 80.0ms 301.3μs +5.5% -
Lambda cold-start with authorizer context 316.3μs 80.0ms 299.8μs +5.5% -
Lambda cold-start realistic scenario 313.5μs 80.0ms 299.2μs +4.8% -
EventBusConfig.start (10 handlers) 1.5μs 10.0ms 1.4μs +5.6% -
EventPublisher.publishNow single event 1.8μs 2.0ms 1.7μs +6.5% -
DefaultHandlerResolver.resolve × 10 0.1μs 5.0ms 0.1μs +0.0% -
Container.get singleton (cold) 83.5μs 5.0ms 70.3μs +18.9% -
Container.register × 50 components 3.5ms 10.0ms 3.2ms +9.0% -
Container.validate (50 components) 3.9ms 20.0ms 3.4ms +14.8% -
Container.get singleton (warm) 1.7μs 500.0μs 1.6μs +3.7% -
TelemetryRuntime.init (lambda preset) 2.0μs 200.0ms 1.1ms -99.8% -
lambdaPreset config creation 1.4μs 2.0ms 1.4μs -0.7% -

Updated: 2026-07-07T02:42:41.932Z · Commit: 5e23e48

@kang-heewon

Copy link
Copy Markdown
Member Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 7, 2026

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 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 `@packages/create-croco-app/src/tests/croco-ranges.spec.ts`:
- Around line 48-65: `normalizeCatalogSpinePackageName` is duplicated across the
test and two script files, so the catalog naming rule can drift out of sync.
Extract this logic into a shared helper or export it from one existing location
and have `croco-ranges.spec.ts`, `scripts/alpha-release-smoke.mts`, and
`scripts/package-quality-report.mts` reuse that single implementation. Keep the
existing behavior for `create-croco-app` and scoped package names, and update
the call sites to import the shared symbol instead of redefining it.

In `@scripts/package-quality-report.mts`:
- Around line 1669-1678: `formatCompatibilityTrainPeerExceptionRows` is omitting
the `compatibilityRationale` field from the peer exception table. Update the row
rendering for `CompatibilityTrainReport.peerExceptions` to include
`exception.compatibilityRationale`, and make sure the matching table header in
the same report output also adds a `Compatibility rationale` column so the
rendered columns stay aligned.
🪄 Autofix (Beta)

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: ASSERTIVE

Plan: Pro

Run ID: b684f19c-3caa-4f73-a009-bd95fb1ad6c7

📥 Commits

Reviewing files that changed from the base of the PR and between 8bf1a44 and 85fc67b.

📒 Files selected for processing (12)
  • .changeset/generated-app-compatibility-train.md
  • RELEASING.md
  • docs/release/croco-1.0-spine.md
  • docs/release/package-entrypoint-contract.md
  • docs/release/package-quality-dashboard.md
  • packages/create-croco-app/src/helpers/croco-ranges.ts
  • packages/create-croco-app/src/tests/croco-ranges.spec.ts
  • scripts/internal-croco-compatibility-policy.mjs
  • scripts/normalize-packages.mjs
  • scripts/package-quality-report.mts
  • scripts/tests/normalize-packages.spec.ts
  • scripts/tests/package-quality-report.spec.ts

Comment thread packages/create-croco-app/src/tests/croco-ranges.spec.ts Outdated
Comment thread scripts/package-quality-report.mts
@kang-heewon
kang-heewon merged commit a6fadf7 into trunk Jul 7, 2026
9 checks passed
@kang-heewon
kang-heewon deleted the fix/1227-package-compatibility-train branch July 7, 2026 03:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[package-manifests] Define Croco compatibility train and internal dependency range policy

1 participant