@sap/cds-compiler 3.5.4 → 3.6.0

package/CHANGELOG.md

@@ -7,19 +7,71 @@
 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 3.6.0 - 2023-01-25
+
+### Added
+
+- API: There are new API functions for `to.cdl`: `smartId`, `smartFunctionId` and `delimitedId`.
+- CDL parser: when defining a parameter for entities, actions or functions,
+  you can use a regular identifier for its name even if that is a reserved name like `in`.
+- The first parameter of a bound action or function can be typed with `$self` or `many $self`
+  even if no type named `$self` exists.
+- If an aspect `sap.common.TextsAspect` exists in the `sap.common` context, it will be included
+  in all `.texts` entities. This allows to extend `.texts` entities via extending the aspect.  
+  Example:
+  ```cds
+  entity E {
+    key id : Integer;
+    content: localized String;
+  }
+  extend sap.common.TextsAspect with {
+    elem: String;
+  };
+  // from @sap/cds common.cds
+  aspect sap.common.TextsAspect {
+    key locale: String;
+  }
+  ```
+- to.edm(x): Support explicit binding parameter `<id>: [many] $self` for OData V4 only.
+  The explicit binding parameter is rendered as any other parameter and `$self` is replaced with
+  the binding type but only if no `$self` definition exists in the model. This gives full control
+  over the binding parameter including name, nullability, default value and annotations.
+  The explicit binding parameter is ignored for OData V2 and has precedence over `@cds.odata.bindingparameter`.
+
+### Changed
+
+- Many messages concerning the CDL and CSN syntax are improved:
+  affects message ids (`syntax-…`), message texts and the error locations.
+- Duplicate doc-comments are now errors, similar to duplicate annotations.
+- Update OData vocabularies 'Aggregation', 'Analytics', 'Capabilities','Common', 'ODM', 'Offline',
+  'PDF', 'Session', 'UI'.
+
+### Fixed
+
+- If an entity with parameters is auto-exposed, the generated projection now has
+  the same formal parameters and its query forwards these parameters to the origin entity.
+- to.hdbcds: Aliases for foreign `keys` were not quoted if necessary.
+- to.cdl:
+  + Aliases for `expand` and foreign `keys` were not quoted if necessary.
+  + Query functions that are CDL keywords were not properly quoted.
+  + CSN `doc` properties containing `*/` resulted in invalid CDL.
+    To avoid compilation issues, `*/` is escaped as `*\/`.
+- to.edm(x): Respect record type hint `$Type` in EDM JSON as  full qualified `@type` URI property.
+
 ## Version 3.5.4 - 2023-01-10
 
 ### Fixed
 
 - Allow window functions also with a deprecated flag being set.
 - to.edm(x): Fix program abort due to malformed error location in EDM annotation preprocessing.
-- to.sql/hdi/hdbcds: The option `pre2134ReferentialConstraintNames` can be used to omit the referential constraint identifier prefix "c__".
+- to.sql/hdi/hdbcds: The option `pre2134ReferentialConstraintNames` can be used to omit the referential
+  constraint identifier prefix `c__`.
 
 ## Version 3.5.2 - 2022-12-20
 
 ### Fixed
 
-- to.sql/hdi/hdbcds: Don't process references in actions, as they have no impact on the database - avoids internal errors
+- to.sql/hdi/hdbcds: Don't process references in actions, as they have no impact on the database - avoids internal errors.
 
 ## Version 3.5.0 - 2022-12-07
 
@@ -51,6 +103,8 @@ The compiler behavior concerning `beta` features can change at any time without
   as the renderer does not modify it.
 - A new warning is emitted if compositions of anonymous aspects are used with the `Association`
   keyword instead of `Composition`. Replace the former with the latter to fix the warning.
+- The previous info messages about annotating undefined artifacts (e.g. `anno-undefined-art`)
+  are now warnings.
 
 ### Removed
 

package/bin/cdsc.js

@@ -128,8 +128,7 @@ function cdsc_main() {
       return;
   }
 
-  // Default warning level is 2 (info)
-  // FIXME: Is that not set anywhere in the API?
+  // Default warning level is 2 (info); default value only needed for cdsc output
   if (!cmdLine.options.warning)
     cmdLine.options.warning = 2;
 
@@ -184,6 +183,15 @@ function cdsc_main() {
   if (cmdLine.options.betaMode)
     cmdLine.options.beta = availableBetaFlags;
 
+  const { shuffle } = cmdLine.options;
+  if (shuffle != null) {
+    const num = Number.parseInt( shuffle, 10 );
+    cmdLine.options.testMode = (num > 0)
+      ? num
+      : Math.floor( Math.random() * 4294967296 ) + 1;
+    console.error( `Running ‘${cmdLine.command}’ with test-mode shuffle ${cmdLine.options.testMode} …` );
+  }
+
   // If set through CLI (and not options file), `deprecated` is a string and needs processing.
   if (cmdLine.options.deprecated && typeof cmdLine.options.deprecated === 'string') {
     const features = cmdLine.options.deprecated.split(',');
@@ -382,7 +390,7 @@ function executeCommandLine( command, options, args ) {
   function manageConstraints( model ) {
     const csn = options.directBackend ? model : compactModel(model, options);
     const alterConstraintsResult = alterConstraintsWithCsn(csn, options);
-    const { src } = options.manageConstraints || {};
+    const { src } = options || {};
     Object.keys(alterConstraintsResult).forEach((id) => {
       const renderedConstraintStatement = alterConstraintsResult[id];
       if (src === 'hdi')
@@ -492,7 +500,7 @@ function executeCommandLine( command, options, args ) {
     }
     else if (options.noMessageContext) {
       messages.filter(msg => (messageLevels[msg.severity] <= options.warning))
-        .forEach(msg => log(main.messageString(msg, normalizeFilename, !options.showMessageId)));
+        .forEach(msg => log(main.messageString(msg, normalizeFilename, !!options.noMessageId)));
     }
     else {
       // Contains file-contents that are split at '\n'. Try to avoid multiple `.split()` calls.
@@ -509,7 +517,7 @@ function executeCommandLine( command, options, args ) {
         const fullFilePath = name ? path.resolve('', name) : undefined;
         log(main.messageStringMultiline(msg, {
           normalizeFilename,
-          noMessageId: !options.showMessageId,
+          noMessageId: !!options.noMessageId,
           withLineSpacer: true,
           hintExplanation: true,
           color: options.color,
@@ -521,7 +529,7 @@ function executeCommandLine( command, options, args ) {
         }
         log(); // newline
       });
-      if (options.showMessageId && hasAtLeastOneExplanation)
+      if (!options.noMessageId && hasAtLeastOneExplanation)
         log(`${colorTerm.asHelp('help')}: Messages marked with '…' have an explanation text. Use \`cdsc explain <message-id>\` for a more detailed error description.`);
     }
     return model;

package/doc/CHANGELOG_ARCHIVE.md

@@ -584,7 +584,7 @@ synchronously.
     for a local definition of `Foo` probably having a different full name.
   + Localized convenience views are no longer generated by the core compiler but added by the `for.odata`
     and `to.sql/hdi/hdbcds` processing on demand.
-  + Minimize name clashes when calculating names for autoexposed entities,
+  + Minimize name clashes when calculating names for auto-exposed entities,
     extends the v1 option `dependentAutoexposed` to sub artifacts of entites (see “Added”).
   + Ambiguities when redirecting associations now always lead to compile errors;
     you might want to use the new annotation `@cds.redirection.target` to solve them.
@@ -760,7 +760,7 @@ synchronously.
 
 ### Fixed
 
-- Correct calculation of dependent autoexposed entity name
+- Correct calculation of dependent auto-exposed entity name
   (fixing a potential regression with v1.50.0)
 - to.hdi.migration: Correctly handle "temporal" and other cases when rendering expressions
 - to.edm(x):
@@ -1177,7 +1177,7 @@ synchronously.
 - Properly consider targets of compositions in `mixin`s to be autoexposed.
 - Uniformly limit propagation of `@cds.autoexposed`, i.e.
   there is not inheritance from a query source navigating along an association.
-  Previously, compiling a compiled model could lead to new autoexposed entities.
+  Previously, compiling a compiled model could lead to new auto-exposed entities.
 - OData:
   + V2: Distribute various `@sap` specific annotations to the entity container.
   + Always set attribute `Nullable` on properties of type `Collection()`.
@@ -1196,7 +1196,7 @@ synchronously.
 - Allow to declare `many/array of` elements, parameters and return types to be `(not) null`.
   The nullability applies to the array items of the element, not the element itself.
 - New boolean option `dependentAutoexposed` to avoid name clashes in dependent
-  autoexposed entities (text entities, components of managed compositions).
+  auto-exposed entities (text entities, components of managed compositions).
 - cdsc: Add toOdata version 'v4x' to combine `{ version: 'v4', odataFormat: 'structured', odataContainment: true }`.
 
 ### Changed
@@ -1971,7 +1971,7 @@ Changes
 
 Fixes
 
-* Make `annotate` statements on members of autoexposed entities and
+* Make `annotate` statements on members of auto-exposed entities and
   automatically created text entities work.
 
 ## Version 1.17.2
@@ -2098,7 +2098,7 @@ Fixes
 * Consider associations in `from` clause for `on` condition rewrite.
 * Make the CSN parser always produce the correct result for `null`.
 * Propagate `@cds.autoexpose` along primary query source in all circumstances.
-* Make `annotate` statements on autoexposed entities work in circumstances.
+* Make `annotate` statements on auto-exposed entities work in circumstances.
 * Do not dump when magic variables like `$now` or `current_date` had been used
   in an entitiy for which the compiler creates a localized convenience view.
 * Fix order problem in creation of association `DraftAdministrativeData` for draft enabled entities.
@@ -2223,7 +2223,7 @@ Changes
   + Auto-exposure via `Composition of` now works in all circumstances.
   + Other features like "localized" work for auto-exposed entity and/or with implicitly redirected association.
   + __Redirections for associations which are sub elements do not work__.
-* The name of an autoexposed entity now looks like `<Service>.<LastNamePart>`
+* The name of an auto-exposed entity now looks like `<Service>.<LastNamePart>`
   where `<LastNamePart>` is the part of the name of the original entity after the final dot.
   If you get an error because of name clashes, just expose one entity explicitly
   (or use the option `longAutoexposed`).
@@ -2307,7 +2307,7 @@ Changes
 * Produce all CSN output in version 1.0 by default.
 * Virtual elements cannot be used in expressions.
 * Command `toRename` creates a stored procedure instead of individual statements.
-* Don't autoexpose composition target which is annotated with `@cds.autoexpose: false`.
+* Don't auto-expose composition target which is annotated with `@cds.autoexpose: false`.
 
 Fixes
 * OData:
@@ -2323,8 +2323,8 @@ Fixes
 ## Version 1.10.0
 
 Features
-* Annotate entities with `@cds.autoexposed` that are autoexposed in a service.
-* Always autoexpose composition targets without annotating them with `@cds.autoexpose`.
+* Annotate entities with `@cds.autoexposed` that are auto-exposed in a service.
+* Always auto-expose composition targets without annotating them with `@cds.autoexpose`.
 * For associations in a service with targets which are not in a service:
   + automatically exclude them if the associaiton is inferred (via select * or include),
   + signal an error if the association is explicitly defined in the service.

package/doc/CHANGELOG_DEPRECATED.md

@@ -115,12 +115,12 @@ behavior (without v1 options `dependentAutoexposed` and `longAutoexposed`).
 ### Added `longAutoexposed`
 
 When this option is set (and `generatedEntityNameWithUnderscore`),
-the names of autoexposed entities are calculated according to the
+the names of auto-exposed entities are calculated according to the
 compiler v1 option `longAutoexposed`.
 
 ### Added `generatedEntityNameWithUnderscore`
 
-Keep using `_` is separator for generated autoexposed entities and for entities
+Keep using `_` is separator for generated auto-exposed entities and for entities
 created for managed compositions.  It also disables a definition `A.B.C` if `A`
 or `A.B` is a definition other than a context or service (v1 behavior).
 

package/lib/api/main.js

@@ -130,6 +130,7 @@ function isPreTransformed( csn, transformation ) {
  * @returns {object} Return an oData-pre-processed CSN
  */
 function odataInternal( csn, internalOptions ) {
+  internalOptions.transformation = 'odata';
   const oDataCsn = forOdataNew.transform4odataWithCsn(csn, internalOptions);
   attachTransformerCharacteristics(oDataCsn, 'odata', internalOptions, relevantOdataOptions, warnAboutMismatchOdata);
   return oDataCsn;
@@ -143,6 +144,7 @@ function odataInternal( csn, internalOptions ) {
  * @returns {oDataCSN} Return an oData-pre-processed CSN
  */
 function odata( csn, options = {} ) {
+  traceApi("Options passed into 'for.odata'", options);
   const internalOptions = prepareOptions.for.odata(options);
   return odataInternal(csn, internalOptions);
 }
@@ -151,11 +153,12 @@ function odata( csn, options = {} ) {
  * Process the given csn back to cdl.
  *
  * @param {object} csn CSN to process
- * @param {object} [externalOptions={}] Options
+ * @param {object} [options={}] Options
  * @returns {object} { model: string, namespace: string }
  */
-function cdl( csn, externalOptions = {} ) {
-  const internalOptions = prepareOptions.to.cdl(externalOptions);
+function cdl( csn, options = {} ) {
+  traceApi("Options passed into 'to.cdl'", options);
+  const internalOptions = prepareOptions.to.cdl(options);
   return toCdl.csnToCdl(csn, internalOptions);
 }
 
@@ -214,6 +217,7 @@ function forHdbcds( csn, options = {} ) {
  * @returns {SQL[]} Array of SQL statements, tables first, views second
  */
 function sql( csn, options = {} ) {
+  traceApi("Options passed into 'to.sql'", options);
   const internalOptions = prepareOptions.to.sql(options);
   internalOptions.transformation = 'sql';
 
@@ -226,50 +230,6 @@ function sql( csn, options = {} ) {
   return result.map(obj => obj.sql).filter(create => create);
 }
 
-/**
- * Render the given deltaCSN as SQL.
- *
- * @param {CSN.Model} csn A clean input CSN
- * @param {CSN.Model} deltaCsn A CSN representing new entities and extensions
- * @param {SqlOptions} [options={}] Options
- * @returns {object} - definitions: An array of objects with all artifacts in the after-image. Each object specifies
- *                                  the artifact filename, the suffix, and the corresponding SQL statement to create
- *                                  the artifact.
- *                   - deletions:   An array of objects with the deleted artifacts. Each object specifies the artifact
- *                                  filename and the suffix.
- *                   - migrations:  An array of objects with the changed (migrated) artifacts. Each object specifies the
- *                                  artifact filename, the suffix, and the changeset (an array of changes, each specifying
- *                                  whether it incurs potential data loss, and its respective SQL statement(s), with
- *                                  multiple statements concatenated as a multi-line string in case the change e.g.
- *                                  consists of a column drop and add).
- */
-function mtx( csn, deltaCsn, options = {} ) {
-  if (!baseModel.isBetaEnabled(options, 'to.mtx'))
-    throw new Error('to.mtx is only available with beta flag `to.mtx`');
-
-  const internalOptions = prepareOptions.to.sql(options);
-  // TODO: Use compiler.compileSources() when this function is moved to lib/main.js
-  const merged = toCsn.compactModel(compiler.compileSourcesX({ 'base.csn': csn, 'delta.csn': deltaCsn }), options);
-  const baseSql = forSql(csn, options);
-  const mergedSql = forSql(merged, options);
-  const diff = modelCompare.compareModels(baseSql, mergedSql, options);
-  // Delete artifacts that are already present in csn
-  Object.keys(baseSql.definitions).forEach((artifactName) => {
-    if (diff.definitions[artifactName]) // don't render again, but need info for primary key extension
-      diff.definitions[artifactName]['@cds.persistence.skip'] = true;
-  });
-
-  internalOptions.forHana = true;
-  internalOptions.beta.sqlExtensions = true;
-  const { deletions, migrations, ...additions } = toSql.toSqlDdl(diff, internalOptions);
-
-  return {
-    additions: createSqlDefinitions(additions, mergedSql),
-    deletions: createSqlDeletions(deletions, baseSql),
-    migrations: createSqlMigrations(migrations, mergedSql),
-  };
-}
-
 /**
  * Process the given CSN into HDI artifacts.
  *
@@ -278,6 +238,7 @@ function mtx( csn, deltaCsn, options = {} ) {
  * @returns {HDIArtifacts} { <filename>:<content>, ...}
  */
 function hdi( csn, options = {} ) {
+  traceApi("Options passed into 'to.hdi'", options);
   const internalOptions = prepareOptions.to.hdi(options);
 
   // we need the CSN for view sorting
@@ -380,14 +341,15 @@ function remapName( key, csn, filter = () => true ) {
  *                                  - createsAndAlters: An array of SQL statements to ALTER/CREATE tables/views
  */
 function sqlMigration( csn, options, beforeImage ) {
+  traceApi("Options passed into 'to.sql.migration'", options);
   const internalOptions = prepareOptions.to.sql(options);
-  const { error, throwWithError } = messages.makeMessageFunction(csn, options, 'to.sql.migration');
+  const { error, throwWithError } = messages.makeMessageFunction(csn, internalOptions, 'to.sql.migration');
 
   // Prepare after-image.
-  const afterImage = forSql(csn, options);
+  const afterImage = forSql(csn, internalOptions);
   // Compare both images.
   const diff = modelCompare.compareModels(beforeImage || afterImage, afterImage, internalOptions);
-  const diffFilterObj = diffFilter[options.sqlDialect];
+  const diffFilterObj = diffFilter[internalOptions.sqlDialect];
 
   if (diffFilterObj) {
     diff.extensions.forEach(ex => diffFilterObj.extension(ex, error));
@@ -489,6 +451,7 @@ function sqlMigration( csn, options, beforeImage ) {
  * @returns {migration} The migration result
  */
 function hdiMigration( csn, options, beforeImage ) {
+  traceApi("Options passed into 'to.hdi.migration'", options);
   const internalOptions = prepareOptions.to.hdi(options);
 
   // Prepare after-image.
@@ -569,6 +532,7 @@ sql.migration = sqlMigration;
  * @returns {HDBCDS} { <filename>:<content>, ...}
  */
 function hdbcds( csn, options = {} ) {
+  traceApi("Options passed into 'to.hdbcds'", options);
   const internalOptions = prepareOptions.to.hdbcds(options);
   internalOptions.transformation = 'hdbcds';
 
@@ -585,6 +549,7 @@ function hdbcds( csn, options = {} ) {
  * @returns {edm} The JSON representation of the service
  */
 function edm( csn, options = {} ) {
+  traceApi("Options passed into 'to.edm'", options);
   // If not provided at all, set service to undefined to trigger validation
   const internalOptions = prepareOptions.to.edm(
     // eslint-disable-next-line comma-dangle
@@ -615,6 +580,7 @@ edm.all = edmall;
  * @returns {edms} { <service>:<JSON representation>, ...}
  */
 function edmall( csn, options = {} ) {
+  traceApi("Options passed into 'to.edm.all'", options);
   const internalOptions = prepareOptions.to.edm(options);
   const { error } = messages.makeMessageFunction(csn, internalOptions, 'for.odata');
 
@@ -645,6 +611,7 @@ function edmall( csn, options = {} ) {
  * @returns {edmx} The XML representation of the service
  */
 function edmx( csn, options = {} ) {
+  traceApi("Options passed into 'to.edmx'", options);
   // If not provided at all, set service to undefined to trigger validation
   const internalOptions = prepareOptions.to.edmx(
     // eslint-disable-next-line comma-dangle
@@ -676,6 +643,7 @@ edmx.all = edmxall;
  * @returns {edmxs} { <service>:<XML representation>, ...}
  */
 function edmxall( csn, options = {} ) {
+  traceApi("Options passed into 'to.edmx.all'", options);
   const internalOptions = prepareOptions.to.edmx(options);
 
   const result = {};
@@ -792,6 +760,20 @@ function flattenResultStructure( toProcess ) {
   return result;
 }
 
+/**
+ * Print args to stderr if CDSC_TRACE_API is set
+ *
+ * @param {...any} args
+ */
+function traceApi( ...args ) {
+  if (process?.env?.CDSC_TRACE_API !== undefined) {
+    for (const arg of args) {
+      // eslint-disable-next-line no-console
+      console.error( `${ typeof arg === 'object' ? JSON.stringify(arg, null, 2) : arg }`);
+    }
+  }
+}
+
 module.exports = {
   odata: publishCsnProcessor(odata, 'for.odata'),
   cdl: publishCsnProcessor(cdl, 'to.cdl'),
@@ -804,8 +786,6 @@ module.exports = {
   for_sql: publishCsnProcessor(forSql, 'for.sql'),
   for_hdi: publishCsnProcessor(forHdi, 'for.hdi'),
   for_hdbcds: publishCsnProcessor(forHdbcds, 'for.hdbcds'),
-  /** beta - WIP */
-  mtx: publishCsnProcessor(mtx, 'to.mtx'),
   /** Deprecated, will be removed in cds-compiler@v4 */
   preparedCsnToEdmx,
   preparedCsnToEdm,
@@ -826,9 +806,6 @@ function publishCsnProcessor( processor, _name ) {
   if (processor.migration)
     api.migration = publishCsnProcessor(processor.migration, `${ _name }.migration`);
 
-  if (processor.mtx)
-    api.mtx = publishCsnProcessor(processor.mtx, `${ _name }.mtx`);
-
   return api;
 
   /**

package/lib/api/validate.js

@@ -109,6 +109,11 @@ const validators = {
     expected: () => 'type string',
     found: val => `type ${ typeof val }`,
   },
+  testMode: {
+    validate: val => typeof val === 'boolean' || typeof val === 'number',
+    expected: () => 'type boolean|number',
+    found: val => `type ${ typeof val }`,
+  },
   dictionaryPrototype: {
     validate: () => true,
   },