blackwell-systems / lsp-edit-symbol

lsp-edit-symbol

Edit a named symbol (function, type, variable) without needing its exact file path
or line/column. Primary path uses replace_symbol_body for direct symbol replacement.
Falls back to find_symbol + list_symbols + apply_edit when
the server does not support document symbols well.

Workflow

Step 1 — Locate the file

{ "tool": "find_symbol", "query": "MyFunc" }

Returns a list of matching symbols with file URI and position. Pick the definition
(not a test file, not a stub). If multiple matches, use the container name or file
path to disambiguate.

Step 2 — Replace the symbol body (primary path)

Use replace_symbol_body to replace the entire function/method/type body by name:

{
  "tool": "replace_symbol_body",
  "file_path": "/path/to/file.go",
  "symbol_path": "MyFunc",
  "new_body": "func MyFunc() error {\n\treturn nil\n}"
}

For methods, use dot notation: "MyStruct.Method".

This resolves the symbol by name within the file, finds its full range, and replaces
it atomically. No position math required.

If replace_symbol_body fails (e.g., the server cannot resolve document symbols
for this file), fall back to the manual path below.

Fallback — Manual resolution via document symbols

Step 2b — Get the full range:

{
  "tool": "list_symbols",
  "file_path": "/path/to/file.go",
  "language_id": "go"
}

Find MyFunc in the returned tree. The range field covers the entire symbol
including its body; selectionRange covers only the name.

Step 3b — Apply the edit:

Option A (text-match, recommended when you have the old text):

{
  "tool": "apply_edit",
  "file_path": "/path/to/file.go",
  "old_text": "func MyFunc() {",
  "new_text": "func MyFunc() error {"
}

Option B (positional, when you have the exact range):

{
  "tool": "apply_edit",
  "workspace_edit": {
    "changes": {
      "file:///path/to/file.go": [{
        "range": { "start": {"line": 12, "character": 0}, "end": {"line": 18, "character": 1} },
        "newText": "func MyFunc() error {\n\treturn nil\n}"
      }]
    }
  }
}

Decision guide

Notes

• replace_symbol_body is the preferred path for full-body replacements. It handles
  symbol resolution and range calculation internally.

• find_symbol returns declaration sites, not all references. The
  first non-test result is usually the definition.

• Positions in list_symbols are 1-based (shifted from LSP convention).
  apply_edit workspace_edit expects 0-based; subtract 1 when using positional
  mode (Option B). Text-match mode (Option A) requires no position math.

• For renames (not edits), use /lsp-rename instead; it updates all call sites.