@hydranium/core 1.0.0-next.10

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

@@ -0,0 +1,127 @@
+/********************************************************************************
+ * 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 FileSystemNode, URI } from '@hydranium/langium';
+import { type Tracer } from '@hydranium/protocol';
+import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
+/**
+ * File content keyed by path, for seeding an {@link InMemoryFileSystemProvider}.
+ *
+ * Keys are absolute URI strings unless {@link InMemoryFileSystemOptions.rootUri}
+ * is given, in which case they are relative to it. The relative form is what
+ * lets a build step emit the record without knowing where the host will mount
+ * the workspace.
+ */
+export type FileSystemSeed = Readonly<Record<string, string>>;
+/** Options for {@link InMemoryFileSystemProvider} and {@link inMemoryFileSystem}. */
+export interface InMemoryFileSystemOptions extends LogNameOptions {
+    /** Initial content. Absent leaves the filesystem empty but writable. */
+    seed?: FileSystemSeed;
+    /**
+     * Prefix for relative {@link seed} keys, without a trailing separator. When
+     * omitted the keys are taken as absolute URIs.
+     */
+    rootUri?: string;
+}
+/**
+ * A writable filesystem held in a `Map`, for a host with no disk — a browser
+ * worker, or a test that needs the workspace walk to find real content.
+ *
+ * # Why neither shipped provider stands in
+ *
+ * `DefaultEmptyFileSystemProvider` is genuinely empty (reads throw, writes
+ * are dropped) and the disk-backed one in `@hydranium/core/node` pulls
+ * `node:fs`, which a browser bundle refuses to resolve. A host that means to
+ * open a workspace without a disk needs a third thing: real contents, no
+ * syscalls.
+ *
+ * # It must be typed writable, not merely `FileSystemProvider`
+ *
+ * The `fileSystemProvider` context slot accepts what it is handed only if that
+ * carries `writeFile`; anything narrower is silently replaced by the empty
+ * default, which presents as "the workspace is empty" rather than as a wiring
+ * error. A read-only in-memory provider is therefore not a smaller version of
+ * this one — it is one that does not bind.
+ *
+ * # Directories are implied, never stored
+ *
+ * Only files are held. A directory exists exactly when some file key sits under
+ * it, which is what keeps a write a single `Map.set` with no parent-creation
+ * step to forget. The cost is that an empty directory cannot be represented; the
+ * workspace walk does not need one, and a stored directory set would be a second
+ * source of truth to keep in step with the first.
+ *
+ * # A trailing separator is stripped on every lookup
+ *
+ * Langium spells the workspace root both with and without one depending on which
+ * walk asks, so normalising only where a directory prefix is computed leaves
+ * `stat` and `exists` disagreeing with `readDirectory` about the same folder.
+ *
+ * # What it deliberately does not answer
+ *
+ * No watch notifications, no case-insensitivity, no eviction policy for a
+ * workspace larger than memory. `mtimeMs` and `realpath` are omitted rather than
+ * stubbed, which the framework degrades on by design: the self-save filter lets
+ * the change through and the URI policy keeps the URI it was given.
+ *
+ * Nor does the map outlive the host: every write is lost when the process or the
+ * page goes. `PersistentFileSystemProvider` is the subclass that mirrors
+ * the same writes into an asynchronous backing store, and it is a subclass
+ * rather than an option because the map has to stay the read path either way.
+ */
+export declare class InMemoryFileSystemProvider implements WritableFileSystemProvider {
+    protected readonly services: ServerSharedServicesMinimal;
+    protected readonly files: Map<string, string>;
+    protected readonly tracer: Tracer;
+    constructor(services: ServerSharedServicesMinimal, options?: InMemoryFileSystemOptions);
+    /**
+     * Replace the content at `uri`, creating it if absent. The synchronous twin
+     * of `writeFile`, for a test that mutates the filesystem between builds
+     * rather than through the server.
+     */
+    setFile(uri: URI, content: string): void;
+    /** Remove the file at `uri`. A no-op when nothing is there. */
+    deleteFile(uri: URI): void;
+    writeFile(uri: URI, content: string): Promise<void>;
+    readFile(uri: URI): Promise<string>;
+    readFileSync(uri: URI): string;
+    readBinary(uri: URI): Promise<Uint8Array>;
+    readBinarySync(uri: URI): Uint8Array;
+    stat(uri: URI): Promise<FileSystemNode>;
+    statSync(uri: URI): FileSystemNode;
+    exists(uri: URI): Promise<boolean>;
+    existsSync(uri: URI): boolean;
+    readDirectory(uri: URI): Promise<FileSystemNode[]>;
+    readDirectorySync(uri: URI): FileSystemNode[];
+    /**
+     * The map key for `uri`.
+     *
+     * Exposed for a subclass that mirrors the map into a second store and has to
+     * key it the same way. Deriving a key from `uri.toString()` instead agrees
+     * with this one for every ordinary path and disagrees for exactly the ones
+     * normalisation exists for — a percent-encodable character, a trailing
+     * separator — so the stored entry becomes unfindable in the case nobody
+     * tests.
+     */
+    protected fileKey(uri: URI | string): string;
+    protected hasChildren(path: string): boolean;
+}
+/**
+ * Module fragment binding an {@link InMemoryFileSystemProvider}, spread into the
+ * 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.
+ */
+export declare function inMemoryFileSystem(options?: InMemoryFileSystemOptions): {
+    fileSystemProvider: (services: unknown) => WritableFileSystemProvider;
+};
+//# sourceMappingURL=in-memory-file-system-provider.d.ts.map

package/lib/langium/workspace/in-memory-file-system-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-file-system-provider.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/in-memory-file-system-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,cAAc,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAC1F,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAuB,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAG9F;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9D,qFAAqF;AACrF,MAAM,WAAW,yBAA0B,SAAQ,cAAc;IAC9D,wEAAwE;IACxE,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,0BAA2B,YAAW,0BAA0B;IAKvE,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,2BAA2B;IAJ3D,SAAS,CAAC,QAAQ,CAAC,KAAK,sBAA6B;IACrD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,QAAQ,EAAE,2BAA2B,EACxD,OAAO,GAAE,yBAA8B;IAW1C;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIxC,+DAA+D;IAC/D,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI;IAIpB,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IAInC,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM;IAY9B,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC;IAIzC,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,UAAU;IAIpC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,cAAc,CAAC;IAIvC,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,cAAc;IAWlC,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlC,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO;IAK7B,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAIlD,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,cAAc,EAAE;IAqB7C;;;;;;;;;OASG;IACH,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,MAAM;IAI5C,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAS9C;AAYD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,yBAA8B,GAAG;IAC1E,kBAAkB,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,0BAA0B,CAAC;CACxE,CAIA"}

package/lib/langium/workspace/in-memory-file-system-provider.js

@@ -0,0 +1,195 @@
+/********************************************************************************
+ * 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 { URI } from '@hydranium/langium';
+import { serverSharedFactory } from '../shared-services.js';
+import { serveVirtualDocument } from './virtual-document.js';
+/**
+ * A writable filesystem held in a `Map`, for a host with no disk — a browser
+ * worker, or a test that needs the workspace walk to find real content.
+ *
+ * # Why neither shipped provider stands in
+ *
+ * `DefaultEmptyFileSystemProvider` is genuinely empty (reads throw, writes
+ * are dropped) and the disk-backed one in `@hydranium/core/node` pulls
+ * `node:fs`, which a browser bundle refuses to resolve. A host that means to
+ * open a workspace without a disk needs a third thing: real contents, no
+ * syscalls.
+ *
+ * # It must be typed writable, not merely `FileSystemProvider`
+ *
+ * The `fileSystemProvider` context slot accepts what it is handed only if that
+ * carries `writeFile`; anything narrower is silently replaced by the empty
+ * default, which presents as "the workspace is empty" rather than as a wiring
+ * error. A read-only in-memory provider is therefore not a smaller version of
+ * this one — it is one that does not bind.
+ *
+ * # Directories are implied, never stored
+ *
+ * Only files are held. A directory exists exactly when some file key sits under
+ * it, which is what keeps a write a single `Map.set` with no parent-creation
+ * step to forget. The cost is that an empty directory cannot be represented; the
+ * workspace walk does not need one, and a stored directory set would be a second
+ * source of truth to keep in step with the first.
+ *
+ * # A trailing separator is stripped on every lookup
+ *
+ * Langium spells the workspace root both with and without one depending on which
+ * walk asks, so normalising only where a directory prefix is computed leaves
+ * `stat` and `exists` disagreeing with `readDirectory` about the same folder.
+ *
+ * # What it deliberately does not answer
+ *
+ * No watch notifications, no case-insensitivity, no eviction policy for a
+ * workspace larger than memory. `mtimeMs` and `realpath` are omitted rather than
+ * stubbed, which the framework degrades on by design: the self-save filter lets
+ * the change through and the URI policy keeps the URI it was given.
+ *
+ * Nor does the map outlive the host: every write is lost when the process or the
+ * page goes. `PersistentFileSystemProvider` is the subclass that mirrors
+ * the same writes into an asynchronous backing store, and it is a subclass
+ * rather than an option because the map has to stay the read path either way.
+ */
+export class InMemoryFileSystemProvider {
+    services;
+    files = new Map();
+    tracer;
+    constructor(services, options = {}) {
+        this.services = services;
+        const { seed = {}, rootUri } = options;
+        for (const [path, content] of Object.entries(seed)) {
+            this.files.set(normalize(rootUri === undefined ? path : `${rootUri}/${path}`), content);
+        }
+        this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated', {
+            files: this.files.size
+        });
+    }
+    /**
+     * Replace the content at `uri`, creating it if absent. The synchronous twin
+     * of `writeFile`, for a test that mutates the filesystem between builds
+     * rather than through the server.
+     */
+    setFile(uri, content) {
+        this.files.set(normalize(uri), content);
+    }
+    /** Remove the file at `uri`. A no-op when nothing is there. */
+    deleteFile(uri) {
+        this.files.delete(normalize(uri));
+    }
+    async writeFile(uri, content) {
+        this.setFile(uri, content);
+    }
+    readFile(uri) {
+        return Promise.resolve(this.readFileSync(uri));
+    }
+    readFileSync(uri) {
+        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: ${uri.toString()}`);
+        }
+        return content;
+    }
+    readBinary(uri) {
+        return Promise.resolve(this.readBinarySync(uri));
+    }
+    readBinarySync(uri) {
+        return new TextEncoder().encode(this.readFileSync(uri));
+    }
+    stat(uri) {
+        return Promise.resolve(this.statSync(uri));
+    }
+    statSync(uri) {
+        const path = normalize(uri);
+        if (this.files.has(path)) {
+            return { isFile: true, isDirectory: false, uri };
+        }
+        if (this.hasChildren(path)) {
+            return { isFile: false, isDirectory: true, uri };
+        }
+        throw new Error(`No such file or directory: ${uri.toString()}`);
+    }
+    exists(uri) {
+        return Promise.resolve(this.existsSync(uri));
+    }
+    existsSync(uri) {
+        const path = normalize(uri);
+        return this.files.has(path) || this.hasChildren(path);
+    }
+    readDirectory(uri) {
+        return Promise.resolve(this.readDirectorySync(uri));
+    }
+    readDirectorySync(uri) {
+        const prefix = `${normalize(uri)}/`;
+        const children = new Map();
+        for (const path of this.files.keys()) {
+            if (!path.startsWith(prefix)) {
+                continue;
+            }
+            const remainder = path.slice(prefix.length);
+            const separator = remainder.indexOf('/');
+            const name = separator < 0 ? remainder : remainder.slice(0, separator);
+            if (!children.has(name)) {
+                children.set(name, separator < 0);
+            }
+        }
+        return [...children].map(([name, isFile]) => ({
+            isFile,
+            isDirectory: !isFile,
+            uri: URI.parse(`${prefix}${name}`)
+        }));
+    }
+    /**
+     * The map key for `uri`.
+     *
+     * Exposed for a subclass that mirrors the map into a second store and has to
+     * key it the same way. Deriving a key from `uri.toString()` instead agrees
+     * with this one for every ordinary path and disagrees for exactly the ones
+     * normalisation exists for — a percent-encodable character, a trailing
+     * separator — so the stored entry becomes unfindable in the case nobody
+     * tests.
+     */
+    fileKey(uri) {
+        return normalize(uri);
+    }
+    hasChildren(path) {
+        const prefix = `${path}/`;
+        for (const candidate of this.files.keys()) {
+            if (candidate.startsWith(prefix)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+/**
+ * Key a URI into the file map: parsed so a seeded string and a URI the framework
+ * hands back agree on percent-encoding, then stripped of a trailing separator so
+ * a folder spelled both ways is one entry.
+ */
+function normalize(uri) {
+    const text = typeof uri === 'string' ? URI.parse(uri).toString() : uri.toString();
+    return text.endsWith('/') ? text.slice(0, -1) : text;
+}
+/**
+ * Module fragment binding an {@link InMemoryFileSystemProvider}, spread into the
+ * 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.
+ */
+export function inMemoryFileSystem(options = {}) {
+    return {
+        fileSystemProvider: serverSharedFactory(services => new InMemoryFileSystemProvider(services, options))
+    };
+}
+//# sourceMappingURL=in-memory-file-system-provider.js.map

package/lib/langium/workspace/in-memory-file-system-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-file-system-provider.js","sourceRoot":"","sources":["../../../src/langium/workspace/in-memory-file-system-provider.ts"],"names":[],"mappings":"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"}

package/lib/langium/workspace/index-manager.d.ts

@@ -0,0 +1,142 @@
+/********************************************************************************
+ * 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 declare class HydraniumIndexManager extends DefaultIndexManager {
+    /** Maps `description.name` → list of descriptions with that name. Used for O(1) `getElementByName`. */
+    protected elementsByName: Map<string, AstNodeDescription[]>;
+    protected readonly sharedServices: ServerSharedServicesMinimal;
+    protected readonly tracer: Tracer;
+    constructor(services: ServerSharedServicesMinimal, options?: LogNameOptions);
+    /**
+     * 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;
+    updateContent(document: LangiumDocument, cancelToken?: CancellationToken): Promise<void>;
+    removeContent(uri: URI): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Turn an `AstNodeDescription` into the actual `AstNode` via the language-specific `AstNodeLocator`. */
+    resolveElement(description?: AstNodeDescription): AstNode | undefined;
+    /** Compose {@link getElementByName} with {@link resolveElement}. */
+    resolveElementByName(name: string, type?: string, languageId?: string): AstNode | undefined;
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * 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;
+}
+//# sourceMappingURL=index-manager.d.ts.map

package/lib/langium/workspace/index-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-manager.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/index-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,kBAAkB,EAAE,mBAAmB,EAAE,KAAK,eAAe,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAChI,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,qBAAsB,SAAQ,mBAAmB;IAC3D,uGAAuG;IACvG,SAAS,CAAC,cAAc,oCAA2C;IAEnE,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,2BAA2B,CAAC;IAC/D,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEtB,QAAQ,EAAE,2BAA2B,EAAE,OAAO,GAAE,cAAmB;IAM/E;;;;;;OAMG;IACH,SAAS,KAAK,cAAc,IAAI,cAAc,CAE7C;IAMc,aAAa,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9F,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI;IAKtC;;;;OAIG;IACH,SAAS,CAAC,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAmBxD;;;;OAIG;IACH,SAAS,CAAC,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAmBnD;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,kBAAkB,EAAE;IAYlG;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIlG;;;;;;;;;OASG;IACH,SAAS,CAAC,YAAY,CAAC,WAAW,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS;IAI5D,yGAAyG;IACzG,cAAc,CAAC,WAAW,CAAC,EAAE,kBAAkB,GAAG,OAAO,GAAG,SAAS;IAYrE,oEAAoE;IACpE,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAI3F;;;;;;;;;;;OAWG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAwB5E;;;;;;OAMG;IACH,sBAAsB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,GAAG,SAAS;IAQrD;;;OAGG;IACH,SAAS,CAAC,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,GAAG,SAAS;CAG5E"}