@mandujs/core 0.31.0 → 0.33.0

package/src/diagnose/run.ts

@@ -0,0 +1,87 @@
+/**
+ * Mandu Diagnose — aggregator.
+ *
+ * Runs all registered checks in parallel (they are pure I/O, no shared
+ * mutable state) and builds a unified `DiagnoseReport`.
+ */
+
+import type { DiagnoseCheckResult, DiagnoseReport } from "./types";
+import {
+  checkManifestFreshness,
+  checkPrerenderPollution,
+  checkCloneElementWarnings,
+  checkDevArtifactsInProd,
+  checkPackageExportGaps,
+} from "./checks";
+
+/**
+ * Registered extended checks (Issue #215). These are the five checks that
+ * supplement the legacy guard/contract/manifest/kitchen validation in MCP.
+ *
+ * Order matters for display purposes only — result aggregation is
+ * order-independent.
+ */
+export const EXTENDED_CHECKS = [
+  { name: "manifest_freshness", run: checkManifestFreshness },
+  { name: "prerender_pollution", run: checkPrerenderPollution },
+  { name: "cloneelement_warnings", run: checkCloneElementWarnings },
+  { name: "dev_artifacts_in_prod", run: checkDevArtifactsInProd },
+  { name: "package_export_gaps", run: checkPackageExportGaps },
+] as const;
+
+/**
+ * Run every extended check in parallel and return the aggregate report.
+ *
+ * Legacy checks (kitchen_errors, guard_check, contract_validation,
+ * manifest_validation) are NOT run here — they live in the MCP tool
+ * surface and have different dependency requirements. Instead, the MCP
+ * `mandu.diagnose` composite combines the extended checks with the
+ * legacy ones and normalizes both into a single unified report.
+ */
+export async function runExtendedDiagnose(rootDir: string): Promise<DiagnoseReport> {
+  const checks = await Promise.all(
+    EXTENDED_CHECKS.map(async ({ run }) => {
+      try {
+        return await run(rootDir);
+      } catch (err) {
+        // Defensive fallback — individual checks shouldn't throw, but if
+        // one does, we surface it as an error rather than crashing the
+        // whole diagnose run.
+        return {
+          ok: false,
+          rule: "diagnose_internal_error",
+          severity: "error" as const,
+          message: `Check threw an error: ${err instanceof Error ? err.message : String(err)}`,
+        };
+      }
+    })
+  );
+
+  return buildReport(checks);
+}
+
+/**
+ * Aggregate a pre-computed list of check results into a `DiagnoseReport`.
+ * Exported so the MCP composite can pass in both extended + legacy checks
+ * at once.
+ */
+export function buildReport(checks: DiagnoseCheckResult[]): DiagnoseReport {
+  let errorCount = 0;
+  let warningCount = 0;
+  for (const c of checks) {
+    if (c.ok) continue;
+    if (c.severity === "error") errorCount += 1;
+    else if (c.severity === "warning") warningCount += 1;
+  }
+  return {
+    healthy: errorCount === 0,
+    errorCount,
+    warningCount,
+    checks,
+    summary: {
+      total: checks.length,
+      passed: checks.filter((c) => c.ok).length,
+      failed: checks.filter((c) => !c.ok).length,
+    },
+  };
+}

package/src/diagnose/types.ts

@@ -0,0 +1,53 @@
+/**
+ * Mandu Diagnose — unified check result shape.
+ *
+ * Every diagnose check returns a `DiagnoseCheckResult`. Severity semantics:
+ *
+ *   - `error`   : blocks deploy. CI should fail. Example: stale dev-mode
+ *                 manifest shipped to prod, package export gap, empty bundles
+ *                 with islands declared.
+ *   - `warning` : degraded UX or future risk. Does NOT block deploy, but
+ *                 surfaces for operator attention. Example: suspicious
+ *                 prerendered routes, many cloneElement warnings.
+ *   - `info`    : neutral observation, no action required.
+ *
+ * The `rule` field is a stable machine-readable identifier. The `message`
+ * field is human-readable and MAY include route paths or counts. The
+ * optional `suggestion` field is a single actionable next step.
+ */
+export type DiagnoseSeverity = "error" | "warning" | "info";
+
+export interface DiagnoseCheckResult {
+  /** Overall pass/fail for this check. `true` = healthy. */
+  ok: boolean;
+  /** Stable machine-readable rule id, e.g. `manifest_freshness`. */
+  rule: string;
+  /** Severity when `ok === false`. Omitted when `ok === true`. */
+  severity?: DiagnoseSeverity;
+  /** Human-readable summary. */
+  message: string;
+  /** Single-line actionable next step, e.g. `"Run mandu build"`. */
+  suggestion?: string;
+  /** Structured details (route list, counts, file paths). */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Aggregated report across all checks for a single diagnose run.
+ */
+export interface DiagnoseReport {
+  /** `true` when no check has `ok: false` with `severity: 'error'`. */
+  healthy: boolean;
+  /** Count of checks returning `ok: false` with `severity: 'error'`. */
+  errorCount: number;
+  /** Count of checks returning `ok: false` with `severity: 'warning'`. */
+  warningCount: number;
+  /** Individual check results in registration order. */
+  checks: DiagnoseCheckResult[];
+  /** Summary statistics. */
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+  };
+}

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