@wirebench/engine 2.1.1

package/dist/import-detect.js

@@ -0,0 +1,169 @@
+/**
+ * Format detection for API definition imports: WSDL, OpenAPI / Swagger, Postman Collections,
+ * Protocol Buffers (`.proto`) and legacy single-XML SOAP projects.
+ *
+ * Inspects document text, file names, or URLs to classify definition formats before or during import.
+ */
+import { parse as parseYamlDocument } from 'yaml';
+import { isPostmanCollection } from './rest/postman/parse.js';
+import { looksLikeLegacyProject } from './soap/legacy-project/format.js';
+const WSDL_XML_REGEX = /<(?:[a-zA-Z0-9_-]+:)?definitions[\s>]/i;
+/** The statement a `.proto` opens with, once its leading comments are gone. */
+const PROTO_SYNTAX_REGEX = /^(?:syntax\s*=\s*["']proto[23]["']|edition\s*=\s*["']\d{4}["'])\s*;/;
+/**
+ * `text` with the whitespace and `//` / `/* *\/` comments a `.proto` may open with removed, by a
+ * linear scan: a regex with a repeated comment group backtracks badly on crafted input.
+ */
+export function stripLeadingProtoComments(text) {
+    let index = 0;
+    for (;;) {
+        while (index < text.length && /\s/.test(text[index] ?? ''))
+            index += 1;
+        if (text.startsWith('//', index)) {
+            const end = text.indexOf('\n', index);
+            if (end === -1)
+                return '';
+            index = end + 1;
+            continue;
+        }
+        if (text.startsWith('/*', index)) {
+            const end = text.indexOf('*/', index + 2);
+            if (end === -1)
+                return '';
+            index = end + 2;
+            continue;
+        }
+        return text.slice(index);
+    }
+}
+const PROTO_KEYWORD_REGEX = /^\s*(?:package\s+[\w.]+\s*;|import\s+"[^"]+\.proto"\s*;|service\s+\w+\s*\{|message\s+\w+\s*\{)/m;
+const WSDL_NS_REGEX = /xmlns(?::[a-zA-Z0-9_-]+)?=["']http:\/\/(?:schemas\.xmlsoap\.org\/wsdl|www\.w3\.org\/ns\/wsdl)/i;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Detects the API definition format from text content, filename, or URL.
+ */
+export function detectImportFormat(input) {
+    const text = input.text?.trim();
+    if (text !== undefined && text.length > 0) {
+        // 0. A .proto file: a syntax statement, or the keywords nothing else opens with
+        const protoHead = stripLeadingProtoComments(text);
+        if (PROTO_SYNTAX_REGEX.test(protoHead)) {
+            const edition = protoHead.startsWith('edition')
+                ? 'editions'
+                : /^syntax\s*=\s*["']proto2/.test(protoHead)
+                    ? 'proto2'
+                    : 'proto3';
+            return { kind: 'proto', label: `Protocol Buffers (${edition})`, confidence: 'definite' };
+        }
+        if (PROTO_KEYWORD_REGEX.test(text) && !text.startsWith('<') && !text.startsWith('{')) {
+            return { kind: 'proto', label: 'Protocol Buffers', confidence: 'probable' };
+        }
+        // 1. A legacy SOAP project, before WSDL: it carries its interfaces' WSDLs inside it
+        if (text.startsWith('<') && looksLikeLegacyProject(text)) {
+            return { kind: 'legacy-soap-project', label: 'Legacy SOAP project', confidence: 'definite' };
+        }
+        // 2. Check for WSDL (XML)
+        if (text.startsWith('<') || text.startsWith('<?xml')) {
+            if (WSDL_XML_REGEX.test(text) || WSDL_NS_REGEX.test(text)) {
+                return { kind: 'wsdl', label: 'WSDL / SOAP', confidence: 'definite' };
+            }
+        }
+        // 3. Try JSON or YAML parsing once (avoiding duplicate parsing work)
+        let parsed;
+        let didParse = false;
+        if (text.startsWith('{') || text.startsWith('[')) {
+            try {
+                parsed = JSON.parse(text);
+                didParse = true;
+            }
+            catch {
+                // Fall through to YAML parse or regex
+            }
+        }
+        if (!didParse) {
+            try {
+                parsed = parseYamlDocument(text);
+                didParse = true;
+            }
+            catch {
+                // Fall through to pattern matching
+            }
+        }
+        if (didParse && isRecord(parsed)) {
+            if (isPostmanCollection(parsed)) {
+                const info = isRecord(parsed['info']) ? parsed['info'] : undefined;
+                const schema = typeof info?.['schema'] === 'string' ? info['schema'] : undefined;
+                const isV21 = schema?.includes('v2.1') ?? false;
+                return {
+                    kind: 'postman',
+                    label: isV21 ? 'Postman Collection v2.1' : 'Postman Collection',
+                    confidence: 'definite',
+                };
+            }
+            if (typeof parsed['openapi'] === 'string') {
+                return {
+                    kind: 'openapi',
+                    label: `OpenAPI ${parsed['openapi']}`,
+                    confidence: 'definite',
+                };
+            }
+            if (typeof parsed['swagger'] === 'string') {
+                return {
+                    kind: 'openapi',
+                    label: `Swagger ${parsed['swagger']}`,
+                    confidence: 'definite',
+                };
+            }
+            if (typeof parsed['swaggerVersion'] === 'string') {
+                return {
+                    kind: 'openapi',
+                    label: `Swagger ${parsed['swaggerVersion']}`,
+                    confidence: 'definite',
+                };
+            }
+        }
+        // 4. Pattern matching fallback on raw text
+        if (/^\s*openapi\s*:\s*['"]?3\.[012]/m.test(text)) {
+            return { kind: 'openapi', label: 'OpenAPI 3.x', confidence: 'probable' };
+        }
+        if (/^\s*swagger(?:Version)?\s*:\s*['"]?[123]\./m.test(text)) {
+            return { kind: 'openapi', label: 'Swagger', confidence: 'probable' };
+        }
+        if (text.includes('schema.getpostman.com/json/collection')) {
+            return { kind: 'postman', label: 'Postman Collection', confidence: 'probable' };
+        }
+        if (WSDL_XML_REGEX.test(text) || WSDL_NS_REGEX.test(text)) {
+            return { kind: 'wsdl', label: 'WSDL / SOAP', confidence: 'definite' };
+        }
+    }
+    // Check by filename or URL (treating empty string as absent)
+    const candidate = input.filename !== undefined && input.filename.trim().length > 0
+        ? input.filename.trim()
+        : input.url !== undefined && input.url.trim().length > 0
+            ? input.url.trim()
+            : undefined;
+    if (candidate !== undefined) {
+        const target = candidate.toLowerCase();
+        if (target.endsWith('.proto')) {
+            return { kind: 'proto', label: 'Protocol Buffers', confidence: 'probable' };
+        }
+        if (target.endsWith('.wsdl') ||
+            target.includes('?wsdl') ||
+            target.includes('&wsdl') ||
+            target.endsWith('.wsdl.xml')) {
+            return { kind: 'wsdl', label: 'WSDL / SOAP', confidence: 'probable' };
+        }
+        if (target.includes('postman_collection') || target.endsWith('.postman.json')) {
+            return { kind: 'postman', label: 'Postman Collection', confidence: 'probable' };
+        }
+        if (target.includes('openapi') ||
+            target.includes('swagger') ||
+            target.endsWith('.yaml') ||
+            target.endsWith('.yml')) {
+            return { kind: 'openapi', label: 'OpenAPI / Swagger', confidence: 'probable' };
+        }
+    }
+    return { kind: 'unknown', label: 'Auto-detect', confidence: 'unknown' };
+}

package/dist/import.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Imports a WSDL definition end to end: resolve its import graph, parse the
+ * merged WSDL, compile the schema set, and summarize the operations a user
+ * can pick from.
+ */
+import type { ImportOptions, ImportResult, ImportSource } from './types.js';
+/**
+ * Imports a WSDL definition from a URL, file path, or inline text: resolves
+ * its full import graph, parses the merged WSDL, compiles the schema set,
+ * and summarizes its operations for a picker UI.
+ *
+ * Never throws for a modelling problem in the definition itself — those are
+ * reported in {@link ImportResult.problems}. It does throw for a malformed
+ * `ImportSource` (an invalid URL) or when the root document cannot be
+ * fetched at all.
+ *
+ * @param source where the WSDL comes from
+ * @param options fetch override, Basic auth for fetching, abort signal, progress callback, definition cache
+ */
+export declare function importDefinition(source: ImportSource, options?: ImportOptions): Promise<ImportResult>;

package/dist/import.js

@@ -0,0 +1,163 @@
+/**
+ * Imports a WSDL definition end to end: resolve its import graph, parse the
+ * merged WSDL, compile the schema set, and summarize the operations a user
+ * can pick from.
+ */
+import { pathToFileURL } from 'node:url';
+import { HttpError, ProjectError, WsdlParseError } from './errors.js';
+import { summarizeOperations } from './operations.js';
+import { summarizeWsa } from './wsa/policy-detect.js';
+import { readDefinitionCache, writeDefinitionCache } from './wsdl/cache.js';
+import { createDefaultFetchDocument } from './wsdl/fetch.js';
+import { parseWsdlBundle } from './wsdl/merge.js';
+import { resolveDefinition } from './wsdl/resolver.js';
+import { buildSchemaSet } from './xsd/schema-set.js';
+/** Turns an {@link ImportSource} into the `DefinitionSource` the resolver understands. */
+function toDefinitionSource(source) {
+    if (source.kind === 'file') {
+        return { location: pathToFileURL(source.path).href };
+    }
+    if (source.kind === 'text') {
+        return { location: source.location ?? 'inline:wsdl', text: source.text };
+    }
+    try {
+        return { location: new URL(source.url).toString() };
+    }
+    catch (cause) {
+        throw new WsdlParseError('invalid-url', `"${source.url}" is not a valid URL`, {
+            cause,
+            details: { url: source.url },
+        });
+    }
+}
+/** Wraps `fetchDocument` to add HTTP Basic auth to every `http(s)://` fetch. */
+function withBasicAuth(fetchDocument, auth) {
+    const header = `Basic ${Buffer.from(`${auth.username}:${auth.password}`).toString('base64')}`;
+    return async (location, signal) => {
+        if (!location.startsWith('http:') && !location.startsWith('https:')) {
+            return fetchDocument(location, signal);
+        }
+        const response = await fetch(location, {
+            redirect: 'follow',
+            ...(signal !== undefined ? { signal } : {}),
+            headers: { authorization: header, 'user-agent': 'wirebench/0.1' },
+        });
+        if (!response.ok) {
+            throw new HttpError('fetch-failed', `GET ${location} failed with status ${response.status}`, {
+                details: { location, status: response.status },
+            });
+        }
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        return { location: response.url, bytes, text: new TextDecoder('utf-8').decode(bytes) };
+    };
+}
+/** Resolves from the network, honoring the optional abort signal. */
+function resolveFromNetwork(definitionSource, fetchDocument, signal) {
+    return resolveDefinition(definitionSource, {
+        fetchDocument,
+        ...(signal !== undefined ? { signal } : {}),
+    });
+}
+/**
+ * Writes `bundle` to the definition cache. A failure here never aborts the
+ * import (the caller already has a usable bundle from the network) — it is
+ * reported as a `definition-cache-write-failed` problem instead.
+ */
+async function writeCacheSafely(bundle, dir, cacheProblems) {
+    try {
+        await writeDefinitionCache(bundle, dir);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        cacheProblems.push({ source: 'resolve', code: 'definition-cache-write-failed', message });
+    }
+}
+/**
+ * Resolves the definition per `cache.mode`:
+ * - `'prefer-cache'`: reads the cache with no network access. A missing
+ *   cache (`definition-cache-missing`) falls back to the network silently
+ *   (no problem reported) and then writes the cache. A corrupt cache
+ *   (`definition-cache-corrupt`) falls back to the network too, but reports
+ *   a problem, and then rewrites the cache. A valid cache is used as-is,
+ *   fully offline, with `fromCache: true`.
+ * - `'refresh'`: always resolves from the network, then (re)writes the cache.
+ * - `'none'`/absent: resolves from the network without touching any cache.
+ *
+ * A cache-write failure in any of the above is reported as a
+ * `definition-cache-write-failed` problem; the import itself still succeeds.
+ */
+async function resolveWithCache(definitionSource, fetchDocument, signal, cache, cacheProblems) {
+    if (cache === undefined || cache.mode === 'none') {
+        const bundle = await resolveFromNetwork(definitionSource, fetchDocument, signal);
+        return { bundle, fromCache: false };
+    }
+    if (cache.mode === 'prefer-cache') {
+        try {
+            const bundle = await readDefinitionCache(cache.dir);
+            return { bundle, fromCache: true };
+        }
+        catch (error) {
+            if (!(error instanceof ProjectError)) {
+                throw error;
+            }
+            if (error.code === 'definition-cache-corrupt') {
+                cacheProblems.push({
+                    source: 'resolve',
+                    code: error.code,
+                    message: error.message,
+                    location: definitionSource.location,
+                });
+            }
+            const bundle = await resolveFromNetwork(definitionSource, fetchDocument, signal);
+            await writeCacheSafely(bundle, cache.dir, cacheProblems);
+            return { bundle, fromCache: false };
+        }
+    }
+    // 'refresh'
+    const bundle = await resolveFromNetwork(definitionSource, fetchDocument, signal);
+    await writeCacheSafely(bundle, cache.dir, cacheProblems);
+    return { bundle, fromCache: false };
+}
+/**
+ * Imports a WSDL definition from a URL, file path, or inline text: resolves
+ * its full import graph, parses the merged WSDL, compiles the schema set,
+ * and summarizes its operations for a picker UI.
+ *
+ * Never throws for a modelling problem in the definition itself — those are
+ * reported in {@link ImportResult.problems}. It does throw for a malformed
+ * `ImportSource` (an invalid URL) or when the root document cannot be
+ * fetched at all.
+ *
+ * @param source where the WSDL comes from
+ * @param options fetch override, Basic auth for fetching, abort signal, progress callback, definition cache
+ */
+export async function importDefinition(source, options) {
+    const signal = options?.signal;
+    const baseFetch = options?.fetchDocument ?? createDefaultFetchDocument();
+    const fetchDocument = options?.auth !== undefined ? withBasicAuth(baseFetch, options.auth) : baseFetch;
+    const definitionSource = toDefinitionSource(source);
+    options?.onProgress?.({ phase: 'fetch', location: definitionSource.location });
+    const cacheProblems = [];
+    const { bundle, fromCache } = await resolveWithCache(definitionSource, fetchDocument, signal, options?.cache, cacheProblems);
+    options?.onProgress?.({ phase: 'parse' });
+    const definition = parseWsdlBundle(bundle);
+    options?.onProgress?.({ phase: 'schema' });
+    const schemaSet = buildSchemaSet(bundle);
+    const problems = [
+        ...cacheProblems,
+        ...bundle.problems.map((p) => ({ source: 'resolve', ...p })),
+        ...definition.problems.map((p) => ({ source: 'wsdl', ...p })),
+        ...schemaSet.problems.map((p) => ({ source: 'schema', ...p })),
+    ];
+    const operations = summarizeOperations(definition);
+    options?.onProgress?.({ phase: 'done' });
+    return {
+        definition,
+        bundle,
+        schemaSet,
+        problems,
+        operations,
+        wsa: summarizeWsa(definition),
+        ...(fromCache ? { fromCache: true } : {}),
+    };
+}