codegraph-brain 0.8.0__tar.gz → 0.9.0__tar.gz

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

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

{codegraph_brain-0.8.0 → codegraph_brain-0.9.0}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.9.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.8.0...codegraph-brain-v0.9.0) (2026-08-01)
+
+
+### Features
+
+* **drift:** look through transparent re-exports in the IMPORTS census ([#329](https://github.com/zaebee/codegraph-brain/issues/329)) ([25b2ce6](https://github.com/zaebee/codegraph-brain/commit/25b2ce6049ae878ebeef05cd47b08dd67faa763d))
+* **extractor:** detect transparent re-exports ([#182](https://github.com/zaebee/codegraph-brain/issues/182) direction 1, slice 1) ([#327](https://github.com/zaebee/codegraph-brain/issues/327)) ([6e6e654](https://github.com/zaebee/codegraph-brain/commit/6e6e654b4ce17c52487507d2d425a4f81045f731))
+
 ## [0.8.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.7.5...codegraph-brain-v0.8.0) (2026-08-01)
 
 

{codegraph_brain-0.8.0 → codegraph_brain-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-brain
-Version: 0.8.0
+Version: 0.9.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

{codegraph_brain-0.8.0 → codegraph_brain-0.9.0}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.8.0"
+version = "0.9.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.8.0 → codegraph_brain-0.9.0}/src/cgis/extractors/python_extractor.py

@@ -1,5 +1,7 @@
 """Implements Python Extractor."""
 
+import re
+
 import tree_sitter_python as tspython
 from tree_sitter import Language, Parser
 from tree_sitter import Node as BaseNode
@@ -29,6 +31,61 @@ def file_path_to_module_fqn(file_path: str, source_root: str | None = None) -> s
     return _file_path_to_module_fqn(file_path, source_root)
 
 
+def _identifiers_outside_imports(root: BaseNode, code_bytes: bytes) -> set[str]:
+    """Every identifier used in the module body, excluding import statements.
+
+    The walker already refuses to recurse into import nodes, so the same rule is
+    applied here: a name that appears *only* in an import is never used by this
+    module.
+    """
+    used: set[str] = set()
+    stack = [root]
+    while stack:
+        node = stack.pop()
+        if node.type in ("import_statement", "import_from_statement"):
+            continue
+        if node.type == "identifier":
+            # `o.thing` and `f(thing=1)` mention `thing` without using the imported
+            # name — counting them would let an unrelated attribute or keyword
+            # silence a real re-export of that name. Only the `attribute`/`name`
+            # field is excluded; the object side of `o.thing` is a genuine use.
+            parent = node.parent
+            shadowed = parent is not None and (
+                (parent.type == "attribute" and parent.child_by_field_name("attribute") == node)
+                or (
+                    parent.type == "keyword_argument" and parent.child_by_field_name("name") == node
+                )
+            )
+            if not shadowed:
+                used.add(code_bytes[node.start_byte : node.end_byte].decode("utf8"))
+        elif node.type == "string" and node.parent is not None and node.parent.type == "type":
+            # A forward-reference annotation — `store: "SQLiteStore | None"` — holds
+            # no identifier nodes, so without this a TYPE_CHECKING import used only
+            # in quoted annotations reads as unused. Restricted to annotation
+            # strings (parent `type`): scanning every string would let a docstring
+            # mentioning a name mask a real re-export.
+            text = code_bytes[node.start_byte : node.end_byte].decode("utf8")
+            used.update(re.findall(r"[A-Za-z_][A-Za-z0-9_]*", text))
+        stack.extend(node.children)
+    return used
+
+
+def find_reexports(root: BaseNode, code_bytes: bytes, import_map: dict[str, str]) -> dict[str, str]:
+    """Return the imports this module never uses — i.e. passes straight through (#182).
+
+    A transparent re-export lets one module absorb another's import edges, so an
+    N-way coupling can be linearised on paper without changing what actually
+    depends on what. Naming them is the precondition for the IMPORTS census
+    being able to look through them.
+
+    "Imported but unused" is the whole test, and in a linted tree that is a
+    precise proxy: ruff's F401 removes genuine dead imports, so what survives is
+    deliberate — `X as X`, an `__all__` entry, or an explicit noqa.
+    """
+    used = _identifiers_outside_imports(root, code_bytes)
+    return {local: target for local, target in import_map.items() if local not in used}
+
+
 class PythonExtractor(BaseExtractor):
     """
     A concrete extractor for Python source code using tree-sitter.
@@ -83,6 +140,8 @@ class PythonExtractor(BaseExtractor):
                     update={"metadata": {**nodes[i].metadata, "local_types": lt}}
                 )
 
+        reexports = find_reexports(root_node, code_bytes, import_map)
+
         file_node = Node(
             id=module_fqn,
             type=NodeType.FILE,
@@ -90,7 +149,7 @@ class PythonExtractor(BaseExtractor):
             file_path=file_path,
             start_line=1,
             end_line=root_node.end_point.row + 1,
-            metadata={"import_map": import_map},
+            metadata={"import_map": import_map, "reexports": reexports},
         )
         nodes.insert(0, file_node)
 

{codegraph_brain-0.8.0 → codegraph_brain-0.9.0}/src/cgis/query/drift/fingerprint.py

@@ -1,6 +1,6 @@
 """PatternFingerprint dataclass and FingerprintExtractor."""
 
-from collections import Counter
+from collections import Counter, defaultdict
 from dataclasses import dataclass, field
 
 from cgis.core.models import Edge, EdgeType, Node, NodeType
@@ -136,6 +136,121 @@ def _count_routers(domain_node_ids: set[str], all_edges: list[Edge]) -> int:
     return router_count
 
 
+def _follow_forwarding(reexports: dict[str, dict[str, str]], symbol_fqn: str) -> str | None:
+    """Resolve a symbol through every passthrough hop, or None if it is not forwarded.
+
+    One hop is not enough: `A -> B -> C -> D` with both B and C forwarding would
+    otherwise stop at C and leave the A->D coupling hidden — a two-hop bypass of
+    the very check this implements. The visited set makes a re-export cycle
+    terminate instead of hanging.
+    """
+    via, _, name = symbol_fqn.rpartition(".")
+    forwarded = reexports.get(via, {}).get(name)
+    if forwarded is None:
+        return None
+    seen = {symbol_fqn}
+    while forwarded not in seen:
+        seen.add(forwarded)
+        next_via, _, next_name = forwarded.rpartition(".")
+        next_hop = reexports.get(next_via, {}).get(next_name)
+        if next_hop is None:
+            break
+        forwarded = next_hop
+    return forwarded
+
+
+def _owning_module(fqn: str, modules: set[str]) -> str | None:
+    """Longest prefix of fqn that is a real module node — the fqn itself included.
+
+    `rpartition` alone is wrong at both ends. A forwarded *module*
+    (`from pkg import submodule as submodule`) would resolve to its package, and
+    a symbol nested in a class would resolve to the class — but IMPORTS edges
+    must land on FILE/MODULE nodes or the DAG-depth walk counts something that
+    is not a module.
+    """
+    parts = fqn.split(".")
+    for cut in range(len(parts), 0, -1):
+        candidate = ".".join(parts[:cut])
+        if candidate in modules:
+            return candidate
+    return None
+
+
+def _reattributed_imports(
+    domain_nodes: list[Node],
+    domain_ids: set[str],
+    internal_edges: list[Edge],
+    all_edges: list[Edge],
+) -> list[Edge]:
+    """Add the IMPORTS edges that transparent re-exports hide (#182).
+
+    A passthrough — ``from C import X as X`` in B, with X unused there — lets B
+    absorb C's import edge, so ``A -> B -> C`` measures as a 021C chain when the
+    truth is a 030T triangle. Any N-way coupling can be linearised that way
+    without changing what actually depends on what, which is what makes the
+    IMPORTS layer gameable.
+
+    So the census looks *through* the passthrough: when A takes a name from B
+    that B merely forwards from C, the hidden ``A -> C`` edge is added.
+
+    Two deliberate limits:
+
+    - **Add, never replace.** A may also take a real name from B; dropping
+      ``A -> B`` would trade a hidden edge for a lost one.
+    - **Intra-domain only**, enforced by requiring the definer in ``domain_ids``.
+      A package ``__init__.py`` re-exporting for external consumers is legitimate
+      API surface, and punishing it would teach deep-importing internals to keep
+      the dashboard green.
+    """
+    reexports: dict[str, dict[str, str]] = {
+        n.id: rx for n in domain_nodes if (rx := n.metadata.get("reexports"))
+    }
+    if not reexports:
+        return internal_edges
+
+    modules = {n.id for n in domain_nodes if n.type in (NodeType.FILE, NodeType.MODULE)}
+    taken: dict[str, list[str]] = defaultdict(list)
+    for edge in all_edges:
+        if edge.type == EdgeType.IMPORTS_SYMBOL and edge.source in domain_ids:
+            taken[edge.source].append(edge.target)
+
+    seen_pairs = {(e.source, e.target) for e in internal_edges if e.type == EdgeType.IMPORTS}
+    added: list[Edge] = []
+    for importer, symbols in taken.items():
+        for symbol_fqn in symbols:
+            definer = _definer_for(symbol_fqn, reexports, modules, importer, seen_pairs)
+            if definer is None:
+                continue
+            seen_pairs.add((importer, definer))
+            added.append(
+                Edge(
+                    id=f"{importer}:imports:{definer}:reattributed",
+                    type=EdgeType.IMPORTS,
+                    source=importer,
+                    target=definer,
+                    confidence=1.0,
+                )
+            )
+    return internal_edges + added
+
+
+def _definer_for(
+    symbol_fqn: str,
+    reexports: dict[str, dict[str, str]],
+    modules: set[str],
+    importer: str,
+    seen_pairs: set[tuple[str, str]],
+) -> str | None:
+    """The module a forwarded symbol really lives in, or None if nothing to add."""
+    forwarded = _follow_forwarding(reexports, symbol_fqn)
+    if forwarded is None:
+        return None
+    definer = _owning_module(forwarded, modules)
+    if definer is None or definer == importer or (importer, definer) in seen_pairs:
+        return None
+    return definer
+
+
 class FingerprintExtractor:
     """Compute a PatternFingerprint for a given FQN domain prefix from a SQLiteStore."""
 
@@ -212,7 +327,8 @@ class FingerprintExtractor:
         raw_calls = [e for e in calls_edges if e.target.startswith(RAW_CALL_PREFIX)]
         unresolved_ratio = len(raw_calls) / len(calls_edges) if calls_edges else 0.0
 
-        t_imports = normalized_census(triad_census(domain_ids, internal_edges, EdgeType.IMPORTS))
+        imports_edges = _reattributed_imports(domain_nodes, domain_ids, internal_edges, all_edges)
+        t_imports = normalized_census(triad_census(domain_ids, imports_edges, EdgeType.IMPORTS))
         t_calls = normalized_census(triad_census(domain_ids, internal_edges, EdgeType.CALLS))
 
         return PatternFingerprint(

{codegraph_brain-0.8.0 → codegraph_brain-0.9.0}/tests/unit/test_fingerprint.py

@@ -8,7 +8,12 @@ from conftest import module_with_funcs
 from cgis.core.models import Edge, EdgeType, Node, NodeNamespace, NodeType
 from cgis.extractors.python_extractor import PythonExtractor
 from cgis.pipeline import IngestionPipeline
-from cgis.query.drift.fingerprint import FingerprintExtractor, PatternFingerprint
+from cgis.query.drift.fingerprint import (
+    FingerprintExtractor,
+    PatternFingerprint,
+    _follow_forwarding,
+    _reattributed_imports,
+)
 from cgis.query.drift.triads import TRIAD_ORDER
 from cgis.storage.sqlite_store import SQLiteStore
 
@@ -510,3 +515,168 @@ def test_tangle_ratio_resolved_calls_unchanged() -> None:
     # unresolved_ratio 0 → discount 1 → calls-tangle unchanged (regression guard).
     fp = _tangle_fp(t_calls=_onehot("300"), unresolved_ratio=0.0)
     assert fp.tangle_ratio == pytest.approx(1.0)
+
+
+# ---------------------------------------------------------------------------
+# Transparent re-export re-attribution in the IMPORTS census (#182)
+# ---------------------------------------------------------------------------
+
+
+def _mod(fqn: str, reexports: dict[str, str] | None = None) -> Node:
+    """A FILE node, optionally carrying transparent re-exports."""
+    return Node(
+        id=fqn,
+        type=NodeType.FILE,
+        name=fqn.rsplit(".", maxsplit=1)[-1],
+        file_path=fqn.replace(".", "/") + ".py",
+        start_line=1,
+        end_line=9,
+        metadata={"reexports": reexports} if reexports else {},
+    )
+
+
+def _imports(source: str, target: str) -> Edge:
+    return Edge(id=f"{source}:i:{target}", type=EdgeType.IMPORTS, source=source, target=target)
+
+
+def _imports_symbol(source: str, target: str) -> Edge:
+    return Edge(
+        id=f"{source}:s:{target}", type=EdgeType.IMPORTS_SYMBOL, source=source, target=target
+    )
+
+
+def _census(nodes: list[Node], edges: list[Edge], prefix: str) -> dict[str, float]:
+    """Non-zero IMPORTS triad shares, keyed by class name."""
+    fp = FingerprintExtractor.from_graph(nodes, edges).extract(prefix)
+    return {name: share for name, share in zip(TRIAD_ORDER, fp.t_imports, strict=True) if share}
+
+
+#: The PR #180 shape: engine -> symbols -> indices, with symbols forwarding a
+#: name it never uses from indices. The real dependency graph is a triangle.
+_LAUNDERED_EDGES = [
+    _imports("d.engine", "d.symbols"),
+    _imports("d.symbols", "d.indices"),
+    _imports_symbol("d.engine", "d.symbols.SymbolResolver"),
+    _imports_symbol("d.engine", "d.symbols.IndexBuilder"),
+]
+
+
+def test_passthrough_reexport_measures_as_a_triangle() -> None:
+    """The laundering from #180: a chain on paper, a triangle in truth."""
+    nodes = [
+        _mod("d.engine"),
+        _mod("d.symbols", {"IndexBuilder": "d.indices.IndexBuilder"}),
+        _mod("d.indices"),
+    ]
+
+    assert _census(nodes, _LAUNDERED_EDGES, "d") == {"030T": 1.0}
+
+
+def test_same_shape_without_a_reexport_stays_a_chain() -> None:
+    """Control: identical edges, no forwarding declared — nothing is re-attributed."""
+    nodes = [_mod("d.engine"), _mod("d.symbols"), _mod("d.indices")]
+
+    assert _census(nodes, _LAUNDERED_EDGES, "d") == {"021C": 1.0}
+
+
+def test_reattribution_does_not_reach_outside_the_domain() -> None:
+    """A facade forwarding from another domain is API surface, not laundering.
+
+    Punishing it would teach deep-importing internals to keep the dashboard
+    green, so the definer must be in the same domain for the edge to be added.
+    """
+    nodes = [
+        _mod("d.engine"),
+        _mod("d.facade", {"Thing": "other.core.Thing"}),
+        _mod("d.indices"),
+    ]
+    edges = [
+        _imports("d.engine", "d.facade"),
+        _imports("d.facade", "d.indices"),
+        _imports_symbol("d.engine", "d.facade.Thing"),
+    ]
+
+    assert _census(nodes, edges, "d") == {"021C": 1.0}
+
+
+def test_reattribution_adds_rather_than_replaces() -> None:
+    """The real A->B edge survives alongside the revealed A->C one.
+
+    engine takes SymbolResolver (real) as well as IndexBuilder (forwarded);
+    dropping engine->symbols would trade a hidden edge for a lost one.
+    """
+    nodes = [
+        _mod("d.engine"),
+        _mod("d.symbols", {"IndexBuilder": "d.indices.IndexBuilder"}),
+        _mod("d.indices"),
+    ]
+    fp = FingerprintExtractor.from_graph(nodes, _LAUNDERED_EDGES).extract("d")
+
+    # 030T requires all three edges: engine->symbols, symbols->indices, engine->indices.
+    assert fp.t_imports[TRIAD_ORDER.index("030T")] == 1.0
+
+
+def _reattributed_targets(nodes: list[Node], edges: list[Edge], importer: str) -> set[str]:
+    """IMPORTS targets seen by the census for `importer`, including revealed ones."""
+    domain_ids = {n.id for n in nodes}
+    internal = [e for e in edges if e.source in domain_ids and e.target in domain_ids]
+    out = _reattributed_imports(nodes, domain_ids, internal, edges)
+    return {e.target for e in out if e.type == EdgeType.IMPORTS and e.source == importer}
+
+
+def test_chained_reexports_are_followed_to_the_definer() -> None:
+    """Two passthroughs in a row must not be a bypass.
+
+    A -> B -> C -> D where both B and C only forward. Asserting on the edge set
+    rather than a triad share: stopping at C still produces a 030T (from the
+    a-b-c triangle), so a share-based check passes for the wrong reason.
+    """
+    nodes = [
+        _mod("d.a"),
+        _mod("d.b", {"Thing": "d.c.Thing"}),
+        _mod("d.c", {"Thing": "d.dd.Thing"}),
+        _mod("d.dd"),
+    ]
+    edges = [
+        _imports("d.a", "d.b"),
+        _imports("d.b", "d.c"),
+        _imports("d.c", "d.dd"),
+        _imports_symbol("d.a", "d.b.Thing"),
+    ]
+
+    assert "d.dd" in _reattributed_targets(nodes, edges, "d.a")
+
+
+def test_reexported_module_resolves_to_the_module_not_its_package() -> None:
+    """`from pkg import submodule as submodule` forwards a module, not a symbol.
+
+    Taking the parent of the forwarded FQN would name the package; the import
+    actually lands on the submodule.
+    """
+    nodes = [_mod("d.a"), _mod("d.facade", {"leaf": "d.leaf"}), _mod("d.leaf")]
+    edges = [
+        _imports("d.a", "d.facade"),
+        _imports("d.facade", "d.leaf"),
+        _imports_symbol("d.a", "d.facade.leaf"),
+    ]
+
+    assert "d.leaf" in _reattributed_targets(nodes, edges, "d.a")
+
+
+def test_reexport_cycle_terminates() -> None:
+    """Two modules forwarding the same name to each other must not hang.
+
+    The docstring claimed the visited set handles this; review pointed out it
+    was never tested. Both the mutual and the self-referential shape resolve to
+    the symbol they started from, which `_definer_for` then discards.
+    """
+    mutual = {"d.a": {"T": "d.b.T"}, "d.b": {"T": "d.a.T"}}
+    assert _follow_forwarding(mutual, "d.a.T") == "d.a.T"
+
+    self_ref = {"d.a": {"T": "d.a.T"}}
+    assert _follow_forwarding(self_ref, "d.a.T") == "d.a.T"
+
+
+def test_dotless_symbol_is_not_a_forward() -> None:
+    """A top-level name has no `via` part, so it cannot be a passthrough."""
+    assert _follow_forwarding({"d.a": {"T": "d.b.T"}}, "Thing") is None

{codegraph_brain-0.8.0 → codegraph_brain-0.9.0}/tests/unit/test_python_extractor.py

@@ -720,3 +720,90 @@ def test_module_imports_edge_coexists_with_symbol_edges(extractor: PythonExtract
     module_edges = [e for e in edges if e.type == EdgeType.IMPORTS]
     assert len(module_edges) == 1
     assert module_edges[0].target == "a.b"
+
+
+# ---------------------------------------------------------------------------
+# Transparent re-export detection (#182)
+# ---------------------------------------------------------------------------
+
+
+def _reexports(extractor: PythonExtractor, code: str) -> dict[str, str]:
+    """Return the FILE node's recorded re-exports for a snippet."""
+    nodes, _ = extractor.parse(code, "pkg/mod.py")
+    file_node = next(n for n in nodes if n.type == NodeType.FILE)
+    return file_node.metadata.get("reexports") or {}
+
+
+def test_unused_import_is_recorded_as_a_reexport(extractor: PythonExtractor) -> None:
+    """`X as X` with no use in the body is the laundering shape from #182."""
+    code = "from pkg.other import Thing as Thing\n"
+
+    assert _reexports(extractor, code) == {"Thing": "pkg.other.Thing"}
+
+
+def test_used_import_is_not_a_reexport(extractor: PythonExtractor) -> None:
+    """A re-export that the module also uses is not transparent.
+
+    Regression guard for the real case in guardian/chunker.py, where
+    `split_diff_by_file` is both re-exported and called — a detector that
+    flagged every `import X as X` would be wrong about it.
+    """
+    code = "from pkg.other import Thing as Thing\n\ndef go():\n    return Thing()\n"
+
+    assert _reexports(extractor, code) == {}
+
+
+def test_import_used_only_in_a_quoted_annotation_is_not_a_reexport(
+    extractor: PythonExtractor,
+) -> None:
+    """A forward reference holds no identifier nodes — but it is still a use.
+
+    Regression: this reported cgis.pipeline's TYPE_CHECKING import of SQLiteStore
+    as a re-export, because `store: "SQLiteStore | None"` is a string.
+    """
+    code = 'from pkg.store import Store\n\ndef go(s: "Store | None") -> None:\n    pass\n'
+
+    assert _reexports(extractor, code) == {}
+
+
+def test_a_name_mentioned_only_in_a_docstring_is_still_a_reexport(
+    extractor: PythonExtractor,
+) -> None:
+    """Only annotation strings count as uses — otherwise prose could mask laundering."""
+    code = 'from pkg.other import Thing as Thing\n\ndef go():\n    """Mentions Thing."""\n'
+
+    assert _reexports(extractor, code) == {"Thing": "pkg.other.Thing"}
+
+
+def test_nested_annotation_string_is_a_use(extractor: PythonExtractor) -> None:
+    """`list["Store"]` counts, because the grammar wraps each element in its own `type`.
+
+    Review raised this as a likely false positive on the assumption that the
+    string's parent would be `subscript`. It is not: tree-sitter nests
+    generic_type -> type_parameter -> type -> string, so the immediate-parent
+    check already covers it. Pinned so a future refactor cannot quietly break it.
+    """
+    code = 'from pkg.store import Store\n\ndef go(s: list["Store"]) -> None:\n    pass\n'
+
+    assert _reexports(extractor, code) == {}
+
+
+def test_attribute_name_does_not_count_as_a_use(extractor: PythonExtractor) -> None:
+    """`o.thing` mentions `thing` without using the import of that name."""
+    code = "from pkg.other import thing as thing\n\ndef go(o):\n    return o.thing\n"
+
+    assert _reexports(extractor, code) == {"thing": "pkg.other.thing"}
+
+
+def test_keyword_argument_name_does_not_count_as_a_use(extractor: PythonExtractor) -> None:
+    """`f(thing=1)` likewise — the keyword is not the imported symbol."""
+    code = "from pkg.other import thing as thing\n\ndef go(f):\n    return f(thing=1)\n"
+
+    assert _reexports(extractor, code) == {"thing": "pkg.other.thing"}
+
+
+def test_object_side_of_an_attribute_is_a_use(extractor: PythonExtractor) -> None:
+    """Only the attribute half is excluded — `thing.attr` genuinely uses `thing`."""
+    code = "from pkg.other import thing as thing\n\ndef go():\n    return thing.attr\n"
+
+    assert _reexports(extractor, code) == {}

{codegraph_brain-0.8.0 → codegraph_brain-0.9.0}/uv.lock

@@ -261,7 +261,7 @@ wheels = [
 
 [[package]]
 name = "codegraph-brain"
-version = "0.8.0"
+version = "0.9.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

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

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