hsk-commit-conventions

Gói preset commitlint + cz-git (czg) cho team Hasaki: conventional commits, func/task, link Work — kèm lệnh commit-conventions init để gắn Husky + config vào repo của bạn trong vài phút.

Bắt đầu nhanh

# 1) Trong thư mục gốc repo app
npm add -D hsk-commit-conventions
# hoặc: yarn add -D hsk-commit-conventions

# 2) Sinh config + hooks + devDeps cần cho CLI (commitlint, husky, czg, prettier, …)
npx commit-conventions init

# 3) Commit có hướng dẫn (đã có script `commit` sau init)
npm run cz
# hoặc: yarn cz   → chạy czg

Chưa chạy init: chỉ có thư viện trong node_modules — không có Husky, không có file config cục bộ.

Bạn nhận được gì?

| Sau bước | Kết quả | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Chỉ npm add | Package + các peer (npm 7+ thường cài kèm lên root). Yarn 1 có thể chỉ cảnh báo → cần init để ghi rõ devDependencies. | | Thêm init | commitlint.config.mjs, cz-git.config.mjs, lint-staged.config.cjs, Husky (.husky/commit-msg, pre-commit), package.json có prepare, commit, config.commitizen, và đủ devDeps để npx commitlint / npx lint-staged / czg chạy từ root repo. |

CLI khi cài package:

• commit-conventions — hiện chỉ lệnh init.
• cz — proxy tới czg (tìm trong node_modules của repo bạn).

Import preset (nâng cao):

| Export | Ý nghĩa ngắn | | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- | | hsk-commit-conventions/preset | defineCommitlintConfig, defineCzGitConfig — chỉnh scope/type/task URL per repo. | | hsk-commit-conventions/commitlint / cz / lint-staged | Config mặc định đóng gói (extend/require trực tiếp). |

commit-conventions init làm gì?

1. package.json

   • prepare → npx husky (nếu đang trống hoặc husky / husky install).
   • commit → czg (nếu chưa có).
   • config.commitizen: cz-git + ./cz-git.config.mjs (dùng với Commitizen / git cz nếu có).
   • devDependencies: thêm các gói trùng peerDependencies của hsk-commit-conventions + prettier (nếu repo chưa có). Sau đó chạy pnpm install / yarn / npm install tùy lockfile.

2. File mới (chỉ khi chưa tồn tại — không ghi đè tay chỉnh của bạn)
   commitlint.config.mjs, cz-git.config.mjs, lint-staged.config.cjs.

3. Husky (luôn ghi lại hooks)

   • npx husky — Husky 9.
   • commit-msg: commitlint + kiểm tra dòng func: / task: (bash — xem templates/commit-msg.bash).
   • pre-commit: lint-staged.

Windows: hook commit-msg dùng bash — cần Git Bash / môi trường tương thích.

husky: command not found: đảm bảo có prepare: "npx husky" và đã npm install (init đã cố gắng thêm husky vào devDeps).

Tuỳ chỉnh theo repo

Luôn chỉnh đồng thời commitlint.config.mjs và cz-git.config.mjs khi đổi scopes hoặc types.

// commitlint.config.mjs
import { defineCommitlintConfig } from "hsk-commit-conventions/preset";

export default defineCommitlintConfig({
  scopes: ["api", "web"],
  subjectMaxLength: 120,
});

// cz-git.config.mjs
import { defineCzGitConfig } from "hsk-commit-conventions/preset";

export default defineCzGitConfig({
  scopes: ["api", "web"],
});

Func / task (tuỳ chọn)

• allowCustomIssuePrefix: mặc định false (chọn func trong danh sách). Đặt true để nhập func ngoài danh sách (vẫn phải khớp regex / hook).
• restrictTaskToChoices: false → task không bị ép vào taskCodeChoices; undefined → nếu có danh sách task thì vẫn kiểm tra thuộc danh sách (hành vi cũ).
• restrictFuncToChoices: true để ép func thuộc funcCodeChoices khi có danh sách.
• funcTaskCodeRe / funcCodeRe / taskCodeRe: đổi regex thì đồng bộ với .husky/commit-msg.

Đầy đủ field: JSDoc trong src/preset/index.mjs.

Biến môi trường (tuỳ chọn)

| Biến | Ý nghĩa | | ------------------------------- | -------------------------------------------------------------- | | HASAKI_WORK_TASK_URL_TEMPLATE | Template URL task, có {taskId}. | | CZ_GIT_OPEN_TASK_URL | 1 / true: có thể mở URL task sau commit (local); 0: tắt. |

Kiểm tra package khi phát triển / trước publish

Trong repo app, có thể cài local:

npm add -D file:/đường-dẫn/tới/hsk-commit-conventions

Hoặc npm pack rồi npm install ./file.tgz. Trong repo package:

npm pack --dry-run