Справочник gRPC API — Документация CodeGraph

GoCPG предоставляет gRPC-интерфейс для операций с графом кода (CPG), запросов, навигации, lifecycle/status и сканирования шаблонов. Python-клиент (GrpcTransport в src/services/gocpg/grpc_transport.py) оборачивает все вызовы RPC в асинхронные методы, возвращающие те же Pydantic-модели, что и транспорт через подпроцесс.

Используются пять gRPC-сервисов: CPGService (разбор/обновление/индексы), QueryService (запросы/статистика/ветки/подмодули/фронтенды), PatternService (поиск/сканирование/валидация), NavigationService (методы nav_*), LifecycleService (status/freshness/maintenance).

Подключение¶

Параметр	По умолчанию	Описание
`grpc_host`	`localhost`	Имя хоста сервера
`grpc_port`	`50051`	Порт сервера
`grpc_api_key`	`None`	Токен Bearer для метаданных `authorization`
`grpc_tls_cert`	`None`	Путь к корневому сертификату CA для TLS

Максимальный размер сообщения: 64 МБ (отправка и получение). Все методы принимают необязательный параметр timeout (секунды).

Аутентификация передаётся через метаданные gRPC: ("authorization", "Bearer <api_key>").

Операции с CPG¶

parse¶

Разбор исходного кода в базу данных CPG (DuckDB). Потоковый серверный RPC с событиями прогресса.

Параметр	Тип	По умолчанию	Описание
`input_path`	`str`	обязательный	Путь к каталогу с исходным кодом
`output_path`	`str`	обязательный	Путь к выходному файлу DuckDB
`language`	`str`	`"c"`	Язык исходного кода
`workers`	`int \\| None`	`None`	Число параллельных обработчиков (0 = авто)
`patterns`	`PatternConfig \\| None`	`None`	Шаблоны включения/исключения и флаг тестов
`include_tests`	`bool`	`False`	Включать тестовые файлы
`exclude_patterns`	`list[str] \\| None`	`None`	Glob-шаблоны для исключения
`include_patterns`	`list[str] \\| None`	`None`	Glob-шаблоны для включения
`domain_config`	`str \\| None`	`None`	Путь к файлу конфигурации домена
`no_index`	`bool`	`False`	Пропустить создание индексов
`timeout`	`int \\| None`	`3600`	Тайм-аут RPC (секунды)

Возвращает: GoCPGParseResult

update¶

Инкрементальное обновление существующей базы CPG. Потоковый серверный RPC с событиями прогресса.

Параметр	Тип	По умолчанию	Описание
`input_path`	`str`	обязательный	Путь к каталогу с исходным кодом
`output_path`	`str`	обязательный	Путь к существующему файлу DuckDB
`git_refs`	`GitRefConfig \\| None`	`None`	Диапазон коммитов (переопределяет отдельные параметры)
`from_commit`	`str \\| None`	`None`	Начальный хеш коммита
`to_commit`	`str \\| None`	`None`	Конечный хеш коммита
`language`	`str \\| None`	`None`	Язык исходного кода
`force`	`bool`	`False`	Принудительная полная пересборка
`domain_config`	`str \\| None`	`None`	Путь к файлу конфигурации домена
`timeout`	`int \\| None`	`600`	Тайм-аут RPC (секунды)

Возвращает: GoCPGUpdateResult

ci_update¶

Инкрементальное обновление для CI-конвейера с поддержкой base/head ссылок. Унарный RPC.

Параметр	Тип	По умолчанию	Описание
`input_path`	`str`	обязательный	Путь к каталогу с исходным кодом
`output_path`	`str`	обязательный	Путь к файлу DuckDB
`git_refs`	`GitRefConfig \\| None`	`None`	Диапазон коммитов (переопределяет отдельные параметры)
`base_ref`	`str`	`"origin/main"`	Базовая git-ссылка
`head_ref`	`str`	`"HEAD"`	Целевая git-ссылка
`cache_dir`	`str \\| None`	`None`	Каталог кеша для промежуточных результатов
`language`	`str \\| None`	`None`	Язык исходного кода
`timeout`	`int \\| None`	`600`	Тайм-аут RPC (секунды)

Возвращает: GoCPGCIUpdateResult

create_indexes¶

Создание или перестроение индексов в базе CPG. Унарный RPC.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`timeout`	`int \\| None`	`300`	Тайм-аут RPC (секунды)

Возвращает: None

Запросы и поиск¶

query¶

Выполнение SQL-запроса к базе CPG. Унарный RPC.

Параметр	Тип	По умолчанию	Описание
`sql`	`str`	обязательный	Строка SQL-запроса
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`timeout`	`int \\| None`	`60`	Тайм-аут RPC (секунды)

Возвращает: GoCPGQueryResult

search¶

Структурный поиск кода по шаблонам tree-sitter. Унарный RPC.

Параметр	Тип	По умолчанию	Описание
`pattern`	`str`	обязательный	Шаблон поиска
`language`	`str`	обязательный	Язык исходного кода
`db_path`	`str \\| None`	`None`	Путь к файлу DuckDB
`max_results`	`int \\| None`	`None`	Максимальное число результатов (0 = без ограничений)
`timeout`	`int \\| None`	`60`	Тайм-аут RPC (секунды)

Возвращает: GoCPGSearchResult

stats¶

Получение статистики базы CPG. Унарный RPC.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`timeout`	`int \\| None`	`60`	Тайм-аут RPC (секунды)

Возвращает: GoCPGStatsResult

quality_stats¶

Получение статистики качества кода (точки сложности, мёртвый код). Унарный RPC.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`top`	`int`	`20`	Количество записей в каждой категории
`timeout`	`int \\| None`	`60`	Тайм-аут RPC (секунды)

Возвращает: GoCPGQualityStatsResult

Жизненный цикл и обслуживание¶

lifecycle_status¶

Получение текущего lifecycle snapshot для базы. Соответствует LifecycleService.GetDatabaseStatus.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к целевому DuckDB-файлу
`repo_path`	`str \\| None`	`None`	Корень git-репозитория для freshness checks
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: GoCPGLifecycleStatusResult

Модель включает поля state, read_available, active_operation, progress_percent, started_at, last_successful_update_at, last_successful_maintenance_at, lock metadata и freshness details.

watch_database_status¶

Потоковая выдача status snapshots для базы. Соответствует LifecycleService.WatchDatabaseStatus.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к целевому DuckDB-файлу
`repo_path`	`str \\| None`	`None`	Корень git-репозитория для freshness checks
`max_events`	`int`	`0`	Максимальное число событий (0 = до отмены)
`poll_interval_ms`	`int`	`0`	Переопределение poll interval в миллисекундах
`timeout`	`int \\| None`	`60`	Тайм-аут RPC (секунды)

Возвращает: AsyncIterator[GoCPGLifecycleStatusResult]

freshness_status¶

Получение freshness-only проекции для базы. Соответствует LifecycleService.GetFreshnessStatus.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к целевому DuckDB-файлу
`repo_path`	`str \\| None`	`None`	Корень git-репозитория для freshness checks
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: GoCPGFreshnessStatusResult

run_maintenance¶

Явный запуск DuckDB maintenance внутри GoCPG. Соответствует LifecycleService.RunMaintenance.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к целевому DuckDB-файлу
`mode`	`str`	обязательный	`checkpoint_vacuum` или `copy_from_database_rewrite`
`timeout`	`int \\| None`	`300`	Тайм-аут RPC (секунды)

Возвращает: GoCPGMaintenanceResult

maintenance_plan¶

Получение текущей рекомендации по обслуживанию базы. Соответствует LifecycleService.GetMaintenancePlan.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к целевому DuckDB-файлу
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: GoCPGMaintenancePlanResult

Навигация¶

nav_symbols¶

Поиск символов по имени в графе кода. Поддерживает точное совпадение и поиск по префиксу.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`name`	`str`	обязательный	Имя символа для поиска
`prefix`	`bool`	`False`	Включить поиск по префиксу
`node_type`	`str`	`""`	Фильтр по типу узла
`file`	`str`	`""`	Фильтр по пути к файлу
`visibility`	`str`	`""`	Фильтр по видимости
`limit`	`int`	`0`	Максимальное число результатов (0 = без ограничений)
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: list[NavSymbolResult]

nav_callers¶

Поиск вызывающих функций для указанного метода с возможностью транзитивного обхода.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`name`	`str`	обязательный	Имя метода
`depth`	`int`	`0`	Глубина транзитивного обхода (0 = только прямые)
`limit`	`int`	`0`	Максимальное число результатов (0 = без ограничений)
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: list[NavCallerResult]

nav_callees¶

Поиск вызываемых функций из указанного метода с возможностью транзитивного обхода.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`name`	`str`	обязательный	Имя метода
`depth`	`int`	`0`	Глубина транзитивного обхода (0 = только прямые)
`limit`	`int`	`0`	Максимальное число результатов (0 = без ограничений)
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: list[NavCalleeResult]

nav_hierarchy¶

Обход иерархии наследования типов (родительские/дочерние типы).

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`name`	`str`	обязательный	Имя типа
`direction`	`str`	`""`	`"up"` (родительские), `"down"` (дочерние) или `""` (оба направления)
`depth`	`int`	`0`	Глубина обхода (0 = без ограничений)
`limit`	`int`	`0`	Максимальное число результатов (0 = без ограничений)
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: list[NavHierarchyNode]

nav_outline¶

Получение структуры файла (функции, классы, методы).

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`file`	`str`	обязательный	Путь к файлу внутри проекта
`limit`	`int`	`0`	Максимальное число результатов (0 = без ограничений)
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: list[NavOutlineEntry]

nav_usages¶

Поиск всех использований (ссылок) символа.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`name`	`str`	обязательный	Имя символа
`limit`	`int`	`0`	Максимальное число результатов (0 = без ограничений)
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: list[NavUsageResult]

nav_deps¶

Получение зависимостей на уровне файлов (импорты/включения).

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`file`	`str`	обязательный	Путь к файлу внутри проекта
`direction`	`str`	`""`	`"in"` (зависящие), `"out"` (зависимости) или `""` (оба направления)
`limit`	`int`	`0`	Максимальное число результатов (0 = без ограничений)
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: list[NavDepResult]

nav_resolve¶

Разрешение имени символа в цепочку полностью квалифицированных имён.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`name`	`str`	обязательный	Имя символа для разрешения
`signature`	`str`	`""`	Сигнатура метода для устранения неоднозначности
`file`	`str`	`""`	Подсказка по файлу для устранения неоднозначности
`limit`	`int`	`0`	Максимальное число шагов разрешения (0 = без ограничений)
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: list[NavResolveStep]

Управление ветками¶

list_frontends¶

Получение списка доступных языковых фронтендов на сервере.

Параметр	Тип	По умолчанию	Описание
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: list[GoCPGFrontendInfo]

list_branches¶

Получение списка веток CPG в базе данных.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: list[GoCPGBranchInfo]

switch_branch¶

Переключение активной ветки CPG в базе данных.

Параметр	Тип	По умолчанию	Описание
`branch_name`	`str`	обязательный	Целевое имя ветки
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: None

prune_branches¶

Удаление веток из базы данных, которые более не существуют в git-репозитории.

Параметр	Тип	По умолчанию	Описание
`input_path`	`str`	обязательный	Путь к репозиторию с исходным кодом
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: int (количество удалённых веток)

list_submodules¶

Получение списка подмодулей, отслеживаемых в базе CPG.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: list[GoCPGSubmoduleInfo]

prune_submodules¶

Удаление данных подмодулей, которые более не присутствуют в репозитории.

Параметр	Тип	По умолчанию	Описание
`input_path`	`str`	обязательный	Путь к репозиторию с исходным кодом
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: int (количество удалённых подмодулей)

Механизм шаблонов¶

scan¶

Запуск правил шаблонов по базе CPG. Потоковый серверный RPC с событиями обнаружения.

Параметр	Тип	По умолчанию	Описание
`db_path`	`str`	обязательный	Путь к файлу DuckDB
`config`	`ScanConfig \\| None`	`None`	Конфигурация сканирования (переопределяет отдельные параметры)
`rule_dirs`	`list[str] \\| None`	`None`	Каталоги с YAML-файлами правил
`rule_id`	`str \\| None`	`None`	Запуск одного правила по идентификатору
`severity_filter`	`str \\| None`	`None`	Фильтр по уровню серьёзности
`incremental`	`bool`	`False`	Инкрементальное сканирование (только изменённые файлы)
`fix`	`bool`	`False`	Применить предложения автоисправления
`dry_run`	`bool`	`False`	Показать исправления без применения
`output_format`	`str \\| None`	`None`	Формат вывода
`output_path`	`str \\| None`	`None`	Путь к файлу вывода
`domain_rules`	`bool`	`False`	Включить доменные правила
`timeout`	`int \\| None`	`300`	Тайм-аут RPC (секунды)

Возвращает: GoCPGScanResult

validate_rule¶

Валидация YAML-файла правила шаблона, с возможностью проверки на тестовом коде. Унарный RPC.

Параметр	Тип	По умолчанию	Описание
`rule_path`	`str`	обязательный	Путь к YAML-файлу правила
`test_code`	`str \\| None`	`None`	Фрагмент тестового кода
`test_lang`	`str \\| None`	`None`	Язык тестового кода
`timeout`	`int \\| None`	`30`	Тайм-аут RPC (секунды)

Возвращает: dict[str, Any]

Примечания по транспорту¶

GrpcTransport.check_health() является клиентским helper-методом проверки соединения, а не публичным gRPC RPC. Он использует ListFrontends как лёгкий probe и поэтому намеренно исключён из RPC-surface, который отслеживает docs-sync.