@sap/cds-dk 10.0.6 → 10.1.0

package/lib/env/schemas/cds-rc.js

@@ -178,79 +178,8 @@ module.exports = {
                     type: "object",
                     description: "Customize cds compile settings",
                     additionalProperties: false,
+                    // export format settings (e.g. `asyncapi`) are contributed by plugins via their package.json `cds.schema.export`
                     properties: {
-                        asyncapi: {
-                            type: "object",
-                            description: "AsyncAPI settings for cds compile",
-                            additionalProperties: false,
-                            properties: {
-                                application_namespace: {
-                                    type: "string",
-                                    description: "The registered namespace of the application"
-                                },
-                                merged: {
-                                    type: "object",
-                                    description: "properties that needs to be there when merged option is used",
-                                    additionalProperties: false,
-                                    properties: {
-                                        title: {
-                                            type: "string",
-                                            description: "Title to be used for merged doc"
-                                        },
-                                        version: {
-                                            type: "string",
-                                            description: "Version to be used for merged doc"
-                                        },
-                                        short_text: {
-                                            type: "string",
-                                            description: "Short decription of the AsyncAPIs"
-                                        },
-                                        description: {
-                                            type: "string",
-                                            description: "Description to be used for the merged doc"
-                                        }
-                                    }
-                                },
-                                event_spec_version: {
-                                    type: "string",
-                                    description: "Mentions the version of AsyncAPI spec"
-                                },
-                                event_source: {
-                                    type: "string",
-                                    description: "Event source information",
-                                    default: "{region}/{applicationNamespace}/{instanceId}",
-                                },
-                                event_source_params: {
-                                    type: "object",
-                                    description: "Parameters related to the source of event",
-                                    default: {
-                                        region: "the region",
-                                        applicationNamespace: "the namespace",
-                                        instanceId: "the instance id"
-                                    },
-                                    additionalProperties: false,
-                                    properties: {
-                                        region: {
-                                            type: "string",
-                                            description: "The regional context of the application"
-                                        },
-                                        applicationNamespace: {
-                                            type: "string",
-                                            description: "The registered namespace of the application"
-                                        },
-                                        instanceId: {
-                                            type: "string",
-                                            description: "The instance id (tenant, installation, ...) of the application."
-                                        }
-                                    }
-                                },
-                                event_characteristics: {
-                                    type: "object",
-                                    description: "The characteristics defined for events",
-                                    additionalProperties: true
-                                }
-                            }
-                        }
                     }
                 },
                 // deploy specific schema
@@ -318,10 +247,6 @@ module.exports = {
         importOptions: {
             from: {
                 oneOf: [
-                    {
-                        const: "asyncapi",
-                        description: "AsyncAPI specification"
-                    },
                     {
                         const: "edmx",
                         description: "OData specification"

package/lib/import/importapi.js

@@ -3,7 +3,6 @@ let { path } = cds.utils;
 let common = require('./common');
 let odata = require('./odata');
 let openapi = require('./openapi');
-let asyncapi = require('./asyncapi');
 let messages = require('./message').getMessages();
 
 module.exports = Object.assign(cds_import, {
@@ -97,15 +96,15 @@ async function cds_import_from_openapi(filepath, options = {}) {
 
 /**
  * This is the import API function to generate CSN from asyncapi files.
+ * cds11: remove once @cap-js/asyncapi is a required project dependency
  * @param {string} filepath
  * - a single valid filepath
  * @returns {object} CSN
  */
 async function cds_import_from_asyncapi(filepath, options = {}) {
-    // validates the input file
     filepath = await common.isValidInputFile(path.resolve(process.cwd(), filepath));
     const src = await common.getContentFromFile(filepath);
-    let csn = asyncapi.asyncapi2csn(src);
+    let csn = require('@cap-js/asyncapi').import.asyncapi2csn(src);
     options.inputFileKind = 'odata';
     return csn;
 }

package/lib/import/message.js

@@ -18,8 +18,6 @@ const messages = {
 	MISSING_ASSOCIATION: 'Association is missing in the input file provided. Please check the edmx file.',
 	COLLECTION_IN_KEY: 'Key Property of an Entity cannot be of the type Collection.',
 	INVALID_OPENAPI_FILE: 'The OpenAPI file is not valid. Specify the correct OpenAPI file.',
-	INVALID_ASYNCAPI_FILE: 'The AsyncAPI file is not valid. Specify the correct AsyncAPI file.',
-	INVALID_MESSAGE_NAME: 'The message name is not valid.',
 	UNRESOLVED_TYPE: 'Could not resolve the type: ',
 	NO_RETURN_TYPE: 'No ReturnType found in Function: ',
 	INVALID_ENUM_TYPE: 'The Underlying type provided is not supported for the EnumType: ',

package/lib/init/constants.js

@@ -5,7 +5,7 @@ module.exports = {
     COMMAND_ADD: 'add',
 
     JAVA_LTS_VERSIONS: [25],
-    MAVEN_ARCHETYPE_VERSION: '5.0.0',
+    MAVEN_ARCHETYPE_VERSION: '5.0.1',
 
     OPTIONS: Object.freeze({
         COMPLETION: 'completion',
@@ -29,6 +29,7 @@ module.exports = {
         IAS: 'ias',
         AMS: 'ams',
         HANA: 'hana',
+        HANA_SERVERLESS: 'hana-serverless',
         POSTGRES: 'postgres',
         SQLITE: 'sqlite',
         LIQUIBASE: 'liquibase',

package/lib/init/index.js

@@ -165,7 +165,7 @@ module.exports = class CDSGenerator {
                 const added = cds.cli.command === 'add' && cds.cli.argv[0]?.split(',').includes(plugin) || cds.cli.options.add?.has(plugin)
                 const inProduction = Plugin.hasInProduction(env4('production')) || added
                 DEBUG && console.log(inProduction ? '✅' : '❌', plugin)
-                if (inProduction) await template.combine()
+                if (inProduction) await template.combine(plugin)
             }
         }
 
@@ -237,7 +237,7 @@ module.exports = class CDSGenerator {
                 const creating = ['java', 'nodejs', 'typescript', 'cjs', 'extension']
                 const { command, options, argv } = cds.cli
                 const inOptions = option => command === 'init' && options.add.has(option) ||
-                                            command === 'add'  && argv[0]?.split(',').includes(option)
+                                            command === 'add'  && argv.flatMap(a => a.split(',')).includes(option)
                 if (!exists('pom.xml') && !exists('package.json') && !creating.some(inOptions)) {
                     if (command === 'init') {
                         const project = argv[0] ? argv[0]+' ' : ''

package/lib/init/merge.js

@@ -1,11 +1,9 @@
 const { EOL } = require('node:os')
-const { inspect } = require('node:util')
 const cds = require('../cds')
 const YAML = require('yaml')
 const { copy, read, write, exists, path: {resolve, join} } = cds.utils
 const { readYAML, writeYAML, readJSON } = require('../util/fs')
 const { detectIndent } = require('./indent')
-const { colors } = require('../util/term')
 
 function _mergeObject(target, source) {
   const _isObject = item => item && typeof item === 'object' && !Array.isArray(item)
@@ -113,288 +111,119 @@ async function _mergeYAML(into, from, project, semantics = {}) {
         throw new Error(`Target YAML doesn't exist`)
     }
 
-    const entryMap = new Map, templateEntryMap = new Map
+    const { forceOverwrite, additions = [], overwrites = [], deletions = [], relationships = [] } = semantics
+    const path = keyPath => keyPath.split('.').filter(k => k)
 
-    const { additions, overwrites, deletions, relationships } = semantics
-    if (relationships && Array.isArray(relationships)) {
-        semantics.additions ??= []
-        const add = semantics.additions
-
-        for (const rel of relationships) {
-            for (const ins of (Array.isArray(rel.insert) ? rel.insert : [rel.insert])) {
-                if (!add.includes(ins)) add.push(ins)
-            }
-            const base = rel.into?.[0]
-            if (base && !add.includes(base)) add.push(base)
-        }
-    }
-
-    for (const entry of additions ?? []) {
-        entryMap.set(entry, undefined)
-        templateEntryMap.set(entry, undefined)
+    // Seq members correspond unless a shared top-level key holds a different scalar.
+    // {name:x} enriches {name:x,...}; {name:x,alias:a} and {name:x,alias:b} stay distinct.
+    const conflict = (a, b) => Object.keys(a).some(k =>
+        k in b && (typeof a[k] !== 'object' || typeof b[k] !== 'object') && JSON.stringify(a[k]) !== JSON.stringify(b[k]))
+    const same = (a, b) => {
+        if (YAML.isMap(a) && YAML.isMap(b)) { const x = a.toJSON(), y = b.toJSON(); return !conflict(x, y) && !conflict(y, x) }
+        return JSON.stringify(a.toJSON?.() ?? a.value) === JSON.stringify(b.toJSON?.() ?? b.value)
     }
-    for (const deletion of deletions ?? []) {
-        entryMap.set(deletion.item, undefined)
+    const has = (seq, node) => YAML.isSeq(seq) && seq.items.some(x => same(x, node))
+
+    // `where` matches a node iff every constraint holds on its JSON projection.
+    const matches = (node, where) => {
+        const json = node.toJSON?.() ?? {}
+        const at = (o, k) => path(k).reduce((p, s) => p?.[s], o)
+        return Object.entries(where).every(([k, v]) =>
+            Array.isArray(v) ? v.every(x => at(json, k) === x) : at(json, k) === v)
     }
-    for (const relationship of relationships ?? []) {
-        const [entry] = relationship.into
-        const [insertEntry] = relationship.insert
-        const hash = JSON.stringify(insertEntry) + ' -> ' + JSON.stringify(entry)
-        entryMap.set(hash, undefined)
-    }
-
-    let collectionStack = [target.contents]
-
-    const _getProperty = (object, keyPath) => keyPath.split('.').filter(k => k).reduce((p, k) => p && p[k], object)
-    const _getYAMLProperty = (object, keyPath) => keyPath.split('.').filter(k => k).reduce((p, k) => p && p.get(k), object)
 
-    const _validateWhere = (node, dict, index) => {
-        const _addToMap = entries => entries?.filter(entry => {
-            if (typeof entry.in === 'string') return true
-            if (typeof entry === 'string' && !entry.where) return false  // no random access caching needed for pure key paths
-            if (Array.isArray(entry)) entry = entry[0]
-            const neededParent = dict.get(entry.in[0])?.node
-            return collectionStack.includes(neededParent) // lookbehind in parent collection stack
-        }).forEach(item => {
-            if (Array.isArray(item)) item = item[0]
-            const json = JSON.parse(String(node))
-            const whereFulfilled = Object.entries(item.where).every(([key, value]) => {
-                if (Array.isArray(value)) {
-                    return value.every(v => _getProperty(json, key) === v)
-                } else {
-                    return _getProperty(json, key) === value
-                }
-            })
-            if (whereFulfilled) {
-                const [collection] = collectionStack
-                dict.set(item, { json, node, index, collection })
-            }
-        })
-        if (additions) _addToMap(additions)
-        if (deletions) _addToMap(deletions.map(deletion => deletion.item))
-        if (relationships) _addToMap(relationships?.map(({into: [entry]}) => entry).filter(e => e))
-        if (overwrites) _addToMap(overwrites.map(overwrite => overwrite.item))
+    // Resolve a descriptor to a live node:
+    //   'a.b.c' -> getIn; {in,where} -> matching seq member; [entry,'rel'] -> getIn on entry.
+    const locate = (doc, d) => {
+        if (d == null) return undefined
+        if (typeof d === 'string') return doc.getIn(path(d))
+        if (Array.isArray(d)) {
+            const [base, keyPath] = d
+            const node = locate(doc, base)
+            return keyPath ? node?.getIn(path(keyPath)) : node
+        }
+        const seq = locate(doc, d.in)
+        return YAML.isSeq(seq) ? seq.items.find(n => matches(n, d.where)) : undefined
     }
 
-    function _traverseYAMLNode(node, index, actions, templateNode) {
-        let shifted = false
-        if (YAML.isMap(node)) {
-            actions.visitMap?.(node, index)
-            const [collection] = collectionStack
-            if (YAML.isSeq(collection)) {
-                collectionStack.unshift(node)
-                shifted = true
+    // Generic deep-merge: recurse maps, enrich matching seq members, union scalars.
+    // Unmatched map members are placed by the passes below. Target scalars win unless forced.
+    const mergeNode = (t, s) => {
+        if (YAML.isMap(t) && YAML.isMap(s)) {
+            for (const pair of s.items) {
+                const tv = t.get(pair.key.value, true)
+                if (tv === undefined) t.add(pair)
+                else mergeNode(tv, pair.value)
             }
-        } else if (YAML.isPair(node) && node.value?.items) {
-            collectionStack.unshift(node.value)
-        } else if (YAML.isScalar(node) && semantics.forceOverwrite && templateNode && node.comment != 'cds.noOverwrite') {
-            node.value = templateNode.value ?? templateNode.items?.[0]?.value?.value
-        }
-
-        if (node.items) {
-            if (YAML.isSeq(node) && templateNode?.items) {
-                actions.mergeCollection?.(node, templateNode)
-                _traverseYAMLCollection(node, actions, templateNode)
-            } else {
-                _traverseYAMLCollection(node, actions, templateNode)
+        } else if (YAML.isSeq(t) && YAML.isSeq(s)) {
+            for (const item of s.items) {
+                const match = t.items.find(x => same(x, item))
+                if (match) mergeNode(match, item)
+                else if (YAML.isScalar(item)) t.add(item)
             }
-        } else if(node.value?.source === '' && YAML.isSeq(templateNode?.value)) {
-            node.value = new YAML.YAMLSeq()
-            collectionStack.unshift(node.value)
-            _traverseYAMLNode(node.value, index, actions, templateNode?.value)
-        } else if (node.value?.items || node.value && semantics.forceOverwrite) {
-            _traverseYAMLNode(node.value, index, actions, templateNode?.value)
+        } else if (forceOverwrite && YAML.isScalar(t) && YAML.isScalar(s) && t.comment !== 'cds.noOverwrite') {
+            t.value = s.value
         }
-
-        if (node.value?.items || shifted) {
-            collectionStack.shift()
+    }
+    mergeNode(target.contents, source.contents)
+
+    // Placement: add matched (and relationship-referenced) template entries not already present.
+    const isEntry = e => e && typeof e === 'object' && !Array.isArray(e) && e.in !== undefined
+    const insertNode = ins => Array.isArray(ins) ? (ins.length === 1 ? ins[0] : undefined) : ins
+    const relEntries = relationships.flatMap(r => [r.into?.[0], ...[].concat(r.insert).map(insertNode)])
+    for (const entry of [...additions, ...relEntries].filter(isEntry)) {
+        const seq = locate(target, entry.in)
+        if (!YAML.isSeq(seq)) continue
+        const clone = locate(source, entry)
+        if (clone && !has(seq, clone)) {
+            entry.at !== undefined ? seq.items.splice(entry.at, 0, clone) : seq.add(clone)
         }
     }
-    _traverseYAMLNode.bind(this)
-
-    function _traverseYAMLCollection (collection, actions, templateCollection) {
-        if (!collection) return
-
-        const keyToIndex = new Map, templateIndexToIndex = new Map
-
-        // Map collection items to their semantic counterpart(s)
-        collection.items.forEach((node, i) => {
-            if (node.key) keyToIndex.set(node.key.value, i)
-            const entry = [...entryMap.entries()].find(([,value]) => value?.node === node)
-            if (entry) {
-                const [entryKey] = entry
-                const templateEntry = entryKey && templateEntryMap.get(entryKey)
-                const templateIndex = templateEntry?.index
-                if (templateIndex !== undefined) templateIndexToIndex.set(templateIndex, i)
-            }
-            if (!templateCollection) _traverseYAMLNode(node, i, actions)
-        })
-
-        if (!templateCollection?.items) return
 
-        templateCollection.items?.forEach((templateNode, templateIndex) => {
-            if (YAML.isScalar(templateNode)) {
-                if (!collection.items.map(item => item.value).includes(templateNode.value)) {
-                    collection.add(templateNode)
-                }
-            } else if (YAML.isPair(templateNode)) {
-                const i = keyToIndex.get(templateNode.key.value)
-                const [collection] = collectionStack
-                const targetNode = collection.items?.[i]
-                if (targetNode) {
-                    _traverseYAMLNode(targetNode, templateIndex, actions, templateNode)
-                } else {
-                    actions.mergePair?.(collection, templateNode)
-                }
-            } else if (YAML.isMap(templateNode)) {
-                const targetNode = collection.items[templateIndexToIndex.get(templateIndex)]
-                actions.mergeCollection?.(targetNode, templateNode)
-                if (targetNode) {
-                    _traverseYAMLNode(targetNode, templateIndex, actions, templateNode)
-                }
-            }
-        })
+    // Relationships: wire a value into a target seq. [entry,'k'] -> {k: value}; [entry] -> the node.
+    for (const { insert, into } of relationships) {
+        const [baseEntry, seqPath, prop] = into
+        const seq = locate(target, seqPath ? [baseEntry, seqPath] : baseEntry)
+        if (!YAML.isSeq(seq)) continue
+        for (const ins of Array.isArray(insert) && typeof insert[0] === 'object' ? [insert] : [].concat(insert)) {
+            const [srcEntry, valueKey] = Array.isArray(ins) ? ins : [ins]
+            const srcNode = locate(target, srcEntry)
+            if (!srcNode) continue
+            const ref = prop || valueKey
+            const node = ref ? target.createNode({ [ref]: (valueKey ? srcNode.get(valueKey) : srcNode.get(ref)) }) : srcNode
+            if (!has(seq, node)) seq.add(node)
+        }
     }
-    _traverseYAMLCollection.bind(this)
-
-    // 1. Register the entries in the template
-    _traverseYAMLNode(source.contents, null, {
-        visitMap: (node, index) => _validateWhere(node, templateEntryMap, index)
-    })
 
-    // 2. Register the entries in the project
-    _traverseYAMLNode(target.contents, null, {
-        visitMap: (node, index) => _validateWhere(node, entryMap, index)
-    })
-
-    // 3. Apply overwrites to already found entries
-    overwrites?.forEach(({ item, withValue }) => {
-        const keyPath = Array.isArray(item) && typeof item[0] === 'string' ? item[0] : typeof item === 'string' ? item : item[1]
-        const inEntry = Array.isArray(item) && typeof item[0] === 'object' ? item[0] : typeof item === 'object' ? item : item[1]
-        let node
-        if (inEntry && entryMap.get(inEntry)) {
-            node = entryMap.get(inEntry).node // starting from item found in nested array cache
-        } else if (typeof inEntry === 'string') {
-            node = collectionStack[collectionStack.length - 1] // starting from root
-        } else {
-            return
-        }
+    // Fill the bare nodes relationships just added from their full source counterparts.
+    if (relationships.length) mergeNode(target.contents, source.contents)
 
-        const keys = keyPath.split('.')
-        for (const key of keys.slice(0, -1)) {
-            if (!node?.get(key) && typeof inEntry === 'string') return // node doesn't exist, will be added by template
-            node = node?.get(key) ?? node
+    // Overwrites: set a (possibly nested) key on a located node.
+    for (const { item, withValue } of overwrites) {
+        const [base, keyPath] = Array.isArray(item) ? item : [undefined, item]
+        const node = base ? locate(target, base) : target.contents
+        const keys = path(typeof base === 'string' ? base : keyPath)
+        if (node?.getIn(keys.slice(0, -1)) !== undefined || base && typeof base !== 'string') {
+            (node.getIn(keys.slice(0, -1)) ?? node).set(keys.at(-1), withValue)
         }
-        const tail = keys.pop()
-        if (!node.get(tail)) {
-            node.add({ key: tail, value: withValue })
-        } else {
-            node.set(tail, withValue)
-        }
-    })
-
-    // 4. Delete entries from the project (e.g. separate deployer module when adding mtx)
-    deletions?.forEach(({ item, relationships, key }) => {
-        const entry = entryMap.get(item)
-        if (!entry) return
-        if (key) entry.collection.deleteIn([entry.index, ...key.split('.')])
-        else entry.collection.delete(entry.index)
-
-        relationships?.forEach(relationship => {
-            const [allWithinKeyPath, inKeyPath, into] = relationship.allWithin
-            const parent = _getYAMLProperty(target, allWithinKeyPath)
-            for (const child of parent.items) {
-                const grandchild = _getYAMLProperty(child, inKeyPath)
-                const i = grandchild?.items?.findIndex(node =>
-                    node.get(into) === _getProperty(entry.json, relationship.removeProperty)
-                ) ?? - 1
-                if (i > -1) grandchild.delete(i)
-            }
-        })
-    })
-
-    // 5. Create missing entries and pairs
-    _traverseYAMLNode(target.contents, null, {
-        mergePair: (collection, templateNode) => {
-            if (YAML.isMap(collection)) {
-                collection.add(templateNode)
-            }
-        },
-        mergeCollection: (targetNode, templateNode) => {
-            if (YAML.isSeq(templateNode)) {
-                let [,parent] = collectionStack
-                additions?.filter(addition => {
-                        if (typeof addition.in === 'string' || Array.isArray(addition.in) && typeof addition.in[0] === 'string') return true
-                            const base = Array.isArray(addition.in) ? addition.in[0] : addition.in
-                            const keyPath = Array.isArray(addition.in) ? addition.in[1] : ''
-                            const inEntry = entryMap.get(base)
-                            if (!inEntry) return false
-                            const depth = String(keyPath).split('.').filter(Boolean).length
-                            const expectedParent = depth > 1 ? collectionStack[depth] : parent
-                            return inEntry.node === expectedParent
-                    })
-                    .filter(addition => {
-                        const keyPath = typeof addition.in === 'string' ? addition.in : Array.isArray(addition.in) && typeof addition.in[0] === 'string' ? addition.in[0] : addition.in[1]
-                        const keys = keyPath.split('.')
-                        if (keys.length > collectionStack.length + 1) return false
-                        if (keys.length > 1) parent = collectionStack[keys.length]
-                        return _getYAMLProperty(parent, keyPath) === targetNode
-                    })
-                    .filter(item => !entryMap.get(item))
-                    .forEach(item => {
-                        if (!templateEntryMap.get(item)) throw 'Error: did not find entry in template for ' + inspect(item, { colors, depth:11 }) + ' in \n' + from
-                        const templateNode = templateEntryMap.get(item).node
-                        item.at !== undefined ? targetNode.items.splice(item.at, 0, templateNode) : targetNode.add(templateNode)
-                    })
-
-            }
-        },
-    }, source.contents)
-
-    // 6. Re-register the entries in the project
-    _traverseYAMLNode(target.contents, null, {
-        visitMap: (node, index) => _validateWhere(node, entryMap, index)
-    })
+    }
 
-    // 7. Create missing relationships
-    _traverseYAMLNode(target.contents, null, {
-        mergeCollection: (targetNode, templateNode) => {
-            if (!YAML.isSeq(templateNode)) return
-            const targetJSON = YAML.parse(String(targetNode))
-            for (const { insert, into } of semantics.relationships ?? []) {
-                const [first, ...rest] = into
-                const seqPath = rest.find(x => typeof x === 'string') || ''
-                const keyPath = rest.length > 1 ? rest.at(-1) : null
-                const base = entryMap.get(first)
-                if (!base) continue
-                const seqNode = seqPath ? _getYAMLProperty(base.node, seqPath) : base.node
-                if (seqNode !== targetNode) continue
-                const inserts = Array.isArray(insert) ? insert : [insert]
-                for (const ins of inserts) {
-                    const insEntry = entryMap.get(ins)
-                    if (!insEntry) continue
-                    const srcNode = insEntry.node, srcJson = insEntry.json
-                    let key = keyPath
-                    if (!key && srcNode.get && srcNode.get('name')) key = 'name'
-                    let cand, duplicate
-                    if (key) {
-                        const val = _getProperty(srcJson, key)
-                        cand = templateNode.items.find(i => YAML.isMap(i) && i.get(key) === val) || { [key]: val }
-                        duplicate = targetJSON.some(t => t?.[key] === val)
-                    } else {
-                        cand = templateNode.items.find(i => JSON.stringify(YAML.parse(String(i))) === JSON.stringify(YAML.parse(String(srcNode)))) || srcNode
-                        const srcObj = YAML.parse(String(cand))
-                        duplicate = targetJSON.some(t => JSON.stringify(t) === JSON.stringify(srcObj))
-                    }
-                    if (!duplicate) {
-                        const clone = YAML.parse(YAML.stringify(cand))
-                        targetNode.add(clone)
-                        targetJSON.push(clone)
-                    }
-                }
+    // Deletions: remove the matched node (or a sub-key), then cascade-remove references to it.
+    for (const { item, key, relationships: refs } of deletions) {
+        const seq = locate(target, item.in)
+        const node = locate(target, item)
+        if (!YAML.isSeq(seq) || !node) continue
+        const removed = node.toJSON()
+        key ? node.deleteIn(path(key)) : seq.delete(seq.items.indexOf(node))
+        for (const { removeProperty, allWithin } of refs ?? []) {
+            const [parentPath, childPath, prop] = allWithin
+            for (const parent of locate(target, parentPath)?.items ?? []) {
+                const list = parent.getIn(path(childPath))
+                const i = list?.items?.findIndex(n => n.get?.(prop) === removed[removeProperty]) ?? -1
+                if (i > -1) list.delete(i)
             }
         }
-    }, source.contents)
+    }
 
     typeof into === 'string' && await writeYAML(into, target)
     return target
@@ -471,39 +300,53 @@ module.exports.merge = (...src) => {
 }
 
 
+/**
+ * A location in a document. One of:
+ *  - a dotted key path from the root, e.g. `'modules'` or `'a.b.c'`;
+ *  - a {@link MatchedNode}, i.e. the member of a collection satisfying a `where` predicate;
+ *  - a based path `[base, keyPath?]` resolving `keyPath` relative to the node `base` denotes
+ *    (with `keyPath` omitted, the pair denotes `base` itself).
+ * @typedef {string | MatchedNode | [Descriptor, string?]} Descriptor
+ */
+
 /**
  * @typedef {Object} MatchedNode
- * @property {string | MatchedNode} in - key path or matched node to start search from
- * @property {Object} where - list of constraints
+ * @property {Descriptor} in - the collection to search
+ * @property {Object.<string, (string | number | boolean | Array)>} where - constraints on the
+ *   node's JSON projection; an array value requires each of its entries to be present
+ * @property {number} [at] - insertion index for additions (appended when omitted)
  */
 
 /**
  * @typedef {Object} Overwrites
- * @property {(string | MatchedNode)[]} item - path to item to be overwritten
- * @property {string} withValue - replacement string
+ * @property {Descriptor} item - location of the value to overwrite
+ * @property {string | number | boolean} withValue - replacement value
  */
 
 /**
  * @typedef {Object} Deletion
  * @property {MatchedNode} item - matched node to delete
- * @property {MatchedNode} [key] - key path to property to delete in node (optional)
- * @property {Object[]} [relationships] - list of relationships to delete
- * @property {string} relationships[].removeProperty - key path to to-be-removed property
- * @property {string[]} relationships[].allWithin - key path to relationship
+ * @property {string} [key] - dotted key path of a sub-property to delete instead of the whole node
+ * @property {Object[]} [relationships] - references to cascade-remove after deletion
+ * @property {string} relationships[].removeProperty - property of the removed node to match on
+ * @property {string[]} relationships[].allWithin - `[parentPath, childPath, prop]` naming the
+ *   sibling collections and the referencing property to strip
  */
 
 /**
  * @typedef {Object} Relationship
- * @property {(string | MatchedNode)[]} insert - source path to matched node
- * @property {(string | MatchedNode)[]} into - target path for inserted relationship
+ * @property {Descriptor | Descriptor[] | [Descriptor, string]} insert - source node(s), or a
+ *   `[entry, key]` pair whose `key` value is wired in
+ * @property {[Descriptor, string?, string?]} into - `[baseEntry, seqPath?, prop?]` naming the
+ *   target sequence and, optionally, the property key the wired value is written under
  */
 
 /**
  * @typedef {Object} MergingSemantics
- * @property {boolean} [forceOverwrite] - overwrite values for existing keys
- * @property {MatchedNode[]} [additions] - matched nodes to be added from source template
- * @property {Overwrites[]} [overwrites] - matched keys to be overwritten with given string
- * @property {Deletion[]} [deletions] - matched nodes to be deleted
- * @property {Relationship[]} [relationships] - relationships to be inserted
+ * @property {boolean} [forceOverwrite] - overwrite existing scalar values from the template
+ * @property {MatchedNode[]} [additions] - matched nodes to add from the source template
+ * @property {Overwrites[]} [overwrites] - values to overwrite at the given locations
+ * @property {Deletion[]} [deletions] - matched nodes (or sub-keys) to delete
+ * @property {Relationship[]} [relationships] - relationships to wire into target sequences
  */