@mandujs/core 0.53.2 → 0.54.0

package/src/guard/auto-correct.ts

@@ -4,7 +4,7 @@ import { GUARD_RULES } from "./rules";
 import { runGuardCheck } from "./check";
 import { generateRoutes } from "../generator/generate";
 import { beginChange, commitChange, rollbackChange } from "../change";
-
+
 
 export interface AutoCorrectStep {
   ruleId: string;

package/src/guard/contract-guard.ts

@@ -199,15 +199,15 @@ export async function checkContractSlotConsistency(
 /**
  * Run all contract-related guard checks
  */
-export async function runContractGuardCheck(
-  manifest: RoutesManifest,
-  rootDir: string
-): Promise<ContractViolation[]> {
-  const violations: ContractViolation[] = [];
-
-  // Check missing contracts (warning level)
-  const missingContracts = await checkMissingContract(manifest, rootDir);
-  violations.push(...missingContracts);
+export async function runContractGuardCheck(
+  manifest: RoutesManifest,
+  rootDir: string
+): Promise<ContractViolation[]> {
+  const violations: ContractViolation[] = [];
+
+  // Check missing contracts (warning level)
+  const missingContracts = await checkMissingContract(manifest, rootDir);
+  violations.push(...missingContracts);
 
   // Check contract file exists
   const notFoundContracts = await checkContractFileExists(manifest, rootDir);

package/src/guard/define-rule.ts

@@ -1,243 +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 };
-}
+/**
+ * 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 };
+}