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

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

Что такое Graphify и зачем нужен локальный AST‑граф

Когда мы говорим об анализе больших кодовых баз или сложных наборов документации с помощью ИИ, стандартный подход через RAG (Retrieval-Augmented Generation) часто даёт сбои. Проблема в том, что векторные хранилища работают с «семантической близостью» — они понимают, что слова похожи по смыслу, но совершенно не понимают структуру кода. Если вы спросите векторную базу о том, как функция calculate_total взаимодействует с объектом Order, она может найти похожие фрагменты текста, но не сможет точно проследить логическую связь.

Graphify решает эту задачу иначе. Вместо того чтобы просто нарезать текст на куски и превращать их в векторы, инструмент строит графы знаний на основе AST (Abstract Syntax Tree — абстрактного синтаксического дерева). Это позволяет превратить разрозненные файлы в единую, структурно связную карту.

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

Главное отличие Graphify от привычных RAG-систем — отказ от обязательного использования векторных БД в пользу локального графового представления. В классических схемах данные проходят через процесс эмбеддинга, сохраняются в базу, а затем ищутся по косинусному сходству. Это удобно, но это «черный ящик»: вы не знаете точно, почему модель выбрала именно этот кусок текста.

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

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

Для начала работы с инструментом достаточно развернуть его локально. Если вы используете Docker, процесс выглядит стандартно:

bash
# Запуск Graphify в контейнере для локального анализа
docker run -v $(pwd)/my_project:/app/project graphify-labs/graphify:latest analyze /app/project

Поддержка кода, docs, SQL и PDF

Универсальность Graphify заключается в том, что он не ограничивается только исходным кодом. Он работает с разными типами данных, приводя их к единому графовому формату.

Программный код. Это основная специализация. Инструмент понимает иерархию вызовов и зависимости, что критически важно для таких задач, как автономная разработка на Rust с помощью Claw-Code.
SQL-схемы. Вместо того чтобы пытаться «угадать» связи между таблицами через текстовый поиск, Graphify строит граф зависимостей на основе внешних ключей (Foreign Keys) и определений таблиц. Это позволяет ИИ-агенту понимать структуру базы данных на уровне схемы, а не просто по названиям колонок.
Документация и PDF. Текстовые файлы и PDF-документы проходят через процесс извлечения сущностей. Это позволяет связать техническое описание (например, в Markdown) с реальным кодом.

Если вы занимаетесь оптимизацией ИИ-агентов с помощью системы ECC, наличие такого структурированного контекста позволяет значительно снизить количество галлюцинаций. Агент получает не «облако слов», а четкую карту знаний.

Пример конфигурации для анализа смешанного проекта (код + документация):

yaml
# config.yaml
input_paths:
  - "./src"          # Исходный код
  - "./docs"         # Markdown документация
  - "./schema.sql"   # Структура БД
parsing_strategy:
  ast_depth: 3       # Глубина анализа дерева
  include_comments: true
output:
  format: "graphml"  # Формат графа для последующего использования

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

Как работает skill /graphify в Claude Code, Cursor, Codex, Gemini CLI

Как работает skill /graphify в Claude Code, Cursor, Codex, Gemini CLI

Локальная deterministic AST‑анализ

Graphify /Local AST‑parser работает полностью офлайн: он берёт исходный код, документацию, схемы SQL или PDF‑файлы, парсит их с помощью встроенного парсера абстрактного синтаксического дерева и формирует локальный граф‑знание. Поскольку парсинг детерминирован, один и тот же файл всегда даёт одинаковый набор узлов и ребер, что удобно для отладки и воспроизводимых исследований.

Для запуска в любой из перечисленных CLI‑утилит достаточно указать путь к файлу (или каталогу) и параметр вывода. Пример для Claude Code:

bash
# Парсим весь проект в текущей директории и сохраняем граф в формате DOT
graphify --input . --output project.dot --format dot

В Cursor и Codex параметры передаются через флаги --source и --output соответственно:

bash
graphify --source ./src --output ./graph.dot

Если требуется уточнить тип анализируемого artefacts, используйте конфигурационный файл .graphify.yml (пример ниже).

yaml
input: "src/"          # каталог с кодом, docs, sql‑схемами
output: "graph.dot"    # имя файла с графом
format: "dot"          # поддерживаемые форматы: dot, json, mermaid
languages:             # optional, ограничивает парсинг
  - python
  - sql
  - markdown

Важно – в конфиге указываются только пути, а не URL‑адреса, иначе парсер не сможет работать локально.

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

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

После генерации графа каждый узел представляет элемент языка (класс, функцию, переменную, импорт и т.п.), а ребро описывает отношение между ними. Например, ребро import указывает, что один модуль использует функции из другого; ребро call – что функция вызывается из контекста другого узла; ребро uses – ссылка на использование переменной.

Ниже пример простого графа, полученного после анализа файла main.py, где импортируется parse и вызывается parse.parse().

dot
digraph G {
  "main.py" -> "parse.py"   [label="import"]
  "parse.py" -> "AstNode_1" [label="call"]
  "AstNode_1" -> "AstNode_2" [label="uses"]
}

В Gemini CLI граф можно сразу вывести в виде Mermaid‑диаграммы, что удобно для быстрого просмотра в терминале:

bash
graphify --input main.py --output - --format mermaid

Вывод будет выглядеть так:

mermaid
graph TD
    main.py -->|import| parse.py
    parse.py -->|call| AstNode_1
    AstNode_1 -->|uses| AstNode_2

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

Связанные материалы:

Таким образом, skill /graphify обеспечивает точный, локальный и полностью детерминированный AST‑анализ, а полученный граф дает возможность явно видеть каждую связь между элементами кода, что упрощает как ручной, так и автоматический аудит.

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

### Интеграция в CI/CD и автоматические отчёты

Во-первых, graphify удобно встраивается в любые CI/CD‑платформы, потому что её CLI‑утилита работает в обычном контейнере и не требует внешних сервисов.
С практической точки зрения достаточно добавить один шаг в конфигурацию пайплайна, запустить парсинг, а затем сгенерировать отчёт.

Пример для GitLab CI:

yaml
stages:
  - analyze
  - report

analyze:
  stage: analyze
  image: alpine:latest
  script:
    - curl -L https://graphify-labs.com/graphify | sh
    - graphify parse --input src/ --output graph.dot
  artifacts:
    paths:
      - graph.dot
  rules:
    - if: $CI_COMMIT_BRANCH

report:
  stage: report
  image: python:3.11
  script:
    - pip install graphify-render
    - graphify render --dot graph.dot --format markdown > report.md
  artifacts:
    paths:
      - report.md
  needs: ["analyze"]

В этом примере graphify parse читает исходный код из каталога src/, строит локальный AST‑граф в виде graph.dot, а graphify render превращает его в читаемый markdown‑отчёт.

Если нужно опубликовать отчёт в чат, можно добавить шаг с curl‑запросом к webhook‑у Slack или Microsoft Teams – при этом всё происходит локально, без отправки кода в сторонние сервисы.

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

yaml
version: "3.9"
services:
  parser:
    image: graphify/graphify:latest
    volumes:
      - ./src:/src
    command: ["graphify", "parse", "--input", "/src", "--output", "/out/graph.dot"]
    working_dir: /out
    volumes:
      - ./out:/out

  reporter:
    image: python:3.11-slim
    depends_on:
      - parser
    command: ["pip", "install", "graphify-render", "&&", "graphify", "render", "--dot", "/out/graph.dot", "--format", "markdown", ">", "/out/report.md"]
    volumes:
      - ./out:/out

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

### Поиск по коду и схемы без индексации

Второй популярный сценарий – это быстрый поиск по коду и схемы без необходимости построения внешнего поискового индекса. Graphify сохраняет весь AST‑граф в локальном хранилище (например, в файле graph.dot или в SQLite‑базе), после чего предоставляет CLI‑инструмент graphify search, который ищет по узлам графа за milliseconds.

Пример поиска использования класса HttpClient в Java‑коде:

bash
graphify search --graph graph.dot --query "class HttpClient" --output results.md

Результат (results.md) будет содержать список файлов и строк, где встречается данный класс, что позволяет сразу перейти к правке.

Для SQL‑схем можно выполнять запросы в стиле SQL над графом:

bash
graphify query --graph schema.dot --sql "SELECT file, line FROM symbols WHERE type='TABLE' AND name LIKE 'User%'"

Эта команда выводит все таблицы, имя которых начинается с User, вместе с указанием файла и номера строки, где они объявлены.

Если требуется интегрировать поиск в редактор, достаточно добавить небольшую утилиту‑обёртку, которая принимает путь к файлу, вызывает graphify search и возвращает результат в формате JSON. Пример на Python:

python
import subprocess, json, sys

def search_graph(graph_path, query):
    result = subprocess.run(
        ["graphify", "search", "--graph", graph_path, "--query", query, "--format", "json"],
        capture_output=True,
        text=True,
        check=True,
    )
    return json.loads(result.stdout)

if __name__ == "__main__":
    if len(sys.argv) != 3:
        print("Usage: script.py <graph.dot> <query>")
        sys.exit(1)
    print(json.dumps(search_graph(sys.argv[1], sys.argv[2]), indent=2))

Эти примеры показывают, что поиск без индексации позволяет быстро находить нужные конструкции в больших проектах, а также в документах типа PDF или схем SQL, которые ранее требовали отдельного импорта в ElasticSearch или Similar.

Для дальнейшего чтения о локальных ИИ‑агентах, которые могут использовать такие графы в своих решениях, см. Локальные ИИ-агенты и инструменты.

Если у вас остались вопросы по настройке graphify в вашем CI/CD‑процессе или по поиску по схемы, дайте знать – помогу подобрать конкретные команды под ваш стек.

Ограничения и рекомендации по использованию

Ограничения по объёму и типу данных

При работе с Graphify важно понимать, что отсутствие векторного хранилища — это не только преимущество в плане приватности, но и архитектурное ограничение. Инструмент полагается на точный AST-парсинг (Abstract Syntax Tree), что требует значительных вычислительных ресурсов при обработке больших массивов данных.

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

Во-вторых, тип данных накладывает свои правила:

Код: Инструмент отлично справляется со структурами, где есть чёткая иерархия (Python, Rust, TypeScript). Однако в динамических языках с «магическим» поведением (например, сложные метапрограммируемые конструкции в Python) AST может не уловить все неявные связи.
Документация и PDF: Несмотря на поддержку PDF, качество графа напрямую зависит от структуры документа. Если PDF представляет собой набор сканов без текстового слоя, парсинг не сработает.
SQL-схемы: Здесь всё предсказуемо, но только если схемы валидны. Ошибки в синтаксисе DDL-запросов приведут к тому, что часть узлов графа просто не будет создана.

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

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

Чем Graphify отличается от стандартного RAG с векторной базой?

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

Нужно ли мне разворачивать отдельную базу данных для работы с графом?

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

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

Благодаря использованию абстрактного синтаксического дерева (AST), точность определения связей значительно выше, чем при обычном текстовом поиске. Инструмент видит не просто текст, а иерархию: где объявлена переменная, какой метод вызывает конкретную функцию и как объекты наследуют свойства друг друга. С практической точки зрения это превращает разрозненные файлы в единую, структурно связную карту проекта.

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

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

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