@techspokes/typescript-wsdl-client 0.6.3 → 0.7.0

package/dist/openapi/buildPaths.js

@@ -0,0 +1,66 @@
+import { toPathSegment } from "./casing.js";
+export function buildPaths(compiled, opts) {
+    const paths = {};
+    const base = normalizeBase(opts.basePath || "/");
+    for (const op of compiled.operations) {
+        const seg = toPathSegment(op.name, opts.pathStyle);
+        const fullPath = (base.endsWith("/") ? base.slice(0, -1) : base) + "/" + seg;
+        const override = opts.overrides?.[op.name] || {};
+        const method = (override.method || opts.defaultMethod || "post").toLowerCase();
+        const tag = opts.tagsMap?.[op.name] || opts.defaultTag;
+        const inputRef = op.inputElement?.local ? { $ref: `#/components/schemas/${op.inputElement.local}` } : { type: "object" };
+        const outputRef = op.outputElement?.local ? { $ref: `#/components/schemas/${op.outputElement.local}` } : { type: "object" };
+        const parameters = [];
+        // Header parameters from security builder
+        const headerParamNames = opts.opHeaderParameters[op.name] || [];
+        for (const pName of headerParamNames) {
+            parameters.push({ $ref: `#/components/parameters/${pName}` });
+        }
+        const operationObject = {
+            operationId: op.name,
+            tags: [tag],
+            requestBody: {
+                required: true,
+                content: {
+                    "application/json": { schema: inputRef }
+                }
+            },
+            responses: {
+                "200": {
+                    description: "Successful SOAP operation response",
+                    content: {
+                        "application/json": { schema: outputRef }
+                    }
+                },
+                default: {
+                    description: "Error response",
+                    content: {
+                        "application/json": { schema: { $ref: "#/components/schemas/ErrorEnvelope" } }
+                    }
+                }
+            },
+        };
+        if (override.summary)
+            operationObject.summary = override.summary;
+        if (override.description)
+            operationObject.description = override.description;
+        if (override.deprecated)
+            operationObject.deprecated = true;
+        if (parameters.length)
+            operationObject.parameters = parameters;
+        const opSec = opts.opSecurity[op.name];
+        if (opSec)
+            operationObject.security = opSec;
+        if (!paths[fullPath])
+            paths[fullPath] = {};
+        paths[fullPath][method] = operationObject;
+    }
+    return paths;
+}
+function normalizeBase(base) {
+    if (!base.startsWith("/"))
+        base = "/" + base;
+    if (base.endsWith("/"))
+        return base;
+    return base;
+}

package/dist/openapi/buildSchemas.d.ts

@@ -0,0 +1,44 @@
+/**
+ * OpenAPI Schema Component Builder
+ *
+ * This module transforms the compiled TypeScript types from the WSDL catalog
+ * into OpenAPI 3.1 schema components. It handles the conversion of complex types,
+ * type aliases, arrays, and primitive types to their JSON Schema equivalents.
+ *
+ * Key features:
+ * - Converts TypeScript interfaces to JSON Schema objects
+ * - Handles type aliases and enumerations
+ * - Supports array types with appropriate item definitions
+ * - Manages property requirements based on XML schema constraints
+ * - Optionally enforces closed schemas with additionalProperties:false
+ * - Can prune schemas that aren't referenced by any operation
+ */
+import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
+/**
+ * Options for building OpenAPI schema components
+ *
+ * @interface BuildSchemasOptions
+ * @property {boolean} [closedSchemas] - Whether to add additionalProperties:false to object schemas
+ * @property {boolean} [pruneUnusedSchemas] - Whether to exclude schemas not referenced by operations
+ */
+export interface BuildSchemasOptions {
+    closedSchemas?: boolean;
+    pruneUnusedSchemas?: boolean;
+}
+export type ComponentsSchemas = Record<string, any>;
+/**
+ * Transforms the compiled WSDL catalog into OpenAPI schema components
+ *
+ * @function buildSchemas
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog containing types, aliases, and operations
+ * @param {BuildSchemasOptions} opts - Options for schema generation
+ * @returns {ComponentsSchemas} - A record of schema component names to their JSON Schema definitions
+ *
+ * @throws Will throw an error if there are unknown referenced types or bases while building schemas
+ *
+ * @example
+ * // Example usage: building schemas with closed schemas enforcement and unused schema pruning
+ * const schemas = buildSchemas(compiledCatalog, { closedSchemas: true, pruneUnusedSchemas: true });
+ */
+export declare function buildSchemas(compiled: CompiledCatalog, opts: BuildSchemasOptions): ComponentsSchemas;
+//# sourceMappingURL=buildSchemas.d.ts.map

package/dist/openapi/buildSchemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildSchemas.d.ts","sourceRoot":"","sources":["../../src/openapi/buildSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAgB,eAAe,EAAe,MAAM,+BAA+B,CAAC;AAEhG;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAmIpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,mBAAmB,GAAG,iBAAiB,CA0DpG"}

package/dist/openapi/buildSchemas.js

@@ -0,0 +1,207 @@
+function isLiteralUnion(ts) {
+    // very naive: split by | and ensure each trimmed starts and ends with quotes
+    const parts = ts.split("|").map(p => p.trim()).filter(Boolean);
+    if (!parts.length)
+        return null;
+    if (parts.every(p => /^".*"$/.test(p))) {
+        return parts.map(p => p.slice(1, -1));
+    }
+    return null;
+}
+function primitiveSchema(ts) {
+    switch (ts) {
+        case "string":
+            return { type: "string" };
+        case "number":
+            return { type: "number" };
+        case "boolean":
+            return { type: "boolean" };
+        case "any":
+            return {};
+        default:
+            if (ts.endsWith("[]")) {
+                return { type: "array", items: primitiveSchema(ts.slice(0, -2)) };
+            }
+            return { $ref: `#/components/schemas/${ts}` };
+    }
+}
+function buildAliasSchema(a) {
+    const lit = isLiteralUnion(a.tsType);
+    if (lit) {
+        return { type: "string", enum: lit };
+    }
+    // If alias wraps primitive
+    if (["string", "number", "boolean", "any"].includes(a.tsType) || a.tsType.endsWith("[]")) {
+        return primitiveSchema(a.tsType);
+    }
+    // alias of another complex/alias type -> allOf wrapper preserves name
+    return { allOf: [{ $ref: `#/components/schemas/${a.tsType}` }] };
+}
+function isArrayWrapper(t) {
+    if (t.attrs.length !== 0)
+        return null;
+    if (t.elems.length !== 1)
+        return null;
+    const e = t.elems[0];
+    if (e.max !== "unbounded" && !(e.max > 1))
+        return null;
+    return { itemType: e.tsType };
+}
+function buildComplexSchema(t, closed, knownTypeNames, aliasNames) {
+    // Use knownTypeNames/aliasNames to validate $ref targets so we surface
+    // compiler issues early instead of emitting dangling references in OpenAPI output.
+    function refOrPrimitive(ts) {
+        switch (ts) {
+            case "string":
+                return { type: "string" };
+            case "number":
+                return { type: "number" };
+            case "boolean":
+                return { type: "boolean" };
+            case "any":
+                return {}; // intentionally permissive
+            default:
+                if (ts.endsWith("[]")) {
+                    const inner = ts.slice(0, -2);
+                    return { type: "array", items: refOrPrimitive(inner) };
+                }
+                if (!knownTypeNames.has(ts) && !aliasNames.has(ts)) {
+                    // Fail fast: this indicates a mismatch between schemaCompiler output and OpenAPI builder expectations.
+                    throw new Error(`[openapi] unknown referenced type '${ts}' while building schema '${t.name}'`);
+                }
+                return { $ref: `#/components/schemas/${ts}` };
+        }
+    }
+    const arrayWrap = isArrayWrapper(t);
+    if (arrayWrap) {
+        const item = refOrPrimitive(String(arrayWrap.itemType));
+        return { type: "array", items: item };
+    }
+    const properties = {};
+    const required = [];
+    // attributes
+    for (const a of t.attrs) {
+        properties[a.name] = refOrPrimitive(a.tsType);
+        if (a.use === "required")
+            required.push(a.name);
+    }
+    // elements
+    for (const e of t.elems) {
+        const baseSchema = refOrPrimitive(e.tsType);
+        const isArray = e.max === "unbounded" || (e.max > 1);
+        let schema = baseSchema;
+        if (isArray)
+            schema = { type: "array", items: baseSchema };
+        if (e.nillable) {
+            schema = { anyOf: [schema, { type: "null" }] };
+        }
+        properties[e.name] = schema;
+        if (e.name === "$value") {
+            // never required
+        }
+        else if (e.min >= 1) {
+            required.push(e.name);
+        }
+    }
+    const obj = {
+        type: "object",
+        properties,
+    };
+    if (required.length)
+        obj.required = Array.from(new Set(required));
+    if (closed)
+        obj.additionalProperties = false;
+    // inheritance via base => allOf
+    if (t.base) {
+        const baseName = t.base;
+        // Validate base reference explicitly (using helper ensures error if unknown)
+        if (!knownTypeNames.has(baseName) && !aliasNames.has(baseName)) {
+            throw new Error(`[openapi] unknown base type '${baseName}' while building schema '${t.name}'`);
+        }
+        obj.allOf = [{ $ref: `#/components/schemas/${baseName}` }, { ...obj }];
+        delete obj.type; // inner object part handled in allOf
+        delete obj.properties;
+        if (!required.length)
+            delete obj.required;
+        if (!closed)
+            delete obj.additionalProperties; // put closed only on leaf part
+    }
+    return obj;
+}
+/**
+ * Transforms the compiled WSDL catalog into OpenAPI schema components
+ *
+ * @function buildSchemas
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog containing types, aliases, and operations
+ * @param {BuildSchemasOptions} opts - Options for schema generation
+ * @returns {ComponentsSchemas} - A record of schema component names to their JSON Schema definitions
+ *
+ * @throws Will throw an error if there are unknown referenced types or bases while building schemas
+ *
+ * @example
+ * // Example usage: building schemas with closed schemas enforcement and unused schema pruning
+ * const schemas = buildSchemas(compiledCatalog, { closedSchemas: true, pruneUnusedSchemas: true });
+ */
+export function buildSchemas(compiled, opts) {
+    const closed = !!opts.closedSchemas;
+    const schemas = {};
+    const typeNames = new Set(compiled.types.map(t => t.name));
+    const aliasNames = new Set(compiled.aliases.map(a => a.name));
+    // Build alias schemas first so complex types can reference them
+    for (const a of compiled.aliases) {
+        schemas[a.name] = buildAliasSchema(a);
+    }
+    for (const t of compiled.types) {
+        schemas[t.name] = buildComplexSchema(t, closed, typeNames, aliasNames);
+    }
+    if (opts.pruneUnusedSchemas) {
+        // Root references: each operation's inputElement.local, outputElement.local
+        const roots = new Set();
+        for (const op of compiled.operations) {
+            if (op.inputElement?.local)
+                roots.add(op.inputElement.local);
+            if (op.outputElement?.local)
+                roots.add(op.outputElement.local);
+        }
+        // BFS through $ref graph
+        const reachable = new Set();
+        const queue = Array.from(roots);
+        while (queue.length) {
+            const cur = queue.shift();
+            if (reachable.has(cur))
+                continue;
+            if (!schemas[cur])
+                continue; // unknown
+            reachable.add(cur);
+            const scan = (node) => {
+                if (!node || typeof node !== "object")
+                    return;
+                if (node.$ref) {
+                    const name = node.$ref.split("/").pop();
+                    if (name && !reachable.has(name))
+                        queue.push(name);
+                }
+                for (const v of Object.values(node))
+                    scan(v);
+            };
+            scan(schemas[cur]);
+        }
+        // prune
+        for (const k of Object.keys(schemas)) {
+            if (!reachable.has(k))
+                delete schemas[k];
+        }
+    }
+    // Standard error envelope (always include)
+    if (!schemas.ErrorEnvelope) {
+        schemas.ErrorEnvelope = {
+            type: "object",
+            properties: {
+                message: { type: "string" },
+                faultCode: { type: "string" },
+                detail: { type: "object", additionalProperties: true },
+            },
+        };
+    }
+    return schemas;
+}

package/dist/openapi/casing.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Path Segment Styling for OpenAPI Generation
+ *
+ * This module provides utilities for converting operation names to appropriately styled
+ * path segments in the OpenAPI specification. It supports multiple styling options to
+ * accommodate different API design preferences:
+ *
+ * - kebab-case: Transforms "GetUserDetails" to "get-user-details"
+ * - as-is: Preserves the original operation name without modification
+ * - lowercase: Converts to lowercase and removes all non-alphanumeric characters
+ *
+ * These transformations ensure that the generated API paths follow consistent conventions
+ * and are properly formatted for RESTful API design.
+ */
+/**
+ * Path segment styling options for OpenAPI generation
+ *
+ * @property {"kebab"} string Convert to kebab-case (e.g., "get-user-details")
+ * @property {"asis"} string Keep the original operation name unchanged
+ * @property {"lower"} string Convert to lowercase and remove non-alphanumeric characters
+ */
+export type PathStyle = "kebab" | "asis" | "lower";
+/**
+ * Converts an operation name to a path segment according to the specified style
+ *
+ * This function transforms operation names like "GetUserDetails" or "createNewOrder"
+ * into appropriately styled path segments based on the selected style:
+ *
+ * - kebab: "GetUserDetails" → "get-user-details"
+ * - asis: "GetUserDetails" → "GetUserDetails"
+ * - lower: "GetUserDetails" → "getuserdetails"
+ *
+ * @param {string} name - Operation name to convert
+ * @param {PathStyle} style - Path segment style to apply
+ * @returns {string} - Formatted path segment
+ */
+export declare function toPathSegment(name: string, style: PathStyle): string;
+//# sourceMappingURL=casing.d.ts.map

package/dist/openapi/casing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"casing.d.ts","sourceRoot":"","sources":["../../src/openapi/casing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAQnD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAepE"}

package/dist/openapi/casing.js

@@ -0,0 +1,49 @@
+/**
+ * Path Segment Styling for OpenAPI Generation
+ *
+ * This module provides utilities for converting operation names to appropriately styled
+ * path segments in the OpenAPI specification. It supports multiple styling options to
+ * accommodate different API design preferences:
+ *
+ * - kebab-case: Transforms "GetUserDetails" to "get-user-details"
+ * - as-is: Preserves the original operation name without modification
+ * - lowercase: Converts to lowercase and removes all non-alphanumeric characters
+ *
+ * These transformations ensure that the generated API paths follow consistent conventions
+ * and are properly formatted for RESTful API design.
+ */
+/**
+ * Regular expression for detecting boundaries between words in camelCase
+ * Matches transitions from lowercase/digit to uppercase letter
+ */
+const CAMEL_BOUNDARY = /([a-z0-9])([A-Z])/g;
+/**
+ * Converts an operation name to a path segment according to the specified style
+ *
+ * This function transforms operation names like "GetUserDetails" or "createNewOrder"
+ * into appropriately styled path segments based on the selected style:
+ *
+ * - kebab: "GetUserDetails" → "get-user-details"
+ * - asis: "GetUserDetails" → "GetUserDetails"
+ * - lower: "GetUserDetails" → "getuserdetails"
+ *
+ * @param {string} name - Operation name to convert
+ * @param {PathStyle} style - Path segment style to apply
+ * @returns {string} - Formatted path segment
+ */
+export function toPathSegment(name, style) {
+    switch (style) {
+        case "asis":
+            return name;
+        case "lower":
+            return name.replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+        case "kebab":
+        default:
+            // insert hyphen between camelCase boundaries then sanitize
+            return name
+                .replace(CAMEL_BOUNDARY, "$1-$2")
+                .replace(/[^A-Za-z0-9]+/g, "-")
+                .replace(/^-+|-+$/g, "")
+                .toLowerCase();
+    }
+}

package/dist/openapi/generateOpenAPI.d.ts

@@ -0,0 +1,57 @@
+import { type CompiledCatalog } from "../compiler/schemaCompiler.js";
+import type { PathStyle } from "./casing.js";
+/**
+ * Options for OpenAPI generation from WSDL
+ *
+ * @interface GenerateOpenAPIOptions
+ * @property {string} [wsdl] - Path or URL to WSDL file (exclusive with catalogFile and compiledCatalog)
+ * @property {string} [catalogFile] - Path to existing compiled catalog.json (exclusive with wsdl and compiledCatalog)
+ * @property {CompiledCatalog} [compiledCatalog] - Pre-compiled catalog in memory (exclusive with wsdl and catalogFile)
+ * @property {string} [outFile] - Output path for generated OpenAPI specification
+ * @property {string} [title] - API title (defaults to derived service name)
+ * @property {string} [version] - API version for info.version (default 0.0.0)
+ * @property {string} [description] - API description
+ * @property {string[]} [servers] - List of server URLs
+ * @property {string} [basePath] - Base path prefix (e.g., /v1/soap)
+ * @property {PathStyle} [pathStyle] - Path segment style: kebab, asis, or lower
+ * @property {string} [defaultMethod] - Default HTTP method: post, get, put, patch, delete
+ * @property {string} [securityConfigFile] - Path to security.json configuration
+ * @property {string} [tagsFile] - Path to tags.json mapping operation names to tags
+ * @property {string} [opsFile] - Path to ops.json with per-operation overrides
+ * @property {boolean} [closedSchemas] - Whether to emit additionalProperties:false
+ * @property {boolean} [pruneUnusedSchemas] - Whether to exclude schemas not referenced by operations
+ * @property {boolean} [asYaml] - Force YAML output regardless of extension (deprecated)
+ * @property {boolean} [validate] - Whether to validate using swagger-parser
+ * @property {"default"|"first"|"service"} [tagStyle] - Heuristic for deriving tags
+ * @property {"json"|"yaml"|"both"} [format] - Output format (default: json)
+ * @property {boolean} [skipValidate] - Skip validation (default: false)
+ */
+export interface GenerateOpenAPIOptions {
+    wsdl?: string;
+    catalogFile?: string;
+    outFile?: string;
+    title?: string;
+    version?: string;
+    description?: string;
+    servers?: string[];
+    basePath?: string;
+    pathStyle?: PathStyle;
+    defaultMethod?: string;
+    securityConfigFile?: string;
+    tagsFile?: string;
+    opsFile?: string;
+    closedSchemas?: boolean;
+    pruneUnusedSchemas?: boolean;
+    asYaml?: boolean;
+    validate?: boolean;
+    tagStyle?: "default" | "first" | "service";
+    compiledCatalog?: CompiledCatalog;
+    format?: "json" | "yaml" | "both";
+    skipValidate?: boolean;
+}
+export declare function generateOpenAPI(opts: GenerateOpenAPIOptions): Promise<{
+    doc: any;
+    jsonPath?: string;
+    yamlPath?: string;
+}>;
+//# sourceMappingURL=generateOpenAPI.d.ts.map

package/dist/openapi/generateOpenAPI.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateOpenAPI.d.ts","sourceRoot":"","sources":["../../src/openapi/generateOpenAPI.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAiB,KAAK,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAInF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IAC3C,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC;IAC3E,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CAgJD"}

package/dist/openapi/generateOpenAPI.js

@@ -0,0 +1,174 @@
+/**
+ * OpenAPI 3.1 Generator from WSDL
+ *
+ * This module generates OpenAPI 3.1 specifications from WSDL documents or compiled catalogs.
+ * It bridges the gap between SOAP web services and REST APIs by creating an OpenAPI
+ * representation that mirrors the TypeScript model generated by the WSDL client generator.
+ *
+ * The generator supports:
+ * - Multiple input sources (WSDL URL/path, pre-compiled catalog, or in-memory catalog)
+ * - Customizable paths, operations, and schemas
+ * - Security scheme configuration
+ * - Custom operation tagging and metadata
+ * - Multiple output formats (JSON, YAML, or both)
+ * - OpenAPI validation
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as yaml from "js-yaml";
+import { loadWsdl } from "../loader/wsdlLoader.js";
+import { compileCatalog } from "../compiler/schemaCompiler.js";
+import { buildSchemas } from "./buildSchemas.js";
+import { buildPaths } from "./buildPaths.js";
+import { buildSecurity, loadSecurityConfig } from "./security.js";
+export async function generateOpenAPI(opts) {
+    // Normalize format (back-compat: asYaml overrides if provided and format not set)
+    let format = opts.format || (opts.asYaml ? "yaml" : "json");
+    if (format === "yaml" && opts.asYaml && opts.outFile && /\.json$/i.test(opts.outFile)) {
+        // user asked for yaml but provided .json path → we'll still switch extension
+    }
+    if (!opts.compiledCatalog && !opts.wsdl && !opts.catalogFile) {
+        throw new Error("Provide one of: compiledCatalog, wsdl, or catalogFile");
+    }
+    if ((opts.wsdl && opts.catalogFile) || (opts.compiledCatalog && (opts.wsdl || opts.catalogFile))) {
+        // Not strictly an error, but disallow ambiguous multi-source inputs to keep deterministic
+        // Users should supply only ONE source of truth.
+        throw new Error("Provide only one source: compiledCatalog OR wsdl OR catalogFile");
+    }
+    let compiled;
+    if (opts.compiledCatalog) {
+        compiled = opts.compiledCatalog;
+    }
+    else if (opts.catalogFile) {
+        const raw = fs.readFileSync(opts.catalogFile, "utf8");
+        compiled = JSON.parse(raw);
+    }
+    else {
+        const wsdlCatalog = await loadWsdl(String(opts.wsdl));
+        compiled = compileCatalog(wsdlCatalog, {
+            // minimal compiler options (no generation side effects needed here)
+            wsdl: String(opts.wsdl),
+            out: "",
+            imports: "js",
+            catalog: false,
+            primitive: { int64As: "string", bigIntegerAs: "string", decimalAs: "string", dateAs: "string" },
+            choice: "all-optional",
+            failOnUnresolved: false,
+            attributesKey: "$attributes",
+            nillableAsOptional: false,
+            clientName: undefined,
+        });
+    }
+    const title = opts.title || (compiled.serviceName ? `${compiled.serviceName} SOAP API` : "Generated SOAP API");
+    const infoVersion = opts.version || "0.0.0";
+    // Load external config files (optional)
+    const tagsMap = opts.tagsFile ? safeJson(opts.tagsFile) : undefined;
+    const opsOverrides = opts.opsFile ? safeJson(opts.opsFile) : undefined;
+    const securityCfg = loadSecurityConfig(opts.securityConfigFile);
+    const securityBuilt = buildSecurity(securityCfg);
+    // Build components.schemas
+    const schemas = buildSchemas(compiled, {
+        closedSchemas: opts.closedSchemas,
+        pruneUnusedSchemas: opts.pruneUnusedSchemas
+    });
+    // Build paths
+    const tagStyle = opts.tagStyle || "default";
+    const defaultTag = (() => {
+        if (tagStyle === "service")
+            return compiled.serviceName || "SOAP";
+        if (tagStyle === "first")
+            return "General"; // fallback; per-op derivation below
+        return compiled.serviceName || "SOAP";
+    })();
+    const paths = buildPaths(compiled, {
+        basePath: opts.basePath || "/",
+        pathStyle: opts.pathStyle || "kebab",
+        defaultMethod: opts.defaultMethod || "post",
+        tagsMap,
+        overrides: opsOverrides,
+        defaultTag,
+        opSecurity: securityBuilt.opSecurity,
+        opHeaderParameters: securityBuilt.opHeaderParameters,
+    });
+    // Apply tag heuristics for operations missing explicit tag if style=first
+    if (tagStyle === "first") {
+        for (const p of Object.values(paths)) {
+            for (const methodObj of Object.values(p)) {
+                if (Array.isArray(methodObj.tags) && methodObj.tags[0] === "General") {
+                    const opId = methodObj.operationId || "Op";
+                    const seg = opId.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).filter(Boolean)[0] || "General";
+                    methodObj.tags = [seg];
+                }
+            }
+        }
+    }
+    const doc = {
+        openapi: "3.1.0",
+        jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema",
+        info: { title, version: infoVersion },
+        paths,
+        components: {
+            schemas,
+            ...(securityBuilt.securitySchemes ? { securitySchemes: securityBuilt.securitySchemes } : {}),
+            ...(Object.keys(securityBuilt.headerParameters).length ? { parameters: securityBuilt.headerParameters } : {}),
+        },
+    };
+    if (opts.description)
+        doc.info.description = opts.description;
+    if (opts.servers && opts.servers.length) {
+        doc.servers = opts.servers.map(u => ({ url: u }));
+    }
+    if (opts.skipValidate !== true) {
+        try {
+            const parser = await import("@apidevtools/swagger-parser");
+            await parser.default.validate(JSON.parse(JSON.stringify(doc)));
+            console.log("OpenAPI validation: OK");
+        }
+        catch (e) {
+            console.error("OpenAPI validation failed:", e instanceof Error ? e.message : e);
+            throw e;
+        }
+    }
+    else {
+        console.log("OpenAPI validation skipped by flag");
+    }
+    // Determine base path for writing
+    let base = opts.outFile;
+    if (base) {
+        const extMatch = base.match(/\.(json|ya?ml)$/i);
+        if (extMatch) {
+            base = base.slice(0, -extMatch[0].length); // strip extension
+        }
+    }
+    let jsonPath;
+    let yamlPath;
+    if (opts.outFile) {
+        const dir = path.dirname(opts.outFile);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        if (format === "json") {
+            jsonPath = base ? `${base}.json` : opts.outFile;
+            fs.writeFileSync(jsonPath, JSON.stringify(doc, null, 2), "utf8");
+        }
+        else if (format === "yaml") {
+            yamlPath = base ? `${base}.yaml` : opts.outFile.replace(/\.(json)$/i, ".yaml");
+            fs.writeFileSync(yamlPath, yaml.dump(doc), "utf8");
+        }
+        else { // both
+            jsonPath = `${base}.json`;
+            yamlPath = `${base}.yaml`;
+            fs.writeFileSync(jsonPath, JSON.stringify(doc, null, 2), "utf8");
+            fs.writeFileSync(yamlPath, yaml.dump(doc), "utf8");
+        }
+    }
+    return { doc, jsonPath, yamlPath };
+}
+function safeJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (e) {
+        console.warn(`⚠️ Failed to parse JSON file '${file}': ${e instanceof Error ? e.message : String(e)}`);
+        return undefined;
+    }
+}