fix: standardize Croco diagnostic codes

[kang-heewon]

Fixes #871.

Summary

@croco/diagnostics-core now exposes a stable CROCO_* diagnostic code contract with typed definitions, source locations, fix examples, message construction, formatting helpers, and an append-only change policy.

The initial standard defines diagnostic examples across dependency injection, routing, and build-time categories. The troubleshooting guide documents the message fields, standard output shape, per-code cause/fix anchors, search keywords, and code stability policy.

Review notes

public-api-surface.snapshot.json was regenerated on current trunk. Alongside the new diagnostics-core exports, it records already-present current-trunk exports for @croco/cli doctor APIs, @croco/framework-routes route registration tables, and @croco/framework-context runtime policies so the all-repo public API guard passes. No source changes were made in those packages.

The diagnostics-core package test/typecheck config now aliases the existing @croco/problems-core workspace source, matching the local source import path needed by package-scoped checks.

Verification

• mise exec node@22 -- pnpm --filter @croco/diagnostics-core test - passed, 2 files and 15 tests.
• mise exec node@22 -- pnpm --filter @croco/diagnostics-core typecheck - passed.
• mise exec node@22 -- pnpm --filter @croco/diagnostics-core build - passed.
• mise exec node@22 -- pnpm public-api:check - passed.
• NODE_OPTIONS=--experimental-strip-types mise exec node@22 -- pnpm check - passed.
• mise exec node@22 -- pnpm typecheck - passed, 200/200 Turbo tasks.
• mise exec node@22 -- pnpm test - passed, 201/201 Turbo tasks.
• mise exec node@22 -- pnpm changeset-required:check -- --base origin/trunk --head HEAD - passed.
• git diff --check and git diff --cached --check - passed.
• Pre-push test and typecheck hooks passed.

Self-review gates

• Correctness/regression: Passed. The issue acceptance is covered by three categories, messages with cause/action/location/docs/search fields, docs, tests, and generated public API snapshots.
• API/release/security: Passed. The new surface is additive, includes a patch changeset, adds no dependencies, and introduces no secrets or external service behavior.
• Maintainability/minimality: Passed. The change is scoped to diagnostics-core, troubleshooting docs, package-local test/typecheck resolution, and generated public API metadata.

[coderabbitai]

Warning

Review limit reached

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

More reviews will be available in 10 minutes and 11 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

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

🚦 How do rate limits work?

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

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, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 3344078b-8a9c-4da6-93c4-05984e27efd5

📥 Commits

Reviewing files that changed from the base of the PR and between 0ae5c7d and c591b60.

📒 Files selected for processing (8)

• .changeset/diagnostic-code-standard.md
• docs/troubleshooting/diagnostics.md
• packages/diagnostics-core/src/index.ts
• packages/diagnostics-core/src/libs/DiagnosticCodes.ts
• packages/diagnostics-core/src/tests/DiagnosticCodes.spec.ts
• packages/diagnostics-core/tsconfig.json
• packages/diagnostics-core/vitest.config.ts
• public-api-surface.snapshot.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/871-diagnostic-code-standard

---

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 and usage tips.}

[github-actions]

📊 Benchmark Results

❌ Some benchmarks failed

Gate failures

• CrocoApp constructor: p75 5.3μs exceeds baseline 3.4μs by more than 20%
• CrocoApp lambdaHandler (10 controllers): p75 44.1μs exceeds baseline 33.3μs by more than 20%
• Lambda cold-start simulation: p75 227.8μs exceeds baseline 70.2μs by more than 20%
• Lambda cold-start with headers: p75 172.8μs exceeds baseline 66.7μs by more than 20%
• Lambda cold-start with binary body: p75 140.0μs exceeds baseline 63.2μs by more than 20%
• Lambda cold-start with query params: p75 121.6μs exceeds baseline 63.9μs by more than 20%
• Lambda cold-start with authorizer context: p75 128.5μs exceeds baseline 59.8μs by more than 20%
• Lambda cold-start realistic scenario: p75 123.3μs exceeds baseline 60.2μs by more than 20%
• EventBusConfig.start (10 handlers): p75 1.3μs exceeds baseline 0.9μs by more than 20%
• EventPublisher.publishNow single event: p75 1.6μs exceeds baseline 1.1μs by more than 20%
• DefaultHandlerResolver.resolve × 10: p75 0.1μs exceeds baseline 0.0μs by more than 20%
• Container.get singleton (cold): p75 2.1μs exceeds baseline 0.6μs by more than 20%
• Container.get singleton (warm): p75 1.5μs exceeds baseline 0.3μs by more than 20%
• lambdaPreset config creation: p75 1.5μs exceeds baseline 1.0μs by more than 20%

Benchmark	p75	Threshold	Baseline	vs Baseline	Status	Notes
CrocoApp constructor	5.3μs	30.0ms	3.4μs	+57.9%	❌	-
CrocoApp lambdaHandler (10 controllers)	44.1μs	50.0ms	33.3μs	+32.6%	❌	-
Lambda cold-start simulation	227.8μs	80.0ms	70.2μs	+224.7%	❌	-
Lambda cold-start with headers	172.8μs	80.0ms	66.7μs	+158.9%	❌	-
Lambda cold-start with binary body	140.0μs	80.0ms	63.2μs	+121.7%	❌	-
Lambda cold-start with query params	121.6μs	80.0ms	63.9μs	+90.4%	❌	-
Lambda cold-start with authorizer context	128.5μs	80.0ms	59.8μs	+114.9%	❌	-
Lambda cold-start realistic scenario	123.3μs	80.0ms	60.2μs	+105.0%	❌	-
EventBusConfig.start (10 handlers)	1.3μs	10.0ms	0.9μs	+52.2%	❌	-
EventPublisher.publishNow single event	1.6μs	2.0ms	1.1μs	+46.2%	❌	-
DefaultHandlerResolver.resolve × 10	0.1μs	5.0ms	0.0μs	+90.5%	❌	-
Container.get singleton (cold)	2.1μs	5.0ms	0.6μs	+233.4%	❌	-
Container.register × 50 components	11.7μs	10.0ms	12.1μs	-3.4%	✅	-
Container.validate (50 components)	29.5μs	20.0ms	29.7μs	-0.5%	✅	-
Container.get singleton (warm)	1.5μs	500.0μs	0.3μs	+414.7%	❌	-
TelemetryRuntime.init (lambda preset)	1.2ms	200.0ms	69.3ms	-98.2%	✅	-
lambdaPreset config creation	1.5μs	2.0ms	1.0μs	+46.3%	❌	-

_{Updated: 2026-06-18T16:56:01.361Z · Commit: c0a483a}