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

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

@@ -7,18 +7,22 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import * as fs from 'fs';
+import * as fs from 'node:fs';
 import * as path from 'path';
 import { emitAstBuilder } from './generate-ast-builder.js';
+import { emitLanguages } from './generate-languages.js';
+import { emitTransferBuilder } from './generate-transfer-builder.js';
 import {
    type Node,
    type ObjectLiteralExpression,
    Project,
    SyntaxKind,
+   ts,
    type ClassDeclaration,
    type InterfaceDeclaration,
    type SourceFile
 } from 'ts-morph';
+import { describeError } from '@hydranium/protocol';
 
 /**
  * Options for the transfer-model generator.
@@ -45,6 +49,28 @@ export interface GenerateTransferModelOptions {
     * and not the other has the two disagreeing about the same grammar.
     */
    astBuilderFile?: string;
+   /**
+    * Destination for a generated test module binding `makeTransferNodeBuilder`
+    * from `@hydranium/protocol/testing` to the transfer model, as `transferNode`,
+    * the way {@link astBuilderFile} binds `astNode`. Belongs in a test tree:
+    * production code has no use for a builder that fills grammar defaults.
+    *
+    * When it sits in another package than {@link outFile}, it imports the model
+    * by that package's name, so the package's main entry must re-export the
+    * generated model, and with it each type's constant: an interface the entry
+    * narrows hides the generated constant of the same name unless the entry
+    * re-exports that constant too, and the builder keeps the generated
+    * interface unless the entry declares `<LanguageId>TransferTypes` with the
+    * narrowed entry.
+    */
+   transferBuilderFile?: string;
+   /**
+    * Destination for a generated module stating each grammar's language id and
+    * file extensions, read from the `module.ts` beside {@link astFile}. Lets a
+    * package without Langium, such as one shared with clients, name the ids
+    * without copying them by hand.
+    */
+   languagesFile?: string;
    /** Name used for the base element type in the output. Defaults to `TransferElement`. */
    elementTypeName?: string;
    /** Name used for the terminal-patterns const in the output. Defaults to `ModelTerminals`. */
@@ -86,6 +112,15 @@ interface AugmentedProperty {
 
 interface ReflectionEntry {
    superTypes: string[];
+   properties: ReflectionProperty[];
+}
+
+/** One grammar property of a reflection entry; `defaultValue` keeps the source text of the literal. */
+interface ReflectionProperty {
+   name: string;
+   defaultValue?: string;
+   optional: boolean;
+   referenceType?: string;
 }
 
 const DEFAULT_ELEMENT_TYPE_NAME = 'TransferElement';
@@ -98,38 +133,72 @@ const DEFAULT_REGEN_COMMAND = 'Run the hydranium-cli generate-transfer-model com
  */
 const NAMESPACED_TERMINALS_NAME = 'Terminals';
 
+/** How often `--watch` polls its input files. */
+const WATCH_POLL_INTERVAL_MS = 250;
+const WATCH_DEBOUNCE_MS = 150;
+
 /**
- * Generate once, then re-generate whenever the AST or augmentation file changes,
+ * Generate once, then re-generate whenever an input file changes (the AST, the
+ * augmentation file, and `module.ts` when a languages file is written),
  * until `signal` aborts (the CLI wires this to SIGINT). Regeneration is debounced
  * so an editor's multi-event save fires a single run, and a generation error is
  * logged without tearing down the watch. Resolves when the signal aborts.
+ * An already-aborted signal resolves immediately without generating or watching.
+ *
+ * Polled by path rather than watched through OS events: langium-cli removes
+ * its output directory and writes the files back, which an event watch, Node's
+ * and chokidar's alike, stops hearing after the first run. A run that finds an
+ * input missing is skipped, since the file's return is a change of its own, so
+ * nothing generates from a half-written output.
  */
 export function watchTransferModel(options: GenerateTransferModelOptions, context: { signal: AbortSignal }): Promise<void> {
+   if (context.signal.aborted) {
+      return Promise.resolve();
+   }
    const runSafely = (): void => {
       try {
          generateTransferModel(options);
       } catch (error: unknown) {
-         console.error(`Transfer-model generation failed: ${error instanceof Error ? error.message : String(error)}`);
+         console.error(`Transfer-model generation failed: ${describeError(error)}`);
       }
    };
    runSafely();
-   console.log(`Watching ${options.astFile} and ${options.augmentationFile} for changes. Press Ctrl-C to stop.`);
+   // A grammar's language id and extensions reach only `module.ts`, so the
+   // languages module would go stale without it.
+   const watched = [
+      options.astFile,
+      options.augmentationFile,
+      ...(options.languagesFile !== undefined ? [languagesModuleFile(options)] : [])
+   ];
 
    let timer: NodeJS.Timeout | undefined;
-   const scheduleRerun = (): void => {
+   const rerun = (): void => {
+      if (watched.every(file => fs.existsSync(file))) {
+         runSafely();
+      }
+   };
+   // The poll reports every stat it takes; a replaced file has a new inode, a
+   // rewritten one a new mtime, a removed or returning one zeroed stats.
+   const onPoll = (current: fs.Stats, previous: fs.Stats): void => {
+      if (current.ino === previous.ino && current.mtimeMs === previous.mtimeMs && current.size === previous.size) {
+         return;
+      }
       if (timer) {
          clearTimeout(timer);
       }
-      timer = setTimeout(runSafely, 150);
+      timer = setTimeout(rerun, WATCH_DEBOUNCE_MS);
    };
-   const watchers = [options.astFile, options.augmentationFile].map(file => fs.watch(file, scheduleRerun));
+   for (const file of watched) {
+      fs.watchFile(file, { interval: WATCH_POLL_INTERVAL_MS }, onPoll);
+   }
+   console.log(`Watching ${watched.join(', ')} for changes. Press Ctrl-C to stop.`);
 
    return new Promise<void>(resolve => {
       context.signal.addEventListener(
          'abort',
          () => {
-            for (const watcher of watchers) {
-               watcher.close();
+            for (const file of watched) {
+               fs.unwatchFile(file, onPoll);
             }
             if (timer) {
                clearTimeout(timer);
@@ -141,6 +210,11 @@ export function watchTransferModel(options: GenerateTransferModelOptions, contex
    });
 }
 
+/** The langium-cli `module.ts` beside the AST file, which the languages module is read from. */
+function languagesModuleFile(options: GenerateTransferModelOptions): string {
+   return path.join(path.dirname(options.astFile), 'module.ts');
+}
+
 /** Run the transfer-model generator. */
 export function generateTransferModel(options: GenerateTransferModelOptions): void {
    const elementTypeName = options.elementTypeName ?? DEFAULT_ELEMENT_TYPE_NAME;
@@ -178,15 +252,19 @@ export function generateTransferModel(options: GenerateTransferModelOptions): vo
       astInterfaces.set(iface.getName(), iface);
    }
 
-   const typeAliases: Array<{ name: string; definition: string }> = [];
+   const typeAliases: Array<{ name: string; definition: string; members: string[] }> = [];
    for (const alias of astSource.getTypeAliases()) {
       const name = alias.getName();
       if (skipTypeAliases.has(name)) {
          continue;
       }
-      const typeText = alias.getTypeNode()?.getText();
-      if (typeText) {
-         typeAliases.push({ name, definition: mapType(resolveNamespacedStringUnion(astSource, typeText), elementTypeName) });
+      const typeNode = alias.getTypeNode();
+      if (typeNode) {
+         typeAliases.push({
+            name,
+            definition: mapType(resolveNamespacedStringUnion(astSource, typeNode.getText()), elementTypeName),
+            members: unionMembers(typeNode).map(member => mapType(member, elementTypeName))
+         });
       }
    }
 
@@ -203,7 +281,6 @@ export function generateTransferModel(options: GenerateTransferModelOptions): vo
    // 7. Classify interfaces: abstract (union $type) vs concrete (literal $type).
    const interfaceNames: string[] = [];
    const abstractTypes = new Set<string>();
-   const concreteTypes = new Set<string>();
 
    for (const name of Object.keys(reflectionTypes)) {
       const iface = astInterfaces.get(name);
@@ -215,8 +292,6 @@ export function generateTransferModel(options: GenerateTransferModelOptions): vo
       const typeText = iface.getProperty('$type')?.getTypeNode()?.getText() ?? '';
       if (typeText.includes('|')) {
          abstractTypes.add(name);
-      } else {
-         concreteTypes.add(name);
       }
    }
 
@@ -258,12 +333,13 @@ export function generateTransferModel(options: GenerateTransferModelOptions): vo
    out.push('}');
    out.push('');
 
-   // Type constants for concrete types.
+   // Langium's per-type constant under the same name, for every reflection type
+   // the model emits, abstract ones and unions included.
+   const reflectedTypes = Object.keys(reflectionTypes).filter(name => astInterfaces.has(name) || typeAliasNames.has(name));
    out.push('// --- Type Constants ---');
-   for (const name of sorted) {
-      if (concreteTypes.has(name)) {
-         out.push(`export const ${name}Type = '${name}';`);
-      }
+   for (const name of reflectedTypes) {
+      const keys = reflectionTypes[name].properties.map(property => `${property.name}: '${property.name}'`);
+      out.push(`export const ${name} = { ${[`$type: '${name}'`, ...keys].join(', ')} } as const;`);
    }
    out.push('');
 
@@ -274,7 +350,7 @@ export function generateTransferModel(options: GenerateTransferModelOptions): vo
          out.push(`export type ${name} = ${definition};`);
          const literals = extractStringLiterals(definition);
          if (literals) {
-            const items = literals.map(l => `'${l}'`).join(', ');
+            const items = literals.map(quote).join(', ');
             out.push(`export const ${name}Values = [${items}] as const;`);
          }
       }
@@ -305,7 +381,7 @@ export function generateTransferModel(options: GenerateTransferModelOptions): vo
          const typeValue = iface.getProperty('$type')?.getTypeNode()?.getText() ?? `'${name}'`;
          out.push(`   readonly $type: ${typeValue};`);
       } else {
-         out.push(`   readonly $type: typeof ${name}Type;`);
+         out.push(`   readonly $type: '${name}';`);
       }
 
       const emitted = new Set<string>(['$type']);
@@ -367,24 +443,24 @@ export function generateTransferModel(options: GenerateTransferModelOptions): vo
          const checks = members.map(m => `item.$type === '${m}'`).join(' || ');
          out.push(`   return is${elementTypeName}(item) && (${checks});`);
       } else {
-         out.push(`   return is${elementTypeName}(item) && item.$type === ${name}Type;`);
+         out.push(`   return is${elementTypeName}(item) && item.$type === '${name}';`);
       }
       out.push('}');
       out.push('');
    }
 
-   for (const { name, definition } of typeAliases) {
+   for (const { name, definition, members } of typeAliases) {
       const literals = extractStringLiterals(definition);
       if (literals) {
-         const checks = literals.map(l => `item === '${l}'`).join(' || ');
+         const checks = literals.map(l => `item === ${quote(l)}`).join(' || ') || 'false';
          out.push(`export function is${name}(item: unknown): item is ${name} {`);
          out.push(`   return ${checks};`);
          out.push('}');
          out.push('');
       } else {
-         // Union (or single) of named members and/or Langium data-type primitives. Each member maps
-         // to its own check (typeof / instanceof / named-guard) via typeAliasMemberGuard.
-         const members = definition.split('|').map(s => s.trim());
+         // Union (or single) of named members, Langium data-type primitives and the string
+         // literals a data-type rule's keywords add beside them. Each member maps to its own
+         // check via typeAliasMemberGuard.
          const checks = members.map(typeAliasMemberGuard).join(' || ');
          out.push(`export function is${name}(item: unknown): item is ${name} {`);
          out.push(`   return ${checks};`);
@@ -393,6 +469,9 @@ export function generateTransferModel(options: GenerateTransferModelOptions): vo
       }
    }
 
+   out.push(...renderTypeMap(languageId, reflectedTypes));
+   out.push(...renderReflection(languageId, elementTypeName, reflectedTypes, reflectionTypes));
+
    // Coverage check: warn on reflection types not emitted.
    const processedSet = new Set(sorted);
    for (const name of Object.keys(reflectionTypes)) {
@@ -422,6 +501,107 @@ export function generateTransferModel(options: GenerateTransferModelOptions): vo
          console.warn(`Warning: no '${languageId}AstType' alias in ${options.astFile}; skipping the AST builder.`);
       }
    }
+
+   if (options.transferBuilderFile !== undefined) {
+      emitTransferBuilder({ outFile: options.transferBuilderFile, transferModelFile: options.outFile, languageId, regenCommand });
+   }
+
+   if (options.languagesFile !== undefined) {
+      const moduleSource = project.addSourceFileAtPath(languagesModuleFile(options));
+      emitLanguages(moduleSource, { outFile: options.languagesFile, regenCommand });
+   }
+}
+
+/**
+ * `<LanguageId>TransferTypes`, each `$type` to its interface, so an encoder or a
+ * builder can type a node by the grammar the way Langium's `<LanguageId>AstType`
+ * does on the AST side.
+ */
+function renderTypeMap(languageId: string, types: readonly string[]): string[] {
+   return ['// --- Type Map ---', `export type ${languageId}TransferTypes = {`, ...types.map(name => `   ${name}: ${name};`), '};', ''];
+}
+
+/**
+ * `<LanguageId>TransferReflection`, the grammar metadata with the method names
+ * Langium's `AstReflection` uses. A plain object with no framework import, so
+ * the file stays self-contained, and nothing references it but its importers:
+ * the `is` guards test `$type` directly, so a guard never pulls it in. `types`
+ * keeps its literal type, which is how the transfer-node builder tells which
+ * fields the grammar defaults.
+ */
+function renderReflection(
+   languageId: string,
+   elementTypeName: string,
+   types: readonly string[],
+   reflectionTypes: Record<string, ReflectionEntry>
+): string[] {
+   const metaData = `${languageId}TransferTypeMetaData`;
+   // Index signatures, not `Readonly<Record<…>>`: a grammar type may be named
+   // `Record` or `Readonly`, which Langium does not reserve as it does `Object`.
+   const out = [
+      '// --- Reflection ---',
+      `export interface ${metaData} {`,
+      '   readonly name: string;',
+      '   readonly properties: {',
+      '      readonly [name: string]: { readonly name: string; readonly defaultValue?: unknown; readonly optional?: boolean; readonly referenceType?: string };',
+      '   };',
+      '   readonly superTypes: readonly string[];',
+      '}',
+      '',
+      `export const ${languageId}TransferReflection = {`,
+      '   types: {'
+   ];
+   for (const name of types) {
+      const { properties, superTypes } = reflectionTypes[name];
+      const propertyEntries = properties.map(property => {
+         const fields = [`name: '${property.name}'`];
+         if (property.defaultValue !== undefined) {
+            fields.push(`defaultValue: ${property.defaultValue}`);
+         }
+         if (property.optional) {
+            fields.push('optional: true');
+         }
+         if (property.referenceType !== undefined) {
+            fields.push(`referenceType: '${property.referenceType}'`);
+         }
+         return `${property.name}: { ${fields.join(', ')} }`;
+      });
+      const supers = superTypes.map(superType => `'${superType}'`).join(', ');
+      const propertiesText = propertyEntries.length > 0 ? `{ ${propertyEntries.join(', ')} }` : '{}';
+      out.push(`      ${name}: { name: '${name}', properties: ${propertiesText}, superTypes: [${supers}] },`);
+   }
+   out.push(
+      `   } as const satisfies { readonly [type: string]: ${metaData} },`,
+      '',
+      '   getAllTypes(): string[] {',
+      '      return Object.keys(this.types);',
+      '   },',
+      '',
+      // An own-property check, not `types[type] ?? …`: a name the object
+      // prototype carries, `toString` say, would read the inherited member and
+      // make `isSubtype` throw. `hasOwnProperty.call` rather than `Object.hasOwn`
+      // because the adopter's protocol package may target a lib without it.
+      `   getTypeMetaData(type: string): ${metaData} {`,
+      '      return Object.prototype.hasOwnProperty.call(this.types, type)',
+      `         ? (this.types as { readonly [type: string]: ${metaData} })[type]`,
+      '         : { name: type, properties: {}, superTypes: [] };',
+      '   },',
+      '',
+      '   isSubtype(subtype: string, supertype: string): boolean {',
+      '      return subtype === supertype || this.getTypeMetaData(subtype).superTypes.some(type => this.isSubtype(type, supertype));',
+      '   },',
+      '',
+      '   getAllSubTypes(type: string): string[] {',
+      '      return this.getAllTypes().filter(candidate => this.isSubtype(candidate, type));',
+      '   },',
+      '',
+      '   isInstance(item: unknown, type: string): boolean {',
+      `      return is${elementTypeName}(item) && this.isSubtype(item.$type, type);`,
+      '   }',
+      '};',
+      ''
+   );
+   return out;
 }
 
 // ---------------------------------------------------------------------------
@@ -462,10 +642,11 @@ function findAstReflectionClass(source: SourceFile): ClassDeclaration {
 }
 
 /**
- * Extract `superTypes` for each entry of the reflection class's `types` property
- * initializer. We rely on the Langium convention that `X.$type === 'X'`, so a
- * supertype expression resolves to the literal type-name string by stripping
- * `.$type`.
+ * Extract `superTypes` and the grammar properties for each entry of the
+ * reflection class's `types` property initializer. We rely on the Langium
+ * convention that `X.$type === 'X'` and `X.p === 'p'`, so a type expression
+ * resolves to the literal type-name string by stripping `.$type`, and a
+ * property's name is its key.
  */
 function parseReflectionTypes(reflectionClass: ClassDeclaration): Record<string, ReflectionEntry> {
    const result: Record<string, ReflectionEntry> = {};
@@ -487,29 +668,35 @@ function parseReflectionTypes(reflectionClass: ClassDeclaration): Record<string,
       const value = entry.getLastChildByKind(SyntaxKind.ObjectLiteralExpression);
       const supersProp = value?.getProperty('superTypes');
       const supersInit = supersProp?.getFirstChildByKind(SyntaxKind.ArrayLiteralExpression);
-      const superTypes: string[] = [];
-      if (supersInit) {
-         for (const element of supersInit.getElements()) {
-            const text = element.getText();
-            const dotMatch = /^([A-Za-z_$][\w$]*)\.\$type$/.exec(text);
-            if (dotMatch) {
-               superTypes.push(dotMatch[1]);
-               continue;
-            }
-            // Bare identifier or quoted string fall-back.
-            const stringMatch = /^['"](.+)['"]$/.exec(text);
-            if (stringMatch) {
-               superTypes.push(stringMatch[1]);
-            } else {
-               superTypes.push(text);
-            }
-         }
-      }
-      result[name] = { superTypes };
+      const superTypes = supersInit?.getElements().map(element => typeNameOf(element.getText())) ?? [];
+      result[name] = { superTypes, properties: parseReflectionProperties(value) };
    }
    return result;
 }
 
+function parseReflectionProperties(entry: ObjectLiteralExpression | undefined): ReflectionProperty[] {
+   const propertiesInit = entry?.getProperty('properties')?.getFirstChildByKind(SyntaxKind.ObjectLiteralExpression);
+   const properties: ReflectionProperty[] = [];
+   for (const property of propertiesInit?.getChildrenOfKind(SyntaxKind.PropertyAssignment) ?? []) {
+      const meta = property.getInitializerIfKind(SyntaxKind.ObjectLiteralExpression);
+      const field = (key: string): string | undefined =>
+         meta?.getProperty(key)?.asKind(SyntaxKind.PropertyAssignment)?.getInitializer()?.getText();
+      const referenceType = field('referenceType');
+      properties.push({
+         name: property.getName(),
+         defaultValue: field('defaultValue'),
+         optional: field('optional') === 'true',
+         referenceType: referenceType === undefined ? undefined : typeNameOf(referenceType)
+      });
+   }
+   return properties;
+}
+
+/** `X.$type` or a quoted `'X'` to `X`; any other text passes through. */
+function typeNameOf(text: string): string {
+   return /^([A-Za-z_$][\w$]*)\.\$type$/.exec(text)?.[1] ?? /^['"](.+)['"]$/.exec(text)?.[1] ?? text;
+}
+
 /**
  * Collect terminal regex literals from the AST file.
  *
@@ -647,12 +834,16 @@ function mapType(text: string, elementTypeName: string): string {
 
 /**
  * Type-guard expression (against an `item: unknown`) for one member of a non-literal type-alias
- * union. Covers the full set of Langium data-type primitives: the `typeof`-checkable ones
- * (`string`/`number`/`boolean`/`bigint`) use `typeof`; `Date` — the one Langium primitive `typeof`
- * reports as `'object'` — uses `instanceof`; any other member is a named type whose generated
- * `is<Member>` guard is called.
+ * union. A string literal is compared as written, so the escapes Langium wrote stay valid.
+ * Covers the full set of Langium data-type primitives. The `typeof`-checkable ones
+ * (`string`/`number`/`boolean`/`bigint`) use `typeof`, and `Date`, the one Langium primitive
+ * `typeof` reports as `'object'`, uses `instanceof`. Any other member is a named type whose
+ * generated `is<Member>` guard is called.
  */
 export function typeAliasMemberGuard(member: string): string {
+   if (member.startsWith("'") || member.startsWith('"')) {
+      return `item === ${member}`;
+   }
    switch (member) {
       case 'string':
       case 'number':
@@ -676,10 +867,11 @@ export function typeAliasMemberGuard(member: string): string {
  * name.
  *
  * Each referenced member is inlined and de-duplicated, preserving first-seen
- * order. The definition is returned UNCHANGED when it holds no
- * namespace-qualified reference (the single-language case) or when any referenced
- * member is not a pure string-literal union — passing it through rather than
- * emitting a half-resolved union.
+ * order; when no member holds a literal, the union is `never`. The definition
+ * is returned UNCHANGED when it holds no namespace-qualified reference (the
+ * single-language case) or when any referenced member is not a pure
+ * string-literal union — passing it through rather than emitting a
+ * half-resolved union.
  */
 export function resolveNamespacedStringUnion(astSource: SourceFile, definition: string): string {
    const references = [...definition.matchAll(/\b([A-Za-z_]\w*)\.([A-Za-z_]\w*)\b/g)];
@@ -701,16 +893,55 @@ export function resolveNamespacedStringUnion(astSource: SourceFile, definition:
          }
       }
    }
-   return literals.map(literal => `'${literal}'`).join(' | ');
+   return literals.length > 0 ? literals.map(quote).join(' | ') : 'never';
 }
 
-/** Extract string literals from a union definition, or undefined if not pure literals. */
+/**
+ * The members of a type-alias union as TypeScript parses them. If a data-type rule groups
+ * alternatives in parentheses, the alias Langium generates contains the same group, as in
+ * `'a' | ('b' | Keyword)`, so each group is flattened into its members. Splitting the text on
+ * `|` breaks such a group and any keyword that contains `|`, such as `'||'`, and the
+ * resulting guard does not compile.
+ */
+function unionMembers(typeNode: Node): string[] {
+   if (typeNode.isKind(SyntaxKind.UnionType)) {
+      return typeNode.getTypeNodes().flatMap(member => unionMembers(member));
+   }
+   if (typeNode.isKind(SyntaxKind.ParenthesizedType)) {
+      return unionMembers(typeNode.getTypeNode());
+   }
+   return [typeNode.getText()];
+}
+
+/**
+ * The values of a union of string literals, or undefined when the definition holds anything
+ * else. The TypeScript scanner decodes each literal, so a keyword with a quote in it reads the
+ * same whichever quotes and escapes Langium wrote it with. Langium writes the keyword names of
+ * a language without keywords as `never`, which adds no value.
+ */
 function extractStringLiterals(definition: string): string[] | undefined {
-   const stringLiteral = '(?:\'[^\']*\'|"[^"]*")';
-   if (!new RegExp(`^\\|?\\s*${stringLiteral}(\\s*\\|\\s*${stringLiteral})*$`).test(definition.trim())) {
-      return undefined;
+   const scanner = ts.createScanner(ts.ScriptTarget.Latest, true, ts.LanguageVariant.Standard, definition);
+   const literals: string[] = [];
+   let members = 0;
+   for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) {
+      if (token === ts.SyntaxKind.StringLiteral) {
+         literals.push(scanner.getTokenValue());
+         members++;
+      } else if (token === ts.SyntaxKind.NeverKeyword) {
+         members++;
+      } else if (token !== ts.SyntaxKind.BarToken) {
+         return undefined;
+      }
    }
-   return [...definition.matchAll(/'([^']*)'|"([^"]*)"/g)].map(m => m[1] ?? m[2]);
+   return members > 0 ? literals : undefined;
+}
+
+/**
+ * `value` as a string literal in the single quotes the generated file uses. A keyword can
+ * contain a quote or a backslash, and either one ends or escapes the literal unless escaped.
+ */
+function quote(value: string): string {
+   return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;
 }
 
 function topologicalSort(names: string[], getDeps: (n: string) => string[]): string[] {

package/src/commands/generated-module-path.ts

@@ -0,0 +1,22 @@
+/********************************************************************************
+ * 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 path from 'path';
+
+/**
+ * Module specifier for `targetFile` as seen from the generated module
+ * `outFile`'s own directory. Emitted with a `.js` extension and posix
+ * separators because the output is ESM TypeScript, where the specifier names
+ * the compiled sibling.
+ */
+export function relativeImportPath(outFile: string, targetFile: string): string {
+   const relative = path.relative(path.dirname(path.resolve(outFile)), path.resolve(targetFile));
+   const posix = relative.split(path.sep).join('/').replace(/\.ts$/, '.js');
+   return posix.startsWith('.') ? posix : `./${posix}`;
+}