zudoku 0.0.0-z3809aef2 → 0.0.0-z63644134

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.0.0-z3809aef2",
+  "version": "0.0.0-z63644134",
   "type": "module",
   "homepage": "https://zudoku.dev",
   "repository": {
@@ -18,6 +18,7 @@
     "src/lib",
     "src/app",
     "src/shiki",
+    "src/zuplo",
     "client.d.ts"
   ],
   "bin": {
@@ -154,6 +155,7 @@
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "14.1.1",
     "@envelop/core": "5.3.2",
+    "@fastify/deepmerge": "3.1.0",
     "@graphql-typed-document-node/core": "3.2.0",
     "@lekoarts/rehype-meta-as-attributes": "3.0.3",
     "@mdx-js/react": "3.1.1",
@@ -184,11 +186,11 @@
     "@radix-ui/react-visually-hidden": "1.2.4",
     "@scalar/openapi-parser": "0.23.2",
     "@sentry/node": "10.27.0",
-    "@shikijs/engine-javascript": "3.20.0",
-    "@shikijs/langs": "3.20.0",
-    "@shikijs/rehype": "3.20.0",
-    "@shikijs/themes": "3.20.0",
-    "@shikijs/transformers": "3.20.0",
+    "@shikijs/engine-javascript": "3.21.0",
+    "@shikijs/langs": "3.21.0",
+    "@shikijs/rehype": "3.21.0",
+    "@shikijs/themes": "3.21.0",
+    "@shikijs/transformers": "3.21.0",
     "@sindresorhus/slugify": "3.0.0",
     "@stefanprobst/rehype-extract-toc": "3.0.0",
     "@tailwindcss/typography": "0.5.19",
@@ -232,7 +234,7 @@
     "pagefind": "1.5.0-beta.1",
     "picocolors": "1.1.1",
     "piscina": "5.1.4",
-    "posthog-node": "5.14.1",
+    "posthog-node": "5.21.2",
     "react-error-boundary": "6.0.0",
     "react-hook-form": "7.66.0",
     "react-is": "19.2.3",
@@ -249,7 +251,7 @@
     "remark-mdx-frontmatter": "5.2.0",
     "rollup": "4.52.5",
     "semver": "7.7.2",
-    "shiki": "3.20.0",
+    "shiki": "3.21.0",
     "sitemap": "9.0.0",
     "strip-ansi": "7.1.2",
     "tailwind-merge": "3.4.0",
@@ -262,12 +264,12 @@
     "vite": "6.4.1",
     "yaml": "2.8.1",
     "yargs": "18.0.0",
-    "zod": "4.1.12",
+    "zod": "4.3.6",
     "zustand": "5.0.8"
   },
   "devDependencies": {
     "@graphql-codegen/cli": "6.1.0",
-    "@inkeep/cxkit-types": "0.5.101",
+    "@inkeep/cxkit-types": "0.5.113",
     "@testing-library/dom": "10.4.1",
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/react": "16.3.0",

package/src/lib/components/index.ts

@@ -1,46 +1,26 @@
-import { useMDXComponents as useMDXComponentsImport } from "@mdx-js/react";
-import { Helmet } from "@zudoku/react-helmet-async";
-import { useTheme as useThemeImport } from "next-themes";
-import { Link as LinkImport } from "react-router";
-import { useAuth as useAuthImport } from "../authentication/hook.js";
-import { Button as ButtonImport } from "../ui/Button.js";
-import { Callout as CalloutImport } from "../ui/Callout.js";
-import { ZudokuError as ZudokuErrorImport } from "../util/invariant.js";
-import { ClientOnly as ClientOnlyImport } from "./ClientOnly.js";
-import {
-  CACHE_KEYS as CACHE_KEYS_IMPORT,
-  useCache as useCacheImport,
-} from "./cache.js";
-import { useZudoku as useZudokuImport } from "./context/ZudokuContext.js";
-import { Heading as HeadingImport } from "./Heading.js";
-import { Markdown as MarkdownImport } from "./Markdown.js";
-import { Slot as SlotImport } from "./Slot.js";
-import { Spinner as SpinnerImport } from "./Spinner.js";
-import { Typography as TypographyImport } from "./Typography.js";
-import { Zudoku as ZudokuImport } from "./Zudoku.js";
+export { Helmet as Head } from "@zudoku/react-helmet-async";
+export { Link } from "react-router";
+export { Button } from "../ui/Button.js";
+export { Callout } from "../ui/Callout.js";
+export { ZudokuError } from "../util/invariant.js";
+export { ClientOnly } from "./ClientOnly.js";
+export { Heading } from "./Heading.js";
+export { Markdown } from "./Markdown.js";
+export { Search } from "./Search.js";
+export { Slot } from "./Slot.js";
+export { Spinner } from "./Spinner.js";
+export { Typography } from "./Typography.js";
+export { Zudoku } from "./Zudoku.js";
 
-export const Head = /*@__PURE__*/ Helmet;
-export const Heading = /*@__PURE__*/ HeadingImport;
-export const Callout = /*@__PURE__*/ CalloutImport;
-export const Markdown = /*@__PURE__*/ MarkdownImport;
-export const Spinner = /*@__PURE__*/ SpinnerImport;
-export const ClientOnly = /*@__PURE__*/ ClientOnlyImport;
-export const Button = /*@__PURE__*/ ButtonImport;
-export const Link = /*@__PURE__*/ LinkImport;
-export const Zudoku = /*@__PURE__*/ ZudokuImport;
-export const Typography = /*@__PURE__*/ TypographyImport;
-export const Slot = /*@__PURE__*/ SlotImport;
-export const ZudokuError = /*@__PURE__*/ ZudokuErrorImport;
+//
 
 /** @deprecated Import from `zudoku/hooks` instead */
-export const useMDXComponents = /*@__PURE__*/ useMDXComponentsImport;
+export { useMDXComponents } from "@mdx-js/react";
 /** @deprecated Import from `zudoku/hooks` instead */
-export const useZudoku = /*@__PURE__*/ useZudokuImport;
+export { useTheme } from "next-themes";
 /** @deprecated Import from `zudoku/hooks` instead */
-export const useAuth = /*@__PURE__*/ useAuthImport;
+export { useAuth } from "../authentication/hook.js";
 /** @deprecated Import from `zudoku/hooks` instead */
-export const useCache = /*@__PURE__*/ useCacheImport;
+export { CACHE_KEYS, useCache } from "./cache.js";
 /** @deprecated Import from `zudoku/hooks` instead */
-export const CACHE_KEYS = /*@__PURE__*/ CACHE_KEYS_IMPORT;
-/** @deprecated Import from `zudoku/hooks` instead */
-export const useTheme = /*@__PURE__*/ useThemeImport;
+export { useZudoku } from "./context/ZudokuContext.js";

package/src/lib/core/plugins.ts

@@ -3,6 +3,7 @@ import type { ReactNode } from "react";
 import type { Location, RouteObject } from "react-router";
 import type { Navigation } from "../../config/validators/NavigationSchema.js";
 import type { ProtectedRoutesInput } from "../../config/validators/ProtectedRoutesSchema.js";
+import type { ZudokuConfig } from "../../config/validators/validate.js";
 import type { AuthenticationPlugin } from "../authentication/authentication.js";
 import type { MdxComponentsType } from "../util/MdxComponents.js";
 import type {
@@ -18,7 +19,8 @@ export type ZudokuPlugin =
   | ApiIdentityPlugin
   | SearchProviderPlugin
   | EventConsumerPlugin
-  | AuthenticationPlugin;
+  | AuthenticationPlugin
+  | TransformConfigPlugin;
 
 export type { AuthenticationPlugin, RouteObject };
 
@@ -60,6 +62,19 @@ export type ProfileNavigationItem = {
   icon?: LucideIcon;
 };
 
+export interface ConfigHookContext {
+  mode: typeof process.env.ZUDOKU_ENV;
+  rootDir: string;
+  configPath: string;
+}
+
+export interface TransformConfigPlugin {
+  transformConfig?: (
+    config: ZudokuConfig,
+    ctx: ConfigHookContext,
+  ) => Partial<ZudokuConfig> | void | Promise<Partial<ZudokuConfig> | void>;
+}
+
 export interface CommonPlugin {
   initialize?: (
     context: ZudokuContext,
@@ -110,3 +125,8 @@ export const isApiIdentityPlugin = (
   obj: ZudokuPlugin,
 ): obj is ApiIdentityPlugin =>
   "getIdentities" in obj && typeof obj.getIdentities === "function";
+
+export const isTransformConfigPlugin = (
+  obj: ZudokuPlugin,
+): obj is TransformConfigPlugin =>
+  "transformConfig" in obj && typeof obj.transformConfig === "function";

package/src/lib/core/transform-config.ts

@@ -0,0 +1,29 @@
+import createDeepmerge from "@fastify/deepmerge";
+import type { ConfigWithMeta } from "../../config/loader.js";
+import { type ConfigHookContext, isTransformConfigPlugin } from "./plugins.js";
+
+const mergeConfig = createDeepmerge({
+  mergeArray: (opt) => (_, source) => opt.clone(source),
+});
+
+export const runTransformConfigHooks = async (
+  config: ConfigWithMeta,
+): Promise<ConfigWithMeta> => {
+  const ctx = {
+    mode: config.__meta.mode,
+    rootDir: config.__meta.rootDir,
+    configPath: config.__meta.configPath,
+  } satisfies ConfigHookContext;
+  const plugins = config.plugins ?? [];
+
+  let result = config;
+
+  for (const plugin of plugins.filter(isTransformConfigPlugin)) {
+    const partial = await plugin.transformConfig?.(result, ctx);
+    if (!partial) continue;
+
+    result = mergeConfig(result, partial) as ConfigWithMeta;
+  }
+
+  return result;
+};

package/src/lib/hooks/index.ts

@@ -1,16 +1,7 @@
-import { useMDXComponents as useMDXComponentsImport } from "@mdx-js/react";
-import { useTheme as useThemeImport } from "next-themes";
-import { useAuth as useAuthImport } from "../authentication/hook.js";
-import { CACHE_KEYS, useCache as useCacheImport } from "../components/cache.js";
-import { useZudoku as useZudokuImport } from "../components/context/ZudokuContext.js";
-import { useExposedProps as useExposedPropsImport } from "../util/useExposedProps.js";
-import { useEvent as useEventImport } from "./useEvent.js";
-
-export const useEvent = /*@__PURE__*/ useEventImport;
-export const useTheme = /*@__PURE__*/ useThemeImport;
-export const useExposedProps = /*@__PURE__*/ useExposedPropsImport;
-export const useMDXComponents = /*@__PURE__*/ useMDXComponentsImport;
-export const useAuth = /*@__PURE__*/ useAuthImport;
-export const useZudoku = /*@__PURE__*/ useZudokuImport;
-export const useCache = /*@__PURE__*/ useCacheImport;
-export { CACHE_KEYS };
+export { useMDXComponents } from "@mdx-js/react";
+export { useTheme } from "next-themes";
+export { useAuth } from "../authentication/hook.js";
+export { CACHE_KEYS, useCache } from "../components/cache.js";
+export { useZudoku } from "../components/context/ZudokuContext.js";
+export { useExposedProps } from "../util/useExposedProps.js";
+export { useEvent } from "./useEvent.js";

package/src/lib/oas/graphql/circular.test.ts

@@ -156,16 +156,20 @@ describe("handleCircularRefs", () => {
     });
   });
 
-  it("should deduplicate shared object instances with __$ref", () => {
+  it("should handle shared object instances with __$ref without marking circular", () => {
     const shared = { __$ref: "#/components/schemas/Foo", type: "string" };
     const obj = { a: shared, b: shared };
     const result = handleCircularRefs(obj);
 
+    // Both should return the cached result, not mark as circular
     expect(result.a).toEqual({
       __$ref: "#/components/schemas/Foo",
       type: "string",
     });
-    expect(result.b).toBe(`${SCHEMA_REF_PREFIX}#/components/schemas/Foo`);
+    expect(result.b).toEqual({
+      __$ref: "#/components/schemas/Foo",
+      type: "string",
+    });
   });
 
   it("should mark circular ref with property name from path", () => {
@@ -183,4 +187,35 @@ describe("handleCircularRefs", () => {
 
     expect(result.properties.child.properties.back).toContain(CIRCULAR_REF);
   });
+
+  // Exact reproduction of #1869 - shared object instances with __$ref
+  it("should NOT mark shared object instances with __$ref as circular (issue #1869)", () => {
+    // When dereferencing, the SAME object instance is returned for all refs to the same schema
+    const timestampSchema = {
+      __$ref: "#/components/schemas/timestamp",
+      type: "string",
+      format: "date-time",
+    };
+
+    // Both created_at and updated_at point to the SAME object instance
+    const obj = {
+      type: "object",
+      properties: {
+        created_at: timestampSchema,
+        updated_at: timestampSchema,
+      },
+    };
+
+    const result = handleCircularRefs(obj);
+
+    // The first one should be fully expanded
+    expect(result.properties.created_at).toEqual({
+      __$ref: "#/components/schemas/timestamp",
+      type: "string",
+      format: "date-time",
+    });
+    // The second one should ALSO be fully expanded (not marked as circular)
+    expect(typeof result.properties.updated_at).toBe("object");
+    expect(result.properties.updated_at).not.toContain(CIRCULAR_REF);
+  });
 });

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

@@ -1,6 +1,5 @@
 import { GraphQLScalarType } from "graphql/index.js";
 import { GraphQLJSON } from "graphql-type-json";
-import type { RecordAny } from "../../util/traverse.js";
 
 export const CIRCULAR_REF = "$[Circular Reference]";
 export const SCHEMA_REF_PREFIX = "$ref:";
@@ -17,73 +16,48 @@ const OPENAPI_PROPS = new Set([
 export const handleCircularRefs = (
   // biome-ignore lint/suspicious/noExplicitAny: Allow any type
   obj: any,
-  visited = new WeakSet(),
+  currentPath = new WeakSet(),
   refs = new WeakMap(),
   path: string[] = [],
-  seenRefPaths = new Set<string>(),
+  currentRefPaths = new Set<string>(),
   // biome-ignore lint/suspicious/noExplicitAny: Allow any type
 ): any => {
   if (obj === null || typeof obj !== "object") return obj;
 
   const refPath = obj.__$ref;
+  const isCircular =
+    currentPath.has(obj) ||
+    (typeof refPath === "string" && currentRefPaths.has(refPath));
 
-  // Check if this object has a __$ref marker (set during schema code generation)
-  // If we've already fully processed this ref path, return a reference marker
-  // instead of the full data to avoid JSON.stringify serializing duplicates
-  if (typeof refPath === "string" && seenRefPaths.has(refPath)) {
-    return SCHEMA_REF_PREFIX + refPath;
-  }
-
-  if (visited.has(obj)) {
-    const cached = refs.get(obj);
-    if (cached) {
-      return typeof refPath === "string"
-        ? // If already processed, return ref marker to avoid duplicate serialization
-          SCHEMA_REF_PREFIX + refPath
-        : cached;
-    }
+  if (isCircular) {
+    if (typeof refPath === "string") return SCHEMA_REF_PREFIX + refPath;
     const circularProp = path.find((p) => !OPENAPI_PROPS.has(p)) || path[0];
-
     return [CIRCULAR_REF, circularProp].filter(Boolean).join(":");
   }
 
-  visited.add(obj);
+  if (refs.has(obj)) return refs.get(obj);
 
-  // Add refPath BEFORE recursing to detect cycles within this branch
-  // This will be removed after processing to allow siblings with the same ref
-  if (typeof refPath === "string") {
-    seenRefPaths.add(refPath);
-  }
+  currentPath.add(obj);
+  if (typeof refPath === "string") currentRefPaths.add(refPath);
 
-  let result: RecordAny | RecordAny[];
-  if (Array.isArray(obj)) {
-    result = obj.map((item, index) =>
-      handleCircularRefs(
-        item,
-        visited,
-        refs,
-        [...path, index.toString()],
-        seenRefPaths,
-      ),
+  const recurse = (value: unknown, key: string) =>
+    handleCircularRefs(
+      value,
+      currentPath,
+      refs,
+      [...path, key],
+      currentRefPaths,
     );
-  } else {
-    result = {};
-    for (const [key, value] of Object.entries(obj)) {
-      result[key] = handleCircularRefs(
-        value,
-        visited,
-        refs,
-        [...path, key],
-        seenRefPaths,
+
+  const result = Array.isArray(obj)
+    ? obj.map((item, i) => recurse(item, i.toString()))
+    : Object.fromEntries(
+        Object.entries(obj).map(([k, v]) => [k, recurse(v, k)]),
       );
-    }
-  }
-  refs.set(obj, result);
 
-  // Remove refPath after processing so sibling refs aren't incorrectly marked
-  if (typeof refPath === "string") {
-    seenRefPaths.delete(refPath);
-  }
+  refs.set(obj, result);
+  currentPath.delete(obj);
+  if (typeof refPath === "string") currentRefPaths.delete(refPath);
 
   return result;
 };

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

@@ -1,6 +1,7 @@
 import { GraphQLError } from "graphql/error/index.js";
 import { OpenAPIV3, type OpenAPIV3_1 } from "openapi-types";
-import { flattenAllOfProcessor } from "../../util/flattenAllOf.js";
+import { flattenAllOf } from "../../util/flattenAllOf.js";
+import { traverse } from "../../util/traverse.js";
 import { dereference, type JSONSchema } from "./dereference/index.js";
 import { upgradeSchema } from "./upgrade/index.js";
 
@@ -104,11 +105,21 @@ export const validate = async (schemaInput: unknown) => {
   const dereferenced = await dereference(schema);
   const upgraded = upgradeSchema(dereferenced);
 
-  const flattened = await flattenAllOfProcessor({
-    schema: upgraded,
-    file: "schema.json",
-    dereference: async (schema) => schema,
-  });
+  const flattened = traverse(upgraded, (spec) => {
+    if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+      return spec;
+    }
+    const isSchemaObject =
+      "type" in spec ||
+      "properties" in spec ||
+      "allOf" in spec ||
+      "anyOf" in spec ||
+      "oneOf" in spec;
+
+    if (!isSchemaObject) return spec;
+
+    return flattenAllOf(spec) as typeof spec;
+  }) as OpenAPIDocument;
 
   return flattened;
 };

package/src/lib/util/flattenAllOf.test.ts

@@ -1,7 +1,8 @@
 import type { JSONSchema7 } from "json-schema";
 import { describe, expect, it, vi } from "vitest";
 import type { OpenAPIDocument } from "../oas/parser/index.js";
-import { flattenAllOf, flattenAllOfProcessor } from "./flattenAllOf.js";
+import { flattenAllOf } from "./flattenAllOf.js";
+import { flattenAllOfProcessor } from "./flattenAllOfProcessor.js";
 import invariant from "./invariant.js";
 
 describe("flattenAllOf", () => {

package/src/lib/util/flattenAllOf.ts

@@ -1,4 +1,3 @@
-import { $RefParser } from "@apidevtools/json-schema-ref-parser";
 import {
   createComparator,
   createMerger,
@@ -9,62 +8,6 @@ import {
   createIntersector,
 } from "@x0k/json-schema-merge/lib/array";
 import type { JSONSchema7Definition } from "json-schema";
-import type { Processor } from "../../config/validators/BuildSchema.js";
-import type { OpenAPIDocument } from "../oas/parser/index.js";
-import { type RecordAny, traverse } from "./traverse.js";
-
-export const flattenAllOfProcessor: Processor = async ({ schema, file }) => {
-  try {
-    // Resolve refs once - creates a lookup table without modifying the schema
-    const parser = new $RefParser();
-    await parser.resolve(schema);
-    const $refs = parser.$refs;
-
-    const flattened = traverse(schema, (spec) => {
-      if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
-        return spec;
-      }
-
-      const isSchemaObject =
-        "type" in spec ||
-        "properties" in spec ||
-        "allOf" in spec ||
-        "anyOf" in spec ||
-        "oneOf" in spec;
-
-      if (!isSchemaObject) return spec;
-
-      if ("allOf" in spec && Array.isArray(spec.allOf)) {
-        const resolvedAllOf = spec.allOf.map((item) => {
-          if (
-            item &&
-            typeof item === "object" &&
-            "$ref" in item &&
-            typeof item.$ref === "string"
-          ) {
-            try {
-              return $refs.get(item.$ref) ?? item;
-            } catch {
-              return item;
-            }
-          }
-          return item;
-        });
-        return flattenAllOf({ ...spec, allOf: resolvedAllOf }) as RecordAny;
-      }
-
-      return flattenAllOf(spec) as RecordAny;
-    }) as OpenAPIDocument;
-
-    return flattened;
-  } catch (error) {
-    // biome-ignore lint/suspicious/noConsole: Logging allowed here
-    console.warn(
-      `Failed to flatten \`allOf\` in ${file}: ${error instanceof Error ? error.message : error}`,
-    );
-    return schema;
-  }
-};
 
 const { compareSchemaDefinitions, compareSchemaValues } = createComparator();
 const { mergeArrayOfSchemaDefinitions } = createMerger({

package/src/lib/util/flattenAllOfProcessor.ts

@@ -0,0 +1,58 @@
+import { $RefParser } from "@apidevtools/json-schema-ref-parser";
+import type { Processor } from "../../config/validators/BuildSchema.js";
+import type { OpenAPIDocument } from "../oas/parser/index.js";
+import { flattenAllOf } from "./flattenAllOf.js";
+import { type RecordAny, traverse } from "./traverse.js";
+
+export const flattenAllOfProcessor: Processor = async ({ schema, file }) => {
+  try {
+    // Resolve refs once - creates a lookup table without modifying the schema
+    const parser = new $RefParser();
+    await parser.resolve(schema);
+    const $refs = parser.$refs;
+
+    const flattened = traverse(schema, (spec) => {
+      if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+        return spec;
+      }
+
+      const isSchemaObject =
+        "type" in spec ||
+        "properties" in spec ||
+        "allOf" in spec ||
+        "anyOf" in spec ||
+        "oneOf" in spec;
+
+      if (!isSchemaObject) return spec;
+
+      if ("allOf" in spec && Array.isArray(spec.allOf)) {
+        const resolvedAllOf = spec.allOf.map((item) => {
+          if (
+            item &&
+            typeof item === "object" &&
+            "$ref" in item &&
+            typeof item.$ref === "string"
+          ) {
+            try {
+              return $refs.get(item.$ref) ?? item;
+            } catch {
+              return item;
+            }
+          }
+          return item;
+        });
+        return flattenAllOf({ ...spec, allOf: resolvedAllOf }) as RecordAny;
+      }
+
+      return flattenAllOf(spec) as RecordAny;
+    }) as OpenAPIDocument;
+
+    return flattened;
+  } catch (error) {
+    // biome-ignore lint/suspicious/noConsole: Logging allowed here
+    console.warn(
+      `Failed to flatten \`allOf\` in ${file}: ${error instanceof Error ? error.message : error}`,
+    );
+    return schema;
+  }
+};

package/src/lib/util/readFrontmatter.ts

@@ -9,5 +9,6 @@ export const yaml = {
 
 export const readFrontmatter = async (filePath: string) => {
   const content = await readFile(filePath, "utf-8");
-  return matter(content, { engines: { yaml } });
+  const normalizedContent = content.replace(/\r\n/g, "\n");
+  return matter(normalizedContent, { engines: { yaml } });
 };

package/src/shiki/langs/c3.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/c3";

package/src/shiki/langs/gn.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/gn";

package/src/shiki/langs/moonbit.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/moonbit";