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

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

@@ -0,0 +1 @@
+2264

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

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

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

@@ -1,5 +1,48 @@
 # Changelog
 
+## [0.19.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.18.0...codegraph-brain-v0.19.0) (2026-09-09)
+
+
+### Features
+
+* **freshness:** every query says when the graph is out of date ([#175](https://github.com/zaebee/codegraph-brain/issues/175) part 2) ([#443](https://github.com/zaebee/codegraph-brain/issues/443)) ([0d6d197](https://github.com/zaebee/codegraph-brain/commit/0d6d197133c1315698b10a223aaf8efb47784578))
+* **metrics:** --scope <prefix> to focus rankings on one subtree ([#239](https://github.com/zaebee/codegraph-brain/issues/239)) ([#439](https://github.com/zaebee/codegraph-brain/issues/439)) ([59605d3](https://github.com/zaebee/codegraph-brain/commit/59605d361f95aeea18b8272183f20938c0ca10b8))
+* **orphans:** generated classes are noise, not findings — hide them by default ([#432](https://github.com/zaebee/codegraph-brain/issues/432)) ([#441](https://github.com/zaebee/codegraph-brain/issues/441)) ([52e0de1](https://github.com/zaebee/codegraph-brain/commit/52e0de1e666612f72d5a58eaad9509252db098e2))
+
+
+### Bug Fixes
+
+* **extractor:** `with X() as y` records y's type ([#444](https://github.com/zaebee/codegraph-brain/issues/444)) ([#445](https://github.com/zaebee/codegraph-brain/issues/445)) ([529b2e2](https://github.com/zaebee/codegraph-brain/commit/529b2e2239ab62a14211d95291afb1d7a6666cfc))
+* **resolver:** only a head-discarding strip is forbidden a foreign head ([#435](https://github.com/zaebee/codegraph-brain/issues/435)) ([#437](https://github.com/zaebee/codegraph-brain/issues/437)) ([3e5309a](https://github.com/zaebee/codegraph-brain/commit/3e5309ac6e65cfdc5174dc70c6ae9d4b5036d92a))
+* **suggest-packages:** name a member by its path under the package ([#446](https://github.com/zaebee/codegraph-brain/issues/446)) ([#447](https://github.com/zaebee/codegraph-brain/issues/447)) ([08af353](https://github.com/zaebee/codegraph-brain/commit/08af353f88b0026f799eb2cb2f9ed5f0c9733d22))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#442](https://github.com/zaebee/codegraph-brain/issues/442)) ([47a6aab](https://github.com/zaebee/codegraph-brain/commit/47a6aab38225f8e8936abd9d9e72b9449f10afe2))
+
+## [0.18.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.17.0...codegraph-brain-v0.18.0) (2026-09-06)
+
+
+### Features
+
+* **extractors:** a class named as a value is a reference (D10, [#415](https://github.com/zaebee/codegraph-brain/issues/415)) ([#430](https://github.com/zaebee/codegraph-brain/issues/430)) ([aea4076](https://github.com/zaebee/codegraph-brain/commit/aea4076b45d0761f50bb989936e89c8054402372))
+* **extractors:** a decorator's arguments are edges, and a decorated class keeps its own ([#429](https://github.com/zaebee/codegraph-brain/issues/429)) ([#434](https://github.com/zaebee/codegraph-brain/issues/434)) ([fd0c63f](https://github.com/zaebee/codegraph-brain/commit/fd0c63f1f887a0b65a433d01571654ae79419ef3))
+* **query:** orphan classes — what production no longer builds ([#415](https://github.com/zaebee/codegraph-brain/issues/415)) ([#431](https://github.com/zaebee/codegraph-brain/issues/431)) ([3b4db3c](https://github.com/zaebee/codegraph-brain/commit/3b4db3cb231d43ae388b080d64d19b3244739017))
+* **resolver:** resolve self.<attr>.<method> through the declared receiver ([#414](https://github.com/zaebee/codegraph-brain/issues/414)) ([#423](https://github.com/zaebee/codegraph-brain/issues/423)) ([a1c94a2](https://github.com/zaebee/codegraph-brain/commit/a1c94a2e4629da955deef761467730a7d711c3fe))
+
+
+### Bug Fixes
+
+* **extractors:** attribute a module-level or class-body call to its owner ([#416](https://github.com/zaebee/codegraph-brain/issues/416)) ([#428](https://github.com/zaebee/codegraph-brain/issues/428)) ([c9f39b8](https://github.com/zaebee/codegraph-brain/commit/c9f39b81bf3a644441b7b5a3215df2d6b39b9489))
+* **resolver:** an import prefix that reaches a node is first-party, not external ([#424](https://github.com/zaebee/codegraph-brain/issues/424)) ([#426](https://github.com/zaebee/codegraph-brain/issues/426)) ([50f8b7c](https://github.com/zaebee/codegraph-brain/commit/50f8b7c03d716c25f9341a879c76a8707f3853fb))
+* **resolver:** resolve a name through the package that re-exports it ([#417](https://github.com/zaebee/codegraph-brain/issues/417)) ([#427](https://github.com/zaebee/codegraph-brain/issues/427)) ([ef76f95](https://github.com/zaebee/codegraph-brain/commit/ef76f9546b4477d4736406eabe417e6e49e68e23))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#433](https://github.com/zaebee/codegraph-brain/issues/433)) ([40af3ee](https://github.com/zaebee/codegraph-brain/commit/40af3ee6839b53a953124e25f1f39b5379bff890))
+
 ## [0.17.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.16.0...codegraph-brain-v0.17.0) (2026-09-05)
 
 

{codegraph_brain-0.17.0 → codegraph_brain-0.19.0}/CLAUDE.md

@@ -35,8 +35,9 @@ make format && make lint && make type-check && make pytest && make doc-coverage
 # Single test
 uv run pytest tests/unit/test_python_extractor.py::test_extract_simple_function -v
 
-# Tests with coverage
-uv run pytest --cov=cgis --cov-report=html
+# Line coverage (same scope as CI — see the Makefile comment on why scripts/ counts)
+make coverage        # runs: uv run pytest --cov=cgis --cov=scripts --cov-report=term-missing
+make coverage-html   # same, writes htmlcov/
 ```
 
 ## Architecture

{codegraph_brain-0.17.0 → codegraph_brain-0.19.0}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: format lint type-check pytest doc-coverage check \
+.PHONY: format lint type-check pytest doc-coverage coverage coverage-html check \
         ui-dev ui-build ui-test ui-lint ui-format ui-preview ui-analyze ui-check \
         all-checks
 
@@ -19,6 +19,20 @@ pytest:
 doc-coverage:
 	uv run interrogate src
 
+# Line coverage. `--cov=scripts` is not optional and not cosmetic: sonar.sources
+# is `src,scripts`, so SonarCloud counts every executable line under scripts/ as
+# a line to cover whether or not the report mentions it. Omitting the directory
+# does not exclude it — it reports all of it as uncovered, which once put
+# new-code coverage at 37.8% on a PR whose script was covered at 99% locally.
+# Keep this scope identical to the Pytest step in .github/workflows/ci.yml, or
+# the number you read here is not the number the gate reads.
+coverage:
+	uv run pytest --cov=cgis --cov=scripts --cov-report=term-missing
+
+# Same scope, browsable. Writes htmlcov/ (git-ignored); open htmlcov/index.html.
+coverage-html:
+	uv run pytest --cov=cgis --cov=scripts --cov-report=html
+
 # Full Python verification (run before every commit/PR)
 check: format lint type-check pytest doc-coverage
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.17.0
+Version: 0.19.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
@@ -198,15 +198,15 @@ classDef stdlibNode fill:#eceff1,stroke:#607d8b,stroke-width:1px,color:#455a64;
 classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dasharray: 3 3,color:#bf360c;
 
     subgraph sg_models["models.py"]
-        models_Edge["Edge (models.py:117)"]:::classNode
-        models_Node["Node (models.py:83)"]:::classNode
+        models_Edge["Edge (models.py:142)"]:::classNode
+        models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_pipeline["pipeline.py"]
-        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:245)"]:::methodNode
-        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:185)"]:::methodNode
-        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:204)"]:::methodNode
-        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:155)"]:::methodNode
-        pipeline_IngestionPipeline_run["run (pipeline.py:51)"]:::methodNode
+        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
     end
     subgraph sg_engine["engine.py"]
         engine_ResolverEngine["ResolverEngine (engine.py:19)"]:::classNode
@@ -217,7 +217,7 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         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:28)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:40)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
@@ -234,18 +234,18 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 
 | Symbol | Type | File |
 |--------|------|------|
-| `Node` | CLASS | [`models.py:83`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L83) |
-| `Edge` | CLASS | [`models.py:117`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L117) |
-| `run` | METHOD | [`pipeline.py:51`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L51) |
-| `_process_file` | METHOD | [`pipeline.py:155`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L155) |
-| `_is_noop_incremental` | METHOD | [`pipeline.py:185`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L185) |
-| `_persist_incremental` | METHOD | [`pipeline.py:204`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L204) |
-| `_get_extractor` | METHOD | [`pipeline.py:245`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L245) |
+| `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) |
 | `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:28`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L28) |
+| `SQLiteStore` | CLASS | [`sqlite_store.py:40`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L40) |
 <!-- END_CGIS_GRAPH -->
 
 ---

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

@@ -148,15 +148,15 @@ classDef stdlibNode fill:#eceff1,stroke:#607d8b,stroke-width:1px,color:#455a64;
 classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dasharray: 3 3,color:#bf360c;
 
     subgraph sg_models["models.py"]
-        models_Edge["Edge (models.py:117)"]:::classNode
-        models_Node["Node (models.py:83)"]:::classNode
+        models_Edge["Edge (models.py:142)"]:::classNode
+        models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_pipeline["pipeline.py"]
-        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:245)"]:::methodNode
-        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:185)"]:::methodNode
-        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:204)"]:::methodNode
-        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:155)"]:::methodNode
-        pipeline_IngestionPipeline_run["run (pipeline.py:51)"]:::methodNode
+        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
     end
     subgraph sg_engine["engine.py"]
         engine_ResolverEngine["ResolverEngine (engine.py:19)"]:::classNode
@@ -167,7 +167,7 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         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:28)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:40)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
@@ -184,18 +184,18 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 
 | Symbol | Type | File |
 |--------|------|------|
-| `Node` | CLASS | [`models.py:83`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L83) |
-| `Edge` | CLASS | [`models.py:117`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L117) |
-| `run` | METHOD | [`pipeline.py:51`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L51) |
-| `_process_file` | METHOD | [`pipeline.py:155`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L155) |
-| `_is_noop_incremental` | METHOD | [`pipeline.py:185`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L185) |
-| `_persist_incremental` | METHOD | [`pipeline.py:204`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L204) |
-| `_get_extractor` | METHOD | [`pipeline.py:245`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L245) |
+| `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) |
 | `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:28`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L28) |
+| `SQLiteStore` | CLASS | [`sqlite_store.py:40`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L40) |
 <!-- END_CGIS_GRAPH -->
 
 ---

{codegraph_brain-0.17.0 → codegraph_brain-0.19.0}/docs/architecture/HOW_IT_WORKS.md

@@ -85,7 +85,9 @@ CREATE TABLE IF NOT EXISTS nodes (
             domains TEXT,
             confidence_score REAL NOT NULL,
             metadata TEXT,
-            namespace TEXT NOT NULL DEFAULT 'INTERNAL'
+            namespace TEXT NOT NULL DEFAULT 'INTERNAL',
+            is_test INTEGER NOT NULL DEFAULT 0,
+            is_generated INTEGER NOT NULL DEFAULT 0
         );
 
         CREATE TABLE IF NOT EXISTS edges (
@@ -105,6 +107,11 @@ CREATE TABLE IF NOT EXISTS nodes (
             hash TEXT NOT NULL
         );
 
+        CREATE TABLE IF NOT EXISTS ingest_state (
+            key   TEXT PRIMARY KEY,
+            value TEXT NOT NULL
+        );
+
         CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type);
         CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source);
         CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target);

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

@@ -8,15 +8,15 @@ classDef stdlibNode fill:#eceff1,stroke:#607d8b,stroke-width:1px,color:#455a64;
 classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dasharray: 3 3,color:#bf360c;
 
     subgraph sg_models["models.py"]
-        models_Edge["Edge (models.py:117)"]:::classNode
-        models_Node["Node (models.py:83)"]:::classNode
+        models_Edge["Edge (models.py:142)"]:::classNode
+        models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_pipeline["pipeline.py"]
-        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:245)"]:::methodNode
-        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:185)"]:::methodNode
-        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:204)"]:::methodNode
-        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:155)"]:::methodNode
-        pipeline_IngestionPipeline_run["run (pipeline.py:51)"]:::methodNode
+        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
     end
     subgraph sg_engine["engine.py"]
         engine_ResolverEngine["ResolverEngine (engine.py:19)"]:::classNode
@@ -27,7 +27,7 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         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:28)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:40)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge

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

@@ -106,6 +106,53 @@ Report per-domain architectural drift against declared ideal patterns.
 
 ---
 
+## `cgis_find_orphans`
+
+Classes nothing in production builds, extends or names — dead-code candidates (#415).
+
+    Finds classes that no test, type checker or linter flags, because each is
+    still imported somewhere: a package re-export keeps a class importable long
+    after its last real caller is gone. On one mid-sized backend this reported
+    43 of 1 789 classes, and the hand-written equivalent's findings were all
+    real and all deleted.
+
+    Two filters decide the answer. **Tests are not users** — a class built only
+    by its own test is exactly the shape being hunted. **A re-export is not a
+    use** — ``IMPORTS_SYMBOL`` does not count, or nothing is ever reported. What
+    counts is construction (``CALLS``), inheritance (``EXTENDS``) and being named
+    (``REFERENCES`` — an annotation, or a class handed to a framework); the last
+    keeps abstract ports and Protocols off the list.
+
+    ``prefix`` narrows to one package on a dot boundary. ``include_tests`` counts
+    test code as a user, turning the report into "unreachable from anywhere".
+
+    Machine-generated classes are **hidden by default**, and ``include_generated``
+    puts them back. The query is right about them — nothing constructs a
+    betterproto stub — but nobody hand-deletes one either, so they are noise
+    rather than a finding. Measured on owner-api at b7d02fe6, five of six
+    reported orphans were generated entities and the sixth a nested pydantic
+    ``Config``: the unfiltered report had no actionable row in it (#432).
+
+    Returns JSON ``{orphans, considered, test_sources, generated_excluded}``;
+    each orphan carries ``fqn``/``file``/``line``. **A listing is a candidate for
+    deletion, not a proof** — a class named only inside a decorator (#429) or
+    arriving through a star import is invisible here, so the sweep errs towards
+    reporting a live class rather than hiding a dead one. ``test_sources: 0`` in a
+    repository that has tests means the graph predates the ``is_test`` column:
+    re-ingest. ``generated_excluded`` counts every generated class left out of
+    the population under the same ``prefix``, referenced or not — so ``0`` on a
+    repository with generated code means the same for ``is_generated``, which has
+    no backfill: the marker is in the file header, not in the database.
+
+| Argument | Type | Required | Description |
+| :--- | :--- | :---: | :--- |
+| `db_path` | `string` |  |  |
+| `prefix` | `any` |  |  |
+| `include_tests` | `boolean` |  |  |
+| `include_generated` | `boolean` |  |  |
+
+---
+
 ## `cgis_find_symbol`
 
 Resolve a partial symbol name to candidate FQNs (substring match, ranked).
@@ -232,11 +279,22 @@ Whole-graph architectural metrics — coupling bottlenecks + God classes (#16).
     (e.g. ``["tests"]`` removes both ``tests.*`` and ``domains.*.tests.*``) so
     test/vendor scaffolding stays out of the rankings.
 
+    ``scope`` is its complement: it keeps only nodes under one of the given
+    dot-prefixes, anchored and cut on a dot boundary, so
+    ``["domains.reservation"]`` is that subtree and not
+    ``domains.reservation_archive``. Use it for a per-domain review. The two
+    compose, and they differ where it matters for PageRank — ``exclude`` removes
+    nodes from the propagation graph, ``scope`` filters the rows and lets rank
+    propagate over the whole graph, so a scoped run reports how central the
+    subtree is *globally*. Coupling in-degree likewise keeps counting callers
+    from outside the scope, which is the ripple a domain review is after (#239).
+
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
 | `db_path` | `string` |  |  |
 | `limit` | `integer` |  |  |
 | `exclude` | `any` |  |  |
+| `scope` | `any` |  |  |
 
 ---