Graphify-Labs/graphify: локальный AST‑парсинг к знани‑графу
Turn codebase, docs, SQL schemas, configs into a queryable knowledge graph with Graphify‑Labs/graphify, local deterministic AST parsing, no vector store.
Основа Graphify-Labs/graphify
Основа Graphify-Labs/graphify
Локальный AST‑парсинг без векторного хранилища
Graphify‑Labs/graphify использует локальный, детерминированный парсер абстрактного синтаксического дерева (AST).
Парсинг происходит полностью на стороне клиента, поэтому не требуется подключение к внешнему векторному хранилищу и никаких зависимостей от сторонних сервисов.
Пример использования
bash# Парсить один Python‑файл и сохранить результат в JSON‑файл
graphify parse \
--input src/main.py \
--output graph.json \
--format json
yaml# graphify.yaml – минимальная конфигурация
version: 1
parser:
type: ast
deterministic: true
output:
format: json
path: ./graph.json
Во‑первых, парсер читает исходный файл, строит дерево узлов и сохраняет его в указанном формате.
С практической точки зрения это позволяет быстро проверять структуру кода без необходимости загружать его в облако.
Поддержка кода, документации, SQL‑схем, конфигов и PDF
Graphify‑Labs/graphify умеет импортировать разные типы артефактов, превращая их в узлы и ребра графа.
Код
bash# Парсить директорию с кодом и добавить результаты в существующий граф
graphify parse \
--input ./src \
--graph ./graph.json \
--mode merge
Документация (Markdown)
bash# Добавить все *.md‑файлы из docs/ в граф
graphify parse \
--input ./docs \
--graph ./graph.json \
--format markdown
SQL‑схемы
bash# Парсить файл схемы PostgreSQL и включить типы таблиц, колонки, ограничения
graphify parse \
--input ./schemas/public.sql \
--graph ./graph.json \
--format sql
Конфиги (YAML, TOML, INI)
bash# Парсить конфигурационный файл и вывести структуру
graphify parse \
--input ./config/app.yaml \
--graph ./graph.json \
--format yaml
bash# Преобразовать техническое руководство в граф (требуется OCR‑инструмент)
graphify parse \
--input ./docs/manual.pdf \
--graph ./graph.json \
--format pdf
Во‑первых, все указанные типы артефактов обрабатываются одним и тем же парсером, что гарантирует одинаковый уровень детализации.
С практической точки зрения это упрощает построение единой модели знаний из разнородных источников, без необходимости экспортировать данные в отдельные векторы.
Для более детального описания возможностей и примеров см. Использование DESIGN.md из awesome-design-md для генерации UI через AI‑агентов.
Также полезно ознакомиться с Настройка GStack: инструменты Claude Code от Гарри Тана и Оптимизация Claude Code через CLAUDE.md.
Подробнее о наборе инструментов для AI‑агентов можно найти в Набор навыков для AI‑агентов: разбор репозитория Skills.
Если требуется расширенная настройка GStack, см. Настройка GStack: набор инструментов Claude Code.
Навык /graphify для AI‑инструментов
Интеграция с Claude Code
Во-первых, установите graphify в среду, где запущен Claude Code. Обычно это делается через cargo или npm, в зависимости от выбранного дистрибутива.
bash# пример установки через cargo
cargo install graphify-cli
После установки создайте конфигурационный файл .graphify.yaml в корне репозитория. Пример:
yaml# .graphify.yaml
mode: local
parse:
enabled: true
include:
- *.py
- *.js
- *.toml
output:
format: dot
path: ./graph.dot
Справедливый способ использования – запустить команду graphify parse из терминала Claude Code. Это сгенерирует файл graph.dot, который можно дальше передать в визуализатор.
Настройка GStack: набор инструментов Claude Code описывает подробно, как подключить graphify к Claude Code в рамках GStack‑инструментов.
Интеграция с Cursor
Если вы работаете в Cursor, достаточно открыть терминал внутри редактора и выполнить ту же команду. Cursor автоматически подхватывает переменные окружения, поэтому достаточно указать путь к конфигу.
bashgraphify parse --config .graphify.yaml
Для удобства можно добавить alias в ~/.bashrc Cursor‑профиля:
bashalias gparse='graphify parse --config .graphify.yaml'
Такой подход обеспечивает предсказуемость: один и тот же скрипт работает и в локальном терминале, и в встроенном терминале Cursor.
Использование DESIGN.md из awesome-design-md для генерации UI через AI‑агентов показывает, как graphify может быть частью более широкой цепочки генерации интерфейсов.
Интеграция с Codex
В среде Codex (например, в VS Code с расширением) удобно вызывать graphify из скриптов, которые запускаются после коммита. Пример post‑commit хука:
bash#!/bin/sh
# .git/hooks/post-commit
graphify parse --config .graphify.yaml
После выполнения хука файл graph.dot будет обновлён, а при необходимости его можно сразу открыть в встроенном просмотрщике графики.
Интеграция с Gemini CLI
Gemini CLI принимает данные в формате DOT, поэтому после генерации графа можно передать его напрямую:
bashgraphify parse --config .graphify.yaml -o - | gemini-cli graph import
Эта команда читает DOT‑данные из стандартного ввода и импортирует их в граф, доступный через Gemini‑интерфейс.
Детерминированный разбор AST и объяснение каждой ребра
graphify использует локальный, детерминированный парсер AST, который не зависит от внешних векторных хранилищ. Это гарантирует, что один и тот же фрагмент кода всегда будет разобран одинаково.
Пример разбора функции на Python:
pythondef add(a: int, b: int) -> int:
return a + b
Запуск graphify parse над файлом, содержащим данный код,produces следующий DOT‑фрагмент:
dotdigraph AST { node [shape=box]; "def add(a: int, b: int) -> int": cluster_0 { label = "Function"; "add": node_0; "a": node_1; "b": node_2; "return": node_3; "a + b": node_4; } node_0 -> node_1; node_0 -> node_2; node_0 -> node_3; node_3 -> node_4; }
Каждое ребро в этом графе соответствует конкретному элементу синтаксиса:
def …→Function– указывает, что узел представляет функцию.add→aиb– входные параметры функции.return→a + b– тело функции, где происходит операция сложения.
Таким образом, каждый «узел» и «ребро» имеют чёткую семантику, что упрощает последующий анализ, например, поиск всех мест, где используется переменная a.
Если мы посмотрим на более сложный пример с вложенными конструкциями, видно, как graphify сохраняет порядок объявлений и типовых связей, что делает его пригодным для статического анализа в AI‑агентах.
Статья подготовлена Алексеем Кузнецовым.
Практические сценарии применения
Практические сценарии применения
Автоматический аудит кода и схем
Во-первых, Graphify‑Labs/graphify позволяет превратить любой набор файлов — исходный код, SQL‑схемы, конфигурационные файлы — в единый локальный граф. Это удобно для выявления структурных несоответствий без необходимости отдельного сканирования и без использования векторных хранилищ.
bash# базовый запуск CLI
graphify-cli -i /path/to/project -o graph.dot
yaml# пример конфигурации graphify.yaml
sources:
- type: code
paths:
- src/
- type: sql
files:
- db/schema.sql
- type: config
paths:
- config/
- type: markdown
paths:
- docs/
С помощью одной команды можно получить файл graph.dot, который затем можно визуализировать в любом графовом редаторе (Graphviz, Neo4j Browser и т.п.).
Для автоматического аудита удобно задать набор правил в отдельном YAML‑файле, например audit.yaml:
yamlrules:
- check: unused_columns
description: Найти столбцы в таблицах, которые не используются в коде
query: |
MATCH (t:Table)-[u:USES]->(c:Column)
WHERE NOT (c.name IN $used_columns)
RETURN t.name, c.name
- check: missing_docs
description: Выявить отсутствие комментариев в публичных функциях
query: |
MATCH (f:Function)
WHERE NOT (f.docstring)
RETURN f.name
Запуск аудита:
bashgraphify audit --config audit.yaml --graph graph.dot
Результат — список нарушений, который можно сразу включить в CI‑pipeline.
Если в проекте используется DESIGN.md из awesome‑design‑md, то Graphify может автоматически синхронизировать UI‑компоненты с их описанием в схеме, проверяя, что каждый компонент имеет соответствующий API‑endpoint, описанный в OpenAPI‑файле.
Поиск и запрос знаний в проектах
С практической точки зрения, знание того, где используется конкретная функция или как взаимосвязаны таблицы, экономит часы ручного поиска. Graphify‑Labs/graphify предоставляет простой CLI‑инструмент для поиска по графу.
bash# поиск по имени функции
graphify search --graph graph.dot --term "parseConfig"
bash# поиск по запросу в естественном виде
graphify query --graph graph.dot --natural "Which services depend on the legacy authentication module?"
Пример вывода:
Service: auth-service
- depends on: db-auth
- config: /etc/auth/config.yaml
Эти данные удобно использовать в Ansible‑playbooks для быстрой настройки зависимостей:
yaml# playbook snippet
- name: Ensure auth-service has correct DB dependency
ansible.builtin.command: "graphify query --graph graph.dot --term 'auth-service'"
register: auth_deps
ignore_errors: true
Далее, результаты можно передать в ansible.builtin.debug для визуализации:
yaml- debug:
var: "{{ auth_deps.stdout_lines }}"
Для более сложных запросов удобно писать небольшие скрипты на Python, использующие API Graphify (если он доступен), либо экспортировать граф в JSON и обрабатывать его стандартными инструментами.
Если вам нужно быстро собрать контекст для Claude Code, то настройка GStack позволяет подключить Graphify‑generated graph как дополнительный источник знаний, тем самым упрощая работу AI‑агентов при анализе кода.
Таким образом, Graphify‑Labs/graphify обеспечивает как автоматический аудит, так и удобный поиск внутри проекта, что делает его полезным инструментом для любой домашней лаборатории, где важна предсказуемость и документированность конфигураций.
Плюсы и ограничения
Преимущества локального deterministic подхода
Локальный deterministic подход — это когда парсер работает полностью на вашем сервере, берёт входные данные (код, конфиги, схемы) и выдаёт один и тот же результат при каждой обработке.
- Повторяемость. Если запустить
graphify parse --input src/ --output graph.jsonдважды, получим идентичныйgraph.json. Нет случайных отклонений, которые часто появляются в моделях с векторами. - Отсутствие внешних зависимостей. В отличие от решений, использующих vector store, здесь не требуется подключать сторонние сервисы, что упрощает развертывание в закрытых сетях.
- Прозрачность. Всё происходит в одном процессе, поэтому легче отследить, где именно «загорелось» при ошибке. Логи
journaldпоказывают точную строку кода, вызывающую сбой.
Пример конфигурации для парсинга нескольких файлов:
yaml# config.yaml
paths:
- src/
- docs/
- schemas/
output:
file: graph.json
format: json
Запуск:
bashgraphify parse --config config.yaml
- Контроль версии. Поскольку парсер фиксирован, можно легко проверить, что изменения в коде не «сломали» граф, просто сравнив хеши
graph.jsonперед и после изменения.
Сравнение с типичными решениями, где используется AI‑модель для генерации схем, показывает, что deterministic‑подход даёт предсказуемый результат, а не «потенциально меняющийся» вывод.
Для UI‑генерации на основе AST удобно использовать DESIGN.md из awesome‑design‑md — после получения графа его можно передать в агент, который уже знает, как превратить структуру в компоненты.
Ограничения по поддержке новых форматов
На сегодняшний день graphify поддерживает несколько «коренных» форматов:
- JavaScript/TypeScript (
.js,.ts) - JSON/YAML‑конфиги (
.json,.yaml,.yml) - SQL‑скрипты (
.sql) - Конфигурационные файлы Nginx, Caddy, HAProxy (
.conf)
Если в проекте появляется, например, файл .rs (Rust) или специфический DSL, парсер просто его не видит и игнорирует. Это значит, что для поддержки нового формата необходимо:
- Написать собственный парсер — класс, реализующий интерфейс
AstParser. - Регистрировать его в конфигурации (
parsers: [{type: "rust", entry: "rust_parser.py"}]). - Тестировать на наборе примеров, чтобы убедиться в детерминированности.
Пример добавления нового парсера (Rust):
python# rust_parser.py
from graphify.parsers import AstParser
class RustParser(AstParser):
def parse(self, file_path: str) -> dict:
import ast
with open(file_path, 'r', encoding='utf-8') as f:
tree = ast.parse(f.read())
# Простейший вывод — список функций
functions = [node.name for node in ast.walk(tree) if isinstance(node, ast.FunctionDef)]
return {"type": "rust", "functions": functions}
-
Зависимость от версии языка. Если меняется синтаксис (например, появляется новый оператор в Python 3.12), старый парсер может «сломаться». Поэтому важно держать парсеры в синхроне с официальными релизами.
-
Ограничения в вложенности. Поддерживаемые форматы обычно ограничены плоской структурой. Глубоко вложенные шаблоны (например, сложные YAML‑модели с динамическими ключами) требуют дополнительного анализа, который пока не реализован.
Для тех, кто хочет přzer expand список поддерживаемых форматов, стоит следить за набором навыков для AI‑агентов — там описаны подходы к написанию кастомных парсеров и их интеграции в CI/CD.
Таким образом, локальный deterministic подход обеспечивает надёжность и простоту, но требует ручной работы по поддержке новых форматов. Это компромисс, который оправдан, когда важна предсказуемость, а не скорость разработки.
Часто задаваемые вопросы
Как работает локальный AST‑парсер и почему он детерминированный?
Парсер читает исходный файл полностью на клиенте, строя дерево узлов из синтаксического анализатора, а затем сохраняет его в выбранный формат (JSON, YAML, markdown и т.п.). Поскольку все операции выполняются локально и не зависят от внешних сервисов, результат одинаковый при повторных запусках при тех же входных данных – это и есть детерминированность. Такой подход исключает любые случайные изменения, связанные с сетью или удалёнными вычислительными ресурсами.
Требуется ли подключение к внешнему векторному хранилищу для работы Graphify‑Labs/graphify?
Нет, парсер и весь процесс построения графа происходят полностью офлайн. Утилита не использует ни векторные базы, ни облачные API, поэтому её можно запускать в любой среде без необходимости регистрировать аккаунты или управлять зависимостями от сторонних сервисов.
Какие типы файлов поддерживает утилита для импорта в граф?
Поддерживаются Python‑скрипты, директории с кодом, Markdown‑документация, SQL‑схемы (PostgreSQL, MySQL и др.), конфигурационные файлы в форматах YAML, TOML, INI, а также PDF‑документы (через OCR‑парсинг). Каждый тип обрабатывается отдельным подмодулем, который формирует узлы и ребра, соответствующие структуре исходного артефакта.
Как добавить новые файлы в уже существующий граф без потери данных?
Для этого используйте параметр --mode merge в команде graphify parse. При указании существующего файла графа (--graph) утилита загружает его, объединяет новые узлы и ребра с уже существующими и сохраняет результат обратно в указанный путь. Это гарантирует сохранность предыдущей модели и позволяет постепенно расширять знание о коде и документах.
В каком формате можно сохранить полученный результат парсинга?
Результат может быть записан в JSON, YAML, markdown или в текстовый формат, определяемый флагом --format. Выбирая нужный формат, вы получаете файл, который легко импортировать в другие инструменты (например, графовые визуализаторы) или использовать в дальнейшем для запросов к знани‑графу.