@techspokes/typescript-wsdl-client 1.1.8 → 1.3.0

package/dist/generation/componentShape.js

@@ -19,7 +19,31 @@ export function lowerComponentShape(contract, supplied, role, check) {
         const owned = inspectComponentRecordProjection(supplied, contract);
         return lowerComponentShape(owned.companion, owned.mapping, role, check);
     }
-    const { projection, applicationGroups } = inspectComponentValueMapping(supplied, contract), { context } = inspectDirectOperation(contract);
+    const { mapping, projection, applicationGroups, rpcParts } = inspectComponentValueMapping(supplied, contract), { context } = inspectDirectOperation(contract);
+    if ('parts' in mapping.root) {
+        const properties = Object.create(null);
+        const required = [], members = [];
+        for (const part of mapping.root.parts) {
+            check();
+            const plan = rpcParts?.find(plan => plan.name === part.name)?.projection;
+            let type = 'string';
+            if (plan?.root.kind === 'record') {
+                const record = plan.records[0];
+                const fields = Object.fromEntries(record.slots.map(slot => [slot.element.name.local, { type: 'boolean' }]));
+                properties[part.name] = { type: 'object', properties: fields, required: Object.keys(fields), additionalProperties: false };
+                type = `{${record.slots.map(slot => `readonly ${literal(slot.element.name.local)}: boolean`).join('; ')}}`;
+            }
+            else {
+                type = plan?.root.kind === 'scalar' && plan.root.builtin.local === 'boolean' ? 'boolean' : 'string';
+                properties[part.name] = { type };
+            }
+            required.push(part.name);
+            members.push(`readonly ${literal(part.name)}: ${type}`);
+        }
+        return { type: `{${members.join('; ')}}`, declarations: [], schema: { type: 'object', additionalProperties: false, properties, required } };
+    }
+    if (!projection)
+        throw new TypeError('Native document projection required');
     const names = new Map(projection.records.map((record, index) => [record.type.id, applicationGroups
             ? applicationRecordName(record.type.id) : `${role}_Record_${index}`]));
     const definitions = Object.create(null);

package/dist/index.d.ts

@@ -5,13 +5,17 @@ export { buildSecurity, loadSecurityConfigFile, parseSecurityConfig, SecurityCon
 export { generateTests } from "./test/generateTests.js";
 export { runGenerationPipeline } from "./pipeline.js";
 export type { PipelineOptions } from './pipeline.js';
+export { runMultiServicePipeline, loadMultiServiceConfig } from './multiServicePipeline.js';
+export type { MultiServicePipelineOptions, MultiServicePipelineResult, MultiServiceEntry } from './multiServicePipeline.js';
+export { composeOpenApiDocuments } from './openapi/composeOpenAPI.js';
+export type { ComposedOpenApiDocument, OpenApiCompositionEntry, OpenApiCompositionOptions } from './openapi/composeOpenAPI.js';
 export type { CheckedComponentOptions, CheckedInventory } from './checkedPipeline.js';
 export { planCheckedComponents, formatCheckedComponentPlan, writeCheckedPlanningFile, CheckedPlanningError } from './checkedPlanning.js';
 export type { CheckedComponentPlan, ComponentPlanBlocker } from './checkedPlanning.js';
 export type { ComponentRecordProjectionSpec, ComponentRecordProjectionAssociation } from './compiler/componentRecordProjection.js';
 export { loadStreamConfigFile, parseStreamConfig, StreamConfigError, type OperationStreamMetadata, type ShapeCatalogRef, type StreamConfig, } from "./util/streamConfig.js";
 export { applyShapeCatalogs, type ApplyShapeCatalogsOptions } from "./compiler/shapeResolver.js";
-export { checkedDirectRuntimeV1, checkedComponentRuntimeV1 } from './client/checkedDirectRuntime.js';
+export { checkedDirectRuntimeV1, checkedComponentRuntimeV1, checkedComponentRuntimeV2 } from './client/checkedDirectRuntime.js';
 /**
  * Compiles a WSDL file to TypeScript client code
  *

package/dist/index.js

@@ -27,10 +27,12 @@ export { generateGateway } from "./gateway/generateGateway.js";
 export { buildSecurity, loadSecurityConfigFile, parseSecurityConfig, SecurityConfigError, } from "./util/securityConfig.js";
 export { generateTests } from "./test/generateTests.js";
 export { runGenerationPipeline } from "./pipeline.js";
+export { runMultiServicePipeline, loadMultiServiceConfig } from './multiServicePipeline.js';
+export { composeOpenApiDocuments } from './openapi/composeOpenAPI.js';
 export { planCheckedComponents, formatCheckedComponentPlan, writeCheckedPlanningFile, CheckedPlanningError } from './checkedPlanning.js';
 export { loadStreamConfigFile, parseStreamConfig, StreamConfigError, } from "./util/streamConfig.js";
 export { applyShapeCatalogs } from "./compiler/shapeResolver.js";
-export { checkedDirectRuntimeV1, checkedComponentRuntimeV1 } from './client/checkedDirectRuntime.js';
+export { checkedDirectRuntimeV1, checkedComponentRuntimeV1, checkedComponentRuntimeV2 } from './client/checkedDirectRuntime.js';
 // noinspection JSUnusedGlobalSymbols
 /**
  * Compiles a WSDL file to TypeScript client code

package/dist/loader/orderedSyntax.d.ts

@@ -70,6 +70,10 @@ export declare function resolveLexicalQName(lexical: string, node: SyntaxElement
 export declare function decodeMetadataXml(bytes: Uint8Array): string;
 /** Positions are one-based lines/columns and zero-based UTF-16 offsets in decoded XML. */
 export interface OrderedSyntaxOptions {
+    /** Explicit component SOAP response policy; source and shipped direct decoding remain separate. */
+    componentResponseEncoding?: {
+        charset?: string;
+    };
     /** Internal metadata boundary; payload/capsule callers retain the existing encoding policy. */
     metadataEncoding?: boolean;
     maxDepth?: number;

package/dist/loader/orderedSyntax.js

@@ -55,19 +55,33 @@ const xmlEncodingDeclaration = /^<\?xml\s[^?]*encoding\s*=\s*["']([^"']+)["']/i;
 export function decodeMetadataXml(bytes) {
     return decodeXml(bytes, true, true);
 }
-function decodeXml(bytes, strictBom = false, metadata = false) {
+function decodeXml(bytes, strictBom = false, metadata = false, response) {
     let encoding = bytes[0] === 0xff && bytes[1] === 0xfe ? "utf-16le"
         : bytes[0] === 0xfe && bytes[1] === 0xff ? "utf-16be" : "utf-8";
     try {
         const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
         // @why Sniff only an ASCII declaration, never guess Latin1 after UTF-8 failure.
         //   A BOM fixes the encoding and must agree with the decoded declaration.
-        if (metadata && encoding === 'utf-8' && !(bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)) {
+        const bom = encoding !== 'utf-8' || bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf;
+        const canonical = (label) => label.toLowerCase() === 'utf8' ? 'utf-8' : label.toLowerCase();
+        const agrees = (label) => canonical(label) === encoding || canonical(label) === 'utf-16' && encoding.startsWith('utf-16');
+        if ((metadata || response) && !bom) {
             const end = buffer.indexOf('>');
             const declaration = xmlEncodingDeclaration.exec(buffer.toString('latin1', 0, end < 0 ? 0 : end + 1))?.[1].toLowerCase();
-            if (declaration === 'iso-8859-1')
+            if (response) {
+                const asserted = response.charset ?? declaration;
+                if (asserted) {
+                    const selected = canonical(asserted);
+                    if (!['utf-8', 'iso-8859-1'].includes(selected))
+                        throw new SchemaLoadingError('unsupported-capability', 'Unsupported XML byte encoding');
+                    encoding = selected;
+                }
+            }
+            else if (declaration === 'iso-8859-1')
                 encoding = 'iso-8859-1';
         }
+        if (response?.charset && !agrees(response.charset))
+            throw new SchemaLoadingError('unsupported-capability', 'HTTP charset disagrees with XML bytes');
         // TextDecoder's ISO label aliases Windows-1252; Buffer supplies actual ISO byte identity.
         const text = encoding === 'iso-8859-1' ? buffer.toString('latin1') : new TextDecoder(encoding, { fatal: true }).decode(bytes);
         if (strictBom && text.startsWith('\ufeff'))
@@ -107,7 +121,7 @@ export function parseOrderedSyntax(bytes, uri, options = {}) {
     const charge = (amount) => options.chargeWork?.(amount);
     charge(4096 + bytes.byteLength * 64);
     const digest = createHash("sha256").update(bytes).digest("hex");
-    const text = options.metadataEncoding ? decodeMetadataXml(bytes) : decodeXml(bytes, options.xml10Only);
+    const text = options.metadataEncoding ? decodeMetadataXml(bytes) : decodeXml(bytes, options.xml10Only, false, options.componentResponseEncoding);
     const lines = [0];
     for (let i = 0; i < text.length; i++) {
         if (text[i] === "\r") {

package/dist/multiServicePipeline.d.ts

@@ -0,0 +1,41 @@
+import { type PipelineOptions } from "./pipeline.js";
+import { type ComposedOpenApiDocument, type OpenApiCompositionOptions } from "./openapi/composeOpenAPI.js";
+import type { CompiledCatalog } from "./compiler/schemaCompiler.js";
+export interface MultiServiceEntry {
+    key: string;
+    generation: PipelineOptions;
+}
+export interface MultiServicePipelineOptions {
+    services: readonly MultiServiceEntry[];
+    openapi: OpenApiCompositionOptions & {
+        outFile: string;
+    };
+    gateway: {
+        outDir: string;
+        imports?: "js" | "ts" | "bare";
+        openapiPath?: string | false;
+    };
+}
+export interface MultiServicePipelineResult {
+    openapiDoc: ComposedOpenApiDocument;
+    services: Record<string, {
+        compiled: CompiledCatalog;
+        clientDir: string;
+        gatewayDir: string;
+    }>;
+    pluginFile: string;
+    openapiFile: string;
+}
+/** 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 declare function runMultiServicePipeline(options: MultiServicePipelineOptions): Promise<MultiServicePipelineResult>;
+/** 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 declare function loadMultiServiceConfig(file: string): Promise<MultiServicePipelineOptions>;

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;