pycode-kg 0.23.1__tar.gz → 0.24.1__tar.gz

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.23.1
+Version: 0.24.1
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -21,8 +21,8 @@ Provides-Extra: viz3d
 Requires-Dist: PyQt5 (>=5.15.0) ; extra == "all"
 Requires-Dist: PyQt5 (>=5.15.0) ; extra == "viz3d"
 Requires-Dist: click (>=8.1.0,<9)
-Requires-Dist: kgmodule-utils[semantic,viz3d] (>=0.13.1)
-Requires-Dist: kgmodule-utils[viz3d-render] (>=0.12.1) ; extra == "viz3d"
+Requires-Dist: kgmodule-utils[semantic,viz3d] (>=0.18.1)
+Requires-Dist: kgmodule-utils[viz3d-qt,viz3d-render] (>=0.18.1) ; extra == "viz3d"
 Requires-Dist: markdown (>=3.6) ; extra == "all"
 Requires-Dist: markdown (>=3.6) ; extra == "viz3d"
 Requires-Dist: mcp (>=1.0.0,<2)
@@ -38,8 +38,8 @@ Requires-Dist: pyvis (>=0.3.2) ; extra == "viz"
 Requires-Dist: pyvista (>=0.44.0) ; extra == "all"
 Requires-Dist: pyvistaqt (>=0.11.0) ; extra == "all"
 Requires-Dist: pyvistaqt (>=0.11.0) ; extra == "viz3d"
-Requires-Dist: quiltwright (>=0.4.0) ; extra == "all"
-Requires-Dist: quiltwright (>=0.4.0) ; extra == "viz3d"
+Requires-Dist: quiltwright (>=0.8.0) ; extra == "all"
+Requires-Dist: quiltwright (>=0.8.0) ; extra == "viz3d"
 Requires-Dist: rich (>=14.3.3,<15)
 Requires-Dist: sentence-transformers (>=5.4.1)
 Requires-Dist: sqlite-vec (==0.1.9)
@@ -60,7 +60,7 @@ Description-Content-Type: text/markdown
 
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
-[![Version](https://img.shields.io/badge/version-0.23.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.24.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
 [![CI](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
@@ -255,7 +255,7 @@ src/pycode_kg/
 └── viz3d_timeline.py                # Metric history timeline
 ```
 
-The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.23.1.md](docs/analysis_v0.23.1.md), produced (of course) by `pycodekg analyze` against this very repo.
+The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.24.1.md](docs/analysis_v0.24.1.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -282,13 +282,13 @@ If you use PyCodeKG in your research or project, please cite it:
 
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
 
-> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.23.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.24.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
 
 ```bibtex
 @software{suchanek_pycode_kg,
   author    = {Suchanek, Eric G.},
   title     = {{PyCodeKG}: A Knowledge Graph for Python Codebases},
-  version   = {0.23.1},
+  version   = {0.24.1},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/README.md

@@ -5,7 +5,7 @@
 
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
-[![Version](https://img.shields.io/badge/version-0.23.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.24.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
 [![CI](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
@@ -200,7 +200,7 @@ src/pycode_kg/
 └── viz3d_timeline.py                # Metric history timeline
 ```
 
-The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.23.1.md](docs/analysis_v0.23.1.md), produced (of course) by `pycodekg analyze` against this very repo.
+The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.24.1.md](docs/analysis_v0.24.1.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -227,13 +227,13 @@ If you use PyCodeKG in your research or project, please cite it:
 
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
 
-> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.23.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.24.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
 
 ```bibtex
 @software{suchanek_pycode_kg,
   author    = {Suchanek, Eric G.},
   title     = {{PyCodeKG}: A Knowledge Graph for Python Codebases},
-  version   = {0.23.1},
+  version   = {0.24.1},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/pyproject.toml

@@ -1,7 +1,6 @@
 # pyproject.toml — PyCodeKG package configuration (PEP 621)
 #
 # Author: Eric G. Suchanek, PhD
-# Last Revision: 2026-08-15
 #
 # Build system : Poetry 2.x with PEP 621 [project] table
 #
@@ -71,7 +70,7 @@ torch = [
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.23.1"
+version = "0.24.1"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"
@@ -137,12 +136,26 @@ dependencies = [
     # Its only dependency is numpy, which `[semantic]` already pulls, so it adds
     # nothing to the install — it just declares what layout3d actually imports.
     # Unlike `[viz]`, there is no pyvis to leak into a bare install.
-    # Floor is 0.13.1 rather than 0.12.1 because that is the release which
-    # stops SnapshotManager writing absolute paths into snapshot JSON. This
-    # package ships `pycodekg snapshot save`, and those snapshots get committed
-    # to the user's repo — against an older kgmodule-utils the command writes
-    # their home directory and username into version control.
-    "kgmodule-utils[semantic,viz3d]>=0.13.1",
+    # Floor is 0.13.x rather than 0.12.1 because that is where SnapshotManager
+    # stops writing absolute paths into snapshot JSON. This package ships
+    # `pycodekg snapshot save`, and those snapshots get committed to the
+    # user's repo — against an older kgmodule-utils the command writes their
+    # home directory and username into version control.
+    #
+    # 0.13.2 specifically, never 0.13.1: that release carried the path fix but
+    # also made `repo_root` a read-only property, which breaks every subclass
+    # that assigns it. 0.13.2 keeps the fix and restores the plain attribute.
+    #
+    # 0.15.0 because the `viz3d` extra below needs kg_utils.viz3d.qt, and this
+    # repo's own rule is one floor per package — a lower floor here would leave
+    # a reader working out which constraint actually binds. Nothing in the core
+    # install needs 0.15.0 functionally; it is a superset of 0.14.0.
+    #
+    # 0.18.1 because resolve_symbols() only reads the receiver_class metadata
+    # this repo's visitor writes as of 0.24.1 -- against 0.18.0 the stubs are
+    # tagged correctly but the tag is silently ignored, so resolution stays on
+    # the old untyped trailing-name match with no error to say so.
+    "kgmodule-utils[semantic,viz3d]>=0.18.1",
 ]
 
 [project.optional-dependencies]
@@ -159,12 +172,22 @@ viz3d = [
     # and smooth_paths live there. The main dependency above stays on plain
     # [viz3d] (numpy only) so the nine repos that take pycode-kg do not acquire
     # VTK for a layout import; rendering stays opt-in, here.
-    "kgmodule-utils[viz3d-render]>=0.12.1",
+    # Same floor as the core declaration above — one package, one floor, so a
+    # reader does not have to work out which constraint actually binds.
+    # [viz3d-qt] (new in 0.15.0) adds kg_utils.viz3d.qt — the Qt machinery a
+    # viewer needs to cast: the render lifecycle and cast_scene_to_looking_glass,
+    # which this module's "Cast to LG" button now drives instead of open-coding
+    # the four-step build/render/write/cast itself. It subsumes [viz3d-render]
+    # (it declares pyvista too), but both are named so the dependency reads as
+    # what it is rather than as a side effect.
+    "kgmodule-utils[viz3d-render,viz3d-qt]>=0.18.1",
     "pyvistaqt>=0.11.0",
     "trame-vtk>=2.0.0",
     # Looking Glass quilts. 0.4.0 supplies depth_report() and widened
-    # requires-python to <3.14, which retires the old marker gate.
-    "quiltwright>=0.4.0",
+    # requires-python to <3.14, which retires the old marker gate. 0.6.0 adds
+    # QuiltSpec.scaled(), which replaces the tile-grid rounding this repo used
+    # to open-code, and save_and_cast_quilt() underneath the SDK cast helper.
+    "quiltwright>=0.8.0",
 ]
 
 # Cross-KG sibling packages (doc-kg, pycode-kg, agent-kg, kg-rag) are NOT
@@ -189,7 +212,7 @@ all = [
     "pyvis>=0.3.2",
     "pyvista>=0.44.0",
     "pyvistaqt>=0.11.0",
-    "quiltwright>=0.4.0",
+    "quiltwright>=0.8.0",
     "streamlit>=1.56.0",
     "trame-vtk>=2.0.0",
 ]
@@ -231,7 +254,7 @@ ty = ">=0.0.41"
 optional = true
 
 [tool.poetry.group.kg.dependencies]
-doc-kg = ">=0.21.2"
+doc-kg = ">=0.22.0"
 
 [project.urls]
 Homepage = "https://github.com/Flux-Frontiers/pycode_kg"

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/src/pycode_kg/__init__.py

@@ -36,7 +36,7 @@ Author: Eric G. Suchanek, PhD
 License: Elastic 2.0
 """
 
-__version__ = "0.23.1"
+__version__ = "0.24.1"
 __author__ = "Eric G. Suchanek, PhD"
 
 # Low-level primitives (locked v0 contract)

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/src/pycode_kg/analysis/bridge.py

@@ -4,7 +4,6 @@ Measures module interaction complexity: how many unique modules each module call
 For well-modularized codebases, identifies orchestrator and hub modules.
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-08-15 00:46:18
 License: Elastic 2.0
 """
 

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/src/pycode_kg/analysis/centrality.py

@@ -12,7 +12,6 @@ Public API:
     - :func:`aggregate_module_scores` — roll node scores up to module level.
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-08-15 00:46:18
 
 License: Elastic 2.0
 """

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/src/pycode_kg/analysis/framework_detector.py

@@ -3,7 +3,6 @@ Framework Detector for PyCodeKG.
 Identifies repo-defining abstractions using centrality and cross-module signals.
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-08-15 00:46:18
 License: Elastic 2.0
 """
 

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/src/pycode_kg/architecture.py

@@ -610,11 +610,11 @@ class ArchitectureAnalyzer:
         readme = self.repo_root / "README.md"
         if readme.exists():
             try:
-                with open(readme) as f:
+                with open(readme, encoding="utf-8") as f:
                     for line in f:
                         if line.startswith("#"):
                             return line.lstrip("#").strip()
-            except OSError:
+            except (OSError, UnicodeDecodeError):
                 pass
         return "PyCodeKG Architecture"
 

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/src/pycode_kg/cli/cmd_hooks.py

@@ -6,7 +6,6 @@ CLI command for installing PyCodeKG git hooks:
   install-hooks — install the pre-commit snapshot hook into .git/hooks/
 
   Author: Eric G. Suchanek, PhD
-  Last Revision: 2026-08-14 22:51:58
 
 Author: Eric G. Suchanek, PhD
 
@@ -29,10 +28,33 @@ from pycode_kg.cli.main import cli
 
 _PRE_COMMIT_HOOK = """\
 #!/usr/bin/env bash
-# PyCodeKG pre-commit hook — runs quality checks first, then rebuilds the local
-# index and captures a metrics snapshot.
+# PyCodeKG pre-commit hook — runs quality checks. The index rebuild and metrics
+# snapshot are opt-in and OFF by default; see "Why snapshots are off" below.
 # Installed by: pycodekg install-hooks
-# Skip with: PYCODEKG_SKIP_SNAPSHOT=1 git commit ...
+#
+#   PYCODEKG_SNAPSHOT=1 git commit ...        opt in to a per-commit snapshot
+#   PYCODEKG_SKIP_SNAPSHOT=1 git commit ...   force snapshots off (wins)
+#
+# Note that PYCODEKG_SKIP_SNAPSHOT no longer skips the quality checks. It used
+# to short-circuit the whole hook, so a variable named "skip snapshot" also
+# silently skipped ruff, ty and pytest. It now gates only what it names.
+#
+# Why snapshots are off by default (2026-08-18)
+# ---------------------------------------------
+# A per-commit snapshot records `git write-tree` and is then itself staged into
+# that same commit. Staging changes the index, so the recorded hash can never
+# equal the tree it claims to describe — and manifest.json carries a
+# `last_update` timestamp, so the `git add` is never a no-op. The drift is
+# guaranteed by construction, not caused by formatting, and reordering does not
+# fix it: the `git add` lands after the hash either way.
+#
+# An audit of 605 snapshots across 29 fleet manifests found 63 (10.4%) keyed to
+# a tree any commit actually has. `snapshot diff` between adjacent entries has
+# therefore been comparing states that never existed.
+#
+# The fix is to snapshot at release, keyed on the tag rather than on an
+# ephemeral pre-commit tree. See kgrag_priv/docs/SNAPSHOT_STRATEGY.md. Until
+# that lands, this hook runs quality checks only.
 #
 # Order matters, and it is deliberately checks-then-index:
 #
@@ -46,8 +68,6 @@ _PRE_COMMIT_HOOK = """\
 #     commit that ruff/ty/pytest is about to reject.
 set -euo pipefail
 
-[ "${PYCODEKG_SKIP_SNAPSHOT:-0}" = "1" ] && exit 0
-
 REPO_ROOT="$(git rev-parse --show-toplevel)"
 
 cd "$REPO_ROOT"
@@ -63,12 +83,27 @@ elif command -v pre-commit &>/dev/null; then
     pre-commit run || exit 1
 fi
 
-# Capture the tree hash now that the checks have passed and nothing further
-# will modify the working tree — this keys the snapshot to the content that is
-# actually about to be committed.
+# ---------------------------------------------------------------------------
+# Opt-in index rebuild + snapshot. Everything below is skipped unless
+# PYCODEKG_SNAPSHOT=1 is set, and is skipped regardless if
+# PYCODEKG_SKIP_SNAPSHOT=1.
+# ---------------------------------------------------------------------------
+[ "${PYCODEKG_SNAPSHOT:-0}" = "1" ] || exit 0
+[ "${PYCODEKG_SKIP_SNAPSHOT:-0}" = "1" ] && exit 0
+
+# Captured after the checks so nothing further modifies the working tree. Note
+# the caveat above: this still cannot match the committed tree, because the
+# `git add` below changes the index after this point.
 TREE_HASH=$(git write-tree)
 BRANCH=$(git rev-parse --abbrev-ref HEAD)
 
+# Snapshots are default-branch history. On any other branch, stop here —
+# feature-branch commits (and the PRs/CI built from them) stay free of
+# generated snapshot files, and skip the 60-90s rebuild along the way.
+DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || true)
+DEFAULT_BRANCH="${DEFAULT_BRANCH#origin/}"
+[ "$BRANCH" != "${DEFAULT_BRANCH:-main}" ] && exit 0
+
 # Rebuild the local index to keep it in sync with staged content.
 "$REPO_ROOT/.venv/bin/pycodekg" build --repo "$REPO_ROOT" || exit 1
 
@@ -104,11 +139,14 @@ exit 0
 def install_hooks(repo: str, force: bool) -> None:
     """Install the PyCodeKG pre-commit git hook.
 
-    After installation, before each commit:
+    After installation, before each commit on the default branch:
       1. Rebuilds the local PyCodeKG index (full wipe)
       2. Captures a metrics snapshot, keyed by tree hash
       3. Stages the snapshot directory
 
+    On any other branch the quality checks still run but the rebuild and
+    snapshot are skipped, so feature-branch commits carry no generated files.
+
     This keeps the index in sync and ensures snapshots reflect the state of
     the knowledge graph at commit time.  The hook only ever touches its own
     repository — sibling KG repos install their own hooks.
@@ -137,5 +175,8 @@ def install_hooks(repo: str, force: bool) -> None:
     hook_path.chmod(mode)
 
     click.echo(f"OK Installed pre-commit hook: {hook_path}")
-    click.echo("  Snapshots will be captured automatically before each commit.")
+    click.echo("  Quality checks run on every commit.")
+    click.echo("  Snapshots are OFF by default - see kgrag_priv/docs/SNAPSHOT_STRATEGY.md.")
+    click.echo("  Opt in with:  PYCODEKG_SNAPSHOT=1 git commit ...")
+    click.echo("  Force off:    PYCODEKG_SKIP_SNAPSHOT=1 git commit ...")
     click.echo("  Run 'pycodekg build' first if you haven't built the graph yet.")

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/src/pycode_kg/cli/cmd_init.py

@@ -253,6 +253,8 @@ def init(
 
                 docstring_cov = analysis.get("docstring_coverage", {})
                 coverage = docstring_cov.get("coverage_pct", 0.0) / 100.0 if docstring_cov else 0.0
+                coverage_documented = docstring_cov.get("with_doc", 0)
+                coverage_total = docstring_cov.get("total", 0)
                 critical_issues = len(analysis.get("issues", []))
 
                 fn_metrics = analysis.get("function_metrics", {})
@@ -276,6 +278,8 @@ def init(
                 branch=branch,
                 graph_stats_dict=stats,
                 coverage=coverage,
+                coverage_documented=coverage_documented,
+                coverage_total=coverage_total,
                 critical_issues=critical_issues,
                 complexity_median=complexity_median,
                 hotspots=hotspots,

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/src/pycode_kg/cli/cmd_quilt.py

@@ -12,7 +12,6 @@ in :mod:`quiltwright`.  What this command owns is the part quiltwright cannot
 know: which graph to grow and how to frame it.
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-08-14
 
 License: Elastic 2.0
 """

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/src/pycode_kg/cli/cmd_snapshot.py

@@ -111,6 +111,8 @@ def save_snapshot(
         # Extract metrics from analysis results
         docstring_cov = analysis.get("docstring_coverage", {})
         coverage = docstring_cov.get("coverage_pct", 0.0) / 100.0 if docstring_cov else 0.0
+        coverage_documented = docstring_cov.get("with_doc", 0)
+        coverage_total = docstring_cov.get("total", 0)
         issue_strings = analysis.get("issues", [])
         critical_issues = len(issue_strings)
 
@@ -140,6 +142,8 @@ def save_snapshot(
         branch=branch,
         graph_stats_dict=stats,
         coverage=coverage,
+        coverage_documented=coverage_documented,
+        coverage_total=coverage_total,
         critical_issues=critical_issues,
         complexity_median=complexity_median,
         hotspots=hotspots,

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/src/pycode_kg/module/extractor.py

@@ -118,6 +118,7 @@ class PyCodeKGExtractor(KGExtractor):
                 lineno=n.lineno,
                 end_lineno=n.end_lineno,
                 docstring=n.docstring or "",
+                metadata={"receiver_class": n.receiver_class} if n.receiver_class else {},
             )
 
         for e in edges:

{pycode_kg-0.23.1 → pycode_kg-0.24.1}/src/pycode_kg/pycodekg.py

@@ -23,7 +23,6 @@ No persistence, no embeddings, no LLMs—just pure AST extraction. Integration w
 vector databases and semantic search happens downstream.
 
 Author: Eric G. Suchanek, PhD
-Last Revision: 2026-08-15 00:46:18
 
 License: Elastic 2.0
 """
@@ -62,6 +61,11 @@ class Node:
     :param lineno: Starting line number
     :param end_lineno: Ending line number (if available)
     :param docstring: Extracted docstring (may be None)
+    :param receiver_class: For a dotted call stub (``kind == "symbol"``), the
+        class name resolved from the receiver's parameter or local variable
+        annotation, if any — e.g. ``"Plotter"`` for a call site
+        ``plotter.render()`` where ``plotter: pv.Plotter``. ``None`` when the
+        receiver has no known annotation, or the node isn't a call stub.
     """
 
     id: str
@@ -72,6 +76,7 @@ class Node:
     lineno: int | None
     end_lineno: int | None
     docstring: str | None
+    receiver_class: str | None = None
 
 
 @dataclass(frozen=True)
@@ -212,6 +217,91 @@ def _owner_id(
     return module_locals[module].get(fn.name)
 
 
+def _own_scope_nodes(node: ast.AST) -> Iterable[ast.AST]:
+    """Yield descendants of *node*, not descending into nested function/class scopes.
+
+    A nested ``def``/``class``/``lambda`` introduces its own name binding for
+    any local it declares, so an ``AnnAssign`` inside one does not describe a
+    name in *node*'s own scope.
+
+    :param node: Root AST node (typically a function body).
+    :return: Iterator over descendants in *node*'s own scope.
+    """
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda | ast.ClassDef):
+            continue
+        yield child
+        yield from _own_scope_nodes(child)
+
+
+def _annotation_class_name(expr: ast.AST) -> str | None:
+    """Extract a class name from a type annotation, unwrapping ``Optional`` shapes.
+
+    ``X | None`` (PEP 604) and ``Optional[X]``/``typing.Optional[X]`` are the
+    common "this local starts as ``None``, gets assigned later" shape --
+    exactly the pattern a loop-accumulated match object or lazily-built
+    instance tends to carry. Neither is a class name on its own, so both are
+    unwrapped to the non-``None`` member before falling back to
+    :func:`expr_to_name`, which does not know about either.
+
+    :param expr: The annotation expression.
+    :return: Dotted class name, or ``None`` if it can't be determined.
+    """
+    if isinstance(expr, ast.BinOp) and isinstance(expr.op, ast.BitOr):
+        for side in (expr.left, expr.right):
+            if isinstance(side, ast.Constant) and side.value is None:
+                continue
+            resolved = _annotation_class_name(side)
+            if resolved:
+                return resolved
+        return None
+
+    if isinstance(expr, ast.Subscript):
+        base = expr_to_name(expr.value)
+        if base and base.rsplit(".", 1)[-1] == "Optional":
+            return _annotation_class_name(expr.slice)
+        return expr_to_name(expr)
+
+    if isinstance(expr, ast.Constant) and expr.value is None:
+        return None
+
+    return expr_to_name(expr)
+
+
+def _receiver_annotation(
+    fn: ast.FunctionDef | ast.AsyncFunctionDef, receiver_name: str
+) -> str | None:
+    """Resolve a call receiver's class name from its parameter or local annotation.
+
+    Looks at *fn*'s own parameters, then any ``AnnAssign`` in *fn*'s own body
+    (see :func:`_own_scope_nodes`), for a name matching *receiver_name*. The
+    first annotation found wins -- no reassignment or narrowing is tracked,
+    matching the conservative stance the rest of this module takes toward
+    ambiguity.
+
+    :param fn: Enclosing function or async function definition.
+    :param receiver_name: Bare name of the call's receiver, e.g. ``"plotter"``.
+    :return: The annotation's last dotted segment (e.g. ``"Plotter"`` for a
+        ``pv.Plotter`` annotation, or ``"Match"`` for ``re.Match | None``), or
+        ``None`` if *receiver_name* has no known annotation.
+    """
+    for a in (*fn.args.posonlyargs, *fn.args.args, *fn.args.kwonlyargs):
+        if a.arg == receiver_name and a.annotation is not None:
+            cls = _annotation_class_name(a.annotation)
+            return cls.rsplit(".", 1)[-1] if cls else None
+
+    for stmt in _own_scope_nodes(fn):
+        if (
+            isinstance(stmt, ast.AnnAssign)
+            and isinstance(stmt.target, ast.Name)
+            and stmt.target.id == receiver_name
+        ):
+            cls = _annotation_class_name(stmt.annotation)
+            return cls.rsplit(".", 1)[-1] if cls else None
+
+    return None
+
+
 # ============================================================================
 # Core extraction logic
 # ============================================================================
@@ -467,6 +557,8 @@ def extract_repo(
             if not callee:
                 continue
 
+            receiver_class: str | None = None
+
             # resolution rules (LOCKED)
             if callee in module_locals[module]:
                 dst_id = module_locals[module][callee]
@@ -481,6 +573,15 @@ def extract_repo(
                 dst_id = module_class_methods[module].get(meth) or f"sym:{callee}"
             else:
                 dst_id = f"sym:{callee}"
+                # A plain local variable/parameter receiver, not self/cls and
+                # not a module-level import alias -- the one case an
+                # annotation can disambiguate. self./cls. never reach here.
+                if (
+                    isinstance(n.func, ast.Attribute)
+                    and isinstance(n.func.value, ast.Name)
+                    and n.func.value.id not in ("self", "cls")
+                ):
+                    receiver_class = _receiver_annotation(fn, n.func.value.id)
 
             if dst_id.startswith("sym:"):
                 nodes.setdefault(
@@ -494,6 +595,7 @@ def extract_repo(
                         None,
                         None,
                         None,
+                        receiver_class,
                     ),
                 )