@goplusvn/core 0.1.66 → 0.1.69

package/src/auth/index.ts

@@ -1,25 +1,30 @@
 // @goerp/core/auth
 // Authentication and RBAC utilities for GoERP
 
-import type { Session } from "../types";
+import type { Permission, PermissionMap, Session } from "../types";
 
 export * from "./auth-service";
 
+// `Permission` từng được KHAI BÁO LẠI ở đây, y hệt bản trong ../types — hai
+// nguồn sự thật cho cùng một shape. Giờ chỉ còn re-export.
+export type { Permission, PermissionMap };
+
 // ============================================================================
 // Types
 // ============================================================================
 
-export interface Permission {
-  resourceCode: string;
-  actionCode: string;
-}
-
 export interface ExtendedUser {
   id: string;
   name?: string | null;
   email?: string | null;
   image?: string | null;
   roles?: string[];
+  /**
+   * Dạng GỌN, nên dùng: resource → các action. Xem `PermissionMap`.
+   * Có `permissionMap` thì `permissions` bị BỎ QUA hoàn toàn.
+   */
+  permissionMap?: PermissionMap;
+  /** Dạng cũ. Vẫn chạy nguyên vẹn, chỉ tốn ~4,5 lần payload. */
   permissions?: Permission[];
 }
 
@@ -72,17 +77,105 @@ export function getActionCode(action: string): string {
 // Permission Functions
 // ============================================================================
 
+// ============================================================================
+// Permission Map — chuyển đổi + tra cứu
+// ============================================================================
+
+/** `Permission[]` → dạng gọn. Tự gộp trùng. */
+export function toPermissionMap(permissions: Permission[]): PermissionMap {
+  const map: PermissionMap = {};
+  for (const p of permissions) {
+    const actions = (map[p.resourceCode] ??= []);
+    if (!actions.includes(p.actionCode)) actions.push(p.actionCode);
+  }
+  return map;
+}
+
+/** Dạng gọn → `Permission[]`. Chỉ dùng ở ranh giới với code chưa chuyển. */
+export function fromPermissionMap(map: PermissionMap): Permission[] {
+  const out: Permission[] = [];
+  for (const resourceCode of Object.keys(map)) {
+    for (const actionCode of map[resourceCode]) {
+      out.push({ resourceCode, actionCode });
+    }
+  }
+  return out;
+}
+
+/**
+ * Nhớ bản đã chuyển đổi theo CHÍNH mảng `permissions` của session cũ.
+ *
+ * Không có nó, mỗi lần `checkPermission` của app chưa chuyển sẽ dựng lại map
+ * từ đầu — một trang gọi 20 lần là 20 lần dựng, tệ hơn hẳn phép quét tuyến
+ * tính có thoát sớm mà nó thay thế. WeakMap khoá theo tham chiếu mảng nên
+ * session hết hạn là bản nhớ tự rụng, không cần dọn.
+ */
+const legacyMapCache = new WeakMap<Permission[], PermissionMap>();
+
+/**
+ * Đọc quyền của session về dạng gọn, bất kể app gán kiểu nào.
+ * Trả `undefined` khi session không có user (khác hẳn "user không có quyền
+ * nào", vốn là `{}`) để chỗ gọi tự quyết cách xử lý.
+ */
+function readPermissionMap(session: Session | null): PermissionMap | undefined {
+  if (!session?.user) return undefined;
+  const user = session.user as ExtendedUser;
+  if (user.permissionMap) return user.permissionMap;
+  if (!user.permissions) return {};
+
+  let cached = legacyMapCache.get(user.permissions);
+  if (!cached) {
+    cached = toPermissionMap(user.permissions);
+    legacyMapCache.set(user.permissions, cached);
+  }
+  return cached;
+}
+
+function isAdminUser(user: ExtendedUser): boolean {
+  return Boolean(
+    user.roles?.includes(ADMIN_ROLE_CODE) || user.roles?.includes("SUPER_ADMIN"),
+  );
+}
+
+/**
+ * Các resource user chạm được — dùng để lọc menu và App Launcher.
+ *
+ * `actionCode` bỏ trống = "có BẤT KỲ action nào" (thấy tile là vào được trang);
+ * truyền `"view"` = đúng nghĩa xem được. Admin trả `Set(["*"])`, khớp quy ước
+ * wildcard mà cây điều hướng đang dùng.
+ *
+ * Có sẵn ở core vì mọi app đều tự viết lại đúng vòng lặp này, mỗi nơi một kiểu.
+ */
+export function getAccessibleResources(
+  session: Session | null,
+  actionCode?: string,
+): Set<string> {
+  if (!session?.user) return new Set();
+  if (isAdminUser(session.user as ExtendedUser)) return new Set(["*"]);
+
+  const map = readPermissionMap(session) ?? {};
+  const out = new Set<string>();
+  for (const resourceCode of Object.keys(map)) {
+    if (!actionCode || map[resourceCode].includes(actionCode)) {
+      out.add(resourceCode);
+    }
+  }
+  return out;
+}
+
 /**
  * Get all permissions from session
+ *
+ * Trả về dạng CŨ (`Permission[]`) nên phải bung map ra — mỗi lần gọi là một
+ * lần dựng lại vài nghìn object. Cần lọc theo resource thì dùng
+ * `getAccessibleResources`; cần kiểm một quyền thì dùng `checkPermission`.
  */
 export function getUserPermissions(session: Session | null): Permission[] {
   if (!session?.user) return [];
   const user = session.user as ExtendedUser;
 
-  if (!user.permissions) {
-    return [];
-  }
-  return user.permissions;
+  if (user.permissionMap) return fromPermissionMap(user.permissionMap);
+  return user.permissions ?? [];
 }
 
 /**
@@ -135,10 +228,7 @@ export function getCrudPermissionsFromSession(
   }
 
   // Check admin role first (fastest check)
-  const isAdmin =
-    user.roles?.includes(ADMIN_ROLE_CODE) ||
-    user.roles?.includes("SUPER_ADMIN");
-  if (isAdmin) {
+  if (isAdminUser(user)) {
     return {
       create: true,
       view: true,
@@ -151,16 +241,12 @@ export function getCrudPermissionsFromSession(
     };
   }
 
-  // Pre-compute permission keys for fast lookup
-  const permissions = user.permissions || [];
-  const permissionKeys = new Set(
-    permissions.map((p) => `${p.resourceCode}:${p.actionCode}`),
-  );
+  // Chỉ lấy danh sách action CỦA RIÊNG entity này. Bản cũ dựng một Set
+  // "resource:action" cho TOÀN BỘ quyền của user (vài nghìn chuỗi) rồi hỏi
+  // đúng 8 lần — dựng lại ở mỗi lần gọi hàm.
+  const actions = readPermissionMap(session)?.[entity] ?? [];
 
-  const hasPermission = (action: string) => {
-    const key = `${entity}:${action}`;
-    return permissionKeys.has(key);
-  };
+  const hasPermission = (action: string) => actions.includes(action);
 
   return {
     create: hasPermission(getActionCode("create")),
@@ -191,20 +277,13 @@ export function checkPermission(
 
   // Admin role bypass — checked BEFORE the empty-permissions guard so an admin
   // who relies on their role (no explicit permission rows) is not locked out.
-  if (
-    user.roles?.includes(ADMIN_ROLE_CODE) ||
-    user.roles?.includes("SUPER_ADMIN")
-  ) {
+  if (isAdminUser(user)) {
     return true;
   }
 
-  if (!user.permissions || user.permissions.length === 0) {
-    return false;
-  }
-
-  return user.permissions.some(
-    (p) => p.resourceCode === resourceCode && p.actionCode === actionCode,
-  );
+  // Tra thẳng theo resource rồi quét danh sách action của riêng nó (vài chục
+  // phần tử), thay vì quét tuyến tính CẢ mảng quyền như bản `Permission[]`.
+  return readPermissionMap(session)?.[resourceCode]?.includes(actionCode) ?? false;
 }
 
 /**

package/src/guardrails/__tests__/guardrails.test.ts

@@ -0,0 +1,430 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { afterAll, describe, expect, it } from "vitest";
+
+import { evaluateGuardrails } from "../preset";
+import { createContext, stripComments } from "../scanner";
+import { forbidPattern, perDirectoryCeiling } from "../primitives";
+import type { GuardrailOptions, GuardrailResult } from "../types";
+
+/**
+ * Test của chính bộ hàng rào.
+ *
+ * Guardrail sai còn tệ hơn không có: nó bật đèn xanh cho đúng thứ nó được lập
+ * ra để chặn. Nên mỗi rule ở đây được kiểm bằng một app giả có vi phạm THẬT,
+ * chứ không chỉ kiểm "chạy không nổ".
+ */
+
+const roots: string[] = [];
+
+/** Dựng một app giả trong thư mục tạm: `{ "lib/prisma.ts": "..." }`. */
+function fixture(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), "goerp-guardrails-"));
+  roots.push(root);
+  for (const [rel, content] of Object.entries(files)) {
+    const full = join(root, rel.startsWith("src/") ? rel : `src/${rel}`);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return root;
+}
+
+/** Đặt file ở GỐC app (không phải trong src) — .dockerignore, tailwind.config… */
+function atRoot(root: string, rel: string, content: string) {
+  const full = join(root, rel);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, content);
+}
+
+const resultOf = (results: GuardrailResult[], id: string) =>
+  results.find((r) => r.rule.id === id)!;
+
+const run = (root: string, options: GuardrailOptions = {}) =>
+  evaluateGuardrails({ root, ...options });
+
+afterAll(() => {
+  for (const root of roots) rmSync(root, { recursive: true, force: true });
+});
+
+describe("scanner", () => {
+  it("bỏ chú thích nhưng giữ nguyên URL trong chuỗi", () => {
+    const code = stripComments(
+      [
+        'const a = "http://x.test"',
+        "// window.open(export)",
+        "/* as any */",
+      ].join("\n"),
+    );
+    expect(code).toContain("http://x.test");
+    expect(code).not.toContain("window.open");
+    expect(code).not.toContain("as any");
+  });
+
+  it("callBodies cắt đúng thân lời gọi trải nhiều dòng", () => {
+    const bodies = createContext({ root: fixture({}) }).callBodies(
+      "await db.$transaction(async (tx) => {\n  await fn(1)\n})\nother()",
+      "$transaction(",
+    );
+    expect(bodies).toHaveLength(1);
+    expect(bodies[0]).toContain("await fn(1)");
+    expect(bodies[0]).not.toContain("other()");
+  });
+
+  it("không quét file test và thư mục build", () => {
+    const ctx = createContext({
+      root: fixture({
+        "lib/a.ts": "export const a = 1",
+        "lib/a.test.ts": "const x: any = 1",
+        ".next/b.ts": "const y: any = 2",
+      }),
+    });
+    expect(ctx.files.map(ctx.rel)).toEqual(["lib/a.ts"]);
+  });
+});
+
+describe("rule bắt được vi phạm thật", () => {
+  it("one-door/single-prisma-client — client thứ hai bị bắt, cửa chính thì không", () => {
+    const root = fixture({
+      "lib/prisma.ts": "export const db = new PrismaClient()",
+      "server/report.ts": "const other = new PrismaClient()",
+    });
+    expect(
+      resultOf(run(root), "one-door/single-prisma-client").violations,
+    ).toEqual(["server/report.ts"]);
+  });
+
+  it("one-door/storage — chỉ cửa được import core, và cửa phải cấu hình", () => {
+    const leaky = fixture({
+      "lib/storage.ts":
+        'import { configureStorage } from "@goerp/core/storage"\nconfigureStorage({ bucket: "x" })',
+      "app/api/upload/route.ts":
+        'import { putObject } from "@goerp/core/storage"\nexport const POST = apiHandler(fn)',
+    });
+    expect(resultOf(run(leaky), "one-door/storage").violations).toEqual([
+      "app/api/upload/route.ts",
+    ]);
+
+    const unconfigured = fixture({
+      "lib/storage.ts": 'export { putObject } from "@goerp/core/storage"',
+    });
+    expect(
+      resultOf(run(unconfigured), "one-door/storage").violations.join(),
+    ).toContain("KHÔNG gọi configureStorage()");
+  });
+
+  it("one-door/storage — app chưa có cửa nào thì rule tự bỏ qua", () => {
+    const root = fixture({ "lib/a.ts": "export const a = 1" });
+    expect(resultOf(run(root), "one-door/storage").status).toBe(
+      "not-applicable",
+    );
+  });
+
+  it("auth/api-route-gated — không gác thì phải được KHAI công khai ở proxy.ts", () => {
+    const root = fixture({
+      "proxy.ts":
+        'createAuthProxy({ publicApiPrefixes: ["/api/better-auth", "/api/zma"] })',
+      "app/api/orders/route.ts":
+        "export async function GET() { return Response.json([]) }",
+      "app/api/roles/route.ts":
+        "export const GET = apiHandler(fn, { resource: 'roles' })",
+      // Khai công khai (self-auth) → không đòi cổng phiên.
+      "app/api/better-auth/[...all]/route.ts": "export const GET = handler",
+      "app/api/zma/orders/route.ts":
+        "export async function GET() { return Response.json([]) }",
+    });
+    expect(resultOf(run(root), "auth/api-route-gated").violations).toEqual([
+      "app/api/orders/route.ts",
+    ]);
+  });
+
+  it("auth/api-route-gated — stub app/api được lần tới handler thật trong module", () => {
+    const root = fixture({
+      "app/api/orders/route.ts": 'export * from "@/modules/sales/api/orders"',
+      "modules/sales/api/orders.ts":
+        "export const GET = apiHandler(fn, { resource: 'orders', action: 'view' })",
+    });
+    expect(resultOf(run(root), "auth/api-route-gated").violations).toEqual([]);
+  });
+
+  it("auth/server-action-bare-session — chỉ bắt file 'use server'", () => {
+    const root = fixture({
+      "actions/orders.ts": '"use server"\nconst s = await getSession()',
+      "lib/read.ts": "const s = await getSession()",
+    });
+    expect(
+      resultOf(run(root), "auth/server-action-bare-session").violations,
+    ).toEqual(["actions/orders.ts"]);
+  });
+
+  it("auth/proxy-matcher-covers-api — matcher loại trừ /api thì đỏ", () => {
+    const bad = fixture({
+      "proxy.ts": "export const config = { matcher: ['/((?!api|_next).*)'] }",
+    });
+    expect(
+      resultOf(run(bad), "auth/proxy-matcher-covers-api").violations,
+    ).toHaveLength(1);
+  });
+
+  it("layering/domain-framework-free — domain dính next/* thì đỏ, modules/*/api thì không", () => {
+    const root = fixture({
+      "modules/sales/services/order-service.ts":
+        'import { revalidatePath } from "next/cache"',
+      "modules/sales/api/orders.ts":
+        'import { NextResponse } from "next/server"',
+    });
+    expect(
+      resultOf(run(root), "layering/domain-framework-free").violations.join(),
+    ).toContain("modules/sales/services/order-service.ts");
+    expect(
+      resultOf(run(root), "layering/domain-framework-free").violations.join(),
+    ).not.toContain("modules/sales/api/orders.ts");
+  });
+
+  it("layering/module-public-api — deep-import bị bắt, server action thì được miễn", () => {
+    const root = fixture({
+      "modules/sales/index.ts": "export {}",
+      "modules/sales/services/x.ts": "export const x = 1",
+      "modules/sales/actions/save.ts":
+        '"use server"\nexport async function save() {}',
+      "app/page.tsx": 'import { x } from "@/modules/sales/services/x"',
+      "app/form.tsx": 'import { save } from "@/modules/sales/actions/save"',
+    });
+    const v = resultOf(run(root), "layering/module-public-api").violations;
+    expect(v.join()).toContain("app/page.tsx");
+    expect(v.join()).not.toContain("app/form.tsx");
+  });
+
+  it("design/no-fragile-flex-hidden — `flex lg:hidden` đỏ, `hidden max-lg:flex` xanh", () => {
+    const root = fixture({
+      "app/bad.tsx": '<div className="flex items-center lg:hidden" />',
+      "app/good.tsx": '<div className="hidden items-center max-lg:flex" />',
+    });
+    const v = resultOf(run(root), "design/no-fragile-flex-hidden").violations;
+    expect(v.join()).toContain("app/bad.tsx");
+    expect(v.join()).not.toContain("app/good.tsx");
+  });
+
+  it("safety/no-network-in-transaction — chỉ bắt lời gọi NẰM TRONG thân transaction", () => {
+    const root = fixture({
+      "modules/a/inside.ts":
+        "await db.$transaction(async (tx) => {\n await fetch(url)\n})",
+      "modules/a/outside.ts":
+        "await fetch(url)\nawait db.$transaction(async (tx) => {})",
+    });
+    expect(
+      resultOf(run(root), "safety/no-network-in-transaction").violations,
+    ).toEqual(["modules/a/inside.ts"]);
+  });
+
+  it("structure/dockerignore-keeps-source — glob nuốt mã nguồn thì đỏ", () => {
+    const root = fixture({
+      "modules/sales/api/check-resold.ts": "export const GET = apiHandler(fn)",
+      "app/page.tsx": "export default function Page() {}",
+    });
+    atRoot(root, ".dockerignore", "node_modules\n**/check-*.ts\n");
+    expect(
+      resultOf(run(root), "structure/dockerignore-keeps-source").violations,
+    ).toEqual(["src/modules/sales/api/check-resold.ts"]);
+  });
+
+  it("rbac/gate-action-declared — cổng đòi action registry chưa khai thì đỏ", () => {
+    const root = fixture({
+      "app/api/orders/route.ts":
+        "export const POST = apiHandler(fn, { resource: 'orders', action: 'approve' })",
+    });
+    const results = run(root, {
+      permissionRegistry: [
+        { resources: [{ code: "orders", actions: ["view", "create"] }] },
+      ],
+    });
+    expect(resultOf(results, "rbac/gate-action-declared").violations).toEqual([
+      "app/api/orders/route.ts → orders:approve",
+    ]);
+  });
+
+  it("rbac/gate-* chỉ đọc đối tượng khai ở CỔNG, không đọc payload nhật ký", () => {
+    const root = fixture({
+      // Ba thứ cùng mang key `resource` trong một file, chỉ MỘT là khai quyền:
+      // sắp xếp của Prisma, payload ghi vết thực thể, và cổng thật.
+      "app/api/orders/route.ts": [
+        "export const GET = apiHandler(async (req) => {",
+        "  await db.auditLog.groupBy({ by: ['resource'], orderBy: { _count: { resource: 'desc' } } })",
+        "  await logEntityAction({ resource: 'stock-movement', action: 'add-document' })",
+        "  return NextResponse.json({})",
+        "}, { resource: 'orders', action: 'view' })",
+      ].join("\n"),
+    });
+    const results = run(root, {
+      permissionRegistry: [
+        { resources: [{ code: "orders", actions: ["view"] }] },
+      ],
+    });
+    expect(resultOf(results, "rbac/gate-resource-declared").violations).toEqual(
+      [],
+    );
+    expect(resultOf(results, "rbac/gate-action-declared").violations).toEqual(
+      [],
+    );
+  });
+
+  it("rbac/gate-resource-declared — cổng khai resource ngoài registry thì đỏ", () => {
+    const root = fixture({
+      "app/api/orders/route.ts":
+        "export const GET = apiHandler(fn, { resource: 'ghost', action: 'view' })",
+    });
+    const results = run(root, {
+      permissionRegistry: [
+        { resources: [{ code: "orders", actions: ["view"] }] },
+      ],
+    });
+    expect(resultOf(results, "rbac/gate-resource-declared").violations).toEqual(
+      ["app/api/orders/route.ts → ghost"],
+    );
+  });
+
+  it("rbac/nav-resource-declared — mục menu trỏ resource chưa khai thì đỏ", () => {
+    const results = run(fixture({ "lib/a.ts": "export const a = 1" }), {
+      permissionRegistry: [
+        { resources: [{ code: "orders", actions: ["view"] }] },
+      ],
+      navigations: [{ items: [{ resource: "orders" }, { resource: "ghost" }] }],
+    });
+    expect(resultOf(results, "rbac/nav-resource-declared").violations).toEqual([
+      "ghost",
+    ]);
+  });
+
+  it("rbac/* tự bỏ qua khi app không truyền registry", () => {
+    const results = run(fixture({ "lib/a.ts": "export const a = 1" }));
+    expect(resultOf(results, "rbac/known-actions").status).toBe(
+      "not-applicable",
+    );
+  });
+});
+
+describe("ratchet: allowlist chỉ được rút bớt", () => {
+  const spec = {
+    id: "test/forbid",
+    title: "t",
+    why: "w",
+    fix: "f",
+    pattern: /forbidden/,
+  };
+
+  it("allowlist che được vi phạm đã biết", () => {
+    const ctx = createContext({
+      root: fixture({ "a.ts": "forbidden", "b.ts": "forbidden" }),
+      allowlists: { "test/forbid": ["a.ts"] },
+    });
+    expect(forbidPattern(spec).run(ctx)).toEqual(["b.ts"]);
+  });
+
+  it("entry hết vi phạm (hoặc file đã xoá) bị báo là ôi", () => {
+    const ctx = createContext({
+      root: fixture({ "a.ts": "clean" }),
+      allowlists: { "test/forbid": ["a.ts", "deleted.ts"] },
+    });
+    expect(forbidPattern(spec).staleAllowlist!(ctx).sort()).toEqual([
+      "a.ts",
+      "deleted.ts",
+    ]);
+  });
+
+  it("entry kết thúc bằng `/` miễn trừ cả thư mục", () => {
+    const ctx = createContext({
+      root: fixture({ "_handlers/a.ts": "forbidden", "b.ts": "forbidden" }),
+      allowlists: { "test/forbid": ["_handlers/"] },
+    });
+    expect(forbidPattern(spec).run(ctx)).toEqual(["b.ts"]);
+  });
+
+  it("entry thư mục hết vi phạm cũng bị báo là ôi", () => {
+    const ctx = createContext({
+      root: fixture({ "_handlers/a.ts": "sạch" }),
+      allowlists: { "test/forbid": ["_handlers/"] },
+    });
+    expect(forbidPattern(spec).staleAllowlist!(ctx)).toEqual(["_handlers/"]);
+  });
+});
+
+describe("ratchet: trần theo thư mục", () => {
+  const [over, slack] = perDirectoryCeiling({
+    id: "test/any",
+    title: "t",
+    why: "w",
+    fix: "f",
+    pattern: /\bas any\b/g,
+  });
+
+  it("app mới không khai trần = trần 0 ở mọi thư mục", () => {
+    const ctx = createContext({ root: fixture({ "lib/a.ts": "x as any" }) });
+    expect(over.run(ctx)).toEqual(["lib: 1 > trần 0"]);
+  });
+
+  it("trần đúng hiện trạng thì xanh cả hai chiều", () => {
+    const ctx = createContext({
+      root: fixture({ "lib/a.ts": "x as any" }),
+      ceilings: { "test/any": { lib: 1 } },
+    });
+    expect(over.run(ctx)).toEqual([]);
+    expect(slack.run(ctx)).toEqual([]);
+  });
+
+  it("trần dư cũng đỏ — trả nợ tới đâu hạ trần tới đó", () => {
+    const ctx = createContext({
+      root: fixture({ "lib/a.ts": "sạch" }),
+      ceilings: { "test/any": { lib: 5 } },
+    });
+    expect(slack.run(ctx)).toEqual(["lib: trần 5 → thực tế 0"]);
+  });
+});
+
+describe("van an toàn `skip`", () => {
+  it("skip theo id và theo cả nhóm đều có tác dụng", () => {
+    const root = fixture({ "server/x.ts": "new PrismaClient()" });
+    expect(
+      resultOf(
+        run(root, { skip: { "one-door/single-prisma-client": "nợ cũ" } }),
+        "one-door/single-prisma-client",
+      ).status,
+    ).toBe("skipped");
+    expect(
+      resultOf(
+        run(root, { skip: { "one-door/*": "nợ cũ" } }),
+        "one-door/single-prisma-client",
+      ).status,
+    ).toBe("skipped");
+  });
+});
+
+describe("app sạch", () => {
+  it("một app tối thiểu, đúng chuẩn thì không rule nào đỏ", () => {
+    const root = fixture({
+      "proxy.ts": [
+        'import { getSessionCookie } from "better-auth/cookies"',
+        'if (pathname.startsWith("/api") && !isPublicApiPath(pathname)) return deny()',
+        "export const config = { matcher: ['/((?!_next).*)'] }",
+      ].join("\n"),
+      "lib/prisma.ts": "export const db = new PrismaClient()",
+      "app/globals.css": '@import "@goerp/core/styles/base.css";',
+      "app/api/roles/route.ts":
+        "export const GET = apiHandler(fn, { resource: 'roles', action: 'view' })",
+      "app/[lang]/(main)/roles/page.tsx":
+        "export default function Page() { return null }",
+      "app/[lang]/(main)/roles/roles-client-page.tsx":
+        "export function C() { return null }",
+    });
+    // globals.css không phải .ts nên fixture ghi thẳng; rule đọc bằng đường dẫn.
+    const failed = run(root, {
+      permissionRegistry: [
+        { resources: [{ code: "roles", actions: ["view"] }] },
+      ],
+      navigations: [{ items: [{ resource: "roles" }] }],
+    }).filter((r) => r.status === "fail");
+    expect(
+      failed.map((r) => `${r.rule.id}: ${r.violations.join(", ")}`),
+    ).toEqual([]);
+  });
+});

package/src/guardrails/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Hàng rào kiến trúc dùng chung — luật đi theo core, dữ liệu ở lại app.
+ *
+ * Mỗi rule ở đây là một **ca lỗi có thật** đã tốn thời gian ở app gốc, viết lại
+ * thành phép quét tĩnh. Ba lý do để chúng sống trong core thay vì trong từng app:
+ *
+ * 1. **Luật lan được.** Bài học rút ra hôm nay tới mọi app ở lần `pnpm up` sau,
+ *    thay vì đóng băng trong bản chép tay của ngày app được scaffold.
+ * 2. **Thông báo lỗi mới là chỗ người ta đọc.** Rule mang theo `why` — nguyên
+ *    văn sự cố — nên khi test đỏ, người/agent sửa hiểu vì sao chứ không đi tìm
+ *    cách làm cho nó xanh.
+ * 3. **Van an toàn hiện hình.** `skip` bắt buộc kèm lý do và tự đỏ khi nợ đã
+ *    trả, nên bump core không làm gãy app đang chạy mà cũng không đẻ ra chỗ trốn.
+ *
+ * Dùng trong `src/__tests__/architecture.test.ts` của app:
+ *
+ * ```ts
+ * import { runCoreGuardrails } from "@goerp/core/guardrails"
+ * import { permissionRegistry } from "@/configs/permissions"
+ * import { navigations } from "@/data/navigations"
+ *
+ * runCoreGuardrails({ permissionRegistry, navigations })
+ * ```
+ */
+
+export { runCoreGuardrails } from "./run";
+export { coreGuardrails, evaluateGuardrails, skipReasonFor } from "./preset";
+export { createContext, callBodies, stripComments, resolveOptions } from "./scanner";
+export {
+  allowlistFor,
+  fileContract,
+  forbidFile,
+  forbidPattern,
+  perDirectoryCeiling,
+  singleDoorImport,
+} from "./primitives";
+export { anyDebtRules, statusLiteralCeiling } from "./rules/debt";
+export type { StatusLiteralSpec } from "./rules/debt";
+export { STANDARD_ACTIONS } from "./rules/rbac";
+export { authRules } from "./rules/auth";
+export { rbacRules } from "./rules/rbac";
+export { layeringRules } from "./rules/layering";
+export { oneDoorRules } from "./rules/one-door";
+export { structureRules } from "./rules/structure";
+export { designRules } from "./rules/design";
+export { safetyRules } from "./rules/safety";
+export { NOT_APPLICABLE } from "./types";
+export type {
+  GuardrailContext,
+  GuardrailGroup,
+  GuardrailOptions,
+  GuardrailResult,
+  GuardrailRule,
+  NavigationGroupLike,
+  PermissionFeatureLike,
+  ResolvedGuardrailOptions,
+} from "./types";