dym-archify-ci-diagram-gate

Skill: dym-archify-ci-diagram-gate — Chốt cổng CI cho sơ đồ trong dự án của bạn

Vì sao dùng: sơ đồ kiến trúc bị thối là vì không ai bắt buộc chúng phải đúng. Nếu nguồn JSON của sơ đồ nằm trong repo, CI có thể từ chối merge khi nguồn không còn validate được.

Kết quả nhận được: một job CI chặn PR, và (tuỳ chọn) các file HTML đã render làm artifact tải về.

Đây là ví dụ viết mới, tối thiểu. Nó không phải bản sao của .github/workflows/ci.yml trong repo Archify — file đó build và test chính Archify (ma trận Node 18/20/22/24, test trình duyệt thật, decode WebM, kiểm định danh release) và không liên quan gì tới việc bạn dùng Archify.

Bố cục repo giả định

docs/diagrams/
  runtime.architecture.json
  release.workflow.json
  checkout.sequence.json

Quy ước đặt tên <tên>.<type>.json là thứ giữ script bên dưới ngắn — loại sơ đồ suy ra từ chính tên file. Nếu bạn không theo quy ước này, hãy khai một bảng ánh xạ tường minh.

Script cổng

scripts/check-diagrams.sh:

#!/usr/bin/env bash
set -uo pipefail

A="${ARCHIFY_HOME:?đặt ARCHIFY_HOME trỏ vào thư mục skill archify}"
CLI="node $A/bin/archify.mjs"
failed=0

shopt -s nullglob
for f in docs/diagrams/*.json; do
  base="$(basename "$f" .json)"
  type="${base##*.}"
  case "$type" in
    architecture|workflow|sequence|dataflow|lifecycle) ;;
    *) echo "BỎ QUA  $f (không suy ra được loại từ tên file)"; continue ;;
  esac

  $CLI validate "$type" "$f" --quality showcase --json > "/tmp/${base}.validate.json"
  rc=$?
  case $rc in
    0) echo "OK      $f" ;;
    2) echo "LỖI GỌI $f — dòng lệnh sai, không phải lỗi nội dung sơ đồ"; failed=1 ;;
    *) echo "HỎNG    $f"; failed=1
       python3 -c "import json,sys;[print('  ',d['code'],'—',d['message']) for d in json.load(open(sys.argv[1])).get('diagnostics',[])]" \
         "/tmp/${base}.validate.json" ;;
  esac
done

exit $failed

Ba điểm cố ý:

• Phân biệt rc 2 với rc 1. 2 nghĩa là script của bạn gọi sai (loại sơ đồ lạ, cờ lạ, --repo-root sai chỗ). Gộp chung với 1 sẽ khiến bạn đi sửa sơ đồ trong khi lỗi nằm ở CI.
• Ép --quality showcase. Nếu không, một biên lai 4-check có thể trôi qua và bạn tưởng đã nghiệm thu showcase.
• In diagnostics[].code, không in stack. Mã ổn định, thông điệp thì không.