Mutrix

프로젝트의 코드 구조와 변경 크기를 탐색하는 로컬 분석 도구입니다. 폴더 → 파일 → 함수·클래스·메서드를 가로 Icicle 차트로 펼치며, 결과는 외부 서버 없이 열리는 단일 HTML입니다.

사용

Windows x64 실행 파일은 dist/mutrix.exe입니다. 분석할 프로젝트에서 실행합니다.

E:\repos\mutrix\dist\mutrix.exe . --open

mutrix.exe C:\projects\app `
  --base main `
  --output C:\reports\app.html `
  --json C:\reports\app.json `
  --summaries changes.json `
  --exclude "**/fixtures/**" `
  --open

인수	동작
[path]	분석할 폴더. 기본값은 현재 폴더이며 Git 저장소 안에서는 Git 루트부터 분석합니다.
--base <ref>	기준 브랜치 또는 커밋을 직접 지정합니다.
--output <path>	HTML 출력. 기본값은 지정 폴더의 mutrix-report.html입니다.
--json <path>	같은 분석 결과를 JSON으로 추가 출력합니다.
--summaries <path>	노드별 설명 JSON을 보고서에 내장합니다.
--exclude <glob>	제외 패턴을 추가합니다. 반복 지정할 수 있습니다.
--open	생성한 보고서를 기본 브라우저에서 엽니다.
--help, --version	사용법·버전을 출력합니다.

실행에는 Bun이나 Node가 필요하지 않습니다. Git 변경 비교에는 PATH에 Git이 있어야 합니다. 생성한 HTML은 다른 폴더나 컴퓨터로 옮겨도 Chromium 계열 브라우저에서 오프라인으로 열 수 있습니다. 경로 복사와 VS Code 링크는 보고서에 기록된 원래 프로젝트 경로를 사용합니다.

출력과 Summary 경로는 서로 달라야 합니다. 기존 Mutrix 보고서는 다시 생성할 수 있지만, 일반 소스 파일을 출력으로 지정하면 덮어쓰지 않고 오류로 종료합니다.

비교 기준

• 기준 자동 선택은 로컬 master, 로컬 main, origin/master, origin/main 순서입니다. 네트워크 fetch는 하지 않습니다.
• 기준 브랜치에서 실행하면 현재 작업 폴더의 구조를 표시합니다.
• 다른 브랜치에서는 기준과 HEAD의 merge-base부터 현재 작업 폴더까지 비교합니다. 커밋·스테이징·미커밋·신규 파일의 최종 내용을 포함합니다.
• 기준 브랜치만 새 커밋을 얻어도, 기능 브랜치의 분기점은 그대로 사용합니다.
• Git이 없거나 자동 기준이 없으면 구조 모드와 설명을 제공합니다. 잘못된 명시적 기준 또는 공통 조상이 없는 비교는 오류입니다.
• 프로젝트를 checkout하거나 파일·인덱스를 수정하지 않습니다. 생성 도중 편집을 계속하면 파일마다 읽은 시점이 다를 수 있으므로, 일관된 전체 스냅샷이 필요하면 편집을 멈추고 생성하세요.

라인 수와 차트

LOC는 주석·빈 줄을 포함한 물리적 줄 수입니다. 빈 파일은 0줄이고, 파일 끝 개행은 가상의 추가 줄을 만들지 않습니다. 줄 추가·삭제 비교에서는 CRLF/LF와 마지막 개행의 차이만 있는 경우를 제외합니다. 원본 내용 변경 상태는 유지합니다.

JS·JSX·TS·TSX·MJS·CJS·MTS·CTS에서는 클래스, 생성자, 메서드, 접근자, 함수 선언·표현식, 화살표 함수, 내부 중첩 함수를 분석합니다. 블록문과 인터페이스·타입 선언은 독립 스코프가 아니며 소유 스코프의 코드로 집계됩니다. 다른 UTF-8 텍스트는 파일 단위로 표시합니다. 구문 오류는 파일 LOC를 유지하고 스코프 분석만 생략합니다.

각 줄은 가장 깊은 스코프가 소유하고, 같은 줄에서 동률이면 소스상 먼저 등장한 스코프가 소유합니다. 부모 LOC는 자기 영역과 자식 영역의 합입니다. 상세 패널의 원본 줄 범위와 소유 LOC가 다를 수 있으며, 같은 줄의 짧은 심볼은 0 LOC여도 트리·검색에서 선택할 수 있습니다. 심볼 밖 영역은 기타 코드로 남깁니다.

구조 모드의 높이는 현재 LOC입니다. 변경 모드에서는 말단 영역별 전후 큰 값을 사용한 비교 표시 LOC로 삭제 영역도 보존합니다. 따라서 비교 높이는 실제 현재 LOC보다 클 수 있습니다. 필터와 부분 확대는 표시 범위의 높이를 다시 계산합니다.

표시	의미
초록	(현재 LOC − 기준 LOC) / 기준 LOC가 양수입니다. 증가율 100%에서 가장 진합니다.
빨강	같은 비율이 음수입니다. 감소율 100%에서 가장 진합니다.
가장 진한 초록, +∞	새 영역입니다.
가장 진한 빨강, 잔존 0%	삭제한 영역입니다.
중립색과 테두리	내용은 수정했지만 순증감이 0입니다.
낮은 opacity	변경이 없습니다.

추가·삭제 줄 수와 순증감은 별도 지표입니다. 이름이나 소속이 바뀐 심볼은 기존 ID와 대응할 수 없으므로 추가·삭제로 나타날 수 있습니다. 파일 이동은 구·신 경로에서 각각 집계하고 Git이 검출한 rename 관계로 연결합니다. 이동 자체도 해당 경로의 추가·삭제에 포함되며 프로젝트 전체 LOC 순증감은 상쇄됩니다.

차트의 변경 모드에서 파일은 130 → 349 LOC처럼 기준·현재 줄 수를 표시하고 순증감은 이름 옆 +219 배지로 표시합니다. 폴더·심볼의 순증감도 같은 배지를 사용합니다. 실제로 추가·삭제된 노드에는 NEW·DEL을 표시하며 중복되는 순증감 배지는 생략합니다. 기존 파일을 0줄로 비운 경우는 삭제로 표시하지 않습니다. 공간이 부족한 영역은 확대하거나 상세 패널에서 수치를 확인할 수 있습니다.

파일·심볼의 현재 LOC가 500줄을 초과하면 눈에 잘 띄는 노란색 WARN 배지를 함께 표시합니다. +43 WARN·NEW WARN처럼 표시할 수 있으며 구조 모드에서도 사용합니다. 폴더 합계·기타 코드·이미 삭제된 심볼에는 크기 경고를 적용하지 않습니다. 왼쪽 아래 표시 설정에서 양의 정수로 기준을 바꾸고 Enter 또는 입력란 밖 클릭으로 적용합니다. 설정은 해당 보고서 세션에 적용되며 초기화는 500줄로 되돌립니다.

클릭하면 상세 정보를 봅니다. 차트·트리·검색에서 폴더·심볼을 더블클릭하면 하위 영역으로 들어가고, 파일을 더블클릭하면 VS Code 파일 링크를 실행합니다. 삭제 파일은 열지 않습니다. 파일 안의 심볼을 차트에서 집중해서 보고 싶으면 상세 패널의 영역 확대를 사용합니다. 배율 버튼을 누르면 함께 / 가로 / 세로 확대 축을 선택하고 각 축의 배율을 별도로 조절할 수 있습니다. 기본 함께 확대에서는 가로가 1.5배까지 커지고 이후에는 세로만 확대합니다. 축소도 세로가 1.5배로 내려올 때까지 가로를 유지하고 이후 두 축을 함께 줄입니다. 가로·세로 배율이 다르면 두 값을 표시합니다. 가로를 직접 1.5배 이상으로 조절할 수 있으며, 이 경우 함께 확대·축소는 수동 가로 배율을 유지합니다. 휠·핀치와 +/− 버튼은 선택한 축에 적용하며 글꼴·아이콘 크기는 유지합니다.

드래그로 이동하고, Shift+스크롤로 가로 이동합니다. 차트에 포커스한 상태에서 +, -로 선택 축을 확대·축소하고, Home이나 초기화 버튼으로 두 배율과 위치를 초기화할 수 있습니다. 트리·검색 결과는 Tab과 Enter로 선택하며 트리에서는 좌우 화살표로 펼치고 접습니다.

세로 높이가 2px 미만인 형제 영역은 LOD 집계 띠로 합쳐집니다. 가로 확대만으로는 집계를 해제하지 않습니다. 집계 띠의 증가·감소는 따로 표시하고 더블클릭하면 가로 폭을 유지하며 해당 띠를 세로로 확대합니다. 화면 밖 하위 트리는 그리지 않습니다. 미니맵은 두 배율에 맞는 표시 범위를 보여주며 클릭으로 화면 위치를 이동할 수 있습니다.

일반 폴더는 루트를 포함해 기본 줌에서 48px 폭과 세로 라벨로 표시합니다. 패키지로 인식한 폴더는 파일처럼 200px 기본 폭과 가로 라벨을 사용하며 더블클릭 탐색은 폴더처럼 동작합니다. 심볼·기타 코드의 기본 폭은 100px이며 중첩 깊이에 따라 줄이지 않습니다. 화면 크기에 맞춰 패키지·파일·심볼 폭에 같은 배율을 적용하므로 심볼은 파일 폭의 절반을 유지합니다. 같은 깊이에 폴더와 파일이 섞여 있어도 각 자식은 자기 부모의 오른쪽에 이어집니다. 영역에 들어가면 그 영역 기준으로 배치와 화면 맞춤을 다시 계산하고 줌·이동을 초기화합니다. 들어간 폴더·심볼을 다시 더블클릭하거나 뒤로가기를 누르면 직전 영역의 줌·이동 위치·필터·표시 모드를 복원합니다. 미니맵도 동일한 열 비율을 사용합니다.

분석에 포함된 package.json이 유효한 JSON 객체이면 그 폴더를 패키지 아이콘으로 표시합니다. 루트·중첩 패키지·이름 없는 비공개 패키지도 포함합니다. npm 계약에 따라 게시하지 않는 패키지에 이름·버전을 요구하지 않습니다. 보고서의 선택 필드 package.before/after에 시점별 존재와 이름을 저장하므로 삭제된 패키지도 기준 아이콘을 유지합니다. 잘못된 JSON은 진단에 기록하고 패키지로 표시하지 않습니다. 제외된 매니페스트는 패키지 판별에 사용하지 않습니다.

Rust의 .rs 파일은 트리·차트에서 같은 Rust 아이콘을 사용합니다. 포함된 Cargo.toml은 Bun의 TOML 파서로 읽고 [package]와 비어 있지 않은 문자열 name이 있으면 crate 패키지로 표시합니다. version.workspace = true 등 워크스페이스 상속 선언을 허용하며 Cargo 실행·빌드는 하지 않습니다. [workspace]만 있는 가상 워크스페이스는 crate로 표시하지 않습니다. 같은 폴더의 package.json과 충돌하면 시점별로 Cargo 패키지를 우선합니다. 선택 필드 package.before/after.kind: "cargo"를 기록하며 상세 패널은 crate · 이름을 표시합니다. 잘못된 TOML·이름 없는 [package]는 진단을 남기고 파일 LOC는 유지합니다. crate도 기존 패키지와 같은 가로 배치·아이콘·설명·폴더 탐색 동작을 사용합니다. Rust AST 심볼 분석은 수행하지 않습니다.

Summary JSON

JSDoc과 변경 Summary는 패키지·파일·심볼 노드의 이름·라인 수 아래에 직접 표시합니다. 일반 폴더에는 설명을 넣지 않고 이름 옆 정보 아이콘으로 설명이 있음을 표시하며 내용은 툴팁에서 확인합니다. 노드가 작으면 설명을 생략하고 확대하면 표시합니다. Summary는 변경:으로 구분하며 툴팁에서도 확인할 수 있습니다. 함수·클래스·메서드·접근자뿐 아니라 변수·필드·프로퍼티에 달린 JSDoc도 읽고 @param 등의 태그와 줄바꿈을 일반 텍스트로 유지합니다. 보고서의 선택 필드 documentation.before/after에 설명을 저장합니다. 현재 주석이 제거되면 기준 설명을 대신 표시하지 않으며, 삭제 심볼에만 기준 설명을 표시합니다. 주석만 수정해도 해당 심볼을 변경으로 표시하지만 주석 줄의 기존 LOC 소유 관계는 유지합니다.

함수·화살표 함수·함수 표현식·메서드·접근자는 노드 안에 인자 이름 옆에 타입을 작은 배지로 표시하고 디바이더 아래에 return과 반환 타입 배지를 표시합니다. 나머지 인자에는 ...를 붙입니다. 코드에 명시된 타입만 사용하며 선언이 없는 타입은 unknown입니다. 외부 의존성이나 프로젝트 전체 타입 추론은 실행하지 않습니다. 작은 노드에서는 생략하고 확대하면 표시하며, 긴 타입·많은 인자는 화면 공간에 맞춰 줄입니다. 선택 필드 signature.before/after에 시점별 시그니처를 저장하고 삭제 심볼에는 기준 시그니처를 표시합니다. 이전 보고서처럼 필드가 없는 경우에는 표시를 생략합니다.

{
  "schemaVersion": 1,
  "entries": [
    {
      "nodeId": "file:src/parser.ts",
      "summary": "파싱 처리를 분리하고 중복 검증을 제거했습니다."
    },
    {
      "nodeId": "scope:src/parser.ts#function:parse~1",
      "summary": "블록 경계를 명시적으로 처리합니다."
    }
  ]
}

먼저 --json으로 결과를 얻고, JSON의 노드 ID를 사용해 설명을 작성한 뒤 --summaries로 다시 생성합니다. 폴더·파일·스코프 모두 설명을 붙일 수 있습니다. 보고서의 상세 패널에서도 ID를 복사할 수 있습니다. ID는 경로와 심볼 계층·종류·이름·동명 순서로 구성하고 줄 번호 이동만으로 바뀌지 않습니다. 익명 콜백이나 동명 심볼의 순서를 바꾸면 ID가 달라질 수 있습니다.

보고서의 Summary 불러오기 버튼도 같은 형식을 받습니다. 화면에서 불러온 설명은 해당 세션에만 반영합니다. 중복 ID는 첫 설명을 유지하고, 모르는 ID는 건너뛰며 각각 진단을 남깁니다. 설명은 HTML이 아닌 일반 텍스트로 출력합니다.

JSON 보고서는 schemaVersion, meta, rootId, nodes, diagnostics로 구성합니다. 노드는 id, parentId, children, 종류·경로·이름, 전후 줄 범위·LOC, delta, added, removed, status, weight, 선택적 summary·rename을 제공합니다. 소스 본문이나 AST는 HTML·JSON에 포함하지 않습니다. 분석 계약은 src/shared/types.ts에 있습니다.

Codex로 PR 결과 확인

레포에 mutrix-pr-review 스킬이 포함되어 있습니다. .agents/skills는 OpenAI 공식 문서의 레포 스킬 위치를 따릅니다. Codex에서 $mutrix-pr-review로 이 PR의 결과를 확인하고 Summary가 붙은 HTML 보고서를 만들어줘처럼 요청하면 사용합니다.

PR head·기준 ref 확인 → JSON 분석 → 실제 diff 검토 → 노드 ID로 Summary 작성 → HTML에 설명 내장 순서로 진행합니다. 미커밋 변경이 섞인 결과는 작업 폴더 스냅샷으로 구분하며, 리뷰 결과를 원격에 게시하지 않습니다. 다른 레포에서 쓰려면 mutrix-pr-review 폴더를 해당 레포의 .agents/skills/ 또는 개인 스킬 폴더에 복사하고 Mutrix 실행 파일 경로를 알려주세요.

분석 대상과 v1 경계

Git 추적 파일과 Git이 무시하지 않는 신규 파일을 분석합니다. .git, node_modules, vendor, dist, build, target, coverage, .next, .cache, artifacts, .venv, __pycache__와 일반적인 lockfile은 기본 제외합니다. 추가 제외 규칙은 기준·현재 상태에 동일하게 적용합니다. 출력 HTML·JSON과 입력 Summary도 제외합니다. 심볼릭 링크·서브모듈 내부·바이너리·UTF-8로 해석할 수 없는 파일은 분석하지 않습니다. Git 저장소가 아닌 폴더에서는 기본 제외 규칙으로 폴더를 순회합니다.

Git 저장소에서는 linguist-generated가 설정되거나 true인 파일을 기본 제외합니다. Git의 check-attr로 중첩 .gitattributes, 매크로, 예외 규칙과 로컬 속성 설정을 일괄 해석합니다. false, -linguist-generated, 미지정은 생성 파일로 판단하지 않습니다. 파일을 읽거나 LOC·AST·diff를 계산하기 전에 제외하므로 파일·폴더·패키지·루트 수치와 차트 높이에서도 빠집니다. 파일명이나 주석으로 생성 여부를 추측하지 않습니다.

변경 모드에서는 merge-base의 속성과 현재 작업 폴더의 속성을 확인하고, 어느 쪽에서든 생성 파일인 경로를 양쪽에서 제외합니다. 속성 변경만으로 대량 추가·삭제가 나타나는 것을 방지합니다. 생성 표시를 해제했어도 기준에서 생성 파일이면 이번 비교에서는 제외됩니다. 생성 결과를 검토하려면 --include-generated를 사용합니다. 이 옵션은 생성 파일 필터만 해제하며 기존 제외 glob·lockfile·바이너리 제외는 유지합니다. JSON의 선택 필드 meta.generatedExclusions에 제외 경로·속성·해당 시점(baseline/current)을 기록하고 진단에 제외 경로 수를 표시합니다.

기준 속성 조회에는 git check-attr --source를 지원하는 Git 2.40 이상이 필요합니다. 속성을 조회하지 못하면 누락 없이 오류로 종료하며 --include-generated로 우회할 수 있습니다. Git 저장소가 아니거나 Git을 사용할 수 없으면 속성 규칙을 적용하지 않고 기존 구조 모드로 분석합니다.

v1은 리팩토링 점수나 자동 판정을 제공하지 않습니다. 다중 언어 AST, 실시간 감시, 전체 소스 diff 뷰, Explorer 직접 실행, 전용 데스크톱 창은 포함하지 않습니다. 삭제 노드는 원래 경로와 기준 범위를 표시하며 VS Code 열기를 비활성화합니다. 보고서는 생성 시점의 스냅샷이므로 새 변경은 다시 생성해야 합니다.

개발과 검증

UI·경로·노드 ID·차트 라벨은 모두 SUIT 가변 글꼴을 사용합니다. 글꼴은 HTML에 내장되어 오프라인으로 동작합니다. SUIT의 저작권 고지와 OFL 1.1 전문은 보고서의 diagnostics → Font license에서 확인할 수 있습니다. 표시 범위는 breadcrumb 옆 배지로, 현재 LOC는 차트 첫 열의 이름 옆에 표시합니다. 차트 조작 안내는 확대·축소 버튼 옆의 ? 버튼에서 열 수 있습니다.

파일 아이콘은 Simple Icons의 필요한 SVG만 번들에 포함합니다. TSX·JSX는 React, TS·MTS·CTS는 TypeScript, JS 계열은 JavaScript이며 JSON·CSS·HTML·Markdown·Python·Go·YAML·TOML·Dockerfile·Svelte도 구분합니다. 트리·검색·상세 패널과 Canvas에서 같은 로고를 사용하고 차트의 변경 색상과 혼동되지 않도록 단색으로 표시합니다. 모든 아이콘은 HTML에 내장되며 Simple Icons 패키지는 CC0-1.0입니다.

현재 검증 환경은 Bun 1.3.6과 Windows x64입니다. 브라우저 자동 검증에만 Node와 설치된 Chromium 계열 브라우저가 추가로 필요합니다.

bun install --frozen-lockfile
bun run dev
bun run typecheck
bun test tests
bun run format:check
bun run build
bun run demo
bun run verify:browser
bun run verify:exe

build는 뷰어를 먼저 빌드한 다음 HTML 템플릿을 내장한 exe를 생성합니다. analyze도 내장 템플릿을 사용하므로 먼저 build:viewer를 실행해야 합니다. 개발 서버와 demo는 설명용 합성 데이터를 표시하며 실제 저장소 분석 결과로 표시하지 않습니다.

브라우저 검증은 기본적으로 Windows Chrome을 사용합니다. 다른 실행 파일을 지정하려면 $env:MUTRIX_BROWSER에 절대 경로를 설정하세요. 외부 HTTP 요청을 차단한 상태에서 이동한 HTML, 검색·선택·필터·확대·Summary·테마·모바일을 확인하고, 정확히 10만 노드로 최초 표시 ≤5초·프레임 p95 ≤50ms를 검증합니다. 측정 환경과 결과는 artifacts/verification.json, exe 검증은 artifacts/exe-verification.json에 기록합니다.

모듈 경계는 src/analysis의 파일·Git·AST 분석, src/shared의 데이터·Summary·색상 계약, src/report의 HTML 직렬화, src/cli의 입력·출력·브라우저 실행, src/viewer의 탐색·레이아웃·Canvas 렌더링입니다. AST·Git 의존성은 프런트엔드 번들에 포함되지 않습니다.