fix: preserve xml comments in decomposed files (#1288)

* fix: preserve xml comments in decomposed files

* test: add gender field for snapshot

* fix: hacky correction to xml comment newline/indent behavior

src/common/constants.ts

@@ -11,3 +11,4 @@ export const META_XML_SUFFIX = '-meta.xml';
 export const XML_DECL = '<?xml version="1.0" encoding="UTF-8"?>\n';
 export const XML_NS_URL = 'http://soap.sforce.com/2006/04/metadata';
 export const XML_NS_KEY = '@_xmlns';
+export const XML_COMMENT_PROP_NAME = '#xml__comment';

src/convert/streams.ts

@@ -15,7 +15,7 @@ import { XMLBuilder } from 'fast-xml-parser';
 import { Logger } from '@salesforce/core';
 import { SourceComponent } from '../resolve/sourceComponent';
 import { SourcePath } from '../common/types';
-import { XML_DECL } from '../common/constants';
+import { XML_COMMENT_PROP_NAME, XML_DECL } from '../common/constants';
 import { ComponentSet } from '../collections/componentSet';
 import { RegistryAccess } from '../registry/registryAccess';
 import { ensureFileExists } from '../utils/fileSystemHandler';
@@ -255,15 +255,18 @@ export class JsToXml extends Readable {
       indentBy: '    ',
       ignoreAttributes: false,
       cdataPropName: '__cdata',
+      commentPropName: XML_COMMENT_PROP_NAME,
     });
-
     const builtXml = String(builder.build(this.xmlObject));
-    const xmlContent = XML_DECL.concat(handleSpecialEntities(builtXml));
+    const xmlContent = correctComments(XML_DECL.concat(handleSpecialEntities(builtXml)));
     this.push(xmlContent);
     this.push(null);
   }
 }
 
+/** xmlBuilder likes to add newline and indent before/after the comment (hypothesis: it uses `<` as a hint to newlint/indent) */
+const correctComments = (xml: string): string =>
+  xml.includes('<!--') ? xml.replace(/\s+<!--(.*?)-->\s+/g, '<!--$1-->') : xml;
 /**
  * use this function to handle special html entities.
  * XmlBuilder will otherwise replace ex: `&#160;` with `'&amp;#160;'` (escape the &)

src/resolve/sourceComponent.ts

@@ -9,6 +9,7 @@ import { Messages, SfError } from '@salesforce/core';
 import { XMLParser, XMLValidator } from 'fast-xml-parser';
 import { get, getString, JsonMap } from '@salesforce/ts-types';
 import { ensureArray } from '@salesforce/kit';
+import { XML_COMMENT_PROP_NAME } from '../common/constants';
 import { getXmlElement } from '../utils/decomposed';
 import { baseName, baseWithoutSuffixes, parseMetadataXml, calculateRelativePath } from '../utils/path';
 import { replacementIterations } from '../convert/replacements';
@@ -271,6 +272,7 @@ export class SourceComponent implements MetadataComponent {
       cdataPropName: '__cdata',
       ignoreDeclaration: true,
       numberParseOptions: { leadingZeros: false, hex: false },
+      commentPropName: XML_COMMENT_PROP_NAME,
     });
     const parsed = parser.parse(String(contents)) as T;
     const [firstElement] = Object.keys(parsed);

test/snapshot/sampleProjects/xmlComments/__snapshots__/verify-md-files.expected/objectTranslations/Contact-en_US.objectTranslation

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomObjectTranslation xmlns="http://soap.sforce.com/2006/04/metadata">
+    <gender></gender>
+    <fields>
+        <help><!-- Please choose an option --></help>
+        <label><!-- Example --></label>
+        <name>Example__c</name>
+        <picklistValues>
+            <masterLabel>One</masterLabel>
+            <translation><!-- One --></translation>
+        </picklistValues>
+        <picklistValues>
+            <masterLabel>Two</masterLabel>
+            <translation><!-- Two --></translation>
+        </picklistValues>
+    </fields>
+</CustomObjectTranslation>