tscode-kg 0.4.0__tar.gz → 0.5.1__tar.gz

{tscode_kg-0.4.0 → tscode_kg-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tscode-kg
-Version: 0.4.0
+Version: 0.5.1
 Summary: Knowledge graph for TypeScript/JavaScript codebases — AST extraction, hybrid semantic+structural search
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -19,7 +19,7 @@ Provides-Extra: viz
 Provides-Extra: viz3d
 Requires-Dist: PyQt5 (>=5.15.11,<5.16) ; extra == "viz3d"
 Requires-Dist: click (>=8.1.0,<9)
-Requires-Dist: kgmodule-utils[semantic,sqlite-vec] (>=0.19.1)
+Requires-Dist: kgmodule-utils[semantic,sqlite-vec] (>=0.22.0)
 Requires-Dist: markdown (>=3.10,<3.11) ; extra == "viz3d"
 Requires-Dist: mcp (>=1.0.0,<2)
 Requires-Dist: networkx (>=3.0)
@@ -42,10 +42,10 @@ Description-Content-Type: text/markdown
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
 [![PyPI](https://img.shields.io/pypi/v/tscode-kg.svg)](https://pypi.org/project/tscode-kg/)
-[![Version](https://img.shields.io/badge/version-0.4.0-blue.svg)](https://github.com/Flux-Frontiers/tscode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.5.1-blue.svg)](https://github.com/Flux-Frontiers/tscode_kg/releases)
 [![CI](https://github.com/Flux-Frontiers/tscode_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/tscode_kg/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
-[![DOI](https://zenodo.org/badge/1247715028.svg)](https://zenodo.org/badge/latestdoi/1247715028)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22559450-blue.svg)](https://doi.org/10.5281/zenodo.22559450)
 
 Knowledge graph for TypeScript and JavaScript codebases — deterministic AST extraction, hybrid semantic + structural search.
 
@@ -193,25 +193,23 @@ Eric G. Suchanek, PhD — Flux Frontiers
 
 If you use TypeScriptKG in your research or project, please cite it:
 
-[![DOI](https://zenodo.org/badge/1247715028.svg)](https://zenodo.org/badge/latestdoi/1247715028)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22559450-blue.svg)](https://doi.org/10.5281/zenodo.22559450)
 
-> Suchanek, E. G. (2026). *TypeScriptKG: Semantic Knowledge Graph for TypeScript/JavaScript Codebases* (Version 0.4.0) [Software]. Flux-Frontiers. https://github.com/Flux-Frontiers/tscode_kg
+> Suchanek, E. G. (2026). *TypeScriptKG: Semantic Knowledge Graph for TypeScript/JavaScript Codebases* (Version 0.5.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.22559450
 
 ```bibtex
 @software{suchanek_tscode_kg,
   author    = {Suchanek, Eric G.},
   title     = {{TypeScriptKG}: Semantic Knowledge Graph for TypeScript/JavaScript Codebases},
-  version   = {0.4.0},
+  version   = {0.5.1},
   year      = {2026},
   publisher = {Flux-Frontiers},
+  doi       = {10.5281/zenodo.22559450},
   url       = {https://github.com/Flux-Frontiers/tscode_kg},
 }
 ```
 
-Full citation metadata in [`CITATION.cff`](CITATION.cff). This is the first
-release archived by Zenodo; the DOI resolves via the badge above once the
-archive completes, and this section is updated with the concept DOI directly
-afterward.
+Full citation metadata in [`CITATION.cff`](CITATION.cff).
 
 ## License
 

{tscode_kg-0.4.0 → tscode_kg-0.5.1}/README.md

@@ -3,10 +3,10 @@
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
 [![PyPI](https://img.shields.io/pypi/v/tscode-kg.svg)](https://pypi.org/project/tscode-kg/)
-[![Version](https://img.shields.io/badge/version-0.4.0-blue.svg)](https://github.com/Flux-Frontiers/tscode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.5.1-blue.svg)](https://github.com/Flux-Frontiers/tscode_kg/releases)
 [![CI](https://github.com/Flux-Frontiers/tscode_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/tscode_kg/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
-[![DOI](https://zenodo.org/badge/1247715028.svg)](https://zenodo.org/badge/latestdoi/1247715028)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22559450-blue.svg)](https://doi.org/10.5281/zenodo.22559450)
 
 Knowledge graph for TypeScript and JavaScript codebases — deterministic AST extraction, hybrid semantic + structural search.
 
@@ -154,25 +154,23 @@ Eric G. Suchanek, PhD — Flux Frontiers
 
 If you use TypeScriptKG in your research or project, please cite it:
 
-[![DOI](https://zenodo.org/badge/1247715028.svg)](https://zenodo.org/badge/latestdoi/1247715028)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22559450-blue.svg)](https://doi.org/10.5281/zenodo.22559450)
 
-> Suchanek, E. G. (2026). *TypeScriptKG: Semantic Knowledge Graph for TypeScript/JavaScript Codebases* (Version 0.4.0) [Software]. Flux-Frontiers. https://github.com/Flux-Frontiers/tscode_kg
+> Suchanek, E. G. (2026). *TypeScriptKG: Semantic Knowledge Graph for TypeScript/JavaScript Codebases* (Version 0.5.1) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.22559450
 
 ```bibtex
 @software{suchanek_tscode_kg,
   author    = {Suchanek, Eric G.},
   title     = {{TypeScriptKG}: Semantic Knowledge Graph for TypeScript/JavaScript Codebases},
-  version   = {0.4.0},
+  version   = {0.5.1},
   year      = {2026},
   publisher = {Flux-Frontiers},
+  doi       = {10.5281/zenodo.22559450},
   url       = {https://github.com/Flux-Frontiers/tscode_kg},
 }
 ```
 
-Full citation metadata in [`CITATION.cff`](CITATION.cff). This is the first
-release archived by Zenodo; the DOI resolves via the badge above once the
-archive completes, and this section is updated with the concept DOI directly
-afterward.
+Full citation metadata in [`CITATION.cff`](CITATION.cff).
 
 ## License
 

{tscode_kg-0.4.0 → tscode_kg-0.5.1}/pyproject.toml

@@ -38,7 +38,7 @@ packages = [{ include = "tscode_kg", from = "src" }]
 
 [project]
 name = "tscode-kg"
-version = "0.4.0"
+version = "0.5.1"
 description = "Knowledge graph for TypeScript/JavaScript codebases — AST extraction, hybrid semantic+structural search"
 readme = "README.md"
 license = "Elastic-2.0"
@@ -64,7 +64,11 @@ dependencies = [
     "tree-sitter>=0.25.0",
     "tree-sitter-typescript>=0.23.2",
     "rich>=14.3.3,<15",
-    "kgmodule-utils[semantic,sqlite-vec]>=0.19.1",
+    # 0.20.0 is a hard requirement, not a preference: the whole snapshot
+    # manager is now the package_name class attribute, where it used to be an
+    # __init__ that only forwarded to super(). Against 0.19.x the manager
+    # reports itself as "kg-utils" in every snapshot's tool field.
+    "kgmodule-utils[semantic,sqlite-vec]>=0.22.0",
     "click>=8.1.0,<9",
     # Upper-bounded: mcp 2.0 removed the bundled `mcp.server.fastmcp` module
     # (FastMCP was split out into the standalone `fastmcp` package) and rebuilt
@@ -149,8 +153,13 @@ ruff = ">=0.4.0,<0.16"
 optional = true
 
 [tool.poetry.group.kg.dependencies]
-doc-kg = ">=0.24.1"
-pycode-kg = ">=0.26.0"
+# Both floors are the releases that retired these packages' own snapshot
+# overrides and moved them onto kgmodule-utils>=0.20.0, the same SDK this repo
+# now requires. Pinned lower, `poetry install --with kg` could resolve a dockg
+# or pycodekg predating the shared extension points into the same environment
+# as a tscode_kg that depends on them.
+doc-kg = ">=0.26.0"
+pycode-kg = ">=0.27.1"
 
 [project.urls]
 Homepage = "https://github.com/Flux-Frontiers/tscode_kg"

{tscode_kg-0.4.0 → tscode_kg-0.5.1}/src/tscode_kg/__init__.py

@@ -18,7 +18,7 @@ KGExtractor SDK::
     from tscode_kg import TSCodeExtractor
 """
 
-__version__ = "0.4.0"
+__version__ = "0.5.1"
 __author__ = "Eric G. Suchanek, PhD"
 
 from tscode_kg.extractor import TSCodeExtractor

{tscode_kg-0.4.0 → tscode_kg-0.5.1}/src/tscode_kg/analysis.py

@@ -166,17 +166,60 @@ class TSCodeKGAnalyzer:
         self.coderank_top_nodes: list[dict] = []
         self.concern_analysis: list[dict] = []
         self._phase_result: str = ""
+        #: Phases that could not run, with the reason. Rendered in the report
+        #: so a degraded run says what is missing rather than omitting it.
+        self.phase_failures: list[dict] = []
 
     # ------------------------------------------------------------------
     # Phase runner
     # ------------------------------------------------------------------
 
+    def _take_phase_result(self) -> str:
+        """Read and clear the one-line summary the phase just set.
+
+        Phases report through ``self._phase_result`` rather than a return
+        value, because they are called as bare ``Callable[[], None]``. Reading
+        it here rather than inline in :meth:`_run_phase` also keeps the read
+        away from that method's own ``= ""`` assignment, which a type checker
+        otherwise narrows to a literal it can never see ``fn()`` change.
+        """
+        result = self._phase_result
+        self._phase_result = ""
+        return f"  {result}" if result else ""
+
     def _run_phase(self, num: int, name: str, fn: Callable[[], None]) -> None:
+        """Run one analysis phase, reporting rather than propagating a failure.
+
+        A phase that cannot run must not take the other thirteen and the report
+        with it. The individual phases already guard the errors they expect
+        (``AttributeError``, ``ValueError``, ``RuntimeError``), but the ones
+        worth surviving are the ones nobody predicted -- the concrete case
+        being ``sqlite3.OperationalError: no such table: vec_nodes`` after
+        ``tscodekg build-sqlite``, a supported command that deliberately builds
+        the graph without the vector index. Only phase 4 seeds on a semantic
+        query; the other thirteen are pure SQL and have everything they need.
+        Aborting the run gave the user no report at all, and an error naming
+        an internal table rather than the missing step.
+
+        The failure is recorded in :attr:`phase_failures` and rendered in the
+        report, so a degraded run says which sections are missing and why
+        instead of quietly omitting them.
+        """
         self._phase_result = ""
         t0 = time.monotonic()
-        fn()
+        try:
+            fn()
+        except Exception as exc:  # noqa: BLE001 -- see docstring
+            elapsed = time.monotonic() - t0
+            self.phase_failures.append({"phase": num, "name": name, "error": str(exc)})
+            logger.warning("Phase %d (%s) failed: %s", num, name, exc)
+            self.console.print(
+                f"  [cyan]▶ Phase {num:2d}/{self._TOTAL_PHASES}:[/cyan]"
+                f" {name}  [yellow]skipped: {exc}[/yellow]  [green]({elapsed:.1f}s)[/green]"
+            )
+            return
         elapsed = time.monotonic() - t0
-        result = f"  {self._phase_result}" if self._phase_result else ""
+        result = self._take_phase_result()
         self.console.print(
             f"  [cyan]▶ Phase {num:2d}/{self._TOTAL_PHASES}:[/cyan]"
             f" {name}{result}  [green]({elapsed:.1f}s)[/green]"
@@ -1404,6 +1447,10 @@ Most-called functions and methods — potential bottlenecks or core APIs.
 """
         )
 
+        degraded = self._render_phase_failures()
+        if degraded:
+            report += "\n---\n\n" + degraded + "\n---\n"
+
         for i, metrics in enumerate(
             sorted(self.function_metrics.values(), key=lambda m: m.fan_in, reverse=True)[:15], 1
         ):
@@ -1641,6 +1688,42 @@ Cohesion = incoming-callers / (incoming + outgoing + 1). Higher = more internall
         Path(report_path).write_text(report, encoding="utf-8")
         self.console.print(f"[green]✓[/green] Report written to {report_path}")
 
+    def _render_phase_failures(self) -> str:
+        """Render the degraded-run notice, or an empty string when all phases ran.
+
+        A phase that could not run leaves its section of the report empty. Said
+        plainly, that is a missing build step; left unsaid, it looks like a
+        finding about the codebase.
+        """
+        if not self.phase_failures:
+            return ""
+
+        lines = ["## Incomplete Analysis\n"]
+        lines.append(
+            f"{len(self.phase_failures)} of {self._TOTAL_PHASES} phases could not run. "
+            "The sections they produce are missing from this report — that is a gap in "
+            "the analysis, not a finding about the code.\n"
+        )
+        lines.append("| Phase | Name | Reason |")
+        lines.append("|---|---|---|")
+        for failure in self.phase_failures:
+            lines.append(f"| {failure['phase']} | {failure['name']} | `{failure['error']}` |")
+
+        if any(
+            "vec_nodes" in f["error"]
+            or "no such table" in f["error"]
+            or "Vector store not found" in f["error"]
+            for f in self.phase_failures
+        ):
+            lines.append(
+                "\n> The semantic index is missing. Only the fan-out phase needs it; "
+                "every other phase reads the SQLite graph directly, which is why the "
+                "rest of this report is complete. Run `tscodekg build --repo <path>` "
+                "(or `tscodekg build-index`) to build it, then re-run the analysis."
+            )
+        lines.append("")
+        return "\n".join(lines)
+
     def _compile_results(self) -> dict:
         """Compile all phase results into a serialisable dictionary."""
         sorted_fn = sorted(self.function_metrics.items(), key=lambda kv: kv[1].fan_in, reverse=True)
@@ -1676,6 +1759,10 @@ Cohesion = incoming-callers / (incoming + outgoing + 1). Higher = more internall
             ],
             "centrality_modules": self.centrality_modules,
             "coderank_top_nodes": self.coderank_top_nodes,
+            # A caller reading the dict rather than the Markdown needs the same
+            # signal the report carries: an empty section here means a phase did
+            # not run, not that the codebase has nothing to show.
+            "phase_failures": self.phase_failures,
         }
 
     def to_markdown(self) -> str:
@@ -1693,6 +1780,11 @@ Cohesion = incoming-callers / (incoming + outgoing + 1). Higher = more internall
         out.append(f"**Generated:** {datetime.datetime.now(datetime.UTC).isoformat()}  \n")
         out.append("\n---\n")
 
+        degraded = self._render_phase_failures()
+        if degraded:
+            out.append(degraded)
+            out.append("\n---\n")
+
         out.append("## Baseline Metrics\n")
         out.append("| Metric | Value |")
         out.append("|---|---|")

{tscode_kg-0.4.0 → tscode_kg-0.5.1}/src/tscode_kg/snapshots.py

@@ -4,9 +4,9 @@ snapshots.py — Temporal Snapshots of TypeScriptKG Metrics
 Thin layer over the shared ``kg_utils.snapshots`` module.  The shared module
 provides the canonical ``Snapshot``, ``SnapshotManifest``, ``SnapshotManager``,
 and ``PruneResult`` backed by free-form metric dicts; this module re-exports
-those types and adds a ``SnapshotManager`` subclass that defaults
-``package_name`` to ``"tscode-kg"`` so version auto-detection resolves to this
-package.
+those types and adds a ``SnapshotManager`` subclass whose entire body is the
+``package_name = "tscode-kg"`` class attribute, so version auto-detection
+resolves to this package.
 
 Snapshots are keyed on a caller-supplied release tag or, absent one, a UTC
 timestamp -- never a git tree hash, which is read before ``git add`` stages
@@ -29,8 +29,6 @@ Author: Eric G. Suchanek, PhD
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from kg_utils.snapshots import (
     PruneResult,  # noqa: F401  re-exported
     Snapshot,  # noqa: F401  re-exported
@@ -53,16 +51,12 @@ class SnapshotManager(_BaseSnapshotManager):
     version auto-detection resolves against the installed ``tscode-kg``
     package instead of ``kg-utils``.
 
+    The whole class is one class attribute. It used to be an ``__init__``
+    whose entire body forwarded to ``super()`` to change that one string.
+
     :param snapshots_dir: Directory holding snapshot JSON files and manifest.
     :param package_name: Package whose installed version stamps snapshots.
     :param db_path: Optional SQLite graph path for per-module node counts.
     """
 
-    def __init__(
-        self,
-        snapshots_dir: Path | str,
-        *,
-        package_name: str = "tscode-kg",
-        db_path: Path | str | None = None,
-    ) -> None:
-        super().__init__(snapshots_dir, package_name=package_name, db_path=db_path)
+    package_name = "tscode-kg"