sonamu 0.7.53 → 0.8.0

package/src/testing/fixture-generator.ts

@@ -0,0 +1,1166 @@
+import chalk from "chalk";
+import type { Knex } from "knex";
+import type { Entity } from "../entity/entity";
+import type { EntityManager } from "../entity/entity-manager";
+import type { EntityProp, FixtureImportResult, FixtureRecord } from "../types/types";
+import { isBelongsToOneRelationProp, isOneToOneRelationProp, isRelationProp } from "../types/types";
+import {
+  DataExplorer,
+  type ExploreWithRelationsOptions,
+  type ExploreWithRelationsResult,
+} from "./data-explorer";
+import { type FakerMappings, fakerMappings } from "./faker-mappings";
+import { FixtureManager } from "./fixture-manager";
+
+export type Locale = "ko" | "en" | "ja";
+
+export type FixtureGeneratorOptions = {
+  locale?: Locale;
+  useLLM?: boolean;
+  enableLLMCache?: boolean;
+  llmModel?: string;
+};
+
+export type GeneratorContext = {
+  /** 생성 중인 fixture들 (메모리 상) */
+  fixtures: Map<string, Record<string, unknown>>;
+
+  /** 참조 데이터 캐시 (DataExplorer 결과) */
+  referenceCache: Map<string, Record<string, unknown>[]>;
+
+  /** 이미 import된 레코드를 추적하여 중복 import를 방지합니다 */
+  importedRecords: Set<string>; // "User#123"
+};
+
+export class FixtureGenerator {
+  private dataExplorer: DataExplorer;
+  private locale: Locale;
+  private mappings: FakerMappings;
+  private llmCache: Map<string, unknown> = new Map();
+  private options: FixtureGeneratorOptions;
+
+  constructor(
+    private sourceDb: Knex,
+    // FixtureManager.insertFixtures가 dbName 문자열을 받기 때문에 직접 사용하지 않습니다
+    // 미래 확장성을 위해 API 시그니처에는 포함시켰습니다
+    _targetDb: Knex,
+    private targetDbName: "fixture" | "test" | "production_master",
+    private entityManager: typeof EntityManager,
+    options?: FixtureGeneratorOptions,
+  ) {
+    this.dataExplorer = new DataExplorer(sourceDb, entityManager);
+    this.locale = options?.locale || "ko";
+    this.mappings = fakerMappings;
+    this.options = {
+      locale: options?.locale || "ko",
+      useLLM: options?.useLLM || false,
+      enableLLMCache: options?.enableLLMCache !== false,
+      llmModel: options?.llmModel || "claude-sonnet-4-5",
+    };
+  }
+
+  /**
+   * Fixture 생성 (단일)
+   * @returns 생성된 fixture 데이터 (메모리 상)
+   */
+  async generate(
+    entityName: string,
+    overrides: Record<string, unknown> = {},
+    context: GeneratorContext = this.createContext(),
+  ): Promise<Record<string, unknown>> {
+    const entity = this.entityManager.get(entityName);
+    const tempId = `${entityName}#temp#${Date.now()}`; // 임시 ID
+
+    // 각 prop별 값 생성
+    const fixture: Record<string, unknown> = {};
+
+    for (const prop of entity.props) {
+      // Virtual prop은 스킵
+      if ("virtual" in prop && prop.virtual) {
+        continue;
+      }
+
+      // override가 있으면 사용
+      if (prop.name in overrides) {
+        fixture[prop.name] = overrides[prop.name];
+        continue;
+      }
+
+      // cone에서 생성 전략 확인
+      const cone = prop.cone;
+
+      // 1. Relation prop 처리
+      if (isRelationProp(prop)) {
+        const relationValue = await this.generateRelationValue(entity, prop, context);
+        // BelongsToOne, OneToOne(hasJoinColumn)의 경우 foreign key 컬럼명으로 저장
+        if (
+          isBelongsToOneRelationProp(prop) ||
+          (isOneToOneRelationProp(prop) && prop.hasJoinColumn)
+        ) {
+          fixture[`${prop.name}_id`] = relationValue;
+        } else {
+          fixture[prop.name] = relationValue;
+        }
+        continue;
+      }
+
+      // 2. fixtureGenerator 사용
+      if (cone?.fixtureGenerator) {
+        fixture[prop.name] = await this.executeGenerator(
+          cone.fixtureGenerator as string,
+          prop,
+          entity,
+        );
+        continue;
+      }
+
+      // 2.5. fixtureHint + LLM 사용
+      if (cone?.fixtureHint && this.options.useLLM) {
+        try {
+          fixture[prop.name] = await this.generateWithLLM(cone.fixtureHint, prop, entity);
+          continue;
+        } catch (error) {
+          console.warn(
+            `[FixtureGenerator] LLM generation failed for ${entity.id}.${prop.name}, falling back to default`,
+            error instanceof Error ? error.message : error,
+          );
+          // fallback: fixtureDefault 또는 기본값으로 계속
+        }
+      }
+
+      // 3. fixtureDefault 사용
+      if (cone?.fixtureDefault !== undefined) {
+        fixture[prop.name] = cone.fixtureDefault;
+        continue;
+      }
+
+      // 4. 타입별 기본 생성
+      fixture[prop.name] = await this.generateDefaultValue(prop, entity);
+    }
+
+    // 5. password 필드 암호화
+    if ("password" in fixture && fixture.password && typeof fixture.password === "string") {
+      const bcrypt = await import("bcrypt");
+      fixture.password = await bcrypt.hash(fixture.password, 10);
+    }
+
+    context.fixtures.set(tempId, fixture);
+    return fixture;
+  }
+
+  /**
+   * Relation 값 생성 + 자동 Import
+   */
+  private async generateRelationValue(
+    entity: Entity,
+    prop: EntityProp,
+    context: GeneratorContext,
+  ): Promise<number | null> {
+    if (!isRelationProp(prop)) {
+      throw new Error(`FixtureGenerator: ${entity.id}.${prop.name} is not a relation prop`);
+    }
+
+    // BelongsToOne, OneToOne(hasJoinColumn)만 처리
+    if (
+      !isBelongsToOneRelationProp(prop) &&
+      !(isOneToOneRelationProp(prop) && prop.hasJoinColumn)
+    ) {
+      return null;
+    }
+
+    const cone = prop.cone;
+    const dataSource = cone?.dataSource;
+
+    // DataExplorer로 참조 데이터 조회 (sourceDb)
+    // 관계 체인을 따라가기 위해 exploreWithRelations 사용
+    if (dataSource) {
+      const cacheKey = `${prop.with}:${JSON.stringify(dataSource)}`;
+
+      if (!context.referenceCache.has(cacheKey)) {
+        const exploreResult = await this.dataExplorer.exploreWithRelations(prop.with, {
+          strategy: dataSource.strategy,
+          limit:
+            ((dataSource.config as Record<string, unknown> | undefined)?.limit as
+              | number
+              | undefined) || 10,
+          includeRelations: true,
+          maxDepth: 3,
+          ...(dataSource.config as Record<string, unknown> | undefined),
+        });
+        context.referenceCache.set(cacheKey, exploreResult.main.records);
+
+        // 조회한 데이터와 관계된 모든 엔티티를 targetDb에 import
+        await this.importExploreResult(exploreResult, context);
+      }
+
+      const candidates = context.referenceCache.get(cacheKey);
+      if (candidates && candidates.length > 0) {
+        // 랜덤하게 하나 선택
+        const selected = candidates[Math.floor(Math.random() * candidates.length)];
+        return selected.id as number;
+      }
+    }
+
+    // dataSource가 없을 때 자동으로 fixture DB에서 조회 시도
+    // 관계 체인을 따라가기 위해 exploreWithRelations 사용
+    const autoKey = `${prop.with}:auto`;
+    if (!context.referenceCache.has(autoKey)) {
+      // fixture DB(sourceDb)에서 자동 조회 (관계 포함)
+      const autoExploreResult = await this.dataExplorer.exploreWithRelations(prop.with, {
+        strategy: "random",
+        limit: 10,
+        includeRelations: true,
+        maxDepth: 3,
+      });
+      context.referenceCache.set(autoKey, autoExploreResult.main.records);
+
+      // 조회한 데이터와 관계된 모든 엔티티를 targetDb에 import
+      if (autoExploreResult.main.records.length > 0) {
+        await this.importExploreResult(autoExploreResult, context);
+      }
+    }
+
+    const autoCandidates = context.referenceCache.get(autoKey);
+    if (autoCandidates && autoCandidates.length > 0) {
+      // 랜덤하게 하나 선택
+      const selected = autoCandidates[Math.floor(Math.random() * autoCandidates.length)];
+      return selected.id as number;
+    }
+
+    // 참조 데이터가 없으면 null 반환 (nullable인 경우)
+    if (prop.nullable) {
+      return null;
+    }
+
+    // nullable이 아니고 데이터도 없으면 에러
+    throw new Error(
+      `FixtureGenerator: ${entity.id}.${prop.name}에 필요한 ${prop.with} 데이터가 없습니다. ` +
+        `먼저 ${prop.with}를 생성하거나 cone.dataSource를 설정하세요.`,
+    );
+  }
+
+  /**
+   * ExploreWithRelations 결과를 targetDb에 import
+   *
+   * 관계 체인을 따라간 결과(main + related)를 모두 import합니다.
+   * 의존성 순서는 FixtureManager.insertFixtures가 자동으로 처리합니다.
+   */
+  private async importExploreResult(
+    exploreResult: ExploreWithRelationsResult,
+    context: GeneratorContext,
+  ): Promise<void> {
+    const allFixtureRecords: FixtureRecord[] = [];
+
+    // 1. Related entities import (Company, Department 등)
+    for (const [entityId, records] of exploreResult.related.entries()) {
+      const entity = this.entityManager.get(entityId);
+      const recordsToImport: Record<string, unknown>[] = [];
+
+      console.log(chalk.cyan(`Importing related entity: ${entityId} (${records.length} records)`));
+
+      for (const record of records) {
+        const recordKey = `${entityId}#${record.id}`;
+        if (!context.importedRecords.has(recordKey)) {
+          recordsToImport.push(record);
+          context.importedRecords.add(recordKey);
+        }
+      }
+
+      if (recordsToImport.length > 0) {
+        for (const record of recordsToImport) {
+          console.log(
+            chalk.gray(`  - Processing ${entityId} record:`, JSON.stringify(record).slice(0, 100)),
+          );
+          const fixtureRecords = await FixtureManager.createFixtureRecord(
+            entity,
+            record as { id: number | string; [key: string]: string | number | boolean | null },
+            { _db: this.sourceDb, singleRecord: true },
+          );
+          allFixtureRecords.push(...fixtureRecords);
+        }
+      }
+    }
+
+    // 2. Main entity import (Employee 등)
+    const mainEntity = this.entityManager.get(exploreResult.main.entityId);
+    const mainRecordsToImport: Record<string, unknown>[] = [];
+
+    console.log(
+      chalk.cyan(
+        `Importing main entity: ${exploreResult.main.entityId} (${exploreResult.main.records.length} records)`,
+      ),
+    );
+
+    for (const record of exploreResult.main.records) {
+      const recordKey = `${exploreResult.main.entityId}#${record.id}`;
+      if (!context.importedRecords.has(recordKey)) {
+        mainRecordsToImport.push(record);
+        context.importedRecords.add(recordKey);
+      }
+    }
+
+    if (mainRecordsToImport.length > 0) {
+      for (const record of mainRecordsToImport) {
+        console.log(
+          chalk.gray(
+            `  - Processing ${exploreResult.main.entityId} record:`,
+            JSON.stringify(record).slice(0, 100),
+          ),
+        );
+        const fixtureRecords = await FixtureManager.createFixtureRecord(
+          mainEntity,
+          record as { id: number | string; [key: string]: string | number | boolean | null },
+          { _db: this.sourceDb, singleRecord: true },
+        );
+        allFixtureRecords.push(...fixtureRecords);
+      }
+    }
+
+    // 3. 모든 fixture를 한 번에 삽입 (의존성 순서 자동 처리)
+    if (allFixtureRecords.length > 0) {
+      await FixtureManager.insertFixtures(this.targetDbName, allFixtureRecords);
+
+      console.log(
+        chalk.green(
+          `Auto-imported ${exploreResult.main.entityId} with relations: ` +
+            `${exploreResult.main.records.length} main + ${exploreResult.related.size} related entities`,
+        ),
+      );
+    }
+  }
+
+  /**
+   * fixtureGenerator 실행 (Faker.js만 지원)
+   *
+   * faker.* 형식의 표현식을 안전하게 파싱하여 실행합니다.
+   * 예: "faker.internet.email()" → faker.internet.email()
+   * 예: "faker.lorem.words(3)" → faker.lorem.words(3)
+   */
+  private async executeGenerator(
+    generator: string,
+    prop: EntityProp,
+    entity: Entity,
+  ): Promise<unknown> {
+    // Faker.js 표현식만 지원
+    if (generator.startsWith("faker.")) {
+      // username이나 name 필드는 한국어 faker 사용
+      const isNameField = prop.name === "username" || prop.name === "name";
+      const fakerModule = await import("@faker-js/faker");
+      const faker = isNameField ? fakerModule.fakerKO : fakerModule.faker;
+      const expr = generator.slice(6); // "faker." 제거
+
+      try {
+        // 함수 경로와 인자 파싱
+        const match = expr.match(/^([\w.]+)(?:\((.*?)\))?$/);
+        if (!match) {
+          throw new Error(
+            `FixtureGenerator: Invalid faker expression for ${prop.name}: ${generator}`,
+          );
+        }
+
+        const [, path, argsStr] = match;
+        const parts = path.split(".");
+
+        // faker 객체에서 함수 찾기
+        let fn: unknown = faker;
+        for (const part of parts) {
+          if (typeof fn === "object" && fn !== null && part in fn) {
+            fn = (fn as Record<string, unknown>)[part];
+          } else {
+            throw new Error(`FixtureGenerator: Invalid faker path for ${prop.name}: faker.${path}`);
+          }
+        }
+
+        // 함수가 아니면 에러
+        if (typeof fn !== "function") {
+          throw new Error(`FixtureGenerator: faker.${path} is not a function (for ${prop.name})`);
+        }
+
+        // 인자 파싱 (JSON 형식만 지원)
+        let args: unknown[] = [];
+        if (argsStr?.trim()) {
+          try {
+            // JSON 배열로 파싱 시도
+            const parsed = JSON.parse(`[${argsStr}]`) as unknown;
+            args = Array.isArray(parsed) ? parsed : [parsed];
+          } catch {
+            // 숫자나 문자열 단일 인자 처리
+            const trimmed = argsStr.trim();
+            if (!Number.isNaN(Number(trimmed))) {
+              args = [Number(trimmed)];
+            } else if (
+              (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+              (trimmed.startsWith("'") && trimmed.endsWith("'"))
+            ) {
+              args = [trimmed.slice(1, -1)];
+            } else {
+              throw new Error(
+                `FixtureGenerator: Cannot parse arguments for ${prop.name}: ${argsStr}`,
+              );
+            }
+          }
+        }
+
+        return fn(...args);
+      } catch (error) {
+        console.log(
+          chalk.yellow(
+            `Failed to execute generator "${generator}" for ${prop.name}, falling back to default:`,
+          ),
+          error,
+        );
+        return this.generateDefaultValue(prop, entity);
+      }
+    }
+
+    // faker 이외의 표현식은 지원하지 않음
+    console.log(
+      chalk.yellow(
+        `Unsupported generator expression for ${prop.name}: ${generator}. Only faker.* expressions are supported. Using default value.`,
+      ),
+    );
+    return this.generateDefaultValue(prop, entity);
+  }
+
+  /**
+   * 필드의 타입과 이름을 분석하여 적절한 기본값을 생성합니다.
+   *
+   * 우선순위:
+   * 1. 필드명 패턴 매칭 (salary, budget 등 의미있는 데이터)
+   * 2. 특수 케이스 (Department name 등 도메인 지식)
+   * 3. 배열 타입 (JSON 배열)
+   * 4. Enum 타입
+   * 5. 타입별 기본값
+   */
+  private async generateDefaultValue(prop: EntityProp, entity?: Entity): Promise<unknown> {
+    const fakerModule = await import("@faker-js/faker");
+    const faker = fakerModule.faker;
+    const fakerKO = fakerModule.fakerKO;
+    const fakerJA = fakerModule.fakerJA;
+
+    const localeFaker = this.locale === "ko" ? fakerKO : this.locale === "ja" ? fakerJA : faker;
+
+    /**
+     * 1. 필드명에서 의미를 추론하여 현실적인 데이터를 생성합니다.
+     * 예: salary → 30M~150M (한국 연봉 범위)
+     *     budget → 10M~500M (프로젝트 예산 범위)
+     */
+    const localeMappings = this.mappings[this.locale] || this.mappings.en;
+    const normalizedName = prop.name.toLowerCase().replace(/_/g, "");
+
+    for (const [pattern, config] of Object.entries(localeMappings.field_patterns)) {
+      if (normalizedName.includes(pattern.toLowerCase())) {
+        try {
+          return await this.executeFakerExpression(config.faker, prop);
+        } catch (error) {
+          console.log(
+            chalk.yellow(
+              `Failed to execute field pattern "${pattern}" for ${prop.name}, falling back:`,
+            ),
+            error,
+          );
+          break;
+        }
+      }
+    }
+
+    /**
+     * 2. Department name은 한국어 부서명 목록에서 선택합니다.
+     * 고유성을 위해 70% 확률로 prefix/suffix를 추가합니다.
+     */
+    if (entity?.id === "Department" && prop.name === "name") {
+      const departments = [
+        "개발팀",
+        "기획팀",
+        "마케팅팀",
+        "영업팀",
+        "인사팀",
+        "총무팀",
+        "재무팀",
+        "회계팀",
+        "법무팀",
+        "디자인팀",
+        "IT팀",
+        "고객지원팀",
+        "품질관리팀",
+        "연구개발팀",
+        "생산팀",
+        "구매팀",
+        "물류팀",
+      ];
+      const prefixes = ["신규", "통합", "전략", "글로벌", "디지털", "핵심"];
+      const suffixes = ["1팀", "2팀", "3팀", "A팀", "B팀", "본부", "센터", "그룹"];
+
+      const dept = faker.helpers.arrayElement(departments);
+
+      const random = Math.random();
+      if (random > 0.7) {
+        const prefix = faker.helpers.arrayElement(prefixes);
+        return `${prefix} ${dept}`;
+      }
+      if (random > 0.4) {
+        const suffix = faker.helpers.arrayElement(suffixes);
+        return `${dept} ${suffix}`;
+      }
+      return dept;
+    }
+
+    /**
+     * 3. JSON 타입이면서 배열인 경우 (SonamuFile[], string[] 등)
+     * 필드명 패턴을 보고 적절한 배열 데이터를 생성합니다.
+     */
+    if (prop.type === "json" && "id" in prop && prop.id) {
+      if (prop.id.endsWith("[]")) {
+        return this.generateArrayValue(prop, entity, faker, localeFaker);
+      }
+    }
+
+    /** 4. Enum 타입은 정의된 값 중 하나를 랜덤 선택합니다 */
+    if (prop.type === "enum") {
+      let enumValues: string[] = [];
+
+      if ("enum" in prop && Array.isArray(prop.enum) && prop.enum.length > 0) {
+        enumValues = prop.enum;
+      } else if ("id" in prop && prop.id && entity?.enumLabels?.[prop.id]) {
+        enumValues = Object.keys(entity.enumLabels[prop.id]);
+      }
+
+      if (enumValues.length > 0) {
+        return faker.helpers.arrayElement(enumValues);
+      }
+      return prop.nullable ? null : "UNKNOWN";
+    }
+
+    if (prop.type === "enum[]") {
+      let enumValues: string[] = [];
+
+      if ("enum" in prop && Array.isArray(prop.enum) && prop.enum.length > 0) {
+        enumValues = prop.enum;
+      } else if ("id" in prop && prop.id && entity?.enumLabels?.[prop.id]) {
+        enumValues = Object.keys(entity.enumLabels[prop.id]);
+      }
+
+      if (enumValues.length > 0) {
+        return [faker.helpers.arrayElement(enumValues)];
+      }
+      return [];
+    }
+
+    /**
+     * 5. Vector 타입은 현재 지원하지 않으므로 null을 반환합니다.
+     * 향후 AI embedding 생성 기능 추가 시 구현 예정입니다.
+     */
+    if (prop.type === "vector" || prop.type === "vector[]" || prop.type === "tsvector") {
+      return null;
+    }
+
+    /** 6. 타입별 기본 Faker 표현식을 실행합니다 */
+    const typeDefault = localeMappings.type_defaults[prop.type];
+    if (typeDefault) {
+      try {
+        return await this.executeFakerExpression(typeDefault.faker, prop);
+      } catch (error) {
+        console.log(
+          chalk.yellow(`Failed to execute type default for ${prop.type}, using fallback:`, error),
+        );
+      }
+    }
+
+    /** 7. 매핑되지 않은 타입은 기본 Faker 함수로 처리합니다 */
+    switch (prop.type) {
+      case "string":
+      case "string[]":
+        return faker.lorem.words(3);
+      case "integer":
+        return faker.number.int({ min: 1, max: 1000 });
+      case "integer[]":
+        return [faker.number.int({ min: 1, max: 1000 })];
+      case "bigInteger":
+        return faker.number.bigInt({ min: 1n, max: 1000n });
+      case "bigInteger[]":
+        return [faker.number.bigInt({ min: 1n, max: 1000n })];
+      case "number":
+      case "numeric":
+        return faker.number.float({ min: 0, max: 1000 });
+      case "number[]":
+      case "numeric[]":
+        return [faker.number.float({ min: 0, max: 1000 })];
+      case "boolean":
+        return faker.datatype.boolean();
+      case "boolean[]":
+        return [faker.datatype.boolean()];
+      case "date":
+      case "date[]":
+        return faker.date.past();
+      case "json":
+        return {};
+      case "uuid":
+      case "uuid[]":
+        return faker.string.uuid();
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * 배열 타입의 값을 생성합니다.
+   *
+   * 타입 ID와 필드명 패턴을 분석하여 적절한 배열 데이터를 생성합니다.
+   * 예: image_urls → [{url, name, mime_type}, ...]
+   *     tag_ids → [1, 23, 45]
+   */
+  private generateArrayValue(
+    prop: EntityProp,
+    _entity: Entity | undefined,
+    faker: typeof import("@faker-js/faker").faker,
+    _localeFaker: typeof import("@faker-js/faker").faker,
+  ): unknown[] {
+    const count = faker.number.int({ min: 1, max: 3 });
+
+    /** SonamuFile[]은 Sonamu 내장 타입으로 구조가 정해져 있습니다 */
+    if ("id" in prop && prop.id === "SonamuFile[]") {
+      return Array.from({ length: count }, () => ({
+        url: faker.image.url(),
+        name: faker.system.fileName(),
+        mime_type: faker.helpers.arrayElement([
+          "image/jpeg",
+          "image/png",
+          "image/gif",
+          "application/pdf",
+        ]),
+      }));
+    }
+
+    /** 필드명에서 배열의 용도를 추론합니다 */
+    const normalizedName = prop.name.toLowerCase().replace(/_/g, "");
+
+    if (normalizedName.includes("url") || normalizedName.includes("image")) {
+      return Array.from({ length: count }, () => faker.internet.url());
+    }
+
+    if (normalizedName.includes("id") && normalizedName.endsWith("s")) {
+      return Array.from({ length: count }, () => faker.number.int({ min: 1, max: 100 }));
+    }
+
+    if (normalizedName.includes("tag") || normalizedName.includes("name")) {
+      return Array.from({ length: count }, () => faker.lorem.word());
+    }
+
+    /** 패턴 매칭되지 않으면 빈 배열을 반환합니다 */
+    return [];
+  }
+
+  /**
+   * JSON 매핑의 Faker 표현식을 파싱하여 실행합니다.
+   *
+   * 표현식 예시:
+   * - "faker.internet.email()" → 인자 없음
+   * - "faker.number.int({ min: 1, max: 100 })" → JSON 인자
+   * - "{}" → 리터럴 값 (JSON.parse)
+   *
+   * fakerKO, fakerJA도 지원하여 다국어 데이터를 생성합니다.
+   */
+  private async executeFakerExpression(expression: string, prop: EntityProp): Promise<unknown> {
+    const fakerModule = await import("@faker-js/faker");
+    const faker = fakerModule.faker;
+    const fakerKO = fakerModule.fakerKO;
+    const fakerJA = fakerModule.fakerJA;
+
+    /** Faker 표현식이 아닌 리터럴 값은 JSON으로 파싱합니다 */
+    if (!expression.startsWith("faker")) {
+      try {
+        return JSON.parse(expression);
+      } catch {
+        return expression;
+      }
+    }
+
+    /** 표현식에서 Faker 객체와 경로를 추출합니다 */
+    const match = expression.match(/^(faker|fakerKO|fakerJA)\.(.*?)$/);
+    if (!match) {
+      throw new Error(`Invalid faker expression: ${expression}`);
+    }
+
+    const [, fakerName, expr] = match;
+    const selectedFaker =
+      fakerName === "fakerKO" ? fakerKO : fakerName === "fakerJA" ? fakerJA : faker;
+
+    const funcMatch = expr.match(/^([\w.]+)(?:\((.*?)\))?$/);
+    if (!funcMatch) {
+      throw new Error(`Invalid faker expression for ${prop.name}: ${expression}`);
+    }
+
+    const [, path, argsStr] = funcMatch;
+    const parts = path.split(".");
+
+    /** 점 표기법(dot notation)으로 Faker 함수를 찾아갑니다 */
+    let fn: unknown = selectedFaker;
+    for (const part of parts) {
+      if (typeof fn === "object" && fn !== null && part in fn) {
+        fn = (fn as Record<string, unknown>)[part];
+      } else {
+        throw new Error(`Invalid faker path for ${prop.name}: ${fakerName}.${path}`);
+      }
+    }
+
+    if (typeof fn !== "function") {
+      throw new Error(`${fakerName}.${path} is not a function (for ${prop.name})`);
+    }
+
+    /** 함수 인자를 JSON으로 파싱합니다 */
+    let args: unknown[] = [];
+    if (argsStr?.trim()) {
+      try {
+        const parsed = JSON.parse(`[${argsStr}]`) as unknown;
+        args = Array.isArray(parsed) ? parsed : [parsed];
+      } catch {
+        /** JSON 파싱 실패 시 단순 숫자/문자열로 시도합니다 */
+        const trimmed = argsStr.trim();
+        if (!Number.isNaN(Number(trimmed))) {
+          args = [Number(trimmed)];
+        } else if (
+          (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+          (trimmed.startsWith("'") && trimmed.endsWith("'"))
+        ) {
+          args = [trimmed.slice(1, -1)];
+        } else {
+          throw new Error(`Cannot parse arguments for ${prop.name}: ${argsStr}`);
+        }
+      }
+    }
+
+    return fn(...args);
+  }
+
+  /**
+   * fixtureHint를 LLM에게 전달하여 현실적인 테스트 데이터를 생성합니다.
+   *
+   * faker.js로는 생성하기 어려운 복잡한 텍스트(자기소개, 설명문 등)를
+   * LLM을 활용하여 생성합니다. 동일한 hint에 대한 중복 호출을 방지하기 위해
+   * 캐싱을 기본으로 지원합니다 (LLM API 비용 절감).
+   *
+   * ai 패키지는 dynamic import로 불러오므로, useLLM이 false인 경우
+   * 의존성이 설치되지 않아도 fixture 생성이 정상 동작합니다.
+   */
+  private async generateWithLLM(
+    fixtureHint: string,
+    prop: EntityProp,
+    entity: Entity,
+  ): Promise<unknown> {
+    const cacheKey = `${entity.id}:${prop.name}:${fixtureHint}`;
+    if (this.options.enableLLMCache && this.llmCache.has(cacheKey)) {
+      return this.llmCache.get(cacheKey);
+    }
+
+    const apiKey = this.getApiKey();
+    const { createAnthropic } = await import("@ai-sdk/anthropic");
+    const { generateText } = await import("ai");
+
+    const { text } = await generateText({
+      model: createAnthropic({ apiKey })(this.options.llmModel || "claude-sonnet-4-5"),
+      prompt: this.buildLLMPrompt(fixtureHint, prop, entity),
+    });
+
+    const value = this.parseLLMResponse(text, prop.type);
+    if (this.options.enableLLMCache) {
+      this.llmCache.set(cacheKey, value);
+    }
+
+    return value;
+  }
+
+  private buildLLMPrompt(hint: string, prop: EntityProp, entity: Entity): string {
+    const locale = this.options.locale || "ko";
+    const language = locale === "ko" ? "Korean" : locale === "ja" ? "Japanese" : "English";
+
+    let prompt = `Generate test data for ${entity.id}.${prop.name} (type: ${prop.type})
+
+Requirement: ${hint}
+
+Rules:
+- Return ONLY the value, no explanation or markdown
+- Use ${language} language if applicable
+- Format: ${this.getExpectedFormat(prop.type)}`;
+
+    // enum 타입인 경우 가능한 값 목록 추가
+    if (prop.type === "enum" || prop.type === "enum[]") {
+      let enumValues: string[] = [];
+
+      if ("enum" in prop && Array.isArray(prop.enum) && prop.enum.length > 0) {
+        enumValues = prop.enum;
+      } else if ("id" in prop && prop.id && entity?.enumLabels?.[prop.id]) {
+        enumValues = Object.keys(entity.enumLabels[prop.id]);
+      }
+
+      if (enumValues.length > 0) {
+        prompt += `\n- IMPORTANT: Choose ONLY from these allowed values: ${enumValues.join(", ")}`;
+      }
+    }
+
+    prompt += `\n\nExample: ${this.getExampleForType(prop.type, locale)}`;
+
+    return prompt;
+  }
+
+  private parseLLMResponse(text: string, propType: string): unknown {
+    const cleaned = text.trim();
+
+    // 배열 타입 처리
+    if (propType.endsWith("[]")) {
+      try {
+        const parsed = JSON.parse(cleaned);
+        const baseType = propType.slice(0, -2); // "integer[]" -> "integer"
+
+        if (Array.isArray(parsed)) {
+          return parsed.map((item) => {
+            // null/undefined는 타입별 기본값으로
+            if (item === null || item === undefined) {
+              return this.getDefaultValueForType(baseType);
+            }
+            // 객체는 JSON.stringify 후 파싱 (json 타입인 경우)
+            if (typeof item === "object") {
+              return baseType === "json"
+                ? item
+                : this.parseScalarValue(JSON.stringify(item), baseType);
+            }
+            // primitive 값은 문자열로 변환 후 파싱
+            return this.parseScalarValue(String(item), baseType);
+          });
+        }
+
+        // 단일 값이 온 경우 배열로 감싸기
+        if (parsed === null || parsed === undefined) {
+          return [this.getDefaultValueForType(baseType)];
+        }
+        return [this.parseScalarValue(String(parsed), baseType)];
+      } catch {
+        return [];
+      }
+    }
+
+    return this.parseScalarValue(cleaned, propType);
+  }
+
+  private getDefaultValueForType(propType: string): unknown {
+    switch (propType) {
+      case "integer":
+        return 0;
+      case "bigInteger":
+        return 0n;
+      case "float":
+      case "number":
+      case "numeric":
+        return 0;
+      case "boolean":
+        return false;
+      case "date":
+        return new Date();
+      case "json":
+        return {};
+      case "uuid":
+        return "00000000-0000-0000-0000-000000000000";
+      default:
+        return "";
+    }
+  }
+
+  private parseScalarValue(text: string, propType: string): unknown {
+    const cleaned = text.trim();
+
+    switch (propType) {
+      case "integer": {
+        const num = parseInt(cleaned, 10);
+        return Number.isNaN(num) ? 0 : num;
+      }
+      case "bigInteger": {
+        try {
+          return BigInt(cleaned);
+        } catch {
+          return 0n;
+        }
+      }
+      case "float":
+      case "number":
+      case "numeric": {
+        const num = parseFloat(cleaned);
+        return Number.isNaN(num) ? 0 : num;
+      }
+      case "boolean":
+        return cleaned.toLowerCase() === "true";
+      case "date": {
+        const date = new Date(cleaned);
+        return Number.isNaN(date.getTime()) ? new Date() : date;
+      }
+      case "json":
+        try {
+          return JSON.parse(cleaned);
+        } catch {
+          return cleaned;
+        }
+      case "uuid":
+      case "enum":
+        return cleaned;
+      default:
+        return cleaned;
+    }
+  }
+
+  /**
+   * Sonamu.secret을 우선으로 하고, 없으면 환경변수에서 API 키를 읽습니다.
+   *
+   * Sonamu.secret은 프로젝트별 설정(sonamu.config.ts)이므로 더 높은 우선순위를 가지며,
+   * 환경변수는 개발 환경이나 CI/CD에서 fallback으로 사용됩니다.
+   */
+  private getApiKey(): string {
+    let apiKey: string | undefined;
+
+    try {
+      const { Sonamu } = require("../api");
+      apiKey = Sonamu.secret?.anthropic_api_key;
+    } catch {
+      // Sonamu가 초기화되지 않은 경우 (테스트 환경 등)
+    }
+
+    if (!apiKey) {
+      apiKey = process.env.ANTHROPIC_API_KEY;
+    }
+
+    if (!apiKey) {
+      throw new Error(
+        "ANTHROPIC_API_KEY not found. Set it in environment variables or Sonamu.secret.anthropic_api_key",
+      );
+    }
+
+    return apiKey;
+  }
+
+  private getExpectedFormat(propType: string): string {
+    // 배열 타입 처리
+    if (propType.endsWith("[]")) {
+      const baseType = propType.slice(0, -2);
+      const baseFormat = this.getScalarFormat(baseType);
+      return `JSON array of ${baseFormat} (e.g., [${this.getExampleForType(baseType, "en")}, ...])`;
+    }
+
+    return this.getScalarFormat(propType);
+  }
+
+  private getScalarFormat(propType: string): string {
+    switch (propType) {
+      case "integer":
+      case "bigInteger":
+        return "integer numbers";
+      case "float":
+      case "number":
+      case "numeric":
+        return "decimal numbers";
+      case "boolean":
+        return "booleans (true or false)";
+      case "date":
+        return "ISO 8601 date strings";
+      case "json":
+        return "valid JSON object or array";
+      case "uuid":
+        return "UUID strings";
+      case "enum":
+        return "one of the allowed enum values";
+      default:
+        return "plain text strings";
+    }
+  }
+
+  private getExampleForType(propType: string, locale: Locale): string {
+    // 배열 타입 처리
+    if (propType.endsWith("[]")) {
+      const baseType = propType.slice(0, -2);
+      const baseExample = this.getScalarExample(baseType, locale);
+      return `[${baseExample}]`;
+    }
+
+    return this.getScalarExample(propType, locale);
+  }
+
+  private getScalarExample(propType: string, locale: Locale): string {
+    const isKorean = locale === "ko";
+
+    switch (propType) {
+      case "integer":
+      case "bigInteger":
+        return "42";
+      case "float":
+      case "number":
+      case "numeric":
+        return "3.14";
+      case "boolean":
+        return "true";
+      case "date":
+        return "2024-01-01";
+      case "json":
+        return '{"key": "value"}';
+      case "uuid":
+        return "550e8400-e29b-41d4-a716-446655440000";
+      case "enum":
+        return "ENUM_VALUE";
+      default:
+        return isKorean ? "안녕하세요" : "Hello";
+    }
+  }
+
+  /**
+   * LLM 캐시 통계를 반환합니다.
+   */
+  getLLMCacheStats() {
+    return {
+      size: this.llmCache.size,
+      enabled: this.options.enableLLMCache,
+    };
+  }
+
+  /**
+   * LLM 캐시를 초기화합니다.
+   */
+  clearLLMCache() {
+    this.llmCache.clear();
+  }
+
+  /**
+   * 컨텍스트 생성
+   */
+  private createContext(): GeneratorContext {
+    return {
+      fixtures: new Map(),
+      referenceCache: new Map(),
+      importedRecords: new Set(),
+    };
+  }
+
+  /**
+   * 배치 생성 및 자동 저장
+   *
+   * 1. 각 spec별로 fixture 생성 (메모리)
+   * 2. FixtureRecord로 변환
+   * 3. FixtureManager.insertFixtures()로 targetDb에 저장
+   *
+   * @returns 저장된 fixture 데이터 (실제 DB ID 포함)
+   */
+  async generateBatch(
+    specs: Array<{ entity: string; count: number; overrides?: Record<string, unknown> }>,
+  ): Promise<FixtureImportResult[]> {
+    const context = this.createContext();
+    const generatedFixtures: Array<{ entity: string; data: Record<string, unknown> }> = [];
+
+    // 1. 각 spec별로 fixture 생성
+    for (const spec of specs) {
+      for (let i = 0; i < spec.count; i++) {
+        const fixture = await this.generate(spec.entity, spec.overrides || {}, context);
+        generatedFixtures.push({
+          entity: spec.entity,
+          data: fixture,
+        });
+      }
+    }
+
+    // 2. FixtureRecord로 변환
+    const fixtureRecords: FixtureRecord[] = [];
+    for (const { entity: entityName, data } of generatedFixtures) {
+      const entity = this.entityManager.get(entityName);
+
+      // 임시 ID 생성 (targetDb에 INSERT 후 실제 ID를 받음)
+      const tempId = Math.floor(Math.random() * 1000000);
+      const records = await FixtureManager.createFixtureRecord(
+        entity,
+        { ...data, id: tempId } as { id: number; [key: string]: string | number | boolean | null },
+        { singleRecord: true },
+      );
+      fixtureRecords.push(...records);
+    }
+
+    // 3. targetDb에 삽입 (FixtureManager가 의존성 정렬 처리)
+    const results = await FixtureManager.insertFixtures(this.targetDbName, fixtureRecords);
+
+    console.log(
+      chalk.green(`Generated and saved ${results.length} fixtures to ${this.targetDbName}`),
+    );
+    return results;
+  }
+
+  /**
+   * 실제 DB(sourceDb)에서 데이터를 조회하여 fixture DB(targetDb)에 import합니다.
+   *
+   * 1. DataExplorer로 sourceDb에서 데이터 조회 (관련 데이터 포함)
+   * 2. FixtureRecord로 변환
+   * 3. targetDb에 삽입
+   *
+   * @param entityName - 조회할 entity 이름
+   * @param options - 조회 옵션 (strategy, limit, includeRelations 등)
+   * @returns 저장된 fixture 데이터 (실제 DB ID 포함)
+   *
+   * @example
+   * // 프로덕션 DB에서 User 10명 + 관련 Employee, Department 가져오기
+   * await generator.importFromSource("User", {
+   *   strategy: "sample",
+   *   limit: 10,
+   *   includeRelations: true,
+   *   maxDepth: 2
+   * });
+   */
+  async importFromSource(
+    entityName: string,
+    options: ExploreWithRelationsOptions,
+  ): Promise<FixtureImportResult[]> {
+    console.log(
+      chalk.blue(
+        `Importing ${entityName} from source DB with options: ${JSON.stringify({ strategy: options.strategy, limit: options.limit, includeRelations: options.includeRelations, maxDepth: options.maxDepth })}`,
+      ),
+    );
+
+    // 1. DataExplorer로 sourceDb에서 데이터 조회 (관련 데이터 포함)
+    const exploreResult = await this.dataExplorer.exploreWithRelations(entityName, options);
+
+    console.log(
+      chalk.cyan(
+        `Found ${exploreResult.main.records.length} ${entityName} records and ${exploreResult.related.size} related entities`,
+      ),
+    );
+
+    // 2. FixtureRecord로 변환
+    const fixtureRecords: FixtureRecord[] = [];
+
+    // 메인 entity의 records를 FixtureRecord로 변환
+    const mainEntity = this.entityManager.get(entityName);
+    for (const record of exploreResult.main.records) {
+      const records = await FixtureManager.createFixtureRecord(
+        mainEntity,
+        record as { id: number | string; [key: string]: string | number | boolean | null },
+        { _db: this.sourceDb, singleRecord: true },
+      );
+      fixtureRecords.push(...records);
+    }
+
+    // 관련 entity의 records를 FixtureRecord로 변환
+    for (const [relatedEntityName, relatedRecords] of exploreResult.related.entries()) {
+      const relatedEntity = this.entityManager.get(relatedEntityName);
+      for (const record of relatedRecords) {
+        const records = await FixtureManager.createFixtureRecord(
+          relatedEntity,
+          record as { id: number | string; [key: string]: string | number | boolean | null },
+          { _db: this.sourceDb, singleRecord: true },
+        );
+        fixtureRecords.push(...records);
+      }
+
+      console.log(chalk.gray(`  - ${relatedEntityName}: ${relatedRecords.length} records`));
+    }
+
+    // 3. targetDb에 삽입 (FixtureManager가 의존성 정렬 처리)
+    const results = await FixtureManager.insertFixtures(this.targetDbName, fixtureRecords);
+
+    console.log(
+      chalk.green(
+        `Successfully imported ${results.length} records to ${this.targetDbName} (${exploreResult.main.records.length} ${entityName} + ${results.length - exploreResult.main.records.length} related)`,
+      ),
+    );
+
+    return results;
+  }
+}