feat: allow destructive changes with MetadataOptions

package.json

@@ -25,8 +25,8 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@salesforce/core": "^7.3.0",
-    "@salesforce/kit": "^3.1.0",
+    "@salesforce/core": "^7.3.1",
+    "@salesforce/kit": "^3.1.1",
     "@salesforce/ts-types": "^2.0.9",
     "fast-levenshtein": "^3.0.0",
     "fast-xml-parser": "^4.3.6",

src/collections/componentSetBuilder.ts

@@ -10,11 +10,12 @@ import { StateAggregator, Logger, SfError, Messages } from '@salesforce/core';
 import fs from 'graceful-fs';
 import minimatch from 'minimatch';
 import { MetadataComponent } from '../resolve/types';
+import { SourceComponent } from '../resolve/sourceComponent';
 import { ComponentSet } from '../collections/componentSet';
 import { RegistryAccess } from '../registry/registryAccess';
 import type { FileProperties } from '../client/types';
 import { MetadataType } from '../registry/types';
-import { FromConnectionOptions } from './types';
+import { DestructiveChangesType, FromConnectionOptions } from './types';
 
 Messages.importMessagesDirectory(__dirname);
 const messages = Messages.loadMessages('@salesforce/source-deploy-retrieve', 'sdr');
@@ -29,6 +30,14 @@ export type ManifestOption = {
 type MetadataOption = {
   metadataEntries: string[];
   directoryPaths: string[];
+  /**
+   * Array of metadata type:name pairs to delete before the deploy. Use of wildcards is not allowed.
+   */
+  destructiveEntriesPre?: string[];
+  /**
+   * Array of metadata type:name pairs to delete after the deploy. Use of wildcards is not allowed.
+   */
+  destructiveEntriesPost?: string[];
 };
 
 type OrgOption = {
@@ -114,6 +123,26 @@ export class ComponentSetBuilder {
           .map(addToComponentSet(componentSetFilter));
 
         logger.debug(`Searching for matching metadata in directories: ${directoryPaths.join(', ')}`);
+
+        // add destructive changes if defined. Because these are deletes, all entries
+        // are resolved to SourceComponents
+        if (metadata.destructiveEntriesPre) {
+          metadata.destructiveEntriesPre
+            .map(entryToTypeAndName(registryAccess))
+            .map(assertNoWildcardInDestructiveEntries)
+            .flatMap(typeAndNameToMetadataComponents({ directoryPaths, registry: registryAccess }))
+            .map((mdComponent) => new SourceComponent({ type: mdComponent.type, name: mdComponent.fullName }))
+            .map(addToComponentSet(componentSet, DestructiveChangesType.PRE));
+        }
+        if (metadata.destructiveEntriesPost) {
+          metadata.destructiveEntriesPost
+            .map(entryToTypeAndName(registryAccess))
+            .map(assertNoWildcardInDestructiveEntries)
+            .flatMap(typeAndNameToMetadataComponents({ directoryPaths, registry: registryAccess }))
+            .map((mdComponent) => new SourceComponent({ type: mdComponent.type, name: mdComponent.fullName }))
+            .map(addToComponentSet(componentSet, DestructiveChangesType.POST));
+        }
+
         const resolvedComponents = ComponentSet.fromSource({
           fsPaths: directoryPaths,
           include: componentSetFilter,
@@ -162,9 +191,9 @@ export class ComponentSetBuilder {
 }
 
 const addToComponentSet =
-  (cs: ComponentSet) =>
+  (cs: ComponentSet, deletionType?: DestructiveChangesType) =>
   (cmp: MetadataComponent): MetadataComponent => {
-    cs.add(cmp);
+    cs.add(cmp, deletionType);
     return cmp;
   };
 
@@ -195,6 +224,13 @@ const assertComponentSetIsNotUndefined = (componentSet: ComponentSet | undefined
   return componentSet;
 };
 
+const assertNoWildcardInDestructiveEntries = (mdEntry: MetadataTypeAndMetadataName): MetadataTypeAndMetadataName => {
+  if (mdEntry.metadataName.includes('*')) {
+    throw SfError.create({ message: 'Wildcards are not supported when providing destructive metadata entries' });
+  }
+  return mdEntry;
+};
+
 /** This is only for debug output of matched files based on the command flags.
  * It will log up to 20 file matches. */
 const logComponents = (logger: Logger, componentSet: ComponentSet): void => {

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/1-post-destructive-and-1-deployment.expected/testOutput/post1/classes/OneClass.cls

@@ -0,0 +1,5 @@
+public with sharing class OneClass {
+    public OneClass() {
+
+    }
+}

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/1-post-destructive-and-1-deployment.expected/testOutput/post1/classes/OneClass.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>59.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/1-post-destructive-and-1-deployment.expected/testOutput/post1/destructiveChangesPost.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>RedClass</members>
+        <name>ApexClass</name>
+    </types>
+    <version>60.0</version>
+</Package>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/1-post-destructive-and-1-deployment.expected/testOutput/post1/package.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>OneClass</members>
+        <name>ApexClass</name>
+    </types>
+    <version>60.0</version>
+</Package>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/1-post-destructive-and-no-deployment.expected/testOutput/post1-solo/destructiveChangesPost.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>RedClass</members>
+        <name>ApexClass</name>
+    </types>
+    <version>60.0</version>
+</Package>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/1-post-destructive-and-no-deployment.expected/testOutput/post1-solo/package.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <version>60.0</version>
+</Package>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/1-pre-destructive-and-1-deployment.expected/testOutput/pre1/classes/OneClass.cls

@@ -0,0 +1,5 @@
+public with sharing class OneClass {
+    public OneClass() {
+
+    }
+}

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/1-pre-destructive-and-1-deployment.expected/testOutput/pre1/classes/OneClass.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>59.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/1-pre-destructive-and-1-deployment.expected/testOutput/pre1/destructiveChangesPre.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>RedClass</members>
+        <name>ApexClass</name>
+    </types>
+    <version>60.0</version>
+</Package>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/1-pre-destructive-and-1-deployment.expected/testOutput/pre1/package.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>OneClass</members>
+        <name>ApexClass</name>
+    </types>
+    <version>60.0</version>
+</Package>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/2-post-destructive-and-2-deployments.expected/testOutput/post2/classes/OneClass.cls

@@ -0,0 +1,5 @@
+public with sharing class OneClass {
+    public OneClass() {
+
+    }
+}

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/2-post-destructive-and-2-deployments.expected/testOutput/post2/classes/OneClass.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>59.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/2-post-destructive-and-2-deployments.expected/testOutput/post2/classes/TwoClass.cls

@@ -0,0 +1,5 @@
+public with sharing class TwoClass {
+    public TwoClass() {
+
+    }
+}

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/2-post-destructive-and-2-deployments.expected/testOutput/post2/classes/TwoClass.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>59.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/2-post-destructive-and-2-deployments.expected/testOutput/post2/destructiveChangesPost.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>BlueClass</members>
+        <members>RedClass</members>
+        <name>ApexClass</name>
+    </types>
+    <version>60.0</version>
+</Package>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/2-post-destructive-and-2-deployments.expected/testOutput/post2/package.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>OneClass</members>
+        <members>TwoClass</members>
+        <name>ApexClass</name>
+    </types>
+    <version>60.0</version>
+</Package>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/2-pre-destructive-and-2-deployments.expected/testOutput/pre2/classes/OneClass.cls

@@ -0,0 +1,5 @@
+public with sharing class OneClass {
+    public OneClass() {
+
+    }
+}

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/2-pre-destructive-and-2-deployments.expected/testOutput/pre2/classes/OneClass.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>59.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/2-pre-destructive-and-2-deployments.expected/testOutput/pre2/classes/TwoClass.cls

@@ -0,0 +1,5 @@
+public with sharing class TwoClass {
+    public TwoClass() {
+
+    }
+}

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/2-pre-destructive-and-2-deployments.expected/testOutput/pre2/classes/TwoClass.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>59.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/2-pre-destructive-and-2-deployments.expected/testOutput/pre2/destructiveChangesPre.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>BlueClass</members>
+        <members>RedClass</members>
+        <name>ApexClass</name>
+    </types>
+    <version>60.0</version>
+</Package>

test/snapshot/sampleProjects/destructiveCompSets/__snapshots__/2-pre-destructive-and-2-deployments.expected/testOutput/pre2/package.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>OneClass</members>
+        <members>TwoClass</members>
+        <name>ApexClass</name>
+    </types>
+    <version>60.0</version>
+</Package>

test/snapshot/sampleProjects/destructiveCompSets/originalSource/classes/BlueClass.cls

@@ -0,0 +1,5 @@
+public with sharing class BlueClass {
+    public BlueClass() {
+
+    }
+}

test/snapshot/sampleProjects/destructiveCompSets/originalSource/classes/BlueClass.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>59.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

test/snapshot/sampleProjects/destructiveCompSets/originalSource/classes/OneClass.cls

@@ -0,0 +1,5 @@
+public with sharing class OneClass {
+    public OneClass() {
+
+    }
+}

test/snapshot/sampleProjects/destructiveCompSets/originalSource/classes/OneClass.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>59.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

test/snapshot/sampleProjects/destructiveCompSets/originalSource/classes/RedClass.cls

@@ -0,0 +1,5 @@
+public with sharing class RedClass {
+    public RedClass() {
+
+    }
+}

test/snapshot/sampleProjects/destructiveCompSets/originalSource/classes/RedClass.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>59.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

test/snapshot/sampleProjects/destructiveCompSets/originalSource/classes/TwoClass.cls

@@ -0,0 +1,5 @@
+public with sharing class TwoClass {
+    public TwoClass() {
+
+    }
+}

test/snapshot/sampleProjects/destructiveCompSets/originalSource/classes/TwoClass.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>59.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

test/snapshot/sampleProjects/destructiveCompSets/sfdx-project.json

@@ -0,0 +1,12 @@
+{
+  "name": "destructiveCompSetsProject",
+  "namespace": "",
+  "packageDirectories": [
+    {
+      "default": true,
+      "path": "force-app"
+    }
+  ],
+  "sfdcLoginUrl": "https://login.salesforce.com",
+  "sourceApiVersion": "52.0"
+}