@hydranium/cli 1.0.0-next.10

package/src/commands/ast-ground-truth-args.ts

@@ -0,0 +1,63 @@
+/********************************************************************************
+ * 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 { runAstGroundTruth, type AstGroundTruthCommandOptions } from './ast-ground-truth.js';
+import {
+   exitWithUsage,
+   helpRequested,
+   LOG_LEVEL_FLAG,
+   logLevelHelpLine,
+   logLevelOption,
+   parseHarnessArgs,
+   printHelp,
+   SERVICES_FLAG,
+   type UsageError
+} from './harness-args.js';
+import { OUT_FILE_FLAG } from './headless-harness.js';
+
+const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG] as const;
+
+/**
+ * Every flag `ast-ground-truth` accepts, derived from the sets the parser is
+ * handed so the list cannot claim a flag the parser would reject. `--services`
+ * is consumed by the shared harness parser itself, so it is in neither set.
+ */
+export const AST_GROUND_TRUTH_FLAGS: readonly string[] = [SERVICES_FLAG, ...VALUE_FLAGS];
+
+/** The subset that takes a value, so `--help` in a value position reads as data. */
+export const AST_GROUND_TRUTH_VALUE_FLAGS: readonly string[] = AST_GROUND_TRUTH_FLAGS;
+
+/** The `--help` text, as data, held to {@link AST_GROUND_TRUTH_FLAGS} by a test. */
+export const AST_GROUND_TRUTH_HELP: readonly string[] = [
+   'Usage: hydranium-cli ast-ground-truth --services <module> <workspace> [--out-file <file>] [--log-level <lvl>]',
+   '',
+   "Tally a workspace's live-model AST nodes by `$type` — the ground truth that",
+   '`analyze-heap --validate <gt.json>` checks a heap snapshot against. `<module>`',
+   'exports a zero-arg `createServices(): { shared }` thunk. Emits the',
+   '`{ documents, totalAstNodes, byType }` JSON on stdout (or `--out-file`).',
+   '',
+   'Options:',
+   '  --services <module>   ESM module exporting `createServices(): { shared }` (required).',
+   '  <workspace>           Workspace root (path or file URI) to build (required).',
+   '  --out-file <file>     Write the JSON to this file instead of stdout.',
+   logLevelHelpLine(22)
+];
+
+export function parseAstGroundTruthArgs(args: string[], onError: UsageError = exitWithUsage): AstGroundTruthCommandOptions {
+   const { servicesModule, workspace, options } = parseHarnessArgs(args, 'ast-ground-truth', VALUE_FLAGS, [], { onError });
+   return { servicesModule, workspace, outFile: options[OUT_FILE_FLAG], logLevel: logLevelOption(options[LOG_LEVEL_FLAG]) };
+}
+
+export function runAstGroundTruthCommand(args: string[]): Promise<void> {
+   if (helpRequested(args, AST_GROUND_TRUTH_VALUE_FLAGS)) {
+      printHelp(AST_GROUND_TRUTH_HELP);
+      return Promise.resolve();
+   }
+   return runAstGroundTruth(parseAstGroundTruthArgs(args));
+}

package/src/commands/ast-ground-truth-driver.ts

@@ -0,0 +1,81 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/*
+ * Spawned child of the `ast-ground-truth` subcommand. Launched by the parent with
+ * `node <this> --services <module> <workspace> [--out-file <file>]`. It
+ * dynamic-imports the head's services module, runs the framework's
+ * `collectAstGroundTruth`, and writes the `{ documents, totalAstNodes, byType }`
+ * JSON to stdout (or `--out-file`). Never imported — only spawned.
+ */
+
+import * as fs from 'node:fs';
+import { loadHeadlessContext, OUT_FILE_FLAG } from './headless-harness.js';
+
+interface DriverArgs {
+   servicesModule?: string;
+   workspace?: string;
+   outFile?: string;
+}
+
+function parseArgs(argv: string[]): DriverArgs {
+   const parsed: DriverArgs = {};
+   for (let index = 0; index < argv.length; index += 1) {
+      const flag = argv[index];
+      const next = (): string => {
+         const value = argv[index + 1];
+         if (value === undefined) {
+            console.error(`Missing value for ${flag}`);
+            process.exit(1);
+         }
+         index += 1;
+         return value;
+      };
+      switch (flag) {
+         case '--services':
+            parsed.servicesModule = next();
+            break;
+         case OUT_FILE_FLAG:
+            parsed.outFile = next();
+            break;
+         default:
+            if (flag.startsWith('--')) {
+               console.error(`Unknown option: ${flag}`);
+               process.exit(1);
+            }
+            parsed.workspace = flag;
+      }
+   }
+   return parsed;
+}
+
+async function main(argv: string[]): Promise<void> {
+   const args = parseArgs(argv);
+   if (!args.servicesModule || !args.workspace) {
+      console.error('ast-ground-truth-driver: --services <module> and a <workspace> are required.');
+      process.exit(1);
+   }
+   const { createServices, coreNode } = await loadHeadlessContext(args.servicesModule);
+   const result = await coreNode.collectAstGroundTruth({ createServices, workspace: args.workspace });
+   const json = JSON.stringify(result, undefined, 2);
+   if (args.outFile) {
+      fs.writeFileSync(args.outFile, `${json}\n`);
+      // Progress to stderr keeps stdout clean for callers that capture either form.
+      console.error(`Ground truth: ${result.documents} docs, ${result.totalAstNodes} AST nodes -> ${args.outFile}`);
+   } else {
+      console.log(json);
+   }
+}
+
+main(process.argv.slice(2))
+   .then(() => process.exit(0))
+   .catch((error: unknown) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+   });

package/src/commands/ast-ground-truth.ts

@@ -0,0 +1,49 @@
+/********************************************************************************
+ * 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 { fileURLToPath } from 'node:url';
+import { OUT_FILE_FLAG, runDriverChild, type DriverSpawnOptions } from './headless-harness.js';
+
+/**
+ * Absolute path to the spawned driver. From `lib/commands/ast-ground-truth.js`
+ * the compiled driver sits beside it at `lib/commands/ast-ground-truth-driver.js`.
+ */
+const DRIVER = fileURLToPath(new URL('./ast-ground-truth-driver.js', import.meta.url));
+
+/** Options for the {@link runAstGroundTruth} subcommand. */
+export interface AstGroundTruthCommandOptions extends DriverSpawnOptions {
+   /** ESM module exporting a zero-arg `createServices(): { shared }` thunk. */
+   readonly servicesModule: string;
+   /** Workspace root (filesystem path or file URI) to build. */
+   readonly workspace: string;
+   /** Write the JSON to this file instead of stdout. */
+   readonly outFile?: string;
+}
+
+/** Build the argv the driver child parses. Pure → unit-testable. */
+export function buildGroundTruthDriverArgs(options: AstGroundTruthCommandOptions): string[] {
+   const args = ['--services', options.servicesModule, options.workspace];
+   if (options.outFile !== undefined) {
+      args.push(OUT_FILE_FLAG, options.outFile);
+   }
+   return args;
+}
+
+/**
+ * Headless live-model `$type` census — the ground truth the offline heap
+ * analyzer validates a snapshot's classification against
+ * (`analyze-heap --validate <gt.json>`). Like `measure-memory`, the binary is
+ * language-agnostic, so the head passes a `createServices` module (`--services`);
+ * the work runs in a spawned child that dynamic-imports it, builds the workspace,
+ * and emits the `{ documents, totalAstNodes, byType }` JSON on stdout (or
+ * `--out-file`). No `--expose-gc` needed — this walks the AST, it does not weigh it.
+ */
+export function runAstGroundTruth(options: AstGroundTruthCommandOptions): Promise<void> {
+   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildGroundTruthDriverArgs(options)], options);
+}

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

@@ -0,0 +1,203 @@
+/********************************************************************************
+ * 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 * as fs from 'node:fs';
+import { deriveAstFileFromLangiumConfig, loadTransferModelConfig, mergeTransferModelOptions } from './generate-transfer-model-config.js';
+import { generateTransferModel, watchTransferModel, type GenerateTransferModelOptions } from './generate-transfer-model.js';
+import { exitWithUsage, helpRequested, printHelp, type UsageError } from './harness-args.js';
+import { wireSigintAbort } from './watch.js';
+
+/**
+ * Every flag `generate-transfer-model` accepts.
+ *
+ * Listed rather than derived: this command takes no `--services` and no
+ * positional, so it parses its own switch instead of going through the shared
+ * harness parser, and there is no flag set to derive the list from. A test
+ * therefore drives the parser with each name to prove the switch has a case for
+ * it, which the harness-backed commands get for free.
+ */
+export const GENERATE_TRANSFER_MODEL_FLAGS: readonly string[] = [
+   '--config',
+   '--langium-config',
+   '--watch',
+   '--ast-file',
+   '--augmentation-file',
+   '--out-file',
+   '--element-type-name',
+   '--terminals-name',
+   '--terminals-source-name',
+   '--skip-type-alias',
+   '--skip-terminal',
+   '--regen-command'
+];
+
+/**
+ * The subset that takes a value, so `--help` in a value position reads as data.
+ * `--watch` is the only presence-only flag; `--regen-command` is the one where a
+ * caller plausibly writes that literal text into a generated header.
+ */
+export const GENERATE_TRANSFER_MODEL_VALUE_FLAGS: readonly string[] = GENERATE_TRANSFER_MODEL_FLAGS.filter(flag => flag !== '--watch');
+
+/** The `--help` text, as data, held to {@link GENERATE_TRANSFER_MODEL_FLAGS} by a test. */
+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. 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.',
+   "                                Relative paths resolve against the config's dir.",
+   "  --langium-config <path>       Derive --ast-file from this config's `out` dir",
+   '                                (<out>/ast.ts). Defaults to ./langium-config.json.',
+   '  --watch                       Regenerate on AST / augmentation file changes.',
+   '  --ast-file <path>             Langium-generated AST source file (required).',
+   '  --augmentation-file <path>    Module-augmentation file (required).',
+   '  --out-file <path>             Destination for the generated transfer model (required).',
+   "                                Do NOT point this inside langium-cli's own `out`",
+   '                                directory: it treats that directory as exclusively',
+   '                                its own, so every `langium generate` reports this',
+   '                                file as unexpected and offers to delete it.',
+   '  --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.',
+   '  --skip-type-alias <name>      Type alias to exclude (repeatable).',
+   '  --skip-terminal <name>        Terminal to exclude (repeatable).',
+   '  --regen-command <text>        Header line shown in the generated file (regen instructions).'
+];
+
+/** The flags as read, before any config file or langium-config derivation is folded in. */
+export interface ParsedGenerateOptions {
+   flags: Partial<GenerateTransferModelOptions>;
+   configFile?: string;
+   langiumConfigFile?: string;
+   watch: boolean;
+}
+
+export function parseGenerateOptions(args: string[], onError: UsageError = exitWithUsage): ParsedGenerateOptions {
+   const skipTypeAliases: string[] = [];
+   const skipTerminals: string[] = [];
+   const flags: Partial<GenerateTransferModelOptions> = {};
+   let configFile: string | undefined;
+   let langiumConfigFile: string | undefined;
+   let watch = false;
+
+   for (let index = 0; index < args.length; index += 1) {
+      const flag = args[index];
+      const next = (): string => {
+         const value = args[index + 1];
+         if (value === undefined) {
+            onError(`Missing value for ${flag}`);
+         }
+         index += 1;
+         return value;
+      };
+      switch (flag) {
+         case '--config':
+            configFile = next();
+            break;
+         case '--langium-config':
+            langiumConfigFile = next();
+            break;
+         case '--watch':
+            watch = true;
+            break;
+         case '--ast-file':
+            flags.astFile = next();
+            break;
+         case '--augmentation-file':
+            flags.augmentationFile = next();
+            break;
+         case '--out-file':
+            flags.outFile = next();
+            break;
+         case '--element-type-name':
+            flags.elementTypeName = next();
+            break;
+         case '--terminals-name':
+            flags.terminalsName = next();
+            break;
+         case '--terminals-source-name':
+            flags.terminalsSourceName = next();
+            break;
+         case '--skip-type-alias':
+            skipTypeAliases.push(next());
+            break;
+         case '--skip-terminal':
+            skipTerminals.push(next());
+            break;
+         case '--regen-command':
+            flags.regenCommand = next();
+            break;
+         default:
+            onError(`Unknown option: ${flag}`);
+      }
+   }
+
+   // Only record the repeatable arrays when the flag actually appeared, so an empty
+   // `--skip-*` doesn't shadow a config-file value in the merge (first-defined-wins).
+   if (skipTypeAliases.length) {
+      flags.skipTypeAliases = skipTypeAliases;
+   }
+   if (skipTerminals.length) {
+      flags.skipTerminals = skipTerminals;
+   }
+
+   return { flags, configFile, langiumConfigFile, watch };
+}
+
+/**
+ * Only auto-detect the default `./langium-config.json` when it exists — an explicit
+ * `--langium-config` always wins and is returned as-is (the caller reports errors if
+ * it is unreadable).
+ */
+function resolveLangiumConfigPath(explicit: string | undefined): string | undefined {
+   if (explicit !== undefined) {
+      return explicit;
+   }
+   return fs.existsSync('langium-config.json') ? 'langium-config.json' : undefined;
+}
+
+export function runGenerateTransferModelCommand(args: string[]): void | Promise<void> {
+   if (helpRequested(args, GENERATE_TRANSFER_MODEL_VALUE_FLAGS)) {
+      printHelp(GENERATE_TRANSFER_MODEL_HELP);
+      return;
+   }
+
+   const parsed = parseGenerateOptions(args);
+
+   // Assemble option sources highest-precedence first: explicit flags, then the
+   // --config file, then a langium-config-derived --ast-file. Merge validates the
+   // three required paths are present after all sources are considered.
+   const sources: Array<Partial<GenerateTransferModelOptions>> = [parsed.flags];
+   if (parsed.configFile !== undefined) {
+      sources.push(loadTransferModelConfig(parsed.configFile));
+   }
+   const langiumConfig = resolveLangiumConfigPath(parsed.langiumConfigFile);
+   if (langiumConfig !== undefined) {
+      const derivedAstFile = deriveAstFileFromLangiumConfig(langiumConfig);
+      if (derivedAstFile !== undefined) {
+         if (parsed.langiumConfigFile !== undefined) {
+            console.log(`Deriving --ast-file from ${langiumConfig}: ${derivedAstFile}`);
+         }
+         sources.push({ astFile: derivedAstFile });
+      }
+   }
+
+   const options = mergeTransferModelOptions(...sources);
+   if (parsed.watch) {
+      const controller = new AbortController();
+      const unwire = wireSigintAbort(controller);
+      return watchTransferModel(options, { signal: controller.signal }).finally(() => unwire());
+   }
+   generateTransferModel(options);
+}

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

@@ -0,0 +1,128 @@
+/********************************************************************************
+ * 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 * as fs from 'node:fs';
+import * as path from 'node:path';
+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'] as const;
+
+/** Resolve `value` against `baseDir` when it is relative; absolute paths pass through. */
+function resolveAgainst(baseDir: string, value: string): string {
+   return path.isAbsolute(value) ? value : path.resolve(baseDir, value);
+}
+
+/**
+ * Read a transfer-model JSON config file into a partial options object. Only the
+ * known {@link GenerateTransferModelOptions} keys are picked (unknown keys are
+ * ignored); the {@link PATH_KEYS} are resolved relative to the config file's own
+ * directory so a config can use paths relative to itself. Throws a clear error on
+ * unreadable / non-object / invalid JSON.
+ */
+export function loadTransferModelConfig(configPath: string): Partial<GenerateTransferModelOptions> {
+   let raw: unknown;
+   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)}`);
+   }
+   if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+      throw new Error(`Transfer-model config '${configPath}' must be a JSON object.`);
+   }
+   const source = raw as Record<string, unknown>;
+   const baseDir = path.dirname(path.resolve(configPath));
+   const result: Partial<GenerateTransferModelOptions> = {};
+   const stringKeys = [
+      'astFile',
+      'augmentationFile',
+      'outFile',
+      'elementTypeName',
+      'terminalsName',
+      'terminalsSourceName',
+      'regenCommand'
+   ] as const;
+   for (const key of stringKeys) {
+      const value = source[key];
+      if (typeof value === 'string') {
+         result[key] = (PATH_KEYS as readonly string[]).includes(key) ? resolveAgainst(baseDir, value) : value;
+      }
+   }
+   for (const key of ['skipTypeAliases', 'skipTerminals'] as const) {
+      const value = source[key];
+      if (Array.isArray(value) && value.every(entry => typeof entry === 'string')) {
+         result[key] = value as string[];
+      }
+   }
+   return result;
+}
+
+/**
+ * Derive the Langium-generated AST file path from a `langium-config.json`: the
+ * generator emits `ast.ts` into the config's `out` directory, so the AST file is
+ * `<config-dir>/<out>/ast.ts`. Returns `undefined` when the config declares no
+ * `out` (nothing to derive). Throws on unreadable / invalid JSON.
+ */
+export function deriveAstFileFromLangiumConfig(langiumConfigPath: string): string | undefined {
+   let raw: unknown;
+   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)}`);
+   }
+   const out = (raw as { out?: unknown })?.out;
+   if (typeof out !== 'string') {
+      return undefined;
+   }
+   const baseDir = path.dirname(path.resolve(langiumConfigPath));
+   return path.resolve(baseDir, out, 'ast.ts');
+}
+
+/**
+ * Merge partial option sources into a complete {@link GenerateTransferModelOptions},
+ * highest precedence first: for each field the first source that defines it wins.
+ * Pure over its inputs. Throws listing every required path (`astFile` /
+ * `augmentationFile` / `outFile`) still missing after the merge.
+ */
+export function mergeTransferModelOptions(...sources: Array<Partial<GenerateTransferModelOptions>>): GenerateTransferModelOptions {
+   const pick = <K extends keyof GenerateTransferModelOptions>(key: K): GenerateTransferModelOptions[K] | undefined => {
+      for (const source of sources) {
+         if (source[key] !== undefined) {
+            return source[key];
+         }
+      }
+      return undefined;
+   };
+
+   const astFile = pick('astFile');
+   const augmentationFile = pick('augmentationFile');
+   const outFile = pick('outFile');
+   const missing = [
+      ['astFile (--ast-file)', astFile],
+      ['augmentationFile (--augmentation-file)', augmentationFile],
+      ['outFile (--out-file)', outFile]
+   ]
+      .filter(([, value]) => value === undefined)
+      .map(([label]) => label);
+   if (missing.length) {
+      throw new Error(`Missing required transfer-model option(s): ${missing.join(', ')}`);
+   }
+
+   return {
+      astFile: astFile!,
+      augmentationFile: augmentationFile!,
+      outFile: outFile!,
+      elementTypeName: pick('elementTypeName'),
+      terminalsName: pick('terminalsName'),
+      terminalsSourceName: pick('terminalsSourceName'),
+      skipTypeAliases: pick('skipTypeAliases'),
+      skipTerminals: pick('skipTerminals'),
+      regenCommand: pick('regenCommand')
+   };
+}