fix: validate adapter certification records

[kang-heewon]

Fixes #1089.

Summary

• Adds certification.records to docs/package-catalog.json with candidate records for R2 storage, Polar billing, and Meilisearch search adapters, including explicit live-smoke gaps instead of prose-only certification claims.
• Extends package-docs-check to validate certification schema version, package catalog linkage, extension-matrix linkage, package version, adapter category, runtime scope, evidence keys, missing-evidence reasons, known-gap naming, certified-state constraints, duplicate records, and command/artifact-backed present evidence.
• Renders certification state and evidence gaps in the generated README catalog, package docs report, and extension matrix docs, with certification table cells escaping pipe characters from free-text metadata.

Verification

• COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm docs:catalog:check
• COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm exec tsc --noEmit --skipLibCheck --module NodeNext --moduleResolution NodeNext --target ES2022 --types node,vitest/globals --allowImportingTsExtensions scripts/package-docs-check.mts scripts/tests/package-docs-check.spec.ts
• COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm exec vitest run scripts/tests/package-docs-check.spec.ts --config vitest.config.ts (19 tests)
• COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm exec oxlint scripts/package-docs-check.mts scripts/tests/package-docs-check.spec.ts
• COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm exec oxfmt --check scripts/package-docs-check.mts scripts/tests/package-docs-check.spec.ts README.md docs/package-docs-report.md packages/docs/src/content/docs/en/reference/extension-matrix.md docs/package-catalog.json
• git diff --check
• COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm check
• COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack pnpm changeset-required:check -- --base origin/trunk --head HEAD

Review Notes

• The certification source remains embedded in the package catalog for this first-party gate so package identity, extension-matrix runtime claims, generated docs, and certification evidence are checked together.
• Present evidence requires a command or artifact; descriptions are only supplemental context.
• Missing evidence requires knownGaps entries that explicitly name each missing evidence key.
• The local pre-push hook was bypassed only after it reached an interactive pnpm install reinstall prompt in the non-interactive shell. The same relevant gates are listed above and passed before push.

UltraQA

• Normal render path: certification records render into generated docs and extension matrix output.
• Missing extension linkage path: invalid records fail the catalog check.
• Missing evidence reason path: missing evidence without an explicit reason fails the catalog check.
• Missing gap naming path: known gaps that do not name liveSmoke fail the catalog check.
• Prose-only present evidence path: present evidence without a command or artifact fails the catalog check.
• Markdown escape path: certification free-text values containing | render as escaped table-cell content.
• Drift path: docs:catalog:check, formatter checks, and full pnpm check all passed after generated docs were updated.

[coderabbitai]

📝 Walkthrough

Walkthrough

scripts/package-docs-check.mts에 certification 타입·파싱·검증·렌더링 파이프라인을 신설한다. docs/package-catalog.json에 3개 패키지의 candidate 인증 레코드를 등록하고, README·extension-matrix·package-docs-report에 Certification 열/섹션이 자동 생성되도록 변경한다.

Changes

Certification Records 도입

Layer / File(s)	Summary
Certification 타입·상수·PackageInfo 확장 scripts/package-docs-check.mts	PackageJson/PackageInfo에 version 필드, CatalogMetadata에 certification 필드를 추가하고, 어댑터 카테고리·인증 상태·증거 키 도메인 타입과 정렬 상수를 정의한다.
parseCertification 파싱·검증 로직 scripts/package-docs-check.mts	parseCertification·parseCertificationRecord 및 보조 함수(readAdapterCategory, readCertificationState, readStringArray 등)를 구현해 스키마 버전·참조 무결성·packageVersion 일치·adapterCategory–group 매핑·runtimes·evidence missing 규칙·레코드 중복을 위반 목록에 누적한다. loadCatalogState에서 호출된다.
package-catalog.json candidate 레코드 등록 docs/package-catalog.json	certification 최상위 섹션을 추가하고 @croco/storage-r2·@croco/billing-polar·@croco/search-meilisearch 3개 패키지를 candidate 상태로 등록한다. liveSmoke는 missing, knownGaps에 live smoke 증빙 필요 문구를 기록한다.
렌더러: 문서 리포트·README·extension-matrix scripts/package-docs-check.mts	formatCertificationCell·formatCertificationRecords 등 포맷터를 추가하고, 문서 리포트 요약 테이블에 Certification records 행·Certification Records 섹션을 삽입한다. extension-matrix 테이블 헤더/행에 Certification 열을 추가하고 README 설명 문구를 확장한다.
생성된 문서 산출물 업데이트 README.md, docs/package-docs-report.md, packages/docs/src/content/docs/en/reference/extension-matrix.md	README·extension-matrix.md·package-docs-report.md의 Certification 열/섹션이 스크립트 출력 결과로 갱신된다.
테스트 픽스처·검증 케이스 확장 scripts/tests/package-docs-check.spec.ts	writePackage에 기본 version: "0.0.0" 병합, writeCatalogMetadata에 certificationRecords 옵션 및 certification 섹션 출력을 추가한다. createCertificationRecord 헬퍼를 도입하고, 성공/실패 4개 신규 테스트와 기존 assertion을 확장한다.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

• #1089: 이 PR은 해당 이슈의 수락 기준(JSON 스키마 검증, 카탈로그 연결, 문서 렌더링, 패키지/계약/런타임/버전 스코핑, missing evidence 명시적 표현)을 직접 구현한다.
• [certification] Add validator and maturity-promotion CI gate #1090: certification 검증기/CI 게이트 구현을 요청하는 이슈로, 이 PR의 parseCertification 검증 로직과 직접 연관된다.

Possibly related PRs

• croco-dev/framework#760: docs/package-catalog.json·scripts/package-docs-check.mts·extension-matrix.md 및 테스트를 동일하게 수정하는 PR로, 이 PR은 해당 호환성 매트릭스 메타데이터 위에 Certification 열/레코드 로직을 추가한다.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	제목이 certification 레코드 검증 추가라는 핵심 변경을 간결하게 요약합니다.
Linked Issues check	✅ Passed	인증 레코드 스키마, 패키지 카탈로그 연결, 문서 렌더링, 증거·누락 처리 검증이 #1089 요구와 일치합니다.
Out of Scope Changes check	✅ Passed	변경 대부분이 인증 레코드, 문서 생성, 검증 테스트에 집중되어 있어 눈에 띄는 범위 이탈이 없습니다.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ 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-1089-certification-schema

---

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

🤖 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/package-docs-check.mts`:
- Around line 2113-2144: Free-text fields in the certification table can break
the markdown pipe layout because they are inserted unescaped in
formatCertificationRecords and formatCertificationEvidenceItem. Add a small
helper to escape pipe characters in cell content, then route all user-authored
text through it before rendering the table, especially record.contract,
record.knownGaps, and the CertificationEvidenceItem fields combined in details
so the generated markdown stays valid.
- Around line 814-818: The knownGaps check in the package-docs validation is
weaker than the violation message claims because it only enforces non-empty
content, not that each missingEvidence key is actually named. Update the
validation around the missingEvidence branch in the docs check logic to either
verify each missing key is explicitly referenced in knownGaps, or relax the
violation text to match the current length-only behavior; keep the fix aligned
with the surrounding missing certification gap validation.

In `@scripts/tests/package-docs-check.spec.ts`:
- Around line 667-711: createCertificationRecord currently only allows
overriding contract, evidence, and packageVersion, which makes it hard to reuse
for broader validation scenarios; update the helper so overrides can cover the
full certification record shape, including fields like package, adapterCategory,
runtimes, and state. Keep the existing defaults in createCertificationRecord,
but broaden the overrides type and merge logic so tests can easily construct
mismatch cases without changing the helper again.

🪄 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: add0a699-d805-4273-b072-bbbabc828891

📥 Commits

Reviewing files that changed from the base of the PR and between 4d8f094 and ff3be40.

📒 Files selected for processing (6)

• README.md
• docs/package-catalog.json
• docs/package-docs-report.md
• packages/docs/src/content/docs/en/reference/extension-matrix.md
• scripts/package-docs-check.mts
• scripts/tests/package-docs-check.spec.ts

[github-actions]

📊 Benchmark Results

❌ Some benchmarks failed

Gate failures

• CrocoApp constructor: p75 8.8μs exceeds baseline 3.4μs by more than 20%
• CrocoApp lambdaHandler (10 controllers): p75 245.4μs exceeds baseline 33.3μs by more than 20%
• Lambda cold-start simulation: p75 401.2μs exceeds baseline 70.2μs by more than 20%
• Lambda cold-start with headers: p75 359.2μs exceeds baseline 66.7μs by more than 20%
• Lambda cold-start with binary body: p75 327.1μs exceeds baseline 63.2μs by more than 20%
• Lambda cold-start with query params: p75 278.4μs exceeds baseline 63.9μs by more than 20%
• Lambda cold-start with authorizer context: p75 275.6μs exceeds baseline 59.8μs by more than 20%
• Lambda cold-start realistic scenario: p75 274.1μs exceeds baseline 60.2μs by more than 20%
• EventBusConfig.start (10 handlers): p75 1.7μs exceeds baseline 0.9μs by more than 20%
• EventPublisher.publishNow single event: p75 1.9μ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 57.3μs exceeds baseline 0.6μs by more than 20%
• Container.register × 50 components: p75 3.1ms exceeds baseline 12.1μs by more than 20%
• Container.validate (50 components): p75 3.3ms exceeds baseline 29.7μs by more than 20%
• Container.get singleton (warm): p75 1.6μs exceeds baseline 0.3μs by more than 20%
• lambdaPreset config creation: p75 1.4μs exceeds baseline 1.0μs by more than 20%

Benchmark	p75	Threshold	Baseline	vs Baseline	Status	Notes
CrocoApp constructor	8.8μs	30.0ms	3.4μs	+160.3%	❌	-
CrocoApp lambdaHandler (10 controllers)	245.4μs	50.0ms	33.3μs	+637.0%	❌	-
Lambda cold-start simulation	401.2μs	80.0ms	70.2μs	+471.8%	❌	-
Lambda cold-start with headers	359.2μs	80.0ms	66.7μs	+438.2%	❌	-
Lambda cold-start with binary body	327.1μs	80.0ms	63.2μs	+417.8%	❌	-
Lambda cold-start with query params	278.4μs	80.0ms	63.9μs	+335.9%	❌	-
Lambda cold-start with authorizer context	275.6μs	80.0ms	59.8μs	+361.0%	❌	-
Lambda cold-start realistic scenario	274.1μs	80.0ms	60.2μs	+355.6%	❌	-
EventBusConfig.start (10 handlers)	1.7μs	10.0ms	0.9μs	+95.7%	❌	-
EventPublisher.publishNow single event	1.9μs	2.0ms	1.1μs	+72.9%	❌	-
DefaultHandlerResolver.resolve × 10	0.1μs	5.0ms	0.0μs	+90.5%	❌	-
Container.get singleton (cold)	57.3μs	5.0ms	0.6μs	+9070.6%	❌	-
Container.register × 50 components	3.1ms	10.0ms	12.1μs	+25116.8%	❌	-
Container.validate (50 components)	3.3ms	20.0ms	29.7μs	+11054.7%	❌	-
Container.get singleton (warm)	1.6μs	500.0μs	0.3μs	+459.2%	❌	-
TelemetryRuntime.init (lambda preset)	1.0ms	200.0ms	69.3ms	-98.5%	✅	-
lambdaPreset config creation	1.4μs	2.0ms	1.0μs	+41.2%	❌	-

_{Updated: 2026-06-30T15:13:17.578Z · Commit: c14f348}