@mandujs/core 0.9.39 → 0.9.40

package/src/guard/presets/index.ts

@@ -23,94 +23,226 @@ export { atomicPreset, ATOMIC_HIERARCHY } from "./atomic";
  */
 export const manduPreset: PresetDefinition = {
   name: "mandu",
-  description: "Mandu 권장 아키텍처 - FSD + Clean Architecture 조합",
+  description: "Mandu 권장 아키텍처 - client/server 분리 + strict shared",
 
   hierarchy: [
-    // Frontend (FSD)
-    "app",
-    "pages",
-    "widgets",
-    "features",
-    "entities",
-    // Backend (Clean)
-    "api",
-    "application",
-    "domain",
-    "infra",
-    // Shared
-    "core",
-    "shared",
+    // Client (FSD)
+    "client/app",
+    "client/pages",
+    "client/widgets",
+    "client/features",
+    "client/entities",
+    "client/shared",
+    // Shared (strict)
+    "shared/contracts",
+    "shared/types",
+    "shared/utils/client",
+    "shared/utils/server",
+    "shared/schema",
+    "shared/env",
+    "shared/unsafe",
+    // Server (Clean)
+    "server/api",
+    "server/application",
+    "server/domain",
+    "server/infra",
+    "server/core",
   ],
 
   layers: [
-    // Frontend layers
+    // Client layers
     {
-      name: "app",
-      pattern: "src/app/**",
-      canImport: ["pages", "widgets", "features", "entities", "shared"],
-      description: "앱 진입점",
+      name: "client/app",
+      pattern: "src/client/app/**",
+      canImport: [
+        "client/pages",
+        "client/widgets",
+        "client/features",
+        "client/entities",
+        "client/shared",
+        "shared/contracts",
+        "shared/types",
+        "shared/utils/client",
+      ],
+      description: "클라이언트 앱 진입점",
     },
     {
-      name: "pages",
-      pattern: "src/pages/**",
-      canImport: ["widgets", "features", "entities", "shared"],
-      description: "페이지 컴포넌트",
+      name: "client/pages",
+      pattern: "src/client/pages/**",
+      canImport: [
+        "client/widgets",
+        "client/features",
+        "client/entities",
+        "client/shared",
+        "shared/contracts",
+        "shared/types",
+        "shared/utils/client",
+      ],
+      description: "클라이언트 페이지",
     },
     {
-      name: "widgets",
-      pattern: "src/widgets/**",
-      canImport: ["features", "entities", "shared"],
-      description: "독립적인 UI 블록",
+      name: "client/widgets",
+      pattern: "src/client/widgets/**",
+      canImport: [
+        "client/features",
+        "client/entities",
+        "client/shared",
+        "shared/contracts",
+        "shared/types",
+        "shared/utils/client",
+      ],
+      description: "클라이언트 위젯",
     },
     {
-      name: "features",
-      pattern: "src/features/**",
-      canImport: ["entities", "shared"],
-      description: "비즈니스 기능",
+      name: "client/features",
+      pattern: "src/client/features/**",
+      canImport: [
+        "client/entities",
+        "client/shared",
+        "shared/contracts",
+        "shared/types",
+        "shared/utils/client",
+      ],
+      description: "클라이언트 기능",
     },
     {
-      name: "entities",
-      pattern: "src/entities/**",
-      canImport: ["shared"],
-      description: "비즈니스 엔티티",
+      name: "client/entities",
+      pattern: "src/client/entities/**",
+      canImport: [
+        "client/shared",
+        "shared/contracts",
+        "shared/types",
+        "shared/utils/client",
+      ],
+      description: "클라이언트 엔티티",
     },
-    // Backend layers
     {
-      name: "api",
-      pattern: "src/api/**",
-      canImport: ["application", "domain", "core", "shared"],
-      description: "API 라우트, 컨트롤러",
+      name: "client/shared",
+      pattern: "src/client/shared/**",
+      canImport: [
+        "shared/contracts",
+        "shared/types",
+        "shared/utils/client",
+      ],
+      description: "클라이언트 전용 공유",
     },
+    // Shared layers
     {
-      name: "application",
-      pattern: "src/application/**",
-      canImport: ["domain", "core", "shared"],
-      description: "유스케이스, 서비스",
+      name: "shared/contracts",
+      pattern: "src/shared/contracts/**",
+      canImport: ["shared/types", "shared/utils/client"],
+      description: "공용 계약 (클라이언트 safe)",
     },
     {
-      name: "domain",
-      pattern: "src/domain/**",
-      canImport: ["shared"],
-      description: "도메인 모델",
+      name: "shared/schema",
+      pattern: "src/shared/schema/**",
+      canImport: ["shared/types", "shared/utils/server"],
+      description: "서버 전용 스키마 (JSON/OpenAPI)",
     },
     {
-      name: "infra",
-      pattern: "src/infra/**",
-      canImport: ["application", "domain", "core", "shared"],
-      description: "인프라 구현",
+      name: "shared/types",
+      pattern: "src/shared/types/**",
+      canImport: [],
+      description: "공용 타입",
+    },
+    {
+      name: "shared/utils/client",
+      pattern: "src/shared/utils/client/**",
+      canImport: ["shared/types"],
+      description: "클라이언트 safe 유틸",
     },
-    // Shared layers
     {
-      name: "core",
-      pattern: "src/core/**",
-      canImport: ["shared"],
-      description: "핵심 공통 (auth, config)",
+      name: "shared/utils/server",
+      pattern: "src/shared/utils/server/**",
+      canImport: ["shared/types", "shared/utils/client"],
+      description: "서버 전용 유틸",
     },
     {
-      name: "shared",
+      name: "shared/env",
+      pattern: "src/shared/env/**",
+      canImport: ["shared/types", "shared/utils/client", "shared/utils/server"],
+      description: "서버 전용 환경/설정",
+    },
+    {
+      name: "shared/unsafe",
       pattern: "src/shared/**",
       canImport: [],
-      description: "공유 유틸리티",
+      description: "금지된 shared 경로",
+    },
+    // Server layers
+    {
+      name: "server/api",
+      pattern: "src/server/api/**",
+      canImport: [
+        "server/application",
+        "server/domain",
+        "server/infra",
+        "server/core",
+        "shared/contracts",
+        "shared/schema",
+        "shared/types",
+        "shared/utils/client",
+        "shared/utils/server",
+        "shared/env",
+      ],
+      description: "서버 API 라우트, 컨트롤러",
+    },
+    {
+      name: "server/application",
+      pattern: "src/server/application/**",
+      canImport: [
+        "server/domain",
+        "server/core",
+        "shared/contracts",
+        "shared/schema",
+        "shared/types",
+        "shared/utils/client",
+        "shared/utils/server",
+        "shared/env",
+      ],
+      description: "서버 유스케이스, 서비스",
+    },
+    {
+      name: "server/domain",
+      pattern: "src/server/domain/**",
+      canImport: [
+        "shared/contracts",
+        "shared/schema",
+        "shared/types",
+        "shared/utils/client",
+        "shared/utils/server",
+        "shared/env",
+      ],
+      description: "서버 도메인 모델",
+    },
+    {
+      name: "server/infra",
+      pattern: "src/server/infra/**",
+      canImport: [
+        "server/application",
+        "server/domain",
+        "server/core",
+        "shared/contracts",
+        "shared/schema",
+        "shared/types",
+        "shared/utils/client",
+        "shared/utils/server",
+        "shared/env",
+      ],
+      description: "서버 인프라 구현",
+    },
+    {
+      name: "server/core",
+      pattern: "src/server/core/**",
+      canImport: [
+        "shared/contracts",
+        "shared/schema",
+        "shared/types",
+        "shared/utils/client",
+        "shared/utils/server",
+        "shared/env",
+      ],
+      description: "서버 핵심 공통",
     },
   ],
 
@@ -119,6 +251,7 @@ export const manduPreset: PresetDefinition = {
     circularDependency: "warn",
     crossSliceDependency: "warn",
     deepNesting: "info",
+    fileType: "error",
   },
 };
 

package/src/guard/rules.ts

@@ -64,12 +64,18 @@ export const GUARD_RULES: Record<string, GuardRule> = {
     description: "Slot 핸들러에 ctx.ok(), ctx.json() 등의 응답 패턴이 없습니다",
     severity: "error",
   },
-  SLOT_MISSING_FILLING_PATTERN: {
-    id: "SLOT_MISSING_FILLING_PATTERN",
-    name: "Slot Missing Filling Pattern",
-    description: "Slot 파일에 Mandu.filling() 패턴이 없습니다",
-    severity: "error",
-  },
+  SLOT_MISSING_FILLING_PATTERN: {
+    id: "SLOT_MISSING_FILLING_PATTERN",
+    name: "Slot Missing Filling Pattern",
+    description: "Slot 파일에 Mandu.filling() 패턴이 없습니다",
+    severity: "error",
+  },
+  SLOT_ZOD_DIRECT_IMPORT: {
+    id: "SLOT_ZOD_DIRECT_IMPORT",
+    name: "Zod Direct Import in Slot",
+    description: "Slot 파일에서 zod를 직접 import 했습니다",
+    severity: "error",
+  },
   // Contract-related rules
   CONTRACT_MISSING: {
     id: "CONTRACT_MISSING",

package/src/guard/statistics.ts

@@ -568,5 +568,11 @@ function getTypeTitle(type: ViolationType): string {
       return "Cross-Slice Dependencies";
     case "deep-nesting":
       return "Deep Nesting";
+    case "file-type":
+      return "File Type Violations";
+    case "invalid-shared-segment":
+      return "Shared Segment Violations";
+    default:
+      return "Violations";
   }
 }

package/src/guard/suggestions.ts

@@ -172,7 +172,7 @@ function generateCircularDependencySuggestions(context: SuggestionContext): stri
  */
 function generateCrossSliceSuggestions(context: SuggestionContext): string[] {
   const { fromLayer, importPath, slice } = context;
-  const toSlice = extractSliceFromPath(importPath);
+  const toSlice = extractSliceFromPath(importPath, fromLayer);
   const suggestions: string[] = [];
 
   suggestions.push(
@@ -339,7 +339,14 @@ function extractModuleName(importPath: string): string {
 /**
  * 경로에서 슬라이스 추출
  */
-function extractSliceFromPath(importPath: string): string {
+function extractSliceFromPath(importPath: string, fromLayer?: string): string {
   const parts = importPath.replace(/^[@~]\//, "").split("/");
+  if (fromLayer) {
+    const layerParts = fromLayer.split("/");
+    const matchesLayer = parts.slice(0, layerParts.length).join("/") === fromLayer;
+    if (matchesLayer && parts.length > layerParts.length) {
+      return parts[layerParts.length];
+    }
+  }
   return parts[1] ?? "unknown";
 }

package/src/guard/types.ts

@@ -37,6 +37,10 @@ export interface SeverityConfig {
   deepNesting?: Severity;
   /** 같은 레이어 내 슬라이스 간 의존 */
   crossSliceDependency?: Severity;
+  /** 파일 타입 위반 (.js/.jsx 금지 등) */
+  fileType?: Severity;
+  /** shared 하위 세그먼트 위반 */
+  invalidSharedSegment?: Severity;
 }
 
 /**
@@ -49,6 +53,8 @@ export interface FSRoutesGuardConfig {
   pageCanImport?: string[];
   /** layout.tsx가 import 가능한 레이어 */
   layoutCanImport?: string[];
+  /** route.ts가 import 가능한 레이어 */
+  routeCanImport?: string[];
 }
 
 /**
@@ -183,7 +189,9 @@ export type ViolationType =
   | "layer-violation"      // 레이어 의존 위반
   | "circular-dependency"  // 순환 의존
   | "cross-slice"          // 같은 레이어 내 슬라이스 간 의존
-  | "deep-nesting";        // 깊은 중첩 import
+  | "deep-nesting"         // 깊은 중첩 import
+  | "file-type"            // 파일 타입 위반
+  | "invalid-shared-segment"; // shared 세그먼트 위반
 
 /**
  * 아키텍처 위반
@@ -322,6 +330,8 @@ export const DEFAULT_GUARD_CONFIG: Required<Omit<GuardConfig, "preset" | "layers
     circularDependency: "warn",
     deepNesting: "info",
     crossSliceDependency: "warn",
+    fileType: "error",
+    invalidSharedSegment: "error",
   },
   realtimeOutput: "console",
   cache: true,

package/src/guard/validator.ts

@@ -72,6 +72,8 @@ export function createViolation(
     "circular-dependency": "circularDependency",
     "cross-slice": "crossSliceDependency",
     "deep-nesting": "deepNesting",
+    "file-type": "fileType",
+    "invalid-shared-segment": "invalidSharedSegment",
   };
 
   const severity: Severity = severityConfig[severityMap[type]] ?? "error";
@@ -81,6 +83,8 @@ export function createViolation(
     "circular-dependency": "Circular Dependency",
     "cross-slice": "Cross-Slice Dependency",
     "deep-nesting": "Deep Nesting",
+    "file-type": "TypeScript Only",
+    "invalid-shared-segment": "Shared Segment",
   };
 
   const ruleDescriptions: Record<ViolationType, string> = {
@@ -88,6 +92,8 @@ export function createViolation(
     "circular-dependency": `순환 의존성이 감지되었습니다: ${fromLayer} ⇄ ${toLayer}`,
     "cross-slice": `같은 레이어 내 다른 슬라이스 간 직접 import가 감지되었습니다`,
     "deep-nesting": `깊은 경로 import가 감지되었습니다. Public API를 통해 import하세요`,
+    "file-type": `JS/JSX 파일은 금지됩니다. .ts/.tsx로 변환하세요`,
+    "invalid-shared-segment": `shared 하위 세그먼트 규칙을 위반했습니다`,
   };
 
   // 스마트 제안 생성
@@ -118,6 +124,98 @@ export function createViolation(
   };
 }
 
+function createFileTypeViolation(
+  analysis: FileAnalysis,
+  severityConfig: SeverityConfig
+): Violation {
+  const severity: Severity = severityConfig.fileType ?? "error";
+  const normalizedPath = analysis.filePath.replace(/\\/g, "/");
+  const extension = normalizedPath.slice(normalizedPath.lastIndexOf("."));
+
+  return {
+    type: "file-type",
+    filePath: analysis.filePath,
+    line: 1,
+    column: 1,
+    importStatement: normalizedPath,
+    importPath: normalizedPath,
+    fromLayer: "typescript",
+    toLayer: extension,
+    ruleName: "TypeScript Only",
+    ruleDescription: `JS/JSX 파일은 금지됩니다 (${extension}). .ts/.tsx로 변환하세요`,
+    severity,
+    allowedLayers: [],
+    suggestions: [
+      "파일 확장자를 .ts 또는 .tsx로 변경하세요",
+      "필요한 타입을 추가하고 TypeScript로 변환하세요",
+    ],
+  };
+}
+
+function createInvalidSharedSegmentViolation(
+  analysis: FileAnalysis,
+  severityConfig: SeverityConfig
+): Violation {
+  const severity: Severity = severityConfig.invalidSharedSegment ?? "error";
+  const normalizedPath = analysis.filePath.replace(/\\/g, "/");
+  const marker = "src/shared/";
+  let segment = "(unknown)";
+
+  const index = normalizedPath.indexOf(marker);
+  if (index !== -1) {
+    const rest = normalizedPath.slice(index + marker.length);
+    segment = rest.split("/")[0] || "(root)";
+  }
+
+  return {
+    type: "invalid-shared-segment",
+    filePath: analysis.filePath,
+    line: 1,
+    column: 1,
+    importStatement: normalizedPath,
+    importPath: normalizedPath,
+    fromLayer: "shared",
+    toLayer: "shared/unsafe",
+    ruleName: "Shared Segment",
+    ruleDescription: `src/shared/${segment}는 허용되지 않습니다`,
+    severity,
+    allowedLayers: [],
+    suggestions: [
+      "허용 경로: src/shared/contracts|schema|types|utils/client|utils/server|env",
+      "파일을 허용된 shared 하위 폴더로 이동하세요",
+    ],
+  };
+}
+
+function createSharedEnvImportViolation(
+  analysis: FileAnalysis,
+  importInfo: ImportInfo,
+  fromLayer: string,
+  allowedLayers: string[],
+  severityConfig: SeverityConfig
+): Violation {
+  const severity: Severity = severityConfig.layerViolation ?? "error";
+
+  return {
+    type: "layer-violation",
+    filePath: analysis.filePath,
+    line: importInfo.line,
+    column: importInfo.column,
+    importStatement: importInfo.statement,
+    importPath: importInfo.path,
+    fromLayer,
+    toLayer: "shared/env",
+    ruleName: "Shared Env (Server-only)",
+    ruleDescription: "shared/env는 서버 전용입니다. 클라이언트 레이어에서 import할 수 없습니다",
+    severity,
+    allowedLayers,
+    suggestions: [
+      "환경변수 접근은 src/server 또는 app/api/route.ts에서 처리하세요",
+      "필요한 값은 서버에서 주입하거나 응답으로 전달하세요",
+    ],
+  };
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // File Validation
 // ═══════════════════════════════════════════════════════════════════════════
@@ -132,6 +230,15 @@ export function validateFileAnalysis(
 ): Violation[] {
   const violations: Violation[] = [];
   const severityConfig = config.severity ?? {};
+  const normalizedPath = analysis.filePath.toLowerCase();
+
+  if (normalizedPath.endsWith(".js") || normalizedPath.endsWith(".jsx")) {
+    violations.push(createFileTypeViolation(analysis, severityConfig));
+  }
+
+  if (analysis.layer === "shared/unsafe") {
+    violations.push(createInvalidSharedSegmentViolation(analysis, severityConfig));
+  }
 
   // FS Routes 규칙 검사 (app/ 내부)
   violations.push(...validateFsRoutesImports(analysis, layers, config));
@@ -167,6 +274,19 @@ export function validateFileAnalysis(
       continue; // 레이어를 알 수 없으면 무시
     }
 
+    if (toLayer === "shared/env" && fromLayer.startsWith("client/")) {
+      violations.push(
+        createSharedEnvImportViolation(
+          analysis,
+          importInfo,
+          fromLayer,
+          fromLayerDef?.canImport ?? [],
+          severityConfig
+        )
+      );
+      continue;
+    }
+
     // 같은 레이어 내 같은 슬라이스는 허용
     if (fromLayer === toLayer) {
       // Cross-slice 체크 (같은 레이어 내 다른 슬라이스)
@@ -257,8 +377,10 @@ function extractSliceFromImport(
   if (!layerRelative) return undefined;
 
   const parts = layerRelative.split("/");
-  if (parts[0] === layer && parts.length > 1) {
-    return parts[1];
+  const layerParts = layer.split("/");
+  const matchesLayer = parts.slice(0, layerParts.length).join("/") === layer;
+  if (matchesLayer && parts.length > layerParts.length) {
+    return parts[layerParts.length];
   }
 
   return undefined;
@@ -281,7 +403,11 @@ function validateFsRoutesImports(
   const violations: Violation[] = [];
   const severity = config.severity?.layerViolation ?? "error";
   const allowedLayers =
-    fileType === "page" ? fsRoutesConfig.pageCanImport : fsRoutesConfig.layoutCanImport;
+    fileType === "page"
+      ? fsRoutesConfig.pageCanImport
+      : fileType === "layout"
+      ? fsRoutesConfig.layoutCanImport
+      : fsRoutesConfig.routeCanImport;
 
   for (const importInfo of analysis.imports) {
     const isFsRoutesImport = isFsRoutesImportPath(importInfo.path);
@@ -323,7 +449,32 @@ function validateFsRoutesImports(
         analysis.rootDir
       );
 
+      if (toLayer === "shared/env" && fileType !== "route") {
+        violations.push(
+          createSharedEnvImportViolation(
+            analysis,
+            importInfo,
+            fileType,
+            allowedLayers,
+            config.severity ?? {}
+          )
+        );
+        continue;
+      }
+
       if (toLayer && !allowedLayers.includes(toLayer)) {
+        const fileLabel = fileType === "route" ? "route.ts" : `${fileType}.tsx`;
+        const suggestions =
+          fileType === "route"
+            ? [
+                `허용 레이어: ${allowedLayers.join(", ")}`,
+                "서버 로직은 src/server 또는 src/shared로 이동하세요",
+              ]
+            : [
+                `허용 레이어: ${allowedLayers.join(", ")}`,
+                "클라이언트 로직은 src/client 또는 src/shared로 이동하세요",
+              ];
+
         violations.push({
           type: "layer-violation",
           filePath: analysis.filePath,
@@ -334,13 +485,10 @@ function validateFsRoutesImports(
           fromLayer: fileType,
           toLayer,
           ruleName: "FS Routes Import Rule",
-          ruleDescription: `${fileType}.tsx는 지정된 레이어만 import 가능합니다`,
+          ruleDescription: `${fileLabel}는 지정된 레이어만 import 가능합니다`,
           severity,
           allowedLayers,
-          suggestions: [
-            `허용 레이어: ${allowedLayers.join(", ")}`,
-            "필요한 모듈은 widgets/features/shared로 옮겨 사용하세요",
-          ],
+          suggestions,
         });
       }
     }
@@ -349,7 +497,7 @@ function validateFsRoutesImports(
   return violations;
 }
 
-function getFsRouteFileType(analysis: FileAnalysis): "page" | "layout" | null {
+function getFsRouteFileType(analysis: FileAnalysis): "page" | "layout" | "route" | null {
   const normalizedPath = normalizePathValue(
     analysis.rootDir
       ? relative(
@@ -372,6 +520,9 @@ function getFsRouteFileType(analysis: FileAnalysis): "page" | "layout" | null {
   if (FILE_PATTERNS.layout.test(fileName)) {
     return "layout";
   }
+  if (FILE_PATTERNS.route.test(fileName)) {
+    return "route";
+  }
 
   return null;
 }

package/src/guard/watcher.ts

@@ -345,6 +345,8 @@ function countByType(violations: Violation[]): Record<ViolationType, number> {
     "circular-dependency": 0,
     "cross-slice": 0,
     "deep-nesting": 0,
+    "file-type": 0,
+    "invalid-shared-segment": 0,
   };
 
   for (const v of violations) {