@sap/cds-dk 6.8.2 → 7.0.0

package/lib/build/buildTaskHandler.js

@@ -0,0 +1,240 @@
+const path = require('path')
+const fs = require('fs').promises
+const cds = require('../cds')
+
+const { OUTPUT_MODE, OUTPUT_MODE_FILESYSTEM, SEVERITY_INFO, SEVERITY_WARNING, SEVERITY_ERROR, OVERRIDE_METHOD_MSG } = require('./constants')
+const { hasOptionValue, getProperty, relativePaths, copy, BuildMessage } = require('./util')
+
+/**
+ * The build task handler creates the build output for a dedicated build task. It is uniquely identified
+ * by the build task's <code>use</code> property. It represents the fully qualified node module path
+ * of the build task handler implementation.
+ * <p>
+ * The build task engine defines the following protocol. The methods are invoked in descending order:
+ * <ul>
+ *  <li>init() - optional</li>
+ *  <li>get priority() - optional</li>
+ *  <li>async clean()</li>
+ *  <li>async build()</li>
+ * </ul>
+ * The reflected CSN can be accessed using the async method <code>model()</code>.
+ */
+class BuildTaskHandler {
+    /**
+     * @class
+     */
+    constructor() {
+        if (new.target === BuildTaskHandler) {
+            throw new TypeError("Cannot construct BuildTaskHandler instances directly");
+        }
+        this._written = new Set()
+        this._messages = []
+    }
+    static get INFO() {
+        return SEVERITY_INFO
+    }
+    static get WARNING() {
+        return SEVERITY_WARNING
+    }
+    static get ERROR() {
+        return SEVERITY_ERROR
+    }
+    /**
+     * Returns the build context
+     * @returns {object}
+     */
+    get context() {
+        return this._context
+    }
+    /**
+     * Returns the build task executed by this build task handler.
+     * @return {object}
+     */
+    get task() {
+        //injected by framework
+        return this._task
+    }
+
+    /**
+     * Returns the message object to add build task specific messages. Severity 'Info', 'Warning', and 'Error' are supported.
+     * @return {Array}
+     */
+    get messages() {
+        return this._messages
+    }
+
+    /**
+     * Returns the list of files written by this build task handler of current CDS build execution.
+     * @return {Array}
+     */
+    get files() {
+        return [...this._written]
+    }
+
+    /**
+     * Returns the priority of this handler as number, where 0 represents the minimum value and
+     * Number.MAX_SAFE_INTEGER the maximum value.
+     * Positive numbers mean higher and negative numbers lower priority. Build task handlers
+     * with higher priority value are executed before handlers with lower priority.
+     * <br>
+     * Note: Currently not supported for custom build task handlers as they are always executed
+     * before the built-in handlers.
+     * @return {number} the priority for this handler as integer.
+     */
+    get priority() {
+        return 1
+    }
+    /**
+     * Called by the framework immediately after this instance has been created.
+     * The instance has already been fully initialized.
+     */
+    init() { }
+
+    /**
+     * Called by the framework to create the artifacts of this build task handler.
+     */
+    async build() {
+        throw new TypeError(OVERRIDE_METHOD_MSG)
+    }
+
+    /**
+     * Called by the framework immediately before 'build' to delete any output created by this build task handler.
+     * <p>
+     * Note: The <code>BuildTaskEngine</code> is cleaning the common generation target folder if the build is
+     * executed in staging mode, e.g. build.target: "gen".
+     */
+    async clean() {
+        throw new TypeError(OVERRIDE_METHOD_MSG)
+    }
+
+    /**
+     * Asynchronously write the given content to a given file path.
+     * If the file exists the content is replaced. If the file does not exist, a new file will be created.
+     * The file name is stored in the list of files written by this build task handler.
+     * @param {string} dest - absolute or relative file path. Relative paths will be resolved to this task's destination path.
+     * @param {any} data - If data is of type object the JSON-stringified version is written.
+     */
+    write(data) {
+        return {
+            to: async (dest) => {
+                if (this._hasBuildOption(OUTPUT_MODE, OUTPUT_MODE_FILESYSTEM)) {
+                    if (!path.isAbsolute(dest)) {
+                        // relative to build task's destination path
+                        dest = path.resolve(this.task.dest, dest)
+                    }
+                    this.pushFile(dest)
+                    await fs.mkdir(path.dirname(dest), { recursive: true })
+                    await fs.writeFile(dest, typeof data === "object" && !Buffer.isBuffer(data) ? JSON.stringify(data, null, 2) : data)
+                }
+            }
+        }
+    }
+
+    // TODO only works with files due to fs.copyFile, check usages
+    /**
+     * Copy a file or directory if the build task option 'outputMode' does not have the value 'resultOnly'.
+     * The directory can have contents.
+     * <p>
+     * Note: The file name is stored in the list of files written by this build task handler.
+     * </p>
+     * @param {string} src The absolute or relative source path of the file or directory to copy.
+     * Relative paths will be resolved to this task's source path.
+     * @param {string} dest The absolute or relative target path. Relative paths will be resolved to this task's destination path.
+     *
+     */
+    copy(src) {
+        return {
+            to: async (dest) => {
+                if (this._hasBuildOption(OUTPUT_MODE, OUTPUT_MODE_FILESYSTEM)) {
+                    if (!path.isAbsolute(src)) {
+                        // relative to build task's source path
+                        src = path.resolve(this.task.src, src)
+                    }
+                    if (!path.isAbsolute(dest)) {
+                        // relative to build task's destination path
+                        dest = path.resolve(this.task.dest, dest)
+                    }
+                    this.pushFile(dest)
+                    if (fs.cp) { // Node.js >= 16.7
+                        return fs.cp(src, dest, { recursive: true })
+                    }
+                    return copy(src, dest)
+                }
+                return dest
+            }
+        }
+    }
+
+    /**
+     * Adds the given user message and severity to the list of messages issued by this build task.
+     * <p>
+     * User messages will be logged after CDS build has been finished based on the log-level that has been set.
+     * By default messages with severity <em>warning</em> and <em>error</em> will be logged.
+     * @param {string} message the message text
+     * @param {string} severity the severity of the message
+     */
+    pushMessage(message, severity) {
+        this.messages.push(new BuildMessage(message, severity))
+    }
+
+    /**
+     * Returns the reflected CSN model using this build task's model settings.
+     * @return {object} the reflected CSN
+     */
+    async model() {
+        const files = this._resolveModel()
+        if (!files || files.length === 0) {
+            this._logger.log(`no CDS model found for [${this.task.for}] build task [${this.task.src}] - nothing to be done`)
+            return null
+        }
+        this._logger._debug && this._logger.debug(`model: ${relativePaths(cds.root, files).join(", ")}`)
+        // $location paths are relative to current working dir by default - make sure a given project root folder is taken
+        const options = { ...this.options(), cwd: cds.root }
+
+        const model = await cds.load(files, options)
+        if (!model) {
+            return null
+        }
+        return model
+    }
+
+    options() {
+        return { messages: this._messages }
+    }
+
+    /**
+     * Adds the given fully qualified file path to the list of files that are written by this build task.
+     * @param {string} filePath
+     */
+    pushFile(filePath) {
+        this._written.add(filePath)
+    }
+    /**
+     * Returns a list of CDS model files defining the transitive closure of the CDS model based on the model options
+     * defined for this build task.
+     */
+    _resolveModel() {
+        const modelPaths = Array.isArray(this.task.options.model) && this.task.options.model.length > 0 ? this.task.options.model : !Array.isArray(this.task.options.model) && this.task.options.model || this.task.src
+        return cds.resolve(modelPaths)
+    }
+    /** Determines whether the given build option value has been set for this build task.
+      * If the value is omitted, the existence of the given property name is checked.
+      */
+    _hasBuildOption(qualifiedName, value) {
+        return hasOptionValue(this._getBuildOption(qualifiedName), value)
+    }
+
+    // Returns the value of the given build option defined for this build task.
+    _getBuildOption(qualifiedName) {
+        // build task options overwriting other settings
+        let value = getProperty(this.task.options, qualifiedName)
+        if (value !== undefined) {
+            return value
+        }
+        value = getProperty(this.context.options, qualifiedName)
+        if (value !== undefined) {
+            return value
+        }
+    }
+}
+module.exports = BuildTaskHandler

package/lib/build/buildTaskProvider.js

@@ -0,0 +1,22 @@
+/* eslint-disable no-unused-vars */
+module.exports = class BuildTaskProvider {
+    constructor() {
+        //injected by framework
+        this._plugin = null
+    }
+    canHandleTask(task) {
+        // return this._plugin.provides.includes(task.for || task.use && this._getTaskId(task.use))
+    }
+    loadHandler(task) {
+        // return module.require(`${this._plugin.path}/${task.for || this._getTaskId(task.use)}`)
+    }
+    async lookupTasks(tasks) { }
+    async applyTaskDefaults(task) {
+        // task.for = task.for || this._getTaskId(task.use)
+    }
+    _getTaskId(use) {
+        if (this._plugin && this._plugin.id) {
+            return use.substring(this._plugin.id.length + 1)
+        }
+    }
+}

package/lib/build/buildTaskProviderFactory.js

@@ -0,0 +1,182 @@
+const fs = require('fs')
+const path = require('path')
+const cds = require('../cds')
+const { LOG_MODULE_NAMES, OUTPUT_MODE_FILESYSTEM } = require("./constants")
+const BuildTaskProviderInternal = require('./provider/buildTaskProviderInternal')
+const BuildTaskProvider = require('./buildTaskProvider')
+
+class BuildTaskProviderFactory {
+    constructor(options = {}) {
+        options.logger = options.logger || cds.log(LOG_MODULE_NAMES)
+        options.outputMode = options.outputMode || OUTPUT_MODE_FILESYSTEM
+        if (options.clean === undefined) {
+            options.clean = true
+        }
+        this._buildOptions = options
+        this._context = { options }
+    }
+    get logger() {
+        return this.buildOptions.logger
+    }
+    get buildOptions() {
+        return this._context.options
+    }
+    get context() {
+        return this._context
+    }
+    get providers() {
+        if (!this._providers) {
+            this._providers = this._loadProviders()
+        }
+        return this._providers
+    }
+
+    async applyTaskDefaults(tasks) {
+        return Promise.all(tasks.map(async task => {
+            if (!task.for && !task.use) {
+                throw new Error("Invalid build task definition - property 'for' and property 'use' missing")
+            }
+            const provider = this.providers.find(provider => {
+                try {
+                    return provider.canHandleTask(task)
+                } catch (e) {
+                    this.logger.error(`Build task provider ${provider.constructor.name} returned error:\n` + e)
+                    throw e
+                }
+            })
+            if (!provider) {
+                throw new Error(`No provider found for build task '${task.for || task.use}'`)
+            }
+            if (provider instanceof DefaultBuildTaskProvider) {
+                this.logger._debug && this.logger.debug(`No provider found for build task '${task.use}', using default provider`)
+            }
+            return this._applyTaskDefaults(provider, [task])
+        }))
+    }
+
+    async lookupTasks(tasks = []) {
+        for (let i = 0; i < this.providers.length; i++) {
+            const provider = this.providers[i]
+            const existingTasks = [...tasks]
+            await this._lookupTasks(provider, tasks)
+            if (existingTasks.length < tasks.length) {
+                // apply defaults
+                const newTasks = tasks.filter(task => !existingTasks.includes(task))
+                await this._applyTaskDefaults(provider, newTasks)
+                this.logger._debug && this.logger.debug(`Build task provider ${provider.constructor.name} returned build tasks ${JSON.stringify(newTasks)}`)
+            }
+        }
+        return tasks
+    }
+
+    /**
+     * Create a BuildTaskHandler instance for the given build task.
+     * The implementation is loaded based on the build task's 'for' or 'use' option.
+     * @param {*} task
+     */
+    createHandler(task) {
+        const BuildTaskHandlerClass = this.loadHandler(task)
+        const resolvedTask = this.resolveTask(task)
+        this.logger._debug && this.logger.debug(`loaded build task handler [${resolvedTask.use}]`)
+
+        const handler = new BuildTaskHandlerClass()
+        handler._task = resolvedTask
+        handler._logger = this.logger
+        handler._context = this.context
+        this.logger._debug && this.logger.debug(`created BuildTaskHandler [${resolvedTask.use}]`)
+        return handler
+    }
+
+    /**
+     * Loads the build task handler implementation for the given build task.
+     * 'for' defines an alias for built-in handlers like 'hana', 'java', 'node', 'fiori' or 'mtx'.
+     * 'use' defines the fully qualified module name of external build task handler implemenations.
+     * @param {object} task
+     */
+    loadHandler(task) {
+        let provider = this.providers.find(provider => provider.canHandleTask(task))
+        if (!provider) {
+            throw new Error(`No provider found for build task '${task.for || task.use}'`)
+        }
+        try {
+            return provider.loadHandler(task)
+        }
+        catch (e) {
+            this.logger.error(`Provider failed to load handler class - provider: ${provider.constructor.name}, task: ${task.for || task.use} :\n` + e)
+            throw e
+        }
+    }
+
+    resolveTasks(tasks) {
+        return tasks.map(task => this.resolveTask(task))
+    }
+
+    /**
+     * Resolves the given build task based on the project root folder.<br>
+     * The task is validated in order to ensure that 'src' refers to a valid folder and 'for' or 'use' reference can be required.
+     * @param {*} task
+     */
+    resolveTask(task) {
+        // first validate handler implementation
+        this.loadHandler(task)
+
+        // second validate src path
+        const resolvedTask = JSON.parse(JSON.stringify(task))
+
+        // Do not store resolved symlinks as this is causing issues on Windows, e.g. if git projects are
+        // located under 'C:\SAPDevelop\git\...' using a sym-link from '%USERHOME%\git' to 'C:\SAPDevelop\git'.
+        // see cap/issues/#8694
+        resolvedTask.src = path.resolve(cds.root, task.src)
+        try {
+            //validate source path
+            fs.realpathSync(resolvedTask.src)
+        } catch (e) {
+            throw new Error(`Build task [${resolvedTask.for || resolvedTask.use}] could not be resolved - folder src [${path.resolve(cds.root, task.src)}] does not exist`)
+        }
+        resolvedTask.dest = path.resolve(cds.root, cds.env.build.target, task.dest || task.src)
+        resolvedTask.options = task.options || {}
+        return resolvedTask
+    }
+
+    async _lookupTasks(provider, tasks) {
+        return provider.lookupTasks(tasks)
+    }
+
+    async _applyTaskDefaults(provider, tasks) {
+        return Promise.all(tasks.map(task => provider.applyTaskDefaults(task)))
+    }
+
+    _loadProviders() {
+        // order is important - the DefaultBuildTaskProvider has to be the last provider in the list
+        return [this._createProvider(BuildTaskProviderInternal), this._createProvider(DefaultBuildTaskProvider)]
+    }
+
+    _createProvider(clazz, plugin) {
+        const provider = new clazz()
+        provider._logger = this.logger
+        provider._plugin = plugin
+        return provider
+    }
+}
+
+/**
+ * Default provider implementation handling fully qualified custom build task declarations.
+ * Has to be the last entry in the providers list.
+ */
+class DefaultBuildTaskProvider extends BuildTaskProvider {
+    canHandleTask(task) {
+        return !!task.use
+    }
+    loadHandler(task) {
+        if (!task.use) {
+            throw new Error(`Invalid build task definition [${task.for}] - property 'use' missing`)
+        }
+        try {
+            return require(require.resolve(task.use, { paths: [cds.root] }))
+        }
+        catch (e) {
+            throw new Error(`Build task could not be resolved - module [${task.use}] cannot be loaded:\n` + e)
+        }
+    }
+}
+module.exports = BuildTaskProviderFactory

package/lib/build/constants.js

@@ -0,0 +1,56 @@
+exports.OUTPUT_MODE = "outputMode"
+exports.OUTPUT_MODE_NONE = 0x0
+exports.OUTPUT_MODE_FILESYSTEM = 0x1
+exports.OUTPUT_MODE_RESULT = 0x2
+
+exports.BUILD_TASK_NPM_SCOPE = "@sap"
+exports.BUILD_TASK_PREFIX = exports.BUILD_TASK_NPM_SCOPE + "/cds/build"
+exports.BUILD_TASK_JAVA = "java"
+exports.BUILD_TASK_JAVA_CF = "java-cf"
+exports.BUILD_TASK_NODEJS = "nodejs"
+exports.BUILD_TASK_NODE_CF = "node-cf"
+exports.BUILD_TASK_HANA = "hana"
+exports.BUILD_TASK_FIORI = "fiori"
+exports.BUILD_TASK_MTX = "mtx"
+exports.BUILD_TASK_MTX_SIDECAR = "mtx-sidecar"
+exports.BUILD_TASK_MTX_EXTENSION = "mtx-extension"
+exports.BUILD_TASKS = [this.BUILD_TASK_JAVA, this.BUILD_TASK_JAVA_CF, this.BUILD_TASK_NODEJS, this.BUILD_TASK_NODE_CF, this.BUILD_TASK_HANA, this.BUILD_TASK_FIORI, this.BUILD_TASK_MTX, this.BUILD_TASK_MTX_SIDECAR, this.BUILD_TASK_MTX_EXTENSION]
+
+exports.ODATA_VERSION_V2 = "v2"
+exports.ODATA_VERSION_V4 = "v4"
+
+exports.CONTENT_LANGUAGE_BUNDLES = "contentLanguageBundles" // create i18n.json language bundles
+exports.CONTENT_DEFAULT_CSN = "contentDefaultCsn"           // create default CSN format flavor: "inferred"
+exports.CONTENT_EDMX = "contentEdmx"                        // create EDMX for required languages
+exports.CONTENT_PACKAGE_JSON = "contentPackageJson"         // create package.json file if not existing, or modify existing package.json
+exports.CONTENT_PACKAGELOCK_JSON = "contentPackageLockJson" // copy package-lock.json file if existing into deployment folder
+exports.CONTENT_HDBTABLEDATA = "contentHdbtabledata"        // create .hdbtabledata files for .csv files if not existing
+exports.CONTENT_NPMRC = "contentNpmrc"                      // copy .npmrc file if existing into deployment folder
+exports.CONTENT_CDSRC_JSON = "contentCdsrcJson"             // copy .cdsrc.json file if existing into deployment folder
+exports.CONTENT_NODE_MODULES = "contentNodeModules"         // copy node_modules folder if existing into deployment folder
+exports.CONTENT_ENV = "contentEnv"                          // copy .env file if existing into deployment folder
+exports.CONTENT_DEFAULT_ENV_JSON = "contentDefaultEnvJson"  // copy default-env.json file if existing into deployment folder
+exports.CSV_FILE_DETECTION = "csvFileDetection"             // detect CSV files based on CDS model location
+exports.EXTENSION_POINT_VALIDATION = "extensionPointValidation" // validate extension point restrictions defined by the extended SaaS app
+exports.DEFAULT_BUILT_IN_MODELS = "defaultBuiltInModels"    // add @sap/cds* built-in models to build tasks
+
+exports.FOLDER_GEN = "gen"
+exports.FILE_EXT_CDS = ".cds"
+exports.MTX_SIDECAR_FOLDER = "mtx/sidecar"                  // default name of the mtx sidecar folder
+exports.DEFAULT_CSN_FILE_NAME = "csn.json"
+// REVISIT: the models are not required if a custom server.js file is used for MTX bootstrap
+exports.NODEJS_MODEL_EXCLUDE_LIST = ['@sap/cds/srv/mtx', '@sap/cds-mtxs/srv/bootstrap']
+
+exports.CDS_CONFIG_PATH_SEP = "/"
+exports.SEVERITY_ERROR = "Error"
+exports.SEVERITY_WARNING = "Warning"
+exports.SEVERITY_INFO = "Info"
+exports.SEVERITY_DEBUG = "Debug"
+exports.SEVERITIES = [exports.SEVERITY_ERROR, exports.SEVERITY_WARNING, exports.SEVERITY_INFO, exports.SEVERITY_DEBUG]
+exports.LOG_LEVEL_ERROR = "error"
+exports.LOG_LEVEL_WARN = "warn"
+exports.LOG_LEVEL_INFO = "info"
+exports.LOG_LEVEL_DEBUG = "debug"
+exports.LOG_LEVELS = [exports.LOG_LEVEL_ERROR, exports.LOG_LEVEL_WARN, exports.LOG_LEVEL_INFO, exports.LOG_LEVEL_DEBUG]
+exports.LOG_MODULE_NAMES = "cds|build"
+exports.OVERRIDE_METHOD_MSG = "Must override method"

package/lib/build/index.js

@@ -0,0 +1,21 @@
+const fs = require('fs')
+const cds = require('../cds')
+const BuildTaskEngine = require('./buildTaskEngine')
+const BuildTaskFactory = require('./buildTaskFactory')
+const BuildTaskHandler = require('./buildTaskHandler')
+const { BuildError } = require('./util')
+
+module.exports = { build, BuildTaskFactory, BuildTaskEngine, BuildTaskHandler, BuildError }
+
+/**
+ * Executes cds build in the directory defined by cds.root.
+ *
+ * @param {object} options - command options as defined by build command.
+ */
+async function build(options = {}) {
+    if (!fs.existsSync(cds.root) || !fs.lstatSync(cds.root).isDirectory()) {
+        const { CliError } = require('../client/helper/errors')
+        throw new CliError(`Project folder '${cds.root}' does not exist`)
+    }
+    return await new BuildTaskEngine(options).processTasks()
+}

package/lib/build/provider/buildTaskHandlerEdmx.js

@@ -0,0 +1,83 @@
+const path = require('path')
+const cds = require('../../cds')
+const BuildTaskHandlerFeatureToggles = require('./buildTaskHandlerFeatureToggles')
+const { OUTPUT_MODE, OUTPUT_MODE_RESULT } = require('../constants')
+
+class BuildTaskHandlerEdmx extends BuildTaskHandlerFeatureToggles {
+    async compileToEdmx(model, edmxDest, compileOptions = {}) { // NOSONAR
+        const promises = []
+
+        // generate edmx for services only that have the odata protocol
+        const serviceNames = cds.reflect(model).services
+            .filter(service => this._isOdataProtocol(service))
+            .map(service => service.name)
+
+        // new compile impl is throwing error in case no services exist!
+        if (serviceNames.length > 0) {
+            const options = {
+                ...this._options4edmx(),
+                ...compileOptions,
+                serviceNames
+            }
+            this.logger._debug && this.logger.debug(`compiling edmx files using OData version ${options.version}`)
+
+            const result = cds.compile.to.edmx(model, options)
+
+            if (result) {
+                let langs = this.task.options.lang || cds.env.i18n.languages
+                if (langs.split) { // string to array
+                    langs = langs.split(',')
+                }
+                if (langs.length > 0 && langs[0] !== 'all' && langs.indexOf('') < 0) {
+                    langs.push('')  // make sure fallback language is in, runtimes expect it
+                }
+                for (let [content, key] of result) {
+                    const serviceName = key.file ? key.file : key.name
+                    if (this.hasBuildOption(OUTPUT_MODE, OUTPUT_MODE_RESULT)) {
+                        this._result.services.add(serviceName)
+                    }
+                    const locResult = cds.localize(model, langs, content)
+                    if (locResult[Symbol.iterator]) { // multi result
+                        for (let [localizedContent, { lang }] of locResult) {
+                            promises.push(this._writeEdmxForLang(localizedContent, serviceName, lang, edmxDest))
+                        }
+                    } else { // single result
+                        promises.push(this._writeEdmxForLang(locResult, serviceName, langs[0], edmxDest))
+                    }
+                }
+            }
+        }
+        return Promise.all(promises)
+    }
+
+    _isOdataProtocol(srv) {
+        return cds.service.protocols.protocol4(srv).startsWith('odata')
+    }
+
+    _options4odata() {
+        const o = this.options()
+        o.version = cds.env.odata.version
+        return o
+    }
+
+    _options4edmx() {
+        const o = this._options4odata()
+        o.service = 'all'
+        return o
+    }
+
+    _writeEdmxForLang(content, serviceName, lang, edmxDest) {
+        const fileName = serviceName + (lang ? '_' + lang + '.xml' : '.xml')
+        if (this.hasBuildOption(OUTPUT_MODE, OUTPUT_MODE_RESULT)) {
+            this._result.languages.add(lang)
+            this._result.edmx.set(fileName, content)
+        }
+
+        //edmxDest might be null
+        if (edmxDest) {
+            return this.write(content).to(path.join(edmxDest, fileName))
+        }
+        return Promise.resolve()
+    }
+}
+module.exports = BuildTaskHandlerEdmx