dym-impeccable-ci-integration

Skill: dym-impeccable-ci-integration — Cắm detector vào CI của dự án bạn

Vì sao dùng: biến 61 luật tất định thành một cổng chặn, để design slop không lọt qua review. Sinh ra cái gì: một bước CI có mã thoát rõ ràng, cộng file impeccable.json làm artifact để soi lại.

Đây là ví dụ viết mới, tối giản, cho người tiêu thụ. Đừng copy .github/workflows/ci.yml của repo Impeccable: nó build và test chính Impeccable (matrix Node 22.18.0/24, Playwright, provider API key, cổng generated-output) — không liên quan gì tới việc bạn quét dự án mình.

Ba điều phải xử lý đúng trong CI

1. rc 2 nghĩa là "có phát hiện", không phải crash. Coi mọi rc != 0 là lỗi hạ tầng là hiểu sai. Rẽ nhánh tường minh: 0 xanh, 2 đỏ vì design, 1 đỏ vì quét không xong.
2. Đường dẫn sai không làm CI đỏ. Target không tồn tại chỉ in Warning: cannot access ... rồi thoát 0 (cli/engine/cli/main.mjs:326). Đổi tên thư mục là cổng lặng lẽ quét 0 file mà vẫn xanh. Phải tự kiểm tra target tồn tại.
3. Đừng gọi qua npx nếu cần tách stdout/stderr. npx gộp stderr vào stdout (đo trên npm 10.9.2). Cài dependency và gọi ./node_modules/.bin/impeccable.

Thêm: package.json khai engines.node >= 22.18.0. Node thấp hơn vẫn chạy nhưng npm cảnh báo EBADENGINE — pin runner ở 22.18 trở lên cho gọn log.

Script cổng (dùng chung cho mọi CI)

scripts/design-gate.sh:

#!/usr/bin/env bash
# Cổng design tất định. rc: 0 sạch · 1 quét không xong · 2 có finding.
set -uo pipefail

TARGET="${1:-src}"
REPORT="${2:-impeccable.json}"
BIN=./node_modules/.bin/impeccable

[ -x "$BIN" ] || { echo "::error::impeccable chưa được cài. Chạy: npm ci"; exit 1; }
[ -e "$TARGET" ] || { echo "::error::target quét không tồn tại: $TARGET"; exit 1; }

"$BIN" detect --json "$TARGET" > "$REPORT"
rc=$?

case "$rc" in
  0) echo "Design gate: sạch (0 finding chính)."; ;;
  2) echo "::error::Design gate: có finding. Xem $REPORT."
     node -e '
       const f = require("./'"$REPORT"'").filter(x => !x.advisory);
       for (const x of f) console.log(`${x.file}${x.line ? ":" + x.line : ""}  [${x.antipattern}] ${x.snippet}`);
       console.log(`\n${f.length} finding chính.`);
     '
     ;;
  1) echo "::error::Design gate: ít nhất một target không quét được (lỗi vận hành)."; ;;
  *) echo "::error::Design gate: mã thoát lạ ($rc)."; ;;
esac

exit "$rc"