cpp-coro-graph (V1)

Синтаксический C++17 coroutine + device-domain граф.
Основная цель: Linux. Только stdlib Python 3.9+ (для запуска не нужны pip-зависимости).

Что умеет V1:

• Все функции как узлы: определения {...} и объявления Foo(); / = default / = delete (включая заголовки)

• Методы классов/структур с квалификацией Class::Method (включая конструкторы/деструкторы)

• Находит exec::task<…> Name и функции с co_await / co_return

• Рисует рёбра await из co_await Foo(…) плюс обычные calls

• Метод-конвейер: co_await m.Init() внутри SosModel::Call разрешается в SosModel::Init (внешний класс + локальная переменная SosModel m)

• Помечает домены устройств (cpu / gpu / npu / dsp) через rules/devices.json

• SQLite-база + HTML-визуализация + CLI (query / callers / callees / explore) + MCP

Чего V1 не умеет:

• Разрешение шаблонов / макросов / перегрузок (потребуются compile_commands позже)

• Продолжение на другом потоке / настоящие параллельные рёбра по времени

• Безошибочный разбор C++ (это regex + сопоставление скобок, а не компилятор)

Установка на 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

Требуется только python3 (3.9+). Используется стандартный модуль sqlite3.

Related MCP server: cpp-semantic-graph

Индексация вашего дерева кода 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

Результат:

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

• /path/to/your/linux/repo/.cpp-coro-graph/graph.html (открыть в браузере)

Запускайте инструмент на Linux-машине (или в FS Linux под WSL2), где лежат исходники. Избегайте индексации через /mnt/c/... из WSL.

Проверка:

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

Визуализация (ствол модуля, а не вся вселенная)

HTML по умолчанию — это module → entries → await trunk → разверну по двойному клику:

# 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

В браузере: выберите модуль, кликните по точке входа, дважды кликните узел, чтобы развернуть следующий слой await. При необходимости включите calls. Рёбра file/contains в этом режиме не показываются.

Запросы к графу (codegraph-style)

Для больших графов (10k+ узлов) — предпочитайте их 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

Если вы cd перешли в индексированный репозиторий, --db можно опустить (производится подъём вверх для поиска .cpp-coro-graph/graph.db).

Cursor MCP (необязательно)

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

Инструменты: big_explore, coro_stats.

Пользовательские правила для устройств

Отредактируйте rules/devices.json или передайте --rules your.json:

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

Побеждает первое совпадение. Размещайте более длинные и более специфичные строки первыми.

Типы рёбер (только четыре)

callers / callees по умолчанию используют control = только calls+await (не file/inheritance), чтобы два направления оставались различимыми.

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"

Пропускаемые каталоги

.git, build, out, third_party, node_modules, .codegraph, bazel-*, .repo, prebuilts, …# cpp-coro-graph (V1)

Синтаксический C++17 coroutine + device-domain граф.
Основная цель: Linux. Только stdlib Python 3.9+ (для запуска не нужны pip-зависимости).

Что умеет V1:

• Все функции как узлы: определения {...} и объявления Foo(); / = default / = delete (включая заголовки)

• Методы классов/структур с квалификацией Class::Method (включая конструкторы/деструкторы)

• Находит exec::task<…> Name и функции с co_await / co_return

• Рисует рёбра await из co_await Foo(…) плюс обычные calls

• Конвейер методов: co_await m.Init() внутри SosModel::Call разрешается в SosModel::Init (внешний класс + локальная переменная SosModel m)

• Помечает домены устройств (cpu / gpu / npu / dsp) через rules/devices.json

• SQLite-база + HTML-визуализация + CLI (query / callers / callees / explore) + MCP

Чего V1 не умеет:

• Разрешение шаблонов / макросов / перегрузок (понадобятся compile_commands позже)

• Продолжение на другом потоке / настоящие параллельные рёбра по времени

• Идеальный разбор C++ (это regex + сопоставление скобок, а не компилятор)

Установка на 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

Требуется только python3 (3.9+). Используется стандартный модуль sqlite3.

Индексация дерева кода 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

Результат:

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

• /path/to/your/linux/repo/.cpp-coro-graph/graph.html (открыть в браузере)

Запускайте инструмент на Linux-машине (или в WSL2 Linux-файловой системе), где хранятся исходники. Избегайте индексации через /mnt/c/... из WSL2.

Smoke-тест:

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

Визуализация (ствол модуля, а не вся вселенная)

HTML по умолчанию: module → entry → await-ствол → разворачивание двойным кликом:

# 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

В браузере: выберите модуль, кликните по entry-чипу, дважды кликните узел, чтобы развернуть следующий await-слой. При необходимости переключайте calls. Рёбра file/contains в этом режиме не показываются.

Запрос к графу (codegraph-style)

Большие графы (10k+ узлов) — предпочитайте их 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

Если вы cd в индексированный репозиторий, --db можно не указывать (происходит поиск вверх по каталогам до .cpp-coro-graph/graph.db).

MCP для Cursor (необязательно)

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

Инструменты: coro_explore, coro_stats.

Пользовательские правила устройств

Отредактируйте rules/devices.json или передайте --rules your.json:

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

Срабатывает первое совпадение. Помещайте более длинные / более специфичные строки первыми.

Типы рёбер (всего четыре)

callers / callees по умолчанию работают в control = только calls+await (не file/inheritance), поэтому оба направления остаются разными.

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"

Пропускаемые каталоги

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