pycode-kg 0.16.0__py3-none-any.whl

pycode_kg/cli/cmd_snapshot.py

@@ -0,0 +1,421 @@
+"""
+cmd_snapshot.py
+
+Click subcommands for managing temporal snapshots of PyCodeKG metrics:
+
+  snapshot save   — capture current metrics and save snapshot
+  snapshot list   — show all snapshots with key metrics
+  snapshot show   — display full snapshot details
+  snapshot diff   — compare two snapshots
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from pycode_kg.cli.main import cli
+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.store import GraphStore
+
+
+@cli.group("snapshot")
+def snapshot() -> None:
+    """Manage temporal snapshots of PyCodeKG metrics."""
+    pass
+
+
+@snapshot.command("save")
+@click.argument("version", metavar="VERSION", default="", required=False)
+@click.option(
+    "--repo",
+    default=".",
+    type=click.Path(exists=True),
+    show_default=True,
+    help="Repository root path.",
+)
+@sqlite_option
+@click.option(
+    "--snapshots-dir",
+    default=None,
+    type=click.Path(),
+    help="Snapshots directory (default: .pycodekg/snapshots).",
+)
+@click.option(
+    "--branch",
+    default=None,
+    type=str,
+    help="Branch name; auto-detected if not provided.",
+)
+@click.option(
+    "--tree-hash",
+    default="",
+    type=str,
+    help="Git tree hash; auto-detected if not provided.",
+)
+def save_snapshot(
+    version: str | None,
+    repo: str,
+    sqlite: str,
+    snapshots_dir: str | None,
+    branch: str | None,
+    tree_hash: 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.
+
+    Snapshots are stored in .pycodekg/snapshots/{tree_hash}.json, with a
+    manifest.json tracking all snapshots and their metrics.
+
+    Example:
+        pycodekg snapshot save 0.5.1 --repo .
+    """
+    repo_root = Path(repo).resolve()
+    db_path = Path(sqlite)
+    snapshots_path = (
+        Path(snapshots_dir).resolve() if snapshots_dir else (repo_root / ".pycodekg" / "snapshots")
+    )
+
+    # Load graph stats
+    store = GraphStore(db_path)
+    try:
+        stats = store.stats()
+    finally:
+        store.close()
+
+    # Load PyCodeKG and get docstring coverage + complexity metrics
+    kg = PyCodeKG(
+        repo_root=repo_root,
+        db_path=db_path,
+        lancedb_dir=repo_root / ".pycodekg" / "lancedb",
+        model=DEFAULT_MODEL,
+    )
+    snap_mgr = SnapshotManager(snapshots_path, db_path=db_path)
+    try:
+        analyzer = PyCodeKGAnalyzer(kg, snapshot_mgr=snap_mgr)
+        analysis = analyzer.run_analysis()
+
+        # 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
+        issue_strings = analysis.get("issues", [])
+        critical_issues = len(issue_strings)
+
+        # Compile hotspots from function metrics
+        fn_metrics = analysis.get("function_metrics", {})
+        hotspots = [
+            {
+                "name": name,
+                "callers": metrics.get("fan_in", 0),
+                "callees": metrics.get("fan_out", 0),
+                "risk_level": metrics.get("risk_level", "low"),
+            }
+            for name, metrics in list(fn_metrics.items())[:10]
+        ]
+
+        # Calculate complexity median from function metrics
+        fan_ins = [m.get("fan_in", 0) for m in fn_metrics.values()]
+        complexity_median = (
+            (sorted(fan_ins)[len(fan_ins) // 2] if len(fan_ins) > 0 else 0.0) if fan_ins else 0.0
+        )
+    finally:
+        kg.close()
+
+    # Capture snapshot
+    snapshot_obj = snap_mgr.capture(
+        version=version,
+        branch=branch,
+        graph_stats_dict=stats,
+        coverage=coverage,
+        critical_issues=critical_issues,
+        complexity_median=complexity_median,
+        hotspots=hotspots,
+        issues=issue_strings,
+        tree_hash=tree_hash,
+    )
+
+    snapshot_file = snap_mgr.save_snapshot(snapshot_obj)
+    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%}")
+
+
+@snapshot.command("list")
+@click.option(
+    "--snapshots-dir",
+    default=None,
+    type=click.Path(exists=True),
+    help="Snapshots directory (default: .pycodekg/snapshots).",
+)
+@click.option(
+    "--limit",
+    type=int,
+    default=None,
+    help="Max snapshots to show.",
+)
+@click.option(
+    "--json",
+    "output_json",
+    is_flag=True,
+    help="Output as JSON.",
+)
+def list_snapshots(snapshots_dir: str | None, limit: int | None, output_json: bool) -> None:
+    """
+    List all temporal snapshots in reverse chronological order.
+
+    Shows key, timestamp, version, and key metrics (nodes, edges, coverage)
+    for each snapshot.
+    """
+    snapshots_path = (
+        Path(snapshots_dir).resolve() if snapshots_dir else (Path.cwd() / ".pycodekg" / "snapshots")
+    )
+    mgr = SnapshotManager(snapshots_path)
+    snapshots = mgr.list_snapshots(limit=limit)
+
+    if not snapshots:
+        click.echo("No snapshots found.")
+        return
+
+    if output_json:
+        click.echo(json.dumps(snapshots, indent=2))
+    else:
+        # Table output
+        click.echo(
+            f"{'Key':<12} {'Timestamp':<20} {'Branch':<12} {'Version':<8} {'Nodes':<6} {'Edges':<6} {'Coverage':<9}"
+        )
+        click.echo("-" * 85)
+        for snap in snapshots:
+            key = snap["key"][:12]
+            # Parse ISO timestamp and format as YYYY-MM-DD HH:MM
+            ts = snap["timestamp"]
+            ts_display = ts[:16].replace("T", " ") if ts else "unknown"[:20]
+            branch = snap["branch"][:12]
+            version = snap["version"][:8]
+            nodes = snap["metrics"]["total_nodes"]
+            edges = snap["metrics"]["total_edges"]
+            coverage = snap["metrics"]["docstring_coverage"]
+            click.echo(
+                f"{key:<12} {ts_display:<20} {branch:<12} {version:<8} {nodes:<6} {edges:<6} {coverage:>6.1%}"
+            )
+
+
+@snapshot.command("show")
+@click.argument("key", metavar="KEY")
+@click.option(
+    "--snapshots-dir",
+    default=None,
+    type=click.Path(exists=True),
+    help="Snapshots directory (default: .pycodekg/snapshots).",
+)
+def show_snapshot(key: str, snapshots_dir: str | None) -> None:
+    """
+    Display full details for a single snapshot by key (tree hash).
+
+    Shows all metrics, hotspots, and deltas vs. previous and baseline snapshots.
+    """
+    snapshots_path = (
+        Path(snapshots_dir).resolve() if snapshots_dir else (Path.cwd() / ".pycodekg" / "snapshots")
+    )
+    mgr = SnapshotManager(snapshots_path)
+    snapshot_obj = mgr.load_snapshot(key)
+
+    if not snapshot_obj:
+        click.echo(f"Snapshot not found: {key}", err=True)
+        raise click.Abort()
+
+    # Print snapshot details
+    click.echo(f"Key:       {snapshot_obj.key}")
+    click.echo(f"Branch:    {snapshot_obj.branch}")
+    click.echo(f"Timestamp: {snapshot_obj.timestamp}")
+    click.echo(f"Version:   {snapshot_obj.version}")
+    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}")
+    click.echo()
+
+    click.echo("Node/Edge Breakdown:")
+    for kind, count in sorted(snapshot_obj.metrics.node_counts.items()):
+        click.echo(f"  {kind}: {count}")
+    click.echo()
+    for rel, count in sorted(snapshot_obj.metrics.edge_counts.items()):
+        click.echo(f"  {rel}: {count}")
+    click.echo()
+
+    if snapshot_obj.hotspots:
+        click.echo("Top Hotspots (Fan-In):")
+        for i, hotspot in enumerate(snapshot_obj.hotspots[:5], 1):
+            name = hotspot.get("name", "unknown")
+            callers = hotspot.get("callers", 0)
+            click.echo(f"  {i}. {name} ({callers} callers)")
+        click.echo()
+
+    if snapshot_obj.vs_previous:
+        click.echo("Delta vs. Previous:")
+        delta = snapshot_obj.vs_previous
+        click.echo(f"  Nodes:       {delta.nodes:+d}")
+        click.echo(f"  Edges:       {delta.edges:+d}")
+        click.echo(f"  Coverage:    {delta.coverage_delta:+.1%}")
+        click.echo(f"  Issues:      {delta.critical_issues_delta:+d}")
+        click.echo()
+
+    if snapshot_obj.vs_baseline:
+        click.echo("Delta vs. Baseline:")
+        delta = snapshot_obj.vs_baseline
+        click.echo(f"  Nodes:       {delta.nodes:+d}")
+        click.echo(f"  Edges:       {delta.edges:+d}")
+        click.echo(f"  Coverage:    {delta.coverage_delta:+.1%}")
+        click.echo(f"  Issues:      {delta.critical_issues_delta:+d}")
+
+
+@snapshot.command("prune")
+@click.option(
+    "--snapshots-dir",
+    default=None,
+    type=click.Path(),
+    help="Snapshots directory (default: .pycodekg/snapshots).",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Show what would be removed without deleting anything.",
+)
+def prune_snapshots(snapshots_dir: str | None, dry_run: bool) -> None:
+    """
+    Remove vestigial snapshots that carry no new metric information.
+
+    Cleans up three categories:
+
+    \b
+    1. Metric-duplicates — interior snapshots with unchanged metrics.
+    2. Broken entries — manifest entries whose JSON file is missing.
+    3. Orphaned files — JSON files on disk not referenced by the manifest.
+
+    The oldest (baseline) and newest (latest) snapshots are always kept.
+
+    Example:
+        pycodekg snapshot prune --dry-run
+        pycodekg snapshot prune
+    """
+    snapshots_path = (
+        Path(snapshots_dir).resolve() if snapshots_dir else (Path.cwd() / ".pycodekg" / "snapshots")
+    )
+    mgr = SnapshotManager(snapshots_path)
+    result = mgr.prune_snapshots(dry_run=dry_run)
+
+    prefix = "[dry-run] " if dry_run else ""
+    if result.total_cleaned == 0:
+        click.echo("Nothing to prune.")
+        return
+
+    if result.removed:
+        click.echo(f"{prefix}Metric-duplicates removed: {len(result.removed)}")
+        for key in result.removed:
+            click.echo(f"  - {key}")
+    if result.broken_entries:
+        click.echo(f"{prefix}Broken manifest entries removed: {len(result.broken_entries)}")
+        for key in result.broken_entries:
+            click.echo(f"  - {key}")
+    if result.orphaned_files:
+        click.echo(f"{prefix}Orphaned JSON files removed: {len(result.orphaned_files)}")
+        for fname in result.orphaned_files:
+            click.echo(f"  - {fname}")
+
+    action = "would be" if dry_run else "were"
+    click.echo(f"\nTotal: {result.total_cleaned} item(s) {action} cleaned.")
+
+
+@snapshot.command("diff")
+@click.argument("key_a", metavar="KEY_A")
+@click.argument("key_b", metavar="KEY_B")
+@click.option(
+    "--snapshots-dir",
+    default=None,
+    type=click.Path(exists=True),
+    help="Snapshots directory (default: .pycodekg/snapshots).",
+)
+@click.option(
+    "--json",
+    "output_json",
+    is_flag=True,
+    help="Output as JSON.",
+)
+def diff_snapshots(key_a: str, key_b: str, snapshots_dir: str | None, output_json: bool) -> None:
+    """
+    Compare two snapshots side-by-side.
+
+    Shows metrics from both snapshots and computed deltas (B - A).
+
+    Example:
+        pycodekg snapshot diff 660e4f0a 3487ed5b
+    """
+    snapshots_path = (
+        Path(snapshots_dir).resolve() if snapshots_dir else (Path.cwd() / ".pycodekg" / "snapshots")
+    )
+    mgr = SnapshotManager(snapshots_path)
+    diff_result = mgr.diff_snapshots(key_a, key_b)
+
+    if "error" in diff_result:
+        click.echo(f"Error: {diff_result['error']}", err=True)
+        raise click.Abort()
+
+    if output_json:
+        click.echo(json.dumps(diff_result, indent=2))
+    else:
+        # Table output
+        a = diff_result["a"]
+        b = diff_result["b"]
+
+        click.echo(f"Comparing {a['key'][:10]} vs {b['key'][:10]}")
+        click.echo()
+        click.echo(f"{'Metric':<20} {'A':<12} {'B':<12} {'Δ':<12}")
+        click.echo("-" * 56)
+
+        metrics_a = a["metrics"]
+        metrics_b = b["metrics"]
+
+        for key in ["total_nodes", "total_edges", "meaningful_nodes"]:
+            val_a = metrics_a[key]
+            val_b = metrics_b[key]
+            delta_val = val_b - val_a
+            click.echo(f"{key:<20} {val_a:<12} {val_b:<12} {delta_val:+d}")
+
+        cov_a = metrics_a["docstring_coverage"]
+        cov_b = metrics_b["docstring_coverage"]
+        cov_delta = cov_b - cov_a
+        click.echo(f"{'docstring_coverage':<20} {cov_a:<12.1%} {cov_b:<12.1%} {cov_delta:+.1%}")
+
+        issues_a = metrics_a["critical_issues"]
+        issues_b = metrics_b["critical_issues"]
+        issues_delta = issues_b - issues_a
+        click.echo(f"{'critical_issues':<20} {issues_a:<12} {issues_b:<12} {issues_delta:+d}")
+
+        issues_data = diff_result.get("issues_delta", {})
+        introduced = issues_data.get("introduced", [])
+        resolved = issues_data.get("resolved", [])
+
+        if introduced or resolved:
+            click.echo()
+            click.echo("Issue Changes:")
+            for issue in introduced:
+                click.echo(f"  [+] {issue}")
+            for issue in resolved:
+                click.echo(f"  [-] {issue}")

pycode_kg/cli/cmd_viz.py

@@ -0,0 +1,180 @@
+"""
+cmd_viz.py
+
+Click subcommands for launching PyCodeKG visualizers:
+
+  viz          — Streamlit-based interactive graph explorer
+  viz3d        — PyVista/PyQt5 3-D interactive knowledge-graph visualizer
+  viz-timeline — Interactive temporal metrics visualization from snapshots
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+
+from pycode_kg.cli.main import cli
+
+_VIZ_EXTRA = 'pip install "pycode-kg[viz]"'
+
+
+@cli.command("viz")
+@click.option(
+    "--db",
+    default=".pycodekg/graph.sqlite",
+    show_default=True,
+    help="SQLite database path.",
+)
+@click.option(
+    "--port",
+    default="8500",
+    show_default=True,
+    help="Streamlit server port.",
+)
+@click.option(
+    "--no-browser",
+    is_flag=True,
+    help="Do not open a browser window automatically.",
+)
+def viz(db: str, port: str, no_browser: bool) -> None:
+    """Launch the PyCodeKG Streamlit visualizer."""
+    if importlib.util.find_spec("streamlit") is None:
+        raise click.UsageError(
+            f"streamlit is not installed. Install viz dependencies with:\n  {_VIZ_EXTRA}"
+        )
+
+    app_path = Path(__file__).parent.parent / "app.py"
+
+    if not app_path.exists():
+        click.echo(f"ERROR: Could not find app.py at {app_path}", err=True)
+        sys.exit(1)
+
+    cmd = [
+        sys.executable,
+        "-m",
+        "streamlit",
+        "run",
+        str(app_path),
+        "--server.port",
+        str(port),
+        "--",
+        "--db",
+        db,
+    ]
+    if no_browser:
+        cmd[5:5] = ["--server.headless", "true"]
+
+    click.echo(f"Launching PyCodeKG Explorer on http://localhost:{port}")
+    click.echo(f"  app   : {app_path}")
+    click.echo(f"  db    : {db}")
+    click.echo("  Press Ctrl+C to stop.\n")
+
+    try:
+        subprocess.run(cmd, check=True)
+    except KeyboardInterrupt:
+        click.echo("\nStopped.")
+
+
+@cli.command("viz3d")
+@click.option(
+    "--db",
+    default=".pycodekg/graph.sqlite",
+    show_default=True,
+    help="SQLite database path.",
+)
+@click.option(
+    "--layout",
+    type=click.Choice(["allium", "cake"]),
+    default="allium",
+    show_default=True,
+    help=(
+        "3-D layout strategy. "
+        "'allium' renders each module as a Giant Allium plant; "
+        "'cake' stratifies nodes by kind across Z layers."
+    ),
+)
+@click.option(
+    "--width",
+    type=int,
+    default=1400,
+    show_default=True,
+    help="Window width in pixels.",
+)
+@click.option(
+    "--height",
+    type=int,
+    default=900,
+    show_default=True,
+    help="Window height in pixels.",
+)
+def viz3d(db: str, layout: str, width: int, height: int) -> None:
+    """Launch the PyCodeKG 3-D PyVista knowledge-graph visualizer."""
+    db_path = Path(db)
+    if not db_path.exists():
+        raise click.UsageError(
+            f"Database not found: {db_path}\n"
+            "Run 'pycodekg build-sqlite' first to index your repository."
+        )
+
+    from pycode_kg.viz3d import launch  # pylint: disable=import-outside-toplevel
+
+    launch(
+        db_path=str(db_path),
+        layout_name=layout,
+        width=width,
+        height=height,
+    )
+
+
+@cli.command("viz-timeline")
+@click.option(
+    "--snapshots",
+    default=".pycodekg/snapshots",
+    show_default=True,
+    help="Snapshots directory path.",
+)
+@click.option(
+    "--type",
+    type=click.Choice(["2d", "3d"]),
+    default="2d",
+    show_default=True,
+    help="Visualization type: 2d (subplots) or 3d (scatter plot).",
+)
+def viz_timeline(snapshots: str, type: str) -> None:
+    """Display temporal metrics evolution across commits."""
+    snapshots_path = Path(snapshots)
+    if not snapshots_path.exists():
+        raise click.UsageError(
+            f"Snapshots directory not found: {snapshots_path}\n"
+            "Run 'pycodekg snapshot save' first to capture snapshots."
+        )
+
+    if importlib.util.find_spec("plotly") is None:
+        raise click.UsageError(
+            f"plotly is not installed. Install viz dependencies with:\n  {_VIZ_EXTRA}"
+        )
+
+    from pycode_kg.viz3d_timeline import (  # pylint: disable=import-outside-toplevel
+        create_3d_timeline_figure,
+        create_timeline_figure,
+        display_timeline_summary,
+    )
+
+    # Display text summary
+    summary = display_timeline_summary(snapshots_path)
+    click.echo(summary)
+
+    # Create and display visualization
+    if type == "3d":
+        fig = create_3d_timeline_figure(snapshots_path)
+    else:
+        fig = create_timeline_figure(snapshots_path)
+
+    try:
+        fig.show()
+    except (OSError, AttributeError, ImportError) as e:
+        click.echo(f"Could not display visualization: {e}", err=True)

pycode_kg/cli/main.py

@@ -0,0 +1,23 @@
+"""
+Root Click group for the PyCodeKG CLI.
+
+Usage::
+
+    python -m pycode_kg --help
+    python -m pycode_kg --version
+"""
+
+import importlib.metadata
+
+import click
+
+
+@click.group()
+@click.version_option(version=importlib.metadata.version("pycode-kg"))
+def cli():
+    """PyCodeKG — knowledge graph tools for Python codebases."""
+    pass
+
+
+if __name__ == "__main__":
+    cli()

pycode_kg/cli/options.py

@@ -0,0 +1,63 @@
+"""
+Shared Click option decorators for PyCodeKG CLI commands.
+
+Each symbol is a reusable decorator factory that can be stacked onto any
+Click command to provide consistent option names, defaults, and help text::
+
+    @cli.command()
+    @sqlite_option
+    @lancedb_option
+    def my_command(sqlite, lancedb):
+        ...
+"""
+
+import click
+
+from pycode_kg.pycodekg import DEFAULT_MODEL
+
+sqlite_option = click.option(
+    "--sqlite",
+    default=".pycodekg/graph.sqlite",
+    type=click.Path(),
+    show_default=True,
+    help="SQLite database path.",
+)
+
+lancedb_option = click.option(
+    "--lancedb",
+    default=".pycodekg/lancedb",
+    type=click.Path(),
+    show_default=True,
+    help="LanceDB directory path.",
+)
+
+model_option = click.option(
+    "--model",
+    default=DEFAULT_MODEL,
+    show_default=True,
+    help="Sentence-transformer model name.",
+)
+
+repo_option = click.option(
+    "--repo",
+    default=".",
+    type=click.Path(exists=True, file_okay=False),
+    show_default=True,
+    help="Repository root directory.",
+)
+
+include_option = click.option(
+    "--include-dir",
+    multiple=True,
+    help="Top-level directory names to include in indexing. Can be used multiple times. "
+    "When none are specified, all directories are indexed. "
+    "Also reads [tool.pycodekg].include from pyproject.toml.",
+)
+
+exclude_option = click.option(
+    "--exclude-dir",
+    multiple=True,
+    help="Directory names to exclude at every depth during indexing. Can be used multiple times. "
+    "E.g. --exclude-dir tests --exclude-dir benchmarks. "
+    "Also reads [tool.pycodekg].exclude from pyproject.toml.",
+)