0
# CLI Tool
1

2
Command-line interface for @umijs/fabric providing git commit message validation and package information utilities.
3

4
## Capabilities
5

6
### Fabric Command
7

8
The main `fabric` command provides access to validation tools and package information.
9

10
```bash { .api }
11
# Main command structure
12
fabric [command] [options]
13

14
# Available commands:
15
fabric verify-commit    # Validate git commit messages
16
fabric --version        # Display package version and local development status
17
fabric --help          # Show help information and available commands
18
```
19

20
### Commit Message Validation
21

22
Validates git commit messages against conventional commit standards with emoji support.
23

24
```bash { .api }
25
/**
26
 * Validates git commit messages according to conventional commit format
27
 * Used in git hooks to enforce consistent commit message patterns
28
 * 
29
 * Usage: fabric verify-commit
30
 * Environment: Requires GIT_PARAMS or HUSKY_GIT_PARAMS environment variable
31
 */
32
fabric verify-commit
33
```
34

35
**Validation Rules:**
36

37
The commit message must match this pattern:
38

39
```regex
40
/^(((\ud83c[\udf00-\udfff])|(\ud83d[\udc00-\ude4f\ude80-\udeff])|[\u2600-\u2B55]) )?(revert: )?(feat|fix|docs|UI|refactor|perf|workflow|build|CI|typos|chore|tests|types|wip|release|dep|locale)(\(.+\))?: .{1,50}/
41
```
42

43
**Supported Commit Types:**
44

45
```javascript { .api }
46
/**
47
 * Valid commit types for conventional commits
48
 */
49
type CommitType = 
50
  | 'feat'      // New feature
51
  | 'fix'       // Bug fix
52
  | 'docs'      // Documentation changes
53
  | 'UI'        // User interface changes
54
  | 'refactor'  // Code refactoring
55
  | 'perf'      // Performance improvements
56
  | 'workflow'  // Workflow changes
57
  | 'build'     // Build system changes
58
  | 'CI'        // Continuous integration changes
59
  | 'typos'     // Typography fixes
60
  | 'chore'     // Maintenance tasks
61
  | 'tests'     // Test additions or modifications
62
  | 'types'     // Type definition changes
63
  | 'wip'       // Work in progress
64
  | 'release'   // Release commits
65
  | 'dep'       // Dependency updates
66
  | 'locale';   // Internationalization changes
67

68
/**
69
 * Optional commit message components
70
 */
71
interface CommitMessageFormat {
72
  /** Optional emoji prefix */
73
  emoji?: string;
74
  
75
  /** Optional revert prefix */
76
  revert?: 'revert: ';
77
  
78
  /** Required commit type */
79
  type: CommitType;
80
  
81
  /** Optional scope in parentheses */
82
  scope?: string;
83
  
84
  /** Required description (1-50 characters) */
85
  description: string;
86
}
87
```
88

89
**Valid Commit Examples:**
90

91
```bash
92
# Basic commits
93
feat: add user authentication
94
fix: resolve login validation bug
95
docs: update API documentation
96

97
# With scope
98
feat(auth): add OAuth2 integration
99
fix(ui): correct button alignment issues
100
perf(api): optimize database queries
101

102
# With emoji
103
💥 feat: add new payment system
104
🐛 fix: resolve memory leak in worker
105
📝 docs: add contribution guidelines
106

107
# With emoji and scope
108
🌷 UI(components): improve button styling
109
🏰 chore(deps): update development dependencies
110
🌐 locale(i18n): add French translations
111

112
# Revert commits
113
revert: feat: add experimental feature
114
revert: 🐛 fix: temporary workaround
115
```
116

117
### Version Information
118

119
Display package version and development status.
120

121
```bash { .api }
122
/**
123
 * Display package version information
124
 * Shows version number and local development indicator if present
125
 * 
126
 * Usage: fabric --version | fabric -v
127
 */
128
fabric --version
129
fabric -v
130
```
131

132
**Output Format:**
133

134
```text
135
4.0.1
136
@local  # Only shown if .local file exists in package directory
137
```
138

139
### Help Information
140

141
Display available commands and usage examples.
142

143
```bash { .api }
144
/**
145
 * Show help information with available commands and examples
146
 * 
147
 * Usage: fabric --help | fabric -h
148
 */
149
fabric --help
150
fabric -h
151
```
152

153
**Help Output:**
154

155
```text
156
Commands:
157
  verify-commit    检查 commit 提交的信息
158

159
Examples:
160
  fabric
161
  fabric -h
162
  verify-commit 
163
  fabric verify-commit
164
```
165

166
### System Requirements
167

168
Node.js version compatibility checking.
169

170
```javascript { .api }
171
/**
172
 * Minimum Node.js version requirement
173
 * CLI will exit with error if Node.js version is below requirement
174
 */
175
const MIN_NODE_VERSION = '>= 8.0.0';
176

177
/**
178
 * Version check performed on CLI startup
179
 * @param {string} processVersion - Current Node.js version (process.version)
180
 * @returns {boolean} True if version meets requirements
181
 */
182
function checkNodeVersion(processVersion: string): boolean;
183
```
184

185
### Environment Variables
186

187
Configuration through environment variables.
188

189
```javascript { .api }
190
/**
191
 * Git hook parameters for commit message validation
192
 * Contains path to the commit message file
193
 */
194
interface GitHookEnvironment {
195
  /** Git parameters (legacy) */
196
  GIT_PARAMS?: string;
197
  
198
  /** Husky git parameters (modern) */
199
  HUSKY_GIT_PARAMS?: string;
200
}
201
```
202

203
### Error Handling
204

205
Comprehensive error messages with internationalization support.
206

207
```javascript { .api }
208
/**
209
 * Error message localization based on system locale
210
 * Supports Chinese (zh-CN) and English (default) error messages
211
 */
212
interface ErrorMessages {
213
  /** System locale detection */
214
  locale: 'zh-CN' | 'en-US' | string;
215
  
216
  /** Localized error message for invalid commit format */
217
  invalidCommitMessage: string;
218
  
219
  /** Examples of valid commit messages */
220
  validExamples: string[];
221
  
222
  /** Reference to commit convention documentation */
223
  documentationLink: string;
224
}
225
```
226

227
**Chinese Error Messages:**
228

229
```text
230
提交日志不符合规范
231

232
合法的提交日志格式如下(emoji 和 模块可选填)：
233

234
💥 feat(模块): 添加了个很棒的功能
235
🐛 fix(模块): 修复了一些 bug
236
📝 docs(模块): 更新了一下文档
237
🌷 UI(模块): 修改了一下样式
238
🏰 chore(模块): 对脚手架做了些更改
239
🌐 locale(模块): 为国际化做了微小的贡献
240

241
其他提交类型: refactor, perf, workflow, build, CI, typos, tests, types, wip, release, dep
242
```
243

244
**English Error Messages:**
245

246
```text
247
invalid commit message format.
248

249
Proper commit message format is required for automated changelog generation. Examples:
250

251
💥 feat(compiler): add 'comments' option
252
🐛 fix(compiler): fix some bug
253
📝 docs(compiler): add some docs
254
🌷 UI(compiler): better styles
255
🏰 chore(compiler): Made some changes to the scaffolding
256
🌐 locale(compiler): Made a small contribution to internationalization
257

258
Other commit types: refactor, perf, workflow, build, CI, typos, tests, types, wip, release, dep
259
```
260

261
### Git Hook Integration
262

263
Integration with popular git hook tools.
264

265
**Husky Integration:**
266

267
```json
268
// package.json
269
{
270
  "husky": {
271
    "hooks": {
272
      "commit-msg": "fabric verify-commit"
273
    }
274
  }
275
}
276
```
277

278
**lint-staged Integration:**
279

280
```json
281
// package.json
282
{
283
  "lint-staged": {
284
    "*.{js,jsx,ts,tsx}": [
285
      "eslint --fix",
286
      "git add"
287
    ]
288
  },
289
  "husky": {
290
    "hooks": {
291
      "pre-commit": "lint-staged",
292
      "commit-msg": "fabric verify-commit"
293
    }
294
  }
295
}
296
```
297

298
**Simple git hooks Integration:**
299

300
```bash
301
#!/bin/sh
302
# .git/hooks/commit-msg
303

304
# Validate commit message format
305
fabric verify-commit
306

307
# Exit with non-zero code if validation fails
308
if [ $? -ne 0 ]; then
309
  exit 1
310
fi
311
```
312

313
### Usage Examples
314

315
**Basic Git Hook Setup:**
316

317
```bash
318
# Install the package
319
npm install @umijs/fabric --save-dev
320

321
# Add to package.json scripts
322
npm pkg set scripts.commit-lint="fabric verify-commit"
323

324
# Use with husky
325
npx husky add .husky/commit-msg "npm run commit-lint"
326
```
327

328
**Manual Validation:**
329

330
```bash
331
# Validate current commit message
332
echo "feat: add new feature" | GIT_PARAMS=/dev/stdin fabric verify-commit
333

334
# Check version
335
fabric --version
336

337
# Get help
338
fabric --help
339
```
340

341
**CI/CD Integration:**
342

343
```yaml
344
# .github/workflows/ci.yml
345
name: CI
346
on: [push, pull_request]
347

348
jobs:
349
  lint:
350
    runs-on: ubuntu-latest
351
    steps:
352
      - uses: actions/checkout@v2
353
        with:
354
          fetch-depth: 0
355
      
356
      - name: Setup Node.js
357
        uses: actions/setup-node@v2
358
        with:
359
          node-version: '16'
360
      
361
      - name: Install dependencies
362
        run: npm ci
363
      
364
      - name: Validate commit messages
365
        run: |
366
          # Validate all commit messages in PR
367
          for commit in $(git rev-list origin/main..HEAD); do
368
            git log --format=%B -n 1 $commit | GIT_PARAMS=/dev/stdin fabric verify-commit
369
          done
370
```