@volter/world-core 3.0.155 → 3.0.157

package/src/xml.ts

@@ -0,0 +1,71 @@
+// Strict XML grammar is shared mechanics; element interpretation belongs to the consuming pack.
+// The exact optional dependency belongs to this kernel, so Node and browser bundles resolve one parser.
+// Source: @xmldom/xmldom 0.9.12 lib/dom-parser.js and index.d.ts (DOMParser/onError).
+export type XmlElement = { kind: 'element'; name: string; attributes: Record<string, string>; content: XmlContent[] };
+export type XmlText = { kind: 'text' | 'cdata' | 'comment'; value: string };
+export type XmlInstruction = { kind: 'processing-instruction'; target: string; value: string };
+export type XmlContent = XmlElement | XmlText | XmlInstruction;
+export type XmlDocument = { root: XmlElement; prologue: Array<XmlText | XmlInstruction>; epilogue: Array<XmlText | XmlInstruction> };
+export class XmlDocumentError extends Error {
+  constructor(readonly code: 'parser-unavailable' | 'unsupported-declaration' | 'malformed-document' | 'parsing-limit') {
+    super(code === 'parser-unavailable' ? 'Strict XML parser @xmldom/xmldom 0.9.12 is unavailable'
+      : code === 'unsupported-declaration' ? 'DTD and entity declarations are unsupported'
+        : code === 'parsing-limit' ? 'XML document exceeds the supported parsing limits'
+        : 'XML document is not well formed');
+    this.name = 'XmlDocumentError';
+  }
+}
+type Grammar = typeof import('@xmldom/xmldom');
+let grammar: Promise<Grammar> | undefined;
+function loadGrammar(): Promise<Grammar> {
+  return grammar ??= import('@xmldom/xmldom').catch(() => { grammar = undefined; throw new XmlDocumentError('parser-unavailable'); });
+}
+
+/** No I/O, globals, vendor names, defaults or recovery. Importing this module does not load the grammar.
+ * The XML declaration is a processing instruction in the prologue. A leading BOM is refused.
+ * Raw DOCTYPE/ENTITY markers refuse even inside comments or CDATA: this conservative preflight is linear.
+ */
+export async function parseDocument(source: string): Promise<XmlDocument> {
+  if (typeof source !== 'string' || source.charCodeAt(0) === 0xfeff) throw new XmlDocumentError('malformed-document');
+  if (source.indexOf('<!DOCTYPE') !== -1 || source.indexOf('<!ENTITY') !== -1) throw new XmlDocumentError('unsupported-declaration');
+  const { DOMParser } = await loadGrammar();
+  try {
+    const document = new DOMParser({ onError: () => { throw new XmlDocumentError('malformed-document'); } }).parseFromString(source, 'application/xml');
+    const convert = (node: import('@xmldom/xmldom').Node): XmlContent => {
+      if (node.nodeType === 1) {
+        const element = node as import('@xmldom/xmldom').Element;
+        const attributes: Record<string, string> = Object.create(null);
+        for (const attr of Array.from(element.attributes)) attributes[attr.name] = attr.value;
+        return { kind: 'element', name: element.tagName, attributes, content: [] };
+      }
+      if (node.nodeType === 3 || node.nodeType === 4 || node.nodeType === 8)
+        return { kind: node.nodeType === 3 ? 'text' : node.nodeType === 4 ? 'cdata' : 'comment', value: node.nodeValue ?? '' };
+      if (node.nodeType === 7) return { kind: 'processing-instruction', target: node.nodeName, value: node.nodeValue ?? '' };
+      throw new XmlDocumentError(node.nodeType === 10 ? 'unsupported-declaration' : 'malformed-document');
+    };
+    const pending: Array<{ source: import('@xmldom/xmldom').Node; target: XmlElement }> = [];
+    const one = (source: import('@xmldom/xmldom').Node): XmlContent => {
+      const target = convert(source);
+      if (target.kind === 'element') pending.push({ source, target });
+      return target;
+    };
+    const nodes = Array.from(document.childNodes).map(one);
+    while (pending.length) {
+      const { source, target } = pending.pop()!;
+      for (const child of Array.from(source.childNodes)) target.content.push(one(child));
+    }
+    const roots = nodes.filter((node): node is XmlElement => node.kind === 'element');
+    if (roots.length !== 1) throw new XmlDocumentError('malformed-document');
+    const root = roots[0]!, index = nodes.indexOf(root);
+    const outside = (list: XmlContent[]): Array<XmlText | XmlInstruction> => list.map(node => {
+      if (node.kind === 'element' || node.kind === 'cdata' || (node.kind === 'text' && node.value.trim())) throw new XmlDocumentError('malformed-document');
+      return node;
+    });
+    return { root, prologue: outside(nodes.slice(0, index)), epilogue: outside(nodes.slice(index + 1)) };
+  } catch (error) {
+    if (error instanceof XmlDocumentError) throw error;
+    if (error instanceof RangeError) throw new XmlDocumentError('parsing-limit');
+    // The grammar's diagnostics can contain source bytes. Expose a fixed error, keeping credentials out of reports.
+    throw new XmlDocumentError('malformed-document');
+  }
+}