@techspokes/typescript-wsdl-client 1.1.5 → 1.2.0

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/openapi/generateOpenAPI.d.ts

@@ -83,4 +83,3 @@ export declare function generateOpenAPI(opts: GenerateOpenAPIOptions): Promise<{
     jsonPath?: string;
     yamlPath?: string;
 }>;
-//# sourceMappingURL=generateOpenAPI.d.ts.map

package/dist/openapi/generatePaths.d.ts

@@ -71,4 +71,3 @@ export interface GeneratePathsOptions {
     opHeaderParameters: Record<string, string[]>;
 }
 export declare function generatePaths(compiled: CompiledCatalog, opts: GeneratePathsOptions): Record<string, any>;
-//# sourceMappingURL=generatePaths.d.ts.map

package/dist/openapi/generateSchemas.d.ts

@@ -42,4 +42,3 @@ export type ComponentsSchemas = Record<string, any>;
  * const schemas = generateSchemas(compiledCatalog, { closedSchemas: true, pruneUnusedSchemas: true });
  */
 export declare function generateSchemas(compiled: CompiledCatalog, opts: GenerateSchemasOptions): ComponentsSchemas;
-//# sourceMappingURL=generateSchemas.d.ts.map

package/dist/openapi/security.d.ts

@@ -1,2 +1 @@
 export { buildSecurity, loadSecurityConfigFile as loadSecurityConfig, } from "../util/securityConfig.js";
-//# sourceMappingURL=security.d.ts.map

package/dist/pipeline.d.ts

@@ -21,8 +21,11 @@ import { type StreamConfig } from "./util/streamConfig.js";
  * @property {"copy"|"reference"} [app.openapiMode] - How to handle OpenAPI file (default: "copy")
  */
 export interface PipelineOptions {
+    /** Additive preview selection; omission preserves the legacy pipeline. */
+    model?: 'legacy' | 'checked-components-v1';
+    checkedComponents?: Partial<import('./checkedPipeline.js').CheckedComponentOptions>;
     wsdl: string;
-    catalogOut: string;
+    catalogOut?: string;
     clientOutDir?: string;
     compiler?: Partial<CompilerOptions>;
     openapi?: Omit<GenerateOpenAPIOptions, "wsdl" | "catalogFile" | "compiledCatalog"> & {
@@ -50,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;
     /**
@@ -78,5 +81,6 @@ export interface PipelineOptions {
 export declare function runGenerationPipeline(opts: PipelineOptions): Promise<{
     compiled: any;
     openapiDoc?: any;
+    checked?: import('./checkedPipeline.js').CheckedInventory;
+    planning?: import('./checkedPlanning.js').CheckedComponentPlan;
 }>;
-//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.js

@@ -21,6 +21,7 @@ import { resolveCompilerOptions } from "./config.js";
 import { emitClientArtifacts, reportCompilationStats, reportOpenApiSuccess, success } from "./util/cli.js";
 import { loadStreamConfigFile } from "./util/streamConfig.js";
 import { applyShapeCatalogs } from "./compiler/shapeResolver.js";
+import { deriveClientName } from "./util/tools.js";
 /**
  * Runs the complete generation pipeline from WSDL to TypeScript artifacts and optionally OpenAPI/Gateway/App
  *
@@ -37,6 +38,19 @@ import { applyShapeCatalogs } from "./compiler/shapeResolver.js";
  * @returns {Promise<{compiled: any; openapiDoc?: any}>} - The compiled catalog and optional OpenAPI document
  */
 export async function runGenerationPipeline(opts) {
+    if (Object.hasOwn(opts, 'checkedDirect'))
+        throw new Error('The unpublished checkedDirect generation option has been removed; use checked-components-v1');
+    if (opts.model === 'checked-components-v1') {
+        const { runCheckedPipeline } = await import('./checkedPipeline.js');
+        return runCheckedPipeline(opts);
+    }
+    if (opts.model !== undefined && opts.model !== 'legacy') {
+        throw new Error('Supported generation models are legacy and checked-components-v1');
+    }
+    if (opts.checkedComponents !== undefined)
+        throw new Error('Explicit model checked-components-v1 is required for component configuration');
+    if (!opts.catalogOut)
+        throw new Error('Legacy pipeline requires catalogOut');
     // Determine a working directory for the compiler (used for relative path resolution)
     // Use the first available output location as the base
     const workingDir = opts.clientOutDir
@@ -116,6 +130,7 @@ export async function runGenerationPipeline(opts) {
             clientDir: opts.clientOutDir ? path.resolve(opts.clientOutDir) : undefined,
             // Reuse the same imports mode as the TypeScript client/types/utils emitters
             imports: finalCompiler.imports,
+            clientClassName: opts.gateway.clientClassName ?? deriveClientName(compiled),
             // Pass catalog for runtime unwrap generation
             catalogFile: path.resolve(opts.catalogOut),
             // Thread flatten flag from OpenAPI options

package/dist/test/generateCheckedTests.d.ts

@@ -0,0 +1,17 @@
+export interface GenerateCheckedTestsOptions {
+    readonly testDir: string;
+    readonly appDir: string;
+    readonly clientDir: string;
+    readonly routePath: string;
+    readonly force?: boolean;
+    readonly routePaths?: readonly string[];
+    readonly sourceFile: string;
+}
+/**
+ * Emits runnable host checks without authorizing any production transaction.
+ * @param options - Explicit project paths and the selected generated operation route.
+ * @returns Resolves after writing missing scaffold tests.
+ * @throws If writing or preamble resolution fails.
+ * @sideEffects Creates a test file, preserving an existing file unless forced.
+ */
+export declare function generateCheckedTests(options: GenerateCheckedTestsOptions): Promise<void>;

package/dist/test/generateCheckedTests.js

@@ -0,0 +1,60 @@
+/**
+ * Emits consumer-owned checks for the checked gateway scaffold.
+ * @since 1.1.6
+ * @constraints These checks are distinct from independently specified SOAP wire/business oracles.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeGeneratedSource } from '../generation/writeGeneratedSource.js';
+/**
+ * Emits runnable host checks without authorizing any production transaction.
+ * @param options - Explicit project paths and the selected generated operation route.
+ * @returns Resolves after writing missing scaffold tests.
+ * @throws If writing or preamble resolution fails.
+ * @sideEffects Creates a test file, preserving an existing file unless forced.
+ */
+export async function generateCheckedTests(options) {
+    const testDir = path.resolve(options.testDir);
+    let serverImport = path.relative(testDir, path.join(options.appDir, 'server.js')).split(path.sep).join('/');
+    if (!serverImport.startsWith('.'))
+        serverImport = './' + serverImport;
+    const localSource = path.relative(testDir, options.sourceFile).split(path.sep).join('/');
+    const fileRoot = path.relative(testDir, options.clientDir).split(path.sep).join('/');
+    fs.mkdirSync(testDir, { recursive: true });
+    const destination = path.join(testDir, 'checked-scaffold.test.ts');
+    if (!options.force && fs.existsSync(destination))
+        return;
+    writeGeneratedSource(destination, `import {afterEach, describe, expect, it} from 'vitest';
+import {fileURLToPath} from 'node:url';
+import {buildServer} from ${JSON.stringify(serverImport)};
+
+describe('generated scaffold checks (independent wire/business oracles are separate)', () => {
+  let app: Awaited<ReturnType<typeof buildServer>> | undefined;
+  afterEach(async () => {await app?.close();});
+  async function host() {
+    app = await buildServer({
+      localSource: fileURLToPath(new URL(${JSON.stringify(localSource)}, import.meta.url)),
+      fileRoots: [fileURLToPath(new URL(${JSON.stringify(fileRoot + '/')}, import.meta.url))],
+      endpoint: 'http://127.0.0.1:1/soap',
+      allowedEndpoints: [],
+      sourceResources: [], sourceOrigins: [],
+    });
+    return app;
+  }
+  it('serves health and selected OpenAPI without upstream SOAP calls', async () => {
+    const server = await host();
+    expect((await server.inject({method: 'GET', url: '/health'})).json()).toEqual({status: 'ok'});
+    const spec = (await server.inject({method: 'GET', url: '/openapi.json'})).json();
+    expect(spec.openapi).toBe('3.1.1');
+    for (const route of ${JSON.stringify(options.routePaths ?? [options.routePath])}) expect(spec.paths).toHaveProperty(route);
+  });
+  it.each(${JSON.stringify(options.routePaths ?? [options.routePath])})('rejects an invalid shape before upstream dispatch: %s', async route => {
+    const server = await host();
+    // @constraints Every supported checked root is non-nullable; no field spelling is reserved for test sentinels.
+    const response = await server.inject({method: 'POST', url: route,
+      headers: {'content-type': 'application/json'}, payload: 'null'});
+    expect(response.statusCode).toBe(400);
+  });
+});
+`, 'test');
+}

package/dist/test/generateTests.d.ts

@@ -18,4 +18,3 @@ export interface GenerateTestsOptions {
  * @param opts - Test generation options
  */
 export declare function generateTests(opts: GenerateTestsOptions): Promise<void>;
-//# sourceMappingURL=generateTests.d.ts.map

package/dist/test/generators.d.ts

@@ -71,4 +71,3 @@ export declare function emitEnvelopeBuildersTest(testDir: string, gatewayDir: st
  * Returns null if no array wrappers exist in the catalog.
  */
 export declare function emitUnwrapTest(testDir: string, gatewayDir: string, importsMode: "js" | "ts" | "bare", catalog: CatalogForMocks): string | null;
-//# sourceMappingURL=generators.d.ts.map

package/dist/test/mockData.d.ts

@@ -112,4 +112,3 @@ export declare function generateAllOperationMocks(catalog: CatalogForMocks, opts
     request: unknown;
     response: unknown;
 }>;
-//# sourceMappingURL=mockData.d.ts.map

package/dist/test/mockData.js

@@ -119,14 +119,8 @@ export function generateMockData(typeName, catalog, opts, visited, depth) {
             const value = generateMockPrimitive(propType, propName);
             result[propName] = isArray ? [value] : value;
         }
-        else if (catalog.aliases?.some(alias => alias.name === propType)) {
-            const alias = catalog.aliases.find(entry => entry.name === propType);
-            const value = generateMockPrimitive(alias.tsType, propName);
-            result[propName] = isArray ? [value] : value;
-        }
         else {
-            // Complex type — recurse
-            const childData = generateMockData(propType, catalog, opts, newVisited, currentDepth + 1);
+            const childData = generateMockValue(propType, propName, catalog, opts, newVisited, currentDepth + 1);
             result[propName] = isArray ? [childData] : childData;
         }
     }
@@ -155,14 +149,26 @@ export function generateMockData(typeName, catalog, opts, visited, depth) {
     }
     return result;
 }
-function generateOperationPayload(typeName, catalog) {
-    if (!typeName)
-        return {};
-    const alias = catalog.aliases?.find(a => a.name === typeName);
-    if (alias) {
-        return generateMockPrimitive(alias.tsType, typeName);
+/** Resolve aliases before choosing scalar or structured mock generation; cycles terminate without inventing text. */
+function generateMockValue(typeName, propName, catalog, opts, visited = new Set(), depth = 0) {
+    const aliasNames = new Set();
+    let resolved = typeName;
+    while (true) {
+        const alias = catalog.aliases?.find(a => a.name === resolved);
+        if (!alias)
+            break;
+        if (aliasNames.has(resolved) || visited.has(resolved))
+            return {};
+        aliasNames.add(resolved);
+        resolved = alias.tsType;
     }
-    return generateMockData(typeName, catalog);
+    if (resolved === 'string' || resolved === 'number' || resolved === 'boolean' || aliasNames.size && !catalog.types?.some(type => type.name === resolved) && !catalog.meta?.childType?.[resolved] && !catalog.meta?.attrType?.[resolved]) {
+        return generateMockPrimitive(resolved, propName);
+    }
+    return generateMockData(resolved, catalog, opts, visited, depth);
+}
+function generateOperationPayload(typeName, catalog) {
+    return typeName ? generateMockValue(typeName, typeName, catalog) : {};
 }
 /**
  * Generates mock request and response data for all operations in the catalog.

package/dist/util/attributeWildcards.d.ts

@@ -13,4 +13,3 @@ export declare function wildcardAttributeBagSchema(): {
         type: "string";
     };
 };
-//# sourceMappingURL=attributeWildcards.d.ts.map

package/dist/util/builder.d.ts

@@ -22,4 +22,3 @@ export declare function buildCompilerOptionsFromArgv(argv: any): Partial<Compile
  * @returns Partial OpenAPI options (excluding wsdl/catalogFile/compiledCatalog/outFile)
  */
 export declare function buildOpenApiOptionsFromArgv(argv: any, format: "json" | "yaml" | "both" | undefined, servers: string[]): Omit<GenerateOpenAPIOptions, "wsdl" | "catalogFile" | "compiledCatalog" | "outFile">;
-//# sourceMappingURL=builder.d.ts.map

package/dist/util/catalogMeta.d.ts

@@ -30,4 +30,3 @@ export declare function detectChildrenTypes(childTypeMap: Record<string, Record<
  * Recursion follows the childType map.
  */
 export declare function flattenMockPayload(data: Record<string, unknown>, typeName: string, childTypeMap: Record<string, Record<string, string>>, arrayWrappers: Record<string, string>): Record<string, unknown>;
-//# sourceMappingURL=catalogMeta.d.ts.map

package/dist/util/checkedCliDiagnostics.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Presents checked planning refusals without changing their structured report.
+ * @since Unreleased
+ */
+import type { CheckedComponentPlan } from '../checkedPlanning.js';
+/**
+ * Formats each refusal with its construct, reason and next action.
+ * @param report Diagnostic data from the unchanged native planning path.
+ * @returns Human-readable diagnostics without a stack trace or dumped report object.
+ */
+export declare function formatCheckedCliRefusal(report: CheckedComponentPlan): string;

package/dist/util/checkedCliDiagnostics.js

@@ -0,0 +1,22 @@
+/**
+ * Formats each refusal with its construct, reason and next action.
+ * @param report Diagnostic data from the unchanged native planning path.
+ * @returns Human-readable diagnostics without a stack trace or dumped report object.
+ */
+export function formatCheckedCliRefusal(report) {
+    return report.blockers.map(blocker => {
+        const location = blocker.source
+            ? `${blocker.source.path} at ${blocker.source.resource}:${blocker.source.line}:${blocker.source.column}`
+            : blocker.pointer;
+        const ambiguous = blocker.stage === 'selection' && blocker.category === 'ambiguous-selection';
+        const operations = [...new Set(blocker.affected.map(selector => selector.operation))];
+        const reason = blocker.reason === 'multiple-service-port-binding-candidates'
+            ? 'The WSDL has multiple service, port or binding choices.' : blocker.reason;
+        const choices = [...new Set(report.candidates.map(candidate => `{${candidate.service.namespace}}${candidate.service.local} / ${candidate.port}`))].join(', ');
+        const action = ambiguous
+            ? `Set service, port and selectors in a JSON file passed with --checked-config. Available choices: ${choices || 'see the planning report'}. Use --checked-report for operation candidates. Legacy mode (--model legacy) has a separate support profile.`
+            : `${blocker.action} See ${blocker.pointer}; use --checked-report to save the structured diagnostics.`;
+        return [`Checked generation refused: ${blocker.category}.`, `Construct: ${location}${operations.length ? '; operations: ' + operations.join(', ') : ''}`,
+            `Reason: ${reason}`, `Next: ${action}`].join('\n');
+    }).join('\n\n');
+}

package/dist/util/cli.d.ts

@@ -107,4 +107,3 @@ export declare function emitClientArtifacts(outDir: string, compiled: any, gener
  * @throws Error if requirements are not met
  */
 export declare function validateGatewayRequirements(gatewayDir: string | undefined, openapiFile: string | undefined, gatewayServiceName: string | undefined, gatewayVersionPrefix: string | undefined): void;
-//# sourceMappingURL=cli.d.ts.map

package/dist/util/errors.d.ts

@@ -34,4 +34,3 @@ export declare class WsdlCompilationError extends Error {
      */
     toUserMessage(): string;
 }
-//# sourceMappingURL=errors.d.ts.map

package/dist/util/imports.d.ts

@@ -14,4 +14,3 @@ export declare function getImportExtension(imports: string): string;
  * @returns {string} - Relative import specifier with proper extension
  */
 export declare function computeRelativeImport(from: string, to: string, imports: string): string;
-//# sourceMappingURL=imports.d.ts.map

package/dist/util/runtimeSource.d.ts

@@ -1,3 +1,2 @@
 export declare function loadRuntimeSource(filename: string): string;
 export declare function loadRuntimeTemplate(filename: string): string;
-//# sourceMappingURL=runtimeSource.d.ts.map