@sap/cds-compiler 2.12.0 → 2.13.6

package/lib/compiler/extend.js

@@ -0,0 +1,983 @@
+// Extend, include, localized data and managed compositions
+
+// Is handled together in this file because people want to extend the generated
+// definitions in the future.
+
+'use strict';
+
+const { searchName, weakLocation } = require('../base/messages');
+const {
+  isDeprecatedEnabled, isBetaEnabled,
+  forEachGeneric, forEachInOrder,
+} = require('../base/model');
+const { dictAdd } = require('../base/dictionaries');
+const { kindProperties, dictKinds } = require('./base');
+const {
+  setLink,
+  setArtifactLink,
+  annotateWith,
+  linkToOrigin,
+  setMemberParent,
+  dependsOnSilent,
+  augmentPath,
+  splitIntoPath,
+} = require('./utils');
+const { compareLayer, layer } = require('./moduleLayers');
+
+function extend( model ) {
+  const { options } = model;
+  // Get simplified "resolve" functionality and the message function:
+  const {
+    message, error, warning, info,
+  } = model.$messageFunctions;
+  const {
+    resolvePath,
+    resolveUncheckedPath,
+    defineAnnotations,
+    attachAndEmitValidNames,
+    checkDefinitions,
+    initArtifact,
+    initMembers,
+    extensionsDict,             // not a function - TODO
+  } = model.$functions;
+
+  Object.assign( model.$functions, {
+    lateExtensions,
+  } );
+
+  applyExtensions();
+
+  const commonLanguagesEntity // TODO: remove beta after a grace period
+        = (options.addTextsLanguageAssoc || isBetaEnabled( options, 'addTextsLanguageAssoc' )) &&
+        model.definitions['sap.common.Languages'];
+  const addTextsLanguageAssoc = !!(commonLanguagesEntity && commonLanguagesEntity.elements &&
+                                   commonLanguagesEntity.elements.code);
+  Object.keys( model.definitions ).forEach( processArtifact );
+
+  lateExtensions( false );
+
+  /**
+   * Process "composition of" artifacts.
+   *
+   * @param {string} name
+   */
+  function processArtifact( name ) {
+    const art = model.definitions[name];
+    if (!(art.$duplicates)) {
+      processAspectComposition( art );
+      if (art.kind === 'entity' && !art.query && art.elements)
+        // check potential entity parse error
+        processLocalizedData( art );
+    }
+  }
+
+  /**
+   * @param {XSN.Definition} art
+   * @param {string} prop
+   */
+  function propagateEarly( art, prop ) {
+    if (art[prop])
+      return;
+    for (const ref of art.includes) {
+      const aspect = ref._artifact;
+      if (aspect) {
+        const anno = aspect[prop];
+        if (anno && (anno.val !== null || !art[prop]))
+          art[prop] = Object.assign( { $inferred: 'include' }, anno );
+      }
+    }
+  }
+
+  // extend ------------------------------------------------------------------
+
+  /**
+   * Apply the extensions inside the extensionsDict on the model.
+   *
+   * Phase 1: context extends, 2: extends with structure includes, 3: extends
+   * without structure includes (in the case of cyclic includes)
+   *
+   * Before phase 1: all artifact extensions have been collected (even those
+   * inside extend context), only "empty" ones from structure includes are still unknown.
+   * After phase 1, all main artifacts are known, also "empty" extensions are known.
+   */
+  function applyExtensions() {
+    let phase = 1;              // TODO: basically remove phase 1
+    let extNames = Object.keys( extensionsDict ).sort();
+    // Remark: The sort() makes sure that an extend for artifact C.E is applied
+    // after the extend for C has been applied (which could have defined C.E).
+    // Looping over model.definitions in Phase 1 would miss the `extend
+    // context` for a context C.C defined in an `extend context C`.
+    //
+    // TODO: no need to sort anymore
+    while (extNames.length) {
+      const { length } = extNames;
+      for (const name of extNames) {
+        const art = model.definitions[name];
+        if (!art || art.kind === 'namespace') {
+          model.$lateExtensions[name] = extensionsDict[name];
+          delete extensionsDict[name];
+        }
+        else if (art.$duplicates) { // cannot extend redefinitions
+          delete extensionsDict[name];
+        }
+        else if (phase === 1
+                 ? extendContext( name, art )
+                 : extendArtifact( extensionsDict[name], art, phase > 2 )) { // >2: no self-include
+          delete extensionsDict[name];
+        }
+      }
+      extNames = Object.keys( extensionsDict ); // no sort() required anymore
+      if (phase === 1)
+        phase = 2;
+      else if (extNames.length >= length)
+        phase = 3;
+    }
+  }
+
+  function extendContext( name, art ) {
+    // (ext.expectedKind == art.kind) already checked by parser except for context/service
+    if (!kindProperties[art.kind].artifacts) {
+      // no context or service => warn about context extensions
+      for (const ext of extensionsDict[name]) {
+        if (ext.expectedKind === 'context' || ext.expectedKind === 'service') {
+          const loc = ext.name.location;
+          // TODO: warning is enough
+          error( 'extend-with-artifacts', [ loc, ext ], { name, '#': ext.expectedKind }, {
+            std: 'Cannot extend non-context / non-service $(NAME) with artifacts',
+            service: 'Cannot extend non-service $(NAME) with artifacts',
+            context: 'Cannot extend non-context $(NAME) with artifacts',
+          });
+        }
+      }
+      return false;
+    }
+
+    for (const ext of extensionsDict[name]) {
+      setArtifactLink( ext.name, art );
+      checkDefinitions( ext, art, 'elements'); // error for elements etc
+      checkDefinitions( ext, art, 'enum');
+      checkDefinitions( ext, art, 'actions');
+      checkDefinitions( ext, art, 'params');
+      defineAnnotations( ext, art, ext._block, ext.kind );
+    }
+    return true;
+  }
+
+  /**
+   * Extend artifact `art` by `extensions`.  `noIncludes` can have values:
+   * - false: includes are applied, extend and annotate is performed
+   * - true:  includes are not applied, extend and annotate is performed
+   * - 'gen': no includes and no extensions allowed, annotate is performed
+   *
+   * @param {XSN.Extension[]} extensions
+   * @param {XSN.Definition} art
+   * @param {boolean|'gen'} [noIncludes=false]
+   */
+  function extendArtifact( extensions, art, noIncludes = false) {
+    if (!noIncludes && !(canApplyIncludes( art ) && extensions.every( canApplyIncludes )))
+      return false;
+    if (!art.query) {
+      model._entities.push( art ); // add structure with includes in dep order
+      art.$entity = ++model.$entity;
+    }
+    if (!noIncludes && art.includes)
+      applyIncludes( art, art );
+    extendMembers( extensions, art, noIncludes === 'gen' );
+    if (!noIncludes && art.includes) {
+      // early propagation of specific annotation assignments
+      propagateEarly( art, '@cds.autoexpose' );
+      propagateEarly( art, '@fiori.draft.enabled' );
+    }
+    // TODO: complain about element extensions inside projection
+    return true;
+  }
+
+  function extendMembers( extensions, art, noExtend ) {
+    // TODO: do the whole extension stuff lazily if the elements are requested
+    const elemExtensions = [];
+    extensions.sort( compareLayer );
+    for (const ext of extensions) {
+      // console.log(message( 'id', [ext.location, ext], { art: ext.name._artifact },
+      //                      'Info', 'EXT').toString())
+      if (!('_artifact' in ext.name)) { // not already applied
+        setArtifactLink( ext.name, art );
+        if (noExtend && ext.kind === 'extend') {
+          error( 'extend-for-generated', [ ext.name.location, ext ], { art },
+                 'You can\'t use EXTEND on the generated $(ART)' );
+          continue;
+        }
+        if (ext.includes) {
+          // TODO: currently, re-compiling from gensrc does not give the exact
+          // element sequence - we need something like
+          //    includes = ['Base1',3,'Base2']
+          // where 3 means adding the next 3 elements before applying include 'Base2'
+          if (art.includes)
+            art.includes.push(...ext.includes);
+          else
+            art.includes = [ ...ext.includes ];
+          applyIncludes( ext, art );
+        }
+        defineAnnotations( ext, art, ext._block, ext.kind );
+        // TODO: do we allow to add elements with array of {...}?  If yes, adapt
+        initMembers( ext, art, ext._block ); // might set _extend, _annotate
+        dependsOnSilent(art, ext); // art depends silently on ext (inverse to normal dep!)
+      }
+      for (const name in ext.elements) {
+        const elem = ext.elements[name];
+        if (elem.kind === 'element') { // i.e. not extend or annotate
+          elemExtensions.push( elem );
+          break;
+        }
+      }
+
+      if (ext.columns)          // extend projection
+        extendColumns( ext, art );
+    }
+    if (elemExtensions.length > 1)
+      reportUnstableExtensions( elemExtensions );
+
+    [ 'elements', 'actions' ].forEach( (prop) => {
+      const dict = art._extend && art._extend[prop];
+      for (const name in dict) {
+        let obj = art;
+        if (obj.targetAspect)
+          obj = obj.targetAspect;
+        while (obj.items)
+          obj = obj.items;
+        const validDict = obj[prop] || prop === 'elements' && obj.enum;
+        const member = validDict[name];
+        if (!member)
+          extendNothing( dict[name], prop, name, art, validDict );
+        else if (!(member.$duplicates))
+          extendMembers( dict[name], member );
+      }
+    });
+  }
+
+  /**
+   * Copy columns for EXTEND PROJECTION
+   *
+   * @param {XSN.Extension} ext
+   * @param {XSN.Artifact} art
+   */
+  function extendColumns( ext, art ) {
+    // TODO: consider reportUnstableExtensions
+    const { location } = ext.name;
+    const { query } = art;
+    if (!query) {
+      if (art.kind !== 'annotate')
+        error( 'extend-columns', [ location, ext ], { art } );
+      return;
+    }
+    if (!query.from || !query.from.path) {
+      error( 'extend-columns', [ location, ext ], { art } );
+    }
+    else {
+      if (!query.columns)
+        query.columns = [ { location, val: '*' } ];
+
+      for (const column of ext.columns) {
+        setLink( column, '_block', ext._block );
+        query.columns.push(column);
+      }
+    }
+  }
+
+  function reportUnstableExtensions( extensions ) {
+    // Report 'Warning: Unstable element order due to repeated extensions'.
+    // Similar to chooseAssignment(), TODO there: also extra intralayer message
+    // as this is a modeling error
+    let lastExt = null;
+    let open = [];              // the "highest" layers
+    for (const ext of extensions) {
+      const extLayer = layer( ext ) || { realname: '', _layerExtends: Object.create(null) };
+      if (!open.length) {
+        lastExt = ext;
+        open = [ extLayer.realname ];
+      }
+      else if (extLayer.realname === open[open.length - 1]) { // in same layer
+        if (lastExt) {
+          message( 'extend-repeated-intralayer', [ lastExt.location, lastExt ] );
+          lastExt = null;
+        }
+        message( 'extend-repeated-intralayer', [ ext.location, ext ] );
+      }
+      else {
+        if (lastExt && (open.length > 1 || !extLayer._layerExtends[open[0]])) {
+          // report for lastExt if that is unrelated to other open exts or current ext
+          message( 'extend-unrelated-layer', [ lastExt.location, lastExt ], {},
+                   'Unstable element order due to other extension in unrelated layer' );
+        }
+        lastExt = ext;
+        open = open.filter( name => !extLayer._layerExtends[name] );
+        open.push( extLayer.realname );
+      }
+    }
+  }
+  /**
+   * @param {XSN.Extension[]} extensions
+   * @param {string} prop
+   * @param {string} name
+   * @param {XSN.Artifact} art
+   * @param {object} validDict
+   */
+  function extendNothing( extensions, prop, name, art, validDict ) {
+    for (const ext of extensions) {
+      // TODO: use shared functionality with notFound in resolver.js
+      const { location } = ext.name;
+      const msg
+        = error( 'extend-undefined', [ location, ext ],
+                 { art: searchName( art, name, dictKinds[prop] ) },
+                 {
+                   std: 'Unknown $(ART) - nothing to extend',
+                   // eslint-disable-next-line max-len
+                   element: 'Artifact $(ART) has no element or enum $(MEMBER) - nothing to extend',
+                   action: 'Artifact $(ART) has no action $(MEMBER) - nothing to extend',
+                 } );
+      attachAndEmitValidNames(msg, validDict);
+    }
+  }
+
+  /**
+   * @param {Function|false} [veryLate]
+   */
+  function lateExtensions( veryLate ) {
+    for (const name in model.$lateExtensions) {
+      const art = model.definitions[name];
+      const exts = model.$lateExtensions[name];
+      if (art && art.kind !== 'namespace') {
+        if (art.builtin) {
+          for (const ext of exts)
+            info( 'anno-builtin', [ ext.name.location, ext ] );
+        }
+        // created texts entity, autoexposed entity
+        if (exts) {
+          extendArtifact( exts, art, 'gen' );
+          if (veryLate)
+            veryLate( art );
+          model.$lateExtensions[name] = null; // done
+        }
+      }
+      else if (veryLate) {
+        // Complain about unused extensions, i.e. those
+        // which do not point to a valid artifact
+        for (const ext of exts) {
+          delete ext.name.path[0]._artifact;      // get message for root
+          // TODO: make resolvePath('extend'/'annotate') ignore namespaces
+          if (resolvePath( ext.name, ext.kind, ext )) { // should issue error/info
+            // should issue error for cds extensions (annotate ok)
+            if (art.kind === 'namespace') {
+              info( 'anno-namespace', [ ext.name.location, ext ], {},
+                    'Namespaces can\'t be annotated' );
+            }
+            // Builtin annotations would be represented as annotations in to-csn.js
+            else if (art.builtin) {
+              info( 'anno-builtin', [ ext.name.location, ext ] );
+            }
+          }
+          // TODO: warning for context/service extension on non-correct
+          if (ext.kind === 'annotate')
+            delete ext.name._artifact; // make it be considered by extendArtifact()
+        }
+        // create "super" ANNOTATE containing all non-applied ones
+        const first = exts[0];
+        const { location } = first.name;
+
+        /** @type {XSN.Definition} */
+        const annotationArtifact = {
+          kind: 'annotate',
+          name: { path: [ { id: name, location } ], absolute: name, location },
+          location: first.location,
+        };
+
+        if (!model.extensions)
+          model.extensions = [];
+
+        model.extensions.push(annotationArtifact);
+        extendArtifact( exts, annotationArtifact ); // also sets _artifact link in extensions
+        // if one of the annotate statement mentions 'returns', assume it
+        // TODO: with warning/info?
+        for (const ext of exts) {
+          if (ext.$syntax === 'returns')
+            annotationArtifact.$syntax = 'returns';
+        }
+      }
+    }
+  }
+
+  // includes ----------------------------------------------------------------
+
+  /**
+   * @param {XSN.Definition} art
+   */
+  function canApplyIncludes( art ) {
+    if (art.includes) {
+      for (const ref of art.includes) {
+        const template = resolvePath( ref, 'include', art );
+        if (template && template.name.absolute in extensionsDict)
+          return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * @param {XSN.Extension} ext
+   * @param {XSN.Artifact} art
+   */
+  function applyIncludes( ext, art ) {
+    if (!art._ancestors)
+      setLink( art, '_ancestors', [] ); // recursive array of includes
+    for (const ref of ext.includes) {
+      const template = ref._artifact; // already resolved
+      if (template) {
+        if (template._ancestors)
+          art._ancestors.push( ...template._ancestors );
+        art._ancestors.push( template );
+      }
+    }
+    includeMembers( ext, 'elements', forEachInOrder, ext === art && art );
+    includeMembers( ext, 'actions', forEachGeneric, ext === art && art );
+  }
+
+  /**
+   * @param {XSN.Extension} ext
+   * @param {string} prop
+   * @param {function} forEach
+   * @param {XSN.Artifact} parent
+   */
+  function includeMembers( ext, prop, forEach, parent ) {
+    // TODO two kind of messages:
+    // Error 'More than one include defines element "A"' (at include ref)
+    // Warning 'Overwrites definition from include "I" (at elem def)
+    const members = ext[prop];
+    ext[prop] = Object.create(null); // TODO: do not set actions property if there are none
+    for (const ref of ext.includes) {
+      const template = ref._artifact; // already resolved
+      if (template) {           // be robust
+        forEach( template, prop, ( origin, name ) => {
+          if (members && name in members)
+            return;               // TODO: warning for overwritten element
+          const elem = linkToOrigin( origin, name, parent, prop, weakLocation( ref.location ) );
+          if (!parent)          // not yet set for EXTEND foo WITH bar
+            dictAdd( ext[prop], name, elem );
+          elem.$inferred = 'include';
+          if (origin.masked)
+            elem.masked = Object.assign( { $inferred: 'include' }, origin.masked );
+          if (origin.key)
+            elem.key = Object.assign( { $inferred: 'include' }, origin.key );
+          // TODO: also complain if elem is just defined in art
+        });
+      }
+    }
+    // TODO: expand elements having direct elements (if needed)
+    if (members) {
+      forEach( { [prop]: members }, prop, ( elem, name ) => {
+        dictAdd( ext[prop], name, elem );
+      });
+    }
+  }
+
+  // localized texts entities
+
+  /**
+   * @param {XSN.Artifact} art
+   */
+  function processLocalizedData( art ) {
+    const fioriAnno = art['@fiori.draft.enabled'];
+    const fioriEnabled = fioriAnno && (fioriAnno.val === undefined || fioriAnno.val);
+
+    const textsName = (isDeprecatedEnabled( options, 'generatedEntityNameWithUnderscore' ))
+      ? `${ art.name.absolute }_texts`
+      : `${ art.name.absolute }.texts`;
+    const textsEntity = model.definitions[textsName];
+    const localized = localizedData( art, textsEntity, fioriEnabled );
+    if (!localized)
+      return;
+    if (textsEntity)            // expanded localized data in source
+      return;                   // -> make it idempotent
+    createTextsEntity( art, textsName, localized, fioriEnabled );
+    addTextsAssociations( art, textsName, localized );
+  }
+
+  /**
+   * @param {XSN.Artifact} art
+   * @param {XSN.Artifact|undefined} textsEntity
+   * @param {boolean} fioriEnabled
+   */
+  function localizedData( art, textsEntity, fioriEnabled ) {
+    let keys = 0;
+    const textElems = [];
+    const conflictingElements = [];
+    const protectedElements = [ 'locale', 'texts', 'localized' ];
+    if (fioriEnabled)
+      protectedElements.push('ID_texts');
+    if (addTextsLanguageAssoc)
+      protectedElements.push('language');
+
+    for (const name in art.elements) {
+      const elem = art.elements[name];
+      if (elem.$duplicates)
+        return false;           // no localized-data unfold with redefined elems
+      if (protectedElements.includes( name ))
+        conflictingElements.push( elem );
+
+      const isKey = elem.key && elem.key.val;
+      const isLocalized = hasTruthyProp( elem, 'localized' );
+
+      if (isKey) {
+        keys += 1;
+        textElems.push( elem );
+      }
+      else if (isLocalized) {
+        textElems.push( elem );
+      }
+
+      if (isKey && isLocalized) { // key with localized is wrong - ignore localized
+        const errpos = elem.localized || elem.type || elem.name;
+        warning( 'localized-key', [ errpos.location, elem ], { keyword: 'localized' },
+                 'Keyword $(KEYWORD) is ignored for primary keys' );
+      }
+    }
+    if (textElems.length <= keys)
+      return false;
+
+    if (!keys) {
+      warning( null, [ art.name.location, art ], {},
+               'No texts entity can be created when no key element exists' );
+      return false;
+    }
+
+    if (textsEntity) {
+      if (textsEntity.$duplicates)
+        return false;
+      if (textsEntity.kind !== 'entity' || textsEntity.query ||
+          // already have elements "texts" and "localized" (and optionally ID_texts)
+          conflictingElements.length !== 2 || art.elements.locale ||
+          (fioriEnabled && art.elements.ID_texts)) {
+        // TODO if we have too much time: check all elements of texts entity for safety
+        warning( null, [ art.name.location, art ], { art: textsEntity },
+                 // eslint-disable-next-line max-len
+                 'Texts entity $(ART) can\'t be created as there is another definition with that name' );
+        info( null, [ textsEntity.name.location, textsEntity ], { art },
+              'Texts entity for $(ART) can\'t be created with this definition' );
+      }
+      else if (!art._block || art._block.$frontend !== 'json') {
+        info( null, [ art.name.location, art ], {},
+              'Localized data expansions has already been done' );
+        return textElems;       // make double-compilation even with after toHana
+      }
+      else if (!art._block.$withLocalized && !options.$recompile) {
+        art._block.$withLocalized = true;
+        info( 'recalculated-text-entities', [ art.name.location, null ], {},
+              'Input CSN contains expansions for localized data' );
+        return textElems;       // make compilation idempotent
+      }
+      else {
+        return textElems;
+      }
+    }
+    for (const elem of conflictingElements) {
+      warning( null, [ elem.name.location, art ], { name: elem.name.id },
+               'No texts entity can be created when element $(NAME) exists' );
+    }
+    return !textsEntity && !conflictingElements.length && textElems;
+  }
+
+  /**
+   * TODO: set _parent also for main artifacts!
+   *
+   * @param {XSN.Artifact} base
+   * @param {string} absolute
+   * @param {XSN.Element[]} textElems
+   * @param {boolean} fioriEnabled
+   */
+  function createTextsEntity( base, absolute, textElems, fioriEnabled ) {
+    const elements = Object.create(null);
+    const { location } = base.name;
+    const art = {
+      kind: 'entity',
+      name: { path: splitIntoPath( location, absolute ), absolute, location },
+      location: base.location,
+      elements,
+      $inferred: 'localized-entity',
+    };
+    const locale = {
+      name: { location, id: 'locale' },
+      kind: 'element',
+      type: augmentPath( location, 'cds.String' ),
+      length: { literal: 'number', val: 14, location },
+      location,
+    };
+
+    if (!fioriEnabled) {
+      locale.key = { val: true, location };
+      // To be compatible, we switch off draft without @fiori.draft.enabled
+      // TODO (next major version): remove?
+      annotateWith( art, '@odata.draft.enabled', art.location, false );
+    }
+    else {
+      const textId = {
+        name: { location, id: 'ID_texts' },
+        kind: 'element',
+        key: { val: true, location },
+        type: augmentPath( location, 'cds.UUID' ),
+        location,
+      };
+      dictAdd( art.elements, 'ID_texts', textId );
+    }
+    if (isDeprecatedEnabled( options, 'generatedEntityNameWithUnderscore' ))
+      setLink( art, '_base', base );
+
+    dictAdd( art.elements, 'locale', locale );
+    if (addTextsLanguageAssoc) {
+      const language = {
+        name: { location, id: 'language' },
+        kind: 'element',
+        location,
+        type: augmentPath( location, 'cds.Association' ),
+        target: augmentPath( location, 'sap.common.Languages' ),
+        on: {
+          op: { val: '=', location },
+          args: [
+            { path: [ { id: 'language', location }, { id: 'code', location } ], location },
+            { path: [ { id: 'locale', location } ], location },
+          ],
+          location,
+        },
+      };
+      setLink( language, '_block', model.$internal );
+      dictAdd( art.elements, 'language', language );
+    }
+    setLink( art, '_block', model.$internal );
+    model.definitions[absolute] = art;
+    initArtifact( art );
+
+    // assertUnique array value, first entry is 'locale'
+    const assertUniqueValue = [ {
+      path: [ { id: locale.name.id, location: locale.location } ],
+      location: locale.location,
+    } ];
+
+    for (const orig of textElems) {
+      const elem = linkToOrigin( orig, orig.name.id, art, 'elements' );
+      if (orig.key && orig.key.val) {
+        // elem.key = { val: fioriEnabled ? null : true, $inferred: 'localized', location };
+        // TODO: the previous would be better, but currently not supported in toCDL
+        if (!fioriEnabled) {
+          elem.key = { val: true, $inferred: 'localized', location };
+          // If the propagated elements remain key (that is not fiori.draft.enabled)
+          // they should be omitted from OData containment EDM
+          annotateWith( elem, '@odata.containment.ignore', location );
+        }
+        else {
+          // add the former key paths to the unique constraint
+          assertUniqueValue.push({
+            path: [ { id: orig.name.id, location: orig.location } ],
+            location: orig.location,
+          });
+        }
+      }
+      if (hasTruthyProp( orig, 'localized' )) { // use location of LOCALIZED keyword
+        const localized = orig.localized || orig.type || orig.name;
+        elem.localized = { val: null, $inferred: 'localized', location: localized.location };
+      }
+    }
+    if (fioriEnabled)
+      annotateWith( art, '@assert.unique.locale', art.location, assertUniqueValue, 'array' );
+  }
+
+  /**
+   * @param {XSN.Artifact} art
+   * @param {string} textsName
+   * @param {XSN.Element[]} textElems
+   */
+  function addTextsAssociations( art, textsName, textElems ) {
+    // texts : Composition of many Books.texts on texts.ID=ID;
+    /** @type {array} */
+    const keys = textElems.filter( e => e.key && e.key.val );
+    const { location } = art.name;
+    const texts = {
+      name: { location, id: 'texts' },
+      kind: 'element',
+      location,
+      $inferred: 'localized',
+      type: augmentPath( location, 'cds.Composition' ),
+      cardinality: { targetMax: { literal: 'string', val: '*', location }, location },
+      target: augmentPath( location, textsName ),
+      on: augmentEqual( location, 'texts', keys ),
+    };
+    setMemberParent( texts, 'texts', art, 'elements' );
+    setLink( texts, '_block', model.$internal );
+    // localized : Association to Books.texts on
+    //             localized.ID=ID and localized.locale = $user.locale;
+    keys.push( [ 'localized.locale', '$user.locale' ] );
+    const localized = {
+      name: { location, id: 'localized' },
+      kind: 'element',
+      location,
+      $inferred: 'localized',
+      type: augmentPath( location, 'cds.Association' ),
+      target: augmentPath( location, textsName ),
+      on: augmentEqual( location, 'localized', keys ),
+    };
+    setMemberParent( localized, 'localized', art, 'elements' );
+    setLink( localized, '_block', model.$internal );
+  }
+
+  /**
+   * @param {XSN.Artifact} art
+   * @param {string} prop
+   */
+  function hasTruthyProp( art, prop ) {
+    // Returns whether art directly or indirectly has the property 'prop',
+    // following the 'origin' and the 'type' (not involving elements).
+    //
+    // TODO: we should issue a warning if we get localized via TYPE OF
+    // TODO XSN: for anno short form, use { val: true, location, <no literal prop> }
+    // ...then this function also works with annotations
+    const processed = Object.create(null); // avoid infloops with circular refs
+    let name = art.name.absolute;        // is ok, since no recursive type possible
+    while (art && !processed[name]) {
+      if (art[prop])
+        return art[prop].val;
+      processed[name] = art;
+      if (art._origin) {
+        art = art._origin;
+        if (!art.name)          // anonymous aspect
+          return false;
+        name = art && art.name.absolute;
+      }
+      else if (art.type && art._block && art.type.scope !== 'typeOf') {
+        // TODO: also do something special for TYPE OF inside `art`s own elements
+        name = resolveUncheckedPath( art.type, 'type', art );
+        art = name && model.definitions[name];
+      }
+      else {
+        return false;
+      }
+    }
+    return false;
+  }
+
+  // managed composition of aspects ------------------------------------------
+
+  function processAspectComposition( base ) {
+    // TODO: we need to forbid COMPOSITION of entity w/o keys and ON anyway
+    // TODO: consider entity includes
+    // TODO: nested containment
+    // TODO: better do circular checks in the aspect!
+    if (base.kind !== 'entity' || base.query)
+      return;
+    const keys = baseKeys();
+    if (keys)
+      forEachGeneric( base, 'elements', expand ); // TODO: recursively here?
+    return;
+
+    function baseKeys() {
+      const k = Object.create(null);
+      for (const name in base.elements) {
+        const elem = base.elements[name];
+        if (elem.$duplicates)
+          return false;           // no composition-of-type unfold with redefined elems
+        if (elem.key && elem.key.val)
+          k[name] = elem;
+      }
+      return k;
+    }
+
+    function expand( elem ) {
+      if (elem.target)
+        return;
+      let origin = elem;
+      // included element do not have target aspect directly
+      while (origin && !origin.targetAspect && origin._origin)
+        origin = origin._origin;
+      let target = origin.targetAspect;
+      if (target && target.path)
+        target = resolvePath( origin.targetAspect, 'compositionTarget', origin );
+      if (!target || !target.elements)
+        return;
+      const entityName = (isDeprecatedEnabled( options, 'generatedEntityNameWithUnderscore' ))
+        ? `${ base.name.absolute }_${ elem.name.id }`
+        : `${ base.name.absolute }.${ elem.name.id }`;
+      const entity = allowAspectComposition( target, elem, keys, entityName ) &&
+            createTargetEntity( target, elem, keys, entityName, base );
+      elem.target = {
+        location: (elem.targetAspect || elem).location,
+        $inferred: 'aspect-composition',
+      };
+      setArtifactLink( elem.target, entity );
+      if (entity) {
+        model.$compositionTargets[entity.name.absolute] = true;
+        processAspectComposition( entity );
+        processLocalizedData( entity );
+      }
+    }
+  }
+
+  /**
+   * @returns {boolean|0} `true`, if allowed, `false` if forbidden, `0` if circular containment.
+   */
+  function allowAspectComposition( target, elem, keys, entityName ) {
+    if (!target.elements || Object.values( target.elements ).some( e => e.$duplicates ))
+      return false;             // no elements or with redefinitions
+    const location = elem.target && elem.target.location || elem.location;
+    if ((elem._main._upperAspects || []).includes( target ))
+      return 0;               // circular containment of the same aspect
+
+    const keyNames = Object.keys( keys );
+    if (!keyNames.length) {
+      // TODO: for "inner aspect-compositions", signal already in type
+      error( null, [ location, elem ], { target },
+             'An aspect $(TARGET) can\'t be used as target in an entity without keys' );
+      return false;
+    }
+    // if (keys.up_) {  // only to be tested if we allow to provide a prefix, which could be ''
+    //   // Cannot be in an "inner aspect-compositions" as it would already be wrong before
+    //   // TODO: if anonymous type, use location of "up_" element
+    //   // FUTURE: add sub info with location of "up_" element
+    //   message( 'id', [location, elem], { target, name: 'up_' }, 'Error',
+    //      'An aspect $(TARGET) can't be used as target in an entity with a key named $(NAME)' );
+    //   return false;
+    // }
+    if (target.elements.up_) {
+      // TODO: for "inner aspect-compositions", signal already in type
+      // TODO: if anonymous type, use location of "up_" element
+      // FUTURE: if named type, add sub info with location of "up_" element
+      error( null, [ location, elem ], { target, name: 'up_' },
+             'An aspect $(TARGET) with an element named $(NAME) can\'t be used as target' );
+      return false;
+    }
+    if (model.definitions[entityName]) {
+      error( null, [ location, elem ], { art: entityName },
+             // eslint-disable-next-line max-len
+             'Target entity $(ART) can\'t be created as there is another definition with this name' );
+      return false;
+    }
+    const names = Object.keys( target.elements )
+      .filter( n => n.startsWith('up__') && keyNames.includes( n.substring(4) ) );
+    if (names.length) {
+      // FUTURE: if named type, add sub info with location of "up_" element
+      error( null, [ location, elem ], { target: entityName, names }, {
+        std: 'Key elements $(NAMES) can\'t be added to $(TARGET) as these already exist',
+        one: 'Key element $(NAMES) can\'t be added to $(TARGET) as it already exist',
+      });
+      return false;
+    }
+    return true;
+  }
+
+  function createTargetEntity( target, elem, keys, entityName, base ) {
+    const { location } = elem.targetAspect || elem.target || elem;
+    elem.on = {
+      location,
+      op: { val: '=', location },
+      args: [
+        augmentPath( location, elem.name.id, 'up_' ),
+        augmentPath( location, '$self' ),
+      ],
+      $inferred: 'aspect-composition',
+    };
+
+    const elements = Object.create(null);
+    const art = {
+      kind: 'entity',
+      name: { path: splitIntoPath( location, entityName ), absolute: entityName, location },
+      location,
+      elements,
+      $inferred: 'composition-entity',
+    };
+    if (target.name) {          // named target aspect
+      setLink( art, '_origin', target );
+      setLink( art, '_upperAspects', [ target, ...(elem._main._upperAspects || []) ] );
+    }
+    else {
+      setLink( art, '_origin', target );
+      // TODO: do we need to give the anonymous target aspect a kind and name?
+      setLink( art, '_upperAspects', elem._main._upperAspects || [] );
+    }
+
+    const up = { // elements.up_ = ...
+      name: { location, id: 'up_' },
+      kind: 'element',
+      location,
+      $inferred: 'aspect-composition',
+      type: augmentPath( location, 'cds.Association' ),
+      target: augmentPath( location, base.name.absolute ),
+      cardinality: {
+        targetMin: { val: 1, literal: 'number', location },
+        targetMax: { val: 1, literal: 'number', location },
+        location,
+      },
+    };
+    // By default, 'up_' is a managed primary key association.
+    // If 'up_' shall be rendered unmanaged, infer the parent
+    // primary keys and add the ON condition
+    if (isDeprecatedEnabled( options, 'unmanagedUpInComponent' )) {
+      addProxyElements( art, keys, 'aspect-composition', target.name && location,
+                        'up__', '@odata.containment.ignore' );
+      up.on = augmentEqual( location, 'up_', Object.values( keys ), 'up__' );
+    }
+    else {
+      up.key = { location, val: true };
+      // managed associations must be explicitly set to not null
+      // even if target cardinality is 1..1
+      up.notNull = { location, val: true };
+    }
+    if (isDeprecatedEnabled( options, 'generatedEntityNameWithUnderscore' ))
+      setLink( art, '_base', base._base || base );
+
+    dictAdd( art.elements, 'up_', up);
+    addProxyElements( art, target.elements, 'aspect-composition', target.name && location );
+
+    setLink( art, '_block', model.$internal );
+    model.definitions[entityName] = art;
+    initArtifact( art );
+    return art;
+  }
+
+  function addProxyElements( proxyDict, elements, inferred, location, prefix = '', anno = '' ) {
+    // TODO: also use for includeMembers()?
+    for (const name in elements) {
+      const pname = `${ prefix }${ name }`;
+      const origin = elements[name];
+      const proxy = linkToOrigin( origin, pname, null, null, location || origin.location );
+      proxy.$inferred = inferred;
+      if (origin.masked)
+        proxy.masked = Object.assign( { $inferred: 'include' }, origin.masked );
+      if (origin.key)
+        proxy.key = Object.assign( { $inferred: 'include' }, origin.key );
+      if (anno)
+        annotateWith( proxy, anno );
+      dictAdd( proxyDict.elements, pname, proxy );
+    }
+  }
+}
+
+function augmentEqual( location, assocname, relations, prefix = '' ) {
+  const args = relations.map( eq );
+  return (args.length === 1)
+    ? args[0]
+    : { op: { val: 'and', location }, args, location };
+
+  function eq( refs ) {
+    if (Array.isArray(refs))
+      return { op: { val: '=', location }, args: refs.map( ref ), location };
+
+    const { id } = refs.name;
+    return {
+      op: { val: '=', location },
+      args: [
+        { path: [ { id: assocname, location }, { id, location } ], location },
+        { path: [ { id: `${ prefix }${ id }`, location } ], location },
+      ],
+      location,
+    };
+  }
+  function ref( path ) {
+    return { path: path.split('.').map( id => ({ id, location }) ), location };
+  }
+}
+
+module.exports = extend;