rubocop-claude 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d78f7699573dfffb71fa026fddbfaed2191d0185356e4dc4372d4743363b2b15
+  data.tar.gz: 3d497ed62af42361fbd1bfda74f08b4595b70167513c99160a63a78cb8e619e4
+SHA512:
+  metadata.gz: 22de6e579985bd72a3b85b1d0b3096b2bf95ab76a06200a149029a018dcac4da619dbdf86d9564e763eecaeb10c4864fcd97dffaf7cfeae3f781b892650951ff
+  data.tar.gz: 0d9f7b33281e32a341f0e65051b2457a69e06dd33bcc81df5708764f41a9f2adfab3ed59aed90921c12fbacbfcb27a1639cfe0b90277bb56751359c0b90633e0

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [0.1.0] - 2025-01-25
+
+First release.
+
+### Added
+
+- `Claude/NoHardcodedLineNumbers` - Flags hardcoded line numbers that become stale
+
+## [0.0.1] - 2025-01-20
+
+Initial pre-alpha release.
+
+### Added
+
+- `Claude/NoFancyUnicode` - Flags emoji and fancy Unicode characters
+- `Claude/TaggedComments` - Requires attribution on TODO/FIXME/NOTE comments
+- `Claude/NoCommentedCode` - Detects commented-out code blocks
+- `Claude/NoBackwardsCompatHacks` - Catches dead code preserved for compatibility
+- `Claude/NoOverlyDefensiveCode` - Flags rescue nil, excessive &. chains, defensive nil checks
+- `Claude/ExplicitVisibility` - Enforces consistent visibility style
+- `Claude/MysteryRegex` - Flags long regexes that should be constants
+- `rubocop-claude init` command for project setup
+- StandardRB plugin support via lint_roller

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nicholas Marshall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,267 @@
+# rubocop-claude
+
+"CUT IT OUT, CLAUDE." doesn't work.
+
+"Oh look, somehow you failed linting, how rough for you, better fix it! no naps!" does.
+
+AI assistants are useful and can write functional code. They also:
+
+- Love to nap on giant hoards of old code.
+- Build defensive code fortresses EVERYWHERE.
+- Handle explosive errors by adding "okay but what if we just ignored that! look, fixed it!"
+- Add comments everywhere and then pretend you wrote them. 😒
+- Reach for the world's least common Unicode symbols and then get confused when you say "stop it."
+
+This gem tries to make them cut that out.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'rubocop-claude', require: false
+```
+
+Then run:
+
+```bash
+bundle install
+rubocop-claude init
+```
+
+The `init` command will:
+
+1. Create `.claude/linting.md` with instructions for AI assistants
+2. Add `rubocop-claude` to your `.standard.yml` or `.rubocop.yml`
+
+## Manual Setup
+
+Add to `.standard.yml` or `.rubocop.yml`:
+
+```yaml
+plugins:
+  - rubocop-claude
+```
+
+## Cops
+
+| Cop | Description |
+| ----- | ------------- |
+| `Claude/NoFancyUnicode` | Flags emoji and fancy Unicode (curly quotes, em-dashes) |
+| `Claude/TaggedComments` | Requires attribution on TODO/FIXME/NOTE comments |
+| `Claude/NoCommentedCode` | Detects commented-out code blocks |
+| `Claude/NoBackwardsCompatHacks` | Catches dead code preserved "for compatibility" |
+| `Claude/NoOverlyDefensiveCode` | Flags `rescue nil`, excessive `&.` chains, defensive nil checks |
+| `Claude/ExplicitVisibility` | Enforces consistent visibility style (grouped or modifier) |
+| `Claude/MysteryRegex` | Flags long regexes that should be extracted to constants |
+| `Claude/NoHardcodedLineNumbers` | Flags hardcoded line numbers that become stale |
+
+## Configuration
+
+All cops are enabled by default. Configure in `.rubocop.yml`:
+
+```yaml
+Claude/NoFancyUnicode:
+  AllowInStrings: true  # Allow emoji in user-facing strings
+  AllowedUnicode:
+    - "\u2192"  # Allow specific characters
+
+Claude/TaggedComments:
+  Keywords:
+    - TODO
+    - FIXME
+    - NOTE
+    - HACK
+
+Claude/NoCommentedCode:
+  MinLines: 2  # Only flag multi-line blocks (set to 1 for single lines)
+  AllowKeep: true  # Allow KEEP [@handle]: comments to preserve code
+
+Claude/NoOverlyDefensiveCode:
+  MaxSafeNavigationChain: 1  # Flag 2+ chained &. operators
+  AddSafeNavigator: false  # Autocorrect to &. instead of direct call
+
+Claude/ExplicitVisibility:
+  EnforcedStyle: grouped  # or 'modifier' for `private def foo`
+
+Claude/MysteryRegex:
+  MaxLength: 25
+
+Claude/NoHardcodedLineNumbers:
+  CheckComments: true   # Check comments (default: true)
+  CheckStrings: true    # Check string literals (default: true)
+```
+
+## Why These Cops?
+
+### NoFancyUnicode
+
+Me: "Okay, let's log that success."
+Claude: A RAINBOW OF OBSCURE SYMBOLS EMERGES FROM THE MISTS.
+
+```ruby
+# bad
+puts "Deployment successful! 🚀"
+logger.info "Task completed ✅"
+
+# good
+puts "Deployment successful!"
+logger.info "Task completed"
+```
+
+### TaggedComments
+
+"You added a comment, and it looks like I added a comment, and that comment is wrong."
+
+```ruby
+# bad
+# TODO: fix this later
+
+# good
+# TODO: [@username] fix this later
+```
+
+### NoCommentedCode
+
+"No hoarding."
+
+```ruby
+# bad
+# def old_implementation
+#   do_something_outdated
+# end
+
+# good - just delete it
+```
+
+### NoBackwardsCompatHacks
+
+"NO HOARDING."
+
+```ruby
+# bad
+_old_value = previous_calculation  # keeping for reference
+OldName = NewName  # backwards compatibility
+
+# good - delete it
+```
+
+### NoOverlyDefensiveCode
+
+"YOU ARE BUILDING A DOOMSDAY BUNKER FOR A METHOD THAT CAN'T FAIL, CLAUDE."
+
+```ruby
+# bad
+result = dangerous_call rescue nil
+user&.profile&.settings&.value
+user && user.name
+
+# good
+result = dangerous_call
+user.profile.settings.value
+user.name
+```
+
+### ExplicitVisibility
+
+"The solution is **NOT** 'make all the private methods visible,' bud."
+
+```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
+```
+
+### MysteryRegex
+
+"I have no idea what your 300-character regex does, Claude, because you dumped that on the screen, said 'okay cool fixed' and then got distracted."
+
+```ruby
+# bad
+if input.match?(/\A[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z/)
+
+# good
+EMAIL_PATTERN = /\A[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z/
+if input.match?(EMAIL_PATTERN)
+```
+
+### NoHardcodedLineNumbers
+
+"That line reference is wrong, Claude. The code moved."
+
+```ruby
+# bad
+# see line 42 for details
+# Error at foo.rb:123
+raise "check line 55"
+
+# good
+# see #validate_input for details
+# Error in FooError class
+raise "check validate_input method"
+```
+
+## Suggested RuboCop Defaults
+
+`rubocop-claude init` also enables some defaults in Rubocop that are aimed at keeping AI coders from getting weird with their Ruby. Full config with rationale in `config/default.yml`.
+
+| Cop | Setting | Why |
+| ----- | --------- | ----- |
+| `Style/DisableCopsWithinSourceCodeDirective` | Enabled | AI "fixes" linting by disabling cops. No. |
+| `Layout/ClassStructure` | Enabled | AI scatters methods randomly. Enforce order. |
+| `Style/CommentAnnotation` | `RequireColon: true` | Works with TaggedComments. |
+| `Lint/Debugger` | Enabled | AI leaves `binding.pry` in code. |
+| `Layout/MultilineMethodCallIndentation` | `indented` | Leading dot, 2-space indent. |
+| `Style/SafeNavigation` | `MaxChainLength: 1` | Complements NoOverlyDefensiveCode. |
+| `Metrics/CyclomaticComplexity` | `Max: 7` | Flag spaghetti logic. |
+| `Metrics/AbcSize` | `Max: 17` | Flag bloated methods. |
+| `Metrics/MethodLength` | `Max: 10` | AI writes 80-line methods. 10 is plenty. |
+| `Metrics/ClassLength` | `Max: 150` | Catches god classes. |
+| `Metrics/ParameterLists` | `Max: 5` | Too many params = needs refactoring. |
+| `Style/GuardClause` | Enabled | Early returns > nested conditionals. |
+| `Style/RedundantReturn` | Enabled | Ruby returns last expression. |
+| `Style/MutableConstant` | `strict` | Always `.freeze` constants. |
+| `Lint/UnusedMethodArgument` | Enabled | Dead params = dead code. |
+| `Style/NestedTernaryOperator` | Enabled | `a ? (b ? c : d) : e` is unreadable. |
+| `Style/OptionalBooleanParameter` | Enabled | `foo(data, true)` - what's true mean? |
+| `Naming/MethodParameterName` | `MinNameLength: 2` | No `x`, `y`, `z` params. Use real names. |
+| `Style/ParallelAssignment` | Enabled | One assignment per line. |
+
+**Not enabled:** `Lint/SuppressedException` and `Style/RescueModifier` - our `NoOverlyDefensiveCode` covers these with a unified "trust internal code" message.
+
+## Claude Integration
+
+`rubocop-claude init` will add files to .claude (or elsewhere if you provide it with a path).
+
+These files are a bunch of reference docs for AI agents to gnaw on when they're asked to think about linting. It does not change any of your other config, and it does not try to integrate with the rest of your setup. It's just providing a structured starting point for getting AI agents to lint more effectively.
+
+## WHAT THIS DOES NOT DO
+
+This isn't a subsitute for reviewing your code or monitoring AI assistants. Static analysis is a wonderful tool for wrangling Ai coders, but it does not replace reviewing and monitoring changes.
+
+Trying to force static analysis tools to fully handle every single edge case is silly, and trying to make these weird, enthusiastic pattern recognition engines get everything right on the first try isn't going to work. What we're trying to do is give tools like Claude a way to efficiently remember that they shouldn't be making weird decisions, and that they should make good decisions instead.
+
+We can't always prevent AI tools from charging off in weird directions, but we CAN scatter rakes in their way and make them stop and think. This adds more rakes.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/config/default.yml

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+#
+# Default configuration for rubocop-claude cops.
+# This file is loaded automatically by the plugin.
+
+AllCops:
+  NewCops: disable
+  SuggestExtensions: false
+
+# =============================================================================
+# Existing RuboCop Cops - Enable/Configure
+# =============================================================================
+
+# Warn on inline rubocop:disable comments - fix the issue instead
+Style/DisableCopsWithinSourceCodeDirective:
+  Enabled: true
+  AllowedCops: []
+
+# Enforce consistent class structure ordering
+Layout/ClassStructure:
+  Enabled: true
+  ExpectedOrder:
+    - module_inclusion
+    - constants
+    - public_class_methods
+    - initializer
+    - public_methods
+    - protected_methods
+    - private_methods
+  Categories:
+    module_inclusion:
+      - include
+      - prepend
+      - extend
+
+# Enforce TODO/FIXME format with uppercase and colon
+Style/CommentAnnotation:
+  Enabled: true
+  Keywords:
+    - TODO
+    - FIXME
+    - NOTE
+    - HACK
+    - OPTIMIZE
+    - REVIEW
+  RequireColon: true
+
+# No debug statements left in code
+Lint/Debugger:
+  Enabled: true
+
+# Method chaining with indented style (leading dot, 2-space indent)
+Layout/MultilineMethodCallIndentation:
+  Enabled: true
+  EnforcedStyle: indented
+
+# Flag defensive .try calls and excessive && nil checks
+Style/SafeNavigation:
+  Enabled: true
+  AllowedMethods: []  # Don't allow try/try! - use &. or trust the code
+  MaxChainLength: 1   # Consistent with NoOverlyDefensiveCode
+
+# Flag overly complex methods
+Metrics/CyclomaticComplexity:
+  Enabled: true
+  Max: 7
+
+# Flag bloated methods
+Metrics/AbcSize:
+  Enabled: true
+  Max: 17
+
+# AI writes 80-line methods without blinking. 10 is plenty.
+# CountAsOne prevents array literals from inflating the count.
+Metrics/MethodLength:
+  Enabled: true
+  Max: 10
+  CountComments: false
+  CountAsOne: [array, hash, heredoc, method_call]
+
+# AI creates god classes. 150 lines is generous but catches the worst offenders.
+Metrics/ClassLength:
+  Enabled: true
+  Max: 150
+  CountComments: false
+  CountAsOne: [array, hash, heredoc, method_call]
+
+# More than 5 params? Use an options hash or a parameter object.
+Metrics/ParameterLists:
+  Enabled: true
+  Max: 5
+  CountKeywordArgs: true
+  MaxOptionalParameters: 3
+
+# AI nests 5 levels deep instead of using early returns.
+# Guard clauses are more readable: `return unless valid?` at the top.
+Style/GuardClause:
+  Enabled: true
+  MinBodyLength: 1
+
+# Ruby returns the last expression. Explicit `return` on the last line is noise.
+# AllowMultipleReturnValues permits `return a, b` for tuple returns.
+Style/RedundantReturn:
+  Enabled: true
+  AllowMultipleReturnValues: true
+
+# ITEMS = ['a', 'b'] is mutable. Always .freeze constants.
+# EnforcedStyle: strict requires freeze even for literals.
+Style/MutableConstant:
+  Enabled: true
+  EnforcedStyle: strict
+
+# Dead parameters after refactoring. Remove them or prefix with _ if interface requires.
+Lint/UnusedMethodArgument:
+  Enabled: true
+  AllowUnusedKeywordArguments: false
+  IgnoreEmptyMethods: true
+  IgnoreNotImplementedMethods: true
+
+# a ? (b ? c : d) : e is unreadable. Use if/else.
+Style/NestedTernaryOperator:
+  Enabled: true
+
+# def process(data, include_extras = false) -> callers see process(data, true).
+# What does true mean? Use keyword args: process(data, include_extras: true).
+Style/OptionalBooleanParameter:
+  Enabled: true
+
+# def calculate(a, b, c) is cryptic. Use real names.
+# Common 2-letter names (id, db, io) are allowed. x, y, z are forbidden.
+Naming/MethodParameterName:
+  Enabled: true
+  MinNameLength: 2
+  AllowedNames: [id, ip, to, by, on, in, at, io, db]
+  ForbiddenNames: [x, y, z]
+
+# a, b, c = 1, 2, 3 is harder to read than three separate lines.
+# Exception: x, y = y, x for swaps is fine (cop handles this).
+Style/ParallelAssignment:
+  Enabled: true
+
+# =============================================================================
+# Custom Claude Cops
+# =============================================================================
+
+Claude/NoFancyUnicode:
+  Enabled: true
+  Description: "Avoid fancy Unicode. Use standard ASCII or add to AllowedUnicode."
+  AllowedUnicode: []
+  AllowInStrings: false
+  AllowInComments: false
+  Exclude:
+    - '**/no_fancy_unicode.rb'
+    - '**/no_fancy_unicode_spec.rb'
+
+Claude/TaggedComments:
+  Enabled: true
+  Description: "Comments need attribution. Use format: # TAG: [@handle] description"
+  Keywords:
+    - TODO
+    - FIXME
+    - NOTE
+    - HACK
+    - OPTIMIZE
+    - REVIEW
+
+Claude/NoCommentedCode:
+  Enabled: true
+  Description: "Delete commented-out code instead of leaving it. Version control preserves history."
+  MinLines: 1
+  AllowKeep: true
+
+Claude/NoBackwardsCompatHacks:
+  Enabled: true
+  Description: "Delete dead code. Don't preserve it for backwards compatibility."
+  CheckUnderscoreAssignments: false
+
+Claude/NoOverlyDefensiveCode:
+  Enabled: true
+  Description: "Trust internal code. Remove unnecessary defensive patterns."
+  MaxSafeNavigationChain: 1
+  AddSafeNavigator: false
+
+Claude/ExplicitVisibility:
+  Enabled: true
+  Description: "Use explicit visibility. Group private methods under `private` keyword."
+  EnforcedStyle: grouped
+
+Claude/MysteryRegex:
+  Enabled: true
+  Description: "Extract long regex to a named constant. Complex patterns deserve descriptive names."
+  MaxLength: 25
+
+Claude/NoHardcodedLineNumbers:
+  Enabled: true
+  Description: "Avoid hardcoded line numbers. They become stale when code shifts."
+  CheckComments: true
+  CheckStrings: true
+  MinLineNumber: 1
+  Exclude:
+    - '**/no_hardcoded_line_numbers.rb'
+    - '**/no_hardcoded_line_numbers_spec.rb'

data/exe/rubocop-claude

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'rubocop_claude/cli'
+
+RubocopClaude::CLI.run(ARGV)

data/lib/rubocop/cop/claude/explicit_visibility.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Claude
+      # Enforces visibility keyword placement style.
+      #
+      # The grouped style (`private` on its own line) is the dominant Ruby
+      # convention. The modifier style (`private def foo`) is less common.
+      #
+      # @example EnforcedStyle: grouped (default)
+      #   # bad
+      #   private def foo; end
+      #
+      #   # good
+      #   private
+      #   def foo; end
+      #
+      # @example EnforcedStyle: modifier
+      #   # bad
+      #   private
+      #   def foo; end
+      #
+      #   # good
+      #   private def foo; end
+      #
+      class ExplicitVisibility < Base
+        extend AutoCorrector
+
+        VISIBILITY_METHODS = %i[private protected public].freeze
+
+        MSG_USE_MODIFIER = 'Use explicit visibility. Place `%<visibility>s` before the method definition.'
+        MSG_USE_GROUPED = 'Use grouped visibility. Move method to `%<visibility>s` section.'
+
+        def on_send(node)
+          return unless standalone_visibility?(node)
+          return unless enforced_style == :modifier
+
+          methods = find_following_methods(node)
+          return if methods.empty?
+
+          add_offense(node, message: format(MSG_USE_MODIFIER, visibility: node.method_name)) do |corrector|
+            autocorrect_to_modifier(corrector, node, methods)
+          end
+        end
+
+        def on_def(node)
+          return unless enforced_style == :grouped
+          return unless inline_visibility?(node.parent)
+
+          visibility = node.parent.method_name
+          add_offense(node.parent, message: format(MSG_USE_GROUPED, visibility: visibility)) do |corrector|
+            autocorrect_to_grouped(corrector, node, node.parent, visibility)
+          end
+        end
+
+        private
+
+        def enforced_style
+          @enforced_style ||= cop_config.fetch('EnforcedStyle', 'grouped').to_sym
+        end
+
+        def standalone_visibility?(node)
+          node.send_type? && VISIBILITY_METHODS.include?(node.method_name) &&
+            node.receiver.nil? && node.arguments.empty?
+        end
+
+        def inline_visibility?(node)
+          node&.send_type? && %i[private protected].include?(node.method_name) &&
+            node.arguments.size == 1
+        end
+
+        def find_following_methods(visibility_node)
+          siblings = visibility_node.parent.children
+          idx = siblings.index(visibility_node)
+          siblings[(idx + 1)..].take_while { |s| !standalone_visibility?(s) }.select(&:def_type?)
+        end
+
+        def autocorrect_to_modifier(corrector, visibility_node, methods)
+          corrector.remove(range_with_newlines(visibility_node))
+          methods.each { |m| corrector.insert_before(m, "#{visibility_node.method_name} ") }
+        end
+
+        def autocorrect_to_grouped(corrector, def_node, send_node, visibility)
+          class_node = def_node.each_ancestor(:class, :module).first
+          return unless class_node
+
+          insert_method_in_section(corrector, class_node, def_node, visibility)
+          corrector.remove(range_with_newlines(send_node))
+        end
+
+        def insert_method_in_section(corrector, class_node, def_node, visibility)
+          section = find_visibility_section(class_node, visibility)
+          ind = indent(def_node)
+
+          if section
+            pos = last_method_in_section(section)&.source_range || section.source_range
+            corrector.insert_after(pos, "\n\n#{ind}#{def_node.source}")
+          else
+            corrector.insert_before(class_node.loc.end.begin,
+              "\n\n#{ind}#{visibility}\n\n#{ind}#{def_node.source}\n")
+          end
+        end
+
+        def find_visibility_section(class_node, visibility)
+          class_node.body.each_child_node(:send).find { |n| n.method_name == visibility && n.arguments.empty? }
+        end
+
+        def last_method_in_section(visibility_node)
+          siblings = visibility_node.parent.children
+          idx = siblings.index(visibility_node)
+          siblings[(idx + 1)..].take_while { |s| !standalone_visibility?(s) }
+            .reverse.find(&:def_type?)
+        end
+
+        def indent(node)
+          node.source_range.source_line[/\A\s*/]
+        end
+
+        def range_with_newlines(node)
+          source = processed_source.buffer.source
+          begin_pos = adjust_begin_pos(node.source_range.begin_pos, source)
+          end_pos = adjust_end_pos(node.source_range.end_pos, source)
+          Parser::Source::Range.new(processed_source.buffer, begin_pos, end_pos)
+        end
+
+        def adjust_begin_pos(pos, source)
+          pos -= 1 while pos.positive? && source[pos - 1] =~ /[ \t]/
+          pos -= 1 if pos.positive? && source[pos - 1] == "\n"
+          pos
+        end
+
+        def adjust_end_pos(pos, source)
+          (source[pos] == "\n") ? pos + 1 : pos
+        end
+      end
+    end
+  end
+end