@wirebench/engine 2.1.1

package/dist/wsdl/docs-generator.js

@@ -0,0 +1,439 @@
+/**
+ * "Generate Documentation": renders an imported definition as a
+ * single self-contained document — HTML (inline CSS, no scripts, everything
+ * escaped) or Markdown (with a table of contents).
+ *
+ * Pure and deterministic: the same {@link ImportResult} always produces
+ * byte-identical output, so the golden tests are meaningful and a regenerated
+ * document is a clean diff. Nothing is fetched; every byte comes from the
+ * bundle the import already resolved.
+ */
+import { findBinding, findMessage, findPortType } from './model.js';
+import { qnameToString } from './qname.js';
+const EMPTY = '—';
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/** Escapes the Markdown characters that would break a one-line table cell. */
+function escapeMarkdownCell(value) {
+    return value.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+/**
+ * Escapes free text — `wsdl:documentation` and the document title — before it goes into the
+ * Markdown output verbatim. Both can come straight from the WSDL author, so they are HTML-escaped
+ * (many Markdown renderers pass raw HTML through) and any line-leading `#`, `>` or `-` is
+ * neutralised so the text can't inject a heading, blockquote or list item into the document's
+ * own structure.
+ */
+function escapeMarkdownText(value) {
+    return escapeHtml(value)
+        .split(/\r?\n/)
+        .map((line) => line.replace(/^(\s*)([#>-])/, '$1\\$2'))
+        .join('\n');
+}
+/** A stable, URL-safe anchor for a heading, deduplicated by the caller's `taken` set. */
+function anchorOf(heading, taken) {
+    const base = heading
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'section';
+    let anchor = base;
+    let n = 2;
+    while (taken.has(anchor)) {
+        anchor = `${base}-${String(n)}`;
+        n += 1;
+    }
+    taken.add(anchor);
+    return anchor;
+}
+/** `{ns}local` for a QName, or the empty marker when there is none. */
+function clark(name) {
+    return name === undefined ? EMPTY : qnameToString(name);
+}
+/** How one `wsdl:part` binds to the schema: an element reference, a type reference, or neither. */
+function partTarget(part) {
+    if (part.element !== undefined) {
+        return `element ${qnameToString(part.element)}`;
+    }
+    if (part.type !== undefined) {
+        return `type ${qnameToString(part.type)}`;
+    }
+    return EMPTY;
+}
+/** The `wsdl:message` a message reference points at, when the merged definition has it. */
+function messageParts(definition, name) {
+    if (name === undefined) {
+        return EMPTY;
+    }
+    const message = findMessage(definition, name);
+    if (message === undefined || message.parts.length === 0) {
+        return qnameToString(name);
+    }
+    return `${qnameToString(name)} (${message.parts.map((part) => `${part.name}: ${partTarget(part)}`).join(', ')})`;
+}
+/**
+ * The XML source of the element that starts on `line` (1-based) of `text`, capped at
+ * `maxLines`. Textual rather than DOM-based on purpose: the point is to show the author's own
+ * markup, comments and formatting, not a re-serialisation of it. An attribute value containing
+ * a literal `>` would end the snippet early — vanishingly rare in a schema, and worth the
+ * simplicity of not carrying a second parser here.
+ *
+ * @param text the whole document the declaration lives in
+ * @param line the 1-based line the declaration's start tag opens on
+ * @param maxLines how many lines to keep before cutting the snippet with an ellipsis
+ * @returns the declaration's source, dedented, or `''` when `line` is out of range
+ *
+ * Deliberately duplicated, not shared, with `apps/desktop/src/renderer/features/interface-editor/source-snippet.ts`
+ * (used by the Schema tab): that one must stay dependency-free JS the sandboxed renderer can run without pulling
+ * in `@wirebench/engine`'s main entry, which drags in Node built-ins (`node:crypto`, `node:fs`, …) the renderer
+ * cannot load. Keep the two in sync using `packages/engine/test/helpers/source-snippet-cases.ts`, a fixture both
+ * test suites run against.
+ */
+export function sourceSnippet(text, line, maxLines = 30) {
+    const lines = text.split(/\r?\n/);
+    if (line < 1 || line > lines.length) {
+        return '';
+    }
+    // Work on the split lines rather than a character offset into `text`: the document may use
+    // CRLF, and a byte offset computed from LF-joined lines would drift by one per preceding line.
+    const rest = lines.slice(line - 1).join('\n');
+    const open = /<\s*([^\s/>!?]+)/.exec(rest);
+    if (open?.[1] === undefined) {
+        return dedent([lines[line - 1] ?? '']);
+    }
+    const tag = open[1];
+    const pattern = new RegExp(`<(/?)${escapeRegExp(tag)}(\\s[^>]*?)?(/?)>`, 'g');
+    let depth = 0;
+    let end = -1;
+    for (const match of rest.matchAll(pattern)) {
+        const closing = match[1] === '/';
+        const selfClosing = match[3] === '/';
+        if (closing) {
+            depth -= 1;
+        }
+        else if (!selfClosing) {
+            depth += 1;
+        }
+        if (depth <= 0) {
+            end = match.index + match[0].length;
+            break;
+        }
+    }
+    const source = end === -1 ? rest : rest.slice(0, end);
+    const collected = source.split(/\r?\n/);
+    const capped = collected.slice(0, maxLines);
+    const truncated = capped.length < collected.length || end === -1;
+    return truncated ? `${dedent(capped)}\n…` : dedent(capped);
+}
+/** Strips the first line's leading whitespace from every line that starts with it. */
+function dedent(lines) {
+    const indent = /^\s*/.exec(lines[0] ?? '')?.[0] ?? '';
+    if (indent === '') {
+        return lines.join('\n');
+    }
+    return lines.map((line) => (line.startsWith(indent) ? line.slice(indent.length) : line.trimStart())).join('\n');
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** The bundle's document texts, keyed by canonical location. */
+function textsOf(result) {
+    return new Map(result.bundle.documents.map((document) => [document.location, document.text]));
+}
+/** The overview block: where the definition came from, and what it is made of. */
+function overviewBlock(result, title) {
+    const { definition, bundle, schemaSet } = result;
+    return {
+        heading: 'Overview',
+        fields: [
+            { label: 'Title', value: title },
+            { label: 'Definition', value: bundle.root.location },
+            { label: 'Target namespace', value: definition.targetNamespace || EMPTY },
+            { label: 'Documents', value: String(bundle.documents.length) },
+            { label: 'Operations', value: String(result.operations.length) },
+            { label: 'Schema namespaces', value: schemaSet.namespaces.length > 0 ? schemaSet.namespaces.join(', ') : EMPTY },
+        ],
+        ...(definition.documentation !== undefined ? { paragraphs: [definition.documentation] } : {}),
+        table: {
+            columns: ['Document', 'Kind', 'Namespace'],
+            rows: bundle.documents.map((document) => [document.location, document.kind, document.namespace ?? EMPTY]),
+        },
+    };
+}
+function servicesBlock(definition) {
+    const rows = [];
+    for (const service of definition.services) {
+        for (const port of service.ports) {
+            const binding = findBinding(definition, port.binding);
+            rows.push([
+                service.name.localName,
+                port.name,
+                clark(port.binding),
+                binding?.soapVersion ?? EMPTY,
+                port.address ?? EMPTY,
+            ]);
+        }
+    }
+    return {
+        heading: 'Services and ports',
+        table: { columns: ['Service', 'Port', 'Binding', 'SOAP', 'Address'], rows },
+    };
+}
+function bindingsBlock(definition) {
+    return {
+        heading: 'Bindings',
+        table: {
+            columns: ['Binding', 'Port type', 'SOAP', 'Style', 'Transport', 'Operations'],
+            rows: definition.bindings.map((binding) => [
+                clark(binding.name),
+                clark(binding.type),
+                binding.soapVersion,
+                binding.style,
+                binding.transport ?? EMPTY,
+                binding.operations.map((operation) => operation.name).join(', ') || EMPTY,
+            ]),
+        },
+    };
+}
+/** One operation's own sub-block: transport metadata, documentation and its messages. */
+function operationBlock(definition, binding, bindingOperation) {
+    const portType = findPortType(definition, binding.type);
+    const abstract = portType?.operations.find((candidate) => candidate.name === bindingOperation.name);
+    const rows = [
+        ['Input', messageParts(definition, abstract?.input?.message)],
+        ['Output', messageParts(definition, abstract?.output?.message)],
+    ];
+    for (const fault of abstract?.faults ?? []) {
+        rows.push([`Fault "${fault.name}"`, messageParts(definition, fault.message)]);
+    }
+    const headers = [...(bindingOperation.input?.headers ?? []), ...(bindingOperation.output?.headers ?? [])];
+    for (const header of headers) {
+        rows.push(['SOAP header', `${qnameToString(header.message)} part ${header.part} (${header.use})`]);
+    }
+    return {
+        heading: `${binding.name.localName}.${bindingOperation.name}`,
+        fields: [
+            { label: 'SOAPAction', value: bindingOperation.soapAction ?? EMPTY },
+            { label: 'Style', value: bindingOperation.style ?? binding.style },
+            { label: 'Use', value: bindingOperation.input?.body.use ?? EMPTY },
+            { label: 'SOAP version', value: binding.soapVersion },
+        ],
+        ...(abstract?.documentation !== undefined ? { paragraphs: [abstract.documentation] } : {}),
+        table: { columns: ['Message', 'Details'], rows },
+    };
+}
+function operationsBlock(definition) {
+    const children = [];
+    for (const binding of definition.bindings) {
+        for (const operation of binding.operations) {
+            children.push(operationBlock(definition, binding, operation));
+        }
+    }
+    return { heading: 'Operations', children };
+}
+function messagesBlock(definition) {
+    const rows = [];
+    for (const message of definition.messages) {
+        if (message.parts.length === 0) {
+            rows.push([clark(message.name), EMPTY, EMPTY]);
+            continue;
+        }
+        for (const part of message.parts) {
+            rows.push([clark(message.name), part.name, partTarget(part)]);
+        }
+    }
+    return { heading: 'Messages', table: { columns: ['Message', 'Part', 'Binds to'], rows } };
+}
+/** One schema component's sub-block: its kind, its type reference and the XML that declares it. */
+function componentBlock(kind, name, typeName, source, texts) {
+    const text = texts.get(source.location);
+    const snippet = text !== undefined && source.line !== undefined ? sourceSnippet(text, source.line) : '';
+    return {
+        heading: `${kind} ${name}`,
+        fields: [
+            { label: 'Type', value: clark(typeName) },
+            {
+                label: 'Declared in',
+                value: `${source.location}${source.line !== undefined ? `:${String(source.line)}` : ''}`,
+            },
+        ],
+        ...(snippet !== '' ? { code: snippet } : {}),
+    };
+}
+function schemaBlock(schemaSet, texts) {
+    const children = [];
+    for (const uri of [...schemaSet.namespaces].sort((a, b) => a.localeCompare(b))) {
+        const components = [];
+        for (const element of [...schemaSet.elementsInNamespace(uri)].sort((a, b) => a.name.localName.localeCompare(b.name.localName))) {
+            components.push(componentBlock('element', element.name.localName, element.type, element.source, texts));
+        }
+        for (const type of [...schemaSet.typesInNamespace(uri)].sort((a, b) => (a.name?.localName ?? '').localeCompare(b.name?.localName ?? ''))) {
+            if (type.name === undefined) {
+                continue;
+            }
+            components.push(componentBlock(type.kind, type.name.localName, undefined, type.source, texts));
+        }
+        children.push({ heading: `Namespace ${uri === '' ? '(no namespace)' : uri}`, children: components });
+    }
+    return { heading: 'Schema components', children };
+}
+/** The document's title: the caller's, then the first service's name, then the root file name. */
+function titleOf(result, options) {
+    if (options.title !== undefined && options.title.trim() !== '') {
+        return options.title.trim();
+    }
+    const service = result.definition.services[0];
+    if (service !== undefined) {
+        return service.name.localName;
+    }
+    return result.bundle.root.location.split('/').pop() ?? 'Definition';
+}
+/**
+ * Assigns every block (recursively, document order) a deduplicated anchor into `anchors`,
+ * sharing one `taken` set across the whole tree. Called once, up front, so the table of
+ * contents and the body headings are guaranteed to agree — see {@link renderHtml}.
+ */
+function collectAnchors(blocks, taken, anchors) {
+    for (const block of blocks) {
+        anchors.set(block, anchorOf(block.heading, taken));
+        if (block.children !== undefined) {
+            collectAnchors(block.children, taken, anchors);
+        }
+    }
+}
+function renderHtmlBlock(block, level, anchors) {
+    const tag = `h${String(Math.min(level, 6))}`;
+    const anchor = anchors.get(block) ?? '';
+    const parts = [`<${tag} id="${escapeHtml(anchor)}">${escapeHtml(block.heading)}</${tag}>`];
+    if (block.fields !== undefined && block.fields.length > 0) {
+        parts.push(`<dl>${block.fields
+            .map((field) => `<dt>${escapeHtml(field.label)}</dt><dd>${escapeHtml(field.value)}</dd>`)
+            .join('')}</dl>`);
+    }
+    for (const paragraph of block.paragraphs ?? []) {
+        parts.push(`<p>${escapeHtml(paragraph)}</p>`);
+    }
+    if (block.table !== undefined && block.table.rows.length > 0) {
+        const head = block.table.columns.map((column) => `<th>${escapeHtml(column)}</th>`).join('');
+        const body = block.table.rows
+            .map((row) => `<tr>${row.map((cell) => `<td>${escapeHtml(cell)}</td>`).join('')}</tr>`)
+            .join('');
+        parts.push(`<table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table>`);
+    }
+    if (block.code !== undefined) {
+        parts.push(`<pre><code>${escapeHtml(block.code)}</code></pre>`);
+    }
+    for (const child of block.children ?? []) {
+        parts.push(renderHtmlBlock(child, level + 1, anchors));
+    }
+    return parts.join('\n');
+}
+/** Inline stylesheet of the HTML document; no external resources, no scripts. */
+const HTML_STYLE = `
+:root { color-scheme: light dark; }
+body { font: 15px/1.55 -apple-system, "Segoe UI", system-ui, sans-serif; margin: 0 auto; max-width: 60rem; padding: 2rem 1.5rem; }
+h1 { font-size: 1.9rem; margin-bottom: 0.25rem; }
+h2 { border-bottom: 1px solid currentColor; margin-top: 2.5rem; padding-bottom: 0.2rem; }
+h3, h4 { margin-top: 1.75rem; }
+dl { display: grid; gap: 0.15rem 1rem; grid-template-columns: max-content 1fr; margin: 0.5rem 0; }
+dt { font-weight: 600; }
+dd { margin: 0; overflow-wrap: anywhere; }
+table { border-collapse: collapse; display: block; margin: 0.75rem 0; overflow-x: auto; width: 100%; }
+th, td { border: 1px solid rgba(128,128,128,0.45); padding: 0.3rem 0.55rem; text-align: left; vertical-align: top; }
+th { background: rgba(128,128,128,0.14); }
+pre { background: rgba(128,128,128,0.12); border-radius: 4px; overflow-x: auto; padding: 0.6rem 0.8rem; }
+code { font: 13px/1.45 ui-monospace, SFMono-Regular, Menlo, monospace; }
+nav ol { padding-left: 1.2rem; }
+footer { color: rgba(128,128,128,1); font-size: 0.85rem; margin-top: 3rem; }
+`.trim();
+function renderHtml(title, blocks) {
+    // One shared pre-pass over the whole tree: the TOC and the body headings then look up the
+    // very same anchors instead of each computing (and potentially deduplicating) their own.
+    const anchors = new Map();
+    collectAnchors(blocks, new Set(), anchors);
+    const toc = blocks.map((block) => ({ heading: block.heading, anchor: anchors.get(block) ?? '' }));
+    const body = blocks.map((block) => renderHtmlBlock(block, 2, anchors)).join('\n');
+    return [
+        '<!DOCTYPE html>',
+        '<html lang="en">',
+        '<head>',
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        `<title>${escapeHtml(title)}</title>`,
+        `<style>\n${HTML_STYLE}\n</style>`,
+        '</head>',
+        '<body>',
+        `<h1>${escapeHtml(title)}</h1>`,
+        `<nav><ol>${toc
+            .map((entry) => `<li><a href="#${escapeHtml(entry.anchor)}">${escapeHtml(entry.heading)}</a></li>`)
+            .join('')}</ol></nav>`,
+        body,
+        '<footer>Generated by Wirebench.</footer>',
+        '</body>',
+        '</html>',
+        '',
+    ].join('\n');
+}
+function renderMarkdownBlock(block, level) {
+    const parts = [`${'#'.repeat(Math.min(level, 6))} ${block.heading}`];
+    if (block.fields !== undefined && block.fields.length > 0) {
+        parts.push(block.fields.map((field) => `- **${field.label}:** ${escapeMarkdownCell(field.value)}`).join('\n'));
+    }
+    for (const paragraph of block.paragraphs ?? []) {
+        parts.push(escapeMarkdownText(paragraph));
+    }
+    if (block.table !== undefined && block.table.rows.length > 0) {
+        const head = `| ${block.table.columns.join(' | ')} |`;
+        const rule = `| ${block.table.columns.map(() => '---').join(' | ')} |`;
+        const rows = block.table.rows.map((row) => `| ${row.map(escapeMarkdownCell).join(' | ')} |`);
+        parts.push([head, rule, ...rows].join('\n'));
+    }
+    if (block.code !== undefined) {
+        parts.push(['```xml', block.code, '```'].join('\n'));
+    }
+    for (const child of block.children ?? []) {
+        parts.push(renderMarkdownBlock(child, level + 1));
+    }
+    return parts.join('\n\n');
+}
+function renderMarkdown(title, blocks) {
+    const taken = new Set();
+    const toc = blocks.map((block) => `- [${block.heading}](#${anchorOf(block.heading, taken)})`);
+    return [
+        `# ${escapeMarkdownText(title)}`,
+        '## Contents',
+        toc.join('\n'),
+        ...blocks.map((block) => renderMarkdownBlock(block, 2)),
+        '---',
+        'Generated by Wirebench.',
+        '',
+    ].join('\n\n');
+}
+/**
+ * Renders `result` as a complete, self-contained document — a single HTML page
+ * or a single Markdown file — covering the definition's services and ports,
+ * bindings, operations (with their messages and SOAP headers), messages and
+ * global schema components with the XML that declares them.
+ *
+ * @param result the imported definition to document
+ * @param options output format and an optional title
+ * @returns the whole document as a string; the caller decides where it lands
+ */
+export function generateDocs(result, options) {
+    const title = titleOf(result, options);
+    const texts = textsOf(result);
+    const blocks = [
+        overviewBlock(result, title),
+        servicesBlock(result.definition),
+        bindingsBlock(result.definition),
+        operationsBlock(result.definition),
+        messagesBlock(result.definition),
+        schemaBlock(result.schemaSet, texts),
+    ];
+    return options.format === 'html' ? renderHtml(title, blocks) : renderMarkdown(title, blocks);
+}

package/dist/wsdl/dom-utils.d.ts

@@ -0,0 +1,15 @@
+import type { Document, Element } from '@xmldom/xmldom';
+/** Returns the direct child elements of `parent` matching `namespaceUri`/`localName`. */
+export declare function childElements(parent: Element | Document, namespaceUri: string, localName: string): Element[];
+/** Returns the first direct child element of `parent` matching `namespaceUri`/`localName`, if any. */
+export declare function firstChildElement(parent: Element | Document, namespaceUri: string, localName: string): Element | undefined;
+/**
+ * Reads a `wsdl:documentation` child of `element` (any namespace's `documentation`
+ * local-name is not sufficient; callers pass the WSDL namespace), trims its text,
+ * and returns `undefined` for a missing or empty element.
+ */
+export declare function readDocumentation(element: Element, wsdlNamespaceUri: string): string | undefined;
+/** Reads a required attribute, throwing `WsdlParseError('wsdl-invalid')` with position details if absent. */
+export declare function requireAttribute(element: Element, name: string, location: string): string;
+/** Reads an optional attribute, returning `undefined` when absent (rather than xmldom's `null`). */
+export declare function optionalAttribute(element: Element, name: string): string | undefined;

package/dist/wsdl/dom-utils.js

@@ -0,0 +1,50 @@
+import { WsdlParseError } from '../errors.js';
+import { getPosition } from '../xml/parse.js';
+/** Returns the direct child elements of `parent` matching `namespaceUri`/`localName`. */
+export function childElements(parent, namespaceUri, localName) {
+    const result = [];
+    let child = parent.firstChild;
+    while (child !== null) {
+        if (child.nodeType === 1) {
+            const el = child;
+            if (el.namespaceURI === namespaceUri && el.localName === localName) {
+                result.push(el);
+            }
+        }
+        child = child.nextSibling;
+    }
+    return result;
+}
+/** Returns the first direct child element of `parent` matching `namespaceUri`/`localName`, if any. */
+export function firstChildElement(parent, namespaceUri, localName) {
+    return childElements(parent, namespaceUri, localName)[0];
+}
+/**
+ * Reads a `wsdl:documentation` child of `element` (any namespace's `documentation`
+ * local-name is not sufficient; callers pass the WSDL namespace), trims its text,
+ * and returns `undefined` for a missing or empty element.
+ */
+export function readDocumentation(element, wsdlNamespaceUri) {
+    const docEl = firstChildElement(element, wsdlNamespaceUri, 'documentation');
+    if (docEl === undefined) {
+        return undefined;
+    }
+    const text = (docEl.textContent ?? '').trim();
+    return text.length > 0 ? text : undefined;
+}
+/** Reads a required attribute, throwing `WsdlParseError('wsdl-invalid')` with position details if absent. */
+export function requireAttribute(element, name, location) {
+    const value = element.getAttribute(name);
+    if (value === null || value === '') {
+        const pos = getPosition(element);
+        throw new WsdlParseError('wsdl-invalid', `Element <${element.tagName}> is missing required attribute "${name}"`, {
+            details: { location, element: element.tagName, attribute: name, ...pos },
+        });
+    }
+    return value;
+}
+/** Reads an optional attribute, returning `undefined` when absent (rather than xmldom's `null`). */
+export function optionalAttribute(element, name) {
+    const value = element.getAttribute(name);
+    return value === null || value === '' ? undefined : value;
+}

package/dist/wsdl/export-definition.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Writes an entire resolved definition (the root WSDL and every document it
+ * imports/includes) to a plain folder — "Export Definition": the
+ * folder is self-contained and portable, with every cross-document reference
+ * rewritten to a relative file name so the exported set opens standalone.
+ *
+ * Unlike `wsdl/cache.ts`, documents ARE re-serialised here (the rewritten
+ * reference has to land somewhere), and no manifest is written.
+ */
+import type { FsLike } from '../project/fs.js';
+import type { DefinitionBundle } from './resolver.js';
+/** Options accepted by {@link exportDefinition}. */
+export interface ExportDefinitionOptions {
+    /** Overrides the file system, e.g. for tests. Defaults to `nodeFs`. */
+    readonly fs?: FsLike;
+}
+/** One document written by {@link exportDefinition}. */
+export interface ExportedFile {
+    /** File name written inside the target directory. */
+    readonly file: string;
+    /** The document's canonical location in the original bundle. */
+    readonly location: string;
+}
+/** The result of {@link exportDefinition}. */
+export interface ExportResult {
+    readonly files: readonly ExportedFile[];
+}
+/**
+ * Writes every document of `bundle` to `targetDir` (created if needed), with
+ * every `wsdl:import/@location`, `xs:import/@schemaLocation`,
+ * `xs:include/@schemaLocation` and `xs:redefine/@schemaLocation` rewritten to
+ * the relative file name of the referenced document, so the folder is
+ * self-contained and can be re-imported standalone.
+ *
+ * @param bundle the resolved definition to export
+ * @param targetDir absolute path of the destination folder
+ */
+export declare function exportDefinition(bundle: DefinitionBundle, targetDir: string, options?: ExportDefinitionOptions): Promise<ExportResult>;

package/dist/wsdl/export-definition.js

@@ -0,0 +1,100 @@
+/**
+ * Writes an entire resolved definition (the root WSDL and every document it
+ * imports/includes) to a plain folder — "Export Definition": the
+ * folder is self-contained and portable, with every cross-document reference
+ * rewritten to a relative file name so the exported set opens standalone.
+ *
+ * Unlike `wsdl/cache.ts`, documents ARE re-serialised here (the rewritten
+ * reference has to land somewhere), and no manifest is written.
+ */
+import { join } from 'node:path';
+import { nodeFs } from '../project/fs.js';
+import { writeFileAtomic } from '../project/fs.js';
+import { NS } from '../xml/namespaces.js';
+import { parseXml } from '../xml/parse.js';
+import { serializeXml } from '../xml/serialize.js';
+import { assignFileNames } from './cache-naming.js';
+import { childElements, firstChildElement, optionalAttribute } from './dom-utils.js';
+/** Resolves `ref` (an import/include/redefine location) against `base` using the WHATWG `URL` class. */
+function resolveUrl(ref, base) {
+    return new URL(ref, base).toString();
+}
+/**
+ * Rewrites one `location`/`schemaLocation` attribute on `element` to the
+ * exported file name of the document it points to, when that document is
+ * part of the bundle. References to a document the bundle never resolved
+ * (a namespace-only import, or one that failed to fetch) are left as-is.
+ */
+function rewriteReference(element, attrName, ownerLocation, fileByLocation) {
+    const ref = optionalAttribute(element, attrName);
+    if (ref === undefined) {
+        return;
+    }
+    const absolute = resolveUrl(ref, ownerLocation);
+    const file = fileByLocation.get(absolute);
+    if (file !== undefined) {
+        element.setAttribute(attrName, file);
+    }
+}
+/** Rewrites the `xs:import`/`xs:include`/`xs:redefine` children of one `xs:schema` element. */
+function rewriteSchemaReferences(schemaEl, ownerLocation, fileByLocation) {
+    for (const el of childElements(schemaEl, NS.XSD, 'import')) {
+        rewriteReference(el, 'schemaLocation', ownerLocation, fileByLocation);
+    }
+    for (const el of childElements(schemaEl, NS.XSD, 'include')) {
+        rewriteReference(el, 'schemaLocation', ownerLocation, fileByLocation);
+    }
+    for (const el of childElements(schemaEl, NS.XSD, 'redefine')) {
+        rewriteReference(el, 'schemaLocation', ownerLocation, fileByLocation);
+    }
+}
+/**
+ * Rewrites every cross-document reference inside `root` (the document
+ * element of a freshly re-parsed copy of `doc` — never the DOM node owned by
+ * the original bundle, which callers may still hold onto), in place.
+ */
+function rewriteDocumentReferences(root, doc, fileByLocation) {
+    if (doc.kind === 'wsdl') {
+        for (const el of childElements(root, NS.WSDL, 'import')) {
+            rewriteReference(el, 'location', doc.location, fileByLocation);
+        }
+        const typesEl = firstChildElement(root, NS.WSDL, 'types');
+        if (typesEl !== undefined) {
+            for (const schemaEl of childElements(typesEl, NS.XSD, 'schema')) {
+                rewriteSchemaReferences(schemaEl, doc.location, fileByLocation);
+            }
+        }
+    }
+    else {
+        rewriteSchemaReferences(root, doc.location, fileByLocation);
+    }
+}
+/**
+ * Writes every document of `bundle` to `targetDir` (created if needed), with
+ * every `wsdl:import/@location`, `xs:import/@schemaLocation`,
+ * `xs:include/@schemaLocation` and `xs:redefine/@schemaLocation` rewritten to
+ * the relative file name of the referenced document, so the folder is
+ * self-contained and can be re-imported standalone.
+ *
+ * @param bundle the resolved definition to export
+ * @param targetDir absolute path of the destination folder
+ */
+export async function exportDefinition(bundle, targetDir, options) {
+    const fs = options?.fs ?? nodeFs;
+    const named = assignFileNames(bundle.documents);
+    const fileByLocation = new Map(named.map(({ document, file }) => [document.location, file]));
+    const files = [];
+    for (const { document, file } of named) {
+        // Re-parse rather than mutate `document.document` in place: that DOM node is owned by
+        // the caller's bundle, which may still be in use (e.g. for the schema set) after export.
+        const working = parseXml(document.text, { location: document.location });
+        const root = working.documentElement;
+        if (root !== null) {
+            rewriteDocumentReferences(root, document, fileByLocation);
+        }
+        const xml = serializeXml(working);
+        await writeFileAtomic(fs, join(targetDir, file), xml);
+        files.push({ file, location: document.location });
+    }
+    return { files };
+}

package/dist/wsdl/fetch.d.ts

@@ -0,0 +1,13 @@
+import type { FetchDocument } from './resolver.js';
+/**
+ * Creates the default {@link FetchDocument} implementation: `file:` URLs are
+ * read from disk via `node:fs/promises`, and `http(s):` URLs are fetched via
+ * the global `fetch` (following redirects, with a 20s timeout combined with
+ * the caller's `AbortSignal`, and a `wirebench/0.1` User-Agent).
+ *
+ * Text is decoded as UTF-8 by default, honouring an `iso-8859-1` `encoding`
+ * in the document's XML declaration when present (see {@link decodeXmlBytes}
+ * for why `utf-16` isn't sniffed the same way). Other declared encodings
+ * fall back to UTF-8.
+ */
+export declare function createDefaultFetchDocument(): FetchDocument;