@wirebench/engine 2.1.1

package/dist/rest/openapi/sample.js

@@ -0,0 +1,336 @@
+/**
+ * Turning a JSON Schema into a body a user can send.
+ *
+ * The generator is deliberately dull and deterministic: the same schema always produces the same
+ * sample, so an imported request is reviewable and a golden test means something. It answers one
+ * question per node — "what is the most specific thing this schema says a value looks like?" — and
+ * takes the first answer it finds: an `example`, then a `default`, then a `const`, then the first
+ * `enum` member, then the type's own empty value.
+ *
+ * Three rules keep the output usable rather than merely correct:
+ *
+ * - **Required properties are always present, optional ones follow the preference.** A body missing a
+ *   required field is a request that cannot succeed, so it is never generated that way.
+ * - **A composition is not a puzzle to solve.** `allOf` is merged (its whole point), and `oneOf` and
+ *   `anyOf` take their first branch — picking "the right one" needs an intent the document does not
+ *   carry, and a body from the first branch is one the user can see and change.
+ * - **Depth is capped**, and a `$ref` the resolver left in place is a cut. A self-referencing schema
+ *   is normal in a description, so it has to end in a finite document rather than a stack overflow.
+ */
+/** How deep generation goes before it stops and emits `null`. */
+export const MAX_SAMPLE_DEPTH = 8;
+/**
+ * How many values one sample may contain before generation stops adding to it.
+ *
+ * The depth cap alone is not a bound: a resolved description is a *graph*, not a tree — a `$ref` to a
+ * shared schema is one object reachable from many places — so a document whose schemas reference each
+ * other reaches `breadth ^ depth` nodes, which for a realistic 20-property schema is billions at
+ * depth 8. A total budget makes generation linear in the size of what it produces, whatever shape the
+ * schema graph has. Required properties are still emitted first, so what a truncated sample keeps is
+ * the part a request cannot go without.
+ */
+export const MAX_SAMPLE_NODES = 2_000;
+/** The placeholder values a `format` maps to, used only when `sampleValues` is on. */
+const FORMAT_VALUES = {
+    'date-time': '2026-01-01T00:00:00Z',
+    date: '2026-01-01',
+    time: '00:00:00Z',
+    duration: 'P1D',
+    uuid: '00000000-0000-4000-8000-000000000000',
+    email: 'user@example.com',
+    hostname: 'example.com',
+    uri: 'https://example.com',
+    'uri-reference': '/path',
+    ipv4: '192.0.2.1',
+    ipv6: '2001:db8::1',
+    password: 'secret',
+    byte: 'AA==',
+    binary: '',
+};
+/** Every type a schema declares, as a set — 3.1 allows a list, which is how it spells nullable. */
+function typesOf(schema) {
+    const declared = schema.type;
+    if (declared === undefined) {
+        return new Set();
+    }
+    return new Set(typeof declared === 'string' ? [declared] : declared);
+}
+/** Whether the schema says a value may be `null`, in either specification's spelling. */
+function isNullable(schema) {
+    return schema.nullable === true || typesOf(schema).has('null');
+}
+/** The type to generate for, ignoring `null` — which is an alternative, not a shape. */
+function effectiveType(schema) {
+    for (const type of typesOf(schema)) {
+        if (type !== 'null') {
+            return type;
+        }
+    }
+    // No `type` at all: a schema with properties is an object, one with items an array. This is what
+    // a reader would assume, and documents in the wild leave `type` out constantly.
+    if (schema.properties !== undefined || schema.additionalProperties !== undefined) {
+        return 'object';
+    }
+    if (schema.items !== undefined) {
+        return 'array';
+    }
+    return undefined;
+}
+/**
+ * The value a schema states outright, if any: `example`, `default`, `const`, or its first `enum`.
+ *
+ * 3.1's `examples` array is read too, first entry first, because that is the only spelling a 3.1
+ * document has.
+ */
+function statedValue(schema) {
+    if (schema.example !== undefined) {
+        return schema.example;
+    }
+    if (schema.examples !== undefined && schema.examples.length > 0) {
+        return schema.examples[0];
+    }
+    if (schema.default !== undefined) {
+        return schema.default;
+    }
+    if (schema.const !== undefined) {
+        return schema.const;
+    }
+    if (schema.enum !== undefined && schema.enum.length > 0) {
+        return schema.enum[0];
+    }
+    return undefined;
+}
+/** A copy of a schema without the keywords the caller has already accounted for. */
+function without(schema, ...keys) {
+    const copy = { ...schema };
+    for (const key of keys) {
+        delete copy[key];
+    }
+    return copy;
+}
+/** The schema an `allOf` amounts to: every branch merged, later branches filling in blanks. */
+function mergeAllOf(schema) {
+    if (schema.allOf === undefined || schema.allOf.length === 0) {
+        return schema;
+    }
+    let properties = { ...schema.properties };
+    let required = [...(schema.required ?? [])];
+    let merged = { ...schema };
+    for (const branch of schema.allOf) {
+        const flattened = mergeAllOf(branch);
+        properties = { ...properties, ...flattened.properties };
+        required = [...required, ...(flattened.required ?? [])];
+        merged = { ...flattened, ...merged };
+    }
+    return {
+        ...without(merged, 'allOf'),
+        ...(Object.keys(properties).length > 0 ? { properties } : {}),
+        ...(required.length > 0 ? { required: [...new Set(required)] } : {}),
+    };
+}
+/** The branch a `oneOf`/`anyOf` generates from: the first, merged with whatever sits beside it. */
+function firstBranch(schema) {
+    const branch = schema.oneOf?.[0] ?? schema.anyOf?.[0];
+    if (branch === undefined) {
+        return schema;
+    }
+    return mergeAllOf({
+        ...branch,
+        ...without(schema, 'oneOf', 'anyOf'),
+        ...(branch.properties !== undefined ? { properties: branch.properties } : {}),
+    });
+}
+/**
+ * A sample value for one schema.
+ *
+ * @param schema the schema, with its references already inlined (see `refs.ts`)
+ * @returns a JSON value — `null` where generation had to stop
+ */
+export function sampleFromSchema(schema, options = {}) {
+    return generate(schema, options, options.maxDepth ?? MAX_SAMPLE_DEPTH, {
+        remaining: options.maxNodes ?? MAX_SAMPLE_NODES,
+    });
+}
+function generate(input, options, depth, nodes) {
+    // A reference the resolver could not follow, or cut as a cycle: there is nothing to generate from,
+    // and `null` is the honest answer. The same answer the depth cap gives, for the same reason.
+    if (input.$ref !== undefined && input.type === undefined && input.properties === undefined) {
+        return null;
+    }
+    if (nodes.remaining <= 0) {
+        return null;
+    }
+    // Charged before the depth check as well, so *every* value this function returns costs exactly one
+    // — including the `null` the depth cap emits. That is what makes the budget an exact bound on the
+    // size of the sample rather than a bound on its objects alone.
+    nodes.remaining -= 1;
+    if (depth <= 0) {
+        return null;
+    }
+    const schema = firstBranch(mergeAllOf(input));
+    const stated = statedValue(schema);
+    if (stated !== undefined) {
+        return stated;
+    }
+    switch (effectiveType(schema)) {
+        case 'object':
+            return generateObject(schema, options, depth, nodes);
+        case 'array':
+            return generateArray(schema, options, depth, nodes);
+        case 'string':
+            return generateString(schema, options);
+        case 'integer':
+        case 'number':
+            return 0;
+        case 'boolean':
+            return false;
+        case 'null':
+            return null;
+        default:
+            // A schema with no type and no shape says nothing at all about its value. `null` says that,
+            // where `{}` or `""` would claim something the document never did.
+            return isNullable(schema) ? null : null;
+    }
+}
+function generateObject(schema, options, depth, nodes) {
+    const required = new Set(schema.required ?? []);
+    const out = {};
+    // Required properties first, so a sample cut short by the budget still carries what a request
+    // cannot be sent without.
+    const names = Object.keys(schema.properties ?? {}).sort((left, right) => Number(required.has(right)) - Number(required.has(left)));
+    for (const name of names) {
+        const property = schema.properties?.[name];
+        if (property === undefined) {
+            continue;
+        }
+        // A read-only property is one the server sends back, never one the client sends, so a generated
+        // request body leaves it out even when the schema requires it in a response.
+        if (property.readOnly === true) {
+            continue;
+        }
+        if (!required.has(name) && options.includeOptional !== true) {
+            continue;
+        }
+        if (nodes.remaining <= 0) {
+            break;
+        }
+        out[name] = generate(property, options, depth - 1, nodes);
+    }
+    // A free-form object (`additionalProperties` with no `properties`) has nothing nameable in it, so
+    // it stays empty rather than inventing a key.
+    return out;
+}
+function generateArray(schema, options, depth, nodes) {
+    if (schema.items === undefined) {
+        return [];
+    }
+    // One item: enough to show the shape, few enough to edit. More would only be guessing.
+    return [generate(schema.items, options, depth - 1, nodes)];
+}
+function generateString(schema, options) {
+    if (options.sampleValues === true && schema.format !== undefined) {
+        return FORMAT_VALUES[schema.format] ?? '';
+    }
+    return '';
+}
+/**
+ * A sample XML body for a schema, honouring its `xml` object: `name`, `attribute`, `wrapped`, and a
+ * `prefix`/`namespace` pair.
+ *
+ * Written here rather than through the XSD sample generator because the shape comes from JSON Schema,
+ * not from an XSD: there is no schema set to resolve against, and the `xml` object is OpenAPI's own.
+ */
+export function sampleXml(schema, options = {}) {
+    const indent = options.indent ?? '  ';
+    const merged = firstBranch(mergeAllOf(schema));
+    const name = merged.xml?.name ?? options.rootName ?? 'root';
+    const nodes = { remaining: options.maxNodes ?? MAX_SAMPLE_NODES };
+    return renderElement(merged, name, options, options.maxDepth ?? MAX_SAMPLE_DEPTH, indent, 0, nodes).join('\n');
+}
+/** The tag name for an element, with its `xml.prefix` when it has one. */
+function tagOf(schema, name) {
+    const local = schema.xml?.name ?? name;
+    return schema.xml?.prefix !== undefined ? `${schema.xml.prefix}:${local}` : local;
+}
+/** The `xmlns` attribute a namespace declaration needs, if any. */
+function namespaceAttribute(xml) {
+    if (xml?.namespace === undefined) {
+        return '';
+    }
+    return xml.prefix !== undefined
+        ? ` xmlns:${xml.prefix}="${escape(xml.namespace)}"`
+        : ` xmlns="${escape(xml.namespace)}"`;
+}
+function escape(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/** One element and everything inside it, as lines at `depth`. */
+function renderElement(input, name, options, remainingDepth, indent, depth, nodes) {
+    const pad = indent.repeat(depth);
+    const schema = firstBranch(mergeAllOf(input));
+    const tag = tagOf(schema, name);
+    // The same two bounds the JSON generator has, and for the same reason: a resolved description is a
+    // graph, so depth alone does not bound the work.
+    if (remainingDepth <= 0 || nodes.remaining <= 0) {
+        return [`${pad}<${tag}/>`];
+    }
+    nodes.remaining -= 1;
+    const type = effectiveType(schema);
+    if (type === 'object') {
+        const required = new Set(schema.required ?? []);
+        const attributes = [];
+        const children = [];
+        for (const [property, propertySchema] of Object.entries(schema.properties ?? {})) {
+            if (propertySchema.readOnly === true) {
+                continue;
+            }
+            if (!required.has(property) && options.includeOptional !== true) {
+                continue;
+            }
+            // An `xml.attribute` property is an attribute of *this* element, not a child of it.
+            if (propertySchema.xml?.attribute === true) {
+                const attributeName = tagOf(propertySchema, property);
+                attributes.push(`${attributeName}="${escape(scalarText(propertySchema, options))}"`);
+                continue;
+            }
+            if (nodes.remaining <= 0) {
+                break;
+            }
+            children.push(...renderProperty(propertySchema, property, options, remainingDepth - 1, indent, depth + 1, nodes));
+        }
+        const open = `<${tag}${namespaceAttribute(schema.xml)}${attributes.length > 0 ? ` ${attributes.join(' ')}` : ''}`;
+        if (children.length === 0) {
+            return [`${pad}${open}/>`];
+        }
+        return [`${pad}${open}>`, ...children, `${pad}</${tag}>`];
+    }
+    if (type === 'array') {
+        return renderProperty(schema, name, options, remainingDepth, indent, depth, nodes);
+    }
+    return [`${pad}<${tag}${namespaceAttribute(schema.xml)}>${escape(scalarText(schema, options))}</${tag}>`];
+}
+/** One property, which for an array is either wrapped or repeated in place. */
+function renderProperty(schema, name, options, remainingDepth, indent, depth, nodes) {
+    if (effectiveType(schema) !== 'array' || schema.items === undefined) {
+        return renderElement(schema, name, options, remainingDepth, indent, depth, nodes);
+    }
+    // `wrapped` puts the items inside an element named for the property; without it they repeat in
+    // place under the item's own name, which is XML's own default for a list.
+    const itemName = schema.items.xml?.name ?? name;
+    const item = renderElement(schema.items, itemName, options, remainingDepth - 1, indent, schema.xml?.wrapped === true ? depth + 1 : depth, nodes);
+    if (schema.xml?.wrapped !== true) {
+        return item;
+    }
+    const pad = indent.repeat(depth);
+    const tag = tagOf(schema, name);
+    return [`${pad}<${tag}${namespaceAttribute(schema.xml)}>`, ...item, `${pad}</${tag}>`];
+}
+/** The text a scalar schema renders as — the same precedence `sampleFromSchema` uses. */
+function scalarText(schema, options) {
+    const value = generate(schema, options, 1, { remaining: 1 });
+    if (value === null) {
+        return '';
+    }
+    // Only scalars reach here in practice; a composite says so as JSON rather than `[object Object]`.
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}

package/dist/rest/postman/import.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Reading a Postman Collection from a file or text and turning it into a Wirebench REST API.
+ */
+import type { MapPostmanOptions, MappedPostmanApi } from './map.js';
+/** Where a Postman collection comes from: a file on disk or text already held in memory. */
+export type PostmanSource = {
+    readonly kind: 'file';
+    readonly path: string;
+} | {
+    readonly kind: 'text';
+    readonly text: string;
+};
+export type ImportPostmanOptions = MapPostmanOptions;
+/** Largest collection accepted, in bytes (file) or UTF-16 code units (text). */
+export declare const MAX_POSTMAN_INPUT_BYTES: number;
+/**
+ * Reads, parses, and maps a Postman Collection (v2.0 or v2.1) into a Wirebench REST API.
+ *
+ * @throws PostmanError when the file cannot be read, the JSON is malformed, or the shape is not a Postman collection.
+ */
+export declare function importPostmanCollection(source: PostmanSource, options?: ImportPostmanOptions): Promise<MappedPostmanApi>;

package/dist/rest/postman/import.js

@@ -0,0 +1,47 @@
+/**
+ * Reading a Postman Collection from a file or text and turning it into a Wirebench REST API.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { PostmanError } from '../../errors.js';
+import { apiFromPostmanCollection } from './map.js';
+import { parsePostmanCollectionText } from './parse.js';
+/** Largest collection accepted, in bytes (file) or UTF-16 code units (text). */
+export const MAX_POSTMAN_INPUT_BYTES = 50 * 1024 * 1024;
+function tooLarge() {
+    return new PostmanError('postman-too-large', `The Postman collection is larger than ${MAX_POSTMAN_INPUT_BYTES / (1024 * 1024)} MB`);
+}
+/**
+ * Reads, parses, and maps a Postman Collection (v2.0 or v2.1) into a Wirebench REST API.
+ *
+ * @throws PostmanError when the file cannot be read, the JSON is malformed, or the shape is not a Postman collection.
+ */
+export async function importPostmanCollection(source, options = {}) {
+    let text;
+    if (source.kind === 'text') {
+        if (source.text.length > MAX_POSTMAN_INPUT_BYTES)
+            throw tooLarge();
+        text = source.text;
+    }
+    else if (source.kind === 'file') {
+        let size;
+        try {
+            size = (await stat(source.path)).size;
+        }
+        catch {
+            size = undefined; // reported by readFile below
+        }
+        if (size !== undefined && size > MAX_POSTMAN_INPUT_BYTES)
+            throw tooLarge();
+        try {
+            text = await readFile(source.path, 'utf8');
+        }
+        catch (error) {
+            throw new PostmanError('postman-read-failed', `Failed to read Postman collection from "${source.path}": ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    else {
+        throw new PostmanError('postman-source-invalid', 'Invalid Postman source provided');
+    }
+    const collection = parsePostmanCollectionText(text);
+    return apiFromPostmanCollection(collection, options);
+}

package/dist/rest/postman/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Postman Collection v2.0 and v2.1 import: parser, entity mapping, and pipeline.
+ */
+export * from './model.js';
+export * from './parse.js';
+export * from './map.js';
+export * from './import.js';

package/dist/rest/postman/index.js

@@ -0,0 +1,7 @@
+/**
+ * Postman Collection v2.0 and v2.1 import: parser, entity mapping, and pipeline.
+ */
+export * from './model.js';
+export * from './parse.js';
+export * from './map.js';
+export * from './import.js';

package/dist/rest/postman/map.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pure mapping from Postman Collection v2.0/v2.1 documents to Wirebench REST entities.
+ *
+ * Recursively maps Postman items into `RestFolder` and `RestRequestDef` trees, preserving author
+ * order, variable substitutions (`${var}`), path parameter definitions, headers, query parameters,
+ * request bodies (raw, urlencoded, formdata, binary), and auth configurations.
+ */
+import type { IdGenerator } from '../../project/model.js';
+import type { RestApi } from '../model.js';
+import type { PostmanCollection, PostmanImportSummary } from './model.js';
+export interface MapPostmanOptions {
+    /** The API's name. Defaults to collection `info.name`. */
+    readonly name?: string;
+    /** The base URL. Defaults to the inferred base URL, baseUrl variable, or empty. */
+    readonly baseUrl?: string;
+    /** Injectable id generator. */
+    readonly newId?: IdGenerator;
+    /** Order in project. */
+    readonly order?: number;
+}
+export interface MappedPostmanApi {
+    readonly api: RestApi;
+    readonly summary: PostmanImportSummary;
+}
+/**
+ * Maps a parsed Postman Collection into a Wirebench REST API and import summary.
+ */
+export declare function apiFromPostmanCollection(collection: PostmanCollection, options?: MapPostmanOptions): MappedPostmanApi;