repoviz

repoviz은(는) 무엇을 하나요?

코드베이스를 렌더링 가능한 다이어그램 URL로 변환합니다. 모든 다이어그램은 단일 https://x-cmd.com/draw URL(플랫, 퍼센트 인코딩된 파라미터)로, 브라우저, GitHub README, 모든 마크다운 뷰어에서 SVG를 렌더링합니다. 기본 모드는 로컬 파일을 전혀 쓰지 않습니다. 로컬 내보내기는 scripts/를 통한 명시적 요청 시에만 발생합니다.

렌더링 ≠ 진실: 모든 노드와 엣지는 소스 증거(verified / inferred / unknown)를 포함합니다. 출력물은 AI 스케치가 아닌 검증 가능한 아티팩트입니다.

1단계 — 의도 분석 및 차트 라우팅

의도 + 리포지토리 형태에서 다이어그램 유형을 선택하세요. 해당 다이어그램을 구성하기 전에 일치하는 references/ 파일만 읽으세요.

사용자 의도	다이어그램	참고 문서
시스템 개요, 폴더 계층, 마이크로서비스, 기술 스택	아키텍처 맵 (/draw/archmap)	references/architecture.md
요청 수명 주기, 함수 호출 체인, API 핸드셰이크	시퀀스 다이어그램 (/draw/seq)	references/flowchart.md
분기 로직, 알고리즘, 인증/파이프라인 단계	순서도 (/draw/mermaid)	references/flowchart.md
상태 머신, 상태, 재시도/롤백	수명 주기 (/draw/lifecycle)	references/flowchart.md
데이터 파이프라인, 종속성/번들 가중치, 트래픽 라우팅	생키 (?type=sankey)	references/sankey.md
기능 트리, 모듈 분류	마인드 맵 (/draw/mindmap)	references/general-charts.md
로드맵, 일정, 릴리스 계획	간트 (/draw/gantt)	references/general-charts.md
정량적 리포지토리 지표(언어 분포, 커버리지, 성장)	데이터 차트 (`?type=pie	hbar
광범위한 "이 리포지토리 시각화"	다중 다이어그램 세트: 1개 archmap 개요 + 1개 생키(데이터/종속성 흐름) 또는 seq(핵심 요청 흐름)	두 개의 일치하는 참고 문서

archmap의 동일 문법 하위 유형(references/architecture.md 참조): arch2 (대체 스킨). 데이터/동작 모델링: uc, dataflow, erd, class — 문법 및 라이브 예제는 references/technical-diagrams.md 참조. 긴 꼬리 차트(트리맵, 퍼널, 그래프, ...): /draw/echarts?d=<url-encoded echarts option JSON>.

스캔 모드 — 코드를 읽기 전에 스캔 범위를 설정하세요(사용자가 선택 가능, 기본값은 의도 기반):

모드	범위	일반적인 출력
quick	매니페스트, 깊이 2의 트리, 진입점	1개 개요 다이어그램
architecture	모듈, 서비스, 종속성 그래프	archmap (+ 가중치 기반 생키)
deep-dive	호출 체인, 데이터 흐름, 상태 머신	seq / 순서도 / 생키 세트
impact	git diff 대비 베이스: 변경된 파일 및 그 종속 항목	변경 흐름 다이어그램
full	위의 모든 항목	리포지토리 보고서 (세트 + 품질 보고서)

impact 모드는 references/architecture-diff.md(git-diff 델타 워크플로)를 로드합니다. full 모드는 references/codebase-report.md(표준 보고서 구조)를 로드합니다. 동일 리포지토리의 반복 스캔은 references/incremental-scan.md(옵트인 캐시 프로토콜)를 로드할 수 있습니다. 다이어그램 다중 또는 증거 민감 작업은 references/repository-ir.md를 로드합니다.

2단계 — 토큰 절제 코드베이스 스캔

1. 먼저 루트 매니페스트를 읽습니다: package.json, go.mod, Cargo.toml, pyproject.toml, docker-compose.yml 및 깊이 3의 디렉토리 트리와 선언된 진입점.
2. 모든 소스 파일을 읽지 마십시오. 진입점 파일과 라우트 테이블을 샘플링하고, 구성 요소를 신호가 강한 노드와 엣지로 요약합니다.
3. 가능한 경우 실제 수량에서 생키 가중치를 파생합니다: 파일 크기(du -sh), 임포트/참조 수 또는 사용자가 제공하는 트래픽/비용 수치.
4. URL 길이 보호 장치: 하나의 다이어그램을 ~15–20개 노드(생키의 경우 ~60개 링크)로 유지하여 URL을 읽을 수 있고 CDN 한도 내에 있도록 합니다. 대규모 리포지토리의 경우 전체 개요 다이어그램 + 서브시스템당 하나의 다이어그램을 생성하고, 절대 하나의 조밀한 메가 다이어그램을 생성하지 마십시오.
5. 매니페스트에서 언어와 스택을 감지하고 해당 렌즈로 스캔합니다: Go → 패키지/인터페이스/고루틴; TypeScript → 모듈/임포트 그래프/API 라우트; Rust → 크레이트/트레이트/피처; Python → 패키지/데코레이터/진입점.
6. 스캔하면서 증거를 기록합니다: 모든 노드/엣지는 file[:symbol[:lines]]와 수준을 획득합니다 — verified(코드에서 확인됨), inferred(구조에서 파생), 또는 unknown(패턴 가정). 파일을 열지 않고 verified로 표시하지 마십시오.

3단계 — URL 구성

• 먼저 세트용 경량 Repository IR을 구축합니다(하나의 공유 노드 인벤토리, 다이어그램당 하나의 문서). 인코딩 시 IR을 URL에 매핑합니다. 스키마 및 검증 프로토콜: references/repository-ir.md.
• 구성하는 모든 URL은 렌더러에 레이블을 전달합니다 — 구성, 검증 또는 내보내기 전에 4단계 기밀성 규칙을 적용합니다.
• 문법(노드/엣지/경계), 인코딩 테이블, 작업 예제, 유형별 제한은 참고 파일에 있습니다. 정확히 따르십시오. 거기의 모든 예제는 라이브 테스트되었습니다.
• 인코딩 필수 사항: 공백 %20, + %2B, & %26, # %23, </> %3C/%3E, 개행 %0A; 구분자 ; = , : / @`는 리터럴 상태 유지. Base64 없음.
• 일반적인 수정자: title=, scheme=dark|light, t=<style>(참고 문서의 유형별 패밀리 — arch2/seq는 t=shadcn과 가장 잘 어울림; arch2 노드는 선택적 6번째 icon 필드를 사용할 수 있음, 예: n=api;be;API;ECS;r2c0;aws:ecs), w=/h=, v=N으로 캐시된 버전 고정, num=all|peak|none(차트).
• PNG 출력은 GB2312 레벨 1 CJK 서브셋을 포함합니다: 드문 문자(예: 渲)는 PNG에서 토푸(tofu)가 됩니다. SVG에는 이러한 제한이 없습니다 — 중국어 PNG 레이블에는 일반적인 동의어를 선호합니다.
• 4xx 발생 시 응답 본문은 수정 예제가 포함된 일반 텍스트입니다 — 읽고, 문제가 있는 파라미터를 수정한 후 재시도하십시오. 두 번 추측하지 마십시오.

4단계 — 출력 전달

기본 모드 — 파일 쓰기 없음. 다이어그램당 다음과 같이 응답:

### <다이어그램 제목>
![<제목>](<draw-url>)
*[인터랙티브 미리보기](<draw-url>)* · [편집기에서 열기](<explore-url>)

- <글머리 기호: 다이어그램이 보여주는 내용 — 계층, 중요 경로, 가장 큰 흐름>
- <글머리 기호: 주목할 만한 결합도 / 단일 장애점 / 소유권 경계>

• <explore-url>은 /draw?type=X&q → /draw/explore?type=X&q 및 /draw/<name>?q → /draw/explore/<name>?q로 다시 작성 — 드로잉의 내장 인터랙티브 편집기입니다. 링크하세요, 다시 빌드하지 마세요.
• 다이어그램당 2–5개의 간결한 글머리 기호. 이미지가 산출물이며, 글머리 기호는 판단을 추가합니다.
• 기밀성: 렌더링 — 그리고 L1 검증, export.sh 다운로드 —는 URL 파라미터로 다이어그램 레이블(순서도의 경우 전체 프로그램 텍스트)을 x-cmd.com 렌더러로 전송합니다. 이는 서버 액세스 로그에 표시될 수 있으며(퍼센트 인코딩은 암호화가 아님), 마크다운 이미지 임베드는 클라이언트나 프록시에 의해 자동으로 가져올 수 있습니다. 로컬 내보내기는 이를 피하지 않습니다 — 렌더링은 여전히 x-cmd.com에서 요청됩니다. 기밀 리포지토리의 경우 렌더링, 검증 또는 내보내기 전에 사용자에게 경고하고 명시적 승인을 받거나, 로컬에 설치된 드로우 CLI를 통해 완전히 오프라인으로 렌더링하십시오.

품질 보고서로 세트를 마무리합니다(실제 수치만 — 절대 조작하지 마십시오):

리포지토리 분석 — <repo> (<scan_mode>, <commit>)
검사된 파일: N | 모듈: N | 관계: N
증거: verified N · inferred N · unknown N
검증: L1 통과|건너뜀(개인정보) · L2 통과 · L3: N 미해결(아래에 표시)

L1은 자동이 아닙니다 — URL을 가져오므로 다이어그램을 x-cmd.com에 보냅니다. 기밀 리포지토리의 경우 사용자의 명시적 승인(4단계 기밀성 규칙)이 있는 경우에만 실행하고, 그렇지 않으면 L1 건너뜀(개인정보)을 보고합니다. 각 unknown을 해당 다이어그램 아래에 표시합니다. 명시적 "검증" 요청 또는 내보내기 전 확인: bash scripts/validate.sh <urls...>(L1 렌더링) 및 bash scripts/validate.sh --ir <ir.json>(L2 구조). L3는 인용된 파일을 다시 읽는 것입니다.

내보내기 모드 — 사용자가 명시적으로 "로컬 저장", "SVG/PNG 다운로드", "이미지 내보내기", "짧은 링크", "내 README에 추가", 또는 "HTML 보고서 생성"이라고 말할 때만:

bash scripts/export.sh "<draw-url>" "<out.svg|png>"        # 단일 다운로드
bash scripts/export.sh --batch <manifest.tsv>              # 다중: 줄당 "<url>\t<out>", # 주석
bash scripts/shorten.sh <type> '<d-schema json>' [title]   # 영구 /draw/c/<hash> (?type= 차트만)
bash scripts/build_html.sh "<title>" "<out.html>" '<json>'   # 독립형 보고서 (+ 선택적 증거)
bash scripts/inject_readme.sh "<README.md>" '<json>'       # repoviz 마커 사이에 다이어그램 삽입/업데이트

• export.sh는 curl을 통해 다운로드합니다(대안: 로컬에 이미 설치된 CLI 사용 — 패키지 가져오기나 설치를 하지 않음); .png 대상은 자동으로 &format=png를 얻습니다(고해상도를 위해 &scale=2|3 추가, scheme=dark 전달 — PNG는 기본적으로 light 스킴 사용). 배치 모드: 줄당 하나의 url<TAB>output, # 주석 허용; 실패 시 0이 아닌 상태로 종료.
• shorten.sh는 차트 정의(?d= JSON 스키마)를 x-cmd.com에 POST합니다 — 속도 제한 ~30/IP/분. ?type=족만 POST를 수락합니다. 노드/엣지 다이어그램 (/draw/archmap, /draw/seq, ...)은 405를 반환합니다 — 전체 URL을 유지하세요. 반환된 /draw/c/<hash>는 GET으로 렌더링되며 영구적입니다. 사용자의 명시적 요청이 있을 때만 실행하세요: 저장된 정의는 영구적이며 링크를 가진 모든 사람에게 공개됩니다(4단계 기밀성 규칙).
• build_html.sh는 {"title","url","note"[,"ev"]} 객체의 JSON 배열을 받아(url은 https://x-cmd.com / https://www.x-cmd.com 그리기 렌더 URL로 제한; ev 선택 사항, 인코딩된 "node|file|symbol|lines|level;..." — 필터링 가능한 소스 증거 테이블 렌더링) 자체 포함된 다크/라이트 반응형 보고서를 생성합니다: 사이드바 내비게이션, 확대/축소, 전체 화면, URL 복사 버튼, 인쇄-PDF 친화적. 모든 값은 HTML 이스케이프됩니다. 예시 페이로드: [{"title":"Architecture","url":"https://x-cmd.com/draw/archmap?...","note":"3 tiers; gateway is the single entry","ev":"api|src/api.ts|createServer|12-40|verified"}]
• inject_readme.sh는 멱등적입니다: 처음 사용 시 <!-- repoviz:start --> … <!-- repoviz:end --> 블록(다이어그램당 마크다운 이미지 + 노트)을 추가하고, 이후 실행 시 해당 위치에서 대체합니다 — 다이어그램은 리포지토리에서 라이브 자산이 됩니다.
• 내보내기 후 저장된 경로를 출력하고 채팅에 마크다운 블록을 계속 출력하여 사용자가 둘 다 얻도록 합니다.

규칙

• 브랜드 중립적: 결과를 repoviz 다이어그램으로 제시하고, 렌더 URL의 이름을 변경하거나 감싸지 마십시오.
• 한 번 스캔, 여러 다이어그램: 다이어그램마다 리포지토리를 다시 읽는 대신 세트 전반에 걸쳐 노드 인벤토리를 재사용합니다.
• 완전성보다는 적고 잘 선택된 노드를 선호합니다. 세부 사항은 sub 캡션과 경계 상자로 축소합니다.
• 증거가 없으면 존재하지 않는 것입니다: 모든 노드/엣지는 verified, inferred 또는 unknown으로 표시되고 — 절대 조작하지 않습니다. 세트, 보고서 및 향후 아키텍처 차이가 하나의 인벤토리를 공유할 수 있도록 IR/렌더러 분할을 유지합니다. 렌더링은 교체 가능한 어댑터로 유지됩니다.
• URL-as-데이터 증분 편집: 기존 repoviz 다이어그램은 URL로 완전히 정의됩니다 — 절대 비전 또는 이미지 읽기 도구를 사용하여 검사하지 마십시오. 마크다운에서 URL을 디코딩하고, 노드/엣지 세트를 현재 코드와 비교한 후 업데이트된 URL을 내보냅니다. 노드 ID, 레이블 및 레이아웃 규칙을 유지합니다.