Chính sách phân tích kiến trúc

Với lệnh khám phá lattice analyze, thiết lập kiến trúc nằm trong .nklattice.json ở gốc đường dẫn được phân tích. Dùng Node.js 24+, pnpm 10.30.3 và chạy pnpm dlx @anhcodo13/lattice@0.5.0 init path/to/project để tạo file tối thiểu, hoặc bỏ file này để dùng mặc định. Trong phiên bản 0.5.0, governance assess dùng thiết lập kiến trúc trung tâm trong governance/policy.json; app không thể hạ gate bằng cấu hình cục bộ. Trọng số kiến trúc và ngưỡng dependency là hai trường riêng của policy đó.

Nếu Vite khai báo alias @ → ./src, thêm "aliases": { "@/": "src/" } trong assessment.architecture.analysis trung tâm hoặc khai báo tương ứng ở tsconfig.paths. Bản đánh giá đối chiếu target alias Vite tĩnh với mapping đó; target không thể xác minh cho kết quả incomplete. Mapping phải nằm trong gốc app. import() và require() có đường dẫn cố định được đưa vào đồ thị; đường dẫn tính lúc chạy không thể đánh giá và làm bằng chứng chưa đầy đủ.

Ngưỡng tích hợp

Finding xuất hiện khi giá trị quan sát lớn hơn ngưỡng.

Trường	Mặc định	Đo điều gì
maxFanIn	8	Số cạnh import runtime nội bộ đi vào một module.
maxFanOut	10	Số cạnh import runtime nội bộ đi ra một module.
maxChainDepth	6	Số bước import runtime nội bộ trong một chuỗi phụ thuộc.
maxComponentLines	200	Số dòng của file có component JSX được nhận diện.
maxJsxDepth	6	Độ sâu JSX lớn nhất trong file.
maxComplexity	15	Số nhánh và điều kiện logic ước lượng.

Có thể ghi đè riêng từng ngưỡng bằng số nguyên không âm. Bộ nhận diện component chỉ tìm function hoặc biến top-level có tên viết hoa và chứa JSX; đây là heuristic, không phải danh mục đầy đủ của React. Xem Finding để hiểu từng rule tích hợp.

Ví dụ cấu hình

Ví dụ này siết hai ngưỡng, đổi trọng số và cấm module UI import phần nội bộ server:

{
  "analysis": {
    "thresholds": {
      "maxFanOut": 8,
      "maxJsxDepth": 5
    },
    "weights": {
      "architecture": 50,
      "imports": 20,
      "components": 20,
      "complexity": 10
    }
  },
  "policies": [
    {
      "id": "ui-server-boundary",
      "description": "UI không được import phần nội bộ server",
      "from": ["src/ui/**"],
      "disallow": ["src/server/**"],
      "severity": "error",
      "recommendation": "Gọi API công khai thay vì import phần nội bộ server."
    }
  ]
}

Chạy pnpm dlx @anhcodo13/lattice@0.5.0 analyze path/to/project để áp dụng. Glob trong policy tính từ gốc được phân tích. Với ví dụ này, một import nội bộ đã resolve từ src/ui/view.ts tới src/server/secret.ts tạo finding tại dòng import. Package ngoài tập source được quét không tạo cạnh trong đồ thị nội bộ.

Cách rule ranh giới hoạt động

Mỗi policy đang bật cần ID duy nhất dạng chữ thường và dấu gạch nối, mô tả không rỗng, ít nhất một glob from, mức info, warning hoặc error, cùng đúng một lựa chọn:

• disallow: báo khi đích import khớp một glob bị cấm.
• allow: báo mọi import runtime nội bộ có đích không khớp glob nào được cho phép. Khi dùng allowlist, hãy liệt kê đủ các đích hợp lệ.

recommendation là bước xử lý hiện trong finding. Đặt "enabled": false để tắt một policy mà không xóa định nghĩa. Rule ranh giới chỉ xem import runtime nội bộ đã resolve; khai báo import type và export type không tạo finding ranh giới runtime.

Có thể thêm policy ranh giới bằng JSON. Các detector tích hợp vẫn cố định trong mã ở bản này; một mục JSON không thể định nghĩa AST rule bất kỳ.

Trọng số đổi điểm, không đổi việc phát hiện

Trọng số mặc định: architecture 40, imports 25, components 20, complexity 15. Nếu ghi đè, phải có đủ bốn giá trị số không âm và tổng đúng 100. Tăng trọng số architecture khiến finding kiến trúc trừ nhiều điểm hơn; nó không tìm thêm chu trình. Xem Cách chấm điểm để biết công thức.

JSON sai, tên ngưỡng không tồn tại, giới hạn âm, ID policy trùng hoặc trọng số sai khiến phân tích dừng với mã thoát 3. NKLattice không âm thầm bỏ qua cấu hình sai. Hãy review thay đổi policy cùng các finding bị ảnh hưởng trước khi áp dụng cho cả team.