@wirebench/engine 2.1.1

package/dist/rest/openapi/refs.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Resolving `$ref` in an OpenAPI document: local JSON pointers, and references into other documents.
+ *
+ * Every reference is inlined before the parser runs, so the parser never fetches and never has to
+ * carry a resolver around. That makes the fetched set the same thing the cache stores, which is what
+ * lets the definition be exported byte-exact later.
+ *
+ * Two rules keep this from being a file-read primitive handed to whoever wrote the document. The
+ * *reference policy* is the one WSDL import already uses (`wsdl/ref-policy.ts`): a `file:` root may
+ * only reference files inside its own folder tree, an `http(s):` root may never reach a local file.
+ * And the walk is bounded — a visited set per pointer, a depth cap, and a document cap — because a
+ * cyclic or fan-out document must end in a diagnostic, not a hang.
+ */
+import type { FetchDocument } from '../../wsdl/resolver.js';
+/** How deep a chain of `$ref`s may nest before the graph is treated as runaway. */
+export declare const MAX_REF_DEPTH = 32;
+/** One document the resolution pulled in, kept for the definition cache. */
+export interface ResolvedDocument {
+    /** The absolute location it was fetched from, post-redirect. */
+    readonly location: string;
+    /** The location that was asked for, before any redirect. */
+    readonly requestedLocation: string;
+    readonly bytes: Uint8Array;
+    readonly text: string;
+}
+/** A reference that could not be followed, and why. Never fatal: the `$ref` is left in place. */
+export interface RefProblem {
+    /** The reference as written. */
+    readonly ref: string;
+    /** Where it was written, as a JSON pointer into the root document. */
+    readonly at: string;
+    readonly reason: string;
+}
+/** What {@link resolveRefs} produced. */
+export interface ResolvedRefs {
+    /** The root document with every reference it could follow inlined. */
+    readonly document: unknown;
+    /** Every document fetched, root first, in the order they were reached. */
+    readonly documents: readonly ResolvedDocument[];
+    readonly problems: readonly RefProblem[];
+}
+export interface ResolveRefsOptions {
+    readonly fetchDocument: FetchDocument;
+    readonly signal?: AbortSignal;
+}
+/** Unescapes one JSON pointer token per RFC 6901: `~1` is `/`, `~0` is `~`, in that order. */
+export declare function unescapePointerToken(token: string): string;
+/**
+ * The value one JSON pointer names inside `document`, or `undefined` when the pointer leads nowhere.
+ *
+ * `''` is the whole document, per RFC 6901. An array index is read as a number; anything else is a
+ * key. A pointer into a non-container is `undefined` rather than an error — the caller reports it as
+ * a reference problem, which is the only form the user can act on.
+ */
+export declare function resolvePointer(document: unknown, pointer: string): unknown;
+/**
+ * Inlines every `$ref` in `rootText`'s document.
+ *
+ * @param rootText the root document's text, JSON or YAML
+ * @param rootLocation its absolute location, which decides the reference policy
+ * @throws OpenApiError `openapi-malformed` when the root document itself does not parse
+ */
+export declare function resolveRefs(rootText: string, rootLocation: string, options: ResolveRefsOptions, rootBytes?: Uint8Array): Promise<ResolvedRefs>;

package/dist/rest/openapi/refs.js

@@ -0,0 +1,258 @@
+/**
+ * Resolving `$ref` in an OpenAPI document: local JSON pointers, and references into other documents.
+ *
+ * Every reference is inlined before the parser runs, so the parser never fetches and never has to
+ * carry a resolver around. That makes the fetched set the same thing the cache stores, which is what
+ * lets the definition be exported byte-exact later.
+ *
+ * Two rules keep this from being a file-read primitive handed to whoever wrote the document. The
+ * *reference policy* is the one WSDL import already uses (`wsdl/ref-policy.ts`): a `file:` root may
+ * only reference files inside its own folder tree, an `http(s):` root may never reach a local file.
+ * And the walk is bounded — a visited set per pointer, a depth cap, and a document cap — because a
+ * cyclic or fan-out document must end in a diagnostic, not a hang.
+ */
+import { OpenApiError } from '../../errors.js';
+import { referencePolicyFor, MAX_IMPORT_DEPTH, MAX_IMPORT_DOCUMENTS } from '../../wsdl/ref-policy.js';
+import { parseDocumentText } from './parse.js';
+/** How deep a chain of `$ref`s may nest before the graph is treated as runaway. */
+export const MAX_REF_DEPTH = MAX_IMPORT_DEPTH;
+/** Unescapes one JSON pointer token per RFC 6901: `~1` is `/`, `~0` is `~`, in that order. */
+export function unescapePointerToken(token) {
+    return token.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+/**
+ * The value one JSON pointer names inside `document`, or `undefined` when the pointer leads nowhere.
+ *
+ * `''` is the whole document, per RFC 6901. An array index is read as a number; anything else is a
+ * key. A pointer into a non-container is `undefined` rather than an error — the caller reports it as
+ * a reference problem, which is the only form the user can act on.
+ */
+export function resolvePointer(document, pointer) {
+    if (pointer === '' || pointer === '#') {
+        return document;
+    }
+    const path = pointer.startsWith('#') ? pointer.slice(1) : pointer;
+    if (!path.startsWith('/')) {
+        return undefined;
+    }
+    let at = document;
+    for (const raw of path.slice(1).split('/')) {
+        const token = unescapePointerToken(decodeURIComponent(raw));
+        if (Array.isArray(at)) {
+            const index = Number(token);
+            if (!Number.isInteger(index) || index < 0 || index >= at.length) {
+                return undefined;
+            }
+            at = at[index];
+            continue;
+        }
+        if (typeof at !== 'object' || at === null) {
+            return undefined;
+        }
+        at = at[token];
+        if (at === undefined) {
+            return undefined;
+        }
+    }
+    return at;
+}
+/** Splits a `$ref` into the document part (possibly empty) and its fragment pointer. */
+function splitRef(ref) {
+    const hash = ref.indexOf('#');
+    if (hash === -1) {
+        return { target: ref, pointer: '' };
+    }
+    return { target: ref.slice(0, hash), pointer: ref.slice(hash) };
+}
+/** Resolves a possibly relative document location against the document that referenced it. */
+function absolute(target, base) {
+    try {
+        return new URL(target, base).toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Inlines every `$ref` in `rootText`'s document.
+ *
+ * @param rootText the root document's text, JSON or YAML
+ * @param rootLocation its absolute location, which decides the reference policy
+ * @throws OpenApiError `openapi-malformed` when the root document itself does not parse
+ */
+export async function resolveRefs(rootText, rootLocation, options, rootBytes) {
+    const root = parseDocumentText(rootText);
+    const byLocation = new Map([[rootLocation, root]]);
+    const rawSelf = typeof root?.$self === 'string'
+        ? root.$self.trim()
+        : undefined;
+    if (rawSelf) {
+        const resolvedSelf = absolute(rawSelf, rootLocation);
+        if (resolvedSelf !== undefined) {
+            try {
+                const normalizedSelf = new URL(resolvedSelf).toString();
+                const rootUrl = new URL(rootLocation);
+                const selfUrl = new URL(normalizedSelf);
+                const isSameOrigin = rootUrl.origin !== 'null' && selfUrl.origin !== 'null'
+                    ? rootUrl.origin === selfUrl.origin
+                    : rootUrl.protocol === selfUrl.protocol;
+                if (isSameOrigin) {
+                    const policy = referencePolicyFor(rootLocation);
+                    const refusal = await policy.allows(normalizedSelf);
+                    if (refusal === undefined) {
+                        byLocation.set(normalizedSelf, root);
+                    }
+                }
+            }
+            catch {
+                // Invalid URL; do not alias
+            }
+        }
+    }
+    const walk = {
+        root,
+        rootLocation,
+        options,
+        byLocation,
+        documents: [
+            {
+                location: rootLocation,
+                requestedLocation: rootLocation,
+                bytes: rootBytes ?? new TextEncoder().encode(rootText),
+                text: rootText,
+            },
+        ],
+        problems: [],
+        resolved: new Map(),
+        inProgress: new Set(),
+    };
+    const document = await inline(walk, root, rootLocation, '', 0);
+    return { document, documents: walk.documents, problems: walk.problems };
+}
+/**
+ * Walks `value`, replacing each `{ $ref }` with what it names.
+ *
+ * `seen` holds the references already being followed *on this branch*, which is what makes a cyclic
+ * document terminate: the second time a branch reaches the same reference it is left as a `$ref`,
+ * and the sample generator treats that as the cut it already caps depth with.
+ */
+async function inline(walk, value, location, at, depth) {
+    walk.options.signal?.throwIfAborted();
+    if (Array.isArray(value)) {
+        const out = [];
+        for (const [index, entry] of value.entries()) {
+            out.push(await inline(walk, entry, location, `${at}/${String(index)}`, depth));
+        }
+        return out;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+    const record = value;
+    const ref = typeof record['$ref'] === 'string' ? record['$ref'] : undefined;
+    if (ref !== undefined) {
+        return await follow(walk, record, ref, location, at, depth);
+    }
+    const out = {};
+    for (const [key, entry] of Object.entries(record)) {
+        out[key] = await inline(walk, entry, location, `${at}/${key.replace(/~/g, '~0').replace(/\//g, '~1')}`, depth);
+    }
+    return out;
+}
+/** Follows one reference, or leaves it in place with a problem recorded. */
+async function follow(walk, node, ref, location, at, depth) {
+    const { target, pointer } = splitRef(ref);
+    const documentLocation = target === '' ? location : absolute(target, location);
+    if (documentLocation === undefined) {
+        walk.problems.push({ ref, at, reason: 'the reference is not a usable location' });
+        return node;
+    }
+    const key = `${documentLocation}${pointer}`;
+    if (walk.inProgress.has(key)) {
+        // A cycle. The `$ref` stays, which is exactly what the sample generator's depth cut expects.
+        return node;
+    }
+    const already = walk.resolved.get(key);
+    if (already !== undefined) {
+        // Seen before, and a target's expansion does not depend on who asked for it: hand back the same
+        // subtree rather than building an identical one. This is what keeps a densely cross-referenced
+        // document from expanding exponentially.
+        return already;
+    }
+    if (depth >= MAX_REF_DEPTH) {
+        walk.problems.push({ ref, at, reason: `references nest deeper than ${String(MAX_REF_DEPTH)} levels` });
+        return node;
+    }
+    let document = walk.byLocation.get(documentLocation);
+    if (document === undefined) {
+        document = await fetchInto(walk, documentLocation, ref, at);
+        if (document === undefined) {
+            return node;
+        }
+    }
+    const resolved = resolvePointer(document, pointer);
+    if (resolved === undefined) {
+        walk.problems.push({ ref, at, reason: 'nothing at that location' });
+        return node;
+    }
+    // Resolved from the *referenced* document's location, so a relative reference inside it is
+    // resolved against the document it was written in rather than against the root.
+    walk.inProgress.add(key);
+    try {
+        const inlined = await inline(walk, resolved, documentLocation, at, depth + 1);
+        walk.resolved.set(key, inlined);
+        return inlined;
+    }
+    finally {
+        walk.inProgress.delete(key);
+    }
+}
+/** Fetches one referenced document, under the policy, and records it. */
+async function fetchInto(walk, location, ref, at) {
+    if (walk.documents.length >= MAX_IMPORT_DOCUMENTS) {
+        walk.problems.push({ ref, at, reason: `more than ${String(MAX_IMPORT_DOCUMENTS)} documents were referenced` });
+        return undefined;
+    }
+    const refusal = await referencePolicyFor(walk.rootLocation).allows(location);
+    if (refusal !== undefined) {
+        walk.problems.push({ ref, at, reason: refusal.reason });
+        return undefined;
+    }
+    let fetched;
+    try {
+        fetched = await walk.options.fetchDocument(location, walk.options.signal);
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw error;
+        }
+        walk.problems.push({
+            ref,
+            at,
+            reason: `could not be fetched: ${error instanceof Error ? error.message : 'failed'}`,
+        });
+        return undefined;
+    }
+    // A cancel that lands while a document is in flight must stop the walk here rather than after the
+    // next reference: the user pressed Cancel, and the remaining fetches are what they cancelled.
+    walk.options.signal?.throwIfAborted();
+    let parsed;
+    try {
+        parsed = parseDocumentText(fetched.text, location);
+    }
+    catch (error) {
+        walk.problems.push({ ref, at, reason: error instanceof OpenApiError ? error.message : 'could not be parsed' });
+        return undefined;
+    }
+    walk.documents.push({
+        location: fetched.location,
+        requestedLocation: location,
+        bytes: fetched.bytes,
+        text: fetched.text,
+    });
+    walk.byLocation.set(location, parsed);
+    // A redirect means the document also answers to where it ended up, so a sibling reference
+    // resolved against that location finds it without a second fetch.
+    walk.byLocation.set(fetched.location, parsed);
+    return parsed;
+}

package/dist/rest/openapi/sample.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ */
+import type { JsonSchema, JsonValue } from './model.js';
+/** How deep generation goes before it stops and emits `null`. */
+export declare 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 declare const MAX_SAMPLE_NODES = 2000;
+export interface SampleOptions {
+    /** Emit properties the schema does not require. Mirrors the WSDL generator's preference. */
+    readonly includeOptional?: boolean;
+    /**
+     * Emit format-appropriate placeholders (`2026-01-01T00:00:00Z` for a `date-time`) instead of the
+     * type's empty value. The same preference the WSDL sample generator has.
+     */
+    readonly sampleValues?: boolean;
+    /** Where to stop. Defaults to {@link MAX_SAMPLE_DEPTH}. */
+    readonly maxDepth?: number;
+    /** How many values the sample may hold. Defaults to {@link MAX_SAMPLE_NODES}. */
+    readonly maxNodes?: number;
+}
+/**
+ * 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 declare function sampleFromSchema(schema: JsonSchema, options?: SampleOptions): JsonValue;
+/** Options for {@link sampleXml}. */
+export interface SampleXmlOptions extends SampleOptions {
+    /** The root element's name, when the schema's own `xml.name` does not give one. */
+    readonly rootName?: string;
+    /** Indent per level. Defaults to two spaces, matching a REST body's own formatting. */
+    readonly indent?: string;
+}
+/**
+ * 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 declare function sampleXml(schema: JsonSchema, options?: SampleXmlOptions): string;