@sap/cds-compiler 2.10.4 → 2.12.0

package/lib/compiler/definer.js

@@ -88,7 +88,7 @@
 // Sub Phase 2 (initXYZ)
 //  - set _parent, _main (later: _service?) links, and _block links of members
 //  - add _subArtifacts dictionary and "namespace artifacts" for name resolution
-//  - duplicate checks (TODO - currently via preProcessArtifact in definer)
+//  - duplicate checks
 //  - structure checks ?
 //  - annotation assignments
 //  - POST: resolvePath() can be called for artifact references (if complete model)
@@ -101,9 +101,11 @@
 //    to avoid consequential or repeated errors.
 //  - But: The same artifact is added to multiple dictionaries.
 //  - Solution part 1: $duplicates as property of the artifact or member
-//    for 'definitions', '_artifacts' and member dictionaries.
-//  - Solution part 2: array value in dictionary for duplicates in CDL 'artifacts'
-//    dictionary, also used for `_combined` in query search dictionary.
+//    for `definitions`, `_artifacts`, member dictionaries, `vocabulary`
+//    dictionary of the whole model, `$tableAliases` dictionary of queries.
+//  - Solution part 2: array value in dictionary for duplicates in CDL `artifacts`
+//    dictionary, `_combined` dictionary for query search, `$tableAliases`
+//    of JOIN restrictions, `vocabulary` dictionary of a CDL input source.
 
 'use strict';
 
@@ -111,7 +113,7 @@ const { searchName, weakLocation } = require('../base/messages');
 const {
   isDeprecatedEnabled, isBetaEnabled,
   setProp, forEachGeneric, forEachInOrder,
-  forEachMember, forEachDefinition,
+  forEachDefinition,
   forEachMemberRecursivelyWithQuery,
 } = require('../base/model');
 const {
@@ -120,20 +122,21 @@ const {
 const {
   dictLocation,
 } = require('../base/location');
+const { kindProperties, dictKinds } = require('./base');
 const {
-  annotationVal, annotationIsFalse, annotateWith,
-} = require('./utils');
-const {
-  dictKinds,
-  kindProperties,
-  fns,
+  annotationVal,
+  annotationIsFalse,
+  annotateWith,
   linkToOrigin,
   setMemberParent,
   storeExtension,
   dependsOnSilent,
-} = require('./shared');
+  pathName,
+  augmentPath,
+  splitIntoPath,
+} = require('./utils');
 const { compareLayer, layer } = require('./moduleLayers');
-const { initBuiltins } = require('./builtins');
+const { initBuiltins, isInReservedNamespace } = require('./builtins');
 const setLink = setProp;
 
 /**
@@ -148,7 +151,7 @@ const setLink = setProp;
  *
  * @param {XSN.Model} model Model with `sources` property that contain AST-like CSNs.
  */
-function getDefinerFunctions( model ) {
+function define( model ) {
   const { options } = model;
   // Get simplified "resolve" functionality and the message function:
   const {
@@ -160,24 +163,29 @@ function getDefinerFunctions( model ) {
     resolveTypeArguments,
     defineAnnotations,
     attachAndEmitValidNames,
-  } = fns( model );
-  const extensionsDict = Object.create(null);
-  let addTextsLanguageAssoc = false;
-
-  return {
-    define,
+  } = model.$functions;
+  Object.assign( model.$functions, {
     initArtifact,
     lateExtensions,
     projectionAncestor,
     hasTruthyProp,
+  } );
+  // During the definer, we can only resolve artifact references, i.e,
+  // after a `.`, we only search in the `_subArtifacts` dictionary:
+  model.$volatileFunctions.environment = function artifactsEnv( art ) {
+    return art._subArtifacts || Object.create(null);
   };
 
+  const extensionsDict = Object.create(null);
+  let addTextsLanguageAssoc = false;
+  return doDefine();
+
   /**
    * Main function of the definer.
    *
    * @returns {XSN.Model}
    */
-  function define() {
+  function doDefine() {
     if (options.deprecated &&
         messages.every( m => m.messageId !== 'api-deprecated-option' )) {
       warning( 'api-deprecated-option', {},
@@ -206,8 +214,6 @@ function getDefinerFunctions( model ) {
 
     if (options.parseCdl) {
       initExtensionsWithoutApplying();
-      // Check for redefinitions
-      Object.keys( model.definitions ).forEach( preProcessArtifact );
       // If no extensions shall be applied then we can skip further
       // artifact processing and return the model with an `extensions` property.
       return model;
@@ -215,7 +221,6 @@ function getDefinerFunctions( model ) {
 
     applyExtensions();
 
-    Object.keys( model.definitions ).forEach( preProcessArtifact );
     const commonLanguagesEntity // TODO: remove beta after a grace period
         = (options.addTextsLanguageAssoc || isBetaEnabled( options, 'addTextsLanguageAssoc' )) &&
           model.definitions['sap.common.Languages'];
@@ -238,13 +243,13 @@ function getDefinerFunctions( model ) {
    * @param {XSN.AST} src
    */
   function addSource( src ) {
-    // handle sub model from CSN parser
+    // handle sub model from parser
     if (!src.kind)
       src.kind = 'source';
 
     let namespace = src.namespace && src.namespace.path;
     let prefix = namespace ? `${ pathName( namespace ) }.` : '';
-    if (prefix.startsWith( 'cds.') && !prefix.match(/^cds\.foundation(\.|$)/)) {
+    if (isInReservedNamespace(prefix)) {
       error( 'reserved-namespace-cds', [ src.namespace.location, src.namespace ], {},
              // TODO: use $(NAME)
              'The namespace "cds" is reserved for CDS builtins' );
@@ -280,8 +285,7 @@ function getDefinerFunctions( model ) {
   function addDefinition( art, block ) {
     const { absolute } = art.name;
     // TODO: check reserved, see checkName()/checkLocalizedObjects() of checks.js
-    if (absolute === 'cds' ||
-        absolute.startsWith( 'cds.') && !absolute.match(/^cds\.foundation(\.|$)/)) {
+    if (absolute === 'cds' || isInReservedNamespace(absolute)) {
       error( 'reserved-namespace-cds', [ art.name.location, art ], {},
              // TODO: use $(NAME)
              'The namespace "cds" is reserved for CDS builtins' );
@@ -305,7 +309,7 @@ function getDefinerFunctions( model ) {
     }
     else {
       setLink( art, '_block', block );
-      // dictAdd might set $duplicates to true if def in other source
+      // dictAdd might set $duplicates to true
       dictAdd( model.definitions, absolute, art );
       return true;
     }
@@ -366,7 +370,7 @@ function getDefinerFunctions( model ) {
     // TODO: check name: no "."
     if (path[0].id === 'localized' || path[0].id.startsWith( 'localized.' )) {
       decl.$inferred = 'LOCALIZED-IGNORED';
-      warning( 'using-localized-view', [ path.location, decl ], {},
+      warning( 'using-localized-view', [ decl.location, decl ], {},
                'Localization views can\'t be referred to - ignored USING' );
       // actually not ignored anymore
     }
@@ -444,6 +448,23 @@ function getDefinerFunctions( model ) {
 
   // Phase 2 ("init") --------------------------------------------------------
 
+  function checkRedefinition( art ) {
+    if (!art.$duplicates)
+      return;
+    if (art._main) {
+      error( 'duplicate-definition', [ art.name.location, art ], {
+        name: art.name.id,
+        '#': kindProperties[art.kind].normalized || art.kind,
+      } );
+    }
+    else {
+      error( 'duplicate-definition', [ art.name.location, art ], {
+        name: art.name.absolute,
+        '#': (art.kind === 'annotation' ? 'annotation' : 'absolute' ),
+      } );
+    }
+  }
+
   function initNamespaceAndUsing( src ) {
     if (src.namespace) {
       const decl = src.namespace;
@@ -488,6 +509,7 @@ function getDefinerFunctions( model ) {
     if (!reInit)
       initParentLink( art, model.definitions );
     const block = art._block;
+    checkRedefinition( art );
     defineAnnotations( art, art, block );
     initMembers( art, art, block );
     initDollarSelf( art );      // $self
@@ -513,6 +535,7 @@ function getDefinerFunctions( model ) {
 
   function initVocabulary( art ) {
     initParentLink( art, model.vocabularies );
+    checkRedefinition( art );
     const block = art._block;
     defineAnnotations( art, art, block );
     initMembers( art, art, block );
@@ -554,20 +577,6 @@ function getDefinerFunctions( model ) {
 
   // From here til EOF, reexamine code ---------------------------------------
 
-  // currently called from preProcessArtifact(), do be called in "init"
-  function checkRedefinitions( obj, name, prop ) {
-    forEachMember( obj, checkRedefinitions, obj.targetAspect );
-    if (!obj.$duplicates)
-      return;
-    if (obj.name.location.file === '<built-in>') {
-      // builtin types like namespace 'cds' or namespace 'localized' shouldn't be printed.
-      // The error shall only be printed for the user-defined conflicting artifact.
-      return;
-    }
-    error( 'duplicate-definition', [ obj.name.location, obj ],
-           { name, '#': (obj.kind === 'namespace') ? 'namespace' : dictKinds[prop] } );
-  }
-
   function initDollarSelf( art ) {
     const selfname = '$self';
     // TODO: use setMemberParent() ?
@@ -774,12 +783,13 @@ function getDefinerFunctions( model ) {
       setMemberParent( table, table.name.id, query );
       setProp( table, '_block', query._block );
       dictAdd( query.$tableAliases, table.name.id, table, ( name, loc ) => {
-        error( 'duplicate-definition', [ loc, table ], { name, '#': '$tableAlias' } );
+        error( 'duplicate-definition', [ loc, table ], { name, '#': 'alias' } );
       } );
       // also add to JOIN nodes for name restrictions:
       for (const p of joinParents) {
-        // console.log('ADD:', query.name.id, parents.length, p)
-        dictAdd( p.$tableAliases, table.name.id, table );
+        // for JOIN alias restriction, we cannot use $duplicates, as it is
+        // already used for duplicate aliases of queries:
+        dictAddArray( p.$tableAliases, table.name.id, table );
       }
       if (table.name.id[0] === '$') {
         warning( 'syntax-dollar-ident', [ table.name.location, table ], {
@@ -793,8 +803,8 @@ function getDefinerFunctions( model ) {
 
   // art is:
   // - entity for top-level queries (including UNION args)
-  // - $tableAlias for sub query in FROM
-  // - $query for real sub query (in columns, WHERE, ...)
+  // - $tableAlias for sub query in FROM - TODO: what about UNION there?
+  // - $query for real sub query (in columns, WHERE, ...), again: what about UNION there?
   function initQueryExpression( query, art ) {
     if (!query)                 // parse error
       return query;
@@ -846,7 +856,7 @@ function getDefinerFunctions( model ) {
       query.kind = 'select';
       query.name = { location: query.location };
       setMemberParent( query, main.$queries.length + 1, main );
-      // console.log(JSON.stringify(query.name))
+      // console.log(art.kind,art.name,query.name,query._$next.name)
       // if (query.name.query === 1 && query.name.absolute === 'S') throw Error();
       main.$queries.push( query );
       setProp( query, '_parent', art ); // _parent should point to alias/main/query
@@ -866,7 +876,7 @@ function getDefinerFunctions( model ) {
           // assignments on the mixin... (also for future mixin definitions
           // with generated values)
           dictAdd( query.$tableAliases, name, query.mixin[name], ( dupName, loc ) => {
-            error( 'duplicate-definition', [ loc, query ], { name: dupName, '#': '$tableAlias' } );
+            error( 'duplicate-definition', [ loc, query ], { name: dupName, '#': 'alias' } );
           } );
           if (mixin.name.id[0] === '$') {
             warning( 'syntax-dollar-ident', [ mixin.name.location, mixin ],
@@ -993,6 +1003,7 @@ function getDefinerFunctions( model ) {
       setProp( elem, '_block', bl );
       setMemberParent( elem, name, parent, construct !== parent && prop );
       // console.log(message( null, elem.location, elem, {}, 'Info', 'INIT').toString())
+      checkRedefinition( elem );
       defineAnnotations( elem, elem, bl );
       initMembers( elem, elem, bl, initExtensions );
 
@@ -1141,7 +1152,8 @@ function getDefinerFunctions( model ) {
         break;                  // only direct projection for auto-exposed
     }
     let ancestors = art && (!autoexposed && art._ancestors || []);
-    for (const a of chain.reverse()) {
+    chain.reverse();
+    for (const a of chain) {
       ancestors = (ancestors ? [ ...ancestors, art ] : []);
       setProp( a, '_ancestors', ancestors );
       art = a;
@@ -1263,6 +1275,9 @@ function getDefinerFunctions( model ) {
     }
   }
 
+  /**
+   * @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
@@ -1330,7 +1345,7 @@ function getDefinerFunctions( model ) {
       name: { path: splitIntoPath( location, entityName ), absolute: entityName, location },
       location,
       elements,
-      $inferred: 'aspect-composition',
+      $inferred: 'composition-entity',
     };
     if (target.name) {          // named target aspect
       setLink( art, '_origin', target );
@@ -1509,8 +1524,15 @@ function getDefinerFunctions( model ) {
       forEachMemberRecursivelyWithQuery(art, checkArtifact);
     }
 
-    // Function for parse.cdl
-    /** @param {XSN.Artifact} artifact */
+    /**
+     * Function for parse.cdl.
+     * This parse.cdl function resolves types inside the artifact ("resolveTypeUnchecked").
+     *
+     * @todo This function needs to be properly reworked because at the moment we simply
+     *       added checks as issues arose (e.g. for "artifact.value").
+     *
+     * @param {XSN.Artifact} artifact
+     * */
     function checkArtifact( artifact ) {
       // columns are initialized (and made to elements) in the resolver - do init here
       for (const col of artifact.columns || []) {
@@ -1521,11 +1543,21 @@ function getDefinerFunctions( model ) {
           recursivelyResolveExpressionCastTypes(col.value, artifact);
       }
 
+      // Possible inside expand/inline
+      if (artifact.value)
+        recursivelyResolveExpressionCastTypes(artifact.value, artifact);
+
       resolveTypeUnchecked(artifact, artifact);
 
       if (artifact.items)
         resolveTypeUnchecked(artifact.items, artifact);
 
+      if (Array.isArray(artifact.expand))
+        artifact.expand.forEach(art => checkArtifact(art));
+
+      if (Array.isArray(artifact.inline))
+        artifact.inline.forEach(art => checkArtifact(art));
+
       for (const include of (artifact.includes || []))
         resolveUncheckedPath(include, 'include', artifact);
 
@@ -1958,24 +1990,6 @@ function getDefinerFunctions( model ) {
     }
   }
 
-  // TODO: move to "init" phase
-  /**
-   * Check whether redefinitions of the given artifact name exist and
-   * adapt to `targetAspect`.
-   *
-   * @param {string} name
-   */
-  function preProcessArtifact( name ) {
-    const art = model.definitions[name];
-    if (Array.isArray(art.$duplicates)) {
-      // A definition name containing a `.` is not invalid (TODO: starting or
-      // ending with a dot is invalid and could be checked here)
-      for (const a of art.$duplicates)
-        checkRedefinitions( a, name, 'definitions' );
-    }
-    checkRedefinitions( art, name, 'definitions' );
-  }
-
   /**
    * Process "composition of" artifacts.
    *
@@ -2111,7 +2125,7 @@ function getDefinerFunctions( model ) {
       name: { path: splitIntoPath( location, absolute ), absolute, location },
       location: base.location,
       elements,
-      $inferred: 'localized',
+      $inferred: 'localized-entity',
     };
     const locale = {
       name: { location, id: 'locale' },
@@ -2212,7 +2226,7 @@ function getDefinerFunctions( model ) {
       name: { location, id: 'texts' },
       kind: 'element',
       location,
-      $inferred: 'localized-texts',
+      $inferred: 'localized',
       type: augmentPath( location, 'cds.Composition' ),
       cardinality: { targetMax: { literal: 'string', val: '*', location }, location },
       target: augmentPath( location, textsName ),
@@ -2227,7 +2241,7 @@ function getDefinerFunctions( model ) {
       name: { location, id: 'localized' },
       kind: 'element',
       location,
-      $inferred: 'localized-texts',
+      $inferred: 'localized',
       type: augmentPath( location, 'cds.Association' ),
       target: augmentPath( location, textsName ),
       on: augmentEqual( location, 'localized', keys ),
@@ -2316,36 +2330,6 @@ function mergeI18nBlocks( model ) {
   }
 }
 
-/**
- * Return string 'A.B.C' for parsed source `A.B.C` (is vector of ids with
- * locations).
- *
- * @param {XSN.Path} path
- */
-function pathName(path) {
-  return path.map( id => id.id ).join('.');
-}
-
-/**
- * Generates an XSN path out of the given name. Path segments are delimited by a dot.
- * Each segment will have the given location assigned.
- *
- * @param {CSN.Location} location
- * @param {string} name
- * @returns {XSN.Path}
- */
-function splitIntoPath( location, name ) {
-  return name.split('.').map( id => ({ id, location }) );
-}
-
-/**
- * @param {CSN.Location} location
- * @param  {...any} args
- */
-function augmentPath( location, ...args ) {
-  return { path: args.map( id => ({ id, location }) ), location };
-}
-
 function augmentEqual( location, assocname, relations, prefix = '' ) {
   const args = relations.map( eq );
   return (args.length === 1)
@@ -2374,9 +2358,4 @@ function augmentEqual( location, assocname, relations, prefix = '' ) {
 // these function could be used to a future lib/compiler/utils.js, but DO NOT
 // SHARE with utility functions for CSN processors
 
-module.exports = {
-  define: model => getDefinerFunctions( model ).define(),
-  getDefinerFunctions,
-  augmentPath,
-  splitIntoPath,
-};
+module.exports = { define };

package/lib/compiler/index.js

@@ -1,5 +1,17 @@
 // Main XSN-based compiler functions
 
+// ...
+
+// How functions are shared across the Core Compiler sub modules:
+
+// - Shared XSN-related functions which do not use a context are in utils.js,
+//   they are `require`d as usual at the beginning of sub modules.
+// - The XSN is the only context which context-dependent functions can depend on.
+// - Sharing such a function is by adding it to `‹xsn›.$functions`,
+//   e.g. `resolvePath` and similar will be attached to the XSN.
+// - Functions which might be overwritten in a next sub module
+//   are added to `‹xsn›.$volatileFunctions`, currently just `environment`.
+
 'use strict';
 
 const { resolveModule, resolveModuleSync } = require('../utils/moduleResolve');
@@ -8,12 +20,12 @@ const parseCsn = require('../json/from-csn');
 
 const assertConsistency = require('./assert-consistency');
 const moduleLayers = require('./moduleLayers');
+const { fns } = require('./shared');
 const { define } = require('./definer');
 const resolve = require('./resolver');
 const propagator = require('./propagator');
 const check = require('./checks');
 
-
 const { emptyWeakLocation } = require('../base/location');
 const { createMessageFunctions, deduplicateMessages } = require('../base/messages');
 const { promiseAllDoNotRejectImmediately } = require('../base/node-helpers');
@@ -52,7 +64,7 @@ class ArgumentError extends Error {
  * @param {object} options Compile options
  * @param {object} messageFunctions If not provided, parse errors will not lead to an exception
  */
-function parseX( source, filename, options = {}, messageFunctions ) {
+function parseX( source, filename, options = {}, messageFunctions = null ) {
   if (!messageFunctions)
     messageFunctions = createMessageFunctions( options, 'parse' );
   const ext = path.extname( filename ).toLowerCase();
@@ -110,7 +122,6 @@ function compileX( filenames, dir = '', options = {}, fileCache = Object.create(
   //   fileCache = Object.assign( Object.create(null), fileCache );
   dir = path.resolve(dir);
   const a = processFilenames( filenames, dir );
-  a.fileContentDict = Object.create(null);
 
   const model = { sources: a.sources, options };
   model.$messageFunctions = createMessageFunctions( options, 'compile', model );
@@ -132,37 +143,25 @@ function compileX( filenames, dir = '', options = {}, fileCache = Object.create(
   });
 
   // Read file `filename` and parse its content, return messages
-  function readAndParse( filename ) {
+  async function readAndParse( filename ) {
+    const { sources } = a;
     if ( filename === false )   // module which has not been found
       return [];
-    const rel = a.sources[filename] || path.relative( dir, filename );
+    const rel = sources[filename] || path.relative( dir, filename );
     if (typeof rel === 'object') // already parsed
       return [];                 // no further dependency processing
     // no parallel readAndParse with same resolved filename should read the file,
-    // also ensure deterministic sequence in a.sources:
-    a.sources[filename] = { location: { file: rel } };
+    // also ensure deterministic sequence in sources:
+    sources[filename] = { location: { file: rel } };
 
-    return new Promise( (fulfill, reject) => {
-      cdsFs( fileCache, options.traceFs ).readFile( filename, 'utf8', (err, source) => {
-        if (err) {
-          reject(err);
-        }
-        else {
-          try {
-            a.fileContentDict[filename] = source;
-            const ast = parseX( source, rel, options, model.$messageFunctions );
-            a.sources[filename] = ast;
-            ast.location = { file: rel };
-            ast.dirname = path.dirname( filename );
-            assertConsistency( ast, options );
-            fulfill( ast );
-          }
-          catch (e) {
-            reject( e );
-          }
-        }
-      });
-    });
+    const source = await cdsFs( fileCache, options.traceFs ).readFileAsync( filename, 'utf8' );
+    const ast = parseX( source, rel, options, model.$messageFunctions );
+    sources[filename] = ast;
+    ast.location = { file: rel };
+    ast.dirname = path.dirname( filename );
+    assertConsistency( ast, options );
+
+    return ast;
   }
 
   // Combine the parse results (if there are not file IO errors)
@@ -220,7 +219,6 @@ function compileSyncX( filenames, dir = '', options = {}, fileCache = Object.cre
   // absolute file names - they start with `/` or `\` or similar
   dir = path.resolve(dir);
   const a = processFilenames( filenames, dir );
-  a.fileContentDict = Object.create(null);
 
   const model = { sources: a.sources, options };
   model.$messageFunctions = createMessageFunctions( options, 'compile', model );
@@ -281,7 +279,6 @@ function compileSyncX( filenames, dir = '', options = {}, fileCache = Object.cre
       }
       else {
         try {
-          a.fileContentDict[filename] = source;
           const ast = parseX( source, rel, options, model.$messageFunctions );
           a.sources[filename] = ast;
           ast.location = { file: rel };
@@ -416,6 +413,9 @@ function compileDoX( model ) {
     throwWithError();
     return model;
   }
+  model.$functions = {};
+  model.$volatileFunctions = {};
+  fns( model );                 // attach (mostly) paths functions
   define( model );
   // do not run the resolver in parse-cdl mode or we get duplicate annotations, etc.
   // TODO: do not use this function for parseCdl anyway…

package/lib/compiler/propagator.js

@@ -8,7 +8,7 @@ const {
   setProp,
   isDeprecatedEnabled,
 } = require( '../base/model');
-const { linkToOrigin, withAssociation } = require('./shared');
+const { linkToOrigin, withAssociation } = require('./utils');
 // const { refString } = require( '../base/messages')
 
 function propagate( model ) {
@@ -19,6 +19,8 @@ function propagate( model ) {
     '@cds.persistence.calcview': never,
     '@cds.persistence.udf': never,
     '@cds.persistence.skip': notWithPersistenceTable,
+    '@sql.prepend': never,
+    '@sql.append': never,
     '@Analytics.hidden': never,
     '@Analytics.visible': never,
     '@cds.autoexpose': onlyViaArtifact,
@@ -64,8 +66,7 @@ function propagate( model ) {
     if (!art)
       return;
     if (!checkAndSetStatus( art )) {
-      if ( art.status !== 'propagated')
-        runMembers( art );
+      runMembers( art );
       return;
     }
     // console.log('RUN:', art.name, art.elements ? Object.keys(art.elements) : 0)
@@ -179,6 +180,8 @@ function propagate( model ) {
   // accessed at their type being a main artifact
   function expensive( prop, target, source ) {
     // console.log(prop,source.name,'->',target.kind,target.name);
+    if (source.kind === 'builtin')
+      return;
     if (prop !== 'foreignKeys' && availableAtType( prop, target, source ))
       // foreignKeys must always be copied with target to avoid any confusion
       // whether we have to generated implicit keys
@@ -211,7 +214,8 @@ function propagate( model ) {
   }
 
   function onlyViaParent( prop, target, source ) {
-    if (target.$inferred === 'proxy') // assocs and enums do not have 'include'
+    if (target.$inferred === 'proxy' || target.$inferred === 'expand-element')
+      // assocs and enums do not have 'include'
       always( prop, target, source );
   }