@sap/cds-dk 7.9.4 → 8.0.2

package/lib/init/index.js

@@ -1,102 +1,60 @@
-const path = require('path');
+const path = require('path')
+const term = require('../util/term')
+const validate = require('./validate')
 
-const term = require('../util/term');
+const { OPTIONS, COMMAND_INIT, PROJECT_FILES } = require('./constants')
+const { readdirSync } = require('fs')
+const { join } = require('path')
+const { NODEJS, JAVA } = OPTIONS
 
-const { OPTIONS, COMMAND_INIT, PROJECT_FILES, REGEX_PROJECT_NAME } = require('./constants')
-const {
-    NODEJS, JAVA,
-    HANA, APPROUTER, XSUAA, APPLICATION_LOGGING, ENTERPRISE_MESSAGING,
-    MTA, MULTITENANCY, PIPELINE,
-    TINY_SAMPLE, SAMPLE
-} = OPTIONS
-
-const cds = require('..'), { exists, readdir } = cds.utils
+const cds = require('..'), { exists } = cds.utils
 const DEBUG = /\b(y|all|cli)\b/.test(process.env.DEBUG) ? console.debug : undefined
 
 module.exports = class CDSGenerator {
-    constructor() {
-        this.cwd = process.cwd()
 
-        this.uiConfig = [{
-            title: 'Project Name',
-            description: 'Enter your project name.',
-            default: '',
-            target: 'projectName',
-            validate: async (value) => {
-                try {
-                    cds.root = path.resolve(this.cwd, value || '.');
-
-                    await this._validateProjectName(value);
-                    await this._validateProjectFolder(path.join(this.cwd, value), this.cwd);
-                } catch (e) {
-                    return e
-                }
+    /** @returns {string[]} */
+    static #findPlugins(excluded) {
+        // actually needs to be sync to be usable in module.exports of dk/bin/init.js
+        const fromDk = readdirSync(join(__dirname, 'template'))
+        const fromPlugins = Object.keys(Object.fromEntries(require('./add').registered))
+        return [...fromDk, ...fromPlugins]
+            .filter(plugin => !excluded?.includes(plugin))
+    }
 
-                return true;
-            },
-            guiOptions: {
-                hint: 'This name is restricted to certain characters. A valid project name is compatible across platforms.',
-                mandatory: true
-            }
-        }, {
-            title: 'Type',
-            description: `Select your runtime.`,
-            default: NODEJS,
-            choices: [
-                { name: 'Node.js', value: NODEJS },
-                { name: 'Java', value: JAVA }
-            ],
-            multiple: false,
-            target: 'add',
-            guiOptions: {
-                hint: `The preferred runtime can't be changed afterwards. To use a different runtime, create a new project.`,
-                mandatory: true
-            }
-        }, {
-            title: 'Features',
-            description: 'Choose productive runtime capabilities for your application.',
-            default: '',
-            choices: [
-                { name: 'SAP HANA Cloud', value: HANA },
-                { name: 'SAP Application Router', value: APPROUTER },
-                { name: 'User Authentication via XSUAA', value: XSUAA },
-                { name: 'Application Logging', value: APPLICATION_LOGGING },
-                { name: 'SAP BTP Event Mesh', value: ENTERPRISE_MESSAGING }
-            ],
-            multiple: true,
-            target: 'add',
-            guiOptions: {
-                hint: `Choose any combination of features enriching the capabilities of your project. You can also add features later with ${term.bold('cds add')}`
-            }
-        }, {
-            title: 'Deployment',
-            description: 'Choose which way to deploy your project.',
-            default: '',
-            choices: [
-                { name: 'Cloud Foundry: MTA Deployment', value: MTA },
-                // { name: 'Kyma: Helm Deployment', value: HELM },
-                { name: 'Multitenancy', value: MULTITENANCY },
-                { name: 'CI/CD Pipeline Integration', value: PIPELINE },
-            ],
-            multiple: true,
-            target: 'add',
-            guiOptions: {
-                hint: `Choose any combination of features enriching the capabilities of your project. You can also add features later with ${term.bold('cds add')}`
-            }
-        }, {
-            title: 'Samples',
-            description: `Add sample content to your project.`,
-            default: '',
-            choices: [
-                { name: 'Minimal Sample', value: TINY_SAMPLE },
-                { name: 'Extended Sample with UI', value: SAMPLE }
-            ],
-            multiple: true,
-            target: 'add',
-            guiOptions: {
-                hint: 'Speed up your ramp-up phase with sample files in your project.'
-            }
-        }]
+    static help({ exclude = [] } = {}) {
+        const plugins = this.readPlugins(exclude)
+        const nameFixedLength = Math.max(...plugins.map(plugin => plugin.name.length))
+        return plugins
+            .map(({name, module}) => {
+                const help = module.help?.() ?? ''
+                return `      *${name}*${' '.repeat(nameFixedLength - name.length)}  - ${help}`
+            })
+            .join('\n\n')
+    }
+
+    /**
+     * @returns {{name: string, module: import('module')}[]}
+     */
+    static readPlugins(excluded = []) {
+        const plugins = this.#findPlugins(excluded)
+            .map(plugin => ({
+                name: plugin,
+                module: cds.add.registered.get(plugin) ?? require('./template/' + plugin)
+            }))
+        const cmds = Object.values(OPTIONS)
+        const byPriority = (lhs, rhs) => {
+            const a = cmds.indexOf(lhs.name), b = cmds.indexOf(rhs.name)
+            if (a === -1 && b === -1) return 0
+            if (a === -1) return 1
+            if (b === -1) return -1
+            return a - b
+        }
+        return plugins.sort(byPriority)
+    }
+
+    constructor() {
+        this.cwd = process.cwd()
+        this.uiConfig = require('./bas') // Used by CAP Generator
     }
 
     /**
@@ -113,7 +71,7 @@ module.exports = class CDSGenerator {
         // `add data` can live without project metadata
         const nonProjectFacets = { completion:1, data:1 }
         const needsProject = facets.some(facet => !nonProjectFacets[facet])
-        if (needsProject && !PROJECT_FILES.find(exists)) {
+        if (needsProject && !PROJECT_FILES.some(exists)) {
             throw `The current folder doesn't seem to contain a project. None of the following files found: ${PROJECT_FILES.join(', ')}.`
         }
 
@@ -124,12 +82,12 @@ module.exports = class CDSGenerator {
     /**
      * @param {string} projectName, the project name
      */
-    async initCmd(projectName) {
+    async init(projectName) {
         await this.stepInit(projectName);
         await this.stepEnd();
     }
 
-    async stepInit(projectName, options) {
+    async stepInit(projectName, options) { // Also used by CAP Generator
         if (options) {
             // called from CAP generator with options
             cds.cli = {
@@ -177,13 +135,18 @@ module.exports = class CDSGenerator {
     async _process(facets) {
         DEBUG?.(`Project path: ${cds.root}`);
 
-        await this._validateOptions();
-
-        const { command, options } = cds.cli
+        const { options, command } = cds.cli
+        if (command === COMMAND_INIT) {
+            validate.projectName(this.projectName)
+            validate.projectFolder(this.cwd)
+        }
         const plugins = command === COMMAND_INIT ? options.add : new Set(facets)
         await this._fillTemplateList(plugins)
 
-        for (const [i, facet] of Object.entries(Array.from(plugins))) {
+        const cmds = Object.values(OPTIONS)
+        const byPriority = (a, b) => cmds.indexOf(a) - cmds.indexOf(b)
+        const sorted = Array.from(plugins).sort(byPriority)
+        for (const [i, facet] of Object.entries(sorted)) {
             if (!cds.cli.options.dry) console.log(`Adding feature '${facet}'...`);
             const template = this.templateList[i]
             await template.run();
@@ -209,16 +172,16 @@ module.exports = class CDSGenerator {
             return new Plugin(this)
         } catch (err) {
             if (err.code === 'MODULE_NOT_FOUND') {
-                const entries = (await readdir(path.join(__dirname, 'template')))
-                    .filter(entry =>
-                        !entry.startsWith('_') &&
-                        !entry.endsWith('.js') &&
-                        entry !== 'nodejs' &&
-                        entry !== 'java'
-                    );
+                const entries = this.constructor.readPlugins()
                 const fuzzySearch = require('../../bin/util/fuzzySearch')
-                const [bestMatch] = fuzzySearch(plugin, entries)
-                throw `Unknown facet '${term.bold(plugin)}'. Did you mean ${term.bold(`cds add ${bestMatch}`)}?\n\nHaven't found the proper facet yet? Here are all supported facets:\n\n  ${term.bold(entries.join('\n  '))}\n`
+                const [bestMatch] = fuzzySearch(plugin, entries.map(e => e.name))
+                const max = entries.reduce((max, {name}) => Math.max(max, name.length), 0)
+                const allFacetsText = entries.map(({name, module}) => {
+                    const help = module.help?.() ?? ''
+                    return `${term.bold(name) + ' '.repeat(max - name.length)}  ${term.dim(help)}`
+                }).join('\n')
+                DEBUG?.(err)
+                throw `Unknown facet '${term.bold(plugin)}'. Did you mean ${term.bold(`cds add ${bestMatch}`)}?\n\nHaven't found the proper facet yet? Here are all supported facets:\n\n${allFacetsText}\n`
             }
             throw err
         }
@@ -226,7 +189,6 @@ module.exports = class CDSGenerator {
 
     async _fillTemplateList(plugins) {
         const templates = new Map
-
         for (let plugin of plugins) {
             // Compat
             if (plugin === 'helm' && cds.cli.options['internal-unified-runtime-charts']) {
@@ -245,6 +207,8 @@ module.exports = class CDSGenerator {
                     templates.set(plugin, template)
                     const dependencies = await template.requires()
                     dependencies?.forEach(d => plugins.add(d))
+                } else {
+                    throw 'cannot run plugin \'' + plugin + '\'' + (DEBUG ? 'Does not satisfy the canRun() function:\n    ' + template.canRun : '')
                 }
             }
         }
@@ -260,12 +224,10 @@ module.exports = class CDSGenerator {
             })
             .map((entry) => entry[1])
 
-        // check debug to avoid lengthy computation when not in debug mode
         DEBUG?.(`Features: ${this.templateList.map(({ name }) => name).join(', ')}`);
     }
 
-    // CAP Generator API
-    async stepEnd() {
+    async stepEnd() { // Also used by CAP Generator
         for (const template of this.templateList) {
             await template.finalize();
         }
@@ -305,42 +267,4 @@ module.exports = class CDSGenerator {
             options.add.add(NODEJS);
         }
     }
-
-    async _validateOptions() {
-        const { options, command } = cds.cli
-        if (options.force) {
-            return;
-        }
-
-        if (command === COMMAND_INIT) {
-            await this._validateProjectName(this.projectName);
-            await this._validateProjectFolder(this.cwd);
-        }
-    }
-
-    async _validateProjectName(projectName) {
-        if (!projectName) {
-            throw 'Specify a project name.'
-        }
-
-        // remove duplicates by using a set
-        const invalidChars = new Set(projectName.match(REGEX_PROJECT_NAME));
-        if (invalidChars.size > 0) {
-            throw `Project name '${projectName}' contains at least one character ('${[...invalidChars]}') which is not supported in npm package names.
-Specify a different project name by replacing characters with '_' or '-', for example '${projectName.replace(REGEX_PROJECT_NAME, '_')}' or '${projectName.replace(REGEX_PROJECT_NAME, '-')}'.`
-        }
-    }
-
-    async _validateProjectFolder(cwd) {
-        const existingProjectFile = PROJECT_FILES.find(exists)
-        if (existingProjectFile) {
-            let message;
-            if (cwd === cds.root) {
-                message = `You seem to be working in a project which is already initialized. Use ${term.bold('cds add')} to add more features.`;
-            } else {
-                message = `You seem to be trying to initialize an existing project. Use a different project name instead.`;
-            }
-            throw `${message}\nDetails: File '${existingProjectFile}' exists in the project folder which indicates an existing project. Use ${term.bold('cds add')} to add more features.`
-        }
-    }
 }

package/lib/init/merge.js

@@ -1,9 +1,10 @@
-const YAML = require('@sap/cds-foss').yaml
+const { EOL } = require('node:os')
+const { inspect } = require('node:util')
 const cds = require('../cds')
-const { copy, read, write, exists } = cds.utils
+const { copy, read, write, exists, path, yaml: YAML } = cds.utils
 const { readYAML, writeYAML, readJSON } = require('../util/fs')
-const { EOL } = require('node:os')
 const { detectIndent } = require('./indent')
+const { colors } = require('../util/term')
 
 function _isObject(item) {
   return item && typeof item === 'object' && !Array.isArray(item)
@@ -28,7 +29,7 @@ function _mergeObject(target, source) {
   return target ?? source
 }
 
-async function sort(path, key) {
+module.exports.sort = async function(path, key) {
   const json = await read(path)
   json[key] = Object.fromEntries(
       Object.entries(json[key]).sort(([a],[b]) => a>b ? 1 : -1)
@@ -41,7 +42,7 @@ async function sort(path, key) {
  * @param {string | string[]} from - either path to file (string) or lines from source gitignore (string[])
  * @returns {Promise<string[]>} the lines of the updated .gitignore
  */
-async function mergeGitignore (into, from) {
+module.exports.mergeGitignore = async function(into, from) {
     const source = typeof from === 'string' ? (await read(from)).split(EOL) : from
 
     if (typeof into === 'string' && !exists(into)) {
@@ -196,7 +197,7 @@ async function _mergeYAML(into, from, project, semantics = {}) {
             }
         } else if (YAML.isPair(node) && node.value?.items) {
             collectionStack.unshift(node.value)
-        } else if (YAML.isScalar(node) && semantics.forceOverwrite && templateNode) {
+        } else if (YAML.isScalar(node) && semantics.forceOverwrite && templateNode && node.comment != 'cds.noOverwrite') {
             node.value = templateNode.value ?? templateNode.items?.[0]?.value?.value
         }
 
@@ -326,9 +327,11 @@ async function _mergeYAML(into, from, project, semantics = {}) {
                     })
                     .filter(item => !entryMap.get(item))
                     .forEach(item => {
+                        if (!templateEntryMap.get(item)) throw 'Error: did not find entry in template for ' + inspect(item, { colors }) + ' in ' + from
                         const templateNode = templateEntryMap.get(item).node
                         item.at !== undefined ? targetNode.items.splice(item.at, 0, templateNode) : targetNode.add(templateNode)
                     })
+
             }
         },
     }, source.contents)
@@ -372,7 +375,7 @@ async function _mergeYAML(into, from, project, semantics = {}) {
     return target
 }
 
-async function removeFromYAML(name, keyPaths) {
+module.exports.removeFromYAML = async function (name, keyPaths) {
     const yaml = await readYAML(name)
     for (const keyPath of keyPaths) {
         let node = yaml
@@ -389,7 +392,7 @@ async function removeFromYAML(name, keyPaths) {
     await writeYAML(name, yaml)
 }
 
-async function removeFromYAMLArray(name, keyPath, aliasToRemove) {
+module.exports.removeFromYAMLArray = async function(name, keyPath, aliasToRemove) {
     const yaml = await readYAML(name)
 
     let node = yaml
@@ -414,16 +417,13 @@ async function removeFromYAMLArray(name, keyPath, aliasToRemove) {
     await writeYAML(name, yaml)
 }
 
-
-const path = require('path')
-
 /**
  * @param {...(string | Object | YAML.Document)} src The source to merge from.
  * @returns {{
 *   into: (dst: (string | Object | YAML.Document), options?: {project?: Object, semantics?: MergingSemantics}) => Promise<any>
 * }} An object with an 'into' method to merge the sources into the specified destination.
 */
-const merge = (...src) => {
+module.exports.merge = (...src) => {
     return {
         /**
          * Merges sources into the specified destination.
@@ -447,11 +447,3 @@ const merge = (...src) => {
         }
     }
 }
-
-module.exports = {
-  merge,
-  sort,
-  mergeGitignore,
-  removeFromYAML,
-  removeFromYAMLArray
-}