@sezzlee/openapi 0.0.0-stage → 0.2.0

package/dist/lower/servers.js

@@ -0,0 +1,50 @@
+import { childPointer } from "../ir/brand.js";
+import { arrayOf, objectOf, stringOf } from "../ir/json.js";
+/**
+ * Resolves the first server of the nearest non-empty list among operation and path item, else the
+ * root's. A configured `baseUrl` replaces the root list; it does not override a server an
+ * operation or path item declares for itself.
+ *
+ * @param lists the operation's and the path item's lists, nearest first
+ */
+export function serverOf(lists, root, options, diagnostics) {
+    const own = lists.find((list) => arrayOf(list.servers).length > 0);
+    if (own === undefined && options.baseUrl !== undefined) {
+        return stripTrailingSlash(options.baseUrl);
+    }
+    const chosen = own ?? (arrayOf(root.servers).length > 0 ? root : undefined);
+    if (chosen === undefined) {
+        return resolve("/", undefined, options, diagnostics);
+    }
+    const at = childPointer(chosen.at, 0);
+    const server = objectOf(arrayOf(chosen.servers)[0]);
+    const template = stringOf(server?.["url"]) ?? "/";
+    const url = template.replace(/\{([^}]+)\}/g, (_match, name) => {
+        const variable = objectOf(objectOf(server?.["variables"])?.[name]);
+        const value = options.variables?.[name] ?? stringOf(variable?.["default"]);
+        const allowed = arrayOf(variable?.["enum"])
+            .map(stringOf)
+            .filter((item) => item !== undefined);
+        if (value === undefined) {
+            diagnostics.report("server_variable_invalid", childPointer(at, "variables", name), `Server variable '${name}' has no default and no configured value.`);
+            return "";
+        }
+        if (allowed.length > 0 && !allowed.includes(value)) {
+            diagnostics.report("server_variable_invalid", childPointer(at, "variables", name), `Server variable '${name}' is '${value}', which its enum does not list.`);
+        }
+        return value;
+    });
+    return resolve(url, at, options, diagnostics);
+}
+function resolve(url, at, options, diagnostics) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) {
+        return stripTrailingSlash(url);
+    }
+    if (options.documentUrl !== undefined &&
+        /^https?:/i.test(options.documentUrl)) {
+        return stripTrailingSlash(new URL(url, options.documentUrl).toString());
+    }
+    diagnostics.report("server_url_unresolvable", at ?? "", `Server URL '${url}' is relative and the document was not read from a URL; configure a base URL.`);
+    return undefined;
+}
+const stripTrailingSlash = (url) => url.replace(/\/+$/, "");

package/dist/normalize/external.d.ts

@@ -0,0 +1,9 @@
+import type { DiagnosticSink } from "../diagnostics.js";
+import { type JsonObject } from "../ir/json.js";
+/**
+ * Reads one referenced document. The host decides what may be read: an allowlist of hosts, a
+ * deadline and a size limit for a URL, and a root directory for a file. An external reference is a
+ * way for a document's author to make the ingesting process issue a request.
+ */
+export type DocumentLoader = (url: URL) => Promise<string>;
+export declare function bundleExternal(document: JsonObject, documentUrl: string | undefined, loader: DocumentLoader | undefined, diagnostics: DiagnosticSink): Promise<JsonObject | undefined>;

package/dist/normalize/external.js

@@ -0,0 +1,93 @@
+import { childPointer, rootPointer } from "../ir/brand.js";
+import { entriesOf, isObject, } from "../ir/json.js";
+import { parseDocument } from "../parse/parse.js";
+import { resolvePointer } from "./refs.js";
+const maxDepth = 32;
+function firstExternalRef(value, at) {
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries()) {
+            const found = firstExternalRef(item, childPointer(at, index));
+            if (found !== undefined) {
+                return found;
+            }
+        }
+        return undefined;
+    }
+    if (!isObject(value)) {
+        return undefined;
+    }
+    for (const [key, child] of entriesOf(value)) {
+        if (key === "$ref" && typeof child === "string") {
+            if (!child.startsWith("#")) {
+                return childPointer(at, key);
+            }
+            continue;
+        }
+        const found = firstExternalRef(child, childPointer(at, key));
+        if (found !== undefined) {
+            return found;
+        }
+    }
+    return undefined;
+}
+function load(bundler, url) {
+    const key = url.href.replace(/#.*$/, "");
+    let pending = bundler.cache.get(key);
+    if (pending === undefined) {
+        pending = bundler
+            .loader(new URL(key))
+            .then((text) => parseDocument(text, bundler.diagnostics));
+        bundler.cache.set(key, pending);
+    }
+    return pending;
+}
+/**
+ * Inlines every external reference. The referenced fragment is inlined with its own references
+ * resolved against its own document, so the result has only local references left.
+ */
+async function inline(bundler, value, base, document, at, depth, local) {
+    if (Array.isArray(value)) {
+        return Promise.all(value.map((item, index) => inline(bundler, item, base, document, childPointer(at, index), depth, local)));
+    }
+    if (!isObject(value)) {
+        return value;
+    }
+    const ref = value["$ref"];
+    if (typeof ref === "string" && (!ref.startsWith("#") || !local)) {
+        if (depth >= maxDepth) {
+            bundler.diagnostics.report("external_ref_blocked", at, `Reference '${ref}' nests more than ${String(maxDepth)} documents deep.`);
+            return {};
+        }
+        const target = new URL(ref, base);
+        const targetDocument = ref.startsWith("#")
+            ? document
+            : await load(bundler, target);
+        if (targetDocument === undefined) {
+            return {};
+        }
+        const fragment = resolvePointer(targetDocument, target.hash);
+        if (fragment === undefined) {
+            bundler.diagnostics.report("external_ref_blocked", at, `Reference '${ref}' resolves to nothing.`);
+            return {};
+        }
+        return inline(bundler, fragment, target, targetDocument, at, depth + 1, false);
+    }
+    const out = {};
+    for (const [key, child] of entriesOf(value)) {
+        out[key] = await inline(bundler, child, base, document, childPointer(at, key), depth, local);
+    }
+    return out;
+}
+export async function bundleExternal(document, documentUrl, loader, diagnostics) {
+    const external = firstExternalRef(document, rootPointer);
+    if (external === undefined) {
+        return document;
+    }
+    if (loader === undefined || documentUrl === undefined) {
+        diagnostics.report("external_ref_blocked", external, "The document references another document, and no loader was configured to read it.");
+        return undefined;
+    }
+    const bundler = { loader, diagnostics, cache: new Map() };
+    const bundled = await inline(bundler, document, new URL(documentUrl), document, rootPointer, 0, true);
+    return isObject(bundled) ? bundled : undefined;
+}

package/dist/normalize/refs.d.ts

@@ -0,0 +1,15 @@
+import { type JsonPointer } from "../ir/brand.js";
+import { type JsonObject, type JsonValue } from "../ir/json.js";
+export declare function resolvePointer(document: JsonObject, ref: string): JsonValue | undefined;
+export declare function pointerOfRef(ref: string): JsonPointer;
+/**
+ * Follows a chain of references to a non-schema component (a parameter, request body, response,
+ * header or path item) and returns the object it ends at, with the pointer of that object.
+ *
+ * @throws OperationDropped `circular_component_ref` when the chain returns to a reference it
+ * already followed, or ends nowhere
+ */
+export declare function resolveComponent(document: JsonObject, value: JsonValue | undefined, at: JsonPointer): {
+    readonly node: JsonObject;
+    readonly at: JsonPointer;
+} | undefined;

package/dist/normalize/refs.js

@@ -0,0 +1,49 @@
+import { OperationDropped } from "../diagnostics.js";
+import { segmentsOf } from "../ir/brand.js";
+import { isObject, objectOf, stringOf, } from "../ir/json.js";
+export function resolvePointer(document, ref) {
+    let node = document;
+    for (const segment of segmentsOf(ref)) {
+        if (Array.isArray(node)) {
+            node = node[Number(segment)];
+        }
+        else if (isObject(node)) {
+            node = node[segment];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return node;
+}
+export function pointerOfRef(ref) {
+    return (ref.startsWith("#") ? ref.slice(1) : ref);
+}
+/**
+ * Follows a chain of references to a non-schema component (a parameter, request body, response,
+ * header or path item) and returns the object it ends at, with the pointer of that object.
+ *
+ * @throws OperationDropped `circular_component_ref` when the chain returns to a reference it
+ * already followed, or ends nowhere
+ */
+export function resolveComponent(document, value, at) {
+    let node = objectOf(value);
+    let where = at;
+    const seen = new Set();
+    while (node !== undefined) {
+        const ref = stringOf(node["$ref"]);
+        if (ref === undefined) {
+            return { node, at: where };
+        }
+        if (seen.has(ref) || !ref.startsWith("#")) {
+            throw new OperationDropped("circular_component_ref", where, `Reference '${ref}' ${seen.has(ref) ? "returns to itself" : "is not local"}.`);
+        }
+        seen.add(ref);
+        where = pointerOfRef(ref);
+        node = objectOf(resolvePointer(document, ref));
+        if (node === undefined) {
+            throw new OperationDropped("circular_component_ref", where, `Reference '${ref}' resolves to nothing.`);
+        }
+    }
+    return undefined;
+}

package/dist/normalize/schema.d.ts

@@ -0,0 +1,24 @@
+import type { JsonSchemaObject } from "@sezzlee/core";
+import { type DiagnosticSink } from "../diagnostics.js";
+import { type JsonPointer } from "../ir/brand.js";
+import { type JsonObject, type JsonValue } from "../ir/json.js";
+import type { DocumentVersion } from "../parse/parse.js";
+export type Direction = "request" | "response";
+export interface SchemaContext {
+    readonly document: JsonObject;
+    readonly version: DocumentVersion;
+    readonly diagnostics: DiagnosticSink;
+}
+/**
+ * @param root how a slot whose top level is a reference is treated: `required` dereferences it or
+ * drops the operation (a parameter's kind is read from its top-level type), `preferred`
+ * dereferences it when that terminates and keeps the reference otherwise
+ * @param fileMediaType the media type a `format: binary` string becomes, from a multipart
+ * `encoding` entry
+ */
+export interface SlotOptions {
+    readonly direction: Direction;
+    readonly root: "required" | "preferred";
+    readonly fileMediaType?: (property: string) => string | undefined;
+}
+export declare function normalizeSlot(context: SchemaContext, schema: JsonValue | undefined, at: JsonPointer, options: SlotOptions): JsonSchemaObject;

package/dist/normalize/schema.js

@@ -0,0 +1,354 @@
+import { OperationDropped } from "../diagnostics.js";
+import { childPointer, segmentsOf } from "../ir/brand.js";
+import { entriesOf, isObject, stringOf, } from "../ir/json.js";
+import { pointerOfRef, resolvePointer } from "./refs.js";
+const subschemaMaps = [
+    "properties",
+    "patternProperties",
+    "dependentSchemas",
+    "$defs",
+];
+const subschemaSingles = [
+    "items",
+    "additionalProperties",
+    "not",
+    "contains",
+    "propertyNames",
+    "if",
+    "then",
+    "else",
+    "unevaluatedItems",
+    "unevaluatedProperties",
+];
+const subschemaLists = ["allOf", "anyOf", "oneOf", "prefixItems"];
+const annotations = new Set(["discriminator", "xml", "externalDocs"]);
+const escapeDefName = (name) => name.replaceAll("~", "~0").replaceAll("/", "~1");
+class SlotNormalizer {
+    context;
+    options;
+    defs = new Map();
+    names = new Map();
+    queue = [];
+    constructor(context, options) {
+        this.context = context;
+        this.options = options;
+    }
+    normalize(schema, at) {
+        let root = this.convert(schema, at, undefined);
+        while (this.queue.length > 0) {
+            const ref = this.queue.shift();
+            const name = this.names.get(ref);
+            const target = resolvePointer(this.context.document, ref);
+            if (target === undefined) {
+                this.context.diagnostics.report("openapi_document_invalid", pointerOfRef(ref), `Reference '${ref}' resolves to nothing; it is treated as an unconstrained schema.`);
+            }
+            this.defs.set(name, this.convert(target, pointerOfRef(ref), undefined));
+        }
+        root = this.dereferenceRoot(root, at);
+        const used = this.referencedDefs(root);
+        const defs = [...this.defs.entries()].filter(([name]) => used.has(name));
+        if (defs.length === 0) {
+            return root;
+        }
+        return { ...root, $defs: Object.fromEntries(defs) };
+    }
+    dereferenceRoot(root, at) {
+        const nullableRef = nullableReference(root);
+        if (nullableRef !== undefined) {
+            const inner = this.dereferenceRoot(nullableRef, at);
+            return inner === nullableRef
+                ? root
+                : this.nullable({ nullable: true }, inner);
+        }
+        let current = root;
+        const seen = new Set();
+        while (Object.keys(current).length === 1 && current.$ref !== undefined) {
+            const name = defNameOf(current.$ref);
+            if (seen.has(name) || !this.defs.has(name)) {
+                if (this.options.root === "required") {
+                    throw new OperationDropped("recursive_parameter_schema", at, "The parameter's schema refers to itself at its top level, so it has no scalar or array type to write.");
+                }
+                return root;
+            }
+            seen.add(name);
+            current = this.defs.get(name);
+        }
+        return current;
+    }
+    referencedDefs(root) {
+        const used = new Set();
+        const pending = [root];
+        while (pending.length > 0) {
+            const node = pending.pop();
+            if (Array.isArray(node)) {
+                pending.push(...node);
+            }
+            else if (isObject(node)) {
+                for (const [key, value] of entriesOf(node)) {
+                    if (key === "$ref" && typeof value === "string") {
+                        const name = defNameOf(value);
+                        if (!used.has(name) && this.defs.has(name)) {
+                            used.add(name);
+                            pending.push(this.defs.get(name));
+                        }
+                    }
+                    else {
+                        pending.push(value);
+                    }
+                }
+            }
+        }
+        return used;
+    }
+    nameFor(ref) {
+        const known = this.names.get(ref);
+        if (known !== undefined) {
+            return known;
+        }
+        const segments = segmentsOf(ref);
+        const base = segments.length === 3 &&
+            segments[0] === "components" &&
+            segments[1] === "schemas"
+            ? segments[2]
+            : segments.join("_");
+        let name = base;
+        const taken = new Set(this.names.values());
+        for (let suffix = 2; taken.has(name); suffix += 1) {
+            name = `${base}_${suffix}`;
+        }
+        this.names.set(ref, name);
+        this.queue.push(ref);
+        return name;
+    }
+    convert(value, at, property) {
+        if (value === true || value === undefined) {
+            return {};
+        }
+        if (value === false) {
+            return { not: {} };
+        }
+        if (!isObject(value)) {
+            return {};
+        }
+        const ref = stringOf(value["$ref"]);
+        if (ref !== undefined && ref.startsWith("#")) {
+            return this.convertRef(value, ref, at, property);
+        }
+        const out = {};
+        for (const [key, child] of entriesOf(value)) {
+            const childAt = childPointer(at, key);
+            if (key === "nullable" || key === "default" || key === "$ref") {
+                continue;
+            }
+            if (key.startsWith("x-") || annotations.has(key)) {
+                this.context.diagnostics.report("annotation_removed", childAt, `Schema annotations such as '${key.startsWith("x-") ? "x-*" : key}' change nothing the composer writes and are removed.`);
+                continue;
+            }
+            if (key === "example") {
+                if (value["examples"] === undefined) {
+                    out["examples"] = [child];
+                }
+                continue;
+            }
+            if (key === "format" && child === "binary") {
+                out["contentMediaType"] =
+                    (property === undefined
+                        ? undefined
+                        : this.options.fileMediaType?.(property)) ??
+                        "application/octet-stream";
+                continue;
+            }
+            if (key === "format" && child === "byte") {
+                out["contentEncoding"] = "base64";
+                continue;
+            }
+            if ((key === "exclusiveMinimum" || key === "exclusiveMaximum") &&
+                typeof child === "boolean") {
+                const bound = key === "exclusiveMinimum" ? "minimum" : "maximum";
+                if (child && typeof value[bound] === "number") {
+                    out[key] = value[bound];
+                }
+                continue;
+            }
+            if ((key === "minimum" || key === "maximum") &&
+                value[key === "minimum" ? "exclusiveMinimum" : "exclusiveMaximum"] ===
+                    true) {
+                continue;
+            }
+            if (subschemaMaps.includes(key)) {
+                out[key] = this.convertMap(key, child, childAt);
+                continue;
+            }
+            if (subschemaSingles.includes(key)) {
+                out[key] =
+                    typeof child === "boolean"
+                        ? child
+                        : this.convert(child, childAt, undefined);
+                continue;
+            }
+            if (subschemaLists.includes(key)) {
+                out[key] = (Array.isArray(child) ? child : []).map((member, index) => this.convert(member, childPointer(childAt, index), undefined));
+                continue;
+            }
+            out[key] = child;
+        }
+        if (Array.isArray(out["required"]) && isObject(out["properties"])) {
+            const kept = new Set(Object.keys(out["properties"]));
+            out["required"] = out["required"].filter((name) => typeof name === "string" && kept.has(name));
+        }
+        const merged = mergeAllOf(out);
+        return this.nullable(value, merged);
+    }
+    convertRef(value, ref, at, property) {
+        const target = {
+            $ref: `#/$defs/${escapeDefName(this.nameFor(ref))}`,
+        };
+        const siblings = entriesOf(value).filter(([key]) => key !== "$ref" && key !== "nullable");
+        if (this.context.version === "3.0" && siblings.length > 0) {
+            this.context.diagnostics.report("ref_siblings_ignored", at, "OpenAPI 3.0 ignores keywords next to $ref; only 'nullable' is honoured beside one.");
+            return this.nullable(value, target);
+        }
+        if (siblings.length === 0) {
+            return this.nullable(value, target);
+        }
+        const rest = {};
+        for (const [key, child] of siblings) {
+            rest[key] = child;
+        }
+        const converted = this.convert(rest, at, property);
+        return this.nullable(value, { ...converted, ...target });
+    }
+    convertMap(key, child, at) {
+        const out = {};
+        for (const [name, schema] of entriesOf(child)) {
+            if (key === "properties" && this.hidden(schema)) {
+                continue;
+            }
+            out[name] = this.convert(schema, childPointer(at, name), key === "properties" ? name : undefined);
+        }
+        return out;
+    }
+    hidden(schema) {
+        if (!isObject(schema)) {
+            return false;
+        }
+        return this.options.direction === "request"
+            ? schema["readOnly"] === true
+            : schema["writeOnly"] === true;
+    }
+    nullable(source, schema) {
+        if (source["nullable"] !== true) {
+            return schema;
+        }
+        const type = schema.type;
+        if (typeof type === "string") {
+            return {
+                ...schema,
+                type: [type, "null"],
+                ...(Array.isArray(schema.enum) && !schema.enum.includes(null)
+                    ? { enum: [...schema.enum, null] }
+                    : {}),
+            };
+        }
+        if (Array.isArray(type)) {
+            return type.includes("null")
+                ? schema
+                : { ...schema, type: [...type, "null"] };
+        }
+        return { anyOf: [schema, { type: "null" }] };
+    }
+}
+function nullableReference(schema) {
+    const members = schema.anyOf ?? schema.oneOf;
+    if (Object.keys(schema).length !== 1 || !Array.isArray(members)) {
+        return undefined;
+    }
+    if (members.length !== 2) {
+        return undefined;
+    }
+    const [first, second] = members;
+    const isNull = (member) => member !== undefined &&
+        Object.keys(member).length === 1 &&
+        member.type === "null";
+    const isRef = (member) => member !== undefined &&
+        Object.keys(member).length === 1 &&
+        member.$ref !== undefined;
+    if (isRef(first) && isNull(second)) {
+        return first;
+    }
+    return isRef(second) && isNull(first) ? second : undefined;
+}
+function defNameOf(ref) {
+    const name = ref.replace(/^#\/\$defs\//, "");
+    return name.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+const structural = new Set([
+    "type",
+    "properties",
+    "required",
+    "additionalProperties",
+    "allOf",
+]);
+/**
+ * Merges an `allOf` of plain object schemas into one object, so a body root built by composition
+ * can still be flattened. Anything that cannot be merged without choosing between two
+ * definitions — a reference, a combinator, two different schemas for one property — is kept as
+ * `allOf`, and the core sends such a body in root mode.
+ */
+function mergeAllOf(schema) {
+    const members = schema["allOf"];
+    if (!Array.isArray(members) || members.length === 0) {
+        return schema;
+    }
+    const objects = members.filter(isObject);
+    if (objects.length !== members.length) {
+        return schema;
+    }
+    const others = Object.keys(schema).filter((key) => key !== "allOf");
+    if (objects.length === 1 &&
+        others.every((key) => !structural.has(key)) &&
+        Object.keys(objects[0]).length === 1 &&
+        objects[0]["$ref"] !== undefined) {
+        const { allOf: _allOf, ...rest } = schema;
+        return { ...rest, ...objects[0] };
+    }
+    const mergeable = objects.every((member) => member["$ref"] === undefined &&
+        Object.keys(member).every((key) => structural.has(key) || key === "description") &&
+        (member["type"] === undefined || member["type"] === "object"));
+    if (!mergeable) {
+        return schema;
+    }
+    const properties = {
+        ...(isObject(schema["properties"]) ? schema["properties"] : {}),
+    };
+    const required = new Set(Array.isArray(schema["required"])
+        ? schema["required"].filter((item) => typeof item === "string")
+        : []);
+    for (const member of objects) {
+        for (const [name, property] of entriesOf(member["properties"])) {
+            const existing = properties[name];
+            if (existing !== undefined &&
+                JSON.stringify(existing) !== JSON.stringify(property)) {
+                return schema;
+            }
+            properties[name] = property;
+        }
+        for (const name of Array.isArray(member["required"])
+            ? member["required"]
+            : []) {
+            if (typeof name === "string") {
+                required.add(name);
+            }
+        }
+    }
+    const { allOf: _allOf, ...rest } = schema;
+    return {
+        ...rest,
+        type: "object",
+        properties,
+        ...(required.size === 0 ? {} : { required: [...required] }),
+    };
+}
+export function normalizeSlot(context, schema, at, options) {
+    return new SlotNormalizer(context, options).normalize(schema, at);
+}

package/dist/parse/parse.d.ts

@@ -0,0 +1,5 @@
+import { DiagnosticSink } from "../diagnostics.js";
+import { type JsonObject } from "../ir/json.js";
+export type DocumentVersion = "2.0" | "3.0" | "3.1" | "3.2";
+export declare function parseDocument(text: string, diagnostics: DiagnosticSink): JsonObject | undefined;
+export declare function versionOf(document: JsonObject, diagnostics: DiagnosticSink): DocumentVersion | undefined;

package/dist/parse/parse.js

@@ -0,0 +1,40 @@
+import { parse as parseYaml } from "yaml";
+import { childPointer, rootPointer } from "../ir/brand.js";
+import { isObject, stringOf } from "../ir/json.js";
+export function parseDocument(text, diagnostics) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        try {
+            value = parseYaml(text, { maxAliasCount: 100 });
+        }
+        catch (error) {
+            diagnostics.report("openapi_document_unparseable", rootPointer, `The document is neither JSON nor YAML: ${error.message}`);
+            return undefined;
+        }
+    }
+    if (!isObject(value)) {
+        diagnostics.report("openapi_document_unparseable", rootPointer, "The document's root is not an object.");
+        return undefined;
+    }
+    return value;
+}
+export function versionOf(document, diagnostics) {
+    const swagger = stringOf(document["swagger"]);
+    if (swagger !== undefined) {
+        if (swagger === "2.0") {
+            return "2.0";
+        }
+    }
+    else {
+        const openapi = stringOf(document["openapi"]) ?? "";
+        const match = /^3\.([0-2])\.\d+$/.exec(openapi);
+        if (match !== null) {
+            return `3.${match[1]}`;
+        }
+    }
+    diagnostics.report("openapi_version_unsupported", childPointer(rootPointer, swagger === undefined ? "openapi" : "swagger"), `Version '${swagger ?? stringOf(document["openapi"]) ?? "absent"}' is not Swagger 2.0 or OpenAPI 3.0, 3.1 or 3.2.`);
+    return undefined;
+}

package/dist/parse/swagger2.d.ts

@@ -0,0 +1,11 @@
+import type { DiagnosticSink } from "../diagnostics.js";
+import { type JsonPointer } from "../ir/brand.js";
+import { type JsonObject } from "../ir/json.js";
+/** Where a node of the upgraded document came from in the author's 2.0 document. */
+export type Origins = WeakMap<object, JsonPointer>;
+/**
+ * Converts a Swagger 2.0 document to the OpenAPI 3 shape the rest of ingestion reads, following
+ * swagger2openapi's rules. Nodes that move are recorded in `origins` so a diagnostic still points
+ * into the author's document.
+ */
+export declare function upgradeSwagger2(document: JsonObject, diagnostics: DiagnosticSink, origins: Origins): JsonObject;