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}!"
Команда парсинга выглядит так:
bashgraphify parse --input utils.py --output graph.db
После выполнения в graph.db появляется структура, где узлом является функция greet, а ребром — её сигнатура и возвращаемое значение. Аналогично парсится YAML‑конфиг:
yaml# config.yaml
database:
host: localhost
port: 5432
user: admin
bashgraphify parse --input config.yaml --output graph.db
В результате в графе появляются узлы database, host, port, user и ребра, связывающие их.
Ссылка на более детальное описание локального AST‑парсинга: Graphify-Labs/graphify: локальный AST‑парсинг к знани‑графу.
Если интересует практический опыт использования в реальном проекте, см. Навыки реальных инженеров: практические практики из .agents.
Зачем это нужно для разработки и анализа
С практической точки зрения граф‑представление кода и документации ускоряет несколько типовых задач разработки.
-
Поиск зависимостей — можно быстро ответить на вопрос «где используется функция
authenticate». Пример запроса:bashgraphify query "SELECT * FROM functions WHERE name='authenticate'" graph.dbРезультат покажет все файлы и сервисы, где эта функция участвует, без необходимости manually grep‑ом по проекту.
-
Влияние изменений — при рефакторинге удобно построить «карту» всех узлов, зависящих от изменяемого модуля. Запустив
graphify diff --old graph_old.db --new graph_new.dbи визуализировав разницу, видно, какие части кода перестанут компилироваться. -
Документация «из кода» — граф автоматически генерирует таблицу функций, схем баз данных и конфигураций, что позволяет генерировать HTML‑отчёт в один клик:
bashgraphify 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
- Лексический анализ – разбивает файл на токены, используя грамму языка.
- Синтаксический разбор – строит дерево AST, где каждый узел соответствует конкретному элементу кода (функция, импорт, объявление переменной).
- Трансформация в граф – каждый узел 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:
bashdot -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‑интерфейс):
bashgraphify 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‑режим и периодически валидировать полученный граф через встроенные проверочные скрипты.