Package Exports

@ttvuong/conventional-commit

Readme

@hemidi/conventional-commit

Gói Conventional Commit linter và interactive CLI cho các dự án JavaScript/TypeScript.

Giới thiệu

@hemidi/conventional-commit là một công cụ toàn diện để áp dụng và kiểm tra conventional commit messages trong dự án của bạn. Package này cung cấp cả chức năng linting và interactive commit builder.

Tính năng chính

Commit Linting: Kiểm tra commit messages theo quy tắc conventional commits
Interactive Mode: Xây dựng commit messages một cách tương tác
Git Hooks: Tự động validate commits với Husky integration
Multiple Presets: Hỗ trợ nhiều preset configurations
CI/CD Ready: Tích hợp dễ dàng với CI/CD pipelines
Customizable Rules: Tùy chỉnh rules theo nhu cầu dự án
Auto-initialization: Tự động setup hooks và configurations

Cài đặt

npm i -D @hemidi/conventional-commit husky commitizen

Bắt đầu nhanh

Bước 1: Khởi tạo project

npx midi-cz init

Lệnh này sẽ:

Thêm scripts vào package.json
Cài đặt git hooks với Husky
Tạo commitlint configuration file

Bước 2: Sử dụng interactive commit

npm run commit

Bước 3: Kiểm tra commits

npm run commit:check     # Kiểm tra commit cuối
npm run commit:all       # Kiểm tra tất cả commits từ development

Tham chiếu Scripts

Scripts cơ bản

Script	Mô tả	Mode	Output
`commit`	Interactive commit builder	interactive	Git commit
`commit:check`	Kiểm tra commit message cuối	check	Console output
`commit:all`	Kiểm tra tất cả commits từ development	check	Console output

Scripts được tạo tự động

Khi chạy npx midi-cz init, các scripts sau sẽ được thêm vào package.json:

{
  "scripts": {
    "commit": "midi-cz interactive",
    "commit:check": "midi-cz --check",
    "commit:all": "midi-cz --from origin/development --to HEAD",
    "prepare": "husky install"
  }
}

Options tham số

Tùy chọn Mode

Option	Mô tả	Default	Mục đích
`--check`	Check commit messages	true	Validation mode
`--interactive`	Interactive commit builder	false	Create commits
`--hook`	Run as git hook	false	Git integration
`--init`	Initialize project	false	Setup project

Tùy chọn Configuration

Option	Mô tả	Default	Format
`--config <path>`	Path to config file	Auto-discover	Path
`--preset <name>`	Use specific preset	@commitlint/config-conventional	String
`--extends <configs>`	Extend configurations	-	Array

Tùy chọn Validation

Option	Mô tả	Default	Ví dụ
`--from <commit>`	Start commit for range	-	`--from ooigin/development`
`--to <commit>`	End commit for range	HEAD	`--to HEAD`
`--edit`	Read from COMMIT_EDITMSG	false	`--edit`

Tùy chọn Output

Option	Mô tả	Default	Formats
`--format <format>`	Output format	stylish	stylish, json, compact
`--verbose`	Verbose output	false	`--verbose`
`--quiet`	Suppress output	false (true in CI)	`--quiet`

Tùy chọn Utility

Option	Mô tả	Mục đích
`--help`	Show help message	Documentation

Hướng dẫn sử dụng theo tình huống

Development hàng ngày

# Tạo commit với interactive mode
npm run commit

# Kiểm tra commit vừa tạo
npm run commit:check

# Kiểm tra nhiều commits
npx midi-cz --from origin/development --to HEAD

Before push

# Kiểm tra tất cả commits local
npm run commit:all

CI/CD Pipeline

# CI mode với JSON output
npx midi-cz --check --format json --quiet

# Kiểm tra PR commits
npx midi-cz --from origin/development --to HEAD

Custom validation

# Sử dụng custom config
npx midi-cz --config ./custom-commitlint.config.js

# Kiểm tra với specific preset
npx midi-cz --preset @company/commitlint-config

Conventional Commit Format

Cấu trúc cơ bản

<type>(<scope>): <subject>

<body>

<footer>

Types được hỗ trợ

Type	Mô tả	Ví dụ
`feat`	Tính năng mới	feat: add user authentication
`fix`	Sửa lỗi	fix: resolve login issue
`docs`	Thay đổi documentation	docs: update API guide
`style`	Code style (không ảnh hưởng logic)	style: format code
`refactor`	Refactor code	refactor: improve performance
`perf`	Cải thiện performance	perf: optimize query
`test`	Thêm/sửa tests	test: add unit tests
`build`	Build system changes	build: update webpack config
`ci`	CI/CD changes	ci: add GitHub Actions
`chore`	Maintenance tasks	chore: update dependencies
`revert`	Revert commit	revert: revert commit abc123

Ví dụ commit messages

Simple commit

feat: add user profile page

With scope

fix(auth): resolve token expiration issue

With body

feat(api): implement pagination for users endpoint

Add limit and offset parameters to GET /users
Default limit is 20, maximum is 100

Breaking change

feat!: update API response format

BREAKING CHANGE: API responses now use camelCase instead of snake_case

fix(ui): correct button alignment in header

The submit button was misaligned on mobile devices
due to incorrect flexbox properties.

Fixes #123
Closes #456

Configuration

commitlint.config.js

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // Custom rules
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'perf',
        'test',
        'build',
        'ci',
        'chore',
        'revert',
      ],
    ],
    'subject-case': [2, 'never', ['upper-case', 'pascal-case']],
    'subject-full-stop': [2, 'never', '.'],
    'subject-max-length': [2, 'always', 100],
    'header-max-length': [2, 'always', 100],
    'body-leading-blank': [2, 'always'],
    'body-max-line-length': [2, 'always', 100],
    'footer-leading-blank': [2, 'always'],
  },
};

Package.json configuration

{
  "commitlint": {
    "extends": ["@commitlint/config-conventional"],
    "rules": {
      "type-enum": [2, "always", ["feat", "fix", "docs"]]
    }
  },
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  }
}

Validation Rules

Header Rules

Rule	Description	Default
`type-empty`	Type không được để trống	error
`type-enum`	Type phải trong danh sách cho phép	error
`subject-empty`	Subject không được để trống	error
`subject-case`	Case của subject	lower-case
`subject-full-stop`	Subject không kết thúc bằng dấu chấm	error
`subject-max-length`	Độ dài tối đa của subject	100
`header-max-length`	Độ dài tối đa của header	100

Body Rules

Rule	Description	Default
`body-leading-blank`	Body phải có dòng trống phía trước	warning
`body-max-line-length`	Độ dài tối đa mỗi dòng trong body	100

Rule	Description	Default
`footer-leading-blank`	Footer phải có dòng trống phía trước	warning

Git Hooks Integration

Husky setup

Package tự động tạo git hooks với Husky:

.husky/
  commit-msg    # Validate commit messages

Manual hook setup

Nếu không dùng Husky, có thể setup manual:

npx --no -- midi-cz hook "$1"

Ví dụ Output

Check mode - Success

$ npm run commit:check

[midi-cz] Checking commit messages...
✅ feat: add user authentication

Check mode - Failed

$ npm run commit:check

[midi-cz] Checking commit messages...
❌ Add new feature
   Type is required (e.g., feat, fix, docs)
   Subject must be in lower-case

JSON format output

[
  {
    "message": "feat: add login feature",
    "valid": true,
    "errors": [],
    "warnings": []
  },
  {
    "message": "WIP: working on dashboard",
    "valid": false,
    "errors": [
      "Type must be one of: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert"
    ],
    "warnings": []
  }
]

Troubleshooting

Common Issues

Husky hooks not working

# Re-install husky
npm run prepare

# Verify hook exists
ls -la .husky/commit-msg

Commitizen not found

# Install commitizen and adapter
npm i -D commitizen cz-conventional-changelog

Custom config not loading

# Verify config path
npx midi-cz --config ./path/to/config.js --verbose

Quy trình đóng gói

B1: Vào thư mục conventional-commit, cài đặt dependencies và kiểm tra authentication với npm registry

cd packages/ci/conventional-commit && npm install
npm whoami
# Nếu chưa đăng nhập, chạy lệnh:
npm login

B2: Cần thay đổi các thông tin cần thiết trong file package.json nếu cần

{
  "name": "@hemidi/conventional-commit", // <- Thay đổi tên package nếu cần
  "version": "1.0.0", // <- Thay đổi version
  "description": "Conventional commit..." // <- Thay đổi mô tả
}

B3: Quản lý version của package

# example
npm version patch # 1.0.1
npm version minor # 1.1.0
npm version major # 2.0.0

B4: Build package

npm run build

B5: Đóng gói và publish

# Đóng gói package public
npm publish --access public

# Đóng gói package private
npm publish --access restricted

@ttvuong/conventional-commit