@formspec/language-server 0.1.0-alpha.22 → 0.1.0-alpha.25

package/dist/language-server-alpha.d.ts

@@ -0,0 +1,312 @@
+/**
+ * \@formspec/language-server
+ *
+ * Language server for FormSpec — provides completions, hover documentation,
+ * and go-to-definition for FormSpec JSDoc constraint tags (`@Minimum`,
+ * `@Maximum`, `@Pattern`, etc.) in TypeScript files.
+ *
+ * This package implements the Language Server Protocol (LSP) using the
+ * `vscode-languageserver` library. Cheap syntax-local behaviors stay in the
+ * LSP process, while TypeScript-project-aware semantics are supplied by
+ * `@formspec/ts-plugin` over a local manifest + IPC transport.
+ *
+ * The packaged server acts as a reference implementation over the composable
+ * completion, hover, and diagnostics helpers exported from this package.
+ *
+ * @example
+ * ```ts
+ * import { createServer } from '@formspec/language-server';
+ *
+ * const connection = createServer();
+ * connection.listen();
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { CompletionItem } from 'vscode-languageserver/node.js';
+import { Connection } from 'vscode-languageserver/node.js';
+import { Diagnostic } from 'vscode-languageserver/node.js';
+import type { ExtensionDefinition } from '@formspec/core';
+import type { Hover } from 'vscode-languageserver/node.js';
+import type { Location } from 'vscode-languageserver/node.js';
+import type { TextDocument } from 'vscode-languageserver-textdocument';
+
+/** @public */
+export declare interface CommentSourceSpan {
+    readonly start: number;
+    readonly end: number;
+}
+
+/** @public */
+export declare type CommentSpan = CommentSourceSpan;
+
+/**
+ * Creates and configures the FormSpec language server connection.
+ *
+ * Registers LSP capability handlers and returns the connection.
+ * Call `connection.listen()` to start accepting messages.
+ *
+ * @returns The configured LSP connection (not yet listening)
+ * @public
+ */
+export declare function createServer(options?: CreateServerOptions): Connection;
+
+/**
+ * Public configuration for constructing the FormSpec language server.
+ *
+ * @public
+ */
+export declare interface CreateServerOptions {
+    /** Optional extension definitions whose custom tags should be surfaced by tooling. */
+    readonly extensions?: readonly ExtensionDefinition[];
+    /** Optional workspace roots to use before initialize() provides them. */
+    readonly workspaceRoots?: readonly string[];
+    /** Set to false to disable tsserver-plugin semantic enrichment. */
+    readonly usePluginTransport?: boolean;
+    /** IPC timeout, in milliseconds, for semantic plugin requests. */
+    readonly pluginQueryTimeoutMs?: number;
+    /** Optional diagnostics publishing mode for the packaged reference LSP. */
+    readonly diagnosticsMode?: "off" | "plugin";
+    /** Source label to use when publishing plugin-derived diagnostics. */
+    readonly diagnosticSource?: string;
+}
+
+/**
+ * Converts a `file://` URI to an absolute filesystem path.
+ *
+ * Returns `null` for any URI that is not a valid `file://` URI (e.g. `untitled:`, `vscode-notebook-cell:`,
+ * malformed URIs). On Windows the returned path uses backslash separators as produced by
+ * `url.fileURLToPath`.
+ *
+ * @public
+ */
+export declare function fileUriToPathOrNull(uri: string): string | null;
+
+/**
+ * File-local diagnostic derived from comment parsing or semantic analysis.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisDiagnostic {
+    readonly code: string;
+    readonly category: FormSpecAnalysisDiagnosticCategory;
+    readonly message: string;
+    readonly range: CommentSpan;
+    readonly severity: "error" | "warning" | "info";
+    readonly relatedLocations: readonly FormSpecAnalysisDiagnosticLocation[];
+    readonly data: Record<string, FormSpecAnalysisDiagnosticDataValue>;
+}
+
+/**
+ * Machine-readable diagnostic category used by FormSpec tooling surfaces.
+ *
+ * @public
+ */
+export declare type FormSpecAnalysisDiagnosticCategory = "tag-recognition" | "value-parsing" | "type-compatibility" | "target-resolution" | "constraint-validation" | "infrastructure";
+
+/**
+ * Primitive structured values carried in diagnostic facts for white-label
+ * downstream rendering.
+ *
+ * @public
+ */
+export declare type FormSpecAnalysisDiagnosticDataValue = string | number | boolean | readonly string[] | readonly number[] | readonly boolean[];
+
+/**
+ * Additional source location associated with a diagnostic.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisDiagnosticLocation {
+    readonly filePath: string;
+    readonly range: CommentSpan;
+    readonly message?: string;
+}
+
+/** @public */
+declare type FormSpecPlacement = "class" | "class-field" | "class-method" | "interface" | "interface-field" | "type-alias" | "type-alias-field" | "variable" | "function" | "function-parameter" | "method-parameter";
+
+/**
+ * Cursor-scoped completion context serialized for transport between the
+ * semantic tsserver plugin and the lightweight LSP.
+ *
+ * @public
+ */
+declare type FormSpecSerializedCompletionContext = {
+    readonly kind: "tag-name";
+    readonly prefix: string;
+    readonly availableTags: readonly FormSpecSerializedTagDefinition[];
+} | {
+    readonly kind: "target";
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+} | {
+    readonly kind: "argument";
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+    readonly valueLabels: readonly string[];
+} | {
+    readonly kind: "none";
+};
+
+/**
+ * Hover payload for a single comment token under the cursor.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedHoverInfo {
+    readonly kind: "tag-name" | "target" | "argument";
+    readonly markdown: string;
+}
+
+/**
+ * Serializable subset of tag metadata needed by hover and completion UIs.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagDefinition {
+    readonly canonicalName: string;
+    readonly completionDetail: string;
+    readonly hoverMarkdown: string;
+}
+
+/**
+ * Semantic facts about one parsed tag, reduced to JSON-safe data for IPC.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagSemanticContext {
+    readonly tagName: string;
+    readonly tagDefinition: FormSpecSerializedTagDefinition | null;
+    readonly placement: FormSpecPlacement | null;
+    readonly supportedTargets: readonly FormSpecTargetKind[];
+    readonly targetCompletions: readonly string[];
+    readonly compatiblePathTargets: readonly string[];
+    readonly valueLabels: readonly string[];
+    readonly signatures: readonly FormSpecSerializedTagSignature[];
+    readonly tagHoverMarkdown: string | null;
+    readonly targetHoverMarkdown: string | null;
+    readonly argumentHoverMarkdown: string | null;
+}
+
+/**
+ * Serializable overload/signature summary for one comment tag form.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagSignature {
+    readonly label: string;
+    readonly placements: readonly FormSpecPlacement[];
+}
+
+/** @public */
+declare type FormSpecTargetKind = "none" | "path" | "member" | "variant";
+
+/**
+ * Returns the full set of tag-name completions currently known to FormSpec.
+ *
+ * @public
+ */
+export declare function getCompletionItems(extensions?: readonly ExtensionDefinition[]): CompletionItem[];
+
+/**
+ * Returns completion items for the cursor position at `offset` in `documentText`.
+ *
+ * When `semanticContext` is supplied (e.g. from {@link getPluginCompletionContextForDocument}),
+ * it is used directly to produce target-value or tag-name completions. Pass `null` or omit it
+ * to fall back to syntax-only analysis, which works without the TypeScript plugin.
+ *
+ * @public
+ */
+export declare function getCompletionItemsAtOffset(documentText: string, offset: number, extensions?: readonly ExtensionDefinition[], semanticContext?: FormSpecSerializedCompletionContext | null): CompletionItem[];
+
+/**
+ * Returns the definition location for a symbol at the given position.
+ *
+ * Always returns `null` in this stub implementation.
+ *
+ * @returns `null` — not yet implemented
+ * @public
+ */
+export declare function getDefinition(): Location | null;
+
+/**
+ * Returns LSP hover content for the cursor position at `offset` in `documentText`.
+ *
+ * When `semanticHover` is supplied (e.g. from {@link getPluginHoverForDocument}), it is used
+ * directly as the hover source. Pass `null` or omit it to fall back to syntax-only analysis,
+ * which works without the TypeScript plugin. Returns `null` when the cursor is not over a
+ * recognised FormSpec tag.
+ *
+ * @public
+ */
+export declare function getHoverAtOffset(documentText: string, offset: number, extensions?: readonly ExtensionDefinition[], semanticHover?: FormSpecSerializedHoverInfo | null): Hover | null;
+
+/**
+ * Returns hover content for a single FormSpec tag name.
+ *
+ * @public
+ */
+export declare function getHoverForTag(tagName: string, extensions?: readonly ExtensionDefinition[]): Hover | null;
+
+/**
+ * Queries the FormSpec TypeScript plugin for semantic completion context at `offset` in the
+ * document identified by `filePath`.
+ *
+ * The workspace root containing `filePath` is located automatically from `workspaceRoots`. The
+ * plugin manifest is read from disk on each call. Returns `null` when no matching workspace root
+ * is found, the manifest is missing or invalid, the IPC socket is unavailable, the plugin times
+ * out (default 2 s), or the plugin's response was computed against a different version of the
+ * document than `documentText` (stale response guard).
+ *
+ * Pass the result to {@link getCompletionItemsAtOffset} as `semanticContext`.
+ *
+ * @public
+ */
+export declare function getPluginCompletionContextForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedCompletionContext | null>;
+
+/**
+ * Retrieves canonical FormSpec diagnostics for the current document revision
+ * from the plugin transport. Returns `null` when the transport is missing,
+ * stale, or invalid.
+ *
+ * @public
+ */
+export declare function getPluginDiagnosticsForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, timeoutMs?: number): Promise<readonly FormSpecAnalysisDiagnostic[] | null>;
+
+/**
+ * Queries the FormSpec TypeScript plugin for semantic hover information at `offset` in the
+ * document identified by `filePath`.
+ *
+ * The workspace root containing `filePath` is located automatically from `workspaceRoots`. The
+ * plugin manifest is read from disk on each call. Returns `null` when no matching workspace root
+ * is found, the manifest is missing or invalid, the IPC socket is unavailable, the plugin times
+ * out (default 2 s), or the plugin's response was computed against a different version of the
+ * document than `documentText` (stale response guard).
+ *
+ * Pass the result to {@link getHoverAtOffset} as `semanticHover`.
+ *
+ * @public
+ */
+export declare function getPluginHoverForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedHoverInfo | null>;
+
+/**
+ * Converts canonical FormSpec diagnostics into LSP diagnostics.
+ *
+ * Downstream consumers that want complete white-label control can ignore this
+ * helper and render their own messages from `code` + `data`.
+ *
+ * @public
+ */
+export declare function toLspDiagnostics(document: TextDocument, diagnostics: readonly FormSpecAnalysisDiagnostic[], options?: ToLspDiagnosticsOptions): Diagnostic[];
+
+/**
+ * Options for converting canonical FormSpec diagnostics into LSP diagnostics.
+ *
+ * @public
+ */
+export declare interface ToLspDiagnosticsOptions {
+    /** Source label shown by LSP clients. Defaults to `formspec`. */
+    readonly source?: string;
+}
+
+export { }

package/dist/language-server-beta.d.ts

@@ -0,0 +1,312 @@
+/**
+ * \@formspec/language-server
+ *
+ * Language server for FormSpec — provides completions, hover documentation,
+ * and go-to-definition for FormSpec JSDoc constraint tags (`@Minimum`,
+ * `@Maximum`, `@Pattern`, etc.) in TypeScript files.
+ *
+ * This package implements the Language Server Protocol (LSP) using the
+ * `vscode-languageserver` library. Cheap syntax-local behaviors stay in the
+ * LSP process, while TypeScript-project-aware semantics are supplied by
+ * `@formspec/ts-plugin` over a local manifest + IPC transport.
+ *
+ * The packaged server acts as a reference implementation over the composable
+ * completion, hover, and diagnostics helpers exported from this package.
+ *
+ * @example
+ * ```ts
+ * import { createServer } from '@formspec/language-server';
+ *
+ * const connection = createServer();
+ * connection.listen();
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { CompletionItem } from 'vscode-languageserver/node.js';
+import { Connection } from 'vscode-languageserver/node.js';
+import { Diagnostic } from 'vscode-languageserver/node.js';
+import type { ExtensionDefinition } from '@formspec/core';
+import type { Hover } from 'vscode-languageserver/node.js';
+import type { Location } from 'vscode-languageserver/node.js';
+import type { TextDocument } from 'vscode-languageserver-textdocument';
+
+/** @public */
+export declare interface CommentSourceSpan {
+    readonly start: number;
+    readonly end: number;
+}
+
+/** @public */
+export declare type CommentSpan = CommentSourceSpan;
+
+/**
+ * Creates and configures the FormSpec language server connection.
+ *
+ * Registers LSP capability handlers and returns the connection.
+ * Call `connection.listen()` to start accepting messages.
+ *
+ * @returns The configured LSP connection (not yet listening)
+ * @public
+ */
+export declare function createServer(options?: CreateServerOptions): Connection;
+
+/**
+ * Public configuration for constructing the FormSpec language server.
+ *
+ * @public
+ */
+export declare interface CreateServerOptions {
+    /** Optional extension definitions whose custom tags should be surfaced by tooling. */
+    readonly extensions?: readonly ExtensionDefinition[];
+    /** Optional workspace roots to use before initialize() provides them. */
+    readonly workspaceRoots?: readonly string[];
+    /** Set to false to disable tsserver-plugin semantic enrichment. */
+    readonly usePluginTransport?: boolean;
+    /** IPC timeout, in milliseconds, for semantic plugin requests. */
+    readonly pluginQueryTimeoutMs?: number;
+    /** Optional diagnostics publishing mode for the packaged reference LSP. */
+    readonly diagnosticsMode?: "off" | "plugin";
+    /** Source label to use when publishing plugin-derived diagnostics. */
+    readonly diagnosticSource?: string;
+}
+
+/**
+ * Converts a `file://` URI to an absolute filesystem path.
+ *
+ * Returns `null` for any URI that is not a valid `file://` URI (e.g. `untitled:`, `vscode-notebook-cell:`,
+ * malformed URIs). On Windows the returned path uses backslash separators as produced by
+ * `url.fileURLToPath`.
+ *
+ * @public
+ */
+export declare function fileUriToPathOrNull(uri: string): string | null;
+
+/**
+ * File-local diagnostic derived from comment parsing or semantic analysis.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisDiagnostic {
+    readonly code: string;
+    readonly category: FormSpecAnalysisDiagnosticCategory;
+    readonly message: string;
+    readonly range: CommentSpan;
+    readonly severity: "error" | "warning" | "info";
+    readonly relatedLocations: readonly FormSpecAnalysisDiagnosticLocation[];
+    readonly data: Record<string, FormSpecAnalysisDiagnosticDataValue>;
+}
+
+/**
+ * Machine-readable diagnostic category used by FormSpec tooling surfaces.
+ *
+ * @public
+ */
+export declare type FormSpecAnalysisDiagnosticCategory = "tag-recognition" | "value-parsing" | "type-compatibility" | "target-resolution" | "constraint-validation" | "infrastructure";
+
+/**
+ * Primitive structured values carried in diagnostic facts for white-label
+ * downstream rendering.
+ *
+ * @public
+ */
+export declare type FormSpecAnalysisDiagnosticDataValue = string | number | boolean | readonly string[] | readonly number[] | readonly boolean[];
+
+/**
+ * Additional source location associated with a diagnostic.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisDiagnosticLocation {
+    readonly filePath: string;
+    readonly range: CommentSpan;
+    readonly message?: string;
+}
+
+/** @public */
+declare type FormSpecPlacement = "class" | "class-field" | "class-method" | "interface" | "interface-field" | "type-alias" | "type-alias-field" | "variable" | "function" | "function-parameter" | "method-parameter";
+
+/**
+ * Cursor-scoped completion context serialized for transport between the
+ * semantic tsserver plugin and the lightweight LSP.
+ *
+ * @public
+ */
+declare type FormSpecSerializedCompletionContext = {
+    readonly kind: "tag-name";
+    readonly prefix: string;
+    readonly availableTags: readonly FormSpecSerializedTagDefinition[];
+} | {
+    readonly kind: "target";
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+} | {
+    readonly kind: "argument";
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+    readonly valueLabels: readonly string[];
+} | {
+    readonly kind: "none";
+};
+
+/**
+ * Hover payload for a single comment token under the cursor.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedHoverInfo {
+    readonly kind: "tag-name" | "target" | "argument";
+    readonly markdown: string;
+}
+
+/**
+ * Serializable subset of tag metadata needed by hover and completion UIs.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagDefinition {
+    readonly canonicalName: string;
+    readonly completionDetail: string;
+    readonly hoverMarkdown: string;
+}
+
+/**
+ * Semantic facts about one parsed tag, reduced to JSON-safe data for IPC.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagSemanticContext {
+    readonly tagName: string;
+    readonly tagDefinition: FormSpecSerializedTagDefinition | null;
+    readonly placement: FormSpecPlacement | null;
+    readonly supportedTargets: readonly FormSpecTargetKind[];
+    readonly targetCompletions: readonly string[];
+    readonly compatiblePathTargets: readonly string[];
+    readonly valueLabels: readonly string[];
+    readonly signatures: readonly FormSpecSerializedTagSignature[];
+    readonly tagHoverMarkdown: string | null;
+    readonly targetHoverMarkdown: string | null;
+    readonly argumentHoverMarkdown: string | null;
+}
+
+/**
+ * Serializable overload/signature summary for one comment tag form.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagSignature {
+    readonly label: string;
+    readonly placements: readonly FormSpecPlacement[];
+}
+
+/** @public */
+declare type FormSpecTargetKind = "none" | "path" | "member" | "variant";
+
+/**
+ * Returns the full set of tag-name completions currently known to FormSpec.
+ *
+ * @public
+ */
+export declare function getCompletionItems(extensions?: readonly ExtensionDefinition[]): CompletionItem[];
+
+/**
+ * Returns completion items for the cursor position at `offset` in `documentText`.
+ *
+ * When `semanticContext` is supplied (e.g. from {@link getPluginCompletionContextForDocument}),
+ * it is used directly to produce target-value or tag-name completions. Pass `null` or omit it
+ * to fall back to syntax-only analysis, which works without the TypeScript plugin.
+ *
+ * @public
+ */
+export declare function getCompletionItemsAtOffset(documentText: string, offset: number, extensions?: readonly ExtensionDefinition[], semanticContext?: FormSpecSerializedCompletionContext | null): CompletionItem[];
+
+/**
+ * Returns the definition location for a symbol at the given position.
+ *
+ * Always returns `null` in this stub implementation.
+ *
+ * @returns `null` — not yet implemented
+ * @public
+ */
+export declare function getDefinition(): Location | null;
+
+/**
+ * Returns LSP hover content for the cursor position at `offset` in `documentText`.
+ *
+ * When `semanticHover` is supplied (e.g. from {@link getPluginHoverForDocument}), it is used
+ * directly as the hover source. Pass `null` or omit it to fall back to syntax-only analysis,
+ * which works without the TypeScript plugin. Returns `null` when the cursor is not over a
+ * recognised FormSpec tag.
+ *
+ * @public
+ */
+export declare function getHoverAtOffset(documentText: string, offset: number, extensions?: readonly ExtensionDefinition[], semanticHover?: FormSpecSerializedHoverInfo | null): Hover | null;
+
+/**
+ * Returns hover content for a single FormSpec tag name.
+ *
+ * @public
+ */
+export declare function getHoverForTag(tagName: string, extensions?: readonly ExtensionDefinition[]): Hover | null;
+
+/**
+ * Queries the FormSpec TypeScript plugin for semantic completion context at `offset` in the
+ * document identified by `filePath`.
+ *
+ * The workspace root containing `filePath` is located automatically from `workspaceRoots`. The
+ * plugin manifest is read from disk on each call. Returns `null` when no matching workspace root
+ * is found, the manifest is missing or invalid, the IPC socket is unavailable, the plugin times
+ * out (default 2 s), or the plugin's response was computed against a different version of the
+ * document than `documentText` (stale response guard).
+ *
+ * Pass the result to {@link getCompletionItemsAtOffset} as `semanticContext`.
+ *
+ * @public
+ */
+export declare function getPluginCompletionContextForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedCompletionContext | null>;
+
+/**
+ * Retrieves canonical FormSpec diagnostics for the current document revision
+ * from the plugin transport. Returns `null` when the transport is missing,
+ * stale, or invalid.
+ *
+ * @public
+ */
+export declare function getPluginDiagnosticsForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, timeoutMs?: number): Promise<readonly FormSpecAnalysisDiagnostic[] | null>;
+
+/**
+ * Queries the FormSpec TypeScript plugin for semantic hover information at `offset` in the
+ * document identified by `filePath`.
+ *
+ * The workspace root containing `filePath` is located automatically from `workspaceRoots`. The
+ * plugin manifest is read from disk on each call. Returns `null` when no matching workspace root
+ * is found, the manifest is missing or invalid, the IPC socket is unavailable, the plugin times
+ * out (default 2 s), or the plugin's response was computed against a different version of the
+ * document than `documentText` (stale response guard).
+ *
+ * Pass the result to {@link getHoverAtOffset} as `semanticHover`.
+ *
+ * @public
+ */
+export declare function getPluginHoverForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedHoverInfo | null>;
+
+/**
+ * Converts canonical FormSpec diagnostics into LSP diagnostics.
+ *
+ * Downstream consumers that want complete white-label control can ignore this
+ * helper and render their own messages from `code` + `data`.
+ *
+ * @public
+ */
+export declare function toLspDiagnostics(document: TextDocument, diagnostics: readonly FormSpecAnalysisDiagnostic[], options?: ToLspDiagnosticsOptions): Diagnostic[];
+
+/**
+ * Options for converting canonical FormSpec diagnostics into LSP diagnostics.
+ *
+ * @public
+ */
+export declare interface ToLspDiagnosticsOptions {
+    /** Source label shown by LSP clients. Defaults to `formspec`. */
+    readonly source?: string;
+}
+
+export { }