@hydranium/core 1.0.0-next.7 → 1.0.0-next.71

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

@@ -7,14 +7,49 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type Tracer } from '@hydranium/protocol';
-import { type AstNode, DefaultLangiumDocuments, type LangiumDocument, type URI } from '@hydranium/langium';
+import { type AstNode, DefaultLangiumDocuments, type LangiumDocument, type LangiumDocuments, type URI } from '@hydranium/langium';
+import { defineMessage } from '@hydranium/protocol';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 import { type DocumentUriPolicy } from './document-uri-policy.js';
+import { type HydraniumLangiumDocumentFactory } from './hydranium-langium-document-factory.js';
 
 /**
- * Default `LangiumDocuments` for `@hydranium/core` consumers. Layers two
- * extensions on top of Langium's {@link DefaultLangiumDocuments}:
+ * The document a caller asked to load is not there.
+ *
+ * User-facing, and the Node host's spelling of it: `loadUri` returns `undefined`
+ * exactly when the URI policy's `realpath` reports the path absent. A host whose
+ * provider has no `realpath` never reaches this — the miss surfaces from the
+ * provider instead, so the same condition has one declaration per host.
+ */
+export const NO_LOADABLE_CONTENT = defineMessage('hydranium/core/no-loadable-content', 'No loadable content for {uri}');
+
+/**
+ * A stand-in was asked for at a URI that routes to no grammar, and no language
+ * id was given to route it instead.
+ *
+ * User-facing, and raised BEFORE the parse: left to Langium's ladder the same
+ * condition surfaces as `no services for the extension ''`, which names neither
+ * the URI nor the argument that would have answered.
+ */
+export const NO_LANGUAGE_FOR_STAND_IN = defineMessage(
+   'hydranium/core/no-language-for-stand-in',
+   'No grammar routes {uri}; pass a languageId to say which one the stand-in should parse with'
+);
+
+/**
+ * The registry surface the framework adds on top of Langium's
+ * {@link LangiumDocuments}. Declared separately from the implementing class so
+ * the shared-services slot can narrow to it: the class takes the services tree
+ * as its constructor parameter, so naming the CLASS there would make that type
+ * depend on itself.
+ */
+export interface HydraniumDocumentRegistry extends LangiumDocuments {
+   createEmptyDocument(uri: URI, languageId?: string): LangiumDocument<AstNode>;
+}
+
+/**
+ * Default `LangiumDocuments` for `@hydranium/core` consumers, extending
+ * Langium's {@link DefaultLangiumDocuments} with:
  *
  * 1. **Identity via the {@link DocumentUriPolicy} seam.**
  *    `getOrCreateDocument` resolves the requested URI through the seam — the
@@ -24,31 +59,78 @@ import { type DocumentUriPolicy } from './document-uri-policy.js';
  *    `LangiumDocuments` override. The default resolves to the URI unchanged
  *    (`DefaultDocumentUriPolicy`), matching Langium's own keying.
  *
- * 2. **`createEmptyDocument(uri)` — synchronous** factory for a transient
- *    document with no loadable on-disk content. `getOrCreateDocument` falls
- *    back to it when the seam reports no loadable URI, or when `super` cannot
- *    load it, so callers always receive a document. Abstract because the
- *    parse-result root is grammar-specific (each grammar returns its own
- *    root node type). The fallback document is deliberately
- *    **not** registered: a transient placeholder must not mask the real
- *    document once it appears.
+ * 2. **A load that finds nothing rejects**, rather than answering with a
+ *    transient empty document. An empty AST validates clean, so a placeholder
+ *    hands the caller something that silently is not the file, and a caller
+ *    that wants a document for a URI with no content on disk cannot use one
+ *    anyway: it is unregistered, so no build, index or save can see it, and
+ *    `LangiumDocumentFactory.update` reads from disk. Content that legitimately
+ *    lives outside the filesystem belongs in a virtual document, which carries
+ *    real source text.
  */
-export abstract class AbstractHydraniumLangiumDocuments extends DefaultLangiumDocuments {
+export class HydraniumLangiumDocuments extends DefaultLangiumDocuments implements HydraniumDocumentRegistry {
    /** Document-identity seam, shared with the text store, event filters, and builder. */
    protected readonly uriPolicy: DocumentUriPolicy;
-   protected readonly tracer: Tracer;
+
+   /**
+    * Narrows the inherited Langium factory field to the framework's, so the
+    * language-explicit `fromStringInLanguage` below needs no cast. The
+    * framework's shared module binds that class.
+    */
+   declare protected readonly langiumDocumentFactory: HydraniumLangiumDocumentFactory;
 
    constructor(protected override readonly services: ServerSharedServicesMinimal) {
       super(services);
       this.uriPolicy = services.workspace.DocumentUriPolicy;
-      this.tracer = services.Tracer.for('LangiumDocuments');
    }
 
    /**
-    * Build a transient empty document for `uri`. Implemented by consumers
-    * because the parse-result root is grammar-specific.
+    * Build a transient document for `uri` by parsing empty text with the
+    * grammar `languageId` names, or the one `uri` routes to when it is
+    * omitted, so the root is that language's entry type with every containment
+    * list initialised.
+    *
+    * For callers that need a document at a URI with no content on disk — the
+    * scope provider querying before a file exists is the case it was added for.
+    * `getOrCreateDocument` deliberately does NOT fall back to this: fabricating
+    * a document behind a caller that asked to LOAD one hands back something
+    * that silently is not the file, whereas calling this is a caller saying it
+    * wants a stand-in.
+    *
+    * **Pass `languageId` whenever the URI names no file.** The create-element
+    * flow this exists for asks at the DIRECTORY a file is about to be written
+    * into, and a directory URI has no extension for the routing ladder to end
+    * on — so omitting the id there fails inside the parse, on an empty
+    * extension rather than on the URI. A caller in that position always knows
+    * its language: {@link HydraniumScopeProvider} is bound per grammar, and a
+    * request that names no document at all still carries the AST type
+    * `ExtendedServiceRegistry.soleServicesByType` routes on.
+    *
+    * The result is not registered, so nothing downstream can see it, and
+    * `LangiumDocumentFactory.update` would read from disk. It is a probe, not a
+    * document under construction; content that must survive belongs in a
+    * virtual document, which carries real source text.
+    *
+    * Building the root by hand instead needs the entry type name and a cast
+    * past the generated types, and leaves those lists `undefined`. A grammar
+    * whose entry rule opens with mandatory syntax yields a parse error here,
+    * and it is kept: `AstReflection.isComplete` is `false` for such a root
+    * however it is built, so the error states the same thing.
     */
-   abstract createEmptyDocument(uri: URI): LangiumDocument<AstNode>;
+   createEmptyDocument(uri: URI, languageId?: string): LangiumDocument<AstNode> {
+      if (languageId !== undefined) {
+         return this.langiumDocumentFactory.fromStringInLanguage('', uri, languageId);
+      }
+      if (!this.services.ServiceRegistry.getServicesFor(uri)) {
+         // Reported here rather than left to the parse, which ends on the empty
+         // extension and so names neither the URI nor the id that would have
+         // answered.
+         throw new Error(NO_LANGUAGE_FOR_STAND_IN.format({ uri: uri.toString() }));
+      }
+      // The two-argument overload is synchronous; passing a cancellation token
+      // selects the promise-returning one, which this contract cannot await.
+      return this.langiumDocumentFactory.fromString('', uri);
+   }
 
    override async getOrCreateDocument(uri: URI): Promise<LangiumDocument<AstNode>> {
       const resolved = this.uriPolicy.loadUri(uri);
@@ -68,27 +150,18 @@ export abstract class AbstractHydraniumLangiumDocuments extends DefaultLangiumDo
             return await super.getOrCreateDocument(resolved);
          } catch (error: unknown) {
             // Load lost a race with a concurrent create — return that document.
+            // Checked before propagating, so a race is not reported as a
+            // missing file; cancellation carries no document and falls through.
             const reentrant = this.getDocument(resolved);
             if (reentrant) {
                this.services.workspace.CstResidencyService.rehydrate(reentrant);
                return reentrant;
             }
-            // No concurrent document, so the load genuinely failed. The fallback
-            // below still runs, because the file-not-found case is the ordinary
-            // one here and no provider-independent way to recognise it exists:
-            // Node's provider throws `ENOENT`, the in-memory one a bare `Error`,
-            // and the provider is a seam an adopter rebinds. Discriminating on
-            // message text across that seam would be a worse defect than the
-            // one it fixes. So the failure is TRACED rather than propagated —
-            // an unreadable-but-present file still degrades to an empty
-            // document, but it stops doing so silently.
-            this.tracer
-               .with(resolved.toString())
-               .debug(`Load failed, falling back to an empty document: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
          }
       }
-      // No loadable content (missing / synthetic / not yet written): a transient
-      // empty placeholder keyed canonically — not registered (see the class doc).
-      return this.createEmptyDocument(resolved ?? uri);
+      // The seam reports no loadable content, so there is nothing to read and
+      // no error from a read to carry.
+      throw new Error(NO_LOADABLE_CONTENT.format({ uri: uri.toString() }));
    }
 }

package/src/locale/index.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+export * from './server-locale.js';

package/src/locale/server-locale.ts

@@ -0,0 +1,86 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import type { Tracer } from '@hydranium/protocol';
+import { type LogNameOptions } from '../langium/diagnostics/logger.js';
+import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
+
+/** Construction options for {@link ServerLocale}. */
+export type ServerLocaleOptions = LogNameOptions;
+
+/**
+ * The locale contract the `ServerLocale` slot holds, implemented by
+ * {@link DefaultServerLocale}.
+ *
+ * An interface rather than the class, so the slot is compared STRUCTURALLY —
+ * a class-typed slot carries its `protected` members into every assignability
+ * check, compared nominally, which makes it unsatisfiable across two physical
+ * copies of this package and unreplaceable by an adopter's own declaration.
+ */
+export interface ServerLocale {
+   /** The locale, or `undefined` when no init supplied one — the framework's English. */
+   readonly value: string | undefined;
+   accept(locale: string): void;
+}
+
+/**
+ * The locale the server was handed at init, for whoever needs to render in the
+ * reading user's language. Held apart from the message renderer that reads it,
+ * so replacing the renderer cannot drop locale handling.
+ *
+ * A plain string in and out. A consumer that must react to a change rather than
+ * read the current value wraps this itself — nothing does today, and both real
+ * hosts respawn the server on a display-language switch.
+ */
+export class DefaultServerLocale implements ServerLocale {
+   protected readonly tracer: Tracer;
+   protected current: string | undefined;
+
+   constructor(services: ServerSharedServicesMinimal, options: ServerLocaleOptions = {}) {
+      this.tracer = services.Tracer.for(options.logName ?? 'ServerLocale').trace('instantiated');
+   }
+
+   /** The locale, or `undefined` when no init supplied one — which means the framework's English. */
+   get value(): string | undefined {
+      return this.current;
+   }
+
+   /**
+    * Take the locale an init declared.
+    *
+    * **One locale per process, and the reason the OTHER heads need none of
+    * their own.** The data and GLSP heads publish a port over the LSP
+    * connection and are reached by forwarding a socket to it, so they are the
+    * same process as the LSP head that was handed this locale — there is no
+    * topology in which one of them serves a second frontend. The Theia backend
+    * is the case that would break it, and it holds no locale precisely because
+    * it serves every frontend at once; nothing there writes here.
+    *
+    * The framework accepts a locale and never sources one, and neither
+    * validates nor normalises the tag: rejecting an unfamiliar one would be
+    * selecting a locale.
+    *
+    * Override to ignore the argument, which is how a host pins a locale it
+    * already knows but has no LSP client to declare.
+    *
+    * **The line is at `info`, which is a deliberate exception to the
+    * per-service default.** A locale is written once per process and it is the
+    * one setting that silently changes every user-facing sentence the server
+    * produces, so a reader trying to explain an unexpected language has nothing
+    * else to look at: the framework ships no catalogue, so "no entry for this
+    * code" and "no locale declared" both render the English and are
+    * indistinguishable in the output. At `debug` the line is below the default
+    * threshold and therefore absent from exactly the log someone would be
+    * reading.
+    */
+   accept(locale: string): void {
+      this.current = locale;
+      this.tracer.info(`rendering messages in locale '${locale}'`);
+   }
+}

package/src/lsp/hydranium-document-update-handler.ts

@@ -257,7 +257,7 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
             }
             const uri = UriUtils.toUri(change.uri);
             const mtimeMs = await this.fileSystemProvider.mtimeMs?.(uri);
-            if (mtimeMs !== undefined && this.selfSaveRegistry.matches(uri.fsPath, mtimeMs)) {
+            if (mtimeMs !== undefined && this.selfSaveRegistry.isRegistered(uri.fsPath, mtimeMs)) {
                return undefined;
             }
             return change;

package/src/lsp/index.ts

@@ -8,7 +8,7 @@
  ********************************************************************************/
 
 export * from './completion/hydranium-completion-provider.js';
-export * from './instrument-connection.js';
+export * from './lsp-latency.js';
 export * from './semantic-token-provider.js';
 export * from './language-module.js';
 export * from './shared-module.js';

package/src/lsp/lsp-latency.ts

@@ -0,0 +1,62 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import type { LatencyCollector } from '@hydranium/protocol';
+import type { ConnectionOptions, Message } from 'vscode-jsonrpc';
+
+/**
+ * Connection options that time every inbound LSP message into `latency` under
+ * its method name — the LSP analog of the data-server RPC chokepoint.
+ *
+ * Pass the result to `createConnection` where the head builds its connection:
+ * `createConnection(ProposedFeatures.all, lspLatencyOptions(latency))`. The
+ * transport is untouched, so a head keeps whatever `--stdio` / `--socket`
+ * selection its arguments make.
+ *
+ * **`messageStrategy` is the seam because it is the only one the handlers
+ * actually pass through.** `vscode-languageserver` builds its `Connection` as an
+ * object whose `onHover`, `onCompletion` and every other named helper register
+ * against the inner protocol connection captured in their closure — not against
+ * the returned object's own `onRequest`. Langium registers exclusively through
+ * those helpers, so decorating the `Connection` reaches none of them and reports
+ * an empty LSP half no matter how much traffic ran. `handleMessage` sits on the
+ * dispatch path itself, which every request and notification crosses, so it also
+ * catches `initialize` — special-cased into `onInitialize` and invisible to any
+ * `onRequest` decoration.
+ *
+ * What it measures is **dispatch plus handler**, not handler alone: the wait a
+ * client actually experiences, including time queued behind other work.
+ *
+ * When `latency` is `undefined` the seam is off and this returns `undefined`, so
+ * a head can pass the result of an env-gated factory (`latencyFromEnv()`)
+ * straight through and pay nothing when timing is not enabled.
+ */
+export function lspLatencyOptions(latency: LatencyCollector | undefined): ConnectionOptions | undefined {
+   if (!latency) {
+      return undefined;
+   }
+   return {
+      messageStrategy: {
+         handleMessage: (message: Message, next: (message: Message) => void | Promise<void>) => {
+            // Responses to requests the SERVER sent carry no method and are not
+            // work this head performed; timing them would report the client's
+            // latency under a name this collector cannot supply.
+            if (!hasMethod(message)) {
+               return next(message);
+            }
+            return latency.time(message.method, () => next(message));
+         }
+      }
+   };
+}
+
+/** Narrow to the messages that name an operation — requests and notifications. */
+function hasMethod(message: Message): message is Message & { method: string } {
+   return typeof (message as { method?: unknown }).method === 'string';
+}

package/src/messages/carriers.ts

@@ -0,0 +1,78 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import {
+   hasMessageIdentity,
+   messageData,
+   type HydraniumMessageData,
+   type MessageDefinition,
+   type ParamsArg,
+   type ResolvedMessage
+} from '@hydranium/protocol';
+import type { AstNode, DiagnosticData, DiagnosticInfo, Properties, ValidationAcceptor } from '@hydranium/langium';
+import { Diagnostic } from 'vscode-languageserver-protocol';
+
+/**
+ * Raise a validation diagnostic from a declaration, so the call site never
+ * restates the code or the sentence.
+ *
+ * `code` is omitted from `info` because this owns it — the framework claims LSP
+ * `Diagnostic.code` for framework codes, which collides with no adopter today
+ * and is a stated rule rather than an accident. `data` is deliberately NOT
+ * omitted: Langium owns `data.code` for code-action dispatch, so a caller has to
+ * be able to request a quick fix. The identity is merged OVER whatever they
+ * pass, which makes the two conventions co-exist rather than compete.
+ *
+ * `data` admits adopter-owned keys beside Langium's, which is why the index
+ * signature is there rather than a bare `Partial<DiagnosticData>`. Langium's
+ * shape is closed, and a diagnostic that carries a COMPANION payload for its own
+ * surface to read — the field a form must highlight, say — has nowhere else to
+ * put it: an encoder projecting that payload reads `diagnostic.data`, so the
+ * narrower type made the identity and the companion mutually exclusive.
+ *
+ * The identity lands in both `code` and `data.hydranium` on purpose. `code` is
+ * what survives to the editor surface; Theia's converter drops `data` before the
+ * squiggle, so a parameterised diagnostic falls back to the server's English
+ * there while any adopter-owned surface can still render the parameterised form
+ * from the marker store.
+ *
+ * `DiagnosticInfo` must be Langium's own type: a `Parameters<ValidationAcceptor>[2]`
+ * shortcut compiles but loses the `property?: Properties<N>` relation. The `data`
+ * re-type has to be an intersection rather than an `Omit` alone, because Langium
+ * declares `data?: unknown` and an `unknown` cannot be spread.
+ */
+export function acceptMessage<S extends string, N extends AstNode, P extends Properties<N> = Properties<N>>(
+   accept: ValidationAcceptor,
+   severity: 'error' | 'warning' | 'info' | 'hint',
+   message: MessageDefinition<S>,
+   info: Omit<DiagnosticInfo<N, P>, 'code' | 'data'> & { data?: Partial<DiagnosticData> & Record<string, unknown> },
+   ...params: ParamsArg<S>
+): void {
+   const data: HydraniumMessageData & Partial<DiagnosticData> & Record<string, unknown> = {
+      ...info.data,
+      ...messageData(message, ...params)
+   };
+   accept(severity, message.format(...params), { ...info, code: message.code, data });
+}
+
+/**
+ * Recover the identity from a published diagnostic, for a surface that
+ * identifies or renders diagnostics itself.
+ *
+ * `Diagnostic.message` is `string | MarkupContent` in LSP 3.17+, so the text
+ * comes from upstream's own `Diagnostic.getMessageString` rather than a
+ * hand-rolled narrowing — consuming the library in its style, and one fewer
+ * place restating the union.
+ */
+export function resolvedFromDiagnostic(diagnostic: Diagnostic): ResolvedMessage | undefined {
+   if (!hasMessageIdentity(diagnostic.data)) {
+      return undefined;
+   }
+   return { ...diagnostic.data.hydranium, text: Diagnostic.getMessageString(diagnostic) };
+}

package/src/messages/index.ts

@@ -0,0 +1,27 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/**
+ * Every user-facing message `@hydranium/core` raises, plus the carrier helpers
+ * that attach an identity to one.
+ *
+ * Declarations stay beside their call sites and are re-exported here, so this is
+ * enumeration rather than centralization: a code's package segment has to name
+ * the package that raises it. The English is a fallback, not a contract; the
+ * code is the contract, and renaming one is a breaking change.
+ */
+
+export * from './carriers.js';
+export * from './renderer.js';
+
+export { MODEL_UPDATE_EDIT } from '../langium/model-service/model-service.js';
+export { SEPARATOR_IN_NAME } from '../langium/naming/name-separator-validation.js';
+export { LEXING_ERROR, UNRESOLVED_REFERENCE } from '../langium/validation/document-validator.js';
+export { NO_LOADABLE_CONTENT } from '../langium/workspace/langium-documents.js';
+export { NO_SUCH_FILE, NO_SUCH_PATH } from '../langium/workspace/in-memory-file-system-provider.js';