@sap/cds-compiler 2.11.2 → 2.13.6

package/CHANGELOG.md

@@ -7,6 +7,179 @@
 Note: `beta` fixes, changes and features are usually not listed in this ChangeLog but [here](doc/CHANGELOG_BETA.md).
 The compiler behavior concerning `beta` features can change at any time without notice.
 
+## Version 2.13.6 - 2022-25-03
+
+### Fixed
+
+- to.hdbcds/hdi/sql: Correctly handle `localized` in conjunction with `@cds.persistence.exists`
+
+## Version 2.13.4 - 2022-22-03
+
+No changes compared to Version 2.13.0; fixes latest NPM tag
+
+## Version 2.13.2 - 2022-22-03
+
+No changes compared to Version 2.13.0; fixes latest NPM tag
+
+## Version 2.13.0 - 2022-22-03
+
+### Added
+
+- CDL syntax:
+  + Allow to `extend E:elem` and `annotate E:elem` instead of having to write deeply nested statements.
+  + Enable `default` values as part of scalar type definitions.
+  + The following `extend` syntax variants are now possible:
+    ```cds
+    extend … with elements { … }
+    extend … with definitions { … }
+    extend … with columns { … }
+    extend … with enum { … }
+    extend … with actions { … }
+    ```
+    This syntax expresses _how_ an artifact is extended instead of _what_ is extended.
+  + Using `ORDER BY` in generic functions such as SAP HANA's `first_value` is now possible.
+- Make API function `compileSources` accept CSN objects as file content
+- to.edm(x): Annotate view parameters with `@sap.parameter: mandatory` (V2) and `@Common.FieldControl: #Mandatory` (V4).
+- to.sql/hdi/hdbcds: Introduce the annotations `@sql.prepend` and `@sql.append` that allow inserting user-written SQL
+  snippets into the compiler generated content. Changes in annotations `@sql.prepend` and `@sql.append` are now reflected
+  in the output of `to.hdi.migration`. This enables CDS Build to produce `.hdbmigrationtable` files translating such model
+  changes into schema changes.
+- API: Lists of keywords for various backends are available as `to.<backend>[.<config>].keywords`, e.g. `to.sql.sqlite.keywords`.
+- for.odata/to.edm(x): The draft composition hull is now also taking into account compositions in subelements.
+
+### Changed
+
+- In query entities inside services, only auto-redirect associations and compositions
+  in the main query of the entity.
+- An element now inherits the property `notNull` from its query source (as
+  before) or its type (like it does for most other properties);
+  `notNull` is then not further propagated to its sub elements anymore.
+- A structure element inherits the property `virtual` from its query source (as
+  before), but does not further propagate `virtual` to its sub elements
+  (semantically of course, but the CSN is not cluttered with it);
+  there is a new warning if a previously `virtual` query entity
+  element is now considered to be non-virtual.
+- Do not propagate annotation value `null`.
+  The value `null` of an annotation (and `doc`) is used to stop the inheritance
+  of an annotation value.  This means than other than that, a value `null` should
+  not be handled differently to not having set that annotation.
+- In the effective CSN, the structure type is only expanded if something has changed
+  for associations: the `target` (`keys` does not change if the `target` does not change)
+  unmanaged associations as sub elements are not supported anyway.
+- In the effective CSN, “simple” type properties like `length`, `precision`,
+  `scale` and `srid` are propagated even for a propagation via type.
+- Update OData Vocabularies: 'Capabilities', 'Common', 'Core', 'UI'.
+- to.sql:
+  + For SQL dialect `hana` referential constraints are now appended
+    as `ALTER TABLE ADD CONSTRAINT` clause to the end of `schema.sql`.
+    With option `constraintsInCreateTable` constraints are rendered into the
+    `CREATE TABLE` statement.
+  + Referential constraint names are now prefixed with `c__`.
+
+### Fixed
+
+- Properly resolve references inside anonymous aspects:
+  + references starting with `$self.` made the compiler dump.
+  + a simple `$self` did  not always work as expected (it represents the entity created via the anonymous aspect).
+  + other references inside deeply nested anonymous aspects induced a compilation error.
+- compiler: `()` inside `ORDER BY` clause was not correctly set.
+- parse.cdl: References in `ORDER BY` and filters are now correctly resolved.
+- Issue error when trying to introduce managed compositions of aspects in `mixin`s
+- Issue error in all cases for type references to unmanaged associations.
+- Avoid dump when extending an illegal definition with a name starting with `cds.`.
+- to.sql/to.cdl/to.hdbcds/to.hdi: Render `cast()` inside `ORDER BY`, `GROUP BY` and `HAVING` properly.
+- to.sql/hdi/hdbcds:
+  + `$self` was incorrectly treated as a structured path step.
+  + Correctly handle table alias in on-condition of mixin in `exists` expansion.
+  + Correctly handle table `$self` references to aliased fields in on-condition of mixin association
+    during `exists` expansion.
+- to.edm: Don't escape `&` as `&amp;`.
+- to.edmx: Escaping compliant to XML specification:
+  + `&` and `<` are always escaped.
+  + `>` is not escaped, unless it appears in text values as `]]>`.
+  + `"` is escaped in attribute values only.
+  + Control characters are always escaped.
+- Ellipsis (`...`) in annotations in different layers but without base annotation now produces an error.
+  The old but incorrect behavior can be re-enabled with option `anno-unexpected-ellipsis-layers`.
+
+## Version 2.12.0 - 2022-01-25
+
+### Added
+
+- CDL parser: You can now use multiline string literals and text blocks.  
+  Use backticks (\`) for string literals that can span multiple lines and can use JavaScript-like escape
+  sequences such as `\u{0020}`.  You can also use three backticks (\`\`\`) for strings (a.k.a. text blocks)
+  which are automatically indentation-stripped and can have an optional language identifier that is used
+  for syntax highlighting, similar to markdown.  In difference to the former, text blocks require the
+  opening and closing backticks to be on separate lines.
+  Example:
+  ````
+  @annotation: `Multi
+   line\u{0020}strings`
+
+  @textblock: ```xml
+              <summary>
+                <detail>The root tag has no indentation in this example</detail>
+              </summary>
+              ```
+  ````
+
+- Enhance the ellipsis operator `...` for array annotations by an `up to ‹val›`:
+  only values in the array of the base annotation up to (including) the first match
+  of the specified `‹val›` are included at the specified place in the final array value.
+  An array annotation can have more than on `... up to ‹val›` items and must also
+  have a pure `...` item after them.  
+  A structured `‹val›` matches if the array item is also a structure and all property
+  values in `‹val›` are equal to the corresponding property value in the array value;
+  it is not necessary to specify all properties of the array value items in `‹val›`.
+  Example
+  ```
+  @Anno: [{name: one, val: 1}, {name: two, val: 2}, {name: four, val: 4}]
+  type T: Integer;
+  @Anno: [{name: zero, val: 0}, ... up to {name: two}, {name: three, val: 3}, ...]
+  annotate T;
+  ```
+- for.odata: Support `@cds.on {update|insert}` as replacement for deprecated `@odata.on { update|insert }` to
+  set `@Core.Computed`.
+
+### Changed
+
+- Update OData Vocabularies 'Aggregation', 'Capabilities', 'Common', 'Core', PersonalData, 'Session', 'UI'
+
+### Fixed
+
+- to.sql/hdi/hdbcds: With `exists`, ensure that the precedence of the existing association-on-conditions and where-conditions is kept by adding braces.
+- to.sql/hdi: Window function suffixes are now properly rendered.
+- to.sql: `$self` comparisons inside aspects are not checked and won't result in an error anymore.
+- to.hdbcds:
+  + Correctly apply the "."-to-"_"-translation algorithm to artifacts that are marked with `@cds.persistence.exists`.
+  + Message with ID `anno-hidden-exists` (former `anno-unstable-hdbcds`) is now
+    only issued if the compiler generates a SAP HANA CDS artifact which would hide
+    a native database object from being resolved in a SAP HANA CDS `using … as …`.
+- to.cdl: Annotation paths containing special characters such as spaces or `@` are now quoted, e.g. `@![some@annotation]`.
+- compiler: A warning is emitted for elements of views with localized keys as the localized property is ignored for them.
+
+## Version 2.11.4 - 2021-12-21
+
+### Fixed
+
+- CDL parser: in many situations, improve message when people use reserved keywords as identifier
+- Improve error text and error location for ambiguous auto-redirection target
+- to.sql/hdi/hdbcds:
+  + Correctly detect `exists` in projections
+  + Correctly handle elements starting with `$` in the on-condition of associations
+  + Correctly handle sub queries in an entity defined with `projection on`
+  + Correctly handle associations in sub queries in a `from` of a sub query
+  + foreign key constraints: respect @assert.integrity: false for compositions
+- to.hdbcds: Correctly quote elements named `$self` and `$projection`
+- to.cdl: `when` was added to the keyword list for smart quoting
+- Compiler support for code completion for `$user` and `$session` now respect user
+  provided variables in `options.variableReplacements`.
+- API: `deduplicateMessages()` no longer removes messages for `duplicate` artifact/annotation errors.
+  Prior to this version, only one of the duplicated artifacts had a message, leaving the user to
+  guess where the other duplicates were.
+
+
 ## Version 2.11.2 - 2021-12-06
 
 ### Fixed
@@ -25,8 +198,8 @@ The compiler behavior concerning `beta` features can change at any time without
   if it can't be assigned to an artifact.  For example for two subsequent doc-comments, the first doc-comment
   is ignored.  To suppress these info messages, explicitly set option `docComment` to `false`.
 - `cdsc`:
-  - `cdsc explain list` can now be used to get a list of message IDs with explanation texts.
-  - `cdsc` now respects the environment variable `NO_COLOR`. If set, no ANSI escape codes will be used.
+  + `cdsc explain list` can now be used to get a list of message IDs with explanation texts.
+  + `cdsc` now respects the environment variable `NO_COLOR`. If set, no ANSI escape codes will be used.
     Can be overwritten by `cdsc --color always`.
 - to.sql/hdi: Support SQL Window Functions
 - to.sql/hdi/hdbcds:

package/bin/.eslintrc.json

@@ -11,7 +11,6 @@
     "no-process-exit": "off",
     "camelcase": "off",
     "radix": "off",
-    // should probably be on
-    "no-shadow": "off"
+    "no-shadow": "warn"
   }
 }

package/bin/cds_update_identifiers.js

@@ -24,37 +24,39 @@
 'use strict';
 
 const parseLanguage = require('../lib/language/antlrParser');
+const { createMessageFunctions } = require('../lib/base/messages');
 
 const fs = require('fs');
 const path = require('path');
 
 const cliArgs = process.argv.slice(2);
-const filename = cliArgs[0];
+const filepath = cliArgs[0];
 
 if (cliArgs.length !== 1)
   exitError(`Expected exactly one argument, ${cliArgs.length} given`);
 
-if (!filename)
-  exitError('Expected non-empty filename as argument!');
+if (!filepath)
+  exitError('Expected non-empty filepath as argument!');
 
 // Do not use allow-list approach.
 // There may be CDS files with other extensions than `.cds`.
-if (filename.endsWith('.csn') || filename.endsWith('.json'))
+if (filepath.endsWith('.csn') || filepath.endsWith('.json'))
   exitError('Only CDS files can be passed! Found CSN file!');
 
-let source = fs.readFileSync(filename, 'utf-8');
-source = modernizeIdentifierStyle(source, filename);
-fs.writeFileSync(filename, source);
+let sourceStr = fs.readFileSync(filepath, 'utf-8');
+sourceStr = modernizeIdentifierStyle(sourceStr, filepath);
+fs.writeFileSync(filepath, sourceStr);
 process.exit(0); // success
 
 // --------------------------------------------------------
 
 function modernizeIdentifierStyle(source, filename) {
   const options = { messages: [], attachTokens: true };
+  const messageFunctions = createMessageFunctions( options, 'parse', null );
 
   // parseLanguage does not throw on CompilationError, so
   // we do not need a try...catch block.
-  const ast = parseLanguage(source, filename, options);
+  const ast = parseLanguage(source, filename, options, messageFunctions);
 
   // To avoid spam, only report errors.
   // Users should use the compiler to get all messages.

package/bin/cdsc.js

@@ -161,8 +161,7 @@ try {
       cmdLine.options.assertIntegrity === 'true' ||
       cmdLine.options.assertIntegrity === 'false'
   )
-    cmdLine.options.assertIntegrity = Boolean(cmdLine.options.assertIntegrity);
-
+    cmdLine.options.assertIntegrity = cmdLine.options.assertIntegrity === 'true';
 
   // Enable all beta-flags if betaMode is set to true
   if (cmdLine.options.betaMode)
@@ -220,7 +219,7 @@ function displayUsage(error, helpText, code) {
   out.write(`${helpText}\n`);
   if (error) {
     if (error instanceof Array)
-      out.write(`${error.map(error => `cdsc: ERROR: ${error}`).join('\n')}\n`);
+      out.write(`${error.map(err => `cdsc: ERROR: ${err}`).join('\n')}\n`);
     else
       out.write(`cdsc: ERROR: ${error}\n`);
   }
@@ -294,11 +293,11 @@ function executeCommandLine(command, options, args) {
   // Return the original model (for chaining)
   function toCsn( model ) {
     if (options.directBackend) {
-      displayNamedCsn(model, 'csn', options);
+      displayNamedCsn(model, 'csn');
     }
     else {
       // Result already provided by caller
-      displayNamedXsn(model, 'csn', options);
+      displayNamedXsn(model, 'csn');
     }
     return model;
   }
@@ -309,7 +308,7 @@ function executeCommandLine(command, options, args) {
     const csn = options.directBackend ? model : compactModel(model, options);
 
     if (options.toHana && options.toHana.csn) {
-      displayNamedCsn(for_hdbcds(csn, remapCmdOptions(options, options.toHana)), 'hana_csn', options);
+      displayNamedCsn(for_hdbcds(csn, remapCmdOptions(options, options.toHana)), 'hana_csn');
     }
     else {
       const hanaResult = main.to.hdbcds(csn, remapCmdOptions(options, options.toHana));
@@ -332,7 +331,7 @@ function executeCommandLine(command, options, args) {
     const csn = options.directBackend ? model : compactModel(model, options);
     const odataCsn = main.for.odata(csn, remapCmdOptions(options, options.toOdata));
     if (options.toOdata && options.toOdata.csn) {
-      displayNamedCsn(odataCsn, 'odata_csn', options);
+      displayNamedCsn(odataCsn, 'odata_csn');
     }
     else if (options.toOdata && options.toOdata.json) {
       const result = main.to.edm.all(odataCsn, options);
@@ -385,7 +384,7 @@ function executeCommandLine(command, options, args) {
     const csn = options.directBackend ? model : compactModel(model, options);
     if (options.toSql && options.toSql.src === 'hdi') {
       if (options.toSql.csn) {
-        displayNamedCsn(for_hdi(csn, remapCmdOptions(options, options.toSql)), 'hdi_csn', options);
+        displayNamedCsn(for_hdi(csn, remapCmdOptions(options, options.toSql)), 'hdi_csn');
       }
       else {
         const hdiResult = main.to.hdi(csn, remapCmdOptions(options, options.toSql));
@@ -394,7 +393,7 @@ function executeCommandLine(command, options, args) {
       }
     }
     else if (options.toSql && options.toSql.csn) {
-      displayNamedCsn(for_sql(csn, remapCmdOptions(options, options.toSql)), 'sql_csn', options);
+      displayNamedCsn(for_sql(csn, remapCmdOptions(options, options.toSql)), 'sql_csn');
     }
     else {
       const sqlResult = main.to.sql(csn, remapCmdOptions(options, options.toSql));
@@ -445,7 +444,7 @@ function executeCommandLine(command, options, args) {
    * Print the model's messages to stderr in a human readable way.
    *
    * @param {CSN.Model | XSN.Model} model
-   * @param {CSN.Message[]} messages
+   * @param {CompileMessage[]} messages
    */
   function displayMessages( model, messages = options.messages ) {
     if (!Array.isArray(messages))
@@ -476,7 +475,6 @@ function executeCommandLine(command, options, args) {
         hasAtLeastOneExplanation = hasAtLeastOneExplanation || main.hasMessageExplanation(msg.messageId);
         const name = msg.location && msg.location.file;
         const fullFilePath = name ? path.resolve('', name) : undefined;
-        const context = fullFilePath ? sourceLines(fullFilePath) : [];
         log(main.messageStringMultiline(msg, {
           normalizeFilename,
           noMessageId: !options.showMessageId,
@@ -484,8 +482,12 @@ function executeCommandLine(command, options, args) {
           hintExplanation: true,
           color: options.color,
         }));
-        if (context)
+        if (fullFilePath && msg.location.col) {
+          // A message context only makes sense, if we have at least a medium precision,
+          // i.e. line and column for start position.
+          const context = sourceLines(fullFilePath);
           log(main.messageContext(context, msg, { color: options.color }));
+        }
         log(); // newline
       });
       if (options.showMessageId && hasAtLeastOneExplanation)
@@ -498,7 +500,7 @@ function executeCommandLine(command, options, args) {
   // or display it to stdout if 'options.out' is '-'.
   // Depending on 'options.rawOutput', the model is either compacted to 'name.json' or
   // written in raw form to '<name>_raw.txt'.
-  function displayNamedXsn(xsn, name, options) {
+  function displayNamedXsn(xsn, name) {
     if (options.rawOutput) {
       writeToFileOrDisplay(options.out, `${name}_raw.txt`, util.inspect(reveal(xsn, options.rawOutput), false, null), true);
     }
@@ -518,9 +520,8 @@ function executeCommandLine(command, options, args) {
   /**
    * @param {CSN.Model} csn
    * @param {string} name
-   * @param {CSN.Options} options
    */
-  function displayNamedCsn(csn, name, options) {
+  function displayNamedCsn(csn, name) {
     if (!csn) // only print CSN if it is set.
       return;
     if (options.internalMsg) {
@@ -551,8 +552,13 @@ function executeCommandLine(command, options, args) {
       content = JSON.stringify(content, null, 2);
 
     if (dir === '-') {
-      if (!omitHeadline)
-        process.stdout.write(`// ------------------- ${fileName} -------------------\n`);
+      if (!omitHeadline) {
+        const sqlTypes = {
+          sql: true, hdbconstraint: true, hdbtable: true, hdbview: true,
+        };
+        const commentStarter = fileName.split('.').pop() in sqlTypes ? '--$' : '//';
+        process.stdout.write(`${commentStarter} ------------------- ${fileName} -------------------\n`);
+      }
 
       process.stdout.write(`${content}\n`);
       if (!omitHeadline)

package/bin/cdsse.js

@@ -144,8 +144,8 @@ function lint( err, buf ) {
   }
 }
 
-function tokensAt( buf, offset, col, symbol ) {
-  const src = `${buf.substring( 0, offset )}≠${buf.substring( offset )}`;
+function tokensAt( buf, _offset, col, symbol ) {
+  const src = `${buf.substring( 0, _offset )}≠${buf.substring( _offset )}`;
   const et = messageAt( compiler.parseX( src, frel, { messages: [] } ), 'expectedTokens', col ) || [];
   for (const n of et) {
     if (typeof symbol === 'string') {

package/bin/cdsv2m.js

@@ -34,10 +34,11 @@ function usage( err ) {
 function ria() {
   const annotates = Object.create( null );
   const msgs = options.messages.filter( m => m.messageId === 'redirected-implicitly-ambiguous' );
-  // regex match on message text not for productive code!
+  // 'Choose via $(ANNO) one of $(SORTED_ARTS) as redirection target for $(TARGET) in … $(ART) otherwise'
+  // NOTE: regex match on message text not for productive code!
   for (const msgObj of msgs) {
     const matches = msgObj.message.match( /["“][^"”]+["”]/g );
-    matches.slice(2).forEach( (name) => {
+    matches.slice( 1, -2 ).forEach( (name) => {
       annotates[name.slice( 1, -1 )] = true;
     } );
   }

package/doc/CHANGELOG_ARCHIVE.md

@@ -1516,7 +1516,7 @@ Changes
 * Preserve the `key` properties of elements selected in a view (like we do in projections).
 * Improve the CSN representation for views.
   Represent the `where` and `on` condition of `select`s like other conditions.
-* Project name in github is now `cdx/cds-compiler`.
+* Project name in github is now `cap/cds-compiler`.
 
 Features
 * Support `select *` in views.

package/doc/CHANGELOG_BETA.md

@@ -8,17 +8,30 @@ Note: `beta` fixes, changes and features are listed in this ChangeLog just for i
 The compiler behavior concerning `beta` features can change at any time without notice.
 **Don't use `beta` fixes, changes and features in productive mode.**
 
-## Version 2.11.0
+## Version 2.XX.YY
+
+### Removed `assocsWithParams`
+
+Instead, of using the beta flag `assocsWithParams`, you can change the severity of the messages
+`def-unexpected-paramview-assoc` and `def-unexpected-calcview-assoc`.
+
+## Version 2.12.0 - 2022-01-25
+
+### Added `sqlSnippets`
+
+- to.sql/hdi/hdbcds: Introduce the annotations `@sql.prepend` and `@sql.append` that allow inserting user-written SQL snippets into the compiler generated content.
+
+## Version 2.11.0 - 2021-12-02
 
 ### Removed `foreignKeyConstraints`
 
-## Version 2.10.4
+## Version 2.10.4 - 2021-11-05
 
 ### Fixed `nestedProjections`
 
 - to.sql/hdi/hdbcds: Correctly handle a `*` at the not-first place in the query
 
-## Version 2.6.0
+## Version 2.6.0 - 2021-08-23
 
 ### Removed `pretransformedCSN`
 
@@ -42,7 +55,7 @@ This is now the default - see CHANGELOG entry for 2.6.0
 - Composition of one w/o backlink will result in a constraint in
   the entity where the composition is defined
 
-## Version 2.4.4
+## Version 2.4.4 - 2021-07-02
 
 ### Added `nestedProjections`
 
@@ -53,7 +66,7 @@ This is now the default - see CHANGELOG entry for 2.6.0
 - _Some checks are missing and will be added! Minor changes might occur._
 - **The SQL backends might not work properly yet if nested projections are used!**
 
-## Version 2.4.2
+## Version 2.4.2 - 2021-07-01
 
 ### Added `keylessManagedAssoc`
 
@@ -65,7 +78,7 @@ This is now the default - see CHANGELOG entry for 2.6.0
   Consequently, these associations are not added to the `WITH ASSOCIATIONS` clause or forwarded to HANA CDS.
   Managed Associations without foreign keys must be enabled with `--beta: keylessManagedAssoc`
 
-## Version 2.4.0
+## Version 2.4.0 - 2021-06-28
 
 ### Changed `foreignKeyConstraints`
 
@@ -163,6 +176,12 @@ The association to join transformation treats foreign key accesses with priority
 
 Unique constraints are now generally available.
 
+## Version 1.33.0 - 2020-08-24
+
+### Added `hanaAssocRealCardinality`
+
+Render JOIN cardinality in native HANA association if provided. If no cardinality has been specified.
+
 ## Version 1.32.0 - 2020-07-10
 
 ### Removed `aspectCompositions`

package/doc/CHANGELOG_DEPRECATED.md

@@ -11,9 +11,25 @@ Note: `deprecated` features are listed in this ChangeLog just for information.
 **When the `deprecated` option is set, the `beta` option is ignored,
 and several new features are not available.**
 
+## Version 2.XX.YY - 2022-MM-DD
+
+### Added `redirectInSubQueries`
+
+When this option is set, we auto-redirect associations and composition also in
+non-main queries, sometimes without rewriting the `keys`/`on` (there will be no
+fix for this).
+
+### Added `oldVirtualNotNullPropagation`
+
+When this option is set, we do not propagate `notNull` along types.
+Additionally, we propagate `notNull` and `virtual` from a query source element
+to the sub elements of a query entity element, even if the property is not
+propagated to the query entity element itself (like with type references).
+
+
 ## Version 2.2.0
 
-## Added `noScopedRedirections`
+### Added `noScopedRedirections`
 
 When this option is set, the definition scope is not taken into account when
 trying to find an implicit redirection target.  Setting the following
@@ -21,18 +37,18 @@ deprecated options also switches off scoped redirections (additionally to their
 other effect): `noElementsExpansion`, `generatedEntityNameWithUnderscore`,
 `shortAutoexposed`, `longAutoexposed`, `noInheritedAutoexposeViaComposition`.
 
-## Added `noInheritedAutoexposeViaComposition`
+### Added `noInheritedAutoexposeViaComposition`
 
 When this option is set, only entities directly specified after `Composition of` are
 auto-exposed, not entities used as target via explicit or implicit `redirected to`.
 
 ## Version 2.0.16
 
-## Added `downgradableErrors`
+### Added `downgradableErrors`
 
 Allow to change the severity of some errors which should stay to be an error.
 
-## Added `shortAutoexposed`
+### Added `shortAutoexposed`
 
 When this option is set (and `generatedEntityNameWithUnderscore`), the names of
 autoexposed entities are calculated according to the default compiler v1
@@ -40,13 +56,13 @@ behavior (without v1 options `dependentAutoexposed` and `longAutoexposed`).
 
 ## Version 2.0.10
 
-## Added `longAutoexposed`
+### Added `longAutoexposed`
 
 When this option is set (and `generatedEntityNameWithUnderscore`),
 the names of autoexposed entities are calculated according to the
 compiler v1 option `longAutoexposed`.
 
-## Added `generatedEntityNameWithUnderscore`
+### Added `generatedEntityNameWithUnderscore`
 
 Keep using `_` is separator for generated autoexposed entities and for entities
 created for managed compositions.  It also disables a definition `A.B.C` if `A`

package/doc/NameResolution.md

@@ -22,22 +22,27 @@ others might want to [skip the introduction](#design-principles).
 
 ## Table of Contents
 
- 1. [Introduction](#introduction)
-    <br/>  –  [Background: SQL](#background-sql)
-    <br/>  –  [Background: modern programming languages](#background-modern-programming-languages)
- 2. [Design Principles](#design-principles)
- 3. [Name Resolution - the Basics](#name-resolution---the-basics)
-    <br/>  –  [Common rules](#common-rules)
-    <br/>  –  [Resolving paths](#resolving-paths)
-    <br/>  –  [Navigation environment](#navigation-environment)
- 4. [References to main artifacts](#references-to-main-artifacts)
- 5. [Values and references to elements](#values-and-references-to-elements)
-    <br/>  –  [References in queries](#references-in-queries)
-    <br/>  –  [References to sibling elements](#references-to-sibling-elements)
-    <br/>  –  [Other element references](#other-element-references)
- 6. [Paths as Annotation Values](#paths-as-annotation-values)
- 7. [Differences to HANA-CDS](#differences-to-hana-cds)
- 8. [Summary](#summary)
+<!-- toc: start -->
+
+1. [Table of Contents](#table-of-contents)
+2. [Introduction](#introduction)
+   1. [Background: SQL](#background-sql)
+   2. [Background: modern programming languages](#background-modern-programming-languages)
+3. [Design Principles](#design-principles)
+4. [Name Resolution - the Basics](#name-resolution---the-basics)
+   1. [Common rules](#common-rules)
+   2. [Resolving paths](#resolving-paths)
+   3. [Navigation environment](#navigation-environment)
+5. [References to main artifacts](#references-to-main-artifacts)
+6. [Values and references to elements](#values-and-references-to-elements)
+   1. [References in queries](#references-in-queries)
+   2. [References to sibling elements](#references-to-sibling-elements)
+   3. [Other element references](#other-element-references)
+7. [Paths as annotation values](#paths-as-annotation-values)
+8. [Differences to HANA-CDS](#differences-to-hana-cds)
+9. [Summary](#summary)
+
+<!-- toc: end -->
 
 
 ## Introduction