피드로 돌아가기
Dev.toDevOps
원문 읽기
Snapshot 기반 정적 분석을 통한 SDK-문서 간 Drift 자동 탐지 및 CI 통합
DriftGuard: catching when your code quietly breaks your docs
AI 요약
Context
SDK 업데이트 시 코드 변경 사항이 README 등 문서와 예제 앱에 반영되지 않아 발생하는 런타임 에러 및 사용자 경험 저하 문제 발생. 특히 Web3 환경의 Contract-SDK-Docs 간의 높은 의존성으로 인한 동기화 실패가 주요 병목 지점으로 작용.
Technical Solution
- 정규화된 JSON Snapshot 기반의 Baseline 비교 방식을 통해 변경 사항을 확정하는 승인 메커니즘 설계
- ts-morph Project를 활용하여 Markdown 내 TypeScript 코드 블록을 현재 SDK 버전으로 재컴파일하는 정적 타입 체크 로직 구현
- Solidity Contract의 함수/이벤트 변경 및 TypeScript SDK의 Export 시그니처 변화를 추적하는 4계층 결정론적 검증 체계 구축
- Line Number 대신 Content-hash ID를 식별자로 채택하여 문서 내 단순 텍스트 추가로 인한 검증 실패 방지
- GitHub Action 내의 번들링 제약을 극복하기 위해 런타임 npm 설치 방식을 채택한 단순화된 배포 전략 적용
- SARIF 리포트 및 Inline Annotation 형식을 통한 PR 단위의 즉각적인 오류 피드백 루프 생성
실천 포인트
- API 변경 시 문서 내 코드 스니펫의 컴파일 가능 여부를 CI 단계에서 자동 검증하는 파이프라인 검토 - 단순 라인 기반 비교가 아닌 콘텐츠 해시 기반의 식별자 체계를 도입하여 문서 구조 변경에 유연하게 대응 - 복잡한 번들링 라이브러리 의존성 해결이 어려울 경우, 런타임 설치와 같은 단순한 배포 구조 우선 고려