@sap/cds-compiler 2.10.4 → 2.11.0

package/lib/main.d.ts

@@ -4,6 +4,10 @@
 //
 // These types are improved step by step and use a lot any types at the moment.
 
+// Author's note: All "options" interfaces should actually be types.  However, due to
+//                https://github.com/TypeStrong/typedoc/issues/1519 we can't use
+//                intersection types at the moment.
+
 export = compiler;
 
 declare namespace compiler {
@@ -11,7 +15,7 @@ declare namespace compiler {
   /**
    * Options used by the core compiler and all backends.
    */
-  export type Options = {
+  export interface Options {
     [option: string]: any,
 
     /**
@@ -57,6 +61,102 @@ declare namespace compiler {
     dictionaryPrototype?: any
   }
 
+  /**
+   * Options used by OData backends.  Includes options for the OData
+   * transformer as well as for rendering EDM and EDMX.
+   */
+  export interface ODataOptions extends Options {
+    /**
+     * OData version for output files.  Either 'v4' or 'v2'.
+     *
+     * @default 'v4'
+     */
+    odataVersion?: string | 'v4' | 'v2'
+    /**
+     * Whether to generate OData as flat or as structured.
+     * Structured is only supported for OData v4.
+     *
+     * @default 'flat'
+     */
+    odataFormat?: string | 'flat' | 'structured'
+    /**
+     * Naming mode used by the corresponding SQL.
+     *
+     * @default 'plain'
+     */
+    sqlMapping?: string | 'plain' | 'quoted' | 'hdbcds'
+    /**
+     * If `true`, `cds.Compositions` are rendered as `edm:NavigationProperty` with the additional
+     * attribute `ContainsTarget="true"` and all contained entities (composition targets) have no
+     * `edm.EntitySet`.
+     *
+     * @note Only available for OData v4 EDM(X) rendering.
+     * @default false
+     */
+    odataContainment?: boolean
+    /**
+     * If `true`, render generated foreign keys for managed associations.
+     * By default foreign keys are never visible in structured OData APIs.
+     *
+     * @note Only available for structured OData v4 EDM(X) rendering.
+     * @default false
+     */
+    odataForeignKeys?: boolean
+    /**
+     * If `true`, association targets outside of the current service are added as
+     * `edm.EntityType` that only exposes their primary keys and have no `edm.EntitySet`.
+     * If the original association target is a service member, a corresponding `edm.Schema`
+     * representing the namespace of that service is added to `edm.Services`.  All association
+     * targets that are no service members are collected in an `edm.Schema` with namespace `root`.
+     *
+     * @note Only valid for structured OData v4 EDM(X) rendering.
+     * @default false
+     * @since v2.1.0
+     */
+    odataProxies?: boolean
+    /**
+     * This option is an extension to `odataProxies`.
+     * If `true`, an `edm:Reference` instead of a proxy `edm.EntityType` is rendered for each
+     * association target that is a service member outside the current service instead of proxies.
+     *
+     * @note Only valid for structured OData v4 EDM(X) rendering.
+     * @default false
+     * @since v2.1.0
+     */
+    odataXServiceRefs?: boolean
+    /**
+     * The OData specification requires that all primary keys of the principal must be used as
+     * referential constraints.  If an association is modelled with only a partial key, no
+     * referential constraints are added.  If `true`, partial constraints are rendered for
+     * backwards compatibility and mocking scenarios.  A spec violation warning is raised for
+     * each incomplete constraint.
+     *
+     * @note Only valid for OData v2 CSN transformation.
+     * @default false
+     * @since v2.2.6
+     */
+    odataV2PartialConstr?: boolean
+    /**
+     * Service name for which EDMX or EDM shall be rendered.
+     *
+     * @note Only available for `to.edmx()` and `to.edm()`.  For `to.edmx.all()`
+     *       and `to.edm.all()`, use `serviceNames` instead.
+     *
+     * @see serviceNames
+     */
+    service?: string
+    /**
+     * Array of service names for which EDMX or EDM shall be rendered.
+     * If unspecified, all services are rendered.
+     *
+     * @note Only available for `to.edmx.all()` and `to.edm.all()`.  For `to.edmx()`
+     *       and `to.edm()`, use `service` instead.
+     *
+     * @see service
+     */
+    serviceNames?: string[]
+  }
+
   /**
    * The compiler's package version.
    * For more details on versioning and SemVer, see `doc/Versioning.md`
@@ -83,6 +183,7 @@ declare namespace compiler {
    * {@link CompilationError} containing a vector of individual errors.
    *
    * @param filenames Array of files that should be compiled.
+   * @param dir Working directory. Relative paths in `filenames` will be resolved relatively to this directory.
    * @param options  Compiler options. If you do not set `messages`, they will be printed to console.
    * @param fileCache A dictionary of absolute file names to the file content with values:
    *  - false: the file does not exist
@@ -138,7 +239,7 @@ declare namespace compiler {
    * _Note_: Sorting is done in-place.
    *
    * Example of sorted messages:
-   * ```txt
+   * ```
    * A.cds:1:11: Info    id-3: First message text   (in entity:“E”/element:“c”)
    * A.cds:8:11: Error   id-5: Another message text (in entity:“C”/element:“g”)
    * B.cds:3:10: Debug   id-7: First message text   (in entity:“B”/element:“e”)
@@ -188,10 +289,11 @@ declare namespace compiler {
    * form (i.e. one line)
    *
    * Example:
-   * ```txt
+   * ```
    * <source>.cds:3:11: Error message-id: Can't find type `nu` in this scope (in entity:“E”/element:“e”)
    * ```
    *
+   * @param msg               Compiler message which shall be stringified.
    * @param normalizeFilename If true, the file path will be normalized to use `/` as the path separator.
    * @param noMessageId       If true, the message ID will _not_ be part of the string.
    * @param noHome            If true, the semantic location will _not_ be part of the string.
@@ -201,26 +303,30 @@ declare namespace compiler {
   /**
    * Returns a message string with file- and semantic location if present
    * in multiline form.
-   * The error (+ message id) will be colored according to their severity if
-   * run on a TTY.
+   * The error (+ message id) can colored according to their severity.
    *
    * Example:
-   * ```txt
-   * Error[message-id]: Can't find type `nu` in this scope (in entity:“E”/element:“e”)
+   * ```
+   * Error[message-id]: Can't find type `nu` in this scope
    *    |
-   *   <source>.cds:3:11, at entity:“E”
+   *   <source>.cds:3:11, at entity:“E”/element:“e”
    * ```
    *
    * @param config.normalizeFilename If true, the file path will be normalized to use `/` as the path separator.
    * @param config.noMessageId       If true, no messages id (in brackets) will be shown.
    * @param config.hintExplanation   If true, messages with explanations will get a "…" marker, see {@link hasMessageExplanation}.
    * @param config.withLineSpacer    If true, an additional line (with `|`) will be inserted between message and location.
+   * @param 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.
    */
   export function messageStringMultiline(msg: CompileMessage, config?: {
     normalizeFilename?: boolean
     noMessageId?: boolean
     hintExplanation?: boolean
     withLineSpacer?: boolean
+    color?: boolean | 'auto'
   }): string;
 
   /**
@@ -233,16 +339,24 @@ declare namespace compiler {
    * All lines are prepended by a pipe (`|`) and show the corresponding line number.
    *
    * Example Output:
-   * ```txt
+   * ```
    *     |
    *  13 |     num * nu
    *     |           ^^
    * ```
    *
-   * @param sourceLines The source code split up into lines, e.g. by `str.split(/\r\n?|\n/);`.
-   * @param msg         Message whose location is used to print the message context.
+   * @param sourceLines  The source code split up into lines, e.g. by `str.split(/\r\n?|\n/);`.
+   * @param msg          Message whose location is used to print the message context.
+   * @param config       Configuration for the message context.
+   * @param 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.
+
    */
-  export function messageContext(sourceLines: string[], msg: CompileMessage): string;
+  export function messageContext(sourceLines: string[], msg: CompileMessage, config?: {
+    color?: boolean | 'auto'
+  }): string;
 
   /**
    * Get an explanatory text for a complicated compiler message with ID
@@ -316,21 +430,26 @@ declare namespace compiler {
    * @alias for
    */
   export namespace For {
-    function odata(): any;
+    /**
+     * Transform the given (generic) CSN into one that is used for OData.
+     * Changes include flattening, type resolution and more, according to
+     * the provided options.
+     */
+    function odata(csn: CSN, options: ODataOptions): any;
   }
 
   export namespace to {
       function cdl(csn: CSN, options: Options): object;
       function sql(csn: CSN, options: Options): any;
 
-      function edm(csn: CSN, options: Options): any;
+      function edm(csn: CSN, options: ODataOptions): any;
       namespace edm {
-          function all(csn: CSN, options: Options): any;
+          function all(csn: CSN, options: ODataOptions): any;
       }
 
-      function edmx(csn: CSN, options: Options): any;
+      function edmx(csn: CSN, options: ODataOptions): any;
       namespace edmx {
-          function all(csn: CSN, options: Options): any;
+          function all(csn: CSN, options: ODataOptions): any;
       }
 
       function hdbcds(csn: CSN, options: Options): any;

package/lib/main.js

@@ -21,6 +21,7 @@ const { createMessageFunctions, sortMessages, sortMessagesSeverityAware, dedupli
 
 const parseLanguage = require('./language/antlrParser');
 const { parseX, compileX, compileSyncX, compileSourcesX, InvocationError } = require('./compiler');
+const { fns } = require('./compiler/shared');
 const { define } = require('./compiler/definer');
 
 // The compiler version (taken from package.json)
@@ -43,13 +44,14 @@ const { compactModel, compactQuery, compactExpr } = require('./json/to-csn')
 function parseCdl( cdl, filename, options = {} ) {
   options = Object.assign( {}, options, { parseCdl: true } );
   const sources = Object.create(null);
-  const model = { sources, options };
+  const model = { sources, options, $functions: {}, $volatileFunctions: {} };
   const messageFunctions = createMessageFunctions( options, 'parse', model );
   model.$messageFunctions = messageFunctions;
 
   const xsn = parseLanguage( cdl, filename, Object.assign( { parseOnly: true }, options ),
                              messageFunctions );
   sources[filename] = xsn;
+  fns( model );
   define( model );
   messageFunctions.throwWithError();
   return compactModel( model );

package/lib/model/api.js

@@ -15,7 +15,7 @@
  * - the ‹property name› (might be useful if the same function is used for several props)
  */
 const defaultFunctions = {
-  '@': () => {},                // do not traverse annotation assignments
+  '@': () => { /* do not traverse annotation assignments */ },
   args: dictionary,
   elements: dictionary,
   enum: dictionary,
@@ -23,7 +23,7 @@ const defaultFunctions = {
   actions: dictionary,
   mixin: dictionary,
   definitions: dictionary,
-  '$': () => {},                // do not traverse properties starting with '$'
+  '$': () => { /*  do not traverse properties starting with '$' */},
 }
 
 /**

package/lib/model/csnRefs.js

@@ -225,17 +225,19 @@ function csnRefs( csn ) {
     const cachedType = getCache( art, '_effectiveType' );
     if (cachedType !== undefined)
       return cachedType;
-    else if (!art.type && !art.$origin ||
-             art.elements || art.target || art.targetAspect || art.enum)
-      return setCache( art, '_effectiveType', art );
 
     const chain = [];
-    while (getCache( art, '_effectiveType' ) === undefined && (art.type || art.$origin) &&
+    let origin;
+    while (getCache( art, '_effectiveType' ) === undefined &&
+           (origin = cached( art, '_origin', getOriginRaw )) &&
            !art.elements && !art.target && !art.targetAspect && !art.enum && !art.items) {
       chain.push( art );
       setCache( art, '_effectiveType', 0 ); // initial setting in case of cycles
-      art = (art.$origin) ? getOrigin( art ) : artifactRef( art.type, BUILTIN_TYPE );
+      art = origin;
     }
+    if (!chain.length)
+      return setCache( art, '_effectiveType', art );
+
     if (getCache( art, '_effectiveType' ) === 0)
       throw new Error( 'Circular type reference');
     const type = getCache( art, '_effectiveType' ) || art;
@@ -251,10 +253,16 @@ function csnRefs( csn ) {
     // here, we do not care whether it is semantically ok to navigate into sub
     // elements of array items (that is the task of the core compiler /
     // semantic check)
-    while (type.items)
+    while (type.items) {
+      cached( type, '$origin', _a => setImplicitOrigin( type, origin ) );
       type = effectiveType( type.items );
+    }
     // cannot navigate along targetAspect!
-    return (type.target) ? csn.definitions[type.target] : type;
+    const env = (type.target) ? csn.definitions[type.target] : type;
+    const origin = cached( env, '_origin', getOriginRaw );
+    if (origin && origin !== BUILTIN_TYPE)
+      cached( env, '$origin', _a => setImplicitOrigin( env, origin ) );
+    return env;
   }
 
   /**
@@ -279,38 +287,102 @@ function csnRefs( csn ) {
   function artifactPathRef( ref ) {
     const [ head, ...tail ] = ref.ref;
     let art = csn.definitions[pathId( head )];
-    for (const elem of tail)
-      art = navigationEnv( art ).elements[pathId( elem )];
+    for (const elem of tail) {
+      const env = navigationEnv( art );
+      art = env.elements[pathId( elem )];
+    }
     return art;
   }
 
-  function getOrigin( def ) {
-    const art = cached( def, '_origin', originPathRef );
-    if (art)
-      return art;
-    throw new Error( 'Undefined origin reference' );
+  function getOrigin( art, alsoType ) {
+    const origin = cached( art, '_origin', getOriginRaw );
+    if (origin && origin !== BUILTIN_TYPE)
+      cached( art, '$origin', _a => setImplicitOrigin( art, origin ) );
+    return art.type && !alsoType ? undefined : origin;
   }
 
-  function originPathRef( def ) {
-    const [ head, ...tail ] = def.$origin;
-    let art = csn.definitions[head];
-    for (const elem of tail)
-      art = originNavigation( art, elem );
-    return art;
+  function getOriginRaw( art ) {
+    if (art.type)               // TODO: make robust against "linked" = only direct
+      return artifactRef( art.type, BUILTIN_TYPE );
+    if (!art.$origin)           // implicit $origin should have been set
+      return null;
+    // art.$origin must not be a string here - shortened refs should already
+    // have been used to set the _origin cache
+    if (!Array.isArray( art.$origin )) // anonymous prototype in $origin
+      return cached( art.$origin, '_origin', getOriginRaw );
+    const [ head, ...tail ] = art.$origin;
+    let origin = csn.definitions[head];
+    // allow shorter $origin ref for actions/functions, just using a string:
+    let isAction = art.kind === 'action' || art.kind === 'function';
+    for (const elem of tail) {
+      origin = originNavigation( origin, elem, isAction );
+      isAction = false;
+    }
+    return origin;
   }
 
-  function originNavigation( art, elem ) {
+  function originNavigation( art, elem, isAction ) {
     if (typeof elem !== 'string') {
       if (elem.action)
-        return art.actions[elem.action]
+        return art.actions[elem.action];
       if (elem.param)
-        return (elem.param ? art.params[elem.param] : art.returns);
+        return art.params[elem.param];
+      if (elem.returns)
+        return art.returns;
     }
-    if (art.returns)
+    if (isAction)
+      return art.actions[elem];
+    // TODO: if we use effectiveType(), we might have more implicit prototypes
+    // we might then need a function like effectiveArtifact,
+    // which cares about actions/params
+    // let origin = cached( art, '_origin', getOriginRaw );
+    // while (art.items) {
+    //   cached( art, '$origin', _a => setImplicitOrigin( art, origin ) );
+    //   art = art.items;
+    //   origin = cached( art, '_origin', getOriginRaw );
+    // }
+    // if (origin)
+    //   cached( art, '$origin', _a => setImplicitOrigin( art, origin ) );
+    return (art.elements || art.enum || (art.targetAspect || art.target).elements)[elem];
+  }
+
+  // From the current CSN object, set implicit origin for the next navigation step
+  // Currently (TODO: ?) `elements` only, i.e. what is needed for name resolution.
+  function setImplicitOrigin( art, origin ) {
+    setMembersImplicit( art.actions, origin.actions );
+    setMembersImplicit( art.params, origin.params );
+    if (art.returns) {
       art = art.returns;
-    while (art.items)
+      if (art.type || typeof art.$origin === 'object') // null, […], {…}
+        return true;            // not implicit or shortened
+      origin = effectiveType( origin.returns );
+      setCache( art, '_origin', origin );
+      return true;
+    }
+    while (art.items) {
       art = art.items;
-    return (art.elements || art.enum || (art.targetAspect || art.target).elements)[elem];
+      if (art.type || typeof art.$origin === 'object') // null, […], {…}
+        return true;            // not implicit or shortened
+      origin = effectiveType( origin.items );
+      setCache( art, '_origin', origin );
+    }
+    setMembersImplicit( art.elements, origin.elements );
+    // The enum base type is _not_ where we find the origins of the enum symbols.
+    // A derived type of an enum type with individual annotations on a symbol
+    // has both 'type' and '$origin'.
+    if (!art.type || art.$origin)
+      setMembersImplicit( art.enum, origin.enum );
+    return true;
+  }
+
+  function setMembersImplicit( members, originMembers ) {
+    if (!members)
+      return;
+    for (const name in members) {
+      const elem = members[name];
+      if (!elem.type && typeof elem.$origin !== 'object') // undefined or string
+        setCache( elem, '_origin', originMembers[elem.$origin || name] || false );
+    }
   }
 
   /**
@@ -371,6 +443,9 @@ function csnRefs( csn ) {
     if (semantics.dynamic === 'global' || ref.global)
       return resolvePath( path, csn.definitions[head], 'global', refCtx === 'from' );
 
+    const origin = cached( main, '_origin', getOriginRaw )
+    if (origin)
+      cached( main, '$origin', _a => setImplicitOrigin( main, origin ) );
     cached( main, '$queries', allQueries );
     let qcache = query && cache.get( query.projection || query );
     // BACKEND ISSUE: you cannot call csnRefs(), inspect some refs, change the
@@ -387,7 +462,7 @@ function csnRefs( csn ) {
       while (cache) {
         const alias = tryAlias && cache.$aliases[head];
         if (alias)
-          return resolvePath( path, alias._select || alias, 'alias', cache.$queryNumber );
+          return resolvePath( path, alias._select || alias._ref, 'alias', cache.$queryNumber );
         const mixin = cache._select.mixin && cache._select.mixin[head];
         if (mixin && {}.hasOwnProperty.call( cache._select.mixin, head ))
           return resolvePath( path, mixin, 'mixin', cache.$queryNumber );
@@ -481,7 +556,8 @@ function csnRefs( csn ) {
       if (query.ref) {          // ref in from
         // console.log('SQ:',query,cache.get(query))
         const as = query.as || implicitAs( query.ref );
-        getCache( fromSelect, '$aliases' )[as] = fromRef( query );
+        const _ref = fromRef( query );
+        getCache( fromSelect, '$aliases' )[as] = { _ref, elements: _ref.elements };
       }
       else {
         const qcache = getQueryCache( parentQuery );
@@ -607,7 +683,7 @@ function queryOrMain( query, main ) {
  *
  * @param {CSN.Query} query
  * @param {CSN.QuerySelect} fromSelect
- * @param {CSN.Query} parentQuery 
+ * @param {CSN.Query} parentQuery
  * @param {(query: CSN.Query&CSN.QueryFrom, select: CSN.QuerySelectEnriched) => void} callback
  */
 function traverseQuery( query, fromSelect, parentQuery, callback ) {
@@ -632,8 +708,9 @@ function traverseQuery( query, fromSelect, parentQuery, callback ) {
 
 /**
  * @param {CSN.QueryFrom} from
- * @param {CSN.QuerySelect} select
- * @param {(from: CSN.QueryFrom, select: CSN.QuerySelect) => void} callback
+ * @param {CSN.QuerySelect} fromSelect
+ * @param {CSN.Query} parentQuery
+ * @param {(from: CSN.QueryFrom, select: CSN.QuerySelect, parentQuery: CSN.Query) => void} callback
  */
 function traverseFrom( from, fromSelect, parentQuery, callback ) {
   if (from.ref) {