모든 JavaScript 프로젝트를 위한 Obsidian 스타일의 코드 인텔리전스 그래프 구축하기

대부분의 의존성 그래프(dependency graphs)는 처음 30초가 지나면 쓸모가 없어집니다.

그것들은 연결 관계를 보여줍니다.

하지만 무엇이 중요한지는 알려주지 않습니다.

TokenCap v0.6을 구축하면서, 저는 다른 질문에 답하고 싶었습니다:

대규모 코드베이스를 처음 열었을 때, 어떤 파일에 주목해야 하는가?

그 질문은 TokenCap의 그래프 엔진을 완전히 재설계하는 계기가 되었습니다. 또 다른 의존성 시각화 도구(dependency visualizer)를 만드는 대신, 저는 제가 '코드 인텔리전스 그래프 (Code Intelligence Graph)'라고 부르는 것을 만들기 시작했습니다.

문제점

전통적인 프로젝트 그래프는 다음과 같은 정보를 알려줍니다:

파일 A가 파일 B를 임포트(imports)함
파일 B가 파일 C를 임포트(imports)함
파일 C가 파일 D를 임포트(imports)함

수백 개의 파일이 지나고 나면, 그래프는 거미줄처럼 변합니다.

보기에는 흥미로울 수 있습니다.

하지만 의사 결정에는 유용하지 않습니다.

개발자들이 실제로 알고 싶은 것은 다음과 같습니다:

어떤 파일이 영향력이 큰가? (high impact)
어떤 파일이 변경하기 위험한가? (risky to change)
어떤 모듈들이 밀접하게 결합되어 있는가? (tightly coupled)
코드베이스의 어느 영역들이 서로 속해 있는가?
AI가 어떤 파일을 가장 먼저 봐야 하는가?

접근 방식

TokenCap v0.6은 저장소(repository)를 분석하고 모든 노드(node)에 인텔리전스를 할당합니다.

각 파일은 다음을 부여받습니다:

노드 유형 (node type)
클러스터 (cluster)
중요도 점수 (importance score)
위험도 점수 (risk score)
의존성 관계 (dependency relationships)

현재 그래프는 13가지 노드 유형을 지원합니다:

Routes (라우트)
APIs (API)
Components (컴포넌트)
Controllers (컨트롤러)
Services (서비스)
Databases (데이터베이스)
Middleware (미들웨어)
Configs (설정)
Utilities (유틸리티)
Hooks (훅)
Packages (패키지)
Tests (테스트)
Unknown files (알 수 없는 파일)

파일의 벽을 보는 대신, 애플리케이션의 구조를 즉시 이해할 수 있습니다.

위험도 점수 산정 (Risk Scoring)

가장 유용한 추가 기능 중 하나는 위험 분석(risk analysis)이었습니다.

모든 파일은 다음과 같이 분류됩니다:

CRITICAL (심각)
HIGH (높음)
MEDIUM (중간)
LOW (낮음)

예를 들어:

연결성이 매우 높은 인증 미들웨어(authentication middleware)는 고립된 유틸리티 함수(utility function)를 수정하는 것보다 훨씬 더 위험합니다.

당연한 소리처럼 들릴 것입니다.

하지만 이를 시각화하는 것은 코드베이스를 탐색하는 방식을 변화시킵니다.

코드베이스 클러스터링 (Clustering the Codebase)

그래프는 관련 파일을 다음과 같은 클러스터로 자동 그룹화합니다:

Authentication (인증)
Payments (결제)
Dashboard (대시보드)
Database (데이터베이스)
API (API)
Frontend (프론트엔드)
Config (설정)
Testing (테스트)

이 기능은 대규모 저장소(repository)를 훨씬 더 작게 느껴지게 만들어주기 때문에, 결과적으로 제가 가장 좋아하는 기능 중 하나가 되었습니다.

뷰어(Viewer) 구축하기

그래프 뷰어는 3개의 패널 레이아웃을 사용합니다:

필터 및 그래프 컨트롤 (Filters and graph controls)
대화형 그래프 캔버스 (Interactive graph canvas)
노드 인텔리전스 패널 (Node intelligence panel)

사용자는 다음과 같은 작업을 할 수 있습니다:

• 노드에 마우스를 올려 의존성 (dependencies) 확인
• 글로벌(global) 및 로컬(local) 그래프 모드 간 전환
• 유형(type) 또는 클러스터(cluster)별 필터링
• 영향도(impact), 리스크(risk), 관계(relationships) 조사
• 아키텍처(architecture)를 시각적으로 탐색

목표는 코드 탐색이 전통적인 의존성 도구보다는 Obsidian의 지식 그래프(knowledge graph)에 더 가깝게 느껴지도록 만드는 것이었습니다.

배운 점들

v0.6을 구축하며 얻은 가장 큰 교훈은 개발자들에게 더 많은 정보가 필요한 것이 아니라는 점입니다.

그들에게 필요한 것은 더 나은 우선순위 지정 (prioritization)입니다.

하나의 저장소(repository)에는 수천 개의 파일이 포함되어 있을 수 있습니다.

하지만 실제로 아키텍처(architecture), 리스크(risk), 의사 결정(decision making)을 주도하는 것은 아주 적은 비율에 불과합니다.

과제는 이러한 파일들을 빠르게 식별하는 것입니다.

그것이 바로 제가 이 그래프를 통해 해결하고자 했던 문제입니다.

다음 단계는?

그래프는 이미 기능적이고 유용하지만, 여전히 제가 개선하는 데 가장 관심이 많은 분야입니다.

향후 반복(iterations) 버전은 더 풍부한 관계(relationships), 더 스마트한 영향 분석(impact analysis), 그리고 AI 지원 워크플로(AI-assisted workflows)와의 더 긴밀한 통합에 집중할 것입니다.

장기적인 목표는 간단합니다:

개발자와 AI 모두가 프로젝트를 더 빠르게 이해하도록 돕는 것입니다.

더 많은 코드를 보여줌으로써가 아니라,

중요한 것이 무엇인지 보여줌으로써 말입니다.

npm package - https://www.npmjs.com/package/tokencap
website - tokencap.vansharora.app