fix: enforce internal Croco package ranges

[kang-heewon]

Fixes #1148.

Summary

• Enforces workspace:* for actual internal @croco/* workspace references across dependencies, devDependencies, peerDependencies, and optionalDependencies, including private workspace manifests.
• Adds a checked peer-only exception registry for intentional internal semver peer ranges, requiring an exact package/dependency/range match, a semver compatibility range, and a non-empty published compatibility rationale.
• Normalizes @croco/frontend-react so its internal @croco/meta-vite dev/peer references use workspace:*, and documents the publish-time policy.

Verification

• COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm exec vitest run scripts/tests/normalize-packages.spec.ts --config vitest.config.ts - passed, 15 tests.
• COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm package-manifests:check - passed, 110 checked, 2 skipped, 0 modified.
• COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm exec oxlint scripts/normalize-packages.mjs scripts/tests/normalize-packages.spec.ts - passed.
• COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm exec oxfmt --check scripts/normalize-packages.mjs scripts/tests/normalize-packages.spec.ts - passed.
• COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm changeset-required:check -- --base origin/trunk --head HEAD - passed, no publishable package behavior changes detected.
• COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm check - passed.
• git diff --check and git diff --cached --check - passed.

Self-review gates

• Correctness/regression: PASS. The manifest gate now fails unreviewed internal semver drift across all dependency sections, ignores @croco/* names that are not workspace packages, covers private manifests, and rejects malformed, non-peer, non-semver, duplicate, and unused exceptions.
• API/security/compatibility/release: PASS. Runtime APIs and dependencies are unchanged; source peer manifests use workspace:* based on pnpm pack/publish rewriting, with a checked exception path for future intentional public semver peers.
• Maintainability/minimality: PASS. The rule lives in the existing package manifest validator, uses no new dependency, and tests the new policy through the existing normalize-packages fixture harness.

Review and QA

• Independent code review: REQUEST_CHANGES on non-semver peer exceptions and private package bypass; both fixed, then APPROVE.
• Independent verifier: PASS for issue acceptance criteria and validation evidence.

Notes

• Local commit and push used LEFTHOOK=0 after the equivalent focused tests, manifest gate, repository check, changeset gate, lint, format, and diff checks above passed explicitly through Corepack/manual commands before PR creation.

Summary by CodeRabbit

• 새 기능
  • 내부 Croco 패키지 참조에 대해 워크스페이스 범위 정책을 적용해 매니페스트 검증을 강화했습니다.
  • 내부 peer 의존성 범위는 제한된 예외 목록으로만 허용되도록 했습니다.
• 버그 수정
  • 공개 배포용 매니페스트에 오래된 내부 semver 범위가 포함되지 않도록 개선했습니다.
  • 릴리스 전에 잘못된 범위 설정을 더 일찍 탐지합니다.
• 문서
  • 패키지 진입점/의존성 계약(예외 처리 방식 포함)을 보강했습니다.
• 테스트
  • 정책 검증 및 예외 처리 시나리오에 대한 테스트를 추가했습니다.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 31454856-892e-4ef9-be8c-caa02c4cd883

📥 Commits

Reviewing files that changed from the base of the PR and between bbf3055 and 7ebcf82.

📒 Files selected for processing (2)

• scripts/normalize-packages.mjs
• scripts/tests/normalize-packages.spec.ts

---

📝 Walkthrough

Walkthrough

내부 @croco 패키지 의존성 범위를 workspace:*로 강제하는 검증이 추가되었고, peerDependencies 예외는 JSON 파일로만 허용된다. frontend-react의 내부 범위는 수정됐고, 문서·테스트·changeset이 함께 갱신됐다.

Changes

내부 의존성 범위 정책

Layer / File(s)	Summary
정책 검증 핵심 로직 및 예외 스키마 scripts/normalize-packages.mjs	내부 의존성 섹션 상수, semver compatibility 패턴, 예외 JSON 파싱/검증, findWorkspacePackageJsonFiles, readWorkspacePackageNames, validateWorkspacePackagePolicy, validateInternalDependencyRangePolicy가 추가된다.
메인 검증 흐름 통합 scripts/normalize-packages.mjs	main 흐름에서 workspace 패키지명/예외 맵을 계산하고 각 패키지에 정책 검증을 적용하며, 미사용 예외를 위반으로 보고한다.
frontend-react 위반 수정 및 예외 파일/체인지셋 packages/frontend-react/package.json, scripts/internal-peer-dependency-range-exceptions.json, .changeset/internal-range-policy.md	@croco/meta-vite 범위를 workspace:*로 수정하고, 예외 목록을 빈 배열로 초기화하며, patch 체인지셋을 추가한다.
패키지 계약 문서 갱신 docs/release/package-entrypoint-contract.md	내부 참조는 workspace:*를 사용하고 peer 예외는 exceptions.json에 등록해야 한다는 계약을 문서화한다.
정책 검증 테스트 scripts/tests/normalize-packages.spec.ts	위반 감지, 유효한 예외 통과, 잘못된/미사용 예외 거부를 검증하는 테스트와 예외 파일 작성 헬퍼를 추가한다.

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

Possibly related PRs

• croco-dev/framework#634: scripts/normalize-packages.mjs와 해당 테스트를 함께 확장해 manifest 검증 규칙을 추가한다는 점에서 같은 정규화/검증 흐름을 수정합니다.

🚥 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	The title clearly and concisely summarizes the main change: enforcing internal Croco package ranges.
Linked Issues check	✅ Passed	The PR implements the internal @croco/* range policy, checked peer exceptions, documentation, and validation expected by #1148.
Out of Scope Changes check	✅ Passed	The code, docs, and tests all align with the range-policy objective and do not introduce unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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 fix/1148-internal-range-policy

---

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.}

[github-actions]

📊 Benchmark Results

✅ All benchmarks passed

Benchmark	p75	Threshold	Baseline	vs Baseline	Status	Notes
CrocoApp constructor	8.4μs	30.0ms	8.2μs	+2.2%	✅	-
CrocoApp lambdaHandler (10 controllers)	245.3μs	50.0ms	258.4μs	-5.1%	✅	-
Lambda cold-start simulation	422.2μs	80.0ms	418.1μs	+1.0%	✅	-
Lambda cold-start with headers	383.8μs	80.0ms	369.7μs	+3.8%	✅	-
Lambda cold-start with binary body	343.2μs	80.0ms	339.1μs	+1.2%	✅	-
Lambda cold-start with query params	307.4μs	80.0ms	301.3μs	+2.0%	✅	-
Lambda cold-start with authorizer context	303.6μs	80.0ms	299.8μs	+1.3%	✅	-
Lambda cold-start realistic scenario	302.5μs	80.0ms	299.2μs	+1.1%	✅	-
EventBusConfig.start (10 handlers)	1.4μs	10.0ms	1.4μs	-2.9%	✅	-
EventPublisher.publishNow single event	1.7μs	2.0ms	1.7μs	-0.6%	✅	-
DefaultHandlerResolver.resolve × 10	0.1μs	5.0ms	0.1μs	-11.2%	✅	-
Container.get singleton (cold)	70.7μs	5.0ms	70.3μs	+0.6%	✅	-
Container.register × 50 components	3.3ms	10.0ms	3.2ms	+0.7%	✅	-
Container.validate (50 components)	3.5ms	20.0ms	3.4ms	+3.4%	✅	-
Container.get singleton (warm)	1.7μs	500.0μs	1.6μs	+3.1%	✅	-
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-04T00:27:58.420Z · Commit: cd1337e}

[kang-heewon]

@coderabbitai review

[coderabbitai]

✅ 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.

[kang-heewon]

@coderabbitai review

[coderabbitai]

✅ 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]

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/normalize-packages.mjs`:
- Around line 578-600: The exception builder in normalize-packages.mjs is
validating semver compatibility range errors but still returning an exception
object when range is invalid. Update the guard around the object returned by the
peerDependencies exception logic so it also rejects non-semver-compatible range
values, not just blank ones. Keep the check aligned with
isSemverCompatibilityRange, internalPeerDependencyRangeExceptionKey, and the
existing packageName/sectionName/dependencyName/rationale validations so invalid
ranges are never registered.

🪄 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: 85bdee88-0584-488e-ba7a-ec4ad931d041

📥 Commits

Reviewing files that changed from the base of the PR and between ebd9874 and bbf3055.

📒 Files selected for processing (6)

• .changeset/internal-range-policy.md
• docs/release/package-entrypoint-contract.md
• packages/frontend-react/package.json
• scripts/internal-peer-dependency-range-exceptions.json
• scripts/normalize-packages.mjs
• scripts/tests/normalize-packages.spec.ts

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bf8f69224b

ℹ️ 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".

[kang-heewon]

@coderabbitai review

[coderabbitai]

✅ 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.

[kang-heewon]

@coderabbitai review

[coderabbitai]

✅ 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.

[kang-heewon]

@coderabbitai review

[coderabbitai]

✅ 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.