prettier-plugin-xml-salesforce 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019-present Kevin Newton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# prettier-plugin-xml-salesforce
+
+<a href="https://www.npmjs.com/package/prettier-plugin-xml-salesforce">
+    <img alt="NPM Version" src="https://img.shields.io/npm/v/prettier-plugin-xml-salesforce.svg?style=flat-square">
+</a>
+<a href="https://github.com/prettier/prettier#badge">
+    <img alt="code style: prettier" src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square">
+</a>
+
+This plugin extends the functionality of the plugin `@prettier/plugin-xml`, providing custom formatting for Salesforce XML files, specifically handling `<flow>` elements and formula tags.
+
+This plugin also support (re-exports) all the standard features of `@prettier/plugin-xml`: [see documentation](https://github.com/prettier/plugin-xml#readme).
+
+## Problem Statement
+
+### Flow Tags
+
+Salesforce Permission Set XML files may contain `<flow>` tags which grant access to specific flows. These tags require to be formatted as single-line elements to maintain proper XML structure by design. Unfortunately, the default `@prettier/plugin-xml` does not handle this correctly, often breaking the intended single-line format.
+
+#### Example:
+
+```xml
+<PermissionSet>
+    <flow>SomeFlowAccess</flow>
+</PermissionSet>
+```
+
+easily becomes:
+
+```xml
+<PermissionSet>
+    <flow>
+        SomeFlowAccess;
+    </flow>
+</PermissionSet>
+```
+
+This breaks the deployment of the `*.permissionset-meta.xml` files.
+
+### Formulas
+
+Salesforce Formula Fields and Validation Rules often contain complex formula expressions. These formulas need to be formatted in a canonical way to ensure readability and maintainability. Unfortunately, there is no default formatting for these formulas, so they must be formatted manually or retriaved and left as-is by default.
+
+#### Example:
+
+```xml
+<CustomField>
+    <formula>AND(
+ISPICKVAL ( Status__c , "quot;Active"quot;),
+NOT( ISBLANK( End_Date__c) ))
+    </formula>
+</CustomField>
+```
+
+This plugin formats Salesforce formula tags in a canonical way:
+
+```xml
+<CustomField>
+    <formula>
+    AND(
+        ISPICKVAL(Status__c, "Active"),
+        NOT(ISBLANK(End_Date__c))
+    )
+    </formula>
+</CustomField>
+```
+
+This allows easier readability and maintainability of complex Salesforce formulas within XML files.
+
+#### Salesforce Limitations
+
+Formula fields in Salesforce have a character limit, and overly complex formulas may exceed this limit when formatted with additional line breaks and indentation. Developers should be aware of this limitation when using the plugin to format formula tags.
+
+| Limit           | Value           |
+| --------------- | --------------- |
+| Formula Field   | 4000 characters |
+| Validation Rule | 3900 characters |
+
+## Usage
+
+### Prettier Configuration
+
+In the Prettier configuration file (e.g., `.prettierrc`), you can enable the plugin and its custom options as follows:
+
+```json
+{
+    "plugins": ["prettier-plugin-xml-salesforce"],
+    "xmlFlowSingleLine": true,
+    "xmlFormulaFormat": true
+}
+```
+
+This plugin should be used instead of the default `@prettier/plugin-xml` when working with Salesforce XML files to ensure proper formatting of `<flow>` tags (in permission sets) and formula tags.
+
+### Prettier Options
+
+| Option            | Type    | Default | Description                                                      |
+| ----------------- | ------- | ------- | ---------------------------------------------------------------- |
+| xmlFlowSingleLine | boolean | true    | Format `<flow>...</flow>` as a single line and drop trailing `;` |
+| xmlFormulaFormat  | boolean | false   | Canonically format Salesforce formula tags                       |

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "prettier-plugin-xml-salesforce",
+    "description": "A Prettier plugin for formatting XML files in Salesforce projects",
+    "version": "1.0.0",
+    "author": {
+        "name": "Dmitry Kovalev",
+        "email": "kov.dmm@gmail.com",
+        "url": "https://github.com/kovdmm"
+    },
+    "license": "MIT",
+    "files": [
+        "src"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/kovdmm/prettier-plugin-xml-salesforce.git"
+    },
+    "keywords": [
+        "salesforce",
+        "formula-fields",
+        "validation-rules",
+        "prettier",
+        "xml",
+        "format",
+        "formatting"
+    ],
+    "scripts": {
+        "format": "prettier --write .",
+        "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+    },
+    "type": "module",
+    "exports": "./src/plugin.js",
+    "types": "./types/plugin.d.ts",
+    "dependencies": {
+        "@prettier/plugin-xml": "^3.4.2"
+    },
+    "peerDependencies": {
+        "prettier": "^3.0.0"
+    },
+    "devDependencies": {
+        "jest": "^30.5.2",
+        "prettier": "^3.9.8"
+    }
+}

package/src/plugin.js

@@ -0,0 +1,77 @@
+import * as xmlPlugin from "@prettier/plugin-xml";
+import { isFlowElement, normalizeFlowTagsInSource } from "./preprocessors/flow-tag.js";
+import { normalizeFormulasInSource } from "./preprocessors/formula.js";
+
+const xml = xmlPlugin.default ?? xmlPlugin;
+const baseXmlParser = xml.parsers?.xml;
+const baseXmlPrinter = xml.printers?.xml;
+
+/**
+ * Redefines the preprocess function to handle <flow> and formula tags according to the plugin's custom options.
+ * @param {string} text The source XML text to preprocess.
+ * @param {*} opts The Prettier options object.
+ * @returns {string} The preprocessed XML text.
+ */
+const preprocess = (text, opts) => {
+    const basePreprocess = baseXmlParser.preprocess;
+    let preprocessedText = typeof basePreprocess === "function" ? basePreprocess(text, opts) : text;
+    if (opts?.xmlFlowSingleLine) {
+        preprocessedText = normalizeFlowTagsInSource(preprocessedText);
+    }
+    if (opts?.xmlFormulaFormat) {
+        preprocessedText = normalizeFormulasInSource(preprocessedText, opts.printWidth);
+    }
+    return preprocessedText;
+};
+
+/**
+ * Redefines the embed function for <flow> elements to prevent the JS "flow" parser from being used.
+ *
+ * @prettier/plugin-xml embeds the element content using a Prettier parser that matches the tag name. For <flow> tags
+ * this accidentally triggers the built-in JS "flow" parser, which adds `;` and newlines, which breaks the intended
+ * single-line formatting for <flow> tags.
+ *
+ * @param {*} path The AST path for the current node. Should be an element node representing a <flow> tag.
+ * @param {*} opts The Prettier options object.
+ * @returns The embedded content for the <flow> element, or null to prevent the default embedding.
+ */
+const embed = (path, opts) => {
+    return opts?.xmlFlowSingleLine && isFlowElement(path.getValue()) ? null : baseXmlPrinter.embed?.(path, opts);
+};
+
+/** Exports the languages supported by the plugin, extending the default @prettier/plugin-xml languages. */
+export const languages = xml.languages;
+
+/** Extends the default @prettier/plugin-xml options with the plugin's custom XML options. */
+export const options = {
+    ...xml.options,
+    xmlFlowSingleLine: {
+        type: "boolean",
+        category: "XML",
+        default: true,
+        description: "Format <flow>...</flow> as a single line and drop trailing ';'. (Project-specific)",
+    },
+    xmlFormulaFormat: {
+        type: "boolean",
+        category: "XML",
+        default: false,
+        description: "Canonically format Salesforce formula tags (AND/OR expansion). (Project-specific)",
+    },
+};
+
+/** Extends the default @prettier/plugin-xml options with the plugin's custom XML options. */
+export const defaultOptions = {
+    ...xml.defaultOptions,
+    xmlFlowSingleLine: true,
+    xmlFormulaFormat: false,
+};
+
+/** Redefines the XML parser to use the custom preprocess function for handling <flow> and formula tags. */
+export const parsers = {
+    xml: { ...baseXmlParser, astFormat: "xml-salesforce", preprocess },
+};
+
+/** Redefines the XML printer to use the custom embed function for handling <flow> elements. */
+export const printers = {
+    "xml-salesforce": { ...baseXmlPrinter, embed },
+};

package/src/preprocessors/flow-tag.js

@@ -0,0 +1,22 @@
+// Project-specific handling for Salesforce <flow> tags in XML metadata.
+// In SF metadata <flow> contains a short plain-text value (e.g. a flow name) with no nested XML,
+// so it should be rendered on a single line without a trailing ';'.
+
+export const isFlowElement = (node) => {
+    return node?.name === "element" && typeof node.Name === "string" && node.Name.toLowerCase() === "flow";
+};
+
+/**
+ * Collapses every <flow>...</flow> tag onto a single line and drops a trailing ';'.
+ * Runs on the raw source BEFORE parsing/printing, so it never affects other tags.
+ * @param {string} sourceText The full XML metadata source.
+ * @returns {string} The source with <flow> tags normalized.
+ */
+export const normalizeFlowTagsInSource = (sourceText) => {
+    return sourceText.replaceAll(/<flow>\s*([^<]*?)\s*<\/flow>/g, (_, inner) => {
+        const cleaned = String(inner)
+            .replaceAll(/\s+|;\s*$/g, " ")
+            .trim();
+        return `<flow>${cleaned}</flow>`;
+    });
+};

package/src/preprocessors/formula.js

@@ -0,0 +1,474 @@
+// Canonical formatter for Salesforce formula expressions used inside XML metadata
+// (<errorConditionFormula>, <formula>, <validationFormula>).
+//
+// Style rules (project convention):
+//   - AND(...) / OR(...) are ALWAYS expanded: one argument per line, 4-space indent.
+//   - Infix boolean operators && / || are converted to AND() / OR().
+//   - The concat operator & is left untouched (NOT rewritten to +); long & / +
+//     chains wrap one operand per line when they exceed printWidth.
+//   - Other function calls stay on a single line unless they exceed printWidth.
+//   - Entities are unescaped to their literal characters, EXCEPT the structurally
+//     significant &lt; &gt; &amp; which stay escaped.
+
+const FORMULA_TAGS = ["errorConditionFormula", "formula", "validationFormula"];
+const INDENT_UNIT = "    ";
+const DEFAULT_PRINT_WIDTH = 120;
+
+//#region Entities
+const decodeEntities = (text) => {
+    return text.replaceAll(/&(lt|gt|amp|quot|apos|#\d+|#x[0-9a-fA-F]+);/g, (match, entity) => {
+        switch (entity) {
+            case "lt":
+                return "<";
+            case "gt":
+                return ">";
+            case "amp":
+                return "&";
+            case "quot":
+                return '"';
+            case "apos":
+                return "'";
+            default: {
+                const codePoint =
+                    entity[1] === "x" || entity[1] === "X"
+                        ? Number.parseInt(entity.slice(2), 16)
+                        : Number.parseInt(entity.slice(1), 10);
+                return Number.isNaN(codePoint) ? match : String.fromCodePoint(codePoint);
+            }
+        }
+    });
+};
+
+// Re-escape only the characters that must remain entities in XML text content.
+const encodeForXml = (text) => {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+};
+//#endregion
+
+//#region Tokenizer
+const TWO_CHAR_OPERATORS = new Set(["&&", "||", "<=", ">=", "<>", "!=", "=="]);
+const SINGLE_CHAR_OPERATORS = new Set(["=", "<", ">", "+", "-", "*", "/", "^", "&", "!"]);
+
+const tokenize = (input) => {
+    const tokens = [];
+    let index = 0;
+
+    while (index < input.length) {
+        const char = input[index];
+
+        if (/\s/.test(char)) {
+            index++;
+            continue;
+        }
+
+        if (char === "'" || char === '"') {
+            const quote = char;
+            let value = quote;
+            let cursor = index + 1;
+            while (cursor < input.length) {
+                if (input[cursor] === "\\" && cursor + 1 < input.length) {
+                    value += input[cursor] + input[cursor + 1];
+                    cursor += 2;
+                    continue;
+                }
+                value += input[cursor];
+                if (input[cursor] === quote) {
+                    cursor++;
+                    break;
+                }
+                cursor++;
+            }
+            tokens.push({ type: "string", value });
+            index = cursor;
+            continue;
+        }
+
+        if (/[0-9]/.test(char) || (char === "." && /[0-9]/.test(input[index + 1] ?? ""))) {
+            let value = "";
+            while (index < input.length && /[0-9.]/.test(input[index])) {
+                value += input[index];
+                index++;
+            }
+            tokens.push({ type: "number", value });
+            continue;
+        }
+
+        if (/[A-Za-z_$]/.test(char)) {
+            let value = "";
+            while (index < input.length && /[\w$.:]/.test(input[index])) {
+                value += input[index];
+                index++;
+            }
+            tokens.push({ type: "ident", value });
+            continue;
+        }
+
+        const twoChar = input.slice(index, index + 2);
+        if (TWO_CHAR_OPERATORS.has(twoChar)) {
+            tokens.push({ type: "op", value: twoChar });
+            index += 2;
+            continue;
+        }
+
+        if (char === "(") {
+            tokens.push({ type: "lparen" });
+            index++;
+            continue;
+        }
+        if (char === ")") {
+            tokens.push({ type: "rparen" });
+            index++;
+            continue;
+        }
+        if (char === ",") {
+            tokens.push({ type: "comma" });
+            index++;
+            continue;
+        }
+        if (SINGLE_CHAR_OPERATORS.has(char)) {
+            tokens.push({ type: "op", value: char });
+            index++;
+            continue;
+        }
+
+        throw new Error(`Unexpected character '${char}' at position ${index}`);
+    }
+
+    return tokens;
+};
+//#endregion
+
+//#region Parser
+const PRECEDENCE = {
+    "||": 1,
+    "&&": 2,
+    "=": 3,
+    "==": 3,
+    "<>": 3,
+    "!=": 3,
+    "<": 3,
+    ">": 3,
+    "<=": 3,
+    ">=": 3,
+    "&": 4,
+    "+": 5,
+    "-": 5,
+    "*": 6,
+    "/": 6,
+    "^": 7,
+};
+const RIGHT_ASSOCIATIVE = new Set(["^"]);
+
+const parse = (tokens) => {
+    let position = 0;
+    const peek = () => tokens[position];
+    const next = () => tokens[position++];
+    const expect = (type) => {
+        const token = next();
+        if (!token || token.type !== type) {
+            throw new Error(`Expected ${type}`);
+        }
+        return token;
+    };
+
+    const parseExpression = (minPrecedence) => {
+        let left = parseUnary();
+        while (true) {
+            const token = peek();
+            if (!token || token.type !== "op" || !(token.value in PRECEDENCE)) {
+                break;
+            }
+            const precedence = PRECEDENCE[token.value];
+            if (precedence < minPrecedence) {
+                break;
+            }
+            next();
+            const nextMinPrecedence = RIGHT_ASSOCIATIVE.has(token.value) ? precedence : precedence + 1;
+            const right = parseExpression(nextMinPrecedence);
+            left = { type: "Binary", op: token.value, left, right };
+        }
+        return left;
+    };
+
+    const parseUnary = () => {
+        const token = peek();
+        if (token && token.type === "op" && (token.value === "-" || token.value === "!" || token.value === "+")) {
+            next();
+            return { type: "Unary", op: token.value, operand: parseUnary() };
+        }
+        return parsePrimary();
+    };
+
+    const parsePrimary = () => {
+        const token = peek();
+        if (!token) {
+            throw new Error("Unexpected end of formula");
+        }
+        if (token.type === "lparen") {
+            next();
+            const expr = parseExpression(0);
+            expect("rparen");
+            return { type: "Group", expr };
+        }
+        if (token.type === "number") {
+            next();
+            return { type: "Number", value: token.value };
+        }
+        if (token.type === "string") {
+            next();
+            return { type: "String", value: token.value };
+        }
+        if (token.type === "ident") {
+            next();
+            if (peek() && peek().type === "lparen") {
+                next();
+                const args = [];
+                if (peek() && peek().type !== "rparen") {
+                    args.push(parseExpression(0));
+                    while (peek() && peek().type === "comma") {
+                        next();
+                        args.push(parseExpression(0));
+                    }
+                }
+                expect("rparen");
+                return { type: "Call", name: token.value, args };
+            }
+            return { type: "Ident", value: token.value };
+        }
+        throw new Error(`Unexpected token ${JSON.stringify(token)}`);
+    };
+
+    const ast = parseExpression(0);
+    if (position !== tokens.length) {
+        throw new Error("Unexpected trailing tokens");
+    }
+    return ast;
+};
+//#endregion
+
+//#region Transform (&& -> AND, || -> OR)
+const ATOMIC_TYPES = new Set(["Call", "Ident", "Number", "String"]);
+
+const flattenBoolean = (node, name, out) => {
+    if (node.type === "Call" && node.fromOperator && node.name === name) {
+        out.push(...node.args);
+    } else {
+        out.push(node);
+    }
+};
+
+// Used only by the disabled structural-IF simplification below; re-enable together.
+// const isBooleanLiteral = (node, value) => node.type === "Ident" && node.value === value;
+
+// Bare identifiers that are language constants and get normalized to upper case.
+const UPPERCASE_CONSTANTS = new Set(["TRUE", "FALSE", "NULL"]);
+
+const transform = (node) => {
+    switch (node.type) {
+        case "Binary": {
+            const left = transform(node.left);
+            const right = transform(node.right);
+            if (node.op === "&&" || node.op === "||") {
+                const name = node.op === "&&" ? "AND" : "OR";
+                const args = [];
+                flattenBoolean(left, name, args);
+                flattenBoolean(right, name, args);
+                return { type: "Call", name, args, fromOperator: true };
+            }
+            // Normalize operators to the project's preferred spelling.
+            // The concat operator & is kept as-is: rewriting it to + would change
+            // null handling for formulas with formulaTreatBlanksAs = BlankAsBlank.
+            const op = node.op === "<>" ? "!=" : node.op;
+            return { type: "Binary", op, left, right };
+        }
+        case "Unary": {
+            const operand = transform(node.operand);
+            // Logical negation ! becomes the NOT() function.
+            if (node.op === "!") {
+                return { type: "Call", name: "NOT", args: [operand] };
+            }
+            return { type: "Unary", op: node.op, operand };
+        }
+        case "Group": {
+            let expr = transform(node.expr);
+            // Collapse redundant nested parentheses: ((X)) -> (X), (((X))) -> (X).
+            while (expr.type === "Group") {
+                expr = expr.expr;
+            }
+            // Parentheses around an atomic node are redundant once operators are calls.
+            return ATOMIC_TYPES.has(expr.type) ? expr : { type: "Group", expr };
+        }
+        case "Call": {
+            const args = node.args.map(transform);
+            const name = node.name.toUpperCase();
+            // FUTURE EXTENSION: structural IF simplification, disabled for now.
+            // IF(x, TRUE, FALSE) -> x  and  IF(x, FALSE, TRUE) -> NOT(x) are only
+            // safe when x can never evaluate to null: IF() treats a null condition
+            // as false, whereas a bare x / NOT(x) propagates the null. The formatter
+            // can't prove x is non-null, so it leaves these expressions untouched.
+            // To re-enable, restore isBooleanLiteral above and this block:
+            //
+            // if (name === "IF" && args.length === 3) {
+            //     const [condition, thenBranch, elseBranch] = args;
+            //     if (isBooleanLiteral(thenBranch, "TRUE") && isBooleanLiteral(elseBranch, "FALSE")) {
+            //         return condition;
+            //     }
+            //     if (isBooleanLiteral(thenBranch, "FALSE") && isBooleanLiteral(elseBranch, "TRUE")) {
+            //         return { type: "Call", name: "NOT", args: [condition] };
+            //     }
+            // }
+            return { type: "Call", name, args };
+        }
+        case "Ident": {
+            const upper = node.value.toUpperCase();
+            return UPPERCASE_CONSTANTS.has(upper) ? { type: "Ident", value: upper } : node;
+        }
+        default:
+            return node;
+    }
+};
+//#endregion
+
+//#region Printer
+const renderInline = (node) => {
+    switch (node.type) {
+        case "Call":
+            return `${node.name}(${node.args.map(renderInline).join(", ")})`;
+        case "Binary":
+            return `${renderInline(node.left)} ${node.op} ${renderInline(node.right)}`;
+        case "Unary":
+            return `${node.op}${renderInline(node.operand)}`;
+        case "Group":
+            return `(${renderInline(node.expr)})`;
+        default:
+            return node.value;
+    }
+};
+
+const containsBooleanCall = (node) => {
+    switch (node.type) {
+        case "Call":
+            return node.name === "AND" || node.name === "OR" || node.args.some(containsBooleanCall);
+        case "Binary":
+            return containsBooleanCall(node.left) || containsBooleanCall(node.right);
+        case "Unary":
+            return containsBooleanCall(node.operand);
+        case "Group":
+            return containsBooleanCall(node.expr);
+        default:
+            return false;
+    }
+};
+
+const BREAKABLE_BINARY_OPS = new Set(["+", "&"]);
+
+const flattenBinaryChain = (node) => {
+    const { op } = node;
+    const parts = [];
+    const walk = (current) => {
+        if (current.type === "Binary" && current.op === op) {
+            walk(current.left);
+            parts.push(current.right);
+        } else {
+            parts.push(current);
+        }
+    };
+    walk(node);
+    return parts;
+};
+
+const createRenderer = (baseIndent, printWidth) => {
+    const indentAt = (level) => baseIndent + INDENT_UNIT.repeat(level);
+    const columnAt = (level) => baseIndent.length + level * INDENT_UNIT.length;
+
+    const render = (node, level, startColumnOverride) => {
+        const startColumn = startColumnOverride ?? columnAt(level);
+
+        if (node.type === "Call") {
+            const inline = renderInline(node);
+            const isBoolean = node.name === "AND" || node.name === "OR";
+            const mustBreak =
+                isBoolean || node.args.some(containsBooleanCall) || startColumn + inline.length > printWidth;
+            if (!mustBreak) {
+                return inline;
+            }
+            const args = node.args.map((arg) => indentAt(level + 1) + render(arg, level + 1)).join(",\n");
+            return `${node.name}(\n${args}\n${indentAt(level)})`;
+        }
+
+        if (node.type === "Binary") {
+            const inline = renderInline(node);
+            const fits = !containsBooleanCall(node) && startColumn + inline.length <= printWidth;
+            if (fits) {
+                return inline;
+            }
+            if (BREAKABLE_BINARY_OPS.has(node.op)) {
+                const parts = flattenBinaryChain(node);
+                return parts
+                    .map((part, index) => {
+                        const rendered = render(part, level, index === 0 ? startColumn : undefined);
+                        const prefix = index === 0 ? "" : indentAt(level);
+                        const suffix = index < parts.length - 1 ? ` ${node.op}` : "";
+                        return `${prefix}${rendered}${suffix}`;
+                    })
+                    .join("\n");
+            }
+            // Non-breakable operator that still overflows: recurse so nested chains can expand.
+            const left = render(node.left, level, startColumn);
+            const right = render(node.right, level);
+            return `${left} ${node.op} ${right}`;
+        }
+
+        return renderInline(node);
+    };
+
+    return render;
+};
+//#endregion
+
+/**
+ * Formats a single formula expression string according to the project convention.
+ * @param {string} source Decoded formula text (no XML entities for < > &).
+ * @param {string} baseIndent Leading indentation of the owning tag.
+ * @param {number} printWidth Maximum line width before non-boolean calls break.
+ * @param {number} [topStartColumn] Column where the top-level expression begins (tag-aware).
+ * @returns {string} The formatted formula (single- or multi-line, without tags).
+ */
+export const formatFormulaExpression = (source, baseIndent, printWidth, topStartColumn) => {
+    const ast = transform(parse(tokenize(source)));
+    const render = createRenderer(baseIndent, printWidth);
+    return render(ast, 0, topStartColumn);
+};
+
+/**
+ * Rewrites every formula tag in the given XML source with a canonically formatted body.
+ * Parse failures leave the original tag untouched so malformed input is never corrupted.
+ * @param {string} source The full XML metadata source.
+ * @param {number} [printWidth] Maximum line width (defaults to 120).
+ * @returns {string} The source with formula tags reformatted.
+ */
+export const normalizeFormulasInSource = (source, printWidth = DEFAULT_PRINT_WIDTH) => {
+    const tagPattern = new RegExp(`^([ \\t]*)<(${FORMULA_TAGS.join("|")})>([\\s\\S]*?)</\\2>`, "gm");
+    return source.replace(tagPattern, (fullMatch, baseIndent, tag, rawInner) => {
+        try {
+            const decoded = decodeEntities(rawInner.trim());
+            if (decoded === "") {
+                return fullMatch;
+            }
+            const openTagLength = tag.length + 2; // "<" + tag + ">"
+            const topStartColumn = baseIndent.length + openTagLength;
+            const body = formatFormulaExpression(decoded, baseIndent, printWidth, topStartColumn);
+            const encoded = encodeForXml(body);
+            // Multi-line formulas get a blank-of-newline before and after the body for readability;
+            // single-line formulas stay inline. xmlWhitespaceSensitivity:preserve keeps these newlines.
+            if (encoded.includes("\n")) {
+                return `${baseIndent}<${tag}>\n${baseIndent}${encoded}\n${baseIndent}</${tag}>`;
+            }
+            return `${baseIndent}<${tag}>${encoded}</${tag}>`;
+        } catch {
+            return fullMatch;
+        }
+    });
+};
+
+export const __testables = { decodeEntities, encodeForXml, tokenize, parse, transform };