Перейти к основному содержимому

LSP-сервер CodeGraph

Подключите LSP-клиент к CodeGraph через GoCPG gRPC, проверьте диагностику и сведения о методах, найдите причины отсутствующих результатов.

Руководства

LSP-сервер CodeGraph помогает разбирать методы прямо в редакторе: видеть сложность, связи вызовов и замечания анализа рядом с исходным кодом. Это удобно при знакомстве с репозиторием и ревью изменений: откройте метод, изучите его метрики и переходите к связанным участкам кода.

Редактор отправляет запросы по Language Server Protocol (LSP). CodeGraph сопоставляет URI открытого файла с путём в существующем CPG и запрашивает граф через GoCPG gRPC. Обновляйте CPG рабочим процессом проекта перед проверкой новой ревизии.

Что показывает редактор

Что показывает редактор
Задача Возможность LSP Результат
Оценить метод перед изменением Hover Сложность, размер, число параметров и связи вызовов в подсказке.
Найти контекст метода CodeLens Число вызывающих и вызываемых методов над объявлением; доступная подсказка о taint flow.
Разобрать замечания анализа Диагностика при открытии и сохранении Замечания с привязкой к строкам файла.

Предварительные условия

Перед запуском:

  1. Установите CodeGraph и зависимости по разделу локальной установки в руководстве CLI. Активируйте это окружение Python, чтобы команда codegraph-lsp была доступна процессу редактора.
  2. Постройте или обновите CPG целевого проекта по руководству по импорту.
  3. Убедитесь, что другой процесс не заменяет базу и не изменяет её схему во время сессии редактора.
  4. Укажите базу проекта, открытого в редакторе, и проверьте, что сервис GoCPG может её прочитать.
  5. Обеспечьте доступ процесса LSP к GoCPG gRPC на localhost:50051. LSP использует этот адрес по умолчанию для запросов к CPG.

Проверка команды

codegraph-lsp --help

Запустите транспорт standard input/output с существующим графом:

Примеры используют PowerShell. После установки консольной команды рабочий каталог не важен. Замените обозначение в кавычках ниже на одобренный путь к базе, доступный сервису GoCPG. Сохраните кавычки, если путь содержит пробелы. Выберите граф репозитория, открытого в редакторе.

codegraph-lsp --db "<cpg.duckdb>"

В исходном репозитории также работает совместимая команда python -m codegraph_lsp, но в конфигурации установленного клиента лучше использовать консольную точку входа.

Поддерживаемые параметры

Поддерживаемые параметры
Параметр Назначение
--db <cpg.duckdb> Обязательный путь к CPG под управлением GoCPG.
--complexity-threshold <integer> Порог диагностики сложности; по умолчанию 10.
--transport stdio|tcp Транспорт LSP; по умолчанию stdio.
--host <address> Адрес TCP; по умолчанию 127.0.0.1.
--port <integer> Порт TCP; по умолчанию 2087.
--log-level debug|info|warning|error Уровень журнала; по умолчанию info.

TCP предназначен для локальной или защищённой сетевой границы:

codegraph-lsp --db "<cpg.duckdb>" --transport tcp --host 127.0.0.1 --port 2087 --log-level info

Сервер не добавляет аутентификацию и TLS к TCP-транспорту. Не привязывайте его к недоверенному интерфейсу без одобренного защитного слоя.

Пример для OpenCode

Создайте opencode.json в корне проекта, который вы открываете в OpenCode, и сохраните в нём конфигурацию ниже. Если файл уже существует, добавьте объект codegraph в его раздел lsp, сохранив остальные настройки.

OpenCode направляет файлы в LSP-сервер по расширениям. Укажите команду из установленного окружения Python и расширения файлов вашего проекта:

{
  "lsp": {
    "codegraph": {
      "command": ["codegraph-lsp", "--db", "<cpg.duckdb>"],
      "extensions": [".py", ".go", ".js", ".ts", ".java", ".c", ".cpp"]
    }
  }
}

Замените <cpg.duckdb> точным путём к CPG вашего проекта перед запуском. Остальная структура JSON готова для раздела lsp. В JSON экранируйте обратные слэши Windows, например C:\\workspace\\project.duckdb.

После изменения конфигурации перезапустите LSP-соединение клиента. Откройте файл, присутствующий в выбранном графе, и сохраните его. Проверьте ответ initialize, журнал сервера, опубликованную диагностику, hover на известном методе и результаты CodeLens. Сверьте имена файлов и сведения о методах с текущими исходниками. Для проверки запроса к графу выберите известный метод: его имя и метрики должны появиться в hover, а связи вызовов — в CodeLens.

События и результаты анализа

Сервер обрабатывает открытие, сохранение и закрытие документа. Сейчас он предоставляет:

  • textDocument/hover с метриками метода;
  • textDocument/codeLens с числом callers/callees и доступной подсказкой о taint flow;
  • диагностику после открытия или сохранения документа.

Диагностика показывает замечания о мёртвых методах и цикломатической сложности из выбранного CPG. Для метода со сложностью выше --complexity-threshold сервер публикует замечание high-complexity. При закрытии файла сервер очищает его диагностику.

Например, метод со сложностью 11 при пороге 10 получает замечание high-complexity на строке объявления. Откройте подсказку метода и сверьте показатель сложности. После изменения кода завершите LSP-подключение и обновите граф рабочим процессом проекта. Подключитесь снова, сохраните файл и проверьте новое значение. Если оно стало не выше 10, замечание о превышении этого порога исчезнет.

Если ожидаемое замечание отсутствует, проверьте журнал запроса, таблицы и столбцы выбранного CPG по разделу «Свежесть и сопоставление путей».

Hover и CodeLens

Hover показывает сложность метода, число входящих и исходящих связей (fan-in и fan-out), вызывающие методы (callers), размер в строках (LOC), число параметров и признаки метода.

fan-in помогает понять, сколько методов зависит от выбранного метода, а fan-out — сколько методов он вызывает. LOC показывает размер метода в строках. Вместе со сложностью эти метрики помогают выбрать участок для подробного ревью и оценить объём изменения.

CodeLens показывает число вызывающих и вызываемых методов. При наличии данных анализа потоков он также показывает путь распространения данных (taint). Подсказка taint: source→sink называет методы начала и конца найденной связи.

Изменения по правилам

Для поиска и исправления совпадений по шаблону используйте руководство по поиску шаблонов. Сначала получите и изучите diff, затем примените выбранные изменения и выполните проверки проекта. Обновите CPG и сохраните файл в редакторе, чтобы увидеть новые метрики и диагностику.

Свежесть и сопоставление путей

LSP-сервер использует адаптеры запросов GoCPG на чтение и преобразует URI файлов в относительные пути рабочей области с прямыми слэшами. Если редактор ничего не показывает:

  1. Проверьте журнал сервера на ошибки запуска и запросов.
  2. Убедитесь, что граф относится к открытому репозиторию.
  3. Обновите CPG поддерживаемым процессом проекта.
  4. Сохраните или заново откройте файл, чтобы запросить диагностику.
  5. Проверьте сопоставимость имён файлов в графе с относительными путями редактора.
  6. Проверьте доступность GoCPG gRPC и возможность запроса выбранной базы.

Не исправляйте устаревший граф прямым редактированием DuckDB. Перед обслуживанием согласуйте остановку процесса записи с его владельцем.

Работа соединений

Connection pool exhausted означает, что сервер занят обработкой других запросов. Дождитесь их завершения и повторите действие в редакторе. GoCPG gRPC transport unavailable for LSP означает, что транспорт получить не удалось. Выбирайте восстановление по фактической ошибке. Перезапуск LSP может очистить оборванную сессию, но не исправит устаревший CPG и не восстановит доступ к недоступному сервису GoCPG.

Связанные руководства

Сообщить об ошибке в документации