sonamu 0.9.4 → 0.9.6

package/src/syncer/syncer.ts

@@ -1,6 +1,6 @@
 import assert from "assert";
 import { EventEmitter } from "events";
-import { mkdir, readFile, writeFile } from "fs/promises";
+import { unlink } from "fs/promises";
 import path from "path";
 
 import { hot } from "@sonamu-kit/hmr-hook";
@@ -13,7 +13,6 @@ import { registeredApis } from "../api/decorators";
 import { Sonamu } from "../api/sonamu";
 import { EntityManager } from "../entity/entity-manager";
 import { type EntityNamesRecord } from "../entity/entity-manager";
-import { AlreadyProcessedException } from "../exceptions/so-exceptions";
 import { Naite } from "../naite/naite";
 import { type WorkflowMetadata } from "../tasks/decorator";
 import { TemplateManager } from "../template/template-manager";
@@ -23,13 +22,13 @@ 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 { copyFileWithReplaceCoreToShared, exists } from "../utils/fs-utils";
+import { exists } from "../utils/fs-utils";
 import { type AbsolutePath } from "../utils/path-utils";
 import { runWithGracefulShutdown } from "../utils/process-utils";
 import { findChangedFilesUsingChecksums, renewChecksums } from "./checksum";
 import { generateTemplate, renderTemplate } from "./code-generator";
 import { createEntity, delEntity } from "./entity-operations";
-import { checksumPatternGroup, getChecksumPatternGroupInAbsolutePath } from "./file-patterns";
+import { getChecksumPatternGroup, getChecksumPatternGroupInAbsolutePath } from "./file-patterns";
 import { type FileType } from "./file-patterns";
 import { loadApis, loadModels, loadTypes, loadWorkflows } from "./module-loader";
 import { type LoadedApis, type LoadedModels, type LoadedTypes } from "./module-loader";
@@ -48,35 +47,25 @@ export class Syncer {
 
   /**
    * 체크섬이 변경된 부분에 대해 싱크를 진행합니다.
-   * sonamu.shared.ts는 파일이 없을 때만 1회 생성하고, 이후에는 덮어쓰지 않습니다.
+   * dev 서버가 처음 떴을 때, sonamu sync 할 때 실행됩니다. 이후에는 syncFromWatcher 경로를 타요.
    * @returns
    */
   async sync(): Promise<void> {
-    const { targets } = Sonamu.config.sync;
+    // 초기 부트스트랩! 얘네들은 idempotent하고 가볍기 때문에 무지성 실행해도 됩니다.
+    // 얘네들은 sonamu.lock에 들어가지도 않고 따라서 HMR 경로를 타지도 않는 친구들입니다.
+    // 그래서 아무 때나 그냥 돌려주면 되는데, syncFromWatcher에서 매번 하는 것은 낭비이니 여기서 한 번만 합니다.
+    await SyncerActions.actionCopySharedToTargetsIfNotExists();
+    await SyncerActions.actionGenerateSsrEntryServerIfNotExists();
 
-    // sonamu.shared.ts는 파일이 없을 때만 1회 생성합니다.
-    await this.copySharedToTargets(targets);
-
-    // 그 다음부터는 변경된 파일을 찾아서 동기화 작업을 실행합니다.
+    // 바뀐 것이 없으면 그냥 넘어가요.
     const changedFiles = await findChangedFilesUsingChecksums();
     if (changedFiles.length === 0) {
       console.log(chalk.black.bgGreen(centerText("All files are synced!")));
-
-      // 변경사항이 없어도 SSR 템플릿은 생성 (초기 설정 시, 이미 존재하면 스킵)
-      try {
-        await generateTemplate("queries", {}, { overwrite: false });
-        await generateTemplate("entry_server", {}, { overwrite: false });
-      } catch (e) {
-        // 파일이 이미 존재하면 무시
-        if (!(e instanceof AlreadyProcessedException)) {
-          console.error("Failed to generate SSR templates:", e);
-        }
-      }
-
       return;
     }
 
-    // 만약 싱크 중에 프로세스가 죽으면 꼬여버리기 때문에,
+    // 여기서 실제 싱크 동작을 수행합니다.
+    // 다만 싱크 중에 프로세스가 죽으면 꼬여버리기 때문에,
     // 시그널에도 잠시 버틸 수 있는 환경 속에서 싱크를 실행합니다.
     await runWithGracefulShutdown(
       async () => {
@@ -91,89 +80,147 @@ export class Syncer {
   }
 
   /**
-   * Watcher가 감지한 파일 변경 사항에 대해 싱크를 진행합니다.
-   * 주어진 변경 파일들 중 체크섬 관리 대상인 것들만 가져다가 싱크를 진행합니다.
-   * 체크섬 파일 업데이트는 여기에서 하지 않습니다. 호출자가 합니다.
-   * @param diffFilePath - 변경 파일들. 프로젝트 루트부터 "src/" 또는 "dist/"로 시작하는 상대 경로입니다. 예시: "src/application/user/user.model.ts"
+   * 강제 풀-싱크: lock을 무시하고 처음부터 다시 싱크합니다.
+   *
+   * **사용처**: git post-merge hook, CI, dev 서버의 `f` 핫키.
+   * **실패 안전성**: 도중에 프로세스가 죽어 lock 없는 상태로 남아도 무해 — 다음 sync에서
+   * lock 없으면 자연스럽게 풀-싱크가 트리거되어 새 lock이 작성됨.
    */
-  async syncFromWatcher(event: string, diffFilePath: AbsolutePath): Promise<void> {
-    if (event !== "change" && event !== "add" && event !== "unlink") {
-      return;
+  async forceSync(): Promise<void> {
+    const lockPath = path.join(Sonamu.apiRootPath, "sonamu.lock");
+    if (await exists(lockPath)) {
+      await unlink(lockPath);
     }
+    await this.sync();
+  }
 
-    // SSR 설정 파일 변경 감지
-    if (diffFilePath.includes("/src/ssr/")) {
-      console.log(chalk.bold.yellow("SSR config changed - reloading..."));
-      // SSR 파일도 invalidate 후 reload
-      if (!isTest()) {
-        await hot.invalidateFile(diffFilePath, event);
-      }
-      await this.autoloadSSRRoutes();
-      this.eventEmitter.emit("onHMRCompleted");
-      return;
+  /**
+   * Watcher가 batch로 모은 변경 파일들에 대해 한 번의 HMR/sync 사이클을 돕니다.
+   *
+   * HMR은 api/src 안에서 일어나는 모든 파일들에 대해서 수행합니다.
+   * checksumPatternGroup 매칭 여부와 무관하게 api/src 전체 대상입니다.
+   * 가령 api/src/utils/subset-loaders.ts 같은 파일도 변경되면 HMR은 해줍니다.
+   *
+   * Sync는 checksumPatternGroup으로 매칭되는 파일들에 대해서만 수행합니다.
+   * 여기에는 web/src나 app/src 같은 다른 target의 파일이 포함될 수 있습니다.
+   * 이런 non-api 경로의 파일들은 HMR과는 아무 상관이 없으므로, invalidate을 하지 않습니다.
+   *
+   * @param fileEvents - path → event 맵. event는 "change" | "add".
+   */
+  async hmrAndSync(fileEvents: Map<AbsolutePath, "change" | "add">): Promise<void> {
+    const hmrActionRequiredEvents = this.extractHmrActionRequiredFileEvents(fileEvents);
+    const syncTriggeringPaths = await this.extractSyncTriggeringFileEventPaths(fileEvents);
+
+    // HMR 영역: 파일 이벤트 중 api의 모듈 그래프에 있는 파일들에 대한 변동은 hmrActionRequiredEvents로 잡힙니다.
+    // 이 친구들은 invalidate 처리해줍니다.
+    // 이 호출은 아래 sync보다 무조건 먼저 일어나야 합니다!
+    // 왜냐하면 sync에서는 변경된 model 코드를 새로 import해서 처리해야 하는 경우도 있기 때문입니다.
+    await this.invalidateDependentsAffectedByFileEvents(hmrActionRequiredEvents);
+
+    // Sync 영역: checksumPatternGroup에 명시된 파일들에 대한 변동은 syncTriggeringPaths로 잡힙니다.
+    // 이 친구들은 적절한 sync 작업으로 대응합니다.
+    if (syncTriggeringPaths.length > 0) {
+      await this.doSyncActions(syncTriggeringPaths);
     }
 
-    // 일단 변경된 파일과 dependent 파일들을 invalidate 합니다.
-    // 한 번 이상 import된 친구들에 대해서만 실제 작업이 일어납니다.
-    // 그러니 안심하고 invalidate 해도 됩니다.
-    // 테스트 환경에서는 hot.invalidateFile시 초기 에러가 발생하기 때문에 invalidate 하지 않습니다.
-    if (!isTest()) {
-      const invalidatedPaths = (await hot.invalidateFile(diffFilePath, event)) as AbsolutePath[];
-
-      if (invalidatedPaths.length > 0) {
-        console.log(chalk.bold(`🔄 Invalidated:`));
-
-        for (const invalidatedPath of invalidatedPaths) {
-          try {
-            // 만약 model.ts 파일이 변경(invalidate)되었다? 그러면 registeredApis 중에서 이 모델에 해당하는 api들은 지워줘요.
-            // registeredApis는 통으로 다 날려버릴 수 없습니다. registeredApis에 올라오는 친구들은 초기 로드시 또는 HMR시에만 등록되기 때문입니다.
-            // 따라서 model.ts 파일의 변경으로 다음번 새로운 eval이 예상되는 이 시점에서만, 이 모델에서 나온 registeredApis들을 지워줄 수 있습니다.
-            const removedApis = this.removeInvalidatedRegisteredApis(invalidatedPath);
-            if (removedApis.length > 0) {
-              console.log(
-                chalk.blue(`- ${path.relative(Sonamu.apiRootPath, invalidatedPath)}`),
-                chalk.gray(`(with ${removedApis.length} APIs)`),
-              );
-            } else {
-              console.log(chalk.blue(`- ${path.relative(Sonamu.apiRootPath, invalidatedPath)}`));
-            }
-          } catch (e) {
-            console.error(e);
-            console.error(
-              chalk.red(`Failed to remove invalidated registered APIs for ${invalidatedPath}`),
-            );
-          }
-        }
+    // 싱크 작업이 끝났으면 무지성 로드를 수행합니다.
+    // 싱크를 안 한 경우에도 로드는 해야 해요. 위에서 관련있는 친구들은 다 invalidate 되었거든요!
+    //
+    // 변경된 파일들에 대해서 새롭게 당겨오는(load) 행위는 doSyncActions에서 하지 않습니다.
+    // doSyncActions에서는 파일을 읽고 만드는 싱크 행위만 합니다.
+    // 거기서 딱 변경된 부분에 영향받는 autoload만 선별해서 수행하려면 너무 지저분하고 복잡해집니다.
+    //
+    // 퍼포먼스 영향은 무시해도 좋습니다.
+    // 어차피 hmr-hook에 의해 invalidate된 부분들이 아니라면 캐시 그대로 유지합니다.
+    await this.autoloadTypes();
+    await this.autoloadModels();
+    await this.autoloadApis();
+    await this.autoloadWorkflows();
+    await this.autoloadSsrRoutes();
+
+    this.eventEmitter.emit("onHMRCompleted");
+  }
+
+  private extractHmrActionRequiredFileEvents(
+    fileEvents: Map<AbsolutePath, "change" | "add">,
+  ): Map<AbsolutePath, "change" | "add"> {
+    const apiSrc = path.join(Sonamu.apiRootPath, "src");
+    const result = new Map<AbsolutePath, "change" | "add">();
+    for (const [filePath, event] of fileEvents) {
+      if (!filePath.startsWith(apiSrc)) {
+        continue;
       }
+      result.set(filePath, event);
     }
+    return result;
+  }
 
-    // devRunner 활성화 시, 변경된 소스 파일을 Vitest 모듈 그래프에서도 무효화합니다.
-    // Vite의 moduleGraph.invalidateModule()이 importer 방향으로 재귀적 cascade하므로,
-    // 소스 파일 하나만 무효화하면 이를 import하는 테스트 파일도 자동으로 무효화됩니다.
-    if (!isTest() && Sonamu.config.test?.devRunner?.enabled && Sonamu.devVitestManager) {
-      Sonamu.devVitestManager.invalidateFiles([diffFilePath]);
-      console.log(
-        chalk.dim(`Test invalidated: ${path.relative(Sonamu.apiRootPath, diffFilePath)}`),
+  private async extractSyncTriggeringFileEventPaths(
+    fileEvents: Map<AbsolutePath, "change" | "add">,
+  ): Promise<AbsolutePath[]> {
+    const checkPatternGroup = getChecksumPatternGroupInAbsolutePath();
+    const syncTriggeringPaths: AbsolutePath[] = [];
+    for (const [diffFilePath] of fileEvents) {
+      const isInCheckPatternGroup = Object.values(checkPatternGroup).some((pattern) =>
+        minimatch(diffFilePath, pattern),
       );
+      if (!isInCheckPatternGroup) {
+        continue;
+      }
+      syncTriggeringPaths.push(diffFilePath);
     }
 
-    const isInCheckPatternGroup = Object.values(getChecksumPatternGroupInAbsolutePath()).some(
-      (pattern) => minimatch(diffFilePath, pattern),
-    );
-
-    // 할 일(sync)이 있으면 합니다.
-    if (isInCheckPatternGroup) {
-      await this.doSyncActions([diffFilePath]);
-    }
+    return syncTriggeringPaths;
+  }
 
-    // 싱크 작업이 끝나면 모든 모듈을 로드합니다.
-    // hmr-hook에 의해 invalidate된 부분들이 아니라면 캐시 그대로 유지합니다.
-    await this.autoloadTypes();
-    await this.autoloadModels();
-    await this.autoloadApis();
-    await this.autoloadWorkflows();
+  private async invalidateDependentsAffectedByFileEvents(
+    fileEvents: Map<AbsolutePath, "change" | "add">,
+  ) {
+    for (const [diffFilePath, event] of fileEvents) {
+      // 변경된 파일과 dependent 파일들을 invalidate 합니다.
+      // 한 번 이상 import된 친구들에 대해서만 실제 작업이 일어납니다.
+      // 그러니 안심하고 invalidate 해도 됩니다.
+      // 테스트 환경에서는 hot.invalidateFile시 초기 에러가 발생하기 때문에 invalidate 하지 않습니다.
+      if (!isTest()) {
+        const invalidatedPaths = (await hot.invalidateFile(diffFilePath, event)) as AbsolutePath[];
+
+        if (invalidatedPaths.length > 0) {
+          console.log(chalk.bold(`🔄 Invalidated:`));
+
+          for (const invalidatedPath of invalidatedPaths) {
+            try {
+              // 만약 model.ts 파일이 변경(invalidate)되었다? 그러면 registeredApis 중에서 이 모델에 해당하는 api들은 지워줘요.
+              // registeredApis는 통으로 다 날려버릴 수 없습니다. registeredApis에 올라오는 친구들은 초기 로드시 또는 HMR시에만 등록되기 때문입니다.
+              // 따라서 model.ts 파일의 변경으로 다음번 새로운 eval이 예상되는 이 시점에서만, 이 모델에서 나온 registeredApis들을 지워줄 수 있습니다.
+              const removedApis = this.removeInvalidatedRegisteredApis(invalidatedPath);
+              if (removedApis.length > 0) {
+                console.log(
+                  chalk.blue(`- ${path.relative(Sonamu.apiRootPath, invalidatedPath)}`),
+                  chalk.gray(`(with ${removedApis.length} APIs)`),
+                );
+              } else {
+                console.log(chalk.blue(`- ${path.relative(Sonamu.apiRootPath, invalidatedPath)}`));
+              }
+            } catch (e) {
+              console.error(e);
+              console.error(
+                chalk.red(`Failed to remove invalidated registered APIs for ${invalidatedPath}`),
+              );
+            }
+          }
+        }
+      }
 
-    this.eventEmitter.emit("onHMRCompleted");
+      // devRunner 활성화 시, 변경된 소스 파일을 Vitest 모듈 그래프에서도 무효화합니다.
+      // Vite의 moduleGraph.invalidateModule()이 importer 방향으로 재귀적 cascade하므로,
+      // 소스 파일 하나만 무효화하면 이를 import하는 테스트 파일도 자동으로 무효화됩니다.
+      if (!isTest() && Sonamu.config.test?.devRunner?.enabled && Sonamu.devVitestManager) {
+        Sonamu.devVitestManager.invalidateFiles([diffFilePath]);
+        console.log(
+          chalk.dim(`Test invalidated: ${path.relative(Sonamu.apiRootPath, diffFilePath)}`),
+        );
+      }
+    }
   }
 
   removeInvalidatedRegisteredApis(
@@ -195,73 +242,6 @@ export class Syncer {
     return toRemove;
   }
 
-  async copySharedToTargets(targets: string[]): Promise<void> {
-    // plural.ts 내용을 읽어서 shared 파일에 삽입합니다.
-    const dictUtilsPath = path.join(
-      import.meta.dirname.replace("/dist/", "/src/"),
-      "../dict/utils.ts",
-    );
-    const dictUtilsCode = (await exists(dictUtilsPath))
-      ? await readFile(dictUtilsPath, "utf-8")
-      : "";
-
-    // 특정 변수 치환을 위해서 사용합니다.
-    const convertMap = {
-      baseUrl:
-        Sonamu.config.server.baseUrl ??
-        `http://${Sonamu.config.server.listen?.host ?? "localhost"}:${Sonamu.config.server.listen?.port ?? 3000}`,
-      dictUtils: dictUtilsCode,
-    };
-
-    for (const target of targets) {
-      // 지금 가져가려는 이 파일은 Sonamu 코드베이스의 일부입니다.
-      // 그런데 dist 속 빌드된 소스 코드 파일이 필요한 것이 아니고, src에만 있는 텍스트 파일이 필요합니다.
-      // 따라서 /src/에서 찾습니다.
-      const srcPath = path.join(
-        import.meta.dirname.replace("/dist/", "/src/"),
-        `../shared/${target}.shared.ts.txt`,
-      );
-      if (!(await exists(srcPath))) {
-        continue;
-      }
-      if (!(await exists(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 convertedText = Object.entries(convertMap).reduce(
-        (acc, [key, value]) => acc.replace(`$[[${key}]]`, value),
-        fullText,
-      );
-
-      // 이건 프로젝트에 .ts 소스 코드 파일을 생성하는 것이므로 src의 .ts 경로로 갑니다.
-      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 });
-        console.warn(`Created directory '${path.dirname(destPath)}' because it did not exist.`);
-      }
-
-      // 파일이 이미 존재하면 건너뜁니다.
-      // sonamu.shared.ts는 프로젝트에서 자유롭게 커스터마이징할 수 있어야 하므로,
-      // 최초 1회만 생성하고 이후에는 덮어쓰지 않습니다.
-      // 템플릿 내용($[[dictUtils]] 등)이 변경되었을 때 반영이 필요하면,
-      // 해당 파일을 삭제한 뒤 `pnpm sonamu sync`로 재생성하면 됩니다.
-      if (await exists(destPath)) {
-        continue;
-      }
-
-      await writeFile(destPath, convertedText);
-      !isTest() &&
-        console.log(
-          chalk.bold("Copied: ") + chalk.blue(path.relative(Sonamu.appRootPath, destPath)),
-        );
-    }
-  }
-
   async autoloadTypes() {
     this.types = await loadTypes();
   }
@@ -279,7 +259,7 @@ export class Syncer {
     await Sonamu.workflows.synchronize(this.workflows);
   }
 
-  async autoloadSSRRoutes(): Promise<void> {
+  async autoloadSsrRoutes(): Promise<void> {
     const ssrConfigPath = path.join(Sonamu.apiRootPath, "src/ssr");
 
     // 기존 routes 초기화
@@ -312,52 +292,46 @@ export class Syncer {
   /**
    * 실제 싱크를 수행하는 본체입니다.
    * 변경된 파일들을 타입별로 분류하고 각 타입에 맞는 액션을 실행합니다.
+   *
    * @param diffFilePaths - 변경된 파일들의 절대 경로 목록
    * @returns diffTypes - 변경된 파일의 타입 목록 (entity, types, model 등)
    */
-  async doSyncActions(diffFilePaths: AbsolutePath[]): Promise<{ diffTypes: string[] }> {
+  async doSyncActions(diffFilePaths: AbsolutePath[]): Promise<{ diffTypes: FileType[] }> {
     const diffGroups = this.calculateDiffGroups(diffFilePaths);
     const diffTypes = Object.keys(diffGroups) as FileType[];
 
-    // Single source of truth가 변경된 경우
-    if (diffTypes.includes("entity") || diffTypes.includes("types")) {
-      await this.handleTruthSourceChanges(diffGroups, diffTypes);
-    }
+    // 여기는 별로 중요한 파트는 아닙니다.
+    // 아래의 if 전개를 깔끔하게 하려고 만든 DSL 같은 거라서, 무시하셔도 됩니다.
+    const { changeMatches, nothingMatches, unhandledPaths } = this.changeMatcher(
+      diffTypes,
+      diffGroups,
+    );
 
-    // 타겟으로 복사만 하면 되는 파일이 변경된 경우
-    if (
-      diffTypes.includes("types") ||
-      diffTypes.includes("functions") ||
-      diffTypes.includes("generated")
-    ) {
-      await this.handleSyncableFileChanges(diffGroups);
+    if (changeMatches("entity", "types")) {
+      await this.handleTruthSourceChanges(diffGroups);
     }
 
-    // 모델/프레임 구현체가 변경된 경우
-    if (diffTypes.includes("model") || diffTypes.includes("frame")) {
+    if (changeMatches("model", "frame")) {
       await this.handleImplementationChanges(diffGroups);
     }
 
-    // 설정 파일이 변경된 경우
-    if (diffTypes.includes("config")) {
-      await SyncerActions.actionSyncConfig();
+    if (changeMatches("types", "functions")) {
+      await this.handleAuxiliarySymbolChanges(diffGroups);
     }
 
-    // 워크플로우 파일이 변경된 경우
-    if (diffTypes.includes("workflow")) {
-      await this.autoloadWorkflows();
+    if (changeMatches("config")) {
+      await this.handleConfigChanges(diffGroups);
     }
 
-    // i18n 관련 파일이 변경된 경우
-    // - i18n/*.ts: locale 번역 파일
-    // - entity.json: entity labels
-    // - sonamu.config.ts: i18n 설정 (defaultLocale, supportedLocales)
-    if (
-      diffTypes.includes("i18n") ||
-      diffTypes.includes("entity") ||
-      diffTypes.includes("config")
-    ) {
-      await this.syncSD();
+    if (changeMatches("i18n", "entity" /*레이블*/, "config" /*defaultLocale등*/)) {
+      await this.handleSonamuDictionaryRelatedChanges(diffGroups);
+    }
+
+    if (nothingMatches()) {
+      // 파일 변경은 감지되었으나 저 위 어느 changeMatches에도 걸리지 않은 파일들이 drifts입니다.
+      // syncer는 소스의 변경에는 반응하지만 산출물의 변경(drift)에는 직접적으로 반응하지 않습니다.
+      // 대신 이 drift에 대해 경고 정도만 출력해줍니다.
+      await this.handleDrifts(unhandledPaths());
     }
 
     return {
@@ -366,16 +340,16 @@ export class Syncer {
   }
 
   calculateDiffGroups(diffFiles: AbsolutePath[]): DiffGroups {
-    const fileTypes = Object.keys(checksumPatternGroup) as FileType[];
+    const patternGroup = getChecksumPatternGroup();
+    const fileTypes = Object.keys(patternGroup) as FileType[];
 
     return group(diffFiles, (filePath) => {
-      // 절대 경로에서 src/로 시작하는 상대 경로 부분을 추출합니다.
-      const srcIndex = filePath.indexOf("/src/");
-      if (srcIndex === -1) return "unknown";
-      const relativePath = filePath.slice(srcIndex + 1); // "src/..." 형태
+      // 절대 경로 → appRoot 기준 상대 경로 (예: "api/src/...", "web/src/...")
+      const relativePath = path.relative(Sonamu.appRootPath, filePath);
+      if (relativePath.startsWith("..")) return "unknown";
 
       for (const fileType of fileTypes) {
-        if (minimatch(relativePath, checksumPatternGroup[fileType])) {
+        if (minimatch(relativePath, patternGroup[fileType])) {
           return fileType;
         }
       }
@@ -383,8 +357,38 @@ export class Syncer {
     }) as unknown as DiffGroups;
   }
 
-  async handleTruthSourceChanges(diffGroups: DiffGroups, diffTypes: string[]): Promise<void> {
-    Naite.t("handleTruthSourceChanges", { diffGroups, diffTypes });
+  private changeMatcher(diffTypes: FileType[], diffGroups: DiffGroups) {
+    const handled = new Set<FileType>();
+
+    /**
+     * 변경 사항이 인자로 받은 FileType들 중 하나 이상을 포함하는지 확인합니다.
+     * 가령 ["entity"]가 변경된 호출에서 changeMatches("entity")는 trye를 반환하며,
+     * ["types", "i18n"]이 변경된 호출에서 changeMatches("types", "functions")도 true를 반환하지만,
+     * ["functions"]가 변경된 호출에서 changeMatches("frame")은 false를 반환합니다.
+     * @param types
+     */
+    const changeMatches = (...types: FileType[]) => {
+      const matching = types.filter((t) => diffTypes.includes(t));
+      matching.forEach((t) => handled.add(t));
+      return matching.length > 0;
+    };
+
+    /**
+     * changeMatches로 매칭된 것이 하나도 없는지 여부를 가져옵니다.
+     */
+    const nothingMatches = () => handled.size === 0;
+
+    /**
+     * 어떤 changeMatches 호출에도 걸리지 않은 FileType들의 실제 파일 경로를 모아서 반환합니다.
+     */
+    const unhandledPaths = (): AbsolutePath[] =>
+      diffTypes.filter((t) => !handled.has(t)).flatMap((t) => diffGroups[t] ?? []);
+
+    return { changeMatches, nothingMatches, unhandledPaths };
+  }
+
+  async handleTruthSourceChanges(diffGroups: DiffGroups): Promise<void> {
+    Naite.t("handleTruthSourceChanges", { diffGroups });
 
     await EntityManager.reload();
 
@@ -394,54 +398,33 @@ export class Syncer {
     if (entityPath !== undefined) {
       const entityId = EntityManager.getEntityIdFromPath(entityPath);
       const entity = EntityManager.get(entityId);
+
       // 프로젝트에 생성되어야 하는 .ts 파일의 경로입니다.
       const typeFilePath = path.join(
         Sonamu.apiRootPath,
         `src/application/${entity.names.fs}/${entity.names.fs}.types.ts`,
-      );
+      ) as AbsolutePath;
+
       if (entity.parentId === undefined && !(await exists(typeFilePath))) {
-        await generateTemplate("init_types", { entityId });
+        // *.types.ts가 만들어집니다.
+        const types = await SyncerActions.actionGenerateInitialTypes(entityId);
+
+        // 그걸 타겟에 갖다둬요.
+        await SyncerActions.actionSyncFilesToTargets(types);
       }
     }
 
-    await SyncerActions.actionGenerateSchemas();
+    // sonamu.generated.ts가 만들어집니다.
+    const generated = await SyncerActions.actionGenerateSchemas();
 
-    diffGroups.generated = unique([
-      ...(diffGroups.generated ?? []),
-      path.join(Sonamu.apiRootPath, "src/application/sonamu.generated.ts") as AbsolutePath,
-    ]);
-    diffTypes.push("generated");
-  }
-
-  async handleSyncableFileChanges(diffGroups: DiffGroups): Promise<FileType[]> {
-    const tsPaths = unique([
-      ...(diffGroups.types ?? []),
-      ...(diffGroups.functions ?? []),
-      ...(diffGroups.generated ?? []),
-    ]);
-    Naite.t("handleSyncableFileChanges", { diffGroups });
-
-    // console.log(
-    //   chalk.gray(
-    //     `[Processing] Handling types/functions/generated changes: ${tsPaths.map((p) => path.relative(Sonamu.apiRootPath, p)).join(", ")}`
-    //   )
-    // );
-
-    await SyncerActions.actionSyncFilesToTargets(tsPaths);
-
-    return [];
+    // 그걸 target들에도 보내요.
+    await SyncerActions.actionSyncFilesToTargets(generated);
   }
 
   async handleImplementationChanges(diffGroups: DiffGroups): Promise<void> {
     Naite.t("handleImplementationChanges", { diffGroups });
     const mergedGroup = [...(diffGroups.model ?? []), ...(diffGroups.frame ?? [])];
 
-    // console.log(
-    //   chalk.gray(
-    //     `[Processing] Handling model/frame changes: ${mergedGroup.map((p) => path.relative(Sonamu.apiRootPath, p)).join(", ")}`
-    //   )
-    // );
-
     // generated_http.template.ts에서 syncer.types를 씁니다.
     // service.template.ts에서 syncer.apis를 씁니다.
     await this.autoloadModels();
@@ -461,9 +444,43 @@ export class Syncer {
       throw new Error("not reachable");
     });
 
+    // services.generated.ts를 target들에, sonamu.generated.http를 api에 만들어줘요.
     await SyncerActions.actionGenerateServices(params);
     await SyncerActions.actionGenerateHttps();
-    await SyncerActions.actionGenerateSsr();
+
+    // queries.generated.ts가 만들어집니다.
+    const queries = await SyncerActions.actionGenerateSsrQueries();
+
+    // 그걸 target들에도 보내요.
+    await SyncerActions.actionSyncFilesToTargets(queries);
+  }
+
+  async handleAuxiliarySymbolChanges(diffGroups: DiffGroups): Promise<void> {
+    Naite.t("handleAuxiliarySymbolChanges", { diffGroups });
+    const tsPaths = unique([...(diffGroups.types ?? []), ...(diffGroups.functions ?? [])]);
+    await SyncerActions.actionSyncFilesToTargets(tsPaths);
+  }
+
+  async handleConfigChanges(_: DiffGroups): Promise<void> {
+    await SyncerActions.actionSyncConfig();
+  }
+
+  async handleSonamuDictionaryRelatedChanges(_: DiffGroups): Promise<void> {
+    await SyncerActions.actionSyncSonamuDictionary();
+  }
+
+  async handleDrifts(drifts: AbsolutePath[]): Promise<void> {
+    if (drifts.length > 0) {
+      console.warn(
+        chalk.yellow(
+          "⚠️ Sonamu가 자동 생성한 파일에 대한 변경이 감지되었습니다. 파일이 Sonamu watcher 외부에서 변경된 것으로 추정됩니다.",
+        ),
+      );
+      for (const p of drifts) {
+        console.warn(chalk.yellow(`  - ${path.relative(Sonamu.appRootPath, p)}`));
+      }
+      console.warn(chalk.dim("  → `pnpm sonamu sync --force`를 권장합니다."));
+    }
   }
 
   /**
@@ -581,58 +598,4 @@ export class Syncer {
   async renewChecksums(): Promise<void> {
     return await renewChecksums();
   }
-
-  /**
-   * SD(Sonamu Dictionary) 템플릿을 생성합니다.
-   */
-  async syncSD(): Promise<void> {
-    const { targets } = Sonamu.config.sync;
-    const i18nConfig = Sonamu.config.i18n;
-
-    const targetList = ["api", ...targets] as ("api" | "web" | "app")[];
-
-    const apiI18nDir = path.join(Sonamu.appRootPath, Sonamu.config.api.dir, "src/i18n");
-
-    for (const target of targetList) {
-      try {
-        // web/app의 경우 locale 파일들을 api에서 복사
-        if (target !== "api") {
-          await this.syncLocaleFiles(target, apiI18nDir, i18nConfig.supportedLocales);
-        }
-
-        await generateTemplate("sd", { target }, { overwrite: true });
-      } catch (e) {
-        console.error(`Failed to generate SD template for ${target}:`, e);
-      }
-    }
-  }
-
-  /**
-   * api의 locale 파일을 web/app으로 복사합니다.
-   */
-  private async syncLocaleFiles(
-    target: string,
-    apiI18nDir: string,
-    locales: string[],
-  ): Promise<void> {
-    const targetI18nDir = path.join(Sonamu.appRootPath, target, "src/i18n");
-
-    // 디렉토리가 없으면 생성
-    await mkdir(targetI18nDir, { recursive: true });
-
-    for (const locale of locales) {
-      const sourceFile = path.join(apiI18nDir, `${locale}.ts`);
-      const targetFile = path.join(targetI18nDir, `${locale}.ts`);
-
-      const syncHeader = [
-        "/**",
-        " * @generated",
-        " * API에서 동기화된 파일입니다. 직접 수정하지 마세요.",
-        " */",
-      ].join("\n");
-      await copyFileWithReplaceCoreToShared(sourceFile, targetFile, syncHeader);
-      !isTest() &&
-        console.log(chalk.bold("Copied: ") + chalk.cyan(`${target}/src/i18n/${locale}.ts`));
-    }
-  }
 }