@goplusvn/core 0.1.67 → 0.1.69

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";

package/src/guardrails/preset.ts

@@ -0,0 +1,75 @@
+import { authRules } from "./rules/auth";
+import { anyDebtRules } from "./rules/debt";
+import { designRules } from "./rules/design";
+import { layeringRules } from "./rules/layering";
+import { oneDoorRules } from "./rules/one-door";
+import { rbacRules } from "./rules/rbac";
+import { safetyRules } from "./rules/safety";
+import { structureRules } from "./rules/structure";
+import { createContext } from "./scanner";
+import type {
+  GuardrailOptions,
+  GuardrailResult,
+  GuardrailRule,
+} from "./types";
+
+/**
+ * Bộ hàng rào chuẩn — chưng cất từ app gốc (vinhhoa) sau nhiều đợt refactor.
+ *
+ * Chỉ giữ những rule ĐÚNG VỚI MỌI APP dựng trên core. Rule dính từ vựng nghiệp
+ * vụ (trạng thái thanh toán, một cửa repository tiền, chokepoint kho hàng) KHÔNG
+ * nằm ở đây — chúng đi qua `options.extraRules`, dựng bằng chính các primitive
+ * mà bộ này dùng.
+ */
+export function coreGuardrails(options: GuardrailOptions = {}): GuardrailRule[] {
+  return [
+    ...authRules,
+    ...rbacRules,
+    ...layeringRules,
+    ...oneDoorRules,
+    ...structureRules,
+    ...designRules,
+    ...safetyRules,
+    ...anyDebtRules,
+    ...(options.extraRules ?? []),
+  ];
+}
+
+/** `skip` nhận cả id chính xác lẫn cả nhóm (`"design/*"`). */
+export function skipReasonFor(
+  id: string,
+  skip: Record<string, string>,
+): string | undefined {
+  if (skip[id]) return skip[id];
+  const group = id.split("/")[0];
+  return skip[`${group}/*`];
+}
+
+/**
+ * Chạy toàn bộ hàng rào mà KHÔNG cần vitest — dùng cho `goerp doctor` và cho
+ * bất kỳ script CI nào muốn báo cáo thay vì ném lỗi.
+ */
+export function evaluateGuardrails(
+  options: GuardrailOptions = {},
+): GuardrailResult[] {
+  const ctx = createContext(options);
+  const skip = options.skip ?? {};
+
+  return coreGuardrails(options).map((rule): GuardrailResult => {
+    const skipReason = skipReasonFor(rule.id, skip);
+    if (skipReason) {
+      return { rule, status: "skipped", violations: [], staleAllowlist: [], skipReason };
+    }
+    const violations = rule.run(ctx);
+    if (violations === null) {
+      return { rule, status: "not-applicable", violations: [], staleAllowlist: [] };
+    }
+    const stale = rule.staleAllowlist?.(ctx) ?? [];
+    return {
+      rule,
+      status: violations.length === 0 && stale.length === 0 ? "pass" : "fail",
+      violations,
+      staleAllowlist: stale,
+    };
+  });
+}