@typemf/generator 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,741 @@
+import { EPackage, EObject, EPackageImpl, EClassImpl, EOperation, EStructuralFeature, EClass, EAnnotation, EModelElement, EGenericType, EClassifier, EDataType, EEnum, ETypedElement } from '@typemf/core';
+import nunjucks from 'nunjucks';
+
+/**
+ * One config, one template set, one .ecore file, one outputDir - per the
+ * design discussion. Multi-language generation is achieved by running the
+ * CLI multiple times with different config files (e.g.
+ * typescript.typemf-generator.json, java.typemf-generator.json), not by
+ * one config handling multiple sets.
+ */
+interface GeneratorConfig {
+    ecoreFile: string;
+    outputDir: string;
+    templateSet: string;
+    options: Record<string, unknown>;
+}
+declare function loadConfig(configPath: string): Promise<GeneratorConfig>;
+
+/**
+ * Loads a real .ecore file into a typed EPackage. A .ecore file is an
+ * ordinary XMI instance document whose root happens to be an EPackage -
+ * read here by @typemf/xmi's own generic XmiSerializer, with no separate
+ * parsing logic of its own. Interpreting it correctly needs a registered
+ * meta-schema describing what "EClass"/"EAttribute"/etc mean (see
+ * ecore-meta-schema.ts) - this produces a DYNAMIC EObject graph, which
+ * gets converted (see ecore-dynamic-to-typed.ts) into the real, typed
+ * EPackage generate() actually needs as input. See NOTES.md for the full
+ * bootstrapping story and why this two-step shape is necessary - NOT
+ * because hand-written classes lack eSet() support (they support it fully
+ * for every real, modeled feature now, confirmed directly), but because
+ * bookkeeping fields (classifierID, featureID, containerClass,
+ * operationID) are deliberately excluded from eSet() by design, matching
+ * real EMF, and generate()'s own internals need those set too (via plain
+ * methods and id-assignment.ts, not eSet) - so a pure eSet-driven read
+ * could never be sufficient on its own regardless.
+ */
+declare function loadEcorePackage(ecoreFilePath: string): Promise<EPackage>;
+
+/**
+ * Converts a dynamic EObject graph - produced by parsing a real .ecore
+ * file against the meta-schema (see ecore-meta-schema.ts) - into a real,
+ * typed EPackage built from @typemf/core's own hand-written classes. This
+ * is the piece generate() actually needs as input; a dynamic graph, even
+ * though it fully supports eGet/eSet reflectively, doesn't have the plain
+ * convenience methods (setClassifierID(), recomputeAllLists(), ...)
+ * generate()'s own internals call directly - only the real typed classes
+ * do. This conversion writes via the real classes' own plain methods
+ * throughout, not because eSet() itself is unsupported there (it is, for
+ * every real, modeled feature - confirmed directly, this comment used to
+ * claim otherwise), but because bookkeeping (classifierID, featureID,
+ * containerClass, operationID) is deliberately unreachable via eSet by
+ * design, matching real EMF, and this conversion needs to set exactly
+ * that bookkeeping too - so writing everything through the SAME plain
+ * methods uniformly is simpler than splitting eSet-for-real-features from
+ * plain-calls-for-bookkeeping. It reads reflectively throughout (eGet, by
+ * name, off whatever meta-schema classifier each dynamic object happens
+ * to be an instance of).
+ *
+ * A classifier named "EObject" in the source graph (present only so
+ * "#//EObject" fragments resolve during parsing - see
+ * ecore-meta-schema.ts) is deliberately NOT converted into a real
+ * classifier here: any reference to it becomes `undefined` on the real
+ * side, matching the generator's own existing convention for a classifier
+ * with no explicit type (which already means "real @typemf/core EObject").
+ */
+declare function convertDynamicEcoreToTyped(dynamicPkg: EObject): EPackage;
+
+/**
+ * A hand-authored graph mirroring real Ecore.ecore's own full structure -
+ * every EClass, every EDataType, every declared feature (including
+ * derived/transient ones - these ARE present in the real file as ordinary
+ * <eStructuralFeatures> descriptions of what features a class HAS; what's
+ * never serialized is a VALUE for a derived feature on some downstream
+ * instance, which never comes up while parsing Ecore.ecore itself, since
+ * this file describes structure, not instances-of-that-structure).
+ *
+ * Two distinct roles, same shape:
+ *  1. Registered as the meta-schema the generic XmiSerializer needs to
+ *     interpret the real Ecore.ecore file at all (a .ecore file is an
+ *     ordinary XMI instance document whose root is an EPackage - reading
+ *     it needs SOME registered EPackage describing what "EClass"/
+ *     "EAttribute"/etc mean, or there's nothing to dispatch xsi:type
+ *     against).
+ *  2. The target shape the dynamic-graph -> typed-EPackage conversion step
+ *     produces after parsing - what actually gets fed to generate().
+ *
+ * EObject gets a real classifier shell here (needed so "#//EObject"
+ * fragments - e.g. EAnnotation.contents: EObject[] - resolve during
+ * parsing) but is deliberately excluded from what the GENERATOR treats as
+ * a real classifier to produce files for: it's the one name the generator
+ * special-cases exactly the way it already handles "no declared supertype"
+ * (see eclass.njk) - any reference to a classifier named "EObject"
+ * resolves to @typemf/core's own real EObject instead of generating a
+ * redundant, shadowing one.
+ *
+ * Does NOT model EString/EInt/EBoolean/etc as anything other than bare
+ * EDataType shells - no instanceClassName is set here beyond a name;
+ * `serializable`/`defaultValueLiteral` on real Ecore.ecore's own
+ * EDataType declarations are read during conversion where present, not
+ * hardcoded into this meta-schema (the meta-schema only needs to recognize
+ * these as valid attributes to parse, not carry their real values itself).
+ */
+declare function buildEcoreMetaSchema(): {
+    pkg: EPackageImpl;
+    eObject: EClassImpl;
+    eModelElement: EClassImpl;
+    eAnnotation: EClassImpl;
+    eNamedElement: EClassImpl;
+    eTypedElement: EClassImpl;
+    eClassifier: EClassImpl;
+    eStructuralFeature: EClassImpl;
+    eAttribute: EClassImpl;
+    eReference: EClassImpl;
+    eClass: EClassImpl;
+    ePackage: EClassImpl;
+    eDataType: EClassImpl;
+    eEnum: EClassImpl;
+    eEnumLiteral: EClassImpl;
+    eFactory: EClassImpl;
+    eOperation: EClassImpl;
+    eParameter: EClassImpl;
+    eStringToStringMapEntry: EClassImpl;
+    eGenericType: EClassImpl;
+    eTypeParameter: EClassImpl;
+};
+
+/** One output file from a generation run. `path` is always relative - see generate.ts. */
+interface GeneratedFile {
+    path: string;
+    content: string;
+}
+
+/**
+ * An isolated, self-contained template contribution - the generator's
+ * extension point. `baseFolder` contains a `main.njk` entry point and is
+ * ALSO the private include/import resolution root for that set: two
+ * different sets can each have their own e.g. `eclass.ts.njk` inside their
+ * own folder and never know the other exists. There is no cross-set
+ * override or search-path merging - isolation is structural, not a policy
+ * decision to make at render time.
+ *
+ * `main.njk` is invoked exactly once per generation run, over the whole
+ * EPackage - it is the template-set author's own job to iterate whatever
+ * they need to (classifiers, features, ...) and call {% file %} as many
+ * times as they want. The generator's own TypeScript orchestration does
+ * not impose a fixed per-class loop on every language.
+ */
+interface TemplateSet {
+    name: string;
+    baseFolder: string;
+    /**
+     * Optional hook to reject a package before any template renders, by
+     * returning a non-empty list of problems (rendered together into one
+     * thrown error) - e.g. this set's own generated member names
+     * colliding in a way it doesn't know how to resolve automatically.
+     * Runs once, after ID assignment, before configureEnvironment/main.njk.
+     */
+    validate?(pkg: EPackage): string[];
+    /**
+     * Optional hook to register set-specific filters/globals (e.g. a
+     * `tsType` filter mapping EDataType names to TypeScript type names) on
+     * this set's own Nunjucks Environment, before `main.njk` renders. Only
+     * this set's templates ever see these - a "java" set registering its
+     * own `javaType` filter neither conflicts with nor is visible to this
+     * one. Also receives the package being generated and the generation
+     * options, for a set that needs them outside the templates themselves.
+     */
+    configureEnvironment?(env: nunjucks.Environment, context: {
+        pkg: EPackage;
+        options: Record<string, unknown>;
+    }): void;
+    /**
+     * Optional hook to transform a file's fully-rendered body before it's
+     * recorded as output - called once per {% file %} block, right after
+     * its body string is complete, before anything else sees it. The one
+     * real use today: prepending a computed, deduplicated import header
+     * that a set's own `useType()`-style mechanism collected while the
+     * body rendered (see ImportCollector/typescript-template-set.ts) -
+     * this is the only point in the pipeline where the whole body is
+     * available as a string but nothing has been finalized yet, since
+     * nunjucks renders top-to-bottom in one linear pass and there's no way
+     * to "go back" and insert a header once the body below it has already
+     * streamed out.
+     */
+    postProcessFile?(path: string, content: string, options: Record<string, unknown>): string;
+}
+
+/**
+ * Renders `templateSet`'s main.njk once, over the whole `pkg`. Pure - no
+ * disk I/O beyond reading the template files themselves; writing the
+ * returned files anywhere is a separate, later step the caller owns. See
+ * the design discussion for why `outputDir` deliberately isn't a
+ * parameter here: every returned path is relative, so relative imports
+ * between generated files are computable without knowing an eventual
+ * absolute location.
+ */
+declare function generate(pkg: EPackage, templateSet: TemplateSet, options?: Record<string, unknown>): GeneratedFile[];
+
+/**
+ * Assigns classifierID/featureID freshly, in declaration order, mutating
+ * the EClass/EStructuralFeature objects directly - matches real EMF's own
+ * behaviour (these are recomputed-every-build implementation details of
+ * the generated code, not values meant to persist anywhere). See the
+ * design discussion: our wire formats (json/xmi) address by name, never by
+ * numeric ID, so this never threatens file compatibility - the only
+ * observable effect is generated-code diff noise across unrelated
+ * metamodel edits, a cosmetic cost judged acceptable given it matches
+ * upstream EMF precedent.
+ *
+ * featureID is assigned over getEAllStructuralFeatures() (inherited-then-
+ * own, matching real EMF), NOT a per-class restart at 0 - a subclass's
+ * generated eGet/eSet needs one flat ID space covering both its inherited
+ * and its own features (a generated subclass typically delegates any
+ * featureID it doesn't recognize to `super.eGet()`/`super.eSet()`), so an
+ * inherited feature and a subclass's own new feature must never collide.
+ * Reassigning via any subclass's getEAllStructuralFeatures() is safe to
+ * repeat for the same feature across multiple classes in the hierarchy -
+ * the computed index is the same regardless of which class's perspective
+ * computes it, since supertype features always come first in the same
+ * relative order.
+ *
+ * operationID follows the exact same shape and rationale, over
+ * getEAllOperations() instead - added for point 4 (EOperation.
+ * getOperationID(), which just exposes this).
+ */
+declare function assignFreshIds(pkg: EPackage): void;
+
+interface RunGenerationResult {
+    writtenPaths: string[];
+    outputRoot: string;
+}
+/**
+ * `configDir` is the directory the config file itself lives in -
+ * `config.outputDir` resolves relative to THAT, not the process's current
+ * working directory, so a config file behaves identically regardless of
+ * where the CLI happens to be invoked from.
+ */
+declare function runGeneration(config: GeneratorConfig, configDir: string, pkg: EPackage): Promise<RunGenerationResult>;
+
+/**
+ * Resolves a config file's "templateSet" name string to a real
+ * TemplateSet. Only built-in sets are known here for now - a third-party
+ * set (e.g. a Java one) would need its own registration mechanism, not yet
+ * built; see NOTES.md.
+ */
+declare function resolveTemplateSet(name: string): TemplateSet;
+
+/** The generator's own annotation source. */
+declare const TYPEMF_GENERATOR_ANNOTATION_SOURCE = "https://typemf.dev/generator";
+/** Real EMF's own GenModel annotation source - where its GenModel keeps an operation's `body`. */
+declare const ECLIPSE_GENMODEL_ANNOTATION_SOURCE = "http://www.eclipse.org/emf/2002/GenModel";
+/** Real EMF's Ecore annotation source - the documentation fallback (real Ecore.ecore uses it for `constraints`). */
+declare const ECLIPSE_ECORE_ANNOTATION_SOURCE = "http://www.eclipse.org/emf/2002/Ecore";
+/**
+ * The layering rule shared by everything that is read from an element's
+ * annotations under a plain key: the `key` detail of the annotation with
+ * source https://typemf.dev/generator first, then the same key in the
+ * annotation with source `fallbackSource`. Which fallback source applies
+ * is decided per thing being read (see documentationOf, operationBody),
+ * not globally. Used as written - not checked, not interpreted; an empty
+ * value counts as absent (so it falls through to the next layer).
+ */
+declare function layeredAnnotationDetail(element: EModelElement, key: string, fallbackSource: string): string | undefined;
+/**
+ * An element's documentation: the `documentation` detail, layered - the
+ * typemf generator annotation first, the annotation with source
+ * http://www.eclipse.org/emf/2002/Ecore as the fallback.
+ *
+ * NOTE: real EMF keeps `documentation` in the GenModel source
+ * (http://www.eclipse.org/emf/2002/GenModel), not the Ecore one - so that
+ * is deliberately NOT read here: documentation an EMF-authored .ecore
+ * carries under GenModel is ignored unless it is also supplied under one
+ * of the two sources above.
+ */
+declare function documentationOf(element: EModelElement): string | undefined;
+/**
+ * Renders a JSDoc block from documentationOf(), or '' if there is none.
+ * Deliberately WITHOUT a trailing newline: every template writes
+ * `{{ docComment(x) }}` on its own line and puts the declaration on the
+ * next one, so the template's own newline is what separates them - a
+ * trailing newline here as well used to leave a blank line between every
+ * doc comment and the declaration it documents.
+ */
+declare function docComment(element: EModelElement, indent?: string): string;
+/**
+ * An operation's body, in strict priority order:
+ *
+ *  1. the `body` detail of the annotation with source
+ *     https://typemf.dev/generator
+ *  2. the `body` detail of the annotation with source
+ *     http://www.eclipse.org/emf/2002/GenModel
+ *
+ * Used as written - not checked, not interpreted; an empty value counts
+ * as absent (the operation then gets the throwing stub). Note the second
+ * layer is real EMF's own key, where the value is Java source: a real
+ * EMF-authored .ecore that carries Java bodies there will have that Java
+ * emitted verbatim unless a layer-1 body overrides it - which is the
+ * point of the ordering, and the reason a layer-1 body should be added
+ * to any operation whose GenModel body isn't valid TypeScript.
+ *
+ * (Earlier versions read a per-template-set key, `body:typescript`, on
+ * the reasoning that one shared key would be ambiguous across multiple
+ * target languages. Replaced on request by these two layers.)
+ */
+declare function operationBody(operation: EOperation): string | undefined;
+/**
+ * The annotation source for a structural feature's own custom getter/setter
+ * bodies: `get` and `set` details of the annotation with source
+ * https://typemf.dev/generator/feature. Deliberately NOT layered with a
+ * GenModel fallback (unlike documentationOf/operationBody) - this source
+ * was specified on its own, with no second layer requested.
+ */
+declare const FEATURE_ANNOTATION_SOURCE = "https://typemf.dev/generator/feature";
+/**
+ * A feature's custom getter body (`get` detail), used verbatim as the body
+ * of its bean getter method - and, so reflective access agrees with the
+ * real implementation (the bug found and fixed for
+ * EClass.getEAllStructuralFeatures: the generated eGet used to read the
+ * STORED FIELD directly, bypassing any computed getter entirely), as what
+ * `eGet` calls too. A feature with a custom getter has NO stored field at
+ * all - there is nothing for the old field-reading shape to read.
+ */
+declare function featureGetter(feature: EStructuralFeature): string | undefined;
+/**
+ * A feature's custom setter body (`set` detail), used verbatim as the body
+ * of its bean setter method, and what `eSet` delegates to reflectively -
+ * replacing the default oldValue/eBasicSetValue/eDidAdd/eDidRemove
+ * machinery entirely, since a custom setter defines the feature's true
+ * write semantics itself. Only meaningful for a SINGLE-valued feature: a
+ * many-valued feature never has a setter method to begin with (real EMF
+ * convention - the getter's EList is mutated directly), so a `set` on one
+ * is a no-op, flagged by findFeatureAnnotationProblems.
+ */
+declare function featureSetter(feature: EStructuralFeature): string | undefined;
+/**
+ * Whether a feature with both a custom getter and a custom setter genuinely needs its own backing
+ * field - true only when at least one of the two bodies actually references it (`this._name`).
+ * EEnumLiteral.literal's getter/setter do ("this._literal ?? this.getName()", "this._literal =
+ * value") - it needs a field. A feature whose getter/setter delegate entirely to a DIFFERENT
+ * feature (e.g. a "shout" getter/setter that only ever reads/writes "raw") does not - declaring an
+ * unused field for it would be dead weight, and checking `eIsSet`/`eUnset` against that field would
+ * be flatly wrong (the field never changes, so "is set" would never reflect reality). Found by
+ * running this exact case: an earlier version of this rule declared a field for EVERY getter+setter
+ * pair unconditionally, breaking any feature that delegates to another one entirely.
+ */
+declare function customBodyNeedsOwnField(feature: EStructuralFeature): boolean;
+/**
+ * Whether a single-valued feature has no setter at all: either a
+ * trivialDerivedFormula (pre-existing, hard-coded), or a custom getter
+ * with no custom setter (a feature computed by featureGetter, and nothing
+ * says how to write it back). A many-valued feature is unaffected by this
+ * (it never has a setter regardless).
+ */
+declare function isReadOnlyFeature(feature: EStructuralFeature): boolean;
+/**
+ * A changeable=false feature that isn't otherwise read-only (not derived, no custom getter) still
+ * needs a real setter SOMEWHERE - real EMF's own convention (matches this session's earlier
+ * containerClass work): a plain, impl-only setter that bypasses eSet/eDidAdd/eDidRemove entirely
+ * (direct field assignment, no notification), reachable only by callers with the concrete impl type
+ * (bootstrap code, the loader), never through the public interface or reflective eSet.
+ */
+declare function needsImplOnlySetter(feature: EStructuralFeature): boolean;
+/** findDataTypeAnnotationProblems's counterpart for feature get/set annotations: a `set` on a many-valued feature is a no-op (see featureSetter), reported rather than silently ignored. */
+declare function findFeatureAnnotationProblems(pkg: EPackage): string[];
+/** The real formula body for a trivially-computable derived feature, or undefined if `feature` isn't one of the four. */
+declare function trivialDerivedFormula(feature: EStructuralFeature): string | undefined;
+/**
+ * The TypeScript type name for a classifier's scalar form (no EList
+ * wrapping). `undefined` specifically means "this feature's type is
+ * Ecore's own EObject classifier" - the generator never produces its own
+ * api/gen/impl files for a classifier named "EObject" (matches the
+ * existing no-declared-supertype convention, which already falls back to
+ * the real @typemf/core EObject rather than generating a redundant,
+ * shadowing one - see eclass.njk / main.njk). The dynamic-to-typed
+ * conversion step that builds a real metamodel from a parsed .ecore file
+ * deliberately leaves such a feature's eType unset for exactly this
+ * reason, so `undefined` reaching here always means EObject.
+ */
+declare function tsScalarType(type: EClassifier | ETypedElement | undefined): string;
+/**
+ * Every classifier bound anywhere inside `genericType`'s type arguments,
+ * recursively (not `genericType`'s own classifier - that is the element's
+ * eType, handled separately) - needed so the templates can register the
+ * imports the emitted type arguments require.
+ */
+declare function genericArgumentClassifiers(genericType: EGenericType | undefined): EClassifier[];
+interface ResolvedDataTypeText {
+    /** The TypeScript type text to emit wherever this datatype is used. */
+    text: string;
+    /** The import this use needs, if the datatype has import information that applies (see resolveDataTypeTs): the symbol and the module it comes from (see ImportEntry.from). Independent of where `text` came from. */
+    importName?: string;
+    importFrom?: string;
+}
+/**
+ * The layered resolution of what TypeScript type text an EDataType
+ * stands for, wherever it occurs (attribute/reference type, operation
+ * return type, parameter type, ...), in strict priority order - and with
+ * NO built-in knowledge of any datatype: every mapping comes from the
+ * metamodel (or the mapping supplied alongside it), and a missing one is
+ * a fix there, not something the generator papers over.
+ *
+ *  1. The `type` detail of the datatype's annotation with source
+ *     https://typemf.dev/generator - the text, as written.
+ *  2. The datatype's `instanceClassName`, as written, if set.
+ *  3. The datatype's name, as written.
+ *
+ * Separately from which layer supplied the text, the datatype's IMPORT
+ * information (TypeImportMapping: the explicit mapping entry if there is
+ * one, else its annotation with source https://typemf.dev/generator/import)
+ * says what to import when it is used: its `type` symbol, from `from` if
+ * the datatype is EXTERNAL (belongs to a package other than the one being
+ * generated) or from `internal-from` (falling back to `from`) if INTERNAL.
+ * If the key that applies is absent, no import is registered - the text is
+ * still emitted, so a missing import shows up as a compile error naming
+ * the type.
+ *
+ * Nothing is checked or interpreted.
+ */
+declare function resolveDataTypeTs(dataType: EDataType): ResolvedDataTypeText;
+/**
+ * Registers the imports a body declares - an operation's, or (see
+ * FEATURE_ANNOTATION_SOURCE) a feature's custom getter/setter: one
+ * annotation with source https://typemf.dev/generator/import per import
+ * (`type` = the symbol; `from` / `internal-from` reuse a datatype's detail
+ * names, but NOT its external/internal MEANING - see below).
+ *
+ * A body is always internal: it is source code that becomes part of the
+ * package being generated, in every generation, never a reference to a
+ * type belonging to some other package. So there is no isExternal()
+ * check here (contrast resolveDataTypeTs, where a datatype genuinely can
+ * belong to a different package) - `internal-from` applies, falling back
+ * to `from` only as an alternate spelling of the same (internal) path,
+ * not as a distinct external case. Returns '' - it is called for its
+ * effect, from the template that emits the body.
+ */
+declare function registerBodyImports(element: EModelElement): string;
+declare function isPrimitiveValueType(classifier: EClassifier | undefined): boolean;
+/**
+ * The feature's own declared `defaultValueLiteral` when it has one (e.g. `changeable`'s real
+ * declared default is "true", not the generic zero-default) - otherwise 'false' for EBoolean, '0' for
+ * every other primitive numeric EDataType (the real Java-primitive zero-default). Used as a stored
+ * field's initial value instead of `undefined`.
+ */
+declare function primitiveDefaultValue(feature: ETypedElement): string;
+/**
+ * A feature's scalar TypeScript type, with " | undefined" appended UNLESS
+ * the type is one of the real JS-primitive-with-a-zero-value EDataTypes
+ * (see isPrimitiveValueType) - those never need the union, since a
+ * generated field for one always has a real value (the zero-default),
+ * never a genuine absence. Prefer this over manually appending
+ * " | undefined" to tsScalarType()'s result in a template, so the
+ * primitive-type exception lives in one place.
+ */
+declare function tsOptionalScalarType(type: EClassifier | ETypedElement | undefined): string;
+/**
+ * "getTitle" or, for a single-valued EBoolean attribute specifically,
+ * "isPublished" - matching the common convention (real EMF does this too,
+ * gated on the same isMany()===false && type===EBoolean condition).
+ * Deliberately does NOT affect many-valued features (an EList<boolean>
+ * has no sensible "isX" reading) or the setter (which stays "setX"
+ * regardless - only asked for the getter to change).
+ */
+declare function beanGetterName(feature: EStructuralFeature): string;
+/** The full TypeScript type for a feature's getter/setter, including EList<T> for many-valued features. */
+declare function tsFeatureType(feature: ETypedElement): string;
+/** Whether a single-valued feature's getter/setter type should be nullable (unset is a real possibility). */
+declare function isOptional(feature: EStructuralFeature): boolean;
+declare function isEClass(classifier: EClassifier): classifier is EClass;
+declare function isEEnum(classifier: EClassifier): classifier is EEnum;
+declare function isEDataType(classifier: EClassifier): classifier is EDataType;
+declare function isEReference(feature: EStructuralFeature): boolean;
+/** "name: Type, name2: Type2" for an operation's parameter list. */
+declare function paramList(operation: EOperation): string;
+/** Like paramList, but every parameter is optional ("name?: type") - for the merged implementation signature of an auto-resolved overload set (see metaclassAccessorCollision). */
+declare function optionalParamList(operation: EOperation): string;
+/** "name, name2" - just the argument names, e.g. for a super-call passthrough. */
+declare function argList(operation: EOperation): string;
+/**
+ * Groups a class's own operations by name, preserving first-seen order -
+ * needed because real Ecore.ecore has genuine overloaded operations
+ * (EEnum.getEEnumLiteral, by name and by value) and a TS class can only
+ * have ONE method body per name, unlike an interface, which supports
+ * overloads natively (so only the impl side needs this grouping, not the
+ * types/ interface side - see the loop in eclass.njk). Scoped to
+ * same-arity overloads only, matching what real Ecore.ecore actually
+ * has - a genuine arity mismatch within one name is not handled (see
+ * NOTES.md).
+ */
+declare function groupOperationsByName(operations: Iterable<EOperation>): EOperation[][];
+/**
+ * The merged implementation signature's parameter list for a group of
+ * same-named operations (see mergedParams; different arities included).
+ * For a group of exactly one operation, this is identical to paramList().
+ */
+declare function mergedParamList(group: EOperation[]): string;
+interface OverloadBranch {
+    operation: EOperation;
+    /** The TypeScript condition that selects this overload. */
+    condition: string;
+    /** The overload's body (layered, see operationBody), or undefined -> the branch throws its own "no body" error. */
+    body: string | undefined;
+    /** `const <own name> = <merged name> as <own type>;` for each of the overload's own parameter names its body actually uses. */
+    aliases: string[];
+    /** e.g. "EClass.getEStructuralFeature(featureID)", for error messages. */
+    label: string;
+}
+interface OverloadDispatch {
+    /** Set when the group is NOT dispatched: the whole implementation is one throwing stub with this message. */
+    stubMessage?: string;
+    branches: OverloadBranch[];
+}
+/**
+ * How the implementation of an overload group selects the overload to
+ * run. Per overload, in order:
+ *
+ *  1. an explicit `dispatch` detail on the overload's annotation with
+ *     source https://typemf.dev/generator, used as written (a condition
+ *     over the MERGED parameter names) - for cases the derivation cannot
+ *     handle;
+ *  2. otherwise a condition derived from the parameters, combined with &&,
+ *     for each position: a position the overload does not have must be
+ *     `=== undefined`; where the overloads having the position differ in
+ *     type, the overload's own type must be a runtime-testable primitive
+ *     (`typeof x === 'string'`); where the type is the same everywhere but
+ *     the position is optional, `!== undefined`.
+ *
+ * The group is NOT dispatched - the implementation stays a single
+ * throwing stub whose message says why - when no overload has a body,
+ * when a needed test cannot be derived and no explicit condition was
+ * given, or when two overloads end up with the same condition (they could
+ * never be told apart, so the second would be unreachable).
+ */
+declare function overloadDispatch(group: EOperation[], className: string): OverloadDispatch;
+/**
+ * An operation's return type, with " | undefined" appended only if its
+ * OWN declared multiplicity says the result may genuinely be absent
+ * (not required - lowerBound < 1) - unlike tsOptionalScalarType() (used
+ * for structural features' getters), which appends it unconditionally
+ * for every non-primitive type. Operations need this per-operation check
+ * instead of a blanket rule: most operations (isSuperTypeOf(): boolean,
+ * getClassifierID(): number, ...) are genuinely never-null by their own
+ * declared multiplicity, and blanket-appending | undefined to every one
+ * of them would be wrong - unlike structural features, where treating
+ * every single-valued reference as "may be unset" is the reasonable
+ * default.
+ *
+ * This is the fix for a real, confirmed gap: real Ecore.ecore's own
+ * EModelElement.getEAnnotation(source) has no declared lowerBound (real
+ * EMF's default there is 0 - not required), meaning the operation is
+ * genuinely allowed to return nothing when no annotation with that
+ * source is attached - but the generator previously always emitted the
+ * bare, non-optional return type for every operation regardless.
+ */
+declare function tsOperationReturnType(op: EOperation): string;
+/** The merged implementation signature's return type for a group - the union of every overload's OWN (possibly optional) return type via tsOperationReturnType(), deduplicated (so an all-identical group collapses to just that one type, not a redundant self-union). */
+declare function mergedReturnType(group: EOperation[]): string;
+/**
+ * Uppercases only the first character, leaving the rest untouched -
+ * NOT the same as Nunjucks' built-in `capitalize` filter, which mirrors
+ * Jinja2's and lowercases everything after the first letter (breaking any
+ * camelCase name: "pageCount" -> "Pagecount"). Used to build bean-style
+ * accessor names ("pageCount" -> "getPageCount") without corrupting them.
+ */
+declare function ucfirst(s: string): string;
+/** The generated Package singleton class name for a package, e.g. "library" -> "LibraryPackage". */
+declare function packageClassName(pkg: EPackage): string;
+declare function factoryClassName(pkg: EPackage): string;
+declare function switchClassName(pkg: EPackage): string;
+declare function typeGuardsClassName(pkg: EPackage): string;
+/** The EClass's single supertype for TS `extends` purposes, or undefined - see NOTES.md on multiple inheritance. */
+declare function superType(eClass: EClass): EClass | undefined;
+/** eClass itself, then each ancestor in turn (via superType()), nearest first. */
+declare function superTypeChain(eClass: EClass): EClass[];
+/**
+ * Whether this class descends from (or is) "EClassifier" - needed
+ * specifically for self-hosting Ecore.ecore: classifierID is internal
+ * dispatch bookkeeping, not a real modeled Ecore feature, so it's never
+ * emitted by the ordinary feature-driven getter/setter generation - but
+ * bootstrap code constructing the metamodel's own classifier shells
+ * (which ARE real EClassifier-derived instances, e.g. EClassImpl,
+ * EDataTypeImpl) genuinely needs to set it. Confirmed as a real,
+ * necessary gap by actually running self-hosted bootstrap code, not
+ * assumed - see NOTES.md.
+ */
+declare function isClassifierDerived(eClass: EClass): boolean;
+/** The featureID analog of isClassifierDerived() - same reasoning, same real gap found the same way (see NOTES.md). */
+declare function isStructuralFeatureDerived(eClass: EClass): boolean;
+/** The operationID analog of isClassifierDerived()/isStructuralFeatureDerived() - added for point 4. */
+declare function isOperationDerived(eClass: EClass): boolean;
+/**
+ * Whether a real EOperation's name collides with a hand-added bookkeeping
+ * method (classifierID/featureID - see isClassifierDerived/
+ * isStructuralFeatureDerived's own doc comments). Real Ecore.ecore
+ * genuinely declares both "EClassifier.getClassifierID(): EInt" and
+ * "EStructuralFeature.getFeatureID(): EInt" as real, zero-arg operations
+ * - colliding, by name, with exactly the bookkeeping getters added for
+ * the self-hosting bootstrap fix. Confirmed directly against the real
+ * file before excluding these operations from the generic,
+ * throwing-stub-generating operation loop, not assumed - see NOTES.md.
+ */
+declare function isBookkeepingOperation(op: EOperation, eClass: EClass): boolean;
+/**
+ * Whether classifier `classifierName`'s zero-arg metaclass accessor
+ * (get{ClassifierName}(), generated directly on the package class for
+ * every classifier the package declares) collides with a real EOperation
+ * inherited by the package class from one of ITS OWN ancestors. Only
+ * relevant when self-hosting - "EPackage" (the package class's own
+ * superclass) is itself one of the metamodel's declared classifiers only
+ * in that case; an ordinary metamodel never has this situation at all,
+ * so this always returns undefined for one.
+ *
+ * General by design, not hardcoded to specific names: real Ecore.ecore
+ * happens to have exactly two instances of this shape
+ * (EModelElement.getEAnnotation(source), EPackage.getEClassifier(name)),
+ * found by a systematic scan across every classifier's own+inherited
+ * generated members, not by inspection - confirmed nothing else in the
+ * real file collides this way (or any other way) - see NOTES.md. This
+ * function exists so the SAME resolution automatically covers any future
+ * metamodel with a classifier sharing a name with one of the package
+ * class's own inherited operations, without needing another hardcoded
+ * exclusion added by hand each time one is found.
+ */
+declare function metaclassAccessorCollision(classifierName: string, pkg: EPackage): EOperation | undefined;
+/**
+ * Distinct, non-primitive classifier names referenced by any metaclass-
+ * accessor collision's own signature (return type or parameter types) in
+ * `pkg` - needed for {Pkg}Package.ts's own import line, general rather
+ * than hardcoding "EAnnotation" (real Ecore.ecore's one actual instance
+ * today): a future metamodel's own colliding operation could return or
+ * accept any classifier at all.
+ */
+declare function metaclassAccessorCollisionTypeNames(pkg: EPackage): string[];
+/**
+ * A general validation pass, meant to run during generation (not just as
+ * a one-off diagnostic): for every classifier in `pkg`, checks every name
+ * that would be generated as one of its members - own or inherited bean
+ * accessors, real operations, bookkeeping methods (classifierID/
+ * featureID), and (for the package class specifically) metaclass
+ * accessors - for a collision with something else generated under the
+ * same name, EXCLUDING the two patterns the generator already resolves
+ * correctly on its own (isBookkeepingOperation's exclusion, and
+ * metaclassAccessorCollision's automatic overload-set generation).
+ * Anything left over is a genuine, unhandled collision that would
+ * silently produce wrong runtime behaviour (the later declaration wins,
+ * no compile error) - generation should refuse to proceed rather than
+ * emit it silently.
+ *
+ * Deliberately reuses the same real helpers the templates themselves
+ * use (isBookkeepingOperation, groupOperationsByName, beanGetterName,
+ * metaclassAccessorCollision) rather than a parallel reimplementation,
+ * so this can never silently drift out of sync with what actually gets
+ * generated.
+ */
+interface MemberCollision {
+    classifierName: string;
+    memberName: string;
+    sources: string[];
+}
+/**
+ * Every classifier, feature, operation, parameter, and enum literal in `pkg` genuinely needs a name -
+ * code generation cannot produce a meaningful `class {name} {}`/`get{name}()`/etc. for one that has
+ * none (real Ecore.ecore's own `name` attribute is optional, matching real EMF, so this is a real,
+ * reachable state, not a hypothetical one). Checked once, up front, via the same validate() hook every
+ * other model-level problem goes through - so every OTHER function in this file can safely assert a
+ * name is present (`!`) rather than re-checking it at every one of the many call sites that need one,
+ * confident generate() would have already refused to run otherwise.
+ */
+declare function findUnnamedElements(pkg: EPackage): string[];
+declare function findUnresolvedCollisions(pkg: EPackage): MemberCollision[];
+/**
+ * Distinct EClass/EEnum type names referenced by `features` (an EClass or
+ * EEnum's own attribute/reference types) that need their own import
+ * statement - EDataType primitives (string/number/boolean/Date) never do.
+ * A TS helper rather than a Nunjucks loop with manual dedup, since
+ * template-level array mutation is awkward without extra Nunjucks
+ * extensions - matches the "templates handle structure, TS computes"
+ * principle.
+ */
+declare function referencedApiTypes(features: Iterable<EStructuralFeature>, ...excludeTypeNames: string[]): string[];
+/**
+ * The operation-scoped analog of referencedApiTypes, for the identical
+ * "needs its own import statement" reason - but operations weren't
+ * scanned by anything at all before this existed, a genuine gap: an
+ * operation's return type or any parameter's type can be any classifier,
+ * including a non-primitive EDataType (real Ecore.ecore's own
+ * EClassifier.getContainerClass(): EJavaClass, for one) - unlike
+ * features, where only EClass/EEnum ever need an import (a plain
+ * EDataType-typed feature is always one of the handful of TS-primitive-
+ * mapped names). Confirmed as a real, previously-missing import by
+ * actually generating real Ecore.ecore and type-checking the merged
+ * output, not assumed - see NOTES.md.
+ */
+declare function referencedOperationTypes(operations: Iterable<EOperation>, ...excludeTypeNames: string[]): string[];
+/**
+ * Nunjucks 3.2.4 silently does not support Jinja2's inline `{% for x in y
+ * if cond %}` for-loop filter syntax (it parses without error but produces
+ * wrong output - verified empirically, not assumed) - these pre-filtered
+ * helpers replace every case a template would otherwise want that syntax
+ * for, consistent with keeping templates dumb.
+ */
+/**
+ * Safely emits a metamodel-supplied string as a TypeScript string literal,
+ * via JSON.stringify() - handles quotes, apostrophes, newlines, backslashes,
+ * anything. Every place a template interpolates a name/label/annotation
+ * value from the metamodel into generated source needs this, not naive
+ * single-quote wrapping - annotation `details` values in particular are
+ * often free-form prose (GenModel documentation, validation constraint
+ * text) and are genuinely likely to contain apostrophes or multi-line
+ * text, which naive interpolation would turn into broken generated code.
+ */
+declare function jsString(value: string | undefined): string;
+/**
+ * Nunjucks' {% for %} reliably iterates plain objects and arrays, but not
+ * necessarily a real ES6 Map instance the same way (its object-iteration
+ * path likely uses Object.keys(), which is empty for a Map's own
+ * enumerable properties - the entries live internally, not as own
+ * properties). Converting to a plain array here avoids relying on
+ * behavior that was never actually verified.
+ */
+declare function detailsEntries(annotation: EAnnotation): {
+    key: string;
+    value: string;
+}[];
+declare function eClassesOf(pkg: EPackage): EClass[];
+declare function concreteEClassesOf(pkg: EPackage): EClass[];
+/**
+ * Finds an EClass by exact name within the package, or undefined if none
+ * matches - used specifically for the EFactory/{Pkg}Factory unification
+ * special case (see efactory.njk): when a metamodel models a classifier
+ * literally named "EFactory" (as real Ecore.ecore does), the package-level
+ * generated Factory extends ITS generated impl instead of the generic
+ * @typemf/core EFactoryImpl base, matching real EMF's own
+ * EcoreFactoryImpl-extends-EFactoryImpl design. Ordinary metamodels (no
+ * "EFactory" classifier) are unaffected.
+ */
+declare function findEClassByName(pkg: EPackage, name: string): EClass | undefined;
+declare function singleValuedFeatures(features: Iterable<EStructuralFeature>): EStructuralFeature[];
+
+declare const typescriptTemplateSet: TemplateSet;
+
+export { ECLIPSE_ECORE_ANNOTATION_SOURCE, ECLIPSE_GENMODEL_ANNOTATION_SOURCE, FEATURE_ANNOTATION_SOURCE, type GeneratedFile, type GeneratorConfig, type MemberCollision, type OverloadBranch, type OverloadDispatch, type ResolvedDataTypeText, type RunGenerationResult, TYPEMF_GENERATOR_ANNOTATION_SOURCE, type TemplateSet, argList, assignFreshIds, beanGetterName, buildEcoreMetaSchema, concreteEClassesOf, convertDynamicEcoreToTyped, customBodyNeedsOwnField, detailsEntries, docComment, documentationOf, eClassesOf, factoryClassName, featureGetter, featureSetter, findEClassByName, findFeatureAnnotationProblems, findUnnamedElements, findUnresolvedCollisions, generate, genericArgumentClassifiers, groupOperationsByName, isBookkeepingOperation, isClassifierDerived, isEClass, isEDataType, isEEnum, isEReference, isOperationDerived, isOptional, isPrimitiveValueType, isReadOnlyFeature, isStructuralFeatureDerived, jsString, layeredAnnotationDetail, loadConfig, loadEcorePackage, mergedParamList, mergedReturnType, metaclassAccessorCollision, metaclassAccessorCollisionTypeNames, needsImplOnlySetter, operationBody, optionalParamList, overloadDispatch, packageClassName, paramList, primitiveDefaultValue, referencedApiTypes, referencedOperationTypes, registerBodyImports, resolveDataTypeTs, resolveTemplateSet, runGeneration, singleValuedFeatures, superType, superTypeChain, switchClassName, trivialDerivedFormula, tsFeatureType, tsOperationReturnType, tsOptionalScalarType, tsScalarType, typeGuardsClassName, typescriptTemplateSet, ucfirst };