pycode-kg 0.24.0__tar.gz → 0.25.0__tar.gz

{pycode_kg-0.24.0 → pycode_kg-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.24.0
+Version: 0.25.0
 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.18.0)
-Requires-Dist: kgmodule-utils[viz3d-qt,viz3d-render] (>=0.18.0) ; extra == "viz3d"
+Requires-Dist: kgmodule-utils[semantic,viz3d] (>=0.19.0)
+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)
@@ -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.24.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.25.0-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.24.0.md](docs/analysis_v0.24.0.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.25.0.md](docs/analysis_v0.25.0.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.24.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.25.0) [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.24.0},
+  version   = {0.25.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},
@@ -312,5 +312,5 @@ If you use PyCodeKG in your research or project, please cite it:
 
 ---
 
-*Built for Python developers and AI agents that work alongside them — egs · Last updated August 2026*
+*Built for Python developers and AI agents that work alongside them — egs*
 

{pycode_kg-0.24.0 → pycode_kg-0.25.0}/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.24.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.25.0-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.24.0.md](docs/analysis_v0.24.0.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.25.0.md](docs/analysis_v0.25.0.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.24.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.25.0) [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.24.0},
+  version   = {0.25.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},
@@ -257,4 +257,4 @@ If you use PyCodeKG in your research or project, please cite it:
 
 ---
 
-*Built for Python developers and AI agents that work alongside them — egs · Last updated August 2026*
+*Built for Python developers and AI agents that work alongside them — egs*

{pycode_kg-0.24.0 → pycode_kg-0.25.0}/pyproject.toml

@@ -70,7 +70,7 @@ torch = [
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.24.0"
+version = "0.25.0"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"
@@ -150,7 +150,12 @@ dependencies = [
     # 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.
-    "kgmodule-utils[semantic,viz3d]>=0.18.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.19.0",
 ]
 
 [project.optional-dependencies]
@@ -175,7 +180,7 @@ viz3d = [
     # 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.0",
+    "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

{pycode_kg-0.24.0 → pycode_kg-0.25.0}/src/pycode_kg/__init__.py

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

{pycode_kg-0.24.0 → pycode_kg-0.25.0}/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.24.0 → pycode_kg-0.25.0}/src/pycode_kg/cli/cmd_snapshot.py

@@ -61,7 +61,13 @@ def snapshot() -> None:
     "--tree-hash",
     default="",
     type=str,
-    help="Git tree hash; auto-detected if not provided.",
+    help="Git tree hash, recorded as provenance; auto-detected if not provided.",
+)
+@click.option(
+    "--subject",
+    default="",
+    type=str,
+    help="What was measured, e.g. 'repo:pycode-kg' or 'corpus:pepys'.",
 )
 def save_snapshot(
     version: str | None,
@@ -70,16 +76,25 @@ def save_snapshot(
     snapshots_dir: str | None,
     branch: str | None,
     tree_hash: str,
+    subject: str,
 ) -> None:
     """
     Capture current PyCodeKG metrics and save as a temporal snapshot.
 
     Reads graph statistics, docstring coverage, and complexity metrics from
-    the SQLite graph, then saves a snapshot tagged with the given VERSION.
-    The tree hash is auto-detected from git when not provided.
+    the SQLite graph, then saves a snapshot keyed on VERSION.
+
+    **Pass VERSION explicitly at release time.** An omitted VERSION is
+    auto-detected from the installed pycode-kg package, which names the
+    measuring tool rather than the repo being measured -- in any repo other
+    than this one that is the wrong number, so it is recorded as the version
+    but never used as the key. Omitting it keys the snapshot on a UTC
+    timestamp instead, which is the right answer for a corpus.
 
-    Snapshots are stored in .pycodekg/snapshots/{tree_hash}.json, with a
-    manifest.json tracking all snapshots and their metrics.
+    Snapshots are stored in .pycodekg/snapshots/{key}.json, with a
+    manifest.json tracking all snapshots and their metrics. The git tree hash
+    is recorded as provenance and is no longer the key: it is read before
+    `git add` stages the snapshot, so it names a tree that is never committed.
 
     Example:
         pycodekg snapshot save 0.5.1 --repo .
@@ -149,6 +164,10 @@ def save_snapshot(
         hotspots=hotspots,
         issues=issue_strings,
         tree_hash=tree_hash,
+        # An explicit VERSION is a release tag and becomes the key. An
+        # auto-detected one is the measuring tool's version and must not be.
+        key=version or "",
+        subject=subject or "",
     )
 
     snapshot_file = snap_mgr.save_snapshot(snapshot_obj)

{pycode_kg-0.24.0 → pycode_kg-0.25.0}/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.24.0 → pycode_kg-0.25.0}/src/pycode_kg/pycodekg.py

@@ -61,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
@@ -71,6 +76,7 @@ class Node:
     lineno: int | None
     end_lineno: int | None
     docstring: str | None
+    receiver_class: str | None = None
 
 
 @dataclass(frozen=True)
@@ -211,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
 # ============================================================================
@@ -466,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]
@@ -480,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(
@@ -493,6 +595,7 @@ def extract_repo(
                         None,
                         None,
                         None,
+                        receiver_class,
                     ),
                 )
 

{pycode_kg-0.24.0 → pycode_kg-0.25.0}/src/pycode_kg/pycodekg_thorough_analysis.py

@@ -43,10 +43,12 @@ from collections.abc import Callable
 from dataclasses import asdict, dataclass
 from pathlib import Path
 
+from rich.columns import Columns
 from rich.console import Console
 from rich.panel import Panel
 from rich.table import Table
 
+from pycode_kg.pycodekg import iter_python_files
 from pycode_kg.report import render_markdown
 from pycode_kg.resolution import BUILTIN_METHOD_NAMES
 from pycode_kg.snapshots import SnapshotManager
@@ -160,6 +162,33 @@ _PROTOCOL_ATTRS_FALLBACK = frozenset(
 )
 _protocol_attrs_cache: frozenset[str] | None = None
 
+# Console labels for the scalar baseline metrics, in display order.  Keys
+# absent here still render (under their raw name) so a new stat can never be
+# dropped silently.
+_STAT_LABELS = {
+    "total_nodes": "Total nodes",
+    "meaningful_nodes": "Meaningful nodes",
+    "total_edges": "Total edges",
+    "docstring_coverage": "Docstring coverage",
+    "snapshot_count": "Snapshots",
+    "vector_backend": "Vector backend",
+    "db_path": "Database",
+}
+
+# Rendered as their own breakout tables instead: the two ``*_counts`` dicts
+# print as raw reprs, and the per-kind ``*_count`` scalars only repeat what
+# ``node_counts`` already says.
+_STAT_BREAKOUT = frozenset(
+    {
+        "node_counts",
+        "edge_counts",
+        "module_count",
+        "class_count",
+        "function_count",
+        "method_count",
+    }
+)
+
 
 def _protocol_attr_names() -> frozenset[str]:
     """Attribute names of the framework base classes the KG SDK dispatches on.
@@ -229,10 +258,11 @@ def _declared_export_names(repo_root: Path) -> set[str]:
     import ast as _ast  # noqa: PLC0415
 
     names: set[str] = set()
-    for py_path in repo_root.rglob("*.py"):
+    for py_path in iter_python_files(repo_root):
         try:
             tree = _ast.parse(py_path.read_text(encoding="utf-8"))
-        except (OSError, SyntaxError):
+        except (OSError, SyntaxError, UnicodeDecodeError) as e:
+            logger.debug(f"Skipping {py_path} while scanning for declared exports: {e}")
             continue
         for node in _ast.walk(tree):
             if (
@@ -729,9 +759,11 @@ class PyCodeKGAnalyzer:
             text: str | None = None
             repo_root = getattr(self.kg, "repo_root", None)
             if repo_root:
+                src_path = Path(repo_root) / module_path
                 try:
-                    text = (Path(repo_root) / module_path).read_text(encoding="utf-8")
-                except OSError:
+                    text = src_path.read_text(encoding="utf-8")
+                except (OSError, UnicodeDecodeError) as e:
+                    logger.debug(f"Could not read {src_path}: {e}")
                     text = None
             self._source_cache[module_path] = text
         return self._source_cache[module_path]
@@ -767,7 +799,8 @@ class PyCodeKGAnalyzer:
         for path in sorted(tests_dir.rglob("*.py")):
             try:
                 chunks.append(path.read_text(encoding="utf-8"))
-            except OSError:
+            except (OSError, UnicodeDecodeError) as e:
+                logger.debug(f"Skipping {path} while building tests corpus: {e}")
                 continue
         return "\n".join(chunks)
 
@@ -2493,16 +2526,31 @@ class PyCodeKGAnalyzer:
         self.console.print()
 
         # Stats table
-        stats_table = Table(title="Baseline Metrics", show_header=True)
+        stats_table = Table(title="Baseline Metrics", show_header=True, title_style="bold")
         stats_table.add_column("Metric", style="dim")
         stats_table.add_column("Value")
 
-        for key, value in self.stats.items():
-            stats_table.add_row(key, str(value))
+        ordered = [k for k in _STAT_LABELS if k in self.stats]
+        extra = [k for k in self.stats if k not in _STAT_LABELS and k not in _STAT_BREAKOUT]
+        for key in (*ordered, *extra):
+            stats_table.add_row(_STAT_LABELS.get(key, key), _format_stat(key, self.stats[key]))
 
         self.console.print(stats_table)
         self.console.print()
 
+        # Node/edge distributions, side by side rather than as raw dict reprs
+        breakouts = [
+            _counts_table(title, label, counts)
+            for title, label, counts in (
+                ("Nodes by Kind", "Kind", self.stats.get("node_counts") or {}),
+                ("Edges by Relation", "Relation", self.stats.get("edge_counts") or {}),
+            )
+            if counts
+        ]
+        if breakouts:
+            self.console.print(Columns(breakouts, padding=(0, 4)))
+            self.console.print()
+
         # Most called functions
         if self.function_metrics:
             calls_table = Table(title="Most Called Functions (Fan-In)", show_header=True)
@@ -2537,6 +2585,42 @@ class PyCodeKGAnalyzer:
             self.console.print()
 
 
+def _format_stat(key: str, value: object) -> str:
+    """Render one baseline-metric value for console display.
+
+    :param key: Stat key, used to recognize the ratio-valued metrics.
+    :param value: Raw value from ``PyCodeKG.stats()``.
+    :return: Display string -- percentage for coverage ratios, thousands
+        separators for counts, ``str()`` otherwise.
+    """
+    if key == "docstring_coverage" and isinstance(value, int | float):
+        return f"{value:.1%}"
+    if isinstance(value, bool):
+        return str(value)
+    if isinstance(value, int):
+        return f"{value:,}"
+    return str(value)
+
+
+def _counts_table(title: str, label: str, counts: dict[str, int]) -> Table:
+    """Build a breakdown table for a ``{name: count}`` stat, largest first.
+
+    ``node_counts``/``edge_counts`` arrive as dicts; printing them through
+    ``str()`` dumps a raw Python repr that wraps across the value column.
+
+    :param title: Table title, e.g. ``"Nodes by Kind"``.
+    :param label: Header for the name column, e.g. ``"Kind"``.
+    :param counts: Mapping of name to count.
+    :return: Rich table sorted by count descending, then name.
+    """
+    table = Table(title=title, show_header=True, title_style="bold")
+    table.add_column(label, style="cyan")
+    table.add_column("Count", justify="right")
+    for name, count in sorted(counts.items(), key=lambda kv: (-kv[1], kv[0])):
+        table.add_row(str(name), f"{count:,}")
+    return table
+
+
 def _default_report_name(repo_root: Path) -> str:
     """Derive a timestamped default markdown report path under ``analysis/``.
 

{pycode_kg-0.24.0 → pycode_kg-0.25.0}/src/pycode_kg/report.py

@@ -21,6 +21,11 @@ from pathlib import Path
 
 from pycode_kg.render import md_table
 
+# The code relationships worth reporting.  RESOLVES_TO is deliberately
+# absent: it links a ``sym:`` stub to the definition it resolved to, which is
+# the graph's own bookkeeping rather than a relationship between two pieces of
+# code.  Because it is excluded, this table does not sum to ``total_edges`` --
+# the renderer states the difference rather than leaving it unaccounted for.
 _EDGE_RELS = ("CALLS", "CONTAINS", "IMPORTS", "ATTR_ACCESS", "INHERITS")
 
 # A single depth-3 chain carries no signal — show the section only once the
@@ -179,6 +184,15 @@ def render_markdown(analyzer, *, metadata: str = "", elapsed_seconds: float | No
         [(rel, edge_counts.get(rel, 0)) for rel in _EDGE_RELS],
         aligns="lr",
     )
+    shown = sum(edge_counts.get(rel, 0) for rel in _EDGE_RELS)
+    excluded = stats.get("total_edges", shown) - shown
+    if excluded > 0:
+        out += [
+            "",
+            f"_Excludes {excluded:,} `RESOLVES_TO` edges: internal symbol-stub "
+            "resolutions, not relationships between two pieces of code. This "
+            "table therefore does not sum to Total Edges._",
+        ]
     rule()
 
     # ── Fan-In Ranking ───────────────────────────────────────────────────

{pycode_kg-0.24.0 → pycode_kg-0.25.0}/src/pycode_kg/snapshots.py

@@ -181,6 +181,12 @@ class Snapshot(_BaseSnapshot):
     The underlying ``metrics``, ``vs_previous``, and ``vs_baseline`` fields
     remain plain dicts on disk; the properties are view-only adapters.
 
+    ``to_dict`` is **not** overridden. The base reads those three fields out of
+    ``__dict__`` rather than through these properties (kgmodule-utils 0.19.0),
+    which is what the override used to exist for -- and the base is also what
+    supplies the current key scheme, so an override here would silently keep
+    writing tree-hash keys.
+
     Implementation note
     -------------------
     Python dataclass fields are stored in ``__dict__`` under their field name.
@@ -225,20 +231,6 @@ class Snapshot(_BaseSnapshot):
         else:
             self.__dict__["vs_baseline"] = value
 
-    def to_dict(self) -> dict[str, Any]:
-        """Convert snapshot to a JSON-serializable dictionary."""
-        return {
-            "key": self.tree_hash,
-            "branch": self.branch,
-            "timestamp": self.timestamp,
-            "version": self.version,
-            "metrics": self.__dict__["metrics"],
-            "hotspots": self.hotspots,
-            "issues": self.issues,
-            "vs_previous": self.__dict__["vs_previous"],
-            "vs_baseline": self.__dict__["vs_baseline"],
-        }
-
     @staticmethod
     def from_dict(data: dict[str, Any]) -> Snapshot:  # type: ignore[override]
         """Reconstruct a pycode-kg ``Snapshot`` from a dictionary."""
@@ -302,6 +294,8 @@ class SnapshotManager(_BaseSnapshotManager):
         hotspots: list[dict[str, Any]] | None = None,
         issues: list[str] | None = None,
         tree_hash: str = "",
+        key: str = "",
+        subject: str = "",
     ) -> Snapshot:
         """Capture a pycode-kg snapshot.
 
@@ -324,7 +318,11 @@ class SnapshotManager(_BaseSnapshotManager):
         :param complexity_median: Median fan-in across functions.
         :param hotspots: Top hotspot entries.
         :param issues: Issue description strings.
-        :param tree_hash: Git tree hash; auto-detected if not provided.
+        :param tree_hash: Git tree hash, recorded as provenance; auto-detected
+            if not provided. It is not the snapshot's key.
+        :param key: Snapshot identifier. Pass the release tag at release time;
+            omit it and the base assigns a UTC timestamp.
+        :param subject: What was measured, e.g. ``repo:pycode-kg``.
         :return: New :class:`Snapshot` instance (not yet persisted).
         """
         module_node_counts = self._collect_module_node_counts()
@@ -334,6 +332,8 @@ class SnapshotManager(_BaseSnapshotManager):
             branch=branch,
             graph_stats_dict=graph_stats_dict,
             tree_hash=tree_hash,
+            key=key,
+            subject=subject,
             hotspots=hotspots,
             issues=issues,
             docstring_coverage=coverage,