pycode-kg 0.25.1__tar.gz → 0.26.0__tar.gz

{pycode_kg-0.25.1 → pycode_kg-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.25.1
+Version: 0.26.0
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -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.25.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.26.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.25.1.md](docs/analysis_v0.25.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.26.0.md](docs/analysis_v0.26.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.25.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.26.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.25.1},
+  version   = {0.26.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.25.1 → pycode_kg-0.26.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.25.1-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.26.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.25.1.md](docs/analysis_v0.25.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.26.0.md](docs/analysis_v0.26.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.25.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.26.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.25.1},
+  version   = {0.26.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.25.1 → pycode_kg-0.26.0}/pyproject.toml

@@ -70,7 +70,7 @@ torch = [
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.25.1"
+version = "0.26.0"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"

{pycode_kg-0.25.1 → pycode_kg-0.26.0}/src/pycode_kg/__init__.py

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

{pycode_kg-0.25.1 → pycode_kg-0.26.0}/src/pycode_kg/cli/cmd_snapshot.py

@@ -25,7 +25,12 @@ from pycode_kg.cli.options import sqlite_option
 from pycode_kg.kg import PyCodeKG
 from pycode_kg.pycodekg import DEFAULT_MODEL
 from pycode_kg.pycodekg_thorough_analysis import PyCodeKGAnalyzer
-from pycode_kg.snapshots import SnapshotManager
+from pycode_kg.snapshots import (
+    SnapshotDelta,
+    SnapshotManager,
+    delta_from_dict,
+    metrics_from_dict,
+)
 from pycode_kg.store import GraphStore
 
 
@@ -174,9 +179,10 @@ def save_snapshot(
     click.echo(f"OK Snapshot saved: {snapshot_file}")
     click.echo(f"  Key:     {snapshot_obj.key}")
     click.echo(f"  Version: {snapshot_obj.version}")
-    click.echo(f"  Nodes:   {snapshot_obj.metrics.total_nodes}")
-    click.echo(f"  Edges:   {snapshot_obj.metrics.total_edges}")
-    click.echo(f"  Coverage: {snapshot_obj.metrics.docstring_coverage:.1%}")
+    saved_metrics = metrics_from_dict(snapshot_obj.metrics)
+    click.echo(f"  Nodes:   {saved_metrics.total_nodes}")
+    click.echo(f"  Edges:   {saved_metrics.total_edges}")
+    click.echo(f"  Coverage: {saved_metrics.docstring_coverage:.1%}")
 
 
 @snapshot.command("list")
@@ -270,19 +276,20 @@ def show_snapshot(key: str, snapshots_dir: str | None) -> None:
     click.echo()
 
     click.echo("Metrics:")
-    click.echo(f"  Total Nodes:       {snapshot_obj.metrics.total_nodes}")
-    click.echo(f"  Total Edges:       {snapshot_obj.metrics.total_edges}")
-    click.echo(f"  Meaningful Nodes:  {snapshot_obj.metrics.meaningful_nodes}")
-    click.echo(f"  Docstring Coverage: {snapshot_obj.metrics.docstring_coverage:.1%}")
-    click.echo(f"  Critical Issues:   {snapshot_obj.metrics.critical_issues}")
-    click.echo(f"  Complexity Median: {snapshot_obj.metrics.complexity_median:.2f}")
+    metrics = metrics_from_dict(snapshot_obj.metrics)
+    click.echo(f"  Total Nodes:       {metrics.total_nodes}")
+    click.echo(f"  Total Edges:       {metrics.total_edges}")
+    click.echo(f"  Meaningful Nodes:  {metrics.meaningful_nodes}")
+    click.echo(f"  Docstring Coverage: {metrics.docstring_coverage:.1%}")
+    click.echo(f"  Critical Issues:   {metrics.critical_issues}")
+    click.echo(f"  Complexity Median: {metrics.complexity_median:.2f}")
     click.echo()
 
     click.echo("Node/Edge Breakdown:")
-    for kind, count in sorted(snapshot_obj.metrics.node_counts.items()):
+    for kind, count in sorted(metrics.node_counts.items()):
         click.echo(f"  {kind}: {count}")
     click.echo()
-    for rel, count in sorted(snapshot_obj.metrics.edge_counts.items()):
+    for rel, count in sorted(metrics.edge_counts.items()):
         click.echo(f"  {rel}: {count}")
     click.echo()
 
@@ -296,7 +303,7 @@ def show_snapshot(key: str, snapshots_dir: str | None) -> None:
 
     if snapshot_obj.vs_previous:
         click.echo("Delta vs. Previous:")
-        delta = snapshot_obj.vs_previous
+        delta = delta_from_dict(snapshot_obj.vs_previous) or SnapshotDelta()
         click.echo(f"  Nodes:       {delta.nodes:+d}")
         click.echo(f"  Edges:       {delta.edges:+d}")
         click.echo(f"  Coverage:    {delta.coverage_delta:+.1%}")
@@ -305,7 +312,7 @@ def show_snapshot(key: str, snapshots_dir: str | None) -> None:
 
     if snapshot_obj.vs_baseline:
         click.echo("Delta vs. Baseline:")
-        delta = snapshot_obj.vs_baseline
+        delta = delta_from_dict(snapshot_obj.vs_baseline) or SnapshotDelta()
         click.echo(f"  Nodes:       {delta.nodes:+d}")
         click.echo(f"  Edges:       {delta.edges:+d}")
         click.echo(f"  Coverage:    {delta.coverage_delta:+.1%}")

{pycode_kg-0.25.1 → pycode_kg-0.26.0}/src/pycode_kg/mcp_server.py

@@ -1653,7 +1653,7 @@ def snapshot_show(key: str = "latest") -> str:
     if snapshot is None:
         return json.dumps({"error": f"Snapshot not found for key: {key!r}"})
     out = snapshot.to_dict()
-    out["freshness"] = _snapshot_freshness(snapshot.metrics.total_nodes)
+    out["freshness"] = _snapshot_freshness(snapshot.metrics.get("total_nodes", 0))
     return json.dumps(out, indent=2, ensure_ascii=False)
 
 

{pycode_kg-0.25.1 → pycode_kg-0.26.0}/src/pycode_kg/pycodekg_thorough_analysis.py

@@ -333,12 +333,19 @@ def _has_property_decorator(source_lines: list[str], def_lineno: int) -> bool:
     found, matching ``@property``, ``@cached_property`` (bare or via
     ``functools``), and ``@<name>.setter/getter/deleter``.
 
+    ``def_lineno`` comes from the graph and ``source_lines`` from the file on
+    disk, so the two disagree whenever the graph is stale: a line number past
+    the end of the current file is normal after an edit, not a bug. Treat that
+    as "no property decorator" rather than indexing past the end -- a node
+    wrongly listed as an orphan is a report to re-read, an ``IndexError`` here
+    aborts the whole analysis phase.
+
     :param source_lines: Module source split into lines.
     :param def_lineno: 1-based line number of the ``def`` statement.
     :return: True when a property-family decorator precedes the definition.
     """
     i = def_lineno - 2  # 0-based index of the line above the def
-    while i >= 0:
+    while 0 <= i < len(source_lines):
         stripped = source_lines[i].strip()
         if not stripped.startswith("@"):
             break

pycode_kg-0.26.0/src/pycode_kg/snapshots.py

@@ -0,0 +1,357 @@
+"""
+snapshots.py — Temporal Snapshots of PyCodeKG Metrics
+
+Thin layer over the shared ``kg_utils.snapshots`` module.
+
+``Snapshot``, ``SnapshotManifest`` and ``PruneResult`` are re-exported from
+``kg_utils.snapshots`` unchanged.  A snapshot's ``metrics``, ``vs_previous``
+and ``vs_baseline`` are plain dicts, which is what the shared manager reads
+and writes.
+
+This module adds:
+
+  - ``SnapshotMetrics`` / ``SnapshotDelta`` — domain dataclasses, used as
+    converters by callers that want attribute access.  Convert with
+    ``metrics_from_dict`` / ``metrics_to_dict`` and ``delta_from_dict`` /
+    ``delta_to_dict``; a ``Snapshot`` never holds one.
+  - a ``SnapshotManager`` subclass that sets ``package_name="pycode-kg"``,
+    names the pycode-kg metric fields in ``capture()``, adds
+    ``coverage_delta`` and ``critical_issues_delta`` to deltas, collects
+    per-module node counts from SQLite, and extends a diff with
+    ``module_node_counts_delta``, ``issues_delta`` and ``timestamp``.
+
+Do not subclass ``Snapshot`` here.  A subclass that exposes ``metrics``,
+``vs_previous`` or ``vs_baseline`` as properties breaks every shared manager
+method that reads those fields by attribute, and each one then needs a
+hand-written copy.  One such copy dropped ``snapshot_key``, ``subject`` and
+``tool`` on the way to disk, which shipped in 0.25.0.
+
+Usage
+-----
+>>> from pycode_kg.snapshots import SnapshotManager, metrics_from_dict
+>>> mgr = SnapshotManager(".pycodekg/snapshots")
+>>> snapshot = mgr.capture(version="0.5.1", key="v0.5.1", subject="repo:pycode-kg")
+>>> mgr.save_snapshot(snapshot)
+>>> metrics_from_dict(snapshot.metrics).docstring_coverage
+0.0
+
+Author: Eric G. Suchanek, PhD
+
+License: Elastic 2.0
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Re-export shared base types (backwards-compat public API)
+# ---------------------------------------------------------------------------
+from kg_utils.snapshots import (
+    PruneResult,  # noqa: F401  re-exported
+    Snapshot,  # noqa: F401  re-exported
+    SnapshotManifest,  # noqa: F401  re-exported
+)
+from kg_utils.snapshots import SnapshotManager as _BaseSnapshotManager
+
+__all__ = [
+    "SnapshotMetrics",
+    "SnapshotDelta",
+    "Snapshot",
+    "SnapshotManifest",
+    "SnapshotManager",
+    "PruneResult",
+    "metrics_to_dict",
+    "metrics_from_dict",
+    "delta_to_dict",
+    "delta_from_dict",
+]
+
+
+# ---------------------------------------------------------------------------
+# Domain-specific dataclasses (used by CLI and tests)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SnapshotMetrics:
+    """Core metrics captured in a pycode-kg snapshot."""
+
+    total_nodes: int
+    total_edges: int
+    meaningful_nodes: int
+    docstring_coverage: float  # 0.0 to 1.0
+    node_counts: dict[str, int]
+    edge_counts: dict[str, int]
+    critical_issues: int
+    complexity_median: float  # median fan-in across functions
+    module_node_counts: dict[str, int] = field(default_factory=dict)
+    coverage_documented: int = 0  # nodes with a docstring
+    coverage_total: int = 0  # nodes eligible for docstring coverage
+
+
+@dataclass
+class SnapshotDelta:
+    """Deltas comparing this snapshot to a baseline or previous snapshot."""
+
+    nodes: int = 0
+    edges: int = 0
+    coverage_delta: float = 0.0
+    critical_issues_delta: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Conversion helpers
+# ---------------------------------------------------------------------------
+
+
+def metrics_to_dict(m: SnapshotMetrics) -> dict[str, Any]:
+    """Convert a ``SnapshotMetrics`` dataclass to a plain dict."""
+    return {
+        "total_nodes": m.total_nodes,
+        "total_edges": m.total_edges,
+        "meaningful_nodes": m.meaningful_nodes,
+        "docstring_coverage": m.docstring_coverage,
+        "node_counts": m.node_counts,
+        "edge_counts": m.edge_counts,
+        "critical_issues": m.critical_issues,
+        "complexity_median": m.complexity_median,
+        "module_node_counts": m.module_node_counts,
+        "coverage_documented": m.coverage_documented,
+        "coverage_total": m.coverage_total,
+    }
+
+
+def metrics_from_dict(d: dict[str, Any]) -> SnapshotMetrics:
+    """Reconstruct a ``SnapshotMetrics`` dataclass from a plain dict."""
+    return SnapshotMetrics(
+        total_nodes=int(d.get("total_nodes", 0)),
+        total_edges=int(d.get("total_edges", 0)),
+        meaningful_nodes=int(d.get("meaningful_nodes", 0)),
+        docstring_coverage=float(d.get("docstring_coverage", 0.0)),
+        node_counts=d.get("node_counts", {}),
+        edge_counts=d.get("edge_counts", {}),
+        critical_issues=int(d.get("critical_issues", 0)),
+        complexity_median=float(d.get("complexity_median", 0.0)),
+        module_node_counts=d.get("module_node_counts", {}),
+        coverage_documented=int(d.get("coverage_documented", 0)),
+        coverage_total=int(d.get("coverage_total", 0)),
+    )
+
+
+def delta_to_dict(delta: SnapshotDelta | None) -> dict[str, Any] | None:
+    """Convert a ``SnapshotDelta`` to a plain dict, or return None."""
+    if delta is None:
+        return None
+    return {
+        "nodes": delta.nodes,
+        "edges": delta.edges,
+        "coverage_delta": delta.coverage_delta,
+        "critical_issues_delta": delta.critical_issues_delta,
+    }
+
+
+def delta_from_dict(d: dict[str, Any] | None) -> SnapshotDelta | None:
+    """Reconstruct a ``SnapshotDelta`` from a plain dict, or return None."""
+    if d is None:
+        return None
+    return SnapshotDelta(
+        nodes=int(d.get("nodes", 0)),
+        edges=int(d.get("edges", 0)),
+        coverage_delta=float(d.get("coverage_delta", 0.0)),
+        critical_issues_delta=int(d.get("critical_issues_delta", 0)),
+    )
+
+
+# ---------------------------------------------------------------------------
+# SnapshotManager — pycode-kg specialisation of the shared manager
+# ---------------------------------------------------------------------------
+
+
+class SnapshotManager(_BaseSnapshotManager):
+    """pycode-kg snapshot manager.
+
+    Subclasses the shared ``kg_utils.snapshots.SnapshotManager`` and adds:
+
+    * ``package_name="pycode-kg"`` default for version detection.
+    * A ``capture()`` naming the pycode-kg metric fields (``coverage``,
+      ``critical_issues``, ``complexity_median`` and the coverage numerator
+      and denominator) and collecting per-module node counts.
+    * ``_compute_delta_from_metrics`` extended with ``coverage_delta`` and
+      ``critical_issues_delta``.
+    * ``diff_snapshots`` extended with ``module_node_counts_delta``,
+      ``issues_delta`` and ``timestamp``.
+    * ``_collect_module_node_counts()`` — SQLite per-module node counts.
+
+    Everything else -- saving, loading, listing, pruning, key handling -- is
+    inherited unchanged.  Overriding those to convert between dicts and the
+    domain dataclasses is what this module used to do, and is what let the
+    0.25.0 snapshot key regression through.
+    """
+
+    def __init__(
+        self,
+        snapshots_dir: Path | str,
+        *,
+        db_path: Path | str | None = None,
+        package_name: str = "pycode-kg",
+    ) -> None:
+        """Initialize the manager rooted at ``snapshots_dir``.
+
+        :param snapshots_dir: Directory where snapshot JSON files live; created
+            on first save if it does not exist.
+        :param db_path: PyCodeKG SQLite graph path; required for collecting
+            per-module node counts during ``capture()``. Optional otherwise.
+        :param package_name: Package name used for version detection in saved
+            snapshots. Defaults to ``"pycode-kg"``.
+        """
+        super().__init__(snapshots_dir, package_name=package_name, db_path=db_path)
+
+    # ------------------------------------------------------------------
+    # capture — name the pycode-kg metric fields
+    # ------------------------------------------------------------------
+
+    def capture(  # ty: ignore[invalid-method-override]
+        self,
+        version: str | None = None,
+        branch: str | None = None,
+        graph_stats_dict: dict[str, Any] | None = None,
+        coverage: float = 0.0,
+        coverage_documented: int = 0,
+        coverage_total: int = 0,
+        critical_issues: int = 0,
+        complexity_median: float = 0.0,
+        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.
+
+        Names the pycode-kg metric fields explicitly rather than taking them
+        through ``**extra_metrics``, and adds per-module node counts, then
+        delegates to the shared implementation.
+
+        :param version: Version string (e.g., "0.5.1").
+        :param branch: Git branch name; auto-detected if None.
+        :param graph_stats_dict: Output from ``graph_stats()`` / ``store.stats()``.
+        :param coverage: Docstring coverage fraction (0.0-1.0).
+        :param coverage_documented: Nodes with a non-empty docstring — the
+            numerator behind ``coverage``.  Shown beside the percentage in
+            Snapshot History so a coverage drop caused by adding undocumented
+            nodes reads differently from one caused by removing docstrings.
+        :param coverage_total: Nodes eligible for docstring coverage — the
+            denominator behind ``coverage``.
+        :param critical_issues: Number of critical issues detected.
+        :param complexity_median: Median fan-in across functions.
+        :param hotspots: Top hotspot entries.
+        :param issues: Issue description strings.
+        :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:`~kg_utils.snapshots.Snapshot` (not yet persisted).
+        """
+        return super().capture(
+            version=version,
+            branch=branch,
+            graph_stats_dict=graph_stats_dict,
+            tree_hash=tree_hash,
+            key=key,
+            subject=subject,
+            hotspots=hotspots,
+            issues=issues,
+            docstring_coverage=coverage,
+            coverage_documented=coverage_documented,
+            coverage_total=coverage_total,
+            critical_issues=critical_issues,
+            complexity_median=complexity_median,
+            module_node_counts=self._collect_module_node_counts(),
+        )
+
+    # ------------------------------------------------------------------
+    # diff_snapshots — adds module_node_counts_delta, issues_delta, timestamp
+    # ------------------------------------------------------------------
+
+    def diff_snapshots(self, key_a: str, key_b: str) -> dict[str, Any]:
+        """Compare two snapshots side-by-side.
+
+        Extends the shared diff with ``module_node_counts_delta``,
+        ``issues_delta`` (introduced / resolved issue strings) and the
+        ``timestamp`` of each side, which the CLI prints.
+
+        :param key_a: Earlier snapshot key.
+        :param key_b: Later snapshot key.
+        :return: The shared diff result with the pycode-kg additions.
+        """
+        result = super().diff_snapshots(key_a, key_b)
+        if "error" in result:
+            return result
+
+        for side, key in (("a", key_a), ("b", key_b)):
+            snap = self.load_snapshot(key)
+            if snap is not None:
+                result[side]["timestamp"] = snap.timestamp
+
+        m_a: dict[str, Any] = result["a"]["metrics"]
+        m_b: dict[str, Any] = result["b"]["metrics"]
+        counts_a: dict[str, int] = m_a.get("module_node_counts", {})
+        counts_b: dict[str, int] = m_b.get("module_node_counts", {})
+        result["module_node_counts_delta"] = {
+            mod: counts_b.get(mod, 0) - counts_a.get(mod, 0)
+            for mod in set(counts_a) | set(counts_b)
+            if counts_b.get(mod, 0) != counts_a.get(mod, 0)
+        }
+
+        issues_a = set(result["a"]["issues"])
+        issues_b = set(result["b"]["issues"])
+        result["issues_delta"] = {
+            "introduced": list(issues_b - issues_a),
+            "resolved": list(issues_a - issues_b),
+        }
+        return result
+
+    # ------------------------------------------------------------------
+    # Delta computation — adds coverage_delta and critical_issues_delta
+    # ------------------------------------------------------------------
+
+    def _compute_delta_from_metrics(
+        self, new_m: dict[str, Any], old_m: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Compute delta dict including pycode-kg specific fields."""
+        return {
+            "nodes": new_m.get("total_nodes", 0) - old_m.get("total_nodes", 0),
+            "edges": new_m.get("total_edges", 0) - old_m.get("total_edges", 0),
+            "coverage_delta": (
+                new_m.get("docstring_coverage", 0.0) - old_m.get("docstring_coverage", 0.0)
+            ),
+            "critical_issues_delta": (
+                new_m.get("critical_issues", 0) - old_m.get("critical_issues", 0)
+            ),
+        }
+
+    # ------------------------------------------------------------------
+    # SQLite per-module node counts
+    # ------------------------------------------------------------------
+
+    def _collect_module_node_counts(self) -> dict[str, int]:
+        """Query SQLite for per-module node counts.
+
+        :return: Dict mapping ``module_path`` to node count, or ``{}`` if the
+                 database is unavailable or the query fails.
+        """
+        if not self.db_path or not self.db_path.exists():
+            return {}
+        try:
+            with sqlite3.connect(self.db_path) as conn:
+                rows = conn.execute(
+                    "SELECT module_path, COUNT(*) FROM nodes GROUP BY module_path"
+                ).fetchall()
+            return {row[0]: row[1] for row in rows if row[0]}
+        except sqlite3.Error:
+            return {}