Graphify: Создание знаний из кода в виде графов

Graphify: Создание знаний из кода в виде графов

Graphify преобразует код, документацию, схемы и PDF в интерактивный граф знаний. Поддержка AST, deterministic парсинг, без векторных хранилищ.

Преобразование кода в граф знаний

Преобразование кода в граф знаний

Как Graphify обрабатывает исходники

Graphify начинает работу с исходного кода на этапе парсинга. Вместо того чтобы собирать векторные эмбеддинги, он строит структурированное представление через абстрактное синтаксическое дерево (AST). Этот подход обеспечивает предсказуемость — каждый узел AST имеет определённое семантическое значение, что позволяет проводить точный семантический анализ.

pythonКопировать
# Пример обработки Python-файла
from graphify import parse_source

# Парсим исходники с помощью deterministic-парсера
ast_tree = parse_source(
    source_path="src/auth_service.py",
    parser="ast",
    language="python"
)

# Конвертируем AST в граф знаний
knowledge_graph = ast_tree.to_knowledge_graph()

# Сохраняем граф в Neo4j или другой графовой базе
knowledge_graph.save(target="neo4j://localhost:7687")

Основной принцип — детерминированный парсинг. Каждый вызов парсера с теми же исходниками даст идентичный граф. Это критично для CI/CD пайплайнов, где воспроизводимость результатов важнее скорости обработки.

yamlКопировать
# Конфигурация парсера в graphify.yml
parsers:
  python:
    engine: ast
    deterministic: true
    options:
      tree_class: "ast.AST"
      include_docstrings: true
      
  javascript:
    engine: espree
    deterministic: true
    options:
      ecma_version: 2024
      locations: true
      
  java:
    engine: javalang
    deterministic: true
    options:
      comments: true

Пример обработки JavaScript-кода показывает, как Graphify извлекает зависимости:

javascriptКопировать
// Пример файла: src/api/routes.js
import express from 'express';
import { validateToken } from '../auth/middleware.js';

const router = express.Router();

// Маршрут с семантической метаданной
router.get('/users/:id', validateToken, async (req, res) => {
  const user = await UserService.getById(req.params.id);
  res.json(user);
});

export default router;

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

Поддерживаемые форматы и источники данных

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

Кодовые форматы:

• Python (ast)
• JavaScript/TypeScript (espree)
• Java (javalang)
• Go (go/parser)
• Rust (syn)
• C/C++ (libclang)

Документационные форматы:

• Markdown (remark)
• reStructuredText (docutils)
• LaTeX (texinfo)
• JSON Schema (jsonschema)

Структурные форматы:

• YAML (yaml)
• TOML (tomli)
• XML (xml.etree)

bashКопировать
# Пример использования CLI для обработки нескольких файлов
graphify process \
  --input-dir ./src \
  --output ./knowledge-graph.json \
  --format json \
  --parsers python javascript java \
  --config graphify.yml

Обработка PDF осуществляется через текстовую экстракцию с последующим парсингом полученного текста:

pythonКопировать
# Пример обработки PDF-документации
from graphify import process_pdf

# Извлекаем текст и строим граф знаний
pdf_graph = process_pdf(
    source="documentation/api.pdf",
    extract_method="pymupdf",  # Быстрый и точный экстрактор
    language="en"
)

# Объединяем с графом кода
combined_graph = knowledge_graph.merge(pdf_graph)

Конфигурация источников данных позволяет гибко настраивать обработку каждого типа данных:

yamlКопировать
# graphify-sources.yml
sources:
  code:
    enabled: true
    directories: ["src/", "lib/"]
    exclude_patterns: ["test_*", "*_test.py"]
    
  documentation:
    enabled: true
    files: ["README.md", "API.md", "docs/*.md"]
    parsers: [markdown, rst]
    
  schemas:
    enabled: true
    formats: [json, yaml, protobuf]
    extract_relations: true
    
  pdfs:
    enabled: true
    directory: "./docs/pdf/"
    quality_threshold: 0.85

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

pythonКопировать
# Запуск веб-интерфейса для визуализации графа
from graphify import visualize_graph

graph = visualize_graph(
    data=knowledge_graph,
    port=8080,
    host="0.0.0.0",
    auth_enabled=True
)

# Граф будет доступен по адресу: http://localhost:8080

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

Deterministic парсинг с помощью AST

Deterministic парсинг с помощью AST

Парсинг файлов и построение узлов

Graphify использует абстрактные синтаксические деревья (AST) для гарантированно детерминированного анализа исходного кода. Этот подход устраняет проблемы с вариативностью парсинга, которые возникают при использовании обычных регулярных выражений или нетипизированных парсеров.

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

typescriptКопировать
// Пример конфигурации парсинга файлов
const parserConfig = {
  language: 'typescript',
  extractors: [
    {
      pattern: 'function',
      selector: 'FunctionDeclaration',
      properties: ['name', 'params', 'body']
    },
    {
      pattern: 'class',
      selector: 'ClassDeclaration',
      properties: ['name', 'superClass', 'methods']
    },
    {
      pattern: 'import',
      selector: 'ImportDeclaration',
      properties: ['source', 'specifiers']
    }
  ],
  deterministic: true
};

С практической точки зрения, парсинг выполняется в три этапа:

1. Лексический анализ — разбивка файла на токены с фиксированным порядком
2. Синтаксический анализ — построение AST с помощью TypeScript compiler API
3. Semantический анализ — извлечение значимых узлов с сохранением связей

Результатом является репрезентативное дерево, где каждый узел содержит метаданные, необходимые для построения графа знаний. Это похоже на то, как IKEA собирает мебель: все детали имеют четкое назначение, и каждая часть может быть использована повторно.

Обработка SQL-схем и конфигураций

Для SQL-схем Graphify применяет детерминированный парсинг с помощью специализированного парсера, который работает с CREATE TABLE, ALTER TABLE и другими определениями DDL. Этот подход гарантирует, что каждая таблица, столбец и ограничение будут представлены в виде отдельных узлов с точными связями.

sqlКопировать
-- Пример SQL-схемы для парсинга
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (email) REFERENCES emails(address)
);

CREATE TABLE emails (
    address VARCHAR(255) PRIMARY KEY,
    domain VARCHAR(100) NOT NULL,
    provider VARCHAR(50)
);

yamlКопировать
# Конфигурация обработки SQL в Graphify
sqlProcessing:
  dialect: postgresql
  extractors:
    - pattern: table
      type: CreateTableStatement
      fields: [name, columns, constraints]
    - pattern: column
      type: ColumnDefinition
      fields: [name, type, constraints]
    - pattern: relationship
      type: ForeignKeyConstraint
      fields: [localColumns, foreignTable, foreignColumns]
  deterministic: true
  validation:
    requirePrimaryKeys: true
    enforceNamingConventions: false

Для конфигурационных файлов Graphify поддерживает детерминированный парсинг YAML, JSON и TOML. Система извлекает параметры конфигурации, связывает их с документацией и создает граф знаний, который отображает зависимость между настройками.

yamlКопировать
# Пример конфигурации приложения
app:
  name: "graphify"
  version: "1.0.0"
  database:
    host: "localhost"
    port: 5432
    name: "graphify_db"
  
  features:
    astParsing: true
    deterministicMode: true
    sqlSupport: true
    
  logging:
    level: "info"
    format: "json"

Результатом парсинга является граф знаний, где каждый узел представляет собой конкретный элемент конфигурации, а связи отражают иерархические зависимости. Например, узел "database.host" будет связан с узлом "database", который в свою очередь связан с корневым узлом "app".

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

Настройка Ponytail для Claude Code Использование DESIGN.md для генерации UI DeepSeek Harness: всё как плагин и его архитектура DeepSeek Harness: Полный плагин для LLM-агентов DeepSeek Harness: Плагинная архитектура для AI-инструментов

Интеграция с Claude Code и другими CLI

Интеграция с Claude Code и другими CLI

Использование в Claude Code

Graphify работает с Claude Code через его MCP (Model Context Protocol) механизм. Для начала вам понадобится установить Graphify в качестве инструмента, который Claude может вызывать напрямую.

bashКопировать
# Установка Graphify через npm
npm install -g @graphify/cli

# Или через pip для Python-версии
pip install graphify

После установки вы можете использовать Graphify в Claude Code следующим образом:

jsonКопировать
{
  "mcpServers": {
    "graphify": {
      "command": "node",
      "args": ["~/.graphify/mcp-server.js"],
      "cwd": "/path/to/your/project"
    }
  }
}

В Claude Code вы можете вызывать Graphify для анализа кода:

/analyze --file src/components/user.ts --format graph
/generate-knowledge --source ./docs/api.md --output ./knowledge-graph.json

Graphify поддерживает deterministic парсинг AST, что важно для AI-агентов — каждый запуск дает одинаковый результат, что критично для отслеживания изменений.

Настройка для Cursor и Gemini CLI

Для интеграции с Cursor (который использует Electron и имеет встроенный Node.js) настройте Graphify как десктопный инструмент:

Конфигурация для Cursor (.cursorrc):

jsonКопировать
{
  "graphify": {
    "enabled": true,
    "autoAnalyze": true,
    "outputPath": "${workspaceFolder}/knowledge-graph.json",
    "ignorePatterns": [
      "node_modules/**",
      "dist/**",
      "*.log"
    }
  }
}

Настройка для Gemini CLI (Google AI CLI):

bashКопировать
# Установка Gemini CLI
npm install -g @gemini/cli

# Конфигурация Graphify в .geminirc
echo '{
  "tools": {
    "graphify": {
      "path": "/usr/local/bin/graphify",
      "args": ["--stdio"]
    }
  }
}' > .geminirc

Для использования Graphify с Gemini CLI:

bashКопировать
# Анализ кода через stdin
cat src/main.py | gemini --tool graphify --format mermaid

# Генерация знаний из нескольких источников
gemini --tool graphify \
  --sources "./README.md,./docs/api.md,./CHANGELOG.md" \
  --output "./knowledge-graph.json"

Пример конфигурации Graphify для продвинутого CI/CD:

yamlКопировать
# .github/workflows/graphify-analysis.yml
name: Graphify Code Analysis
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Установка Graphify
        run: npm install -g @graphify/cli
        
      - name: Анализ кода
        run: |
          graphify --input . --output ./knowledge-graph.json \
            --format json \
            --ignore "node_modules,dist,*.log"
            
      - name: Проверка изменений
        run: |
          if [ -f ./knowledge-graph.json ]; then
            git diff --quiet || echo "Graphify обнаружил изменения в структуре знаний"
          fi

Советы по настройке:

• Для больших кодовых базов добавьте maxMemory в конфигурацию Graphify
• Используйте batchSize для обработки файлов порциями
• Включите watchMode для отслеживания изменений в режиме реального времени

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

• Настройка Ponytail для Claude Code
• Использование DESIGN.md для генерации UI
• DeepSeek Harness: всё как плагин и его архитектура
• DeepSeek Harness: Полный плагин для LLM-агентов
• DeepSeek Harness: Плагинная архитектура для AI-инструментов

Практическое применение и примеры

Пример создания графа

Представим, что нам нужно проанализировать проект на Rust и визуализировать зависимости между модулями. Graphify позволяет сделать это буквально за несколько команд.

bashКопировать
# Установка Graphify (одна команда, никаких сложных зависимостей)
npm install -g @graphify/cli

# Инициализация проекта в текущей директории
graphify init

# Анализ исходного кода — CLI поддерживает Rust, Python, TypeScript, Go и десятки других языков
graphify analyze src/ --language rust --output graph.json

# Генерация интерактивной визуализации
graphify render graph.json --format mermaid --output README.md

Результат — это интерактивная схема, где каждый узел — это модуль или функция, а связи отображают импорты и вызовы. Например, в Rust-проекте Graphify автоматически парсит use-инструкции и создаёт граф зависимостей, который можно открыть в браузере или встроить в документацию.

mermaidКопировать
graph TD
    A[main.rs] --> B[lib.rs]
    B --> C[utils.rs]
    C --> D[types.rs]
    D --> E[external_crate]

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

bashКопировать
# Анализ всех источников: исходники + markdown + PDF
graphify analyze . \
  --include "**/*.rs" \
  --include "**/*.md" \
  --include "**/*.pdf" \
  --output full_project_graph.json

# Экспорт в формат, удобный для CI/CD
graphify export full_project_graph.json --format dot --output project_graph.dot

Советы по оптимизации и мониторингу

Кэширование парсинга для больших кодовых баз

Graphify умеет кэшировать результаты парсинга AST. Для проектов с десятками тысяч файлов это экономит часы вычислительного времени.

yamlКопировать
# graphify.config.yaml
cache:
  enabled: true
  directory: ./.graphify_cache
  ttl: 3600  # секунды

analysis:
  workers: 4  # параллельная обработка файлов
  batch_size: 100

Мониторинг изменений

Если вам нужно отслеживать, что изменилось в графе за день, настройте автоматический мониторинг:

bashКопировать
# Установка watcher-а для отслеживания изменений в исходниках
npm install -g chokidar-cli

# Команда для перестроения графа при изменении любого .rs файла
chokidar 'src/**/*.rs' -c 'graphify analyze src/ --language rust --output graph.json && graphify render graph.json --format mermaid --output README.md'

Оптимизация размера графа

Для очень больших проектов можно использовать сэмплирование — Graphify поддерживает вытягивание репрезентативной подвыборки узлов:

bashКопировать
graphify analyze src/ --language typescript \
  --sample-ratio 0.1 \
  --output sampled_graph.json

Настройка производительности

В конфигурации можно ограничить глубину анализа AST, если вам не нужны детализации на уровне выражений:

yamlКопировать
analysis:
  ast_depth: 2  # ограничить глубину AST
  exclude_patterns:
    - "**/*test*.ts"
    - "**/node_modules/**"

Интеграция с CI/CD

Добавьте проверку графа в пайплайн — Graphify может вернуть ненулевой код завершения, если обнаружит проблемные зависимости:

yamlКопировать
# Пример для GitHub Actions
- name: Проверка графа зависимостей
  run: |
    graphify analyze . --output ci_graph.json
    graphify validate ci_graph.json --rules circular-dependencies
    echo "Граф успешно валидирован"

Экспорт в внешние системы

Если вам нужно связать граф с другими инструментами, Graphify поддерживает экспорт в Neo4j, PostgreSQL и даже в простые CSV-файлы:

bashКопировать
# Экспорт в Neo4j импортный формат
graphify export graph.json --format neo4j --output neo4j_import.cypher

# Экспорт в CSV для дальнейшей обработки в Excel
graphify export graph.json --format csv --output nodes.csv --format csv --output edges.csv

Советы по мониторингу

• Используйте deterministic парсинг — это гарантирует, что один и тот же исходный код всегда даёт одинаковый граф, что критично для отслеживания реальных изменений.
• Настройте кэширование для больших кодовых баз — это экономит как время, так и ресурсы процессора.
• Комбинируйте с CI/CD — автоматическая проверка графа помогает обнаруживать проблемные архитектурные решения на ранних стадиях.

Для более глубокого погружения в возможности Graphify ознакомьтесь с материалами на нашем сайте:

• Настройка Ponytail для Claude Code — о том, как интегрировать Graphify с Claude Code
• Использование DESIGN.md для генерации UI — пример автоматической генерации документации на основе графов
• DeepSeek Harness: всё как плагин и его архитектура
• DeepSeek Harness: Полный плагин для LLM-агентов
• DeepSeek Harness: Плагинная архитектура для AI-инструментов