codegraph-brain 0.16.0__tar.gz → 0.18.0__tar.gz

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

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

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

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

{codegraph_brain-0.16.0 → codegraph_brain-0.18.0}/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* **extractors:** record what annotations say — self_types and REFERENCES edges ([#414](https://github.com/zaebee/codegraph-brain/issues/414), [#415](https://github.com/zaebee/codegraph-brain/issues/415)) ([#418](https://github.com/zaebee/codegraph-brain/issues/418)) ([eeaa60b](https://github.com/zaebee/codegraph-brain/commit/eeaa60b831956bb85fff88c987789ea179c2dc71))
+
+
+### Bug Fixes
+
+* **render:** draw one arrow per distinct triple in a mermaid diagram ([#421](https://github.com/zaebee/codegraph-brain/issues/421)) ([19a6067](https://github.com/zaebee/codegraph-brain/commit/19a6067f7c98d84f9d0a3e02e132f85ba0791817))
+
+
+### Documentation
+
+* auto-sync architecture graph after the annotation-edge work ([#420](https://github.com/zaebee/codegraph-brain/issues/420)) ([061843d](https://github.com/zaebee/codegraph-brain/commit/061843dd0ba997d2fd7549acaa72e7290b10f9cf))
+
 ## [0.16.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.15.0...codegraph-brain-v0.16.0) (2026-08-17)
 
 

{codegraph_brain-0.16.0 → codegraph_brain-0.18.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.16.0 → codegraph_brain-0.18.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.16.0 → codegraph_brain-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.16.0
+Version: 0.18.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
@@ -197,6 +197,10 @@ classDef defaultNode fill:#fafafa,stroke:#9e9e9e,stroke-width:1.5px,color:#21212
 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:138)"]:::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
@@ -205,13 +209,19 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         pipeline_IngestionPipeline_run["run (pipeline.py:51)"]:::methodNode
     end
     subgraph sg_engine["engine.py"]
-        engine_ResolverEngine["ResolverEngine (engine.py:18)"]:::classNode
-        engine_ResolverEngine_resolve["resolve (engine.py:35)"]:::methodNode
+        engine_ResolverEngine["ResolverEngine (engine.py:19)"]:::classNode
+        engine_ResolverEngine_resolve["resolve (engine.py:36)"]:::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:30)"]:::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_get_extractor
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_process_file
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_is_noop_incremental
@@ -224,15 +234,18 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 
 | Symbol | Type | File |
 |--------|------|------|
+| `Node` | CLASS | [`models.py:85`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L85) |
+| `Edge` | CLASS | [`models.py:138`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L138) |
 | `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) |
-| `ResolverEngine` | CLASS | [`engine.py:18`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L18) |
-| `resolve` | METHOD | [`engine.py:35`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L35) |
+| `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:30`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L30) |
 <!-- END_CGIS_GRAPH -->
 
 ---

{codegraph_brain-0.16.0 → codegraph_brain-0.18.0}/README.md

@@ -147,6 +147,10 @@ classDef defaultNode fill:#fafafa,stroke:#9e9e9e,stroke-width:1.5px,color:#21212
 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:138)"]:::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
@@ -155,13 +159,19 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         pipeline_IngestionPipeline_run["run (pipeline.py:51)"]:::methodNode
     end
     subgraph sg_engine["engine.py"]
-        engine_ResolverEngine["ResolverEngine (engine.py:18)"]:::classNode
-        engine_ResolverEngine_resolve["resolve (engine.py:35)"]:::methodNode
+        engine_ResolverEngine["ResolverEngine (engine.py:19)"]:::classNode
+        engine_ResolverEngine_resolve["resolve (engine.py:36)"]:::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:30)"]:::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_get_extractor
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_process_file
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_is_noop_incremental
@@ -174,15 +184,18 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 
 | Symbol | Type | File |
 |--------|------|------|
+| `Node` | CLASS | [`models.py:85`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L85) |
+| `Edge` | CLASS | [`models.py:138`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L138) |
 | `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) |
-| `ResolverEngine` | CLASS | [`engine.py:18`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L18) |
-| `resolve` | METHOD | [`engine.py:35`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L35) |
+| `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:30`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L30) |
 <!-- END_CGIS_GRAPH -->
 
 ---

{codegraph_brain-0.16.0 → codegraph_brain-0.18.0}/docs/architecture/HOW_IT_WORKS.md

@@ -85,7 +85,8 @@ 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
         );
 
         CREATE TABLE IF NOT EXISTS edges (

{codegraph_brain-0.16.0 → codegraph_brain-0.18.0}/docs/architecture/diagrams/pipeline_flow.mermaid

@@ -7,6 +7,10 @@ classDef defaultNode fill:#fafafa,stroke:#9e9e9e,stroke-width:1.5px,color:#21212
 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:138)"]:::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
@@ -15,13 +19,19 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         pipeline_IngestionPipeline_run["run (pipeline.py:51)"]:::methodNode
     end
     subgraph sg_engine["engine.py"]
-        engine_ResolverEngine["ResolverEngine (engine.py:18)"]:::classNode
-        engine_ResolverEngine_resolve["resolve (engine.py:35)"]:::methodNode
+        engine_ResolverEngine["ResolverEngine (engine.py:19)"]:::classNode
+        engine_ResolverEngine_resolve["resolve (engine.py:36)"]:::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:30)"]:::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_get_extractor
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_process_file
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_is_noop_incremental

{codegraph_brain-0.16.0 → codegraph_brain-0.18.0}/docs/how-to/MCP_REFERENCE.md

@@ -106,6 +106,41 @@ 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".
+
+    Returns JSON ``{orphans, considered, test_sources}``; 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.
+
+| Argument | Type | Required | Description |
+| :--- | :--- | :---: | :--- |
+| `db_path` | `string` |  |  |
+| `prefix` | `any` |  |  |
+| `include_tests` | `boolean` |  |  |
+
+---
+
 ## `cgis_find_symbol`
 
 Resolve a partial symbol name to candidate FQNs (substring match, ranked).