tscode-kg 0.2.0__py3-none-any.whl

tscode_kg/cli/cmd_viz.py

@@ -0,0 +1,175 @@
+"""
+cli/cmd_viz.py — tscodekg visualizer commands.
+
+  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
+
+_VIZ_EXTRA = 'pip install "tscode-kg[viz]"'
+
+
+@click.command("viz")
+@click.option(
+    "--db",
+    default=".tscodekg/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 TypeScriptKG 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 TypeScriptKG 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.")
+
+
+@click.command("viz3d")
+@click.option(
+    "--db",
+    default=".tscodekg/graph.sqlite",
+    show_default=True,
+    help="SQLite database path.",
+)
+@click.option(
+    "--layout",
+    type=click.Choice(["allium", "funnel"]),
+    default="allium",
+    show_default=True,
+    help=(
+        "3-D layout strategy. "
+        "'allium' renders each module as a Giant Allium plant; "
+        "'funnel' 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 TypeScriptKG 3-D PyVista knowledge-graph visualizer."""
+    db_path = Path(db)
+    if not db_path.exists():
+        raise click.UsageError(
+            f"Database not found: {db_path}\nRun 'tscodekg build' first to index your repository."
+        )
+
+    from tscode_kg.viz3d import launch  # noqa: PLC0415
+
+    launch(
+        db_path=str(db_path),
+        layout_name=layout,
+        width=width,
+        height=height,
+    )
+
+
+@click.command("viz-timeline")
+@click.option(
+    "--snapshots",
+    default=".tscodekg/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 'tscodekg 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 tscode_kg.viz3d_timeline import (  # noqa: PLC0415
+        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)

tscode_kg/cli/main.py

@@ -0,0 +1,56 @@
+"""
+cli/main.py — TypeScriptKG CLI entry point.
+
+Usage::
+
+    tscodekg init --repo /path/to/ts-repo
+    tscodekg build --repo /path/to/ts-repo
+    tscodekg query "authentication middleware"
+    tscodekg pack "error handling" --hop 2
+    tscodekg analyze /path/to/ts-repo
+    tscodekg snapshot save --repo /path/to/ts-repo
+    tscodekg install-hooks --repo /path/to/ts-repo
+    tscodekg mcp --repo /path/to/ts-repo
+"""
+
+from __future__ import annotations
+
+import click
+
+from tscode_kg.cli.cmd_analyze import analyze
+from tscode_kg.cli.cmd_bridges import bridges
+from tscode_kg.cli.cmd_build import build
+from tscode_kg.cli.cmd_centrality import centrality
+from tscode_kg.cli.cmd_explain import explain
+from tscode_kg.cli.cmd_framework_nodes import framework_nodes
+from tscode_kg.cli.cmd_hooks import install_hooks
+from tscode_kg.cli.cmd_init import init
+from tscode_kg.cli.cmd_mcp import mcp_cmd
+from tscode_kg.cli.cmd_model import download_model
+from tscode_kg.cli.cmd_query import pack, query
+from tscode_kg.cli.cmd_snapshot import snapshot
+from tscode_kg.cli.cmd_viz import viz, viz3d, viz_timeline
+
+
+@click.group()
+@click.version_option(package_name="tscode-kg")
+def cli() -> None:
+    """TypeScriptKG — knowledge graph for TypeScript/JavaScript codebases."""
+
+
+cli.add_command(init)
+cli.add_command(build)
+cli.add_command(query)
+cli.add_command(pack)
+cli.add_command(analyze)
+cli.add_command(explain)
+cli.add_command(centrality)
+cli.add_command(bridges)
+cli.add_command(framework_nodes)
+cli.add_command(snapshot)
+cli.add_command(viz)
+cli.add_command(viz3d)
+cli.add_command(viz_timeline, name="viz-timeline")
+cli.add_command(install_hooks)
+cli.add_command(download_model)
+cli.add_command(mcp_cmd, name="mcp")