dsh-lsp-actions 0.2.0

package/lib/translate.js

@@ -0,0 +1,715 @@
+/**
+ * Pure protocol translation for the LSP action client: method names, capability gating, position
+ * encoding negotiation, and the strict normalizers that turn untrusted wire payloads into the
+ * action vocabulary. No I/O or process state — every function is a pure transform.
+ * @module dsh-lsp-actions/translate
+ */
+import { LspActionError } from "./vocabulary.js";
+/**
+ * The `textDocument/*` request method for one action request.
+ * @param request - operation plus the optional formatting range that selects rangeFormatting.
+ * @returns the LSP request method name.
+ */
+export function requestMethod(request) {
+    switch (request.operation) {
+        case 'diagnostics': return 'textDocument/diagnostic';
+        case 'completion': return 'textDocument/completion';
+        case 'formatDocument': return request.range === undefined ? 'textDocument/formatting' : 'textDocument/rangeFormatting';
+        case 'codeAction': return 'textDocument/codeAction';
+        case 'workspaceSymbol': return 'workspace/symbol';
+        case 'documentSymbol': return 'textDocument/documentSymbol';
+        case 'signatureHelp': return 'textDocument/signatureHelp';
+        case 'inlayHint': return 'textDocument/inlayHint';
+        case 'rename': return 'textDocument/rename';
+    }
+}
+/** Whether a provider capability value counts as present (`true` or an options object). */
+function present(value) {
+    return value !== undefined && value !== false;
+}
+/**
+ * Whether the server advertises the requested action. Diagnostics is always servable: pull when the
+ * server advertises a diagnostic provider, otherwise the open→push→settle path.
+ * @param capabilities - the server's initialize capabilities.
+ * @param operation - the action to check.
+ * @param hasRange - whether a formatDocument request carries a range (selects the range provider).
+ * @returns true when the capability is advertised.
+ */
+export function supportsAction(capabilities, operation, hasRange) {
+    switch (operation) {
+        case 'diagnostics': return true;
+        case 'formatDocument': return present(capabilities[hasRange ? 'documentRangeFormattingProvider' : 'documentFormattingProvider']);
+        case 'completion': return present(capabilities.completionProvider);
+        case 'codeAction': return present(capabilities.codeActionProvider);
+        case 'workspaceSymbol': return present(capabilities.workspaceSymbolProvider);
+        case 'documentSymbol': return present(capabilities.documentSymbolProvider);
+        case 'signatureHelp': return present(capabilities.signatureHelpProvider);
+        case 'inlayHint': return present(capabilities.inlayHintProvider);
+        case 'rename': return present(capabilities.renameProvider);
+    }
+}
+/**
+ * Whether the server advertises pull diagnostics (`diagnosticProvider`), selecting the pull request
+ * over the open→push→settle path.
+ * @param capabilities - the server's initialize capabilities.
+ * @returns true when `diagnosticProvider` is present.
+ */
+export function supportsPullDiagnostics(capabilities) {
+    return present(capabilities.diagnosticProvider);
+}
+/**
+ * Whether a `textDocumentSync` value permits the transient `didOpen`/`didClose` this client relies
+ * on. The legacy enum form implies open/close for `Full` (1)/`Incremental` (2); the options form
+ * requires an explicit `openClose: true`.
+ * @param sync - the server's advertised `textDocumentSync`.
+ * @returns true when transient open/close is supported.
+ */
+export function supportsTransientOpen(sync) {
+    if (typeof sync === 'number')
+        return sync === 1 || sync === 2;
+    if (sync === null || typeof sync !== 'object')
+        return false;
+    return sync.openClose === true;
+}
+/**
+ * Normalize the negotiated position encoding. An omitted encoding defaults to `utf-16`; the
+ * client also serves `utf-8` and `utf-32` servers by converting positions through
+ * {@link PositionCodec}. Anything else is a protocol error.
+ * @param encoding - the server's advertised `positionEncoding`, if any.
+ * @returns the negotiated encoding.
+ * @throws Error for an encoding outside the supported set.
+ */
+export function negotiatePositionEncoding(encoding) {
+    if (encoding === undefined)
+        return 'utf-16';
+    if (encoding === 'utf-16' || encoding === 'utf-8' || encoding === 'utf-32')
+        return encoding;
+    throw new Error(`server negotiated unsupported position encoding "${String(encoding)}"; this client supports utf-16, utf-8, and utf-32`);
+}
+/**
+ * Converts zero-based cursor coordinates between position encodings for one document. Line
+ * numbers are encoding-independent (newlines are one unit in every encoding); only the character
+ * offset INSIDE the line is converted, so the tables map each utf-16 code unit index to its
+ * absolute byte (utf-8) or code-point (utf-32) offset, and conversions subtract the line's own
+ * base offset on both sides.
+ */
+export class PositionCodec {
+    utf8;
+    utf32;
+    lineStarts;
+    length;
+    /**
+     * @param text - the document text positions are converted against.
+     */
+    constructor(text) {
+        this.length = text.length;
+        const utf8 = new Uint32Array(text.length + 1);
+        const utf32 = new Uint32Array(text.length + 1);
+        const lineStarts = [0];
+        let bytes = 0;
+        let points = 0;
+        for (let i = 0; i < text.length;) {
+            const codePoint = text.codePointAt(i);
+            const width = codePoint > 0xffff ? 2 : 1;
+            // The offset BEFORE the code point at i; both units of a surrogate pair share it.
+            utf8[i] = bytes;
+            utf32[i] = points;
+            if (width === 2) {
+                utf8[i + 1] = bytes;
+                utf32[i + 1] = points;
+            }
+            if (codePoint === 0x0a)
+                lineStarts.push(i + width);
+            bytes += codePoint <= 0x7f ? 1 : codePoint <= 0x7ff ? 2 : codePoint <= 0xffff ? 3 : 4;
+            points += 1;
+            i += width;
+        }
+        utf8[text.length] = bytes;
+        utf32[text.length] = points;
+        this.utf8 = utf8;
+        this.utf32 = utf32;
+        this.lineStarts = lineStarts;
+    }
+    /**
+     * Convert a utf-16 position to the server's encoding. A character offset inside a surrogate
+     * pair (never legal in any encoding) maps to the code point's own offset.
+     * @param position - the utf-16 position.
+     * @param encoding - the server's position encoding.
+     * @returns the converted position (identical for `utf-16`).
+     */
+    encode(position, encoding) {
+        if (encoding === 'utf-16')
+            return position;
+        const table = encoding === 'utf-8' ? this.utf8 : this.utf32;
+        const line = Math.min(Math.max(Math.trunc(position.line), 0), this.lineStarts.length - 1);
+        const lineStart = this.lineStarts[line];
+        const lineEnd = this.lineStarts[line + 1] ?? this.length;
+        const character = Math.min(Math.max(Math.trunc(position.character), 0), lineEnd - lineStart);
+        const base = table[lineStart];
+        return { line, character: table[lineStart + character] - base };
+    }
+    /**
+     * Convert a server-side position back to utf-16. An offset inside a multi-unit code point
+     * (illegal per protocol) maps to the code point's first utf-16 unit.
+     * @param position - the position in the server's encoding.
+     * @param encoding - the server's position encoding.
+     * @returns the utf-16 position (identical for `utf-16`).
+     */
+    decode(position, encoding) {
+        if (encoding === 'utf-16')
+            return position;
+        const table = encoding === 'utf-8' ? this.utf8 : this.utf32;
+        const line = Math.min(Math.max(Math.trunc(position.line), 0), this.lineStarts.length - 1);
+        const lineStart = this.lineStarts[line];
+        const base = table[lineStart];
+        const target = base + Math.max(Math.trunc(position.character), 0);
+        let lo = lineStart;
+        let hi = this.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (table[mid] < target)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return { line, character: lo - lineStart };
+    }
+}
+/** Convert a range with the given position converter, or pass it through. */
+function convertRange(range, convert) {
+    if (convert === undefined)
+        return range;
+    return { start: convert(range.start), end: convert(range.end) };
+}
+/** Create the stable structured error for malformed server result payloads. */
+function malformedResponse(message) {
+    return new LspActionError(message, 'LSP_ACTION_MALFORMED_RESPONSE');
+}
+/** Whether a value is a well-formed wire position (nonnegative integer line/character). */
+function isWirePosition(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const record = value;
+    return isCoordinate(record.line) && isCoordinate(record.character);
+}
+/** Whether a value is a nonnegative safe integer. */
+function isCoordinate(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+/** Normalize a wire range, throwing on malformed input. */
+function toRange(value, decode) {
+    if (value === null || typeof value !== 'object')
+        throw malformedResponse('LSP range was not an object');
+    const record = value;
+    if (!isWirePosition(record.start))
+        throw malformedResponse('LSP range was missing a valid start position');
+    if (!isWirePosition(record.end))
+        throw malformedResponse('LSP range was missing a valid end position');
+    const start = record.start;
+    const end = record.end;
+    return convertRange({ start, end }, decode);
+}
+/**
+ * Normalize a `textDocument/diagnostic` pull report (`{ kind, items }`) or a pushed `Diagnostic[]`
+ * into the action vocabulary. `null`/`undefined` items normalize to an empty list.
+ * @param payload - the raw diagnostic payload.
+ * @param decode - optional server-side position decoder (utf-8/utf-32 servers).
+ * @returns the normalized diagnostics.
+ * @throws LspActionError LSP_ACTION_MALFORMED_RESPONSE for structurally invalid entries.
+ */
+export function normalizeDiagnostics(payload, decode) {
+    if (payload === null || payload === undefined)
+        return [];
+    if (typeof payload !== 'object')
+        throw malformedResponse('LSP diagnostics result was not an object or array');
+    const record = payload;
+    const items = Array.isArray(payload) ? payload : record.items;
+    if (!Array.isArray(items))
+        throw malformedResponse('LSP diagnostics result had no items array');
+    return items.map(item => normalizeDiagnostic(item, decode));
+}
+/** Normalize one wire diagnostic. */
+function normalizeDiagnostic(value, decode) {
+    if (value === null || typeof value !== 'object') {
+        throw malformedResponse('LSP diagnostics contained a non-object entry');
+    }
+    const record = value;
+    const range = toRange(record.range, decode);
+    if (typeof record.message !== 'string')
+        throw malformedResponse('LSP diagnostic had no message string');
+    const severity = record.severity === undefined ? 1 : record.severity;
+    if (typeof severity !== 'number' || !Number.isInteger(severity) || severity < 1 || severity > 4) {
+        throw malformedResponse('LSP diagnostic severity must be an integer from 1 to 4');
+    }
+    if (record.source !== undefined && typeof record.source !== 'string') {
+        throw malformedResponse('LSP diagnostic source must be a string');
+    }
+    if (record.code !== undefined && typeof record.code !== 'string' && typeof record.code !== 'number') {
+        throw malformedResponse('LSP diagnostic code must be a string or number');
+    }
+    return {
+        severity: severity,
+        range,
+        message: record.message,
+        ...record.source === undefined ? {} : { source: record.source },
+        ...record.code === undefined ? {} : { code: record.code },
+    };
+}
+/**
+ * Normalize a formatting result (`TextEdit[]` or `null`) into the action vocabulary.
+ * @param payload - the raw `textDocument/formatting|rangeFormatting` result.
+ * @param decode - optional server-side position decoder (utf-8/utf-32 servers).
+ * @returns the normalized edits (empty for `null`).
+ * @throws LspActionError LSP_ACTION_MALFORMED_RESPONSE for structurally invalid entries.
+ */
+export function normalizeEdits(payload, decode) {
+    if (payload === null)
+        return [];
+    if (payload === undefined)
+        throw malformedResponse('LSP formatting result was missing');
+    if (!Array.isArray(payload))
+        throw malformedResponse('LSP formatting result was not an array');
+    return payload.map(value => normalizeEdit(value, decode));
+}
+/** Normalize one wire text edit. */
+function normalizeEdit(value, decode) {
+    if (value === null || typeof value !== 'object') {
+        throw malformedResponse('LSP formatting result contained a non-object entry');
+    }
+    const record = value;
+    const range = toRange(record.range, decode);
+    if (typeof record.newText !== 'string')
+        throw malformedResponse('LSP text edit had no newText string');
+    return { range, newText: record.newText };
+}
+/**
+ * Normalize a completion result (`CompletionItem[]`, a `CompletionList`, or `null`) into the action
+ * vocabulary.
+ * @param payload - the raw `textDocument/completion` result.
+ * @param decode - optional server-side position decoder (utf-8/utf-32 servers).
+ * @returns the normalized items (empty for `null`).
+ * @throws LspActionError LSP_ACTION_MALFORMED_RESPONSE for structurally invalid entries.
+ */
+export function normalizeCompletionItems(payload, decode) {
+    if (payload === null)
+        return [];
+    if (payload === undefined)
+        throw malformedResponse('LSP completion result was missing');
+    if (typeof payload !== 'object')
+        throw malformedResponse('LSP completion result was not an object or array');
+    const record = payload;
+    const items = Array.isArray(payload) ? payload : record.items;
+    if (!Array.isArray(items))
+        throw malformedResponse('LSP completion result had no items array');
+    return items.map(item => normalizeCompletionItem(item, decode));
+}
+/** Normalize one wire completion item. */
+function normalizeCompletionItem(value, decode) {
+    if (value === null || typeof value !== 'object') {
+        throw malformedResponse('LSP completion contained a non-object entry');
+    }
+    const record = value;
+    if (typeof record.label !== 'string')
+        throw malformedResponse('LSP completion item had no label string');
+    if (record.kind !== undefined && (typeof record.kind !== 'number' || !Number.isInteger(record.kind))) {
+        throw malformedResponse('LSP completion item kind must be an integer');
+    }
+    if (record.detail !== undefined && typeof record.detail !== 'string') {
+        throw malformedResponse('LSP completion item detail must be a string');
+    }
+    if (record.insertText !== undefined && typeof record.insertText !== 'string') {
+        throw malformedResponse('LSP completion item insertText must be a string');
+    }
+    if (record.sortText !== undefined && typeof record.sortText !== 'string') {
+        throw malformedResponse('LSP completion item sortText must be a string');
+    }
+    let textEdit;
+    if (record.textEdit !== undefined) {
+        if (record.textEdit === null || typeof record.textEdit !== 'object') {
+            throw malformedResponse('LSP completion item textEdit must be an object');
+        }
+        const edit = record.textEdit;
+        textEdit = { range: toRange(edit.range, decode), newText: requireString(edit.newText, 'textEdit.newText') };
+    }
+    return {
+        label: record.label,
+        ...record.kind === undefined ? {} : { kind: record.kind },
+        ...record.detail === undefined ? {} : { detail: record.detail },
+        ...record.insertText === undefined ? {} : { insertText: record.insertText },
+        ...record.sortText === undefined ? {} : { sortText: record.sortText },
+        ...textEdit === undefined ? {} : { textEdit },
+    };
+}
+/** Require a string field, throwing the shared malformed-response error. */
+function requireString(value, name) {
+    if (typeof value !== 'string')
+        throw malformedResponse(`LSP completion item ${name} must be a string`);
+    return value;
+}
+/**
+ * Normalize a `textDocument/codeAction` result (`(Command | CodeAction)[]` or `null`) into the
+ * action vocabulary. Edits are grouped by target document URI; a `Command` form is reported
+ * verbatim and never executed. Non-text workspace edits (create/rename/delete) are dropped —
+ * applying code actions is the model's own write/edit decision.
+ * @param payload - the raw code action result.
+ * @param decode - optional server-side position decoder (utf-8/utf-32 servers).
+ * @returns the normalized actions (empty for `null`).
+ * @throws LspActionError LSP_ACTION_MALFORMED_RESPONSE for structurally invalid entries.
+ */
+export function normalizeCodeActions(payload, decode) {
+    if (payload === null)
+        return [];
+    if (payload === undefined)
+        throw malformedResponse('LSP code action result was missing');
+    if (!Array.isArray(payload))
+        throw malformedResponse('LSP code action result was not an array');
+    return payload.map(value => normalizeCodeAction(value, decode));
+}
+/** Normalize one wire code action (Command or CodeAction form). */
+function normalizeCodeAction(value, decode) {
+    if (value === null || typeof value !== 'object') {
+        throw malformedResponse('LSP code action result contained a non-object entry');
+    }
+    const record = value;
+    if (typeof record.title !== 'string')
+        throw malformedResponse('LSP code action had no title string');
+    const kind = record.kind === undefined ? undefined : requireString(record.kind, 'kind');
+    const isPreferred = record.isPreferred === undefined ? undefined : requireBoolean(record.isPreferred, 'isPreferred');
+    // Command form: no edits, only a reference to a server command (never executed).
+    if (record.command !== undefined) {
+        if (record.command === null || typeof record.command !== 'object') {
+            throw malformedResponse('LSP code action command must be an object');
+        }
+        const wire = record.command;
+        if (typeof wire.command !== 'string')
+            throw malformedResponse('LSP code action command had no command string');
+        return {
+            title: record.title,
+            ...kind === undefined ? {} : { kind },
+            ...isPreferred === undefined ? {} : { isPreferred },
+            edits: {},
+            command: {
+                title: typeof wire.title === 'string' ? wire.title : record.title,
+                command: wire.command,
+                ...wire.arguments === undefined ? {} : { arguments: wire.arguments },
+            },
+        };
+    }
+    const edits = {};
+    const wireEdit = record.edit;
+    if (wireEdit !== undefined) {
+        if (wireEdit === null || typeof wireEdit !== 'object')
+            throw malformedResponse('LSP code action edit must be an object');
+        const editRecord = wireEdit;
+        if (editRecord.changes !== undefined) {
+            collectWorkspaceEdits(editRecord.changes, decode, edits);
+        }
+        if (Array.isArray(editRecord.documentChanges)) {
+            for (const change of editRecord.documentChanges) {
+                if (change === null || typeof change !== 'object')
+                    continue;
+                const changeRecord = change;
+                if (changeRecord.kind !== undefined)
+                    continue; // create/rename/delete: not applicable here
+                const doc = changeRecord.textDocument;
+                if (doc === null || typeof doc !== 'object' || typeof doc.uri !== 'string')
+                    continue;
+                if (!Array.isArray(changeRecord.edits))
+                    continue;
+                for (const edit of changeRecord.edits) {
+                    ;
+                    (edits[doc.uri] ??= []).push(normalizeEdit(edit, decode));
+                }
+            }
+        }
+    }
+    return {
+        title: record.title,
+        ...kind === undefined ? {} : { kind },
+        ...isPreferred === undefined ? {} : { isPreferred },
+        edits,
+    };
+}
+/** Collect a wire `changes` map (`uri` → `TextEdit[]`) into the grouped edit record. */
+function collectWorkspaceEdits(changes, decode, into) {
+    if (changes === null || typeof changes !== 'object' || Array.isArray(changes)) {
+        throw malformedResponse('LSP code action changes must be an object');
+    }
+    for (const [uri, wireEdits] of Object.entries(changes)) {
+        if (!Array.isArray(wireEdits))
+            throw malformedResponse('LSP code action changes held a non-array edit list');
+        const normalized = wireEdits.map(edit => normalizeEdit(edit, decode));
+        if (normalized.length > 0) {
+            const existing = into[uri];
+            if (existing === undefined)
+                into[uri] = normalized;
+            else
+                existing.push(...normalized);
+        }
+    }
+}
+/**
+ * Normalize a `textDocument/rename` result (`WorkspaceEdit` or `null`) into the raw grouped edit
+ * record. Positions stay in the server's encoding — each document's edits are decoded per
+ * document by the caller, which owns that document's text. Resource operations (create/rename/
+ * delete) are refused: this client only applies text edits.
+ * @param payload - the raw WorkspaceEdit payload.
+ * @returns the grouped wire edits (empty for `null`).
+ * @throws LspActionError LSP_ACTION_MALFORMED_RESPONSE for structurally invalid entries, and
+ *   LSP_ACTION_UNSUPPORTED for resource operations.
+ */
+export function normalizeWorkspaceEdit(payload) {
+    if (payload === null)
+        return {};
+    if (payload === undefined || typeof payload !== 'object')
+        throw malformedResponse('LSP rename result was not an object');
+    const record = payload;
+    const edits = {};
+    if (record.changes !== undefined)
+        collectWorkspaceEdits(record.changes, undefined, edits);
+    if (record.documentChanges !== undefined) {
+        if (!Array.isArray(record.documentChanges))
+            throw malformedResponse('LSP rename documentChanges must be an array');
+        for (const change of record.documentChanges) {
+            if (change === null || typeof change !== 'object')
+                throw malformedResponse('LSP rename documentChanges contained a non-object entry');
+            const changeRecord = change;
+            if (changeRecord.kind !== undefined) {
+                throw new LspActionError(`the language server returned a ${String(changeRecord.kind)} file operation this client cannot apply — renames must be text edits`, 'LSP_ACTION_UNSUPPORTED');
+            }
+            const doc = changeRecord.textDocument;
+            if (doc === null || typeof doc !== 'object' || typeof doc.uri !== 'string') {
+                throw malformedResponse('LSP rename documentChange had no textDocument uri');
+            }
+            if (!Array.isArray(changeRecord.edits))
+                throw malformedResponse('LSP rename documentChange had no edits array');
+            const normalized = changeRecord.edits.map(edit => normalizeEdit(edit, undefined));
+            if (normalized.length > 0) {
+                const existing = edits[doc.uri];
+                if (existing === undefined)
+                    edits[doc.uri] = normalized;
+                else
+                    existing.push(...normalized);
+            }
+        }
+    }
+    return edits;
+}
+/**
+ * Decode one document's wire edits from the server's position encoding to utf-16.
+ * @param edits - the edits in the server's encoding.
+ * @param codec - the document's position codec (undefined for utf-16 servers).
+ * @param encoding - the negotiated position encoding.
+ * @returns the decoded edits.
+ */
+export function decodeTextEdits(edits, codec, encoding) {
+    if (codec === undefined)
+        return [...edits];
+    return edits.map(edit => ({ range: convertRange(edit.range, position => codec.decode(position, encoding)), newText: edit.newText }));
+}
+/**
+ * Normalize a `workspace/symbol` or `textDocument/documentSymbol` result into the action
+ * vocabulary. DocumentSymbol hierarchies are flattened depth-first, each node carrying its own
+ * range; SymbolInformation locations pass through verbatim.
+ * @param payload - the raw symbol result.
+ * @param documentUri - the URI DocumentSymbol entries belong to.
+ * @param decode - optional server-side position decoder (utf-8/utf-32 servers).
+ * @returns the normalized symbols (empty for `null`).
+ * @throws LspActionError LSP_ACTION_MALFORMED_RESPONSE for structurally invalid entries.
+ */
+export function normalizeSymbols(payload, documentUri, decode) {
+    if (payload === null)
+        return [];
+    if (payload === undefined)
+        throw malformedResponse('LSP symbol result was missing');
+    if (!Array.isArray(payload))
+        throw malformedResponse('LSP symbol result was not an array');
+    const symbols = [];
+    for (const entry of payload) {
+        if (entry === null || typeof entry !== 'object') {
+            throw malformedResponse('LSP symbol result contained a non-object entry');
+        }
+        const record = entry;
+        if (record.location !== undefined) {
+            symbols.push(normalizeSymbolInformation(record, decode));
+        }
+        else if (documentUri !== undefined) {
+            flattenDocumentSymbol(record, documentUri, decode, symbols);
+        }
+    }
+    return symbols;
+}
+/** Normalize one SymbolInformation. */
+function normalizeSymbolInformation(record, decode) {
+    if (typeof record.name !== 'string')
+        throw malformedResponse('LSP symbol had no name string');
+    const kind = requireIntegerField(record.kind, 'kind');
+    const location = record.location;
+    if (location === null || typeof location !== 'object')
+        throw malformedResponse('LSP symbol had no location object');
+    if (typeof location.uri !== 'string')
+        throw malformedResponse('LSP symbol location had no uri string');
+    return {
+        name: record.name,
+        kind,
+        location: { uri: location.uri, range: toRange(location.range, decode) },
+        ...typeof record.containerName === 'string' ? { containerName: record.containerName } : {},
+    };
+}
+/** Flatten one DocumentSymbol node (with its children) into the list. */
+function flattenDocumentSymbol(record, documentUri, decode, into) {
+    if (typeof record.name !== 'string')
+        throw malformedResponse('LSP document symbol had no name string');
+    const kind = requireIntegerField(record.kind, 'kind');
+    into.push({
+        name: record.name,
+        kind,
+        location: { uri: documentUri, range: toRange(record.range, decode) },
+        ...typeof record.containerName === 'string' ? { containerName: record.containerName } : {},
+    });
+    if (Array.isArray(record.children)) {
+        for (const child of record.children) {
+            if (child === null || typeof child !== 'object')
+                throw malformedResponse('LSP document symbol child was not an object');
+            flattenDocumentSymbol(child, documentUri, decode, into);
+        }
+    }
+}
+/**
+ * Normalize a `textDocument/signatureHelp` result into the action vocabulary. Documentation is
+ * normalized from MarkupContent to plain text; tuple parameter labels are sliced out of the
+ * signature label.
+ * @param payload - the raw signature help result.
+ * @returns the normalized signatures, or `{ signatures: [] }`-equivalent null result.
+ * @throws LspActionError LSP_ACTION_MALFORMED_RESPONSE for structurally invalid entries.
+ */
+export function normalizeSignatures(payload) {
+    if (payload === null)
+        return { signatures: [] };
+    if (payload === undefined || typeof payload !== 'object')
+        throw malformedResponse('LSP signature help result was not an object');
+    const record = payload;
+    if (!Array.isArray(record.signatures))
+        throw malformedResponse('LSP signature help had no signatures array');
+    const signatures = record.signatures.map(normalizeSignature);
+    return {
+        signatures,
+        ...typeof record.activeSignature === 'number' ? { activeSignature: record.activeSignature } : {},
+        ...typeof record.activeParameter === 'number' ? { activeParameter: record.activeParameter } : {},
+    };
+}
+/** Normalize one SignatureInformation. */
+function normalizeSignature(value) {
+    if (value === null || typeof value !== 'object')
+        throw malformedResponse('LSP signature help contained a non-object entry');
+    const record = value;
+    if (typeof record.label !== 'string')
+        throw malformedResponse('LSP signature had no label string');
+    const labelText = record.label;
+    let parameters;
+    if (record.parameters !== undefined) {
+        if (!Array.isArray(record.parameters))
+            throw malformedResponse('LSP signature parameters must be an array');
+        parameters = record.parameters.map((parameter) => {
+            const p = parameter;
+            if (p === null || typeof p !== 'object')
+                throw malformedResponse('LSP signature parameter was not an object');
+            const wire = p.label;
+            let label;
+            if (typeof wire === 'string') {
+                label = wire;
+            }
+            else if (Array.isArray(wire) && typeof wire[0] === 'number' && typeof wire[1] === 'number') {
+                label = labelText.slice(wire[0], wire[1]);
+            }
+            else {
+                throw malformedResponse('LSP signature parameter label must be a string or a [start, end] tuple');
+            }
+            return {
+                label,
+                ...p.documentation === undefined ? {} : { documentation: markupText(p.documentation) },
+            };
+        });
+    }
+    return {
+        label: labelText,
+        ...record.documentation === undefined ? {} : { documentation: markupText(record.documentation) },
+        ...parameters === undefined ? {} : { parameters },
+    };
+}
+/**
+ * Normalize a `textDocument/inlayHint` result into the action vocabulary. Multi-part labels are
+ * joined into plain text.
+ * @param payload - the raw inlay hint result.
+ * @param decode - optional server-side position decoder (utf-8/utf-32 servers).
+ * @returns the normalized hints (empty for `null`).
+ * @throws LspActionError LSP_ACTION_MALFORMED_RESPONSE for structurally invalid entries.
+ */
+export function normalizeInlayHints(payload, decode) {
+    if (payload === null)
+        return [];
+    if (payload === undefined)
+        throw malformedResponse('LSP inlay hint result was missing');
+    if (!Array.isArray(payload))
+        throw malformedResponse('LSP inlay hint result was not an array');
+    return payload.map((value) => {
+        if (value === null || typeof value !== 'object')
+            throw malformedResponse('LSP inlay hint result contained a non-object entry');
+        const record = value;
+        const position = isWirePosition(record.position)
+            ? toRange({ start: record.position, end: record.position }, decode).start
+            : undefined;
+        if (position === undefined)
+            throw malformedResponse('LSP inlay hint had no valid position');
+        const wireLabel = record.label;
+        let label;
+        if (typeof wireLabel === 'string') {
+            label = wireLabel;
+        }
+        else if (Array.isArray(wireLabel)) {
+            const parts = [];
+            for (const part of wireLabel) {
+                if (part === null || typeof part !== 'object' || typeof part.value !== 'string') {
+                    throw malformedResponse('LSP inlay hint label part had no value string');
+                }
+                parts.push(part.value);
+            }
+            label = parts.join('');
+        }
+        else {
+            throw malformedResponse('LSP inlay hint label must be a string or a part array');
+        }
+        return {
+            position,
+            label,
+            ...record.kind === undefined ? {} : { kind: requireIntegerField(record.kind, 'kind') },
+            ...record.paddingLeft === undefined ? {} : { paddingLeft: requireBoolean(record.paddingLeft, 'paddingLeft') },
+            ...record.paddingRight === undefined ? {} : { paddingRight: requireBoolean(record.paddingRight, 'paddingRight') },
+        };
+    });
+}
+/** Require an integer field, throwing the shared malformed-response error. */
+function requireIntegerField(value, name) {
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw malformedResponse(`LSP ${name} must be an integer`);
+    }
+    return value;
+}
+/** Require a boolean field, throwing the shared malformed-response error. */
+function requireBoolean(value, name) {
+    if (typeof value !== 'boolean')
+        throw malformedResponse(`LSP ${name} must be a boolean`);
+    return value;
+}
+/** Normalize `string | MarkupContent` documentation to plain text. */
+function markupText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === null || typeof value !== 'object')
+        throw malformedResponse('LSP documentation must be a string or MarkupContent');
+    const record = value;
+    if (typeof record.value !== 'string')
+        throw malformedResponse('LSP MarkupContent had no value string');
+    return record.value;
+}
+//# sourceMappingURL=translate.js.map