@sap/cds-dk 10.0.6 → 10.1.0

package/node_modules/@sap/cds-compiler/lib/compiler/define.js

@@ -127,6 +127,7 @@ const {
   dictAdd, dictAddArray, dictForEach, pushToDict,
 } = require('./dictionaries');
 const { kindProperties } = require('./base');
+const { CompilerAssertion } = require('../base/error');
 const {
   setLink,
   initItemsLinks,
@@ -277,6 +278,18 @@ function define( model ) {
     }
   }
 
+  /**
+   * Calculate the absolute name of a main artifact (created via CDL or CSN parser).
+   * Detect reserved-namespace violations (name starts with `cds.`).
+   * Add artifact to `model.definitions` if the name does not start with `localized.`.
+   *
+   * Set `_block` links for the artifact and annotations with expression value
+   * (also set `kind` to `$annotation` for those).
+   *
+   * @param {XSN.Artifact} art
+   * @param {XSN.SourceAst|XSN.Artifact} block  Enclosing block (source or context/service)
+   * @param {string} prefix  Dot-terminated absolute name prefix, e.g. `A.B.`, or ``
+   */
   function addMainArtifact( art, block, prefix ) {
     setLink( art, '_block', block );
     initExprAnnoBlock( art, block, error ); // TODO: why also here?
@@ -303,7 +316,39 @@ function define( model ) {
     dictAdd( model.definitions, absolute, art );
   }
 
-  // If 'A.B.C' is in 'artifacts', also add 'A' for name resolution
+  /**
+   * Add a main artifact to the model, like `addMainArtifact` does.
+   * Additionally, add all main artifacts in `art.artifacts` to the model, and
+   * all extensions in `art.extensions`.
+   *
+   * @param {XSN.Artifact} art
+   * @param {XSN.SourceAst|XSN.Artifact} block  Enclosing block (source or context/service)
+   * @param {string} prefix  Dot-terminated absolute name prefix, e.g. `A.B.`, or ``
+   */
+  function addBlockArtifact( art, block, prefix ) {
+    if (art.kind === 'using')
+      return;
+    addMainArtifact( art, block, prefix );
+    if (art.artifacts) {
+      const p = `${ art.name.id }.`;
+      // path prefixes (usings) must be added before extensions in artifacts:
+      addPathPrefixes( art.artifacts, p );
+      dictForEach( art.artifacts, a => addBlockArtifact( a, art, p ) );
+    }
+    if (art.extensions) {       // requires using to be known!
+      art.extensions.forEach( e => e.name && addExtension( e, art ) );
+    }
+  }
+
+  /**
+   * Ensure that every dotted top-level name in `artifacts` has a synthetic `using`
+   * proxy for its first path component so that name resolution can find it.
+   * E.g. if `artifacts` contains an artifact with block-relative name `B.C`,
+   * a `using`-like entry for `B` is inserted (unless one already exists).
+   *
+   * @param {Object} artifacts  Dictionary of artifact definitions keyed by relative name
+   * @param {string} prefix     Absolute name prefix of the enclosing block, e.g. `"A."`
+   */
   function addPathPrefixes( artifacts, prefix ) {
     for (const name in artifacts) {
       const d = artifacts[name];
@@ -331,10 +376,9 @@ function define( model ) {
 
   /**
    * Add the names of a USING declaration to the top-level search environment
-   * of the source, and set the absolute name referred by the USING
-   * declaration.
+   * of the source, and set the absolute name referred by the USING declaration.
    *
-   * @param {XSN.Using} decl Node to be expanded and added to `src`
+   * @param {XSN.Using} decl  USING declaration to be expanded and added to `src`
    * @param {XSN.SourceAst} src
    */
   function addUsing( decl, src ) {
@@ -360,7 +404,14 @@ function define( model ) {
       dictAddArray( src.artifacts, name, decl );
   }
 
-  // must be called after addUsing().
+  /**
+   * Use the namespace declaration as USING declaration if the local name
+   * is not already defined in the source (that is why all `addUsing`s must
+   * have been called before).
+   *
+   * @param {XSN.Namespace} namespace  Namespace declaration of `src`
+   * @param {XSN.SourceAst} src
+   */
   function addNamespace( namespace, src ) {
     // create using for own namespace:
     // TODO: should we really do that (in v6)?  See also initNamespaceAndUsing().
@@ -377,29 +428,40 @@ function define( model ) {
       $inferred: 'namespace',
     };
   }
-  function addBlockArtifact( art, block, prefix ) {
-    if (art.kind === 'using')
-      return;
-    addMainArtifact( art, block, prefix );
-    if (art.artifacts) {
-      const p = `${ art.name.id }.`;
-      // path prefixes (usings) must be added before extensions in artifacts:
-      addPathPrefixes( art.artifacts, p );
-      dictForEach( art.artifacts, a => addBlockArtifact( a, art, p ) );
-    }
-    if (art.extensions) {       // requires using to be known!
-      art.extensions.forEach( e => e.name && addExtension( e, art ) );
-    }
-  }
 
+  /**
+   * Register an extension block in `model.$collectedExtensions` so it can be
+   * applied during the extend phase.  For context/service extensions that carry
+   * nested `artifacts`, those artifacts are registered in `model.definitions` as
+   * well (delegating to `addBlockArtifact`).
+   *
+   * @param {XSN.Extension} ext   The `extend`/`annotate` node from the source AST
+   * @param {XSN.SourceAst|XSN.Artifact} block  Enclosing block that provides scope
+   */
   function addExtension( ext, block ) {
     setLink( ext, '_block', block );
     initExprAnnoBlock( ext, block, error );
     const absolute = ext.name && resolveUncheckedPath( ext.name, '_uncheckedExtension', ext );
     if (!absolute)                    // broken path
       return;
-    delete ext.name.path[0]._artifact; // might point to wrong JS object in phase 1 - TODO: still?
+
+    if (ext.artifacts) {
+      // Directly add the artifacts of context and service extension:
+      if (!model.$blocks)
+        model.$blocks = Object.create( null );
+      // Set block number for debugging (--raw-output):
+      // eslint-disable-next-line no-multi-assign
+      ext.$effectiveSeqNo = model.$blocks[absolute] = (model.$blocks[absolute] || 0) + 1;
+      const prefix = `${ absolute }.`;
+      dictForEach( ext.artifacts, a => addBlockArtifact( a, ext, prefix ) );
+
+      if (!ext.expectedKind && !ext.doc &&
+          !Object.keys( ext ).some( prop => prop.startsWith( '@' ) ))
+        return;               // not part of extensions if just nested definitions
+    }
     ext.name.id = absolute; // definition might not be there yet, no _artifact link
+    delete ext.name.path[0]._artifact; // might point to wrong JS object in phase 1 - TODO: still?
+
     const location = { file: '' }; // stupid required location
     const late = model.$collectedExtensions[absolute] ||
           (model.$collectedExtensions[absolute] = {
@@ -409,19 +471,15 @@ function define( model ) {
             location,
           });
     pushToDict( late, '_extensions', ext );
-    if (!ext.artifacts)
-      return;
-
-    // Directly add the artifacts of context and service extension:
-    if (!model.$blocks)
-      model.$blocks = Object.create( null );
-    // Set block number for debugging (--raw-output):
-    // eslint-disable-next-line no-multi-assign
-    ext.$effectiveSeqNo = model.$blocks[absolute] = (model.$blocks[absolute] || 0) + 1;
-    const prefix = `${ absolute }.`;
-    dictForEach( ext.artifacts, a => addBlockArtifact( a, ext, prefix ) );
   }
 
+  /**
+   * Register a vocabulary artifact in `model.vocabularies` under its absolute name.
+   *
+   * @param {XSN.Artifact} vocab
+   * @param {XSN.SourceAst} block
+   * @param {string} prefix  Dot-terminated absolute name prefix, or `""`
+   */
   function addVocabulary( vocab, block, prefix ) {
     setLink( vocab, '_block', block );
     const { name } = vocab;
@@ -480,6 +538,14 @@ function define( model ) {
   // Functions called from top-level: initNamespaceAndUsing(), initMainArtifact(),
   // initVocabulary(), initExtension()
 
+  /**
+   * Initialise for a single CDL source: register the "namespace artifact" in
+   * `model.definitions` if no real artifact with that name exists,
+   * warn when the namespace's last component shadows a builtin name, and
+   * report duplicate top-level `using` names introduced by `using` declarations.
+   *
+   * @param {XSN.SourceAst} src
+   */
   function initNamespaceAndUsing( src ) {
     if (src.$frontend && src.$frontend !== 'cdl')
       return;
@@ -518,6 +584,16 @@ function define( model ) {
     }
   }
 
+  /**
+   * Initialise for a top-level artifact: sets `_parent`/`_subArtifacts` links,
+   * check for duplicate definitions, initialise `$self`/`$parameters` aliases,
+   * recurse into members, and drive query initialisation for entities/views.
+   * Pass `reInit = true` for auto-exposed entities to skip the `_parent` step
+   * (their parent link is already set up during auto-exposure).
+   *
+   * @param {XSN.Artifact} art
+   * @param {boolean} [reInit]
+   */
   function initMainArtifact( art, reInit = false ) {
     if (!reInit)                // not for auto-exposed entity
       initArtifactParentLink( art, model.definitions );
@@ -533,6 +609,13 @@ function define( model ) {
     }
   }
 
+  /**
+   * Initialise for a vocabulary artifact: sets `_parent`/`_subArtifacts` links,
+   * checks for duplicates, recurses into members, and rejects query-based vocabulary
+   * definitions (projections on annotation definitions are unsupported).
+   *
+   * @param {XSN.Artifact} art
+   */
   function initVocabulary( art ) {
     initArtifactParentLink( art, model.vocabularies );
     checkRedefinition( art );
@@ -545,10 +628,16 @@ function define( model ) {
     }
   }
 
-  function initExtension( parent ) {
-    initMembers( parent );
-    if (parent.columns)
-      initSelectItems( parent, parent.columns, parent, true );
+  /**
+   * Initialise for an `extend`/`annotate` node: recurse into its members
+   * and, for `extend … with columns`, initialises the column list in extension context.
+   *
+   * @param {XSN.Extension} ext  The collected super-extension node
+   */
+  function initExtension( ext ) {
+    initMembers( ext );
+    if (ext.columns)
+      initSelectItems( ext, ext.columns, ext, true );
     // there are no sub queries in extensions yet
     // Remark: sub queries not yet allowed in `extend … with columns`
   }
@@ -588,6 +677,11 @@ function define( model ) {
       parent._subArtifacts[id.substring( dot + 1 )] = art; // not dictAdd()
   }
 
+  /**
+   * Report a duplicate-definition error for `art` if it was flagged as a redefinition
+   * during phase 1.  Extensions (`extend`/`annotate`) are silently skipped because
+   * they are merged and only kept as `$duplicates` for LSP purposes.
+   */
   // TODO: message ids
   // Called by initMainArtifact() and initVocabulary() and for members
   function checkRedefinition( art ) {
@@ -660,24 +754,53 @@ function define( model ) {
     }
   }
 
+  /**
+   * Initialise all queries of a query-bearing artifact and store them in `$queries`.
+   *
+   * Also create helper artifacts like for `$projection` and set various links
+   * (`_parent`, `_$next`, `_origin`) for the name resolution in queries.
+   *
+   * Also moves pre-existing `elements` (for basic "specified elements" support)
+   * aside into `elements$` so the populate phase can merge them later.
+   *
+   * @param {XSN.Artifact} art  An entity, view, type, or event with a `query` property
+   */
   function initArtifactQuery( art ) {
     art.$queries = [];
-    setLink( art, '_from', [] ); // for sequence of resolve steps - TODO: remove
-    if (!setLink( art, '_leadingQuery', initQueryExpression( art.query, art ) ) )
-      return;                   // null or undefined in case of parse error
-    // if (art._leadingQuery !== art.$queries [0]) throw Error('FOO');
-    setLink( art._leadingQuery, '_$next', art );
+    const leading = initQueryExpression( art.query, art );
+    if (!leading)
+      return;
+    if (leading !== art.$queries[0])
+      throw new CompilerAssertion( `Invalid leading query of ${ art.name.id }` );
+
+    setLink( art, '_origin', leading._origin );
+    // Remark: setting _origin to `leading` would break `extend … with columns`
+    setLink( leading, '_$next', art );
     if (art.elements) { // specified element via compilation of client-style CSN
-      // TODO: consider this part of a revamped on-demand 'extend' functionality
+      // TODO: consider this part of the normal 'extend' functionality
       setLink( art, 'elements$', art.elements );
       delete art.elements;
     }
   }
 
-  // art is:
-  // - entity/event/type for top-level queries (including UNION args)
-  // - $tableAlias for sub query in FROM - TODO: what about UNION there?
-  // - $query for real sub query (in columns, WHERE, ...), again: what about UNION there?
+  /**
+   * Recursively initialise a query expression node — either a `SELECT` or a set
+   * operation (`UNION`/`INTERSECT`/…).  For `SELECT`, drives `initQuery`,
+   * `initTableExpression`, `initMixins`, and the implicit `$self`/`$projection`
+   * table-alias registration.  For set operations, delegates to each operand and
+   * propagates `ORDER BY`/`LIMIT` clauses onto the leading query.
+   * Returns the leading query node (the innermost leftmost `SELECT`), or `undefined`
+   * on parse error.
+   *
+   * `art` is:
+   * - entity/event/type for top-level queries (including UNION args)
+   * - $tableAlias for sub query in FROM - TODO: what about UNION there?
+   * - $query for real sub query (in columns, WHERE, ...) - what about UNION there?
+   *
+   * @param {XSN.Query|null} query
+   * @param {XSN.Artifact|XSN.Query} art  Owning artifact or parent alias
+   * @returns {XSN.Query|undefined}
+   */
   function initQueryExpression( query, art ) {
     if (!query)                 // parse error
       return query;
@@ -705,38 +828,49 @@ function define( model ) {
         query.$tableAliases.$projection = projection;
       }
       initSubQuery( query );    // check for SELECT clauses after from / mixin
+      return query;
     }
-    else if (query.args) {      // UNION, INTERSECT, ..., query in parens
-      const leading = initQueryExpression( query.args[0], art );
-      for (const q of query.args.slice(1))
-        initQueryExpression( q, art );
-      setLink( query, '_leadingQuery', leading );
-      if (leading) {
-        if (query.orderBy) {
-          leading.$orderBy ??= [ ];
-          leading.$orderBy.push( ...query.orderBy );
-        }
-        if (query.limit) {
-          leading.$limit ??= [ ];
-          leading.$limit.push( query.limit );
-        }
+    if (query.args) {           // UNION, INTERSECT, ...
+      let leading = null;       // first SELECT
+      for (const q of query.args) {
+        const sub = initQueryExpression( q, art );
+        leading ??= sub;
       }
-      // ORDER BY and LIMIT to be evaluated in leading query
-    }
-    else { // with parse error (`select from <EOF>`, `select from E { *, ( select }`)
-      // TODO: call initQuery() anyway to avoid Error[expr-no-subquery] also for
-      // UNIONs (test3/Queries/DollarSelf/CorruptedSource.err.cds), see also
-      // resolveExprNode()
-      return undefined;
+      setLink( query, '_origin', leading?._origin ?? false );
+      if (!leading)
+        return false; // potentially with parse error, false not overwritten by `??=`
+      // ORDER BY and LIMIT to be evaluated according to elements of first SELECT:
+      if (query.orderBy) {
+        leading.$orderBy ??= [ ];
+        leading.$orderBy.push( ...query.orderBy );
+      }
+      if (query.limit) {
+        leading.$limit ??= [ ];
+        leading.$limit.push( query.limit );
+      }
+      return leading;
     }
-    return query._leadingQuery || query;
+    // with parse error (`select from <EOF>`, `select from E { *, ( select }`)
+    // TODO: call initQuery() anyway to avoid Error[expr-no-subquery] also for
+    // UNIONs (test3/Queries/DollarSelf/CorruptedSource.err.cds), see also
+    // resolveExprNode()
+    return undefined;
   }
 
+  /**
+   * Assign `kind: 'select'` and a numeric name to `query`, register it in
+   * `main.$queries`, and set up `_block`, `_$next`, `_parent`, `$tableAliases`,
+   * and `dependsOn` links needed by the populate and resolve phase.
+   *
+   * @param {XSN.Query} query
+   * @param {XSN.Artifact|XSN.TableAlias} art  Owning artifact or enclosing table alias
+   */
   function initQuery( query, art ) {
     setLink( query, '_block', art._block );
     const main = art._main || art;
     setLink( query, '_$next',
              (art.kind === '$tableAlias' ? art._parent._$next : art ) );
+    setLink( query, '_origin', null ); // set later in initTableExpression → addAsAlias
     query.kind = 'select';
     query.name = { location: query.location, id: main.$queries.length + 1 };
     setMemberParent( query, null, main );
@@ -747,6 +881,17 @@ function define( model ) {
     dependsOnSilent( main, query );
   }
 
+  /**
+   * Initialise a table expression in a FROM clause: path references, sub-selects,
+   * and JOIN trees.  Path references and sub-selects become `$tableAlias` nodes
+   * registered in `query.$tableAliases`.  JOIN trees are traversed recursively;
+   * each arm with an ON clause becomes a `$join` node whose aliases are also
+   * propagated upward via `joinParents` for restriction checking.
+   *
+   * @param {XSN.TableExpr|null} table
+   * @param {XSN.Query} query
+   * @param {XSN.JoinNode[]} joinParents  Stack of enclosing JOIN nodes with ON clauses
+   */
   // table is table expression in FROM, becomes an alias
   function initTableExpression( table, query, joinParents ) {
     if (!table)                 // parse error
@@ -764,9 +909,6 @@ function define( model ) {
       }
       addAsAlias( table, query, joinParents );
       // _origin is set when we resolve the ref
-      if (query._parent.kind !== 'select')
-        query._main._from.push( table ); // store tabref if outside "real" subquery
-      // (tab refs on the right of union are unnecessary)
     }
     else if (table.query) {
       if (!table.name?.id) {
@@ -816,10 +958,22 @@ function define( model ) {
     }
   }
 
+  /**
+   * Register `table` as a `$tableAlias` in `query.$tableAliases` and, for JOIN
+   * contexts, in each enclosing JOIN node's `$tableAliases` (for alias restriction
+   * checks).  Report duplicate alias names and warn when a user-written alias
+   * starts with `$`.
+   *
+   * @param {XSN.TableAlias} table
+   * @param {XSN.Query} query
+   * @param {XSN.JoinNode[]} joinParents
+   */
   function addAsAlias( table, query, joinParents ) {
     table.kind = '$tableAlias';
     setLink( table, '_block', query._block );
     setMemberParent( table, table.name.id, query );
+    if (!query._origin)
+      setLink( query, '_origin', table );
     dictAdd( query.$tableAliases, table.name.id, table, ( name, loc, tableAlias ) => {
       if (tableAlias.name.$inferred === '$internal') {
         const semanticLoc = tableAlias.query?.name ? tableAlias.query : tableAlias;
@@ -847,6 +1001,12 @@ function define( model ) {
     }
   }
 
+  /**
+   * Walk sub-query nodes embedded inside a SELECT's ON, WHERE, HAVING, column list,
+   * and members, and drive `initQueryExpression` for each.
+   *
+   * @param {XSN.Query|XSN.JoinNode} query
+   */
   function initSubQuery( query ) {
     if (query.on)
       initExprForQuery( query.on, query );
@@ -859,6 +1019,14 @@ function define( model ) {
     initMembers( query );
   }
 
+  /**
+   * Recursively find and initialise sub-query nodes embedded inside an expression
+   * (WHERE, HAVING, ON, column values).  Descend into `args` arrays and named
+   * argument objects; calls `initQueryExpression` for any `expr.query` encountered.
+   *
+   * @param {XSN.Expr|XSN.Expr[]|null} expr
+   * @param {XSN.Query} query  Enclosing query that owns the expression
+   */
   function initExprForQuery( expr, query ) {
     // TODO: use traverseExpr()
     if (Array.isArray( expr )) { // TODO: old-style $parens ?
@@ -876,6 +1044,14 @@ function define( model ) {
     }
   }
 
+  /**
+   * Initialise all MIXIN definitions of `query`: set parent/block links, check for
+   * duplicates, register each mixin as a `$tableAlias` in `query.$tableAliases`,
+   * and warn when a mixin name starts with `$`.
+   *
+   * @param {XSN.Query} query
+   * @param {XSN.Artifact} art  Main artifact owning the query (provides `_block`)
+   */
   function initMixins( query, art ) {
     forEachInOrder( query, 'mixin', initMixin );
 
@@ -898,6 +1074,20 @@ function define( model ) {
     }
   }
 
+  /**
+   * Initialise the select-item list of a query or expand/inline column.  Iterates
+   * over `columns` (or `parent.expand`/`parent.inline`) and for each item:
+   * - tracks the first wildcard (`*`) and rejects subsequent ones;
+   *   reports a warning when `excluding` is used without a wildcard
+   * - assigns `kind: 'element'`, sets parent/block links, infers a column alias
+   *   via `ensureColumnName`, recurses into nested expand/inline, and calls
+   *   `initExprForQuery` for sub-queries in column values.
+   *
+   * @param {XSN.Query|XSN.Column} parent   Node that owns the column list
+   * @param {XSN.Column[]|null}    columns  Explicit column array, or `null` to use expand/inline
+   * @param {XSN.Query}            user     Enclosing query (for semantic location in messages)
+   * @param {boolean}             [inExtension]  `true` when processing `extend … with columns`
+   */
   function initSelectItems( parent, columns, user, inExtension = false ) {
     let wildcard = !!inExtension; // no `extend … with columns { * }`
     // TODO: forbid expand/inline in ref-where, outside queries (CSN), ...
@@ -1023,10 +1213,16 @@ function define( model ) {
     return col.name.id;
   }
 
+  /**
+   * Report a CDL-style type cast to an anonymous structure or an expand with an
+   * explicit type as a syntax error.  Called for every column during select-item
+   * initialisation.  Rejection happens here (rather than in `checks.js`) so that
+   * it is also enforced during `parseCdl`.
+   *
+   * @param {XSN.Column} col
+   */
   function checkCdlTypeCast( col ) { // with #13933:
-    // We don't allow CDL-style casts to anonymous structures.  We reject it already here
-    // and not in checks.js to ensure that it's rejected in parseCdl.
-    // TODO: via <guard> in CdlGrammar.g4
+    // TODO: do via <guard> in CdlGrammar.g4 ?
     if (col.elements) {
       error( 'type-invalid-cast', [ (col.elements[$location] ?? col.location), col ],
              { '#': 'to-inline-structure' } );
@@ -1042,8 +1238,13 @@ function define( model ) {
   // Members (elements, enum, actions, params): ---------------------------------
 
   /**
-   * Set property `_parent` for all elements in `parent` to `parent` and do so
-   * recursively for all sub elements.
+   * Initialise for all members of `parent`: resolves the concrete member container
+   * (following `items`/`many` wrappers via `initItemsLinks`), reports a scale-without-
+   * precision error on type extensions, detects inline aspects on managed compositions
+   * (delegating to `initAnonymousAspect`), and then calls `initArtifact` for every
+   * element, enum value, foreign key, action, param, and RETURNS declaration.
+   *
+   * @param {XSN.Artifact|XSN.Element|XSN.Query|XSN.Extension} parent
    */
   function initMembers( parent ) {
     // TODO: combine with initMembers() - better structuring
@@ -1084,6 +1285,18 @@ function define( model ) {
     }
   }
 
+  /**
+   * Initialise the inline aspect that appears as the `targetAspect` of a managed
+   * composition element.  Sets up `_outer`, `_parent`, `_block`, `_main`, and
+   * `$self` links on `targetAspect`, promotes its kind to `'aspect'`, and injects
+   * a synthetic `up_` `$navElement` when the composition is directly inside an
+   * entity (so that references to `up_` inside the aspect resolve correctly).
+   *
+   * @param {XSN.Element} parent        The composition element that owns the inline aspect
+   * @param {XSN.Element} obj           The resolved composition element (may differ via `items`)
+   * @param {XSN.InlineAspect} targetAspect  The inline aspect node to initialise
+   * @returns {XSN.InlineAspect}
+   */
   function initAnonymousAspect( parent, obj, targetAspect ) {
     // TODO: main?
     const inEntity = parent._main?.kind === 'entity';
@@ -1118,6 +1331,19 @@ function define( model ) {
     return targetAspect;
   }
 
+  /**
+   * Initialise for a single member (element, enum value, foreign key, action,
+   * function, or parameter).  Infers a missing name from the last path component
+   * of `targetElement`/`value`, sets `_block`/`_parent`/`_main` links, checks for
+   * duplicates, recurses into sub-members, and — for action/function params —
+   * sets up the bound `$self` parameter.  Also promotes elements with a `value`
+   * expression to calculated elements (`$syntax: 'calc'`) and creates the
+   * companion `$calcDepElement`.
+   *
+   * @param {XSN.Artifact|XSN.Element|XSN.Query} parent  Enclosing node
+   * @param {XSN.Element} elem
+   * @param {string} name  Relative member name (empty string `''` for RETURNS)
+   */
   // TODO: combine with initMembers()
   function initArtifact( parent, elem, name ) {
     if (!elem.name && !elem._outer) {

package/node_modules/@sap/cds-compiler/lib/compiler/dictionaries.js

@@ -86,6 +86,8 @@ function dictAddArray( dict, name, entry, messageCallback ) {
 function dictFirst( dict ) {
   if (!dict)
     return dict;
+  // Remark: previously, we had a loop and returned directly there.
+  // Earlier tests showed that this is faster, but SonarQube did not like it.
   const names = Object.keys( dict );
   return names.length ? dict[names[0]] : null;
 }