@tradik/xslt-processor 1.0.3 → 1.3.0

package/src/xslt/engine/topLevel.js

@@ -0,0 +1,130 @@
+/**
+ * Top-level elements of a stylesheet module: their dispatch to the
+ * declaration handlers, simplified stylesheets and the stylesheet-wide
+ * namespace table.
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { XSLT_NAMESPACE } from "../elements.js";
+import { inScopeNamespaces } from "../stylesheetNamespaces.js";
+import {
+  checkLocalBindings,
+  checkNumberPatterns,
+  checkTopLevelText,
+} from "../stylesheetChecks.js";
+import { isForwardsCompatible } from "../forwardsCompatible.js";
+
+/**
+ * Engine method handling each top-level XSLT element (xsl:import is handled
+ * first, separately, because imports must precede everything else).
+ */
+const TOP_LEVEL_HANDLERS = Object.freeze({
+  template: "registerTemplate",
+  output: "processOutput",
+  variable: "processGlobalVariable",
+  param: "processGlobalParam",
+  key: "processKey",
+  "decimal-format": "processDecimalFormat",
+  "namespace-alias": "processNamespaceAlias",
+  "attribute-set": "processAttributeSet",
+  "strip-space": "processStripSpace",
+  "preserve-space": "processPreserveSpace",
+  include: "processInclude",
+});
+
+export const topLevelMethods = {
+  /**
+   * Process the top-level elements of a stylesheet module.
+   *
+   * xsl:import elements are processed first, so imported declarations get a
+   * lower import precedence than the ones of the importing stylesheet.
+   *
+   * @param {Element} root - The xsl:stylesheet element
+   * @param {string} stylesheetUri - URI used to resolve imports and includes
+   * @returns {void}
+   */
+  processTopLevelElements(root, stylesheetUri) {
+    checkTopLevelText(root);
+    this.collectNamespaces(root);
+
+    const imports = [];
+    const otherElements = [];
+    for (const child of root.childNodes) {
+      if (child.nodeType !== 1) continue;
+      if (this.isXsltElement(child, "import")) imports.push(child);
+      else otherElements.push(child);
+    }
+
+    for (const importNode of imports) {
+      this.processImport(importNode, stylesheetUri);
+    }
+
+    for (const child of otherElements) {
+      if (!this.isXsltNamespace(child)) continue;
+      const method = TOP_LEVEL_HANDLERS[child.localName];
+      if (method) this[method](child, stylesheetUri);
+      else this.unknownTopLevelElement(child);
+    }
+    checkNumberPatterns(this.patternMatcher, root);
+  },
+
+  /**
+   * Ignore an unknown top-level XSLT element: silently in forwards-compatible
+   * mode (XSLT 1.0 section 2.5), with a warning otherwise.
+   *
+   * @param {Element} node - The unknown element
+   * @returns {void}
+   */
+  unknownTopLevelElement(node) {
+    if (isForwardsCompatible(node)) return;
+    this.warnOnce(`unknown top-level element xsl:${node.localName} is ignored`);
+  },
+
+  /**
+   * Register a simplified stylesheet (XSLT 1.0 section 2.3): the literal result
+   * root element is the body of a template rule matching "/", so the root
+   * element itself is instantiated, not only its children.
+   *
+   * @param {Element} root - The literal result root element
+   * @returns {void}
+   */
+  processLiteralResultStylesheet(root) {
+    this.collectNamespaces(root);
+    checkNumberPatterns(this.patternMatcher, root);
+    checkLocalBindings(root, (message) => this.warnOnce(message));
+    this.templates.push({
+      match: "/",
+      name: null,
+      mode: null,
+      priority: 0.5,
+      importPrecedence: this.currentImportPrecedence,
+      namespaces: inScopeNamespaces(root),
+      node: { firstChild: root, childNodes: [root] },
+    });
+  },
+
+  /**
+   * Record the namespace declarations of a stylesheet document element in
+   * the stylesheet-wide fallback table. Instructions resolve prefixes against
+   * their own in-scope namespaces; this table only serves contexts without a
+   * stylesheet element. The first binding of a prefix wins, so a module
+   * loaded later cannot rebind the main stylesheet's prefixes.
+   *
+   * @param {Element} node - The stylesheet element
+   * @returns {void}
+   */
+  collectNamespaces(node) {
+    if (!node.attributes) return;
+
+    for (const attr of node.attributes) {
+      let prefix = null;
+      if (attr.name.startsWith("xmlns:")) prefix = attr.name.substring(6);
+      else if (attr.name === "xmlns") prefix = "";
+
+      if (prefix !== null && attr.value !== XSLT_NAMESPACE) {
+        this.namespaces[prefix] ??= attr.value;
+      }
+    }
+  },
+};

package/src/xslt/engine/transformation.js

@@ -0,0 +1,263 @@
+/**
+ * Transformation entry points: building the result tree and shaping it as
+ * a fragment, a document or a string.
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { WhitespaceFilter, stripWhitespaceNodes } from "../whitespace.js";
+import {
+  createResultDocument,
+  importResultFragment,
+  isHtmlDocument,
+  parseHtmlFragment,
+  wrapTextResult,
+} from "../resultTree.js";
+import { resolveOutputSettings, serializeResult } from "../serializer.js";
+import { fillXmlDocument, parseHtmlDocument } from "../resultDocument.js";
+import { XsltContext } from "./context.js";
+import {
+  DocumentOrderIndex,
+  hasNativePositionComparison,
+} from "../../xpath/documentOrder.js";
+
+/**
+ * Turn a JavaScript stack overflow into a clear transformation error; any
+ * other error is returned unchanged.
+ *
+ * @param {Error} error - The error thrown by a transformation
+ * @returns {Error} The error to report
+ */
+function recursionError(error) {
+  const isStackOverflow =
+    (error instanceof RangeError && /call stack/i.test(error.message)) ||
+    // Firefox reports "InternalError: too much recursion"
+    (error?.name === "InternalError" && /recursion/i.test(error.message));
+  if (!isStackOverflow) return error;
+
+  return new Error(
+    "Template recursion too deep: the transformation exceeded the JavaScript " +
+      "call stack (infinite recursion, or recursion deeper than the runtime allows)",
+    { cause: error },
+  );
+}
+
+export const transformationMethods = {
+  /**
+   * Transform a source node into a fragment owned by `ownerDocument`, built
+   * with the XML DOM (names and namespaces as in the result tree).
+   *
+   * @param {Node} sourceNode - Source document or element
+   * @param {Document} [ownerDocument] - Output document, default the global one
+   * @returns {DocumentFragment} The result
+   */
+  transform(sourceNode, ownerDocument) {
+    const doc = this.outputDocumentOf(ownerDocument);
+    return importResultFragment(this.buildResultTree(sourceNode, doc), doc);
+  },
+
+  /**
+   * Transform a source node into a fragment of `ownerDocument` as Chrome's
+   * `transformToFragment` does: into an HTML document, the output of the
+   * html method (declared or detected) is serialized and parsed as HTML, so
+   * it holds HTMLElements, and other output keeps its nodes except that
+   * elements in no namespace become XHTML elements (as in Chrome and
+   * Firefox); into an XML document the result nodes are kept.
+   *
+   * @param {Node} sourceNode - Source document or element
+   * @param {Document} ownerDocument - Output document
+   * @returns {DocumentFragment} The result
+   */
+  transformToFragment(sourceNode, ownerDocument) {
+    const doc = this.outputDocumentOf(ownerDocument);
+    const fragment = this.buildResultTree(sourceNode, doc);
+    const settings = resolveOutputSettings(this.outputSettings, fragment);
+    if (isHtmlDocument(doc) && settings.method === "html") {
+      return parseHtmlFragment(
+        serializeResult(fragment, this.outputSettings),
+        doc,
+      );
+    }
+    return importResultFragment(fragment, doc, { htmlElements: true });
+  },
+
+  /**
+   * The document that owns a transformation result.
+   *
+   * @param {Document} [ownerDocument] - Requested owner
+   * @returns {Document} The owner, else the global document
+   * @throws {Error} When there is no document at all
+   */
+  outputDocumentOf(ownerDocument) {
+    const doc =
+      ownerDocument || (typeof document !== "undefined" ? document : null);
+
+    if (!doc) {
+      throw new Error("No output document available");
+    }
+    return doc;
+  },
+
+  /**
+   * Run the transformation and return the result tree, built in a neutral
+   * XML document: creating nodes directly in an HTML owner document would
+   * lower case names and force the XHTML namespace on every element.
+   *
+   * The templates are applied to the document node (not the document
+   * element), so the "/" template has the document as context node and
+   * paths such as "RootElement/child" work.
+   *
+   * @param {Node} sourceNode - Source document or element
+   * @param {Document} doc - Document providing the DOM implementation
+   * @returns {DocumentFragment} The result tree
+   */
+  buildResultTree(sourceNode, doc) {
+    const resultDocument = createResultDocument(doc);
+    const source = this.initialNode(this.prepareSource(sourceNode, doc));
+
+    const context = new XsltContext({
+      currentNode: source,
+      currentNodeList: [source],
+      position: 1,
+      outputDocument: resultDocument,
+      stylesheet: this.stylesheetDoc,
+      namespaces: this.namespaces,
+      templates: this.templates,
+      keys: this.keys,
+      decimalFormats: this.decimalFormats,
+      outputMethod: this.outputSettings.method,
+      xpathEvaluator: this.xpathEvaluator,
+    });
+
+    this.rootContext = context;
+    // The source tree may have changed since the previous transformation
+    this.keyRegistry.clear();
+    this.patternMatcher.reset();
+    this.xpathEvaluator.resetNamespaceNodes();
+    // Document order from positions numbered once, unless the DOM compares
+    // positions natively (see documentOrder.js)
+    this.xpathEvaluator.resetDocumentOrder(
+      hasNativePositionComparison(source) ? null : new DocumentOrderIndex(),
+    );
+    this.numberMemos = new WeakMap();
+
+    const fragment = resultDocument.createDocumentFragment();
+    try {
+      context.globals = this.createGlobals(context);
+      context.globals.evaluateAll();
+      this.applyTemplates([source], null, context, fragment);
+    } catch (error) {
+      throw recursionError(error);
+    }
+    return fragment;
+  },
+
+  /**
+   * Choose the node the transformation starts from.
+   *
+   * A document element is transformed through its document, so that the "/"
+   * template rule applies as for a whole document (as browsers do); any other
+   * node is transformed as is.
+   *
+   * @param {Node} source - The (prepared) source node
+   * @returns {Node} The initial context node
+   */
+  initialNode(source) {
+    const owner = source.ownerDocument;
+    return source.nodeType === 1 && owner?.documentElement === source
+      ? owner
+      : source;
+  },
+
+  /**
+   * Apply `xsl:strip-space` to the source tree.
+   *
+   * Stripping produces a copy so the caller's document is never modified; when
+   * no `xsl:strip-space` is declared the original node is used unchanged.
+   *
+   * @param {Node} sourceNode - The source document or element
+   * @param {Document} ownerDocument - Document providing the DOM implementation
+   * @returns {Node} The source to transform
+   */
+  prepareSource(sourceNode, ownerDocument) {
+    const filter = new WhitespaceFilter(this.stripSpace, this.preserveSpace);
+    if (!filter.isActive()) return sourceNode;
+
+    return stripWhitespaceNodes(
+      sourceNode,
+      filter,
+      createResultDocument(ownerDocument),
+    );
+  },
+
+  /**
+   * Transform to a complete document, shaped as Chrome's XSLTProcessor
+   * returns it (see resultDocument.js): with `method="text"` an XHTML page
+   * holding the text in a `pre` element (see wrapTextResult), with the html
+   * method (declared or detected) an HTML document parsed from the html
+   * output, otherwise an XML document of the result nodes.
+   *
+   * @param {Node} sourceNode - Source document or element to transform
+   * @returns {Document} The result document
+   */
+  transformToDocument(sourceNode) {
+    const doc = this.createDocument(sourceNode);
+    const fragment = this.transform(sourceNode, doc);
+
+    if (this.outputSettings.method === "text") {
+      return wrapTextResult(doc, fragment.textContent);
+    }
+    const settings = resolveOutputSettings(this.outputSettings, fragment);
+    if (settings.method === "html") {
+      const markup = serializeResult(fragment, this.outputSettings);
+      const htmlDoc = parseHtmlDocument(markup, doc);
+      if (htmlDoc) return htmlDoc;
+    }
+    return fillXmlDocument(doc, fragment, settings);
+  },
+
+  /**
+   * Transform a source document and serialize the result to a string.
+   *
+   * Non-W3C convenience method: the result tree is serialized honoring the
+   * `xsl:output` settings of the stylesheet (XSLT 1.0 section 16).
+   *
+   * @param {Node} sourceNode - Source document or element to transform
+   * @returns {string} The serialized transformation result
+   */
+  transformToString(sourceNode) {
+    const fragment = this.buildResultTree(
+      sourceNode,
+      this.createDocument(sourceNode),
+    );
+    return serializeResult(fragment, this.outputSettings);
+  },
+
+  /**
+   * Create an empty XML document to hold a transformation result.
+   *
+   * Uses the global `document` when running in a browser and otherwise falls
+   * back to the DOM implementation owning `referenceNode` (e.g. a jsdom or
+   * xmldom document in Node.js).
+   *
+   * @param {Node} [referenceNode] - Any node whose DOM implementation can be reused
+   * @returns {Document} A new empty document
+   * @throws {Error} When no DOM implementation is available
+   */
+  createDocument(referenceNode) {
+    if (typeof document !== "undefined") {
+      return document.implementation.createDocument(null, null, null);
+    }
+
+    const ownerDocument =
+      referenceNode &&
+      (referenceNode.nodeType === 9
+        ? referenceNode
+        : referenceNode.ownerDocument);
+    if (ownerDocument?.implementation) {
+      return ownerDocument.implementation.createDocument(null, null, null);
+    }
+
+    throw new Error("Document creation not available in this environment");
+  },
+};

package/src/xslt/engine/workStack.js

@@ -0,0 +1,245 @@
+/**
+ * Explicit work stack for template instantiation.
+ *
+ * Recursive stylesheets nest template invocations thousands of levels deep
+ * (libxslt allows 3000). Instantiating each level with JavaScript recursion
+ * costs several native frames per level and overflows the call stack of
+ * browsers and Node long before that, so the engine keeps the pending work
+ * in frames on an explicit stack instead:
+ *
+ * - a SequenceFrame walks the children of a stylesheet element (a sequence
+ *   constructor: a template body, the content of xsl:if, a literal result
+ *   element, ...);
+ * - a LoopFrame visits the items of xsl:apply-templates or xsl:for-each.
+ *
+ * An instruction whose content comes last (xsl:if, xsl:choose,
+ * xsl:call-template, literal result elements, ...) schedules that content
+ * with {@link workStackMethods.continueWith} and returns; the driver loop
+ * runs it before the next sibling of the instruction. The native stack then
+ * stays flat however deep the templates nest. Instructions that need the
+ * result at once (xsl:attribute, xsl:with-param content, ...) run a nested
+ * driver with {@link workStackMethods.runFrame}.
+ *
+ * Methods installed on XsltEngine.prototype (`this` is the engine).
+ */
+
+import { inScopeNamespaces } from "../stylesheetNamespaces.js";
+
+/**
+ * Deepest nesting of template instantiations in a transformation, the
+ * default of libxslt's `xsltMaxDepth`. Deeper recursion is reported as a
+ * potential infinite recursion. Override it with the `maxTemplateDepth`
+ * engine option.
+ */
+export const XSLT_MAX_TEMPLATE_DEPTH = 3000;
+
+/**
+ * Pending instantiation of the children of a stylesheet element.
+ */
+export class SequenceFrame {
+  /**
+   * A body declaring variables gets its own copy of the local bindings: a
+   * variable is visible to its following siblings and their descendants only.
+   *
+   * @param {object} engine - The engine
+   * @param {Element|object} node - The parent stylesheet element
+   * @param {XsltContext} context - The current context
+   * @param {Node} output - The result node receiving the output
+   * @param {(() => void)|null} [onDone] - Called once the children are done
+   */
+  constructor(engine, node, context, output, onDone = null) {
+    this.scope = engine.declaresVariables(node) ? context.clone() : context;
+    this.saved = this.scope.namespaces;
+    this.next = node.firstChild;
+    this.output = output;
+    // Not named `then`: an object with a `then` method is treated as a promise
+    this.onDone = onDone;
+    // Whether the frame is a template instantiation (counted in the depth)
+    this.template = false;
+  }
+
+  /**
+   * Instantiate children until one schedules further frames or none is left.
+   *
+   * @param {object} engine - The engine
+   * @param {object[]} frames - The work stack
+   * @returns {boolean} False when every child is done
+   */
+  advance(engine, frames) {
+    const height = frames.length;
+    const scope = this.scope;
+    for (let child = this.next; child; child = this.next) {
+      this.next = child.nextSibling;
+      const type = child.nodeType;
+      if (type === 1) {
+        // Prefixes resolve against the namespaces in scope on the element
+        scope.namespaces = inScopeNamespaces(child);
+        const method = engine.instructionMethod(child);
+        if (method) engine[method](child, scope, this.output);
+      } else if (type === 3 || type === 4) {
+        engine.processText(child, scope, this.output);
+      }
+      if (frames.length !== height) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Leave the frame, completed or abandoned by an error.
+   *
+   * @param {object} engine - The engine
+   * @returns {void}
+   */
+  release(engine) {
+    this.scope.namespaces = this.saved;
+    if (this.template) engine.templateDepth--;
+  }
+
+  /**
+   * Complete the frame.
+   *
+   * @param {object} engine - The engine
+   * @returns {void}
+   */
+  finish(engine) {
+    this.release(engine);
+    if (this.onDone) this.onDone();
+  }
+}
+
+/**
+ * Pending visits of the items of a list (the nodes of xsl:apply-templates
+ * or xsl:for-each), one at a time.
+ */
+export class LoopFrame {
+  /**
+   * @param {number} count - Number of items
+   * @param {(index: number) => void} visit - Instantiates one item; it may
+   *   schedule frames, which run before the next item
+   */
+  constructor(count, visit) {
+    this.count = count;
+    this.index = 0;
+    this.visit = visit;
+    this.template = false;
+  }
+
+  /**
+   * Visit items until one schedules further frames or none is left.
+   *
+   * @param {object} _engine - The engine
+   * @param {object[]} frames - The work stack
+   * @returns {boolean} False when every item is done
+   */
+  advance(_engine, frames) {
+    const height = frames.length;
+    while (this.index < this.count) {
+      this.visit(this.index++);
+      if (frames.length !== height) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Leave the frame, completed or abandoned by an error.
+   *
+   * @param {object} engine - The engine
+   * @returns {void}
+   */
+  release(engine) {
+    if (this.template) engine.templateDepth--;
+  }
+
+  /**
+   * Complete the frame.
+   *
+   * @param {object} engine - The engine
+   * @returns {void}
+   */
+  finish(engine) {
+    this.release(engine);
+  }
+}
+
+export const workStackMethods = {
+  /**
+   * Run a frame, and the frames it schedules, to completion.
+   *
+   * The outermost call owns the work stack of the transformation; nested
+   * calls (content whose result is needed at once) run on top of it.
+   *
+   * @param {SequenceFrame|LoopFrame} frame - The frame
+   * @returns {void}
+   */
+  runFrame(frame) {
+    const outermost = this.frames === null;
+    if (outermost) {
+      this.frames = [];
+      this.templateDepth = 0;
+    }
+    const frames = this.frames;
+    const base = frames.length;
+    try {
+      this.pushFrame(frame);
+      while (frames.length > base) {
+        const top = frames[frames.length - 1];
+        if (!top.advance(this, frames)) {
+          frames.pop();
+          top.finish(this);
+        }
+      }
+    } catch (error) {
+      this.unwindFrames(base);
+      throw error;
+    } finally {
+      if (outermost) this.frames = null;
+    }
+  },
+
+  /**
+   * Schedule a frame to run once the current instruction returns, before
+   * its next sibling; without a running work stack, run it now.
+   *
+   * The instruction must not use the output of the frame afterwards.
+   *
+   * @param {SequenceFrame|LoopFrame} frame - The frame
+   * @returns {void}
+   */
+  continueWith(frame) {
+    if (this.frames === null) this.runFrame(frame);
+    else this.pushFrame(frame);
+  },
+
+  /**
+   * Push a frame on the work stack, counting template instantiations.
+   *
+   * @param {SequenceFrame|LoopFrame} frame - The frame
+   * @returns {void}
+   * @throws {Error} When the frame would nest templates deeper than
+   *   `maxTemplateDepth`
+   */
+  pushFrame(frame) {
+    if (frame.template) {
+      if (this.templateDepth >= this.maxTemplateDepth) {
+        throw new Error(
+          `Template recursion too deep: more than ${this.maxTemplateDepth} ` +
+            "nested template invocations, a potential infinite recursion " +
+            "(raise the maxTemplateDepth option to allow deeper recursion)",
+        );
+      }
+      this.templateDepth++;
+    }
+    this.frames.push(frame);
+  },
+
+  /**
+   * Drop the frames above a height after an error.
+   *
+   * @param {number} base - The height to return to
+   * @returns {void}
+   */
+  unwindFrames(base) {
+    const frames = this.frames;
+    while (frames.length > base) frames.pop().release(this);
+  },
+};