skills/proffesor-for-testing__agentic-qe

mirror of https://github.com/proffesor-for-testing/agentic-qe.git synced 2026-09-19 08:45:47 +08:00

Files

T

Profa ae528aea7e feat(code-intelligence): implement Wave 1-2 with SQL-based graph architecture

## Wave 1: Database Foundation
- Add SQL schema for code_chunks, code_entities, entity_relationships
- Use RuVector 768-dim embeddings (not pgvector)
- Implement hybrid_code_search function (BM25 + vector)
- Add pg_trgm extension for full-text search
- Create setup scripts for Ollama/nomic-embed-text

## Wave 2: Multi-Language Parser
- Implement TreeSitterParser with 5 language support
- Add language-specific extractors (TS, Python, Go, Rust, JS)
- Implement incremental parsing with tree caching
- Create comprehensive test suite with fixtures

## Architecture Decision
- Defer Apache AGE to v2 (see ADR-002)
- Use SQL tables for graph relationships
- Rationale: Lower complexity, team familiarity, sufficient for v1

Closes #159, Closes #160

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2025-12-21 13:49:39 +00:00

60 KiB

Raw Permalink Blame History

RuVector Knowledge Graph Complementary Tools - Research Report 2025

Research Date: December 21, 2025 Researcher: Research Agent Context: Project knowledge graph with RuVector (PostgreSQL + pgvector) + Serena LSP + ts-morph Goal: Identify tools to enhance code vectorization, semantic search, and relationship graph capabilities

Executive Summary

This research identifies the most promising tools to complement the RuVector-based code knowledge graph architecture. The analysis covers 40+ tools across 6 categories, with detailed evaluation of fit, maturity, integration effort, licensing, and performance.

Top 5 Recommendations

Tree-sitter - Incremental AST parsing for multi-language support (36x faster than alternatives)
Apache AGE - PostgreSQL graph extension for native Cypher queries on existing database
nomic-embed-text - Local code embeddings with 8192 token context (Matryoshka architecture)
LlamaIndex - RAG framework optimized for code retrieval (40% faster than LangChain)
Mermaid.js - Code visualization with native GitHub/GitLab integration

Architecture Evolution

Current: RuVector + pgvector + Serena + ts-morph
Phase 1: + Tree-sitter + Apache AGE + nomic-embed
Phase 2: + LlamaIndex + hybrid search (BM25)
Phase 3: + Incremental indexing + visualization dashboard

1. Code Intelligence & Understanding

1.1 Tree-sitter ⭐ HIGHLY RECOMMENDED

Description: Incremental AST parser supporting 40+ languages written in pure C.

Key Features:

Incremental parsing: Only re-parses changed portions (real-time analysis)
Error resilience: Parses incomplete code with syntax errors
WebAssembly support: Browser-based parsing without server
Powerful query language for pattern matching
36x speed improvement over traditional parsers

Fit with RuVector: 🟢 EXCELLENT

Complements ts-morph by adding multi-language support
Incremental parsing aligns with git-based change detection
CST (Concrete Syntax Tree) preserves full source fidelity for accurate vectorization
Query language enables relationship extraction (IMPORTS, CALLS, etc.)

Integration:

// Example: Adding Tree-sitter alongside ts-morph
import Parser from 'tree-sitter';
import Python from 'tree-sitter-python';

const parser = new Parser();
parser.setLanguage(Python);

// Incremental update on file change
const tree = parser.parse(sourceCode);
const newTree = tree.edit(edit).parse(newSourceCode);

Metrics:

GitHub Stars: 18.6k+ (tree-sitter/tree-sitter)
Languages: 40+ grammars maintained
License: MIT
Maturity: Production-ready, used in GitHub, Atom, Neovim
Performance: 36x faster parsing, incremental updates in <10ms

Recommendation: ADOPT IN PHASE 1 - Essential for multi-language support

Sources:

1.2 SWC (Speedy Web Compiler)

Description: Rust-based JavaScript/TypeScript compiler and bundler.

Key Features:

20x faster than Babel on single thread, 70x on 4 cores
AST transformation and code generation
Plugin system for custom transformations
Used in Next.js, Remix

Fit with RuVector: 🟡 MODERATE

Faster than ts-morph for JS/TS parsing but less flexible
Better for build pipelines than analysis workflows
AST interop possible with Babel plugins

Metrics:

GitHub Stars: 31k+ (swc-project/swc)
License: Apache 2.0
Performance: 616 ops/sec vs Babel's 34 ops/sec
Maturity: Production-ready, framework adoption

Recommendation: EVALUATE IN PHASE 2 - Consider for high-throughput parsing if JS/TS dominates

Sources:

1.3 CodeQL

Description: Semantic code analysis engine by GitHub treating code as data.

Key Features:

Deep semantic analysis beyond pattern matching
Custom query language for vulnerability detection
Multi-language: Java, JS, Python, C/C++, TypeScript, Go, C#
Native GitHub integration

Fit with RuVector: 🟡 MODERATE

Powerful for security/quality analysis but heavyweight
Query results could feed into knowledge graph as relationships
Slower than pattern-matching tools (database-driven analysis)

Metrics:

License: MIT (CLI and libraries)
Maturity: Enterprise-grade, GitHub Advanced Security
Accuracy: High precision but higher false-positive rate than Semgrep
Performance: Requires database creation before querying

Recommendation: OPTIONAL - PHASE 3 - Use for advanced security graph relationships

Sources:

1.4 Semgrep ⭐ RECOMMENDED

Description: Fast pattern-matching SAST tool with AST-aware rules.

Key Features:

Lightweight syntax-based analysis
Zero false positives in security mode (Doyensec research)
20+ programming languages
Rapid scanning for CI/CD (seconds, not minutes)

Fit with RuVector: 🟢 GOOD

Fast pattern detection complements deeper semantic analysis
Could populate graph with code quality/security relationships
Rules exportable as metadata for vector search

Metrics:

GitHub Stars: 10k+ (semgrep/semgrep)
License: LGPL (open-source), commercial options
Performance: Significantly faster than CodeQL
Maturity: Production-ready with enterprise support

Recommendation: ADOPT IN PHASE 2 - Augment graph with security/quality edges

Sources:

1.5 SeaGOAT

Description: Local-first semantic code search using vector embeddings.

Key Features:

ChromaDB for local vector storage (telemetry disabled)
all-MiniLM-L6-v2 embeddings (not code-specific)
ripgrep integration for hybrid search
No remote APIs required

Fit with RuVector: 🟡 MODERATE

Similar goals but uses ChromaDB instead of pgvector
Could inspire retrieval patterns
Limited by general-purpose embedding model

Metrics:

GitHub Stars: 2k+ (kantord/SeaGOAT)
License: MIT
Performance: Depends on all-MiniLM-L6-v2 (not optimized for code)
Maturity: Early-stage project

Recommendation: REFERENCE ONLY - Study retrieval patterns but stick with pgvector

Sources:

2. Knowledge Graph & Graph Databases

2.1 Apache AGE ⭐ HIGHLY RECOMMENDED

Description: PostgreSQL extension adding graph database functionality with Cypher query language.

Key Features:

Native PostgreSQL extension (uses existing infrastructure)
OpenCypher query language (SQL/PGQ inspired)
Multi-model: Combines relational + graph in one database
GIN indices for graph property indexing
ACID transactions, MVCC, triggers

Fit with RuVector: 🟢 EXCELLENT

Perfect match - extends PostgreSQL (same as RuVector)
No additional database infrastructure needed
Cypher queries for relationship traversal (IMPORTS, CALLS, TESTS)
Can query pgvector embeddings + graph relationships together

Integration Example:

-- Create graph schema
SELECT create_graph('code_graph');

-- Add nodes and edges
SELECT * FROM cypher('code_graph', $$
  CREATE (f:File {path: '/src/auth.ts', embedding_id: 123})
  CREATE (c:Class {name: 'AuthService', file_id: f.id})
  CREATE (m:Method {name: 'login'})
  CREATE (c)-[:CONTAINS]->(m)
$$) as (result agtype);

-- Query with vector similarity + graph traversal
SELECT f.path, similarity
FROM files f
JOIN LATERAL (
  SELECT * FROM cypher('code_graph', $$
    MATCH (file:File {embedding_id: $1})-[:IMPORTS*1..3]->(dep)
    RETURN dep.path
  $$) as (dep_path agtype)
) deps ON true
ORDER BY f.embedding <=> query_vector
LIMIT 10;

Metrics:

GitHub Stars: 3.2k+ (apache/age)
PostgreSQL Versions: 11-17 supported
License: Apache 2.0
Maturity: v1.1.0+ production-ready
Performance: Optimized with GIN indices, outperforms Neo4j on certain queries
Cloud Support: Azure Database for PostgreSQL (preview)

Recommendation: ADOPT IN PHASE 1 - Native graph capabilities on existing database

Sources:

2.2 DuckPGQ (DuckDB Graph Extension)

Description: SQL/PGQ graph queries on DuckDB (SQL:2023 standard).

Key Features:

SQL/PGQ syntax (Cypher-inspired, standardized)
Persistent property graphs
Fast in-memory operations
Outperforms Neo4j on pattern matching

Fit with RuVector: 🔴 LOW

Would require DuckDB alongside PostgreSQL (complexity)
Better for analytics workloads than persistent graph storage
Apache AGE provides same benefits on PostgreSQL

Metrics:

GitHub Stars: 200+ (cwida/duckpgq-extension)
License: MIT
Maturity: Community extension (v0.1.0+)
Performance: Faster than traditional graph DBs for certain queries

Recommendation: DO NOT ADOPT - Adds unnecessary complexity vs Apache AGE

Sources:

2.3 TypeDB

Description: Knowledge graph database with native reasoning engine and type system.

Key Features:

TypeQL query language (logic-based)
Deductive reasoning at query time
Polymorphic type system with inheritance
Rule-based inference
Full explainability for reasoning results

Fit with RuVector: 🟡 MODERATE

Powerful for complex reasoning but heavyweight
Would require separate database infrastructure
Better for domain-specific knowledge graphs (biomedical, robotics)

Metrics:

GitHub Stars: 3.6k+ (vaticle/typedb)
License: AGPL (open-source), commercial available
Maturity: Production-ready, enterprise deployments
Use Cases: Drug discovery, biomedical knowledge graphs

Recommendation: EVALUATE IN PHASE 3 - Consider for advanced reasoning if needed

Sources:

2.4 Oxigraph + RDFLib

Description: SPARQL graph database written in Rust with Python bindings.

Key Features:

SPARQL 1.1 Query, Update, Federated Query
RocksDB backend for persistence
RDF serialization formats (Turtle, N-Triples, RDF/XML)
rdflib integration via oxrdflib

Fit with RuVector: 🔴 LOW

RDF/SPARQL adds complexity vs property graphs
Better for semantic web / linked data use cases
Apache AGE provides simpler property graph model

Metrics:

GitHub Stars: 900+ (oxigraph/oxigraph)
License: MIT / Apache 2.0
Maturity: Production-ready
Performance: Fast for SPARQL queries

Recommendation: DO NOT ADOPT - Semantic web model not needed for code graphs

Sources:

3. Embedding & Vector Models

3.1 nomic-embed-text ⭐ HIGHLY RECOMMENDED

Description: Multilingual MoE (Mixture-of-Experts) embedding model with Matryoshka architecture.

Key Features:

First MoE text embedding model
Supports ~100 languages
Context length: 8,192 tokens (ideal for large code files)
Flexible dimensions: 768 → 256 (Matryoshka learning)
Trained on 1.6B+ pairs
Local deployment via Ollama or Hugging Face

Fit with RuVector: 🟢 EXCELLENT

Long context handles entire files/modules
Local deployment = no API costs or privacy concerns
Matryoshka: Tune dimension/performance tradeoff
Strong performance on long-context tasks

Integration:

# Local deployment with Ollama
from ollama import embeddings

# Generate embeddings for code
code_embedding = embeddings(
    model='nomic-embed-text',
    prompt=source_code
)

# Store in pgvector
cursor.execute(
    "INSERT INTO code_chunks (content, embedding) VALUES (%s, %s)",
    (source_code, code_embedding)
)

Metrics:

Model: nomic-embed-text-v2-moe
Dimensions: 768 (default), flexible to 256
Context: 8,192 tokens
License: Apache 2.0
Performance: 86.2% top-5 accuracy (best in class)
Cost: Free (local)

Recommendation: ADOPT IN PHASE 1 - Superior to OpenAI for code + local deployment

Sources:

3.2 BGE (BAAI General Embedding)

Description: Family of multilingual embedding models, especially BGE-M3.

Key Features:

Multi-functionality: Dense, multi-vector, sparse retrieval simultaneously
Multi-linguality: 100+ languages
Multi-granularity: Sentences → 8,192 token documents
Common semantic space across languages

Fit with RuVector: 🟢 GOOD

Versatile for different code granularities
Hybrid retrieval capabilities (dense + sparse)
Good balance of power and efficiency

Metrics:

Model: BGE-M3
Dimensions: 1024
Context: 8,192 tokens
License: Apache 2.0
Performance: Mid-size, balanced accuracy

Recommendation: ALTERNATIVE TO NOMIC - Consider if multi-vector retrieval needed

Sources:

3.3 all-MiniLM-L6-v2

Description: Lightweight sentence embedding model.

Key Features:

Fast: 14.7ms / 1K tokens
Small: 384 dimensions
Low latency: 68ms end-to-end
Efficient for limited hardware

Fit with RuVector: 🟡 MODERATE

Speed excellent for real-time search
5-8% lower accuracy vs larger models
Not optimized for code (general-purpose)

Metrics:

Dimensions: 384
Context: 256 tokens (short)
License: Apache 2.0
Performance: Fast but less accurate

Recommendation: FALLBACK OPTION - Use only if resource-constrained

Sources:

Comparing Local Embedding Models for RAG Systems

3.4 Code-Specific Models

Voyage Code-3 (Commercial)

Key Features:

97.3% MRR, 95% Recall@1 (best performance)
Specialized for code semantic understanding
Proprietary model

Fit: 🟡 MODERATE - Excellent performance but requires API/licensing

StarCoder/StarEncoder (Open-Source)

Key Features:

Trained on 1T+ tokens, 80+ languages
Open-source code LLM chosen for extensive training
Outperforms CodeGen, code-cushman-001 on HumanEval

Fit: 🟢 GOOD - Open-source code-specific option

Metrics:

License: Apache 2.0 (StarCoder)
Performance: Better than CodeBERT but below Voyage-3

Recommendation: EVALUATE StarEncoder if code-specific model needed

Sources:

3.5 AST-Based Chunking Strategy ⭐ CRITICAL

Description: Structure-aware code chunking using Abstract Syntax Trees.

Key Findings:

Traditional chunking by lines breaks semantic units (functions, classes)
AST-based chunking preserves syntactic structure
cAST approach: Recursively break large AST nodes, merge siblings
Results: 5.5 points gain on RepoEval, 4.3 points on CrossCodeEval

Implementation:

# Using Tree-sitter for AST-based chunking
import tree_sitter
from tree_sitter import Language, Parser

# Parse code
parser = Parser()
parser.set_language(Language('build/my-languages.so', 'python'))
tree = parser.parse(bytes(source_code, "utf8"))

# Chunk by AST nodes (functions, classes)
def chunk_by_ast(node, max_tokens=512):
    chunks = []
    if node.type in ['function_definition', 'class_definition']:
        chunk_text = source_code[node.start_byte:node.end_byte]
        if count_tokens(chunk_text) <= max_tokens:
            chunks.append({
                'text': chunk_text,
                'type': node.type,
                'metadata': extract_metadata(node)
            })
        else:
            # Recursively split large nodes
            for child in node.children:
                chunks.extend(chunk_by_ast(child, max_tokens))
    return chunks

Best Practices:

Optimal chunk size: 256-512 tokens
Overlap: 10-20% for context preservation
Metadata retention: Preserve file, class, function-level context
Tools: ASTChunk (Python), cAST framework

Recommendation: ADOPT IN PHASE 1 - Essential for quality code embeddings

Sources:

3.6 Hybrid Search (BM25 + Vector) ⭐ RECOMMENDED

Description: Combine keyword search (BM25) with vector similarity for best results.

Key Features:

BM25: Precision on exact keyword matches (term frequency + IDF)
Vector Search: Semantic understanding and generalization
Fusion: Reciprocal Rank Fusion (RRF) or weighted scoring

Why Hybrid:

Vector search alone can miss exact matches
BM25 alone lacks semantic understanding
Hybrid bridges both gaps

Implementation:

-- PostgreSQL with pgvector + BM25 (VectorChord-bm25)
WITH bm25_results AS (
  SELECT id, ts_rank_cd(to_tsvector(content), query) as bm25_score
  FROM code_chunks
  WHERE to_tsvector(content) @@ plainto_tsquery('authentication error')
),
vector_results AS (
  SELECT id, 1 - (embedding <=> query_vector) as vector_score
  FROM code_chunks
  ORDER BY embedding <=> query_vector
  LIMIT 100
)
SELECT
  c.id, c.content,
  COALESCE(b.bm25_score * 0.4, 0) + COALESCE(v.vector_score * 0.6, 0) as combined_score
FROM code_chunks c
LEFT JOIN bm25_results b ON c.id = b.id
LEFT JOIN vector_results v ON c.id = v.id
ORDER BY combined_score DESC
LIMIT 10;

Fusion Techniques:

Weighted Sum: Normalize scores (e.g., 60% BM25, 40% vector)
Reciprocal Rank Fusion (RRF): Combine rankings without raw scores
- Formula: RRF(d) = Σ 1/(k + rank_i(d)) where k=60 typically
Cross-Encoder Reranking: Final stage for top results (slower but accurate)

Recommendation: ADOPT IN PHASE 2 - Significant accuracy improvement

Sources:

4. Indexing & Incremental Updates

4.1 Git-Based Change Detection ⭐ RECOMMENDED

Description: Detect changed files using git diff for incremental re-indexing.

Key Features:

tj-actions/changed-files: GitHub Action for PR/branch change detection
- Fast: 0-10 seconds execution
- Uses GitHub REST API or Git native diff
dorny/paths-filter: Workflow filtering based on file paths
Only re-index changed files, not entire codebase

Fit with RuVector: 🟢 EXCELLENT

Essential for incremental updates at scale
Integrates with CI/CD pipelines
Reduces embedding costs (only changed code)

Integration:

# .github/workflows/index-code.yml
name: Incremental Code Indexing
on: [push, pull_request]

jobs:
  index:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # Full history for diff

      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@v40
        with:
          files: |
            src/**/*.{ts,js,py}
            tests/**/*.{ts,js,py}

      - name: Re-index changed files
        if: steps.changed-files.outputs.any_changed == 'true'
        run: |
          echo "Changed files: ${{ steps.changed-files.outputs.all_changed_files }}"
          npm run index -- ${{ steps.changed-files.outputs.all_changed_files }}

Recommendation: ADOPT IN PHASE 1 - Critical for scalability

Sources:

4.2 File Watchers

e-dant/watcher ⭐ RECOMMENDED

Description: Cross-platform filesystem watcher with minimal overhead.

Key Features:

Watch entire filesystem efficiently
Near-zero resource usage
Event overhead < filesystem operation time (10x less)
Cross-platform: macOS FSEvents, Linux inotify, Windows

Fit: 🟢 EXCELLENT - Local development incremental indexing

fswatch

Description: Cross-platform file change monitor with multiple backends.

Fit: 🟢 GOOD - Alternative to e-dant/watcher

Recommendation: ADOPT e-dant/watcher IN PHASE 2 for local development

Sources:

4.3 Monorepo Build Tools

Nx vs Turborepo

Nx:

7x faster than Turborepo in large monorepos (Nx benchmarks)
Interactive dependency graph visualization
Rust core + TypeScript extensibility
Advanced features: affected detection, task orchestration

Turborepo:

Simpler, focused approach
Better incremental caching mechanisms (smaller cache size)
Rust-based for speed
Used by Vercel, Next.js

Fit with RuVector: 🟢 GOOD

Dependency graphs could feed into knowledge graph
Incremental build detection informs re-indexing
Project graph provides DEPENDS_ON relationships

Recommendation: EVALUATE IN PHASE 2 if monorepo structure exists

Sources:

5. RAG Frameworks for Code

5.1 LlamaIndex ⭐ HIGHLY RECOMMENDED

Description: RAG framework optimized for data ingestion and document indexing.

Key Features:

150+ data connectors (Git, GitHub, file systems)
40% faster retrieval than LangChain
35% boost in retrieval accuracy (2025)
Specialized for document-heavy applications
Node parsers, chunkers, embeddings pipeline
Index types: vector, list, tree, knowledge graph
Query engines with adaptive retrieval strategies
Built-in observability and evaluation tools

Fit with RuVector: 🟢 EXCELLENT

Purpose-built for code/doc retrieval
Data connectors handle multi-source ingestion
Query engines integrate with pgvector
Better accuracy for code context retrieval

Integration:

from llama_index import VectorStoreIndex, ServiceContext
from llama_index.vector_stores import PGVectorStore
from llama_index.embeddings import HuggingFaceEmbedding

# Configure pgvector as vector store
vector_store = PGVectorStore.from_params(
    database="ruvector_db",
    host="localhost",
    port=5432,
    table_name="code_embeddings"
)

# Use nomic-embed for embeddings
embed_model = HuggingFaceEmbedding(
    model_name="nomic-ai/nomic-embed-text-v2"
)

# Create index
service_context = ServiceContext.from_defaults(embed_model=embed_model)
index = VectorStoreIndex.from_vector_store(
    vector_store=vector_store,
    service_context=service_context
)

# Query with graph context
query_engine = index.as_query_engine(
    similarity_top_k=5,
    filters={"language": "typescript"}
)
response = query_engine.query("How does authentication work?")

When to Use LlamaIndex vs LangChain:

LlamaIndex: Document retrieval, code search, knowledge bases
LangChain: Multi-step workflows, agentic systems, rapid prototyping
Both Together: Many teams use LlamaIndex for retrieval + LangChain for workflows

Recommendation: ADOPT IN PHASE 2 - Core RAG framework for code retrieval

Sources:

5.2 LangChain

Description: Framework for building complex LLM applications with chains and agents.

Key Features:

Modular "chain of calls" architecture
50K+ integrations
3x faster development time vs custom solutions
LangGraph for workflow control (2025)
Large ecosystem

Fit with RuVector: 🟡 MODERATE

Better for agentic workflows than pure retrieval
Overkill if only need RAG (LlamaIndex simpler)
Useful for multi-step code analysis tasks

Recommendation: EVALUATE IN PHASE 3 if building agents beyond retrieval

Sources:

5.3 Continue Dev

Description: Open-source AI code assistant with custom RAG support.

Key Features:

MCP (Model Context Protocol) integration
Custom RAG via MCP servers
Context provider system (inspired by Aider's repo map)
Recommended: voyage-code-3 embeddings + LanceDB
VS Code and JetBrains plugins

Fit with RuVector: 🟢 GOOD

MCP could integrate with RuVector knowledge graph
Context providers show best practices for code RAG
Reference architecture for IDE integration

Recommendation: REFERENCE ARCHITECTURE - Study patterns for IDE integration

Sources:

5.4 Cursor AI

Description: AI-powered code editor with @codebase feature.

Key Features:

@codebase for semantic code search
Understanding codebases: file finding, execution tracing, class/method usage
MCPs + Rules (.cursor/rules/*.mdc) + Memories
Granular in-editor guidance

Fit with RuVector: 🟡 MODERATE

Commercial product (not directly integratable)
Patterns worth studying for UX

Recommendation: REFERENCE ONLY - Study @codebase feature UX

Sources:

6. Visualization & Developer Experience

6.1 Mermaid.js ⭐ HIGHLY RECOMMENDED

Description: JavaScript diagramming tool with Markdown-inspired syntax.

Key Features:

71.8k+ GitHub stars (mermaid-js/mermaid)
Native rendering in GitHub, GitLab markdown
Diagram-as-Code: Flowcharts, sequence, class, ER diagrams
47% increase in diagram-as-code adoption since 2021
Teams using it are 2.4x more likely to implement continuous docs

Fit with RuVector: 🟢 EXCELLENT

Generate diagrams from knowledge graph relationships
Visualize code structure, dependencies, call graphs
Embed in documentation automatically
No server required (browser-based)

Integration:

// Generate Mermaid diagram from graph relationships
const generateClassDiagram = (graphData) => {
  let mermaid = 'classDiagram\n';

  graphData.classes.forEach(cls => {
    mermaid += `  class ${cls.name} {\n`;
    cls.methods.forEach(m => {
      mermaid += `    +${m.name}()\n`;
    });
    mermaid += `  }\n`;
  });

  graphData.relationships.forEach(rel => {
    mermaid += `  ${rel.from} ${rel.type} ${rel.to}\n`;
  });

  return mermaid;
};

// Example output:
// classDiagram
//   class AuthService {
//     +login()
//     +logout()
//   }
//   class UserService {
//     +getUser()
//   }
//   AuthService --> UserService : uses

Use Cases:

Auto-generate architecture diagrams from code graph
Visualize dependencies in pull requests
Document API relationships
Show test coverage relationships

Recommendation: ADOPT IN PHASE 2 - Essential for visualization

Sources:

6.2 Graphviz

Description: Graph visualization tool with DOT language.

Key Features:

Mature ecosystem: Python, Java, JavaScript bindings
Advanced layout algorithms (dot, neato, fdp, circo)
Full control over styling
Mission-critical systems use it

Fit with RuVector: 🟢 GOOD

More powerful for complex dependency graphs
Better for algorithmic layout control
Export as images (PNG, SVG)

When to Choose:

Mermaid: Quick diagrams, GitHub/GitLab integration, stakeholder-friendly
Graphviz: Complex layouts, deterministic positioning, detailed customization

Recommendation: PHASE 3 OPTION - Use Mermaid first, add Graphviz for complex visualizations

Sources:

Mermaid vs Graphviz Comparison

6.3 D3.js

Description: Data visualization library for web-based interactive graphics.

Key Features:

Treemaps, force-directed graphs, Voronoi, contours
Interactive behaviors: panning, zooming, brushing, dragging
Encodes data as visual properties (position, size, color)
Canvas or SVG rendering

Fit with RuVector: 🟡 MODERATE

Powerful for interactive graph exploration
More complex than Mermaid (requires JavaScript expertise)
Better for web dashboards than documentation

Note: Mermaid uses D3 and dagre-d3 under the hood

Recommendation: PHASE 3 OPTION - For custom interactive dashboards

Sources:

7. Vector Database Alternatives (Comparison)

While RuVector uses pgvector, here's how it compares to alternatives:

7.1 Pgvector (Current Choice) ✅

Strengths:

Uses existing PostgreSQL (no new infrastructure)
SQL integration for joins, transactions
ACID guarantees
Mature ecosystem

Limitations:

15x slower than Qdrant at high scale (benchmark)
Performance degrades at 50M+ vectors
Requires tuning for large datasets

Recommendation: KEEP FOR NOW - Optimize with indices, consider scaling strategies

7.2 Qdrant

Strengths:

Best open-source performance with filtering
Designed for billion-scale datasets
Horizontal scalability
Excellent filtering capabilities

Limitations:

Performance degrades at 50M+ vectors (471 QPS vs 41 QPS)
Separate database infrastructure

Fit: 🟡 MODERATE - Consider if scaling beyond 10M vectors

7.3 Milvus

Strengths:

35k+ GitHub stars - most popular open-source vector DB
Handles billions of vectors efficiently
Most indexing strategies: IVF, HNSW, DiskANN
Distributed deployments on Kubernetes

Limitations:

Complex setup and operations
Higher overhead than pgvector

Fit: 🟡 MODERATE - Overkill for most use cases, consider at massive scale

Performance Comparison Table

Database	Scale	QPS (50M vectors)	Setup Complexity	SQL Integration
pgvector	<10M	~471	⭐ Easy	✅ Native
Qdrant	<50M	~41	⭐⭐ Moderate	❌ API only
Milvus	Billions	High	⭐⭐⭐ Complex	❌ API only

Recommendation: Stick with pgvector + optimize - Only migrate if hitting 10M+ vector scale

Sources:

8. Tool Recommendation Matrix

Category × Tool Comparison

Category	Tool	Fit	License	Maturity	Performance	Priority
AST Parsing	Tree-sitter	🟢	MIT	⭐⭐⭐	36x faster	P1
	SWC	🟡	Apache 2.0	⭐⭐⭐	70x faster	P2
	ts-morph	🟢	MIT	⭐⭐⭐	Good	Current
Code Analysis	Semgrep	🟢	LGPL	⭐⭐⭐	Fast	P2
	CodeQL	🟡	MIT	⭐⭐⭐	Slow	P3
	SeaGOAT	🟡	MIT	⭐	Moderate	Reference
Graph DB	Apache AGE	🟢	Apache 2.0	⭐⭐⭐	Good	P1
	DuckPGQ	🔴	MIT	⭐⭐	Fast	Skip
	TypeDB	🟡	AGPL	⭐⭐⭐	Good	P3
	Oxigraph	🔴	MIT/Apache	⭐⭐⭐	Good	Skip
Embeddings	nomic-embed	🟢	Apache 2.0	⭐⭐⭐	86% acc	P1
	BGE-M3	🟢	Apache 2.0	⭐⭐⭐	Balanced	Alt
	all-MiniLM	🟡	Apache 2.0	⭐⭐⭐	Fast, -5%	Fallback
	StarEncoder	🟢	Apache 2.0	⭐⭐	Good	P2
Chunking	AST-based	🟢	N/A	⭐⭐	+5.5 pts	P1
	cAST/ASTChunk	🟢	MIT	⭐⭐	+5.5 pts	P1
Search	Hybrid (BM25+Vec)	🟢	N/A	⭐⭐⭐	40% better	P2
Change Detection	Git-based	🟢	N/A	⭐⭐⭐	0-10s	P1
	e-dant/watcher	🟢	MIT	⭐⭐⭐	Fast	P2
	fswatch	🟢	GPL	⭐⭐⭐	Good	Alt
Monorepo	Nx	🟢	MIT	⭐⭐⭐	7x faster	P2
	Turborepo	🟢	MIT	⭐⭐⭐	Good	Alt
RAG Framework	LlamaIndex	🟢	MIT	⭐⭐⭐	40% faster	P2
	LangChain	🟡	MIT	⭐⭐⭐	Good	P3
	Continue	🟢	Apache 2.0	⭐⭐	Good	Reference
Visualization	Mermaid.js	🟢	MIT	⭐⭐⭐	Fast	P2
	Graphviz	🟢	EPL	⭐⭐⭐	Good	P3
	D3.js	🟡	ISC	⭐⭐⭐	Interactive	P3
Vector DB	pgvector	🟢	PostgreSQL	⭐⭐⭐	<10M scale	Current
	Qdrant	🟡	Apache 2.0	⭐⭐⭐	<50M scale	Future
	Milvus	🟡	Apache 2.0	⭐⭐⭐	Billions	Future

Legend:

🟢 Excellent fit | 🟡 Moderate fit | 🔴 Poor fit
⭐⭐⭐ Production-ready | ⭐⭐ Stable | ⭐ Early-stage
P1 Phase 1 (Core) | P2 Phase 2 (Enhancement) | P3 Phase 3 (Advanced)

9. Top 10 Recommendations

Priority 1 (Core - Adopt Immediately)

Tree-sitter - Multi-language incremental AST parsing
- Why: 36x faster, 40+ languages, incremental updates
- Impact: Foundation for multi-language support
Apache AGE - PostgreSQL graph extension
- Why: Native Cypher queries on existing database
- Impact: Powerful relationship traversal without new infrastructure
nomic-embed-text - Local code embeddings
- Why: 8192 token context, 86% accuracy, local deployment
- Impact: Superior embeddings without API costs
AST-Based Chunking - Semantic code chunking
- Why: +5.5 points on RepoEval, preserves code structure
- Impact: Essential for quality embeddings
Git-Based Change Detection - Incremental indexing
- Why: Only re-index changed files, 0-10s execution
- Impact: Scalability at large codebase sizes

Priority 2 (Enhancement - Adopt Next Quarter)

LlamaIndex - RAG framework for code
- Why: 40% faster retrieval, 150+ data connectors
- Impact: Production-ready retrieval system
Hybrid Search (BM25 + Vector) - Combined retrieval
- Why: Best of keyword + semantic search
- Impact: 40% accuracy improvement
Semgrep - Fast SAST for code quality
- Why: Zero false positives, graph relationship enrichment
- Impact: Security/quality edges in knowledge graph
e-dant/watcher - File system monitoring
- Why: Near-zero overhead, real-time local updates
- Impact: Developer experience for local indexing
Mermaid.js - Code visualization
- Why: 71k stars, native GitHub integration
- Impact: Auto-generate docs from graph

Priority 3 (Advanced - Evaluate Later)

Nx/Turborepo - If using monorepo structure
CodeQL - Advanced security graph relationships
TypeDB - Complex reasoning requirements
Graphviz - Custom complex visualizations
LangChain - Multi-agent workflows beyond retrieval

10. Integration Architecture

Phase 1: Foundation (Months 1-2)

┌─────────────────────────────────────────────────────────────┐
│                    Code Repository (Git)                     │
└──────────────┬──────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│               Incremental Change Detection                    │
│  • Git-based diff (tj-actions/changed-files)                 │
│  • File watcher (e-dant/watcher) for local dev               │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│                  Multi-Language Parsing                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │ Tree-sitter │  │  ts-morph   │  │   Serena    │          │
│  │  (Multi)    │  │   (TS/JS)   │  │    (LSP)    │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│                   AST-Based Chunking                          │
│  • cAST algorithm (recursive split, sibling merge)           │
│  • Preserve function/class boundaries                        │
│  • 256-512 tokens, 10-20% overlap                            │
│  • Metadata: file, class, function context                   │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│                  Embedding Generation                         │
│  • nomic-embed-text (8192 context, local)                    │
│  • Batch processing for efficiency                           │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│              PostgreSQL (RuVector Core)                       │
│  ┌──────────────────────┐  ┌──────────────────────┐          │
│  │   pgvector tables    │  │   Apache AGE graph   │          │
│  │  • code_chunks       │  │  • Files, Classes    │          │
│  │  • embeddings        │  │  • Methods, Imports  │          │
│  │  • vector indices    │  │  • Relationships     │          │
│  └──────────────────────┘  └──────────────────────┘          │
└──────────────────────────────────────────────────────────────┘

Phase 2: Enhancement (Months 3-4)

┌──────────────────────────────────────────────────────────────┐
│                   PostgreSQL + Extensions                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │  pgvector    │  │ Apache AGE   │  │  tsvector    │        │
│  │  (Vector)    │  │   (Graph)    │  │   (BM25)     │        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│                     Hybrid Retrieval                          │
│  ┌─────────────────────────────────────────────────┐          │
│  │  Query Processing                               │          │
│  │  • Keyword extraction → BM25                    │          │
│  │  • Semantic embedding → Vector search           │          │
│  │  • Graph context → Cypher traversal             │          │
│  └─────────────────────────────────────────────────┘          │
│  ┌─────────────────────────────────────────────────┐          │
│  │  Fusion (Reciprocal Rank Fusion)                │          │
│  │  • Normalize scores                             │          │
│  │  • Weight: 40% BM25 + 60% vector                │          │
│  │  • RRF: Σ 1/(k + rank_i)                        │          │
│  └─────────────────────────────────────────────────┘          │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│                    LlamaIndex RAG                             │
│  • Query engines with adaptive retrieval                     │
│  • Context filtering by language, file, module               │
│  • Observability and evaluation metrics                      │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│                  Code Quality Enrichment                      │
│  ┌─────────────────┐  ┌─────────────────┐                    │
│  │    Semgrep      │  │  Monorepo Tools │                    │
│  │  (Security)     │  │   (Nx/Turbo)    │                    │
│  │  • Patterns     │  │  • Dependencies │                    │
│  │  • Anti-patterns│  │  • Build graph  │                    │
│  └─────────────────┘  └─────────────────┘                    │
│         │                      │                              │
│         └──────────┬───────────┘                              │
│                    ▼                                          │
│         Graph Relationships (SECURES, DEPENDS_ON)            │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│                      Visualization                            │
│  • Mermaid.js diagrams (auto-generated)                      │
│  • GitHub/GitLab integration                                 │
│  • PR documentation enrichment                               │
└──────────────────────────────────────────────────────────────┘

Phase 3: Advanced (Months 5-6)

┌──────────────────────────────────────────────────────────────┐
│                  Advanced Query Layer                         │
│  ┌─────────────────────────────────────────────────┐          │
│  │  Multi-Modal Retrieval                          │          │
│  │  • Code (vector)                                │          │
│  │  • Documentation (vector)                       │          │
│  │  • Test coverage (graph)                        │          │
│  │  • Security findings (graph)                    │          │
│  │  • Build dependencies (graph)                   │          │
│  └─────────────────────────────────────────────────┘          │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│                     Agent Workflows                           │
│  • LangChain for multi-step analysis                         │
│  • Code explanation agents                                   │
│  • Refactoring suggestion agents                             │
│  • Test generation agents                                    │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│                  Interactive Dashboard                        │
│  • D3.js force-directed graph explorer                       │
│  • Real-time dependency visualization                        │
│  • Code metrics and quality trends                           │
│  • Search interface with filters                             │
└──────────────────────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────┐
│                    IDE Integrations                           │
│  • VS Code extension (Continue patterns)                     │
│  • MCP servers for external tools                            │
│  • Inline code suggestions from graph                        │
└──────────────────────────────────────────────────────────────┘

11. Implementation Priority

Month 1-2: Foundation

✅ Git-based change detection pipeline
✅ Tree-sitter integration for multi-language parsing
✅ AST-based chunking implementation
✅ nomic-embed-text local deployment
✅ Apache AGE graph schema design
✅ Incremental indexing workflow

Expected Outcomes:

Multi-language support (40+ languages)
Incremental updates (<10s for changed files)
Quality embeddings with semantic chunking
Graph relationships (IMPORTS, EXTENDS, CALLS)

Month 3-4: Enhancement

✅ Hybrid search (BM25 + vector) implementation
✅ LlamaIndex RAG framework integration
✅ Semgrep analysis for code quality edges
✅ e-dant/watcher for local development
✅ Mermaid.js visualization generation
✅ Query optimization and performance tuning

Expected Outcomes:

40% retrieval accuracy improvement
Fast local development workflow
Security/quality graph enrichment
Auto-generated documentation diagrams

Month 5-6: Advanced

⬜ LangChain agents for code analysis
⬜ D3.js interactive graph dashboard
⬜ IDE extension (VS Code)
⬜ CodeQL integration for deep analysis
⬜ Advanced reasoning (optional: TypeDB)
⬜ Performance benchmarking and scaling

Expected Outcomes:

Multi-agent code analysis workflows
Interactive visualization dashboard
Seamless IDE integration
Production-ready scalability

12. Risk Assessment

Technical Risks

Risk	Impact	Mitigation
Multi-language parser complexity	High	Start with Tree-sitter for top 5 languages, expand gradually
pgvector performance at scale	High	Monitor at 1M, 5M, 10M vectors; plan migration to Qdrant if needed
Apache AGE maturity	Medium	v1.1.0+ stable; test thoroughly; have fallback to pure SQL
Embedding model drift	Low	Pin nomic-embed-text version; version embeddings table
AST chunking edge cases	Medium	Extensive testing; fallback to line-based for failures
Hybrid search complexity	Medium	Start with simple weighted fusion; iterate to RRF

Operational Risks

Risk	Impact	Mitigation
Incremental indexing failures	High	Robust error handling; full re-index fallback; monitoring
Graph schema evolution	Medium	Migration scripts; schema versioning; backward compatibility
Embedding storage growth	High	Matryoshka dimensions (768→256); archival strategy
Dependencies maintenance	Medium	Pin versions; automated dependency updates; security scanning

Cost Considerations

Component	Cost	Optimization
Embeddings (nomic-embed)	$0	Local deployment (free)
Vector storage (pgvector)	Low	PostgreSQL existing infrastructure
Graph storage (Apache AGE)	$0	Extension on existing PostgreSQL
Compute (parsing)	Medium	Incremental updates reduce load
Monitoring/observability	Low	Open-source tools (Prometheus, Grafana)

Total Estimated Cost: Minimal infrastructure overhead vs managed services

13. Success Metrics

Performance KPIs

Metric	Baseline	Target (Phase 1)	Target (Phase 2)
Query latency	N/A	<50ms (p95)	<10ms (p95)
Indexing time (1K files)	N/A	<5 min	<2 min (incremental)
Retrieval accuracy	N/A	75% MRR	85% MRR
Vector storage per file	N/A	<10KB	<5KB (Matryoshka)
Graph traversal (3 hops)	N/A	<100ms	<50ms

Developer Experience KPIs

Metric	Target
Time to find code	<30 seconds (vs 5+ min manual search)
Context accuracy	>80% relevant results in top 5
Local indexing delay	<10s after file save
Documentation freshness	Auto-update on commit

Business KPIs

Metric	Target
LLM context reduction	50% fewer tokens via better retrieval
Development velocity	20% faster code navigation
Codebase understanding	Onboarding time reduced 30%
Documentation coverage	100% auto-generated diagrams

14. Conclusion

Recommended Technology Stack

Core Stack (Phase 1):
  Parsing:
    - Tree-sitter (multi-language, 40+ grammars)
    - ts-morph (TypeScript/JavaScript deep analysis)
    - Serena (LSP-based symbol extraction)

  Graph Database:
    - Apache AGE (PostgreSQL extension, Cypher queries)

  Vector Database:
    - pgvector (existing PostgreSQL)

  Embeddings:
    - nomic-embed-text (local, 8192 context)

  Chunking:
    - AST-based with cAST algorithm

  Indexing:
    - Git-based change detection (tj-actions/changed-files)
    - e-dant/watcher (local development)

Enhancement Stack (Phase 2):
  RAG Framework:
    - LlamaIndex (code retrieval optimized)

  Search:
    - Hybrid (BM25 + vector with RRF)

  Code Quality:
    - Semgrep (SAST, graph enrichment)

  Visualization:
    - Mermaid.js (auto-generated diagrams)

  Monorepo (if applicable):
    - Nx (dependency graphs)

Advanced Stack (Phase 3):
  Agents:
    - LangChain (multi-step workflows)

  Security:
    - CodeQL (deep semantic analysis)

  Visualization:
    - D3.js (interactive dashboards)

  Reasoning (optional):
    - TypeDB (complex inference)

Key Architectural Decisions

PostgreSQL-First: Apache AGE extends existing database vs separate graph DB
Local Embeddings: nomic-embed-text eliminates API costs and privacy concerns
Incremental Everything: Git-based + file watcher for scalable updates
AST-Aware: Structure-preserving chunking for quality embeddings
Hybrid Retrieval: Best of keyword + semantic search

Next Steps

Immediate (Week 1):
- Set up Tree-sitter for top 3 languages (TypeScript, Python, Go)
- Deploy Apache AGE extension on PostgreSQL
- Install nomic-embed-text locally via Ollama
Short-term (Month 1):
- Implement AST-based chunking pipeline
- Build git-based incremental indexing workflow
- Design Apache AGE graph schema (Files, Classes, Methods, Relationships)
Medium-term (Month 2-3):
- Integrate LlamaIndex for RAG
- Add hybrid search (BM25 + vector)
- Deploy Mermaid.js diagram generation
Long-term (Month 4-6):
- Build interactive visualization dashboard
- Create VS Code extension
- Implement multi-agent analysis workflows

Resources & References

All sources are embedded inline throughout the document as hyperlinks.

Key resource categories:

AST Parsing: Tree-sitter, SWC documentation
Graph Databases: Apache AGE, DuckPGQ guides
Embeddings: nomic-embed, BGE model papers
RAG Frameworks: LlamaIndex, LangChain comparisons
Hybrid Search: BM25 + vector fusion techniques
Visualization: Mermaid.js, Graphviz comparisons
Vector DBs: pgvector, Qdrant, Milvus benchmarks

Report Generated: December 21, 2025 Research Agent: Agentic QE Research Specialist Version: 1.0 Status: Ready for implementation planning

60 KiB Raw Permalink Blame History Unescape Escape

RuVector Knowledge Graph Complementary Tools - Research Report 2025

Executive Summary

Top 5 Recommendations

Architecture Evolution

1. Code Intelligence & Understanding

1.1 Tree-sitter ⭐ HIGHLY RECOMMENDED

1.2 SWC (Speedy Web Compiler)

1.3 CodeQL

1.4 Semgrep ⭐ RECOMMENDED

1.5 SeaGOAT

2. Knowledge Graph & Graph Databases

2.1 Apache AGE ⭐ HIGHLY RECOMMENDED

2.2 DuckPGQ (DuckDB Graph Extension)

2.3 TypeDB

2.4 Oxigraph + RDFLib

3. Embedding & Vector Models

3.1 nomic-embed-text ⭐ HIGHLY RECOMMENDED

3.2 BGE (BAAI General Embedding)

3.3 all-MiniLM-L6-v2

3.4 Code-Specific Models

Voyage Code-3 (Commercial)

StarCoder/StarEncoder (Open-Source)

3.5 AST-Based Chunking Strategy ⭐ CRITICAL

3.6 Hybrid Search (BM25 + Vector) ⭐ RECOMMENDED

4. Indexing & Incremental Updates

4.1 Git-Based Change Detection ⭐ RECOMMENDED

4.2 File Watchers

e-dant/watcher ⭐ RECOMMENDED

fswatch

4.3 Monorepo Build Tools

Nx vs Turborepo

5. RAG Frameworks for Code

5.1 LlamaIndex ⭐ HIGHLY RECOMMENDED

5.2 LangChain

5.3 Continue Dev

5.4 Cursor AI

6. Visualization & Developer Experience

6.1 Mermaid.js ⭐ HIGHLY RECOMMENDED

6.2 Graphviz

6.3 D3.js

7. Vector Database Alternatives (Comparison)

7.1 Pgvector (Current Choice) ✅

7.2 Qdrant

7.3 Milvus

Performance Comparison Table

8. Tool Recommendation Matrix

Category × Tool Comparison

9. Top 10 Recommendations

Priority 1 (Core - Adopt Immediately)

Priority 2 (Enhancement - Adopt Next Quarter)

Priority 3 (Advanced - Evaluate Later)

10. Integration Architecture

Phase 1: Foundation (Months 1-2)

Phase 2: Enhancement (Months 3-4)

Phase 3: Advanced (Months 5-6)

11. Implementation Priority

Month 1-2: Foundation

Month 3-4: Enhancement

Month 5-6: Advanced

12. Risk Assessment

Technical Risks

Operational Risks

Cost Considerations

13. Success Metrics

Performance KPIs

Developer Experience KPIs

Business KPIs

14. Conclusion

Recommended Technology Stack

Key Architectural Decisions

Next Steps

Resources & References

60 KiB

Raw Permalink Blame History