@wirebench/engine 2.1.1

package/dist/wsa/policy-detect.js

@@ -0,0 +1,245 @@
+/**
+ * Reads what a WSDL says about WS-Addressing, so an imported interface can turn addressing on
+ * by itself instead of making the user discover the requirement from a runtime fault.
+ *
+ * Three shapes are recognised, all of which real services use:
+ * - `wsaw:UsingAddressing` (or the 2004 `wsap:UsingAddressing`) on the binding or the port;
+ * - a `wsp:Policy` — attached inline or through a `wsp:PolicyReference` to a `#id` — that
+ *   contains `wsam:Addressing` or one of the `UsingAddressing` assertions;
+ * - `wsam:Action` (or `wsaw:Action`) on a `portType` operation's `wsdl:input`, which also
+ *   supplies that operation's default `wsa:Action`.
+ */
+import { NS } from '../xml/namespaces.js';
+import { findPortType } from '../wsdl/model.js';
+import { qnameEquals, qnameToString } from '../wsdl/qname.js';
+/** The `wsp:Policy`/`wsp:PolicyReference` namespaces, newest first. */
+const POLICY_NAMESPACES = [NS.WSP, NS.WSP_2004];
+/** Every descendant element of `root` (excluding `root` itself), in document order. */
+function descendants(root) {
+    const found = [];
+    const walk = (element) => {
+        for (let node = element.firstChild; node !== null; node = node.nextSibling) {
+            if (node.nodeType === 1) {
+                found.push(node);
+                walk(node);
+            }
+        }
+    };
+    walk(root);
+    return found;
+}
+/** True when `value` is the WS-Policy "true" spelling (`true` or `1`) used by `wsp:Optional`. */
+function isPolicyTrue(value) {
+    return value === 'true' || value === '1';
+}
+/** True when `element` carries `wsp:Optional="true"` (either policy-namespace flavour). */
+function isOptionalAssertion(element) {
+    return POLICY_NAMESPACES.some((ns) => isPolicyTrue(element.getAttributeNS(ns, 'Optional')));
+}
+/** True when `element` is one of the addressing assertions; describes which flavour and optionality. */
+function addressingAssertion(element) {
+    const { namespaceURI: ns, localName } = element;
+    const optional = isOptionalAssertion(element);
+    if (ns === NS.WSAP_2004 && localName === 'UsingAddressing') {
+        return { version: '2004/08', optional };
+    }
+    if (ns === NS.WSAW && localName === 'UsingAddressing') {
+        return { version: '2005/08', optional };
+    }
+    if (ns === NS.WSAM && (localName === 'Addressing' || localName === 'AnonymousResponses')) {
+        return { version: '2005/08', optional };
+    }
+    return undefined;
+}
+/** The `wsp:Policy` element with `wsu:Id`/`xml:id`/`Id` equal to `id`, anywhere in `doc`. */
+function policyById(doc, id) {
+    const root = doc.documentElement;
+    if (root === null) {
+        return undefined;
+    }
+    for (const element of descendants(root)) {
+        if (!POLICY_NAMESPACES.some((ns) => ns === element.namespaceURI) || element.localName !== 'Policy') {
+            continue;
+        }
+        const wsuId = element.getAttributeNS(NS.WSU, 'Id');
+        const xmlId = element.getAttributeNS(NS.XML, 'id');
+        const plainId = element.getAttribute('Id');
+        const candidate = wsuId !== null && wsuId.length > 0
+            ? wsuId
+            : xmlId !== null && xmlId.length > 0
+                ? xmlId
+                : plainId !== null && plainId.length > 0
+                    ? plainId
+                    : undefined;
+        if (candidate === id) {
+            return element;
+        }
+    }
+    return undefined;
+}
+/**
+ * The addressing assertions reachable from `owner`: its own extension children, plus every
+ * policy it attaches inline or references by `#id`.
+ */
+function assertionsUnder(owner) {
+    const versions = [];
+    const consider = (element) => {
+        const assertion = addressingAssertion(element);
+        if (assertion !== undefined) {
+            versions.push(assertion);
+        }
+    };
+    for (let node = owner.firstChild; node !== null; node = node.nextSibling) {
+        if (node.nodeType !== 1) {
+            continue;
+        }
+        const element = node;
+        consider(element);
+        const isPolicyNs = POLICY_NAMESPACES.some((ns) => ns === element.namespaceURI);
+        if (isPolicyNs && element.localName === 'Policy') {
+            descendants(element).forEach(consider);
+            continue;
+        }
+        if (isPolicyNs && element.localName === 'PolicyReference') {
+            const uri = element.getAttribute('URI');
+            const doc = owner.ownerDocument;
+            if (uri !== null && uri.startsWith('#') && doc !== null) {
+                const policy = policyById(doc, uri.slice(1));
+                if (policy !== undefined) {
+                    consider(policy);
+                    descendants(policy).forEach(consider);
+                }
+            }
+        }
+    }
+    return versions;
+}
+/** The `wsam:Action`/`wsaw:Action` attribute of a `portType` operation's `wsdl:input`. */
+function declaredAction(operation) {
+    const input = operation?.input?.sourceElement;
+    if (input === undefined) {
+        return undefined;
+    }
+    for (const ns of [NS.WSAM, NS.WSAW]) {
+        const value = input.getAttributeNS(ns, 'Action');
+        if (value !== null && value.length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/** Joins `parts` with single `/` separators, tolerating a target namespace with a trailing one. */
+function joinUri(...parts) {
+    return parts
+        .map((part, index) => (index === 0 ? part.replace(/\/+$/, '') : part.replace(/^\/+|\/+$/g, '')))
+        .join('/');
+}
+/**
+ * The default `wsa:Action` for one operation, following the WS-Addressing 1.0 WSDL binding's
+ * precedence: an explicit `wsam:Action`, then a non-empty `soapAction`, then the default
+ * pattern `<targetNamespace>/<portType>/<operation>Request`.
+ *
+ * @param definition the definition the operation belongs to
+ * @param portType the operation's `wsdl:portType`
+ * @param operation the abstract `wsdl:operation`
+ * @param options `soapAction` from the binding operation, when it has one
+ */
+export function defaultAction(definition, portType, operation, options) {
+    const declared = declaredAction(operation);
+    if (declared !== undefined) {
+        return declared;
+    }
+    const soapAction = options?.soapAction;
+    if (soapAction !== undefined && soapAction.length > 0) {
+        return soapAction;
+    }
+    const namespace = portType.name.namespaceUri.length > 0 ? portType.name.namespaceUri : definition.targetNamespace;
+    return joinUri(namespace, portType.name.localName, `${operation.name}Request`);
+}
+/** The ports, across every service, that bind to `binding`. */
+function portElementsFor(definition, binding) {
+    const elements = [];
+    for (const service of definition.services) {
+        for (const port of service.ports) {
+            if (qnameEquals(port.binding, binding.name) && port.sourceElement !== undefined) {
+                elements.push(port.sourceElement);
+            }
+        }
+    }
+    return elements;
+}
+/**
+ * What `definition` says about WS-Addressing for one binding operation.
+ *
+ * `version` is `'2004/08'` only when *every* marker found is a 2004 one; a definition that
+ * mixes the two (or declares none at all) is treated as 2005/08, the version a modern stack
+ * speaks.
+ *
+ * @param definition the imported definition
+ * @param binding the binding the operation belongs to
+ * @param operation the binding operation, for its `soapAction` and abstract counterpart
+ */
+export function detectWsaDefaults(definition, binding, operation) {
+    const owners = [
+        ...(binding.sourceElement !== undefined ? [binding.sourceElement] : []),
+        ...portElementsFor(definition, binding),
+    ];
+    const assertions = owners.flatMap(assertionsUnder);
+    const portType = findPortType(definition, binding.type);
+    const abstract = portType?.operations.find((candidate) => candidate.name === operation.name);
+    const action = declaredAction(abstract);
+    const required = assertions.filter((assertion) => !assertion.optional);
+    const usingAddressing = required.length > 0 || action !== undefined;
+    const versionSource = required.length > 0 ? required : assertions;
+    const version = versionSource.length > 0 && versionSource.every((a) => a.version === '2004/08') ? '2004/08' : '2005/08';
+    // Optional only when the WSDL merely offers addressing (no required assertion, no declared
+    // action) but does say something — an `wsp:Optional="true"` assertion.
+    const optional = !usingAddressing && assertions.some((assertion) => assertion.optional);
+    return {
+        usingAddressing,
+        version,
+        ...(action !== undefined ? { action } : {}),
+        ...(optional ? { optional: true } : {}),
+    };
+}
+/** The `defaultActionByOperation` key for one binding operation: `{ns}Binding|Operation`. */
+export function wsaActionKey(bindingName, operationName) {
+    return `${qnameToString(bindingName)}|${operationName}`;
+}
+/**
+ * Folds {@link detectWsaDefaults} and {@link defaultAction} over every binding operation, for
+ * the interface summary an import produces.
+ *
+ * @param definition the imported definition
+ */
+export function summarizeWsa(definition) {
+    let enabled = false;
+    let optional = false;
+    const versions = [];
+    const defaultActionByOperation = {};
+    for (const binding of definition.bindings) {
+        const portType = findPortType(definition, binding.type);
+        for (const operation of binding.operations) {
+            const detected = detectWsaDefaults(definition, binding, operation);
+            if (detected.usingAddressing) {
+                enabled = true;
+                versions.push(detected.version);
+            }
+            else if (detected.optional === true) {
+                optional = true;
+            }
+            const abstract = portType?.operations.find((candidate) => candidate.name === operation.name);
+            if (portType !== undefined && abstract !== undefined) {
+                defaultActionByOperation[wsaActionKey(binding.name, operation.name)] = defaultAction(definition, portType, abstract, {
+                    ...(operation.soapAction !== undefined ? { soapAction: operation.soapAction } : {}),
+                });
+            }
+        }
+    }
+    return {
+        enabled,
+        optional,
+        version: versions.length > 0 && versions.every((v) => v === '2004/08') ? '2004/08' : '2005/08',
+        defaultActionByOperation,
+    };
+}

package/dist/wsdl/cache-naming.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Derives on-disk file names for the documents in a {@link DefinitionBundle}
+ * when writing a definition cache or an export folder. Shared by
+ * `wsdl/cache.ts` and `wsdl/export-definition.ts` so both lay documents out
+ * identically (a location always maps to the same relative file name).
+ *
+ * File names are sanitised with the same segment-validation rules Task 17
+ * uses for project slugs ({@link sanitiseFileName}/{@link isReservedFileName}
+ * from `project/paths.ts`), so a hyphen or space is preserved and a Windows
+ * reserved device name (`CON`, `NUL`, `COM1`, ...) is renamed safely instead
+ * of being written as-is.
+ */
+/** The least a document must say for a file name to be derived from it. */
+export interface NameableDocument {
+    readonly location: string;
+    /** The extension a document with no usable name of its own falls back to (`wsdl`, `xsd`, `yaml`). */
+    readonly kind: string;
+}
+/** Options accepted by {@link assignFileNames}. */
+export interface AssignFileNamesOptions {
+    /** File name for the root document when its location gives none. Defaults to `service.wsdl`. */
+    readonly rootFile?: string;
+}
+/** One document's assigned on-disk file name, alongside the document itself. */
+export interface NamedDocument<T extends NameableDocument = NameableDocument> {
+    readonly document: T;
+    readonly file: string;
+}
+/**
+ * Assigns a unique, sanitised file name to every document in `documents`
+ * (root first, in the order given), de-duplicating collisions with a
+ * numeric suffix inserted before the extension (`service.wsdl`,
+ * `service-2.wsdl`, ...).
+ *
+ * Generic in the document type so a caller keeps its own: the naming rules
+ * only ever read `location` and `kind`, which is why an OpenAPI definition
+ * cache uses the same function as a WSDL one.
+ */
+export declare function assignFileNames<T extends NameableDocument>(documents: readonly T[], options?: AssignFileNamesOptions): readonly NamedDocument<T>[];

package/dist/wsdl/cache-naming.js

@@ -0,0 +1,90 @@
+/**
+ * Derives on-disk file names for the documents in a {@link DefinitionBundle}
+ * when writing a definition cache or an export folder. Shared by
+ * `wsdl/cache.ts` and `wsdl/export-definition.ts` so both lay documents out
+ * identically (a location always maps to the same relative file name).
+ *
+ * File names are sanitised with the same segment-validation rules Task 17
+ * uses for project slugs ({@link sanitiseFileName}/{@link isReservedFileName}
+ * from `project/paths.ts`), so a hyphen or space is preserved and a Windows
+ * reserved device name (`CON`, `NUL`, `COM1`, ...) is renamed safely instead
+ * of being written as-is.
+ */
+import { isReservedFileName, sanitiseFileName } from '../project/paths.js';
+/** Extracts the last path segment of a location's pathname, ignoring any query/fragment. */
+function lastPathSegment(location) {
+    try {
+        const url = new URL(location);
+        const segments = url.pathname.split('/').filter((s) => s.length > 0);
+        return segments.at(-1);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Extension to use for a document with no usable name of its own, keyed by `kind`. */
+function fallbackName(isRoot, kind, index, rootFile) {
+    if (isRoot) {
+        return rootFile;
+    }
+    return `document-${index}.${kind}`;
+}
+/**
+ * Renames a reserved Windows device name (`CON`, `NUL`, `COM1`, ...) safely
+ * by suffixing its stem with `_`, keeping the extension intact (`con.xsd` →
+ * `con_.xsd`). Names that are not reserved pass through unchanged.
+ */
+function guardReservedName(name) {
+    if (!isReservedFileName(name)) {
+        return name;
+    }
+    const dot = name.lastIndexOf('.');
+    const stem = dot > 0 ? name.slice(0, dot) : name;
+    const ext = dot > 0 ? name.slice(dot) : '';
+    return `${stem}_${ext}`;
+}
+/**
+ * Chooses a base file name for one document: the last segment of its
+ * location when it looks like a real file name (has an extension), or a
+ * `service.wsdl` / `document-N.<kind>` fallback for extensionless or
+ * unparsable locations (e.g. a `?wsdl` query-string root). Either way, the
+ * result is sanitised and guarded against Windows reserved device names.
+ */
+function baseFileName(doc, isRoot, index, rootFile) {
+    const segment = lastPathSegment(doc.location);
+    if (segment !== undefined && /\.[A-Za-z0-9]+$/.test(segment)) {
+        return guardReservedName(sanitiseFileName(segment));
+    }
+    return guardReservedName(fallbackName(isRoot, doc.kind, index, rootFile));
+}
+/**
+ * Assigns a unique, sanitised file name to every document in `documents`
+ * (root first, in the order given), de-duplicating collisions with a
+ * numeric suffix inserted before the extension (`service.wsdl`,
+ * `service-2.wsdl`, ...).
+ *
+ * Generic in the document type so a caller keeps its own: the naming rules
+ * only ever read `location` and `kind`, which is why an OpenAPI definition
+ * cache uses the same function as a WSDL one.
+ */
+export function assignFileNames(documents, options) {
+    const rootFile = options?.rootFile ?? 'service.wsdl';
+    const used = new Set();
+    const named = [];
+    documents.forEach((document, index) => {
+        const isRoot = index === 0;
+        const base = baseFileName(document, isRoot, index, rootFile);
+        const dot = base.lastIndexOf('.');
+        const stem = dot > 0 ? base.slice(0, dot) : base;
+        const ext = dot > 0 ? base.slice(dot) : '';
+        let candidate = base;
+        let n = 2;
+        while (used.has(candidate.toLowerCase())) {
+            candidate = `${stem}-${n}${ext}`;
+            n += 1;
+        }
+        used.add(candidate.toLowerCase());
+        named.push({ document, file: candidate });
+    });
+    return named;
+}

package/dist/wsdl/cache.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Persists a resolved {@link DefinitionBundle} byte-exact inside a project
+ * (`interfaces/<slug>/definition/`) so the interface can be opened offline,
+ * and reconstructs a bundle from that cache later. Unlike
+ * `wsdl/export-definition.ts`, nothing here is ever re-serialised: every
+ * document is written and read back as the exact bytes that were fetched,
+ * verified by SHA-256 against the manifest.
+ */
+import type { DefinitionCacheManifest } from '../project/schema.js';
+import type { FsLike } from '../project/fs.js';
+import type { DefinitionBundle, FetchDocument } from './resolver.js';
+/** Options accepted by {@link writeDefinitionCache} and {@link readDefinitionCache}. */
+export interface DefinitionCacheOptions {
+    /** Overrides the file system, e.g. for tests. Defaults to `nodeFs`. */
+    readonly fs?: FsLike;
+}
+/** Options accepted by {@link writeDefinitionCache} beyond {@link DefinitionCacheOptions}. */
+export interface WriteDefinitionCacheOptions extends DefinitionCacheOptions {
+    /** Overrides the clock used for `fetchedAt`. Defaults to `() => new Date().toISOString()`. */
+    readonly now?: () => string;
+}
+/**
+ * Writes every document of `bundle` byte-exact into `dir` (created if
+ * needed), alongside a `manifest.yaml` describing them, and returns that
+ * manifest. This entirely REPLACES the directory's previous contents: any
+ * file left over from a prior cache that is not part of the new manifest is
+ * deleted, so the folder never accumulates stale documents across re-caches.
+ *
+ * @param bundle the resolved definition to cache
+ * @param dir absolute path of the interface's `definition/` directory
+ */
+export declare function writeDefinitionCache(bundle: DefinitionBundle, dir: string, options?: WriteDefinitionCacheOptions): Promise<DefinitionCacheManifest>;
+/**
+ * Reads a manifest previously written by {@link writeDefinitionCache} back
+ * into a {@link DefinitionBundle}, re-parsing every document and verifying
+ * its bytes against the manifest's recorded SHA-256.
+ *
+ * @throws {ProjectError} `definition-cache-missing` if `dir` has no `manifest.yaml`
+ * @throws {ProjectError} `definition-cache-corrupt` if a document's bytes no longer match its recorded hash
+ */
+export declare function readDefinitionCache(dir: string, options?: DefinitionCacheOptions): Promise<DefinitionBundle>;
+/**
+ * Wraps `fallback` with a {@link FetchDocument} that serves documents from a
+ * previously-written cache by canonical location (or the location that was
+ * originally requested to fetch it), and only falls through to `fallback`
+ * for a location the cache does not contain.
+ */
+export declare function createCachedFetchDocument(manifest: DefinitionCacheManifest, dir: string, fallback: FetchDocument, options?: DefinitionCacheOptions): FetchDocument;

package/dist/wsdl/cache.js

@@ -0,0 +1,141 @@
+/**
+ * Persists a resolved {@link DefinitionBundle} byte-exact inside a project
+ * (`interfaces/<slug>/definition/`) so the interface can be opened offline,
+ * and reconstructs a bundle from that cache later. Unlike
+ * `wsdl/export-definition.ts`, nothing here is ever re-serialised: every
+ * document is written and read back as the exact bytes that were fetched,
+ * verified by SHA-256 against the manifest.
+ */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { ProjectError } from '../errors.js';
+import { definitionCacheManifestSchema, parseFile } from '../project/schema.js';
+import { nodeFs, readFileIfExists, readdirIfExists, writeFileAtomic } from '../project/fs.js';
+import { parseYaml, stringifyYaml } from '../project/yaml.js';
+import { parseXml } from '../xml/parse.js';
+import { assignFileNames } from './cache-naming.js';
+const MANIFEST_FILE = 'manifest.yaml';
+/** Hex-encoded SHA-256 digest of `bytes`, used to verify cached documents haven't been tampered with or corrupted. */
+function sha256Hex(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/**
+ * Writes every document of `bundle` byte-exact into `dir` (created if
+ * needed), alongside a `manifest.yaml` describing them, and returns that
+ * manifest. This entirely REPLACES the directory's previous contents: any
+ * file left over from a prior cache that is not part of the new manifest is
+ * deleted, so the folder never accumulates stale documents across re-caches.
+ *
+ * @param bundle the resolved definition to cache
+ * @param dir absolute path of the interface's `definition/` directory
+ */
+export async function writeDefinitionCache(bundle, dir, options) {
+    const fs = options?.fs ?? nodeFs;
+    const now = options?.now ?? (() => new Date().toISOString());
+    const existing = await readdirIfExists(fs, dir);
+    const named = assignFileNames(bundle.documents);
+    const documents = named.map(({ document, file }) => ({
+        file,
+        location: document.location,
+        ...(document.requestedLocation !== document.location ? { requestedLocation: document.requestedLocation } : {}),
+        kind: document.kind,
+        sha256: sha256Hex(document.bytes),
+        bytes: document.bytes.length,
+        ...(document.importedBy !== undefined ? { importedBy: document.importedBy } : {}),
+        ...(document.namespace !== undefined ? { namespace: document.namespace } : {}),
+        ...(document.chameleonFor !== undefined ? { chameleonFor: document.chameleonFor } : {}),
+    }));
+    const manifest = {
+        formatVersion: 1,
+        rootLocation: bundle.root.location,
+        fetchedAt: now(),
+        documents,
+    };
+    for (const { document, file } of named) {
+        await writeFileAtomic(fs, join(dir, file), Buffer.from(document.bytes));
+    }
+    await writeFileAtomic(fs, join(dir, MANIFEST_FILE), stringifyYaml(manifest));
+    const keep = new Set([MANIFEST_FILE, ...named.map((n) => n.file)]);
+    for (const entry of existing) {
+        if (entry.isFile && !keep.has(entry.name)) {
+            await fs.rm(join(dir, entry.name), { force: true });
+        }
+    }
+    return manifest;
+}
+/**
+ * Reads a manifest previously written by {@link writeDefinitionCache} back
+ * into a {@link DefinitionBundle}, re-parsing every document and verifying
+ * its bytes against the manifest's recorded SHA-256.
+ *
+ * @throws {ProjectError} `definition-cache-missing` if `dir` has no `manifest.yaml`
+ * @throws {ProjectError} `definition-cache-corrupt` if a document's bytes no longer match its recorded hash
+ */
+export async function readDefinitionCache(dir, options) {
+    const fs = options?.fs ?? nodeFs;
+    const manifestPath = join(dir, MANIFEST_FILE);
+    const manifestRaw = await readFileIfExists(fs, manifestPath);
+    if (manifestRaw === undefined) {
+        throw new ProjectError('definition-cache-missing', `No definition cache manifest at ${manifestPath}`, {
+            details: { dir },
+        });
+    }
+    const manifest = parseFile(definitionCacheManifestSchema, parseYaml(manifestRaw.toString('utf-8'), manifestPath), manifestPath);
+    const documents = [];
+    for (const entry of manifest.documents) {
+        const filePath = join(dir, entry.file);
+        const buffer = await fs.readFile(filePath);
+        const bytes = new Uint8Array(buffer);
+        const actualSha256 = sha256Hex(bytes);
+        if (actualSha256 !== entry.sha256) {
+            throw new ProjectError('definition-cache-corrupt', `Definition cache document "${entry.file}" is corrupt`, {
+                details: { file: entry.file, expected: entry.sha256, actual: actualSha256 },
+            });
+        }
+        const text = new TextDecoder('utf-8').decode(bytes);
+        const document = parseXml(text, { location: entry.location });
+        documents.push({
+            location: entry.location,
+            requestedLocation: entry.requestedLocation ?? entry.location,
+            bytes,
+            text,
+            kind: entry.kind,
+            ...(entry.importedBy !== undefined ? { importedBy: entry.importedBy } : {}),
+            ...(entry.namespace !== undefined ? { namespace: entry.namespace } : {}),
+            ...(entry.chameleonFor !== undefined ? { chameleonFor: entry.chameleonFor } : {}),
+            document,
+        });
+    }
+    const root = documents.find((d) => d.location === manifest.rootLocation) ?? documents[0];
+    if (root === undefined) {
+        throw new ProjectError('definition-cache-corrupt', `Definition cache manifest at ${manifestPath} lists no documents`, {
+            details: { dir },
+        });
+    }
+    return { root, documents, problems: [] };
+}
+/**
+ * Wraps `fallback` with a {@link FetchDocument} that serves documents from a
+ * previously-written cache by canonical location (or the location that was
+ * originally requested to fetch it), and only falls through to `fallback`
+ * for a location the cache does not contain.
+ */
+export function createCachedFetchDocument(manifest, dir, fallback, options) {
+    const fs = options?.fs ?? nodeFs;
+    const byLocation = new Map();
+    for (const entry of manifest.documents) {
+        byLocation.set(entry.location, entry);
+        if (entry.requestedLocation !== undefined) {
+            byLocation.set(entry.requestedLocation, entry);
+        }
+    }
+    return async (location, signal) => {
+        const entry = byLocation.get(location);
+        if (entry === undefined) {
+            return fallback(location, signal);
+        }
+        const buffer = await fs.readFile(join(dir, entry.file));
+        const bytes = new Uint8Array(buffer);
+        return { location: entry.location, bytes, text: new TextDecoder('utf-8').decode(bytes) };
+    };
+}

package/dist/wsdl/docs-generator.d.ts

@@ -0,0 +1,47 @@
+/**
+ * "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 type { ImportResult } from '../types.js';
+/** Options accepted by {@link generateDocs}. */
+export interface GenerateDocsOptions {
+    readonly format: 'html' | 'markdown';
+    /** Document title; defaults to the first service's name, then the definition's file name. */
+    readonly title?: string;
+}
+/**
+ * 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 declare function sourceSnippet(text: string, line: number, maxLines?: number): string;
+/**
+ * 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 declare function generateDocs(result: ImportResult, options: GenerateDocsOptions): string;