@techspokes/typescript-wsdl-client 1.4.0 → 1.4.1

package/README.md

@@ -258,6 +258,7 @@ See [CLI Reference](docs/cli-reference.md) for all flags and examples.
 | [Agent Skill Artifact](docs/agent-skill.md) | Release ZIP for consumer-project AI agents |
 | [Version Migration](docs/migration.md) | Upgrading between package versions |
 | [1.2.0 Release Notes](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/releases/v1.2.0.md) | Composition, consumer compatibility and bounded RPC qualification |
+| [1.4.1 Release Notes](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/releases/v1.4.1.md) | Composable checked OpenAPI documentation |
 | [1.4.0 Release Notes](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/releases/v1.4.0.md) | Contract corrections, offline inspection and SOAP 1.1 protocol faults |
 | [1.3.0 Release Notes](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/releases/v1.3.0.md) | Checked SOAP 1.2 execution and preserved SOAP 1.1 compatibility |
 | [XML/JSON Mapping Contract](docs/mapping-contract.md) | Checked keyed, namespace, nil and group representations |

package/dist/gateway/checkedDocumentation.d.ts

@@ -0,0 +1,14 @@
+import type { DirectOperationSelector } from '../compiler/directOperation.js';
+type Schema = Readonly<Record<string, unknown>>;
+/** Lower one issued shape while its original reference scope is still available.
+ * @param root Generator-owned shape, with at most one root resource and definition dictionary.
+ * @param selector Outer operation selector, independent of companion projection contracts.
+ * @param role Direction or declared-fault role owning the shape.
+ * @param grouped Whether published configured definition names must be preserved.
+ * @param components Destination dictionary shared by the operation document.
+ * @param check Generation cancellation and semantic resource-accounting checkpoint.
+ * @returns A new documentation schema; runtime schemas and literal annotations remain unchanged.
+ * @throws TypeError For unexpected resources, references, missing descendants or component collisions.
+ */
+export declare function lowerCheckedDocumentation(root: Schema, selector: DirectOperationSelector, role: string, grouped: boolean, components: Record<string, Schema>, check: () => void): Schema;
+export {};

package/dist/gateway/checkedDocumentation.js

@@ -0,0 +1,106 @@
+/**
+ * Relocates generator-owned shape resources into OpenAPI documentation components.
+ * @since 1.4.1
+ * @constraints This is not a general JSON Schema resource bundler.
+ */
+import { createHash } from 'node:crypto';
+const maps = new Set(['properties', 'patternProperties', 'dependentSchemas']);
+const singles = new Set(['additionalProperties', 'additionalItems', 'contains', 'not', 'if', 'then', 'else', 'propertyNames', 'unevaluatedProperties', 'unevaluatedItems']);
+const arrays = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+const escape = (value) => encodeURIComponent(value.replace(/~/g, '~0').replace(/\//g, '~1'));
+/** Lower one issued shape while its original reference scope is still available.
+ * @param root Generator-owned shape, with at most one root resource and definition dictionary.
+ * @param selector Outer operation selector, independent of companion projection contracts.
+ * @param role Direction or declared-fault role owning the shape.
+ * @param grouped Whether published configured definition names must be preserved.
+ * @param components Destination dictionary shared by the operation document.
+ * @param check Generation cancellation and semantic resource-accounting checkpoint.
+ * @returns A new documentation schema; runtime schemas and literal annotations remain unchanged.
+ * @throws TypeError For unexpected resources, references, missing descendants or component collisions.
+ */
+export function lowerCheckedDocumentation(root, selector, role, grouped, components, check) {
+    check();
+    if (root.$id !== undefined && (typeof root.$id !== 'string' || !/^urn:checked-component:shape:[a-f0-9]{64}$/.test(root.$id))) {
+        throw new TypeError('Unexpected checked documentation resource');
+    }
+    const definitions = (root.definitions ?? {});
+    // @why #467 Original resource IDs encode selection, not contract equivalence or component ownership.
+    const owner = createHash('sha256').update(JSON.stringify([selector.portType.namespace, selector.portType.local,
+        selector.binding.namespace, selector.binding.local, selector.operation, role])).digest('hex');
+    const names = new Map(Object.keys(definitions).sort().map(name => [name, grouped ? name : `Checked_${owner}_${name}`]));
+    const reference = (value) => {
+        if (typeof value !== 'string' || !value.startsWith('#/definitions/'))
+            throw new TypeError('Unexpected checked documentation reference');
+        let pointer;
+        try {
+            pointer = decodeURIComponent(value.slice(1));
+        }
+        catch {
+            throw new TypeError('Invalid checked documentation pointer');
+        }
+        const parts = pointer.slice(1).split('/').map(part => {
+            if (/~(?![01])/.test(part))
+                throw new TypeError('Invalid checked documentation pointer');
+            return part.replace(/~1/g, '/').replace(/~0/g, '~');
+        });
+        const name = names.get(parts[1]);
+        if (!name)
+            throw new TypeError('Unresolved checked documentation definition');
+        let target = root;
+        for (const part of parts) {
+            check();
+            if (!target || typeof target !== 'object' || !Object.hasOwn(target, part))
+                throw new TypeError('Unresolved checked documentation descendant');
+            target = target[part];
+        }
+        if (typeof target !== 'boolean' && (!target || typeof target !== 'object' || Array.isArray(target))) {
+            throw new TypeError('Checked documentation reference must target a schema');
+        }
+        return '#/components/schemas/' + escape(name) + parts.slice(2).map(part => '/' + escape(part)).join('');
+    };
+    const visit = (value, isRoot = false) => {
+        check();
+        if (typeof value === 'boolean')
+            return value;
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new TypeError('Unexpected checked documentation schema');
+        const record = value, result = Object.create(null);
+        for (const [key, item] of Object.entries(record)) {
+            check();
+            if (key === '$id' && isRoot)
+                continue;
+            if (key === 'definitions' && isRoot)
+                continue;
+            if (['$id', '$anchor', '$dynamicAnchor', '$dynamicRef', '$recursiveRef', '$recursiveAnchor', '$defs', 'definitions'].includes(key)) {
+                throw new TypeError('Unexpected checked documentation resource');
+            }
+            if (key === '$ref')
+                result[key] = reference(item);
+            else if (maps.has(key) || key === 'dependencies') {
+                const dictionary = Object.create(null);
+                for (const [name, child] of Object.entries(item)) {
+                    check();
+                    dictionary[name] = key === 'dependencies' && Array.isArray(child) ? child : visit(child);
+                }
+                result[key] = dictionary;
+            }
+            else if (arrays.has(key) || key === 'items' && Array.isArray(item))
+                result[key] = item.map(child => visit(child));
+            else if (singles.has(key) || key === 'items')
+                result[key] = visit(item);
+            // @constraints Unknown annotations are literal data, including keyword-shaped application examples.
+            else
+                result[key] = item;
+        }
+        return result;
+    };
+    const lowered = visit(root, true);
+    for (const [original, name] of names) {
+        const resolved = visit(definitions[original]);
+        if (Object.hasOwn(components, name) && JSON.stringify(components[name]) !== JSON.stringify(resolved)) {
+            throw new TypeError(`applicationGroups OpenAPI component collision ${name}`);
+        }
+        components[name] = resolved;
+    }
+    return lowered;
+}

package/dist/gateway/generateCheckedGateway.js

@@ -7,6 +7,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { componentSourceCapsuleBytes, inspectReconstructedComponentSource, inspectComponentSourceService } from '../compiler/directSourceCapsule.js';
 import { lowerComponentShape } from '../generation/componentShape.js';
+import { lowerCheckedDocumentation } from './checkedDocumentation.js';
 import { checkSemanticBudget } from '../compiler/semanticBudget.js';
 import { inspectDirectOperation } from '../compiler/directOperation.js';
 import { inspectComponentValueMapping } from '../compiler/directValues.js';
@@ -31,15 +32,21 @@ async function generateGatewayFromReconstruction(expected, options) {
     const output = expected.mappings.find(mapping => mapping.direction.kind === 'output');
     if (!input || !output)
         throw new TypeError('Issued input and output mappings required');
-    const schema = (mapping, role) => {
-        const { budget } = inspectDirectOperation(expected.contract).context;
-        return lowerComponentShape(expected.contract, mapping, role, () => {
-            checkSemanticBudget(budget);
-            if (options.signal?.aborted)
-                throw new Error('Checked gateway generation cancelled');
-        }).schema;
+    const { budget } = inspectDirectOperation(expected.contract).context;
+    const check = () => {
+        checkSemanticBudget(budget);
+        if (options.signal?.aborted)
+            throw new Error('Checked gateway generation cancelled');
     };
+    const schema = (mapping, role) => lowerComponentShape(expected.contract, mapping, role, check).schema;
+    const components = Object.create(null);
+    const documented = (value, mapping, role) => lowerCheckedDocumentation(value, expected.contract.selector, role, mapping.kind === 'component-mapping'
+        && !!inspectComponentValueMapping(mapping, expected.contract).applicationGroups, components, () => {
+        budget.chargeWork();
+        check();
+    });
     const request = schema(input, 'Request'), response = schema(output, 'Response');
+    const documentation = { request: documented(request, input, 'Request'), response: documented(response, output, 'Response') };
     const soap12 = expected.contract.binding.version === '1.2';
     const nameSchema = { type: 'object', additionalProperties: false, required: ['namespace', 'local'],
         properties: { namespace: { type: 'string' }, local: { type: 'string' } } };
@@ -53,12 +60,14 @@ async function generateGatewayFromReconstruction(expected, options) {
     const faults = expected.mappings.filter(mapping => mapping.direction.kind === 'fault').map(mapping => {
         if (mapping.direction.kind !== 'fault')
             throw new TypeError('Declared fault mapping required');
-        return { name: mapping.direction.name, value: schema(mapping, `Fault_${expected.mappings.filter(item => item.direction.kind === 'fault').indexOf(mapping)}`) };
+        const role = `Fault_${expected.mappings.filter(item => item.direction.kind === 'fault').indexOf(mapping)}`;
+        const value = schema(mapping, role);
+        return { name: mapping.direction.name, value, documented: documented(value, mapping, role) };
     });
-    const faultVariants = faults.map(fault => ({
+    const faultVariants = (documentationOnly) => faults.map(fault => ({
         type: 'object', additionalProperties: false, required: ['fault', 'value'],
         properties: {
-            value: fault.value,
+            value: documentationOnly ? fault.documented : fault.value,
             fault: {
                 type: 'object', additionalProperties: false, required: ['name', 'code', 'string', ...(soap12 ? ['version', 'subcodes', 'reasons'] : [])],
                 properties: soap12 ? { ...protocolFaultProperties, name: { const: fault.name } } : {
@@ -69,48 +78,17 @@ async function generateGatewayFromReconstruction(expected, options) {
             },
         },
     }));
-    faultVariants.push({ type: 'object', additionalProperties: false, required: ['fault'], properties: {
+    const protocolFault = { type: 'object', additionalProperties: false, required: ['fault'], properties: {
             fault: { type: 'object', additionalProperties: false, required: ['version', 'code', 'string', ...(soap12 ? ['subcodes', 'reasons'] : [])],
                 properties: soap12 ? protocolFaultProperties : { version: { const: '1.1' }, code: nameSchema, string: { type: 'string' }, actor: { type: 'string' } } },
-        } });
-    const fault = { oneOf: faultVariants };
+        } };
+    const fault = { oneOf: [...faultVariants(false), protocolFault] };
+    const documentedFault = { oneOf: [...faultVariants(true), protocolFault] };
     const schemas = { request: { $schema: draft07, ...request }, response: { $schema: draft07, ...response }, fault: { $schema: draft07, ...fault } };
-    const grouped = expected.mappings.some(mapping => mapping.kind === 'component-mapping'
-        && inspectComponentValueMapping(mapping, expected.contract).applicationGroups);
-    const components = Object.create(null);
-    const documented = (value, dictionary = false) => {
-        if (Array.isArray(value))
-            return value.map(item => documented(item));
-        if (!value || typeof value !== 'object')
-            return value;
-        const record = value, result = Object.create(null);
-        // @why Property names belong to the application; definitions and $id are keywords only at schema nodes.
-        if (dictionary) {
-            for (const [key, item] of Object.entries(record))
-                result[key] = documented(item);
-            return result;
-        }
-        if (Object.hasOwn(record, 'definitions'))
-            for (const [key, definition] of Object.entries(record.definitions)) {
-                const resolved = documented(definition);
-                if (components[key] && JSON.stringify(components[key]) !== JSON.stringify(resolved))
-                    throw new TypeError(`applicationGroups OpenAPI component collision ${key}`);
-                components[key] = resolved;
-            }
-        for (const [key, item] of Object.entries(record)) {
-            if (key === 'definitions' || key === '$id')
-                continue;
-            result[key] = ['const', 'enum', 'default', 'examples'].includes(key) ? item
-                : key === '$ref' && typeof item === 'string' && item.startsWith('#/definitions/') ? item.replace('#/definitions/', '#/components/schemas/')
-                    : documented(item, ['properties', 'patternProperties', 'dependencies', 'dependentSchemas'].includes(key));
-        }
-        return result;
-    };
-    const documentation = grouped ? { request: documented(request), response: documented(response), fault: documented(fault) } : { request, response, fault };
     const doc = {
         openapi: '3.1.1', jsonSchemaDialect: 'https://json-schema.org/draft/2020-12/schema',
         info: { title: expected.selection.service.local, version: '1.0.0' },
-        ...(grouped ? { components: { schemas: components } } : {}),
+        ...(Object.keys(components).length ? { components: { schemas: components } } : {}),
         'x-checked-model': { model: 'checked-components-v1', scope: soap12 ? 'native-component-structured-soap12' : 'native-component-structured-soap11',
             ...(expected.responseProjection
                 ? { responseProjection: { spec: expected.responseProjection.spec, delivery: 'buffered', retainedValue: 'complete-companion-payload' } } : {}),
@@ -123,7 +101,7 @@ async function generateGatewayFromReconstruction(expected, options) {
                     requestBody: { required: true, content: { 'application/json': { schema: documentation.request } } },
                     responses: { '200': { description: 'Independently validated SOAP response', content: { 'application/json': { schema: documentation.response } } },
                         '400': { description: 'Invalid HTTP request; no SOAP request is dispatched' },
-                        '502': { description: 'SOAP fault or refused upstream response', content: { 'application/json': { schema: { oneOf: [documentation.fault,
+                        '502': { description: 'SOAP fault or refused upstream response', content: { 'application/json': { schema: { oneOf: [documentedFault,
                                             { type: 'object', additionalProperties: false, required: ['kind', 'rule'], properties: { kind: { type: 'string' }, rule: { type: 'string' } } }] } } } },
                         '500': { description: 'Incompatible artifacts or gateway configuration' } } } } },
     };

package/docs/api-reference.md

@@ -362,6 +362,8 @@ The generated aggregate plugin exports `createClients`, `MultiServiceClientOptio
 
 Compose existing OpenAPI 3.1 documents without generating clients or routers:
 
+Checked documents regenerated with 1.4.1 or later support this API. Regeneration relocates generator-owned local schema resources while preserving configured names and native supplemental-validation metadata. Archived resource-bearing documents remain unsupported; composition does not replace native XML validation.
+
 ```typescript
 interface OpenApiCompositionEntry {key: string; document: unknown}
 interface OpenApiCompositionOptions {

package/docs/checked-gateway.md

@@ -255,6 +255,10 @@ Generated `buildServer` accepts runtime cancellation, timeout and XML limits. Or
 
 ## Validation and coverage evidence
 
+Regenerate with 1.4.1 or later to compose checked OpenAPI documents through `composeOpenApiDocuments`. Documentation definitions are relocated into operation- and role-scoped components for ungrouped shapes; configured grouped names remain unchanged. Runtime draft-07 schemas, capsules and native supplemental validation retain their existing contracts.
+
+Composition preserves structural JSON documentation, not complete native XML equivalence. Archived 1.4.0 documents with embedded schema resources still refuse composition; updating the runtime package alone does not repair those documents.
+
 OpenAPI documentation uses 3.1.1 with separate draft-07 HTTP runtime plans. Route-local Ajv disables coercion, default insertion and property removal, and preserves unrelated host policy. The native runtime explicitly converts validated HTTP values through the issued mapping, performs actual SOAP execution and independently validates response/fault XML. HTTP response validation also runs independently of serializer selection; JSON serialization preserves the validated values.
 
 `client/inventory.json` and the API result's `checked` field list every discovered portType operation, selected service/port/binding, requested/generated operation and unselected operations. Generation records `executed:false`; it does not claim a SOAP call occurred. Refused selection diagnostics name the requested operation and zero generated/executed operations. Unselected operations remain unassessed.

package/docs/migration.md

@@ -6,6 +6,12 @@ Versions are listed newest first. Find your current version and follow the steps
 
 See the root [README](../README.md). Historical version sections below describe their original releases; 1.2.0 compatibility guidance supersedes earlier unchanged-output statements for this upgrade.
 
+## From 1.4.0 to 1.4.1
+
+Regenerate checked specifications to compose them with `composeOpenApiDocuments`. Ungrouped documentation uses operation- and role-scoped components; configured grouped names remain stable. Archived 1.4.0 specifications containing embedded resources remain explicitly refused by composition.
+
+Existing runtime artifacts remain usable. Runtime draft-07 validation, capsules and native supplemental validation are unchanged; structural documentation parity does not establish complete native XML equivalence.
+
 ## General Upgrade Steps
 
 These steps apply to every version upgrade:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Turn legacy WSDL/SOAP services into typed TypeScript clients, OpenAPI 3.1 specs, and production-ready Fastify REST gateways. Built for enterprise SOAP modernization.",
   "keywords": [
     "wsdl",