@mandujs/core 0.9.46 → 0.11.0

package/src/config/metadata.ts

@@ -0,0 +1,293 @@
+/**
+ * Mandu Symbol 메타데이터 유틸리티 🏷️
+ *
+ * Zod 스키마에 메타데이터를 부착하고 조회하는 유틸리티
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ * import { withMetadata, getMetadata, SENSITIVE_FIELD } from "./metadata";
+ *
+ * const tokenSchema = withMetadata(
+ *   z.string(),
+ *   SENSITIVE_FIELD,
+ *   { redactIn: ["log", "diff"] }
+ * );
+ *
+ * const metadata = getMetadata(tokenSchema, SENSITIVE_FIELD);
+ * // { redactIn: ["log", "diff"] }
+ * ```
+ */
+
+import type { z } from "zod";
+import {
+  type SymbolMetadataMap,
+  ALL_METADATA_SYMBOLS,
+  isManduMetadataSymbol,
+  SENSITIVE_FIELD,
+  PROTECTED_FIELD,
+  FIELD_SOURCE,
+  SCHEMA_REFERENCE,
+  VALIDATION_CONTEXT,
+} from "./symbols.js";
+
+// ============================================
+// 메타데이터 부착
+// ============================================
+
+/**
+ * Zod 스키마에 메타데이터 부착
+ *
+ * @param schema Zod 스키마
+ * @param key 메타데이터 심볼 키
+ * @param value 메타데이터 값
+ * @returns 메타데이터가 부착된 스키마 (원본 수정)
+ *
+ * @example
+ * ```typescript
+ * const schema = withMetadata(
+ *   z.string(),
+ *   SENSITIVE_FIELD,
+ *   { redactIn: ["log"] }
+ * );
+ * ```
+ */
+export function withMetadata<
+  T extends z.ZodType,
+  K extends keyof SymbolMetadataMap,
+>(
+  schema: T,
+  key: K,
+  value: SymbolMetadataMap[K]
+): T {
+  (schema as any)[key] = value;
+  return schema;
+}
+
+/**
+ * 여러 메타데이터를 한 번에 부착
+ *
+ * @example
+ * ```typescript
+ * const schema = withMetadataMultiple(z.string(), [
+ *   [SENSITIVE_FIELD, { redactIn: ["log"] }],
+ *   [PROTECTED_FIELD, { reason: "Security" }],
+ * ]);
+ * ```
+ */
+export function withMetadataMultiple<T extends z.ZodType>(
+  schema: T,
+  entries: Array<[symbol, unknown]>
+): T {
+  for (const [key, value] of entries) {
+    (schema as any)[key] = value;
+  }
+  return schema;
+}
+
+// ============================================
+// 메타데이터 조회
+// ============================================
+
+/**
+ * 스키마에서 메타데이터 조회
+ *
+ * @param schema Zod 스키마
+ * @param key 메타데이터 심볼 키
+ * @returns 메타데이터 값 또는 undefined
+ */
+export function getMetadata<K extends keyof SymbolMetadataMap>(
+  schema: z.ZodType,
+  key: K
+): SymbolMetadataMap[K] | undefined {
+  return (schema as any)[key];
+}
+
+/**
+ * 스키마에 특정 메타데이터가 있는지 확인
+ */
+export function hasMetadata(schema: z.ZodType, key: symbol): boolean {
+  return key in (schema as any);
+}
+
+/**
+ * 스키마의 모든 mandu 메타데이터 조회
+ */
+export function getAllMetadata(
+  schema: z.ZodType
+): Partial<SymbolMetadataMap> {
+  const result: Partial<SymbolMetadataMap> = {};
+
+  for (const sym of ALL_METADATA_SYMBOLS) {
+    if (sym in (schema as any)) {
+      (result as any)[sym] = (schema as any)[sym];
+    }
+  }
+
+  return result;
+}
+
+// ============================================
+// 메타데이터 제거
+// ============================================
+
+/**
+ * 스키마에서 메타데이터 제거
+ */
+export function removeMetadata<T extends z.ZodType>(
+  schema: T,
+  key: symbol
+): T {
+  delete (schema as any)[key];
+  return schema;
+}
+
+/**
+ * 스키마에서 모든 mandu 메타데이터 제거
+ */
+export function clearAllMetadata<T extends z.ZodType>(schema: T): T {
+  for (const sym of ALL_METADATA_SYMBOLS) {
+    if (sym in (schema as any)) {
+      delete (schema as any)[sym];
+    }
+  }
+  return schema;
+}
+
+// ============================================
+// 메타데이터 복사
+// ============================================
+
+/**
+ * 한 스키마의 메타데이터를 다른 스키마로 복사
+ */
+export function copyMetadata<T extends z.ZodType>(
+  from: z.ZodType,
+  to: T
+): T {
+  for (const sym of ALL_METADATA_SYMBOLS) {
+    if (sym in (from as any)) {
+      (to as any)[sym] = (from as any)[sym];
+    }
+  }
+  return to;
+}
+
+// ============================================
+// 스키마 체인 헬퍼
+// ============================================
+
+/**
+ * 메타데이터와 함께 스키마를 체이닝하기 위한 빌더
+ *
+ * @example
+ * ```typescript
+ * const schema = schemaWithMeta(z.string())
+ *   .sensitive({ redactIn: ["log"] })
+ *   .protected({ reason: "Security" })
+ *   .build();
+ * ```
+ */
+export function schemaWithMeta<T extends z.ZodType>(schema: T) {
+  return new SchemaMetaBuilder(schema);
+}
+
+class SchemaMetaBuilder<T extends z.ZodType> {
+  constructor(private schema: T) {}
+
+  /**
+   * 민감 필드로 마킹
+   */
+  sensitive(meta: SymbolMetadataMap[typeof SENSITIVE_FIELD]) {
+    withMetadata(this.schema, SENSITIVE_FIELD, meta);
+    return this;
+  }
+
+  /**
+   * 보호된 필드로 마킹
+   */
+  protected(meta: SymbolMetadataMap[typeof PROTECTED_FIELD]) {
+    withMetadata(this.schema, PROTECTED_FIELD, meta);
+    return this;
+  }
+
+  /**
+   * 필드 소스 설정
+   */
+  source(meta: SymbolMetadataMap[typeof FIELD_SOURCE]) {
+    withMetadata(this.schema, FIELD_SOURCE, meta);
+    return this;
+  }
+
+  /**
+   * 스키마 참조 설정
+   */
+  ref(meta: SymbolMetadataMap[typeof SCHEMA_REFERENCE]) {
+    withMetadata(this.schema, SCHEMA_REFERENCE, meta);
+    return this;
+  }
+
+  /**
+   * 검증 컨텍스트 설정
+   */
+  validation(meta: SymbolMetadataMap[typeof VALIDATION_CONTEXT]) {
+    withMetadata(this.schema, VALIDATION_CONTEXT, meta);
+    return this;
+  }
+
+  /**
+   * 커스텀 메타데이터 추가
+   */
+  meta<K extends keyof SymbolMetadataMap>(key: K, value: SymbolMetadataMap[K]) {
+    withMetadata(this.schema, key, value);
+    return this;
+  }
+
+  /**
+   * 스키마 반환
+   */
+  build(): T {
+    return this.schema;
+  }
+}
+
+// ============================================
+// 유틸리티
+// ============================================
+
+/**
+ * 객체의 모든 Symbol 키 가져오기
+ */
+export function getSymbolKeys(obj: object): symbol[] {
+  return Object.getOwnPropertySymbols(obj);
+}
+
+/**
+ * mandu 메타데이터 심볼만 필터링
+ */
+export function getManduSymbolKeys(obj: object): symbol[] {
+  return getSymbolKeys(obj).filter(isManduMetadataSymbol);
+}
+
+/**
+ * 스키마에 메타데이터가 있는지 확인
+ */
+export function hasAnyMetadata(schema: z.ZodType): boolean {
+  return getManduSymbolKeys(schema as any).length > 0;
+}
+
+/**
+ * 메타데이터를 일반 객체로 직렬화 (디버깅용)
+ */
+export function serializeMetadata(
+  schema: z.ZodType
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const sym of getManduSymbolKeys(schema as any)) {
+    const name = sym.description ?? sym.toString();
+    result[name] = (schema as any)[sym];
+  }
+
+  return result;
+}

package/src/config/symbols.ts

@@ -0,0 +1,144 @@
+/**
+ * Mandu Symbol 상수 정의 🔣
+ *
+ * ont-run의 Symbol 기반 메타데이터 패턴 참고
+ * @see DNA/ont-run/src/config/categorical.ts
+ * @see docs/plans/08_ont-run_adoption_plan.md - 섹션 3.2
+ *
+ * Symbol.for()를 사용하여 전역 심볼 레지스트리에 등록
+ * → 모듈 간에도 동일한 심볼 공유 가능
+ */
+
+// ============================================
+// 메타데이터 심볼
+// ============================================
+
+/**
+ * MCP 서버 상태 메타데이터
+ * - connected, disconnected, error 등
+ */
+export const MCP_SERVER_STATUS = Symbol.for("mandu:mcpServerStatus");
+
+/**
+ * 검증 컨텍스트 메타데이터
+ * - 커스텀 검증 규칙, 에러 메시지 등
+ */
+export const VALIDATION_CONTEXT = Symbol.for("mandu:validationContext");
+
+/**
+ * 스키마 참조 메타데이터
+ * - 다른 스키마/함수 참조
+ */
+export const SCHEMA_REFERENCE = Symbol.for("mandu:schemaReference");
+
+/**
+ * 필드 소스 메타데이터
+ * - 필드 값의 출처 (env, config, default 등)
+ */
+export const FIELD_SOURCE = Symbol.for("mandu:fieldSource");
+
+/**
+ * 민감 정보 마커
+ * - 로깅/출력 시 마스킹 필요
+ */
+export const SENSITIVE_FIELD = Symbol.for("mandu:sensitiveField");
+
+/**
+ * 보호된 필드 마커
+ * - AI 에이전트 수정 불가
+ */
+export const PROTECTED_FIELD = Symbol.for("mandu:protectedField");
+
+/**
+ * 기본값 출처 메타데이터
+ * - 기본값이 어디서 왔는지 추적
+ */
+export const DEFAULT_SOURCE = Symbol.for("mandu:defaultSource");
+
+/**
+ * 런타임 주입 메타데이터
+ * - 런타임에 주입되는 값 표시
+ */
+export const RUNTIME_INJECTED = Symbol.for("mandu:runtimeInjected");
+
+// ============================================
+// 타입 정의
+// ============================================
+
+export interface McpServerStatusMetadata {
+  status: "connected" | "disconnected" | "error" | "unknown";
+  lastChecked?: string;
+  error?: string;
+}
+
+export interface ValidationContextMetadata {
+  customMessage?: string;
+  severity?: "error" | "warning" | "info";
+  autoFix?: boolean;
+}
+
+export interface SchemaReferenceMetadata {
+  type: "mcpServer" | "function" | "schema" | "env";
+  name: string;
+  optional?: boolean;
+}
+
+export interface FieldSourceMetadata {
+  source: "env" | "config" | "default" | "computed" | "injected";
+  key?: string;
+  fallback?: unknown;
+}
+
+export interface SensitiveFieldMetadata {
+  redactIn: ("log" | "diff" | "snapshot")[];
+  mask?: string;
+}
+
+export interface ProtectedFieldMetadata {
+  reason: string;
+  allowedModifiers?: string[];
+}
+
+// ============================================
+// 심볼-타입 매핑
+// ============================================
+
+export type SymbolMetadataMap = {
+  [MCP_SERVER_STATUS]: McpServerStatusMetadata;
+  [VALIDATION_CONTEXT]: ValidationContextMetadata;
+  [SCHEMA_REFERENCE]: SchemaReferenceMetadata;
+  [FIELD_SOURCE]: FieldSourceMetadata;
+  [SENSITIVE_FIELD]: SensitiveFieldMetadata;
+  [PROTECTED_FIELD]: ProtectedFieldMetadata;
+  [DEFAULT_SOURCE]: string;
+  [RUNTIME_INJECTED]: boolean;
+};
+
+// ============================================
+// 심볼 목록 (순회용)
+// ============================================
+
+export const ALL_METADATA_SYMBOLS = [
+  MCP_SERVER_STATUS,
+  VALIDATION_CONTEXT,
+  SCHEMA_REFERENCE,
+  FIELD_SOURCE,
+  SENSITIVE_FIELD,
+  PROTECTED_FIELD,
+  DEFAULT_SOURCE,
+  RUNTIME_INJECTED,
+] as const;
+
+/**
+ * 심볼이 mandu 메타데이터 심볼인지 확인
+ */
+export function isManduMetadataSymbol(sym: symbol): boolean {
+  return ALL_METADATA_SYMBOLS.includes(sym as any);
+}
+
+/**
+ * 심볼 이름 가져오기 (디버깅용)
+ */
+export function getSymbolName(sym: symbol): string | undefined {
+  return sym.description?.replace("mandu:", "");
+}

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>;