Ragex: Гибридный RAG для анализа кода

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

Я уже давно понял: если мне нужно, чтобы что-то было сделано хорошо, — делегирование отпадает, придётся брать в руки молоток самому. Это касается любых жизненных аспектов: варки борща, замены сантехники, перевода Эдгара Аллана По или Антонио Мачадо на русский, или, там, программирования.

Когда БЯМ научились подключать сторонние MCP-сервера, произошел качественный скачок. Теперь не нужно файнтьюнить модель, можно файнтьюнить буковку «R» из акронима «RAG». Я-то лучше знаю, как правильно извлекать смыслы из моего личного контента. Если речь про код — лучше всего искать правду в AST.

Так и был зачат Ragex — MCP-сервер для семантического анализа кодовых баз с элементами чёрной магии. Проект, понятно, написан на Elixir, потому что ну а на чем еще?

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

Занахрена́?

Я задумывал всё это как retrieval engine для передачи в какой-нибудь клод, но, поскольку сам я ассистентами не пользуюсь, в результате получилось решение, подходящее и для подключения к БЯМ, и для помощи (если не замены) обычному LSP.

Три кита, на которых держится Ragex:

1. Local-first: Никаких внешних API. Всё работает локально. Код не отправляется в облако на растерзание корпоративным серверам. Параноики оценят. Кроме того, использовать БЯМ для извлечения контекста из кода — глупо, когда у нас есть AST. Но простенький локальный семантический поиск я тоже, конечно, прикрутил.

2. Гибридный поиск: Символьный анализ (AST) + семантический поиск (эмбеддинги) + графы знаний. Это как смотреть в тринокль: один окуляр видит близко, другой далеко, третий вообще смотрит в прошлое.

3. Производительность: Запросы выполняются за разумное время, иногда — в ущерб качеству. Потому что жизнь коротка, а ждать результатов анализа кода — это издевательство и вообще прерогатива создателей IDE корпоративного масштаба.

Архитектура

Ragex состоит из нескольких слоёв, каждый из которых старается не испортить работу остальных:

┌─────────────────────────────────────┐
│   MCP Server (JSON-RPC 2.0)         │
│      stdio + Unix Socket            │
└──────────────┬──────────────────────┘
               │
       ┌───────┴────────┐
       ▼                ▼
┌─────────────┐  ┌──────────────┐
│ Анализаторы │  │ Graph Store  │
│ (AST)       │  │ (ETS)        │
└──────┬──────┘  └──────┬───────┘
       │                │
       │         ┌──────┴───────┐
       │         ▼              ▼
       │   ┌──────────┐  ┌─────────────┐
       └──►│  Vector  │  │  Bumblebee  │
           │  Store   │  │  (ML Model) │
           └──────────┘  └─────────────┘

Компоненты

1. MCP Server
Реализация Model Context Protocol — протокола, который позволяет AI-ассистентам общаться с внешними инструментами. JSON-RPC 2.0 через stdio (для интеграции) и Unix-сокет (для интерактивного использования). Люди, использующие ассистентов могут подключить этот MCP туда, я просто добавил его в свой LunarVim (см. ниже).

2. Анализаторы
Парсеры готовы для Elixir, Erlang, Python (частично), JavaScript/TypeScript (наброски), скоро добавлю раст и го, наверное. Каждый парсер извлекает AST, модули, функции, вызовы. Elixir и Erlang используют нативные парсеры, Python вызывает через порт в питоновский модуль ast, JavaScript использует регулярные выражения (потому что жизнь — боль).

3. Graph Store
Граф знаний на основе ETS (Erlang Term Storage). Узлы: модули, функции, вызовы. Рёбра: :calls, :imports, :defines. Поверх графа работают алгоритмы: PageRank, поиск путей, метрики центральности, детекция сообществ.

4. Embeddings & Vector Store
Локальная ML-модель (по умолчанию — sentence-transformers/all-MiniLM-L6-v2, настраивается в конфигах) через Bumblebee. Генерирует 384-мерные векторные представления для каждой функции и модуля. Косинусная близость для семантического поиска. Всё работает без интернета.

5. Hybrid Retrieval
Reciprocal Rank Fusion (RRF) — алгоритм объединения результатов символьного и семантического поиска. Три стратегии: fusion (RRF), semantic-first, graph-first.

6. Editor System
Безопасное редактирование кода с атомарными операциями, бэкапами, валидацией синтаксиса, форматированием. Поддержка multi-file транзакций и семантического рефакторинга через AST.

Зачем это вообще нужно?

1. Семантический поиск по кодовой базе

Проблема: Вы помните, что где-то была функция для работы с HTTP-запросами, но где именно — забыли. Название тоже не помните. Grep не поможет.

Решение: Семантический поиск, да.

# Подключаемся к Ragex
alias Ragex.VectorStore

# Ищем функцию
{:ok, results} = VectorStore.search("HTTP request handler", 
  limit: 5, 
  threshold: 0.7,
  node_type: :function
)

# Результаты отсортированы по релевантности
Enum.each(results, fn {node, similarity} ->
  IO.puts("#{node.name} (#{similarity})")
  IO.puts("  File: #{node.metadata.file}")
  IO.puts("  Line: #{node.metadata.line}")
end)

2. Анализ зависимостей и вызовов

Проблема: Нужн�� понять, откуда вызывается функция process_data/2, и что она сама вызывает. Рефакторинг без такой информации — русская рулетка (которая в запутанных случаях с макросами — до сих пор лучше удается^W удавалась эвристикам из навороченных IDE, чем БЯМ).

Решение: Граф вызовов.

alias Ragex.Graph.Store
alias Ragex.Graph.Algorithms

# Найти все функции, которые вызывают process_data/2
callers = Store.get_callers({:function, "MyModule.process_data/2"})

IO.puts("Callers:")
Enum.each(callers, fn caller ->
  IO.puts("  - #{caller.id}")
end)

# Найти все функции, которые вызывает process_data/2
callees = Store.get_callees({:function, "MyModule.process_data/2"})

IO.puts("\nCallees:")
Enum.each(callees, fn callee ->
  IO.puts("  - #{callee.id}")
end)

# Найти все пути между двумя функциями (с лимитом)
paths = Algorithms.find_all_paths(
  {:function, "MyModule.start/0"},
  {:function, "MyModule.process_data/2"},
  max_depth: 10,
  max_paths: 100
)

IO.puts("\nFound #{length(paths)} paths")

Защита от плотных графов: Если у узла >10 рёбер, Ragex предупредит о потенциальных проблемах с производительностью. Параметр max_paths предотвращает зависание на экспоненциальных взрывах. Не вижу проблемы дать этот параметр на откуп разработчику.

3. Поиск бутылочных горлышек в архитектуре

Проблема: Какие функции являются критичными для всей системы? Если они упадут — всё рухнет.

Решение: Betweenness Centrality (метрика центральности по посредничеству — если кто знает, как перевести менее коряво, свистните, пожалуйста).

alias Ragex.Graph.Algorithms

# Вычислить betweenness centrality для всех функций
scores = Algorithms.betweenness_centrality(
  max_nodes: 1000,
  normalize: true
)

# Отсортировать по убыванию
top_bottlenecks = scores
  |> Enum.sort_by(fn {_node, score} -> score end, :desc)
  |> Enum.take(10)

IO.puts("Top 10 bottleneck functions:")
Enum.each(top_bottlenecks, fn {node_id, score} ->
  IO.puts("  #{node_id}: #{Float.round(score, 4)}")
end)

4. Определение (извлечение) архитектурных модулей

Проблема: Код разросся, структура неочевидна. Хотелось бы понять, какие модули логически связаны и образуют кластеры.

Решение: Community Detection (алгоритм Louvain).

alias Ragex.Graph.Algorithms

# Найти сообщества (кластеры модулей)
communities = Algorithms.detect_communities(
  algorithm: :louvain,
  hierarchical: true,
  resolution: 1.0
)

IO.puts("Found #{map_size(communities)} communities")

# Группировка по сообществам
grouped = Enum.group_by(communities, fn {_node, community} -> community end)

Enum.each(grouped, fn {community_id, members} ->
  IO.puts("\nCommunity #{community_id} (#{length(members)} nodes):")
  Enum.each(members, fn {node_id, _} ->
    IO.puts("  - #{node_id}")
  end)
end)

5. Безопасный рефакторинг

Проблема: Нужно переименовать функцию old_function/2 в new_function/2 во всём проекте. Ручной рефакторинг — это ошибки и страдания.

Решение: Семантический рефакторинг через AST. Да, даже для питона.

alias Ragex.Editor.Refactor

# Переименовать функцию во всём проекте
result = Refactor.rename_function(
  :MyModule,
  :old_function,
  :new_function,
  2,  # arity
  scope: :project,
  validate: true,
  format: true
)

case result do
  {:ok, details} ->
    IO.puts("Success! Updated files:")
    Enum.each(details.edited_files, &IO.puts("  - #{&1}"))
    
  {:error, reason} ->
    IO.puts("Rollback performed. Error: #{inspect(reason)}")
end

Через граф знаний нашли все места, откуда вызывается функция, заменили AST по месту (то есть, работает даже для сгенерированного мюнхгаузен-кода), форматирует результат, валидирует синтаксис, и (!) атомарно применяет изменения (или откатывает всё при ошибке).

6. Multi-File транзакции

Проблема: Нужно одновременно изменить несколько файлов. Если хоть одно изменение невалидно — откатить всё.

Решение: Атомарные транзакции.

alias Ragex.Editor.{Transaction, Types}

# Создать транзакцию
txn = Transaction.new(validate: true, format: true)
  |> Transaction.add("lib/module_a.ex", [
      Types.replace(10, 15, "def new_version do\n  :ok\nend")
    ])
  |> Transaction.add("lib/module_b.ex", [
      Types.insert(20, "@doc \"Updated documentation\"")
    ])
  |> Transaction.add("test/module_test.exs", [
      Types.replace(5, 5, "# Updated test")
    ])

# Применить все изменения атомарно
case Transaction.commit(txn) do
  {:ok, result} ->
    IO.puts("Edited #{result.files_edited} files successfully")
    
  {:error, result} ->
    IO.puts("Transaction rolled back!")
    IO.puts("Errors: #{inspect(result.errors)}")
end

Тут важна атомарность: при любой ошибке — автоматический откат всех изменений, все бэкапы хранятся (в ~/.ragex/backups/<project_hash>/) и т. д.

7. Бонус-трек — экспорт в DOT и D3.js

Интеграция с LunarVim

LunarVim — это мой редактор кода, Neovim на стероидах. Ragex интегрируется через MCP и предоставляет команды для семантического поиска прямо из редактора.

Установка

Скопируйте конфигурационные файлы:

cp ragex/lvim.cfg/lua/user/*.lua ~/.config/lvim/lua/user/

Добавьте в ~/.config/lvim/config.lua:

-- Ragex integration
local ragex = require("user.ragex")
local ragex_telescope = require("user.ragex_telescope")

-- Setup
ragex.setup({
  ragex_path = vim.fn.expand("~/Proyectos/Ammotion/ragex"),
  enabled = true,
  debug = false,
})

-- Keybindings (using "r" prefix)
lvim.builtin.which_key.mappings["r"] = {
  name = "Ragex",
  s = { function() ragex_telescope.ragex_search() end, "Semantic Search" },
  w = { function() ragex_telescope.ragex_search_word() end, "Search Word" },
  f = { function() ragex_telescope.ragex_functions() end, "Find Functions" },
  m = { function() ragex_telescope.ragex_modules() end, "Find Modules" },
  a = { function() ragex.analyze_current_file() end, "Analyze File" },
  d = { function() ragex.analyze_directory(vim.fn.getcwd()) end, "Analyze Directory" },
  c = { function() ragex.show_callers() end, "Find Callers" },
  r = { function()
      vim.ui.input({ prompt = "New name: " }, function(name)
        if name then ragex.rename_function(name) end
      end)
    end, "Rename Function" },
  g = { function() ragex.graph_stats() end, "Graph Stats" },
  b = { function() ragex.show_betweenness_centrality() end, "Betweenness" },
  n = { function() ragex.show_communities("louvain") end, "Communities" },
  e = { function() ragex.export_graph("graphviz") end, "Export Graph" },
}

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

<leader>r

Пример Workflow

Типичный сценарий работы с Ragex в LunarVim:

1. Открыли проект: <leader>rd (анализировать директорию, по умолчанию — автоматом)
2. Нужно найти функцию: <leader>rs → "database connection"
3. Нашли функцию, открыли файл <Enter> в телескопе
4. Хотим узнать, кто вызывает: <leader>rc
5. Решили переименовать: <leader>rr → "connect_to_db"
6. Проверили статистику: <leader>rg
7. Экспортировали граф для визуализации: <leader>re

Настройка Auto-Analyze

Ragex может автоматически анализировать код при сохранении файлов:

ragex.setup({
  auto_analyze = true,
  auto_analyze_on_start = true,
  auto_analyze_dirs = { "/path/to/project" },
})

Инкрементальные обновления: Ragex отслеживает изменения через SHA256-хеширование и перегенерирует эмбеддинги только для изменённых файлов.

Память

На совсем жиденьких лэптопах я бы не стал пользоваться Ragex.

• ML-модель: ~400 MB RAM

• ETS-таблицы: линейный рост, ~400 bytes на узел

• Эмбеддинги: ~400 bytes на вектор (384 float32)

• Кеш-файлы: ~15 MB на 1000 сущностей

Настройка

Поддержка пользовательских Embedding-Моделей

Ragex поддерживает 4 предконфигурированных модели, но не для смены на лету:

# config/config.exs
config :ragex, :embedding_model, "sentence-transformers/all-MiniLM-L6-v2"

# Альтернативы:
# - "sentence-transformers/all-MiniLM-L12-v2" (больше точность)
# - "sentence-transformers/paraphrase-MiniLM-L3-v2" (быстрее)
# - "sentence-transformers/multi-qa-MiniLM-L6-cos-v1" (для Q&A)

Миграция моделей:

mix ragex.embeddings.migrate --from old_model --to new_model

File Watching

Автоматическое переиндексирование при изменении файлов:

# Через MCP
{"method": "tools/call", "params": {
  "name": "watch_directory",
  "arguments": {"path": "/project/lib"}
}}

# В коде
Ragex.FileWatcher.watch("/project/lib")

Экспорт Графа для Визуализации

alias Ragex.Graph.Algorithms

# Graphviz DOT format
{:ok, dot} = Algorithms.export_graphviz(
  color_by: :betweenness,
  include_communities: true
)
File.write!("graph.dot", dot)

# Рендерим через Graphviz
System.cmd("dot", ["-Tpng", "graph.dot", "-o", "graph.png"])

# D3.js JSON format (для веб-визуализации)
{:ok, json} = Algorithms.export_d3_json(include_communities: true)
File.write!("graph.json", json)

Ух, обожаю картинки и D3.js-диаграммки, которые можно пошевелить мышкой.

Ограничения и подводные камни

Потому что честность — моё третье «я»:

1. JavaScript/TypeScript анализатор: Использует регулярные выражения. Работает для «простых» случаев. Когда-нибудь, может быть, руки дойдут.

2. Семантический рефакторинг: Пока только для Elixir. Erlang/Python/JS в планах, но не сегодня.

3. Плотные графы: Если у функции >100 вызовов, поиск путей может занять вечность. Используйте max_paths и max_depth.

4. Память: 400 MB для модели — это цена локального ML. Если RAM критична, можно отключить эмбеддинги (но зачем тогда вообще Ragex?).

5. Cold start: Первая генерация эмбеддингов занимает время. После этого — кеширование спасает.

В общем

Ragex — это попытка сделать анализ кода менее болезненным и более семантическим. Граф знаний + векторные эмбеддинги + алгоритмы на графах = инструмент, который может ответить на вопросы типа «где это используется?», «что это делает?», «почему всё сломалось?». А еще это MCP-сервер, который можно подключить к вашему ассистенту кода, чтобы тому тоже было проще ответить на эти вопросы.

MCP-протокол, потому что AI-ассистенты — будущее (или настоящее, в зависимости от того, насколько вы параноик).

Интеграция с LunarVim превращает рефакторинг в нечто почти приятное. Семантический поиск работает, граф не врёт, рефакторинг никогда не ломает код. В теории.

---

P. S. Если возникло желание попробовать, скачайте проект, скачайте зависимости, запустите ./start_mcp.sh и наслаждайтесь. Если что-то сломается — issue в GitHub. Если всё заработало — это, конечно, тоже можно написать в issue, но кто так делает?

P. P. S. Проект open-source, лицензия MIT. Делайте что хотите, на свой страх и риск. Автор не несёт ответственности за потерянное время, сломанный код и экзистенциальные кризисы, вызванные чтением чужих графов вызовов.

Репозиторий: https://github.com/am-kantox/ragex