analyzer: module-level name bindings produce graph Nodes

Generalize the analyzer's notion of "defined Node" so that every named
entity reachable from outside its definition site has a Node — not just
classes, functions, modules, and imports.

Until now, module-level plain assignments (`CONSTANT = 42`, `LOGGER = ...`,
`store = _NS()`) were tracked only as scope-local set_value bindings, with
no Node in the graph. Cross-module imports contracted to wildcards, and
the #127 attribute-fallback had to climb all the way to the enclosing
module since the binding itself wasn't an addressable Node.

Now `_bind_target` creates a defined Flavor.NAME Node at the LHS dotted
path whenever the current scope is a module or class. Function-locals
stay as scope-only set_value bindings (promoting every loop variable to
a Node would clutter the graph).

Consequences:
- `from mymod import CONSTANT` resolves to the actual NAME Node rather
  than contracting to a wildcard.
- The #127 fallback for `store.dataset` lands on `mymod.store` (the
  binding) rather than the enclosing module — strictly more specific.
  For the simple-attribute case the "fallback" no longer climbs at all,
  since obj_node itself is already defined; the same code path still
  fires but is now redundant with what the obj_node already provides.
  The chained-access case still genuinely climbs through undefined
  intermediate ATTRIBUTE Nodes.
- Edgeless NAME Nodes (module constants that nobody imports) are
  suppressed from the rendered output by default in visgraph, so the
  default visual density is unchanged. The Node still exists in the
  analyzer's graph for cross-module resolution.

Tests:
- The three #127 regression tests now assert the more-specific edge
  target (`namespace_module.store` instead of `namespace_module`). The
  simple-case tests are renamed to `_emits_edge_to_binding`, dropping
  the "falls_back" framing since obj_node is now already defined; the
  chained-case test keeps "climbs_to_defined_ancestor" because the
  climb through undefined intermediates is still genuine.
- Four new tests in test_features.py cover the prequisite directly:
  module-level binding creates a defined NAME Node, function-local
  does not, cross-module constant import resolves to the NAME Node,
  visgraph suppresses edgeless NAME Nodes.

Prequisite to #129.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Technologicat

CHANGELOG.md

@@ -1,12 +1,20 @@
 # Changelog
 
-## 2.5.1 (in progress)
+## 2.6.0 (in progress)
+
+### New features
+
+- **Module-level name bindings now produce graph Nodes.** Every module-level assignment (e.g. `CONSTANT = 42`, `LOGGER = logging.getLogger(__name__)`, `store = _NS()`) creates a defined `Flavor.NAME` Node at the bound dotted path. `from mymod import x` now resolves to the actual binding instead of contracting to a wildcard, and the #127 attribute-fallback lands on the specific binding rather than climbing all the way to the enclosing module. Function-locals are unchanged — they stay as scope-only bindings to keep the graph readable. Edgeless NAME Nodes (module constants nobody imports) are suppressed from the rendered output by default; they remain in the analyzer's graph for cross-module resolution.
 
 ### Bug fixes
 
 - **Cross-module attribute reads on namespace-style modules now produce uses edges.** A module whose public surface is a runtime-built object (`SimpleNamespace`, `unpythonic.env.env`, a small `class _NS: pass; store = _NS()` shim) used to appear as an isolated node even when it was central to the subsystem — every `store.dataset` access landed on a synthetic ATTRIBUTE node that visgraph dropped as undefined. The analyzer now also emits an edge to the immediate defined parent of the obj (typically the exporting module) when the attribute itself can't be resolved. Symmetric for attribute writes (`store.flag = value`). One-level only — does not climb through unanalyzed packages, and within-scope self-references are suppressed (a method reading an undefined attribute on its own class, or a function reading module-level state in its own module, is just normal scoping). Generalizes the existing class-fallback (Enum members, class constants) introduced in 2.4.0. (#127)
 - **Advisory when `infer_root` may have misidentified the package root.** Two ambiguous situations now emit a warning suggesting `--root`: (1) inference walked up at least one package level and stopped at a directory that has neither `__init__.py` nor a project-root marker (`pyproject.toml`, `setup.py`, `setup.cfg`) — consistent with a top-level PEP 420 namespace package; (2) inference didn't walk up at all but the input directory's parent has `__init__.py` — consistent with the user feeding pyan the contents of a namespace subpackage (e.g. `pyan3 pkg/sub_ns/*.py` where `sub_ns/` has no `__init__.py`), which would otherwise silently produce bare module names and broken relative imports. Auto-walking further is unsafe — the same filesystem shapes also occur for workspace directories like `tests/` or `examples/` — so the choice is left to the user. The `--root` help text now also mentions the namespace-package case explicitly. (#128)
 
+### Internal
+
+- **Flavor rename:** `Flavor.NAMESPACE` (synthetic structural marker for module/class/function scope bookkeeping) is now `Flavor.SCOPE`. The previous name is being freed up for an upcoming `Flavor.NAMESPACE_OBJECT` representing a runtime namespace value (env, SimpleNamespace, …). The Node represents the scope; the `Scope` class implements one — same concept at two layers.
+
 
 ---
 

pyan/__init__.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-__version__ = "2.5.1-dev"
+__version__ = "2.6.0-dev"
 
 from .main import create_callgraph, main  # noqa: F401
 from .modvis import create_modulegraph  # noqa: F401

pyan/analyzer.py

@@ -1763,6 +1763,7 @@ def _bind_target(self, target, value):
         """
         if isinstance(target, ast.Name):
             self.set_value(target.id, value)
+            self._maybe_define_name_node(target)
         elif isinstance(target, ast.Attribute):
             try:
                 if self.set_attribute(target, value):
@@ -1792,6 +1793,39 @@ def _bind_target(self, target, value):
         elif isinstance(target, ast.arg):
             self.set_value(target.arg, value)
 
+    def _maybe_define_name_node(self, name_target):
+        """Create a defined ``Flavor.NAME`` Node for an ``ast.Name`` binding
+        target if currently in a module or class scope.
+
+        The graph's notion of "defined Node" tracks named entities reachable
+        from outside their definition site. Module-level and class-level
+        bindings are reachable (via ``from mymod import x`` or ``Class.x``)
+        and so deserve a Node so that cross-module imports and attribute
+        accesses can resolve to the actual binding rather than degrading to
+        a wildcard or to #127's coarser module-level fallback.
+
+        Function-locals (and synthetic anonymous scopes — comprehensions,
+        lambdas — which symtable reports as ``"function"``) are not
+        externally addressable; promoting every loop variable to a Node
+        would only clutter the graph. They stay scope-only, set via
+        ``set_value``.
+
+        Method/function/class definitions are flavored separately by their
+        own visitors (``visit_FunctionDef``, ``visit_ClassDef``) and don't
+        come through this path.
+        """
+        if not self.scope_stack:
+            return
+        scope = self.scope_stack[-1]
+        if scope.type not in ("module", "class"):
+            return
+        from_node = self.get_node_of_current_namespace()
+        ns = from_node.get_name()
+        to_node = self.get_node(ns, name_target.id, name_target, flavor=Flavor.NAME)
+        if self.add_defines_edge(from_node, to_node):
+            self.logger.info(f"Def from {from_node} to NAME {to_node}")
+        self.associate_node(to_node, name_target, self.filename)
+
     @staticmethod
     def _collect_target_names(target, names):
         """Collect all Name identifiers from an assignment target AST node."""

pyan/visgraph.py

@@ -173,11 +173,31 @@ def make_tooltip(n):
         logger = logger or logging.getLogger(__name__)
 
         # collect and sort defined nodes
+        #
+        # NAME-flavored Nodes with no incoming or outgoing uses edges are
+        # suppressed by default. Module-level bindings (e.g. ``__version__``,
+        # ``LOGGER``) become defined NAME Nodes during analysis to make them
+        # addressable for cross-module imports, but if nothing actually
+        # imports or uses them, they only add visual noise. Their defines
+        # edge from the enclosing module is *always* present by construction
+        # and so cannot indicate use; we look at uses_edges only.
+        from .node import Flavor  # noqa: PLC0415 -- avoid circular import at module level
+        named_with_uses = set()
+        for from_node, to_nodes in visitor.uses_edges.items():
+            if from_node.flavor == Flavor.NAME:
+                named_with_uses.add(from_node)
+            for to_node in to_nodes:
+                if to_node.flavor == Flavor.NAME:
+                    named_with_uses.add(to_node)
+
         visited_nodes = []
         for name in visitor.nodes:
             for node in visitor.nodes[name]:
-                if node.defined:
-                    visited_nodes.append(node)
+                if not node.defined:
+                    continue
+                if node.flavor == Flavor.NAME and node not in named_with_uses:
+                    continue
+                visited_nodes.append(node)
         visited_nodes.sort(key=lambda x: (x.namespace, x.name))
 
         def find_filenames():
@@ -254,17 +274,21 @@ def find_filenames():
             #
             color = "#838b8b" if draw_defines else "#ffffff00"
             for n in visitor.defines_edges:
-                if n.defined:
-                    for n2 in visitor.defines_edges[n]:
-                        if n2.defined:
-                            root_graph.edges.append(VisualEdge(nodes_dict[n], nodes_dict[n2], "defines", color))
+                if n not in nodes_dict:
+                    continue
+                for n2 in visitor.defines_edges[n]:
+                    if n2 not in nodes_dict:
+                        continue
+                    root_graph.edges.append(VisualEdge(nodes_dict[n], nodes_dict[n2], "defines", color))
 
         if draw_uses:
             color = "#000000"
             for n in visitor.uses_edges:
-                if n.defined:
-                    for n2 in visitor.uses_edges[n]:
-                        if n2.defined:
-                            root_graph.edges.append(VisualEdge(nodes_dict[n], nodes_dict[n2], "uses", color))
+                if n not in nodes_dict:
+                    continue
+                for n2 in visitor.uses_edges[n]:
+                    if n2 not in nodes_dict:
+                        continue
+                    root_graph.edges.append(VisualEdge(nodes_dict[n], nodes_dict[n2], "uses", color))
 
         return root_graph

tests/test_features.py

@@ -820,3 +820,79 @@ def test_depth_no_self_edges():
 
     for n, edges in v.uses_edges.items():
         assert n not in edges, f"Self-edge on {n.get_name()}"
+
+
+# --- Module-level NAME Node-ification ---
+#
+# Every named entity reachable from outside its definition site is a Node.
+# Module-level and class-level bindings are reachable; function-locals are not.
+
+def _name_nodes_at(visitor, namespace):
+    """Return defined NAME-flavored Nodes at *namespace*."""
+    from pyan.node import Flavor
+    return [
+        n for ns in visitor.nodes.values() for n in ns
+        if n.defined and n.flavor == Flavor.NAME and n.namespace == namespace
+    ]
+
+
+def test_module_level_assignment_creates_defined_name_node():
+    """``mymod.x = ...`` at module level produces a defined ``Flavor.NAME``
+    Node at ``mymod.x``, with a defines edge from the module Node."""
+    v = CallGraphVisitor.from_sources([
+        ("CONSTANT = 42\nLOGGER = object()\n", "mymod"),
+    ])
+    name_nodes = {n.name for n in _name_nodes_at(v, "mymod")}
+    assert "CONSTANT" in name_nodes
+    assert "LOGGER" in name_nodes
+
+
+def test_function_local_does_not_create_name_node():
+    """Function-local bindings stay as scope-only ``set_value`` and do not
+    produce graph Nodes — they aren't externally addressable and would
+    only clutter the graph."""
+    v = CallGraphVisitor.from_sources([
+        ("def f():\n    local = 1\n    return local\n", "mymod"),
+    ])
+    name_nodes = {n.name for n in _name_nodes_at(v, "mymod.f")}
+    assert "local" not in name_nodes
+
+
+def test_cross_module_constant_import_resolves_to_name_node():
+    """``from mymod import CONSTANT`` should bind to the actual NAME Node
+    at ``mymod.CONSTANT``, not contract to a wildcard. This is the
+    precision win from making module-level bindings addressable Nodes."""
+    v = CallGraphVisitor.from_sources([
+        ("CONSTANT = 42\n", "constants"),
+        ("from constants import CONSTANT\n\ndef use():\n    return CONSTANT\n", "consumer"),
+    ])
+    use_uses = {n.get_name() for n in v.uses_edges.get(
+        v.get_node("consumer", "use"), set()
+    )}
+    assert "constants.CONSTANT" in use_uses
+
+
+def test_visgraph_suppresses_edgeless_name_nodes():
+    """NAME Nodes with no incoming or outgoing uses edges should not appear
+    in the visgraph output (visual-density default). The Node still exists
+    in the analyzer's graph for cross-module resolution; only the rendered
+    output filters it."""
+    from pyan.visgraph import VisualGraph
+    v = CallGraphVisitor.from_sources([
+        # UNUSED has no uses edges anywhere; USED is imported by consumer.
+        ("UNUSED = 1\nUSED = 2\n", "constants"),
+        ("from constants import USED\n\ndef f():\n    return USED\n", "consumer"),
+    ])
+    vg = VisualGraph.from_visitor(v, options={"draw_defines": True, "draw_uses": True})
+
+    def collect(graph, out):
+        for n in graph.nodes:
+            out.add(n.label)
+        for sg in graph.subgraphs:
+            collect(sg, out)
+    labels = set()
+    collect(vg, labels)
+    assert any("USED" in lab for lab in labels), f"USED should appear; saw {labels}"
+    assert not any("UNUSED" in lab for lab in labels), (
+        f"UNUSED has no uses edges and should be suppressed; saw {labels}"
+    )

tests/test_regressions.py

@@ -407,36 +407,39 @@ def _issue127_visitor(*basenames):
     return CallGraphVisitor(filenames, logger=logging.getLogger())
 
 
-def test_issue127_attr_read_falls_back_to_module():
+def test_issue127_unresolved_attr_read_emits_edge_to_binding():
     """Reading ``store.dataset`` where ``dataset`` isn't statically known
-    should produce a uses edge to the nearest defined ancestor of the
-    unresolved chain — here, the ``namespace_module`` module itself
-    (since ``store`` is an IMPORTEDITEM with ``defined=False``). Without
-    this fallback, namespace-style modules become invisible in the graph."""
+    should still produce a uses edge to ``namespace_module.store`` (the
+    binding), so the cross-module coupling stays visible. The binding is
+    a defined ``Flavor.NAME`` Node, so the edge lands on it directly —
+    no climb needed. (Pre-#129-prequisite, the binding wasn't a Node and
+    the edge had to fall back to the enclosing module.)"""
     v = _issue127_visitor("namespace_module.py", "consumer.py")
     uses = get_in_dict(v.uses_edges, "consumer.use_attr")
-    get_node(uses, "namespace_module")
+    get_node(uses, "namespace_module.store")
 
 
-def test_issue127_attr_write_falls_back_to_module():
-    """Writing ``store.flag = value`` should also count as coupling to
-    the namespace-style module — same fallback rule, applied through
+def test_issue127_unresolved_attr_write_emits_edge_to_binding():
+    """Writing ``store.flag = value`` should also produce the
+    binding-level edge — same mechanism, applied through
     ``set_attribute`` / the Attribute-in-Store path."""
     v = _issue127_visitor("namespace_module.py", "consumer.py")
     uses = get_in_dict(v.uses_edges, "consumer.write_attr")
-    get_node(uses, "namespace_module")
+    get_node(uses, "namespace_module.store")
 
 
 def test_issue127_chained_access_climbs_to_defined_ancestor():
-    """``store.foo.bar`` — neither ``foo`` nor ``bar`` is statically known,
-    and ``store`` itself is an undefined IMPORTEDITEM. The fallback should
-    climb past every undefined intermediate and emit exactly one edge to
-    the nearest defined ancestor: the ``namespace_module`` module.
-    No edges should point at undefined synthetic ATTRIBUTE nodes — those
-    are invisible in the rendered graph and just noise in ``uses_edges``."""
+    """``store.foo.bar`` — neither ``foo`` nor ``bar`` is statically known.
+    The intermediate access ``store.foo`` produces an undefined synthetic
+    ATTRIBUTE Node, and the outer ``.bar`` access has to climb past it to
+    reach a defined ancestor. After the prequisite to #129, the climb
+    terminates at ``namespace_module.store`` (the binding's NAME Node)
+    rather than at the enclosing module. No edges should point at the
+    undefined ATTRIBUTE intermediates — those are invisible in the
+    rendered graph and just noise in ``uses_edges``."""
     v = _issue127_visitor("namespace_module.py", "chained_consumer.py")
     uses = get_in_dict(v.uses_edges, "chained_consumer.use_chained")
-    get_node(uses, "namespace_module")
+    get_node(uses, "namespace_module.store")
     # No edges to undefined non-wildcard nodes (e.g. namespace_module.store.foo).
     for n in uses:
         assert n.defined or n.namespace is None, (