@sap/cds-compiler 2.15.2 → 3.0.2

package/lib/transform/universalCsn/universalCsnEnricher.js

@@ -29,10 +29,7 @@ module.exports = (csn, options) => {
   const definitionPropagationRules = {
     '@cds.autoexpose': onlyViaArtifact,
     '@fiori.draft.enabled': onlyViaArtifact,
-    '@': (prop, target, source) => {
-      if (source[prop] !== null)
-        target[prop] = source[prop];
-    },
+    '@': nullStopsPropagation,
     // Example: `type E : F;` does not have `elements`, but they are required for e.g. OData.
     elements: onlyTypeDef,
     '@cds.persistence.exists': skip,
@@ -48,7 +45,7 @@ module.exports = (csn, options) => {
     '@cds.autoexposed': skip,
     '@cds.redirection.target': skip,
     type: always,
-    doc: always,
+    doc: nullStopsPropagation,
     length: always,
     precision: always,
     scale: always,
@@ -94,6 +91,10 @@ module.exports = (csn, options) => {
     }, // overwrite from defProps
     kind: skip,
     val: always,
+    type: notWithItemsOrElements,
+    target: notWithItemsOrElements,
+    keys: notWithItemsOrElements,
+    cardinality: notWithItemsOrElements,
   };
 
   generate();
@@ -702,6 +703,19 @@ function notWithTypeOrigin(prop, target, source) {
     target[prop] = source[prop];
 }
 
+/**
+ * The value `null` tells us to skip the propagation of the property.
+ * This is the case e.g. for `doc` or for annotations.
+ *
+ * @param {string} prop
+ * @param {CSN.Element} target
+ * @param {CSN.Element} source
+ */
+function nullStopsPropagation(prop, target, source) {
+  if (source[prop] !== null)
+    target[prop] = source[prop];
+}
+
 /**
  * Special propagation rules for .items - depending on the exact type of .items and the
  * way it was referenced (type of, direct type, direct many), we need to propagate (or not).
@@ -722,6 +736,20 @@ function specialItemsRules(prop, target, source) {
     target[prop] = source[prop];
 }
 
+/**
+ * Don't propagate certain properties if the target already has a .items or .elements
+ *
+ * This happens with .expand/.inline
+ *
+ * @param {string} prop
+ * @param {CSN.Element} target
+ * @param {CSN.Element} source
+ */
+function notWithItemsOrElements(prop, target, source) {
+  if (!target.items && !target.elements || !source.target)
+    target[prop] = source[prop];
+}
+
 /**
  * Some properties must not be copied over if the type of this member
  * is a reference to another element.

package/lib/utils/file.js

@@ -61,12 +61,12 @@ function cdsFs(fileCache, enableTrace) {
   };
 
   function realpath(path, cb) {
-    return fs.realpath(path, cb);
+    return fs.realpath.native(path, cb);
   }
 
   function realpathSync(path, cb) {
     try {
-      cb(null, fs.realpathSync(path));
+      cb(null, fs.realpathSync.native(path));
     }
     catch (err) {
       cb(err, null);
@@ -87,7 +87,7 @@ function cdsFs(fileCache, enableTrace) {
       }
       let body = fileCache[filename];
       if (body && typeof body === 'object' && body.realname) {
-        filename = body.realname; // use fs.realpath name
+        filename = body.realname; // use fs.realpath.native name
         body = fileCache[filename];
       }
       if (body !== undefined && body !== true) { // true: we just know it is there
@@ -113,11 +113,16 @@ function cdsFs(fileCache, enableTrace) {
         traceFS( 'READFILE:start:', filename );
         // TODO: set cache directly to some "delay" - store error differently?
         // e.g. an error of callback functions!
-        reader(filename, enc, ( err, data ) => {
-          fileCache[filename] = err || data;
-          traceFS( 'READFILE:data:', filename, err || data );
-          cb( err, data );
-        });
+        try {
+          reader(filename, enc, (err, data) => {
+            fileCache[filename] = err || data;
+            traceFS('READFILE:data:', filename, err || data);
+            cb(err, data);
+          });
+        }
+        catch (err) {
+          cb(err); // if filename is not a valid (e.g. contains NUL byte), readFile() may throw
+        }
       }
     };
   }
@@ -143,19 +148,24 @@ function cdsFs(fileCache, enableTrace) {
         // in the future (if we do module resolve ourself with just readFile),
         // we avoid parallel readFile by storing having an array of `cb`s in
         // fileCache[ filename ] before starting fs.readFile().
-        fsStat( filename, ( err, stat ) => {
-          if (err)
-            body = (err.code === 'ENOENT' || err.code === 'ENOTDIR') ? false : err;
-          else
-            body = !!(stat.isFile() || stat.isFIFO());
-          if (fileCache[filename] === undefined) // parallel readFile() has been processed
-            fileCache[filename] = body;
-          traceFS( 'ISFILE:data:', filename, body );
-          if (body instanceof Error)
-            cb( err );
-          else
-            cb( null, body );
-        });
+        try {
+          fsStat(filename, (err, stat) => {
+            if (err)
+              body = (err.code === 'ENOENT' || err.code === 'ENOTDIR') ? false : err;
+            else
+              body = !!(stat.isFile() || stat.isFIFO());
+            if (fileCache[filename] === undefined) // parallel readFile() has been processed
+              fileCache[filename] = body;
+            traceFS('ISFILE:data:', filename, body);
+            if (body instanceof Error)
+              cb(err);
+            else
+              cb(null, body);
+          });
+        }
+        catch (err) {
+          cb(err); // if filename is not a valid (e.g. contains NUL byte), fsStat() may throw
+        }
       }
     };
   }

package/lib/utils/timetrace.js

@@ -14,47 +14,43 @@ class StopWatch {
    */
   constructor(id) {
     this.id = id;
-    // TODO: If we require Node 12, use process.hrtime.bigint()
-    //       as process.hrtime() is deprecated.
-    // eslint-disable-next-line no-multi-assign
-    this.startTime = this.lapTime = process.hrtime();
+    this.startTime = process.hrtime.bigint();
+    this.lapTime = this.startTime;
   }
 
   /**
-     * Start watch.
-     */
+   * Start watch.
+   */
   start() {
-    // eslint-disable-next-line no-multi-assign
-    this.startTime = this.lapTime = process.hrtime();
+    this.startTime = process.hrtime.bigint();
+    this.lapTime = this.startTime;
   }
 
   /**
-   * Stop and return delta T
+   * Stop and return delta T in nanoseconds,
    * but do not set start time
    */
   stop() {
-    return process.hrtime(this.startTime);
+    const endTime = process.hrtime.bigint();
+    return endTime - this.startTime;
   }
 
-  /**
-   * return lap time
-   */
   lap() {
-    const dt = process.hrtime(this.lapTime);
-    this.lapTime = process.hrtime();
+    const endTime = process.hrtime.bigint();
+    const dt = endTime - this.startTime;
+    this.lapTime = process.hrtime.bigint();
     return dt;
   }
 
-  // stop as sec.ns float
   stopInFloatSecs() {
     const dt = this.stop();
-    return dt[0] + dt[1] / 1000000000;
+    return dt / BigInt(1000000000);
   }
 
   // lap as sec.ns float
   lapInFloatSecs() {
     const dt = this.lap();
-    return dt[0] + dt[1] / 1000000000;
+    return dt / BigInt(1000000000);
   }
 }
 
@@ -63,7 +59,7 @@ class StopWatch {
  *
  * Results are logged to stderr
  *
- * To enable time tracing, set CDSC_TIMETRACE to true in the environment
+ * To enable time tracing, set CDSC_TIMETRACING to true in the environment
  *
  * @class TimeTracer
  */
@@ -107,10 +103,13 @@ class TimeTracer {
   stop() {
     try {
       const current = this.traceStack.pop();
-      const dT = current.stop();
+      const dt = current.stop();
       const base = `${ ' '.repeat(this.traceStack.length * 2) }${ current.id } took:`;
+      const sec = (dt / BigInt(1000000000)).toString();
+      // first, get remaining ns, then convert to ms.
+      const msec = ((dt % BigInt(1000000000)) / BigInt(1000000)).toString();
       // eslint-disable-next-line no-console
-      console.error( `${ base }${ ' '.repeat(60 - base.length) } %ds %dms`, dT[0], dT[1] / 1000000);
+      console.error( `${ base }${ ' '.repeat(60 - base.length) } %ds %dms`, sec, msec );
     }
     catch (e) {
       // eslint-disable-next-line no-console

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@sap/cds-compiler",
-  "version": "2.15.2",
+  "version": "3.0.2",
   "description": "CDS (Core Data Services) compiler and backends",
   "homepage": "https://cap.cloud.sap/",
   "author": "SAP SE (https://www.sap.com)",
   "license": "SEE LICENSE IN LICENSE",
+  "type": "commonjs",
   "bin": {
     "cdsc": "bin/cdsc.js",
     "cdshi": "bin/cdshi.js",
@@ -13,13 +14,42 @@
   "main": "lib/main.js",
   "types": "lib/main.d.ts",
   "scripts": {
-    "postinstall": "node lib/fix_antlr4-8_warning.js"
+    "download": "node scripts/downloadANTLR.js",
+    "gen": "node ./scripts/build.js && node scripts/genGrammarChecksum.js",
+    "xmakeBeforeInstall": "echo \"Due to binary mirror, use sqlite 5.0.8 explicitly\" && npm install --save --save-exact --no-package-lock sqlite3@5.0.8",
+    "xmakeAfterInstall": "npm run gen",
+    "xmakePrepareRelease": "echo \"$(node scripts/stripReadme.js README.md)\" > README.md && node scripts/assertSnapshotVersioning.js && node scripts/assertChangelog.js && node scripts/cleanup.js --remove-dev",
+    "test": "node scripts/verifyGrammarChecksum.js && mocha --reporter min --reporter-option maxDiffSize=0 scripts/testLazyLoading.js && mocha --parallel --reporter min --reporter-option maxDiffSize=0 test/ test3/",
+    "testverbose": "node scripts/verifyGrammarChecksum.js && mocha --parallel test/ test3/",
+    "test3": "node scripts/verifyGrammarChecksum.js && node scripts/linter/lintTests.js test3/ && mocha --reporter-option maxDiffSize=0 scripts/linter/lintMessages.js test3/",
+    "deployTest3SQL": "deployRefs=true mocha --reporter-option maxDiffSize=0 test3/testHANASQLDeployment.js",
+    "deployTest3": "deployRefs=true mocha --reporter-option maxDiffSize=0 test3/testDeployment.js",
+    "deployDiffs": "deployRefs=true mocha --reporter-option maxDiffSize=0 test3/deployDiffs.js",
+    "gentest3": "cross-env MAKEREFS=${MAKEREFS:-'true'} mocha --reporter-option maxDiffSize=0 test3/testRefFiles.js",
+    "testdb": "node scripts/verifyGrammarChecksum.js && cross-env TESTDB='TRUE' mocha",
+    "testmigration": "npm install --no-save @sap/hana-client@2.3.123 @sap/hdi-deploy@3.10.0 && node scripts/verifyGrammarChecksum.js && cross-env TESTMIGRATION='TRUE' mocha",
+    "testall": "npm install --no-save @sap/hana-client@2.3.123 @sap/hdi-deploy@3.10.0 && node scripts/verifyGrammarChecksum.js && cross-env TESTDB='TRUE' TESTMIGRATION='TRUE' mocha",
+    "coverage": "cross-env nyc mocha --reporter-option maxDiffSize=0 test/ test3/ && nyc report --reporter=lcov",
+    "lint": "eslint bin/ benchmark/ lib/ test/ test3/ scripts/ types/ && node scripts/linter/lintGrammar.js && node scripts/linter/lintTests.js test3/ && markdownlint README.md CHANGELOG.md doc/ internalDoc/ && cd share/messages && markdownlint .",
+    "tslint": "tsc --pretty -p .",
+    "updateVocs": "node scripts/odataAnnotations/generateDictMain.js && npm run generateAllRefs",
+    "generateCompilerRefs": "cross-env MAKEREFS='true' mocha test/testCompiler.js",
+    "generateEdmRefs": "cross-env MAKEREFS='true' mocha test/testEdmPositive.js",
+    "generateForHanaRefs": "cross-env MAKEREFS='true' mocha test/testHanaTransformation.js",
+    "generateOdataRefs": "cross-env MAKEREFS='true' mocha test/testODataTransformation.js",
+    "generateOdataAnnoRefs": "cross-env MAKEREFS='true' mocha test/testODataAnnotations.js",
+    "generateToSqlRefs": "cross-env MAKEREFS='true' mocha test/testToSql.js",
+    "generateToRenameRefs": "cross-env MAKEREFS='true' mocha test/testToRename.js",
+    "generateChecksRefs": "cross-env MAKEREFS='true' mocha test/testChecks.js",
+    "generateScenarioRefs": "cross-env MAKEREFS='true' mocha test/testScenarios.js",
+    "generateDraftRefs": "cross-env MAKEREFS='true' mocha test/testDraft.js",
+    "generateAllRefs": "node scripts/verifyGrammarChecksum.js && cross-env MAKEREFS='true' mocha --reporter-option maxDiffSize=0 test/ test3/"
   },
   "keywords": [
     "CDS"
   ],
   "dependencies": {
-    "antlr4": "4.8.0"
+    "antlr4": "4.9.3"
   },
   "files": [
     "bin",
@@ -32,6 +62,6 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=12"
+    "node": ">=14"
   }
 }

package/share/messages/syntax-expected-integer.md

@@ -1,12 +1,12 @@
 # syntax-expected-integer
 
 The compiler expects a safe integer here.
-The last safe Integer is `2^53 - 1` or `9007199254740991`.
+The last safe integer is `2^53 - 1` or `9007199254740991`.
 
-A safe integer is an integer that
+A safe integer is an integer that fulfills all of the following:
 
-- can be exactly represented as an IEEE-754 double precision number, and
-- whose IEEE-754 representation cannot be the result of rounding any
+- Can be exactly represented as an IEEE-754 double precision number.
+- The IEEE-754 representation cannot be the result of rounding any
   other integer to fit the IEEE-754 representation.
 
 The message's severity is `Error`.
@@ -15,13 +15,14 @@ The message's severity is `Error`.
 
 Erroneous code example:
 
+<!-- cds-mode: ignore -->
 ```cdl
 type LengthIsUnsafe : String(9007199254740992);
 type NotAnInteger : String(42.1);
 ```
 
-In the above example, the string length for the type `LengthIsUnsafe` is not a
-safe Integer. It is too large.
+In the erroneous example, the string length for the type `LengthIsUnsafe` is
+not a safe integer. It is too large.
 Likewise, the string length for the type `NotAnInteger` is a decimal.
 
 ## How to Fix
@@ -33,5 +34,5 @@ type LengthIsSafe : String(9007199254740991);
 type AnInteger : String(42);
 ```
 
-If not feasible, a string representation of the number needs to be used,
-e.g. in annotation values.
+If it's not feasible to use a safe integer, a string representation of the
+number needs to be used, for example, in annotation values.

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).