sonamu 0.10.11 → 0.10.13

package/src/bin/cli.ts

@@ -1,6 +1,6 @@
 import assert from "assert";
-import { execSync, spawn } from "child_process";
-import { mkdir, readdir, writeFile } from "fs/promises";
+import { spawn, spawnSync } from "child_process";
+import { mkdir, open, readFile, readdir, rm, writeFile } from "fs/promises";
 import { createRequire } from "module";
 import path from "path";
 import process from "process";
@@ -31,19 +31,88 @@ import { exists } from "../utils/fs-utils";
 import { findApiRootPath, findAppRootPath } from "../utils/utils";
 import { API_ARTIFACTS, WEB_ARTIFACTS } from "./build-config";
 import { type BuildArtifact } from "./build-config";
+import {
+  assertApiZodCompilerBuildOutput,
+  createApiZodCompilerBuildWrapper,
+  HTTP_VALIDATOR_REGISTRY_BUILD_PATH,
+  HTTP_VALIDATOR_REGISTRY_SOURCE_PATH,
+} from "./build-config";
+import { loadBuildCompilerPolicy } from "./compiler-policy";
 import { fixtureExploreCommand, fixtureFetchCommand, fixtureGenCommand } from "./fixture";
 import { getMigrateRunTargets } from "./migrate-targets";
 import { testCommand } from "./test-command";
 
 let migrator: Migrator;
 
+function runMysql(
+  args: string[],
+  stdio: [number | "ignore", number | "inherit", "inherit"] = ["ignore", "inherit", "inherit"],
+) {
+  const result = spawnSync("mysql", args, { stdio });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(`mysql 명령이 종료 코드 ${result.status ?? "unknown"}로 실패했습니다.`);
+  }
+}
+
+async function writeMysqlDump(args: string[], outputPath: string) {
+  const output = await open(outputPath, "w");
+  try {
+    const result = spawnSync("mysqldump", args, { stdio: ["ignore", output.fd, "inherit"] });
+    if (result.error) {
+      throw result.error;
+    }
+    if (result.status !== 0) {
+      throw new Error(`mysqldump 명령이 종료 코드 ${result.status ?? "unknown"}로 실패했습니다.`);
+    }
+  } finally {
+    await output.close();
+  }
+}
+
+async function runMysqlWithInput(args: string[], inputPath: string) {
+  const input = await open(inputPath, "r");
+  try {
+    runMysql(args, [input.fd, "inherit", "inherit"]);
+  } finally {
+    await input.close();
+  }
+}
+
+function openInCode(pathToOpen: string) {
+  const result = spawnSync("code", [pathToOpen], { stdio: ["ignore", "inherit", "inherit"] });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(`code 명령이 종료 코드 ${result.status ?? "unknown"}로 실패했습니다.`);
+  }
+}
+
+function mysqlConnectionArgs(connection: Knex.ConnectionConfig) {
+  return [
+    `-h${String(connection.host)}`,
+    `-u${String(connection.user)}`,
+    `-p${String(connection.password)}`,
+  ];
+}
+
+function copyToClipboard(value: string) {
+  const result = spawnSync("pbcopy", [], { input: value, stdio: ["pipe", "inherit", "inherit"] });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(`pbcopy 명령이 종료 코드 ${result.status ?? "unknown"}로 실패했습니다.`);
+  }
+}
+
 /**
  * CLI 옵션을 파싱하는 헬퍼 함수
  */
-function parseCliOptions(argv: string[] = process.argv): {
-  flags: Set<string>; // --regenerate, --ai, --no-cones 등
-  options: Record<string, string>; // --locale ko 등
-} {
+function parseCliOptions(argv: string[] = process.argv) {
   const flags = new Set<string>();
   const options: Record<string, string> = {};
 
@@ -388,8 +457,8 @@ async function dev_web() {
  * API 빌드 설정 파일 경로를 결정합니다.
  * 프로젝트 루트에 `tsdown.config.ts`가 있으면 그것을, 없으면 sonamu 기본 설정을 사용합니다.
  */
-async function resolveApiBuildConfigPath(): Promise<string> {
-  const localConfigPath = path.join(process.cwd(), "tsdown.config.ts");
+async function resolveApiBuildConfigPath(apiRootPath: string): Promise<string> {
+  const localConfigPath = path.join(apiRootPath, "tsdown.config.ts");
 
   try {
     if (await exists(localConfigPath)) {
@@ -421,22 +490,46 @@ async function build_all() {
  * Sonamu.init 없이 호출될 것을 상정하여 구현되었습니다.
  */
 async function build_api() {
-  const appRoot = findAppRootPath();
-  const configFilePath = await resolveApiBuildConfigPath();
+  const apiRootPath = findApiRootPath();
+  const baseConfigPath = await resolveApiBuildConfigPath(apiRootPath);
+  const policy = await loadBuildCompilerPolicy(apiRootPath);
+  const registryPath = path.join(apiRootPath, HTTP_VALIDATOR_REGISTRY_SOURCE_PATH);
+  const configFilePath = await createApiZodCompilerBuildWrapper({
+    apiRootPath,
+    baseConfigPath,
+    policy,
+    registryPath,
+  });
+  const temporaryConfigPath = configFilePath === baseConfigPath ? undefined : configFilePath;
 
   const apiStartedAt = Date.now();
   try {
     for (const artifact of API_ARTIFACTS) {
-      const cwd = path.join(appRoot, artifact.projectPath);
+      const cwd = apiRootPath;
       printTaskHeader(artifact.name, artifact.description, cwd);
 
       await runBuildSteps(artifact, { cwd, buildCommandArgs: { configFilePath } });
     }
+    if (policy.api === "aot") {
+      const outputPath = path.join(apiRootPath, HTTP_VALIDATOR_REGISTRY_BUILD_PATH);
+      if (!(await exists(outputPath))) {
+        throw new Error(`Built HTTP validator registry not found: ${outputPath}`);
+      }
+      assertApiZodCompilerBuildOutput([
+        {
+          code: await readFile(outputPath, "utf8"),
+          path: outputPath,
+        },
+      ]);
+    }
     printBuildSummary("API", true, Date.now() - apiStartedAt);
   } catch (e) {
     printBuildSummary("API", false, Date.now() - apiStartedAt);
-    console.error(e);
-    process.exit(1);
+    throw e;
+  } finally {
+    if (temporaryConfigPath !== undefined) {
+      await rm(temporaryConfigPath, { force: true });
+    }
   }
 }
 
@@ -527,7 +620,6 @@ async function start() {
     return;
   }
 
-  const { spawn } = await import("child_process");
   const serverProcess = spawn(
     process.execPath,
     ["--enable-source-maps", "-r", "dotenv/config", entryPoint],
@@ -554,12 +646,12 @@ async function setupFixtureManager() {
 
 async function migrate_apply(targets: (keyof SonamuDBConfig)[]) {
   await setupMigrator();
-  await migrator.runAction("apply", targets);
+  await migrator.apply(targets);
 }
 
 async function migrate_run() {
   await setupMigrator();
-  await migrator.runAction("apply", getMigrateRunTargets());
+  await migrator.apply(getMigrateRunTargets());
 }
 
 async function migrate_generate() {
@@ -597,7 +689,7 @@ async function migrate_status() {
 
 async function fixture_init() {
   const srcConfig = Sonamu.dbConfig[getSonamuEnvironment()];
-  const targets = [
+  const targets = /* SAFETY: CLI 파서와 빌드 도구 입력 계약이 이 값의 타입을 보장한다. */ [
     {
       label: "(REMOTE) Fixture DB",
       config: Sonamu.dbConfig.fixture,
@@ -606,8 +698,12 @@ async function fixture_init() {
       label: "(LOCAL) Testing DB",
       config: Sonamu.dbConfig.test,
       toSkip: (() => {
-        const remoteConn = Sonamu.dbConfig.fixture.connection as Knex.ConnectionConfig;
-        const localConn = Sonamu.dbConfig.test.connection as Knex.ConnectionConfig;
+        const remoteConn =
+          /* SAFETY: CLI 파서와 빌드 도구 입력 계약이 이 값의 타입을 보장한다. */ Sonamu.dbConfig
+            .fixture.connection as Knex.ConnectionConfig;
+        const localConn =
+          /* SAFETY: CLI 파서와 빌드 도구 입력 계약이 이 값의 타입을 보장한다. */ Sonamu.dbConfig
+            .test.connection as Knex.ConnectionConfig;
         return remoteConn.host === localConn.host && remoteConn.database === localConn.database;
       })(),
     },
@@ -620,35 +716,56 @@ async function fixture_init() {
   // 1. 기준DB 스키마를 덤프
   console.log("DUMP...");
   const dumpFilename = `/tmp/sonamu-fixture-init-${Date.now()}.sql`;
-  const srcConn = srcConfig.connection as Knex.ConnectionConfig;
+  const srcConn =
+    /* SAFETY: CLI 파서와 빌드 도구 입력 계약이 이 값의 타입을 보장한다. */ srcConfig.connection as Knex.ConnectionConfig;
   const migrationsDump = `/tmp/sonamu-fixture-init-migrations-${Date.now()}.sql`;
-  execSync(
-    `mysqldump -h${srcConn.host} -u${srcConn.user} -p${srcConn.password} --single-transaction -d --no-create-db --triggers ${srcConn.database} > ${dumpFilename}`,
+  await writeMysqlDump(
+    [
+      ...mysqlConnectionArgs(srcConn),
+      "--single-transaction",
+      "-d",
+      "--no-create-db",
+      "--triggers",
+      String(srcConn.database),
+    ],
+    dumpFilename,
   );
-  const _db = knex(srcConfig);
-  const [[migrations]] = await _db.raw(
+  const sourceDb = knex(srcConfig);
+  const [[migrations]] = await sourceDb.raw(
     "SELECT COUNT(*) as count FROM information_schema.tables WHERE table_schema = ? AND table_name = 'knex_migrations'",
     [srcConn.database],
   );
   if (migrations.count > 0) {
-    execSync(
-      `mysqldump -h${srcConn.host} -u${srcConn.user} -p${srcConn.password} --single-transaction --no-create-db --triggers ${srcConn.database} knex_migrations knex_migrations_lock > ${migrationsDump}`,
+    await writeMysqlDump(
+      [
+        ...mysqlConnectionArgs(srcConn),
+        "--single-transaction",
+        "--no-create-db",
+        "--triggers",
+        String(srcConn.database),
+        "knex_migrations",
+        "knex_migrations_lock",
+      ],
+      migrationsDump,
     );
   }
 
   // 2. 대상DB 각각에 대하여 존재여부 확인 후 붓기
   for (const { label, config, toSkip } of targets) {
-    const conn = config.connection as Knex.ConnectionConfig;
+    const conn =
+      /* SAFETY: CLI 파서와 빌드 도구 입력 계약이 이 값의 타입을 보장한다. */ config.connection as Knex.ConnectionConfig;
 
     if (toSkip === true) {
       console.log(chalk.red(`${label}: Skipped!`));
       continue;
     }
 
+    // SAFETY: Sonamu DB 구성은 Knex 연결 구성으로 검증된 뒤 이 명령에 전달된다.
+    const databaseConnection = (config.connection ?? {}) as Knex.ConnectionConfig;
     const db = knex({
       ...config,
       connection: {
-        ...((config.connection ?? {}) as Knex.ConnectionConfig),
+        ...databaseConnection,
         database: undefined,
       },
     });
@@ -660,18 +777,20 @@ async function fixture_init() {
     }
 
     console.log(`SYNC to ${label}...`);
-    const mysqlCmd = `mysql -h${conn.host} -u${conn.user} -p${conn.password}`;
-    execSync(`${mysqlCmd} -e 'DROP DATABASE IF EXISTS \`${conn.database}\`'`);
-    execSync(`${mysqlCmd} -e 'CREATE DATABASE \`${conn.database}\`'`);
-    execSync(`${mysqlCmd} ${conn.database} < ${dumpFilename}`);
+    const connectionArgs = mysqlConnectionArgs(conn);
+    const database = String(conn.database);
+    const escapedDatabase = database.replaceAll("`", "``");
+    runMysql([...connectionArgs, "-e", `DROP DATABASE IF EXISTS \`${escapedDatabase}\``]);
+    runMysql([...connectionArgs, "-e", `CREATE DATABASE \`${escapedDatabase}\``]);
+    await runMysqlWithInput([...connectionArgs, database], dumpFilename);
     if (await exists(migrationsDump)) {
-      execSync(`${mysqlCmd} ${conn.database} < ${migrationsDump}`);
+      await runMysqlWithInput([...connectionArgs, database], migrationsDump);
     }
 
     await db.destroy();
   }
 
-  await _db.destroy();
+  await sourceDb.destroy();
 }
 
 async function fixture_import(entityId: string, recordIds: number[]) {
@@ -799,14 +918,14 @@ async function stub_practice(name: string) {
   ].join("\n");
   await writeFile(dstPath, code);
 
-  execSync(`code ${dstPath}`);
+  openInCode(dstPath);
 
   const runCode = `yarn node -r dotenv/config --enable-source-maps dist/practices/${fileName.replace(
     ".ts",
     ".js",
   )}`;
   console.log(`${chalk.blue(runCode)} copied to clipboard.`);
-  execSync(`echo "${runCode}" | pbcopy`);
+  copyToClipboard(runCode);
 }
 
 async function stub_entity(entityId: string) {
@@ -822,7 +941,6 @@ async function stub_entity(entityId: string) {
     return;
   }
 
-  const { EntityManager } = await import("../entity/entity-manager");
   const entity = EntityManager.get(entityId);
   if (!entity) {
     console.error(`Entity not found: ${entityId}`);
@@ -879,7 +997,6 @@ async function stub_entity(entityId: string) {
  * ANTHROPIC_API_KEY 필요 (sonamu.secret.ts 또는 환경변수)
  */
 async function cone_gen(entityId: string) {
-  const { EntityManager } = await import("../entity/entity-manager");
   const { flags, options } = parseCliOptions();
 
   // --all 옵션: 모든 entity cone 생성

package/src/bin/compiler-policy.ts

@@ -0,0 +1,35 @@
+import { pathToFileURL } from "node:url";
+
+import { normalizeZodCompilerPolicy, type NormalizedZodCompilerPolicy } from "../api/config";
+import { applyCurrentSnapshotToProcessEnv } from "../env";
+import { isFunctionValue, isObjectValue } from "../utils/runtime-value";
+import { ensureTsLoaderRegistered } from "./ts-loader-registration";
+
+type BuildSourceConfig = {
+  validation?: {
+    zodCompiler?: unknown;
+  };
+};
+
+export async function loadBuildCompilerPolicy(
+  apiRootPath: string,
+): Promise<NormalizedZodCompilerPolicy> {
+  applyCurrentSnapshotToProcessEnv(apiRootPath);
+  await ensureTsLoaderRegistered(apiRootPath);
+
+  const configUrl = pathToFileURL(`${apiRootPath}/src/sonamu.config.ts`);
+  configUrl.searchParams.set("sonamu-build", `${Date.now()}-${Math.random()}`);
+  const imported =
+    /* SAFETY: CLI 파서와 빌드 도구 입력 계약이 이 값의 타입을 보장한다. */ (await import(
+      configUrl.href
+    )) as { default: unknown };
+  const configured = isFunctionValue(imported.default)
+    ? await Promise.resolve(imported.default())
+    : await Promise.resolve(imported.default);
+  if (!isObjectValue(configured) || configured === null || Array.isArray(configured)) {
+    throw new Error("sonamu.config.ts must export a configuration object");
+  }
+
+  const config: BuildSourceConfig = configured;
+  return normalizeZodCompilerPolicy(config.validation?.zodCompiler);
+}

package/src/bin/fixture.ts

@@ -1,5 +1,6 @@
 import chalk from "chalk";
 import prompts from "prompts";
+import { z } from "zod";
 
 import { Sonamu } from "../api/sonamu";
 import { DB } from "../database/db";
@@ -23,6 +24,16 @@ interface FixtureCommandOptions {
   "no-cache"?: boolean;
 }
 
+interface SignupBody {
+  name: string;
+  email: string;
+  username: string;
+  password: string;
+  display_username?: string;
+}
+
+const SignupErrorResponse = z.object({ code: z.string().optional() }).passthrough();
+
 /**
  * username을 일반적인 규칙(영문자 시작, 영문자/숫자만, 1-20자)에 맞도록 정규화합니다.
  */
@@ -162,7 +173,7 @@ export async function fixtureGenCommand(options: FixtureCommandOptions) {
           const displayUsername =
             userData.display_username !== undefined ? String(userData.display_username) : undefined;
 
-          const body: Record<string, unknown> = {
+          const body: SignupBody = {
             name,
             email,
             username,
@@ -181,8 +192,8 @@ export async function fixtureGenCommand(options: FixtureCommandOptions) {
           const response = await Sonamu.auth.handler(req);
 
           if (!response.ok) {
-            const responseData = (await response.json()) as Record<string, unknown>;
-            const code = typeof responseData.code === "string" ? responseData.code : undefined;
+            const responseData = SignupErrorResponse.parse(await response.json());
+            const code = responseData.code;
             if (code === "USER_ALREADY_EXISTS") {
               console.log(chalk.yellow(`  ⚠️  ${email} 이미 존재 - 건너뜁니다.`));
               continue;

package/src/bin/test-command.ts

@@ -2,17 +2,58 @@ import path from "node:path";
 
 import chalk from "chalk";
 
-import { type SonamuConfig } from "../api/config";
 import { loadConfig } from "../api/config";
 import { type RunResult, type TestCaseResult } from "../testing";
+import { isStringValue } from "../utils/runtime-value";
 import { findApiRootPath } from "../utils/utils";
 
-async function loadDevServerConfig(): Promise<SonamuConfig> {
+interface TestServerLocation {
+  host: string;
+  port: number;
+  routePrefix: string;
+  baseUrl: string;
+}
+
+interface TestRunPayload {
+  files?: string[];
+  pattern?: string;
+}
+
+type TestCommandConfig = {
+  server: {
+    listen?: {
+      host?: string;
+      port?: number;
+    };
+  };
+  test?: {
+    devRunner?: {
+      enabled?: boolean;
+      routePrefix?: string;
+    };
+  };
+};
+
+export interface TestCommandDependencies {
+  fetch: typeof globalThis.fetch;
+  findApiRootPath: typeof findApiRootPath;
+  loadConfig: (apiRootPath: string) => Promise<TestCommandConfig>;
+}
+
+const testCommandDependencies: TestCommandDependencies = {
+  fetch: globalThis.fetch,
+  findApiRootPath,
+  loadConfig,
+};
+
+async function loadDevServerConfig(
+  dependencies: TestCommandDependencies,
+): Promise<TestCommandConfig> {
   const prevVitest = process.env.VITEST;
   process.env.VITEST = "true";
   try {
-    const apiRootPath = findApiRootPath();
-    return await loadConfig(apiRootPath);
+    const apiRootPath = dependencies.findApiRootPath();
+    return await dependencies.loadConfig(apiRootPath);
   } finally {
     if (prevVitest === undefined) {
       delete process.env.VITEST;
@@ -22,22 +63,19 @@ async function loadDevServerConfig(): Promise<SonamuConfig> {
   }
 }
 
-function resolveTestBaseUrl(config: SonamuConfig): {
-  host: string;
-  port: number;
-  routePrefix: string;
-  baseUrl: string;
-} {
+function resolveTestBaseUrl(config: TestCommandConfig): TestServerLocation {
   const port = config.server.listen?.port ?? 3000;
   const host = config.server.listen?.host ?? "localhost";
   const routePrefix = config.test?.devRunner?.routePrefix ?? "/__test__";
   return { host, port, routePrefix, baseUrl: `http://${host}:${port}${routePrefix}` };
 }
 
-export async function testCommand(): Promise<void> {
+export async function testCommand(
+  dependencies: TestCommandDependencies = testCommandDependencies,
+): Promise<void> {
   const args = process.argv.slice(3);
 
-  const config = await loadDevServerConfig();
+  const config = await loadDevServerConfig(dependencies);
 
   // process.argv 파싱: sonamu test [file...] --pattern "이름" --traces --status
   const files: string[] = [];
@@ -59,7 +97,7 @@ export async function testCommand(): Promise<void> {
   }
 
   if (showStatus) {
-    return testStatusCommand(config);
+    return testStatusCommand(config, dependencies.fetch);
   }
 
   if (!config.test?.devRunner?.enabled) {
@@ -74,7 +112,7 @@ export async function testCommand(): Promise<void> {
   const { baseUrl } = resolveTestBaseUrl(config);
   const url = `${baseUrl}/run`;
 
-  const payload: { files?: string[]; pattern?: string } = {};
+  const payload: TestRunPayload = {};
   if (files.length > 0) {
     payload.files = files;
   }
@@ -83,7 +121,7 @@ export async function testCommand(): Promise<void> {
   }
 
   try {
-    const response = await fetch(url, {
+    const response = await dependencies.fetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(payload),
@@ -99,7 +137,10 @@ export async function testCommand(): Promise<void> {
     }
 
     if (response.status === 500) {
-      const errorBody = (await response.json()) as { error?: string };
+      const errorBody =
+        /* SAFETY: CLI 파서와 빌드 도구 입력 계약이 이 값의 타입을 보장한다. */ (await response.json()) as {
+          error?: string;
+        };
       console.error(chalk.red("Vitest 인스턴스가 아직 준비되지 않았습니다"));
       if (errorBody.error) {
         console.error(chalk.red(errorBody.error));
@@ -112,7 +153,8 @@ export async function testCommand(): Promise<void> {
       process.exit(1);
     }
 
-    const result = (await response.json()) as RunResult;
+    const result =
+      /* SAFETY: CLI 파서와 빌드 도구 입력 계약이 이 값의 타입을 보장한다. */ (await response.json()) as RunResult;
 
     const { passed, failed: failedCount, total, durationMs } = result.summary;
     const passedStr = chalk.green(`${passed} passed`);
@@ -141,10 +183,9 @@ export async function testCommand(): Promise<void> {
           console.log(`  ${chalk.dim(path.basename(file))}`);
           for (const trace of traces) {
             const loc = `${path.basename(trace.filePath)}:${trace.lineNumber}`;
-            const valueStr =
-              typeof trace.value === "string"
-                ? trace.value
-                : (JSON.stringify(trace.value, null, 2) ?? "undefined");
+            const valueStr = isStringValue(trace.value)
+              ? trace.value
+              : (JSON.stringify(trace.value, null, 2) ?? "undefined");
             console.log(`\n    ${chalk.yellow(`[${trace.key}]`)} ${chalk.dim(loc)}`);
             const indented = valueStr.split("\n").join("\n    ");
             console.log(`    ${indented}`);
@@ -195,7 +236,10 @@ function collectTracesFromResults(
   return result;
 }
 
-async function testStatusCommand(config: SonamuConfig): Promise<void> {
+async function testStatusCommand(
+  config: TestCommandConfig,
+  fetchRequest: typeof globalThis.fetch,
+): Promise<void> {
   if (!config.test?.devRunner?.enabled) {
     console.error(
       chalk.red(
@@ -209,19 +253,20 @@ async function testStatusCommand(config: SonamuConfig): Promise<void> {
   const url = `${baseUrl}/status`;
 
   try {
-    const response = await fetch(url);
+    const response = await fetchRequest(url);
 
     if (!response.ok) {
       console.error(chalk.red(`예상하지 못한 응답: ${response.status}`));
       process.exit(1);
     }
 
-    const status = (await response.json()) as {
-      ready: boolean;
-      running: boolean;
-      lastRunAt: string | null;
-      sseAvailable: boolean;
-    };
+    const status =
+      /* SAFETY: CLI 파서와 빌드 도구 입력 계약이 이 값의 타입을 보장한다. */ (await response.json()) as {
+        ready: boolean;
+        running: boolean;
+        lastRunAt: string | null;
+        sseAvailable: boolean;
+      };
 
     console.log(chalk.bold("DevRunner 상태:"));
     console.log(`  ready:        ${status.ready ? chalk.green("true") : chalk.red("false")}`);

package/src/bin/ts-loader-registration.ts

@@ -13,8 +13,23 @@ type GlobalWithTsLoaderRegisterState = typeof globalThis & {
   [tsLoaderRegisterStateKey]?: TsLoaderRegisterState;
 };
 
+export interface TsLoaderRegistrationDependencies {
+  registerLoader: (specifier: string, options: { parentURL: string }) => void;
+  resolveLoaderPath: () => string;
+}
+
+const tsLoaderRegistrationDependencies: TsLoaderRegistrationDependencies = {
+  registerLoader(specifier, options) {
+    register(specifier, options);
+  },
+  resolveLoaderPath() {
+    return require.resolve("@sonamu-kit/ts-loader/loader");
+  },
+};
+
 function getTsLoaderRegisterState(): TsLoaderRegisterState {
-  const globalState = globalThis as GlobalWithTsLoaderRegisterState;
+  const globalState =
+    /* SAFETY: CLI 파서와 빌드 도구 입력 계약이 이 값의 타입을 보장한다. */ globalThis as GlobalWithTsLoaderRegisterState;
 
   if (!globalState[tsLoaderRegisterStateKey]) {
     globalState[tsLoaderRegisterStateKey] = { registered: false };
@@ -23,16 +38,19 @@ function getTsLoaderRegisterState(): TsLoaderRegisterState {
   return globalState[tsLoaderRegisterStateKey];
 }
 
-export async function ensureTsLoaderRegistered(apiRoot: string): Promise<void> {
+export async function ensureTsLoaderRegistered(
+  apiRoot: string,
+  dependencies: TsLoaderRegistrationDependencies = tsLoaderRegistrationDependencies,
+): Promise<void> {
   const state = getTsLoaderRegisterState();
   if (state.registered) {
     return;
   }
 
   void apiRoot;
-  const loaderPath = require.resolve("@sonamu-kit/ts-loader/loader");
+  const loaderPath = dependencies.resolveLoaderPath();
 
-  register(pathToFileURL(loaderPath).href, {
+  dependencies.registerLoader(pathToFileURL(loaderPath).href, {
     parentURL: import.meta.url,
   });
   state.registered = true;