@sap/cds-dk 9.3.2 → 9.4.2

package/bin/data-products/prepare-csn.js

@@ -0,0 +1,282 @@
+//
+// input: single (interop) CSN for a Data Product, including texts
+//          to be clarified: should/does it already contain a service wrapper?
+//        service name (incl. namespace) for step 5
+// output: single CSN file with ...
+//   1) all type refs resolved to built-in types
+//   2) all type definitions removed
+//   3) unwanted annotations removed, some annotations renamed
+//   4) unused texts removed
+//   5) wrap everything into service if not yet done, service annos added
+//   6) all annotations for entities/elements moved from "definitions" into "extensions"
+//   7) add java name annotations
+//
+// Assumptions on input CSN (reflecting current possibilities of interop CSN):
+// - definitions section only contains
+//   - zero or one service
+//   - entities
+//     - if there is a service, all entities are part of this service
+//     - no views/projections
+//     - no actions/functions
+//     - no parameters
+//   - type definitions
+// - type definitions are only simple (scalar) types referring to built-in types
+//   - no structs, no arrays, no assocs
+//   - can be enum type
+//   - no type chains
+// - entity elements can be
+//   - built-in types, including enum types
+//   - references to the simple (scalar) type definitions described above
+//   - unmanaged(!) associations
+//   - no structs, no arrays
+
+'use strict'
+
+/**
+ *
+ * @param csn
+ * @param srvName
+ * @param ordId
+ */
+exports.prepareCsn = function (csn, srvName, ordId) {
+
+  //
+  // ---------- step 0: check assumptions ---------------------------------------------------------
+  //
+
+  // TODO: check whether all assumptions are met, raise error if not
+
+  //
+  // ---------- step 1: resolve simple types ------------------------------------------------------
+  //
+  // Loop over all entity elements. If type is reference to simple type, replace it by
+  //   corresponding built-in type and copy over the type's properties (unless already present)
+
+  for (let n in csn.definitions) {
+    let entity = csn.definitions[n]
+    if (entity.kind === 'entity' && entity.elements) {
+
+      for (let en in entity.elements) {
+        let element = entity.elements[en]
+
+        if (element.type && !element.type.startsWith('cds.')) {
+          let type = csn.definitions[element.type]
+          // TODO: warn/err if type not found
+          if (type?.kind === 'type') {
+            element.type = type.type
+            // copy props of type if not yet present
+            for (let prop in type) {
+              if (prop !== 'type' && prop !== 'kind' && !element[prop]) {
+                element[prop] = type[prop]
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  //
+  // ---------- step 2: remove simple types ---------------------------------------------------------
+  //
+  // Remove all type definitions.
+
+  for (let n in csn.definitions) {
+    let typedef = csn.definitions[n]
+    if (typedef.kind === 'type') {
+      delete csn.definitions[n]
+    }
+  }
+
+  //
+  // ---------- step 3: remove or rename annotations ------------------------------------------------
+  //
+
+  const annosToRemove = [
+    '__abapOriginalName',
+    '@AccessControl.authorizationCheck',
+    '@AccessControl.personalData',
+    '@Analytics.dataCategory',
+    '@Analytics.dataExtraction',
+    '@Metadata.allowExtensions',
+    '@ObjectModel.sapObjectNodeType.name',
+    '@ObjectModel.usageType',
+    '@VDM.viewType',
+    '@AbapCatalog',
+    '@ObjectModel.upperCase'
+  ]
+  const annotationsToRename = {
+    '@EndUserText.label': '@title'
+  }
+  /**
+   *
+   * @param obj
+   */
+  function removeOrRenameAnnotations(obj) {
+    for (let prop in obj) {
+      // if prop has any entry in annosToRemove as prefix, delete it
+      for (let anno of annosToRemove) {
+        if (prop.startsWith(anno)) {
+          delete obj[prop]
+          break
+        }
+      }
+      // if prop equals any entry in annosToRename, rename it
+      if (annotationsToRename[prop]) {
+        obj[annotationsToRename[prop]] = obj[prop]
+        delete obj[prop]
+      }
+    }
+  }
+
+  for (let n in csn.definitions) {
+    let entity = csn.definitions[n]
+    if (entity.kind === 'entity') {
+      removeOrRenameAnnotations(entity)
+      for (let en in entity.elements || {} ) {
+        removeOrRenameAnnotations(entity.elements[en])
+      }
+    }
+  }
+
+  //
+  // ---------- step 4: remove unused texts ---------------------------------------------------------
+  //
+  // Remove all texts that are no longer used.
+  // Usage example: "@EndUserText.label": "{i18n>I_CUSTOMERCOMPANY@ENDUSERTEXT.LABEL}"
+
+  // first loop over entities and their elements and collect all i18n keys used in annotation values ...
+  let i18nKeys = new Set()
+  /**
+   *
+   * @param obj
+   */
+  function CollectKeys(obj) {
+    for (let prop in obj) {
+      if (prop.startsWith('@') && typeof obj[prop] === 'string' && obj[prop].startsWith('{i18n>')) {
+        let val = obj[prop]
+        i18nKeys.add(val.substring(6, val.length - 1)) // extract text key
+      }
+    }
+  }
+  for (let n in csn.definitions) {
+    let entity = csn.definitions[n]
+    if (entity.kind === 'entity') {
+      CollectKeys(entity)
+      for (let en in entity.elements || {} ) {
+        CollectKeys(entity.elements[en])
+      }
+    }
+  }
+  // ... then remove all texts that are not used
+  for (let lang in csn.i18n) {
+    for (let key in csn.i18n[lang]) {
+      if (!i18nKeys.has(key)) {
+        delete csn.i18n[lang][key]
+      }
+    }
+  }
+
+  //
+  // ---------- step 5: wrap everyting into service if not yet done -------------------------------
+  //
+  // Prefix all entity names with service name. Adapt association targets.
+  // Add CAP specific annotations for DP handling.
+
+  if (srvName) {
+    if (!csn.definitions[srvName] || csn.definitions[srvName].kind !== 'service') {
+      // add the service
+      csn.definitions[srvName] = {kind: 'service'}
+      // loop over all entities and prefix names with service name
+      for (let n in csn.definitions) {
+        let entity = csn.definitions[n]
+        if (entity.kind === 'entity') {
+          // find association elements and rename the targets
+          for (let en in entity.elements || {} ) {
+            let element = entity.elements[en]
+            if (element?.type == 'cds.Association' || element?.type == 'cds.Composition') {
+              element.target = srvName + '.' + element.target
+            }
+          }
+          csn.definitions[srvName + '.' + n] = entity
+          delete csn.definitions[n]
+        }
+      }
+    }
+    // add service annotations
+    Object.assign(csn.definitions[srvName], {
+      '@cds.dp.ordId': ordId,
+      '@cds.external': true,
+      '@data.product': true,
+      '@protocol'    : 'none'  // don't serve via OData
+    })
+  }
+
+  //
+  // ---------- step 6: move entity/element annotations into extensions section -------------------
+  //
+
+  for (let n in csn.definitions) {
+    let entity = csn.definitions[n]
+    if (entity.kind === 'entity') {
+      let annosEntity = { annotate: n }
+      for (let prop in entity) {
+        if (prop.startsWith('@')) {
+          annosEntity[prop] = entity[prop]
+          delete entity[prop]
+        }
+      }
+      for (let en in entity.elements || {} ) {
+        let element = entity.elements[en]
+        let annosElement = {}
+        for (let prop in element) {
+          if (prop.startsWith('@')) {
+            annosElement[prop] = element[prop]
+            delete element[prop]
+          }
+        }
+        if (Object.keys(annosElement).length > 0) {
+          annosEntity.elements ||= {}
+          annosEntity.elements[en] = annosElement
+        }
+      }
+      if (Object.keys(annosEntity).length > 1) {
+        csn.extensions ||= []
+        csn.extensions.push(annosEntity)
+      }
+    }
+  }
+
+  //
+  // ---------- step 7: add Java specific annotations --------------------------------------------
+  //
+  // In S/4 DPs, names of association elements oftentimes begin with `_`, and the respective FK
+  // has the same name w/o `_`, like:
+  // *  Customer : ... // the FK
+  // *  _Customer : Association ...
+  // When generating accessor classes, CAP Java ignores the `_` prefix, which leads to duplicate names.
+  //
+  // If an association-like element's name starts with `_` and there is an element with the same name w/o '_',
+  //   we add an annotation to change the Java name.
+  // This is done after the separation of all other entities into a separate file, so that these
+  //   annotations are visible directly in the entity definition
+  for (let n in csn.definitions) {
+    let entity = csn.definitions[n]
+    if (entity.kind === 'entity') {
+      // find offensive names
+      for (let en in entity.elements || {} ) {
+        let element = entity.elements[en]
+        if (en.startsWith('_') && entity.elements[en.slice(1)] &&
+            element?.type == 'cds.Association' || element?.type == 'cds.Composition') {
+           element['@cds.java.name'] = 'to' + en.slice(1)
+        }
+      }
+    }
+  }
+
+  //
+  // ----------------------------------------------------------------------------------------------
+  //
+
+  return csn
+}

package/bin/data-products/prepare-files.js

@@ -0,0 +1,69 @@
+// input: single prepared CSN for a Data Product
+// output: array with file names and contents, like
+//   [ {path: 'Customer.cds',             src: '...content...'},
+//     {path: 'annotations.cds',          src: '...content...'},
+//     {path: 'index.cds',                src: '...content...'},
+//     {path: '_i18n/i18n_de.properties', src: '...content...'},
+//     ...
+//   ]
+
+'use strict'
+
+const path = require('node:path')
+const { EOL } = require('node:os')
+const { compiler: compile } = require ('../../lib/cds')
+
+/**
+ *
+ * @param csn
+ * @param srvName_short
+ */
+function prepareFiles(csn, srvName_short) {
+  const {definitions, extensions, i18n} = csn
+
+  let files = []
+
+  // main cds file
+  const cdl_main  = compile.to.cdl({definitions: definitions})
+  files.push({
+    path: srvName_short + '.cds',
+    src: cdl_main.model
+  })
+
+  // annotations file
+  if (extensions) {
+    const using = `using from './${srvName_short}';` + EOL + EOL
+    const cdl_annos = compile.to.cdl({extensions: extensions})
+    files.push({
+      path: 'annotations.cds',
+      src: using + cdl_annos.model
+    })
+  }
+
+  // index file
+  const index_text = `using from './${srvName_short}';` + EOL
+                   + (extensions ? ('using from \'./annotations\';' + EOL) : '')
+  files.push({
+    path: 'index.cds',
+    src: index_text
+  })
+
+  // text files
+  for (const langu in i18n) {
+    const i18n_block = i18n[langu]
+    let out = ''
+    for (const key in i18n_block) {
+      let txt = i18n_block[key]
+      txt = txt.replace(/'/g, "\\'")
+      out += key + '=' + txt + EOL
+    }
+    files.push({
+      path: path.join('_i18n', 'i18n_' + langu + '.properties'),
+      src: out
+    })
+  }
+
+  return files
+}
+
+module.exports = prepareFiles

package/bin/export.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+const cds = require ('../lib/cds.js')
+const { regex4 } = require ('./util/cli.js')
+const { Minify } = require ('./minify.js')
+
+class Export extends Minify {
+
+  options = Export.options // for IntelliSense
+  static options = { ...super.options,
+    services: /all/,
+    from: ['*'],
+    to: './apis/*',
+    cleanse: { _excluding: 'keep',
+      '@restrict': true,
+      '@requires': true,
+      '@cds.api.': true,
+      '@UI.': true,
+      includes: true,
+      ignored: true,
+      assocs: true,
+      texts: true,
+      views: true,
+    },
+    reuse: [ '@sap/cds/common' ],
+    force: false,
+    texts: true,
+    data: true,
+    as: 'csn',
+    for: 'npm',
+  }
+  static shortcuts = { ...super.shortcuts,
+    to:'2',
+    for:'4'
+  }
+  static filename = __filename
+
+
+  parseArgs (conf) {
+    if (!process.stdout.isTTY) this.options.to = '-'
+    let [sources,o] = super.parseArgs (conf)
+ // -----------------------------------------------------------------------
+    // Java-specific adjustments -> shall this stay for GA?
+    if (o.for === 'mvn' && !o.to.startsWith('./') && !o.to.startsWith('/'))
+      o.to = './src/main/resources/cds/' + o.to
+    // -----------------------------------------------------------------------
+    if (o.from && o.from != '*') { // variant: cds-export <services> --from <models>
+      if (o.services == '/all/') o.services = regex4 (sources)
+      sources = o.from
+    }
+    return [ this.sources = o.from = sources, this.options = o ]
+  }
+
+
+  async requires (models) {
+    if (models == 'none' || models == '') return {check(){}}
+    const { definitions: defs, $sources } = await cds.load (models, 'parsed')
+    const $map = Object.fromEntries ($sources.map ((s,i) => [ local(s), models[i] ]))
+    return Object.assign (new Set, { check(n) {
+      return n in defs && this.add ($map[defs[n].$location.file])
+    }})
+  }
+
+
+  async cleanse (csn, o = this.options) {
+
+    const reused = await this.requires (o.reuse)
+    const { definitions: defs } = csn = { ...csn, definitions: { ...csn.definitions }}
+    const { cleanse } = o
+
+    // cleanse model...
+    for (const [each,d] of Object.entries (defs)) {
+      if (reused.check(each)) delete defs [each]
+      else if (cleanse.ignored && d['@cds.api.ignore']) delete defs [each]
+      else if (cleanse.texts && each.endsWith('.texts')) delete defs [each]
+      else if (d.kind === 'entity') _cleanse (d, cleanse)
+    }
+    if (reused.size > 0) csn.requires = [...reused]
+
+    // cleanse entities...
+    function _cleanse (d, cleanse) {
+      if (cleanse.managed) {
+        delete d.elements.createdAt
+        delete d.elements.createdBy
+        delete d.elements.modifiedAt
+        delete d.elements.modifiedBy
+      }
+      if (cleanse.users) {
+        delete d.elements.createdBy
+        delete d.elements.modifiedBy
+      }
+      if (cleanse.views) {
+        delete d.projection
+        delete d.query
+      }
+      if (cleanse.texts) {
+        delete d.elements.localized
+        delete d.elements.texts
+      }
+
+      // cleanse elements...
+      for (const [each,e] of Object.entries(d.elements)) {
+        if (cleanse.ignored && e['@cds.api.ignore']) return delete d.elements[each]
+        if (cleanse.texts) delete e.localized
+        if (cleanse.assocs) delete e.keys // cleanse .keys added by cdsc
+      }
+    }
+
+    return super.cleanse (csn,o)
+  }
+
+  async export (minified,o) {
+    if (this.options.to === '-') return super.print (minified)
+    if (this.options.to.endsWith('/*')) this.options.to = this.export_to()
+    console.log(`\n${this.name}ing APIs to`, this.options.to, '...\n')
+    const exports = []; exports.push(...this.export_models (minified))
+    if (o.texts) exports.push (...this.export_texts (minified))
+    if (o.data) exports.push (this.export_data (minified))
+    if (o.for === 'npm') exports.push (this.export_package_json())
+    await Promise.all (exports)
+  }
+
+  export_to() {
+    const to = this.options.to.replace('/*','')
+    const { resolve, basename } = cds.utils.path
+    const { sources } = this
+    if (sources.length === 1 && sources[0].endsWith('.cds'))
+      return resolve (to, this.package_name = basename(sources[0]).slice(0,-4))
+    const defs = this.min.definitions
+    const services = Object.keys(defs).filter (k => defs[k].kind === 'service')
+    if (services.length === 1)
+      return resolve (to, this.package_name = services[0])
+    else throw `\n Can't determine an output folder. \n Please specify one using --to option. \n`
+  }
+
+  async export_package_json (pkg, o = this.options) {
+    await this.write ('// just a tag file for plug & play') .to ('cds-plugin.js', false)
+    if (!o.force && exists (path.join (this.options.to, 'package.json'))) return null
+    if (!pkg) {
+      let { name, version } = await read ('package.json')
+      let requires = Object.fromEntries (Object.entries(this.min.definitions)
+        .filter (([,d]) => d.kind === 'service')
+        .map (([name]) => [ name, true ]))
+      name += '-' + cds.utils.path.basename (this.options.to)
+      pkg = { name, version, cds:{requires} }
+    }
+    return this.write (pkg) .to ('package.json')
+  }
+
+  *export_models (model, o = this.options) {
+    for (let d of Object.values(model.definitions))
+      if (d.kind === 'service') d['@cds.external'] ??= 2
+    yield this.write (
+      `// This file acts as a central facade to exported service definitions.\n`+
+      `// You can modify it to tweak things, without your changes being overridden.\n`+
+      `using from './services';`
+    ) .to ('index.cds', false)
+    if (o.as === 'cdl') {
+      const cdl = cds.compile.to.cdl (model)
+      yield this.write (cdl) .to ('services.cds')
+    } else {
+      const csn = cds.compile.to.json (model)
+      yield this.write (csn) .to ('services.csn')
+    }
+  }
+
+  *export_texts() {
+
+    const common = cds.load.properties (require.resolve('@sap/cds/_i18n/i18n.properties'))
+    const bundles = cds.i18n.labels.all()
+    const defaults = cds.i18n.labels.defaults
+    const serialize = texts => Object.entries(texts).map(([k,v]) => k +'='+ v.replace(/'/g, "''")).join('\n')
+    const write = texts => ({ to: file => this.write(serialize(texts)).to(file) })
+
+    // minify fallback bundle entries
+    const fallback = bundles[''] = {}
+    for (let key in defaults) {
+      if (key in common) continue
+      fallback[key] = defaults[key]
+    }
+    yield write(fallback) .to ('_i18n/i18n.properties')
+
+    // minify other bundles
+    for (let [locale,texts] of Object.entries(bundles)) {
+      const min = bundles[locale] = {}
+      for (let key in texts) {
+        if (key in common) continue
+        if (texts[key] === defaults[key]) continue
+        min[key] = texts[key]
+      }
+      if (Object.keys(min).length > 0) write(min) .to (`_i18n/i18n_${locale}.properties`)
+    }
+  }
+
+  async export_data (model) {
+    const db = cds.db = await cds.deploy ('*',{silent:true})
+    const out = path.resolve (this.options.to, 'data')
+    await fs.promises.rm (out, { recursive: true, force: true })
+    await mkdirp (this.options.to, 'data')
+    for (let each of cds.linked(model).entities) {
+      await _export (db.model.definitions[each.name])
+    }
+    async function _export (e) {
+      if (!e || e['@cds.persistence.skip']) return
+      const file = path.join (out, `${e.name}.csv`)
+      const columns = Object.keys(e.elements).filter(k => !e.elements[k]['@Core.Computed'])
+      const rows = await SELECT.from(e).columns(columns)
+      let csv = fs.createWriteStream (file), i=0
+      for (let r of await rows) {
+        if (i++ === 0) csv.write (Object.keys(r).join(',') +'\n')
+        csv.write (Object.values(r).map(quoted).join(',') +'\n')
+      }
+      csv.end()
+      console.log (DIMMED,' >', local(file), RESET)
+    }
+    function quoted (x) {
+      if (typeof x === 'string') {
+        if (x.startsWith('"') && x.endsWith('"')) return x // already quoted
+        if (x.endsWith(',')) x = x.slice(0, -1) // remove trailing comma
+        if (x.includes(',') || x.includes('\n')) return `"${x.replace(/"/g, '""')}"`
+      }
+      return x
+    }
+  }
+
+  write (x) { return { to: async (filename, force=true) => {
+    if (!x) return; else if (x.then) x = await x
+    const file = path.join (this.options.to, filename)
+    if (!force && !this.options.force && exists(file)) return
+    console.log (DIMMED,' >', local(file), RESET)
+    return write(x).to (file)
+  }}}
+
+  print = undefined // tells the base class to use this.export()
+}
+
+
+const { read, write, exists, mkdirp, local, path, fs } = cds.utils
+const { DIMMED, RESET } = cds.utils.colors
+
+module.exports = Object.assign (Export._for_cds_dk(), { Export })

package/bin/help/export.md

@@ -0,0 +1,37 @@
+
+# SYNOPSIS
+
+   *cds export* [ --services ] <patterns> --from <sources> [ ...options ]
+   *cds export* [ <sources> ] [ ...options ]
+
+# OPTIONS
+
+   *-s | --services* <patterns>
+   *-f | --from* <sources>
+   *-2 | --to* <folder>
+   *-4 | --for* <npm|mvn>
+   *-a | --as* <csn|cdl>
+
+   *-c | --cleanse* <properties>
+   *-k | --keep* <kinds>
+   *-x | --skip* <kinds>
+   *-d | --data*
+   *-t | --texts*
+
+   *-y | --dry*
+   *-i | --inspect*
+   *-f | --force*
+   *-h | --help*
+
+   Run with *--debug* to list all options with their defaults.
+
+# EXAMPLES
+
+   *cds export* ?
+   *cds export* --help
+   *cds export* srv/cat-service.cds --dry
+   *cds export* -s cat*s --dry
+   *cds export* -s cat*s --cleanse @,all | cds -2 cdl
+   *cds export* -s cat*s --inspect=2
+   *cds export* -s cat*s --as cdl
+   *cds export* -s cat*s

package/bin/help/import.md

@@ -0,0 +1,11 @@
+
+# SYNOPSIS
+
+   *cds import* [ --services ] <patterns> --from <sources> [ ...options ]
+   *cds import* [ <sources> ] [ ...options ]
+
+# ANALYSIS
+
+   The *cds import* command is used to import definitions from other sources
+   into the current project. It is the exact inverse to *cds export*, and only
+   used when the sources didn't provide a client package with *cds export*.

package/bin/help/minify.md

@@ -0,0 +1,23 @@
+
+# SYNOPSIS
+
+   *cds minify* <models> [ ...options ]
+
+# OPTIONS
+
+   *-c | --cleanse* <properties>
+   *-k | --keep* <kinds>
+   *-x | --skip* <kinds>
+   *-2 | --to* <folder>
+   *-i | --inspect*
+   *-y | --dry*
+   *-h | --help*
+
+   Run with *--debug* to list all options with their defaults.
+
+# EXAMPLES
+
+   *cds minify* ?
+   *cds minify* -h
+   *cds minify* --debug
+   *cds minify* srv/cat-service.cds -y