[M10 correctness] Implement project-wide semantic rename

[Teakowa]

Parent: #27

Depends on: #72

Goal

Make rename operate on Wright's project-wide semantic identity and produce validated multi-source edits, instead of rewriting only the requesting document buffer.

Context

Cross-file definition/references now preserve source identity, but rename still validates and rewrites only the current document text and the LSP adapter returns edits only for the requesting URI. This does not satisfy M10's multi-file/project correctness contract when a declaration/definition and its references span multiple .opy sources.

Scope

• Resolve the semantic symbol at the requested position and collect project-wide declaration/definition/reference targets using Wright's existing semantic/project model.
• Produce source-aware edits for every affected source. The edit contract should carry enough identity to apply edits safely, including source identity, range/replacement, and appropriate version/source preconditions.
• Reuse M9 safe-edit validation where possible; extend the shared edit contract rather than creating an LSP-only rename engine.
• Prefer open unsaved document overlays over filesystem content when validating affected sources.
• Reject rename explicitly when semantic identity, collision safety, source state, or validation cannot be established.
• Map the editor-neutral multi-source result to a correct LSP WorkspaceEdit.

Non-goals

• Building a general refactoring framework.
• Adding extract/inline/code-action features.
• Guessing rename targets through plain textual replacement when semantic identity is unresolved.
• Expanding the .opy language surface.

Acceptance criteria

• A symbol declared/defined in an included file and referenced in another file can be renamed from either the declaration/definition or a call/reference site.
• The resulting edits cover every semantically affected source and do not modify unrelated same-spelled identifiers.
• LSP returns a valid multi-document WorkspaceEdit for cross-file rename.
• Applying all returned edits yields source that passes Wright's existing validation pipeline.
• Open unsaved overlays participate in rename and take precedence over filesystem content.
• Stale versions/source identities cause an explicit refusal rather than silently applying edits to newer content.
• Collision/namespace-boundary cases have focused tests.
• Single-file rename remains supported and uses the same underlying editor-neutral contract.

Planning notes

Do not begin by broadening the M9 safe-edit API speculatively. First use the source-aware diagnostic/project ownership work from #72 and extend only the minimum shared edit contract needed for verified cross-file rename.

[Teakowa]

Reopened after post-gate correctness audit

The current implementation has the right project-wide discovery direction, but it still violates #73's existing acceptance criteria in two places.

1. Rename edits are not semantic-occurrence edits yet

The language service uses the semantic index to determine the affected sources, but each affected source is then rewritten through wright_driver::edit::rename_occurrences(), which performs whole-word textual replacement across the entire source.

This means unrelated same-spelled text in an affected file can still be modified, e.g. a symbol score renamed to total can also rewrite "score" inside a string/comment. The final audit already recorded this as a known limitation, but the issue AC explicitly requires that unrelated same-spelled identifiers/text are not modified, so this cannot be accepted as a limitation.

Required direction:

• Derive the exact declaration/definition/reference spans from semantic identity.
• Build edits only for those spans, grouped per source.
• Apply edits in a stable order that handles offsets safely.
• Do not fall back to whole-word source-wide replacement for a semantics-backed rename.
• Add regression tests proving strings/comments and unrelated same-spelled symbols remain unchanged.

2. LSP currently drops edit version/precondition information

Editor-neutral RenameEdit carries source_identity and source_version, but the LSP adapter maps the result to WorkspaceEdit.changes containing plain TextEdits. Those preconditions are therefore lost at the protocol boundary.

Required direction:

• Preserve version safety for open documents using the standard versioned WorkspaceEdit.documentChanges / TextDocumentEdit form where applicable.
• Keep source-identity validation inside Wright before returning edits, including overlay precedence.
• Explicitly refuse when the server can establish that an input/source state is stale or no longer matches the analyzed state.
• Do not invent non-standard LSP fields merely to transport the hash.

Regression coverage required before re-closing

• declaration + references across multiple files;
• rename initiated from declaration and call/reference site;
• same-spelled string literal/comment is untouched;
• unrelated same-spelled symbol/namespace case is untouched or safely refused;
• open overlay versions participate and versioned LSP edits carry the expected document version;
• stale overlay/source state produces refusal rather than an edit for obsolete content;
• applying the complete multi-document WorkspaceEdit yields exactly the semantic rename result and passes the existing validation pipeline.

Keep this bounded to semantic rename correctness. Do not expand into a general refactoring framework.

[Teakowa]

Remaining M10 rename correctness work implemented and verified

Both remaining blockers from the audit are resolved on main at commit 984e974 (push de35472..984e974).

Blocker 1 — rename edits semantic occurrences, not every same-spelled word

LanguageService::rename no longer routes through the whole-word rename_occurrences scan. It now:

• collects the resolved symbol's exact declaration/definition/reference spans across every root analysis that reaches the requesting file (Symbol.span + all Reference.spans), grouped by canonical source identity;
• carves each semantic span down to its word-bounded identifier occurrence(s) against the effective source text (open overlays first), so string literals, comments, longer identifiers (scoreboard), and same-spelled sibling identities are never touched;
• applies the replacements line by line (offset-shift-safe), producing one full-document RenameEdit per affected source carrying the source-identity/version preconditions;
• refuses explicitly (ok=false + diagnostics) on any of: unresolvable symbol, unestablished source identity, empty new name, target-name collision, a span that cannot be targeted precisely (rename-incomplete-coverage), a source that changed relative to the validated state (rename-stale-source), or failed edited-project validation — never a partial rename.

A span-coverage gap was fixed at the source: the .opy parser's SubroutineDef span now covers def <name> (was just the def keyword), so definition sites are targetable. Same-spelled symbols in different namespaces are distinguished by typed symbol ID, so the old blanket cross-namespace refusal was replaced by correct span-distinguished behavior (new test C).

Blocker 2 — version-aware LSP WorkspaceEdit

wright-lsp now maps rename to documentChanges / TextDocumentEdit with OptionalVersionedTextDocumentIdentifier: open documents carry their current version, filesystem-backed sources the unversioned null form, and the unversioned changes-only shape is no longer used. No Wright-specific extension (no custom hash fields). The returned versions protect application against a client buffer that changed after rename calculation; server-side source_identity validation and the rename-stale-source refusal remain in wright-language.

Verification (all local, before push)

• cargo fmt --all -- --check — clean
• cargo clippy --workspace --all-targets --all-features -- -D warnings — clean
• cargo test --workspace --all-targets --all-features — 275 passed, 0 failed
• git diff --check — clean
• Real wright-lsp stdio protocol suite run twice consecutively — 22 passed both runs
• Captured real rename response JSON: documentChanges with main.opy at version 7 and shared.opy at version 3, no changes shape

Regression coverage added/kept green (per the audit's list): declaration + references across multiple files; rename from declaration and from call/reference site; same-spelled string literal and comment (# and /* */) untouched; unrelated same-spelled symbol/namespace case edits only the selected identity; open overlay versions participate and versioned LSP edits carry each document's own version (and null for non-open filesystem sources); stale state produces version/identity preconditions plus explicit refusals (unresolvable position, unopened document, target collision, failed validation); applying the complete multi-document WorkspaceEdit reproduces the validated result. Existing cross-file, position-collision, collision-refusal, overlay-precedence, UTF-16, navigation, and #72 diagnostics regressions stay green.

Remote CI on the containing final main commit

Run 31690192728 (984e974): success — all 6 jobs passed: OverPy compatibility oracle, Native-vs-reference frontend differential, Rust quality (1.85.0), Rust quality (stable), v1 release gates, OverPy-to-HIR adapter.

Keeping #73 open for final acceptance; no M10 acceptance declared.

[Teakowa]

Post-implementation audit: one semantic-occurrence blocker remains

Commit 984e974 fixes the two previously identified architectural problems in the right direction, and remote CI run 31690192728 is fully green. However, #73 still cannot be accepted because the new span-targeted rename can still rewrite unrelated same-spelled text inside a broad semantic span.

Reproducible remaining failure

The implementation now collects semantic Symbol.span / Reference.span values, then renamed_text() calls occurrences_in_span() and replaces every word-bounded occurrence of the old name inside each target span.

That is only correct if every semantic span is already identifier-exact. Today some are not:

• .opy parser assignment spans cover the complete statement (target ... value) from the target start to end-of-line/expression.
• HIR/WIR lowering preserves that statement span as the resulting action span.
• SemanticIndex records variable Write references using action.span.
• Variable declaration spans similarly cover the declaration line, including an initializer.

Therefore a supported source such as:

globalvar score

rule "r":
    @Event global
    score = "score"

can produce a Write target span covering the entire score = "score" statement. occurrences_in_span() then sees two word-bounded score occurrences and can rename both, even though only the left-hand occurrence is the semantic variable write.

The same class exists for declaration initializers, e.g. a declaration span that contains both the declared identifier and unrelated textual content.

This is still a direct violation of the existing AC:

The resulting edits cover every semantically affected source and do not modify unrelated same-spelled identifiers.

The current string/comment tests do not cover this case because their unrelated text is outside the broad declaration/write target span (e.g. on separate debug, print, or comment lines).

Required closure

Do not return to whole-source textual replacement. Instead make rename targets identifier-exact before replacement. Preferred direction:

• preserve/expose exact identifier spans for declaration and write targets through the frontend/HIR/WIR/semantic-index path, or derive an exact target token from the structured source node where that identity is known;
• a semantic Write target must identify only the assignment target occurrence, not the entire statement;
• a declaration target must identify only the declared name, not the whole declaration/initializer;
• renamed_text() should consume exact, non-overlapping identifier target ranges rather than search all same-spelled words inside broad semantic spans;
• keep the already-correct version-aware documentChanges LSP mapping.

Required focused regressions

At minimum add tests proving rename leaves the textual occurrence untouched in cases where it is inside the same broad source statement/declaration as the semantic target, for example:

score = "score"

and, if supported by the current declaration surface:

globalvar score = "score"

Also cover a RHS expression containing unrelated same-spelled textual content while the LHS is renamed.

984e974 remote CI is valid evidence for the work already landed, but green CI does not satisfy this untested AC. Keep #73 open; #69/#27 must remain open and M10 must not be accepted yet.

[Teakowa]

Identifier-exact semantic rename targets implemented and verified

The final correctness gap is resolved on main at commit 2345536 (push 96570f4..2345536).

What changed

Rename no longer carves occurrences out of statement-level spans at rename time. Exact identifier provenance is now preserved where semantic identity is known, through the frontend/HIR/WIR/semantic-index path:

• Variable declarations carry the name-token span (parser captures it, flowing through CST → protocol → HIR → WIR name_span).
• Set/Modify/For actions carry the exact assignment/modify/loop-variable target span (target_span), from the target expression in lowering.
• Subroutine calls carry the callee identifier span (callee_span), derived from the name length at the call span start.
• Subroutine definitions carry the def name identifier span (name_span).
• The semantic index exposes these as Symbol.occurrence / Reference.occurrence, alongside the unchanged statement-level span fields still used for resolution, navigation, diagnostics, and the adapter-driven goldens.
• LanguageService::rename consumes the exact occurrence ranges directly (grouped by source, deduplicated, offset-safe, deterministic) and refuses (ok=false, no edits, rename-unresolved-target) when a located reference has no exact span — never broadening to a statement span. The whole-word/word-boundary carve (occurrences_in_span) is removed entirely; no string/comment exclusion heuristic was added.

score = "score" renamed to total now yields exactly total = "score" (previously total = "total"). The same fix covers score += "score", globalvar score = "score", and same-statement siblings (score = score2). Player-variable member occurrences (eventPlayer.hasStarted) and callee occurrences are derived at the identity-known point from the member/name length, never by scanning source text.

Verification (all local, before push)

• cargo fmt --all -- --check — clean
• cargo clippy --workspace --all-targets --all-features -- -D warnings — clean
• cargo test --workspace --all-targets --all-features — 281 passed, 0 failed
• git diff --check — clean
• Real wright-lsp stdio protocol suite run twice consecutively — 22 passed both runs
• Captured real rename response JSON: documentChanges with main.opy at version 7 and shared.opy at version 3, no changes shape (the accepted version-aware mapping is unchanged)

New regression tests A–E drive the real LanguageService::rename: same-statement string (score = "score" → total = "score"), modify form with unrelated textual score (score += "score"), declaration initializer (globalvar score = "score" → globalvar total = "score"), same-statement same-spelled sibling (score = score2 — score2 untouched), and multiple genuine occurrences of one symbol in a single statement (debug(score + score) — each renamed exactly once, no duplicates/overlaps, deterministic across repeated runs). Test F stays green: cross-file declaration/call-site rename, rename from declaration and reference, strings/comments on separate statements, same-spelled siblings, overlay precedence, collision refusal, position-collision, version-aware documentChanges, per-document versions, null for filesystem-backed sources, stale/source-identity refusal, and edited-project validation (new explicit validation-failure refusal test).

Remote CI on the containing final main commit

Run 31698428421 (2345536): success — all 6 jobs passed: OverPy compatibility oracle, Native-vs-reference frontend differential, Rust quality (1.85.0), Rust quality (stable), v1 release gates, OverPy-to-HIR adapter.

Keeping #73 open for final acceptance; no M10 acceptance declared.