rubocop-claude 0.1.0

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Claude
+      # Enforces that long regexes are extracted to named constants.
+      #
+      # Complex regexes are hard to understand at a glance. Extracting them
+      # to a named constant with a descriptive name (and optionally a comment)
+      # makes the intent clear.
+      #
+      # @example MaxLength: 25 (default)
+      #   # bad - what does this match?
+      #   text.match?(/\A[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z/)
+      #
+      #   # good - intent is clear from the name
+      #   EMAIL_PATTERN = /\A[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z/
+      #   text.match?(EMAIL_PATTERN)
+      #
+      #   # good - short regexes are fine inline
+      #   text.match?(/\A\d+\z/)
+      #
+      class MysteryRegex < Base
+        MSG = 'Extract long regex to a named constant. ' \
+              'Complex patterns deserve descriptive names.'
+
+        def on_regexp(node)
+          return if node.content.length <= max_length
+          return if inside_constant_assignment?(node)
+
+          add_offense(node)
+        end
+
+        private
+
+        def max_length
+          @max_length ||= cop_config.fetch('MaxLength', 25)
+        end
+
+        def inside_constant_assignment?(node)
+          node.each_ancestor(:casgn).any?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module RuboCop
+  module Cop
+    module Claude
+      # Detects patterns that preserve dead code for backwards compatibility.
+      #
+      # AI assistants often add "helpful" compatibility shims instead of
+      # cleanly removing code. This creates confusion and maintenance burden.
+      # If code is unused, delete it completely.
+      #
+      # == Detection Philosophy
+      #
+      # This cop catches *self-documented* compatibility hacks - patterns where
+      # the code includes comments like "for backwards compatibility" or markers
+      # like "# removed:". It won't catch silent compat hacks without comments.
+      #
+      # This is intentional. The goal is teaching, not comprehensive detection.
+      # When the cop fires, it's a teaching moment - the AI reads the guidance
+      # and learns the principle "don't preserve dead code." Over time, this
+      # shapes better habits even for cases we can't detect.
+      #
+      # @example Dead code marker comments (always flagged)
+      #   # bad
+      #   # removed: def old_method; end
+      #   # deprecated: use new_method instead
+      #   # legacy: keeping for backwards compat
+      #   # backwards compatibility: aliased from OldClass
+      #
+      #   # good - just delete the comment entirely
+      #
+      # @example Constant re-exports with compat comments (always flagged)
+      #   # bad
+      #   OldName = NewName  # for backwards compatibility
+      #
+      #   # bad
+      #   # deprecated alias
+      #   LegacyClass = ModernClass
+      #
+      #   # good - delete the alias, update callers
+      #
+      # @example CheckUnderscoreAssignments: true (optional, off by default)
+      #   # bad - underscore prefix to silence unused variable warning
+      #   _old_method = :deprecated
+      #   _unused = previous_value
+      #
+      #   # good - delete the line entirely if not needed
+      #
+      #   # ok - single underscore in blocks is idiomatic Ruby
+      #   hash.each { |_, v| puts v }
+      #
+      class NoBackwardsCompatHacks < Base
+        MSG_UNDERSCORE = "Delete dead code. Don't use underscore prefix to preserve unused values."
+        MSG_REEXPORT = "Delete dead code. Don't re-export removed constants for backwards compatibility."
+        MSG_COMMENT = "Delete dead code. Don't leave removal markers in comments."
+
+        # Comments that indicate removed/deprecated code being preserved
+        DEAD_CODE_COMMENT_PATTERN = /\A#\s*(?:removed|deprecated|legacy|backwards?\s*compat(?:ibility)?|for\s+compat(?:ibility)?|compat(?:ibility)?\s+shim):/i
+
+        # Patterns for detecting backwards-compatibility comments near constant assignments
+        COMPAT_KEYWORD_PATTERN = /\b(?:backwards?\s*)?compat(?:ibility)?\b/i
+        LEGACY_REFERENCE_PATTERN = /\bfor\s+(?:legacy|old|previous)\b/i
+        DEPRECATED_PATTERN = /\bdeprecated\b/i
+        ALIAS_PATTERN = /\balias\s+for\b/i
+
+        # Assignment to underscore-prefixed variables (not just _ which is idiomatic for unused block args)
+        UNDERSCORE_ASSIGNMENT_MSG = 'Assignment to underscore-prefixed variable'
+
+        def on_new_investigation
+          build_compat_comment_index
+          check_dead_code_comments
+        end
+
+        # Detect _unused = value patterns (optional, off by default)
+        def on_lvasgn(node)
+          return unless check_underscore_assignments?
+
+          var_name = node.children[0].to_s
+          return unless var_name.start_with?('_') && var_name.length > 1
+
+          # Allow in block parameters context (common Ruby idiom)
+          return if in_block_arguments?(node)
+
+          add_offense(node, message: MSG_UNDERSCORE)
+        end
+
+        # Detect Constant = OtherConstant patterns with backwards compat comments
+        def on_casgn(node)
+          # Check for re-export patterns: OldName = NewName
+          _, _, value = *node
+          return unless value.const_type?
+
+          # Look for backwards compatibility indicators in nearby comments
+          return unless has_compat_comment_nearby?(node)
+
+          add_offense(node, message: MSG_REEXPORT)
+        end
+
+        private
+
+        def build_compat_comment_index
+          @compat_comment_lines = Set.new
+          processed_source.comments.each do |comment|
+            @compat_comment_lines << comment.location.line if compat_comment?(comment.text)
+          end
+        end
+
+        def check_dead_code_comments
+          processed_source.comments.each do |comment|
+            next unless comment.text.match?(DEAD_CODE_COMMENT_PATTERN)
+
+            add_offense(comment, message: MSG_COMMENT)
+          end
+        end
+
+        def in_block_arguments?(node)
+          node.each_ancestor(:block, :numblock).any?
+        end
+
+        def has_compat_comment_nearby?(node)
+          line = node.location.line
+          @compat_comment_lines.include?(line) || @compat_comment_lines.include?(line - 1)
+        end
+
+        def compat_comment?(text)
+          COMPAT_KEYWORD_PATTERN.match?(text) ||
+            LEGACY_REFERENCE_PATTERN.match?(text) ||
+            DEPRECATED_PATTERN.match?(text) ||
+            ALIAS_PATTERN.match?(text)
+        end
+
+        def check_underscore_assignments?
+          @check_underscore_assignments ||= cop_config.fetch('CheckUnderscoreAssignments', false)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Claude
+      # Detects commented-out code blocks.
+      #
+      # Commented-out code is technical debt. It clutters the codebase,
+      # confuses readers, and version control already preserves history.
+      # Delete it instead of commenting it out.
+      #
+      # @example Default (flags consecutive commented code)
+      #   # bad
+      #   # def old_method
+      #   #   do_something
+      #   # end
+      #
+      # @example AllowKeep: true (default) - explicit exceptions with attribution
+      #   # good - KEEP comment with attribution
+      #   # KEEP [@username]: Rollback path, remove after 2025-06
+      #   # def legacy_method
+      #   #   old_implementation
+      #   # end
+      #
+      # @safety
+      #   Autocorrection deletes commented code. Review changes to ensure
+      #   no important context is lost. Version control preserves history.
+      #
+      class NoCommentedCode < Base
+        extend AutoCorrector
+
+        MSG = 'Delete commented-out code instead of leaving it. Version control preserves history.'
+
+        # Patterns that strongly suggest commented-out Ruby code
+        CODE_PATTERNS = [
+          /\A\s*def\s+\w+/,                                     # Method definitions
+          /\A\s*(?:class|module)\s+[A-Z]/,                      # Class/module definitions
+          /\A\s*(?:if|unless|case|while|until|begin|end)\b/,   # Control flow
+          /\A\s*\w+\.\w+[!(?)]*\s*(?:\(|do\b|$)/,              # Method calls with receiver
+          /\A\s*[a-z_]\w*[!(?)]\s*$/,                           # Bare method calls with ! or ?
+          /\A\s*[a-z_]\w+\s*$/,                                 # Bare identifiers
+          %r{\A\s*(?:@{1,2}|\$)?\w+\s*[+\-*/]?=\s*.+},         # Assignments
+          /\A\s*(?:return|raise)\b/,                            # Return/raise statements
+          /\A\s*require(?:_relative)?\s+['"]/,                  # Require statements
+          /\A\s*\.\w+/,                                         # Method chains
+          /\A\s*[A-Z][A-Z0-9_]*\s*=/                            # Constants
+        ].freeze
+
+        # Patterns that suggest prose, not code
+        NON_CODE_PATTERNS = [
+          /\A\s*(?:TODO|FIXME|NOTE|HACK|OPTIMIZE|REVIEW)\b/i,  # Annotations
+          /\A\s*[A-Z][a-z]+(?:\s+[a-z]+){3,}/,                 # Prose sentences
+          %r{\A\s*https?://},                                   # URLs
+          /\A\s*rubocop:/,                                      # Rubocop directives
+          /\A\s*@(?:param|return|raise|see|note|deprecated)/   # YARD tags
+        ].freeze
+
+        YARD_EXAMPLE_START = /\A#\s*@example/
+        KEEP_PATTERN = /\A#\s*KEEP\s+\[(?:[\w\s]+-\s*)?@[\w-]+\]:/i
+
+        def on_new_investigation
+          @min_lines = cop_config.fetch('MinLines', 1)
+          @state = initial_state
+
+          processed_source.comments.each { |comment| process_comment(comment) }
+          report_pending_comments
+        end
+
+        private
+
+        def initial_state
+          {consecutive: [], in_yard_example: false, preceded_by_keep: false}
+        end
+
+        def process_comment(comment)
+          return if inline_comment?(comment)
+
+          raw_text = comment.text
+          return handle_yard_example_start if raw_text.match?(YARD_EXAMPLE_START)
+          return handle_keep_comment if allow_keep? && raw_text.match?(KEEP_PATTERN)
+          return if skip_yard_example_content?(raw_text)
+
+          accumulate_or_report(comment)
+        end
+
+        def handle_yard_example_start
+          report_and_reset
+          @state[:in_yard_example] = true
+        end
+
+        def handle_keep_comment
+          report_and_reset
+          @state[:preceded_by_keep] = true
+        end
+
+        def report_and_reset
+          report_pending_comments
+          @state[:consecutive] = []
+          @state[:preceded_by_keep] = false
+        end
+
+        def skip_yard_example_content?(raw_text)
+          return false unless @state[:in_yard_example]
+          return true if yard_example_content?(raw_text)
+
+          @state[:in_yard_example] = false
+          false
+        end
+
+        def accumulate_or_report(comment)
+          content = extract_content(comment)
+
+          if looks_like_code?(content)
+            @state[:consecutive] << comment
+          else
+            report_pending_comments
+            @state[:preceded_by_keep] = false
+          end
+        end
+
+        def report_pending_comments
+          comments = @state[:consecutive]
+          return if comments.length < @min_lines
+
+          # KEEP protection - clear without reporting
+          if @state[:preceded_by_keep]
+            @state[:consecutive] = []
+            return
+          end
+
+          add_offense(comments.first) { |corrector| remove_comment_block(corrector, comments) }
+          @state[:consecutive] = []
+        end
+
+        def yard_example_content?(raw_text)
+          return false if raw_text.match?(/\A#\s*@/)
+          return false if raw_text.match?(/\A#[^ ]/)
+          return false if raw_text.match?(/\A#\s?\S/) && !raw_text.match?(/\A#\s{2,}/)
+
+          raw_text.match?(/\A#\s{2,}/) || raw_text.match?(/\A#\s*$/)
+        end
+
+        def inline_comment?(comment)
+          line = processed_source.lines[comment.location.line - 1]
+          line[0...comment.location.column].match?(/\S/)
+        end
+
+        def extract_content(comment)
+          comment.text.sub(/\A#\s?/, '')
+        end
+
+        def looks_like_code?(content)
+          return false if content.strip.empty?
+          return false if NON_CODE_PATTERNS.any? { |p| content.match?(p) }
+
+          CODE_PATTERNS.any? { |p| content.match?(p) }
+        end
+
+        def remove_comment_block(corrector, comments)
+          source = comments.first.location.expression.source_buffer
+          begin_pos = source.line_range(comments.first.location.line).begin_pos
+          end_pos = calculate_end_pos(source, comments.last.location.line)
+
+          corrector.remove(Parser::Source::Range.new(source, begin_pos, end_pos))
+        end
+
+        def calculate_end_pos(source, last_line)
+          next_line = last_line + 1
+          if next_line <= source.last_line
+            source.line_range(next_line).begin_pos
+          else
+            source.line_range(last_line).end_pos
+          end
+        end
+
+        def allow_keep?
+          @allow_keep ||= cop_config.fetch('AllowKeep', true)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Claude
+      # Detects non-standard Unicode characters that may cause issues.
+      #
+      # Flags characters outside the standard set of language characters
+      # and keyboard symbols. This catches emoji, fancy typography (curly
+      # quotes, em-dashes), and mathematical symbols that look like ASCII
+      # operators but aren't.
+      #
+      # The allowed character set is:
+      # - Letters from any script (Latin, Chinese, Japanese, Cyrillic, etc.)
+      # - Numbers from any script
+      # - Combining marks (for accented characters)
+      # - Standard ASCII printable characters (keyboard symbols)
+      # - Whitespace
+      #
+      # @safety
+      #   This cop's autocorrection removes the offending character, which
+      #   may change the meaning of strings. Review the changes carefully.
+      #
+      # @example AllowInStrings: false (default)
+      #   # bad - emoji
+      #   puts "Success! 🎉"
+      #
+      #   # bad - fancy curly quotes
+      #   puts "Hello world"
+      #
+      #   # bad - mathematical symbols instead of ASCII
+      #   return false if x ≠ y
+      #
+      #   # bad - em-dash instead of double-hyphen
+      #   # See section 3 — Implementation
+      #
+      #   # good - standard ASCII
+      #   puts "Success!"
+      #   puts "Hello world"
+      #   return false if x != y
+      #   # See section 3 -- Implementation
+      #
+      #   # good - international text
+      #   greeting = "你好"
+      #   message = "Привет мир"
+      #   text = "café"
+      #
+      # @example AllowInStrings: true
+      #   # bad - still catches in comments
+      #   # TODO: Fix bug 🐛
+      #
+      #   # bad - still catches in symbols
+      #   status = :"done_✅"
+      #
+      #   # good - strings can have fancy unicode
+      #   puts "Success! 🎉"
+      #   message = "Use → for arrows"
+      #
+      # @example AllowedUnicode: ['→', '←', '•']
+      #   # bad - not in allowed list
+      #   puts "Check: ✅"
+      #
+      #   # good - in allowed list
+      #   # Click → to continue
+      #   puts "• Item one"
+      #
+      # @example Allowed character set
+      #   \p{L}       # Letters (any script: Latin, Chinese, Japanese, Cyrillic, etc.)
+      #   \p{M}       # Marks (combining diacritics for accented characters)
+      #   \p{N}       # Numbers (any script)
+      #   \x20-\x7E   # ASCII printable (space through tilde - all keyboard symbols)
+      #   \t\n\r      # Whitespace
+      #
+      # @see https://www.compart.com/en/unicode/category
+      class NoFancyUnicode < Base
+        extend AutoCorrector
+
+        MSG = 'Avoid fancy Unicode `%<char>s` (U+%<codepoint>s). ' \
+              'Use standard ASCII or add to AllowedUnicode.'
+
+        ALLOWED_PATTERN = /[\p{L}\p{M}\p{N}\x20-\x7E\t\n\r]/
+
+        def on_new_investigation
+          process_comments unless allow_in_comments?
+        end
+
+        def on_str(node)
+          return if allow_in_strings?
+
+          check_for_fancy_unicode(node, node.value)
+        end
+
+        def on_dstr(node)
+          return if allow_in_strings?
+
+          node.each_child_node(:str) do |str_node|
+            check_for_fancy_unicode(str_node, str_node.value)
+          end
+        end
+
+        def on_sym(node)
+          check_for_fancy_unicode(node, node.value.to_s)
+        end
+
+        def on_dsym(node)
+          node.each_child_node(:str) do |str_node|
+            check_for_fancy_unicode(str_node, str_node.value)
+          end
+        end
+
+        private
+
+        def process_comments
+          processed_source.comments.each do |comment|
+            fancy_chars = find_fancy_unicode(comment.text)
+            next if fancy_chars.empty?
+
+            # Report first char but fix ALL chars in one correction
+            add_offense(comment, message: format_message(fancy_chars.first)) do |corrector|
+              corrector.replace(comment, clean_text(comment.text, fancy_chars))
+            end
+          end
+        end
+
+        def check_for_fancy_unicode(node, value)
+          fancy_chars = find_fancy_unicode(value)
+          return if fancy_chars.empty?
+
+          # Report first char but fix ALL chars in one correction
+          add_offense(node, message: format_message(fancy_chars.first)) do |corrector|
+            corrector.replace(node, clean_text(node.source, fancy_chars))
+          end
+        end
+
+        def clean_text(text, chars)
+          result = text.dup
+          Array(chars).each { |char| result.gsub!(char, '') }
+          result
+            .gsub(/_+\z/, '')          # Remove trailing underscores at end
+            .gsub(/_+(['"])/, '\1')    # Remove trailing underscores before closing quote
+            .gsub(/\s{2,}/, ' ')       # Collapse multiple spaces to single space
+            .gsub(/\s+(['"])/, '\1')   # Remove trailing space before closing quote
+            .gsub(/\s+\z/, '')         # Remove trailing whitespace at end
+        end
+
+        def find_fancy_unicode(text)
+          # Find all characters that don't match the allowed pattern
+          fancy = text.chars.reject { |char| char.match?(ALLOWED_PATTERN) }
+
+          # Filter out explicitly allowed unicode characters
+          fancy.reject { |char| allowed_unicode.include?(char) }.uniq
+        end
+
+        def format_message(char)
+          codepoint = char.ord.to_s(16).upcase.rjust(4, '0')
+          format(MSG, char: char, codepoint: codepoint)
+        end
+
+        def allow_in_strings?
+          @allow_in_strings ||= cop_config.fetch('AllowInStrings', false)
+        end
+
+        def allow_in_comments?
+          @allow_in_comments ||= cop_config.fetch('AllowInComments', false)
+        end
+
+        def allowed_unicode
+          @allowed_unicode ||= Array(cop_config.fetch('AllowedUnicode', [])).freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Claude
+      # Detects hardcoded line numbers in comments and strings.
+      #
+      # Hardcoded line numbers become stale when code shifts. References
+      # like "see line 42" or "foo.rb:123" break silently as the codebase
+      # evolves. Use method names, class names, or other stable references.
+      #
+      # @example CheckComments: true (default)
+      #   # bad
+      #   # see line 42 for details
+      #   # Error defined at foo.rb:123
+      #   # Check L42 for the fix
+      #   # at line 15, we handle errors
+      #
+      #   # good
+      #   # see #validate_input for details
+      #   # Error defined in FooError class
+      #   # Check the validate_input method for the fix
+      #
+      # @example CheckStrings: true (default)
+      #   # bad
+      #   raise "Error at line 42"
+      #   expect(error.message).to include("foo.rb:55")
+      #
+      #   # good
+      #   raise "Error in validate_input"
+      #   expect(error.message).to include("validate_input")
+      #
+      # @example MinLineNumber: 1 (default)
+      #   # Only flags line numbers >= MinLineNumber
+      #   # With MinLineNumber: 10, "line 5" would not be flagged
+      #
+      class NoHardcodedLineNumbers < Base
+        MSG = 'Avoid hardcoded line number `%<line>s`. ' \
+              'Line numbers shift when code changes.'
+
+        # Patterns that look like line number references
+        # Order matters - more specific patterns first
+        LINE_PATTERNS = [
+          /\bL(\d+)\b/,                       # "L42" (GitHub style)
+          /\.(?:rb|erb|rake|ru):(\d+)\b/,     # "foo.rb:42", "app.erb:10"
+          /\blines?\s+(\d+)/i                 # "line 42" or "lines 42"
+        ].freeze
+
+        # Patterns that look like line refs but aren't
+        IGNORE_PATTERNS = [
+          /ruby\s+\d+\.\d+/i,                 # "Ruby 3.1"
+          /version\s+\d+/i,                   # "version 2"
+          /port\s+\d+/i,                      # "port 8080"
+          /\bv\d+\.\d+/i,                     # "v1.2.3"
+          /\d+\.\d+\.\d+/,                    # "1.2.3" semver
+          /pid[:\s]+\d+/i,                    # "pid: 1234"
+          /id[:\s]+\d+/i,                     # "id: 42"
+          /\d+\s*(?:ms|seconds?|minutes?)/i,  # "42ms", "5 seconds"
+          /\d+\s*(?:bytes?|kb|mb|gb)/i,       # "100 bytes", "5mb"
+          /\d+%/,                             # "50%"
+          /\$\d+/,                            # "$42"
+          /#\d+/,                             # "#42" (issue reference)
+          %r{://[^/]*:\d+}                    # URLs with ports "http://localhost:8080"
+        ].freeze
+
+        def on_new_investigation
+          return unless check_comments?
+
+          processed_source.comments.each do |comment|
+            check_for_line_numbers(comment.text, comment)
+          end
+        end
+
+        def on_str(node)
+          return unless check_strings?
+          return if inside_heredoc?(node)
+
+          check_for_line_numbers(node.value, node)
+        end
+
+        def on_dstr(node)
+          return unless check_strings?
+          return if inside_heredoc?(node)
+
+          node.each_child_node(:str) do |str_node|
+            check_for_line_numbers(str_node.value, str_node)
+          end
+        end
+
+        private
+
+        def check_for_line_numbers(text, node)
+          return if text.nil? || text.empty?
+          return if matches_ignore_pattern?(text)
+
+          match = find_first_line_number(text)
+          return unless match
+
+          add_offense(node, message: format(MSG, line: match))
+        end
+
+        def find_first_line_number(text)
+          min = min_line_number
+          LINE_PATTERNS.each do |pattern|
+            text.scan(pattern) do |capture|
+              line_num = Array(capture).first
+              next unless line_num && line_num.to_i >= min
+
+              return Regexp.last_match[0]
+            end
+          end
+          nil
+        end
+
+        def matches_ignore_pattern?(text)
+          IGNORE_PATTERNS.any? { |pattern| text.match?(pattern) }
+        end
+
+        def inside_heredoc?(node)
+          return true if node.respond_to?(:heredoc?) && node.heredoc?
+
+          node.each_ancestor do |ancestor|
+            return true if ancestor.respond_to?(:heredoc?) && ancestor.heredoc?
+          end
+          false
+        end
+
+        def check_comments?
+          @check_comments ||= cop_config.fetch('CheckComments', true)
+        end
+
+        def check_strings?
+          @check_strings ||= cop_config.fetch('CheckStrings', true)
+        end
+
+        def min_line_number
+          @min_line_number ||= cop_config.fetch('MinLineNumber', 1)
+        end
+      end
+    end
+  end
+end