@goplusvn/core 0.1.67 → 0.1.70

package/src/guardrails/primitives.ts

@@ -0,0 +1,307 @@
+import { join } from "node:path";
+
+import type { GuardrailContext, GuardrailRule } from "./types";
+
+/** Bỏ cờ `g` để `.test()` không bị con trỏ `lastIndex` làm cho lúc đúng lúc sai. */
+const stateless = (re: RegExp) =>
+  new RegExp(re.source, re.flags.replace(/[gy]/g, ""));
+
+/** Nợ cũ của rule: app truyền vào, mặc định lấy `defaults` của chính rule. */
+export function allowlistFor(
+  ctx: GuardrailContext,
+  ruleId: string,
+  defaults: string[] = [],
+): Set<string> {
+  return new Set(ctx.options.allowlists[ruleId] ?? defaults);
+}
+
+/**
+ * Một entry allowlist là FILE, hoặc THƯ MỤC nếu kết thúc bằng `/`.
+ *
+ * Có loại miễn trừ mà danh sách file không diễn đạt nổi: `_handlers/` của một
+ * dispatcher khai resource bằng BIẾN, nên mọi handler trong đó vi phạm vì đúng
+ * một lý do, và số file thì tăng mỗi lần thêm hành động. Liệt kê từng file ở đó
+ * chỉ đẻ ra một danh sách phải sửa cho xanh — mà danh sách sửa-cho-xanh thì
+ * không còn là ratchet. Miễn trừ theo thư mục nêu đúng một lý do, một lần.
+ */
+export const allowlistCovers = (allowed: Set<string>, rel: string): boolean =>
+  allowed.has(rel) ||
+  [...allowed].some((entry) => entry.endsWith("/") && rel.startsWith(entry));
+
+interface ForbidPatternSpec {
+  id: string;
+  title: string;
+  why: string;
+  fix: string;
+  /** Mẫu bị cấm, soi trên bản đã bỏ chú thích. */
+  pattern: RegExp;
+  /** Chỉ soi file thoả điều kiện này (đường dẫn tương đối `src`). */
+  include?: (rel: string) => boolean;
+  /**
+   * Điều kiện GHÉP trên nội dung, xét TRƯỚC `pattern` — ví dụ "chỉ soi file
+   * mang chỉ thị `use server`". Cùng dùng cho phép kiểm allowlist ôi, nên một
+   * entry hết là server action cũng bị coi là hết lý do tồn tại.
+   */
+  when?: (code: string, rel: string) => boolean;
+  /** Nợ cũ mặc định của app gốc; app khác đè bằng `options.allowlists[id]`. */
+  defaultAllowlist?: string[];
+  /** Rule chỉ chạy khi hàm này đúng — dùng để tự bỏ qua app không có thứ đó. */
+  applies?: (ctx: GuardrailContext) => boolean;
+  /** Đọc bản thô thay vì bản đã bỏ chú thích (hiếm — chỉ khi soi chính chú thích). */
+  raw?: boolean;
+}
+
+/**
+ * Rule "không được xuất hiện mẫu X", kèm allowlist chỉ-được-rút-bớt.
+ *
+ * Đây là khuôn của phần lớn hàng rào: một mẫu code đã từng gây sự cố, cộng một
+ * danh sách file được miễn vì lý do chính đáng. Phần allowlist mới là chỗ dễ
+ * mục: người ta thêm tên vào cho test xanh rồi quên. Nên mỗi rule kiểu này tự
+ * sinh thêm phép kiểm "entry nào hết lý do thì phải gỡ".
+ */
+export function forbidPattern(spec: ForbidPatternSpec): GuardrailRule {
+  const test = stateless(spec.pattern);
+  const source = (ctx: GuardrailContext, file: string) =>
+    spec.raw ? ctx.read(file) : ctx.readCode(file);
+
+  return {
+    id: spec.id,
+    title: spec.title,
+    why: spec.why,
+    fix: spec.fix,
+    run(ctx) {
+      if (spec.applies && !spec.applies(ctx)) return null;
+      const allowed = allowlistFor(ctx, spec.id, spec.defaultAllowlist);
+      const offenders: string[] = [];
+      for (const file of ctx.files) {
+        const rel = ctx.rel(file);
+        if (spec.include && !spec.include(rel)) continue;
+        if (allowlistCovers(allowed, rel)) continue;
+        const code = source(ctx, file);
+        if (spec.when && !spec.when(code, rel)) continue;
+        if (test.test(code)) offenders.push(rel);
+      }
+      return offenders;
+    },
+    staleAllowlist(ctx) {
+      if (spec.applies && !spec.applies(ctx)) return [];
+      const allowed = allowlistFor(ctx, spec.id, spec.defaultAllowlist);
+      const violates = (rel: string, file: string) => {
+        const code = source(ctx, file);
+        if (spec.when && !spec.when(code, rel)) return false;
+        return test.test(code);
+      };
+      return [...allowed].filter((entry) => {
+        // Entry thư mục hết hạn khi KHÔNG còn file nào dưới nó vi phạm.
+        if (entry.endsWith("/")) {
+          return !ctx.files.some(
+            (f) => ctx.rel(f).startsWith(entry) && violates(ctx.rel(f), f),
+          );
+        }
+        if (!ctx.existsInSrc(entry)) return true;
+        return !violates(entry, join(ctx.srcDir, entry));
+      });
+    },
+  };
+}
+
+interface SingleDoorSpec {
+  id: string;
+  title: string;
+  why: string;
+  fix: string;
+  /** Import bị coi là "đi cửa sau" nếu khớp mẫu này. */
+  pattern: RegExp;
+  /** Các file hạ tầng ĐƯỢC phép đi thẳng (tương đối `src`). */
+  doors: (ctx: GuardrailContext) => string[];
+  /**
+   * Cửa chính phải chứa mẫu này (thường là lời gọi `configureX`). Cửa duy nhất
+   * mà quên cấu hình singleton thì "một cửa" chỉ còn là hình thức: mọi lời gọi
+   * vẫn đúng đường mà chạy thật vẫn nổ.
+   */
+  mustConfigure?: RegExp;
+  /** Tên gọi để in ra khi thiếu cấu hình — mặc định lấy phần chữ đầu của mẫu. */
+  mustConfigureName?: string;
+  /**
+   * Chỉ đòi cấu hình khi app THẬT SỰ dùng phần cần cấu hình.
+   *
+   * Ví dụ: extension branch-guard (lớp 2) chạy được mà không cần
+   * `configureBranchScope`; chỉ lớp 1 (`scopedBranchWhere`) mới cần. Đòi vô
+   * điều kiện là bắt app nhỏ khai một thứ nó không dùng — và thước nào bắt người
+   * ta khai thừa thì sớm muộn cũng bị tắt cả cụm.
+   */
+  mustConfigureWhen?: (ctx: GuardrailContext) => boolean;
+}
+
+/**
+ * Rule "engine singleton chỉ được vào qua đúng một cửa".
+ *
+ * Bẫy có thật: engine kho tập tin / phạm vi chi nhánh của core là singleton cần
+ * `configureX()` 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 — code chạy tới lúc thật mới nổ, và 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.
+ */
+export function singleDoorImport(spec: SingleDoorSpec): GuardrailRule {
+  const test = stateless(spec.pattern);
+  return {
+    id: spec.id,
+    title: spec.title,
+    why: spec.why,
+    fix: spec.fix,
+    run(ctx) {
+      const doors = spec.doors(ctx);
+      // Không app nào có cửa nào → app này chưa dùng engine đó.
+      if (!doors.some((d) => ctx.existsInSrc(d))) return null;
+
+      const offenders: string[] = [];
+      for (const file of ctx.files) {
+        const rel = ctx.rel(file);
+        if (doors.includes(rel)) continue;
+        if (test.test(ctx.readCode(file))) offenders.push(rel);
+      }
+
+      if (spec.mustConfigure && (spec.mustConfigureWhen?.(ctx) ?? true)) {
+        const main = doors.find((d) => ctx.existsInSrc(d));
+        if (
+          main &&
+          !stateless(spec.mustConfigure).test(ctx.readCodeRel(main))
+        ) {
+          const name =
+            spec.mustConfigureName ??
+            /[A-Za-z][A-Za-z0-9]*/.exec(spec.mustConfigure.source)?.[0];
+          offenders.push(`${main} — cửa duy nhất nhưng KHÔNG gọi ${name}()`);
+        }
+      }
+      return offenders;
+    },
+  };
+}
+
+interface CeilingSpec {
+  id: string;
+  title: string;
+  why: string;
+  fix: string;
+  /** Mẫu được ĐẾM (bắt buộc có cờ `g`). */
+  pattern: RegExp;
+  /** Trần mặc định theo thư mục cấp 1; app đè bằng `options.ceilings[id]`. */
+  defaultCeilings?: Record<string, number>;
+}
+
+/**
+ * Ratchet đếm theo thư mục: chỉ được giảm.
+ *
+ * Dùng cho nợ kỹ thuật đông người (`any`, literal mã trạng thái) — cấm tuyệt
+ * đối thì không ai migrate nổi, thả lỏng thì nợ lặng lẽ phình. Trần = hiện
+ * trạng. Có HAI phép kiểm, và phép thứ hai mới là phép giữ cho rule sống: trần
+ * dư = chỗ trống cho nợ mới lọt vào mà test vẫn xanh.
+ */
+export function perDirectoryCeiling(spec: CeilingSpec): GuardrailRule[] {
+  const count = (ctx: GuardrailContext) => {
+    const counts: Record<string, number> = {};
+    for (const file of ctx.files) {
+      const top = ctx.rel(file).split("/")[0];
+      const re = new RegExp(spec.pattern.source, spec.pattern.flags);
+      counts[top] =
+        (counts[top] ?? 0) + (ctx.readCode(file).match(re) ?? []).length;
+    }
+    return counts;
+  };
+  const ceilings = (ctx: GuardrailContext) =>
+    ctx.options.ceilings[spec.id] ?? spec.defaultCeilings ?? {};
+
+  return [
+    {
+      id: spec.id,
+      title: spec.title,
+      why: spec.why,
+      fix: spec.fix,
+      run(ctx) {
+        const counts = count(ctx);
+        const caps = ceilings(ctx);
+        return Object.entries(counts)
+          .filter(([dir, n]) => n > (caps[dir] ?? 0))
+          .map(([dir, n]) => `${dir}: ${n} > trần ${caps[dir] ?? 0}`);
+      },
+    },
+    {
+      id: `${spec.id}-no-slack`,
+      title: `${spec.title} — trần không được dư`,
+      why:
+        "Trần dư là chỗ trống cho nợ mới lọt vào mà ratchet vẫn xanh: trả nợ " +
+        "xong mà không hạ trần thì lần sau thêm nợ ngang phần đã trả, không ai hay.",
+      fix: "Sửa trần xuống đúng số hiện tại trong CÙNG commit — đó là bản ghi nhìn thấy được của tiến độ.",
+      run(ctx) {
+        const counts = count(ctx);
+        return Object.entries(ceilings(ctx))
+          .filter(([dir, cap]) => (counts[dir] ?? 0) < cap)
+          .map(
+            ([dir, cap]) => `${dir}: trần ${cap} → thực tế ${counts[dir] ?? 0}`,
+          );
+      },
+    },
+  ];
+}
+
+interface FileContractSpec {
+  id: string;
+  title: string;
+  why: string;
+  fix: string;
+  /** Đường dẫn tương đối `src`. */
+  file: string;
+  /** File phải tồn tại. Bỏ qua rule nếu `false` và file vắng mặt. */
+  required?: boolean;
+  /** File phải chứa các mẫu này. */
+  mustMatch?: RegExp[];
+  /** File KHÔNG được chứa các mẫu này. */
+  mustNotMatch?: RegExp[];
+}
+
+/** Rule "một file hạ tầng phải giữ đúng hợp đồng của nó". */
+export function fileContract(spec: FileContractSpec): GuardrailRule {
+  return {
+    id: spec.id,
+    title: spec.title,
+    why: spec.why,
+    fix: spec.fix,
+    run(ctx) {
+      if (!ctx.existsInSrc(spec.file)) {
+        return spec.required ? [`thiếu file ${spec.file}`] : null;
+      }
+      const code = ctx.readRel(spec.file);
+      const problems: string[] = [];
+      for (const re of spec.mustMatch ?? []) {
+        if (!stateless(re).test(code)) {
+          problems.push(`${spec.file} — thiếu \`${re.source}\``);
+        }
+      }
+      for (const re of spec.mustNotMatch ?? []) {
+        if (stateless(re).test(code)) {
+          problems.push(`${spec.file} — còn \`${re.source}\``);
+        }
+      }
+      return problems;
+    },
+  };
+}
+
+/** Rule "file/thư mục này phải KHÔNG tồn tại" (di sản đã dọn, cấm mọc lại). */
+export function forbidFile(spec: {
+  id: string;
+  title: string;
+  why: string;
+  fix: string;
+  /** Đường dẫn tương đối gốc app. */
+  paths: string[];
+}): GuardrailRule {
+  return {
+    id: spec.id,
+    title: spec.title,
+    why: spec.why,
+    fix: spec.fix,
+    run(ctx) {
+      return spec.paths.filter((p) => ctx.existsInRoot(p));
+    },
+  };
+}

package/src/guardrails/rules/auth.ts

@@ -0,0 +1,178 @@
+import { fileContract, forbidPattern } from "../primitives";
+import type { GuardrailContext, GuardrailRule } from "../types";
+
+const isApiRoute = (rel: string) =>
+  rel.startsWith("app/api/") && rel.endsWith("/route.ts");
+
+/** Handler đã có cổng: bọc apiHandler, factory core, hoặc tự lấy phiên. */
+const GATED = /apiHandler[<(]|create\w*Handlers\(|getSession/;
+
+/**
+ * Nơi cổng THẬT SỰ nằm, cho một file route.
+ *
+ * App đã module hoá thì `app/api/**\/route.ts` chỉ là stub `export * from
+ * "@/modules/<domain>/api/..."` — Next cần một file ở đó để mount URL, còn
+ * handler (và cổng của nó) sống trong module. Đọc mỗi stub rồi kết luận
+ * "không gác" là báo động giả cho toàn bộ app: đúng 212 route của vinhhoa.
+ */
+/**
+ * URL của một file route: `app/api/x/[id]/route.ts` → `/api/x/[id]`.
+ * Route group `(...)` không xuất hiện trong URL nên bị bỏ.
+ */
+const routeUrl = (rel: string) =>
+  "/" +
+  rel
+    .replace(/^app\//, "")
+    .replace(/\/route\.ts$/, "")
+    .split("/")
+    .filter((seg) => !/^\(.*\)$/.test(seg))
+    .join("/");
+
+/**
+ * Tiền tố API tự-xác-thực, đọc thẳng từ `proxy.ts`.
+ *
+ * Không hard-code trong core: mỗi app có bề mặt công khai riêng (webhook, mini
+ * app, link theo token). Điều core ép là bề mặt đó phải được KHAI Ở MỘT CHỖ —
+ * chính chỗ cổng mặc-định-chặn đọc — chứ không phải suy ra từ việc route quên gác.
+ */
+function publicPrefixes(ctx: GuardrailContext): string[] {
+  if (!ctx.existsInSrc("proxy.ts")) return [];
+  return [...ctx.readCodeRel("proxy.ts").matchAll(/["'](\/api\/[^"']*)["']/g)].map(
+    (m) => m[1].replace(/\/$/, ""),
+  );
+}
+
+function gateSources(ctx: GuardrailContext, code: string): string[] {
+  const targets = [...code.matchAll(/export \* from ["']@\/([^"']+)["']/g)].map(
+    (m) => m[1],
+  );
+  if (targets.length === 0) return [code];
+  return targets.map((spec) => {
+    const candidate = [`${spec}.ts`, `${spec}/index.ts`, `${spec}/route.ts`].find(
+      (p) => ctx.existsInSrc(p),
+    );
+    // Không lần ra đích thì xét chính stub — thà báo thừa còn hơn bỏ lọt.
+    return candidate ? ctx.readCodeRel(candidate) : code;
+  });
+}
+
+/**
+ * Cổng xác thực & phân quyền.
+ *
+ * Cả nhóm bảo vệ đúng một tài sản: **không bề mặt gọi được nào thoát khỏi
+ * cổng**. Ba bề mặt đó là proxy (middleware của Next 16), route API, và server
+ * action. Mỗi lỗ ở đây đều từng là lỗ hổng thật, không phải giả định.
+ */
+export const authRules: GuardrailRule[] = [
+  {
+    id: "auth/proxy-default-deny",
+    title: "proxy.ts có cổng mặc-định-chặn cho bề mặt /api",
+    why:
+      "Trước khi có cổng mặc-định-chặn, mỗi route API tự lo phần xác thực của " +
+      "mình — chỉ cần một route quên là thủng, và không có gì báo.",
+    fix: "Dùng `createAuthProxy({ publicApiPrefixes })` (@goerp/core/auth/proxy-gate), hoặc tự dựng nhánh `pathname.startsWith('/api')` + `getSessionCookie` + danh sách trắng công khai.",
+    run(ctx) {
+      if (!ctx.existsInSrc("proxy.ts")) return ["thiếu src/proxy.ts — không có cổng nào cả"];
+      const code = ctx.readCodeRel("proxy.ts");
+      // Hai lối dựng đều hợp lệ: factory của core, hoặc bản tự dựng của app.
+      // Ràng cứng vào một lối là bắt app phải giống hệt vinhhoa về CÁCH VIẾT,
+      // trong khi thứ cần ràng là TÍNH CHẤT: /api chặn trước, công khai phải khai.
+      const viaCore = /createAuthProxy\s*\(/.test(code) && /publicApiPrefixes/.test(code);
+      const handRolled =
+        /getSessionCookie/.test(code) &&
+        /pathname\.startsWith\(["']\/api["']\)/.test(code) &&
+        /isPublicApiPath|PUBLIC_API_PREFIXES/.test(code);
+      return viaCore || handRolled
+        ? []
+        : ["proxy.ts — không thấy cổng /api mặc-định-chặn nào (createAuthProxy hoặc bản tự dựng)"];
+    },
+  },
+
+  {
+    id: "auth/proxy-matcher-covers-api",
+    title: "matcher của proxy không loại trừ /api (để cổng thật sự chạy)",
+    why:
+      "Cấu hình mặc định của Next loại /api khỏi matcher bằng `(?!api|...)`. " +
+      "Để nguyên thì cổng mặc-định-chặn nằm đó mà không bao giờ được gọi — " +
+      "đọc code thì tưởng đã an toàn.",
+    fix: "Bỏ `(?!api` khỏi `config.matcher` trong src/proxy.ts.",
+    run(ctx) {
+      if (!ctx.existsInSrc("proxy.ts")) return null;
+      const matcher =
+        ctx.readRel("proxy.ts").match(/matcher:\s*\[([\s\S]*?)\]/)?.[1] ?? "";
+      return /\(\?!api\b/.test(matcher)
+        ? ["proxy.ts — matcher còn loại trừ /api"]
+        : [];
+    },
+  },
+
+  {
+    id: "auth/no-stray-middleware",
+    title: "không có middleware.ts lạc (Next 16 dùng proxy.ts)",
+    why: "Có cả hai file thì build gãy, và người sửa dễ vá nhầm vào file không chạy.",
+    fix: "Xoá src/middleware.ts, giữ src/proxy.ts.",
+    run(ctx) {
+      return ctx.existsInSrc("middleware.ts") ? ["src/middleware.ts"] : [];
+    },
+  },
+
+  {
+    id: "auth/api-route-gated",
+    title: "route API hoặc đi qua cổng, hoặc được KHAI là công khai trong proxy.ts",
+    why:
+      "Route quên gác là lỗ hổng im lặng: nó trả dữ liệu đúng, test chức năng " +
+      "vẫn xanh, chỉ có điều ai gọi cũng được. Thước này không cấm route công " +
+      "khai — nó cấm route công khai KHÔNG AI BIẾT: muốn mở thì phải ghi tiền " +
+      "tố vào danh sách công khai của proxy.ts, nơi người review nhìn thấy.",
+    fix: "Bọc `apiHandler(fn, { resource, action })`, hoặc nếu route thật sự công khai thì thêm tiền tố vào danh sách công khai trong src/proxy.ts (kèm ghi rõ nó tự xác thực bằng gì).",
+    run(ctx) {
+      const routes = ctx.files.filter((f) => isApiRoute(ctx.rel(f)));
+      if (routes.length === 0) return null;
+      const publics = publicPrefixes(ctx);
+      const allowed = new Set(ctx.options.allowlists["auth/api-route-gated"] ?? []);
+      return routes
+        .map(ctx.rel)
+        .filter((rel) => {
+          if (allowed.has(rel)) return false;
+          const url = routeUrl(rel);
+          if (publics.some((p) => url === p || url.startsWith(`${p}/`))) return false;
+          // Chưa gác = KHÔNG nguồn cổng nào (stub trỏ tới) có dấu hiệu gác.
+          return !gateSources(ctx, ctx.readCodeRel(rel)).some((src) => GATED.test(src));
+        });
+    },
+    staleAllowlist(ctx) {
+      const publics = publicPrefixes(ctx);
+      return (ctx.options.allowlists["auth/api-route-gated"] ?? []).filter((rel) => {
+        if (!ctx.existsInSrc(rel)) return true;
+        const url = routeUrl(rel);
+        if (publics.some((p) => url === p || url.startsWith(`${p}/`))) return true;
+        return gateSources(ctx, ctx.readCodeRel(rel)).some((src) => GATED.test(src));
+      });
+    },
+  },
+
+  forbidPattern({
+    id: "auth/server-action-bare-session",
+    title: "file 'use server' không gọi getSession trần — dùng requirePermission",
+    why:
+      "Server action là API surface thật: mọi client đã đăng nhập đều gọi được, " +
+      "nhưng nó KHÔNG đi qua apiHandler. `getSession()` trần chỉ trả lời 'anh là " +
+      "ai', không trả lời 'anh được làm gì' — đúng kiểu lỗ print-actions từng hở.",
+    fix: "Gọi `requirePermission(resource, action)` ở đầu mỗi action (guard action của app).",
+    pattern: /\bgetSession\s*\(/,
+    when: (code) => /^\s*["']use server["']/.test(code),
+  }),
+
+  forbidPattern({
+    id: "auth/api-inline-check-permission",
+    title: "tầng API không checkPermission inline — khai quyền ở cổng",
+    why:
+      "Quyền khai rải trong thân handler thì không cách nào liệt kê tĩnh 'route " +
+      "này cần quyền gì', nên registry và thực tế trôi khỏi nhau; rbac-sync seed " +
+      "thiếu quyền mà không ai biết.",
+    fix: "Khai `{ resource, action }` ở `apiHandler(...)` — cổng khai báo, quét được.",
+    pattern: /\bcheckPermission\s*\(/,
+    include: (rel) =>
+      rel.startsWith("app/api/") || /^modules\/[a-z-]+\/api\//.test(rel),
+  }),
+];

package/src/guardrails/rules/debt.ts

@@ -0,0 +1,71 @@
+import { perDirectoryCeiling } from "../primitives";
+import type { GuardrailRule } from "../types";
+
+/**
+ * Bắt cả ba lối viết `any`: chú thích kiểu (`: any`), ép kiểu (`as any`), và
+ * tham số generic (`Record<string, any>`, `Promise<any>`, `any[]` trong ngoặc
+ * nhọn). Bản chỉ bắt hai lối đầu từng bỏ sót hơn trăm điểm nợ, trong đó có
+ * nguyên một thư mục ai cũng tưởng đã sạch.
+ */
+const ANY_PATTERN = /:\s*any\b|\bas any\b|<[^<>\n]*\bany\b[^<>\n]*>/g;
+
+/**
+ * Ratchet nợ `any`.
+ *
+ * App mới bắt đầu ở trần rỗng — nghĩa là 0 ở mọi thư mục, và mọi `any` mới đều
+ * đỏ ngay. App đã có lịch sử thì khai trần bằng hiện trạng rồi hạ dần.
+ */
+export const anyDebtRules: GuardrailRule[] = perDirectoryCeiling({
+  id: "debt/any",
+  title: "số `any` mỗi thư mục không vượt trần",
+  why:
+    "`any` tắt kiểm tra kiểu ở đúng chỗ nó cần nhất và lan theo giá trị trả về. " +
+    "Cấm tuyệt đối thì không migrate nổi app cũ, thả lỏng thì nợ phình lặng lẽ — " +
+    "nên khoá bằng trần, chỉ được giảm.",
+  fix: "Type cho đúng, hoặc dùng `unknown` + thu hẹp. Trả nợ chỗ nào thì hạ trần chỗ đó.",
+  pattern: ANY_PATTERN,
+});
+
+export interface StatusLiteralSpec {
+  /** Tên các cột trạng thái, ví dụ `["status", "paymentStatus"]`. */
+  fields: string[];
+  /** Từ vựng mã trạng thái, ví dụ `["pending", "paid", "cancelled"]`. */
+  values: string[];
+  /** Trần mặc định theo thư mục cấp 1. */
+  ceilings?: Record<string, number>;
+}
+
+/**
+ * Ratchet literal mã trạng thái — nhà máy, vì từ vựng là của từng app.
+ *
+ * Mã trạng thái là CODE: nó nằm trong guard nghiệp vụ (`paymentStatus !== "paid"`
+ * chặn một thao tác), không phải nhãn hiển thị. Rải chuỗi thô khắp nơi đẻ ra từ
+ * vựng ma — một app thật đã sống nhiều tháng với `misa_status === "exported"`
+ * trong khi cột đó chưa bao giờ có giá trị `exported`, và một bộ lọc khai
+ * `"partial"` nên luôn trả rỗng. Cả hai im lặng vì chuỗi thô thì compiler không
+ * có gì để đối chiếu.
+ *
+ * Thước bắt ba lối viết: so sánh (`=== "x"`), khai giá trị (`: "x"`), và gán
+ * (`status = "x"`). Vế gán bắt buộc có khoảng trắng hai bên `=` — prettier viết
+ * gán JS như vậy, còn prop JSX thì `status="pending"` dính liền, nhờ đó
+ * `<StatusIndicator status="pending" />` (trình bày thuần) không bị tính mà
+ * không cần allowlist theo file.
+ */
+export function statusLiteralCeiling(spec: StatusLiteralSpec): GuardrailRule[] {
+  const pattern = new RegExp(
+    `\\b(?:${spec.fields.join("|")})(?:\\s*(?:===|!==|:)\\s*|\\s+=\\s+)"(?:${spec.values.join("|")})"`,
+    "g",
+  );
+  return perDirectoryCeiling({
+    id: "debt/status-literal",
+    title: "literal mã trạng thái mỗi thư mục không vượt trần",
+    why:
+      "Từ vựng ma: mã không tồn tại vẫn biên dịch, guard nghiệp vụ so sai thì " +
+      "không báo lỗi mà chỉ lặng lẽ trả rỗng hoặc cho qua.",
+    fix:
+      "Dùng hằng số từ nguồn trạng thái của app (`src/lib/status`). Nếu là state " +
+      "bước UI cục bộ thì đổi tên field thành `phase`/`step` — thước sẽ không đụng tới.",
+    pattern,
+    defaultCeilings: spec.ceilings,
+  });
+}

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