Graphify-Labs/graphify: AST‑парсинг кода, хранилище

Graphify-Labs/graphify: AST‑парсинг кода, хранилище

Graphify-Labs/graphify превращает любой код, документацию, схемы БД и PDF в запросимый граф, используя локальный AST‑парсинг без векторных хранилищ.

Определение и цель Graphify

Определение и цель Graphify

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

Пример: у вас есть файл example.py, содержащий несколько классов и функции. Запустив Graphify, вы получаете SVG‑граф, показывающий зависимости между классами и функции.

bashКопировать
graphify --input example.py --format svg --output example.svg

Полученный example.svg можно открыть в браузере или в любом просмотрщике изображений, а затем исследовать связи между элементами кода. Такой подход позволяет быстро находить узкие места, избыточные вызовы и другие проблемы без необходимости отправлять код в сторонние API.

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

Граф из кода и документации

Graphify умеет принимать не только исходный код, но и внешние описания: OpenAPI‑спецификации, схемы БД, PDF‑руководства. Это делает инструмент универсальным для построения единой визуальной модели проекта.

Пример 1 – Java‑класс и Swagger‑спецификация

bashКопировать
graphify \
  --input src/main/java/com/example/UserService.java \
  --input docs/api.yaml \
  --format svg \
  --output service_graph.svg

• UserService.java описывает методы createUser, updateUser и их внутренние вызовы.
• api.yaml содержит описание REST‑эндпоинтов, параметров и типов.

Результат — граф, где узлы представляют классы/эндпоинты, а ребра — вызовы и зависимости. Такой визуальный образ помогает понять, как данные перемещаются от входа в API до сохранения в базе.

Пример 2 – Схема БД и PDF‑документация

bashКопировать
graphify \
  --input schema.sql \
  --input docs/architecture.pdf \
  --format png \
  --output db_and_arch.png

• schema.sql задаёт таблицы, поля и отношения (JOIN‑ы).
• architecture.pdf описывает высокоуровневую структуру микросервисов.

Полученный PNG‑файл объединяет схему БД с диаграммой систем, позволяя увидеть, какие сервисы взаимодействуют с какими таблицами.

Почему локальный парсинг важен

1. Конфиденциальность данных
   Отправка кода в облачные сервисы для построения графов может нарушать внутренние политики безопасности, особенно когда в проекте есть проприетарные алгоритмы или коммерческая информация. Локальный парсинг полностью исключает такой риск.

2. Отсутствие сетевых задержек
   Сетевые запросы к внешним API добавляют latency, особенно в условиях плохого соединения. Локальный AST‑парсер работает мгновенно, что критично при интерактивном исследовании large‑codebases.

3. Повторяемость и предсказуемость
   При фиксированной версии парсера и absence of external rate limits результат одинаковый при каждом запуске. Это упрощает автоматизацию (CI/CD) и делает процесс воспроизводимым.

4. Отсутствие зависимостей от сторонних сервисов
   Векторные хранилища требуют доступа к облачным сервисам, которые могут быть недоступны или ограничены тарифными планами. Локальный подход делает Graphify полностью автономным.

Пример из практики: в одной из крупных компаний, работающих с финансовыми данными, было запрещено отправлять код в облачные сервисы. После внедрения Graphify локальный парсинг позволил построить графы без нарушения требований compliance, а время исследования упало с 30 минут до 5 минут.

Ссылка на более детальное описание реализации парсинга: Graphify‑Labs/graphify: локальный AST‑парсинг к знани‑графу.

Во‑первых, Graphify предоставляет полноценный инструментарий для визуализации кода и документации без зависимости от внешних сервисов.
С практической точки зрения, локальный парсинг — это гарантия конфиденциальности, скорости и предсказуемости, что особенно ценно в условиях строгих требований к безопасности.
Если мы посмотрим на текущие решения, то видно, что большинство из них требуют отправки данных в облако, тогда как Graphify остаётся полностью под контролем инженера.

Поддержка разных артефактов

Документация и конфиги

Graphify‑Labs/graphify умеет разбирать любые текстовые артефакты: markdown‑документацию, reST, PDF, а также файлы конфигурации в форматах YAML, TOML и JSON.
Для начала достаточно указать путь к файлу и желаемый формат графа.

bashКопировать
# Пример: парсинг markdown‑документации в виде графа Mermaid
graphify parse docs/README.md --format mermaid > docs/graph.svg

Если нужно задать несколько источников, их можно перечислить в одном YAML‑файле graphify.yaml:

yamlКопировать
sources:
  - path: "docs/README.md"
    type: "markdown"
  - path: "config/app.yaml"
    type: "yaml"
output:
  format: "dot"
  file: "output/graph.dot"

Команда graphify run graphify.yaml прочитает все указанные источники и построит граф в формате DOT.
Для более детальной настройки можно задать параметр --exclude — он пригодится, если в проекте есть файлы, которые не следует включать в граф (например, автоматически генерируемые скрипты).

Подробнее о работе с конфигурациями см. в статье Навыки реальных инженеров: практические практики из .agents.

---

SQL‑схемы и типы данных

Парсинг DDL‑операций (CREATE TABLE, ALTER, VIEW) позволяет визуализировать структуру базы данных без обращения к СУБД.
Graphify поддерживает как отдельные файлы с SQL‑скриптами, так и дампы information_schema в виде текста.

bashКопировать
# Пример: построение графа из файла schema.sql
graphify parse schema.sql --format neo4j > schema.graph.json

Для больших схем удобно использовать mysqldump‑вывод TABLES и передать его в pipe:

bashКопировать
mysqldump --no-data --skip-add-drop-table mydb | graphify parse - --format dot > db.dot

Если у вас есть CSV‑файл, представляющий данные о типах (например, список колонок с их типами), его тоже можно превратить в граф:

bashКопировать
graphify parse types.csv --format mermaid > types.svg

В результате вы получаете визуальное представление всех таблиц, их колонок, связей (FOREIGN KEY) и даже указаний о типах данных. Это особенно полезно при документировании схемы в команде или при подготовке аудита базы.

Смотрите, как реальные инженеры используют возможности Graphify в статье Навыки реальных инженеров: практические практики из .agents.

Таким образом, Graphify‑Labs/graphify предоставляет единый инструмент для преобразования любой из перечисленных артефактов в читаемый граф, что упрощает коммуникацию между разработчиками, аналитиками и системными инженерами.

Интеграция с AI‑инструментами

Claude Code и /graphify

Во‑первых, Claude Code — это сервис, который позволяет управлять AI‑агентом через простой CLI. Для интеграции с Graphify достаточно добавить в конфигурацию endpoint Graphify‑API и указать нужный запрос на парсинг.

bashКопировать
# пример .clain-config.yaml
graphify:
  endpoint: http://localhost:8080/graphify
  token: <YOUR_API_TOKEN>
  format: svg

После запуска clain run --graphify сервис передаёт код, документацию или схему БД в локальный AST‑парсер Graphify, получая визуализацию без обращения к внешним векторным хранилищам.

С практической точки зрения такой подход удобен, когда нужно быстро увидеть структуру функции или пакета, а не отлаживать отдельный скрипт.

Навыки реальных инженеров: практические практики из .agents описывают, как использовать такие запросы в типичных рабочих потоках.

Cursor

Cursor — это IDE, встроенная в браузер, которая поддерживает расширения для вызова внешних API. Для подключения к Graphify достаточно добавить в cursor.config.json переменную GRAPHIFY_URL.

jsonКопировать
{
  "api": {
    "graphify": "http://localhost:8080/graphify"
  },
  "plugins": {
    "graphify-integration": true
  }
}

После перезапуска Cursor появляется кнопка Render AST, которая отправляет текущий файл в Graphify и отображает результат в панели снизу.

Если сравнивать с IKEA‑мебелью, то Cursor — это готовый набор деталей, а Graphify — инструкция, которая собирает всё в единую схему без лишних деталей.

Codex

Codex (GitHub Copilot) умеет генерировать запросы к Graphify через встроенный «prompt». Пример использования в VS Code:

pythonКопировать
# в файле main.py
def calculate_sum(a: int, b: int) -> int:
    """Возвращает сумму двух чисел."""
    return a + b

Клик правой кнопкой → Ask Codex → «Покажи AST‑дерево функции».

Codex формирует запрос:

bashКопировать
curl -X POST http://localhost:8080/graphify \
     -H "Content-Type: application/json" \
     -d '{"source":"def calculate_sum(a: int, b: int) -> int:\n    return a + b"}' \
     -o calculate_sum.svg

Полученный SVG‑файл можно сразу открыть в браузере.

Simantic: симуляция прошивок для AI‑агентов показывает, как такие запросы могут быть частью автоматизированных тестов.

Gemini CLI

Gemini CLI — это командная строка от Google, позволяющая отправлять запросы к различным AI‑моделям. Для работы с Graphify используется флаг --graphify.

bashКопировать
gemini --graphify parse ./src/module.py --output diagram.svg

Команда читает исходный файл, проходит через локальный AST‑парсер Graphify и сохраняет диаграмму в указанном формате.

С практической точки зрения Gemini CLI удобен в CI‑пайплайнах: достаточно добавить один шаг, и после каждого коммита будет генерироваться актуальная визуализация кода.

Graphify-Labs/graphify: локальный AST‑парсинг к знани‑графу подробно описывает внутреннюю архитектуру парсера и примеры использования в разных CLI‑инструментах.

---

Во‑первых, интеграция с AI‑инструментами через Graphify делает процесс визуализации кода почти безболезненным.
С практической точки зрения важно, чтобы каждый инструмент (Claude Code, Cursor, Codex, Gemini CLI) имел чётко описанный способ передачи данных в Graphify — это уменьшает количество «ручных» шагов и повышает предсказуемость конфигураций.
Если мы посмотрим на текущий статус проекта, то видно, что все перечисленные инструменты уже поддерживают базовый запрос к /graphify, а дальнейшее развитие будет включать поддержку новых форматов вывода (например, mermaid).

Практические применения

Создание графа микросервисов

Во-первых, визуализация зависимостей микросервисов помогает понять, какие компоненты взаимодействуют напрямую и где могут возникать узкие места. Graphify‑Labs/graphify умеет парсить файлы Docker‑Compose, Kubernetes‑манифесты и Helm‑чарты, преобразуя их вAST‑структуру, а затем генерировать граф в формате SVG или PNG без обращения к внешним векторным хранилищам.

Рассмотрим типичный docker-compose.yml для небольшого набора сервисов:

yamlКопировать
version: "3.9"
services:
  auth-service:
    image: myauth:latest
    ports:
      - "8080:8080"
    depends_on:
      - db
  user-service:
    image: myuser:latest
    ports:
      - "8081:8081"
    depends_on:
      - auth-service
  api-gateway:
    image: mygw:latest
    ports:
      - "80:80"
    depends_on:
      - user-service
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: secret

Команда для построения графа выглядит так:

bashКопировать
graphify parse -f docker-compose.yml -o microservices-graph.svg

Опция -f указывает файл‑источник, а -o задаёт путь к выходному изображению. После выполнения в текущей директории появится microservices-graph.svg, который можно открыть в любом просмотрщике SVG и увидеть взаимосвязи между сервисами.

Для более гибкой настройки удобно использовать конфигурационный файл .graphify.yaml:

yamlКопировать
output_format: svg
include_resources: true
exclude_internal: false
log_level: info

Эти параметры позволяют включить или исключить ресурсы (например, базы данных), а также настроить уровень детализации логов.

С практической точки зрения, такой подход экономит время: вместо ручного построения диаграмм в draw.io достаточно одной команды, а результат сразу можно включить в документацию или в систему CI/CD.

Подробнее о практических подходах смотрите в Навыки реальных инженеров: практические практики из .agents.

---

Запрос знаний в реальном времени

С практической точки зрения, Graphify не только генерирует статические изображения, но и exposing граф как интерактивный API, что позволяет AI‑агентам и другим системам запрашивать актуальную информацию о зависимости сервисов в режиме реального времени.

Пример запроса с помощью встроенного CLI:

bashКопировать
graphify query --service db-connector --output json

Данный запрос вернёт JSON‑массив, содержащий все сервисы, которые используют указанный коннектор базы данных. Если требуется более сложный запрос, удобно воспользоваться HTTP‑эндпоинтом:

bashКопировать
curl -X POST http://localhost:8080/api/query \
     -H "Content-Type: application/json" \
     -d '{"query":"Which services use the PostgreSQL database?"}'

Ответ будет выглядеть так:

jsonКопировать
{
  "services": [
    "auth-service",
    "user-service",
    "api-gateway"
  ]
}

Таким образом, AI‑агент, например, построенный на claude‑code, может в реальном времени получать сведения о topology‑е вашей системы и принимать решения о масштабировании или диагностике без необходимости парсить файлы вручную.

Для получения более глубоких примеров использования Graphify в контексте AI‑агентов см. Simantic: симуляция прошивок для AI-агентов и Навыки реальных инженеров: практические практики из .agents.

Если интересует интеграция с Rust‑проектами, стоит посмотреть Автономная разработка на Rust с помощью Claw-Code, где описаны подходы к построению знани‑графов в собственных приложениях.

В итоге, Graphify‑Labs/graphify предоставляет полноценный инструментарий как для одноразового построения графов микросервисов, так и для постоянного доступа к знанию о системе в реальном времени, что соответствует принципу предсказуемости и надёжности, который я ценю в своей работе.

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

Как Graphify обеспечивает конфиденциальность данных?

Он выполняет весь парсинг и генерацию графа на том же сервере, где находятся исходные файлы, используя локальный AST‑движок. Никакой сетевой трафик не генерируется, а все операции происходят в локальном контексте. Это гарантирует, что код, документация и схемы баз данных не покидают ваш хост.

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

Поддерживаются исходные коды (Python, Java, JavaScript, Go и др.), документации в форматах Markdown, reST и PDF, а также спецификации API (OpenAPI/Swagger) и схемы баз данных в SQL или ER‑диаграммах. additionally it accepts YAML‑описания и простые текстовые схемы. Инструмент автоматически определяет тип файла по расширению и преобразует его в AST.

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

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

Как просмотреть и экспортировать полученный граф?

После выполнения команды Graphify сохраняет результат в указанный файл, обычно в формате SVG, PNG или JSON. SVG‑файл открывается в любом современном браузере или в просмотрщике изображений, где можно интерактивно исследовать узлы и ребра. JSON‑экспорт содержит идентификаторы узлов и связи, что позволяет интегрировать граф в собственные визуализационные утилиты.