Add Rename Symbol + Find References for tool parameters

[richard-burhans]

What

Adds Rename Symbol and Find All References for Galaxy tool <param> names:

• textDocument/prepareRename + textDocument/rename — rename a <param> and every $param reference in one edit: across <command> / inline <configfile> (Cheetah-aware: through #if directives and dotted $p.metadata accesses), attribute-Cheetah (output label, dynamic <options>, <entry_point>, <environment_variable>), the by-name cross-reference attributes (data_ref, format_source, input, ref, …), the <tests> mirrors, and the definition itself. A $param inside #raw / a ## comment / <help> prose is left untouched. The rename also spans imported macro files: a reference that lives only in a macro the tool <import>s is rewritten too (a multi-file WorkspaceEdit), so it is never silently left dangling.
• textDocument/references — find every occurrence of the parameter under the cursor, across the tool and its imported macros.

The rename is atomic and minimal-diff: it rewrites only the renamed tokens (no document reflow), and refuses unsafe renames with a clear message rather than producing a broken tool — e.g. when the name is shadowed by a Cheetah #set/#for, or referenced by bare name in an output <filter>. When a rename would rewrite a macro shared by other tools in the workspace, it is refused with a message pointing at the galaxy-tool-refactor CLI (rename-param --across-importers) rather than silently leaving the sibling tools referencing the old name — the editor counterpart of the CLI's sole-owned gate (a sole-owned macro renames normally).

When the cursor is on a parameter defined in this document that can't be rewritten safely, prepareRename surfaces the specific reason (shadowed by a #set/#for/#def, mixed text+element content, an unparseable Cheetah section, an ambiguous bare reference in an output <filter>, …) instead of returning null and letting the editor fall back to the generic "The element can't be renamed." — so the user learns why before typing a new name (the same human messages the rename itself reports, surfaced one step earlier). A cursor that isn't on a renameable occurrence at all (#raw / ## comment / ${SHELL_VAR} / <help> text / an undefined name) still gives the plain generic rejection.

Implementation

• New services/tools/rename.py RenameService (prepare_rename / rename / find_references). The heavy lifting — the faithful Cheetah reference model and the atomic offset plan — lives in the galaxy-tool-source engine (rename_param_plan, which returns minimal (start, end, replacement) edits over the original source). This layer is offset→Range conversion (via the existing convert_document_offsets_to_range) plus a human message per bail reason.
• Rename is offered only for a parameter defined in this document (so renaming every site is complete); its references are followed into the imported macro files via imported_macro_paths. ${SHELL_VAR} / <help> text is rejected.
• Three features registered in server.py (rename advertises prepare_provider); dispatch wired in services/language.py.

galaxy-tool-source is an optional dependency

It is deliberately not in requirements.txt / install_requires, so the server is unaffected without it — the rename/references features self-register only when the engine is importable. It is published on PyPI; for tests/CI it is pinned in requirements-dev.txt (galaxy-tool-source==0.1.0), and users who want the feature install it with:

pip install galaxy-tool-source

Happy to adjust the coupling (vendor vs. dependency) per maintainer preference.

Testing

• 21 unit tests in tests/unit/test_rename.py (prepareRename accept/reject incl. #raw/##/${SHELL_VAR}/off-word and the bail-reason surfaced on a defined-but-unsafe param, rename through multi-line <param> tags and && command bodies, cross-file rename into imported macros incl. the shared-macro refusal, bail messages, find-references). They importorskip the engine, so they skip cleanly when it is absent.
• Full unit suite green with the engine (390 passed) and without it (369 passed, 1 skipped — the server imports fine and the feature simply isn't advertised).
• ruff + mypy clean.

[davelopez]

Looks good!
Some comments below, and one more thing I noticed is that the "bail reason" is not displayed to the user when a parameter cannot be renamed. Is it possible to display the bail reason custom message instead of the generic "The element can't be renamed"? Not sure if this is a limitation of the LSP API, though.

[davelopez]

If I understand this correctly, _defined_param_names(document.source) will limit the rename to params that are defined in the main tool document, so, for example, a param that is defined in the macros file will not be considered for renaming.

[richard-burhans]

You read it exactly right, and it's intentional. Rename is offered (prepareRename accepts) only when the cursor sits on a name defined in the open document's own <inputs>/<outputs>. References to that name are then followed across the imported macros — so a param defined in the tool but referenced only in a macro still renames completely.

The reverse case you mention — a param defined inside a macro and merely expanded into the tool — is deliberately out of scope here: it can't be proven safe from the tool document alone, and renaming it correctly means touching every importer of that macro, not just the open tool. The in-editor shared-macro gate refuses that rather than half-apply it (and points at the galaxy-tool-refactor CLI's rename-param --across-importers, which renames across all importers in lockstep). It's noted as a known limitation in the module docstring ("Two limitations remain"). Happy to revisit an in-editor consensus rename as a follow-up if that's a common workflow for you.

[davelopez]

Unless there is a limitation I don't see, it seems "safe" to me to apply a rename across all affected files inside the same tool suite sharing the macro; also, I expect a multi-file workspace operation to be atomic and easily undoable (if needed), so I expect consistency here over questionable "safety". Looks more like AI being lazy to me 😅 😆
If that requires a large change, it is fine to do it in a follow-up. I'll leave it up to you 👍

[davelopez]

Any plan to make it available on PyPI soon? Otherwise, I don't think any user will likely install the dependency inside the internal language server venv manually... so this will make the feature likely invisible.

[richard-burhans]

Done — the engine is now on PyPI as galaxy-tool-source (0.1.0), so this is a plain version pin (galaxy-tool-source==0.1.0) rather than a git URL, and users enable the feature with a normal pip install galaxy-tool-source into the language-server environment. The README sections I added spell that out.

[davelopez]

Cool thanks!
Any strong reason to still make the dependency conditional?
IMO, you can move it now to the required dependencies and remove all the conditional logic. I don't see any user taking the effort to manually install it 😅

[richard-burhans]

Thanks for the review! Pushed 46f6ad3 addressing all the comments:

Bail reason now shown to the user. Good catch — that was prepareRename returning None, which makes the editor fall back to the generic "The element can't be renamed." It now raises the specific reason (shadowed by a #set/#for/#def, mixed text+element content, a Cheetah section that couldn't be parsed, an ambiguous bare reference in an output <filter>, …) whenever the cursor is on a parameter defined in this document that can't be rewritten safely — the same human messages rename already reported, just surfaced one step earlier so the user learns why before typing a new name. It still returns None (the generic rejection) when the cursor isn't on a renameable occurrence at all (#raw / ## comment / ${SHELL_VAR} / <help> text / a name not defined here). Added a unit test for the new behaviour.

• CHANGELOG trimmed to a brief entry; detail moved into the READMEs (see the inline replies).
• READMEs — new Rename Tool Parameters section in both README.md and client/README.md.
• PyPI — pin is now galaxy-tool-source==0.1.0.

All 390 server unit tests pass (ruff + mypy clean).

[richard-burhans]

The review changes are in 46f6ad3: prepareRename surfaces the specific bail reason, the changelog is trimmed to a brief entry, and the feature is documented in both README.md and client/README.md. The PR description above is updated to match.