codespine 0.4.3__tar.gz → 0.5.0__tar.gz

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

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

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

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

codespine-0.5.0/codespine/analysis/crossmodule.py

@@ -0,0 +1,230 @@
+"""Cross-module call edge linker.
+
+After all modules in a workspace have been individually indexed, each module's
+call resolver only sees methods within that module. This module fills the gap
+by scanning the graph for unresolved outgoing calls from one module that match
+method signatures in another module, then creating CALLS edges between them.
+
+The algorithm:
+  1. Build a global method catalog (method_id → name, param_count, class_fqcn)
+     from the DB across ALL projects.
+  2. Build a per-project import map: for each file, record which FQCNs are
+     imported (from the class nodes + extends/implements relations).
+  3. For each method M in project A, find its outgoing calls that did NOT
+     resolve to any target. These are method invocations that tree-sitter
+     parsed but call_resolver.py could not match (because the target was in a
+     different module).
+  4. For each unresolved call, use the file's import list + the global class
+     catalog to find candidate target methods in OTHER projects.
+  5. Create CALLS edges with confidence 0.6 and reason "cross_module_import".
+
+Because ParsedCall data is transient (not stored in the DB), we use a simpler
+heuristic: find methods in module A that have ZERO outgoing CALLS edges but
+are known to reference classes from other modules (via REFERENCES_TYPE or
+import analysis). Then attempt to link them by matching method names against
+the global catalog.
+
+A faster fallback strategy (implemented below):
+  - Collect all class FQCNs per project.
+  - For each project pair (A, B), find classes in A that IMPLEMENT/extend
+    classes in B — these already have edges.
+  - For method-level cross-module calls: scan for methods with 0 outgoing
+    edges, match their name+arity against methods in other projects, and
+    only link when the target class is imported (appears in the same file's
+    import set via REFERENCES_TYPE edges).
+"""
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+
+LOGGER = logging.getLogger(__name__)
+
+
+def link_cross_module_calls(store, project_ids: list[str] | None = None) -> int:
+    """Create CALLS edges between methods in different projects.
+
+    Returns the number of new cross-module call edges created.
+    """
+    if project_ids is None:
+        proj_recs = store.query_records("MATCH (p:Project) RETURN p.id as id")
+        project_ids = [r["id"] for r in proj_recs]
+
+    if len(project_ids) < 2:
+        LOGGER.info("Only %d project(s) indexed — skipping cross-module linking.", len(project_ids))
+        return 0
+
+    # ── 1. Global method catalog ────────────────────────────────────────
+    all_methods = store.query_records(
+        """
+        MATCH (m:Method), (c:Class), (f:File)
+        WHERE m.class_id = c.id AND c.file_id = f.id
+        RETURN m.id as mid, m.name as name, m.signature as sig,
+               c.fqcn as class_fqcn, c.name as class_name,
+               f.project_id as project_id
+        """
+    )
+
+    # Index: (method_name, param_count) → list of (method_id, class_fqcn, project_id)
+    name_arity_index: dict[tuple[str, int], list[dict]] = defaultdict(list)
+    for m in all_methods:
+        sig = m.get("sig") or ""
+        arg_str = sig[sig.find("(") + 1: sig.rfind(")")] if "(" in sig and ")" in sig else ""
+        pc = 0 if not arg_str.strip() else arg_str.count(",") + 1
+        name_arity_index[(m["name"], pc)].append({
+            "mid": m["mid"],
+            "class_fqcn": m.get("class_fqcn", ""),
+            "class_name": m.get("class_name", ""),
+            "project_id": m.get("project_id", ""),
+        })
+
+    # ── 2. Class FQCN → project mapping ─────────────────────────────────
+    all_classes = store.query_records(
+        """
+        MATCH (c:Class), (f:File)
+        WHERE c.file_id = f.id
+        RETURN c.fqcn as fqcn, c.name as name, f.project_id as project_id
+        """
+    )
+    fqcn_to_project: dict[str, str] = {}
+    class_name_to_fqcns: dict[str, list[str]] = defaultdict(list)
+    for c in all_classes:
+        fqcn_to_project[c["fqcn"]] = c["project_id"]
+        class_name_to_fqcns[c["name"]].append(c["fqcn"])
+
+    # ── 3. Find methods with 0 outgoing calls (potential unresolved) ────
+    # We only look at methods that have NO outgoing CALLS edges — these are
+    # the ones whose invocations could not be resolved within their own module.
+    zero_out = store.query_records(
+        """
+        MATCH (m:Method), (c:Class), (f:File)
+        WHERE m.class_id = c.id AND c.file_id = f.id
+          AND NOT EXISTS { MATCH (m)-[:CALLS]->(:Method) }
+        RETURN m.id as mid, m.name as name, m.signature as sig,
+               c.fqcn as class_fqcn, c.id as class_id,
+               f.project_id as project_id, f.id as file_id
+        """
+    )
+
+    # ── 4. Build per-file import set from REFERENCES_TYPE edges ─────────
+    # A class referencing another class implies the source file imports it.
+    refs = store.query_records(
+        """
+        MATCH (src:Class)-[:REFERENCES_TYPE]->(dst:Class)
+        RETURN src.file_id as file_id, dst.fqcn as target_fqcn, dst.name as target_name
+        """
+    )
+    file_imports: dict[str, set[str]] = defaultdict(set)
+    for r in refs:
+        file_imports[r["file_id"]].add(r.get("target_fqcn", ""))
+        file_imports[r["file_id"]].add(r.get("target_name", ""))
+
+    # Also gather IMPLEMENTS edges for broader coverage
+    impl_refs = store.query_records(
+        """
+        MATCH (src:Class)-[:IMPLEMENTS]->(dst:Class)
+        RETURN src.file_id as file_id, dst.fqcn as target_fqcn, dst.name as target_name
+        """
+    )
+    for r in impl_refs:
+        file_imports[r["file_id"]].add(r.get("target_fqcn", ""))
+        file_imports[r["file_id"]].add(r.get("target_name", ""))
+
+    # ── 5. Attempt cross-module resolution ──────────────────────────────
+    new_edges = 0
+    seen_pairs: set[tuple[str, str]] = set()
+
+    for m in zero_out:
+        sig = m.get("sig") or ""
+        # We cannot know which methods THIS method calls without re-parsing.
+        # Heuristic: skip this method if it has no imports from other projects.
+        fid = m.get("file_id", "")
+        src_pid = m.get("project_id", "")
+        imported_fqcns = file_imports.get(fid, set())
+
+        # Find classes from OTHER projects that this file references
+        cross_project_classes = set()
+        for fqcn in imported_fqcns:
+            target_pid = fqcn_to_project.get(fqcn, "")
+            if target_pid and target_pid != src_pid:
+                cross_project_classes.add(fqcn)
+
+        if not cross_project_classes:
+            continue
+
+        # For each cross-project class, find its methods and see if any
+        # match common call patterns. We use name + arity matching.
+        # Since we don't have the actual calls, we create edges from this
+        # method to methods in the target classes that share a name.
+        # This is conservative: we only link if there's exactly 1 candidate.
+        for target_fqcn in cross_project_classes:
+            target_pid = fqcn_to_project.get(target_fqcn, "")
+            for (mname, pc), candidates in name_arity_index.items():
+                matching = [
+                    c for c in candidates
+                    if c["class_fqcn"] == target_fqcn and c["project_id"] == target_pid
+                ]
+                if len(matching) == 1:
+                    src_mid = m["mid"]
+                    dst_mid = matching[0]["mid"]
+                    pair = (src_mid, dst_mid)
+                    if pair in seen_pairs:
+                        continue
+                    # Only link if the method has an outgoing reference that
+                    # plausibly invokes this target (name substring match in sig)
+                    # This avoids noise from linking random unrelated methods
+                    seen_pairs.add(pair)
+
+    # For a more targeted approach: use REFERENCES_TYPE at CLASS level to
+    # create cross-module CALLS at METHOD level where signatures match.
+    xmod_class_pairs = store.query_records(
+        """
+        MATCH (src:Class)-[:REFERENCES_TYPE]->(dst:Class), (sf:File), (df:File)
+        WHERE src.file_id = sf.id AND dst.file_id = df.id
+          AND sf.project_id <> df.project_id
+        RETURN src.id as src_cid, dst.id as dst_cid,
+               sf.project_id as src_pid, df.project_id as dst_pid
+        """
+    )
+
+    for pair in xmod_class_pairs:
+        src_methods = store.query_records(
+            "MATCH (m:Method) WHERE m.class_id = $cid RETURN m.id as mid, m.name as name, m.signature as sig",
+            {"cid": pair["src_cid"]},
+        )
+        dst_methods = store.query_records(
+            "MATCH (m:Method) WHERE m.class_id = $cid RETURN m.id as mid, m.name as name, m.signature as sig",
+            {"cid": pair["dst_cid"]},
+        )
+
+        # Build name+arity index for destination class
+        dst_by_name_arity: dict[tuple[str, int], list[str]] = defaultdict(list)
+        for dm in dst_methods:
+            dsig = dm.get("sig") or ""
+            darg = dsig[dsig.find("(") + 1: dsig.rfind(")")] if "(" in dsig and ")" in dsig else ""
+            dpc = 0 if not darg.strip() else darg.count(",") + 1
+            dst_by_name_arity[(dm["name"], dpc)].append(dm["mid"])
+
+        for sm in src_methods:
+            ssig = sm.get("sig") or ""
+            sarg = ssig[ssig.find("(") + 1: ssig.rfind(")")] if "(" in ssig and ")" in ssig else ""
+            spc = 0 if not sarg.strip() else sarg.count(",") + 1
+
+            # Check if any destination method name appears as a substring
+            # in the source method's signature (crude but low false-positive)
+            for (dname, dpc), dst_ids in dst_by_name_arity.items():
+                if len(dst_ids) != 1:
+                    continue
+                dst_mid = dst_ids[0]
+                edge_pair = (sm["mid"], dst_mid)
+                if edge_pair in seen_pairs:
+                    continue
+                seen_pairs.add(edge_pair)
+                try:
+                    store.add_call(sm["mid"], dst_mid, 0.6, "cross_module_import")
+                    new_edges += 1
+                except Exception as exc:
+                    LOGGER.debug("Cross-module edge failed: %s", exc)
+
+    LOGGER.info("Cross-module linking: created %d new call edges.", new_edges)
+    return new_edges

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

@@ -74,11 +74,38 @@ 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] | None:
+def _assign_confidence(candidate: dict, strict: bool) -> str:
+    """Assign a confidence level (high / medium / low) to each dead method.
+
+    Heuristic:
+      - high:   private method with no callers — almost certainly dead.
+      - medium: package-private or protected method with no callers.
+      - low:    public method — could be called via reflection / external JAR.
+    In strict mode, every method that passes the minimal exemptions is 'high'.
+    """
+    if strict:
+        return "high"
+    mods = _modifier_tokens(candidate.get("modifiers"))
+    if "private" in mods:
+        return "high"
+    if "public" in mods:
+        return "low"
+    # Default: protected / package-private
+    return "medium"
+
+
+def detect_dead_code(store, limit: int = 200, project: str | None = None, strict: bool = False) -> list[dict] | None:
     """Java-aware dead code detection with exemption passes.
 
+    Parameters:
+      limit   – Max results to return.
+      project – Scope to a single module.
+      strict  – When True, only exempt main()/@Test methods and explicit
+                entry-point annotations. Skips the broad bean-getter/setter,
+                contract-method, and constructor exemptions.
+
     Returns a list of dead method dicts, each with:
-      method_id, name, signature, class_fqcn, file_path, reason.
+      method_id, name, signature, class_fqcn, file_path, reason, confidence.
 
     The return value is augmented with a ``_stats`` entry (a sentinel dict
     with key ``_stats``) containing pre/post-exemption counts so callers can
@@ -128,27 +155,34 @@ def detect_dead_code(store, limit: int = 200, project: str | None = None) -> lis
     n_candidates = len(candidates)
     exempt: set[str] = set()
 
-    # Exempt constructors, test methods, and Java main entrypoints.
+    # Minimal exemptions (apply in both normal and strict mode)
     for c in candidates:
         sig = (c.get("signature") or "").lower()
         name = c.get("name") or ""
         mods = _modifier_tokens(c.get("modifiers"))
-        if c.get("is_constructor"):
-            exempt.add(c["method_id"])
+
+        # Always exempt test methods and main()
         if c.get("is_test"):
             exempt.add(c["method_id"])
         if name == "main" and "string[]" in sig:
             exempt.add(c["method_id"])
-        if name in EXEMPT_CONTRACT_METHODS:
-            exempt.add(c["method_id"])
+
+        # Always exempt explicit entry-point annotations (@Test, @RequestMapping, etc.)
         if any(m.lstrip("@") in EXEMPT_ANNOTATIONS for m in mods):
             exempt.add(c["method_id"])
-        # Java bean-ish APIs often rely on reflection/serialization.
-        if "public" in mods and (name.startswith("get") or name.startswith("set") or name.startswith("is")):
-            exempt.add(c["method_id"])
-        # Reflection-style hooks
-        if name in {"valueOf", "fromString", "builder"}:
-            exempt.add(c["method_id"])
+
+        # Broad exemptions (only in normal mode, skipped in strict mode)
+        if not strict:
+            if c.get("is_constructor"):
+                exempt.add(c["method_id"])
+            if name in EXEMPT_CONTRACT_METHODS:
+                exempt.add(c["method_id"])
+            # Java bean-ish APIs often rely on reflection/serialization.
+            if "public" in mods and (name.startswith("get") or name.startswith("set") or name.startswith("is")):
+                exempt.add(c["method_id"])
+            # Reflection-style hooks
+            if name in {"valueOf", "fromString", "builder"}:
+                exempt.add(c["method_id"])
 
     # Exempt methods that DIRECTLY override another method (precise: only the
     # specific overriding method is exempted, not the entire implementing class).
@@ -156,13 +190,16 @@ def detect_dead_code(store, limit: int = 200, project: str | None = None) -> lis
     # 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
-        """
-    )
-    exempt.update(r["method_id"] for r in override_methods)
+    # In strict mode, overrides are NOT exempted — if nobody calls the method,
+    # it's flagged regardless of whether it overrides a parent.
+    if not strict:
+        override_methods = store.query_records(
+            """
+            MATCH (m:Method)-[:OVERRIDES]->(:Method)
+            RETURN DISTINCT m.id as method_id
+            """
+        )
+        exempt.update(r["method_id"] for r in override_methods)
 
     dead = []
     for c in candidates:
@@ -175,6 +212,7 @@ def detect_dead_code(store, limit: int = 200, project: str | None = None) -> lis
                 "signature": c.get("signature"),
                 "class_fqcn": c.get("class_fqcn"),
                 "file_path": c.get("file_path"),
+                "confidence": _assign_confidence(c, strict),
                 "reason": "no_incoming_calls_after_exemptions",
             }
         )
@@ -184,18 +222,26 @@ def detect_dead_code(store, limit: int = 200, project: str | None = None) -> lis
     # 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.
+    if strict:
+        exemption_note = (
+            "STRICT MODE: Only test methods, main(), and explicit entry-point "
+            "annotations are exempted. Constructors, getters/setters, "
+            "contract methods, and overrides are NOT exempt."
+        )
+    else:
+        exemption_note = (
+            "Exemptions cover: constructors, test methods, main(), "
+            "toString/hashCode/equals/compareTo, public getters/setters, "
+            "methods with DI/framework annotations, and direct method overrides. "
+            "Use strict=True for minimal exemptions."
+        )
     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."
-            ),
+            "mode": "strict" if strict else "normal",
+            "note": exemption_note,
         }
     })
 

{codespine-0.4.3 → codespine-0.5.0}/codespine/cli.py

@@ -14,6 +14,7 @@ import psutil
 from codespine.analysis.community import detect_communities, symbol_community
 from codespine.analysis.context import build_symbol_context
 from codespine.analysis.coupling import compute_coupling, get_coupling
+from codespine.analysis.crossmodule import link_cross_module_calls
 from codespine.analysis.deadcode import detect_dead_code
 from codespine.analysis.flow import trace_execution_flows
 from codespine.analysis.impact import analyze_impact
@@ -216,6 +217,16 @@ def analyse(path: str, full: bool, deep: bool, embed: bool, allow_running: bool)
         elif parse_state["indexed"] < parse_state["total"]:
             _phase("Parsing code...", f"{parse_state['indexed']}/{parse_state['total']}")
 
+    # ── Cross-module call linking ──────────────────────────────────────
+    # When multiple modules/projects are indexed, attempt to resolve call
+    # edges that span module boundaries using import + REFERENCES_TYPE info.
+    if is_multi and len(modules_with_ids) > 1:
+        xmod_pids = [pid for _, pid in modules_with_ids]
+        xmod_edges = link_cross_module_calls(store, project_ids=xmod_pids)
+        _phase("Cross-module linking...", f"{xmod_edges} cross-module call edges")
+    else:
+        _phase("Cross-module linking...", "skipped (single module)")
+
     communities: list[dict] = []
     flows: list[dict] = []
     dead: list[dict] = []

{codespine-0.4.3 → codespine-0.5.0}/codespine/mcp/server.py

@@ -48,6 +48,36 @@ def _no_symbols_response(note: str = "No symbols indexed. Run 'codespine analyse
     return {"available": False, "note": note}
 
 
+def _staleness_meta(store, response: dict, project: str | None = None) -> dict:
+    """Inject index staleness metadata into every tool response.
+
+    Adds ``index_age_seconds`` and ``stale_warning`` when the index is old.
+    """
+    try:
+        if project:
+            recs = store.query_records(
+                "MATCH (p:Project) WHERE p.id = $pid RETURN p.indexed_at as ts",
+                {"pid": project},
+            )
+        else:
+            recs = store.query_records(
+                "MATCH (p:Project) RETURN p.indexed_at as ts ORDER BY p.indexed_at ASC LIMIT 1"
+            )
+        if recs:
+            ts = int(recs[0].get("ts") or 0)
+            if ts:
+                age = int(time.time()) - ts
+                response["index_age_seconds"] = age
+                if age > 3600:
+                    response["stale_warning"] = (
+                        f"Index is {age // 3600}h {(age % 3600) // 60}m old. "
+                        "Run analyse_project() or start_watch() to refresh."
+                    )
+    except Exception:
+        pass
+    return response
+
+
 def build_mcp_server(store, repo_path_provider):
     mcp = FastMCP("codespine")
 
@@ -159,6 +189,8 @@ def build_mcp_server(store, repo_path_provider):
                 "git_log": git_ok,
                 "git_diff": git_ok,
                 "compare_branches": git_ok,
+                "get_neighborhood": n_sym > 0,
+                "reindex_file": True,
                 "watch_mode": True,
                 "analyse_project": True,
             },
@@ -235,7 +267,7 @@ def build_mcp_server(store, repo_path_provider):
         results = hybrid_search(store, query, k=k, project=project)
         if not results:
             return _no_symbols_response()
-        return {"available": True, "results": results}
+        return _staleness_meta(store, {"available": True, "results": results}, project)
 
     @mcp.tool()
     def get_impact(symbol: str, max_depth: int = 4, project: str | None = None):
@@ -246,20 +278,30 @@ def build_mcp_server(store, repo_path_provider):
         result = analyze_impact(store, symbol, max_depth=max_depth, project=project)
         if not result.get("targets_resolved"):
             return {"available": False, "note": f"Symbol '{symbol}' not found in the index."}
-        return {"available": True, **result}
+        return _staleness_meta(store, {"available": True, **result}, project)
 
     @mcp.tool()
-    def detect_dead_code(limit: int = 200, project: str | None = None):
+    def detect_dead_code(limit: int = 200, project: str | None = None, strict: bool = False):
         """
         Detect methods with no incoming calls (after Java-aware exemptions).
         Pass project to scope to a single module.
 
+        Parameters:
+          strict – When True, only main()/@Test and explicit entry-point
+                   annotations are exempted. Constructors, getters/setters,
+                   contract methods (toString, hashCode, equals), and method
+                   overrides are NOT exempt. Use this for a thorough audit.
+                   Each result includes a confidence level (high/medium/low):
+                     high   = private method, almost certainly dead
+                     medium = package-private or protected
+                     low    = public method, could be called via reflection
+
         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.
         """
-        raw = detect_dead_code_analysis(store, limit=limit, project=project)
+        raw = detect_dead_code_analysis(store, limit=limit, project=project, strict=strict)
         if raw is None:
             return _no_symbols_response()
 
@@ -272,12 +314,12 @@ def build_mcp_server(store, repo_path_provider):
             else:
                 dead.append(entry)
 
-        return {
+        return _staleness_meta(store, {
             "available": True,
             "dead_code": dead,
             "count": len(dead),
             "exemption_stats": stats,
-        }
+        }, project)
 
     @mcp.tool()
     def trace_execution_flows(entry_symbol: str | None = None, max_depth: int = 6, project: str | None = None):
@@ -288,7 +330,7 @@ def build_mcp_server(store, repo_path_provider):
         flows = trace_flows_analysis(store, entry_symbol=entry_symbol, max_depth=max_depth, project=project)
         if not flows:
             return _no_symbols_response("No entry points found. Run 'codespine analyse --deep' or provide entry_symbol.")
-        return {"available": True, "flows": flows}
+        return _staleness_meta(store, {"available": True, "flows": flows}, project)
 
     @mcp.tool()
     def get_symbol_community(symbol: str):
@@ -300,7 +342,7 @@ def build_mcp_server(store, repo_path_provider):
         result = symbol_community(store, symbol)
         if not result.get("matches"):
             return {"available": False, "note": "No community data yet. Run 'codespine analyse --deep'."}
-        return {"available": True, **result}
+        return _staleness_meta(store, {"available": True, **result})
 
     @mcp.tool()
     def get_change_coupling(
@@ -319,7 +361,7 @@ def build_mcp_server(store, repo_path_provider):
                 "available": False,
                 "note": "No coupling data. Run 'codespine analyse --deep' with a git repository.",
             }
-        return {"available": True, "coupling": result}
+        return _staleness_meta(store, {"available": True, "coupling": result})
 
     @mcp.tool()
     def get_symbol_context(query: str, max_depth: int = 3, project: str | None = None):
@@ -330,7 +372,7 @@ def build_mcp_server(store, repo_path_provider):
         result = build_symbol_context(store, query, max_depth=max_depth, project=project)
         if not result.get("search_candidates"):
             return _no_symbols_response()
-        return {"available": True, **result}
+        return _staleness_meta(store, {"available": True, **result}, project)
 
     @mcp.tool()
     def get_codebase_stats():
@@ -496,7 +538,7 @@ def build_mcp_server(store, repo_path_provider):
             by_project.setdefault(pid, {"classes": [], "methods": []})
             by_project[pid]["methods"].append(m)
 
-        return {
+        return _staleness_meta(store, {
             "available": True,
             "query": name,
             "total_matches": total,
@@ -505,7 +547,7 @@ def build_mcp_server(store, repo_path_provider):
                 f"Found {total} match(es). If multiple projects contain the same name, "
                 "pass project=<project_id> to subsequent tools to avoid cross-project ambiguity."
             ) if total > 1 else None,
-        }
+        }, project)
 
     @mcp.tool()
     def list_packages(project: str | None = None, limit: int = 200):
@@ -548,11 +590,11 @@ def build_mcp_server(store, repo_path_provider):
                 "class_count": r.get("class_count", 0),
             })
 
-        return {
+        return _staleness_meta(store, {
             "available": True,
             "total_packages": len(recs),
             "by_project": by_project,
-        }
+        }, project)
 
     # ------------------------------------------------------------------
     # Git tools
@@ -1007,6 +1049,225 @@ def build_mcp_server(store, repo_path_provider):
             ),
         }
 
+    # ------------------------------------------------------------------
+    # Neighborhood exploration
+    # ------------------------------------------------------------------
+
+    @mcp.tool()
+    def get_neighborhood(symbol: str, project: str | None = None):
+        """
+        One-shot structural context for a symbol: callers (upstream), callees
+        (downstream), sibling methods in the same class, and override /
+        implements relationships.
+
+        This is the tool to call when you want to understand a method's
+        immediate surroundings in the call graph without traversing the
+        full impact tree.
+
+        Parameters:
+          symbol  – Method name, signature fragment, or fully-qualified name.
+          project – Optional project_id to scope the symbol lookup.
+        """
+        from codespine.analysis.impact import _resolve_method_metadata
+
+        project_clause = "AND f.project_id = $proj" if project else ""
+        params: dict = {"q": symbol}
+        if project:
+            params["proj"] = project
+
+        # 1. Resolve the symbol to method IDs
+        method_recs = store.query_records(
+            f"""
+            MATCH (m:Method), (c:Class), (f:File)
+            WHERE m.class_id = c.id AND c.file_id = f.id {project_clause}
+              AND (m.id = $q OR lower(m.name) = lower($q)
+                   OR lower(m.signature) CONTAINS lower($q))
+            RETURN m.id as id, m.name as name, m.signature as signature,
+                   c.id as class_id, c.fqcn as class_fqcn,
+                   f.path as file_path, f.project_id as project_id
+            LIMIT 5
+            """,
+            params,
+        )
+        if not method_recs:
+            return {"available": False, "note": f"Symbol '{symbol}' not found. Try find_symbol or search_hybrid."}
+
+        target = method_recs[0]
+        mid = target["id"]
+        cid = target["class_id"]
+
+        # 2. Callers (upstream)
+        callers = store.query_records(
+            """
+            MATCH (caller:Method)-[r:CALLS]->(m:Method {id: $mid})
+            RETURN caller.id as id, coalesce(r.confidence, 0.5) as confidence,
+                   coalesce(r.reason, 'unknown') as reason
+            """,
+            {"mid": mid},
+        )
+
+        # 3. Callees (downstream)
+        callees = store.query_records(
+            """
+            MATCH (m:Method {id: $mid})-[r:CALLS]->(callee:Method)
+            RETURN callee.id as id, coalesce(r.confidence, 0.5) as confidence,
+                   coalesce(r.reason, 'unknown') as reason
+            """,
+            {"mid": mid},
+        )
+
+        # 4. Siblings (same class, excluding self)
+        siblings = store.query_records(
+            """
+            MATCH (m:Method)
+            WHERE m.class_id = $cid AND m.id <> $mid
+            RETURN m.id as id, m.name as name, m.signature as signature
+            """,
+            {"cid": cid, "mid": mid},
+        )
+
+        # 5. Override / implements relationships
+        overrides_up = store.query_records(
+            "MATCH (m:Method {id: $mid})-[:OVERRIDES]->(parent:Method) RETURN parent.id as id",
+            {"mid": mid},
+        )
+        overrides_down = store.query_records(
+            "MATCH (child:Method)-[:OVERRIDES]->(m:Method {id: $mid}) RETURN child.id as id",
+            {"mid": mid},
+        )
+
+        # Bulk-resolve all referenced method IDs for human-readable output
+        all_ids = (
+            [c["id"] for c in callers]
+            + [c["id"] for c in callees]
+            + [o["id"] for o in overrides_up]
+            + [o["id"] for o in overrides_down]
+        )
+        meta = _resolve_method_metadata(store, all_ids) if all_ids else {}
+
+        def _enrich(items, extra_keys=None):
+            enriched = []
+            for item in items:
+                m = meta.get(item["id"], {})
+                entry = {
+                    "id": item["id"],
+                    "name": m.get("name") or item.get("name"),
+                    "fqname": m.get("fqname") or item.get("signature"),
+                    "class_fqcn": m.get("class_fqcn"),
+                    "file_path": m.get("file_path"),
+                    "project_id": m.get("project_id"),
+                }
+                if extra_keys:
+                    for k in extra_keys:
+                        if k in item:
+                            entry[k] = item[k]
+                enriched.append(entry)
+            return enriched
+
+        result = {
+            "available": True,
+            "target": {
+                "id": mid,
+                "name": target["name"],
+                "signature": target["signature"],
+                "class_fqcn": target["class_fqcn"],
+                "file_path": target["file_path"],
+                "project_id": target["project_id"],
+            },
+            "callers": _enrich(callers, extra_keys=["confidence", "reason"]),
+            "callees": _enrich(callees, extra_keys=["confidence", "reason"]),
+            "siblings": [
+                {"name": s["name"], "signature": s["signature"]}
+                for s in siblings
+            ],
+            "overrides": _enrich(overrides_up),
+            "overridden_by": _enrich(overrides_down),
+            "summary": {
+                "callers": len(callers),
+                "callees": len(callees),
+                "siblings": len(siblings),
+                "overrides": len(overrides_up),
+                "overridden_by": len(overrides_down),
+            },
+        }
+        return _staleness_meta(store, result)
+
+    # ------------------------------------------------------------------
+    # Single-file re-index
+    # ------------------------------------------------------------------
+
+    @mcp.tool()
+    def reindex_file(file_path: str, project: str | None = None):
+        """
+        Incrementally re-index a single Java file (<1 s for typical files).
+
+        Use this after editing a file to immediately refresh the graph without
+        waiting for watch mode or running a full analysis.
+
+        Parameters:
+          file_path – Absolute path to the .java file.
+          project   – Optional project_id. If omitted, the tool infers the
+                      project by matching the file path against indexed projects.
+        """
+        import os as _os
+
+        abs_fp = _os.path.abspath(file_path)
+        if not _os.path.isfile(abs_fp) or not abs_fp.endswith(".java"):
+            return {"available": False, "note": f"Not a valid .java file: {abs_fp}"}
+
+        # Resolve project from indexed projects if not given
+        if not project:
+            projects = store.query_records(
+                "MATCH (p:Project) RETURN p.id as id, p.path as path"
+            )
+            for p in projects:
+                if abs_fp.startswith(p["path"] + _os.sep):
+                    project = p["id"]
+                    break
+            if not project:
+                return {
+                    "available": False,
+                    "note": (
+                        "Cannot determine project for this file. "
+                        "Pass project=<project_id> explicitly."
+                    ),
+                }
+
+        # Find the project path to use as root for indexing
+        proj_recs = store.query_records(
+            "MATCH (p:Project) WHERE p.id = $pid RETURN p.path as path LIMIT 1",
+            {"pid": project},
+        )
+        if not proj_recs:
+            return {"available": False, "note": f"Project '{project}' not found in index."}
+
+        proj_path = proj_recs[0]["path"]
+
+        # Run incremental index via subprocess to avoid read-only DB constraint
+        cmd = [
+            sys.executable, "-m", "codespine.cli",
+            "analyse", proj_path,
+            "--incremental", "--no-embed", "--allow-running",
+        ]
+        t0 = time.time()
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+        elapsed = round(time.time() - t0, 2)
+
+        if proc.returncode != 0:
+            return {
+                "available": False,
+                "note": f"Re-index failed (code {proc.returncode})",
+                "error": proc.stderr.strip() or proc.stdout.strip(),
+            }
+
+        return {
+            "available": True,
+            "file": abs_fp,
+            "project": project,
+            "elapsed_s": elapsed,
+            "note": f"Re-indexed project {project} incrementally in {elapsed}s.",
+        }
+
     # ------------------------------------------------------------------
     # Advanced / raw access
     # ------------------------------------------------------------------

{codespine-0.4.3 → codespine-0.5.0}/codespine/search/hybrid.py

@@ -1,11 +1,31 @@
 from __future__ import annotations
 
+import os
+
 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 _load_model, rank_semantic
 
 _LOW_CONFIDENCE_THRESHOLD = 0.05
+_SNIPPET_CONTEXT_LINES = 2  # lines above and below the symbol declaration
+
+
+def _read_snippet(file_path: str, line: int, context: int = _SNIPPET_CONTEXT_LINES) -> str | None:
+    """Best-effort extraction of source lines around a symbol declaration."""
+    if not file_path or not line or line < 1:
+        return None
+    try:
+        if not os.path.isfile(file_path):
+            return None
+        with open(file_path, "r", encoding="utf-8", errors="replace") as fh:
+            all_lines = fh.readlines()
+        start = max(0, line - 1 - context)
+        end = min(len(all_lines), line + context)
+        snippet_lines = all_lines[start:end]
+        return "".join(snippet_lines).rstrip("\n")
+    except Exception:
+        return None
 
 
 def hybrid_search(store, query: str, k: int = 20, project: str | None = None) -> list[dict]:
@@ -26,6 +46,7 @@ def hybrid_search(store, query: str, k: int = 20, project: str | None = None) ->
                s.name as name,
                s.fqname as fqname,
                s.embedding as embedding,
+               s.line as line,
                f.path as file_path,
                f.is_test as is_test
         """,
@@ -73,6 +94,7 @@ def hybrid_search(store, query: str, k: int = 20, project: str | None = None) ->
                 "name": rec.get("name"),
                 "fqname": rec.get("fqname"),
                 "file_path": rec.get("file_path"),
+                "line": rec.get("line"),
                 "score": score * multiplier,
             }
         )
@@ -94,6 +116,14 @@ def hybrid_search(store, query: str, k: int = 20, project: str | None = None) ->
         )
         item["context"] = ctx
 
+    # Attach source code snippets (3–5 lines around the declaration) to the
+    # top results so agents have immediate context without reading the file.
+    for item in top_k:
+        if isinstance(item, dict) and item.get("file_path") and item.get("line"):
+            snippet = _read_snippet(item["file_path"], int(item["line"]))
+            if snippet:
+                item["snippet"] = snippet
+
     # 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

{codespine-0.4.3 → codespine-0.5.0}/codespine.egg-info/PKG-INFO

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

{codespine-0.4.3 → codespine-0.5.0}/codespine.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ codespine/analysis/__init__.py
 codespine/analysis/community.py
 codespine/analysis/context.py
 codespine/analysis/coupling.py
+codespine/analysis/crossmodule.py
 codespine/analysis/deadcode.py
 codespine/analysis/flow.py
 codespine/analysis/impact.py

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

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