vibeeval/code-knowledge-graph

Code Knowledge Graph - Codebase Graph Analysis

Codebase'i knowledge graph olarak modeller. Dosya, modul, fonksiyon ve class'lar node; import, call, inheritance ve composition iliskileri edge olur. Sonuc: Mermaid diagram + JSON graph data.

Neden Knowledge Graph?

Kod text degil, graph'tir. Her dosya diger dosyalara baglidir. Bu baglantilari anlamadan:

• Refactoring yaparken neyi kiracagini bilemezsin
• Dead code'u guvenle silemezsin
• Yeni feature'in nereye oturacagini gormezsin
• Circular dependency'lerin kokunu bulamazsin

Knowledge graph tum bu iliskileri gorsellestirir ve olculebilir yapar.

Kullanim

/code-knowledge-graph [hedef-dizin] [--focus module] [--depth N] [--format mermaid|json|both]

Ornekler

# Tum codebase analizi
/code-knowledge-graph src/

# Belirli module odaklan
/code-knowledge-graph src/ --focus auth

# Sadece circular dependency kontrolu
/code-knowledge-graph src/ --focus circular

# Hotspot analizi
/code-knowledge-graph src/ --focus hotspots

# Orphan/dead code tespiti
/code-knowledge-graph src/ --focus orphans

Graph Olusturma Adimlari

Adim 1: Node Discovery

# Dosya agaci
tldr tree ${PATH:-src/} --ext .py

# Kod yapisi: fonksiyonlar, class'lar, export'lar
tldr structure ${PATH:-src/} --lang python

Her dosya, class, fonksiyon ve export bir node olur.

Adim 2: Edge Extraction

# Dosyanin import'lari (outgoing edges)
tldr imports ${FILE}

# Modulu kim import ediyor? (incoming edges)
tldr importers ${MODULE} ${PATH:-src/}

# Cross-file call graph
tldr calls ${PATH:-src/}

Her import ve fonksiyon cagrisi bir directed edge olur.

Adim 3: Layer Detection

# Architectural layer analizi
tldr arch ${PATH:-src/}

Node'lar 3 katmana ayrilir:

| Katman | Tanim | Ornekler | |--------|-------|---------| | Entry | Disaridan cagirilan, ici cagirmayan | routes, cli, main, handlers | | Middle | Hem cagrilan hem cagirir | services, business logic | | Leaf | Cagirilan ama baskasini cagirmayan | utils, helpers, constants |

Adim 4: Impact Analysis

# Bu fonksiyona kim bagimli?
tldr impact ${FUNCTION} ${PATH:-src/} --depth 3

# Dead code: hicbir yerden cagrilmayan fonksiyonlar
tldr dead ${PATH:-src/}

Adim 5: codebase-memory MCP Entegrasyonu

codebase-memory MCP kuruluysa, persistent graph sorgusu yap:

mcp: index_status       -> Repo index durumu
mcp: index_repository   -> Repo'yu indexle (yoksa)
mcp: query_graph        -> Graph sorgusu (iliskiler)
mcp: search_graph       -> Pattern arama
mcp: get_architecture   -> Mimari genel bakis
mcp: trace_call_path    -> Fonksiyonlar arasi cagri yolu

MCP, session'lar arasi kalici graph verisi saglar. tldr ise anlik taze analiz verir. Ikisini birlikte kullan.

Dependency Analysis Pattern'leri

Direct Dependencies

A dogrudan B'yi import ediyor:

A --import--> B

Transitive Dependencies

A, B'yi import ediyor, B de C'yi import ediyor. A, C'ye transitif bagimli:

A --import--> B --import--> C
A ....transitif....> C

Transitive dependency chain'i uzadikca risk artar. tldr impact ile transitif zincirleri gor.

Fan-In vs Fan-Out

| Metrik | Yuksek Degerin Anlami | Risk | |--------|----------------------|------| | Fan-In (in-degree) | Cok modul buna bagimli | Fragile - degisiklik cascade yapar | | Fan-Out (out-degree) | Bu modul cok seye bagimli | Unstable - disaridan kirilabilir |

Hedef: Leaf node'larda yuksek fan-in (iyi - utility), entry node'larda yuksek fan-out (kotu - god module).

Circular Dependency Cozme Stratejileri

Circular dependency = A imports B, B imports A (dogrudan veya transitif).

Strateji 1: Extract Interface

ONCE: A <--> B (circular)
SONRA: A --> IB <-- B (interface ile decouple)

Her iki modul de bir interface'e bagimli olur, birbirine degil.

Strateji 2: Dependency Inversion

ONCE: A --> B --> A (circular)
SONRA: A --> B, A <-- C (C yeni modul, B'nin A'ya ihtiyac duydugu kismi tasir)

Strateji 3: Extract Shared Module

ONCE: A <--> B (ortak kod paylasiyor)
SONRA: A --> Shared <-- B (ortak kod ayri module)

Strateji 4: Event-Based Decoupling

ONCE: A --> B --> A (geri cagri)
SONRA: A --> EventBus <-- B (event ile haberlesme)

Hangi Stratejiyi Sec?

| Durum | Strateji | |-------|----------| | Type/interface paylasimi | Extract Interface | | Fonksiyon geri cagrisi | Dependency Inversion | | Ortak utility kodu | Extract Shared Module | | Async bildirim ihtiyaci | Event-Based Decoupling |

Hotspot Analizi ve Refactoring Onceliklendirme

Hotspot = Graph'ta en cok baglantisi olan node.

Hotspot Skorlama

hotspot_score = (in_degree * 2) + out_degree + (change_frequency * 3)

• in_degree * 2: Bagimli modul sayisi (en onemli - cascade risk)
• out_degree: Bagimlilik sayisi (kirilganlik)
• change_frequency * 3: Git log'dan degisiklik sikligi (degisen hotspot = en tehlikeli)

Refactoring Oncelik Matrisi

| Hotspot Tipi | Oncelik | Aksiyon | |-------------|---------|--------| | Yuksek in-degree + sik degisen | P0 CRITICAL | Hemen split et, test ekle | | Yuksek in-degree + stabil | P2 MEDIUM | Test ekle, dikkatli degistir | | Yuksek out-degree | P1 HIGH | Dependency'leri azalt, facade pattern | | Yuksek her ikisi | P0 CRITICAL | God module - parcala |

Change Frequency Analizi

# Git log'dan en cok degisen dosyalar
git log --format=format: --name-only --since="6 months ago" | sort | uniq -c | sort -rn | head -20

Cok degisen + cok baglantili = en yuksek risk.

Mermaid Diagram Ornekleri

Dependency Graph (Layered)

graph TD
    subgraph Entry["Entry Layer (Red)"]
        routes[routes.py]
        cli[cli.py]
    end
    subgraph Middle["Middle Layer (Orange)"]
        auth[auth_service.py]
        user[user_service.py]
    end
    subgraph Leaf["Leaf Layer (Green)"]
        utils[utils.py]
        validators[validators.py]
    end

    routes --> auth
    routes --> user
    cli --> user
    auth --> utils
    auth --> validators
    user --> utils

    style routes fill:#e74c3c,color:#fff
    style cli fill:#e74c3c,color:#fff
    style auth fill:#f39c12,color:#fff
    style user fill:#f39c12,color:#fff
    style utils fill:#27ae60,color:#fff
    style validators fill:#27ae60,color:#fff

Call Graph

graph LR
    handle_request --> validate
    handle_request --> authorize
    authorize --> check_token
    authorize --> check_role
    validate --> sanitize
    check_token --> decode_jwt

Circular Dependency (Highlighted)

graph LR
    A[module_a] -->|imports| B[module_b]
    B -->|imports| C[module_c]
    C -->|imports| A

    style A fill:#e74c3c,color:#fff
    style B fill:#e74c3c,color:#fff
    style C fill:#e74c3c,color:#fff
    linkStyle 0 stroke:#e74c3c,stroke-width:3px
    linkStyle 1 stroke:#e74c3c,stroke-width:3px
    linkStyle 2 stroke:#e74c3c,stroke-width:3px

Hotspot Visualization

graph TD
    A[utils.py<br/>in:12 out:1<br/>HOTSPOT]
    B[service.py<br/>in:3 out:8]
    C[routes.py<br/>in:0 out:5]
    D[models.py<br/>in:6 out:2]

    C --> B
    C --> A
    B --> A
    B --> D
    D --> A

    style A fill:#e74c3c,stroke:#c0392b,stroke-width:4px,color:#fff
    style D fill:#f39c12,stroke:#e67e22,stroke-width:2px,color:#fff

Graph-Based Code Review

Knowledge graph review'da su sorulari cevaplar:

1. Impact sorusu: "Bu degisiklik kac modulu etkiler?"

   tldr impact changed_function src/ --depth 3
   

2. Coupling sorusu: "Bu yeni import cycle yaratir mi?"

   • Mevcut graph'a yeni edge ekle, cycle kontrol et

3. Cohesion sorusu: "Bu modul cok mu fazla is yapiyor?"

   • Out-degree > 8 ise muhtemelen evet

4. Dead code sorusu: "Bu fonksiyon gercekten kullaniliyor mu?"

   tldr impact function_name src/
   

Onboarding Icin Graph Kullanimi

Yeni developer'a codebase'i tanitmak icin:

1. Buyuk resim: Layer diagram'i goster (entry/middle/leaf)
2. Kritik yollar: En onemli call chain'leri goster
3. Hotspot'lar: "Bu dosyalara dokunurken dikkatli ol" listesi
4. Moduller: Her modulu 1 cumle ile acikla + bagimliliklari goster

Architectural Decision Support

Graph verisi mimari kararlari destekler:

| Karar | Graph Verisi | |-------|-------------| | "Bu modulu bolmeli miyiz?" | In-degree + out-degree + LOC | | "Microservice siniri nerede?" | Cluster analizi (yuksek ic baglantilar, dusuk dis baglantilar) | | "Hangi modulu once refactor edelim?" | Hotspot score siralamasina bak | | "Yeni feature nereye oturur?" | Mevcut layer'a ve dependency pattern'ine bak | | "Bu dependency guvenli mi?" | Transitif dependency chain'ine bak |

tldr CLI Komut Referansi

| Komut | Kullanim | Cikti | |-------|---------|-------| | tldr tree [path] | Dosya agaci | JSON | | tldr structure [path] --lang X | Kod yapisi (codemaps) | JSON | | tldr calls [path] | Cross-file call graph | JSON | | tldr impact <func> [path] | Reverse call graph | JSON | | tldr dead [path] | Dead/orphan code | JSON | | tldr arch [path] | Layer detection | JSON | | tldr imports <file> | Dosyanin import'lari | JSON | | tldr importers <module> [path] | Modulu kim import ediyor | JSON |

JSON Graph Data Formati

{
  "metadata": {
    "project": "project-name",
    "analyzed_at": "2026-03-26T10:00:00Z",
    "total_nodes": 45,
    "total_edges": 128,
    "languages": ["python"]
  },
  "nodes": [
    {
      "id": "src/auth/service.py::AuthService",
      "type": "class",
      "file": "src/auth/service.py",
      "layer": "middle",
      "in_degree": 5,
      "out_degree": 3,
      "is_hotspot": true,
      "is_orphan": false
    }
  ],
  "edges": [
    {
      "source": "src/routes.py::handle_login",
      "target": "src/auth/service.py::AuthService.authenticate",
      "type": "call"
    }
  ],
  "layers": {
    "entry": [],
    "middle": [],
    "leaf": []
  },
  "circular_dependencies": [],
  "hotspots": [],
  "orphans": []
}

Iliskili Araclar

| Arac | Ne Zaman | |------|---------| | graph-analyst agent | Tam graph analizi, otomatik rapor | | tldr arch | Hizli layer detection | | tldr calls | Hizli call graph | | codebase-memory MCP | Persistent graph, session arasi sorgulama | | /explore architecture | Genel mimari kesfetme | | architect agent | Graph verisiyle mimari karar | | janitor agent | Orphan/dead code temizligi |