@sap/cds-compiler 3.1.2 → 3.4.0

package/lib/compiler/define.js

@@ -1,15 +1,31 @@
-// Compiler phase "define": transform dictionary of AST-like CSNs into augmented CSN
+// Compiler phase 1 = "define": transform dictionary of AST-like XSNs into XSN
 
-// AST-like CSN looks as follows:
-//   { kind: 'source', env: <dictionary of artifact defs>, namespace: {}, ... }
+// The 'define' phase (function 'define' below) is the first phase of the compile
+// function.  In it, the compiler
+//
+//  - collects definitions and extensions from the XSN representation of CDL and
+//    CSN sources (“ASTs”) into _one_ XSN model,
+//  - sets “structural” links between XSN nodes and completes the “name”,
+//    some links and names inside `extensions` are set at a later stage
+//  - reports errors for: “late” syntax errors (when it is more convenient to do
+//    it here instead of doing it in both CDL and CSN parser), “structural” errors
+//    and “duplicate definition errors”
+
+// The 'define' phase is the only compile() phase which is also called for
+// parse.cdl.  See file ./finalize-parse-cdl.js for details.
+
+// --------- TODO: begin in extra markdown document -----------------------------
+
+// An XSN for a source looks like
+//   { kind: 'source', artifacts: <dictionary of artifact defs>, namespace: {}, ... }
 //
 // The property `artifacts` of a source contains the top-level definitions.
 // Definitions inside a context are not listed here (as opposed to
 // `definitions`, see below), but inside the property `artifacts` of that context.
 
-// The define phase (function 'define' below) enriches a dictionary of
-// (file names to) AST-like CSNs and restructure them a little bit, the result
-// is called "augmented CSN":
+// The 'define' phase (function 'define' below) enriches a dictionary of
+// (file names to) AST-like XSNs and restructure them a little bit, the result
+// is called XSN ("augmented CSN"):
 //   { sources: <dictionary of ASTs>, definitions: <dictionary of artifact defs> }
 //
 // The property `sources` is the input argument (dictionary of source ASTs).
@@ -20,14 +36,8 @@
 // objects as the definitions accessible via `sources` and `artifacts` of the
 // corresponding source/context.
 //
-// Because different sources could define artifacts with the same absolute
-// name, this compiler phase also put a property `messages` to the resulting
-// model, which is a vector of messages for the redefinitions.  (Using the same
-// name for different definitions in one source is already recognized during
-// parsing.)
-//
 // You get the compact "official" CSN format by applying the function exported
-// by "../json/to-csn.js" to the augmented CSN.
+// by "../json/to-csn.js" to the XSN.
 
 // Example 'file.cds':
 //   namespace A;
@@ -54,7 +64,7 @@
 // An artifact definition looks as follows (example: context "A.B" above):
 //   {
 //     kind: 'context',
-//     name: { id: 'B', absolute: 'A.B', location: { <for the id "B"> } },
+//     name: { path: [ { id: 'B'} ], absolute: 'A.B', location: { <for the id "B"> } },
 //     artifacts: <for contexts, a dictionary of artifacts defined within>,
 //     location: { <of the complete artifact definition> } },
 //     _parent: <the parent artifact, here the source 'file.cds'>
@@ -74,11 +84,10 @@
 //     location: { <of the complete element definition> } },
 //     _parent: <the parent artifact, here the type "A.B.C">
 //   }
-// References are resolved in the "resolve" phase of the compiler, see
-// './resolver.js'.  We then get the properties `type.absolute` and `length`.
+// --------- TODO: end in extra markdown document -------------------------------
 
 // Sub phase 1 (addXYZ) - only for main artifacts
-//  - set _block links
+//  - set _block links for main definitions, vocabulary and extensions
 //  - store definitions (including context extensions), NO duplicate check
 //  - artifact name check
 //  - Note: the only allow name resolving is resolveUncheckedPath(),
@@ -96,6 +105,7 @@
 // More sub phases...
 
 // The main difficulty is the correct behavior concerning duplicate definitions
+//  - For code completion, all duplicate definitions must be further checked.
 //  - We need a unique object for the _subArtifacts dictionary.
 //  - We must have a property at the artifact whether there are duplicates in order
 //    to avoid consequential or repeated errors.
@@ -121,6 +131,7 @@ const {
   dependsOnSilent,
   pathName,
   splitIntoPath,
+  annotationHasEllipsis,
 } = require('./utils');
 const { compareLayer } = require('./moduleLayers');
 const { initBuiltins, isInReservedNamespace } = require('./builtins');
@@ -148,15 +159,15 @@ function define( model ) {
   const {
     resolveUncheckedPath,
     checkAnnotate,
-    defineAnnotations,
   } = model.$functions;
 
   const extensionsDict = Object.create(null);
   Object.assign( model.$functions, {
     initArtifact,
     initMembers,
-    extensionsDict,             // a dictionary - TODO: remove
+    extensionsDict,             // a dictionary - TODO: put directly into model?
     checkDefinitions,
+    initAnnotations,
   } );
   // During the definer, we can only resolve artifact references, i.e,
   // after a `.`, we only search in the `_subArtifacts` dictionary:
@@ -193,8 +204,9 @@ function define( model ) {
       initNamespaceAndUsing( model.sources[name] );
     dictForEach( model.definitions, initArtifact );
     dictForEach( model.vocabularies, initVocabulary );
+    dictForEach( extensionsDict, initExtension );
 
-    mergeI18nBlocks( model );
+    mergeI18nBlocks();
   }
 
   // Phase 1: ----------------------------------------------------------------
@@ -213,9 +225,8 @@ function define( model ) {
     let namespace = src.namespace && src.namespace.path;
     let prefix = namespace ? `${ pathName( namespace ) }.` : '';
     if (isInReservedNamespace(prefix)) {
-      error( 'reserved-namespace-cds', [ src.namespace.location, src.namespace ], {},
-             // TODO: use $(NAME)
-             'The namespace "cds" is reserved for CDS builtins' );
+      error( 'reserved-namespace-cds', [ src.namespace.location, src.namespace ], { name: 'cds' },
+             'The namespace $(NAME) is reserved for CDS builtins' );
       namespace = null;
     }
     if (src.$frontend !== 'json') { // CDL input
@@ -249,9 +260,8 @@ function define( model ) {
     const { absolute } = art.name;
     // TODO: check reserved, see checkName()/checkLocalizedObjects() of checks.js
     if (absolute === 'cds' || isInReservedNamespace(absolute)) {
-      error( 'reserved-namespace-cds', [ art.name.location, art ], {},
-             // TODO: use $(NAME)
-             'The namespace "cds" is reserved for CDS builtins' );
+      error( 'reserved-namespace-cds', [ art.name.location, art ], { name: 'cds' },
+             'The namespace $(NAME) is reserved for CDS builtins' );
       const builtin = model.definitions[absolute];
       if (builtin && builtin.builtin) // if already a builtin...
         return;
@@ -259,8 +269,6 @@ function define( model ) {
     }
     else if (art.query && (absolute === 'localized' || absolute.startsWith( 'localized.' ))) {
       // Due to recompilation, we don't emit this info message for JSON frontend.
-      // TODO: generalize this for $generated (definitions starting with
-      // "localized" just have `$generated: true` as default)
       if (block.$frontend !== 'json') {
         info( 'ignored-localized-definition', [ art.name.location, art ], {},
               'This definition in the namespace "localized" is ignored' );
@@ -398,7 +406,7 @@ function define( model ) {
 
   // Phase 2 ("init") --------------------------------------------------------
   // Functions called from top-level: initNamespaceAndUsing(), initArtifact(),
-  // initVocabulary()
+  // initVocabulary(), initExtension()
 
   function checkRedefinition( art ) {
     if (!art.$duplicates || art.$errorReported === 'syntax-duplicate-extend' ||
@@ -419,6 +427,8 @@ function define( model ) {
   }
 
   function initNamespaceAndUsing( src ) {
+    if (src.$frontend && src.$frontend !== 'cdl')
+      return;
     if (src.namespace) {
       const decl = src.namespace;
       const { path } = decl;
@@ -463,11 +473,11 @@ function define( model ) {
       initParentLink( art, model.definitions );
     const block = art._block;
     checkRedefinition( art );
-    defineAnnotations( art, art, block );
+    initAnnotations( art, block );
     initMembers( art, art, block );
     initDollarSelf( art );      // $self
     if (art.params)
-      initParams( art );        // $parameters
+      initDollarParameters( art );
     if (art.includes && !(art.name.absolute in extensionsDict)) // TODO: in next phase?
       extensionsDict[art.name.absolute] = []; // structure with includes must be "extended"
 
@@ -478,19 +488,23 @@ function define( model ) {
     if (!setLink( art, '_leadingQuery', initQueryExpression( art.query, art ) ) )
       return;                   // null or undefined in case of parse error
     setLink( art._leadingQuery, '_$next', art );
-    // the following we be removed soon if we have:
+    // the following may be removed soon if we have:
     // view elements as proxies to elements of leading query
     if (art.elements) { // specified element via compilation of client-style CSN
       setLink( art, 'elements$', art.elements );
       delete art.elements;
     }
+    if (art.enum) { // specified enum via compilation of client-style CSN
+      setLink( art, 'enum$', art.enum );
+      delete art.enum;
+    }
   }
 
   function initVocabulary( art ) {
     initParentLink( art, model.vocabularies );
     checkRedefinition( art );
     const block = art._block;
-    defineAnnotations( art, art, block );
+    initAnnotations( art, block );
     initMembers( art, art, block );
   }
 
@@ -516,6 +530,57 @@ function define( model ) {
       parent._subArtifacts[absolute.substring( dot + 1 )] = art; // not dictAdd()
   }
 
+  /** Initialize the extension `ext`.
+   *
+   * Currently:
+   *
+   *  - initialize annotations (set _block, $priority, `...` check) on "main"
+   *    extension and its columns do more later
+   *  - for members in compile(): init annotations via extendMembers/annotateMembers
+   *  - for members in parse.cdl(): init annotation via initMembers
+   *
+   * In the future:
+   *
+   *  - also initialize members and member extensions/annotations here
+   *  - we might also do other things, like calculating whether an `extend` is
+   *    `annotate`-like, i.e. only contains name-resolution irrelevant extensions.
+   */
+  function initExtension( ext ) {
+    const block = ext._block;
+    initAnnotations( ext, block, ext.kind );
+    if (ext.columns)            // the columns themselves are "definitions"
+      ext.columns.forEach( col => initAnnotations( col, block ) );
+  }
+
+  // Set _block links for annotations (necessary for layering) and do a late
+  // syntax check (`...` only with extensions, not definitions).
+  // extKind is either ext.kind (=art is extension) or false (=art is not an extension)
+  function initAnnotations( art, block, extKind = false ) {
+    // TODO: think of removing $priority, then
+    // no _block: define, _block: annotate/extend/edmx
+    // would fit with extending defs with props like length
+    for (const prop in art) {
+      if (prop.charAt(0) === '@') {
+        const anno = art[prop];
+        // TODO: make anno never be an array, see addAnnotation() in genericAntlrParser
+        if (Array.isArray( anno ))
+          anno.forEach( init );
+        else
+          init( anno );
+      }
+    }
+    return;
+
+    function init( anno ) {
+      setLink( anno, '_block', block );
+      anno.$priority = extKind;
+      if (!extKind && annotationHasEllipsis( anno )) {
+        error( 'anno-unexpected-ellipsis',
+               [ anno.name.location, art ], { code: '...' } );
+      }
+    }
+  }
+
   // From here til EOF, reexamine code ---------------------------------------
   // See populate:
   // - userQuery() or _query property?
@@ -541,7 +606,8 @@ function define( model ) {
     setLink( art, '_$next', model.$magicVariables );
   }
 
-  function initParams( art ) {
+  function initDollarParameters( art ) {
+    // TODO: remove $parameters in v4?
     // TODO: use setMemberParent() ?
     const parameters = {
       name: { id: '$parameters', param: '$parameters', absolute: art.name.absolute },
@@ -604,16 +670,16 @@ function define( model ) {
       // Either expression (value), expand or new association (target && type)
       else if (col.value || col.expand || (col.target && col.type)) {
         setLink( col, '_block', parent._block );
-        defineAnnotations( col, col, parent._block );
+        initAnnotations( col, parent._block );
         if (col.inline) { // `@anno elem.{ * }` does not work
           if (col.doc)
-            warning( 'syntax-anno-ignored', [ col.doc.location, col ], { '#': 'doc' } );
+            warning( 'syntax-ignoring-anno', [ col.doc.location, col ], { '#': 'doc' } );
 
           // col.$annotations no available for CSN input, have to search.
           // Warning about first annotation should be enough to avoid spam.
           const firstAnno = Object.keys(col).find(key => key.startsWith('@'));
           if (firstAnno)
-            warning( 'syntax-anno-ignored', [ col[firstAnno].name.location, col ] );
+            warning( 'syntax-ignoring-anno', [ col[firstAnno].name.location, col ] );
         }
         // TODO: allow sub queries? at least in top-level expand without parallel ref
         if (columns)
@@ -658,7 +724,7 @@ function define( model ) {
 
   /**
    * If we have a valid top-level exists, exists in filters of sub-expressions can be translated,
-   * since we will have a top-level subquery after exists-processing in the forHanaNew.
+   * since we will have a top-level subquery after exists-processing in the forRelationalDB.
    *
    * Recursively drill down into:
    * - the .path
@@ -886,17 +952,21 @@ function define( model ) {
   /**
    * Set property `_parent` for all elements in `parent` to `parent` and do so
    * recursively for all sub elements.
+   *
+   * If not for extensions: construct === parent
    */
-  // If not for extensions: construct === parent
   function initMembers( construct, parent, block, initExtensions = false ) {
     // TODO: split extend from init
     const isQueryExtension = kindProperties[construct.kind].isExtension &&
           (parent._main || parent).query;
     let obj = construct;
-    if (obj.items) {            // TODO: while
-      setLink( obj.items, '_outer', obj );
-      obj = obj.items;          // TODO: probably set parent = obj (is so in csnRefs)
-      setLink( obj, '_block', block );
+    let { items } = obj;
+    while (items) {
+      setLink( items, '_outer', obj );
+      setLink( items, '_parent', obj._parent );
+      setLink( items, '_block', block );
+      obj = items;
+      items = obj.items;
     }
     if (obj.target && targetIsTargetAspect( obj )) {
       obj.targetAspect = obj.target;
@@ -913,7 +983,7 @@ function define( model ) {
       if (obj.on && !obj.target) {
         error( 'unexpected-on-for-composition', [ obj.on.location, construct ],
                {},
-               'A managed aspect composition can\'t have a specified ON condition' );
+               'A managed aspect composition can\'t have a specified ON-condition' );
         delete obj.on;          // continuation semantics: not specified
       }
       if (targetAspect.elements) {
@@ -1017,9 +1087,9 @@ function define( model ) {
       setMemberParent( elem, name, parent, construct !== parent && prop );
       // console.log(message( null, elem.location, elem, {}, 'Info', 'INIT').toString())
       checkRedefinition( elem );
-      if (elem.kind === 'annotate')
+      if (elem.kind === 'annotate' || elem.kind === 'extend')
         checkAnnotate( elem, elem );
-      defineAnnotations( elem, elem, bl );
+      initAnnotations( elem, bl );
       initMembers( elem, elem, bl, initExtensions );
 
       // for a correct home path, setMemberParent needed to be called
@@ -1039,7 +1109,7 @@ function define( model ) {
                    std: 'Elements can\'t have a value',
                    entity: 'Entity elements can\'t have a value',
                    type: 'Type elements can\'t have a value',
-                   extend: 'Cannot extend type/entity elements with values',
+                   extend: 'Can\'t extend type/entity elements with values',
                  });
           return;
         }
@@ -1072,8 +1142,11 @@ function define( model ) {
              'Actions and functions only exist top-level and for entities' );
     }
     else if (parent.kind === 'action' || parent.kind === 'function') {
-      error( 'extend-action', [ construct.location, construct ], {},
-             'Actions and functions can\'t be extended, only annotated' );
+      error( 'extend-action', [ construct.location, construct ], { '#': parent.kind }, {
+        std: 'Actions and functions can\'t be extended, only annotated',
+        action: 'Actions can\'t be extended, only annotated',
+        function: 'Functions can\'t be extended, only annotated',
+      } );
     }
     else if (prop === 'params') {
       if (!feature) {
@@ -1105,29 +1178,27 @@ function define( model ) {
     }
     return construct === parent;
   }
-}
 
-/**
- * Merge (optional) translations into the XSN model.
- *
- * @param {XSN.Model} model
- */
-function mergeI18nBlocks( model ) {
-  const sortedSources = Object.keys(model.sources)
-    .filter(name => !!model.sources[name].i18n)
-    .sort( (a, b) => compareLayer( model.sources[a], model.sources[b] ) );
+  /**
+   * Merge (optional) translations into the XSN model.
+   */
+  function mergeI18nBlocks() {
+    const sortedSources = Object.keys(model.sources)
+      .filter(name => !!model.sources[name].i18n)
+      .sort( (a, b) => compareLayer( model.sources[a], model.sources[b] ) );
 
-  if (sortedSources.length === 0)
-    return;
+    if (sortedSources.length === 0)
+      return;
 
-  if (!model.i18n)
-    model.i18n = Object.create( null );
+    if (!model.i18n)
+      model.i18n = Object.create( null );
 
-  for (const name of sortedSources)
-    initI18nFromSource( model.sources[name] );
+    for (const name of sortedSources)
+      initI18nFromSource( model.sources[name] );
+  }
 
   /**
-   * Add the source's translations to the model. Warns if the sources translations
+   * Add the source's translations to the model. Warns if the source's translations
    * do not match the ones from previous sources.
    *
    * @param {XSN.SourceAst} src
@@ -1144,9 +1215,8 @@ function mergeI18nBlocks( model ) {
           model.i18n[langKey][textKey] = sourceVal;
         }
         else if (modelVal.val !== sourceVal.val) {
-          // TODO: put mergeI18nBlocks() into main function instead
-          model.$messageFunctions.warning( 'i18n-different-value', sourceVal.location,
-                                           { prop: textKey, otherprop: langKey } );
+          warning( 'i18n-different-value', sourceVal.location,
+                   { prop: textKey, otherprop: langKey } );
         }
       }
     }