code-comment-check/README.md

A fast, SWC-powered CLI for enforcing comment standards on variable declarations before commits.

# 🧩 code-comment-check

> 🧠 A lightweight, fast CLI tool that checks whether your variable declarations are properly commented before committing code.
> Ensure code readability and consistency across your team with one simple command.

[👉【查阅中文文档请点击这里】](https://github.com/laoer536/code-comment-check/blob/main/README.zh.md)

---

## 🚀 Why use code-comment-check?

Modern projects often enforce strict code style rules — yet **comment standards** are easy to overlook.
`code-comment-check` solves exactly that problem:

* ✅ Automatically detects missing comments for each variable declaration
* ✅ Prevents committing code with missing comments
* ✅ By default, only checks **changed lines** in the current commit — fast and efficient
* ✅ Supports a `--strict` mode to inspect all declarations in changed files
* 🚫 Ignores test files by default (`__tests__`, `.test.ts`, `.spec.tsx`, etc.)

Use it in your local workflow or CI pipeline to enforce consistent documentation standards across your team.

---

## 📦 Installation

```bash
# Recommended
pnpm add -D code-comment-check

# Or using npm / yarn
npm install -D code-comment-check
# or
yarn add -D code-comment-check
```

After installation, the CLI command is automatically registered:

```bash
comment-check
```

---

## ⚙️ Usage

### 🔹 Default mode (recommended)

```bash
pnpm comment-check
```

Default behavior:

* Only checks **changed lines** in the committed files
* Automatically **ignores test files**
* Displays missing comment entries in a formatted table (file, line, declaration)
* Returns a non-zero exit code if issues are found, blocking the commit

---

### 🔹 Strict mode

```bash
pnpm comment-check --strict
```

In strict mode, the tool scans all declarations in changed files,
making it ideal for **code review** or **CI environments**.

---

## 🪝 Integrating with Husky (pre-commit hook)

In your `.husky/pre-commit` file, add the following:

```bash
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

pnpm comment-check
```

Effect:

* ✅ If all checks pass — the commit proceeds
* ❌ If any declaration lacks a comment — a table of missing comments is printed, and the commit is blocked

---

## 💡 Example Output

```
🔍 Checking annotation comments...

⚠️  Missing annotation comments:

┌────────────────────────────────────────┬────────┬────────────────────────────────────────────────────────────┐
│ File                                   │ Line   │ Declaration                                                │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 1      │ const test = '123'                                         │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 2      │ let test1 = '123'                                          │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 3      │ var test2 = '123'                                          │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 4      │ export const test3 = '123'                                 │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 5      │ export let test4 = '123'                                   │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 6      │ export var test5 = '123'                                   │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 8      │ interface Type {                                           │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 12     │ type UserType = 'admin' | 'user'                           │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 14     │ export interface User {                                    │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 20     │ export type UserWithType = User & {                        │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 24     │ const bb = '123'                                           │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 25     │ const cc = '123'                                           │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 26     │ const dd = '123'                                           │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 28     │ function fn() {                                            │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 32     │ class Test {                                               │
├────────────────────────────────────────┼────────┼────────────────────────────────────────────────────────────┤
│ test/test2.ts                          │ 38     │ enum TestEnum {                                            │
└────────────────────────────────────────┴────────┴────────────────────────────────────────────────────────────┘

❌ Please add comments before committing your code.
```

---

## 🌟 Features & Advantages

| Feature               | Description                                           |
| --------------------- |-------------------------------------------------------|
| ⚡️ High performance   | Built on the SWC compiler — much faster than Babel    |
| 🧩 Zero configuration | Works out of the box, automatically registers the CLI |
| 💬 Clear output       | Displays missing comment details in a table           |
| 🧠 Smart parsing      | Supports Javascript / TypeScript / JSX / TSX syntax   |
| 🪶 Lightweight        | Non-intrusive — analyzes AST without modifying code   |
| 🔧 Extensible         | Supports the `--strict` flag for broader checks       |

---

## 📘 Use Cases

* Enforcing code documentation standards
* Pre-commit comment validation
* Automated CI code inspection
* Integration in internal dev tools or monorepo setups

---

## 📄 License

MIT © 2025 — maintained by [laoer536](https://github.com/laoer536)

---