TypeScriptKG

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

Edge types

Quick start

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

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:

[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:

Suchanek, E. G. (2026). TypeScriptKG: Semantic Knowledge Graph for TypeScript/JavaScript Codebases (Version 0.7.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.22559450

@software{suchanek_tscode_kg,
  author    = {Suchanek, Eric G.},
  title     = {{TypeScriptKG}: Semantic Knowledge Graph for TypeScript/JavaScript Codebases},
  version   = {0.7.0},
  year      = {2026},
  publisher = {Flux-Frontiers},
  doi       = {10.5281/zenodo.22559450},
  url       = {https://github.com/Flux-Frontiers/tscode_kg},
}

Full citation metadata in CITATION.cff.

License

Elastic-2.0