@youngemmy/comment-cleaner

v1.1.4

Published

7 days ago

A CLI tool to scan your codebase for commented-out code, preview findings, and generate a Markdown report

0High
0Medium
0Low

youngemmy

cli comments cleanup codebase dry-run report refactoring code-quality

🧹 comment-cleaner

A zero-dependency CLI that scans your codebase for commented-out code, previews findings, auto-fixes them, watches in real time, and exports reports in Markdown, JSON, or HTML.

✨ Features

🔍 Preview mode — see all commented-out code blocks with file path and line numbers
🔧 Fix mode — automatically remove all detected commented-out code with one command
🎛️ Interactive mode — step through each block and choose delete, keep, or skip
🧪 Dry-run mode — preview exactly what --fix would remove before committing
👀 Watch mode — monitor your project in real time and alert on new commented-out code as you type
📈 Stats mode — view your scan history and trend over time
🚦 Threshold mode — fail CI automatically if too many blocks are found
📁 Output dir — save all reports (HTML, JSON, MD) to one folder in a single command
🌐 HTML report — beautiful dark-themed visual report you can open in any browser
📊 Markdown report — clean report, perfect for code reviews
📦 JSON output — machine-readable output for CI pipelines and editor integrations
🏷️ Severity levels — every block ranked 🔴 High · 🟡 Medium · 🟢 Low
🔒 @keep annotation — permanently exclude any comment from detection
⚙️ Config file — save your settings per project in .commentcleanerrc
🤖 GitHub Action — run automatically on every pull request
🧠 Smart detection — only flags actual dead code, ignores explanatory comments and TODOs
🌍 13 languages — JS, TS, Python, Go, Java, Rust, Ruby, PHP, C/C++, Swift, CSS, and more
⚡ Zero dependencies — pure Node.js

📦 Installation

npm install -g @youngemmy/comment-cleaner

Or run with npx (no install needed):

npx @youngemmy/comment-cleaner ./src

📦 npmjs.com/package/@youngemmy/comment-cleaner
⭐ github.com/Youngemmy5956/comment-cleaner

🚀 Usage

# Preview commented-out code with severity levels (no changes made)
comment-cleaner ./src

# Preview what --fix would remove without touching files
comment-cleaner ./src --dry-run

# Auto-remove all commented-out code
comment-cleaner ./src --fix

# Step through each block interactively
comment-cleaner ./src -i

# Fix and save a report of what was removed
comment-cleaner ./src --fix -r

# Watch mode — alerts you in real time as you code
comment-cleaner ./src --watch

# Show scan history and trend over time
comment-cleaner --stats

# Fail CI if more than 5 commented blocks found
comment-cleaner ./src --threshold 5

# Save all reports (HTML + JSON + MD) to a folder
comment-cleaner ./src --output-dir ./reports

# Generate a beautiful HTML report
comment-cleaner ./src --html

# Output results as JSON
comment-cleaner ./src --json

# Save a Markdown report
comment-cleaner ./src -r

# Only scan Go and Rust files
comment-cleaner . -e .go,.rs

# Silent scan for CI
comment-cleaner ./src --no-preview -r audit.md

⚙️ Options

| Flag | Alias | Description | |------|-------|-------------| | --fix | -f | Automatically remove all detected commented-out code | | --interactive | -i | Step through each block — choose delete, keep, or skip | | --dry-run | | Show what --fix would remove without making any changes | | --watch | -w | Watch mode — alert on new commented-out code in real time | | --stats | | Show scan history and trend over time | | --threshold <n> | | Exit with error code if commented blocks exceed n (for CI) | | --output-dir <dir> | | Save all reports (HTML, JSON, MD) to a folder at once | | --html [file] | | Generate a beautiful HTML report | | --json [file] | | Output results as JSON — stdout or file | | --report [file] | -r | Save findings as a Markdown report | | --ext .js,.ts | -e | Only scan specific extensions (comma-separated) | | --ignore dir1,dir2 | | Extra directories to skip on top of defaults | | --no-preview | | Suppress terminal output | | --help | -h | Show help |

🎛️ Interactive Mode

Step through every flagged block one by one and decide what to do with each — no more all-or-nothing deletes.

comment-cleaner ./src -i

🎛️  Interactive mode — review each block one by one

📄 src/api.ts
  ┌─ lines 4–5 ─────────────────────── 🟢 LOW
  │    4    // const OLD_CACHE = new Map<string, User>();
  │    5    // if (OLD_CACHE.has(id)) return OLD_CACHE.get(id);
  └────────────────────────────────────────────────────

  → [d] delete  [k] keep  [s] skip file  [q] quit:

📈 Stats Mode

Track how your codebase is improving over time. Every scan is recorded automatically.

comment-cleaner --stats

📈 comment-cleaner — Scan History

  Last 10 scans:

  Date                  Path                          Blocks  Lines
  ──────────────────────────────────────────────────────────────────
  2/21/2026, 10:00 AM   src                               33      36
  2/20/2026,  9:30 AM   src                               21      24
  2/19/2026,  8:15 AM   src                                5       6

  📉 Trend: DOWN 28 blocks since first scan — great progress! 🎉

🚦 Threshold Mode

Perfect for CI pipelines — fail the build automatically if too many commented-out blocks are found.

comment-cleaner . --threshold 5

✅  Threshold passed: 3 blocks found, limit is 5    → exit code 0
❌  Threshold exceeded: 8 blocks found, limit is 5  → exit code 1

Add it to your GitHub Action:

- run: comment-cleaner . --threshold 10

📁 Output Dir

Save all three reports at once with a single command.

comment-cleaner ./src --output-dir ./reports

Creates:

reports/
├── comment-cleaner.html
├── comment-cleaner.json
└── comment-cleaner.md

🧪 Dry-run Mode

See exactly what --fix would remove before you commit to it. Nothing is changed.

comment-cleaner ./src --dry-run

🔒 @keep Annotation

Add @keep to any comment you want the tool to permanently ignore, even if it looks like dead code.

// @keep const LEGACY_URL = 'https://legacy.api.com'; // needed for migration
// @keep const OLD_TIMEOUT = 3000;

# @keep old_hash = hashlib.md5(password.encode()).hexdigest()

These lines will never be flagged, even with --fix.

🏷️ Severity Levels

Every detected block is automatically ranked so you know where to focus first.

| Level | Lines | Meaning | |-------|-------|---------| | 🔴 HIGH | 10+ lines | Large dead block — clean up first | | 🟡 MEDIUM | 4–9 lines | Medium dead block | | 🟢 LOW | 1–3 lines | Small dead comment |

Severity appears in the terminal, HTML report, Markdown report, and JSON output.

👀 Watch Mode

Monitors your project in the background and instantly alerts you when new commented-out code is saved.

comment-cleaner ./src --watch

🌐 HTML Report

A beautiful dark-themed visual report, perfect for sharing with your team.

comment-cleaner ./src --html
comment-cleaner ./src --html report.html

📦 JSON Output

Machine-readable output for CI pipelines, editor plugins, or custom scripts.

comment-cleaner ./src --json

{
  "generatedAt": "2026-02-21T10:00:00.000Z",
  "scannedPath": "src",
  "summary": {
    "filesScanned": 42,
    "filesWithIssues": 3,
    "commentedBlocks": 5,
    "linesAffected": 12
  },
  "files": {
    "src/api.ts": [
      {
        "startLine": 3,
        "endLine": 4,
        "lineCount": 2,
        "severity": "low",
        "code": "// const OLD_BASE = 'https://old.api.com';\n// const TIMEOUT = 5000;"
      }
    ]
  }
}

⚙️ Config File

Create a .commentcleanerrc in your project root. CLI flags always override config values.

{
  "extensions": [".js", ".jsx", ".ts", ".tsx", ".py", ".css", ".scss"],
  "ignore": ["tmp", "fixtures", "__tests__", "migrations"],
  "report": true,
  "reportPath": "comment-cleaner-report.md",
  "threshold": 10
}

🤖 GitHub Action

Create .github/workflows/comment-cleaner.yml:

name: 🧹 Comment Cleaner

on:
  pull_request:
    branches: [main, master, develop]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm install -g @youngemmy/comment-cleaner
      - run: comment-cleaner . --threshold 20 --output-dir reports || true
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: comment-cleaner-reports
          path: reports/

🌐 Supported Languages

| Language | Extensions | |----------|-----------| | JavaScript | .js .jsx .mjs .cjs | | TypeScript | .ts .tsx | | Python | .py | | Go | .go | | Java | .java | | Kotlin | .kt .kts | | Rust | .rs | | Ruby | .rb | | PHP | .php | | C / C++ | .c .cpp .h | | Swift | .swift | | CSS | .css | | SCSS / Sass / Less | .scss .sass .less |

🧠 How Detection Works

Only flags actual dead code — not comments that explain what your code does.

✅ Kept (not flagged)

// Load posts from Firebase
// Helper function to split the title
// TODO: add retry logic
/** @param {string} id - The user ID */
// @keep const LEGACY_URL = 'https://legacy.api.com';

❌ Flagged (dead code)

// import TwitterTimeline from "../components/TwitterTimeline";
// const BASE_URL = 'https://api.legacy.com/v1';
// function oldGetUser(id) { return db.query(id); }

// oldDB := sql.Open("postgres", connStr)
// rows, _ := oldDB.Query("SELECT * FROM users")

// fn old_parse(input: &str) -> HashMap<String, i32> {
//     HashMap::new()
// }

💡 Tips

Always preview first or use --dry-run before --fix
Use -i when you want control over what gets deleted
Use --watch during development to catch dead comments as you write them
Use --stats to track your cleanup progress over time
Use --threshold in CI to enforce clean code standards
Use --output-dir to save all reports in one shot
Use @keep to protect comments that look like dead code but are intentional
Use --fix -r to remove code and keep a record of what was deleted

🤝 Contributing

Contributions, issues, and feature requests are welcome! See CONTRIBUTING.md for details. Open an issue at github.com/Youngemmy5956/comment-cleaner/issues

👨‍💻 Author

Nwamini Emmanuel O