@hydranium/core 1.0.0-next.28 → 1.0.0-next.281

package/src/langium/workspace/hydranium-workspace-manager.ts

@@ -7,18 +7,29 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { Deferred, type Logger, type Tracer } from '@hydranium/protocol';
-import { DefaultWorkspaceManager, DocumentState, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
-import { type CancellationToken } from 'vscode-languageserver';
+import { Deferred, type Logger, type Tracer, describeError, describeErrorWithStack } from '@hydranium/protocol';
+import {
+   DefaultWorkspaceManager,
+   DocumentState,
+   interruptAndCheck,
+   isOperationCancelled,
+   type LangiumDocument,
+   type Stream,
+   UriUtils,
+   type URI
+} from '@hydranium/langium';
+import { type CancellationToken, CancellationTokenSource, type InitializeParams } from 'vscode-languageserver';
 import type { WorkspaceFolder } from 'vscode-languageserver-types';
 import { type LogNameOptions, resolveLogFilePlaceholder, toLogFileWorkspaceToken } from '../diagnostics/logger.js';
+import type { ServerLocale } from '../../locale/server-locale.js';
 import type { ProjectChangeEvent } from '../project/project-change-event.js';
 import type { ProjectManager } from '../project/project-manager.js';
 import type { ServerSharedServicesMinimal } from '../shared-services.js';
-import type { WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import type { WritableFileSystemProvider } from './file-system-provider.js';
 import { type DocumentUriPolicy, findRealpathDivergence } from './document-uri-policy.js';
 import { type AdditionalDocumentContribution, collectAdditionalDocuments } from './additional-document-contribution.js';
 import { onProcessEvent } from '../../util/environment.js';
+import { isConnectionGoneError } from '../../util/connection-liveness.js';
 
 /**
  * Module-level guard so repeated workspace-manager construction (e.g.
@@ -36,6 +47,13 @@ let operationCancelledSuppressionInstalled = false;
  */
 let operationCancelledSuppressionLogger: Logger | undefined;
 
+/**
+ * Never cancelled: `interruptAndCheck` yields only for a token other than
+ * `CancellationToken.None`, and the load must not stop part-way, since Langium
+ * checks for cancellation once every document exists.
+ */
+const LOAD_YIELD_TOKEN = new CancellationTokenSource().token;
+
 /**
  * Decide what to do with a process-level unhandled promise rejection.
  *
@@ -59,7 +77,7 @@ export function handleProcessUnhandledRejection(reason: unknown, logger: Logger)
    if (typeof reason === 'symbol' && String(reason) === 'Symbol(OperationCancelled)') {
       return;
    }
-   logger.error('Unhandled promise rejection: ' + (reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)));
+   logger.error('Unhandled promise rejection: ' + describeErrorWithStack(reason));
 }
 
 /**
@@ -92,6 +110,18 @@ export function installOperationCancelledSuppression(logger: Logger): void {
    });
 }
 
+/** Options for {@link HydraniumWorkspaceManager}. */
+export interface HydraniumWorkspaceManagerOptions extends LogNameOptions {
+   /**
+    * Whether startup warns about seeded documents the bound
+    * `FileSystemProvider` cannot serve (see
+    * {@link HydraniumWorkspaceManager.warnIfDocumentsUnserved}). Defaults to
+    * `true`; turn it off for a host that drops such documents at their last
+    * close on purpose.
+    */
+   warnUnservedDocuments?: boolean;
+}
+
 /**
  * Framework {@link DefaultWorkspaceManager} subclass that integrates the
  * project tier with Langium's workspace startup.
@@ -124,8 +154,8 @@ export function installOperationCancelledSuppression(logger: Logger): void {
  * URIs (its own members plus any transitive dependents per the
  * `getAffectedProjects` hook). This manager re-runs
  * `DocumentBuilder.resetToState(doc, DocumentState.Changed)` on each
- * affected document so the next build cycle re-links them with the new
- * visibility scope.
+ * affected document so the build of the update that changed the descriptor
+ * re-links them with the new visibility scope.
  *
  * Descriptor URIs that triggered the cycle are intentionally excluded
  * from the affected set by `AbstractProjectManager.onBuildUpdate` —
@@ -156,19 +186,29 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
    readonly workspaceInitialized: Promise<unknown> = this.workspaceInitializedDeferred.promise;
 
    protected readonly uriPolicy: DocumentUriPolicy;
+   /** Handed the client's locale at init; read by whoever renders in it. */
+   protected readonly serverLocale: ServerLocale;
    protected readonly writableFileSystemProvider: WritableFileSystemProvider;
    protected readonly additionalDocuments: Record<string, AdditionalDocumentContribution>;
    /** Registry consulted by {@link warnIfUnroutable} to check a seeded document routes. */
    protected readonly languageRegistry: ServerSharedServicesMinimal['ServiceRegistry'];
+   /** Whether startup runs {@link warnIfDocumentsUnserved}. */
+   protected readonly warnUnservedDocuments: boolean;
+   /** URIs of the documents the running startup's file traversal loaded; see {@link loadWorkspaceDocuments}. */
+   protected readonly traversedUris = new Set<string>();
+   /** How many documents {@link loadWorkspaceDocuments} reads and parses before it may yield; below 1 counts as 1. */
+   protected readonly loadChunkSize: number = 10;
 
-   constructor(services: ServerSharedServicesMinimal, options: LogNameOptions = {}) {
+   constructor(services: ServerSharedServicesMinimal, options: HydraniumWorkspaceManagerOptions = {}) {
       super(services);
       this.projectManager = services.workspace.ProjectManager;
       this.projectManager.onProjectsChanged(event => this.onProjectsChanged(event));
       this.uriPolicy = services.workspace.DocumentUriPolicy;
+      this.serverLocale = services.ServerLocale;
       this.writableFileSystemProvider = services.workspace.FileSystemProvider;
       this.additionalDocuments = services.additionalDocuments;
       this.languageRegistry = services.ServiceRegistry;
+      this.warnUnservedDocuments = options.warnUnservedDocuments ?? true;
       this.tracer = services.Tracer.for(options.logName ?? 'WorkspaceManager').trace('instantiated');
       installOperationCancelledSuppression(this.tracer);
    }
@@ -197,16 +237,16 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
       // seeded. `tags` is read at the done-emit, so the document count pushed
       // inside the callback appears in the log line.
       const tags: string[] = [`${contributions.length} contributions`];
-      let documentCount = 0;
+      const seeded: LangiumDocument[] = [];
       await this.tracer.time(
          'Load additional documents',
          async () => {
             await collectAdditionalDocuments(this.additionalDocuments, folders, document => {
-               documentCount++;
+               seeded.push(document);
                this.warnIfUnroutable(document);
                collector(document);
             });
-            tags.push(`${documentCount} documents`);
+            tags.push(`${seeded.length} documents`);
          },
          'info',
          { logAfterMs: 0, tags }
@@ -268,11 +308,136 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
             discovered.push(document);
          }
       }
-      const documents = await super.performStartup(folders);
+      this.traversedUris.clear();
+      let documents: LangiumDocument[];
+      try {
+         documents = await super.performStartup(folders);
+         if (this.warnUnservedDocuments) {
+            await this.warnIfDocumentsUnserved(documents.filter(document => !this.traversedUris.has(document.uri.toString())));
+         }
+      } finally {
+         this.traversedUris.clear();
+      }
       this.probePathDivergence(folders);
       return this.withDiscoveredDescriptors(documents, discovered);
    }
 
+   /**
+    * Load the documents the file traversal found through
+    * {@link loadTraversedDocument}, {@link loadChunkSize} at a time, yielding
+    * between chunks once Langium's interruption period has passed. Langium's
+    * own load starts every read at once and parses each as it returns: over a
+    * synchronous provider nothing else runs until the last file has parsed, and
+    * over the Node provider incoming messages wait through long runs of parses.
+    * The cost: at most a chunk of reads is in flight, and each chunk waits for
+    * its slowest read, so slow storage takes a round per chunk, not one burst.
+    *
+    * Each loaded document is recorded, so startup can tell them from the
+    * documents `loadAdditionalDocuments` seeded, through the
+    * `additionalDocuments` group or an override of its own.
+    *
+    * The traversal found each of its documents through the provider, so asking
+    * it again whether they exist costs one call per workspace file and cannot
+    * come out false. Telling them apart by scheme does not work either: the
+    * registry's host answers every scheme no other provider claims, a seeded
+    * scheme nobody serves included. An override that loads documents without
+    * delegating here leaves them unrecorded, so startup asks the provider
+    * about each of them.
+    */
+   protected override async loadWorkspaceDocuments(uris: Stream<URI>, collector: (document: LangiumDocument) => void): Promise<void> {
+      const pending = uris.toArray();
+      const chunkSize = Math.max(1, this.loadChunkSize);
+      for (let i = 0; i < pending.length; i += chunkSize) {
+         if (i > 0) {
+            await interruptAndCheck(LOAD_YIELD_TOKEN);
+         }
+         await Promise.all(
+            pending.slice(i, i + chunkSize).map(async uri => {
+               const document = await this.loadTraversedDocument(uri);
+               if (document) {
+                  this.traversedUris.add(document.uri.toString());
+                  collector(document);
+               }
+            })
+         );
+      }
+   }
+
+   /**
+    * Load one document the file traversal found, or answer `undefined` to
+    * leave it out of the workspace.
+    *
+    * A file whose read fails and that the provider's `existsSettled`, or
+    * `exists` for a provider without it, reports gone is left out with a debug
+    * line, since it went between the scan and the read. A file still there is
+    * read once more, since a replacing rename can hide its name for a moment;
+    * that read's failure, and cancellation, fail the startup. A check that
+    * throws counts the file as there, since it cannot say the file went. The
+    * skip is the startup's only: other callers of `getOrCreateDocument` still
+    * get the read error.
+    */
+   protected async loadTraversedDocument(uri: URI): Promise<LangiumDocument | undefined> {
+      try {
+         return await this.langiumDocuments.getOrCreateDocument(uri);
+      } catch (error: unknown) {
+         if (isOperationCancelled(error)) {
+            throw error;
+         }
+         const fileSystem = this.writableFileSystemProvider;
+         if (!(await (fileSystem.existsSettled?.(uri) ?? fileSystem.exists(uri)).catch(() => true))) {
+            this.tracer.debug(`Skipped ${uri.toString()}: it was removed between the workspace scan and its load`);
+            return undefined;
+         }
+         return this.langiumDocuments.getOrCreateDocument(uri);
+      }
+   }
+
+   /**
+    * Warn once when the bound `FileSystemProvider` cannot serve a seeded
+    * document, naming each such document's scheme.
+    *
+    * The last close keeps a document only if the provider says it `exists`, so
+    * each such document leaves the workspace the first time an editor closes
+    * it, and whatever resolved against it breaks. The framework's registry
+    * serves `virtual:` through the `fileSystemProviders` group and every other
+    * scheme through its host, which knows nothing of a scheme an adopter
+    * invented for its seeded documents, and nothing else reports the loss. A
+    * provider that throws counts as not serving the document, since a startup
+    * that failed on a diagnostic would be worse than the loss.
+    *
+    * Runs over every document startup collected outside the file traversal,
+    * which is what `loadAdditionalDocuments` seeded, through the
+    * `additionalDocuments` group or an override of that method, once startup
+    * has added them to the workspace, unless `warnUnservedDocuments` is
+    * `false`.
+    */
+   protected async warnIfDocumentsUnserved(documents: readonly LangiumDocument[]): Promise<void> {
+      const unserved: URI[] = [];
+      for (const document of documents) {
+         let served = false;
+         try {
+            served = await this.writableFileSystemProvider.exists(document.uri);
+         } catch {
+            // Counted as unserved, below.
+         }
+         if (!served) {
+            unserved.push(document.uri);
+         }
+      }
+      if (unserved.length === 0) {
+         return;
+      }
+      const schemes = [...new Set(unserved.map(uri => uri.scheme))];
+      const named = unserved.slice(0, 3).map(uri => uri.toString());
+      this.tracer.warn(
+         `${unserved.length} seeded document(s) under ${schemes.map(scheme => `${scheme}:`).join(', ')} cannot be served by the bound workspace.FileSystemProvider ` +
+            `(${named.join(', ')}${unserved.length > 3 ? ', …' : ''}), so each leaves the workspace at its ` +
+            `last close. Register a provider under the key ${schemes.map(scheme => `'${scheme}'`).join(', ')} in the shared ` +
+            'fileSystemProviders group, or serve the scheme from the host provider; set warnUnservedDocuments: false ' +
+            'to accept the loss.'
+      );
+   }
+
    /**
     * Add back the documents project discovery created that Langium's file
     * traversal then filtered out.
@@ -360,6 +525,31 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
       }
    }
 
+   /**
+    * Forward the locale the client declared, then Langium's own read of the
+    * params. `DefaultWorkspaceManager.initialize` reads `workspaceFolders`
+    * alone, so `params.locale` would otherwise be discarded — and this is the
+    * only place it arrives, which the headless init seams route through too.
+    *
+    * **The ABSENT case is reported from here rather than from `ServerLocale`,
+    * because this is the only end that can see it.** `accept` is not called
+    * when no locale was declared — nor should it be, since `''` is a claim
+    * about a language rather than the absence of one — so a log written there
+    * covers one of the two outcomes and leaves the other looking like a server
+    * that never reached init. Both lines are at `info` for the reason `accept`
+    * gives: the framework ships no catalogue, so an undeclared locale and an
+    * untranslated code produce the same English and the log is what separates
+    * them.
+    */
+   override initialize(params: InitializeParams): void {
+      if (params.locale) {
+         this.serverLocale.accept(params.locale);
+      } else {
+         this.tracer.info("no locale declared at init — rendering messages in the framework's English");
+      }
+      super.initialize(params);
+   }
+
    /**
     * Override of Langium's workspace setup to resolve / reject
     * {@link workspaceInitializedDeferred} once setup completes. Adopters with
@@ -367,22 +557,37 @@ export class HydraniumWorkspaceManager extends DefaultWorkspaceManager {
     * and either delegate to `super.initializeWorkspace(...)` (preserving the
     * default resolve) or call `this.workspaceInitializedDeferred.resolve(...)`
     * themselves after the additional work finishes.
+    *
+    * A failed setup is logged here, since every framework waiter on
+    * {@link workspaceInitialized} discards the rejection; an override that
+    * rejects the deferred itself logs its own failure. A failed startup also
+    * rejects `ready`, so its waiters fail rather than wait forever; an override
+    * that skips `super` and catches a failed startup rejects `_ready` too.
     */
    override async initializeWorkspace(folders: WorkspaceFolder[], cancelToken?: CancellationToken): Promise<void> {
       try {
          await super.initializeWorkspace(folders, cancelToken);
          this.workspaceInitializedDeferred.resolve(undefined);
-      } catch (error) {
+      } catch (error: unknown) {
+         if (isOperationCancelled(error) || isConnectionGoneError(error)) {
+            this.tracer.debug(`Initial workspace build did not complete: ${describeError(error)}`);
+         } else {
+            this.tracer.error(`Initial workspace build failed: ${describeErrorWithStack(error)}`);
+         }
          this.workspaceInitializedDeferred.reject(error);
+         // Langium settles `ready` only after a startup that succeeded. Marked
+         // handled, as logged above; a no-op once startup has resolved it.
+         this._ready.reject(error);
+         this._ready.promise.catch(() => undefined);
          throw error;
       }
    }
 
    /**
     * Default cascade-rebuild handler. Iterates {@link ProjectChangeEvent.affectedDocuments}
-    * and resets each to {@link DocumentState.Changed} so the next build cycle
-    * re-runs the pipeline (parse → link → validate) under the new project
-    * visibility scope.
+    * and resets each to {@link DocumentState.Changed} so the build of the update
+    * that changed the descriptor re-runs the pipeline (parse → link → validate)
+    * under the new project visibility scope.
     *
     * Subclasses can override for additional behaviour (e.g. logging,
     * telemetry, custom rebuild policies); call `super` to preserve the

package/src/langium/workspace/in-memory-file-system-provider.ts

@@ -9,21 +9,46 @@
 
 import { type FileSystemNode, URI } from '@hydranium/langium';
 import { defineMessage, type Tracer } from '@hydranium/protocol';
-import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import { type WritableFileSystemProvider } from './file-system-provider.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { serverSharedFactory, type ServerSharedServicesMinimal } from '../shared-services.js';
-import { serveVirtualDocument } from './virtual-document.js';
+import { notFound } from './file-not-found.js';
 
 /**
- * The browser host's spelling of "the document is not there". Its Node
- * counterpart is `NO_LOADABLE_CONTENT`: this provider has no `realpath`, so the
- * URI policy cannot answer the existence question ahead of the read and the miss
- * surfaces here instead.
+ * A provider's spelling of "the document is not there", raised wherever a read
+ * finds no content — this filesystem, or a URI naming no location a disk-backed
+ * provider can reach. Distinct from `NO_LOADABLE_CONTENT`, which the URI policy
+ * raises when it can settle the question AHEAD of the read; a provider with no
+ * `realpath` cannot, so the miss surfaces here instead.
  */
 export const NO_SUCH_FILE = defineMessage('hydranium/core/no-such-file', 'No such file: {uri}');
 
+/** The same for a node of any kind, so it also covers a directory. */
 export const NO_SUCH_PATH = defineMessage('hydranium/core/no-such-path', 'No such file or directory: {uri}');
 
+/**
+ * A write addressed a URI the provider cannot reach on disk.
+ *
+ * Deliberately not a not-found code: {@link NO_SUCH_FILE} reports something
+ * missing, which a caller may reasonably answer by creating it — exactly the
+ * wrong reading here. The destination is not missing; the URI names no disk
+ * location at all, and no retry makes it one.
+ *
+ * Declared here rather than beside the Node provider that raises it, so the
+ * message catalog stays reachable from the portable `.` entry — the Node
+ * module pulls `node:fs` and is server-only.
+ */
+export const UNSUPPORTED_WRITE = defineMessage(
+   'hydranium/core/unsupported-write',
+   'Cannot write {uri}: the scheme names no location on disk'
+);
+
+/** A delete addressed a URI the provider cannot reach on disk, as {@link UNSUPPORTED_WRITE} a write. */
+export const UNSUPPORTED_DELETE = defineMessage(
+   'hydranium/core/unsupported-delete',
+   'Cannot delete {uri}: the scheme names no location on disk'
+);
+
 /**
  * File content keyed by path, for seeding an {@link InMemoryFileSystemProvider}.
  *
@@ -117,41 +142,47 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
       this.files.set(normalize(uri), content);
    }
 
-   /** Remove the file at `uri`. A no-op when nothing is there. */
-   deleteFile(uri: URI): void {
-      this.files.delete(normalize(uri));
+   /** Remove the file at `uri`. A no-op when nothing is there; a directory is refused. */
+   async deleteFile(uri: URI): Promise<void> {
+      const key = normalize(uri);
+      if (this.hasChildren(key)) {
+         throw new Error(`Cannot delete ${uri.toString()}: it is a directory`);
+      }
+      this.files.delete(key);
    }
 
    async writeFile(uri: URI, content: string): Promise<void> {
       this.setFile(uri, content);
    }
 
-   readFile(uri: URI): Promise<string> {
-      return Promise.resolve(this.readFileSync(uri));
+   // `async` on each read whose sync twin can throw, rather than
+   // `Promise.resolve(this.<x>Sync(uri))`. That form evaluates the sync call
+   // FIRST, so a miss throws before `Promise.resolve` is ever reached — and a
+   // synchronous throw escapes the promise chain: `.catch()` never attaches and
+   // `Promise.all` dies while its argument array is still being built, so a
+   // caller reading several URIs cannot handle the miss it asked about.
+   async readFile(uri: URI): Promise<string> {
+      return this.readFileSync(uri);
    }
 
    readFileSync(uri: URI): string {
-      const served = serveVirtualDocument(this.services, uri);
-      if (served !== undefined) {
-         return served;
-      }
       const content = this.files.get(normalize(uri));
       if (content === undefined) {
-         throw new Error(NO_SUCH_FILE.format({ uri: uri.toString() }));
+         throw notFound(NO_SUCH_FILE.format({ uri: uri.toString() }), uri);
       }
       return content;
    }
 
-   readBinary(uri: URI): Promise<Uint8Array> {
-      return Promise.resolve(this.readBinarySync(uri));
+   async readBinary(uri: URI): Promise<Uint8Array> {
+      return this.readBinarySync(uri);
    }
 
    readBinarySync(uri: URI): Uint8Array {
       return new TextEncoder().encode(this.readFileSync(uri));
    }
 
-   stat(uri: URI): Promise<FileSystemNode> {
-      return Promise.resolve(this.statSync(uri));
+   async stat(uri: URI): Promise<FileSystemNode> {
+      return this.statSync(uri);
    }
 
    statSync(uri: URI): FileSystemNode {
@@ -162,7 +193,7 @@ export class InMemoryFileSystemProvider implements WritableFileSystemProvider {
       if (this.hasChildren(path)) {
          return { isFile: false, isDirectory: true, uri };
       }
-      throw new Error(NO_SUCH_PATH.format({ uri: uri.toString() }));
+      throw notFound(NO_SUCH_PATH.format({ uri: uri.toString() }), uri);
    }
 
    exists(uri: URI): Promise<boolean> {
@@ -239,8 +270,8 @@ function normalize(uri: URI | string): string {
  * services context exactly where a Node host spreads `NodeFileSystem`.
  *
  * A host that needs to reach the provider afterwards — to seed or mutate it
- * mid-test — reads it back off `shared.workspace.FileSystemProvider`, since the
- * slot owns construction.
+ * mid-test — narrows `shared.workspace.FileSystemProvider.host` to this
+ * class, since the slot owns construction.
  */
 export function inMemoryFileSystem(options: InMemoryFileSystemOptions = {}): {
    fileSystemProvider: (services: unknown) => WritableFileSystemProvider;

package/src/langium/workspace/index.ts

@@ -11,6 +11,7 @@ export * from './document-uri-policy.js';
 export * from './file-system-provider.js';
 export * from './in-memory-file-system-provider.js';
 export * from './persistent-file-system-provider.js';
+export * from './self-save-registry.js';
 export * from './index-manager.js';
 export * from './initialize-workspace.js';
 export * from './langium-documents.js';

package/src/langium/workspace/initialize-workspace.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { UriUtils, URI } from '@hydranium/langium';
+import type { Locale } from '@hydranium/protocol';
 // Bare `'path'` (not `node:path`) so a browser bundle can alias it to a POSIX
 // shim — this is the only filesystem-path use left on the portable `.` entry,
 // and it's the headless/CLI string-input convenience of `toWorkspaceFolders`.
@@ -18,6 +19,33 @@ import type { ServerSharedServicesMinimal } from '../shared-services.js';
 /** A workspace folder root accepted by the headless init seams: a filesystem path or a {@link URI}. */
 export type WorkspaceFolderInput = string | URI;
 
+/**
+ * Options for the headless init seams.
+ *
+ * **Optional, and the parameter is optional too**, so that no existing caller
+ * has to change to gain a field it does not set.
+ */
+export interface ProgrammaticInitOptions {
+   /**
+    * The locale to render user-facing server messages in — the headless
+    * equivalent of LSP `initialize`'s `locale`, for a head with no LSP
+    * connection (`startStdioServer`, the CLI subcommands, a test harness).
+    *
+    * Omitted means no locale, which the default renderer resolves as the
+    * framework's English. That is the correct answer for a headless tool: it
+    * has no reading user to have a language.
+    *
+    * **An IETF language tag, hyphenated — `de`, `de-CH`, `zh-Hant-TW` — and
+    * not the POSIX or Java spelling.** An LSP client is held to that syntax by
+    * the protocol, while a headless caller supplies the string itself and the
+    * obvious source is an environment variable holding `de_DE` or
+    * `en_US.UTF-8`. Neither is a tag, and the string is passed through
+    * unchecked, so a renderer that parses it finds nothing to match and every
+    * message renders in English.
+    */
+   readonly locale?: Locale;
+}
+
 /**
  * Normalize the seam's flexible folder argument to LSP {@link WorkspaceFolder}s.
  * A `string` is resolved to an absolute filesystem path and wrapped as a
@@ -58,17 +86,25 @@ function toWorkspaceFolders(folders: WorkspaceFolderInput | ReadonlyArray<Worksp
  *
  * @param services the shared services tree the workspace manager lives on
  * @param folders one or more workspace roots (filesystem paths or URIs)
+ * @param options the message locale, when the caller has one
  */
 export async function initializeWorkspaceProgrammatically(
    services: ServerSharedServicesMinimal,
-   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>
+   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>,
+   options: ProgrammaticInitOptions = {}
 ): Promise<void> {
    const workspaceFolders = toWorkspaceFolders(folders);
    const manager = services.workspace.WorkspaceManager;
-   // `initialize` records the folders (DefaultWorkspaceManager reads only this
+   // `locale` goes through the synthesized params rather than a direct
+   // `acceptLocale` call, so this seam and a real LSP `initialize` reach the
+   // slot by the SAME path — an adopter overriding the capture in
+   // `HydraniumWorkspaceManager.initialize` is honoured headlessly too, which a
+   // second write site here would silently bypass.
+   //
+   // `initialize` records the folders (DefaultWorkspaceManager reads only that
    // field); `initialized` runs `mutex.write(initializeWorkspace)` and resolves
    // once discovery + the init build settle, so awaiting it is the ready gate.
-   manager.initialize({ workspaceFolders } as InitializeParams);
+   manager.initialize({ workspaceFolders, locale: options.locale } as InitializeParams);
    await manager.initialized({} as InitializedParams);
 }
 
@@ -91,12 +127,14 @@ export async function initializeWorkspaceProgrammatically(
  *
  * @param services the shared services tree the workspace manager lives on
  * @param folders one or more workspace roots (filesystem paths or URIs)
+ * @param options the message locale, when the caller has one
  */
 export async function buildWorkspaceProgrammatically(
    services: ServerSharedServicesMinimal,
-   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>
+   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>,
+   options: ProgrammaticInitOptions = {}
 ): Promise<void> {
-   await initializeWorkspaceProgrammatically(services, folders);
+   await initializeWorkspaceProgrammatically(services, folders, options);
    const documents = services.workspace.LangiumDocuments.all.toArray();
    await services.workspace.DocumentBuilder.build(documents, { validation: true });
 }