@mandujs/core 0.30.0 → 0.32.0

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

package/src/guard/define-rule.ts

@@ -0,0 +1,243 @@
+/**
+ * Phase 18.ν — Consumer-defined Guard rules.
+ *
+ * Ships `defineGuardRule()` + `GuardRule` / `GuardRuleContext` /
+ * `GuardViolation` types so consumers can extend Mandu's architecture
+ * guard without forking the framework. Rules declared via
+ * `mandu.config.ts` `guard.rules` are merged into the standard Guard
+ * report alongside Mandu's built-in presets (fsd/clean/hexagonal/atomic/
+ * cqrs/mandu).
+ *
+ * @module guard/define-rule
+ *
+ * @example Project-local "no axios" rule.
+ * ```ts
+ * // mandu.config.ts
+ * import { defineGuardRule } from "@mandujs/core/guard/define-rule";
+ *
+ * export default {
+ *   guard: {
+ *     rules: [
+ *       defineGuardRule({
+ *         id: "forbid-axios",
+ *         severity: "error",
+ *         description: "Use native fetch() instead of axios.",
+ *         check: (ctx) => ctx.imports
+ *           .filter((imp) => imp.path === "axios" || imp.path.startsWith("axios/"))
+ *           .map((imp) => ({
+ *             file: ctx.sourceFile,
+ *             line: imp.line,
+ *             message: `axios import at line ${imp.line} — use fetch().`,
+ *             hint: "Replace with globalThis.fetch() or a thin wrapper.",
+ *           })),
+ *       }),
+ *     ],
+ *   },
+ * };
+ * ```
+ */
+
+import type { ExportInfo as AstExportInfo } from "./ast-analyzer";
+import type { ImportInfo as AstImportInfo } from "./types";
+import type { ManduConfig } from "../config/mandu";
+
+/**
+ * Severity emitted by a consumer-defined rule when it flags a file.
+ *
+ *   - `"error"`   — fails `mandu guard check` (non-zero exit code).
+ *   - `"warning"` — surfaces in the report but keeps the exit code clean.
+ *   - `"info"`    — purely informational; useful for migration-phase
+ *                   rules that should not gate CI yet.
+ *
+ * The built-in `applyRuleSeverity()` downgrades `"info"` → `"warning"`
+ * when emitted through the unified report so the rest of the pipeline
+ * (reporter, CI formatter) does not have to special-case a third level.
+ */
+export type GuardRuleSeverity = "error" | "warning" | "info";
+
+/**
+ * Information about a single import statement in the file being
+ * checked. Shape matches {@link AstImportInfo} from the Guard AST
+ * analyzer so rules can consume the two interchangeably.
+ */
+export type ImportInfo = AstImportInfo;
+
+/**
+ * Information about a single export declaration in the file being
+ * checked. Shape matches {@link AstExportInfo}.
+ */
+export type ExportInfo = AstExportInfo;
+
+/**
+ * Violation record emitted by a consumer-defined rule. The Guard
+ * runner prefixes `ruleId` with `custom:<rule.id>` when merging into
+ * the standard report, so the originating rule is always traceable in
+ * CI output.
+ */
+export interface GuardViolation {
+  /** Relative (preferred) or absolute file path where the violation occurs. */
+  file: string;
+  /** 1-indexed line number, if known. */
+  line?: number;
+  /** 1-indexed column number, if known. */
+  column?: number;
+  /** Human-readable message surfaced in the reporter. */
+  message: string;
+  /** Optional remediation hint. Shown alongside `message` in the CLI report. */
+  hint?: string;
+  /** Optional docs URL (rendered as a clickable link in supported terminals). */
+  docsUrl?: string;
+}
+
+/**
+ * Per-file execution context handed to a rule's `check()` function.
+ * The runner parses imports/exports up front with the Guard AST
+ * analyzer so every rule gets a pre-tokenized view without paying the
+ * parse cost N times.
+ */
+export interface GuardRuleContext {
+  /** Absolute path of the file being checked. */
+  sourceFile: string;
+  /** Raw file content (UTF-8). */
+  content: string;
+  /** Parsed import statements (AST-level, comments/strings stripped). */
+  imports: ImportInfo[];
+  /** Parsed export declarations (AST-level). */
+  exports: ExportInfo[];
+  /** Resolved Mandu config — useful for rules that branch on project settings. */
+  config: ManduConfig;
+  /** Project root (absolute). Useful for computing relative paths for `file`. */
+  projectRoot: string;
+}
+
+/**
+ * A consumer-defined Guard rule. Register an array of these under
+ * `mandu.config.ts` `guard.rules`.
+ *
+ * Rules are executed once per source file scanned by
+ * `checkInvalidGeneratedImport()`'s source-dir walker (packages/, src/,
+ * app/). Each rule's `check()` may be synchronous or asynchronous —
+ * the runner awaits both uniformly.
+ *
+ * @see {@link defineGuardRule}
+ */
+export interface GuardRule {
+  /**
+   * Stable rule identifier, e.g. `"company-no-axios"`. The runner
+   * prefixes this with `custom:` when emitting violations, so the final
+   * `ruleId` in the report is `custom:company-no-axios`.
+   *
+   * Must be unique within a config; duplicate ids trigger a
+   * config-load-time warning via `validateCustomRules()`.
+   */
+  id: string;
+  /** Default severity for violations emitted by this rule. */
+  severity: GuardRuleSeverity;
+  /** One-line description surfaced in the reporter and in `mandu guard explain`. */
+  description: string;
+  /**
+   * Predicate that returns zero or more violations for the given file.
+   * May be sync or async; the runner awaits uniformly with a
+   * concurrency-limited `Promise.all`.
+   *
+   * Throwing inside `check()` is non-fatal — the runner catches the
+   * error, emits a `custom:<id>` violation with the thrown message,
+   * and continues scanning the rest of the files. This keeps one
+   * malformed rule from tearing down the whole report.
+   */
+  check: (ctx: GuardRuleContext) => GuardViolation[] | Promise<GuardViolation[]>;
+}
+
+/**
+ * Identity helper that returns the rule it was given. The only
+ * behavior-bearing piece is the type guard — `defineGuardRule()`
+ * validates the minimum shape (`id`, `severity`, `check`) at runtime
+ * so typos in a plain-JS `mandu.config.js` surface immediately instead
+ * of hiding inside the Guard runner.
+ *
+ * @throws `TypeError` when `rule` is missing a required field, or
+ *         when `severity` is not one of `"error" | "warning" | "info"`.
+ */
+export function defineGuardRule(rule: GuardRule): GuardRule {
+  if (!rule || typeof rule !== "object") {
+    throw new TypeError("defineGuardRule: argument must be an object.");
+  }
+  if (typeof rule.id !== "string" || rule.id.length === 0) {
+    throw new TypeError("defineGuardRule: `id` must be a non-empty string.");
+  }
+  if (rule.severity !== "error" && rule.severity !== "warning" && rule.severity !== "info") {
+    throw new TypeError(
+      `defineGuardRule: \`severity\` must be one of "error" | "warning" | "info" (got ${JSON.stringify(rule.severity)}).`
+    );
+  }
+  if (typeof rule.check !== "function") {
+    throw new TypeError("defineGuardRule: `check` must be a function (sync or async).");
+  }
+  if (typeof rule.description !== "string") {
+    throw new TypeError("defineGuardRule: `description` must be a string.");
+  }
+  return rule;
+}
+
+/**
+ * Structural check used by the Zod `z.custom<GuardRule>()` guard in
+ * `config/validate.ts` and by `validateCustomRules()` at load time.
+ * Kept deliberately loose — we only reject values that are obviously
+ * not `GuardRule` objects; deeper validation (severity enum,
+ * description type) happens in `defineGuardRule()` for the clearest
+ * DX error, or in the runner (`check` throws) where the violation is
+ * reported in-band.
+ */
+export function isGuardRuleLike(value: unknown): value is GuardRule {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.id !== "string" || obj.id.length === 0) return false;
+  if (typeof obj.check !== "function") return false;
+  return true;
+}
+
+/**
+ * Duplicate-id result returned by {@link validateCustomRules}.
+ */
+export interface DuplicateRuleId {
+  id: string;
+  /** Zero-indexed positions in the original array where the id appears. */
+  indices: number[];
+}
+
+/**
+ * Structural validation executed at config-load. Returns the list of
+ * duplicate ids plus a list of entries that failed {@link isGuardRuleLike}.
+ * The CLI prints a warning per duplicate; malformed rules are surfaced
+ * via Zod's standard error path.
+ */
+export function validateCustomRules(rules: readonly unknown[]): {
+  duplicates: DuplicateRuleId[];
+  malformed: number[];
+} {
+  const duplicates: DuplicateRuleId[] = [];
+  const malformed: number[] = [];
+  const seen = new Map<string, number[]>();
+
+  for (let i = 0; i < rules.length; i++) {
+    const rule = rules[i];
+    if (!isGuardRuleLike(rule)) {
+      malformed.push(i);
+      continue;
+    }
+    const existing = seen.get(rule.id);
+    if (existing) {
+      existing.push(i);
+    } else {
+      seen.set(rule.id, [i]);
+    }
+  }
+
+  for (const [id, indices] of seen) {
+    if (indices.length > 1) {
+      duplicates.push({ id, indices });
+    }
+  }
+
+  return { duplicates, malformed };
+}

package/src/guard/index.ts

@@ -275,6 +275,32 @@ export {
   type SemanticSlotValidationResult,
 } from "./semantic-slots";
 
+// ═══════════════════════════════════════════════════════════════════════════
+// Custom Guard Rules (Phase 18.ν) - Consumer-defined rules
+// ═══════════════════════════════════════════════════════════════════════════
+
+export {
+  defineGuardRule,
+  isGuardRuleLike,
+  validateCustomRules,
+  type GuardRule as CustomGuardRule,
+  type GuardRuleContext as CustomGuardRuleContext,
+  type GuardViolation as CustomGuardViolation,
+  type GuardRuleSeverity as CustomGuardRuleSeverity,
+  type DuplicateRuleId,
+  type ImportInfo as CustomRuleImportInfo,
+  type ExportInfo as CustomRuleExportInfo,
+} from "./define-rule";
+
+export {
+  forbidImport,
+  requireNamedExport,
+  requirePrefixForExports,
+  type ForbidImportOptions,
+  type RequireNamedExportOptions,
+  type RequirePrefixForExportsOptions,
+} from "./rule-presets";
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Architecture Negotiation - AI-Framework 협상
 // ═══════════════════════════════════════════════════════════════════════════