{"id":49503047,"url":"https://github.com/cristianociuti/reponova","last_synced_at":"2026-05-30T10:00:47.491Z","repository":{"id":355005568,"uuid":"1226394607","full_name":"CristianoCiuti/reponova","owner":"CristianoCiuti","description":"Turn your codebase into a knowledge graph. 11 MCP tools for AI code assistants — search, impact analysis, shortest path, semantic similarity, and more.","archived":false,"fork":false,"pushed_at":"2026-05-27T17:14:25.000Z","size":3692,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T17:16:33.507Z","etag":null,"topics":["ai-coding-assistant","claude-code","code-analysis","codebase-search","community-detection","copilot","cursor","dependency-graph","knowledge-graph","mcp","mcp-server","opencode","semantic-search","static-analysis","tree-sitter"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CristianoCiuti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T10:42:00.000Z","updated_at":"2026-05-21T21:29:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CristianoCiuti/reponova","commit_stats":null,"previous_names":["cristianociuti/reponova"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/CristianoCiuti/reponova","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CristianoCiuti%2Freponova","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CristianoCiuti%2Freponova/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CristianoCiuti%2Freponova/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CristianoCiuti%2Freponova/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CristianoCiuti","download_url":"https://codeload.github.com/CristianoCiuti/reponova/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CristianoCiuti%2Freponova/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33687722,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding-assistant","claude-code","code-analysis","codebase-search","community-detection","copilot","cursor","dependency-graph","knowledge-graph","mcp","mcp-server","opencode","semantic-search","static-analysis","tree-sitter"],"created_at":"2026-05-01T13:05:33.371Z","updated_at":"2026-05-30T10:00:47.471Z","avatar_url":"https://github.com/CristianoCiuti.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/npm/v/reponova?style=flat-square\u0026color=cb3837\u0026logo=npm\" alt=\"npm version\" /\u003e\n  \u003cimg src=\"https://img.shields.io/npm/dm/reponova?style=flat-square\u0026color=blue\" alt=\"npm downloads\" /\u003e\n  \u003cimg src=\"https://img.shields.io/node/v/reponova?style=flat-square\u0026color=339933\u0026logo=node.js\u0026logoColor=white\" alt=\"node version\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/CristianoCiuti/reponova?style=flat-square\u0026color=green\" alt=\"license\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/MCP-compatible-8A2BE2?style=flat-square\" alt=\"MCP compatible\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/reponova-social.jpg\" alt=\"RepoNova\" width=\"600\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e🤖 RepoNova 🔭\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eTurn your codebase into a knowledge graph. Query it with AI.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\" style=\"font-style: italic;\"\u003e\n  Knowledge graph builder \u0026amp; \u003ca href=\"https://modelcontextprotocol.io/\"\u003eMCP\u003c/a\u003e server for AI code assistants.\u003cbr/\u003e\n  Extracts symbols, relationships, and semantics from your code — then exposes the entire structure\u003cbr/\u003e\n  as 11 graph tools that any MCP-compatible agent can use.\n\u003c/p\u003e\n\n---\n\n\u003e **⚠️ Alpha — Active Development**\n\u003e APIs, config format, and CLI may change between releases.\n\u003e Already usable in production workflows. [Open an issue](https://github.com/CristianoCiuti/reponova/issues) if something doesn't work.\n\n---\n\n## Why RepoNova?\n\nAI agents read files one at a time. They don't understand how your codebase fits together — which functions call what, which modules depend on which, where the architectural bottlenecks are.\n\n**RepoNova fixes that.** It builds a persistent knowledge graph of your entire codebase (or multiple repos) and gives your AI agent 11 specialized tools to query it: search, impact analysis, shortest path, semantic similarity, community detection, and more.\n\n\u003e **One build. Persistent graph. Instant queries across sessions.**\n\u003e No re-reading files. No burning tokens on context. The graph remembers everything.\n\n### What makes it different\n\n- **Zero external dependencies** — no Python, no Docker, no database servers. Pure Node.js\n- **Multi-repo support** — build one graph spanning multiple repositories\n- **Smart incremental builds** — SHA256 file hashing, per-phase config change detection\n- **Intelligent enrichment** — your AI agent or a configured LLM provider generates architectural descriptions, community profiles, and routing decisions\n- **11 MCP tools** — from text search to weighted Dijkstra, semantic similarity to structural queries\n- **Works with any AI coding agent** — OpenCode, Cursor, Claude Code, VS Code Copilot\n\n---\n\n## How it works\n\n```\n  Your Codebase                      /reponova-enrich                             AI Agent\n  ─────────────                      ────────────────                             ────────\n\n  Python ¹                           1. tree-sitter AST parsing                   graph_search\n  Markdown / Docs    ──────────►     2. Symbol + edge extraction        ──────►   graph_impact\n  Diagrams / SVG                     3. Louvain communities                       graph_path\n  Multi-repo                         4. Enrichment (summaries + descriptions)     graph_similar\n                                     5. TF-IDF / ONNX / API embeddings\n                                     6. HTML visualizations                       ... (11 tools)\n```\n\n¹ More languages coming soon — [contributing](#contributing).\n\n---\n\n## Quick Start\n\n### 1. Install into your editor\n\n```bash\nreponova install --target opencode\n```\n\nSupported targets: `opencode`, `cursor`, `claude`, `vscode`\n\nArtifacts installed per editor:\n\n| Editor | MCP Config | Hook / Plugin | MCP Skill | Enrich Command | Config |\n|--------|-----------|---------------|-----------|----------------|--------|\n| OpenCode | `.opencode/opencode.json` | `.opencode/plugins/reponova.js` | `.opencode/skills/reponova-mcp/SKILL.md` | `.opencode/commands/reponova-enrich.md` | `.opencode/reponova.yml` |\n| Cursor | `.cursor/mcp.json` | `.cursor/rules/reponova-mcp.mdc` | *(embedded in rule)* | `.cursor/commands/reponova-enrich.md` | `.cursor/reponova.yml` |\n| Claude Code | `claude mcp add` (manual) | `.claude/settings.json` (PreToolUse) | `.claude/skills/reponova-mcp/SKILL.md` | `.claude/skills/reponova-enrich/SKILL.md` | `.claude/reponova.yml` |\n| VS Code | `.vscode/mcp.json` | *(skill auto-loads)* | `.github/skills/reponova-mcp/SKILL.md` | `.github/skills/reponova-enrich/SKILL.md` | `.vscode/reponova.yml` |\n\n### 2. Build and enrich the graph\n\nType `/reponova-enrich` in your editor. This single command handles the entire pipeline:\n\n- Builds the structural graph (file detection, AST parsing, community detection)\n- Generates architectural node descriptions\n- Profiles communities with meaningful labels\n- Routes misplaced nodes to correct communities\n- Proposes and applies structural merges/splits\n- Runs downstream phases (search index, embeddings, HTML visualizations)\n\nYour AI agent acts as the reasoning engine — no API keys, no local models, no downloads.\n\n\u003e **Headless alternative:** Run `reponova build` from the CLI for a fully algorithmic build (no LLM). For automated LLM enrichment, configure `enrich.provider` in `reponova.yml` — then `reponova build` handles everything including intelligent enrichment.\n\n### 3. Use it\n\nThe MCP server starts automatically. Your AI agent now has 11 graph tools.\n\n```\nYou: \"What would be the impact of refactoring the authenticate function?\"\nAgent: [calls graph_impact] → shows upstream/downstream blast radius across repos\n```\n\n### Keeping the graph fresh\n\nAfter code changes, re-run `/reponova-enrich` — only changed files are re-parsed, only affected steps re-run.\n\nFor CI or headless environments: `reponova build` (incremental by default, `--force` for full rebuild).\n\n---\n\n## MCP Tools\n\n11 specialized tools exposed over MCP (stdio):\n\n| Tool | Description |\n|------|-------------|\n| `graph_search` | 🔍 Full-text search across nodes. Filter by type, repo. Expand results with BFS/DFS. |\n| `graph_impact` | 💥 Blast radius analysis — find all upstream/downstream dependents of any symbol. |\n| `graph_path` | 🛤️ Weighted shortest path (Dijkstra) between two symbols. Filter by edge type. |\n| `graph_explain` | 📋 Full detail on a node: edges, community, centrality metrics, signature, docstring. |\n| `graph_similar` | 🧲 Semantic similarity search using vector embeddings (TF-IDF, ONNX, or remote provider). |\n| `graph_context` | 🧠 Smart context builder with token budget — combines search + vectors + graph expansion. |\n| `graph_community` | 🏘️ List all nodes in a community, ranked by degree centrality. |\n| `graph_hotspots` | 🔥 God nodes / architectural bottlenecks — most connected symbols in the graph. |\n| `graph_outline` | 🗂️ Tree-sitter code outline: functions, classes, imports with signatures and line ranges. |\n| `graph_docs` | 📄 Search documentation nodes (markdown, text, rst). |\n| `graph_status` | 📊 Graph metadata: node/edge counts, repos, build timestamp, version. |\n\n---\n\n## Enrichment\n\nRepoNova supports two enrichment modes:\n\n| Mode | How it works | Requires |\n|------|-------------|----------|\n| **Agent-driven** | `/reponova-enrich` — your AI agent builds the graph AND acts as the reasoning engine for enrichment. Complete pipeline in one command. | Any AI coding agent |\n| **Automated** | `reponova build` with `enrich.provider` configured — an external LLM generates descriptions, profiles, and routing decisions during the build. | A configured LLM provider in `reponova.yml` |\n\n### What enrichment does\n\nThe enrichment pipeline (7 steps) transforms a raw structural graph into an architecturally-aware knowledge base:\n\n| Step | What |\n|------|------|\n| 0 | Classify boundary nodes (candidates for rerouting) + compute edge density |\n| 1 | Generate architectural descriptions for high-degree nodes |\n| 2 | Profile each community (label, purpose, misfits) |\n| 3 | Route misfit nodes to better communities based on profiles |\n| 4 | Detect merge/split opportunities across communities |\n| 5 | Apply routing + restructure mutations to the graph |\n| 6 | Re-profile affected communities |\n| 7 | Finalize output files (`graph-enriched.json`, `node_descriptions.json`, `community_summaries.json`) |\n\n### Agent-driven enrichment (`/reponova-enrich`)\n\nThe installed command guides the agent through the full pipeline:\n\n```\nYou: /reponova-enrich\nAgent: [builds structural graph]\n       [reads input batches, reasons about architecture, writes output batches]\n       [CLI merges results, applies mutations]\n       [runs downstream phases: search index, embeddings, HTML]\n```\n\nThe agent uses `reponova enrich:*` subcommands for batch preparation and merging. All reasoning (descriptions, profiles, routing decisions) comes from the agent itself.\n\n---\n\n## CLI Reference\n\n### `reponova install`\n\nSet up editor integration (MCP server, plugin/hook, skills, enrich command, config).\n\n```bash\nreponova install --target \u003ceditor\u003e [--graph \u003cpath\u003e]\n```\n\n| Option | Required | Description |\n|--------|----------|-------------|\n| `--target` | Yes | `opencode`, `cursor`, `claude`, `vscode` |\n| `--graph` | No | Path to output directory. Default: `./reponova-out` |\n\n### `reponova build`\n\nRun the full build pipeline (incremental by default).\n\n```bash\nreponova build [--config \u003cpath\u003e] [--force] [--target \u003cphase\u003e] [--start-after \u003cphase\u003e] [--check \u003cphase\u003e]\n```\n\n| Option | Required | Description |\n|--------|----------|-------------|\n| `--config` | No | Path to `reponova.yml` (default: auto-detected) |\n| `--force` | No | Ignore all caches and rerun every phase |\n| `--target` | No | Run only this phase and its dependencies |\n| `--start-after` | No | Run only phases downstream of this phase |\n| `--check` | No | Check if a phase needs to run (exit 0 = up to date, exit 1 = needs run) |\n\n**Build pipeline (9 DAG phases, 5 levels):**\n\n```\nLevel 0: file-detection\nLevel 1: graph, outlines                         (parallel)\nLevel 2: communities\nLevel 3: enrich\nLevel 4: search-index, embeddings, html, report  (parallel)\n```\n\n| Phase | What it does |\n|-------|-------------|\n| **file-detection** | Discover source files, docs, diagrams — respects patterns/exclude/incremental |\n| **graph** | Parse with tree-sitter, extract symbols/calls/imports/inheritance, build graph |\n| **outlines** | Generate tree-sitter code outlines per file (SHA256 hashing — skip unchanged) |\n| **communities** | Louvain community detection, write `graph.json` |\n| **enrich** | Generate `graph-enriched.json`, community summaries, node descriptions (algorithmic or LLM) |\n| **search-index** | SQLite search index (`graph_search.db`) |\n| **embeddings** | Incremental embeddings (TF-IDF, ONNX, or remote provider) |\n| **html** | Interactive visualizations (`graph.html`, `graph_communities.html`) |\n| **report** | Build report with stats, hotspots, community breakdown |\n\n### `reponova enrich`\n\nRun the intelligent enrichment pipeline with a configured LLM provider. Builds up to `communities` if needed, runs all enrichment steps, seals the cache.\n\n```bash\nreponova enrich [--config \u003cpath\u003e]\n```\n\n| Option | Required | Description |\n|--------|----------|-------------|\n| `--config` | No | Path to `reponova.yml` (default: auto-detected) |\n\n\u003e **Note:** Does NOT run downstream phases (search-index, embeddings, html, report). Run `reponova build --start-after enrich` afterwards to complete the pipeline.\n\n### `reponova enrich:*`\n\nStep-by-step enrichment subcommands for IDE/agent workflows.\n\n```bash\nreponova enrich:metrics                        # Step 0: candidates + edge density\nreponova enrich:prepare \u003cstep\u003e                 # Prepare input batches\nreponova enrich:merge \u003cstep\u003e                   # Merge output batches\nreponova enrich:apply                          # Step 5: apply routing + restructure\nreponova enrich:finalize                       # Step 7: produce final output files\n```\n\n| Step | What it produces |\n|------|-----------------|\n| `descriptions` | Architectural descriptions for high-degree nodes |\n| `profiles` | Community profiles (label, purpose, misfits) |\n| `routing` | Routing decisions for boundary candidates |\n| `restructure` | Merge/split proposals across communities |\n| `updated-profiles` | Re-profiled communities after mutations |\n\n| Option | Required | Description |\n|--------|----------|-------------|\n| `--config` | No | Path to `reponova.yml` (default: auto-detected) |\n\n### `reponova mcp`\n\nStart the MCP server (stdio transport). Normally launched automatically by the editor.\n\n```bash\nreponova mcp [--graph \u003cpath\u003e]\n```\n\n| Option | Required | Description |\n|--------|----------|-------------|\n| `--graph` | No | Path to output directory. Default: `./reponova-out` |\n\n### `reponova check`\n\nValidate config, grammar availability, and display resolved paths.\n\n```bash\nreponova check [--config \u003cpath\u003e]\n```\n\n| Option | Required | Description |\n|--------|----------|-------------|\n| `--config` | No | Path to `reponova.yml` (default: auto-detected) |\n\n### `reponova cache`\n\nInspect and manage per-phase cache state. Exactly one operation is required. Phases are the same as in [`reponova build`](#reponova-build).\n\n```bash\nreponova cache --status                        # Show cache status for all phases\nreponova cache --check \u003cphase\u003e                 # Check if fresh (exit 0 = fresh, exit 1 = stale)\nreponova cache --seal \u003cphase\u003e                  # Manually seal (marks as up-to-date)\nreponova cache --invalidate \u003cphase\u003e            # Invalidate (forces re-run on next build)\n```\n\n| Option | Required | Description |\n|--------|----------|-------------|\n| `--config` | No | Path to `reponova.yml` (default: auto-detected) |\n\n### `reponova models`\n\nManage local AI models (ONNX embeddings, GGUF LLM weights).\n\n```bash\nreponova models \u003csubcommand\u003e\n```\n\n| Subcommand | Description |\n|------------|-------------|\n| `status` | Show configured and cached models |\n| `download` | Pre-download all models needed by config |\n| `remove \u003cname\u003e` | Remove a specific cached model |\n| `clear` | Remove all cached models |\n\n---\n\n## Supported Languages\n\n### Extraction (AST parsing + graph building)\n\n| Language | Extensions | Parser | Symbols Extracted |\n|----------|-----------|--------|-------------------|\n| Python | `.py`, `.pyw` | tree-sitter | Functions, classes, methods, decorators, docstrings, variables, imports, calls, inheritance |\n| Markdown | `.md` | Regex | Documents, sections (as containment hierarchy) |\n| Diagrams | `.puml`, `.plantuml`, `.svg` | Regex | Components, relationships (PlantUML); text content (SVG) |\n\n### Edge Types\n\n| Edge Type | Description |\n|-----------|-------------|\n| `calls` | Function/method invocation |\n| `imports` | Module-level import |\n| `imports_from` | Named import of a specific symbol |\n| `extends` | Class inheritance |\n| `contains` | Parent contains child (module→symbol, class→method, document→section) |\n\n---\n\n## Configuration\n\n### Config Resolution\n\nAuto-detected from (first match wins):\n\n1. `--config` argument\n2. `reponova.yml` in project root\n3. `.opencode/reponova.yml`\n4. `.cursor/reponova.yml`\n5. `.claude/reponova.yml`\n6. `.vscode/reponova.yml`\n\nAll paths are **relative to the config file's location**.\n\n### Full Config Reference\n\n```yaml\n# ──────────────────────────────────────────────────────────────────────────────\n# reponova.yml — Full Configuration Reference\n# ──────────────────────────────────────────────────────────────────────────────\n\n# Where to write build output\n# Default: \"reponova-out\"\noutput: ../reponova-out\n\n# ── Repositories ──────────────────────────────────────────────────────────────\nrepos:\n  - name: api-service           # unique identifier\n    path: ../services/api       # path relative to this file\n  - name: core-lib\n    path: ../services/core\n\n# ── Providers (optional — AI backends) ────────────────────────────────────────\n# Default (no provider) = fully algorithmic. No downloads, no API keys.\n# providers:\n#   my-openai:\n#     type: openai                  # \"openai\" | \"llama-cpp\" | \"onnx\"\n#     base_url: https://api.openai.com/v1\n#     model: text-embedding-3-small\n#     api_key: ${OPENAI_API_KEY}    # env var (resolved at runtime)\n#     timeout: 30                   # seconds (default: 30)\n#   local-llm:\n#     type: llama-cpp\n#     model: \"hf:Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q4_K_M\"\n#     context_size: 512\n#   local-embeddings:\n#     type: onnx\n#     model: all-MiniLM-L6-v2\n#   ollama:\n#     type: openai\n#     base_url: http://localhost:11434/v1\n#     model: nomic-embed-text\n\n# ── Model Management ─────────────────────────────────────────────────────────\nmodels:\n  cache_dir: ~/.cache/reponova/models   # default\n  gpu: auto                             # \"auto\" | \"cpu\" | \"cuda\" | \"metal\" | \"vulkan\"\n  threads: 0                            # 0 = auto-detect\n  download_on_first_use: true\n\n# ── Source Code Filters ───────────────────────────────────────────────────────\npatterns: []                    # empty = auto-detect by extension\nexclude: []                     # e.g. [\"**/generated/**\", \"**/*.test.ts\"]\nexclude_common: true            # skip node_modules, __pycache__, .git, venv, dist, build, ...\nincremental: true               # SHA256 file hashing — only re-parse changed files\n\n# ── Documentation ─────────────────────────────────────────────────────────────\ndocs:\n  enabled: true\n  patterns: []                  # empty = auto-detect (.md, .txt, .rst)\n  exclude: []\n  max_file_size_kb: 500\n\n# ── Diagrams / Images ─────────────────────────────────────────────────────────\nimages:\n  enabled: true\n  patterns: []                  # empty = auto-detect (.puml, .plantuml, .svg, ...)\n  exclude: []\n  parse_puml: true\n  parse_svg_text: true\n\n# ── Embeddings ────────────────────────────────────────────────────────────────\n# Default: TF-IDF (fast, no download). Set provider for ONNX or remote embeddings.\nembeddings:\n  enabled: true\n  # provider: my-openai\n  batch_size: 128\n\n# ── Enrich ────────────────────────────────────────────────────────────────────\n# Default (no provider): algorithmic (rule-based summaries + descriptions)\n# With provider: intelligent multi-step LLM enrichment pipeline\nenrich:\n  enabled: true\n  threshold: 0.8                  # top 20% of nodes by degree get descriptions\n  max_communities: 0              # 0 = no limit\n  candidate_threshold: 0.3        # boundary ratio for routing candidates\n  description_batch_tokens: 40000 # token budget per description batch\n  routing_batch_size: 30\n  concurrency: 4                  # max parallel LLM calls\n  max_retry_depth: 3\n  # provider: local-llm           # enables intelligent enrichment\n  max_tokens:                     # per-step LLM output token limits\n    descriptions: 32768\n    profiles: 2048\n    routing: 8192\n    restructure: 4096\n  # profile:                      # community profile prompt limits\n  #   max_nodes: 80\n  #   max_edges: 50\n  # restructure_max_pairs: 20\n\n# ── HTML ──────────────────────────────────────────────────────────────────────\nhtml: true\n# html_min_degree: 3\n\n# ── Outlines ──────────────────────────────────────────────────────────────────\noutlines:\n  enabled: true\n\n# ── Server ────────────────────────────────────────────────────────────────────\nserver: {}\n```\n\n### Config Examples\n\n**Minimal (single repo, algorithmic):**\n```yaml\noutput: ../reponova-out\nrepos:\n  - name: my-project\n    path: ..\n```\n\n**Multi-repo:**\n```yaml\noutput: ../reponova-out\nrepos:\n  - name: api\n    path: ../services/api\n  - name: core\n    path: ../services/core\n```\n\n**With LLM provider (automated enrichment via `reponova build`):**\n```yaml\noutput: ../reponova-out\nrepos:\n  - name: my-project\n    path: ..\nproviders:\n  local-llm:\n    type: openai\n    base_url: http://localhost:11434/v1\n    model: llama3.2\nenrich:\n  provider: local-llm\n```\n\n---\n\n## Models \u0026 Providers\n\nBy default, everything is algorithmic — no downloads, no API keys. Providers enable richer AI features.\n\n| Type | Purpose | Size | Requires |\n|------|---------|------|----------|\n| `onnx` | Local embeddings (sentence-transformers) | ~86 MB | Nothing (bundled runtime) |\n| `llama-cpp` | Local LLM (GGUF) for enrichment | ~350 MB | `node-llama-cpp` (optional peer dep) |\n| `openai` | Remote OpenAI-compatible API | None | API key or local server (Ollama, LM Studio, etc.) |\n\n**Retry policy:** Embeddings — 3 retries with exponential backoff on HTTP 429. Enrichment — configurable via `enrich.max_retry_depth` (default 3).\n\n---\n\n## Build Output\n\nAfter building the graph, the output directory contains:\n\n```\nreponova-out/\n├── graph.json                    # Full graph: nodes, edges, community assignments\n├── graph-enriched.json           # Enriched graph (after intelligent enrichment)\n├── graph-nodes.json              # Intermediate (pre-community detection)\n├── detected-files.json           # Detected file list\n├── graph.html                    # Interactive visualization (vis.js)\n├── graph_communities.html        # Community-focused visualization\n├── graph_search.db               # SQLite search index\n├── report.md                     # Build report: stats, hotspots, communities\n├── community_summaries.json      # Community summaries\n├── node_descriptions.json        # Node descriptions\n├── tfidf_idf.json                # TF-IDF vocabulary weights\n├── vectors/                      # LanceDB vector store\n├── outlines/                     # Code outlines per file\n├── .enrich/                      # Enrichment intermediates (intelligent mode)\n│   ├── candidates.json           #   boundary node classification\n│   ├── edge-density.json         #   inter-community density\n│   ├── descriptions.json         #   merged descriptions\n│   ├── profiles.json             #   merged community profiles\n│   ├── routing.json              #   merged routing decisions\n│   ├── restructure.json          #   merge/split proposals\n│   ├── graph-applied.json        #   graph after mutations\n│   └── updated-profiles.json     #   re-profiled communities\n└── .cache/                       # Incremental build cache\n```\n\n---\n\n## Programmatic API\n\n### Build\n\n```typescript\nimport { build } from \"reponova\";\n\nconst result = await build(\"./reponova.yml\");\n// result.outputDir, result.phases, result.totalProcessed\n```\n\n### Runtime Registration + Build\n\n```typescript\nimport { build, registerExtractor, registerOutlineLanguage } from \"reponova\";\nimport type { LanguageExtractor, LanguageSupport } from \"reponova\";\n\nregisterExtractor(myExtractor);\nregisterOutlineLanguage(\"rust\", [\"rs\"], myOutline);\nconst result = await build(\"./reponova.yml\");\n```\n\n### Query\n\n```typescript\nimport {\n  openDatabase, initializeSchema, populateDatabase,\n  loadGraphData, searchNodes, analyzeImpact, findShortestPath,\n} from \"reponova\";\n\nconst graphData = loadGraphData(\"./reponova-out/graph.json\");\nconst db = await openDatabase(\":memory:\");\ninitializeSchema(db);\npopulateDatabase(db, graphData);\n\nconst results = searchNodes(db, \"authentication\", { top_k: 5, type: \"function\" });\nconst impact = analyzeImpact(db, \"Function:authenticate_user\", { max_depth: 3 });\nconst path = findShortestPath(db, graphData, \"ModuleA\", \"ModuleB\");\n```\n\n### Smart Context\n\n```typescript\nimport { ContextBuilder, loadConfig } from \"reponova\";\n\nconst { config } = loadConfig(\"./reponova.yml\");\nconst builder = new ContextBuilder(db, graphData, \"./reponova-out\");\nawait builder.initialize(config.embeddings);\nconst context = await builder.buildContext({ query: \"authentication flow\", maxTokens: 4000 });\n```\n\n---\n\n## FAQ\n\n### Do I need an API key?\n\nNo. By default, RepoNova is fully algorithmic. For agent-driven enrichment (`/reponova-enrich`), the agent's own reasoning is the \"model\" — no external services needed. API keys are only needed if you configure a remote `openai` provider.\n\n### How long does a build take?\n\nAlgorithmic mode (no LLM):\n- Small (500 files): ~5-10s\n- Medium (5,000 files): ~30-60s\n- Large monorepo (20,000+ files): 2-5 min\n\nIntelligent enrichment adds 1-10 minutes depending on graph size, LLM speed, and concurrency.\n\n### Can I use it without an editor?\n\nYes. `reponova build` and the programmatic API work standalone. The MCP server is just one way to query the graph.\n\n---\n\n## Contributing\n\n### Adding Language Support (Extraction)\n\n1. **Create** `src/extract/languages/\u003clang\u003e.ts` implementing `LanguageExtractor`\n2. **Register** in `src/extract/languages/registry.ts`\n3. **Add** tree-sitter WASM grammar to `grammars/`\n\n#### `LanguageExtractor` Interface\n\n```typescript\ninterface LanguageExtractor {\n  readonly languageId: string;\n  readonly extensions: string[];\n  readonly wasmFile?: string;\n  extract(tree: SyntaxTree | null, sourceCode: string, filePath: string): FileExtraction;\n  resolveImportPath(importModule: string, currentFilePath: string): string[];\n}\n```\n\n#### `FileExtraction` Return Type\n\n```typescript\ninterface FileExtraction {\n  filePath: string;\n  language: string;\n  symbols: SymbolNode[];\n  imports: ImportDeclaration[];\n  references: SymbolReference[];\n}\n```\n\n| Type | Key Fields | Purpose |\n|------|-----------|---------|\n| `SymbolNode` | `name`, `qualifiedName`, `kind`, `signature?`, `decorators`, `docstring?`, `startLine`, `endLine`, `parent?`, `bases?`, `calls` | A symbol in the file |\n| `ImportDeclaration` | `module`, `names`, `isWildcard`, `isExport?`, `line` | An import/export statement |\n| `SymbolReference` | `name`, `fromSymbol`, `kind`, `line` | A reference to another symbol |\n| `SymbolKind` | `\"function\"` \\| `\"class\"` \\| `\"method\"` \\| `\"variable\"` \\| `\"constant\"` \\| `\"interface\"` \\| `\"enum\"` \\| `\"module\"` \\| `\"document\"` \\| `\"section\"` | Symbol classification |\n\nSee `src/extract/types.ts` for full definitions. Reference implementations: `src/extract/languages/python.ts` (tree-sitter), `src/extract/languages/markdown.ts` (regex).\n\n### Adding Outline Support\n\nOutlines (`graph_outline`) use a **separate system** from extraction.\n\n1. **Create** `src/outline/languages/\u003clang\u003e.ts` implementing `LanguageSupport`\n2. **Register** in `src/outline/languages/registry.ts`\n\n```typescript\ninterface LanguageSupport {\n  readonly wasmFile: string;\n  treeSitterExtract(rootNode: SyntaxNode, filePath: string, lineCount: number): FileOutline;\n  regexExtract(filePath: string, source: string, lineCount: number): FileOutline;\n}\n```\n\nReference: `src/outline/languages/python.ts`\n\n---\n\n## License\n\nMIT — [CristianoCiuti/reponova](https://github.com/CristianoCiuti/reponova)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcristianociuti%2Freponova","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcristianociuti%2Freponova","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcristianociuti%2Freponova/lists"}