@mandujs/core 0.54.17 → 0.54.19

package/src/client/serialize.ts

@@ -1,404 +1,50 @@
-/**
- * Mandu Props Serialization 📦
- * Fresh 스타일 고급 직렬화/역직렬화
- *
- * @see https://fresh.deno.dev/docs/concepts/islands
- *
- * 지원 타입:
- * - 원시형: null, boolean, number, string, bigint, undefined
- * - 특수 객체: Date, URL, RegExp, Map, Set
- * - 순환 참조
- * - 중첩 객체/배열
- */
-
-// ============================================
-// 타입 마커
-// ============================================
-
-const TYPE_MARKERS = {
-  /** undefined */
-  UNDEFINED: "\x00_",
-  /** Date */
-  DATE: "\x00D",
-  /** URL */
-  URL: "\x00U",
-  /** RegExp */
-  REGEXP: "\x00R",
-  /** Map */
-  MAP: "\x00M",
-  /** Set */
-  SET: "\x00S",
-  /** 순환 참조 */
-  REF: "\x00$",
-  /** BigInt */
-  BIGINT: "\x00B",
-  /** Symbol (제한적 지원) */
-  SYMBOL: "\x00Y",
-  /** Error */
-  ERROR: "\x00E",
-} as const;
-
-// ============================================
-// 직렬화
-// ============================================
-
-/**
- * 직렬화 컨텍스트 (순환 참조 추적)
- */
-interface SerializeContext {
-  /** 이미 본 객체 → 인덱스 */
-  seen: Map<object, number>;
-  /** 참조 테이블 */
-  refs: object[];
-}
-
-/**
- * Props 직렬화
- *
- * @example
- * ```typescript
- * const props = {
- *   date: new Date(),
- *   url: new URL('https://example.com'),
- *   items: new Set([1, 2, 3]),
- *   cache: new Map([['key', 'value']]),
- * };
- *
- * const json = serializeProps(props);
- * // 클라이언트로 전송
- * ```
- */
-export function serializeProps(props: Record<string, unknown>): string {
-  const ctx: SerializeContext = { seen: new Map(), refs: [] };
-  return JSON.stringify(serialize(props, ctx));
-}
-
-/**
- * 값 직렬화 (재귀)
- */
-function serialize(value: unknown, ctx: SerializeContext): unknown {
-  // null
-  if (value === null) return null;
-
-  // undefined
-  if (value === undefined) return TYPE_MARKERS.UNDEFINED;
-
-  // 원시형
-  if (typeof value === "boolean" || typeof value === "number") {
-    return value;
-  }
-
-  if (typeof value === "string") {
-    // 타입 마커와 충돌 방지 (첫 문자가 \x00인 경우)
-    if (value.startsWith("\x00")) {
-      return "\x00\x00" + value;
-    }
-    return value;
-  }
-
-  if (typeof value === "bigint") {
-    return TYPE_MARKERS.BIGINT + value.toString();
-  }
-
-  if (typeof value === "symbol") {
-    // Symbol은 description만 보존
-    return TYPE_MARKERS.SYMBOL + (value.description ?? "");
-  }
-
-  // 함수는 직렬화 불가
-  if (typeof value === "function") {
-    console.warn("[Mandu Serialize] Functions cannot be serialized, skipping");
-    return undefined;
-  }
-
-  // 객체 순환 참조 체크
-  if (typeof value === "object") {
-    const existing = ctx.seen.get(value);
-    if (existing !== undefined) {
-      return TYPE_MARKERS.REF + existing;
-    }
-
-    const idx = ctx.refs.length;
-    ctx.seen.set(value, idx);
-    ctx.refs.push(value);
-  }
-
-  // Date
-  if (value instanceof Date) {
-    return TYPE_MARKERS.DATE + value.toISOString();
-  }
-
-  // URL
-  if (value instanceof URL) {
-    return TYPE_MARKERS.URL + value.href;
-  }
-
-  // RegExp
-  if (value instanceof RegExp) {
-    return TYPE_MARKERS.REGEXP + value.toString();
-  }
-
-  // Error
-  if (value instanceof Error) {
-    return [
-      TYPE_MARKERS.ERROR,
-      value.name,
-      value.message,
-      value.stack ?? "",
-    ];
-  }
-
-  // Map
-  if (value instanceof Map) {
-    const entries: [unknown, unknown][] = [];
-    for (const [k, v] of value.entries()) {
-      entries.push([serialize(k, ctx), serialize(v, ctx)]);
-    }
-    return [TYPE_MARKERS.MAP, ...entries];
-  }
-
-  // Set
-  if (value instanceof Set) {
-    const items: unknown[] = [];
-    for (const item of value) {
-      items.push(serialize(item, ctx));
-    }
-    return [TYPE_MARKERS.SET, ...items];
-  }
-
-  // 배열
-  if (Array.isArray(value)) {
-    return value.map((item) => serialize(item, ctx));
-  }
-
-  // 일반 객체
-  const result: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(value as object)) {
-    const serialized = serialize(v, ctx);
-    if (serialized !== undefined) {
-      result[k] = serialized;
-    }
-  }
-  return result;
-}
-
-// ============================================
-// 역직렬화
-// ============================================
-
-/**
- * 역직렬화 컨텍스트 (순환 참조 복원)
- */
-interface DeserializeContext {
-  refs: unknown[];
-}
-
-/**
- * Props 역직렬화
- *
- * @example
- * ```typescript
- * // 서버에서 받은 JSON
- * const json = '{"date":"\x00D2025-01-28T00:00:00.000Z"}';
- *
- * const props = deserializeProps(json);
- * console.log(props.date instanceof Date); // true
- * ```
- */
-export function deserializeProps(json: string): Record<string, unknown> {
-  const ctx: DeserializeContext = { refs: [] };
-  const parsed = JSON.parse(json);
-  return deserialize(parsed, ctx) as Record<string, unknown>;
-}
-
-/**
- * 값 역직렬화 (재귀)
- */
-function deserialize(value: unknown, ctx: DeserializeContext): unknown {
-  // null
-  if (value === null) return null;
-
-  // 문자열 → 타입 마커 체크
-  if (typeof value === "string") {
-    // undefined
-    if (value === TYPE_MARKERS.UNDEFINED) return undefined;
-
-    // 이스케이프된 문자열 (\x00\x00 → \x00)
-    if (value.startsWith("\x00\x00")) {
-      return value.slice(2);
-    }
-
-    // Date
-    if (value.startsWith(TYPE_MARKERS.DATE)) {
-      return new Date(value.slice(2));
-    }
-
-    // URL
-    if (value.startsWith(TYPE_MARKERS.URL)) {
-      return new URL(value.slice(2));
-    }
-
-    // RegExp
-    if (value.startsWith(TYPE_MARKERS.REGEXP)) {
-      const str = value.slice(2);
-      const match = str.match(/^\/(.*)\/([gimsuy]*)$/);
-      if (match) {
-        return new RegExp(match[1], match[2]);
-      }
-      return str; // 파싱 실패 시 문자열 반환
-    }
-
-    // BigInt
-    if (value.startsWith(TYPE_MARKERS.BIGINT)) {
-      return BigInt(value.slice(2));
-    }
-
-    // Symbol
-    if (value.startsWith(TYPE_MARKERS.SYMBOL)) {
-      return Symbol(value.slice(2));
-    }
-
-    // 순환 참조
-    if (value.startsWith(TYPE_MARKERS.REF)) {
-      const idx = parseInt(value.slice(2), 10);
-      return ctx.refs[idx];
-    }
-
-    return value;
-  }
-
-  // 원시형
-  if (typeof value === "boolean" || typeof value === "number") {
-    return value;
-  }
-
-  // 배열 → 특수 타입 체크
-  if (Array.isArray(value)) {
-    const marker = value[0];
-
-    // Error
-    if (marker === TYPE_MARKERS.ERROR) {
-      const [, name, message, stack] = value as [string, string, string, string];
-      const error = new Error(message);
-      error.name = name;
-      if (stack) error.stack = stack;
-      ctx.refs.push(error);
-      return error;
-    }
-
-    // Map
-    if (marker === TYPE_MARKERS.MAP) {
-      const map = new Map();
-      ctx.refs.push(map);
-      for (let i = 1; i < value.length; i++) {
-        const [k, v] = value[i] as [unknown, unknown];
-        map.set(deserialize(k, ctx), deserialize(v, ctx));
-      }
-      return map;
-    }
-
-    // Set
-    if (marker === TYPE_MARKERS.SET) {
-      const set = new Set();
-      ctx.refs.push(set);
-      for (let i = 1; i < value.length; i++) {
-        set.add(deserialize(value[i], ctx));
-      }
-      return set;
-    }
-
-    // 일반 배열
-    const arr: unknown[] = [];
-    ctx.refs.push(arr);
-    for (const item of value) {
-      arr.push(deserialize(item, ctx));
-    }
-    return arr;
-  }
-
-  // 일반 객체
-  if (typeof value === "object") {
-    const obj: Record<string, unknown> = {};
-    ctx.refs.push(obj);
-    for (const [k, v] of Object.entries(value)) {
-      obj[k] = deserialize(v, ctx);
-    }
-    return obj;
-  }
-
-  return value;
-}
-
-// ============================================
-// 유틸리티
-// ============================================
-
-/**
- * 직렬화 가능 여부 체크
- */
-export function isSerializable(value: unknown): boolean {
-  if (value === null || value === undefined) return true;
-
-  const type = typeof value;
-  if (type === "boolean" || type === "number" || type === "string" || type === "bigint") {
-    return true;
-  }
-
-  if (type === "function" || type === "symbol") {
-    return false;
-  }
-
-  if (value instanceof Date || value instanceof URL || value instanceof RegExp) {
-    return true;
-  }
-
-  if (value instanceof Map || value instanceof Set) {
-    return true;
-  }
-
-  if (Array.isArray(value)) {
-    return value.every(isSerializable);
-  }
-
-  if (type === "object") {
-    return Object.values(value as object).every(isSerializable);
-  }
-
-  return false;
-}
-
-/**
- * SSR에서 클라이언트로 props 전달용 스크립트 생성
- */
-export function generatePropsScript(
-  islandId: string,
-  props: Record<string, unknown>
-): string {
-  const json = serializeProps(props);
-  const escaped = json
-    .replace(/</g, "\\u003c")
-    .replace(/>/g, "\\u003e")
-    .replace(/&/g, "\\u0026");
-
-  return `<script type="application/json" data-mandu-props="${islandId}">${escaped}</script>`;
-}
-
-/**
- * 클라이언트에서 props 스크립트 파싱
- */
-export function parsePropsScript(islandId: string): Record<string, unknown> | null {
-  if (typeof document === "undefined") return null;
-
-  const script = document.querySelector(
-    `script[data-mandu-props="${islandId}"]`
-  ) as HTMLScriptElement | null;
-
-  if (!script?.textContent) return null;
-
-  try {
-    return deserializeProps(script.textContent);
-  } catch (err) {
-    console.error(`[Mandu] Failed to parse props for island ${islandId}:`, err);
-    return null;
-  }
-}
+/**
+ * Mandu props serialization public API.
+ *
+ * Core serialization/deserialization lives in `props-serialization.ts` so the
+ * browser runtime and server render path share exactly one wire format.
+ */
+
+import { deserializeProps, serializeProps } from "./props-serialization";
+
+export {
+  deserializeProps,
+  isSerializable,
+  serializeProps,
+} from "./props-serialization";
+
+/**
+ * SSR에서 클라이언트로 props 전달용 스크립트 생성
+ */
+export function generatePropsScript(
+  islandId: string,
+  props: Record<string, unknown>
+): string {
+  const json = serializeProps(props);
+  const escaped = json
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026");
+
+  return `<script type="application/json" data-mandu-props="${islandId}">${escaped}</script>`;
+}
+
+/**
+ * 클라이언트에서 props 스크립트 파싱
+ */
+export function parsePropsScript(islandId: string): Record<string, unknown> | null {
+  if (typeof document === "undefined") return null;
+
+  const script = document.querySelector(
+    `script[data-mandu-props="${islandId}"]`
+  ) as HTMLScriptElement | null;
+
+  if (!script?.textContent) return null;
+
+  try {
+    return deserializeProps(script.textContent);
+  } catch (err) {
+    console.error(`[Mandu] Failed to parse props for island ${islandId}:`, err);
+    return null;
+  }
+}

package/src/diagnose/__tests__/checks.test.ts

@@ -16,9 +16,10 @@ import {
   checkPrerenderPollution,
   checkCloneElementWarnings,
   checkDevArtifactsInProd,
-  checkPackageExportGaps,
-  checkNestedInternalCore,
-} from "../checks";
+  checkPackageExportGaps,
+  checkNestedInternalCore,
+  checkClientBoundaryManifests,
+} from "../checks";
 import { runExtendedDiagnose, buildReport } from "../run";
 
 async function mkTmpRoot(): Promise<string> {
@@ -324,7 +325,7 @@ describe("checkPackageExportGaps", () => {
 // nested_internal_core (#261)
 // ──────────────────────────────────────────────────────────────────
 
-describe("checkNestedInternalCore", () => {
+describe("checkNestedInternalCore", () => {
   let rootDir: string;
   beforeEach(async () => { rootDir = await mkTmpRoot(); });
   afterEach(async () => { await fs.rm(rootDir, { recursive: true, force: true }); });
@@ -387,21 +388,134 @@ describe("checkNestedInternalCore", () => {
     expect(result.ok).toBe(false);
     expect(result.details?.mismatchCount).toBe(2);
   });
-});
-
-// ──────────────────────────────────────────────────────────────────
-// aggregator
-// ──────────────────────────────────────────────────────────────────
+});
+
+// ──────────────────────────────────────────────────────────────────
+// client_boundary_manifests
+// ──────────────────────────────────────────────────────────────────
+
+describe("checkClientBoundaryManifests", () => {
+  let rootDir: string;
+  beforeEach(async () => { rootDir = await mkTmpRoot(); });
+  afterEach(async () => { await fs.rm(rootDir, { recursive: true, force: true }); });
+
+  it("skips gracefully when routes manifest is missing", async () => {
+    const result = await checkClientBoundaryManifests(rootDir);
+    expect(result.ok).toBe(true);
+    expect(result.details?.skipped).toBe(true);
+  });
+
+  it("passes when the routes manifest has no compiler-owned boundaries", async () => {
+    await writeFile(rootDir, ".mandu/routes.manifest.json", JSON.stringify({
+      routes: [{ id: "home", kind: "page" }],
+    }));
+    const result = await checkClientBoundaryManifests(rootDir);
+    expect(result.ok).toBe(true);
+    expect(result.details?.boundaryCount).toBe(0);
+  });
+
+  it("flags duplicate client boundary ids in the routes manifest", async () => {
+    await writeFile(rootDir, ".mandu/routes.manifest.json", JSON.stringify({
+      routes: [
+        {
+          id: "a",
+          boundaries: [{ id: "dup--0", routeId: "a", module: "src/client/A.client.tsx", exportName: "A" }],
+        },
+        {
+          id: "b",
+          boundaries: [{ id: "dup--0", routeId: "b", module: "src/client/B.client.tsx", exportName: "B" }],
+        },
+      ],
+    }));
+    const result = await checkClientBoundaryManifests(rootDir);
+    expect(result.ok).toBe(false);
+    expect(result.severity).toBe("error");
+    expect(result.message).toMatch(/duplicate/);
+  });
+
+  it("flags missing boundary bundle manifest entries", async () => {
+    await writeFile(rootDir, ".mandu/routes.manifest.json", JSON.stringify({
+      routes: [
+        {
+          id: "home",
+          boundaries: [{ id: "home--0", routeId: "home", module: "src/client/Home.client.tsx", exportName: "Home" }],
+        },
+      ],
+    }));
+    await writeFile(rootDir, ".mandu/manifest.json", JSON.stringify({
+      version: 1,
+      buildTime: "x",
+      env: "production",
+      bundles: {},
+      boundaries: {},
+      shared: { runtime: "/.mandu/client/_runtime.js", vendor: "/.mandu/client/_react.js" },
+    }));
+    const result = await checkClientBoundaryManifests(rootDir);
+    expect(result.ok).toBe(false);
+    expect(result.severity).toBe("error");
+    expect(result.message).toMatch(/incomplete/);
+    expect(result.details?.missingEntries).toEqual(["home--0"]);
+  });
+
+  it("treats a missing bundle manifest as an error when routes declare compiler-owned boundaries", async () => {
+    await writeFile(rootDir, ".mandu/routes.manifest.json", JSON.stringify({
+      routes: [
+        {
+          id: "home",
+          boundaries: [{ id: "home--0", routeId: "home", module: "src/client/Home.client.tsx", exportName: "Home" }],
+        },
+      ],
+    }));
+    const result = await checkClientBoundaryManifests(rootDir);
+    expect(result.ok).toBe(false);
+    expect(result.severity).toBe("error");
+    expect(result.message).toMatch(/bundle manifest is missing/);
+  });
+
+  it("passes when route and bundle boundary manifests line up", async () => {
+    await writeFile(rootDir, ".mandu/routes.manifest.json", JSON.stringify({
+      routes: [
+        {
+          id: "home",
+          boundaries: [{ id: "home--0", routeId: "home", module: "src/client/Home.client.tsx", exportName: "Home" }],
+        },
+      ],
+    }));
+    await writeFile(rootDir, ".mandu/client/home--0.boundary.js", "export default function Home() {}\n");
+    await writeFile(rootDir, ".mandu/manifest.json", JSON.stringify({
+      version: 1,
+      buildTime: "x",
+      env: "production",
+      bundles: {},
+      boundaries: {
+        "home--0": {
+          route: "home",
+          js: "/.mandu/client/home--0.boundary.js",
+          module: "src/client/Home.client.tsx",
+          exportName: "Home",
+        },
+      },
+      shared: { runtime: "/.mandu/client/_runtime.js", vendor: "/.mandu/client/_react.js" },
+    }));
+    const result = await checkClientBoundaryManifests(rootDir);
+    expect(result.ok).toBe(true);
+    expect(result.details?.boundaryCount).toBe(1);
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────
+// aggregator
+// ──────────────────────────────────────────────────────────────────
 
 describe("runExtendedDiagnose", () => {
   let rootDir: string;
   beforeEach(async () => { rootDir = await mkTmpRoot(); });
   afterEach(async () => { await fs.rm(rootDir, { recursive: true, force: true }); });
 
-  it("runs all 7 extended checks and returns a structured report", async () => {
-    const report = await runExtendedDiagnose(rootDir);
-    // #261 added `nested_internal_core` — total is now 7.
-    expect(report.summary.total).toBe(7);
+  it("runs all 8 extended checks and returns a structured report", async () => {
+    const report = await runExtendedDiagnose(rootDir);
+    // F42/F45 added `client_boundary_manifests` — total is now 8.
+    expect(report.summary.total).toBe(8);
     // manifest is missing → at least one error
     expect(report.healthy).toBe(false);
     expect(report.errorCount).toBeGreaterThanOrEqual(1);
@@ -410,10 +524,11 @@ describe("runExtendedDiagnose", () => {
     expect(rules).toContain("prerender_pollution");
     expect(rules).toContain("cloneelement_warnings");
     expect(rules).toContain("dev_artifacts_in_prod");
-    expect(rules).toContain("package_export_gaps");
-    expect(rules).toContain("nested_internal_core");
-    expect(rules).toContain("a11y_hints");
-  });
+    expect(rules).toContain("package_export_gaps");
+    expect(rules).toContain("nested_internal_core");
+    expect(rules).toContain("client_boundary_manifests");
+    expect(rules).toContain("a11y_hints");
+  });
 
   it("returns healthy=true when all checks pass (production manifest, no gaps)", async () => {
     await writeFile(rootDir, ".mandu/manifest.json", JSON.stringify({