@lionweb/core 0.7.0-beta.18 → 0.7.0-beta.19

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"

package/src/m3/lioncore.ts

@@ -0,0 +1,139 @@
+import { currentReleaseVersion } from "../version.js"
+import { builtinClassifiers, builtinPrimitives } from "./builtins.js"
+import { LanguageFactory } from "./factory.js"
+
+const lioncoreKey = "LionCore-M3"
+
+const factory = new LanguageFactory(
+    "LionCore_M3",
+    currentReleaseVersion,
+    (...names) => "-id-" + (names.length === 1 ? lioncoreKey : names.slice(1).join("-")),
+    (...names) => names.slice(1).join("-")
+)
+/*
+ * ID: `-id-${key}`
+ * key: qualified name _without_ "LionCore_M3", dash-separated
+ */
+
+/**
+ * Definition of LionCore in terms of itself.
+ */
+export const lioncore = factory.language.havingKey("LionCore-M3")
+
+const { inamed } = builtinClassifiers
+const { booleanDataType, stringDataType } = builtinPrimitives
+
+const ikeyed = factory.interface("IKeyed").extending(inamed)
+
+const ikeyed_key = factory.property(ikeyed, "key").ofType(stringDataType)
+
+const feature = factory.concept("Feature", true).implementing(ikeyed)
+
+const feature_optional = factory.property(feature, "optional").ofType(booleanDataType)
+
+const property = factory.concept("Property", false, feature)
+
+const property_type = factory.reference(property, "type")
+
+const link = factory.concept("Link", true, feature)
+
+const link_multiple = factory.property(link, "multiple").ofType(booleanDataType)
+
+const link_type = factory.reference(link, "type")
+
+const containment = factory.concept("Containment", false, link)
+
+const reference = factory.concept("Reference", false, link)
+
+const languageEntity = factory.concept("LanguageEntity", true).implementing(ikeyed)
+
+const classifier = factory.concept("Classifier", true, languageEntity)
+
+const classifier_features = factory.containment(classifier, "features").isOptional().isMultiple().ofType(feature)
+
+link_type.ofType(classifier)
+
+const annotation = factory.concept("Annotation", false, classifier)
+
+const annotation_annotates = factory.reference(annotation, "annotates").isOptional().ofType(classifier)
+
+const annotation_extends = factory.reference(annotation, "extends").isOptional().ofType(annotation)
+
+const annotation_implements = factory.reference(annotation, "implements").isMultiple().isOptional()
+
+const concept = factory.concept("Concept", false, classifier)
+
+const concept_abstract = factory.property(concept, "abstract").ofType(booleanDataType)
+
+const concept_partition = factory.property(concept, "partition").ofType(booleanDataType)
+
+const concept_extends = factory.reference(concept, "extends").isOptional().ofType(concept)
+
+const concept_implements = factory.reference(concept, "implements").isOptional().isMultiple()
+
+const interface_ = factory.concept("Interface", false, classifier)
+
+const interface_extends = factory.reference(interface_, "extends").isOptional().isMultiple().ofType(interface_)
+
+annotation_implements.ofType(interface_)
+concept_implements.ofType(interface_)
+
+const dataType = factory.concept("DataType", true, languageEntity)
+
+property_type.ofType(dataType)
+
+const primitiveType = factory.concept("PrimitiveType", false, dataType)
+
+const enumeration = factory.concept("Enumeration", false, dataType)
+
+const enumeration_literals = factory.containment(enumeration, "literals").isMultiple().isOptional()
+
+const enumerationLiteral = factory.concept("EnumerationLiteral", false).implementing(ikeyed)
+
+enumeration_literals.ofType(enumerationLiteral)
+
+const language = factory.concept("Language", false).implementing(ikeyed).isPartition()
+
+const language_version = factory.property(language, "version").ofType(stringDataType)
+
+const language_entities = factory.containment(language, "entities").isOptional().isMultiple().ofType(languageEntity)
+
+const language_dependsOn = factory.reference(language, "dependsOn").isOptional().isMultiple().ofType(language)
+
+export const metaConcepts = {
+    annotation,
+    classifier,
+    concept,
+    interface: interface_,
+    containment,
+    enumeration,
+    enumerationLiteral,
+    ikeyed,
+    language,
+    primitiveType,
+    property,
+    reference
+}
+
+export const metaFeatures = {
+    annotation_annotates,
+    annotation_extends,
+    annotation_implements,
+    classifier_features,
+    concept_abstract,
+    concept_partition,
+    concept_extends,
+    concept_implements,
+    interface_extends,
+    enumeration_literals,
+    feature_optional,
+    ikeyed_key,
+    language_dependsOn,
+    language_entities,
+    language_version,
+    link_multiple,
+    link_type,
+    property_type
+}
+
+export { lioncoreKey }

package/src/m3/reference-checker.ts

@@ -0,0 +1,38 @@
+import { SingleRef, unresolved } from "../references.js"
+import { flatMap, qualifiedNameOf } from "./functions.js"
+import { Concept, Containment, Language, Property, Reference } from "./types.js"
+
+
+/**
+ * Checks whether the metamodel of the given language contains unresolved references.
+ */
+export const checkReferences = (language: Language): string[] =>
+    flatMap(
+        language,
+        (thing) => {
+
+            const locations: string[] = []
+            const check = (ref: SingleRef<unknown>, location: string) => {
+                if (ref === unresolved) {
+                    locations.push(location)
+                }
+            }
+
+            if (thing instanceof Concept) {
+                check(thing.extends, `<Concept>${qualifiedNameOf(thing)}#extends`)
+            }
+            if (thing instanceof Containment) {
+                check(thing.type, `<Containment>${qualifiedNameOf(thing)}#type`)
+            }
+            if (thing instanceof Property) {
+                check(thing.type, `<Property>${qualifiedNameOf(thing)}#type`)
+            }
+            if (thing instanceof Reference) {
+                check(thing.type, `<Reference>${qualifiedNameOf(thing)}#type`)
+            }
+
+            return locations
+        }
+    )
+// TODO (#8)  make this generic, parametrized by a {@link Metamodel}
+

package/src/m3/serializer.ts

@@ -0,0 +1,13 @@
+import { LionWebJsonChunk } from "@lionweb/json"
+import { nodeSerializer } from "../serializer.js"
+import { lioncoreReader } from "./facade.js"
+import { Language } from "./types.js"
+
+
+/**
+ * Serializes languages (i.e., instances of the LionCore metametamodel, using {@link M3Concept these type definitions})
+ * into the LionWeb serialization JSON format.
+ */
+export const serializeLanguages = (...languages: Language[]): LionWebJsonChunk =>
+    nodeSerializer(lioncoreReader)(languages)
+

package/src/m3/symbol-table.ts

@@ -0,0 +1,119 @@
+import { LionWebJsonMetaPointer, LionWebKey } from "@lionweb/json"
+import { lazyMapGet } from "@lionweb/ts-utils"
+import { allFeaturesOf } from "./functions.js"
+import { Classifier, Feature, Language, LanguageEntity } from "./types.js"
+
+
+/**
+ * Interface for objects that can look up within languages, based on given {@link LionWebJsonMetaPointer meta pointers}.
+ * This is meant to be able to properly encapsulate performance optimizations, also outside of the context
+ * of deserialization.
+ */
+interface SymbolTable {
+
+    /**
+     * Looks up the {@link Language}, as pointed to by the given language key and version.
+     */
+    languageMatching(key: LionWebKey, version: string): Language | undefined
+
+    /**
+     * Looks up the {@link LanguageEntity}, as pointed to by the given {@link LionWebJsonMetaPointer},
+     * or {@code undefined} if it couldn't be found.
+     */
+    entityMatching(entityMetaPointer: LionWebJsonMetaPointer): LanguageEntity | undefined
+
+    /**
+     * Looks up the {@link Feature}, as pointed to by the {@link LionWebJsonMetaPointer} given second,
+     * as a feature of the {@link Classifier}, as pointed to by the {@link LionWebJsonMetaPointer} given first,
+     * or {@code undefined} it it couldn't be found.
+     * <em>Note</em> that the {@code language} and {@code version} values of both {@link LionWebJsonMetaPointer}-typed arguments should coincide,
+     * although this is typically not checked!
+     */
+    featureMatching(entityMetaPointer: LionWebJsonMetaPointer, featureMetaPointer: LionWebJsonMetaPointer): Feature | undefined
+
+}
+
+
+type EntityInfo = {
+    entity: LanguageEntity
+    allFeatures: Feature[]                                      // === [] if entity is not a Classifier
+    featureKey2feature: { [featureKey: LionWebKey]: Feature }   // populated through memoisation
+}
+
+class MemoisingSymbolTable implements SymbolTable {
+
+    private readonly languages: Language[]
+
+    constructor(languages: Language[]) {
+        this.languages = languages
+    }
+
+    private readonly languageKey2version2language: { [languageKey: LionWebKey]: { [version: string]: Language } } = {}
+
+    languageMatching = (languageKey: LionWebKey, version: string): Language | undefined =>
+        lazyMapGet(
+            lazyMapGet(this.languageKey2version2language, languageKey, () => ({})),
+            version,
+            () => this.languages.find((language) =>
+                   language.key === languageKey
+                && language.version === version
+            )
+        )
+
+
+    private readonly languageKey2version2entityKey2entityInfo: { [languageKey: LionWebKey]: { [version: string]: { [entityKey: LionWebKey]: (EntityInfo | undefined) } } } = {}
+
+    private entityInfoMatching = (entityMetaPointer: LionWebJsonMetaPointer): undefined | EntityInfo =>
+        lazyMapGet(
+            lazyMapGet(
+                lazyMapGet(this.languageKey2version2entityKey2entityInfo, entityMetaPointer.language, () => ({})),
+                entityMetaPointer.version,
+                () => ({})
+            ),
+            entityMetaPointer.key,
+            () => {
+                const entity = this.languageMatching(entityMetaPointer.language, entityMetaPointer.version)
+                    ?.entities
+                    .find((entity) => entity.key === entityMetaPointer.key)
+                return entity === undefined
+                    ? undefined
+                    : {
+                        entity,
+                        allFeatures: entity instanceof Classifier ? allFeaturesOf(entity) : [], featureKey2feature: {}
+                }
+            }
+        )
+
+    entityMatching = (entityMetaPointer: LionWebJsonMetaPointer): LanguageEntity | undefined =>
+        this.entityInfoMatching(entityMetaPointer)?.entity
+
+    /**
+     * Looks up the {@link LanguageEntity}, as pointed to by the given {@link LionWebJsonMetaPointer},
+     * and @returns all its {@link Feature features} or an empty array if it couldn't be found.
+     */
+    allFeaturesOfEntityMatching = (entityMetaPointer: LionWebJsonMetaPointer): Feature[] =>
+        this.entityInfoMatching(entityMetaPointer)?.allFeatures ?? []
+
+    featureMatching(classifierMetaPointer: LionWebJsonMetaPointer, featureMetaPointer: LionWebJsonMetaPointer): Feature | undefined {
+        const entityInfo = this.entityInfoMatching(classifierMetaPointer)
+        if (entityInfo === undefined || !(entityInfo.entity instanceof Classifier)) {
+            return undefined
+        }
+        return lazyMapGet(
+            entityInfo.featureKey2feature,
+            featureMetaPointer.key,
+            () => entityInfo.allFeatures.find((feature) => feature.key === featureMetaPointer.key)
+        )
+    }
+
+}
+
+
+export type {
+    SymbolTable
+}
+
+export {
+    MemoisingSymbolTable
+}
+