cpp-coro-graph (V1)

Graph auf Syntax-Ebene: C++17-Koroutine + Geräte-Domäne.
Hauptziel: Linux. Python 3.9+ nur mit Standardbibliothek (keine pip-Abhängigkeiten erforderlich).

Was V1 kann:

• Alle Funktionen als Knoten: Definitionen {...} und Deklarationen Foo(); / = default / = delete (Header inklusive)

• Klassen-/Struct-Member qualifiziert als Class::Method (inkl. Konstruktor/Destruktor)

• Findet exec::task<…> Name / Funktionen mit co_await / co_return

• Zeichnet await-Kanten von co_await Foo(…) plus normale calls-Kanten

• Member-Pipeline: co_await m.Init() in SosModel::Call wird zu SosModel::Init aufgelöst (umschließende Klasse + lokales SosModel m)

• Markiert Geräte-Domänen (cpu / gpu / npu / dsp) über rules/devices.json

• SQLite-DB + HTML-Visualisierung + CLI (query / callers / callees / explore) + MCP

Was V1 nicht kann:

• Template-/Makro-/Overload-Auflösung (braucht später compile_commands)

• Cross-Thread-Resume / echte parallele Kanten aus der Zeit

• Vollkommenes C++-Parsen (Regex + Klammerabgleich, kein Compiler)

Installation unter Linux

git clone https://github.com/ArcherLin13/cpp-coro-graph.git
cd cpp-coro-graph

# option A — no install (recommended for a quick try)
chmod +x scripts/cpp-coro-graph scripts/index_repo.sh
./scripts/cpp-coro-graph index /path/to/your/repo

# option B — install CLI on PATH
python3 -m pip install -e .
cpp-coro-graph index /path/to/your/repo

Benötigt nur python3 (3.9+). Verwendet das Stdlib-Modul sqlite3.

Related MCP server: cpp-semantic-graph

Linux-Codebaum indexieren

# one-shot: index + HTML + status
./scripts/index_repo.sh /path/to/your/linux/repo

# or step by step
python3 -m cpp_coro_graph index /path/to/your/linux/repo
python3 -m cpp_coro_graph viz --db /path/to/your/linux/repo/.cpp-coro-graph/graph.db
python3 -m cpp_coro_graph status --db /path/to/your/linux/repo/.cpp-coro-graph/graph.db

Ausgaben:

• /path/to/your/linux/repo/.cpp-coro-graph/graph.db

• /path/to/your/linux/repo/.cpp-coro-graph/graph.html (im Browser öffnen)

Führe das Tool auf der Linux-Maschine (oder dem WSL2-Linux-Dateisystem) aus, auf der bzw. dem dir Quellen liegen. Vermeide das Indizieren über /mnt/c/... aus WSL.

Smoke-Test:

./scripts/cpp-coro-graph index fixtures/sample --db fixtures/sample/.cpp-coro-graph/graph.db
./scripts/cpp-coro-graph viz --db fixtures/sample/.cpp-coro-graph/graph.db

Viz (Modul-Trunk, nicht das ganze Universum)

Standard-HTML: Modul → Einträge → Await-Trunk → Doppelklick zum Erweitern:

# recommended: one module’s entries + main await flow
python3 -u -m cpp_coro_graph -q viz --db "$DB" --module path/to/module --depth 1

# pin one entry
python3 -u -m cpp_coro_graph -q viz --db "$DB" --around Call --depth 1

# legacy full graph (avoid on large trees)
python3 -u -m cpp_coro_graph -q viz --db "$DB" --full

Im Browser: Modul auswählen, Eintrag-Chip anklicken, Doppelklick auf einen Knoten, um die nächste Await-Ebene zu erweitern. calls ist bei Bedarf umschaltbar. Datei-/contains-Kanten werden in diesem Modus nicht angezeigt.

Graph abfragen (codegraph-Stil)

Große Graphen (10k+ Knoten) – diese bevorzugen Sie gegenüber HTML:

DB=/path/to/repo/.cpp-coro-graph/graph.db

# search symbols
python3 -u -m cpp_coro_graph -q query OnSos --db "$DB"

# who calls / awaits this
python3 -u -m cpp_coro_graph -q callers OnSos --db "$DB"

# what it calls / awaits / spawns
python3 -u -m cpp_coro_graph -q callees OnSos --db "$DB" --edge-kind calls,await,spawns

# neighborhood BFS
python3 -u -m cpp_coro_graph -q explore OnSos --depth 2 --db "$DB"

# incoming blast radius
python3 -u -m cpp_coro_graph -q impact OnSos --depth 2 --db "$DB"

# JSON for scripting
python3 -u -m cpp_coro_graph -q callers OnSos --db "$DB" --json

Wenn du dich per cd in das indizierte Repository begibst, kannst du --db weglassen (sucht aufwärts nach .cpp-coro-graph/graph.db).

Cursor MCP (optional)

{
  "mcpServers": {
    "cpp-coro-graph": {
      "command": "python3",
      "args": [
        "-m", "cpp_coro_graph", "mcp",
        "--db", "/path/to/your/linux/repo/.cpp-coro-graph/graph.db"
      ],
      "cwd": "/path/to/cpp-coro-graph"
    }
  }
}

Tools: coro_explore, coro_stats.

Eigene Geräte-Regeln

Bearbeite rules/devices.json oder übergib --rules your.json:

{
  "patterns": [
    {"match": "RunOnNpu", "domain": "npu", "backend": "custom"},
    {"match": "clEnqueue", "domain": "gpu", "backend": "opencl"}
  ]
}

Der erste Treffer gewinnt. Längere / spezifischere Strings zuerst.

Kantenarten (nur vier)

callers / callees stehen standardmäßig auf control = nur calls+await (keine contains/inherits), sodass die beiden Richtungen unterscheidbar bleiben.

python3 -u -m cpp_coro_graph -q callees Call --db "$DB"           # await+calls
python3 -u -m cpp_coro_graph -q callers Init --db "$DB"
python3 -u -m cpp_coro_graph -q explore SosModel --edge-kind inherits,contains --db "$DB"

Übersprungene Verzeichnisse

.git, build, out, third_party, node_modules, .codegraph, bazel-*, .repo, prebuilts, …