Croco Contract Graph

[kang-heewon]

Summary

Croco controller/decorator/schema metadata를 하나의 canonical contract graph로 수집하고, OpenAPI, typed client, frontend integration, contract drift check가 모두 이 graph를 소비하도록 만든다.

현재 Croco에는 REST metadata, OpenAPI generation, RPC codegen, frontend/meta-vite integration이 존재하지만, 각 도구가 완전히 같은 source of truth를 공유한다는 보장이 약하다. 이 기능은 Croco의 contract-first 개발 경험을 제품화하는 로드맵이다.

Product Narrative

사용자는 서버 controller와 schema를 작성하면 다음 산출물이 자동으로 맞춰지길 기대한다.

• API 문서
• typed client
• request/response validation
• Problem error shape
• frontend integration hook 또는 route/action boundary
• CI에서 contract drift 감지

이 기능의 핵심은 “서버 코드를 바꾸면 문서와 클라이언트가 함께 바뀐다”가 아니라, “서버/문서/클라이언트가 같은 contract graph에서 나온다”이다.

Why This Matters

• Croco의 가장 강한 DX 메시지가 된다.
• OpenAPI와 generated client의 불일치를 줄인다.
• controller template, repository template, frontend template 같은 생성기 품질을 contract 기준으로 검증할 수 있다.
• SaaS Golden Path Kit가 신뢰 가능한 API/client foundation을 갖게 된다.

MVP Scope

Canonical contract graph

최소 다음 정보를 하나의 IR로 표현한다.

• controller/module identity
• route path와 method
• path/query/header/body params
• input validation schema
• response schema
• Problem error shape
• auth/access metadata가 있다면 최소 reference 형태
• runtime/frontend integration에 필요한 route id

Generators

• canonical IR 기반 OpenAPI spec generator.
• typed fetch 또는 RPC client generator.
• generated client와 backend round-trip smoke test.
• croco contracts check 또는 equivalent drift checker.

Template alignment

• CLI controller/page/domain 생성기가 contract graph와 맞는 코드를 생성해야 한다.
• create-croco-app 템플릿이 generated contract/client와 충돌하지 않아야 한다.

Non-Goals

• 첫 버전에서 GraphQL/tRPC까지 모두 통합하지 않는다.
• 모든 Zod transform/refinement edge case를 완벽히 표현하지 않는다.
• full API gateway나 deployment product를 만들지 않는다.
• frontend UI generation은 별도 후속 기능으로 둔다.

Design Constraints

• IR은 특정 generator의 내부 구조가 아니라 여러 소비자가 공유할 수 있는 stable contract여야 한다.
• unsupported schema feature는 조용히 누락하지 말고 diagnostic으로 드러낸다.
• generated artifact는 package boundary와 dependency manifest를 깨뜨리지 않아야 한다.
• Problem error shape는 Croco 표준 오류 모델과 일관되어야 한다.

Suggested Breakdown

1. 현재 protocols-rest, openapi-spec, rpc-codegen, meta-vite의 metadata 흐름을 맵핑한다.
2. canonical IR 타입과 diagnostics model을 정의한다.
3. REST route extraction을 canonical IR로 이관하거나 adapter를 둔다.
4. OpenAPI generator를 canonical IR 소비자로 정리한다.
5. typed client generator를 canonical IR 소비자로 정리한다.
6. generated client와 backend round-trip fixture를 만든다.
7. croco contracts check 명령으로 drift/unsupported feature를 CI에서 잡는다.
8. CLI/create-croco-app 템플릿을 contract graph 기준으로 갱신한다.

Acceptance Criteria

• route metadata 변경이 OpenAPI와 typed client에 같은 방식으로 반영된다.
• generated client가 실제 backend round-trip test를 통과한다.
• unsupported schema 또는 route metadata는 diagnostic으로 실패한다.
• generated artifacts가 package dependency boundary를 깨지 않는다.
• CLI 생성 템플릿이 현재 public contract와 일치한다.

Validation Strategy

• pnpm test --filter=@croco/protocols-rest
• pnpm test --filter=@croco/openapi-spec
• pnpm test --filter=@croco/rpc-codegen
• pnpm test --filter=@croco/cli
• generated client/backend round-trip smoke
• isolated package typecheck smoke

Related Issues

Seed issues:

• [transports-http] ParamResolver가 zod 공개 타입을 노출하지만 직접 의존성을 선언하지 않음 #699
• [cli] 컨트롤러 템플릿이 공개되지 않은 RouteContext 타입을 가져옴 #692
• [cli] 리포지토리/엔티티 템플릿이 존재하지 않는 repository-core 계약을 생성함 #693
• [cli] page 생성기가 현재 meta-vite defineRoute 계약이 아닌 구형 라우트 설정을 방출함 #695

Done When

Croco API 개발자가 controller/schema 하나를 source of truth로 삼아 문서와 client를 생성하고, CI가 contract drift를 잡을 수 있을 때 완료로 본다.