@mandujs/core 0.10.0 → 0.11.0

package/README.md

@@ -72,16 +72,20 @@ const handlers = Mandu.handler(userContract, {
 
 ```
 @mandujs/core
-├── router/      # FS Routes - file-system based routing
-├── guard/       # Mandu Guard - architecture enforcement
-├── runtime/     # Server, SSR, streaming
-├── filling/     # Handler chain API (Mandu.filling())
-├── contract/    # Type-safe API contracts
-├── bundler/     # Client bundling, HMR
-├── client/      # Island hydration, client router
-├── brain/       # Doctor, Watcher, Architecture analyzer
-├── change/      # Transaction & history
-└── spec/        # Manifest schema & validation
+├── router/          # FS Routes - file-system based routing
+├── guard/           # Mandu Guard - architecture enforcement
+│   ├── healing      # Self-Healing Guard with auto-fix
+│   ├── decision-memory   # ADR storage (RFC-001)
+│   ├── semantic-slots    # Constraint validation (RFC-001)
+│   └── negotiation       # AI-Framework dialog (RFC-001)
+├── runtime/         # Server, SSR, streaming
+├── filling/         # Handler chain API (Mandu.filling())
+├── contract/        # Type-safe API contracts
+├── bundler/         # Client bundling, HMR
+├── client/          # Island hydration, client router
+├── brain/           # Doctor, Watcher, Architecture analyzer
+├── change/          # Transaction & history
+└── spec/            # Manifest schema & validation
 ```
 
 ---
@@ -201,6 +205,71 @@ console.log(trend.trend); // "improving" | "stable" | "degrading"
 const markdown = generateGuardMarkdownReport(report, trend);
 ```
 
+### Self-Healing Guard (RFC-001) 🆕
+
+```typescript
+import { checkWithHealing, healAll, explainRule } from "@mandujs/core/guard";
+
+// Detect violations with fix suggestions
+const result = await checkWithHealing({ preset: "mandu" }, process.cwd());
+
+// Auto-fix all fixable violations
+if (result.items.length > 0) {
+  const healResult = await healAll(result);
+  console.log(`Fixed: ${healResult.fixed}, Failed: ${healResult.failed}`);
+}
+
+// Explain any rule
+const explanation = explainRule("layer-dependency");
+console.log(explanation.description, explanation.examples);
+```
+
+### Decision Memory (RFC-001) 🆕
+
+```typescript
+import {
+  searchDecisions,
+  saveDecision,
+  checkConsistency,
+  getCompactArchitecture
+} from "@mandujs/core/guard";
+
+// Search past decisions
+const results = await searchDecisions(rootDir, ["auth", "jwt"]);
+
+// Save new decision (ADR)
+await saveDecision(rootDir, {
+  id: "ADR-002",
+  title: "Use PostgreSQL",
+  status: "accepted",
+  context: "Need relational database",
+  decision: "Use PostgreSQL with Drizzle ORM",
+  consequences: ["Need to manage migrations"],
+  tags: ["database", "orm"]
+});
+
+// Check implementation consistency
+const consistency = await checkConsistency(rootDir);
+```
+
+### Architecture Negotiation (RFC-001) 🆕
+
+```typescript
+import { negotiate, generateScaffold } from "@mandujs/core/guard";
+
+// AI negotiates with framework before implementation
+const plan = await negotiate({
+  intent: "Add user authentication",
+  requirements: ["JWT based", "Refresh tokens"],
+  constraints: ["Use existing User model"]
+}, projectRoot);
+
+if (plan.approved) {
+  // Generate scaffold files
+  await generateScaffold(plan.structure, projectRoot);
+}
+```
+
 ---
 
 ## Filling API

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/config/index.ts

@@ -1,5 +1,6 @@
 export * from "./mandu";
 export * from "./validate";
+export * from "./watcher";
 
 // Symbol 메타데이터 (Phase 3)
 export * from "./symbols.js";

package/src/config/validate.ts

@@ -1,78 +1,135 @@
-import { z, ZodError } from "zod";
+import { z, ZodError, ZodIssueCode } from "zod";
 import path from "path";
 import { pathToFileURL } from "url";
 import { CONFIG_FILES, coerceConfig } from "./mandu";
 import { readJsonFile } from "../utils/bun";
 
 /**
- * Mandu 설정 스키마
+ * DNA-003: Strict mode schema helper
+ *
+ * Creates a schema that warns about unknown keys instead of failing
+ * This provides the benefits of .strict() while maintaining compatibility
+ */
+function strictWithWarnings<T extends z.ZodRawShape>(
+  schema: z.ZodObject<T>,
+  schemaName: string
+): z.ZodObject<T> {
+  return schema.superRefine((data, ctx) => {
+    if (typeof data !== "object" || data === null) return;
+
+    const knownKeys = new Set(Object.keys(schema.shape));
+    const unknownKeys = Object.keys(data).filter((key) => !knownKeys.has(key));
+
+    if (unknownKeys.length > 0 && process.env.MANDU_STRICT !== "0") {
+      // In strict mode (default), add warnings to issues
+      for (const key of unknownKeys) {
+        ctx.addIssue({
+          code: ZodIssueCode.unrecognized_keys,
+          keys: [key],
+          message: `Unknown key '${key}' in ${schemaName}. Did you mean one of: ${[...knownKeys].join(", ")}?`,
+        });
+      }
+    }
+  });
+}
+
+/**
+ * Server 설정 스키마 (strict)
+ */
+const ServerConfigSchema = z
+  .object({
+    port: z.number().min(1).max(65535).default(3000),
+    hostname: z.string().default("localhost"),
+    cors: z
+      .union([
+        z.boolean(),
+        z.object({
+          origin: z.union([z.string(), z.array(z.string())]).optional(),
+          methods: z.array(z.string()).optional(),
+          credentials: z.boolean().optional(),
+        }).strict(),
+      ])
+      .default(false),
+    streaming: z.boolean().default(false),
+  })
+  .strict();
+
+/**
+ * Guard 설정 스키마 (strict)
+ */
+const GuardConfigSchema = z
+  .object({
+    preset: z.enum(["mandu", "fsd", "clean", "hexagonal", "atomic"]).default("mandu"),
+    srcDir: z.string().default("src"),
+    exclude: z.array(z.string()).default([]),
+    realtime: z.boolean().default(true),
+    rules: z.record(z.enum(["error", "warn", "warning", "off"])).optional(),
+  })
+  .strict();
+
+/**
+ * Build 설정 스키마 (strict)
+ */
+const BuildConfigSchema = z
+  .object({
+    outDir: z.string().default(".mandu"),
+    minify: z.boolean().default(true),
+    sourcemap: z.boolean().default(false),
+    splitting: z.boolean().default(false),
+  })
+  .strict();
+
+/**
+ * Dev 설정 스키마 (strict)
+ */
+const DevConfigSchema = z
+  .object({
+    hmr: z.boolean().default(true),
+    watchDirs: z.array(z.string()).default([]),
+  })
+  .strict();
+
+/**
+ * FS Routes 설정 스키마 (strict)
+ */
+const FsRoutesConfigSchema = z
+  .object({
+    routesDir: z.string().default("app"),
+    extensions: z.array(z.string()).default([".tsx", ".ts", ".jsx", ".js"]),
+    exclude: z.array(z.string()).default([]),
+    islandSuffix: z.string().default(".island"),
+    legacyManifestPath: z.string().optional(),
+    mergeWithLegacy: z.boolean().default(true),
+  })
+  .strict();
+
+/**
+ * SEO 설정 스키마 (strict)
+ */
+const SeoConfigSchema = z
+  .object({
+    enabled: z.boolean().default(true),
+    defaultTitle: z.string().optional(),
+    titleTemplate: z.string().optional(),
+  })
+  .strict();
+
+/**
+ * Mandu 설정 스키마 (DNA-003: strict mode)
+ *
+ * 알 수 없는 키가 있으면 오류 발생 → 오타 즉시 감지
+ * MANDU_STRICT=0 으로 비활성화 가능
  */
 export const ManduConfigSchema = z
   .object({
-    server: z
-      .object({
-        port: z.number().min(1).max(65535).default(3000),
-        hostname: z.string().default("localhost"),
-        cors: z
-          .union([
-            z.boolean(),
-            z.object({
-              origin: z.union([z.string(), z.array(z.string())]).optional(),
-              methods: z.array(z.string()).optional(),
-              credentials: z.boolean().optional(),
-            }),
-          ])
-          .default(false),
-        streaming: z.boolean().default(false),
-      })
-      .default({}),
-
-    guard: z
-      .object({
-        preset: z.enum(["mandu", "fsd", "clean", "hexagonal", "atomic"]).default("mandu"),
-        srcDir: z.string().default("src"),
-        exclude: z.array(z.string()).default([]),
-        realtime: z.boolean().default(true),
-        rules: z.record(z.enum(["error", "warn", "warning", "off"])).optional(),
-      })
-      .default({}),
-
-    build: z
-      .object({
-        outDir: z.string().default(".mandu"),
-        minify: z.boolean().default(true),
-        sourcemap: z.boolean().default(false),
-        splitting: z.boolean().default(false),
-      })
-      .default({}),
-
-    dev: z
-      .object({
-        hmr: z.boolean().default(true),
-        watchDirs: z.array(z.string()).default([]),
-      })
-      .default({}),
-
-    fsRoutes: z
-      .object({
-        routesDir: z.string().default("app"),
-        extensions: z.array(z.string()).default([".tsx", ".ts", ".jsx", ".js"]),
-        exclude: z.array(z.string()).default([]),
-        islandSuffix: z.string().default(".island"),
-        legacyManifestPath: z.string().optional(),
-        mergeWithLegacy: z.boolean().default(true),
-      })
-      .default({}),
-
-    seo: z
-      .object({
-        enabled: z.boolean().default(true),
-        defaultTitle: z.string().optional(),
-        titleTemplate: z.string().optional(),
-      })
-      .default({}),
+    server: ServerConfigSchema.default({}),
+    guard: GuardConfigSchema.default({}),
+    build: BuildConfigSchema.default({}),
+    dev: DevConfigSchema.default({}),
+    fsRoutes: FsRoutesConfigSchema.default({}),
+    seo: SeoConfigSchema.default({}),
   })
-  .passthrough();
+  .strict();
 
 export type ValidatedManduConfig = z.infer<typeof ManduConfigSchema>;
 

package/src/config/watcher.ts

@@ -0,0 +1,311 @@
+/**
+ * DNA-006: Config Hot Reload
+ *
+ * 설정 파일 변경 감시 및 핫 리로드
+ * - 디바운스로 연속 변경 병합
+ * - 에러 발생 시 기존 설정 유지
+ * - 클린업 함수 반환
+ */
+
+import { watch, type FSWatcher } from "fs";
+import { loadManduConfig, type ManduConfig } from "./mandu.js";
+
+/**
+ * 설정 변경 이벤트 타입
+ */
+export type ConfigChangeEvent = {
+  /** 이전 설정 */
+  previous: ManduConfig;
+  /** 새 설정 */
+  current: ManduConfig;
+  /** 변경된 파일 경로 */
+  path: string;
+  /** 변경 시간 */
+  timestamp: Date;
+};
+
+/**
+ * 설정 감시 옵션
+ */
+export interface WatchConfigOptions {
+  /** 디바운스 딜레이 (ms, 기본: 100) */
+  debounceMs?: number;
+  /** 초기 로드 시에도 콜백 호출 (기본: false) */
+  immediate?: boolean;
+  /** 에러 핸들러 */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * 설정 변경 콜백
+ */
+export type ConfigChangeCallback = (
+  newConfig: ManduConfig,
+  event: ConfigChangeEvent
+) => void;
+
+/**
+ * 설정 감시 결과
+ */
+export interface ConfigWatcher {
+  /** 감시 중지 */
+  stop: () => void;
+  /** 현재 설정 */
+  getConfig: () => ManduConfig;
+  /** 수동 리로드 */
+  reload: () => Promise<ManduConfig>;
+}
+
+/**
+ * 설정 파일 감시 및 핫 리로드
+ *
+ * @example
+ * ```ts
+ * const watcher = await watchConfig(
+ *   "/path/to/project",
+ *   (newConfig, event) => {
+ *     console.log("Config changed:", event.path);
+ *     applyConfig(newConfig);
+ *   },
+ *   { debounceMs: 200 }
+ * );
+ *
+ * // 나중에 정리
+ * watcher.stop();
+ * ```
+ */
+export async function watchConfig(
+  rootDir: string,
+  onReload: ConfigChangeCallback,
+  options: WatchConfigOptions = {}
+): Promise<ConfigWatcher> {
+  const { debounceMs = 100, immediate = false, onError } = options;
+
+  // 현재 설정 로드
+  let currentConfig = await loadManduConfig(rootDir);
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let watchers: FSWatcher[] = [];
+  let isWatching = true;
+
+  // 감시 대상 파일들
+  const configFiles = [
+    "mandu.config.ts",
+    "mandu.config.js",
+    "mandu.config.json",
+    ".mandu/guard.json",
+  ];
+
+  /**
+   * 설정 리로드 수행
+   */
+  const doReload = async (changedPath: string): Promise<void> => {
+    if (!isWatching) return;
+
+    try {
+      const previous = currentConfig;
+      const newConfig = await loadManduConfig(rootDir);
+
+      // 설정이 동일하면 무시
+      if (JSON.stringify(previous) === JSON.stringify(newConfig)) {
+        return;
+      }
+
+      // 이전에 설정이 있었는데 새 설정이 비어있으면 (파싱 에러 등)
+      // 기존 설정 유지하고 에러 핸들러 호출
+      const previousHasContent = Object.keys(previous).length > 0;
+      const newIsEmpty = Object.keys(newConfig).length === 0;
+
+      if (previousHasContent && newIsEmpty) {
+        if (onError) {
+          onError(new Error(`Failed to reload config from ${changedPath}`));
+        }
+        return; // 기존 설정 유지
+      }
+
+      currentConfig = newConfig;
+
+      const event: ConfigChangeEvent = {
+        previous,
+        current: newConfig,
+        path: changedPath,
+        timestamp: new Date(),
+      };
+
+      onReload(newConfig, event);
+    } catch (error) {
+      if (onError && error instanceof Error) {
+        onError(error);
+      }
+      // 에러 시 기존 설정 유지
+    }
+  };
+
+  /**
+   * 디바운스된 리로드
+   */
+  const scheduleReload = (changedPath: string): void => {
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      doReload(changedPath);
+    }, debounceMs);
+  };
+
+  // 각 설정 파일 감시 시작
+  for (const fileName of configFiles) {
+    const filePath = `${rootDir}/${fileName}`;
+
+    try {
+      const watcher = watch(filePath, (eventType) => {
+        if (eventType === "change" && isWatching) {
+          scheduleReload(filePath);
+        }
+      });
+
+      watcher.on("error", () => {
+        // 파일이 없거나 접근 불가 - 무시
+      });
+
+      watchers.push(watcher);
+    } catch {
+      // 파일이 없으면 감시 생략
+    }
+  }
+
+  // 초기 콜백 호출
+  if (immediate) {
+    const event: ConfigChangeEvent = {
+      previous: {},
+      current: currentConfig,
+      path: rootDir,
+      timestamp: new Date(),
+    };
+    onReload(currentConfig, event);
+  }
+
+  return {
+    stop: () => {
+      isWatching = false;
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      for (const watcher of watchers) {
+        watcher.close();
+      }
+      watchers = [];
+    },
+
+    getConfig: () => currentConfig,
+
+    reload: async () => {
+      const previous = currentConfig;
+      currentConfig = await loadManduConfig(rootDir);
+
+      if (JSON.stringify(previous) !== JSON.stringify(currentConfig)) {
+        const event: ConfigChangeEvent = {
+          previous,
+          current: currentConfig,
+          path: rootDir,
+          timestamp: new Date(),
+        };
+        onReload(currentConfig, event);
+      }
+
+      return currentConfig;
+    },
+  };
+}
+
+/**
+ * 간단한 단일 파일 감시
+ *
+ * @example
+ * ```ts
+ * const stop = watchConfigFile(
+ *   "/path/to/mandu.config.ts",
+ *   async (path) => {
+ *     const config = await loadManduConfig(dirname(path));
+ *     applyConfig(config);
+ *   }
+ * );
+ *
+ * // 정리
+ * stop();
+ * ```
+ */
+export function watchConfigFile(
+  filePath: string,
+  onChange: (path: string) => void,
+  debounceMs = 100
+): () => void {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let watcher: FSWatcher | null = null;
+
+  try {
+    watcher = watch(filePath, (eventType) => {
+      if (eventType === "change") {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => {
+          timer = null;
+          onChange(filePath);
+        }, debounceMs);
+      }
+    });
+  } catch {
+    // 파일 없음 - 빈 함수 반환
+    return () => {};
+  }
+
+  return () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (watcher) {
+      watcher.close();
+      watcher = null;
+    }
+  };
+}
+
+/**
+ * 설정 변경 감지 헬퍼
+ *
+ * 특정 설정 섹션의 변경 여부 확인
+ */
+export function hasConfigChanged(
+  previous: ManduConfig,
+  current: ManduConfig,
+  section?: keyof ManduConfig
+): boolean {
+  if (section) {
+    return JSON.stringify(previous[section]) !== JSON.stringify(current[section]);
+  }
+  return JSON.stringify(previous) !== JSON.stringify(current);
+}
+
+/**
+ * 변경된 설정 섹션 목록
+ */
+export function getChangedSections(
+  previous: ManduConfig,
+  current: ManduConfig
+): (keyof ManduConfig)[] {
+  const sections: (keyof ManduConfig)[] = [
+    "server",
+    "guard",
+    "build",
+    "dev",
+    "fsRoutes",
+    "seo",
+  ];
+
+  return sections.filter(
+    (section) =>
+      JSON.stringify(previous[section]) !== JSON.stringify(current[section])
+  );
+}