Продвинутый

Graphify-Labs/graphify: Turn codebase into queryable graph

Алексей Кузнецов
Алексей Кузнецов
Системный администратор31 октября 2026 г.10 мин чтения

Graphify-Labs/graphify turns codebase, docs, SQL schemas, configs, and PDFs into a queryable knowledge graph using deterministic parsing, no vector store.

Graphify-Labs/graphify: Turn codebase into queryable graph

Graphify-Labs/graphify turns codebase, docs, SQL schemas, configs, and PDFs into a queryable knowledge graph using deterministic parsing, no vector store.

Общая концепция и задачи

Превращение кода и документов в граф

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

Для примера возьмём небольшой Python‑модуль utils.py:

python
# utils.py
def greet(name: str) -> str:
    return f"Hello, {name}!"

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

bash
graphify parse --input utils.py --output graph.db

После выполнения в graph.db появляется структура, где узлом является функция greet, а ребром — её сигнатура и возвращаемое значение. Аналогично парсится YAML‑конфиг:

yaml
# config.yaml
database:
  host: localhost
  port: 5432
  user: admin
bash
graphify parse --input config.yaml --output graph.db

В результате в графе появляются узлы database, host, port, user и ребра, связывающие их.

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

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


Зачем это нужно для разработки и анализа

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

  • Поиск зависимостей — можно быстро ответить на вопрос «где используется функция authenticate». Пример запроса:

    bash
    graphify query "SELECT * FROM functions WHERE name='authenticate'" graph.db
    

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

  • Влияние изменений — при рефакторинге удобно построить «карту» всех узлов, зависящих от изменяемого модуля. Запустив graphify diff --old graph_old.db --new graph_new.db и визуализировав разницу, видно, какие части кода перестанут компилироваться.

  • Документация «из кода» — граф автоматически генерирует таблицу функций, схем баз данных и конфигураций, что позволяет генерировать HTML‑отчёт в один клик:

    bash
    graphify docs --input graph.db --output docs/
    
  • Анализ нагрузки и «горячих» точек — благодаря связям в графе можно построить матрицу вызовов и определить, где находятся узкие места в исполнении запросов к базе, что особенно полезно при оптимизации SQL‑схем.

Во-вторых, такой подход упрощает onboarding новых инженеров: вместо того чтобы изучать множество файлов, они могут «пройтись» по графу и увидеть, как всё связано.

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

Таким образом, deterministic‑парсинговый граф — это инструмент, который превращает разрозненные артефакты в единую, предсказуемую структуру, облегчая поиск, анализ и документирование кода.

Локальное детерминированное AST‑парсинг

### Как работает парсинг без векторного хранилища

График строится полностью deterministically: исходный код читается, токенизируется, а затем парсится с помощью фиксированных грамм. Векторное хранилище не участвует – все узлы и ребра формируются из синтаксических деревьев (AST) и метаданных файлов.

bash
# Пример запуска локального парсера
graphify parse \
  --config parser.yaml \
  --input ./src/ \
  --output ./graph.json
yaml
# parser.yaml – минимальная конфигурация
parser:
  language: python
  entry_point: graphify.entry
output:
  format: json
  path: ./graph.json
  1. Лексический анализ – разбивает файл на токены, используя грамму языка.
  2. Синтаксический разбор – строит дерево AST, где каждый узел соответствует конкретному элементу кода (функция, импорт, объявление переменной).
  3. Трансформация в граф – каждый узел AST преобразуется в вершину графа, а связи между узлами (например, import, call, uses) формируют ребра.

Поскольку правила парсинга фиксированы, одинаковый набор файлов всегдаproduce одинаковый граф, что упрощает отладку и воспроизводимость.

Пример – простое Python‑функциональное дерево:

json
{
  "node_id": "func_foo",
  "type": "function",
  "name": "foo",
  "params": ["x"],
  "body": [
    {"type": "return", "value": "x + 1"}
  ]
}

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

Навыки реальных инженеров: практические практики из .agents — описывает, как детерминированный подход помогает поддерживать стабильные конфигурации в продакшене.
Graphify-Labs/graphify: локальный AST‑парсинг к знани‑графу — подробно рассматривает процесс построения графа без внешних хранилищ.

Преимущества детерминированности и объяснения рёбер

Детерминированность обеспечивает предсказуемость: каждый запуск парсера даёт одинаковый набор вершин и рёбер, что упрощает тестирование и CI‑pipeline.

  • Повторяемость – одинаковый код в разных окружениях (локальном сервере, Docker‑контейнере, CI) генерирует идентичный граф, без «случайных» различий.
  • Отладка – если в графе обнаружена ошибка, её можно локализовать, проанализировав конкретные узлы AST, а не «чёрный ящик»‑векторный модель.
  • Объяснение рёбер – каждое ребро содержит явно прописанную метку, описывающую связь (например, imports, calls, uses). Это делает граф самодокументируемым.
json
{
  "source": "def process(data):",
  "target": "json.dumps(data)",
  "type": "calls",
  "description": "Функция process вызывает json.dumps для сериализации данных"
}

Эти метаданные позволяют быстро понять, почему узел A связан с узлом B, без необходимости делать дополнительный анализ similarity‑search’ом.

Практический пример: в кластере из трёх Proxmox‑нод, где каждый сервис описан в YAML‑конфигурациях, парсер выделяет ребро depends_on между сервисами. При изменении зависимости в одном из файлов граф сразу меняется, и алерт в Grafana (подключённый к Prometheus) срабатывает, потому что структура графа уже известна заранее.

Таким образом, детерминированный локальный AST‑парсинг обеспечивает прозрачность, надёжность и простоту поддержки – ключевые свойства для инженера, который строит инфраструктуру, где предсказуемость важнее любой «магической»black‑box‑технологии.

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

Интеграция с Claude Code и Cursor

Claude Code exposes a simple CLI that can be called from any terminal.
Для запуска Graphify достаточно передать путь к проекту и указать файл‑конфиг, если он есть.

bash
# пример вызова из Claude Code
graphify --project /path/to/my/project --config .graphify.yaml

.graphify.yaml – минимальный конфиг, где задаются директории, которые следует парсить, и параметры вывода:

yaml
# .graphify.yaml
project_root: "/path/to/my/project"
output: "graph.dot"
exclude:
  - "node_modules"
  - "*.log"

В Cursor можно добавить alias в settings.json, чтобы запуск был ещё короче:

json
// .cursor/settings.json
{
  "terminal": {
    "aliases": {
      "graphify": "graphify --project ${CURSOR_WORKDIR} --config .graphify.yaml"
    }
  }
}

После выполнения команды в текущем каталоге появится файл graph.dot, который можно визуализировать через Graphviz:

bash
dot -Tpng graph.dot -o graph.png

Навыки реальных инженеров: практические практики из .agents описывают, как такие alias‑ы уменьшают количество контекстных переключений и повышают предсказуемость процесса.


Использование в Codex и Gemini CLI

В Codex (интеграция с GitHub) Graphify удобно запускать как часть pre‑commit хука.
Скрипт‑хук проверяет изменённые файлы, а затем формирует граф только для новых/изменённых путей.

bash
#!/usr/bin/env bash
# .git/hooks/pre-commit
changed_files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(py|js|toml|yaml)$')
if [ -z "$changed_files" ]; then
  exit 0
fi

# формируем временный конфиг, указывающий только на изменённые директории
tmp_cfg=$(mktemp)
cat > "$tmp_cfg" <<EOF
project_root: "/repo"
output: "graph-commit.dot"
exclude:
  - "node_modules"
EOF

for f in $changed_files; do
  dir=$(dirname "$f")
  echo "$dir" >> "$tmp_cfg"
done

graphify --config "$tmp_cfg"
dot -Tpng graph-commit.dot -o graph-commit.png
rm "$tmp_cfg"

Gemini CLI (инструмент для локального взаимодействия с моделями) поддерживает передачу stdin в Graphify, что позволяет «на лету» получать граф из вывода любой команды. Пример:

bash
# передаём дерево файлов в Graphify через stdin
find . -type f -name "*.py" | graphify --project - --config - <<'EOF'
project_root: "/dev/stdin"
output: "stdin_graph.dot"
exclude:
  - "tests"
EOF

В результате появляется stdin_graph.dot, который можно сразу визуализировать или отправить в чат для обсуждения.

Simantic: симуляция прошивок для AI‑агентов показывает, как подобные пайплайны интегрируются в более крупные автоматизированные процессы, а Автономная разработка на Rust с помощью Claw-Code демонстрирует, как Graphify может быть частью CI/CD‑цикла в Rust‑проектах.

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

Анализ SQL‑схем и конфигураций

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

bash
# Пример: парсинг SQL‑скрипта и экспорт в JSON‑граф
graphify parse \
    --input ./schemas/create_schema.sql \
    --output ./graphs/db_graph.json \
    --format json
yaml
# Пример конфигурационного файла, который также может быть проанализирован
database:
  host: "localhost"
  port: 5432
  name: "analytics"
  user: "etl_user"
  password: "s3cr3t"
bash
# Парсинг YAML‑конфигурации
graphify parse \
    --input ./configs/app_config.yaml \
    --output ./graphs/config_graph.json \
    --format json

Справочный пример запроса к полученному графу (используется встроенный CLI‑интерфейс):

bash
graphify query \
    --graph ./graphs/db_graph.json \
    --query "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"

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

Навыки реальных инженеров: практические практики из .agents — в этой статье описаны типичные workflow‑ы, где Graphify применяется для быстрого аудита схем.


Обход PDF‑документов и технической документации

Техническая документация часто поставляется в PDF‑формате: руководства по установке, описания API, спецификации архитектур. Текст из PDF‑файлов можно превратить в обычный plain‑text (например, с помощью pdftotext), а затем передать в Graphify для построения графа. Это особенно полезно, когда нужно найти взаимосвязи между описанием параметров и реальными реализационными деталями.

bash
# Преобразование PDF в текст и последующий парсинг
pdftotext -layout manual.pdf - | \
graphify parse \
    --input - \
    --output ./graphs/manual_graph.json \
    --format json
bash
# Пример запроса: найти все упоминания «webhook» в документе
graphify query \
    --graph ./graphs/manual_graph.json \
    --query "SELECT * FROM nodes WHERE text CONTAINS \"webhook\""

В результате получаем структурированный граф, где каждый узел — это фрагмент текста, а ребра — ссылки на связанные понятия (например, «webhook» ↔ «REST‑API» ↔ «конечный пункт»). Такой подход позволяет быстро построить карту знаний без ручного сканирования страниц.

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


Краткое резюме

  • Для анализа SQL‑схем и конфигураций используйте graphify parse с указанием входного файла и желаемого формата вывода, а затем применяйте graphify query для поиска нужных связей.
  • Для обхода PDF‑документов предварительно конвертируйте их в текст, а затем передайте в Graphify – результат будет детерминированным графом, который можно исследовать через простые запросы.

Эти сценарии демонстрируют, как Graphify‑Labs/graphify превращает разрозненные текстовые artefacts в единую, queryable knowledge graph, устраняя необходимость в vector‑store и упрощая процесс аудита и поиска информации.

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

Как Graphify‑Labs/graphify отличается от подходов, использующих векторные хранилища?

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

Какие типы артефактов поддерживает Graphify и как они парсятся?

Поддерживаются исходный код (Python, Java, Go, Rust и др.), конфигурационные файлы (YAML, JSON, TOML, XML), SQL‑схемы, PDF‑документы и любые другие текстовые artefacts. Парсинг выполняется через deterministic‑парсер, который строит локальный AST, а затем трансформирует его в графовый модель, где каждый узел — сущность (функция, переменная, параметр, таблица и т.п.), а ребра — связи между ними (вызов, ссылка, параметр).

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

Запрос задаётся через CLI‑утилиту graphify query, например: graphify query --graph graph.db --query "SELECT * FROM functions WHERE name = 'authenticate'". После выполнения вы получаете набор узлов и ребер, описывающих все места, где используется функция authenticate. Запросы позволяют искать зависимости, вызовы, конфигурационные параметры, а также строить визуализацию графа для анализа сложных связей.

Какие ограничения имеет Graphify и как обеспечить надёжность парсинга?

Граф генерируется только из статического, предсказуемого кода; динамически создаваемый код (eval, импорт‑по‑runtime) может быть пропущен парсером. Поддержка синтаксисов ограничена тем, что реализованы в правилах парсинга – новые языки или специфичные паттерны требуют добавления соответствующих правил. Чтобы обеспечить надёжность, рекомендуется проверять входные файлы на корректность, использовать deterministic‑режим и периодически валидировать полученный граф через встроенные проверочные скрипты.

Поделиться:TelegramX / TwitterVK

Читайте также