@mandujs/core 0.31.0 → 0.32.0

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 협상
 // ═══════════════════════════════════════════════════════════════════════════

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