diff가 실제로 무엇을 의미하는지 알려주는 GitLab flow를 구축했습니다

모든 코드 리뷰는 똑같은 방식으로 시작됩니다. diff를 열고 그것이 실제로 무엇을 의미하는지 파악하려고 노력합니다. 단순히 무엇이 바뀌었는지가 아니라, 무엇이 그것에 의존하는지, 하위 스트림(downstream)에서 무언가를 깨뜨리지는 않는지, 그리고 다른 누군가가 곧 같은 코드를 건드리게 될지 등을 파악해야 합니다. 이러한 조사 작업은 보통 리뷰어의 몫이며, 매번 수동으로 이루어집니다.

저는 지난 2주 동안 이를 변화시키기 위한 무언가를 만드는 데 시간을 보냈습니다.

제가 만든 것

Orbit Change Passport는 머지 리퀘스트(merge request)가 리뷰 준비 완료로 표시될 때 자동으로 실행되는 GitLab Duo Agent Platform flow입니다. 이 flow는 GitLab Orbit의 지식 그래프(Knowledge Graph)를 쿼리하여, 누군가 diff의 단 한 줄을 읽기도 전에 구조화된 댓글을 게시합니다.

댓글이 다루는 내용은 다음과 같습니다:

변경 범위 (Changed Surface) - 줄 번호가 아닌 이름으로 식별된, diff가 건드린 정확한 함수와 메서드
의존성 그래프 (Dependency graph) - 변경된 모듈을 임포트(import)하는 모든 것을 나타내는 실시간 Mermaid 다이어그램으로, GitLab 내에 인라인으로 렌더링됨
충돌 레이더 (Conflict Radar) - 현재 동일한 코드를 건드리는 다른 모든 오픈된 MR(merge request), 머지 시점이 아닌 머지 전에 포착
교차 프로젝트 영향 범위 (Cross-project blast radius) - 그룹 내 다른 프로젝트에서 변경 사항에 의존하는 파일들. 이는 Orbit의 그래프가 단일 리포지토리(repo)가 아닌 그룹 전체에 걸쳐 있기 때문에 가능합니다
테스트 공백 (Test gaps) - 변경된 모듈을 임포트하지만 이번 MR에서 건드리지 않은 테스트 파일들
추천 리뷰어 (Suggested reviewers) - 의존성 파일의 최근 작성자(authorship)를 기반으로 함
리뷰어 브리핑 (Reviewer Brief) - 직후에 게시되는 두 번째의 더 짧은 댓글: diff를 읽기 전 가장 중요한 한 가지를 담은 한 단락

동반되는 Duo Chat 에이전트를 통해 리뷰어는 패스포트가 게시된 후에도 동일한 그래프를 대상으로 계속 질문을 던질 수 있습니다. "이것을 호출하는 다른 것은 무엇인가요?", "누가 이 파일을 임포트하나요?"와 같은 질문에 대해 댓글 내용을 단순히 재진술하는 것이 아니라 실시간으로 답변합니다.

구체적인 예시

실제 실행 시 영향력 라인이 어떻게 보이는지는 다음과 같습니다:

영향력: 높음(HIGH) - 2개의 정의(definitions) 변경 - 2개의 프로젝트 내 의존성(within-project dependents) -
프로젝트 간 영향 범위(cross-project blast radius) (3개 프로젝트) - 1개의 충돌(conflict)

그 단 한 줄의 정보가 저에게 알려줍니다: 이 변경 사항은 이 저장소(repo) 외부에도 의존성이 있으며, 다른 열려 있는 MR(Merge Request)이 이미 동일한 함수를 건드리고 있다는 사실을 말이죠. 이 두 가지 사항을 수동으로 찾는 데는 보통 10분이 걸립니다. 하지만 저는 diff를 열기도 전에 이 정보들을 자동으로 확인했습니다.

프로젝트 간(cross-project) 결과는 저를 가장 놀라게 한 부분이었습니다. engine/orbit_client.py에 대한 docstring 변경이 그룹 내 다른 세 개 프로젝트에 걸쳐 있는 14개의 의존성 파일들을 찾아냈습니다. diff를 스크롤해서 내려보는 것만으로는 아무도 이를 잡아낼 수 없습니다.

작동 원리

이 flow는 diff가 실제로 어떤 함수를 건드렸는지 식별하기 위해 3단계 전략을 사용합니다:

Orbit 그래프에서의 DEFINES 순회 (파일에서 정의로 이어지는 edge)
Rust crate를 위한 fallback으로서의 fqn-fragment 쿼리
최후의 수단으로서의 제한된 페이지 스캔(Bounded page scan)

각 단계는 출력 결과에서 서로 다른 신뢰 수준(confidence level)을 생성합니다. 이러한 중복성(redundancy)은 매우 중요한데, 라이브 Orbit 인스턴스에서의 쿼리 가용성이 보장되지 않기 때문입니다. 테스트 중에 DEFINES, IMPORTS, CALLS 및 정의 필터링(Definition filtering)이 각각 독립적으로 2시간의 시간 동안 사용할 수 없었던 적이 있었습니다. 특정 쿼리가 살아있을 때만 작동하는 flow는 유용하지 않습니다.

의존성(dependents)의 경우, 이 flow는 Rust를 위해 FQN 및 crate-relative 형태 모두에서 ImportedSymbol 조회를 수행하며, Python 파일의 경우 identifier_name stem을 사용합니다. 마지막 방식은 알아내는 데 시간이 좀 걸렸습니다. Python의 상대 임포트(from . import module)는 Orbit에 저장될 때 점으로 구분된 경로(dotted path)가 아니라, import_path는 패키지 이름으로, identifier_name은 모듈 stem으로 설정됩니다. 저희는 실제 그래프 데이터를 읽음으로써 이 사실을 발견했습니다.

Reviewer Brief는 동일한 에이전트 턴 (agent turn) 내에서 create_merge_request_note를 두 번째로 호출하는 것입니다. 저희는 다른 두 가지 접근 방식이 실패한 후에 이 방식에 도달했습니다. 첫 번째는 시작조차 되지 않았던 라우터 체인 방식 (router-chained)의 두 번째 AgentComponent였고, 두 번째는 첫 번째 흐름 (flow)과 트리거를 조용히 공유하는 것으로 밝혀진 두 번째 앰비언트 흐름 (ambient flow)이었습니다. 가장 최근에 활성화된 것만 실행되는데, 이 내용은 어디에도 문서화되어 있지 않아 진단하는 데 시간이 걸렸습니다.

저장소 구성 요소

flows/change-passport/change-passport.yaml   - Duo Agent Platform 흐름 (flow)
skills/ask-orbit-passport/SKILL.md           - 동반 Duo Chat 에이전트 (agent)
engine/passport_runner.py                    - CLI 러너 (runner), 모든 MR에 게시
...

사용해 보기

이 흐름 (flow)은 AI Catalog에서 라이브로 제공됩니다. 저장소는 공개되어 있으며 MIT 라이선스를 따릅니다.

저장소 (Repo): https://gitlab.com/gitlab-ai-hackathon/transcend/38491653
흐름 (Flow): https://gitlab.com/gitlab-ai-hackathon/transcend/38491653/-/automate/flows/1011552/
에이전트 (Agent): https://gitlab.com/gitlab-ai-hackathon/transcend/38491653/-/automate/agents/1011562
데모 MR: https://gitlab.com/gitlab-ai-hackathon/transcend/38491653/-/merge_requests/5

GitLab Transcend Hackathon을 위해 제작되었습니다.

diff는 무엇이 변경되었는지를 보여줍니다. Orbit Change Passport는 그 변경이 무엇을 의미하는지를 보여줍니다.