@tradik/xslt-processor 1.0.3 → 1.3.0

package/src/xslt/sort.js

@@ -0,0 +1,151 @@
+/**
+ * xsl:sort (XSLT 1.0 section 10).
+ *
+ * Sort keys are computed once per node (decorate, sort, undecorate) instead of
+ * once per comparison, and the attributes `order`, `lang`, `data-type` and
+ * `case-order` are evaluated as attribute value templates.
+ *
+ * Text keys are compared by Unicode code point unless `lang` or `case-order`
+ * is given. That matches libxslt, the engine behind the native XSLTProcessor
+ * in Chromium browsers, so a stylesheet sorts the same way with this library
+ * as it did natively. With `lang` or `case-order` an `Intl.Collator` is used.
+ *
+ * @module xslt/sort
+ */
+
+/**
+ * Compare two strings by Unicode code point (not by UTF-16 code unit).
+ *
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} Negative, zero or positive
+ */
+export function compareCodePoints(a, b) {
+  const left = a[Symbol.iterator]();
+  const right = b[Symbol.iterator]();
+
+  for (;;) {
+    const x = left.next();
+    const y = right.next();
+    if (x.done || y.done) return Number(y.done) - Number(x.done) || 0;
+    const diff = x.value.codePointAt(0) - y.value.codePointAt(0);
+    if (diff !== 0) return diff;
+  }
+}
+
+/**
+ * Compare two numeric sort keys; NaN precedes every number (section 10).
+ *
+ * @param {number} a - First key
+ * @param {number} b - Second key
+ * @returns {number} Negative, zero or positive
+ */
+export function compareNumbers(a, b) {
+  const aNaN = Number.isNaN(a);
+  const bNaN = Number.isNaN(b);
+  if (aNaN || bNaN) return Number(bNaN) - Number(aNaN) || 0;
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+/**
+ * Build the text comparator for one sort key.
+ *
+ * @param {string} lang - Evaluated `lang` attribute (may be empty)
+ * @param {string} caseOrder - Evaluated `case-order` attribute (may be empty)
+ * @returns {(a: string, b: string) => number} The comparator
+ */
+function textComparator(lang, caseOrder) {
+  if (!lang && !caseOrder) return compareCodePoints;
+
+  let collator;
+  try {
+    collator = new Intl.Collator(lang || undefined, {
+      caseFirst: caseOrder === "lower-first" ? "lower" : "upper",
+      sensitivity: "variant",
+    });
+  } catch {
+    collator = new Intl.Collator(undefined, {
+      caseFirst: caseOrder === "lower-first" ? "lower" : "upper",
+      sensitivity: "variant",
+    });
+  }
+  return collator.compare;
+}
+
+/**
+ * @typedef {object} SortHost
+ * @property {(expr: string, context: object) => *} evaluate - Evaluate an XPath expression
+ * @property {(value: string, context: object) => string} avt - Evaluate an attribute value template
+ * @property {(value: *) => string} toString - XPath string() conversion
+ * @property {(value: *) => number} toNumber - XPath number() conversion
+ */
+
+/**
+ * Resolve one xsl:sort element into a key specification.
+ *
+ * @param {Element} element - The xsl:sort element
+ * @param {object} context - Context of the sorting instruction (for AVTs)
+ * @param {SortHost} host - Engine callbacks
+ * @returns {{select: string, descending: boolean, numeric: boolean, compare: Function}} Specification
+ */
+export function resolveSortSpec(element, context, host) {
+  const attribute = (name) => {
+    const raw = element.getAttribute(name);
+    return raw ? host.avt(raw, context).trim() : "";
+  };
+
+  const dataType = attribute("data-type");
+  const numeric = dataType === "number";
+
+  return {
+    select: element.getAttribute("select") || ".",
+    descending: attribute("order") === "descending",
+    numeric,
+    compare: numeric
+      ? compareNumbers
+      : textComparator(attribute("lang"), attribute("case-order")),
+  };
+}
+
+/**
+ * Sort a node list by the given xsl:sort elements.
+ *
+ * Each key is evaluated with the node as current node, the unsorted list as
+ * current node list and the node's position in that list, as the
+ * specification requires. Ties keep the original order.
+ *
+ * @param {Node[]} nodes - Nodes in their original (document) order
+ * @param {Element[]} sortElements - The xsl:sort children, in order
+ * @param {object} context - XSLT context of the sorting instruction
+ * @param {SortHost} host - Engine callbacks
+ * @returns {Node[]} A new, sorted array
+ */
+export function sortNodes(nodes, sortElements, context, host) {
+  if (sortElements.length === 0 || nodes.length < 2) return [...nodes];
+
+  const specs = sortElements.map((el) => resolveSortSpec(el, context, host));
+
+  const rows = nodes.map((node, index) => {
+    const nodeContext = context.clone({
+      currentNode: node,
+      currentNodeList: nodes,
+      position: index + 1,
+    });
+    const keys = specs.map((spec) => {
+      const text = host.toString(host.evaluate(spec.select, nodeContext));
+      return spec.numeric ? host.toNumber(text) : text;
+    });
+    return { node, index, keys };
+  });
+
+  rows.sort((a, b) => {
+    for (let k = 0; k < specs.length; k++) {
+      const cmp = specs[k].compare(a.keys[k], b.keys[k]);
+      if (cmp !== 0) return specs[k].descending ? -cmp : cmp;
+    }
+    return a.index - b.index;
+  });
+
+  return rows.map((row) => row.node);
+}

package/src/xslt/spaceNameTests.js

@@ -0,0 +1,115 @@
+/**
+ * Name tests of `xsl:strip-space` and `xsl:preserve-space` (XSLT 1.0
+ * section 3.4).
+ *
+ * The `elements` attribute lists XPath name tests: `*`, `prefix:*` or a
+ * QName. The prefixes are expanded with the namespace declarations in scope
+ * on the declaring element, and an unprefixed name only matches elements in
+ * no namespace (XPath 1.0 section 2.3), so `p:*` matches by namespace URI
+ * whatever prefix the source document uses. Name tests given as plain
+ * strings (the {@link WhitespaceFilter} API before 1.2.0) are still matched
+ * by their lexical name.
+ *
+ * @module xslt/spaceNameTests
+ */
+
+"use strict";
+
+import { isQName } from "./qname.js";
+import { splitQName } from "./resultNamespaces.js";
+import { inScopeNamespaces, resolvePrefix } from "./stylesheetNamespaces.js";
+
+/**
+ * @typedef {Object} ElementNameTest
+ * @property {string|null|undefined} namespaceUri - The namespace to match,
+ *   null for no namespace, undefined for any (the `*` test)
+ * @property {string} localName - The local name, `*` for any
+ */
+
+/**
+ * Expand the name tests of an `elements` attribute.
+ *
+ * @param {string|null} value - Whitespace separated name tests
+ * @param {Element} element - The xsl:strip-space or xsl:preserve-space element
+ * @param {(message: string) => void} warn - Reports a skipped name test
+ * @returns {ElementNameTest[]} The expanded name tests
+ *
+ * @example
+ * // <xsl:strip-space xmlns:m="urn:m" elements="m:* p *"/>
+ * compileSpaceNameTests("m:* p *", element, console.warn);
+ * // [{ namespaceUri: "urn:m", localName: "*" },
+ * //  { namespaceUri: null, localName: "p" },
+ * //  { namespaceUri: undefined, localName: "*" }]
+ */
+export function compileSpaceNameTests(value, element, warn) {
+  const tests = [];
+  for (const token of (value ?? "").split(/[ \t\r\n]+/).filter(Boolean)) {
+    if (token === "*") {
+      tests.push({ namespaceUri: undefined, localName: "*" });
+      continue;
+    }
+    const { prefix, localName } = splitQName(token);
+    const qname = localName === "*" ? `${prefix}:x` : token;
+    const namespaceUri = prefix
+      ? resolvePrefix(inScopeNamespaces(element), prefix)
+      : null;
+    if (!isQName(qname) || (prefix && !namespaceUri)) {
+      warn(
+        `xsl:${element.localName} elements: "${token}" is not a name test with a declared prefix and is ignored`,
+      );
+      continue;
+    }
+    tests.push({ namespaceUri, localName });
+  }
+  return tests;
+}
+
+/**
+ * The XSLT default priority of an element name test (section 5.5).
+ *
+ * @param {string|ElementNameTest} nameTest - A name test
+ * @returns {number} -0.5 for `*`, -0.25 for `prefix:*`, 0 for a name
+ */
+export function nameTestPriority(nameTest) {
+  if (typeof nameTest === "string") {
+    if (nameTest === "*") return -0.5;
+    return nameTest.endsWith(":*") ? -0.25 : 0;
+  }
+  if (nameTest.namespaceUri === undefined) return -0.5;
+  return nameTest.localName === "*" ? -0.25 : 0;
+}
+
+/**
+ * Whether an element matches a lexical name test (the string API).
+ *
+ * @param {Element} element - The element to test
+ * @param {string} nameTest - `*`, `prefix:*` or a name
+ * @returns {boolean} True when the element matches
+ */
+function matchesLexicalTest(element, nameTest) {
+  if (nameTest === "*") return true;
+  if (nameTest.endsWith(":*")) {
+    return element.nodeName.startsWith(`${nameTest.slice(0, -2)}:`);
+  }
+  return element.nodeName === nameTest || element.localName === nameTest;
+}
+
+/**
+ * Whether an element matches a name test.
+ *
+ * @param {Element} element - The element to test
+ * @param {string|ElementNameTest} nameTest - A name test
+ * @returns {boolean} True when the element matches
+ *
+ * @example
+ * matchesNameTest(pElement, { namespaceUri: null, localName: "p" }); // true
+ */
+export function matchesNameTest(element, nameTest) {
+  if (typeof nameTest === "string") {
+    return matchesLexicalTest(element, nameTest);
+  }
+  const { namespaceUri, localName } = nameTest;
+  if (namespaceUri === undefined) return true;
+  if ((element.namespaceURI || null) !== namespaceUri) return false;
+  return localName === "*" || element.localName === localName;
+}

package/src/xslt/stylesheetChecks.js

@@ -0,0 +1,206 @@
+/**
+ * Static checks run while a stylesheet is compiled.
+ *
+ * - Patterns (XSLT 1.0 section 5.2) of `xsl:template match`, `xsl:key match`
+ *   and `xsl:number count`/`from` are compiled at import time, so an invalid
+ *   pattern makes `importStylesheet` fail with an error naming it, as libxslt
+ *   (and so the browsers' XSLTProcessor) rejects such a stylesheet.
+ * - Two global xsl:variable elements of the same name and import precedence
+ *   (section 11.4) and text at the top level of a stylesheet (section 2.2)
+ *   make `importStylesheet` fail, as libxslt rejects such a stylesheet.
+ * - Two local variables or parameters of the same name where one is in the
+ *   scope of the other (section 11.5), and a global xsl:param clashing with
+ *   another global binding of the same import precedence (section 11.4),
+ *   are errors libxslt only reports; they are warned about here, and the
+ *   binding used so far keeps being used.
+ *
+ * @module xslt/stylesheetChecks
+ */
+
+"use strict";
+
+import { XSLT_NAMESPACE } from "./elements.js";
+
+/**
+ * The local name of an XSLT element, or null for any other node.
+ *
+ * @param {Node} node - A stylesheet node
+ * @returns {string|null} e.g. "number" for xsl:number
+ */
+export function xsltLocalName(node) {
+  if (node.nodeType !== 1) return null;
+  if (node.namespaceURI === XSLT_NAMESPACE) return node.localName;
+  return node.nodeName.startsWith("xsl:") ? node.nodeName.slice(4) : null;
+}
+
+/**
+ * Visit every element below a node, in document order.
+ *
+ * @param {Node} root - The subtree root (not visited itself)
+ * @param {(element: Element) => void} visit - Called for each element
+ * @returns {void}
+ */
+function forEachDescendant(root, visit) {
+  for (let child = root.firstChild; child; child = child.nextSibling) {
+    if (child.nodeType !== 1) continue;
+    visit(child);
+    forEachDescendant(child, visit);
+  }
+}
+
+/**
+ * Compile a pattern of the stylesheet, reporting where it comes from when
+ * it is invalid.
+ *
+ * @param {{compile: (pattern: string) => object[]}} matcher - The pattern matcher
+ * @param {string} pattern - The pattern
+ * @param {string} where - The attribute holding it, e.g. "xsl:template match"
+ * @returns {void}
+ * @throws {Error} When the pattern is invalid
+ *
+ * @example
+ * checkPattern(matcher, "a/..", "xsl:template match");
+ * // Error: xsl:template match: Invalid pattern "a/..": Axis not allowed ...
+ */
+export function checkPattern(matcher, pattern, where) {
+  try {
+    matcher.compile(pattern);
+  } catch (error) {
+    throw new Error(`${where}: ${error.message}`, { cause: error });
+  }
+}
+
+/**
+ * Compile the `count` and `from` patterns of every `xsl:number` below a
+ * stylesheet element (they are not attribute value templates, so they are
+ * known at compile time).
+ *
+ * @param {{compile: (pattern: string) => object[]}} matcher - The pattern matcher
+ * @param {Element} root - The stylesheet (or simplified stylesheet) element
+ * @returns {void}
+ * @throws {Error} When one of the patterns is invalid
+ */
+export function checkNumberPatterns(matcher, root) {
+  forEachDescendant(root, (element) => {
+    if (xsltLocalName(element) !== "number") return;
+    for (const attribute of ["count", "from"]) {
+      const pattern = element.getAttribute(attribute);
+      if (pattern) checkPattern(matcher, pattern, `xsl:number ${attribute}`);
+    }
+  });
+}
+
+/**
+ * A short description of the declaration holding local bindings.
+ *
+ * @param {Element} declaration - xsl:template, xsl:variable, ...
+ * @returns {string} e.g. `template match="/"`
+ */
+function describeDeclaration(declaration) {
+  const kind = xsltLocalName(declaration) ?? declaration.nodeName;
+  for (const attribute of ["match", "name"]) {
+    const value = declaration.getAttribute(attribute);
+    if (value !== null) return `${kind} ${attribute}="${value}"`;
+  }
+  return kind;
+}
+
+/**
+ * Walk a sequence constructor, reporting bindings that shadow another local
+ * binding in scope. A binding is in scope for its following siblings and
+ * their descendants, not for its own content.
+ *
+ * @param {Element} parent - The element whose children are walked
+ * @param {Set<string>} inScope - Local names bound around `parent`
+ * @param {(name: string) => void} report - Called for each duplicate
+ * @returns {void}
+ */
+function walkBindings(parent, inScope, report) {
+  let scope = inScope;
+  for (let child = parent.firstChild; child; child = child.nextSibling) {
+    if (child.nodeType !== 1) continue;
+    const kind = xsltLocalName(child);
+    walkBindings(child, scope, report);
+    if (kind !== "variable" && kind !== "param") continue;
+
+    const name = child.getAttribute("name");
+    if (scope.has(name)) report(name);
+    scope = new Set(scope).add(name);
+  }
+}
+
+/**
+ * Warn about local variables and parameters that shadow another local
+ * binding of the same declaration (XSLT 1.0 section 11.5). A local binding
+ * shadowing a global one is allowed and not reported.
+ *
+ * @param {Element} declaration - A top-level element (xsl:template,
+ *   xsl:variable, xsl:param, xsl:attribute-set)
+ * @param {(message: string) => void} warn - Reports one duplicate
+ * @returns {void}
+ *
+ * @example
+ * checkLocalBindings(templateElement, (m) => console.warn(m));
+ */
+export function checkLocalBindings(declaration, warn) {
+  walkBindings(declaration, new Set(), (name) =>
+    warn(
+      `duplicate binding of variable $${name} in ${describeDeclaration(declaration)}; the later one is used (XSLT 1.0 section 11.5)`,
+    ),
+  );
+}
+
+/**
+ * Check a global variable or parameter repeating the name of an earlier one
+ * with the same import precedence (XSLT 1.0 section 11.4). Two
+ * xsl:variable elements are an error, as in libxslt; a clash involving an
+ * xsl:param is warned about, naming the binding the engine uses: the later
+ * declaration, except that a global xsl:variable wins over an xsl:param.
+ *
+ * @param {{name: string, kind: string, precedence: number}} declaration - The
+ *   new declaration: its name, "variable" or "param", and import precedence
+ * @param {{variable?: object, param?: object}} earlier - The definitions
+ *   registered so far under that name (with `node` and `importPrecedence`)
+ * @param {(message: string) => void} warn - Reports the duplicate
+ * @returns {void}
+ * @throws {Error} When an xsl:variable repeats an xsl:variable
+ *
+ * @example
+ * checkGlobalDuplicate({ name: "v", kind: "param", precedence: 1 },
+ *   { variable: { node, importPrecedence: 1 } }, console.warn);
+ */
+export function checkGlobalDuplicate(declaration, earlier, warn) {
+  const { name, kind, precedence } = declaration;
+  const clashes = (definition) =>
+    Boolean(definition?.node) && definition.importPrecedence === precedence;
+  if (kind === "variable" && clashes(earlier.variable)) {
+    throw new Error(
+      `redefinition of global variable $${name} at the same import precedence (XSLT 1.0 section 11.4)`,
+    );
+  }
+  if (!clashes(earlier.variable) && !clashes(earlier.param)) return;
+  const used =
+    kind === "param" && earlier.variable ? "the xsl:variable" : "the later one";
+  warn(
+    `duplicate global binding of variable $${name} at the same import precedence; ${used} is used (XSLT 1.0 section 11.4)`,
+  );
+}
+
+/**
+ * Reject text other than whitespace among the top-level elements of a
+ * stylesheet (XSLT 1.0 section 2.2), as libxslt does.
+ *
+ * @param {Element} root - The xsl:stylesheet or xsl:transform element
+ * @returns {void}
+ * @throws {Error} When a text node holds non-whitespace characters
+ */
+export function checkTopLevelText(root) {
+  for (let child = root.firstChild; child; child = child.nextSibling) {
+    const isText = child.nodeType === 3 || child.nodeType === 4;
+    if (isText && /[^ \t\r\n]/.test(child.nodeValue)) {
+      throw new Error(
+        `misplaced text at the top level of the stylesheet: "${child.nodeValue.trim()}" (XSLT 1.0 section 2.2)`,
+      );
+    }
+  }
+}