typegraph-mcp 0.9.0

package/skills/code-exploration/SKILL.md

@@ -0,0 +1,55 @@
+# Code Exploration Workflow
+
+Efficiently explore unfamiliar TypeScript code using navigation tools instead of reading entire files.
+
+## When to Activate
+
+- User asks "how does X work?" or "walk me through the code for X"
+- Exploring a new codebase or unfamiliar module
+- Understanding the architecture or data flow of a feature
+- Tracing a request from API handler to database
+
+## Workflow
+
+### Step 1: Find the Entry Point
+If you know the symbol name but not the file:
+- Call `ts_navigate_to` with the symbol name
+
+If you know the file:
+- Call `ts_module_exports` to see what the file provides
+- Call `ts_find_symbol` to locate a specific symbol within it
+
+### Step 2: Understand the Type
+Call `ts_type_info` on the entry point symbol. This gives you the full type signature and documentation without reading the entire file.
+
+### Step 3: Trace the Implementation
+Call `ts_trace_chain` to follow the definition chain from the entry point to the implementation. Each hop shows the file, line, and a code preview.
+
+### Step 4: Explore the Neighborhood
+Call `ts_subgraph` with the key files discovered in step 3 to see the surrounding module structure. Use `direction: "both"` and `depth: 1` for immediate context.
+
+### Step 5: Deep Dive Where Needed
+Only now, read specific files at the lines identified by the tools. You have precise coordinates — no need to read entire files.
+
+## Key Principle
+
+**Never start by reading entire files.** Use navigation tools to find the exact lines that matter, then read only those lines. This saves context tokens and produces more accurate understanding.
+
+## Example
+
+```
+User: "How does the magic link authentication flow work?"
+
+1. ts_navigate_to({ symbol: "MagicLinkHandler" })
+   -> Found in apps/core-api/src/entrypoints/magic-link.ts
+
+2. ts_type_info -> Shows handler signature with ClaimToken input, AuthResult output
+
+3. ts_trace_chain -> 4 hops:
+   magic-link.ts -> ClaimService.ts -> TokenRepository.ts -> tenant-context.ts
+
+4. ts_subgraph({ files: [those 4 files], depth: 1 })
+   -> Shows AuthService and NotificationService also connect to ClaimService
+
+5. Read the specific lines at each hop to explain the flow
+```

package/skills/dependency-audit/SKILL.md

@@ -0,0 +1,50 @@
+# Dependency Audit Workflow
+
+Audit module dependencies to find circular imports, analyze coupling, and understand the dependency structure.
+
+## When to Activate
+
+- User asks about circular dependencies or import cycles
+- User wants to understand the module structure or dependency graph
+- User asks about coupling between packages or modules
+- Debugging import-related issues (circular deps, missing exports)
+- Evaluating module boundaries for extraction or reorganization
+
+## Workflow
+
+### Step 1: Detect Cycles
+Call `ts_import_cycles` (no filter for project-wide, or with a file/package filter for targeted analysis).
+
+### Step 2: Analyze Hotspots
+For each cycle found, call `ts_dependency_tree` on the files in the cycle to understand why the cycle exists (what each file needs from the other).
+
+### Step 3: Measure Coupling
+Call `ts_module_boundary` on the package or directory you want to analyze. The isolation score quantifies how self-contained it is:
+- **> 0.7**: Well isolated
+- **0.3 - 0.7**: Moderate coupling
+- **< 0.3**: Tightly coupled (candidate for restructuring)
+
+### Step 4: Map Cross-Package Dependencies
+Call `ts_dependents` on key files to see the cross-package dependency picture. The `byPackage` grouping shows which packages depend on what.
+
+### Step 5: Report
+Present findings as:
+1. **Cycles found** (count + file lists)
+2. **Coupling scores** (per module/directory)
+3. **Cross-package dependencies** (dependency direction violations, if any)
+4. **Recommendations** (break cycles, reduce coupling, extract modules)
+
+## Example
+
+```
+User: "Are there any circular dependencies in the project?"
+
+1. ts_import_cycles() -> 1 cycle: TodoService.ts <-> TodoHistoryService.ts
+2. ts_dependency_tree({ file: "TodoService.ts" }) -> imports TodoHistoryService for history recording
+   ts_dependency_tree({ file: "TodoHistoryService.ts" }) -> imports TodoService for status lookup
+3. ts_module_boundary({ files: [services directory files] }) -> isolation: 0.42 (moderate)
+
+Report: 1 circular dependency found between TodoService and TodoHistoryService.
+        Root cause: mutual dependency for history recording + status lookup.
+        Recommendation: Extract shared types into a separate file to break the cycle.
+```

package/skills/impact-analysis/SKILL.md

@@ -0,0 +1,52 @@
+# Impact Analysis Workflow
+
+Analyze the impact of changing a TypeScript symbol by combining blast radius, dependents, and module boundary analysis.
+
+## When to Activate
+
+- User asks "what will break if I change X?"
+- User asks about the impact or blast radius of a change
+- Before modifying a widely-used symbol, type, or interface
+- Assessing risk of a refactor
+
+## Workflow
+
+### Step 1: Blast Radius
+Call `ts_blast_radius` with the file and symbol to get direct callers and affected files.
+
+### Step 2: Assess Scope
+- If **< 5 callers**: Low impact. Report the callers and you're done.
+- If **5-20 callers**: Medium impact. Proceed to step 3 for package breakdown.
+- If **> 20 callers**: High impact. Proceed to steps 3 and 4.
+
+### Step 3: Package Breakdown
+Call `ts_dependents` on the file to see the transitive impact grouped by package. This shows whether the change is contained to one package or crosses boundaries.
+
+### Step 4: Module Boundary (for high-impact changes)
+Call `ts_module_boundary` with the affected files to understand the coupling. A low isolation score means the change is tightly coupled to external code.
+
+### Step 5: Report
+Present findings as:
+1. **Direct callers** (count + file list)
+2. **Packages affected** (from dependents breakdown)
+3. **Risk assessment** (low/medium/high based on caller count and cross-package spread)
+4. **Suggested approach** (safe migration steps if high impact)
+
+## Example
+
+```
+User: "What happens if I change the TenantId schema?"
+
+1. ts_blast_radius({ file: "packages/core/src/schemas/ids.ts", symbol: "TenantId" })
+   -> 45 direct callers across 28 files
+
+2. ts_dependents({ file: "packages/core/src/schemas/ids.ts" })
+   -> 158 transitive dependents across 4 packages
+
+3. ts_module_boundary({ files: ["packages/core/src/schemas/ids.ts"] })
+   -> isolation score: 0.058 (highly coupled)
+
+Report: HIGH IMPACT. 45 direct usages across 28 files in 4 packages.
+        The schemas module has very low isolation (0.058).
+        Recommend: add new schema alongside old, migrate callers incrementally, then remove old.
+```

package/skills/refactor-safety/SKILL.md

@@ -0,0 +1,50 @@
+# Refactor Safety Check Workflow
+
+Verify a refactor is safe before making changes by checking call chains, circular dependencies, and module boundaries.
+
+## When to Activate
+
+- User is about to rename, move, or restructure TypeScript modules
+- User asks "is it safe to refactor X?"
+- Before extracting code into a new module or package
+- Before changing an interface or service definition
+
+## Workflow
+
+### Step 1: Trace the Chain
+Call `ts_trace_chain` on the symbol being refactored to understand its full definition chain. This reveals all the layers of indirection the refactor needs to preserve.
+
+### Step 2: Check for Cycles
+Call `ts_import_cycles` filtered to the file being refactored. If the file participates in a cycle, the refactor must not break or worsen it.
+
+### Step 3: Assess Boundaries
+Call `ts_module_boundary` with the files involved in the refactor (source + destination). Check:
+- **Incoming edges**: Other code that imports from these files (must be preserved)
+- **Outgoing edges**: Dependencies these files need (must be available at new location)
+- **Isolation score**: How self-contained the module is
+
+### Step 4: Verify References
+Call `ts_references` on the key symbol to get the complete list of call sites that need updating.
+
+### Step 5: Report
+Present a safety assessment:
+1. **Definition chain** (what indirection exists)
+2. **Cycle involvement** (any circular dependencies to be aware of)
+3. **Boundary analysis** (incoming/outgoing edges, isolation)
+4. **Call sites to update** (complete list from references)
+5. **GO / CAUTION / STOP** recommendation
+
+## Example
+
+```
+User: "I want to move AuthService from packages/core to apps/gateway"
+
+1. ts_trace_chain -> AuthService defined in core, consumed via Layer in gateway
+2. ts_import_cycles -> No cycles involving AuthService.ts
+3. ts_module_boundary -> 12 incoming edges (other core modules import it), 3 outgoing
+4. ts_references -> 23 references across 15 files
+
+CAUTION: AuthService has 12 incoming edges within packages/core.
+         Moving it to apps/gateway would break the core -> gateway dependency direction.
+         Consider: keep the interface in core, move only the Live implementation.
+```

package/skills/tool-selection/SKILL.md

@@ -0,0 +1,79 @@
+# TypeGraph Tool Selection Guide
+
+Select the right typegraph-mcp tool for the task at hand. These tools provide type-aware TypeScript navigation — use them instead of grep/glob for any TypeScript codebase navigation.
+
+## When to Activate
+
+- Navigating TypeScript code (finding definitions, references, types)
+- Exploring unfamiliar code or understanding how modules connect
+- Preparing to refactor or modify TypeScript symbols
+- Answering questions about code structure, dependencies, or impact
+- Any task where you would otherwise use grep/glob to find TypeScript symbols
+
+## Tool Selection Decision Tree
+
+### "Where is X defined?"
+Use **ts_definition** with the file + symbol name (or line+column). Resolves through barrel files, re-exports, and project references.
+
+### "I don't know which file X is in"
+Use **ts_navigate_to** with just the symbol name. Searches the entire project. For object literal keys (like RPC handlers), also pass a `file` hint.
+
+### "What is the type of X?"
+Use **ts_type_info** — returns the same info as hovering in VS Code. Includes documentation.
+
+### "What are all the exports of this file?"
+Use **ts_module_exports** — lists all exported symbols with their resolved types.
+
+### "Where is X used?"
+Use **ts_references** for all semantic references. Unlike grep, this returns only real code references, not string matches in comments or unrelated variables.
+
+### "What breaks if I change X?"
+Use **ts_blast_radius** — finds all usage sites and groups them by file. This is the starting point for impact analysis.
+
+### "How does the code get from A to B?"
+Use **ts_trace_chain** — follows go-to-definition hops automatically, building a call chain. Stops at the bottom of the chain or at node_modules boundaries.
+
+### "What does this file import?"
+Use **ts_dependency_tree** for the transitive import tree. Set `depth` to limit traversal.
+
+### "What imports this file?"
+Use **ts_dependents** — all files that depend on a given file, grouped by package. Shows both direct and transitive dependents.
+
+### "Are there circular imports?"
+Use **ts_import_cycles** — detects strongly connected components. Filter by file or package.
+
+### "How does module A reach module B?"
+Use **ts_shortest_path** — finds the shortest import path between two files in the module graph.
+
+### "What's the neighborhood around these files?"
+Use **ts_subgraph** — extracts nodes and edges around seed files, expanding by depth in any direction (imports, dependents, or both).
+
+### "How coupled is this module?"
+Use **ts_module_boundary** — analyzes incoming/outgoing edges, shared dependencies, and computes an isolation score.
+
+## Key Principles
+
+1. **Always prefer ts_* tools over grep/glob** for TypeScript navigation. They resolve through barrel files, re-exports, and project references.
+2. **Start narrow, expand if needed.** Use ts_definition or ts_find_symbol first. Only use ts_navigate_to (project-wide search) when you don't know the file.
+3. **Combine tools for workflows.** Impact analysis = ts_blast_radius + ts_dependents. Refactor safety = ts_trace_chain + ts_import_cycles.
+4. **Graph queries are instant** (~0.1ms). Point queries are fast (~2-50ms). Don't hesitate to use them liberally.
+5. **First query may be slow** (~2s) as tsserver warms up. All subsequent queries are fast.
+
+## Tool Reference
+
+| Tool | Input | Best For |
+|---|---|---|
+| `ts_find_symbol` | file + symbol name | Locating a symbol when you know the file |
+| `ts_definition` | file + symbol (or line+col) | Go-to-definition through any indirection |
+| `ts_references` | file + symbol (or line+col) | All semantic references to a symbol |
+| `ts_type_info` | file + symbol (or line+col) | Type signature and documentation |
+| `ts_navigate_to` | symbol name (+ optional file) | Project-wide symbol search |
+| `ts_trace_chain` | file + symbol + maxHops | Following a call chain to implementation |
+| `ts_blast_radius` | file + symbol | Impact analysis for changes |
+| `ts_module_exports` | file | Listing a module's public API |
+| `ts_dependency_tree` | file (+ depth) | What a file depends on |
+| `ts_dependents` | file (+ depth) | What depends on a file |
+| `ts_import_cycles` | optional file/package filter | Circular dependency detection |
+| `ts_shortest_path` | from file + to file | Import path between two files |
+| `ts_subgraph` | seed files + depth + direction | Neighborhood extraction |
+| `ts_module_boundary` | file list | Module coupling analysis |