Language Features

/**
 * Main middleware interface combining all LSP feature middlewares
 */
interface Middleware {
  /** Completion feature middleware */
  completion?: CompletionMiddleware;
  /** Hover feature middleware */
  hover?: HoverMiddleware;
  /** Signature help feature middleware */
  signatureHelp?: SignatureHelpMiddleware;
  /** Go to definition feature middleware */
  definition?: DefinitionMiddleware;
  /** Find references feature middleware */
  references?: ReferencesMiddleware;
  /** Document highlight feature middleware */
  documentHighlight?: DocumentHighlightMiddleware;
  /** Document symbol feature middleware */
  documentSymbol?: DocumentSymbolMiddleware;
  /** Code action feature middleware */
  codeAction?: CodeActionMiddleware;
  /** Code lens feature middleware */
  codeLens?: CodeLensMiddleware;
  /** Document formatting feature middleware */
  formatting?: FormattingMiddleware;
  /** Rename feature middleware */
  rename?: RenameMiddleware;
  /** Document link feature middleware */
  documentLink?: DocumentLinkMiddleware;
  /** Execute command feature middleware */
  executeCommand?: ExecuteCommandMiddleware;
  /** Workspace symbol feature middleware */
  workspaceSymbol?: WorkspaceSymbolMiddleware;
  /** Text document synchronization middleware */
  textDocumentSync?: TextDocumentSynchronizationMiddleware;
  /** Configuration feature middleware */
  configuration?: ConfigurationMiddleware;
  /** Workspace folder feature middleware */
  workspaceFolder?: WorkspaceFolderMiddleware;
  /** Diagnostic feature middleware */
  diagnostic?: DiagnosticProviderMiddleware;
  /** Semantic tokens feature middleware */
  semanticTokens?: SemanticTokensMiddleware;
  /** Call hierarchy feature middleware */
  callHierarchy?: CallHierarchyMiddleware;
  /** Type hierarchy feature middleware */
  typeHierarchy?: TypeHierarchyMiddleware;
  /** Inlay hints feature middleware */
  inlayHints?: InlayHintsMiddleware;
  /** Inline values feature middleware */
  inlineValue?: InlineValueMiddleware;
  /** Folding range feature middleware */
  foldingRange?: FoldingRangeProviderMiddleware;
  /** Linked editing range feature middleware */
  linkedEditingRange?: LinkedEditingRangeMiddleware;
  /** Selection range feature middleware */
  selectionRange?: SelectionRangeProviderMiddleware;
  /** Document color feature middleware */
  colorProvider?: ColorProviderMiddleware;
  /** Declaration feature middleware */
  declaration?: DeclarationMiddleware;
  /** Implementation feature middleware */
  implementation?: ImplementationMiddleware;
  /** Type definition feature middleware */
  typeDefinition?: TypeDefinitionMiddleware;
  /** File operations feature middleware */
  fileOperations?: FileOperationsMiddleware;
  /** Notebook document feature middleware */
  notebookDocument?: NotebookDocumentMiddleware;
}

/**
 * Middleware for completion features
 */
interface CompletionMiddleware {
  /** Customize completion item provision */
  provideCompletionItem?: ProvideCompletionItemsSignature;
  /** Customize completion item resolution */
  resolveCompletionItem?: ResolveCompletionItemSignature;
}

/**
 * Signature for providing completion items
 */
type ProvideCompletionItemsSignature = (
  document: TextDocument,
  position: Position,
  context: CompletionContext,
  token: CancellationToken,
  next: ProvideCompletionItemsSignature
) => ProviderResult<CompletionItem[] | CompletionList>;

/**
 * Signature for resolving completion items
 */
type ResolveCompletionItemSignature = (
  item: CompletionItem,
  token: CancellationToken,
  next: ResolveCompletionItemSignature
) => ProviderResult<CompletionItem>;

/**
 * Middleware for hover features
 */
interface HoverMiddleware {
  /** Customize hover information provision */
  provideHover?: ProvideHoverSignature;
}

/**
 * Signature for providing hover information
 */
type ProvideHoverSignature = (
  document: TextDocument,
  position: Position,
  token: CancellationToken,
  next: ProvideHoverSignature
) => ProviderResult<Hover>;

/**
 * Middleware for signature help features
 */
interface SignatureHelpMiddleware {
  /** Customize signature help provision */
  provideSignatureHelp?: ProvideSignatureHelpSignature;
}

/**
 * Signature for providing signature help
 */
type ProvideSignatureHelpSignature = (
  document: TextDocument,
  position: Position,
  context: SignatureHelpContext,
  token: CancellationToken,
  next: ProvideSignatureHelpSignature
) => ProviderResult<SignatureHelp>;

/**
 * Middleware for definition features
 */
interface DefinitionMiddleware {
  /** Customize definition provision */
  provideDefinition?: ProvideDefinitionSignature;
}

/**
 * Signature for providing definitions
 */
type ProvideDefinitionSignature = (
  document: TextDocument,
  position: Position,
  token: CancellationToken,
  next: ProvideDefinitionSignature
) => ProviderResult<Definition | DefinitionLink[]>;

/**
 * Middleware for references features
 */
interface ReferencesMiddleware {
  /** Customize references provision */
  provideReferences?: ProvideReferencesSignature;
}

/**
 * Signature for providing references
 */
type ProvideReferencesSignature = (
  document: TextDocument,
  position: Position,
  context: ReferenceContext,
  token: CancellationToken,
  next: ProvideReferencesSignature
) => ProviderResult<Location[]>;

/**
 * Middleware for document highlight features
 */
interface DocumentHighlightMiddleware {
  /** Customize document highlights provision */
  provideDocumentHighlights?: ProvideDocumentHighlightsSignature;
}

/**
 * Signature for providing document highlights
 */
type ProvideDocumentHighlightsSignature = (
  document: TextDocument,
  position: Position,
  token: CancellationToken,
  next: ProvideDocumentHighlightsSignature
) => ProviderResult<DocumentHighlight[]>;

/**
 * Middleware for code action features
 */
interface CodeActionMiddleware {
  /** Customize code actions provision */
  provideCodeActions?: ProvideCodeActionsSignature;
  /** Customize code action resolution */
  resolveCodeAction?: ResolveCodeActionSignature;
}

/**
 * Signature for providing code actions
 */
type ProvideCodeActionsSignature = (
  document: TextDocument,
  range: Range,
  context: CodeActionContext,
  token: CancellationToken,
  next: ProvideCodeActionsSignature
) => ProviderResult<(Command | CodeAction)[]>;

/**
 * Signature for resolving code actions
 */
type ResolveCodeActionSignature = (
  item: CodeAction,
  token: CancellationToken,
  next: ResolveCodeActionSignature
) => ProviderResult<CodeAction>;

/**
 * Middleware for rename features
 */
interface RenameMiddleware {
  /** Customize rename preparation */
  prepareRename?: PrepareRenameSignature;
  /** Customize rename edits provision */
  provideRenameEdits?: ProvideRenameEditsSignature;
}

/**
 * Signature for preparing rename
 */
type PrepareRenameSignature = (
  document: TextDocument,
  position: Position,
  token: CancellationToken,
  next: PrepareRenameSignature
) => ProviderResult<Range | { range: Range; placeholder: string }>;

/**
 * Signature for providing rename edits
 */
type ProvideRenameEditsSignature = (
  document: TextDocument,
  position: Position,
  newName: string,
  token: CancellationToken,
  next: ProvideRenameEditsSignature
) => ProviderResult<WorkspaceEdit>;

/**
 * Middleware for document symbol features
 */
interface DocumentSymbolMiddleware {
  /** Customize document symbols provision */
  provideDocumentSymbols?: ProvideDocumentSymbolsSignature;
}

/**
 * Signature for providing document symbols
 */
type ProvideDocumentSymbolsSignature = (
  document: TextDocument,
  token: CancellationToken,
  next: ProvideDocumentSymbolsSignature
) => ProviderResult<SymbolInformation[] | DocumentSymbol[]>;

/**
 * Middleware for formatting features
 */
interface FormattingMiddleware {
  /** Customize document formatting */
  provideDocumentFormattingEdits?: ProvideDocumentFormattingEditsSignature;
  /** Customize range formatting */
  provideDocumentRangeFormattingEdits?: ProvideDocumentRangeFormattingEditsSignature;
  /** Customize on-type formatting */
  provideOnTypeFormattingEdits?: ProvideOnTypeFormattingEditsSignature;
}

/**
 * Signature for providing document formatting edits
 */
type ProvideDocumentFormattingEditsSignature = (
  document: TextDocument,
  options: FormattingOptions,
  token: CancellationToken,
  next: ProvideDocumentFormattingEditsSignature
) => ProviderResult<TextEdit[]>;

/**
 * Signature for providing range formatting edits
 */
type ProvideDocumentRangeFormattingEditsSignature = (
  document: TextDocument,
  range: Range,
  options: FormattingOptions,
  token: CancellationToken,
  next: ProvideDocumentRangeFormattingEditsSignature
) => ProviderResult<TextEdit[]>;

/**
 * Signature for providing on-type formatting edits
 */
type ProvideOnTypeFormattingEditsSignature = (
  document: TextDocument,
  position: Position,
  ch: string,
  options: FormattingOptions,
  token: CancellationToken,
  next: ProvideOnTypeFormattingEditsSignature
) => ProviderResult<TextEdit[]>;

/**
 * Middleware for diagnostic features
 */
interface DiagnosticProviderMiddleware {
  /** Customize diagnostic provision */
  provideDiagnostics?: ProvideDiagnosticSignature;
  /** Customize workspace diagnostic provision */
  provideWorkspaceDiagnostics?: ProvideWorkspaceDiagnosticSignature;
}

/**
 * Signature for providing diagnostics
 */
type ProvideDiagnosticSignature = (
  document: TextDocument | Uri,
  previousResultId: string | undefined,
  token: CancellationToken,
  next: ProvideDiagnosticSignature
) => ProviderResult<DocumentDiagnosticReport>;

/**
 * Signature for providing workspace diagnostics
 */
type ProvideWorkspaceDiagnosticSignature = (
  resultIds: PreviousResultId[],
  token: CancellationToken,
  resultReporter: ResultReporter,
  next: ProvideWorkspaceDiagnosticSignature
) => ProviderResult<WorkspaceDiagnosticReport>;

/**
 * Diagnostic pull mode configuration
 */
enum DiagnosticPullMode {
  /** Pull diagnostics on open, change, save, and close events */
  onType = 'onType',
  /** Pull diagnostics only on save events */
  onSave = 'onSave'
}

/**
 * Options for diagnostic pull configuration
 */
type DiagnosticPullOptions = {
  /** Whether to pull diagnostics on open */
  onOpen?: boolean;
  /** Whether to pull diagnostics on change */
  onChange?: boolean;
  /** Whether to pull diagnostics on save */  
  onSave?: boolean;
  /** Whether to pull diagnostics on close */
  onClose?: boolean;
  /** Pull mode configuration */
  mode?: DiagnosticPullMode;
};

/**
 * Provider shape for diagnostic features
 */
type DiagnosticProviderShape = {
  /** Provide document diagnostics */
  provideDiagnostics: ProvideDiagnosticSignature;
  /** Provide workspace diagnostics */
  provideWorkspaceDiagnostics?: ProvideWorkspaceDiagnosticSignature;
};

/**
 * Provider shape for code lens features
 */
type CodeLensProviderShape = {
  /** Provide code lenses for a document */
  provideCodeLenses: ProvideCodeLensesSignature;
  /** Resolve a code lens with additional information */
  resolveCodeLens?: ResolveCodeLensSignature;
};

/**
 * Provider shape for semantic tokens features
 */
type SemanticTokensProviderShape = {
  /** Provide semantic tokens for entire document */
  provideDocumentSemanticTokens: DocumentSemanticsTokensSignature;
  /** Provide semantic token edits */
  provideDocumentSemanticTokensEdits?: DocumentSemanticsTokensEditsSignature;
  /** Provide semantic tokens for document range */
  provideDocumentRangeSemanticTokens?: DocumentRangeSemanticTokensSignature;
};

/**
 * Provider shape for inlay hints features
 */
type InlayHintsProviderShape = {
  /** Provide inlay hints for a document range */
  provideInlayHints: ProvideInlayHintsSignature;
  /** Resolve an inlay hint with additional information */
  resolveInlayHint?: ResolveInlayHintSignature;
};

/**
 * Provider shape for inline values features  
 */
type InlineValueProviderShape = {
  /** Provide inline values for a document range */
  provideInlineValues: ProvideInlineValuesSignature;
};

/**
 * Middleware for semantic tokens features
 */
interface SemanticTokensMiddleware {
  /** Customize document semantic tokens provision */
  provideDocumentSemanticTokens?: DocumentSemanticsTokensSignature;
  /** Customize document semantic tokens edits provision */
  provideDocumentSemanticTokensEdits?: DocumentSemanticsTokensEditsSignature;
  /** Customize range semantic tokens provision */
  provideDocumentRangeSemanticTokens?: DocumentRangeSemanticTokensSignature;
}

/**
 * Signature for providing document semantic tokens
 */
type DocumentSemanticsTokensSignature = (
  document: TextDocument,
  token: CancellationToken,
  next: DocumentSemanticsTokensSignature
) => ProviderResult<SemanticTokens>;

/**
 * Signature for providing document semantic tokens edits
 */
type DocumentSemanticsTokensEditsSignature = (
  document: TextDocument,
  previousResultId: string,
  token: CancellationToken,
  next: DocumentSemanticsTokensEditsSignature
) => ProviderResult<SemanticTokensEdits | SemanticTokens>;

/**
 * Signature for providing range semantic tokens
 */
type DocumentRangeSemanticTokensSignature = (
  document: TextDocument,
  range: Range,
  token: CancellationToken,
  next: DocumentRangeSemanticTokensSignature
) => ProviderResult<SemanticTokens>;

/**
 * Middleware for text document synchronization
 */
interface TextDocumentSynchronizationMiddleware {
  /** Customize document open handling */
  didOpen?: NextSignature<TextDocument, Promise<void>>;
  /** Customize document change handling */
  didChange?: NextSignature<TextDocumentChangeEvent, Promise<void>>;
  /** Customize document will save handling */
  willSave?: NextSignature<TextDocumentWillSaveEvent, Promise<void>>;
  /** Customize document will save wait until handling */
  willSaveWaitUntil?: NextSignature<TextDocumentWillSaveEvent, Thenable<TextEdit[]>>;
  /** Customize document save handling */
  didSave?: NextSignature<TextDocument, Promise<void>>;
  /** Customize document close handling */
  didClose?: NextSignature<TextDocument, Promise<void>>;
}

/**
 * Generic next signature for middleware chaining
 */
type NextSignature<P, R> = (data: P, next: (data: P) => R) => R;

/**
 * Middleware for notebook document features
 */
interface NotebookDocumentMiddleware {
  /** Customize notebook document synchronization */
  didOpen?: NextSignature<NotebookDocument, Promise<void>>;
  /** Customize notebook document change handling */
  didChange?: NextSignature<VNotebookDocumentChangeEvent, Promise<void>>;
  /** Customize notebook document save handling */
  didSave?: NextSignature<NotebookDocument, Promise<void>>;
  /** Customize notebook document close handling */
  didClose?: NextSignature<NotebookDocument, Promise<void>>;
}

/**
 * Configuration options for notebook document synchronization
 */
interface NotebookDocumentOptions {
  /** Notebook selector to match notebook types */
  notebookSelector: NotebookSelector[];
  /** Cell selector to match cell types within notebooks */
  cellSelector?: DocumentSelector;
  /** Whether to save the notebook document */
  save?: boolean;
}

/**
 * Event representing changes to a notebook document
 */
type VNotebookDocumentChangeEvent = {
  /** The notebook document that changed */
  notebook: NotebookDocument;
  /** Metadata changes */
  metadata?: { old: { [key: string]: any }; new: { [key: string]: any } };
  /** Cell changes */
  cells?: NotebookDocumentCellChange;
};

/**
 * Selector for matching notebook documents
 */
interface NotebookSelector {
  /** Notebook type pattern (e.g., 'jupyter-notebook') */
  notebook: string | { pattern: string };
  /** Language pattern for cells */
  language?: string | { pattern: string };
}

/**
 * Changes to notebook cells
 */
interface NotebookDocumentCellChange {
  /** Array of cell changes */
  structure?: {
    /** Cells that were added */
    array: NotebookDocumentCellChangeStructure;
    /** Whether cells were added or removed */
    didOpen?: NotebookCell[];
    didClose?: NotebookCell[];
  };
  /** Content changes to existing cells */
  data?: NotebookCell[];
  /** Text changes to cell content */
  textContent?: {
    document: TextDocument;
    changes: TextDocumentContentChangeEvent[];
  }[];
}

const clientOptions: LanguageClientOptions = {
  middleware: {
    completion: {
      provideCompletionItem: (document, position, context, token, next) => {
        // Add custom completion items
        const customItems: CompletionItem[] = [
          { label: 'custom-snippet', kind: CompletionItemKind.Snippet }
        ];
        
        // Call next to get server completions
        const serverItems = next(document, position, context, token);
        
        // Combine custom and server items
        return Promise.resolve(serverItems).then(items => {
          if (Array.isArray(items)) {
            return [...customItems, ...items];
          }
          return { isIncomplete: false, items: [...customItems, ...(items?.items || [])] };
        });
      }
    }
  }
};

const clientOptions: LanguageClientOptions = {
  middleware: {
    diagnostic: {
      provideDiagnostics: (document, previousResultId, token, next) => {
        // Custom diagnostic processing
        console.log(`Providing diagnostics for: ${document.uri}`);
        return next(document, previousResultId, token);
      }
    }
  }
};

const clientOptions: LanguageClientOptions = {
  middleware: {
    notebookDocument: {
      didOpen: (notebook, next) => {
        console.log(`Notebook opened: ${notebook.uri}`);
        return next(notebook);
      },
      didChange: (changeEvent, next) => {
        console.log(`Notebook changed: ${changeEvent.notebook.uri}`);
        return next(changeEvent);
      }
    }
  }
};