@sap/cds-compiler 2.11.4 → 2.12.0

package/lib/model/csnRefs.js

@@ -4,6 +4,8 @@
 // a reference is context-dependent, especially if queries are involved.  This
 // module provides the corresponding resolve/inspect functions.
 //
+// This module should work with both client-style CSN and Universal CSN.
+//
 // See below for preconditions / things to consider – the functions in this
 // module do not issue user-friendly messages for invalid references in a CSN,
 // such messages are (hopefully) issued by the compile() function.
@@ -41,18 +43,18 @@
 //
 // 1. a well-formed CSN with valid references;
 // 2. a compiled model, i.e. a CSN with all inferred information provided by
-//    the compile() function, including the (non-)enumerable `elements`
-//    property of sub `SELECT`s in a FROM;
+//    the compile() function for the CSN flavors `client` or `universal`
+//    (including the (non-)enumerable `elements` property in `client` CSN);
 // 3. no (relevant) CSN changes between the calls of the same instance of
 //    inspectRef() - to enable caching.
 //
 // If any of these conditions are not given, our functions usually simply
 // throws an exception (which might even be a plain TypeError), but it might
-// also jsut return any value.  CSN processors can provide user-friendly error
+// also just return any value.  CSN processors can provide user-friendly error
 // messages by calling the Core Compiler in case of exceptions.  For details,
 // see internalDoc/CoreCompiler.md#use-of-the-core-compiler-for-csn-processors.
 
-// During a transformation, care must be taked to adhere to these conditions.
+// During a transformation, care must be taken to adhere to these conditions.
 // E.g. a structure flattening function cannot create an element `s_x` and
 // delete `s` and then still expects inspectRef() to be able to resolve a
 // reference `['s', 'x']`.
@@ -93,7 +95,7 @@
 //
 // The names in further path items are searched in the “navigation” environment
 // of the path so far - it does not need to depend on the reference context (as
-// we do not check the validility here):
+// we do not check the validity here):
 //
 // 1. We search in the elements of the target entity for associations and
 //    compositions, and in the elements of the current object otherwise.
@@ -157,6 +159,24 @@
 //   hierarchy, query number, table aliases and links from a column to its
 //   respective inferred element.
 
+// Properties in cache:
+//
+// - _effectiveType on def/member/items: cached result of effectiveType()
+// - _origin on def/member/items: the "prototype"
+// - $origin on def/member/items: whether implicit _origin refs have been set for direct members
+// - _parent: not yet used (for debugging)
+//
+// - _env on non-string path item: environment provided by the ref so far,
+//    next path item is element in it
+// - _ref on non-string `type` or `from` ref, or on alias: the referred def/elem
+//
+// - $queries on def: array of all queries of an entity
+// - $queryNumber: the index position +1 of a query inside the $queries array
+// - $aliases on query: dictionary of alias names to cache with _ref/_select and elements
+// - _select: value of the `SELECT` property of a query (or value of `projection`)
+// - elements: the elements of the query (original CSN elements from query or main)
+// - _element on query column: the corresponding element
+
 'use strict';
 
 const BUILTIN_TYPE = {};
@@ -178,12 +198,13 @@ const referenceSemantics = {
   targetAspect: { lexical: false, dynamic: 'global' },
   from: { lexical: false, dynamic: 'global' },
   keys: { lexical: false, dynamic: 'target' },
+  keys_origin: { lexical: false, dynamic: 'target' },
   excluding: { lexical: false, dynamic: 'source' },
   expand: { lexical: justDollar, dynamic: 'expand' },   // ...using baseEnv
   inline: { lexical: justDollar, dynamic: 'inline' },   // ...using baseEnv
   ref_where: { lexical: justDollar , dynamic: 'ref-target'}, // ...using baseEnv
   on: { lexical: justDollar, dynamic: 'query' }, // assoc defs, redirected to
-  // there are also 'join_on' and 'mixin_on' with default semantics
+  // there are also 'on_join' and 'on_mixin' with default semantics
   orderBy: { lexical: query => query, dynamic: 'query' },
   orderBy_set: { lexical: query => query.$next, dynamic: 'query' }, // to outer SELECT (from UNION)
   // default: { lexical: query => query, dynamic: 'source' }
@@ -249,20 +270,18 @@ function csnRefs( csn ) {
    * @param {CSN.Artifact} art
    */
   function navigationEnv( art ) {
-    let type = effectiveType( art );
+    let env = effectiveType( art );
+    getOrigin( env );          // also set implicit origins
     // here, we do not care whether it is semantically ok to navigate into sub
     // elements of array items (that is the task of the core compiler /
     // semantic check)
-    while (type.items) {
-      cached( type, '$origin', _a => setImplicitOrigin( type, origin ) );
-      type = effectiveType( type.items );
-    }
-    // cannot navigate along targetAspect!
-    const env = (type.target) ? csn.definitions[type.target] : type;
-    const origin = cached( env, '_origin', getOriginRaw );
-    if (origin && origin !== BUILTIN_TYPE)
-      cached( env, '$origin', _a => setImplicitOrigin( env, origin ) );
-    return env;
+    while (env.items)
+      env = effectiveType( env.items );
+    if (!env.target)
+      return env;
+    const target = csn.definitions[env.target];
+    getOrigin( target );
+    return target;
   }
 
   /**
@@ -294,11 +313,28 @@ function csnRefs( csn ) {
     return art;
   }
 
-  function getOrigin( art, alsoType ) {
+  // Return target when resolving references in 'keys'
+  function assocTarget( art, refCtx ) {
+    // Call contexts:
+    // 1. normal definition of association with explicit foreign keys
+    // 2. auto-redirected association with renaming of foreign keys
+    //    (currently: `keys` always available on inherited associations)
+    // 3. user-induced redirection (in 'cast') with explicit foreign keys
+    // 4. original provided association def inside $origin with explicit foreign keys
+    //    (outside $origin like 2)
+    const targetName = refCtx !== 'keys_origin' && art.target
+                    || art.$origin && art.$origin.target
+                    || art.cast.target;
+    const target = csn.definitions[targetName];
+    getOrigin( target );        // induce implicit $origin on target
+    return target;
+  }
+
+  function getOrigin( art ) {
     const origin = cached( art, '_origin', getOriginRaw );
     if (origin && origin !== BUILTIN_TYPE)
       cached( art, '$origin', _a => setImplicitOrigin( art, origin ) );
-    return art.type && !alsoType ? undefined : origin;
+    return origin;
   }
 
   function getOriginRaw( art ) {
@@ -308,6 +344,7 @@ function csnRefs( csn ) {
       return null;
     // art.$origin must not be a string here - shortened refs should already
     // have been used to set the _origin cache
+    // If $origin object, return $origin of that:
     if (!Array.isArray( art.$origin )) // anonymous prototype in $origin
       return cached( art.$origin, '_origin', getOriginRaw );
     const [ head, ...tail ] = art.$origin;
@@ -344,6 +381,8 @@ function csnRefs( csn ) {
     // if (origin)
     //   cached( art, '$origin', _a => setImplicitOrigin( art, origin ) );
     // console.log(art)
+    if (art.returns)            // for ["main", {action: "act"}, "elem"]
+      art = art.returns;
     return (art.elements || art.enum || targetAspect( art ).elements)[elem];
   }
 
@@ -444,16 +483,16 @@ function csnRefs( csn ) {
 
     const head = pathId( path[0] );
     if (ref.param)
-      return resolvePath( path, main.params[head], 'param' );
+      return resolvePath( path, main.params[head], main, 'param' );
 
     const semantics = referenceSemantics[refCtx] || {};
     if (semantics.dynamic === 'global' || ref.global)
-      return resolvePath( path, csn.definitions[head], 'global', refCtx === 'from' );
+      return resolvePath( path, csn.definitions[head], null, 'global', refCtx === 'from' );
 
-    const origin = cached( main, '_origin', getOriginRaw )
-    if (origin)
-      cached( main, '$origin', _a => setImplicitOrigin( main, origin ) );
-    cached( main, '$queries', allQueries );
+    if (main) {
+      getOrigin( main );
+      cached( main, '$queries', allQueries );
+    }
     let qcache = query && cache.get( query.projection || query );
     // BACKEND ISSUE: you cannot call csnRefs(), inspect some refs, change the
     // CSN and again inspect some refs without calling csnRefs() before!
@@ -469,39 +508,38 @@ function csnRefs( csn ) {
       while (cache) {
         const alias = tryAlias && cache.$aliases[head];
         if (alias)
-          return resolvePath( path, alias._select || alias._ref, 'alias', cache.$queryNumber );
+          return resolvePath( path, alias._select || alias._ref, null,
+                              'alias', cache.$queryNumber );
         const mixin = cache._select.mixin && cache._select.mixin[head];
         if (mixin && {}.hasOwnProperty.call( cache._select.mixin, head ))
-          return resolvePath( path, mixin, 'mixin', cache.$queryNumber );
+          return resolvePath( path, mixin, null, 'mixin', cache.$queryNumber );
         cache = cache.$next;
       }
       if (head.charAt(0) === '$') {
         if (head !== '$self' && head !== '$projection')
           return { scope: '$magic' };
         const self = qcache && qcache.$queryNumber > 1 ? qcache._select : main;
-        return resolvePath( path, self, '$self' );
+        return resolvePath( path, self, null, '$self' );
       }
     }
     // now the dynamic environment: ------------------------------------------
     if (semantics.dynamic === 'target') { // ref in keys
-      // not selecting the corresponding element for a select column works,
-      // because explicit keys can only be provided with explicit redirection
-      // target
-      const target = csn.definitions[parent.target || parent.$origin && parent.$origin.target || parent.cast.target];
-      return resolvePath( path, target.elements[head], 'target' );
+      const target = assocTarget( parent, refCtx );
+      return resolvePath( path, target.elements[head], target, 'target' );
     }
     if (baseEnv)                // ref-target (filter condition), expand, inline
-      return resolvePath( path, baseEnv.elements[head], semantics.dynamic );
+      return resolvePath( path, baseEnv.elements[head], baseEnv, semantics.dynamic );
     if (!query)                 // outside queries - TODO: items?
-      return resolvePath( path, parent.elements[head], 'parent' );
+      return resolvePath( path, parent.elements[head], parent, 'parent' );
 
     if (semantics.dynamic === 'query')
       // TODO: for ON condition in expand, would need to use cached _element
-      return resolvePath( path, qcache.elements[head], 'query' );
+      return resolvePath( path, qcache.elements[head], null, 'query' );
     for (const name in qcache.$aliases) {
-      const found = qcache.$aliases[name].elements[head];
+      const alias = qcache.$aliases[name];
+      const found = alias.elements[head];
       if (found)
-        return resolvePath( path, found, 'source', name )
+        return resolvePath( path, found, alias._ref, 'source', name )
     }
     // console.log(query.SELECT,qcache,qcache.$next,main)
     throw new Error ( `Path item ${ 0 }=${ head } refers to nothing, refCtx: ${ refCtx }` );
@@ -511,8 +549,9 @@ function csnRefs( csn ) {
    * @param {CSN.Path} path
    * @param {CSN.Artifact} art
    * @param {string} [scope]
+   * @param [extraInfo]
    */
-  function resolvePath( path, art, scope, extraInfo ) {
+  function resolvePath( path, art, parent, scope, extraInfo ) {
     /** @type {{idx, art?, env?}[]} */
     const links = path.map( (_v, idx) => ({ idx }) );
     // TODO: backends should be changed to enable uncommenting:
@@ -520,11 +559,11 @@ function csnRefs( csn ) {
     //   throw new Error ( `Path item ${ 0 }=${ pathId( path[0] ) } refers to nothing, scope: ${ scope }`);
     links[0].art = art;
     for (let i = 1; i < links.length; ++i) { // yes, starting at 1, links[0] is set above
-      art = navigationEnv( art );
-      links[i - 1].env = art;
+      parent = navigationEnv( art );
+      links[i - 1].env = parent;
       if (typeof path[i - 1] !== 'string')
-        setCache( path[i - 1], '_env', art );
-      art = art.elements[pathId( path[i] )];
+        setCache( path[i - 1], '_env', parent );
+      art = parent.elements[pathId( path[i] )];
       if (!art) {
         const env = links[i - 1].env;
         const loc = env.name && env.name.$location || env.$location;
@@ -537,14 +576,16 @@ function csnRefs( csn ) {
     if (fromRef || typeof last !== 'string') {
       const env = navigationEnv( art );
       links[links.length - 1].env = env;
-      if (fromRef)
+      if (fromRef) {
         art = env;
+        parent = null;
+      }
       if (typeof last !== 'string')
         setCache( last, '_env', env )
     }
     return (extraInfo && !fromRef)
-      ? { links, art, scope, $env: extraInfo }
-      : { links, art, scope };
+      ? { links, art, parent, scope, $env: extraInfo }
+      : { links, art, parent, scope };
   }
 
   /**
@@ -666,8 +707,8 @@ function csnRefs( csn ) {
 // i.e. a value with an `elements` property.
 // TODO: only used in forHanaNew - move somewhere else
 /**
- * @param {CSN.Query} query node (object with SET or SELECT property)
- * @param {CSN.Definition} main
+ * @param {object} query node (object with SET or SELECT property)
+ * @param {object} main definition
  */
 function queryOrMain( query, main ) {
   while (query.SET)
@@ -691,7 +732,7 @@ function queryOrMain( query, main ) {
  * @param {CSN.Query} query
  * @param {CSN.QuerySelect} fromSelect
  * @param {CSN.Query} parentQuery
- * @param {(query: CSN.Query&CSN.QueryFrom, select: CSN.QuerySelectEnriched) => void} callback
+ * @param {(query: CSN.Query&CSN.QueryFrom, select: CSN.QuerySelectEnriched, parentQuery: CSN.Query) => void} callback
  */
 function traverseQuery( query, fromSelect, parentQuery, callback ) {
   const select = query.SELECT || query.projection;
@@ -755,30 +796,42 @@ function implicitAs( ref ) {
   return id.substring( id.lastIndexOf('.') + 1 );
 }
 
+function startCsnPath( csnPath, csn ) {
+  const head = csnPath[0];
+  if (typeof head !== 'string') {
+    const { main, parent, art } = head;
+    return { index: 1, main, parent, art };
+  }
+  if (csnPath.length < 2 || csnPath[0] !== 'definitions')
+    throw new Error( 'References outside definitions not supported yet');
+  const art = csn.definitions[csnPath[1]];
+  return { index: 2, main: art, parent: null, art };
+}
+
 /**
  * @param {CSN.Path} csnPath
  * @param {CSN.Model} csn
  */
 function analyseCsnPath( csnPath, csn, resolve ) {
-  if (csnPath[0] !== 'definitions')
-    throw new Error( 'References outside definitions not supported yet');
-
   /** @type {object} */
-  let obj = csn;
-  let parent = null;
   let query = null;
   let refCtx = null;
-  let art = null;
   /** @type {boolean|string|number} */
   let isName = false;
   let baseRef = null;
   let baseEnv = null;
-  let main = csn.definitions[csnPath[1]];
+  let { index, main, parent, art } = startCsnPath( csnPath, csn );
+  let obj = art;
+
+  for (; index < csnPath.length; index++) {
+    if (!obj && !resolve)
+      // For the semantic location, use current object as best guess
+      break;
 
-  for (let index = 0; index < csnPath.length; index++) {
     const prop = csnPath[index];
     // array item, name/index of artifact/member, (named) argument
     if (isName || Array.isArray( obj )) {
+      // TODO: call some kind of resolve.setOrigin()
       if (typeof isName === 'string') {
         parent = art;
         art = obj[prop];
@@ -791,7 +844,8 @@ function analyseCsnPath( csnPath, csn, resolve ) {
         parent = null;
       }
       isName = prop;
-      refCtx = prop;
+      // if we want to allow auto-redirect of user-provided target with renamed keys:
+      refCtx = (refCtx === '$origin' && prop === 'keys') ? 'keys_origin' : prop;
     }
     else if (prop === 'items' || prop === 'returns') {
       art = obj[prop];
@@ -807,15 +861,13 @@ function analyseCsnPath( csnPath, csn, resolve ) {
     }
     else if (prop === 'where' && refCtx === 'ref') {
       if (resolve)
-        baseEnv = resolve.ref_where( obj, baseRef, refCtx, csn.definitions[csnPath[1]],
-                                    query, parent, baseEnv );
+        baseEnv = resolve.ref_where( obj, baseRef, refCtx, main, query, parent, baseEnv );
       refCtx = 'ref_where';
     }
     else if (prop === 'expand' || prop === 'inline') {
       if (obj.ref) {
         if (resolve)
-          baseEnv = resolve.expandInline( obj, refCtx, csn.definitions[csnPath[1]],
-                                          query, parent, baseEnv );
+          baseEnv = resolve.expandInline( obj, refCtx, main, query, parent, baseEnv );
         refCtx = prop;
       }
       if (prop === 'expand')
@@ -823,9 +875,9 @@ function analyseCsnPath( csnPath, csn, resolve ) {
     }
     else if (prop === 'on') {
       if (refCtx === 'from')
-        refCtx = 'join_on';
+        refCtx = 'on_join';
       else if (refCtx === 'mixin')
-        refCtx = 'mixin_on';
+        refCtx = 'on_mixin';
       else
         refCtx = 'on';          // will use query elements with REDIRECTED TO
     }
@@ -839,11 +891,7 @@ function analyseCsnPath( csnPath, csn, resolve ) {
     else if (prop !== 'xpr') {
       refCtx = prop;
     }
-
     obj = obj[prop];
-    if (!obj && !resolve)
-      // For the semantic location, use current object as best guess
-      break;
   }
   // console.log( 'CPATH:', csnPath, refCtx, obj, parent.$location );
   if (!resolve)

package/lib/model/csnUtils.js

@@ -61,6 +61,7 @@ function getUtils(model) {
     effectiveType,
     get$combined,
     getOrigin,
+    getQueryPrimarySource,
   };
 
   /**
@@ -176,10 +177,10 @@ function getUtils(model) {
       }
     }
 
-      /**
-   * Return the name part of the artifact name - no namespace etc.
-   * @param {string|object} name Absolute name of the artifact
-   */
+    /**
+     * Return the name part of the artifact name - no namespace etc.
+     * @param {string|object} name Absolute name of the artifact
+     */
     function getBaseName(name) {
       if (!name)
         return name;
@@ -191,6 +192,27 @@ function getUtils(model) {
     }
   }
 
+  /**
+   * Return the left-most, primary source of the given query.
+   * @param {*} query Definition's query object
+   */
+  function getQueryPrimarySource(query) {
+    if (!query)
+      return undefined;
+    else if (query.SELECT) {
+      return getQueryPrimarySource(query.SELECT);
+    } else if (query.SET) {
+      return getQueryPrimarySource(query.SET);
+    } else if (query.from) {
+      return getQueryPrimarySource(query.from);
+    } else if (query.ref) {
+      return query;
+    } else if (query.args) {
+      return getQueryPrimarySource(query.args[0]);
+    }
+    return undefined;
+  }
+
 
   /**
    * Create an object to track visited objects identified by a unique string.
@@ -230,7 +252,7 @@ function getUtils(model) {
    * Returns true if an artifact is a structured type
    * or a typedef of a structured type.
    *
-   * @param {CSN.Artifact} obj
+   * @param {object} obj
    */
   function isStructured(obj) {
     return obj.elements ||
@@ -397,7 +419,7 @@ function getUtils(model) {
   function getServiceName(artifactName) {
     for(;;) {
       let idx = artifactName.lastIndexOf('.');
-      if (idx == -1) return null;
+      if (idx === -1) return null;
       artifactName = artifactName.substring(0, idx);
       let artifact = model.definitions[artifactName];
       if (artifact && artifact.kind === 'service') {
@@ -859,11 +881,14 @@ function forAllElements(artifact, artifactName, cb, includeActions = false){
  * @param {CSN.Artifact} artifact
  * @param {string} annotationName Name of the annotation (including the at-sign)
  * @param {any} expected
+ * @param {boolean} caseInsensitive
  * @returns {boolean}
  */
-function hasAnnotationValue(artifact, annotationName, expected = true) {
+function hasAnnotationValue(artifact, annotationName, expected = true, caseInsensitive = false) {
   if(expected === false)
     return artifact[annotationName] === expected || artifact[annotationName] === null;
+  else if (typeof artifact[annotationName] === 'string' && caseInsensitive === true)
+    return artifact[annotationName].toLowerCase() === expected.toLowerCase();
   else
     return artifact[annotationName] === expected;
 }
@@ -1232,38 +1257,6 @@ function mergeOptions(...optionsObjects) {
   }
 }
 
-// Return the name of the top-level artifact surrounding the artifact 'name'
-// in 'model'.
-// We define "top-level artifact" to be an artifact that has either no parent or only
-// ancestors of kind 'namespace'. Note that it is possible for a non-top-level artifact
-// to have a namespace as parent and e.g. a context as grandparent (weird but true).
-// Will return the artifact 'name' if it is a top-level artifact itself, and 'undefined'
-// if there is no artifact surrounding 'name' in the model
-// TODO: to be checked by author: still intended behaviour with 'cds' prefix?
-// TODO: Can this be replaced by getRootArtifactName? Or maybe not rely on namespace-hacking...
-// FIXME: This only works with namespace-hacking, i.e. adding them as artifacts...
-function getTopLevelArtifactNameOf(name, model) {
-  let dotIdx = name.indexOf('.');
-  if (dotIdx == -1) {
-    // No '.' in the name, i.e. no parent - this is a top-level artifact (if it exists)
-    return model.definitions[name] ? name : undefined;
-  }
-  // If the first name part is not in the model, there is nothing to find
-  if (!model.definitions[name.substring(0, dotIdx)]) {
-    return undefined;
-  }
-  // Skip forward through '.'s until finding a non-namespace
-  while (dotIdx != -1 && (!model.definitions[name.substring(0, dotIdx)] || model.definitions[name.substring(0, dotIdx)].kind === 'namespace')) {
-    dotIdx = name.indexOf('.', dotIdx + 1);
-  }
-  if (dotIdx == -1) {
-    // This is a top-level artifact
-    return name;
-  }
-  // The skipped part of 'name' is the top-level artifact name
-  return name.substring(0, dotIdx);
-}
-
 /**
 * If the artifact with the name given is part of a context (or multiple), return the top-most context.
 * Else, return the artifact itself. Namespaces are not of concern here.
@@ -1473,8 +1466,8 @@ function isSkipped(artifact) {
 function walkCsnPath(csn, path) {
   /** @type {object} */
   let obj = csn;
-  for(let i = 0; i < path.length; i++){
-    obj = obj[path[i]];
+  for(const segment of path){
+    obj = obj[segment];
   }
 
   return obj;
@@ -1483,16 +1476,16 @@ function walkCsnPath(csn, path) {
 /**
  * If provided, get the replacement string for the given magic variable ref.
  * No validation is done that the ref is actually magic!
- * 
- * @param {array} ref 
- * @param {CSN.Options} options 
- * @returns {string|null} 
+ *
+ * @param {array} ref
+ * @param {CSN.Options} options
+ * @returns {string|null}
  */
 function getVariableReplacement(ref, options) {
   if(options && options.variableReplacements) {
     let replacement = options.variableReplacements;
-    for(let i = 0; i < ref.length; i++) {
-      replacement = replacement[ref[i]];
+    for(const segment of ref) {
+      replacement = replacement[segment];
       if(replacement === undefined)
         return null;
     }
@@ -1534,7 +1527,6 @@ module.exports = {
   generatedByCompilerVersion,
   getNormalizedQuery,
   mergeOptions,
-  getTopLevelArtifactNameOf,
   getRootArtifactName,
   getLastPartOfRef,
   getParentNamesOf,

package/lib/model/enrichCsn.js

@@ -7,9 +7,9 @@
 
 // * `File.cds:3:5` if the original CSN has a non-enumerable `$location` property
 //   with value `{file: "File.cds", line: 3, col: 5}`.
-// * `File.cds:3:5-1` if the original CSN has _no_ `$location` property, for an
+// * `File.cds:3:5^` if the original CSN has _no_ `$location` property, for an
 //   inferred member of a main artifact or member with `$location: `File.cds:3:5`;
-//   the number of digits in the `-1` suffix is the member depth.
+//   the number of `^`s in the suffix is the member depth.
 
 // Other enumerable properties in the JSON for non-enumerable properties in the
 // original CSN:
@@ -25,11 +25,17 @@
 // * `_type`, `_includes` and `_targets` have as values the `$location`s of the
 //   referred artifacts which are returned by function `artifactRef`.
 // * `_links` and `_art` as sibling properties of `ref` have as values the
-//   `$locations` of the artifacts/members returned by function `inspectRef`.
+//   `$locations` of the artifacts/members returned by function `inspectRef` (`_art`
+//   for ref in `from` only, where it is different to the last item of `_links`).
 // * `_scope` and `_env` as sibling properties of `ref` have (string) values,
 //   returned by function `inspectRef`, giving add/ info about the “ref base”.
 // * `_origin` (in Universal CSN only) has as value the `$location` of the
 //   prototype returned by function getOrigin().
+// * `_test.inspect.csnpath` as sibling property of `ref` has an object value
+//   with properties `_links` and `_scope` of a further `inspectRef` call;
+//   it is only called, with `[‹art›, ...‹csnpath›]` as argument, if `‹art›`,
+//   which is the referred artifact returned by the first `inspectRef` call,
+//   has an annotation `@$test.inspect.csnpath` with array value `‹csnpath›`.
 
 'use strict';
 
@@ -92,7 +98,7 @@ function enrichCsn( csn, options = {} ) {
     // call getOrigin() before standard() to set implicit protos inside standard():
     const origin = handleError( err => err ? err.toString() : getOrigin( obj ) );
     standard( parent, prop, obj );
-    if (obj.$origin === undefined && origin != null)
+    if (obj.$origin === undefined && !obj.type && origin != null)
       obj._origin = refLocation( origin );
   }
 
@@ -142,16 +148,18 @@ function enrichCsn( csn, options = {} ) {
     handleError( err => {
       if (err)
         parent._origin = err.toString();
-      else if (Array.isArray( ref ) || typeof ref === 'string') // $origin: […], not $origin: {…}
-        parent._origin = refLocation( getOrigin( parent, true ) );
-      else if ( ref )
+      else if (Array.isArray( ref ) || typeof ref === 'string') // $origin: […] / "short-ref"
+        parent._origin = refLocation( getOrigin( parent ) );
+      else if ( ref )                                           // $origin: {…}
         standard( parent, prop, ref );
     } );
   }
 
-  function pathRef( parent, prop, path ) {
-    const { links, art, scope, $env }
-          = handleError( err => (err) ? { scope: err.toString() } : inspectRef( csnPath ) );
+  function pathRef( parent, prop, path, inspectionPath = csnPath ) {
+    const inspection = handleError( (err) => {
+      return (err) ? { scope: err.toString() } : inspectRef( inspectionPath );
+    });
+    const { links, art, scope, $env } = inspection;
     if (links)
       parent._links = links.map( l => refLocation( l.art ) );
     if (links && links[links.length-1].art !== art)
@@ -160,6 +168,15 @@ function enrichCsn( csn, options = {} ) {
     if ($env)
       parent._env = $env;
 
+    if (!prop)                  // recursive call for @$test.inspect.csnpath
+      return;
+    const testPath = art && art['@$test.inspect.csnpath'];
+    if (testPath && parent.ref) {
+      const further = {};
+      pathRef( further, null, null, [ inspection, ...testPath ] );
+      parent['_test.inspect.csnpath'] = further;
+    }
+
     csnPath.push( prop );
     path.forEach( function step( s, i ) {
       if (s && typeof s === 'object') {
@@ -256,12 +273,11 @@ function setLocations( node, prop, loc ) {
     return;
   const isMember = artifactProperties.includes( prop );
   if (!isMember && node.$location) {
-    const value = locationString( node.$location, true );
-    reveal( node, '$location', value );
-    loc = value + '-';
+    loc = locationString( node.$location, true );
+    reveal( node, '$location', loc );
   }
   else if (prop === true) {
-    loc += '1';
+    loc += '^';
     node.$location = loc;
   }
   if (Array.isArray( node )) {