@sap/cds-compiler 2.15.2 → 3.0.2

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)

package/doc/ODataTransformation.md

@@ -1,273 +0,0 @@
-# ODATA Transformation
-
-> Status Oct 2019: outdated, uses old-style CSN, to be reworked completely -> move to internalDoc/.
-> For users, OData is a backend, they do not care too much that it works via a CSN transformation.
-
-Prior to the generation of EDMX (Entity Data Model XML) files from a CDS model,
-the following transformations are applied to the model. Most (but not all) of
-them become visible both in Augmented CSN and in Plain CSN:
-
-## Generated foreign key fields for managed associations
-
-Managed associations do not have ON-conditions. Instead, they implicitly
-compare fields (usually the key fields) of the association's target entity with
-foreign key fields automatically generated into the entity containing the
-association.
-
-### Creating the generated fields
-
-The ODATA transformation adds the generated foreign key fields to the model.
-The names of the generated foreign key fields are a concatenation of the
-association element name, an underscore, and the key name or its alias.
-
-Each generated foreign key field gets the name of the corresponding association
-as an annotation `@odata.foreignKey4`.
-
-_FIXME_: Do we want to keep that?
-
-For example, for the three association elements `a1`, `a2` and `a3` in the
-following snippet:
-
-```
-service S {
-  entity FromEntity {
-    a1 : association to ToEntity;          // Use target's keys
-    a2 : association to ToEntity {x};      // Explicitly specified key
-    a3 : association to ToEntity {x as z}; // Key with alias
-  }
-
-  entity ToEntity {
-    key x : Integer;
-    key y : Integer;
-  }
-}
-```
-
-the ODATA transformation would generate foreign key fields in the resulting CSN
-as follows (shown here in CDS source form):
-
-```
-entity FromEntity {
-  a1 : association to ToEntity;
-  a2 : association to ToEntity {x};
-  @odata.foreignKey4: 'a1'
-  a1_x : Integer;  // Generated foreign key
-  @odata.foreignKey4: 'a1'
-  a1_y : Integer;  // Generated foreign key
-  @odata.foreignKey4: 'a2'
-  a2_x : Integer;  // Generated foreign key
-  @odata.foreignKey4: 'a3'
-  a3_z : Integer;  // Generated foreign key
-}
-```
-
-It is an error if the generated fields conflict with existing fields.
-
-### Annotation propagation
-
-The ODATA transformation propagates all annotations from the association to all
-its generated foreign key fields.
-
-_FIXME_: Do we want to keep that?
-
-### Connecting the associations with the generated fields
-
-The CSN for the managed association elements contains a `foreignKeys` property,
-which is a dictionary of foreign key names (taken from the target key names, or
-from explicitly specified keys resp. their aliases) to the foreign key
-properties.
-
-The ODATA transformation adds a `generatedFieldName` property to each foreign
-key, containing the name of the generated foreign key field. Together with the
-`@odata.foreignKey4` annotation described above, this provides a bi-directional
-link between the association and its generated field.
-
-For the example shown above, the CSN for the three association elements `a1`,
-`a2` and `a3` would look as follows:
-
-```
-  "a1": {
-    "indexNo": 1,
-    "target": "S.ToEntity",
-    "type": "cds.Association",
-    "foreignKeys": {
-      "x": {
-        "indexNo": 1,
-        "path": "x",
-        "generatedFieldName": "a1_x"
-      },
-      "y": {
-        "indexNo": 2,
-        "path": "y",
-        "generatedFieldName": "a1_y"
-      }
-    }
-  },
-  "a2": {
-    "indexNo": 2,
-    "target": "S.ToEntity",
-    "type": "cds.Association",
-    "foreignKeys": {
-      "x": {
-        "path": "x",
-        "indexNo": 1,
-        "generatedFieldName": "a2_x"
-      }
-    }
-  },
-  "a3": {
-    "indexNo": 3,
-    "target": "S.ToEntity",
-    "type": "cds.Association",
-    "foreignKeys": {
-      "z": {
-        "path": "x",
-        "indexNo": 1,
-        "generatedFieldName": "a3_z"
-      }
-    }
-  },
-```
-
-## (Augmented CSN only): Adding `_service` to exposed artifacts
-
-For each artifact that is exposed by a service (including the service itself),
-the ODATA transformation adds a non-enumerable property `_service` to the
-artifact in the Augmented CSN model, containing a link to the corresponding
-service artifact.
-
-This is convenient for EDMX processors that want to process only exposed
-artifacts or only artifacts belonging to a specific service.
-
-## Implicit redirection for non-exposed association targets
-
-For each exposed artifact that contains associations, it is checked that the
-association target is also exposed by the same service. If this is not the
-case, the ODATA transformation tries to find an "exposed representative" of
-the target, i.e. an exposed projection or view on the target, or an exposed entity
-that includes the target. If such a representative is found and unique, the
-association is implicitly redirected to the exposed representative.
-
-Note that only projections and projection-like views (i.e. those that have a
-single `from` source without `union`, `join` or nested queries) are considered
-as implicit redirection targets.
-
-Example:
-
-```
-// All these entities are used as association targets below
-// Simple target
-entity E1 {
-  key id : Integer;
-}
-// Base target included by E2a
-entity E2 {
-  key id : Integer;
-}
-entity E2a : E2 {
-  s : String(10);
-}
-// Base target included by S.E3a
-entity E3 {
-  key id : Integer;
-}
-
-// Exposure in service
-service S {
-  entity P1 as projection on E1;    // Exposes simple target E1
-  entity P2a as projection on E2a;  // Exposes E2a but also its included E2
-  entity E3a : E3 { };              // Exposes included E3
-
-  entity Redirected {
-    toE1 : association to E1;   // Implicitly redirected to P1 (projection exposes E1)
-    toE2 : association to E2;   // Implicitly redirected to P2a (projection exposes something that includes E2)
-    toE3 : association to E3;   // Implicitly redirected to E3a (entity includes E3)
-  }
-}
-```
-
-## Exposure checking
-
-Currently, it is assumed that services must be self-contained, i.e. that all
-associations within a service must point to targets also exposed by this
-service. This is checked by the ODATA transformation.
-
-_FIXME: The same restriction will probably apply when structured types are
-allowed as element types within exposed entities._
-
-## Unraveling derived scalar types
-
-The ODATA transformation unravels derived scalar types, i.e. primitive types
-for which the user has provided a custom name (possibly multiple times in a
-chain) are replaced by the original primitive type. Annotations are propagated
-upwards in the chain from the primitive type to the most derived type.
-
-For example, the following CDS source
-
-```
-@IsName: true
-type Name : String(20);
-
-@IsCustomer: true
-type CustomerName : Name;
-
-service S {
-  entity E {
-    name : CustomerName;
-  }
-}
-```
-
-essentially behaves as if the user had written
-
-```
-service S {
-  entity E {
-    @IsCustomer: true
-    @IsName: true
-    name : String(20);
-  }
-}
-```
-
-## (Tentative): Checking ON-conditions
-
-Currently, the ODATA transformation checks for various restrictions regarding
-ON-conditions of unmanaged associations:
-
-- only `=` and `AND` operators may be used
-- operands may only be paths or values (not expressions)
-- exactly one of the operands must traverse the association
-
-The intention behind this restriction is to produce a meaningful value for the
-`ReferentialConstraint` of the resulting `NavigationProperty`.
-
-_FIXME_: Do we want to keep that?
-
-## (Tentative): Renaming annotations
-
-Currently, the ODATA transformation renames various "shorthand" annotations to
-their more elaborate "long form".
-
-| Original name              | New name                                      |
-| -------------------------- | --------------------------------------------- |
-| `@label`                   | `@Common.Label`                               |
-| `@label`                   | `@Common.Label`                               |
-| `@title`                   | `@Common.Label`                               |
-| `@ValueList.entity`        | `@Common.ValueList.entity`                    |
-| `@ValueList.type`          | `@Common.ValueList.type`                      |
-| `@Capabilities.Deletable`  | `@Capabilities.DeleteRestrictions.Deletable`  |
-| `@Capabilities.Insertable` | `@Capabilities.InsertRestrictions.Insertable` |
-| `@Capabilities.Updatable`  | `@Capabilities.UpdateRestrictions.Updatable`  |
-| `@readonly`                | `@Core.Immutable`                             |
-| `@important`               | `@UI.Importance`                              |
-| `@assert.format`           | `@Validation.pattern: value`                  |
-| `@assert.range`            | `@Validation.Minimum/Maximum: value`          |
-|                            | or `@Validation.AllowedValues: {`             |
-|                            |      `@Core.SymbolicName: enum-name }`        |
-
-
-For the annotation `@important` (which is renamed to `@UI.Importance`), the
-values `true`/`false` are also replaced by the enum constants `#High`/`#Low`.
-
-_FIXME_: Do we want to keep that?