tscode-kg 0.2.0__py3-none-any.whl

tscode_kg/framework_detector.py

@@ -0,0 +1,106 @@
+"""
+Framework Detector for TypeScriptKG.
+Identifies repo-defining abstractions using centrality and cross-module signals.
+
+Ported from PyCodeKG's ``analysis/framework_detector.py`` with the boilerplate
+exclusion list adapted to TS/JS lifecycle and protocol members.
+
+Author: Eric G. Suchanek, PhD
+License: Elastic 2.0
+"""
+
+import sqlite3
+
+# Short member names that are structurally high fan-in but architecturally trivial.
+# Excluded from framework-node ranking so hubs surface over lifecycle boilerplate.
+_BOILERPLATE_NAMES: frozenset[str] = frozenset(
+    {
+        "constructor",
+        "toString",
+        "valueOf",
+        "toJSON",
+        "hasOwnProperty",
+        "close",
+        "dispose",
+        "destroy",
+        "next",
+        "return",
+        "throw",
+        "then",
+        "catch",
+        "finally",
+    }
+)
+
+
+def detect_framework_nodes(
+    limit: int = 25, db_path: str = "tscodekg.sqlite"
+) -> list[tuple[str, float, str]]:
+    """
+    Detect framework-like nodes using SIR and module connectivity.
+
+    Combines Structural Importance Ranking (SIR — importance within the graph)
+    with module connectivity (interaction complexity) to identify modules that are
+    both architecturally central AND highly connected to other modules.
+
+    Framework score = 0.6 × normalized SIR + 0.4 × normalized connectivity.
+    High-scoring modules are critical hubs: important AND complex.
+
+    Lifecycle / protocol boilerplate (``constructor``, ``toString``, ``close``,
+    etc.) is excluded so the ranking surfaces meaningful orchestrators rather
+    than the most-called teardown methods.
+
+    :param limit: Number of top framework nodes to return (default 25).
+    :param db_path: Path to SQLite database (default "tscodekg.sqlite").
+    :return: List of (node_id, framework_score, label) tuples, sorted by score descending.
+    """
+    # Aggregate node-level SIR up to module level so we compare like-for-like
+    # against the module_connectivity metric.  Both signals end up keyed by
+    # bare module path (e.g. "src/auth/middleware.ts"), which we map to "mod:..."
+    # IDs for output.
+    from tscode_kg.centrality import (  # noqa: PLC0415
+        StructuralImportanceRanker,
+        aggregate_module_scores,
+    )
+
+    with sqlite3.connect(db_path) as con:
+        connectivity = dict(
+            con.execute(
+                "SELECT node_id, score FROM centrality_scores WHERE metric = 'module_connectivity'"
+            )
+        )
+        module_id_by_path: dict[str, str] = dict(
+            con.execute("SELECT module_path, id FROM nodes WHERE kind = 'module'")
+        )
+
+    ranker = StructuralImportanceRanker(db_path)
+    sir_records = ranker.compute()
+    sir_by_path: dict[str, float] = {
+        row["module_path"]: row["score"] for row in aggregate_module_scores(sir_records)
+    }
+
+    def norm(d: dict) -> dict:
+        if not d:
+            return {}
+        vals = list(d.values())
+        mn, mx = min(vals), max(vals)
+        return {k: (v - mn) / (mx - mn) if mx > mn else 0.0 for k, v in d.items()}
+
+    nsir = norm(sir_by_path)
+    nconnectivity = norm(connectivity)
+
+    # Framework score: weighted sum (SIR 60% — importance, connectivity 40% — coupling).
+    # Restrict to module paths only — the tool advertises "Framework-like Modules",
+    # so methods/functions must not leak into the ranking.
+    framework: dict[str, float] = {}
+    for path in set(nsir) | set(nconnectivity):
+        framework[path] = 0.6 * nsir.get(path, 0.0) + 0.4 * nconnectivity.get(path, 0.0)
+
+    ranked = sorted(framework.items(), key=lambda x: x[1], reverse=True)
+    result: list[tuple[str, float, str]] = []
+    for path, score in ranked[:limit]:
+        node_id = module_id_by_path.get(path, f"mod:{path}")
+        result.append((node_id, score, path))
+    # _BOILERPLATE_NAMES retained for backward-compat at the import site.
+    _ = _BOILERPLATE_NAMES
+    return result

tscode_kg/kg.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""
+kg.py — TypeScriptKG: concrete KGModule for TypeScript/JavaScript codebases.
+
+Owns the TS/JS-specific extraction layer (tree-sitter AST) and delegates all
+generic infrastructure (SQLite, sqlite-vec, hybrid query, snippet packing,
+snapshots) to the KGModule base class from kg_utils.pipeline.
+
+Author: Eric G. Suchanek, PhD
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+try:
+    from kg_utils.extractor import KGExtractor
+    from kg_utils.pipeline import KGModule
+    from kg_utils.semantic import DEFAULT_MODEL
+    from kg_utils.specs import BuildStats, QueryResult, SnippetPack
+    from kg_utils.store import GraphStore  # noqa: F401
+except ImportError as _e:
+    raise ImportError(
+        "TypeScriptKG requires kgmodule-utils[semantic] for its graph infrastructure.\n"
+        "Install with:  pip install 'tscode-kg[kg]'\n"
+        f"Original error: {_e}"
+    ) from _e
+
+from tscode_kg.config import load_exclude_dirs, load_include_dirs
+from tscode_kg.extractor import TSCodeExtractor
+
+__all__ = [
+    "TypeScriptKG",
+    "BuildStats",
+    "QueryResult",
+    "SnippetPack",
+]
+
+# TypeScript/JavaScript node kind priority for ranking
+_TS_KIND_PRIORITY: dict[str, int] = {
+    "function": 0,
+    "method": 1,
+    "class": 2,
+    "interface": 3,
+    "type_alias": 4,
+    "enum": 5,
+    "namespace": 6,
+    "module": 7,
+    "symbol": 8,
+}
+
+
+class TypeScriptKG(KGModule):
+    """
+    Top-level orchestrator for the TypeScript/JavaScript Knowledge Graph.
+
+    Subclasses :class:`~kg_utils.pipeline.KGModule` and provides the
+    TypeScript/JS-specific extraction layer via :class:`~tscode_kg.extractor.TSCodeExtractor`.
+    All generic infrastructure — SQLite persistence, sqlite-vec indexing,
+    hybrid query, snippet packing — is inherited from KGModule.
+
+    Typical usage::
+
+        kg = TypeScriptKG(repo_root="/path/to/ts-repo")
+        stats = kg.build(wipe=True)
+        print(stats)
+
+        result = kg.query("authentication middleware", k=8)
+        pack = kg.pack("API error handling")
+        pack.save("context.md")
+
+    :param repo_root: Repository root directory.
+    :param db_path: SQLite database path (defaults to ``<repo_root>/.tscodekg/graph.sqlite``).
+    :param vectors_path: sqlite-vec store path (defaults to ``<repo_root>/.tscodekg/vectors.sqlite``).
+    :param model: Sentence-transformer model name.
+    :param table: sqlite-vec table name.
+    """
+
+    _default_dir = ".tscodekg"
+
+    def __init__(
+        self,
+        repo_root: str | Path,
+        db_path: str | Path | None = None,
+        vectors_path: str | Path | None = None,
+        *,
+        model: str = DEFAULT_MODEL,
+        table: str = "tscodekg_nodes",
+    ) -> None:
+        super().__init__(
+            repo_root,
+            db_path=db_path,
+            model=model,
+            table=table,
+            vector_backend="sqlite-vec",
+        )
+        if vectors_path is not None:
+            self.vectors_path = Path(vectors_path)
+
+    # ------------------------------------------------------------------
+    # KGModule abstract interface
+    # ------------------------------------------------------------------
+
+    def make_extractor(self) -> KGExtractor:
+        include = load_include_dirs(self.repo_root)
+        exclude = load_exclude_dirs(self.repo_root)
+        return TSCodeExtractor(self.repo_root, include=include, exclude=exclude)
+
+    def kind(self) -> str:
+        return "code"
+
+    def analyze(self) -> str:
+        """Run thorough structural analysis and return a Markdown report.
+
+        Uses :class:`~tscode_kg.analysis.TSCodeKGAnalyzer` for a full 14-phase
+        analysis (fan-in, fan-out, module coupling, JSDoc coverage, hierarchy, …).
+        Falls back to a lightweight summary when the KG has not been built yet.
+        """
+        try:
+            from tscode_kg.analysis import TSCodeKGAnalyzer  # noqa: PLC0415
+
+            analyzer = TSCodeKGAnalyzer(self)
+            analyzer.run_analysis()
+            return analyzer.to_markdown()
+        except Exception as exc:  # noqa: BLE001
+            try:
+                return _render_analysis(str(self.repo_root), self.store.stats())
+            except Exception:  # noqa: BLE001
+                return f"# TypeScriptKG Analysis\n\nAnalysis failed: {exc}\n"
+
+    # ------------------------------------------------------------------
+    # TS-specific overrides
+    # ------------------------------------------------------------------
+
+    def _kind_priority(self, kind: str) -> int:
+        return _TS_KIND_PRIORITY.get(kind, 99)
+
+    # ------------------------------------------------------------------
+    # Repr
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        return (
+            f"TypeScriptKG(repo_root={self.repo_root!r}, "
+            f"db_path={self.db_path!r}, "
+            f"vectors_path={self.vectors_path!r}, "
+            f"model={self.model_name!r})"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Analysis renderer
+# ---------------------------------------------------------------------------
+
+
+def _render_analysis(repo_root: str, stats: dict) -> str:
+    """Render a Markdown analysis report from store stats."""
+    lines: list[str] = [
+        "# TypeScriptKG Analysis Report\n",
+        f"**Repository:** `{repo_root}`\n",
+        "---\n",
+        "## Structural Metrics\n",
+        f"- **Total nodes:** {stats.get('total_nodes', 0):,}",
+        f"- **Meaningful nodes:** {stats.get('meaningful_nodes', 0):,}",
+        f"- **Total edges:** {stats.get('total_edges', 0):,}",
+    ]
+
+    cov = stats.get("docstring_coverage")
+    if cov is not None:
+        lines.append(f"- **JSDoc coverage:** {cov:.1%} *(functions + methods)*")
+
+    node_counts: dict = stats.get("node_counts", {})
+    if node_counts:
+        lines.append("\n### Nodes by Kind\n")
+        lines.append("| Kind | Count |")
+        lines.append("|------|------:|")
+        for kind, count in sorted(node_counts.items(), key=lambda x: -x[1]):
+            lines.append(f"| {kind} | {count:,} |")
+
+    edge_counts: dict = stats.get("edge_counts", {})
+    if edge_counts:
+        lines.append("\n### Edges by Relation\n")
+        lines.append("| Relation | Count |")
+        lines.append("|----------|------:|")
+        for rel, count in sorted(edge_counts.items(), key=lambda x: -x[1]):
+            lines.append(f"| {rel} | {count:,} |")
+
+    lines.append("\n---\n")
+    lines.append(
+        "> Graph built by deterministic tree-sitter AST extraction. "
+        "No LLM inference used in indexing."
+    )
+    return "\n".join(lines)