pycode-kg 0.16.0__py3-none-any.whl

pycode_kg/cli/cmd_centrality.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Click command for Structural Importance Ranking (SIR)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from pycode_kg.analysis.centrality import (
+    StructuralImportanceRanker,
+    aggregate_module_scores,
+)
+from pycode_kg.cli.main import cli
+
+
+@cli.command("centrality")
+@click.option(
+    "--db",
+    type=click.Path(path_type=Path, dir_okay=False),
+    default=Path(".pycodekg/graph.sqlite"),
+    show_default=True,
+    help="Path to the PyCodeKG SQLite graph.",
+)
+@click.option(
+    "--kind",
+    "kinds",
+    multiple=True,
+    type=click.Choice(["module", "class", "function", "method"], case_sensitive=False),
+    help="Restrict output to one or more node kinds.",
+)
+@click.option("--top", type=int, default=25, show_default=True, help="Maximum rows to show.")
+@click.option(
+    "--group-by",
+    type=click.Choice(["node", "module"], case_sensitive=False),
+    default="node",
+    show_default=True,
+    help="Return node-level or module-level rankings.",
+)
+@click.option("--json", "as_json", is_flag=True, help="Emit JSON instead of a table.")
+@click.option("--write-db", is_flag=True, help="Persist node-level scores into centrality_scores.")
+def cmd_centrality(
+    db: Path,
+    kinds: tuple[str, ...],
+    top: int,
+    group_by: str,
+    as_json: bool,
+    write_db: bool,
+) -> None:
+    """Compute Structural Importance Ranking over the resolved PyCodeKG graph."""
+    ranker = StructuralImportanceRanker(db)
+    records = ranker.compute(kinds=set(kinds) if kinds else None, top=None)
+
+    if write_db:
+        ranker.write_scores(records)
+
+    if group_by == "module":
+        payload = aggregate_module_scores(records)[:top]
+        if as_json:
+            click.echo(json.dumps(payload, indent=2))
+            return
+        _print_module_table(payload)
+        return
+
+    node_payload = records[:top]
+    if as_json:
+        click.echo(json.dumps([_record_to_dict(r) for r in node_payload], indent=2))
+        return
+    _print_node_table(node_payload)
+
+
+def _record_to_dict(record) -> dict:
+    return {
+        "node_id": record.node_id,
+        "kind": record.kind,
+        "name": record.name,
+        "module_path": record.module_path,
+        "score": record.score,
+        "rank": record.rank,
+        "inbound_count": record.inbound_count,
+        "cross_module_inbound": record.cross_module_inbound,
+        "rel_breakdown": record.rel_breakdown,
+        "top_contributors": record.top_contributors,
+    }
+
+
+def _print_node_table(records) -> None:
+    headers = (
+        "Rank",
+        "Score",
+        "Kind",
+        "Name",
+        "Inbound",
+        "XMod",
+        "Module",
+    )
+    rows = [
+        (
+            r.rank,
+            f"{r.score:.6f}",
+            r.kind,
+            r.name,
+            r.inbound_count,
+            r.cross_module_inbound,
+            r.module_path or "",
+        )
+        for r in records
+    ]
+    click.echo(click.format_filename(""))
+    click.echo(_format_table(headers, rows))
+
+
+def _print_module_table(payload) -> None:
+    headers = ("Rank", "Score", "Members", "Module")
+    rows = [
+        (row["rank"], f"{row['score']:.6f}", row["member_count"], row["module_path"])
+        for row in payload
+    ]
+    click.echo(_format_table(headers, rows))
+
+
+def _format_table(headers, rows) -> str:
+    widths = [len(str(h)) for h in headers]
+    for row in rows:
+        for i, value in enumerate(row):
+            widths[i] = max(widths[i], len(str(value)))
+    fmt = "  ".join(f"{{:{w}}}" for w in widths)
+    lines = [fmt.format(*headers), fmt.format(*["-" * w for w in widths])]
+    lines.extend(fmt.format(*[str(v) for v in row]) for row in rows)
+    return "\n".join(lines)

pycode_kg/cli/cmd_explain.py

@@ -0,0 +1,180 @@
+"""
+cmd_explain.py
+
+Click subcommand for explaining code nodes:
+
+  explain  — get a natural-language explanation of a code node by its ID
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from pycode_kg.cli.main import cli
+from pycode_kg.cli.options import lancedb_option, model_option, sqlite_option
+from pycode_kg.kg import PyCodeKG
+
+
+@cli.command("explain")
+@click.argument("node_id", metavar="NODE_ID")
+@sqlite_option
+@lancedb_option
+@click.option(
+    "--table",
+    default="pycodekg_nodes",
+    show_default=True,
+    help="LanceDB table name.",
+)
+@model_option
+@click.option(
+    "--out",
+    type=click.Path(),
+    default=None,
+    help="Output file path (default: stdout).",
+)
+def explain(
+    node_id: str,
+    sqlite: str,
+    lancedb: str,
+    table: str,
+    model: str,
+    out: str | None,
+) -> None:
+    """Get a natural-language explanation of a code node.
+
+    NODE_ID is the stable identifier of a node, e.g.:
+    fn:src/pycode_kg/store.py:GraphStore.expand
+    """
+    # explain-only does not need repo_root for source reading; use sqlite parent as placeholder
+    repo_root = Path(sqlite).parent
+
+    kg = PyCodeKG(
+        repo_root=repo_root,
+        db_path=Path(sqlite),
+        lancedb_dir=Path(lancedb),
+        model=model,
+        table=table,
+    )
+
+    node = kg.node(node_id)
+
+    if node is None:
+        click.echo(f"[ERROR] Node not found: {node_id}", err=True)
+        kg.close()
+        raise SystemExit(1)
+
+    markdown_output = _explain_node(kg, node_id, node)
+
+    if out:
+        Path(out).write_text(markdown_output)
+        click.echo(f"[OK] Explanation written to {out}")
+    else:
+        click.echo(markdown_output)
+
+    kg.close()
+
+
+def _explain_node(kg: PyCodeKG, node_id: str, node: dict) -> str:
+    """Generate markdown explanation for a node.
+
+    :param kg: PyCodeKG instance
+    :param node_id: Node identifier
+    :param node: Node dict from kg.node()
+    :return: Markdown-formatted explanation
+    """
+    out: list[str] = []
+
+    # Header with kind and name
+    kind = node.get("kind", "unknown")
+    name = node.get("qualname") or node.get("name", "unknown")
+    out.append(f"# {kind.capitalize()}: `{name}`\n")
+
+    # Metadata
+    out.append("## Metadata\n")
+    if node.get("module_path"):
+        out.append(f"- **Module**: `{node['module_path']}`")
+    if node.get("lineno") is not None:
+        out.append(
+            f"- **Location**: line {node['lineno']}"
+            + (f"–{node['end_lineno']}" if node.get("end_lineno") else "")
+        )
+    out.append(f"- **ID**: `{node_id}`")
+    out.append("")
+
+    # Docstring
+    docstring = node.get("docstring", "").strip()
+    if docstring:
+        out.append("## Documentation\n")
+        out.append(docstring)
+        out.append("")
+
+    # Get callers
+    try:
+        caller_list = kg.callers(node_id, rel="CALLS")
+        if caller_list:
+            out.append("## Called By (Callers)\n")
+            out.append(f"This {kind} is called by **{len(caller_list)}** other function(s):\n")
+            for caller in caller_list[:10]:
+                caller_name = caller.get("qualname") or caller.get("name", "unknown")
+                caller_module = caller.get("module_path", "")
+                out.append(f"- `{caller_name}` ({caller_module})")
+            if len(caller_list) > 10:
+                out.append(f"- ... and {len(caller_list) - 10} more")
+            out.append("")
+    except (AttributeError, ValueError, RuntimeError):
+        pass
+
+    # Get callees (what this function calls)
+    try:
+        if hasattr(kg, "_store") and kg._store is not None:
+            edges = kg._store.edges_from(node_id, rel="CALLS", limit=50)
+            if edges:
+                out.append("## Calls (Callees)\n")
+                out.append(f"This {kind} calls **{len(edges)}** other function(s):\n")
+                callees = set()
+                for edge in edges:
+                    dst_id = edge.get("dst")
+                    if dst_id is not None:
+                        dst_node = kg.node(dst_id)
+                        if dst_node:
+                            dst_name = dst_node.get("qualname") or dst_node.get("name", "unknown")
+                            callees.add(f"- `{dst_name}`")
+                for callee in sorted(list(callees))[:10]:
+                    out.append(callee)
+                if len(callees) > 10:
+                    out.append(f"- ... and {len(callees) - 10} more")
+                out.append("")
+    except (AttributeError, ValueError, RuntimeError):
+        pass
+
+    # Role assessment
+    out.append("## Role in Codebase\n")
+    try:
+        caller_count = len(kg.callers(node_id, rel="CALLS"))
+        if caller_count > 50:
+            out.append(
+                f"**High-value function**: Called {caller_count} times. "
+                "This is likely a core API or bottleneck. Changes here may have wide impact."
+            )
+        elif caller_count > 10:
+            out.append(
+                f"**Important function**: Called {caller_count} times. "
+                "Part of the essential infrastructure."
+            )
+        elif caller_count > 0:
+            out.append(
+                f"**Utility function**: Called {caller_count} time(s). "
+                "Specific to particular use cases."
+            )
+        else:
+            out.append("**Orphaned**: Never called. This may be dead code or internal utility.")
+    except (AttributeError, ValueError, RuntimeError):
+        out.append("Unable to determine call graph role.")
+
+    out.append("")
+    out.append("---\n")
+    out.append("*Use `pycodekg pack` to retrieve the full source code.*")
+
+    return "\n".join(out)

pycode_kg/cli/cmd_framework_nodes.py

@@ -0,0 +1,18 @@
+"""
+CLI command for framework node detection in PyCodeKG.
+"""
+
+import argparse
+
+from pycode_kg.analysis.framework_detector import detect_framework_nodes
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Show top framework-like modules.")
+    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 framework nodes to show")
+    args = parser.parse_args()
+    nodes = detect_framework_nodes(limit=args.top, db_path=args.db)
+    print(f"Top {args.top} framework-like modules:")
+    for node_id, score, label in nodes:
+        print(f"{label:50s}  {score:.5f}  ({node_id})")

pycode_kg/cli/cmd_hooks.py

@@ -0,0 +1,137 @@
+"""
+cmd_hooks.py
+
+CLI command for installing PyCodeKG git hooks:
+
+  install-hooks — install the pre-commit snapshot hook into .git/hooks/
+
+  Author: Eric G. Suchanek, PhD
+  Last Revision: 2026-03-08 21:30:55
+"""
+
+from __future__ import annotations
+
+import stat
+from pathlib import Path
+
+import click
+
+from pycode_kg.cli.main import cli
+
+# ---------------------------------------------------------------------------
+# Hook script content (embedded so this module is self-contained when
+# installed as a package in any repo, not just pycode_kg itself)
+# ---------------------------------------------------------------------------
+
+_PRE_COMMIT_HOOK = """\
+#!/usr/bin/env bash
+# PyCodeKG + DocKG pre-commit hook — keeps local indices in sync and captures
+# metrics snapshots BEFORE quality checks run.
+# Installed by: pycodekg install-hooks
+# Skip with: PYCODEKG_SKIP_SNAPSHOT=1 git commit ...
+set -euo pipefail
+
+[ "${PYCODEKG_SKIP_SNAPSHOT:-0}" = "1" ] && exit 0
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+WORKSPACE_ROOT="$(cd "$REPO_ROOT/.." && pwd)"
+DOCKG_REPO="${WORKSPACE_ROOT}/doc_kg"
+
+cd "$REPO_ROOT"
+
+# Capture the tree hash of the staged index NOW — before any tool modifies files.
+TREE_HASH=$(git write-tree)
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Rebuild both local indices to keep them in sync with staged content.
+"$REPO_ROOT/.venv/bin/pycodekg" build --repo "$REPO_ROOT" || exit 1
+if [ -d "$DOCKG_REPO" ]; then
+    "$REPO_ROOT/.venv/bin/dockg" build --repo "$DOCKG_REPO" || true
+fi
+
+# Snapshot PyCodeKG (version auto-detected from installed package).
+"$REPO_ROOT/.venv/bin/pycodekg" snapshot save \\
+    --repo . \\
+    --tree-hash "$TREE_HASH" \\
+    --branch "$BRANCH" \\
+  || { echo "[pycodekg] snapshot skipped (run 'pycodekg build' to initialize)" >&2; }
+
+# Snapshot DocKG if available (version auto-detected from installed package).
+if [ -d "$DOCKG_REPO/.dockg" ]; then
+    (cd "$DOCKG_REPO" && "$REPO_ROOT/.venv/bin/dockg" snapshot save \\
+        --repo . \\
+        --tree-hash "$TREE_HASH" \\
+        --branch "$BRANCH") || true
+fi
+
+# Stage both snapshot directories so they are included in the commit.
+git add .pycodekg/snapshots/ 2>/dev/null || true
+if [ -d "$DOCKG_REPO" ]; then
+    (cd "$DOCKG_REPO" && git add .dockg/snapshots/ 2>/dev/null || true)
+fi
+
+# Run pre-commit framework checks (ruff, mypy, detect-secrets, etc.) AFTER
+# snapshots are captured and staged. Delegates to .pre-commit-config.yaml so
+# quality checks stay in one place.
+PRECOMMIT="$REPO_ROOT/.venv/bin/pre-commit"
+if [ -x "$PRECOMMIT" ]; then
+    "$PRECOMMIT" run || exit 1
+elif command -v pre-commit &>/dev/null; then
+    pre-commit run || exit 1
+fi
+
+exit 0
+"""
+
+
+@cli.command("install-hooks")
+@click.option(
+    "--repo",
+    default=".",
+    type=click.Path(exists=True),
+    show_default=True,
+    help="Repository root.",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Overwrite an existing pre-commit hook.",
+)
+def install_hooks(repo: str, force: bool) -> None:
+    """Install the PyCodeKG pre-commit git hook.
+
+    After installation, before each commit:
+      1. Rebuilds local PyCodeKG index (full wipe)
+      2. Rebuilds local DocKG index if available (full wipe)
+      3. Captures metrics snapshots for both KGs, keyed by tree hash
+      4. Stages both snapshot directories atomically
+
+    This keeps PyCodeKG and DocKG indices in sync and ensures snapshots
+    reflect the current state of both knowledge graphs at commit time.
+
+    Example:
+        pycodekg install-hooks --repo .
+    """
+    repo_root = Path(repo).resolve()
+    git_dir = repo_root / ".git"
+
+    if not git_dir.is_dir():
+        click.echo(f"Error: {repo_root} is not a git repository.", err=True)
+        raise SystemExit(1)
+
+    hooks_dir = git_dir / "hooks"
+    hooks_dir.mkdir(exist_ok=True)
+    hook_path = hooks_dir / "pre-commit"
+
+    if hook_path.exists() and not force:
+        click.echo(f"Hook already exists: {hook_path}")
+        click.echo("Use --force to overwrite.")
+        raise SystemExit(1)
+
+    hook_path.write_text(_PRE_COMMIT_HOOK)
+    mode = hook_path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+    hook_path.chmod(mode)
+
+    click.echo(f"OK Installed pre-commit hook: {hook_path}")
+    click.echo("  Snapshots will be captured automatically before each commit.")
+    click.echo("  Run 'pycodekg build' first if you haven't built the graph yet.")