@hydranium/core 1.0.0-next.10

package/lib/langium/validation/document-validator.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 LogThreshold, type MaybeObservableValue, ObservableValue, type Tracer } from '@hydranium/protocol';
+import { type AstNode, type AstNodeLocator, DefaultDocumentValidator, type DiagnosticInfo, type LangiumDocument, type LangiumCoreServices, type ValidateSingleNodeOptions, type ValidationOptions, type ValidationSeverity } from '@hydranium/langium';
+import type { CancellationToken } from 'vscode-languageserver-protocol';
+import type { Diagnostic } from 'vscode-languageserver-types';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+/**
+ * Diagnostic shape produced by {@link HydraniumDocumentValidator}: an LSP
+ * {@link Diagnostic} extended with the protocol-level `element` path and
+ * optional `property` name from {@link TransferDiagnostic}.
+ */
+export interface TransferLspDiagnostic extends Diagnostic {
+    element: string;
+    property?: string;
+}
+export interface DocumentValidatorOptions extends LogNameOptions {
+    /**
+     * Level at which the `validateDocument` timing line is emitted, or `'off'`
+     * to disable the timing wrap entirely. Default: `'debug'`. Read per call, so
+     * it accepts a {@link MaybeObservableValue} — pass a constant or bind it to a
+     * user setting (via the `Settings` namespace) to retune live.
+     */
+    readonly logLevel?: MaybeObservableValue<LogThreshold>;
+    /**
+     * Suppress the timing line for validation runs shorter than this. Default:
+     * `20`ms. Read per call; accepts a {@link MaybeObservableValue}.
+     */
+    readonly logAfterMs?: MaybeObservableValue<number>;
+    /**
+     * Validate documents under the virtual URI scheme (see `isVirtualUri`).
+     * Default `false`: virtual documents (stdlib / library / built-in content)
+     * are skipped, because a virtual URI cannot be opened, so a diagnostic on it
+     * is un-actionable, and shipped library content is presumed correct. Set
+     * `true` to validate built-in definitions. Read per call, so it accepts a
+     * {@link MaybeObservableValue} — bind it to a user setting to toggle live.
+     */
+    readonly validateVirtualDocuments?: MaybeObservableValue<boolean>;
+    /**
+     * Validate nodes marked synthetic via `markSynthetic` (see `isSyntheticNode`).
+     * Default `false`: synthetic nodes (stdlib content, projection mirrors) are
+     * skipped, so a mirror never double-reports an error owned by its real
+     * declaration. Set `true` to validate them normally. Read per call, so it
+     * accepts a {@link MaybeObservableValue}.
+     */
+    readonly validateSyntheticNodes?: MaybeObservableValue<boolean>;
+}
+/**
+ * Default validator behaviour for `@hydranium/core` consumers:
+ *
+ * - **Skip-validation hook** via the virtual {@link shouldSkipValidation}
+ *   predicate, which adopters override to compose additional skip reasons.
+ * - **Diagnostic mapping** to {@link TransferDiagnostic}-shaped
+ *   {@link TransferLspDiagnostic}: every emitted diagnostic carries the AST
+ *   node's path (built via Langium's `AstNodeLocator`) plus the optional
+ *   offending property name.
+ * - **Optional timing wrap** on `validateDocument`, on by default.
+ */
+export declare class HydraniumDocumentValidator extends DefaultDocumentValidator {
+    protected readonly tracer: Tracer;
+    protected readonly astNodeLocator: AstNodeLocator;
+    protected readonly logLevel: ObservableValue<LogThreshold>;
+    protected readonly logAfterMs: ObservableValue<number>;
+    protected readonly validateVirtualDocuments: ObservableValue<boolean>;
+    protected readonly validateSyntheticNodes: ObservableValue<boolean>;
+    constructor(services: LangiumCoreServices & {
+        shared: {
+            Tracer: Tracer;
+        };
+    }, options?: DocumentValidatorOptions);
+    validateDocument(document: LangiumDocument, options?: ValidationOptions, cancelToken?: CancellationToken): Promise<Diagnostic[]>;
+    /**
+     * Skip validation for a node **and its children** when
+     * {@link shouldSkipValidation} returns true.
+     */
+    protected validateSingleNodeOptions(node: AstNode, options: ValidationOptions): ValidateSingleNodeOptions;
+    /**
+     * True when validation should skip `node` and its children. Default: the
+     * node is marked synthetic ({@link isSyntheticNode}) and
+     * {@link DocumentValidatorOptions.validateSyntheticNodes} has not opted back
+     * in — so the option and the predicate are one decision, not two. Adopters
+     * override to compose additional skip reasons with
+     * `super.shouldSkipValidation(node) || ...`.
+     */
+    protected shouldSkipValidation(node: AstNode): boolean;
+    protected toDiagnostic<N extends AstNode>(severity: ValidationSeverity, message: string, info: DiagnosticInfo<N, string>): TransferLspDiagnostic;
+    /**
+     * Construct the `element` path for a diagnostic. Falls back through:
+     * - the node's own AST path, then
+     * - the parent's AST path (for nodes Langium can't locate directly, e.g.
+     *   references or transient nodes).
+     *
+     * When the path doesn't include the array index (some reference-array
+     * cases) but `info.index` is provided, the index is appended explicitly
+     * — keeping element paths stable and consistent with how the client
+     * expects collection-item paths to be formed.
+     */
+    protected buildElementPath<N extends AstNode>(node: N, info: DiagnosticInfo<N, string>): string;
+}
+//# sourceMappingURL=document-validator.d.ts.map

package/lib/langium/validation/document-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-validator.d.ts","sourceRoot":"","sources":["../../../src/langium/validation/document-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,oBAAoB,EAAE,eAAe,EAAE,KAAK,MAAM,EAAsB,MAAM,qBAAqB,CAAC;AACrI,OAAO,EACJ,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,wBAAwB,EACxB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,UAAU;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,wBAAyB,SAAQ,cAAc;IAC7D;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC,YAAY,CAAC,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;IACnD;;;;;;;OAOG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAClE;;;;;;OAMG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC;CAClE;AAED;;;;;;;;;;GAUG;AACH,qBAAa,0BAA2B,SAAQ,wBAAwB;IACrE,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IAClD,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;IAC3D,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IACvD,SAAS,CAAC,QAAQ,CAAC,wBAAwB,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IACtE,SAAS,CAAC,QAAQ,CAAC,sBAAsB,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;gBAExD,QAAQ,EAAE,mBAAmB,GAAG;QAAE,MAAM,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,EAAE,OAAO,GAAE,wBAA6B;IAUzG,gBAAgB,CACtB,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,iBAAiB,EAC3B,WAAW,CAAC,EAAE,iBAAiB,GAC/B,OAAO,CAAC,UAAU,EAAE,CAAC;IAqBxB;;;OAGG;cACgB,yBAAyB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,GAAG,yBAAyB;IAOlH;;;;;;;OAOG;IACH,SAAS,CAAC,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO;cAInC,YAAY,CAAC,CAAC,SAAS,OAAO,EAC9C,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,cAAc,CAAC,CAAC,EAAE,MAAM,CAAC,GAC/B,qBAAqB;IAWxB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,gBAAgB,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,MAAM;CAejG"}

package/lib/langium/validation/document-validator.js

@@ -0,0 +1,118 @@
+/********************************************************************************
+ * 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 { ObservableValue, TransferDiagnostic } from '@hydranium/protocol';
+import { DefaultDocumentValidator } from '@hydranium/langium';
+import { isSyntheticNode } from '../workspace/synthetic.js';
+import { isVirtualUri } from '../workspace/virtual-document.js';
+/**
+ * Default validator behaviour for `@hydranium/core` consumers:
+ *
+ * - **Skip-validation hook** via the virtual {@link shouldSkipValidation}
+ *   predicate, which adopters override to compose additional skip reasons.
+ * - **Diagnostic mapping** to {@link TransferDiagnostic}-shaped
+ *   {@link TransferLspDiagnostic}: every emitted diagnostic carries the AST
+ *   node's path (built via Langium's `AstNodeLocator`) plus the optional
+ *   offending property name.
+ * - **Optional timing wrap** on `validateDocument`, on by default.
+ */
+export class HydraniumDocumentValidator extends DefaultDocumentValidator {
+    tracer;
+    astNodeLocator;
+    logLevel;
+    logAfterMs;
+    validateVirtualDocuments;
+    validateSyntheticNodes;
+    constructor(services, options = {}) {
+        super(services);
+        this.tracer = services.shared.Tracer.for(options.logName ?? 'DocumentValidator').trace('instantiated');
+        this.astNodeLocator = services.workspace.AstNodeLocator;
+        this.logLevel = ObservableValue.from(options.logLevel ?? 'debug');
+        this.logAfterMs = ObservableValue.from(options.logAfterMs ?? 20);
+        this.validateVirtualDocuments = ObservableValue.from(options.validateVirtualDocuments ?? false);
+        this.validateSyntheticNodes = ObservableValue.from(options.validateSyntheticNodes ?? false);
+    }
+    validateDocument(document, options, cancelToken) {
+        // Skip whole virtual documents (stdlib / library / built-in) unless opted
+        // in — a virtual URI cannot be opened, so diagnostics on it are
+        // un-actionable. Decided per document (not per node) so the walk is
+        // avoided entirely; the per-node `$synthetic` skip is separate.
+        if (isVirtualUri(document.uri) && !this.validateVirtualDocuments.value) {
+            this.tracer.withUri(document.uri.toString()).debug('skipping validation (virtual document)');
+            return Promise.resolve([]);
+        }
+        const level = this.logLevel.value;
+        if (level === 'off') {
+            return super.validateDocument(document, options, cancelToken);
+        }
+        // `level` is narrowed to `LogLevel` past the early-return.
+        return this.tracer
+            .withUri(document.uri.toString())
+            .time('validateDocument', () => super.validateDocument(document, options, cancelToken), level, {
+            logAfterMs: this.logAfterMs.value
+        });
+    }
+    /**
+     * Skip validation for a node **and its children** when
+     * {@link shouldSkipValidation} returns true.
+     */
+    validateSingleNodeOptions(node, options) {
+        if (this.shouldSkipValidation(node)) {
+            return { validateNode: false, validateChildren: false };
+        }
+        return super.validateSingleNodeOptions(node, options);
+    }
+    /**
+     * True when validation should skip `node` and its children. Default: the
+     * node is marked synthetic ({@link isSyntheticNode}) and
+     * {@link DocumentValidatorOptions.validateSyntheticNodes} has not opted back
+     * in — so the option and the predicate are one decision, not two. Adopters
+     * override to compose additional skip reasons with
+     * `super.shouldSkipValidation(node) || ...`.
+     */
+    shouldSkipValidation(node) {
+        return !this.validateSyntheticNodes.value && isSyntheticNode(node);
+    }
+    toDiagnostic(severity, message, info) {
+        const base = super.toDiagnostic(severity, message, info);
+        const node = info.node;
+        if (!node) {
+            this.tracer.warn('Cannot create diagnostic element path: DiagnosticInfo has no node.');
+            return { ...base, property: info.property, element: '' };
+        }
+        const elementPath = this.buildElementPath(node, info);
+        return { ...base, property: info.property, element: elementPath };
+    }
+    /**
+     * Construct the `element` path for a diagnostic. Falls back through:
+     * - the node's own AST path, then
+     * - the parent's AST path (for nodes Langium can't locate directly, e.g.
+     *   references or transient nodes).
+     *
+     * When the path doesn't include the array index (some reference-array
+     * cases) but `info.index` is provided, the index is appended explicitly
+     * — keeping element paths stable and consistent with how the client
+     * expects collection-item paths to be formed.
+     */
+    buildElementPath(node, info) {
+        const directPath = this.astNodeLocator.getAstNodePath(node);
+        const containerPath = directPath ? undefined : this.astNodeLocator.getAstNodePath(node.$container ?? { $type: 'Dummy' });
+        const nodePath = directPath || containerPath;
+        if (!nodePath) {
+            this.tracer.warn('Cannot create diagnostic element path: Unable to determine AST node path.');
+            return '';
+        }
+        if (info.index === undefined || nodePath.endsWith(`${TransferDiagnostic.ELEMENT_INDEX_SEPARATOR}${info.index}`)) {
+            return nodePath;
+        }
+        return info.property
+            ? `${nodePath}${TransferDiagnostic.ELEMENT_SEGMENT_SEPARATOR}${info.property}${TransferDiagnostic.ELEMENT_INDEX_SEPARATOR}${info.index}`
+            : `${nodePath}${TransferDiagnostic.ELEMENT_INDEX_SEPARATOR}${info.index}`;
+    }
+}
+//# sourceMappingURL=document-validator.js.map

package/lib/langium/validation/document-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-validator.js","sourceRoot":"","sources":["../../../src/langium/validation/document-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAgD,eAAe,EAAe,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACrI,OAAO,EAGJ,wBAAwB,EAO1B,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AA4ChE;;;;;;;;;;GAUG;AACH,MAAM,OAAO,0BAA2B,SAAQ,wBAAwB;IAClD,MAAM,CAAS;IACf,cAAc,CAAiB;IAC/B,QAAQ,CAAgC;IACxC,UAAU,CAA0B;IACpC,wBAAwB,CAA2B;IACnD,sBAAsB,CAA2B;IAEpE,YAAY,QAA8D,EAAE,UAAoC,EAAE;QAC/G,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChB,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,mBAAmB,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACvG,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC,SAAS,CAAC,cAAc,CAAC;QACxD,IAAI,CAAC,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,CAAC;QAClE,IAAI,CAAC,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;QACjE,IAAI,CAAC,wBAAwB,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,wBAAwB,IAAI,KAAK,CAAC,CAAC;QAChG,IAAI,CAAC,sBAAsB,GAAG,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,sBAAsB,IAAI,KAAK,CAAC,CAAC;IAC/F,CAAC;IAEQ,gBAAgB,CACtB,QAAyB,EACzB,OAA2B,EAC3B,WAA+B;QAE/B,0EAA0E;QAC1E,gEAAgE;QAChE,oEAAoE;QACpE,gEAAgE;QAChE,IAAI,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,wBAAwB,CAAC,KAAK,EAAE,CAAC;YACtE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;YAC7F,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9B,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAClC,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;YACnB,OAAO,KAAK,CAAC,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;QACjE,CAAC;QACD,2DAA2D;QAC3D,OAAO,IAAI,CAAC,MAAM;aACd,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;aAChC,IAAI,CAAC,kBAAkB,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,KAAK,EAAE;YAC5F,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK;SACnC,CAAC,CAAC;IACT,CAAC;IAED;;;OAGG;IACgB,yBAAyB,CAAC,IAAa,EAAE,OAA0B;QACnF,IAAI,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC;QAC3D,CAAC;QACD,OAAO,KAAK,CAAC,yBAAyB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;IAED;;;;;;;OAOG;IACO,oBAAoB,CAAC,IAAa;QACzC,OAAO,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAK,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC;IAEkB,YAAY,CAC5B,QAA4B,EAC5B,OAAe,EACf,IAA+B;QAE/B,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QACzD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,IAAI,EAAE,CAAC;YACT,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oEAAoE,CAAC,CAAC;YACvF,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAC5D,CAAC;QACD,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACtD,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IACrE,CAAC;IAED;;;;;;;;;;OAUG;IACO,gBAAgB,CAAoB,IAAO,EAAE,IAA+B;QACnF,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QAC5D,MAAM,aAAa,GAAG,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,IAAI,CAAC,UAAU,IAAK,EAAE,KAAK,EAAE,OAAO,EAAc,CAAC,CAAC;QACtI,MAAM,QAAQ,GAAG,UAAU,IAAI,aAAa,CAAC;QAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,2EAA2E,CAAC,CAAC;YAC9F,OAAO,EAAE,CAAC;QACb,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,kBAAkB,CAAC,uBAAuB,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC;YAC/G,OAAO,QAAQ,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ;YACjB,CAAC,CAAC,GAAG,QAAQ,GAAG,kBAAkB,CAAC,yBAAyB,GAAG,IAAI,CAAC,QAAQ,GAAG,kBAAkB,CAAC,uBAAuB,GAAG,IAAI,CAAC,KAAK,EAAE;YACxI,CAAC,CAAC,GAAG,QAAQ,GAAG,kBAAkB,CAAC,uBAAuB,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IAChF,CAAC;CACH"}

package/lib/langium/validation/index.d.ts

@@ -0,0 +1,12 @@
+/********************************************************************************
+ * 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-validator.js';
+export * from './validation-contribution.js';
+export * from './validation-contribution-collector.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/langium/validation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wCAAwC,CAAC"}

package/lib/langium/validation/index.js

@@ -0,0 +1,12 @@
+/********************************************************************************
+ * 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-validator.js';
+export * from './validation-contribution.js';
+export * from './validation-contribution-collector.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/langium/validation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wCAAwC,CAAC"}

package/lib/langium/validation/validation-contribution-collector.d.ts

@@ -0,0 +1,34 @@
+/********************************************************************************
+ * 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 '../diagnostics/logger.js';
+import { type ServerLanguageServices } from '../language-module.js';
+export type ValidationContributionCollectorOptions = LogNameOptions;
+/**
+ * Per-language eager collector that wires `ValidationCheckContribution`s
+ * declared under `services.validation.checks` into Langium's native
+ * `ValidationRegistry`.
+ *
+ * Acts as the validation-side analog of the build-side
+ * `BuildPipelineIntegration` routing: at construction time it iterates the
+ * language's `validation.checks` contribution group, hands each contribution a
+ * thin {@link ValidationCheckRegistry} adapter, and the contribution registers
+ * its checks through it.
+ *
+ * Constructed on first per-language services access (typically forced by
+ * `BuildPipelineIntegration` touching the language services tree at the first
+ * build event); subsequent touches return the cached singleton from Langium's
+ * DI proxy. That is what gets the checks into the registry before Langium
+ * reaches the `Validated` phase — nothing else constructs this service.
+ */
+export declare class ValidationContributionCollector {
+    protected readonly tracer: Tracer;
+    constructor(services: ServerLanguageServices, options?: ValidationContributionCollectorOptions);
+}
+//# sourceMappingURL=validation-contribution-collector.d.ts.map

package/lib/langium/validation/validation-contribution-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-contribution-collector.d.ts","sourceRoot":"","sources":["../../../src/langium/validation/validation-contribution-collector.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAGpE,MAAM,MAAM,sCAAsC,GAAG,cAAc,CAAC;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,+BAA+B;IACzC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEtB,QAAQ,EAAE,sBAAsB,EAAE,OAAO,GAAE,sCAA2C;CAUpG"}

package/lib/langium/validation/validation-contribution-collector.js

@@ -0,0 +1,51 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Per-language eager collector that wires `ValidationCheckContribution`s
+ * declared under `services.validation.checks` into Langium's native
+ * `ValidationRegistry`.
+ *
+ * Acts as the validation-side analog of the build-side
+ * `BuildPipelineIntegration` routing: at construction time it iterates the
+ * language's `validation.checks` contribution group, hands each contribution a
+ * thin {@link ValidationCheckRegistry} adapter, and the contribution registers
+ * its checks through it.
+ *
+ * Constructed on first per-language services access (typically forced by
+ * `BuildPipelineIntegration` touching the language services tree at the first
+ * build event); subsequent touches return the cached singleton from Langium's
+ * DI proxy. That is what gets the checks into the registry before Langium
+ * reaches the `Validated` phase — nothing else constructs this service.
+ */
+export class ValidationContributionCollector {
+    tracer;
+    constructor(services, options = {}) {
+        this.tracer = services.shared.Tracer.for(options.logName ?? 'ValidationContributions').trace('instantiated');
+        const registry = createValidationCheckRegistry(services.validation.ValidationRegistry);
+        // Optional chaining tolerates incomplete test stubs; production
+        // wiring always provides the slot via `createServerLanguageModule`.
+        const contributions = services.validation?.checks ?? {};
+        for (const contribution of Object.values(contributions)) {
+            contribution.registerValidationChecks(registry);
+        }
+    }
+}
+/**
+ * Build a {@link ValidationCheckRegistry} adapter over Langium's
+ * `ValidationRegistry.register` — a pass-through, so `thisObj` and `category`
+ * must be forwarded rather than dropped.
+ */
+function createValidationCheckRegistry(langiumRegistry) {
+    return {
+        register(checks, thisObj, category) {
+            langiumRegistry.register(checks, thisObj, category);
+        }
+    };
+}
+//# sourceMappingURL=validation-contribution-collector.js.map

package/lib/langium/validation/validation-contribution-collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-contribution-collector.js","sourceRoot":"","sources":["../../../src/langium/validation/validation-contribution-collector.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAUlF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,+BAA+B;IACtB,MAAM,CAAS;IAElC,YAAY,QAAgC,EAAE,UAAkD,EAAE;QAC/F,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,yBAAyB,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAC7G,MAAM,QAAQ,GAAG,6BAA6B,CAAC,QAAQ,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;QACvF,gEAAgE;QAChE,oEAAoE;QACpE,MAAM,aAAa,GAAG,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,EAAE,CAAC;QACxD,KAAK,MAAM,YAAY,IAAI,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;YACvD,YAAY,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC;QACnD,CAAC;IACJ,CAAC;CACH;AAED;;;;GAIG;AACH,SAAS,6BAA6B,CAAC,eAAmC;IACvE,OAAO;QACJ,QAAQ,CAAI,MAA2B,EAAE,OAAoC,EAAE,QAA6B;YACzG,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QACvD,CAAC;KACH,CAAC;AACL,CAAC"}

package/lib/langium/validation/validation-contribution.d.ts

@@ -0,0 +1,36 @@
+/********************************************************************************
+ * 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 ValidationCategory, type ValidationChecks } from '@hydranium/langium';
+/**
+ * Registry handed to a {@link ValidationCheckContribution}. A thin wrapper over
+ * Langium's `ValidationRegistry.register` — the same type-keyed,
+ * category-scheduled check map underneath, so two contributions registering a
+ * check for the same node type both run (the registry stores checks in a
+ * `MultiMap`, which appends).
+ *
+ * `thisObj` mirrors Langium's signature: when a contribution passes check
+ * methods that read `this`, hand the contribution instance here so the binding
+ * is preserved.
+ */
+export interface ValidationCheckRegistry {
+    register<T>(checks: ValidationChecks<T>, thisObj?: ThisParameterType<unknown>, category?: ValidationCategory): void;
+}
+/**
+ * Declarative registration of validation checks. Bound under the module's
+ * `validation.checks` contribution group; a framework collector reads the group
+ * and calls this method, handing in a {@link ValidationCheckRegistry} that
+ * forwards to Langium's `ValidationRegistry`.
+ *
+ * The domain-qualified method name lets a single cross-cutting class implement
+ * several contribution interfaces without method collision.
+ */
+export interface ValidationCheckContribution {
+    registerValidationChecks(registry: ValidationCheckRegistry): void;
+}
+//# sourceMappingURL=validation-contribution.d.ts.map

package/lib/langium/validation/validation-contribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-contribution.d.ts","sourceRoot":"","sources":["../../../src/langium/validation/validation-contribution.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEpF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACrC,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACtH;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,2BAA2B;IACzC,wBAAwB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,IAAI,CAAC;CACpE"}

package/lib/langium/validation/validation-contribution.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 {};
+//# sourceMappingURL=validation-contribution.js.map

package/lib/langium/validation/validation-contribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-contribution.js","sourceRoot":"","sources":["../../../src/langium/validation/validation-contribution.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF"}

package/lib/langium/workspace/additional-document-contribution.d.ts

@@ -0,0 +1,68 @@
+/********************************************************************************
+ * 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 MaybePromise } from '@hydranium/protocol';
+import { type AstNode, type LangiumDocument } from '@hydranium/langium';
+import { type WorkspaceFolder } from 'vscode-languageserver-types';
+/**
+ * Registry handed to an {@link AdditionalDocumentContribution} — a pure sink,
+ * like the AST-extension / integrity / scope registries: the workspace
+ * {@link folders} being initialized plus a {@link register} sink that seeds each
+ * built document into the workspace.
+ *
+ * Transient, unlike those lifetime-held registries: their registrations are
+ * *consulted repeatedly* (per build, per scope query), so the owning service
+ * holds them; additional documents are seeded *once* at startup — nothing
+ * consults them later — so the workspace manager materialises this registry
+ * during `loadAdditionalDocuments` (the only point Langium's document collector
+ * is in scope) and discards it.
+ *
+ * The registry does NOT hand over a `LangiumDocumentFactory`: a contribution is
+ * DI-instantiated with `services` (the standard contribution pattern) and reads
+ * `services.workspace.LangiumDocumentFactory` itself to build its documents.
+ */
+export interface AdditionalDocumentRegistry {
+    /**
+     * The workspace folders being initialized (empty for a folderless init) —
+     * the same input Langium hands `loadAdditionalDocuments`. Lets a contribution
+     * key its documents off the workspace (per-folder libraries,
+     * workspace-relative resolution).
+     */
+    readonly folders: readonly WorkspaceFolder[];
+    /** Seed a built document into the workspace (indexed like any startup document). */
+    register(document: LangiumDocument<AstNode>): void;
+}
+/**
+ * Declarative registration of additional startup documents — the contribution
+ * form of overriding `DefaultWorkspaceManager.loadAdditionalDocuments`. Bound
+ * under the shared `additionalDocuments` group; the framework workspace manager
+ * reads its own group during startup and calls this method, handing in a
+ * transient {@link AdditionalDocumentRegistry}.
+ *
+ * A registered document is added to the workspace and indexed like any file, so
+ * its exported symbols reach the global scope with no manual scope extension.
+ * For a virtual (`virtualUri`) document with no owning project, that indexing
+ * classifies it universal-tier (visible everywhere) — the standard way to
+ * contribute a stdlib / library / built-in set.
+ *
+ * The domain-qualified method name lets a single cross-cutting class implement
+ * several contribution interfaces without method collision.
+ */
+export interface AdditionalDocumentContribution {
+    registerAdditionalDocuments(registry: AdditionalDocumentRegistry): MaybePromise<void>;
+}
+/**
+ * Iterate an {@link AdditionalDocumentContribution} group, handing each a
+ * transient registry (workspace `folders` + a `register` sink) and seeding the
+ * registered documents through `collect`. Awaits each contribution so async
+ * document construction is supported. Pure over its inputs (no services / DI)
+ * so it is unit-testable; the framework workspace manager calls it from
+ * `loadAdditionalDocuments`.
+ */
+export declare function collectAdditionalDocuments(contributions: Record<string, AdditionalDocumentContribution>, folders: readonly WorkspaceFolder[], collect: (document: LangiumDocument<AstNode>) => void): Promise<void>;
+//# sourceMappingURL=additional-document-contribution.d.ts.map

package/lib/langium/workspace/additional-document-contribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"additional-document-contribution.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/additional-document-contribution.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,0BAA0B;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,8BAA8B;IAC5C,2BAA2B,CAAC,QAAQ,EAAE,0BAA0B,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;CACxF;AAED;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC7C,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,8BAA8B,CAAC,EAC7D,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,OAAO,EAAE,CAAC,QAAQ,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,IAAI,GACrD,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/lib/langium/workspace/additional-document-contribution.js

@@ -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
+ ********************************************************************************/
+/**
+ * Iterate an {@link AdditionalDocumentContribution} group, handing each a
+ * transient registry (workspace `folders` + a `register` sink) and seeding the
+ * registered documents through `collect`. Awaits each contribution so async
+ * document construction is supported. Pure over its inputs (no services / DI)
+ * so it is unit-testable; the framework workspace manager calls it from
+ * `loadAdditionalDocuments`.
+ */
+export async function collectAdditionalDocuments(contributions, folders, collect) {
+    const registry = { folders, register: collect };
+    for (const contribution of Object.values(contributions)) {
+        await contribution.registerAdditionalDocuments(registry);
+    }
+}
+//# sourceMappingURL=additional-document-contribution.js.map

package/lib/langium/workspace/additional-document-contribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"additional-document-contribution.js","sourceRoot":"","sources":["../../../src/langium/workspace/additional-document-contribution.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAuDlF;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC7C,aAA6D,EAC7D,OAAmC,EACnC,OAAqD;IAErD,MAAM,QAAQ,GAA+B,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAC5E,KAAK,MAAM,YAAY,IAAI,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;QACvD,MAAM,YAAY,CAAC,2BAA2B,CAAC,QAAQ,CAAC,CAAC;IAC5D,CAAC;AACJ,CAAC"}