@wirebench/engine 2.1.1

package/dist/xml/namespaces.js

@@ -0,0 +1,60 @@
+/**
+ * XML namespace URIs used across WSDL, SOAP, XSD, WS-Security, WS-Addressing
+ * and WS-Policy. Centralizing these avoids typos scattered through the
+ * codebase and gives every consumer the same canonical values.
+ */
+export const NS = {
+    WSDL: 'http://schemas.xmlsoap.org/wsdl/',
+    WSDL_SOAP11: 'http://schemas.xmlsoap.org/wsdl/soap/',
+    WSDL_SOAP12: 'http://schemas.xmlsoap.org/wsdl/soap12/',
+    WSDL_HTTP: 'http://schemas.xmlsoap.org/wsdl/http/',
+    WSDL_MIME: 'http://schemas.xmlsoap.org/wsdl/mime/',
+    SOAP11_ENV: 'http://schemas.xmlsoap.org/soap/envelope/',
+    SOAP11_ENC: 'http://schemas.xmlsoap.org/soap/encoding/',
+    SOAP12_ENV: 'http://www.w3.org/2003/05/soap-envelope',
+    SOAP12_ENC: 'http://www.w3.org/2003/05/soap-encoding',
+    XSD: 'http://www.w3.org/2001/XMLSchema',
+    XSI: 'http://www.w3.org/2001/XMLSchema-instance',
+    XML: 'http://www.w3.org/XML/1998/namespace',
+    XOP: 'http://www.w3.org/2004/08/xop/include',
+    XMLMIME: 'http://www.w3.org/2005/05/xmlmime',
+    WSSE: 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd',
+    WSU: 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd',
+    DS: 'http://www.w3.org/2000/09/xmldsig#',
+    XENC: 'http://www.w3.org/2001/04/xmlenc#',
+    WSA_200508: 'http://www.w3.org/2005/08/addressing',
+    WSA_200408: 'http://schemas.xmlsoap.org/ws/2004/08/addressing',
+    WSAW: 'http://www.w3.org/2006/05/addressing/wsdl',
+    WSAM: 'http://www.w3.org/2007/05/addressing/metadata',
+    WSAP_2004: 'http://schemas.xmlsoap.org/ws/2004/08/addressing/policy',
+    WSP: 'http://www.w3.org/ns/ws-policy',
+    WSP_2004: 'http://schemas.xmlsoap.org/ws/2004/09/policy',
+};
+/** Conventional XML prefix for each namespace in {@link NS}. */
+export const PREFIX = {
+    WSDL: 'wsdl',
+    WSDL_SOAP11: 'soap',
+    WSDL_SOAP12: 'soap12',
+    WSDL_HTTP: 'http',
+    WSDL_MIME: 'mime',
+    SOAP11_ENV: 'soapenv',
+    SOAP11_ENC: 'soapenc',
+    SOAP12_ENV: 'soapenv',
+    SOAP12_ENC: 'soapenc',
+    XSD: 'xs',
+    XSI: 'xsi',
+    XML: 'xml',
+    XOP: 'xop',
+    XMLMIME: 'xmlmime',
+    WSSE: 'wsse',
+    WSU: 'wsu',
+    DS: 'ds',
+    XENC: 'xenc',
+    WSA_200508: 'wsa',
+    WSA_200408: 'wsa',
+    WSAW: 'wsaw',
+    WSAM: 'wsam',
+    WSAP_2004: 'wsap',
+    WSP: 'wsp',
+    WSP_2004: 'wsp',
+};

package/dist/xml/parse.d.ts

@@ -0,0 +1,79 @@
+import type { Document, Node } from '@xmldom/xmldom';
+/** Options accepted by {@link parseXml} and {@link parseXmlDetailed}. */
+export interface ParseXmlOptions {
+    /** A human-readable origin for the document (file path or URL), included in error details. */
+    readonly location?: string;
+}
+/**
+ * A non-fatal problem xmldom reported while parsing (a `warning` or `error`
+ * level `onError` call). The document was still produced despite this
+ * problem; only `fatalError` aborts parsing entirely (see {@link parseXmlDetailed}).
+ */
+export interface XmlProblem {
+    readonly level: 'warning' | 'error';
+    readonly message: string;
+    readonly line?: number;
+    readonly column?: number;
+    readonly location?: string;
+}
+/** The result of classifying a single xmldom `onError` callback invocation. */
+export type ParseEventClassification = {
+    readonly fatal: true;
+} | {
+    readonly fatal: false;
+    readonly level: 'warning' | 'error';
+};
+/**
+ * Determines whether a raw xmldom `onError` level is fatal. Only xmldom's
+ * `fatalError` level aborts parsing; `warning` and `error` are reported
+ * problems that xmldom still recovers from, producing a `Document`.
+ *
+ * Exported as a pure function so the level-dispatch logic can be unit-tested
+ * directly even if no non-fatal xmldom input is available in a given
+ * environment.
+ *
+ * @param level the raw level string xmldom passed to `onError`
+ * @param message the message xmldom passed to `onError` (unused by the classification itself;
+ *   accepted so the exported signature matches the full `onError` payload callers reason about)
+ */
+export declare function classifyParseEvent(level: string, message: string): ParseEventClassification;
+/**
+ * Parses an XML string into a DOM `Document` using `@xmldom/xmldom`, and
+ * collects every warning/error xmldom reports along the way (without
+ * printing anything to the console).
+ *
+ * Only a `fatalError` from xmldom aborts parsing and results in a thrown
+ * {@link WirebenchError}; lesser `warning`/`error` levels are collected into
+ * `problems` and the resulting `Document` (which xmldom still produces
+ * despite them) is returned.
+ *
+ * @param text the XML source to parse
+ * @param options.location a human-readable origin (file path/URL) included in the thrown error's details and in each collected problem
+ * @returns the parsed `Document` plus any non-fatal problems xmldom reported
+ * @throws {WirebenchError} with code `xml-parse-error` if xmldom reports a `fatalError`
+ */
+export declare function parseXmlDetailed(text: string, options?: ParseXmlOptions): {
+    document: Document;
+    problems: readonly XmlProblem[];
+};
+/**
+ * Parses an XML string into a DOM `Document` using `@xmldom/xmldom`.
+ *
+ * Thin wrapper over {@link parseXmlDetailed} that discards non-fatal
+ * `problems` and returns only the `Document`. Never writes to the console.
+ *
+ * @param text the XML source to parse
+ * @param options.location a human-readable origin (file path/URL) included in the thrown error's details
+ * @returns the parsed `Document`
+ * @throws {WirebenchError} with code `xml-parse-error` if xmldom reports a `fatalError`
+ */
+export declare function parseXml(text: string, options?: ParseXmlOptions): Document;
+/**
+ * Reads the source position xmldom recorded for `node` when it was parsed
+ * with `locator: true`. Returns `undefined` for nodes without position data
+ * (e.g. nodes created programmatically rather than parsed).
+ */
+export declare function getPosition(node: Node): {
+    line: number;
+    column: number;
+} | undefined;

package/dist/xml/parse.js

@@ -0,0 +1,109 @@
+import { DOMParser } from '@xmldom/xmldom';
+import { WirebenchError } from '../errors.js';
+/**
+ * Determines whether a raw xmldom `onError` level is fatal. Only xmldom's
+ * `fatalError` level aborts parsing; `warning` and `error` are reported
+ * problems that xmldom still recovers from, producing a `Document`.
+ *
+ * Exported as a pure function so the level-dispatch logic can be unit-tested
+ * directly even if no non-fatal xmldom input is available in a given
+ * environment.
+ *
+ * @param level the raw level string xmldom passed to `onError`
+ * @param message the message xmldom passed to `onError` (unused by the classification itself;
+ *   accepted so the exported signature matches the full `onError` payload callers reason about)
+ */
+export function classifyParseEvent(level, message) {
+    void message;
+    if (level === 'fatalError') {
+        return { fatal: true };
+    }
+    // xmldom only ever reports 'warning', 'error', or 'fatalError'; treat anything
+    // else defensively as a non-fatal 'error' rather than silently dropping it.
+    return { fatal: false, level: level === 'warning' ? 'warning' : 'error' };
+}
+/**
+ * Parses an XML string into a DOM `Document` using `@xmldom/xmldom`, and
+ * collects every warning/error xmldom reports along the way (without
+ * printing anything to the console).
+ *
+ * Only a `fatalError` from xmldom aborts parsing and results in a thrown
+ * {@link WirebenchError}; lesser `warning`/`error` levels are collected into
+ * `problems` and the resulting `Document` (which xmldom still produces
+ * despite them) is returned.
+ *
+ * @param text the XML source to parse
+ * @param options.location a human-readable origin (file path/URL) included in the thrown error's details and in each collected problem
+ * @returns the parsed `Document` plus any non-fatal problems xmldom reported
+ * @throws {WirebenchError} with code `xml-parse-error` if xmldom reports a `fatalError`
+ */
+export function parseXmlDetailed(text, options) {
+    const problems = [];
+    let fatal;
+    const parser = new DOMParser({
+        locator: true,
+        onError: (level, message, context) => {
+            const locator = context?.locator;
+            const classification = classifyParseEvent(level, message);
+            if (classification.fatal) {
+                fatal = { message, line: locator?.lineNumber, column: locator?.columnNumber };
+                // Throwing here both stops the parser immediately and prevents xmldom's
+                // default console output for this (fatal) event.
+                throw new Error(message);
+            }
+            problems.push({
+                level: classification.level,
+                message,
+                ...(locator?.lineNumber !== undefined ? { line: locator.lineNumber } : {}),
+                ...(locator?.columnNumber !== undefined ? { column: locator.columnNumber } : {}),
+                ...(options?.location !== undefined ? { location: options.location } : {}),
+            });
+        },
+    });
+    try {
+        const document = parser.parseFromString(text, 'application/xml');
+        return { document, problems };
+    }
+    catch (cause) {
+        // `onError` above only throws for a fatal event, which always populates
+        // `fatal` first. The fallback only guards against a hypothetical error
+        // thrown by `parseFromString` itself outside of `onError`.
+        /* v8 ignore next */
+        const fallbackMessage = fatal?.message ?? 'Failed to parse XML';
+        throw new WirebenchError('xml-parse-error', fallbackMessage, {
+            cause,
+            details: {
+                location: options?.location,
+                line: fatal?.line,
+                column: fatal?.column,
+                message: fallbackMessage,
+            },
+        });
+    }
+}
+/**
+ * Parses an XML string into a DOM `Document` using `@xmldom/xmldom`.
+ *
+ * Thin wrapper over {@link parseXmlDetailed} that discards non-fatal
+ * `problems` and returns only the `Document`. Never writes to the console.
+ *
+ * @param text the XML source to parse
+ * @param options.location a human-readable origin (file path/URL) included in the thrown error's details
+ * @returns the parsed `Document`
+ * @throws {WirebenchError} with code `xml-parse-error` if xmldom reports a `fatalError`
+ */
+export function parseXml(text, options) {
+    return parseXmlDetailed(text, options).document;
+}
+/**
+ * Reads the source position xmldom recorded for `node` when it was parsed
+ * with `locator: true`. Returns `undefined` for nodes without position data
+ * (e.g. nodes created programmatically rather than parsed).
+ */
+export function getPosition(node) {
+    const located = node;
+    if (located.lineNumber === undefined || located.columnNumber === undefined) {
+        return undefined;
+    }
+    return { line: located.lineNumber, column: located.columnNumber };
+}

package/dist/xml/positions.d.ts

@@ -0,0 +1,26 @@
+/** A 1-based line/column position within a text document. */
+export interface LinePosition {
+    readonly line: number;
+    readonly column: number;
+}
+/**
+ * Converts between character offsets and 1-based line/column positions for a
+ * fixed text document. Line starts are indexed once at construction time so
+ * repeated lookups (e.g. reporting many diagnostics) are cheap.
+ *
+ * Handles both `\n` and `\r\n` line endings: a `\r\n` pair is treated as the
+ * line terminator, so the character immediately after it starts the next
+ * line at column 1.
+ */
+export declare class LineIndex {
+    /** Offset of the first character of each line, in ascending order. */
+    private readonly lineStarts;
+    private readonly length;
+    constructor(text: string);
+    /** Converts a character offset (0-based) into a 1-based line/column position. */
+    offsetToPosition(offset: number): LinePosition;
+    /** Converts a 1-based line/column position back into a character offset. */
+    positionToOffset(line: number, column: number): number;
+    /** Binary search for the last line whose start is <= offset. */
+    private findLineIndex;
+}

package/dist/xml/positions.js

@@ -0,0 +1,71 @@
+/**
+ * Converts between character offsets and 1-based line/column positions for a
+ * fixed text document. Line starts are indexed once at construction time so
+ * repeated lookups (e.g. reporting many diagnostics) are cheap.
+ *
+ * Handles both `\n` and `\r\n` line endings: a `\r\n` pair is treated as the
+ * line terminator, so the character immediately after it starts the next
+ * line at column 1.
+ */
+export class LineIndex {
+    /** Offset of the first character of each line, in ascending order. */
+    lineStarts;
+    length;
+    constructor(text) {
+        this.length = text.length;
+        const starts = [0];
+        for (let i = 0; i < text.length; i += 1) {
+            const ch = text[i];
+            if (ch === '\n') {
+                starts.push(i + 1);
+            }
+            else if (ch === '\r') {
+                const next = text[i + 1];
+                const lineStart = next === '\n' ? i + 2 : i + 1;
+                starts.push(lineStart);
+                if (next === '\n') {
+                    i += 1;
+                }
+            }
+        }
+        this.lineStarts = starts;
+    }
+    /** Converts a character offset (0-based) into a 1-based line/column position. */
+    offsetToPosition(offset) {
+        const clamped = Math.max(0, Math.min(offset, this.length));
+        const lineIndex = this.findLineIndex(clamped);
+        // `lineIndex` always comes from `findLineIndex`, which returns an index within
+        // `lineStarts` bounds; the `?? 0` only satisfies `noUncheckedIndexedAccess`.
+        /* v8 ignore next */
+        const lineStart = this.lineStarts[lineIndex] ?? 0;
+        return { line: lineIndex + 1, column: clamped - lineStart + 1 };
+    }
+    /** Converts a 1-based line/column position back into a character offset. */
+    positionToOffset(line, column) {
+        const lineIndex = Math.max(0, Math.min(line - 1, this.lineStarts.length - 1));
+        // `lineIndex` is clamped to `[0, lineStarts.length - 1]` above, so it is
+        // always in bounds; the `?? 0` only satisfies `noUncheckedIndexedAccess`.
+        /* v8 ignore next */
+        const lineStart = this.lineStarts[lineIndex] ?? 0;
+        return lineStart + (column - 1);
+    }
+    /** Binary search for the last line whose start is <= offset. */
+    findLineIndex(offset) {
+        let low = 0;
+        let high = this.lineStarts.length - 1;
+        while (low < high) {
+            const mid = Math.ceil((low + high) / 2);
+            // `mid` is always within `[low, high]` here, so it is in bounds; the `?? 0`
+            // only satisfies `noUncheckedIndexedAccess`.
+            /* v8 ignore next */
+            const start = this.lineStarts[mid] ?? 0;
+            if (start <= offset) {
+                low = mid;
+            }
+            else {
+                high = mid - 1;
+            }
+        }
+        return low;
+    }
+}

package/dist/xml/pretty.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A token-based XML pretty printer. Unlike a DOM round trip, this tolerates
+ * slightly malformed input (it never throws) and preserves everything a DOM
+ * serializer would normally lose: comments, CDATA sections, processing
+ * instructions, the XML declaration, DOCTYPE, attribute order/quoting and
+ * entity references.
+ */
+/** Options for {@link formatXml}. */
+export interface FormatXmlOptions {
+    /** Indentation unit per nesting level. Defaults to three spaces. */
+    readonly indent?: string;
+    /**
+     * Element names (local name or `prefix:local`) whose inner content is
+     * reproduced verbatim instead of being reformatted — for elements that
+     * carry significant whitespace (e.g. `xs:documentation`-like free text).
+     */
+    readonly preserveWhitespaceIn?: readonly string[];
+}
+/** Result of {@link formatXml}. */
+export interface FormatXmlResult {
+    /** The formatted text, or the (line-ending normalised) input unchanged when `problem` is set. */
+    readonly text: string;
+    /** Whether `text` differs from the (line-ending normalised) input. */
+    readonly changed: boolean;
+    /** Set, and `text` left unchanged, when the input could not be safely reformatted (e.g. unbalanced tags). */
+    readonly problem?: string;
+}
+/**
+ * Pretty-prints XML text without a DOM round trip. Preserves comments, CDATA,
+ * processing instructions, the XML declaration, DOCTYPE, attribute
+ * order/quoting and entity references. Collapses whitespace-only text
+ * between elements; leaves mixed content (non-whitespace text next to a
+ * child element) untouched inside that element; keeps a text-only element on
+ * one line. Never throws — on unbalanced tags, returns the input unchanged
+ * with `problem` set. Line endings are normalised to `\n`.
+ */
+export declare function formatXml(text: string, options?: FormatXmlOptions): FormatXmlResult;

package/dist/xml/pretty.js

@@ -0,0 +1,137 @@
+/**
+ * A token-based XML pretty printer. Unlike a DOM round trip, this tolerates
+ * slightly malformed input (it never throws) and preserves everything a DOM
+ * serializer would normally lose: comments, CDATA sections, processing
+ * instructions, the XML declaration, DOCTYPE, attribute order/quoting and
+ * entity references.
+ */
+import { localNameOf, normalizeLineEndings, tokenizeXml } from './tolerant-tree.js';
+/** Builds a tree from tokens; returns a `problem` message instead of throwing on unbalanced tags. */
+function buildTree(tokens, text) {
+    const roots = [];
+    const stack = [];
+    const currentChildren = () => stack[stack.length - 1]?.children ?? roots;
+    for (const tok of tokens) {
+        switch (tok.kind) {
+            case 'text':
+                currentChildren().push({ type: 'text', value: tok.raw });
+                break;
+            case 'comment':
+            case 'cdata':
+            case 'pi':
+            case 'doctype':
+                currentChildren().push({ type: tok.kind, raw: tok.raw });
+                break;
+            case 'open':
+                if (tok.selfClosing) {
+                    currentChildren().push({
+                        type: 'element',
+                        name: tok.name,
+                        rawAttrs: tok.rawAttrs ?? '',
+                        selfClosing: true,
+                        children: [],
+                        rawInner: '',
+                    });
+                }
+                else {
+                    stack.push({ name: tok.name, rawAttrs: tok.rawAttrs ?? '', children: [], openEnd: tok.end });
+                }
+                break;
+            case 'close': {
+                const top = stack.pop();
+                if (top === undefined || top.name !== tok.name) {
+                    return { problem: `Mismatched closing tag </${tok.name}>` };
+                }
+                const rawInner = text.slice(top.openEnd, tok.start);
+                const node = {
+                    type: 'element',
+                    name: top.name,
+                    rawAttrs: top.rawAttrs,
+                    selfClosing: false,
+                    children: top.children,
+                    rawInner,
+                };
+                (stack.length > 0 ? stack[stack.length - 1].children : roots).push(node);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    if (stack.length > 0) {
+        return { problem: `Unclosed tag <${stack[stack.length - 1].name}>` };
+    }
+    return { roots };
+}
+function renderNodes(nodes, depth, indent, preserve, out) {
+    for (const n of nodes) {
+        if (n.type === 'text') {
+            if (n.value.trim() === '') {
+                continue;
+            }
+            out.push(indent.repeat(depth) + n.value.trim());
+            continue;
+        }
+        if (n.type === 'element') {
+            renderElement(n, depth, indent, preserve, out);
+            continue;
+        }
+        out.push(indent.repeat(depth) + n.raw);
+    }
+}
+function renderElement(n, depth, indent, preserve, out) {
+    const pad = indent.repeat(depth);
+    const openTag = `<${n.name}${n.rawAttrs !== '' ? ` ${n.rawAttrs}` : ''}`;
+    if (n.selfClosing) {
+        out.push(`${pad}${openTag}/>`);
+        return;
+    }
+    if (preserve.has(n.name) || preserve.has(localNameOf(n.name))) {
+        out.push(`${pad}${openTag}>${n.rawInner}</${n.name}>`);
+        return;
+    }
+    const hasNonWsText = n.children.some((c) => c.type === 'text' && c.value.trim() !== '');
+    const hasElementLike = n.children.some((c) => c.type !== 'text');
+    if (hasNonWsText && hasElementLike) {
+        // Mixed content: leave untouched.
+        out.push(`${pad}${openTag}>${n.rawInner}</${n.name}>`);
+        return;
+    }
+    if (!hasElementLike) {
+        const text = n.children
+            .map((c) => (c.type === 'text' ? c.value : ''))
+            .join('')
+            .trim();
+        out.push(`${pad}${openTag}>${text}</${n.name}>`);
+        return;
+    }
+    out.push(`${pad}${openTag}>`);
+    renderNodes(n.children, depth + 1, indent, preserve, out);
+    out.push(`${pad}</${n.name}>`);
+}
+/**
+ * Pretty-prints XML text without a DOM round trip. Preserves comments, CDATA,
+ * processing instructions, the XML declaration, DOCTYPE, attribute
+ * order/quoting and entity references. Collapses whitespace-only text
+ * between elements; leaves mixed content (non-whitespace text next to a
+ * child element) untouched inside that element; keeps a text-only element on
+ * one line. Never throws — on unbalanced tags, returns the input unchanged
+ * with `problem` set. Line endings are normalised to `\n`.
+ */
+export function formatXml(text, options) {
+    const indent = options?.indent ?? '   ';
+    const preserve = new Set(options?.preserveWhitespaceIn ?? []);
+    const normalized = normalizeLineEndings(text);
+    const tokens = tokenizeXml(normalized);
+    if (tokens === undefined) {
+        return { text: normalized, changed: false, problem: 'Malformed markup: could not tokenize' };
+    }
+    const built = buildTree(tokens, normalized);
+    if ('problem' in built) {
+        return { text: normalized, changed: false, problem: built.problem };
+    }
+    const out = [];
+    renderNodes(built.roots, 0, indent, preserve, out);
+    const resultText = out.join('\n');
+    return { text: resultText, changed: resultText !== normalized };
+}

package/dist/xml/serialize.d.ts

@@ -0,0 +1,6 @@
+import type { Node } from '@xmldom/xmldom';
+/**
+ * Serializes a DOM node (typically a `Document` or `Element`) back to an XML
+ * string using `@xmldom/xmldom`'s `XMLSerializer`.
+ */
+export declare function serializeXml(node: Node): string;

package/dist/xml/serialize.js

@@ -0,0 +1,8 @@
+import { XMLSerializer } from '@xmldom/xmldom';
+/**
+ * Serializes a DOM node (typically a `Document` or `Element`) back to an XML
+ * string using `@xmldom/xmldom`'s `XMLSerializer`.
+ */
+export function serializeXml(node) {
+    return new XMLSerializer().serializeToString(node);
+}

package/dist/xml/tolerant-tree.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A tolerant XML tokenizer shared by the pretty printer and the envelope transforms.
+ *
+ * "Tolerant" means: it never throws, it recognises every construct a serializer would
+ * normally lose (comments, CDATA, processing instructions, the XML declaration, DOCTYPE),
+ * and it reports failure by returning `undefined` rather than by raising — the callers are
+ * text transforms that must return their input unchanged when they cannot understand it.
+ *
+ * Every token carries its `[start, end)` offsets into the original text, so a transform can
+ * splice ranges out of the source instead of re-serializing a tree (which would silently
+ * rewrite attribute spacing and quoting).
+ */
+/** What a {@link XmlToken} is. */
+export type XmlTokenKind = 'comment' | 'cdata' | 'pi' | 'doctype' | 'open' | 'close' | 'text';
+/** One lexical unit of an XML document, with its offsets into the source text. */
+export interface XmlToken {
+    readonly kind: XmlTokenKind;
+    readonly raw: string;
+    readonly start: number;
+    readonly end: number;
+    /** Element name (`prefix:local`) for `open`/`close` tokens. */
+    readonly name?: string;
+    /** Everything between the element name and the closing `>`/`/>`, trimmed. */
+    readonly rawAttrs?: string;
+    readonly selfClosing?: boolean;
+}
+/** Normalises CRLF/CR line endings to `\n`. */
+export declare function normalizeLineEndings(text: string): string;
+/** The local part of a possibly prefixed name. */
+export declare function localNameOf(name: string): string;
+/**
+ * Tokenizes `text`. Returns `undefined` when the tokens do not contiguously cover the whole
+ * string (i.e. the markup is malformed enough that a transform must leave it alone).
+ */
+export declare function tokenizeXml(text: string): XmlToken[] | undefined;
+/** One element in a {@link buildRangeTree} result, with the source range it occupies. */
+export interface XmlRangeNode {
+    readonly name: string;
+    readonly rawAttrs: string;
+    readonly selfClosing: boolean;
+    /** Offset of the `<` opening this element. */
+    readonly start: number;
+    /** Offset just past this element's closing `>`. */
+    readonly end: number;
+    /** Offsets of the element's inner content (equal to each other for a self-closing element). */
+    readonly innerStart: number;
+    readonly innerEnd: number;
+    readonly children: readonly XmlRangeNode[];
+    /** Tokens that are direct children of this element (text, comments, CDATA, PIs). */
+    readonly leafTokens: readonly XmlToken[];
+}
+/**
+ * Builds an element tree over `tokens`, keeping source ranges. Returns `undefined` when tags
+ * are unbalanced or mismatched — again, a signal to leave the document alone.
+ */
+export declare function buildRangeTree(tokens: readonly XmlToken[]): XmlRangeNode[] | undefined;