👹 gremlh (Gremlin Hunter)

gremlh is a blazing fast, multi-threaded CLI tool designed to hunt down and sanitize "gremlin" characters in your source code.

It identifies invisible characters, zero-width spaces, homoglyphs, and potential security risks (such as Trojan Source attacks) that can cause compilation errors, syntax issues, or confusing bugs.

🚀 Features

• 🛡️ Security First: Detects Bidi overrides (\u202A - \u202E) used in supply-chain attacks.
• ⚡ Parallel Scanning: Built on the ignore crate (the same engine used by ripgrep) for maximum speed.
• 💾 Atomic Writes: Fixes files safely. Changes are written to a temporary file and swapped only upon success.
• 🤖 Smart Detection: Automatically skips binary files and respects .gitignore rules.
• 🐚 Shell Integration: Comes with Man pages and completions for Bash, Zsh, and Fish.
• ✨ CI Ready: Strict exit codes (1 for found gremlins, 0 for clean).

📦 Installation

From Source (Recommended for Rust users)

cargo install gremlh

Pre-built Binaries

Download pre-built binaries for Linux, macOS, and Windows from the GitHub Releases page.

Homebrew (macOS/Linux)

brew tap boorboor/gremlh
brew install gremlh

🛠️ Usage

1. Scan Mode (Default)

Recursively scans the current directory. Prints issues to stderr and exits with code 1 if gremlins are found.

gremlh
# Or specify a path
gremlh ./src

Example Output:

src/main.rs:10:45: found "​" (Zero Width Space)
src/legacy.js:2:15: found "“" (Smart Double Quote)
src/security.go:5:1: found "‮" (Bidirectional Text Override)

2. Fix Mode (--write)

Automatically cleans files in-place.

gremlh --write

What gets fixed?

• Smart Quotes: “ → "
• Non-Breaking Spaces: \u00A0 → (Space)
• Zero-Width Characters: Removed entirely.
• BOM: Byte Order Mark removed.
• Bidi Characters: Removed entirely.

3. Pipe Mode (STDIN)

Great for scripting or single-file processing.

cat dirty_file.txt | gremlh > clean_file.txt

⚙️ Command Line Options

🔌 Integrations

GitHub Actions (Native)

gremlh provides a native GitHub Action. Add this to your workflow to fail builds when gremlins are detected, or automatically fix them.

steps:
  - uses: actions/checkout@v4

  - name: Gremlin Hunter
    uses: boorboor/gremlh@v0.1.0
    with:
      path: 'src/'          # Optional: defaults to '.'
      write: 'false'        # Optional: set to 'true' to fix files
      verbose: 'true'       # Optional: show scanned files
      # no-ignore: 'true'   # Optional: ignore .gitignore
      # hidden: 'true'      # Optional: scan hidden files

Git Hooks (Pre-commit)

Add this to your .pre-commit-config.yaml. We provide two hooks: one for checking, and one for auto-fixing.

-   repo: [https://github.com/boorboor/gremlh](https://github.com/boorboor/gremlh)
    rev: v0.1.0
    hooks:
    -   id: gremlh          # Fail on detection
    # OR
    -   id: gremlh-fix      # Auto-fix on commit

Vim/Neovim

Auto-fix on save (add to your init.vim or .vimrc):

augroup GremlinKiller
    autocmd!
    autocmd BufWritePre *.rs,*.js,*.py silent! %!gremlh 2>/dev/null
augroup END

🔍 Detected Gremlins

💻 Development

We welcome contributions! Please see CONTRIBUTING.md for details on how to set up the environment and add new gremlin definitions.

1. Install tools: cargo install prek
2. Setup hooks: prek install
3. Run checks: prek run --all-files

⚠️ Known Limitations

• Visual Columns: Error reporting uses character indices, not visual columns (tabs are counted as 1 char).
• Encodings: Only UTF-8 is supported. UTF-16 files are typically treated as binary and skipped.

📄 License

This project is licensed under the Apache-2.0 License.