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

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

Turn any codebase, docs, SQL schemas, configs and PDFs into a queryable knowledge graph with /graphify skill for Claude Code, Cursor, Codex and Gemini CLI.

Что такое Graphify-Labs/graphify

Что такое Graphify-Labs/graphify

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

Определение знаний‑графа

Я, Алексей Кузнецов, считаю, что знание — граф — это набор узлов, описывающих сущности (классы, функции, переменные, таблицы), и ребр — показывающих их связи (импорт, вызов, ссылка). Пример ниже показывает, как Graphify‑Labs/graphify превращает простой Python‑модуль в граф.

bashКопировать
# парсим директорию src и генерируем DOT‑файл
graphify --input src/ --format dot > graph.dot

Файл graph.dot выглядит так:

dotКопировать
digraph G {
    "module:utils.helpers" -> "function:parse_config" [label="calls"];
    "class:Config" -> "field:db_host" [label="has"];
    "table:users" -> "column:id" [label="contains"];
}

Запрос к графу выглядит так:

bashКопировать
graphify query "SELECT * FROM nodes WHERE type='function' AND name LIKE '%parse%'" --output json

Эта возможность делает поиск предсказуемым и быстрым, как в реальном инженерном стеке, где каждый вызов функции — это ребро, которое можно отследить без лишних поисков.

Подробнее о локальных ИИ-агентах и инструментах

Поддерживаемые форматы

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

bashКопировать
# Python‑проект
graphify --lang python --input ./my_project/

# JavaScript‑модуль
graphify --lang javascript --input ./src/

# SQL‑схема
graphify --lang sql --input ./schema.sql

# YAML‑конфиг
graphify --lang yaml --input ./config.yaml

# PDF‑документ
graphify --input ./docs/manual.pdf

Конфигурационный файл graphify.yaml выглядит так:

yamlКопировать
input:
  - path: ./src/
    lang: python
  - path: ./schema.sql
    lang: sql
output:
  format: dot
  file: graph.dot

Здесь я использую возможности CLI, а не GUI, потому что «GUI для тех, кто не знает, где лежит конфиг». Такой подход гарантирует предсказуемость: каждый запуск читает один и тот же файл, а не скрытые настройки в графическом интерфейсе.

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

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

Локальный AST‑парсинг без векторного хранилища

Локальный AST-парсинг без векторного хранилища

Когда мы говорим об анализе больших кодовых баз с помощью ИИ, стандартный путь — это создание векторного хранилища (RAG). Мы нарезаем код на куски, превращаем их в эмбеддинги и ищем похожие фрагменты. Но у этого подхода есть фундаментальная проблема: семантическая близость векторов не гарантирует структурную точность. Вектор может найти функцию, которая «похожа» по смыслу, но пропустит вызов этой функции в другом файле, потому что связь между ними — это не сходство слов, а логическая структура программы.

Инструмент graphify предлагает другой подход. Вместо того чтобы полагаться на вероятности, он использует абстрактное синтаксическое дерево (AST). Это позволяет превратить код, SQL-схемы или даже PDF-документы в граф знаний, где узлы — это сущности, а ребра — жесткие логические связи.

С практической точки зрения это означает, что мы уходим от «угадывания» контекста к его точному извлечению. Для локальных ИИ-агентов и инструментов это критически важно: агент получает не просто случайный кусок текста, а понимание того, как один компонент системы влияет на другой.

Детерминированный разбор кода

Главное преимущество использования AST перед векторным поиском — предсказуемость. Векторный поиск вероятностен по своей природе. AST же детерминирован: если в коде есть вызов метода, парсер зафиксирует это как связь, независимо от того, насколько «похож» текст вызова на текст определения.

Graphify работает как прослойка между вашим кодом и LLM (например, через Claude Code или Gemini CLI). Он анализирует синтаксис и строит карту зависимостей. Если вы используете автономную разработку на Rust с помощью Claw-Code, вы понимаете, насколько важна точность типов и владения. AST-парсинг позволяет передать агенту не весь файл, а именно ту цепочку вызовов, которая необходима для решения задачи.

Чтобы начать работу с инструментом, достаточно установить его и запустить процесс построения графа для вашей директории. Например, для анализа проекта на Python:

bashКопировать
# Установка инструмента (примерный порядок действий)
pip install graphify

# Генерация графа знаний для текущей директории
graphify build ./my_project --output graph.json

В результате вы получаете структурированный файл, который описывает топологию вашего проекта. Это гораздо эффективнее, чем пытаться «скормить» агенту сотни файлов в надежде, что его контекстное окно вместит всё важное.

Объяснение каждого ребра

В графе знаний, который строит Graphify, связь (ребро) между узлами — это не просто линия, а конкретный тип взаимодействия. В векторном поиске связь — это «расстояние» между точками. Здесь же каждое ребро несет информацию: «вызывает», «наследует», «содержит» или «импортирует».

Если мы посмотрим на структуру графа, то увидим, что каждое ребро имеет свои атрибуты. Это позволяет ИИ-агенту не просто находить файлы, а проводить глубокий анализ. Например, при запросе «где используется эта переменная?», агент не ищет совпадения строк, а проходит по ребрам графа, которые указывают на области видимости и зависимости.

Для повышения производительности таких систем можно использовать методы оптимизации ИИ-агентов с помощью системы ECC, что особенно актуально при работе с тяжелыми графами.

Пример того, как может выглядеть логическая связь в JSON-представлении графа:

jsonКопировать
{
  "node": "UserService.createUser",
  "type": "function",
  "edges": [
    {
      "target": "Database.execute",
      "relation": "calls", // Ребро типа "вызывает"
      "metadata": {
        "line": 42,
        "file": "services/user_service.py"
      }
    },
    {
      "target": "UserSchema",
      "relation": "uses", // Ребро типа "использует"
      "metadata": {
        "line": 15
      }
    }
  ]
}

Такая точность превращает работу агента из «угадывания по тексту» в «навигацию по структуре». Это делает процесс разработки более контролируемым, а результаты работы ИИ — проверяемыми. Если агент утверждает, что функция A вызывает функцию B, вы можете мгновенно проверить это по ребру в графе, а не верить на слово результатам векторного поиска.

Интеграция с Claude Code, Cursor, Codex, Gemini CLI

Интеграция с Claude Code, Cursor, Codex и Gemini CLI

Когда мы говорим об использовании локальных ИИ-агентов и инструментов, основная проблема часто упирается в контекстное окно. Даже самые продвинутые модели начинают «галлюцинировать» или терять нить повествования, когда им приходится переваривать огромные репозитории целиком. Graphify решает это через создание графа знаний на основе AST (абстрактного синтаксического дерева). Вместо того чтобы скармливать агенту сырой текст, мы даём ему структурированную карту связей.

Для работы с инструментами вроде Claude Code или Cursor, Graphify выступает в роли «умного индексатора», который позволяет агенту делать точечные запросы к архитектуре кода.

Установка и конфигурация

Поскольку Graphify ориентирован на локальную работу, процесс установки не требует развёртывания тяжёлых облачных сервисов. Если вы привыкли к предсказуемости систем на базе Docker, вам будет проще всего использовать контейнеризированный вариант, чтобы не засорять основную систему зависимостями для парсинга.

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

yamlКопировать
# config.yaml
indexing:
  include_extensions:
    - .py
    - .go
    - .rs
    - .sql
  exclude_dirs:
    - node_modules
    - target
    - .git
graph_storage:
  type: local
  path: ./graph_data

Для установки через пакетный менеджер (если вы используете среду, где это предусмотрено разработчиком Graphify-Labs) или через прямой запуск, выполните:

bashКопировать
# Установка CLI-утилиты
pip install graphify-cli

# Инициализация графа для текущего проекта
graphify init --config config.yaml

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

Примеры запросов

Главная ценность интеграции — это возможность задавать вопросы не «по тексту», а «по структуре». Когда вы работаете в Cursor или через Gemini CLI, вы можете использовать навыки (skills) Graphify для получения точных ответов.

С практической точки зрения, вместо того чтобы просить ИИ «найди, где используется эта функция», вы используете семантический запрос к графу.

Пример 1: Анализ зависимостей в Python-проекте Если вам нужно понять, как изменение в одном модуле повлияет на систему, запрос может выглядеть так:

bashКопировать
# Запрос через CLI для получения графа зависимостей конкретного класса
graphify query "Show all downstream dependencies of class UserSession in auth_module.py"

Пример 2: Работа с SQL-схемами и кодом Graphify умеет связывать документацию или схемы БД с реальным кодом. Это полезно, если вы занимаетесь автономной разработкой на Rust, где типизация и структура данных играют ключевую роль.

bashКопировать
# Поиск соответствия между SQL-таблицей и сущностями в коде
graphify query "Map table 'orders' from schema.sql to all corresponding structs in the codebase"

Пример 3: Интеграция в рабочий процесс агента В рамках использования системы ECC для оптимизации агентов, Graphify позволяет минимизировать количество лишних токенов. Вместо передачи всего файла, агент вызывает инструмент:

1. Агент получает задачу: «Исправь утечку памяти в обработчике запросов».
2. Агент вызывает graphify skill для поиска всех узлов, связанных с RequestLifecycle.
3. Получает компактный граф связей.
4. Выполняет анализ только нужных участков кода.

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

Практические сценарии и преимущества

Практические сценарии и преимущества

Когда мы говорим об использовании локальных ИИ-агентов и инструментов, основная проблема часто упирается не в качество ответов модели, а в контекст. Даже самая мощная LLM начинает галлюцинировать, если ей «скормить» слишком много разрозненных файлов без понимания их структуры. Graphify решает эту задачу через построение графа знаний на основе AST (Abstract Syntax Tree). Вместо того чтобы просто искать похожие куски текста, инструмент понимает иерархию: где объявляется класс, как функции связаны через вызовы и как конфиги влияют на логику приложения.

Поиск в коде и документах

Обычный поиск по ключевым словам (grep) или семантический поиск (RAG на эмбеддингах) часто пасуют перед сложными связями. Например, если вам нужно найти все места, где используется специфический тип данных в связке с определённым SQL-схемой, обычный поиск выдаст сотни нерелевантных строк.

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

Для интеграции в рабочий процесс (например, через Claude Code или Cursor) достаточно инициализировать парсинг проекта. Если вы используете CLI, процесс выглядит примерно так:

bashКопировать
# Инициализация построения графа для текущей директории
graphify build ./my-project --output ./graph-data

После того как граф построен, вы можете использовать его в связке с вашим ИИ-агентом. Это особенно полезно, когда проект разрастается и вы начинаете терять предсказуемость при внесении изменений. Вместо того чтобы вручную сканировать файлы, вы делегируете анализ графу, который «видит» проект целиком, включая PDF-документацию и конфигурационные файлы.

Автоматизация аудита и рефакторинга

В задачах рефакторинга критически важно понимать область влияния (blast radius) изменений. Если вы решите изменить структуру базы данных или переписать центральный модуль, Graphify поможет визуализировать цепочку зависимостей.

С точки зрения системного инженера, это инструмент для обеспечения чистоты архитектуры. Вы можете автоматизировать аудит на предмет нарушения инкапсуляции или поиска «мертвого» кода. Например, можно составить запрос к графу, чтобы найти функции, которые объявлены, но не вызываются ни в одном из модулей системы.

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

Пример логики проверки через агент, использующий Graphify:

yamlКопировать
# Пример концептуального сценария для агента (pseudo-config)
task: "Audit dependency chain"
scope:
  - "src/**/*.rs"
  - "configs/*.yaml"
  - "docs/*.pdf"
query: "Find all modules that directly or indirectly depend on 'DatabaseConnector' and list their potential breaking points"

Такой подход позволяет не просто «чинить» код, а проводить глубокий анализ. Это близко к идее оптимизации ИИ-агентов, где эффективность работы инструмента напрямую зависит от качества предоставляемого ему контекста. Использование графа вместо сырого текста — это и есть переход от «угадывания» к инженерному подходу.

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

Как инструмент обеспечивает безопасность данных при парсинге?

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

Можно ли использовать Graphify для анализа конфигурационных файлов?

Да, инструмент поддерживает парсинг не только программного кода, но и схем баз данных, конфигураций и даже PDF-документов. Это позволяет объединить разрозненные данные — например, связи между SQL-схемами и логикой приложения — в единый предсказуемый граф знаний.

В чём преимущество использования графа перед обычным поиском по тексту?

Обычный поиск (grep) находит только совпадения строк, в то время как граф учитывает семантические связи между сущностями. С практической точки зрения это позволяет отследить цепочку вызовов или зависимости между классами, даже если их имена не дублируются в тексте.

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

Инструмент позволяет экспортировать результат в различных форматах, включая DOT-файлы для визуализации графов и JSON для дальнейшей программной обработки. Выбор формата зависит от того, планируете ли вы изучать связи визуально или интегрировать данные в свой автоматизированный пайплайн.