CI: SDL description 커버리지 게이트를 validate에 추가

[chanwoo7]

배경

SDL에 설명 없는 필드를 추가해도 아무도 모른다. yarn validate(lint + tsc + dto:check + arch:check + test:cov)에 설명 검사가 없어서 CI가 그대로 통과한다.

dto:check가 SDL↔DTO 동기화를 도구로 강제하는 것처럼, 문서 커버리지도 사람 주의력이 아니라 게이트로 받쳐야 한다. 실제로 #249에서 확인된 도메인별 편차(seller-order 4% ↔ user-search 100%)가 그 방증이다.

제안

scripts/에 SDL description 커버리지 검사 스크립트를 추가하고 yarn validate에 편입한다.

• src/**/*.graphql을 graphql 패키지로 파싱해 요소별 description 유무 집계
• 요소 종류별 임계치를 설정 파일이나 스크립트 상수로 관리하고, 기존 부채는 임계치를 점진적으로 올려가며 갚는다
• 위반 시 어떤 필드가 비었는지 목록 출력 (수정 지점을 바로 알 수 있게)

초기 임계치 (제안)

요소	현재	초기 임계치	근거
Query/Mutation 필드	100%	100% (회귀 방지)	이미 달성 — 내려가지 않게 고정
enum 값	6%	#248 완료 후 100%	개수가 적고 오해 위험이 큼
스칼라 루트 인자	0%	#248 완료 후 상향	설명이 유일한 자리
input 필드	16%	현재치 + 여유(회귀만 차단)	#249 진행에 따라 단계적 상향
출력 type 필드	25%	현재치 + 여유	동일

핵심은 신규 API에는 문서화를 강제하고, 기존 부채는 회귀만 막으면서 점진 상환하는 구조다.

수행 조건

• 스크립트 작성 + 단위 spec (DB 불필요)
• package.json에 docs:check(가칭) 추가, validate 체인에 편입
• 임계치 미달 시 비어 있는 요소 목록을 출력하는지 확인
• 자명한 필드(id 등)까지 강제하지 않도록 제외 규칙이 필요한지 판단 — 과하면 형식적 설명만 양산된다

참고

• 선행: #248 (enum·스칼라 인자) → 100% 임계치를 걸 수 있게 됨
• 병행: #249 (input·출력 필드 대량 보강) → 임계치 상향의 근거
• 문서 산출물 자체는 SpectaQL(yarn graphql:docs, spectaql.yml)로 이미 생성 가능하다. 다만 출력물(public/)이 gitignore이고 발행 워크플로가 없어 로컬에서 각자 돌려야만 볼 수 있다 — 발행 자동화가 필요하면 별도 이슈로 분리한다.