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

tscode_kg-0.4.0/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+**You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.**
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to the
+software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms or the URL for them above, as well as copies of
+any plain-text lines beginning with "Required Notice:" that the licensor provided
+with the software. For example:
+
+Required Notice: Copyright (c) 2026 Eric G. Suchanek, PhD
+
+## No Other Rights
+
+These terms do not imply any other licenses not expressly granted in this
+license.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you with
+a notice of your violation, and you cease all violation of this license no later
+than 30 days after you receive that notice, your licenses will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any
+additional violation of these terms will cause your licenses to terminate
+automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising out
+of these terms or the use or nature of the software, under any kind of legal
+claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion of
+it.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+Control means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.
+
+**Trademark** means trademarks, service marks, and similar rights.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tscode-kg
-Version: 0.2.0
+Version: 0.4.0
 Summary: Knowledge graph for TypeScript/JavaScript codebases — AST extraction, hybrid semantic+structural search
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -15,42 +15,38 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Provides-Extra: dev
-Provides-Extra: kgdeps
 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: detect-secrets (>=1.5.0) ; extra == "dev"
-Requires-Dist: doc-kg (>=0.18.1) ; extra == "kgdeps"
-Requires-Dist: kgmodule-utils[semantic,sqlite-vec] (>=0.8.0)
+Requires-Dist: kgmodule-utils[semantic,sqlite-vec] (>=0.19.1)
 Requires-Dist: markdown (>=3.10,<3.11) ; extra == "viz3d"
 Requires-Dist: mcp (>=1.0.0,<2)
 Requires-Dist: networkx (>=3.0)
 Requires-Dist: param (>=2.4,<2.5) ; extra == "viz3d"
 Requires-Dist: plotly (>=6.8.0,<6.9) ; extra == "viz"
-Requires-Dist: pre-commit (>=4.5.1) ; extra == "dev"
-Requires-Dist: pycode-kg (>=0.20.0,<0.21) ; extra == "dev"
-Requires-Dist: pycode-kg (>=0.20.0,<0.21) ; extra == "kgdeps"
-Requires-Dist: pylint (>=4.0.5) ; extra == "dev"
-Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
-Requires-Dist: pytest-cov (>=5.0.0) ; extra == "dev"
 Requires-Dist: pyvis (>=0.3.2,<0.4) ; extra == "viz"
 Requires-Dist: pyvista (>=0.48.4,<0.49) ; extra == "viz3d"
 Requires-Dist: pyvistaqt (>=0.12,<0.13) ; extra == "viz3d"
 Requires-Dist: rich (>=14.3.3,<15)
-Requires-Dist: ruff (>=0.4.0) ; extra == "dev"
 Requires-Dist: streamlit (>=1.59.0,<1.60) ; extra == "viz"
 Requires-Dist: trame-vtk (>=2.11.8,<2.12) ; extra == "viz3d"
 Requires-Dist: tree-sitter (>=0.25.0)
 Requires-Dist: tree-sitter-typescript (>=0.23.2)
-Requires-Dist: ty (>=0.0.41) ; extra == "dev"
 Project-URL: Homepage, https://github.com/Flux-Frontiers/tscode_kg
 Project-URL: Repository, https://github.com/Flux-Frontiers/tscode_kg
 Description-Content-Type: text/markdown
 
 # TypeScriptKG
 
+[![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)
+[![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)
+
 Knowledge graph for TypeScript and JavaScript codebases — deterministic AST extraction, hybrid semantic + structural search.
 
 ## Overview
@@ -112,7 +108,7 @@ tscodekg framework-nodes --top 20
 tscodekg explain "fn:src/utils/helpers.ts:formatDate"
 
 # Temporal metric snapshots
-tscodekg snapshot save --repo /path/to/ts-repo
+tscodekg snapshot save 0.4.0 --repo /path/to/ts-repo --subject repo:tscode-kg
 tscodekg snapshot list
 
 # Interactive visualizers (install extras: tscode-kg[viz] / tscode-kg[viz3d])
@@ -146,9 +142,12 @@ Repo-local Claude Code skills live in `skills/`.
 
 ## Snapshots & git hook
 
-`tscodekg snapshot save` captures graph metrics (nodes, edges, JSDoc coverage,
-issues, hotspots) keyed by git tree hash into `.tscodekg/snapshots/`, with
-deltas computed against the previous and baseline snapshots.
+`tscodekg snapshot save [VERSION]` captures graph metrics (nodes, edges,
+JSDoc coverage, issues, hotspots) into `.tscodekg/snapshots/`, keyed on
+VERSION -- pass a release tag at release time, or omit it for a UTC
+timestamp key, which is what the per-commit hook below uses. The git tree
+hash is recorded as provenance, not the key. Deltas are computed against
+the previous and baseline snapshots.
 `tscodekg install-hooks` installs a pre-commit hook that rebuilds the index,
 captures a snapshot, stages the snapshot directory, and then runs the
 pre-commit framework checks — so every commit records the state of the
@@ -190,6 +189,30 @@ exclude = ["__tests__"]     # extra dirs to skip
 
 Eric G. Suchanek, PhD — Flux Frontiers
 
+## Citation
+
+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)
+
+> 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
+
+```bibtex
+@software{suchanek_tscode_kg,
+  author    = {Suchanek, Eric G.},
+  title     = {{TypeScriptKG}: Semantic Knowledge Graph for TypeScript/JavaScript Codebases},
+  version   = {0.4.0},
+  year      = {2026},
+  publisher = {Flux-Frontiers},
+  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.
+
 ## License
 
 Elastic-2.0

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

@@ -1,5 +1,13 @@
 # TypeScriptKG
 
+[![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)
+[![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)
+
 Knowledge graph for TypeScript and JavaScript codebases — deterministic AST extraction, hybrid semantic + structural search.
 
 ## Overview
@@ -61,7 +69,7 @@ tscodekg framework-nodes --top 20
 tscodekg explain "fn:src/utils/helpers.ts:formatDate"
 
 # Temporal metric snapshots
-tscodekg snapshot save --repo /path/to/ts-repo
+tscodekg snapshot save 0.4.0 --repo /path/to/ts-repo --subject repo:tscode-kg
 tscodekg snapshot list
 
 # Interactive visualizers (install extras: tscode-kg[viz] / tscode-kg[viz3d])
@@ -95,9 +103,12 @@ Repo-local Claude Code skills live in `skills/`.
 
 ## Snapshots & git hook
 
-`tscodekg snapshot save` captures graph metrics (nodes, edges, JSDoc coverage,
-issues, hotspots) keyed by git tree hash into `.tscodekg/snapshots/`, with
-deltas computed against the previous and baseline snapshots.
+`tscodekg snapshot save [VERSION]` captures graph metrics (nodes, edges,
+JSDoc coverage, issues, hotspots) into `.tscodekg/snapshots/`, keyed on
+VERSION -- pass a release tag at release time, or omit it for a UTC
+timestamp key, which is what the per-commit hook below uses. The git tree
+hash is recorded as provenance, not the key. Deltas are computed against
+the previous and baseline snapshots.
 `tscodekg install-hooks` installs a pre-commit hook that rebuilds the index,
 captures a snapshot, stages the snapshot directory, and then runs the
 pre-commit framework checks — so every commit records the state of the
@@ -139,6 +150,30 @@ exclude = ["__tests__"]     # extra dirs to skip
 
 Eric G. Suchanek, PhD — Flux Frontiers
 
+## Citation
+
+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)
+
+> 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
+
+```bibtex
+@software{suchanek_tscode_kg,
+  author    = {Suchanek, Eric G.},
+  title     = {{TypeScriptKG}: Semantic Knowledge Graph for TypeScript/JavaScript Codebases},
+  version   = {0.4.0},
+  year      = {2026},
+  publisher = {Flux-Frontiers},
+  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.
+
 ## License
 
 Elastic-2.0

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

@@ -4,20 +4,30 @@
 #
 # Build system : Poetry 2.x with PEP 621 [project] table
 #
+# Extras are user-facing features; dev tooling is a Poetry group, so it never
+# ships in the wheel and cannot be pip-installed. See FLEET_STANDARDS.md.
+#
 # Quick install (pip)
 # -------------------
-#   pip install -e ".[dev]"    core + dev tools
-#   pip install -e "."         core runtime only
+#   pip install -e "."                  core runtime only
+#   pip install -e ".[viz]"             + Streamlit/Plotly explorer
+#   pip install -e ".[viz3d]"           + PyVista/PyQt5 3-D visualizer
+#
+# Quick install (poetry)
+# ----------------------
+#   poetry install                      core runtime only
+#   poetry install --with dev           + pytest, ruff, ty, pre-commit
+#   poetry install --with kg            + the pycodekg / dockg CLIs
+#   poetry install --all-extras --with dev,kg    full maintainer environment
 #
 # First-time setup
 # ----------------
-#   python -m venv .venv
-#   source .venv/bin/activate
-#   pip install -e ".[dev]"
+#   poetry install --with dev
 #
 # Build KG indices
 # ----------------
-#   tscodekg build --repo .
+#   tscodekg build --repo .              full rebuild (wipes)
+#   tscodekg update --repo .             incremental upsert
 
 [build-system]
 requires = ["poetry-core>=2.0.0"]
@@ -28,7 +38,7 @@ packages = [{ include = "tscode_kg", from = "src" }]
 
 [project]
 name = "tscode-kg"
-version = "0.2.0"
+version = "0.4.0"
 description = "Knowledge graph for TypeScript/JavaScript codebases — AST extraction, hybrid semantic+structural search"
 readme = "README.md"
 license = "Elastic-2.0"
@@ -54,7 +64,7 @@ dependencies = [
     "tree-sitter>=0.25.0",
     "tree-sitter-typescript>=0.23.2",
     "rich>=14.3.3,<15",
-    "kgmodule-utils[semantic,sqlite-vec]>=0.8.0",
+    "kgmodule-utils[semantic,sqlite-vec]>=0.19.1",
     "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
@@ -67,11 +77,9 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-# Cross-KG: PyCodeKG (Python codebases) and DocKG (docs) available from within tscode_kg
-kgdeps = [
-    "pycode-kg>=0.20.0,<0.21",
-    "doc-kg>=0.18.1",
-]
+# pycode-kg is not an extra: it is never imported by this package, so it does
+# not belong in published metadata. It lives in [tool.poetry.group.kg] below --
+# see that block for why the old "install it by hand" workaround is retired.
 # Streamlit graph explorer + plotly timeline.
 # Version brackets follow pycode_kg's proven lockfile versions.
 viz = [
@@ -93,17 +101,56 @@ viz3d = [
     "pyvistaqt>=0.12,<0.13",
     "trame-vtk>=2.11.8,<2.12",
 ]
-dev = [
-    "detect-secrets>=1.5.0",
-    # This repo is Python — pycodekg indexes it and runs in the pre-commit hook.
-    "pycode-kg>=0.20.0,<0.21",
-    "ty>=0.0.41",
-    "pre-commit>=4.5.1",
-    "pylint>=4.0.5",
-    "pytest>=8.0.0",
-    "pytest-cov>=5.0.0",
-    "ruff>=0.4.0",
-]
+
+# ---------------------------------------------------------------------------
+# Dev tooling (Poetry group, not a PEP 621 extra)
+# ---------------------------------------------------------------------------
+# `optional = true` keeps it out of a bare `poetry install`.
+[tool.poetry.group.dev]
+optional = true
+
+[tool.poetry.group.dev.dependencies]
+detect-secrets = ">=1.5.0"
+ty = ">=0.0.44"
+pre-commit = ">=4.5.1"
+# >=9.0.3 is a security floor, not a preference: GHSA-6w46-j5rx-g56g.
+pytest = ">=9.0.3"
+pytest-cov = ">=5.0.0"
+# Capped below 0.16 to match the fleet: 0.16 formats Python inside Markdown
+# code blocks as stable behaviour. The floor was unbounded, so the lock could
+# drift away from the version .pre-commit-config.yaml pins.
+ruff = ">=0.4.0,<0.16"
+
+# ---------------------------------------------------------------------------
+# Maintainer tooling (Poetry group, not a PEP 621 extra)
+# ---------------------------------------------------------------------------
+# pycode-kg is a tool this repo *runs*, not a library it imports: PyCodeKG
+# indexes this repo's Python source from the outside, via the `pycodekg` CLI in
+# .git/hooks/pre-commit. It belongs in a Poetry group -- locked and installable,
+# but never written into the wheel, so no published extra acquires a sibling.
+#
+# doc-kg rides along for fleet uniformity: every repo's `kg` group carries the
+# same two CLIs, so `poetry install --with kg` means one thing everywhere. This
+# repo has no DocKG index today (no .mcp.json, no `dockg` invocation), so the
+# CLI is simply available rather than required -- and it is here, not in an
+# extra, precisely because nothing depends on it at runtime.
+#
+#   poetry install --with kg      # get the pycodekg CLI into .venv/bin
+#   poetry install                # default: group is optional, skipped
+#
+# This supersedes the standing "install it by hand" workaround. That note
+# described a real deadlock -- older pycode-kg capped transformers below 4.57
+# while kgmodule-utils >=0.9.0 needs >=5.5.0, which silently held this repo on
+# the pre-CVE transformers line. pycode-kg 0.21.4 no longer pins transformers at
+# all; it inherits the same kgmodule-utils[semantic] constraint this project
+# already uses, so the two no longer conflict. Verified: locking with this group
+# keeps transformers at 5.14.1.
+[tool.poetry.group.kg]
+optional = true
+
+[tool.poetry.group.kg.dependencies]
+doc-kg = ">=0.24.1"
+pycode-kg = ">=0.26.0"
 
 [project.urls]
 Homepage = "https://github.com/Flux-Frontiers/tscode_kg"
@@ -113,6 +160,9 @@ Repository = "https://github.com/Flux-Frontiers/tscode_kg"
 tscodekg                = "tscode_kg.cli.main:cli"
 tscodekg-analyze        = "tscode_kg.cli.cmd_analyze:analyze"
 tscodekg-build          = "tscode_kg.cli.cmd_build:build"
+tscodekg-update         = "tscode_kg.cli.cmd_build:update"
+tscodekg-build-sqlite   = "tscode_kg.cli.cmd_build:build_sqlite"
+tscodekg-build-index    = "tscode_kg.cli.cmd_build:build_index"
 tscodekg-centrality     = "tscode_kg.cli.cmd_centrality:centrality"
 tscodekg-download-model = "tscode_kg.cli.cmd_model:download_model"
 tscodekg-init           = "tscode_kg.cli.cmd_init:init"

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

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

tscode_kg-0.4.0/src/tscode_kg/cli/cmd_build.py

@@ -0,0 +1,229 @@
+"""
+cli/cmd_build.py — tscodekg build / update commands.
+
+Builds the SQLite graph and sqlite-vec vector index from a TypeScript/JS repo.
+
+Two commands, not one command with a flag, mirroring ``pycodekg``:
+
+* ``build``  wipes existing data and rebuilds from scratch.
+* ``update`` upserts changes without wiping.
+
+The split matters because the two are different operations, not a switch on
+one. A rebuild is correct after renames or deletions, where an upsert leaves
+phantom nodes behind — the vector store upserts by node ID, so a renamed
+symbol keeps its old entry forever. Making the safe operation the bare verb
+means the surprising outcome has to be asked for by name.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+def _build_options(fn):
+    """Apply the option set shared by ``build`` and ``update``."""
+    for option in reversed(
+        [
+            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(
+                "--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.",
+            ),
+        ]
+    ):
+        fn = option(fn)
+    return fn
+
+
+def _run(
+    *,
+    repo: str,
+    db: str | None,
+    vectors: str | None,
+    graph_only: bool,
+    index_only: bool,
+    wipe: bool,
+) -> None:
+    """Shared body for ``build`` and ``update``."""
+    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(f"[bold]TypeScriptKG {'build' if wipe else 'update'}[/bold]")
+    console.print(f"  repo    : {repo_path}")
+    console.print(f"  db      : {kg.db_path}")
+    console.print(f"  vectors : {kg.vectors_path}")
+    console.print(f"  mode    : {'full rebuild (wipes)' if wipe else 'incremental upsert'}")
+    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
+
+
+@click.command("build")
+@_build_options
+def build(
+    repo: str,
+    db: str | None,
+    vectors: str | None,
+    graph_only: bool,
+    index_only: bool,
+) -> None:
+    """Build knowledge graph from scratch: wipes existing data, then extracts
+    TypeScript/JS AST -> graph store -> vector index."""
+    _run(
+        repo=repo,
+        db=db,
+        vectors=vectors,
+        graph_only=graph_only,
+        index_only=index_only,
+        wipe=True,
+    )
+
+
+@click.command("update")
+@_build_options
+def update(
+    repo: str,
+    db: str | None,
+    vectors: str | None,
+    graph_only: bool,
+    index_only: bool,
+) -> None:
+    """Update knowledge graph incrementally: upserts changes without wiping
+    existing data."""
+    _run(
+        repo=repo,
+        db=db,
+        vectors=vectors,
+        graph_only=graph_only,
+        index_only=index_only,
+        wipe=False,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Granular stages, mirroring `pycodekg build-sqlite` / `pycodekg build-index`
+# ---------------------------------------------------------------------------
+# These reach the same two halves as `build --graph-only` / `build --index-only`,
+# exposed under the names pycodekg uses so the two CLIs read alike. Unlike
+# `build`/`update` they keep `--wipe`: a stage is a lower-level tool than a
+# verb, and pycodekg's stages carry the flag too.
+#
+# One deliberate divergence: pycodekg names this option `--db` on build-sqlite
+# but `--sqlite` on build-index, an inconsistency its own skill documents as a
+# common mistake. Both spellings are accepted here, so muscle memory from
+# either CLI works and neither is a trap.
+
+
+@click.command("build-sqlite")
+@click.option("--repo", default=".", show_default=True, help="Repository root directory.")
+@click.option(
+    "--db",
+    "--sqlite",
+    "db",
+    default=None,
+    help="SQLite database path (default: <repo>/.tscodekg/graph.sqlite).",
+)
+@click.option(
+    "--wipe",
+    is_flag=True,
+    default=False,
+    help="Clear existing graph data before extracting.",
+)
+def build_sqlite(repo: str, db: str | None, wipe: bool) -> None:
+    """Extract a TypeScript/JS knowledge graph and store it in SQLite.
+
+    The graph half of `build`; skips the vector index.
+    """
+    _run(
+        repo=repo,
+        db=db,
+        vectors=None,
+        graph_only=True,
+        index_only=False,
+        wipe=wipe,
+    )
+
+
+@click.command("build-index")
+@click.option("--repo", default=".", show_default=True, help="Repository root directory.")
+@click.option(
+    "--sqlite",
+    "--db",
+    "db",
+    default=None,
+    help="Path to the existing SQLite graph (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 the existing vector store before indexing.",
+)
+def build_index(repo: str, db: str | None, vectors: str | None, wipe: bool) -> None:
+    """Build the sqlite-vec semantic index from an existing SQLite graph.
+
+    The index half of `build`; the graph must already exist.
+    """
+    _run(
+        repo=repo,
+        db=db,
+        vectors=vectors,
+        graph_only=False,
+        index_only=True,
+        wipe=wipe,
+    )

tscode_kg-0.4.0/src/tscode_kg/cli/cmd_hooks.py

@@ -0,0 +1,172 @@
+"""
+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 — runs quality checks. The index rebuild and
+# metrics snapshot are opt-in and OFF by default; see "Why snapshots are off".
+# Installed by: tscodekg install-hooks
+#
+#   TSCODEKG_SNAPSHOT=1 git commit ...        opt in to a per-commit snapshot
+#   TSCODEKG_SKIP_SNAPSHOT=1 git commit ...   force snapshots off (wins)
+#
+# Note that TSCODEKG_SKIP_SNAPSHOT no longer skips the quality checks. It used
+# to short-circuit the whole hook, so a variable named "skip snapshot" also
+# silently skipped ruff, ty and pytest. It now gates only what it names.
+#
+# Why snapshots are off by default (2026-08-18)
+# ---------------------------------------------
+# A per-commit snapshot records `git write-tree` and is then itself staged into
+# that same commit. Staging changes the index, so the recorded hash can never
+# equal the tree it claims to describe — and manifest.json carries a
+# `last_update` timestamp, so the `git add` is never a no-op. The drift is
+# guaranteed by construction, not caused by formatting.
+#
+# An audit of 605 snapshots across 29 fleet manifests found 63 (10.4%) keyed to
+# a tree any commit actually has. `snapshot diff` between adjacent entries has
+# therefore been comparing states that never existed.
+#
+# The fix is to snapshot at release, keyed on the tag rather than on an
+# ephemeral pre-commit tree. See kgrag_priv/docs/SNAPSHOT_STRATEGY.md. Until
+# that lands, this hook runs quality checks only.
+#
+# This hook also used to run the rebuild and snapshot BEFORE the quality
+# checks, which is the opposite of what it should do:
+#
+#   * `pre-commit run` stashes unstaged changes and restores them afterwards.
+#     Building first meant the freshly-rewritten snapshots/manifest.json landed
+#     inside the stash window, where the restore could fail with "patch does not
+#     apply" and abort the commit outright — or, worse, let a staged deletion of
+#     a tracked snapshot slip into the commit.
+#   * There is no reason to pay for an index rebuild on a commit that
+#     ruff/ty/pytest is about to reject.
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+# Quality checks first (ruff, ty, pytest, detect-secrets, ...). Delegates to
+# .pre-commit-config.yaml so quality checks stay in one place. A hook that
+# rewrites files also exits non-zero here, so we never index a tree that is
+# about to be reformatted.
+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
+
+# ---------------------------------------------------------------------------
+# Opt-in index rebuild + snapshot. Everything below is skipped unless
+# TSCODEKG_SNAPSHOT=1 is set, and is skipped regardless if
+# TSCODEKG_SKIP_SNAPSHOT=1.
+# ---------------------------------------------------------------------------
+[ "${TSCODEKG_SNAPSHOT:-0}" = "1" ] || exit 0
+[ "${TSCODEKG_SKIP_SNAPSHOT:-0}" = "1" ] && exit 0
+
+# 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" >&2
+    exit 0
+fi
+
+# Captured after the checks so nothing further modifies the working tree. Note
+# the caveat above: this still cannot match the committed tree, because the
+# `git add` below changes the index after this point.
+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. These files are
+# added after `pre-commit run`, so they are not scanned by it — detect-secrets
+# already excludes snapshots/ by config, which is why that is safe.
+git add .tscodekg/snapshots/ 2>/dev/null || true
+
+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("  Quality checks run on every commit.")
+    click.echo("  Snapshots are OFF by default - see kgrag_priv/docs/SNAPSHOT_STRATEGY.md.")
+    click.echo("  Opt in with:  TSCODEKG_SNAPSHOT=1 git commit ...")
+    click.echo("  Force off:    TSCODEKG_SKIP_SNAPSHOT=1 git commit ...")
+    click.echo("  Run 'tscodekg build' first if you haven't built the graph yet.")

{tscode_kg-0.2.0 → tscode_kg-0.4.0}/src/tscode_kg/cli/cmd_snapshot.py

@@ -62,7 +62,13 @@ def _default_snapshots_dir(snapshots_dir: str | None, repo_root: Path | None = N
     "--tree-hash",
     default="",
     type=str,
-    help="Git tree hash; auto-detected if not provided.",
+    help="Git tree hash, recorded as provenance; auto-detected if not provided.",
+)
+@click.option(
+    "--subject",
+    default="",
+    type=str,
+    help="What was measured, e.g. 'repo:tscode-kg'.",
 )
 def save_snapshot(
     version: str | None,
@@ -71,20 +77,23 @@ def save_snapshot(
     snapshots_dir: str | None,
     branch: str | None,
     tree_hash: str,
+    subject: str,
 ) -> None:
     """
     Capture current TypeScriptKG metrics and save as a temporal snapshot.
 
     Reads graph statistics and JSDoc coverage from the SQLite graph, runs the
-    analyzer for issue counts and hotspots, then saves a snapshot tagged with
-    the given VERSION.  The tree hash is auto-detected from git when not
-    provided.
+    analyzer for issue counts and hotspots, then saves a snapshot keyed on
+    VERSION. Omit VERSION and the snapshot is keyed on a UTC timestamp, which
+    is the right answer for a corpus with no release tag. The tree hash is
+    recorded as provenance and auto-detected from git when not provided; it
+    is not the key.
 
-    Snapshots are stored in .tscodekg/snapshots/{tree_hash}.json, with a
+    Snapshots are stored in .tscodekg/snapshots/{key}.json, with a
     manifest.json tracking all snapshots and their metrics.
 
     Example:
-        tscodekg snapshot save 0.1.0 --repo .
+        tscodekg snapshot save 0.1.0 --repo . --subject repo:tscode-kg
     """
     capture_snapshot(
         version=version,
@@ -93,6 +102,7 @@ def save_snapshot(
         snapshots_dir=snapshots_dir,
         branch=branch,
         tree_hash=tree_hash,
+        subject=subject,
     )
 
 
@@ -104,15 +114,22 @@ def capture_snapshot(
     snapshots_dir: str | None,
     branch: str | None,
     tree_hash: str,
+    subject: str = "",
 ) -> None:
     """Capture and persist a snapshot; shared by ``snapshot save`` and ``init``.
 
-    :param version: Version tag; auto-detected from the package when falsy.
+    :param version: Release tag, becoming the snapshot's key; auto-detected
+        from the installed package when falsy, which then yields a UTC
+        timestamp key instead -- the right answer for a corpus, not a repo
+        release. Never used as the key without being explicitly passed here.
     :param repo: Repository root path.
     :param db: SQLite graph path; defaults to ``<repo>/.tscodekg/graph.sqlite``.
     :param snapshots_dir: Snapshots directory; defaults to ``<repo>/.tscodekg/snapshots``.
     :param branch: Branch name; auto-detected when ``None``.
-    :param tree_hash: Git tree hash; auto-detected when empty.
+    :param tree_hash: Git tree hash, recorded as provenance; auto-detected
+        when empty. It is not the snapshot's key.
+    :param subject: What was measured, e.g. ``repo:tscode-kg``. Recorded
+        separately from ``version``, which names the measuring tool.
     """
     from tscode_kg.kg import TypeScriptKG  # pylint: disable=import-outside-toplevel
     from tscode_kg.snapshots import SnapshotManager  # pylint: disable=import-outside-toplevel
@@ -171,6 +188,10 @@ def capture_snapshot(
         hotspots=hotspots,
         issues=issue_strings,
         tree_hash=tree_hash,
+        # An explicit VERSION is a release tag and becomes the key. An
+        # auto-detected one is the measuring tool's version and must not be.
+        key=version or "",
+        subject=subject,
     )
 
     snapshot_file = snap_mgr.save_snapshot(snapshot_obj)

{tscode_kg-0.2.0 → tscode_kg-0.4.0}/src/tscode_kg/cli/main.py

@@ -19,7 +19,7 @@ import click
 
 from tscode_kg.cli.cmd_analyze import analyze
 from tscode_kg.cli.cmd_bridges import bridges
-from tscode_kg.cli.cmd_build import build
+from tscode_kg.cli.cmd_build import build, build_index, build_sqlite, update
 from tscode_kg.cli.cmd_centrality import centrality
 from tscode_kg.cli.cmd_explain import explain
 from tscode_kg.cli.cmd_framework_nodes import framework_nodes
@@ -40,6 +40,9 @@ def cli() -> None:
 
 cli.add_command(init)
 cli.add_command(build)
+cli.add_command(update)
+cli.add_command(build_sqlite)
+cli.add_command(build_index)
 cli.add_command(query)
 cli.add_command(pack)
 cli.add_command(analyze)

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

@@ -8,15 +8,19 @@ those types and adds a ``SnapshotManager`` subclass that defaults
 ``package_name`` to ``"tscode-kg"`` so version auto-detection resolves to this
 package.
 
-Snapshots are stored in ``.tscodekg/snapshots/{tree_hash}.json`` with a
-``manifest.json`` tracking all snapshots and their metrics — the same layout
-PyCodeKG uses under ``.pycodekg/snapshots/``.
+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
+the snapshot and so names a tree that is never committed. Stored in
+``.tscodekg/snapshots/{key}.json`` with a ``manifest.json`` tracking all
+snapshots and their metrics — the same layout PyCodeKG uses under
+``.pycodekg/snapshots/``.
 
 Usage
 -----
 >>> from tscode_kg.snapshots import SnapshotManager
 >>> mgr = SnapshotManager(".tscodekg/snapshots")
->>> snapshot = mgr.capture(version="0.1.0", branch="develop", graph_stats_dict=stats)
+>>> snapshot = mgr.capture(version="0.4.0", branch="main", key="0.4.0",
+...                         subject="repo:tscode-kg", graph_stats_dict=stats)
 >>> mgr.save_snapshot(snapshot)
 >>> manifest = mgr.load_manifest()
 

tscode_kg-0.2.0/LICENSE

@@ -1,24 +0,0 @@
-BSD 2-Clause License
-
-Copyright (c) 2026, Flux-Frontiers
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

tscode_kg-0.2.0/src/tscode_kg/cli/cmd_build.py

@@ -1,86 +0,0 @@
-"""
-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-0.2.0/src/tscode_kg/cli/cmd_hooks.py

@@ -1,125 +0,0 @@
-"""
-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.")