RepoNova

  Your Codebase                      reponova build                         AI Agent
  ─────────────                      ──────────────                         ────────

  Python ¹                           1. tree-sitter AST parsing             graph_search
  Markdown / Docs    ──────────►     2. Symbol + edge extraction        ──► graph_impact
  Diagrams / SVG                     3. Louvain communities            g    raph_path
  Multi-repo                         4. TF-IDF / ONNX / API embeddings      graph_similar
                                     5. Community summaries
                                     6. HTML visualizations                 ... (11 tools)

npm install -g reponova

npx reponova

reponova install --target opencode

reponova build

You: "What would be the impact of refactoring the authenticate function?"
Agent: [calls graph_impact] → shows upstream/downstream blast radius across repos

1. graph_impact "TargetFunction" → understand blast radius
2. graph_path "ModuleA" "ModuleB" → see dependency chain
3. graph_community 5 → understand the module cluster
4. Make changes with full structural awareness

1. graph_status → understand graph size and repos
2. graph_hotspots → identify architectural pillars
3. graph_search "authentication" → find entry points
4. graph_explain "Function:authenticate" → deep dive

1. graph_search "X" → find the node
2. graph_impact "X" direction=downstream → who depends on it
3. graph_similar "X" → find semantically related code

# Incremental rebuild — only processes changed files
reponova build

# Force rebuild — ignores all caches, reruns every phase
reponova build --force

reponova install --target <editor> [--graph <path>]

reponova build [--config <path>] [--force] [--target <phase>]

reponova build --target index       # file-detection → graph → communities → index
reponova build --target outlines    # file-detection → outlines
reponova build --target html        # file-detection → graph → communities → community-summaries → node-descriptions → html
reponova build --target embeddings  # file-detection → graph → communities → community-summaries → node-descriptions → embeddings

Level 0: file-detection
Level 1: graph, outlines                                       (parallel)
Level 2: communities
Level 3: community-summaries, node-descriptions, search-index  (parallel)
Level 4: embeddings, html, report                              (parallel)

reponova mcp [--graph <path>]

reponova models status              # Show configured and cached models
reponova models download            # Pre-download all models needed by config
reponova models remove <name>       # Remove a specific cached model
reponova models clear               # Remove all cached models

reponova check [--graph <path>]

src/core.py
src/utils/helpers.py
tests/test_core.py

repos:
  - name: my-project
    path: .
patterns: ["src/**/*.py"]            # matches src/core.py ✓
exclude: ["tests/**"]                # excludes tests/test_core.py ✓

api/src/routes.py          # ← "api" comes from repos[].name
api/src/handlers.py
core/src/models.py         # ← "core" comes from repos[].name
core/src/db.py

repos:
  - name: api
    path: ../services/api
  - name: core
    path: ../services/core
patterns: ["src/**/*.py"]            # matches api/src/routes.py, api/src/handlers.py, core/src/models.py, core/src/db.py ✓ (via repo-relative)
exclude: ["**/test_*.py"]            # works across all repos

exclude:
  - "api/src/generated/**"           # excludes only in the api repo
  - "**/migrations/**"               # excludes in all repos

# ──────────────────────────────────────────────────────────────────────────────
# reponova.yml — Full Configuration Reference
# ──────────────────────────────────────────────────────────────────────────────

# Where to write build output (graph.json, graph.html, graph_search.db, etc.)
# Type: string
# Default: "reponova-out"
output: ../reponova-out

# ── Repositories ──────────────────────────────────────────────────────────────
# List of repositories to include in the build.
# Each repo needs a unique name and a path (relative to this config file).
repos:
  - name: api-service           # string — unique identifier for this repo
    path: ../services/api       # string — path to repo root (relative to this file)
  - name: core-lib
    path: ../services/core

# ── Providers (optional — AI backends) ────────────────────────────────────────
# Define named providers here, then reference them from features below.
# Default (no provider) = algorithmic mode (TF-IDF embeddings, rule-based summaries).
# Type: Record<string, ProviderConfig>
# Default: {} (empty — fully algorithmic)
# providers:
#   my-openai:
#     type: openai                  # "openai" (remote), "llama-cpp" (local LLM), "onnx" (local embeddings)
#     base_url: https://api.openai.com/v1
#     model: text-embedding-3-small
#     api_key: ${OPENAI_API_KEY}    # env var reference (resolved at runtime)
#     timeout: 30                   # seconds (default: 30)
#   local-llm:
#     type: llama-cpp
#     model: "hf:Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q4_K_M"
#     context_size: 512
#   local-embeddings:
#     type: onnx
#     model: all-MiniLM-L6-v2
#   ollama:
#     type: openai                  # Ollama is OpenAI-compatible
#     base_url: http://localhost:11434/v1
#     model: nomic-embed-text

# ── Centralized Model Management ─────────────────────────────────────────────
# Shared settings for local AI models (ONNX embeddings + GGUF LLM weights).
# These apply to providers of type "onnx" and "llama-cpp".
models:
  # Directory to cache downloaded models (ONNX embeddings + LLM weights)
  # Type: string
  # Default: "~/.cache/reponova/models"
  cache_dir: ~/.cache/reponova/models

  # GPU acceleration backend for LLM inference
  # Values: "auto" | "cpu" | "cuda" | "metal" | "vulkan"
  #   - auto:    auto-detect best available backend
  #   - cpu:     force CPU inference (slower but always works)
  #   - cuda:    NVIDIA GPU (requires CUDA drivers)
  #   - metal:   Apple Silicon GPU (macOS only)
  #   - vulkan:  Cross-platform GPU (AMD, Intel, NVIDIA)
  # Default: "auto"
  gpu: auto

  # Number of CPU threads for LLM inference
  # Type: number
  # Default: 0 (auto-detect based on available cores)
  threads: 0

  # Automatically download models on first use
  # Type: boolean
  # Default: true
  download_on_first_use: true

# ── Source Code File Filters ──────────────────────────────────────────────────
# Shared by graph + outlines — a single file-detection phase produces
# the file list consumed by both.

# Glob patterns for source code files to include
# Type: string[]
# Default: [] (empty = auto-detect by file extension using registered extractors)
# Example: ["src/**/*.py", "lib/**/*.ts"]
patterns: []

# Glob patterns to exclude from source code detection
# Type: string[]
# Default: []
# Example: ["**/generated/**", "**/*.test.ts", "**/vendor/**"]
exclude: []

# Exclude common non-source directories from all file detection
# (source code, documentation and diagrams).
# When true, the following directories are skipped at any depth:
#   node_modules, __pycache__, .git, .svn, .hg, venv, .venv, env, .env, .tox,
#   site-packages, dist, build, .eggs, .mypy_cache, .pytest_cache, .ruff_cache,
#   target, bin, obj
# Set to false if you need to index files inside these directories
# (e.g. vendored code in node_modules). You can still exclude specific
# directories via the `exclude` patterns above.
# Type: boolean
# Default: true
exclude_common: true

# Incremental builds: only re-process files whose SHA256 hash changed
# Type: boolean
# Default: true
incremental: true

# ── Documentation Extraction ─────────────────────────────────────────────────
docs:
  # Enable/disable documentation extraction
  # Type: boolean
  # Default: true
  enabled: true

  # Glob patterns for documentation files (relative to repo root)
  # Type: string[]
  # Default: [] (empty = auto-detect by file extension: .md, .txt, .rst)
  # Example: ["docs/**/*.md", "**/*.rst"]
  patterns: []

  # Glob patterns to exclude from documentation extraction
  # Type: string[]
  # Default: []
  # Example: ["**/CHANGELOG.md", "**/node_modules/**"]
  exclude: []

  # Maximum file size in KB — files larger than this are skipped
  # Type: number
  # Default: 500
  max_file_size_kb: 500

# ── Diagram / Image Extraction ───────────────────────────────────────────────
images:
  # Enable/disable diagram extraction
  # Type: boolean
  # Default: true
  enabled: true

  # Glob patterns for diagram files (relative to repo root)
  # Type: string[]
  # Default: [] (empty = auto-detect by file extension: .puml, .plantuml, .svg, .png, .jpg, .jpeg, .gif)
  # Example: ["diagrams/**/*.puml", "**/*.svg"]
  patterns: []

  # Glob patterns to exclude
  # Type: string[]
  # Default: []
  # Example: ["**/node_modules/**"]
  exclude: []

  # Parse PlantUML files to extract components and relationships
  # Type: boolean
  # Default: true
  parse_puml: true

  # Extract text content from SVG files
  # Type: boolean
  # Default: true
  parse_svg_text: true

# ── Embeddings ────────────────────────────────────────────────────────────────
# Vector representations for semantic search (graph_similar, graph_context)
# Default (no provider): TF-IDF (384-dim, fast, no download required)
# With provider: uses the named provider for embedding generation
embeddings:
  # Enable/disable embedding generation
  # Type: boolean
  # Default: true
  enabled: true

  # Reference a named provider from the `providers` section above
  # When omitted: uses built-in TF-IDF (384-dim, no download)
  # Type: string | undefined
  # Default: (none — algorithmic TF-IDF)
  # provider: my-openai

  # Batch size for embedding generation
  # Type: number
  # Default: 128
  batch_size: 128

# ── Community Summaries ───────────────────────────────────────────────────────
# Natural-language summaries for each detected community (cluster of related symbols).
# Independent from node descriptions — can enable one without the other.
# Default (no provider): algorithmic summaries (rule-based, still useful)
# With provider: uses LLM for richer natural-language summaries
community_summaries:
  # Enable/disable community summary generation
  # Type: boolean
  # Default: true
  enabled: true

  # Maximum number of communities to summarize
  # Type: integer (>= 0)
  # Default: 0 (no limit — summarize all communities)
  # Communities are sorted by size (largest first). When max_number > 0,
  # only the top N largest communities are summarized.
  # Communities with fewer than 3 nodes are always excluded.
  max_number: 0

  # Provider name — references a provider defined in the top-level `providers` map
  # When omitted: uses algorithmic summaries (rule-based)
  # The referenced provider must be type "openai" or "llama-cpp" (LLM-capable)
  # Type: string (optional)
  # provider: local-llm

# ── Node Descriptions ────────────────────────────────────────────────────────
# Natural-language descriptions for high-degree (important) nodes.
# Independent from community summaries — can enable one without the other.
# Default (no provider): algorithmic descriptions
# With provider: uses LLM for richer descriptions
node_descriptions:
  # Enable/disable node description generation
  # Type: boolean
  # Default: true
  enabled: true

  # Degree threshold for node description generation
  # Type: number (0.0 – 1.0)
  # Default: 0.8
  # Meaning: top (1 - threshold)% of nodes by degree get descriptions.
  #   - 0.8 = top 20% of nodes
  #   - 0.5 = top 50% of nodes
  #   - 0.0 = all nodes (expensive!)
  #   - 1.0 = no nodes
  threshold: 0.8

  # Provider name — references a provider defined in the top-level `providers` map
  # When omitted: uses algorithmic descriptions
  # The referenced provider must be type "openai" or "llama-cpp" (LLM-capable)
  # Type: string (optional)
  # provider: local-llm

# ── HTML Visualizations ──────────────────────────────────────────────────────

# Generate interactive HTML visualizations (graph.html + graph_communities.html)
# Type: boolean
# Default: true
html: true

# Minimum node degree to include in HTML visualization
# Useful for large graphs — filters out leaf nodes to reduce clutter
# Type: integer (>= 1)
# Default: not set (include all nodes)
# html_min_degree: 3

# ── Outlines ──────────────────────────────────────────────────────────────────
# Tree-sitter code outlines: functions, classes, imports with signatures.
# Language is auto-detected from file extension (no need to specify it).
# File selection comes from top-level patterns / exclude / exclude_common.
outlines:
  # Enable/disable outline generation
  # Type: boolean
  # Default: true
  enabled: true

# ── Server ────────────────────────────────────────────────────────────────────
# MCP server options (reserved for future use)
# Type: object
# Default: {}
server: {}

output: ../reponova-out
repos:
  - name: my-project
    path: ..

output: ../reponova-out
repos:
  - name: api
    path: ../services/api
  - name: core
    path: ../services/core
  - name: shared
    path: ../libs/shared

output: ../reponova-out
repos:
  - name: my-project
    path: ..
providers:
  local-llm:
    type: llama-cpp
    model: "hf:Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q4_K_M"   # ~350MB download
    context_size: 512
models:
  gpu: auto                 # auto-detect GPU, falls back to CPU
  download_on_first_use: true
community_summaries:
  enabled: true
  provider: local-llm       # use local LLM for richer summaries
node_descriptions:
  enabled: true
  threshold: 0.5            # describe top 50% nodes by degree
  provider: local-llm       # same provider — engine instance is shared

providers:
  openai-embed:
    type: openai
    base_url: https://api.openai.com/v1
    model: text-embedding-3-small
    api_key: ${OPENAI_API_KEY}
  ollama-llm:
    type: openai
    base_url: http://localhost:11434/v1
    model: llama3.2
embeddings:
  enabled: true
  provider: openai-embed
community_summaries:
  enabled: true
  provider: ollama-llm

output: ../reponova-out
repos:
  - name: my-project
    path: ..
patterns:                      # only include files matching these globs
  - "src/**/*.py"
  - "lib/**/*.ts"
exclude:                       # exclude files matching these globs
  - "**/test/**"
  - "**/tests/**"
  - "**/migrations/**"
  - "**/*.generated.ts"

reponova models status              # Show configured and cached models
reponova models download            # Pre-download all models needed by config
reponova models remove <name>       # Remove a specific cached model
reponova models clear               # Remove all cached models

reponova-out/
├── graph.json                                # Full graph: nodes, edges, community assignments, metadata
│                                             #   metadata.build_config: config fingerprint for change detection
│                                             #   nodes include: docstring, signature, bases (when available)
├── graph-nodes.json                          # Intermediate graph (pre-community detection, no Louvain assignments)
├── detected-files.json                       # Detected file list (intermediate, consumed by graph + outlines)
├── graph.html                                # Interactive visualization (vis.js) — click, search, filter
├── graph_communities.html                    # Community-focused visualization with summary labels
├── graph_search.db                           # SQLite search index (sql.js WASM) — structural queries
├── report.md                                 # Build report: stats, hotspots, community breakdown
├── community_summaries.json                  # Community summaries (algorithmic or provider-enhanced)
├── node_descriptions.json                    # Descriptions for high-degree nodes
├── tfidf_idf.json                            # TF-IDF vocabulary weights (for query-time embedding)
├── vectors/                                  # LanceDB vector store — semantic similarity search
│   └── (LanceDB internal files)              #   fallback: vectors.json when @lancedb/lancedb unavailable
├── outlines/                                 # Pre-computed code outlines per file
│   └── <repo>/<path>.outline.json
└── .cache/                                   # Incremental build cache
    ├── hashes.json                           # file path → SHA256 hex map (source code hashing)
    ├── outline-hashes.json                   # file path → SHA256 map for outline generation
    ├── node-texts.json                       # node id → text hash map for incremental embeddings
    ├── graph-nodes-hash.txt                  # SHA256 of graph-nodes.json (skip community detection)
    ├── embeddings-config-hash.txt            # config fingerprint for embeddings phase
    ├── community-summaries-config-hash.txt   # config fingerprint for community summaries phase
    ├── community-summary-fingerprints.json   # per-community content fingerprint (incremental)
    ├── node-descriptions-config-hash.txt     # config fingerprint for node descriptions phase
    ├── node-description-fingerprints.json    # per-node content fingerprint (incremental)
    └── extractions/                          # cached FileExtraction per file
        └── <hash>.json

import { build } from "reponova";

const result = await build("./reponova.yml");
console.log(`Output: ${result.outputDir}`);
console.log(`Total processed: ${result.totalProcessed}`);
for (const [phase, r] of result.phases) {
  console.log(`  ${phase}: ${r.skipped ? `skipped (${r.skipReason})` : `${r.processed} items`}`);
}

// Force rebuild — ignores all caches, reruns every phase
const result = await build("./reponova.yml", { force: true });

import {
  build,
  registerExtractor,
  registerOutlineLanguage,
} from "reponova";
import type { LanguageExtractor, LanguageSupport } from "reponova";

// 1. Register a custom extractor (graph building)
const myExtractor: LanguageExtractor = { /* ... */ };
registerExtractor(myExtractor);

// 2. Register outline support (graph_outline)
const myOutline: LanguageSupport = { /* ... */ };
registerOutlineLanguage("rust", ["rs"], myOutline);

// 3. Build — all registrations are picked up automatically
const result = await build("./reponova.yml");

import {
  openDatabase,
  initializeSchema,
  populateDatabase,
  loadGraphData,
  searchNodes,
  analyzeImpact,
  findShortestPath,
  getNodeDetail,
} from "reponova";

// Load and index the graph
const graphData = loadGraphData("./reponova-out/graph.json");
const db = await openDatabase(":memory:");
initializeSchema(db);
populateDatabase(db, graphData);

// Search
const results = searchNodes(db, "authentication", { top_k: 5, type: "function" });

// Impact analysis
const impact = analyzeImpact(db, "Function:authenticate_user", { max_depth: 3 });

// Shortest path
const path = findShortestPath(db, graphData, "ModuleA", "ModuleB");

// Node detail
const detail = getNodeDetail(db, graphData, "Function:process_payment");

import {
  ContextBuilder,
  loadConfig,
} from "reponova";

// Smart context assembly (search + vectors + graph expansion)
const { config } = loadConfig("./reponova.yml");
const builder = new ContextBuilder(db, graphData, "./reponova-out");
await builder.initialize(config.embeddings);
const context = await builder.buildContext({
  query: "authentication flow",
  maxTokens: 4000,
});

interface LanguageExtractor {
  /** Language identifier — must match tree-sitter grammar name (e.g., "javascript") */
  readonly languageId: string;

  /** File extensions this extractor handles (e.g., [".js", ".mjs", ".cjs"]) */
  readonly extensions: string[];

  /**
   * WASM grammar filename (e.g., "tree-sitter-javascript.wasm").
   * If provided: pipeline parses with tree-sitter and passes the SyntaxTree.
   * If omitted: extract() receives a null tree and must work from sourceCode directly.
   * (Markdown and diagram extractors use this — no WASM needed.)
   */
  readonly wasmFile?: string;

  /**
   * Extract symbols, imports, and references from a single source file.
   * @param tree - Parsed tree-sitter AST (null if wasmFile not set)
   * @param sourceCode - Raw file content
   * @param filePath - Relative path (normalized, forward slashes)
   */
  extract(tree: SyntaxTree | null, sourceCode: string, filePath: string): FileExtraction;

  /**
   * Resolve an import module path to candidate file paths.
   * Example: "config.loader" → ["config/loader.py", "config/loader/__init__.py"]
   * Return empty array for external/third-party modules.
   */
  resolveImportPath(importModule: string, currentFilePath: string): string[];
}

interface FileExtraction {
  filePath: string;           // Relative path (forward slashes)
  language: string;           // Must match languageId
  symbols: SymbolNode[];      // Functions, classes, methods, variables
  imports: ImportDeclaration[];  // Import/export statements
  references: SymbolReference[];  // Calls, type annotations, inheritance refs
}

import { registerExtractor } from "reponova";
import type { LanguageExtractor } from "reponova";

const myExtractor: LanguageExtractor = { /* ... */ };
registerExtractor(myExtractor);

interface LanguageSupport {
  /** WASM grammar filename (e.g., "tree-sitter-python.wasm") */
  readonly wasmFile: string;

  /** Extract outline from tree-sitter AST (primary method) */
  treeSitterExtract(rootNode: SyntaxNode, filePath: string, lineCount: number): FileOutline;

  /** Extract outline from raw source via regex (fallback when WASM unavailable) */
  regexExtract(filePath: string, source: string, lineCount: number): FileOutline;
}

import { registerOutlineLanguage } from "reponova";
import type { LanguageSupport } from "reponova";

const myOutline: LanguageSupport = { /* ... */ };
registerOutlineLanguage("rust", ["rs"], myOutline);