코드 구조 시각화를 위한 CodeFlow 가이드

Summary

CodeFlow는 GitHub 주소를 붙여 넣거나 로컬 폴더를 선택하면 코드 구조와 의존 관계를 브라우저에서 시각화해 주는 도구입니다.

빠른 시작

CodeFlow GitHub 저장소

License 확인 4.7k stars 721 forks

가장 쉬운 방법은 다음과 같습니다.

1. 브라우저에서 CodeFlow 온라인 버전을 엽니다.
2. 공개 GitHub 저장소 주소 또는 facebook/react와 같은 소유자/저장소 값을 입력합니다.
3. Enter 키를 눌러 분석을 시작합니다.
4. 생성된 파일 관계 그래프를 확대하거나 노드를 선택해 살펴봅니다.

온라인 사용에는 저장소 복제나 패키지 설치가 필요하지 않습니다.

저장소 소개

CodeFlow는 새로운 코드베이스의 파일 구조와 연결 관계를 빠르게 파악하기 위한 브라우저 기반 분석 도구입니다. 주요 언어는 HTML이며, 웹 앱은 단일 index.html을 중심으로 구성된 것으로 README에서 확인됩니다.

항목	내용
기본 브랜치	main
주요 언어	HTML
라이선스	원본에서 확인되지 않음
설치 과정	일반 사용에는 없음
입력	공개 GitHub 주소, 비공개 저장소, 로컬 파일·폴더
주요 결과	의존 관계 그래프, 변경 영향 범위, 보안 탐지, 건강 점수, 보고서

분석은 휴리스틱, 즉 정해진 규칙과 이름 비교를 이용한 빠른 추정입니다. 동적 import나 실행 중에 바뀌는 참조는 놓칠 수 있으므로 결과를 확정적인 코드 감사 보고서로 간주하면 안 됩니다.

Windows 사전 준비

사용 방식에 따라 준비물이 달라집니다.

사용 방식	필요한 항목
온라인 버전	최신 웹 브라우저, 인터넷 연결
로컬 파일 분석	최신 웹 브라우저와 분석할 폴더
저장소 직접 실행	Git, 최신 웹 브라우저
테스트 수정·실행	Node.js가 사용된다는 사실만 확인됨. 지원 버전은 기본 앱에 대해 원본에서 확인되지 않음

Git 설치 방법이나 Windows 패키지 관리자 명령은 제공된 원본에서 확인되지 않았습니다. 필요한 경우 Git 공식 사이트에서 Windows용 설치 프로그램을 확인하세요.

TIP

단순히 CodeFlow를 체험하려면 Git이나 Node.js를 설치하지 말고 온라인 버전부터 사용하세요.

설치와 실행

방법 1: 온라인에서 사용

온라인 버전을 열면 별도의 설치 없이 사용할 수 있습니다. 공개 저장소 분석은 주소 입력만으로 시작할 수 있습니다.

방법 2: 저장소를 내려받아 실행

README에서 확인되는 복제 명령은 다음과 같습니다. PowerShell에서 실행할 수 있습니다.

git clone https://github.com/braedonsaunders/codeflow.git

복제가 끝나면 파일 탐색기에서 생성된 codeflow 폴더로 이동해 index.html을 브라우저로 엽니다. README에는 빌드 및 npm install이 필요 없고, 브라우저 의존성을 CDN에서 불러온다고 설명되어 있습니다.

WARNING

CDN 의존성을 처음 불러오는 직접 실행 방식은 인터넷 연결이 필요할 수 있습니다. README의 “오프라인 지원”은 로컬 파일 분석 기능에 관한 설명이며, 최초 웹 앱 로딩까지 완전히 오프라인으로 가능한지는 원본에서 확인되지 않음입니다.

방법 3: 로컬 폴더 분석

1. CodeFlow 화면에서 Open Folder 버튼을 선택합니다.
2. 분석할 폴더나 파일을 지정합니다.
3. 필요하면 제외 패턴을 설정합니다.
4. 브라우저가 파일을 처리하고 그래프를 생성할 때까지 기다립니다.

README에 따르면 이 방식의 파일 처리는 브라우저 안에서 수행되며 파일을 GitHub에 업로드하지 않습니다.

첫 성공 확인

다음 상태가 보이면 기본 실행에 성공한 것입니다.

• 저장소 이름이나 분석 대상이 화면에 표시됩니다.
• 파일을 나타내는 노드와 파일 사이의 연결선이 나타납니다.
• 노드를 클릭하면 관련 의존 관계가 강조됩니다.
• 마우스 드래그와 확대·축소가 동작합니다.

확인하기 쉬운 공개 저장소 입력 예시는 README에 나온 다음 두 형식입니다.

facebook/react
https://github.com/facebook/react

분석 후 상단의 Export 기능이 보인다면 JSON, Markdown, 일반 텍스트, SVG, PDF 등의 내보내기 항목도 확인할 수 있습니다.

핵심 구조

경로	역할
index.html	React 화면, 파서와 분석 기능을 포함하는 단일 웹 앱 진입점
README.md	기능, 사용 방법, 지원 언어와 제한 사항을 설명하는 문서
screenshot.png	README에 표시되는 대표 실행 화면
card/	저장소 상태를 SVG 카드로 생성하는 GitHub Action 관련 영역
card/README.md	CodeFlow Card 설정, 입력값과 권한 설명
tests/	Node 내장 테스트 실행기를 사용하는 테스트 영역

웹 앱에는 README 기준으로 React 18, D3.js 7, Babel이 사용되며 고정된 CDN 의존성으로 로드됩니다. 별도의 npm 빌드 과정은 확인되지 않습니다.

동작 흐름

아래 다이어그램은 README에서 확인되는 입력, 브라우저 분석 및 결과 표시 관계만 나타냅니다.

flowchart TD
    A["GitHub 저장소 주소"] --> B["브라우저의 CodeFlow"]
    C["로컬 파일·폴더"] --> B
    B --> D["파일과 함수 분석"]
    D --> E["의존 관계 그래프"]
    D --> F["보안·건강 지표"]
    E --> G["보고서 내보내기"]
    F --> G

GitHub 저장소를 입력하면 브라우저가 GitHub API를 직접 호출합니다. 로컬 파일을 선택하면 브라우저 내부에서 파일을 처리합니다. 분석 결과는 그래프, 변경 영향 범위, 보안 문제, 패턴 및 보고서 형태로 제공됩니다.

안전 주의사항

WARNING

비공개 저장소 분석을 위해 토큰을 입력하면 민감한 자격 증명을 다루게 됩니다. 처음에는 공개 저장소나 로컬 예제 폴더로 연습하고, 실제 토큰은 필요한 최소 권한만 부여하세요.

• README는 토큰이 브라우저 메모리에만 저장되고 탭을 닫으면 지워진다고 설명합니다. 그래도 화면 공유, 브라우저 확장 프로그램 및 클립보드 노출에 주의하세요.
• README의 비공개 저장소 예시는 repo 범위의 Personal Access Token을 안내합니다. 이 범위는 접근 권한이 넓을 수 있으므로 사용 전 권한을 직접 검토해야 합니다.
• 온라인 버전은 GitHub API와 통신합니다. 네트워크 요청이 전혀 없는 방식이 필요하다면 로컬 파일 분석을 검토하세요.
• 보안 스캐너는 비밀 값, SQL 삽입, 위험한 eval() 등의 가능성을 탐지하지만 휴리스틱 결과입니다. 탐지 항목을 실제 취약점으로 확정하기 전에 해당 코드를 직접 확인하세요.
• card/의 GitHub Action 예시는 저장소 내용을 쓰는 권한을 사용합니다. 초보자는 권한과 생성 파일을 이해하기 전까지 자신의 저장소에 바로 적용하지 않는 편이 안전합니다.
• 관리자 권한이 필요하다는 설명은 원본에서 확인되지 않음입니다.
• 로컬 서버를 외부 네트워크에 공개하는 명령이나 기능은 원본에서 확인되지 않음입니다.

다음 단계

1. 작은 공개 저장소를 분석해 노드 선택, 드래그 및 확대·축소를 연습합니다.
2. Folder, Layer, Churn, Blast 표시 모드를 차례로 비교합니다.
3. 로컬의 복사본이나 민감하지 않은 예제 폴더로 로컬 분석을 시험합니다.
4. JSON 또는 Markdown 보고서를 내보내 원본 코드와 결과가 일치하는지 확인합니다.
5. 기능을 수정하려면 index.html부터 읽고, Markdown·위키 링크 파서를 다룰 때는 tests/의 Node 테스트를 확인합니다.
6. 자동 갱신 SVG 카드가 필요할 때만 card/README.md의 권한과 생성 파일을 먼저 검토합니다.

README에서 확인되는 파서 테스트 명령은 다음과 같습니다. 이는 일반 사용이 아니라 코드를 수정하려는 기여자용입니다.

node --test tests/

참고한 원본

GitHub에서 원본 저장소 열기 →