akanjs 2.2.4-rc.4 → 2.2.4

package/client/client.router.test.ts

@@ -0,0 +1,290 @@
+import { afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
+
+type Side = "server" | "client";
+
+const envState = {
+  side: "client" as Side,
+  operationMode: "local",
+  basePaths: "admin,console",
+};
+const requestState = {
+  request: undefined as Request | undefined,
+  headers: new Map<string, string>(),
+};
+const messages: unknown[] = [];
+const timeoutCallbacks: Array<() => void> = [];
+
+beforeAll(() => {
+  mock.module("akanjs/base", () => ({
+    getEnv: () => ({
+      side: envState.side,
+      renderMode: "csr",
+      appName: "test-app",
+      environment: "debug",
+      operationMode: envState.operationMode,
+    }),
+  }));
+  mock.module("akanjs/common", () => ({
+    Logger: { log: () => undefined, verbose: () => undefined },
+    parseAkanI18nEnv: () => ({ locales: ["en", "ko"], defaultLocale: "en" }),
+    parseBasePaths: (value?: string) => (value ? value.split(",").filter(Boolean) : []),
+    pathGet: (path: string, obj: Record<string, unknown>, separator = ".", fallback?: unknown) =>
+      path.split(separator).reduce<unknown>((acc, key) => {
+        if (!acc || typeof acc !== "object") return fallback;
+        return (acc as Record<string, unknown>)[key] ?? fallback;
+      }, obj),
+    getBasePathFromPathname: (
+      pathname: string,
+      opts: { basePaths: Set<string>; i18n: { locales: string[] }; headerBasePath?: string },
+    ) => {
+      if (opts.headerBasePath) return opts.headerBasePath;
+      const [, lang, base] = pathname.split("/");
+      return opts.i18n.locales.includes(lang ?? "") && base && opts.basePaths.has(base) ? base : null;
+    },
+  }));
+  mock.module("akanjs/fetch", () => ({
+    FetchClient: {
+      build: () => ({ fetch: { setJwt: () => undefined }, sig: {} }),
+    },
+    defaultAccount: { appName: "test-app", environment: "debug" },
+    requestStorage: {
+      getStore: () => requestState.request,
+    },
+    getRequest: () => requestState.request,
+    headers: () => requestState.headers,
+  }));
+});
+
+const installClientWindow = (pathname = "/en/admin/current", search = "", hash = "") => {
+  Object.defineProperty(globalThis, "window", {
+    value: {
+      location: { pathname, search, hash },
+      parent: { postMessage: (message: unknown) => messages.push(message) },
+    },
+    configurable: true,
+  });
+  Object.defineProperty(globalThis, "document", {
+    value: { referrer: "https://example.test/en/admin/previous" },
+    configurable: true,
+  });
+  Object.defineProperty(globalThis, "location", {
+    value: { pathname, search, hash },
+    configurable: true,
+  });
+};
+
+afterEach(() => {
+  envState.side = "client";
+  envState.operationMode = "local";
+  envState.basePaths = "admin,console";
+  process.env.AKAN_PUBLIC_BASE_PATHS = envState.basePaths;
+  requestState.request = undefined;
+  requestState.headers = new Map();
+  messages.length = 0;
+  timeoutCallbacks.length = 0;
+  globalThis.__AKAN_ROUTER__ = undefined;
+  Object.defineProperty(globalThis, "window", { value: undefined, configurable: true });
+  Object.defineProperty(globalThis, "document", { value: undefined, configurable: true });
+  Object.defineProperty(globalThis, "location", { value: undefined, configurable: true });
+});
+
+describe("router", () => {
+  test("normalizes paths with language, prefix, query, hash, root, and absolute hrefs", async () => {
+    const { getPathInfo } = await import("./router");
+
+    expect(getPathInfo("/en/admin/users?tab=a#bio", "en", "admin")).toEqual({
+      path: "/users",
+      pathname: "/en/admin/users",
+      search: "tab=a",
+      hash: "bio",
+      href: "/en/admin/users?tab=a#bio",
+    });
+    expect(getPathInfo("/en/admin", "en", "admin").path).toBe("/");
+    expect(getPathInfo("/users", "ko", "").href).toBe("/ko/users");
+    expect(getPathInfo("https://external.test/path", "en", "admin").pathname).toBe("https://external.test/path");
+  });
+
+  test("client router init wraps push, replace, back, refresh, and path helpers", async () => {
+    envState.side = "client";
+    installClientWindow();
+    const originalSetTimeout = globalThis.setTimeout;
+    const mockSetTimeout = ((handler: TimerHandler) => {
+      timeoutCallbacks.push(() => {
+        if (typeof handler === "function") handler();
+      });
+      return timeoutCallbacks.length as unknown as ReturnType<typeof setTimeout>;
+    }) as unknown as typeof setTimeout;
+    globalThis.setTimeout = mockSetTimeout;
+    const calls: unknown[] = [];
+    const { router } = await import("./router");
+
+    router.init({
+      type: "csr",
+      lang: "en",
+      prefix: "admin",
+      router: {
+        push: (href, options) => calls.push(["push", href, options]),
+        replace: (href, options) => calls.push(["replace", href, options]),
+        back: (options) => calls.push(["back", options]),
+        refresh: () => calls.push(["refresh"]),
+      },
+    });
+
+    router.push("/users", { scrollToTop: true });
+    router.replace("/settings");
+    expect(calls).toEqual([["push", "/en/admin/users", { scrollToTop: true }]]);
+    timeoutCallbacks.splice(0).forEach((callback) => {
+      callback();
+    });
+    expect(calls).toEqual([
+      ["push", "/en/admin/users", { scrollToTop: true }],
+      ["replace", "/en/admin/settings", undefined],
+    ]);
+    router.back({ scrollToTop: false });
+    router.refresh();
+    expect(calls.at(-2)).toEqual(["back", { scrollToTop: false }]);
+    expect(calls.at(-1)).toEqual(["refresh"]);
+    expect(messages[0]).toMatchObject({ type: "pathChange", path: "/users", pathname: "/en/admin/users" });
+    expect(router.getPath("/en/admin/current")).toBe("/current");
+    expect(router.getFullPath()).toBe("/en/admin/current");
+    expect(router.getPrefixedPath("/next")).toBe("/en/admin/next");
+
+    router.setLang("ko");
+    timeoutCallbacks.splice(0).forEach((callback) => {
+      callback();
+    });
+    expect(calls.at(-1)).toEqual(["replace", "/ko/admin/current", undefined]);
+    globalThis.setTimeout = originalSetTimeout;
+  });
+
+  test("csr navigation preserves csr runtime search params", async () => {
+    envState.side = "client";
+    installClientWindow("/en/admin/current", "?csr=true&akanMobileTarget=default&akanMobileBasePath=admin");
+    const originalSetTimeout = globalThis.setTimeout;
+    const mockSetTimeout = ((handler: TimerHandler) => {
+      timeoutCallbacks.push(() => {
+        if (typeof handler === "function") handler();
+      });
+      return timeoutCallbacks.length as unknown as ReturnType<typeof setTimeout>;
+    }) as unknown as typeof setTimeout;
+    globalThis.setTimeout = mockSetTimeout;
+    const calls: unknown[] = [];
+    const { router } = await import("./router");
+
+    router.init({
+      type: "csr",
+      lang: "en",
+      prefix: "admin",
+      router: {
+        push: (href, options) => calls.push(["push", href, options]),
+        replace: (href, options) => calls.push(["replace", href, options]),
+        back: (options) => calls.push(["back", options]),
+        refresh: () => calls.push(["refresh"]),
+      },
+    });
+
+    router.push("/users?tab=a#bio");
+    router.replace("/settings?csr=false");
+    timeoutCallbacks.splice(0).forEach((callback) => {
+      callback();
+    });
+
+    expect(calls).toEqual([
+      ["push", "/en/admin/users?tab=a&csr=true&akanMobileTarget=default&akanMobileBasePath=admin#bio", undefined],
+      ["replace", "/en/admin/settings?csr=false&akanMobileTarget=default&akanMobileBasePath=admin", undefined],
+    ]);
+    globalThis.setTimeout = originalSetTimeout;
+  });
+
+  test("ssr client navigation hides base path outside local mode", async () => {
+    envState.side = "client";
+    envState.operationMode = "main";
+    installClientWindow("/en/current");
+    const calls: unknown[] = [];
+    const { router } = await import("./router");
+
+    router.init({
+      type: "ssr",
+      side: "client",
+      lang: "en",
+      prefix: "admin",
+      router: {
+        push: (href, options) => calls.push(["push", href, options]),
+        replace: (href, options) => calls.push(["replace", href, options]),
+        back: (options) => calls.push(["back", options]),
+        refresh: () => calls.push(["refresh"]),
+      },
+    });
+
+    router.push("/", { scrollToTop: true });
+    router.replace("/users?tab=a#bio");
+
+    expect(calls).toEqual([
+      ["push", "/en", { scrollToTop: true }],
+      ["replace", "/en/users?tab=a#bio", undefined],
+    ]);
+    expect(messages[0]).toMatchObject({ type: "pathChange", path: "/", pathname: "/en/admin" });
+  });
+
+  test("ssr setLang preserves production public paths while switching locale", async () => {
+    envState.side = "client";
+    envState.operationMode = "main";
+    installClientWindow("/ko/docs/intro/fundamentals", "?from=nav", "#section");
+    const calls: unknown[] = [];
+    const { router } = await import("./router");
+
+    router.init({
+      type: "ssr",
+      side: "client",
+      lang: "en",
+      prefix: "akanjs",
+      router: {
+        push: (href, options) => calls.push(["push", href, options]),
+        replace: (href, options) => calls.push(["replace", href, options]),
+        back: (options) => calls.push(["back", options]),
+        refresh: () => calls.push(["refresh"]),
+      },
+    });
+
+    router.setLang("ko");
+
+    expect(calls).toEqual([["replace", "/ko/docs/intro/fundamentals?from=nav#section", undefined]]);
+    expect(messages[0]).toMatchObject({
+      type: "pathChange",
+      path: "/docs/intro/fundamentals",
+      pathname: "/ko/akanjs/docs/intro/fundamentals",
+      hash: "section",
+    });
+  });
+
+  test("throws initialized guard before init and server redirect/notFound errors", async () => {
+    envState.side = "client";
+    installClientWindow();
+    const { AkanNotFoundError, AkanRedirectError, router } = await import("./router");
+
+    envState.side = "server";
+    process.env.AKAN_PUBLIC_BASE_PATHS = "admin,console";
+    requestState.request = new Request("https://example.test/en/admin/current");
+    requestState.headers = new Map([
+      ["x-locale", "en"],
+      ["x-base-path", "admin"],
+    ]);
+    expect(() => router.redirect("/users?tab=a")).toThrow(AkanRedirectError);
+    try {
+      router.redirect("/users?tab=a");
+    } catch (error) {
+      expect(error).toBeInstanceOf(AkanRedirectError);
+      expect((error as Error & { location: string; method: string }).location).toBe("/en/admin/users?tab=a");
+      expect((error as Error & { method: string }).method).toBe("replace");
+    }
+    envState.operationMode = "main";
+    expect(() => router.redirect("/users?tab=a")).toThrow(AkanRedirectError);
+    try {
+      router.redirect("/users?tab=a");
+    } catch (error) {
+      expect(error).toBeInstanceOf(AkanRedirectError);
+      expect((error as Error & { location: string; method: string }).location).toBe("/en/users?tab=a");
+    }
+    expect(() => router.notFound()).toThrow(AkanNotFoundError);
+  });
+});

package/client/cookie.ts

@@ -49,7 +49,7 @@ export const setCookie = (
   const path = options.path ? `; path=${options.path}` : "";
   const sameSite = options.sameSite ? `; SameSite=${options.sameSite}` : "";
   const secure = options.secure ? "; Secure" : "";
-  
+  // biome-ignore lint/suspicious/noDocumentCookie: Akan auth helpers intentionally manage browser cookies.
   document.cookie = `${encoded}${path}${sameSite}${secure}`;
   if (env.renderMode !== "csr") return;
   void loadCapacitorCore()
@@ -59,6 +59,7 @@ export const setCookie = (
 
 export const getCookie = (key: string): string | undefined => {
   if (getEnv().side === "server") return cookies().get(key)?.value;
+  //capacitor 문서에서 document.cookie로 가져오라고 되어었음.
   else
     return document.cookie
       .split(";")
@@ -69,8 +70,9 @@ export const getCookie = (key: string): string | undefined => {
 export const removeCookie = (key: string, options: { path: string } = { path: "/" }) => {
   if (getEnv().side === "server") return cookies().delete(key);
   else {
-    
+    // biome-ignore lint/suspicious/noDocumentCookie: Akan auth helpers intentionally manage browser cookies.
     document.cookie = `${key}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;`;
+    // void CapacitorCookies.deleteCookie({ key });
   }
 };
 export const headers = (): Map<string, string> => {

package/client/createFont.ts

@@ -1,5 +1,5 @@
-
-
+// webpack config에서 alias로 사용하는 파일, null처리로 CSR폰트를 할당할 수 있음.
+// 각 사용하는 폰트마다 여기에 추가해줘야함.
 export const createFont = (_data: unknown) => null;
 export default createFont;
 export const Nanum_Gothic_Coding = createFont;

package/client/csrTypes.ts

@@ -133,10 +133,16 @@ export interface Route {
   renderLayout?: RouteRender;
   pageIncludesOwnLayout?: boolean;
   isSpecialRoute?: boolean;
-
+  // Page?:
+  //   | (({ params, searchParams }: PageProps) => ReactNode)
+  //   | (({ params, searchParams }: PageProps) => Promise<ReactNode>);
+  // Layout?:
+  //   | (({ children, params, searchParams }: LayoutProps) => ReactNode)
+  //   | (({ children, params, searchParams }: LayoutProps) => Promise<ReactNode>);
   loader?: () => any;
   pageState?: PageState;
-
+  // action?: any;
+  // ErrorBoundary?: any;
   children: Map<string, Route>;
 }
 

package/client/makePageProto.tsx

@@ -26,13 +26,17 @@ const getPageInfo = (): { locale: string; path: string } => {
   if (getEnv().side !== "server") {
     const [, firstSegment = "", ...rest] = window.location.pathname.split("/");
     const hasLocalePrefix = localeSet.has(firstSegment);
-
+    // Prefer the server-resolved active locale (seeded via ClientWrapper) so client lookups match the
+    // SSR render even when the URL's leading segment is not the locale (base-path / cloud routing).
+    // Fall back to the URL segment for CSR or any pre-seed render.
     const activeLocale = Translator.getActiveLocale();
     const locale = activeLocale ?? (hasLocalePrefix ? firstSegment : defaultLocale);
     return { locale, path: hasLocalePrefix ? `/${rest.join("/")}` : window.location.pathname };
   }
   const h = headers();
-
+  // Honor explicit proxy/middleware headers when present; otherwise derive
+  // locale+path from the request URL itself so unadorned dev requests (e.g.
+  // `curl /en/hello`) still work.
   const localeHeader = h.get("x-locale");
   const pathHeader = h.get("x-path");
   if (localeHeader && pathHeader) return { locale: localeHeader, path: pathHeader };
@@ -158,11 +162,13 @@ export const makePageProto = <
       l.rich = (key: DictKey, param?: { [key: string]: string | number }) =>
         (
           <span
-            
+            // biome-ignore lint/security/noDangerouslySetInnerHtml: <a>an explanation</a>
             dangerouslySetInnerHTML={{
               __html: translator.translate(lang, key, {
                 ...param,
-
+                // strong: (chunks: string) => `<b>${chunks}</b>`,
+                // "bg-primary": (chunks: string) => `<span className="bg-primary text-base-100">${chunks}</span>`,
+                // primary: (chunks: string) => `<span className="bg-base-100 text-primary">${chunks}</span>`,
                 br: `<br />`,
               }),
             }}

package/client/router.ts

@@ -110,10 +110,14 @@ class Router {
     push: (href: string) => {
       const { href: fullHref } = this.#getPathInfo(href);
       Logger.log(`push to:${fullHref}`);
+      // ! need to revive
+      // if (getEnv().side === "server") void redirect(fullHref);
     },
     replace: (href: string) => {
       const { pathname } = this.#getPathInfo(href);
       Logger.log(`replace to:${pathname}`);
+      // ! need to revive
+      // if (getEnv().side === "server") void redirect(fullHref);
     },
     back: () => {
       throw new Error("back is only available in client");
@@ -123,7 +127,7 @@ class Router {
     },
   };
   init(options: SsrClientRouterOption | SsrServerRouterOption | CSRClientRouterOption) {
-    
+    // if (this.isInitialized) throw new Error("Router is already initialized");
     this.#prefix = options.prefix ?? "";
     this.#lang = options.lang ?? parseAkanI18nEnv().defaultLocale;
     if (options.type === "csr") this.#initCsrClientRouter(options);
@@ -133,6 +137,7 @@ class Router {
     Logger.verbose("Router initialized");
   }
   #initSsrServerRouter(options: SsrServerRouterOption) {
+    // already initialized in next server
   }
   #initSsrClientRouter(options: SsrClientRouterOption) {
     this.#instance = {
@@ -174,7 +179,7 @@ class Router {
       replace: (href: string, routeOptions) => {
         const { path, pathname, hash, href: fullHref } = this.#getPathInfo(href);
         this.#postPathChange({ path, pathname, hash });
-        
+        // for avoiding set state while rendering in redirect
         setTimeout(() => {
           options.router.replace(this.#withCsrRuntimeSearchParams(fullHref), routeOptions);
         }, 0);
@@ -235,7 +240,7 @@ class Router {
   }
   back(routeOptions?: RouteOptions) {
     if (getEnv().side === "server") throw new Error("back is only available in client side");
-    
+    // history보고 뒤로갈지 끌지 정하던가 먹통하던가
     this.#checkInitialized();
     this.#instance.back(routeOptions);
     return undefined as never;

package/client/translator.ts

@@ -11,9 +11,15 @@ export interface AllDictionary {
 
 export class Translator {
   static #langDictionaryMap = new Map<string, Dictionary>();
-
+  // Tracks dictionary objects already merged into the static map. The seeded
+  // snapshot (`allDictionary[lang]`) is a stable module-level reference within a
+  // build, so repeat requests skip the merge entirely. A dev rebuild produces a
+  // new object reference, which re-seeds and keeps hot reload correct.
   static #seededDicts = new WeakSet<object>();
-
+  // Browser-only source of truth for the active locale. Set by ClientWrapper from the server-resolved
+  // `lang` (Flight prop) so client lookups use the same locale that was seeded and server-rendered,
+  // instead of re-deriving it from the URL (unreliable for base-path / cloud routing). Unsafe on the
+  // server (concurrent requests share the module), so it must only be set when `typeof window !== undefined`.
   static #activeLocale: string | undefined;
   static setActiveLocale(lang: string | undefined) {
     if (lang) Translator.#activeLocale = lang;
@@ -29,10 +35,12 @@ export class Translator {
   hasDictionary(lang: string) {
     return Translator.#langDictionaryMap.has(lang);
   }
-
+  // Synchronously merge a single locale's dictionary into the shared static map.
+  // Idempotent: re-seeding the same locale merges keys without dropping existing ones.
+  // Used by ClientWrapper to seed the active locale from the server-provided prop.
   static seed(lang: string, dict: Dictionary | undefined) {
     if (!dict) return;
-    
+    // Skip the merge when this exact dictionary snapshot was already seeded.
     if (Translator.#seededDicts.has(dict)) return;
     Translator.#seededDicts.add(dict);
     const existingDictionary = Translator.#langDictionaryMap.get(lang) ?? {};

package/common/Logger.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { Logger, type LoggerSinkEntry } from "./Logger";
+
+const resetLoggerLevels = () => {
+  Logger.setLevel("log");
+  Logger.setFileLevel("trace");
+};
+
+describe("Logger sinks", () => {
+  test("emits file sink entries independently from terminal log level", () => {
+    const entries: LoggerSinkEntry[] = [];
+    const removeSink = Logger.addSink((entry) => entries.push(entry));
+
+    try {
+      Logger.setLevel("error");
+      Logger.setFileLevel("trace");
+      Logger.trace("file only", "sink-test", "LoggerTest");
+
+      expect(entries.length).toBe(1);
+      expect(entries[0]?.level).toBe("trace");
+      expect(entries[0]?.plainMessage.includes("file only")).toBe(true);
+    } finally {
+      removeSink();
+      resetLoggerLevels();
+    }
+  });
+
+  test("filters sink entries with AKAN_LOG_FILE_LEVEL semantics", () => {
+    const entries: LoggerSinkEntry[] = [];
+    const removeSink = Logger.addSink((entry) => entries.push(entry));
+
+    try {
+      Logger.setLevel("error");
+      Logger.setFileLevel("warn");
+      Logger.info("skip file", "sink-test", "LoggerTest");
+      Logger.warn("keep file", "sink-test", "LoggerTest");
+
+      expect(entries.map((entry) => entry.level)).toEqual(["warn"]);
+      expect(entries[0]?.plainMessage.includes("keep file")).toBe(true);
+    } finally {
+      removeSink();
+      resetLoggerLevels();
+    }
+  });
+});

package/common/Logger.ts

@@ -92,7 +92,7 @@ export class Logger {
   rawLog(msg: string, method?: "console" | "process") {
     Logger.rawLog(msg, method);
   }
-  
+  // biome-ignore lint/suspicious/useAdjacentOverloadSignatures: static logger API mirrors the instance API.
   static trace(msg: string, context = "", name = "App") {
     if (Logger.#shouldLog("trace")) Logger.#printMessages(name, msg, context, "trace");
   }
@@ -134,6 +134,7 @@ export class Logger {
       try {
         void Promise.resolve(sink(entry)).catch(() => undefined);
       } catch {
+        // Log sinks are observers; they must not break application logging.
       }
     }
   }
@@ -162,6 +163,7 @@ export class Logger {
     if (!Logger.#shouldWriteConsole(logLevel)) return;
     if (typeof window === "undefined")
       (process[writeStreamType] as unknown as NodeJS.WriteStream | undefined)?.write(message);
+    // biome-ignore lint/suspicious/noConsole: browser fallback
     else console.log(message);
   }
   static rawLog(msg = "", method?: "console" | "process", outputStream?: "log" | "error") {
@@ -172,6 +174,7 @@ export class Logger {
     Logger.#emit({ stream, message: msg, plainMessage: Logger.#stripAnsi(msg) });
     if (typeof window === "undefined" && method !== "console" && (process as unknown as NodeJS.Process | undefined))
       process[stream].write(msg);
+    // biome-ignore lint/suspicious/noConsole: browser fallback
     else console[outputStream === "error" ? "error" : "log"](msg.trim());
   }
 }

package/common/formatAndValidation.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  capitalize,
+  formatNumber,
+  formatPhone,
+  isEmail,
+  isPhoneNumber,
+  isValidDate,
+  lowerlize,
+  mergeVersion,
+  splitVersion,
+} from ".";
+
+describe("format and validation helpers", () => {
+  test("capitalizes and lowerlizes only the first character", () => {
+    expect(capitalize("akan")).toBe("Akan");
+    expect(capitalize("aKan")).toBe("AKan");
+    expect(lowerlize("Akan")).toBe("akan");
+    expect(lowerlize("AKan")).toBe("aKan");
+  });
+
+  test("formats numbers while preserving decimal text", () => {
+    expect(formatNumber("1234567")).toBe("1,234,567");
+    expect(formatNumber("1,234,567.89")).toBe("1,234,567.89");
+    expect(formatNumber("12abc34")).toBe("1,234");
+  });
+
+  test("formats supported phone number lengths", () => {
+    expect(formatPhone("0101234567")).toBe("010-123-4567");
+    expect(formatPhone("010-1234-5678")).toBe("010-1234-5678");
+    expect(formatPhone("0212345678")).toBe("021-234-5678");
+    expect(formatPhone("12345")).toBe("12345");
+    expect(formatPhone("")).toBe("");
+  });
+
+  test("validates email and phone strings", () => {
+    expect(isEmail("user@example.com")).toBe(true);
+    expect(isEmail("user.name@example.co.kr")).toBe(true);
+    expect(isEmail("not-an-email")).toBe(false);
+    expect(isEmail(null)).toBe(false);
+
+    expect(isPhoneNumber("010-1234-5678")).toBe(true);
+    expect(isPhoneNumber("031-123-4567")).toBe(true);
+    expect(isPhoneNumber("01012345678")).toBe(false);
+    expect(isPhoneNumber(undefined)).toBe(false);
+  });
+
+  test("validates dates from strings and Date instances", () => {
+    expect(isValidDate("2025-01-01")).toBe(true);
+    expect(isValidDate("not-a-date")).toBe(false);
+    expect(isValidDate(new Date("2025-01-01T00:00:00.000Z"))).toBe(true);
+    expect(isValidDate(new Date("not-a-date"))).toBe(false);
+  });
+
+  test("splits and merges semantic version parts", () => {
+    expect(splitVersion("1.2.3")).toEqual({ major: "1", minor: "2", patch: "3" });
+    expect(mergeVersion(1, 2, 3)).toBe("1.2.3");
+    expect(() => splitVersion("1.2")).toThrow("Invalid version");
+  });
+});

package/common/formatNumber.ts

@@ -1,14 +1,17 @@
 export const formatNumber = (numString: string) => {
-  
+  // 문자열이 아니면 문자열로 변환
   if (typeof numString !== "string") {
     numString = String(numString);
   }
 
+  // 소수점이 있는 경우 처리
   const parts = numString.split(".");
-  const integerPart = parts[0]?.replace(/[^\d]/g, "") ?? ""; 
+  const integerPart = parts[0]?.replace(/[^\d]/g, "") ?? ""; // 정수 부분에서 숫자만 추출
   const decimalPart = parts.length > 1 ? `.${parts[1]}` : "";
 
+  // 정수 부분에 콤마 추가
   const formattedInteger = Number(integerPart).toLocaleString("ko-KR");
 
+  // 정수 부분과 소수 부분 합치기
   return formattedInteger + decimalPart;
 };

package/common/hmrPhase.ts

@@ -1,7 +1,7 @@
 export type AkanHmrPhase = "refresh-import" | "react-refresh" | null;
 
 declare global {
-  
+  // Browser-only dev signal set by the Akan HMR client while applying Fast Refresh.
   var __AKAN_HMR_PHASE__: AkanHmrPhase | undefined;
 }