ts-semantic-graph

Callers, callees, symbol references, and module dependencies for TypeScript projects, resolved through the TypeScript compiler instead of text matching. Comes as a lookup CLI, a query daemon, an MCP server, and an importable library.

Requires Node 22.12+ and a TypeScript project.

Install

npm install --global ts-semantic-graph

Library

The same engine the CLI and MCP server use is importable:

import { CodeGraph } from "ts-semantic-graph";

const graph = await CodeGraph.load({
  repositoryRoot: "/path/to/repo",
  tsconfigPath: "/path/to/repo/tsconfig.json",
  backend: "ts7",
});
try {
  const result = await graph.lookup({ filePath: "src/target.ts", functionName: "Primary" });
  // result: GraphResult — status, target, relations with evidence, summary
} finally {
  await graph.dispose();
}

CodeGraph.load resolves paths, applies one validation policy, and picks the backend, so callers pass raw options and nothing else. Concurrent calls are serialized internally; refreshes never interleave with in-flight lookups.

Lookup CLI

# callers and callees, compact text (default)
ts-semantic-graph src/target.ts Primary --repo /path/to/repo

# full graph as JSON, plus references and module queries
ts-semantic-graph src/target.ts Primary --output json --repo /path/to/repo
ts-semantic-graph references src/symbols.ts ExampleInterface --repo /path/to/repo
ts-semantic-graph module src/target.ts --output detailed --repo /path/to/repo

Every query returns a versioned GraphResult: a status (ok, not-found, ambiguous), the target node, directed relations with source evidence, and a summary. --output json prints it unfiltered, which is what scripts and IDE integrations should consume. not-found and ambiguous are normal results, not errors. Pass --line when the same name is declared more than once in a file.

Text output is low-noise by default: known builtin and framework calls are hidden unless --include-builtins, and each section is capped at 12 items unless --max-items says otherwise. detailed adds per-relation evidence.

Daemon

A cold query starts a fresh tsserver each time. For repeated queries against a large project, keep one alive:

ts-semantic-graph serve start \
  --repo /path/to/repo \
  --tsconfig /path/to/repo/tsconfig.json
# { "daemonId": "482731", ... }

ts-semantic-graph serve lookup 482731 src/target.ts Primary
ts-semantic-graph serve references 482731 src/symbols.ts ExampleInterface
ts-semantic-graph serve module 482731 src/target.ts
ts-semantic-graph serve status 482731  # omit the ID to list all daemons
ts-semantic-graph serve stop 482731

Query and stop commands take only the ID; project options belong to serve start and are rejected elsewhere. Relative paths resolve from the daemon's repo root. IDs are ephemeral: if a daemon stops or crashes, start a new one.

MCP server

ts-semantic-graph-mcp \
  --repo /path/to/repo \
  --tsconfig /path/to/repo/tsconfig.json

Exposes lookup_function, find_symbol_references, and inspect_module_dependencies, with the same output, maxItems, and includeBuiltins options as the CLI.

Backends

The default backend is the project's own classic tsserver, discovered from its local TypeScript install. If that fails, pass the entrypoint:

ts-semantic-graph src/bar.ts baz --repo ~/Codes/foo \
  --tsserver ~/Codes/foo/node_modules/typescript/lib/tsserver.js

tsserver picks the nearest tsconfig.json per file, so --tsconfig is optional here; when given, it is only used to verify the expected project was picked up. The bundled TypeScript 7 backend does require it:

ts-semantic-graph src/bar.ts baz \
  --repo ~/Codes/foo --tsconfig ~/Codes/foo/tsconfig.json \
  --backend ts7

--max-old-space-size (default 8192 MB) and --request-timeout-ms tune the tsserver child. All backend options also apply to serve start and the MCP server. tsserver-only options are rejected under --backend ts7.

Limitations

The graph only records relations the compiler can vouch for directly, plus a few narrow patterns (useCallback/useMemo unwrapping, direct JSX renders). It does not infer through state updates, routing, Redux, or network calls.

Development

pnpm install --frozen-lockfile
pnpm test

TSSERVER_PATH=… pnpm test additionally runs the classic-tsserver integration tests against a specific tsserver.