refactor: eliminate code duplication between parseXml and parseXmlForDiff

- Refactored parseXml to accept optional ParseXmlOptions parameter
- parseXmlForDiff now delegates to parseXml with processEntities: false
- Added explanatory comment in multiApplyDiffTool.ts about why parseXmlForDiff is used
- Improved JSDoc documentation with specific use cases for parseXmlForDiff

This maintains backward compatibility while eliminating code duplication.
parseXml continues to be used for general XML parsing (file reads, follow-up questions),
while parseXmlForDiff is specifically for diff operations where entity processing must be disabled.

Author: daniel-lxs

src/core/tools/multiApplyDiffTool.ts

@@ -108,6 +108,9 @@ export async function applyDiffTool(
 	if (argsXmlTag) {
 		// Parse file entries from XML (new way)
 		try {
+			// IMPORTANT: We use parseXmlForDiff here instead of parseXml to prevent HTML entity decoding
+			// This ensures exact character matching when comparing parsed content against original file content
+			// Without this, special characters like & would be decoded to & causing diff mismatches
 			const parsed = parseXmlForDiff(argsXmlTag, ["file.diff.content"]) as ParsedXmlResult
 			const files = Array.isArray(parsed.file) ? parsed.file : [parsed.file].filter(Boolean)
 

src/utils/xml.ts

@@ -1,20 +1,36 @@
 import { XMLParser } from "fast-xml-parser"
 
+/**
+ * Options for XML parsing
+ */
+interface ParseXmlOptions {
+	/**
+	 * Whether to process HTML entities (e.g., & to &).
+	 * Default: true for general parsing, false for diff operations
+	 */
+	processEntities?: boolean
+}
+
 /**
  * Parses an XML string into a JavaScript object
  * @param xmlString The XML string to parse
+ * @param stopNodes Optional array of node names to stop parsing at
+ * @param options Optional parsing options
  * @returns Parsed JavaScript object representation of the XML
  * @throws Error if the XML is invalid or parsing fails
  */
-export function parseXml(xmlString: string, stopNodes?: string[]): unknown {
+export function parseXml(xmlString: string, stopNodes?: string[], options?: ParseXmlOptions): unknown {
 	const _stopNodes = stopNodes ?? []
+	const processEntities = options?.processEntities ?? true
+
 	try {
 		const parser = new XMLParser({
 			ignoreAttributes: false,
 			attributeNamePrefix: "@_",
 			parseAttributeValue: false,
 			parseTagValue: false,
 			trimValues: true,
+			processEntities,
 			stopNodes: _stopNodes,
 		})
 
@@ -30,27 +46,18 @@ export function parseXml(xmlString: string, stopNodes?: string[]): unknown {
  * Parses an XML string for diffing purposes, ensuring no HTML entities are decoded.
  * This is a specialized version of parseXml to be used exclusively by diffing tools
  * to prevent mismatches caused by entity processing.
+ *
+ * Use this instead of parseXml when:
+ * - Comparing parsed content against original file content
+ * - Performing diff operations where exact character matching is required
+ * - Processing XML that will be used in search/replace operations
+ *
  * @param xmlString The XML string to parse
+ * @param stopNodes Optional array of node names to stop parsing at
  * @returns Parsed JavaScript object representation of the XML
  * @throws Error if the XML is invalid or parsing fails
  */
 export function parseXmlForDiff(xmlString: string, stopNodes?: string[]): unknown {
-	const _stopNodes = stopNodes ?? []
-	try {
-		const parser = new XMLParser({
-			ignoreAttributes: false,
-			attributeNamePrefix: "@_",
-			parseAttributeValue: false,
-			parseTagValue: false,
-			trimValues: true,
-			processEntities: false, // Do not process HTML entities, keep them as is
-			stopNodes: _stopNodes,
-		})
-
-		return parser.parse(xmlString)
-	} catch (error) {
-		// Enhance error message for better debugging
-		const errorMessage = error instanceof Error ? error.message : "Unknown error"
-		throw new Error(`Failed to parse XML: ${errorMessage}`)
-	}
+	// Delegate to parseXml with processEntities disabled
+	return parseXml(xmlString, stopNodes, { processEntities: false })
 }