codespine 0.4.1__tar.gz → 0.4.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.4.1
+Version: 0.4.3
 Summary: Local Java code intelligence indexer backed by a graph database
 Author: CodeSpine contributors
 License: MIT License
@@ -46,7 +46,7 @@ Requires-Dist: click
 Requires-Dist: kuzu
 Requires-Dist: tree-sitter
 Requires-Dist: tree-sitter-java
-Requires-Dist: fastmcp
+Requires-Dist: fastmcp>=2.3.0
 Requires-Dist: psutil
 Requires-Dist: watchfiles
 Provides-Extra: ml

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

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

{codespine-0.4.1 → codespine-0.4.3}/codespine/analysis/deadcode.py

@@ -74,8 +74,17 @@ def _modifier_tokens(modifiers) -> set[str]:
     return {str(m).strip() for m in modifiers}
 
 
-def detect_dead_code(store, limit: int = 200, project: str | None = None) -> list[dict]:
-    """Java-aware dead code detection with exemption passes."""
+def detect_dead_code(store, limit: int = 200, project: str | None = None) -> list[dict] | None:
+    """Java-aware dead code detection with exemption passes.
+
+    Returns a list of dead method dicts, each with:
+      method_id, name, signature, class_fqcn, file_path, reason.
+
+    The return value is augmented with a ``_stats`` entry (a sentinel dict
+    with key ``_stats``) containing pre/post-exemption counts so callers can
+    show users that the exemption logic is actually working:
+      candidates_with_no_callers, exempted, dead_returned
+    """
     if project:
         candidates = store.query_records(
             """
@@ -88,16 +97,17 @@ def detect_dead_code(store, limit: int = 200, project: str | None = None) -> lis
                    m.modifiers as modifiers,
                    c.fqcn as class_fqcn,
                    m.is_constructor as is_constructor,
-                   m.is_test as is_test
+                   m.is_test as is_test,
+                   f.path as file_path
             LIMIT $limit
             """,
-            {"limit": int(limit * 3), "proj": project},
+            {"limit": int(limit * 5), "proj": project},
         )
     else:
         candidates = store.query_records(
             """
-            MATCH (m:Method), (c:Class)
-            WHERE m.class_id = c.id
+            MATCH (m:Method), (c:Class), (f:File)
+            WHERE m.class_id = c.id AND c.file_id = f.id
               AND NOT EXISTS { MATCH (:Method)-[:CALLS]->(m) }
             RETURN m.id as method_id,
                    m.name as name,
@@ -105,15 +115,17 @@ def detect_dead_code(store, limit: int = 200, project: str | None = None) -> lis
                    m.modifiers as modifiers,
                    c.fqcn as class_fqcn,
                    m.is_constructor as is_constructor,
-                   m.is_test as is_test
+                   m.is_test as is_test,
+                   f.path as file_path
             LIMIT $limit
             """,
-            {"limit": int(limit * 3)},
+            {"limit": int(limit * 5)},
         )
 
     if not candidates:
         return []
 
+    n_candidates = len(candidates)
     exempt: set[str] = set()
 
     # Exempt constructors, test methods, and Java main entrypoints.
@@ -138,22 +150,19 @@ def detect_dead_code(store, limit: int = 200, project: str | None = None) -> lis
         if name in {"valueOf", "fromString", "builder"}:
             exempt.add(c["method_id"])
 
-    # Exempt override/interface contract methods if relation exists.
+    # Exempt methods that DIRECTLY override another method (precise: only the
+    # specific overriding method is exempted, not the entire implementing class).
+    # NOTE: we intentionally do NOT use the class-level IMPLEMENTS relation here
+    # because that would exempt ALL methods of every class that implements ANY
+    # interface — in a typical Spring project that wipes out almost everything
+    # and produces 0 dead code results.
     override_methods = store.query_records(
         """
         MATCH (m:Method)-[:OVERRIDES]->(:Method)
         RETURN DISTINCT m.id as method_id
         """
     )
-    interface_methods = store.query_records(
-        """
-        MATCH (c:Class)-[:IMPLEMENTS]->(:Class), (m:Method)
-        WHERE m.class_id = c.id
-        RETURN DISTINCT m.id as method_id
-        """
-    )
     exempt.update(r["method_id"] for r in override_methods)
-    exempt.update(r["method_id"] for r in interface_methods)
 
     dead = []
     for c in candidates:
@@ -164,8 +173,30 @@ def detect_dead_code(store, limit: int = 200, project: str | None = None) -> lis
                 "method_id": c["method_id"],
                 "name": c.get("name"),
                 "signature": c.get("signature"),
+                "class_fqcn": c.get("class_fqcn"),
+                "file_path": c.get("file_path"),
                 "reason": "no_incoming_calls_after_exemptions",
             }
         )
 
-    return dead[:limit]
+    result = dead[:limit]
+
+    # Append stats as a sentinel entry so the MCP layer can surface them
+    # without changing the return type.  Callers should strip entries that
+    # have a "_stats" key when iterating over method results.
+    result.append({
+        "_stats": {
+            "candidates_with_no_callers": n_candidates,
+            "exempted": len(exempt),
+            "dead_returned": len(result),
+            "note": (
+                "Exemptions cover: constructors, test methods, main(), "
+                "toString/hashCode/equals/compareTo, public getters/setters, "
+                "methods with DI/framework annotations, and direct method overrides. "
+                "The class-level IMPLEMENTS exemption has been removed — only "
+                "methods with direct OVERRIDES relations are now exempted."
+            ),
+        }
+    })
+
+    return result

{codespine-0.4.1 → codespine-0.4.3}/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.3}/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.3}/codespine/mcp/server.py

@@ -253,11 +253,31 @@ def build_mcp_server(store, repo_path_provider):
         """
         Detect methods with no incoming calls (after Java-aware exemptions).
         Pass project to scope to a single module.
+
+        Returns dead_code list, count, and an exemption_stats dict showing
+        how many candidates were found and how many were filtered out by the
+        exemption rules — useful for validating that the feature is working
+        even when the dead list is empty.
         """
-        dead = detect_dead_code_analysis(store, limit=limit, project=project)
-        if dead is None:
+        raw = detect_dead_code_analysis(store, limit=limit, project=project)
+        if raw is None:
             return _no_symbols_response()
-        return {"available": True, "dead_code": dead, "count": len(dead)}
+
+        # Separate the sentinel stats entry appended by the analysis function.
+        stats: dict = {}
+        dead = []
+        for entry in raw:
+            if "_stats" in entry:
+                stats = entry["_stats"]
+            else:
+                dead.append(entry)
+
+        return {
+            "available": True,
+            "dead_code": dead,
+            "count": len(dead),
+            "exemption_stats": stats,
+        }
 
     @mcp.tool()
     def trace_execution_flows(entry_symbol: str | None = None, max_depth: int = 6, project: str | None = None):
@@ -273,7 +293,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 +530,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,
@@ -586,11 +609,24 @@ def build_mcp_server(store, repo_path_provider):
         }
 
     @mcp.tool()
-    def compare_branches(base_ref: str, head_ref: str):
-        """Symbol-level diff between two git refs (branches, tags, commits)."""
-        repo = repo_path_provider()
+    def compare_branches(base_ref: str, head_ref: str, project: str | None = None):
+        """
+        Symbol-level diff between two git refs (branches, tags, commits).
+        Pass project=<project_id> so the tool can resolve the correct git
+        repository root from the indexed project path rather than relying on
+        the MCP server's working directory (which may point to the graph DB
+        location, not the source tree).
+        """
+        repo = _resolve_repo_path(store, project, repo_path_provider)
         if not _git_available(repo):
-            return {"available": False, "note": "Not a git repository (or git not installed)."}
+            return {
+                "available": False,
+                "note": (
+                    "Not a git repository (or git not installed). "
+                    "Pass project=<project_id> so the tool can resolve the repo "
+                    "from the indexed project path. Use list_projects() to see available IDs."
+                ),
+            }
         result = compare_branches_analysis(repo, base_ref, head_ref)
         return {"available": True, **result}
 
@@ -978,6 +1014,7 @@ def build_mcp_server(store, repo_path_provider):
     @mcp.tool()
     def run_cypher(query: str):
         """Run a raw Cypher query against the graph. For advanced exploration."""
-        return store.query_records(query)
+        records = store.query_records(query)
+        return {"available": True, "records": records, "count": len(records)}
 
     return mcp

{codespine-0.4.1 → codespine-0.4.3}/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.3}/codespine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespine
-Version: 0.4.1
+Version: 0.4.3
 Summary: Local Java code intelligence indexer backed by a graph database
 Author: CodeSpine contributors
 License: MIT License
@@ -46,7 +46,7 @@ Requires-Dist: click
 Requires-Dist: kuzu
 Requires-Dist: tree-sitter
 Requires-Dist: tree-sitter-java
-Requires-Dist: fastmcp
+Requires-Dist: fastmcp>=2.3.0
 Requires-Dist: psutil
 Requires-Dist: watchfiles
 Provides-Extra: ml

{codespine-0.4.1 → codespine-0.4.3}/codespine.egg-info/requires.txt

@@ -2,7 +2,7 @@ click
 kuzu
 tree-sitter
 tree-sitter-java
-fastmcp
+fastmcp>=2.3.0
 psutil
 watchfiles
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codespine"
-version = "0.4.1"
+version = "0.4.3"
 description = "Local Java code intelligence indexer backed by a graph database"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -30,7 +30,7 @@ dependencies = [
   "kuzu",
   "tree-sitter",
   "tree-sitter-java",
-  "fastmcp",
+  "fastmcp>=2.3.0",
   "psutil",
   "watchfiles"
 ]