zudoku 0.0.0-fed343e → 0.0.0-ff27e7ea

package/src/lib/plugins/openapi/schema/UnionView.tsx

@@ -0,0 +1,132 @@
+import { useState } from "react";
+import type { SchemaObject } from "../../../oas/parser/index.js";
+import { Badge } from "../../../ui/Badge.js";
+import { Frame, FramePanel } from "../../../ui/Frame.js";
+import { cn } from "../../../util/cn.js";
+import { SchemaView } from "./SchemaView.js";
+import {
+  decideExclusivity,
+  labelForVariant,
+  quickGuards,
+  unionVariants,
+} from "./union-helpers.js";
+
+const DecisionTable = ({
+  variants,
+  schema,
+  selectedVariant,
+  onSelectVariant,
+}: {
+  variants: SchemaObject[];
+  schema: SchemaObject;
+  selectedVariant: string;
+  onSelectVariant: (label: string) => void;
+}) => {
+  const rows = variants.map((v, i) => ({
+    label: labelForVariant(i, v),
+    guards: quickGuards(v, schema),
+  }));
+
+  return (
+    <div className="flex flex-col gap-2 text-sm">
+      <h4 className="font-medium">Decision Table</h4>
+      <div className="border rounded-md overflow-hidden">
+        <table className="w-full">
+          <thead>
+            <tr className="border-b bg-muted/50">
+              <th className="text-left p-2 font-medium">Variant</th>
+              <th className="text-left p-2 font-medium">Matching Criteria</th>
+            </tr>
+          </thead>
+          <tbody className="divide-y">
+            {rows.map((row) => (
+              <tr key={row.label} className="hover:bg-muted/30">
+                <td className="p-2 font-medium">
+                  <button
+                    type="button"
+                    className={cn(
+                      "hover:underline",
+                      selectedVariant === row.label && "text-primary",
+                    )}
+                    onClick={() => onSelectVariant(row.label)}
+                  >
+                    {row.label}
+                  </button>
+                </td>
+                <td className="p-2 text-muted-foreground text-xs">
+                  {row.guards.length > 0
+                    ? row.guards.join(" · ")
+                    : "No specific criteria"}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+};
+
+export const UnionView = ({
+  schema,
+  cardHeader,
+}: {
+  schema: SchemaObject;
+  cardHeader?: React.ReactNode;
+}) => {
+  const mode = Array.isArray(schema.oneOf)
+    ? "oneOf"
+    : Array.isArray(schema.anyOf)
+      ? "anyOf"
+      : undefined;
+
+  const variants = mode ? unionVariants(schema) : [];
+  const [selectedVariant, setSelectedVariant] = useState(() =>
+    variants[0] ? labelForVariant(0, variants[0]) : "",
+  );
+
+  if (!mode) return null;
+
+  const exclusivity = decideExclusivity(schema);
+
+  const semanticsMessage =
+    exclusivity === "exactly-one" ? (
+      <>
+        Exactly one variant <b>must match</b>.
+      </>
+    ) : (
+      <>
+        At least one variant <b>must match</b>. Multiple variants{" "}
+        <i>may match</i> simultaneously.
+      </>
+    );
+
+  const currentVariantIndex = variants.findIndex(
+    (v, i) => labelForVariant(i, v) === selectedVariant,
+  );
+  const currentVariant =
+    currentVariantIndex >= 0 ? variants[currentVariantIndex] : null;
+
+  return (
+    <Frame>
+      {cardHeader}
+      <FramePanel className="text-sm flex flex-col gap-4">
+        <div className="flex items-center gap-2">
+          <Badge variant="outline">{mode}</Badge>
+          <div className="flex-1 p-2">
+            <span className="text-sm">{semanticsMessage}</span>
+          </div>
+        </div>
+
+        <DecisionTable
+          variants={variants}
+          schema={schema}
+          selectedVariant={selectedVariant}
+          onSelectVariant={setSelectedVariant}
+        />
+        <strong>Properties for {selectedVariant}:</strong>
+        {currentVariant && <SchemaView schema={currentVariant} />}
+      </FramePanel>
+    </Frame>
+  );
+};

package/src/lib/plugins/openapi/schema/union-helpers.ts

@@ -0,0 +1,123 @@
+import type { SchemaObject } from "../../../oas/parser/index.js";
+
+export type FieldSignature = {
+  type?: SchemaObject["type"];
+  const?: unknown;
+  enum?: unknown[];
+  format?: string;
+  pattern?: string;
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: boolean | number;
+  exclusiveMaximum?: boolean | number;
+  minLength?: number;
+  maxLength?: number;
+  minItems?: number;
+  maxItems?: number;
+  itemsType?: string | string[];
+  additionalProps?: "true" | "false" | "schema";
+};
+
+export type FieldDoc = {
+  name: string;
+  humanType: string;
+  description?: string;
+  requiredInAll: boolean;
+};
+
+export const unionVariants = (schema: SchemaObject): SchemaObject[] => {
+  const variants = (schema.oneOf ?? schema.anyOf ?? []) as SchemaObject[];
+
+  // If parent schema has properties that variants don't, merge them
+  // This handles the pattern where anyOf/oneOf is used just for required field combinations
+  if (schema.properties && Object.keys(schema.properties).length > 0) {
+    return variants.map((variant) => {
+      // If variant doesn't define its own properties or type, inherit from parent
+      const shouldInherit =
+        !variant.properties &&
+        !variant.type &&
+        !variant.oneOf &&
+        !variant.anyOf;
+
+      if (shouldInherit) {
+        return {
+          ...variant,
+          type: "object" as const,
+          properties: schema.properties,
+          required: variant.required ?? schema.required,
+        };
+      }
+
+      return variant;
+    });
+  }
+
+  return variants;
+};
+
+export const decideExclusivity = (
+  schema: SchemaObject,
+): "exactly-one" | "at-least-one" => {
+  if (Array.isArray(schema.oneOf)) return "exactly-one";
+
+  const discriminator = schema.discriminator?.propertyName;
+  if (!discriminator) return "at-least-one";
+
+  const variants = unionVariants(schema);
+  const seen = new Set<string>();
+
+  for (const variant of variants) {
+    const prop = variant.properties?.[discriminator];
+
+    const value =
+      prop?.const ??
+      (Array.isArray(prop?.enum) && prop.enum.length === 1
+        ? String(prop.enum[0])
+        : undefined);
+
+    if (value == null || seen.has(String(value))) return "at-least-one";
+    seen.add(String(value));
+  }
+
+  return "exactly-one";
+};
+
+export const labelForVariant = (index: number, variant: SchemaObject) =>
+  variant.title?.trim() || `Variant ${index + 1}`;
+
+export const quickGuards = (variant: SchemaObject, root?: SchemaObject) => {
+  const guards: string[] = [];
+
+  if (variant.type) {
+    guards.push(
+      `type = ${Array.isArray(variant.type) ? variant.type.join("|") : variant.type}`,
+    );
+  }
+
+  const discriminator = root?.discriminator?.propertyName;
+  if (discriminator) {
+    const discriminatorProp = variant.properties?.[discriminator] as
+      | SchemaObject
+      | undefined;
+
+    const discriminatorValue =
+      discriminatorProp?.const ??
+      (Array.isArray(discriminatorProp?.enum) &&
+      discriminatorProp.enum.length === 1
+        ? discriminatorProp.enum[0]
+        : undefined);
+
+    if (discriminatorValue !== undefined) {
+      guards.push(`${discriminator}=${JSON.stringify(discriminatorValue)}`);
+    }
+  }
+
+  const required = (variant.required ?? []).filter((k) => k !== discriminator);
+  if (required.length) {
+    const head = required.slice(0, 3).join(", ");
+    const more = required.length > 3 ? ` +${required.length - 3} more` : "";
+    guards.push(`requires: ${head}${more}`);
+  }
+
+  return guards;
+};

package/src/lib/plugins/openapi/schema/utils.ts

@@ -1,18 +1,35 @@
+import { CIRCULAR_REF } from "../../../oas/graphql/circular.js";
 import type { SchemaObject } from "../../../oas/parser/index.js";
 
-export const isComplexType = (value: SchemaObject) =>
-  value.type === "object" ||
-  (value.type === "array" &&
-    typeof value.items === "object" &&
-    (!value.items.type || value.items.type === "object"));
+export const isBasicType = (
+  type: unknown,
+): type is "string" | "number" | "boolean" | "integer" | "null" =>
+  (typeof type === "string" &&
+    ["string", "number", "boolean", "integer", "null"].includes(type)) ||
+  (Array.isArray(type) && type.every(isBasicType));
 
-export const hasLogicalGroupings = (value: SchemaObject) =>
-  Boolean(value.oneOf ?? value.allOf ?? value.anyOf);
+export const isArrayType = (value: SchemaObject) =>
+  value.type === "array" ||
+  // schema.type might be an array of types, so we need to check if "array" is one of them
+  (Array.isArray(value.type) && value.type.includes("array"));
 
-export const LogicalSchemaTypeMap = {
-  allOf: "AND",
-  anyOf: "OR",
-  oneOf: "ONE",
-} as const;
+export const isComplexType = (value?: SchemaObject) =>
+  value &&
+  ((value.type === "object" &&
+    Object.keys(value.properties ?? {}).length > 0) ||
+    (value.type === "array" &&
+      typeof value.items === "object" &&
+      (!value.items.type || value.items.type === "object")));
 
-export type LogicalGroupType = "AND" | "OR" | "ONE";
+export const isCircularRef = (schema: unknown): schema is string =>
+  typeof schema === "string" && schema.startsWith(CIRCULAR_REF);
+
+export const isArrayCircularRef = (
+  schema: SchemaObject,
+): schema is SchemaObject & { items: SchemaObject } =>
+  isArrayType(schema) && "items" in schema && isCircularRef(schema.items);
+
+export const extractCircularRefInfo = (
+  ref?: string | SchemaObject,
+): string | undefined =>
+  typeof ref === "string" ? ref.split(":")[1] : undefined;

package/src/lib/plugins/openapi/state.ts

@@ -0,0 +1,36 @@
+import { useMemo } from "react";
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+
+interface SelectedServerState {
+  selectedServer?: string;
+  setSelectedServer: (newServer: string) => void;
+}
+
+export const useSelectedServerStore = create<SelectedServerState>()(
+  persist(
+    (set) => ({
+      selectedServer: undefined,
+      setSelectedServer: (newServer: string) =>
+        set({ selectedServer: newServer }),
+    }),
+    { name: "zudoku-selected-server" },
+  ),
+);
+
+/**
+ * Simple wrapper for `useSelectedServerStore` to fall back to first of the provided servers
+ */
+export const useSelectedServer = (servers: Array<{ url: string }>) => {
+  const { selectedServer, setSelectedServer } = useSelectedServerStore();
+
+  const finalSelectedServer = useMemo(
+    () =>
+      selectedServer && servers.some((s) => s.url === selectedServer)
+        ? selectedServer
+        : (servers.at(0)?.url ?? ""),
+    [selectedServer, servers],
+  );
+
+  return { selectedServer: finalSelectedServer, setSelectedServer };
+};

package/src/lib/plugins/openapi/util/createHttpSnippet.ts

@@ -0,0 +1,107 @@
+import { HTTPSnippet } from "@zudoku/httpsnippet";
+import type { OperationsFragmentFragment } from "../graphql/graphql.js";
+
+export const createHttpSnippet = ({
+  operation,
+  selectedServer,
+  exampleBody,
+}: {
+  operation: OperationsFragmentFragment;
+  selectedServer: string;
+  exampleBody: {
+    mimeType: string;
+    text?: string;
+  };
+}) => {
+  return new HTTPSnippet({
+    method: operation.method.toUpperCase(),
+    url:
+      selectedServer + operation.path.replaceAll("{", ":").replaceAll("}", ""),
+    postData: exampleBody,
+    headers: [
+      ...(exampleBody.text
+        ? [{ name: "Content-Type", value: exampleBody.mimeType }]
+        : []),
+      ...(operation.parameters
+        ?.filter((p) => p.in === "header" && p.required === true)
+        .map((p) => ({
+          name: p.name,
+          value:
+            p.schema?.default ??
+            p.examples?.find((x) => x.value)?.value ??
+            (p.schema?.type === "string"
+              ? "<string>"
+              : p.schema?.type === "number" || p.schema?.type === "integer"
+                ? "<number>"
+                : p.schema?.type === "boolean"
+                  ? "<bool>"
+                  : "<value>"),
+        })) ?? []),
+    ],
+    queryString:
+      operation.parameters
+        ?.filter((p) => p.in === "query" && p.required === true)
+        .map((p) => ({
+          name: p.name,
+          value:
+            p.schema?.default ??
+            p.examples?.find((x) => x.value)?.value ??
+            (p.schema?.type === "string"
+              ? "<string>"
+              : p.schema?.type === "number" || p.schema?.type === "integer"
+                ? "<number>"
+                : p.schema?.type === "boolean"
+                  ? "<bool>"
+                  : "<value>"),
+        })) ?? [],
+    httpVersion: "",
+    cookies: [],
+    headersSize: 0,
+    bodySize: 0,
+  });
+};
+
+export const getConverted = (snippet: HTTPSnippet, option: string) => {
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
+  let converted: any;
+  switch (option) {
+    case "shell":
+      converted = snippet.convert("shell", "curl");
+      break;
+    case "js":
+      converted = snippet.convert("javascript", "fetch");
+      break;
+    case "python":
+      converted = snippet.convert("python", "requests");
+      break;
+    case "java":
+      converted = snippet.convert("java", "okhttp");
+      break;
+    case "go":
+      converted = snippet.convert("go", "native");
+      break;
+    case "csharp":
+      converted = snippet.convert("csharp", "httpclient");
+      break;
+    case "kotlin":
+      converted = snippet.convert("kotlin", "okhttp");
+      break;
+    case "objc":
+      converted = snippet.convert("objc", "nsurlsession");
+      break;
+    case "php":
+      converted = snippet.convert("php", "http2");
+      break;
+    case "ruby":
+      converted = snippet.convert("ruby");
+      break;
+    case "swift":
+      converted = snippet.convert("swift");
+      break;
+    default:
+      converted = snippet.convert("shell");
+      break;
+  }
+
+  return converted ? converted[0] : "";
+};

package/src/lib/plugins/openapi/util/createNavigationCategory.tsx

@@ -0,0 +1,39 @@
+import type { NavigationItem } from "../../../../config/validators/NavigationSchema.js";
+import type { OperationResult } from "../index.js";
+import { MethodColorMap } from "./methodColorMap.js";
+
+export const createNavigationCategory = ({
+  label,
+  path,
+  operations,
+  collapsible,
+  collapsed,
+}: {
+  label: string;
+  path: string;
+  operations: OperationResult[];
+  collapsible?: boolean;
+  collapsed?: boolean;
+}): NavigationItem => ({
+  type: "category",
+  label,
+  link: {
+    type: "doc" as const,
+    path,
+    file: path,
+    label,
+  },
+  collapsible,
+  collapsed,
+  items: operations.map((operation) => ({
+    type: "link" as const,
+    label: operation.summary ?? operation.path,
+    to: `${path}#${operation.slug}`,
+    badge: {
+      label: operation.method,
+      // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
+      color: MethodColorMap[operation.method.toLowerCase()]!,
+      invert: true,
+    },
+  })),
+});

package/src/lib/plugins/openapi/util/generateSchemaExample.ts

@@ -1,72 +1,122 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { type SchemaObject } from "../../../oas/graphql/index.js";
-
-export const isObject = (value: unknown): boolean =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
+import type { SchemaObject } from "../../../oas/graphql/index.js";
+import { isCircularRef } from "../schema/utils.js";
 
 export const generateSchemaExample = (
-  schema: SchemaObject,
+  schema?: SchemaObject,
   name?: string,
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
 ): any => {
-  // Directly return the example or default if they exist
+  if (!schema || isCircularRef(schema)) {
+    return null;
+  }
+
+  // Check for schema-level example first
   if (schema.example !== undefined) {
     return schema.example;
-  } else if (schema.default !== undefined) {
-    return schema.default;
   }
 
-  // Process examples object
-  if (schema.examples && isObject(schema.examples)) {
-    return Object.values(schema.examples)[0];
+  // Then check for schema-level examples
+  if (
+    schema.examples &&
+    typeof schema.examples === "object" &&
+    "default" in schema.examples
+  ) {
+    const defaultExample = schema.examples.default;
+    if (defaultExample !== null) {
+      return typeof defaultExample === "object" && "value" in defaultExample
+        ? defaultExample.value
+        : defaultExample;
+    }
   }
 
-  // Recursively process objects and arrays
-  return processComplexTypes(schema, name);
-};
+  // No example needed for const values
+  if (schema.const !== undefined) {
+    return schema.const;
+  }
 
-function processComplexTypes(schema: SchemaObject, name?: string): any {
-  const properties = Object.entries(schema.properties ?? {}).concat(
-    Object.entries(schema.additionalProperties ?? {}),
-  );
-  if (schema.type === "object" && properties.length > 0) {
-    const obj: { [key: string]: any } = {};
-    properties.forEach(([key, propSchema]) => {
-      const value = generateSchemaExample(propSchema, key);
-      if (value !== undefined) {
-        obj[key] = value;
+  // For object schemas with properties
+  if (schema.type === "object" && schema.properties) {
+    // biome-ignore lint/suspicious/noExplicitAny: Allow any type
+    const example: Record<string, any> = {};
+
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      if (typeof propSchema === "object") {
+        example[key] = generateSchemaExample(propSchema as SchemaObject, key);
       }
-    });
-    return obj;
-  } else if (schema.type === "array" && schema.items) {
-    const value = generateSchemaExample(schema.items, name);
-    if (value !== undefined) {
-      return [value];
+    }
+
+    return example;
+  }
+
+  if (schema.type === "array") {
+    if (Array.isArray(schema.items)) {
+      return schema.items.map((itemSchema) =>
+        generateSchemaExample(itemSchema as SchemaObject),
+      );
+    }
+    if (schema.items) {
+      return [generateSchemaExample(schema.items as SchemaObject)];
     }
     return [];
   }
-  // Fallback for missing or undefined types
-  return undefined; //getDefaultForType(schema.type);
-}
 
-function getDefaultForType(type?: string | string[]): any {
-  if (Array.isArray(type)) {
-    return getDefaultForSingleType(type[0]);
+  if (schema.format !== undefined) {
+    // Partial implementation of JSON Schema format examples
+    // https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7.3
+    switch (schema.format) {
+      case "date-time":
+        return "2024-08-25T15:00:00Z";
+      case "date":
+        return "2024-08-25";
+      case "time":
+        return "15:00:00";
+      case "email":
+        return "test@example.com";
+      case "uri":
+        return "https://www.example.com/path/to/resource";
+      case "uri-reference":
+        return "/path/to/resource";
+      case "uuid":
+        return "00000000-0000-0000-0000-000000000000";
+    }
+  }
+
+  if (schema.enum) {
+    return schema.enum[0];
+  }
+
+  if (schema.oneOf && schema.oneOf.length > 0) {
+    return generateSchemaExample(schema.oneOf[0]);
   }
-  return getDefaultForSingleType(type);
-}
 
-function getDefaultForSingleType(type?: string): any {
-  switch (type) {
+  if (schema.anyOf && schema.anyOf.length > 0) {
+    // Should likely be expanded to return a partial set of values, but it would require
+    // detection if being used within an array or a string type.
+    return generateSchemaExample(schema.anyOf[0]);
+  }
+
+  // Check for property-level examples
+  if (
+    schema.examples &&
+    Array.isArray(schema.examples) &&
+    schema.examples.length > 0
+  ) {
+    return schema.examples[0];
+  }
+
+  switch (schema.type) {
     case "string":
-      return "";
+      return name || "string";
     case "number":
     case "integer":
       return 0;
     case "boolean":
-      return false;
+      return true;
     case "null":
       return null;
+    case "object":
+      return {};
     default:
-      return "undefined";
+      return {};
   }
-}
+};