@tradik/xslt-processor 1.1.1 → 1.3.0

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)`,
+      );
+    }
+  }
+}

package/src/xslt/stylesheetNamespaces.js

@@ -0,0 +1,266 @@
+/**
+ * In-scope namespaces of stylesheet elements.
+ *
+ * Prefixes in XPath expressions, patterns and QName-valued attributes resolve
+ * against the namespace declarations in scope on the element that carries
+ * them (XSLT 1.0 section 2.4), not against one stylesheet-wide table: a
+ * declaration on `xsl:template` or on a literal result element applies inside
+ * it only, and an included stylesheet may bind a prefix differently from the
+ * including one. The same bindings are the namespace nodes that literal
+ * result elements copy to the result tree (section 7.1.1), minus the XSLT
+ * namespace and the excluded and extension prefixes.
+ *
+ * Every map is computed once per element and cached; an element without
+ * declarations of its own shares its parent's (frozen) map, so identical
+ * scopes can be recognised by identity.
+ *
+ * @module xslt/stylesheetNamespaces
+ */
+
+"use strict";
+
+import { XSLT_NAMESPACE } from "./elements.js";
+
+/** Namespace of `xmlns` attributes. */
+export const XMLNS_NAMESPACE = "http://www.w3.org/2000/xmlns/";
+
+/** Namespace bound to the `xml` prefix. */
+export const XML_NAMESPACE = "http://www.w3.org/XML/1998/namespace";
+
+/** The scope above the stylesheet document element. */
+const EMPTY_SCOPE = Object.freeze({});
+
+/** Namespaces excluded above the stylesheet document element. */
+const BASE_EXCLUSIONS = new Set([XSLT_NAMESPACE]);
+
+/** No extension namespaces, above the stylesheet document element. */
+const NO_EXTENSIONS = new Set();
+
+const scopes = new WeakMap();
+const exclusions = new WeakMap();
+const extensions = new WeakMap();
+const namespaceNodes = new WeakMap();
+
+/**
+ * The prefix a namespace declaration attribute declares, or null when the
+ * attribute is not a declaration.
+ *
+ * @param {Attr} attribute - Any attribute
+ * @returns {string|null} The prefix, "" for a default namespace declaration
+ */
+export function declaredPrefix(attribute) {
+  const name = attribute.name;
+  if (name === "xmlns") return "";
+  if (name.startsWith("xmlns:")) return name.slice(6);
+  return null;
+}
+
+/**
+ * The namespace bindings in scope on a stylesheet element.
+ *
+ * @param {Node|null} node - A stylesheet element (other nodes have no scope)
+ * @returns {Readonly<Object<string, string>>} URIs by prefix; "" holds the
+ *   default namespace, an empty URI means "undeclared"
+ *
+ * @example
+ * inScopeNamespaces(templateElement).f; // "urn:f"
+ */
+export function inScopeNamespaces(node) {
+  if (node?.nodeType !== 1) return EMPTY_SCOPE;
+
+  let scope = scopes.get(node);
+  if (scope) return scope;
+
+  const parentScope = inScopeNamespaces(node.parentNode);
+  let own = null;
+  for (const attribute of node.attributes) {
+    const prefix = declaredPrefix(attribute);
+    if (prefix === null) continue;
+    own ??= {};
+    own[prefix] = attribute.value;
+  }
+
+  scope = own ? Object.freeze({ ...parentScope, ...own }) : parentScope;
+  scopes.set(node, scope);
+  return scope;
+}
+
+/**
+ * Split an XSLT attribute holding whitespace separated prefixes.
+ *
+ * @param {string|null} value - e.g. `"a b #default"`
+ * @returns {string[]} The prefixes, "" standing for `#default`
+ */
+function prefixList(value) {
+  if (!value) return [];
+  return value
+    .split(/[ \t\r\n]+/)
+    .filter(Boolean)
+    .map((prefix) => (prefix === "#default" ? "" : prefix));
+}
+
+/** Attributes whose prefixes are excluded from the result tree. */
+const EXCLUSION_ATTRIBUTES = [
+  "exclude-result-prefixes",
+  "extension-element-prefixes",
+];
+
+/** Attributes declaring extension namespaces (XSLT 1.0 section 14.1). */
+const EXTENSION_ATTRIBUTES = ["extension-element-prefixes"];
+
+/**
+ * Read prefix list attributes of one stylesheet element: unqualified on
+ * `xsl:stylesheet`, `xsl:`-qualified on literal result elements.
+ *
+ * @param {Element} element - A stylesheet element
+ * @param {string[]} attributes - Local names of the attributes to read
+ * @returns {Array<{prefix: string, attribute: string}>} Prefixes declared on
+ *   this element, with the attribute declaring each
+ */
+function ownPrefixes(element, attributes) {
+  const isXslt = element.namespaceURI === XSLT_NAMESPACE;
+  const read = (localName) =>
+    isXslt
+      ? element.getAttribute(localName)
+      : element.getAttributeNS(XSLT_NAMESPACE, localName);
+  return attributes.flatMap((attribute) =>
+    prefixList(read(attribute)).map((prefix) => ({ prefix, attribute })),
+  );
+}
+
+/**
+ * Namespace URIs named by prefix list attributes on a stylesheet element or
+ * its ancestors, cached per element.
+ *
+ * @param {Node|null} node - A stylesheet element
+ * @param {object} kind - What to collect
+ * @param {string[]} kind.attributes - The prefix list attributes
+ * @param {WeakMap<Element, Set<string>>} kind.cache - Results by element
+ * @param {Set<string>} kind.base - The set above the document element
+ * @param {boolean} kind.report - Whether undeclared prefixes are reported
+ * @returns {Set<string>} The namespace URIs
+ */
+function declaredNamespaces(node, kind) {
+  if (node?.nodeType !== 1) return kind.base;
+
+  let found = kind.cache.get(node);
+  if (found) return found;
+
+  found = declaredNamespaces(node.parentNode, kind);
+  const prefixes = ownPrefixes(node, kind.attributes);
+  if (prefixes.length > 0) {
+    const scope = inScopeNamespaces(node);
+    found = new Set(found);
+    for (const { prefix, attribute } of prefixes) {
+      const uri = resolvePrefix(scope, prefix);
+      if (uri) {
+        found.add(uri);
+      } else if (kind.report) {
+        // An error in XSLT 1.0 (section 7.1.1) that libxslt reports and
+        // recovers from; reported once, as the result is cached per element
+        console.warn(
+          `XSLT: ${attribute}: undefined namespace prefix "${prefix || "#default"}" is ignored`,
+        );
+      }
+    }
+  }
+  kind.cache.set(node, found);
+  return found;
+}
+
+/** Excluded namespaces: excluded and extension prefixes, plus XSLT. */
+const EXCLUDED = {
+  attributes: EXCLUSION_ATTRIBUTES,
+  cache: exclusions,
+  base: BASE_EXCLUSIONS,
+  report: true,
+};
+
+/** Extension namespaces (reported through EXCLUDED already). */
+const EXTENSIONS = {
+  attributes: EXTENSION_ATTRIBUTES,
+  cache: extensions,
+  base: NO_EXTENSIONS,
+  report: false,
+};
+
+/**
+ * Namespace URIs excluded from the result tree around a stylesheet element:
+ * the XSLT namespace, plus the namespaces of every excluded or extension
+ * prefix declared on the element or its ancestors. A prefix that is not
+ * declared (including `#all`, which XSLT 1.0 does not know) is reported with
+ * console.warn and ignored.
+ *
+ * @param {Node|null} node - A stylesheet element
+ * @returns {Set<string>} Excluded namespace URIs
+ */
+function excludedNamespaces(node) {
+  return declaredNamespaces(node, EXCLUDED);
+}
+
+/**
+ * Whether a stylesheet element is an extension element: an element in a
+ * namespace that an `extension-element-prefixes` attribute on it or on an
+ * ancestor declares as an extension namespace (XSLT 1.0 section 14.1).
+ *
+ * @param {Element} element - A stylesheet element that is not in the XSLT namespace
+ * @returns {boolean} True for extension elements
+ *
+ * @example
+ * // <xsl:stylesheet xmlns:e="urn:e" extension-element-prefixes="e">
+ * isExtensionElement(eElement); // true
+ */
+export function isExtensionElement(element) {
+  const uri = element.namespaceURI;
+  if (!uri) return false;
+  // Resolving the exclusions first reports undeclared prefixes once
+  excludedNamespaces(element);
+  return declaredNamespaces(element, EXTENSIONS).has(uri);
+}
+
+/**
+ * The namespace nodes a literal result element copies to the result tree
+ * (XSLT 1.0 section 7.1.1).
+ *
+ * @param {Element} node - The literal result element
+ * The list is shared by every element with the same scope and exclusions,
+ * so equal lists can be compared by identity.
+ *
+ * @param {Element} node - The literal result element
+ * @returns {Array<[string, string]>} `[prefix, uri]` pairs, "" for the default namespace
+ *
+ * @example
+ * resultNamespaceNodes(literalElement); // [["q", "urn:q"]]
+ */
+export function resultNamespaceNodes(node) {
+  const scope = inScopeNamespaces(node);
+  const excluded = excludedNamespaces(node);
+
+  let byExclusions = namespaceNodes.get(scope);
+  if (!byExclusions) {
+    byExclusions = new WeakMap();
+    namespaceNodes.set(scope, byExclusions);
+  }
+  let nodes = byExclusions.get(excluded);
+  if (!nodes) {
+    nodes = Object.entries(scope).filter(
+      ([, uri]) => uri !== "" && !excluded.has(uri),
+    );
+    byExclusions.set(excluded, nodes);
+  }
+  return nodes;
+}
+
+/**
+ * Resolve a QName prefix against a scope.
+ *
+ * @param {Object<string, string>} scope - Bindings from {@link inScopeNamespaces}
+ * @param {string} prefix - The prefix, "" for the default namespace
+ * @returns {string|null} The namespace URI, or null when unbound
+ */
+export function resolvePrefix(scope, prefix) {
+  if (prefix === "xml") return XML_NAMESPACE;
+  return Object.hasOwn(scope, prefix) && scope[prefix] !== ""
+    ? scope[prefix]
+    : null;
+}

package/src/xslt/variables.js

@@ -0,0 +1,152 @@
+/**
+ * Variable and parameter bindings (XSLT 1.0 section 11).
+ *
+ * Local bindings live in the `variables` and `parameters` objects of an
+ * XSLT context; the engine gives every template invocation empty ones and a
+ * new copy to every sequence constructor that declares a variable, which
+ * makes local variables lexically scoped. Global variables and parameters are
+ * kept in a {@link GlobalBindings} table shared by all contexts of one
+ * transformation and are evaluated lazily, so they may refer to each other in
+ * any order (section 11.4).
+ *
+ * @module xslt/variables
+ */
+
+"use strict";
+
+/** Evaluation states of a global binding. */
+const PENDING = 0;
+const EVALUATING = 1;
+const DONE = 2;
+
+/**
+ * The global variables and parameters of one transformation.
+ */
+export class GlobalBindings {
+  /**
+   * @param {(definition: object) => *} evaluate - Computes the value of a
+   *   definition; called at most once per name
+   */
+  constructor(evaluate) {
+    this.evaluate = evaluate;
+    this.entries = new Map();
+  }
+
+  /**
+   * Declare a global binding. A later declaration of the same name replaces
+   * an earlier one.
+   *
+   * @param {string} name - The variable or parameter name
+   * @param {object} definition - Passed to the evaluate callback
+   * @returns {void}
+   *
+   * @example
+   * globals.define('title', { select: "'Report'" });
+   */
+  define(name, definition) {
+    this.entries.set(name, { definition, state: PENDING, value: undefined });
+  }
+
+  /**
+   * Whether a global binding with that name exists.
+   *
+   * @param {string} name - The variable name
+   * @returns {boolean} True when declared
+   */
+  has(name) {
+    return this.entries.has(name);
+  }
+
+  /**
+   * The value of a global binding, evaluating it on first use.
+   *
+   * @param {string} name - The variable name
+   * @returns {*} The value, undefined when the name is not declared
+   * @throws {Error} When the definition (indirectly) refers to itself
+   *
+   * @example
+   * globals.get('title'); // "Report"
+   */
+  get(name) {
+    const entry = this.entries.get(name);
+    if (!entry) return undefined;
+    if (entry.state === DONE) return entry.value;
+    if (entry.state === EVALUATING) {
+      throw new Error(
+        `Circular definition of global variable $${name} (XSLT 1.0 section 11.4)`,
+      );
+    }
+
+    entry.state = EVALUATING;
+    try {
+      entry.value = this.evaluate(entry.definition);
+    } catch (error) {
+      entry.state = PENDING;
+      throw error;
+    }
+    entry.state = DONE;
+    return entry.value;
+  }
+
+  /**
+   * Evaluate every binding, in declaration order, so that errors and
+   * `xsl:message` side effects of unused globals still surface.
+   *
+   * @returns {void}
+   */
+  evaluateAll() {
+    for (const name of this.entries.keys()) this.get(name);
+  }
+}
+
+/**
+ * Look a variable up in an XSLT context: local variables, then local
+ * parameters, then the globals.
+ *
+ * @param {{variables: object, parameters: object, globals?: GlobalBindings|null}} context - The XSLT context
+ * @param {string} name - The variable name
+ * @returns {{found: boolean, value: *}} Whether it is bound, and its value
+ */
+export function lookupVariable(context, name) {
+  if (Object.hasOwn(context.variables, name)) {
+    return { found: true, value: context.variables[name] };
+  }
+  if (Object.hasOwn(context.parameters, name)) {
+    return { found: true, value: context.parameters[name] };
+  }
+  const globals = context.globals;
+  if (globals?.has(name)) return { found: true, value: globals.get(name) };
+  return { found: false, value: undefined };
+}
+
+/**
+ * Read-only object view of the variables in scope of an XSLT context, in the
+ * shape the XPath evaluator expects (`hasOwnProperty` + property access).
+ * Nothing is copied: lookups read the context live, and globals are only
+ * evaluated when an expression actually refers to them.
+ *
+ * @param {object} context - The XSLT context
+ * @returns {object} A proxy mapping variable names to values
+ *
+ * @example
+ * new XPathContext(node, 1, 1, createVariableView(xsltContext), namespaces);
+ */
+export function createVariableView(context) {
+  const binding = (name) =>
+    typeof name === "string" ? lookupVariable(context, name) : null;
+
+  return new Proxy(Object.create(null), {
+    has: (_target, name) => binding(name)?.found === true,
+    get: (_target, name) => binding(name)?.value,
+    getOwnPropertyDescriptor: (_target, name) => {
+      const found = binding(name);
+      if (!found?.found) return undefined;
+      return {
+        value: found.value,
+        writable: false,
+        enumerable: true,
+        configurable: true,
+      };
+    },
+  });
+}