@sezzlee/openapi 0.0.0-stage → 0.2.0

package/dist/parse/swagger2.js

@@ -0,0 +1,394 @@
+import { childPointer, rootPointer } from "../ir/brand.js";
+import { arrayOf, entriesOf, isObject, objectOf, stringOf, } from "../ir/json.js";
+const methods = [
+    "get",
+    "put",
+    "post",
+    "delete",
+    "options",
+    "head",
+    "patch",
+];
+const schemaKeys = [
+    "type",
+    "format",
+    "items",
+    "enum",
+    "default",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "minLength",
+    "maxLength",
+    "pattern",
+    "minItems",
+    "maxItems",
+    "uniqueItems",
+    "multipleOf",
+];
+function located(context, node, at) {
+    context.origins.set(node, at);
+    return node;
+}
+/**
+ * Rewrites every 2.0 reference target to its 3.x home. `#/parameters` and `#/responses` point at
+ * 2.0 shapes that are converted in place under the same names, so their references move with them.
+ */
+function rewriteRefs(value) {
+    if (Array.isArray(value)) {
+        return value.map(rewriteRefs);
+    }
+    if (!isObject(value)) {
+        return value;
+    }
+    const out = {};
+    for (const [key, child] of entriesOf(value)) {
+        if (key === "$ref" && typeof child === "string") {
+            out[key] = child
+                .replace(/^#\/definitions\//, "#/components/schemas/")
+                .replace(/^#\/parameters\//, "#/components/parameters/")
+                .replace(/^#\/responses\//, "#/components/responses/");
+        }
+        else if (key === "x-nullable" && child === true) {
+            out["nullable"] = true;
+        }
+        else {
+            out[key] = rewriteRefs(child);
+        }
+    }
+    if (out["type"] === "file") {
+        out["type"] = "string";
+        out["format"] = "binary";
+    }
+    return out;
+}
+function resolveParameter(context, parameter) {
+    const node = objectOf(parameter);
+    const ref = stringOf(node?.["$ref"]);
+    if (ref === undefined) {
+        return node;
+    }
+    const name = /^#\/parameters\/(.+)$/.exec(ref)?.[1];
+    return name === undefined
+        ? undefined
+        : objectOf(objectOf(context.document["parameters"])?.[name]);
+}
+function styleFor(location, collectionFormat, context, at) {
+    switch (collectionFormat ?? "csv") {
+        case "csv":
+            return location === "path" || location === "header"
+                ? { style: "simple", explode: false }
+                : { style: "form", explode: false };
+        case "ssv":
+            if (location === "query") {
+                return { style: "spaceDelimited", explode: false };
+            }
+            break;
+        case "pipes":
+            if (location === "query") {
+                return { style: "pipeDelimited", explode: false };
+            }
+            break;
+        case "multi":
+            if (location === "query") {
+                return { style: "form", explode: true };
+            }
+            break;
+    }
+    context.diagnostics.report("unsupported_collection_format", at, `collectionFormat '${collectionFormat ?? "csv"}' has no ${location} form.`);
+    return undefined;
+}
+function schemaOfSimple(node) {
+    const schema = {};
+    for (const key of schemaKeys) {
+        if (node[key] !== undefined) {
+            schema[key] = rewriteRefs(node[key]);
+        }
+    }
+    return schema;
+}
+function upgradeParameter(context, parameter, at) {
+    const location = stringOf(parameter["in"]) ?? "query";
+    const out = {
+        name: parameter["name"],
+        in: location,
+        ...(parameter["required"] === undefined
+            ? {}
+            : { required: parameter["required"] }),
+        ...(parameter["description"] === undefined
+            ? {}
+            : { description: parameter["description"] }),
+        schema: schemaOfSimple(parameter),
+    };
+    if (parameter["allowEmptyValue"] !== undefined) {
+        out["allowEmptyValue"] = parameter["allowEmptyValue"];
+    }
+    if (parameter["type"] === "array") {
+        const style = styleFor(location, stringOf(parameter["collectionFormat"]), context, at);
+        if (style === undefined) {
+            return "drop";
+        }
+        Object.assign(out, style);
+    }
+    return located(context, out, at);
+}
+function upgradeParameters(context, parameters, consumes, at) {
+    const out = [];
+    const form = { type: "object", properties: {} };
+    const formRequired = [];
+    let hasFormField = false;
+    let hasFile = false;
+    let requestBody;
+    let dropped = false;
+    parameters.forEach((raw, index) => {
+        const parameterAt = childPointer(at, index);
+        const parameter = resolveParameter(context, raw);
+        if (parameter === undefined) {
+            out.push(rewriteRefs(raw));
+            return;
+        }
+        const location = stringOf(parameter["in"]);
+        if (location === "body") {
+            const content = {};
+            for (const mediaType of consumes) {
+                content[mediaType] = {
+                    schema: rewriteRefs(parameter["schema"] ?? {}),
+                };
+            }
+            requestBody = located(context, {
+                content,
+                required: parameter["required"] === true,
+                ...(parameter["description"] === undefined
+                    ? {}
+                    : { description: parameter["description"] }),
+            }, parameterAt);
+            return;
+        }
+        if (location === "formData") {
+            hasFormField = true;
+            const name = stringOf(parameter["name"]) ?? "";
+            const schema = schemaOfSimple(parameter);
+            if (schema["type"] === "file") {
+                hasFile = true;
+                schema["type"] = "string";
+                schema["format"] = "binary";
+            }
+            const collectionFormat = stringOf(parameter["collectionFormat"]);
+            if (parameter["type"] === "array" &&
+                collectionFormat !== undefined &&
+                collectionFormat !== "multi") {
+                context.diagnostics.report("unsupported_encoding", parameterAt, `A form field with collectionFormat '${collectionFormat}' has no form-body writer; only repeated keys are written.`);
+                dropped = true;
+            }
+            form["properties"][name] = located(context, schema, parameterAt);
+            if (parameter["required"] === true) {
+                formRequired.push(name);
+            }
+            return;
+        }
+        const upgraded = upgradeParameter(context, parameter, parameterAt);
+        if (upgraded === "drop") {
+            dropped = true;
+            return;
+        }
+        out.push(upgraded);
+    });
+    if (hasFormField) {
+        const mediaType = hasFile || consumes.includes("multipart/form-data")
+            ? "multipart/form-data"
+            : "application/x-www-form-urlencoded";
+        if (formRequired.length > 0) {
+            form["required"] = formRequired;
+        }
+        requestBody = {
+            content: { [mediaType]: { schema: form } },
+            required: formRequired.length > 0,
+        };
+    }
+    return {
+        parameters: out,
+        ...(requestBody === undefined ? {} : { requestBody }),
+        dropped,
+    };
+}
+function upgradeResponses(context, responses, produces, at) {
+    const out = {};
+    for (const [code, raw] of entriesOf(responses)) {
+        const response = objectOf(raw);
+        if (response === undefined) {
+            continue;
+        }
+        if (stringOf(response["$ref"]) !== undefined) {
+            out[code] = rewriteRefs(response);
+            continue;
+        }
+        const converted = {
+            description: response["description"] ?? "",
+        };
+        if (response["schema"] !== undefined) {
+            const content = {};
+            for (const mediaType of produces) {
+                content[mediaType] = { schema: rewriteRefs(response["schema"]) };
+            }
+            converted["content"] = content;
+        }
+        out[code] = located(context, converted, childPointer(at, code));
+    }
+    return out;
+}
+function upgradeSecuritySchemes(definitions) {
+    const out = {};
+    for (const [name, raw] of entriesOf(definitions)) {
+        const scheme = objectOf(raw);
+        if (scheme === undefined) {
+            continue;
+        }
+        switch (stringOf(scheme["type"])) {
+            case "basic":
+                out[name] = { type: "http", scheme: "basic" };
+                break;
+            case "apiKey":
+                out[name] = { type: "apiKey", in: scheme["in"], name: scheme["name"] };
+                break;
+            case "oauth2": {
+                const flow = {
+                    implicit: "implicit",
+                    password: "password",
+                    application: "clientCredentials",
+                    accessCode: "authorizationCode",
+                }[stringOf(scheme["flow"]) ?? ""] ?? "clientCredentials";
+                out[name] = {
+                    type: "oauth2",
+                    flows: {
+                        [flow]: {
+                            ...(scheme["authorizationUrl"] === undefined
+                                ? {}
+                                : { authorizationUrl: scheme["authorizationUrl"] }),
+                            ...(scheme["tokenUrl"] === undefined
+                                ? {}
+                                : { tokenUrl: scheme["tokenUrl"] }),
+                            scopes: scheme["scopes"] ?? {},
+                        },
+                    },
+                };
+                break;
+            }
+        }
+    }
+    return out;
+}
+function serversOf(document) {
+    const basePath = stringOf(document["basePath"]) ?? "";
+    const host = stringOf(document["host"]);
+    if (host === undefined) {
+        return [{ url: basePath === "" ? "/" : basePath }];
+    }
+    const schemes = arrayOf(document["schemes"])
+        .map(stringOf)
+        .filter((scheme) => scheme !== undefined);
+    const ordered = schemes.length === 0 ? ["https"] : schemes;
+    return [...ordered]
+        .sort((a, b) => Number(b === "https") - Number(a === "https"))
+        .map((scheme) => ({ url: `${scheme}://${host}${basePath}` }));
+}
+const mediaTypes = (value) => {
+    const list = arrayOf(value)
+        .map(stringOf)
+        .filter((item) => item !== undefined);
+    return list.length === 0 ? undefined : list;
+};
+/**
+ * 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 function upgradeSwagger2(document, diagnostics, origins) {
+    const context = { document, diagnostics, origins };
+    const rootConsumes = mediaTypes(document["consumes"]) ?? ["application/json"];
+    const rootProduces = mediaTypes(document["produces"]) ?? ["application/json"];
+    const componentParameters = {};
+    for (const [name, raw] of entriesOf(document["parameters"])) {
+        const parameter = objectOf(raw);
+        const location = stringOf(parameter?.["in"]);
+        if (parameter !== undefined &&
+            location !== "body" &&
+            location !== "formData") {
+            const upgraded = upgradeParameter(context, parameter, childPointer(rootPointer, "parameters", name));
+            if (upgraded !== "drop") {
+                componentParameters[name] = upgraded;
+            }
+        }
+    }
+    const paths = {};
+    for (const [path, rawItem] of entriesOf(document["paths"])) {
+        const item = objectOf(rawItem);
+        if (item === undefined) {
+            continue;
+        }
+        const itemAt = childPointer(rootPointer, "paths", path);
+        const shared = arrayOf(item["parameters"]);
+        const converted = {};
+        for (const method of methods) {
+            const operation = objectOf(item[method]);
+            if (operation === undefined) {
+                continue;
+            }
+            const operationAt = childPointer(itemAt, method);
+            const consumes = mediaTypes(operation["consumes"]) ?? rootConsumes;
+            const produces = mediaTypes(operation["produces"]) ?? rootProduces;
+            const own = arrayOf(operation["parameters"]);
+            const ownKeys = new Set(own
+                .map((parameter) => resolveParameter(context, parameter))
+                .map((parameter) => parameter === undefined
+                ? ""
+                : `${stringOf(parameter["in"])}|${stringOf(parameter["name"])}`));
+            const inherited = shared.filter((parameter) => {
+                const resolved = resolveParameter(context, parameter);
+                return (resolved === undefined ||
+                    !ownKeys.has(`${stringOf(resolved["in"])}|${stringOf(resolved["name"])}`));
+            });
+            const upgraded = upgradeParameters(context, [...inherited, ...own], consumes, childPointer(operationAt, "parameters"));
+            const out = {};
+            for (const [key, value] of entriesOf(operation)) {
+                if (key === "parameters" ||
+                    key === "consumes" ||
+                    key === "produces" ||
+                    key === "responses" ||
+                    key === "schemes") {
+                    continue;
+                }
+                out[key] = rewriteRefs(value);
+            }
+            out["parameters"] = upgraded.parameters;
+            if (upgraded.requestBody !== undefined) {
+                out["requestBody"] = upgraded.requestBody;
+            }
+            out["responses"] = upgradeResponses(context, operation["responses"], produces, childPointer(operationAt, "responses"));
+            if (upgraded.dropped) {
+                out["x-sezzlee-dropped"] = true;
+            }
+            converted[method] = located(context, out, operationAt);
+        }
+        paths[path] = located(context, converted, itemAt);
+    }
+    const componentResponses = {};
+    const upgradedResponses = upgradeResponses(context, document["responses"], rootProduces, childPointer(rootPointer, "responses"));
+    Object.assign(componentResponses, upgradedResponses);
+    return {
+        openapi: "3.0.3",
+        info: document["info"] ?? {},
+        servers: serversOf(document),
+        paths,
+        components: {
+            schemas: rewriteRefs(document["definitions"] ?? {}),
+            parameters: componentParameters,
+            responses: componentResponses,
+            securitySchemes: upgradeSecuritySchemes(document["securityDefinitions"]),
+        },
+        ...(document["security"] === undefined
+            ? {}
+            : { security: document["security"] }),
+        ...(document["tags"] === undefined ? {} : { tags: document["tags"] }),
+    };
+}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@sezzlee/openapi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Ingests a Swagger 2.0 or OpenAPI 3.0–3.2 document into the endpoint descriptors the sezzlee catalog is built from.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "sezzlee",
+    "openapi",
+    "swagger",
+    "agents",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sezzlee/mcp.git",
+    "directory": "packages/http/openapi"
+  },
+  "homepage": "https://github.com/sezzlee/mcp/tree/main/packages/http/openapi#readme",
+  "bugs": {
+    "url": "https://github.com/sezzlee/mcp/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@sezzlee/core": "^0.2.0",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@sezzlee/oxlint-config": "0.0.0",
+    "@sezzlee/typescript-config": "0.0.0",
+    "@types/node": "^24.3.0",
+    "oxlint": "1.85.0",
+    "typescript": "7.0.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "dev": "tsc --watch",
+    "lint": "oxlint --deny-warnings",
+    "check-types": "tsc -p tsconfig.test.json",
+    "test": "vitest run"
+  }
 }