@sap/cds-compiler 2.12.0 → 2.13.6

package/lib/json/from-csn.js

@@ -89,6 +89,8 @@
 
 const { dictAdd } = require('../base/dictionaries');
 
+const $location = Symbol.for('cds.$location');
+
 let inExtensions = null;
 
 let vocabInDefinitions = null;  // must be reset!
@@ -661,6 +663,9 @@ const schema = compileSchema( {
     ignore: true, type: ignore,
   },
   // TODO: should we keep $parens ?
+  $generated: {
+    type: string,
+  },
   $: { type: ignore, ignore: true }, // including $origin
   _: { type: ignore, ignore: true },
 } );
@@ -931,8 +936,10 @@ function definition( def, spec, xsn, csn, name ) {
   popLocation( def );
   if (kind !== 'annotation' || prop === 'vocabularies')
     return r;
-  if (!vocabInDefinitions)
+  if (!vocabInDefinitions) {
     vocabInDefinitions = Object.create(null);
+    vocabInDefinitions[$location] = location();
+  }
   vocabInDefinitions[name] = r;     // deprecated: anno def in 'definitions'
   return undefined;
 
@@ -957,6 +964,7 @@ function dictionaryOf( elementFct ) {
       return ignore( dict );
     }
     const r = Object.create(null);
+    r[$location] = location();
     const allNames = Object.keys( dict );
     if (!allNames.length)
       return r;                   // {} in one JSON line
@@ -980,6 +988,7 @@ function keys( array, spec, xsn ) {
   if (!isArray( array, spec ))
     return;
   const r = Object.create(null);
+  r[$location] = location();
   ++virtualLine;
   for (const def of array) {
     const id = def.as || implicitName( def.ref );
@@ -1177,6 +1186,7 @@ function annoValue( val, spec ) {
   if (lit !== 'object')
     return { val, literal: lit, location: location() };
   if (Array.isArray( val )) {
+    /** @type {string|boolean} */
     let seenEllipsis = false;
     if (arrayLevelCount > 0) {  // TODO: also inside structure (possible in CSN!)
       if (val.some( isEllipsis )) {
@@ -1435,6 +1445,7 @@ function excluding( array, spec, xsn ) {
   if (!isArray( array, spec ))
     return;
   const r = Object.create(null);
+  r[$location] = location();
   ++virtualLine;
   for (const ex of array) {
     const id = string( ex, spec ) || '';

package/lib/json/to-csn.js

@@ -57,7 +57,7 @@ const transformers = {
   key: value,
   unique: value,
   masked: value,
-  params: insertOrderDict,
+  params,
   // early expression / query properties -------------------------------------
   op: o => ((o.val !== 'SELECT' && o.val !== '$query') ? o.val : undefined),
   from,                         // before elements!
@@ -185,7 +185,7 @@ const propertyOrder = (function orderPositions() {
 
 // sync with definition in from-csn.js:
 const typeProperties = [
-  'target', 'elements', 'enum', 'items',
+  'target', 'elements', 'enum', 'items', // TODO: notNull?
   'type', 'length', 'precision', 'scale', 'srid', 'localized',
   'foreignKeys', 'on',      // for explicit ON/keys with REDIRECTED
 ];
@@ -204,7 +204,10 @@ const operators = {
   when: exprs => [ 'when', ...exprs[0], 'then', ...exprs[1] ],
   case: exprs => [ 'case' ].concat( ...exprs, [ 'end' ] ),
   over: exprs => [ 'over', { xpr: [].concat( ...exprs ) } ],
-  orderBy: exprs => [
+  orderBy: exprs => [ // ORDER BY in generic functions
+    ...exprs[0], ...operators.overOrderBy(exprs.slice(1)),
+  ],
+  overOrderBy: exprs => [ // ORDER BY in OVER() clause
     'order', 'by', ...exprs[0].concat( ...exprs.slice(1).map( e => [ ',', ...e ] ) ),
   ],
   partitionBy: exprs => [
@@ -277,7 +280,7 @@ function sortCsn( csn, cloneOptions = false ) {
 }
 
 /**
- * Check wether the given object has non enumerable property.
+ * Check whether the given object has non enumerable property.
  * Ensure that we don't take it from the prototype, only "directly" - we accidentally
  * cloned elements with a cds.linked input otherwise.
  *
@@ -621,10 +624,7 @@ function targetAspect( val, csn, node ) {
     if (val.$inferred)
       return undefined;
     if (node.target) {
-      csn.$origin = { type: 'cds.Composition' };
-      if (node.cardinality)
-        csn.$origin.cardinality = standard( node.cardinality );
-      csn.$origin.target = (val.elements) ? standard( val ) : artifactRef( val, true );
+      csn.$origin = { target: (val.elements) ? standard( val ) : artifactRef( val, true ) };
       return undefined;
     }
   }
@@ -643,7 +643,7 @@ function target( val, _csn, node ) {
     val = node._origin.target;
   if (val.elements)
     return standard( val );       // elements in target (parse-cdl)
-  if (!universalCsn || node.on)
+  if (!universalCsn || gensrcFlavor || node.on)
     return artifactRef( val, true );
   const tref = artifactRef( val, true );
   const proto = node.type && !node.type.$inferred ? node.type._artifact : node._origin;
@@ -779,7 +779,7 @@ function addLocation( loc, csn ) {
     // Remove endLine/endCol:
     // Reasoning: $location is mostly attached to definitions/members but the name
     // is often not the reason for an error or warning.  So we gain little benefit for
-    // two more properties.
+    // two more properties. It is also an indication that the location is not exact.
     const val = { file: loc.file, line: loc.line, col: loc.col };
     Object.defineProperty( csn, '$location', {
       value: val, configurable: true, writable: true, enumerable: withLocations,
@@ -807,6 +807,13 @@ function actions( dict ) {
     : undefined;
 }
 
+function params( dict ) {
+  const keys = Object.keys( dict );
+  return (keys.length)
+    ? insertOrderDict( dict )
+    : undefined;
+}
+
 function dictionary( dict, keys, prop ) {
   const csn = Object.create( dictionaryPrototype );
   for (const name of keys) {
@@ -863,7 +870,7 @@ function definition( art, _csn, _node, prop ) {
     c.returns = { elements: elems };
   }
   // precondition already fulfilled: art.kind !== 'key'
-  addOrigin( c, art, art._origin );
+  addOrigin( c, art, art );
   return c;
 }
 
@@ -876,7 +883,8 @@ function includesOrigin( includes, art ) {
   for (const incl of includes.slice(1)) {
     const aspect = incl._artifact;
     for (const prop in aspect) {
-      if (prop.charAt(0) === '@' && (!art[prop] || art[prop].$inferred)) {
+      if ((prop.charAt(0) === '@' || prop === 'doc') &&
+          (!art[prop] || art[prop].$inferred)) {
         const anno = aspect[prop];
         if (anno.val !== null)
           // matererialize non-null annos (whether direct or inherited)
@@ -887,9 +895,23 @@ function includesOrigin( includes, art ) {
   return (Object.keys( result ).length === 1) ? $origin : result;
 }
 
-function addOrigin( csn, xsn, origin ) {
-  if (!universalCsn || hasExplicitProp( xsn.type ))
+function addOrigin( csn, xsn, node ) {
+  if (!universalCsn)
     return;
+  if (hasExplicitProp( xsn.type, 'cast' )) {
+    const main = xsn._main || xsn;
+    let count = 0;
+    let source = xsn;
+    while (source && source._main === main) {
+      source = source.value && source.value._artifact;
+      ++count;
+    }
+    if (count > 0 && source && source.kind !== 'builtin')
+      csn.$source = originRef( source, xsn );
+    else if (count > 1)
+      csn.$source = null;
+    return;
+  }
   if (xsn._from) {
     const source = xsn._from[0]._origin;
     csn.$origin = originRef( source );
@@ -903,23 +925,22 @@ function addOrigin( csn, xsn, origin ) {
     csn.$origin = includesOrigin( xsn.includes, xsn );
     return;
   }
-  else if (!xsn._main || xsn.kind === 'select') {
+  let origin = getOrigin( node );
+  if (xsn.$inferred === 'composition-entity') {
+    csn.$origin = originRef( origin, xsn );
     return;
   }
+  else if (!isMember( xsn ) || xsn.kind === 'select') {
+    return;
+  }
+  // from here on: member:
   const parent = getParent( xsn );
   const parentOrigin = getOrigin( parent );
-  if (!xsn._origin || xsn._origin.kind === 'builtin') { // or $dollarVariable
-    if (parentOrigin && (!parent.enum || parent.$origin || !parent.type))
+  if (!origin) {
+    if (parentOrigin && !(parent.enum && !parent.$origin && parent.type))
       csn.$origin = null;
     return;
   }
-  // Skip all proxies which do not make it into the CSN, as there are no
-  // individual annotations or redirection targets on it:
-  while (origin._parent && origin._parent.$expand === 'origin')
-    origin = origin._origin || origin.type._artifact;
-  // The while loop is not only for the else case below: when setting implicit
-  // prototypes, it is important that we do not have to follow the prototypes of
-  // other object; we would need to ensure a right order to avoid issues otherwise.
   if (parentOrigin === getParent( origin )) {
     // implicit prototype or shortened reference
     const { id } = origin.name || {};
@@ -928,16 +949,21 @@ function addOrigin( csn, xsn, origin ) {
     return;
   }
   if (origin.kind === 'mixin') {
-    // currently, target and on are always set - nothing to do here, just set type
-    csn.type = 'cds.Association';
+    set( 'type', csn, origin );
+    set( 'cardinality', csn, origin );
+    // currently, target and on are always set - nothing to do here
     return;
   }
+  // Skip all proxies which do not make it into the CSN, as there are no
+  // individual annotations or redirection targets on it:
+  while (origin._parent && origin._parent.$expand === 'origin')
+    origin = origin._origin || origin.type._artifact;
   const ref = originRef( origin, xsn );
   if (ref) {
     csn.$origin = ref;
     return;
   }
-  // An element of a query with a query in FROM:
+  // An element of a query with a query in FROM: -----------------------------
   const anon = definition( origin );   // use $origin: {...} if necessary
   // as there are no implicit $origin prototypes on sub query elements (yet),
   // we do not have to care about $origin not being set
@@ -945,15 +971,26 @@ function addOrigin( csn, xsn, origin ) {
   if ($origin && typeof $origin === 'object' && !Array.isArray( $origin )) {
     // repeated anon: flatten
     csn.$origin = Object.assign( $origin, anon );
+    return;
+  }
+  // Annotations and 'doc' must keep the distinction between direct or inherited,
+  // other properties can as well be set as direct element properties
+  const annos = {};
+  for (const prop of Object.keys( anon )) {
+    if (prop.charAt(0) === '@' || prop === 'doc')
+      annos[prop] = anon[prop];
+    else if (prop === '$source')
+      csn[prop] = anon[prop];   // overwrite from inner
+    else if (prop !== '$location' && prop !== '$origin' && !(prop in csn))
+      csn[prop] = anon[prop];
   }
-  else if (Object.keys( anon )
-           // (we can use the properties in `csn`, because addOrigin() is called last)
-    .every( p => p in csn || p === '$origin' || p === '$location')) {
-    // nothing new in $origin: {...}
-    addOrigin( csn, xsn, origin._origin );
+  if (Object.keys( annos ).length) {
+    if (!csn.type && $origin)
+      annos.$origin = $origin;
+    csn.$origin = annos;
   }
-  else {
-    csn.$origin = anon;
+  else if (!csn.type) {
+    addOrigin( csn, xsn, origin );
   }
 }
 
@@ -963,10 +1000,27 @@ function getParent( art ) {
   return (main && parent === main._leadingQuery) ? main : parent;
 }
 
+function isMember( art ) {
+  // TODO: introduce art.kind = '$aspect' for anonymous aspect (is a member) ?
+  return !!(art._main || art._outer);
+}
+
+// function getDefinition( art ) {
+//   let main = art._main || art;
+//   while (main._outer)           // anonymous aspect
+//     main = main._outer._main;
+//   return main;
+// }
+
+// XSN `_origin` is (currently?) not the same as _origin in Universal CSN...
+// TODO: at least with expand, set it correctly (alias: keep, assoc: to entity, $builtin: no)
 function getOrigin( art ) {
-  if (art._origin)
-    return art._origin;
-  if (hasExplicitProp( art.type ))
+  if (art.$noOrigin)
+    return undefined;
+  const { _origin } = art;
+  if (_origin)
+    return (_origin.kind === 'builtin') ? undefined : _origin; // not $dollarVariable
+  if (hasExplicitProp( art.type, 'cast' ))
     return art.type._artifact;
   if (art.includes)
     return art.includes[0]._artifact;
@@ -975,31 +1029,31 @@ function getOrigin( art ) {
   return undefined;
 }
 
-function hasExplicitProp( ref ) {
-  return ref && !ref.$inferred;
+function hasExplicitProp( ref, alsoLikeExplicit ) {
+  return ref && (!ref.$inferred || ref.$inferred === alsoLikeExplicit );
 }
 
 function originRef( art, user ) {
   const r = [];
-  // do not use name.element, as we allow `.`s in name
+  // do not use name.element, as we might allow `.`s in name
   let parent = art;
-  while (parent._main && parent.kind !== 'select') {
+  if (parent._outer && parent.kind === 'aspect')
+    r.push( { target: true } );
+  while (isMember( parent ) && parent.kind !== 'select') {
     const nkind = normalizedKind[parent.kind];
-    if (parent.name.id || !r.length)
+    const name = parent.name || parent._outer.name;
+    if (name.id || !r.length)
       // Return parameter is in XSN - kind: 'param', name.id: ''
       // eslint-disable-next-line no-nested-ternary, max-len
-      r.push( !nkind ? parent.name.id : parent.name.id ? { [nkind]: parent.name.id } : { return: true } );
+      r.push( !nkind ? name.id : name.id ? { [nkind]: name.id } : { returns: true } );
     parent = parent._parent;
   }
   if (user && parent._main && parent._main === user._main && parent !== user._main._leadingQuery)
     // well, an element of an query in FROM (TODO: try with sub elem), but not the leading query
-    return null;                // probably use $origin: {...}
+    return false;               // do not write, probably use $origin: {...}
   // for sub query in FROM in sub query in FROM, we could condense the info
 
-  // Now the ref, with ["absolute", "action"] instead of ["absolute", {action:"action"}]
-  if (r.length === 1 && normalizedKind[art.kind] === 'action')
-    return [ art.name.absolute, art.name.id ];
-  r.push( art.name.absolute );
+  r.push( parent.name.absolute );
   r.reverse();
   return r;
 }
@@ -1018,6 +1072,9 @@ function kind( k, csn, node ) {
   else if (k === 'action' && node._main && universalCsn && node.$inferred) {
     // Universal CSN:  do not mention kind: 'action' on expanded action
   }
+  else if (k === 'aspect' && (node._outer || node.$inferred)) {
+    return;                     // do not show kind for anonymous aspect
+  }
   else if (![
     'element', 'key', 'param', 'enum', 'select', '$join',
     '$tableAlias', 'annotation', 'mixin',
@@ -1032,26 +1089,20 @@ function kind( k, csn, node ) {
 function type( node, csn, xsn ) {
   if (!universalCsn)
     return artifactRef( node, !node.$extra );
-  if (node.$inferred)
+  if (node.$inferred && node.$inferred !== 'cast')
     return undefined;
   if (xsn._origin) {
     if (xsn._origin.$inferred === 'REDIRECTED') { // auto-redirected user-provided target
       csn.$origin = definition( xsn._origin );
-      return undefined;
     }
   }
-  else if ( xsn.targetAspect && xsn.target ) {
-    // type moved to $origin: { type: … }
-    return undefined;
-  }
   return artifactRef( node, !node.$extra );
 }
 
-function cardinality( node, csn, xsn ) {
+function cardinality( node ) {
   if (!universalCsn)
     return standard( node );
-  // cardinality might be moved to $origin: { cardinality: … }
-  if (node.$inferred || xsn.targetAspect && !xsn.targetAspect.$inferred && xsn.target)
+  if (node.$inferred)
     return undefined;
   return standard( node );
 }
@@ -1159,8 +1210,12 @@ function value( node ) {
 // "Short" value form, e.g. for annotation assignments
   if (!node)
     return true;                // `@aBool` short for `@aBool: true`
-  if (universalCsn && node.$inferred === 'prop') // via propagator.js
-    return undefined;
+  if (universalCsn && node.$inferred) {
+    if (node.$inferred === 'prop' || node.$inferred === '$generated') // via propagator.js
+      return undefined;
+    else if (node.$inferred === 'NULL')
+      return null;
+  }
   if (node.$inferred && gensrcFlavor)
     return undefined;
   if (node.path) {
@@ -1329,7 +1384,7 @@ function query( node, csn, xsn, _prop, expectedParens = 0 ) {
   if (node.op.val === 'SELECT') {
     if (xsn && xsn.query === node && xsn.$syntax === 'projection' &&
        node.from && node.from.path && !projectionAsQuery) {
-      csn.projection = standard( node );
+      csn.projection = addLocation( node.location, standard( node ) );
       return undefined;
     }
     const select = { SELECT: extra( standard( node ), node, expectedParens ) };
@@ -1351,6 +1406,9 @@ function query( node, csn, xsn, _prop, expectedParens = 0 ) {
         gensrcFlavor = gensrcSaved;
       }
     }
+    // the $location is better put inside the SELECT value, not as sibling (but
+    // we keep it as sibling also for compatibility):
+    addLocation( node.location, select.SELECT );
     return addLocation( node.location, select );
   }
   const union = {};
@@ -1399,11 +1457,13 @@ function from( node ) {
   else if (node.query) {
     return addExplicitAs( query( node.query, null, null, null, 1 ), node.name );
   }
-  else if (!node._artifact || node._artifact._main) { // CQL or follow assoc
-    return extra( addExplicitAs( artifactRef( node, false ), node.name ), node );
-  }
-  return extra( addExplicitAs( artifactRef( node, false ), node.name, (id) => {
-    const name = node._artifact.name.absolute;
+
+  const ref = artifactRef( node, false );
+  return extra( addExplicitAs( ref, node.name, (id) => {
+    let name = ref.ref ? ref.ref[ref.ref.length - 1] : ref;
+    name = name && name.id || name;
+    if (!name)
+      return false;
     const dot = name.lastIndexOf('.');
     return name.substring( dot + 1 ) !== id;
   }), node );
@@ -1452,7 +1512,7 @@ function addElementAsColumn( elem, cols ) {
 }
 
 function orderBy( node ) {
-  const expr = expression( node, 'ignoreExtra' );
+  const expr = expression( node );
   if (node.sort)
     expr.sort = node.sort.val;
   if (node.nulls)

package/lib/language/docCommentParser.js

@@ -127,8 +127,8 @@ function removeFooterFence(line) {
  * @param {string[]} lines
  */
 function isFencedComment(lines) {
-  const index = lines.findIndex((line, index) => {
-    const exclude = (index === 0 || index === lines.length - 1);
+  const index = lines.findIndex((line, i) => {
+    const exclude = (i === 0 || i === lines.length - 1);
     return !exclude && !(/^\s*[*]/.test(line));
   });
   return index === -1 && lines.length > 2;

package/lib/language/genericAntlrParser.js

@@ -14,6 +14,7 @@ const { parseDocComment } = require('./docCommentParser');
 const { parseMultiLineStringLiteral } = require('./multiLineStringParser');
 const { functionsWithoutParens, specialFunctions } = require('../compiler/builtins');
 
+const $location = Symbol.for('cds.$location');
 
 // Push message `msg` with location `loc` to array of errors:
 function _message( parser, severity, id, loc, ...args ) {
@@ -35,6 +36,19 @@ function GenericAntlrParser( ...args ) {
   // ANTLR restriction: we cannot add parameters to the constructor.
   antlr4.Parser.call( this, ...args );
   this.buildParseTrees = false;
+
+  // Common properties.
+  // We set them here so that they are available in the prototype.
+  // This improved performance by 25% for certain scenario tests.
+  // Probably because there was no need to look up the prototype chain anymore.
+  this.$adaptExpectedToken = null;
+  this.$adaptExpectedExcludes = [ ];
+  this.$nextTokensToken = null;
+  this.$nextTokensContext = null;
+
+  this.prepareGenericKeywords();
+  this.options = {};
+
   return this;
 }
 
@@ -55,6 +69,8 @@ GenericAntlrParser.prototype = Object.assign(
     valueWithTokenLocation,
     previousTokenAtLocation,
     combinedLocation,
+    createDict,
+    setDictEndLocation,
     surroundByParens,
     unaryOpForParens,
     leftAssocBinaryOp,
@@ -70,6 +86,7 @@ GenericAntlrParser.prototype = Object.assign(
     docComment,
     addDef,
     addItem,
+    artifactForElementAnnotateOrExtend,
     assignProps,
     createPrefixOp,
     setOnce,
@@ -79,6 +96,7 @@ GenericAntlrParser.prototype = Object.assign(
     reportExpandInline,
     notSupportedYet,
     csnParseOnly,
+    disallowElementExtension,
     noAssignmentInSameLine,
     noSemicolonHere,
     setLocalToken,
@@ -213,6 +231,22 @@ function setLocalTokenIfBefore( string, tokenName, before, inSameLine ) {
 //     // throw new antlr4.error.InputMismatchException(this);
 // }
 
+/**
+ * For element extensions (`extend E:elem` syntax).
+ * If `elemName.path` is set, remove the last extension from `$outer` and
+ * emit an error that the extension is invalid.
+ *
+ * @param {object} elemName
+ * @param {object} outer
+ * @param {string} extensionVariant
+ */
+function disallowElementExtension(elemName, outer, extensionVariant) {
+  if (elemName.path) {
+    this.message( 'syntax-invalid-extend', this.tokenLocation(this.getCurrentToken()), { 'kind': extensionVariant } );
+    outer.extensions.length = outer.extensions.length - 1; // remove last, i.e. new extension
+  }
+}
+
 function noAssignmentInSameLine() {
   const t = this.getCurrentToken();
   if (t.text === '@' && t.line <= this._input.LT(-1).line) {
@@ -373,6 +407,20 @@ function combinedLocation( start, end ) {
   return locUtils.combinedLocation( start, end );
 }
 
+function createDict( location = null ) {
+  const dict = Object.create(null);
+  dict[$location] = location || this.startLocation( this._input.LT(-1) );
+  return dict;
+}
+
+function setDictEndLocation( dict ) {
+  const stop = this._input.LT(-1);
+  Object.assign( dict[$location], {
+    endLine: stop.line,
+    endCol: stop.stop - stop.start + stop.column + 2,
+  } );
+}
+
 function surroundByParens( expr, open, close, asQuery = false ) {
   if (!expr)
     return expr;
@@ -664,13 +712,13 @@ function addDef( parent, env, kind, name, annos, props, location ) {
     }
   }
   else if (name && name.id == null) {
-    name.id = pathName(name.path ); // A.B.C -> 'A.B.C'
+    name.id = pathName( name.path ); // A.B.C -> 'A.B.C'
   }
   const art = this.assignProps( { name }, annos, props, location );
   if (kind)
     art.kind = kind;
-  if (!parent[env])
-    parent[env] = Object.create(null);
+  if (!parent[env])      // TODO: dump with --test-mode, env !== 'artifacts'
+    parent[env] = env === 'args' ? Object.create(null) : this.createDict( { ...location } );
   if (!art.name || art.name.id == null) {
     // no id was parsed, but with error recovery: no further error
     // TODO: add to  parent[env]['']
@@ -727,6 +775,31 @@ function addItem( parent, env, kind, annos, props, location ) {
   return art;
 }
 
+/**
+ * For `annotate/extend E:elem.sub`, create the `elements` structure
+ * that can be used by the core compiler to annotate/extend elements.
+ *
+ * @param {string} kind Either `annotate` or `extend`
+ * @param {object} artifact Main artifact that shall have `elements`.
+ * @param {XSN.Path} elementPath Path as returned by `simplePath` token.
+ * @param {object[]} annos  Existing annotations that shall be added to the _last_ path step.
+ * @param {XSN.Location} artifactLocation Start location of the `annotate` statement.
+ * @returns {object} Deepest element
+ */
+function artifactForElementAnnotateOrExtend(kind, artifact, elementPath, annos, artifactLocation ) {
+  if (!Array.isArray(elementPath) || elementPath.broken || elementPath.length < 1)
+    return artifact;
+
+  for (const seg of elementPath.slice(0, -1)) {
+    artifact = this.addDef( artifact, 'elements', kind,
+      { path: [seg], location: seg.location }, null, {}, artifactLocation );
+  }
+  const last = elementPath[elementPath.length - 1];
+  artifact = this.addDef( artifact, 'elements', kind,
+    { path: [ last ], location: last.location }, annos, {}, artifactLocation );
+  return artifact;
+}
+
 /** Assign all non-empty (undefined, null, {}, []) properties in argument
  * `props` and argument `annos` as property `$annotations` to `target`
  * and return it.  Hack: if argument `annos` is exactly `true`, return