@hydranium/cli 1.0.0-next.10

package/lib/commands/init.js

@@ -0,0 +1,303 @@
+/********************************************************************************
+ * 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 { buildInitTemplates, readFrameworkVersion, UNPUBLISHED_FRAMEWORK_VERSION } from './init-templates.js';
+import { createNodeWorkspaceProbe, detectWorkspace } from './init-workspace.js';
+/**
+ * The protocol heads a scaffold can start, in composition order.
+ *
+ * `lsp` is mandatory rather than optional: it owns the workspace, the build
+ * pipeline and the shared service tier every other head reads through, so a
+ * project without it has nothing for `data` or `glsp` to serve.
+ */
+export const INIT_HEADS = ['lsp', 'data', 'glsp'];
+/** The heads a scaffold emits when `--heads` is not given. */
+export const DEFAULT_INIT_HEADS = ['lsp', 'data'];
+/** True for a string naming one of {@link INIT_HEADS}. */
+export function isInitHead(value) {
+    return INIT_HEADS.includes(value);
+}
+/**
+ * A standalone, unscoped, unpublishable package — what `init` emits without the
+ * packaging flags.
+ *
+ * `private` defaults to TRUE because the manifest also declares `license:
+ * "UNLICENSED"`, and a package that grants no rights while being publishable to
+ * a public registry asserts two contradictory things about itself. npm pairs
+ * those two keys for exactly this reason. The scaffold cannot pick a licence for
+ * a stranger's project, so it withholds publication instead of granting rights
+ * nobody chose; `--public` is the opt-out for a project that has picked one.
+ */
+export const STANDALONE_PACKAGING = { private: true };
+/** Kebab-case a PascalCase/camelCase name. */
+export function kebab(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+/** True for a PascalCase identifier legal as a generated TypeScript symbol prefix. */
+function isPascalIdentifier(value) {
+    return /^[A-Za-z][A-Za-z0-9]*$/.test(value);
+}
+/** Strip a leading dot and reject an extension that is empty or dotted through. */
+function normalizeExtension(value, grammar) {
+    const extension = value.replace(/^\./, '');
+    if (extension.length === 0) {
+        throw new Error(`Invalid extension '${value}' for grammar '${grammar}': an extension cannot be empty.`);
+    }
+    return extension;
+}
+/**
+ * Resolve one grammar's names.
+ *
+ * `qualify` comes from the project rather than the grammar: a lone grammar
+ * whose name matches the project keeps the bare project id, but as soon as
+ * there are several every id is qualified, so the set reads consistently
+ * instead of one member being special.
+ */
+function resolveGrammar(spec, projectId, qualify, diagram) {
+    if (!isPascalIdentifier(spec.name)) {
+        throw new Error(`Invalid --grammar '${spec.name}': must be a PascalCase identifier (letters and digits, starting with a letter), e.g. 'Domain'.`);
+    }
+    const grammarId = kebab(spec.name);
+    const extensions = (spec.extensions ?? [grammarId]).map(extension => normalizeExtension(extension, spec.name));
+    if (extensions.length === 0) {
+        throw new Error(`Invalid --extensions for grammar '${spec.name}': at least one extension is required.`);
+    }
+    return {
+        grammar: spec.name,
+        grammarId,
+        languageId: spec.languageId ?? (qualify || grammarId !== projectId ? `${projectId}-${grammarId}` : projectId),
+        extensions,
+        entryRule: `${spec.name}Model`,
+        nodeRule: `${spec.name}Node`,
+        diagram
+    };
+}
+/**
+ * Resolve which grammars get a diagram.
+ *
+ * With the `glsp` head on and nothing marked, a lone grammar is unambiguous and
+ * is taken as the diagram's; with several it is a real choice, so it is required
+ * rather than guessed — binding a diagram to the wrong grammar surfaces much
+ * later as references resolving against the wrong scope.
+ */
+function resolveDiagrams(specs, heads) {
+    const marked = specs.map(spec => spec.diagram === true);
+    if (!heads.includes('glsp')) {
+        const named = specs.filter(spec => spec.diagram === true).map(spec => spec.name);
+        if (named.length > 0) {
+            throw new Error(`--diagram was given for ${named.join(', ')} but the head set is '${heads.join(',')}'. ` +
+                "Add 'glsp' to --heads, since the emitted dependencies follow the head set.");
+        }
+        return marked;
+    }
+    if (marked.some(Boolean)) {
+        return marked;
+    }
+    if (specs.length === 1) {
+        return [true];
+    }
+    throw new Error(`--heads includes 'glsp' but no grammar carries --diagram. Mark the one the diagram edits: ` +
+        `${specs.map(spec => spec.name).join(', ')}.`);
+}
+/** Validate the head set: known names only, and `lsp` present. */
+function resolveHeads(heads) {
+    const resolved = heads === undefined || heads.length === 0 ? DEFAULT_INIT_HEADS : heads;
+    const unknown = resolved.filter(head => !isInitHead(head));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown head(s) '${unknown.join(', ')}': expected one of ${INIT_HEADS.join(', ')}.`);
+    }
+    if (!resolved.includes('lsp')) {
+        throw new Error("--heads must include 'lsp': it owns the workspace, the build pipeline and the shared service tier the other heads read through.");
+    }
+    // De-duplicated and put back in composition order, so the order the heads
+    // were named in does not change the emitted project.
+    return INIT_HEADS.filter(head => resolved.includes(head));
+}
+/**
+ * Reject the collisions that would otherwise surface as a confusing generator
+ * or runtime failure rather than as a bad invocation.
+ *
+ * The extension check is the one worth having: Langium routes documents to a
+ * language BY extension, so two grammars claiming `.foo` is not a name clash
+ * but a silent mis-route of every `.foo` file to whichever language registered
+ * first.
+ */
+function assertNoCollisions(grammars) {
+    const byGrammarId = new Map();
+    const byLanguageId = new Map();
+    const byExtension = new Map();
+    for (const grammar of grammars) {
+        const clashingName = byGrammarId.get(grammar.grammarId);
+        if (clashingName !== undefined) {
+            throw new Error(`Duplicate grammar '${grammar.grammar}': it resolves to the same file as '${clashingName}'.`);
+        }
+        byGrammarId.set(grammar.grammarId, grammar.grammar);
+        const clashingLanguage = byLanguageId.get(grammar.languageId);
+        if (clashingLanguage !== undefined) {
+            throw new Error(`Duplicate language id '${grammar.languageId}': claimed by both '${clashingLanguage}' and '${grammar.grammar}'.`);
+        }
+        byLanguageId.set(grammar.languageId, grammar.grammar);
+        for (const extension of grammar.extensions) {
+            const clashingExtension = byExtension.get(extension);
+            if (clashingExtension !== undefined) {
+                throw new Error(`File extension '.${extension}' is claimed by both '${clashingExtension}' and '${grammar.grammar}'. ` +
+                    'Langium routes documents by extension, so each grammar needs its own.');
+            }
+            byExtension.set(extension, grammar.grammar);
+        }
+    }
+}
+/**
+ * Derive the whole scaffold description from `--name` plus the collected
+ * grammars. Throws on a name that is not a valid PascalCase identifier — both
+ * project and grammar names become prefixes of generated TypeScript symbols.
+ *
+ * With no grammars given, one is synthesised from the project name, which is
+ * the single-language starter shape.
+ */
+export function resolveInitComposition(name, grammars = [], heads, packaging = STANDALONE_PACKAGING) {
+    if (!isPascalIdentifier(name)) {
+        throw new Error(`Invalid --name '${name}': must be a PascalCase identifier (letters and digits, starting with a letter), e.g. 'Bookstore'.`);
+    }
+    const projectId = kebab(name);
+    if (packaging.scope !== undefined && !/^@[a-z0-9][a-z0-9._-]*$/.test(packaging.scope)) {
+        throw new Error(`Invalid --scope '${packaging.scope}': an npm scope starts with '@', e.g. '@acme'.`);
+    }
+    const resolvedHeads = resolveHeads(heads);
+    const specs = grammars.length > 0 ? grammars : [{ name }];
+    const diagrams = resolveDiagrams(specs, resolvedHeads);
+    const resolved = specs.map((spec, index) => resolveGrammar(spec, projectId, specs.length > 1, diagrams[index]));
+    assertNoCollisions(resolved);
+    return { name, projectId, heads: resolvedHeads, grammars: resolved, packaging, frameworkVersion: readFrameworkVersion() };
+}
+/**
+ * Plan the files a scaffold emits — every template rendered for this
+ * composition. Pure over its input → unit-testable without touching disk;
+ * {@link runInit} is the thin IO wrapper.
+ */
+export function planInitFiles(composition) {
+    return buildInitTemplates(composition);
+}
+/** True when `dir` exists and contains at least one entry. */
+export function isNonEmptyDir(dir) {
+    return fs.existsSync(dir) && fs.statSync(dir).isDirectory() && fs.readdirSync(dir).length > 0;
+}
+/**
+ * Resolve the packaging tier for a target directory, running workspace
+ * detection when `--monorepo` asked for it.
+ *
+ * Exported because the `init`-provenance gate re-runs the reference example's
+ * recorded invocation and must reach the same composition `runInit` would: a
+ * second copy of these rules there would drift from these, and the gate exists
+ * precisely to catch drift.
+ */
+export function resolveInitPackaging(targetDir, options) {
+    if (options.monorepo !== true) {
+        return { scope: options.scope, private: options.public !== true };
+    }
+    const detection = detectWorkspace(targetDir, options.probe ?? createNodeWorkspaceProbe());
+    if (detection === undefined) {
+        throw new Error(`--monorepo was given but no ancestor of '${path.resolve(targetDir)}' has a package.json declaring 'workspaces'. ` +
+            'Scaffold without it for a standalone project.');
+    }
+    return {
+        scope: options.scope,
+        private: options.public !== true,
+        // The scope and the publishability deliberately do NOT fall back to what
+        // detection found: the emitted package name stays a function of the argv
+        // alone, which is what lets the wizard's echoed command reproduce the
+        // scaffold anywhere. Detection only supplies the wizard's DEFAULT answer.
+        workspace: {
+            targetPath: detection.targetPath,
+            baseTsconfig: detection.baseTsconfig,
+            baseCompilerOptions: detection.baseCompilerOptions,
+            printWidth: detection.printWidth,
+            eslintConfig: detection.eslintConfig
+        }
+    };
+}
+/**
+ * Scaffold a new Hydranium language project end-to-end: one starter grammar per
+ * `--grammar`, `create<Name>Services` DI wiring, a launcher for each head in
+ * `--heads`, `langium-config.json`, `package.json`, and scripts. Does NOT run `npm install`
+ * or `langium generate` — those are printed as next steps, so the command stays
+ * offline and side-effect-free beyond the files it writes. Refuses a non-empty
+ * target directory unless `force`.
+ */
+export function runInit(options) {
+    const write = options.write ?? ((line) => process.stdout.write(line));
+    const targetDir = path.resolve(options.targetDir);
+    const detection = options.monorepo ? detectWorkspace(targetDir, options.probe ?? createNodeWorkspaceProbe()) : undefined;
+    const composition = resolveInitComposition(options.name, options.grammars, options.heads, resolveInitPackaging(targetDir, options));
+    if (!options.force && isNonEmptyDir(targetDir)) {
+        throw new Error(`Target directory '${targetDir}' is not empty. Pass --force to scaffold into it anyway.`);
+    }
+    const files = planInitFiles(composition);
+    if (options.__writeFilesForTest) {
+        options.__writeFilesForTest(targetDir, files);
+    }
+    else {
+        for (const file of files) {
+            const absolute = path.join(targetDir, file.path);
+            fs.mkdirSync(path.dirname(absolute), { recursive: true });
+            fs.writeFileSync(absolute, file.content, 'utf-8');
+        }
+    }
+    const grammarList = composition.grammars.map(grammar => (grammar.diagram ? `${grammar.grammar} (diagram)` : grammar.grammar)).join(', ');
+    write(`Scaffolded ${composition.name} (${files.length} files, heads: ${composition.heads.join(',')}, ` +
+        `${composition.grammars.length} grammar(s): ${grammarList}) into ${targetDir}\n`);
+    if (detection !== undefined) {
+        write('\n');
+        write(`Workspace root: ${detection.rootDir}\n`);
+        if (detection.baseTsconfig !== undefined) {
+            write(`  tsconfig.json extends ${detection.baseTsconfig}, minus the options it inherits unchanged.\n`);
+        }
+        else {
+            write('  No root tsconfig carries compilerOptions, so the emitted one stands alone.\n');
+        }
+        write("  .gitignore holds `syntaxes/` only — the workspace root's covers the rest.\n");
+        if (detection.printWidth !== undefined) {
+            write(`  Sources wrapped at ${detection.printWidth} columns, from ${detection.rootDir}'s prettier config.\n`);
+        }
+        if (detection.eslintConfig !== undefined) {
+            write(`  A lint script was added — ${detection.eslintConfig} says this repo lints. Adjust it if your invocation differs.\n`);
+        }
+        // Printed rather than applied: `init` writes inside the target directory
+        // and nowhere else, so a scaffold can never surprise-edit a manifest that
+        // is under review, mid-rebase, or simply not the caller's to change.
+        if (detection.coveredBy === undefined) {
+            write(`  Add this to "workspaces" in ${path.join(detection.rootDir, 'package.json')}:\n`);
+            write(`    "${detection.targetPath}"\n`);
+        }
+        else {
+            write(`  Already covered by the "${detection.coveredBy}" workspaces entry — no root manifest change needed.\n`);
+        }
+        if (composition.packaging.scope === undefined && detection.scope !== undefined) {
+            write(`  Sibling packages all use the "${detection.scope}" scope; pass --scope ${detection.scope} to match them.\n`);
+        }
+    }
+    write('\n');
+    write('Next steps:\n');
+    write(`  cd ${options.targetDir}\n`);
+    // The warning is conditional on the pins this scaffold actually carries — see
+    // `UNPUBLISHED_FRAMEWORK_VERSION`.
+    write(composition.frameworkVersion === UNPUBLISHED_FRAMEWORK_VERSION
+        ? '  npm install              # 404s until @hydranium/* is published — see README\n'
+        : '  npm install\n');
+    write('  npm run build            # langium generate + tsc\n');
+    write('  npm test                 # the scaffolded DI-composition test\n');
+    // `npx`, not a bare invocation: `@hydranium/cli` is a devDependency of the
+    // scaffold, so the binary is on PATH inside an npm script and nowhere else.
+    write('  npx hydranium-cli reflect --services ./lib/services.js\n');
+    write('\n');
+    write('The emitted sources carry no license header — run your own header tool if\n');
+    write('your repo gates them. See the README section on that.\n');
+}
+//# sourceMappingURL=init.js.map

package/lib/commands/init.js.map

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

package/lib/commands/lint-grammar-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 UsageError } from './harness-args.js';
+import { type LintGrammarCommandOptions } from './lint-grammar.js';
+/**
+ * Every flag `lint-grammar` 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 LINT_GRAMMAR_FLAGS: readonly string[];
+/** The subset that takes a value, so `--help` in a value position reads as data. */
+export declare const LINT_GRAMMAR_VALUE_FLAGS: readonly string[];
+/** The `--help` text, as data, held to {@link LINT_GRAMMAR_FLAGS} by a test. */
+export declare const LINT_GRAMMAR_HELP: readonly string[];
+export declare function parseLintGrammarArgs(args: string[], onError?: UsageError): LintGrammarCommandOptions;
+export declare function runLintGrammarCommand(args: string[]): Promise<void>;
+//# sourceMappingURL=lint-grammar-args.d.ts.map

package/lib/commands/lint-grammar-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint-grammar-args.d.ts","sourceRoot":"","sources":["../../src/commands/lint-grammar-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EASJ,KAAK,UAAU,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAkB,KAAK,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAMnF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAA8E,CAAC;AAE/H,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAA+D,CAAC;AAEtH,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAkB9C,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,UAA0B,GAAG,yBAAyB,CAanH;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnE"}

package/lib/commands/lint-grammar-args.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 { exitWithUsage, helpRequested, LOG_LEVEL_FLAG, logLevelHelpLine, logLevelOption, parseHarnessArgs, printHelp, SERVICES_FLAG } from './harness-args.js';
+import { runLintGrammar } from './lint-grammar.js';
+const VALUE_FLAGS = [LOG_LEVEL_FLAG];
+const BOOL_FLAGS = ['--strict', '--json'];
+const REPEATABLE_VALUE_FLAGS = ['--name-property'];
+/**
+ * Every flag `lint-grammar` 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 LINT_GRAMMAR_FLAGS = [SERVICES_FLAG, ...REPEATABLE_VALUE_FLAGS, ...VALUE_FLAGS, ...BOOL_FLAGS];
+/** The subset that takes a value, so `--help` in a value position reads as data. */
+export const LINT_GRAMMAR_VALUE_FLAGS = [SERVICES_FLAG, ...REPEATABLE_VALUE_FLAGS, ...VALUE_FLAGS];
+/** The `--help` text, as data, held to {@link LINT_GRAMMAR_FLAGS} by a test. */
+export const LINT_GRAMMAR_HELP = [
+    'Usage: hydranium-cli lint-grammar --services <module> [--name-property <p>]... [--strict] [--json] [--log-level <lvl>]',
+    '',
+    "Check a head's grammar against the framework's conventions — a CI gate: the",
+    'process exits non-zero when a violation is found. Read-only: no workspace is',
+    'built (the grammar is static once the head registers its language), so',
+    '`lint-grammar` takes no `<workspace>`. Checks that every concrete cross-reference',
+    'target carries a name property (else references cannot resolve) and that each',
+    'language declares an entry rule. `<module>` is an ESM module exporting a',
+    'zero-arg `createServices(): { shared }` thunk. Needs @hydranium/core.',
+    '',
+    'Options:',
+    '  --services <module>    ESM module exporting `createServices(): { shared }` (required).',
+    '  --name-property <p>    Property that satisfies the nameability convention',
+    '                         (repeatable). Default: name.',
+    '  --strict               Also fail (non-zero exit) on warnings, not only errors.',
+    '  --json                 Emit the raw JSON result instead of the human report.',
+    logLevelHelpLine(23)
+];
+export function parseLintGrammarArgs(args, onError = exitWithUsage) {
+    const { servicesModule, options, values } = parseHarnessArgs(args, 'lint-grammar', VALUE_FLAGS, BOOL_FLAGS, {
+        requireWorkspace: false,
+        repeatableValueFlags: REPEATABLE_VALUE_FLAGS,
+        onError
+    });
+    return {
+        servicesModule,
+        nameProperties: values['--name-property'],
+        strict: options['--strict'] === 'true',
+        json: options['--json'] === 'true',
+        logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+    };
+}
+export function runLintGrammarCommand(args) {
+    if (helpRequested(args, LINT_GRAMMAR_VALUE_FLAGS)) {
+        printHelp(LINT_GRAMMAR_HELP);
+        return Promise.resolve();
+    }
+    return runLintGrammar(parseLintGrammarArgs(args));
+}
+//# sourceMappingURL=lint-grammar-args.js.map

package/lib/commands/lint-grammar-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint-grammar-args.js","sourceRoot":"","sources":["../../src/commands/lint-grammar-args.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,aAAa,EACb,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,aAAa,EAEf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAkC,MAAM,mBAAmB,CAAC;AAEnF,MAAM,WAAW,GAAG,CAAC,cAAc,CAAU,CAAC;AAC9C,MAAM,UAAU,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAU,CAAC;AACnD,MAAM,sBAAsB,GAAG,CAAC,iBAAiB,CAAU,CAAC;AAE5D;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAsB,CAAC,aAAa,EAAE,GAAG,sBAAsB,EAAE,GAAG,WAAW,EAAE,GAAG,UAAU,CAAC,CAAC;AAE/H,oFAAoF;AACpF,MAAM,CAAC,MAAM,wBAAwB,GAAsB,CAAC,aAAa,EAAE,GAAG,sBAAsB,EAAE,GAAG,WAAW,CAAC,CAAC;AAEtH,gFAAgF;AAChF,MAAM,CAAC,MAAM,iBAAiB,GAAsB;IACjD,wHAAwH;IACxH,EAAE;IACF,6EAA6E;IAC7E,8EAA8E;IAC9E,wEAAwE;IACxE,mFAAmF;IACnF,+EAA+E;IAC/E,0EAA0E;IAC1E,uEAAuE;IACvE,EAAE;IACF,UAAU;IACV,0FAA0F;IAC1F,6EAA6E;IAC7E,uDAAuD;IACvD,kFAAkF;IAClF,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,UAAU,oBAAoB,CAAC,IAAc,EAAE,UAAsB,aAAa;IACrF,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE;QACzG,gBAAgB,EAAE,KAAK;QACvB,oBAAoB,EAAE,sBAAsB;QAC5C,OAAO;KACT,CAAC,CAAC;IACH,OAAO;QACJ,cAAc;QACd,cAAc,EAAE,MAAM,CAAC,iBAAiB,CAAC;QACzC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,MAAM;QACtC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,MAAM;QAClC,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;KACnD,CAAC;AACL,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAc;IACjD,IAAI,aAAa,CAAC,IAAI,EAAE,wBAAwB,CAAC,EAAE,CAAC;QACjD,SAAS,CAAC,iBAAiB,CAAC,CAAC;QAC7B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IACD,OAAO,cAAc,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC;AACrD,CAAC"}

package/lib/commands/lint-grammar-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=lint-grammar-driver.d.ts.map

package/lib/commands/lint-grammar-driver.d.ts.map

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

package/lib/commands/lint-grammar-driver.js

@@ -0,0 +1,72 @@
+/********************************************************************************
+ * 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 `lint-grammar` subcommand. Launched by the parent with
+ * `node <this> --services <module> [--name-property <p>]... [--json] [--strict]`.
+ * It dynamic-imports the head's services module, runs the framework's
+ * `lintGrammar`, prints the report (human or `--json`) and exits with the gate
+ * code (non-zero on errors; `--strict` also fails on warnings). Never imported —
+ * only spawned.
+ */
+import { loadHeadlessContext } from './headless-harness.js';
+import { formatLintReport, lintExitCode } from './lint-grammar-report.js';
+function parseArgs(argv) {
+    const parsed = { nameProperties: [], json: false, strict: false };
+    for (let index = 0; index < argv.length; index += 1) {
+        const flag = argv[index];
+        const next = () => {
+            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 '--name-property':
+                parsed.nameProperties.push(next());
+                break;
+            case '--json':
+                parsed.json = true;
+                break;
+            case '--strict':
+                parsed.strict = true;
+                break;
+            default:
+                console.error(`Unknown option: ${flag}`);
+                process.exit(1);
+        }
+    }
+    return parsed;
+}
+async function main(argv) {
+    const args = parseArgs(argv);
+    if (!args.servicesModule) {
+        console.error('lint-grammar-driver: --services <module> is required.');
+        process.exit(1);
+    }
+    const { createServices, coreNode } = await loadHeadlessContext(args.servicesModule);
+    const result = coreNode.lintGrammar({
+        createServices,
+        nameProperties: args.nameProperties.length ? args.nameProperties : undefined
+    });
+    console.log(formatLintReport(result, { json: args.json }));
+    return lintExitCode(result, args.strict);
+}
+main(process.argv.slice(2))
+    .then(code => process.exit(code))
+    .catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});
+//# sourceMappingURL=lint-grammar-driver.js.map

package/lib/commands/lint-grammar-driver.js.map

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

package/lib/commands/lint-grammar-report.d.ts

@@ -0,0 +1,24 @@
+/********************************************************************************
+ * 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 { GrammarLintResult } from '@hydranium/core/node';
+/**
+ * The exit code for a lint run: non-zero blocks the CI gate. Errors always fail;
+ * `strict` additionally fails on warnings.
+ */
+export declare function lintExitCode(result: GrammarLintResult, strict?: boolean): number;
+/**
+ * Render a grammar-convention lint result for the terminal. `json` emits the raw
+ * {@link GrammarLintResult} (the machine-readable CI contract); the default is a
+ * human report — one `severity  [rule]  message` line per finding — closing with
+ * the {@link summaryLine} tally.
+ */
+export declare function formatLintReport(result: GrammarLintResult, options?: {
+    json?: boolean;
+}): string;
+//# sourceMappingURL=lint-grammar-report.d.ts.map

package/lib/commands/lint-grammar-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint-grammar-report.d.ts","sourceRoot":"","sources":["../../src/commands/lint-grammar-report.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAO9D;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,UAAQ,GAAG,MAAM,CAQ9E;AAwBD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAapG"}

package/lib/commands/lint-grammar-report.js

@@ -0,0 +1,65 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/** `s` when `count !== 1`, else empty. */
+function plural(count) {
+    return count === 1 ? '' : 's';
+}
+/**
+ * The exit code for a lint run: non-zero blocks the CI gate. Errors always fail;
+ * `strict` additionally fails on warnings.
+ */
+export function lintExitCode(result, strict = false) {
+    if (result.counts.error > 0) {
+        return 1;
+    }
+    if (strict && result.counts.warning > 0) {
+        return 1;
+    }
+    return 0;
+}
+/** One-line severity tally, or the clean-grammar message. */
+function summaryLine(result) {
+    const { error, warning } = result.counts;
+    if (error + warning === 0) {
+        // "target type", not "target": the tally counts distinct TYPES reachable
+        // as a cross-reference target, not cross-reference properties. Several
+        // references can share one target type, so the bare word reads as though
+        // the lint had missed the rest.
+        return `No grammar-convention problems found (${result.checkedReferenceTargets} reference target type${plural(result.checkedReferenceTargets)} checked).`;
+    }
+    const parts = [];
+    if (error) {
+        parts.push(`${error} error${plural(error)}`);
+    }
+    if (warning) {
+        parts.push(`${warning} warning${plural(warning)}`);
+    }
+    return `${parts.join(', ')}.`;
+}
+/**
+ * Render a grammar-convention lint result for the terminal. `json` emits the raw
+ * {@link GrammarLintResult} (the machine-readable CI contract); the default is a
+ * human report — one `severity  [rule]  message` line per finding — closing with
+ * the {@link summaryLine} tally.
+ */
+export function formatLintReport(result, options = {}) {
+    if (options.json) {
+        return JSON.stringify(result, undefined, 2);
+    }
+    const lines = [];
+    for (const finding of result.findings) {
+        lines.push(`  ${finding.severity.padEnd(7)} [${finding.rule}] ${finding.message}`);
+    }
+    if (result.findings.length > 0) {
+        lines.push('');
+    }
+    lines.push(summaryLine(result));
+    return lines.join('\n');
+}
+//# sourceMappingURL=lint-grammar-report.js.map

package/lib/commands/lint-grammar-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint-grammar-report.js","sourceRoot":"","sources":["../../src/commands/lint-grammar-report.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAMlF,0CAA0C;AAC1C,SAAS,MAAM,CAAC,KAAa;IAC1B,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAyB,EAAE,MAAM,GAAG,KAAK;IACnE,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,CAAC;IACZ,CAAC;IACD,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QACvC,OAAO,CAAC,CAAC;IACZ,CAAC;IACD,OAAO,CAAC,CAAC;AACZ,CAAC;AAED,6DAA6D;AAC7D,SAAS,WAAW,CAAC,MAAyB;IAC3C,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC;IACzC,IAAI,KAAK,GAAG,OAAO,KAAK,CAAC,EAAE,CAAC;QACzB,yEAAyE;QACzE,uEAAuE;QACvE,yEAAyE;QACzE,gCAAgC;QAChC,OAAO,yCAAyC,MAAM,CAAC,uBAAuB,yBAAyB,MAAM,CAC1G,MAAM,CAAC,uBAAuB,CAChC,YAAY,CAAC;IACjB,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,KAAK,EAAE,CAAC;QACT,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,OAAO,EAAE,CAAC;QACX,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,WAAW,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AACjC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAyB,EAAE,UAA8B,EAAE;IACzF,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClB,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAChC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC"}

package/lib/commands/lint-grammar.d.ts

@@ -0,0 +1,33 @@
+/********************************************************************************
+ * 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 DriverSpawnOptions } from './headless-harness.js';
+/** Options for the {@link runLintGrammar} subcommand. */
+export interface LintGrammarCommandOptions extends DriverSpawnOptions {
+    /** ESM module exporting a zero-arg `createServices(): { shared }` thunk. */
+    readonly servicesModule: string;
+    /** Property names that satisfy the nameability convention. Empty → the framework default `name`. */
+    readonly nameProperties?: readonly string[];
+    /** Emit the raw JSON result instead of the human report. */
+    readonly json?: boolean;
+    /** Also fail (non-zero exit) on warnings, not only errors. */
+    readonly strict?: boolean;
+}
+/** Build the argv the driver child parses. Pure → unit-testable. */
+export declare function buildLintGrammarDriverArgs(options: LintGrammarCommandOptions): string[];
+/**
+ * Headless grammar-convention lint — a CI gate that checks a head's grammar against
+ * the framework's expectations (nameable cross-reference targets, an entry rule) and
+ * exits non-zero when a violation is found (`--strict` also fails on warnings).
+ * Read-only: no workspace is built (the reflection is static once the head registers
+ * its language), so this subcommand takes only `--services` and the name-property
+ * overrides. The work runs in a spawned child that dynamic-imports the head's
+ * `createServices` module, keeping the binary language-agnostic.
+ */
+export declare function runLintGrammar(options: LintGrammarCommandOptions): Promise<void>;
+//# sourceMappingURL=lint-grammar.d.ts.map