@hydranium/core 1.0.0-next.34 → 1.0.0-next.341

package/src/langium/diagnostics/lsp-logger.ts

@@ -11,7 +11,9 @@ import {
    AbstractLogger,
    type Clock,
    DEFAULT_LOG_FILE_ENV,
+   DEFAULT_LOG_FILE_LEVEL_ENV,
    DEFAULT_LOG_LEVEL_ENV,
+   LEVEL_ORDER,
    Logger,
    type LogLevel,
    type LogThreshold,
@@ -22,6 +24,8 @@ import {
 import { type URI } from '@hydranium/langium';
 import type { Connection } from 'vscode-languageserver';
 import { type ServerSharedServices } from '../module.js';
+import { installConsoleTee } from './console-tee.js';
+import { formatLogArg } from './format-log-arg.js';
 import { setLogFilePath, teeLogLine } from './logger.js';
 import { processEnv, writeStderr } from '../../util/environment.js';
 
@@ -32,6 +36,8 @@ import { processEnv, writeStderr } from '../../util/environment.js';
  * live setting.
  */
 let envBaselineApplied = false;
+/** Whether the first logger has run the console tee's install, which does nothing in a browser. */
+let consoleTeeInstalled = false;
 
 /**
  * Options accepted by {@link LspLogger}. Carries the logger's own
@@ -79,9 +85,10 @@ export class LspLogger extends AbstractLogger implements Logger {
       options: LspLoggerOptions = {}
    ) {
       super(options.component);
-      // 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
+      // Apply the framework env baselines (`HYDRANIUM_LOG_LEVEL`,
+      // `HYDRANIUM_LOG_FILE` and `HYDRANIUM_LOG_FILE_LEVEL`) 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
@@ -92,16 +99,30 @@ export class LspLogger extends AbstractLogger implements Logger {
          // 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);
-            }
+            // The file-tee target FIRST: the other order writes the level
+            // announcement before the sink exists, losing the one line that says
+            // which threshold the rest of the file was written at.
             const envLogFile = env[DEFAULT_LOG_FILE_ENV];
             if (envLogFile) {
-               setLogFilePath(envLogFile);
+               const fileLevel = parseLogLevel(env[DEFAULT_LOG_FILE_LEVEL_ENV]);
+               setLogFilePath(envLogFile, fileLevel);
+               if (fileLevel) {
+                  this.logAt(fileLevel, `Log file level ${fileLevel} (${DEFAULT_LOG_FILE_LEVEL_ENV})`);
+               }
+            }
+            const envLevel = parseLogLevel(env[DEFAULT_LOG_LEVEL_ENV]);
+            if (envLevel) {
+               this.applyLevel(envLevel, DEFAULT_LOG_LEVEL_ENV, { launch: true });
             }
          }
       }
+      // Once, so a server without an LSP head writes console lines to the file
+      // too; `startLanguageServer` wraps again where a stdio connection created
+      // after this logger replaced them.
+      if (!consoleTeeInstalled) {
+         consoleTeeInstalled = true;
+         installConsoleTee();
+      }
       // 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;
@@ -109,16 +130,61 @@ export class LspLogger extends AbstractLogger implements Logger {
       if (options.logThreshold !== undefined) {
          const level = ObservableValue.from(options.logThreshold);
          if (level.value) {
-            Logger.setLevel(level.value);
+            this.applyLevel(level.value, 'setting');
          }
          level.onChange(next => {
             if (next) {
-               Logger.setLevel(next);
+               this.applyLevel(next, 'setting');
             }
          });
       }
    }
 
+   /**
+    * Set the process-wide threshold and announce the transition under whichever
+    * of the two thresholds can carry the notice, so a reader sees every change
+    * after launch that one of them can carry.
+    *
+    * `error` and `off` admit no notice of their own — `off` nothing at all, and
+    * an error-severity line is read as a fault, which a client that marks its
+    * log as having seen an error keeps for the session. Entering either is
+    * therefore announced BEFORE the switch, under the outgoing threshold; every
+    * other change is announced after it, at the level being entered. Leaving
+    * `error` or `off` for one of those two says nothing, both thresholds being
+    * unable to carry it.
+    *
+    * Only on a real transition: the bound setting re-fires for configuration
+    * changes that leave the value alone.
+    *
+    * A `launch` baseline, the environment's, is announced only after the
+    * switch, so a run launched at `error` or `off` carries no notice. The
+    * threshold it leaves is a default no reader ran at, so a notice under it
+    * would be the one line of a run launched at `off`, and an info line in a
+    * run launched at `error`, against the launch's request.
+    */
+   protected applyLevel(next: LogThreshold, source: string, options: { launch?: boolean } = {}): void {
+      const previous = Logger.getLevel();
+      if (previous === next) {
+         return;
+      }
+      const message = `Log level ${previous} → ${next} (${source})`;
+      if (options.launch) {
+         Logger.setLevel(next);
+         if (next !== 'error') {
+            this.logAt(next, message);
+         }
+         return;
+      }
+      const announceFirst = next === 'error' || next === 'off';
+      if (announceFirst && previous !== 'error') {
+         this.logAt(previous, message);
+      }
+      Logger.setLevel(next);
+      if (!announceFirst) {
+         this.logAt(next, message);
+      }
+   }
+
    /**
     * Route logger timing and timestamps through the injected framework
     * {@link Clock} (the dedicated `shared.Clock` slot) so server-side log time
@@ -145,9 +211,7 @@ export class LspLogger extends AbstractLogger implements Logger {
    }
 
    protected emit(level: LogLevel, label: string, message: string, args: readonly unknown[]): void {
-      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 prefix = this.formatLinePrefix(label);
       const combined = args.length === 0 ? message : `${message} ${args.map(formatLogArg).join(' ')}`;
       const formatted = `${prefix} ${combined}`;
       const connection = this.services.lsp.Connection;
@@ -165,7 +229,11 @@ export class LspLogger extends AbstractLogger implements Logger {
       // 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)) {
+      //
+      // `send` admits a line either threshold takes, so the client sink checks
+      // its own; the file-tee filters for itself.
+      const toClient = LEVEL_ORDER[level] <= LEVEL_ORDER[Logger.getLevel()];
+      if (toClient && (!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` /
@@ -180,7 +248,7 @@ export class LspLogger extends AbstractLogger implements Logger {
       }
       // 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);
+      teeLogLine(level, formatted);
    }
 
    protected derive(component: string): this {
@@ -246,32 +314,3 @@ const LSP_CONSOLE: Record<LogLevel, (connection: Connection) => (message: string
    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: unknown): string {
-   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);
-}

package/src/langium/document-builder/build-pipeline-integration.ts

@@ -10,35 +10,11 @@
 import { type LangiumDocument, DocumentState } from '@hydranium/langium';
 import { type CancellationToken } from 'vscode-languageserver';
 import { IntegrityPhase } from '../integrity/integrity-rule.js';
-import { groupDocumentsByLanguage } from '../build-phase-pass/build-phase-pass.js';
+import { AstExtensionPhase } from '../ast-extension/ast-extension-service.js';
+import { BuildPassPhase, groupDocumentsByLanguage } from '../build-phase-pass/build-phase-pass.js';
 import { type ServerSharedServices } from '../module.js';
 import { labelPhaseListener } from './labeled-phase-listener.js';
 
-/**
- * AST extension wiring covers every "useful" `DocumentState` an extension can
- * target. `Changed` has no AST yet; `IndexedContent` carries the same
- * per-document information as `Parsed`. No-op fires for documents with no
- * extension at a given state are negligible (`notifyDocumentPhase` is a plain
- * listener loop), so the framework wires the full set unconditionally rather
- * than collecting declared states from per-language registrations.
- */
-const AST_EXTENSION_PHASES: readonly DocumentState[] = [
-   DocumentState.Parsed,
-   DocumentState.ComputedScopes,
-   DocumentState.Linked,
-   DocumentState.IndexedReferences,
-   DocumentState.Validated
-];
-
-/**
- * Build phases at which the `BuildPhasePassService` is driven. Same useful
- * set as {@link AST_EXTENSION_PHASES}: a pass registered at any other state
- * never fires (the listener is not wired), mirroring the AST-extension contract.
- * `runPasses` no-ops at a phase with no registered pass, so wiring the full set
- * unconditionally costs only an empty-bucket check per phase.
- */
-const BUILD_PHASE_PASS_STATES: readonly DocumentState[] = AST_EXTENSION_PHASES;
-
 /**
  * Default priority of the framework integrity passes. Integrity mutates / cleans
  * the AST that every derived-state pass reads, so it is *foundational* and must
@@ -65,6 +41,19 @@ export interface BuildPipelineIntegrationOptions {
    readonly integrityPriority?: number;
 }
 
+/**
+ * The build-pipeline slot. Empty because nothing calls this service — it wires
+ * itself in its constructor and every seam it offers is `protected`.
+ *
+ * Typing the slot by the class instead would stop an adopter's subclass
+ * satisfying it, since a class carries its `protected` members into the check
+ * and they compare by declaration rather than by shape. The cost of the empty
+ * shape is that any non-null value satisfies it, so a mis-bound slot compiles
+ * and the framework's phase listeners are then never attached.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- the slot has no public member to name
+export interface BuildPipelineIntegration {}
+
 /**
  * Wires the framework's build-time features (integrity rules, AST
  * enrichment) into Langium's document-build pipeline. The single shared
@@ -90,7 +79,7 @@ export interface BuildPipelineIntegrationOptions {
  * Eagerly constructed (via `DEFAULT_EAGER_SERVICES`) so the listeners are
  * attached before the first build cycle.
  */
-export class BuildPipelineIntegration {
+export class DefaultBuildPipelineIntegration implements BuildPipelineIntegration {
    constructor(
       protected readonly services: ServerSharedServices,
       options: BuildPipelineIntegrationOptions = {}
@@ -108,17 +97,19 @@ export class BuildPipelineIntegration {
       for (const phase of IntegrityPhase.all()) {
          passes.register({
             id: `framework:integrity:${IntegrityPhase.toString(phase).toLowerCase()}`,
-            state: phase,
+            phase,
             priority: integrityPriority,
             run: (documents, cancelToken) => this.callIntegrity(documents, phase, cancelToken)
          });
       }
 
-      // One onBuildPhase listener per pass state, routed through the overridable
+      // One onBuildPhase listener per pass phase, routed through the overridable
       // `runBuildPhase` seam → priority-ordered, sequential, cancel-aware pass
       // dispatch. The returned promise is awaited by the build pipeline, so a
-      // mutating pass (integrity) reparses before the build advances.
-      for (const phase of BUILD_PHASE_PASS_STATES) {
+      // mutating pass (integrity) reparses before the build advances. The full
+      // set is wired unconditionally: `runPasses` no-ops at a phase with no
+      // pass, so an unused listener costs one empty-bucket check.
+      for (const phase of BuildPassPhase.all()) {
          builder.onBuildPhase(
             phase,
             labelPhaseListener(
@@ -128,11 +119,21 @@ export class BuildPipelineIntegration {
          );
       }
 
+      // Per DOCUMENT as well: `reparseAndRelink` re-indexes one document from
+      // inside the `Linked` phase and fires no build-phase notification, so a
+      // batch-level listener cannot see the AST it replaced.
+      builder.onDocumentPhase(
+         DocumentState.IndexedContent,
+         labelPhaseListener(() => this.clearScopeCaches(), 'BuildPipeline.clearScopeCaches')
+      );
+
       // AST enrichment stays per-document (onDocumentPhase) and node-granular —
       // unchanged by the build-phase-pass registry, which is batch-granular. The
       // listener calls the `extendAst` seam directly (the document-phase analog of
       // `runBuildPhase`); there is no per-phase handler tier — one parameterized seam.
-      for (const phase of AST_EXTENSION_PHASES) {
+      // Wired for every phase unconditionally rather than for the phases the
+      // per-language registrations declare: a no-op fire is a plain listener loop.
+      for (const phase of AstExtensionPhase.all()) {
          builder.onDocumentPhase(
             phase,
             labelPhaseListener(
@@ -174,6 +175,19 @@ export class BuildPipelineIntegration {
       }
    }
 
+   /**
+    * Drop the cached scopes of every REGISTERED language, not of those owning a
+    * document in the batch. The index a scope is built from is
+    * workspace-global, so narrowing to the batch with
+    * {@link groupDocumentsByLanguage}, the way {@link callIntegrity} does,
+    * leaves a cross-grammar reference resolving against a mid-rebuild scope.
+    */
+   protected clearScopeCaches(): void {
+      for (const languageServices of this.services.ServiceRegistry.all) {
+         languageServices.references.ScopeProvider.clearScopeCaches();
+      }
+   }
+
    /** Run AST enrichment for a single document at `phase` via its language service. */
    protected extendAst(document: LangiumDocument, phase: DocumentState, cancelToken: CancellationToken): void {
       this.services.ServiceRegistry.getServices(document.uri).ast.AstExtensionService.extendDocument(document, phase, cancelToken);

package/src/langium/document-builder/build-session.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import { type URI } from '@hydranium/langium';
+import { type Stopwatch } from '@hydranium/protocol';
 
 /** What a build is about, handed to `HydraniumDocumentBuilder.createBuildSession`. */
 export interface BuildSessionContext {
@@ -59,14 +60,14 @@ export class BuildSession {
    traceId?: number;
    /** Set when the build ended in `OperationCancelled`, so the successor can tag itself "cancels #N". */
    cancelled = false;
-   /** Phase-reached lines produced so far; the first one measures from {@link startMs} rather than from the previous phase. */
+   /** Phase-reached lines produced so far; the first one measures from {@link sinceStart} rather than from the previous phase. */
    phasesLogged = 0;
    /** Lines held back by {@link detailThresholdMs}; flushed or dropped when the build ends. */
    readonly bufferedLines: string[] = [];
 
    constructor(
-      /** Millisecond timestamp the build started at, on the same clock as `performance.now()`. */
-      readonly startMs: number,
+      /** Running since the build started. */
+      readonly sinceStart: Stopwatch,
       /** What caused this build — a formatted URI, a count summary, or an adopter label. */
       readonly trigger: string,
       /** True when {@link trigger} already states the document count, so a phase line must not repeat it. */