rubocop-claude 0.1.0

data/templates/cops/no-backwards-compat-hacks.md

@@ -0,0 +1,101 @@
+# Claude/NoBackwardsCompatHacks
+
+**What it catches:** Self-documented compatibility hacks - code with comments like "for backwards compatibility" or markers like `# removed:`.
+
+**Why it matters:** Dead code should be deleted, not preserved "helpfully."
+
+## The Principle
+
+When removing or replacing code, **delete it completely**. Don't:
+- Leave commented tombstones (`# removed: old_method`)
+- Create "compatibility shims" (`OldName = NewName`)
+- Silence linters with underscore prefixes (`_unused = old_value`)
+- Add wrapper methods that just delegate to new ones
+- Keep empty methods "for backwards compatibility"
+
+Version control preserves history. Callers should be updated, not shimmed.
+
+## What This Cop Detects
+
+This cop catches **self-documented** hacks - patterns where you've helpfully commented your intent:
+
+```ruby
+# CAUGHT - has compat comment
+OldName = NewName  # for backwards compatibility
+
+# CAUGHT - dead code marker
+# removed: def old_method; end
+# deprecated: use new_method instead
+
+# NOT CAUGHT - no comment (silent hack)
+OldName = NewName
+```
+
+### Detection Philosophy
+
+We only catch ~30% of compat hacks (the self-documented ones). This is intentional.
+
+**The goal is teaching, not comprehensive detection.**
+
+When this cop fires, you're reading this guidance and learning the principle. Even if we can't catch every case, the teaching moments shape better habits over time.
+
+## How to Fix
+
+### Dead Code Markers
+
+```ruby
+# BAD
+# removed: def old_method; end
+# deprecated: use new_method instead
+# legacy: keeping for backwards compat
+
+# GOOD - just delete the comment entirely
+```
+
+### Constant Re-exports
+
+```ruby
+# BAD
+OldClassName = NewClassName  # for backwards compatibility
+
+# GOOD - delete the alias, update all callers
+# (yes, even if there are many callers)
+```
+
+### Underscore Assignments (optional check)
+
+```ruby
+# BAD (if CheckUnderscoreAssignments: true)
+_old_value = calculate_something
+
+# GOOD - delete the line if the value isn't needed
+```
+
+## For AI Assistants
+
+**When you're about to add a compat shim, stop.** Ask yourself:
+
+1. "Am I preserving dead code?" → Delete it instead
+2. "Will callers break?" → Update the callers
+3. "There are too many callers" → Update them anyway, or ask the human
+4. "What if someone needs the old behavior?" → They can use git history
+
+**Never:**
+- Add `# for backwards compatibility` comments
+- Create `OldName = NewName` aliases
+- Use `_unused = value` to silence linters
+- Leave `# removed:` or `# deprecated:` markers
+- Create wrapper methods that just delegate
+
+**Instead:**
+- Delete the old code completely
+- Update all callers to use the new code
+- If unsure, ask: "Should I update all callers or is there a reason to keep the old interface?"
+
+## Configuration
+
+```yaml
+Claude/NoBackwardsCompatHacks:
+  Enabled: true
+  CheckUnderscoreAssignments: false  # Optional, off by default
+```

data/templates/cops/no-commented-code.md

@@ -0,0 +1,74 @@
+# Claude/NoCommentedCode
+
+**What it catches:** Commented-out code (even single lines by default).
+
+**Why it matters:** Commented code is technical debt. Version control preserves history - just delete it.
+
+**Autocorrectable:** Yes (unsafe) - deletes the commented code. Run `rubocop -A` to auto-fix.
+
+## How to Fix
+
+```ruby
+# BAD
+# def old_method
+#   do_something
+# end
+
+# BAD - even single lines
+# user.update!(name: "test")
+
+# GOOD - just delete the commented code entirely
+```
+
+## The KEEP Exception
+
+Sometimes you genuinely need to preserve commented code temporarily. Use a `KEEP` comment with attribution:
+
+```ruby
+# GOOD - explicit, attributed, time-boxed
+# KEEP [@username]: Rollback path during migration, remove after 2025-06
+# def legacy_method
+#   old_implementation
+# end
+
+# BAD - KEEP without attribution doesn't work
+# KEEP: I might need this later
+# def old_method
+#   do_something
+# end
+```
+
+### KEEP Rules
+
+1. **Must have attribution** - `[@handle]` format (same as TaggedComments)
+2. **Must have justification** - explain why it's kept
+3. **Should be time-boxed** - include a removal date when possible
+4. **Only protects the immediately following block** - prose comments break the protection
+
+## For AI Assistants
+
+**Default behavior: delete commented code.** Don't ask "should I keep this?" - the answer is delete.
+
+If you encounter a `# KEEP` comment with valid attribution, leave it alone. The human made an explicit decision to preserve that code.
+
+**Never add KEEP comments yourself** unless the human explicitly asks you to preserve specific code temporarily.
+
+## What's NOT Commented Code
+
+These are fine and won't be flagged:
+
+- Explanatory prose comments
+- Documentation (YARD/RDoc)
+- TODO/FIXME/NOTE annotations
+- `@example` blocks in documentation
+- RuboCop directives
+
+## Configuration
+
+```yaml
+Claude/NoCommentedCode:
+  MinLines: 1        # Flag even single lines (default)
+  AllowKeep: true    # Honor KEEP comments with attribution (default)
+```
+
+Set `MinLines: 2` if single-line detection is too noisy for your codebase.

data/templates/cops/no-fancy-unicode.md

@@ -0,0 +1,72 @@
+# Claude/NoFancyUnicode
+
+**What it catches:** Non-standard Unicode characters outside the allowed set (letters, numbers, ASCII symbols).
+
+**Why it matters:** Fancy Unicode causes subtle bugs. Curly quotes `""` break string matching. Mathematical symbols `≠` look like `!=` but aren't. Em-dashes `—` aren't hyphens. Emoji reduce professionalism.
+
+## How to Fix
+
+```ruby
+# BAD - curly quotes
+puts "Hello world"
+
+# BAD - em-dash
+# Section 3 — Details
+
+# BAD - mathematical symbol
+puts "x ≠ y"
+
+# BAD - emoji
+puts "Success! 🎉"
+status = :done_✅
+
+# GOOD - ASCII equivalents
+puts "Hello world"
+
+# GOOD - double hyphen or just hyphen
+# Section 3 -- Details
+
+# GOOD - ASCII operators
+puts "x != y"
+
+# GOOD - no emoji
+puts "Success!"
+status = :done
+```
+
+## Allowed Characters
+
+- **Letters** - Any script: Latin, Chinese, Japanese, Cyrillic, Arabic, etc.
+- **Numbers** - Any script
+- **Combining marks** - Accents, diacritics (café, José)
+- **ASCII printable** - All standard keyboard symbols (0x20-0x7E)
+- **Whitespace** - Tabs, newlines
+
+## Configuration Options
+
+```yaml
+Claude/NoFancyUnicode:
+  AllowedUnicode: ['→', '←', '•']  # Specific chars to permit
+  AllowInStrings: false            # Skip checking strings
+  AllowInComments: false           # Skip checking comments
+```
+
+## Common Replacements
+
+| Fancy | ASCII | Description |
+|-------|-------|-------------|
+| `"` `"` | `"` | Curly quotes to straight quotes |
+| `'` `'` | `'` | Curly apostrophes to straight |
+| `—` | `--` | Em-dash to double hyphen |
+| `–` | `-` | En-dash to hyphen |
+| `≠` | `!=` | Not equal |
+| `≤` `≥` | `<=` `>=` | Comparison operators |
+| `→` `←` | `->` `<-` | Arrows |
+| `•` | `*` or `-` | Bullet |
+
+## When to Allow
+
+Add to `AllowedUnicode` if the character is:
+- Required by external API or data format
+- Part of user-facing content where typography matters
+- In comments explaining Unicode behavior

data/templates/cops/no-hardcoded-line-numbers.md

@@ -0,0 +1,70 @@
+# Claude/NoHardcodedLineNumbers
+
+**What it catches:** Hardcoded line numbers in comments and strings that become stale when code shifts.
+
+**Why it matters:** References like "see line 42" or "foo.rb:123" break silently as code evolves. Use stable references like method names, class names, or descriptive comments instead.
+
+## How to Fix
+
+```ruby
+# BAD - line numbers shift when code changes
+# see line 42 for details
+# Error defined at foo.rb:123
+raise "error at line 42"
+
+# GOOD - use stable references
+# see #validate_input for details
+# Error defined in FooError class
+raise "error in validate_input"
+
+# GOOD - use descriptive comments
+# The validation logic below handles edge cases
+# See the ErrorHandler module for error definitions
+```
+
+## Patterns Detected
+
+| Pattern | Example | Description |
+|---------|---------|-------------|
+| `line N` | `# see line 42` | Natural language reference |
+| `lines N` | `# lines 42-50` | Plural form |
+| `LN` | `# see L42` | GitHub-style reference |
+| `.rb:N` | `# foo.rb:123` | Ruby file:line format |
+| `.erb:N` | `# app.erb:10` | ERB file:line format |
+| `.rake:N` | `# tasks.rake:5` | Rake file:line format |
+
+## Patterns NOT Flagged
+
+These are explicitly ignored:
+
+- Version strings: `Ruby 3.1`, `v1.2.3`, `1.2.3`
+- Port numbers: `port 8080`
+- IDs: `id: 42`, `pid: 1234`
+- Time durations: `30 seconds`, `100ms`
+- Byte sizes: `100 bytes`, `5mb`
+- Percentages: `50%`
+- Dollar amounts: `$42`
+- Issue references: `#42`
+
+## Configuration
+
+```yaml
+Claude/NoHardcodedLineNumbers:
+  Enabled: true
+  CheckComments: true   # Check comments for line refs (default: true)
+  CheckStrings: true    # Check string literals (default: true)
+  MinLineNumber: 1      # Only flag line numbers >= this (default: 1)
+```
+
+## Better Alternatives
+
+| Instead of... | Use... |
+|---------------|--------|
+| `# see line 42` | `# see #method_name` |
+| `# foo.rb:123` | `# see FooClass#method` |
+| `"error at line 42"` | `"error in validate_input"` |
+| `# L42 handles this` | `# The validation block handles this` |
+
+## Edge Cases
+
+The cop reports only the first line number per node to avoid noisy output. Heredocs are intentionally ignored since they often contain documentation or templates where line references may be intentional.

data/templates/cops/no-overly-defensive-code.md

@@ -0,0 +1,117 @@
+# Claude/NoOverlyDefensiveCode
+
+**What it catches:**
+1. `rescue => e; nil` or `rescue nil` - swallowing errors
+2. 2+ chained `&.` operators - excessive safe navigation
+3. `a && a.foo` - defensive nil check before method call
+4. `a.present? && a.foo` - defensive presence check
+5. `foo.nil? ? default : foo` - verbose nil ternary
+6. `foo ? foo : default` - verbose identity ternary
+
+**Why it matters:** Defensive code hides bugs and indicates distrust of the codebase. Internal code should be trusted; errors should propagate.
+
+## The Principle
+
+Don't code defensively against your own codebase. When you add defensive patterns, you're saying "I don't trust this code." Either:
+1. Fix the code so it's trustworthy, or
+2. Handle the error/nil explicitly and meaningfully
+
+## Error Swallowing
+
+```ruby
+# BAD - swallows all errors
+begin
+  risky_operation
+rescue => e
+  nil
+end
+
+# BAD - inline form
+result = dangerous_call rescue nil
+
+# GOOD - let errors propagate
+result = risky_operation
+
+# GOOD - specific exceptions with intentional ignore
+begin
+  require 'optional_gem'
+rescue LoadError
+  # Optional dependency not available
+end
+```
+
+## Excessive Safe Navigation
+
+```ruby
+# BAD - 2+ chained &. violates design principles
+user&.profile&.settings
+
+# GOOD - single &. at system boundary
+user&.name
+
+# GOOD - trust your data model
+user.profile.settings.notifications
+```
+
+## Defensive Nil Checks
+
+```ruby
+# BAD - pre-safe-navigation pattern
+a && a.foo
+user && user.name
+
+# BAD - presence check before method call
+user.present? && user.name
+
+# GOOD (default: AddSafeNavigator: false) - trust the code
+a.foo
+user.name
+
+# ALTERNATIVE (AddSafeNavigator: true) - if you really need nil safety
+a&.foo
+user&.name
+```
+
+## Verbose Ternaries
+
+```ruby
+# BAD - verbose nil check
+foo.nil? ? default : foo
+value.blank? ? fallback : value
+
+# BAD - verbose identity check
+foo ? foo : default
+
+# GOOD - use ||
+foo || default
+value || fallback
+```
+
+## For AI Assistants
+
+**When you're about to add defensive code, stop.** Ask yourself:
+
+1. "Why don't I trust this code?" → Fix the trust issue instead
+2. "What error am I hiding?" → Let it propagate or handle it properly
+3. "Why might this be nil?" → Fix the data model or handle at the boundary
+
+**The right response to uncertainty is not defensive code.** It's:
+- Understanding why the uncertainty exists
+- Fixing the root cause
+- Or asking the human: "This could be nil/error here - how should I handle it?"
+
+## Configuration
+
+```yaml
+Claude/NoOverlyDefensiveCode:
+  Enabled: true
+  MaxSafeNavigationChain: 1   # Flag 2+ chained &. operators
+  AddSafeNavigator: false     # Autocorrect `a && a.foo` to `a.foo` (fail fast)
+                              # Set to true for `a&.foo` (add safe nav)
+```
+
+## Related Cops
+
+If using `rubocop-rails`, also enable:
+- `Rails/Present` - catches `a && a.present?`
+- `Rails/Blank` - catches `a.blank? && a.foo`

data/templates/cops/tagged-comments.md

@@ -0,0 +1,74 @@
+# Claude/TaggedComments
+
+**What it catches:** TODO/FIXME/NOTE/HACK comments without attribution.
+
+**Why it matters:** Anonymous TODOs lose context. Attribution tracks ownership and distinguishes human comments from AI-generated ones.
+
+## How to Fix
+
+```ruby
+# BAD
+# TODO: Refactor this method
+# FIXME: Handle edge case
+
+# GOOD - human attribution
+# TODO [@username]: Refactor this method - it's doing too much
+# FIXME [Alice - @alice]: Handle edge case where user is nil
+
+# GOOD - AI attribution
+# TODO [@claude]: Consider extracting to a service object
+# NOTE [@claude]: This mirrors the pattern in user_factory.rb
+```
+
+## For AI Assistants
+
+**Your handle is `@claude`.** When you write TODO/FIXME/NOTE/HACK comments, always use `[@claude]`:
+
+```ruby
+# TODO [@claude]: This method could be simplified
+# NOTE [@claude]: Intentionally duplicated from BaseController for isolation
+```
+
+This makes it easy to find AI-generated comments later with `grep -r "@claude"`.
+
+## Attribution Format
+
+Required format: `[@handle]` or `[Name - @handle]`
+
+| Format | Example | Valid |
+|--------|---------|-------|
+| Handle only | `[@username]` | Yes |
+| Name + handle | `[Alice - @alice]` | Yes |
+| Full name + handle | `[Alice Smith - @alice]` | Yes |
+| No @ symbol | `[username]` | No |
+| No handle | `[Alice]` | No |
+| Plain text | `[some text]` | No |
+
+## Placement
+
+Attribution can appear anywhere in the comment:
+
+```ruby
+# Both valid:
+# TODO [@username]: Fix this later
+# TODO: Fix this later [@username]
+```
+
+## Configuration Options
+
+```yaml
+Claude/TaggedComments:
+  Keywords:
+    - TODO
+    - FIXME
+    - NOTE      # Default keywords
+    - HACK
+    - OPTIMIZE
+    - REVIEW
+```
+
+## When Fixing Existing Comments
+
+- **Your own new comments:** Use `[@claude]`
+- **Existing anonymous comments:** Ask the human whose attribution to use
+- **Don't guess:** If unsure, ask "Who should I attribute this TODO to?"

data/templates/hooks/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/ruby-lint.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

data/templates/linting.md

@@ -0,0 +1,81 @@
+# Linting
+
+Run `bin/standardrb` (or `bin/rubocop`) before committing. Fix all errors.
+
+## Quick Reference
+
+| Cop | Fix |
+|-----|-----|
+| **Claude/NoFancyUnicode** | Remove emoji and fancy Unicode. Use ASCII text. |
+| **Claude/TaggedComments** | Add attribution: `# TODO: [@handle] description` |
+| **Claude/NoCommentedCode** | Delete commented-out code. Use version control. |
+| **Claude/NoBackwardsCompatHacks** | Delete dead code. Don't preserve for compatibility. |
+| **Claude/NoOverlyDefensiveCode** | Trust internal code. Remove `rescue nil` and excessive `&.` chains. |
+| **Claude/ExplicitVisibility** | Use consistent visibility style (grouped or modifier). |
+| **Claude/MysteryRegex** | Extract long regexes to named constants. |
+
+## When to Ask
+
+- If a cop seems wrong for this codebase, ask before disabling
+- If you're unsure how to fix, ask rather than guessing
+- Never add `# rubocop:disable` without discussing first
+
+## Common Patterns
+
+### Tagged Comments
+```ruby
+# bad
+# TODO fix this later
+
+# good
+# TODO: [@username] fix this later
+```
+
+### Commented Code
+```ruby
+# bad - delete this, don't comment it out
+# def old_method
+#   do_something
+# end
+
+# good - just delete it, git has history
+```
+
+### Defensive Code
+```ruby
+# bad - swallowing errors
+result = dangerous_call rescue nil
+
+# bad - excessive safe navigation
+user&.profile&.settings&.value
+
+# bad - defensive nil check
+user && user.name
+
+# good - trust internal code
+result = dangerous_call
+user.profile.settings.value
+user.name
+```
+
+### Visibility Style
+
+Check `.rubocop.yml` for `EnforcedStyle` (grouped or modifier):
+
+```ruby
+# grouped style (default)
+class Foo
+  def public_method; end
+
+  private
+
+  def private_method; end
+end
+
+# modifier style
+class Foo
+  def public_method; end
+
+  private def private_method; end
+end
+```