java-codebase-rag 0.6.7__py3-none-any.whl → 0.8.0__py3-none-any.whl

ast_java.py

@@ -1868,6 +1868,11 @@ def _collect_outgoing_calls(
     file_rel: str,
 ) -> list[OutgoingCallDecl]:
     del project_root
+    from java_ontology import (  # deferred: java_ontology imports ast_java
+        CLIENT_KIND_FEIGN_METHOD,
+        CLIENT_KIND_REST_TEMPLATE,
+        CLIENT_KIND_WEB_CLIENT,
+    )
     out: list[OutgoingCallDecl] = []
     method_fqn = f"{type_fqn}#{method_decl.signature}"
     type_mods = _find_modifiers_child(type_node) if type_node is not None else None
@@ -1899,7 +1904,7 @@ def _collect_outgoing_calls(
             OutgoingCallDecl(
                 method_fqn=method_fqn,
                 method_sig=method_decl.signature,
-                client_kind="feign_method",
+                client_kind=CLIENT_KIND_FEIGN_METHOD,
                 channel="http",
                 feign_target_name=feign_target_name,
                 feign_target_url=feign_target_url,
@@ -1998,7 +2003,7 @@ def _collect_outgoing_calls(
                     OutgoingCallDecl(
                         method_fqn=method_fqn,
                         method_sig=method_decl.signature,
-                        client_kind="rest_template",
+                        client_kind=CLIENT_KIND_REST_TEMPLATE,
                         channel="http",
                         feign_target_name="",
                         feign_target_url="",
@@ -2051,7 +2056,7 @@ def _collect_outgoing_calls(
                     OutgoingCallDecl(
                         method_fqn=method_fqn,
                         method_sig=method_decl.signature,
-                        client_kind="web_client",
+                        client_kind=CLIENT_KIND_WEB_CLIENT,
                         channel="http",
                         feign_target_name="",
                         feign_target_url="",

build_ast_graph.py

@@ -66,7 +66,13 @@ from graph_enrich import (
     symbol_id,
 )
 from path_filtering import LayeredIgnore, iter_java_source_files
-from java_ontology import VALID_CLIENT_KINDS, VALID_HTTP_CALL_MATCHES, VALID_PRODUCER_KINDS
+from java_ontology import (
+    CLIENT_KIND_FEIGN_METHOD,
+    CLIENT_KIND_REST_TEMPLATE,
+    VALID_CLIENT_KINDS,
+    VALID_HTTP_CALL_MATCHES,
+    VALID_PRODUCER_KINDS,
+)
 
 log = logging.getLogger(__name__)
 
@@ -472,10 +478,26 @@ class IncrementalResult:
     elapsed_sec: float
 
 
+# --- Builder-owned files in the index dir (single source of truth) ---------------
+# Every artifact the graph builder writes next to code_graph.lbug. The lifecycle
+# CLI's `erase` clears all of these from one list so the builder and erase cannot
+# drift (issues #349 / #350): previously erase hardcoded ".graph_hashes.json" only
+# and left the crash marker (.graph_increment_in_progress) and the atomic-write
+# temp (.graph_hashes.json.tmp) behind on disk.
+GRAPH_HASHES_FILENAME = ".graph_hashes.json"
+GRAPH_HASHES_TMP_FILENAME = ".graph_hashes.json.tmp"
+GRAPH_INCREMENT_MARKER_FILENAME = ".graph_increment_in_progress"
+BUILDER_OWNED_INDEX_FILES: tuple[str, ...] = (
+    GRAPH_HASHES_FILENAME,
+    GRAPH_HASHES_TMP_FILENAME,
+    GRAPH_INCREMENT_MARKER_FILENAME,
+)
+
+
 class FileHashTracker:
     """Track content hashes for incremental graph rebuild."""
     def __init__(self, index_dir: Path):
-        self._path = index_dir / ".graph_hashes.json"
+        self._path = index_dir / GRAPH_HASHES_FILENAME
         self._hashes: dict[str, str] = {}  # rel_path -> sha256_hex
 
     def load(self) -> None:
@@ -491,7 +513,7 @@ class FileHashTracker:
 
     def save(self) -> None:
         """Persist hashes to disk atomically (write .tmp, rename)."""
-        tmp_path = self._path.with_suffix(".json.tmp")
+        tmp_path = self._path.parent / GRAPH_HASHES_TMP_FILENAME
         try:
             with open(tmp_path, "w", encoding="utf-8") as f:
                 json.dump(self._hashes, f, sort_keys=True)
@@ -576,7 +598,7 @@ def _load_existing_types(conn: ladybug.Connection, tables: GraphTables, exclude_
     query = f"""
     MATCH (s:Symbol)
     {where}
-    RETURN s.kind, s.fqn, s.name, s.filename, s.module, s.microservice, s.id
+    RETURN s.kind, s.fqn, s.name, s.filename, s.module, s.microservice, s.id, s.role
     """
     result = conn.execute(query, params)
     while result.has_next():
@@ -585,6 +607,7 @@ def _load_existing_types(conn: ladybug.Connection, tables: GraphTables, exclude_
         module = row[4] if len(row) > 4 else ""
         microservice = row[5] if len(row) > 5 else ""
         node_id = row[6] if len(row) > 6 else ""
+        role = row[7] if len(row) > 7 else ""
 
         decl = TypeDecl(name, kind, fqn)
         package = fqn[: -(len(name) + 1)] if fqn.endswith("." + name) else ""
@@ -602,6 +625,10 @@ def _load_existing_types(conn: ladybug.Connection, tables: GraphTables, exclude_
         tables.types[fqn] = entry
         tables.by_simple_name.setdefault(name, []).append(entry)
         tables.by_package.setdefault(package, []).append(entry)
+        # Seed the persisted role so the annotation-less stub is not recomputed to
+        # the default during node staging (issue #352 divergence #2).
+        if role:
+            tables.type_role_by_node_id[node_id] = role
 
 
 def _load_existing_members(conn: ladybug.Connection, tables: GraphTables, exclude_files: set[str] | None = None) -> None:
@@ -2382,7 +2409,7 @@ def pass5_imperative_edges(
                         )
                     rid = ""
                     strategy = call.resolution_strategy
-                    if call.client_kind == "feign_method":
+                    if call.client_kind == CLIENT_KIND_FEIGN_METHOD:
                         exposing = next((e for e in tables.exposes_rows if e.symbol_id == member.node_id), None)
                         if exposing is not None:
                             rid = exposing.route_id
@@ -2585,7 +2612,7 @@ def _match_call_edge(
         return "unresolved", []
 
     candidates: list[RouteRow] = []
-    if call.client_kind == "feign_method":
+    if call.client_kind == CLIENT_KIND_FEIGN_METHOD:
         # Prefer endpoint matching by target service + path/method for Feign declarations.
         path_value = call.path_template_call
         method_value = call.method_call
@@ -2714,7 +2741,7 @@ def pass6_match_edges(
             if src_route is None and member is not None:
                 # Recover feign caller hints from persisted caller-side Client declarations.
                 for client in client_hints_by_member.get(member.node_id, ()):
-                    if client.client_kind != "feign_method":
+                    if client.client_kind != CLIENT_KIND_FEIGN_METHOD:
                         continue
                     path_template, path_regex = _normalize_path(client.path)
                     src_route = RouteRow(
@@ -2750,7 +2777,7 @@ def pass6_match_edges(
             call = OutgoingCallDecl(
                 method_fqn=f"{member.parent_fqn}#{member.decl.signature}" if member else "",
                 method_sig=member.decl.signature if member else "",
-                client_kind="feign_method" if _feign_like else "rest_template",
+                client_kind=CLIENT_KIND_FEIGN_METHOD if _feign_like else CLIENT_KIND_REST_TEMPLATE,
                 channel="http",
                 feign_target_name=src_route.feign_name if src_route else "",
                 feign_target_url=src_route.feign_url if src_route else "",
@@ -3207,15 +3234,24 @@ def _write_nodes_impl(
         ))
     # types
     for entry in tables.types.values():
-        if entry.loaded_from_db:
-            stub_ids.add(entry.node_id)
         d = entry.decl
         role, capabilities = resolve_role_and_capabilities(
             d,
             overrides=overrides,
             meta_chain=mch,
         )
-        tables.type_role_by_node_id[entry.node_id] = role
+        if entry.loaded_from_db:
+            stub_ids.add(entry.node_id)
+            # Out-of-scope stub: its annotation-less decl collapses role to the
+            # default. The real node's role was persisted at index time and seeded
+            # into type_role_by_node_id by _load_existing_types; trust it so CALLS
+            # edges into this type keep the correct callee_declaring_role (#352).
+            # The staged row is filtered out of the write via stub_ids, so its
+            # capabilities placeholder never reaches the graph.
+            role = tables.type_role_by_node_id.get(entry.node_id, role)
+            capabilities = []
+        else:
+            tables.type_role_by_node_id[entry.node_id] = role
         rows.append(_node_row(
             id=entry.node_id, kind=d.kind, name=d.name, fqn=d.fqn,
             package=entry.package,
@@ -3424,13 +3460,15 @@ def _write_edges(conn: ladybug.Connection, tables: GraphTables, _file_by_node_id
     _bulk_copy(conn, "OVERRIDES", _REL_OVERRIDES_COLUMNS, overrides_rows)
 
     # Stage CALLS rows with dedup and callee_declaring_role materialization
-    seen_calls: set[tuple[str, str, int, int]] = set()
+    seen_calls: set[tuple[str, str, int, int, int]] = set()
     calls_rows: list[dict] = []
     member_by_id = {m.node_id: m for m in tables.members}
     for row in tables.calls_rows:
         if row.src_id not in valid_ids or row.dst_id not in valid_ids:
             continue
-        key = (row.src_id, row.dst_id, row.arg_count, row.call_site_line)
+        # Include call_site_byte so two call sites of the same method on the same
+        # source line (same arg_count) are kept as distinct edges (issue #359).
+        key = (row.src_id, row.dst_id, row.arg_count, row.call_site_line, row.call_site_byte)
         if key in seen_calls:
             continue
         seen_calls.add(key)
@@ -3606,10 +3644,15 @@ def _write_routes_and_exposes(conn: ladybug.Connection, tables: GraphTables, _fi
 
 
 def _write_meta(conn: ladybug.Connection, tables: GraphTables, source_root: Path) -> None:
-    seen_calls: set[tuple[str, str, int, int]] = set()
+    # Dedup key MUST match _write_edges (build_ast_graph.py, _REL_CALLS writer): the
+    # 5-tuple includes call_site_byte so two call sites of the same method on the
+    # same source line are counted separately. A previous version used the 4-tuple
+    # here, which made counts['calls'] (678) diverge from the real CALLS edge count
+    # (684) that _write_edges actually persisted — describe/stats then undercounted.
+    seen_calls: set[tuple[str, str, int, int, int]] = set()
     calls_unique = 0
     for row in tables.calls_rows:
-        key = (row.src_id, row.dst_id, row.arg_count, row.call_site_line)
+        key = (row.src_id, row.dst_id, row.arg_count, row.call_site_line, row.call_site_byte)
         if key not in seen_calls:
             seen_calls.add(key)
             calls_unique += 1
@@ -3773,6 +3816,7 @@ def incremental_rebuild(
                 if verbose:
                     _verbose_stderr_line(f"[increment] ontology version {version} < 17; falling back to full rebuild")
                 conn.close()
+                db.close()
                 del conn, db
                 return _fallback_to_full(source_root, ladybug_path, verbose, t_start)
     except Exception as e:
@@ -3780,6 +3824,7 @@ def incremental_rebuild(
             _verbose_stderr_line(f"[increment] failed to read ontology version: {e}; falling back to full rebuild")
         try:
             conn.close()
+            db.close()
         except Exception:
             pass
         del conn, db
@@ -3798,6 +3843,7 @@ def incremental_rebuild(
         if verbose:
             _verbose_stderr_line("[increment] no changes detected; no-op")
         conn.close()
+        db.close()
         return IncrementalResult(
             mode="incremental",
             files_changed=0,
@@ -3811,11 +3857,12 @@ def incremental_rebuild(
         _verbose_stderr_line(f"[increment] detected {len(added)} added, {len(changed)} changed, {len(removed)} removed files")
 
     # Step 2: Crash marker check
-    crash_marker_path = index_dir / ".graph_increment_in_progress"
+    crash_marker_path = index_dir / GRAPH_INCREMENT_MARKER_FILENAME
     if crash_marker_path.exists():
         if verbose:
             _verbose_stderr_line("[increment] crash marker exists; falling back to full rebuild")
         conn.close()
+        db.close()
         crash_marker_path.unlink(missing_ok=True)
         return _fallback_to_full(source_root, ladybug_path, verbose, t_start)
 
@@ -3850,6 +3897,7 @@ def incremental_rebuild(
             if verbose:
                 _verbose_stderr_line(f"[increment] dependent expansion cap ({expansion_cap}) exceeded ({len(scope_files)} files); falling back to full rebuild")
             conn.close()
+            db.close()
             crash_marker_path.unlink(missing_ok=True)
             return _fallback_to_full(source_root, ladybug_path, verbose, t_start)
 
@@ -3896,6 +3944,11 @@ def incremental_rebuild(
         # Rebuild full tables for global pass 5-6 (pass1 populates members from scratch)
         tables_for_global = GraphTables()
         global_asts = pass1_parse(source_root, tables_for_global, verbose=verbose)
+        # pass4 (routes/EXPOSES) must run on the global pass5/6 tables too (issue
+        # #352): pass5 links Feign HTTP_CALLS to routes via exposes_rows, and pass6
+        # matches against routes_rows. Without pass4 both stay empty and the
+        # HTTP_CALLS match outcome drifts from a full rebuild. Mirrors main().
+        pass4_routes(tables_for_global, global_asts, source_root=source_root, verbose=verbose)
 
         pass5_imperative_edges(tables_for_global, global_asts, source_root=source_root, verbose=verbose)
 
@@ -3929,6 +3982,7 @@ def incremental_rebuild(
         crash_marker_path.unlink(missing_ok=True)
 
         conn.close()
+        db.close()
 
         elapsed = time.time() - t_start
         if verbose:
@@ -3948,6 +4002,7 @@ def incremental_rebuild(
         if verbose:
             _verbose_stderr_line(f"[increment] error during incremental rebuild: {e}; falling back to full rebuild")
         conn.close()
+        db.close()
         crash_marker_path.unlink(missing_ok=True)
         return _fallback_to_full(source_root, ladybug_path, verbose, t_start)
 
@@ -4152,6 +4207,7 @@ def write_ladybug(
             _verbose_stderr_line(f"[graph] writing · routes/exposes written in {time.time() - t2:.2f}s")
         _write_meta(conn, tables, source_root)
         conn.close()
+        db.close()
     _init_hash_tracker(source_root, db_path)
 
 

graph_enrich.py

@@ -43,6 +43,7 @@ from ast_java import (
     _TYPE_ANN_TO_CAPABILITY,
 )
 from java_ontology import (
+    CLIENT_KIND_REST_TEMPLATE,
     VALID_CAPABILITIES,
     VALID_CLIENT_KINDS,
     VALID_PRODUCER_KINDS,
@@ -1301,7 +1302,7 @@ def resolve_http_client_for_method(
             hint = overrides.annotation_to_http_client_hint.get("CodebaseHttpClient")
             if hint is None:
                 hint = HttpClientHint(
-                    client_kind=anchor.client_kind if anchor else "rest_template",
+                    client_kind=anchor.client_kind if anchor else CLIENT_KIND_REST_TEMPLATE,
                     target_service=anchor.feign_target_name if anchor else "",
                     path=anchor.path_template_call if anchor else "",
                     method=anchor.method_call if anchor else "",

graph_types.py

@@ -0,0 +1,133 @@
+"""Shared graph types and helpers used by mcp_v2 and resolve_service.
+
+This is the neutral, acyclic shared module. It must NOT import from
+``mcp_v2`` or ``resolve_service`` — both of those import FROM here.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+from ladybug_queries import LadybugGraph
+from mcp_hints import generate_hints
+
+__all__ = [
+    "NodeRef",
+    "StructuredHint",
+    "set_hints_enabled",
+    "_hints_or_skip",
+    "_node_kind_from_id",
+    "_resolve_node_kind",
+    "_node_ref_from_row",
+    "_to_structured_hints",
+]
+
+
+class NodeRef(BaseModel):
+    id: str
+    kind: Literal["symbol", "route", "client", "producer", "unresolved_call_site"]
+    fqn: str
+    name: str | None = None
+    symbol_kind: str | None = None
+    microservice: str | None = None
+    module: str | None = None
+    role: str | None = None
+
+
+class StructuredHint(BaseModel):
+    label: str = ""
+    tool: Literal["search", "find", "describe", "neighbors", "resolve"]
+    args: dict[str, Any]
+    actionable: bool = True
+    reason: str = ""
+
+
+# Module-level flag set by server.py at startup from resolved config.
+# Single source of truth — both mcp_v2 and resolve_service read this via
+# _hints_or_skip, and server.py sets it via set_hints_enabled (re-exported
+# by mcp_v2 for back-comat).
+_hints_enabled: bool = True
+
+
+def set_hints_enabled(enabled: bool) -> None:
+    global _hints_enabled
+    _hints_enabled = enabled
+
+
+def _hints_or_skip(tool: str, payload: dict) -> tuple[list, list]:
+    return generate_hints(tool, payload) if _hints_enabled else ([], [])
+
+
+def _node_kind_from_id(
+    id_str: str,
+) -> Literal["symbol", "route", "client", "producer", "unresolved_call_site"]:
+    if id_str.startswith("ucs:"):
+        return "unresolved_call_site"
+    if id_str.startswith("sym:"):
+        return "symbol"
+    if id_str.startswith("route:") or id_str.startswith("r:"):
+        return "route"
+    if id_str.startswith("client:") or id_str.startswith("c:"):
+        return "client"
+    if id_str.startswith("producer:") or id_str.startswith("p:"):
+        return "producer"
+    raise ValueError(f"Unknown id prefix for `{id_str}`")
+
+
+def _resolve_node_kind(
+    graph: LadybugGraph,
+    node_id: str,
+) -> Literal["symbol", "route", "client", "producer", "unresolved_call_site"]:
+    try:
+        return _node_kind_from_id(node_id)
+    except ValueError:
+        pass
+    if graph._rows("MATCH (n:Symbol) WHERE n.id = $id RETURN n.id AS id LIMIT 1", {"id": node_id}):  # noqa: SLF001
+        return "symbol"
+    if graph._rows("MATCH (n:Route) WHERE n.id = $id RETURN n.id AS id LIMIT 1", {"id": node_id}):  # noqa: SLF001
+        return "route"
+    if graph._rows("MATCH (n:Client) WHERE n.id = $id RETURN n.id AS id LIMIT 1", {"id": node_id}):  # noqa: SLF001
+        return "client"
+    if graph._rows("MATCH (n:Producer) WHERE n.id = $id RETURN n.id AS id LIMIT 1", {"id": node_id}):  # noqa: SLF001
+        return "producer"
+    raise ValueError(f"Unknown id prefix for `{node_id}`")
+
+
+def _node_ref_from_row(kind: Literal["symbol", "route", "client", "producer"], row: dict[str, Any]) -> NodeRef:
+    symbol_kind: str | None = None
+    if kind == "symbol":
+        fqn = str(row.get("fqn") or "")
+        role = str(row.get("role") or "") or None
+        symbol_kind_val = str(row.get("symbol_kind") or row.get("kind") or "").strip()
+        symbol_kind = symbol_kind_val or None
+    elif kind == "route":
+        method = str(row.get("method") or "")
+        path = str(row.get("path_template") or row.get("path") or "")
+        fqn = f"{method} {path}".strip()
+        role = None
+    elif kind == "client":
+        method = str(row.get("method") or "")
+        target = str(row.get("target_service") or "")
+        path = str(row.get("path_template") or row.get("path") or "")
+        fqn = f"{target} {method} {path}".strip()
+        role = None
+    else:
+        topic = str(row.get("topic") or "")
+        broker = str(row.get("broker") or "")
+        fqn = f"{topic} {broker}".strip()
+        role = None
+    return NodeRef(
+        id=str(row.get("id") or ""),
+        kind=kind,
+        fqn=fqn,
+        symbol_kind=symbol_kind,
+        microservice=str(row.get("microservice") or "") or None,
+        module=str(row.get("module") or "") or None,
+        role=role,
+    )
+
+
+def _to_structured_hints(raw: list[Any]) -> list[StructuredHint]:
+    return [StructuredHint(label=h.label, tool=h.tool, args=h.args, actionable=h.actionable, reason=h.reason) for h in raw]

java_codebase_rag/_fdlimit.py

@@ -22,7 +22,15 @@ See https://github.com/HumanBean17/java-codebase-rag/issues/306
 
 from __future__ import annotations
 
-import resource
+try:
+    # Unix-only: the ``resource`` module does not exist on Windows. Importing it
+    # unconditionally at module scope crashes on Windows, which (because
+    # ``cli.py`` and ``server.py`` both import ``raise_fd_limit``) made the
+    # entire CLI and MCP server fail to start there. Guard the import so the
+    # module loads everywhere; the function below no-ops when it's absent.
+    import resource
+except ImportError:  # pragma: no cover - Windows lacks the resource module
+    resource = None  # type: ignore[assignment]
 
 # Safe ceiling well above LanceDB's appetite, comfortably below macOS libc
 # quirks. The hard limit caps it further if lower (locked-down servers).
@@ -35,7 +43,7 @@ def raise_fd_limit(cap: int = _DEFAULT_CAP) -> None:
     Best-effort and silent: never raises. No-op where ``RLIMIT_NOFILE`` is
     unsupported (Windows) or where the soft limit already meets ``min(hard, cap)``.
     """
-    if not hasattr(resource, "RLIMIT_NOFILE"):
+    if resource is None or not hasattr(resource, "RLIMIT_NOFILE"):
         return
     soft, hard = resource.getrlimit(resource.RLIMIT_NOFILE)
     target = min(hard, cap)

java_codebase_rag/_stdio.py

@@ -0,0 +1,32 @@
+"""Force stdout/stderr to UTF-8 so non-ASCII glyphs never crash the CLI.
+
+The text renderers emit Unicode glyphs — ``↑``/``↓`` (hierarchy tree headers
+in ``jrag_render``), ``✓`` (success markers in ``cli_format``), ``→``/``…``
+(listing/role lines). On Windows, ``sys.stdout``/``sys.stderr`` default to the
+system ANSI codepage (cp1252 on en-US Windows), which can't encode those
+characters, so ``print()`` raises ``UnicodeEncodeError`` and the process exits
+non-zero. Unix platforms already default to UTF-8, so this is a no-op there.
+
+Called from the console-script entry points (``_console_script_main``), not
+from in-process ``main()`` callers, so a test that drives ``main()`` directly
+keeps whatever stdout the host wired up.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def force_utf8_stdio() -> None:
+    """Reconfigure ``sys.stdout``/``sys.stderr`` to UTF-8.
+
+    Best-effort and silent: never raises. No-op where a stream lacks
+    ``reconfigure`` (streams replaced by capture frameworks that don't expose
+    it). ``errors="replace"`` is a last-resort safety net so a hostile console
+    can never crash a run; under UTF-8 every codepoint encodes cleanly, so
+    replacement never actually fires for the glyphs we emit.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(encoding="utf-8", errors="replace")