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

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

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

Основы Graphify-Labs/graphify

Локальный AST‑парсинг

Graphify‑Labs/graphify выполняет детерминированный парсинг абстрактного синтаксического дерева (AST) непосредственно на вашем же «домашнем сервере», без обращения к внешним векторным хранилищам. Это гарантирует одинаковый результат при повторных запусках и полностью исключает необходимость в облачных сервисах.

Пример парсинга Python‑файла:

bashКопировать
# парсим файл и сохраняем граф в формате DOT
graphify parse src/example.py --output example.dot

Полученный example.dot можно визуализировать любой граф‑редактором (Graphviz, Cytoscape и т.п.). Поскольку парсер работает локально, он полезен, когда требуется предсказуемость конфигураций и отсутствие зависимостей от сторонних API.

Для сравнения с другими подходами см. статью о локальных ИИ‑агентах и инструментах.

Поддержка кода

Graphify‑Labs/graphify умеет парсить широкий спектр языков: Python, JavaScript, TypeScript, Go, Rust, Java, C# и др. Каждый язык имеет собственный набор правил парсинга, но результат всегда единый AST‑объект, который затем превращается в граф.

Пример: парсим небольшой JavaScript‑фрагмент и получаем граф взаимосвязей импортов.

bashКопировать
graphify parse src/utils.js --output utils graph.png

Конфигурационный файл graphify.yaml позволяет задать пути к исходникам, шаблоны имён и параметры визуализации:

yamlКопировать
paths:
  - src/
  - docs/
output:
  format: png
  theme: dark

Информацию о работе с Rust‑проектами можно найти в статье Автономная разработка на Rust с помощью Claw-Code.

docs

Документационные файлы (Markdown, reStructuredText, AsciiDoc) тоже преобразуются в AST. Это удобно, когда нужно построить граф структуры документа: разделы, подпункты, ссылки и т.п.

Пример: создаём граф из README.md:

bashКопировать
graphify parse docs/README.md --output readme.dot

Полученный DOT‑файл можно сразу же передать в CI‑pipeline для автоматической проверки целостности документации.

Подробнее о работе с документами – в статье Оптимизация ИИ‑агентов с помощью системы ECC.

SQL и PDF

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

SQL‑пример: парсим файл с CREATE‑операциями:

bashКопировать
graphify parse sql/schema.sql --output schema.dot

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

PDF‑пример: извлекаем структуру технического документа:

bashКопировать
graphify parse docs/technical_guide.pdf --output guide.dot

Эта возможность позволяет быстро визуализировать hierarchy of sections, figure captions и ссылки внутри PDF‑файла.

Пример использования в реальном проекте – в статье Claw-code: автономный музейный экспонат на Rust, где показано, как парсить PDF‑описания экспонатов.

---

Если у вас остались вопросы – открывайте issue в репозитории Graphify‑Labs/graphify, где я, Алексей Кузнецов, с радостью помогу настроить парсинг под ваш конкретный случай.

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

### Claude Code

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

bashКопировать
# 1. Парсим проект и сохраняем граф в JSON
graphify parse ./src --output project.graph.json

# 2. Загружаем граф в Claude Code и получаем анализ
claude-code analyze --graph project.graph.json --prompt "Какие узлы отвечают за обработку ошибок и как их можно улучшить?"

Пример ответа

В узлах `ErrorHandler` и `ExceptionTracker` находятся функции, отвечающие за логирование исключений. Рекомендуется вынести их в отдельный модуль и добавить unit‑тесты с использованием mock‑объектов.

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

yamlКопировать
analysis:
  target: "ErrorHandler"
  prompt: "Какие узлы отвечают за обработку ошибок и как их можно улучшить?"

Ссылка на обзор возможностей локальных ИИ‑агентов: Локальные ИИ‑агенты и инструменты.

---

### Cursor

С практической точки зрения Cursor — интегрированная среда разработки с встроенным AI‑ассистентом — позволяет работать с Graphify‑графом без выхода из редактора. Граф можно импортировать как файл .graph и сразу задавать вопросы.

bashКопировать
# Экспортируем граф в формате, понятном Cursor
graphify export --format cursor ./src --output myproject.graph

Внутри Cursor открываем myproject.graph, выделяем интересующий узел и пишем запрос:

@cursor, объясни, как происходит построение дерева зависимостей в этом модуле.

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

---

### Codex

Если мы посмотрим на то, как Codex (API OpenAI) может использовать локальный граф, то увидим простой HTTP‑запрос. Graphify сохраняет граф в JSON, который легко отправляется в Codex для получения сгенерированного кода или комментариев.

bashКопировать
curl -X POST https://api.codex.example.com/v1/graph \
  -H "Authorization: Bearer $CODEX_TOKEN" \
  -H "Content-Type: application/json" \
  -d @project.graph.json \
  -d '{"request":"Сгенерировать unit‑тест для функции process_data"}'

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

---

### Gemini CLI

Gemini CLI — инструмент от Google, позволяющий выполнять запросы к Gemini Pro через командную строку. Он поддерживает чтение файлов JSON, что делает его совместимым с Graphify.

bashКопировать
# Передаём граф в Gemini CLI
gemini-cli analyze --file project.graph.json --question "Какие компоненты отвечают за кэширование данных?"

Вывод будет структурированным списком, удобным для дальнейшего анализа в скриптах.

---

### AI‑агентские workflows

В AI‑агентских workflows Graphify выступает в роли «знаничкового» источника, который агент может последовательно запрашивать. Пример типичного пайплайна:

bashКопировать
# 1. Получаем граф проекта
graphify parse ./app --output app.graph.json

# 2. Передаём его в агент, который ищет узлы с высокой нагрузкой
agent-query --graph app.graph.json --query "покажи узлы с максимальной глубиной вызова"

# 3. На основе результата генерируем оптимизацию
agent-suggest --graph app.graph.json --action "рефакторинг" --output refactor.yaml

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

См. также Оптимизация ИИ‑агентов с помощью системы ECC и affaan-m/ECC: AI Agent Harness Performance Optimization для более детального описания подхода.

Плюсы и ограничения

Детерминированный AST и объяснимость

Детерминированный парсинг гарантирует, что каждый запуск graphifyproduce одинаковый абстрактный синтаксический дерево (AST) для одного и того же файла. Это удобно, когда нужно сравнивать версии кода, автоматизировать ревью или интегрировать результаты в CI‑pipeline.

Пример получения AST для простого скрипта:

bashКопировать
graphify parse src/example.py --output ast.json

jsonКопировать
{
  "type": "File",
  "body": [
    {
      "type": "FunctionDeclaration",
      "id": { "type": "Identifier", "name": "add" },
      "params": [
        { "type": "Identifier", "name": "a" },
        { "type": "Identifier", "name": "b" }
      ],
      "body": {
        "type": "BlockStatement",
        "body": [
          {
            "type": "ReturnStatement",
            "argument": {
              "type": "BinaryExpression",
              "operator": "+",
              "left": { "type": "Identifier", "name": "a" },
              "right": { "type": "Identifier", "name": "b" }
            }
          }
        ]
      }
    }
  ]
}

Поскольку структура дерева фиксирована, её можно легко визуализировать, сравнивать или передавать в другие инструменты. Например, с помощью graphify show ast.json --node 3 вы получите детальное представление конкретного узла, что упрощает поиск места, где меняется логика.

Такой подход резонирует с практикой локальных ИИ‑агентов, о которых подробно рассказывается в Локальные ИИ‑агенты и инструменты. Детерминированность обеспечивает предсказуемость, а значит — более надёжную работу агентов, которые полагаются на стабильный AST для анализа кода.

---

Отсутствие векторного хранилища

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

Если требуется семантическая поисковая функциональность, её следует реализовывать отдельно, например, экспортируя граф в JSON и загружая его в внешнюю систему вектора (FAISS, Milvus и т.п.).

bashКопировать
graphify export ast.json --format json > graph.json
# дальше импортируем graph.json в выбранный векторный хранилище

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

В контексте автономных Rust‑решений, о которых написано в Claw-code: автономный музейный экспонат на Rust, отсутствие готового вектора подчёркивает, что Graphify оставляет пространство для интеграции с другими библиотеками, специализирующимися на семантическом представлении.

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

Практические сценарии развертывания

Docker‑контейнерный запуск

Graphify‑Labs/graphify поставляется в виде Docker‑образа, что упрощает развёртывание как на отдельном сервере, так и в домашней лаборатории. Образ построен на минимальном образе Alpine, поэтому требуемые ресурсы минимальны, а процесс запуска полностью детерминирован – без обращения к внешним хранилищу векторных представлений.

Для быстрого старта достаточно выполнить две команды:

bashКопировать
# скачивание последней версии образа
docker pull graphify/graphify:latest

# запуск контейнера
docker run -d \
  --name graphify \
  -v /home/alexey/projects:/data \
  -v /home/alexey/graphs:/output \
  graphify/graphify:latest \
  --input /data/example.py \
  --output /output/graph.svg

• --input – путь к файлу или каталогу с исходными данными (код, документ, схема БД, PDF).
• --output – куда будет записан результат (изображение графа, JSON‑описание и т.п.).

При монтировании каталогов важно использовать NFS‑share или локальный диск, размещённый на домашнем сервере, чтобы избежать лишних сетевых задержек. Если требуется обработка нескольких файлов, удобно задать общий скрипт‑обёртку, которая последовательно передаёт каждый путь в контейнер.

Для интеграции в CI/CD‑pipeline достаточно добавить эту команду в stage build, а результаты сохранять в артефактах. Подробнее о возможностях образе – в Локальные ИИ‑агенты и инструменты.

---

Развёртывание в домашней лаборатории (Proxmox, TrueNAS)

В домашней лаборатории, состоящей из кластера Proxmox и хранилища TrueNAS, Graphify удобно разворачивать как отдельный виртуальный сервер, так и как контейнер внутри существующей ВМ. Подходы отличаются по уровню изоляции и потреблению ресурсов, но оба позволяют сохранять детерминированность работы и полную локальность данных.

Развёртывание в Proxmox

1. Создание виртуальной машины – типичная конфигурация для Graphify (2 ЯДР, 4 ГБ RAM, диск 20 ГБ).

bashКопировать
# создаём VM с номером 101, используя образ Debian 12
qm create 101 --memory 4096 --cores 2 --net0 virtio,bridge=vmbr0,model=virtio_e
qm set 101 --scsi0 local-lvm:20G
qm set 101 --boot c --bootdisk scsi0
qm set 101 --ide2 local:iso/debian-12.0.0-amd64.iso
qm start 101

2. Подключение TrueNAS‑share – удобно монтировать NFS‑share с TrueNAS внутри ВМ.

bashКопировать
# в ВМ Debian монтируем NFS‑share
apt-get update && apt-get install -y nfs-common
mkdir -p /mnt/truenas
mount -t nfs 192.168.1.100/truenas/data /mnt/truenas

3. Установка Docker и запуск контейнера, как описано в предыдущем подразделе, но с путями, размещёнными на NFS‑share.

Развёртывание в TrueNAS (контейнер)

TrueNAS Scale поддерживает Docker‑контейнеры напрямую, что позволяет запустить Graphify без дополнительной ВМ.

bashКопировать
# в веб‑интерфейсе TrueNAS Scale → Apps → Add Container
docker run -d \
  --name graphify \
  -v /mnt/truenas/data:/data \
  -v /mnt/truenas/graphs:/output \
  graphify/graphify:latest \
  --input /data/**/*.py \
  --output /output/graph.json

• Параметр -v монтирует datasets TrueNAS как локальные каталоги, что обеспечивает высокую доступность и резервное копирование.
• Запуск в фоне (-d) позволяет освободить терминал для мониторинга логов через docker logs -f graphify.

Автоматизация и мониторинг

Для предсказуемости рекомендуется настроить systemd‑unit, который будет поднимать контейнер при загрузке системы. Пример unit‑файла:

iniКопировать
[Unit]
Description=Graphify local AST parser
After=network-online.target
Wants=network-online.target

[Service]
Restart=always
ExecStart=/usr/bin/docker run --rm \
  --name graphify \
  -v /mnt/truenas/data:/data \
  -v /mnt/truenas/graphs:/output \
  graphify/graphify:latest \
  --input /data/example.py \
  --output /output/graph.svg

[Install]
WantedBy=multi-user.target

После размещения файла в /etc/systemd/system/graphify.service выполнить:

bashКопировать
systemctl daemon-reload
systemctl enable --now graphify.service

Таким образом, Graphify будет доступен в любой момент, а его работа будет полностью локальной, без обращения к внешним сервисам.

---

Готово к использованию.