rgql: AST-Aware GraphQL Refactoring That AI Agents Can Trust

Context

GraphQL 필드 이름 변경 시 동일한 필드명이 여러 타입에 존재하면 단순 find-and-replace는 잘못된 필드까지 변경하는 문제가 발생한다. 중첩된 쿼리 구조와 TypeScript 파일에 임베드된 GraphQL 쿼리까지 고려하면 수동 리팩토링은 매우 복잡하고 오류가 발생하기 쉽다. 대부분의 IDE는 GraphQL 문자열을 불투명한 텍스트로 취급해 리팩토링 지원이 제한적이다.

Technical Solution

• TypeInfo와 visitWithTypeInfo 원시 함수를 활용한 AST 기반 분석: 쿼리 트리를 순회하며 각 필드 노드의 부모 타입을 추적해 정확한 타입-필드 매칭 수행
• 스키마 파일(.graphql)과 TypeScript 임베드 쿼리(graphql 템플릿) 모두에 대응: ts-morph로 TS/TSX 파일의 tagged template literal을 검출하고 GraphQL AST 위치를 절대 파일 위치로 변환
• 인터페이스 구현 시 캐스케이드 이름 변경 감지 및 차단: 인터페이스 정의 필드를 변경할 때 해당 인터페이스를 구현하는 모든 타입에서의 필드 이름 변경을 검증하고 --force 플래그 없이는 부분 변경 거부
• 순수 함수 아키텍처로 테스트 및 결정성 확보: RenameCommand + Schema + Documents → RenameOutcome 파이프라인을 부작용 없는 순수 함수로 구현하고 Result 타입으로 명시적 에러 처리
• Branded Types를 통한 컴파일 타임 타입 안전성: TypeName과 FieldName을 구분되는 branded type으로 정의해 런타임 비용 없이 잘못된 매개변수 전달 방지

Key Takeaway

AST 기반 리팩토링을 원자적 단일 명령으로 제공하면 AI 코딩 에이전트가 전체 파일을 읽고 추론해야 하는 컨텍스트 윈도우 소비를 완전히 제거할 수 있으며, 순수 함수 아키텍처와 타입 브랜딩은 AI 에이전트가 호출할 도구로서의 신뢰성을 확보하는 핵심 설계 원칙이다.