Cổng kiểm: chặn và báo cáo

Cổng (gate) là một script tự kiểm một điều cụ thể và trả đạt hoặc không đạt. Bản lệnh đòi một danh sách gate làm nguồn duy nhất cho cả hook ở máy lẫn CI, chia thành ba nhóm.

Ba nhóm

Nhóm	Lệnh	Khi đỏ	Gồm
code (chặn)	npm run check:code	Không commit, không push, CI không deploy	Kiểu, build hỏng, seed sai, hợp đồng API, an toàn migration, luật chữ bắt buộc của chủ dự án
docs (chặn)	npm run check:docs	Như trên, khi đụng docs	Link hỏng, sidebar, trang mồ côi
report (không chặn)	npm run check:report	Chỉ báo, in trong lượt hằng tuần	Sổ sách docs, ratchet một chiều, cổng theo lịch, gói thừa. Đỏ = việc cần làm.

Luật cho gate mới: vào report, trừ khi gọi được tên thứ hỏng cho người dùng, cho deploy hay cho dữ liệu khi bỏ qua nó. Một gate sổ sách mà chặn deploy là một gate làm mọi app đứng chờ vì một dòng ngày tháng cũ.

Hai file

• scripts/run-checks-groups.mjs: nguồn duy nhất. Mỗi gate khai tên, lệnh, nhóm, và paths (regex) nếu nó chỉ liên quan một vùng file.
• scripts/run-checks.mjs: bộ chạy.

Bộ chạy

• Chạy song song (os.availableParallelism()). Vì thế mọi gate phải độc lập và chỉ đọc.
• Chỉ in đầu ra của gate đỏ; in 3 gate chậm nhất để biết chỗ cần làm nhanh.
• --staged: gate có paths chỉ chạy khi file đã stage khớp; gate không khai paths thì luôn chạy; sửa chính bộ chạy thì chạy hết.
• Gate dạng node --test chạy với env đã xoá mọi biến GIT_* (bẫy 1).

Một danh sách, không hai

Pre-commit và CI gọi đúng hai nhóm ấy. Không thêm bước gate lẻ vào workflow: một gate chỉ CI biết là gate mà máy không bao giờ chạy trước khi push, nên lần nào nó đỏ cũng là một vòng CI phí.

Gộp và dọn

• Gộp gate trùng việc.
• Gate chỉ kiểm nội dung một tính năng: chuyển thành unit test của app đó, hoặc sang report.
• Mỗi gate có test (*.test.mjs) cho cả ca đỏ lẫn ca xanh. Gate chưa từng đỏ trong test là gate chưa chứng minh được gì.
• Test của hooks cũng nằm trong nhóm code (có paths).

Ở Conan hôm nay

Conan đã có phần lớn: một danh sách ở scripts/run-guards.mjs (40 mục: 26 gác và 14 tự kiểm), chạy song song 4 luồng, chạy hết rồi mới báo, CI gọi đúng bộ chạy đó, và bộ chạy đỏ nếu có check-*.mjs chưa đăng ký. Cả bộ chạy trong 5,0 giây (13,3 giây nếu tuần tự). Tập --fast (14 gác) chạy trước khi push.

Còn thiếu: tầng report (mọi gác đều chặn), paths theo từng gác, tự kiểm cho 8 gác. Xem Audit, mục 2.