@tradik/xslt-processor 1.0.3 → 1.3.0

package/bin/lib/paths.js

@@ -0,0 +1,186 @@
+/**
+ * XSLT Processor CLI - Path Validation
+ *
+ * Every file the CLI reads or writes goes through this module first: the raw
+ * command line argument is resolved, canonicalized with `realpathSync`, checked
+ * to lie inside the trusted base directory and validated against the file
+ * system before any read or write is attempted. The base directory is the
+ * current working directory, or `XSLT_BASE_DIR` when that variable is set.
+ */
+
+"use strict";
+
+import { realpathSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+
+/**
+ * Error raised for a command line path that cannot be used.
+ */
+export class CliPathError extends Error {
+  /**
+   * @param {string} message - Human readable explanation
+   */
+  constructor(message) {
+    super(message);
+    this.name = "CliPathError";
+  }
+}
+
+/**
+ * Resolve a raw path argument to an absolute path.
+ *
+ * @param {string} rawPath - Raw command line argument
+ * @param {string} label - Human readable role of the path, used in errors
+ * @returns {string} The absolute path
+ * @throws {CliPathError} When the argument is empty or contains a NUL byte
+ */
+function toAbsolutePath(rawPath, label) {
+  if (typeof rawPath !== "string" || rawPath.length === 0) {
+    throw new CliPathError(`${label} path is missing`);
+  }
+
+  if (rawPath.includes("\0")) {
+    throw new CliPathError(`${label} path contains a NUL byte`);
+  }
+
+  return resolve(rawPath);
+}
+
+/**
+ * Canonicalize an existing path, turning a missing entry into a CLI error.
+ *
+ * @param {string} absolute - Absolute path that should exist
+ * @param {string} message - Error message when nothing exists there
+ * @returns {string} The canonical path with symbolic links resolved
+ * @throws {CliPathError} When the path does not exist
+ */
+function canonicalize(absolute, message) {
+  try {
+    return realpathSync(absolute);
+  } catch {
+    throw new CliPathError(message);
+  }
+}
+
+/**
+ * Ensure a canonical path lies inside the trusted base directory.
+ *
+ * This is the security boundary of the CLI: whatever the caller typed, the
+ * canonical path must be the base directory itself or a descendant of it.
+ *
+ * @param {string} canonical - Canonical absolute path
+ * @param {string} baseDir - Canonical absolute base directory
+ * @param {string} label - Human readable role of the path, used in errors
+ * @returns {string} The same path, now known to be inside baseDir
+ * @throws {CliPathError} When the path escapes the base directory
+ */
+function assertInsideBase(canonical, baseDir, label) {
+  // A file system root ("/", "C:\\") already ends with the separator
+  const prefix = baseDir.endsWith(sep) ? baseDir : baseDir + sep;
+  const inside = canonical === baseDir || canonical.startsWith(prefix);
+
+  if (!inside) {
+    throw new CliPathError(
+      `${label} path is outside the allowed base directory (${baseDir}): ${canonical}. ` +
+        "Run the command from that directory or set XSLT_BASE_DIR.",
+    );
+  }
+
+  return canonical;
+}
+
+/**
+ * Resolve the trusted base directory all file arguments are confined to.
+ *
+ * Uses `XSLT_BASE_DIR` when set, otherwise the current working directory.
+ *
+ * @returns {string} The canonical absolute path of an existing directory
+ * @throws {CliPathError} When the configured directory does not exist or is not a directory
+ *
+ * @example
+ * const baseDir = resolveBaseDir(); // process.cwd() unless XSLT_BASE_DIR is set
+ */
+export function resolveBaseDir() {
+  const configured = process.env.XSLT_BASE_DIR || process.cwd();
+  const absolute = toAbsolutePath(configured, "Base directory");
+  const canonical = canonicalize(
+    absolute,
+    `Base directory does not exist: ${absolute}`,
+  );
+
+  if (!statSync(canonical).isDirectory()) {
+    throw new CliPathError(`Base directory is not a directory: ${canonical}`);
+  }
+
+  return canonical;
+}
+
+/**
+ * Validate a path the CLI is going to read.
+ *
+ * @param {string} rawPath - Raw command line argument
+ * @param {string} label - Human readable role of the path, used in errors
+ * @param {string} baseDir - Canonical base directory from resolveBaseDir()
+ * @returns {string} The canonical path of an existing regular file inside baseDir
+ * @throws {CliPathError} When the path is malformed, missing, outside baseDir or not a file
+ *
+ * @example
+ * const xmlFile = resolveInputPath("data.xml", "XML", resolveBaseDir());
+ */
+export function resolveInputPath(rawPath, label, baseDir) {
+  const absolute = toAbsolutePath(rawPath, label);
+  const canonical = assertInsideBase(
+    canonicalize(absolute, `File not found: ${absolute}`),
+    baseDir,
+    label,
+  );
+
+  if (!statSync(canonical).isFile()) {
+    throw new CliPathError(`${label} path is not a file: ${canonical}`);
+  }
+
+  return canonical;
+}
+
+/**
+ * Validate a path the CLI is going to write.
+ *
+ * The file itself may be missing, but its parent directory has to exist, lie
+ * inside the base directory, and an existing target has to be a regular file.
+ *
+ * @param {string} rawPath - Raw command line argument
+ * @param {string} baseDir - Canonical base directory from resolveBaseDir()
+ * @returns {string} The canonical path to write to
+ * @throws {CliPathError} When the path is malformed, outside baseDir or not writable as a file
+ *
+ * @example
+ * const target = resolveOutputPath("build/result.html", resolveBaseDir());
+ */
+export function resolveOutputPath(rawPath, baseDir) {
+  const absolute = toAbsolutePath(rawPath, "Output");
+  const parent = assertInsideBase(
+    canonicalize(
+      dirname(absolute),
+      `Output directory does not exist: ${dirname(absolute)}`,
+    ),
+    baseDir,
+    "Output directory",
+  );
+
+  if (!statSync(parent).isDirectory()) {
+    throw new CliPathError(`Output directory is not a directory: ${parent}`);
+  }
+
+  const canonical = assertInsideBase(
+    join(parent, basename(absolute)),
+    baseDir,
+    "Output",
+  );
+  const targetStats = statSync(canonical, { throwIfNoEntry: false });
+
+  if (targetStats && !targetStats.isFile()) {
+    throw new CliPathError(`Output path is not a file: ${canonical}`);
+  }
+
+  return canonical;
+}

package/bin/lib/transform.js

@@ -0,0 +1,206 @@
+/**
+ * XSLT Processor CLI - Transformation Helpers
+ *
+ * DOM environment setup, document parsing and the transformation itself.
+ * Output is serialized in chunks (src/async/stream.js, the same serializer
+ * as XSLTProcessor#transformToString) so that the xsl:output settings of the
+ * stylesheet are honored and large results are written as they are produced.
+ */
+
+"use strict";
+
+import { XSLTProcessor } from "../../src/XSLTProcessor.js";
+import { transformToChunks } from "../../src/async/stream.js";
+import { findParseError } from "../../src/xslt/domParsing.js";
+import { XSLT_VERSION_MODES, usesXslt3 } from "../../src/bridge/version.js";
+import {
+  createDocumentLoader,
+  createStylesheetLoader,
+  toBaseUri,
+} from "./loaders.js";
+import { installDomGlobals, loadDomEnvironment } from "./dom.js";
+
+/**
+ * Create the DOM environment of the command line tool and expose it
+ * globally (see dom.js): jsdom, else @xmldom/xmldom; `XSLT_DOM=xmldom` or
+ * `XSLT_DOM=jsdom` picks one.
+ *
+ * The XSLT engine builds its result documents through the global `document`,
+ * so the globals have to be installed before transforming.
+ *
+ * @param {string} [name] - DOM implementation, default `$XSLT_DOM`
+ * @returns {Promise<import("./dom.js").DomEnvironment>} The environment
+ * @throws {Error} When no DOM implementation is installed
+ */
+export async function createDomEnvironment(name = process.env.XSLT_DOM) {
+  return installDomGlobals(await loadDomEnvironment(name));
+}
+
+/**
+ * Parse an XML string, reporting parser errors as exceptions.
+ *
+ * @param {import("./dom.js").DomEnvironment} dom - DOM environment
+ * @param {string} content - XML source text
+ * @param {string} label - Human readable document label used in errors
+ * @returns {Document} Parsed document
+ */
+export function parseDocument(dom, content, label) {
+  const doc = new dom.window.DOMParser().parseFromString(
+    content,
+    "application/xml",
+  );
+
+  const error = findParseError(doc);
+  if (error) {
+    throw new Error(`Error parsing ${label}: ${error.textContent}`);
+  }
+
+  return doc;
+}
+
+/** Output methods accepted by `--method`. */
+export const OUTPUT_METHODS = Object.freeze(["xml", "html", "xhtml", "text"]);
+
+/**
+ * Override the stylesheet xsl:output settings from the command line flags.
+ *
+ * @param {XSLTProcessor} processor - Processor with an imported stylesheet
+ * @param {object} values - Parsed command line option values
+ * @returns {object} The effective output settings
+ * @throws {Error} When `--method` is not one of {@link OUTPUT_METHODS}
+ */
+export function applyOutputOverrides(processor, values) {
+  const settings = processor.engine.outputSettings;
+
+  if (values.format || values.indent) {
+    settings.indent = "yes";
+  }
+  if (values.method) {
+    if (!OUTPUT_METHODS.includes(values.method)) {
+      throw new Error(
+        `Invalid --method "${values.method}": expected xml, html, xhtml or text`,
+      );
+    }
+    settings.method = values.method;
+  }
+  if (values["no-declaration"]) {
+    settings.omitXmlDeclaration = "yes";
+  }
+
+  return settings;
+}
+
+/**
+ * The `xsltVersion` option selected by `--xslt-version`.
+ *
+ * @param {object} values - Parsed command line option values
+ * @returns {"1.0"|"auto"} The mode, "1.0" by default
+ * @throws {Error} When the flag is neither 1.0 nor auto
+ */
+export function xsltVersionOf(values) {
+  const mode = values["xslt-version"] ?? "1.0";
+  if (!XSLT_VERSION_MODES.includes(mode)) {
+    throw new Error(`Invalid --xslt-version "${mode}": expected 1.0 or auto`);
+  }
+  return mode;
+}
+
+/**
+ * Load @tradik/xslt3 (dynamic import) when `--xslt-version auto` is given
+ * and the stylesheet declares version 2.0 or more, so that the synchronous
+ * transformation can use it.
+ *
+ * @param {import("./dom.js").DomEnvironment} dom - DOM environment
+ * @param {string} xsltContent - XSLT stylesheet text
+ * @param {object} values - Parsed command line option values
+ * @returns {Promise<void>} Resolves once the engine is available
+ * @throws {Error} For an invalid flag, or when @tradik/xslt3 is missing
+ */
+export async function prepareXsltVersion(dom, xsltContent, values) {
+  const mode = xsltVersionOf(values);
+  if (mode === "auto") {
+    const xsltDoc = parseDocument(dom, xsltContent, "XSLT");
+    if (usesXslt3(xsltDoc, mode)) await XSLTProcessor.preload();
+  }
+}
+
+/**
+ * @typedef {Object} TransformationInputs
+ * @property {import("./dom.js").DomEnvironment} dom - DOM environment
+ * @property {string} xmlContent - XML source text
+ * @property {string} xsltContent - XSLT stylesheet text
+ * @property {Record<string, string>} params - Stylesheet parameters
+ * @property {object} values - Parsed command line option values
+ * @property {string} [xsltFile] - Canonical stylesheet path; enables
+ *   xsl:include, xsl:import and document() relative to it
+ * @property {string} [baseDir] - Canonical base directory every loaded file
+ *   is confined to (required together with xsltFile)
+ * @property {(message: string) => void} [warn] - Warning sink for document()
+ */
+
+/**
+ * @typedef {Object} StreamedTransformation
+ * @property {Iterator<string>} chunks - The serialized result in chunks of
+ *   bounded size (see src/xslt/serializer/chunks.js), with character
+ *   references for the characters the output encoding cannot represent
+ * @property {string} encoding - The effective `xsl:output` encoding, the
+ *   encoding the result has to be written in
+ */
+
+/**
+ * Run a transformation; its result is serialized as the chunks are read,
+ * so the output is written without ever being held as one string.
+ *
+ * @param {TransformationInputs} inputs - Transformation inputs
+ * @returns {StreamedTransformation} The result chunks and their encoding
+ * @throws {Error} "Transformation failed" when the transformation fails
+ *   (the cause is reported on stderr, as XSLTProcessor does)
+ */
+export function streamTransformation({
+  dom,
+  xmlContent,
+  xsltContent,
+  params,
+  values,
+  xsltFile,
+  baseDir,
+  warn,
+}) {
+  const xmlDoc = parseDocument(dom, xmlContent, "XML");
+  const xsltDoc = parseDocument(dom, xsltContent, "XSLT");
+
+  const processor = new XSLTProcessor({ xsltVersion: xsltVersionOf(values) });
+  if (xsltFile) {
+    processor.setStylesheetLoader(createStylesheetLoader(baseDir));
+    processor.setDocumentLoader(createDocumentLoader(baseDir, warn));
+  }
+  processor.importStylesheet(xsltDoc, xsltFile && toBaseUri(xsltFile));
+
+  for (const [name, value] of Object.entries(params)) {
+    processor.setParameter(null, name, value);
+  }
+
+  applyOutputOverrides(processor, values);
+
+  let chunks;
+  try {
+    chunks = transformToChunks(processor.engine, xmlDoc);
+  } catch (error) {
+    console.error("XSLT transformation error:", error);
+    throw new Error("Transformation failed", { cause: error });
+  }
+  return { chunks, encoding: processor.engine.outputSettings.encoding };
+}
+
+/**
+ * Run a transformation and serialize its result to one string.
+ *
+ * @param {TransformationInputs} inputs - Transformation inputs
+ * @returns {{output: string, encoding: string}} The serialized result and
+ *   its encoding
+ * @throws {Error} "Transformation failed" when the transformation fails
+ */
+export function runTransformation(inputs) {
+  const { chunks, encoding } = streamTransformation(inputs);
+  return { output: [...chunks].join(""), encoding };
+}

package/bin/xslt.js

@@ -4,117 +4,54 @@
  * XSLT Processor CLI
  *
  * Command-line interface for transforming XML using XSLT stylesheets.
+ * The result is serialized according to the xsl:output element of the
+ * stylesheet (XSLT 1.0 section 16).
  */
 
-'use strict';
+"use strict";
+
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import {
+  CLI_OPTIONS,
+  parseParameters,
+  printHelp,
+  printVersion,
+} from "./lib/options.js";
+import {
+  createDomEnvironment,
+  prepareXsltVersion,
+  streamTransformation,
+} from "./lib/transform.js";
+import { decodeXml } from "./lib/decode.js";
+import { writeResult } from "./lib/output.js";
+import {
+  resolveBaseDir,
+  resolveInputPath,
+  resolveOutputPath,
+} from "./lib/paths.js";
 
-import { readFile, writeFile } from 'node:fs/promises';
-import { parseArgs } from 'node:util';
-import { JSDOM } from 'jsdom';
-import { XSLTProcessor } from '../src/XSLTProcessor.js';
-
-const VERSION = '1.0.5';
-
-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
-  -h, --help              Show this help message
-  -v, --version           Show version number
-
-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
-`);
-}
-
-function printVersion() {
-  console.log(`xslt-processor v${VERSION}`);
-}
-
-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;
-    }
-
-    const name = param.substring(0, equalIndex);
-    const value = param.substring(equalIndex + 1);
-    result[name] = value;
-  }
-
-  return result;
-}
-
-function formatXml(xml) {
-  let formatted = '';
-  let indent = 0;
-  const lines = xml.replace(/>\s*</g, '>\n<').split('\n');
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-
-    if (trimmed.startsWith('</')) {
-      indent = Math.max(0, indent - 1);
-    }
-
-    formatted += '  '.repeat(indent) + trimmed + '\n';
-
-    if (trimmed.startsWith('<') && !trimmed.startsWith('</') &&
-        !trimmed.startsWith('<?') && !trimmed.startsWith('<!') &&
-        !trimmed.endsWith('/>') && !trimmed.includes('</')) {
-      indent++;
-    }
-  }
-
-  return formatted;
-}
-
-async function main() {
-  const options = {
-    output: { type: 'string', short: 'o' },
-    param: { type: 'string', short: 'p', multiple: true },
-    format: { type: 'boolean', short: 'f', default: false },
-    help: { type: 'boolean', short: 'h', default: false },
-    version: { type: 'boolean', short: 'v', default: false }
-  };
-
-  let args;
+/**
+ * Parse the command line, exiting on malformed input.
+ *
+ * @returns {object} The parseArgs result
+ */
+function readArguments() {
   try {
-    args = parseArgs({ options, allowPositionals: true });
+    return parseArgs({ options: CLI_OPTIONS, allowPositionals: true });
   } catch (err) {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   }
+}
+
+/**
+ * CLI entry point.
+ *
+ * @returns {Promise<void>} Resolves once the CLI has finished
+ */
+async function main() {
+  const args = readArguments();
 
   if (args.values.help) {
     printHelp();
@@ -129,80 +66,48 @@ async function main() {
   const [xmlPath, xsltPath] = args.positionals;
 
   if (!xmlPath || !xsltPath) {
-    console.error('Error: Both XML and XSLT file paths are required');
+    console.error("Error: Both XML and XSLT file paths are required");
     console.error('Run "xslt --help" for usage information');
     process.exit(1);
   }
 
-  // Setup JSDOM for DOM parsing
-  const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', {
-    contentType: 'text/html'
-  });
-  const { DOMParser, XMLSerializer } = dom.window;
-
   try {
-    // Read input files
-    const [xmlContent, xsltContent] = await Promise.all([
-      readFile(xmlPath, 'utf-8'),
-      readFile(xsltPath, 'utf-8')
+    const dom = await createDomEnvironment();
+    const baseDir = resolveBaseDir();
+    const xmlFile = resolveInputPath(xmlPath, "XML", baseDir);
+    const xsltFile = resolveInputPath(xsltPath, "XSLT", baseDir);
+    const outputFile = args.values.output
+      ? resolveOutputPath(args.values.output, baseDir)
+      : undefined;
+
+    const [xmlBytes, xsltBytes] = await Promise.all([
+      readFile(xmlFile),
+      readFile(xsltFile),
     ]);
 
-    // Parse documents
-    const parser = new DOMParser();
-    const xmlDoc = parser.parseFromString(xmlContent, 'application/xml');
-    const xsltDoc = parser.parseFromString(xsltContent, 'application/xml');
-
-    // Check for parsing errors
-    const xmlError = xmlDoc.querySelector('parsererror');
-    if (xmlError) {
-      console.error(`Error parsing XML: ${xmlError.textContent}`);
-      process.exit(1);
-    }
-
-    const xsltError = xsltDoc.querySelector('parsererror');
-    if (xsltError) {
-      console.error(`Error parsing XSLT: ${xsltError.textContent}`);
-      process.exit(1);
-    }
-
-    // Create processor
-    const processor = new XSLTProcessor();
-    processor.importStylesheet(xsltDoc);
-
-    // Set parameters
-    const params = parseParameters(args.values.param);
-    for (const [name, value] of Object.entries(params)) {
-      processor.setParameter(null, name, value);
-    }
-
-    // Transform
-    const fragment = processor.transformToFragment(xmlDoc, dom.window.document);
-
-    // Serialize result
-    const serializer = new XMLSerializer();
-    let output = serializer.serializeToString(fragment);
-
-    // Format if requested
-    if (args.values.format) {
-      output = formatXml(output);
-    }
-
-    // Output result
-    if (args.values.output) {
-      await writeFile(args.values.output, output, 'utf-8');
-      console.error(`Output written to ${args.values.output}`);
-    } else {
-      console.log(output);
-    }
-
+    const xsltContent = decodeXml(xsltBytes, xsltFile);
+    // --xslt-version auto: load @tradik/xslt3 for a 2.0/3.0 stylesheet
+    await prepareXsltVersion(dom, xsltContent, args.values);
+
+    const { chunks, encoding } = streamTransformation({
+      dom,
+      xmlContent: decodeXml(xmlBytes, xmlFile),
+      xsltContent,
+      params: parseParameters(args.values.param),
+      values: args.values,
+      xsltFile,
+      baseDir,
+    });
+
+    await writeResult(chunks, outputFile, { encoding });
   } catch (err) {
-    if (err.code === 'ENOENT') {
-      console.error(`Error: File not found: ${err.path}`);
-    } else {
-      console.error(`Error: ${err.message}`);
-    }
+    console.error(`Error: ${err.message}`);
     process.exit(1);
   }
 }
 
-main();
+main().catch((err) => {
+  // main() reports expected failures itself; this catches anything unexpected.
+  console.error(`Error: ${err?.message ?? err}`);
+  process.exit(1);
+});