saturndocs 0.1.0

package/dist/chunk-S45UWCML.js

@@ -0,0 +1,588 @@
+// ../openapi/dist/index.js
+import { parse as parseYaml } from "yaml";
+var nodeImport = async (specifier) => await import(specifier);
+var HTTP_METHODS = [
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "head",
+  "options",
+  "trace"
+];
+var MAX_REF_DEPTH = 40;
+var SCHEMA_REF = /* @__PURE__ */ Symbol("schemaRef");
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function withSchemaRef(value, ref) {
+  if (!isRecord(value)) return value;
+  Object.defineProperty(value, SCHEMA_REF, { value: ref, enumerable: false, configurable: true });
+  return value;
+}
+function decodePointerToken(token) {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function lookupPointer(root, ref) {
+  const pointer = ref.slice(1);
+  const tokens = pointer.split("/").filter((segment) => segment.length > 0);
+  let current = root;
+  for (const rawToken of tokens) {
+    const token = decodePointerToken(rawToken);
+    if (isRecord(current)) {
+      current = current[token];
+    } else if (Array.isArray(current)) {
+      current = current[Number(token)];
+    } else {
+      current = void 0;
+    }
+    if (current === void 0) {
+      throw new Error(
+        `OpenAPI specification contains an unresolvable reference: "${ref}"`
+      );
+    }
+  }
+  return current;
+}
+function parseDocument(source, filePath) {
+  let root;
+  try {
+    root = parseYaml(source);
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const suffix = filePath ? ` in ${filePath}` : "";
+    throw new Error(`Failed to parse OpenAPI specification${suffix}: ${message}`);
+  }
+  if (!isRecord(root)) {
+    const suffix = filePath ? ` in ${filePath}` : "";
+    throw new Error(
+      `Failed to parse OpenAPI specification${suffix}: the document is empty or not an object.`
+    );
+  }
+  return root;
+}
+function splitRef(ref) {
+  const hashIndex = ref.indexOf("#");
+  if (hashIndex === -1) return { filePart: ref, pointer: "" };
+  return {
+    filePart: ref.slice(0, hashIndex),
+    pointer: ref.slice(hashIndex)
+  };
+}
+function isHttpRef(ref) {
+  return /^https?:\/\//i.test(ref);
+}
+function isAbsolutePath(path) {
+  return path.startsWith("/");
+}
+function normalizePath(path) {
+  const absolute = isAbsolutePath(path);
+  const parts = [];
+  for (const part of path.split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") {
+      if (parts.length > 0 && parts[parts.length - 1] !== "..") {
+        parts.pop();
+      } else if (!absolute) {
+        parts.push("..");
+      }
+      continue;
+    }
+    parts.push(part);
+  }
+  const normalized = parts.join("/");
+  if (absolute) return `/${normalized}`;
+  return normalized || ".";
+}
+function resolvePath(...paths) {
+  let out = "";
+  for (const path of paths) {
+    if (!path) continue;
+    if (isAbsolutePath(path)) {
+      out = path;
+    } else {
+      out = out ? `${out}/${path}` : path;
+    }
+  }
+  if (!isAbsolutePath(out)) out = `${process.cwd()}/${out}`;
+  return normalizePath(out);
+}
+function dirnamePath(path) {
+  const normalized = normalizePath(path);
+  const index = normalized.lastIndexOf("/");
+  if (index <= 0) return isAbsolutePath(normalized) ? "/" : ".";
+  return normalized.slice(0, index);
+}
+function relativePath(from, to) {
+  const fromParts = normalizePath(from).split("/").filter(Boolean);
+  const toParts = normalizePath(to).split("/").filter(Boolean);
+  let common = 0;
+  while (common < fromParts.length && common < toParts.length && fromParts[common] === toParts[common]) {
+    common += 1;
+  }
+  return [
+    ...Array.from({ length: fromParts.length - common }, () => ".."),
+    ...toParts.slice(common)
+  ].join("/") || "";
+}
+function isInsideRoot(rootDir, filePath) {
+  const rel = relativePath(rootDir, filePath);
+  return rel === "" || !rel.startsWith("..") && !isAbsolutePath(rel);
+}
+function withSiblings(resolvedTarget, siblings, ref) {
+  if (Object.keys(siblings).length > 0 && isRecord(resolvedTarget)) {
+    return withSchemaRef({ ...resolvedTarget, ...siblings }, ref);
+  }
+  return withSchemaRef(resolvedTarget, ref);
+}
+function withSourceRef(out, node) {
+  const sourceRef = node[SCHEMA_REF];
+  return typeof sourceRef === "string" ? withSchemaRef(out, sourceRef) : out;
+}
+function resolveRefs(node, root, seen, depth) {
+  if (depth > MAX_REF_DEPTH) {
+    return node;
+  }
+  if (Array.isArray(node)) {
+    return node.map((item) => resolveRefs(item, root, seen, depth + 1));
+  }
+  if (!isRecord(node)) {
+    return node;
+  }
+  const ref = node["$ref"];
+  if (typeof ref === "string" && ref.startsWith("#/")) {
+    if (seen.has(ref)) {
+      return { $ref: ref };
+    }
+    const target = lookupPointer(root, ref);
+    const nextSeen = new Set(seen);
+    nextSeen.add(ref);
+    const resolvedTarget = resolveRefs(target, root, nextSeen, depth + 1);
+    const siblings = {};
+    for (const [key, value] of Object.entries(node)) {
+      if (key !== "$ref") siblings[key] = resolveRefs(value, root, seen, depth + 1);
+    }
+    return withSiblings(resolvedTarget, siblings, ref);
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(node)) {
+    out[key] = resolveRefs(value, root, seen, depth + 1);
+  }
+  return withSourceRef(out, node);
+}
+async function resolveRefsAsync(node, root, seen, depth, context) {
+  if (depth > MAX_REF_DEPTH) {
+    return node;
+  }
+  if (Array.isArray(node)) {
+    return Promise.all(
+      node.map((item) => resolveRefsAsync(item, root, seen, depth + 1, context))
+    );
+  }
+  if (!isRecord(node)) {
+    return node;
+  }
+  const ref = node["$ref"];
+  const local = typeof ref === "string" && ref.startsWith("#/");
+  const external = typeof ref === "string" && !local && context.currentFile !== "" && !isHttpRef(ref);
+  if (typeof ref === "string" && (local || external)) {
+    const marker = `${context.currentFile}:${ref}`;
+    if (seen.has(marker)) {
+      return { $ref: ref };
+    }
+    const nextSeen = new Set(seen);
+    nextSeen.add(marker);
+    const resolvedTarget = local ? await resolveRefsAsync(lookupPointer(root, ref), root, nextSeen, depth + 1, context) : await context.resolver.resolveExternal(ref, context.currentFile, nextSeen, depth + 1);
+    const siblings = {};
+    for (const [key, value] of Object.entries(node)) {
+      if (key !== "$ref") siblings[key] = await resolveRefsAsync(value, root, seen, depth + 1, context);
+    }
+    return withSiblings(resolvedTarget, siblings, ref);
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(node)) {
+    out[key] = await resolveRefsAsync(value, root, seen, depth + 1, context);
+  }
+  return withSourceRef(out, node);
+}
+function* resolve(node) {
+  return yield node;
+}
+function runResolving(steps, resolveNode) {
+  let step = steps.next();
+  while (!step.done) step = steps.next(resolveNode(step.value));
+  return step.value;
+}
+async function runResolvingAsync(steps, resolveNode) {
+  let step = steps.next();
+  while (!step.done) step = steps.next(await resolveNode(step.value));
+  return step.value;
+}
+function operationSlug(method, path) {
+  return `${method} ${path}`.toLowerCase().replace(/[{}]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function* pickContent(content) {
+  if (!isRecord(content)) return void 0;
+  const keys = Object.keys(content);
+  if (keys.length === 0) return void 0;
+  const contentType = keys.includes("application/json") ? "application/json" : keys[0];
+  const contentTypes = [
+    contentType,
+    ...keys.filter((key) => key !== contentType)
+  ];
+  const resolved = yield* resolve(content[contentType]);
+  const media = isRecord(resolved) ? resolved : {};
+  return {
+    contentType,
+    contentTypes,
+    schema: media["schema"],
+    example: extractExample(media),
+    examples: extractExamples(media)
+  };
+}
+function extractExample(media) {
+  if (media["example"] !== void 0) {
+    return media["example"];
+  }
+  const examples = media["examples"];
+  if (isRecord(examples)) {
+    const first = Object.values(examples)[0];
+    if (isRecord(first) && "value" in first) {
+      return first["value"];
+    }
+  }
+  return void 0;
+}
+function extractExamples(media) {
+  const examples = [];
+  if (media["example"] !== void 0) {
+    examples.push({ name: "Example", value: media["example"] });
+  }
+  const rawExamples = media["examples"];
+  if (!isRecord(rawExamples)) return examples;
+  for (const [name, raw] of Object.entries(rawExamples)) {
+    if (!isRecord(raw) || !("value" in raw)) continue;
+    const example = { name, value: raw["value"] };
+    const summary = asStringOrUndefined(raw["summary"]);
+    if (summary !== void 0) example.summary = summary;
+    examples.push(example);
+  }
+  return examples;
+}
+function codeSamples(raw) {
+  const value = raw["x-codeSamples"] ?? raw["x-code-samples"];
+  if (!Array.isArray(value)) return [];
+  const samples = [];
+  for (const entry of value) {
+    if (!isRecord(entry)) continue;
+    const lang = asStringOrUndefined(entry["lang"]);
+    const source = asStringOrUndefined(entry["source"]);
+    if (!lang || source === void 0) continue;
+    const sample = { lang, source };
+    const label = asStringOrUndefined(entry["label"]);
+    if (label !== void 0) sample.label = label;
+    samples.push(sample);
+  }
+  return samples;
+}
+function securityNames(requirement) {
+  if (!Array.isArray(requirement)) return [];
+  const names = [];
+  for (const entry of requirement) {
+    if (isRecord(entry)) {
+      for (const name of Object.keys(entry)) {
+        if (!names.includes(name)) names.push(name);
+      }
+    }
+  }
+  return names;
+}
+function securityRequirementGroups(requirement) {
+  if (!Array.isArray(requirement)) return { groups: [], optional: false };
+  const groups = [];
+  let optional = false;
+  for (const entry of requirement) {
+    if (!isRecord(entry)) continue;
+    const names = [];
+    for (const name of Object.keys(entry)) {
+      if (!names.includes(name)) names.push(name);
+    }
+    if (names.length === 0) optional = true;
+    else groups.push(names);
+  }
+  return { groups, optional };
+}
+var SECURITY_SCHEME_TYPES = [
+  "apiKey",
+  "http",
+  "oauth2",
+  "openIdConnect",
+  "mutualTLS"
+];
+var API_KEY_LOCATIONS = ["header", "query", "cookie"];
+function normalizeSecurityScheme(name, raw) {
+  if (!isRecord(raw)) return void 0;
+  const type = raw["type"];
+  if (typeof type !== "string") return void 0;
+  if (!SECURITY_SCHEME_TYPES.includes(type)) return void 0;
+  const info = { name, type };
+  const description = asStringOrUndefined(raw["description"]);
+  if (description !== void 0) info.description = description;
+  if (type === "apiKey") {
+    const location = raw["in"];
+    const parameterName = asStringOrUndefined(raw["name"]);
+    if (typeof location !== "string") return void 0;
+    if (!API_KEY_LOCATIONS.includes(location)) {
+      return void 0;
+    }
+    if (parameterName === void 0 || parameterName.length === 0) return void 0;
+    info.in = location;
+    info.parameterName = parameterName;
+    return info;
+  }
+  if (type === "http") {
+    const scheme = asStringOrUndefined(raw["scheme"]);
+    if (scheme === void 0 || scheme.length === 0) return void 0;
+    info.scheme = scheme.toLowerCase();
+    const bearerFormat = asStringOrUndefined(raw["bearerFormat"]);
+    if (bearerFormat !== void 0) info.bearerFormat = bearerFormat;
+    return info;
+  }
+  return info;
+}
+function securitySchemeMap(resolved) {
+  if (!isRecord(resolved)) return {};
+  const map = {};
+  for (const [name, raw] of Object.entries(resolved)) {
+    const info = normalizeSecurityScheme(name, raw);
+    if (info) map[name] = info;
+  }
+  return map;
+}
+function securitySchemesNode(root) {
+  const components = root["components"];
+  return isRecord(components) ? components["securitySchemes"] : void 0;
+}
+function asStringOrUndefined(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function* toParamInfo(raw) {
+  const resolved = yield* resolve(raw);
+  if (!isRecord(resolved)) return void 0;
+  const name = resolved["name"];
+  const location = resolved["in"];
+  if (typeof name !== "string" || typeof location !== "string") return void 0;
+  if (location !== "query" && location !== "path" && location !== "header" && location !== "cookie") {
+    return void 0;
+  }
+  const required = location === "path" ? true : resolved["required"] === true;
+  const info = { name, location, required };
+  const description = asStringOrUndefined(resolved["description"]);
+  if (description !== void 0) info.description = description;
+  if (resolved["schema"] !== void 0) info.schema = resolved["schema"];
+  return info;
+}
+function* collectParameters(pathParams, opParams) {
+  const byKey = /* @__PURE__ */ new Map();
+  const order = [];
+  for (const list of [pathParams, opParams]) {
+    if (!Array.isArray(list)) continue;
+    for (const raw of list) {
+      const info = yield* toParamInfo(raw);
+      if (!info) continue;
+      const key = `${info.location}:${info.name}`;
+      if (!byKey.has(key)) order.push(key);
+      byKey.set(key, info);
+    }
+  }
+  return order.map((key) => byKey.get(key));
+}
+function* buildRequestBody(raw) {
+  const resolved = yield* resolve(raw);
+  if (!isRecord(resolved)) return void 0;
+  const picked = yield* pickContent(resolved["content"]);
+  if (!picked) return void 0;
+  const body = {
+    required: resolved["required"] === true,
+    contentType: picked.contentType,
+    contentTypes: picked.contentTypes,
+    examples: picked.examples
+  };
+  if (picked.schema !== void 0) body.schema = picked.schema;
+  if (picked.example !== void 0) body.example = picked.example;
+  return body;
+}
+function* buildResponses(raw) {
+  if (!isRecord(raw)) return [];
+  const responses = [];
+  for (const [status, value] of Object.entries(raw)) {
+    const resolved = yield* resolve(value);
+    const info = { status, examples: [] };
+    if (isRecord(resolved)) {
+      const description = asStringOrUndefined(resolved["description"]);
+      if (description !== void 0) info.description = description;
+      if (isRecord(resolved["headers"])) {
+        const headers = [];
+        for (const [name, rawHeader] of Object.entries(resolved["headers"])) {
+          const header = yield* resolve(rawHeader);
+          if (!isRecord(header)) continue;
+          const content = yield* pickContent(header["content"]);
+          headers.push({
+            name,
+            required: header["required"] === true,
+            description: asStringOrUndefined(header["description"]),
+            schema: header["schema"] ?? content?.schema
+          });
+        }
+        if (headers.length > 0) info.headers = headers;
+      }
+      const picked = yield* pickContent(resolved["content"]);
+      if (picked) {
+        info.contentType = picked.contentType;
+        info.contentTypes = picked.contentTypes;
+        if (picked.schema !== void 0) info.schema = picked.schema;
+        if (picked.example !== void 0) info.example = picked.example;
+        info.examples = picked.examples;
+      }
+    }
+    responses.push(info);
+  }
+  return responses;
+}
+function parseOpenApi(source) {
+  const root = parseDocument(source);
+  return runResolving(buildParsedSpec(root), (node) => resolveRefs(node, root, /* @__PURE__ */ new Set(), 0));
+}
+function* buildParsedSpec(root) {
+  const info = isRecord(root["info"]) ? root["info"] : {};
+  const title = asStringOrUndefined(info["title"]) ?? "";
+  const version = asStringOrUndefined(info["version"]) ?? "";
+  const description = asStringOrUndefined(info["description"]);
+  const servers = [];
+  if (Array.isArray(root["servers"])) {
+    for (const server of root["servers"]) {
+      if (isRecord(server) && typeof server["url"] === "string") {
+        servers.push(server["url"]);
+      }
+    }
+  }
+  const rootSecurity = securityNames(root["security"]);
+  const rootRequirements = securityRequirementGroups(root["security"]);
+  const securitySchemes = securitySchemeMap(yield* resolve(securitySchemesNode(root)));
+  const paths = root["paths"];
+  if (!isRecord(paths)) {
+    throw new Error(
+      "Failed to parse OpenAPI specification: missing or invalid `paths` object."
+    );
+  }
+  const operations = [];
+  for (const [path, pathItemRaw] of Object.entries(paths)) {
+    if (!isRecord(pathItemRaw)) continue;
+    const pathParams = pathItemRaw["parameters"];
+    for (const method of HTTP_METHODS) {
+      const opRaw = pathItemRaw[method];
+      if (!isRecord(opRaw)) continue;
+      const tags = Array.isArray(opRaw["tags"]) ? opRaw["tags"].filter((tag) => typeof tag === "string") : [];
+      const requirements = opRaw["security"] !== void 0 ? securityRequirementGroups(opRaw["security"]) : rootRequirements;
+      const operation = {
+        slug: operationSlug(method, path),
+        method,
+        path,
+        deprecated: opRaw["deprecated"] === true,
+        codeSamples: codeSamples(opRaw),
+        tags,
+        parameters: yield* collectParameters(pathParams, opRaw["parameters"]),
+        responses: yield* buildResponses(opRaw["responses"]),
+        security: opRaw["security"] !== void 0 ? securityNames(opRaw["security"]) : rootSecurity,
+        securityRequirements: requirements.groups,
+        securityOptional: requirements.optional
+      };
+      const operationId = asStringOrUndefined(opRaw["operationId"]);
+      if (operationId !== void 0) operation.operationId = operationId;
+      const summary = asStringOrUndefined(opRaw["summary"]);
+      if (summary !== void 0) operation.summary = summary;
+      const opDescription = asStringOrUndefined(opRaw["description"]);
+      if (opDescription !== void 0) operation.description = opDescription;
+      if (operation.deprecated) {
+        const deprecationMessage = asStringOrUndefined(opRaw["x-deprecation-message"]);
+        if (deprecationMessage !== void 0) operation.deprecationMessage = deprecationMessage;
+        else if (opDescription !== void 0 && /deprecat/i.test(opDescription)) operation.deprecationMessage = opDescription;
+      }
+      const requestBody = yield* buildRequestBody(opRaw["requestBody"]);
+      if (requestBody !== void 0) operation.requestBody = requestBody;
+      operations.push(operation);
+    }
+  }
+  const spec = { title, version, servers, operations, securitySchemes };
+  if (description !== void 0) spec.description = description;
+  return spec;
+}
+async function parseOpenApiFile(filePath, options = {}) {
+  const rootFile = resolvePath(filePath);
+  const rootDir = dirnamePath(rootFile);
+  const reader = options.readFile ?? (async (path) => {
+    const fs = await nodeImport("node:fs/promises");
+    return fs.readFile(path, "utf8");
+  });
+  const cache = /* @__PURE__ */ new Map();
+  const loadDocument = (targetPath) => {
+    const absolute = resolvePath(targetPath);
+    let promise = cache.get(absolute);
+    if (!promise) {
+      promise = reader(absolute).then(
+        (source) => parseDocument(source, absolute)
+      );
+      cache.set(absolute, promise);
+      return promise;
+    }
+    return promise;
+  };
+  const resolver = {
+    async resolveExternal(ref, referringFile, seen, depth) {
+      const { filePart, pointer } = splitRef(ref);
+      if (filePart.length === 0) {
+        const referringRoot = await loadDocument(referringFile);
+        const target2 = pointer ? lookupPointer(referringRoot, pointer) : referringRoot;
+        const targetMarker2 = `${referringFile}:${pointer}`;
+        if (seen.has(targetMarker2)) return { $ref: ref };
+        const nextSeen2 = new Set(seen);
+        nextSeen2.add(targetMarker2);
+        return resolveRefsAsync(
+          target2,
+          referringRoot,
+          nextSeen2,
+          depth + 1,
+          { resolver, currentFile: referringFile }
+        );
+      }
+      const targetPath = resolvePath(dirnamePath(referringFile), filePart);
+      if (!isInsideRoot(rootDir, targetPath)) {
+        throw new Error(
+          `OpenAPI external reference "${ref}" from ${referringFile} resolves outside the spec root directory ${rootDir}.`
+        );
+      }
+      const targetRoot = await loadDocument(targetPath);
+      const target = pointer ? lookupPointer(targetRoot, pointer) : targetRoot;
+      const targetMarker = `${targetPath}:${pointer}`;
+      if (seen.has(targetMarker)) return { $ref: ref };
+      const nextSeen = new Set(seen);
+      nextSeen.add(targetMarker);
+      return resolveRefsAsync(
+        target,
+        targetRoot,
+        nextSeen,
+        depth + 1,
+        { resolver, currentFile: targetPath }
+      );
+    }
+  };
+  const root = await loadDocument(rootFile);
+  const context = { resolver, currentFile: rootFile };
+  return runResolvingAsync(buildParsedSpec(root), (node) => resolveRefsAsync(node, root, /* @__PURE__ */ new Set(), 0, context));
+}
+
+export {
+  parseOpenApi,
+  parseOpenApiFile
+};