@tradik/xslt-processor 1.0.2 → 1.1.1

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) {
+  const inside =
+    canonical === baseDir ||
+    (canonical.startsWith(baseDir) && canonical.startsWith(baseDir + sep));
+
+  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,115 @@
+/**
+ * XSLT Processor CLI - Transformation Helpers
+ *
+ * DOM environment setup, document parsing and the transformation itself.
+ * Output is serialized through XSLTProcessor#transformToString so that the
+ * xsl:output settings of the stylesheet are honored.
+ */
+
+"use strict";
+
+import { JSDOM } from "jsdom";
+import { XSLTProcessor } from "../../src/XSLTProcessor.js";
+
+/**
+ * Create a JSDOM based DOM environment and expose it globally.
+ *
+ * The XSLT engine builds its result documents through the global `document`,
+ * so the globals have to be installed before transforming.
+ *
+ * @returns {JSDOM} The created JSDOM instance
+ */
+export function createDomEnvironment() {
+  const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>", {
+    contentType: "text/html",
+  });
+
+  globalThis.document = dom.window.document;
+  globalThis.DOMParser = dom.window.DOMParser;
+  globalThis.XMLSerializer = dom.window.XMLSerializer;
+
+  return dom;
+}
+
+/**
+ * Parse an XML string, reporting parser errors as exceptions.
+ *
+ * @param {JSDOM} 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 = doc.querySelector("parsererror");
+  if (error) {
+    throw new Error(`Error parsing ${label}: ${error.textContent}`);
+  }
+
+  return doc;
+}
+
+/**
+ * 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
+ */
+export function applyOutputOverrides(processor, values) {
+  const settings = processor._engine.outputSettings;
+
+  if (values.format || values.indent) {
+    settings.indent = "yes";
+  }
+  if (values.method) {
+    settings.method = values.method;
+  }
+  if (values["no-declaration"]) {
+    settings.omitXmlDeclaration = "yes";
+  }
+
+  return settings;
+}
+
+/**
+ * Run a transformation and serialize its result.
+ *
+ * @param {object} options - Transformation inputs
+ * @param {JSDOM} options.dom - DOM environment
+ * @param {string} options.xmlContent - XML source text
+ * @param {string} options.xsltContent - XSLT stylesheet text
+ * @param {Record<string, string>} options.params - Stylesheet parameters
+ * @param {object} options.values - Parsed command line option values
+ * @returns {string} The serialized transformation result
+ */
+export function runTransformation({
+  dom,
+  xmlContent,
+  xsltContent,
+  params,
+  values,
+}) {
+  const xmlDoc = parseDocument(dom, xmlContent, "XML");
+  const xsltDoc = parseDocument(dom, xsltContent, "XSLT");
+
+  const processor = new XSLTProcessor();
+  processor.importStylesheet(xsltDoc);
+
+  for (const [name, value] of Object.entries(params)) {
+    processor.setParameter(null, name, value);
+  }
+
+  applyOutputOverrides(processor, values);
+
+  const output = processor.transformToString(xmlDoc);
+  if (output === null) {
+    throw new Error("Transformation failed");
+  }
+
+  return output;
+}

package/bin/xslt.js

@@ -4,117 +4,64 @@
  * 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, writeFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import {
+  CLI_OPTIONS,
+  parseParameters,
+  printHelp,
+  printVersion,
+} from "./lib/options.js";
+import { createDomEnvironment, runTransformation } from "./lib/transform.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;
+/**
+ * Parse the command line, exiting on malformed input.
+ *
+ * @returns {object} The parseArgs result
+ */
+function readArguments() {
+  try {
+    return parseArgs({ options: CLI_OPTIONS, allowPositionals: true });
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
   }
-
-  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++;
-    }
+/**
+ * Write the transformation result to a file or to stdout.
+ *
+ * @param {string} output - Serialized transformation result
+ * @param {string|undefined} target - Validated absolute output path, if any
+ * @returns {Promise<void>} Resolves once the result has been written
+ */
+async function writeOutput(output, target) {
+  if (target) {
+    await writeFile(target, output, "utf-8");
+    console.error(`Output written to ${target}`);
+    return;
   }
-
-  return formatted;
+  console.log(output);
 }
 
+/**
+ * CLI entry point.
+ *
+ * @returns {Promise<void>} Resolves once the CLI has finished
+ */
 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;
-  try {
-    args = parseArgs({ options, allowPositionals: true });
-  } catch (err) {
-    console.error(`Error: ${err.message}`);
-    process.exit(1);
-  }
+  const args = readArguments();
 
   if (args.values.help) {
     printHelp();
@@ -129,78 +76,37 @@ 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;
+  const dom = createDomEnvironment();
 
   try {
-    // Read input files
+    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 [xmlContent, xsltContent] = await Promise.all([
-      readFile(xmlPath, 'utf-8'),
-      readFile(xsltPath, 'utf-8')
+      readFile(xmlFile, "utf-8"),
+      readFile(xsltFile, "utf-8"),
     ]);
 
-    // 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 output = runTransformation({
+      dom,
+      xmlContent,
+      xsltContent,
+      params: parseParameters(args.values.param),
+      values: args.values,
+    });
 
+    await writeOutput(output, outputFile);
   } 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);
   }
 }