Proposal: editable-ranges hint for embedded-editor hosts (clarion/editableRanges) so refactors respect generated code

[msarson]

Context

Embedded-editor hosts now push PWEE-style buffers to the server addressed as the real generated MEMBER module (the MEMBER-header technique from ClarionLive/ClarionAssistant#56 / PR #74, same approach as ClarionMonacoEditor). That gives the server full PROGRAM scope inside embed buffers — completion, hover, definition, implementation, and signature help all resolve correctly, because those features only read.

Code actions / refactors write, and there the illusion breaks: the server believes the whole buffer is a normal editable file, but in an embeditor buffer only the embed slots are user-owned — everything else is template-generated, read-only in the editor, and regenerated from the .app at will.

The failure modes (why clients can't fully fix this alone)

Using Introduce EQUATE (#281) as the example:

• In-buffer, out-of-slot inserts: "declare in procedure local data" picks a textual insertion point in the data section — in an embed buffer that's a generated read-only line, even when a data embed slot sits a few lines away. The client can only block the edit (action appears to do nothing) or heuristically remap it after the fact.
• Cross-file edits into generated files: "Global (in App.clw)" writes to the generated PROGRAM file — the edit succeeds, compiles, and is silently wiped by the next generate. The durable home for that change is the .app, which is outside the LSP's world.

Clients can filter WorkspaceEdits against their known editable ranges (that's the planned v1 on the ClarionAssistant side), but filtering after computation means the server wastes work proposing actions that get hidden, and the useful variants (e.g. "declare in the data embed slot") never get offered because the server doesn't know slots exist.

Proposal

An opt-in notification, mirroring the shape of clarion/updatePaths:

// notification: clarion/editableRanges
{
  "uri": "file:///c%3A/apps/MyApp001.clw",
  "ranges": [ { "startLine": 12, "endLine": 14 }, { "startLine": 210, "endLine": 230 } ]  // 0-based inclusive
}

Semantics:

• Absence of the notification (or an empty send with ranges: null) = whole document editable — VS Code and every existing client are completely unaffected; this only activates for hosts that send it.
• Ranges describe the CURRENT buffer version; hosts re-send after edits move slots (they already track live ranges for their own read-only enforcement). Cleared on didClose.
• When present, providers that produce edits consult it:
  • Code actions: only offer actions whose edits fall inside editable ranges — or better, prefer editable insertion targets when choosing where a declaration goes (e.g. Introduce EQUATE's scope quick-pick could offer "the data embed" because an editable range exists inside the data section).
  • Rename: skip/flag edits landing in read-only regions of this document (cross-file rename is a separate question — those files may be generated too, but the host can filter file-level).
  • Read-only features (completion/hover/nav/signature help/diagnostics) ignore it entirely.

Why server-side beats client-side filtering

• The server picks insertion points — only it can pick a different, legal one. Client filtering can only veto.
• Every embedded host (ClarionAssistant CA Embeditor, ClarionMonacoEditor, anything future) gets correct behavior from one implementation instead of N re-implemented filters.
• Actions that can't be satisfied inside editable ranges simply don't appear — no "I clicked and nothing happened".

Non-goals

• No change to VS Code behavior (never sends the notification).
• Not trying to model .app-level targets ("declare in global data" belonging in the app tree rather than generated source) — hosts that know about the .app can layer that on top; this proposal just stops the server from proposing edits into regions the user cannot own.

Discussion that led here: ClarionLive/ClarionAssistant PRs #74/#75/#78 (embed scope + signature help + go-to-implementation) — read-side features are now fully lit in embeds; this is the missing piece for the write-side (Ctrl+. code actions).

🤖 Generated with Claude Code

[msarson]

Reviewed against the current server code — the proposal holds up. The opt-in notification mirroring clarion/updatePaths is the right pattern, "absence = whole document editable" keeps VS Code genuinely untouched, and the core argument is correct: the server chooses insertion points, so only the server can pick a different, legal one. Client-side filtering can only veto after the fact.

Three refinements before implementation:

1. Coverage gap: several refactors are client-side, not server-side. FlipIfElse, NegateCondition, and SurroundWith live in client/src/refactor/ — embedded hosts bundling only the LSP server never see those at all, and this proposal can't help them. The covered set is the server-side actions (IntroduceEquate #281, GenerateRoutine, MapDeclaration, ClassConstants, Unicode) plus rename (server/src/providers/RenameProvider.ts). This interacts with the 1.0.1 refactor batch: if #282/#286/#283/#271 follow the #279 client-side pattern, none of them benefit from editableRanges in embedded hosts. If embed-host support matters for refactors, that's an argument for putting the new batch's code actions server-side.

2. Rename semantics should be "reject", not "skip". Silently skipping edits that land in read-only regions produces a half-renamed buffer that won't compile. If a rename requires touching generated code, the right behavior is to refuse with a reason (LSP supports returning an error/ResponseError from rename), not to apply the editable subset.

3. Phase it: v1 filter, v2 target-selection. Suppressing actions whose edits fall outside editable ranges is a small, central guard — per-URI range map + one isEditInsideEditable() check in edit-producing providers. Teaching Introduce EQUATE to prefer a data embed slot as an insertion target is real per-provider design work. v1 alone already kills the "silently wiped by next generate" hazard.

Minor mechanical note: there's an inherent race between didChange and a re-sent editableRanges — a code-action request landing between them sees stale ranges. Worst case is a briefly wrong offer/suppression (probably acceptable), but adding the document version to the notification payload would let the server discard stale sends cheaply.

🤖 Generated with Claude Code