@hydranium/core 1.0.0-next.10

package/src/langium/project/project-change-event.ts

@@ -0,0 +1,66 @@
+/********************************************************************************
+ * 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 { Project } from '@hydranium/protocol';
+import type { URI } from '@hydranium/langium';
+
+/**
+ * Event emitted by `ProjectManager.onProjectsChanged` when the project
+ * registry diffs after a workspace update. Reports both the registry-level
+ * diff (which projects appeared / changed / disappeared) and the document-
+ * level fallout (which documents need to rebuild because their reachable
+ * scope changed).
+ *
+ * - {@link added} / {@link updated} carry **project ids**, not {@link Project}
+ *   objects. The full {@link Project} can be retrieved via
+ *   `ProjectManager.getProjectById`.
+ * - {@link removed} carries **{ id, snapshot }** pairs — by the time the event
+ *   fires the registry has already cleared the project, so each entry bundles
+ *   the id with the pre-removal snapshot so consumers can read the project's
+ *   metadata (version, dependencies, plus any subclass-extended fields)
+ *   without maintaining their own shadow registry.
+ * - {@link affectedDocuments} lists URIs whose reachable scope changed. The
+ *   default cascade plumbing in `HydraniumWorkspaceManager` subscribes to
+ *   this event and re-runs `DocumentBuilder.resetToState` for each entry,
+ *   which the next build cycle picks up. Consumers can subscribe
+ *   independently for other reactions.
+ */
+export interface ProjectChangeEvent<TProject extends Project = Project> {
+   /** Ids of projects newly registered since the last event. */
+   readonly added: readonly string[];
+
+   /**
+    * Ids of projects re-parsed from a changed descriptor that kept the same
+    * id. A descriptor that now names a *different* id is reported as a
+    * removal of the old id plus an addition of the new one, never here.
+    */
+   readonly updated: readonly string[];
+
+   /**
+    * Projects no longer in the registry, paired with their pre-removal
+    * snapshot. The id and snapshot are bundled per-entry so consumers
+    * never need to zip parallel arrays by index.
+    */
+   readonly removed: ReadonlyArray<{ readonly id: string; readonly snapshot: TProject }>;
+
+   /**
+    * Documents whose reachable scope changed and therefore need to
+    * rebuild. Includes the changed projects' own member documents plus
+    * any transitive dependents according to the concrete
+    * `ProjectManager`'s visibility model (see
+    * `AbstractProjectManager.getAffectedProjects`).
+    *
+    * Descriptor URIs themselves are intentionally excluded: they triggered
+    * this cycle and re-adding them would loop.
+    */
+   readonly affectedDocuments: readonly URI[];
+}
+
+/** Callback shape for `ProjectManager.onProjectsChanged`. */
+export type ProjectChangeListener<TProject extends Project = Project> = (event: ProjectChangeEvent<TProject>) => void;

package/src/langium/project/project-manager.ts

@@ -0,0 +1,221 @@
+/********************************************************************************
+ * 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 { Project } from '@hydranium/protocol';
+import type { AstNode, URI } from '@hydranium/langium';
+import type { Disposable } from 'vscode-languageserver';
+import type { WorkspaceFolder } from 'vscode-languageserver-types';
+import type { ProjectChangeListener } from './project-change-event.js';
+
+/**
+ * Manages the **project tier** sitting between the LSP `WorkspaceFolder`
+ * (protocol-owned: URI + display name only) and `LangiumDocument`
+ * (Langium-owned: per-file parse + index + state). Owns project discovery,
+ * registry maintenance, and the cascade signal for documents whose
+ * reachable scope changed when a project changed.
+ *
+ * Langium does not provide a project tier and explicitly does not intend
+ * to add one — see [Discussion #1375 — *Multiple Languages from different
+ * Projects*](https://github.com/eclipse-langium/langium/discussions/1375).
+ * `@hydranium/core` provides this tier so consumers don't have to
+ * reinvent it.
+ *
+ * ## Lifecycle
+ *
+ * 1. `HydraniumWorkspaceManager.performStartup` awaits {@link discoverProjects}
+ *    as **phase 0**, before Langium's file-discovery and document-loading
+ *    phases. By the time any non-descriptor document hits `Parsed`, the
+ *    registry is fully populated and {@link getProject} returns a
+ *    definitive answer.
+ * 2. {@link ready} resolves at the end of phase 0. Code that depends on
+ *    project membership during startup (AST extensions running at
+ *    `IndexedContent`, integrity rules, scope providers) awaits this.
+ * 3. After startup, the abstract `AbstractProjectManager` base auto-
+ *    subscribes to `DocumentBuilder.onUpdate` to track incremental
+ *    changes to descriptor files; each relevant update fires
+ *    {@link onProjectsChanged} with the registry diff + affected
+ *    documents, and `HydraniumWorkspaceManager` re-runs
+ *    `DocumentBuilder.resetToState` on the affected URIs to cascade
+ *    the rebuild.
+ *
+ * ## Implementations
+ *
+ * - **`SingleProjectManager`** — the framework default. One synthetic
+ *   project owns every document, so visibility queries answer
+ *   "everything sees everything" and consumers without a project tier
+ *   pay zero cost.
+ * - **`AbstractProjectManager`** — abstract base for project-aware
+ *   consumers, carrying the registry, the `DocumentBuilder.onUpdate`
+ *   subscription, the event channel, and the cascade computation.
+ */
+export interface ProjectManager<TProject extends Project = Project> {
+   // ============================================================
+   // Lifecycle
+   // ============================================================
+
+   /**
+    * Phase-0 discovery. Called once during workspace startup, before any
+    * non-descriptor documents are loaded. Implementations walk the given
+    * workspace folders for descriptor files (whatever the consumer defines
+    * as such via {@link isProjectDescriptor}), parse them, and populate the
+    * registry. After this method resolves, {@link ready} resolves.
+    *
+    * Implementations may emit an initial {@link onProjectsChanged} with
+    * `added` populated. The empty-registry case (no descriptors found) is
+    * valid and emits nothing.
+    */
+   discoverProjects(folders: readonly WorkspaceFolder[]): Promise<void>;
+
+   /**
+    * Resolves at the end of {@link discoverProjects}.
+    *
+    * `SingleProjectManager` resolves this synchronously at construction
+    * time — consumers can await it safely without triggering a hang when
+    * no project tier is wired.
+    */
+   readonly ready: Promise<void>;
+
+   /**
+    * Subscribe to project add / update / remove events. Fires whenever
+    * the registry changes — both during incremental rebuilds (descriptor
+    * file edited / deleted) and as a single event at the end of
+    * {@link discoverProjects} when projects were found.
+    *
+    * Returns a `Disposable` that unregisters the listener.
+    */
+   onProjectsChanged(listener: ProjectChangeListener<TProject>): Disposable;
+
+   // ============================================================
+   // Queries
+   // ============================================================
+
+   /**
+    * The {@link Project} owning the given document URI, or `undefined` if
+    * the URI does not belong to any project. Membership is determined by
+    * the concrete implementation.
+    *
+    * `SingleProjectManager` always returns its synthetic workspace project —
+    * never `undefined` — so consumers can rely on a non-null answer when
+    * no project tier is wired (matches Langium's flat-scope default).
+    */
+   getProject(uri: URI | string): TProject | undefined;
+
+   /**
+    * The {@link Project} owning the document `node` belongs to, or `undefined`
+    * (including when `node` is not attached to a document). Convenience over
+    * {@link getProject} that centralizes the node→root-document→URI derivation
+    * that callers would otherwise hand-roll (and risk skipping URI
+    * normalization on). No `getProjectForDocument` sibling — `getProject(document.uri)`
+    * is already a bare access, so a wrapper would hide nothing.
+    */
+   getProjectForNode(node: AstNode): TProject | undefined;
+
+   /** Look up a project by its {@link Project.id}. */
+   getProjectById(id: string): TProject | undefined;
+
+   /** Snapshot of all projects currently in the registry. */
+   getProjects(): readonly TProject[];
+
+   /**
+    * URIs of documents that belong to the given project. Returns an
+    * empty array if the project id is unknown.
+    */
+   getProjectUris(projectId: string): readonly URI[];
+
+   /**
+    * Project ids visible from the given project: the project itself plus
+    * the transitive closure of declared dependencies according to the
+    * concrete implementation's visibility model. Returns an empty array
+    * if the project id is unknown.
+    *
+    * Default behaviour in `AbstractProjectManager` is the **transitive
+    * closure** of {@link Project.dependencies}, including the project
+    * itself. An adopter can override to use a different visibility model.
+    *
+    * `SingleProjectManager` returns `[id]` for its synthetic workspace
+    * project, which combined with "synthetic project owns every URI"
+    * yields "everything is visible to everything" — Langium's flat-
+    * scope behaviour preserved.
+    */
+   getVisibleProjects(projectId: string): readonly string[];
+
+   /**
+    * Convenience predicate over {@link getVisibleProjects}: returns true
+    * iff `targetProjectId` is in the visibility set of `sourceProjectId`.
+    * Unknown source ids (empty visibility set) always return false.
+    *
+    * @param selfVisible when `sourceProjectId === targetProjectId`,
+    *        controls whether the project is considered visible to itself.
+    *        Reference-construction callers pass `true` (a project sees
+    *        its own elements); strict cross-project walks pass `false`.
+    *        Default: `false`.
+    *
+    * **The `false` default is deliberate, and stays that way while the only
+    * production caller passes `true`.** Flipping it to match that caller
+    * would make a configure-time default out of a single hardcoded
+    * argument — the same decision, written where the reader cannot see it.
+    * Per-call explicitness keeps the *why* at the call site instead. Revisit
+    * if a second non-test caller appears, or if an audit-strict caller
+    * genuinely wants `false`.
+    */
+   isVisible(sourceProjectId: string, targetProjectId: string, selfVisible?: boolean): boolean;
+
+   // ============================================================
+   // Virtual hooks (consumer-implementable)
+   // ============================================================
+
+   /**
+    * Fast-path predicate: true when the workspace has at most one
+    * meaningful project boundary. Enables a fast-path in the framework's
+    * `HydraniumScopeProvider.getProjectScope` that returns the
+    * unfiltered global scope when project filtering would be a no-op.
+    *
+    * Default implementations:
+    * - `SingleProjectManager`: returns `true` unconditionally (its
+    *   synthetic workspace project owns everything).
+    * - `AbstractProjectManager`: returns `getProjects().length <= 1`
+    *   (conservative — once a second project is registered, returns
+    *   false even if all documents are still owned by the original).
+    *
+    * Adopters with custom `ProjectManager` implementations override to
+    * match their workspace shape.
+    */
+   isSingleProject(): boolean;
+
+   /**
+    * Predicate: is the given URI a project descriptor file?
+    *
+    * Determines which URIs participate in project discovery (during
+    * {@link discoverProjects}) and incremental tracking (via the
+    * auto-subscription to `DocumentBuilder.onUpdate` inside
+    * `AbstractProjectManager`).
+    *
+    * Default in `SingleProjectManager`: returns `false`. Single-project /
+    * project-less consumers get the default and never participate in
+    * descriptor tracking.
+    */
+   isProjectDescriptor(uri: URI | string): boolean;
+
+   /**
+    * Whether the project owning `uri` uses unqualified references — i.e.
+    * its {@link Project.referenceName} equals the
+    * `UNQUALIFIED_PROJECT_REFERENCE` sentinel, or `uri` is not owned by
+    * any project. The predicate exists so callers that would otherwise
+    * compose a project prefix can skip the composition without reaching
+    * for the sentinel value themselves; an implementation that can answer
+    * without a full membership lookup overrides it.
+    *
+    * Default implementations:
+    * - `SingleProjectManager`: always `true` — its synthetic workspace
+    *   project is constructed with the sentinel.
+    * - `AbstractProjectManager`: the owning project is absent, or its
+    *   `referenceName` is the sentinel.
+    */
+   isUnqualifiedProjectReference(uri: URI | string): boolean;
+}

package/src/langium/project/single-project-manager.ts

@@ -0,0 +1,126 @@
+/********************************************************************************
+ * 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 Project, type Tracer, UNQUALIFIED_PROJECT_REFERENCE } from '@hydranium/protocol';
+import { type AstNode, type LangiumDocuments, type URI } from '@hydranium/langium';
+import { Disposable } from 'vscode-languageserver';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
+import type { ProjectChangeListener } from './project-change-event.js';
+import type { ProjectManager } from './project-manager.js';
+
+/**
+ * Framework default {@link ProjectManager}. Exposes a single synthetic
+ * project ({@link SingleProjectManager.WORKSPACE_PROJECT_ID}) that owns
+ * every document in the workspace, so visibility queries answer
+ * **"everything is visible to everything"** — preserving Langium's
+ * default flat-scope behaviour.
+ *
+ * The class name describes the state literally: one project. Consumers
+ * without a project tier (tests / single-grammar adopters) bind
+ * this and pay zero cost. No descriptor tracking, no incremental work,
+ * no events ever fire from {@link onProjectsChanged}.
+ *
+ * For project-aware consumers, extend `AbstractProjectManager` instead.
+ */
+export class SingleProjectManager implements ProjectManager {
+   /**
+    * Identity of the synthetic project. Prefixed with `@` so it cannot
+    * collide with a descriptor-derived project id, which by convention
+    * never begins with `@`.
+    */
+   static readonly WORKSPACE_PROJECT_ID = '@workspace';
+
+   protected readonly project: Project = {
+      id: SingleProjectManager.WORKSPACE_PROJECT_ID,
+      referenceName: UNQUALIFIED_PROJECT_REFERENCE
+   };
+   readonly ready = Promise.resolve();
+
+   protected readonly langiumDocuments: LangiumDocuments;
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: ServerSharedServicesMinimal,
+      options: LogNameOptions = {}
+   ) {
+      this.langiumDocuments = services.workspace.LangiumDocuments;
+      this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+   }
+
+   /** No-op: there are no descriptors to discover. */
+   async discoverProjects(): Promise<void> {
+      // no-op
+   }
+
+   /** Never fires — `SingleProjectManager` exposes a fixed registry. The returned disposable is a safe no-op. */
+   onProjectsChanged(_listener: ProjectChangeListener): Disposable {
+      return Disposable.create(() => undefined);
+   }
+
+   isProjectDescriptor(_uri: URI | string): boolean {
+      return false;
+   }
+
+   /** Always `true` — single-project by definition. */
+   isSingleProject(): boolean {
+      return true;
+   }
+
+   /**
+    * Always `true` — the synthetic workspace project is constructed with
+    * {@link UNQUALIFIED_PROJECT_REFERENCE}, so every URI it owns is by
+    * definition unqualified.
+    */
+   isUnqualifiedProjectReference(_uri: URI | string): boolean {
+      return true;
+   }
+
+   /** Every URI belongs to the synthetic workspace project. */
+   getProject(_uri: URI | string): Project | undefined {
+      return this.project;
+   }
+
+   /** Every node belongs to the synthetic workspace project. */
+   getProjectForNode(_node: AstNode): Project | undefined {
+      return this.project;
+   }
+
+   getProjectById(id: string): Project | undefined {
+      return id === SingleProjectManager.WORKSPACE_PROJECT_ID ? this.project : undefined;
+   }
+
+   getProjects(): readonly Project[] {
+      return [this.project];
+   }
+
+   /** All workspace URIs belong to the synthetic project; any other id yields `[]`. */
+   getProjectUris(projectId: string): readonly URI[] {
+      if (projectId !== SingleProjectManager.WORKSPACE_PROJECT_ID) {
+         return [];
+      }
+      return Array.from(this.langiumDocuments.all, document => document.uri);
+   }
+
+   /** Self-only visibility, combined with single-project ownership = "everything sees everything." */
+   getVisibleProjects(projectId: string): readonly string[] {
+      return projectId === SingleProjectManager.WORKSPACE_PROJECT_ID ? [SingleProjectManager.WORKSPACE_PROJECT_ID] : [];
+   }
+
+   /** Synthetic project sees itself iff `selfVisible`; cross-project queries always false. */
+   isVisible(sourceProjectId: string, targetProjectId: string, selfVisible = false): boolean {
+      if (sourceProjectId !== SingleProjectManager.WORKSPACE_PROJECT_ID) {
+         return false;
+      }
+      if (sourceProjectId === targetProjectId) {
+         return selfVisible;
+      }
+      return false;
+   }
+}