sonamu 0.10.12 → 0.10.13

package/src/api/__tests__/sonamu.websocket.test.ts

@@ -3,17 +3,29 @@ import { describe, expect, it, vi } from "vitest";
 import { type WebSocket } from "ws";
 import { z } from "zod";
 
-import { type AnyWebSocketConnection, WebSocketRuntime } from "../../stream/ws";
+import {
+  type AnyWebSocketConnection,
+  type WebSocketConnection,
+  WebSocketRuntime,
+} from "../../stream/ws";
 import { type WebSocketTelemetryConnectionContext } from "../../stream/ws-telemetry";
-import { type SonamuFastifyConfig } from "../config";
+import { type SonamuFastifyConfig } from "../../types/types";
 import { type WebSocketContext } from "../context";
 import { type ExtendedApi } from "../decorators";
 import { Sonamu } from "../sonamu";
 
+interface TestWebSocketMessage {
+  roomId?: string;
+}
+
+interface TestWebSocketEvents {
+  joinRoom: TestWebSocketMessage;
+}
+
 describe("Sonamu websocket context scoping", () => {
   it("웹소켓 컨텍스트를 생성한 뒤 해당 컨텍스트 안에서 guard를 실행한다", async () => {
     const executionOrder: string[] = [];
-    const rawWs = {
+    const rawWs: AnyWebSocketConnection = {
       id: "ws-guard",
       namespace: "chat",
       transport: "ws" as const,
@@ -30,12 +42,12 @@ describe("Sonamu websocket context scoping", () => {
       leave() {},
       setUserId() {},
       clearUserId() {},
-    } satisfies AnyWebSocketConnection;
+    };
     const runtime = new WebSocketRuntime({ nodeId: "websocket-guard-test" });
-    const originalRuntime = Reflect.get(Sonamu, "_websocketRuntime");
-    const originalSyncer = Reflect.get(Sonamu, "_syncer");
+    const originalState = Sonamu.captureTestingSnapshot();
     let contextCreated: WebSocketContext | null = null;
     let guardContext: WebSocketContext | null = null;
+    let guardTransport: WebSocketContext["transport"] | null = null;
 
     vi.spyOn(runtime, "registerConnection").mockReturnValue(rawWs);
     vi.spyOn(runtime, "activateConnection").mockImplementation(() => {
@@ -43,7 +55,7 @@ describe("Sonamu websocket context scoping", () => {
     });
     vi.spyOn(Sonamu, "createWebSocketContext").mockImplementation(async (_config, request, ws) => {
       executionOrder.push("context");
-      contextCreated = {
+      const context: WebSocketContext = {
         transport: "ws",
         request,
         headers: request.headers,
@@ -53,16 +65,21 @@ describe("Sonamu websocket context scoping", () => {
         user: null,
         session: null,
       };
-      return contextCreated;
+      contextCreated = context;
+      return context;
     });
     vi.spyOn(Sonamu, "invokeModelMethod").mockImplementation(async () => {
       executionOrder.push("handler");
     });
 
-    const config = {
+    const config = /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ {
       guardHandler() {
         executionOrder.push("guard");
         guardContext = Sonamu.getContext<WebSocketContext>();
+        guardTransport = guardContext.transport;
+      },
+      contextProvider(defaultContext) {
+        return defaultContext;
       },
     } as SonamuFastifyConfig;
     const api: ExtendedApi = {
@@ -78,28 +95,27 @@ describe("Sonamu websocket context scoping", () => {
       parameters: [],
       returnType: "void",
     };
-    const request = {
+    const request = /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ {
       headers: {},
       query: {},
     } as FastifyRequest;
-    const createWebSocketHandler: (
-      api: ExtendedApi,
-      config: SonamuFastifyConfig,
-    ) => (connection: { socket: WebSocket }, request: FastifyRequest) => Promise<void> =
-      Reflect.get(Sonamu, "createWebSocketHandler");
-
     try {
       Sonamu.websocketRuntime = runtime;
-      Reflect.set(Sonamu, "_syncer", { types: {} });
+      Reflect.set(Sonamu, "syncerValue", { types: {} });
 
-      await createWebSocketHandler.call(Sonamu, api, config)({ socket: {} as WebSocket }, request);
+      await Sonamu.createWebSocketHandlerForTesting(api, config)(
+        {
+          socket:
+            /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ {} as WebSocket,
+        },
+        request,
+      );
 
       expect(executionOrder).toEqual(["context", "guard", "activate", "handler"]);
       expect(guardContext).toBe(contextCreated);
-      expect(guardContext?.transport).toBe("ws");
+      expect(guardTransport).toBe("ws");
     } finally {
-      Reflect.set(Sonamu, "_websocketRuntime", originalRuntime);
-      Reflect.set(Sonamu, "_syncer", originalSyncer);
+      Sonamu.restoreTestingSnapshot(originalState);
       vi.restoreAllMocks();
     }
   });
@@ -108,12 +124,12 @@ describe("Sonamu websocket context scoping", () => {
     const messageHandlers = new Map<
       string,
       (
-        data: unknown,
+        data: TestWebSocketMessage,
         telemetryContext?: WebSocketTelemetryConnectionContext,
       ) => void | Promise<void>
     >();
 
-    const rawWs = {
+    const rawWs: WebSocketConnection<TestWebSocketEvents, TestWebSocketEvents> = {
       id: "ws-1",
       namespace: "chat",
       transport: "ws" as const,
@@ -132,18 +148,15 @@ describe("Sonamu websocket context scoping", () => {
       leave() {},
       setUserId() {},
       clearUserId() {},
-    } satisfies AnyWebSocketConnection;
+    };
 
-    let context: WebSocketContext | null = null;
-    const createScopedWebSocketConnection: (
-      ws: AnyWebSocketConnection,
-      getContext: () => WebSocketContext | null,
-    ) => AnyWebSocketConnection = Reflect.get(Sonamu, "createScopedWebSocketConnection");
-    const scopedWs = createScopedWebSocketConnection.call(Sonamu, rawWs, () => context);
+    let context: WebSocketContext<TestWebSocketEvents, TestWebSocketEvents> | null = null;
+    const scopedWs = Sonamu.createScopedWebSocketConnectionForTesting(rawWs, () => context);
 
     context = {
       transport: "ws",
-      request: {} as WebSocketContext["request"],
+      request:
+        /* SAFETY: 테스트는 request 속성을 읽지 않고 websocket 컨텍스트 복원만 검증합니다. */ {} as WebSocketContext["request"],
       headers: {},
       ws: scopedWs,
       naiteStore: new Map(),
@@ -168,12 +181,12 @@ describe("Sonamu websocket context scoping", () => {
     const messageHandlers = new Map<
       string,
       (
-        data: unknown,
+        data: TestWebSocketMessage,
         telemetryContext?: WebSocketTelemetryConnectionContext,
       ) => void | Promise<void>
     >();
 
-    const rawWs = {
+    const rawWs: WebSocketConnection<TestWebSocketEvents, TestWebSocketEvents> = {
       id: "ws-1",
       namespace: "chat",
       transport: "ws" as const,
@@ -192,18 +205,15 @@ describe("Sonamu websocket context scoping", () => {
       leave() {},
       setUserId() {},
       clearUserId() {},
-    } satisfies AnyWebSocketConnection;
+    };
 
-    let context: WebSocketContext | null = null;
-    const createScopedWebSocketConnection: (
-      ws: AnyWebSocketConnection,
-      getContext: () => WebSocketContext | null,
-    ) => AnyWebSocketConnection = Reflect.get(Sonamu, "createScopedWebSocketConnection");
-    const scopedWs = createScopedWebSocketConnection.call(Sonamu, rawWs, () => context);
+    let context: WebSocketContext<TestWebSocketEvents, TestWebSocketEvents> | null = null;
+    const scopedWs = Sonamu.createScopedWebSocketConnectionForTesting(rawWs, () => context);
 
     context = {
       transport: "ws",
-      request: {} as WebSocketContext["request"],
+      request:
+        /* SAFETY: 테스트는 request 속성을 읽지 않고 websocket 컨텍스트 복원만 검증합니다. */ {} as WebSocketContext["request"],
       headers: {},
       ws: scopedWs,
       naiteStore: new Map(),

package/src/api/__tests__/zod-compiler-policy.test.ts

@@ -0,0 +1,95 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { DB } from "../../database/db";
+import { normalizeZodCompilerPolicy } from "../config";
+import { Sonamu } from "../sonamu";
+
+describe("zod-compiler 정책 정규화", () => {
+  it.each([undefined, false] as const)(
+    "미설정 또는 false를 opt-out 정책으로 정규화한다",
+    (policy) => {
+      expect(normalizeZodCompilerPolicy(policy, ["web", "app"])).toEqual({
+        api: false,
+        targets: {},
+      });
+    },
+  );
+
+  it("API JIT 정책을 target registry 없이 정규화한다", () => {
+    expect(normalizeZodCompilerPolicy({ api: "jit" }, ["web"])).toEqual({
+      api: "jit",
+      targets: {},
+    });
+  });
+
+  it("API AOT 정책을 target registry 없이 정규화한다", () => {
+    expect(normalizeZodCompilerPolicy({ api: "aot" }, ["web"])).toEqual({
+      api: "aot",
+      targets: {},
+    });
+  });
+
+  it("지원하지 않는 target opt-in을 targets 설정 경로에서 거부한다", () => {
+    expect(() =>
+      normalizeZodCompilerPolicy(
+        {
+          api: "aot",
+          targets: {
+            web: "aot",
+          },
+        },
+        ["web"],
+      ),
+    ).toThrowError(/validation\.zodCompiler\.targets/);
+  });
+});
+
+describe("zod-compiler 빌드 전용 정책 로딩", () => {
+  const tempRoots: string[] = [];
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    vi.resetModules();
+    await Promise.all(
+      tempRoots.splice(0).map((rootPath) => rm(rootPath, { recursive: true, force: true })),
+    );
+  });
+
+  it("Sonamu와 DB를 초기화하지 않고 source config의 compiler 정책만 읽는다", async () => {
+    const rootPath = await mkdtemp(path.join(os.tmpdir(), "sonamu-compiler-policy-test-"));
+    tempRoots.push(rootPath);
+    await mkdir(path.join(rootPath, "src"), { recursive: true });
+    await writeFile(path.join(rootPath, ".env"), "SONAMU_DB_HOST=localhost\n");
+    await writeFile(
+      path.join(rootPath, "src", "sonamu.config.ts"),
+      `
+export default {
+  sync: { targets: ["web"] },
+  validation: {
+    zodCompiler: {
+      api: "aot",
+    },
+  },
+};
+`,
+    );
+
+    const sonamuInit = vi.spyOn(Sonamu, "init");
+    const generateDBConfig = vi.spyOn(DB, "generateDBConfig");
+    const setDBConfig = vi.spyOn(DB, "setConfig");
+
+    const { loadBuildCompilerPolicy } = await import("../../bin/compiler-policy");
+
+    await expect(loadBuildCompilerPolicy(rootPath)).resolves.toEqual({
+      api: "aot",
+      targets: {},
+    });
+    expect(sonamuInit).not.toHaveBeenCalled();
+    expect(generateDBConfig).not.toHaveBeenCalled();
+    expect(setDBConfig).not.toHaveBeenCalled();
+  });
+});

package/src/api/caster.ts

@@ -3,6 +3,8 @@ import assert from "assert";
 import { z } from "zod";
 import { type $ZodType } from "zod/v4/core";
 
+import { isObjectValue, isStringValue } from "../utils/runtime-value";
+
 function isNumberType(zodType: $ZodType): zodType is z.ZodNumber {
   return zodType instanceof z.ZodNumber;
 }
@@ -28,7 +30,7 @@ function isZodNumberAnyway(zodType: $ZodType) {
 // ZodType을 이용해 raw를 Type Coercing
 // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- 캐스팅에는 any가 필요함.
 export function caster(zodType: $ZodType, raw: any): any {
-  if (isZodNumberAnyway(zodType) && typeof raw === "string") {
+  if (isZodNumberAnyway(zodType) && isStringValue(raw)) {
     // number
     return Number(raw);
   } else if (
@@ -51,14 +53,10 @@ export function caster(zodType: $ZodType, raw: any): any {
     // array
     // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- 캐스팅에는 any가 필요함.
     return raw.map((elem: any) => caster(zodType.element, elem));
-  } else if (zodType instanceof z.ZodObject && typeof raw === "object" && raw !== null) {
+  } else if (zodType instanceof z.ZodObject && isObjectValue(raw) && raw !== null) {
     // object
-    return Object.keys(raw).reduce(
-      (r, rawKey) => {
-        r[rawKey] = caster(zodType.shape[rawKey], raw[rawKey]);
-        return r;
-      },
-      {} as Record<string, unknown>,
+    return Object.fromEntries(
+      Object.keys(raw).map((rawKey) => [rawKey, caster(zodType["shape"][rawKey], raw[rawKey])]),
     );
   } else if (zodType instanceof z.ZodOptional) {
     // optional

package/src/api/code-converters.ts

@@ -28,6 +28,76 @@ import { type ExtendedApi } from "./decorators";
 type AnyZodObject = z.ZodObject;
 type AnyZodLiteral = z.ZodLiteral;
 
+const ApiParamTypeSchema: z.ZodType<ApiParamType> = z.lazy(() =>
+  z.union([
+    z.enum([
+      "string",
+      "number",
+      "boolean",
+      "null",
+      "undefined",
+      "void",
+      "any",
+      "unknown",
+      "true",
+      "false",
+    ]),
+    z.object({ t: z.literal("string-literal"), value: z.string() }),
+    z.object({ t: z.literal("numeric-literal"), value: z.number() }),
+    z.object({
+      t: z.literal("object"),
+      props: z.array(
+        z.object({
+          name: z.string(),
+          type: ApiParamTypeSchema,
+          optional: z.boolean(),
+          defaultDef: z.string().optional(),
+        }),
+      ),
+    }),
+    z.object({ t: z.literal("union"), types: z.array(ApiParamTypeSchema) }),
+    z.object({ t: z.literal("intersection"), types: z.array(ApiParamTypeSchema) }),
+    z.object({ t: z.literal("array"), elementsType: ApiParamTypeSchema }),
+    z.object({
+      t: z.literal("ref"),
+      id: z.string(),
+      args: z.array(ApiParamTypeSchema).optional(),
+    }),
+    z.object({
+      t: z.literal("indexed-access"),
+      object: ApiParamTypeSchema,
+      index: ApiParamTypeSchema,
+    }),
+    z.object({
+      t: z.literal("type-param"),
+      id: z.string(),
+      constraint: ApiParamTypeSchema.optional(),
+    }),
+    z.object({ t: z.literal("tuple-type"), elements: z.array(ApiParamTypeSchema) }),
+    z.object({
+      t: z.literal("function"),
+      parameters: z.array(
+        z.object({
+          name: z.string(),
+          type: ApiParamTypeSchema,
+          optional: z.boolean(),
+          defaultDef: z.string().optional(),
+        }),
+      ),
+      returnType: ApiParamTypeSchema,
+    }),
+  ]),
+);
+
+/** 신뢰할 수 없는 값을 ApiParamType 경계에서 검증합니다. */
+export function parseApiParamType<Input>(input: Input): ApiParamType {
+  const result = ApiParamTypeSchema.safeParse(input);
+  if (!result.success) {
+    throw new Error(`resolve 불가 ApiParamType: ${z.prettifyError(result.error)}`);
+  }
+  return result.data;
+}
+
 /**
  * Promise 타입을 한 번 언래핑하여 내부 타입을 반환합니다.
  * Promise가 아닌 경우 원본 타입을 그대로 반환합니다.
@@ -49,12 +119,13 @@ export function unwrapPromiseOnce(paramType: ApiParamType) {
  * string, number, array, union 등 모든 ApiParamType을 처리하며,
  * 순환참조가 발생하는 경우 z.unknown()으로 fallback합니다.
  */
-export function getZodTypeFromApiParamType(
-  paramType: ApiParamType,
+export function getZodTypeFromApiParamType<Input>(
+  input: Input,
   references: {
     [id: string]: z.ZodType;
   },
 ): z.ZodType {
+  const paramType = parseApiParamType(input);
   switch (paramType) {
     case "string":
       return z.string();
@@ -63,28 +134,38 @@ export function getZodTypeFromApiParamType(
     case "boolean":
       return z.boolean();
     default: {
-      const advType = paramType as { t: string; value?: string | number };
+      const advType =
+        /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ paramType as {
+          t: string;
+          value?: string | number;
+        };
       switch (advType.t) {
         case "string-literal":
         case "numeric-literal":
           return z.literal(advType.value);
         case "object": {
-          const objType = paramType as { t: string; props: ApiParam[] };
+          const objType =
+            /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ paramType as {
+              t: string;
+              props: ApiParam[];
+            };
           return getZodObjectFromApiParams(objType.props);
         }
         case "array": {
-          const arrType = paramType as {
-            t: string;
-            elementsType: ApiParamType;
-          };
+          const arrType =
+            /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ paramType as {
+              t: string;
+              elementsType: ApiParamType;
+            };
           return z.array(getZodTypeFromApiParamType(arrType.elementsType, references));
         }
         case "ref": {
-          const refType = paramType as {
-            t: string;
-            id: string;
-            args?: ApiParamType[];
-          };
+          const refType =
+            /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ paramType as {
+              t: string;
+              id: string;
+              args?: ApiParamType[];
+            };
           // Date 타입 처리
           if (refType.id === "Date") {
             return z.date();
@@ -94,10 +175,10 @@ export function getZodTypeFromApiParamType(
             if (refType.args?.length !== 2) {
               throw new Error(`잘못된 ${refType.id}`);
             }
-            const [obj, literalOrUnion] = refType.args.map(
-              (arg) => getZodTypeFromApiParamType(arg, references),
-              // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- 생성되는 ZodUnion의 타입을 추적하기 어려움
-            ) as [AnyZodObject, z.ZodUnion<any> | AnyZodLiteral];
+            const [obj, literalOrUnion] =
+              /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ refType.args.map(
+                (arg) => getZodTypeFromApiParamType(arg, references),
+              ) as [AnyZodObject, z.ZodUnion<any> | AnyZodLiteral];
 
             let keys: string[] = [];
             if (literalOrUnion instanceof z.ZodUnion) {
@@ -105,18 +186,25 @@ export function getZodTypeFromApiParamType(
                 (option: { def: { values: string[] } }) => option.def.values[0],
               );
             } else {
-              keys = (literalOrUnion as z.ZodLiteral<string>).def.values;
+              keys =
+                /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ (
+                  literalOrUnion as z.ZodLiteral<string>
+                ).def.values;
             }
             const keyRecord = Object.fromEntries(keys.map((key) => [key, true as const]));
             if (refType.id === "Pick") {
               if (obj.pick) {
                 // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- Zod 4.3.6 pick 타입 호환성
-                return obj.pick(keyRecord as any);
+                return obj.pick(
+                  /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ keyRecord as any,
+                );
               }
             } else {
               if (obj.omit) {
                 // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- Zod 4.3.6 omit 타입 호환성
-                return obj.omit(keyRecord as any);
+                return obj.omit(
+                  /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ keyRecord as any,
+                );
               }
             }
           }
@@ -126,7 +214,9 @@ export function getZodTypeFromApiParamType(
             }
             const obj = getZodTypeFromApiParamType(refType.args[0], references);
             // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- Partial 인수 타입 캐스팅
-            return (obj as z.ZodObject<any>).partial();
+            return /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ (
+              obj as z.ZodObject<any>
+            ).partial();
           }
           const reference = references[refType.id];
           if (reference === undefined) {
@@ -136,10 +226,11 @@ export function getZodTypeFromApiParamType(
           return reference;
         }
         case "union": {
-          const unionType = paramType as {
-            t: string;
-            types: ApiParamType[];
-          };
+          const unionType =
+            /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ paramType as {
+              t: string;
+              types: ApiParamType[];
+            };
           // nullable 유니온
           if (unionType.types.length === 2 && unionType.types.some((type) => type === "null")) {
             if (unionType.types[0] === "null") {
@@ -154,10 +245,11 @@ export function getZodTypeFromApiParamType(
           );
         }
         case "intersection": {
-          const intersectionType = paramType as {
-            t: string;
-            types: ApiParamType[];
-          };
+          const intersectionType =
+            /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ paramType as {
+              t: string;
+              types: ApiParamType[];
+            };
           return intersectionType.types.reduce((result, type, index) => {
             const resolvedType = getZodTypeFromApiParamType(type, references);
             if (index === 0) {
@@ -165,13 +257,16 @@ export function getZodTypeFromApiParamType(
             } else {
               return z.intersection(result, resolvedType);
             }
-          }, z.unknown() as z.ZodType);
+          }, /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ z.unknown() as z.ZodType);
         }
         case "tuple-type": {
-          const tupleType = paramType as ApiParamType.TupleType;
+          const tupleType =
+            /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ paramType as ApiParamType.TupleType;
           return z.tuple(
             // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- 생성되는 ZodTuple의 타입을 추적하기 어려움
-            tupleType.elements.map((elem) => getZodTypeFromApiParamType(elem, references)) as any,
+            /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ tupleType.elements.map(
+              (elem) => getZodTypeFromApiParamType(elem, references),
+            ) as any,
           );
         }
       }
@@ -221,7 +316,9 @@ export function getZodObjectFromApi(
 
         // FIXME: references는 글로벌 오브젝트로, typeParam.id("T" 등)를 key로 이렇게 덮어씌워버리면 loadedTypes가 오염됨.
         // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- 레퍼런스 타입 캐스팅
-        (references[typeParam.id] as z.ZodType<any>) = zodType;
+        /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ (references[
+          typeParam.id
+        ] as z.ZodType<any>) = zodType;
       }
     }
   }
@@ -247,7 +344,8 @@ export function getZodObjectFromApi(
  * union, intersection, array, ref 등 모든 타입을 TS 문법으로 표현하며,
  * import가 필요한 타입 ID는 injectImportKeys에 수집합니다.
  */
-export function apiParamTypeToTsType(paramType: ApiParamType, injectImportKeys: string[]): string {
+export function apiParamTypeToTsType<Input>(input: Input, injectImportKeys: string[]): string {
+  const paramType = parseApiParamType(input);
   if (
     [
       "string",
@@ -260,9 +358,11 @@ export function apiParamTypeToTsType(paramType: ApiParamType, injectImportKeys:
       "void",
       "any",
       "unknown",
-    ].includes(paramType as string)
+    ].includes(
+      /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ paramType as string,
+    )
   ) {
-    return paramType as string;
+    return /* SAFETY: API 데코레이터와 Zod 검증기 등록 계약이 이 값의 타입을 보장한다. */ paramType as string;
   } else if (ApiParamType.isObject(paramType)) {
     return `{ ${apiParamToTsCode(paramType.props, injectImportKeys)} }`;
   } else if (ApiParamType.isStringLiteral(paramType)) {