tscode-kg 0.2.0__py3-none-any.whl

tscode_kg/cli/cmd_build.py

@@ -0,0 +1,86 @@
+"""
+cli/cmd_build.py — tscodekg build command.
+
+Builds the SQLite graph and sqlite-vec vector index from a TypeScript/JS repo.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+@click.command("build")
+@click.option("--repo", default=".", show_default=True, help="Repository root directory.")
+@click.option(
+    "--db",
+    default=None,
+    help="SQLite database path (default: <repo>/.tscodekg/graph.sqlite).",
+)
+@click.option(
+    "--vectors",
+    default=None,
+    help="sqlite-vec store path (default: <repo>/.tscodekg/vectors.sqlite).",
+)
+@click.option("--wipe", is_flag=True, default=False, help="Clear existing data before building.")
+@click.option(
+    "--graph-only",
+    is_flag=True,
+    default=False,
+    help="Build SQLite graph only; skip vector index.",
+)
+@click.option(
+    "--index-only",
+    is_flag=True,
+    default=False,
+    help="Build vector index only; graph must already exist.",
+)
+def build(
+    repo: str,
+    db: str | None,
+    vectors: str | None,
+    wipe: bool,
+    graph_only: bool,
+    index_only: bool,
+) -> None:
+    """Build the TypeScript/JS knowledge graph for a repository."""
+    from tscode_kg.kg import TypeScriptKG  # pylint: disable=import-outside-toplevel
+
+    repo_path = Path(repo).resolve()
+    if not repo_path.is_dir():
+        console.print(f"[red]Error:[/red] Repository not found: {repo_path}")
+        raise SystemExit(1)
+
+    kg = TypeScriptKG(
+        repo_root=repo_path,
+        db_path=db,
+        vectors_path=vectors,
+    )
+
+    console.print("[bold]TypeScriptKG build[/bold]")
+    console.print(f"  repo    : {repo_path}")
+    console.print(f"  db      : {kg.db_path}")
+    console.print(f"  vectors : {kg.vectors_path}")
+    console.print(f"  wipe    : {wipe}")
+    console.print()
+
+    try:
+        if index_only:
+            console.print("[cyan]Building vector index...[/cyan]")
+            stats = kg.build_index(wipe=wipe)
+        elif graph_only:
+            console.print("[cyan]Building SQLite graph...[/cyan]")
+            stats = kg.build_graph(wipe=wipe)
+        else:
+            console.print("[cyan]Building graph + vector index...[/cyan]")
+            stats = kg.build(wipe=wipe)
+
+        console.print("[green]Done.[/green]")
+        console.print(str(stats))
+    except Exception as exc:  # pylint: disable=broad-except
+        console.print(f"[red]Build failed:[/red] {exc}")
+        raise SystemExit(1) from exc

tscode_kg/cli/cmd_centrality.py

@@ -0,0 +1,124 @@
+"""
+cli/cmd_centrality.py — tscodekg centrality command.
+
+Structural Importance Ranking (SIR) over the TypeScriptKG graph.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+
+@click.command("centrality")
+@click.option(
+    "--db",
+    type=click.Path(path_type=Path, dir_okay=False),
+    default=Path(".tscodekg/graph.sqlite"),
+    show_default=True,
+    help="Path to the TypeScriptKG SQLite graph.",
+)
+@click.option(
+    "--kind",
+    "kinds",
+    multiple=True,
+    type=click.Choice(["module", "class", "interface", "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 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 TypeScriptKG graph."""
+    from tscode_kg.centrality import (  # pylint: disable=import-outside-toplevel
+        StructuralImportanceRanker,
+        aggregate_module_scores,
+    )
+
+    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(_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)

tscode_kg/cli/cmd_explain.py

@@ -0,0 +1,58 @@
+"""
+cli/cmd_explain.py — tscodekg explain command.
+
+  explain — get a natural-language explanation of a code node by its ID
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+
+@click.command("explain")
+@click.argument("node_id", metavar="NODE_ID")
+@click.option("--repo", default=".", show_default=True, help="Repository root.")
+@click.option(
+    "--db",
+    default=None,
+    type=click.Path(),
+    help="SQLite knowledge graph path (default: <repo>/.tscodekg/graph.sqlite).",
+)
+@click.option(
+    "--out",
+    type=click.Path(),
+    default=None,
+    help="Output file path (default: stdout).",
+)
+def explain(node_id: str, repo: str, db: str | None, 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/utils/helpers.ts:formatDate
+    """
+    from tscode_kg.explain import render_explain  # pylint: disable=import-outside-toplevel
+    from tscode_kg.kg import TypeScriptKG  # pylint: disable=import-outside-toplevel
+
+    kg = TypeScriptKG(repo_root=Path(repo).resolve(), db_path=db)
+
+    # Fail fast for scripting: distinguish missing-node from rendered output.
+    if kg.node(node_id) is None:
+        click.echo(f"[ERROR] Node not found: {node_id}", err=True)
+        kg.close()
+        raise SystemExit(1)
+
+    markdown_output = render_explain(
+        kg,
+        node_id,
+        snippets_hint="tscodekg pack",
+    )
+
+    if out:
+        Path(out).write_text(markdown_output)
+        click.echo(f"[OK] Explanation written to {out}")
+    else:
+        click.echo(markdown_output)
+
+    kg.close()

tscode_kg/cli/cmd_framework_nodes.py

@@ -0,0 +1,43 @@
+"""
+cli/cmd_framework_nodes.py — tscodekg framework-nodes command.
+
+Framework-like hub module detection over the TypeScriptKG graph.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+
+@click.command("framework-nodes")
+@click.option(
+    "--db",
+    type=click.Path(path_type=Path, dir_okay=False),
+    default=Path(".tscodekg/graph.sqlite"),
+    show_default=True,
+    help="Path to the TypeScriptKG SQLite graph.",
+)
+@click.option("--top", type=int, default=25, show_default=True, help="Number of top modules.")
+def framework_nodes(db: Path, top: int) -> None:
+    """Show top framework-like modules (high SIR + high connectivity)."""
+    from tscode_kg.bridge import (  # pylint: disable=import-outside-toplevel
+        compute_bridge_centrality,
+    )
+    from tscode_kg.centrality import (  # pylint: disable=import-outside-toplevel
+        StructuralImportanceRanker,
+    )
+    from tscode_kg.framework_detector import (  # pylint: disable=import-outside-toplevel
+        detect_framework_nodes,
+    )
+
+    # Both metrics must be persisted before detection can combine them.
+    ranker = StructuralImportanceRanker(str(db))
+    ranker.write_scores(ranker.compute(), metric="sir_pagerank")
+    compute_bridge_centrality(kind="module", include_imports=True, top=top, db_path=str(db))
+
+    nodes = detect_framework_nodes(limit=top, db_path=str(db))
+    click.echo(f"Top {top} framework-like modules:")
+    for node_id, score, label in nodes:
+        click.echo(f"{label:50s}  {score:.5f}  ({node_id})")

tscode_kg/cli/cmd_hooks.py

@@ -0,0 +1,125 @@
+"""
+cli/cmd_hooks.py — tscodekg install-hooks command.
+
+  install-hooks — install the pre-commit snapshot hook into .git/hooks/
+"""
+
+from __future__ import annotations
+
+import stat
+from pathlib import Path
+
+import click
+
+# ---------------------------------------------------------------------------
+# Hook script content (embedded so this module is self-contained when
+# installed as a package in any repo, not just tscode_kg itself)
+# ---------------------------------------------------------------------------
+
+_PRE_COMMIT_HOOK = """\
+#!/usr/bin/env bash
+# TypeScriptKG pre-commit hook — keeps the local index in sync and captures
+# metrics snapshots BEFORE quality checks run.
+# Installed by: tscodekg install-hooks
+# Skip with: TSCODEKG_SKIP_SNAPSHOT=1 git commit ...
+set -euo pipefail
+
+[ "${TSCODEKG_SKIP_SNAPSHOT:-0}" = "1" ] && exit 0
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+# Resolve the tscodekg binary: prefer the repo's .venv, fall back to PATH.
+if [ -x "$REPO_ROOT/.venv/bin/tscodekg" ]; then
+    TSCODEKG="$REPO_ROOT/.venv/bin/tscodekg"
+elif command -v tscodekg &>/dev/null; then
+    TSCODEKG="tscodekg"
+else
+    echo "[tscodekg] binary not found — skipping snapshot hook" >&2
+    exit 0
+fi
+
+# 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 the local index to keep it in sync with staged content.
+"$TSCODEKG" build --repo "$REPO_ROOT" || exit 1
+
+# Snapshot TypeScriptKG (version auto-detected from installed package).
+"$TSCODEKG" snapshot save \\
+    --repo . \\
+    --tree-hash "$TREE_HASH" \\
+    --branch "$BRANCH" \\
+  || { echo "[tscodekg] snapshot skipped (run 'tscodekg build' to initialize)" >&2; }
+
+# Stage the snapshot directory so it is included in the commit.
+git add .tscodekg/snapshots/ 2>/dev/null || true
+
+# Run pre-commit framework checks (ruff, ty, 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
+"""
+
+
+@click.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 TypeScriptKG pre-commit git hook.
+
+    After installation, before each commit:
+
+    \b
+      1. Rebuilds the local TypeScriptKG index (full wipe)
+      2. Captures a metrics snapshot keyed by tree hash
+      3. Stages the snapshot directory atomically
+      4. Runs the pre-commit framework checks
+
+    This keeps the index in sync and ensures snapshots reflect the state of
+    the knowledge graph at commit time.
+
+    Example:
+        tscodekg 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 'tscodekg build' first if you haven't built the graph yet.")

tscode_kg/cli/cmd_init.py

@@ -0,0 +1,234 @@
+"""
+cli/cmd_init.py — tscodekg init command.
+
+  init — download model, build graph, install hooks, capture snapshot
+"""
+
+from __future__ import annotations
+
+import stat
+import subprocess
+import time
+import tomllib
+from pathlib import Path
+
+import click
+
+from tscode_kg.cli.cmd_hooks import _PRE_COMMIT_HOOK
+
+
+def _has_tscodekg_config(repo_root: Path) -> bool:
+    """Check whether pyproject.toml already has a [tool.tscodekg] section.
+
+    :param repo_root: Repository root directory.
+    :return: True when the section exists.
+    """
+    pyproject = repo_root / "pyproject.toml"
+    if not pyproject.exists():
+        return False
+    try:
+        with open(pyproject, "rb") as f:
+            data = tomllib.load(f)
+        return "tscodekg" in data.get("tool", {})
+    except (OSError, ValueError):
+        return False
+
+
+def _scaffold_tscodekg_config(repo_root: Path) -> bool:
+    """Append a minimal [tool.tscodekg] section to pyproject.toml if missing.
+
+    Detects the most likely source directory (``src``, ``lib``, or ``app``)
+    and sets it as the include list.
+
+    :param repo_root: Repository root directory.
+    :return: True if the section was added, False if skipped.
+    """
+    pyproject = repo_root / "pyproject.toml"
+    if not pyproject.exists():
+        return False
+
+    candidates = ["src", "lib", "app"]
+    include_dirs: list[str] = [d for d in candidates if (repo_root / d).is_dir()]
+
+    lines = [
+        "",
+        "[tool.tscodekg]",
+        "# Directories to include in the knowledge graph build and analysis.",
+        "# When unset, all directories are indexed.",
+    ]
+    if include_dirs:
+        include_str = ", ".join(f'"{d}"' for d in include_dirs)
+        lines.append(f"include = [{include_str}]")
+    else:
+        lines.append("# include = []")
+
+    pyproject.open("a").write("\n".join(lines) + "\n")
+    return True
+
+
+@click.command("init")
+@click.option(
+    "--repo",
+    default=".",
+    type=click.Path(exists=True),
+    show_default=True,
+    help="Repository root.",
+)
+@click.option(
+    "--model",
+    default=None,
+    help="SentenceTransformer model name (default: shared kg_utils default).",
+)
+@click.option("--skip-hooks", is_flag=True, help="Don't install the pre-commit git hook.")
+@click.option("--skip-snapshot", is_flag=True, help="Don't capture an initial snapshot.")
+@click.option("--force", is_flag=True, help="Overwrite existing graph data and hook.")
+def init(
+    repo: str,
+    model: str | None,
+    skip_hooks: bool,
+    skip_snapshot: bool,
+    force: bool,
+) -> None:
+    """Initialize TypeScriptKG in a repository.
+
+    Downloads the embedding model, builds the knowledge graph (SQLite +
+    sqlite-vec), optionally installs the pre-commit hook, and captures an
+    initial snapshot.  Designed to be idempotent — safe to run more than once.
+
+    Example::
+
+        tscodekg init --repo .
+    """
+    from kg_utils.semantic import (  # pylint: disable=import-outside-toplevel
+        DEFAULT_MODEL,
+        _local_model_path,
+    )
+
+    from tscode_kg.kg import TypeScriptKG  # pylint: disable=import-outside-toplevel
+
+    repo_root = Path(repo).resolve()
+    model = model or DEFAULT_MODEL
+    t_total = time.monotonic()
+
+    click.echo()
+    click.echo("  TypeScriptKG  Init")
+    click.echo(f"  repo  {repo_root}")
+    click.echo()
+
+    # ------------------------------------------------------------------
+    # Step 0: Scaffold [tool.tscodekg] in pyproject.toml if missing
+    # ------------------------------------------------------------------
+    if not _has_tscodekg_config(repo_root):
+        if _scaffold_tscodekg_config(repo_root):
+            click.echo("  [0/4]  Added [tool.tscodekg] section to pyproject.toml")
+        else:
+            click.echo("  [0/4]  No pyproject.toml found — skipping config scaffold")
+    else:
+        click.echo("  [0/4]  [tool.tscodekg] config already present")
+
+    # ------------------------------------------------------------------
+    # Step 1: Download the embedding model
+    # ------------------------------------------------------------------
+    click.echo()
+    local_path = _local_model_path(model)
+
+    if local_path.exists() and not force:
+        click.echo(f"  [1/4]  Model already cached at {local_path}")
+    else:
+        click.echo(f"  [1/4]  Downloading embedding model '{model}'...")
+        from sentence_transformers import (  # pylint: disable=import-outside-toplevel
+            SentenceTransformer,
+        )
+
+        st_model = SentenceTransformer(model)
+        local_path.mkdir(parents=True, exist_ok=True)
+        st_model.save(str(local_path))
+        click.echo(f"         OK: model saved to {local_path}")
+
+    # ------------------------------------------------------------------
+    # Step 2: Build the knowledge graph (full wipe)
+    # ------------------------------------------------------------------
+    click.echo()
+    click.echo("  [2/4]  Building knowledge graph...")
+    kg = TypeScriptKG(repo_root=repo_root, model=model)
+    try:
+        stats = kg.build(wipe=True)
+        click.echo(f"         OK: {stats}")
+    finally:
+        kg.close()
+
+    # ------------------------------------------------------------------
+    # Step 3: Install pre-commit hook
+    # ------------------------------------------------------------------
+    click.echo()
+    if skip_hooks:
+        click.echo("  [3/4]  Skipping hook installation (--skip-hooks)")
+    else:
+        git_dir = repo_root / ".git"
+        if not git_dir.is_dir():
+            click.echo("  [3/4]  Not a git repository — skipping hook installation")
+        else:
+            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"  [3/4]  Hook already exists: {hook_path}")
+                click.echo("         Use --force to overwrite.")
+            else:
+                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"  [3/4]  OK: installed pre-commit hook at {hook_path}")
+
+    # ------------------------------------------------------------------
+    # Step 4: Capture initial snapshot
+    # ------------------------------------------------------------------
+    click.echo()
+    if skip_snapshot:
+        click.echo("  [4/4]  Skipping initial snapshot (--skip-snapshot)")
+    else:
+        try:
+            tree_hash = (
+                subprocess.check_output(
+                    ["git", "rev-parse", "HEAD"],
+                    cwd=str(repo_root),
+                    stderr=subprocess.DEVNULL,
+                )
+                .decode()
+                .strip()
+            )
+            branch = (
+                subprocess.check_output(
+                    ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                    cwd=str(repo_root),
+                    stderr=subprocess.DEVNULL,
+                )
+                .decode()
+                .strip()
+            )
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            tree_hash = ""
+            branch = None
+
+        from tscode_kg.cli.cmd_snapshot import (  # pylint: disable=import-outside-toplevel
+            capture_snapshot,
+        )
+
+        try:
+            capture_snapshot(
+                version="",
+                repo=str(repo_root),
+                db=None,
+                snapshots_dir=None,
+                branch=branch,
+                tree_hash=tree_hash,
+            )
+            click.echo("  [4/4]  OK: initial snapshot captured")
+        except Exception as exc:  # noqa: BLE001
+            click.echo(f"  [4/4]  Snapshot skipped: {exc}")
+
+    elapsed = time.monotonic() - t_total
+    click.echo()
+    click.echo(f"  Done in {elapsed:.1f}s — TypeScriptKG is ready.")
+    click.echo('  Try:  tscodekg query "authentication middleware"')