@shipworthy/openapi-parser 0.0.0-stage → 0.0.2

package/dist/upgraders/3.0-to-3.1.js

@@ -0,0 +1,310 @@
+import { JsonSchema, Predicate } from "effect";
+import { OpenApiHttpMethod } from "../schemas/3.1/http-method.js";
+function asRecord(value) {
+    return Predicate.isObject(value) ? value : undefined;
+}
+const METHODS = new Set(OpenApiHttpMethod.literals);
+const SINGLE_KEYS = [
+    "not",
+    "additionalProperties",
+    "unevaluatedProperties",
+    "items",
+    "additionalItems",
+    "contains",
+    "if",
+    "then",
+    "else",
+    "propertyNames",
+    "unevaluatedItems",
+    "contentSchema",
+];
+const ARRAY_KEYS = ["allOf", "anyOf", "oneOf", "prefixItems"];
+const MAP_KEYS = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"];
+export function isOpenApi3(document) {
+    const record = asRecord(document);
+    return typeof record?.openapi === "string" && record.openapi.startsWith("3.");
+}
+export function isOpenApi3_0(document) {
+    const record = asRecord(document);
+    return typeof record?.openapi === "string" && record.openapi.startsWith("3.0");
+}
+export function upgradeOpenApi3_0(document) {
+    if (!isOpenApi3_0(document))
+        return;
+    for (const slot of schemaSlots(document)) {
+        slot.parent[slot.key] = upgradeSchema(slot.parent[slot.key]);
+    }
+    document.openapi = "3.1.0";
+}
+export function schemaSlots(document, includeComponentSchemas = true) {
+    const slots = [];
+    const components = asRecord(document.components);
+    if (components) {
+        if (includeComponentSchemas)
+            collectSchemaMap(components.schemas, slots);
+        collectParameterMap(components.parameters, slots);
+        collectResponseMap(components.responses, slots);
+        collectRequestBodyMap(components.requestBodies, slots);
+        collectHeaderMap(components.headers, slots);
+        const pathItems = asRecord(components.pathItems);
+        if (pathItems) {
+            for (const value of Object.values(pathItems))
+                collectPathItem(value, slots);
+        }
+    }
+    const paths = asRecord(document.paths);
+    if (paths) {
+        for (const value of Object.values(paths))
+            collectPathItem(value, slots);
+    }
+    const webhooks = asRecord(document.webhooks);
+    if (webhooks) {
+        for (const value of Object.values(webhooks))
+            collectPathItem(value, slots);
+    }
+    return slots;
+}
+export function componentSchemas(document) {
+    const slots = [];
+    collectSchemaMap(asRecord(document.components)?.schemas, slots);
+    return slots;
+}
+function collectSchemaMap(value, slots) {
+    const map = asRecord(value);
+    if (!map)
+        return;
+    for (const key of Object.keys(map))
+        slots.push({ parent: map, key });
+}
+function collectParameterMap(value, slots) {
+    const map = asRecord(value);
+    if (!map)
+        return;
+    for (const parameter of Object.values(map))
+        collectParameter(parameter, slots);
+}
+function collectResponseMap(value, slots) {
+    const map = asRecord(value);
+    if (!map)
+        return;
+    for (const response of Object.values(map))
+        collectResponse(response, slots);
+}
+function collectRequestBodyMap(value, slots) {
+    const map = asRecord(value);
+    if (!map)
+        return;
+    for (const body of Object.values(map))
+        collectRequestBody(body, slots);
+}
+function collectHeaderMap(value, slots) {
+    const map = asRecord(value);
+    if (!map)
+        return;
+    for (const header of Object.values(map))
+        collectHeader(header, slots);
+}
+function collectPathItem(value, slots) {
+    const record = asRecord(value);
+    if (!record || typeof record.$ref === "string")
+        return;
+    collectParameterList(record.parameters, slots);
+    for (const [key, child] of Object.entries(record)) {
+        if (METHODS.has(key))
+            collectOperation(child, slots);
+    }
+}
+function collectOperation(value, slots) {
+    const record = asRecord(value);
+    if (!record)
+        return;
+    collectParameterList(record.parameters, slots);
+    collectRequestBody(record.requestBody, slots);
+    const responses = asRecord(record.responses);
+    if (responses) {
+        for (const response of Object.values(responses))
+            collectResponse(response, slots);
+    }
+    const callbacks = asRecord(record.callbacks);
+    if (callbacks) {
+        for (const callback of Object.values(callbacks)) {
+            const paths = asRecord(callback);
+            if (!paths || typeof paths.$ref === "string")
+                continue;
+            for (const pathItem of Object.values(paths))
+                collectPathItem(pathItem, slots);
+        }
+    }
+}
+function collectParameterList(value, slots) {
+    if (!Array.isArray(value))
+        return;
+    for (const parameter of value)
+        collectParameter(parameter, slots);
+}
+function collectParameter(value, slots) {
+    const record = asRecord(value);
+    if (!record || typeof record.$ref === "string")
+        return;
+    if ("schema" in record)
+        slots.push({ parent: record, key: "schema" });
+    collectContent(record.content, slots);
+}
+function collectRequestBody(value, slots) {
+    const record = asRecord(value);
+    if (!record || typeof record.$ref === "string")
+        return;
+    collectContent(record.content, slots);
+}
+function collectResponse(value, slots) {
+    const record = asRecord(value);
+    if (!record || typeof record.$ref === "string")
+        return;
+    collectContent(record.content, slots);
+    collectHeaderMap(record.headers, slots);
+}
+function collectHeader(value, slots) {
+    const record = asRecord(value);
+    if (!record || typeof record.$ref === "string")
+        return;
+    if ("schema" in record)
+        slots.push({ parent: record, key: "schema" });
+    collectContent(record.content, slots);
+}
+function collectContent(value, slots) {
+    const content = asRecord(value);
+    if (!content)
+        return;
+    for (const media of Object.values(content)) {
+        const mediaRecord = asRecord(media);
+        if (mediaRecord && "schema" in mediaRecord)
+            slots.push({ parent: mediaRecord, key: "schema" });
+    }
+}
+function upgradeSchema(value) {
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    for (const key of SINGLE_KEYS) {
+        if (!(key in record))
+            continue;
+        if (key === "items" && Array.isArray(record.items)) {
+            record.items = record.items.map((item) => upgradeSchema(item));
+        }
+        else {
+            record[key] = upgradeSchema(record[key]);
+        }
+    }
+    for (const key of ARRAY_KEYS) {
+        if (Array.isArray(record[key]))
+            record[key] = record[key].map((item) => upgradeSchema(item));
+    }
+    for (const key of MAP_KEYS) {
+        const map = asRecord(record[key]);
+        if (!map)
+            continue;
+        for (const child of Object.keys(map))
+            map[child] = upgradeSchema(map[child]);
+    }
+    if (Array.isArray(record.items)) {
+        record.prefixItems = record.items;
+        if ("additionalItems" in record) {
+            record.items = record.additionalItems;
+            delete record.additionalItems;
+        }
+        else {
+            delete record.items;
+        }
+    }
+    if (typeof record.$ref === "string" && Object.keys(record).some((key) => key !== "$ref")) {
+        const nullable = record.nullable === true;
+        const readOnly = record.readOnly === true;
+        const writeOnly = record.writeOnly === true;
+        const { $ref, ...siblings } = record;
+        delete siblings.nullable;
+        if (readOnly)
+            delete siblings.readOnly;
+        if (writeOnly)
+            delete siblings.writeOnly;
+        // OpenAPI 3.0 ignores the siblings of a $ref; 3.1 applies them, so they move into allOf
+        const target = Object.keys(siblings).length > 0 ? { allOf: [{ $ref }, siblings] } : { $ref };
+        const lifted = nullable ? orNull(target) : target;
+        if (readOnly)
+            lifted.readOnly = true;
+        if (writeOnly)
+            lifted.writeOnly = true;
+        return lifted;
+    }
+    return applyOpenApi30Keywords(record);
+}
+/** Keywords that describe a schema without constraining it. They stay outside `orNull`'s `anyOf`. */
+const ANNOTATION_KEYS = new Set([
+    "title",
+    "description",
+    "default",
+    "deprecated",
+    "readOnly",
+    "writeOnly",
+    "example",
+    "examples",
+    "externalDocs",
+    "xml",
+    "$comment",
+]);
+/** `schema` or null, as `anyOf: [schema, { type: "null" }]`. Annotations and extensions stay outside. */
+function orNull(schema) {
+    const outer = {};
+    const inner = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (ANNOTATION_KEYS.has(key) || key.startsWith("x-"))
+            outer[key] = value;
+        else
+            inner[key] = value;
+    }
+    return Object.keys(inner).length === 0 ? schema : { ...outer, anyOf: [inner, { type: "null" }] };
+}
+function applyOpenApi30Keywords(schema) {
+    const nullable = schema.nullable === true;
+    delete schema.nullable;
+    if (typeof schema.exclusiveMinimum === "boolean" ||
+        typeof schema.exclusiveMaximum === "boolean") {
+        const projection = {};
+        if ("minimum" in schema)
+            projection.minimum = schema.minimum;
+        if ("maximum" in schema)
+            projection.maximum = schema.maximum;
+        if ("exclusiveMinimum" in schema)
+            projection.exclusiveMinimum = schema.exclusiveMinimum;
+        if ("exclusiveMaximum" in schema)
+            projection.exclusiveMaximum = schema.exclusiveMaximum;
+        const converted = JsonSchema.fromSchemaOpenApi3_0(projection).schema;
+        delete schema.minimum;
+        delete schema.maximum;
+        delete schema.exclusiveMinimum;
+        delete schema.exclusiveMaximum;
+        for (const key of ["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum"]) {
+            if (key in converted)
+                schema[key] = converted[key];
+        }
+    }
+    if ("example" in schema) {
+        const converted = JsonSchema.fromSchemaOpenApi3_0({ example: schema.example }).schema;
+        const existing = Array.isArray(schema.examples) ? schema.examples : [];
+        const convertedExamples = Array.isArray(converted.examples) ? converted.examples : [];
+        schema.examples = [...convertedExamples, ...existing];
+        delete schema.example;
+    }
+    if (!nullable)
+        return schema;
+    // A "null" type can only join a schema's own type. Compositions have to hold for null too,
+    // so a schema with allOf/anyOf/oneOf, or without a type, becomes a disjunction instead.
+    const composed = "allOf" in schema || "anyOf" in schema || "oneOf" in schema;
+    if (typeof schema.type === "string" && !composed) {
+        const converted = JsonSchema.fromSchemaOpenApi3_0({ type: schema.type, nullable: true }).schema;
+        schema.type = converted.type;
+        if (Array.isArray(schema.enum) && !schema.enum.includes(null))
+            schema.enum = [...schema.enum, null];
+        return schema;
+    }
+    return orNull(schema);
+}

package/dist/url.d.ts

@@ -0,0 +1,29 @@
+import { Effect } from "effect";
+import { ResolverFailure } from "./errors.ts";
+export interface ResolvedUrlAddress {
+    address: string;
+    family: number;
+}
+export interface UrlSafety {
+    unsafe: boolean;
+    addresses?: ResolvedUrlAddress[];
+}
+export declare function stripHash(value: string): string;
+export declare function getHash(value: string): string;
+export declare function isHttp(value: string): boolean;
+export declare function isFileSystemPath(value: string | undefined): boolean;
+export declare function httpOrigin(value: string): string | undefined;
+export declare const normalizeRef: (input: string | undefined) => Effect.Effect<string, ResolverFailure, never>;
+export declare function resolveAgainst(from: string, to: string): string;
+export declare function toFileSystemPath(ref: string): string;
+export declare function extensionOf(ref: string): string;
+export declare function isUnsafeUrl(value: string): boolean;
+export declare function isAllowedOrigin(href: string, allowedOrigins: readonly string[] | undefined): boolean;
+export declare const resolveUrlSafety: (href: string) => Effect.Effect<{
+    unsafe: boolean;
+    addresses?: undefined;
+} | {
+    unsafe: boolean;
+    addresses: import("dns").LookupAddress[];
+}, ResolverFailure, never>;
+export declare function isUnsafeHostname(hostname: string): boolean;

package/dist/url.js

@@ -0,0 +1,255 @@
+import * as NodePath from "@effect/platform-node/NodePath";
+import { fileURLToPath } from "node:url";
+import { Effect, Path } from "effect";
+import { ResolverFailure, nodeErrorCode } from "./errors.js";
+const unsafeDomainSuffixes = [
+    ".localhost",
+    ".local",
+    ".internal",
+    ".intranet",
+    ".corp",
+    ".home",
+    ".lan",
+];
+export function stripHash(value) {
+    const index = value.indexOf("#");
+    return index === -1 ? value : value.slice(0, index);
+}
+export function getHash(value) {
+    const index = value.indexOf("#");
+    if (index === -1)
+        return "#";
+    return value.slice(index) || "#";
+}
+export function isHttp(value) {
+    return /^https?:\/\//i.test(value);
+}
+export function isFileSystemPath(value) {
+    if (!value)
+        return false;
+    if (value.startsWith("file:"))
+        return true;
+    return !/^[a-z][a-z0-9+.-]*:/i.test(value);
+}
+export function httpOrigin(value) {
+    try {
+        const parsed = new URL(value);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+            return undefined;
+        return parsed.origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const normalizeRef = Effect.fnUntraced(function* (input) {
+    if (input && /^[a-z][a-z0-9+.-]*:/i.test(input))
+        return input;
+    const path = yield* Path.Path;
+    const absolute = !input || input === "/" ? `${path.resolve(".")}${path.sep}` : path.resolve(input);
+    return yield* path.toFileUrl(absolute).pipe(Effect.map((url) => url.href), Effect.mapError((cause) => new ResolverFailure({
+        message: cause.message,
+        source: input ?? "",
+        cause,
+    })));
+}, Effect.provide(NodePath.layer));
+export function resolveAgainst(from, to) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(to))
+        return to;
+    return new URL(to, stripHash(from)).href;
+}
+export function toFileSystemPath(ref) {
+    const withoutHash = stripHash(ref);
+    if (withoutHash.startsWith("file:"))
+        return fileURLToPath(withoutHash);
+    return withoutHash;
+}
+export function extensionOf(ref) {
+    const pathname = stripHash(ref).split("?")[0] ?? "";
+    const base = pathname.slice(Math.max(pathname.lastIndexOf("/"), pathname.lastIndexOf("\\")) + 1);
+    const dot = base.lastIndexOf(".");
+    return dot >= 0 ? base.slice(dot).toLowerCase() : "";
+}
+export function isUnsafeUrl(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized)
+        return true;
+    if (normalized.startsWith("javascript:") ||
+        normalized.startsWith("vbscript:") ||
+        normalized.startsWith("data:")) {
+        return true;
+    }
+    if (normalized.startsWith("file:"))
+        return true;
+    try {
+        const url = new URL(normalized.startsWith("//") ? `http:${normalized}` : normalized);
+        if (isUnsafeHostname(url.hostname))
+            return true;
+        if (url.port && isInternalPort(Number(url.port)))
+            return true;
+    }
+    catch {
+        return false;
+    }
+    return false;
+}
+export function isAllowedOrigin(href, allowedOrigins) {
+    const origin = httpOrigin(href);
+    if (!origin || !allowedOrigins?.length)
+        return false;
+    return allowedOrigins.some((allowed) => httpOrigin(allowed) === origin);
+}
+export const resolveUrlSafety = Effect.fnUntraced(function* (href) {
+    if (isUnsafeUrl(href))
+        return { unsafe: true };
+    if (typeof process === "undefined" || !process.versions?.node)
+        return { unsafe: false };
+    const parsed = URL.parse(href.startsWith("//") ? `http:${href}` : href);
+    if (parsed === null)
+        return { unsafe: true };
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return { unsafe: false };
+    const onError = (cause) => new ResolverFailure({
+        message: `Error downloading ${href}: ${cause instanceof Error ? cause.message : String(cause)}`,
+        source: href,
+        cause,
+        ...ioCode(cause),
+    });
+    const dns = yield* Effect.tryPromise({
+        try: () => import("node:dns/promises"),
+        catch: onError,
+    });
+    const addresses = yield* Effect.tryPromise({
+        try: () => dns.lookup(normalizeHostname(parsed.hostname), { all: true, verbatim: true }),
+        catch: onError,
+    });
+    if (addresses.length === 0 || addresses.some(({ address }) => isUnsafeHostname(address))) {
+        return { unsafe: true };
+    }
+    return { unsafe: false, addresses };
+});
+export function isUnsafeHostname(hostname) {
+    const normalized = normalizeHostname(hostname);
+    if (!normalized)
+        return true;
+    if (normalized === "localhost" ||
+        unsafeDomainSuffixes.some((suffix) => normalized.endsWith(suffix)))
+        return true;
+    const ipv4 = parseIPv4Address(normalized);
+    if (ipv4)
+        return isUnsafeIPv4Address(ipv4);
+    const ipv6 = parseIPv6Address(normalized);
+    if (ipv6)
+        return isUnsafeIPv6Address(ipv6);
+    return false;
+}
+function ioCode(cause) {
+    const ioErrorCode = nodeErrorCode(cause);
+    return ioErrorCode ? { ioErrorCode } : undefined;
+}
+function normalizeHostname(hostname) {
+    let normalized = hostname.trim().toLowerCase();
+    if (normalized.startsWith("[") && normalized.endsWith("]"))
+        normalized = normalized.slice(1, -1);
+    while (normalized.endsWith("."))
+        normalized = normalized.slice(0, -1);
+    return normalized;
+}
+function parseIPv4Address(ip) {
+    const parts = ip.split(".");
+    if (parts.length !== 4)
+        return undefined;
+    const octets = parts.map((part) => (/^\d+$/.test(part) ? Number(part) : Number.NaN));
+    if (octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255))
+        return undefined;
+    return octets;
+}
+function isUnsafeIPv4Address(octets) {
+    const a = octets[0];
+    const b = octets[1];
+    const c = octets[2];
+    const d = octets[3];
+    if (a === undefined || b === undefined || c === undefined || d === undefined)
+        return true;
+    return (a === 0 ||
+        a === 10 ||
+        a === 127 ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 0 && c === 0) ||
+        (a === 192 && b === 168) ||
+        (a === 198 && (b === 18 || b === 19)) ||
+        a >= 224 ||
+        (a === 255 && b === 255 && c === 255 && d === 255));
+}
+function parseIPv6Address(ip) {
+    if (!ip.includes(":"))
+        return undefined;
+    let normalized = ip;
+    const lastSeparator = normalized.lastIndexOf(":");
+    const possibleIPv4 = normalized.slice(lastSeparator + 1);
+    if (possibleIPv4.includes(".")) {
+        const ipv4 = parseIPv4Address(possibleIPv4);
+        if (!ipv4)
+            return undefined;
+        const firstGroup = ipv4[0] * 256 + ipv4[1];
+        const secondGroup = ipv4[2] * 256 + ipv4[3];
+        normalized = `${normalized.slice(0, lastSeparator + 1)}${firstGroup.toString(16)}:${secondGroup.toString(16)}`;
+    }
+    const halves = normalized.split("::");
+    if (halves.length > 2)
+        return undefined;
+    const head = parseIPv6Groups(halves[0] ?? "");
+    const tail = halves.length === 2 ? parseIPv6Groups(halves[1] ?? "") : [];
+    if (!head || !tail)
+        return undefined;
+    if (halves.length === 1)
+        return head.length === 8 ? head : undefined;
+    const missing = 8 - head.length - tail.length;
+    if (missing < 1)
+        return undefined;
+    return [...head, ...Array(missing).fill(0), ...tail];
+}
+function parseIPv6Groups(groups) {
+    if (!groups)
+        return [];
+    const parsed = groups
+        .split(":")
+        .map((group) => (/^[\da-f]{1,4}$/i.test(group) ? Number.parseInt(group, 16) : Number.NaN));
+    if (parsed.some((group) => !Number.isInteger(group) || group < 0 || group > 0xffff))
+        return undefined;
+    return parsed;
+}
+function isUnsafeIPv6Address(groups) {
+    if (groups.length !== 8)
+        return false;
+    const unspecified = groups.every((group) => group === 0);
+    const loopback = groups.slice(0, 7).every((group) => group === 0) && groups[7] === 1;
+    const uniqueLocal = (groups[0] & 0xfe00) === 0xfc00;
+    const linkLocal = (groups[0] & 0xffc0) === 0xfe80;
+    const multicast = (groups[0] & 0xff00) === 0xff00;
+    if (unspecified || loopback || uniqueLocal || linkLocal || multicast)
+        return true;
+    const mapped = mappedIPv4(groups);
+    return mapped ? isUnsafeIPv4Address(mapped) : false;
+}
+function mappedIPv4(groups) {
+    const firstFive = groups.slice(0, 5).every((group) => group === 0);
+    const firstSix = firstFive && groups[5] === 0;
+    const v4Mapped = firstFive && groups[5] === 0xffff;
+    if (!firstSix && !v4Mapped)
+        return undefined;
+    return [
+        Math.floor(groups[6] / 256),
+        groups[6] % 256,
+        Math.floor(groups[7] / 256),
+        groups[7] % 256,
+    ];
+}
+function isInternalPort(port) {
+    return [
+        22, 23, 25, 53, 135, 139, 445, 993, 995, 1433, 1521, 3306, 3389, 5432, 5900, 6379, 8080, 8443,
+        9200, 27017,
+    ].includes(port);
+}

package/dist/yaml.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Effect's YAML decoder rejects `- - value` and treats `<<` as a normal key.
+ * OpenAPI fixtures in this repo use both, so expand those forms before parsing.
+ */
+export declare function parseYamlDocument(source: string): unknown;
+export declare function expandCompactNestedSequences(source: string): string;