sonamu 0.10.11 → 0.10.13

package/src/syncer/filesystem-dependencies.ts

@@ -0,0 +1,73 @@
+import {
+  constants,
+  type MakeDirectoryOptions,
+  type PathLike,
+  type RmOptions,
+  type Stats,
+} from "node:fs";
+import { access, mkdir, readFile, rm, stat, unlink, writeFile } from "node:fs/promises";
+
+export type SyncerFilesystemDependencies = {
+  access(path: PathLike, mode?: number): Promise<void>;
+  mkdir(path: PathLike, options?: MakeDirectoryOptions): Promise<string | undefined>;
+  readFile(path: PathLike, encoding: BufferEncoding): Promise<string>;
+  rm(path: PathLike, options?: RmOptions): Promise<void>;
+  stat(path: PathLike): Promise<Stats>;
+  unlink(path: PathLike): Promise<void>;
+  writeFile(
+    path: PathLike,
+    data: string | NodeJS.ArrayBufferView,
+    encoding?: BufferEncoding,
+  ): Promise<void>;
+};
+
+const defaults: SyncerFilesystemDependencies = {
+  access: (path, mode) => access(path, mode),
+  mkdir: (path, options) => mkdir(path, options),
+  readFile: (path, encoding) => readFile(path, encoding),
+  rm: (path, options) => rm(path, options),
+  stat: (path) => stat(path),
+  unlink: (path) => unlink(path),
+  writeFile: (path, data, encoding) => writeFile(path, data, encoding),
+};
+
+export const syncerFilesystem: SyncerFilesystemDependencies = { ...defaults };
+
+export async function syncerFileExists(path: PathLike): Promise<boolean> {
+  try {
+    await syncerFilesystem.access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 테스트와 임베딩 환경에서 Syncer의 파일시스템 경계를 교체합니다. */
+export function configureSyncerFilesystem(
+  dependencies: Partial<SyncerFilesystemDependencies>,
+): () => void {
+  const restorers: Array<() => void> = [];
+  const override = <Key extends keyof SyncerFilesystemDependencies>(key: Key): void => {
+    if (!(key in dependencies)) return;
+
+    const previousDependency = syncerFilesystem[key];
+    Object.assign(syncerFilesystem, { [key]: dependencies[key] });
+    restorers.push(() => Object.assign(syncerFilesystem, { [key]: previousDependency }));
+  };
+
+  override("access");
+  override("mkdir");
+  override("readFile");
+  override("rm");
+  override("stat");
+  override("unlink");
+  override("writeFile");
+
+  let configured = true;
+  return () => {
+    if (!configured) return;
+    configured = false;
+
+    for (const restore of restorers) restore();
+  };
+}

package/src/syncer/module-loader.ts

@@ -11,6 +11,7 @@ import { globAsync } from "../utils/async-utils";
 import { importMembers } from "../utils/esm-utils";
 import { runtimePath } from "../utils/path-utils";
 import { type AbsolutePath } from "../utils/path-utils";
+import { isFunctionValue, isObjectValue } from "../utils/runtime-value";
 import { readApisFromFile } from "./api-parser";
 
 export type LoadedApis = ExtendedApi[];
@@ -35,7 +36,10 @@ export async function loadApis(): Promise<LoadedApis> {
     Sonamu.apiRootPath,
     "src/application/**/*.{model,frame}.ts", // !! runtimePath 안 씀 주의 !!
   );
-  const modelPaths = (await globAsync(modelPathsPattern)) as AbsolutePath[];
+  const modelPaths =
+    /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (await globAsync(
+      modelPathsPattern,
+    )) as AbsolutePath[];
 
   const apis: LoadedApis = [];
   for (const filePath of modelPaths) {
@@ -125,16 +129,16 @@ export async function loadWorkflows() {
       importedMembers
         .filter(({ value }) => {
           return (
-            typeof value === "object" &&
+            isObjectValue(value) &&
             value !== null &&
             "type" in value &&
             value.type === "workflow" &&
             "fn" in value &&
-            typeof value.fn === "function"
+            isFunctionValue(value.fn)
           );
         })
         .map(({ value }) => {
-          return value as WorkflowMetadata;
+          return /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ value as WorkflowMetadata;
         }),
     );
   }

package/src/syncer/syncer-actions.ts

@@ -1,5 +1,4 @@
 import assert from "assert";
-import { mkdir, readFile, writeFile } from "fs/promises";
 import path, { dirname } from "path";
 
 import chalk from "chalk";
@@ -10,10 +9,12 @@ import { AlreadyProcessedException } from "../exceptions/so-exceptions";
 import { Naite } from "../naite/naite";
 import { isTest } from "../utils/controller";
 import { formatCode } from "../utils/formatter";
-import { copyFileWithReplaceCoreToShared, exists } from "../utils/fs-utils";
 import { type AbsolutePath } from "../utils/path-utils";
+import { isObjectValue } from "../utils/runtime-value";
 import { generateTemplate } from "./code-generator";
+import { copyFileWithReplaceCoreToShared } from "./file-copy";
 import { trackWritten } from "./file-tracking";
+import { syncerFileExists, syncerFilesystem } from "./filesystem-dependencies";
 
 // web/.sonamu.env 에 현재 설정값 저장
 export async function actionSyncConfig() {
@@ -22,8 +23,11 @@ export async function actionSyncConfig() {
 
   Naite.t("actionSyncConfig", { content });
   await Promise.all([
-    ...Sonamu.config.sync.targets.map(async (target) => {
-      await writeFile(path.join(Sonamu.appRootPath, target, ".sonamu.env"), content);
+    ...Sonamu.config.sync.targets.map((target) => {
+      return syncerFilesystem.writeFile(
+        path.join(Sonamu.appRootPath, target, ".sonamu.env"),
+        content,
+      );
     }),
     generateTemplate("generated_sso", {}, { overwrite: true }),
   ]);
@@ -88,6 +92,30 @@ export async function actionGenerateHttps(): Promise<AbsolutePath> {
   return res;
 }
 
+/**
+ * 최종 REST caster를 담는 API 전용 validator registry를 재생성합니다.
+ */
+export async function actionGenerateHttpValidators(): Promise<AbsolutePath> {
+  const registryPath =
+    /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ path.join(
+      Sonamu.apiRootPath,
+      "src/application/sonamu.validators.generated.ts",
+    ) as AbsolutePath;
+  const policy = Sonamu.config.validation?.zodCompiler;
+  const isAot = isObjectValue(policy) && policy !== null && policy.api === "aot";
+  if (!isAot) {
+    // opt-out/JIT 전환 뒤 AOT compile import가 애플리케이션에 남지 않도록 산출물도 함께 정리합니다.
+    if (await syncerFileExists(registryPath)) {
+      await syncerFilesystem.unlink(registryPath);
+    }
+    return registryPath;
+  }
+
+  const [generatedPath] = await generateTemplate("http_validators", {}, { overwrite: true });
+  assert(generatedPath);
+  return generatedPath;
+}
+
 /**
  * queries.generated.ts 재생성합니다.
  * @returns 생성된 파일 경로 배열.
@@ -137,8 +165,8 @@ export async function actionSyncFilesToTargets(tsPaths: AbsolutePath[]): Promise
               .replace(`/${apiDir}/`, `/${target}/`)
               .replace("/application/", "/services/");
             const dir = dirname(dst);
-            if (!(await exists(dir))) {
-              await mkdir(dir, { recursive: true });
+            if (!(await syncerFileExists(dir))) {
+              await syncerFilesystem.mkdir(dir, { recursive: true });
             }
             const syncHeader = [
               "/**",
@@ -147,7 +175,9 @@ export async function actionSyncFilesToTargets(tsPaths: AbsolutePath[]): Promise
               " */",
             ].join("\n");
             await copyFileWithReplaceCoreToShared(realSrc, dst, syncHeader);
-            await trackWritten(dst as AbsolutePath);
+            await trackWritten(
+              /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ dst as AbsolutePath,
+            );
             !isTest() &&
               console.log(
                 chalk.bold("Copied: ") + chalk.blue(dst.replace(`${Sonamu.appRootPath}/`, "")),
@@ -174,7 +204,9 @@ export async function actionCopySharedToTargetsIfNotExists(): Promise<void> {
     import.meta.dirname.replace("/dist/", "/src/"),
     "../dict/utils.ts",
   );
-  const dictUtilsCode = (await exists(dictUtilsPath)) ? await readFile(dictUtilsPath, "utf-8") : "";
+  const dictUtilsCode = (await syncerFileExists(dictUtilsPath))
+    ? await syncerFilesystem.readFile(dictUtilsPath, "utf-8")
+    : "";
 
   // 특정 변수 치환을 위해서 사용합니다.
   const convertMap = {
@@ -192,16 +224,16 @@ export async function actionCopySharedToTargetsIfNotExists(): Promise<void> {
       import.meta.dirname.replace("/dist/", "/src/"),
       `../shared/${target}.shared.ts.txt`,
     );
-    if (!(await exists(srcPath))) {
+    if (!(await syncerFileExists(srcPath))) {
       continue;
     }
-    if (!(await exists(path.join(Sonamu.appRootPath, target)))) {
+    if (!(await syncerFileExists(path.join(Sonamu.appRootPath, target)))) {
       throw new Error(
         `Tried to copy sonamu.shared.ts to target '${target}' but the target directory does not exist. Please check your project directory structure.`,
       );
     }
 
-    const fullText = await readFile(srcPath, "utf-8");
+    const fullText = await syncerFilesystem.readFile(srcPath, "utf-8");
     const convertedText = Object.entries(convertMap).reduce(
       (acc, [key, value]) => acc.replace(`$[[${key}]]`, value),
       fullText,
@@ -211,8 +243,8 @@ export async function actionCopySharedToTargetsIfNotExists(): Promise<void> {
     const destPath = path.join(Sonamu.appRootPath, target, "src/services/sonamu.shared.ts");
 
     // 정말 혹시나지만 target 디렉토리는 있어도 src/services 디렉토리는 없을 수 있으므로 미리 생성해줍니다.
-    if (!(await exists(path.dirname(destPath)))) {
-      await mkdir(path.dirname(destPath), { recursive: true });
+    if (!(await syncerFileExists(path.dirname(destPath)))) {
+      await syncerFilesystem.mkdir(path.dirname(destPath), { recursive: true });
       console.warn(`Created directory '${path.dirname(destPath)}' because it did not exist.`);
     }
 
@@ -221,11 +253,11 @@ export async function actionCopySharedToTargetsIfNotExists(): Promise<void> {
     // 최초 1회만 생성하고 이후에는 덮어쓰지 않습니다.
     // 템플릿 내용($[[dictUtils]] 등)이 변경되었을 때 반영이 필요하면,
     // 해당 파일을 삭제한 뒤 `pnpm sonamu sync`로 재생성하면 됩니다.
-    if (await exists(destPath)) {
+    if (await syncerFileExists(destPath)) {
       continue;
     }
 
-    await writeFile(destPath, await formatCode(convertedText, destPath));
+    await syncerFilesystem.writeFile(destPath, await formatCode(convertedText, destPath));
     !isTest() &&
       console.log(chalk.bold("Copied: ") + chalk.blue(path.relative(Sonamu.appRootPath, destPath)));
   }
@@ -244,7 +276,11 @@ export async function actionSyncSonamuDictionary(): Promise<void> {
   const { targets } = Sonamu.config.sync;
   const i18nConfig = Sonamu.config.i18n;
 
-  const targetList = ["api", ...targets] as ("api" | "web" | "app")[];
+  const targetList =
+    /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ [
+      "api",
+      ...targets,
+    ] as ("api" | "web" | "app")[];
 
   const apiI18nDir = path.join(Sonamu.appRootPath, Sonamu.config.api.dir, "src/i18n");
 
@@ -273,7 +309,7 @@ async function syncLocaleFiles(
   const targetI18nDir = path.join(Sonamu.appRootPath, target, "src/i18n");
 
   // 디렉토리가 없으면 생성
-  await mkdir(targetI18nDir, { recursive: true });
+  await syncerFilesystem.mkdir(targetI18nDir, { recursive: true });
 
   for (const locale of locales) {
     const sourceFile = path.join(apiI18nDir, `${locale}.ts`);
@@ -286,7 +322,9 @@ async function syncLocaleFiles(
       " */",
     ].join("\n");
     await copyFileWithReplaceCoreToShared(sourceFile, targetFile, syncHeader);
-    await trackWritten(targetFile as AbsolutePath);
+    await trackWritten(
+      /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ targetFile as AbsolutePath,
+    );
     !isTest() &&
       console.log(chalk.bold("Copied: ") + chalk.cyan(`${target}/src/i18n/${locale}.ts`));
   }

package/src/syncer/syncer.ts

@@ -1,12 +1,11 @@
 import assert from "assert";
 import { EventEmitter } from "events";
-import { unlink } from "fs/promises";
 import path from "path";
 
 import { hot } from "@sonamu-kit/hmr-hook";
 import chalk from "chalk";
 import { minimatch } from "minimatch";
-import { group, unique } from "radashi";
+import { unique } from "radashi";
 import { type z } from "zod";
 
 import { registeredApis } from "../api/decorators";
@@ -22,20 +21,36 @@ import { type TemplateOptions } from "../types/types";
 import { mapAsync, reduceAsync } from "../utils/async-utils";
 import { centerText } from "../utils/console-util";
 import { isTest } from "../utils/controller";
-import { exists } from "../utils/fs-utils";
 import { type AbsolutePath } from "../utils/path-utils";
 import { runWithGracefulShutdown } from "../utils/process-utils";
+import { isObjectValue } from "../utils/runtime-value";
 import { findChangedFilesUsingChecksums, renewChecksums } from "./checksum";
 import { generateTemplate, renderTemplate } from "./code-generator";
 import { createEntity, delEntity } from "./entity-operations";
 import { getChecksumPatternGroup, getChecksumPatternGroupInAbsolutePath } from "./file-patterns";
 import { type FileType } from "./file-patterns";
+import { syncerFileExists, syncerFilesystem } from "./filesystem-dependencies";
 import { loadApis, loadModels, loadTypes, loadWorkflows } from "./module-loader";
 import { type LoadedApis, type LoadedModels, type LoadedTypes } from "./module-loader";
 import * as SyncerActions from "./syncer-actions";
 
-type DiffGroups = {
-  [key in FileType]: AbsolutePath[];
+type DiffGroupKey = FileType | "unknown";
+type DiffGroups = Partial<Record<DiffGroupKey, AbsolutePath[]>>;
+
+export interface SyncerDependencies {
+  actionCopySharedToTargetsIfNotExists: typeof SyncerActions.actionCopySharedToTargetsIfNotExists;
+  actionGenerateHttpValidators: typeof SyncerActions.actionGenerateHttpValidators;
+  actionGenerateSsrEntryServerIfNotExists: typeof SyncerActions.actionGenerateSsrEntryServerIfNotExists;
+  findChangedFilesUsingChecksums: typeof findChangedFilesUsingChecksums;
+  renewChecksums: typeof renewChecksums;
+}
+
+const defaultSyncerDependencies: SyncerDependencies = {
+  actionCopySharedToTargetsIfNotExists: SyncerActions.actionCopySharedToTargetsIfNotExists,
+  actionGenerateHttpValidators: SyncerActions.actionGenerateHttpValidators,
+  actionGenerateSsrEntryServerIfNotExists: SyncerActions.actionGenerateSsrEntryServerIfNotExists,
+  findChangedFilesUsingChecksums,
+  renewChecksums,
 };
 
 export class Syncer {
@@ -45,6 +60,8 @@ export class Syncer {
   workflows: Map<string, WorkflowMetadata[]> = new Map();
   eventEmitter: EventEmitter = new EventEmitter();
 
+  constructor(private readonly dependencies: SyncerDependencies = defaultSyncerDependencies) {}
+
   /**
    * 체크섬이 변경된 부분에 대해 싱크를 진행합니다.
    * dev 서버가 처음 떴을 때, sonamu sync 할 때 실행됩니다. 이후에는 hmrAndSync 경로를 타요.
@@ -54,12 +71,15 @@ export class Syncer {
     // 초기 부트스트랩! 얘네들은 idempotent하고 가볍기 때문에 무지성 실행해도 됩니다.
     // 얘네들은 sonamu.lock에 들어가지도 않고 따라서 HMR 경로를 타지도 않는 친구들입니다.
     // 그래서 아무 때나 그냥 돌려주면 되는데, hmrAndSync에서 매번 하는 것은 낭비이니 여기서 한 번만 합니다.
-    await SyncerActions.actionCopySharedToTargetsIfNotExists();
-    await SyncerActions.actionGenerateSsrEntryServerIfNotExists();
+    await this.dependencies.actionCopySharedToTargetsIfNotExists();
+    await this.dependencies.actionGenerateSsrEntryServerIfNotExists();
 
     // 바뀐 것이 없으면 그냥 넘어가요.
-    const changedFiles = await findChangedFilesUsingChecksums();
+    const changedFiles = await this.dependencies.findChangedFilesUsingChecksums();
     if (changedFiles.length === 0) {
+      if (await this.reconcileHttpValidatorRegistry()) {
+        await this.dependencies.renewChecksums();
+      }
       console.log(chalk.black.bgGreen(centerText("All files are synced!")));
       return;
     }
@@ -71,14 +91,31 @@ export class Syncer {
       async () => {
         // 얘가 싱크 작업 수행하는 본체입니다.
         await this.doSyncActions(changedFiles);
+        await this.reconcileHttpValidatorRegistry();
 
         // 싱크 액션이 끝나면 항상 체크섬을 다시 갱신합니다.
-        await renewChecksums();
+        await this.dependencies.renewChecksums();
       },
       { whenThisHappens: "SIGUSR2", waitForUpTo: 20000 },
     );
   }
 
+  private async reconcileHttpValidatorRegistry(): Promise<boolean> {
+    const registryPath = path.join(
+      Sonamu.apiRootPath,
+      "src/application/sonamu.validators.generated.ts",
+    );
+    const policy = Sonamu.config.validation?.zodCompiler;
+    const isAot = isObjectValue(policy) && policy !== null && policy.api === "aot";
+    if (isAot === (await syncerFileExists(registryPath))) {
+      return false;
+    }
+
+    // 변경 목록이 registry 삭제를 놓쳐도 checksum 갱신 전에 정책과 산출물을 다시 맞춥니다.
+    await this.dependencies.actionGenerateHttpValidators();
+    return true;
+  }
+
   /**
    * 강제 풀-싱크: lock을 무시하고 처음부터 다시 싱크합니다.
    *
@@ -88,8 +125,8 @@ export class Syncer {
    */
   async forceSync(): Promise<void> {
     const lockPath = path.join(Sonamu.apiRootPath, "sonamu.lock");
-    if (await exists(lockPath)) {
-      await unlink(lockPath);
+    if (await syncerFileExists(lockPath)) {
+      await syncerFilesystem.unlink(lockPath);
     }
     await this.sync();
   }
@@ -137,6 +174,7 @@ export class Syncer {
     await this.autoloadApis();
     await this.autoloadWorkflows();
     await this.autoloadSsrRoutes();
+    await Sonamu.refreshHttpValidators();
 
     this.eventEmitter.emit("onHMRCompleted");
   }
@@ -182,7 +220,11 @@ export class Syncer {
       // 그러니 안심하고 invalidate 해도 됩니다.
       // 테스트 환경에서는 hot.invalidateFile시 초기 에러가 발생하기 때문에 invalidate 하지 않습니다.
       if (!isTest()) {
-        const invalidatedPaths = (await hot.invalidateFile(diffFilePath, event)) as AbsolutePath[];
+        const invalidatedPaths =
+          /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (await hot.invalidateFile(
+            diffFilePath,
+            event,
+          )) as AbsolutePath[];
 
         if (invalidatedPaths.length > 0) {
           console.log(chalk.bold(`🔄 Invalidated:`));
@@ -271,7 +313,7 @@ export class Syncer {
     clearSSRRoutes();
 
     // ssr 폴더 없으면 스킵
-    if (!(await exists(ssrConfigPath))) {
+    if (!(await syncerFileExists(ssrConfigPath))) {
       return;
     }
 
@@ -302,7 +344,10 @@ export class Syncer {
    */
   async doSyncActions(diffFilePaths: AbsolutePath[]): Promise<{ diffTypes: FileType[] }> {
     const diffGroups = this.calculateDiffGroups(diffFilePaths);
-    const diffTypes = Object.keys(diffGroups) as FileType[];
+    const diffTypes =
+      /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ Object.keys(
+        diffGroups,
+      ) as FileType[];
 
     // 여기는 별로 중요한 파트는 아닙니다.
     // 아래의 if 전개를 깔끔하게 하려고 만든 DSL 같은 거라서, 무시하셔도 됩니다.
@@ -324,11 +369,27 @@ export class Syncer {
     }
 
     if (changeMatches("config")) {
-      await this.handleConfigChanges(diffGroups);
+      await this.handleConfigChanges();
     }
 
     if (changeMatches("i18n", "entity" /*레이블*/, "config" /*defaultLocale등*/)) {
-      await this.handleSonamuDictionaryRelatedChanges(diffGroups);
+      await this.handleSonamuDictionaryRelatedChanges();
+    }
+
+    const metadataChanged = diffTypes.some((type) =>
+      ["entity", "types", "model", "frame", "config"].includes(type),
+    );
+    if (changeMatches("httpValidatorsGenerated") && !metadataChanged) {
+      // registry 자체 drift는 최신 in-memory metadata로 즉시 덮어써 lock 갱신 전에 정합성을 복구합니다.
+      await this.dependencies.actionGenerateHttpValidators();
+    }
+
+    if (metadataChanged) {
+      // 모든 생성/복사 액션 뒤 최신 metadata를 다시 읽어 registry를 한 번만 확정합니다.
+      await this.autoloadTypes();
+      await this.autoloadModels();
+      await this.autoloadApis();
+      await this.dependencies.actionGenerateHttpValidators();
     }
 
     if (nothingMatches()) {
@@ -343,22 +404,26 @@ export class Syncer {
     };
   }
 
-  calculateDiffGroups(diffFiles: AbsolutePath[]): DiffGroups {
+  calculateDiffGroups(diffFiles: AbsolutePath[]) {
     const patternGroup = getChecksumPatternGroup();
-    const fileTypes = Object.keys(patternGroup) as FileType[];
-
-    return group(diffFiles, (filePath) => {
-      // 절대 경로 → appRoot 기준 상대 경로 (예: "api/src/...", "web/src/...")
+    const fileTypes =
+      /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ Object.keys(
+        patternGroup,
+      ) as FileType[];
+
+    const diffGroups: DiffGroups = {};
+    for (const filePath of diffFiles) {
+      // 절대 경로를 appRoot 기준 상대 경로로 바꿔 체크섬 패턴과 비교한다.
       const relativePath = path.relative(Sonamu.appRootPath, filePath);
-      if (relativePath.startsWith("..")) return "unknown";
-
-      for (const fileType of fileTypes) {
-        if (minimatch(relativePath, patternGroup[fileType])) {
-          return fileType;
-        }
-      }
-      return "unknown";
-    }) as unknown as DiffGroups;
+      const fileType = fileTypes.find((candidate) =>
+        minimatch(relativePath, patternGroup[candidate]),
+      );
+      const groupKey: DiffGroupKey = relativePath.startsWith("..")
+        ? "unknown"
+        : (fileType ?? "unknown");
+      (diffGroups[groupKey] ??= []).push(filePath);
+    }
+    return diffGroups;
   }
 
   private changeMatcher(diffTypes: FileType[], diffGroups: DiffGroups) {
@@ -404,12 +469,13 @@ export class Syncer {
       const entity = EntityManager.get(entityId);
 
       // 프로젝트에 생성되어야 하는 .ts 파일의 경로입니다.
-      const typeFilePath = path.join(
-        Sonamu.apiRootPath,
-        `src/application/${entity.names.fs}/${entity.names.fs}.types.ts`,
-      ) as AbsolutePath;
+      const typeFilePath =
+        /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ path.join(
+          Sonamu.apiRootPath,
+          `src/application/${entity.names.fs}/${entity.names.fs}.types.ts`,
+        ) as AbsolutePath;
 
-      if (entity.parentId === undefined && !(await exists(typeFilePath))) {
+      if (entity.parentId === undefined && !(await syncerFileExists(typeFilePath))) {
         // *.types.ts가 만들어집니다.
         const types = await SyncerActions.actionGenerateInitialTypes(entityId);
 
@@ -464,11 +530,15 @@ export class Syncer {
     await SyncerActions.actionSyncFilesToTargets(tsPaths);
   }
 
-  async handleConfigChanges(_: DiffGroups): Promise<void> {
+  async handleConfigChanges(): Promise<void> {
+    if (process.env.HOT === "yes") {
+      const { loadConfig } = await import("../api/config");
+      Sonamu.config = await loadConfig(Sonamu.apiRootPath);
+    }
     await SyncerActions.actionSyncConfig();
   }
 
-  async handleSonamuDictionaryRelatedChanges(_: DiffGroups): Promise<void> {
+  async handleSonamuDictionaryRelatedChanges(): Promise<void> {
     await SyncerActions.actionSyncSonamuDictionary();
   }
 
@@ -508,7 +578,7 @@ export class Syncer {
     return {
       subPath,
       fullPath,
-      isExists: await exists(fullPath),
+      isExists: await syncerFileExists(fullPath),
     };
   }
 
@@ -535,7 +605,7 @@ export class Syncer {
         if (key.startsWith("view_enums")) {
           await mapAsync(enumsKeys, async (componentId) => {
             const { target, path: p } = tpl.getTargetAndPath(names, componentId);
-            result[`${key}__${componentId}`] = await exists(
+            result[`${key}__${componentId}`] = await syncerFileExists(
               path.join(Sonamu.appRootPath, target, p),
             );
           });
@@ -546,17 +616,20 @@ export class Syncer {
         const { targets } = Sonamu.config.sync;
         if (target.includes(":target")) {
           await mapAsync(targets, async (t) => {
-            result[`${key}__${t}`] = await exists(
+            result[`${key}__${t}`] = await syncerFileExists(
               path.join(Sonamu.appRootPath, target.replace(":target", t), p),
             );
           });
         } else {
-          result[key] = await exists(path.join(Sonamu.appRootPath, target, p));
+          result[key] = await syncerFileExists(path.join(Sonamu.appRootPath, target, p));
         }
 
         return result;
       },
-      {} as Record<`${TemplateKey}${string}`, boolean>,
+      /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ {} as Record<
+        `${TemplateKey}${string}`,
+        boolean
+      >,
     );
   }
 
@@ -599,6 +672,6 @@ export class Syncer {
    * 하위호환용 프록시 메소드입니다.
    */
   async renewChecksums(): Promise<void> {
-    return await renewChecksums();
+    return await this.dependencies.renewChecksums();
   }
 }

package/src/syncer/watcher.ts

@@ -3,7 +3,7 @@ import { type Stats } from "node:fs";
 import path from "path";
 
 import chalk from "chalk";
-import chokidar, { type FSWatcher } from "chokidar";
+import { type FSWatcher, watch } from "chokidar";
 import { minimatch } from "minimatch";
 
 import { Sonamu } from "../api";
@@ -22,7 +22,7 @@ export async function setupWatcher(
   // api 본인뿐 아니라 sync target들의 src도 봅니다.
   // target 산출물(sonamu.generated, services.generated, i18n copy 등)이 외부에서
   // 변경되는 경우를 drift로 잡아 워닝을 띄우기 위함입니다.
-  const watcher = chokidar.watch(apiAndTargetsSrcPaths(), {
+  const watcher = watch(apiAndTargetsSrcPaths(), {
     ignored: ignoreIfExtensionIsNotOneOf(".ts", ".json", ".http"),
     persistent: true,
     ignoreInitial: true,
@@ -49,7 +49,8 @@ export async function setupWatcher(
   });
 
   watcher.on("all", (event: string, filePath: string) => {
-    const absolutePath = filePath as AbsolutePath;
+    const absolutePath =
+      /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ filePath as AbsolutePath;
     assert(
       absolutePath.startsWith(Sonamu.appRootPath),
       "File path is not within the app root path",
@@ -92,7 +93,10 @@ function apiAndTargetsSrcPaths() {
  * 따라서 "이 확장자만 허용"을 표현하려면 *다른 확장자에 대해 true*를 반환해야 합니다.
  */
 function ignoreIfExtensionIsNotOneOf(...allowedExtensions: `.${string}`[]) {
-  const isAllowed = (ext: string) => (allowedExtensions as string[]).includes(ext);
+  const isAllowed = (ext: string) =>
+    /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+      allowedExtensions as string[]
+    ).includes(ext);
 
   return (p: string, stats?: Stats) => !!stats?.isFile() && !isAllowed(path.extname(p));
 }