@tradik/xslt-processor 1.0.3 → 1.3.0

package/bin/lib/decode.js

@@ -0,0 +1,15 @@
+/**
+ * XSLT Processor CLI - Character Encoding Detection
+ *
+ * Thin wrapper: the decoding core (XML 1.0 Appendix F: byte order mark, then
+ * the XML declaration, then UTF-8) lives in src/io/decode.js, shared with the
+ * asynchronous API.
+ */
+
+"use strict";
+
+export {
+  EncodingError,
+  decodeXml,
+  detectEncoding,
+} from "../../src/io/decode.js";

package/bin/lib/dom.js

@@ -0,0 +1,177 @@
+/**
+ * XSLT Processor CLI - DOM implementations
+ *
+ * The library has no runtime dependencies: in Node.js the host brings a DOM.
+ * The command line tool (and the test suites) can run on two of them, both
+ * optional peer dependencies:
+ *
+ * - `jsdom`: the complete one, with HTML documents (the default);
+ * - `@xmldom/xmldom`: a small XML-only DOM, faster to load; it is used when
+ *   jsdom is not installed, or when chosen with `XSLT_DOM=xmldom`.
+ *
+ * Both are exposed through the same shape as a JSDOM instance
+ * (`{ window: { document, DOMParser, XMLSerializer } }`), so callers never
+ * need to know which one they got.
+ *
+ * @module bin/lib/dom
+ */
+
+"use strict";
+
+/** Names of the supported DOM implementations, in order of preference. */
+export const DOM_IMPLEMENTATIONS = Object.freeze(["jsdom", "xmldom"]);
+
+/**
+ * Loader of each supported DOM implementation. The specifiers are literal so
+ * that bundlers (the standalone binaries, see scripts/binaries/bundle.mjs)
+ * can follow them.
+ */
+const IMPORTERS = Object.freeze({
+  jsdom: () => import("jsdom"),
+  xmldom: () => import("@xmldom/xmldom"),
+});
+
+/** Message shown when no DOM implementation is installed. */
+export const DOM_MISSING_MESSAGE =
+  "The xslt command needs a DOM implementation, an optional peer dependency " +
+  "that is not installed. Install jsdom or @xmldom/xmldom (lighter, XML only) " +
+  "next to this package: npm install -g jsdom (global install) " +
+  "or npm install jsdom (project install).";
+
+/**
+ * @typedef {Object} DomEnvironment
+ * @property {string} name - "jsdom" or "xmldom"
+ * @property {{document: Document, DOMParser: Function, XMLSerializer: Function}} window -
+ *   The DOM classes, and the document results are created with
+ */
+
+/**
+ * Whether an import failed because the package is not installed.
+ *
+ * @param {*} error - The rejection of a dynamic import
+ * @returns {boolean} True for a missing module
+ */
+function isMissingModule(error) {
+  return (
+    error?.code === "ERR_MODULE_NOT_FOUND" || error?.code === "MODULE_NOT_FOUND"
+  );
+}
+
+/** The xmldom warning about well-formed markup. */
+const BENIGN_WARNING = /^Unicode replacement character/;
+
+/**
+ * A DOMParser class for xmldom that reports malformed XML as browsers do:
+ * a document holding a `parsererror` element instead of a thrown ParseError
+ * or a message on the console. xmldom only warns about some malformed
+ * markup (unquoted attribute values, attributes without a space between
+ * them), which browsers reject too, so warnings count as errors, except
+ * the one about U+FFFD characters (well formed). Lenient `text/html`
+ * parsing never fails.
+ *
+ * @param {object} xmldom - The @xmldom/xmldom module
+ * @returns {Function} The DOMParser class
+ */
+function createXmldomParser(xmldom) {
+  return class DOMParser {
+    /**
+     * @param {string} text - Markup
+     * @param {string} type - MIME type ("application/xml", "text/html", ...)
+     * @returns {Document} The parsed document, or a parsererror document
+     */
+    parseFromString(text, type) {
+      let failure = null;
+      const onError = (level, message) => {
+        if (type === "text/html" || BENIGN_WARNING.test(message)) return;
+        failure ??= message;
+        throw new Error(message);
+      };
+      try {
+        return new xmldom.DOMParser({ onError }).parseFromString(text, type);
+      } catch (error) {
+        const doc = new xmldom.DOMImplementation().createDocument(
+          null,
+          "parsererror",
+          null,
+        );
+        doc.documentElement.appendChild(
+          doc.createTextNode(failure ?? error.message),
+        );
+        return doc;
+      }
+    }
+  };
+}
+
+/**
+ * Build the environment of one DOM implementation from its module.
+ *
+ * @param {string} name - "jsdom" or "xmldom"
+ * @param {object} module - The imported package
+ * @returns {DomEnvironment} The environment
+ */
+function environmentOf(name, module) {
+  if (name === "jsdom") {
+    const dom = new module.JSDOM("<!DOCTYPE html><html><body></body></html>", {
+      contentType: "text/html",
+    });
+    dom.name = "jsdom";
+    return dom;
+  }
+  return {
+    name,
+    window: {
+      document: new module.DOMImplementation().createDocument(null, null),
+      DOMParser: createXmldomParser(module),
+      XMLSerializer: module.XMLSerializer,
+    },
+  };
+}
+
+/**
+ * Load a DOM implementation: the one named, else the first installed of
+ * {@link DOM_IMPLEMENTATIONS}.
+ *
+ * @param {string} [name] - "jsdom" or "xmldom"; empty for the first installed
+ * @param {Record<string, () => Promise<object>>} [importers] - Module loaders
+ *   by implementation name (for tests)
+ * @returns {Promise<DomEnvironment>} The environment (not installed globally)
+ * @throws {Error} When the name is unknown or no implementation is installed
+ *
+ * @example
+ * const dom = await loadDomEnvironment("xmldom");
+ * new dom.window.DOMParser().parseFromString("<a/>", "application/xml");
+ */
+export async function loadDomEnvironment(name, importers = IMPORTERS) {
+  if (name && !DOM_IMPLEMENTATIONS.includes(name)) {
+    throw new Error(
+      `Unknown DOM implementation "${name}": expected ${DOM_IMPLEMENTATIONS.join(" or ")}`,
+    );
+  }
+  const candidates = name ? [name] : DOM_IMPLEMENTATIONS;
+  let missing = null;
+  for (const candidate of candidates) {
+    try {
+      return environmentOf(candidate, await importers[candidate]());
+    } catch (error) {
+      if (!isMissingModule(error)) throw error;
+      missing ??= error;
+    }
+  }
+  throw new Error(DOM_MISSING_MESSAGE, { cause: missing });
+}
+
+/**
+ * Expose a DOM environment globally: the XSLT engine builds its results in
+ * the global `document` and parses imported stylesheets given as strings
+ * with the global `DOMParser`.
+ *
+ * @param {DomEnvironment} dom - The environment
+ * @returns {DomEnvironment} The same environment
+ */
+export function installDomGlobals(dom) {
+  globalThis.document = dom.window.document;
+  globalThis.DOMParser = dom.window.DOMParser;
+  globalThis.XMLSerializer = dom.window.XMLSerializer;
+  return dom;
+}

package/bin/lib/loaders.js

@@ -0,0 +1,127 @@
+/**
+ * XSLT Processor CLI - Stylesheet and Document Loaders
+ *
+ * Resolves the URIs of `xsl:include`, `xsl:import` and `document()` against
+ * the stylesheet location and reads the referenced local files. Every URI is
+ * turned into a file system path and passed through resolveInputPath, which
+ * canonicalizes it with realpathSync and confines it to the base directory
+ * BEFORE the file is read. Only relative references, absolute paths and
+ * `file:` URLs are supported; network schemes are refused.
+ */
+
+"use strict";
+
+import { readFileSync } from "node:fs";
+import { URL, fileURLToPath, pathToFileURL } from "node:url";
+import { decodeXml } from "./decode.js";
+import { resolveInputPath } from "./paths.js";
+
+/**
+ * Error raised for a URI the CLI refuses to load.
+ */
+export class CliUriError extends Error {
+  /**
+   * @param {string} message - Human readable explanation
+   */
+  constructor(message) {
+    super(message);
+    this.name = "CliUriError";
+  }
+}
+
+/**
+ * Convert an absolute file path into the base URI handed to the engine.
+ *
+ * @param {string} path - Absolute file path
+ * @returns {string} The `file:` URL of the path
+ *
+ * @example
+ * toBaseUri('/work/main.xsl'); // 'file:///work/main.xsl'
+ */
+export function toBaseUri(path) {
+  return pathToFileURL(path).href;
+}
+
+/**
+ * Turn a (possibly relative) URI into a local file path.
+ *
+ * @param {string} uri - URI as resolved by the engine
+ * @param {string} [baseUri] - Base URI of the referencing stylesheet
+ * @param {string} baseDir - Canonical base directory, used when no base URI is known
+ * @returns {string} Absolute file system path, not yet validated
+ * @throws {CliUriError} When the URI is malformed or uses a non-file scheme
+ */
+export function uriToPath(uri, baseUri, baseDir) {
+  let url;
+
+  try {
+    url = new URL(uri, baseUri || toBaseUri(`${baseDir}/`));
+  } catch {
+    throw new CliUriError(`Invalid URI: ${uri}`);
+  }
+
+  if (url.protocol !== "file:") {
+    throw new CliUriError(
+      `Only local files can be loaded, refusing ${url.protocol} URI: ${uri}`,
+    );
+  }
+
+  return fileURLToPath(url);
+}
+
+/**
+ * Validate and read a referenced XML file.
+ *
+ * @param {string} uri - URI as resolved by the engine
+ * @param {string} [baseUri] - Base URI of the referencing stylesheet
+ * @param {string} baseDir - Canonical base directory
+ * @param {string} label - Human readable role of the file, used in errors
+ * @returns {string} The decoded file content
+ * @throws {Error} When the URI is refused or the file is missing, outside baseDir or undecodable
+ */
+function readReferencedFile(uri, baseUri, baseDir, label) {
+  const path = resolveInputPath(
+    uriToPath(uri, baseUri, baseDir),
+    label,
+    baseDir,
+  );
+  return decodeXml(readFileSync(path), path);
+}
+
+/**
+ * Create the loader used for `xsl:include` and `xsl:import`.
+ *
+ * @param {string} baseDir - Canonical base directory
+ * @returns {(href: string, baseUri?: string) => string} Stylesheet loader
+ *
+ * @example
+ * processor.setStylesheetLoader(createStylesheetLoader(baseDir));
+ */
+export function createStylesheetLoader(baseDir) {
+  return (href, baseUri) =>
+    readReferencedFile(href, baseUri, baseDir, "Stylesheet");
+}
+
+/**
+ * Create the loader used for the XSLT `document()` function.
+ *
+ * A document that cannot be loaded yields an empty node-set (XSLT 1.0
+ * section 12.1 allows recovering this way) and a one line warning.
+ *
+ * @param {string} baseDir - Canonical base directory
+ * @param {(message: string) => void} [warn] - Warning sink, stderr by default
+ * @returns {(uri: string, baseUri?: string) => (string|null)} Document loader
+ *
+ * @example
+ * processor.setDocumentLoader(createDocumentLoader(baseDir));
+ */
+export function createDocumentLoader(baseDir, warn = console.error) {
+  return (uri, baseUri) => {
+    try {
+      return readReferencedFile(uri, baseUri, baseDir, "Document");
+    } catch (error) {
+      warn(`Warning: document('${uri}') is empty: ${error.message}`);
+      return null;
+    }
+  };
+}

package/bin/lib/options.js

@@ -0,0 +1,131 @@
+/**
+ * XSLT Processor CLI - Option Handling
+ *
+ * Command line option definitions, help/version banners and parameter parsing.
+ */
+
+"use strict";
+
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Version of the CLI, read from the package manifest.
+ * @type {string}
+ */
+export const VERSION = require("../../package.json").version;
+
+/**
+ * parseArgs option definitions.
+ * @type {object}
+ */
+export const CLI_OPTIONS = {
+  output: { type: "string", short: "o" },
+  param: { type: "string", short: "p", multiple: true },
+  format: { type: "boolean", short: "f", default: false },
+  indent: { type: "boolean", default: false },
+  method: { type: "string" },
+  "no-declaration": { type: "boolean", default: false },
+  "xslt-version": { type: "string", default: "1.0" },
+  help: { type: "boolean", short: "h", default: false },
+  version: { type: "boolean", short: "v", default: false },
+};
+
+/**
+ * Print the usage banner.
+ * @returns {void}
+ */
+export function printHelp() {
+  console.log(`
+xslt-processor - Transform XML documents using XSLT stylesheets
+
+USAGE:
+  xslt <xml-file> <xslt-file> [options]
+
+ARGUMENTS:
+  <xml-file>       Path to XML source document
+  <xslt-file>      Path to XSLT stylesheet
+
+OPTIONS:
+  -o, --output <file>     Write output to file instead of stdout
+  -p, --param <n>=<v>     Set XSLT parameter (can be used multiple times)
+  -f, --format            Format output with indentation (same as --indent)
+      --indent            Override xsl:output to indent="yes"
+      --method <m>        Override xsl:output method (xml|html|xhtml|text)
+      --no-declaration    Override xsl:output to omit the XML declaration
+      --xslt-version <v>  1.0 (default): XSLT 1.0 engine, a version="2.0"
+                          stylesheet runs in forwards-compatible mode;
+                          auto: XSLT 2.0/3.0 stylesheets run with
+                          @tradik/xslt3 (npm install @tradik/xslt3)
+  -h, --help              Show this help message
+  -v, --version           Show version number
+
+The output is serialized according to the xsl:output element of the
+stylesheet; the options above override individual xsl:output settings.
+
+All file arguments must live inside the current working directory, or inside
+the directory named by the XSLT_BASE_DIR environment variable when it is set.
+xsl:include, xsl:import and document() resolve relative to the stylesheet and
+are confined to the same directory; only local files are loaded. Input files
+are decoded by their byte order mark or XML encoding declaration (UTF-8 by
+default), e.g. UTF-16, ISO-8859-1 or windows-1252. The result is written in
+the encoding named by xsl:output (UTF-8 by default); characters that encoding
+cannot represent are written as character references (&#8364;).
+
+The DOM implementation is jsdom, or @xmldom/xmldom when jsdom is not
+installed; set XSLT_DOM=xmldom or XSLT_DOM=jsdom to choose one.
+
+EXAMPLES:
+  # Basic transformation
+  xslt data.xml transform.xsl
+
+  # Save output to file
+  xslt data.xml transform.xsl -o result.html
+
+  # With parameters
+  xslt data.xml transform.xsl -p title="My Page" -p count=10
+
+  # Multiple parameters with formatted output
+  xslt data.xml transform.xsl -p lang=en -p debug=true -f -o output.html
+
+  # An XSLT 2.0/3.0 stylesheet (needs @tradik/xslt3)
+  xslt data.xml grouping.xsl --xslt-version auto
+`);
+}
+
+/**
+ * Print the version banner.
+ * @returns {void}
+ */
+export function printVersion() {
+  console.log(`xslt-processor v${VERSION}`);
+}
+
+/**
+ * Parse `name=value` parameter arguments.
+ *
+ * @param {string[]|undefined} params - Raw `--param` values
+ * @returns {Record<string, string>} Parsed parameters
+ */
+export function parseParameters(params) {
+  const result = {};
+
+  if (!params || !Array.isArray(params)) {
+    return result;
+  }
+
+  for (const param of params) {
+    const equalIndex = param.indexOf("=");
+    if (equalIndex === -1) {
+      console.error(
+        `Warning: Invalid parameter format "${param}". Expected name=value`,
+      );
+      continue;
+    }
+
+    result[param.substring(0, equalIndex)] = param.substring(equalIndex + 1);
+  }
+
+  return result;
+}

package/bin/lib/output.js

@@ -0,0 +1,114 @@
+/**
+ * XSLT Processor CLI - Result Output
+ *
+ * Writes the serialized result byte for byte, chunk by chunk as it is
+ * serialized (waiting for stdout to drain when its buffer is full): `-o file`
+ * and redirected stdout receive exactly what the stylesheet produced, encoded
+ * in the `xsl:output` encoding (UTF-8 by default; UTF-16 with a byte order mark; ISO-8859-1,
+ * US-ASCII, windows-125x and the other single-byte encodings byte per
+ * character). Encodings without an encoder (Shift_JIS, EUC-KR, ...) are
+ * written as UTF-8 with a warning. Only an interactive terminal gets a
+ * trailing newline appended, so the shell prompt starts on its own line.
+ */
+
+"use strict";
+
+import { open } from "node:fs/promises";
+import {
+  createOutputEncoder,
+  getOutputEncoding,
+} from "../../src/xslt/serializer/encoding.js";
+
+/**
+ * Compute the text written to stdout.
+ *
+ * @param {string} output - Serialized transformation result
+ * @param {boolean} isTty - Whether stdout is an interactive terminal
+ * @returns {string} The output, with a newline appended only for a terminal
+ *   when it does not already end with one
+ *
+ * @example
+ * forStdout('<a/>', false); // '<a/>'
+ * forStdout('<a/>', true);  // '<a/>\n'
+ */
+export function forStdout(output, isTty) {
+  return isTty && !output.endsWith("\n") ? `${output}\n` : output;
+}
+
+/**
+ * Write bytes to a stream, waiting for `drain` when its buffer is full
+ * (backpressure), so a large result is never queued whole in memory.
+ *
+ * @param {NodeJS.WritableStream} stream - Destination
+ * @param {Uint8Array} bytes - Bytes to write
+ * @returns {Promise<void>|undefined} Pending until the stream drains, if it must
+ */
+function writeBytes(stream, bytes) {
+  if (stream.write(bytes) === false) {
+    return new Promise((resolve) => stream.once("drain", resolve));
+  }
+  return undefined;
+}
+
+/**
+ * Encode chunks of serialized output and hand the bytes to a sink. At least
+ * one (possibly empty) chunk is encoded, so an empty UTF-16 result still
+ * gets its byte order mark.
+ *
+ * @param {Iterable<string>} chunks - Serialized output
+ * @param {(text: string) => Uint8Array} encode - Output encoder
+ * @param {(bytes: Uint8Array) => (Promise<unknown>|unknown)} sink - Writer
+ * @returns {Promise<string>} The last chunk ("" when none)
+ */
+async function pump(chunks, encode, sink) {
+  let last = null;
+  for (const chunk of chunks) {
+    await sink(encode(chunk));
+    last = chunk;
+  }
+  if (last === null) {
+    last = "";
+    await sink(encode(last));
+  }
+  return last;
+}
+
+/**
+ * Write the transformation result to a file or to stdout, chunk by chunk.
+ *
+ * @param {string|Iterable<string>} output - Serialized transformation
+ *   result, whole or in chunks (see streamTransformation)
+ * @param {string|undefined} target - Validated absolute output path, if any
+ * @param {object} [options] - Encoding and output streams
+ * @param {string} [options.encoding] - The `xsl:output` encoding, UTF-8 by default
+ * @param {NodeJS.WriteStream} [options.stdout] - Result stream
+ * @param {NodeJS.WriteStream} [options.stderr] - Status message stream
+ * @returns {Promise<void>} Resolves once the result has been written
+ */
+export async function writeResult(
+  output,
+  target,
+  { encoding = "UTF-8", stdout = process.stdout, stderr = process.stderr } = {},
+) {
+  if (!getOutputEncoding(encoding).isExact) {
+    stderr.write(
+      `Warning: cannot write the ${encoding} encoding, writing UTF-8 instead\n`,
+    );
+  }
+  const chunks = typeof output === "string" ? [output] : output;
+  const encode = createOutputEncoder(encoding);
+  if (target) {
+    const file = await open(target, "w");
+    try {
+      await pump(chunks, encode, (bytes) => file.write(bytes));
+    } finally {
+      await file.close();
+    }
+    stderr.write(`Output written to ${target}\n`);
+    return;
+  }
+  const last = await pump(chunks, encode, (bytes) => writeBytes(stdout, bytes));
+  if (forStdout(last, Boolean(stdout.isTTY)) !== last) {
+    await writeBytes(stdout, encode("\n"));
+  }
+}