zudoku 0.0.0-f90a252 → 0.0.0-f9211eb

package/src/lib/oas/graphql/index.ts

@@ -42,37 +42,41 @@ type OperationLike = {
 export const createOperationSlug = (
   slugify: CountableSlugify,
   operation: OperationLike,
-  tag?: string,
 ) => {
   const summary =
     operation.summary ||
     operation.operationId ||
     `${operation.method}-${operation.path}`;
-  const prefix = tag ? `${tag}-` : "";
 
-  return slugify(prefix + summary);
+  return slugify(summary);
 };
 
-export type SchemaImports = Record<
-  string,
-  () => Promise<{ schema: OpenAPIDocument }>
->;
+export type SchemaImport = () => Promise<{
+  schema: OpenAPIDocument;
+  slugs: ReturnType<typeof getAllSlugs>;
+}>;
+
+export type SchemaImports = Record<string, SchemaImport>;
+
+type Context = {
+  schema: OpenAPIDocument;
+  operations: GraphQLOperationObject[];
+  schemaImports?: SchemaImports;
+  tags: ReturnType<typeof getAllTags>;
+  slugs: ReturnType<typeof getAllSlugs>;
+};
 
 const builder = new SchemaBuilder<{
+  DefaultFieldNullability: false;
   Scalars: {
     JSON: any;
     JSONObject: any;
     JSONSchema: any;
   };
-  Context: {
-    schema: OpenAPIDocument;
-    operations: GraphQLOperationObject[];
-    tags: TagObject[];
-    schemaImports?: SchemaImports;
-    currentTag?: string;
-    slugify: CountableSlugify;
-  };
-}>({});
+  Context: Context;
+}>({
+  defaultFieldNullability: false,
+});
 
 type GraphQLOperationObject = OperationObject & {
   path: string;
@@ -85,7 +89,15 @@ const JSONScalar = builder.addScalarType("JSON", GraphQLJSON);
 const JSONObjectScalar = builder.addScalarType("JSONObject", GraphQLJSONObject);
 const JSONSchemaScalar = builder.addScalarType("JSONSchema", GraphQLJSONSchema);
 
-export const getAllTags = (schema: OpenAPIDocument): TagObject[] => {
+const resolveExtensions = (obj: Record<string, any>) =>
+  Object.fromEntries(
+    Object.entries(obj).filter(([key]) => key.startsWith("x-")),
+  );
+
+export const getAllTags = (
+  schema: OpenAPIDocument,
+  slugs: ReturnType<typeof getAllSlugs>["tags"],
+): Array<Omit<TagObject, "name"> & { name?: string; slug?: string }> => {
   const rootTags = schema.tags ?? [];
   const operationTags = new Set(
     Object.values(schema.paths ?? {})
@@ -93,16 +105,53 @@ export const getAllTags = (schema: OpenAPIDocument): TagObject[] => {
       .flatMap((op) => (op as OperationObject).tags ?? []),
   );
 
+  const hasUntaggedOperations = Object.values(schema.paths ?? {}).some((path) =>
+    Object.values(path ?? {}).some(
+      (op) => !(op as OperationObject).tags?.length,
+    ),
+  );
+
   return [
     // Keep root tags that are actually used in operations
-    ...rootTags.filter((tag) => operationTags.has(tag.name)),
+    ...rootTags
+      .filter((tag) => operationTags.has(tag.name))
+      .map((tag) => ({ ...tag, slug: slugs[tag.name] })),
     // Add tags found in operations but not defined in root tags
     ...[...operationTags]
       .filter((tag) => !rootTags.some((rt) => rt.name === tag))
-      .map((tag) => ({ name: tag })),
+      .map((tag) => ({ name: tag, slug: slugs[tag] })),
+    // Add untagged operations if there are any
+    ...(hasUntaggedOperations ? [{ name: undefined, slug: undefined }] : []),
   ];
 };
 
+export const getAllSlugs = (
+  ops: GraphQLOperationObject[],
+  schemaTags: TagObject[] = [],
+) => {
+  const slugify = slugifyWithCounter();
+
+  const tags = Array.from(
+    new Set([
+      ...ops.flatMap((op) => op.tags ?? []),
+      ...schemaTags.map((tag) => tag.name),
+    ]),
+  );
+
+  return {
+    operations: Object.fromEntries(
+      ops.map((op) => [
+        getOperationSlugKey(op),
+        createOperationSlug(slugify, op),
+      ]),
+    ),
+    tags: Object.fromEntries(tags.map((tag) => [tag, slugify(tag)])),
+  };
+};
+
+const getOperationSlugKey = (op: GraphQLOperationObject) =>
+  [op.path, op.method, op.operationId, op.summary].filter(Boolean).join("-");
+
 export const getAllOperations = (
   paths?: PathsObject,
 ): GraphQLOperationObject[] => {
@@ -140,14 +189,21 @@ export const getAllOperations = (
   return operations;
 };
 
-const SchemaTag = builder.objectRef<TagObject>("SchemaTag").implement({
+const SchemaTag = builder.objectRef<
+  Omit<TagObject, "name"> & { name?: string; slug?: string }
+>("SchemaTag");
+
+SchemaTag.implement({
   fields: (t) => ({
-    name: t.exposeString("name"),
+    name: t.exposeString("name", { nullable: true }),
+    slug: t.exposeString("slug", { nullable: true }),
+    isUntagged: t.field({ type: "Boolean", resolve: (parent) => !parent.name }),
     description: t.exposeString("description", { nullable: true }),
     operations: t.field({
       type: [OperationItem],
       resolve: (parent, _args, ctx) => {
         const rootTags = ctx.tags.map((tag) => tag.name);
+
         return ctx.operations
           .filter((item) =>
             parent.name
@@ -156,12 +212,30 @@ const SchemaTag = builder.objectRef<TagObject>("SchemaTag").implement({
                 // If none of the tags are present in the root tags, then show them here
                 item.tags?.every((tag) => !rootTags.includes(tag)),
           )
-          .map((item) => ({
-            ...item,
-            parentTag: parent.name,
-          }));
+          .map((item) => ({ ...item, parentTag: parent.name }));
+      },
+    }),
+    prev: t.field({
+      type: SchemaTag,
+      nullable: true,
+      resolve: (parent, _args, ctx) => {
+        const index = ctx.tags.findIndex((tag) => tag.slug === parent.slug);
+        return ctx.tags[index - 1];
+      },
+    }),
+    next: t.field({
+      type: SchemaTag,
+      nullable: true,
+      resolve: (parent, _args, ctx) => {
+        const index = ctx.tags.findIndex((tag) => tag.slug === parent.slug);
+        return ctx.tags[index + 1];
       },
     }),
+    extensions: t.field({
+      type: JSONObjectScalar,
+      resolve: (parent) => resolveExtensions(parent),
+      nullable: true,
+    }),
   }),
 });
 
@@ -188,6 +262,11 @@ const TagItem = builder.objectRef<TagObject>("TagItem").implement({
   fields: (t) => ({
     name: t.exposeString("name"),
     description: t.exposeString("description", { nullable: true }),
+    extensions: t.field({
+      type: JSONObjectScalar,
+      resolve: (parent) => resolveExtensions(parent),
+      nullable: true,
+    }),
   }),
 });
 
@@ -246,6 +325,11 @@ const ParameterItem = builder
         nullable: true,
       }),
       schema: t.expose("schema", { type: JSONSchemaScalar, nullable: true }),
+      extensions: t.field({
+        type: JSONObjectScalar,
+        resolve: (parent) => resolveExtensions(parent),
+        nullable: true,
+      }),
     }),
   });
 
@@ -303,6 +387,11 @@ const ResponseItem = builder
       content: t.expose("content", { type: [MediaTypeItem], nullable: true }),
       headers: t.expose("headers", { type: JSONScalar, nullable: true }),
       links: t.expose("links", { type: JSONScalar, nullable: true }),
+      extensions: t.field({
+        type: JSONObjectScalar,
+        resolve: (parent) => resolveExtensions(parent),
+        nullable: true,
+      }),
     }),
   });
 
@@ -313,18 +402,16 @@ const OperationItem = builder
       slug: t.field({
         type: "String",
         resolve: (parent, _, ctx) => {
-          const slugData = {
-            summary: parent.summary,
-            operationId: parent.operationId,
-            path: parent.path,
-            method: parent.method,
-          };
-
-          //TODO: fix parent tag parent.tags
-          return createOperationSlug(ctx.slugify, slugData, parent.parentTag);
+          const slug = ctx.slugs.operations[getOperationSlugKey(parent)];
+
+          if (!slug) {
+            throw new Error(
+              `No slug found for operation: ${getOperationSlugKey(parent)}`,
+            );
+          }
+          return slug;
         },
       }),
-
       path: t.exposeString("path"),
       method: t.exposeString("method"),
       operationId: t.exposeString("operationId", { nullable: true }),
@@ -396,9 +483,51 @@ const OperationItem = builder
         nullable: true,
       }),
       deprecated: t.exposeBoolean("deprecated", { nullable: true }),
+      extensions: t.field({
+        type: JSONObjectScalar,
+        resolve: (parent) => resolveExtensions(parent),
+        nullable: true,
+      }),
     }),
   });
 
+const SchemaItem = builder
+  .objectRef<{
+    name: string;
+    schema: SchemaObject;
+    extensions?: Record<string, any>;
+  }>("SchemaItem")
+  .implement({
+    fields: (t) => ({
+      name: t.exposeString("name"),
+      schema: t.expose("schema", { type: JSONSchemaScalar }),
+      extensions: t.expose("extensions", {
+        type: JSONObjectScalar,
+        nullable: true,
+      }),
+    }),
+  });
+
+const Components = builder.objectRef<{
+  schemas?: Record<string, SchemaObject>;
+}>("Components");
+
+Components.implement({
+  fields: (t) => ({
+    schemas: t.field({
+      type: [SchemaItem],
+      resolve: (parent) => {
+        return Object.entries(parent.schemas ?? {}).map(([name, schema]) => ({
+          name,
+          schema,
+          extensions: resolveExtensions(schema),
+        }));
+      },
+      nullable: true,
+    }),
+  }),
+});
+
 const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
   fields: (t) => ({
     openapi: t.string({ resolve: (root) => root.openapi }),
@@ -428,17 +557,30 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
           methods: Object.keys(value!) as typeof HttpMethods,
         })),
     }),
-    tags: t.field({
+    tag: t.field({
+      type: SchemaTag,
       args: {
+        slug: t.arg.string(),
         name: t.arg.string(),
+        untagged: t.arg.boolean(),
       },
-      type: [SchemaTag],
-      resolve: (root, args, ctx) => {
-        return args.name
-          ? ctx.tags.filter((tag) => tag.name === args.name)
-          : ctx.tags;
+      nullable: true,
+      resolve: (_, args, ctx) => {
+        if (args.untagged) {
+          return ctx.tags.find((tag) => tag.name === undefined);
+        }
+        if (args.slug) {
+          return ctx.tags.find((tag) => tag.slug === args.slug);
+        }
+        if (args.name) {
+          return ctx.tags.find((tag) => tag.name === args.name);
+        }
       },
     }),
+    tags: t.field({
+      type: [SchemaTag],
+      resolve: (_root, _args, ctx) => ctx.tags,
+    }),
     operations: t.field({
       type: [OperationItem],
       args: {
@@ -448,7 +590,7 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
         tag: t.arg.string(),
         untagged: t.arg.boolean(),
       },
-      resolve: (parent, args, ctx) =>
+      resolve: (_parent, args, ctx) =>
         ctx.operations.filter((op) => {
           return (
             (!args.operationId || op.operationId === args.operationId) &&
@@ -459,6 +601,16 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
           );
         }),
     }),
+    components: t.field({
+      type: Components,
+      resolve: (root) => root.components,
+      nullable: true,
+    }),
+    extensions: t.field({
+      type: JSONObjectScalar,
+      resolve: (root) => resolveExtensions(root),
+      nullable: true,
+    }),
   }),
 });
 
@@ -474,27 +626,26 @@ builder.queryType({
         type: t.arg({ type: SchemaSource, required: true }),
         input: t.arg({ type: JSONScalar, required: true }),
       },
-      resolve: async (_, args, ctx) => {
-        let schema: OpenAPIDocument;
-
+      resolve: async (_parent, args, ctx) => {
         if (args.type === "file" && typeof args.input === "string") {
           const loadSchema = ctx.schemaImports?.[args.input];
 
           if (!loadSchema) {
             throw new Error(`No schema loader found for path: ${args.input}`);
           }
-          const module = await loadSchema();
-          schema = module.schema;
+          const { schema, slugs } = await loadSchema();
+          ctx.schema = schema;
+          ctx.operations = getAllOperations(schema.paths);
+          ctx.slugs = slugs;
+          ctx.tags = getAllTags(schema, ctx.slugs.tags);
         } else {
-          schema = await validate(args.input as string);
+          ctx.schema = await validate(args.input as string);
+          ctx.operations = getAllOperations(ctx.schema.paths);
+          ctx.slugs = getAllSlugs(ctx.operations);
+          ctx.tags = getAllTags(ctx.schema, ctx.slugs.tags);
         }
 
-        ctx.schema = schema;
-        ctx.operations = getAllOperations(schema.paths);
-        ctx.slugify = slugifyWithCounter();
-        ctx.tags = getAllTags(schema);
-
-        return schema;
+        return ctx.schema;
       },
     }),
   }),
@@ -504,4 +655,4 @@ export const schema = builder.toSchema();
 
 export const createGraphQLServer = (
   options?: Omit<YogaServerOptions<any, any>, "schema">,
-) => createYoga({ schema, ...options });
+) => createYoga({ schema, batching: true, ...options });

package/src/lib/oas/parser/dereference/index.ts

@@ -38,6 +38,8 @@ export const dereference = async (
         }
       } else {
         if ("$ref" in current && typeof current.$ref === "string") {
+          // Store the ref path before resolving
+          current.__$ref = current.$ref;
           for (const resolver of resolvers) {
             const resolved = await resolver(current.$ref);
             if (resolved) return await resolve(resolved, path);

package/src/lib/oas/parser/index.ts

@@ -3,11 +3,15 @@ import { OpenAPIV3, type OpenAPIV3_1 } from "openapi-types";
 import { dereference, type JSONSchema } from "./dereference/index.js";
 import { upgradeSchema } from "./upgrade/index.js";
 
-type ReferenceObject = OpenAPIV3_1.ReferenceObject;
-type DeepOmitReference<T> = T extends ReferenceObject
+// Must be an interface (not a type) to allow merging with OpenAPI types with index signatures
+interface WithRef {
+  __$ref?: string;
+}
+
+type DeepOmitReference<T> = T extends OpenAPIV3_1.ReferenceObject
   ? never
   : T extends object
-    ? { [K in keyof T]: DeepOmitReference<T[K]> }
+    ? { [K in keyof T]: DeepOmitReference<T[K]> } & WithRef
     : T;
 
 export type OpenAPIDocument = DeepOmitReference<OpenAPIV3_1.Document>;
@@ -24,25 +28,6 @@ export type ServerObject = DeepOmitReference<OpenAPIV3_1.ServerObject>;
 
 export const HttpMethods = Object.values(OpenAPIV3.HttpMethods);
 
-// class ValidationError extends Error {
-//   constructor(public errors: OutputUnit[]) {
-//     super("Validation error");
-//   }
-// }
-
-// const getValidator = async (openApiVersion: string) => {
-//   if (openApiVersion.startsWith("3.0")) {
-//     const schema = (await import("./schemas/v3.0.json")) as any;
-//     return new Validator(schema, "4");
-//   }
-//   if (openApiVersion.startsWith("3.1")) {
-//     const schema = (await import("./schemas/v3.1.json")) as any;
-//     return new Validator(schema as any, "2020-12");
-//   }
-
-//   throw new Error(`Unsupported OpenAPI version: ${openApiVersion}`);
-// };
-
 const parseSchemaInput = async (
   schemaInput: unknown,
 ): Promise<JSONSchema & { openapi?: string }> => {
@@ -110,13 +95,6 @@ export const validate = async (schemaInput: unknown) => {
     throw new GraphQLError("OpenAPI version is not defined");
   }
 
-  // const validator = await getValidator(schema.openapi);
-  // const result = validator.validate(schema);
-  //
-  // if (!result.valid) {
-  //   throw new ValidationError(result.errors);
-  // }
-
   const dereferenced = await dereference(schema);
 
   return upgradeSchema(dereferenced);

package/src/lib/plugins/api-catalog/Catalog.tsx

@@ -1,121 +1,71 @@
-import slugify from "@sindresorhus/slugify";
 import { useSuspenseQuery } from "@tanstack/react-query";
-import { useSearchParams } from "react-router";
-import { Head, Link } from "zudoku/components";
+import { Helmet } from "@zudoku/react-helmet-async";
+import { useMatch } from "react-router";
+import { Link } from "zudoku/components";
 import { useAuthState } from "../../authentication/state.js";
+import { Heading } from "../../components/Heading.js";
 import { Markdown } from "../../components/Markdown.js";
-import { cn } from "../../util/cn.js";
-import type { ApiCatalogPluginOptions } from "./index.js";
-
-const getKey = (category: string, tag: string) => slugify(`${category}-${tag}`);
+import { joinUrl } from "../../util/joinUrl.js";
+import { type ApiCatalogPluginOptions, getKey } from "./index.js";
 
 export const Catalog = ({
   items,
   filterCatalogItems = (items) => items,
-  categories,
   label = "API Library",
-}: Omit<ApiCatalogPluginOptions, "navigationId">) => {
-  const [searchParams, setSearchParams] = useSearchParams();
-  const activeCategory = searchParams.get("category");
+  categoryLabel,
+}: Omit<ApiCatalogPluginOptions, "navigationId"> & {
+  categoryLabel?: string;
+}) => {
   const auth = useAuthState();
+  const match = useMatch({ path: "/catalog/:category" });
+  const activeCategory = match?.params.category;
 
   const catalogItems = useSuspenseQuery({
     queryFn: () => filterCatalogItems(items, { auth }),
     queryKey: ["catalogItems", auth],
   });
 
+  // Only index the overview page, ignore the rest
+  const dataSet = activeCategory ? { "data-pagefind-ignore": "all" } : {};
+
   return (
-    <section className="pt-[--padding-content-top] pb-[--padding-content-bottom]">
-      <Head>
-        <title>{label}</title>
-      </Head>
-      <div className="grid grid-cols-12 gap-12">
-        <div className="flex flex-col gap-4 col-span-3 not-prose sticky top-48">
-          <div className="max-w-[--side-nav-width] flex flex-col gap-4 justify-between">
-            {categories?.map((category, idx) => (
-              <div key={category.label}>
-                <div className="flex justify-between mb-2.5">
-                  <span className="font-medium text-sm">{category.label}</span>
-                  {idx === 0 && activeCategory && (
-                    <button
-                      type="button"
-                      className="text-end text-sm text-foreground/60 hover:text-foreground"
-                      onClick={() => setSearchParams({})}
-                    >
-                      Clear
-                    </button>
-                  )}
-                </div>
-                <ul className="space-y-1 [&>li]:py-2">
-                  {category.tags
-                    .map((tag) => ({
-                      tag,
-                      count: items.filter((api) =>
-                        api.categories.find((c) => c.tags.includes(tag)),
-                      ).length,
-                    }))
-                    .map(({ tag, count }) => {
-                      const slug = getKey(category.label, tag);
-                      const isActive = slug === activeCategory;
+    <section className="pt-[--padding-content-top]" {...dataSet}>
+      <Helmet>
+        <title>
+          {categoryLabel ? `${categoryLabel} - ` : ""}
+          {label}
+        </title>
+      </Helmet>
+      <div className="grid gap-4">
+        <Heading level={2}>
+          {label}
+          {categoryLabel && ` - ${categoryLabel}`}
+        </Heading>
 
-                      return (
-                        <li
-                          key={slug}
-                          className={cn(
-                            "flex rounded-lg justify-between text-sm cursor-pointer hover:text-primary transition px-[--padding-nav-item] -mx-[--padding-nav-item]",
-                            isActive && "bg-border/30 rounded",
-                          )}
-                          onClick={() => setSearchParams({ category: slug })}
-                        >
-                          <span>{tag}</span>
-                          <span
-                            className={cn(
-                              "flex items-center justify-center border rounded-md w-8 text-xs font-semibold",
-                              isActive &&
-                                "bg-primary border-primary text-primary-foreground",
-                            )}
-                          >
-                            {count}
-                          </span>
-                        </li>
-                      );
-                    })}
-                </ul>
-              </div>
+        <div className="grid grid-cols-2 gap-4">
+          {catalogItems.data
+            .filter(
+              (api) =>
+                !activeCategory ||
+                api.categories.find((c) =>
+                  c.tags.find((t) => getKey(c.label, t) === activeCategory),
+                ),
+            )
+            .map((api) => (
+              <Link
+                to={joinUrl(api.path)}
+                className="no-underline hover:!text-foreground"
+                key={api.path}
+              >
+                <div className="border h-full rounded-lg p-4 flex flex-col gap-2 cursor-pointer hover:bg-border/20 font-normal">
+                  <span className="font-semibold">{api.label}</span>
+                  <Markdown
+                    className="text-sm whitespace-pre-wrap mb-6 line-clamp-2"
+                    content={api.description}
+                  />
+                </div>
+              </Link>
             ))}
-          </div>
-        </div>
-        <div className="col-span-9">
-          <h3 className="mt-0 text-2xl font-bold mb-4">{label}</h3>
-
-          <div className="grid grid-cols-2 gap-4">
-            {catalogItems.data
-              .filter(
-                (api) =>
-                  !activeCategory ||
-                  api.categories.find((c) =>
-                    c.tags.find((t) => getKey(c.label, t) === activeCategory),
-                  ),
-              )
-              .map((api) => (
-                <Link
-                  to={{
-                    pathname: `/${api.path}`,
-                    search: activeCategory ? `category=${activeCategory}` : "",
-                  }}
-                  className="no-underline hover:!text-foreground"
-                  key={api.path}
-                >
-                  <div className="border h-full rounded p-4 flex flex-col gap-2 cursor-pointer hover:bg-border/20 font-normal">
-                    <span className="font-semibold">{api.label}</span>
-                    <Markdown
-                      className="text-sm whitespace-pre-wrap mb-6 line-clamp-2"
-                      content={api.description}
-                    />
-                  </div>
-                </Link>
-              ))}
-          </div>
         </div>
       </div>
     </section>