coldteadotai/pr-lens

PR Lens – 풀 리퀘스트 시각적 리뷰

기능

• 풀 리퀘스트(PR)가 열리면 PR Lens은 변경 사항에 대한 애니메이션 아키텍처 다이어그램을 포함한 댓글을 게시합니다. 이 다이어그램은 추가, 수정, 삭제된 파일, 서비스 또는 컴포넌트(녹색/황색/빨간색)와 그 사이의 데이터 흐름을 보여줍니다.
• 댓글은 상호작용이 가능합니다: <details> 섹션으로 확장되어 전체 '영향 범위', 새 코드 경로, 또는 폐기된 부분에 집중할 수 있습니다.
• 각 다이어그램은 전체 크기 캔버스에서 열 수 있으며, 줌/팬 기능과 라이트/다크 테마 전환 기능을 제공합니다. 워크스루 모드는 변경 사항을 단계별로 따라가며 영향을 받은 노드와 경로를 강조 표시합니다.

사용 방법

1. GitHub App – 어떤 리포지토리든에 coldtea‑pr‑lens 앱을 설치합니다. 앱은 각 PR을 자동으로 분석하고 SVG를 렌더링하며, 모든 푸시마다 댓글을 업데이트합니다.
2. GitHub Action – CI에서 동일한 분석을 수행하는 워크플로우(.github/workflows/pr‑lens.yml)를 추가합니다. 자체 LLM API 키를 사용할 수 있습니다(Gemini가 기본이지만 OpenAI 또는 /chat/completions 엔드포인트도 지원).
3. CLI – @coldtea/pr‑lens‑cli를 로컬에서 실행하여 diff를 분석하고 SVG를 렌더링하며, 마크다운 댓글을 생성하고 생성된 그래프를 검증하거나 시스템의 지속 가능한 맵을 내보낼 수 있습니다.
4. 에이전트 스킬 – 스킬(npx skills add coldteadotai/pr‑lens)을 설치하면 코딩 어시스턴트(Claude, Gemini, Copilot 등)가 그래프 문서를 자동으로 생성하고 댓글을 게시할 수 있습니다.

핵심 구성 요소

패키지	역할
@coldtea/pr‑lens‑schema	모든 구성 요소 간에 공유되는 그래프 계약을 정의하는 JSON 스키마
@coldtea/pr‑lens‑renderer	JSON 그래프를 결정론적이고 애니메이션 가능한 SVG(라이트/다크 쌍)로 변환
@coldtea/pr‑lens‑cli	LLM과 상호작용하여 git diff를 그래프로 변환하고, SVG를 렌더링하며, 댓글을 구성하고 검증하며, 맵을 내보낼 수 있는 CLI
pr‑lens GitHub Action	CI 친화적인 래퍼로 CLI를 실행하고 정적 댓글을 게시
@coldtea/pr‑lens‑agent‑skill	코딩 에이전트가 그래프를 생성하고 게시할 수 있도록 가르치는 작은 '스킬'

설정

• .github/pr‑lens.yml 파일을 추가하여 파일 이름을 변경하거나 제외하거나 그룹화하거나 레인을 고정할 수 있습니다. 이 파일은 코드가 진화해도 유효한 오버레이입니다.
• CLI는 자동으로 .pr‑lens/ 폴더(git 무시)를 생성하여 임시 파일을 저장합니다. 커밋할 수 있는 유일한 아티팩트는 내보낸 맵(.github/pr‑lens.map.json)입니다.

왜 중요한가 큰 PR을 리뷰하는 것은 정신적으로 부담이 큽니다. PR Lens는 텍스트 기반의 diff를 시각적 지도로 변환하여 시스템의 어떤 부분이 영향을 받았는지, 데이터가 어떻게 흐르는지 보여주며, 코드를 줄 단위로 읽기 전에 영향을 파악할 수 있게 해줍니다.

실제 예시 보기

• '홀 오브 페임'에 링크된 실시간 예시(예: React Hooks, Node fetch, Kubernetes Ingress, vLLM). 각각은 PR Lens로 렌더링된 실제 PR을 보여줍니다.
• 웹 UI(prlens.dev)는 인터랙티브 캔버스를 호스팅합니다.

시작하기

# GitHub App 설치 (또는 Action 추가)
# 또는 로컬에서 실행:
export GEMINI_API_KEY=YOUR_KEY   # 또는 OPENAI_API_KEY
npx @coldtea/pr-lens-cli analyze --base origin/main
npx @coldtea/pr-lens-cli render .pr-lens/graph.json
open .pr-lens/*-dark-*.svg

라이선스 – MIT.