@hydranium/core 1.0.0-next.10

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

@@ -0,0 +1,266 @@
+/********************************************************************************
+ * 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 AstNode, type AstNodeDescription, DefaultIndexManager, type LangiumDocument, type URI } from '@hydranium/langium';
+import type { CancellationToken } from 'vscode-languageserver-protocol';
+import type { LogNameOptions } from '../diagnostics/logger.js';
+import type { ProjectManager } from '../project/project-manager.js';
+import type { ServerSharedServicesMinimal } from '../shared-services.js';
+
+/**
+ * Default `IndexManager` for `@hydranium/core` consumers. Layers an
+ * additional **`elementsByName: name → descriptions`** index on top of
+ * Langium's {@link DefaultIndexManager} so consumers can look up
+ * descriptions by exact name in O(1) instead of streaming the whole
+ * index. Provides the resolution helpers built on that index:
+ *
+ * - {@link getElementsByName} — O(1) name lookup returning every match,
+ *   optionally narrowed by reference type and owning language.
+ * - {@link getElementByName} — the single-answer form, abstaining when the
+ *   name does not identify exactly one element.
+ * - {@link resolveElement} — turn an `AstNodeDescription` into the
+ *   actual `AstNode` via `LangiumDocuments` + `AstNodeLocator`.
+ * - {@link resolveElementByName} — composition of the two.
+ * - {@link resolveSemanticElement} — resolve a document's root node;
+ *   default returns the parse-result root, consumers with wrapper
+ *   grammars override to return the inner semantic root via
+ *   {@link findSemanticRoot}.
+ *
+ * The `elementsByName` index is maintained incrementally inside
+ * Langium's `updateContent` / `removeContent` lifecycle. Subclasses
+ * that add their own indexes (e.g. a reverse map from project to
+ * member URIs for project-tier queries) override `updateContent` /
+ * `removeContent` and chain `super`.
+ */
+export class HydraniumIndexManager extends DefaultIndexManager {
+   /** Maps `description.name` → list of descriptions with that name. Used for O(1) `getElementByName`. */
+   protected elementsByName = new Map<string, AstNodeDescription[]>();
+
+   protected readonly sharedServices: ServerSharedServicesMinimal;
+   protected readonly tracer: Tracer;
+
+   constructor(services: ServerSharedServicesMinimal, options: LogNameOptions = {}) {
+      super(services);
+      this.sharedServices = services;
+      this.tracer = services.Tracer.for(options.logName ?? 'IndexManager').trace('instantiated');
+   }
+
+   /**
+    * Lazy access to {@link ProjectManager}. Reading it eagerly in the
+    * constructor caused a DI cycle in project-aware consumers
+    * (`DocumentBuilder → IndexManager → ProjectManager →
+    * DocumentBuilder`); deferring the read until first use breaks the
+    * cycle without splitting the bindings.
+    */
+   protected get projectManager(): ProjectManager {
+      return this.sharedServices.workspace.ProjectManager;
+   }
+
+   // ============================================================
+   // Incremental index maintenance
+   // ============================================================
+
+   override async updateContent(document: LangiumDocument, cancelToken?: CancellationToken): Promise<void> {
+      const uriStr = document.uri.toString();
+      this.removeFromElementsByName(uriStr);
+      await super.updateContent(document, cancelToken);
+      this.addToElementsByName(uriStr);
+   }
+
+   override removeContent(uri: URI): void {
+      this.removeFromElementsByName(uri.toString());
+      super.removeContent(uri);
+   }
+
+   /**
+    * Drop all entries this URI contributed to {@link elementsByName}.
+    * Reads from `symbolIndex` which still holds the old descriptions at
+    * this point (we run *before* `super` clears them).
+    */
+   protected removeFromElementsByName(uriStr: string): void {
+      const oldDescs = this.symbolIndex.get(uriStr);
+      if (!oldDescs) {
+         return;
+      }
+      for (const desc of oldDescs) {
+         const entries = this.elementsByName.get(desc.name);
+         if (!entries) {
+            continue;
+         }
+         const filtered = entries.filter(entry => entry.documentUri.toString() !== uriStr);
+         if (filtered.length === 0) {
+            this.elementsByName.delete(desc.name);
+         } else {
+            this.elementsByName.set(desc.name, filtered);
+         }
+      }
+   }
+
+   /**
+    * Add this URI's fresh contributions to {@link elementsByName}. Reads
+    * from `symbolIndex` which now holds the new descriptions (we run
+    * *after* `super.updateContent` populated them).
+    */
+   protected addToElementsByName(uriStr: string): void {
+      const newDescs = this.symbolIndex.get(uriStr);
+      if (!newDescs) {
+         return;
+      }
+      for (const desc of newDescs) {
+         const entries = this.elementsByName.get(desc.name);
+         if (entries) {
+            entries.push(desc);
+         } else {
+            this.elementsByName.set(desc.name, [desc]);
+         }
+      }
+   }
+
+   // ============================================================
+   // Lookup + resolution helpers
+   // ============================================================
+
+   /**
+    * O(1) lookup by exact name, returning EVERY match — optionally
+    * narrowed by reference type (via Langium's `AstReflection.isSubtype`,
+    * so grammar subtype relations are honoured) and by the owning
+    * document's language.
+    *
+    * The name index spans every language in the workspace, so a name is
+    * only as unique as the adopter's naming scheme makes it. Callers that
+    * need one answer go through {@link getElementByName}, which abstains
+    * when the name does not identify a single element; callers that can
+    * disambiguate from context (or want to report the ambiguity) use this.
+    */
+   getElementsByName(name: string, type?: string, languageId?: string): readonly AstNodeDescription[] {
+      const candidates = this.elementsByName.get(name);
+      if (!candidates || candidates.length === 0) {
+         return [];
+      }
+      const byType = type ? candidates.filter(candidate => this.astReflection.isSubtype(candidate.type, type)) : candidates;
+      if (languageId === undefined) {
+         return byType;
+      }
+      return byType.filter(candidate => this.languageIdOf(candidate.documentUri) === languageId);
+   }
+
+   /**
+    * O(1) lookup by exact name, returning the FIRST match — optionally
+    * narrowed by reference type and owning language.
+    *
+    * **First-match is deliberate here, and is not a routing answer.** A real
+    * workspace indexes one logical element under several descriptions: scope
+    * computation emits a symbol per visibility tier, and a wrapper grammar
+    * exports both its document root and its inner semantic root. So a
+    * multi-match is usually one element seen several ways, and abstaining on
+    * it would empty every reference dropdown that resolves a scope's source
+    * by name.
+    *
+    * What genuinely IS ambiguous — the same name in two different DOCUMENTS —
+    * cannot be told apart from that here, only by a caller that knows what it
+    * is asking. {@link getElementsByName} exposes the full set for callers that
+    * must distinguish; the useful test is whether the matches disagree on the
+    * document, which is the only distinction language routing needs.
+    */
+   getElementByName(name: string, type?: string, languageId?: string): AstNodeDescription | undefined {
+      return this.getElementsByName(name, type, languageId)[0];
+   }
+
+   /**
+    * The language id owning a document, or `undefined` when its URI
+    * matches no registered language. Non-throwing: an indexed document
+    * whose URI no longer routes must not break an unrelated lookup.
+    *
+    * One walk of the lookup ladder, via `getServicesFor`. The obvious
+    * `hasServices(uri) && getServices(uri)` pair costs two, because Langium
+    * implements `hasServices` as a try/catch around `getServices` — and this
+    * runs once per CANDIDATE inside {@link getElementsByName}'s language filter.
+    */
+   protected languageIdOf(documentUri: URI): string | undefined {
+      return this.sharedServices.ServiceRegistry.getServicesFor(documentUri)?.LanguageMetaData.languageId;
+   }
+
+   /** Turn an `AstNodeDescription` into the actual `AstNode` via the language-specific `AstNodeLocator`. */
+   resolveElement(description?: AstNodeDescription): AstNode | undefined {
+      if (!description) {
+         return undefined;
+      }
+      const langiumDocument = this.documents.getDocument(description.documentUri);
+      if (!langiumDocument) {
+         return undefined;
+      }
+      const languageServices = this.serviceRegistry.getServices(description.documentUri);
+      return languageServices.workspace.AstNodeLocator.getAstNode(langiumDocument.parseResult.value, description.path);
+   }
+
+   /** Compose {@link getElementByName} with {@link resolveElement}. */
+   resolveElementByName(name: string, type?: string, languageId?: string): AstNode | undefined {
+      return this.resolveElement(this.getElementByName(name, type, languageId));
+   }
+
+   /**
+    * Project-scoped element listing — all descriptions whose owning URI
+    * belongs to the given project. Equivalent to Langium's
+    * `allElements(type)` but filtered to one project's members.
+    *
+    * Returns direct members only — **no visibility transitivity is
+    * applied**. For "everything visible from project X", map
+    * {@link ProjectManager.getVisibleProjects} over this method and
+    * flatten the result.
+    *
+    * Returns an empty array if the project id is unknown.
+    */
+   getElementsInProject(projectId: string, type?: string): AstNodeDescription[] {
+      const memberUris = this.projectManager.getProjectUris(projectId);
+      if (memberUris.length === 0) {
+         return [];
+      }
+      const memberUriSet = new Set<string>();
+      for (const uri of memberUris) {
+         memberUriSet.add(uri.toString());
+      }
+      const result: AstNodeDescription[] = [];
+      for (const bucket of this.elementsByName.values()) {
+         for (const description of bucket) {
+            if (!memberUriSet.has(description.documentUri.toString())) {
+               continue;
+            }
+            if (type && !this.astReflection.isSubtype(description.type, type)) {
+               continue;
+            }
+            result.push(description);
+         }
+      }
+      return result;
+   }
+
+   /**
+    * Resolve the "semantic root" of a document — the meaningful root
+    * element callers expect when treating the document as a unit.
+    * Default returns the parse-result root directly; consumers with a
+    * wrapper grammar (a generic envelope with a single inner element)
+    * override {@link findSemanticRoot} to return the inner element.
+    */
+   resolveSemanticElement(uri: URI): AstNode | undefined {
+      const document = this.documents.getDocument(uri);
+      if (!document) {
+         return undefined;
+      }
+      return this.findSemanticRoot(document);
+   }
+
+   /**
+    * Default: the document's parse-result root. Override for wrapper
+    * grammars that store the meaningful root inside an envelope.
+    */
+   protected findSemanticRoot(document: LangiumDocument): AstNode | undefined {
+      return document.parseResult.value;
+   }
+}

package/src/langium/workspace/index.ts

@@ -0,0 +1,23 @@
+/********************************************************************************
+ * 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 './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 './index-manager.js';
+export * from './initialize-workspace.js';
+export * from './langium-documents.js';
+export * from './hydranium-workspace-manager.js';
+export * from './hydranium-workspace-lock.js';
+export * from './write-lock-scope.js';
+export * from './hydranium-langium-document-factory.js';
+export * from './additional-document-contribution.js';
+export * from './synthetic.js';
+export * from './virtual-document.js';

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

@@ -0,0 +1,102 @@
+/********************************************************************************
+ * 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 { UriUtils, URI } from '@hydranium/langium';
+// 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`.
+import * as path from 'path';
+import type { InitializeParams, InitializedParams, WorkspaceFolder } from 'vscode-languageserver';
+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;
+
+/**
+ * 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
+ * `file:` URI; a {@link URI} is taken as-is. `name` is the URI's basename.
+ */
+function toWorkspaceFolders(folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>): WorkspaceFolder[] {
+   const list = Array.isArray(folders) ? folders : [folders as WorkspaceFolderInput];
+   return list.map(entry => {
+      const uri = typeof entry === 'string' ? URI.file(path.resolve(entry)) : entry;
+      return { uri: uri.toString(), name: UriUtils.basename(uri) };
+   });
+}
+
+/**
+ * Initialize a hydranium workspace **without an LSP `initialize` request** —
+ * the headless counterpart to the editor entry. Drives the workspace manager's
+ * own lifecycle methods: sets the workspace folders, then runs the
+ * lock-protected discovery + standard init build.
+ *
+ * Leaves the workspace exactly as an LSP `initialize`/`initialized` pair would:
+ * `ProjectManager.discoverProjects` has run, the project registry is populated,
+ * and the init build has covered every document in the workspace folders —
+ * including the project descriptors, which `HydraniumWorkspaceManager.performStartup`
+ * back-fills because Langium's traversal drops URIs discovery already created a
+ * document for. Documents outside the folders (a contributed library document
+ * seeded elsewhere, a URI a client opens later) still build on demand; use
+ * {@link buildWorkspaceProgrammatically} to force every registered document
+ * built regardless of where it came from. The eager build pipeline (integrity,
+ * AST extensions) is wired at bootstrap (`DEFAULT_EAGER_SERVICES`), not here, so
+ * it is already active.
+ *
+ * Client-only LSP-init steps (configuration fetch, server-capability
+ * negotiation, `onInitialize`/`onInitialized` events) are intentionally not
+ * reproduced — a headless server has no client and they degrade gracefully.
+ *
+ * Invoke once during headless startup; this is not a re-initialization API.
+ * Errors from discovery/build propagate to the caller.
+ *
+ * @param services the shared services tree the workspace manager lives on
+ * @param folders one or more workspace roots (filesystem paths or URIs)
+ */
+export async function initializeWorkspaceProgrammatically(
+   services: ServerSharedServicesMinimal,
+   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>
+): Promise<void> {
+   const workspaceFolders = toWorkspaceFolders(folders);
+   const manager = services.workspace.WorkspaceManager;
+   // `initialize` records the folders (DefaultWorkspaceManager reads only this
+   // 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);
+   await manager.initialized({} as InitializedParams);
+}
+
+/**
+ * {@link initializeWorkspaceProgrammatically} **and then build every registered
+ * document to `Validated`** — the "fully-built workspace" convenience for
+ * headless consumers (test harnesses, eager batch tools) that want every
+ * registered document linked + validated, not only the ones inside a workspace
+ * folder.
+ *
+ * The trailing `DocumentBuilder.build(..., { validation: true })` over
+ * `LangiumDocuments.all` picks up anything the init build did not reach —
+ * documents registered from outside the folders. For a workspace whose content
+ * the init build already covered it is effectively idempotent, since the builder
+ * skips documents already at the target state.
+ *
+ * Use {@link initializeWorkspaceProgrammatically} instead when you only need the
+ * project registry populated (e.g. listing projects) and want documents to build
+ * on demand, as an editor session does.
+ *
+ * @param services the shared services tree the workspace manager lives on
+ * @param folders one or more workspace roots (filesystem paths or URIs)
+ */
+export async function buildWorkspaceProgrammatically(
+   services: ServerSharedServicesMinimal,
+   folders: WorkspaceFolderInput | ReadonlyArray<WorkspaceFolderInput>
+): Promise<void> {
+   await initializeWorkspaceProgrammatically(services, folders);
+   const documents = services.workspace.LangiumDocuments.all.toArray();
+   await services.workspace.DocumentBuilder.build(documents, { validation: true });
+}

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

@@ -0,0 +1,94 @@
+/********************************************************************************
+ * 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 AstNode, DefaultLangiumDocuments, type LangiumDocument, type URI } from '@hydranium/langium';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
+import { type DocumentUriPolicy } from './document-uri-policy.js';
+
+/**
+ * Default `LangiumDocuments` for `@hydranium/core` consumers. Layers two
+ * extensions on top of Langium's {@link DefaultLangiumDocuments}:
+ *
+ * 1. **Identity via the {@link DocumentUriPolicy} seam.**
+ *    `getOrCreateDocument` resolves the requested URI through the seam — the
+ *    same identity the text store and the AST-document event filters use — so
+ *    an adopter that strengthens document identity (e.g. resolving symlinks to
+ *    a real path) does so by binding the policy *once*, with no
+ *    `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.
+ */
+export abstract class AbstractHydraniumLangiumDocuments extends DefaultLangiumDocuments {
+   /** Document-identity seam, shared with the text store, event filters, and builder. */
+   protected readonly uriPolicy: DocumentUriPolicy;
+   protected readonly tracer: Tracer;
+
+   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.
+    */
+   abstract createEmptyDocument(uri: URI): LangiumDocument<AstNode>;
+
+   override async getOrCreateDocument(uri: URI): Promise<LangiumDocument<AstNode>> {
+      const resolved = this.uriPolicy.loadUri(uri);
+      if (resolved) {
+         const existing = this.getDocument(resolved);
+         if (existing) {
+            // A registered document may have had its CST shed by a residency
+            // policy. CST→AST readers that fetch it here — e.g. the call/type
+            // hierarchy's `findDeclarationNodeAtOffset(root.$cstNode, …).astNode`
+            // offset-scan — run no build, so restore the CST on demand. No-op
+            // (and so behaviour-neutral) when the CST is resident.
+            this.services.workspace.CstResidencyService.rehydrate(existing);
+            return existing;
+         }
+         try {
+            // Real on-disk content → Langium loads it and registers it.
+            return await super.getOrCreateDocument(resolved);
+         } catch (error: unknown) {
+            // Load lost a race with a concurrent create — return that document.
+            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)}`);
+         }
+      }
+      // 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);
+   }
+}