@goplusvn/core 0.1.66 → 0.1.69

package/src/guardrails/rules/design.ts

@@ -0,0 +1,95 @@
+import { forbidFile } from "../primitives";
+import type { GuardrailRule } from "../types";
+
+const BASE_DISPLAY = /^(flex|inline-flex|grid|inline-grid|block|inline-block|table)$/;
+const BP_HIDDEN = /^(sm|md|lg|xl|2xl):hidden$/;
+
+/**
+ * Hệ thiết kế.
+ *
+ * Hai rule đầu giữ cho token ở MỘT nguồn (core), rule thứ ba là một bẫy
+ * Tailwind v4 rất khó truy, rule cuối giữ bảng danh sách không phân mảnh trở lại.
+ */
+export const designRules: GuardrailRule[] = [
+  forbidFile({
+    id: "design/no-tailwind-config",
+    title: "không có tailwind.config.ts — Tailwind v4 đọc @theme trong globals.css",
+    why:
+      "File config JS bị v4 bỏ qua, nên nó là code chết trông như đang có tác " +
+      "dụng: sửa token ở đó không đổi gì và người sửa mất khá lâu mới hiểu.",
+    fix: "Xoá tailwind.config.ts; khai token trong `@theme` của globals.css.",
+    paths: ["tailwind.config.ts", "tailwind.config.js", "tailwind.config.mjs"],
+  }),
+
+  {
+    id: "design/globals-imports-core-tokens",
+    title: "globals.css nạp tầng token chuẩn từ @goerp/core",
+    why:
+      "Hệ token (Radix → shadcn → semantic) sống ở `@goerp/core/styles/base.css` " +
+      "và được mọi app dùng chung. App tự khai lại tầng `@theme` là fork âm thầm: " +
+      "nâng cấp core không tới được app đó nữa.",
+    fix: "Giữ `@import \"@goerp/core/styles/base.css\"` trong src/app/globals.css.",
+    run(ctx) {
+      if (!ctx.existsInSrc("app/globals.css")) return null;
+      const css = ctx.readRel("app/globals.css");
+      return css.includes("@goerp/core/styles/base.css")
+        ? []
+        : ["app/globals.css — thiếu @import @goerp/core/styles/base.css"];
+    },
+  },
+
+  {
+    id: "design/no-fragile-flex-hidden",
+    title: "không dùng `flex {bp}:hidden` — dùng `hidden max-{bp}:flex`",
+    why:
+      "Tailwind v4 + Next chia CSS thành chunk: class `.flex` cơ sở có thể được " +
+      "emit ở chunk tải SAU rồi đè `.lg:hidden` (media query KHÔNG tăng độ ưu " +
+      "tiên → cái đứng sau thắng). Hậu quả: phần tử 'chỉ-mobile' vẫn hiện trên " +
+      "desktop → header/thanh công cụ NHÂN ĐÔI. Đã dính ở 4 màn cùng lúc.",
+    fix: "Đảo lại: cơ sở là `hidden`, hiện lại bằng `max-{bp}:flex` — không có `.flex` cơ sở để bị đè.",
+    run(ctx) {
+      const offenders: string[] = [];
+      for (const file of ctx.files) {
+        if (!file.endsWith(".tsx")) continue;
+        const code = ctx.readCode(file);
+        const classStrings = [
+          ...code.matchAll(/className=(?:"([^"]*)"|'([^']*)'|\{`([^`]*)`\})/g),
+        ].map((m) => m[1] ?? m[2] ?? m[3] ?? "");
+        for (const cls of classStrings) {
+          const tokens = cls.split(/\s+/).filter(Boolean);
+          if (
+            tokens.some((t) => BASE_DISPLAY.test(t)) &&
+            tokens.some((t) => BP_HIDDEN.test(t))
+          ) {
+            offenders.push(`${ctx.rel(file)}  ["${cls.slice(0, 70)}"]`);
+            break;
+          }
+        }
+      }
+      return offenders;
+    },
+  },
+
+  {
+    id: "design/list-table-uses-kit",
+    title: "bảng mới trong app/ dùng DataTableWrapper, không tự dựng <Table>",
+    why:
+      "Bảng tự dựng lại thiếu một trong: header dính, phân trang, trạng thái " +
+      "rỗng, hàng bấm được, footer tổng. Mỗi bảng thiếu một thứ khác nhau, và " +
+      "người dùng học lại thao tác ở mỗi trang.",
+    fix: "Dùng `DataTableWrapper` + cột tanstack trong `*-columns.tsx`. Thật sự phải tự dựng thì thêm vào allowlist kèm lý do.",
+    run(ctx) {
+      const allowed = new Set(ctx.options.allowlists["design/list-table-uses-kit"] ?? []);
+      const handRolled = ctx.files
+        .map(ctx.rel)
+        .filter((rel) => rel.startsWith("app/") && /<TableBody/.test(ctx.readCodeRel(rel)));
+      return handRolled.filter((rel) => !allowed.has(rel));
+    },
+    staleAllowlist(ctx) {
+      const allowed = ctx.options.allowlists["design/list-table-uses-kit"] ?? [];
+      return allowed.filter(
+        (rel) => !ctx.existsInSrc(rel) || !/<TableBody/.test(ctx.readCodeRel(rel)),
+      );
+    },
+  },
+];

package/src/guardrails/rules/layering.ts

@@ -0,0 +1,160 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import type { GuardrailContext, GuardrailRule } from "../types";
+
+/** Tên các module nghiệp vụ dưới `src/modules/`. Rỗng = app chưa module hoá. */
+function moduleNames(ctx: GuardrailContext): string[] {
+  const dir = join(ctx.srcDir, "modules");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((e) => statSync(join(dir, e)).isDirectory());
+}
+
+/**
+ * Stub route hợp lệ: `app/api/**\/route.ts` CHỈ re-export handler từ
+ * `modules/<domain>/api/**`. Next cần một file trong `app/` để mount URL, còn
+ * logic sống trong module. Nội dung phải là re-export thuần, không thêm code.
+ */
+const isRouteStub = (rel: string, code: string): boolean =>
+  /^app\/api\/.*\/route\.ts$/.test(rel) &&
+  /^export \* from ["']@\/modules\/[a-z-]+\/api\/[a-zA-Z0-9/[\]-]+["']$/.test(code.trim());
+
+/**
+ * Deep-import hợp lệ thứ hai: file đích là SERVER ACTION.
+ *
+ * Client component BẮT BUỘC import thẳng file action (đó là ranh giới RPC) —
+ * đi qua barrel sẽ kéo cả module (prisma/auth) vào bundle client và vỡ build
+ * production. Sự cố này đã xảy ra một lần, mất nửa ngày để lần ra.
+ */
+const isServerActionTarget = (ctx: GuardrailContext, spec: string): boolean => {
+  const p = join(ctx.srcDir, spec.replace(/^@\//, "") + ".ts");
+  if (!existsSync(p)) return false;
+  return readFileSync(p, "utf8").trimStart().startsWith('"use server"');
+};
+
+/**
+ * Ranh giới tầng.
+ *
+ * Module hoá chỉ có giá trị nếu ranh giới được CANH. Không canh thì mỗi lần
+ * vội một người deep-import xuyên qua, và sau ba tháng cấu trúc thư mục còn
+ * đó nhưng đồ thị phụ thuộc đã là mì spaghetti như cũ.
+ */
+export const layeringRules: GuardrailRule[] = [
+  {
+    id: "layering/module-public-api",
+    title: "bên ngoài chỉ được import module qua public API (index)",
+    why:
+      "Deep-import xuyên ranh giới tái tạo đúng mớ bòng bong mà việc module hoá " +
+      "đang gỡ: đổi một file nội bộ là gãy chỗ không liên quan.",
+    fix: "Import `@/modules/<domain>` (barrel). Ngoại lệ: stub app/api re-export thuần, và file server action (ranh giới RPC).",
+    run(ctx) {
+      const modules = moduleNames(ctx);
+      if (modules.length === 0) return null;
+      const offenders: string[] = [];
+      for (const file of ctx.files) {
+        const rel = ctx.rel(file);
+        const code = ctx.readCode(file);
+        if (isRouteStub(rel, code)) continue;
+        for (const m of modules) {
+          if (rel.startsWith(`modules/${m}/`)) continue; // nội bộ module đó
+          const deep = new RegExp(`["'](@/modules/${m}/[^"']+)["']`, "g");
+          for (const match of code.matchAll(deep)) {
+            if (isServerActionTarget(ctx, match[1])) continue;
+            offenders.push(`${rel} — deep-import ${match[1]} (dùng @/modules/${m})`);
+          }
+        }
+      }
+      return offenders;
+    },
+  },
+
+  {
+    id: "layering/no-cross-module-internals",
+    title: "module này không deep-import ruột module khác",
+    why:
+      "Hai module dính ruột nhau thì không tách được cái nào ra package riêng, " +
+      "và một thay đổi nội bộ lan sang domain khác.",
+    fix: "Đi qua public API `@/modules/<domain>`, hoặc kéo phần dùng chung xuống `@/lib`.",
+    run(ctx) {
+      const modules = moduleNames(ctx);
+      if (modules.length === 0) return null;
+      const offenders: string[] = [];
+      for (const file of ctx.files) {
+        const rel = ctx.rel(file);
+        const mine = modules.find((m) => rel.startsWith(`modules/${m}/`));
+        if (!mine) continue;
+        for (const other of modules) {
+          if (other === mine) continue;
+          if (new RegExp(`["']@/modules/${other}/`).test(ctx.readCode(file))) {
+            offenders.push(`${rel} — import ruột @/modules/${other}/...`);
+          }
+        }
+      }
+      return offenders;
+    },
+  },
+
+  {
+    id: "layering/lib-below-modules",
+    title: "lib KHÔNG được import @/modules (lib là tầng dưới)",
+    why:
+      "`lib` là hạ tầng — module dựng trên nó. Cho `lib` gọi ngược lên module " +
+      "là tạo vòng phụ thuộc: import một tiện ích nhỏ kéo theo cả domain.",
+    fix: "Wiring theo entity của app đặt ở `server/` hoặc `app/`, hoặc inject từ caller.",
+    run(ctx) {
+      if (moduleNames(ctx).length === 0) return null;
+      return ctx.files
+        .map(ctx.rel)
+        .filter((rel) => rel.startsWith("lib/"))
+        .filter((rel) => /["']@\/modules\//.test(ctx.readCodeRel(rel)))
+        .map((rel) => `${rel} — dời wiring sang server/ hoặc inject từ caller`);
+    },
+  },
+
+  {
+    id: "layering/module-not-import-app",
+    title: "module KHÔNG được import @/app (ngược tầng)",
+    why:
+      "Module là code nghiệp vụ độc lập. Import vào thư mục app là lộn ngược " +
+      "tầng: di chuyển một trang admin làm gãy module và cron, và khi promote " +
+      "module thành package thì path `@/app` không tồn tại.",
+    fix: "Đưa code dùng chung vào chính module hoặc xuống `@/lib`.",
+    run(ctx) {
+      const modules = moduleNames(ctx);
+      if (modules.length === 0) return null;
+      const offenders: string[] = [];
+      for (const file of ctx.files) {
+        const rel = ctx.rel(file);
+        if (!modules.some((m) => rel.startsWith(`modules/${m}/`))) continue;
+        if (/["']@\/app\//.test(ctx.readCode(file))) {
+          offenders.push(`${rel} — import @/app/... (dời code chung vào module/@/lib)`);
+        }
+      }
+      return offenders;
+    },
+  },
+
+  {
+    id: "layering/domain-framework-free",
+    title: "modules ngoài */api/ không dính Next (chạy được ngoài framework)",
+    why:
+      "Đây là điều kiện để sau này tách backend độc lập. Tầng domain lẫn " +
+      "`next/cache`, `next/server` hay chỉ thị `use server` thì nó không còn là " +
+      "domain nữa — nó là transport, và không test được ngoài Next.",
+    fix: "Dời phần Next (session/revalidatePath/'use server') ra `src/actions/` hoặc `modules/*/api/`.",
+    run(ctx) {
+      if (moduleNames(ctx).length === 0) return null;
+      const offenders: string[] = [];
+      for (const file of ctx.files) {
+        const rel = ctx.rel(file);
+        if (!rel.startsWith("modules/")) continue;
+        if (/^modules\/[a-z-]+\/api\//.test(rel)) continue;
+        const code = ctx.readCode(file);
+        if (/from ["']next\//.test(code) || /^\s*["']use server["']/.test(code)) {
+          offenders.push(`${rel} — tách phần Next ra src/actions/ hoặc modules/*/api/`);
+        }
+      }
+      return offenders;
+    },
+  },
+];

package/src/guardrails/rules/one-door.ts

@@ -0,0 +1,115 @@
+import { forbidPattern, singleDoorImport } from "../primitives";
+import type { GuardrailRule } from "../types";
+
+/**
+ * Một cửa.
+ *
+ * Mấy engine của core (`storage`, `branch-scope`) là **singleton phải cấu hình
+ * một lần**. Import thẳng từ core lấy được hàm nhưng KHÔNG kéo theo lời gọi cấu
+ * hình, nên code trông đúng và chỉ nổ lúc chạy thật. Với branch-scope thì "nổ"
+ * nghĩa là người chi nhánh này nhìn thấy dữ liệu chi nhánh khác — im lặng và
+ * nguy hiểm hơn nhiều so với một exception.
+ *
+ * Cùng logic áp cho những đường mà việc có HAI lối đi là bug: PrismaClient thứ
+ * hai = pool kết nối thứ hai + bỏ qua extension audit/branch-guard.
+ */
+export const oneDoorRules: GuardrailRule[] = [
+  {
+    id: "one-door/single-prisma-client",
+    title: "chỉ một file được tạo PrismaClient",
+    why:
+      "Client thứ hai mở pool kết nối thứ hai và bỏ qua mọi extension đã cắm " +
+      "(audit log, chặn phạm vi chi nhánh) — dữ liệu ghi qua đường đó không có vết.",
+    fix: "Import `db` từ cửa duy nhất (mặc định `@/lib/prisma`). Script vận hành chạy độc lập ngoài Next thì thêm vào allowlist.",
+    run(ctx) {
+      const door = ctx.options.doors.prisma;
+      const allowed = new Set(
+        ctx.options.allowlists["one-door/single-prisma-client"] ?? [],
+      );
+      return ctx.files
+        .map(ctx.rel)
+        .filter(
+          (rel) =>
+            rel !== door && !allowed.has(rel) && /new PrismaClient\(/.test(ctx.readCodeRel(rel)),
+        );
+    },
+    staleAllowlist(ctx) {
+      const allowed = ctx.options.allowlists["one-door/single-prisma-client"] ?? [];
+      return allowed.filter(
+        (rel) => !ctx.existsInSrc(rel) || !/new PrismaClient\(/.test(ctx.readCodeRel(rel)),
+      );
+    },
+  },
+
+  singleDoorImport({
+    id: "one-door/storage",
+    title: "chỉ cửa kho tập tin được import @goerp/core/storage",
+    why:
+      "Engine kho là singleton cần `configureStorage()` một lần. Đã dính một " +
+      "lần khi rút ruột adapter MinIO: adapter hết import prisma nên composition " +
+      "root không còn chạy, và mọi lời gọi upload nổ 'chưa configureStorage'.",
+    fix: "Vào kho qua cửa của app (mặc định `@/lib/storage`), chấm hết.",
+    pattern: /from\s+["']@goerp\/core\/storage(\/s3)?["']/,
+    doors: (ctx) => ctx.options.doors.storage,
+    mustConfigure: /configureStorage\s*\(/,
+  }),
+
+  singleDoorImport({
+    id: "one-door/branch-scope",
+    title: "chỉ file hạ tầng được import @goerp/core/branch-scope",
+    why:
+      "Cùng bẫy singleton với kho tập tin, nhưng hậu quả nặng hơn: đây là đường " +
+      "dữ liệu. Quên cấu hình = phạm vi chi nhánh không áp = rò dữ liệu chéo chi nhánh.",
+    fix: "Import qua cửa của app (mặc định `@/lib/branch-scope`); composition root phải gọi `configureBranchScope`.",
+    pattern: /from\s+["']@goerp\/core\/branch-scope["']/,
+    doors: (ctx) => ctx.options.doors.branchScope,
+    mustConfigure: /configureBranchScope\s*[<(]/,
+    // Lớp 2 (`createBranchGuardExtension`) không cần cấu hình singleton; chỉ lớp
+    // 1 mới cần, và thiếu thì nó NÉM ở mọi truy vấn có phạm vi chi nhánh.
+    mustConfigureWhen: (ctx) =>
+      ctx.files.some((f) => /\b(getBranchScope|scopedBranchWhere)\s*\(/.test(ctx.readCode(f))),
+  }),
+
+  forbidPattern({
+    id: "one-door/export-no-window-open",
+    title: "không window.open(...) tới endpoint /export",
+    why:
+      "`window.open` tới API xuất file bỏ qua toàn bộ phần xử lý lỗi và trạng " +
+      "thái chờ: lỗi 500 hiện ra thành một tab trắng có JSON, người dùng tưởng " +
+      "app hỏng. Nó cũng bị trình duyệt chặn popup không báo.",
+    fix: "Dùng `useExport()` / `exportFile()` (@goerp/core/export/use-export).",
+    pattern: /window\.open\([^)\n]*export/,
+  }),
+
+  forbidPattern({
+    id: "one-door/import-dialog",
+    title: "không dùng lại CrudImportDialog đã gỡ",
+    why: "Hai hộp thoại nhập liệu song song thì sửa một bên, bên kia lặng lẽ giữ hành vi cũ.",
+    fix: "Dùng `ImportDialog` hợp nhất (@goerp/core/import).",
+    pattern: /import\s*\{[^}]*\bCrudImportDialog\b|<CrudImportDialog\b/,
+  }),
+
+  {
+    id: "one-door/api-500-persists",
+    title: "mọi đường trả 500 của route API đều ghi vào error_logs",
+    why:
+      "500 không ghi lại thì lỗi production chỉ còn là ảnh chụp màn hình của " +
+      "người dùng. Bảng error_logs là thứ duy nhất giữ stack trace.",
+    fix: "Bọc catch bằng `serverError(error, request, { message })` (hoặc `logServerError` nếu cần giữ response riêng).",
+    run(ctx) {
+      const offenders: string[] = [];
+      for (const file of ctx.files) {
+        const rel = ctx.rel(file);
+        if (!rel.startsWith("app/api/") || !rel.endsWith("/route.ts")) continue;
+        // Chính route ghi log bị loại trừ — nếu không thì đệ quy.
+        if (rel.startsWith("app/api/error-logs/")) continue;
+        const code = ctx.readCode(file);
+        if (!/status:\s*500/.test(code)) continue;
+        if (!/serverError|logServerError|apiHandler|withErrorHandler/.test(code)) {
+          offenders.push(rel);
+        }
+      }
+      return offenders;
+    },
+  },
+];

package/src/guardrails/rules/rbac.ts

@@ -0,0 +1,282 @@
+import { forbidPattern } from "../primitives";
+import type { GuardrailContext, GuardrailRule } from "../types";
+
+/** Bộ action ai cũng hiểu — mặc định, trùng `scripts/rbac-sync.ts` của starter. */
+export const STANDARD_ACTIONS = [
+  "view",
+  "create",
+  "update",
+  "delete",
+  "export",
+  "import",
+];
+
+const registryOf = (ctx: GuardrailContext) => ctx.options.permissionRegistry;
+
+const declaredResources = (ctx: GuardrailContext) =>
+  new Set(
+    (registryOf(ctx) ?? []).flatMap((f) => f.resources.map((r) => r.code)),
+  );
+
+const isApiFile = (rel: string) =>
+  (rel.startsWith("app/api/") && rel.endsWith("/route.ts")) ||
+  /^modules\/[a-z-]+\/api\//.test(rel);
+
+/** Hàm CỔNG: thứ nhận `{ resource, action }` làm KHAI BÁO quyền. */
+const DEFAULT_GATE_CALLS = [
+  "apiHandler",
+  "requirePermission",
+  "requireApiPermission",
+];
+
+const gateCallsOf = (ctx: GuardrailContext) =>
+  ctx.options.domain?.gateCalls ?? DEFAULT_GATE_CALLS;
+
+/**
+ * Đối tượng tuỳ chọn truyền vào một lời gọi cổng, trong một file.
+ *
+ * Quét trần `resource:\s*"..."` trên cả file đọc nhầm hai thứ rất phổ biến:
+ * `orderBy: { _count: { resource: "desc" } }` của Prisma (mã quyền tên `desc`),
+ * và payload nhật ký `logEntityAction({ resource: "stock-movement", action:
+ * "add-document" })` — ở đó `resource` là tên THỰC THỂ bị ghi vết, không phải
+ * mã quyền, nên đòi nó có trong registry là đòi sai. Cả năm "vi phạm" đầu tiên
+ * thước này tìm được ở vinhhoa đều thuộc hai loại đó.
+ *
+ * Nên chỉ đọc đúng chỗ khai: các đối số dạng object literal ở TẦNG NGOÀI CÙNG
+ * của lời gọi cổng. Thân handler nằm ở đối số khác (bắt đầu bằng `async`/`(`)
+ * nên mọi lời gọi lồng bên trong không lọt vào.
+ */
+function gateOptionObjects(code: string, names: string[]): string[] {
+  const call = new RegExp(
+    `\\b(?:${names.join("|")})\\s*(?:<[^>()]*>)?\\s*\\(`,
+    "g",
+  );
+  const objects: string[] = [];
+  for (const m of code.matchAll(call)) {
+    let i = (m.index ?? 0) + m[0].length;
+    let depth = 0;
+    let segment = "";
+    const take = () => {
+      if (segment.trim().startsWith("{")) objects.push(segment);
+      segment = "";
+    };
+    while (i < code.length) {
+      const ch = code[i];
+      if ("([{".includes(ch)) depth++;
+      else if (")]}".includes(ch)) {
+        if (ch === ")" && depth === 0) break; // hết lời gọi
+        depth--;
+      } else if (ch === "," && depth === 0) {
+        take();
+        i++;
+        continue;
+      }
+      segment += ch;
+      i++;
+    }
+    take();
+  }
+  return objects;
+}
+
+const literal = (obj: string, key: string) =>
+  obj.match(new RegExp(`${key}:\\s*["']([^"']+)["']`))?.[1];
+
+/**
+ * Toàn vẹn của registry quyền.
+ *
+ * Cả nhóm chống đúng một loại lỗi: **hỏng im lặng**. Khai sai quyền không làm
+ * app nổ — nó làm nút biến mất, mục menu ẩn vĩnh viễn kể cả với admin, hoặc
+ * grant chết không cấp cho ai. Không có thông báo nào, nên chỉ có phép quét
+ * tĩnh mới thấy.
+ */
+export const rbacRules: GuardrailRule[] = [
+  {
+    id: "rbac/known-actions",
+    title:
+      "mọi action được dùng đều là action chuẩn hoặc đã khai customActions",
+    why: "rbac-sync ném lỗi khi gặp action lạ — bắt ở test rẻ hơn nhiều so với phát hiện lúc deploy.",
+    fix: "Thêm action vào `customActions` của feature, hoặc dùng một trong bộ chuẩn.",
+    run(ctx) {
+      const registry = registryOf(ctx);
+      if (!registry) return null;
+      const standard = ctx.options.standardActions ?? STANDARD_ACTIONS;
+      const custom = new Set(
+        registry.flatMap((f) => (f.customActions ?? []).map((a) => a.code)),
+      );
+      const unknown: string[] = [];
+      for (const feature of registry) {
+        for (const r of feature.resources) {
+          for (const a of r.actions) {
+            if (!standard.includes(a) && !custom.has(a))
+              unknown.push(`${r.code}:${a}`);
+          }
+        }
+      }
+      return unknown;
+    },
+  },
+
+  {
+    id: "rbac/default-grants-declared",
+    title: "defaultGrants chỉ trỏ tới action đã khai trên chính resource đó",
+    why:
+      "Grant trỏ vào action không tồn tại là grant CHẾT: seed chạy xong, vai trò " +
+      "trông như có quyền, thực tế không cấp gì. Không có cảnh báo.",
+    fix: "Khai action đó trong `resources[].actions`, hoặc bỏ khỏi `defaultGrants`.",
+    run(ctx) {
+      const registry = registryOf(ctx);
+      if (!registry) return null;
+      const bad: string[] = [];
+      for (const feature of registry) {
+        for (const r of feature.resources) {
+          for (const [role, grant] of Object.entries(r.defaultGrants ?? {})) {
+            if (grant === "*") continue;
+            for (const a of grant) {
+              if (!r.actions.includes(a)) bad.push(`${role} → ${r.code}:${a}`);
+            }
+          }
+        }
+      }
+      return bad;
+    },
+  },
+
+  {
+    id: "rbac/resource-code-kebab-case",
+    title:
+      "mã resource dùng kebab-case (khớp chuỗi trong checkPermission và URL)",
+    why: "Mã lệch quy ước thì so chuỗi ở cổng trượt, mà trượt thì chỉ biểu hiện thành 403 khó truy.",
+    fix: "Đổi mã về dạng `a-b-c` (thường, số, gạch nối).",
+    run(ctx) {
+      const registry = registryOf(ctx);
+      if (!registry) return null;
+      return registry
+        .flatMap((f) => f.resources.map((r) => r.code))
+        .filter((code) => !/^[a-z][a-z0-9-]*$/.test(code));
+    },
+  },
+
+  {
+    id: "rbac/no-duplicate-resource",
+    title: "registry không khai trùng resource giữa các feature",
+    why:
+      "Hai feature cùng khai một mã thì bản nạp sau đè bản trước — action của " +
+      "bản trước biến mất khỏi seed, và diff không cho thấy gì bất thường.",
+    fix: "Gộp về một feature, hoặc đổi mã.",
+    run(ctx) {
+      const registry = registryOf(ctx);
+      if (!registry) return null;
+      const seen = new Set<string>();
+      const dup = new Set<string>();
+      for (const f of registry) {
+        for (const r of f.resources) {
+          if (seen.has(r.code)) dup.add(r.code);
+          seen.add(r.code);
+        }
+      }
+      return [...dup];
+    },
+  },
+
+  {
+    id: "rbac/nav-resource-declared",
+    title: "mọi mục navigation có `resource` đều đã khai trong registry",
+    why:
+      "Mục nav trỏ tới resource chưa khai sẽ ẨN VĨNH VIỄN với mọi người dùng, " +
+      "kể cả admin, mà không có thông báo nào — cả trang coi như biến mất.",
+    fix: "Khai resource đó trong registry, hoặc bỏ trường `resource` khỏi mục nav.",
+    run(ctx) {
+      const registry = registryOf(ctx);
+      const navs = ctx.options.navigations;
+      if (!registry || !navs) return null;
+      const declared = declaredResources(ctx);
+      const missing: string[] = [];
+      for (const group of navs) {
+        for (const item of group.items ?? []) {
+          if (item.resource && !declared.has(item.resource))
+            missing.push(item.resource);
+        }
+      }
+      return missing;
+    },
+  },
+
+  {
+    id: "rbac/gate-resource-declared",
+    title: "resource mà cổng gác đều đã khai trong registry",
+    why:
+      "Cổng khai một mã chưa có trong registry thì rbac-sync không seed mã đó → " +
+      "không vai trò nào cấp được → 403 vĩnh viễn. Runtime chỉ phát hiện khi route " +
+      "được gọi; quét tĩnh thấy cả route chưa ai đụng tới.",
+    fix: "Khai resource trong `src/configs/permissions`, rồi chạy lại `pnpm rbac-sync`.",
+    run(ctx) {
+      const registry = registryOf(ctx);
+      if (!registry) return null;
+      const declared = declaredResources(ctx);
+      const missing: string[] = [];
+      for (const file of ctx.files) {
+        const rel = ctx.rel(file);
+        if (!isApiFile(rel)) continue;
+        for (const obj of gateOptionObjects(
+          ctx.readCode(file),
+          gateCallsOf(ctx),
+        )) {
+          const code = literal(obj, "resource");
+          if (code && !declared.has(code)) missing.push(`${rel} → ${code}`);
+        }
+      }
+      return missing;
+    },
+  },
+
+  {
+    id: "rbac/gate-action-declared",
+    title: "mọi cặp (resource, action) khai ở cổng đều có trong registry",
+    why:
+      "Đây là lỗi tốn thời gian nhất của cả hệ: cổng đòi `orders:approve` mà " +
+      "registry chỉ khai `view/create/update` → nút hiện ra rồi bấm vào 403, " +
+      "hoặc UI gate ẩn nút vĩnh viễn vì `canCreate` fail-closed.",
+    fix: "Thêm action vào resource tương ứng trong registry (và `customActions` nếu ngoài bộ chuẩn).",
+    run(ctx) {
+      const registry = registryOf(ctx);
+      if (!registry) return null;
+      const byResource = new Map<string, Set<string>>();
+      for (const f of registry) {
+        for (const r of f.resources) {
+          const set = byResource.get(r.code) ?? new Set<string>();
+          r.actions.forEach((a) => set.add(a));
+          byResource.set(r.code, set);
+        }
+      }
+
+      const missing: string[] = [];
+      const gateCalls = gateCallsOf(ctx);
+      for (const file of ctx.files) {
+        const rel = ctx.rel(file);
+        for (const obj of gateOptionObjects(ctx.readCode(file), gateCalls)) {
+          const resource = literal(obj, "resource");
+          const action = literal(obj, "action");
+          if (!resource || !action) continue;
+          const actions = byResource.get(resource);
+          // Resource chưa khai đã có rule riêng lo — ở đây chỉ xét action.
+          if (actions && !actions.has(action)) {
+            missing.push(`${rel} → ${resource}:${action}`);
+          }
+        }
+      }
+      return missing;
+    },
+  },
+
+  forbidPattern({
+    id: "rbac/permissions-config-is-pure-data",
+    title: "cấu hình quyền là dữ liệu thuần — không kéo prisma/next/react vào",
+    why:
+      "`scripts/rbac-sync.ts` và test đọc thẳng các file này qua tsx, ngoài môi " +
+      "trường Next. Kéo `next/*` hay `@prisma/client` vào là seed gãy ngay lệnh đầu.",
+    fix: "Giữ `src/configs/permissions` là object literal + type; phần cần Prisma đặt ở script.",
+    pattern: /from ["'](@\/lib\/prisma|next|react|@prisma)/,
+    include: (rel) => rel.startsWith("configs/permissions"),
+  }),
+];