@formicoidea/labre-core 0.50.0 → 0.51.0

package/dist/_pkgs/affine-block-surface/extensions/xml-reader.d.ts

@@ -0,0 +1,238 @@
+/**
+ * A tolerant XML READER — the inverse of UML's `xml.ts` writer, and the one
+ * thing an importer cannot do without. Read by the XMI and draw.io importers,
+ * by BPMN and by the SVG sketch (through `xml-element.ts`), all four servable
+ * from the editor-free `./interchange` entry.
+ *
+ * ## Why not `DOMParser`
+ *
+ * BPMN and the SVG sketch used to call it, and the P0 import spike measured
+ * the cost on a server: a DOM to install (jsdom, 6 MB, behind `vm`), and a
+ * BPMN read that grew quadratically on it. An interchange parser is a PURE function of a string (`docs/adr/0012` P3) — the
+ * same function an editor command, a unit test and labre-mcp all call — and
+ * `DOMParser` is a DOM global that exists in exactly one of those three. A
+ * reader that needs `happy-dom` to be loaded is a reader with an environment in
+ * its signature.
+ *
+ * So: two hundred lines of scanner, and no global in sight.
+ *
+ * ## Tolerant, and what that costs
+ *
+ * **It never throws.** A file that stops mid-element, a close tag that names
+ * the wrong element, an attribute with no quotes, an entity nobody declared —
+ * every one of them produces a tree with a NOTE beside it rather than an
+ * exception. That is not sloppiness, it is the job: the files this reader is
+ * handed were written by Papyrus, StarUML, Enterprise Architect and a dozen
+ * scripts, and a user who exported a model from one of them is entitled to get
+ * back everything it said even when part of it is malformed. The alternative —
+ * one exception for one stray `&` — imports nothing at all.
+ *
+ * What it does NOT do is pretend to be a conformant parser. There is no DTD, no
+ * entity declaration, no namespace RESOLUTION (prefixes are kept exactly as the
+ * file spelled them — see {@link XmlNode.prefix}), no attribute-value
+ * normalization beyond the character references XML 1.0 §3.3.3 makes
+ * mandatory. Every one of those is a feature an XMI file in the wild does not
+ * use, and each would be a piece of surface with nothing behind it.
+ *
+ * ## Verbatim means the source's own bytes
+ *
+ * Every node records the byte RANGE it was read from ({@link XmlNode.range}),
+ * and {@link xmlFragmentOf} hands back that slice of the original string. So a
+ * quarantined fragment (ADR 0012 D5) is the file's own text — its comments, its
+ * whitespace, its attribute order, its prefixes — and not this reader's opinion
+ * of it. {@link serializeXmlNode} re-serializes from the tree instead, and is
+ * the fallback for a node assembled rather than read.
+ *
+ * ## Bounded, because a server reads it too
+ *
+ * The one exception to "never throws": a document past {@link XML_MAX_NODES}
+ * nodes or {@link XML_MAX_CHARACTERS} characters is refused with an
+ * {@link InterchangeImportError} carrying a static key, at the node that
+ * crosses the line and not after the tree is built. Each node costs about two
+ * hundred bytes of heap, and a 1.5 KiB `.drawio` inflates to a million of
+ * them (the 2026-10-14 security review: 3.2 s and 223 MiB before the cap). The
+ * scan is linear in the source otherwise: an orphan close tag is answered from
+ * a count of open names, not by searching the stack.
+ *
+ * Pure: a string in, a tree out. No `std`, no DOM, no clock.
+ */
+import type { ChromeWording } from '../../affine-shared/services/index.js';
+/**
+ * One element.
+ *
+ * `name` is the qualified name AS WRITTEN (`uml:Model`), with {@link prefix}
+ * and {@link local} split out beside it, because an importer asks both
+ * questions: the prefix is how a file says which vocabulary it means, and the
+ * local name is the only half two tools reliably agree on — Papyrus writes
+ * `uml:Class`, an older Enterprise Architect writes `UML:Class`, and a
+ * namespace-defaulted file writes `Class`.
+ */
+export interface XmlNode {
+    /** The qualified name, verbatim: `uml:Model`, `packagedElement`. */
+    name: string;
+    /** The prefix, `''` when the name carries none. */
+    prefix: string;
+    /** The local name — `Model`, `packagedElement`. */
+    local: string;
+    /** Attributes by qualified name, values entity-decoded, in document order. */
+    attrs: Record<string, string>;
+    children: XmlNode[];
+    /**
+     * The element's character data — text and CDATA, concatenated and decoded.
+     *
+     * Absent rather than `''` when the element holds nothing but whitespace and
+     * children, which is what every element of an indented XMI document holds.
+     * A `<body>` with prose in it has this; a `<packagedElement>` does not.
+     */
+    text?: string;
+    /**
+     * `[start, end)` in the SOURCE string — what {@link xmlFragmentOf} slices.
+     *
+     * `end` is the offset just past this element's close tag (or past `/>`). For
+     * an element the file never closed it is the end of what was read, which is
+     * the honest answer and keeps the slice well-formed enough to re-parse.
+     */
+    range: [number, number];
+    /**
+     * Everything inside the element IN DOCUMENT ORDER: child elements, character
+     * data (text and CDATA, decoded, whitespace included), comments and
+     * processing instructions. {@link text} and {@link children} are the two
+     * convenient projections of it; this is what a reader needs when order or
+     * markup that is not an element matters (`<text>a<tspan>b</tspan>c</text>`,
+     * a vendor comment carried back verbatim). Always present on a node
+     * {@link readXml} produced; absent on one a caller assembled.
+     */
+    content?: XmlContent[];
+}
+/** One entry of {@link XmlNode.content}. */
+export type XmlContent = XmlNode
+/** Text and CDATA are one kind: a consumer escapes both the same way. */
+ | {
+    kind: 'text';
+    value: string;
+} | {
+    kind: 'comment';
+    value: string;
+} | {
+    kind: 'pi';
+    /** The target, `xml-stylesheet` in `<?xml-stylesheet href="…"?>`. */
+    target: string;
+    /** The rest, leading whitespace dropped, as the DOM's `data` has it. */
+    data: string;
+};
+/** How strictly {@link readXml} reads. */
+export interface XmlReadOptions {
+    /**
+     * Two XML 1.0 rules the tolerant default leaves out, for a caller that used
+     * to read with `DOMParser` and must keep its answers (BPMN, the SVG sketch):
+     * attribute values are whitespace-normalized as §3.3.3 makes mandatory (a
+     * literal tab or newline reads as a space, a character reference keeps its
+     * character), and a second top-level element is a note. Off by default, so
+     * the XMI and draw.io readers keep reading exactly what they read before.
+     */
+    conformant?: boolean;
+    /**
+     * Elements, attributes, character runs, comments, instructions and notes,
+     * counted together. Default {@link XML_MAX_NODES}.
+     */
+    maxNodes?: number;
+    /**
+     * Characters of decoded text, attribute values, comments and instructions.
+     * Default {@link XML_MAX_CHARACTERS}.
+     */
+    maxCharacters?: number;
+}
+/**
+ * Safe for a function with 256 MiB and two seconds: the largest file of the
+ * corpus holds a few thousand nodes, a reading at the cap about 40 MiB.
+ */
+export declare const XML_MAX_NODES = 200000;
+/** Notes written in full; the rest are counted in one last note. */
+export declare const XML_MAX_NOTES = 100;
+/** 2 MiB of decoded characters, well past any drawing the canvas can show. */
+export declare const XML_MAX_CHARACTERS: number;
+/** The reader's one refusal; static, so a server can hand the key on. */
+export declare const XML_READ_TOO_LARGE: ChromeWording;
+/** A document, and everything the reader had to complain about to read it. */
+export interface XmlDocument {
+    /** The first top-level element, or `undefined` for a document with none. */
+    root?: XmlNode;
+    /**
+     * Every top-level element, in order.
+     *
+     * A well-formed document has exactly one. A file that has been concatenated,
+     * truncated or hand-edited has none or several, and the reader says what it
+     * found rather than deciding which one was meant.
+     */
+    roots: XmlNode[];
+    /** One line each, in the user's words — see the header on tolerance. */
+    notes: string[];
+}
+/**
+ * Character data as its characters — the five named entities and any numeric
+ * reference.
+ *
+ * An entity this reader does not know (`&nbsp;`, a DTD-declared one) is left
+ * EXACTLY as it was written, unresolved and unannounced. Two reasons, and the
+ * second is the one that matters: resolving it would need the DTD the file
+ * does not ship, and dropping it would lose a character; leaving the reference
+ * standing means a later re-serialization writes back what the file said, which
+ * is the promise `xmlFragmentOf` makes and this keeps true for text as well.
+ */
+export declare function decodeXmlText(value: string): string;
+/**
+ * Read a document. Throws only past its size caps; see the header.
+ *
+ * The scan is a single left-to-right pass with an explicit stack, which is what
+ * makes the tolerance cheap: every recovery is "say what is wrong, and carry on
+ * from the next `<`", and there is no recursion to unwind. In conformant mode
+ * the first note STOPS the read: its callers refuse on any note, and a file
+ * built to raise twenty thousand of them must not get to.
+ */
+export declare function readXml(source: string, options?: XmlReadOptions): XmlDocument;
+/**
+ * The element's own bytes, from the string it was read from.
+ *
+ * This is what a quarantined fragment is (ADR 0012 D5): the file's text, not a
+ * re-rendering of this reader's tree. Comments, attribute order, prefixes and
+ * whitespace all survive, because none of them was ever taken apart.
+ */
+export declare function xmlFragmentOf(source: string, node: XmlNode): string;
+/**
+ * A node back as XML, from the TREE rather than from the source.
+ *
+ * The fallback for a fragment that has no range to slice — one assembled by a
+ * caller, or read out of a document this function's caller no longer holds. It
+ * is faithful to what the tree records and therefore drops what the tree does
+ * not: comments, processing instructions, and the file's own indentation.
+ * Prefer {@link xmlFragmentOf} whenever the source string is still in hand.
+ */
+export declare function serializeXmlNode(node: XmlNode): string;
+/** Children with this local name, whatever prefix the file gave them. */
+export declare function xmlChildren(node: XmlNode, local: string): XmlNode[];
+/** The first child with this local name, if any. */
+export declare function xmlChild(node: XmlNode, local: string): XmlNode | undefined;
+/**
+ * An attribute by LOCAL name — `xmi:id`, `xmi:ID` and a bare `id` all answer.
+ *
+ * Prefix-insensitive on purpose, and it is the difference between reading three
+ * tools and reading one: the XMI prefix is `xmi` by convention and by nothing
+ * else, Enterprise Architect has shipped files under `XMI`, and an
+ * attribute-defaulted file drops it altogether. The QUALIFIED name is still in
+ * `attrs` for anything that needs it, and {@link xmlFragmentOf} still writes
+ * back what the file said.
+ *
+ * The first match in document order wins, which only matters for a file that
+ * spells the same attribute twice under two prefixes.
+ */
+export declare function xmlAttr(node: XmlNode, local: string): string | undefined;
+/** Every `xmlns` / `xmlns:*` declaration on this element, by prefix (`''`). */
+export declare function xmlNamespaces(node: XmlNode): Record<string, string>;
+/**
+ * Every element under `node`, at any depth, in document order.
+ *
+ * An explicit stack rather than recursion: the depth of a file is whatever its
+ * author chose, and a hostile one nested a hundred thousand deep must cost a
+ * loop, not the call stack.
+ */
+export declare function xmlDescendants(node: XmlNode): XmlNode[];