java-codebase-rag 0.6.0__tar.gz → 0.6.1__tar.gz

{java_codebase_rag-0.6.0/java_codebase_rag.egg-info → java_codebase_rag-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.6.0
+Version: 0.6.1
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
@@ -35,6 +35,7 @@ Requires-Dist: unidiff<1,>=0.7.3
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-xdist>=3; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
 Dynamic: license-file
 

{java_codebase_rag-0.6.0 → java_codebase_rag-0.6.1}/ast_java.py

@@ -13,6 +13,7 @@ Python with no tree-sitter dependency.
 from __future__ import annotations
 
 import posixpath
+import sys
 from dataclasses import dataclass, field
 from functools import lru_cache
 from typing import Iterable
@@ -1642,9 +1643,17 @@ def _parse_codebase_http_client_annotation(
     pairs, _ = _annotation_kv_nodes(ann, src)
     client_kind = ""
     if "clientKind" in pairs:
-        val, _kind = _annotation_value(pairs["clientKind"], src)
-        if val and _kind == "enum":
-            client_kind = str(val)
+        val, vkind = _annotation_value(pairs["clientKind"], src)
+        if val and vkind == "enum":
+            kind_val = str(val)
+            from java_ontology import VALID_CLIENT_KINDS  # deferred: java_ontology imports ast_java
+            if kind_val in VALID_CLIENT_KINDS:
+                client_kind = kind_val
+            else:
+                print(
+                    f"[lancedb-mcp] CodebaseHttpClient: invalid clientKind {kind_val!r} — ignored",
+                    file=sys.stderr,
+                )
     target_service = ""
     if "targetService" in pairs:
         atoms = _string_value_atoms(pairs["targetService"], src, ctx)
@@ -1714,9 +1723,17 @@ def _parse_codebase_producer_annotation(
     client_kind = "kafka_send"
     kind_node = pairs.get("producerKind") or pairs.get("clientKind")
     if kind_node is not None:
-        val, _kind = _annotation_value(kind_node, src)
-        if val and _kind == "enum":
-            client_kind = str(val)
+        val, vkind = _annotation_value(kind_node, src)
+        if val and vkind == "enum":
+            kind_val = str(val)
+            from java_ontology import VALID_PRODUCER_KINDS  # deferred: java_ontology imports ast_java
+            if kind_val in VALID_PRODUCER_KINDS:
+                client_kind = kind_val
+            else:
+                print(
+                    f"[lancedb-mcp] CodebaseProducer: invalid producerKind {kind_val!r} — ignored",
+                    file=sys.stderr,
+                )
     topic = ""
     if "topic" in pairs:
         atoms = _string_value_atoms(pairs["topic"], src, ctx)

{java_codebase_rag-0.6.0 → java_codebase_rag-0.6.1}/build_ast_graph.py

@@ -3668,10 +3668,17 @@ def incremental_rebuild(
 
 
 def _init_hash_tracker(source_root: Path, ladybug_path: Path) -> int:
-    """Initialize hash tracker for all Java files. Returns number of files hashed."""
+    """Initialize hash tracker for all Java files. Returns number of files hashed.
+
+    Called right after a full graph rebuild (``write_ladybug``), so the store must
+    mirror exactly the files that were just indexed. We deliberately do NOT
+    ``load()`` the existing store: ``update`` re-hashes every current file anyway,
+    and preserving old entries would leave stale hashes for files that no longer
+    exist (deleted or now-ignored). Those ghosts would be re-detected as "removed"
+    on every subsequent ``increment``, sustaining an endless full-rebuild loop.
+    """
     index_dir = ladybug_path.parent
     tracker = FileHashTracker(index_dir)
-    tracker.load()
     ignore = LayeredIgnore(source_root)
     all_files: set[str] = set()
     source_root_resolved = source_root.resolve()
@@ -3742,7 +3749,7 @@ def _write_clients_producers_and_calls(conn: ladybug.Connection, tables: GraphTa
 
     # Write declares_client edges
     for row in tables.declares_client_rows:
-        source_file = member_by_id.get(row.symbol_id, MemberEntry(kind="", decl=None, parent_id="", parent_fqn="", file_path="", module="", microservice="")).file_path
+        source_file = member_by_id.get(row.symbol_id, MemberEntry(kind="", decl=None, parent_id="", parent_fqn="", file_path="", module="", microservice="", node_id="")).file_path
         conn.execute(_CREATE_DECLARES_CLIENT, {
             "sid": row.symbol_id,
             "cid": row.client_id,
@@ -3753,7 +3760,7 @@ def _write_clients_producers_and_calls(conn: ladybug.Connection, tables: GraphTa
 
     # Write declares_producer edges
     for row in tables.declares_producer_rows:
-        source_file = member_by_id.get(row.symbol_id, MemberEntry(kind="", decl=None, parent_id="", parent_fqn="", file_path="", module="", microservice="")).file_path
+        source_file = member_by_id.get(row.symbol_id, MemberEntry(kind="", decl=None, parent_id="", parent_fqn="", file_path="", module="", microservice="", node_id="")).file_path
         conn.execute(_CREATE_DECLARES_PRODUCER, {
             "sid": row.symbol_id,
             "pid": row.producer_id,

{java_codebase_rag-0.6.0 → java_codebase_rag-0.6.1}/java_codebase_rag/config.py

@@ -306,9 +306,19 @@ def _pick_bool(
 def _resolve_index_dir_path(
     *,
     source_root: Path,
+    config_dir: Path,
     cli_index_dir: str | None,
     yaml_dict: dict[str, Any],
 ) -> tuple[Path, SettingSource]:
+    # Bases for relative paths:
+    #   - YAML ``index_dir``  -> the config file's directory (``config_dir``),
+    #     the SAME base used for YAML ``source_root``. Paths written in the
+    #     config file are relative to the file, so both keys stay consistent.
+    #   - CLI / env ``index_dir`` -> ``source_root`` (unchanged). These are not
+    #     "in the config file"; preserving the existing base avoids a semantics
+    #     change for operators who pass ``--index-dir`` on the command line.
+    #   - Default ``./.java-codebase-rag`` -> ``source_root`` so the index sits
+    #     beside the Java tree (the layout ``discover_project_root`` anchors on).
     raw_cli = cli_index_dir.strip() if isinstance(cli_index_dir, str) else None
     if raw_cli:
         p = Path(raw_cli).expanduser()
@@ -324,7 +334,7 @@ def _resolve_index_dir_path(
     idx = yaml_dict.get("index_dir")
     if isinstance(idx, str) and idx.strip():
         p = Path(idx.strip()).expanduser()
-        out = p.resolve() if p.is_absolute() else (source_root / p).resolve()
+        out = p.resolve() if p.is_absolute() else (config_dir / p).resolve()
         return out, "yaml"
 
     return (source_root / ".java-codebase-rag").resolve(), "default"
@@ -368,7 +378,7 @@ def resolve_operator_config(
                 root = config_dir
 
     index_dir, index_src = _resolve_index_dir_path(
-        source_root=root, cli_index_dir=cli_index_dir, yaml_dict=yaml_dict
+        source_root=root, config_dir=config_dir, cli_index_dir=cli_index_dir, yaml_dict=yaml_dict
     )
     model, model_src = _pick_str(
         cli_val=cli_embedding_model,

{java_codebase_rag-0.6.0 → java_codebase_rag-0.6.1/java_codebase_rag.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.6.0
+Version: 0.6.1
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
@@ -35,6 +35,7 @@ Requires-Dist: unidiff<1,>=0.7.3
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-xdist>=3; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
 Dynamic: license-file
 

{java_codebase_rag-0.6.0 → java_codebase_rag-0.6.1}/java_codebase_rag.egg-info/requires.txt

@@ -16,4 +16,5 @@ unidiff<1,>=0.7.3
 [dev]
 pytest>=7
 pytest-asyncio>=0.21
+pytest-xdist>=3
 ruff>=0.4

{java_codebase_rag-0.6.0 → java_codebase_rag-0.6.1}/java_ontology.py

@@ -15,7 +15,10 @@ from ast_java import (
     _TYPE_ANN_TO_CAPABILITY,
 )
 
-# Roles: Spring stereotype values plus DTO from `infer_role_for_type`.
+# Roles assignable by indexing: Spring stereotype values plus DTO. ``OTHER`` is the
+# built-in inference fallback (ast_java.infer_role when nothing matches) and is
+# deliberately excluded here — it is a read-side value (the mcp_v2 ``Role`` enum
+# includes it) but not a role a user may set via @CodebaseRole / role_overrides.
 VALID_ROLES: frozenset[str] = frozenset((*ROLE_ANNOTATIONS.values(), "DTO"))
 
 VALID_CAPABILITIES: frozenset[str] = frozenset(

{java_codebase_rag-0.6.0 → java_codebase_rag-0.6.1}/mcp_v2.py

@@ -48,6 +48,22 @@ def _hints_or_skip(tool: str, payload: dict) -> tuple[list, list]:
 
 DeclarationSymbolKind = Literal["class", "interface", "enum", "record", "annotation", "method", "constructor"]
 
+# Closed value taxonomies surfaced to MCP consumers as enums. Sources of truth:
+#   Role         — VALID_ROLES in java_ontology.py + the "OTHER" inference fallback (ast_java.infer_role)
+#   Framework    — hardcoded literals across ast_java.py / build_ast_graph.py
+#   SourceLayer  — exhaustive classifier build_ast_graph._client_source_layer / _producer_source_layer
+#   ClientKind   — VALID_CLIENT_KINDS in java_ontology.py (every producer validated at index time)
+#   ProducerKind — VALID_PRODUCER_KINDS in java_ontology.py (every producer validated at index time)
+# Keep these in sync with the indexing-side taxonomies if they change.
+Role = Literal[
+    "CONTROLLER", "SERVICE", "REPOSITORY", "COMPONENT", "CONFIG",
+    "ENTITY", "CLIENT", "MAPPER", "DTO", "OTHER",
+]
+Framework = Literal["spring_mvc", "webflux", "kafka", "rabbitmq", "jms", "stream", "feign", ""]
+SourceLayer = Literal["builtin", "layer_a_meta", "layer_b_ann", "layer_b_fqn", "layer_c_source"]
+ClientKind = Literal["feign_method", "rest_template", "web_client"]
+ProducerKind = Literal["kafka_send", "stream_bridge_send"]
+
 # Stored graph edge labels for one-hop neighbors. Composed DECLARES.* and OVERRIDDEN_BY.*
 # dot-keys are separate ComposedEdgeType literals (2-hop traversal). Stored OVERRIDES is an EdgeType.
 EdgeType = Literal[
@@ -133,21 +149,30 @@ class NodeFilter(BaseModel):
 
     microservice: str | None = None
     module: str | None = None
-    source_layer: str | None = None
-    role: str | None = None
-    exclude_roles: list[str] | None = None
+    source_layer: SourceLayer | None = None
+    role: Role | None = None
+    exclude_roles: list[Role] | None = None
     annotation: str | None = None
     capability: str | None = None
     fqn_prefix: str | None = None
     symbol_kind: DeclarationSymbolKind | None = None
     symbol_kinds: list[DeclarationSymbolKind] | None = None
-    http_method: str | None = None
+    http_method: str | None = Field(
+        default=None,
+        description="HTTP verb (commonly GET/POST/PUT/DELETE/PATCH; user route annotations may yield others).",
+    )
     path_prefix: str | None = None
-    framework: str | None = None
-    client_kind: str | None = None
+    framework: Framework | None = None
+    client_kind: ClientKind | None = Field(
+        default=None,
+        description="Outbound HTTP client kind: feign_method, rest_template, or web_client.",
+    )
     target_service: str | None = None
     target_path_prefix: str | None = None
-    producer_kind: str | None = None
+    producer_kind: ProducerKind | None = Field(
+        default=None,
+        description="Outbound async producer kind: kafka_send or stream_bridge_send.",
+    )
     topic_prefix: str | None = None
 
 
@@ -157,9 +182,9 @@ class EdgeFilter(BaseModel):
     min_confidence: float | None = None
     exclude_strategies: list[str] | None = None
     include_strategies: list[str] | None = None
-    callee_declaring_role: str | None = None
-    callee_declaring_roles: list[str] | None = None
-    exclude_callee_declaring_roles: list[str] | None = None
+    callee_declaring_role: Role | None = None
+    callee_declaring_roles: list[Role] | None = None
+    exclude_callee_declaring_roles: list[Role] | None = None
 
     @model_validator(mode="after")
     def _strategy_axes_mutually_exclusive(self) -> EdgeFilter:

{java_codebase_rag-0.6.0 → java_codebase_rag-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "java-codebase-rag"
-version = "0.6.0"
+version = "0.6.1"
 description = "MCP server for semantic + structural search over Java codebases"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -43,6 +43,7 @@ dependencies = [
 dev = [
     "pytest>=7",
     "pytest-asyncio>=0.21",
+    "pytest-xdist>=3",
     "ruff>=0.4",
 ]
 

{java_codebase_rag-0.6.0 → java_codebase_rag-0.6.1}/server.py

@@ -7,7 +7,7 @@ import os
 import sys
 import time
 from pathlib import Path
-from typing import Any, Literal
+from typing import Literal
 
 import mcp_v2
 from index_common import SBERT_MODEL
@@ -31,14 +31,14 @@ from search_lancedb import TABLES
 
 _COCOINDEX_TARGET = "java_index_flow_lancedb.py:JavaCodeIndexLance"
 _INSTRUCTIONS = (
-    "Java codebase graph navigator (LanceDB + Ladybug). "
+    "Java codebase graph navigator over an indexed Java codebase. "
     "Tools: search (NL/code locate), find (structured NodeFilter), describe (one node + edge_summary: stored edge-label counts and optional composed keys for type Symbols and override-axis virtual keys for method Symbols), "
     "neighbors (one hop; you MUST pass direction in|out AND edge_types list — no defaults), "
-    "resolve (identifier-shaped lookup for symbol/route/client/producer — three statuses one|many/none). "
-    "NodeFilter `filter` is a JSON object (preferred); a JSON-encoded string is also accepted as a fallback. "
+    "resolve (identifier-shaped lookup for symbol/route/client/producer — three statuses: one | many | none). "
     "Unknown filter keys and populated fields not applicable to the effective node kind fail with success=false and message. "
+    "Successful responses from any tool may include `hints_structured` (tool call suggestions with a `reason` field) and `advisories` (pure informational text) when hints are enabled. "
     "Edge labels: EXTENDS, IMPLEMENTS, INJECTS, OVERRIDES, DECLARES, DECLARES_CLIENT, DECLARES_PRODUCER, CALLS, EXPOSES, HTTP_CALLS, ASYNC_CALLS; "
-    "type Symbols may also use composed neighbors edge_types DECLARES.DECLARES_CLIENT, DECLARES.DECLARES_PRODUCER, DECLARES.EXPOSES (out only). "
+    "type Symbols may also use composed neighbors edge_types DECLARES.DECLARES_CLIENT, DECLARES.DECLARES_PRODUCER, DECLARES.EXPOSES (out only, type Symbol origin). "
     "Reprocess/init, meta, tables, diagnose-ignore, analyze-pr: use java-codebase-rag CLI — not MCP."
 )
 
@@ -123,19 +123,15 @@ class ScopeManager:
             print("[scope] No microservice detected (at project root)", file=sys.stderr)
             print("[scope] Queries will span all microservices", file=sys.stderr)
 
-    def apply_auto_scope(self, node_filter: dict[str, Any] | None) -> dict[str, Any] | None:
+    def apply_auto_scope(self, node_filter: mcp_v2.NodeFilter | None) -> mcp_v2.NodeFilter | None:
         """Apply auto-detected scope to filter if no explicit microservice is set."""
         if self.default_scope is None:
             return node_filter
-        # Convert to dict for manipulation
         if node_filter is None:
-            filter_dict = {}
-        else:
-            filter_dict = dict(node_filter)
-        # Only inject if user didn't specify microservice
-        if "microservice" not in filter_dict:
-            filter_dict["microservice"] = self.default_scope
-        return filter_dict
+            return mcp_v2.NodeFilter(microservice=self.default_scope)
+        if node_filter.microservice is None:
+            return node_filter.model_copy(update={"microservice": self.default_scope})
+        return node_filter
 
 
 def _resolve_lancedb_uri() -> str:
@@ -159,6 +155,27 @@ def _project_root() -> Path:
     return discovered if discovered is not None else Path.cwd().resolve()
 
 
+def _source_root_for_operator_config() -> Path | None:
+    """``source_root`` arg to hand ``resolve_operator_config`` from the MCP server.
+
+    Returns ``JAVA_CODEBASE_RAG_SOURCE_ROOT`` when set (an explicit operator
+    override that wins and suppresses the YAML ``source_root`` field, exactly
+    like CLI ``--source-root``), otherwise ``None`` — so
+    ``resolve_operator_config`` runs its OWN walk-up discovery and HONORS the
+    YAML ``source_root`` field, matching the CLI (``init`` / ``increment`` /
+    ``reprocess``) path.
+
+    Do NOT pass ``_project_root()`` (the walk-up-discovered dir) here: a
+    non-``None`` value routes into the "explicit source root" branch that
+    skips the YAML ``source_root`` field, which made the MCP server and the
+    CLI resolve different ``source_root`` / ``index_dir`` from the same config
+    file (the init-vs-MCP index_dir divergence). ``_project_root()`` is kept
+    only for the ``_resolve_lancedb_uri()`` fallback below.
+    """
+    env = os.environ.get("JAVA_CODEBASE_RAG_SOURCE_ROOT", "").strip()
+    return Path(env).expanduser().resolve() if env else None
+
+
 def _cocoindex_subprocess_env(project_root: Path) -> dict[str, str]:
     sub_env = os.environ.copy()
     sub_env["JAVA_CODEBASE_RAG_SOURCE_ROOT"] = str(project_root)
@@ -413,14 +430,15 @@ def create_mcp_server() -> FastMCP:
     @mcp.tool(
         name="search",
         description=(
-            "Ranked chunk retrieval: `query` is opaque text (natural language or code fragments); "
-            "results are score-ranked, not boolean-matched. Optional `filter` uses the same NodeFilter "
-            "schema as `find` but only **symbol-applicable** fields apply (strict frame). Wildcards "
+            "Ranked chunk retrieval over content tables (java/sql/yaml); `query` is opaque text (natural language or code "
+            "fragments) and results are score-ranked, not boolean-matched. For graph-structured listing "
+            "(symbols/routes/clients/producers) use `find`, not `search`. Optional `filter` uses the same NodeFilter "
+            "schema as `find` but only **symbol-applicable** fields apply — others return success=false. Wildcards "
             "(`*`, `?`) in prefix fields are rejected—use ranked `query` text instead. There is **no** "
             "structured DSL inside `query`; structured predicates belong in `find`. "
             "For identifier-shaped lookups (FQN, id prefix, route/client identifiers, …), use `resolve` first; "
             "use `search` for natural-language or ranked fuzzy discovery. "
-            "Successful responses echo `limit`/`offset` and may include `hints_structured` (tool call suggestions with `reason` field) and `advisories` (pure informational text)."
+            "Successful responses echo `limit`/`offset`."
         ),
     )
     async def search(
@@ -431,7 +449,7 @@ def create_mcp_server() -> FastMCP:
         ),
         hybrid: bool = Field(
             default=False,
-            description="If true, fuse FTS + vector (single-table java/sql/yaml only)",
+            description="If true, fuse FTS + vector. Requires a single table (java/sql/yaml); hybrid with table='all' returns success=false.",
         ),
         limit: int = Field(default=5, ge=1, le=50, description="Max hits to return"),
         offset: int = Field(default=0, ge=0, le=500, description="Skip this many hits (pagination)"),
@@ -439,11 +457,11 @@ def create_mcp_server() -> FastMCP:
             default=None,
             description="Substring match on file path (pre-filter from index)",
         ),
-        filter: dict[str, Any] | str | None = Field(
+        filter: mcp_v2.NodeFilter | None = Field(
             default=None,
             description=(
-                "Optional NodeFilter post-filter on symbol-oriented hit rows. Unknown keys or populated fields not "
-                "applicable to symbols return success=false. Prefer a JSON object; a JSON-encoded string is accepted."
+                "Optional NodeFilter post-filter on symbol-oriented hit rows. An empty object or omitted means no "
+                "predicate. Unknown keys or populated fields not applicable to symbols return success=false."
             ),
         ),
     ) -> mcp_v2.SearchOutput:
@@ -468,9 +486,11 @@ def create_mcp_server() -> FastMCP:
             "**route** — microservice, module, http_method, path_prefix, framework; **client** — microservice, module, "
             "source_layer, client_kind, target_service, target_path_prefix, http_method; **producer** — microservice, "
             "module, source_layer, producer_kind, topic_prefix. "
+            "`role` is singular and `exclude_roles` plural; `capability` is a functional tag assigned during indexing. "
+            "`fqn_prefix` is a prefix predicate — for exact FQN or id lookup use `resolve`/`describe`. "
             "Wildcards in prefix fields are rejected. An empty filter (`{}`) or `filter=None` means no predicate (all nodes of "
             "that kind; use pagination). Unknown keys or inapplicable populated fields return success=false. "
-            "Successful responses echo `limit`/`offset` and may include `hints_structured` (tool call suggestions with `reason` field) and `advisories` (pure informational text)."
+            "Successful responses echo `limit`/`offset`."
         ),
     )
     async def find(
@@ -481,11 +501,10 @@ def create_mcp_server() -> FastMCP:
                 "'producer' = outbound async producers."
             )
         ),
-        filter: dict[str, Any] | str = Field(
+        filter: mcp_v2.NodeFilter = Field(
             ...,
             description=(
-                "Required NodeFilter dict (extra keys forbidden). Fields must be applicable to `kind`. "
-                "Prefer a JSON object; a JSON-encoded string is accepted."
+                "Required NodeFilter object (extra keys forbidden). Fields must be applicable to `kind`."
             ),
         ),
         limit: int = Field(default=25, ge=1, le=500, description="Max nodes to return"),
@@ -497,17 +516,14 @@ def create_mcp_server() -> FastMCP:
     @mcp.tool(
         name="describe",
         description=(
-            "Full node record plus `edge_summary` (in/out counts per stored edge label, plus optional describe-time keys). Type Symbols may add "
-            "composed keys DECLARES.DECLARES_CLIENT, DECLARES.DECLARES_PRODUCER, and DECLARES.EXPOSES (navigable on type Symbols via neighbors, out only); "
-            "method Symbols may add override-axis virtual keys (OVERRIDDEN_BY, OVERRIDDEN_BY.DECLARES_CLIENT, OVERRIDDEN_BY.DECLARES_PRODUCER, "
-            "OVERRIDDEN_BY.EXPOSES, plus an `OVERRIDES` map entry that merges stored `[:OVERRIDES]` counts with the dispatch-up rollup per direction). "
-            "Override-axis virtual keys are navigable via neighbors on non-static method Symbol origins "
-            "(out only; composed keys include via_id in attrs). The stored `OVERRIDES` relationship "
-            "is also a normal edge label (e.g. direction in from declaration toward overriders). "
+            "Full node record plus `edge_summary` (in/out counts per stored edge label). For type Symbols, `edge_summary` "
+            "also exposes composed keys (DECLARES.DECLARES_CLIENT, DECLARES.DECLARES_PRODUCER, DECLARES.EXPOSES); for "
+            "non-static method Symbols it adds override-axis virtual keys (OVERRIDDEN_BY and its composed forms, plus an "
+            "`OVERRIDES` map merging stored `[:OVERRIDES]` counts with the dispatch-up rollup). These composed/override keys "
+            "are out-only and navigable via `neighbors`; the stored `OVERRIDES` is also a normal edge label (in toward declaration). "
             "Pass `id` for any kind, or exact `fqn` for Symbol lookup (`id` wins when both are set). "
             "`describe(fqn=…)` keeps the first graph row when multiple symbols share that FQN; when an FQN may collide, "
-            "prefer `resolve(identifier=…, hint_kind='symbol')` first, then `describe(id=…)` on the chosen node. "
-            "Successful responses may include `hints_structured` (tool call suggestions with `reason` field) and `advisories` (pure informational text)."
+            "prefer `resolve(identifier=…, hint_kind='symbol')` first, then `describe(id=…)` on the chosen node."
         ),
     )
     async def describe(
@@ -531,18 +547,19 @@ def create_mcp_server() -> FastMCP:
     @mcp.tool(
         name="neighbors",
         description=(
-            "Graph walk: **direction** (`in` | `out`) and non-empty **edge_types** are required (stored labels for one hop; "
-            "type Symbol origins may also pass composed DECLARES.DECLARES_CLIENT, DECLARES.DECLARES_PRODUCER, or DECLARES.EXPOSES "
-            "for 2-hop member rollups; method Symbol origins may pass OVERRIDDEN_BY, OVERRIDDEN_BY.DECLARES_CLIENT, "
-            "OVERRIDDEN_BY.DECLARES_PRODUCER, OVERRIDDEN_BY.EXPOSES for override-axis rollups — out only, via_id in "
-            "attrs on composed keys). "
+            "Graph walk: **direction** (`in` | `out`) and non-empty **edge_types** are required (one hop over stored edge "
+            "labels; type/method Symbol origins may also pass composed or override-axis keys — see `edge_types`). From a "
+            "type Symbol, `direction='out'` with EXPOSES yields route nodes and HTTP_CALLS/ASYNC_CALLS yield client/producer "
+            "nodes; `direction='in'` reverses each relationship. "
+            "`direction` and `edge_types` have no defaults; an empty `edge_types` fails. The CALLS-only features — "
+            "`edge_filter`, `include_unresolved`, `dedup_calls` — each require `edge_types=['CALLS']`; `edge_filter` and "
+            "`include_unresolved` are mutually exclusive. Violating a precondition (wrong CALLS context, composed/override "
+            "keys on an ineligible origin or with `direction='in'`, wildcards in prefix fields, unknown filter keys) returns "
+            "success=false with a message; `dedup_calls` with other edge_types is a silent no-op. "
             "Optional `filter` applies to each neighbor endpoint row; populated fields must be applicable to that "
-            "neighbor's kind—mixed-kind result sets fail on the first inapplicable neighbor (strict frame). "
-            "Optional `edge_filter` requires edge_types=['CALLS'] only (no composed dot-keys or extra stored "
-            "labels); projects the ordered CALLS stream by edge attributes (min_confidence, strategies, "
-            "callee_declaring_role). Wildcards in prefix fields are rejected. Unknown filter keys return success=false. "
-            "Successful responses echo `requested_edge_types` and may include `hints_structured` (tool call suggestions with `reason` field) and `advisories` (pure informational text). "
-            "Each edge's `attrs.strategy` indicates resolution quality (brownfield/fallback vs primary paths)."
+            "neighbor's kind—mixed-kind result sets fail on the first inapplicable neighbor (per-neighbor strict frame). "
+            "Each edge's `attrs.strategy` indicates resolution quality (brownfield/fallback vs primary paths). "
+            "Successful responses echo `requested_edge_types`."
         ),
     )
     async def neighbors(
@@ -573,19 +590,19 @@ def create_mcp_server() -> FastMCP:
             le=1000,
             description="Skip this many edges after merge (pagination)",
         ),
-        filter: dict[str, Any] | str | None = Field(
+        filter: mcp_v2.NodeFilter | None = Field(
             default=None,
             description=(
-                "Optional NodeFilter on the neighbor node. Same applicability rules as `find` for that node's kind. "
-                "Prefer a JSON object; a JSON-encoded string is accepted."
+                "Optional NodeFilter on the neighbor node. An empty object or omitted means no predicate. "
+                "Same applicability rules as `find` for that node's kind."
             ),
         ),
-        edge_filter: dict[str, Any] | str | None = Field(
+        edge_filter: mcp_v2.EdgeFilter | None = Field(
             default=None,
             description=(
                 "Optional EdgeFilter on CALLS edge attributes (edge_types=['CALLS'] only). Use "
                 "callee_declaring_role for callee stereotype projection — not NodeFilter.role on method neighbors. "
-                "Mutually exclusive with include_unresolved. Prefer a JSON object; a JSON-encoded string is accepted."
+                "Mutually exclusive with include_unresolved."
             ),
         ),
         include_unresolved: bool = Field(
@@ -627,10 +644,11 @@ def create_mcp_server() -> FastMCP:
             "status=one (single node), many (≥2 ranked candidates with reason), or none "
             "(no match — fall back to search(query=...) for natural language or fuzzy text). "
             "Optional hint_kind narrows to symbol, route, client, or producer. "
-            "Successful responses may include hints_structured (tool call suggestions with `reason` field) and advisories (pure informational text) — same contract as other v2 tools. "
             "Malformed empty/whitespace identifier returns success=false. "
             "Examples: resolve('com.foo.Bar', hint_kind='symbol'); "
             "resolve('GET /api/v1/customers', hint_kind='route'); "
+            "resolve('PaymentClient', hint_kind='client'); "
+            "resolve('order.created', hint_kind='producer'); "
             "resolve('the client that handles assignments') → none (use search instead)."
         ),
     )
@@ -657,7 +675,7 @@ def main() -> None:
     # Load YAML config and apply embedding settings to environment
     # This ensures SBERT_MODEL and SBERT_DEVICE from .java-codebase-rag.yml are available
     # before any tool handler runs (same behavior as CLI path)
-    cfg = resolve_operator_config(source_root=_project_root())
+    cfg = resolve_operator_config(source_root=_source_root_for_operator_config())
     cfg.apply_to_os_environ()
     mcp_v2.set_hints_enabled(cfg.hints_enabled)
 

{java_codebase_rag-0.6.0 → java_codebase_rag-0.6.1}/tests/test_brownfield_clients.py

@@ -254,6 +254,63 @@ http_client_overrides:
     assert _http_calls(db) == []
 
 
+def _client_kinds(db_path: Path) -> list[str]:
+    db = ladybug.Database(str(db_path), read_only=True)
+    conn = ladybug.Connection(db)
+    r = conn.execute("MATCH (c:Client) RETURN c.client_kind AS client_kind")
+    out: list[str] = []
+    while r.has_next():
+        out.append(str(r.get_next()[0] or ""))
+    return out
+
+
+def _producer_kinds(db_path: Path) -> list[str]:
+    db = ladybug.Database(str(db_path), read_only=True)
+    conn = ladybug.Connection(db)
+    r = conn.execute("MATCH (p:Producer) RETURN p.producer_kind AS producer_kind")
+    out: list[str] = []
+    while r.has_next():
+        out.append(str(r.get_next()[0] or ""))
+    return out
+
+
+def test_29a_unknown_source_client_kind_warns_and_ignored(tmp_path: Path) -> None:
+    """In-source @CodebaseHttpClient(clientKind=<invalid enum>) is validated at parse
+    time (source-annotation mirror of the YAML-side test_29): the bad value is ignored
+    and a warning is emitted, so client_kind stays a closed set safe to surface as an enum."""
+    java = {
+        "p/X.java": (
+            "package p; import com.example.rag.*; class X { "
+            "@CodebaseHttpClient(clientKind=CodebaseClientKind.bogus, path=\"/bad\", method=CodebaseHttpMethod.GET) "
+            "void m() {} }"
+        ),
+    }
+    buf = io.StringIO()
+    with redirect_stderr(buf):
+        db = _build(tmp_path, None, java)
+    assert "invalid clientkind" in buf.getvalue().lower()
+    assert "bogus" not in _client_kinds(db)
+
+
+def test_29b_unknown_source_producer_kind_warns_and_falls_back(tmp_path: Path) -> None:
+    """In-source @CodebaseProducer(producerKind=<invalid enum>) is validated at parse
+    time: the bad value is ignored with a warning and producer_kind falls back to the
+    kafka_send default."""
+    java = {
+        "p/X.java": (
+            "package p; import com.example.rag.*; class X { "
+            "@CodebaseProducer(topic=\"t\", producerKind=CodebaseProducerKind.bogus) void m() {} }"
+        ),
+    }
+    buf = io.StringIO()
+    with redirect_stderr(buf):
+        db = _build(tmp_path, None, java)
+    assert "invalid producerkind" in buf.getvalue().lower()
+    kinds = _producer_kinds(db)
+    assert "bogus" not in kinds
+    assert "kafka_send" in kinds
+
+
 def test_30_brownfield_percentage_counter(tmp_path: Path) -> None:
     java = {
         "p/X.java": (