@techspokes/typescript-wsdl-client 1.1.8 → 1.2.0

package/dist/multiServicePipeline.js

@@ -0,0 +1,287 @@
+import fs from "node:fs/promises";
+import { existsSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { types } from "node:util";
+import { fileURLToPath } from "node:url";
+import { runGenerationPipeline } from "./pipeline.js";
+import { composeOpenApiDocuments } from "./openapi/composeOpenAPI.js";
+import { buildComposedGatewaySource } from "./gateway/generateComposedGateway.js";
+import { deriveClientName } from "./util/tools.js";
+import { slugName } from "./gateway/helpers.js";
+const data = (value, label) => {
+    if (!value || typeof value !== "object" || Array.isArray(value) || types.isProxy(value) || ![null, Object.prototype].includes(Object.getPrototypeOf(value)))
+        throw new TypeError(`${label} must be a data object`);
+    for (const property of Object.values(Object.getOwnPropertyDescriptors(value)))
+        if (!Object.hasOwn(property, "value"))
+            throw new TypeError(`${label} must not contain accessors`);
+    return value;
+};
+const text = (value, label) => {
+    if (typeof value !== "string" || !value.trim())
+        throw new TypeError(`${label} must be a nonempty string`);
+    return value;
+};
+const known = (value, allowed, label) => {
+    for (const key of Reflect.ownKeys(value))
+        if (typeof key !== "string" || !allowed.includes(key))
+            throw new TypeError(`Unknown ${label} option: ${String(key)}`);
+};
+const localPath = (value, label) => {
+    // @why Lexically different output paths can share a symlink/junction target; ownership checks must compare their filesystem destinations.
+    let ancestor = path.resolve(text(value, label));
+    const missing = [];
+    while (!existsSync(ancestor)) {
+        missing.unshift(path.basename(ancestor));
+        const parent = path.dirname(ancestor);
+        if (parent === ancestor)
+            throw new TypeError(`Cannot resolve output filesystem root for ${label}`);
+        ancestor = parent;
+    }
+    return path.join(realpathSync(ancestor), ...missing);
+};
+const canonical = (value) => process.platform === "win32" ? value.toLowerCase() : value;
+const within = (directory, file) => {
+    const relative = path.relative(canonical(directory), canonical(file));
+    return relative === "" || relative !== ".." && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative);
+};
+const prefix = (value) => {
+    const result = text(value, "generation.openapi.basePath");
+    if (!/^\/(?:[a-zA-Z0-9._~-]+\/)*[a-zA-Z0-9._~-]+$/.test(result) || result.split("/").some(segment => segment === "." || segment === ".."))
+        throw new TypeError("Each service needs an explicit static OpenAPI basePath without trailing slash");
+    return result;
+};
+function prepare(options) {
+    const input = data(options, "composition");
+    if (Object.keys(input).some(key => !["services", "openapi", "gateway"].includes(key)))
+        throw new TypeError("Unknown multi-service composition option");
+    if (!Array.isArray(options.services) || options.services.length === 0)
+        throw new TypeError("At least one independent service is required");
+    known(data(options.openapi, "aggregate OpenAPI"), ["outFile", "title", "version", "description", "servers"], "aggregate OpenAPI");
+    known(data(options.gateway, "aggregate gateway"), ["outDir", "imports", "openapiPath"], "aggregate gateway");
+    for (const name of ["title", "version", "description"])
+        if (options.openapi[name] !== undefined && typeof options.openapi[name] !== "string")
+            throw new TypeError(`openapi.${name} must be a string`);
+    if (options.openapi.servers !== undefined && (!Array.isArray(options.openapi.servers) || options.openapi.servers.some(server => typeof server !== "string" || !server)))
+        throw new TypeError("openapi.servers must contain server URL strings");
+    const outFile = localPath(options.openapi.outFile, "openapi.outFile");
+    if (path.extname(outFile).toLowerCase() !== ".json")
+        throw new TypeError("The aggregate OpenAPI output must be a JSON file");
+    const gatewayDir = localPath(options.gateway.outDir, "gateway.outDir");
+    if (options.gateway.imports !== undefined && !["js", "ts", "bare"].includes(options.gateway.imports))
+        throw new TypeError("Invalid aggregate import extension mode");
+    const openapiPath = options.gateway.openapiPath === false ? false : options.gateway.openapiPath ?? "/openapi.json";
+    if (openapiPath !== false && (!/^\/[^?#\\]*$/.test(openapiPath) || openapiPath.includes("//")))
+        throw new TypeError("Invalid OpenAPI discovery path");
+    const keys = new Set(), slugs = new Set(), decorators = new Set(), prefixes = new Set();
+    const outputs = [
+        { owner: "aggregate", role: "gateway", file: gatewayDir, directory: true },
+        { owner: "aggregate", role: "openapi", file: outFile, directory: false },
+    ];
+    const entries = options.services.map(entry => {
+        data(entry, "service entry");
+        if (Object.keys(entry).some(key => !["key", "generation"].includes(key)))
+            throw new TypeError("Unknown service entry option");
+        const key = text(entry.key, "service key");
+        if (!/^[a-z][a-z0-9-]*$/.test(key) || keys.has(key))
+            throw new TypeError("Unique lowercase service keys required");
+        keys.add(key);
+        const generation = data(entry.generation, `generation for ${key}`);
+        known(generation, ["model", "checkedComponents", "wsdl", "catalogOut", "clientOutDir", "compiler", "openapi", "gateway", "app", "test", "streamConfigFile", "streamConfig"], "service generation");
+        if (generation.model !== undefined && generation.model !== "legacy" || generation.checkedComponents !== undefined || generation.app !== undefined || generation.test !== undefined)
+            throw new TypeError("Multi-service generation currently composes legacy service routers; app/test/checked settings are not aggregate settings");
+        text(generation.wsdl, `${key}.wsdl`);
+        if (!generation.openapi || !generation.gateway)
+            throw new TypeError(`Service ${key} requires OpenAPI and gateway generation`);
+        data(generation.openapi, "service OpenAPI");
+        data(generation.gateway, "service gateway");
+        const basePath = prefix(generation.openapi.basePath);
+        if (prefixes.has(basePath))
+            throw new TypeError(`Duplicate service basePath ${basePath}`);
+        prefixes.add(basePath);
+        const clientDir = localPath(generation.clientOutDir, `${key}.clientOutDir`);
+        const catalogOut = localPath(generation.catalogOut, `${key}.catalogOut`);
+        const serviceOpenapi = localPath(generation.openapi.outFile, `${key}.openapi.outFile`);
+        const serviceGateway = localPath(generation.gateway.outDir, `${key}.gateway.outDir`);
+        if (!slugName(text(generation.gateway.versionSlug, `${key}.gateway.versionSlug`)))
+            throw new TypeError("A normalized gateway version slug is required");
+        const slug = slugName(text(generation.gateway.serviceSlug, `${key}.gateway.serviceSlug`));
+        if (!slug || slugs.has(slug))
+            throw new TypeError("Gateway service slugs must remain unique after normalization");
+        slugs.add(slug);
+        const decorator = generation.gateway.clientDecoratorName ?? `wsdl_${key.replaceAll("-", "_")}Client`;
+        if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(decorator) || decorators.has(decorator))
+            throw new TypeError("Unique valid client decorators required");
+        decorators.add(decorator);
+        if (generation.gateway.emitPlugin === false || generation.gateway.stubHandlers === true || generation.gateway.emitRuntime === false)
+            throw new TypeError("Composition requires complete service plugins and runtime handlers");
+        for (const target of [clientDir, serviceGateway])
+            if (path.parse(target).root !== path.parse(gatewayDir).root)
+                throw new TypeError("Composed generated modules must share a filesystem root");
+        outputs.push({ owner: key, role: "client", file: clientDir, directory: true }, { owner: key, role: "gateway", file: serviceGateway, directory: true }, { owner: key, role: "catalog", file: catalogOut, directory: false }, { owner: key, role: "openapi", file: serviceOpenapi, directory: false });
+        return { key, generation: { ...generation, catalogOut, clientOutDir: clientDir,
+                openapi: { ...generation.openapi, basePath, outFile: serviceOpenapi },
+                gateway: { ...generation.gateway, outDir: serviceGateway, clientDecoratorName: decorator } } };
+    });
+    for (let a = 0; a < outputs.length; a++)
+        for (let b = a + 1; b < outputs.length; b++) {
+            const left = outputs[a], right = outputs[b];
+            if (canonical(left.file) === canonical(right.file))
+                throw new TypeError(`Conflicting output paths: ${left.role} and ${right.role}`);
+            const overlap = left.directory && within(left.file, right.file) || right.directory && within(right.file, left.file);
+            if (overlap && (left.owner !== right.owner || left.directory && right.directory))
+                throw new TypeError("Service output ownership must not overlap");
+            const file = left.directory ? right : left, directory = left.directory ? left : right;
+            if (overlap && !file.directory && directory.directory) {
+                const relative = path.relative(directory.file, file.file).replaceAll("\\", "/");
+                if (relative.endsWith(".ts") || /^(?:routes|schemas)(?:\/|$)/.test(relative))
+                    throw new TypeError("Output file conflicts with generated service modules");
+            }
+        }
+    for (const entry of entries) {
+        const source = entry.generation.wsdl;
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(source) && !source.startsWith("file:"))
+            continue;
+        const sourceFile = localPath(source.startsWith("file:") ? fileURLToPath(source) : source, "source WSDL");
+        if (outputs.some(output => output.directory ? within(output.file, sourceFile) : canonical(output.file) === canonical(sourceFile)))
+            throw new TypeError("Source WSDLs must remain outside generated output ownership");
+    }
+    return { entries, outFile, gatewayDir, openapiPath };
+}
+/** Publish the matched spec/plugin after all service generation and composition checks succeed.
+ * @constraints Uses only individually owned staging files; never removes a consumer output tree.
+ */
+async function publish(files) {
+    const staged = [];
+    try {
+        for (const { file, content } of files) {
+            await fs.mkdir(path.dirname(file), { recursive: true });
+            let previous;
+            try {
+                previous = await fs.readFile(file);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            const temporary = file + ".stage-" + randomUUID();
+            staged.push({ file, temporary, previous, committed: false });
+            await fs.writeFile(temporary, content, { flag: "wx" });
+        }
+        for (const entry of staged) {
+            await fs.rename(entry.temporary, entry.file);
+            entry.committed = true;
+        }
+    }
+    catch (error) {
+        for (const entry of [...staged].reverse())
+            if (entry.committed) {
+                if (entry.previous === undefined)
+                    await fs.unlink(entry.file);
+                else
+                    await fs.writeFile(entry.file, entry.previous);
+            }
+        throw error;
+    }
+    finally {
+        for (const entry of staged)
+            await fs.unlink(entry.temporary).catch(error => { if (error.code !== "ENOENT")
+                throw error; });
+    }
+}
+/** Generate independent WSDL clients behind one typed gateway and discoverable API definition.
+ * @param options Explicit per-service pipelines and disjoint aggregate output paths.
+ * @returns Matched aggregate artifacts and each service's unmerged compiled catalog.
+ * @throws For configuration/output conflicts, source generation failures or invalid API composition.
+ * @sideEffects Generates each selected legacy service in caller order, then publishes the aggregate spec/plugin pair.
+ * @constraints Failure preserves previous aggregate spec/plugin files; earlier generated service dependencies are not rolled back.
+ */
+export async function runMultiServicePipeline(options) {
+    const prepared = prepare(options);
+    const services = Object.create(null);
+    const documents = [];
+    const routers = [];
+    for (const { key, generation } of prepared.entries) {
+        const result = await runGenerationPipeline(generation);
+        const compiled = result.compiled;
+        const fileSlugs = new Set();
+        const expectedOperations = new Set(compiled.operations.map(operation => operation.name));
+        if (expectedOperations.size !== compiled.operations.length)
+            throw new TypeError(`Service ${key} has overloaded operation names that cannot own unique gateway routes`);
+        for (const operation of compiled.operations) {
+            const slug = slugName(operation.name);
+            if (!slug || fileSlugs.has(slug))
+                throw new TypeError(`Service ${key} has colliding generated operation filenames`);
+            fileSlugs.add(slug);
+        }
+        const described = [];
+        const document = data(result.openapiDoc, "generated OpenAPI");
+        for (const item of Object.values(data(document.paths, "generated paths"))) {
+            const pathItem = data(item, "generated path item");
+            for (const method of ["get", "put", "post", "delete", "options", "head", "patch", "trace"]) {
+                if (pathItem[method] !== undefined)
+                    described.push(text(data(pathItem[method], "generated operation").operationId, "operationId"));
+            }
+        }
+        if (described.length !== expectedOperations.size || described.some(name => !expectedOperations.has(name)))
+            throw new TypeError(`Service ${key} loses operations through generated route collisions`);
+        const className = deriveClientName(compiled);
+        if (generation.gateway.clientClassName && generation.gateway.clientClassName !== className)
+            throw new TypeError("Configure compiler.clientName to keep client and gateway classes matched");
+        services[key] = { compiled, clientDir: generation.clientOutDir, gatewayDir: generation.gateway.outDir };
+        documents.push({ key, document: result.openapiDoc });
+        routers.push({ key, clientDir: generation.clientOutDir, gatewayDir: generation.gateway.outDir, clientClassName: className });
+    }
+    const openapiDoc = composeOpenApiDocuments(documents, options.openapi);
+    const { default: SwaggerParser } = await import("@apidevtools/swagger-parser");
+    const validator = new SwaggerParser();
+    await validator.validate(structuredClone(openapiDoc), { resolve: { external: false } });
+    if (prepared.openapiPath !== false && Object.hasOwn(openapiDoc.paths, prepared.openapiPath))
+        throw new TypeError("OpenAPI discovery path conflicts with a service route");
+    const pluginFile = path.join(prepared.gatewayDir, "plugin.ts");
+    const source = buildComposedGatewaySource(routers, { outDir: prepared.gatewayDir, openapiFile: prepared.outFile,
+        imports: options.gateway.imports, openapiPath: prepared.openapiPath });
+    await publish([{ file: prepared.outFile, content: JSON.stringify(openapiDoc, null, 2) + "\n" }, { file: pluginFile, content: source }]);
+    return { openapiDoc, services, pluginFile, openapiFile: prepared.outFile };
+}
+/** Load a composition config with paths resolved against its own directory.
+ * @throws For invalid JSON or missing required output/source paths when the pipeline validates it.
+ * @constraints Runtime client options and credentials are deliberately not generation configuration.
+ */
+export async function loadMultiServiceConfig(file) {
+    const absolute = path.resolve(file), base = path.dirname(absolute);
+    const options = JSON.parse(await fs.readFile(absolute, "utf8"));
+    data(options, "composition");
+    data(options.openapi, "aggregate OpenAPI");
+    data(options.gateway, "aggregate gateway");
+    if (!Array.isArray(options.services))
+        throw new TypeError("services must be an array");
+    const resolve = (value) => value === undefined ? undefined : path.resolve(base, text(value, "config path"));
+    const source = (value) => /^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : resolve(value);
+    options.openapi.outFile = resolve(options.openapi.outFile);
+    options.gateway.outDir = resolve(options.gateway.outDir);
+    for (const entry of options.services) {
+        data(entry, "service");
+        const generation = data(entry.generation, "generation");
+        generation.wsdl = source(text(generation.wsdl, "wsdl"));
+        generation.catalogOut = resolve(generation.catalogOut);
+        generation.clientOutDir = resolve(generation.clientOutDir);
+        generation.streamConfigFile = resolve(generation.streamConfigFile);
+        if (generation.openapi) {
+            generation.openapi.outFile = resolve(generation.openapi.outFile);
+            generation.openapi.tagsFile = resolve(generation.openapi.tagsFile);
+            generation.openapi.opsFile = resolve(generation.openapi.opsFile);
+            generation.openapi.securityConfigFile = resolve(generation.openapi.securityConfigFile);
+        }
+        if (generation.gateway)
+            generation.gateway.outDir = resolve(generation.gateway.outDir);
+        if (generation.streamConfig)
+            for (const shape of Object.values(generation.streamConfig.shapeCatalogs)) {
+                if (shape.catalogFile)
+                    shape.catalogFile = resolve(shape.catalogFile);
+                if (shape.wsdlSource)
+                    shape.wsdlSource = source(shape.wsdlSource);
+            }
+    }
+    return options;
+}

package/dist/openapi/composeOpenAPI.d.ts

@@ -0,0 +1,29 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export interface ComposedOpenApiDocument extends JsonObject {
+    openapi: string;
+    info: JsonObject;
+    paths: Record<string, JsonObject>;
+    components: Record<string, Record<string, JsonValue>>;
+}
+export interface OpenApiCompositionOptions {
+    title?: string;
+    version?: string;
+    description?: string;
+    servers?: readonly string[];
+}
+export interface OpenApiCompositionEntry {
+    key: string;
+    document: unknown;
+}
+/** Compose service-scoped OpenAPI contracts without changing SOAP client ownership.
+ * @param entries Self-contained OpenAPI 3.1 documents whose HTTP paths already contain their service prefixes.
+ * @param options Combined API metadata and default gateway servers; custom source servers remain operation-local.
+ * @returns A fresh deterministic document with qualified component names and operation identifiers.
+ * @throws For invalid JSON, duplicate service keys/paths/operation IDs, unresolved local references or unsupported relative references/schema resources.
+ * @constraints Only reference-bearing OpenAPI/JSON Schema positions are rewritten; examples, literal values and extensions remain data.
+ * @see https://spec.openapis.org/oas/v3.1.0.html Reference, Link, Security Requirement and Schema objects govern distinct reference positions.
+ */
+export declare function composeOpenApiDocuments(entries: readonly OpenApiCompositionEntry[], options?: OpenApiCompositionOptions): ComposedOpenApiDocument;

package/dist/openapi/composeOpenAPI.js

@@ -0,0 +1,322 @@
+import { types } from "node:util";
+const methods = new Set(["get", "put", "post", "delete", "options", "head", "patch", "trace"]);
+const categories = {
+    schemas: "schema", responses: "response", parameters: "parameter", examples: "example",
+    requestBodies: "requestBody", headers: "header", securitySchemes: "securityScheme", links: "link",
+    callbacks: "callback", pathItems: "pathItem",
+};
+const dict = () => Object.create(null);
+const record = (value, context) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new TypeError(`${context} must be an object`);
+    return value;
+};
+const items = (value, context) => {
+    if (!Array.isArray(value))
+        throw new TypeError(`${context} must be an array`);
+    return value;
+};
+const pointerToken = (value) => value.replaceAll("~", "~0").replaceAll("/", "~1");
+/** Copy JSON data without invoking accessors or sharing mutable source objects.
+ * @throws For non-JSON values, accessors, proxies, sparse arrays or cycles.
+ */
+function copyJson(value, active = new Set()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (!value || typeof value !== "object" || types.isProxy(value) || active.has(value))
+        throw new TypeError("Actual acyclic JSON data required");
+    if (!Array.isArray(value) && ![null, Object.prototype].includes(Object.getPrototypeOf(value)))
+        throw new TypeError("Plain JSON objects required");
+    active.add(value);
+    try {
+        if (Array.isArray(value)) {
+            if (Reflect.ownKeys(value).length !== value.length + 1)
+                throw new TypeError("Dense JSON arrays required");
+            return Array.from({ length: value.length }, (_, index) => {
+                const property = Object.getOwnPropertyDescriptor(value, String(index));
+                if (!property || !Object.hasOwn(property, "value"))
+                    throw new TypeError("JSON array data properties required");
+                return copyJson(property.value, active);
+            });
+        }
+        const result = dict();
+        for (const key of Reflect.ownKeys(value)) {
+            const property = Object.getOwnPropertyDescriptor(value, key);
+            if (typeof key !== "string" || !property.enumerable || !Object.hasOwn(property, "value"))
+                throw new TypeError("JSON object data properties required");
+            result[key] = copyJson(property.value, active);
+        }
+        return result;
+    }
+    finally {
+        active.delete(value);
+    }
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])]));
+}
+/** Compose service-scoped OpenAPI contracts without changing SOAP client ownership.
+ * @param entries Self-contained OpenAPI 3.1 documents whose HTTP paths already contain their service prefixes.
+ * @param options Combined API metadata and default gateway servers; custom source servers remain operation-local.
+ * @returns A fresh deterministic document with qualified component names and operation identifiers.
+ * @throws For invalid JSON, duplicate service keys/paths/operation IDs, unresolved local references or unsupported relative references/schema resources.
+ * @constraints Only reference-bearing OpenAPI/JSON Schema positions are rewritten; examples, literal values and extensions remain data.
+ * @see https://spec.openapis.org/oas/v3.1.0.html Reference, Link, Security Requirement and Schema objects govern distinct reference positions.
+ */
+export function composeOpenApiDocuments(entries, options = {}) {
+    if (!Array.isArray(entries) || entries.length === 0)
+        throw new TypeError("At least one service document is required");
+    const input = items(copyJson(entries), "services");
+    const keys = new Set();
+    const paths = dict();
+    const components = dict();
+    const webhooks = dict();
+    const tags = dict();
+    const services = dict();
+    const rootServers = options.servers?.map(url => ({ url })) ?? [{ url: "/" }];
+    let dialect;
+    for (const entry of input.map(value => record(value, "service")).sort((left, right) => String(left.key).localeCompare(String(right.key)))) {
+        const key = entry.key;
+        if (typeof key !== "string" || !/^[a-z][a-z0-9-]*$/.test(key) || keys.has(key))
+            throw new TypeError("Unique lowercase service keys required");
+        keys.add(key);
+        const source = record(entry.document, `service ${key}`);
+        if (typeof source.openapi !== "string" || !/^3\.1\.\d+$/.test(source.openapi))
+            throw new TypeError("OpenAPI 3.1 documents required");
+        record(source.info, "OpenAPI info");
+        const sourcePaths = record(source.paths, "OpenAPI paths");
+        const sourceComponents = source.components === undefined ? dict() : record(source.components, "OpenAPI components");
+        const sourceDialect = source.jsonSchemaDialect ?? "https://spec.openapis.org/oas/3.1/dialect/base";
+        if (typeof sourceDialect !== "string" || dialect !== undefined && dialect !== sourceDialect)
+            throw new TypeError("Source schema dialects must agree");
+        dialect = sourceDialect;
+        const qualified = (name) => `${key}__${name}`;
+        const operationIds = new Map();
+        const operationNodes = new Set();
+        const sourceRootServers = source.servers === undefined ? undefined : items(source.servers, "servers");
+        const defaultSourceServer = JSON.stringify(sourceRootServers) === '[{"url":"/"}]';
+        const effectiveServers = options.servers && defaultSourceServer ? undefined : sourceRootServers;
+        const defaultSecurity = source.security;
+        function resolve(tokens, reference) {
+            let target = source;
+            for (const token of tokens) {
+                if (!target || typeof target !== "object" || !Object.hasOwn(target, token))
+                    throw new TypeError(`Unresolved local reference ${reference} in ${key}`);
+                target = target[token];
+            }
+            return target;
+        }
+        function reference(value, operation = false) {
+            if (typeof value !== "string" || value.length === 0)
+                throw new TypeError("Reference must be a nonempty string");
+            if (!value.startsWith("#")) {
+                try {
+                    new URL(value);
+                }
+                catch {
+                    throw new TypeError(`Relative external references need resolution before composition: ${value}`);
+                }
+                return value;
+            }
+            let fragment;
+            try {
+                fragment = decodeURIComponent(value.slice(1));
+            }
+            catch {
+                throw new TypeError(`Invalid reference ${value}`);
+            }
+            if (!fragment.startsWith("/") || /~(?![01])/u.test(fragment))
+                throw new TypeError(`Unsupported local reference ${value}`);
+            const tokens = fragment.slice(1).split("/").map(token => token.replaceAll("~1", "/").replaceAll("~0", "~"));
+            const target = resolve(tokens, value);
+            if (operation && (!target || typeof target !== "object" || Array.isArray(target) || !operationNodes.has(target)))
+                throw new TypeError(`operationRef does not resolve to an operation: ${value}`);
+            if (tokens[0] === "components" && tokens.length >= 3)
+                tokens[2] = qualified(tokens[2]);
+            else if (tokens[0] === "webhooks" && tokens.length >= 2)
+                tokens[1] = qualified(tokens[1]);
+            else if (tokens[0] !== "paths")
+                throw new TypeError(`Reference target cannot be retained during composition: ${value}`);
+            return "#/" + tokens.map(token => encodeURIComponent(pointerToken(token))).join("/");
+        }
+        function security(value) {
+            return items(value, "security").map(requirement => Object.fromEntries(Object.entries(record(requirement, "security requirement")).map(([name, scopes]) => {
+                if (!Object.hasOwn(record(sourceComponents.securitySchemes, "securitySchemes"), name))
+                    throw new TypeError(`Missing security scheme ${name}`);
+                if (!items(scopes, "security scopes").every(scope => typeof scope === "string"))
+                    throw new TypeError("Security scopes must be strings");
+                return [qualified(name), scopes];
+            })));
+        }
+        function map(value, kind, scan, extensions = false) {
+            return Object.fromEntries(Object.entries(record(value, `${kind} map`)).map(([name, child]) => [name,
+                extensions && name.startsWith("x-") ? child : walk(child, kind, scan)]));
+        }
+        function walk(value, kind, scan, inheritedServers = effectiveServers) {
+            if (kind === "data")
+                return value;
+            if (kind === "schema" && typeof value === "boolean")
+                return value;
+            const node = record(value, kind);
+            const out = { ...node };
+            if (kind === "operation" && scan) {
+                operationNodes.add(node);
+                if (node.operationId !== undefined) {
+                    if (typeof node.operationId !== "string" || !node.operationId || operationIds.has(node.operationId))
+                        throw new TypeError(`Duplicate or invalid operationId in ${key}`);
+                    operationIds.set(node.operationId, node);
+                }
+            }
+            if (Object.hasOwn(node, "$ref") && !scan)
+                out.$ref = reference(node.$ref);
+            const array = (name, childKind) => { if (node[name] !== undefined)
+                out[name] = items(node[name], name).map(child => walk(child, childKind, scan)); };
+            const child = (name, childKind) => { if (node[name] !== undefined)
+                out[name] = walk(node[name], childKind, scan); };
+            const keyed = (name, childKind, extensions = false) => { if (node[name] !== undefined)
+                out[name] = map(node[name], childKind, scan, extensions); };
+            if (kind === "schema") {
+                if (["$id", "$anchor", "$dynamicAnchor", "$vocabulary"].some(name => Object.hasOwn(node, name)))
+                    throw new TypeError("Resolve schema resources/anchors before OpenAPI composition");
+                if (node.$dynamicRef !== undefined && !scan)
+                    out.$dynamicRef = reference(node.$dynamicRef);
+                for (const name of ["properties", "patternProperties", "dependentSchemas", "$defs", "definitions"])
+                    keyed(name, "schema");
+                for (const name of ["allOf", "anyOf", "oneOf", "prefixItems"])
+                    array(name, "schema");
+                for (const name of ["items", "contains", "additionalProperties", "unevaluatedProperties", "unevaluatedItems", "propertyNames", "not", "if", "then", "else", "additionalItems"])
+                    child(name, "schema");
+                if (node.discriminator !== undefined && !scan) {
+                    const discriminator = record(node.discriminator, "discriminator");
+                    const mapping = discriminator.mapping;
+                    if (mapping !== undefined)
+                        out.discriminator = { ...discriminator, mapping: Object.fromEntries(Object.entries(record(mapping, "discriminator mapping")).map(([name, target]) => {
+                                if (typeof target !== "string")
+                                    throw new TypeError("Discriminator targets must be strings");
+                                const schemas = record(sourceComponents.schemas, "schemas");
+                                return [name, Object.hasOwn(schemas, target) ? qualified(target) : reference(target)];
+                            })) };
+                }
+            }
+            else if (kind === "pathItem") {
+                array("parameters", "parameter");
+                const servers = node.servers === undefined ? inheritedServers : items(node.servers, "path servers");
+                for (const method of methods)
+                    if (node[method] !== undefined)
+                        out[method] = walk(node[method], "operation", scan, servers);
+            }
+            else if (kind === "operation") {
+                array("parameters", "parameter");
+                child("requestBody", "requestBody");
+                keyed("responses", "response", true);
+                keyed("callbacks", "callback");
+                if (!scan) {
+                    if (node.operationId !== undefined)
+                        out.operationId = `${key}.${node.operationId}`;
+                    if (node.security !== undefined || defaultSecurity !== undefined)
+                        out.security = security(node.security ?? defaultSecurity);
+                    if (node.servers === undefined && inheritedServers !== undefined && JSON.stringify(inheritedServers) !== JSON.stringify(rootServers))
+                        out.servers = inheritedServers;
+                    if (node.tags !== undefined)
+                        out.tags = items(node.tags, "tags").map(tag => { if (typeof tag !== "string")
+                            throw new TypeError("Tags must be strings"); return `${key}.${tag}`; });
+                }
+            }
+            else if (kind === "parameter" || kind === "header" || kind === "mediaType") {
+                child("schema", "schema");
+                keyed("examples", "example");
+                keyed("content", "mediaType");
+                keyed("encoding", "encoding");
+                if (kind === "mediaType" && node["x-wsdl-tsc-stream"] !== undefined) {
+                    // @why Generated stream consumers discover record schemas here; unrelated extension payloads may contain literal $ref data.
+                    const stream = record(node["x-wsdl-tsc-stream"], "stream metadata");
+                    out["x-wsdl-tsc-stream"] = { ...stream,
+                        ...(stream.itemSchema === undefined ? {} : { itemSchema: walk(stream.itemSchema, "schema", scan) }) };
+                }
+            }
+            else if (kind === "encoding")
+                keyed("headers", "header");
+            else if (kind === "requestBody")
+                keyed("content", "mediaType");
+            else if (kind === "response") {
+                keyed("headers", "header");
+                keyed("content", "mediaType");
+                keyed("links", "link");
+            }
+            else if (kind === "callback") {
+                for (const [expression, pathItem] of Object.entries(node))
+                    if (expression !== "$ref" && !expression.startsWith("x-"))
+                        out[expression] = walk(pathItem, "pathItem", scan);
+            }
+            else if (kind === "link" && !scan) {
+                if (node.operationId !== undefined && node.operationRef !== undefined)
+                    throw new TypeError("A link cannot set both operationId and operationRef");
+                if (node.operationId !== undefined) {
+                    if (typeof node.operationId !== "string" || !operationIds.has(node.operationId))
+                        throw new TypeError(`Unresolved link operationId ${String(node.operationId)}`);
+                    out.operationId = `${key}.${node.operationId}`;
+                }
+                if (node.operationRef !== undefined)
+                    out.operationRef = reference(node.operationRef, true);
+            }
+            return out;
+        }
+        for (const [route, value] of Object.entries(sourcePaths))
+            if (!route.startsWith("x-"))
+                walk(value, "pathItem", true);
+        if (source.webhooks !== undefined)
+            map(source.webhooks, "pathItem", true);
+        for (const [category, values] of Object.entries(sourceComponents)) {
+            if (category.startsWith("x-"))
+                continue;
+            if (!Object.hasOwn(categories, category))
+                throw new TypeError(`Unsupported OpenAPI component category ${category}`);
+            map(values, categories[category], true);
+        }
+        for (const [route, value] of Object.entries(sourcePaths)) {
+            if (route.startsWith("x-"))
+                continue;
+            if (!route.startsWith("/") || Object.hasOwn(paths, route))
+                throw new TypeError(`Duplicate or invalid final path ${route}`);
+            paths[route] = record(walk(value, "pathItem", false), "path item");
+        }
+        if (source.webhooks !== undefined)
+            for (const [name, value] of Object.entries(record(source.webhooks, "webhooks")))
+                webhooks[qualified(name)] = walk(value, "pathItem", false);
+        for (const [category, values] of Object.entries(sourceComponents)) {
+            if (category.startsWith("x-"))
+                continue;
+            const destination = components[category] ??= dict();
+            for (const [name, value] of Object.entries(record(values, "components")))
+                destination[qualified(name)] = walk(value, categories[category], false);
+        }
+        if (source.tags !== undefined)
+            for (const value of items(source.tags, "tags")) {
+                const tag = record(value, "tag");
+                if (typeof tag.name !== "string")
+                    throw new TypeError("Tag name must be a string");
+                tags[`${key}.${tag.name}`] = { ...tag, name: `${key}.${tag.name}` };
+            }
+        services[key] = { info: source.info,
+            extensions: Object.fromEntries(Object.entries(source).filter(([name]) => name.startsWith("x-"))),
+            componentExtensions: Object.fromEntries(Object.entries(sourceComponents).filter(([name]) => name.startsWith("x-"))),
+            pathExtensions: Object.fromEntries(Object.entries(sourcePaths).filter(([name]) => name.startsWith("x-"))) };
+    }
+    const info = { title: options.title ?? "Composed SOAP API", version: options.version ?? "0.0.0" };
+    if (options.description !== undefined)
+        info.description = options.description;
+    const result = { openapi: "3.1.0", info, servers: rootServers, paths, components, "x-wsdl-tsc-services": services };
+    if (Object.keys(webhooks).length)
+        result.webhooks = webhooks;
+    if (Object.keys(tags).length)
+        result.tags = Object.keys(tags).sort().map(name => tags[name]);
+    if (dialect !== "https://spec.openapis.org/oas/3.1/dialect/base")
+        result.jsonSchemaDialect = dialect;
+    return stable(result);
+}

package/dist/pipeline.d.ts

@@ -53,7 +53,7 @@ export interface PipelineOptions {
     /**
      * Path to a stream configuration JSON file. Loaded and parsed once before
      * compilation; the parsed value takes precedence over `streamConfig` when
-     * both are set. Leave undefined to preserve byte-for-byte buffered output.
+     * both are set. Unlisted operations retain their buffered API selection.
      */
     streamConfigFile?: string;
     /**