sonamu 0.10.13 → 0.11.0

package/src/testing/fixture-manager.ts

@@ -1,7 +1,7 @@
-import assert from "assert";
-import { execSync, type ExecSyncOptions } from "child_process";
-import { readFileSync, writeFileSync } from "fs";
-import { inspect } from "util";
+import assert from "node:assert";
+import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+import { inspect } from "node:util";
 
 import chalk from "chalk";
 import inflection from "inflection";
@@ -61,10 +61,51 @@ type UpsertRow = {
   [columnName: string]: UpsertRowValue;
 };
 
-function executeFixtureSyncCommand(command: string, options: ExecSyncOptions): void {
+function waitForFixtureCommand(child: ChildProcess, executable: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (code === 0) resolve();
+      else
+        reject(
+          new Error(`${executable} 명령이 ${code ?? signal ?? "unknown"} 상태로 실패했습니다.`),
+        );
+    });
+  });
+}
+
+function executeFixtureCommand(
+  executable: string,
+  args: string[],
+  options: Pick<SpawnOptions, "env" | "stdio">,
+): Promise<void> {
+  return waitForFixtureCommand(spawn(executable, args, options), executable);
+}
+
+async function pipeFixtureCommands(
+  source: { executable: string; args: string[]; env: NodeJS.ProcessEnv },
+  destination: { executable: string; args: string[]; env: NodeJS.ProcessEnv },
+): Promise<void> {
+  const sourceProcess = spawn(source.executable, source.args, {
+    env: source.env,
+    stdio: ["ignore", "pipe", "inherit"],
+  });
+  const destinationProcess = spawn(destination.executable, destination.args, {
+    env: destination.env,
+    stdio: ["pipe", "inherit", "inherit"],
+  });
+  assert(sourceProcess.stdout);
+  assert(destinationProcess.stdin);
+  sourceProcess.stdout.pipe(destinationProcess.stdin);
+
   try {
-    execSync(command, options);
+    await Promise.all([
+      waitForFixtureCommand(sourceProcess, source.executable),
+      waitForFixtureCommand(destinationProcess, destination.executable),
+    ]);
   } catch (error) {
+    sourceProcess.kill();
+    destinationProcess.kill();
     throw new Error("Fixture database synchronization command failed", { cause: error });
   }
 }
@@ -74,6 +115,8 @@ export interface DuplicateCheckOptions {
   columns?: {
     [entityId: string]: string[];
   };
+  includeRelations?: boolean;
+  maxDepth?: number;
 }
 
 export class FixtureManagerClass {
@@ -137,40 +180,76 @@ export class FixtureManagerClass {
 
     // 1. 로컬 test DB 연결 종료 및 재생성
     const testPgEnv = { PGPASSWORD: testConn.password || "" };
-    executeFixtureSyncCommand(
-      `psql -h ${testConn.host} -p ${testConn.port ?? 5432} -U ${testConn.user} -d postgres -c "
+    const testPsqlArgs = [
+      "-h",
+      testConn.host ?? "localhost",
+      "-p",
+      String(testConn.port ?? 5432),
+      "-U",
+      testConn.user ?? "",
+      "-d",
+      "postgres",
+      "-c",
+    ];
+    await executeFixtureCommand(
+      "psql",
+      [
+        ...testPsqlArgs,
+        `
         SELECT pg_terminate_backend(pg_stat_activity.pid)
         FROM pg_stat_activity
         WHERE datname = '${testConn.database}'
           AND pid <> pg_backend_pid();
-      "`,
+      `,
+      ],
       { stdio: "inherit", env: { ...process.env, ...testPgEnv } },
     );
-
-    executeFixtureSyncCommand(
-      `psql -h ${testConn.host} -p ${testConn.port ?? 5432} -U ${testConn.user} -d postgres -c "DROP DATABASE IF EXISTS \\"${testConn.database}\\""`,
+    await executeFixtureCommand(
+      "psql",
+      [...testPsqlArgs, `DROP DATABASE IF EXISTS "${testConn.database}"`],
       { stdio: "inherit", env: { ...process.env, ...testPgEnv } },
     );
-
-    executeFixtureSyncCommand(
-      `psql -h ${testConn.host} -p ${testConn.port ?? 5432} -U ${testConn.user} -d postgres -c "CREATE DATABASE \\"${testConn.database}\\""`,
+    await executeFixtureCommand(
+      "psql",
+      [...testPsqlArgs, `CREATE DATABASE "${testConn.database}"`],
       { stdio: "inherit", env: { ...process.env, ...testPgEnv } },
     );
 
     // 2. 원격 fixture DB → 로컬 test DB로 복사 (pg_dump | pg_restore)
     const fixturePgEnv = { PGPASSWORD: fixtureConn.password || "" };
-    const dumpCmd = `pg_dump -h ${fixtureConn.host} -p ${fixtureConn.port ?? 5432} -U ${fixtureConn.user} -d ${fixtureConn.database} -Fc`;
-    const restoreCmd = `pg_restore -h ${testConn.host} -p ${testConn.port ?? 5432} -U ${testConn.user} -d ${testConn.database} --no-owner --no-acl`;
-
-    executeFixtureSyncCommand(
-      `${dumpCmd} | PGPASSWORD="${testConn.password || ""}" ${restoreCmd}`,
+    await pipeFixtureCommands(
       {
-        stdio: "inherit",
+        executable: "pg_dump",
+        args: [
+          "-h",
+          fixtureConn.host ?? "localhost",
+          "-p",
+          String(fixtureConn.port ?? 5432),
+          "-U",
+          fixtureConn.user ?? "",
+          "-d",
+          fixtureConn.database,
+          "-Fc",
+        ],
         env: { ...process.env, ...fixturePgEnv },
-        shell: "/bin/bash",
+      },
+      {
+        executable: "pg_restore",
+        args: [
+          "-h",
+          testConn.host ?? "localhost",
+          "-p",
+          String(testConn.port ?? 5432),
+          "-U",
+          testConn.user ?? "",
+          "-d",
+          testConn.database,
+          "--no-owner",
+          "--no-acl",
+        ],
+        env: { ...process.env, ...testPgEnv },
       },
     );
-
     // 3. 시퀀스 리셋 (데이터 복사 후 시퀀스를 MAX(id)로 정렬)
     await this.resetSequences(Sonamu.dbConfig.test);
   }
@@ -364,6 +443,8 @@ export class FixtureManagerClass {
         const initialRecordsLength = fixtures.length;
         const newRecords = await this.createFixtureRecord(entity, row, {
           db: sourceDB,
+          includeRelations: duplicateCheck?.includeRelations,
+          maxDepth: duplicateCheck?.maxDepth,
         });
         fixtures.push(...newRecords);
         const currentFixtureRecord = fixtures.find((r) => r.fixtureId === `${entityId}#${row.id}`);
@@ -421,12 +502,14 @@ export class FixtureManagerClass {
     options?: {
       singleRecord?: boolean;
       db?: Knex;
+      includeRelations?: boolean;
+      maxDepth?: number;
     },
   ): Promise<FixtureRecord[]> {
     const records: FixtureRecord[] = [];
     const visitedEntities = new Set<string>();
 
-    const create = async (entity: Entity, row: FixtureSourceRecord) => {
+    const create = async (entity: Entity, row: FixtureSourceRecord, depth: number) => {
       const fixtureId = `${entity.id}#${row.id}`;
       if (visitedEntities.has(fixtureId)) {
         return;
@@ -488,14 +571,23 @@ export class FixtureManagerClass {
           if (relatedId) {
             record.belongsRecords.push(`${prop.with}#${relatedId}`);
           }
-          if (!options?.singleRecord && relatedId) {
+          if (
+            !options?.singleRecord &&
+            options?.includeRelations !== false &&
+            depth < (options?.maxDepth ?? Number.POSITIVE_INFINITY) &&
+            relatedId
+          ) {
             const relatedEntity = EntityManager.get(prop.with);
             const relatedRow = await db(relatedEntity.table).where("id", relatedId).first();
             if (relatedRow) {
-              await create(relatedEntity, {
-                ...dataExplorerRecordSchema.parse(relatedRow),
-                id: z.union([z.number(), z.string()]).parse(relatedRow.id),
-              });
+              await create(
+                relatedEntity,
+                {
+                  ...dataExplorerRecordSchema.parse(relatedRow),
+                  id: z.union([z.number(), z.string()]).parse(relatedRow.id),
+                },
+                depth + 1,
+              );
             }
           }
         }
@@ -504,7 +596,7 @@ export class FixtureManagerClass {
       records.push(record);
     };
 
-    await create(rootEntity, rootRow);
+    await create(rootEntity, rootRow, 0);
 
     return records;
   }
@@ -1120,7 +1212,7 @@ export class FixtureManagerClass {
 
   async addFixtureLoader(code: string) {
     const path = `${Sonamu.apiRootPath}/src/testing/fixture.ts`;
-    const content = readFileSync(path).toString();
+    const content = await readFile(path, "utf8");
 
     const fixtureLoaderStart = content.indexOf("const fixtureLoader = {");
     const fixtureLoaderEnd = content.indexOf("};", fixtureLoaderStart);
@@ -1128,7 +1220,7 @@ export class FixtureManagerClass {
     if (fixtureLoaderStart !== -1 && fixtureLoaderEnd !== -1) {
       const newContent = `${content.slice(0, fixtureLoaderEnd)}  ${code}\n${content.slice(fixtureLoaderEnd)}`;
 
-      writeFileSync(path, newContent);
+      await writeFile(path, newContent);
     } else {
       throw new Error("Failed to find fixtureLoader in fixture.ts");
     }

package/src/tooling/__tests__/cdd-rule-bootstrap.contract.test.ts

@@ -0,0 +1,118 @@
+import * as fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { createDefaultCddToolingAdapter } from "../cdd-service";
+
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })),
+  );
+});
+
+async function createContractRoot() {
+  const workspace = await fs.mkdtemp(path.join(os.tmpdir(), "sonamu-cdd-rule-"));
+  temporaryDirectories.push(workspace);
+  const contractRoot = path.join(workspace, "contract");
+  await fs.mkdir(contractRoot);
+  return contractRoot;
+}
+
+const RULE_INPUT = {
+  ruleKey: "api",
+  id: "api-1",
+  when: "API 응답을 정의할 때",
+  text: "모든 목록 응답은 페이지네이션을 포함한다",
+  examples: ["GET /posts"],
+  dryRun: false,
+};
+
+describe("CDD 규칙 최초 등록", () => {
+  it("rules 디렉터리가 없어도 첫 규칙 파일을 만들어 저장한다", async () => {
+    const contractRoot = await createContractRoot();
+    const adapter = createDefaultCddToolingAdapter({ contractRoot, fs });
+
+    await expect(adapter.addRule(RULE_INPUT)).resolves.toMatchObject({
+      key: "api",
+      path: "rules/api.rules.json",
+      rules: [
+        {
+          id: "api-1",
+          when: "API 응답을 정의할 때",
+          instruction: "모든 목록 응답은 페이지네이션을 포함한다",
+          examples: ["GET /posts"],
+        },
+      ],
+    });
+
+    const saved = JSON.parse(
+      await fs.readFile(path.join(contractRoot, "rules", "api.rules.json"), "utf8"),
+    );
+    expect(saved.rules).toHaveLength(1);
+    expect(saved.rules[0].id).toBe("api-1");
+  });
+
+  it("rules 디렉터리는 있지만 규칙 키 파일이 없으면 새로 만든다", async () => {
+    const contractRoot = await createContractRoot();
+    await fs.mkdir(path.join(contractRoot, "rules"));
+    const adapter = createDefaultCddToolingAdapter({ contractRoot, fs });
+
+    await expect(adapter.addRule(RULE_INPUT)).resolves.toMatchObject({
+      key: "api",
+      rules: [{ id: "api-1" }],
+    });
+
+    await expect(adapter.rules()).resolves.toMatchObject({
+      rules: [{ key: "api", path: "rules/api.rules.json", ruleCount: 1 }],
+    });
+  });
+
+  it("기존 규칙 문서에는 규칙을 이어붙이고 description을 보존한다", async () => {
+    const contractRoot = await createContractRoot();
+    await fs.mkdir(path.join(contractRoot, "rules"));
+    await fs.writeFile(
+      path.join(contractRoot, "rules", "api.rules.json"),
+      JSON.stringify({
+        description: "API 규칙",
+        rules: [{ id: "api-0", when: "언제나", instruction: "기존 규칙" }],
+      }),
+      "utf8",
+    );
+    const adapter = createDefaultCddToolingAdapter({ contractRoot, fs });
+
+    await expect(adapter.addRule(RULE_INPUT)).resolves.toMatchObject({
+      description: "API 규칙",
+      rules: [{ id: "api-0" }, { id: "api-1" }],
+    });
+  });
+
+  it("dryRun이면 규칙 파일을 만들지 않는다", async () => {
+    const contractRoot = await createContractRoot();
+    const adapter = createDefaultCddToolingAdapter({ contractRoot, fs });
+
+    await expect(adapter.addRule({ ...RULE_INPUT, dryRun: true })).resolves.toMatchObject({
+      dryRun: true,
+    });
+
+    await expect(fs.access(path.join(contractRoot, "rules"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+  });
+
+  it("깨진 JSON 규칙 문서는 빈 문서로 덮어쓰지 않고 실패한다", async () => {
+    const contractRoot = await createContractRoot();
+    const ruleFile = path.join(contractRoot, "rules", "api.rules.json");
+    await fs.mkdir(path.join(contractRoot, "rules"));
+    await fs.writeFile(ruleFile, "{ broken", "utf8");
+    const adapter = createDefaultCddToolingAdapter({ contractRoot, fs });
+
+    await expect(adapter.addRule(RULE_INPUT)).rejects.toMatchObject({
+      code: "INVALID_CDD_RULES",
+    });
+    await expect(fs.readFile(ruleFile, "utf8")).resolves.toBe("{ broken");
+  });
+});

package/src/tooling/__tests__/cli-tooling-auth.contract.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import * as authModule from "../../auth";
+import { tooling } from "../cli-tooling";
+
+function stubGenerator() {
+  return vi.spyOn(authModule, "generateBetterAuthEntities").mockResolvedValue(undefined);
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("auth.generate tooling 연산", () => {
+  it("plugins 옵션이 없으면 빈 플러그인 목록으로 core 엔티티를 생성한다", async () => {
+    const generate = stubGenerator();
+
+    await expect(tooling.auth.generate({})).resolves.toBeUndefined();
+
+    expect(generate).toHaveBeenCalledTimes(1);
+    expect(generate).toHaveBeenCalledWith({ plugins: [] });
+  });
+
+  it("plugins 값이 undefined로 전달되어도 빈 플러그인 목록으로 처리한다", async () => {
+    const generate = stubGenerator();
+
+    await expect(tooling.auth.generate({ plugins: undefined })).resolves.toBeUndefined();
+
+    expect(generate).toHaveBeenCalledWith({ plugins: [] });
+  });
+
+  it.each([
+    ["배열", ["admin", "jwt"]],
+    ["숫자", 1],
+    ["객체", { admin: true }],
+    ["불리언", true],
+  ])("plugins가 문자열이 아닌 %s이면 인자 오류로 거절한다", async (_label, plugins) => {
+    const generate = stubGenerator();
+
+    // 문자열이 아닌 값을 조용히 무시하면 잘못된 입력이 core 전용 생성으로 둔갑합니다.
+    await expect(tooling.auth.generate({ plugins })).rejects.toMatchObject({
+      code: "INVALID_ARGUMENT",
+      exitCode: 2,
+    });
+
+    expect(generate).not.toHaveBeenCalled();
+  });
+
+  it("plugins가 빈 문자열이면 빈 플러그인 목록으로 처리한다", async () => {
+    const generate = stubGenerator();
+
+    await expect(tooling.auth.generate({ plugins: "" })).resolves.toBeUndefined();
+
+    expect(generate).toHaveBeenCalledWith({ plugins: [] });
+  });
+
+  it("쉼표로 구분한 plugins 목록은 그대로 전달한다", async () => {
+    const generate = stubGenerator();
+
+    await tooling.auth.generate({ plugins: "admin, jwt" });
+
+    expect(generate).toHaveBeenCalledWith({ plugins: ["admin", "jwt"] });
+  });
+
+  it("지원하지 않는 plugin은 거절하고 엔티티 생성을 시도하지 않는다", async () => {
+    const generate = stubGenerator();
+
+    await expect(tooling.auth.generate({ plugins: "bogus" })).rejects.toThrow();
+
+    expect(generate).not.toHaveBeenCalled();
+  });
+});

package/src/tooling/__tests__/cli-tooling-cone-locale.contract.test.ts

@@ -0,0 +1,150 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { loadConfig } from "../../api/config";
+import { Sonamu } from "../../api/sonamu";
+import { type ConeGenerationResult } from "../../cone/cone-generator";
+import { EntityManager } from "../../entity/entity-manager";
+import { Syncer } from "../../syncer/syncer";
+import { type EntityJson } from "../../types/types";
+import { tooling } from "../cli-tooling";
+import { attachSonamuTestRoot, detachSonamuTestRoot } from "./helpers/sonamu-test-root";
+
+const CONE_RESULT: ConeGenerationResult = {
+  propCones: {},
+  subsetCones: {},
+  enumCones: {},
+  tokensUsed: 100,
+};
+
+function entityJson(id: string): EntityJson {
+  return {
+    id,
+    table: `${id.toLowerCase()}s`,
+    title: id,
+    props: [{ name: "id", type: "integer" }],
+    indexes: [],
+    subsets: {},
+    enums: {},
+  };
+}
+
+/**
+ * 임시 프로젝트를 만들고 sonamu.config.ts를 실제로 로딩해 Sonamu에 주입합니다.
+ *
+ * @param i18nSource - config에 넣을 i18n 블록 소스. null이면 i18n 자체를 생략합니다.
+ */
+async function attachProject(i18nSource: string | null): Promise<void> {
+  const apiRootPath = await attachSonamuTestRoot();
+  await writeFile(path.join(apiRootPath, ".env"), "SONAMU_CONE_LOCALE_TEST=1\n");
+  await writeFile(
+    path.join(apiRootPath, "src", "sonamu.config.ts"),
+    `export default { ${i18nSource === null ? "" : `i18n: ${i18nSource},`} };\n`,
+  );
+  Sonamu.config = await loadConfig(apiRootPath);
+  Sonamu.syncer = new Syncer();
+
+  await EntityManager.register(entityJson("Post"));
+  await EntityManager.register(entityJson("Comment"));
+}
+
+function spyOnCones(entityId: string) {
+  return vi.spyOn(EntityManager.get(entityId), "generateCones").mockResolvedValue(CONE_RESULT);
+}
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await detachSonamuTestRoot();
+});
+
+describe("cone 생성의 locale 기본값", () => {
+  it("cone gen에 locale이 없으면 설정된 defaultLocale을 사용한다", async () => {
+    await attachProject(`{ defaultLocale: "en", supportedLocales: ["en", "ko"] }`);
+    const generateCones = spyOnCones("Post");
+
+    await tooling.entity.cones({ entityId: "Post" });
+
+    expect(generateCones).toHaveBeenCalledWith(expect.objectContaining({ locale: "en" }));
+  });
+
+  it("i18n 설정이 없으면 ko로 폴백한다", async () => {
+    await attachProject(null);
+    const generateCones = spyOnCones("Post");
+
+    await tooling.entity.cones({ entityId: "Post" });
+
+    expect(generateCones).toHaveBeenCalledWith(expect.objectContaining({ locale: "ko" }));
+  });
+
+  it("지원하지 않는 defaultLocale이면 ko로 폴백한다", async () => {
+    await attachProject(`{ defaultLocale: "fr", supportedLocales: ["fr"] }`);
+    const generateCones = spyOnCones("Post");
+
+    await tooling.entity.cones({ entityId: "Post" });
+
+    expect(generateCones).toHaveBeenCalledWith(expect.objectContaining({ locale: "ko" }));
+  });
+
+  it("명시한 locale이 설정된 defaultLocale보다 우선한다", async () => {
+    await attachProject(`{ defaultLocale: "en", supportedLocales: ["en", "ja"] }`);
+    const generateCones = spyOnCones("Post");
+
+    await tooling.entity.cones({ entityId: "Post", locale: "ja" });
+
+    expect(generateCones).toHaveBeenCalledWith(expect.objectContaining({ locale: "ja" }));
+  });
+
+  it("stub entity --ai도 설정된 defaultLocale을 사용한다", async () => {
+    await attachProject(`{ defaultLocale: "en", supportedLocales: ["en", "ko"] }`);
+    const createEntity = vi.spyOn(Sonamu.syncer, "createEntity").mockResolvedValue(undefined);
+    const generateCones = spyOnCones("Post");
+
+    await tooling.entity.create({ name: "Post", ai: true });
+
+    expect(createEntity).toHaveBeenCalledWith({ entityId: "Post", title: "Post" });
+    expect(generateCones).toHaveBeenCalledWith(expect.objectContaining({ locale: "en" }));
+  });
+});
+
+describe("cone gen all의 엔티티별 결과 보존", () => {
+  it("모두 성공하면 엔티티별 결과를 배열로 반환한다", async () => {
+    await attachProject(null);
+    spyOnCones("Post");
+    spyOnCones("Comment");
+
+    await expect(tooling.entity.cones({ entityId: "all" })).resolves.toEqual([
+      { entityId: "Post", ...CONE_RESULT },
+      { entityId: "Comment", ...CONE_RESULT },
+    ]);
+  });
+
+  it("일부 엔티티가 실패해도 성공한 엔티티 결과를 함께 보고한다", async () => {
+    await attachProject(null);
+    spyOnCones("Post");
+    vi.spyOn(EntityManager.get("Comment"), "generateCones").mockRejectedValue(
+      new Error("LLM rate limit"),
+    );
+
+    await expect(tooling.entity.cones({ entityId: "all" })).rejects.toMatchObject({
+      code: "CONE_GENERATION_FAILED",
+      details: {
+        results: [{ entityId: "Post", tokensUsed: 100 }],
+        failures: [{ entityId: "Comment", message: expect.stringContaining("LLM rate limit") }],
+      },
+    });
+  });
+
+  it("한 엔티티가 실패해도 다른 엔티티의 cone 생성을 건너뛰지 않는다", async () => {
+    await attachProject(null);
+    const post = spyOnCones("Post");
+    vi.spyOn(EntityManager.get("Comment"), "generateCones").mockRejectedValue(
+      new Error("LLM rate limit"),
+    );
+
+    await expect(tooling.entity.cones({ entityId: "all" })).rejects.toThrow();
+
+    expect(post).toHaveBeenCalledTimes(1);
+  });
+});