@mandujs/core 0.31.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -36,6 +36,7 @@
     "./testing": "./src/testing/index.ts",
     "./plugins": "./src/plugins/index.ts",
     "./error": "./src/error/index.ts",
+    "./i18n": "./src/i18n/index.ts",
     "./id": "./src/id/index.ts",
     "./observability": "./src/observability/index.ts",
     "./perf": "./src/perf/index.ts",
@@ -43,6 +44,8 @@
     "./routes": "./src/routes/index.ts",
     "./scheduler": "./src/scheduler/index.ts",
     "./storage/s3": "./src/storage/s3/index.ts",
+    "./guard/define-rule": "./src/guard/define-rule.ts",
+    "./guard/rule-presets": "./src/guard/rule-presets.ts",
     "./bundler/prerender": "./src/bundler/prerender.ts",
     "./bundler/safe-build": "./src/bundler/safe-build.ts",
     "./bundler/hmr-types": "./src/bundler/hmr-types.ts",

package/src/config/mandu.ts

@@ -5,6 +5,8 @@ import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
 import type { Middleware } from "../middleware/define";
 import type { RpcDefinition, RpcProcedureRecord } from "../contract/rpc";
 import type { CronDef } from "../scheduler";
+import type { GuardRule as CustomGuardRule } from "../guard/define-rule";
+import type { I18nStrategy, LocaleCode } from "../i18n/types";
 
 export type GuardRuleSeverity = "error" | "warn" | "warning" | "off";
 
@@ -148,7 +150,20 @@ export interface ManduConfig {
     srcDir?: string;
     exclude?: string[];
     realtime?: boolean;
-    rules?: Record<string, GuardRuleSeverity>;
+    /**
+     * Built-in rule severity overrides (map) OR consumer-defined
+     * custom rules (array). The Guard runner dispatches on shape:
+     *
+     *   - `Record<string, GuardRuleSeverity>` → override severity of
+     *     Mandu's built-in rules by id.
+     *   - `GuardRule[]` (Phase 18.ν) → register consumer-defined rules
+     *     alongside the built-in presets. See `@mandujs/core/guard/define-rule`.
+     *
+     * Passing both at once is not supported; pick one shape per config.
+     * Mixed input falls back to "custom rules only" and the built-in
+     * rule severity overrides become unreachable.
+     */
+    rules?: Record<string, GuardRuleSeverity> | CustomGuardRule[];
     contractRequired?: GuardRuleSeverity;
     /**
      * Issue #207 — hard-fail on direct `__generated__/` imports at the
@@ -422,6 +437,48 @@ export interface ManduConfig {
     jobs?: CronDef[];
     disabled?: boolean;
   };
+  /**
+   * Phase 18.μ — first-class internationalization.
+   *
+   * Declaring this block opts the project into the framework's built-in
+   * locale resolution + route synthesis. The CLI (`mandu build` /
+   * `mandu dev`) materializes per-locale route variants when
+   * `strategy === "path-prefix"` so a single `app/docs/page.tsx`
+   * serves `/en/docs`, `/ko/docs`, etc. without file duplication.
+   *
+   * At runtime, the server dispatcher attaches `ctx.locale`
+   * ({@link ResolvedLocale}) + `ctx.t` (typed translator, when a
+   * message registry is wired) to every loader and stamps
+   * `Vary: Accept-Language` on responses so CDNs cache correctly.
+   *
+   * Coexists with the legacy `app/[lang]/...` manual pattern — users
+   * migrate only when ready. See `docs/architect/i18n.md`.
+   *
+   * @example
+   * ```ts
+   * export default {
+   *   i18n: {
+   *     locales: ['en', 'ko'],
+   *     defaultLocale: 'en',
+   *     strategy: 'path-prefix',
+   *   },
+   * } satisfies ManduConfig;
+   * ```
+   */
+  i18n?: {
+    /** Non-empty list of supported locale codes. */
+    locales: LocaleCode[];
+    /** Fallback when no signal matches. MUST be in `locales`. */
+    defaultLocale: LocaleCode;
+    /** Optional fallback chain between request locale and defaultLocale. */
+    fallback?: LocaleCode;
+    /** Locale detection strategy. See {@link I18nStrategy}. */
+    strategy: I18nStrategy;
+    /** Cookie name (default: "mandu_locale"). */
+    cookieName?: string;
+    /** Domain → locale map; required when strategy === "domain". */
+    domains?: Record<string, LocaleCode>;
+  };
 }
 
 export const CONFIG_FILES = [

package/src/config/validate.ts

@@ -7,6 +7,7 @@ import type { ManduAdapter } from "../runtime/adapter";
 import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
 import type { Middleware } from "../middleware/define";
 import type { CronDef } from "../scheduler";
+import { isGuardRuleLike, type GuardRule as CustomGuardRule } from "../guard/define-rule";
 
 /**
  * DNA-003: Strict mode schema helper
@@ -72,8 +73,30 @@ const ServerConfigSchema = z
   })
   .strict();
 
+/**
+ * Phase 18.ν — consumer-defined Guard rule (structural check).
+ *
+ * Rule objects carry closures (`check`) that Zod cannot introspect, so
+ * we validate structurally: must be a non-null object with a non-empty
+ * `id` string and a `check` function. Deeper validation (severity enum,
+ * description type) happens at `defineGuardRule()` time for the clearest
+ * DX error; the Guard runner catches any in-band violations.
+ */
+const CustomGuardRuleSchema = z.custom<CustomGuardRule>(
+  (v) => isGuardRuleLike(v),
+  {
+    message:
+      "Each custom guard rule must be an object with a non-empty `id` string and a `check` function. Use `defineGuardRule({...})` from `@mandujs/core/guard/define-rule` to construct.",
+  }
+);
+
 /**
  * Guard 설정 스키마 (strict)
+ *
+ * `guard.rules` is a discriminated union of two shapes:
+ *   - `Record<string, GuardRuleSeverity>` → built-in rule severity overrides.
+ *   - `GuardRule[]` (Phase 18.ν) → consumer-defined custom rules.
+ * The runner dispatches on `Array.isArray()`.
  */
 const GuardConfigSchema = z
   .object({
@@ -81,7 +104,12 @@ const GuardConfigSchema = z
     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(),
+    rules: z
+      .union([
+        z.record(z.enum(["error", "warn", "warning", "off"])),
+        z.array(CustomGuardRuleSchema),
+      ])
+      .optional(),
     /**
      * Issue #207 — bundler-level hard-fail on direct `__generated__/`
      * imports. Default `true`. Set `false` to opt out of the
@@ -377,6 +405,69 @@ const SchedulerConfigSchema = z
   })
   .strict();
 
+/**
+ * Phase 18.μ — i18n config schema (strict).
+ *
+ * Strictly validates shape + cross-field invariants that `defineI18n()`
+ * enforces at runtime (defaultLocale ∈ locales, fallback ∈ locales,
+ * domain map required when strategy === "domain"). Doing this at
+ * config load gives users a clean `mandu validate` error instead of
+ * a runtime boot failure.
+ */
+const I18nConfigSchema = z
+  .object({
+    locales: z.array(z.string().min(1)).min(1),
+    defaultLocale: z.string().min(1),
+    fallback: z.string().min(1).optional(),
+    strategy: z.enum(["path-prefix", "domain", "header", "cookie"]),
+    cookieName: z.string().min(1).optional(),
+    domains: z.record(z.string().min(1)).optional(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    const locales = new Set(value.locales);
+    if (locales.size !== value.locales.length) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["locales"],
+        message: "locales must not contain duplicates",
+      });
+    }
+    if (!locales.has(value.defaultLocale)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["defaultLocale"],
+        message: `defaultLocale "${value.defaultLocale}" must be one of locales`,
+      });
+    }
+    if (value.fallback !== undefined && !locales.has(value.fallback)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["fallback"],
+        message: `fallback "${value.fallback}" must be one of locales`,
+      });
+    }
+    if (value.strategy === "domain") {
+      if (!value.domains || Object.keys(value.domains).length === 0) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["domains"],
+          message: "strategy 'domain' requires a non-empty domains map",
+        });
+      } else {
+        for (const [host, locale] of Object.entries(value.domains)) {
+          if (!locales.has(locale)) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              path: ["domains", host],
+              message: `domains["${host}"] = "${locale}" is not in locales`,
+            });
+          }
+        }
+      }
+    }
+  });
+
 export const ManduConfigSchema = z
   .object({
     adapter: AdapterConfigSchema.optional(),
@@ -423,6 +514,11 @@ export const ManduConfigSchema = z
      * passthrough).
      */
     scheduler: SchedulerConfigSchema.optional(),
+    /**
+     * Phase 18.μ — first-class i18n config. See {@link I18nConfigSchema}.
+     * Optional; omission leaves i18n disabled with zero runtime overhead.
+     */
+    i18n: I18nConfigSchema.optional(),
   })
   .strict();
 

package/src/filling/context.ts

@@ -20,6 +20,8 @@ import {
   type SpanAttributes,
   type SpanOptions,
 } from "../observability/tracing";
+// Phase 18.μ — i18n integration.
+import type { ResolvedLocale, Translator } from "../i18n/types";
 
 type ContractInput<
   TContract extends ContractSchema,
@@ -332,6 +334,18 @@ export class ManduContext {
   private _deps: FillingDeps;
   private _cacheMeta: { tags: string[]; maxAge?: number; staleWhileRevalidate?: number } = { tags: [] };
   private _cacheHelper: CacheHelper | null = null;
+  /**
+   * Phase 18.μ — resolved active locale. `undefined` when the server has
+   * no `ManduConfig.i18n` configured (zero-overhead — the runtime never
+   * attaches this field). Populated by `runtime/server.ts` μ dispatch.
+   */
+  private _locale: ResolvedLocale | undefined = undefined;
+  /**
+   * Phase 18.μ — typed translator bound to the active locale. `undefined`
+   * until the runtime attaches one via `_setI18n()`. User code should
+   * null-check via `ctx.t?.(...)` OR require i18n via a type predicate.
+   */
+  private _t: Translator | undefined = undefined;
 
   constructor(
     public readonly request: Request,
@@ -397,6 +411,52 @@ export class ManduContext {
     };
   }
 
+  /**
+   * Phase 18.μ — active resolved locale. `undefined` when i18n is
+   * disabled at server boot (`ManduConfig.i18n` omitted). Populated by
+   * the runtime dispatcher BEFORE loader + render so downstream code
+   * can branch on it without threading state manually.
+   *
+   * @example
+   * ```ts
+   * if (ctx.locale?.code === "ko") {
+   *   return ctx.redirect("/ko/welcome");
+   * }
+   * ```
+   */
+  get locale(): ResolvedLocale | undefined {
+    return this._locale;
+  }
+
+  /**
+   * Phase 18.μ — typed translator bound to `ctx.locale`. `undefined`
+   * when i18n is disabled OR no message registry was supplied to
+   * `startServer()`. Unlike `ctx.locale`, this is safe to call with an
+   * unknown key — misses fall through `fallbackLocale` → `defaultLocale`
+   * → raw key per {@link createTranslator}.
+   *
+   * @example
+   * ```ts
+   * return ctx.ok({ greeting: ctx.t?.("welcome", { name: "만두" }) });
+   * ```
+   */
+  get t(): Translator | undefined {
+    return this._t;
+  }
+
+  /**
+   * Phase 18.μ — runtime-internal: attach resolved locale + translator.
+   * Exposed as a method (not a public setter) so user code can't mutate
+   * mid-request. Called exactly once by the server dispatcher before
+   * loader execution.
+   *
+   * @internal
+   */
+  _setI18n(locale: ResolvedLocale, translator?: Translator): void {
+    this._locale = locale;
+    if (translator) this._t = translator;
+  }
+
   /**
    * DNA-002: 의존성 접근
    *

package/src/guard/check.ts

@@ -4,6 +4,14 @@ import { validateSlotContent } from "../slot/validator";
 import type { RoutesManifest } from "../spec/schema";
 import type { GeneratedMap } from "../generator/generate";
 import { loadManduConfig, type GuardRuleSeverity } from "../config";
+import { extractImportsAST, extractExportsAST } from "./ast-analyzer";
+import {
+  validateCustomRules,
+  type GuardRule as CustomGuardRule,
+  type GuardRuleContext as CustomGuardRuleContext,
+  type GuardViolation as CustomGuardViolation,
+} from "./define-rule";
+import type { ManduConfig } from "../config/mandu";
 import path from "path";
 import fs from "fs/promises";
 
@@ -445,7 +453,20 @@ export async function runGuardCheck(
   violations.push(...slotContentViolations);
   violations.push(...contractViolations);
 
-  const resolvedViolations = applyRuleSeverity(violations, config.guard ?? {});
+  // ============================================
+  // Phase 18.ν — Consumer-defined custom rules
+  // ============================================
+  const customRules = (config.guard?.rules as unknown);
+  if (Array.isArray(customRules) && customRules.length > 0) {
+    const customViolations = await runCustomRules(
+      customRules as CustomGuardRule[],
+      rootDir,
+      config
+    );
+    violations.push(...customViolations);
+  }
+
+  const resolvedViolations = applyRuleSeverity(violations, normalizeGuardConfigForSeverity(config.guard));
   const passed = resolvedViolations.every((v) => v.severity !== "error");
 
   return {
@@ -453,3 +474,206 @@ export async function runGuardCheck(
     violations: resolvedViolations,
   };
 }
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 18.ν — Consumer-defined Guard rules
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * The existing `config.guard.rules` field was a `Record<string,
+ * GuardRuleSeverity>` map for built-in rule overrides. Phase 18.ν
+ * allows consumers to also pass an array of `GuardRule` objects.
+ * `applyRuleSeverity` only understands the record shape, so we strip
+ * the array out before forwarding to it.
+ */
+function normalizeGuardConfigForSeverity(
+  guard: ManduConfig["guard"] | undefined
+): { rules?: Record<string, GuardRuleSeverity>; contractRequired?: GuardRuleSeverity } {
+  if (!guard) return {};
+  const rulesField = guard.rules as unknown;
+  const rules =
+    rulesField && !Array.isArray(rulesField) && typeof rulesField === "object"
+      ? (rulesField as Record<string, GuardRuleSeverity>)
+      : undefined;
+  return {
+    rules,
+    contractRequired: (guard as { contractRequired?: GuardRuleSeverity }).contractRequired,
+  };
+}
+
+/**
+ * Parallel scan cap for `runCustomRules()`. Matches `safeBuild` default
+ * (`MANDU_BUN_BUILD_CONCURRENCY`) semantics — tunable via
+ * `MANDU_GUARD_CUSTOM_CONCURRENCY` positive integer env var.
+ */
+function customRuleConcurrency(): number {
+  const raw = process.env.MANDU_GUARD_CUSTOM_CONCURRENCY;
+  if (!raw) return 8;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 1) return 8;
+  return parsed;
+}
+
+/** Default source directories scanned for custom rules. */
+const CUSTOM_RULE_SOURCE_DIRS = ["packages", "src", "app"];
+
+async function collectCustomRuleSourceFiles(rootDir: string): Promise<string[]> {
+  const files = await Promise.all(
+    CUSTOM_RULE_SOURCE_DIRS.map((d) => scanTsFiles(path.join(rootDir, d)))
+  );
+  // Deduplicate paths (a file could in theory live under multiple roots
+  // if a consumer symlinks, which the walker doesn't follow but we
+  // guard anyway).
+  return Array.from(new Set(files.flat()));
+}
+
+/**
+ * Convert a consumer-defined `GuardViolation` into the standard Guard
+ * report `GuardViolation` shape. Adds the `custom:<id>` ruleId prefix
+ * so the reporter can attribute each entry unambiguously.
+ */
+function toReportViolation(
+  rule: CustomGuardRule,
+  violation: CustomGuardViolation
+): GuardViolation {
+  const severity: "error" | "warning" =
+    rule.severity === "error" ? "error" : "warning";
+  return {
+    ruleId: `custom:${rule.id}`,
+    file: violation.file,
+    message: violation.message,
+    suggestion: violation.hint ?? violation.docsUrl ?? "",
+    line: violation.line,
+    severity,
+  };
+}
+
+/**
+ * Execute every consumer-defined rule against every source file under
+ * `rootDir`. Rules are awaited per-file with a concurrency cap; a
+ * single rule throwing is caught and reported as a `custom:<id>`
+ * violation so the rest of the scan still completes.
+ *
+ * Exported for tests; not re-exported via `guard/index.ts` to keep the
+ * public surface small.
+ */
+export async function runCustomRules(
+  rules: readonly CustomGuardRule[],
+  rootDir: string,
+  config: ManduConfig
+): Promise<GuardViolation[]> {
+  const { duplicates, malformed } = validateCustomRules(rules);
+  const results: GuardViolation[] = [];
+
+  if (malformed.length > 0) {
+    for (const idx of malformed) {
+      results.push({
+        ruleId: "custom:__invalid__",
+        file: "mandu.config",
+        message: `guard.rules[${idx}] is not a valid GuardRule (missing \`id\` or \`check()\`).`,
+        suggestion:
+          "Wrap the rule with defineGuardRule({...}) or import a preset from @mandujs/core/guard/define-rule.",
+        severity: "error",
+      });
+    }
+  }
+
+  if (duplicates.length > 0) {
+    for (const dup of duplicates) {
+      // Warning-level so duplicates don't gate CI but still surface in the
+      // report. Matches the "soft failure" convention used by config-guard.
+      results.push({
+        ruleId: `custom:${dup.id}`,
+        file: "mandu.config",
+        message: `Duplicate guard.rules id "${dup.id}" at indices [${dup.indices.join(", ")}] — only the first instance will be enforced.`,
+        suggestion: "Give each rule a unique \`id\`, or remove the duplicate.",
+        severity: "warning",
+      });
+    }
+  }
+
+  // Deduplicate rules by id (keep first occurrence). Matches the
+  // warning emitted above.
+  const seen = new Set<string>();
+  const uniqueRules = rules.filter((r) => {
+    if (!r || typeof r !== "object" || typeof (r as CustomGuardRule).id !== "string") return false;
+    const id = (r as CustomGuardRule).id;
+    if (seen.has(id)) return false;
+    seen.add(id);
+    return true;
+  });
+  if (uniqueRules.length === 0) return results;
+
+  const files = await collectCustomRuleSourceFiles(rootDir);
+  if (files.length === 0) return results;
+
+  const cap = customRuleConcurrency();
+  let cursor = 0;
+
+  async function worker(): Promise<GuardViolation[]> {
+    const local: GuardViolation[] = [];
+    while (true) {
+      const index = cursor++;
+      if (index >= files.length) return local;
+      const filePath = files[index];
+
+      // Skip __generated__ and build output.
+      if (filePath.includes("__generated__") || filePath.includes(".mandu/")) continue;
+
+      let content: string;
+      try {
+        content = await Bun.file(filePath).text();
+      } catch {
+        continue;
+      }
+
+      let imports: ReturnType<typeof extractImportsAST>;
+      let exportsAst: ReturnType<typeof extractExportsAST>;
+      try {
+        imports = extractImportsAST(content);
+        exportsAst = extractExportsAST(content);
+      } catch {
+        // Tokenizer failure on an exotic file — skip rather than abort.
+        continue;
+      }
+
+      const relFile = path.relative(rootDir, filePath) || filePath;
+      const ctx: CustomGuardRuleContext = {
+        sourceFile: relFile.replace(/\\/g, "/"),
+        content,
+        imports,
+        exports: exportsAst,
+        config,
+        projectRoot: rootDir,
+      };
+
+      for (const rule of uniqueRules) {
+        try {
+          const violations = await rule.check(ctx);
+          if (!Array.isArray(violations)) continue;
+          for (const v of violations) {
+            if (!v || typeof v !== "object") continue;
+            local.push(toReportViolation(rule, v));
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          local.push({
+            ruleId: `custom:${rule.id}`,
+            file: ctx.sourceFile,
+            message: `Rule "${rule.id}" threw: ${message}`,
+            suggestion: "Fix the rule's check() implementation or wrap it in a try/catch.",
+            severity: rule.severity === "error" ? "error" : "warning",
+          });
+        }
+      }
+    }
+  }
+
+  const workerCount = Math.min(cap, files.length);
+  const workers: Promise<GuardViolation[]>[] = [];
+  for (let i = 0; i < workerCount; i++) workers.push(worker());
+  const chunks = await Promise.all(workers);
+  for (const chunk of chunks) results.push(...chunk);
+
+  return results;
+}