zls: rename_symbol silently omits edits in files that are not open (cross-file renames leave stale references)

[AmirF194]

Preconditions:

• I have made sure it's an actual issue, not a question (use GitHub Discussions instead).
• I have consulted the user guide and verified that the issue cannot be resolved by adjusting configuration/following recommended workflows.
• I have looked for similar issues and discussions, including closed ones.

Issue details:

• I have provided a meaningful title and description.
• I have explained how the issue arose and, where possible, added instructions on how to reproduce it.
• I have added details on my setup: Serena version, MCP client, OS, the programming language(s), relevant configuration adjustments and project specifics.
• If the issue relates to an application of Serena to an open-source project, I have added the link.

Summary

rename_symbol on a Zig project can silently return a WorkspaceEdit that is missing edits in files that reference the renamed symbol but are not currently open in ZLS. Serena applies the edit as-is and reports success with no indication that other files were skipped, leaving the project in a broken (non-compiling) state after a rename that reads as fully successful.

Setup

• HEAD ac256f36 (main as of 2026-07-23)
• Zig 0.14.1, ZLS 0.14.0 (versions pinned in .github/workflows/pytest.yml), run inside a python:3.11-slim Docker container, no live editor involved
• Reproduced against the repo's own test fixture, test/resources/repos/zig/test_repo

Root cause

ZLS only reports rename edits for files it has open (same restriction already documented for textDocument/references in test/solidlsp/zig/test_zig_basic.py: "ZLS requires files to be open in the editor to find cross-file references (performance optimization)"). ZigLanguageServer (src/solidlsp/language_servers/zls.py) has no override for rename, so it falls through to the shared SolidLanguageServer.request_rename_symbol_edit (src/solidlsp/ls.py:3083-3107), which only opens the target file before calling textDocument/rename:

def request_rename_symbol_edit(self, relative_file_path, line, column, new_name):
    ...
    with self.open_file(relative_file_path):
        return self.server.send.rename(params)

It never opens the other files that reference the symbol, so ZLS's response covers only the target file. code_editor.py's rename_symbol then applies whatever edit comes back and reports success as long as num_changes > 0, with no check for whether all known references were covered.

This is the same defect shape as #1333 and #1348 (TypeScript/Vue rename silently skipping .vue files unless the companion server had already indexed them), both fixed by ensuring the relevant files are opened/indexed before the rename request is sent. ZLS was not covered by either fix.

Reproduction

Using the repo's own fixture, renaming isPrime (defined in src/math_utils.zig, used once in src/main.zig at math_utils.isPrime(17)), without opening main.zig first:

from test.conftest import start_default_ls_context
from solidlsp.ls_config import LanguageServerId

with start_default_ls_context(LanguageServerId.ZIG) as ls:
    with ls.open_file("src/math_utils.zig"):
        result = ls.request_rename_symbol_edit("src/math_utils.zig", 14, 9, "is_prime_check")
        print(list(result["changes"].keys()))

Output: only src/math_utils.zig is present in changes; src/main.zig, which contains a live call to isPrime, is absent. If this edit is applied via rename_symbol, main.zig still calls the now-nonexistent isPrime, and the project no longer compiles, with no warning from the tool.

For contrast, a same-file rename (target and all usages in one file, e.g. Calculator in calculator.zig, or factorial/isPrime's own in-file test usages) returns a complete edit, since the only file involved is already open. This also means the exact "no rename edits at all" symptom from #799 does not reproduce here: ZLS does return edits when it can see the symbol's file; the risk is a silently incomplete edit for symbols used outside the file being renamed. (I could not reproduce #799 itself with these pinned versions; the reporter there used ZLS 0.15.0, and I did not test that version.)

Expected behavior

A rename should either include edits for every known reference, or the tool should refuse / warn when it cannot guarantee full coverage, the same guarantee the fix for #1333 established for Vue/TypeScript.

Possible fix

Before calling request_rename_symbol_edit for Zig, open the files known to reference the symbol (via request_references) so ZLS includes them in the response, mirroring _ensure_vue_files_indexed_on_ts_server()'s role in the Vue fix. Whether that belongs in ZigLanguageServer specifically or as a general helper other single-process language servers with the same "only sees open files" restriction could reuse is a design call I'd rather leave to a maintainer; happy to open a PR once there's agreement on where it should live.

[opcode81]

Thanks for your report.

It seems contradictory that the server would be able to return references correctly with request_references but not consider the same references when applying the rename operation. The rename operation is supposed to be a workspace operation, which is not contingent on files being open.

I therefore suspect that request_references would not return the references either and that this is a problem with workspace initialisation. Most likely, we need to wait for some event from the language server prior to making the calls. If there is really no such event, then we may indeed have to open all workspace files and keep them open forever as a workaround. For Vue and Svelte, we already have such workarounds (which only recently came to my attention, see #1712), which build on hacks, and we might want to provide a more disciplined way to support this sort of thing.

[AmirF194]

Confirmed directly, not through rename: calling request_references on isPrime in math_utils.zig, with main.zig never opened, returns 7 references, all inside math_utils.zig (the file's own test block), and none in main.zig. So this isn't specific to rename or to a missing workspace-init event; request_references has the identical requirement. That matches what test_zig_basic.py already documents for Calculator/main.zig (test_cross_file_references_with_open_files: "Cross-file references ... only work when target files are open. This is a performance optimization in ZLS.").

Same shape as the Vue/Svelte case in #1712, so the fix probably wants to lean on that precedent (open every file that could hold a reference before renaming, or refuse/warn when full coverage can't be guaranteed) rather than an LSP readiness event that as far as I can tell doesn't exist here.

[opcode81]

open every file that could hold a reference before renaming

Unfortunately, that is, of course, every zig file.

This is a performance optimization in ZLS

Performance optimisation? What an excellent idea.

[AmirF194]

Agreed, opening every zig file isn't realistic for larger projects. The warn-on-partial-coverage direction seems more tractable: refuse or flag the edit when the LSP hasn't confirmed a file's references are known, rather than silently dropping them. Happy to look at where that check would sit in code_editor.py if that's the direction you'd want, or leave it to you if you'd rather shape it yourself.

[opcode81]

opening every zig file isn't realistic for larger projects

I don't know, it doesn't seem unreasonable to me. An IDE must index the entire codebase. If the only way to do that with ZLS is to open every file explicitly, then I suppose that's what we should try.
If ZLS deliberately decided not to do this internally because it is too slow, then ZLS is just not a tool that is ready for production.

[AmirF194]

Agreed, that's the more disciplined read. If ZLS genuinely can't index a real project fast enough with every file open, that's a ZLS limitation to raise upstream, not something Serena should paper over. I'll build toward opening every project file before rename_symbol on ZLS specifically, since Vue and Svelte already have their own workaround from #1712 rather than a shared one.

[MischaPanch]

We should file that upstream, to me this is clearly a bug. Might also be that we missed some setting in the initialization options

[AmirF194]

Checked the missed-setting idea first: ZLS's own config schema (schema.json) only exposes zig_exe_path, zig_lib_path, build_runner_path, global_cache_path, enable_build_on_save, build_on_save_args, and the snippet/inlay-hint/style toggles. Nothing there changes whether unopened files get indexed, and zls.py already passes every key in that schema. So this isn't a config we're missing.

On the upstream front, this is already the tracked issue: zigtools/zls#1071 ("Broken cross-file references"). It closed via zigtools/zls#2608 (merged), which fixes reference lookups within a build-system module but says explicitly it "does not yet account for references across modules (or projects)", which is exactly our main.zig/math_utils.zig case. Serena's test harness pins Zig 0.14.1 + ZLS 0.14.0, both older than that fix, so it's worth re-testing against a current ZLS to see if the gap narrowed, but the architecture limitation itself is already acknowledged and open there. A fresh issue there wouldn't add anything beyond what #1071/#2608 already say.

[MischaPanch]

Would you like to bump zls and see if that fixes it?

[AmirF194]

Yes. The test harness currently pins ZLS 0.14.0, and the upstream fix (zigtools/zls#2608) landed after that with two releases since (0.15.0, 0.16.0). I'll bump the pin and re-run the main.zig/math_utils.zig cross-module repro (isPrime references, target file never opened) against 0.16.0 to see whether it resolves without the everything-open workaround, and report back with what I find.

[AmirF194]

Bumped ZLS to 0.16.0 and re-ran the repro. That also required bumping Zig itself to 0.16.0: ZLS 0.16.0's build.zig.zon sets minimum_zig_version = "0.16.0", so it won't run against the pinned 0.14.1 toolchain.

Repro: rename isPrime in src/math_utils.zig, with src/main.zig (which calls it) never opened. Still reproduces. The returned WorkspaceEdit has 8 edits, all inside math_utils.zig; the call site in main.zig is silently omitted, same as on 0.14.0.

I also went back and checked zigtools/zls#2608, the fix I was hoping would cover this. It merged 2026-02-17 for #1071, and fixes cross-file reference search pulling in every build file in a workspace. That's a different bug from this one. ZLS still only analyzes files it's been told to open, so the fix has to live on serena's side: open referencing files (via request_references) before calling rename_symbol for Zig, same as proposed in the issue body.

Clean run, no environment issues, fresh clone at main HEAD 31aef8378634d6f1e9b798a1b1aa0d65e3b292a7, Docker (python:3.11-slim).

[opcode81]

the fix has to live on serena's side: open referencing files (via request_references) before calling rename_symbol for Zig, same as proposed in the issue body.

As I have already stated above, I don't think that makes any sense. If ZLS can correctly determine the references, then ignoring them when applying the rename operation is a bug. Both operations likely produce incomplete results in exactly the same way.

[AmirF194]

That was actually already tested (my July 23 comment above): calling request_references directly on isPrime with main.zig unopened returns 7 references, all inside math_utils.zig, none in main.zig. So both operations do produce the same incomplete result.

That does change the practical takeaway: if request_references has the same blind spot, serena can't use it to decide which files are worth opening before a rename, since it would miss the same references it's trying to protect. The only workaround left on serena's side is opening every candidate file unconditionally, or warning that coverage isn't guaranteed, rather than being selective about it.

[opcode81]

As far as I am concerned, the solution we should experiment with (i.e. to open all zig files in the language server) has not changed based on the 0.16.0 experiment.