@coderline/alphatab-language-server 1.7.0-alpha.1626

package/src/server/hover.ts

@@ -0,0 +1,262 @@
+import * as alphaTab from '@coderline/alphatab';
+import {
+    allMetadata,
+    beatProperties,
+    durationChangeProperties,
+    noteProperties
+} from '@coderline/alphatab-alphatex/definitions';
+import type {
+    ParameterValueDefinition,
+    PropertyDefinition,
+    SignatureDefinition,
+    WithSignatures
+} from '@coderline/alphatab-alphatex/types';
+import type {
+    AlphaTexTextDocument,
+    Connection,
+    Hover,
+    TextDocuments
+} from '@coderline/alphatab-language-server/server/types';
+import {
+    binaryNodeSearch,
+    nodeTypesToTypeDocs as nodeTypesToSyntax,
+    parameterToSyntax,
+    resolveSignature
+} from '@coderline/alphatab-language-server/server/utils';
+
+export function setupHover(connection: Connection, documents: TextDocuments<AlphaTexTextDocument>) {
+    connection.onHover(params => {
+        const document = documents.get(params.textDocument.uri);
+        if (!document?.ast) {
+            return null;
+        }
+
+        const offset = document.offsetAt(params.position);
+
+        // lookup bar at location
+        const bar = binaryNodeSearch(document.ast.bars, offset);
+        if (!bar) {
+            return null;
+        }
+
+        const metaData = binaryNodeSearch(bar.metaData, offset);
+        if (metaData) {
+            return createMetaDataHover(metaData, offset);
+        }
+
+        const beat = binaryNodeSearch(bar.beats, offset);
+        if (beat) {
+            return createBeatHover(beat, offset);
+        }
+
+        return null;
+    });
+}
+
+function createMetaDataHover(metaData: alphaTab.importer.alphaTex.AlphaTexMetaDataNode, offset: number): Hover | null {
+    const metaDataDocs = allMetadata.get(`\\${metaData.tag.tag.text.toLowerCase()}`);
+    if (!metaDataDocs) {
+        return null;
+    }
+
+    if (metaData.tag.start!.offset <= offset && offset <= metaData.tag.end!.offset) {
+        return {
+            contents: {
+                kind: 'markdown',
+                value: withSignaturesToMarkdown(metaDataDocs, metaDataDocs.tag, 'Tag Syntax')
+            }
+        };
+    }
+
+    if (metaData.arguments) {
+        const hover = createArgumentsHover(metaData.arguments, metaDataDocs.signatures, offset);
+        if (hover != null) {
+            return hover;
+        }
+    }
+
+    if (metaData.properties && metaDataDocs.properties) {
+        const hover = createPropertiesHover(metaData.properties, metaDataDocs.properties, offset);
+        if (hover != null) {
+            return hover;
+        }
+    }
+
+    return null;
+}
+
+function createBeatHover(beat: alphaTab.importer.alphaTex.AlphaTexBeatNode, offset: number): Hover | null {
+    if (beat.durationChange?.properties) {
+        const hover = createPropertiesHover(beat.durationChange.properties, durationChangeProperties, offset);
+        if (hover != null) {
+            return hover;
+        }
+    }
+
+    if (beat.notes) {
+        const note = binaryNodeSearch(beat.notes.notes, offset);
+        if (note) {
+            return createNoteHover(note, offset);
+        }
+    }
+
+    if (beat.beatEffects) {
+        const hover = createPropertiesHover(beat.beatEffects, beatProperties, offset);
+        if (hover != null) {
+            return hover;
+        }
+    }
+
+    return null;
+}
+
+function createNoteHover(note: alphaTab.importer.alphaTex.AlphaTexNoteNode, offset: number): Hover | null {
+    if (note?.noteEffects) {
+        const hover = createPropertiesHover(note.noteEffects, [noteProperties, beatProperties], offset);
+        if (hover != null) {
+            return hover;
+        }
+    }
+
+    return null;
+}
+
+function createPropertiesHover(
+    properties: alphaTab.importer.alphaTex.AlphaTexPropertiesNode,
+    propertiesDocs: Map<string, PropertyDefinition> | Map<string, PropertyDefinition>[],
+    offset: number
+): Hover | null {
+    const prop = binaryNodeSearch(properties.properties, offset);
+    if (prop) {
+        let propDocs: PropertyDefinition | undefined;
+        if (Array.isArray(propertiesDocs)) {
+            for (const d of propertiesDocs) {
+                propDocs = d.get(prop.property.text.toLowerCase());
+                if (propDocs) {
+                    break;
+                }
+            }
+        } else {
+            propDocs = propertiesDocs.get(prop.property.text.toLowerCase());
+        }
+
+        if (propDocs) {
+            if (prop.property.start!.offset <= offset && offset <= prop.property.end!.offset) {
+                return {
+                    contents: {
+                        kind: 'markdown',
+                        value: withSignaturesToMarkdown(propDocs, propDocs.property)
+                    }
+                };
+            } else if (prop.arguments) {
+                const hover = createArgumentsHover(prop.arguments, propDocs.signatures, offset);
+                if (hover) {
+                    return hover;
+                }
+            }
+        }
+    }
+    return null;
+}
+
+function valueToText(value: alphaTab.importer.alphaTex.IAlphaTexArgumentValue): string {
+    switch (value.nodeType) {
+        case alphaTab.importer.alphaTex.AlphaTexNodeType.Ident:
+        case alphaTab.importer.alphaTex.AlphaTexNodeType.String:
+            return (value as alphaTab.importer.alphaTex.AlphaTexTextNode).text;
+        case alphaTab.importer.alphaTex.AlphaTexNodeType.Number:
+            return (value as alphaTab.importer.alphaTex.AlphaTexNumberLiteral).value.toString();
+    }
+
+    return '';
+}
+
+function createArgumentsHover(
+    values: alphaTab.importer.alphaTex.AlphaTexArgumentList,
+    signatures: SignatureDefinition[],
+    offset: number
+): Hover | null {
+    const value = binaryNodeSearch(values.arguments, offset);
+    if (value) {
+        const valueIndex = values.arguments.indexOf(value);
+        const signature = resolveSignature(signatures, values).values().next().value;
+        if (signature && valueIndex < signature.parameters.length) {
+            const parameterDoc = signature.parameters[valueIndex];
+            const valueText = valueToText(value).toLowerCase();
+            const valueItem = parameterDoc.values?.find(d => d.name.toLowerCase() === valueText);
+            if (valueItem) {
+                return {
+                    contents: {
+                        kind: 'markdown',
+                        value: parameterValueDocsToMarkDown(valueItem)
+                    }
+                };
+            }
+        }
+    }
+    return null;
+}
+
+function withSignaturesToMarkdown(docs: WithSignatures, prefix: string, syntaxName: string = 'Syntax'): string {
+    return [
+        `## ${docs.shortDescription}`,
+        docs.longDescription ? `**Description:** ${docs.longDescription}` : '',
+        '',
+        `**${syntaxName}:**`,
+        '```alphatex',
+        ...docs.signatures.map((s, i) => signatureToSyntax(prefix, s, i, docs.signatures.length > 1)),
+        '```',
+        '',
+        signatureParametersToMarkdownTable(docs.signatures)
+    ].join('\n');
+}
+
+function signatureParametersToMarkdownTable(signatures: SignatureDefinition[]): string {
+    return signatures.length === 0 || (signatures.length === 1 && signatures[0].parameters.length === 0)
+        ? ''
+        : [
+              '',
+              '**Parameters:**',
+              '| Name | Description | Type | Required |',
+              '|------|-------------|------|----------|',
+              ...signatures.flatMap((s, si) =>
+                  s.parameters.map(v => {
+                      const index = signatures.length > 1 ? `[^${si + 1}] ` : '';
+                      return `| \`${v.name}\` ${index}| ${(v.longDescription ?? v.shortDescription)?.replaceAll('\n', '<br />') ?? ''} | \`${nodeTypesToSyntax(v).replaceAll('|', '\\|')}\` | ${isRequiredParameter(v.parseMode) ? 'yes' : 'no'} ${v.defaultValue ?? ''} |`;
+                  })
+              )
+          ].join('\n');
+}
+
+function parameterValueDocsToMarkDown(docs: ParameterValueDefinition): string {
+    return [`## ${docs.name}`, docs.longDescription ?? docs.shortDescription, ''].join('\n');
+}
+
+function signatureToSyntax(prefix: string, value: SignatureDefinition, index: number, hasOverloads: boolean): string {
+    let syntax = '';
+
+    if (hasOverloads) {
+        syntax += `// [^${index + 1}]: ${value.description}\n`;
+    } else if (value.description) {
+        syntax += `//  ${value.description}\n`;
+    }
+
+
+    syntax += prefix;
+    if(value.parameters.length > 0) {
+        syntax += `(${value.parameters.map(p => parameterToSyntax(p, true)).join(' ')})`;
+    }
+
+    return syntax;
+}
+
+function isRequiredParameter(parseMode: alphaTab.importer.alphaTex.ArgumentListParseTypesMode) {
+    switch (parseMode) {
+        case alphaTab.importer.alphaTex.ArgumentListParseTypesMode.Required:
+        case alphaTab.importer.alphaTex.ArgumentListParseTypesMode.RequiredAsFloat:
+        case alphaTab.importer.alphaTex.ArgumentListParseTypesMode.RequiredAsValueList:
+            return true;
+        default:
+            return false;
+    }
+}

package/src/server/index.ts

@@ -0,0 +1,96 @@
+import { setupCompletion } from '@coderline/alphatab-language-server/server/completion';
+import { setupDiagnostics } from '@coderline/alphatab-language-server/server/diagnostics';
+import { setupHover } from '@coderline/alphatab-language-server/server/hover';
+import { setupSignatureHelp } from '@coderline/alphatab-language-server/server/signatureHelp';
+import {
+    type AlphaTexTextDocument,
+    type Connection,
+    type InitializeParams,
+    type InitializeResult,
+    PositionEncodingKind,
+    TextDocument,
+    TextDocumentSyncKind,
+    TextDocuments
+} from '@coderline/alphatab-language-server/server/types';
+
+// the only place where we should import specif vscode-languageserver packages
+import {
+    BrowserMessageReader,
+    BrowserMessageWriter,
+    createConnection as createBrowserConnection
+} from 'vscode-languageserver/lib/browser/main.js';
+import {
+    createConnection as createNodeConnection,
+    ProposedFeatures as NodeProposedFeatures
+} from 'vscode-languageserver/lib/node/main.js';
+
+function startLanguageServer(serverConnection: Connection) {
+    const documents = new TextDocuments<AlphaTexTextDocument>(TextDocument);
+
+    serverConnection.onInitialize((params: InitializeParams) => {
+        const capabilities = params.capabilities;
+
+        const hasWorkspaceFolderCapability = !!(capabilities.workspace && !!capabilities.workspace.workspaceFolders);
+
+        const result: InitializeResult = {
+            capabilities: {
+                textDocumentSync: TextDocumentSyncKind.Incremental,
+                positionEncoding: PositionEncodingKind.UTF16,
+                completionProvider: {
+                    resolveProvider: true
+                },
+                signatureHelpProvider: {
+                    triggerCharacters: ['(']
+                },
+                diagnosticProvider: {
+                    interFileDependencies: false,
+                    workspaceDiagnostics: false
+                },
+                hoverProvider: {}
+            }
+        };
+        if (hasWorkspaceFolderCapability) {
+            result.capabilities.workspace = {
+                workspaceFolders: {
+                    supported: true
+                }
+            };
+        }
+        return result;
+    });
+
+    setupDiagnostics(serverConnection, documents);
+    setupCompletion(serverConnection, documents);
+    setupHover(serverConnection, documents);
+    setupSignatureHelp(serverConnection, documents);
+
+    documents.listen(serverConnection);
+    serverConnection.listen();
+}
+
+
+type Port = ConstructorParameters<typeof BrowserMessageReader>[0];
+
+/**
+ * Starts a new language server communicating via WebWorker.
+ * @param readerPort The port used to reading incoming language server messages
+ * @param writerPort The port used to writer outgoing language server messages
+ */
+export function startWebWorkerLanguageServer(
+    readerPort: Port,
+    writerPort: Port
+) {
+    startLanguageServer(
+        createBrowserConnection(
+            new BrowserMessageReader(readerPort),
+            new BrowserMessageWriter(writerPort)
+        )
+    );
+}
+
+/**
+ * Starts a new language server communicating from a Node.js process with a parent Node.js.
+ */
+export function startNodeLanguageServer() {
+    startLanguageServer(createNodeConnection(NodeProposedFeatures.all));
+}

package/src/server/signatureHelp.ts

@@ -0,0 +1,206 @@
+import type * as alphaTab from '@coderline/alphatab';
+import {
+    allMetadata,
+    beatProperties,
+    durationChangeProperties,
+    noteProperties
+} from '@coderline/alphatab-alphatex/definitions';
+import type {
+    ParameterDefinition,
+    PropertyDefinition,
+    SignatureDefinition,
+    WithSignatures
+} from '@coderline/alphatab-alphatex/types';
+import {
+    type AlphaTexTextDocument,
+    type Connection,
+    ParameterInformation,
+    type SignatureHelp,
+    SignatureInformation,
+    type TextDocuments
+} from '@coderline/alphatab-language-server/server/types';
+import { binaryNodeSearch, parameterToSyntax } from '@coderline/alphatab-language-server/server/utils';
+
+export function setupSignatureHelp(connection: Connection, documents: TextDocuments<AlphaTexTextDocument>) {
+    connection.onSignatureHelp(params => {
+        const document = documents.get(params.textDocument.uri);
+        if (!document?.ast) {
+            return null;
+        }
+
+        const offset = document.offsetAt(params.position);
+
+        // lookup bar at location
+        const bar = binaryNodeSearch(document.ast.bars, offset);
+        if (!bar) {
+            return null;
+        }
+
+        const metaData = binaryNodeSearch(bar.metaData, offset);
+        if (metaData) {
+            return createMetaDataSignatureHelp(metaData, offset);
+        }
+
+        const beat = binaryNodeSearch(bar.beats, offset);
+        if (beat) {
+            return createBeatSignatureHelp(beat, offset);
+        }
+
+        return null;
+    });
+}
+
+function createMetaDataSignatureHelp(
+    metaData: alphaTab.importer.alphaTex.AlphaTexMetaDataNode,
+    offset: number
+): SignatureHelp | null {
+    const metaDataDocs = allMetadata.get(`\\${metaData.tag.tag.text.toLowerCase()}`);
+    if (!metaDataDocs) {
+        return null;
+    }
+
+    const endOfValues = metaData.arguments?.end!.offset ?? metaData.properties?.start!.offset ?? metaData.end!.offset;
+    if (metaData.start!.offset <= offset && offset < endOfValues) {
+        return createArgumentsSignatureHelp(`\\${metaData.tag.tag.text}`, metaDataDocs, metaData.arguments, offset);
+    }
+
+    if (metaData.properties && metaDataDocs.properties) {
+        const help = createPropertiesSignatureHelp(metaData.properties, metaDataDocs.properties, offset);
+        if (help != null) {
+            return help;
+        }
+    }
+
+    return null;
+}
+
+function createBeatSignatureHelp(
+    beat: alphaTab.importer.alphaTex.AlphaTexBeatNode,
+    offset: number
+): SignatureHelp | null {
+    if (beat.durationChange?.properties) {
+        const hover = createPropertiesSignatureHelp(beat.durationChange.properties, durationChangeProperties, offset);
+        if (hover != null) {
+            return hover;
+        }
+    }
+
+    if (beat.notes) {
+        const note = binaryNodeSearch(beat.notes.notes, offset);
+        if (note) {
+            return createNoteSignatureHelp(note, offset);
+        }
+    }
+
+    if (beat.beatEffects) {
+        const hover = createPropertiesSignatureHelp(beat.beatEffects, beatProperties, offset);
+        if (hover != null) {
+            return hover;
+        }
+    }
+
+    return null;
+}
+
+function createNoteSignatureHelp(
+    note: alphaTab.importer.alphaTex.AlphaTexNoteNode,
+    offset: number
+): SignatureHelp | null {
+    if (note?.noteEffects) {
+        const hover = createPropertiesSignatureHelp(note.noteEffects, [noteProperties, beatProperties], offset);
+        if (hover != null) {
+            return hover;
+        }
+    }
+
+    return null;
+}
+
+function createPropertiesSignatureHelp(
+    properties: alphaTab.importer.alphaTex.AlphaTexPropertiesNode,
+    propertiesDocs: Map<string, PropertyDefinition> | Map<string, PropertyDefinition>[],
+    offset: number
+): SignatureHelp | null {
+    const prop = binaryNodeSearch(properties.properties, offset);
+    if (!prop) {
+        return null;
+    }
+
+    let propDocs: PropertyDefinition | undefined;
+    if (Array.isArray(propertiesDocs)) {
+        for (const d of propertiesDocs) {
+            propDocs = d.get(prop.property.text.toLowerCase());
+            if (propDocs) {
+                break;
+            }
+        }
+    } else {
+        propDocs = propertiesDocs.get(prop.property.text.toLowerCase());
+    }
+
+    if (propDocs) {
+        return createArgumentsSignatureHelp(prop.property.text, propDocs, prop.arguments, offset);
+    }
+
+    return null;
+}
+
+function createArgumentsSignatureHelp(
+    parentItemLabel: string,
+    docs: WithSignatures,
+    values: alphaTab.importer.alphaTex.AlphaTexArgumentList | undefined,
+    offset: number
+): SignatureHelp | null {
+    const help: SignatureHelp = {
+        signatures: docs.signatures.map(s => signatureDefinitionToHelp(parentItemLabel, docs, s)),
+        activeSignature: undefined,
+        activeParameter: undefined
+    };
+
+    if (!values) {
+        return help;
+    }
+
+    if (values.signatureCandidateIndices !== undefined) {
+        help.activeSignature = values.signatureCandidateIndices[0];
+        const value = binaryNodeSearch(values.arguments, offset);
+        if (value) {
+            if (value.parameterIndices !== undefined) {
+                for (const [signatureIndex, parameterIndex] of value.parameterIndices) {
+                    if (parameterIndex >= 0) {
+                        help.signatures[signatureIndex].activeParameter = parameterIndex;
+                    }
+                }
+            }
+        }
+    }
+
+    return help;
+}
+
+function createParameterInfo(signature: SignatureInformation, doc: ParameterDefinition) {
+    const start = signature.label.length;
+    signature.label += parameterToSyntax(doc, false);
+
+    const end = signature.label.length;
+    signature.parameters!.push(ParameterInformation.create([start, end], doc.longDescription ?? doc.shortDescription));
+}
+
+function signatureDefinitionToHelp(
+    label: string,
+    docs: WithSignatures,
+    signature: SignatureDefinition
+): SignatureInformation {
+    const signatureDocs = SignatureInformation.create(`${label} `, docs.longDescription ?? docs.shortDescription);
+
+    signatureDocs.label += ' (';
+    for (let i = 0; i < signature.parameters.length; i++) {
+        if (i > 0) {
+            signatureDocs.label += ' ';
+        }
+        createParameterInfo(signatureDocs, signature.parameters[i]);
+    }
+
+    signatureDocs.label += ')';
+    return signatureDocs;
+}

package/src/server/types.ts

@@ -0,0 +1,28 @@
+import type * as alphaTab from '@coderline/alphatab';
+import type { createConnection as createBrowserConnection } from 'vscode-languageserver/lib/browser/main.js';
+import type { createConnection as createNodeConnection } from 'vscode-languageserver/lib/node/main.js';
+import type { TextDocument } from 'vscode-languageserver-textdocument';
+
+export type NodeConnection = ReturnType<typeof createNodeConnection>;
+export type BrowserConnection = ReturnType<typeof createBrowserConnection>;
+
+export type Connection = NodeConnection | BrowserConnection;
+
+export interface AlphaTexTextDocument extends TextDocument {
+    score?: alphaTab.model.Score;
+    ast?: alphaTab.importer.alphaTex.AlphaTexScoreNode;
+}
+
+export { type RemoteConsole, type TextDocumentPositionParams, TextDocuments } from 'vscode-languageserver';
+
+export {type DocumentDiagnosticReport, 
+    DocumentDiagnosticReportKind, type InitializeParams,
+    type InitializeResult, PositionEncodingKind,
+    TextDocumentSyncKind 
+} from 'vscode-languageserver-protocol';
+export { TextDocument } from 'vscode-languageserver-textdocument';
+export {type CompletionItem,
+    CompletionItemKind, 
+    type Diagnostic, DiagnosticSeverity, type Hover, InsertTextFormat, ParameterInformation, type SignatureHelp, SignatureInformation, TextEdit,
+    uinteger 
+} from 'vscode-languageserver-types';

package/src/server/utils.ts

@@ -0,0 +1,111 @@
+import * as alphaTab from '@coderline/alphatab';
+import type { ParameterDefinition, SignatureDefinition } from '@coderline/alphatab-alphatex/types';
+
+function binaryNodeSearchInner<T extends alphaTab.importer.alphaTex.AlphaTexAstNode>(
+    items: T[],
+    offset: number,
+    left: number = 0,
+    right: number = items.length,
+    trailingEnd: number
+) {
+    if (left > right) {
+        return undefined;
+    }
+
+    const center = Math.trunc((left + right) / 2);
+    const centerItem = items[center];
+
+    // match
+    const end = center === items.length - 1 ? trailingEnd : items[center + 1].start!.offset;
+    if (centerItem.start!.offset <= offset && offset <= end) {
+        return centerItem;
+    }
+
+    // left half
+    if (offset < centerItem.start!.offset) {
+        return binaryNodeSearchInner(items, offset, left, center, trailingEnd);
+    }
+
+    // right half
+    return binaryNodeSearchInner(items, offset, center, right, trailingEnd);
+}
+
+export function binaryNodeSearch<T extends alphaTab.importer.alphaTex.AlphaTexAstNode>(
+    items: T[],
+    offset: number,
+    trailingEnd: number = items.length > 0 ? items[items.length - 1].end!.offset : 0
+) {
+    // no items
+    if (items.length === 0) {
+        return undefined;
+    }
+
+    // not in range
+    const rangeStart = items[0].start!.offset;
+    const rangeEnd = trailingEnd;
+    if (offset < rangeStart || offset > rangeEnd) {
+        return undefined;
+    }
+
+    return binaryNodeSearchInner(items, offset, 0, items.length, trailingEnd);
+}
+
+export function resolveSignature(
+    signatures: SignatureDefinition[],
+    args: alphaTab.importer.alphaTex.AlphaTexArgumentList
+): Map<number, SignatureDefinition> {
+    const resolved = new Map<number, SignatureDefinition>();
+
+    if (args.signatureCandidateIndices !== undefined) {
+        for (const i of args.signatureCandidateIndices) {
+            resolved.set(i, signatures[i]);
+        }
+    }
+
+    return resolved;
+}
+
+export function parameterToSyntax(parameter: ParameterDefinition, onlyParameterNames: boolean) {
+    let p: string = parameter.name;
+    if (!onlyParameterNames) {
+        switch (parameter.parseMode) {
+            case alphaTab.importer.alphaTex.ArgumentListParseTypesMode.Optional:
+            case alphaTab.importer.alphaTex.ArgumentListParseTypesMode.OptionalAsFloat:
+                p += '?';
+                break;
+        }
+        p += `: ${nodeTypesToTypeDocs(parameter)}`;
+
+        if (parameter.defaultValue) {
+            p += ` = ${parameter.defaultValue}`;
+        }
+    }
+
+    return p;
+}
+
+export function nodeTypesToTypeDocs(parameter: ParameterDefinition) {
+    const typeArray = Array.isArray(parameter.type) ? parameter.type : [parameter.type];
+    let p: string = '';
+    if (parameter.values && !parameter.valuesOnlyForCompletion && parameter.values.length < 5) {
+        const valueArray = parameter.values.map(v => v.name);
+        switch (typeArray[0]) {
+            case alphaTab.importer.alphaTex.AlphaTexNodeType.String:
+                p = valueArray.map(v => `"${v}"`).join('|');
+                break;
+            default:
+                p = valueArray.join('|');
+                break;
+        }
+    } else {
+        p = typeArray.map(t => alphaTab.importer.alphaTex.AlphaTexNodeType[t]).join('|');
+    }
+
+    switch (parameter.parseMode) {
+        case alphaTab.importer.alphaTex.ArgumentListParseTypesMode.RequiredAsValueList:
+        case alphaTab.importer.alphaTex.ArgumentListParseTypesMode.ValueListWithoutParenthesis:
+            p += '[]';
+    }
+
+    return p;
+}