Graphify-Labs/graphify: локальный AST‑парсинг

Graphify-Labs/graphify: локальный AST‑парсинг

Turn any codebase, docs, SQL schemas, configs and PDFs into a queryable graph via /graphify skill for Claude Code, Cursor, Gemini CLI, using deterministic AST parsing.

Graphify: локальный AST‑парсинг кода для разработки

Определение и возможности

Graphify‑Labs/graphify — это локальный инструмент, который превращает любой кодовый репозиторий, техническую документацию, схемы SQL, конфигурационные файлы и даже PDF‑документы в queryable‑граф через скилл /graphify. Парсинг выполняется полностью на машине‑клиенте, что гарантирует детерминированность и отсутствие сетевых задержек.

Основные возможности:

1. Полный охват – от небольших скриптов до многократных микросервисных проектов.
2. Поддержка множества форматов – Python, Go, Java, SQL, YAML, TOML, JSON, а также PDF‑страницы.
3. Интеграция с AI‑агентами – Claude Code, Cursor, Gemini CLI получают готовый граф и могут выполнять запросы типа «найти все функции, использующие PostgreSQL».
4. Детерминированный вывод – один и тот же набор файлов всегда даёт одинаковый граф, что удобно для тестов и CI.

Пример запуска Graphify в терминале:

bashКопировать
# базовый вариант
graphify --input /home/alexey/projects/my‑service \
         --skill /graphify \
         --output /tmp/graph.json

Для удобства можно задать alias в ~/.bashrc:

bashКопировать
alias gf='graphify --skill /graphify'

Теперь достаточно выполнить gf --input ./my‑service и получить файл graph.json, который можно передать в любой из поддерживаемых агентов. Подробнее о возможностях смотрите в статье Graphify‑Labs/graphify: локальный AST‑парсинг кода и docs.

---

Сценарии применения

1. Статический анализ кода

С помощью Graphify можно построить граф зависимостей и быстро найти «мусорный» код, который не используется в текущей сборке. Например, запрос «найти все импорты, которые не встречаются ни в одном модуле» выглядит так:

bashКопировать
graphify --input ./src \
         --skill '/graphify query "find unused imports"' \
         --output /tmp/unused-imports.json

Результат удобно импортировать в VS Code или в пайплайн CI для автоматического удаления.

2. Инспекция схем баз данных

SQL‑схемы (DDL‑файлы) парсятся в граф, где узлы – таблицы, столбцы, внешние ключи. Это позволяет задавать вопросы в стиле «Какие таблицы связаны с orders через customer_id?»

bashКопировать
graphify --input ./db/schema.sql \
         --skill '/graphify query "list tables linked to orders"' \
         --output /tmp/db‑links.json

Полученный JSON удобно визуализировать в Graphistry или в простом скрипте на Python.

3. Анализ конфигураций

YAML‑ или TOML‑конфиги, используемые в Docker‑Compose, Proxmox или Ansible, также преобразуются в граф. Пример запроса «найти все сервисы, использующие образ nginx:alpine»:

bashКопировать
graphify --input ./docker-compose.yml \
         --skill '/graphify query "services using nginx:alpine"' \
         --output /tmp/compose‑services.json

4. Обработка технической документации и PDF

PDF‑страницы, где описаны архитектурные решения, парсятся с помощью встроенного OCR‑модуля. После этого можно задавать вопросы «Какие шаги описаны для миграции на Kubernetes?».

bashКопировать
graphify --input ./docs/architecture.pdf \
         --skill '/graphify query "migration steps to k8s"' \
         --output /tmp/migration‑steps.json

Эти примеры показывают, насколько гибко может применяться локальный AST‑парсинг в повседневной работе системного инженера.

Для более детального ознакомства с сценариями и примерами кода см. материал Graphify‑Labs/graphify: локальный AST‑парсинг.

---

Если у вас возникнут вопросы — пишите в комментариях, я постараюсь ответить без лишних вводных фраз.

Архитектура: детерминированный парсинг без векторов

Локальный AST‑парсинг без векторного хранилища

Когда мы говорим об анализе больших кодовых баз с помощью AI-агентов, стандартный путь — это RAG (Retrieval-Augmented Generation) с использованием векторных баз данных. Вы разбиваете код на куски (chunks), превращаете их в эмбеддинги и ищете наиболее похожие фрагменты. С практической точки зрения это работает неплохо, но у такого подхода есть фундаментальный изъян: потеря контекста. Векторный поиск понимает семантическую близость слов, но он не понимает структуру программы. Он не знает, что функция в одном файле вызывает метод в другом, если эти фрагменты не попали в один «чанк».

Graphify меняет парадигму. Вместо того чтобы полагаться на вероятностный поиск по сходству векторов, инструмент использует детерминированный парсинг абстрактного синтаксического дерева (AST). Это позволяет превратить код, SQL-схемы или конфигурационные файлы в графовую структуру, где узлы — это сущности (классы, функции, переменные), а ребра — логические связи между ними.

Если мы сравним это с тем, как работает Ponytail: AI‑агент, как ленивый старший разработчик, то увидим разницу в подходе к навигации. Там агент имитирует логику человека, а Graphify предоставляет ему «карту местности», построенную не на ощущениях, а на строгом синтаксическом анализе.

Преимущество здесь в предсказуемости. Вам не нужно подбирать размер окна чанка или настраивать параметры индексации. Результат парсинга всегда будет одинаковым для одного и того же исходного кода. Это особенно важно при работе с инструментами вроде Claude Code, где точность извлечения контекста напрямую влияет на качество генерации кода.

Детерминированные границы и объяснение ребер

Главная проблема при анализе кода — это определение границ. Где заканчивается одна логическая единица и начинается другая? В векторном подходе границы часто проходят «по живому», разрывая функции или классы пополам. В Graphify границы определяются правилами грамматики языка.

Когда парсер проходит по коду, он строит дерево, где каждый узел имеет четкую принадлежность. Например, если мы анализируем Python-проект, парсер точно знает, что блок внутри def является дочерним элементом этой функции. Это позволяет создавать ребра (связи) на основе реальных зависимостей.

Типы связей в графе можно разделить на несколько категорий:

1. Иерархические: связь «класс — метод» или «модуль — функция».
2. Вызовы (Call edges): связь между местом вызова функции и её определением.
3. Ссылочные (Reference edges): использование переменной или импорт модуля.

С точки зрения архитектуры, это позволяет агенту не просто «читать» кусок текста, а выполнять запросы к графу. Вместо вопроса «найди мне код, похожий на этот», агент может спросить: «какие функции зависят от этого метода?».

Для интеграции в рабочий процесс, например, через CLI, процесс выглядит следующим образом. Сначала мы подготавливаем окружение, а затем запускаем парсинг. Если вы используете инструменты для автоматизации, конфигурация может выглядеть примерно так:

yamlКопировать
# Пример логики конфигурации для обработки проекта
project_analysis:
  source_path: "./src"
  parser_engine: "ast"
  output_format: "graph"
  include_extensions:
    - ".py"
    - ".sql"
    - ".yaml"
  # Мы задаем правила, по которым строятся ребра
  edge_rules:
    - type: "dependency"
      on: "import_statement"
    - type: "invocation"
      on: "function_call"

Такой подход делает работу AI-агента менее хаотичной. Если раньше агент мог «галлюцинировать» связи, которых нет, то теперь он опирается на структуру, которую невозможно оспорить, так как она выведена напрямую из синтаксиса языка. Это превращает процесс из «угадывания» в полноценный семантический поиск по структуре.

Интеграция с Claude Code, Cursor, Gemini CLI для разработки

Поддержка популярных AI‑инструментов

Главная проблема при работе с AI-агентами вроде Ponytail или Claude Code заключается в том, что они часто «галлюцинируют» структуру проекта. Когда вы просите агента проанализировать зависимости, он пытается угадать их, читая файлы как обычный текст. Это не даёт предсказуемости: агент может пропустить импорт или неверно интерпретировать вложенность функций.

Graphify решает эту задачу через механизм skill. Вместо того чтобы скармливать нейросети сырой код, вы предоставляете ей доступ к графу, построенному на основе AST (Abstract Syntax Tree). Это превращает процесс из «чтения текста» в «запросы к структуре».

Инструменты, которые получают профит от такой интеграции:

• Claude Code: через добавление кастомного навыка (skill), что позволяет агенту выполнять точечные запросы к графу кода.
• Cursor: использование графа для более точного контекста при работе с Codebase Indexing.
• Gemini CLI: возможность передавать структурированные данные о схемах БД или конфигурациях вместо огромных текстовых дампов.

С практической точки зрения, интеграция сводится к тому, что агент перестаёт быть просто «умным чатом» и становится полноценным инструментом анализа, который понимает иерархию вашего проекта так же, как это делает компилятор. Это концептуально близко к тому, как AI-агент работает в режиме ленивого разработчика, когда вместо перебора всех файлов он сразу обращается к нужным узлам графа.

Пример использования в реальном проекте

Представим типичную ситуацию: у вас есть разросшийся монолит на Python, и вам нужно понять, какие функции затронет изменение сигнатуры одного из базовых методов. Обычный поиск по тексту (grep) здесь подведёт, так как он не учитывает область видимости и динамические импорты.

Если вы используете Graphify, процесс превращается в структурированный запрос. Сначала убедитесь, что у вас установлен инструмент и инициализирован локальный парсинг, как описано в материале про локальный AST-парсинг.

Допустим, мы работаем в терминале с Claude Code. Чтобы агент мог использовать возможности Graphify, мы подключаем его как навык. В конфигурационном файле или через CLI-команду мы определяем путь к нашему графу.

Пример логики запроса, который агент выполняет «под капотом» через /graphify:

bashКопировать
# Примерная команда для инициализации навыка в среде агента
/graphify add-skill --path ./my_project/ast_graph --type python

Теперь вы можете задать вопрос на естественном языке, но результат будет базироваться на детерминированном анализе:

Запрос пользователя:

«Найди все места в проекте, где вызывается метод process_data в модуле core/engine.py, и покажи цепочку наследования для этих вызовов».

Что делает агент:

1. Вместо того чтобы сканировать файлы, он обращается к графу через API Graphify.
2. Находит узел process_data.
3. Выполняет обход графа (graph traversal) по связям CallExpression.
4. Извлекает информацию о типах и иерархии классов.

Результат будет максимально точным:

textКопировать
Found 3 references to `process_data`:
1. core/handlers/api.py: line 42 -> calls `Engine.process_data`
2. core/workers/celery_task.py: line 115 -> calls `Engine.process_data`
3. tests/test_engine.py: line 12 -> calls `MockEngine.process_data` (Inheritance: MockEngine -> Engine)

Такой подход исключает ситуацию, когда агент находит похожие по названию, но не связанные по логике функции. Для сложных систем, где документация и код могут расходиться, использование графа для сопоставления SQL-схем и реальных моделей в коде — это единственный способ добиться консистентности. Подробнее о том, как это работает на низком уровне, можно почитать в обзоре локального AST-парсинга кода и docs.

Практические рекомендации: настройка и эксплуатация в продакшене

Настройка и запуск /graphify

Когда мы переходим от простого тестирования к использованию Graphify в реальных рабочих процессах, важно понимать: детерминированный AST-парсинг требует предсказуемой среды. Если вы планируете использовать инструмент в связке с Claude Code или Cursor для анализа больших репозиториев, запуск «просто в терминале» может привести к нехватке ресурсов или конфликтам зависимостей.

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

Для начала разверните сервис в Docker. Это обеспечит чистоту окружения и позволит избежать проблем с версиями системных библиотек при парсинге сложных SQL-схем или PDF-документов.

dockerfileКопировать
# Пример базового Dockerfile для развертывания Graphify
FROM python:3.11-slim

WORKDIR /app

# Устанавливаем системные зависимости для парсинга различных форматов
RUN apt-get update && apt-get install -y \
    build-essential \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# Запускаем через gunicorn для обеспечения стабильности в продакшене
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8080", "app:app"]

После сборки образа запустите контейнер, явно ограничив ресурсы. AST-парсинг — задача ресурсоёмкая, особенно на больших кодовых базах. Без лимитов один тяжелый запрос может «съесть» всю память на вашем домашнем сервере.

bashКопировать
# Запуск с ограничением памяти и CPU
docker run -d \
  --name graphify-service \
  --memory="4g" \
  --cpus="2.0" \
  -p 8080:8080 \
  graphify-labs/graphify:latest

Для интеграции с CLI-инструментами вам потребуется настроить эндпоинт /graphify. Если вы используете локальный AST-парсинг для анализа конфигов, убедитесь, что сетевая доступность между агентом и сервисом стабильна.

Мониторинг и поддержка в продакшене

Запуск сервиса — это только половина дела. Чтобы система оставалась предсказуемой, её нужно мониторить. В случае с Graphify основными метриками будут время обработки запроса (latency) и потребление памяти при парсинге глубоких деревьев AST.

Во-первых, я всегда настраиваю сбор логов через journald или аналогичные системы, если сервис работает под управлением systemd. Это позволяет быстро понять, на каком этапе произошёл сбой: на этапе извлечения текста из PDF или при построении графа связей.

Если вы используете Docker, настройте сбор метрик для Prometheus. Вам важно отслеживать не только доступность API, но и корректность парсинга. Если агент начинает получать пустые графы вместо структур данных, это верный признак того, что формат входных данных изменился или парсер столкнулся с невалидной структурой.

Для базового мониторинга состояния контейнера можно использовать простой healthcheck в docker-compose.yml:

yamlКопировать
services:
  graphify:
    image: graphify-labs/graphify:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Во-вторых, стоит обратить внимание на хранение промежуточных данных. Если вы строите графы для огромных репозиториев, кэширование результатов парсинга станет необходимостью. Без него каждый запрос агента будет приводить к повторному полному обходу AST, что создаст ненужную нагрузку на процессор.

При масштабировании решения, например, при переходе от одного сервера к кластеру (как в случае с настройкой инфраструктуры для AI-агентов), используйте внешний Redis для хранения состояний графов. Это позволит разным нодам кластера работать с единой актуальной версией структуры вашего кода или документации.

Часто задаваемые вопросы

Как Graphify влияет на безопасность исходного кода?

Поскольку парсинг выполняется локально на вашей машине, исходный код и содержимое документов не передаются на сторонние серверы для анализа. Инструмент лишь подготавливает структурированный граф, который затем передаётся AI-агенту в рамках вашего рабочего процесса. С практической точки зрения это минимизирует риски утечки интеллектуальной собственности при работе с закрытыми репозиториями.

Можно ли использовать Graphify для анализа больших монолитов?

Да, инструмент спроектирован для работы с проектами разного масштаба — от небольших скриптов до сложных микросервисных архитектур. Детерминированный подход к AST-парсингу позволяет получать предсказуемый результат даже при обработке глубоко вложенных зависимостей. Однако при работе с очень крупными базами данных стоит учитывать объем оперативной памяти, необходимой для построения графа в памяти.

В чём преимущество AST-парсинга перед обычным поиском по тексту?

Обычный поиск (например, через grep) находит просто совпадения строк, что часто приводит к ложноположительным результатам. AST-парсинг понимает структуру кода: он отличает вызов функции от её определения или комментария. Это позволяет AI-агентам вроде Cursor или Claude Code строить точные логические связи, например, находить не просто упоминание переменной, а именно её использование в конкретном контексте.

Какие форматы файлов поддерживает инструмент?

Graphify поддерживает широкий спектр форматов, включая языки программирования (Python, Go, Java), конфигурационные файлы (YAML, TOML, JSON), схемы SQL и даже PDF-документы. Это делает его универсальным инструментом для создания единого графа знаний, объединяющего код, инфраструктурные настройки и техническую документацию.

Как интегрировать полученный граф в существующий рабочий процесс?

Самый простой способ — использовать команду для генерации JSON-файла и передавать его в поддерживаемые AI-инструменты. Для автоматизации этого процесса можно настроить alias в вашем shell-профиле или добавить шаг генерации графа в CI-пайплайн. Это обеспечит актуальность контекста, который видят ваши AI-агенты при анализе изменений в коде.