codecompass-mcp 5.2.0__tar.gz → 6.0.0__tar.gz

{codecompass_mcp-5.2.0 → codecompass_mcp-6.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecompass-mcp
-Version: 5.2.0
+Version: 6.0.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
@@ -156,17 +156,21 @@ The index follows the graph's lifecycle: wiped and rebuilt at the end of every
 `ingest`, so parser nodes *and* agent-recorded ones are searchable. Without the
 extra, ingest simply skips the vector step.
 
-### Enrichment (agent-in-the-loop)
+### Agent-written knowledge
 
-Via the MCP tools: `enrich` stages entities for an agent swarm (one-line
-descriptions + missing call edges), `enrich(apply=True)` merges the swarm's
-results, and `add_entity` / `add_call` record single parser-missed entries.
+The parser extracts structure. Everything it *can't* see — dynamic dispatch,
+callbacks, runtime registration — and everything it can't know — what an entity
+is FOR — comes from the agent reading the code and writing it back with
+`add_entity` / `add_call`. There is no bulk enrichment pass and no LLM
+backfill: the graph improves as it gets used, or not at all.
 
-`enrich` is a bulk, user-triggered pass. `add_entity`/`add_call` are the
-opportunistic version: as an agent reads code and spots something the parser
-missed, it records it immediately. Everything agent-written is marked
-`agent_inferred` and **preserved across re-ingests** — the graph gets better
-with use. Ambiguous call targets are skipped, never guessed.
+Descriptions live in `.codecompass/description.jsonl`, one
+`{"node": "<id>", "description": "..."}` per line, joined onto every query
+result by node id. Keeping them out of `graph.json` means they survive the
+wholesale rebuild each `ingest` performs (and a deleted `graph.json`), while
+entries whose node vanishes from the source are pruned on the next ingest.
+Agent-written nodes and edges are marked `agent_inferred`; ambiguous call
+targets are skipped, never guessed.
 
 ### Flow: `flow` vs `flow-summary`
 
@@ -191,9 +195,8 @@ with use. Ambiguous call targets are skipped, never guessed.
 | `dead_code(include_entrypoints)` | Entities with no inbound caller |
 | `styles(element)` | CSS selectors that style an element |
 | `tree()` | Full project hierarchy |
-| `enrich(apply, batch_size)` | Stage/merge agent-written descriptions + missing call edges |
-| `add_entity(name, kind, file, line, description)` | Record a parser-missed entity (`agent_inferred`) |
-| `add_call(caller, callee, line)` | Record a parser-missed CALLS edge (`agent_inferred`) |
+| `add_entity(name, kind, file, line, description)` | Record a parser-missed entity, or describe an existing one (`agent_inferred`) |
+| `add_call(caller, callee, line, relation)` | Record a parser-missed CALLS/IMPORTS/INHERITS edge (`agent_inferred`) |
 | `set_repo` / `get_repo` / `init` / `ingest` | Project selection & indexing |
 
 ---
@@ -243,9 +246,11 @@ Source files
    ▼  code_queries       traversal helpers: grep / impact / blast_radius /
                           deps / flow / dead_code / tree
    ▼  mcp_server         FastMCP server — the only query surface for agents
-   ▼  enricher            agent-in-the-loop: enrich batches (descriptions +
-                          missing calls) and opportunistic add_entity/add_call
-                          writes — agent_inferred, preserved across re-ingest
+   ▼  agent_writes        add_entity / add_call: what the parser can't see,
+                          written back by the agent — agent_inferred, preserved
+                          across re-ingest
+   ▼  description.jsonl   node id → description, joined onto every result;
+                          outlives the graph rebuild, pruned when a node dies
    ▼  vector_store        optional: entity embeddings in vectors.lance (LanceDB
                           + fastembed), wiped & rebuilt on every ingest
 ```
@@ -258,9 +263,13 @@ Inside each indexed project:
 
 ```
 your-project/
-├── .codecompass/graph.json      the code knowledge graph (auto-generated)
-├── .codecompass/vectors.lance/  semantic search index (optional, rebuilt on ingest)
-└── AGENTS.md                    discovery guide for agents (auto-updated)
+├── .codecompass/graph.json           the code knowledge graph (auto-generated)
+├── .codecompass/description.jsonl    agent-written descriptions, keyed by node id
+├── .codecompass/overview.md          what this repo is (agent-maintained)
+├── .codecompass/memory.md            how it's built (agent-maintained)
+├── .codecompass/learnings.md         what to watch out for (agent-maintained)
+├── .codecompass/vectors.lance/       semantic search index (optional, rebuilt on ingest)
+└── AGENTS.md                         discovery guide for agents (auto-updated)
 ```
 
 ---
@@ -268,9 +277,9 @@ your-project/
 ## Limitations
 
 - **Structure first, semantics layered on** — the parser knows what calls what,
-  not what it means. Two optional layers close that gap: `enrich` (agent-written
-  descriptions and missed edges, marked `agent_inferred`) and `search`
-  (semantic vector search over those descriptions and names).
+  not what it means. Agents close that gap as they work (`add_entity` /
+  `add_call`, marked `agent_inferred`), and `search` makes the result
+  semantically findable. An unexplored corner of the repo stays undescribed.
 - **Static analysis** — dynamic dispatch, reflection, and string-based invocation
   can't be fully resolved. `impact` surfaces those flagged `resolved: false`, and
   `dead_code` results are always candidates to verify.

{codecompass_mcp-5.2.0 → codecompass_mcp-6.0.0}/README.md

@@ -117,17 +117,21 @@ The index follows the graph's lifecycle: wiped and rebuilt at the end of every
 `ingest`, so parser nodes *and* agent-recorded ones are searchable. Without the
 extra, ingest simply skips the vector step.
 
-### Enrichment (agent-in-the-loop)
-
-Via the MCP tools: `enrich` stages entities for an agent swarm (one-line
-descriptions + missing call edges), `enrich(apply=True)` merges the swarm's
-results, and `add_entity` / `add_call` record single parser-missed entries.
-
-`enrich` is a bulk, user-triggered pass. `add_entity`/`add_call` are the
-opportunistic version: as an agent reads code and spots something the parser
-missed, it records it immediately. Everything agent-written is marked
-`agent_inferred` and **preserved across re-ingests** — the graph gets better
-with use. Ambiguous call targets are skipped, never guessed.
+### Agent-written knowledge
+
+The parser extracts structure. Everything it *can't* see — dynamic dispatch,
+callbacks, runtime registration — and everything it can't know — what an entity
+is FOR — comes from the agent reading the code and writing it back with
+`add_entity` / `add_call`. There is no bulk enrichment pass and no LLM
+backfill: the graph improves as it gets used, or not at all.
+
+Descriptions live in `.codecompass/description.jsonl`, one
+`{"node": "<id>", "description": "..."}` per line, joined onto every query
+result by node id. Keeping them out of `graph.json` means they survive the
+wholesale rebuild each `ingest` performs (and a deleted `graph.json`), while
+entries whose node vanishes from the source are pruned on the next ingest.
+Agent-written nodes and edges are marked `agent_inferred`; ambiguous call
+targets are skipped, never guessed.
 
 ### Flow: `flow` vs `flow-summary`
 
@@ -152,9 +156,8 @@ with use. Ambiguous call targets are skipped, never guessed.
 | `dead_code(include_entrypoints)` | Entities with no inbound caller |
 | `styles(element)` | CSS selectors that style an element |
 | `tree()` | Full project hierarchy |
-| `enrich(apply, batch_size)` | Stage/merge agent-written descriptions + missing call edges |
-| `add_entity(name, kind, file, line, description)` | Record a parser-missed entity (`agent_inferred`) |
-| `add_call(caller, callee, line)` | Record a parser-missed CALLS edge (`agent_inferred`) |
+| `add_entity(name, kind, file, line, description)` | Record a parser-missed entity, or describe an existing one (`agent_inferred`) |
+| `add_call(caller, callee, line, relation)` | Record a parser-missed CALLS/IMPORTS/INHERITS edge (`agent_inferred`) |
 | `set_repo` / `get_repo` / `init` / `ingest` | Project selection & indexing |
 
 ---
@@ -204,9 +207,11 @@ Source files
    ▼  code_queries       traversal helpers: grep / impact / blast_radius /
                           deps / flow / dead_code / tree
    ▼  mcp_server         FastMCP server — the only query surface for agents
-   ▼  enricher            agent-in-the-loop: enrich batches (descriptions +
-                          missing calls) and opportunistic add_entity/add_call
-                          writes — agent_inferred, preserved across re-ingest
+   ▼  agent_writes        add_entity / add_call: what the parser can't see,
+                          written back by the agent — agent_inferred, preserved
+                          across re-ingest
+   ▼  description.jsonl   node id → description, joined onto every result;
+                          outlives the graph rebuild, pruned when a node dies
    ▼  vector_store        optional: entity embeddings in vectors.lance (LanceDB
                           + fastembed), wiped & rebuilt on every ingest
 ```
@@ -219,9 +224,13 @@ Inside each indexed project:
 
 ```
 your-project/
-├── .codecompass/graph.json      the code knowledge graph (auto-generated)
-├── .codecompass/vectors.lance/  semantic search index (optional, rebuilt on ingest)
-└── AGENTS.md                    discovery guide for agents (auto-updated)
+├── .codecompass/graph.json           the code knowledge graph (auto-generated)
+├── .codecompass/description.jsonl    agent-written descriptions, keyed by node id
+├── .codecompass/overview.md          what this repo is (agent-maintained)
+├── .codecompass/memory.md            how it's built (agent-maintained)
+├── .codecompass/learnings.md         what to watch out for (agent-maintained)
+├── .codecompass/vectors.lance/       semantic search index (optional, rebuilt on ingest)
+└── AGENTS.md                         discovery guide for agents (auto-updated)
 ```
 
 ---
@@ -229,9 +238,9 @@ your-project/
 ## Limitations
 
 - **Structure first, semantics layered on** — the parser knows what calls what,
-  not what it means. Two optional layers close that gap: `enrich` (agent-written
-  descriptions and missed edges, marked `agent_inferred`) and `search`
-  (semantic vector search over those descriptions and names).
+  not what it means. Agents close that gap as they work (`add_entity` /
+  `add_call`, marked `agent_inferred`), and `search` makes the result
+  semantically findable. An unexplored corner of the repo stays undescribed.
 - **Static analysis** — dynamic dispatch, reflection, and string-based invocation
   can't be fully resolved. `impact` surfaces those flagged `resolved: false`, and
   `dead_code` results are always candidates to verify.

{codecompass_mcp-5.2.0 → codecompass_mcp-6.0.0}/codecompass_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecompass-mcp
-Version: 5.2.0
+Version: 6.0.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
@@ -156,17 +156,21 @@ The index follows the graph's lifecycle: wiped and rebuilt at the end of every
 `ingest`, so parser nodes *and* agent-recorded ones are searchable. Without the
 extra, ingest simply skips the vector step.
 
-### Enrichment (agent-in-the-loop)
+### Agent-written knowledge
 
-Via the MCP tools: `enrich` stages entities for an agent swarm (one-line
-descriptions + missing call edges), `enrich(apply=True)` merges the swarm's
-results, and `add_entity` / `add_call` record single parser-missed entries.
+The parser extracts structure. Everything it *can't* see — dynamic dispatch,
+callbacks, runtime registration — and everything it can't know — what an entity
+is FOR — comes from the agent reading the code and writing it back with
+`add_entity` / `add_call`. There is no bulk enrichment pass and no LLM
+backfill: the graph improves as it gets used, or not at all.
 
-`enrich` is a bulk, user-triggered pass. `add_entity`/`add_call` are the
-opportunistic version: as an agent reads code and spots something the parser
-missed, it records it immediately. Everything agent-written is marked
-`agent_inferred` and **preserved across re-ingests** — the graph gets better
-with use. Ambiguous call targets are skipped, never guessed.
+Descriptions live in `.codecompass/description.jsonl`, one
+`{"node": "<id>", "description": "..."}` per line, joined onto every query
+result by node id. Keeping them out of `graph.json` means they survive the
+wholesale rebuild each `ingest` performs (and a deleted `graph.json`), while
+entries whose node vanishes from the source are pruned on the next ingest.
+Agent-written nodes and edges are marked `agent_inferred`; ambiguous call
+targets are skipped, never guessed.
 
 ### Flow: `flow` vs `flow-summary`
 
@@ -191,9 +195,8 @@ with use. Ambiguous call targets are skipped, never guessed.
 | `dead_code(include_entrypoints)` | Entities with no inbound caller |
 | `styles(element)` | CSS selectors that style an element |
 | `tree()` | Full project hierarchy |
-| `enrich(apply, batch_size)` | Stage/merge agent-written descriptions + missing call edges |
-| `add_entity(name, kind, file, line, description)` | Record a parser-missed entity (`agent_inferred`) |
-| `add_call(caller, callee, line)` | Record a parser-missed CALLS edge (`agent_inferred`) |
+| `add_entity(name, kind, file, line, description)` | Record a parser-missed entity, or describe an existing one (`agent_inferred`) |
+| `add_call(caller, callee, line, relation)` | Record a parser-missed CALLS/IMPORTS/INHERITS edge (`agent_inferred`) |
 | `set_repo` / `get_repo` / `init` / `ingest` | Project selection & indexing |
 
 ---
@@ -243,9 +246,11 @@ Source files
    ▼  code_queries       traversal helpers: grep / impact / blast_radius /
                           deps / flow / dead_code / tree
    ▼  mcp_server         FastMCP server — the only query surface for agents
-   ▼  enricher            agent-in-the-loop: enrich batches (descriptions +
-                          missing calls) and opportunistic add_entity/add_call
-                          writes — agent_inferred, preserved across re-ingest
+   ▼  agent_writes        add_entity / add_call: what the parser can't see,
+                          written back by the agent — agent_inferred, preserved
+                          across re-ingest
+   ▼  description.jsonl   node id → description, joined onto every result;
+                          outlives the graph rebuild, pruned when a node dies
    ▼  vector_store        optional: entity embeddings in vectors.lance (LanceDB
                           + fastembed), wiped & rebuilt on every ingest
 ```
@@ -258,9 +263,13 @@ Inside each indexed project:
 
 ```
 your-project/
-├── .codecompass/graph.json      the code knowledge graph (auto-generated)
-├── .codecompass/vectors.lance/  semantic search index (optional, rebuilt on ingest)
-└── AGENTS.md                    discovery guide for agents (auto-updated)
+├── .codecompass/graph.json           the code knowledge graph (auto-generated)
+├── .codecompass/description.jsonl    agent-written descriptions, keyed by node id
+├── .codecompass/overview.md          what this repo is (agent-maintained)
+├── .codecompass/memory.md            how it's built (agent-maintained)
+├── .codecompass/learnings.md         what to watch out for (agent-maintained)
+├── .codecompass/vectors.lance/       semantic search index (optional, rebuilt on ingest)
+└── AGENTS.md                         discovery guide for agents (auto-updated)
 ```
 
 ---
@@ -268,9 +277,9 @@ your-project/
 ## Limitations
 
 - **Structure first, semantics layered on** — the parser knows what calls what,
-  not what it means. Two optional layers close that gap: `enrich` (agent-written
-  descriptions and missed edges, marked `agent_inferred`) and `search`
-  (semantic vector search over those descriptions and names).
+  not what it means. Agents close that gap as they work (`add_entity` /
+  `add_call`, marked `agent_inferred`), and `search` makes the result
+  semantically findable. An unexplored corner of the repo stays undescribed.
 - **Static analysis** — dynamic dispatch, reflection, and string-based invocation
   can't be fully resolved. `impact` surfaces those flagged `resolved: false`, and
   `dead_code` results are always candidates to verify.

{codecompass_mcp-5.2.0 → codecompass_mcp-6.0.0}/codecompass_mcp.egg-info/SOURCES.txt

@@ -16,22 +16,23 @@ graph/code_graph_client.py
 graph/code_queries.py
 graph/vector_store.py
 ingestion/__init__.py
+ingestion/agent_writes.py
 ingestion/code_normalizer.py
 ingestion/code_parser.py
-ingestion/enricher.py
 ingestion/file_watcher.py
 ingestion/hierarchy_builder.py
 ingestion/source_context.py
 models/__init__.py
 models/code_types.py
 tests/test_accuracy_fixes.py
+tests/test_agent_writes.py
 tests/test_block_hook.py
 tests/test_code_parser.py
-tests/test_enrich_preserve.py
-tests/test_enricher.py
+tests/test_descriptions.py
 tests/test_ingest_progress.py
 tests/test_init.py
 tests/test_lit_css_parser.py
 tests/test_mcp_server.py
 tests/test_php_parser.py
+tests/test_pi_setup.py
 tests/test_vector_store.py

{codecompass_mcp-5.2.0 → codecompass_mcp-6.0.0}/graph/code_graph_client.py

@@ -37,6 +37,52 @@ def _now() -> str:
     return datetime.now(timezone.utc).isoformat()
 
 
+# Descriptions do NOT live on the graph nodes. graph.json is parser output,
+# rebuilt from scratch on every ingest; a description is the one thing in the
+# graph no parser can regenerate, so it lives in its own sidecar keyed by node
+# id and is joined back on read. One {"node", "description"} object per line —
+# line-diffable, greppable, and survives a deleted or corrupt graph.json.
+DESCRIPTIONS_FILE = os.path.join(".codecompass", "description.jsonl")
+
+
+def descriptions_path(repo_path: str) -> str:
+    return os.path.join(repo_path, DESCRIPTIONS_FILE)
+
+
+def load_descriptions(repo_path: str) -> dict[str, str]:
+    """Read the sidecar as {node_id: description}.
+
+    A missing file or an unparseable line yields nothing rather than raising —
+    a query must still answer when the sidecar is absent.
+    """
+    out: dict[str, str] = {}
+    try:
+        with open(descriptions_path(repo_path), encoding="utf-8") as f:
+            for line in f:
+                if not line.strip():
+                    continue
+                try:
+                    row = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if row.get("node") and row.get("description"):
+                    out[row["node"]] = row["description"]
+    except OSError:
+        pass
+    return out
+
+
+def save_descriptions(repo_path: str, descriptions: dict[str, str]) -> int:
+    """Write the sidecar, one JSON object per line, sorted by node id."""
+    path = descriptions_path(repo_path)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        for nid in sorted(descriptions):
+            if descriptions[nid]:
+                f.write(json.dumps({"node": nid, "description": descriptions[nid]}) + "\n")
+    return len(descriptions)
+
+
 def _entity_id(project: str, name: str, file: str | None, owner: str | None = None) -> str:
     """Node id for an entity — file- and class-qualified so same-named entities
     stay distinct across files AND across classes in the same file. Case is
@@ -148,9 +194,38 @@ class LocalGraphClient:
 
     def __init__(self, storage_path: str) -> None:
         self.storage_path = storage_path
+        # .../<repo>/.codecompass/graph.json -> <repo>
+        self.repo_path = os.path.dirname(os.path.dirname(storage_path))
         self.graph = nx.MultiDiGraph()
+        self.descriptions = load_descriptions(self.repo_path)
+        # Ingest builds a throwaway graph and flips this on only for the final
+        # write, so a half-built graph never rewrites the description sidecar.
+        self.sync_descriptions = True
         self.load()
 
+    def describe(self, node_id: str) -> str:
+        """Description for a node, joined from the sidecar. '' when undescribed."""
+        return self.descriptions.get(node_id, "")
+
+    def set_description(self, node_id: str, text: str) -> None:
+        """Record a description for a node (empty text clears it)."""
+        text = (text or "").strip()
+        if text:
+            self.descriptions[node_id] = text
+        else:
+            self.descriptions.pop(node_id, None)
+
+    def prune_descriptions(self) -> int:
+        """Drop sidecar entries whose node no longer exists in the graph.
+
+        Called after an ingest rebuild: a renamed or deleted symbol takes its
+        description with it instead of lingering as a ghost forever.
+        """
+        stale = [nid for nid in self.descriptions if nid not in self.graph]
+        for nid in stale:
+            del self.descriptions[nid]
+        return len(stale)
+
     def load(self) -> None:
         """Load graph from JSON file."""
         if os.path.exists(self.storage_path):
@@ -161,13 +236,29 @@ class LocalGraphClient:
             except (json.JSONDecodeError, Exception) as e:
                 print(f"Warning: Could not load graph from {self.storage_path} ({e}). Starting fresh.")
                 self.graph = nx.MultiDiGraph()
+            self._adopt_legacy_descriptions()
+
+    def _adopt_legacy_descriptions(self) -> None:
+        """Move descriptions off nodes written by pre-sidecar versions.
+
+        Older graphs stored the description as a node attribute and flagged the
+        agent-authored ones; only those are worth keeping (the rest were
+        generated blurbs like "python function in x.py"). The attributes are
+        dropped as they are read, so this runs exactly once per graph.
+        """
+        for _nid, a in self.graph.nodes(data=True):
+            legacy = a.pop("description", None)
+            if legacy and a.get("agent_inferred"):
+                self.descriptions.setdefault(_nid, legacy)
 
     def save(self) -> None:
-        """Save graph to JSON file."""
+        """Save the graph and its description sidecar."""
         os.makedirs(os.path.dirname(self.storage_path), exist_ok=True)
         data = nx.node_link_data(self.graph, edges="links")
         with open(self.storage_path, "w") as f:
             json.dump(data, f, indent=2)
+        if self.sync_descriptions:
+            save_descriptions(self.repo_path, self.descriptions)
 
     # ------------------------------------------------------------------
     # Structural nodes (hierarchy skeleton)
@@ -232,7 +323,6 @@ class LocalGraphClient:
             "entity_type": triple.from_type,
             "language": language,
             "kind": f"{triple.from_type}:{language}",
-            "description": f"{language} {triple.from_type} in {triple.source_file}",
             "project": project,
             "file": triple.source_file,
         })
@@ -248,7 +338,7 @@ class LocalGraphClient:
         if getattr(triple, "owner_class", None):
             self.graph.nodes[from_id]["owner"] = triple.owner_class
 
-        # Upsert to entity — only set language/kind/description if not already known
+        # Upsert to entity — only set language/kind if not already known
         self.graph.add_node(to_id)
         existing = self.graph.nodes[to_id]
         existing.setdefault("type", "Entity")
@@ -258,7 +348,6 @@ class LocalGraphClient:
         if not existing.get("language"):
             existing["language"] = language
             existing["kind"] = f"{triple.to_type}:{language}"
-            existing["description"] = f"{language} {triple.to_type}"
         # A module's definition is line 1 of its file.
         if triple.relation_type == "DEFINED_IN" and triple.to_type == "module":
             existing.setdefault("line", 1)
@@ -487,6 +576,7 @@ class LocalGraphClient:
                         "caller_type": node.get("entity_type"),
                         "caller_file": call_edge.get("source_file") or node.get("file"),
                         "line": call_edge.get("line"),
+                        "description": self.describe(pred),
                         "receiver": receiver,
                         "receiver_type": receiver_type,
                         "resolved": True,
@@ -520,6 +610,7 @@ class LocalGraphClient:
                         "caller_type": node.get("entity_type"),
                         "caller_file": ce.get("source_file") or node.get("file"),
                         "line": ce.get("line"),
+                        "description": self.describe(pred),
                         "receiver": next((e.get("receiver") for e in rel if e.get("receiver")), None),
                         "receiver_type": None,
                         "resolved": False,
@@ -550,8 +641,11 @@ class LocalGraphClient:
         for _n, a in self.graph.nodes(data=True):
             if a.get("type") != "Entity" or a.get("project") != project:
                 continue
+            description = self.describe(_n)
             for f in fields:
-                val = str(a.get(f) or "")
+                # description is not a node attribute — it is joined from the
+                # sidecar, and grep searches it like any other field.
+                val = description if f == "description" else str(a.get(f) or "")
                 m = rx.search(val) if val else None
                 if m:
                     matches.append({
@@ -559,6 +653,7 @@ class LocalGraphClient:
                         "kind": a.get("kind"),
                         "file": a.get("file"),
                         "line": a.get("line"),
+                        "description": description,
                         "matched_field": f,
                         "match": m.group(0),
                     })
@@ -595,6 +690,7 @@ class LocalGraphClient:
                             "dependency": node.get("name"),
                             "dep_type": node.get("entity_type"),
                             "line": node.get("line"),
+                            "description": self.describe(succ),
                             "depth": depth + 1
                         })
                     
@@ -615,7 +711,8 @@ class LocalGraphClient:
                         results.append({
                             "selector": node.get("name"),
                             "source_file": node.get("file"),
-                            "line": edge.get("line")
+                            "line": edge.get("line"),
+                            "description": self.describe(pred),
                         })
 
         return sorted(results, key=lambda x: x["selector"])
@@ -641,7 +738,7 @@ class LocalGraphClient:
             "id": start_id,
             "name": start_attr.get("name", start_name),
             "kind": start_attr.get("kind", ""),
-            "description": start_attr.get("description", ""),
+            "description": self.describe(start_id),
             "file": start_attr.get("file", ""),
             "line": start_attr.get("line"),
             "depth": 0,
@@ -675,7 +772,7 @@ class LocalGraphClient:
                         "id": succ,
                         "name": succ_attr.get("name", ""),
                         "kind": succ_attr.get("kind", ""),
-                        "description": succ_attr.get("description", ""),
+                        "description": self.describe(succ),
                         "file": succ_attr.get("file", ""),
                         "line": succ_attr.get("line"),
                         "depth": depth + 1,
@@ -712,6 +809,7 @@ class LocalGraphClient:
                             "callee_type": node.get("entity_type"),
                             "callee_file": node.get("file"),
                             "line": node.get("line"),
+                            "description": self.describe(succ),
                             "depth": depth + 1
                         })
                         visited.add(succ)
@@ -784,6 +882,7 @@ class LocalGraphClient:
                 "entity_type": attr.get("entity_type", ""),
                 "file": attr.get("file", ""),
                 "line": attr.get("line"),
+                "description": self.describe(node_id),
             }
             # Exported symbols and name-heuristic entry points are public API:
             # having no in-repo caller is expected, not evidence of dead code.
@@ -919,7 +1018,11 @@ class LocalGraphClient:
                 importers.append(from_file)
         return sorted(set(importers))
 
-def get_client(project_path: str) -> LocalGraphClient:
-    """Return a LocalGraphClient for the project at project_path."""
-    storage_path = os.path.join(project_path, ".codecompass", "graph.json")
+def get_client(project_path: str, filename: str = "graph.json") -> LocalGraphClient:
+    """Return a LocalGraphClient for the project at project_path.
+
+    `filename` exists so ingest can build into `graph.json.copy` and swap it in
+    once the rebuild succeeds, rather than clearing the live graph in place.
+    """
+    storage_path = os.path.join(project_path, ".codecompass", filename)
     return LocalGraphClient(storage_path)

{codecompass_mcp-5.2.0 → codecompass_mcp-6.0.0}/graph/code_queries.py

@@ -172,7 +172,8 @@ def fetch_flow(start_name: str, repo_path: str, project: str, max_hops: int = DE
     edges = _order_edges(edges, project, start_name)
     lean_nodes = [
         {"id": n["id"], "name": n["name"], "kind": n.get("kind", ""),
-         "file": n.get("file", ""), "line": n.get("line"), "depth": n["depth"]}
+         "file": n.get("file", ""), "line": n.get("line"), "depth": n["depth"],
+         "description": n.get("description", "")}
         for n in sorted(nodes, key=lambda n: n["depth"])
     ]
     lean_edges = [

{codecompass_mcp-5.2.0 → codecompass_mcp-6.0.0}/graph/vector_store.py

@@ -47,32 +47,36 @@ def _db_path(repo_path: str) -> str:
     return os.path.join(repo_path, ".codecompass", DB_DIRNAME)
 
 
-def _entity_text(a: dict) -> str:
+def _entity_text(a: dict, description: str) -> str:
     """The string that gets embedded for one entity node."""
     parts = [a.get("kind") or "", a.get("name") or "", a.get("file") or "",
-             a.get("description") or ""]
+             description]
     return " ".join(p for p in parts if p)
 
 
 def index_entities(repo_path: str) -> int:
     """Wipe and rebuild the vector index from graph.json. Returns rows indexed."""
+    from graph.code_graph_client import load_descriptions
+
     lancedb, _ = _deps()
     graph_path = os.path.join(repo_path, ".codecompass", "graph.json")
     with open(graph_path) as f:
         nodes = json.load(f).get("nodes", [])
+    descriptions = load_descriptions(repo_path)
 
     rows = []
     for a in nodes:
         if a.get("type") != "Entity":
             continue
+        description = descriptions.get(a.get("id") or "", "")
         rows.append({
             "id": a.get("id") or "",
             "name": a.get("name") or "",
             "kind": a.get("kind") or "",
             "file": a.get("file") or "",
             "line": a.get("line") or 0,
-            "description": a.get("description") or "",
-            "text": _entity_text(a),
+            "description": description,
+            "text": _entity_text(a, description),
         })
     if not rows:
         return 0