@lionweb/core 0.7.0-beta.2 → 0.7.0-beta.21

package/src/m3/facade.ts

@@ -0,0 +1,130 @@
+import { builtinFeatures } from "./builtins.js"
+import { metaTypedBasedClassifierDeducerFor, qualifiedNameOf } from "./functions.js"
+import { lioncore, metaConcepts, metaFeatures } from "./lioncore.js"
+import { Reader } from "../reading.js"
+import {
+    Annotation,
+    Classifier,
+    Concept,
+    Containment,
+    Enumeration,
+    EnumerationLiteral,
+    Interface,
+    Language,
+    M3Concept,
+    PrimitiveType,
+    Property,
+    Reference
+} from "./types.js"
+import { updateSettingsNameBased, Writer } from "../writing.js"
+
+const { inamed_name } = builtinFeatures
+const { ikeyed_key } = metaFeatures
+
+export const lioncoreReader: Reader<M3Concept> = {
+    classifierOf: metaTypedBasedClassifierDeducerFor(lioncore),
+    getFeatureValue: (node, feature) =>
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (node as any)[feature.name], // (mirrors name-based update of settings)
+    enumerationLiteralFrom: (value, _) => value as EnumerationLiteral | null
+}
+
+/**
+ * Alias for {@link lioncoreReader}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export const lioncoreExtractionFacade = lioncoreReader
+
+/**
+ * @return An implementation of {@link Writer} for instances of the LionCore M3 (so M2s).
+ */
+export const lioncoreWriter: Writer<M3Concept> = {
+    nodeFor: (parent, classifier, id, propertySettings) => {
+        switch (classifier.key) {
+            case metaConcepts.annotation.key:
+                return new Annotation(
+                    parent as Language,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.concept.key:
+                return new Concept(
+                    parent as Language,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id,
+                    propertySettings[metaFeatures.concept_abstract.key] as boolean
+                )
+            case metaConcepts.interface.key:
+                return new Interface(
+                    parent as Language,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.containment.key:
+                return new Containment(
+                    parent as Classifier,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.enumeration.key:
+                return new Enumeration(
+                    parent as Language,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.enumerationLiteral.key:
+                return new EnumerationLiteral(
+                    parent as Enumeration,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.language.key:
+                return new Language(
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[metaFeatures.language_version.key] as string,
+                    id,
+                    propertySettings[metaFeatures.ikeyed_key.key] as string
+                )
+            case metaConcepts.primitiveType.key:
+                return new PrimitiveType(
+                    parent as Language,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.property.key:
+                return new Property(
+                    parent as Classifier,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            case metaConcepts.reference.key:
+                return new Reference(
+                    parent as Classifier,
+                    propertySettings[inamed_name.key] as string,
+                    propertySettings[ikeyed_key.key] as string,
+                    id
+                )
+            default:
+                throw new Error(
+                    `don't know a node of concept ${qualifiedNameOf(classifier)} with key ${classifier.key} that's not in LionCore M3`
+                )
+        }
+    },
+    setFeatureValue: (node, feature, value) => {
+        updateSettingsNameBased(node as unknown as Record<string, unknown>, feature, value)
+    },
+    encodingOf: literal => literal
+}
+
+/**
+ * Alias for {@link lioncoreWriter}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+export const lioncoreInstantationFacade = lioncoreWriter
+

package/src/m3/factory.ts

@@ -0,0 +1,98 @@
+import { StringsMapper } from "@lionweb/ts-utils"
+import { SingleRef } from "../references.js"
+import {
+    Annotation,
+    Classifier,
+    Concept,
+    Containment,
+    Enumeration,
+    EnumerationLiteral,
+    Interface,
+    Language,
+    PrimitiveType,
+    Property,
+    Reference
+} from "./types.js"
+
+
+/**
+ * A factory that produces a {@link Language} instance,
+ * as well as {@link LanguageEntity entities} contained by that instance
+ * and {@link Feature features} of {@link Classifier classifiers}
+ * and {@link EnumerationLiteral enumeration literals} of {@link Enumeration enumerations}.
+ *
+ * The factory methods take care of proper containment.
+ * *Note:* also calling `havingEntities`, `havingFeatures`, and `havingLiterals` doesn't produce duplicates.
+ * (This is to stay backward compatible.)
+ */
+export class LanguageFactory {
+
+    readonly id: StringsMapper
+    readonly key: StringsMapper
+    readonly language: Language
+
+    constructor(name: string, version: string, id: StringsMapper, key: StringsMapper) {
+        this.id = id
+        this.key = key
+        this.language = new Language(name, version, this.id(name), this.key(name))
+    }
+
+
+    annotation(name: string, extends_?: SingleRef<Annotation>): Annotation {
+        const annotation = new Annotation(this.language, name, this.key(this.language.name, name), this.id(this.language.name, name), extends_)
+        this.language.havingEntities(annotation)
+        return annotation
+    }
+
+    concept(name: string, abstract: boolean, extends_?: SingleRef<Concept>): Concept {
+        const concept = new Concept(this.language, name, this.key(this.language.name, name), this.id(this.language.name, name), abstract, extends_)
+        this.language.havingEntities(concept)
+        return concept
+    }
+
+    interface(name: string): Interface {
+        const intface = new Interface(this.language, name, this.key(this.language.name, name), this.id(this.language.name, name))
+        this.language.havingEntities(intface)
+        return intface
+    }
+
+    enumeration(name: string): Enumeration {
+        const enumeration = new Enumeration(this.language, name, this.key(this.language.name, name), this.id(this.language.name, name))
+        this.language.havingEntities(enumeration)
+        return enumeration
+    }
+
+    primitiveType(name: string): PrimitiveType {
+        const primitiveType = new PrimitiveType(this.language, name, this.key(this.language.name, name), this.id(this.language.name, name))
+        this.language.havingEntities(primitiveType)
+        return primitiveType
+    }
+
+
+    containment(classifier: Classifier, name: string): Containment {
+        const containment = new Containment(classifier, name, this.key(this.language.name, classifier.name, name), this.id(this.language.name, classifier.name, name))
+        classifier.havingFeatures(containment)
+        return containment
+    }
+
+    property(classifier: Classifier, name: string): Property {
+        const property = new Property(classifier, name, this.key(this.language.name, classifier.name, name), this.id(this.language.name, classifier.name, name))
+        classifier.havingFeatures(property)
+        return property
+    }
+
+    reference(classifier: Classifier, name: string): Reference {
+        const reference = new Reference(classifier, name, this.key(this.language.name, classifier.name, name), this.id(this.language.name, classifier.name, name))
+        classifier.havingFeatures(reference)
+        return reference
+    }
+
+
+    enumerationLiteral(enumeration: Enumeration, name: string): EnumerationLiteral {
+        const enumerationLiteral = new EnumerationLiteral(enumeration, name, this.key(this.language.name, enumeration.name, name), this.id(this.language.name, enumeration.name, name))
+        enumeration.havingLiterals(enumerationLiteral)
+        return enumerationLiteral
+    }
+
+}
+

package/src/m3/feature-resolvers.ts

@@ -0,0 +1,72 @@
+// Copyright 2025 TRUMPF Laser SE and other contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { LionWebJsonMetaPointer } from "@lionweb/json"
+
+import { Classifier, Containment, Feature, Language, Property, Reference } from "./types.js"
+import { MemoisingSymbolTable } from "./symbol-table.js"
+
+
+/**
+ * Type def. for functions that resolve a {@link Feature feature} of the indicated sub-type
+ * from a feature's and a classifier's meta-pointers,
+ * throwing an {@link Error error} when the feature couldn't be resolved,
+ * or it isn't of the expected sub-type.
+ */
+export type FeatureResolver<FT extends Feature> = (metaPointer: LionWebJsonMetaPointer, classifier: Classifier) => FT
+
+/**
+ * Type def. for an object containing {@link FeatureResolver resolvers} for
+ * {@link Property properties}, {@link Containmnent containments}, and {@link Reference references}.
+ */
+export type FeatureResolvers = {
+    resolvedPropertyFrom: FeatureResolver<Property>
+    resolvedContainmentFrom: FeatureResolver<Containment>
+    resolvedReferenceFrom: FeatureResolver<Reference>
+}
+
+/**
+ * @return an {@link FeatureResolvers object} for the given {@link Language languages}.
+ */
+export const featureResolversFor = (languages: Language[]): FeatureResolvers => {
+    const symbolTable = new MemoisingSymbolTable(languages)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const featureResolverFor = <FT extends Feature>(featureClassConstructor: new (...args: any[]) => FT): FeatureResolver<FT> =>
+        (featureMetaPointer, classifier: Classifier) => {
+            const classifierMetaPointer = classifier.metaPointer()
+            const featureLocationMessage = () => `feature with meta-pointer ${JSON.stringify(featureMetaPointer)} on classifier with meta-pointer ${JSON.stringify(classifierMetaPointer)}`
+            const feature = symbolTable.featureMatching(classifierMetaPointer, featureMetaPointer)
+            if (feature === undefined) {
+                throw new Error(`couldn't resolve ${featureLocationMessage()}`)    // fail early <== unrecoverable
+            }
+            if (feature.constructor !== featureClassConstructor) {  // feature's type must match desired type *exactly* — cheaper to evaluate than "feature instanceof featureClassConstructor"
+                throw new Error(`${featureLocationMessage()} is not a ${featureClassConstructor.name} but a ${feature.constructor.name}`)    // fail early <== unrecoverable
+            }
+            /*
+             * We could make this function memoising as well, to avoid having to perform these checks every resolution.
+             * That memoisation would involve a 6-deep lookup, in the feature's meta-pointer + container's classifier meta-pointer.
+             * The checks seem cheap enough to not be problematic performance-wise, though.
+             */
+            return feature as FT    // valid <== feature.constructor === featureClassConstructor
+        }
+    return {
+        resolvedPropertyFrom: featureResolverFor(Property),
+        resolvedContainmentFrom: featureResolverFor(Containment),
+        resolvedReferenceFrom: featureResolverFor(Reference)
+    }
+}
+

package/src/m3/functions.ts

@@ -0,0 +1,379 @@
+/**
+ * Various functions on M3 models.
+ */
+
+
+import { LionWebId, LionWebKey } from "@lionweb/json"
+import { cycleWith, flatMapNonCyclingFollowing, sortByStringKey } from "@lionweb/ts-utils"
+import { containmentChain } from "../functions.js"
+import { ClassifierDeducer } from "../reading.js"
+import { isRef, unresolved } from "../references.js"
+import { Node } from "../types.js"
+import {
+    Annotation,
+    Classifier,
+    Concept,
+    Containment,
+    DataType,
+    Enumeration,
+    Feature,
+    IKeyed,
+    IMetaTyped,
+    INamed,
+    Interface,
+    isINamed,
+    Language,
+    LanguageEntity,
+    Link,
+    M3Concept,
+    Property,
+    Reference
+} from "./types.js"
+
+
+/**
+ * @return The type of the given {@link Feature}
+ */
+const type = (feature: Feature): Classifier | DataType | typeof unresolved =>
+    (feature as (Link | Property)).type
+
+
+const isProperty = (feature: Feature): feature is Property =>
+    feature instanceof Property
+
+const isContainment = (feature: Feature): feature is Containment =>
+    feature instanceof Containment
+
+const isReference = (feature: Feature): feature is Reference =>
+    feature instanceof Reference
+
+const isMultiple = (feature: Feature): feature is Link =>
+    feature instanceof Link && feature.multiple
+
+
+/**
+ * The (names of the) metatypes of a feature.
+ */
+type FeatureMetaType =
+    | "Containment"
+    | "Property"
+    | "Reference"
+
+/**
+ * @return the (name of the) metatype of the given {@link Feature feature}.
+ */
+const featureMetaType = (feature: Feature): FeatureMetaType => {
+    if (feature instanceof Containment) {
+        return "Containment"
+    }
+    if (feature instanceof Property) {
+        return "Property"
+    }
+    if (feature instanceof Reference) {
+        return "Reference"
+    }
+    throw new Error(`unhandled Feature sub type ${feature.constructor.name}`)
+}
+
+
+/**
+ * Determines whether a {@link Feature feature} is "relational",
+ * i.e. it's a {@link Link containment or reference}.
+ */
+const isRelational = (feature: Feature): feature is Link =>
+    feature instanceof Link
+
+/**
+ * @return the relations among the given {@link Feature features}.
+ */
+const relations = (features: Feature[]): Link[] =>
+    features.filter(isRelational)
+
+/**
+ * @return the non-relations among the given {@link Feature features}.
+ */
+const nonRelationalFeatures = (features: Feature[]): Feature[] =>
+    features.filter((feature) => !isRelational(feature))
+
+
+/**
+ * @return the relations of the given {@link LanguageEntity language element}.
+ */
+const relationsOf = (element: LanguageEntity): Link[] =>
+    element instanceof Classifier
+        ? relations(element.features)
+        : []
+
+
+/**
+ * @return The "things", i.e. {@link M3Concept}s, directly contained by the given "thing".
+ *  These can be:
+ *  {@link LanguageEntity language entities}, {@link Feature features}, and {@link EnumerationLiteral enumeration literals}
+ *  (and all their sub types).
+ */
+const directlyContaineds = (thing: M3Concept): M3Concept[] => {
+    if (thing instanceof Language) {
+        return thing.entities
+    }
+    if (thing instanceof Classifier) {
+        return thing.features as M3Concept[]    // (cast is necessary because of presence of Feature#classifier getter...?)
+    }
+    if (thing instanceof Enumeration) {
+        return thing.literals
+    }
+    return []
+}
+
+
+/**
+ * @return All {@link M3Concept nodes} contained in this {@link Language language},
+ * including the language itself.
+ */
+const allContaineds = (language: Language): M3Concept[] =>
+    [
+        language,
+        ...directlyContaineds(language),
+        ...directlyContaineds(language).flatMap(directlyContaineds)
+    ]
+
+
+/**
+ * Performs a depth-first tree traversal of a language, "flatMapping" the `map` function on every node.
+ * It avoids visiting nodes twice (to avoid potential infinite loops), but doesn't report cycles.
+ */
+const flatMap = <T>(language: Language, map: (t: M3Concept) => T[]): T[] =>
+    flatMapNonCyclingFollowing(map, directlyContaineds)(language)
+
+
+/**
+ * @return string the name of the given {@link INamed named thing}.
+ */
+const nameOf = <T extends INamed>({name}: T): string =>
+    name
+
+
+/**
+ * @return the given named things sorted by name
+ */
+export const nameSorted = <T extends INamed>(ts: T[]): T[] =>
+    sortByStringKey(ts, nameOf)
+
+
+/**
+ * @return the concatenation of the names of the given nodes using the given separator.
+ */
+const concatenateNamesOf = (separator: string, nodes: M3Concept[]): string =>
+    nodes
+        .filter(isINamed)
+        .map(nameOf)
+        .join(separator)
+    // !! slight overkill: every node in an M2 is an M3Concept, so IKeyed and INamed
+
+/**
+ * @return the qualified name of the given {@link INamed named thing}.
+ */
+const qualifiedNameOf = <T extends INamed & Node>(node: T, separator = "."): string =>
+    concatenateNamesOf(separator, containmentChain(node).reverse() as M3Concept[])
+
+
+/**
+ * @return the {@link INamed named things} in this {@link Language language}
+ *  (excluding the language itself)
+ */
+const namedsOf = (language: Language): M3Concept[] =>
+    allContaineds(language).filter(isINamed)
+
+
+/**
+ * @return the key of the given {@link INamed named thing}.
+ */
+const keyOf = <T extends IKeyed>({key}: T): LionWebKey =>
+    key
+
+
+type ConcreteClassifier = Concept | Annotation
+
+
+/**
+ * Determines whether the given {@link LanguageEntity metamodel element} is
+ * *concrete*, i.e. is instantiable.
+ */
+const isConcrete = (thing: LanguageEntity): thing is ConcreteClassifier =>
+    (thing instanceof Concept && !thing.abstract) || (thing instanceof Annotation)
+
+/**
+ * Determines whether the given {@link LanguageEntity metamodel element} is a {@link Concept concept}
+ * which is a partition.
+ */
+const isPartition = (thing: LanguageEntity): thing is Concept =>
+    thing instanceof Concept && thing.partition
+
+/**
+ * @return an array of {@link Classifier classifiers} that it **directly** inherits from.
+ */
+const inheritsDirectlyFrom = (classifier: Classifier): Classifier[] => {
+    if (classifier instanceof Concept || classifier instanceof Annotation) {
+        return [
+            ...(
+                isRef(classifier.extends)
+                    ? [classifier.extends as Classifier]
+                    : []
+            ),
+            ...classifier.implements
+        ]
+    }
+    if (classifier instanceof Interface) {
+        return classifier.extends
+    }
+    throw new Error(`classifier type ${typeof classifier} not handled`)
+}
+
+/**
+ * Alias for {@link inheritsDirectlyFrom}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+const inheritsFrom = inheritsDirectlyFrom;
+
+/**
+ * @return an array that's either an inheritance cycle, or empty (meaning: no inheritance cycle).
+ */
+const inheritanceCycleWith = (classifier: Classifier) =>
+    cycleWith(classifier, inheritsDirectlyFrom)
+
+/**
+ * Alias for {@link inheritanceCycleWith}, kept for backward compatibility, and to be deprecated and removed later.
+ */
+const inheritedCycleWith = inheritanceCycleWith;
+
+/**
+ * @return *all* super types (through `extends` or `implements`) of the given {@link Classifier classifier}.
+ */
+const allSuperTypesOf = (classifier: Classifier): Classifier[] =>
+    flatMapNonCyclingFollowing(inheritsDirectlyFrom, inheritsDirectlyFrom)(classifier)
+
+
+/**
+ * @return *all* {@link Feature features} of the given {@link Classifier classifier},
+ * including the inherited ones.
+ */
+const allFeaturesOf = (classifier: Classifier): Feature[] =>
+    flatMapNonCyclingFollowing((ci) => ci.features, inheritsDirectlyFrom)(classifier)
+
+
+/**
+ * Determines whether the given {@link LanguageEntity language element} is an {@link Enumeration enumeration}.
+ */
+const isEnumeration = (element: LanguageEntity): element is Enumeration =>
+    element instanceof Enumeration
+
+
+/**
+ * @return a function that looks up a classifier from the given {@link Language language} by its ID.
+ */
+const idBasedClassifierDeducerFor = (language: Language) =>
+    (id: LionWebId) =>
+        language.entities.find((element) => element instanceof Classifier && element.id === id) as Classifier
+
+/**
+ * @return a function that looks up a classifier from the given {@link Language language} by its name.
+ */
+const nameBasedClassifierDeducerFor = (language: Language) =>
+    (name: string) =>
+        language.entities.find((element) => element instanceof Classifier && element.name === name) as Classifier
+
+
+/**
+ * @return a {@link ClassifierDeducer classifier deducer} that deduces the classifier of nodes by looking up
+ * the classifier in the given {@link Language language} by matching the node object's class name to classifiers' names.
+ * **Note** that this is not reliable when using bundlers who might minimize class names, and such.
+ */
+const classBasedClassifierDeducerFor = <NT extends Node>(language: Language): ClassifierDeducer<NT> =>
+    (node: NT) => nameBasedClassifierDeducerFor(language)(node.constructor.name)
+
+
+/**
+ * @return a {@link ClassifierDeducer classifier deducer} that deduces the classifier of nodes that implement {@link IMetaTyped}
+ * by looking up the classifier in the given {@link Language language} by matching the result of {@link IMetaTyped#metaType}
+ * to classifiers' names.
+ */
+const metaTypedBasedClassifierDeducerFor = <NT extends Node & IMetaTyped>(language: Language): ClassifierDeducer<NT> =>
+    (node: NT) => nameBasedClassifierDeducerFor(language)(node.metaType())
+
+
+/**
+ * @return all {@link Concept concepts} defined in the given {@link Language language}.
+ */
+const conceptsOf = (language: Language): Concept[] =>
+    language.entities.filter((entity) => entity instanceof Concept) as Concept[]
+
+
+const isInstantiableClassifier = (entity: LanguageEntity): boolean =>
+       entity instanceof Annotation
+    || (entity instanceof Concept && !entity.abstract)
+    // leaves out Interface and Concept { abstract: true }
+
+/**
+ * @return an array of all instantiable {@link Classifier classifiers} of the given {@link Language language}.
+ */
+const instantiableClassifiersOf = (language: Language): Classifier[] =>
+    language.entities.filter(isInstantiableClassifier) as Classifier[]
+
+
+/**
+ * @return whether the two given {@link Classifiers classifiers} are the same (/identical by meta-pointer).
+ */
+const areSameClassifiers = (left: Classifier, right: Classifier) =>
+    (left === right) || (
+        areSameLanguages(left.language, right.language) && left.key === right.key
+    )
+
+/**
+ * @return whether the two given {@link Language languages} are the same (/identical by meta-pointer).
+ */
+const areSameLanguages = (left: Language, right: Language) =>
+    (left === right) || (
+        left.key === right.key && left.version === right.version
+    )
+
+
+export {
+    allContaineds,
+    allFeaturesOf,
+    allSuperTypesOf,
+    areSameClassifiers,
+    areSameLanguages,
+    classBasedClassifierDeducerFor,
+    concatenateNamesOf,
+    conceptsOf,
+    containmentChain,
+    directlyContaineds,
+    featureMetaType,
+    flatMap,
+    idBasedClassifierDeducerFor,
+    inheritanceCycleWith,
+    inheritedCycleWith,
+    inheritsFrom,
+    inheritsDirectlyFrom,
+    instantiableClassifiersOf,
+    isConcrete,
+    isContainment,
+    isEnumeration,
+    isMultiple,
+    isPartition,
+    isProperty,
+    isReference,
+    keyOf,
+    metaTypedBasedClassifierDeducerFor,
+    nameBasedClassifierDeducerFor,
+    nameOf,
+    namedsOf,
+    nonRelationalFeatures,
+    relations,
+    relationsOf,
+    type,
+    qualifiedNameOf
+}
+
+export type {
+    FeatureMetaType
+}
+

package/src/m3/index.ts

@@ -0,0 +1,12 @@
+export * from "./builtins.js"
+export * from "./constraints.js"
+export * from "./deserializer.js"
+export * from "./facade.js"
+export * from "./factory.js"
+export * from "./feature-resolvers.js"
+export * from "./functions.js"
+export * from "./lioncore.js"
+export * from "./reference-checker.js"
+export * from "./serializer.js"
+export * from "./symbol-table.js"
+export * from "./types.js"