@sap/cds-dk 7.2.0 → 7.3.0

package/lib/build/buildTaskEngine.js

@@ -5,7 +5,7 @@ const { sortMessagesSeverityAware, deduplicateMessages, CompilationError } = cds
 const { relativePaths, BuildError, resolveRequiredSapModels } = require('./util')
 const { SEVERITIES, LOG_LEVELS } = require('./constants')
 const BuildTaskFactory = require('./buildTaskFactory')
-const BuildTaskHandlerInternal = require('./provider/buildTaskHandlerInternal')
+const InternalBuildPlugin = require('./provider/internalBuildPlugin')
 
 const COMPILATION_ERROR = 'CompilationError'
 const COMPILE_MESSAGE = 'CompileMessage'
@@ -40,66 +40,66 @@ class BuildTaskEngine {
             throw new BuildError(`Required CDS models [${unresolved.join(', ')}] cannot be resolved. Make sure up-to-date versions of the missing modules are installed.`)
         }
 
-        // create build task handlers
-        const handlers = []
+        // create build plugins
+        const plugins = []
         tasks.forEach((task) => {
             if (task) {
-                const handler = this._createHandler(task)
-                handlers.push(handler)
+                const plugin = this._createPlugin(task)
+                plugins.push(plugin)
             }
         })
 
         try {
-            await this._executePrepare(handlers)
-            await this._executeCleanBuildTasks(handlers)
+            await this._executePrepare(plugins)
+            await this._executeCleanBuildTasks(plugins)
 
             // throwing Exception in case of compilation errors
-            const buildResult = await this._executeBuildTasks(handlers)
+            const buildResult = await this._executeBuildTasks(plugins)
 
-            await this._writeGenerationLog(handlers)
-            this._logBuildOutput(handlers)
-            this._logMessages(BuildTaskEngine._getHandlerMessages(handlers))
+            await this._writeGenerationLog(plugins)
+            this._logOutput(plugins)
+            this._logMessages(BuildTaskEngine._getMessages(plugins))
             this._logTimer(startTime, Date.now())
 
             return buildResult
         } catch (error) {
-            this._logBuildOutput(handlers)
+            this._logOutput(plugins)
             throw error
         }
     }
 
     /**
-     * BuildTaskHandler#prepare has been deprecated and was never part of the public API.
-     * Currently only used by internal FioriBuildTaskHandler.
+     * BuildPlugin#prepare has been deprecated and was never part of the public API.
+     * Currently only used by internal FioriBuildPlugin.
      * @deprecated
-     * @param {*} handlers
+     * @param {*} plugins
      * @returns
      */
-    async _executePrepare(handlers) {
-        const handlerGroups = new Map()
+    async _executePrepare(plugins) {
+        const pluginGroups = new Map()
 
-        // group handlers by type
-        handlers.forEach(handler => {
-            handlerGroups.has(handler.task.for) ? handlerGroups.get(handler.task.for).push(handler) : handlerGroups.set(handler.task.for, [handler])
+        // group plugins by type
+        plugins.forEach(plugin => {
+            pluginGroups.has(plugin.task.for) ? pluginGroups.get(plugin.task.for).push(plugin) : pluginGroups.set(plugin.task.for, [plugin])
         })
 
         const promises = []
-        for (let handlerGroup of handlerGroups.values()) {
-            promises.push(this._doPrepare(handlerGroup))
+        for (let pluginGroup of pluginGroups.values()) {
+            promises.push(this._doPrepare(pluginGroup))
         }
         return Promise.all(promises)
     }
 
     /**
      * @deprecated
-     * @param {*} handlerGroup
+     * @param {*} pluginGroup
      */
-    async _doPrepare(handlerGroup) {
-        for (let handler of handlerGroup) {
+    async _doPrepare(pluginGroup) {
+        for (let plugin of pluginGroup) {
             // prepare has been deprecated
-            if (handler instanceof BuildTaskHandlerInternal) {
-                this.logger._debug && this.logger.debug(`preparing, handler [${handler.constructor.name}], src [${relativePaths(cds.root, handler.task.src)}]`)
-                const result = await handler.prepare()
+            if (plugin instanceof InternalBuildPlugin) {
+                this.logger._debug && this.logger.debug(`preparing, plugin [${plugin.constructor.name}], src [${relativePaths(cds.root, plugin.task.src)}]`)
+                const result = await plugin.prepare()
                 if (result === false) {
                     break
                 }
@@ -107,7 +107,7 @@ class BuildTaskEngine {
         }
     }
 
-    async _executeCleanBuildTasks(handlers) {
+    async _executeCleanBuildTasks(plugins) {
         if (this.options.clean) {
             // clean entire build staging folder once
             if (cds.env.build.target !== '.') {
@@ -116,30 +116,30 @@ class BuildTaskEngine {
                 await fs.promises.rm(target, { force: true, recursive: true })
             }
 
-            const results = await Promise.allSettled(handlers.map((handler) => {
-                this.logger._debug && this.logger.debug(`cleaning, handler [${handler.constructor.name}], src [${relativePaths(cds.root, handler.task.src)}]`)
-                return handler.clean()
+            const results = await Promise.allSettled(plugins.map((plugin) => {
+                this.logger._debug && this.logger.debug(`cleaning, plugin [${plugin.constructor.name}], src [${relativePaths(cds.root, plugin.task.src)}]`)
+                return plugin.clean()
             }))
             // check for errors and throw exception
             this._resolveHandlerResponse(results)
         }
     }
 
-    async _executeBuildTasks(handlers) {
-        // sort handlers based on priority in
-        handlers = handlers.sort((a, b) => {
+    async _executeBuildTasks(plugins) {
+        // sort plugins based on priority in
+        plugins = plugins.sort((a, b) => {
             return a.priority === b.priority ? 0 : a.priority > b.priority ? -1 : 1
         })
-        // group handlers with same priority in order to execute in parallel
-        const buildPipeline = handlers.reduce((acc, handler) => {
+        // group plugins with same priority in order to execute in parallel
+        const buildPipeline = plugins.reduce((acc, plugin) => {
             if (acc.length === 0) {
-                acc.push([handler])
+                acc.push([plugin])
             } else {
                 const currGroup = acc[acc.length - 1]
-                if (currGroup[0].priority === handler.priority) {
-                    currGroup.push(handler)
+                if (currGroup[0].priority === plugin.priority) {
+                    currGroup.push(plugin)
                 } else {
-                    acc.push([handler])
+                    acc.push([plugin])
                 }
             }
             return acc
@@ -148,20 +148,20 @@ class BuildTaskEngine {
         const results = await this._executePipeline(buildPipeline)
 
         // check for errors and throw exception - return results otherwise including any compiler and build status messages
-        return this._resolveHandlerResponse(results, BuildTaskEngine._getHandlerMessages(handlers))
+        return this._resolveHandlerResponse(results, BuildTaskEngine._getMessages(plugins))
     }
 
     async _executePipeline(pipeline) {
         let allResults = []
         for (const group of pipeline) {
-            const results = await Promise.allSettled(group.map((handler) => {
-                this.logger._debug && this.logger.debug(`building, handler [${handler.constructor.name}], src [${relativePaths(cds.root, handler.task.src)}]`)
-                return handler.build()
-                    .then(handlerResult => {
+            const results = await Promise.allSettled(group.map((plugin) => {
+                this.logger._debug && this.logger.debug(`building, plugin [${plugin.constructor.name}], src [${relativePaths(cds.root, plugin.task.src)}]`)
+                return plugin.build()
+                    .then(pluginResult => {
                         return Promise.resolve({
-                            task: handler.task,
-                            result: handlerResult,
-                            messages: this._sortMessagesUnique(handler.messages)
+                            task: plugin.task,
+                            result: pluginResult,
+                            messages: this._sortMessagesUnique(plugin.messages)
                         })
                     })
             }))
@@ -170,7 +170,7 @@ class BuildTaskEngine {
         return allResults
     }
 
-    _resolveHandlerResponse(results, handlerMessages = []) {
+    _resolveHandlerResponse(results, pluginMessages = []) {
         const errors = []
         const resolvedResults = results.reduce((acc, r) => {
             if (r.status === 'fulfilled') {
@@ -192,9 +192,9 @@ class BuildTaskEngine {
 
             // propagate existing CompilationErrors
             // merge all existing compilation messages into a single CompilationError
-            // compiler warning and info messages are returned as handler messages
+            // compiler warning and info messages are returned as plugin messages
             const compileErrors = errors.filter(e => e.constructor.name === COMPILATION_ERROR)
-            const compileMessages = handlerMessages.filter(message => message.constructor.name === COMPILE_MESSAGE)
+            const compileMessages = pluginMessages.filter(message => message.constructor.name === COMPILE_MESSAGE)
             if (compileErrors.length) {
                 throw new CompilationError(this._sortMessagesUnique(BuildTaskEngine._getErrorMessages(compileErrors), compileMessages))
             }
@@ -202,31 +202,31 @@ class BuildTaskEngine {
         return resolvedResults
     }
 
-    _createHandler(task) {
-        const handler = this.taskFactory.createHandler(task)
-        handler.init()
+    _createPlugin(task) {
+        const plugin = this.taskFactory.createPlugin(task)
+        plugin.init()
 
-        if (!(handler instanceof BuildTaskHandlerInternal) && handler.priority !== 1) {
-            // Custom build handlers are executed before internal handlers to ensure
+        if (!(plugin instanceof InternalBuildPlugin) && plugin.priority !== 1) {
+            // Custom build plugins are executed before internal plugins to ensure
             // that generated content cannot be overwritten by mistake
-            throw new Error(`Illegal priority for ${handler.constructor.name} encountered for custom handler - in this version only priority value '1' is allowed`)
+            throw new Error(`Illegal priority for ${plugin.constructor.name} encountered for custom plugin - in this version only priority value '1' is allowed`)
         }
-        this._logTaskHandler(handler)
-        return handler
+        this._logTaskHandler(plugin)
+        return plugin
     }
 
-    _logBuildOutput(handlers) {
+    _logOutput(plugins) {
         // log all generated files
-        const files = BuildTaskEngine._getBuildOutput(handlers)
+        const files = BuildTaskEngine._getOutput(plugins)
         if (files.length > 0) {
             this.logger.log(`done > wrote output to:\n   ${files.join("\n   ")}\n`)
         }
     }
 
-    async _writeGenerationLog(handlers) {
+    async _writeGenerationLog(plugins) {
         const outputFile = cds.env.build.outputfile || process.env.GENERATION_LOG
         if (outputFile) {
-            const files = BuildTaskEngine._getBuildOutput(handlers)
+            const files = BuildTaskEngine._getOutput(plugins)
             this.logger.log(`writing generation log to [${outputFile}]\n`)
             try {
                 await fs.promises.mkdir(path.dirname(outputFile), { recursive: true })
@@ -238,8 +238,8 @@ class BuildTaskEngine {
         }
     }
 
-    static _getBuildOutput(handlers) {
-        const files = handlers.reduce((acc, handler) => acc.concat(handler.files), []).sort()
+    static _getOutput(plugins) {
+        const files = plugins.reduce((acc, plugin) => acc.concat(plugin.files), []).sort()
         return files.map(file => {
             if (path.isAbsolute(cds.env.build.target)) {
                 return file
@@ -252,9 +252,9 @@ class BuildTaskEngine {
         this.logger.log(`build completed in ${end - start} ms\n`)
     }
 
-    _logTaskHandler(handler) {
-        this.logger._debug && this.logger.debug(`handler ${handler.constructor.name}`)
-        this.logger._debug && this.logger.debug(`details src [${relativePaths(cds.root, handler.task.src)}], dest [${relativePaths(cds.root, handler.task.dest)}], use [${handler.task.use}], options [${JSON.stringify(handler.task.options)}]`) //NOSONAR
+    _logTaskHandler(plugin) {
+        this.logger._debug && this.logger.debug(`plugin ${plugin.constructor.name}`)
+        this.logger._debug && this.logger.debug(`details src [${relativePaths(cds.root, plugin.task.src)}], dest [${relativePaths(cds.root, plugin.task.dest)}], use [${plugin.task.use}], options [${JSON.stringify(plugin.task.options)}]`) //NOSONAR
     }
 
     _logMessages(messages) {
@@ -303,11 +303,11 @@ class BuildTaskEngine {
     }
 
     /**
-     * Returns compiler messages and validation messages issued by handlers.
-     * @param {Array<BuildTaskHandler>} handlers
+     * Returns compiler messages and validation messages issued by plugins.
+     * @param {Array<BuildPlugin>} plugins
      */
-    static _getHandlerMessages(handlers) {
-        return handlers.reduce((acc, handler) => acc.concat(handler.messages), [])
+    static _getMessages(plugins) {
+        return plugins.reduce((acc, plugin) => acc.concat(plugin.messages), [])
     }
 
     /**

package/lib/build/buildTaskFactory.js

@@ -47,8 +47,8 @@ class BuildTaskFactory {
         return tasks
     }
 
-    createHandler(task) {
-        return this.providerFactory.createHandler(task)
+    createPlugin(task) {
+        return this.providerFactory.createPlugin(task)
     }
 
     async _createTasks() {
@@ -65,7 +65,7 @@ class BuildTaskFactory {
             // 1. apply default values including task.for and task.use and ensure that for all tasks a provider exists - throwing error otherwise
             await this.providerFactory.applyTaskDefaults(tasks)
             // ensure that dependencies get wired up before filtering
-            await this.providerFactory.lookupTasks(tasks)
+            await this.providerFactory.lookupTasks(tasks, true)
         }
 
         // 3. filters the list of build tasks and adapts according to given CLI options
@@ -83,7 +83,7 @@ class BuildTaskFactory {
 
         // 2. add dependencies
         existingTasks = [...tasks]
-        await this.providerFactory.lookupTasks(tasks)
+        await this.providerFactory.lookupTasks(tasks, true)
         if (tasks.length > existingTasks.length) {
             const newTasks = tasks.filter(task => !existingTasks.includes(task))
             // a dependant task was added
@@ -93,9 +93,6 @@ class BuildTaskFactory {
         // obligatory task defaults shared by all tasks
         BuildTaskFactory._applyCommonTaskDefaults(tasks)
 
-        // ensure correct values for optional build task properties, error for missing mandatory properties
-        BuildTaskFactory._validateBuildTasks(tasks)
-
         this._setDefaultBuildTargetFolder(tasks)
         return tasks
     }
@@ -115,14 +112,6 @@ class BuildTaskFactory {
         })
     }
 
-    static _validateBuildTasks(tasks) {
-        tasks.forEach(task => {
-            if (!task.src) {
-                throw new Error(`Invalid build task definition - value of property 'src' is missing in [${task.for || task.use}].`)
-            }
-        })
-    }
-
     _setDefaultBuildTargetFolder(tasks) {
         const task = tasks.find(task => task.for === BUILD_TASK_JAVA_CF || task.for === BUILD_TASK_JAVA)
         const srv = task ? task.src : BuildTaskFactory._getModuleFolder(flatten([cds.env.folders.srv])) || "srv"
@@ -161,19 +150,13 @@ class BuildTaskFactory {
         })
         if (resultTasks.length === 0) {
             if (options.for || options.use) {
-                const task = {}
-                if ((options.for)) {
-                    task.for = options.for
-                }
-                if ((options.use)) {
-                    task.use = options.use
-                }
+                const task = this.providerFactory.getTask(options.for ? { for: options.for } : { use: options.use })
                 if (options.src) {
                     task.src = options.src
                 }
                 resultTasks.push(task)
             }
-        } else if (resultTasks.length < tasks.length) {
+        } else if (resultTasks.length <= tasks.length) {
             // return the same array as long as it contains a subset of the given tasks
             tasks.length = 0
             resultTasks.forEach(task => tasks.push(task))

package/lib/build/buildTaskProvider.js

@@ -1,22 +1,27 @@
 /* eslint-disable no-unused-vars */
+/**
+ * @abstract
+ */
 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)
-        }
-    }
+    /**
+     * @param {object} task 
+     */
+    providesTask(key) { }
+    /**
+     * @returns {object} task 
+     */
+    getTask(key) { return key }
+    /**
+     * @param {object} task 
+     */
+    loadPlugin(task) { }
+    /**
+     * @param {Array} tasks 
+     * @param {boolean} dependencies 
+     */
+    async lookupTasks(tasks, dependencies) { }
+    /**
+     * @param {object} task 
+     */
+    async applyTaskDefaults(task) { }
 }