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

package/lib/commands/generate-transfer-model.d.ts

@@ -32,6 +32,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`. */
@@ -63,10 +85,18 @@ export interface GenerateTransferModelOptions {
     regenCommand?: string;
 }
 /**
- * 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 declare function watchTransferModel(options: GenerateTransferModelOptions, context: {
     signal: AbortSignal;
@@ -94,10 +124,11 @@ export declare function parseTerminals(astSource: SourceFile, terminalsSourceNam
 }>;
 /**
  * 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 declare function typeAliasMemberGuard(member: string): string;
 /**
@@ -110,10 +141,11 @@ export declare 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 declare function resolveNamespacedStringUnion(astSource: SourceFile, definition: string): string;
 //# sourceMappingURL=generate-transfer-model.d.ts.map

package/lib/commands/generate-transfer-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-transfer-model.d.ts","sourceRoot":"","sources":["../../src/commands/generate-transfer-model.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAKlF,OAAO,EAOJ,KAAK,UAAU,EACjB,MAAM,UAAU,CAAC;AAElB;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA4B;IAC1C,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wFAAwF;IACxF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6FAA6F;IAC7F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACxB;AAwBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,4BAA4B,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAmCzH;AAED,wCAAwC;AACxC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,IAAI,CAwRjF;AAwFD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC3B,SAAS,EAAE,UAAU,EACrB,mBAAmB,EAAE,MAAM,EAC3B,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B1C;AAsFD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAY3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAqB9F"}
+{"version":3,"file":"generate-transfer-model.d.ts","sourceRoot":"","sources":["../../src/commands/generate-transfer-model.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAOlF,OAAO,EAQJ,KAAK,UAAU,EACjB,MAAM,UAAU,CAAC;AAGlB;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA4B;IAC1C,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;;OAaG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6FAA6F;IAC7F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACxB;AAqCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,4BAA4B,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDzH;AAOD,wCAAwC;AACxC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,IAAI,CAsSjF;AA2LD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC3B,SAAS,EAAE,UAAU,EACrB,mBAAmB,EAAE,MAAM,EAC3B,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B1C;AAsFD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAe3D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAqB9F"}

package/lib/commands/generate-transfer-model.js

@@ -6,10 +6,13 @@
  *
  * 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 { Project, SyntaxKind } from 'ts-morph';
+import { emitLanguages } from './generate-languages.js';
+import { emitTransferBuilder } from './generate-transfer-builder.js';
+import { Project, SyntaxKind, ts } from 'ts-morph';
+import { describeError } from '@hydranium/protocol';
 const DEFAULT_ELEMENT_TYPE_NAME = 'TransferElement';
 const DEFAULT_TERMINALS_NAME = 'ModelTerminals';
 const DEFAULT_REGEN_COMMAND = 'Run the hydranium-cli generate-transfer-model command to regenerate.';
@@ -19,35 +22,68 @@ const DEFAULT_REGEN_COMMAND = 'Run the hydranium-cli generate-transfer-model com
  * `<LanguageId>Terminals` const then spreads these.
  */
 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, context) {
+    if (context.signal.aborted) {
+        return Promise.resolve();
+    }
     const runSafely = () => {
         try {
             generateTransferModel(options);
         }
         catch (error) {
-            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;
-    const scheduleRerun = () => {
+    const rerun = () => {
+        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, previous) => {
+        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(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);
@@ -56,6 +92,10 @@ export function watchTransferModel(options, context) {
         }, { once: true });
     });
 }
+/** The langium-cli `module.ts` beside the AST file, which the languages module is read from. */
+function languagesModuleFile(options) {
+    return path.join(path.dirname(options.astFile), 'module.ts');
+}
 /** Run the transfer-model generator. */
 export function generateTransferModel(options) {
     const elementTypeName = options.elementTypeName ?? DEFAULT_ELEMENT_TYPE_NAME;
@@ -93,9 +133,13 @@ export function generateTransferModel(options) {
         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))
+            });
         }
     }
     // 5. Parse augmentations from the consumer's `declare module` blocks.
@@ -109,7 +153,6 @@ export function generateTransferModel(options) {
     // 7. Classify interfaces: abstract (union $type) vs concrete (literal $type).
     const interfaceNames = [];
     const abstractTypes = new Set();
-    const concreteTypes = new Set();
     for (const name of Object.keys(reflectionTypes)) {
         const iface = astInterfaces.get(name);
         if (!iface) {
@@ -121,9 +164,6 @@ export function generateTransferModel(options) {
         if (typeText.includes('|')) {
             abstractTypes.add(name);
         }
-        else {
-            concreteTypes.add(name);
-        }
     }
     // 8. Resolve extends-chains. Filter out type-alias supertypes (Langium reflection
     //    includes them for the grammar hierarchy but TypeScript can't extend a union
@@ -158,12 +198,13 @@ export function generateTransferModel(options) {
     out.push('   readonly $type: string;');
     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('');
     // Type aliases.
@@ -173,7 +214,7 @@ export function generateTransferModel(options) {
             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;`);
             }
         }
@@ -201,7 +242,7 @@ export function generateTransferModel(options) {
             out.push(`   readonly $type: ${typeValue};`);
         }
         else {
-            out.push(`   readonly $type: typeof ${name}Type;`);
+            out.push(`   readonly $type: '${name}';`);
         }
         const emitted = new Set(['$type']);
         for (const prop of iface.getProperties()) {
@@ -257,24 +298,24 @@ export function generateTransferModel(options) {
             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};`);
@@ -282,6 +323,8 @@ export function generateTransferModel(options) {
             out.push('');
         }
     }
+    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)) {
@@ -310,6 +353,73 @@ export function generateTransferModel(options) {
             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, types) {
+    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, elementTypeName, types, reflectionTypes) {
+    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;
 }
 // ---------------------------------------------------------------------------
 // AST source parsing helpers
@@ -348,10 +458,11 @@ function findAstReflectionClass(source) {
     throw new Error('Could not find a class extending AbstractAstReflection in the AST source.');
 }
 /**
- * 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) {
     const result = {};
@@ -372,29 +483,31 @@ function parseReflectionTypes(reflectionClass) {
         const value = entry.getLastChildByKind(SyntaxKind.ObjectLiteralExpression);
         const supersProp = value?.getProperty('superTypes');
         const supersInit = supersProp?.getFirstChildByKind(SyntaxKind.ArrayLiteralExpression);
-        const superTypes = [];
-        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) {
+    const propertiesInit = entry?.getProperty('properties')?.getFirstChildByKind(SyntaxKind.ObjectLiteralExpression);
+    const properties = [];
+    for (const property of propertiesInit?.getChildrenOfKind(SyntaxKind.PropertyAssignment) ?? []) {
+        const meta = property.getInitializerIfKind(SyntaxKind.ObjectLiteralExpression);
+        const field = (key) => 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) {
+    return /^([A-Za-z_$][\w$]*)\.\$type$/.exec(text)?.[1] ?? /^['"](.+)['"]$/.exec(text)?.[1] ?? text;
+}
 /**
  * Collect terminal regex literals from the AST file.
  *
@@ -513,12 +626,16 @@ function mapType(text, elementTypeName) {
 }
 /**
  * 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) {
+    if (member.startsWith("'") || member.startsWith('"')) {
+        return `item === ${member}`;
+    }
     switch (member) {
         case 'string':
         case 'number':
@@ -541,10 +658,11 @@ export function typeAliasMemberGuard(member) {
  * 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, definition) {
     const references = [...definition.matchAll(/\b([A-Za-z_]\w*)\.([A-Za-z_]\w*)\b/g)];
@@ -566,15 +684,54 @@ export function resolveNamespacedStringUnion(astSource, definition) {
             }
         }
     }
-    return literals.map(literal => `'${literal}'`).join(' | ');
+    return literals.length > 0 ? literals.map(quote).join(' | ') : 'never';
+}
+/**
+ * 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) {
+    if (typeNode.isKind(SyntaxKind.UnionType)) {
+        return typeNode.getTypeNodes().flatMap(member => unionMembers(member));
+    }
+    if (typeNode.isKind(SyntaxKind.ParenthesizedType)) {
+        return unionMembers(typeNode.getTypeNode());
+    }
+    return [typeNode.getText()];
 }
-/** Extract string literals from a union definition, or undefined if not pure literals. */
+/**
+ * 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) {
-    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 = [];
+    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) {
+    return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;
 }
 function topologicalSort(names, getDeps) {
     const visited = new Set();