@sap/cds-compiler 2.15.8 → 3.1.0

package/doc/ApiMigration.md

@@ -1,237 +0,0 @@
-# API Migration
-
-> Status Oct 2019: this document is still valid, but the recommended API will change (again) in the near future.
-> The future version of this document (renamed to `API.md`) will basically explain the recommended API,
-> the migration will only be a minor aspect and explained in a later section.
-
-<!-- The option handling might also change: -->
-<!-- the backend-specific structure is overly complex and not always appriopriate (e.g. naming mode). -->
-
-With revision 1.0.24, the CDS compiler offers new API backend functions, i.e. new functions for the
-generation of output from (augmented) CSN models. The new functions and their options are closely
-aligned with the new command line interface `cdsc`. The old backend functions are deprecated, will
-not be extended with new features, and will be removed in a subsequent release. Note that only these
-API functions from `lib/main.js` are supported - **all internal functions are subject to change without
-notice**.
-
-Please see the function headers in `lib/backends.js` for a description of the new API functions (for a
-snapshot of the current version, see below).
-
-## Some helpful hints
-
-Please note the following general concepts regarding the new API functions:
-- The behavior of the compiler and of all backend API functions is controlled by a common `options` object,
-  with subsections for each backend function, e.g. `options: {toHana: {src: true}, toOdata: {version: 'v2'}}`.
-- Options can either be specified with one of the `compile` functions (transported within the model to the
-  backends), or explicitly at the invocation of a backend API function.
-- Options are merged, with precedence given to those specified explicitly at the backend API functions.
-- When invoking a backend function with options that all belong to this backend function, the subsection wrapper
-  can be omitted, i.e. `toHana(model, {toHana: {src: true}})` is equivalent to `toHana(model, {src: true})`.
-- Most backend API functions have a combination of options controlling _what_ is generated
-  (e.g. `toHana: {src: true}`) and options modifying  _how_ things are generated (e.g. `toOdata: {version: 'v2'}`).
-
-## Migration guide
-
-The following table shows replacements for the deprecated API functions (relying on default options where possible):
-
-| Deprecated function call   | New function call                           |
-| -------------------------- | ------------------------------------------- |
-| `toHanaCdl(model)` | `toHana(model)`|
-| `forHana(model)` | `toHana(model, {csn: true})`|
-| `toOdataOutput(model, {oDataVersion: 'v2'}` | `toOdata(model, {version: 'v2', xml: true, json: true, separate: true, combined: true, csn: true})`|
-| `toSqlDdl(model)` | `toSql(model)`|
-| `compactJson(model)` | `toCsn(model)`|
-
-## Changes in behavior
-
-The following changes have been made to the behavior of `toOdata` in comparison to `toOdataOutput`:
-- Output is now generated either for ODATA V2 or for V4. The old `toOdataOutput` function produced the `annotations` output with
-  an extra invocation of the backend using `oDataVersion: 'v4'` even if the original invocation specified `oDataVersion: 'v2'`,
-  resulting in slightly different output. The `combined` output always had the correct versioning.
-- The `metadata_json` output is now an object, not a string.
-
-## Snapshot of backend API function documentation
-
-Note that these backend API functions are all exposed in `lib/main.js` (which is **the only external API**), but
-their documentation is currently located in `lib/backends.js` (this will likely change).
-
-### `toHana(model, options)`
-
-```
-// Transform an augmented CSN 'model' into HANA-compatible CDS source.
-// The following options control what is actually generated:
-//   options : {
-//     toHana.names        : either 'plain' (generate uppercased flattened entity names with
-//                           underscores) or 'quoted' (default, generate entity names with nested
-//                           contexts as in CDL)
-//     toHana.associations : either 'assocs' (default, keep associations as they are if possible)
-//                           or 'joins' (replace associations by joins)
-//     toHana.src          : if true, generate HANA CDS source files (default)
-//     toHana.csn          : if true, generate the transformed CSN model
-//   }
-// Options provided here are merged with (and take precedence over) options from 'model'.
-// If 'toHana.names' is not provided, 'quoted' is used.
-// If 'toHana.associations' is not provided, 'assocs' is used.
-// If neither 'toHana.src' nor 'toHana.csn' are provided, the default is to generate only HANA CDS
-// source files.
-// If all provided options are part of 'toHana', the 'toHana' wrapper can be omitted.
-// The result object contains the generation results as follows (as enabled in 'options'):
-//   result : {
-//     csn               : the (compact) transformed CSN model
-//     _augmentedCsn     : (subject to change): the augmented CSN model
-//     hdbcds            : a dictionary of top-level artifact names, containing for each name 'X':
-//       <X>             : the HANA CDS source string of the artifact 'X'. Please note that the
-//                         name of 'X' may contain characters that are not legal for filenames on
-//                         all operating systems (e.g. ':', '\' or '/').
-//     messages          : an array of strings with warnings (if any)
-//   }
-function toHana(model, options) {
-  ...
-}
-```
-
-### `toOdata(model, options)`
-
-```
-// Generate ODATA for augmented CSN `model` using `options`.
-// Before anything is generated, the following transformations are applied to 'model':
-// FIXME: Verify that this is still correct
-// - Flatten structured elements (and foreign keys of managed associations pointing to
-//   keys that are themselves managed associations).
-// - Generate foreign key fields for entities with managed associations (annotated with
-//   '@odata.foreignKey4'). Propagate along projections accordingly. Names are built using
-//   <assoc>_<key>, conflicts are checked.
-// - Complete the 'foreignKeys' property for all managed associations, so that there
-//   is always a 'generatedFieldName' for the corresponding generated foreign key field.
-// - Implicitly redirect associations based on exposure
-// - Check that exposed associations do not point to non-exposed targets
-// - Unravel derived type chains, propagating annotations upwards.
-// - Rename annotations according to a fixed list of short-hands
-// The following options control what is actually generated:
-//   options : {
-//     toOdata.version     : either 'v2' or 'v4' (default)
-//     toOdata.xml         : if true, generate XML output (default)
-//     toOdata.json        : if true, generate JSON output (not available for ODATA V2)
-//     toOdata.separate    : if true, generate XML 'metadata' and XML 'annotations' separately
-//     toOdata.combined    : if true, generate XML metadata and XML annotations together as
-//                           'combined' (default)
-//     toOdata.csn         : if true, generate the transformed CSN model
-//   }
-// Options provided here are merged with (and take precedence over) options from 'model'.
-// If 'toOdata.version' is not provided, 'v4' is used.
-// If neither 'toOdata.xml' nor 'toOdata.json' nor 'toOdata.csn' are provided, the default is
-// to generate only XML output. If neither 'toOdata.separate' nor 'toOdata.combined' are provided,
-// the default is to generate only combined XML output.
-// If all provided options are part of 'toOdata', the 'toOdata' wrapper can be omitted.
-//
-// The result object contains the generation results as follows (as enabled in 'options'):
-//   result : {
-//     csn               : the (compact) transformed CSN model including all services
-//     _augmentedCsn     : (subject to change): the augmented CSN model including all services
-//     services          : a dictionary of service names, containing for each name:
-//       <servicename> : {
-//         annotations   : an XML string with EDMX annotations for service 'svc'
-//         metadata      : an XML string with EDMX metadata for service 'svc'
-//         combined      : an XML string with both EDMX metadata and annotations for service 'svc'
-//         metadata_json : a JSON object (not a string!) with EDM metadata for service 'svc'
-//       }
-//     messages          : an array of strings with warnings (if any)
-//   }
-// If 'model' does not contain any services, 'csn' will still contain the transformed model, but
-// 'services' will be an empty dictionary.
-//
-// Throws a CompilationError on errors.
-function toOdata(model, options) {
-  ...
-}
-```
-
-### `toCdl(model, options)`
-
-```
-// Generate CDS source text for augmented CSN model 'model'.
-// The following options control what is actually generated:
-//   options : {
-//     FIXME: This option should be removed and something like 'toCdl.dialect: 'hana' be
-//            used instead.
-//     hanaFlavor : if true, HANA-specific source dialect is generated (affects e.g. the
-//                  translation of '$self.foo' in paths and ::-ish namespace declarations)
-//   }
-// One source is created per top-level artifact.
-// Return a dictionary of top-level artifacts
-// by their names, like this:
-// { "foo" : "using XY; context foo {...};",
-//   "bar::wiz" : "namespace bar::; entity wiz {...};"
-// }
-// Throws a CompilationError on errors.
-function toCdl(model, options) {
-  ...
-}
-```
-
-### `toSwagger(model, options)`
-
-```
-// Generate OpenAPI JSON version 3 for the augmented CSN 'model'.
-// Return an object representing the Swagger JSON:
-// {
-//   openapi: '3.0.0',
-//   info: { ... },
-//   paths: { ...},
-//   components: {
-//     schemas: { ... }
-//   }
-// }
-//
-// Throws a CompilationError on errors.
-function toSwagger(model, options) {
-  ...
-}
-```
-
-### `toSql(model, options)`
-
-```
-// Generate SQL DDL statements for augmented CSN 'model'.
-// The following options control what is actually generated:
-//   options : {
-//     toSql.names         : either 'plain' (generate uppercased flattened table/view names with
-//                           underscores) or 'quoted' (default, generate quoted table/view names
-//                           with dots as in CDL)
-//     toSql.associations  : either 'assocs' (default, keep associations as they are if possible)
-//                           or 'joins' (replace associations by joins)
-//     toSql.src           : if 'sql', generate SQL DDL source files (default)
-//     toSql.csn           : if true, generate the transformed CSN model
-//   }
-// Options provided here are merged with (and take precedence over) options from 'model'.
-// If 'toSql.names' is not provided, 'quoted' is used.
-// If 'toSql.associations' is not provided, 'assocs' is used.
-// If neither 'toSql.src' nor 'toSql.csn' are provided, the default is to generate only SQL DDL
-// source files.
-// If all provided options are part of 'toSql', the 'toSql' wrapper can be omitted.
-// The result object contains the generation results as follows (as enabled in 'options'):
-//   result : {
-//     csn               : the (compact) transformed CSN model
-//     _augmentedCsn     : (subject to change): the augmented CSN model
-//     sql               : a dictionary of top-level artifact names, containing for each name 'X':
-//       <X>             : a string with SQL DDL statements for artifact 'X', terminated with ';'.
-//                         Please note that the name of 'X' may contain characters that are not
-//                         legal for filenames on all operating systems (e.g. ':', '\' or '/').
-//     messages          : an array of strings with warnings (if any)
-//   }
-// Throws a CompilationError on errors.
-```
-
-### `toCsn(model, options)`
-
-```
-// Generate compact CSN for augmented CSN 'model'
-// The following options control what is actually generated:
-//   options : {
-//     testMode : if true, the result is extra-stable for automated tests (sorted, no 'version')
-//   }
-// Options provided here are merged with (and take precedence over) options from 'model'.
-function toCsn(model, options) {
-  ...
-}
-```

package/doc/CommandLineMigration.md

@@ -1,58 +0,0 @@
-# Command Line Migration
-
-> Status Oct 2019: this document is still basically valid.
-> The future version of this document (renamed to `CommandLine.md`) will basically explain the recommended CLI options,
-> the migration will only be a minor aspect and explained in a later section.
-
-<!-- The option handling might also change: -->
-<!-- the backend-specific structure is overly complex and not always appriopriate (e.g. naming mode). -->
-<!-- The placement of options should not depend on a not always apparent distinction between command-specific and general options. -->
-
-
-With revision 1.5.1, the `cdsc` command line interface has been adapted to use commands with
-options.
-
-Usage is now `cdsc <command> [options] <files...>` instead of `cdsc [options] <file...>`.
-
-The generation options (`--toHana`, `--toSql`, ...) have been replaced by commands
-(`toHana`, `toSql`, ...). This allows for better per-command options, which can now be optional,
-can use more single-letter abbreviations, and now match those from the `options` object in the API.
-
-Some examples:
-
-| Old command line        | New command line                           |
-| -------------------------- | --------------------------------------------- |
-| `cdsc --new-csn --toHana csn,plain foo.cds` | `cdsc --new-csn toHana --csn --names plain foo.cds` |
-| `cdsc -R --H csn,plain foo.cds` | `cdsc -R H -c -n plain foo.cds` |
-| `cdsc --toOdata xml,v2,separate foo.cds` | `cdsc toOdata --xml --version v2 --separate foo.cds` |
-| `cdsc --toSql src foo.cds` | `cdsc toSql foo.cds` |
-| `cdsc foo.cds` | `cdsc foo.cds` |
-
-List of commands (as of v1.5.1):
-
-```
-  Commands
-    H, toHana [options] <files...>     Generate HANA CDS source files
-    O, toOdata [options] <files...>    Generate ODATA metadata and annotations
-    C, toCdl <files...>                Generate CDS source files
-    S, toSwagger [options] <files...>  Generate Swagger (OpenAPI) JSON
-    Q, toSql [options] <files...>      Generate SQL DDL statements
-       toCsn [options] <files...>      (default) Generate original model as CSN
-       toTntSpecificOutput <files...>  (internal) Generate TNT-specific post-processed CSN
-       toRename [options] <files...>   (internal) Generate SQL DDL rename statements
-```
-
-Please see `cdsc --help` for the list of commands and general options, or `cdsc <command> --help`
-for help regarding a specific command.
-
-## Some helpful hints
-
-Please note the following general concepts regarding the new command line:
-- General options can be placed anywhere, command specific options must appear after the command.
-- In the unlikely case that a file name starts with `-`, please use `--` to indicate the end of options.
-- The `src` argument of `toHana`, `toCdl`, `toSql` is now optional (and it would now be `--src`).  
-- If no command is specified, the default is `toCsn --flavor client` (as before).
-- When no `--out` option is provided or if `-` is specified as output directory , all output will
-  go to `<stdout>` instead of being written to files (like before).
-- The `--raw-output` option also affects all commands where a CSN file is generated.
-  Instead of `...csn.json`, a `...csn_raw.txt` will be produced (like before).

package/doc/ErrorMessages.md

@@ -1,175 +0,0 @@
-# Error Messages Explained
-
-> Status Oct 2019: up-to-date
-
-This document tries to explain some of the less-obvious error messages.
-
-## Common Compiler Messages (Independent From Backend)
-
-### Duplicate definitions
-
-In most cases, you really have just used the same name twice when defining an artifact.
-This section is about a situation where you are pretty sure that you have not done that.
-
-```
-node_modules/Base/index.cds:1:6-7: Error: Duplicate definition of artifact "T"
-node_modules/base/index.cds:1:6-7: Error: Duplicate definition of artifact "T"
-node_modules/dep/node_modules/model/index.cds:1:8-9: Error: Duplicate definition of artifact "E"
-node_modules/model/index.cds:1:8-9: Error: Duplicate definition of artifact "E"
-```
-
-Here, the CDS Compiler considers `…/Base/index.cds` to be different to `…/base/index.cds`,
-and also considers the two `…/model/index.cds` files to be different files.
-Why is that the case?  Consider the following "top-level" file
-
-```
-using from 'Base';     // upper-case 'B'!
-using from 'model';
-using from 'dep';
-```
-
-File node_modules/dep/index.cds` looks like:
-
-```
-using from 'base';     // lower-case 'b'!
-using from 'model';
-```
-
-`node_modules/Base/index.cds` is the same file as
-`node_modules/base/index.cds` on case-insensitive file systems (Windows, Mac):
-
-```
-type T: Integer;
-```
-
-We have `node_modules/model/index.cds` and a copy of it in
-`node_modules/dep/node_modules/model/index.cds`:
-
-```
-entity E { i: Integer; }
-```
-
-The technical explanation is that the CDS Compiler considers
-two file names pointing to the same file if their `fs.realpath` is equal.
-That means that we properly _recognize symlinks_ (Linux, Mac),
-but we do _not_ recognize two files to be equal if:
-
-* the same file is referred to with different name casing,
-  which does not work on case-sensitive file systems (Linux) anyway
-  (yes, we might issue a better message when `node v9.2` is widely adopted),
-* a file is _copied_ within the NPM package (or when _hardlinks_ are used).
-
-The CDL code/package can be corrected as follows:
-
-* Use __consistent casing__ when referring to file and modules in `using from`
-  (if in doubt, please check the error output provided by the CDS compiler client tool).
-* __Clean up a dirty NPM installation__.  Then, the file
-  `node_modules/dep/node_modules/model/index.cds` should disappear
-  (or be a symlink to `node_modules/model/index.cds`).
-
-
-### Nested extensions
-
-If you use nested extensions, you might get messages like:
-
-```
-nested-extensions.cds:3:20-26: Error: No `EXTEND artifact` within CONTEXT extensions
-nested-extensions.cds:4:20-28: Error: No `ANNOTATE artifact` within SERVICE extensions
-nested-extensions.cds:5:14-22: Error: Elements only exist in entities, types or typed constructs
-nested-extensions.cds:6:12-36: Error: Elements only exist in entities, types or typed constructs
-```
-
-Artifacts (entities, types, …) should not be extended within other extensions –
-just elements (and other members) are to be extended within an artifact extension.
-The above messages are reported for the following CDL code:
-
-```
-context C { entity E { d: Integer; } }
-service S { entity E { d: Integer; } }
-extend context C { extend C.E { e: Integer; } }
-extend service S { annotate S.E @Anno; }
-annotate C { E @Anno; }
-extend S { extend E { e: Integer; } }
-```
-
-The reason for these messages is – if we would allow it:
-
-* If we follow the [normal name resolution rules](NameResolution.md),
-  people would have to refer to the entity the same way
-  as outside `extend context`/`extend service`.
-  Most people would probably expect being able
-  to write just `E` instead `C.E`/`S.E` in line 3 and 4,
-  but this not only require special rules, but leads to other surprises – see below.
-* Using `{ … }` inside a plain `annotate` or `extend` statement
-  is supposed to annotate/extend elements (or enums), not containing artifacts.
-
-The CDL code can be corrected as follows:
-
-```
-context C { entity E { d: Integer; } }
-service S { entity E { d: Integer; } }
-extend C.E { e: Integer; }
-annotate S.E @Anno;
-annotate C.E @Anno;
-extend S.E { e: Integer; }
-```
-
-Now consider that you could use the following to extend the entity `C.E`:
-
-```
-context C { entity E { key d: Integer; } }
-entity E { key x: Integer; }
-extend context C {
-    extend E { e: Integer; }          // i.e. extend C.E
-}
-extend context C {
-    entity F { a: association to E; } // target: E, not C.E (normal name resolution)
-}
-```
-
-What about combining the two `extend context`:
-
-```
-context C { entity E { key d: Integer; } }
-entity E { key x: Integer; }
-extend context C {
-    extend E { e: Integer; }          // i.e. extend C.E
-    entity F { a: association to E; } // target: E or C.E ?
-}
-```
-
-In summary, allowing artifact extensions inside `extend context`/`extend service`
-would provide little benefit, but would add complexity and confusion.
-
-
-### Redirection issues
-
-The target `OrigTarget` of an existing association can only be redirected to another target `NewTarget`
-if the `NewTarget` is a direct or indirect projection of `OrigTarget`
-(complex views are questionable and lead to a Warning),
-or an entity definition which directly or indirectly includes `OrigTarget`.
-
-```
-entity Base {
-    key i: Integer;
-}
-entity Proj as projection on Base;
-entity NewTarget as projection on Intermediate;
-entity Intermediate as projection on Base;
-
-entity Assocs {
-    base: association to Base;
-    proj: association to Proj;
-}
-entity Redirect as projection on Assocs {
-    base: redirected to NewTarget, // works
-    proj: redirected to NewTarget  // ERROR: does not originate from Proj
-}
-```
-
-For the above CDS code, you get the following error message:
-
-```
-redirect-to-unrelated.cds:16:25-34: Error: The redirected target does not originate from "Proj"
-    (in entity:"Redirect"/element:"proj")
-```

package/doc/FioriAnnotations.md

@@ -1,94 +0,0 @@
-# Translation of Fiori annotations
-
-> Status Oct 2019: too vague, old links, to be moved to internalDoc if we want to keep it.
-
-Fiori annotations are translated in a generic way. Essentially, write down in CDS precisely what you want to get in edmx.
-
-A more detailed description will follow soon, for the time being we hope the following example will give the idea:
-
-These CDS annotations
-```
-@(
-  UI.Chart : {
-    ChartType: #Bullet,
-    Measures: [ Revenue ],
-    MeasureAttributes: [
-      {
-        Measure: Revenue,
-        Role: #Axis1,
-        DataPoint: '@UI.DataPoint#BulletChartDataPoint'
-      }
-    ]
-  },
-  UI.DataPoint#BulletChartDataPoint: {
-    Title: 'Product',
-    Value: Revenue,
-    TargetValue: TargetRevenue,
-    ForecastValue: ForecastRevenue,
-    MinimumValue: MinValue,
-    MaximumValue: MaxValue,
-    CriticalityCalculation: {
-      ImprovementDirection: #Target,
-      ToleranceRangeLowValue: ToleranceRangeLow,
-      ToleranceRangeHighValue: ToleranceRangeHigh,
-      DeviationRangeLowValue: DeviationRangeLow,
-      DeviationRangeHighValue: DeviationRangeHigh
-    }
-  }
-)
-Something ...;
-```
-are translated into the following edmx:
-```xml
-<Annotations Target="Something">
-  <Annotation Term="UI.Chart">
-    <Record>
-      <PropertyValue EnumMember="UI.ChartType/Bullet"
-        Property="ChartType" />
-      <PropertyValue Property="Measures">
-        <Collection>
-          <PropertyPath>Revenue</PropertyPath>
-        </Collection>
-      </PropertyValue>
-      <PropertyValue Property="MeasureAttributes">
-        <Collection>
-          <Record Type="UI.ChartMeasureAttributeType">
-            <PropertyValue Property="Measure" PropertyPath="Revenue" />
-            <PropertyValue Property="Role" EnumMember="UI.ChartMeasureRoleType/Axis1" />
-            <PropertyValue Property="DataPoint" AnnotationPath="@UI.DataPoint#BulletChartDataPoint" />
-          </Record>
-        </Collection>
-      </PropertyValue>
-    </Record>
-  </Annotation>
-  <Annotation Term="UI.DataPoint" Qualifier="BulletChartDataPoint">
-    <Record>
-      <PropertyValue String="Product" Property="Title" />
-      <PropertyValue Path="Revenue" Property="Value" />
-      <PropertyValue Path="TargetRevenue" Property="TargetValue" />
-      <PropertyValue Path="ForecastRevenue" Property="ForecastValue" />
-      <PropertyValue Path="MinValue" Property="MinimumValue" />
-      <PropertyValue Path="MaxValue" Property="MaximumValue" />
-      <PropertyValue Property="CriticalityCalculation">
-        <Record>
-          <PropertyValue Property="ImprovementDirection" EnumMember="UI.ImprovementDirectionType/Target" />
-          <PropertyValue Path="ToleranceRangeLow" Property="ToleranceRangeLowValue" />
-          <PropertyValue Path="ToleranceRangeHigh" Property="ToleranceRangeHighValue" />
-          <PropertyValue Path="DeviationRangeLow" Property="DeviationRangeLowValue" />
-          <PropertyValue Path="DeviationRangeHigh" Property="DeviationRangeHighValue" />
-        </Record>
-      </PropertyValue>
-    </Record>
-  </Annotation>
-</Annotations>
-```
-
-
-All suppoted Fiori annotations are defined in the following vocabularies:
-* [Core](http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/vocabularies/Org.OData.Core.V1.xml)
-* [Measures](http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/vocabularies/Org.OData.Measures.V1.xml)
-* [Capabilities](http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/vocabularies/Org.OData.Capabilities.V1.xml)
-* [Aggregation](http://docs.oasis-open.org/odata/odata-data-aggregation-ext/v4.0/cs02/vocabularies/Org.OData.Aggregation.V1.xml)
-* [Common](https://wiki.scn.sap.com/wiki/download/attachments/448470974/Common.xml?api=v2)
-* [Communication](https://wiki.scn.sap.com/wiki/download/attachments/448470971/Communication.xml?api=v2)
-* [UI](https://wiki.scn.sap.com/wiki/download/attachments/448470968/UI.xml?api=v2)