codmap 0.0.12__tar.gz → 0.0.13__tar.gz

{codmap-0.0.12/codmap.egg-info → codmap-0.0.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.12
+Version: 0.0.13
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -85,7 +85,7 @@ layers         core 9 · data 12 · indicators 16 · analysis 42 · visualizatio
                analysis → core 38 edges · indicators → core 22 · data → core 13
 violation    ⚠ analysis ↔ core             — one backward edge, written inside a function
 cycle          pipeline → cache → pipeline  — the classic Python import-order landmine
-lazy cycles    40 more, closed only by a function-local import — not import-time failures,
+lazy cycles    40 more, closed only by a non-eager import (function-local or `TYPE_CHECKING`) — not import-time failures,
                still mutual coupling: neither module can be extracted without the other
 coupling       core.logging_config  Ca 96   — a breaking change here reaches 96 modules
 concentration  ZoneVisualizer 35 methods, worst function CC 66 / MI 12.5

{codmap-0.0.12 → codmap-0.0.13}/README.md

@@ -49,7 +49,7 @@ layers         core 9 · data 12 · indicators 16 · analysis 42 · visualizatio
                analysis → core 38 edges · indicators → core 22 · data → core 13
 violation    ⚠ analysis ↔ core             — one backward edge, written inside a function
 cycle          pipeline → cache → pipeline  — the classic Python import-order landmine
-lazy cycles    40 more, closed only by a function-local import — not import-time failures,
+lazy cycles    40 more, closed only by a non-eager import (function-local or `TYPE_CHECKING`) — not import-time failures,
                still mutual coupling: neither module can be extracted without the other
 coupling       core.logging_config  Ca 96   — a breaking change here reaches 96 modules
 concentration  ZoneVisualizer 35 methods, worst function CC 66 / MI 12.5

{codmap-0.0.12 → codmap-0.0.13}/codemap/arch.py

@@ -207,7 +207,8 @@ def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
             worst = sorted(lazy, key=lambda c: (len(c), c))
             violations.append(Violation(
                 "no_lazy_cycles",
-                f"{len(lazy)} dependency cycle(s) closed only by a function-local import",
+                f"{len(lazy)} dependency cycle(s) closed only by a non-eager import "
+                f"(function-local, or under `if TYPE_CHECKING:`)",
                 modules=tuple(" → ".join(c) + " → " + c[0] for c in worst),
             ))
 

{codmap-0.0.12 → codmap-0.0.13}/codemap/extract/griffe_extractor.py

@@ -265,8 +265,9 @@ def _input_report(graph, pkg_dir: Path, root: Path, walk) -> dict:
     return report
 
 
-def _source_import_targets(module) -> list[tuple[str, str]]:
-    """``(target, scope)`` for the imports griffe's module-level map does not carry.
+def _source_import_targets(module) -> tuple[list[tuple[str, str]], set[str]]:
+    """``([(target, scope)], eager targets)`` — the imports griffe's module-level map does
+    not carry, and the targets it carries correctly.
 
     Two families, one traversal, one parse — griffe records neither, and both used to be
     invisible to the import graph:
@@ -282,6 +283,11 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
     - **imports written in a class body** → scope ``"module"``. They run at
       class-definition time, i.e. at import time, so they are ordinary eager dependencies
       and *can* close a real import cycle. griffe does not record them either (measured).
+    - **imports under `if TYPE_CHECKING:`** (R1-C48 / issue #18) → scope
+      ``"type_checking"``. griffe *does* record these, as module-level — it has no notion
+      of a condition that is always false at run time — so the second value returned is
+      the set of targets imported at plain module level: the caller demotes griffe's entry
+      for a target that appears only under ``TYPE_CHECKING``.
 
     Cost discipline, and it is not theoretical: the first version of this walked every
     function's subtree separately, which is quadratic in nesting and cost the dogfood
@@ -293,13 +299,13 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
     try:
         src = module.source
     except Exception:                       # no source (namespace dir, synthetic)
-        return []
+        return [], set()
     if not NESTED_IMPORT_HINT.search(src):
-        return []
+        return [], set()
     try:
         tree = ast.parse(src)
     except (SyntaxError, ValueError):
-        return []                            # unreadable: D2's report owns this file
+        return [], set()                     # unreadable: D2's report owns this file
     modpath = module.canonical_path
     f = module_file(module)
     is_pkg = f is not None and f.name == "__init__.py"
@@ -312,9 +318,11 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
         return node.module or ""
 
     out: list[tuple[str, str]] = []
+    eager: set[str] = set()   # targets imported at plain module level (griffe has them)
 
     def visit(node, scope: str | None) -> None:
-        """``scope`` is None at module level (griffe has those), else module|function."""
+        """``scope`` is None at module level (griffe has those), else
+        module|function|type_checking."""
         for child in ast.iter_child_nodes(node):
             if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
                 visit(child, "function")
@@ -322,9 +330,21 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
                 # A class body runs at import time — unless we are already inside a
                 # function, in which case the whole thing does not.
                 visit(child, "function" if scope == "function" else "module")
+            elif isinstance(child, ast.If) and scope in (None, "type_checking") \
+                    and (tc := _type_checking_branches(child)) is not None:
+                # R1-C48 (issue #18): `if TYPE_CHECKING:` never runs. Its body is a third
+                # scope; its `else` is ordinary module level. Inside a function the whole
+                # `if` is function-local already and is not looked at.
+                body_scope, else_scope = tc
+                for stmt in child.body:
+                    visit_stmt(stmt, body_scope if body_scope else scope)
+                for stmt in child.orelse:
+                    visit_stmt(stmt, else_scope if else_scope else scope)
             elif isinstance(child, ast.Import):
                 if scope is not None:
                     out.extend((a.name, scope) for a in child.names)
+                else:
+                    eager.update(a.name for a in child.names)
             elif isinstance(child, ast.ImportFrom):
                 target = resolve(child)
                 if not target:
@@ -333,6 +353,8 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
                 if scope is None:
                     if star:                 # the D3 case: griffe records nothing
                         out.append((target, "module"))
+                    eager.add(target)
+                    eager.update(f"{target}.{a.name}" for a in child.names if a.name != "*")
                     continue
                 # `from pkg.mod import name` → keep the member paths so the resolver walks
                 # down to the containing module exactly as it does for the module-level
@@ -343,19 +365,49 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
             else:
                 visit(child, scope)
 
+    def visit_stmt(stmt, scope: str | None) -> None:
+        """Route one statement through ``visit`` as if it were the only child."""
+        holder = ast.Module(body=[stmt], type_ignores=[])
+        visit(holder, scope)
+
     visit(tree, None)
-    return out
+    return out, eager
+
+
+def _type_checking_branches(node: ast.If) -> tuple[str | None, str | None] | None:
+    """``(scope of body, scope of else)`` for a recognised ``TYPE_CHECKING`` test, else None.
+
+    Recognised, narrowly (design D3): the bare name ``TYPE_CHECKING``, any attribute named
+    ``TYPE_CHECKING`` (``typing.TYPE_CHECKING``, ``t.TYPE_CHECKING``), and ``not`` of either,
+    which swaps the branches. A compound test (``TYPE_CHECKING or X``) is *not* recognised
+    and stays eager: a condition the tool cannot read is judged strictly, never leniently.
+    ``None`` in a slot means "the enclosing scope" (module level).
+    """
+    test, negated = node.test, False
+    if isinstance(test, ast.UnaryOp) and isinstance(test.op, ast.Not):
+        test, negated = test.operand, True
+    is_tc = ((isinstance(test, ast.Name) and test.id == "TYPE_CHECKING")
+             or (isinstance(test, ast.Attribute) and test.attr == "TYPE_CHECKING"))
+    if not is_tc:
+        return None
+    return (None, "type_checking") if negated else ("type_checking", None)
 
 
 def _collect(graph, obj, root, target_pkg, walk) -> None:
     if obj.kind.value == "module":
         _claim(obj, walk)  # the root claims its own path before any member is walked
         _add_node(graph, obj, root)
+        # R1-C23/D3 (star imports) + R1-C29 (function-local and class-body imports) +
+        # R1-C48 (`if TYPE_CHECKING:`): everything griffe's module-level map does not
+        # carry, or carries under the wrong scope, in one parse.
+        nested, eager = _source_import_targets(obj)
+        type_checking = {tgt for tgt, scope in nested if scope == "type_checking"}
         for name, tgt in (obj.imports or {}).items():
-            walk.imports.append((obj.canonical_path, tgt, "module"))
-        # R1-C23/D3 (star imports) + R1-C29 (function-local and class-body imports):
-        # everything griffe's module-level map does not carry, in one parse.
-        for tgt, scope in _source_import_targets(obj):
+            # griffe files an import under `if TYPE_CHECKING:` as module-level; it never
+            # runs. Demote it unless the same target is also imported eagerly (D2).
+            scope = "type_checking" if tgt in type_checking and tgt not in eager else "module"
+            walk.imports.append((obj.canonical_path, tgt, scope))
+        for tgt, scope in nested:
             walk.imports.append((obj.canonical_path, tgt, scope))
     for name, member in obj.members.items():
         if member.is_alias:
@@ -429,6 +481,13 @@ def _emit_decorated_by(graph, obj) -> None:
 
 # -- pass 2: resolve export + import edges against known nodes ----------------
 
+#: How early an import scope reaches its target: an edge carries the earliest (R1-C29 D2,
+#: R1-C48 D2). ``module`` runs at import time, ``type_checking`` never, ``function`` when
+#: the function runs — the middle one is ordered before ``function`` only so the label
+#: names the construct actually written at module level.
+_SCOPE_RANK = {"module": 0, "type_checking": 1, "function": 2}
+
+
 def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
     module_ids = sorted(
         (n.id for n in graph.nodes.values() if n.kind == "module"), key=len, reverse=True
@@ -457,7 +516,7 @@ def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
     # the eager import it is. `scope` only ever *weakens* to "function" for a pair that
     # has no module-level import at all — the edge says how the dependency is reached at
     # its earliest, never how it happens to appear last in the walk.
-    ordered = sorted(imports, key=lambda t: t[2] == "function")
+    ordered = sorted(imports, key=lambda t: _SCOPE_RANK.get(t[2], 0))
 
     # pass A — package-qualified targets. Exact, and run first so that a pair reachable
     # both ways is recorded as exact rather than inferred.
@@ -472,7 +531,7 @@ def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
         if key in seen:
             continue
         seen.add(key)
-        extras = {"scope": "function"} if scope == "function" else {}
+        extras = {"scope": scope} if scope != "module" else {}
         graph.add_edge(Edge("imports", src_module, tgt_module, extras=extras))
 
     # pass B — flat layout (R1-C21): sibling modules importing each other by bare name
@@ -489,8 +548,8 @@ def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
             continue
         seen.add(key)
         extras = {"resolution": "flat"}
-        if scope == "function":
-            extras["scope"] = "function"
+        if scope != "module":
+            extras["scope"] = scope
         graph.add_edge(Edge("imports", src_module, tgt_module, extras=extras))
 
 

{codmap-0.0.12 → codmap-0.0.13}/codemap/extract/union.py

@@ -36,7 +36,10 @@ An edge seen in fewer than N runs carries ``extras.seen: k``; nothing is written
 ``k == N``, so a single-sample build's edges are byte-identical to what they were. Node
 counters (``calls`` / ``attr_access``) count *sites*, which dedupe into edges — the
 measured node had three counter variants behind one flapping edge — so per node the
-variant with the fewest ``unresolved`` is kept (tie: most ``resolved``, tie: first run).
+variant with the fewest ``unresolved`` is kept (tie: most ``resolved``, tie: the serialized
+counter). Every choice between variants of one key is a **total order** over the candidates
+(:func:`_rank`, :func:`_counter_rank`): the merged graph is a function of the set of
+samples, and the same samples in any order produce the same bytes.
 
 **Every sample is a fresh process.** The share above was measured across processes —
 the consumer's 175 builds and the eight here. Repeating the behavioural layer *inside*
@@ -74,20 +77,30 @@ def _identity(e: Edge) -> tuple:
             json.dumps(e.extras, sort_keys=True, ensure_ascii=False))
 
 
-def _deeper(new: Edge, current: Edge) -> bool:
-    return (new.extras.get("resolution") == "deep"
-            and current.extras.get("resolution") != "deep")
+def _rank(e: Edge) -> tuple:
+    """Total order among the variants of one identity key: ``deep`` beats any other
+    resolution, more call sites beat fewer, and the serialized ``extras`` break what is
+    left — so the winner is a function of the *set* of samples, never of the order they
+    arrived in. The consumer's hint on codemap#17: where two candidates are equally
+    legitimate, 'first one wins' is a dependence on arrival order, and one that a probe
+    permuting the *output* can never see."""
+    ex = e.extras
+    return (ex.get("resolution") == "deep", ex.get("callsites", 0),
+            json.dumps(ex, sort_keys=True, ensure_ascii=False))
+
+
+def _counter_rank(c: dict) -> tuple:
+    return (-c.get("unresolved", 0), c.get("resolved", 0), json.dumps(c, sort_keys=True))
 
 
 def _better_counter(a: dict | None, b: dict | None) -> dict | None:
-    """The counter variant that resolved more sites (``None`` never beats a value)."""
+    """The counter variant that resolved more sites (``None`` never beats a value);
+    a tie is broken by the serialized counter, not by which sample came first."""
     if a is None:
         return b
     if b is None:
         return a
-    ka = (-a.get("unresolved", 0), a.get("resolved", 0))
-    kb = (-b.get("unresolved", 0), b.get("resolved", 0))
-    return b if kb > ka else a
+    return b if _counter_rank(b) > _counter_rank(a) else a
 
 
 def merge_samples(samples: list[Graph]) -> tuple[Graph, dict]:
@@ -116,7 +129,7 @@ def merge_samples(samples: list[Graph]) -> tuple[Graph, dict]:
             else:
                 if key not in seen_this_run:
                     entry[0] += 1
-                if _deeper(e, entry[1]):
+                if _rank(e) > _rank(entry[1]):
                     entry[1] = e
             seen_this_run.add(key)
 

{codmap-0.0.12 → codmap-0.0.13}/codemap/query.py

@@ -119,7 +119,7 @@ class Query:
         # made an incomplete map read as a safety property.
         self._imports = nx.DiGraph()
         self._imports_eager = nx.DiGraph()
-        self._import_scopes = {"module": 0, "function": 0}
+        self._import_scopes = {"module": 0, "function": 0, "type_checking": 0}
         for n in graph.nodes.values():
             if n.kind == "module":
                 self._imports.add_node(n.id)
@@ -127,8 +127,11 @@ class Query:
         for e in graph.edges:
             if e.type == "imports":
                 self._imports.add_edge(e.source, e.target)
-                if e.extras.get("scope") == "function":
-                    self._import_scopes["function"] += 1
+                scope = e.extras.get("scope")
+                if scope in ("function", "type_checking"):
+                    # R1-C29: runs when the function runs; R1-C48: never runs. Neither
+                    # is an import-time edge.
+                    self._import_scopes[scope] += 1
                 else:
                     self._imports_eager.add_edge(e.source, e.target)
                     self._import_scopes["module"] += 1
@@ -885,7 +888,8 @@ class Query:
         return [c for c in nx.simple_cycles(self._imports_eager)]
 
     def lazy_import_cycles(self) -> list[list[str]]:
-        """Dependency cycles that close **only** through a function-local import.
+        """Dependency cycles that close **only** through a non-eager import — one
+        written inside a function (R1-C29) or under ``if TYPE_CHECKING:`` (R1-C48).
 
         Not an import-time failure, and not nothing: the modules still cannot be
         separated, and the lazy import is the evidence someone already hit this. Before
@@ -904,7 +908,8 @@ class Query:
         did not look for them".
         """
         return {"module_level": self._import_scopes["module"],
-                "function_local": self._import_scopes["function"]}
+                "function_local": self._import_scopes["function"],
+                "type_checking": self._import_scopes["type_checking"]}
 
     def orphan_modules(self, root: str | None = None) -> list[str]:
         """Modules with no incoming imports (dead-code candidates — heuristic).

{codmap-0.0.12 → codmap-0.0.13}/codemap/serve/architecture.py

@@ -19,7 +19,8 @@ def build_architecture(query: Query) -> dict:
     """Structured whole-system overview (cycles + layers + coupling + hotspots).
 
     R1-C29: ``cycles`` are the **import-time** ones and ``lazy_cycles`` the dependency
-    cycles closed only by a function-local import. Splitting them is the point — a lazy
+    cycles closed only by a non-eager import — function-local (R1-C29) or under
+    ``if TYPE_CHECKING:`` (R1-C48). Splitting them is the point — a lazy
     import is how a developer *fixes* an import cycle, so folding the two together would
     report someone's fix as their bug, while dropping the second (what this tool did
     until issue #11) hides that the modules are still inseparable. ``import_map`` is
@@ -78,15 +79,16 @@ def render_architecture(query: Query) -> str:
                 sorted(a["cycles"], key=lambda c: (len(c), c))]
                or ["_none found in the eager import graph._"])
     out.append("")
-    out.append(f"_Read {im['module_level']} module-level and {im['function_local']} "
-               f"function-local import(s). Only module-level imports run at import time, "
-               f"so only they can break on import._")
+    out.append(f"_Read {im['module_level']} module-level, {im['function_local']} "
+               f"function-local and {im['type_checking']} `TYPE_CHECKING` import(s). Only "
+               f"module-level imports run at import time, so only they can break on import; "
+               f"an import under `if TYPE_CHECKING:` never runs._")
     out.append("")
     if a["lazy_cycles"]:
-        out.append(f"### Dependency cycles closed only by a function-local import: "
-                   f"{len(a['lazy_cycles'])}")
+        out.append(f"### Dependency cycles closed only by a non-eager import "
+                   f"(function-local, or under `if TYPE_CHECKING:`): {len(a['lazy_cycles'])}")
         out.append("")
-        out.append("_These do **not** break at import time — the lazy import is what "
+        out.append("_These do **not** break at import time — the non-eager import is what "
                    "prevents that, and is usually deliberate. They are listed because "
                    "the modules are still mutually dependent: neither can be extracted "
                    "without the other._")

{codmap-0.0.12 → codmap-0.0.13}/codemap/serve/audit.py

@@ -29,11 +29,13 @@ def render_dependencies(query: Query) -> str:
         # map that would have to be complete to support it demonstrably is not.
         lines.append("_none found in the eager import graph._")
     lines.append("")
-    lines.append(f"_Read {im['module_level']} module-level and {im['function_local']} "
-                 f"function-local import(s); only the former run at import time. "
-                 + (f"{len(lazy)} further cycle(s) close through a lazy import — real "
-                    f"coupling, not an import-time failure._" if lazy
-                    else "No cycle closes through a lazy import._"))
+    lines.append(f"_Read {im['module_level']} module-level, {im['function_local']} "
+                 f"function-local and {im['type_checking']} `TYPE_CHECKING` import(s); only "
+                 f"the first run at import time. "
+                 + (f"{len(lazy)} further cycle(s) close through a non-eager import "
+                    f"(function-local, or under `if TYPE_CHECKING:`) — real coupling, not "
+                    f"an import-time failure._" if lazy
+                    else "No cycle closes through a non-eager import._"))
     lines.append("")
 
     lines.append("## Most-depended-on modules (top 15)")

{codmap-0.0.12 → codmap-0.0.13}/codemap/serve/check.py

@@ -33,9 +33,10 @@ def _not_judged(query, contract: ArchitectureContract) -> list[dict]:
     return [{
         "rule": "no_cycles",
         "judged": "the eager import graph — imports that run at import time",
-        "not_judged": "dependency cycles closed only by a function-local import",
+        "not_judged": "dependency cycles closed only by a non-eager import (function-local, or under `if TYPE_CHECKING:`)",
+        "type_checking_imports": query.import_map()["type_checking"],
         "count": len(lazy),
-        "note": ("a lazy import does not run at import time, so such a cycle cannot break "
+        "note": ("a non-eager import does not run at import time, so such a cycle cannot break "
                  "on import; it is still mutual coupling. Set `no_lazy_cycles = true` to "
                  "gate these as well, or see `report architecture` for the list."),
     }]
@@ -132,10 +133,14 @@ def _render_scope(query, contract: ArchitectureContract) -> str:
         return ""
     s = scope[0]
     if not s["count"]:
-        return ("\n_`no_cycles` judged the eager import graph; no dependency cycle is closed "
-                "only by a function-local import either._\n")
+        return (f"\n_`no_cycles` judged the eager import graph; no dependency cycle is closed "
+                f"only by a non-eager import (function-local, or under `if TYPE_CHECKING:`) "
+                f"either. {s['type_checking_imports']} import(s) under `TYPE_CHECKING` read "
+                f"as never running._\n")
     return (f"\n_`no_cycles` judged **the eager import graph only** — imports that run at "
             f"import time. **{s['count']}** dependency cycle(s) closed only by a "
-            f"function-local import were **not** judged: such a cycle cannot break on "
-            f"import, but the coupling is real. `report architecture` lists them; "
-            f"`no_lazy_cycles = true` gates them._\n")
+            f"non-eager import (function-local, or under `if TYPE_CHECKING:`) were **not** "
+            f"judged: such a cycle cannot break on import, but the coupling is real. "
+            f"`report architecture` lists them; `no_lazy_cycles = true` gates them. "
+            f"{s['type_checking_imports']} import(s) under `TYPE_CHECKING` read as never "
+            f"running._\n")

{codmap-0.0.12 → codmap-0.0.13}/codemap/serve/livingdocs.py

@@ -156,8 +156,9 @@ def render_docs(query: Query) -> str:
         # proof of acyclicity, which this map cannot support.
         out.append("- No import cycle found in the eager import graph.")
     if lazy:
-        out.append(f"- **{len(lazy)} dependency cycle(s) closed only by a function-local "
-                   f"import** — deliberate, and still mutual coupling.")
+        out.append(f"- **{len(lazy)} dependency cycle(s) closed only by a non-eager "
+                   f"import** (function-local, or under `if TYPE_CHECKING:`) — deliberate, "
+                   f"and still mutual coupling.")
     if lay["violations"]:
         out.append("- **Layer violations (mutual dependency):** "
                    + ", ".join(f"{a} ↔ {b}" for a, b in lay["violations"]))

{codmap-0.0.12 → codmap-0.0.13/codmap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.12
+Version: 0.0.13
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -85,7 +85,7 @@ layers         core 9 · data 12 · indicators 16 · analysis 42 · visualizatio
                analysis → core 38 edges · indicators → core 22 · data → core 13
 violation    ⚠ analysis ↔ core             — one backward edge, written inside a function
 cycle          pipeline → cache → pipeline  — the classic Python import-order landmine
-lazy cycles    40 more, closed only by a function-local import — not import-time failures,
+lazy cycles    40 more, closed only by a non-eager import (function-local or `TYPE_CHECKING`) — not import-time failures,
                still mutual coupling: neither module can be extracted without the other
 coupling       core.logging_config  Ca 96   — a breaking change here reaches 96 modules
 concentration  ZoneVisualizer 35 methods, worst function CC 66 / MI 12.5

{codmap-0.0.12 → codmap-0.0.13}/codmap.egg-info/SOURCES.txt

@@ -116,6 +116,7 @@ tests/test_r1c44_absent_answers.py
 tests/test_r1c45_repeat_union.py
 tests/test_r1c46_shadowed_definitions.py
 tests/test_r1c47_incremental_resample.py
+tests/test_r1c48_type_checking_imports.py
 tests/test_r1c4_complexity.py
 tests/test_r1c5_apidiff.py
 tests/test_r1c6_pack.py

{codmap-0.0.12 → codmap-0.0.13}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 # version. README says this plainly, since `pip install codmap` / `import codemap` is a
 # seam a reader will otherwise hit by surprise.
 name = "codmap"
-version = "0.0.12"
+version = "0.0.13"
 description = "Static analyzer that turns a package's source into a queryable code graph."
 readme = "README.md"
 # M20/D1: measured, not assumed. Each release of the declared range runs the full suite in

{codmap-0.0.12 → codmap-0.0.13}/tests/test_m1_query.py

@@ -63,10 +63,15 @@ def test_dependencies_both_ways(q):
 
 
 def test_cycle_detection(q):
-    cycles = q.import_cycles()
-    # bquant has a real pipeline<->cache circular dependency.
-    flat = {frozenset(c) for c in cycles}
-    assert frozenset({PIPELINE, "bquant.analysis.zones.cache"}) in flat
+    # bquant's pipeline<->cache pair is mutually dependent, and the cache side reaches
+    # pipeline only through an import under `if TYPE_CHECKING:` — which never runs. Until
+    # R1-C48 (issue #18) that edge was counted as eager and this test pinned the defect:
+    # the pair is a *dependency* cycle, and not an import-time one.
+    pair = frozenset({PIPELINE, "bquant.analysis.zones.cache"})
+    assert pair not in {frozenset(c) for c in q.import_cycles()}, \
+        "an import under TYPE_CHECKING must not close an eager cycle"
+    assert pair in {frozenset(c) for c in q.lazy_import_cycles()}
+    assert q.import_map()["type_checking"] >= 1
 
 
 def test_orphan_modules(q):

{codmap-0.0.12 → codmap-0.0.13}/tests/test_r1c29_lazy_imports.py

@@ -153,7 +153,7 @@ def test_import_map_is_emitted_even_when_nothing_is_lazy(tmp_path):
     to tell "no lazy imports here" from "this build did not look for them"."""
     pkg = _pkg(tmp_path, {"a.py": "x = 1\n", "b.py": "from pkg.a import x\n"})
     im = Query(extract(str(pkg))).import_map()
-    assert im == {"module_level": 1, "function_local": 0}
+    assert im == {"module_level": 1, "function_local": 0, "type_checking": 0}
 
 
 # -- and no consumer states acyclicity as a property -------------------------
@@ -162,21 +162,21 @@ def test_architecture_never_claims_acyclic(lazy_cycle):
     md = render_architecture(Query(extract(str(lazy_cycle))))
     assert "acyclic" not in md, "a partial map cannot support a property claim"
     assert "none found in the eager import graph" in md
-    assert "function-local import(s)" in md
-    assert "Dependency cycles closed only by a function-local import: 1" in md
+    assert "function-local and 0 `TYPE_CHECKING` import(s)" in md
+    assert "Dependency cycles closed only by a non-eager import (function-local, or under `if TYPE_CHECKING:`): 1" in md
 
 
 def test_dependencies_report_never_claims_acyclic(lazy_cycle):
     md = render_dependencies(Query(extract(str(lazy_cycle))))
     assert "acyclic" not in md
-    assert "close through a lazy import" in md
+    assert "close through a non-eager import" in md
 
 
 def test_architecture_payload_carries_both_kinds_and_the_counts(lazy_cycle):
     a = build_architecture(Query(extract(str(lazy_cycle))))
     assert a["cycles"] == []
     assert [sorted(c) for c in a["lazy_cycles"]] == [["pkg.a", "pkg.b"]]
-    assert a["import_map"] == {"module_level": 1, "function_local": 1}
+    assert a["import_map"] == {"module_level": 1, "function_local": 1, "type_checking": 0}
 
 
 def test_no_renderer_states_acyclicity_anywhere(tmp_path):

{codmap-0.0.12 → codmap-0.0.13}/tests/test_r1c30f2_check_scope.py

@@ -92,7 +92,7 @@ def test_it_is_declared_even_when_there_is_nothing_to_declare(eager_only):
     contract, violations = _run(eager_only, {"no_cycles": True})
     scope = build_check(eager_only, contract, violations)["scope"]
     assert len(scope) == 1 and scope[0]["count"] == 0
-    assert "no dependency cycle is closed only by a function-local import" \
+    assert "no dependency cycle is closed only by a non-eager import" \
         in render_check(eager_only, contract, violations)
 
 

{codmap-0.0.12 → codmap-0.0.13}/tests/test_r1c45_repeat_union.py

@@ -72,6 +72,31 @@ def test_the_order_of_runs_does_not_change_the_result():
     assert _edges(merge_samples([shallow, deep])[0]) == _edges(merge_samples([deep, shallow])[0])
 
 
+def test_the_same_samples_in_any_order_merge_to_the_same_bytes():
+    """codemap#17, the consumer's hint: where two candidates are equally legitimate, the
+    choice must not depend on the order the samples arrived in. The three places the
+    rule 'deep wins, else first run' could see a tie are fed here — two `deep` variants
+    of one call, two non-deep variants of one call, and a counter tie — and every
+    permutation of the same samples must serialize to the same bytes (provenance is
+    the first sample's by contract and is left out)."""
+    import itertools
+    a = _graph([("calls", "pkg.a", "pkg.B", {"resolution": "deep", "callsites": 1, "via": "B"}),
+                ("calls", "pkg.a", "pkg.B.m", {"resolution": "imported", "callsites": 1, "via": "m"})],
+               {"attr_access": {"out": 4, "resolved": 3, "unresolved": 1, "external": 0}})
+    b = _graph([("calls", "pkg.a", "pkg.B", {"resolution": "deep", "callsites": 2, "via": "B"}),
+                ("calls", "pkg.a", "pkg.B.m", {"resolution": "imported", "callsites": 2, "via": "m"})],
+               {"attr_access": {"out": 4, "resolved": 3, "unresolved": 1, "external": 1}})
+    c = _graph([("calls", "pkg.a", "pkg.B", {"resolution": "deep", "callsites": 1, "via": "B"})])
+
+    def bytes_of(samples):
+        d = json.loads(store.dumps(merge_samples(list(samples))[0]))
+        d.pop("provenance", None)
+        return json.dumps(d, sort_keys=True)
+
+    outcomes = {bytes_of(p) for p in itertools.permutations([a, b, c])}
+    assert len(outcomes) == 1, f"{len(outcomes)} distinct graphs from the same three samples"
+
+
 def test_a_read_and_a_write_of_one_attribute_are_two_edges_not_one():
     """`(type, source, target)` would collapse these; 96 such pairs exist in one bquant build."""
     pair = [("accesses", "pkg.a", "pkg.B.f", {"access": "read", "resolution": "self"}),
@@ -82,6 +107,30 @@ def test_a_read_and_a_write_of_one_attribute_are_two_edges_not_one():
     assert stats == {"runs": 2, "unstable": 0}
 
 
+def test_the_third_trees_three_pairs_survive_the_merge_and_deep_wins_only_by_resolution():
+    """codemap#17: on the consumer's 219-file tree 17 logical triples carry two records on
+    the deep tier — a read and a write, a name as annotation and as value, a dict-literal
+    and a subscript write of one column. Fed literally: every pair must come out as two
+    edges, and only an `imported`/`deep` pair on a call may collapse — by `resolution`,
+    not by the rest of `extras`."""
+    pairs = [
+        ("accesses", "pkg.a", "pkg.B.by_k", {"access": "read", "resolution": "self"}),
+        ("accesses", "pkg.a", "pkg.B.by_k", {"access": "write", "resolution": "self"}),
+        ("references", "pkg.a", "pkg.B", {"resolution": "annotation", "sites": 1}),
+        ("references", "pkg.a", "pkg.B", {"resolution": "name", "sites": 1}),
+        ("writes", "pkg.a", "column:n_zones", {"access": "dict-literal", "resolution": "string-key"}),
+        ("writes", "pkg.a", "column:n_zones", {"access": "subscript", "resolution": "string-key"}),
+        ("calls", "pkg.a", "pkg.B.m", {"resolution": "imported", "via": "B.m", "callsites": 1}),
+    ]
+    deeper = pairs[:-1] + [("calls", "pkg.a", "pkg.B.m", {"resolution": "deep", "via": "B.m", "callsites": 2})]
+    merged, stats = merge_samples([_graph(pairs), _graph(deeper), _graph(pairs)])
+    assert len(merged.edges) == 7, "six facts in three pairs plus one call — nothing collapsed"
+    assert all("seen" not in e.extras for e in merged.edges), "every fact was in every run"
+    call = next(e for e in merged.edges if e.type == "calls")
+    assert call.extras == {"resolution": "deep", "via": "B.m", "callsites": 2}
+    assert stats == {"runs": 3, "unstable": 0}
+
+
 def test_a_construct_write_and_a_deep_write_are_two_sites_and_both_survive():
     pair = [("accesses", "pkg.a", "pkg.B.f", {"access": "write", "resolution": "construct"}),
             ("accesses", "pkg.a", "pkg.B.f", {"access": "write", "resolution": "deep"})]