@shipworthy/openapi-parser 0.0.0-stage → 0.0.1

package/dist/hoist.js

@@ -0,0 +1,444 @@
+import { Predicate, Schema } from "effect";
+import { MissingPointerFailure, bundleFailure } from "./errors.js";
+import { cloneData, getAt, joinPointer, parsePointer, setAt } from "./pointer.js";
+import { getHash, isFileSystemPath, isHttp, stripHash } from "./url.js";
+const MAX_ATTEMPTS = 1000;
+function asRecord(value) {
+    return Predicate.isObject(value) ? value : undefined;
+}
+const MAX_PASSES = 100_000;
+export function findExternalRef(root, keep, abandoned = new Set()) {
+    const stack = [{ node: root, pointer: "#" }];
+    const seen = new Set();
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (typeof current.node !== "object" || current.node === null)
+            continue;
+        if (seen.has(current.node))
+            continue;
+        seen.add(current.node);
+        if (Array.isArray(current.node)) {
+            for (let index = current.node.length - 1; index >= 0; index--) {
+                stack.push({
+                    node: current.node[index],
+                    pointer: joinPointer(current.pointer, String(index)),
+                    parent: current.node,
+                    key: String(index),
+                });
+            }
+            continue;
+        }
+        const record = current.node;
+        if (current.parent &&
+            current.key &&
+            typeof record.$ref === "string" &&
+            !record.$ref.startsWith("#") &&
+            !keep(record.$ref) &&
+            !abandoned.has(current.pointer)) {
+            return {
+                parent: current.parent,
+                key: current.key,
+                ref: record.$ref,
+                pointer: current.pointer,
+            };
+        }
+        const keys = Object.keys(record);
+        for (let index = keys.length - 1; index >= 0; index--) {
+            const key = keys[index];
+            stack.push({
+                node: record[key],
+                pointer: joinPointer(current.pointer, key),
+                parent: record,
+                key,
+            });
+        }
+    }
+    return undefined;
+}
+export function hoistExternalRefs(root, readValue, hooks, keep) {
+    const placed = new Map();
+    const componentSource = new Map();
+    const buckets = new Map();
+    const abandoned = new Set();
+    for (let pass = 0; pass < MAX_PASSES; pass++) {
+        const found = findExternalRef(root, keep, abandoned);
+        if (!found) {
+            collapseRefChains(root);
+            return placed;
+        }
+        const url = stripHash(found.ref);
+        const hash = getHash(found.ref);
+        const placeKey = `${url}${hash}`;
+        if (readValue(url) === undefined) {
+            abandoned.add(found.pointer);
+            continue;
+        }
+        // Some documents put `$ref` under `properties`, so the map itself is the reference.
+        // Rewriting that to a component `$ref` leaves a string where a schema object is required.
+        if (found.key === "properties" || found.key === "patternProperties") {
+            const inlined = cloneData(valueAt(readValue(url), hash, found.ref));
+            rebaseInternalRefs(inlined, url);
+            inlineRef(found, inlined, hooks);
+            continue;
+        }
+        const existing = placed.get(placeKey);
+        if (existing) {
+            rewriteRef(found, existing, hooks);
+            continue;
+        }
+        const value = cloneData(valueAt(readValue(url), hash, found.ref));
+        rebaseInternalRefs(value, url);
+        const rootName = oas3DefaultRoot(found.pointer);
+        const identical = rootName
+            ? matchingComponent(root, rootName, value, url, componentSource)
+            : undefined;
+        if (identical) {
+            placed.set(placeKey, identical);
+            rewriteRef(found, identical, hooks);
+            continue;
+        }
+        const reserveName = rootName === "#/components/schemas" && childReservesName(value, fileBaseName(url));
+        const target = generateKey(root, url, hash, found.pointer, buckets, reserveName);
+        if (target) {
+            setAt(root, target, value);
+            placed.set(placeKey, target);
+            componentSource.set(target, url);
+            rewriteRef(found, target, hooks);
+        }
+        else {
+            inlineRef(found, value, hooks);
+            placed.set(placeKey, found.pointer);
+        }
+    }
+    throw bundleFailure("Could not finish bundling external references.");
+}
+function valueAt(document, hash, ref) {
+    if (hash === "#")
+        return document;
+    return getAt(document, hash, ref);
+}
+function rebaseInternalRefs(value, fileUrl, seen = new Set()) {
+    if (typeof value !== "object" || value === null || seen.has(value))
+        return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value)
+            rebaseInternalRefs(item, fileUrl, seen);
+        return;
+    }
+    const record = value;
+    if (typeof record.$ref === "string" && record.$ref.startsWith("#"))
+        record.$ref = `${fileUrl}${record.$ref}`;
+    for (const child of Object.values(record))
+        rebaseInternalRefs(child, fileUrl, seen);
+}
+function collapseRefChains(root) {
+    for (let pass = 0; pass < 20; pass++) {
+        let changed = false;
+        const visit = (value, seen = new Set()) => {
+            if (typeof value !== "object" || value === null || seen.has(value))
+                return;
+            seen.add(value);
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    visit(item, seen);
+                return;
+            }
+            const record = value;
+            if (typeof record.$ref === "string" &&
+                record.$ref.startsWith("#") &&
+                Object.keys(record).length === 1) {
+                try {
+                    const target = asRecord(getAt(root, record.$ref, record.$ref));
+                    if (target &&
+                        typeof target.$ref === "string" &&
+                        Object.keys(target).length === 1 &&
+                        target.$ref !== record.$ref) {
+                        record.$ref = target.$ref;
+                        changed = true;
+                    }
+                }
+                catch (error) {
+                    if (!Schema.is(MissingPointerFailure)(error))
+                        throw error;
+                }
+            }
+            for (const child of Object.values(record))
+                visit(child, seen);
+        };
+        visit(root);
+        if (!changed)
+            return;
+    }
+}
+function rewriteRef(found, pointer, hooks) {
+    const current = found.parent[found.key];
+    const record = asRecord(current);
+    if (!record)
+        return;
+    record.$ref = pointer;
+    hooks?.onBundle?.(pointer, record, found.parent, found.key);
+}
+function inlineRef(found, value, hooks) {
+    const current = asRecord(found.parent[found.key]);
+    const siblings = { ...current };
+    delete siblings.$ref;
+    if (Object.keys(siblings).length === 0) {
+        found.parent[found.key] = value;
+    }
+    else if (oas3DefaultRoot(found.pointer) === "#/components/schemas" ||
+        found.pointer.includes("/schema")) {
+        found.parent[found.key] = { allOf: [value, siblings] };
+    }
+    else if (asRecord(value)) {
+        found.parent[found.key] = { ...asRecord(value), ...siblings };
+    }
+    else {
+        found.parent[found.key] = value;
+    }
+    hooks?.onBundle?.(found.ref, found.parent[found.key], found.parent, found.key);
+}
+function generateKey(schema, file, hash, pathFromRoot, buckets, childReservesBase = false) {
+    if (!isOpenApiDocument(schema))
+        return null;
+    const root = oas3DefaultRoot(pathFromRoot);
+    if (!root)
+        return null;
+    if (!isFileSystemPath(file) && !isHttp(file) && !file.includes("://"))
+        return null;
+    if (hash === "#" && isUnderDirectRoot(pathFromRoot, root))
+        return null;
+    const existing = existingComponentPointer(schema, file, hash, root);
+    if (existing && existing !== pathFromRoot)
+        return existing;
+    if (hash !== "#") {
+        if (isUnderDirectRoot(hash, root) || !isInRoot(hash, root)) {
+            const token = pointerTokens(hash).at(-1);
+            if (!token)
+                return null;
+            return register(schema, root, `${file}${hash}`, suggest(bucket(schema, root, buckets).taken, token, fileBaseName(file)), buckets);
+        }
+        const filePointer = keyForFile(schema, file, root, buckets);
+        if (filePointer == null)
+            return null;
+        return keyForPointer(schema, filePointer + hash.slice(1), root, buckets);
+    }
+    return keyForFile(schema, file, root, buckets, hash === "#" && childReservesBase);
+}
+function isOpenApiDocument(schema) {
+    return typeof schema.openapi === "string";
+}
+export function oas3DefaultRoot(pathFromRoot) {
+    const path = pathFromRoot.split("/");
+    if (canReferenceParameter(path))
+        return "#/components/parameters";
+    if (canReferenceResponse(path))
+        return "#/components/responses";
+    if (canReferenceRequestBody(path))
+        return "#/components/requestBodies";
+    if (canReferenceHeader(path))
+        return "#/components/headers";
+    if (canReferenceExample(path))
+        return "#/components/examples";
+    if (canReferenceSecurityScheme(path))
+        return "#/components/securitySchemes";
+    if (canReferenceLink(path))
+        return "#/components/links";
+    if (canReferenceCallback(path))
+        return "#/components/callbacks";
+    if (canReferenceSchema(path))
+        return "#/components/schemas";
+    return null;
+}
+function canReferenceSchema(path) {
+    return path.includes("schema") || (path[1] === "components" && path[2] === "schemas");
+}
+function canReferenceParameter(path) {
+    return path.at(-2) === "parameters";
+}
+function canReferenceResponse(path) {
+    return path.at(-2) === "responses";
+}
+function canReferenceRequestBody(path) {
+    return path.at(-1) === "requestBody";
+}
+function canReferenceHeader(path) {
+    return path.at(-2) === "headers";
+}
+function canReferenceExample(path) {
+    return path.at(-2) === "examples";
+}
+function canReferenceSecurityScheme(path) {
+    return path[1] === "components" && path[2] === "securitySchemes";
+}
+function canReferenceLink(path) {
+    return ((path[1] === "components" && path[2] === "links") ||
+        (path[1] === "paths" && path.includes("links")));
+}
+function canReferenceCallback(path) {
+    return ((path[1] === "components" && path[2] === "callbacks") ||
+        (path[1] === "paths" && path.includes("callbacks")));
+}
+function isUnderDirectRoot(pathFromRoot, root) {
+    const pointer = pointerTokens(pathFromRoot);
+    const rootTokens = pointerTokens(root);
+    return (pointer.length === rootTokens.length + 1 &&
+        rootTokens.every((token, index) => pointer[index] === token));
+}
+function isInRoot(pointer, root) {
+    const pointerTokens_ = pointerTokens(pointer);
+    const rootTokens = pointerTokens(root);
+    return (pointerTokens_.length > rootTokens.length &&
+        rootTokens.every((token, index) => pointerTokens_[index] === token));
+}
+function pointerTokens(pointer) {
+    if (!pointer.startsWith("#"))
+        return [];
+    try {
+        return parsePointer(pointer);
+    }
+    catch {
+        return [];
+    }
+}
+function existingComponentPointer(schema, file, hash, root) {
+    const map = asRecord(valueAtSafe(schema, root));
+    if (!map)
+        return undefined;
+    for (const [key, child] of Object.entries(map)) {
+        const record = asRecord(child);
+        if (!record || typeof record.$ref !== "string")
+            continue;
+        const extras = Object.keys(record).filter((name) => name !== "$ref" && name !== "summary" && name !== "description");
+        if (extras.length > 0)
+            continue;
+        if (stripHash(record.$ref) !== file || getHash(record.$ref) !== hash)
+            continue;
+        return joinPointer(root, key);
+    }
+    return undefined;
+}
+function keyForFile(schema, file, root, buckets, childReservesBase = false) {
+    const names = bucket(schema, root, buckets);
+    if (names.generated.has(file))
+        return names.generated.get(file) ?? null;
+    const base = prettify(fileBaseName(file));
+    if (!base)
+        return register(schema, root, file, null, buckets);
+    const taken = childReservesBase ? new Set(names.taken).add(base) : names.taken;
+    return register(schema, root, file, suggest(taken, base), buckets);
+}
+function childReservesName(value, base) {
+    if (!base)
+        return false;
+    const stack = [value];
+    const seen = new Set();
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (typeof current !== "object" || current === null || seen.has(current))
+            continue;
+        seen.add(current);
+        if (Array.isArray(current)) {
+            stack.push(...current);
+            continue;
+        }
+        const record = current;
+        if (typeof record.$ref === "string" && !record.$ref.startsWith("#")) {
+            const token = getHash(record.$ref).split("/").at(-1);
+            if (token === base)
+                return true;
+        }
+        stack.push(...Object.values(record));
+    }
+    return false;
+}
+function keyForPointer(schema, pointer, root, buckets) {
+    const names = bucket(schema, root, buckets);
+    if (names.generated.has(pointer))
+        return names.generated.get(pointer) ?? null;
+    const fragment = `${root.slice(1)}/`;
+    const actualPath = pointer.split(fragment).slice(1);
+    const base = prettify(actualPath.join("/"));
+    if (!base)
+        return register(schema, root, pointer, null, buckets);
+    return register(schema, root, pointer, suggest(names.taken, base), buckets);
+}
+function register(schema, root, id, key, buckets) {
+    const names = bucket(schema, root, buckets);
+    if (key === null) {
+        names.generated.set(id, null);
+        return null;
+    }
+    names.taken.add(key);
+    const pointer = joinPointer(root, key);
+    names.generated.set(id, pointer);
+    return pointer;
+}
+function bucket(schema, root, buckets) {
+    const id = `${root}`;
+    const existing = buckets.get(id);
+    if (existing)
+        return existing;
+    const taken = new Set();
+    const value = valueAtSafe(schema, root);
+    if (asRecord(value)) {
+        for (const key of Object.keys(value))
+            taken.add(key);
+    }
+    const created = { taken, generated: new Map() };
+    buckets.set(id, created);
+    return created;
+}
+function valueAtSafe(root, pointer) {
+    try {
+        return getAt(root, pointer);
+    }
+    catch (error) {
+        if (Schema.is(MissingPointerFailure)(error))
+            return undefined;
+        throw error;
+    }
+}
+function suggest(taken, key, fileBase) {
+    if (!taken.has(key))
+        return key;
+    if (fileBase && fileBase !== key) {
+        const prefixed = `${fileBase}_${key}`;
+        if (!taken.has(prefixed))
+            return prefixed;
+    }
+    for (let attempt = 2; attempt <= MAX_ATTEMPTS; attempt++) {
+        const candidate = `${key}-${attempt}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+    throw bundleFailure(`Could not generate a unique component name for ${key}.`);
+}
+function matchingComponent(_schema, _root, _value, _source, _componentSource) {
+    // Each external file keeps its own component, even when two files contain the same
+    // schema. DigitalOcean repeats one enum as apps_domain_phase and app_alert_phase.
+    return undefined;
+}
+function prettify(key) {
+    const pretty = key.replace(/(?:\.|[\\/]+)([a-z])?/g, (_match, letter, index) => {
+        if (letter === undefined)
+            return index === 0 ? "" : "_";
+        return `_${letter.toUpperCase()}`;
+    });
+    return pretty;
+}
+function fileBaseName(file) {
+    let pathname = file;
+    if (file.includes("://")) {
+        try {
+            pathname = decodeURIComponent(new URL(file).pathname);
+        }
+        catch {
+            pathname = file;
+        }
+    }
+    const slash = Math.max(pathname.lastIndexOf("/"), pathname.lastIndexOf("\\"));
+    const base = slash >= 0 ? pathname.slice(slash + 1) : pathname;
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(0, dot) : base;
+}

package/dist/http.d.ts

@@ -0,0 +1,2 @@
+import type { EffectPlugin, Options } from "./plugins.ts";
+export declare function httpResolver(rootUrl: string, options: Options, policy?: "root" | "reference"): EffectPlugin<Uint8Array> | undefined;

package/dist/http.js

@@ -0,0 +1,163 @@
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import { Agent } from "@effect/platform-node/Undici";
+import { Cause, Effect, Schedule } from "effect";
+import { HttpClient } from "effect/http";
+import { ResolverFailure, nodeErrorCode, timeoutFailure } from "./errors.js";
+import { httpOrigin, isAllowedOrigin, isHttp, isUnsafeUrl, resolveUrlSafety, } from "./url.js";
+export function httpResolver(rootUrl, options, policy = "reference") {
+    if (policy === "root") {
+        return {
+            order: 200,
+            can: (file) => isHttp(file.url),
+            run: (file) => Effect.flatMap(HttpClient.HttpClient, (client) => client
+                .pipe(HttpClient.filterStatusOk)
+                .get(file.url)
+                .pipe(Effect.flatMap((response) => response.arrayBuffer), Effect.map((buffer) => new Uint8Array(buffer)), Effect.mapError((cause) => resolverFailure(file.url, cause)))),
+        };
+    }
+    if (options.resolve?.http === false)
+        return undefined;
+    const http = httpSettings(rootUrl, options);
+    return {
+        order: 200,
+        can: (file) => isHttp(file.url) &&
+            (http.safeUrlResolver === false ||
+                isAllowedOrigin(file.url, http.allowedOrigins) ||
+                !isUnsafeUrl(file.url)),
+        run: (file) => download(file.url, http),
+    };
+}
+function httpSettings(rootUrl, options) {
+    const user = typeof options.resolve?.http === "object" ? options.resolve.http : {};
+    const origin = httpOrigin(rootUrl);
+    const allowed = [...(user.allowedOrigins ?? [])];
+    if (origin && !allowed.includes(origin))
+        allowed.push(origin);
+    return {
+        headers: null,
+        timeout: 60_000,
+        redirects: 5,
+        withCredentials: false,
+        safeUrlResolver: true,
+        ...user,
+        allowedOrigins: allowed,
+    };
+}
+const download = Effect.fnUntraced(function* (href, http, redirects = []) {
+    const nextRedirects = [...redirects, href];
+    const requestedPrivate = isAllowedOrigin(href, http.allowedOrigins) && isUnsafeUrl(href);
+    let addresses;
+    if (http.safeUrlResolver !== false && !requestedPrivate) {
+        const safety = yield* resolveUrlSafety(href);
+        if (safety.unsafe) {
+            return yield* new ResolverFailure({
+                message: `Error downloading ${href}: Unsafe URL blocked by safeUrlResolver: ${href}`,
+                source: href,
+            });
+        }
+        addresses = safety.addresses;
+    }
+    const hop = addresses && addresses.length > 0
+        ? yield* Effect.scoped(pinnedHop(href, http, addresses, nextRedirects))
+        : yield* receive(yield* HttpClient.HttpClient, href, http, nextRedirects);
+    if (hop.kind === "redirect")
+        return yield* download(hop.href, hop.http, nextRedirects);
+    return hop.bytes;
+});
+const pinnedHop = Effect.fnUntraced(function* (href, http, addresses, redirects) {
+    const dispatcher = yield* Effect.acquireRelease(Effect.sync(() => new Agent({
+        connect: { lookup: pinnedLookup(href, addresses) },
+        autoSelectFamily: true,
+    })), (agent) => Effect.promise(() => agent.destroy()));
+    const client = yield* NodeHttpClient.makeUndici.pipe(Effect.provideService(NodeHttpClient.Dispatcher, dispatcher));
+    return yield* receive(client, href, http, redirects);
+});
+const receive = Effect.fnUntraced(function* (client, href, http, redirects) {
+    const request = client
+        .pipe(HttpClient.retryTransient({
+        schedule: Schedule.exponential("100 millis"),
+        times: 3,
+    }))
+        .get(href, { headers: http.headers || undefined })
+        .pipe(Effect.mapError((cause) => resolverFailure(href, cause)));
+    const timeout = http.timeout;
+    const response = yield* typeof timeout === "number" && timeout > 0
+        ? request.pipe(Effect.timeout(timeout), Effect.catchIf(Cause.isTimeoutError, () => Effect.fail(timeoutFailure(timeout))))
+        : request;
+    if (response.status >= 400) {
+        return yield* new ResolverFailure({
+            message: `Error downloading ${href}: HTTP ERROR ${response.status}`,
+            source: href,
+            ioErrorCode: String(response.status),
+        });
+    }
+    if (response.status >= 300) {
+        if (http.redirects !== undefined && redirects.length > http.redirects) {
+            return yield* new ResolverFailure({
+                message: `Error downloading ${redirects[0]}. \nToo many redirects: \n  ${redirects.join(" \n  ")}`,
+                source: href,
+                ioErrorCode: String(response.status),
+            });
+        }
+        const location = response.headers.location;
+        if (!location) {
+            return yield* new ResolverFailure({
+                message: `Error downloading ${href}: HTTP ${response.status} redirect with no location header`,
+                source: href,
+                ioErrorCode: String(response.status),
+            });
+        }
+        const redirectTo = new URL(location, href).href;
+        const redirectOptions = new URL(redirectTo).origin === new URL(href).origin ? http : withoutSensitiveHeaders(http);
+        return { kind: "redirect", href: redirectTo, http: redirectOptions };
+    }
+    const buffer = yield* response.arrayBuffer.pipe(Effect.mapError((cause) => resolverFailure(href, cause)));
+    return { kind: "body", bytes: new Uint8Array(buffer) };
+});
+function pinnedLookup(href, addresses) {
+    const expectedHostname = normalizeLookupHostname(new URL(href).hostname);
+    return (hostname, options, callback) => {
+        const normalizedHostname = normalizeLookupHostname(hostname);
+        const requestedFamily = options.family === "IPv4" ? 4 : options.family === "IPv6" ? 6 : options.family || 0;
+        const candidates = addresses.filter(({ family }) => requestedFamily === 0 || family === requestedFamily);
+        if (normalizedHostname !== expectedHostname || candidates.length === 0) {
+            const error = new Error(`No validated address is available for ${hostname}`);
+            error.code = "ENOTFOUND";
+            callback(error, "", 0);
+        }
+        else if (options.all) {
+            callback(null, candidates);
+        }
+        else {
+            const selected = candidates[0];
+            callback(null, selected.address, selected.family);
+        }
+    };
+}
+function normalizeLookupHostname(hostname) {
+    return hostname
+        .replace(/^\[|\]$/g, "")
+        .replace(/\.+$/, "")
+        .toLowerCase();
+}
+function withoutSensitiveHeaders(http) {
+    if (!http.headers)
+        return http;
+    const headers = new Headers(http.headers);
+    headers.delete("authorization");
+    headers.delete("proxy-authorization");
+    headers.delete("cookie");
+    return { ...http, headers: Object.fromEntries(headers.entries()) };
+}
+function resolverFailure(href, cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const ioErrorCode = nodeErrorCode(cause);
+    return new ResolverFailure({
+        message: message.startsWith("Error downloading")
+            ? message
+            : `Error downloading ${href}: ${message}`,
+        source: href,
+        cause,
+        ...(ioErrorCode ? { ioErrorCode } : {}),
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { bundleDocument, type BundleOptions } from "./bundle.ts";
+export { ParsedOpenApiFromString, type ParseOptions } from "./codec.ts";
+export type * from "./schemas/3.1/index.ts";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { bundleDocument } from "./bundle.js";
+export { ParsedOpenApiFromString } from "./codec.js";

package/dist/load.d.ts

@@ -0,0 +1,17 @@
+import { Effect, type FileSystem, Path, Schema } from "effect";
+import type { HttpClient } from "effect/http";
+import { type OpenAPIDocument } from "./document.ts";
+import { type LoadError } from "./errors.ts";
+declare const loadOptions: Schema.Struct<{
+    readonly cwd: Schema.optional<Schema.Union<readonly [Schema.String, Schema.URL]>>;
+}>;
+export type LoadOptions = typeof loadOptions.Type;
+interface LoadedDocument {
+    readonly document: OpenAPIDocument;
+    readonly absoluteRef: string;
+}
+type LoadServices = FileSystem.FileSystem | Path.Path | HttpClient.HttpClient;
+export declare const loadDocument: (source: unknown, options?: {
+    readonly cwd?: string | URL | undefined;
+} | undefined) => Effect.Effect<LoadedDocument, LoadError, LoadServices>;
+export {};