codegraph-brain 0.19.0__tar.gz → 0.21.0__tar.gz

codegraph_brain-0.21.0/.github/test-count-baseline

@@ -0,0 +1 @@
+2459

codegraph_brain-0.21.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.21.0"
+}

{codegraph_brain-0.19.0 → codegraph_brain-0.21.0}/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.21.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.20.0...codegraph-brain-v0.21.0) (2026-09-16)
+
+
+### Features
+
+* **resolver:** resolve JS/TS runtime globals into js_builtins.* ([#111](https://github.com/zaebee/codegraph-brain/issues/111)) ([#453](https://github.com/zaebee/codegraph-brain/issues/453)) ([84e790b](https://github.com/zaebee/codegraph-brain/commit/84e790b404f7a515e048f7a2370b8865b71912ff))
+
+
+### Bug Fixes
+
+* **cli:** a full ingest into a database records file hashes ([#461](https://github.com/zaebee/codegraph-brain/issues/461)) ([e0a4a5e](https://github.com/zaebee/codegraph-brain/commit/e0a4a5ec34f8b0b34220f3f318ce0edc99ed1d9b))
+* **pipeline:** rebuild when a change alters what other files resolve against ([#38](https://github.com/zaebee/codegraph-brain/issues/38)) ([#458](https://github.com/zaebee/codegraph-brain/issues/458)) ([8126fd6](https://github.com/zaebee/codegraph-brain/commit/8126fd6377c82613f9f8a76f33253a8cd9e636f0))
+* **resolver:** Python stdlib names are STDLIB only in Python sources ([#454](https://github.com/zaebee/codegraph-brain/issues/454)) ([#457](https://github.com/zaebee/codegraph-brain/issues/457)) ([15e7ba1](https://github.com/zaebee/codegraph-brain/commit/15e7ba17ae49e2e3c10a2ef9f6cf1f11e663edfb))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#456](https://github.com/zaebee/codegraph-brain/issues/456)) ([ae24054](https://github.com/zaebee/codegraph-brain/commit/ae24054361935dbb1a1f9471eea7b4b949ab8a10))
+* auto-sync architecture graph and MCP reference ([#460](https://github.com/zaebee/codegraph-brain/issues/460)) ([a341063](https://github.com/zaebee/codegraph-brain/commit/a3410631511802bdc9851decadbbbf25b40d8d22))
+
+## [0.20.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.19.0...codegraph-brain-v0.20.0) (2026-09-11)
+
+
+### Features
+
+* **query:** a traversal says how much of its neighbourhood resolved ([#201](https://github.com/zaebee/codegraph-brain/issues/201)) ([#448](https://github.com/zaebee/codegraph-brain/issues/448)) ([0c63469](https://github.com/zaebee/codegraph-brain/commit/0c634697789f5264316c8a218e993f13a9a0f73f))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#449](https://github.com/zaebee/codegraph-brain/issues/449)) ([e9eccae](https://github.com/zaebee/codegraph-brain/commit/e9eccae8d43e8dc264ca87f8ea0a45752471f079))
+
 ## [0.19.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.18.0...codegraph-brain-v0.19.0) (2026-09-09)
 
 

{codegraph_brain-0.19.0 → codegraph_brain-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.19.0
+Version: 0.21.0
 Summary: Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP.
 Project-URL: Homepage, https://github.com/zaebee/codegraph-brain
 Project-URL: Repository, https://github.com/zaebee/codegraph-brain
@@ -202,31 +202,36 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_pipeline["pipeline.py"]
-        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:252)"]:::methodNode
-        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:192)"]:::methodNode
-        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:211)"]:::methodNode
-        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:157)"]:::methodNode
-        pipeline_IngestionPipeline_run["run (pipeline.py:53)"]:::methodNode
+        pipeline_IngestionPipeline_cross_file_inputs_changed["_cross_file_inputs_changed (pipeline.py:249)"]:::methodNode
+        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:384)"]:::methodNode
+        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:310)"]:::methodNode
+        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:334)"]:::methodNode
+        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:212)"]:::methodNode
+        pipeline_IngestionPipeline_run["run (pipeline.py:99)"]:::methodNode
+        pipeline_IngestionPipeline_workspace_root["workspace_root (pipeline.py:82)"]:::methodNode
     end
     subgraph sg_engine["engine.py"]
-        engine_ResolverEngine["ResolverEngine (engine.py:19)"]:::classNode
-        engine_ResolverEngine_resolve["resolve (engine.py:36)"]:::methodNode
+        engine_ResolverEngine["ResolverEngine (engine.py:20)"]:::classNode
+        engine_ResolverEngine_resolve["resolve (engine.py:37)"]:::methodNode
     end
     subgraph sg_uplift["uplift.py"]
         uplift_SemanticUpliftEngine["SemanticUpliftEngine (uplift.py:66)"]:::classNode
         uplift_SemanticUpliftEngine_execute_uplift["execute_uplift (uplift.py:91)"]:::methodNode
     end
     subgraph sg_sqlite_store["sqlite_store.py"]
-        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:40)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:42)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
     pipeline_IngestionPipeline_run -->|REFERENCES| sqlite_store_SQLiteStore
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_workspace_root
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_get_extractor
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_process_file
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_is_noop_incremental
     pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine
     pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine_resolve
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_cross_file_inputs_changed
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_run
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_persist_incremental
     pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine_execute_uplift
     pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine
@@ -236,16 +241,18 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 |--------|------|------|
 | `Node` | CLASS | [`models.py:85`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L85) |
 | `Edge` | CLASS | [`models.py:142`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L142) |
-| `run` | METHOD | [`pipeline.py:53`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L53) |
-| `_process_file` | METHOD | [`pipeline.py:157`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L157) |
-| `_is_noop_incremental` | METHOD | [`pipeline.py:192`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L192) |
-| `_persist_incremental` | METHOD | [`pipeline.py:211`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L211) |
-| `_get_extractor` | METHOD | [`pipeline.py:252`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L252) |
-| `ResolverEngine` | CLASS | [`engine.py:19`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L19) |
-| `resolve` | METHOD | [`engine.py:36`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L36) |
+| `workspace_root` | METHOD | [`pipeline.py:82`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L82) |
+| `run` | METHOD | [`pipeline.py:99`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L99) |
+| `_process_file` | METHOD | [`pipeline.py:212`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L212) |
+| `_cross_file_inputs_changed` | METHOD | [`pipeline.py:249`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L249) |
+| `_is_noop_incremental` | METHOD | [`pipeline.py:310`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L310) |
+| `_persist_incremental` | METHOD | [`pipeline.py:334`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L334) |
+| `_get_extractor` | METHOD | [`pipeline.py:384`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L384) |
+| `ResolverEngine` | CLASS | [`engine.py:20`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L20) |
+| `resolve` | METHOD | [`engine.py:37`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L37) |
 | `SemanticUpliftEngine` | CLASS | [`uplift.py:66`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L66) |
 | `execute_uplift` | METHOD | [`uplift.py:91`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L91) |
-| `SQLiteStore` | CLASS | [`sqlite_store.py:40`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L40) |
+| `SQLiteStore` | CLASS | [`sqlite_store.py:42`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L42) |
 <!-- END_CGIS_GRAPH -->
 
 ---

{codegraph_brain-0.19.0 → codegraph_brain-0.21.0}/README.md

@@ -152,31 +152,36 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_pipeline["pipeline.py"]
-        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:252)"]:::methodNode
-        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:192)"]:::methodNode
-        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:211)"]:::methodNode
-        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:157)"]:::methodNode
-        pipeline_IngestionPipeline_run["run (pipeline.py:53)"]:::methodNode
+        pipeline_IngestionPipeline_cross_file_inputs_changed["_cross_file_inputs_changed (pipeline.py:249)"]:::methodNode
+        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:384)"]:::methodNode
+        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:310)"]:::methodNode
+        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:334)"]:::methodNode
+        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:212)"]:::methodNode
+        pipeline_IngestionPipeline_run["run (pipeline.py:99)"]:::methodNode
+        pipeline_IngestionPipeline_workspace_root["workspace_root (pipeline.py:82)"]:::methodNode
     end
     subgraph sg_engine["engine.py"]
-        engine_ResolverEngine["ResolverEngine (engine.py:19)"]:::classNode
-        engine_ResolverEngine_resolve["resolve (engine.py:36)"]:::methodNode
+        engine_ResolverEngine["ResolverEngine (engine.py:20)"]:::classNode
+        engine_ResolverEngine_resolve["resolve (engine.py:37)"]:::methodNode
     end
     subgraph sg_uplift["uplift.py"]
         uplift_SemanticUpliftEngine["SemanticUpliftEngine (uplift.py:66)"]:::classNode
         uplift_SemanticUpliftEngine_execute_uplift["execute_uplift (uplift.py:91)"]:::methodNode
     end
     subgraph sg_sqlite_store["sqlite_store.py"]
-        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:40)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:42)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
     pipeline_IngestionPipeline_run -->|REFERENCES| sqlite_store_SQLiteStore
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_workspace_root
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_get_extractor
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_process_file
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_is_noop_incremental
     pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine
     pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine_resolve
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_cross_file_inputs_changed
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_run
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_persist_incremental
     pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine_execute_uplift
     pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine
@@ -186,16 +191,18 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 |--------|------|------|
 | `Node` | CLASS | [`models.py:85`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L85) |
 | `Edge` | CLASS | [`models.py:142`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L142) |
-| `run` | METHOD | [`pipeline.py:53`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L53) |
-| `_process_file` | METHOD | [`pipeline.py:157`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L157) |
-| `_is_noop_incremental` | METHOD | [`pipeline.py:192`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L192) |
-| `_persist_incremental` | METHOD | [`pipeline.py:211`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L211) |
-| `_get_extractor` | METHOD | [`pipeline.py:252`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L252) |
-| `ResolverEngine` | CLASS | [`engine.py:19`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L19) |
-| `resolve` | METHOD | [`engine.py:36`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L36) |
+| `workspace_root` | METHOD | [`pipeline.py:82`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L82) |
+| `run` | METHOD | [`pipeline.py:99`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L99) |
+| `_process_file` | METHOD | [`pipeline.py:212`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L212) |
+| `_cross_file_inputs_changed` | METHOD | [`pipeline.py:249`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L249) |
+| `_is_noop_incremental` | METHOD | [`pipeline.py:310`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L310) |
+| `_persist_incremental` | METHOD | [`pipeline.py:334`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L334) |
+| `_get_extractor` | METHOD | [`pipeline.py:384`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L384) |
+| `ResolverEngine` | CLASS | [`engine.py:20`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L20) |
+| `resolve` | METHOD | [`engine.py:37`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L37) |
 | `SemanticUpliftEngine` | CLASS | [`uplift.py:66`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L66) |
 | `execute_uplift` | METHOD | [`uplift.py:91`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L91) |
-| `SQLiteStore` | CLASS | [`sqlite_store.py:40`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L40) |
+| `SQLiteStore` | CLASS | [`sqlite_store.py:42`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L42) |
 <!-- END_CGIS_GRAPH -->
 
 ---

{codegraph_brain-0.19.0 → codegraph_brain-0.21.0}/docs/architecture/diagrams/pipeline_flow.mermaid

@@ -12,31 +12,36 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_pipeline["pipeline.py"]
-        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:252)"]:::methodNode
-        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:192)"]:::methodNode
-        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:211)"]:::methodNode
-        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:157)"]:::methodNode
-        pipeline_IngestionPipeline_run["run (pipeline.py:53)"]:::methodNode
+        pipeline_IngestionPipeline_cross_file_inputs_changed["_cross_file_inputs_changed (pipeline.py:249)"]:::methodNode
+        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:384)"]:::methodNode
+        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:310)"]:::methodNode
+        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:334)"]:::methodNode
+        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:212)"]:::methodNode
+        pipeline_IngestionPipeline_run["run (pipeline.py:99)"]:::methodNode
+        pipeline_IngestionPipeline_workspace_root["workspace_root (pipeline.py:82)"]:::methodNode
     end
     subgraph sg_engine["engine.py"]
-        engine_ResolverEngine["ResolverEngine (engine.py:19)"]:::classNode
-        engine_ResolverEngine_resolve["resolve (engine.py:36)"]:::methodNode
+        engine_ResolverEngine["ResolverEngine (engine.py:20)"]:::classNode
+        engine_ResolverEngine_resolve["resolve (engine.py:37)"]:::methodNode
     end
     subgraph sg_uplift["uplift.py"]
         uplift_SemanticUpliftEngine["SemanticUpliftEngine (uplift.py:66)"]:::classNode
         uplift_SemanticUpliftEngine_execute_uplift["execute_uplift (uplift.py:91)"]:::methodNode
     end
     subgraph sg_sqlite_store["sqlite_store.py"]
-        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:40)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:42)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
     pipeline_IngestionPipeline_run -->|REFERENCES| sqlite_store_SQLiteStore
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_workspace_root
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_get_extractor
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_process_file
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_is_noop_incremental
     pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine
     pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine_resolve
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_cross_file_inputs_changed
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_run
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_persist_incremental
     pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine_execute_uplift
     pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine

{codegraph_brain-0.19.0 → codegraph_brain-0.21.0}/docs/how-to/MCP_REFERENCE.md

@@ -10,9 +10,13 @@
 Analyse transitive upstream callers of a specific FQN.
 
     Answers "what breaks if I change X?". ``output_format="mermaid"`` (default)
-    returns a diagram; ``"json"`` returns a joinable ``{root, nodes, edges}``
-    payload with real FQNs — letting an agent compute set differences (e.g.
-    "which route handlers never reach ``verify_ownership``?") directly.
+    returns a diagram; ``"json"`` returns a joinable ``{root, nodes, edges,
+    coverage}`` payload with real FQNs — letting an agent compute set
+    differences (e.g. "which route handlers never reach ``verify_ownership``?")
+    directly. ``coverage`` counts unresolved calls whose name matches a
+    traversed function, method or class: callers that may be missing, named in
+    ``top_unresolved``. It is an upper bound — a common name matches calls on
+    unrelated objects, which the names make visible.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
@@ -233,9 +237,11 @@ Scan a local directory, extract all symbols, resolve links, and build the graph
 
     By default the ingest is **incremental**: only changed/new files are
     re-scanned, and the summary reports both what changed this run and the
-    whole-graph total. Set ``full_rebuild=True`` to re-scan every file and
-    overwrite the database from scratch — use this to drop nodes for files that
-    were deleted or renamed, which an incremental run leaves behind.
+    whole-graph total. When a change alters what other files resolve against — a
+    renamed, removed or added symbol, a deleted or new file, a changed base class
+    or re-export — the incremental run rebuilds the whole graph itself, so edges
+    in unchanged files never point at symbols that no longer exist. Set
+    ``full_rebuild=True`` to force a re-scan of every file from scratch.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
@@ -325,8 +331,12 @@ Suggest sub-package boundaries for a package from its dependency communities.
 Trace the execution call-graph starting from a specific FQN downwards.
 
     ``output_format="mermaid"`` (default) returns a human-readable diagram;
-    ``"json"`` returns a joinable ``{root, nodes, edges}`` payload with real
-    FQNs (not display hashes) for agent/CI use. Use ``cgis_ingest`` first if
+    ``"json"`` returns a joinable ``{root, nodes, edges, coverage}`` payload
+    with real FQNs (not display hashes) for agent/CI use. ``coverage`` counts
+    the calls the traversed functions make that resolved to nothing, and
+    ``top_unresolved`` names the most frequent. Read the names, not only the
+    ratio: in Python most are methods on untyped locals (``logger.info``,
+    ``items.append``), which cut nothing short. Use ``cgis_ingest`` first if
     the database does not exist yet.
 
 | Argument | Type | Required | Description |

{codegraph_brain-0.19.0 → codegraph_brain-0.21.0}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.19.0"
+version = "0.21.0"
 description = "Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP."
 readme = "README.md"
 requires-python = ">=3.12"

{codegraph_brain-0.19.0 → codegraph_brain-0.21.0}/src/cgis/api/mcp_server.py

@@ -13,6 +13,7 @@ from typing import Any
 import structlog
 from mcp.server.mcpserver import MCPServer
 
+from cgis.core.coverage import TraversalCoverage
 from cgis.core.freshness import Freshness, FreshnessState
 from cgis.core.models import Edge, Node, NodeType
 from cgis.extractors.python_extractor import PythonExtractor
@@ -64,6 +65,11 @@ def _blank_fqn_error(fqn: str) -> str | None:
     return None
 
 
+def _wants_json(output_format: str) -> bool:
+    """True when a traversal will be rendered as JSON — the only shape that carries coverage."""
+    return output_format.strip().lower() == "json"
+
+
 def _render_subgraph_with_freshness(
     db_path: str,
     output_format: str,
@@ -72,10 +78,11 @@ def _render_subgraph_with_freshness(
     title: str,
     nodes: list[Node],
     edges: list[Edge],
+    coverage: TraversalCoverage | None = None,
 ) -> str:
     """`_render_subgraph`, with this database's freshness measured for it (#175)."""
     return _render_subgraph(
-        output_format, root, note, title, nodes, edges, _graph_freshness(db_path)
+        output_format, root, note, title, nodes, edges, _graph_freshness(db_path), coverage
     )
 
 
@@ -87,6 +94,7 @@ def _render_subgraph(
     nodes: list[Node],
     edges: list[Edge],
     freshness: "Freshness | None" = None,
+    coverage: TraversalCoverage | None = None,
 ) -> str:
     """Render a traversal result as a Mermaid diagram or joinable JSON (#171).
 
@@ -98,11 +106,12 @@ def _render_subgraph(
     ``freshness`` is placed differently in each: a key inside the JSON object,
     a prose note above the diagram. Prefixing the JSON would make it unparseable
     exactly when the graph goes stale, and this renderer is the only place that
-    knows which shape it is about to produce (#175).
+    knows which shape it is about to produce (#175). ``coverage`` (#201) rides
+    in the JSON only.
     """
     fmt = output_format.strip().lower()
     if fmt == "json":
-        payload = graph_to_json(root, nodes, edges)
+        payload = graph_to_json(root, nodes, edges, coverage)
         if freshness is not None and freshness.state is not FreshnessState.FRESH:
             payload = {**payload, "freshness": freshness.model_dump()}
         return json.dumps(payload, indent=2)
@@ -251,9 +260,11 @@ def cgis_ingest(project_path: str, db_path: str = _DEFAULT_DB, full_rebuild: boo
 
     By default the ingest is **incremental**: only changed/new files are
     re-scanned, and the summary reports both what changed this run and the
-    whole-graph total. Set ``full_rebuild=True`` to re-scan every file and
-    overwrite the database from scratch — use this to drop nodes for files that
-    were deleted or renamed, which an incremental run leaves behind.
+    whole-graph total. When a change alters what other files resolve against — a
+    renamed, removed or added symbol, a deleted or new file, a changed base class
+    or re-export — the incremental run rebuilds the whole graph itself, so edges
+    in unchanged files never point at symbols that no longer exist. Set
+    ``full_rebuild=True`` to force a re-scan of every file from scratch.
     """
     refusal = _reject_db_path(db_path)
     if refusal is not None:
@@ -263,13 +274,12 @@ def cgis_ingest(project_path: str, db_path: str = _DEFAULT_DB, full_rebuild: boo
     pipeline = IngestionPipeline(_EXTRACTORS)
     try:
         with SQLiteStore(db_path) as store:
-            if full_rebuild:
-                # Clear first, then run incrementally over an empty DB: this drops
-                # deleted-file nodes, repopulates files_state correctly, and runs
-                # uplift inside the pipeline (store provided) — all in one path.
-                store.clear()
-            _nodes, _raw, resolved = pipeline.run(project_path, store=store)
-            store.record_ingest(project_path)
+            # A rebuild replaces the stored graph in the transaction that writes the
+            # new one: deleted-file nodes and stale hashes go, uplift runs inside
+            # the pipeline, and a failure part-way leaves the old graph intact.
+            nodes, _raw, resolved = pipeline.run(project_path, store=store, rebuild=full_rebuild)
+            if nodes:
+                store.record_ingest(project_path)
             total_nodes = store.get_node_count()
             total_edges = store.get_edge_count()
     except Exception as exc:
@@ -283,8 +293,14 @@ def cgis_ingest(project_path: str, db_path: str = _DEFAULT_DB, full_rebuild: boo
         total_edges=total_edges,
         db=db_path,
     )
-    lines = [f"✅ Ingested: {project_path} (mode: {mode})"]
-    if not full_rebuild and not resolved:
+    if not nodes:
+        # Nothing extracted: a rebuild kept the stored graph, and neither mode
+        # records this path as the graph's fresh root.
+        kept = "the stored graph was kept" if full_rebuild else "the graph now holds none"
+        lines = [f"⚠️ No source files extracted from {project_path} (mode: {mode}); {kept}."]
+    else:
+        lines = [f"✅ Ingested: {project_path} (mode: {mode})"]
+    if nodes and not full_rebuild and not resolved:
         # Incremental no-op: an empty resolved set means no files changed. Say so
         # explicitly so the stable total below doesn't read as a shrunken graph (#192).
         lines.append("No files changed since the last ingest.")
@@ -300,8 +316,12 @@ def cgis_trace_flow(
     """Trace the execution call-graph starting from a specific FQN downwards.
 
     ``output_format="mermaid"`` (default) returns a human-readable diagram;
-    ``"json"`` returns a joinable ``{root, nodes, edges}`` payload with real
-    FQNs (not display hashes) for agent/CI use. Use ``cgis_ingest`` first if
+    ``"json"`` returns a joinable ``{root, nodes, edges, coverage}`` payload
+    with real FQNs (not display hashes) for agent/CI use. ``coverage`` counts
+    the calls the traversed functions make that resolved to nothing, and
+    ``top_unresolved`` names the most frequent. Read the names, not only the
+    ratio: in Python most are methods on untyped locals (``logger.info``,
+    ``items.append``), which cut nothing short. Use ``cgis_ingest`` first if
     the database does not exist yet.
     """
     if blank := _blank_fqn_error(fqn):
@@ -313,13 +333,22 @@ def cgis_trace_flow(
             res = resolve_fqn(store, fqn)
             if res.resolved is None:
                 return _resolution_error(fqn, res.candidates, res.truncated)
-            nodes, edges = QueryEngine(store).get_flow_graph(res.resolved, max_depth=depth)
+            result = QueryEngine(store).get_flow_result(
+                res.resolved, max_depth=depth, with_coverage=_wants_json(output_format)
+            )
     except Exception as exc:
         return f"❌ {exc}"
 
     note = f"> Resolved '{fqn}' → '{res.resolved}'\n\n" if res.via_suffix else ""
     return _render_subgraph_with_freshness(
-        db_path, output_format, res.resolved, note, "Execution flow for", nodes, edges
+        db_path,
+        output_format,
+        res.resolved,
+        note,
+        "Execution flow for",
+        result.nodes,
+        result.edges,
+        result.coverage,
     )
 
 
@@ -330,9 +359,13 @@ def cgis_analyze_impact(
     """Analyse transitive upstream callers of a specific FQN.
 
     Answers "what breaks if I change X?". ``output_format="mermaid"`` (default)
-    returns a diagram; ``"json"`` returns a joinable ``{root, nodes, edges}``
-    payload with real FQNs — letting an agent compute set differences (e.g.
-    "which route handlers never reach ``verify_ownership``?") directly.
+    returns a diagram; ``"json"`` returns a joinable ``{root, nodes, edges,
+    coverage}`` payload with real FQNs — letting an agent compute set
+    differences (e.g. "which route handlers never reach ``verify_ownership``?")
+    directly. ``coverage`` counts unresolved calls whose name matches a
+    traversed function, method or class: callers that may be missing, named in
+    ``top_unresolved``. It is an upper bound — a common name matches calls on
+    unrelated objects, which the names make visible.
     """
     if blank := _blank_fqn_error(fqn):
         return blank
@@ -343,13 +376,22 @@ def cgis_analyze_impact(
             res = resolve_fqn(store, fqn)
             if res.resolved is None:
                 return _resolution_error(fqn, res.candidates, res.truncated)
-            nodes, edges = QueryEngine(store).get_impact_graph(res.resolved, max_depth=depth)
+            result = QueryEngine(store).get_impact_result(
+                res.resolved, max_depth=depth, with_coverage=_wants_json(output_format)
+            )
     except Exception as exc:
         return f"❌ {exc}"
 
     note = f"> Resolved '{fqn}' → '{res.resolved}'\n\n" if res.via_suffix else ""
     return _render_subgraph_with_freshness(
-        db_path, output_format, res.resolved, note, "Impact analysis for", nodes, edges
+        db_path,
+        output_format,
+        res.resolved,
+        note,
+        "Impact analysis for",
+        result.nodes,
+        result.edges,
+        result.coverage,
     )