@sap/cds-compiler 2.5.2 → 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
@@ -107,22 +208,92 @@ declare namespace compiler {
       constructor(messages: any, model: any, text: any, ...args);
       messages: any[];
       toString(): string;
+      /**
+       * If `options.attachValidNames` is set, this non-enumerable property holds the CSN model.
+       * @internal
+       */
+      model?: CSN;
+      /**
+       * Used by `cdsc` to indicate whether the message was already printed to stderr.
+       * @private
+       */
+      hasBeenReported: boolean;
   }
 
-  export function sortMessages(messages: any[]): void;
-  export function sortMessagesSeverityAware(messages: any[]): void;
+  /**
+   * Sort the given messages according to their location.  Messages are sorted
+   * in ascending order according to their:
+   *
+   *  - file name
+   *  - start line
+   *  - start column
+   *  - end line
+   *  - end column
+   *  - semantic location (“home”)
+   *  - message text
+   *
+   * If both messages do not have a location, they are sorted by their semantic
+   * location and then by their message text.  If only one message has a file
+   * location, that message is sorted prior to those that don't have one.
+   *
+   * _Note_: Sorting is done in-place.
+   *
+   * Example of sorted messages:
+   * ```
+   * 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”)
+   * B.cds:3:12: Warning id-4: Message text         (in entity:“B”/element:“d”)
+   * B.cds:3:12: Error   id-4: Message text         (in entity:“B”/element:“e”)
+   * ```
+   *
+   * If you also want to sort according to message's severity,
+   * see {@link sortMessagesSeverityAware}.
+   *
+   * @returns The same messages array as the input parameter.
+   */
+  export function sortMessages(messages: CompileMessage[]): CompileMessage[];
 
-  export function deduplicateMessages(messages: any[]): void;
+  /**
+   * Sort the given messages in severity aware order.  Messages are sorted first
+   * by severity where 'Error' comes first, then 'Warning' and so forth.
+   * Messages of the same severity are sorted the same as by {@link sortMessages}.
+   *
+   * _Note_: Sorting is done in-place.
+   *
+   * @returns The same messages array as the input parameter.
+   */
+  export function sortMessagesSeverityAware(messages: CompileMessage[]): CompileMessage[];
+
+  /**
+   * Removes duplicate messages from the given messages array without destroying
+   * references to the array, i.e. removes them in-place.
+   *
+   * _Note_: Does NOT keep the original order!
+   *
+   * Two messages are the same if they have the same message hash (see below).
+   * If one of the two is more precise, then it replaces the other.
+   * A message is more precise if it is contained in the other or if
+   * the first does not have an `endLine`/`endCol`.
+   *
+   * A “message hash” is the string representation of the message.  If the
+   * message does not have a semantic location (“home”), the message hash
+   * is the result of {@link messageString}.  If the message has a semantic
+   * location, the file location is stripped before being passed to
+   * {@link messageString}.
+   */
+  export function deduplicateMessages(messages: CompileMessage[]): void;
 
   /**
    * Returns a message string with file- and semantic location if present in compact
    * 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.
@@ -132,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;
 
   /**
@@ -164,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
@@ -205,6 +388,15 @@ declare namespace compiler {
   export function preparedCsnToEdmx(csn: CSN, service: string, options: any): any;
 
   export namespace parse {
+      /**
+       * Parse the given CDL in parseCdl mode and return its corresponding CSN representation.
+       *
+       * @param cdl      CDL source as string.
+       * @param filename Filename to be used in compiler messages.
+       * @param options  Compiler options. Note that if `options.messages` is not set, messages will be printed to stderr.
+       */
+      function cdl(cdl: string, filename: string, options?: Options): any;
+
       /**
        * Parse the given CQL and return its corresponding CSN representation.
        *
@@ -238,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

@@ -16,10 +16,13 @@
 const backends = require('./backends');
 const { odata, cdl, sql, hdi, hdbcds, edm, edmx } = require('./api/main');
 const { getArtifactDatabaseNameOf, getElementDatabaseNameOf } = require('./model/csnUtils');
-const { sortMessages, sortMessagesSeverityAware, deduplicateMessages } = require('./base/messages');
+const { traverseCsn } = require('./model/api');
+const { createMessageFunctions, sortMessages, sortMessagesSeverityAware, deduplicateMessages } = require('./base/messages');
 
 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)
 function version() {
@@ -31,7 +34,6 @@ const {
   messageString,
   messageStringMultiline,
   messageContext,
-  handleMessages,
   hasErrors,
   explainMessage,
   hasMessageExplanation
@@ -39,15 +41,35 @@ const {
 
 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, $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 );
+}
+
 function parseCql( cdl, filename = '<query>.cds', options = {} ) {
-  let xsn = parseLanguage( cdl, filename, Object.assign( {parseOnly:true}, options ), 'query' );
-  handleMessages( xsn, options );
+  const messageFunctions = createMessageFunctions( options, 'parse' );
+  const xsn = parseLanguage( cdl, filename, Object.assign( { parseOnly: true }, options ),
+                             messageFunctions, 'query' );
+  messageFunctions.throwWithError();
   return compactQuery( xsn );
 }
 
 function parseExpr( cdl, filename = '<expr>.cds', options = {} ) {
-  let xsn = parseLanguage( cdl, filename, Object.assign( {parseOnly:true}, options ), 'expr' );
-  handleMessages( xsn, options );
+  const messageFunctions = createMessageFunctions( options, 'parse' );
+  const xsn = parseLanguage( cdl, filename, Object.assign( { parseOnly: true }, options ),
+                             messageFunctions, 'expr' );
+  messageFunctions.throwWithError();
   return compactExpr( xsn );
 }
 
@@ -79,7 +101,7 @@ module.exports = {
   preparedCsnToEdm :  (csn, service, options) => { return backends.preparedCsnToEdm(csn, service, options).edmj},
 
   // additional API:
-  parse: { cql: parseCql, expr: parseExpr }, // preferred names
+  parse: { cdl: parseCdl, cql: parseCql, expr: parseExpr }, // preferred names
   /**
    * @deprecated Use parse.cql instead
    */
@@ -92,6 +114,9 @@ module.exports = {
   getArtifactCdsPersistenceName: getArtifactDatabaseNameOf,
   getElementCdsPersistenceName: getElementDatabaseNameOf,
 
+  // Other API functions:
+  traverseCsn,
+
   // INTERNAL functions for the cds-lsp package and friends - before you use
   // it, you MUST talk with us - there can be potential incompatibilities with
   // new releases (even having the same major version):

package/lib/model/api.js

@@ -0,0 +1,78 @@
+// Miscellaneous CSN functions we put into our compiler API
+
+// Do not change at will - they are in the compiler API!
+
+/**
+ * Dictionary of default traversal functions for function `traverseCsn`.
+ * It maps CSN property names to functions which are used by default
+ * to traverse the CSN node which is the value of the corresponding property.
+ * Users specify their own traversal function via argument `userFunctions`.
+ *
+ * Each function in `userFunctions` and `defaultFunctions` is called with:
+ * - `userFunctions`
+ * - the current CSN node, i.e. ‹parent node›.‹property name›
+ * - the the ‹parent node›
+ * - the ‹property name› (might be useful if the same function is used for several props)
+ */
+const defaultFunctions = {
+  '@': () => { /* do not traverse annotation assignments */ },
+  args: dictionary,
+  elements: dictionary,
+  enum: dictionary,
+  params: dictionary,
+  actions: dictionary,
+  mixin: dictionary,
+  definitions: dictionary,
+  '$': () => { /*  do not traverse properties starting with '$' */},
+}
+
+/**
+ * Traverse the CSN node `csn`.
+ * If `csn` is an array, call it recursively on each array item.
+ * If `csn` is an(other) object, call a function on each property:
+ * - The property name is a used as key in argument `userFunctions` and the
+ *   constant `defaultFunctions` above to get the function which is called on
+ *   the property value, see `defaultFunctions` for details.
+ * - If no function is found with the property name, try to find one with the first char.
+ * - If still not found, call `traverseCsn` recursively.
+ *
+ * The functions in `userFunctions` are usually transformer functions, which
+ * change the input CSN destructively.
+ */
+function traverseCsn( userFunctions, csn ) {
+  if (!csn || typeof csn !== 'object')
+    return;
+  if (Array.isArray( csn )) {
+    csn.forEach( node => traverseCsn( userFunctions, node ) );
+  }
+  else {
+    for (const prop of Object.keys( csn )) {
+      const func = userFunctions[prop] || defaultFunctions[prop] ||
+            userFunctions[prop.charAt(0)] || defaultFunctions[prop.charAt(0)] ||
+            traverseCsn;
+      func( userFunctions, csn[prop], csn, prop );
+    }
+  }
+}
+// people might want to have their own traversal function for `elements`, etc:
+traverseCsn.dictionary = dictionary;
+
+/**
+ * Traverse the CSN dictionary node `csn`.
+ * Call `traverseCsn` on each property value in `csn`, passing down `userFunctions`.
+ */
+function dictionary( userFunctions, csn ) {
+  if (!csn || typeof csn !== 'object')
+    return;
+  if (Array.isArray( csn )) {   // args can be both array and dictionary
+    csn.forEach( node => traverseCsn( userFunctions, node ) );
+  }
+  else {
+    for (const name of Object.keys( csn ))
+      traverseCsn( userFunctions, csn[name] );
+  }
+}
+
+module.exports = {
+  traverseCsn,
+};