@hydranium/core 1.0.0-next.10

package/lib/langium/diagnostics/log-preamble.js

@@ -0,0 +1,57 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 { DEFER_START_MS } from '@hydranium/protocol';
+const DIVIDER = '───────────────────────────────────────────────────────────────────';
+/**
+ * Emits session info and log format conventions. The body is portable
+ * (browser-safe); Node-specific runtime details and monitor conventions are
+ * injected via {@link LogPreambleOptions.systemInfoLines} /
+ * {@link LogPreambleOptions.conventionLines} (see `@hydranium/core/node`).
+ */
+export function logPreamble(logger, options) {
+    logSessionInfo(logger, options.productName, options.version, options.systemInfoLines ?? []);
+    logFormatConventions(logger, options.phaseDetailThresholdMs ?? 50, options.conventionLines ?? []);
+}
+function logSessionInfo(logger, productName, version, systemInfoLines) {
+    const now = new Date();
+    const dateStr = now.toISOString().slice(0, 10); // YYYY-MM-DD, unambiguous across midnight
+    const lines = [
+        DIVIDER,
+        `${productName} server session`,
+        DIVIDER,
+        `date        ${dateStr}`,
+        `version     ${version}`,
+        ...systemInfoLines,
+        DIVIDER
+    ];
+    for (const line of lines) {
+        logger.info(line);
+    }
+}
+function logFormatConventions(logger, phaseDetailThresholdMs, conventionLines) {
+    const lines = [
+        'Log format conventions',
+        DIVIDER,
+        '• Timing pairs:   "<op> [#N start]"  ->  "<op> [#N done|cancelled|failed, Nms]"',
+        '• Rebuild tags:   contextual metadata lives inside the status brackets, e.g.',
+        '                  "[#N start, event: didChangeContent, cancels #M]"',
+        `• Quiet ops:      operations under ${DEFER_START_MS}ms are silent; lifecycle ops (save, load) always log`,
+        '                  (failures/cancels always log, even below the threshold - in that case',
+        '                  [start] is emitted retroactively so timestamps may be back-to-back while',
+        '                  the reported Nms is the real elapsed time)',
+        `• Phase detail:   Parsed/IndexedContent/.../Validated shown only for rebuilds >=${phaseDetailThresholdMs}ms;`,
+        '                  workspace init always emits per-phase lines live',
+        ...conventionLines,
+        DIVIDER
+    ];
+    for (const line of lines) {
+        logger.info(line);
+    }
+}
+//# sourceMappingURL=log-preamble.js.map

package/lib/langium/diagnostics/log-preamble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-preamble.js","sourceRoot":"","sources":["../../../src/langium/diagnostics/log-preamble.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,cAAc,EAAe,MAAM,qBAAqB,CAAC;AAElE,MAAM,OAAO,GAAG,qEAAqE,CAAC;AA4BtF;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,OAA2B;IACpE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;IAC5F,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,sBAAsB,IAAI,EAAE,EAAE,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;AACrG,CAAC;AAED,SAAS,cAAc,CAAC,MAAc,EAAE,WAAmB,EAAE,OAAe,EAAE,eAAkC;IAC7G,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,OAAO,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,0CAA0C;IAC1F,MAAM,KAAK,GAAG;QACX,OAAO;QACP,GAAG,WAAW,iBAAiB;QAC/B,OAAO;QACP,eAAe,OAAO,EAAE;QACxB,eAAe,OAAO,EAAE;QACxB,GAAG,eAAe;QAClB,OAAO;KACT,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAAC,MAAc,EAAE,sBAA8B,EAAE,eAAkC;IAC7G,MAAM,KAAK,GAAG;QACX,wBAAwB;QACxB,OAAO;QACP,iFAAiF;QACjF,8EAA8E;QAC9E,qEAAqE;QACrE,sCAAsC,cAAc,sDAAsD;QAC1G,yFAAyF;QACzF,4FAA4F;QAC5F,8DAA8D;QAC9D,mFAAmF,sBAAsB,KAAK;QAC9G,oEAAoE;QACpE,GAAG,eAAe;QAClB,OAAO;KACT,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;AACJ,CAAC"}

package/lib/langium/diagnostics/logger.d.ts

@@ -0,0 +1,104 @@
+/********************************************************************************
+ * Copyright (c) 2023-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
+ ********************************************************************************/
+/** Only append a memory suffix when the heap has moved by at least this much since the last log line. */
+export declare const MEMORY_DELTA_BYTES: number;
+/**
+ * Pluggable file-tee sink. The file-tee's only platform coupling is the
+ * actual disk write + directory create; routing those through an injected
+ * sink keeps this module free of `node:fs` so it stays on the portable `.`
+ * entry. `@hydranium/core/node` installs a `node:fs`-backed sink (see
+ * `installNodeLogFileSink`); when
+ * no sink is installed (browser / in-memory hosts) the file-tee is inert and
+ * lines fan out only to the LSP/console destination. Configuring a tee target
+ * (`HYDRANIUM_LOG_FILE`) is itself Node-only, so the inert path is never hit
+ * in a browser.
+ */
+export interface LogFileSink {
+    /** Append already-formatted text to the file at `path`. Must not throw. */
+    append(path: string, data: string): void;
+    /** Best-effort create of the parent directory for `path`. Must not throw. */
+    ensureDir(path: string): void;
+}
+/** Install (or clear, with `undefined`) the file-tee sink. Idempotent. */
+export declare function setLogFileSink(sink: LogFileSink | undefined): void;
+/**
+ * Set the file-tee target programmatically. Pass `undefined` to disable. The
+ * path may contain `{placeholder}` tokens (e.g. `{workspace}`); lines buffer
+ * until every token is supplied via {@link resolveLogFilePlaceholder}.
+ * Called by the `LspLogger` constructor's
+ * one-time `HYDRANIUM_LOG_FILE` env baseline (and by tests).
+ */
+export declare function setLogFilePath(path: string | undefined): void;
+/**
+ * Supply a value for a `{name}` placeholder in the configured target. Once the
+ * last placeholder is supplied the target resolves and any lines buffered while
+ * it was pending are flushed in emission order.
+ */
+export declare function resolveLogFilePlaceholder(name: string, value: string): void;
+/**
+ * Last-resort flush for the case where the target never resolves (e.g. the
+ * server crashed before the workspace was known). Substitutes any remaining
+ * `{...}` token with a process-unique `_startup-<pid>` segment and flushes the
+ * buffer, so startup / failure lines are never lost. No-op when the target is
+ * already resolved or there is nothing buffered. Registered on `process.exit`
+ * as soon as an unresolved target is configured.
+ */
+export declare function flushLogFileFallback(): void;
+/** Current resolved file-tee target. `undefined` when disabled or still pending. */
+export declare function getLogFilePath(): string | undefined;
+/**
+ * Fan a single already-formatted log line out to the file-tee target, if one is
+ * configured. Called by `LspLogger`'s emit in
+ * addition to the LSP/console sink — log sinks fan out, they don't replace.
+ * While the target is still pending (unresolved `{placeholder}`), the line is
+ * buffered instead of dropped.
+ */
+export declare function teeLogLine(formatted: string): void;
+export { toLogFileWorkspaceToken } from './log-file-token.js';
+/**
+ * Shared options-base for every framework-bound service that derives a
+ * `Tracer` (or
+ * `Logger`) from its `services`
+ * constructor parameter. Carries the `logName` label used to identify the
+ * service in its log / trace output and in the startup instantiation trace.
+ *
+ * The field name reads from the adopter's perspective — `logName` is "the
+ * name this service appears under in the log". Distinct from
+ * `LspLoggerOptions.component`, which is the logger's own identity field
+ * (matches `AbstractLogger.component` and `Logger.for`'s argument).
+ *
+ * A framework service's constructor stores a tracer named by `logName` and
+ * emits a single instantiation trace. The fallback used when `logName` is
+ * absent is chosen per service: a fixed curated string where the slot has one
+ * canonical implementation, or `this.constructor.name` where it has swappable
+ * strategy bindings, so the log shows which implementation ran. The
+ * framework's default `Logger` level is `'info'`, so those trace lines are
+ * no-ops in production; raising the level to `trace` — directly or via the
+ * LSP-config-bound setting — before workspace load makes startup
+ * instantiation visible.
+ */
+export interface LogNameOptions {
+    /**
+     * Name passed to `Tracer.for(...)` / `Logger.for(...)` — the label the
+     * service appears under in its log / trace output. Optional; each
+     * service supplies its own default (a fixed curated string, or
+     * `this.constructor.name`). Override when the runtime class name is
+     * generic (anonymous adopter subclass) or when multiple instances of
+     * the same class are bound to distinct slots and the adopter wants to
+     * disambiguate them in the log.
+     */
+    readonly logName?: string;
+}
+/**
+ * Format current memory as "heap used/total, rss N". Returns `''` where
+ * `process.memoryUsage` is unavailable (browser) so callers can append it
+ * unconditionally.
+ */
+export declare function formatMemory(): string;
+//# sourceMappingURL=logger.d.ts.map

package/lib/langium/diagnostics/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/langium/diagnostics/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAKlF,yGAAyG;AACzG,eAAO,MAAM,kBAAkB,QAAkB,CAAC;AAElD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IACzB,2EAA2E;IAC3E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,6EAA6E;IAC7E,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAID,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAElE;AA6ED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAM7D;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAG3E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAO3C;AAaD,oFAAoF;AACpF,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAYlD;AAKD,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,cAAc;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAMrC"}

package/lib/langium/diagnostics/logger.js

@@ -0,0 +1,178 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 { Format } from '@hydranium/protocol';
+import { currentMemoryUsage, onProcessEvent, processPid } from '../../util/environment.js';
+/** Only append a memory suffix when the heap has moved by at least this much since the last log line. */
+export const MEMORY_DELTA_BYTES = 5 * 1024 * 1024;
+let fileSink;
+/** Install (or clear, with `undefined`) the file-tee sink. Idempotent. */
+export function setLogFileSink(sink) {
+    fileSink = sink;
+}
+/**
+ * File-tee state for `LspLogger`'s emit. When
+ * non-empty, every formatted log line is appended to the path in addition to
+ * its LSP `window/logMessage` / console destination (see {@link teeLogLine}).
+ * Diagnostic surface only — once the LSP connection binds, server logs route
+ * through `connection.console.*` and disappear from any pipe watching backend
+ * stdout; setting this path makes them visible to a headless test harness
+ * without scraping the client's Output view.
+ *
+ * The sink writes synchronously, so log lines preserve emission order; errors
+ * are swallowed because a failing log sink must not propagate.
+ * Append-only — the path is the consumer's responsibility to truncate / rotate.
+ *
+ * Raw configured target — may contain `{placeholder}` tokens (e.g.
+ * `{workspace}`) that are not known at module-load time.
+ */
+let logFileTemplate;
+/** Fully-resolved target (no remaining placeholders). `undefined` while pending. */
+let resolvedLogFilePath;
+/** Placeholder values supplied so far via {@link resolveLogFilePlaceholder}. */
+const logFilePlaceholders = new Map();
+/**
+ * Lines emitted while the target is still pending (placeholders unresolved).
+ * Flushed verbatim — preserving emission order — once the target resolves, so
+ * no startup line is ever dropped. Each entry already carries its trailing `\n`.
+ */
+const pendingLogLines = [];
+/** Matches any remaining `{name}` placeholder token. */
+const PLACEHOLDER_PATTERN = /\{[^}]+\}/;
+/**
+ * Recompute {@link resolvedLogFilePath} from the template + known placeholders.
+ * Resolves (and flushes the pending buffer) only once no `{...}` token remains.
+ */
+function tryResolveLogFilePath() {
+    if (!logFileTemplate) {
+        resolvedLogFilePath = undefined;
+        return;
+    }
+    let path = logFileTemplate;
+    for (const [name, value] of logFilePlaceholders) {
+        path = path.split(`{${name}}`).join(value);
+    }
+    if (PLACEHOLDER_PATTERN.test(path)) {
+        resolvedLogFilePath = undefined;
+        // Target is pending — guarantee the buffer is flushed even if the process
+        // exits before the remaining placeholders are ever supplied.
+        ensureFallbackHandler();
+        return;
+    }
+    resolvedLogFilePath = path;
+    ensureLogDir(path);
+    flushPendingLogLines();
+}
+/**
+ * Best-effort create of the target's parent directory. Covers the headless-test
+ * case where the runner wipes the output directory before the server writes its
+ * log under it. Failures are swallowed — a log sink must never propagate.
+ */
+function ensureLogDir(filePath) {
+    // No-op when no sink is installed (browser); the Node sink swallows its own errors.
+    fileSink?.ensureDir(filePath);
+}
+/** Append the buffered lines to the resolved target, then clear the buffer. */
+function flushPendingLogLines() {
+    if (!resolvedLogFilePath || pendingLogLines.length === 0) {
+        return;
+    }
+    fileSink?.append(resolvedLogFilePath, pendingLogLines.join(''));
+    pendingLogLines.length = 0;
+}
+/**
+ * Set the file-tee target programmatically. Pass `undefined` to disable. The
+ * path may contain `{placeholder}` tokens (e.g. `{workspace}`); lines buffer
+ * until every token is supplied via {@link resolveLogFilePlaceholder}.
+ * Called by the `LspLogger` constructor's
+ * one-time `HYDRANIUM_LOG_FILE` env baseline (and by tests).
+ */
+export function setLogFilePath(path) {
+    logFileTemplate = path && path.length > 0 ? path : undefined;
+    logFilePlaceholders.clear();
+    pendingLogLines.length = 0;
+    resolvedLogFilePath = undefined;
+    tryResolveLogFilePath();
+}
+/**
+ * Supply a value for a `{name}` placeholder in the configured target. Once the
+ * last placeholder is supplied the target resolves and any lines buffered while
+ * it was pending are flushed in emission order.
+ */
+export function resolveLogFilePlaceholder(name, value) {
+    logFilePlaceholders.set(name, value);
+    tryResolveLogFilePath();
+}
+/**
+ * Last-resort flush for the case where the target never resolves (e.g. the
+ * server crashed before the workspace was known). Substitutes any remaining
+ * `{...}` token with a process-unique `_startup-<pid>` segment and flushes the
+ * buffer, so startup / failure lines are never lost. No-op when the target is
+ * already resolved or there is nothing buffered. Registered on `process.exit`
+ * as soon as an unresolved target is configured.
+ */
+export function flushLogFileFallback() {
+    if (!logFileTemplate || resolvedLogFilePath || pendingLogLines.length === 0) {
+        return;
+    }
+    resolvedLogFilePath = logFileTemplate.replace(/\{[^}]+\}/g, `_startup-${processPid() ?? 'unknown'}`);
+    ensureLogDir(resolvedLogFilePath);
+    flushPendingLogLines();
+}
+/** Registered at most once; flushes any pending buffer on process teardown. */
+let fallbackHandlerRegistered = false;
+function ensureFallbackHandler() {
+    if (fallbackHandlerRegistered) {
+        return;
+    }
+    fallbackHandlerRegistered = true;
+    // Node-only teardown flush; a no-op in a browser worker (no `exit` event).
+    onProcessEvent('exit', () => flushLogFileFallback());
+}
+/** Current resolved file-tee target. `undefined` when disabled or still pending. */
+export function getLogFilePath() {
+    return resolvedLogFilePath;
+}
+/**
+ * Fan a single already-formatted log line out to the file-tee target, if one is
+ * configured. Called by `LspLogger`'s emit in
+ * addition to the LSP/console sink — log sinks fan out, they don't replace.
+ * While the target is still pending (unresolved `{placeholder}`), the line is
+ * buffered instead of dropped.
+ */
+export function teeLogLine(formatted) {
+    if (!logFileTemplate) {
+        return;
+    }
+    const line = `${formatted}\n`;
+    if (resolvedLogFilePath) {
+        // The sink swallows its own errors; recursing into the logger here would
+        // re-enter emit and loop. The LSP/console sink already delivered the line.
+        fileSink?.append(resolvedLogFilePath, line);
+    }
+    else {
+        pendingLogLines.push(line);
+    }
+}
+// Re-exported so the token derivation is reachable from the diagnostics barrel.
+// It is defined in a standalone, dependency-light module so a Playwright test
+// helper can import it directly without pulling the barrel's module graph.
+export { toLogFileWorkspaceToken } from './log-file-token.js';
+/**
+ * Format current memory as "heap used/total, rss N". Returns `''` where
+ * `process.memoryUsage` is unavailable (browser) so callers can append it
+ * unconditionally.
+ */
+export function formatMemory() {
+    const mem = currentMemoryUsage();
+    if (!mem) {
+        return '';
+    }
+    return `heap ${Format.bytes(mem.heapUsed)}/${Format.bytes(mem.heapTotal)}, rss ${Format.bytes(mem.rss)}`;
+}
+//# sourceMappingURL=logger.js.map

package/lib/langium/diagnostics/logger.js.map

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

package/lib/langium/diagnostics/lsp-logger.d.ts

@@ -0,0 +1,76 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 { AbstractLogger, type Clock, Logger, type LogLevel, type LogThreshold, type MaybeObservableValue } from '@hydranium/protocol';
+import { type URI } from '@hydranium/langium';
+import { type ServerSharedServices } from '../module.js';
+/**
+ * Options accepted by {@link LspLogger}. Carries the logger's own
+ * identity {@link component} (the field on {@link AbstractLogger}
+ * prefixed to every log line the logger emits). This is intentionally
+ * a separate field from `logName` on
+ * `LogNameOptions` — the latter labels a
+ * service that DERIVES a logger; this labels the logger itself.
+ */
+export interface LspLoggerOptions {
+    /** Component label prefixed to log output. Read by `AbstractLogger.emit`. */
+    readonly component?: string;
+    /**
+     * Process-global log threshold, applied at construction of the ROOT logger
+     * (the instance bound in DI). When set, the constructor calls
+     * `Logger.setLevel` with the current value (only when truthy, so an unset
+     * setting leaves the env-fallback / `'info'` default in place) and
+     * re-applies on every `onChange`. Bind to a user setting via
+     * `Settings.value`.
+     *
+     * The threshold is GLOBAL, not per-instance: `derive` / `for` create child
+     * loggers passing only `component`, so children never carry or re-apply
+     * `logThreshold` — the root owns it. Pass a constant for tests / non-LSP
+     * runs. (Named `logThreshold`, not `logLevel`, to avoid colliding with
+     * GLSP's per-instance numeric `Logger.logLevel`; it is an
+     * `MaybeObservableValue<LogThreshold>`, matching the framework's filter-side type.)
+     */
+    readonly logThreshold?: MaybeObservableValue<LogThreshold | undefined>;
+}
+/**
+ * LSP-bound implementation of {@link Logger}. Forwards messages to the
+ * language client via the connection bound in {@link ServerSharedServices}.
+ * Emission only — memory readout and timing live on the server's
+ * `ServerTracer`, which composes this
+ * logger. Adds URI-aware labelling on top of {@link AbstractLogger}.
+ *
+ * `withUri` renders workspace-relative paths by default (via the framework
+ * `WorkspaceManager.wsRelativePath`); consumers subclass only for a different
+ * display convention or extra language-specific helpers.
+ */
+export declare class LspLogger extends AbstractLogger implements Logger {
+    protected readonly services: ServerSharedServices;
+    constructor(services: ServerSharedServices, options?: LspLoggerOptions);
+    /**
+     * Route logger timing and timestamps through the injected framework
+     * {@link Clock} (the dedicated `shared.Clock` slot) so server-side log time
+     * shares the one fake-clock axis tests drive with `makeFakeClock`, rather
+     * than reading the wall clock directly. The logger takes the full
+     * {@link ServerSharedServices}, which carries the slot, so the read is
+     * direct — no cast or fallback needed.
+     */
+    protected clock(): Clock;
+    /**
+     * URI labelling rendered as a workspace-relative path via the framework
+     * `HydraniumWorkspaceManager.wsRelativePath` (falls back to the URI
+     * string when no workspace folder is known). Widens the
+     * {@link Logger.withUri} parameter to accept a `URI` object directly —
+     * server-side callers typically hold URIs, not strings. Subclasses with a
+     * different display convention override their `WorkspaceManager.wsRelativePath`
+     * (preferred) or this method.
+     */
+    withUri(uri: URI | string): this;
+    protected emit(level: LogLevel, label: string, message: string, args: readonly unknown[]): void;
+    protected derive(component: string): this;
+}
+//# sourceMappingURL=lsp-logger.d.ts.map

package/lib/langium/diagnostics/lsp-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lsp-logger.d.ts","sourceRoot":"","sources":["../../../src/langium/diagnostics/lsp-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,cAAc,EACd,KAAK,KAAK,EAGV,MAAM,EACN,KAAK,QAAQ,EACb,KAAK,YAAY,EAEjB,KAAK,oBAAoB,EAE3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAYzD;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;CACzE;AAED;;;;;;;;;;GAUG;AACH,qBAAa,SAAU,SAAQ,cAAe,YAAW,MAAM;IAEzD,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB;gBAA9B,QAAQ,EAAE,oBAAoB,EACjD,OAAO,GAAE,gBAAqB;IA2CjC;;;;;;;OAOG;cACgB,KAAK,IAAI,KAAK;IAIjC;;;;;;;;OAQG;IACM,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,IAAI;IAIzC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAuC/F,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAM3C"}

package/lib/langium/diagnostics/lsp-logger.js

@@ -0,0 +1,223 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 { AbstractLogger, DEFAULT_LOG_FILE_ENV, DEFAULT_LOG_LEVEL_ENV, Logger, ObservableValue, parseLogLevel } from '@hydranium/protocol';
+import { setLogFilePath, teeLogLine } from './logger.js';
+import { processEnv, writeStderr } from '../../util/environment.js';
+/**
+ * Guards the one-time env-var log-level and log-file baselines (see the
+ * {@link LspLogger} constructor). Applied on the first logger construction and
+ * never again, so derived child loggers cannot re-read the env and clobber a
+ * live setting.
+ */
+let envBaselineApplied = false;
+/**
+ * LSP-bound implementation of {@link Logger}. Forwards messages to the
+ * language client via the connection bound in {@link ServerSharedServices}.
+ * Emission only — memory readout and timing live on the server's
+ * `ServerTracer`, which composes this
+ * logger. Adds URI-aware labelling on top of {@link AbstractLogger}.
+ *
+ * `withUri` renders workspace-relative paths by default (via the framework
+ * `WorkspaceManager.wsRelativePath`); consumers subclass only for a different
+ * display convention or extra language-specific helpers.
+ */
+export class LspLogger extends AbstractLogger {
+    services;
+    constructor(services, options = {}) {
+        super(options.component);
+        this.services = services;
+        // Apply the framework env baselines (`HYDRANIUM_LOG_LEVEL` and
+        // `HYDRANIUM_LOG_FILE`) exactly once, on the first logger construction,
+        // before any setting is read. Unconditional and process-global, so it
+        // needs no root detection and is never re-applied by derived children —
+        // which would otherwise clobber a live setting. These are the single env
+        // vars for level / file-tee (an adopter brands them by renaming the
+        // framework env, not by introducing its own).
+        if (!envBaselineApplied) {
+            envBaselineApplied = true;
+            // No `process.env` in a browser — the level/file-tee env baseline is
+            // a Node concern; skip it cleanly there.
+            const env = processEnv();
+            if (env) {
+                const envLevel = parseLogLevel(env[DEFAULT_LOG_LEVEL_ENV]);
+                if (envLevel) {
+                    Logger.setLevel(envLevel);
+                }
+                const envLogFile = env[DEFAULT_LOG_FILE_ENV];
+                if (envLogFile) {
+                    setLogFilePath(envLogFile);
+                }
+            }
+        }
+        // Apply the configured threshold from the root logger only — `derive`
+        // passes just `component`, so children never carry `logThreshold`. The
+        // setting overrides the env baseline above and re-applies on every change;
+        // truthy-guarded so an unset setting leaves the baseline / `'info'` default.
+        if (options.logThreshold !== undefined) {
+            const level = ObservableValue.from(options.logThreshold);
+            if (level.value) {
+                Logger.setLevel(level.value);
+            }
+            level.onChange(next => {
+                if (next) {
+                    Logger.setLevel(next);
+                }
+            });
+        }
+    }
+    /**
+     * Route logger timing and timestamps through the injected framework
+     * {@link Clock} (the dedicated `shared.Clock` slot) so server-side log time
+     * shares the one fake-clock axis tests drive with `makeFakeClock`, rather
+     * than reading the wall clock directly. The logger takes the full
+     * {@link ServerSharedServices}, which carries the slot, so the read is
+     * direct — no cast or fallback needed.
+     */
+    clock() {
+        return this.services.Clock;
+    }
+    /**
+     * URI labelling rendered as a workspace-relative path via the framework
+     * `HydraniumWorkspaceManager.wsRelativePath` (falls back to the URI
+     * string when no workspace folder is known). Widens the
+     * {@link Logger.withUri} parameter to accept a `URI` object directly —
+     * server-side callers typically hold URIs, not strings. Subclasses with a
+     * different display convention override their `WorkspaceManager.wsRelativePath`
+     * (preferred) or this method.
+     */
+    withUri(uri) {
+        return this.with(this.services.workspace.WorkspaceManager.wsRelativePath(uri));
+    }
+    emit(level, label, message, args) {
+        const component = this.component ? ` [${this.component}]` : '';
+        // Pad to the widest label (5 chars — 'Error'/'Debug'/'Trace') so timestamps line up.
+        const prefix = `[${label.padEnd(5)} - ${this.timestamp()}]${component}`;
+        const combined = args.length === 0 ? message : `${message} ${args.map(formatLogArg).join(' ')}`;
+        const formatted = `${prefix} ${combined}`;
+        const connection = this.services.lsp.Connection;
+        // Route through the LSP `window/logMessage` channel so log lines stay
+        // framed as JSON-RPC messages even in `--stdio` mode (where stdout is
+        // the LSP transport — any raw `console.*` write before
+        // vscode-languageserver's `attachConsole` patches the globals would
+        // corrupt the protocol stream). Pre-stringify all args into one
+        // message because `RemoteConsole.*` takes a single string.
+        //
+        // Falls through to the raw sink below when the connection cannot take the
+        // line, which is NOT a theoretical case: `RemoteConsole.send` throws
+        // `Connection is disposed` once the client has gone, and the log lines
+        // most likely to arrive at that moment are the ones that matter most —
+        // shutdown diagnostics and the workspace manager's own
+        // unhandled-rejection handler. A log sink that throws turns a diagnostic
+        // into a crash, so a dead channel degrades to stderr instead.
+        if (!connection || !sendViaConnection(connection, level, formatted)) {
+            if (!writeStderr(`${formatted}\n`)) {
+                // Browser only. In Node every level goes to STDERR, including the
+                // three that `console.*` would put on stdout (`info` / `debug` /
+                // `log`) — stdout is the JSON-RPC channel for any head launched over
+                // stdio, so a log line written there corrupts the protocol stream
+                // rather than merely appearing in the wrong place. A browser has no
+                // such channel, so it keeps the per-level console methods, which
+                // render structured args far better than a pre-joined string.
+                const consumer = CONSOLE[level];
+                consumer(prefix, message, ...args);
+            }
+        }
+        // File-tee fan-out for headless capture (see `setLogFilePath`). Always runs
+        // in addition to the LSP/console sink — log sinks fan out, they don't replace.
+        teeLogLine(formatted);
+    }
+    derive(component) {
+        const Subclass = this.constructor;
+        return new Subclass(this.services, { component });
+    }
+}
+/**
+ * Deliver one formatted line over the LSP `window/logMessage` channel,
+ * reporting whether the channel took it.
+ *
+ * Returns `false` — rather than throwing — when the connection is closed or
+ * disposed. `RemoteConsole.send` throws `Connection is disposed` in that state,
+ * and a logger that propagates it converts a diagnostic into an uncaught
+ * exception at exactly the moment things are already going wrong: the framework's
+ * own `handleProcessUnhandledRejection` logs through this path, so a late
+ * rejection after client teardown would crash the server while *reporting* an
+ * error. The caller falls back to the raw sink, so the line is still delivered.
+ */
+function sendViaConnection(connection, level, formatted) {
+    try {
+        LSP_CONSOLE[level](connection)(formatted);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Per-level console adapter, used **only where there is no `process.stderr`**
+ * (a browser). In Node the fallback writes to stderr for every level instead —
+ * see the `emit` branch. Kept per-level rather than collapsed onto
+ * `console.error` because devtools render `info` / `debug` distinctly and
+ * colouring every framework log line as an error would be actively misleading.
+ */
+const CONSOLE = {
+    error: console.error,
+    warn: console.warn,
+    info: console.info,
+    debug: console.debug,
+    trace: console.log
+};
+/**
+ * Per-level adapter that resolves the right `RemoteConsole` method on a
+ * Langium {@link Connection}. `RemoteConsole` exposes
+ * `error / warn / info / log / debug` — `debug` arriving with LSP 3.18's
+ * `MessageType.Debug` severity, so a debug line is now tagged as such in
+ * the client's log instead of being indistinguishable from `log`. There is
+ * still no `trace`, so that one level folds into `log` (severity `Log` in
+ * the `window/logMessage` type table). A client predating 3.18 has no
+ * `Debug` case and appends the message unlabelled, so the mapping degrades
+ * rather than dropping output. The returned function takes a single
+ * pre-formatted string since `RemoteConsole.*` accepts only one argument.
+ */
+const LSP_CONSOLE = {
+    error: c => c.console.error.bind(c.console),
+    warn: c => c.console.warn.bind(c.console),
+    info: c => c.console.info.bind(c.console),
+    debug: c => c.console.debug.bind(c.console),
+    trace: c => c.console.log.bind(c.console)
+};
+/**
+ * Render a logger-argument value into the single combined string the LSP
+ * `window/logMessage` channel takes. Mirrors how raw `console.*` would
+ * format multiple args, but with explicit handling for Errors (stack) and
+ * objects (JSON).
+ */
+function formatLogArg(value) {
+    if (value === undefined) {
+        return 'undefined';
+    }
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (value instanceof Error) {
+        return value.stack ?? value.message;
+    }
+    if (typeof value === 'object') {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+    return String(value);
+}
+//# sourceMappingURL=lsp-logger.js.map