[ts-morph] Type-aware rename of a TypeScript/JavaScript symbol (function, variable, class, type, interface, enum, etc.) across the entire project.

When to use

• Renaming any symbol that may be imported, re-exported, or referenced in other files.

• Prefer this over manual Edit + grep / sed. Identifier-based search misses re-exports, JSX attribute usage, and matches unrelated same-name tokens. This tool resolves references via the type checker, so it is both safer and faster.

• Even for a "local-only" symbol, this tool is the correct default: it costs nothing extra and guarantees no missed reference.

When NOT to use

• Renaming a file or folder (and updating imports to it) -> use rename_filesystem_entry_by_tsmorph.

• Moving a symbol to a different file -> use move_symbol_to_file_by_tsmorph.

• Just looking up where a symbol is used (no rename) -> use find_references_by_tsmorph.

Critical constraints

• position must point at the symbol's identifier (1-based line/column, as shown by editors). If the position lands on whitespace or a different token, the rename fails.

• symbolName must match the identifier text at that position; it is used as a sanity check.

• All paths (tsconfigPath, targetFilePath) MUST be absolute.

Tips

• Run with dryRun: true first when the change spans many files, to preview the affected file list.

Result

Returns the list of modified (or to-be-modified, in dryRun) file paths, plus status and processing time.

[ts-morph] Rename or move one or more TypeScript/JavaScript files and/or folders, and automatically rewrite every import/export path that references them.

When to use

• Renaming or moving any .ts/.tsx/.js/.jsx file or directory (single or batch).

• Prefer this over mv + manual import fixing. This tool resolves references via the type checker, so it handles relative paths, path aliases (@/), and barrel imports (from '.', from '..') that grep cannot reliably find.

• Use batch mode (multiple entries in renames) when reorganizing several files at once -- a single AST pass is much faster than running the tool repeatedly.

When NOT to use

• Renaming a symbol inside a file -> rename_symbol_by_tsmorph.

• Moving a single symbol (not the whole file) to another file -> move_symbol_to_file_by_tsmorph.

Critical constraints

• Path aliases in updated imports are REWRITTEN AS RELATIVE PATHS (e.g., @/foo -> ../foo). If you want to keep aliases, run remove_path_alias_by_tsmorph separately beforehand, or accept the conversion.

• Barrel imports like import X from '../components' are rewritten to point at the resolved index file (e.g., '../components/index.tsx').

• Default exports declared via a bare identifier (export default Foo;) may not be updated correctly. Default function/class declarations (export default function foo() {}) are handled.

• All paths (tsconfigPath, oldPath, newPath) MUST be absolute.

• The tool refuses to run on path conflicts (target already exists, duplicate destinations).

Tips

• Run with dryRun: true first for any non-trivial rename to inspect the affected file list.

• timeoutSeconds defaults to 120; raise it for very large projects or huge batch renames.

Result

Returns the list of modified (or to-be-modified, in dryRun) file paths, plus status and processing time. On timeout the operation is cancelled and an error is returned.

[ts-morph] Locate the definition AND every reference of a symbol at a given position, project-wide. Read-only.

When to use

• Assessing the blast radius of a planned refactor before changing anything.

• Answering "who calls this function?" / "where is this type used?" precisely.

• Prefer this over grep for identifier lookups: grep matches unrelated same-name tokens (different scopes, comments, strings), while this tool uses the type checker to return only true references.

When NOT to use

• You just want a free-text search (comments, strings, doc files) -> use grep.

• You already plan to rename -> skip straight to rename_symbol_by_tsmorph (it computes the same set internally and supports dryRun).

Critical constraints

• position must land on the symbol identifier itself (1-based line/column, as shown by editors). A position on whitespace or another token will fail to resolve.

• All paths (tsconfigPath, targetFilePath) MUST be absolute.

Result

Returns the definition (file path, line, column, source line) when found, followed by a numbered list of references with the same fields.

[ts-morph] Convert path-alias imports/exports (e.g., @/components/Button) to relative paths (../../components/Button) within a target file or directory.

When to use

• Standardizing on relative paths for a subset of the codebase.

• Preparing for a large rename_filesystem_entry_by_tsmorph run when you want to control alias rewriting explicitly (note: rename_filesystem_entry_by_tsmorph already rewrites aliases to relative paths automatically; run this tool first only if you want the conversion to be a separate, reviewable commit).

• Prefer this over manual find/replace -- relative path computation is error-prone across nested directories.

When NOT to use

• The project has no paths mapping in tsconfig.json (this tool has nothing to do).

• You want to ADD aliases or change one alias to another (not supported).

Critical constraints

• Aliases are read from the paths option of the project's tsconfig.json. Only those aliases are resolved.

• targetPath may be a single file OR a directory. Directory targets process every .ts/.tsx file under it.

• All paths (tsconfigPath, targetPath) MUST be absolute.

Tips

• Run with dryRun: true first when applying to a directory, to confirm the scope.

Result

Returns the list of modified (or to-be-modified, in dryRun) file paths, plus status and processing time.

[ts-morph] Move one top-level symbol (function, variable, class, interface, type, enum) from one file to another, carrying its internal-only dependencies and rewriting all imports/exports across the project.

When to use

• Splitting a large file: move related symbols to a new file one by one.

• Relocating a helper from a generic utils.ts to a feature-specific module.

• Prefer this over manual cut-and-paste + import fixing. Manual moves frequently miss re-exports, leave stale imports, or fail to add the new export -- this tool handles all of that via the type checker.

When NOT to use

• Renaming the file (without moving a single symbol out of it) -> rename_filesystem_entry_by_tsmorph.

• Renaming a symbol in place -> rename_symbol_by_tsmorph.

• The symbol you want to move is a export default -> NOT SUPPORTED, refactor it to a named export first.

Critical constraints

• ONE top-level symbol per call. To move N symbols, invoke the tool N times.

• Default exports CANNOT be moved. Convert them to named exports beforehand.

• If multiple top-level declarations share the same name (e.g., function + namespace), pass declarationKindString (e.g., "FunctionDeclaration", "VariableStatement") to disambiguate.

• Internal dependency rules:

  • Dependencies used ONLY by the moved symbol travel with it.

  • Dependencies also used by other symbols in the source file stay put, gain export if missing, and are imported back into the destination file.

• All paths (tsconfigPath, originalFilePath, targetFilePath) MUST be absolute.

• targetFilePath may point to a non-existent file; it will be created.

Tips

• Run with dryRun: true first when the source file has many co-dependencies to confirm what gets pulled along.

Result

Returns the list of modified (or to-be-modified, in dryRun) file paths, plus status and processing time.

[ts-morph] Add, remove, or reorder parameters of a function/method/arrow-function and propagate the matching argument changes to every call site in the project.

When to use

• Adding a required parameter to a function with many callers (LLM single-edit reliably misses some — this tool guarantees every call site is updated via the type checker).

• Removing or reordering parameters of a function that is imported, re-exported, or accessed through a method chain.

• Inserting a context-like first parameter (ctx, logger, etc.) into existing helpers.

When NOT to use

• Renaming a parameter — use rename_symbol_by_tsmorph on the parameter identifier instead.

• Changing only the parameter's type annotation without changing arity — edit the source file directly.

• Moving the function to another file — use move_symbol_to_file_by_tsmorph.

Critical constraints

• position must point at the function's name identifier (1-based line/column). For const foo = () => {}, point at foo; for class C { foo() {} }, point at foo.

• functionName must match the identifier text at that position (sanity check).

• All paths (tsconfigPath, targetFilePath) MUST be absolute.

• Spread arguments (fn(...args)) at call sites cause the operation to fail when a change would modify arguments. Refactor those callers manually first, or limit changes to trailing optional/defaulted parameters with no argumentForCallers.

• Operations apply sequentially; later operations see the parameter list produced by earlier ones.

Operation semantics

• add: Inserts a parameter at index (default: end). If argumentForCallers is provided, that exact text is inserted at the same index in every call site. If omitted, callers are left untouched (use only for trailing optional / defaulted parameters).

• remove: Removes the parameter at index. Each call site with at least that many arguments drops the corresponding one. Calls passing fewer arguments are left untouched.

• reorder: Rebuilds the parameter list and every call site according to newOrder. Fails if any call site does not pass exactly that many arguments (no way to safely reorder omitted optionals).

Tips

• Run with dryRun: true first when the function has many callers to preview the impacted files.

• For adding multiple parameters at once, list multiple add operations; their index values refer to the parameter list after prior operations in the same call have been applied.

Result

Returns the list of modified (or to-be-modified, in dryRun) file paths, plus status and processing time.