@hydranium/core 1.0.0-next.10

package/lib/langium/build-phase-pass/build-phase-pass-service.js

@@ -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 { Logger } from '@hydranium/protocol';
+import { DocumentState } from '@hydranium/langium';
+import { Registry } from '../../util/registry.js';
+/**
+ * Default {@link BuildPhasePassService}. Generic registry for batch-level
+ * build-phase work, the `onBuildPhase` sibling of
+ * `DefaultAstExtensionService`
+ * (which is per-node, `onDocumentPhase`). This class owns the registry +
+ * priority-ordered dispatch; the listener lifecycle lives in
+ * `BuildPipelineIntegration`,
+ * which calls {@link runPasses} from its `onBuildPhase` listeners.
+ *
+ * **Performance:** {@link runPasses} shares the bucket-by-state cache pattern
+ * with the AST-extension service — the per-state pass list is rebuilt lazily
+ * only after a register / unregister, so steady-state dispatch allocates
+ * nothing and early-outs when no pass targets the phase.
+ *
+ * **Profiling:** mirrors the AST-extension / integrity idiom — a debug-gated
+ * `ProfileSession` scopes each pass by its
+ * `id`, so `report('debug')` emits one self-time line per pass. At the default
+ * `info` level no session is allocated.
+ */
+export class DefaultBuildPhasePassService {
+    passes = new Registry();
+    /** Per-state bucket of passes targeting each state, rebuilt lazily on the first run after a registry mutation. */
+    stateBuckets = new Map();
+    stateBucketsFor;
+    tracer;
+    constructor(services, options = {}) {
+        this.tracer = services.Tracer.for(options.logName ?? 'BuildPhasePass').trace('instantiated');
+        // Read the shared `buildPhasePasses` contribution group and let each
+        // contribution register one or many passes through this service. The `??`
+        // fallback tolerates incomplete test stubs; production wiring provides the
+        // slot via `createServerSharedModule` + adopter modules.
+        const contributions = services.buildPhasePasses ?? {};
+        for (const contribution of Object.values(contributions)) {
+            contribution.registerBuildPhasePasses(this);
+        }
+    }
+    register(pass) {
+        return this.passes.register(pass);
+    }
+    async runPasses(documents, phase, cancelToken) {
+        const bucket = this.getStateBucket(phase);
+        if (bucket.length === 0) {
+            return;
+        }
+        // Per-pass self-time profiling is opt-in: only open a session when the
+        // debug threshold is active, so the production path allocates nothing and
+        // the dispatch loop stays a single const-branch off `session`.
+        const session = Logger.isLevelEnabled('debug') ? this.tracer.profile(`build-phase-pass ${DocumentState[phase]}`) : undefined;
+        for (const pass of bucket) {
+            if (cancelToken.isCancellationRequested) {
+                break;
+            }
+            // Scope per pass id so the session aggregates self-time by pass across
+            // the phase; off the profiling path call directly. `scope` awaits an
+            // async `run`, so timing covers the full settle.
+            if (session) {
+                await session.scope(pass.id, () => pass.run(documents, cancelToken));
+            }
+            else {
+                await pass.run(documents, cancelToken);
+            }
+        }
+        // One line per pass (count + self-% + self-ms), sorted — only when profiling.
+        session?.report('debug');
+    }
+    /**
+     * Bucket-by-state view of {@link passes}, rebuilt lazily when the registry's
+     * cached `all()` reference changes. Each bucket preserves the registry's
+     * priority order (`Registry.all()` is already priority-sorted).
+     */
+    getStateBucket(phase) {
+        const current = this.passes.all();
+        if (this.stateBucketsFor !== current) {
+            const next = new Map();
+            for (const pass of current) {
+                let bucket = next.get(pass.state);
+                if (!bucket) {
+                    bucket = [];
+                    next.set(pass.state, bucket);
+                }
+                bucket.push(pass);
+            }
+            this.stateBuckets = next;
+            this.stateBucketsFor = current;
+        }
+        return this.stateBuckets.get(phase) ?? EMPTY_STATE_BUCKET;
+    }
+}
+/** Shared empty result so `getStateBucket` doesn't allocate per call on the cold path. */
+const EMPTY_STATE_BUCKET = Object.freeze([]);
+//# sourceMappingURL=build-phase-pass-service.js.map

package/lib/langium/build-phase-pass/build-phase-pass-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-phase-pass-service.js","sourceRoot":"","sources":["../../../src/langium/build-phase-pass/build-phase-pass-service.ts"],"names":[],"mappings":"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"}

package/lib/langium/build-phase-pass/build-phase-pass.d.ts

@@ -0,0 +1,106 @@
+/********************************************************************************
+ * 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 DocumentState, type LangiumCoreServices, type LangiumDocument, type URI } from '@hydranium/langium';
+import { type CancellationToken, type Disposable } from 'vscode-languageserver';
+import { type RegistryItem } from '../../util/registry.js';
+/**
+ * A unit of whole-batch work run once per build when the batch reaches a
+ * declared build phase, ordered by {@link RegistryItem.priority}.
+ *
+ * **Granularity.** This is the batch-level (`documents[]`) sibling of the
+ * node-level registries `AstExtension` (per node, `onDocumentPhase`) and
+ * `IntegrityRule` (per node, dispatched from a framework-registered pass of this
+ * kind). A `BuildPhasePass` rides Langium's native `onBuildPhase` signature
+ * directly — it is handed the whole built batch and owns its own walk, for work
+ * that needs cross-document ordering, rather than having the framework drive a
+ * per-node `streamAllContents` walk.
+ *
+ * **Ordering.** {@link RegistryItem.priority} orders passes WITHIN one phase,
+ * never across phases, because each phase has its own bucket. Lower runs first;
+ * ties break by registration order. Passes in a bucket run sequentially — each
+ * is awaited before the next begins. This is the framework's single declared
+ * insertion point for build-phase work: an adopter pass that must run after a
+ * framework pass declares a higher priority instead of relying on DI
+ * construction order.
+ *
+ * **Priority bands.** `priority` defaults to `0` ({@link RegistryItem.priority}).
+ * The framework reserves NEGATIVE priorities for *foundational* passes that must
+ * precede adopter work regardless of registration order — notably integrity
+ * (`INTEGRITY_PASS_PRIORITY`), which cleans/mutates the AST every derived-state
+ * pass reads. Adopter passes therefore use `0` or higher, which puts them after
+ * the foundational band without declaring anything; chained adopter passes order
+ * among themselves with increasing values. Adopters do NOT need a negative
+ * priority — that band is the framework's.
+ *
+ * **Async + cancellation.** {@link run} may be sync or async; an async pass is
+ * awaited so the next pass sees its full effect. The dispatcher checks the
+ * cancel token before each pass, so a build preempted mid-phase stops cleanly
+ * rather than running the remaining passes against a doomed build.
+ */
+export interface BuildPhasePass extends RegistryItem {
+    /**
+     * The single build phase whose `onBuildPhase` fires this pass. The framework
+     * wires a listener for the same phase set as AST extension; a pass declaring
+     * any other state type-checks but never fires.
+     */
+    state: DocumentState;
+    /**
+     * Run this pass against the whole built batch. May mutate and reparse
+     * documents — the framework's integrity pass does — or derive cross-document
+     * state. Honour `cancelToken` for long walks; the dispatcher already checks
+     * it between passes.
+     */
+    run(documents: readonly LangiumDocument[], cancelToken: CancellationToken): void | Promise<void>;
+}
+/**
+ * Group a build batch by the language that owns each document, preserving the
+ * batch's order within each group.
+ *
+ * **Why a pass needs this.** A {@link BuildPhasePass} is handed the whole batch
+ * with no language dimension — unlike its node-level siblings `AstExtension`
+ * and `IntegrityRule`, which the framework resolves per document before calling
+ * them. In a single-grammar workspace that difference is invisible. In a
+ * multi-grammar one, a pass that reaches for `services.language.<anything>`
+ * silently applies the FIRST language's services to every document in the
+ * batch, including documents of the other grammar; nothing errors, and the
+ * result is derived state computed against the wrong grammar's rules.
+ *
+ * Documents whose URI matches no registered language are omitted — a pass
+ * cannot meaningfully run a language's services over them, and throwing would
+ * fail the whole build over one stray URI.
+ */
+export declare function groupDocumentsByLanguage<TLanguage extends LangiumCoreServices>(services: {
+    ServiceRegistry: {
+        hasServices(uri: URI): boolean;
+        getServices(uri: URI): TLanguage;
+    };
+}, documents: readonly LangiumDocument[]): Map<TLanguage, LangiumDocument[]>;
+/**
+ * Registry handed to a {@link BuildPhasePassContribution}. Implemented by the
+ * `BuildPhasePassService`; doubles
+ * as the low-level imperative API the framework uses to self-register its own
+ * passes (integrity, the Langium profiler flush).
+ */
+export interface BuildPhasePassRegistry {
+    register(pass: BuildPhasePass): Disposable;
+}
+/**
+ * Declarative registration of build-phase passes. Bound under the shared
+ * module's `buildPhasePasses` contribution group; the
+ * `BuildPhasePassService` reads its
+ * own group at construction and calls this method, handing itself in as the
+ * registry.
+ *
+ * The domain-qualified method name lets a single cross-cutting class implement
+ * several contribution interfaces without method collision.
+ */
+export interface BuildPhasePassContribution {
+    registerBuildPhasePasses(registry: BuildPhasePassRegistry): void;
+}
+//# sourceMappingURL=build-phase-pass.d.ts.map

package/lib/langium/build-phase-pass/build-phase-pass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-phase-pass.d.ts","sourceRoot":"","sources":["../../../src/langium/build-phase-pass/build-phase-pass.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,mBAAmB,EAAE,KAAK,eAAe,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAClH,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,cAAe,SAAQ,YAAY;IACjD;;;;OAIG;IACH,KAAK,EAAE,aAAa,CAAC;IACrB;;;;;OAKG;IACH,GAAG,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,EAAE,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,SAAS,mBAAmB,EAC3E,QAAQ,EAAE;IAAE,eAAe,EAAE;QAAE,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC;QAAC,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,SAAS,CAAA;KAAE,CAAA;CAAE,EACnG,SAAS,EAAE,SAAS,eAAe,EAAE,GACrC,GAAG,CAAC,SAAS,EAAE,eAAe,EAAE,CAAC,CAenC;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACpC,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CAAC;CAC7C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,0BAA0B;IACxC,wBAAwB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI,CAAC;CACnE"}

package/lib/langium/build-phase-pass/build-phase-pass.js

@@ -0,0 +1,43 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Group a build batch by the language that owns each document, preserving the
+ * batch's order within each group.
+ *
+ * **Why a pass needs this.** A {@link BuildPhasePass} is handed the whole batch
+ * with no language dimension — unlike its node-level siblings `AstExtension`
+ * and `IntegrityRule`, which the framework resolves per document before calling
+ * them. In a single-grammar workspace that difference is invisible. In a
+ * multi-grammar one, a pass that reaches for `services.language.<anything>`
+ * silently applies the FIRST language's services to every document in the
+ * batch, including documents of the other grammar; nothing errors, and the
+ * result is derived state computed against the wrong grammar's rules.
+ *
+ * Documents whose URI matches no registered language are omitted — a pass
+ * cannot meaningfully run a language's services over them, and throwing would
+ * fail the whole build over one stray URI.
+ */
+export function groupDocumentsByLanguage(services, documents) {
+    const grouped = new Map();
+    for (const document of documents) {
+        if (!services.ServiceRegistry.hasServices(document.uri)) {
+            continue;
+        }
+        const language = services.ServiceRegistry.getServices(document.uri);
+        const group = grouped.get(language);
+        if (group) {
+            group.push(document);
+        }
+        else {
+            grouped.set(language, [document]);
+        }
+    }
+    return grouped;
+}
+//# sourceMappingURL=build-phase-pass.js.map

package/lib/langium/build-phase-pass/build-phase-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-phase-pass.js","sourceRoot":"","sources":["../../../src/langium/build-phase-pass/build-phase-pass.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAwDlF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,wBAAwB,CACrC,QAAmG,EACnG,SAAqC;IAErC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAgC,CAAC;IACxD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACvD,SAAS;QACZ,CAAC;QACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,eAAe,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACpE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACpC,IAAI,KAAK,EAAE,CAAC;YACT,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxB,CAAC;aAAM,CAAC;YACL,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;QACrC,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AAClB,CAAC"}

package/lib/langium/build-phase-pass/index.d.ts

@@ -0,0 +1,11 @@
+/********************************************************************************
+ * 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 './build-phase-pass.js';
+export * from './build-phase-pass-service.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/langium/build-phase-pass/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/langium/build-phase-pass/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC"}

package/lib/langium/build-phase-pass/index.js

@@ -0,0 +1,11 @@
+/********************************************************************************
+ * 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 './build-phase-pass.js';
+export * from './build-phase-pass-service.js';
+//# sourceMappingURL=index.js.map

package/lib/langium/build-phase-pass/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/langium/build-phase-pass/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC"}

package/lib/langium/config/index.d.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 './settings.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/langium/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/langium/config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,eAAe,CAAC"}

package/lib/langium/config/index.js

@@ -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 './settings.js';
+//# sourceMappingURL=index.js.map

package/lib/langium/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/langium/config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,eAAe,CAAC"}

package/lib/langium/config/settings.d.ts

@@ -0,0 +1,173 @@
+/********************************************************************************
+ * 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 ObservableValue } from '@hydranium/protocol';
+import { type ServerSharedServices } from '../module.js';
+/** True only when `T` is exactly `unknown` (distinguishing it from `any`). */
+type IsUnknown<T> = unknown extends T ? ([T] extends [never] ? false : T extends never ? false : true) : false;
+/**
+ * Union of valid path tuples through `T` — manually unrolled to four levels
+ * (TS conditional-type recursion saturates around depth 5 and trips
+ * "instantiation excessively deep" through generic helpers). LSP config trees
+ * are almost always <= 3 levels in practice.
+ */
+type Path<T> = T extends object ? {
+    [K in keyof T & string]: NonNullable<T[K]> extends object ? readonly [K] | readonly [K, ...Extract<PathL2<NonNullable<T[K]>>, readonly string[]>] : readonly [K];
+}[keyof T & string] : never;
+type PathL2<T> = T extends object ? {
+    [K in keyof T & string]: NonNullable<T[K]> extends object ? readonly [K] | readonly [K, ...Extract<PathL3<NonNullable<T[K]>>, readonly string[]>] : readonly [K];
+}[keyof T & string] : never;
+type PathL3<T> = T extends object ? {
+    [K in keyof T & string]: NonNullable<T[K]> extends object ? readonly [K] | readonly [K, ...Extract<PathL4<NonNullable<T[K]>>, readonly string[]>] : readonly [K];
+}[keyof T & string] : never;
+type PathL4<T> = T extends object ? {
+    [K in keyof T & string]: readonly [K];
+}[keyof T & string] : never;
+/**
+ * Producers that bind a user-configurable editor setting (an LSP
+ * `workspace/configuration` section) to an {@link ObservableValue} — the
+ * snapshot updates on the initial fetch and on every `didChangeConfiguration`
+ * push for the section. `Settings` is reserved for this user-config source;
+ * the {@link ObservableValue} the producers yield is itself source-agnostic.
+ */
+export declare namespace Settings {
+    /** Accepted `key` shape for a given `TConfig` (top-level key or nested path tuple). */
+    type Key<TConfig> = IsUnknown<TConfig> extends true ? string | readonly string[] : (keyof TConfig & string) | Path<TConfig>;
+    /**
+     * Construction options for {@link Settings.value}. The two-key shape
+     * (`root` + `configuration`) mirrors Langium's
+     * `ConfigurationProvider.getConfiguration(language, configuration)`: `root`
+     * selects the top-level section (typically the language id), `configuration`
+     * is the first-level key beneath it, and `select` does the deep traversal.
+     */
+    interface ValueOptions<TConfig, TValue> {
+        readonly services: ServerSharedServices;
+        /**
+         * LSP configuration section root. Defaults to
+         * `services.lsp.configurationRoot`; multi-grammar adopters rebind that
+         * slot to dispatch by language id. Single-grammar adopters rarely pass it.
+         */
+        readonly root?: string;
+        /** First-level key under `root` (NOT a dotted path — Langium semantics). */
+        readonly configuration: string;
+        /**
+         * Default returned until the first fetch completes, and afterwards when
+         * the configuration is absent or `select` returns `undefined` / `null`.
+         */
+        readonly default: TValue;
+        /**
+         * Deep-traverse the subtree returned by `getConfiguration(root,
+         * configuration)`. Returns the typed `TValue`, or `undefined` / `null` /
+         * throws to fall back to {@link ValueOptions.default}.
+         */
+        readonly select: (config: TConfig) => TValue | undefined | null;
+    }
+    /**
+     * Bind a {@link ObservableValue} to a Langium configuration section. The
+     * snapshot starts at `default` and updates when (a) the initial
+     * `provider.getConfiguration` resolves and (b) every `didChangeConfiguration`
+     * push affecting the same `root`. `onChange` is dedup'd by snapshot identity
+     * (`Object.is`). Errors thrown by `select` fall back to `default`.
+     */
+    function value<TConfig, TValue>(options: ValueOptions<TConfig, TValue>): ObservableValue<TValue>;
+    /**
+     * Common options shared by the typed readers ({@link Settings.number},
+     * {@link Settings.boolean}, {@link Settings.string}). Each binds a value at
+     * `<root>.<configuration>.<key>`. `default` is returned whenever the
+     * configuration is absent, the raw value is the wrong shape, or coercion /
+     * validation rejects it.
+     */
+    interface ReaderOptions<T, TConfig = unknown> {
+        readonly services: ServerSharedServices;
+        readonly root?: string;
+        readonly configuration: string;
+        /**
+         * Key or path inside the `configuration` subtree. Narrows to the valid
+         * paths through `TConfig` when a schema is declared; otherwise
+         * `string | readonly string[]`.
+         */
+        readonly key: Key<TConfig>;
+        readonly default: T;
+    }
+    /** Options for {@link Settings.number}. */
+    interface NumberOptions<TConfig = unknown> extends ReaderOptions<number, TConfig> {
+        /** Coerce string-typed values via `Number.parseFloat`. Default: `true`. */
+        readonly coerceString?: boolean;
+        /** Reject negative values. Default: `false`. */
+        readonly nonNegative?: boolean;
+        /** Round to the nearest integer via `Math.round`. Default: `false`. */
+        readonly integer?: boolean;
+        /** Reject values below `min`. */
+        readonly min?: number;
+        /** Reject values above `max`. */
+        readonly max?: number;
+    }
+    /** Options for {@link Settings.boolean}. */
+    interface BooleanOptions<TConfig = unknown> extends ReaderOptions<boolean, TConfig> {
+        /** Coerce `'true'`/`'false'`/`'1'`/`'0'` (case-insensitive). Default: `true`. */
+        readonly coerceString?: boolean;
+    }
+    /** Options for {@link Settings.string}. */
+    interface StringOptions<T extends string = string, TConfig = unknown> extends ReaderOptions<T, TConfig> {
+        /** Restrict accepted values to a set. */
+        readonly allowed?: readonly T[];
+        /** Coerce non-string values via `String(value)`. Off by default. */
+        readonly coerceToString?: boolean;
+    }
+    /**
+     * Bind a numeric setting with optional string-coercion + range / integer
+     * validation. Any rejection falls back to `default`.
+     */
+    function number<TConfig = unknown>(options: NumberOptions<TConfig>): ObservableValue<number>;
+    /**
+     * Bind a boolean setting with optional string-coercion (`'true'`/`'false'`/
+     * `'1'`/`'0'`, case-insensitive). Any other shape falls back to `default`.
+     */
+    function boolean<TConfig = unknown>(options: BooleanOptions<TConfig>): ObservableValue<boolean>;
+    /**
+     * Bind a string setting with optional non-string coercion + allowed-list
+     * validation. Type-parameterise `T` to a literal-string union to correlate
+     * the snapshot type with the `allowed` set at compile time.
+     */
+    function string<T extends string = string, TConfig = unknown>(options: StringOptions<T, TConfig>): ObservableValue<T>;
+}
+/** Standard LSP message-tracing verbosity — the value of the `<langId>.trace.server` setting. */
+export type TraceServerValue = 'off' | 'messages' | 'verbose';
+/**
+ * Shape of the standard `<langId>.trace` configuration section — `trace.server`
+ * selects message-tracing verbosity. The framework owns this type because,
+ * unlike bespoke per-adopter settings, it is universal across LSP adopters: a
+ * server reads it through {@link Settings.string} without re-declaring the
+ * shape, and gets an {@link ObservableValue} that tracks the user's edits.
+ *
+ * **A server usually has nothing to read here, which is why this type has no
+ * in-repo consumer.** The setting is the CLIENT's: `vscode-languageclient`
+ * reads `<clientId>.trace.server` itself, re-reads it on every configuration
+ * change, writes the protocol trace to its own output channel, and forwards the
+ * value to the server as the dedicated `$/setTrace` notification. So the value
+ * already reaches a server on its own channel; going through
+ * `workspace/configuration` is the indirect route to the same thing, and
+ * nothing here registers a `$/setTrace` handler either.
+ *
+ * The one case that wants this type is a server choosing to mirror trace
+ * verbosity onto its own `LogThreshold`. Weigh that deliberately rather than by
+ * analogy: message tracing and application logging are orthogonal axes, so
+ * mirroring means protocol tracing cannot be enabled without also raising
+ * application log volume. The similar spelling is a false friend —
+ * `trace.server: 'verbose'` and `LogThreshold`'s `'trace'` are unrelated.
+ *
+ * The client library does NOT contribute the schema. An adopter that wants the
+ * setting to be discoverable declares it in its own host manifest
+ * (`contributes.configuration`); in Theia that is not merely cosmetic, because
+ * an unregistered preference is dropped as unknown rather than returned.
+ */
+export interface LspTraceConfiguration {
+    server?: TraceServerValue;
+}
+export {};
+//# sourceMappingURL=settings.d.ts.map

package/lib/langium/config/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../src/langium/config/settings.ts"],"names":[],"mappings":"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"}