@hydranium/cli 1.0.0-next.31 → 1.0.0-next.312

package/templates/server/src/glsp/__GRAMMAR_ID__/state.ts

@@ -0,0 +1,18 @@
+// GLSP state for the __GRAMMAR__ diagram.
+//
+// `FullTextHydraniumGlspState` is the simplest of the framework source-model
+// strategies (the others project a structured transfer model, over one document
+// or several): the source model is the whole document text, serialised through
+// the per-URI `Serializer` and round-tripped by re-parsing. Both seams resolve
+// through shared services, so narrowing the root type is all an adopter adds.
+//
+// It cannot field-merge — every concurrent edit on a whole-document model is a
+// same-document collision, so undo / redo degrade to drop-on-divergence. Move to
+// `ReconcilingTransferHydraniumGlspState` when you need field-level undo.
+
+import { FullTextHydraniumGlspState } from '@hydranium/glsp-server';
+import { injectable } from 'inversify';
+import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
+
+@injectable()
+export class __GRAMMAR__GlspState extends FullTextHydraniumGlspState<__ENTRY_RULE__> {}

package/templates/server/src/glsp/__GRAMMAR_ID__/storage.ts

@@ -0,0 +1,16 @@
+// Source-model storage for the __GRAMMAR__ diagram, inheriting both framework
+// defaults: `loadSourceModel` (open + settle + `setSourceRoot`) and
+// `saveSourceModel` (flush the store's text for the primary and every tracked
+// secondary through the diagram's client session).
+//
+// No serializer runs on the save path — a save persists what the diagram's
+// operations already wrote to the store.
+//
+// The subclass exists so a bespoke load or save has a stable place to land.
+
+import { type FullTextSourceModel, HydraniumGlspStorage } from '@hydranium/glsp-server';
+import { injectable } from 'inversify';
+import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
+
+@injectable()
+export class __GRAMMAR__GlspStorage extends HydraniumGlspStorage<__ENTRY_RULE__, FullTextSourceModel> {}

package/templates/server/src/glsp/__GRAMMAR_ID__/submission-handler.ts

@@ -0,0 +1,24 @@
+// Submission handler for the __GRAMMAR__ diagram.
+//
+// Inherits the framework's `readyEvent = IntegrityService.SettledState`, which
+// is load-bearing rather than incidental: the GModel factory resolves
+// `target.ref`, so it needs a fully-linked AST. Without the gate those reads
+// fire mid-build and warn about resolution before scopes are computed.
+//
+// Only `formatSourceRoot` is overridden, so the submit log names the model and
+// its node count instead of a bare `$type`.
+
+import { ModelState } from '@eclipse-glsp/server';
+import { type FullTextSourceModel, HydraniumGlspSubmissionHandler } from '@hydranium/glsp-server';
+import { inject, injectable } from 'inversify';
+import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
+import type { __GRAMMAR__GlspState } from './state.js';
+
+@injectable()
+export class __GRAMMAR__SubmissionHandler extends HydraniumGlspSubmissionHandler<__ENTRY_RULE__, FullTextSourceModel> {
+   @inject(ModelState) declare protected modelState: __GRAMMAR__GlspState;
+
+   protected override formatSourceRoot(root: __ENTRY_RULE__ | undefined): string {
+      return root ? `__ENTRY_RULE__ nodes=${root.nodes.length}` : 'none';
+   }
+}

package/templates/server/src/grammar/common.langium

@@ -0,0 +1,12 @@
+// Shared lexical basis for this project's grammars. Imported, never registered:
+// it has no entry rule and no `langium-config.json` entry, so it is a fragment
+// rather than a language.
+//
+// Keeping the tokens here rather than in one of the languages means a grammar
+// imports `common` for its TOKENS and another language only when it needs that
+// language's TYPES — separate reasons that are worth keeping separate.
+
+hidden terminal WS: /\s+/;
+terminal ID: /[_a-zA-Z][\w_]*/;
+hidden terminal SL_COMMENT: /\/\/[^\n\r]*/;
+hidden terminal ML_COMMENT: /\/\*[\s\S]*?\*\//;

package/templates/server/src/language-server/__GRAMMAR_ID__-serializer.ts

@@ -0,0 +1,53 @@
+// Concrete-syntax emitter for __GRAMMAR__ — the parser's inverse, turning a
+// model back into text this grammar accepts. Derived from the starter grammar
+// exactly as `generated/ast.ts` is, so replacing the grammar replaces this too.
+//
+// Without it every structured write fails: the framework's default binding at
+// `services.serializer.Serializer` THROWS, because a concrete syntax is
+// language knowledge no framework can derive. A client session's `update` /
+// `save`, the data head's `saveModelDocument` and a GLSP `SaveModelAction`
+// all reach it.
+//
+// `AbstractSerializer`'s generic property walk lays out FORMAT-structured
+// output — its YAML and JSON subclasses are what it exists for — and cannot
+// produce a keyword-delimited syntax like `node a -> b`. So `serializeNode` is
+// a per-`$type` emitter here and the two array hooks are unreachable.
+
+import { AbstractSerializer } from '@hydranium/core';
+import type { AstNode } from '@hydranium/langium';
+import { type __ENTRY_RULE__, type __NODE_RULE__, is__ENTRY_RULE__, is__NODE_RULE__ } from './ast.js';
+
+export class __GRAMMAR__Serializer extends AbstractSerializer<__ENTRY_RULE__> {
+   protected override serializeNode(node: AstNode | Record<string, unknown>): string {
+      if (is__ENTRY_RULE__(node)) {
+         return node.nodes.map(child => this.emitNode(child)).join('\n');
+      }
+      if (is__NODE_RULE__(node)) {
+         return this.emitNode(node);
+      }
+      // Defensive: a rule added to the grammar with no emitter added here.
+      throw new Error(`__GRAMMAR__Serializer: no emitter for $type ${(node as AstNode).$type}`);
+   }
+
+   /** Unreachable — this grammar's one list is emitted by its `__ENTRY_RULE__` parent. */
+   protected override serializeArray(): string {
+      throw new Error('__GRAMMAR__Serializer: arrays are emitted by the per-$type parent, not the generic dispatch.');
+   }
+
+   /** Unreachable — same reasoning as {@link serializeArray}. */
+   protected override serializeReferenceArray(): string {
+      throw new Error('__GRAMMAR__Serializer: reference arrays are emitted by the per-$type parent, not the generic dispatch.');
+   }
+
+   /**
+    * `serializeReferenceText` rather than `node.target?.$refText`: it is the one
+    * read that spans BOTH input shapes. A transfer model reaching
+    * `serializeTransfer` carries `target` as a plain string rather than a
+    * `Reference`, and a serializer that reaches for `$refText` directly emits
+    * the AST correctly and drops every reference on the transfer path.
+    */
+   private emitNode(node: __NODE_RULE__): string {
+      const target = this.serializeReferenceText(node.target);
+      return target === undefined ? `node ${node.name}` : `node ${node.name} -> ${target}`;
+   }
+}

package/templates/server/src/language-server/ast.ts

@@ -0,0 +1,23 @@
+// The language's AST entry point: a re-export of what `langium generate`
+// emits, plus anywhere you augment those types.
+//
+// Import the AST from HERE rather than from `./generated/ast.js`, so any
+// augmentation below travels with every import. One `langium-cli` run over N
+// grammars emits ONE combined AST module sharing one reflection, so a further
+// grammar needs no change here.
+//
+// `generate:transfer-model` reads this file as its `--augmentation-file`: the
+// generated wire types are derived from the AST *as augmented*, not from the
+// raw generated module. Augment a type here and the transfer model follows.
+//
+// A `@derived` property is computed at build time rather than parsed, so it is
+// declared here and populated by an AST-extension contribution:
+//
+// declare module './generated/ast.js' {
+//    interface __ENTRY_RULE__ {
+//       /** @derived Populated by an `ast.extensions.computedProperties` contribution. */
+//       readonly _summary?: string;
+//    }
+// }
+
+export * from './generated/ast.js';

package/templates/server/src/node/services.ts

@@ -0,0 +1,16 @@
+// Zero-arg service factory for the headless `hydranium-cli` tooling: the
+// `reflect` / `lint-grammar` / `validate` subcommands import this via
+// `--services ./lib/node/services.js`. The head wires its own filesystem here.
+//
+// Behind the package's `./node` entry rather than its root because it reads
+// the real filesystem: the root stays loadable in a browser worker, which has
+// no `node:fs`.
+//
+// The contract is language-count-agnostic — a second grammar needs no edit here.
+
+import { NodeFileSystem } from '@hydranium/core/node';
+import { create__NAME__Services } from '../language-server/__PROJECT_ID__-module.js';
+
+export function createServices(): ReturnType<typeof create__NAME__Services> {
+   return create__NAME__Services({ ...NodeFileSystem });
+}

package/templates/server/test/__GRAMMAR_ID__-diagram.test.ts

@@ -0,0 +1,112 @@
+// The starter diagram, run the way a client runs it: an in-process GLSP server
+// opens a document. A create-node operation adds a node, and an undo and a redo
+// take it out and put it back; every step must keep the nodes the document
+// already had, and its comments, since the diagram writes the document from its
+// AST, which carries none. A reference into another document draws no edge,
+// since the graph holds no node for its target, but resolves, even when the
+// diagram opened its document before the workspace was up.
+
+import 'reflect-metadata';
+import { type Action, CreateNodeOperation, RedoAction, ServerModule, SetDirtyStateAction, UndoAction } from '@eclipse-glsp/server';
+import { initializeWorkspaceProgrammatically } from '@hydranium/core';
+import { makeScratchWorkspace, type ScratchWorkspace } from '@hydranium/core/testing/node';
+import { HydraniumGlspAppModule } from '@hydranium/glsp-server';
+import { type GlspHarness, makeGlspHarness } from '@hydranium/glsp-server/testing';
+import { waitFor } from '@hydranium/protocol/testing';
+import { __GRAMMAR_ID_CONST___DIAGRAM_TYPE, __GRAMMAR_ID_CONST___NODE_TYPE } from '__PROTOCOL_PACKAGE__';
+import { afterEach, describe, expect, it } from 'vitest';
+import { __GRAMMAR__DiagramModule } from '../src/glsp/__GRAMMAR_ID__/diagram-module.js';
+import type { __GRAMMAR__GlspState } from '../src/glsp/__GRAMMAR_ID__/state.js';
+import { createServices } from '../src/node/services.js';
+
+let workspace: ScratchWorkspace | undefined;
+let diagram: GlspHarness<__GRAMMAR__GlspState> | undefined;
+
+afterEach(() => {
+   diagram?.dispose();
+   workspace?.dispose();
+   diagram = undefined;
+   workspace = undefined;
+});
+
+/** Send `action` and wait for the dirty state the server answers it with, which it sends once the edit is written. */
+async function send(harness: GlspHarness<__GRAMMAR__GlspState>, action: Action, reason: string): Promise<void> {
+   const before = harness.actions.length;
+   harness.dispatch(action);
+   await waitFor(() => harness.actions.slice(before).some(sent => SetDirtyStateAction.is(sent) && sent.reason === reason), {
+      message: `no '${reason}' dirty state`
+   });
+}
+
+describe('__GRAMMAR__ diagram', () => {
+   it('creates a node after the existing ones, keeping their comments, and undoes and redoes it', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      const original = '// keep this comment\nnode first -> second\n// about second\nnode second';
+      const file = workspace.write('model.__EXTENSION__', original);
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      diagram = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      await diagram.start();
+      await diagram.openDocument(file);
+      const uri = workspace.uri('model.__EXTENSION__');
+      const text = (): string | undefined => shared.workspace.TextDocuments.get(uri)?.getText();
+
+      await send(diagram, CreateNodeOperation.create(__GRAMMAR_ID_CONST___NODE_TYPE), 'operation');
+      const created = text();
+      await send(diagram, UndoAction.create(), 'undo');
+      const undone = text();
+      await send(diagram, RedoAction.create(), 'redo');
+
+      expect({ created, undone, redone: text() }).toEqual({
+         created: `${original}\nnode Node`,
+         undone: original,
+         redone: `${original}\nnode Node`
+      });
+   });
+
+   it('draws no edge for a reference that resolves into another document', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      workspace.write('declaring.__EXTENSION__', 'node second');
+      const file = workspace.write('referencing.__EXTENSION__', 'node first -> second');
+      const { shared } = createServices();
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      diagram = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      await diagram.start();
+      await diagram.openDocument(file);
+
+      // The reference resolves, so the missing edge is the document rule and
+      // not a dangling reference.
+      expect(diagram.state.sourceRoot?.nodes[0].target?.ref?.name).toBe('second');
+      expect(diagram.state.root.children.map(child => child.type)).toEqual([__GRAMMAR_ID_CONST___NODE_TYPE]);
+   });
+
+   it('resolves a cross-document reference in a document opened before the workspace is up', async () => {
+      workspace = makeScratchWorkspace({ prefix: '__GRAMMAR_ID__-diagram-' });
+      workspace.write('declaring.__EXTENSION__', 'node second');
+      const file = workspace.write('referencing.__EXTENSION__', 'node first -> second');
+      const { shared } = createServices();
+      diagram = makeGlspHarness<__GRAMMAR__GlspState>({
+         serverModule: new ServerModule().configureDiagramModule(new __GRAMMAR__DiagramModule()),
+         diagramType: __GRAMMAR_ID_CONST___DIAGRAM_TYPE,
+         appModules: [new HydraniumGlspAppModule({ shared })]
+      });
+      await diagram.start();
+      // The open waits for the workspace. One that did not would have linked
+      // within this timer against a workspace holding only itself, and the
+      // bring-up does not relink it. Its budget covers the bring-up as well.
+      const opening = diagram.openDocument(file, 10_000);
+      await new Promise(resolve => setTimeout(resolve, 200));
+      await initializeWorkspaceProgrammatically(shared, workspace.root);
+      await opening;
+
+      expect(diagram.state.sourceRoot?.nodes[0].target?.ref?.name).toBe('second');
+   });
+});

package/templates/server/test/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.test.json",
+  "include": ["../src", ".", "../src/**/*.json"]
+}

package/templates/server/tsconfig.test.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true,
+    "isolatedModules": true,
+    "types": ["node"]
+  },
+  "include": ["src", "test", "src/**/*.json"]
+}

package/templates/server/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+
+// Vitest transforms TypeScript itself and resolves `.js` specifiers to their
+// `.ts` source, so tests import from `../src/` with the same specifiers the
+// compiled output uses. `include` is scoped to `test/` so `lib/` is never
+// scanned; `npm test` runs `typecheck:test` first, because vitest's
+// transform strips types without checking them.
+
+export default defineConfig({
+   test: {
+      environment: 'node',
+      include: ['test/**/*.{test,spec}.ts']
+   }
+});

package/templates/workspace/nodes.__EXTENSION__

@@ -0,0 +1,5 @@
+/** The first node. Hover a name to read its comment. */
+node First
+
+/** A second node, pointing at the first in the same file. */
+node Second -> First

package/templates/workspace/references.__EXTENSION__

@@ -0,0 +1,2 @@
+/** Points at a node declared in nodes.__EXTENSION__: hover the target to read its comment from there. */
+node Third -> Second