@mandujs/core 0.30.0 → 0.32.0

package/src/guard/rule-presets.ts

@@ -0,0 +1,379 @@
+/**
+ * Phase 18.ν — Convenience presets for consumer-defined Guard rules.
+ *
+ * Wraps {@link defineGuardRule} with the three most common project-local
+ * patterns observed in Mandu consumer projects:
+ *
+ *   1. `forbidImport()` — reject imports whose specifier matches a regex
+ *      (or equals a literal string). Replaces the 90% case of
+ *      `eslint-plugin-local` rules.
+ *   2. `requireNamedExport()` — require specific named exports in files
+ *      whose paths match a glob/regex. Useful for enforcing file-based
+ *      routing conventions (`route.ts` must export a `handler`, etc.).
+ *   3. `requirePrefixForExports()` — require exported functions to start
+ *      with a given prefix (e.g. HTTP verb names for API route files).
+ *
+ * All helpers return a {@link GuardRule} so they can be pushed directly
+ * into `mandu.config.ts` `guard.rules: [...]`.
+ *
+ * @module guard/rule-presets
+ *
+ * @example
+ * ```ts
+ * // mandu.config.ts
+ * import {
+ *   forbidImport,
+ *   requireNamedExport,
+ *   requirePrefixForExports,
+ * } from "@mandujs/core/guard/define-rule";
+ *
+ * export default {
+ *   guard: {
+ *     rules: [
+ *       forbidImport({ from: "axios", matches: /./ }),
+ *       requireNamedExport({
+ *         patterns: [/app\/api\/.*\/route\.ts$/],
+ *         names: ["GET", "POST"],
+ *         requireAny: true,
+ *       }),
+ *       requirePrefixForExports({
+ *         patterns: [/app\/api\/.*\/route\.ts$/],
+ *         prefix: /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)$/,
+ *       }),
+ *     ],
+ *   },
+ * };
+ * ```
+ */
+
+import {
+  defineGuardRule,
+  type GuardRule,
+  type GuardRuleContext,
+  type GuardRuleSeverity,
+  type GuardViolation,
+} from "./define-rule";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Shared helpers
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Normalize a string | RegExp matcher into a `.test(value)`-capable object. */
+function toRegex(matcher: string | RegExp): RegExp {
+  if (matcher instanceof RegExp) return matcher;
+  // Escape regex metacharacters for literal-string matches.
+  const escaped = matcher.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(escaped);
+}
+
+/**
+ * Returns true when `filePath` matches at least one of the supplied
+ * patterns. Strings are treated as literal substrings; RegExps use
+ * `.test()`. Forward slashes are used throughout (the Guard runner
+ * already normalizes Windows backslashes upstream).
+ */
+function matchesAny(filePath: string, patterns: ReadonlyArray<string | RegExp>): boolean {
+  for (const pattern of patterns) {
+    if (typeof pattern === "string") {
+      if (filePath.includes(pattern)) return true;
+    } else if (pattern.test(filePath)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// forbidImport
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Options for {@link forbidImport}.
+ */
+export interface ForbidImportOptions {
+  /**
+   * Package name / path that triggers the rule. Matched against
+   * {@link ImportInfo.path} via `===` (literal) or `.test()` (regex).
+   * Pass a regex like `/^(node:fs|fs|fs\/promises)$/` for a set match.
+   */
+  from: string | RegExp;
+  /**
+   * Only the imports whose import path also matches this regex are
+   * flagged. Defaults to `/./` (all imports). Useful for cases where
+   * you want to forbid a package except when imported for types only.
+   */
+  matches?: RegExp;
+  /** Rule severity. Defaults to `"error"`. */
+  severity?: GuardRuleSeverity;
+  /** Override rule `id`. Defaults to `forbid-import:<normalized-from>`. */
+  id?: string;
+  /**
+   * Override rule `description`. Defaults to a human-friendly sentence
+   * describing the forbidden source.
+   */
+  description?: string;
+  /**
+   * Remediation hint surfaced alongside each violation. Defaults to a
+   * generic "Use a project-approved alternative" string.
+   */
+  hint?: string;
+  /** Optional docs URL surfaced with each violation. */
+  docsUrl?: string;
+  /**
+   * Restrict the rule to files whose path matches one of these
+   * patterns. When omitted, every scanned file is considered.
+   */
+  includePaths?: ReadonlyArray<string | RegExp>;
+  /**
+   * Exclude files whose path matches one of these patterns. Applied
+   * after `includePaths`.
+   */
+  excludePaths?: ReadonlyArray<string | RegExp>;
+}
+
+function normalizeIdFragment(value: string | RegExp): string {
+  const raw = value instanceof RegExp ? value.source : value;
+  return raw.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "import";
+}
+
+/**
+ * Create a rule that rejects every `import ... from "<from>"` whose
+ * specifier matches `matches` (default: all). Works for static,
+ * dynamic, and CommonJS `require()` imports.
+ */
+export function forbidImport(options: ForbidImportOptions): GuardRule {
+  const fromMatcher = toRegex(options.from);
+  const extraMatcher = options.matches ?? /./;
+  const id = options.id ?? `forbid-import:${normalizeIdFragment(options.from)}`;
+  const description =
+    options.description ??
+    `Imports from \`${options.from instanceof RegExp ? options.from.source : options.from}\` are forbidden.`;
+  const hint = options.hint ?? "Use a project-approved alternative.";
+  const severity = options.severity ?? "error";
+
+  return defineGuardRule({
+    id,
+    severity,
+    description,
+    check(ctx: GuardRuleContext): GuardViolation[] {
+      if (options.includePaths && !matchesAny(ctx.sourceFile, options.includePaths)) {
+        return [];
+      }
+      if (options.excludePaths && matchesAny(ctx.sourceFile, options.excludePaths)) {
+        return [];
+      }
+
+      const violations: GuardViolation[] = [];
+      for (const imp of ctx.imports) {
+        if (!fromMatcher.test(imp.path)) continue;
+        if (!extraMatcher.test(imp.path)) continue;
+
+        violations.push({
+          file: ctx.sourceFile,
+          line: imp.line,
+          column: imp.column,
+          message: `Forbidden import: \`${imp.path}\` (${description})`,
+          hint,
+          docsUrl: options.docsUrl,
+        });
+      }
+      return violations;
+    },
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// requireNamedExport
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Options for {@link requireNamedExport}.
+ */
+export interface RequireNamedExportOptions {
+  /**
+   * Only files whose path matches one of these patterns are checked.
+   * Strings are substring matches; regexes use `.test()`.
+   */
+  patterns: ReadonlyArray<string | RegExp>;
+  /**
+   * Export names that must be present. By default (`requireAny === false`)
+   * *all* names in this array must be exported; pass `requireAny: true`
+   * to require at least one.
+   */
+  names: readonly string[];
+  /**
+   * If `true`, a file passes when at least one of `names` is exported.
+   * Defaults to `false` (all names required).
+   */
+  requireAny?: boolean;
+  /** Rule severity. Defaults to `"error"`. */
+  severity?: GuardRuleSeverity;
+  /** Override rule `id`. Defaults to `require-named-export:<names.join("|")>`. */
+  id?: string;
+  /** Override rule `description`. */
+  description?: string;
+  /** Remediation hint. */
+  hint?: string;
+  /** Optional docs URL. */
+  docsUrl?: string;
+}
+
+/**
+ * Create a rule that requires specific named exports to exist in
+ * matching files. Useful for enforcing file-based routing conventions
+ * (e.g. `app/api/**\/route.ts` must export a `GET` or `POST` handler).
+ */
+export function requireNamedExport(options: RequireNamedExportOptions): GuardRule {
+  if (!Array.isArray(options.names) || options.names.length === 0) {
+    throw new TypeError("requireNamedExport: `names` must be a non-empty array of strings.");
+  }
+  if (!Array.isArray(options.patterns) || options.patterns.length === 0) {
+    throw new TypeError("requireNamedExport: `patterns` must be a non-empty array.");
+  }
+
+  const id = options.id ?? `require-named-export:${options.names.join("|")}`;
+  const description =
+    options.description ??
+    (options.requireAny
+      ? `Files matching the pattern must export at least one of: ${options.names.join(", ")}.`
+      : `Files matching the pattern must export all of: ${options.names.join(", ")}.`);
+  const hint = options.hint ?? `Add the missing \`export\` declarations.`;
+  const severity = options.severity ?? "error";
+
+  return defineGuardRule({
+    id,
+    severity,
+    description,
+    check(ctx: GuardRuleContext): GuardViolation[] {
+      if (!matchesAny(ctx.sourceFile, options.patterns)) return [];
+
+      const exportedNames = new Set<string>();
+      for (const exp of ctx.exports) {
+        if (exp.type === "named" || exp.type === "default") {
+          if (exp.name) exportedNames.add(exp.name);
+        }
+      }
+
+      const missing = options.names.filter((n) => !exportedNames.has(n));
+
+      if (options.requireAny) {
+        if (missing.length === options.names.length) {
+          return [
+            {
+              file: ctx.sourceFile,
+              message: `Missing required export: expected at least one of [${options.names.join(", ")}], found none.`,
+              hint,
+              docsUrl: options.docsUrl,
+            },
+          ];
+        }
+        return [];
+      }
+
+      if (missing.length === 0) return [];
+      return [
+        {
+          file: ctx.sourceFile,
+          message: `Missing required exports: ${missing.join(", ")}.`,
+          hint,
+          docsUrl: options.docsUrl,
+        },
+      ];
+    },
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// requirePrefixForExports
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Options for {@link requirePrefixForExports}.
+ */
+export interface RequirePrefixForExportsOptions {
+  /**
+   * Only files whose path matches one of these patterns are checked.
+   */
+  patterns: ReadonlyArray<string | RegExp>;
+  /**
+   * Prefix that every named export must match. String is treated as a
+   * literal prefix (`startsWith`); RegExp is `.test()`-ed against the
+   * full export name.
+   */
+  prefix: string | RegExp;
+  /**
+   * Export names to exempt from the check (e.g. `"default"`, helper
+   * types). Literal strings only — kept simple because this is the
+   * common case.
+   */
+  allowList?: readonly string[];
+  /**
+   * When `true`, only check exports whose `type` is `"named"` (skip
+   * `default`, `all`, and `type` re-exports). Defaults to `true`.
+   */
+  onlyNamed?: boolean;
+  /** Rule severity. Defaults to `"error"`. */
+  severity?: GuardRuleSeverity;
+  /** Override rule `id`. Defaults to `require-prefix:<normalized-prefix>`. */
+  id?: string;
+  /** Override rule `description`. */
+  description?: string;
+  /** Remediation hint. */
+  hint?: string;
+  /** Optional docs URL. */
+  docsUrl?: string;
+}
+
+/**
+ * Create a rule that requires every named export in matching files to
+ * match `prefix`. Classic use case: enforce that `app/api/**\/route.ts`
+ * files only export HTTP verb names (`GET`, `POST`, ...).
+ */
+export function requirePrefixForExports(options: RequirePrefixForExportsOptions): GuardRule {
+  if (!Array.isArray(options.patterns) || options.patterns.length === 0) {
+    throw new TypeError("requirePrefixForExports: `patterns` must be a non-empty array.");
+  }
+
+  const prefixRegex =
+    options.prefix instanceof RegExp
+      ? options.prefix
+      : new RegExp(`^${options.prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
+  const id = options.id ?? `require-prefix:${normalizeIdFragment(options.prefix)}`;
+  const description =
+    options.description ??
+    `Named exports in matching files must start with \`${options.prefix instanceof RegExp ? options.prefix.source : options.prefix}\`.`;
+  const hint =
+    options.hint ??
+    `Rename the export to match the required prefix, or move the helper to a different module.`;
+  const severity = options.severity ?? "error";
+  const allowSet = new Set(options.allowList ?? []);
+  const onlyNamed = options.onlyNamed ?? true;
+
+  return defineGuardRule({
+    id,
+    severity,
+    description,
+    check(ctx: GuardRuleContext): GuardViolation[] {
+      if (!matchesAny(ctx.sourceFile, options.patterns)) return [];
+
+      const violations: GuardViolation[] = [];
+      for (const exp of ctx.exports) {
+        if (onlyNamed && exp.type !== "named") continue;
+        if (!exp.name) continue;
+        if (allowSet.has(exp.name)) continue;
+        if (prefixRegex.test(exp.name)) continue;
+
+        violations.push({
+          file: ctx.sourceFile,
+          line: exp.line,
+          message: `Export \`${exp.name}\` does not match the required prefix ${
+            options.prefix instanceof RegExp ? options.prefix.source : `"${options.prefix}"`
+          }.`,
+          hint,
+          docsUrl: options.docsUrl,
+        });
+      }
+      return violations;
+    },
+  });
+}

package/src/i18n/define.ts

@@ -0,0 +1,126 @@
+/**
+ * Phase 18.μ — `defineI18n()` contract.
+ *
+ * Thin factory with strict validation so misconfiguration surfaces
+ * at boot time (not at first request). Returns a frozen object
+ * branded as {@link I18nDefinition} to discourage callers from
+ * mutating the config after handing it to the runtime.
+ */
+
+import type { I18nConfig, I18nDefinition, I18nStrategy, LocaleCode } from "./types";
+
+export const VALID_STRATEGIES: readonly I18nStrategy[] = [
+  "path-prefix",
+  "domain",
+  "header",
+  "cookie",
+] as const;
+
+/** Default cookie name when none is specified. Matches Next.js `NEXT_LOCALE`. */
+export const DEFAULT_I18N_COOKIE = "mandu_locale";
+
+/**
+ * Validate + brand an i18n configuration.
+ *
+ * @throws Error when:
+ *   - `locales` is empty
+ *   - `defaultLocale` is not in `locales`
+ *   - `fallback` is supplied but not in `locales`
+ *   - `strategy` is unknown
+ *   - `strategy === "domain"` without a non-empty `domains` map
+ *   - any `domains[...]` value is not in `locales`
+ *
+ * @example
+ * ```ts
+ * export const i18n = defineI18n({
+ *   locales: ['en', 'ko', 'ja'],
+ *   defaultLocale: 'en',
+ *   strategy: 'path-prefix',
+ * });
+ * ```
+ */
+export function defineI18n(config: I18nConfig): I18nDefinition {
+  if (!config || typeof config !== "object") {
+    throw new Error("[mandu/i18n] defineI18n() requires a config object");
+  }
+
+  const { locales, defaultLocale, fallback, strategy, cookieName, domains } = config;
+
+  if (!Array.isArray(locales) || locales.length === 0) {
+    throw new Error("[mandu/i18n] `locales` must be a non-empty array");
+  }
+
+  for (const l of locales) {
+    if (typeof l !== "string" || l.length === 0) {
+      throw new Error(
+        "[mandu/i18n] every entry in `locales` must be a non-empty string"
+      );
+    }
+  }
+
+  const dedup = new Set(locales);
+  if (dedup.size !== locales.length) {
+    throw new Error("[mandu/i18n] `locales` must not contain duplicates");
+  }
+
+  if (typeof defaultLocale !== "string" || !dedup.has(defaultLocale)) {
+    throw new Error(
+      `[mandu/i18n] defaultLocale "${defaultLocale}" must be one of locales [${locales.join(", ")}]`
+    );
+  }
+
+  if (fallback !== undefined) {
+    if (typeof fallback !== "string" || !dedup.has(fallback)) {
+      throw new Error(
+        `[mandu/i18n] fallback "${fallback}" must be one of locales [${locales.join(", ")}]`
+      );
+    }
+  }
+
+  if (!VALID_STRATEGIES.includes(strategy)) {
+    throw new Error(
+      `[mandu/i18n] strategy "${strategy}" is invalid. Expected one of: ${VALID_STRATEGIES.join(", ")}`
+    );
+  }
+
+  if (strategy === "domain") {
+    if (!domains || typeof domains !== "object" || Object.keys(domains).length === 0) {
+      throw new Error(
+        "[mandu/i18n] strategy 'domain' requires a non-empty `domains` map"
+      );
+    }
+    for (const [host, locale] of Object.entries(domains)) {
+      if (typeof host !== "string" || host.length === 0) {
+        throw new Error("[mandu/i18n] domain keys must be non-empty strings");
+      }
+      if (!dedup.has(locale)) {
+        throw new Error(
+          `[mandu/i18n] domains["${host}"] = "${locale}" is not in locales`
+        );
+      }
+    }
+  }
+
+  const frozen: I18nDefinition = Object.freeze({
+    locales: Object.freeze([...locales]) as readonly LocaleCode[],
+    defaultLocale,
+    fallback,
+    strategy,
+    cookieName: cookieName ?? DEFAULT_I18N_COOKIE,
+    domains: domains ? Object.freeze({ ...domains }) : undefined,
+    __manduI18n: true,
+  });
+  return frozen;
+}
+
+/**
+ * Type guard for {@link I18nDefinition}. Use in adapter/runtime code
+ * that receives `unknown` from user config.
+ */
+export function isI18nDefinition(value: unknown): value is I18nDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __manduI18n?: unknown }).__manduI18n === true
+  );
+}

package/src/i18n/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Phase 18.μ — i18n barrel.
+ *
+ * Public surface for first-class internationalization in Mandu.
+ *
+ * ```ts
+ * import { defineI18n, defineMessages, resolveLocale, createTranslator } from "@mandujs/core/i18n";
+ *
+ * export const i18n = defineI18n({
+ *   locales: ["en", "ko"],
+ *   defaultLocale: "en",
+ *   strategy: "path-prefix",
+ * });
+ *
+ * export const messages = defineMessages({
+ *   en: { welcome: "Welcome, {{name}}" },
+ *   ko: { welcome: "환영합니다, {{name}}님" },
+ * } as const);
+ * ```
+ */
+
+export type {
+  LocaleCode,
+  MessageBundle,
+  I18nStrategy,
+  I18nConfig,
+  I18nDefinition,
+  ResolvedLocale,
+  Translator,
+} from "./types";
+
+export {
+  defineI18n,
+  isI18nDefinition,
+  VALID_STRATEGIES,
+  DEFAULT_I18N_COOKIE,
+} from "./define";
+
+export {
+  resolveLocale,
+  stripLocalePrefix,
+  parseAcceptLanguage,
+  readLocaleCookie,
+} from "./locale-resolver";
+
+export {
+  defineMessages,
+  createTranslator,
+  interpolate,
+  isMessageRegistry,
+  type MessageRegistry,
+} from "./message-registry";