Merge pull request #185 from mkslanc/manual-session-control

Manual session control

Author: mkslanc

README.md

@@ -16,7 +16,7 @@ let worker = new Worker(new URL('./webworker.js', import.meta.url));
 
 // Create an Ace editor
 let editor = ace.edit("container", {
-    mode: new TypescriptMode() // Set the mode of the editor to Typescript
+  mode: new TypescriptMode() // Set the mode of the editor to Typescript
 });
 
 // Create a language provider for web worker (
@@ -28,6 +28,41 @@ languageProvider.registerEditor(editor);
 
 [Example webworker.js with all services](https://github.com/mkslanc/ace-linters/blob/main/packages/demo/webworker-lsp/webworker.ts)
 
+## New features in 1.8.1
+- add `manualSessionControl` provider option to disable automatic session registration. When enabled, you must manually handle session changes:
+```javascript
+// Create provider with manual session control
+let languageProvider = LanguageProvider.create(worker, {
+  manualSessionControl: true
+});
+
+// Register sessions manually
+languageProvider.registerSession(editor.session, editor, {
+  filePath: 'path/to/file.ts',
+  joinWorkspaceURI: true
+});
+
+// Handle session changes manually
+editor.on("changeSession", ({session}) => {
+  languageProvider.registerSession(session, editor, session.lspConfig);
+});
+```
+- add `setSessionLspConfig` method to set LSP configuration on Ace sessions:
+```javascript
+// Set LSP configuration on session
+languageProvider.setSessionLspConfig(editor.session, {
+    filePath: 'src/components/MyComponent.tsx',
+    joinWorkspaceURI: true
+});
+```
+- add `setDocumentOptions` method to replace deprecated `setSessionOptions`:
+```javascript
+// Configure document-specific options (replaces setSessionOptions)
+languageProvider.setDocumentOptions(editor.session, {
+    // service-specific options here
+});
+```
+
 ## New Features in 1.2.0
 - add `setProviderOptions` method to `LanguageProvider` to set options for client.
 - add experimental semantic tokens support (turned off by default). To turn on semantic tokens, set `semanticTokens` to
@@ -142,15 +177,15 @@ import {AceLanguageClient} from "ace-linters/build/ace-language-client";
 // Create a web worker
 let worker = new Worker(new URL('./webworker.js', import.meta.url));
 const serverData = {
-    module: () => import("ace-linters/build/language-client"),
-    modes: "json",
-    type: "webworker",
-    worker: worker,
+  module: () => import("ace-linters/build/language-client"),
+  modes: "json",
+  type: "webworker",
+  worker: worker,
 }
 
 // Create an Ace editor
 let editor = ace.edit("container", {
-    mode: new TypescriptMode() // Set the mode of the editor to Typescript
+  mode: new TypescriptMode() // Set the mode of the editor to Typescript
 });
 
 // Create a language provider for web worker
@@ -166,35 +201,13 @@ languageProvider.registerEditor(editor);
 **[!]** You need to describe server similar to that example:
 [Example server](https://github.com/mkslanc/ace-linters/blob/main/packages/demo/webworker-json-rpc/webworker.ts)
 
-## Supported LSP Capabilities
-
-- **Text Document Synchronization** (incremental changes)
-- **Diagnostics**
-  - Related document support
-  - Diagnostic tags (Unnecessary, Deprecated)
-  - Related diagnostic information support
-- **Hover**
-  - Markdown and plaintext content formats
-- **Formatting**
-- **Completions**
-  - Snippet support
-  - Documentation formats (Markdown, plaintext)
-- **Signature Help**
-  - Documentation formats (Markdown, plaintext)
-  - Active parameter highlighting support
-- **Document Highlight**
-- **Semantic Tokens**
-  - Relative format tokens
-  - Range requests supported
-  - Augments syntax tokens
-- **Code Actions**
-- **Inline Completions**
-- **Workspace Capabilities**
-  - Configuration change notifications
-  - Command execution
-  - Workspace edits (`applyEdit` supported)
-- **Window Capabilities**
-  - `showDocument` request support
+## Supported LSP capabilities:
+- Text Document Synchronization (with incremental changes)
+- Hover
+- Diagnostics
+- Formatting
+- Completions
+- Signature Help
 
 [Full list of capabilities](https://github.com/mkslanc/ace-linters/wiki/Client-LSP-capabilities)
 
@@ -209,15 +222,10 @@ Ace linters supports the following languages by default with webworkers approach
 - YAML *powered by* [Yaml Language Server](https://github.com/redhat-developer/yaml-language-server)
 - XML *powered by* [XML-Tools](https://github.com/SAP/xml-tools)
 - Javascript, JSX *powered by* [Eslint](https://github.com/eslint/eslint)
+- Python *powered by* [Ruff](https://github.com/charliermarsh/ruff)
 
 ## Supported languages via extensions
 - MySQL, FlinkSQL, SparkSQL, HiveSQL, TrinoSQL, PostgreSQL, Impala SQL, PL/SQL *with* [ace-sql-linter](https://www.npmjs.com/package/ace-sql-linter)
-- Clang *with* [ace-clang-linter](https://www.npmjs.com/package/ace-clang-linter)
-- Dart *with* [ace-dart-linter](https://www.npmjs.com/package/ace-dart-linter)
-- Go *with* [ace-go-linter](https://www.npmjs.com/package/ace-go-linter)
-- Lua *with* [ace-lua-linter](https://www.npmjs.com/package/ace-lua-linter)
-- Python *with* [ace-python-linter](https://www.npmjs.com/package/ace-python-linter)
-- Zig *with* [ace-zig-linter](https://www.npmjs.com/package/ace-zig-linter)
 
 ## Installation
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ace-linters-root",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "scripts": {
     "build:parts": "npm run build -ws",
     "build": "npm run build:parts && webpack",

packages/ace-linters/README.md

@@ -28,6 +28,41 @@ languageProvider.registerEditor(editor);
 
 [Example webworker.js with all services](https://github.com/mkslanc/ace-linters/blob/main/packages/demo/webworker-lsp/webworker.ts)
 
+## New features in 1.8.1
+- add `manualSessionControl` provider option to disable automatic session registration. When enabled, you must manually handle session changes:
+```javascript
+// Create provider with manual session control
+let languageProvider = LanguageProvider.create(worker, {
+  manualSessionControl: true
+});
+
+// Register sessions manually
+languageProvider.registerSession(editor.session, editor, {
+  filePath: 'path/to/file.ts',
+  joinWorkspaceURI: true
+});
+
+// Handle session changes manually
+editor.on("changeSession", ({session}) => {
+  languageProvider.registerSession(session, editor, session.lspConfig);
+});
+```
+- add `setSessionLspConfig` method to set LSP configuration on Ace sessions:
+```javascript
+// Set LSP configuration on session
+languageProvider.setSessionLspConfig(editor.session, {
+    filePath: 'src/components/MyComponent.tsx',
+    joinWorkspaceURI: true
+});
+```
+- add `setDocumentOptions` method to replace deprecated `setSessionOptions`:
+```javascript
+// Configure document-specific options (replaces setSessionOptions)
+languageProvider.setDocumentOptions(editor.session, {
+    // service-specific options here
+});
+```
+
 ## New Features in 1.2.0
 - add `setProviderOptions` method to `LanguageProvider` to set options for client.
 - add experimental semantic tokens support (turned off by default). To turn on semantic tokens, set `semanticTokens` to

packages/ace-linters/src/language-provider.ts

@@ -23,7 +23,7 @@ import {
     ProviderOptions,
     ServiceFeatures,
     ServiceOptions,
-    ServiceOptionsMap, ServiceStruct, SessionInitialConfig,
+    ServiceOptionsMap, ServiceStruct, SessionLspConfig,
     SupportedServices,
     Tooltip
 } from "./types/language-service";
@@ -169,11 +169,20 @@ export class LanguageProvider {
      * @param session The Ace edit session to update with the file path.
      * @param config config to set
      */
-    setSessionFilePath(session: Ace.EditSession, config: SessionInitialConfig) {
+    setSessionFilePath(session: Ace.EditSession, config: SessionLspConfig) {
         this.$getSessionLanguageProvider(session)?.setFilePath(config.filePath, config.joinWorkspaceURI);
     }
 
-    private $registerSession = (session: Ace.EditSession, editor: Ace.Editor, config?: SessionInitialConfig) => {
+    /**
+     * Registers a new editing session with the editor and associates it with a language provider.
+     * If a language provider for the specified editing session does not already exist, it initializes
+     * and stores a new session-specific language provider.
+     *
+     * @param session - The Ace EditSession object to be registered, representing a specific editing session.
+     * @param editor - The Ace Editor instance associated with the editing session.
+     * @param [config] - An optional configuration object for initializing the session.
+     */
+    registerSession = (session: Ace.EditSession, editor: Ace.Editor, config?: SessionLspConfig) => {
         if (!this.$sessionLanguageProviders[session["id"]]) {
             this.$sessionLanguageProviders[session["id"]] = new SessionLanguageProvider(this, session, editor, this.$messageController, config);
         }
@@ -182,6 +191,18 @@ export class LanguageProvider {
         }
     }
 
+    /**
+     * Sets the Language Server Protocol (LSP) configuration for the given session.
+     *
+     * @param session - The editor session to which the LSP configuration will be applied.
+     * @param config - The LSP configuration to set for the session.
+     * @return The updated editor session with the applied LSP configuration.
+     */
+    setSessionLspConfig(session: Ace.EditSession, config: SessionLspConfig) {
+        session.lspConfig = config;
+        return session;
+    }
+
     private $getSessionLanguageProvider(session: Ace.EditSession): SessionLanguageProvider {
         return this.$sessionLanguageProviders[session["id"]];
     }
@@ -197,12 +218,14 @@ export class LanguageProvider {
      * @param editor - The Ace editor instance to be registered.
      * @param [config] - Configuration options for the session.
      */
-    registerEditor(editor: Ace.Editor, config?: SessionInitialConfig) {
+    registerEditor(editor: Ace.Editor, config?: SessionLspConfig) {
         if (!this.editors.includes(editor))
             this.$registerEditor(editor);
-        this.$registerSession(editor.session, editor, config);
+        config = config ?? editor.session.lspConfig;
+        this.registerSession(editor.session, editor, config);
     }
 
+
     codeActionCallback: (codeActions: CodeActionsByService[]) => void;
 
     /**
@@ -278,7 +301,11 @@ export class LanguageProvider {
         AceEditor.getConstructor(editor);
 
         editor.setOption("useWorker", false);
-        editor.on("changeSession", ({session}) => this.$registerSession(session, editor));
+
+
+        if (!this.options.manualSessionControl) {
+            editor.on("changeSession", ({session}) => this.registerSession(session, editor, session.lspConfig));
+        }
 
         if (this.options.functionality!.completion || this.options.functionality!.inlineCompletion) {
             this.$registerCompleters(editor);
@@ -405,11 +432,19 @@ export class LanguageProvider {
     }
 
     /**
-     * Sets global options for the specified service.
+     * Configures global options that apply to all documents handled by the specified language service.
+     *
+     * Global options serve as default settings for all documents processed by a service when no
+     * document-specific options are provided. These options affect language service behavior across
+     * the entire workspace, including validation rules, formatting preferences, completion settings,
+     * and service-specific configurations.
      *
-     * @param serviceName - The name of the service for which to set global options.
-     * @param options - The options to set for the specified service.
-     * @param {boolean} [merge=false] - Indicates whether to merge the provided options with the existing options. Defaults to false.
+     * @param serviceName - The identifier of the language service to configure. Must be a valid
+     *                      service name from the supported services (e.g., 'typescript', 'json', 'html').
+     * @param options - The global configuration options specific to the language service. The structure
+     *                  varies by service type.
+     * @param {boolean} [merge=false] - Indicates whether to merge the provided options with the existing options.
+     *                  Defaults to false.
      */
     setGlobalOptions<T extends keyof ServiceOptionsMap>(serviceName: T & string, options: ServiceOptionsMap[T], merge = false) {
         this.$messageController.setGlobalOptions(serviceName, options, merge);
@@ -437,12 +472,25 @@ export class LanguageProvider {
      *
      * @param session - The Ace editor session to configure.
      * @param options - The configuration options to be applied to the session.
+     * @deprecated Use `setDocumentOptions` instead. This method will be removed in the future.
      */
     setSessionOptions<OptionsType extends ServiceOptions>(session: Ace.EditSession, options: OptionsType) {
         let sessionLanguageProvider = this.$getSessionLanguageProvider(session);
         sessionLanguageProvider.setOptions(options);
     }
 
+    /**
+     * Sets configuration options for a document associated with the specified editor session.
+     *
+     * @param session - The Ace editor session representing the document to configure.
+     * @param options - The service options to apply. The exact shape depends on the language services
+     *                  active for this session (e.g. JSON schema settings).
+     */
+    setDocumentOptions<OptionsType extends ServiceOptions>(session: Ace.EditSession, options: OptionsType) {
+        let sessionLanguageProvider = this.$getSessionLanguageProvider(session);
+        sessionLanguageProvider.setOptions(options);
+    }
+
     /**
      * Configures the specified features for a given service.
      *

packages/ace-linters/src/services/language-client.ts

@@ -205,6 +205,10 @@ export class LanguageClient extends BaseService implements LanguageService {
     }
 
     addDocument(document: lsp.TextDocumentItem) {//TODO: this need to be async to avoid race condition
+        if (this.getDocument(document.uri)) {
+            console.warn(document.uri + ' already exists');
+            return;
+        }
         super.addDocument(document);
         const textDocumentMessage: lsp.DidOpenTextDocumentParams = {
             textDocument: document

packages/ace-linters/src/session-language-provider.ts

@@ -1,6 +1,6 @@
 import {Ace} from "ace-code";
 import {ComboDocumentIdentifier, IMessageController} from "./types/message-controller-interface";
-import {AceRangeData, ServiceOptions, SessionInitialConfig} from "./types/language-service";
+import {AceRangeData, ServiceOptions, SessionLspConfig} from "./types/language-service";
 import {MarkerGroup} from "./ace/marker_group";
 import type {LanguageProvider} from "./language-provider";
 import * as lsp from "vscode-languageserver-protocol";
@@ -53,7 +53,7 @@ export class SessionLanguageProvider {
      * @param messageController - The `IMessageController` instance for handling messages.
      * @param config
      */
-    constructor(provider: LanguageProvider, session: Ace.EditSession, editor: Ace.Editor, messageController: IMessageController, config?: SessionInitialConfig) {
+    constructor(provider: LanguageProvider, session: Ace.EditSession, editor: Ace.Editor, messageController: IMessageController, config?: SessionLspConfig) {
         this.$provider = provider;
         this.$messageController = messageController;
         this.session = session;
@@ -90,19 +90,24 @@ export class SessionLanguageProvider {
      * Increments the document version and updates the internal document URI and identifier.
      *
      * @param {string} filePath - The new file path for the document.
-     * @param {boolean} [joinWorkspaceURI] - Optional flag to indicate whether to join the file path with the workspace URI.
+     * @param {boolean} [joinWorkspaceURI] - when true the given path is treated as relative and will be joined with
+     * the workspace’s root URI to form the final canonical URI. When false (or omitted) filePath is just transformed to
+     * URI.
      */
     setFilePath(filePath: string, joinWorkspaceURI?: boolean) {
         this.enqueueIfNotConnected(() => {
             this.session.doc.version++;
             this.$filePath = filePath;
             const previousComboId = this.comboDocumentIdentifier;
             this.initDocumentUri(true, joinWorkspaceURI);
+            if (previousComboId.documentUri === this.comboDocumentIdentifier.documentUri) { //no need to rename
+                return;
+            }
             this.$messageController.renameDocument(previousComboId, this.comboDocumentIdentifier.documentUri, this.session.doc.version);
         })
     };
 
-    private $init(config?: SessionInitialConfig) {
+    private $init(config?: SessionLspConfig) {
         if (config?.filePath) {
             this.$filePath = config.filePath;
         }

packages/ace-linters/src/types/ace-extension.ts

@@ -1,16 +1,20 @@
-import { DecodedSemanticTokens } from "../type-converters/lsp/semantic-tokens";
+import {DecodedSemanticTokens} from "../type-converters/lsp/semantic-tokens";
+import {SessionLspConfig} from "./language-service";
 
 declare module "ace-code/src/edit_session" {
 
     interface EditSession {
         setSemanticTokens: (tokens: DecodedSemanticTokens | undefined) => void;
+        lspConfig?: SessionLspConfig
     }
 }
 
 declare module "ace-code/src/background_tokenizer" {
     interface BackgroundTokenizer {
         semanticTokens: DecodedSemanticTokens | undefined;
+
         $tokenizeRow(row: number): import("ace-code").Ace.Token[];
+
         $worker: () => void;
         $updateOnChange: () => void;
     }