@hydranium/cli 1.0.0-next.10

package/lib/cli-version.js

@@ -0,0 +1,30 @@
+/********************************************************************************
+ * 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 { readFileSync } from 'node:fs';
+/** This package's own manifest, reachable at the same relative path from `src/` and `lib/`. */
+const CLI_MANIFEST = new URL('../package.json', import.meta.url);
+/**
+ * The version of the running binary.
+ *
+ * Read from the manifest rather than emitted as a constant at build time: a
+ * generated constant is a second copy of a number the manifest already carries,
+ * and nothing goes red while the two disagree.
+ *
+ * Throws rather than reporting `unknown`: every caller turns the number into a
+ * claim someone else acts on — a pinned dependency range, a version in a bug
+ * report — where a placeholder is worse than a failure.
+ */
+export function readCliVersion() {
+    const manifest = JSON.parse(readFileSync(CLI_MANIFEST, 'utf-8'));
+    if (typeof manifest.version !== 'string' || manifest.version === '') {
+        throw new Error('hydranium-cli cannot read its own version from its package manifest.');
+    }
+    return manifest.version;
+}
+//# sourceMappingURL=cli-version.js.map

package/lib/cli-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-version.js","sourceRoot":"","sources":["../src/cli-version.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,+FAA+F;AAC/F,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEjE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc;IAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAA0B,CAAC;IAC1F,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,IAAI,QAAQ,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,QAAQ,CAAC,OAAO,CAAC;AAC3B,CAAC"}

package/lib/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/lib/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;kFAOkF"}

package/lib/cli.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/********************************************************************************
+ * 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 { Command } from 'commander';
+import { readCliVersion } from './cli-version.js';
+import { runAnalyzeHeapCommand } from './commands/analyze-heap-args.js';
+import { runAstGroundTruthCommand } from './commands/ast-ground-truth-args.js';
+import { runGenerateTransferModelCommand } from './commands/generate-transfer-model-args.js';
+import { runInitCommand } from './commands/init-args.js';
+import { InitWizardCancelled } from './commands/init-prompt.js';
+import { runLintGrammarCommand } from './commands/lint-grammar-args.js';
+import { runMeasureMemoryCommand } from './commands/measure-memory-args.js';
+import { runModelDocsCommand } from './commands/model-docs-args.js';
+import { runProjectsCommand } from './commands/projects-args.js';
+import { runQueryCommand } from './commands/query-args.js';
+import { runReflectCommand } from './commands/reflect-args.js';
+import { runSaveCommand } from './commands/save-args.js';
+import { runValidateCommand } from './commands/validate-args.js';
+import { runWatchCommand } from './commands/watch-args.js';
+/**
+ * The subcommand table, as name → handler over that command's own argv tail.
+ *
+ * Each handler owns its own flag parsing, in a sibling `<name>-args` module that
+ * also holds the command's flag list and its help text as data. `commander`
+ * provides the dispatch, the command list and the top-level help, but NOT the
+ * option parsing: it would generate the per-command help from declared options,
+ * at the price of its own error vocabulary replacing the messages scripts match
+ * on. `init` could not follow it there in any case — its grammar-scoped flags
+ * (`--extensions` applies to the PRECEDING `--grammar`) depend on the relative
+ * order of two DIFFERENT option names, which no declarative option model
+ * expresses.
+ */
+const COMMANDS = {
+    'analyze-heap': { summary: 'Analyze a V8 heap snapshot (needs optional @memlab/heap-analysis).', run: runAnalyzeHeapCommand },
+    'ast-ground-truth': {
+        summary: "Tally a workspace's live-model $types (analyze-heap --validate input).",
+        run: runAstGroundTruthCommand
+    },
+    'generate-transfer-model': {
+        summary: 'Generate a transfer-model TypeScript file from a Langium AST.',
+        run: runGenerateTransferModelCommand
+    },
+    init: { summary: 'Scaffold a new Hydranium language project (grammar + server head).', run: runInitCommand },
+    'lint-grammar': { summary: 'Check a grammar against framework conventions (CI gate).', run: runLintGrammarCommand },
+    'measure-memory': { summary: 'Measure model-store memory for a workspace (needs @hydranium/core).', run: runMeasureMemoryCommand },
+    'model-docs': { summary: 'Generate a navigable Markdown model reference for adopter docs.', run: runModelDocsCommand },
+    projects: { summary: 'List projects exposed by a data-server subprocess.', run: runProjectsCommand },
+    query: { summary: 'Print the data-server document envelope for a URI.', run: runQueryCommand },
+    reflect: { summary: "Dump a head's grammar/AST reflection (types, terminals, refs).", run: runReflectCommand },
+    save: { summary: 'Update + persist a document via a data-server subprocess.', run: runSaveCommand },
+    validate: { summary: 'Validate a workspace headlessly; non-zero exit on errors (CI gate).', run: runValidateCommand },
+    watch: { summary: 'Subscribe to data-server document updates; print events as NDJSON.', run: runWatchCommand }
+};
+/**
+ * The `commander` program.
+ *
+ * `.usage()` and the help formatter are pinned to the shape scripts already
+ * read — `Usage: hydranium-cli <command> [options]` with a two-space-indented
+ * command list — because a CI step that greps the usage line is a contract, not
+ * cosmetics. Each subcommand passes its raw tail through to its own handler
+ * (`.allowUnknownOption()` plus a variadic operand), so commander owns dispatch
+ * and discovery while the handlers keep the exact flag semantics they had.
+ */
+function buildProgram() {
+    const program = new Command();
+    program
+        .name('hydranium-cli')
+        .usage('<command> [options]')
+        .addHelpText('after', '\nRun `hydranium-cli <command> --help` for command-specific options.')
+        .helpOption('-h, --help', 'Show this help.')
+        // Declared so the top-level help lists it; the dispatch below answers it,
+        // because commander would otherwise never see the token — an argv whose
+        // first word is not a known subcommand is rejected before `parseAsync`.
+        .version(readCliVersion(), '-V, --version', 'Show the version.')
+        // No `help <command>` alias: the surface stays exactly the COMMANDS
+        // table, and `<command> --help` already covers what it would offer.
+        .helpCommand(false)
+        .configureHelp({ subcommandTerm: command => command.name() });
+    for (const [name, { summary, run }] of Object.entries(COMMANDS)) {
+        program
+            .command(name)
+            .summary(summary)
+            .description(summary)
+            .allowUnknownOption()
+            .allowExcessArguments()
+            .helpOption(false)
+            .argument('[args...]')
+            .action(async (args) => {
+            await run(args);
+        });
+    }
+    return program;
+}
+async function main(argv) {
+    const [command] = argv;
+    // Handled ahead of commander so the three shapes a script can depend on keep
+    // their exact contract: a bare invocation prints usage on STDOUT and exits 1,
+    // `--help` prints the same on stdout and exits 0, and an unknown command
+    // names itself on STDERR with the usage still on stdout.
+    const program = buildProgram();
+    if (!command || command === '--help' || command === '-h') {
+        program.outputHelp();
+        process.exit(command ? 0 : 1);
+    }
+    // Ahead of the unknown-command branch, which claims every first token the
+    // COMMANDS table does not name and would report the flag as a misspelt
+    // subcommand on stderr with a non-zero exit.
+    if (command === '--version' || command === '-V') {
+        console.log(readCliVersion());
+        process.exit(0);
+    }
+    if (!Object.hasOwn(COMMANDS, command)) {
+        console.error(`Unknown command: ${command}`);
+        program.outputHelp();
+        process.exit(1);
+    }
+    await program.parseAsync(argv, { from: 'user' });
+}
+main(process.argv.slice(2)).catch(err => {
+    // Ctrl-C out of the wizard is a choice, not a failure: clack has already
+    // drawn its cancel line, so printing a stack trace over it would report the
+    // user's own decision back to them as an error.
+    if (err instanceof InitWizardCancelled) {
+        process.exit(130);
+    }
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/lib/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/lib/commands/analyze-heap-args.d.ts

@@ -0,0 +1,46 @@
+/********************************************************************************
+ * 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 { type AnalyzeHeapDeps } from './analyze-heap.js';
+import { type UsageError } from './harness-args.js';
+/**
+ * Every flag `analyze-heap` accepts, derived from the three sets the parser
+ * scans so the list cannot claim a flag the parser would reject. `--help` is
+ * absent because it selects the help block rather than describing a run.
+ */
+export declare const ANALYZE_HEAP_FLAGS: readonly string[];
+/** The subset whose value is mandatory, so `--help` in a value position reads as data. */
+export declare const ANALYZE_HEAP_VALUE_FLAGS: readonly string[];
+/**
+ * The `--help` text, as data, held to {@link ANALYZE_HEAP_FLAGS} by a test.
+ *
+ * The analyzer is a standalone ESM asset spawned as a child, so this is the only
+ * copy: a second one beside its argv reads is what let its flags and its help
+ * drift apart with nothing able to see it.
+ */
+export declare const ANALYZE_HEAP_HELP: readonly string[];
+/** What {@link parseAnalyzeHeapArgs} recovered from an argv. */
+export interface AnalyzeHeapArgs {
+    /** `true` when the argv selects the JSON-vs-JSON diff, which reads no snapshot. */
+    readonly diff: boolean;
+    /** The `.heapsnapshot` to read; absent only on the {@link diff} path. */
+    readonly snapshot?: string;
+}
+/**
+ * Validate the argv the analyzer will be handed.
+ *
+ * The values themselves stay the analyzer's to read — it is a standalone ESM
+ * asset spawned as a child, and duplicating its numeric coercions here would be
+ * a second place for them to drift. What this pass adds is the rejection every
+ * sibling subcommand performs: an unrecognised token left inert makes a typo'd
+ * `--treshold 0` apply the default silently, so the caller believes a threshold
+ * is in force.
+ */
+export declare function parseAnalyzeHeapArgs(args: string[], onError?: UsageError): AnalyzeHeapArgs;
+export declare function runAnalyzeHeapCommand(args: string[], deps?: AnalyzeHeapDeps): Promise<void>;
+//# sourceMappingURL=analyze-heap-args.d.ts.map

package/lib/commands/analyze-heap-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-heap-args.d.ts","sourceRoot":"","sources":["../../src/commands/analyze-heap-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAA2C,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAoB7F;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAA6D,CAAC;AAE9G,0FAA0F;AAC1F,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAAgB,CAAC;AAEvE;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EA8D9C,CAAC;AAEF,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC7B,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAA0B,GAAG,eAAe,CAqCzG;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe/F"}

package/lib/commands/analyze-heap-args.js

@@ -0,0 +1,174 @@
+/********************************************************************************
+ * 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 { DIFF_FLAG, runAnalyzeHeap } from './analyze-heap.js';
+import { exitWithUsage, helpRequested, printHelp } from './harness-args.js';
+import { OUT_FILE_FLAG } from './headless-harness.js';
+/**
+ * Flags whose value is mandatory. `--diff` is here for
+ * {@link helpRequested}'s benefit — it takes TWO values, which the parser below
+ * handles as its own case.
+ */
+const VALUE_FLAGS = [DIFF_FLAG, OUT_FILE_FLAG, '--validate', '--json', '--threshold', '--classifier'];
+/**
+ * Flags whose value may be omitted: each names a top-N the analyzer defaults
+ * when the token is bare, so a following token is a value only when it is not
+ * itself a flag.
+ */
+const OPTIONAL_VALUE_FLAGS = ['--breakdown-depth', '--top-concepts', '--strings', '--cutpoints', '--docs', '--holders'];
+/** Presence-only flags. */
+const BOOL_FLAGS = ['--cutpoints-all', '--renderer'];
+/**
+ * Every flag `analyze-heap` accepts, derived from the three sets the parser
+ * scans so the list cannot claim a flag the parser would reject. `--help` is
+ * absent because it selects the help block rather than describing a run.
+ */
+export const ANALYZE_HEAP_FLAGS = [...VALUE_FLAGS, ...OPTIONAL_VALUE_FLAGS, ...BOOL_FLAGS];
+/** The subset whose value is mandatory, so `--help` in a value position reads as data. */
+export const ANALYZE_HEAP_VALUE_FLAGS = VALUE_FLAGS;
+/**
+ * The `--help` text, as data, held to {@link ANALYZE_HEAP_FLAGS} by a test.
+ *
+ * The analyzer is a standalone ESM asset spawned as a child, so this is the only
+ * copy: a second one beside its argv reads is what let its flags and its help
+ * drift apart with nothing able to see it.
+ */
+export const ANALYZE_HEAP_HELP = [
+    'Usage: hydranium-cli analyze-heap <snapshot> [options]',
+    '       hydranium-cli analyze-heap --diff <baseline.json> <current.json> [--threshold <pct>]',
+    '',
+    'Langium-aware V8 heap-snapshot analyzer (memlab-based). A default run (just',
+    '<snapshot>) prints a Markdown report to stdout: concept table, a hierarchical',
+    'breakdown (each concept group drilled into its colon-delimited sub-levels, e.g.',
+    'AST node -> $type, GModel -> kind -> subtype), the duplicate-string / cut-point /',
+    'per-document drill-downs, and sample retainer paths. Loading is the only real',
+    'cost, so the drill-downs run by default; tune or disable them with the flags',
+    'below. The Markdown reads fine as text, saves as a .md file (--out-file), and',
+    'is ideal input for the memory-analysis skill.',
+    '',
+    'Reading a snapshot needs the optional @memlab/core + @memlab/heap-analysis peer',
+    'dependencies (`npm install @memlab/core @memlab/heap-analysis`); --diff and',
+    '--help need neither.',
+    '',
+    'Options:',
+    '  <snapshot>               the .heapsnapshot to read; omit only with --diff (required).',
+    '  --out-file <file.md>     also write the Markdown report to a file',
+    '  --breakdown-depth [N]    max DISPLAY depth of the hierarchical breakdown',
+    '                           (default: full depth). Aggregation is always',
+    '                           depth-agnostic; a cap only hides deeper rows — their',
+    '                           bytes still roll up into the deepest shown row.',
+    '  --top-concepts [N]       how many of the biggest anchor concepts get a',
+    '                           retainer-path sample and are the default --holders',
+    '                           targets (default 6)',
+    '  --strings [N]            duplicate plain strings, top N (default 20; 0 = off)',
+    '  --cutpoints [N]          lightweight sole owners, top N (default 10; 0 = off)',
+    '  --cutpoints-all          include Node/V8/server runtime owners (default: model only)',
+    '  --docs [N]               heaviest documents, top N (default 15; 0 = off).',
+    '                           Langium/server-only — skipped in --renderer mode (a',
+    '                           renderer heap has no documents).',
+    '  --holders [a,b,c]        who holds each concept: dominator + referrer tallies,',
+    '                           comma-separated, one heap pass (e.g. CST,Range,Map);',
+    '                           no value = the top model concepts',
+    "  --validate <gt.json>     validate the snapshot's $type classification against",
+    '                           the live model (ground truth from the',
+    '                           hydranium-cli ast-ground-truth subcommand); flags',
+    '                           drift and computed/derived types',
+    '  --json <file>            write the analysis as JSON (baseline artifact for --diff)',
+    '  --diff <base> <cur>      diff two analysis JSONs; prints deltas + verdict,',
+    '                           exits non-zero on regression (no snapshot needed)',
+    '  --threshold <pct>        regression threshold for --diff, % growth of total',
+    '                           shallow (default 5)',
+    '  --renderer               analyze a BROWSER/renderer heap (the browser-heap',
+    '                           artefact, from CDP) instead of a Langium server heap:',
+    '                           buckets by DOM vocabulary (Detached DOM / DOM node /',
+    '                           Event listener) and the retainer paths to each detached',
+    '                           concept ARE the listener-retainer analysis. Skips the',
+    '                           Langium/GLSP classifiers + --validate (no ground truth).',
+    '  --classifier <file>      ESM module default-exporting a ConceptClassifier',
+    '                           (classify(node) -> a colon-delimited label path, +',
+    '                           optional anchorConcepts/grammarTypes/isAnchor) to label',
+    "                           a head's own concepts; repeatable. Tried BEFORE the",
+    '                           built-in Langium + GLSP defaults (return undefined to',
+    '                           defer), so a more specific classifier overrides a',
+    '                           default. Order = precedence.',
+    '  -h, --help               show this help',
+    '',
+    'Notes: snapshot is the language-server process only (no other processes, native',
+    'memory, or browser heap).'
+];
+/**
+ * Validate the argv the analyzer will be handed.
+ *
+ * The values themselves stay the analyzer's to read — it is a standalone ESM
+ * asset spawned as a child, and duplicating its numeric coercions here would be
+ * a second place for them to drift. What this pass adds is the rejection every
+ * sibling subcommand performs: an unrecognised token left inert makes a typo'd
+ * `--treshold 0` apply the default silently, so the caller believes a threshold
+ * is in force.
+ */
+export function parseAnalyzeHeapArgs(args, onError = exitWithUsage) {
+    const mandatoryValue = new Set(VALUE_FLAGS);
+    const optionalValue = new Set(OPTIONAL_VALUE_FLAGS);
+    const presenceOnly = new Set(BOOL_FLAGS);
+    let diff = false;
+    let snapshot;
+    for (let index = 0; index < args.length; index += 1) {
+        const flag = args[index];
+        if (flag === DIFF_FLAG) {
+            diff = true;
+            if (args[index + 1] === undefined || args[index + 2] === undefined) {
+                onError(`Missing value for ${DIFF_FLAG}`);
+            }
+            index += 2;
+        }
+        else if (mandatoryValue.has(flag)) {
+            if (args[index + 1] === undefined) {
+                onError(`Missing value for ${flag}`);
+            }
+            index += 1;
+        }
+        else if (optionalValue.has(flag)) {
+            if (args[index + 1] !== undefined && !args[index + 1].startsWith('-')) {
+                index += 1;
+            }
+        }
+        else if (presenceOnly.has(flag)) {
+            // Nothing to claim; the analyzer reads its presence.
+        }
+        else if (flag.startsWith('-')) {
+            onError(`Unknown option: ${flag} (hydranium-cli analyze-heap --help)`);
+        }
+        else if (snapshot === undefined) {
+            snapshot = flag;
+        }
+        else {
+            onError(`Unexpected argument: ${flag} (hydranium-cli analyze-heap --help)`);
+        }
+    }
+    if (!diff && snapshot === undefined) {
+        onError('Missing required option: <snapshot> (hydranium-cli analyze-heap --help)');
+    }
+    return { diff, snapshot };
+}
+export function runAnalyzeHeapCommand(args, deps = {}) {
+    if (args.length === 0) {
+        // Usage on stdout and a non-zero exit, matching the parent binary's bare
+        // invocation: a CI step that forgot its snapshot argument must fail rather
+        // than read a help page as a completed analysis.
+        printHelp(ANALYZE_HEAP_HELP);
+        process.exitCode = 1;
+        return Promise.resolve();
+    }
+    if (helpRequested(args, ANALYZE_HEAP_VALUE_FLAGS)) {
+        printHelp(ANALYZE_HEAP_HELP);
+        return Promise.resolve();
+    }
+    parseAnalyzeHeapArgs(args);
+    return runAnalyzeHeap(args, deps);
+}
+//# sourceMappingURL=analyze-heap-args.js.map

package/lib/commands/analyze-heap-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-heap-args.js","sourceRoot":"","sources":["../../src/commands/analyze-heap-args.ts"],"names":[],"mappings":"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"}

package/lib/commands/analyze-heap.d.ts

@@ -0,0 +1,37 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Selects the JSON-vs-JSON comparison, which reads two analysis artifacts and
+ * needs neither a snapshot nor memlab. Declared here rather than in the args
+ * module so the guard below and the flag list read the same constant.
+ */
+export declare const DIFF_FLAG = "--diff";
+/** Test-only injection seam for {@link runAnalyzeHeap}, mirroring the sibling harness commands. */
+export interface AnalyzeHeapDeps {
+    /** Capture the node argv instead of spawning the real analyzer child. */
+    readonly __spawnForTest?: (execArgs: string[]) => Promise<number>;
+    /** Override the memlab-availability check. */
+    readonly __memlabInstalledForTest?: () => boolean;
+}
+/**
+ * Run the heap-snapshot analyzer. Memlab is an OPTIONAL PEER dependency and a
+ * heavy one — it drags in a browser download — so an install of this package
+ * pulls in nothing, and a caller that wants heap analysis opts in with the
+ * install line the guard below prints. This subcommand loads it only when
+ * invoked, by spawning the bundled analyzer in a child process with the large
+ * heap memlab needs. All arguments are forwarded verbatim — the analyzer owns
+ * how it reads them.
+ *
+ * The guard is skipped for {@link DIFF_FLAG}, which the analyzer short-circuits
+ * before any memlab import: refusing it would demand ~86 MB of dependency for a
+ * run that reads two JSON files. Help is intercepted earlier still, by the args
+ * module, so it never reaches this function.
+ */
+export declare function runAnalyzeHeap(args: string[], deps?: AnalyzeHeapDeps): Promise<void>;
+//# sourceMappingURL=analyze-heap.d.ts.map

package/lib/commands/analyze-heap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-heap.d.ts","sourceRoot":"","sources":["../../src/commands/analyze-heap.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAuBlF;;;;GAIG;AACH,eAAO,MAAM,SAAS,WAAW,CAAC;AAElC,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClE,8CAA8C;IAC9C,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,OAAO,CAAC;CACpD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB9F"}

package/lib/commands/analyze-heap.js

@@ -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 { fileURLToPath } from 'node:url';
+import { spawnNodeChild } from './headless-harness.js';
+/**
+ * Absolute path to the bundled memlab-based analyzer (a standalone ESM script
+ * shipped under the package's `heap-analysis/` assets, not the compiled `lib/`).
+ * From `lib/commands/analyze-heap.js` that is `../../heap-analysis/analyze-heap.mjs`.
+ */
+const ANALYZER = fileURLToPath(new URL('../../heap-analysis/analyze-heap.mjs', import.meta.url));
+/** `true` when the optional `@memlab/heap-analysis` dependency is installed and resolvable. */
+function memlabInstalled() {
+    const resolve = import.meta.resolve;
+    try {
+        resolve?.('@memlab/heap-analysis');
+        return resolve !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Selects the JSON-vs-JSON comparison, which reads two analysis artifacts and
+ * needs neither a snapshot nor memlab. Declared here rather than in the args
+ * module so the guard below and the flag list read the same constant.
+ */
+export const DIFF_FLAG = '--diff';
+/**
+ * Run the heap-snapshot analyzer. Memlab is an OPTIONAL PEER dependency and a
+ * heavy one — it drags in a browser download — so an install of this package
+ * pulls in nothing, and a caller that wants heap analysis opts in with the
+ * install line the guard below prints. This subcommand loads it only when
+ * invoked, by spawning the bundled analyzer in a child process with the large
+ * heap memlab needs. All arguments are forwarded verbatim — the analyzer owns
+ * how it reads them.
+ *
+ * The guard is skipped for {@link DIFF_FLAG}, which the analyzer short-circuits
+ * before any memlab import: refusing it would demand ~86 MB of dependency for a
+ * run that reads two JSON files. Help is intercepted earlier still, by the args
+ * module, so it never reaches this function.
+ */
+export async function runAnalyzeHeap(args, deps = {}) {
+    const isMemlabInstalled = deps.__memlabInstalledForTest ?? memlabInstalled;
+    if (!args.includes(DIFF_FLAG) && !isMemlabInstalled()) {
+        console.error('analyze-heap needs the optional @memlab/heap-analysis dependency (heavy: ~86 MB).\n' +
+            'It is an optional peer dependency, so it is not installed by default; add it with:\n' +
+            '  npm install @memlab/core @memlab/heap-analysis');
+        process.exitCode = 1;
+        return;
+    }
+    const spawnChild = deps.__spawnForTest ?? spawnNodeChild;
+    const code = await spawnChild(['--max-old-space-size=8192', ANALYZER, ...args]);
+    if (code) {
+        process.exitCode = code;
+    }
+}
+//# sourceMappingURL=analyze-heap.js.map

package/lib/commands/analyze-heap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-heap.js","sourceRoot":"","sources":["../../src/commands/analyze-heap.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,sCAAsC,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAEjG,+FAA+F;AAC/F,SAAS,eAAe;IACrB,MAAM,OAAO,GAAI,MAAM,CAAC,IAAoD,CAAC,OAAO,CAAC;IACrF,IAAI,CAAC;QACF,OAAO,EAAE,CAAC,uBAAuB,CAAC,CAAC;QACnC,OAAO,OAAO,KAAK,SAAS,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACN,OAAO,KAAK,CAAC;IAChB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;AAUlC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAc,EAAE,OAAwB,EAAE;IAC5E,MAAM,iBAAiB,GAAG,IAAI,CAAC,wBAAwB,IAAI,eAAe,CAAC;IAC3E,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC;QACrD,OAAO,CAAC,KAAK,CACV,qFAAqF;YAClF,sFAAsF;YACtF,kDAAkD,CACvD,CAAC;QACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACV,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,IAAI,cAAc,CAAC;IACzD,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,CAAC,2BAA2B,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IAChF,IAAI,IAAI,EAAE,CAAC;QACR,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC3B,CAAC;AACJ,CAAC"}

package/lib/commands/ast-ground-truth-args.d.ts

@@ -0,0 +1,23 @@
+/********************************************************************************
+ * 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 { type AstGroundTruthCommandOptions } from './ast-ground-truth.js';
+import { type UsageError } from './harness-args.js';
+/**
+ * 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 declare const AST_GROUND_TRUTH_FLAGS: readonly string[];
+/** The subset that takes a value, so `--help` in a value position reads as data. */
+export declare const AST_GROUND_TRUTH_VALUE_FLAGS: readonly string[];
+/** The `--help` text, as data, held to {@link AST_GROUND_TRUTH_FLAGS} by a test. */
+export declare const AST_GROUND_TRUTH_HELP: readonly string[];
+export declare function parseAstGroundTruthArgs(args: string[], onError?: UsageError): AstGroundTruthCommandOptions;
+export declare function runAstGroundTruthCommand(args: string[]): Promise<void>;
+//# sourceMappingURL=ast-ground-truth-args.d.ts.map

package/lib/commands/ast-ground-truth-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-ground-truth-args.d.ts","sourceRoot":"","sources":["../../src/commands/ast-ground-truth-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAqB,KAAK,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EASJ,KAAK,UAAU,EACjB,MAAM,mBAAmB,CAAC;AAK3B;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAoC,CAAC;AAEzF,oFAAoF;AACpF,eAAO,MAAM,4BAA4B,EAAE,SAAS,MAAM,EAA2B,CAAC;AAEtF,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAalD,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAA0B,GAAG,4BAA4B,CAGzH;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAMtE"}

package/lib/commands/ast-ground-truth-args.js

@@ -0,0 +1,47 @@
+/********************************************************************************
+ * 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 } from './ast-ground-truth.js';
+import { exitWithUsage, helpRequested, LOG_LEVEL_FLAG, logLevelHelpLine, logLevelOption, parseHarnessArgs, printHelp, SERVICES_FLAG } from './harness-args.js';
+import { OUT_FILE_FLAG } from './headless-harness.js';
+const VALUE_FLAGS = [OUT_FILE_FLAG, LOG_LEVEL_FLAG];
+/**
+ * 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 = [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 = 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 = [
+    '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, onError = exitWithUsage) {
+    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) {
+    if (helpRequested(args, AST_GROUND_TRUTH_VALUE_FLAGS)) {
+        printHelp(AST_GROUND_TRUTH_HELP);
+        return Promise.resolve();
+    }
+    return runAstGroundTruth(parseAstGroundTruthArgs(args));
+}
+//# sourceMappingURL=ast-ground-truth-args.js.map

package/lib/commands/ast-ground-truth-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-ground-truth-args.js","sourceRoot":"","sources":["../../src/commands/ast-ground-truth-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,iBAAiB,EAAqC,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EACJ,aAAa,EACb,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,aAAa,EAEf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,MAAM,WAAW,GAAG,CAAC,aAAa,EAAE,cAAc,CAAU,CAAC;AAE7D;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsB,CAAC,aAAa,EAAE,GAAG,WAAW,CAAC,CAAC;AAEzF,oFAAoF;AACpF,MAAM,CAAC,MAAM,4BAA4B,GAAsB,sBAAsB,CAAC;AAEtF,oFAAoF;AACpF,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACrD,+GAA+G;IAC/G,EAAE;IACF,6EAA6E;IAC7E,gFAAgF;IAChF,oEAAoE;IACpE,0EAA0E;IAC1E,EAAE;IACF,UAAU;IACV,yFAAyF;IACzF,gFAAgF;IAChF,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,UAAU,uBAAuB,CAAC,IAAc,EAAE,UAAsB,aAAa;IACxF,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,EAAE,WAAW,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IACxH,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC;AAC5H,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,IAAc;IACpD,IAAI,aAAa,CAAC,IAAI,EAAE,4BAA4B,CAAC,EAAE,CAAC;QACrD,SAAS,CAAC,qBAAqB,CAAC,CAAC;QACjC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,iBAAiB,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/lib/commands/ast-ground-truth-driver.d.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+export {};
+//# sourceMappingURL=ast-ground-truth-driver.d.ts.map

package/lib/commands/ast-ground-truth-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-ground-truth-driver.d.ts","sourceRoot":"","sources":["../../src/commands/ast-ground-truth-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF"}