@mandujs/core 0.9.1 → 0.9.3

package/src/brain/architecture/types.ts

@@ -0,0 +1,195 @@
+/**
+ * Brain v0.2 - Architecture Guard Types
+ *
+ * 프로젝트 아키텍처 규칙 정의 및 검증을 위한 타입
+ */
+
+/**
+ * 폴더 역할 정의
+ */
+export interface FolderRule {
+  /** 폴더 경로 패턴 (glob) */
+  pattern: string;
+  /** 폴더 설명/역할 */
+  description: string;
+  /** 허용되는 파일 패턴 */
+  allowedFiles?: string[];
+  /** 금지되는 파일 패턴 */
+  forbiddenFiles?: string[];
+  /** 이 폴더에서 허용되는 export */
+  allowedExports?: string[];
+  /** 수정 금지 여부 */
+  readonly?: boolean;
+}
+
+/**
+ * Import 규칙 정의
+ */
+export interface ImportRule {
+  /** 적용 대상 파일 패턴 (glob) */
+  source: string;
+  /** 허용되는 import 패턴 */
+  allow?: string[];
+  /** 금지되는 import 패턴 */
+  forbid?: string[];
+  /** 규칙 설명 */
+  reason?: string;
+}
+
+/**
+ * 레이어 의존성 규칙
+ */
+export interface LayerRule {
+  /** 레이어 이름 */
+  name: string;
+  /** 레이어에 속하는 폴더 패턴 */
+  folders: string[];
+  /** 의존 가능한 레이어 */
+  canDependOn: string[];
+  /** 의존 불가 레이어 */
+  cannotDependOn?: string[];
+}
+
+/**
+ * 네이밍 규칙
+ */
+export interface NamingRule {
+  /** 적용 대상 폴더 패턴 */
+  folder: string;
+  /** 파일명 패턴 (정규식) */
+  filePattern: string;
+  /** 규칙 설명 */
+  description: string;
+  /** 예시 */
+  examples?: string[];
+}
+
+/**
+ * 아키텍처 설정
+ */
+export interface ArchitectureConfig {
+  /** 폴더 규칙 */
+  folders?: Record<string, FolderRule | string>;
+  /** Import 규칙 */
+  imports?: ImportRule[];
+  /** 레이어 규칙 */
+  layers?: LayerRule[];
+  /** 네이밍 규칙 */
+  naming?: NamingRule[];
+  /** 커스텀 규칙 */
+  custom?: CustomRule[];
+}
+
+/**
+ * 커스텀 규칙
+ */
+export interface CustomRule {
+  /** 규칙 ID */
+  id: string;
+  /** 규칙 설명 */
+  description: string;
+  /** 파일 패턴 */
+  pattern: string;
+  /** 검증 조건 (코드에 포함되어야 하는 패턴) */
+  mustContain?: string[];
+  /** 금지 조건 (코드에 포함되면 안 되는 패턴) */
+  mustNotContain?: string[];
+}
+
+/**
+ * 아키텍처 위반
+ */
+export interface ArchitectureViolation {
+  /** 규칙 ID */
+  ruleId: string;
+  /** 규칙 타입 */
+  ruleType: "folder" | "import" | "layer" | "naming" | "custom";
+  /** 위반 파일 경로 */
+  file: string;
+  /** 위반 메시지 */
+  message: string;
+  /** 수정 제안 */
+  suggestion?: string;
+  /** 심각도 */
+  severity: "error" | "warning" | "info";
+  /** 위반 라인 (해당시) */
+  line?: number;
+}
+
+/**
+ * 위치 검증 요청
+ */
+export interface CheckLocationRequest {
+  /** 검사할 파일 경로 */
+  path: string;
+  /** 파일 내용 (선택) */
+  content?: string;
+  /** 파일 타입 */
+  fileType?: "ts" | "tsx" | "js" | "jsx" | "json" | "other";
+}
+
+/**
+ * 위치 검증 결과
+ */
+export interface CheckLocationResult {
+  /** 허용 여부 */
+  allowed: boolean;
+  /** 위반 목록 */
+  violations: ArchitectureViolation[];
+  /** LLM 제안 (활성화시) */
+  suggestion?: string;
+  /** 권장 경로 */
+  recommendedPath?: string;
+}
+
+/**
+ * Import 검증 요청
+ */
+export interface CheckImportRequest {
+  /** 소스 파일 경로 */
+  sourceFile: string;
+  /** 검사할 import 문 */
+  imports: string[];
+}
+
+/**
+ * Import 검증 결과
+ */
+export interface CheckImportResult {
+  /** 모든 import 허용 여부 */
+  allowed: boolean;
+  /** 위반된 import 목록 */
+  violations: Array<{
+    import: string;
+    reason: string;
+    suggestion?: string;
+  }>;
+}
+
+/**
+ * 프로젝트 구조 정보
+ */
+export interface ProjectStructure {
+  /** 루트 디렉토리 */
+  rootDir: string;
+  /** 폴더 트리 */
+  folders: FolderInfo[];
+  /** 아키텍처 설정 */
+  config: ArchitectureConfig;
+  /** 인덱싱 시간 */
+  indexedAt: string;
+}
+
+/**
+ * 폴더 정보
+ */
+export interface FolderInfo {
+  /** 경로 */
+  path: string;
+  /** 역할 설명 */
+  description?: string;
+  /** 파일 수 */
+  fileCount: number;
+  /** 하위 폴더 */
+  children?: FolderInfo[];
+}

package/src/brain/index.ts

@@ -1,9 +1,10 @@
 /**
- * Brain v0.1 - Module Exports
+ * Brain v0.2 - Module Exports
  *
- * Brain handles two responsibilities:
+ * Brain handles three responsibilities:
  * 1. Doctor (error recovery): Guard failure analysis + minimal patch suggestions
  * 2. Watch (error prevention): File change warnings (no blocking)
+ * 3. Architecture (structure enforcement): Project structure validation for coding agents
  */
 
 // Types
@@ -43,3 +44,6 @@ export {
 
 // Doctor
 export * from "./doctor";
+
+// Architecture (v0.2)
+export * from "./architecture";

package/src/client/index.ts

@@ -103,8 +103,9 @@ import { Link, NavLink } from "./Link";
 /**
  * Mandu Client namespace
  * v0.8.0: Hydration은 자동으로 처리됨 (generateRuntimeSource에서 생성)
+ * Note: Use `ManduClient` to avoid conflict with other Mandu exports
  */
-export const Mandu = {
+export const ManduClient = {
   /**
    * Create an island component
    * @see island

package/src/contract/client.test.ts

@@ -0,0 +1,308 @@
+/**
+ * Mandu Contract Client Tests
+ *
+ * 클라이언트 타입 추론 및 기능 테스트
+ */
+
+import { describe, it, expect, mock } from "bun:test";
+import { z } from "zod";
+import { Mandu, createClient, contractFetch } from "./index";
+
+// === Test Contract ===
+const testContract = Mandu.contract({
+  description: "Test API",
+  tags: ["test"],
+  request: {
+    GET: {
+      query: z.object({
+        page: z.coerce.number().default(1),
+        search: z.string().optional(),
+      }),
+    },
+    POST: {
+      body: z.object({
+        name: z.string(),
+        email: z.string().email(),
+      }),
+    },
+    PUT: {
+      params: z.object({
+        id: z.string(),
+      }),
+      body: z.object({
+        name: z.string().optional(),
+      }),
+    },
+    DELETE: {
+      params: z.object({
+        id: z.string(),
+      }),
+    },
+  },
+  response: {
+    200: z.object({
+      data: z.array(
+        z.object({
+          id: z.string(),
+          name: z.string(),
+        })
+      ),
+      total: z.number(),
+    }),
+    201: z.object({
+      data: z.object({
+        id: z.string(),
+        name: z.string(),
+        email: z.string(),
+      }),
+    }),
+    204: z.undefined(),
+    404: z.object({
+      error: z.string(),
+    }),
+  },
+});
+
+describe("Contract Client", () => {
+  it("should create a client with all HTTP methods", () => {
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+    });
+
+    expect(client.GET).toBeDefined();
+    expect(client.POST).toBeDefined();
+    expect(client.PUT).toBeDefined();
+    expect(client.DELETE).toBeDefined();
+    expect(typeof client.GET).toBe("function");
+    expect(typeof client.POST).toBe("function");
+  });
+
+  it("should build query string correctly", async () => {
+    let capturedUrl = "";
+
+    const mockFetch = mock(async (url: string, _options: RequestInit) => {
+      capturedUrl = url;
+      return new Response(JSON.stringify({ data: [], total: 0 }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+      fetch: mockFetch as unknown as typeof fetch,
+    });
+
+    await client.GET({ query: { page: 2, search: "hello" } });
+
+    expect(capturedUrl).toContain("page=2");
+    expect(capturedUrl).toContain("search=hello");
+  });
+
+  it("should send JSON body for POST requests", async () => {
+    let capturedBody = "";
+    let capturedContentType = "";
+
+    const mockFetch = mock(async (_url: string, options: RequestInit) => {
+      capturedBody = options.body as string;
+      capturedContentType =
+        (options.headers as Record<string, string>)["Content-Type"] || "";
+      return new Response(
+        JSON.stringify({
+          data: { id: "1", name: "Test", email: "test@example.com" },
+        }),
+        {
+          status: 201,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    });
+
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+      fetch: mockFetch as unknown as typeof fetch,
+    });
+
+    await client.POST({ body: { name: "Test", email: "test@example.com" } });
+
+    expect(capturedContentType).toBe("application/json");
+    expect(JSON.parse(capturedBody)).toEqual({
+      name: "Test",
+      email: "test@example.com",
+    });
+  });
+
+  it("should parse JSON response", async () => {
+    const mockData = {
+      data: [
+        { id: "1", name: "User 1" },
+        { id: "2", name: "User 2" },
+      ],
+      total: 2,
+    };
+
+    const mockFetch = mock(async () => {
+      return new Response(JSON.stringify(mockData), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+      fetch: mockFetch as unknown as typeof fetch,
+    });
+
+    const result = await client.GET({ query: { page: 1 } });
+
+    expect(result.status).toBe(200);
+    expect(result.ok).toBe(true);
+    expect(result.data).toEqual(mockData);
+  });
+
+  it("should include default headers", async () => {
+    let capturedHeaders: Record<string, string> = {};
+
+    const mockFetch = mock(async (_url: string, options: RequestInit) => {
+      capturedHeaders = options.headers as Record<string, string>;
+      return new Response(JSON.stringify({ data: [], total: 0 }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+      headers: {
+        Authorization: "Bearer token123",
+        "X-Custom-Header": "custom-value",
+      },
+      fetch: mockFetch as unknown as typeof fetch,
+    });
+
+    await client.GET();
+
+    expect(capturedHeaders["Authorization"]).toBe("Bearer token123");
+    expect(capturedHeaders["X-Custom-Header"]).toBe("custom-value");
+  });
+
+  it("should allow per-request headers", async () => {
+    let capturedHeaders: Record<string, string> = {};
+
+    const mockFetch = mock(async (_url: string, options: RequestInit) => {
+      capturedHeaders = options.headers as Record<string, string>;
+      return new Response(JSON.stringify({ data: [], total: 0 }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+      headers: { "X-Default": "default" },
+      fetch: mockFetch as unknown as typeof fetch,
+    });
+
+    await client.GET({
+      headers: { "X-Custom": "per-request" },
+    });
+
+    expect(capturedHeaders["X-Default"]).toBe("default");
+    expect(capturedHeaders["X-Custom"]).toBe("per-request");
+  });
+});
+
+describe("contractFetch", () => {
+  it("should make type-safe fetch call", async () => {
+    const mockFetch = mock(async () => {
+      return new Response(JSON.stringify({ data: [], total: 0 }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    const result = await contractFetch(
+      testContract,
+      "GET",
+      "http://localhost:3000/api/test",
+      { query: { page: 1 } },
+      { fetch: mockFetch as unknown as typeof fetch }
+    );
+
+    expect(result.status).toBe(200);
+    expect(result.ok).toBe(true);
+    expect(mockFetch).toHaveBeenCalled();
+  });
+
+  it("should handle path parameters", async () => {
+    let capturedUrl = "";
+
+    const mockFetch = mock(async (url: string) => {
+      capturedUrl = url;
+      return new Response(JSON.stringify({ data: [], total: 0 }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    await contractFetch(
+      testContract,
+      "PUT",
+      "http://localhost:3000/api/test/:id",
+      { params: { id: "123" }, body: { name: "Updated" } },
+      { fetch: mockFetch as unknown as typeof fetch }
+    );
+
+    expect(capturedUrl).toBe("http://localhost:3000/api/test/123");
+  });
+});
+
+describe("Mandu.client", () => {
+  it("should be accessible via Mandu namespace", () => {
+    expect(Mandu.client).toBe(createClient);
+  });
+
+  it("should work via Mandu namespace", async () => {
+    const mockFetch = mock(async () => {
+      return new Response(JSON.stringify({ data: [], total: 0 }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+
+    const client = Mandu.client(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+      fetch: mockFetch as unknown as typeof fetch,
+    });
+
+    const result = await client.GET({ query: { page: 1 } });
+
+    expect(result.status).toBe(200);
+    expect(result.data).toEqual({ data: [], total: 0 });
+  });
+});
+
+describe("Mandu.fetch", () => {
+  it("should be accessible via Mandu namespace", () => {
+    expect(Mandu.fetch).toBe(contractFetch);
+  });
+});
+
+describe("Type Safety (Compile-time)", () => {
+  it("should enforce query types", () => {
+    // This test verifies that the type system is working
+    // If the types are wrong, this won't compile
+    const client = createClient(testContract, {
+      baseUrl: "http://localhost:3000/api/test",
+    });
+
+    // These are valid calls (would compile)
+    const _validGet = () => client.GET({ query: { page: 1 } });
+    const _validPost = () =>
+      client.POST({ body: { name: "Test", email: "test@example.com" } });
+
+    // Type-level assertions
+    expect(typeof client.GET).toBe("function");
+    expect(typeof client.POST).toBe("function");
+  });
+});