java-codebase-rag 0.9.6__tar.gz → 0.10.0__tar.gz

{java_codebase_rag-0.9.6/src/java_codebase_rag.egg-info → java_codebase_rag-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.9.6
+Version: 0.10.0
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
@@ -21,21 +21,22 @@ Classifier: Operating System :: Microsoft :: Windows
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: cocoindex[lancedb]<2,>=1.0.7; sys_platform != "darwin" or platform_machine != "x86_64"
+Requires-Dist: cocoindex[lancedb]<2,>=1.0.15; sys_platform != "darwin" or platform_machine != "x86_64"
 Requires-Dist: ladybug<0.18,>=0.17.1
-Requires-Dist: lancedb<0.31,>=0.25.3; sys_platform != "darwin" or platform_machine != "x86_64"
+Requires-Dist: lancedb<0.36,>=0.34; sys_platform != "darwin" or platform_machine != "x86_64"
 Requires-Dist: mcp<2,>=1.27.0
 Requires-Dist: numpy<2.5,>=1.26.4
 Requires-Dist: pathspec<2,>=1.0.4
-Requires-Dist: pyarrow<24,>=23.0.1
+Requires-Dist: pyarrow<26,>=23.0.1
 Requires-Dist: pydantic<3,>=2.0
 Requires-Dist: PyYAML<7,>=6.0.3
 Requires-Dist: questionary<3,>=2.0
-Requires-Dist: rich<15,>=14
+Requires-Dist: rich<16,>=14
 Requires-Dist: sentence-transformers<6,>=5.4.0; sys_platform != "darwin" or platform_machine != "x86_64"
 Requires-Dist: tree-sitter<0.26,>=0.25.2
 Requires-Dist: tree-sitter-java<0.24,>=0.23.5
 Requires-Dist: unidiff<1,>=0.7.3
+Requires-Dist: watchdog<7,>=6
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
@@ -45,18 +46,16 @@ Dynamic: license-file
 
 # java-codebase-rag
 
-A graph-native code intelligence layer for Java microservice estates — usable as an **MCP server** or a **CLI** (`jrag`), two surfaces over the same graph.
+A graph-native code intelligence layer for Java microservice estates, surfaced through the **`jrag` CLI** — one command per engineering intent. A **legacy MCP server** (`search` / `find` / `describe` / `neighbors` / `resolve`) is also available for existing setups. Both are thin surfaces over the same **AST Graph**: a deterministic property graph extracted from Java source with tree-sitter, stored **locally** in **LadybugDB** (graph) alongside a **LanceDB** vector index (chunks). There is no server to host and no cloud round-trip — the index lives on your disk and your source never leaves the machine. Both surfaces collapse onto three primitive operations: **locate**, **inspect**, **walk**.
 
-The system extracts a deterministic property graph from Java source (tree-sitter), stores it in **LadybugDB** (graph) alongside a **LanceDB** vector index (chunks), and exposes two agent surfaces, picked at install time (`java-codebase-rag install --surface mcp|cli`): the **MCP** surface ships five tools — `search`, `find`, `describe`, `neighbors`, `resolve` — over stdio; the **CLI** surface ships `jrag`, one command per engineering intent. Both collapse onto three primitive operations: **locate**, **inspect**, **walk**.
-
-> **What this MCP is:** a **GPS for code navigation**, not a reasoning engine.
+> **What this is: a GPS for code navigation**, not a reasoning engine.
 > Agents use a simple loop:
 >
-> 1. **Locate** entry nodes (`search` / `find`, or identifier-shaped **`resolve`**)
-> 2. **Inspect** what a node is (`describe`)
-> 3. **Walk** one hop at a time (`neighbors`) until enough evidence is gathered
+> 1. **Locate** entry nodes (`jrag find`, `jrag search`, or identifier-shaped lookup)
+> 2. **Inspect** what a node is (`jrag inspect`)
+> 3. **Walk** one hop at a time (`jrag callers` / `callees` / `hierarchy` / …) until enough evidence is gathered
 >
-> The MCP exposes structure and adjacency; the agent owns multi-hop reasoning and stop conditions.
+> The tool exposes structure and adjacency; the agent owns multi-hop reasoning and stop conditions.
 
 For the design rationale, the GPS metaphor, and the full ontology, see [`docs/paper/paper.pdf`](./docs/paper/paper.pdf) (architecture report).
 
@@ -66,7 +65,7 @@ For the design rationale, the GPS metaphor, and the full ontology, see [`docs/pa
 
 Generic code-search tools (grep, ctags, vector-only RAG) hit a ceiling on real Java microservice estates: they find files but lose the structure that makes a Spring/JAX-RS system navigable. This project is built around five choices that target that gap.
 
-- **Hybrid RAG + GraphRAG, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (LadybugDB property graph) are composed in one surface. `search` finds candidate nodes by meaning; `neighbors` walks the exact edge you care about (`CALLS`, `IMPLEMENTS`, `INJECTS`, `EXPOSES`, …). The agent picks the right primitive per step instead of being forced into pure-vector or pure-symbol search.
+- **Hybrid RAG + AST Graph, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (the LadybugDB AST Graph) are composed in one surface. `search` finds candidate nodes by meaning; `neighbors` walks the exact edge you care about (`CALLS`, `IMPLEMENTS`, `INJECTS`, `EXPOSES`, …). The agent picks the right primitive per step instead of being forced into pure-vector or pure-symbol search.
 
 - **A Java-tuned role model.** Symbols are labelled with stereotypes inferred from Spring and JAX-RS conventions — `CONTROLLER`, `SERVICE`, `REPOSITORY`, `COMPONENT`, `CONFIG`, `ENTITY`, `CLIENT`, `MAPPER`, `DTO`. Agents can ask "list controllers" or "who injects this repository" directly, instead of grep-ing for `@RestController` and hoping for the best. Roles drive both filtering (`find` with a `NodeFilter`) and ranking.
 
@@ -86,7 +85,7 @@ The rest of this README is the install, the tool/command orientation, and the re
 pip install java-codebase-rag
 ```
 
-Python **3.11+** required, on **Linux, macOS, and Windows**. On Linux, Windows, and **Apple Silicon** Macs every native dependency (LanceDB, LadybugDB/kuzu, CocoIndex) ships a wheel and you get the full semantic + graph search. **Intel Macs (x86_64) install graph-only**: PyTorch ≥2.3 and LanceDB ≥0.26 dropped macOS Intel wheels, so the vector stack is auto-excluded via PEP 508 markers — `pip install java-codebase-rag` works out of the box, the graph layer (`find` / `describe` / `neighbors` / `resolve`) is fully usable, and the `search` tool falls back to **lexical (keyword) search** over the symbol graph (same tool contract, keyword-ranked instead of semantic; an advisory notes the mode). Semantic/vector search needs Apple Silicon, Linux, or Windows. After install, `java-codebase-rag --help` should print the CLI groups.
+Python **3.11+** required, on **Linux, macOS, and Windows**. On Linux, Windows, and **Apple Silicon** Macs every native dependency (LanceDB, LadybugDB, CocoIndex) ships a wheel and you get the full semantic + graph search. **Intel Macs (x86_64) install graph-only**: PyTorch ≥2.3 and LanceDB ≥0.26 dropped macOS Intel wheels, so the vector stack is auto-excluded via PEP 508 markers — `pip install java-codebase-rag` works out of the box, the graph layer (`find` / `describe` / `neighbors` / `resolve`) is fully usable, and the `search` tool falls back to **lexical search** over the symbol graph — BM25-ranked over a LadybugDB full-text index (same tool contract, keyword-ranked instead of semantic; an advisory notes the mode). Semantic/vector search needs Apple Silicon, Linux, or Windows. After install, `java-codebase-rag --help` should print the CLI groups.
 The package includes the CocoIndex lifecycle dependency used by `init`, `increment`, `reprocess`, and `erase` on platforms that have it (it is absent on Intel Mac).
 
 ### Interactive setup (recommended)
@@ -122,19 +121,7 @@ If you prefer manual configuration, see [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs
 
 ## Tools & commands at a glance
 
-Pick a surface at install time — `java-codebase-rag install --surface mcp|cli` (default `cli`, recommended). Both surfaces walk the same LanceDB vectors + LadybugDB graph. Switch an existing install later with `java-codebase-rag update --surface mcp|cli`.
-
-**MCP surface — five tools over stdio**
-
-| Tool | Purpose | Required args |
-|---|---|---|
-| `search` | Locate nodes by NL / code text. | `query` |
-| `find` | Locate nodes by structured filter. | `kind`, `filter` |
-| `describe` | Full record + edge counts for one node. | `id` |
-| `resolve` | Identifier-shaped lookup (FQN-collision-safe). Returns `one` / `many` / `none`. | `identifier` |
-| `neighbors` | Graph walk, one hop. | `ids`, `direction`, `edge_types` |
-
-Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live in [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md). Edge types and traversal directions are listed in [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md).
+`jrag` is the default and recommended surface (`java-codebase-rag install --surface cli`). The **MCP server** (`--surface mcp`) is kept as a **legacy** option for existing setups. Both surfaces walk the same LanceDB vectors + LadybugDB **AST Graph**. Switch an existing install later with `java-codebase-rag update --surface mcp|cli`.
 
 **CLI surface — `jrag`, one command per engineering intent**
 
@@ -143,7 +130,7 @@ Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live
 jrag status                    # index health (ontology version, freshness, counts)
 jrag microservices             # microservices with resolved type counts
 jrag map                       # counts per kind per service/module
-jrag map --module              # group by module instead
+jrag map --by module           # group by module instead (--module filters)
 jrag conventions               # dominant roles + framework tallies
 jrag overview chat-core        # bundle for a microservice
 jrag overview /chat/assign     # route flow (inbound callers + outbound CALLS)
@@ -191,9 +178,21 @@ jrag search "audit" --offset 5            # paginated
 
 Every `<query>` command takes human-readable identifiers (FQN / simple name / route path / topic) — never raw node IDs. Output contract, flags, and the resolve-first rule are in [`jrag` — agent CLI](#jrag--agent-cli) below.
 
+**MCP surface — five tools over stdio (legacy)**
+
+| Tool | Purpose | Required args |
+|---|---|---|
+| `search` | Locate nodes by NL / code text. | `query` |
+| `find` | Locate nodes by structured filter. | `kind`, `filter` |
+| `describe` | Full record + edge counts for one node. | `id` |
+| `resolve` | Identifier-shaped lookup (FQN-collision-safe). Returns `one` / `many` / `none`. | `identifier` |
+| `neighbors` | Graph walk, one hop. | `ids`, `direction`, `edge_types` |
+
+Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live in [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md). Edge types and traversal directions are listed in [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md).
+
 ### Three-layer architecture
 
-Layer 1 (storage) → Layer 2 (5 MCP tools **or** the `jrag` CLI) → Layer 3 (skill). The MCP-surface skill **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** documents the 5-tool MCP; the CLI-surface skill **[`/explore-codebase-cli`](./skills/explore-codebase-cli/SKILL.md)** documents the `jrag` CLI (PR-JRAG-5). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
+Layer 1 (storage) → Layer 2 (the `jrag` CLI, **or** the legacy 5-tool MCP) → Layer 3 (skill). The CLI-surface skill **[`/explore-codebase-cli`](./skills/explore-codebase-cli/SKILL.md)** documents the `jrag` CLI; the MCP-surface skill **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** documents the legacy 5-tool MCP (PR-JRAG-5). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
 
 ---
 
@@ -303,7 +302,7 @@ full design and per-PR breakdown.
 | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | Environment variables, project YAML, graph ontology, brownfield overrides, ignore patterns. |
 | [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) | CLI operator playbook: workflows, exit codes, env alignment. |
 | [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) | MCP-traversable edges, directions, dot-key composition. |
-| [`skills/`](./skills/) | `/explore-codebase` (MCP surface) + `/explore-codebase-cli` (CLI surface) skills — operating manuals for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
+| [`skills/`](./skills/) | `/explore-codebase-cli` (CLI surface) + `/explore-codebase` (legacy MCP surface) skills — operating manuals for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
 | [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md) | 7-phase agent-driven verification after indexing your project. |
 | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) | Assumptions about your Java repo + per-file edit map for non-conforming codebases. |
 | [`docs/PRODUCT-VISION.md`](./docs/PRODUCT-VISION.md) | Long-term product direction. |

{java_codebase_rag-0.9.6 → java_codebase_rag-0.10.0}/README.md

@@ -1,17 +1,15 @@
 # java-codebase-rag
 
-A graph-native code intelligence layer for Java microservice estates — usable as an **MCP server** or a **CLI** (`jrag`), two surfaces over the same graph.
+A graph-native code intelligence layer for Java microservice estates, surfaced through the **`jrag` CLI** — one command per engineering intent. A **legacy MCP server** (`search` / `find` / `describe` / `neighbors` / `resolve`) is also available for existing setups. Both are thin surfaces over the same **AST Graph**: a deterministic property graph extracted from Java source with tree-sitter, stored **locally** in **LadybugDB** (graph) alongside a **LanceDB** vector index (chunks). There is no server to host and no cloud round-trip — the index lives on your disk and your source never leaves the machine. Both surfaces collapse onto three primitive operations: **locate**, **inspect**, **walk**.
 
-The system extracts a deterministic property graph from Java source (tree-sitter), stores it in **LadybugDB** (graph) alongside a **LanceDB** vector index (chunks), and exposes two agent surfaces, picked at install time (`java-codebase-rag install --surface mcp|cli`): the **MCP** surface ships five tools — `search`, `find`, `describe`, `neighbors`, `resolve` — over stdio; the **CLI** surface ships `jrag`, one command per engineering intent. Both collapse onto three primitive operations: **locate**, **inspect**, **walk**.
-
-> **What this MCP is:** a **GPS for code navigation**, not a reasoning engine.
+> **What this is: a GPS for code navigation**, not a reasoning engine.
 > Agents use a simple loop:
 >
-> 1. **Locate** entry nodes (`search` / `find`, or identifier-shaped **`resolve`**)
-> 2. **Inspect** what a node is (`describe`)
-> 3. **Walk** one hop at a time (`neighbors`) until enough evidence is gathered
+> 1. **Locate** entry nodes (`jrag find`, `jrag search`, or identifier-shaped lookup)
+> 2. **Inspect** what a node is (`jrag inspect`)
+> 3. **Walk** one hop at a time (`jrag callers` / `callees` / `hierarchy` / …) until enough evidence is gathered
 >
-> The MCP exposes structure and adjacency; the agent owns multi-hop reasoning and stop conditions.
+> The tool exposes structure and adjacency; the agent owns multi-hop reasoning and stop conditions.
 
 For the design rationale, the GPS metaphor, and the full ontology, see [`docs/paper/paper.pdf`](./docs/paper/paper.pdf) (architecture report).
 
@@ -21,7 +19,7 @@ For the design rationale, the GPS metaphor, and the full ontology, see [`docs/pa
 
 Generic code-search tools (grep, ctags, vector-only RAG) hit a ceiling on real Java microservice estates: they find files but lose the structure that makes a Spring/JAX-RS system navigable. This project is built around five choices that target that gap.
 
-- **Hybrid RAG + GraphRAG, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (LadybugDB property graph) are composed in one surface. `search` finds candidate nodes by meaning; `neighbors` walks the exact edge you care about (`CALLS`, `IMPLEMENTS`, `INJECTS`, `EXPOSES`, …). The agent picks the right primitive per step instead of being forced into pure-vector or pure-symbol search.
+- **Hybrid RAG + AST Graph, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (the LadybugDB AST Graph) are composed in one surface. `search` finds candidate nodes by meaning; `neighbors` walks the exact edge you care about (`CALLS`, `IMPLEMENTS`, `INJECTS`, `EXPOSES`, …). The agent picks the right primitive per step instead of being forced into pure-vector or pure-symbol search.
 
 - **A Java-tuned role model.** Symbols are labelled with stereotypes inferred from Spring and JAX-RS conventions — `CONTROLLER`, `SERVICE`, `REPOSITORY`, `COMPONENT`, `CONFIG`, `ENTITY`, `CLIENT`, `MAPPER`, `DTO`. Agents can ask "list controllers" or "who injects this repository" directly, instead of grep-ing for `@RestController` and hoping for the best. Roles drive both filtering (`find` with a `NodeFilter`) and ranking.
 
@@ -41,7 +39,7 @@ The rest of this README is the install, the tool/command orientation, and the re
 pip install java-codebase-rag
 ```
 
-Python **3.11+** required, on **Linux, macOS, and Windows**. On Linux, Windows, and **Apple Silicon** Macs every native dependency (LanceDB, LadybugDB/kuzu, CocoIndex) ships a wheel and you get the full semantic + graph search. **Intel Macs (x86_64) install graph-only**: PyTorch ≥2.3 and LanceDB ≥0.26 dropped macOS Intel wheels, so the vector stack is auto-excluded via PEP 508 markers — `pip install java-codebase-rag` works out of the box, the graph layer (`find` / `describe` / `neighbors` / `resolve`) is fully usable, and the `search` tool falls back to **lexical (keyword) search** over the symbol graph (same tool contract, keyword-ranked instead of semantic; an advisory notes the mode). Semantic/vector search needs Apple Silicon, Linux, or Windows. After install, `java-codebase-rag --help` should print the CLI groups.
+Python **3.11+** required, on **Linux, macOS, and Windows**. On Linux, Windows, and **Apple Silicon** Macs every native dependency (LanceDB, LadybugDB, CocoIndex) ships a wheel and you get the full semantic + graph search. **Intel Macs (x86_64) install graph-only**: PyTorch ≥2.3 and LanceDB ≥0.26 dropped macOS Intel wheels, so the vector stack is auto-excluded via PEP 508 markers — `pip install java-codebase-rag` works out of the box, the graph layer (`find` / `describe` / `neighbors` / `resolve`) is fully usable, and the `search` tool falls back to **lexical search** over the symbol graph — BM25-ranked over a LadybugDB full-text index (same tool contract, keyword-ranked instead of semantic; an advisory notes the mode). Semantic/vector search needs Apple Silicon, Linux, or Windows. After install, `java-codebase-rag --help` should print the CLI groups.
 The package includes the CocoIndex lifecycle dependency used by `init`, `increment`, `reprocess`, and `erase` on platforms that have it (it is absent on Intel Mac).
 
 ### Interactive setup (recommended)
@@ -77,19 +75,7 @@ If you prefer manual configuration, see [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs
 
 ## Tools & commands at a glance
 
-Pick a surface at install time — `java-codebase-rag install --surface mcp|cli` (default `cli`, recommended). Both surfaces walk the same LanceDB vectors + LadybugDB graph. Switch an existing install later with `java-codebase-rag update --surface mcp|cli`.
-
-**MCP surface — five tools over stdio**
-
-| Tool | Purpose | Required args |
-|---|---|---|
-| `search` | Locate nodes by NL / code text. | `query` |
-| `find` | Locate nodes by structured filter. | `kind`, `filter` |
-| `describe` | Full record + edge counts for one node. | `id` |
-| `resolve` | Identifier-shaped lookup (FQN-collision-safe). Returns `one` / `many` / `none`. | `identifier` |
-| `neighbors` | Graph walk, one hop. | `ids`, `direction`, `edge_types` |
-
-Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live in [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md). Edge types and traversal directions are listed in [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md).
+`jrag` is the default and recommended surface (`java-codebase-rag install --surface cli`). The **MCP server** (`--surface mcp`) is kept as a **legacy** option for existing setups. Both surfaces walk the same LanceDB vectors + LadybugDB **AST Graph**. Switch an existing install later with `java-codebase-rag update --surface mcp|cli`.
 
 **CLI surface — `jrag`, one command per engineering intent**
 
@@ -98,7 +84,7 @@ Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live
 jrag status                    # index health (ontology version, freshness, counts)
 jrag microservices             # microservices with resolved type counts
 jrag map                       # counts per kind per service/module
-jrag map --module              # group by module instead
+jrag map --by module           # group by module instead (--module filters)
 jrag conventions               # dominant roles + framework tallies
 jrag overview chat-core        # bundle for a microservice
 jrag overview /chat/assign     # route flow (inbound callers + outbound CALLS)
@@ -146,9 +132,21 @@ jrag search "audit" --offset 5            # paginated
 
 Every `<query>` command takes human-readable identifiers (FQN / simple name / route path / topic) — never raw node IDs. Output contract, flags, and the resolve-first rule are in [`jrag` — agent CLI](#jrag--agent-cli) below.
 
+**MCP surface — five tools over stdio (legacy)**
+
+| Tool | Purpose | Required args |
+|---|---|---|
+| `search` | Locate nodes by NL / code text. | `query` |
+| `find` | Locate nodes by structured filter. | `kind`, `filter` |
+| `describe` | Full record + edge counts for one node. | `id` |
+| `resolve` | Identifier-shaped lookup (FQN-collision-safe). Returns `one` / `many` / `none`. | `identifier` |
+| `neighbors` | Graph walk, one hop. | `ids`, `direction`, `edge_types` |
+
+Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live in [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md). Edge types and traversal directions are listed in [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md).
+
 ### Three-layer architecture
 
-Layer 1 (storage) → Layer 2 (5 MCP tools **or** the `jrag` CLI) → Layer 3 (skill). The MCP-surface skill **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** documents the 5-tool MCP; the CLI-surface skill **[`/explore-codebase-cli`](./skills/explore-codebase-cli/SKILL.md)** documents the `jrag` CLI (PR-JRAG-5). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
+Layer 1 (storage) → Layer 2 (the `jrag` CLI, **or** the legacy 5-tool MCP) → Layer 3 (skill). The CLI-surface skill **[`/explore-codebase-cli`](./skills/explore-codebase-cli/SKILL.md)** documents the `jrag` CLI; the MCP-surface skill **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** documents the legacy 5-tool MCP (PR-JRAG-5). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
 
 ---
 
@@ -258,7 +256,7 @@ full design and per-PR breakdown.
 | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | Environment variables, project YAML, graph ontology, brownfield overrides, ignore patterns. |
 | [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) | CLI operator playbook: workflows, exit codes, env alignment. |
 | [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) | MCP-traversable edges, directions, dot-key composition. |
-| [`skills/`](./skills/) | `/explore-codebase` (MCP surface) + `/explore-codebase-cli` (CLI surface) skills — operating manuals for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
+| [`skills/`](./skills/) | `/explore-codebase-cli` (CLI surface) + `/explore-codebase` (legacy MCP surface) skills — operating manuals for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
 | [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md) | 7-phase agent-driven verification after indexing your project. |
 | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) | Assumptions about your Java repo + per-file edit map for non-conforming codebases. |
 | [`docs/PRODUCT-VISION.md`](./docs/PRODUCT-VISION.md) | Long-term product direction. |

{java_codebase_rag-0.9.6 → java_codebase_rag-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "java-codebase-rag"
-version = "0.9.6"
+version = "0.10.0"
 description = "MCP server for semantic + structural search over Java codebases"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -32,21 +32,22 @@ classifiers = [
 # lexical (keyword) backend over the symbol graph (search_lexical.py); every other platform
 # is unchanged.
 dependencies = [
-    "cocoindex[lancedb]>=1.0.7,<2; sys_platform != 'darwin' or platform_machine != 'x86_64'",
+    "cocoindex[lancedb]>=1.0.15,<2; sys_platform != 'darwin' or platform_machine != 'x86_64'",
     "ladybug>=0.17.1,<0.18",
-    "lancedb>=0.25.3,<0.31; sys_platform != 'darwin' or platform_machine != 'x86_64'",
+    "lancedb>=0.34,<0.36; sys_platform != 'darwin' or platform_machine != 'x86_64'",
     "mcp>=1.27.0,<2",
     "numpy>=1.26.4,<2.5",
     "pathspec>=1.0.4,<2",
-    "pyarrow>=23.0.1,<24",
+    "pyarrow>=23.0.1,<26",
     "pydantic>=2.0,<3",
     "PyYAML>=6.0.3,<7",
     "questionary>=2.0,<3",
-    "rich>=14,<15",
+    "rich>=14,<16",
     "sentence-transformers>=5.4.0,<6; sys_platform != 'darwin' or platform_machine != 'x86_64'",
     "tree-sitter>=0.25.2,<0.26",
     "tree-sitter-java>=0.23.5,<0.24",
     "unidiff>=0.7.3,<1",
+    "watchdog>=6,<7",
 ]
 
 [project.optional-dependencies]

{java_codebase_rag-0.9.6 → java_codebase_rag-0.10.0}/src/java_codebase_rag/absence/absence_vocab.py

@@ -375,8 +375,13 @@ def get_vocabulary_index(graph: Any, cfg: Any) -> VocabularyIndex:
         # (JSONDecodeError/KeyError) — all subsumed by Exception; rebuild.
         log.debug(f"Vocab index missing/stale/corrupt ({e}), rebuilding from graph")
 
-        # Build from graph
-        index = VocabularyIndex.build(graph, q=cfg.absence_ngram_q)
+        # Build from graph. Coerce q to int (mirror absence_diagnosis.py's
+        # int(getattr(cfg, ...)) pattern): a non-int cfg.absence_ngram_q (e.g. a
+        # MagicMock cfg from a leaked test mock, or a YAML string) would otherwise
+        # crash _qgrams at `len(text) < q` ('int < MagicMock'). Default 3 = the
+        # config default for absence_ngram_q.
+        q = int(getattr(cfg, "absence_ngram_q", 3) or 3)
+        index = VocabularyIndex.build(graph, q=q)
 
         # Save to sidecar (best-effort)
         try:

{java_codebase_rag-0.9.6 → java_codebase_rag-0.10.0}/src/java_codebase_rag/analysis/pr_analysis.py

@@ -377,6 +377,31 @@ def _route_ids_for_symbol(graph: Any, symbol_id: str) -> list[str]:
     return out
 
 
+def _route_natural_id(graph: Any, rid: str) -> str:
+    """Map a raw Route node id to its agent-facing natural identifier.
+
+    Mirrors the envelope contract (``METHOD path`` for HTTP endpoints,
+    ``topic:<name>`` for kafka topics surfaced as :Route) so ``routes_touched``
+    in the PR risk report is readable instead of leaking raw graph ids like
+    ``r:970ffaa960a4f65d``. Falls back to ``rid`` only if the route vanished.
+    """
+    rows = graph._rows(
+        "MATCH (r:Route {id: $rid}) "
+        "RETURN r.method AS method, r.path_template AS path_template, "
+        "r.path AS path, r.topic AS topic LIMIT 1",
+        {"rid": rid},
+    )
+    if not rows:
+        return rid
+    r = rows[0]
+    method = str(r.get("method") or "")
+    path = str(r.get("path_template") or r.get("path") or "")
+    if method or path:
+        return f"{method} {path}".strip()
+    topic = str(r.get("topic") or "")
+    return f"topic:{topic}" if topic else rid
+
+
 def compute_risk(graph: Any, changed: list[ChangedSymbol]) -> PrRiskReport:
     """Aggregate blast radius, routes, cross-service callers, and v1 risk score.
 
@@ -415,7 +440,9 @@ def compute_risk(graph: Any, changed: list[ChangedSymbol]) -> PrRiskReport:
         needle = _impact_needle_for_changed(graph, fqn, cs.kind)
         ia = graph.impact_analysis(needle, depth=2, limit=400)
         n = len(ia)
-        blast_by[cs.symbol_id] = n
+        # Key blast radius by the symbol's FQN (agent-facing identifier), not
+        # its raw graph id — the report is operator-facing JSON.
+        blast_by[fqn or cs.symbol_id] = n
         blast_total += n
 
         for e in graph.find_callers(cs.fqn, depth=2, limit=400):
@@ -429,8 +456,11 @@ def compute_risk(graph: Any, changed: list[ChangedSymbol]) -> PrRiskReport:
         cs_cross_service = 0
         route_ids = _route_ids_for_symbol(graph, cs.symbol_id)
         for rid in route_ids:
-            if rid not in routes:
-                routes.append(rid)
+            # Record the route by its natural identifier (METHOD path /
+            # topic:name), not the raw graph id.
+            label = _route_natural_id(graph, rid)
+            if label and label not in routes:
+                routes.append(label)
             callers = graph._rows(
                 "MATCH (s:Symbol)-[:DECLARES_CLIENT]->(c:Client)-[e:HTTP_CALLS]->(r:Route {id: $rid}) "
                 "WHERE e.match = 'cross_service' "

{java_codebase_rag-0.9.6 → java_codebase_rag-0.10.0}/src/java_codebase_rag/ast/ast_java.py

@@ -84,7 +84,8 @@ _DTO_LOMBOK_ANNOTATIONS: frozenset[str] = frozenset({
 # Phase 11: `EDGE_SCHEMA` in `java_ontology.py` (canonical edge navigation schema; v14 re-index).
 # Phase 12: CALLS `callee_declaring_role`, supertype-walk dedup, pass3 unresolved counters (v15 re-index).
 # Bumps whenever extraction / enrichment semantics change.
-ONTOLOGY_VERSION = 18
+# Phase 13: Symbol.search_text + LadybugDB FTS (Okapi BM25) index for lexical search (v19 re-index).
+ONTOLOGY_VERSION = 19
 
 ROLE_ANNOTATIONS: dict[str, str] = {
     # Spring Web

{java_codebase_rag-0.9.6 → java_codebase_rag-0.10.0}/src/java_codebase_rag/cli.py

@@ -846,7 +846,15 @@ def _cmd_unresolved_calls_list(args: argparse.Namespace) -> int:
         callee_simple=args.callee_simple,
         limit=int(args.limit),
     )
-    _emit({"success": True, "count": len(rows), "sites": rows})
+    # Drop the raw caller symbol id: the row already carries the agent-facing
+    # ``caller_fqn``, so ``caller_id`` is redundant noise in an operator-facing
+    # report. The call-site ``id`` (``ucs:``) is kept — it's each site's
+    # primary key, not a caller reference.
+    sites = [
+        {k: v for k, v in row.items() if k != "caller_id"}
+        for row in rows
+    ]
+    _emit({"success": True, "count": len(sites), "sites": sites})
     return 0
 
 
@@ -1060,12 +1068,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     _add_index_embedding_flags(erase)
     erase.add_argument("--yes", action="store_true", help="Confirm destructive deletion (required in CI)")
-    erase.add_argument(
-        "--quiet", "-q",
-        action="store_true",
-        dest="quiet",
-        help="Suppress stderr progress relay; stdout payload unchanged.",
-    )
+    _add_verbosity_flags(erase)
     erase.set_defaults(handler=_cmd_erase)
 
     meta = subparsers.add_parser("meta", help="Print graph meta and embedding resolution.")
@@ -1162,8 +1165,20 @@ def _console_script_main() -> None:
     racy teardown — the command has already done its work and emitted its result.
     ``main()`` stays return-based so in-process test callers (``cli.main(...)``)
     keep working.
+
+    ``KeyboardInterrupt`` (Ctrl+C during a long indexing step) is caught here
+    rather than left to propagate: an uncaught interrupt bypasses this function
+    and runs full interpreter finalization (traceback + thread teardown),
+    whereas routing it through the same flush + ``os._exit`` path gives a clean,
+    immediate exit (code 130) and avoids the finalization-time SIGABRT noted
+    above for commands that loaded lancedb.
     """
-    rc = main()
+    try:
+        rc = main()
+    except KeyboardInterrupt:
+        sys.stderr.write("\nInterrupted.\n")
+        sys.stderr.flush()
+        rc = 130
     sys.stdout.flush()
     sys.stderr.flush()
     os._exit(rc)

{java_codebase_rag-0.9.6 → java_codebase_rag-0.10.0}/src/java_codebase_rag/config.py

@@ -378,6 +378,14 @@ class ResolvedOperatorConfig:
     # used with no config file). Recorded into the index dir at index time so a
     # later discovery run from a sibling/cwd can relocate this config.
     yaml_config_path: Path | None = None
+    # ``watch:`` block knobs (jrag watch / watcher). Defaults make the block
+    # optional; no env vars are introduced for these (CLI flag > YAML > default).
+    watch_debounce_ms: int = 1500
+    watch_backend: str = "auto"
+    watch_poll_interval_ms: int = 2000
+    watch_debounce_ms_source: SettingSource = "default"
+    watch_backend_source: SettingSource = "default"
+    watch_poll_interval_ms_source: SettingSource = "default"
 
     def apply_to_os_environ(self) -> None:
         """Make downstream modules (server, ladybug_queries, flows) see a consistent environment.
@@ -506,16 +514,20 @@ def _pick_float(
 
 def _pick_int(
     *,
+    cli_val: int | None = None,
     env_key: str,
     yaml_dict: dict[str, Any],
     yaml_path: tuple[str, ...],
     default: int,
 ) -> tuple[int, SettingSource]:
-    """Pick an int setting from env (parsed via int(...)), YAML, or default.
+    """Pick an int setting from CLI, env (parsed via int(...)), YAML, or default.
 
     Precedence: CLI > env > YAML > default. Env values that fail to parse as int
     fall back to the default (matching the brief's requirement for graceful degradation).
+    ``cli_val`` defaults to ``None`` so existing callers are unaffected.
     """
+    if cli_val is not None:
+        return int(cli_val), "cli"
     env_raw = os.environ.get(env_key, "").strip()
     if env_raw:
         try:
@@ -577,6 +589,9 @@ def resolve_operator_config(
     cli_index_dir: str | None = None,
     cli_embedding_model: str | None = None,
     cli_embedding_device: str | None = None,
+    cli_watch_debounce_ms: int | None = None,
+    cli_watch_backend: str | None = None,
+    cli_watch_poll_interval_ms: int | None = None,
 ) -> ResolvedOperatorConfig:
     # Phase 1: Find the config file directory
     if source_root is not None:
@@ -671,6 +686,52 @@ def resolve_operator_config(
         yaml_path=("absence", "diag_enabled"),
         default=True,
     )
+    # ``watch:`` block knobs. No env vars are introduced for watch (CLI > YAML >
+    # default), so an empty env_key is passed to the ``_pick_*`` helpers —
+    # ``os.environ.get("", "")`` never matches, leaving the env tier inert.
+    w_debounce, w_debounce_src = _pick_int(
+        cli_val=cli_watch_debounce_ms,
+        env_key="",
+        yaml_dict=yaml_dict,
+        yaml_path=("watch", "debounce_ms"),
+        default=1500,
+    )
+    w_backend, w_backend_src = _pick_str(
+        cli_val=cli_watch_backend,
+        env_key="",
+        yaml_dict=yaml_dict,
+        yaml_path=("watch", "backend"),
+        default="auto",
+    )
+    w_poll, w_poll_src = _pick_int(
+        cli_val=cli_watch_poll_interval_ms,
+        env_key="",
+        yaml_dict=yaml_dict,
+        yaml_path=("watch", "poll_interval_ms"),
+        default=2000,
+    )
+    # Inline floors/validation (mirror the existing graceful-degradation style).
+    if w_debounce < 100:
+        print(
+            f"java-codebase-rag: watch.debounce_ms={w_debounce} is below the 100 ms "
+            "floor; falling back to 1500.",
+            file=sys.stderr,
+        )
+        w_debounce, w_debounce_src = 1500, "default"
+    if w_backend not in ("auto", "watchdog", "polling"):
+        print(
+            f"java-codebase-rag: watch.backend={w_backend!r} is not one of "
+            "auto/watchdog/polling; falling back to 'auto'.",
+            file=sys.stderr,
+        )
+        w_backend, w_backend_src = "auto", "default"
+    if w_poll < 200:
+        print(
+            f"java-codebase-rag: watch.poll_interval_ms={w_poll} is below the 200 ms "
+            "floor; falling back to 2000.",
+            file=sys.stderr,
+        )
+        w_poll, w_poll_src = 2000, "default"
     ku = index_dir / "code_graph.lbug"
     coco = index_dir / "cocoindex.db"
     return ResolvedOperatorConfig(
@@ -696,6 +757,12 @@ def resolve_operator_config(
         absence_ngram_q_source=abs_q_src,
         absence_diag_enabled_source=abs_diag_src,
         yaml_config_path=find_yaml_config_file(config_dir),
+        watch_debounce_ms=w_debounce,
+        watch_backend=w_backend,
+        watch_poll_interval_ms=w_poll,
+        watch_debounce_ms_source=w_debounce_src,
+        watch_backend_source=w_backend_src,
+        watch_poll_interval_ms_source=w_poll_src,
     )