codecompass-mcp 2.7.0__tar.gz → 2.8.0__tar.gz

{codecompass_mcp-2.7.0 → codecompass_mcp-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecompass-mcp
-Version: 2.7.0
+Version: 2.8.0
 Summary: Structural code context for AI coding agents — a local code knowledge graph for blast radius, impact, deps, dead code, and flow tracing
 Author: CodeCompass contributors
 License: MIT

{codecompass_mcp-2.7.0 → codecompass_mcp-2.8.0}/codecompass_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecompass-mcp
-Version: 2.7.0
+Version: 2.8.0
 Summary: Structural code context for AI coding agents — a local code knowledge graph for blast radius, impact, deps, dead code, and flow tracing
 Author: CodeCompass contributors
 License: MIT

{codecompass_mcp-2.7.0 → codecompass_mcp-2.8.0}/graph/code_graph_client.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import networkx as nx
 from datetime import datetime, timezone
 from typing import Optional, Any
@@ -36,6 +37,15 @@ def _now() -> str:
     return datetime.now(timezone.utc).isoformat()
 
 
+def _entity_id(project: str, name: str, file: str | None) -> str:
+    """Node id for an entity — file-qualified so same-named entities in different
+    files stay distinct. Case is preserved so `Session` (class) and `session`
+    (function) don't collide. External/module targets with no file are name-only."""
+    if file:
+        return f"{project}:{file}:{name}"
+    return f"{project}:{name}"
+
+
 _ENTRY_POINT_PREFIXES = ("run_", "main", "handle_", "cmd_", "test_", "setup_", "teardown_")
 _ENTRY_POINT_NAMES = {"main", "__main__", "handler", "lambda_handler", "application", "app"}
 
@@ -186,9 +196,14 @@ class LocalGraphClient:
     # Entity nodes and semantic edges (from code triples)
     # ------------------------------------------------------------------
 
-    def write_code_triple(self, triple: CodeTriple, file_node_id: str, project: str) -> None:
-        from_id = f"{project}:{triple.from_entity.lower()}"
-        to_id = f"{project}:{triple.to_entity.lower()}"
+    def write_code_triple(self, triple: CodeTriple, file_node_id: str, project: str,
+                          from_id: str | None = None, to_id: str | None = None) -> None:
+        # from_id/to_id are the resolved (file-qualified) node ids from the batch
+        # writer; fall back to name-only for any direct/legacy caller.
+        if from_id is None:
+            from_id = f"{project}:{triple.from_entity}"
+        if to_id is None:
+            to_id = f"{project}:{triple.to_entity}"
         rel_type = triple.relation_type if triple.relation_type in _ALLOWED_REL_TYPES else "RELATION"
 
         ext = os.path.splitext(triple.source_file)[1].lower()
@@ -236,16 +251,52 @@ class LocalGraphClient:
 
         self.graph.add_edge(file_node_id, from_id, type="CONTAINS")
 
+    def _resolve_to_id(self, triple: CodeTriple, project: str,
+                       defs_by_name: dict, class_file: dict) -> str:
+        """Resolve a triple's callee/target to a specific definition node when we
+        can, else a name-only bucket. Uses the captured receiver type to pick the
+        right same-named method (self.send() in a Session method -> the send
+        defined alongside class Session)."""
+        name = triple.to_entity
+        if triple.relation_type == "DEFINED_IN":
+            return f"{project}:{name}"  # module container — name-only
+        cands = defs_by_name.get(name)
+        if cands:
+            rt = getattr(triple, "call_receiver_type", None)
+            if rt:
+                cf = class_file.get(rt)
+                if cf:
+                    for nid, f in cands:
+                        if f == cf:
+                            return nid
+            if len(cands) == 1:
+                return cands[0][0]
+        # ambiguous or external → name-only bucket (edge not lost)
+        return f"{project}:{name}"
+
     def write_code_triples_batch(
-        self, 
-        triples: list[CodeTriple], 
-        file_id_map: dict[str, str], 
+        self,
+        triples: list[CodeTriple],
+        file_id_map: dict[str, str],
         project: str
     ) -> int:
+        # Pass 1: index every definition so calls can resolve to a specific one.
+        defs_by_name: dict[str, list] = {}
+        class_file: dict[str, str] = {}
+        for t in triples:
+            if t.relation_type == "DEFINED_IN":
+                nid = _entity_id(project, t.from_entity, t.source_file)
+                defs_by_name.setdefault(t.from_entity, []).append((nid, t.source_file))
+                if t.from_type == "class":
+                    class_file.setdefault(t.from_entity, t.source_file)
+
+        # Pass 2: write nodes/edges with resolved, file-qualified ids.
         for triple in triples:
             file_id = file_id_map.get(triple.source_file, "")
-            self.write_code_triple(triple, file_id, project)
-        
+            from_id = _entity_id(project, triple.from_entity, triple.source_file)
+            to_id = self._resolve_to_id(triple, project, defs_by_name, class_file)
+            self.write_code_triple(triple, file_id, project, from_id=from_id, to_id=to_id)
+
         self.save()
         return len(triples)
 
@@ -290,30 +341,59 @@ class LocalGraphClient:
     # Traversal queries used by code_query_cli
     # ------------------------------------------------------------------
 
+    def _resolve_query_nodes(self, entity_name: str, project: str) -> list[str]:
+        """Resolve a bare or receiver-qualified name to the node id(s) it refers
+        to. `Session.send` → the `send` node in the file where class `Session` is
+        defined; `send` → every `send` node. Includes the name-only bucket id
+        when present (unresolved/ambiguous calls land there)."""
+        qualifier = None
+        name = entity_name
+        if "." in entity_name:
+            qualifier, name = entity_name.rsplit(".", 1)
+        name_l = name.lower()
+
+        matches = [
+            n for n, a in self.graph.nodes(data=True)
+            if a.get("type") == "Entity" and (a.get("name") or "").lower() == name_l
+        ]
+        # name-only bucket (unresolved calls land here) is matched by its name attr,
+        # but sort it last so flow/trace pick a real definition as the start.
+        matches.sort(key=lambda n: self.graph.nodes[n].get("file") is None)
+
+        if qualifier and matches:
+            cls_files = {
+                a.get("file") for n, a in self.graph.nodes(data=True)
+                if a.get("type") == "Entity" and a.get("entity_type") == "class"
+                and (a.get("name") or "").lower() == qualifier.lower() and a.get("file")
+            }
+            pref = [n for n in matches if self.graph.nodes[n].get("file") in cls_files]
+            if pref:
+                return pref
+        return matches
+
     def find_callers(self, entity_name: str, project: str, max_hops: int = 3) -> list[dict]:
         """Return everything that calls/uses/references entity_name (reverse traversal).
 
         `entity_name` may be a bare name ("handle") or receiver-qualified
-        ("app.handle" / "Router.handle"). When qualified, only call sites whose
-        receiver matches are returned — by inferred receiver *type* first
-        (`Router.handle` -> calls on a `new Router()`), then by receiver name.
-        This separates distinct same-named methods (app.handle vs router.handle)
-        that share a single graph node. Every returned row carries the call's
-        `receiver` and `receiver_type`, so an unqualified query still surfaces
-        the collision instead of hiding it.
+        ("app.handle" / "Router.handle"). Node ids are file-qualified, so distinct
+        same-named methods are distinct nodes; a qualified query resolves to the
+        one defined alongside the named class. The receiver filter still applies
+        for calls that landed in a shared name-only bucket (genuinely ambiguous).
+        Every returned row carries the call's `receiver`/`receiver_type` and the
+        real call-site file+line.
         """
         want_receiver = None
-        lookup_name = entity_name
         if "." in entity_name:
-            want_receiver, lookup_name = entity_name.rsplit(".", 1)
+            want_receiver, _ = entity_name.rsplit(".", 1)
 
-        target_id = f"{project}:{lookup_name.lower()}"
-        if target_id not in self.graph:
+        targets = self._resolve_query_nodes(entity_name, project)
+        if not targets:
             return []
+        target_set = set(targets)
 
         results = []
-        visited = {target_id}
-        queue = [(target_id, 0)]
+        visited = set(targets)
+        queue = [(t, 0) for t in targets]
 
         while queue:
             current_id, depth = queue.pop(0)
@@ -331,7 +411,7 @@ class LocalGraphClient:
 
                 # Only apply receiver filtering to the direct (depth-0) edge into
                 # the queried symbol; deeper hops are transitive callers.
-                if want_receiver is not None and current_id == target_id:
+                if want_receiver is not None and current_id in target_set:
                     if not any(
                         _receiver_matches(want_receiver, edge.get("receiver"),
                                           edge.get("receiver_type"))
@@ -349,18 +429,96 @@ class LocalGraphClient:
                         (e.get("receiver_type") for e in relevant_edges if e.get("receiver_type")),
                         None,
                     )
+                    # The caller NODE is keyed by name only, so when two functions
+                    # share a name its "file" is last-writer-wins (a merge). The
+                    # CALLS edge, however, records where THIS call actually is —
+                    # use it so each caller row points at the real call site with a
+                    # line number, not the merged node's file.
+                    call_edge = next(
+                        (e for e in relevant_edges if e.get("source_file")), relevant_edges[0]
+                    )
                     results.append({
                         "caller_name": node.get("name"),
                         "caller_type": node.get("entity_type"),
-                        "caller_file": node.get("file"),
+                        "caller_file": call_edge.get("source_file") or node.get("file"),
+                        "line": call_edge.get("line"),
                         "receiver": receiver,
                         "receiver_type": receiver_type,
+                        "resolved": True,
                         "depth": depth + 1
                     })
                     visited.add(pred)
                     queue.append((pred, depth + 1))
 
-        return sorted(results, key=lambda x: x["depth"])
+        # Qualified query (Type.method): also surface the name-only bucket's
+        # direct callers — calls whose receiver couldn't be statically typed
+        # (e.g. `adapter = self.get_adapter(url); adapter.send()`). They MAY hit
+        # this method, so we don't drop them, but flag resolved=False rather than
+        # claim false precision. An unqualified query already includes them.
+        if want_receiver is not None:
+            method = entity_name.rsplit(".", 1)[1]
+            bucket = f"{project}:{method}"
+            if bucket in self.graph and bucket not in target_set:
+                for pred in self.graph.predecessors(bucket):
+                    if pred in visited:
+                        continue
+                    rel = [e for e in self.graph.get_edge_data(pred, bucket).values()
+                           if e.get("type") in {"CALLS", "USES_VAR", "REFERENCES"}]
+                    node = self.graph.nodes[pred]
+                    if not rel or node.get("type") != "Entity":
+                        continue
+                    ce = next((e for e in rel if e.get("source_file")), rel[0])
+                    results.append({
+                        "caller_name": node.get("name"),
+                        "caller_type": node.get("entity_type"),
+                        "caller_file": ce.get("source_file") or node.get("file"),
+                        "line": ce.get("line"),
+                        "receiver": next((e.get("receiver") for e in rel if e.get("receiver")), None),
+                        "receiver_type": None,
+                        "resolved": False,
+                        "depth": 1,
+                    })
+                    visited.add(pred)
+
+        return sorted(results, key=lambda x: (not x.get("resolved", True), x["depth"]))
+
+    def grep_graph(self, pattern: str, project: str, field: str = "all",
+                   ignore_case: bool = True, limit: int = 100) -> dict:
+        """Regex-search the graph — 'grep' for entities instead of file lines.
+
+        Matches `pattern` against each entity's name / file / kind / description
+        (or a single `field`), returning the matching entities with the field
+        that hit and the matched text. This is the graph-native replacement for
+        grepping source: full regex power, but over the indexed symbols rather
+        than raw text.
+        """
+        flags = re.IGNORECASE if ignore_case else 0
+        try:
+            rx = re.compile(pattern, flags)
+        except re.error as exc:
+            return {"pattern": pattern, "error": f"invalid regex: {exc}", "matches": [], "count": 0}
+
+        fields = ["name", "file", "kind", "description"] if field == "all" else [field]
+        matches = []
+        for _n, a in self.graph.nodes(data=True):
+            if a.get("type") != "Entity" or a.get("project") != project:
+                continue
+            for f in fields:
+                val = str(a.get(f) or "")
+                m = rx.search(val) if val else None
+                if m:
+                    matches.append({
+                        "name": a.get("name"),
+                        "kind": a.get("kind"),
+                        "file": a.get("file"),
+                        "matched_field": f,
+                        "match": m.group(0),
+                    })
+                    break
+            if len(matches) >= limit:
+                break
+        matches.sort(key=lambda r: (r["file"] or "", r["name"] or ""))
+        return {"pattern": pattern, "matches": matches, "count": len(matches)}
 
     def search_entities(self, query: str, project: str, limit: int = 30,
                         kind: str | None = None) -> list[dict]:
@@ -482,22 +640,19 @@ class LocalGraphClient:
 
     def find_styles(self, element_name: str, project: str) -> list[dict]:
         """Return all CSS selectors that style element_name."""
-        target_id = f"{project}:{element_name.lower()}"
-        if target_id not in self.graph:
-            return []
-            
         results = []
-        for pred in self.graph.predecessors(target_id):
-            edges = self.graph.get_edge_data(pred, target_id)
-            for key, edge in edges.items():
-                if edge.get("type") == "STYLES":
-                    node = self.graph.nodes[pred]
-                    results.append({
-                        "selector": node.get("name"),
-                        "source_file": node.get("file"),
-                        "line": edge.get("line")
-                    })
-        
+        for target_id in self._resolve_query_nodes(element_name, project):
+            for pred in self.graph.predecessors(target_id):
+                edges = self.graph.get_edge_data(pred, target_id)
+                for key, edge in edges.items():
+                    if edge.get("type") == "STYLES":
+                        node = self.graph.nodes[pred]
+                        results.append({
+                            "selector": node.get("name"),
+                            "source_file": node.get("file"),
+                            "line": edge.get("line")
+                        })
+
         return sorted(results, key=lambda x: x["selector"])
 
     def trace_flow(self, start_name: str, project: str, max_hops: int = 6,
@@ -506,9 +661,10 @@ class LocalGraphClient:
         """BFS from start_name along CALLS/IMPORTS edges. Returns nodes + edges for rendering."""
         if edge_types is None:
             edge_types = frozenset({"CALLS", "IMPORTS"})
-        start_id = f"{project}:{start_name.lower()}"
-        if start_id not in self.graph:
+        starts = self._resolve_query_nodes(start_name, project)
+        if not starts:
             return {"nodes": [], "edges": []}
+        start_id = starts[0]
 
         flow_nodes: dict[str, dict] = {}
         flow_edges: list[dict] = []
@@ -563,9 +719,10 @@ class LocalGraphClient:
 
     def trace_calls(self, start_name: str, project: str, max_hops: int = 4) -> list[dict]:
         """Trace the call chain forward from start_name up to max_hops deep."""
-        start_id = f"{project}:{start_name.lower()}"
-        if start_id not in self.graph:
+        starts = self._resolve_query_nodes(start_name, project)
+        if not starts:
             return []
+        start_id = starts[0]
 
         results = []
         visited = {start_id}
@@ -686,14 +843,13 @@ class LocalGraphClient:
         self, target: str, project: str, max_hops: int = 3
     ) -> tuple[list[dict], str | None]:
         """Return all files reachable from target via CALLS/IMPORTS/INHERITS."""
-        # Try as entity name first
-        entity_id = f"{project}:{target.lower()}"
+        # Try as entity name first (may resolve to several same-named nodes).
+        ent_nodes = self._resolve_query_nodes(target, project) if "/" not in target else []
         target_file = None
 
-        if entity_id in self.graph:
-            node = self.graph.nodes[entity_id]
-            target_file = node.get("file")
-            start_ids = [entity_id]
+        if ent_nodes:
+            target_file = self.graph.nodes[ent_nodes[0]].get("file")
+            start_ids = ent_nodes
         else:
             # Try as file path
             file_node = next((n for n, attr in self.graph.nodes(data=True)

{codecompass_mcp-2.7.0 → codecompass_mcp-2.8.0}/graph/code_query_cli.py

@@ -51,6 +51,17 @@ def fetch_impact(entity_name: str, repo_path: str, project: str, max_hops: int =
     return {"entity": entity_name, "callers": rows, "updated_at": updated_at}
 
 
+def fetch_grep(pattern: str, repo_path: str, project: str, field: str = "all",
+               ignore_case: bool = True, limit: int = 100) -> dict:
+    """Regex-search the graph — 'grep' over indexed entities, not file lines."""
+    client = get_client(repo_path)
+    try:
+        return client.grep_graph(pattern, project, field=field,
+                                 ignore_case=ignore_case, limit=limit)
+    finally:
+        client.close()
+
+
 def fetch_search(query: str, repo_path: str, project: str, limit: int = 30,
                  kind: str | None = None) -> dict:
     """Search the graph for entities matching a keyword — the discovery entry point."""
@@ -322,6 +333,16 @@ def main() -> None:
         run_flow(args.flow, repo_path, project, max_hops=args.hops, rich=rich,
                  output=args.flow_output, include_external=args.include_external,
                  fmt=args.format)
+    elif args.flow_summary:
+        run_flow(args.flow_summary, repo_path, project, max_hops=args.hops, rich=rich,
+                 output=args.flow_output, include_external=args.include_external,
+                 fmt=args.format if args.format != "drawio" else "mermaid")
+    elif args.map:
+        print(json.dumps(fetch_map(repo_path, project), indent=2))
+    elif args.search:
+        print(json.dumps(fetch_search(args.search, repo_path, project), indent=2))
+    elif args.grep:
+        print(json.dumps(fetch_grep(args.grep, repo_path, project), indent=2))
     elif args.dead_code:
         run_dead_code(repo_path, project, rich=rich, show_entrypoints=args.include_entrypoints)
     elif args.tree:
@@ -999,6 +1020,14 @@ def _parse_args() -> argparse.Namespace:
     parser.add_argument("--styles", metavar="ELEMENT")
     parser.add_argument("--trace", metavar="ENTITY")
     parser.add_argument("--flow", metavar="ENTITY")
+    parser.add_argument("--flow-summary", metavar="ENTITY",
+                        help="Flow trace + rendered narration (mermaid by default) for a human")
+    parser.add_argument("--map", action="store_true",
+                        help="Compact {file: [symbols]} index to reason over during discovery")
+    parser.add_argument("--search", metavar="KEYWORDS",
+                        help="Keyword search over entity names/files/descriptions")
+    parser.add_argument("--grep", metavar="REGEX",
+                        help="Regex search over graph entities (grep for the graph)")
     parser.add_argument("--flow-output", metavar="PATH", default=None)
     parser.add_argument("--include-external", action="store_true",
                         help="Include external/stdlib symbols in --flow output")

{codecompass_mcp-2.7.0 → codecompass_mcp-2.8.0}/ingestion/code_parser.py

@@ -377,13 +377,38 @@ def _py_type_name(ann: Node | None) -> str | None:
     return None
 
 
+def _py_return_types(root: Node) -> dict[str, str]:
+    """Map function name -> its declared return type (`def f(...) -> Foo:`).
+
+    Enables return-type inference: `x = self.get_adapter(url)` gets typed by
+    `get_adapter`'s `-> BaseAdapter` annotation. Same-named functions with
+    conflicting return types are dropped (can't disambiguate statically)."""
+    rets: dict[str, str] = {}
+    conflict: set[str] = set()
+    for node in _walk(root):
+        if node.type == "function_definition":
+            name = _get_node_name(node, ["identifier"])
+            rt = node.child_by_field_name("return_type")
+            t = _py_type_name(rt) if rt is not None else None
+            if name and t:
+                if name in rets and rets[name] != t:
+                    conflict.add(name)
+                else:
+                    rets[name] = t
+    for name in conflict:
+        rets.pop(name, None)
+    return rets
+
+
 def _py_type_env(root: Node) -> dict[str, str]:
     """Best-effort variable → class map for a Python module.
 
-    Binds from unambiguous local signals: `x = Foo()` instantiations and
-    annotations (`x: Foo`, `def f(x: Foo)`). A name bound to two different types
-    is dropped rather than mis-resolved.
+    Binds from unambiguous local signals: `x = Foo()` instantiations, type
+    annotations (`x: Foo`, `def f(x: Foo)`), and return-type inference
+    (`x = get_thing()` where `get_thing` is declared `-> Foo`). A name bound to
+    two different types is dropped rather than mis-resolved.
     """
+    ret_types = _py_return_types(root)
     types: dict[str, str] = {}
     ambiguous: set[str] = set()
 
@@ -405,6 +430,11 @@ def _py_type_env(root: Node) -> dict[str, str]:
                 bind(name, _py_type_name(ann))
                 if ann is None:
                     bind(name, _py_call_class(right))
+                    # return-type inference: x = fn(...) / x = obj.fn(...)
+                    if right is not None and right.type == "call":
+                        callee = _extract_python_call_parts(right)[0]
+                        if callee:
+                            bind(name, ret_types.get(callee))
         elif node.type in ("typed_parameter", "typed_default_parameter"):
             ident = _child_of_type(node, "identifier")
             ann = node.child_by_field_name("type")
@@ -1126,14 +1156,17 @@ def _type_from_annotation(ann: Node | None) -> str | None:
 def _js_type_env(root: Node) -> dict[str, str]:
     """Best-effort variable → type map for a file.
 
-    Binds from two unambiguous, local signals:
+    Binds from unambiguous, local signals:
       - `var x = new Foo()`            -> x : Foo
       - TS annotations `let x: Foo`,
         `function f(x: Foo)`           -> x : Foo
+      - return-type inference `const x = getThing()` where TS declares
+        `function getThing(): Foo`    -> x : Foo
 
     A name bound to two different types anywhere in the file is dropped as
     ambiguous — better to fall back to name-based handling than to mis-resolve.
     """
+    ret_types = _js_return_types(root)
     types: dict[str, str] = {}
     ambiguous: set[str] = set()
 
@@ -1152,6 +1185,11 @@ def _js_type_env(root: Node) -> dict[str, str]:
             value = node.child_by_field_name("value")
             bind(name, _new_expression_type(value))
             bind(name, _type_from_annotation(_child_of_type(node, "type_annotation")))
+            # return-type inference: const x = fn(...) / const x = obj.fn(...)
+            if value is not None and value.type == "call_expression":
+                callee = _extract_js_call(value)[0]
+                if callee:
+                    bind(name, ret_types.get(callee))
         elif node.type in ("required_parameter", "optional_parameter"):
             pat = node.child_by_field_name("pattern") or _child_of_type(node, "identifier")
             ann = _child_of_type(node, "type_annotation")
@@ -1162,6 +1200,29 @@ def _js_type_env(root: Node) -> dict[str, str]:
     return types
 
 
+def _js_return_types(root: Node) -> dict[str, str]:
+    """Map function name -> its TS return type (`function f(): Foo` / `f(): Foo`).
+
+    Same-named functions with conflicting return types are dropped."""
+    rets: dict[str, str] = {}
+    conflict: set[str] = set()
+    for node in _walk(root):
+        if node.type in ("function_declaration", "function_expression", "method_definition"):
+            name_node = (_child_of_type(node, "identifier")
+                         or _child_of_type(node, "property_identifier"))
+            rt = node.child_by_field_name("return_type")
+            t = _type_from_annotation(rt) if rt is not None else None
+            if name_node is not None and t:
+                name = _text(name_node)
+                if name in rets and rets[name] != t:
+                    conflict.add(name)
+                else:
+                    rets[name] = t
+    for name in conflict:
+        rets.pop(name, None)
+    return rets
+
+
 def _enclosing_class_name(node: Node) -> str | None:
     """Name of the nearest enclosing `class C { ... }`, for resolving `this`."""
     current = node.parent

{codecompass_mcp-2.7.0 → codecompass_mcp-2.8.0}/main.py

@@ -334,55 +334,50 @@ human-readable `description`. Use it as your primary navigation tool.
 
 All commands default to the current directory — run them from the project root.
 
-### Rules
-
-0. **Orient before you search.** When you don't yet know where something lives,
-   start from the graph — `codecompass query --tree` to see what's where, then
-   `--flow`/`--impact`/`--deps` to trace from an entry point — instead of blind
-   grepping. Once you know the string/symbol you want, or need to confirm a
-   result, grep/cat/read are fine. Pick the tool that fits; the graph is the
-   default reflex for structure/relationship questions, not a hard requirement.
-1. **Before editing any file**, run `--blast-radius` on it to see what depends on it:
-   ```bash
-   codecompass query --blast-radius <file_or_symbol>
-   ```
-2. **Before calling or importing a symbol you haven't read**, run `--impact` to
-   understand its downstream effects:
-   ```bash
-   codecompass query --impact <symbol>
-   ```
-3. **After creating or deleting files**, re-ingest so the graph stays current:
-   ```bash
-   codecompass ingest-code
-   ```
-4. **Never skip step 1.** Reading a file without checking its blast radius first
-   means you may miss callers, importers, or CSS/HTML dependents.
-
-### Graph vs. `ls`/`find` — how to decide
-
-Use **codecompass** when the question is about code structure or relationships:
-"what calls this", "what depends on this file", "what does this module do",
-"how does this flow work", "is this dead code". The graph knows the real
-dependency edges; a directory listing does not.
-
-Use **`ls`/`find`** when the question has nothing to do with code
-relationships: confirming a generated/output file exists, listing a
-build/dist/log directory, checking test fixtures or assets, or any path the
-graph doesn't index. These are fine — don't force codecompass onto questions
-it can't answer.
-
-### Available queries
-
-| Command | Purpose |
-|---|---|
-| `codecompass query --blast-radius <file_or_symbol>` | All nodes affected if you change this |
-| `codecompass query --impact <symbol>` | Downstream callers / importers of a symbol |
-| `codecompass query --deps <file>` | What this file depends on |
-| `codecompass query --tree` | Full project structure with entity types |
-| `codecompass query --dead-code` | Find functions/classes with no caller or importer (candidates to remove) |
-| `codecompass query --flow <entry_symbol>` | Trace a call/import flow from an entry point (draw.io diagram by default) |
-| `codecompass query --flow <entry_symbol> --format mermaid` | Same trace as a Markdown mermaid flowchart (renders on GitHub) |
-| `codecompass query --flow <entry_symbol> --format json` | Same trace enriched with signatures, docstrings, and source snippets |
+### The loop: discover → trace → read → edit
+
+1. **Discover** — find the symbol(s) you care about (pick by what you have):
+
+   | You have… | Use | Example |
+   |---|---|---|
+   | a feature request that names a concept ("session timeout", "adapter retries") | `--grep <concept>` first | `--grep "^Session"` — scope straight to it (cheap); only fall back to `--map` if the concept isn't a symbol name |
+   | a regex / name pattern | `--grep <regex>` | `--grep "^get_"`, `--grep ".*Adapter$"` |
+   | keywords | `--search <words>` | `--search "session cookie"` |
+   | a truly nameless need ("where does caching go?" with no `cache` symbol) | `--map` | read the compact index and reason about where it belongs |
+   | the full layout | `--tree` | (large — prefer `--map` for reasoning) |
+
+2. **Trace** — understand relationships around a known symbol/file:
+
+   | Question | Use |
+   |---|---|
+   | who calls / would break if I change this symbol? | `--impact <symbol>` |
+   | what files are affected if I edit this file? | `--blast-radius <file>` |
+   | what does this file depend on? | `--deps <file>` |
+   | what does this entry point call, step by step? | `--flow <symbol>` (lean structure) |
+   | explain a flow to a human (diagram + narration) | `--flow-summary <symbol>` |
+   | is anything unused? | `--dead-code` |
+
+3. **Read** the specific slice the graph pointed you to (Read tool / `sed -n`),
+   not the whole file.
+
+4. **Edit** — and before editing, `--impact`/`--blast-radius` the target so you
+   don't miss a caller or dependent. After adding/deleting files, re-ingest.
+
+### Reading the results
+
+- `--impact` rows carry `resolved`: `true` = the receiver was statically typed
+  (trust it); `false` = receiver type unknown, this call *might* target the
+  symbol (verify by reading the slice at `caller_file:line`).
+- `--flow` is lean (structure only). Start at `hops=1` and only go deeper along
+  the one path you actually need — deep hops on a high-fan-out symbol are large.
+- `--dead-code` is a candidate list — static analysis misses dynamic dispatch,
+  so read each before removing.
+
+### Graph vs. `ls`/`find`
+
+`ls`/`find` are for non-code paths the graph doesn't index (build/dist/log
+output, fixtures, confirming a generated file exists). For anything about code
+structure or relationships, use the graph.
 
 ### Explaining how something works
 

{codecompass_mcp-2.7.0 → codecompass_mcp-2.8.0}/mcp_server.py

@@ -28,6 +28,7 @@ from graph.code_query_cli import (
     fetch_deps,
     fetch_flow,
     fetch_flow_summary,
+    fetch_grep,
     fetch_impact,
     fetch_map,
     fetch_search,
@@ -154,6 +155,23 @@ def styles(element: str) -> dict:
     return fetch_styles(element, repo, os.path.basename(repo))
 
 
+@mcp.tool()
+def grep(pattern: str, field: str = "all", ignore_case: bool = True, limit: int = 100) -> dict:
+    """Regex-search the graph — 'grep' over indexed entities instead of file text.
+
+    Matches `pattern` (a Python regex) against each entity's name / file / kind /
+    description (or one `field`), returning matching entities with the field that
+    hit. This is the graph-native replacement for grepping source: full regex
+    power over the symbols the graph knows about. Use it to find symbols by
+    pattern (`^test_`, `.*Adapter$`, `handle|dispatch`), then drill in with
+    impact/flow/deps.
+    """
+    repo = _active_repo()
+    _ensure_initialized(repo)
+    return fetch_grep(pattern, repo, os.path.basename(repo), field=field,
+                      ignore_case=ignore_case, limit=limit)
+
+
 @mcp.tool()
 def map(include_tests: bool = False) -> dict:
     """Compact `{file: [symbols]}` index of the codebase — the discovery entry

{codecompass_mcp-2.7.0 → codecompass_mcp-2.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codecompass-mcp"
-version = "2.7.0"
+version = "2.8.0"
 description = "Structural code context for AI coding agents — a local code knowledge graph for blast radius, impact, deps, dead code, and flow tracing"
 readme = "README.md"
 license = {text = "MIT"}

{codecompass_mcp-2.7.0 → codecompass_mcp-2.8.0}/tests/test_accuracy_fixes.py

@@ -339,6 +339,39 @@ def test_python_public_method_marked_exported():
     assert by_name.get("_private") is False, "underscore method is not exported"
 
 
+def test_graph_grep_regex():
+    triples = [
+        CodeTriple("HTTPAdapter", "class", "DEFINED_IN", "m", "module", "adapters.py", 1),
+        CodeTriple("get_adapter", "function", "DEFINED_IN", "m", "module", "sessions.py", 5),
+        CodeTriple("send", "function", "DEFINED_IN", "m", "module", "sessions.py", 9),
+    ]
+    client = _client()
+    _write(client, triples)
+    # anchored regex on name
+    r = client.grep_graph("^get_", "proj", field="name")
+    assert {m["name"] for m in r["matches"]} == {"get_adapter"}
+    # alternation across name
+    r2 = client.grep_graph("Adapter|send", "proj", field="name")
+    assert {m["name"] for m in r2["matches"]} == {"HTTPAdapter", "get_adapter", "send"}
+    # field filter
+    r3 = client.grep_graph("sessions", "proj", field="file")
+    assert {m["name"] for m in r3["matches"]} == {"get_adapter", "send"}
+    # bad regex is reported, not raised
+    assert "error" in client.grep_graph("(", "proj")
+
+
+def test_python_return_type_inference():
+    src = ("class Session:\n"
+           "    def get_adapter(self, url) -> HTTPAdapter:\n"
+           "        return self.a\n"
+           "    def send(self, req):\n"
+           "        adapter = self.get_adapter(req.url)\n"
+           "        return adapter.send(req)\n")
+    triples = _parse_py(src)
+    call = next(t for t in triples if t.relation_type == "CALLS" and t.to_entity == "send")
+    assert call.call_receiver_type == "HTTPAdapter", "return type of get_adapter should type `adapter`"
+
+
 def test_python_public_module_function_marked_exported():
     src = "def has_app_context():\n    return True\n\ndef _helper():\n    pass\n"
     triples = _parse_py(src)