codespine 0.4.1__tar.gz → 0.4.2__tar.gz

{codespine-0.4.1 → codespine-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.4.1
+Version: 0.4.2
 Summary: Local Java code intelligence indexer backed by a graph database
 Author: CodeSpine contributors
 License: MIT License

{codespine-0.4.1 → codespine-0.4.2}/codespine/__init__.py

@@ -1,4 +1,4 @@
 """CodeSpine package."""
 
 __all__ = ["__version__"]
-__version__ = "0.4.1"
+__version__ = "0.4.2"

{codespine-0.4.1 → codespine-0.4.2}/codespine/analysis/flow.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 from collections import defaultdict, deque
 
+from codespine.analysis.impact import _resolve_method_metadata
+
 
 def _entry_methods(store, project: str | None = None) -> list[str]:
     if project:
@@ -108,4 +110,24 @@ def trace_execution_flows(store, entry_symbol: str | None = None, max_depth: int
             }
         )
 
+    # ------------------------------------------------------------------ #
+    # Enrich every node with human-readable metadata so AI agents don't
+    # need a second round-trip to resolve raw method ID hashes.
+    # Collect all unique IDs across all flows, resolve in one bulk query.
+    # ------------------------------------------------------------------ #
+    all_ids = list({node["symbol"] for flow in flows for node in flow["nodes"]})
+    meta = _resolve_method_metadata(store, all_ids)
+
+    for flow in flows:
+        entry_m = meta.get(flow["entry"], {})
+        flow["entry_name"] = entry_m.get("name")
+        flow["entry_fqname"] = entry_m.get("fqname")
+        flow["entry_file_path"] = entry_m.get("file_path")
+        for node in flow["nodes"]:
+            m = meta.get(node["symbol"], {})
+            node["name"] = m.get("name")
+            node["fqname"] = m.get("fqname")
+            node["file_path"] = m.get("file_path")
+            node["project_id"] = m.get("project_id")
+
     return flows

{codespine-0.4.1 → codespine-0.4.2}/codespine/analysis/impact.py

@@ -21,6 +21,27 @@ def _resolve_symbol_ids(store, symbol_query: str, project: str | None = None) ->
     return [r["id"] for r in recs]
 
 
+def _resolve_method_metadata(store, method_ids: list[str]) -> dict[str, dict]:
+    """Bulk-resolve method IDs to human-readable metadata in a single query.
+
+    Returns a dict keyed by method ID with fields:
+      name, fqname (= m.signature), class_fqcn, file_path, project_id.
+    Any ID not found in the graph is silently omitted.
+    """
+    if not method_ids:
+        return {}
+    recs = store.query_records(
+        """
+        MATCH (m:Method), (c:Class), (f:File)
+        WHERE m.id IN $ids AND m.class_id = c.id AND c.file_id = f.id
+        RETURN m.id as id, m.name as name, m.signature as fqname,
+               c.fqcn as class_fqcn, f.path as file_path, f.project_id as project_id
+        """,
+        {"ids": method_ids},
+    )
+    return {r["id"]: r for r in recs}
+
+
 def analyze_impact(store, symbol_query: str, max_depth: int = 4, project: str | None = None) -> dict:
     target_symbol_ids = _resolve_symbol_ids(store, symbol_query, project=project)
     if not target_symbol_ids:
@@ -85,9 +106,45 @@ def analyze_impact(store, symbol_query: str, max_depth: int = 4, project: str |
                 depth_groups["3+"].append(item)
             queue.append((src, next_depth, path + [src]))
 
+    # ------------------------------------------------------------------ #
+    # Enrich every caller entry with human-readable metadata so AI agents
+    # don't need a second round-trip to resolve raw ID hashes.
+    # A single bulk query resolves all collected method IDs at once.
+    # ------------------------------------------------------------------ #
+    all_caller_ids = [item["symbol"] for items in depth_groups.values() for item in items]
+    meta = _resolve_method_metadata(store, all_caller_ids)
+
+    for items in depth_groups.values():
+        for item in items:
+            m = meta.get(item["symbol"], {})
+            item["name"] = m.get("name")
+            item["fqname"] = m.get("fqname")
+            item["file_path"] = m.get("file_path")
+            item["project_id"] = m.get("project_id")
+            item["class_fqcn"] = m.get("class_fqcn")
+            # Convert the call-path from a list of raw IDs to human-readable names
+            # so an agent can read the chain without additional lookups.
+            item["path"] = [
+                meta.get(pid, {}).get("name") or pid
+                for pid in item["path"]
+            ]
+
+    # Also enrich the targets_resolved list for context
+    target_meta = _resolve_method_metadata(store, target_method_ids)
+    resolved_targets = [
+        {
+            "id": mid,
+            "name": target_meta.get(mid, {}).get("name"),
+            "fqname": target_meta.get(mid, {}).get("fqname"),
+            "file_path": target_meta.get(mid, {}).get("file_path"),
+            "class_fqcn": target_meta.get(mid, {}).get("class_fqcn"),
+        }
+        for mid in target_method_ids
+    ]
+
     return {
         "target": symbol_query,
-        "targets_resolved": target_method_ids,
+        "targets_resolved": resolved_targets,
         "depth_groups": depth_groups,
         "summary": {
             "direct": len(depth_groups["1"]),

{codespine-0.4.1 → codespine-0.4.2}/codespine/mcp/server.py

@@ -273,7 +273,10 @@ def build_mcp_server(store, repo_path_provider):
     @mcp.tool()
     def get_symbol_community(symbol: str):
         """Return the architectural community cluster a symbol belongs to."""
-        detect_communities(store)
+        # NOTE: do NOT call detect_communities() here — the MCP server opens the
+        # graph DB read-only, so any write attempt raises "Cannot execute write
+        # operations in a read-only database!".  Communities are computed once
+        # during 'codespine analyse --deep' and persisted; we just read them.
         result = symbol_community(store, symbol)
         if not result.get("matches"):
             return {"available": False, "note": "No community data yet. Run 'codespine analyse --deep'."}
@@ -507,7 +510,7 @@ def build_mcp_server(store, repo_path_provider):
             MATCH (c:Class), (f:File)
             WHERE c.file_id = f.id {project_clause}
             RETURN c.package as package, f.project_id as project_id, count(c) as class_count
-            ORDER BY f.project_id, c.package
+            ORDER BY project_id, package
             LIMIT $lim
             """,
             params,

{codespine-0.4.1 → codespine-0.4.2}/codespine/search/hybrid.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from codespine.search.bm25 import rank_bm25
 from codespine.search.fuzzy import rank_fuzzy
 from codespine.search.rrf import reciprocal_rank_fusion
-from codespine.search.vector import rank_semantic
+from codespine.search.vector import _load_model, rank_semantic
 
 _LOW_CONFIDENCE_THRESHOLD = 0.05
 
@@ -95,14 +95,27 @@ def hybrid_search(store, query: str, k: int = 20, project: str | None = None) ->
         item["context"] = ctx
 
     # Warn when all scores are near zero — the results are likely noise.
+    # The threshold 0.05 is calibrated for embedding mode.  Without sentence-
+    # transformers the hash-fallback vector and BM25/fuzzy signals produce lower
+    # RRF scores, so the warning fires on nearly every query.  Make the note
+    # context-aware so the agent understands whether this is a calibration issue
+    # or a genuine low-relevance result.
     if top_k and top_k[0]["score"] < _LOW_CONFIDENCE_THRESHOLD:
+        has_model = _load_model() is not None
         for item in top_k:
             item["low_confidence"] = True
-        top_k.append({
-            "note": (
+        if has_model:
+            note = (
                 "Low confidence results — all scores below threshold. "
                 "If searching for an exact class or method name, use find_symbol instead."
             )
-        })
+        else:
+            note = (
+                "Low confidence results — scores are lower in BM25/fuzzy-only mode "
+                "(no embedding model detected). "
+                "This is expected without 'codespine[ml]' installed; results may still be correct. "
+                "For exact name matches, use find_symbol instead."
+            )
+        top_k.append({"note": note})
 
     return top_k

{codespine-0.4.1 → codespine-0.4.2}/codespine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.4.1
+Version: 0.4.2
 Summary: Local Java code intelligence indexer backed by a graph database
 Author: CodeSpine contributors
 License: MIT License

{codespine-0.4.1 → codespine-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codespine"
-version = "0.4.1"
+version = "0.4.2"
 description = "Local Java code intelligence indexer backed by a graph database"
 readme = "README.md"
 requires-python = ">=3.10"