🧩 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.

👉【查阅中文文档请点击这里】

---

🚀 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

# 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:

comment-check

---

⚙️ Usage

🔹 Default mode (recommended)

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

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:

#!/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

---