pycode-kg 0.16.0__py3-none-any.whl

pycode_kg/cli/cmd_analyze.py

@@ -0,0 +1,96 @@
+"""
+cmd_analyze.py
+
+Click subcommand for running a thorough codebase analysis:
+
+  analyze  — run PyCodeKGAnalyzer, emit a Markdown report (JSON optional via --json)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from pycode_kg.cli.main import cli
+from pycode_kg.cli.options import exclude_option, include_option
+from pycode_kg.config import load_exclude_dirs, load_include_dirs
+from pycode_kg.pycodekg_thorough_analysis import main as run_analysis
+
+
+@cli.command("analyze")
+@click.argument("repo_root", default=".", required=False)
+@click.option(
+    "--db",
+    default=None,
+    type=click.Path(),
+    help="SQLite knowledge graph path (default: <repo>/.pycodekg/graph.sqlite).",
+)
+@click.option(
+    "--lancedb",
+    default=None,
+    type=click.Path(),
+    help="LanceDB vector index directory (default: <repo>/.pycodekg/lancedb).",
+)
+@click.option(
+    "--output",
+    "-o",
+    default=None,
+    type=click.Path(),
+    help="Markdown report output path (default: <repo>_analysis_<YYYYMMDD>.md).",
+)
+@click.option(
+    "--json",
+    "-j",
+    "json_path",
+    default=None,
+    type=click.Path(),
+    help="Write JSON snapshot to this path (omit to skip JSON output).",
+)
+@click.option(
+    "--quiet",
+    "-q",
+    is_flag=True,
+    help="Suppress the Rich console summary table.",
+)
+@click.option(
+    "--write-centrality",
+    is_flag=True,
+    help="Persist SIR centrality scores to the centrality_scores table in the SQLite graph.",
+)
+@include_option
+@exclude_option
+def analyze(
+    repo_root: str,
+    db: str | None,
+    lancedb: str | None,
+    output: str | None,
+    json_path: str | None,
+    quiet: bool,
+    write_centrality: bool,
+    include_dir: tuple[str, ...],
+    exclude_dir: tuple[str, ...],
+) -> None:
+    """Run a thorough analysis of a Python repository.
+
+    Analyzes complexity, hotspots, docstring coverage, circular dependencies,
+    and other health signals. Outputs a Markdown report. Pass --json PATH to
+    also write a JSON snapshot.
+    """
+    # Merge pyproject.toml config with CLI flags
+    repo_path = Path(repo_root).resolve()
+    include = load_include_dirs(repo_path) | set(include_dir)
+    exclude = load_exclude_dirs(repo_path) | set(exclude_dir)
+
+    # Run thorough analysis
+    run_analysis(
+        repo_root=repo_root,
+        db_path=db,
+        lancedb_path=lancedb,
+        report_path=output,
+        json_path=json_path,
+        quiet=quiet,
+        include=include if include else None,
+        exclude=exclude if exclude else None,
+        persist_centrality=write_centrality,
+    )

pycode_kg/cli/cmd_architecture.py

@@ -0,0 +1,150 @@
+"""
+cmd_architecture.py
+
+Click subcommand for generating coherent architecture descriptions:
+
+  architecture  — analyze codebase architecture, emit Markdown or JSON descriptions
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import subprocess
+from pathlib import Path
+
+import click
+
+from pycode_kg.architecture import ArchitectureAnalyzer
+from pycode_kg.cli.main import cli
+from pycode_kg.store import GraphStore
+
+
+@cli.command("architecture")
+@click.argument("repo_root", default=".", required=False)
+@click.option(
+    "--db",
+    default=None,
+    type=click.Path(),
+    help="SQLite knowledge graph path (default: <repo>/.pycodekg/graph.sqlite).",
+)
+@click.option(
+    "--markdown",
+    "-m",
+    "markdown_path",
+    default=None,
+    type=click.Path(),
+    help="Save architecture description as Markdown.",
+)
+@click.option(
+    "--json",
+    "-j",
+    "json_path",
+    default=None,
+    type=click.Path(),
+    help="Save architecture description as JSON (infographic-ready).",
+)
+@click.option(
+    "--analysis",
+    type=click.Path(),
+    default=None,
+    help="Path to thorough analysis JSON (from 'pycodekg analyze') to incorporate.",
+)
+@click.option(
+    "--load-latest",
+    is_flag=True,
+    help="Auto-load latest thorough analysis from ~/.claude/pycodekg_analysis_latest.json.",
+)
+def architecture(
+    repo_root: str,
+    db: str | None,
+    markdown_path: str | None,
+    json_path: str | None,
+    analysis: str | None,
+    load_latest: bool,
+) -> None:
+    """Generate a coherent architecture description of a Python repository.
+
+    Produces human-readable Markdown and machine-friendly JSON suitable for
+    infographics. Can incorporate insights from 'pycodekg analyze' output.
+
+    If neither --markdown nor --json is specified, prints Markdown to console.
+    """
+    repo_path = Path(repo_root).resolve()
+    db_path = Path(db or repo_path / ".pycodekg" / "graph.sqlite")
+
+    if not db_path.exists():
+        raise click.UsageError(
+            f"SQLite graph not found: {db_path}\nRun 'pycodekg build' first to index your repository."
+        )
+
+    store = GraphStore(db_path)
+    try:
+        # Get version and commit for provenance
+        try:
+            commit = subprocess.check_output(
+                ["git", "rev-parse", "HEAD"], text=True, stderr=subprocess.DEVNULL
+            ).strip()[:10]
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            commit = "unknown"
+
+        # Try to get version from package
+        version = "unknown"
+        try:
+            version = importlib.metadata.version("pycode-kg")
+        except importlib.metadata.PackageNotFoundError:
+            pass
+
+        analyzer = ArchitectureAnalyzer(store, repo_path, version=version, commit=commit)
+
+        # Load thorough analysis - try in order: explicit path, auto-load latest, skip
+        import json  # pylint: disable=import-outside-toplevel
+
+        analysis_loaded = False
+        if analysis:
+            try:
+                with open(analysis) as f:
+                    analysis_data = json.load(f)
+                analyzer.incorporate_thorough_analysis(analysis_data)
+                click.echo(f"OK Loaded analysis: {analysis}")
+                analysis_loaded = True
+            except (FileNotFoundError, json.JSONDecodeError) as e:
+                click.echo(f"Warning: Could not load analysis file: {e}", err=True)
+
+        elif load_latest:
+            latest_path = Path.home() / ".claude" / "pycodekg_analysis_latest.json"
+            if latest_path.exists():
+                try:
+                    with open(latest_path) as f:
+                        analysis_data = json.load(f)
+                    analyzer.incorporate_thorough_analysis(analysis_data)
+                    click.echo("OK Auto-loaded latest analysis")
+                    analysis_loaded = True
+                except json.JSONDecodeError as e:
+                    click.echo(f"Warning: Could not parse analysis file: {e}", err=True)
+
+        if not analysis_loaded:
+            click.echo(
+                "Tip: Run 'pycodekg analyze --json' then 'pycodekg architecture --load-latest'"
+            )
+            click.echo("    for richer architectural insights.")
+
+        # Generate outputs
+        if markdown_path:
+            arch_md = analyzer.analyze_to_markdown()
+            with open(markdown_path, "w") as f:
+                f.write(arch_md)
+            click.echo(f"OK Architecture Markdown: {markdown_path}")
+
+        if json_path:
+            arch_json = analyzer.analyze_to_json()
+            with open(json_path, "w") as f:
+                f.write(arch_json)
+            click.echo(f"OK Architecture JSON: {json_path}")
+
+        if not markdown_path and not json_path:
+            # Print to console
+            arch_md = analyzer.analyze_to_markdown()
+            click.echo(arch_md)
+
+    finally:
+        store.close()

pycode_kg/cli/cmd_bridges.py

@@ -0,0 +1,26 @@
+"""
+CLI command for bridge centrality in PyCodeKG.
+"""
+
+import argparse
+
+from pycode_kg.analysis.bridge import compute_bridge_centrality
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Show top bridge modules by betweenness centrality."
+    )
+    parser.add_argument("--db", default="pycodekg.sqlite", help="Path to PyCodeKG SQLite DB")
+    parser.add_argument("--top", type=int, default=25, help="Number of top bridges to show")
+    parser.add_argument("--no-imports", action="store_true", help="Ignore IMPORTS edges")
+    args = parser.parse_args()
+    bridges = compute_bridge_centrality(
+        kind="module",
+        include_imports=not args.no_imports,
+        top=args.top,
+        db_path=args.db,
+    )
+    print(f"Top {args.top} bridge modules:")
+    for mod, score in bridges:
+        print(f"{mod:50s}  {score:.5f}")

pycode_kg/cli/cmd_build.py

@@ -0,0 +1,154 @@
+"""
+cmd_build.py
+
+Click subcommands for building the PyCodeKG knowledge graph:
+
+    build-sqlite   - repo -> AST -> graph store
+    build-lancedb  - graph store -> vector index
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from pycode_kg.cli.main import cli
+from pycode_kg.cli.options import exclude_option, include_option, repo_option
+from pycode_kg.config import load_exclude_dirs, load_include_dirs
+from pycode_kg.graph import CodeGraph
+from pycode_kg.index import (
+    SemanticIndex,
+    SentenceTransformerEmbedder,
+    suppress_ingestion_logging,
+)
+from pycode_kg.pycodekg import DEFAULT_MODEL
+from pycode_kg.store import GraphStore
+
+
+@cli.command("build-sqlite")
+@repo_option
+@click.option(
+    "--db",
+    default=None,
+    type=click.Path(),
+    show_default=False,
+    help="SQLite database path (default: <repo>/.pycodekg/graph.sqlite).",
+)
+@click.option("--wipe", is_flag=True, help="Delete existing graph first.")
+@include_option
+@exclude_option
+def build_sqlite(
+    repo: str,
+    db: str | None,
+    wipe: bool,
+    include_dir: tuple[str, ...],
+    exclude_dir: tuple[str, ...],
+) -> None:
+    """Extract a code knowledge graph from a Python repo and store it in SQLite."""
+    repo_root = Path(repo).resolve()
+    db_path = Path(db) if db else repo_root / ".pycodekg" / "graph.sqlite"
+
+    # Merge pyproject.toml config with CLI flags
+    include = load_include_dirs(repo_root) | set(include_dir)
+    exclude = load_exclude_dirs(repo_root) | set(exclude_dir)
+
+    graph = CodeGraph(
+        repo_root,
+        include=include if include else None,
+        exclude=exclude if exclude else None,
+    )
+    nodes, edges = graph.extract().result()
+
+    store = GraphStore(db_path)
+    store.write(nodes, edges, wipe=wipe)
+    resolved = store.resolve_symbols()
+    store.close()
+
+    print(f"OK: nodes={len(nodes)} edges={len(edges)} resolved={resolved} db={db_path}")
+
+
+@cli.command("build-lancedb")
+@repo_option
+@click.option(
+    "--sqlite",
+    default=None,
+    type=click.Path(),
+    show_default=False,
+    help="Path to graph.sqlite (default: <repo>/.pycodekg/graph.sqlite).",
+)
+@click.option(
+    "--lancedb",
+    default=None,
+    type=click.Path(),
+    show_default=False,
+    help="Directory for LanceDB (default: <repo>/.pycodekg/lancedb).",
+)
+@click.option(
+    "--table",
+    default="pycodekg_nodes",
+    show_default=True,
+    help="LanceDB table name.",
+)
+@click.option(
+    "--model",
+    default=DEFAULT_MODEL,
+    show_default=True,
+    help="SentenceTransformer model name.",
+)
+@click.option("--wipe", is_flag=True, help="Delete existing vectors first.")
+@click.option("-v", "--verbose", is_flag=True, help="Show LanceDB and embedder progress output.")
+@click.option(
+    "--kinds",
+    default="module,class,function,method",
+    show_default=True,
+    help="Comma-separated node kinds to index.",
+)
+@click.option(
+    "--batch",
+    type=int,
+    default=256,
+    show_default=True,
+    help="Embedding batch size.",
+)
+def build_lancedb(
+    repo: str,
+    sqlite: str | None,
+    lancedb: str | None,
+    table: str,
+    model: str,
+    wipe: bool,
+    verbose: bool,
+    kinds: str,
+    batch: int,
+) -> None:
+    """Build a LanceDB semantic index from an existing pycodekg SQLite database."""
+    repo_root = Path(repo).resolve()
+    sqlite_path = Path(sqlite) if sqlite else repo_root / ".pycodekg" / "graph.sqlite"
+    lancedb_dir = Path(lancedb) if lancedb else repo_root / ".pycodekg" / "lancedb"
+
+    if not verbose:
+        suppress_ingestion_logging()
+
+    kinds_tuple = tuple(k.strip() for k in kinds.split(",") if k.strip())
+    embedder = SentenceTransformerEmbedder(model)
+
+    store = GraphStore(sqlite_path)
+    idx = SemanticIndex(
+        lancedb_dir,
+        embedder=embedder,
+        table=table,
+        index_kinds=kinds_tuple,
+    )
+    stats = idx.build(store, wipe=wipe, batch_size=batch, quiet=not verbose)
+    store.close()
+
+    print(
+        "OK:",
+        f"indexed_rows={stats['indexed_rows']}",
+        f"embedder={model}",
+        f"dim={stats['dim']}",
+        f"table={stats['table']}",
+        f"lancedb_dir={stats['lancedb_dir']}",
+        f"kinds={','.join(stats['kinds'])}",
+    )

pycode_kg/cli/cmd_build_full.py

@@ -0,0 +1,242 @@
+"""
+cmd_build_full.py
+
+Click subcommand for building the full PyCodeKG pipeline in one step:
+
+    build   - repo -> AST -> graph store -> vector index (full pipeline, always wipes)
+    update  - repo -> AST -> graph store -> vector index (incremental upsert, no wipe)
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import click
+
+from pycode_kg.cli.main import cli
+from pycode_kg.cli.options import (
+    exclude_option,
+    include_option,
+    model_option,
+    repo_option,
+)
+from pycode_kg.config import load_exclude_dirs, load_include_dirs
+from pycode_kg.graph import CodeGraph
+from pycode_kg.index import (
+    SemanticIndex,
+    SentenceTransformerEmbedder,
+    suppress_ingestion_logging,
+)
+from pycode_kg.store import GraphStore
+
+
+def _banner(repo_root: Path, label: str) -> None:
+    """Print the build header banner."""
+    click.echo()
+    click.echo(f"  PyCodeKG  {label}")
+    click.echo("  repo - AST - graph store - vector index")
+    click.echo(f"  repo  {repo_root}")
+    click.echo()
+
+
+def _step_result(n: int, label: str, pairs: list[tuple[str, str]], elapsed: float) -> None:
+    """Print a single-line step result after the step completes."""
+    kv = "  ".join(f"{k}={v}" for k, v in pairs)
+    click.echo(f"  Step {n}  {label}  {kv}  ({elapsed:.1f}s)")
+
+
+def _done(elapsed: float) -> None:
+    """Print a compact build-complete summary."""
+    click.echo()
+    click.echo(f"  done  ({elapsed:.1f}s)")
+    click.echo()
+
+
+def _common_options(fn):
+    """Shared Click options for build and update commands."""
+    fn = repo_option(fn)
+    fn = click.option(
+        "--db",
+        default=None,
+        type=click.Path(),
+        show_default=False,
+        help="SQLite database path (default: <repo>/.pycodekg/graph.sqlite).",
+    )(fn)
+    fn = click.option(
+        "--lancedb",
+        default=None,
+        type=click.Path(),
+        show_default=False,
+        help="LanceDB directory path (default: <repo>/.pycodekg/lancedb).",
+    )(fn)
+    fn = click.option(
+        "--table",
+        default="pycodekg_nodes",
+        show_default=True,
+        help="LanceDB table name.",
+    )(fn)
+    fn = model_option(fn)
+    fn = click.option(
+        "-v", "--verbose", is_flag=True, help="Show LanceDB and embedder progress output."
+    )(fn)
+    fn = click.option(
+        "--kinds",
+        default="module,class,function,method",
+        show_default=True,
+        help="Comma-separated node kinds to index.",
+    )(fn)
+    fn = click.option(
+        "--batch",
+        type=int,
+        default=256,
+        show_default=True,
+        help="Embedding batch size.",
+    )(fn)
+    fn = include_option(fn)
+    fn = exclude_option(fn)
+    return fn
+
+
+def _run_pipeline(
+    repo: str,
+    db: str | None,
+    lancedb: str | None,
+    table: str,
+    model: str,
+    verbose: bool,
+    kinds: str,
+    batch: int,
+    include_dir: tuple[str, ...],
+    exclude_dir: tuple[str, ...],
+    *,
+    wipe: bool,
+    label: str,
+) -> None:
+    """Execute the full build pipeline (shared by build and update)."""
+    repo_root = Path(repo).resolve()
+    db_path = Path(db) if db else repo_root / ".pycodekg" / "graph.sqlite"
+    lancedb_dir = Path(lancedb) if lancedb else repo_root / ".pycodekg" / "lancedb"
+
+    include = load_include_dirs(repo_root) | set(include_dir)
+    exclude = load_exclude_dirs(repo_root) | set(exclude_dir)
+
+    _banner(repo_root, label)
+    t_total = time.monotonic()
+
+    # Step 1: Build graph store
+    t1 = time.monotonic()
+    graph = CodeGraph(
+        repo_root,
+        include=include if include else None,
+        exclude=exclude if exclude else None,
+    )
+    nodes, edges = graph.extract().result()
+
+    store = GraphStore(db_path)
+    store.write(nodes, edges, wipe=wipe)
+    resolved = store.resolve_symbols()
+    store.close()
+
+    _step_result(
+        1,
+        "graph store",
+        [
+            ("nodes", str(len(nodes))),
+            ("edges", str(len(edges))),
+            ("resolved", str(resolved)),
+        ],
+        elapsed=time.monotonic() - t1,
+    )
+
+    # Step 2: Build vector index
+    if not verbose:
+        suppress_ingestion_logging()
+
+    t2 = time.monotonic()
+    kinds_tuple = tuple(k.strip() for k in kinds.split(",") if k.strip())
+    embedder = SentenceTransformerEmbedder(model)
+
+    store = GraphStore(db_path)
+    idx = SemanticIndex(
+        lancedb_dir,
+        embedder=embedder,
+        table=table,
+        index_kinds=kinds_tuple,
+    )
+    stats = idx.build(store, wipe=wipe, batch_size=batch, quiet=not verbose)
+    store.close()
+
+    _step_result(
+        2,
+        "vector index",
+        [
+            ("indexed", str(stats["indexed_rows"])),
+            ("model", Path(model).name),
+        ],
+        elapsed=time.monotonic() - t2,
+    )
+
+    _done(elapsed=time.monotonic() - t_total)
+
+
+@cli.command("build")
+@_common_options
+def build(
+    repo: str,
+    db: str | None,
+    lancedb: str | None,
+    table: str,
+    model: str,
+    verbose: bool,
+    kinds: str,
+    batch: int,
+    include_dir: tuple[str, ...],
+    exclude_dir: tuple[str, ...],
+) -> None:
+    """Build knowledge graph from scratch: wipes existing data, then extracts AST -> graph store -> vector index."""
+    _run_pipeline(
+        repo,
+        db,
+        lancedb,
+        table,
+        model,
+        verbose,
+        kinds,
+        batch,
+        include_dir,
+        exclude_dir,
+        wipe=True,
+        label="Full Build",
+    )
+
+
+@cli.command("update")
+@_common_options
+def update(
+    repo: str,
+    db: str | None,
+    lancedb: str | None,
+    table: str,
+    model: str,
+    verbose: bool,
+    kinds: str,
+    batch: int,
+    include_dir: tuple[str, ...],
+    exclude_dir: tuple[str, ...],
+) -> None:
+    """Update knowledge graph incrementally: upserts changes without wiping existing data."""
+    _run_pipeline(
+        repo,
+        db,
+        lancedb,
+        table,
+        model,
+        verbose,
+        kinds,
+        batch,
+        include_dir,
+        exclude_dir,
+        wipe=False,
+        label="Update",
+    )