eXist-aware completion, hover, parameter hints & exist: resource handling

[joewiz]

[This PR was co-authored with Claude Code. -Joe]

⚠️ This PR was merged ahead of existdb-openapi #42, #44, and #45 are released** to facilitate continued development. This PR consumes their language-service shapes.

Summary

The eXist-aware language-service layer for XQuery editors — content completion, function documentation, query evaluation — plus correct, lossless reading and writing of exist: resources (the fix that makes opening .xq/.xqm work and stops binary corruption). Stacked on the pane-polish PR; GitHub will retarget this to main once that merges.

What changed

exist: resource reading & writing (text vs binary)

• Open XQuery as source, not by executing it. eXist stores XQuery modules as binary documents, so the resource envelope's binary flag is true for .xq/.xqm even though their content is text. Reading those from the raw streaming endpoint executed the module on GET (the "No function call details… Library Module" / OPERATION 500s). Resources are now read by whether their mime-type is textual (application/xquery, text/*, XML/JSON): text comes from the JSON envelope's UTF-8 content, and only genuinely-binary types (images, PDFs, fonts) are fetched as raw bytes.
• Binary resources handled losslessly. A centralized ExistClient.readResource (raw bytes for binary, UTF-8 content for text) and a binary-safe streaming PUT (putResourceBytes) fix three paths that previously round-tripped binaries through text and corrupted them: download to ~/Downloads, cross-server drag-and-drop copy, and file upload (which used to skip binary files entirely — they now upload). Verified end-to-end: a PNG round-trips byte-identical and .xqm opens as intact source.
• No spurious Problems pane when a clean exist: XQuery file is opened.

Content completion

• Rich popup — a proposal list with function/variable icons beside a documentation panel (signature + description), like Oxygen's built-in completion.
• Type-to-filter — a filter field seeded with the local name already typed before the caret, narrowing the list live (eXide behavior: util: → all util: functions, then w → util:wait). Down/Up steer, Enter accepts, Escape closes.
• Snippet expansion — function completions from existdb-openapi #45 arrive as LSP snippets (util:log(${1:$priority}, ${2:$message})); accepting one inserts the expanded call and selects the first argument to type over (a dependency-free SnippetExpander handles ${n:default}/${n}/$n/choices and \$ \} \\). Plain (non-snippet) proposals fall back to dropping the caret inside ().
• Shortcuts — Cmd/Ctrl+Alt+Slash and Ctrl+Space trigger completion, scoped to XQuery editors. (Note: macOS reserves Ctrl+Space for input-source switching at the OS level, so Cmd/Ctrl+Alt+Slash is the reliable binding there.)

Query evaluation

• One destination-aware action. "Evaluate Query (eXist-db)" replaces the two former run entries and routes results to the destination chosen in Configure eXist-db Connections (Results pane / new editor). It's enabled only when running makes sense (an XQuery editor, or a text selection), and is bound to Cmd/Ctrl+Enter and the toolbar button.

Function documentation (F1) — rich, from LSP Markdown hover

• F1 → eXist function documentation for the symbol under the caret, overriding Oxygen's default F1 (Help). F1=Help is a global menu accelerator, so it's intercepted with a KeyEventDispatcher that fires only while an XQuery editor is focused and otherwise leaves F1 to Oxygen.
• Rich hover card rendered from existdb-openapi #44's LSP MarkupContent (Markdown) hover: a monospace signature, the description, a Parameters list (each $name (type) — doc), and Returns:. A small dependency-free MarkdownRenderer converts the Markdown to the Swing HTML the popup shows; long signatures wrap rather than scroll. Also covers variable references (e.g. $x → xs:integer) via #44's variable-type hover. (Function hover covers eXist extension modules — util:, xmldb:, imported DB modules — not built-in fn:.)

Parameter hints (signature-help)

• "Parameter Hints (eXist-db)" — a non-focus-stealing popup showing the enclosing call's signature with the active parameter bolded, from #44's /api/langservice/signature-help. It pops automatically as you type (, ,, ) (advancing the highlight, closing when you leave the call) and can be re-summoned via Cmd/Ctrl+Shift+Space or the context menu.

Menu labels

• "Evaluate Query (eXist-db)", "Content Completion (eXist-db)", "Go to Definition (eXist-db)", "Hover Documentation (eXist-db)", "Parameter Hints (eXist-db)".

Test plan

• mvn test — 78 unit tests (incl. MimeTypes.isTextual text/binary, hover Markdown parsing, signature-help parsing, MarkdownRenderer, SnippetExpander)
• Codacy PMD clean on changed files
• End-to-end against eXist 7 + existdb-openapi (#42 + #44 + #45 on the integration server): .xq/.xqm open as source; PNG download/upload/copy round-trips byte-identical; hover renders the full Parameters/Returns card and variable types; signature-help tracks the active parameter (incl. mid-typing and overloads); completions expand snippets
• Manual in Oxygen: completion popup + type-to-filter + snippet first-arg select; Evaluate routes per the preference; F1 shows the rich doc card on util:log (and leaves Help elsewhere); hover on a $var shows its type; parameter hints pop while typing a call; binary image opens/downloads intact

Dependency / coordination

• Requires existdb-openapi #42 (completion scoping), #44 (Markdown hover, variable-type hover, signature-help with overloads + lenient mid-typing resolution), and #45 (function-completion arg snippets, stacked on #42). Pin the upstream release once they land. The function hover not covering built-in fn: functions is a known upstream item; the plugin degrades gracefully (shows nothing rather than erroring).