@sap/cds-compiler 3.4.2 → 3.5.0

package/lib/compiler/extend.js

@@ -20,7 +20,7 @@ const {
   setMemberParent,
   dependsOnSilent,
   augmentPath,
-  splitIntoPath,
+  splitIntoPath, isDirectComposition,
 } = require('./utils');
 const layers = require('./moduleLayers');
 const { typeParameters } = require('./builtins');
@@ -53,10 +53,9 @@ function extend( model ) {
 
   applyExtensions();
 
-  const commonLanguagesEntity = options.addTextsLanguageAssoc &&
-    model.definitions['sap.common.Languages'];
-  const addTextsLanguageAssoc = !!(commonLanguagesEntity && commonLanguagesEntity.elements &&
-                                   commonLanguagesEntity.elements.code);
+  const addTextsLanguageAssoc = checkTextsLanguageAssocOption(model, options);
+  const useTextsAspects = checkTextsAspects();
+
   Object.keys( model.definitions ).forEach( processArtifact );
 
   lateExtensions( false );
@@ -107,7 +106,7 @@ function extend( model ) {
     const processed = new WeakSet();
     forEachDefinition(model, processCompositionPersistence);
 
-    function processCompositionPersistence(def) {
+    function processCompositionPersistence( def ) {
       if (def.$inferred === 'composition-entity' && !processed.has(def)) {
         if (def._parent)
           processCompositionPersistence(def._parent);
@@ -207,7 +206,7 @@ function extend( model ) {
    * @param {XSN.Definition} art
    * @param {boolean|'gen'} [noIncludes=false]
    */
-  function extendArtifact( extensions, art, noIncludes = false) {
+  function extendArtifact( extensions, art, noIncludes = false ) {
     if (!noIncludes && !(canApplyIncludes( art, art ) &&
         extensions.every( ext => canApplyIncludes(ext, art) )))
       return false;
@@ -295,6 +294,97 @@ function extend( model ) {
     });
   }
 
+  /**
+   * Check that special `sap.common.*` aspects for `.texts` entities are
+   * consistent with compiler expectations.  Emits messages and returns
+   * false if the aspects are not valid.
+   *
+   * @return {boolean}
+   */
+  function checkTextsAspects() {
+    const textsAspect = model.definitions['sap.common.TextsAspect'];
+    const fioriTextsAspect = model.definitions['sap.common.FioriTextsAspect'];
+
+    let hasError = false;
+
+    if (textsAspect) {
+      const specialElements = { locale: { key: true } };
+      if (!checkTextsAspect(textsAspect, specialElements))
+        hasError = true;
+    }
+
+    if (fioriTextsAspect) {
+      const specialElements = { ID_texts: { key: true }, locale: { key: false } };
+      if (!checkTextsAspect(fioriTextsAspect, specialElements))
+        hasError = true;
+    }
+
+    return !hasError;
+  }
+
+  function checkTextsAspect( art, specialElements ) {
+    if (art.kind !== 'aspect' || !art.elements) {
+      error('def-invalid-texts-aspect', [ art.name.location, art ], { '#': 'no-aspect', art });
+      return false;
+    }
+
+    let hasError = false;
+    if (addTextsLanguageAssoc && art.elements.language) {
+      const lang = art.elements.language;
+      error('def-unexpected-element', [ lang.name.location, lang ],
+            { option: 'addTextsLanguageAssoc', art, name: 'language' },
+            // eslint-disable-next-line max-len
+            '$(ART) is not used because option $(OPTION) conflicts with existing element $(NAME); remove either option or element' );
+      hasError = true;
+    }
+
+    for (const name in specialElements) {
+      const expected = specialElements[name];
+      const elem = art.elements[name];
+      if (!elem) {
+        error('def-invalid-texts-aspect', [ art.name.location, art ],
+              { '#': 'missing', art, name });
+        hasError = true;
+      }
+      else if (expected.key !== undefined && !!elem.key?.val !== expected.key) {
+        const loc = elem.key?.location || elem.name?.location || art.name.location;
+        error('def-invalid-texts-aspect', [ loc, elem ],
+              { '#': expected.key ? 'key' : 'no-key', art: elem });
+        hasError = true;
+      }
+    }
+
+    if (hasError) // avoid subsequent errors, if the special elements are already wrong
+      return false;
+
+    for (const name in art.elements) {
+      const elem = art.elements[name];
+      const include = elem.$inferred === 'include';
+      if (!specialElements[name] && elem.key) {
+        const loc = include ? elem.location : elem.key.location;
+        error( 'def-unexpected-key', [ loc, elem ],
+               { '#': !include ? 'std' : 'include', art } );
+        hasError = true;
+      }
+      else if (hasTruthyProp( elem, 'localized' )) {
+        // TODO: T:loc, i.e. "localized" from other type (needs resolver?)
+        //       Not supported anyway, but important for recompilation (which fails correctly).
+        const loc = elem.localized?.location || elem.location;
+        error( 'def-unexpected-localized', [ loc, elem ],
+               { '#': !include ? 'std' : 'include', art } );
+        hasError = true;
+      }
+      else if (elem.targetAspect) {
+        error( 'def-unexpected-composition', [ elem.targetAspect.location, elem ], { art },
+               '$(ART) can\'t have composition of aspects' );
+        hasError = true;
+      }
+    }
+
+    return !hasError;
+  }
+
+
   /**
    * Copy columns for EXTEND PROJECTION
    *
@@ -332,7 +422,7 @@ function extend( model ) {
    *
    * @param art
    */
-  function applyTypeExtensions(art) {
+  function applyTypeExtensions( art ) {
     /**
      * Contains the previous extension for each property that was applied
      * successfully.
@@ -616,7 +706,7 @@ function extend( model ) {
   function applyIncludes( ext, art ) {
     if (kindProperties[art.kind].include !== true) {
       error('extend-unexpected-include', [ ext.includes[0]?.location, ext ],
-            { kind: art.kind });
+            { meta: art.kind });
       return;
     }
 
@@ -698,9 +788,8 @@ function extend( model ) {
       return;
     if (textsEntity)            // expanded localized data in source
       return;                   // -> make it idempotent
-    const newTextsEntity = createTextsEntity( art, textsName, localized, fioriEnabled );
+    createTextsEntity( art, textsName, localized, fioriEnabled );
     addTextsAssociations( art, textsName, localized );
-    copyPersistenceAnnotations(newTextsEntity, art, options);
   }
 
   /**
@@ -716,6 +805,9 @@ function extend( model ) {
     let keys = 0;
     const textElems = [];
     const conflictingElements = [];
+    // These elements are required or the localized-mechanism does not work.
+    // Other elements from sap.common.TextsAspect may be "overridden" as per
+    // usual include-mechanism.
     const protectedElements = [ 'locale', 'texts', 'localized' ];
     if (fioriEnabled)
       protectedElements.push('ID_texts');
@@ -742,7 +834,7 @@ function extend( model ) {
 
       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' },
+        warning( 'def-ignoring-localized-key', [ errpos.location, elem ], { keyword: 'localized' },
                  'Keyword $(KEYWORD) is ignored for primary keys' );
       }
     }
@@ -750,7 +842,7 @@ function extend( model ) {
       return false;
 
     if (!keys) {
-      warning( null, [ art.name.location, art ], {},
+      warning( 'def-expecting-key', [ art.name.location, art ], {},
                'No texts entity can be created when no key element exists' );
       return false;
     }
@@ -800,46 +892,15 @@ function extend( model ) {
    * @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',
-    };
-    // If there is a type `sap.common.Locale`, then use it as the type for the element `locale`.
-    // If not, use the default `cds.String` with a length of 14.
-    const hasLocaleType = model.definitions['sap.common.Locale'] &&
-      model.definitions['sap.common.Locale'].kind === 'type';
-    const locale = {
-      name: { location, id: 'locale' },
-      kind: 'element',
-      type: augmentPath( location, hasLocaleType ? 'sap.common.Locale' : 'cds.String' ),
-      location,
-    };
-    if (!hasLocaleType)
-      locale.length = { literal: 'number', val: 14, location };
+    const name = (fioriEnabled ? 'sap.common.FioriTextsAspect' : 'sap.common.TextsAspect');
+    const withTextsAspect = useTextsAspects && model.definitions[name];
 
-    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 );
-    }
+    const art = withTextsAspect
+      ? createTextsEntityWithInclude( base, absolute, fioriEnabled )
+      : createTextsEntityWithDefaultElements( base, absolute, fioriEnabled );
+
+    const { location } = base.name;
 
-    dictAdd( art.elements, 'locale', locale );
     if (addTextsLanguageAssoc) {
       const language = {
         name: { location, id: 'language' },
@@ -859,15 +920,9 @@ function extend( model ) {
       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,
-    } ];
+    const assertUniqueValue = [];
 
     for (const orig of textElems) {
       const elem = linkToOrigin( orig, orig.name.id, art, 'elements' );
@@ -893,8 +948,114 @@ function extend( model ) {
         elem.localized = { val: null, $inferred: 'localized', location: localized.location };
       }
     }
-    if (fioriEnabled)
+
+    initArtifact( art );
+    if (art.includes) {
+      // add elements `locale`, etc. which are required below.
+      applyIncludes(art, art);
+    }
+
+    if (fioriEnabled ) {
+      const { locale } = art.elements;
+      assertUniqueValue.unshift({
+        path: [ { id: locale.name.id, location: locale.location } ],
+        location: locale.location,
+      });
       annotateWith( art, '@assert.unique.locale', art.location, assertUniqueValue, 'array' );
+    }
+
+    copyPersistenceAnnotations(art, base, options);
+    return art;
+  }
+
+  /**
+   * Create the `.texts` entity for the given base artifact.
+   * In contrast to createTextsEntityWithDefaultElements(), this one creates
+   * an include for `sap.common.TextsAspect`.
+   *
+   * Does NOT apply the include!
+   *
+   * TODO: When beta flag textsAspect is removed, update caller-site and remove old coding.
+   *
+   * @param {XSN.Artifact} base
+   * @param {string} absolute
+   * @param {boolean} fioriEnabled
+   */
+  function createTextsEntityWithInclude( base, absolute, fioriEnabled ) {
+    const elements = Object.create(null);
+    const { location } = base.name;
+
+    const include = fioriEnabled ? 'sap.common.FioriTextsAspect' : 'sap.common.TextsAspect';
+    const art = {
+      kind: 'entity',
+      name: { path: splitIntoPath( location, absolute ), absolute, location },
+      includes: [ createInclude( include, base.location ) ],
+      location: base.location,
+      elements,
+      $inferred: 'localized-entity',
+    };
+
+    if (!fioriEnabled) {
+      // To be compatible, we switch off draft without @fiori.draft.enabled
+      // TODO (next major version): remove?
+      annotateWith( art, '@odata.draft.enabled', art.location, false );
+    }
+
+    if (addTextsLanguageAssoc && art.elements.language)
+      art.elements.language = undefined; // TODO: Message? Ignore?
+
+    setLink( art, '_block', model.$internal );
+    model.definitions[absolute] = art;
+    return art;
+  }
+
+  /**
+   * @param {XSN.Artifact} base
+   * @param {string} absolute
+   * @param {boolean} fioriEnabled
+   */
+  function createTextsEntityWithDefaultElements( base, absolute, 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',
+    };
+    // If there is a type `sap.common.Locale`, then use it as the type for the element `locale`.
+    // If not, use the default `cds.String` with a length of 14.
+    const hasLocaleType = model.definitions['sap.common.Locale']?.kind === 'type';
+    const locale = {
+      name: { location, id: 'locale' },
+      kind: 'element',
+      type: augmentPath( location, hasLocaleType ? 'sap.common.Locale' : 'cds.String' ),
+      location,
+    };
+    if (!hasLocaleType)
+      locale.length = { literal: 'number', val: 14, 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 );
+    }
+
+    dictAdd( art.elements, 'locale', locale );
+    setLink( art, '_block', model.$internal );
+    model.definitions[absolute] = art;
 
     return art;
   }
@@ -937,6 +1098,22 @@ function extend( model ) {
     setLink( localized, '_block', model.$internal );
   }
 
+  /**
+   * Create a structure that can be used as an item in `includes`.
+   *
+   * @param {string} name
+   * @param {XSN.Location} location
+   */
+  function createInclude( name, location ) {
+    const include = {
+      path: [ { id: name, location } ],
+      location,
+    };
+    setArtifactLink( include.path[0], model.definitions[name] );
+    setArtifactLink( include, model.definitions[name] );
+    return include;
+  }
+
   /**
    * Returns whether `art` directly or indirectly has the property 'prop',
    * following the 'origin' and the 'type' (not involving elements).
@@ -1086,6 +1263,15 @@ function extend( model ) {
       });
       return false;
     }
+
+    if (elem.type && !isDirectComposition(elem)) {
+      // Only issue warning for direct usages, not for projections, includes, etc.
+      // TODO: Make it configurable error; v4: error
+      warning( 'def-expected-comp-aspect', [ elem.type.location, elem ],
+               { prop: 'Composition of', otherprop: 'Association to' },
+               'Expected $(PROP), but found $(OTHERPROP) for composition of aspect');
+    }
+
     return true;
   }
 
@@ -1268,7 +1454,7 @@ function compareAssignments( a, b ) {
  * @param {object} source
  * @param {CSN.Options} options
  */
-function copyPersistenceAnnotations(target, source, options) {
+function copyPersistenceAnnotations( target, source, options ) {
   if (!source)
     return;
 
@@ -1325,4 +1511,24 @@ function storeTypeExtension( ext, art ) {
   art._extendType.push( ext );
 }
 
+
+function checkTextsLanguageAssocOption( model, options ) {
+  const languages = model.definitions['sap.common.Languages'];
+  const commonLanguagesEntity = options.addTextsLanguageAssoc && languages?.elements?.code;
+
+  if (options.addTextsLanguageAssoc && !commonLanguagesEntity) {
+    const variant = !languages ? 'std' : 'code';
+    const loc = model.definitions['sap.common.Languages']?.name?.location || null;
+    model.$messageFunctions.info('api-ignoring-language-assoc', loc, {
+      '#': variant, option: 'addTextsLanguageAssoc', art: 'sap.common.Languages', name: 'code',
+    }, {
+      std: 'Ignoring option $(OPTION) because entity $(ART) is missing',
+      code: 'Ignoring option $(OPTION) because entity $(ART) is missing element $(NAME)',
+    });
+  }
+
+  return !!commonLanguagesEntity;
+}
+
+
 module.exports = extend;

package/lib/compiler/finalize-parse-cdl.js

@@ -67,7 +67,7 @@ function finalizeParseCdl( model ) {
    * @param {*} artifact
    * @param {XSN.Artifact} main
    */
-  function resolveTypesForParseCdl(artifact, main) {
+  function resolveTypesForParseCdl( artifact, main ) {
     if (!artifact || typeof artifact !== 'object')
       return;
 
@@ -160,7 +160,7 @@ function finalizeParseCdl( model ) {
    * @param {object} artWithType
    * @param {XSN.Artifact} user
    */
-  function resolveTypeUnchecked(artWithType, user) {
+  function resolveTypeUnchecked( artWithType, user ) {
     const root = artWithType.type.path && artWithType.type.path[0];
     if (!root) // parse error
       return;
@@ -186,8 +186,13 @@ function finalizeParseCdl( model ) {
       // For better error messages, check for invalid TYPE OFs similarly
       // to how `resolveType()` does.
       let struct = artWithType;
-      while (struct.kind === 'element')
-        struct = struct._parent;
+      // `items` have no kind, but need to be skipped as well
+      while (struct.kind === 'element' || struct._outer?.items) {
+        if (struct._outer?.items)
+          struct = struct._outer;
+        else
+          struct = struct._parent;
+      }
       if (struct.kind === 'select' || struct.kind === 'annotation' || struct !== user._main) {
         message( 'type-unexpected-typeof', [ artWithType.type.location, user ],
                  { keyword: 'type of', '#': struct.kind } );
@@ -202,7 +207,7 @@ function finalizeParseCdl( model ) {
     }
   }
 
-  function chooseAndReportDuplicateAnnotation(artifact, annoName) {
+  function chooseAndReportDuplicateAnnotation( artifact, annoName ) {
     for (const anno of artifact[annoName])
       message( 'anno-duplicate', [ anno.name.location, artifact ], { anno: annoName } );
 

package/lib/compiler/index.js

@@ -40,8 +40,14 @@ const { cdsFs } = require('../utils/file');
 const fs = require('fs');
 const path = require('path');
 
-const csnExtensions = [ '.json', '.csn' ];
-const cdlExtensions = [ '.cds', '.hdbcds', '.hdbdd', '.cdl' ];
+const extensionParsers = {
+  csn: parseCsn.parse,
+  json: parseCsn.parse,
+  cds: parseLanguage,
+  cdl: parseLanguage,
+  hdbcds: parseLanguage,
+  hdbdd: parseLanguage,
+};
 
 // Class for command invocation errors.  Additional members:
 //  `errors`: vector of errors (file IO or ArgumentError)
@@ -75,21 +81,18 @@ class ArgumentError extends Error {
 function parseX( source, filename, options = {}, messageFunctions = null ) {
   if (!messageFunctions)
     messageFunctions = createMessageFunctions( options, 'parse' );
-  const ext = path.extname( filename ).toLowerCase();
-  if (csnExtensions.includes(ext) || options.fallbackParser === 'csn!')
-    return parseCsn.parse( source, filename, options, messageFunctions );
-  if (cdlExtensions.includes(ext))
-    return parseLanguage( source, filename, options, messageFunctions );
-  if (options.fallbackParser === 'csn')
-    return parseCsn.parse( source, filename, options, messageFunctions );
-  if (options.fallbackParser)   // any other value: like 'cdl' (historic reasons)
-    return parseLanguage( source, filename, options, messageFunctions );
-  if (source.startsWith('{')) // Source may be JSON.
-    return parseCsn.parse( source, filename, options, messageFunctions );
+  const ext = path.extname( filename ).slice(1).toLowerCase();
+  // eslint-disable-next-line no-nested-ternary
+  const parser = options.fallbackParser === 'auto!'
+    ? (source?.startsWith('{') ? parseCsn.parse : parseLanguage)
+    : (extensionParsers[ext] || extensionParsers[options.fallbackParser] ||
+       source.startsWith('{') && parseCsn.parse);
+  if (parser)
+    return parser( source, filename, options, messageFunctions );
 
   const model = { location: { file: filename } };
   messageFunctions.error( 'file-unknown-ext', emptyWeakLocation(filename),
-                          { file: ext && ext.slice(1), '#': !ext && 'none' }, {
+                          { file: ext, '#': !ext && 'none' }, {
                             std: 'Unknown file extension $(FILE)',
                             none: 'No file extension',
                           } );

package/lib/compiler/populate.js

@@ -45,6 +45,7 @@ const {
   dependsOn,
   traverseQueryPost,
   setExpandStatus,
+  setExpandStatusAnnotate,
 } = require('./utils');
 
 const $inferred = Symbol.for('cds.$inferred');
@@ -163,7 +164,6 @@ function populate( model ) {
     const chain = [];
     while (art && !('_effectiveType' in art) &&
            (art.type || art._origin || art.value?.path || art.value?.type) &&
-           // TODO: really stop at art.enum? See #8942
            !art.target && !art.enum && !art.elements && !art.items) {
       chain.push( art );
       setLink( art, '_effectiveType', 0 ); // initial setting in case of cycles
@@ -192,17 +192,15 @@ function populate( model ) {
       // collect the "latest" cardinality (calculate lazily if necessary)
       let cardinality = art.cardinality ||
           art._effectiveType && (() => getCardinality( art._effectiveType ));
-      let prev = art;
       for (const a of chain) {
         if (a.cardinality)
           cardinality = a.cardinality;
         if (a.expand && expandFromColumns( a, art, cardinality ) ||
             art.target && redirectImplicitly( a, art ) ||
             art.elements && expandElements( a, art ) ||
-            art.items && expandItems( a, art ))
+            art.items && expandItems( a, art ) ||
+            art.enum && expandEnum( a, art ))
           art = a;
-        else if (art.enum && expandEnum( a, prev ))
-          prev = a;             // do not set art - effective type is base
         setLink( a, '_effectiveType', art );
       }
     }
@@ -469,11 +467,21 @@ function populate( model ) {
               'Element $(ID) is missing in specified elements' );
       }
       else {
+        let wasAnnotated = false;
         for (const prop in selem) {
           // just annotation assignments and doc comments for the moment
-          if (prop.charAt(0) === '@' || prop === 'doc')
+          if (prop.charAt(0) === '@' || prop === 'doc') {
             ielem[prop] = selem[prop];
+            // required for gensrc mode of to-csn.js, otherwise the annotation
+            // may be lost during recompilation.
+            ielem[prop].$priority = 'annotate';
+            wasAnnotated = true;
+          }
         }
+
+        if (wasAnnotated)
+          setExpandStatusAnnotate(art, 'annotate');
+
         selem.$replacement = true;
         if (selem.elements) {
           setLink(ielem, 'elements$', selem.elements);

package/lib/compiler/propagator.js

@@ -15,6 +15,7 @@ const {
   isDeprecatedEnabled,
 } = require( '../base/model');
 const { setLink, linkToOrigin, withAssociation } = require('./utils');
+const $inferred = Symbol.for('cds.$inferred');
 // const { refString } = require( '../base/messages')
 
 // Note that propagation here is also used for deep-copying (function `onlyViaParent`)
@@ -225,6 +226,7 @@ function propagate( model ) {
       member.$inferred = 'proxy';
       setEffectiveType(member, dict[name]);
     }
+    target[prop][$inferred] = 'prop';
   }
 
   function onlyViaParent( prop, target, source ) {

package/lib/compiler/resolve.js

@@ -63,6 +63,7 @@ const {
   storeExtension,
   dependsOn,
   dependsOnSilent,
+  setExpandStatusAnnotate,
   testExpr,
   targetMaxNotOne,
   traverseQueryPost,
@@ -618,20 +619,6 @@ function resolve( model ) {
     }
   }
 
-  function setExpandStatusAnnotate( elem, status ) {
-    for (;;) {
-      if (elem.$expand === status)
-        return;                 // already set
-      elem.$expand = status;    // meaning: expanded, containing annos
-      for (let line = elem.items; line; line = line.items)
-        line.$expand = status; // to-csn just uses the innermost $expand
-      if (!elem._main)
-        return;
-      elem = elem._parent;
-    }
-  }
-
-
   function expandParameters( action ) {
     // see also expandElements()
     if (!effectiveType( action ))
@@ -1291,7 +1278,7 @@ function resolve( model ) {
     }
   }
 
-  function resolveExpr( expr, expected, user, extDict, expandOrInline) {
+  function resolveExpr( expr, expected, user, extDict, expandOrInline ) {
     // TODO: when we have rewritten the resolvePath functions,
     // define a traverseExpr() in ./utils.js
     // TODO: extra "expected" 'expand'/'inline' instead o param `expandOrInline`