langium-zod 0.5.3 → 0.6.0

package/README.md

@@ -64,3 +64,26 @@ Generated output uses Zod 4 and exports named schemas like `<TypeName>Schema`.
 - Langium 4.x
 - Zod 4.x
 
+## Domain target (experimental)
+
+Besides Zod schemas, langium-zod can emit a **domain surface** — quirk-free read
+interfaces, a `toDomain(node)` read projection, and field-precise write accessors:
+
+    langium-zod generate --domain --domain-out src/generated/domain.ts
+
+Mechanical rules are generic (a single cross-reference flattens to a `$refText`
+string). Project-specific renames and read-only merges are supplied via
+`domainOverlays` in `langium-zod.config.js`:
+
+    export default {
+      domainOverlays: {
+        types: {
+          Choice: { renames: { attributes: 'options' } },
+          RosettaFunction: { merges: [{ from: ['conditions', 'postConditions'], to: 'conditions' }] }
+        }
+      }
+    };
+
+Merges are read-only on the merged name; write accessors target the source
+fields (`addConditions`, `addPostConditions`) — there is no merged setter.
+

package/dist/api.d.ts

@@ -1,4 +1,127 @@
 import type { ZodGeneratorConfig } from './config.js';
 export type PublicZodGeneratorConfig = ZodGeneratorConfig;
+/**
+ * Main entry point for programmatic Zod schema generation from a Langium grammar.
+ *
+ * Accepts a {@link ZodGeneratorConfig} that specifies either a parsed Langium
+ * `Grammar` object or a pre-built {@link AstTypesLike} descriptor, then runs the
+ * full extraction → projection → code-generation pipeline and returns the
+ * generated TypeScript source as a string. When `config.outputPath` is set the
+ * result is also written to disk. Conformance artifacts are generated when
+ * `config.conformance` is provided.
+ *
+ * @remarks
+ * This is the primary API for most consumers. It combines {@link extractTypeDescriptors},
+ * {@link detectRecursiveTypes}, and {@link generateZodCode} into a single call. Use the
+ * lower-level functions directly only when you need fine-grained control over individual
+ * pipeline stages (e.g. to inspect descriptors before code generation, or to cache
+ * extraction results across multiple code-generation runs).
+ *
+ * The function is synchronous and writes to disk only when `config.outputPath` is set.
+ * It does not shell out or spawn child processes.
+ *
+ * **Config option decision tree:**
+ * - Does your grammar have recursive rules (e.g. `Expression: ... | left=Expression`)? →
+ *   no action needed; cycle detection is automatic. If you run a custom pipeline, pass the
+ *   *full* (unprojected) descriptor set to `detectRecursiveTypes` first.
+ * - Does your grammar have cross-references (`ref:` properties)? →
+ *   if you need runtime ref-text validation in a live language server, enable
+ *   `crossRefValidation: true` and use the emitted `create*Schema()` factories.
+ *   Otherwise leave it off — unconstrained `ReferenceSchema` is lighter and sufficient for
+ *   batch/offline validation.
+ * - Do you want to strip Langium internal bookkeeping fields (`$container`, `$document`,
+ *   `$cstNode`, etc.)? → set `stripInternals: true`. These fields are never meaningful
+ *   in a validation context and inflate the generated schema.
+ * - Do you need form labels and descriptions driven by the grammar? → enable `formMetadata: true`.
+ *   Only properties whose grammar rule has a JSDoc/grammar comment get a `description`; every
+ *   property gets a humanized `title` regardless.
+ * - Are you using Zod 4's `z.looseObject`? → the default `objectStyle: 'loose'` emits
+ *   `z.looseObject(...)`. Switch to `objectStyle: 'strict'` + `.strict()` on the schema only
+ *   when you need hard rejection of unknown properties (e.g. strict API request validation).
+ *
+ * @param config - Generator configuration including the grammar or AST types,
+ *   optional output path, include/exclude filters, projection, and feature flags.
+ * @returns The generated TypeScript source containing all Zod schema exports.
+ * @throws {@link ZodGeneratorError} when required configuration is missing, when
+ *   `conformance` is enabled without `outputPath`, or when a grammar property type
+ *   cannot be mapped to a Zod schema.
+ *
+ * @example
+ * ```ts
+ * import { createLangiumGrammarServices } from 'langium/grammar';
+ * import { NodeFileSystem } from 'langium/node';
+ * import { generateZodSchemas } from 'langium-zod';
+ *
+ * const { grammar } = createLangiumGrammarServices(NodeFileSystem);
+ * // assume `parsedGrammar` is a Grammar node obtained from Langium
+ * const source = generateZodSchemas({
+ *   grammar: parsedGrammar,
+ *   outputPath: 'src/generated/zod-schemas.ts',
+ *   stripInternals: true,
+ * });
+ * console.log(source); // TypeScript source with Zod schema exports
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Using a pre-built AstTypesLike descriptor (skips grammar parsing)
+ * import { generateZodSchemas } from 'langium-zod';
+ * import { collectAst } from 'langium/grammar';
+ *
+ * const astTypes = collectAst(myGrammar);
+ * const source = generateZodSchemas({ astTypes });
+ * ```
+ *
+ * @useWhen
+ * - You have a parsed Langium `Grammar` object and want Zod schemas as a TypeScript string.
+ * - You are integrating langium-zod into a build pipeline (Vite plugin, codegen script, etc.).
+ * - You need conformance artifacts (type-guard files) alongside the schema output.
+ * - You want to write generated schemas to disk in a single call.
+ *
+ * @avoidWhen
+ * - You only need to inspect the intermediate type descriptors without generating code —
+ *   use {@link extractTypeDescriptors} directly instead.
+ * - You are running inside the Langium DI container — prefer {@link DefaultZodSchemaGenerator}
+ *   which injects services automatically.
+ * - You want to generate schemas for only a subset of types at runtime — pass `include`/`exclude`
+ *   in the config rather than post-processing the output.
+ *
+ * @never
+ * - NEVER omit both `grammar` and `astTypes` — the function throws {@link ZodGeneratorError}
+ *   immediately. BECAUSE there is no default grammar source and no way to recover silently.
+ *   FIX: provide at least `{ grammar: parsedGrammar }` or `{ astTypes: collectAst(grammar) }`.
+ * - NEVER enable `conformance` without setting `outputPath` — the function will throw before
+ *   writing any output. BECAUSE the conformance module needs to derive a sibling output path
+ *   from the schema file's directory. FIX: always set `outputPath` when `conformance` is truthy.
+ * - NEVER pass a `Grammar[]` array when grammars share type names across files without
+ *   verifying that Langium's `collectAst()` merges them correctly. BECAUSE duplicate type names
+ *   will silently overwrite each other in the type map, producing truncated schemas.
+ *   FIX: run `collectAst` separately and inspect the merged map before generation.
+ * - NEVER call with `crossRefValidation: true` on grammars with no cross-reference properties —
+ *   it emits dead `create*Schema` factory functions that add noise without benefit.
+ *   FIX: only enable `crossRefValidation` when your grammar has at least one `ref:` property.
+ * - NEVER remove the `// @ts-nocheck` comment from generated output files. BECAUSE the
+ *   getter-based recursive property syntax (emitted for self-referential types) is not always
+ *   accepted by TypeScript's strict object-literal type checker — removing the comment causes
+ *   immediate TS build failures in grammars with recursive rules. FIX: treat generated files as
+ *   opaque artifacts; place any hand-written extensions in a separate file that imports the schema.
+ * - NEVER commit generated schemas as the sole copy of your schema logic. BECAUSE any grammar
+ *   edit (new rule, renamed property, changed cardinality) produces stale schemas that pass
+ *   TypeScript but fail at Zod validation runtime. FIX: wire `langium-zod generate` as a
+ *   pre-build or CI step so schema freshness is enforced automatically.
+ *
+ * @category Generation
+ * @see {@link extractTypeDescriptors}
+ * @see {@link detectRecursiveTypes}
+ * @see {@link generateZodCode}
+ * @see {@link ZodGeneratorConfig}
+ */
 export declare function generateZodSchemas(config: ZodGeneratorConfig): string;
+/**
+ * Programmatic entry point for the domain target. Runs the same extract pipeline
+ * as {@link generateZodSchemas}, then emits the domain surface (read interfaces +
+ * `toDomain` projection + field-precise write accessors). Writes to
+ * `config.domainOutputPath` when set.
+ */
+export declare function generateDomainSchemas(config: ZodGeneratorConfig): string;
 //# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAStD,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,CAAC;AAS1D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAgGrE"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAUtD,MAAM,MAAM,wBAAwB,GAAG,kBAAkB,CAAC;AAS1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmHG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAkGrE;AAcD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CA4BxE"}

package/dist/api.js

@@ -6,6 +6,7 @@ import { ZodGeneratorError } from './errors.js';
 import { extractTypeDescriptors } from './extractor.js';
 import { generateZodCode } from './generator.js';
 import { applyProjectionToDescriptors, resolveEffectiveStripFields } from './projection.js';
+import { generateDomainCode } from './emitters/domain.js';
 import { detectRecursiveTypes } from './recursion-detector.js';
 function resolveAstTypes(astTypes) {
     return {
@@ -13,6 +14,122 @@ function resolveAstTypes(astTypes) {
         unions: astTypes.unions ?? []
     };
 }
+/**
+ * Main entry point for programmatic Zod schema generation from a Langium grammar.
+ *
+ * Accepts a {@link ZodGeneratorConfig} that specifies either a parsed Langium
+ * `Grammar` object or a pre-built {@link AstTypesLike} descriptor, then runs the
+ * full extraction → projection → code-generation pipeline and returns the
+ * generated TypeScript source as a string. When `config.outputPath` is set the
+ * result is also written to disk. Conformance artifacts are generated when
+ * `config.conformance` is provided.
+ *
+ * @remarks
+ * This is the primary API for most consumers. It combines {@link extractTypeDescriptors},
+ * {@link detectRecursiveTypes}, and {@link generateZodCode} into a single call. Use the
+ * lower-level functions directly only when you need fine-grained control over individual
+ * pipeline stages (e.g. to inspect descriptors before code generation, or to cache
+ * extraction results across multiple code-generation runs).
+ *
+ * The function is synchronous and writes to disk only when `config.outputPath` is set.
+ * It does not shell out or spawn child processes.
+ *
+ * **Config option decision tree:**
+ * - Does your grammar have recursive rules (e.g. `Expression: ... | left=Expression`)? →
+ *   no action needed; cycle detection is automatic. If you run a custom pipeline, pass the
+ *   *full* (unprojected) descriptor set to `detectRecursiveTypes` first.
+ * - Does your grammar have cross-references (`ref:` properties)? →
+ *   if you need runtime ref-text validation in a live language server, enable
+ *   `crossRefValidation: true` and use the emitted `create*Schema()` factories.
+ *   Otherwise leave it off — unconstrained `ReferenceSchema` is lighter and sufficient for
+ *   batch/offline validation.
+ * - Do you want to strip Langium internal bookkeeping fields (`$container`, `$document`,
+ *   `$cstNode`, etc.)? → set `stripInternals: true`. These fields are never meaningful
+ *   in a validation context and inflate the generated schema.
+ * - Do you need form labels and descriptions driven by the grammar? → enable `formMetadata: true`.
+ *   Only properties whose grammar rule has a JSDoc/grammar comment get a `description`; every
+ *   property gets a humanized `title` regardless.
+ * - Are you using Zod 4's `z.looseObject`? → the default `objectStyle: 'loose'` emits
+ *   `z.looseObject(...)`. Switch to `objectStyle: 'strict'` + `.strict()` on the schema only
+ *   when you need hard rejection of unknown properties (e.g. strict API request validation).
+ *
+ * @param config - Generator configuration including the grammar or AST types,
+ *   optional output path, include/exclude filters, projection, and feature flags.
+ * @returns The generated TypeScript source containing all Zod schema exports.
+ * @throws {@link ZodGeneratorError} when required configuration is missing, when
+ *   `conformance` is enabled without `outputPath`, or when a grammar property type
+ *   cannot be mapped to a Zod schema.
+ *
+ * @example
+ * ```ts
+ * import { createLangiumGrammarServices } from 'langium/grammar';
+ * import { NodeFileSystem } from 'langium/node';
+ * import { generateZodSchemas } from 'langium-zod';
+ *
+ * const { grammar } = createLangiumGrammarServices(NodeFileSystem);
+ * // assume `parsedGrammar` is a Grammar node obtained from Langium
+ * const source = generateZodSchemas({
+ *   grammar: parsedGrammar,
+ *   outputPath: 'src/generated/zod-schemas.ts',
+ *   stripInternals: true,
+ * });
+ * console.log(source); // TypeScript source with Zod schema exports
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Using a pre-built AstTypesLike descriptor (skips grammar parsing)
+ * import { generateZodSchemas } from 'langium-zod';
+ * import { collectAst } from 'langium/grammar';
+ *
+ * const astTypes = collectAst(myGrammar);
+ * const source = generateZodSchemas({ astTypes });
+ * ```
+ *
+ * @useWhen
+ * - You have a parsed Langium `Grammar` object and want Zod schemas as a TypeScript string.
+ * - You are integrating langium-zod into a build pipeline (Vite plugin, codegen script, etc.).
+ * - You need conformance artifacts (type-guard files) alongside the schema output.
+ * - You want to write generated schemas to disk in a single call.
+ *
+ * @avoidWhen
+ * - You only need to inspect the intermediate type descriptors without generating code —
+ *   use {@link extractTypeDescriptors} directly instead.
+ * - You are running inside the Langium DI container — prefer {@link DefaultZodSchemaGenerator}
+ *   which injects services automatically.
+ * - You want to generate schemas for only a subset of types at runtime — pass `include`/`exclude`
+ *   in the config rather than post-processing the output.
+ *
+ * @never
+ * - NEVER omit both `grammar` and `astTypes` — the function throws {@link ZodGeneratorError}
+ *   immediately. BECAUSE there is no default grammar source and no way to recover silently.
+ *   FIX: provide at least `{ grammar: parsedGrammar }` or `{ astTypes: collectAst(grammar) }`.
+ * - NEVER enable `conformance` without setting `outputPath` — the function will throw before
+ *   writing any output. BECAUSE the conformance module needs to derive a sibling output path
+ *   from the schema file's directory. FIX: always set `outputPath` when `conformance` is truthy.
+ * - NEVER pass a `Grammar[]` array when grammars share type names across files without
+ *   verifying that Langium's `collectAst()` merges them correctly. BECAUSE duplicate type names
+ *   will silently overwrite each other in the type map, producing truncated schemas.
+ *   FIX: run `collectAst` separately and inspect the merged map before generation.
+ * - NEVER call with `crossRefValidation: true` on grammars with no cross-reference properties —
+ *   it emits dead `create*Schema` factory functions that add noise without benefit.
+ *   FIX: only enable `crossRefValidation` when your grammar has at least one `ref:` property.
+ * - NEVER remove the `// @ts-nocheck` comment from generated output files. BECAUSE the
+ *   getter-based recursive property syntax (emitted for self-referential types) is not always
+ *   accepted by TypeScript's strict object-literal type checker — removing the comment causes
+ *   immediate TS build failures in grammars with recursive rules. FIX: treat generated files as
+ *   opaque artifacts; place any hand-written extensions in a separate file that imports the schema.
+ * - NEVER commit generated schemas as the sole copy of your schema logic. BECAUSE any grammar
+ *   edit (new rule, renamed property, changed cardinality) produces stale schemas that pass
+ *   TypeScript but fail at Zod validation runtime. FIX: wire `langium-zod generate` as a
+ *   pre-build or CI step so schema freshness is enforced automatically.
+ *
+ * @category Generation
+ * @see {@link extractTypeDescriptors}
+ * @see {@link detectRecursiveTypes}
+ * @see {@link generateZodCode}
+ * @see {@link ZodGeneratorConfig}
+ */
 export function generateZodSchemas(config) {
     let rawAstTypes;
     if (config.astTypes) {
@@ -104,4 +221,38 @@ function buildDescriptorPipeline(astTypes, config) {
     });
     return descriptors;
 }
+/**
+ * Programmatic entry point for the domain target. Runs the same extract pipeline
+ * as {@link generateZodSchemas}, then emits the domain surface (read interfaces +
+ * `toDomain` projection + field-precise write accessors). Writes to
+ * `config.domainOutputPath` when set.
+ */
+export function generateDomainSchemas(config) {
+    let rawAstTypes;
+    if (config.astTypes) {
+        rawAstTypes = config.astTypes;
+    }
+    else if (config.grammar) {
+        rawAstTypes = collectAst(config.grammar);
+    }
+    else {
+        throw new ZodGeneratorError('Missing grammar or astTypes in ZodGeneratorConfig', {
+            suggestion: "Provide astTypes from Langium's collectAst() or pass a grammar object"
+        });
+    }
+    const astTypes = resolveAstTypes(rawAstTypes);
+    const descriptors = buildDescriptorPipeline(astTypes, config);
+    // Note: regexOverrides (regex-enum upgrades) are intentionally NOT applied here —
+    // the domain surface uses type references + primitives, never regex-enum shapes.
+    const source = generateDomainCode(descriptors, {
+        projection: config.projection,
+        stripInternals: config.stripInternals,
+        overlays: config.domainOverlays
+    });
+    if (config.domainOutputPath) {
+        mkdirSync(dirname(config.domainOutputPath), { recursive: true });
+        writeFileSync(config.domainOutputPath, source, 'utf8');
+    }
+    return source;
+}
 //# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,yBAAyB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,4BAA4B,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAK/D,SAAS,eAAe,CAAC,QAAsB;IAC9C,OAAO;QACN,UAAU,EAAE,QAAQ,CAAC,UAAU,IAAI,EAAE;QACrC,MAAM,EAAE,QAAQ,CAAC,MAAM,IAAI,EAAE;KAC7B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAA0B;IAC5D,IAAI,WAAyB,CAAC;IAC9B,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC/B,CAAC;SAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QAC3B,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,OAAO,CAA4B,CAAC;IACrE,CAAC;SAAM,CAAC;QACP,MAAM,IAAI,iBAAiB,CAAC,mDAAmD,EAAE;YAChF,UAAU,EAAE,uEAAuE;SACnF,CAAC,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;IAC9C,MAAM,cAAc,GAAG,uBAAuB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAEjE,gFAAgF;IAChF,4EAA4E;IAC5E,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,IAAI,EAAE,CAAC;IAC9C,MAAM,WAAW,GAAwB,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACjE,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,QAAQ,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,iBAAiB,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC,EAAE,CAAC;YAC3E,OAAO;gBACN,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI,EAAE,YAAY;gBAClB,KAAK,EAAE,QAAQ;gBACf,QAAQ,EAAE,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAE,CAA4B,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE;aAC9C,CAAC;QACpC,CAAC;QACD,OAAO,CAAC,CAAC;IACV,CAAC,CAAC,CAAC;IAEH,MAAM,cAAc,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IACzD,MAAM,kBAAkB,GAAG,4BAA4B,CAAC,WAAW,EAAE;QACpE,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,cAAc,EAAE,MAAM,CAAC,cAAc;KACrC,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,eAAe,CAAC,WAAW,EAAE,cAAc,EAAE;QAC3D,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;QAC7C,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,WAAW,EAAE,MAAM,CAAC,WAAW;KAC/B,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACvB,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,aAAa,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YACxB,MAAM,IAAI,iBAAiB,CAAC,4CAA4C,EAAE;gBACzE,UAAU,EAAE,2DAA2D;aACvE,CAAC,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,YAAY,EAAE,CAAC;YACtC,MAAM,IAAI,iBAAiB,CAAC,8CAA8C,EAAE;gBAC3E,UAAU,EAAE,yEAAyE;aACrF,CAAC,CAAC;QACJ,CAAC;QAED,MAAM,eAAe,GAAG,kBAAkB;aACxC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,KAAK,QAAQ,CAAC;aACpD,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAEvC,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,CAAC,IAAI,CAAC,oFAAoF,CAAC,CAAC;YACnG,OAAO,MAAM,CAAC;QACf,CAAC;QAED,MAAM,qBAAqB,GAAG,0BAA0B,CACvD,MAAM,CAAC,UAAU,EACjB,MAAM,CAAC,WAAW,CAAC,UAAU,CAC7B,CAAC;QACF,MAAM,WAAW,GAAG,yBAAyB,CAAC;YAC7C,gBAAgB,EAAE,MAAM,CAAC,UAAU;YACnC,qBAAqB;YACrB,YAAY,EAAE,MAAM,CAAC,WAAW,CAAC,YAAY;YAC7C,eAAe;YACf,WAAW,EAAE,2BAA2B,CAAC;gBACxC,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,cAAc,EAAE,MAAM,CAAC,cAAc;aACrC,CAAC;YACF,UAAU,EAAE,MAAM,CAAC,UAAU;SAC7B,CAAC,CAAC;QAEH,KAAK,MAAM,WAAW,IAAI,WAAW,CAAC,eAAe,EAAE,CAAC;YACvD,OAAO,CAAC,IAAI,CAAC,oDAAoD,WAAW,aAAa,CAAC,CAAC;QAC5F,CAAC;QAED,SAAS,CAAC,OAAO,CAAC,qBAAqB,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/D,aAAa,CAAC,qBAAqB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC;AAED,SAAS,uBAAuB,CAAC,QAAsB,EAAE,MAA0B;IAClF,MAAM,WAAW,GAAG,sBAAsB,CAAC,QAAQ,EAAE;QACpD,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,MAAM,CAAC,OAAO;KACvB,CAAC,CAAC;IAEH,OAAO,WAAW,CAAC;AACpB,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -10,14 +10,90 @@ export interface LangiumZodConfig extends Omit<ZodGeneratorConfig, 'grammar' | '
     /** Explicit output path. Overrides derived path from langium-config.json `out` field. */
     outputPath?: string;
 }
+/**
+ * Merges CLI `--include` / `--exclude` flag values with the base filter from a
+ * user config file, producing a deduplicated, conflict-free filter pair.
+ *
+ * CLI arguments take precedence over the config file values. Any name that appears
+ * in both `include` and `exclude` is removed from `include` so that the exclude
+ * list is authoritative.
+ *
+ * @param base - Baseline include/exclude arrays from the user's
+ *   `langium-zod.config.js`, used when the corresponding CLI flag is absent.
+ * @param includeArg - Raw comma-separated string from `--include`, or `undefined`
+ *   when the flag was not passed.
+ * @param excludeArg - Raw comma-separated string from `--exclude`, or `undefined`
+ *   when the flag was not passed.
+ * @returns A resolved `{ include, exclude }` pair ready to merge into the
+ *   generator config.
+ */
 export declare function resolveFilterOverrides(base: Pick<LangiumZodConfig, 'include' | 'exclude'>, includeArg?: string, excludeArg?: string): Pick<LangiumZodConfig, 'include' | 'exclude'>;
+/**
+ * Returns the subset of `requested` names that are not present in
+ * `availableTypeNames`.
+ *
+ * Used to surface warnings when the user's `--include` or `--exclude` list
+ * references type names that do not exist in the parsed grammar, helping catch
+ * typos before generation runs.
+ *
+ * @param requested - The type names requested by the user (include or exclude
+ *   list). Returns an empty array immediately when this is `undefined` or empty.
+ * @param availableTypeNames - All type names present in the parsed Langium grammar
+ *   (both interface types and union/datatype rule types).
+ * @returns An array of names from `requested` that are absent from
+ *   `availableTypeNames`.
+ */
 export declare function getUnknownFilterNames(requested: string[] | undefined, availableTypeNames: string[]): string[];
+/**
+ * Options accepted by the programmatic {@link generate} function.
+ *
+ * Allows the core generation logic to be invoked directly from other tools or
+ * scripts without going through the CLI argument parser.
+ */
 export interface GenerateOptions {
     /** Absolute path to langium-config.json */
     langiumConfigPath: string;
     /** Merged generator config (from user's langium-zod.config.js + CLI flags) */
     config?: LangiumZodConfig;
 }
+/**
+ * Programmatic entry point for the `langium-zod generate` command.
+ *
+ * Loads `langium-config.json` from `opts.langiumConfigPath`, resolves the grammar
+ * file path, parses the grammar with Langium services (including eager import
+ * loading so cross-file references link correctly), then calls
+ * {@link generateZodSchemas} with the merged configuration. Prints a success
+ * message to stdout when generation completes.
+ *
+ * @param opts - {@link GenerateOptions} specifying the langium config path and
+ *   optional pre-merged generator config.
+ * @throws `Error` when the langium-config.json or grammar file cannot be found, or
+ *   when the config defines no languages.
+ *
+ * @example
+ * ```ts
+ * import { generate } from 'langium-zod';
+ * import { resolve } from 'node:path';
+ *
+ * await generate({
+ *   langiumConfigPath: resolve(process.cwd(), 'langium-config.json'),
+ *   config: {
+ *     outputPath: 'src/generated/zod-schemas.ts',
+ *     stripInternals: true,
+ *   },
+ * });
+ * // Prints: ✓ Generated Zod schemas → src/generated/zod-schemas.ts
+ * ```
+ */
 export declare function generate(opts: GenerateOptions): Promise<void>;
+/**
+ * CLI entry point executed when the `langium-zod` binary is invoked directly.
+ *
+ * Parses `process.argv`, resolves `langium-config.json`, loads an optional
+ * `langium-zod.config.js` from the same directory, merges all CLI flag overrides
+ * (--out, --include, --exclude, --projection, --strip-internals, --conformance,
+ * --cross-ref-validation), then delegates to {@link generate}. Exits the process
+ * with code 1 on error.
+ */
 export declare function main(): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAgBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAQtD,kEAAkE;AAClE,MAAM,WAAW,gBAChB,SAAQ,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;IACrE;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAuCD,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,SAAS,CAAC,EACnD,UAAU,CAAC,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GACjB,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,SAAS,CAAC,CAc/C;AAoBD,wBAAgB,qBAAqB,CACpC,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,EAC/B,kBAAkB,EAAE,MAAM,EAAE,GAC1B,MAAM,EAAE,CAOV;AAyED,MAAM,WAAW,eAAe;IAC/B,2CAA2C;IAC3C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA0FnE;AAMD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAmG1C"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAgBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAQtD,kEAAkE;AAClE,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAC5C,kBAAkB,EAClB,SAAS,GAAG,UAAU,GAAG,UAAU,CACpC;IACC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAuCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,SAAS,CAAC,EACnD,UAAU,CAAC,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,SAAS,CAAC,CAc/C;AAkBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,EAC/B,kBAAkB,EAAE,MAAM,EAAE,GAC3B,MAAM,EAAE,CAOV;AA2ED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA2GnE;AAMD;;;;;;;;GAQG;AACH,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA6G1C"}

package/dist/cli.js

@@ -12,7 +12,7 @@ import { pathToFileURL } from 'node:url';
 import { URI } from 'langium';
 import { createLangiumGrammarServices, resolveImportUri } from 'langium/grammar';
 import { NodeFileSystem } from 'langium/node';
-import { generateZodSchemas } from './api.js';
+import { generateZodSchemas, generateDomainSchemas } from './api.js';
 import { resolveAstTypesPath } from './conformance.js';
 import { loadProjectionConfig } from './projection.js';
 function parseCsvList(value) {
@@ -39,6 +39,23 @@ function getArgValue(args, flag) {
     }
     return value;
 }
+/**
+ * Merges CLI `--include` / `--exclude` flag values with the base filter from a
+ * user config file, producing a deduplicated, conflict-free filter pair.
+ *
+ * CLI arguments take precedence over the config file values. Any name that appears
+ * in both `include` and `exclude` is removed from `include` so that the exclude
+ * list is authoritative.
+ *
+ * @param base - Baseline include/exclude arrays from the user's
+ *   `langium-zod.config.js`, used when the corresponding CLI flag is absent.
+ * @param includeArg - Raw comma-separated string from `--include`, or `undefined`
+ *   when the flag was not passed.
+ * @param excludeArg - Raw comma-separated string from `--exclude`, or `undefined`
+ *   when the flag was not passed.
+ * @returns A resolved `{ include, exclude }` pair ready to merge into the
+ *   generator config.
+ */
 export function resolveFilterOverrides(base, includeArg, excludeArg) {
     const includeFromCli = includeArg === undefined ? undefined : parseCsvList(includeArg);
     const excludeFromCli = excludeArg === undefined ? undefined : parseCsvList(excludeArg);
@@ -56,11 +73,24 @@ function warnUnknownFilterNames(filterName, requested, availableTypeNames) {
     if (unknown.length === 0) {
         return;
     }
-    const availableList = availableTypeNames.length > 0
-        ? availableTypeNames.join(', ')
-        : '(none)';
+    const availableList = availableTypeNames.length > 0 ? availableTypeNames.join(', ') : '(none)';
     console.warn(`Warning: Unknown ${filterName} type name(s): ${unknown.join(', ')}. Available types: ${availableList}`);
 }
+/**
+ * Returns the subset of `requested` names that are not present in
+ * `availableTypeNames`.
+ *
+ * Used to surface warnings when the user's `--include` or `--exclude` list
+ * references type names that do not exist in the parsed grammar, helping catch
+ * typos before generation runs.
+ *
+ * @param requested - The type names requested by the user (include or exclude
+ *   list). Returns an empty array immediately when this is `undefined` or empty.
+ * @param availableTypeNames - All type names present in the parsed Langium grammar
+ *   (both interface types and union/datatype rule types).
+ * @returns An array of names from `requested` that are absent from
+ *   `availableTypeNames`.
+ */
 export function getUnknownFilterNames(requested, availableTypeNames) {
     if (!requested || requested.length === 0) {
         return [];
@@ -89,6 +119,8 @@ OPTIONS
 	--ast-types <path> Path to generated AST declarations (ast.ts)
 	--conformance-out <path> Output path for conformance artifact
 	--cross-ref-validation Emit runtime cross-reference schema factories
+	--domain          Also emit the domain surface (domain.ts)
+	--domain-out <path> Output path for the domain surface
   --help            Show this help message
 
 CONFIGURATION
@@ -128,6 +160,35 @@ async function eagerLoad(document, documents, visited = new Set()) {
         }
     }
 }
+/**
+ * Programmatic entry point for the `langium-zod generate` command.
+ *
+ * Loads `langium-config.json` from `opts.langiumConfigPath`, resolves the grammar
+ * file path, parses the grammar with Langium services (including eager import
+ * loading so cross-file references link correctly), then calls
+ * {@link generateZodSchemas} with the merged configuration. Prints a success
+ * message to stdout when generation completes.
+ *
+ * @param opts - {@link GenerateOptions} specifying the langium config path and
+ *   optional pre-merged generator config.
+ * @throws `Error` when the langium-config.json or grammar file cannot be found, or
+ *   when the config defines no languages.
+ *
+ * @example
+ * ```ts
+ * import { generate } from 'langium-zod';
+ * import { resolve } from 'node:path';
+ *
+ * await generate({
+ *   langiumConfigPath: resolve(process.cwd(), 'langium-config.json'),
+ *   config: {
+ *     outputPath: 'src/generated/zod-schemas.ts',
+ *     stripInternals: true,
+ *   },
+ * });
+ * // Prints: ✓ Generated Zod schemas → src/generated/zod-schemas.ts
+ * ```
+ */
 export async function generate(opts) {
     const { langiumConfigPath } = opts;
     const userConfig = opts.config ?? {};
@@ -177,7 +238,7 @@ export async function generate(opts) {
     await eagerLoad(entryDocument, langiumDocuments);
     // Build (parse + link) all loaded documents
     await documentBuilder.build(langiumDocuments.all.toArray(), {
-        validation: false,
+        validation: false
     });
     const grammar = entryDocument.parseResult.value;
     const availableTypeNames = [
@@ -189,17 +250,39 @@ export async function generate(opts) {
     warnUnknownFilterNames('include', userConfig.include, availableTypeNames);
     warnUnknownFilterNames('exclude', userConfig.exclude, availableTypeNames);
     // ── 4. Generate schemas ──────────────────────────────────────────────────
-    const { langiumConfig: _ignored, outputPath: _op, ...restConfig } = userConfig;
+    const { langiumConfig: _ignored, outputPath: _op, emitDomain: _emitDomain, domainOutputPath: _domainOutputPath, ...restConfig } = userConfig;
     generateZodSchemas({
         grammar,
         outputPath,
-        ...restConfig,
+        ...restConfig
     });
     console.log(`✓ Generated Zod schemas → ${outputPath}`);
+    if (userConfig.emitDomain) {
+        const domainOutputPath = userConfig.domainOutputPath ?? join(outDir, 'domain.ts');
+        generateDomainSchemas({
+            grammar,
+            domainOutputPath,
+            stripInternals: restConfig.stripInternals,
+            projection: restConfig.projection,
+            domainOverlays: restConfig.domainOverlays,
+            include: restConfig.include,
+            exclude: restConfig.exclude
+        });
+        console.log(`✓ Generated domain surface → ${domainOutputPath}`);
+    }
 }
 // ────────────────────────────────────────────────────────────────────────────
 // CLI entry point
 // ────────────────────────────────────────────────────────────────────────────
+/**
+ * CLI entry point executed when the `langium-zod` binary is invoked directly.
+ *
+ * Parses `process.argv`, resolves `langium-config.json`, loads an optional
+ * `langium-zod.config.js` from the same directory, merges all CLI flag overrides
+ * (--out, --include, --exclude, --projection, --strip-internals, --conformance,
+ * --cross-ref-validation), then delegates to {@link generate}. Exits the process
+ * with code 1 on error.
+ */
 export async function main() {
     const args = process.argv.slice(2);
     if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
@@ -225,16 +308,15 @@ export async function main() {
     const stripInternalsEnabled = args.includes('--strip-internals');
     const conformanceEnabled = args.includes('--conformance');
     const crossRefValidationEnabled = args.includes('--cross-ref-validation');
+    const domainEnabled = args.includes('--domain');
+    const domainOutFlagValue = getArgValue(args, '--domain-out');
     // ── Locate langium-config.json ───────────────────────────────────────────
     const configFileName = configFlagValue ?? 'langium-config.json';
     const langiumConfigPath = resolve(process.cwd(), configFileName);
     // ── Load optional langium-zod.config.js ──────────────────────────────────
     const configDir = dirname(langiumConfigPath);
     let userConfig = {};
-    for (const candidate of [
-        'langium-zod.config.js',
-        'langium-zod.config.mjs',
-    ]) {
+    for (const candidate of ['langium-zod.config.js', 'langium-zod.config.mjs']) {
         const candidatePath = join(configDir, candidate);
         if (existsSync(candidatePath)) {
             const mod = await import(pathToFileURL(candidatePath).href);
@@ -269,7 +351,9 @@ export async function main() {
             ...userConfig,
             conformance: {
                 astTypesPath: astTypesFlagValue ? resolve(process.cwd(), astTypesFlagValue) : undefined,
-                outputPath: conformanceOutFlagValue ? resolve(process.cwd(), conformanceOutFlagValue) : undefined
+                outputPath: conformanceOutFlagValue
+                    ? resolve(process.cwd(), conformanceOutFlagValue)
+                    : undefined
             }
         };
     }
@@ -279,6 +363,15 @@ export async function main() {
             crossRefValidation: true
         };
     }
+    if (domainEnabled) {
+        userConfig = {
+            ...userConfig,
+            emitDomain: true,
+            domainOutputPath: domainOutFlagValue
+                ? resolve(process.cwd(), domainOutFlagValue)
+                : userConfig.domainOutputPath
+        };
+    }
     try {
         await generate({ langiumConfigPath, config: userConfig });
     }