@goplusvn/core 0.1.66 → 0.1.69

package/src/guardrails/rules/safety.ts

@@ -0,0 +1,86 @@
+import { forbidPattern } from "../primitives";
+import type { GuardrailRule } from "../types";
+
+/**
+ * An toàn giao dịch & khoá.
+ *
+ * Hai rule đầu chặn kiểu lỗi làm TREO CẢ APP chứ không phải sai một màn hình:
+ * giữ kết nối DB trong lúc chờ mạng thì pool cạn, và khoá hàng bằng `FOR UPDATE`
+ * thì deadlock với advisory lock đánh số chứng từ. Rule thứ ba chặn kiểu chậm
+ * dần đều: truy vấn không chặn số dòng, chạy tốt hôm nay và chết theo lịch sử.
+ */
+export const safetyRules: GuardrailRule[] = [
+  forbidPattern({
+    id: "safety/no-raw-for-update",
+    title: "không dùng `FOR UPDATE` thô — nối tiếp qua advisory lock",
+    why:
+      "Khoá hàng bằng FOR UPDATE cùng lúc với advisory lock đánh số chứng từ tạo " +
+      "hai thứ tự khoá khác nhau → deadlock, và deadlock ở đây biểu hiện thành " +
+      "'lưu đơn bị treo' chứ không thành lỗi rõ ràng.",
+    fix: "Dùng advisory lock của bộ đánh số chứng từ (@goerp/core/document-number).",
+    pattern: /\bFOR\s+UPDATE\b/i,
+  }),
+
+  {
+    id: "safety/no-network-in-transaction",
+    title: "không gọi mạng/tích hợp bên trong thân $transaction",
+    why:
+      "Chờ HTTP trong khi đang giữ một kết nối DB và các khoá của nó: một tích " +
+      "hợp chậm là đủ làm cạn pool và cả app đứng, chứ không chỉ tính năng đó lỗi.",
+    fix: "Gọi tích hợp TRƯỚC hoặc SAU transaction; trong transaction chỉ đọc/ghi DB.",
+    run(ctx) {
+      const danger = ctx.options.domain?.networkInTransaction ?? /\bfetch\(/;
+      const test = new RegExp(danger.source, danger.flags.replace(/[gy]/g, ""));
+      const offenders: string[] = [];
+      for (const file of ctx.files) {
+        const code = ctx.readCode(file);
+        if (!code.includes("$transaction(")) continue;
+        if (ctx.callBodies(code, "$transaction(").some((b) => test.test(b))) {
+          offenders.push(ctx.rel(file));
+        }
+      }
+      return offenders;
+    },
+  },
+
+  {
+    id: "safety/page-findmany-capped",
+    title: "findMany của bảng giao dịch trong page phải chặn số dòng bằng `take`",
+    why:
+      "Một Server Component nạp cả bảng giao dịch, JSON.stringify nó, rồi đổ vào " +
+      "`<Select>` sẽ render mọi hàng — chi phí lớn dần theo lịch sử, nên nó chạy " +
+      "tốt lúc viết và chậm dần tới mức không mở nổi trang sau vài tháng.",
+    fix: "Thêm `take` (và chèn riêng hàng đang được tham chiếu nếu nó có thể nằm ngoài giới hạn).",
+    run(ctx) {
+      const models = ctx.options.domain?.cappedFindManyModels;
+      if (!models || models.length === 0) return null;
+      const allowed = new Set(ctx.options.allowlists["safety/page-findmany-capped"] ?? []);
+      const offenders: string[] = [];
+      for (const file of ctx.files) {
+        const rel = ctx.rel(file);
+        if (!rel.startsWith("app/") || !rel.endsWith("page.tsx")) continue;
+        if (allowed.has(rel)) continue;
+        const code = ctx.readCode(file);
+        for (const model of models) {
+          for (const body of ctx.callBodies(code, `db.${model}.findMany(`)) {
+            if (!/\btake\s*:/.test(body)) {
+              offenders.push(`${rel} — db.${model}.findMany thiếu take`);
+            }
+          }
+        }
+      }
+      return offenders;
+    },
+    staleAllowlist(ctx) {
+      const models = ctx.options.domain?.cappedFindManyModels ?? [];
+      const allowed = ctx.options.allowlists["safety/page-findmany-capped"] ?? [];
+      return allowed.filter((rel) => {
+        if (!ctx.existsInSrc(rel)) return true;
+        const code = ctx.readCodeRel(rel);
+        return models.every((m) =>
+          ctx.callBodies(code, `db.${m}.findMany(`).every((b) => /\btake\s*:/.test(b)),
+        );
+      });
+    },
+  },
+];

package/src/guardrails/rules/structure.ts

@@ -0,0 +1,136 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+import type { GuardrailContext, GuardrailRule } from "../types";
+
+const appFiles = (ctx: GuardrailContext) =>
+  ctx.files.map(ctx.rel).filter((rel) => rel.startsWith("app/"));
+
+/**
+ * Docker dùng glob riêng, không phải glob của shell. Mô phỏng lại để bắt được
+ * trường hợp `.dockerignore` nuốt mất mã nguồn thật.
+ */
+function dockerGlobToRegex(pattern: string): RegExp {
+  const parts = pattern.split("/");
+  let re = "^";
+  parts.forEach((seg, i) => {
+    if (seg === "**") {
+      re += "(.*/)?";
+    } else {
+      re += seg
+        .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+        .replace(/\\\*/g, "[^/]*")
+        .replace(/\\\?/g, "[^/]");
+      if (i !== parts.length - 1) re += "/";
+    }
+  });
+  return new RegExp(re + "$");
+}
+
+/**
+ * Đặt tên & vị trí file.
+ *
+ * Nghe như chuyện thẩm mỹ, thực ra là chuyện đọc nhầm file. Một trang gồm ĐÚNG
+ * hai file cạnh nhau: `page.tsx` (server, lấy dữ liệu) và `<slug>-client-page.tsx`
+ * (client). Khi cùng một vai trò mang bốn cái tên khác nhau thì nhìn tên file
+ * không đoán được đâu là trang, đâu là mảnh giao diện — và mở nhầm là chuyện
+ * xảy ra hằng ngày.
+ */
+export const structureRules: GuardrailRule[] = [
+  {
+    id: "structure/no-client-suffix",
+    title: "không còn `*-client.tsx` (dùng `*-client-page.tsx`)",
+    why: "Hai quy ước song song cho cùng một vai trò khiến tìm kiếm ra hai nhóm kết quả rời rạc.",
+    fix: "Đổi tên thành `<slug>-client-page.tsx`.",
+    run: (ctx) => appFiles(ctx).filter((rel) => /-client\.tsx$/.test(rel)),
+  },
+
+  {
+    id: "structure/page-suffix-reserved",
+    title: "chỉ `page.tsx` và `*-client-page.tsx` được mang đuôi `-page`",
+    why: "Đuôi `-page` là tín hiệu 'đây là một trang'. Dùng cho mảnh giao diện thì tín hiệu đó vô nghĩa.",
+    fix: "Đổi tên mảnh giao diện thành danh từ mô tả nó, đặt trong `_components/`.",
+    run: (ctx) =>
+      appFiles(ctx).filter(
+        (rel) => /-page\.tsx$/.test(rel) && !/-client-page\.tsx$/.test(rel),
+      ),
+  },
+
+  {
+    id: "structure/client-page-beside-page",
+    title: "`*-client-page.tsx` nằm CẠNH `page.tsx`, không nhét vào `_components/`",
+    why: "Cặp server/client của một trang tách hai chỗ thì đọc luồng dữ liệu phải nhảy thư mục.",
+    fix: "Chuyển file lên cùng cấp với `page.tsx`.",
+    run: (ctx) =>
+      appFiles(ctx).filter(
+        (rel) => /-client-page\.tsx$/.test(rel) && rel.includes("/_components/"),
+      ),
+  },
+
+  {
+    id: "structure/private-folders-underscored",
+    title: "thư mục phụ trong app/ phải gạch dưới (`_components`, không phải `components`)",
+    why: "Không gạch dưới thì Next coi đó là một route segment thật — sinh ra URL không ai định tạo.",
+    fix: "Đổi tên thành `_components`, `_hooks`, `_utils`…",
+    run: (ctx) =>
+      appFiles(ctx).filter((rel) =>
+        /\/(components|hooks|constants|utils|types)\//.test(rel),
+      ),
+  },
+
+  {
+    id: "structure/no-backup-files",
+    title: "không có .bak/.old/.orig/.copy trong src/",
+    why:
+      "Bản sao cũ của một file đang sống là bẫy đọc nhầm tệ nhất: nội dung na ná, " +
+      "tìm kiếm ra hai kết quả, không có gì cho biết cái nào mới. Một file .bak 46KB " +
+      "từng nằm trong repo nhiều ngày mà đợt quét code chết không thấy (nó chỉ duyệt .ts/.tsx).",
+    fix: "Xoá file backup — git giữ lịch sử rồi.",
+    run(ctx) {
+      const junk: string[] = [];
+      const walk = (dir: string) => {
+        for (const e of readdirSync(dir)) {
+          if (e === "node_modules" || e === ".next") continue;
+          const full = join(dir, e);
+          if (statSync(full).isDirectory()) walk(full);
+          else if (/\.(bak|old|orig|copy)$|\.tsx?\.(bak|old|orig)$/i.test(e)) {
+            junk.push(relative(ctx.srcDir, full).split("\\").join("/"));
+          }
+        }
+      };
+      if (existsSync(ctx.srcDir)) walk(ctx.srcDir);
+      return junk;
+    },
+  },
+
+  {
+    id: "structure/dockerignore-keeps-source",
+    title: ".dockerignore không loại nhầm mã nguồn app",
+    why:
+      "Đã dính: glob `**/check-*.ts` nhằm loại script dev nuốt luôn handler thật " +
+      "`modules/sales/api/.../check-resold.ts`. Build trên Docker 500 'Module not " +
+      "found', còn build local (không đọc .dockerignore) vẫn xanh — nên không cách " +
+      "nào phát hiện trước khi lên server.",
+    fix: "Thu hẹp glob của script dev về `**/scripts/`, đừng để `**/check-*.ts` trần.",
+    run(ctx) {
+      const path = join(ctx.root, ".dockerignore");
+      if (!existsSync(path)) return null;
+      const patterns = readFileSync(path, "utf8")
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith("#") && !l.startsWith("!"))
+        .map(dockerGlobToRegex);
+
+      const srcName = relative(ctx.root, ctx.srcDir).split("\\").join("/") || "src";
+      const offenders: string[] = [];
+      for (const file of ctx.files) {
+        const rel = ctx.rel(file);
+        if (!rel.startsWith("app/") && !rel.startsWith("modules/")) continue;
+        // .dockerignore neo ở gốc build context.
+        const contextPath = `${srcName}/${rel}`;
+        if (patterns.some((re) => re.test(contextPath))) offenders.push(contextPath);
+      }
+      return offenders;
+    },
+  },
+];

package/src/guardrails/run.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+
+import { coreGuardrails, skipReasonFor } from "./preset";
+import { createContext } from "./scanner";
+import type { GuardrailOptions, GuardrailRule } from "./types";
+
+const GROUP_TITLES: Record<string, string> = {
+  auth: "cổng xác thực & phân quyền",
+  rbac: "toàn vẹn registry quyền",
+  layering: "ranh giới tầng",
+  "one-door": "một cửa",
+  structure: "đặt tên & vị trí file",
+  design: "hệ thiết kế",
+  safety: "an toàn giao dịch & hiệu năng",
+  debt: "nợ kỹ thuật (ratchet)",
+};
+
+/** Thông báo khi đỏ: nói SỰ CỐ trước, rồi mới nói phải làm gì. */
+function failureMessage(rule: GuardrailRule, extra?: string): string {
+  return [
+    `[${rule.id}] ${rule.why}`,
+    `→ ${rule.fix}`,
+    extra,
+    "Đổi quy ước có chủ đích? Sửa allowlist/trần trong CÙNG commit, hoặc khai " +
+      "`skip: { \"" + rule.id + '": "lý do" }` — suất tắt phải nhìn thấy được trong diff.',
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+/**
+ * Nạp bộ hàng rào chuẩn vào file test của app.
+ *
+ * File `src/__tests__/architecture.test.ts` của app chỉ còn phần DỮ LIỆU riêng
+ * của nó (allowlist nợ cũ, trần, rule domain). Luật thì đi theo `@goerp/core`,
+ * nên nâng core là nhận luật mới — thay vì mỗi app giữ một bản chép tay đóng
+ * băng ở ngày nó được scaffold.
+ *
+ * ```ts
+ * runCoreGuardrails({
+ *   permissionRegistry,
+ *   navigations,
+ *   allowlists: { "design/list-table-uses-kit": [...] },
+ *   ceilings: { "debt/any": { app: 671 } },
+ *   skip: { "layering/domain-framework-free": "nợ 49 page SSR, xem docs/..." },
+ * })
+ * ```
+ */
+export function runCoreGuardrails(options: GuardrailOptions = {}): void {
+  const ctx = createContext(options);
+  const rules = coreGuardrails(options);
+  const skip = options.skip ?? {};
+
+  const byGroup = new Map<string, GuardrailRule[]>();
+  for (const rule of rules) {
+    const group = rule.id.split("/")[0];
+    byGroup.set(group, [...(byGroup.get(group) ?? []), rule]);
+  }
+
+  describe("hàng rào kiến trúc (@goerp/core/guardrails)", () => {
+    it("bộ rule lành mạnh: có rule để chạy, id không trùng", () => {
+      expect(rules.length).toBeGreaterThan(0);
+      const seen = new Set<string>();
+      const dup = rules.map((r) => r.id).filter((id) => !seen.has(id) && !seen.add(id));
+      expect(dup, "Hai rule cùng id thì cái sau che cái trước khi khai `skip`.").toEqual(
+        [],
+      );
+    });
+
+    it("mọi suất tắt (`skip`) đều trỏ tới rule có thật và vẫn còn cần thiết", () => {
+      const ids = new Set(rules.map((r) => r.id));
+      const stale: string[] = [];
+      for (const key of Object.keys(skip)) {
+        if (key.endsWith("/*")) {
+          const group = key.slice(0, -2);
+          if (![...ids].some((id) => id.startsWith(`${group}/`))) {
+            stale.push(`${key} — không có rule nào thuộc nhóm này`);
+          }
+          continue;
+        }
+        if (!ids.has(key)) {
+          stale.push(`${key} — không có rule nào mang id này (đổi tên? gõ nhầm?)`);
+          continue;
+        }
+        const rule = rules.find((r) => r.id === key)!;
+        const violations = rule.run(ctx);
+        if (violations !== null && violations.length === 0) {
+          stale.push(`${key} — rule này giờ đã XANH, gỡ khỏi \`skip\``);
+        }
+      }
+      expect(
+        stale,
+        "Suất tắt bỏ ngỏ là cách hàng rào mục dần: nợ trả rồi mà `skip` còn đó " +
+          "thì lần sau có người lặng lẽ dùng lại nó.",
+      ).toEqual([]);
+    });
+  });
+
+  for (const [group, groupRules] of byGroup) {
+    describe(`${group} — ${GROUP_TITLES[group] ?? group}`, () => {
+      for (const rule of groupRules) {
+        const reason = skipReasonFor(rule.id, skip);
+        if (reason) {
+          it.skip(`${rule.title}  [tắt: ${reason}]`, () => {});
+          continue;
+        }
+
+        it(rule.title, () => {
+          const violations = rule.run(ctx);
+          if (violations === null) return; // không áp dụng cho app này
+          expect(violations, failureMessage(rule)).toEqual([]);
+        });
+
+        if (rule.staleAllowlist) {
+          it(`${rule.title} — allowlist chỉ được rút bớt`, () => {
+            const stale = rule.staleAllowlist!(ctx);
+            expect(
+              stale,
+              failureMessage(
+                rule,
+                "Các mục trên hết lý do tồn tại (file đã xoá hoặc đã hết vi phạm). " +
+                  "Mỗi tên thừa là một suất miễn trừ bỏ ngỏ.",
+              ),
+            ).toEqual([]);
+          });
+        }
+      }
+    });
+  }
+}

package/src/guardrails/scanner.ts

@@ -0,0 +1,144 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+import type {
+  GuardrailContext,
+  GuardrailOptions,
+  ResolvedGuardrailOptions,
+} from "./types";
+
+const DEFAULT_IGNORE = [
+  "node_modules",
+  ".next",
+  ".turbo",
+  "__tests__",
+  "dist",
+  "coverage",
+];
+
+/**
+ * Bỏ chú thích trước khi quét.
+ *
+ * Code trong hệ này viết tiếng Việt rất nhiều ở phần chú thích, và chú thích
+ * thường NHẮC LẠI đúng cái mẫu mà rule đang cấm ("đừng dùng window.open"). Quét
+ * trên bản thô là guardrail tự bắt chính lời cảnh báo của mình.
+ */
+export function stripComments(src: string): string {
+  return (
+    src
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      // Giữ `http://` — nếu không thì mọi URL trong chuỗi bị cắt cụt.
+      .replace(/(^|[^:])\/\/.*$/gm, "$1")
+  );
+}
+
+/**
+ * Cắt thân đối số của từng lời gọi `<needle>` bằng cách đếm ngoặc cân bằng.
+ *
+ * Dùng cho các rule kiểu "trong thân `$transaction(...)` không được gọi mạng"
+ * hay "`findMany(...)` phải có `take`": tham số trải nhiều dòng nên regex một
+ * dòng hoặc bỏ sót, hoặc ăn lem sang lời gọi kế tiếp.
+ */
+export function callBodies(code: string, needle: string): string[] {
+  const bodies: string[] = [];
+  let idx = code.indexOf(needle);
+  while (idx !== -1) {
+    let i = idx + needle.length;
+    let depth = 1;
+    const start = i;
+    while (i < code.length && depth > 0) {
+      const ch = code[i];
+      if (ch === "(") depth++;
+      else if (ch === ")") depth--;
+      i++;
+    }
+    bodies.push(code.slice(start, i - 1));
+    idx = code.indexOf(needle, i);
+  }
+  return bodies;
+}
+
+export function resolveOptions(
+  options: GuardrailOptions = {},
+): ResolvedGuardrailOptions {
+  const root = resolve(options.root ?? process.cwd());
+  return {
+    ...options,
+    root,
+    srcDir: options.srcDir ? resolve(options.srcDir) : join(root, "src"),
+    allowlists: options.allowlists ?? {},
+    ceilings: options.ceilings ?? {},
+    skip: options.skip ?? {},
+    doors: {
+      prisma: options.doors?.prisma ?? "lib/prisma.ts",
+      storage: options.doors?.storage ?? ["lib/storage.ts"],
+      // Composition root (`lib/prisma.ts`) là cửa hợp lệ mặc định: app nhỏ cắm
+      // branch-guard thẳng vào chỗ tạo client thay vì tách file riêng.
+      branchScope: options.doors?.branchScope ?? [
+        "lib/branch-scope.ts",
+        "lib/rbac/branch-scope.ts",
+        "lib/prisma.ts",
+      ],
+    },
+  };
+}
+
+/**
+ * Dựng ngữ cảnh quét: đi hết cây `src`, nhớ nội dung để ~70 rule không phải đọc
+ * lại cùng một file 70 lần (một app cỡ vinhhoa là ~1.400 file — đọc lại là mất
+ * vài chục giây mỗi lần chạy test).
+ */
+export function createContext(options: GuardrailOptions = {}): GuardrailContext {
+  const resolved = resolveOptions(options);
+  const { srcDir, root } = resolved;
+  const ignore = new Set([...DEFAULT_IGNORE, ...(options.ignoreDirs ?? [])]);
+
+  const files: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir)) {
+      if (ignore.has(entry)) continue;
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) walk(full);
+      else if (/\.(ts|tsx)$/.test(entry) && !/\.test\.tsx?$/.test(entry)) {
+        files.push(full);
+      }
+    }
+  };
+  if (existsSync(srcDir)) walk(srcDir);
+
+  const rawCache = new Map<string, string>();
+  const codeCache = new Map<string, string>();
+
+  const read = (file: string) => {
+    let cached = rawCache.get(file);
+    if (cached === undefined) {
+      cached = existsSync(file) ? readFileSync(file, "utf8") : "";
+      rawCache.set(file, cached);
+    }
+    return cached;
+  };
+
+  const readCode = (file: string) => {
+    let cached = codeCache.get(file);
+    if (cached === undefined) {
+      cached = stripComments(read(file));
+      codeCache.set(file, cached);
+    }
+    return cached;
+  };
+
+  return {
+    root,
+    srcDir,
+    files,
+    rel: (file) => relative(srcDir, file).split("\\").join("/"),
+    read,
+    readCode,
+    existsInSrc: (relPath) => existsSync(join(srcDir, relPath)),
+    existsInRoot: (relPath) => existsSync(join(root, relPath)),
+    readRel: (relPath) => read(join(srcDir, relPath)),
+    readCodeRel: (relPath) => readCode(join(srcDir, relPath)),
+    callBodies,
+    options: resolved,
+  };
+}

package/src/guardrails/types.ts

@@ -0,0 +1,181 @@
+/**
+ * Kiểu dữ liệu của bộ hàng rào kiến trúc.
+ *
+ * Mỗi `GuardrailRule` là một **ca lỗi thật** đã từng tốn thời gian ở app gốc
+ * (vinhhoa) được viết lại thành phép quét tĩnh. Rule mang theo `why` — nguyên
+ * văn sự cố — vì thông báo lỗi mới là chỗ người/agent đời sau thực sự đọc;
+ * quy tắc nằm trong tài liệu thì bị bỏ qua, nằm trong test đỏ thì không.
+ */
+
+/** Một rule không áp dụng cho app này (thiếu thư mục/tệp mà nó soi). */
+export const NOT_APPLICABLE = null;
+
+export interface GuardrailContext {
+  /** Gốc app (chứa package.json, .dockerignore…). */
+  root: string;
+  /** Thư mục mã nguồn, thường là `<root>/src`. */
+  srcDir: string;
+  /** Đường dẫn TUYỆT ĐỐI mọi file .ts/.tsx đang được soi (đã loại test). */
+  files: string[];
+  /** Đường dẫn tương đối `srcDir`, luôn dùng dấu `/` kể cả trên Windows. */
+  rel(file: string): string;
+  /** Nội dung thô. */
+  read(file: string): string;
+  /** Nội dung đã BỎ chú thích — mọi phép quét mẫu nên dùng bản này. */
+  readCode(file: string): string;
+  /** Tồn tại không, đường dẫn tương đối `srcDir`. */
+  existsInSrc(relPath: string): boolean;
+  /** Tồn tại không, đường dẫn tương đối `root`. */
+  existsInRoot(relPath: string): boolean;
+  /** Đọc file theo đường dẫn tương đối `srcDir` (rỗng nếu không có). */
+  readRel(relPath: string): string;
+  /** Như `readRel` nhưng đã bỏ chú thích — mặc định nên dùng bản này. */
+  readCodeRel(relPath: string): string;
+  /**
+   * Cắt thân đối số của mọi lời gọi `<needle>` bằng cách khớp ngoặc cân bằng.
+   * Regex một dòng không làm được việc này khi tham số trải nhiều dòng.
+   */
+  callBodies(code: string, needle: string): string[];
+  /** Tuỳ chọn người dùng truyền vào, đã điền mặc định. */
+  options: ResolvedGuardrailOptions;
+}
+
+export interface GuardrailRule {
+  /** Định danh ổn định, dạng `nhóm/tên-gạch-nối` — dùng làm khoá `skip`. */
+  id: string;
+  /** Câu mô tả hiển thị làm tên `it(...)`. */
+  title: string;
+  /** Sự cố có thật đứng sau rule. In ra khi test đỏ. */
+  why: string;
+  /** Việc cần làm để hết đỏ. */
+  fix: string;
+  /**
+   * Trả danh sách vi phạm (rỗng = đạt), hoặc `NOT_APPLICABLE` khi app không có
+   * thứ mà rule soi — im lặng bỏ qua thay vì đỏ oan.
+   */
+  run(ctx: GuardrailContext): string[] | null;
+  /**
+   * Với rule có allowlist: entry nào đã hết lý do tồn tại. Suất miễn trừ bỏ
+   * ngỏ là cách guardrail mục dần — nợ trả rồi mà tên vẫn nằm đó thì lần sau
+   * có người lặng lẽ dùng lại suất ấy.
+   */
+  staleAllowlist?(ctx: GuardrailContext): string[];
+}
+
+/** Nhóm rule để báo cáo và để `skip` theo cả cụm (`"design/*"`). */
+export type GuardrailGroup =
+  | "auth"
+  | "rbac"
+  | "layering"
+  | "one-door"
+  | "structure"
+  | "design"
+  | "safety";
+
+export interface GuardrailOptions {
+  /** Gốc app. Mặc định `process.cwd()`. */
+  root?: string;
+  /** Thư mục nguồn. Mặc định `<root>/src`. */
+  srcDir?: string;
+  /**
+   * Registry quyền của app (`src/configs/permissions`). Thiếu thì nhóm rule
+   * `rbac/*` tự bỏ qua.
+   */
+  permissionRegistry?: PermissionFeatureLike[];
+  /** Cây menu (`src/data/navigations`). Thiếu thì rule nav tự bỏ qua. */
+  navigations?: NavigationGroupLike[];
+  /**
+   * Bộ action ai cũng hiểu. PHẢI trùng danh sách trong `scripts/rbac-sync.ts`
+   * của app — lệch nhau thì test xanh mà seed ném lỗi lúc deploy.
+   */
+  standardActions?: string[];
+  /**
+   * Nợ cũ theo từng rule: `{ "<ruleId>": ["đường/dẫn.ts", …] }`. Engine chỉ
+   * cho RÚT BỚT — thêm tên mới thì phải giải trình trong review.
+   */
+  allowlists?: Record<string, string[]>;
+  /**
+   * Trần theo thư mục cấp 1: `{ "<ruleId>": { app: 671, lib: 91 } }`.
+   * Vượt trần = đỏ. Dư trần cũng đỏ — trả nợ tới đâu hạ trần tới đó.
+   */
+  ceilings?: Record<string, Record<string, number>>;
+  /**
+   * Tắt rule kèm LÝ DO bắt buộc. Đây là van an toàn để bump core không làm
+   * gãy app đang chạy; đổi lại mỗi suất tắt đều hiện hình trong git diff.
+   * Nhận cả `"nhóm/*"`.
+   */
+  skip?: Record<string, string>;
+  /** Rule riêng của app (domain SSOT, một-cửa repository…). */
+  extraRules?: GuardrailRule[];
+  /** Thư mục bỏ qua khi quét, ngoài mặc định. */
+  ignoreDirs?: string[];
+  /** Vài rule cần biết từ vựng riêng của app. */
+  domain?: {
+    /**
+     * Mẫu lời gọi mạng/tích hợp bị cấm trong thân `$transaction`. Mặc định chỉ
+     * bắt `fetch(`; app nên bổ sung tên client tích hợp của mình.
+     */
+    networkInTransaction?: RegExp;
+    /**
+     * Model mà `findMany` trong một `page.tsx` bắt buộc phải có `take` — dùng
+     * cho bảng giao dịch lớn đổ vào dropdown.
+     */
+    cappedFindManyModels?: string[];
+    /**
+     * Tên hàm CỔNG — thứ mà `{ resource, action }` truyền vào là khai báo
+     * quyền. Mặc định `apiHandler` / `requirePermission` /
+     * `requireApiPermission`. Đặt tên cổng khác mà quên khai ở đây thì hai
+     * thước `rbac/gate-*` im lặng không soi gì cả.
+     */
+    gateCalls?: string[];
+  };
+  /** Đường vào của các engine singleton — mỗi app đặt tên hơi khác nhau. */
+  doors?: {
+    /** File DUY NHẤT được `new PrismaClient()`. Mặc định `lib/prisma.ts`. */
+    prisma?: string;
+    /** File DUY NHẤT được import `@goerp/core/storage`. */
+    storage?: string[];
+    /** File hạ tầng được import `@goerp/core/branch-scope`. */
+    branchScope?: string[];
+  };
+}
+
+export type ResolvedGuardrailOptions = GuardrailOptions &
+  Required<Pick<GuardrailOptions, "root" | "srcDir">> & {
+    allowlists: Record<string, string[]>;
+    ceilings: Record<string, Record<string, number>>;
+    skip: Record<string, string>;
+    doors: {
+      prisma: string;
+      storage: string[];
+      branchScope: string[];
+    };
+  };
+
+/**
+ * Hình dạng TỐI THIỂU của registry quyền mà rule cần đọc. Cố ý không dùng thẳng
+ * kiểu `PermissionFeature` của app: app khai thêm trường gì cũng vẫn khớp, và
+ * guardrails không kéo theo phụ thuộc ngược lên tầng config.
+ */
+export interface PermissionFeatureLike {
+  resources: Array<{
+    code: string;
+    actions: string[];
+    defaultGrants?: Record<string, string[] | "*">;
+  }>;
+  customActions?: Array<{ code: string }>;
+}
+
+export interface NavigationGroupLike {
+  items?: Array<{ resource?: string; [key: string]: unknown }>;
+  [key: string]: unknown;
+}
+
+/** Kết quả chạy một rule — dùng cho `goerp doctor` (không cần vitest). */
+export interface GuardrailResult {
+  rule: GuardrailRule;
+  status: "pass" | "fail" | "skipped" | "not-applicable";
+  violations: string[];
+  staleAllowlist: string[];
+  skipReason?: string;
+}