cpp-coro-graph (V1)

Grafo a nivel de sintaxis corrutina C++17 + dominio de dispositivo.
Objetivo principal: Linux. Solo stdlib de Python 3.9+ (sin dependencias pip necesarias para ejecutar).

Lo que V1 puede hacer:

• Todas las funciones como nodos: definiciones {...} y declaraciones Foo(); / = default / = delete (cabeceras incluidas)

• Miembros de clase/struct calificados como Class::Method (incl. ctor/dtor)

• Encuentra exec::task<…> Name / funciones con co_await / co_return

• Dibuja aristas await desde co_await Foo(…) además de calls normales

• Pipeline de miembros: co_await m.Init() dentro de SosModel::Call se resuelve a SosModel::Init (clase contenedora + SosModel m local)

• Etiqueta dominios de dispositivo (cpu / gpu / npu / dsp) mediante rules/devices.json

• Base de datos SQLite + visualización HTML + CLI (query / callers / callees / explore) + MCP

Lo que V1 no puede hacer:

• Resolución de plantillas / macros / sobrecargas (necesita compile_commands más tarde)

• Reanudación entre hilos / aristas paralelas reales desde el tiempo

• Análisis C++ perfecto (regex + emparejamiento de llaves, no un compilador)

Instalación en 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

Solo requiere python3 (3.9+). Usa el módulo sqlite3 de la stdlib.

Related MCP server: cpp-semantic-graph

Indexa tu árbol de código Linux

# 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

Salidas:

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

• /path/to/your/linux/repo/.cpp-coro-graph/graph.html (ábrelo en un navegador)

Ejecuta la herramienta en la máquina Linux (o en el sistema de archivos Linux de WSL2) que contiene los fuentes. Evita indexar a través de /mnt/c/... desde WSL.

Prueba de humo:

./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

Visualización (tronco de módulo, no universo completo)

El HTML por defecto es módulo → entradas → tronco de await → expandir con doble clic:

# 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

En el navegador: elige un módulo, haz clic en un chip de entrada, haz doble clic en un nodo para expandir la siguiente capa de await. Alterna calls si es necesario. Las aristas de archivo/contains no se muestran en este modo.

Consulta el grafo (estilo codegraph)

Grafos grandes (10k+ nodos) — prefiere estos sobre el 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

Si haces cd al repositorio indexado, se puede omitir --db (busca hacia arriba .cpp-coro-graph/graph.db).

Cursor MCP (opcional)

{
  "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"
    }
  }
}

Herramientas: coro_explore, coro_stats.

Reglas de dispositivo personalizadas

Edita rules/devices.json o pasa --rules your.json:

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

Gana la primera coincidencia. Pon primero las cadenas más largas / más específicas.

Tipos de aristas (solo cuatro)

callers / callees usan por defecto control = solo calls+await (no archivo/herencia), de modo que las dos direcciones se mantienen distintas.

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"

Directorios omitidos

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