repo-rag

RAG-поиск по кодовой базе TypeScript/JavaScript. Индексирует AST-блоки, строит граф импортов, ищет семантически + по тексту, реранкит cross-encoder'ом, диверсифицирует MMR.

Установка

npm install @lancedb/lancedb @huggingface/transformers repomix glob ignore typescript

Модели кэшируются в ./models/ (не в ~/.cache).

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

Индексация

# Полная
node rag.js index ./my-project --force

# Инкрементальная (по git diff с последнего коммита)
node rag.js index ./my-project

# Только scope
node rag.js index ./my-project --scope src/auth

Поиск

# Базовый
node rag.js search "add Google OAuth2" --output jira-123.xml

# Со scope
node rag.js search "add Google OAuth2" --scope src/auth --output jira-123.xml

# С диаграммой поиска (Mermaid)
node rag.js search "add Google OAuth2" --output jira-123.xml --diagram search-graph.mmd
# Открой .mmd в https://mermaid.live

Архитектура

┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│   Запрос    │────→│  Эмбеддер   │────→│  LanceDB vector │
│   (Jira)    │     │jina-embed-  │     │    search       │
└─────────────┘     │dings-v2-base│     └─────────────────┘
                    │    -code    │              │
                    └─────────────┘              ↓
                                         ┌─────────────┐
                                         │  Hybrid:    │
                                         │ vector +    │
                                         │ BM25 (FTS)  │
                                         └─────────────┘
                                                  │
                    ┌─────────────┐              ↓
                    │  Reranker   │←─────┌─────────────┐
                    │jina-reranker│      │   Top-K     │
                    │v1-turbo-en  │      │   hits      │
                    └─────────────┘      └─────────────┘
                            │
                            ↓
                    ┌─────────────┐
                    │    MMR      │  ← диверсификация, убирает дубли
                    │  (λ=0.7)    │    одной функции
                    └─────────────┘
                            │
                            ↓
                    ┌─────────────┐
                    │ Graph       │  ← тянем связанные файлы
                    │ expansion   │    по импортам
                    └─────────────┘
                            │
                            ↓
                    ┌─────────────┐
                    │  XML для    │
                    │    Kimi     │
                    └─────────────┘

Фичи

1. Гибридный поиск (vector + BM25)

• Векторный поиск через jina-embeddings-v2-base-code (768d, код-специфичный)
• FTS через LanceDB inverted index по content и block_name
• Fusion: веса 0.7 (vector) / 0.3 (BM25)
• BM25 отлично ловит редкие имена функций (validateTOTPSecret), которые вектор может промазать

2. Cross-encoder reranking

• jina-reranker-v1-turbo-en — правильный sequence classification, не костыль с CLS
• Sigmoid-скор 0..1, комбинируется с векторным расстоянием

3. MMR (Maximal Marginal Relevance)

• lambda = 0.7: релевантность с штрафом на похожие блоки
• Убирает ситуацию, когда 5 чанков одной и той же функции занимают весь топ

4. Семантический чанкинг

• Разбивает не по символам, а по логическим блокам:
  • if/for/while/switch/try/catch
  • .get/.post/.put/.delete (роуты)
  • useEffect/useCallback/useMemo (React hooks)
  • describe/it/test (тесты)
  • case (switch cases)
• Чанкит только если функция >1500 символов И >6000 символов

5. API Surface индекс

• Отдельная таблица экспортов (export function foo, export class Bar)
• При поиске API-хиты бустят файлы как entry points
• Помечаются в XML тегом [API entry point]

6. Граф импортов + cross-file expansion

• Строит граф по import ... from './file' и вызовам функций
• После primary hits тянет связанные файлы (3 блока из каждого)
• Помечает [RELATED] в XML

7. Инкрементальная индексация

• По git diff --name-only с последнего коммита
• Обрабатывает удалённые файлы (убирает из базы)
• Переиндексирует только изменённые

8. Кэширование эмбеддингов

• SHA256 текста → вектор в ./cache/
• Повторная индексация — мгновенная для неизменённых блоков

9. Scope-фильтрация

• --scope src/auth на индексации и поиске
• Работает на glob + SQL WHERE

10. Mermaid-диаграмма поиска

• --diagram graph.mmd генерирует flowchart
• Показывает: запрос → primary hits → API → related → included files → calls
• Открывать в https://mermaid.live

Модели

| Роль | Модель | Размерность | Особенности | |------|--------|-------------|-------------| | Эмбеддер | jinaai/jina-embeddings-v2-base-code | 768 | The Stack + GitHub, 8k токенов, код-специфичный | | Reranker | jinaai/jina-reranker-v1-turbo-en | — | Cross-encoder, 8k токенов, 3× быстрее базового |

Структура БД

repo-rag-db/
├── blocks/          # AST-блоки (функции, классы, интерфейсы...)
├── files/           # Файлы (сводка по экспортам/импортам)
├── api_surface/     # Экспорты (entry points)
└── meta.json        # Граф импортов + последний коммит

Переменные окружения

# Куда скачивать модели (по умолчанию ./models)
HF_HOME=./models node rag.js index ./project