@techspokes/typescript-wsdl-client 1.1.4 → 1.1.8

package/dist/openapi/generateOpenAPI.js

@@ -27,6 +27,7 @@ import * as path from "path";
 import * as yaml from "js-yaml";
 import { loadWsdl } from "../loader/wsdlLoader.js";
 import { compileCatalog } from "../compiler/schemaCompiler.js";
+import { readLegacyCatalogFile } from "../compiler/semanticCatalog.js";
 import { generateSchemas } from "./generateSchemas.js";
 import { generatePaths } from "./generatePaths.js";
 import { error, info, warn } from "../util/cli.js";
@@ -50,8 +51,7 @@ export async function generateOpenAPI(opts) {
         compiled = opts.compiledCatalog;
     }
     else if (opts.catalogFile) {
-        const raw = fs.readFileSync(opts.catalogFile, "utf8");
-        compiled = JSON.parse(raw);
+        compiled = readLegacyCatalogFile(opts.catalogFile);
     }
     else {
         const wsdlCatalog = await loadWsdl(String(opts.wsdl));

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"> & {
@@ -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

@@ -37,6 +37,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

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/generateTests.js

@@ -12,6 +12,7 @@
  * 5. For each file: skip-if-exists check, then write
  */
 import fs from "node:fs";
+import { readLegacyCatalogFile } from "../compiler/semanticCatalog.js";
 import { writeGeneratedSource } from "../generation/writeGeneratedSource.js";
 import path from "node:path";
 import { info, success } from "../util/cli.js";
@@ -63,8 +64,7 @@ export async function generateTests(opts) {
         throw new Error(`Catalog file does not exist: ${catalogFile}`);
     }
     // Read and parse catalog
-    const catalogRaw = fs.readFileSync(catalogFile, "utf-8");
-    const catalog = JSON.parse(catalogRaw);
+    const catalog = readLegacyCatalogFile(catalogFile);
     // Resolve client metadata
     const clientMeta = resolveClientMeta({
         clientDir,

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

package/dist/util/runtimeSource.js

@@ -2,11 +2,9 @@
  * Helpers to load wsdl-tsc's own runtime modules as source text, for embedding
  * into generated client and gateway output.
  *
- * The runtime modules live at `src/runtime/*.ts` and are published alongside
- * `dist/` via the `files` field in package.json. Resolving via
- * `import.meta.url` works both in dev (tsx runs the .ts directly from src/) and
- * in a published install (generator code lives under dist/, and `../../src/runtime/…`
- * climbs to the package root where the source .ts files sit beside `dist/`).
+ * @constraints Only generation resources are published: raw streamXml.ts and runtime templates.
+ * @see package.json The files allowlist retains these resources beside dist/ for installed generation.
+ * @since Unreleased
  */
 import fs from "node:fs";
 import path from "node:path";

package/dist/util/securityConfig.d.ts

@@ -112,4 +112,3 @@ export declare function buildSecurity(cfg?: SecurityConfig): BuiltSecurity;
  * @returns True when `upstream.profile` is configured to anything other than `none`.
  */
 export declare function hasUpstreamRuntimeSecurity(cfg?: SecurityConfig): boolean;
-//# sourceMappingURL=securityConfig.d.ts.map

package/dist/util/streamConfig.d.ts

@@ -56,4 +56,3 @@ export declare function parseStreamConfig(raw: unknown, opts?: {
  * against the caller's cwd.
  */
 export declare function loadStreamConfigFile(filePath: string): StreamConfig;
-//# sourceMappingURL=streamConfig.d.ts.map

package/dist/util/tools.d.ts

@@ -118,4 +118,3 @@ export declare function explodePascal(s: string): string[];
  * @returns {string} - snake_case version of the input string
  */
 export declare function pascalToSnakeCase(s: string): string;
-//# sourceMappingURL=tools.d.ts.map

package/dist/util/xmlWhitespace.d.ts

@@ -0,0 +1,2 @@
+/** XML Schema whiteSpace mapping; only the four XML whitespace characters. */
+export declare function normalizeWhitespace(value: string, mode: "preserve" | "replace" | "collapse"): string;

package/dist/util/xmlWhitespace.js

@@ -0,0 +1,4 @@
+/** XML Schema whiteSpace mapping; only the four XML whitespace characters. */
+export function normalizeWhitespace(value, mode) {
+    return mode === "preserve" ? value : mode === "replace" ? value.replace(/[\t\r\n]/g, " ") : value.replace(/[\t\r\n ]+/g, " ").replace(/^ | $/g, "");
+}

package/dist/xsd/primitives.d.ts

@@ -38,4 +38,3 @@ export type PrimitiveOptions = {
  * @returns {string} - The corresponding TypeScript primitive type
  */
 export declare function xsdToTsPrimitive(xsdQName: string, options?: PrimitiveOptions): string;
-//# sourceMappingURL=primitives.d.ts.map

package/docs/agent-skill.md

@@ -38,6 +38,8 @@ Fluid references are generated from maintained repository docs during validation
 
 Do not maintain `agent-skill/references/` by hand. The package scripts generate packaged references under `dist/`.
 
+The extracted testing reference selects consumer setup, legacy mock patterns, generated tests and checked scaffold guidance from [Testing Guide](testing.md#for-consumer-projects). Maintainer-only Vitest grouping, repository commands, shared locks, evidence and release procedures stay outside that extraction. The npm package also ships the full guide with explicit audience routes; installation does not supply repository testing infrastructure.
+
 ## Installation
 
 Download the release ZIP from the GitHub draft or published release, extract it, and run the installer from the extracted skill folder:

package/docs/api-reference.md

@@ -44,7 +44,7 @@ declare function compileWsdlToProject(input: {
 }): Promise<void>;
 ```
 
-`streamConfigFile` points at a JSON file parsed by `loadStreamConfigFile`. `streamConfig` accepts an already-parsed value; `streamConfigFile` takes precedence when both are set. Buffered generation is unchanged when both are omitted. See [Stream Configuration](configuration.md#stream-configuration) for the file format and [ADR-002](decisions/002-streamable-responses.md) for rationale.
+`streamConfigFile` points at a JSON file parsed by `loadStreamConfigFile`. `streamConfig` accepts an already-parsed value; `streamConfigFile` takes precedence when both are set. Buffered generation is unchanged when both are omitted. See [Stream Configuration](configuration.md#stream-configuration) for the file format and [ADR-002](https://github.com/TechSpokes/typescript-wsdl-client/blob/main/docs/decisions/002-streamable-responses.md) for rationale.
 
 ### CompilerOptions