@tradik/xslt-processor 1.0.3 → 1.3.0

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/templatePriority.js

@@ -0,0 +1,45 @@
+/**
+ * Default template priorities (XSLT 1.0 section 5.5).
+ *
+ * A template rule without an explicit `priority` attribute gets a default
+ * priority derived from the shape of its match pattern. A union pattern is
+ * treated as a set of template rules, one per alternative, so each
+ * alternative must be assigned its own priority by the caller.
+ *
+ * @module xslt/templatePriority
+ */
+
+const NAME = String.raw`[A-Za-z_][\w.-]*`;
+const QNAME = `(?:${NAME}:)?${NAME}`;
+
+/** Patterns of the form `name`, `prefix:name`, `@name`, `@prefix:name`. */
+const QNAME_PATTERN = new RegExp(`^(?:child::|attribute::|@)?${QNAME}$`);
+
+/** Patterns of the form `prefix:*` or `@prefix:*`. */
+const PREFIX_WILDCARD_PATTERN = new RegExp(
+  String.raw`^(?:child::|attribute::|@)?${NAME}:\*$`,
+);
+
+/** Patterns of the form `*`, `@*`, `node()`, `text()`, `comment()`, `processing-instruction()`. */
+const NODE_TEST_PATTERN =
+  /^(?:child::|attribute::|@)?(?:\*|node\(\)|text\(\)|comment\(\)|processing-instruction\(\))$/;
+
+/** `processing-instruction('literal')` patterns. */
+const PI_LITERAL_PATTERN =
+  /^(?:child::)?processing-instruction\(\s*(?:"[^"]*"|'[^']*')\s*\)$/;
+
+/**
+ * Compute the default priority of a single (non-union) match pattern.
+ *
+ * @param {string|null|undefined} pattern - The match pattern, already trimmed
+ * @returns {number} -0.5, -0.25, 0 or 0.5 as defined by the specification
+ */
+export function calculatePriority(pattern) {
+  if (!pattern) return 0.5;
+
+  if (NODE_TEST_PATTERN.test(pattern)) return -0.5;
+  if (PREFIX_WILDCARD_PATTERN.test(pattern)) return -0.25;
+  if (QNAME_PATTERN.test(pattern) || PI_LITERAL_PATTERN.test(pattern)) return 0;
+
+  return 0.5;
+}

package/src/xslt/uri.js

@@ -0,0 +1,68 @@
+/**
+ * URI helpers for XSLT stylesheet and document resolution.
+ *
+ * Kept deliberately small and dependency free: the engine only needs enough
+ * URI arithmetic to turn a relative `href` into something a host supplied
+ * loader can resolve, plus fragment removal for the `document()` function.
+ */
+
+"use strict";
+
+/** Matches an absolute URI such as `http://`, `https://` or `file://`. */
+const ABSOLUTE_URI_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+
+/**
+ * Resolve a possibly relative URI against a base URI.
+ *
+ * Absolute URIs (with a scheme) and root relative URIs (starting with `/`)
+ * are returned untouched, as is any URI when no base is available.
+ *
+ * @param {string} href - The URI to resolve
+ * @param {string} [baseUri] - The base URI, typically the stylesheet location
+ * @returns {string} The resolved URI
+ *
+ * @example
+ * resolveUri('common.xsl', '/styles/main.xsl'); // '/styles/common.xsl'
+ */
+export function resolveUri(href, baseUri) {
+  if (!href) return href;
+  if (!baseUri || isAbsoluteUri(href) || href.startsWith("/")) {
+    return href;
+  }
+
+  const lastSlash = baseUri.lastIndexOf("/");
+  const baseDir = lastSlash >= 0 ? baseUri.substring(0, lastSlash + 1) : "";
+
+  return baseDir + href;
+}
+
+/**
+ * Check whether a URI is absolute (has a scheme).
+ *
+ * @param {string} uri - The URI to inspect
+ * @returns {boolean} True when the URI carries a scheme
+ *
+ * @example
+ * isAbsoluteUri('https://example.com/a.xml'); // true
+ */
+export function isAbsoluteUri(uri) {
+  return ABSOLUTE_URI_PATTERN.test(uri);
+}
+
+/**
+ * Remove a fragment identifier from a URI.
+ *
+ * XSLT 1.0 leaves the meaning of fragment identifiers passed to `document()`
+ * implementation defined; this processor ignores them.
+ *
+ * @param {string} uri - The URI, possibly carrying a `#fragment`
+ * @returns {string} The URI without its fragment
+ *
+ * @example
+ * stripFragment('data.xml#section'); // 'data.xml'
+ */
+export function stripFragment(uri) {
+  if (typeof uri !== "string") return "";
+  const hash = uri.indexOf("#");
+  return hash === -1 ? uri : uri.substring(0, hash);
+}

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