@beyondwork/docx-react-component 1.0.29 → 1.0.30

package/src/io/ooxml/parse-comments.ts

@@ -0,0 +1,852 @@
+import type { CommentThread } from "../../review/store/comment-store.ts";
+import { createImportedCommentThread } from "../../review/store/comment-thread.ts";
+
+interface XmlElementNode {
+  type: "element";
+  name: string;
+  attributes: Record<string, string>;
+  children: XmlNode[];
+  start: number;
+  end: number;
+}
+
+interface XmlTextNode {
+  type: "text";
+  text: string;
+  start: number;
+  end: number;
+}
+
+type XmlNode = XmlElementNode | XmlTextNode;
+
+export interface ParsedCommentsInput {
+  commentsXml: string;
+  commentsExtendedXml?: string;
+  commentsIdsXml?: string;
+  peopleXml?: string;
+}
+
+export interface ImportedCommentDefinition {
+  commentId: string;
+  authorId?: string;
+  createdAt?: string;
+  body: string;
+  rawXml: string;
+  order: number;
+  initials?: string;
+  paraId?: string;
+  parentParaId?: string;
+  durableId?: string;
+  isDone?: boolean;
+}
+
+interface CommentAnchorBounds {
+  start?: number;
+  end?: number;
+  startParagraphIndex?: number;
+  endParagraphIndex?: number;
+  referenceAt?: number;
+  referenceParagraphIndex?: number;
+}
+
+interface CommentExtensionRecord {
+  paraId: string;
+  parentParaId?: string;
+  isDone?: boolean;
+}
+
+export interface CommentImportDiagnostic {
+  commentId: string;
+  code:
+    | "missing_comment_definition"
+    | "missing_anchor_reference"
+    | "multi_paragraph_anchor_preserve_only"
+    | "opaque_anchor_preserve_only"
+    | "preserve_only_revision_overlap";
+  message: string;
+  featureClass: "preserve-only";
+  detachedReason?: "incomplete-markers" | "multi-paragraph" | "opaque-region" | "revision-overlap";
+  actionabilityNote?: string;
+}
+
+export interface ParsedCommentsResult {
+  threads: CommentThread[];
+  diagnostics: CommentImportDiagnostic[];
+  definitions: ImportedCommentDefinition[];
+  sourceRootTag?: string;
+  sourceExtendedRootTag?: string;
+  sourceIdsRootTag?: string;
+  sourcePeopleRootTag?: string;
+  peopleAuthors: string[];
+}
+
+export function parseCommentsFromOoxml(
+  documentXml: string,
+  input: string | ParsedCommentsInput,
+): ParsedCommentsResult {
+  const parts = normalizeInput(input);
+  const commentExtensions = parseCommentExtensions(parts.commentsExtendedXml);
+  const durableIds = parseCommentDurableIds(parts.commentsIdsXml);
+  const peopleAuthors = parsePeopleAuthors(parts.peopleXml);
+  const definitions = parseCommentDefinitions(parts.commentsXml, commentExtensions, durableIds);
+  const definitionsById = new Map(definitions.map((definition) => [definition.commentId, definition]));
+  const definitionsByParaId = new Map(
+    definitions
+      .filter((definition) => typeof definition.paraId === "string")
+      .map((definition) => [definition.paraId!, definition]),
+  );
+  const anchors = parseCommentAnchors(documentXml);
+  const diagnostics: CommentImportDiagnostic[] = [];
+  const threadDefinitions = groupThreadDefinitions(definitions, definitionsByParaId);
+  const threads: CommentThread[] = [];
+
+  for (const [rootCommentId, groupedDefinitions] of threadDefinitions) {
+    const rootDefinition = groupedDefinitions[0];
+    if (!rootDefinition) {
+      continue;
+    }
+
+    const anchor = anchors.get(rootCommentId);
+    const start = anchor?.start ?? anchor?.referenceAt;
+    const end = anchor?.end ?? anchor?.referenceAt;
+    const startParagraphIndex = anchor?.startParagraphIndex ?? anchor?.referenceParagraphIndex;
+    const endParagraphIndex = anchor?.endParagraphIndex ?? anchor?.referenceParagraphIndex;
+    const entries = groupedDefinitions.map((definition, index) => ({
+      entryId: `${rootCommentId}-entry-${index + 1}`,
+      authorId: definition.authorId ?? "unknown",
+      body: definition.body,
+      createdAt: definition.createdAt ?? "1970-01-01T00:00:00.000Z",
+      metadata: {
+        ooxmlCommentId: definition.commentId,
+        paraId: definition.paraId,
+        parentParaId: definition.parentParaId,
+        durableId: definition.durableId,
+        initials: definition.initials,
+      },
+    }));
+    const createdBy = rootDefinition.authorId ?? entries[0]?.authorId ?? "unknown";
+    const createdAt = rootDefinition.createdAt ?? entries[0]?.createdAt ?? "1970-01-01T00:00:00.000Z";
+    const lastEntry = entries.length > 0 ? entries[entries.length - 1] : undefined;
+    const resolution =
+      rootDefinition.isDone
+        ? {
+            resolvedAt: lastEntry?.createdAt ?? createdAt,
+            resolvedBy: lastEntry?.authorId ?? createdBy,
+          }
+        : undefined;
+    const detachedRange = anchor ? toDetachedRange(anchor) : { from: 0, to: 0 };
+
+    if (
+      start === undefined ||
+      end === undefined ||
+      startParagraphIndex === undefined ||
+      endParagraphIndex === undefined
+    ) {
+      diagnostics.push({
+        commentId: rootCommentId,
+        code: "missing_anchor_reference",
+        message: "Comment anchor markers are incomplete (missing start, end, or reference). Thread is visible but detached and not actionable.",
+        featureClass: "preserve-only",
+        detachedReason: "incomplete-markers",
+        actionabilityNote: "Re-anchoring requires the host to supply a valid range. The comment body and thread are preserved for display.",
+      });
+      threads.push(
+        createImportedCommentThread({
+          commentId: rootCommentId,
+          body: rootDefinition.body,
+          createdBy,
+          createdAt,
+          range: detachedRange,
+          entries,
+          status: "detached",
+          resolution,
+          metadata: {
+            source: "import",
+            rootOoxmlCommentId: rootDefinition.commentId,
+            rootParaId: rootDefinition.paraId,
+            detachedReason: "incomplete-markers",
+            actionabilityNote:
+              "Re-anchoring requires the host to supply a valid range. The comment body and thread are preserved for display.",
+          },
+        }),
+      );
+      continue;
+    }
+
+    if (startParagraphIndex !== endParagraphIndex) {
+      diagnostics.push({
+        commentId: rootCommentId,
+        code: "multi_paragraph_anchor_preserve_only",
+        message:
+          "Comment anchor spans multiple paragraphs. Thread is visible but detached; cross-paragraph anchoring is not yet supported for live editing.",
+        featureClass: "preserve-only",
+        detachedReason: "multi-paragraph",
+        actionabilityNote: "The comment thread and body are preserved. Operators see the thread in the sidebar but cannot navigate to an inline highlight.",
+      });
+      threads.push(
+        createImportedCommentThread({
+          commentId: rootCommentId,
+          body: rootDefinition.body,
+          createdBy,
+          createdAt,
+          range: detachedRange,
+          entries,
+          status: "detached",
+          resolution,
+          metadata: {
+            source: "import",
+            rootOoxmlCommentId: rootDefinition.commentId,
+            rootParaId: rootDefinition.paraId,
+            detachedReason: "multi-paragraph",
+            actionabilityNote:
+              "The comment thread and body are preserved. Operators see the thread in the sidebar but cannot navigate to an inline highlight.",
+          },
+        }),
+      );
+      continue;
+    }
+
+    threads.push(
+      createImportedCommentThread({
+        commentId: rootCommentId,
+        body: rootDefinition.body,
+        createdBy,
+        createdAt,
+        range: {
+          from: Math.min(start, end),
+          to: Math.max(start, end),
+        },
+        entries,
+        status: resolution ? "resolved" : "open",
+        resolution,
+        metadata: {
+          source: "import",
+          rootOoxmlCommentId: rootDefinition.commentId,
+          rootParaId: rootDefinition.paraId,
+        },
+      }),
+    );
+  }
+
+  for (const commentId of anchors.keys()) {
+    if (definitionsById.has(commentId)) {
+      continue;
+    }
+
+    diagnostics.push({
+      commentId,
+      code: "missing_comment_definition",
+      message: "Document anchor markers reference a comment id missing from comments.xml.",
+      featureClass: "preserve-only",
+    });
+  }
+
+  threads.sort(compareThreadsByAnchor);
+
+  return {
+    threads,
+    diagnostics,
+    definitions,
+    sourceRootTag: extractRootTag(parts.commentsXml, "comments"),
+    sourceExtendedRootTag: extractRootTag(parts.commentsExtendedXml, "commentsEx"),
+    sourceIdsRootTag: extractRootTag(parts.commentsIdsXml, "commentsIds"),
+    sourcePeopleRootTag: extractRootTag(parts.peopleXml, "people"),
+    peopleAuthors,
+  };
+}
+
+function normalizeInput(input: string | ParsedCommentsInput): ParsedCommentsInput {
+  return typeof input === "string"
+    ? {
+        commentsXml: input,
+      }
+    : input;
+}
+
+function groupThreadDefinitions(
+  definitions: ImportedCommentDefinition[],
+  definitionsByParaId: Map<string, ImportedCommentDefinition>,
+): Map<string, ImportedCommentDefinition[]> {
+  const grouped = new Map<string, ImportedCommentDefinition[]>();
+
+  for (const definition of definitions) {
+    const rootCommentId = resolveRootCommentId(definition, definitionsByParaId);
+    const group = grouped.get(rootCommentId);
+    if (group) {
+      group.push(definition);
+    } else {
+      grouped.set(rootCommentId, [definition]);
+    }
+  }
+
+  for (const group of grouped.values()) {
+    group.sort((left, right) => left.order - right.order);
+    const rootIndex = group.findIndex((definition) => !definition.parentParaId);
+    if (rootIndex > 0) {
+      const [rootDefinition] = group.splice(rootIndex, 1);
+      if (rootDefinition) {
+        group.unshift(rootDefinition);
+      }
+    }
+  }
+
+  return new Map(
+    [...grouped.entries()].sort(([leftId], [rightId]) => leftId.localeCompare(rightId)),
+  );
+}
+
+function resolveRootCommentId(
+  definition: ImportedCommentDefinition,
+  definitionsByParaId: Map<string, ImportedCommentDefinition>,
+): string {
+  const visited = new Set<string>();
+  let current: ImportedCommentDefinition | undefined = definition;
+
+  while (current?.parentParaId) {
+    if (visited.has(current.parentParaId)) {
+      break;
+    }
+    visited.add(current.parentParaId);
+    const parent = definitionsByParaId.get(current.parentParaId);
+    if (!parent) {
+      break;
+    }
+    current = parent;
+  }
+
+  return current?.commentId ?? definition.commentId;
+}
+
+function parseCommentDefinitions(
+  commentsXml: string,
+  extensions: Map<string, CommentExtensionRecord>,
+  durableIds: Map<string, string>,
+): ImportedCommentDefinition[] {
+  if (commentsXml.trim().length === 0) {
+    return [];
+  }
+
+  const root = parseXml(commentsXml);
+  const commentsElement = findChildElement(root, "comments");
+  const definitions: ImportedCommentDefinition[] = [];
+  let order = 0;
+
+  for (const child of commentsElement.children) {
+    if (child.type !== "element" || localName(child.name) !== "comment") {
+      continue;
+    }
+
+    const commentId = child.attributes["w:id"] ?? child.attributes.id;
+    if (!commentId) {
+      continue;
+    }
+
+    const authorId = child.attributes["w:author"] ?? child.attributes.author;
+    const createdAt = normalizeImportedTimestamp(
+      child.attributes["w:date"] ?? child.attributes.date,
+    );
+    const initials = child.attributes["w:initials"] ?? child.attributes.initials;
+    const paragraphNodes = child.children.filter(
+      (node): node is XmlElementNode => node.type === "element" && localName(node.name) === "p",
+    );
+    const body = paragraphNodes
+      .map(extractParagraphText)
+      .join("\n");
+    const paraId = paragraphNodes[0]?.attributes["w14:paraId"] ?? paragraphNodes[0]?.attributes.paraId;
+    const extension = paraId ? extensions.get(paraId) : undefined;
+
+    definitions.push({
+      commentId,
+      authorId,
+      createdAt,
+      body,
+      rawXml: commentsXml.slice(child.start, child.end),
+      order,
+      initials,
+      paraId,
+      parentParaId: extension?.parentParaId,
+      durableId: paraId ? durableIds.get(paraId) : undefined,
+      isDone: extension?.isDone,
+    });
+    order += 1;
+  }
+
+  return definitions;
+}
+
+function normalizeImportedTimestamp(value: string | undefined): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.valueOf())) {
+    return undefined;
+  }
+
+  return parsed.toISOString();
+}
+
+function parseCommentExtensions(xml: string | undefined): Map<string, CommentExtensionRecord> {
+  if (!xml || xml.trim().length === 0) {
+    return new Map();
+  }
+
+  const root = parseXml(xml);
+  const commentsElement = findChildElement(root, "commentsEx");
+  const extensions = new Map<string, CommentExtensionRecord>();
+
+  for (const child of commentsElement.children) {
+    if (child.type !== "element" || localName(child.name) !== "commentEx") {
+      continue;
+    }
+
+    const paraId = child.attributes["w15:paraId"] ?? child.attributes.paraId;
+    if (!paraId) {
+      continue;
+    }
+
+    const parentParaId = child.attributes["w15:paraIdParent"] ?? child.attributes.paraIdParent;
+    const doneValue = child.attributes["w15:done"] ?? child.attributes.done;
+    extensions.set(paraId, {
+      paraId,
+      parentParaId,
+      isDone:
+        typeof doneValue === "string"
+          ? doneValue.toLowerCase() === "true" || doneValue === "1"
+          : undefined,
+    });
+  }
+
+  return extensions;
+}
+
+function parseCommentDurableIds(xml: string | undefined): Map<string, string> {
+  if (!xml || xml.trim().length === 0) {
+    return new Map();
+  }
+
+  const root = parseXml(xml);
+  const commentsIdsElement = findChildElement(root, "commentsIds");
+  const durableIds = new Map<string, string>();
+
+  for (const child of commentsIdsElement.children) {
+    if (child.type !== "element" || localName(child.name) !== "commentId") {
+      continue;
+    }
+
+    const paraId = child.attributes["w16cid:paraId"] ?? child.attributes.paraId;
+    const durableId = child.attributes["w16cid:durableId"] ?? child.attributes.durableId;
+    if (paraId && durableId) {
+      durableIds.set(paraId, durableId);
+    }
+  }
+
+  return durableIds;
+}
+
+function parsePeopleAuthors(xml: string | undefined): string[] {
+  if (!xml || xml.trim().length === 0) {
+    return [];
+  }
+
+  const root = parseXml(xml);
+  const peopleElement = findChildElement(root, "people");
+  const authors = new Set<string>();
+
+  for (const child of peopleElement.children) {
+    if (child.type !== "element" || localName(child.name) !== "person") {
+      continue;
+    }
+
+    const author = child.attributes["w15:author"] ?? child.attributes.author;
+    if (author) {
+      authors.add(author);
+    }
+  }
+
+  return [...authors].sort((left, right) => left.localeCompare(right));
+}
+
+function extractRootTag(xml: string | undefined, localTagName: string): string | undefined {
+  if (!xml) {
+    return undefined;
+  }
+
+  const pattern = new RegExp(`<[^>]*:?${localTagName}\\b[^>]*>`, "u");
+  return pattern.exec(xml)?.[0];
+}
+
+function parseCommentAnchors(documentXml: string): Map<string, CommentAnchorBounds> {
+  const root = parseXml(documentXml);
+  const documentElement = findChildElement(root, "document");
+  const bodyElement = findChildElement(documentElement, "body");
+  const anchors = new Map<string, CommentAnchorBounds>();
+  walkCommentAnchorBlocks(bodyElement.children, anchors, 0, -1, true);
+
+  return anchors;
+}
+
+function walkCommentAnchorBlocks(
+  nodes: readonly XmlNode[],
+  anchors: Map<string, CommentAnchorBounds>,
+  cursor: number,
+  paragraphIndex: number,
+  useSurfaceParagraphSeparators: boolean,
+): {
+  cursor: number;
+  paragraphIndex: number;
+} {
+  let nextCursor = cursor;
+  let nextParagraphIndex = paragraphIndex;
+  let elementIndex = -1;
+
+  for (const node of nodes) {
+    if (node.type !== "element") {
+      continue;
+    }
+    elementIndex += 1;
+
+    const name = localName(node.name);
+    if (name === "p") {
+      if (useSurfaceParagraphSeparators && elementIndex > 0) {
+        nextCursor += 1;
+      }
+      nextParagraphIndex += 1;
+      walkParagraph(node, nextParagraphIndex, anchors, () => nextCursor, (next) => {
+        nextCursor = next;
+      });
+      continue;
+    }
+
+    if (name === "tbl") {
+      for (const child of node.children) {
+        if (child.type !== "element" || localName(child.name) !== "tr") {
+          continue;
+        }
+        for (const rowChild of child.children) {
+          if (rowChild.type !== "element" || localName(rowChild.name) !== "tc") {
+            continue;
+          }
+          const result = walkCommentAnchorBlocks(
+            rowChild.children,
+            anchors,
+            nextCursor,
+            nextParagraphIndex,
+            false,
+          );
+          nextCursor = result.cursor;
+          nextParagraphIndex = result.paragraphIndex;
+        }
+      }
+      continue;
+    }
+
+    if (name === "sdt") {
+      const sdtContent = findChildElement(node, "sdtContent");
+      const result = walkCommentAnchorBlocks(
+        sdtContent.children,
+        anchors,
+        nextCursor,
+        nextParagraphIndex,
+        false,
+      );
+      nextCursor = result.cursor;
+      nextParagraphIndex = result.paragraphIndex;
+      continue;
+    }
+
+    if (name === "customXml") {
+      nextCursor += 1;
+      continue;
+    }
+
+    nextCursor += 0;
+  }
+
+  return {
+    cursor: nextCursor,
+    paragraphIndex: nextParagraphIndex,
+  };
+}
+
+function walkParagraph(
+  paragraph: XmlElementNode,
+  paragraphIndex: number,
+  anchors: Map<string, CommentAnchorBounds>,
+  getCursor: () => number,
+  setCursor: (next: number) => void,
+): void {
+  for (const child of paragraph.children) {
+    walkInlineNode(child, paragraphIndex, anchors, getCursor, setCursor);
+  }
+}
+
+function walkInlineNode(
+  node: XmlNode,
+  paragraphIndex: number,
+  anchors: Map<string, CommentAnchorBounds>,
+  getCursor: () => number,
+  setCursor: (next: number) => void,
+): void {
+  if (node.type !== "element") {
+    return;
+  }
+
+  switch (localName(node.name)) {
+    case "commentRangeStart": {
+      const commentId = node.attributes["w:id"] ?? node.attributes.id;
+      if (commentId) {
+        const bounds = ensureCommentAnchor(anchors, commentId);
+        bounds.start = getCursor();
+        bounds.startParagraphIndex = paragraphIndex;
+      }
+      return;
+    }
+    case "commentRangeEnd": {
+      const commentId = node.attributes["w:id"] ?? node.attributes.id;
+      if (commentId) {
+        const bounds = ensureCommentAnchor(anchors, commentId);
+        bounds.end = getCursor();
+        bounds.endParagraphIndex = paragraphIndex;
+      }
+      return;
+    }
+    case "commentReference": {
+      const commentId = node.attributes["w:id"] ?? node.attributes.id;
+      if (commentId) {
+        const bounds = ensureCommentAnchor(anchors, commentId);
+        bounds.referenceAt = getCursor();
+        bounds.referenceParagraphIndex = paragraphIndex;
+      }
+      return;
+    }
+    case "t": {
+      const text = node.children
+        .filter((child): child is XmlTextNode => child.type === "text")
+        .map((child) => child.text)
+        .join("");
+      setCursor(getCursor() + Array.from(text).length);
+      return;
+    }
+    case "tab":
+    case "br":
+      setCursor(getCursor() + 1);
+      return;
+    default:
+      for (const child of node.children) {
+        walkInlineNode(child, paragraphIndex, anchors, getCursor, setCursor);
+      }
+  }
+}
+
+function ensureCommentAnchor(
+  anchors: Map<string, CommentAnchorBounds>,
+  commentId: string,
+): CommentAnchorBounds {
+  const existing = anchors.get(commentId);
+  if (existing) {
+    return existing;
+  }
+
+  const next: CommentAnchorBounds = {};
+  anchors.set(commentId, next);
+  return next;
+}
+
+function extractParagraphText(paragraph: XmlElementNode): string {
+  let text = "";
+
+  for (const child of paragraph.children) {
+    text += extractNodeText(child);
+  }
+
+  return text;
+}
+
+function extractNodeText(node: XmlNode): string {
+  if (node.type === "text") {
+    return node.text;
+  }
+
+  switch (localName(node.name)) {
+    case "t":
+      return node.children.map(extractNodeText).join("");
+    case "tab":
+      return "\t";
+    case "br":
+      return "\n";
+    default:
+      return node.children.map(extractNodeText).join("");
+  }
+}
+
+function compareThreadsByAnchor(left: CommentThread, right: CommentThread): number {
+  const leftStart =
+    left.anchor.kind === "range" ? left.anchor.range.from : Number.MAX_SAFE_INTEGER;
+  const rightStart =
+    right.anchor.kind === "range" ? right.anchor.range.from : Number.MAX_SAFE_INTEGER;
+
+  if (leftStart !== rightStart) {
+    return leftStart - rightStart;
+  }
+
+  return left.commentId.localeCompare(right.commentId);
+}
+
+function toDetachedRange(anchor: CommentAnchorBounds): { from: number; to: number } | undefined {
+  const positions = [anchor.start, anchor.end, anchor.referenceAt].filter(
+    (value): value is number => typeof value === "number",
+  );
+  if (positions.length === 0) {
+    return undefined;
+  }
+  return {
+    from: Math.min(...positions),
+    to: Math.max(...positions),
+  };
+}
+
+function parseXml(xml: string): XmlElementNode {
+  const root: XmlElementNode = {
+    type: "element",
+    name: "#document",
+    attributes: {},
+    children: [],
+    start: 0,
+    end: xml.length,
+  };
+  const stack: XmlElementNode[] = [root];
+  const tokenPattern =
+    /<!--[\s\S]*?-->|<\?[\s\S]*?\?>|<!DOCTYPE[\s\S]*?>|<!\[CDATA\[[\s\S]*?\]\]>|<[^>]+>|[^<]+/gu;
+
+  for (const match of xml.matchAll(tokenPattern)) {
+    const token = match[0] ?? "";
+    const start = match.index ?? 0;
+    const end = start + token.length;
+
+    if (token.startsWith("<?") || token.startsWith("<!DOCTYPE") || token.startsWith("<!--")) {
+      continue;
+    }
+
+    if (token.startsWith("<![CDATA[")) {
+      const text = token.slice(9, -3);
+      stack[stack.length - 1]?.children.push({
+        type: "text",
+        text,
+        start,
+        end,
+      });
+      continue;
+    }
+
+    if (token.startsWith("</")) {
+      const node = stack.pop();
+      if (!node) {
+        throw new Error("Malformed XML: unexpected closing tag.");
+      }
+      node.end = end;
+      continue;
+    }
+
+    if (token.startsWith("<")) {
+      const selfClosing = /\/>$/.test(token);
+      const tagBody = token.slice(1, token.length - (selfClosing ? 2 : 1)).trim();
+      const { name, attributes } = parseTag(tagBody);
+      const node: XmlElementNode = {
+        type: "element",
+        name,
+        attributes,
+        children: [],
+        start,
+        end,
+      };
+      stack[stack.length - 1]?.children.push(node);
+      if (!selfClosing) {
+        stack.push(node);
+      }
+      continue;
+    }
+
+    const text = decodeXmlText(token);
+    if (text.length > 0) {
+      stack[stack.length - 1]?.children.push({
+        type: "text",
+        text,
+        start,
+        end,
+      });
+    }
+  }
+
+  if (stack.length !== 1) {
+    throw new Error("Malformed XML: unclosed tag.");
+  }
+
+  return root;
+}
+
+function parseTag(tagBody: string): { name: string; attributes: Record<string, string> } {
+  const whitespaceIndex = tagBody.search(/\s/u);
+  const name = whitespaceIndex === -1 ? tagBody : tagBody.slice(0, whitespaceIndex);
+  const rawAttributes = whitespaceIndex === -1 ? "" : tagBody.slice(whitespaceIndex + 1);
+  const attributes: Record<string, string> = {};
+  const pattern = /([A-Za-z_][A-Za-z0-9:._-]*)\s*=\s*("([^"]*)"|'([^']*)')/gu;
+
+  for (const match of rawAttributes.matchAll(pattern)) {
+    const key = match[1];
+    const value = match[3] ?? match[4] ?? "";
+    if (key) {
+      attributes[key] = decodeXmlText(value);
+    }
+  }
+
+  return { name, attributes };
+}
+
+function findChildElement(node: XmlElementNode, name: string): XmlElementNode {
+  const match = node.children.find(
+    (child): child is XmlElementNode =>
+      child.type === "element" && localName(child.name) === name,
+  );
+
+  if (!match) {
+    throw new Error(`Expected XML element ${name}.`);
+  }
+
+  return match;
+}
+
+function localName(name: string): string {
+  const index = name.indexOf(":");
+  return index === -1 ? name : name.slice(index + 1);
+}
+
+function decodeXmlText(text: string): string {
+  return text.replace(
+    /&(?:#x([0-9A-Fa-f]+)|#([0-9]+)|([A-Za-z]+));/gu,
+    (_, hex, dec, named) => {
+      if (hex) {
+        return String.fromCodePoint(Number.parseInt(hex, 16));
+      }
+      if (dec) {
+        return String.fromCodePoint(Number.parseInt(dec, 10));
+      }
+
+      switch (named) {
+        case "amp":
+          return "&";
+        case "lt":
+          return "<";
+        case "gt":
+          return ">";
+        case "quot":
+          return "\"";
+        case "apos":
+          return "'";
+        default:
+          return `&${named};`;
+      }
+    },
+  );
+}