Metadata-Version: 2.4
Name: tscode-kg
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
Keywords: knowledge-graph,typescript,javascript,ast,sqlite-vec,sqlite,semantic-search
Author: Eric G. Suchanek, PhD
Author-email: suchanek@mac.com
Requires-Python: >=3.12,<3.14
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
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: 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.22.0)
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: 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: 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)
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.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://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.

## Overview

TypeScriptKG builds a queryable knowledge graph from TypeScript/JavaScript source code using:

- **tree-sitter** for deterministic, parser-level AST extraction (no LLM inference during indexing)
- **SQLite** for the structural graph (nodes, edges, provenance)
- **sqlite-vec** for the semantic vector index (embeddings via `BAAI/bge-small-en-v1.5`)
- **Hybrid retrieval**: semantic seed → graph hop expansion → lexical re-ranking

## Node types

| Kind | Description |
|------|-------------|
| `module` | Every indexed `.ts`/`.tsx`/`.js`/`.jsx` file |
| `class` | Class declaration |
| `interface` | TypeScript interface |
| `type_alias` | TypeScript type alias |
| `enum` | TypeScript enum |
| `namespace` | TypeScript namespace / module declaration |
| `function` | Module-level function (declaration or `const` arrow) |
| `method` | Method or accessor within a class |
| `symbol` | Unresolved external import stub |

## Edge types

| Relation | Description |
|----------|-------------|
| `CONTAINS` | module → class/function/interface… |
| `IMPORTS` | module → module |
| `CALLS` | function/method → function |
| `INHERITS` | class extends class |
| `IMPLEMENTS` | class implements interface |
| `EXTENDS` | interface extends interface |

## Quick start

```bash
pip install tscode-kg

# First-time setup (downloads model, builds graph, installs hooks, snapshots)
tscodekg init --repo /path/to/ts-repo

# Build the KG for a TypeScript repo
tscodekg build --repo /path/to/ts-repo

# Query
tscodekg query "authentication middleware"
tscodekg pack "error handling utilities" --hop 2

# Thorough architectural analysis (fan-in/out, CodeRank, SIR centrality, JSDoc coverage)
tscodekg analyze /path/to/ts-repo --report analysis.md

# Structural rankings and node explanations
tscodekg centrality --top 20
tscodekg bridges --top 20
tscodekg framework-nodes --top 20
tscodekg explain "fn:src/utils/helpers.ts:formatDate"

# Temporal metric snapshots
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])
tscodekg viz --port 8500
tscodekg viz3d --layout allium
tscodekg viz-timeline --type 2d

# Install the pre-commit snapshot hook
tscodekg install-hooks --repo /path/to/ts-repo

# MCP server (Claude Desktop, Cursor, etc.)
tscodekg mcp --repo /path/to/ts-repo
```

Each subcommand is also available as a dedicated script alias — `tscodekg-init`,
`tscodekg-build`, `tscodekg-query`, `tscodekg-pack`, `tscodekg-analyze`,
`tscodekg-centrality`, `tscodekg-viz`, `tscodekg-viz3d`, `tscodekg-viz-timeline`,
`tscodekg-install-hooks`, `tscodekg-download-model`, `tscodekg-mcp` — both forms
are equivalent.

## MCP tools

The MCP server exposes the full PyCodeKG toolkit, applied to TypeScript/JavaScript
codebases: `graph_stats`, `query_codebase`, `pack_snippets`, `callers`, `get_node`,
`list_nodes`, `find_node`, `centrality`, `bridge_centrality`, `framework_nodes`,
`find_definition_at`, `analyze_repo`, `explain`, `rank_nodes`, `query_ranked`,
`explain_rank`, `snapshot_list`, `snapshot_show`, and `snapshot_diff`.

See `docs/MCP.md` for setup and `docs/CHEATSHEET.md` for a query cookbook.
Repo-local Claude Code skills live in `skills/`.

## Snapshots & git hook

`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
knowledge graph. Skip it for one commit with `TSCODEKG_SKIP_SNAPSHOT=1`.

## Python API

```python
from tscode_kg import TypeScriptKG

kg = TypeScriptKG(repo_root="/path/to/ts-repo")
stats = kg.build(wipe=True)

result = kg.query("authentication middleware", k=8)
result.print_summary()

pack = kg.pack("error handling", k=8, hop=1)
pack.save("context.md")
```

## Architecture

TypeScriptKG is a domain implementation of the `KGModule` base class from `kgmodule-utils`.
Only the TypeScript/JS-specific extraction layer is implemented here — all generic
infrastructure (SQLite, sqlite-vec, hybrid query, snippet packing) is inherited from
`KGModule`.

## Configuration

In your project's `pyproject.toml`:

```toml
[tool.tscodekg]
include = ["src"]           # top-level dirs to index (empty = all)
exclude = ["__tests__"]     # extra dirs to skip
```

## Author

Eric G. Suchanek, PhD — Flux Frontiers

## Citation

If you use TypeScriptKG in your research or project, please cite it:

[![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.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.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).

## License

Elastic-2.0

