sonamu 0.10.12 → 0.11.0

package/src/tooling/__tests__/helpers/sonamu-test-root.ts

@@ -0,0 +1,42 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { Sonamu, type SonamuTestingSnapshot } from "../../../api/sonamu";
+import { type AbsolutePath } from "../../../utils/path-utils";
+
+const createdWorkspaces: string[] = [];
+let capturedSnapshot: SonamuTestingSnapshot | null = null;
+let capturedInitialized = false;
+
+/**
+ * 임시 api root를 만들어 Sonamu singleton의 공개 setter로 주입합니다.
+ *
+ * tooling 연산은 `Sonamu.isInitialized`가 참이면 초기화를 건너뛰므로,
+ * 실제 DB/설정 없이 파일 경로 기반 동작만 검증할 수 있습니다.
+ */
+export async function attachSonamuTestRoot(): Promise<string> {
+  const workspace = await mkdtemp(path.join(os.tmpdir(), "sonamu-tooling-"));
+  createdWorkspaces.push(workspace);
+  const apiRootPath = path.join(workspace, "api");
+  await mkdir(path.join(apiRootPath, "src", "application"), { recursive: true });
+
+  capturedSnapshot ??= Sonamu.captureTestingSnapshot();
+  capturedInitialized = Sonamu.isInitialized;
+  // SAFETY: mkdtemp가 반환한 절대 경로만 주입합니다.
+  Sonamu.apiRootPath = apiRootPath as AbsolutePath;
+  Sonamu.isInitialized = true;
+  return apiRootPath;
+}
+
+/** 주입한 Sonamu 상태를 되돌리고 임시 디렉터리를 정리합니다. */
+export async function detachSonamuTestRoot(): Promise<void> {
+  if (capturedSnapshot !== null) {
+    Sonamu.restoreTestingSnapshot(capturedSnapshot);
+    capturedSnapshot = null;
+  }
+  Sonamu.isInitialized = capturedInitialized;
+  await Promise.all(
+    createdWorkspaces.splice(0).map((workspace) => rm(workspace, { recursive: true, force: true })),
+  );
+}

package/src/tooling/__tests__/test-run-client-config.contract.test.ts

@@ -0,0 +1,154 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { createServer, type Server } from "node:http";
+import { type AddressInfo } from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { createDefaultTestRunClient } from "../test-run-client";
+
+const STATUS_PAYLOAD = { running: false };
+const RUN_RESULT = {
+  ok: true,
+  summary: { total: 1, passed: 1, failed: 0, skipped: 0, durationMs: 12 },
+  results: [],
+};
+
+const originalVitest = process.env.VITEST;
+const originalHot = process.env.HOT;
+const temporaryRoots: string[] = [];
+const startedServers: Server[] = [];
+
+/** DevRunner 응답을 대신하는 실제 로컬 HTTP 서버를 띄웁니다. */
+async function startDevRunnerServer(): Promise<number> {
+  const server = createServer((request, response) => {
+    response.setHeader("content-type", "application/json");
+    if (request.url === "/__test__/status") {
+      response.end(JSON.stringify(STATUS_PAYLOAD));
+      return;
+    }
+    if (request.url === "/__test__/run") {
+      response.end(JSON.stringify(RUN_RESULT));
+      return;
+    }
+    response.statusCode = 404;
+    response.end("{}");
+  });
+  startedServers.push(server);
+  await new Promise<void>((resolve) => {
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  // SAFETY: TCP listen 이후의 주소는 항상 AddressInfo 입니다.
+  const address = server.address() as AddressInfo;
+  return address.port;
+}
+
+/** dist 빌드 없이 src/sonamu.config.ts만 가진 일반 개발 프로젝트를 만듭니다. */
+async function createSourceOnlyProject(port: number | null): Promise<string> {
+  const projectRoot = await mkdtemp(path.join(os.tmpdir(), "sonamu-test-run-client-"));
+  temporaryRoots.push(projectRoot);
+  await mkdir(path.join(projectRoot, "src"), { recursive: true });
+  await writeFile(path.join(projectRoot, ".env"), "SONAMU_TEST_RUN_CLIENT=1\n");
+  if (port === null) return projectRoot;
+
+  await writeFile(
+    path.join(projectRoot, "src", "sonamu.config.ts"),
+    `
+export default {
+  server: { listen: { host: "127.0.0.1", port: ${port} } },
+  test: { devRunner: { enabled: true, routePrefix: "/__test__" } },
+};
+`,
+  );
+  return projectRoot;
+}
+
+function enterPlainDevShell(): void {
+  // dist 설정을 고르는 환경변수가 없는 일반 개발 셸을 재현합니다.
+  delete process.env.VITEST;
+  delete process.env.HOT;
+}
+
+afterEach(async () => {
+  if (originalVitest === undefined) delete process.env.VITEST;
+  else process.env.VITEST = originalVitest;
+  if (originalHot === undefined) delete process.env.HOT;
+  else process.env.HOT = originalHot;
+
+  await Promise.all(
+    startedServers.splice(0).map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          server.close(() => resolve());
+        }),
+    ),
+  );
+  await Promise.all(
+    temporaryRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })),
+  );
+});
+
+describe("test-run-client의 sonamu.config 로딩", () => {
+  it("dist 빌드가 없어도 status가 src/sonamu.config.ts를 읽는다", async () => {
+    const port = await startDevRunnerServer();
+    const projectRoot = await createSourceOnlyProject(port);
+    enterPlainDevShell();
+
+    await expect(createDefaultTestRunClient(projectRoot).status()).resolves.toEqual(STATUS_PAYLOAD);
+    expect(process.env.VITEST).toBeUndefined();
+  });
+
+  it("dist 빌드가 없어도 run이 src/sonamu.config.ts를 읽는다", async () => {
+    const port = await startDevRunnerServer();
+    const projectRoot = await createSourceOnlyProject(port);
+    enterPlainDevShell();
+
+    await expect(
+      createDefaultTestRunClient(projectRoot).run({ files: ["a.test.ts"] }),
+    ).resolves.toMatchObject({ ok: true });
+    expect(process.env.VITEST).toBeUndefined();
+  });
+
+  it("기존 VITEST 값은 설정 로딩 후 원래 값으로 되돌린다", async () => {
+    const port = await startDevRunnerServer();
+    const projectRoot = await createSourceOnlyProject(port);
+    enterPlainDevShell();
+    process.env.VITEST = "false";
+
+    await expect(createDefaultTestRunClient(projectRoot).status()).resolves.toEqual(STATUS_PAYLOAD);
+    expect(process.env.VITEST).toBe("false");
+  });
+
+  it("설정 파일이 없으면 TEST_RUN_CONFIG_ERROR로 실패하고 환경변수를 복원한다", async () => {
+    const projectRoot = await createSourceOnlyProject(null);
+    enterPlainDevShell();
+
+    await expect(createDefaultTestRunClient(projectRoot).status()).rejects.toMatchObject({
+      code: "TEST_RUN_CONFIG_ERROR",
+    });
+    expect(process.env.VITEST).toBeUndefined();
+  });
+
+  it("devRunner가 비활성화되어 있으면 설정 오류로 실패한다", async () => {
+    const projectRoot = await mkdtemp(path.join(os.tmpdir(), "sonamu-test-run-client-off-"));
+    temporaryRoots.push(projectRoot);
+    await mkdir(path.join(projectRoot, "src"), { recursive: true });
+    await writeFile(path.join(projectRoot, ".env"), "SONAMU_TEST_RUN_CLIENT=1\n");
+    await writeFile(
+      path.join(projectRoot, "src", "sonamu.config.ts"),
+      `
+export default {
+  server: { listen: { host: "127.0.0.1", port: 3000 } },
+  test: { devRunner: { enabled: false } },
+};
+`,
+    );
+    enterPlainDevShell();
+
+    await expect(createDefaultTestRunClient(projectRoot).status()).rejects.toMatchObject({
+      code: "TEST_RUN_CONFIG_ERROR",
+    });
+    expect(process.env.VITEST).toBeUndefined();
+  });
+});

package/src/tooling/cdd-service.ts

@@ -0,0 +1,256 @@
+import { constants } from "node:fs";
+import * as defaultFs from "node:fs/promises";
+import path from "node:path";
+
+type CddFileSystem = Pick<typeof defaultFs, "lstat" | "mkdir" | "open" | "opendir" | "realpath">;
+
+function invalidCddPath(relativePath: string, cause?: unknown): Error {
+  return Object.assign(new Error(`CDD 경로가 contract 밖을 참조합니다: ${relativePath}`), {
+    code: "INVALID_CDD_PATH",
+    cause,
+  });
+}
+
+function isWithin(root: string, target: string): boolean {
+  const relative = path.relative(root, target);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== "..");
+}
+
+async function nearestExistingPath(fs: CddFileSystem, target: string): Promise<string> {
+  let candidate = target;
+  while (true) {
+    try {
+      await fs.lstat(candidate);
+      return candidate;
+    } catch (error) {
+      // SAFETY: node:fs lstat 실패의 code만 읽어 경로 부재를 구분합니다.
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      const parent = path.dirname(candidate);
+      if (parent === candidate) throw error;
+      candidate = parent;
+    }
+  }
+}
+
+function createCddFileOperation({
+  contractRoot,
+  fs = defaultFs,
+}: {
+  contractRoot: string;
+  fs?: CddFileSystem;
+}) {
+  async function resolveBoundary(relativePath: string) {
+    const [canonicalRoot, configuredRoot] = await Promise.all([
+      fs.realpath(contractRoot),
+      Promise.resolve(path.resolve(contractRoot)),
+    ]);
+    const target = path.resolve(configuredRoot, relativePath);
+    if (!isWithin(configuredRoot, target)) throw invalidCddPath(relativePath);
+    return { canonicalRoot, target };
+  }
+
+  async function assertCanonicalPath(
+    canonicalRoot: string,
+    target: string,
+    relativePath: string,
+  ): Promise<string> {
+    const canonicalTarget = await fs.realpath(target);
+    if (!isWithin(canonicalRoot, canonicalTarget)) throw invalidCddPath(relativePath);
+    return canonicalTarget;
+  }
+
+  return {
+    async readDirectory(relativePath: string) {
+      const { canonicalRoot, target } = await resolveBoundary(relativePath);
+      const canonicalTarget = await assertCanonicalPath(canonicalRoot, target, relativePath);
+      let directory;
+      try {
+        directory = await fs.opendir(target);
+        const recheckedTarget = await assertCanonicalPath(canonicalRoot, target, relativePath);
+        if (recheckedTarget !== canonicalTarget) throw invalidCddPath(relativePath);
+        const entries = [];
+        while (true) {
+          const entry = await directory.read();
+          if (entry === null) return entries;
+          entries.push(entry);
+        }
+      } finally {
+        await directory?.close();
+      }
+    },
+    async read(relativePath: string): Promise<string> {
+      const { canonicalRoot, target } = await resolveBoundary(relativePath);
+      const canonicalTarget = await assertCanonicalPath(canonicalRoot, target, relativePath);
+      let handle;
+      try {
+        // 최종 symlink를 따라가지 않은 descriptor를 연 뒤 실제 경로를 다시 확인합니다.
+        handle = await fs.open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const recheckedTarget = await assertCanonicalPath(canonicalRoot, target, relativePath);
+        if (recheckedTarget !== canonicalTarget) throw invalidCddPath(relativePath);
+        return await handle.readFile("utf8");
+      } catch (error) {
+        // SAFETY: node:fs open 실패의 code만 읽어 symlink 거부를 정규화합니다.
+        if ((error as NodeJS.ErrnoException).code === "ELOOP") {
+          throw invalidCddPath(relativePath, error);
+        }
+        throw error;
+      } finally {
+        await handle?.close();
+      }
+    },
+
+    async write(relativePath: string, contents: string): Promise<void> {
+      const { canonicalRoot, target } = await resolveBoundary(relativePath);
+      const existing = await nearestExistingPath(fs, target);
+      const canonicalExisting = await assertCanonicalPath(canonicalRoot, existing, relativePath);
+      const targetExists = existing === target;
+
+      if (!targetExists) {
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await assertCanonicalPath(canonicalRoot, path.dirname(target), relativePath);
+      }
+
+      let handle;
+      try {
+        // 검증 전 truncate를 피하고 새 파일은 배타적으로 생성합니다.
+        const flags = targetExists
+          ? constants.O_WRONLY | constants.O_NOFOLLOW
+          : constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW;
+        handle = await fs.open(target, flags, 0o666);
+        const canonicalTarget = await assertCanonicalPath(canonicalRoot, target, relativePath);
+        if (
+          !isWithin(canonicalRoot, canonicalTarget) ||
+          (targetExists && canonicalTarget !== canonicalExisting)
+        ) {
+          throw invalidCddPath(relativePath);
+        }
+        await handle.truncate(0);
+        await handle.writeFile(contents, "utf8");
+      } catch (error) {
+        // SAFETY: node:fs open 실패의 code만 읽어 symlink 거부를 정규화합니다.
+        if ((error as NodeJS.ErrnoException).code === "ELOOP") {
+          throw invalidCddPath(relativePath, error);
+        }
+        throw error;
+      } finally {
+        await handle?.close();
+      }
+    },
+  };
+}
+
+type CddRuleDocument = {
+  description?: string;
+  rules?: Array<{ id: string; when: string; instruction: string; examples?: string[] }>;
+};
+
+function parseCddRules(contents: string): CddRuleDocument {
+  try {
+    // SAFETY: CDD 규칙 소비 지점은 선택 필드만 읽고 배열 부재를 기본값으로 처리합니다.
+    return JSON.parse(contents) as CddRuleDocument;
+  } catch (cause) {
+    throw Object.assign(new Error("CDD rules JSON is malformed"), {
+      code: "INVALID_CDD_RULES",
+      exitCode: 2,
+      cause,
+    });
+  }
+}
+
+/**
+ * 규칙 문서를 읽되, 아직 파일이 없으면 빈 문서로 취급합니다.
+ *
+ * 첫 규칙 등록 시 rules 디렉터리와 파일이 없는 상태를 부트스트랩하기 위한 처리이며,
+ * 깨진 JSON은 그대로 INVALID_CDD_RULES로 실패시켜 덮어쓰기를 막습니다.
+ */
+async function readCddRuleDocument(
+  files: { read(relativePath: string): Promise<string> },
+  relativePath: string,
+): Promise<CddRuleDocument> {
+  try {
+    return parseCddRules(await files.read(relativePath));
+  } catch (error) {
+    // SAFETY: node:fs 읽기 실패의 code만 읽어 규칙 문서 부재를 구분합니다.
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+export function createDefaultCddToolingAdapter({
+  contractRoot,
+  fs = defaultFs,
+}: {
+  contractRoot: string;
+  fs?: CddFileSystem;
+}) {
+  const files = createCddFileOperation({ contractRoot, fs });
+
+  return {
+    async read(input: { path: string }) {
+      return { content: await files.read(input.path), fileType: "contract" as const };
+    },
+    async rules() {
+      let entries;
+      try {
+        entries = await files.readDirectory("rules");
+      } catch (error) {
+        // SAFETY: node:fs 디렉터리 조회 실패의 code만 읽어 규칙 디렉터리 부재를 구분합니다.
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return { rules: [] };
+        throw error;
+      }
+
+      const rules = [];
+      for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".rules.json")) continue;
+        const key = entry.name.replace(/\.rules\.json$/, "");
+        const relativePath = `rules/${entry.name}`;
+        const document = parseCddRules(await files.read(relativePath));
+        rules.push({
+          key,
+          path: relativePath,
+          description: document.description ?? "",
+          ruleCount: document.rules?.length ?? 0,
+        });
+      }
+      return { rules };
+    },
+    async showRule(input: { ruleId: string }) {
+      const relativePath = `rules/${input.ruleId}.rules.json`;
+      return {
+        key: input.ruleId,
+        path: relativePath,
+        ...parseCddRules(await files.read(relativePath)),
+      };
+    },
+    async addRule(input: {
+      ruleKey: string;
+      id: string;
+      when: string;
+      text: string;
+      examples?: string[];
+      dryRun: boolean;
+    }) {
+      const rule = { ruleKey: input.ruleKey, id: input.id, when: input.when, text: input.text };
+      if (input.dryRun) return { dryRun: true as const, rule };
+
+      const relativePath = `rules/${input.ruleKey}.rules.json`;
+      const document = await readCddRuleDocument(files, relativePath);
+      document.rules ??= [];
+      document.rules.push({
+        id: input.id,
+        when: input.when,
+        instruction: input.text,
+        examples: input.examples ?? [],
+      });
+      await files.write(relativePath, `${JSON.stringify(document, null, 2)}\n`);
+      return { key: input.ruleKey, path: relativePath, ...document };
+    },
+    async addAcceptanceCriterion(input: { document: string; text: string; dryRun: boolean }) {
+      if (input.dryRun)
+        return { operation: "addAcceptanceCriterion" as const, input, dryRun: true };
+      const contents = await files.read(input.document);
+      await files.write(input.document, `${contents}\n- ${input.text}\n`);
+      return { document: input.document, text: input.text, applied: true as const };
+    },
+  };
+}