⚡ 다중 저장소 코드 검색 엔진

프로덕션급 코드 검색 및 조회 시스템으로, 여러 소스 코드 저장소를 동시에 검색하고 탐색할 수 있도록 설계되었습니다. OpenSpec 스펙 기반 개발(Spec-Driven Development) 프레임워크를 사용하여 계획 및 설계되었습니다. 순위가 매겨진 결과(저장소, 파일, 줄, 심볼, 그래프 메타데이터 포함)는 외부 클라우드 LLM 클라이언트의 통합 경계 역할을 하며, 해당 클라이언트는 자체 환경에서 생성을 수행합니다.

🌟 주요 기능

1. 다중 저장소 수집 및 증분 동기화:

   • 로컬 코드베이스 디렉터리와 원격 Git 저장소를 관리합니다.

   • .gitignore 규칙을 존중하며 바이너리 및 잠금 파일을 자동으로 제외합니다.

   • SHA-256 해시 추적 및 Git 커밋 감지를 통해 즉각적인 증분 업데이트를 수행합니다.

2. AST 기반 의미론적 코드 청킹:

   • Python, TypeScript/JavaScript, Go, Rust, Java, C/C++, HTML/CSS, SQL, Markdown에 대한 언어 인지 구조적 파싱을 지원합니다.

   • 함수, 메서드, 클래스, 인터페이스 경계를 보존합니다.

   • 범위 헤더(// [Context] Repository | File | Imports | Doc)를 주입합니다.

3. 하이브리드 Dense + Lexical 인덱싱:

   • Dense 벡터 검색: 의미론적 하위 단어 특징 벡터 및 외부 임베딩 지원(Gemini, OpenAI, Voyage AI, Ollama). 로컬 Ollama 임베딩은 기본적으로 qwen3-embedding:0.6b를 사용하며, 필요 시에만 로드되고 유휴 시 해제됩니다.

   • Sparse BM25 검색: camelCase 및 snake_case 토큰을 분리하는 코드 맞춤형 토크나이저와 심볼 가중치 부여를 지원합니다.

   • 상호 순위 융합(RRF): 정확한 식별자 부스트와 함께 Dense 및 Sparse 순위를 병합합니다.

4. 심볼 그래프 및 교차 저장소 의존성 연결:

   • SQLite에서 심볼 정의, 호출자, 피호출자, 임포트를 추출합니다.

   • 서로 다른 저장소 간 프론트엔드 클라이언트 API 호출(예: apiClient.post('/api/v1/auth/login'))을 백엔드 API 라우트 핸들러로 자동 매핑합니다.

5. 인터페이스:

   • 최신 웹 UI: 기본 검색 환경으로 하이브리드 검색, 저장소 관리자, 교차 저장소 API 계약 맵, 코드 검사기 드로어를 제공합니다.

   • MCP(Model Context Protocol) 서버: AI 코딩 어시스턴트(Antigravity, Cursor, Claude Code, Windsurf)에 stdio 도구(search_codebases, get_symbol_definition, get_call_hierarchy, list_repositories)를 노출합니다.

   • CLI: 인덱싱 및 검색을 위한 빠른 터미널 명령어를 제공합니다.

   • REST API: POST /api/v1/search는 외부 클라우드 LLM 소비자를 위해 순위가 매겨진 코드 청크를 반환합니다.

Related MCP server: CodeGraph

📂 OpenSpec 스펙 기반 계획

모든 사양, 아키텍처 계약, 작업 분류는 openspec/ 디렉터리 아래에 유지 관리됩니다:

openspec/
├── config.json                     # OpenSpec project configuration
├── specs/                          # Living System Specifications (Source of Truth)
│   ├── repository-management.md    # Repo ingestion & git tracking
│   ├── ast-code-chunking.md        # AST semantic parsing & context injection
│   ├── hybrid-indexing.md          # Dense vector + BM25 lexical index
│   ├── symbol-graph-retrieval.md   # Call graph & cross-repo API linkage
│   ├── context-fusion-reranking.md # RRF fusion & citation packaging
│   ├── rag-generation.md           # LLM prompting & grounded citations
│   ├── mcp-server.md               # Model Context Protocol tools
│   └── api-and-web-ui.md           # REST & Web UI specifications
└── changes/
    └── 01-foundation-and-core-rag/ # Phase 1 Change Proposal
        ├── proposal.md             # Goals, scope, and motivation
        ├── design.md               # Technical architecture & contracts
        └── tasks.md                # Implementation checklist (Completed)

🚀 빠른 시작

1. 저장소 등록 및 인덱싱

# Add a local repository
python3 main.py add auth-service ./fixtures/repo_auth_service

# Add another repository
python3 main.py add web-client ./fixtures/repo_web_client

# List all indexed repositories
python3 main.py list

2. 저장소 그룹 및 의존성 관계 관리

# Create a repository group
python3 main.py group create platform --repos auth-service shared-schemas

# Declare a dependency edge: web-client depends on auth-service
python3 main.py relation add web-client auth-service

# Inspect relations for a repository
python3 main.py relation show web-client

# Search with group scoping and upstream dependency expansion
python3 main.py search "jwt token" --group platform --expand upstream --expand-depth 1

3. 저장소 간 검색(CLI)

# Hybrid search across all codebases
python3 main.py search "login user authenticate"

# Search scoped to a group with upstream dependency expansion
python3 main.py search "How does authentication flow between web-client and auth-service?" --group platform --expand upstream

4. 대화형 웹 UI 실행

python3 main.py serve --host 127.0.0.1 --port 8000

브라우저에서 http://localhost:8000 을 엽니다.

5. MCP(Model Context Protocol)로 AI IDE 연결

AI IDE 구성에 이 MCP 서버 항목을 추가합니다(Antigravity / Cursor / Claude Code / Windsurf):

{
  "mcpServers": {
    "multi-repo-code-rag": {
      "command": "python3",
      "args": ["/Users/nick-work-pc/.gemini/antigravity/scratch/multi-repo-code-rag/main.py", "mcp"]
    }
  }
}

🧠 임베딩 모델 런타임

엔진은 데이터 디렉터리당 단일 인스턴스로 실행되며 로컬 임베딩 모델을 작동 중일 때만 상주시킵니다.

• 기본 모델: qwen3-embedding:0.6b(ollama pull qwen3-embedding:0.6b로 한 번 설치). --embedding-model 또는 $OLLAMA_EMBEDDING_MODEL로 재정의할 수 있습니다.

• 요청 시 상주: 모델은 시작 시 로드되지 않습니다. 인덱싱 또는 검색 중 첫 임베딩 시 로드되며, 마지막 진행 중 작업이 완료되고 유휴 유예 시간이 경과하면 해제됩니다. 동시 요청은 하나의 로드를 공유하고 하나의 해제를 생성합니다.

• 상주 정책은 --keep-alive 또는 $EMBEDDING_KEEP_ALIVE로 설정합니다:

  값	동작
  (설정 안 함)	30초 유휴 후 해제(기본값)
  0	마지막 작업 직후 즉시 해제
  45s, 5m	해당 유휴 시간 경과 후 해제
  always	프로세스 수명 동안 모델 상주 유지

• 단일 인스턴스: 시작 시 <data-dir>/.rag-instance.lock에 대한 배타적 잠금을 획득합니다. 두 번째 인스턴스는 소유 PID와 함께 즉시 실패합니다. --allow-multi-instance를 전달하면 경고로 강등됩니다.

• 수동 검사 / 해제: GET /api/v1/models/status는 상주 상태, 활성 작업, 정책, 인덱스 출처를 보고합니다. POST /api/v1/models/unload(또는 python3 main.py unload)는 모델을 해제하며, 작업 진행 중이면 409 busy를 반환합니다.

모델 변경 시 자동 재인덱싱

Dense 인덱스는 벡터를 생성한 공급자, 모델, 벡터 차원을 기록합니다(<data-dir>/index_meta.json). 구성된 임베딩 모델이 변경되면(예: qwen3-embedding:4b(2560차원)에서 기본 qwen3-embedding:0.6b(1024차원)로 업그레이드) 영향을 받는 저장소는 검색 결과가 제공되기 전에 자동으로 재임베딩됩니다:

• 청크 텍스트, 심볼, BM25 어휘 인덱스는 보존됩니다(임베딩 전용 패스, 재파싱 아님).

• 진행 상황은 일반 인덱싱 진행 출력을 통해 보고됩니다.

• 출처는 저장소별로 기록되므로 중단된 재빌드는 아직 처리되지 않은 저장소부터 재개됩니다.

• 재빌드 중 도착하는 검색은 다른 모델의 벡터로 점수를 매기는 대신 503 reindexing을 받습니다.

이전 동작으로 롤백: OLLAMA_EMBEDDING_MODEL=qwen3-embedding:4b EMBEDDING_KEEP_ALIVE=always는 이전 모델과 상시 상주 정책을 복원하며, 출처 확인 시 코드 변경 없이 4b 벡터 공간으로 재빌드됩니다.

🏷️ 저장소 그룹 및 의존성 관계 아키텍처

토폴로지 및 도메인 규칙

• 명명된 저장소 그룹: 저장소의 단순 컬렉션(예: core, platform, billing). 그룹을 삭제해도 기본 저장소는 삭제되지 않습니다.

• 방향성 의존성 DAG: 명시적 의존성 엣지 A -> depends on -> B. 엣지 추가 시 쓰기 시간에 순환 감지를 실행하여 순환이 발생하면 DependencyCycleError를 발생시킵니다.

• 범위 확인: 명시적 저장소 ID와 그룹 구성원을 기본 집합으로 결합한 다음, upstream(의존성), downstream(의존 대상), 또는 both 방향으로 expand_depth까지 그래프를 따라 확장합니다.

• 홉 감쇠 순위: 확장된 저장소에서 검색된 청크는 (0.85 ** hops) 점수 승수 패널티를 받아 기본 저장소가 먼저 순위에 오르도록 보장합니다.

• 출처 메타데이터: 확장된 저장소에서 발생한 결과는 메타데이터(repo_relation='expanded', relation_direction, relation_hops)를携带하며 UI에서 시각적 배지로 표시됩니다.

REST API 엔드포인트

MCP 도구

• manage_repository_relations: 작업 create_group, delete_group, add_to_group, remove_from_group, add_dependency, remove_dependency.

• get_repository_relations: 단일 저장소 또는 전체 관계 그래프에 대한 관계를 반환합니다.

• search_codebases: 선택적 groups, expand, expand_depth 인자로 확장되었습니다.

🧪 테스트 실행

python3 -m unittest discover -s tests -p "test_*.py" -v

모든 단위 및 통합 테스트 스위트가 통과하여 AST 청킹, 심볼 추출, 교차 저장소 API 감지, 저장소 관계 DAG 및 순환 감지, 범위 확인 및 홉 감쇠 검색, REST API 핸들러, MCP 프로토콜, 종단 간 하이브리드 검색 조회를 검증합니다.