@tradik/xslt-processor 1.0.3 → 1.1.1

package/README.md

@@ -1,12 +1,18 @@
 # @tradik/xslt-processor
 
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-181717?logo=github)](https://github.com/spagu/XSLT-Processor)
+[![GitHub stars](https://img.shields.io/github/stars/spagu/XSLT-Processor?style=social)](https://github.com/spagu/XSLT-Processor/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/spagu/XSLT-Processor?style=social)](https://github.com/spagu/XSLT-Processor/network/members)
+
 [![CI](https://github.com/spagu/XSLT-Processor/actions/workflows/test.yml/badge.svg)](https://github.com/spagu/XSLT-Processor/actions/workflows/test.yml)
 [![Release](https://github.com/spagu/XSLT-Processor/actions/workflows/release.yml/badge.svg)](https://github.com/spagu/XSLT-Processor/actions/workflows/release.yml)
 [![npm version](https://img.shields.io/npm/v/@tradik/xslt-processor.svg)](https://www.npmjs.com/package/@tradik/xslt-processor)
 [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
-[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.19.0-brightgreen.svg)](https://nodejs.org/)
 [![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/spagu/XSLT-Processor)
 
+> **Source Code:** [github.com/spagu/XSLT-Processor](https://github.com/spagu/XSLT-Processor)
+
 JavaScript implementation of XSLTProcessor for browser environments and Node.js CLI. This package provides a complete implementation of the W3C XSLTProcessor API that can be used as a drop-in replacement for the native browser implementation.
 
 ## Background
@@ -22,6 +28,7 @@ This library ensures your XSLT-based applications continue to work regardless of
 - **1:1 Native API Compatibility**: Drop-in replacement for native `XSLTProcessor`
 - **Full XSLT 1.0 Support**: Implements the complete W3C XSLT 1.0 specification
 - **XPath 1.0 Engine**: Built-in XPath evaluator with all core functions
+- **`xsl:output` Serialization**: `transformToString()` honors method, indent, doctype, CDATA sections and `disable-output-escaping`
 - **Zero Dependencies**: Standalone implementation with no external dependencies
 - **Multiple Formats**: ESM, CommonJS, and browser IIFE bundles
 - **TypeScript Support**: Includes TypeScript declarations
@@ -136,6 +143,22 @@ xslt data.xml template.xsl -p title="My Page" -p count=10
 
 # Format output with indentation
 xslt data.xml template.xsl -f -o output.html
+
+# Override the output method and drop the XML declaration
+xslt data.xml template.xsl --method text
+xslt data.xml template.xsl --no-declaration
+```
+
+The output is serialized according to the `xsl:output` element of the
+stylesheet (see [Serializing output](#serializing-output-xsloutput)); the
+options below override individual `xsl:output` settings.
+
+All file arguments must live inside the current working directory (symbolic
+links are resolved first). To work with files elsewhere, run the command from
+that directory or point `XSLT_BASE_DIR` at it:
+
+```bash
+XSLT_BASE_DIR=/srv/data xslt /srv/data/in.xml /srv/data/t.xsl -o /srv/data/out.html
 ```
 
 #### CLI Options
@@ -144,7 +167,10 @@ xslt data.xml template.xsl -f -o output.html
 |--------|-------------|
 | `-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 |
+| `-f, --format` | Format output with indentation (same as `--indent`) |
+| `--indent` | Override `xsl:output` to `indent="yes"` |
+| `--method <m>` | Override the `xsl:output` method (`xml`, `html`, `xhtml`, `text`) |
+| `--no-declaration` | Override `xsl:output` to omit the XML declaration |
 | `-h, --help` | Show help message |
 | `-v, --version` | Show version number |
 
@@ -162,14 +188,78 @@ const processor = new XSLTProcessor();
 
 | Method | Description |
 |--------|-------------|
-| `importStylesheet(node)` | Imports an XSLT stylesheet from a Document or Element node |
+| `importStylesheet(node, stylesheetUri?)` | Imports an XSLT stylesheet from a Document or Element node. The optional `stylesheetUri` is the base URI used to resolve relative `xsl:import`/`xsl:include` hrefs |
 | `transformToFragment(source, output)` | Transforms XML and returns a DocumentFragment |
 | `transformToDocument(source)` | Transforms XML and returns an XMLDocument |
+| `transformToString(source)` | Transforms XML and returns the serialized result honoring `xsl:output` (non-W3C extension) |
 | `setParameter(namespaceURI, localName, value)` | Sets an XSLT parameter |
 | `getParameter(namespaceURI, localName)` | Gets an XSLT parameter value |
 | `removeParameter(namespaceURI, localName)` | Removes an XSLT parameter |
 | `clearParameters()` | Removes all parameters |
-| `reset()` | Resets the processor, removing stylesheet and parameters |
+| `reset()` | Resets the processor, removing stylesheet and parameters (the stylesheet and document loaders are kept) |
+| `setStylesheetLoader(loader)` | Sets the loader used to resolve `xsl:import`/`xsl:include`. Returns the processor for chaining |
+| `setDocumentLoader(loader)` | Sets the loader used to resolve the XSLT `document()` function. Returns the processor for chaining |
+
+#### Properties
+
+| Property | Description |
+|----------|-------------|
+| `engine` | Read-only access to the underlying `XsltEngine` (advanced usage). It is `null` until `importStylesheet()` has been called |
+
+### Serializing output (xsl:output)
+
+`transformToString(source)` serializes the result tree according to the
+`xsl:output` element of the stylesheet (XSLT 1.0 section 16). Unlike the DOM
+based methods it returns ready to write markup, so the CLI and Node.js users do
+not need a separate `XMLSerializer` or a hand rolled re-indenter.
+
+```javascript
+const xslt = parser.parseFromString(`<?xml version="1.0"?>
+  <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+    <xsl:output method="xml" indent="yes"/>
+    <xsl:template match="/"><BAR><QUX/></BAR></xsl:template>
+  </xsl:stylesheet>`, 'application/xml');
+
+const processor = new XSLTProcessor();
+processor.importStylesheet(xslt);
+
+processor.transformToString(xmlDoc);
+// <?xml version="1.0" encoding="UTF-8"?>
+// <BAR>
+//   <QUX/>
+// </BAR>
+```
+
+Supported `xsl:output` attributes:
+
+| Attribute | Behavior |
+|-----------|----------|
+| `method="xml"` | XML declaration, minimal escaping, empty elements as `<x/>` (default) |
+| `method="html"` | No XML declaration, void elements as `<br>`, minimized boolean attributes, unescaped `script`/`style` |
+| `method="xhtml"` | XML rules with void elements written as `<br />` |
+| `method="text"` | Concatenation of all text nodes, no escaping |
+| `indent="yes"` | Newline plus two-space indentation for element-only content; mixed content and `pre`/`script`/`style`/`textarea` are left untouched |
+| `encoding`, `version`, `standalone` | Written into the XML declaration |
+| `omit-xml-declaration="yes"` | Suppresses the XML declaration |
+| `doctype-public`, `doctype-system` | Emit a `<!DOCTYPE ...>` before the document element |
+| `cdata-section-elements` | Text children of the listed elements are wrapped in `<![CDATA[...]]>`, split around any `]]>` |
+| `media-type` | Parsed and exposed on the settings object |
+
+`disable-output-escaping="yes"` on `xsl:text` and `xsl:value-of` is honored: the
+generated text is emitted verbatim, so `&lt;b&gt;` reaches the output as `<b>`.
+
+The serializer can also be used on its own, for example on a fragment produced
+by `transformToFragment`:
+
+```javascript
+import { serializeResult } from '@tradik/xslt-processor';
+
+serializeResult(fragment, { method: 'html', indent: 'yes' });
+```
+
+When `method` is absent (or `auto`), the output method is derived from the
+result tree: `html` when the document element is `html` in no namespace, `xml`
+otherwise.
 
 ### Parameters Example
 
@@ -190,30 +280,135 @@ processor.clearParameters();
 
 ### Using xsl:import and xsl:include
 
-To use `xsl:import` and `xsl:include` elements in your stylesheets, you need to configure a stylesheet loader that tells the processor how to fetch external stylesheets:
+To use `xsl:import` and `xsl:include` elements in your stylesheets, configure a
+stylesheet loader that tells the processor how to fetch external stylesheets.
+
+Call `processor.setStylesheetLoader(...)` **before** `importStylesheet()` -
+references are resolved while the main stylesheet is being compiled, so a loader
+set afterwards is too late for that stylesheet (it still applies to the next
+`importStylesheet()` call).
+
+The loader is **synchronous**. It receives the resolved `href` and the `baseUri`
+of the importing stylesheet, and must return either a `Document` or an XML
+`string` (which is parsed automatically). Promises are not awaited, so pre-load
+remote stylesheets before importing.
 
 ```javascript
 import { XSLTProcessor } from '@tradik/xslt-processor';
 
 const processor = new XSLTProcessor();
 
-// Configure stylesheet loader
-processor.engine.setStylesheetLoader((href, baseUri) => {
-  // href: the href attribute from xsl:import/xsl:include
-  // baseUri: the URI of the importing stylesheet
+// Pre-loaded stylesheets, keyed by resolved URI
+const stylesheets = {
+  '/styles/base.xsl': baseXslText,
+  '/styles/utils.xsl': utilsXslText,
+};
+
+processor.setStylesheetLoader((href, baseUri) => {
+  // href:    resolved URI of the xsl:import/xsl:include target
+  // baseUri: URI of the importing stylesheet (the stylesheetUri you passed in)
+  const xml = stylesheets[href];
+  if (!xml) {
+    throw new Error(`Unknown stylesheet: ${href} (from ${baseUri})`);
+  }
+  return xml; // a Document is also accepted
+});
 
-  // Option 1: Return a parsed Document
-  const response = await fetch(href);
-  const text = await response.text();
-  const parser = new DOMParser();
-  return parser.parseFromString(text, 'application/xml');
+// The second argument is the base URI used to resolve relative hrefs
+processor.importStylesheet(mainStylesheet, '/styles/main.xsl');
+```
+
+If you need remote stylesheets in the browser, fetch them first and hand the
+loader a ready-made map:
+
+```javascript
+const hrefs = ['/styles/base.xsl', '/styles/utils.xsl'];
+const texts = await Promise.all(
+  hrefs.map((href) => fetch(href).then((response) => response.text())),
+);
+const cache = Object.fromEntries(hrefs.map((href, i) => [href, texts[i]]));
 
-  // Option 2: Return XML string (will be parsed automatically)
-  return await fetch(href).then(r => r.text());
+processor.setStylesheetLoader((href) => cache[href]);
+processor.importStylesheet(mainStylesheet, '/styles/main.xsl');
+```
+
+#### Node.js example (filesystem loader)
+
+```javascript
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { DOMParser } from '@xmldom/xmldom'; // or: new JSDOM(...).window.DOMParser
+import { XSLTProcessor } from '@tradik/xslt-processor';
+
+const parser = new DOMParser();
+const mainPath = path.resolve('./styles/main.xsl');
+
+const processor = new XSLTProcessor();
+
+processor.setStylesheetLoader((href, baseUri) => {
+  const filePath = path.resolve(path.dirname(baseUri), href);
+  return readFileSync(filePath, 'utf8'); // returned XML string is parsed for you
+});
+
+const mainStylesheet = parser.parseFromString(
+  readFileSync(mainPath, 'utf8'),
+  'application/xml',
+);
+
+processor.importStylesheet(mainStylesheet, mainPath);
+
+const xml = parser.parseFromString(readFileSync('./data.xml', 'utf8'), 'application/xml');
+const result = processor.transformToDocument(xml);
+```
+
+#### Advanced: the engine accessor
+
+After `importStylesheet()`, `processor.engine` exposes the underlying
+`XsltEngine` for advanced inspection (output settings, compiled templates). It
+is `null` before the first import, which is why the loader must be configured
+through `processor.setStylesheetLoader(...)` rather than `processor.engine`.
+
+### Using the document() function
+
+The XSLT `document()` function loads additional XML documents at transformation
+time. Configure a **synchronous** document loader with
+`processor.setDocumentLoader(...)`; it receives the resolved URI and the base URI
+and returns a `Document`, an XML `string` (parsed automatically) or `null`.
+
+Semantics:
+
+- `document('')` returns the stylesheet itself, per the XSLT 1.0 specification.
+- A node-set argument loads one document per node and returns their union.
+- Relative URIs are resolved against the `stylesheetUri` passed to
+  `importStylesheet()`; fragment identifiers are ignored.
+- Without a loader, or when the loader returns `null`, `document()` evaluates to
+  an **empty node-set** instead of failing the transformation.
+- Each resolved URI is loaded once and cached for the life of the processor.
+
+```javascript
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { XSLTProcessor } from '@tradik/xslt-processor';
+
+const processor = new XSLTProcessor();
+
+processor.setDocumentLoader((uri, baseUri) => {
+  const filePath = path.resolve(path.dirname(baseUri || '.'), uri);
+  try {
+    return readFileSync(filePath, 'utf8'); // XML string is parsed for you
+  } catch {
+    return null; // -> empty node-set, the transformation keeps going
+  }
 });
 
-// Now xsl:import and xsl:include will work
 processor.importStylesheet(mainStylesheet, '/styles/main.xsl');
+const result = processor.transformToDocument(xmlDoc);
+```
+
+```xml
+<xsl:template match="/">
+  <rate><xsl:value-of select="document('rates.xml')/rates/eur"/></rate>
+</xsl:template>
 ```
 
 #### Import vs Include Behavior
@@ -236,7 +431,12 @@ processor.importStylesheet(mainStylesheet, '/styles/main.xsl');
 ### Utility Functions
 
 ```javascript
-import { isNativeXSLTSupported, installGlobal } from '@tradik/xslt-processor';
+import {
+  isNativeXSLTSupported,
+  installGlobal,
+  serializeResult,
+  markRawText
+} from '@tradik/xslt-processor';
 
 // Check if native XSLT is functional
 if (!isNativeXSLTSupported()) {
@@ -246,6 +446,12 @@ if (!isNativeXSLTSupported()) {
 // Install as global XSLTProcessor
 installGlobal(); // Only if native not available
 installGlobal(true); // Force install
+
+// Serialize any result tree with xsl:output settings
+serializeResult(node, { method: 'xml', indent: 'yes' });
+
+// Mark a text node so that it is emitted without escaping
+markRawText(document.createTextNode('<b>raw</b>'));
 ```
 
 ## Complete Example
@@ -392,6 +598,13 @@ const result = evaluator.evaluate(ast, context);
 | `xsl:with-param` | Supported |
 | `xsl:import` | Supported |
 | `xsl:include` | Supported |
+| `xsl:apply-imports` | Supported |
+| `xsl:attribute-set` | Supported (also via `xsl:use-attribute-sets` on literal result elements) |
+| `xsl:key` | Supported (see `key()`) |
+| `xsl:decimal-format` | Supported (see `format-number()`) |
+| `xsl:namespace-alias` | Supported |
+| `xsl:strip-space` / `xsl:preserve-space` | Supported |
+| `xsl:fallback` | Parsed, never instantiated (no extension elements) |
 
 ## XPath Functions Supported
 
@@ -407,11 +620,28 @@ const result = evaluator.evaluate(ast, context);
 ### Number Functions
 - `ceiling()`, `floor()`, `number()`, `round()`, `sum()`
 
+### XSLT-Defined Functions
+- `current()` - the XSLT current node, also inside predicates
+- `document(object, base?)` - external documents, see `setDocumentLoader()`
+- `element-available(name)`, `function-available(name)` - reflect the real element and function tables
+- `format-number(number, pattern, decimalFormat?)` - full XSLT 1.0 picture strings, honouring `xsl:decimal-format`
+- `generate-id(nodeSet?)` - stable identifier for the life of the transformation
+- `key(name, value)` - `xsl:key` lookup, with lazily built per-document indexes
+- `system-property(name)` - `xsl:version`, `xsl:vendor`, `xsl:vendor-url`
+- `unparsed-entity-uri(name)` - always returns `''` (unparsed entities are not exposed by the DOM)
+
+### Conformance Notes
+- CDATA sections count as text everywhere (string-value, `text()`, `xsl:value-of`, `xsl:copy-of`)
+- The identity transform `<xsl:template match="@*|node()"><xsl:copy><xsl:apply-templates select="@*|node()"/></xsl:copy></xsl:template>` round-trips a document exactly
+- `xsl:number` supports `level="single|multiple|any"` with `count`, `from` and the `1`, `01`, `a`, `A`, `i`, `I` format tokens
+- The result tree is built in a neutral XML document and imported into the output
+  document at the end, so element names and namespaces survive an HTML owner document
+
 ## Development
 
 ### Prerequisites
 
-- Node.js 25+ (for native test runner)
+- Node.js 22+ (native test runner; CI runs 22, 24 and 26)
 - Docker (optional, for containerized testing)
 
 ### Setup
@@ -455,30 +685,38 @@ docker-compose run build
 
 ### Publishing to npm
 
-The package is automatically published to npm when a GitHub release is created or a version tag is pushed.
+The package is published to npm automatically by the `Release` workflow when a
+`v*` tag is pushed (or a GitHub release is published). Publishing uses npm
+**Trusted Publishing** (OIDC): no `NPM_TOKEN` secret and no OTP are involved,
+and every release carries provenance attestations.
 
-**Prerequisites:**
-1. Set up `NPM_TOKEN` secret in GitHub repository settings
-2. Ensure version in `package.json` matches the release tag
+**One-time prerequisite** (npmjs.com -> package `@tradik/xslt-processor` ->
+Settings -> Trusted Publisher): provider *GitHub Actions*, owner `spagu`,
+repository `XSLT-Processor`, workflow `release.yml`, environment left empty.
+Alternatively add an `NPM_TOKEN` repository secret (granular access token
+with publish rights and 2FA bypass); the publish step passes it as
+`NODE_AUTH_TOKEN`. Without either, the `publish` job fails with `E404` and the
+package must be published manually with
+`npm publish --provenance --access public --otp=CODE`.
 
-**Release Process:**
+**Release process:**
 
 ```bash
-# 1. Update version in package.json
-npm version patch  # or minor, major
-
-# 2. Push the tag
-git push origin --tags
+# 1. Bump the version in package.json, package-lock.json, src/index.js and
+#    add a CHANGELOG.md entry, then commit to main.
 
-# 3. Create a GitHub release (or push triggers automatically)
+# 2. Tag and push the tag; the workflow refuses to publish if the tag does
+#    not match package.json.
+git tag v1.1.1
+git push origin v1.1.1
 ```
 
-**Automated Workflow:**
-1. Runs all tests and linting checks
-2. Performs security audit with `npm audit`
-3. Builds distribution bundles
-4. Publishes to npm with provenance (supply chain security)
-5. Uploads build artifacts to GitHub
+**Automated workflow:**
+1. Runs lint, formatting check and tests on Node.js 22, 24 and 26
+2. Builds the distribution bundles and verifies the package contents
+3. Checks that the tag matches the `package.json` version
+4. Uploads the `dist/` build artifacts to GitHub
+5. Publishes to npm with provenance
 
 ## Browser Compatibility
 
@@ -488,13 +726,13 @@ This library provides a JavaScript polyfill for XSLTProcessor that works across
 
 | Browser | Minimum Version | ES Modules | Status |
 |---------|-----------------|------------|--------|
-| Chrome | 90+ | Yes | Fully Supported |
-| Firefox | 88+ | Yes | Fully Supported |
-| Safari | 14+ | Yes | Fully Supported |
-| Edge | 90+ | Yes | Fully Supported |
-| Opera | 76+ | Yes | Fully Supported |
-| Samsung Internet | 15+ | Yes | Fully Supported |
-| Node.js | 25+ | Yes | Fully Supported |
+| Chrome | 92+ | Yes | Fully Supported |
+| Firefox | 92+ | Yes | Fully Supported |
+| Safari | 15.4+ | Yes | Fully Supported |
+| Edge | 92+ | Yes | Fully Supported |
+| Opera | 78+ | Yes | Fully Supported |
+| Samsung Internet | 16+ | Yes | Fully Supported |
+| Node.js | 20.19+ | Yes | Fully Supported (CI: 22, 24, 26) |
 
 ### Native XSLT Deprecation Timeline
 
@@ -560,7 +798,12 @@ This implementation follows these W3C specifications with comprehensive test cov
 | 13 | Messages | Supported | `xsl:message` with `terminate` attribute |
 | 14 | Extensions | Partial | `xsl:fallback` supported |
 | 15 | Fallback | Supported | `xsl:fallback` element |
-| 16 | Output | Supported | `xsl:output` with method, encoding, indent |
+| 16 | Output | Supported | `xsl:output` honored by `transformToString()` / `serializeResult()` |
+| 16.1 | XML Output Method | Supported | XML declaration (`encoding`, `version`, `standalone`), `omit-xml-declaration`, `doctype-public`/`doctype-system`, namespace declarations, `indent="yes"` for element-only content |
+| 16.1 | CDATA Sections | Supported | `cdata-section-elements`, split around `]]>` |
+| 16.2 | HTML Output Method | Supported | Void elements as `<br>`, minimized boolean attributes, unescaped `script`/`style`, no re-indent inside `pre`/`script`/`style`/`textarea` |
+| 16.3 | Text Output Method | Supported | Concatenation of all text nodes, no escaping |
+| 16.4 | Disabling Output Escaping | Supported | `disable-output-escaping` on `xsl:text` and `xsl:value-of` |
 
 ### XPath 1.0 Specification Compliance
 
@@ -625,6 +868,7 @@ This implementation provides full compatibility with the [MDN XSLTProcessor API]
 | `importStylesheet(node)` | Supported | Accepts Document or Element |
 | `transformToFragment(source, output)` | Supported | Returns DocumentFragment |
 | `transformToDocument(source)` | Supported | Returns XMLDocument |
+| `transformToString(source)` | Extension | Not part of the W3C API; returns the `xsl:output` serialized result |
 | `setParameter(namespaceURI, localName, value)` | Supported | Full namespace support |
 | `getParameter(namespaceURI, localName)` | Supported | Returns parameter value |
 | `removeParameter(namespaceURI, localName)` | Supported | Removes single parameter |
@@ -640,8 +884,9 @@ This implementation provides full compatibility with the [MDN XSLTProcessor API]
 | XPath 1.0 Axes | 26+ | All 13 axes |
 | DOM Level 3 | 20+ | Core interfaces |
 | XSLTProcessor API | 39+ | All methods |
+| Output Serialization | 79+ | `xsl:output`, CLI, `transformToString()` |
 | Security | 34+ | DoS prevention, prototype pollution |
-| **Total** | **441** | **99.41% line coverage** |
+| **Total** | **560** | **100% line coverage** |
 
 ## Style Guide
 

package/bin/lib/options.js

@@ -0,0 +1,114 @@
+/**
+ * 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 },
+  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
+  -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.
+
+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
+`);
+}
+
+/**
+ * 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;
+}