@sap/cds-compiler 3.9.4 → 4.0.2

package/lib/base/messages.js

@@ -12,9 +12,11 @@ const _messageIdsWithExplanation = require('../../share/messages/message-explana
 const { analyseCsnPath, traverseQuery } = require('../model/csnRefs');
 const { CompilerAssertion } = require('./error');
 const { getArtifactName } = require('../compiler/base');
+const { cdlNewLineRegEx } = require('../language/textUtils');
 
 const fs = require('fs');
 const path = require('path');
+const { inspect } = require('util')
 
 // term instance for messages
 const colorTerm = term();
@@ -41,12 +43,12 @@ function hasErrors( messages ) {
  *
  * @param {CompileMessage[]} messages
  * @param {string} moduleName
+ * @param {CSN.Options} options
  * @returns {boolean}
  */
-function hasNonDowngradableErrors( messages, moduleName, deprecatedDowngradable ) {
+function hasNonDowngradableErrors( messages, moduleName, options ) {
   return messages &&
-    messages.some( m => m.severity === 'Error' &&
-                   !isDowngradable( m.messageId, moduleName, deprecatedDowngradable ));
+    messages.some( m => m.severity === 'Error' && !isDowngradable( m.messageId, moduleName, options ));
 }
 
 /**
@@ -56,10 +58,10 @@ function hasNonDowngradableErrors( messages, moduleName, deprecatedDowngradable
  *
  * @param {string} messageId
  * @param {string} moduleName
- * @param {boolean} deprecatedDowngradable
+ * @param {CSN.Options} options Options used to check for test mode and beta flags.
  * @returns {boolean}
  */
-function isDowngradable( messageId, moduleName, deprecatedDowngradable ) {
+function isDowngradable( messageId, moduleName, options ) {
   if (!messageId || !centralMessages[messageId])
     return false;
 
@@ -74,43 +76,40 @@ function isDowngradable( messageId, moduleName, deprecatedDowngradable ) {
   const { configurableFor } = msg;
   return (Array.isArray( configurableFor ))
     ? configurableFor.includes( moduleName )
-    : configurableFor && (configurableFor !== 'deprecated' || deprecatedDowngradable);
+    : configurableFor && (configurableFor !== 'deprecated' || isDeprecatedEnabled( options, 'downgradableErrors' ));
 }
 
 /**
  * Class for combined compiler errors.  Additional members:
- *   `errors`: vector of errors (CompileMessage and errors from peg.js)
- *   `model`: the CSN model
- * TODO: standard param order
- * @class CompilationError
- * @extends {Error}
+ * - `messages`: array of compiler messages (CompileMessage)
+ * - `model`: the CSN model
  */
 class CompilationError extends Error {
   /**
-   * Creates an instance of CompilationError.
-   * @param {array} messages vector of errors
+   * @param {CompileMessage[]} messages
    * @param {XSN.Model} [model] the XSN model, only to be set with options.attachValidNames
-   * @param {string} [text] Text of the error
-   * @param {any} args Any args to pass to the super constructor
-   *
-   * @memberOf CompilationError
    */
-  constructor(messages, model, text, ...args) {
-    super( text || `CDS compilation failed\n${ messages.map( m => m.toString() ).join('\n') }`,
-      // @ts-ignore Error does not take more arguments according to TypeScript...
-           ...args );
+  constructor(messages, model) {
+    // TODO(v5): Don't store stringified messages.
+    super( `CDS compilation failed\n${messages?.map( m => m.toString() ).join('\n') || ''}` );
+    /** @since v4.0.0 */
+    this.code = 'ERR_CDS_COMPILATION_FAILURE';
     this.messages = messages;
 
-    /** @type {boolean} model */
-    this.hasBeenReported = false; // TODO: remove this bin/cdsc.js specifics
+    // TODO: remove this bin/cdsc.js specifics
+    Object.defineProperty( this, 'hasBeenReported', { value: false, configurable: true, writable: true, enumerable: false } );
     // property `model` is only set with options.attachValidNames:
     Object.defineProperty( this, 'model', { value: model || undefined, configurable: true } );
   }
 
-  toString() {                  // does not really help -> set message
-    return this.message.includes('\n')
-      ? this.message
-      : `${ this.message }\n${ this.messages.map( m => m.toString() ).join('\n') }`;
+  /**
+   * Called by `console.*()` functions in NodeJs. To avoid `err.messages` being
+   * printed using `util.inspect()`.
+   *
+   * @return {string}
+   */
+  [inspect.custom]() {
+    return this.stack || this.message;
   }
 
   /**
@@ -140,8 +139,7 @@ class CompileMessage {
    */
   constructor(location, msg, severity = 'Error', id = null, home = null, moduleName = null) {
     this.message = msg;
-    this.location = location;
-    this.$location = { ...this.location, address: undefined };
+    this.$location = { ...location, address: undefined };
     this.validNames = null;
     this.home = home;  // semantic location, e.g. 'entity:"E"/element:"x"'
     this.severity = severity;
@@ -180,16 +178,12 @@ const severitySpecs = {
  * @param {object} msg The CompileMessage.
  * @param {CSN.Options} options
  * @param {string} moduleName
- * @param {boolean} deprecatedDowngradable
  * @returns {MessageSeverity}
  */
-function reclassifiedSeverity( msg, options, moduleName, deprecatedDowngradable ) {
+function reclassifiedSeverity( msg, options, moduleName ) {
   const spec = centralMessages[msg.messageId] || { severity: msg.severity, configurableFor: null, errorFor: null };
   if (spec.severity === 'Error') {
-    const { configurableFor } = spec;
-    if (!(Array.isArray( configurableFor )
-      ? configurableFor.includes( moduleName )
-      : configurableFor && (configurableFor !== 'deprecated' || deprecatedDowngradable)))
+    if (!isDowngradable(msg.messageId, moduleName, options))
       return 'Error';
   }
   else {
@@ -311,7 +305,6 @@ function makeMessageFunction( model, options, moduleName = null ) {
   }
 
   const hasMessageArray = !!options.messages;
-  const deprecatedDowngradable = isDeprecatedEnabled( options, '_downgradableErrors' );
   /**
    * Array of collected compiler messages. Only use it for debugging. Will not
    * contain the messages created during a `callTransparently` call.
@@ -362,12 +355,12 @@ function makeMessageFunction( model, options, moduleName = null ) {
     if (id) {
       if (options.testMode && !options.$recompile)
         _check$Consistency( id, moduleName, severity, texts, options );
-      msg.severity = reclassifiedSeverity(msg, options, moduleName, deprecatedDowngradable );
+      msg.severity = reclassifiedSeverity( msg, options, moduleName );
     }
 
     messages.push( msg );
     hasNewError = hasNewError || msg.severity === 'Error' &&
-      !(options.testMode && isDowngradable( msg.messageId, moduleName, deprecatedDowngradable ));
+      !(options.testMode && isDowngradable( msg.messageId, moduleName, options ));
     if (!hasMessageArray)
       console.error( messageString( msg ) );
     return msg;
@@ -410,7 +403,7 @@ function makeMessageFunction( model, options, moduleName = null ) {
 
   /**
    * Normalize the given location. Location may be a CSN path, XSN/CSN location or an
-   * array of the form `[CSN.Location, user, suffix]`.
+   * array of the form `[CSN.Location, XSN user, suffix]`.
    *
    * @param {any} location
    * @returns {[CSN.Location, string, string]} Location, semantic location and definition.
@@ -514,7 +507,7 @@ function makeMessageFunction( model, options, moduleName = null ) {
     if (!messages || !messages.length)
       return;
     const hasError = options.testMode ? hasNonDowngradableErrors : hasErrors;
-    if (hasError( messages, moduleName, deprecatedDowngradable ))
+    if (hasError( messages, moduleName, options ))
       throw new CompilationError( messages, options.attachValidNames && model );
   }
 
@@ -526,13 +519,13 @@ function makeMessageFunction( model, options, moduleName = null ) {
   function reclassifyMessagesForModule() {
     for (const msg of messages) {
       if (msg.messageId && msg.severity !== 'Error') {
-        const severity = reclassifiedSeverity(msg, options, moduleName, deprecatedDowngradable);
+        const severity = reclassifiedSeverity( msg, options, moduleName );
         if (severity !== msg.severity) {
           msg.severity = severity;
           // Re-set the module regardless of severity, since we reclassified it.
           Object.defineProperty( msg, '$module', { value: moduleName, configurable: true } );
           hasNewError = hasNewError || severity === 'Error' &&
-            !(options.testMode && isDowngradable( msg.messageId, moduleName, deprecatedDowngradable ));
+            !(options.testMode && isDowngradable( msg.messageId, moduleName, options ));
         }
       }
     }
@@ -621,7 +614,7 @@ function _check$Severities( id, moduleName, severity ) {
     return;
   }
   // now try whether the message could be something less than an Error in the module due to user wishes
-  if (!isDowngradable( id, moduleName, true )) { // always an error in module
+  if (!isDowngradable(id, moduleName, { testMode: true, deprecated: { downgradableErrors: true } } )) { // always an error in module
     if (severity !== 'Error')
       throw new CompilerAssertion( `Inconsistent severity: Expecting "Error", not "${ severity }" for message ID "${ id }" in module "${ moduleName }"` );
   }
@@ -656,7 +649,7 @@ function _check$Texts( id, prop, val ) {
 }
 
 const quote = {            // could be an option in the future
-  double: p => `“${ p }”`, // for names, including annotation names (with preceeding `@`)
+  double: p => `“${ p }”`, // for names, including annotation names (with preceding `@`)
   single: p => `‘${ p }’`, // for other things cited from or expected in the model
   angle: p => `‹${ p }›`, // for tokens like ‹Identifier›, and similar
   direct: p => p,          // e.g. for numbers _not cited from or expected in_ the source
@@ -786,7 +779,7 @@ function quoted( name ) {
 
 function tokenSymbol( token ) {
   if (token.match( /^[A-Z][A-Z]/ )) // keyword
-    return quote.upper( token );
+    return keyword( token );
   else if (token.match( /^[A-Z][a-z]/ )) // Number, Identifier, ...
     return quote.angle( token );
   if (token.startsWith('\'') && token.endsWith('\'')) // operator token symbol
@@ -803,12 +796,8 @@ function transformElementRef( arg ) {
   if (arg.ref) {
     // Can be used by CSN backends to create a simple path such as E:elem
     return quoted(arg.ref.map((ref) => {
-      if (ref.id) {
-        // Indicate that the path has a filter.
-        if (ref.where)
-          return `${ ref.id }[…]`;
-        return ref.id;
-      }
+      if (ref.id)
+        return `${ ref.id }${ref.args ? '(…)' : ''}${ref.where ? '[…]' : ''}`;
       return ref;
     }).join('.'));
   }
@@ -914,26 +903,54 @@ function weakLocation( loc ) {
 }
 
 /**
- * Return message string with location if present in compact form (i.e. one line)
+ * Return message string with location if present in compact form (i.e. one line).
+ *
+ * IMPORTANT:
+ *   cds-compiler <v4 used following signature:
+ *   `messageString( err, normalizeFilename, noMessageId, noHome, moduleName = undefined ) : string`
+ *   This signature is still supported for backwards compatibility but is deprecated.
  *
  * Example:
  *   <source>.cds:3:11: Error message-id: Can't find type `nu` in this scope (in entity:“E”/element:“e”)
  *
  * @param {CompileMessage} err
- * @param {boolean} [normalizeFilename]
- * @param {boolean} [noMessageId]
- * @param {boolean} [noHome]
+ *
+ * @param {object} [config = {}]
+ *
+ * @param {boolean} [config.normalizeFilename]
+ *     If true, the file path will be normalized to use `/` as the path separator (instead of `\` on Windows).
+ *
+ * @param {boolean} [config.noMessageId]
+ *     If true, will _not_ show the message ID (+ explanation hint) in the output.
+ *
+ * @param {boolean} [config.noHome]
+ *     If true, will _not_ show message's semantic location.
+ *
+ * @param {string} [config.module]
+ *     If set, downgradable error messages will get a '‹↓›' marker, depending on whether
+ *     the message can be downgraded for the given module.
+ *
  * @returns {string}
  */
-function messageString( err, normalizeFilename, noMessageId, noHome, moduleName = undefined ) {
-  const location = (err.$location?.file ? `${ locationString( err.$location, normalizeFilename ) }: ` : '');
+function messageString( err,  config ) {
+  // backwards compatibility <v4
+  if (!config || typeof config === 'boolean' || arguments.length > 2) {
+    config = {
+      normalizeFilename: arguments[1],
+      noMessageId: arguments[2],
+      noHome: arguments[3],
+      module: arguments[4],
+    };
+  }
+
+  const location = (err.$location?.file ? `${ locationString( err.$location, config.normalizeFilename ) }: ` : '');
   const severity = err.severity || 'Error';
-  const downgradable = severity === 'Error' && moduleName &&
-    isDowngradable(err.messageId, moduleName, false) ? '‹↓›' : '';
+  const downgradable = severity === 'Error' && config.module &&
+    isDowngradable(err.messageId, config.module, {}) ? '‹↓›' : '';
   // even with noHome, print err.home if the location is weak
-  const home = !err.home || noHome && err.$location?.endLine ? '' : ` (in ${ err.home })`;
+  const home = !err.home || config.noHome && err.$location?.endLine ? '' : ` (in ${ err.home })`;
   // TODO: the plan was with brackets = `Error[ref-undefined-def]`
-  const id = err.messageId && !noMessageId ? ` ${ err.messageId }` : '';
+  const id = err.messageId && !config.noMessageId ? ` ${ err.messageId }` : '';
   return `${ location }${ severity }${ downgradable }${ id }: ${ err.message }${ home }`;
 }
 
@@ -957,91 +974,151 @@ function messageHash( msg ) {
 }
 
 /**
- * Returns a message string with file- and semantic location if present
- * in multiline form.
- *
- * Example:
- * ```txt
- * Error[message-id]: Can't find type `nu` in this scope
- *    |
- *   <source>.cds:3:11, at entity:“E”/element:“e”
- * ```
+ * Returns a message string with file- and semantic location if present in multiline form
+ * with a source code snippet below that has highlights for the message's location.
+ * The message (+ message id) are colored according to their severity.
  *
  * @param {CompileMessage} err
+ *
  * @param {object} [config = {}]
- * @param {boolean} [config.normalizeFilename] Replace windows `\` with forward slashes `/`.
+ *
+ * @param {boolean} [config.normalizeFilename]
+ *     If true, the file path will be normalized to use `/` as the path separator (instead of `\` on Windows).
+ *
  * @param {boolean} [config.noMessageId]
- * @param {boolean} [config.hintExplanation] If true, messages with explanations will get a "…" marker.
- * @param {boolean} [config.withLineSpacer]  If true, an additional line (with `|`) will be inserted between message and location.
- * @param {boolean | 'auto'} [config.color]  If true, ANSI escape codes will be used for coloring the severity.  If false, no
- *                                           coloring will be used.  If 'auto', we will decide based on certain factors such
- *                                           as whether the shell is a TTY and whether the environment variable 'NO_COLOR' is
- *                                           unset.
+ *     If true, will _not_ show the message ID (+ explanation hint) in the output.
+ *
+ * @param {boolean} [config.hintExplanation]
+ *     If true, messages with explanations will get a "…" marker.
+ *
+ * @param {string} [config.module]
+ *     If set, downgradable error messages will get a '‹↓›' marker, depending on whether
+ *     the message can be downgraded for the given module.
+ *
+ * @param {Record<string, string>} [config.sourceMap]
+ *     A dictionary of filename<->source-code entries.  You can pass the `fileCache` that is used
+ *     by the compiler.
+ *
+ * @param {Record<string, number[]>} [config.sourceLineMap]
+ *     A dictionary of filename<->source-newline-indices entries. Is used to extract source code
+ *     snippets for message locations.  If not set, will be set and filled by this function on-demand.
+ *     An entry is an array of character/byte offsets to new-lines, for example sourceLineMap[1] is the
+ *     end-newline for the second line.
+ *
+ * @param {string} [config.cwd]
+ *     The current working directory (cwd) that was passed to the compiler.
+ *     This value is only used if a source map is provided and relative paths needs to be
+ *     resolved to absolute ones.
+ *
+ * @param {boolean | 'auto' | 'never' | 'always'} [config.color]
+ *     If true/'always', ANSI escape codes will be used for coloring the severity.  If false/'never',
+ *     no coloring will be used.  If 'auto', we will decide based on certain factors such
+ *     as whether the shell is a TTY and whether the environment variable `NO_COLOR` is
+ *     unset.
+ *
  * @returns {string}
  */
 function messageStringMultiline( err, config = {} ) {
   colorTerm.changeColorMode(config ? config.color : 'auto');
 
   const explainHelp = (config.hintExplanation && hasMessageExplanation(err.messageId)) ? '…' : '';
-  const msgId = (err.messageId && !config.noMessageId) ? `[${ err.messageId }${ explainHelp }]` : '';
   const home = !err.home ? '' : (`at ${ err.home }`);
   const severity = err.severity || 'Error';
+  const downgradable = config.module && severity === 'Error' &&
+    isDowngradable(err.messageId, config.module, {}) ? '‹↓›' : '';
+  const msgId = (err.messageId && !config.noMessageId) ? `[${ err.messageId }${downgradable}${ explainHelp }]` : '';
 
   let location = '';
-  if (err.$location && err.$location.file) {
+  let context = '';
+  if (err.$location?.file) {
     location += locationString( err.$location, config.normalizeFilename );
     if (home)
       location += ', ';
+    context = _messageContext(err, config);
+    if (context !== '')
+      context = `\n${context}`;
   }
   else if (!home) {
     return `${ colorTerm.severity(severity, severity + msgId) } ${ err.message }`;
   }
 
-  let lineSpacer = '';
-  if (config.withLineSpacer) {
-    const additionalIndent = err.$location ? `${ err.$location.endLine || err.$location.line || 1 }`.length : 1;
-    lineSpacer = `\n  ${ ' '.repeat( additionalIndent ) }|`;
+  const additionalIndent = err.$location ? `${ err.$location.endLine || err.$location.line || 1 }`.length : 1;
+  const lineSpacer = `\n  ${ ' '.repeat( additionalIndent ) }|`;
+
+  return `${ colorTerm.severity(severity, severity + msgId) }: ${ err.message }${ lineSpacer }\n  ${ location }${ home }${context}`;
+}
+
+/**
+ * Used by _messageContext() to create an array of line start offsets.
+ * Each entry in the returned array contains the offset for the start line,
+ * where the line is the index in the array.
+ *
+ * @param source
+ * @return {number[]}
+ * @private
+ */
+function _createSourceLineMap(source) {
+  const newlines = [ 0 ];
+
+  const re = new RegExp(cdlNewLineRegEx, 'g');
+  let line;
+  while((line = re.exec(source)) !== null) {
+    newlines.push(line.index + line[0].length);
   }
+  newlines.push(source.length); // EOF marker
 
-  return `${ colorTerm.severity(severity, severity + msgId) }: ${ err.message }${ lineSpacer }\n  ${ location }${ home }`;
+  return newlines;
 }
 
 /**
- * Returns a context (code) string that is human readable (similar to rust's compiler)
+ * Returns a context (code) string that is human-readable (similar to rust's compiler).
+ *
+ * IMPORTANT: In case that `config.sourceMap[err.loc.file]` does not exist, this function
+ *            uses `path.resolve()` to get the absolute filename.
  *
  * Example Output:
  *     |
  *   3 |     num * nu
  *     |           ^^
  *
- * @param {string[]} sourceLines The source code split up into lines, e.g. by `splitLines(src)`
- *                               from `lib/utils/file.js`
  * @param {CompileMessage} err Error object containing all details like line, message, etc.
- * @param {object} [config = {}]
- * @param {boolean | 'auto'} [config.color] If true, ANSI escape codes will be used for coloring the `^`.  If false, no
- *                                          coloring will be used.  If 'auto', we will decide based on certain factors such
- *                                          as whether the shell is a TTY and whether the environment variable 'NO_COLOR' is
- *                                          unset.
+ * @param {object} [config = {}] See `messageStringMultiline()` for details.
+ *
  * @returns {string}
+ * @private
  */
-function messageContext( sourceLines, err, config ) {
-  colorTerm.changeColorMode(config ? config.color : 'auto');
+function _messageContext( err, config ) {
   const MAX_COL_LENGTH = 100;
 
   const loc = err.$location;
-  if (!loc || !loc.line)
+  if (!loc || !loc.line || !loc.file || !config.sourceMap)
+    return '';
+
+  let filepath = config.sourceMap[loc.file]?.realname || loc.file;
+  if (!config.sourceMap[filepath])
+    filepath = path.resolve(config.cwd || '', filepath);
+
+  const source = config.sourceMap[filepath];
+  if (!source || source === true) // true: file exists, no further knowledge
     return '';
 
+  if (!config.sourceLineMap)
+    config.sourceLineMap = Object.create(null);
+  if (!config.sourceLineMap[filepath])
+    config.sourceLineMap[filepath] = _createSourceLineMap(source);
+
+  const sourceLines = config.sourceLineMap[filepath];
 
   // Lines are 1-based, we need 0-based ones for arrays
-  const startLine = loc.line - 1;
-  const endLine = loc.endLine ? loc.endLine - 1 : startLine;
+  const startLine = Math.min(sourceLines.length, loc.line - 1);
+  const endLine = Math.min(sourceLines.length, loc.endLine ? loc.endLine - 1 : startLine);
+  /** Only print N lines even if the error spans more lines. */
+  const maxLine = Math.min((startLine + 2), endLine);
 
   // check that source lines exists
-  if (typeof sourceLines[startLine] !== 'string' || typeof sourceLines[endLine] !== 'string')
+  if (typeof sourceLines[startLine] !== 'number')
     return '';
 
-
   const digits = String(endLine + 1).length;
   const severity = err.severity || 'Error';
   const indent = ' '.repeat(2 + digits);
@@ -1054,15 +1131,13 @@ function messageContext( sourceLines, err, config ) {
   let endColumn = (loc.endCol && loc.endCol > loc.col) ? loc.endCol - 1 : loc.col;
   endColumn = Math.min(MAX_COL_LENGTH, endColumn);
 
-  /** Only print N lines even if the error spans more lines. */
-  const maxLine = Math.min((startLine + 2), endLine);
-
   let msg = `${ indent }|\n`;
 
   // print source line(s)
   for (let line = startLine; line <= maxLine; line++) {
     // Replaces tabs with 1 space
-    let sourceCode = sourceLines[line].replace(/\t/g, ' ');
+    let sourceCode = source.substring(sourceLines[line], sourceLines[line+1] || source.length).trimEnd();
+    sourceCode = sourceCode.replace(/\t/g, ' ');
     if (sourceCode.length >= MAX_COL_LENGTH)
       sourceCode = sourceCode.slice(0, MAX_COL_LENGTH);
     // Only prepend space if the line contains any sources.
@@ -1081,7 +1156,7 @@ function messageContext( sourceLines, err, config ) {
   }
   else if (maxLine !== endLine) {
     // error spans more lines which we don't print
-    msg += `${ indent }| ...`;
+    msg += `${ indent }| …`;
   }
   else {
     msg += `${ indent }|`;
@@ -1090,6 +1165,36 @@ function messageContext( sourceLines, err, config ) {
   return msg;
 }
 
+/**
+ * Returns a context (code) string that is human-readable (similar to rust's compiler)
+ *
+ * Example Output:
+ *     |
+ *   3 |     num * nu
+ *     |           ^^
+ *
+ * @param {string[]} sourceLines The source code split up into lines, e.g. by `splitLines(src)`
+ *                               from `lib/utils/file.js`
+ * @param {CompileMessage} err Error object containing all details like line, message, etc.
+ * @param {object} [config = {}]
+ * @param {boolean | 'auto'} [config.color] If true, ANSI escape codes will be used for coloring the `^`.  If false, no
+ *                                          coloring will be used.  If 'auto', we will decide based on certain factors such
+ *                                          as whether the shell is a TTY and whether the environment variable 'NO_COLOR' is
+ *                                          unset.
+ * @returns {string}
+ *
+ * @deprecated Use `messageStringMultiline()` with `config.sourceMap` and `config.sourceLineMap` instead!
+ */
+function messageContext( sourceLines, err, config ) {
+  const loc = err.$location;
+  if (!loc || !loc.line|| !loc.file)
+    return '';
+
+  colorTerm.changeColorMode(config ? config.color : 'auto');
+  const sourceMap = { [err.$location.file]: sourceLines.join('\n') };
+  return _messageContext(err, { ...config, sourceMap });
+}
+
 /**
  * Compare two messages `a` and `b`. Return 0 if they are equal, 1 if `a` is
  * larger than `b`, and -1 if `a` is smaller than `b`. Messages without a location
@@ -1238,6 +1343,8 @@ function memberActionName( art ) {
 function homeName( art, absoluteOnly ) {
   if (!art)
     return art;
+  if (art._user)               // when providing a path item with filter as “user”
+    return homeName( art._user, absoluteOnly );
   if (art._outer)               // in items property
     return homeName( art._outer, absoluteOnly );
   else if (art.kind === 'source' || !art.name) // error reported in parser or on source level
@@ -1446,8 +1553,8 @@ function constructSemanticLocationFromCsnPath( model, options, csnPath ) {
         result += '/target';
       break;
     }
-    else if (step === 'xpr' || step === 'ref' || step === 'as') {
-      break; // don't go into xprs, refs, aliases, etc.
+    else if (step === 'xpr' || step === 'ref' || step === 'as' || step === 'value') {
+      break; // don't go into xprs, refs, aliases, values, etc.
     }
     else if (step === 'returns') {
       result += '/returns';
@@ -1675,7 +1782,6 @@ module.exports = {
   deduplicateMessages,
   CompileMessage,
   CompilationError,
-  isMessageDowngradable: isDowngradable,
   explainMessage,
   hasMessageExplanation,
   messageIdsWithExplanation,

package/lib/base/model.js

@@ -22,31 +22,29 @@ const queryOps = {
 const availableBetaFlags = {
   // enabled by --beta-mode
   annotationExpressions: true,
-  toRename: true,
-  assocsWithParams: true,
+  toRename: true, // Removes once it's publicly documented
+  assocsWithParams: true, // beta, because runtimes don't support it, yet.
   hanaAssocRealCardinality: true,
-  mapAssocToJoinCardinality: true,
-  ignoreAssocPublishingInUnion: true,
+  mapAssocToJoinCardinality: true, // only SAP HANA HEX engine supports it
   enableUniversalCsn: true,
-  postgres: true,
   aspectWithoutElements: true, // TODO: do not just remove beta flag - remove elements, too!
   odataTerms: true,
-  optionalActionFunctionParameters: true,
-  calculatedElementsOnWrite: true,
+  optionalActionFunctionParameters: true, // not supported by runtime, yet.
   // disabled by --beta-mode
   nestedServices: false,
-  v4preview: false,
 };
 
+// Used by isDeprecatedEnabled() to check if any flag ist set.
 const availableDeprecatedFlags = {
   // the old ones starting with _, : false
-  autoCorrectOrderBySourceRefs: true,
+  downgradableErrors: true,
+  includesNonShadowedFirst: true,
   eagerPersistenceForGeneratedEntities: true,
 }
 
 const oldDeprecatedFlags_v2 = [
   'createLocalizedViews',
-  'downgradableErrors',
+  // 'downgradableErrors', // re-added in v4
   'generatedEntityNameWithUnderscore',
   'longAutoexposed',
   'noElementsExpansion',
@@ -60,13 +58,15 @@ const oldDeprecatedFlags_v2 = [
   'shortAutoexposed',
   'unmanagedUpInComponent',
   'v1KeysForTemporal',
+  // do not add old deprecated flags which should not lead to an error:
+  // autoCorrectOrderBySourceRefs - just info would be ok
 ];
 
 /**
  * Test for early-adaptor feature, stored in option `beta`(new-style) / `betaMode`(old-style)
  * With that, the value of `beta` is a dictionary of feature=>Boolean.
  *
- * Beta features cannot be used when options.deprecated is set.
+ * Beta features cannot be used when `options.deprecated` is set.
  *
  * A feature always needs to be provided - otherwise false will be returned.
  *

package/lib/checks/.eslintrc.json

@@ -1,6 +1,6 @@
 {
   // we actually do not extend airbnb-base, as it weakens some eslint:recommended rules
-  "extends": ["../../.eslintrc-ydkjsi.json", "plugin:jsdoc/recommended"],
+  "extends": ["plugin:jsdoc/recommended", "../../.eslintrc-ydkjsi.json"],
   "plugins":  [
     "jsdoc"
   ],

package/lib/checks/annotationsOData.js

@@ -12,7 +12,7 @@
  *
  * @param {CSN.Element} member Member to be checked
  */
-function checkCoreMediaTypeAllowence( member ) {
+function checkCoreMediaTypeAllowance( member ) {
   const allowedCoreMediaTypes = {
     'cds.String': 1,
     'cds.LargeString': 1,
@@ -67,7 +67,7 @@ function checkReadOnlyAndInsertOnly( artifact, artifactName ) {
 }
 
 module.exports = {
-  checkCoreMediaTypeAllowence,
+  checkCoreMediaTypeAllowance,
   checkAnalytics,
   checkAtSapAnnotations,
   checkReadOnlyAndInsertOnly,

package/lib/checks/elements.js

@@ -153,7 +153,7 @@ function checkManagedAssoc( art ) {
 /**
  * All DB  & OData flat mode must reject recursive type usages in entities
  * 'items' break recursion as 'items' will turn into an NCLOB and the path
- * prefix to 'items' can be flattend in the DB.
+ * prefix to 'items' can be flattened in the DB.
  * In OData flat mode the first appearance of 'items' breaks out into structured
  * mode producing (legal) recursive complex types.
  *