shadow_brain_core/scripts/build_graph.py

# -*- coding: utf-8 -*-
"""🔱 Graphify 지식 그래프 생성 및 시각화 빌더

제국 프로젝트(shadow_brain_core)의 코드 구조(AST)와 마크다운 문서를 분석하여
구조적 의존망을 담은 graph.json 및 웹 시각화 graph.html을 빌드합니다.
빌드된 파일은 로컬 및 R2 Live 스토리지에 업로드되어 AI와 마왕님께 지도로 제공됩니다.

실행 방법:
    python scripts/build_graph.py [--upload]
"""

import os
import sys
import json
import ast
import argparse
from pathlib import Path

# UTF-8 인코딩 강제
sys.stdout.reconfigure(encoding='utf-8')

class ProjectGraphBuilder:
    def __init__(self, root_dir: Path):
        self.root_dir = root_dir.resolve()
        self.nodes = {}
        self.edges = []
        self.scanned_files = set()

    def add_node(self, node_id: str, label: str, node_type: str, details: dict = None):
        if node_id not in self.nodes:
            self.nodes[node_id] = {
                "id": node_id,
                "label": label,
                "type": node_type,
                "details": details or {}
            }

    def add_edge(self, source: str, target: str, rel_type: str):
        # 중복 엣지 방지
        edge = {"source": source, "target": target, "type": rel_type}
        if edge not in self.edges:
            self.edges.append(edge)

    def scan_python_files(self):
        """Python 파일의 AST 파싱을 통해 클래스, 함수, import 관계 분석"""
        for root, _, files in os.walk(self.root_dir):
            # 제외 폴더 필터링
            if any(p in root for p in [".git", "venv", "__pycache__", "node_modules", "dist", "build"]):
                continue

            for file in files:
                if not file.endswith(".py"):
                    continue

                file_path = Path(root) / file
                rel_path = file_path.relative_to(self.root_dir).as_posix()
                self.scanned_files.add(rel_path)

                # 파일 노드 추가
                self.add_node(rel_path, file, "file", {"size": file_path.stat().st_size})

                try:
                    with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
                        code = f.read()

                    # AST 분석
                    tree = ast.parse(code, filename=str(file_path))
                    self._analyze_ast(tree, rel_path)

                except Exception as e:
                    print(f"⚠️ AST 파싱 실패 [{rel_path}]: {e}")

    def _analyze_ast(self, tree: ast.AST, file_rel_path: str):
        """AST 노드를 순회하며 클래스, 함수, import 관계 정의"""
        for node in ast.walk(tree):
            # 1. Imports 분석
            if isinstance(node, ast.Import):
                for alias in node.names:
                    # 프로젝트 내부 모듈로 추정되는 import만 연결
                    target_module = alias.name.split('.')[0]
                    self._try_add_import_edge(file_rel_path, target_module)

            elif isinstance(node, ast.ImportFrom):
                if node.module:
                    target_module = node.module.split('.')[0]
                    self._try_add_import_edge(file_rel_path, target_module)

            # 2. 클래스 정의 분석
            elif isinstance(node, ast.ClassDef):
                class_id = f"{file_rel_path}::{node.name}"
                self.add_node(class_id, node.name, "class", {
                    "file": file_rel_path,
                    "methods": [n.name for n in node.body if isinstance(n, ast.FunctionDef)]
                })
                # 파일 -> 클래스 부모-자식 연결
                self.add_edge(file_rel_path, class_id, "defines")

            # 3. 최상위 함수 정의 분석
            elif isinstance(node, ast.FunctionDef):
                # 클래스 메서드가 아닌 독립 함수만 추가 (클래스 메서드는 클래스 노드 상세 정보에 포함)
                # 부모가 ClassDef인지 간단히 판단하기 위해 walk가 아닌 단단계 매핑이 좋으나, 간소화를 위해 수집
                pass

    def _try_add_import_edge(self, source_file: str, target_module: str):
        """임포트 대상 모듈이 프로젝트 내부에 실존하는 파일인지 판별 후 간선 연결"""
        # 1. module_name.py 형태 검사
        potential_py = f"{target_module}.py"
        potential_dir_py = f"{target_module}/__init__.py"

        for scanned in self.scanned_files:
            if scanned == potential_py or scanned.endswith("/" + potential_py) or scanned == potential_dir_py:
                self.add_edge(source_file, scanned, "imports")
                return

    def scan_markdown_docs(self):
        """프로젝트 루트 내 Markdown 문서와 그 안의 연결고리(wiki 링크, 파일 참조) 분석"""
        for root, _, files in os.walk(self.root_dir):
            if any(p in root for p in [".git", "venv", "node_modules", ".agent"]):
                continue

            for file in files:
                if not file.endswith(".md"):
                    continue

                file_path = Path(root) / file
                rel_path = file_path.relative_to(self.root_dir).as_posix()

                # 문서 노드 추가
                self.add_node(rel_path, file, "document", {"size": file_path.stat().st_size})

                try:
                    with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
                        content = f.read()

                    # 문서 내부의 타 파일 참조([[링크]] 또는 마크다운 파일 링크) 탐색
                    # 간단한 파일명 매칭
                    for other_file in self.scanned_files:
                        other_name = Path(other_file).name
                        if other_name in content:
                            self.add_edge(rel_path, other_file, "references")

                except Exception as e:
                    print(f"⚠️ 문서 스캔 실패 [{rel_path}]: {e}")

    def build(self) -> dict:
        self.scan_python_files()
        self.scan_markdown_docs()
        return {
            "nodes": list(self.nodes.values()),
            "links": self.edges
        }

def generate_interactive_html(graph_data: dict) -> str:
    """D3.js 기반의 멋진 Force-Directed Graph UI 템플릿 생성"""
    data_json = json.dumps(graph_data, ensure_ascii=False, indent=2)
    
    html_template = f"""<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>🔱 Imperial Guild Knowledge Graph Portal</title>
    <script src="https://d3js.org/d3.v7.min.js"></script>
    <style>
        body {{
            margin: 0;
            font-family: 'Outfit', 'Inter', sans-serif;
            background-color: #0f1016;
            color: #e2e8f0;
            overflow: hidden;
        }}
        #header {{
            position: absolute;
            top: 20px;
            left: 20px;
            z-index: 10;
            pointer-events: none;
        }}
        h1 {{
            margin: 0;
            font-size: 24px;
            font-weight: 700;
            background: linear-gradient(135deg, #38bdf8, #818cf8);
            -webkit-background-clip: text;
            -webkit-text-fill-color: transparent;
            letter-spacing: -0.05em;
        }}
        p {{
            margin: 5px 0 0 0;
            font-size: 12px;
            color: #64748b;
        }}
        #canvas {{
            width: 100vw;
            height: 100vh;
        }}
        .node {{
            stroke-width: 1.5px;
            cursor: pointer;
            transition: r 0.2s ease, stroke-width 0.2s ease;
        }}
        .link {{
            stroke: #334155;
            stroke-opacity: 0.6;
            stroke-width: 1.2px;
        }}
        .label {{
            font-size: 10px;
            fill: #94a3b8;
            pointer-events: none;
            text-shadow: 0 1px 3px rgba(0,0,0,0.8);
        }}
        #details {{
            position: absolute;
            top: 20px;
            right: 20px;
            width: 320px;
            background: rgba(15, 23, 42, 0.85);
            backdrop-filter: blur(12px);
            border: 1px solid rgba(255,255,255,0.1);
            border-radius: 12px;
            padding: 20px;
            box-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.5);
            z-index: 10;
            display: none;
            max-height: 80vh;
            overflow-y: auto;
        }}
        #details h3 {{
            margin-top: 0;
            color: #38bdf8;
            border-bottom: 1px solid rgba(255,255,255,0.1);
            padding-bottom: 10px;
        }}
        .meta-item {{
            margin-bottom: 10px;
            font-size: 13px;
        }}
        .meta-label {{
            color: #64748b;
            font-weight: bold;
        }}
        .meta-value {{
            color: #cbd5e1;
            word-break: break-all;
        }}
        .legend {{
            position: absolute;
            bottom: 20px;
            left: 20px;
            background: rgba(15, 23, 42, 0.7);
            padding: 10px 15px;
            border-radius: 8px;
            border: 1px solid rgba(255,255,255,0.05);
            font-size: 11px;
            z-index: 10;
        }}
        .legend-item {{
            display: flex;
            align-items: center;
            margin-bottom: 5px;
        }}
        .legend-color {{
            width: 10px;
            height: 10px;
            border-radius: 50%;
            margin-right: 8px;
        }}
    </style>
</head>
<body>
    <div id="header">
        <h1>🔱 제국 지식 그래프 포탈</h1>
        <p>Imperial Knowledge & Codebase Mapping (Graphify Engine)</p>
    </div>

    <div id="details">
        <h3 id="detail-title">Node Details</h3>
        <div id="detail-content"></div>
    </div>

    <div class="legend">
        <div class="legend-item"><div class="legend-color" style="background: #38bdf8;"></div> 소스 코드 (File)</div>
        <div class="legend-item"><div class="legend-color" style="background: #fb7185;"></div> 마크다운 문서 (Document)</div>
        <div class="legend-item"><div class="legend-color" style="background: #c084fc;"></div> 구조적 클래스 (Class)</div>
    </div>

    <svg id="canvas"></svg>

    <script>
        const graph = {data_json};

        const width = window.innerWidth;
        const height = window.innerHeight;

        const svg = d3.select("#canvas")
            .attr("viewBox", [0, 0, width, height]);

        const g = svg.append("g");

        // 줌/팬 설정
        svg.call(d3.zoom()
            .scaleExtent([0.1, 8])
            .on("zoom", (event) => {{
                g.attr("transform", event.transform);
            }}));

        // 색상 맵
        const colorMap = {{
            "file": "#38bdf8",
            "document": "#fb7185",
            "class": "#c084fc"
        }};

        // 시뮬레이션 설정
        const simulation = d3.forceSimulation(graph.nodes)
            .force("link", d3.forceLink(graph.links).id(d => d.id).distance(80))
            .force("charge", d3.forceManyBody().strength(-120))
            .force("center", d3.forceCenter(width / 2, height / 2))
            .force("collision", d3.forceCollide().radius(25));

        // 간선(Edges) 드로잉
        const link = g.append("g")
            .selectAll("line")
            .data(graph.links)
            .join("line")
            .attr("class", "link");

        // 노드(Nodes) 드로잉
        const node = g.append("g")
            .selectAll("circle")
            .data(graph.nodes)
            .join("circle")
            .attr("class", "node")
            .attr("r", d => d.type === "file" ? 8 : (d.type === "document" ? 7 : 5))
            .attr("fill", d => colorMap[d.type] || "#94a3b8")
            .attr("stroke", "#0f1016")
            .attr("stroke-width", 1.5)
            .call(drag(simulation));

        // 라벨 추가
        const label = g.append("g")
            .selectAll("text")
            .data(graph.nodes)
            .join("text")
            .attr("class", "label")
            .attr("dx", 12)
            .attr("dy", ".35em")
            .text(d => d.label);

        // 이벤트 리스너
        node.on("click", (event, d) => {{
            showDetails(d);
            event.stopPropagation();
        }});

        svg.on("click", () => {{
            d3.select("#details").style("display", "none");
        }});

        simulation.on("tick", () => {{
            link
                .attr("x1", d => d.source.x)
                .attr("y1", d => d.source.y)
                .attr("x2", d => d.target.x)
                .attr("y2", d => d.target.y);

            node
                .attr("cx", d => d.x)
                .attr("cy", d => d.y);

            label
                .attr("x", d => d.x)
                .attr("y", d => d.y);
        }});

        function showDetails(d) {{
            const details = d3.select("#details");
            d3.select("#detail-title").text(d.label);
            
            let html = `
                <div class="meta-item">
                    <div class="meta-label">ID / 상대 경로</div>
                    <div class="meta-value">${{d.id}}</div>
                </div>
                <div class="meta-item">
                    <div class="meta-label">유형</div>
                    <div class="meta-value">${{d.type.toUpperCase()}}</div>
                </div>
            `;

            if (d.type === "class" && d.details.methods) {{
                html += `
                    <div class="meta-item">
                        <div class="meta-label">부모 소스 파일</div>
                        <div class="meta-value">${{d.details.file}}</div>
                    </div>
                    <div class="meta-item">
                        <div class="meta-label">포함된 메서드 목록</div>
                        <div class="meta-value">${{d.details.methods.join(', ') || '없음'}}</div>
                    </div>
                `;
            }} else if (d.details.size) {{
                html += `
                    <div class="meta-item">
                        <div class="meta-label">파일 크기</div>
                        <div class="meta-value">${{d.details.size.toLocaleString()}} bytes</div>
                    </div>
                `;
            }}

            d3.select("#detail-content").html(html);
            details.style("display", "block");
        }}

        function drag(simulation) {{
            return d3.drag()
                .on("start", (event) => {{
                    if (!event.active) simulation.alphaTarget(0.3).restart();
                    event.subject.fx = event.subject.x;
                    event.subject.fy = event.subject.y;
                }})
                .on("drag", (event) => {{
                    event.subject.fx = event.subject.x;
                    event.subject.fy = event.subject.y;
                }})
                .on("end", (event) => {{
                    if (!event.active) simulation.alphaTarget(0);
                    event.subject.fx = null;
                    event.subject.fy = null;
                }});
        }}
    </script>
</body>
</html>
"""
    return html_template

def upload_to_r2_live(json_path: Path, html_path: Path):
    """R2 Live 버킷에 지식 그래프 지도 업로드"""
    try:
        # shadow_brain_core/web_server.py의 R2 Live 로드 패턴 참조
        core_dir = Path(__file__).parent.parent
        project_root = core_dir.parent
        sys.path.append(str(core_dir))
        sys.path.append(str(project_root / "scripts" / "tools"))
        
        from cloud_tool import R2_ACCOUNTS, _get_bw_credential
        import boto3
        from botocore.config import Config

        print("🔮 R2 Live 자격증명 확보 시작...")
        # live 설정 추출
        live_cfg = R2_ACCOUNTS.get("live")
        if not live_cfg:
            print("❌ R2 Live 계정이 cloud_tool.py에 정의되어 있지 않습니다.")
            return

        account_id = _get_bw_credential(live_cfg["account_id"])
        access_key = _get_bw_credential(live_cfg["access_key_id"])
        secret_key = _get_bw_credential(live_cfg["secret_access_key"])
        # 🔱 [Fix] R2_ACCOUNTS["live"] 의 버킷 키는 "bucket"(="cache") 이다.
        #   잘못된 키 "bucket_name"(기본 "taemingames")을 쓰면 공개 도메인
        #   r2.taemingames.com(=cache 버킷)과 다른 버킷에 올라가 404 가 난다.
        bucket_name = live_cfg.get("bucket", "cache")

        if not all([account_id, access_key, secret_key]):
            print("❌ R2 Live 자격증명이 비어 있어 업로드를 건너뜁니다.")
            return

        print("⚡ R2 Live S3 클라이언트 초기화 중...")
        s3 = boto3.client(
            "s3",
            endpoint_url=f"https://{account_id}.r2.cloudflarestorage.com",
            aws_access_key_id=access_key,
            aws_secret_access_key=secret_key,
            config=Config(signature_version="s3v4")
        )

        prefix = "cloud-obsidian/graph"
        
        # json 업로드
        print(f"🚀 {json_path.name} 업로드 중 -> R2 Live/{prefix}/{json_path.name}")
        s3.upload_file(
            Filename=str(json_path),
            Bucket=bucket_name,
            Key=f"{prefix}/{json_path.name}",
            ExtraArgs={"ContentType": "application/json"}
        )

        # html 업로드
        print(f"🚀 {html_path.name} 업로드 중 -> R2 Live/{prefix}/{html_path.name}")
        s3.upload_file(
            Filename=str(html_path),
            Bucket=bucket_name,
            Key=f"{prefix}/{html_path.name}",
            ExtraArgs={"ContentType": "text/html"}
        )
        print("✅ R2 Live 지식 그래프 업로드 완료!")

    except ImportError:
        print("⚠️ cloud_tool 또는 boto3 모듈을 찾을 수 없어 R2 업로드를 생략합니다.")
    except Exception as e:
        print(f"⚠️ R2 Live 업로드 실패: {e}")

def main():
    parser = argparse.ArgumentParser(description="🔱 Graphify 지식 그래프 엔진")
    parser.add_argument("--upload", action="store_true", help="R2 Live 버킷에 자동 업로드")
    args = parser.parse_args()

    # 스크립트 실행 위치가 scripts/ 여도 부모 shadow_brain_core를 가리키도록 설정
    script_dir = Path(__file__).parent.resolve()
    core_dir = script_dir.parent

    print(f"🔱 Graphify: [{core_dir}] 소스 분석을 개시합니다...")
    builder = ProjectGraphBuilder(core_dir)
    graph_data = builder.build()

    # 로컬 저장 경로
    output_dir = core_dir / "static" / "graph"
    output_dir.mkdir(parents=True, exist_ok=True)

    json_path = output_dir / "graph.json"
    html_path = output_dir / "graph.html"

    # json 쓰기
    with open(json_path, "w", encoding="utf-8") as f:
        json.dump(graph_data, f, ensure_ascii=False, indent=2)

    # html 쓰기
    html_content = generate_interactive_html(graph_data)
    with open(html_path, "w", encoding="utf-8") as f:
        f.write(html_content)

    print(f"✅ 분석 완료! 총 노드: {len(graph_data['nodes'])}, 간선: {len(graph_data['links'])}")
    print(f"💾 로컬 데이터 저장: {json_path}")
    print(f"💾 로컬 시각화 저장: {html_path}")

    # 업로드 처리
    if args.upload:
        upload_to_r2_live(json_path, html_path)

if __name__ == "__main__":
    main()