@hydranium/cli 1.0.0-next.42 → 1.0.0-next.420

package/src/commands/generate-transfer-builder.ts

@@ -0,0 +1,101 @@
+/********************************************************************************
+ * Copyright (c) 2026 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 * as fs from 'fs';
+import * as path from 'path';
+import { describeError } from '@hydranium/protocol';
+import { relativeImportPath } from './generated-module-path.js';
+
+/** Inputs for {@link emitTransferBuilder}, resolved by the transfer-model command. */
+export interface EmitTransferBuilderOptions {
+   /** Destination path for the generated builder module. */
+   outFile: string;
+   /** Path of the generated transfer model the builder binds to. */
+   transferModelFile: string;
+   /** Language id derived from the `<LanguageId>AstReflection` class name. */
+   languageId: string;
+   /** Header line naming the command that regenerates the file. */
+   regenCommand: string;
+}
+
+/**
+ * Emit a test module binding `makeTransferNodeBuilder` to the transfer model's
+ * reflection and type map, as `transferNode`.
+ *
+ * The module usually sits in a test tree of the server package while the
+ * transfer model sits in a protocol package of its own, and a relative import
+ * would reach into that package's sources. Across packages it therefore imports
+ * the model by the package's name, which relies on the package's main entry
+ * re-exporting the generated model; within one package it imports by path.
+ */
+export function emitTransferBuilder(options: EmitTransferBuilderOptions): void {
+   const content = buildTransferBuilderSource(options);
+   fs.mkdirSync(path.dirname(options.outFile), { recursive: true });
+   if (fs.existsSync(options.outFile) && fs.readFileSync(options.outFile, 'utf-8') === content) {
+      console.log('Transfer builder is up to date.');
+      return;
+   }
+   fs.writeFileSync(options.outFile, content, 'utf-8');
+   console.log(`Generated: ${options.outFile}`);
+}
+
+/** The module text {@link emitTransferBuilder} would write. */
+export function buildTransferBuilderSource(options: EmitTransferBuilderOptions): string {
+   const modelPackage = owningPackage(options.transferModelFile);
+   const specifier =
+      modelPackage !== undefined && modelPackage.dir !== owningPackage(options.outFile)?.dir
+         ? modelPackage.name
+         : relativeImportPath(options.outFile, options.transferModelFile);
+   const reflection = `${options.languageId}TransferReflection`;
+   const typeMap = `${options.languageId}TransferTypes`;
+   return [
+      '/******************************************************************************',
+      ' * Generated from the Langium AST — DO NOT EDIT MANUALLY!',
+      ` * ${options.regenCommand}`,
+      ' ******************************************************************************/',
+      '',
+      '/* eslint-disable */',
+      '',
+      "import { makeTransferNodeBuilder } from '@hydranium/protocol/testing';",
+      `import { ${reflection}, type ${typeMap} } from '${specifier}';`,
+      '',
+      '/**',
+      " * Transfer-node factory for this project's grammar, for tests. It fills the",
+      ' * grammar defaults, so a test names only the fields it cares about;',
+      ' * `transferNode.partial` fills none and types the node as incomplete.',
+      ' */',
+      `export const transferNode = makeTransferNodeBuilder<${typeMap}, typeof ${reflection}>(${reflection});`,
+      ''
+   ].join('\n');
+}
+
+/** The nearest `package.json` at or above `file` that names a package. */
+function owningPackage(file: string): { dir: string; name: string } | undefined {
+   let dir = path.dirname(path.resolve(file));
+   for (;;) {
+      const manifest = path.join(dir, 'package.json');
+      if (fs.existsSync(manifest)) {
+         let parsed: unknown;
+         try {
+            parsed = JSON.parse(fs.readFileSync(manifest, 'utf-8'));
+         } catch (error: unknown) {
+            throw new Error(`Cannot read '${manifest}' to name the transfer model's package: ${describeError(error)}`);
+         }
+         const name = typeof parsed === 'object' && parsed !== null && 'name' in parsed ? parsed.name : undefined;
+         if (typeof name === 'string') {
+            return { dir, name };
+         }
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) {
+         return undefined;
+      }
+      dir = parent;
+   }
+}

package/src/commands/generate-transfer-model-args.ts

@@ -30,6 +30,8 @@ export const GENERATE_TRANSFER_MODEL_FLAGS: readonly string[] = [
    '--augmentation-file',
    '--out-file',
    '--ast-builder-file',
+   '--transfer-builder-file',
+   '--languages-file',
    '--element-type-name',
    '--terminals-name',
    '--terminals-source-name',
@@ -50,11 +52,12 @@ export const GENERATE_TRANSFER_MODEL_HELP: readonly string[] = [
    'Usage: hydranium-cli generate-transfer-model [options]',
    '',
    'Generate a serializable transfer-model TypeScript file from a Langium AST, and',
-   'optionally an AST-node builder module bound to the same reflection. The',
-   'required inputs (--ast-file / --augmentation-file / --out-file) may instead come',
-   'from a --config JSON file, and --ast-file can be auto-discovered from a Langium',
-   "config's `out` directory. Precedence, highest first: explicit flags, then the",
-   '--config file, then the langium-config-derived --ast-file.',
+   'optionally an AST-node builder bound to the same reflection and a transfer-node',
+   'builder for tests. The required inputs (--ast-file / --augmentation-file /',
+   '--out-file) may instead come from a --config JSON file, and --ast-file can be',
+   "auto-discovered from a Langium config's `out` directory. Precedence, highest",
+   'first: explicit flags, then the --config file, then the langium-config-derived',
+   '--ast-file.',
    '',
    'Options:',
    '  --config <path>               JSON config supplying any of the options below.',
@@ -74,6 +77,12 @@ export const GENERATE_TRANSFER_MODEL_HELP: readonly string[] = [
    '                                spanning all of them. Omit if nothing constructs',
    '                                AST nodes. Same restriction as --out-file: keep it',
    "                                out of langium-cli's own `out` directory.",
+   '  --transfer-builder-file <p>   Also emit a test module here binding',
+   '                                makeTransferNodeBuilder to the transfer model as',
+   '                                transferNode. Import it from tests only.',
+   "  --languages-file <path>       Also emit each grammar's language id and file",
+   '                                extensions here, read from the module.ts beside',
+   '                                --ast-file, for a package without Langium.',
    '  --element-type-name <name>    Base element type name in output. Default: TransferElement.',
    '  --terminals-name <name>       Terminals const name in output. Default: ModelTerminals.',
    '  --terminals-source-name <n>   Source-side terminals variable name. Default: <LanguageId>Terminals.',
@@ -130,6 +139,12 @@ export function parseGenerateOptions(args: string[], onError: UsageError = exitW
          case '--ast-builder-file':
             flags.astBuilderFile = next();
             break;
+         case '--transfer-builder-file':
+            flags.transferBuilderFile = next();
+            break;
+         case '--languages-file':
+            flags.languagesFile = next();
+            break;
          case '--element-type-name':
             flags.elementTypeName = next();
             break;

package/src/commands/generate-transfer-model-config.ts

@@ -9,10 +9,11 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { describeError } from '@hydranium/protocol';
 import type { GenerateTransferModelOptions } from './generate-transfer-model.js';
 
 /** Path-valued option keys — resolved relative to a config/langium-config file's directory. */
-const PATH_KEYS = ['astFile', 'augmentationFile', 'outFile', 'astBuilderFile'] as const;
+const PATH_KEYS = ['astFile', 'augmentationFile', 'outFile', 'astBuilderFile', 'transferBuilderFile', 'languagesFile'] as const;
 
 /** Resolve `value` against `baseDir` when it is relative; absolute paths pass through. */
 function resolveAgainst(baseDir: string, value: string): string {
@@ -31,7 +32,7 @@ export function loadTransferModelConfig(configPath: string): Partial<GenerateTra
    try {
       raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
    } catch (error: unknown) {
-      throw new Error(`Cannot read transfer-model config '${configPath}': ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(`Cannot read transfer-model config '${configPath}': ${describeError(error)}`);
    }
    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
       throw new Error(`Transfer-model config '${configPath}' must be a JSON object.`);
@@ -44,6 +45,8 @@ export function loadTransferModelConfig(configPath: string): Partial<GenerateTra
       'augmentationFile',
       'outFile',
       'astBuilderFile',
+      'transferBuilderFile',
+      'languagesFile',
       'elementTypeName',
       'terminalsName',
       'terminalsSourceName',
@@ -75,7 +78,7 @@ export function deriveAstFileFromLangiumConfig(langiumConfigPath: string): strin
    try {
       raw = JSON.parse(fs.readFileSync(langiumConfigPath, 'utf-8'));
    } catch (error: unknown) {
-      throw new Error(`Cannot read langium-config '${langiumConfigPath}': ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(`Cannot read langium-config '${langiumConfigPath}': ${describeError(error)}`);
    }
    const out = (raw as { out?: unknown })?.out;
    if (typeof out !== 'string') {
@@ -120,6 +123,8 @@ export function mergeTransferModelOptions(...sources: Array<Partial<GenerateTran
       augmentationFile: augmentationFile!,
       outFile: outFile!,
       astBuilderFile: pick('astBuilderFile'),
+      transferBuilderFile: pick('transferBuilderFile'),
+      languagesFile: pick('languagesFile'),
       elementTypeName: pick('elementTypeName'),
       terminalsName: pick('terminalsName'),
       terminalsSourceName: pick('terminalsSourceName'),