TypeScript code knowledge graphs for AI assistants

What is a TypeScript code knowledge graph?

It is a structural representation of TypeScript files and symbols connected by relationships such as imports, exports, declarations, calls, references, and documentation links. It complements the TypeScript compiler by providing a navigable project map.

• Files become nodes and containers.
• Functions, classes, interfaces, and types can be modeled as symbols.
• Imports, exports, calls, and documentation links become edges.

Why use a graph instead of only TypeScript tooling?

TypeScript tooling answers compiler and type questions precisely inside an editor. A graph adds project-level navigation across modules, documentation, and AI assistant sessions, where the agent needs a compact map of relationships before opening source files.

• See cross-module paths without manually tracing imports.
• Find architecture hubs and dependency cycles.
• Connect implementation to product or design documentation.
• Reuse the same map across assistant sessions.

How do tsconfig files and monorepos affect the graph?

A syntax-level graph can show imports, files, symbols, and call candidates across a monorepo, but it does not replace TypeScript's project references, path aliases, package exports, or compiler module resolution. Teams should keep package boundaries explicit and verify alias and cross-package edges with the compiler.

• Record the package roots and TypeScript project references that define the workspace.
• Verify path aliases such as @app/* against the active tsconfig chain.
• Exclude node_modules, build output, and generated declaration noise.
• Recheck workspace-package imports after moving source files or package entry points.

What TypeScript structure can Graphify extract?

Graphify's documented tree-sitter extraction covers code symbols, imports, exports, and call-graph relationships. TypeScript declarations, interfaces, and type aliases remain source-level facts; assistants should verify them against the compiler and current source.

• Functions, classes, and module declarations.
• Import and export relationships.
• Calls and references between symbols.
• Confidence labels for extracted versus inferred edges.

How should AI assistants query a TypeScript graph?

Ask for paths, callers, dependent modules, or subsystem context before requesting a full file read. Then open the relevant TypeScript source and run the type checker and tests before making changes.

• Start with the changed or unfamiliar symbol.
• Trace reverse dependencies and call paths.
• Use communities to identify package or subsystem boundaries.
• Verify types with the compiler, not the graph alone.

Does a graph replace the TypeScript compiler?

No. The graph is a relationship and navigation layer. The TypeScript compiler remains authoritative for type checking, overload resolution, narrowing, module resolution, and generated diagnostics.

• Use the compiler for correctness.
• Use the graph for architecture and discovery.
• Use tests for runtime behavior.

How do you keep a TypeScript graph fresh?

Rebuild after changing interfaces, package boundaries, imports, generated code, or directory structure. For active repositories, update mode, watch mode, or a Git hook can keep the graph aligned with commits.

• Refresh after large refactors and dependency upgrades.
• Keep generated declaration files out of the graph if they add noise.
• Record the graph revision or timestamp in project instructions.

Which TypeScript questions fit a graph best?

Graph queries fit cross-module relationships: which packages import a symbol, how interfaces connect to implementations, where a service is called, and which modules form a subsystem. They fit poorly for overload resolution, narrowing, conditional types, and precise compiler diagnostics, where TypeScript tooling should answer directly.

• Use the graph for candidate discovery and architecture navigation.
• Use the compiler for semantic type correctness.
• Use tests for runtime behavior.
• Use exact source search for string values and current configuration.

How should a team evaluate a TypeScript graph?

Evaluate it on representative tasks from the actual repository: trace one shared interface, explain a circular dependency, identify callers before an API change, and locate the tests around a service. Compare source evidence and verification time rather than the total node count.

• Test at least one path-alias-heavy package.
• Include a generated-code boundary and one mixed JS/TS module.
• Confirm ambiguous symbols are surfaced rather than silently guessed.
• Repeat after a branch merge to test freshness behavior.

What should a useful TypeScript graph answer contain?

A useful answer names the source revision, queried symbol, relevant files and lines, edge type, and confidence. For a cross-package question it should also identify the package boundary and path alias involved, so the assistant can verify the result against the active TypeScript project configuration.

• Return the exact file and symbol, not only a semantically similar node.
• Distinguish imports, exports, calls, references, and inferred similarity.
• Show whether the edge crosses a package or project-reference boundary.
• Identify ambiguity when several classes, methods, or aliases share a name.
• State the graph revision before the assistant opens source.
• Recommend compiler checks and focused tests for the affected path.

Which TypeScript graph claims are not trustworthy by default?

Treat dynamic imports, reflected decorators, runtime dependency injection, generated clients, and type-only imports as claims to verify. A syntax graph can identify useful candidates, but exact runtime wiring and compiler semantics require project-specific tools. The answer becomes trustworthy when it names the uncertainty and points to the source or compiler evidence that resolves it.

• Do not assume a dynamic import target is statically resolved.
• Do not treat type-only imports as runtime dependencies.
• Do not infer generated-client behavior without checking the generator.
• Do not replace project-reference resolution with path-string similarity.
• Do not trust a call edge that conflicts with the current compiler graph.
• Do not accept a stale graph after interface or package-boundary changes.