mroberts/shush
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: update documentation for v0.2.0 features

Browse Source 
- Add configuration system documentation with TOML examples
- Document Claude Code hooks integration (now available)
- Update CLI options with new hook management commands
- Add string-aware parsing and comment preservation features
- Update architecture overview with new packages and flow
This commit is contained in:
carraes
2025-07-06 09:04:34 -03:00
parent 39e3c27f34
commit 9e372f5f52
2 changed files with 129 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+46 -22
View File
@@ -4,11 +4,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview ## Project Overview
Shush is a CLI tool written in Go that removes comments from source code files using sed under the hood. It supports multiple programming languages and can process individual files or directories (with optional recursive traversal). The tool emphasizes preserving file structure while providing precise comment removal control. Shush is a CLI tool written in Go that removes comments from source code files while preserving important comments through configuration. It supports multiple programming languages and can process individual files or directories with optional recursive traversal. The tool emphasizes preserving file structure while providing precise comment removal control.
**Key Features**: **Key Features**:
- **Git-aware processing**: Surgical precision targeting only changed lines - **Git-aware processing**: Surgical precision targeting only changed lines
- **Claude Code integration**: Automatic comment cleanup via hooks (planned v0.2.0) - **Claude Code integration**: Automatic comment cleanup via hooks (✅ available now)
- **Smart comment preservation**: Configurable patterns via .shush.toml with wildcard support
- **String-aware parsing**: Preserves URLs and strings containing comment markers
- **Dual processing modes**: Traditional sed-based + in-memory line-based for git operations - **Dual processing modes**: Traditional sed-based + in-memory line-based for git operations
## Build and Development Commands ## Build and Development Commands
@@ -39,48 +41,67 @@ make dev
# Git-aware examples # Git-aware examples
./shush --staged --dry-run ./shush --staged --dry-run
./shush --changes-only ./shush --changes-only
# Configuration and hooks examples
./shush --create-config
./shush --config
./shush --install-hook
./shush --hook-status
``` ```
## Architecture ## Architecture
### Project Structure ### Project Structure
- `cmd/shush/main.go` - Entry point, CLI parsing with kong, version management, LLM guide, git flag validation - `cmd/shush/main.go` - Entry point, CLI parsing with kong, version management, LLM guide, hook commands
- `internal/types/types.go` - Core type definitions (CLI struct with git flags, Language struct, BlockComment) - `internal/types/types.go` - Core type definitions (CLI struct with hook flags, Language struct, BlockComment)
- `internal/processor/processor.go` - Main processing logic, routing between sed and git modes - `internal/processor/processor.go` - Main processing logic, routing between sed and git modes
- `internal/processor/git_processor.go` - Git-aware processing with line-based comment removal - `internal/processor/git_processor.go` - Git-aware processing with line-based comment removal + config integration
- `internal/processor/languages.go` - Language detection and mapping (file extension → comment syntax) - `internal/processor/languages.go` - Language detection and mapping (file extension → comment syntax)
- `internal/git/` - Git operations: repo detection, diff parsing, line range extraction - `internal/git/` - Git operations: repo detection, diff parsing, line range extraction
- `internal/config/` - TOML configuration system with wildcard pattern matching
- `internal/hooks/` - Claude Code hooks integration with conflict detection
- `ai_docs/` - Design documents (GIT_FEATURE_PLAN.md, HOOKS_FEATURE_PLAN.md) - `ai_docs/` - Design documents (GIT_FEATURE_PLAN.md, HOOKS_FEATURE_PLAN.md)
### Core Flow ### Core Flow
1. **CLI Parsing**: Kong parses arguments into `types.CLI` struct with git flag validation 1. **CLI Parsing**: Kong parses arguments into `types.CLI` struct with hook and git flag validation
2. **Mode Detection**: Route to git-aware or traditional processing 2. **Mode Detection**: Route to hook commands, git-aware processing, or traditional processing
3. **Git Mode** (`--staged`, `--unstaged`, `--changes-only`): 3. **Hook Commands** (`--install-hook`, `--hook-status`, etc.):
- Settings file management for user-wide and project-specific scopes
- Cross-scope conflict detection and prevention
- JSON configuration merging with existing Claude Code hooks
4. **Git Mode** (`--staged`, `--unstaged`, `--changes-only`):
- Configuration loading from .shush.toml files
- Git repository detection and file change analysis - Git repository detection and file change analysis
- Diff parsing to extract precise line ranges - Diff parsing to extract precise line ranges
- Line-based comment removal with totals tracking - String-aware comment removal with pattern-based preservation
4. **Traditional Mode** (file/directory paths): 5. **Traditional Mode** (file/directory paths):
- Language detection from file extension - Language detection from file extension
- Sed command generation and execution - Sed command generation and execution
- Directory scanning (recursive if `-r` flag) - Directory scanning (recursive if `-r` flag)
5. **Output**: Color-coded preview, totals summary, or file modification 6. **Output**: Color-coded preview with preserved comment indicators, totals summary, or file modification
### Key Design Principles ### Key Design Principles
- **Dual Processing Architecture**: - **Dual Processing Architecture**:
- Traditional: sed-based for entire files/directories - Traditional: sed-based for entire files/directories
- Git-aware: in-memory line-based for surgical precision - Git-aware: in-memory line-based for surgical precision with config integration
- **Comment Removal Logic**: - **String-Aware Processing**:
- Comment-only lines are deleted entirely - Preserves URLs and strings containing comment markers (e.g., `"https://example.com"`)
- Inline comments are stripped but lines preserved - Context-aware parsing respects quote boundaries and escaping
- **Comment Preservation Logic**:
- Configurable patterns via .shush.toml (exact matches + wildcards)
- Comment-only lines are deleted entirely unless preserved
- Inline comments are stripped but lines preserved unless preserved
- Spacing preserved unless comments are actually removed - Spacing preserved unless comments are actually removed
- **Git Integration**: Surgical targeting of only changed lines - **Git Integration**: Surgical targeting of only changed lines
- **Language Support**: Extensible via `languageMap` in `languages.go` - **Language Support**: Extensible via `languageMap` in `languages.go`
### Comment Processing Rules ### Comment Processing Rules
- **Line comments** (`//`, `#`, `--`): Remove entire line if comment-only, strip inline comments - **Line comments** (`//`, `#`, `--`): Remove entire line if comment-only, strip inline comments
- **Block comments** (`/* */`): Remove single-line or multi-line blocks - **Block comments** (`/* */`): Remove single-line or multi-line blocks
- **Preservation patterns**: Check against .shush.toml preserve patterns before removal
- **String protection**: Comment markers inside strings are ignored
- **Git mode**: Only processes lines within detected change ranges - **Git mode**: Only processes lines within detected change ranges
- **Flag exclusions**: `--inline` and `--block` are mutually exclusive; git flags are mutually exclusive - **Flag exclusions**: `--inline` and `--block` are mutually exclusive; git flags are mutually exclusive; hook commands are mutually exclusive
- **Structure preservation**: Never remove intentional blank lines; preserve spacing unless comments removed - **Structure preservation**: Never remove intentional blank lines; preserve spacing unless comments removed
## Release Process ## Release Process
@@ -106,11 +127,14 @@ The git-aware comment removal feature is now implemented:
- `--unstaged`: Remove comments only from unstaged changes ✅ - `--unstaged`: Remove comments only from unstaged changes ✅
- `--changes-only`: Process all git changes (staged + unstaged + untracked) ✅ - `--changes-only`: Process all git changes (staged + unstaged + untracked) ✅
### Planned: Claude Code Hooks Integration (v0.2.0) ### Completed: Configuration System & Claude Code Hooks (v0.2.0)
Seamless integration with Claude Code via hooks (see `ai_docs/HOOKS_FEATURE_PLAN.md`): Smart comment preservation and seamless Claude Code integration:
- `--install-hooks`: Auto-configure Claude Code to run shush after file modifications - TOML configuration with wildcard pattern support ✅
- `--install-hooks project`: Project-specific hook installation - `--install-hook`: Auto-configure Claude Code to run shush after file modifications ✅
- Automatic comment cleanup with zero manual intervention - `--install-hook -s project`: Project-specific hook installation ✅
- Cross-scope conflict detection prevents duplicate execution ✅
- String-aware parsing preserves URLs and code in strings ✅
- Automatic comment cleanup with configurable preservation ✅
## Development Notes ## Development Notes
README.md
+83 -13
View File
@@ -1,6 +1,6 @@
# shush 🤫 # shush 🤫
Remove comments from source code files blazingly fast using sed under the hood. Features git-aware processing and Claude Code integration. Remove comments from source code files blazingly fast using sed under the hood. Features git-aware processing, smart comment preservation, and Claude Code integration.
## Installation ## Installation
@@ -46,6 +46,13 @@ shush --staged # Clean comments from staged changes
shush --unstaged # Clean comments from unstaged changes shush --unstaged # Clean comments from unstaged changes
shush --changes-only # Clean comments from all changes shush --changes-only # Clean comments from all changes
# Configuration and hooks management
shush --create-config # Create .shush.toml configuration
shush --config # Show current configuration
shush --install-hook # Install Claude Code hooks (user-wide)
shush --install-hook -s project # Install project-specific hooks
shush --hook-status # Check hook installation status
# Combine flags for complex operations # Combine flags for complex operations
shush src/ --recursive --inline --dry-run --verbose shush src/ --recursive --inline --dry-run --verbose
``` ```
@@ -68,8 +75,11 @@ shush src/ --recursive --inline --dry-run --verbose
## Options ## Options
``` ```
# Comment filtering
--inline Remove only line comments --inline Remove only line comments
--block Remove only block comments --block Remove only block comments
# Processing modes
-r, --recursive Process directories recursively -r, --recursive Process directories recursively
--dry-run Show what would be removed without making changes --dry-run Show what would be removed without making changes
--backup Create backup files before modification --backup Create backup files before modification
@@ -80,6 +90,17 @@ shush src/ --recursive --inline --dry-run --verbose
--staged Remove comments only from staged git changes --staged Remove comments only from staged git changes
--unstaged Remove comments only from unstaged git changes --unstaged Remove comments only from unstaged git changes
# Configuration management
--config Show current configuration and location
--create-config Create example .shush.toml configuration file
# Claude Code hooks
--install-hook Install Claude Code hooks for automatic comment cleanup
--uninstall-hook Uninstall Claude Code hooks
--list-hooks List current Claude Code hooks configuration
--hook-status Check if shush hooks are installed
-s, --hook-scope Hook scope: 'project' for local, default for user-wide
# Utility flags # Utility flags
--version Show version information --version Show version information
--llm Show LLM-friendly usage guide --llm Show LLM-friendly usage guide
@@ -146,29 +167,78 @@ shush important.go --backup
shush config.yaml --dry-run --verbose shush config.yaml --dry-run --verbose
``` ```
## Comment Preservation Configuration 🎯
Shush supports smart comment preservation through `.shush.toml` configuration files:
```bash
# Create example configuration file
shush --create-config
# Check current configuration
shush --config
```
### Configuration File (`.shush.toml`)
```toml
# Patterns to preserve in comments (supports wildcards with *)
preserve = [
"TODO:",
"FIXME:",
"HACK:",
"XXX:",
"@ts-ignore",
"@ts-expect-error",
"eslint-",
"prettier-ignore",
"pylint:",
"mypy:",
"type: ignore",
"*IMPORTANT*", # Wildcard: preserves any comment containing IMPORTANT
"*DEBUG*", # Wildcard: preserves any comment containing DEBUG
]
```
### Configuration Discovery
Shush searches for configuration in this order:
1. `.shush.toml` (current directory)
2. `.shush.toml` (git repository root)
3. `~/.config/.shush.toml` (global user config)
## Claude Code Integration 🤖 ## Claude Code Integration 🤖
*Coming soon in v0.2.0* - Seamless integration with Claude Code via hooks: Seamless integration with Claude Code via hooks - **available now**:
```bash ```bash
# Install automatic comment cleanup after Claude modifies files # Install automatic comment cleanup after Claude modifies files
shush --install-hooks # User-wide (all projects) shush --install-hook # User-wide (all projects)
shush --install-hooks project # Project-specific only shush --install-hook -s project # Project-specific only
# Check hook status # Manage hooks
shush --hooks-status # See current configuration shush --hook-status # Check installation status
shush --list-hooks # Show all configured hooks
shush --uninstall-hook # Remove hooks
# Hook scope conflict detection
# Prevents duplicate execution when both user and project hooks exist
``` ```
Once installed, comments will be automatically cleaned whenever Claude Code uses Write, Edit, or MultiEdit tools. No manual intervention required! Once installed, comments will be automatically cleaned whenever Claude Code uses Write, Edit, or MultiEdit tools. Respects your `.shush.toml` configuration for comment preservation!
## How It Works ## How It Works
shush uses optimized sed commands to remove comments while preserving code structure. It: shush uses optimized processing to remove comments while preserving code structure:
- Auto-detects language from file extension
- Builds appropriate sed patterns for the detected language - **Language Detection**: Auto-detects language from file extension
- **Git-aware processing**: Only processes changed lines for surgical precision - **String-Aware Parsing**: Preserves URLs and strings that contain comment markers (e.g., `"https://example.com"`)
- Preserves strings and code that might look like comments - **Git-Aware Processing**: Only processes changed lines for surgical precision
- **Claude Code integration**: Automatic cleanup via PostToolUse hooks - **Smart Preservation**: Configurable comment preservation via `.shush.toml` patterns
- **Dual Processing Modes**:
- Traditional sed-based for files/directories
- Line-based processing for git operations with comment preservation
- **Claude Code Integration**: Automatic cleanup via PostToolUse hooks
## Building from Source ## Building from Source