rubocop-claude 0.1.0

data/lib/rubocop_claude/init_wizard/hooks_installer.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RubocopClaude
+  class InitWizard
+    # Handles installing Claude Code hooks for auto-linting
+    class HooksInstaller
+      def initialize(wizard)
+        @wizard = wizard
+      end
+
+      def run
+        create_hooks_directory
+        create_hook_script
+        create_hooks_settings
+      end
+
+      private
+
+      def create_hooks_directory
+        return if Dir.exist?('.claude/hooks')
+
+        FileUtils.mkdir_p('.claude/hooks')
+      end
+
+      def create_hook_script
+        dest = '.claude/hooks/ruby-lint.sh'
+        File.write(dest, generate_hook_script)
+        FileUtils.chmod(0o755, dest)
+        @wizard.add_change('Created .claude/hooks/ruby-lint.sh')
+        puts "  Created #{dest}"
+      end
+
+      def generate_hook_script
+        linter_command = if @wizard.hook_linter == 'standardrb'
+          'standardrb --fix "$file" 2>&1'
+        else
+          # Prefer binstub, fall back to bundle exec
+          # Use $CLAUDE_PROJECT_DIR to ensure correct path regardless of cwd
+          <<~CMD.chomp
+            if [[ -x "$CLAUDE_PROJECT_DIR/bin/rubocop" ]]; then
+              "$CLAUDE_PROJECT_DIR/bin/rubocop" -a "$file" --format simple 2>&1
+            else
+              bundle exec rubocop -a "$file" --format simple 2>&1
+            fi
+          CMD
+        end
+
+        <<~SCRIPT
+          #!/usr/bin/env bash
+          # Claude Code hook: Auto-lint Ruby files after edits
+          # Generated by rubocop-claude init --hooks
+
+          set -e
+
+          file="$CLAUDE_EDITED_FILE"
+          [[ -z "$file" ]] && exit 0
+          [[ "$file" != *.rb ]] && exit 0
+          [[ ! -f "$file" ]] && exit 0
+
+          # Autocorrect and report remaining issues
+          #{linter_command}
+        SCRIPT
+      end
+
+      def create_hooks_settings
+        dest = '.claude/settings.local.json'
+        source = File.join(CLI::TEMPLATES_DIR, 'hooks', 'settings.local.json')
+
+        if File.exist?(dest)
+          merge_hooks_settings(dest, source)
+        else
+          FileUtils.cp(source, dest)
+          @wizard.add_change('Created .claude/settings.local.json with hooks')
+          puts "  Created #{dest}"
+        end
+      end
+
+      def merge_hooks_settings(dest, source)
+        existing = load_json(dest)
+        new_hooks = load_json(source)
+
+        ensure_hooks_structure(existing)
+        warn_if_existing_lint_hook(existing['hooks']['PostToolUse'])
+        existing['hooks']['PostToolUse'].concat(new_hooks['hooks']['PostToolUse'])
+
+        File.write(dest, JSON.pretty_generate(existing))
+        @wizard.add_change('Added Ruby lint hook to .claude/settings.local.json')
+        puts "  Updated #{dest}"
+      end
+
+      def load_json(path)
+        JSON.parse(File.read(path))
+      end
+
+      def ensure_hooks_structure(config)
+        config['hooks'] ||= {}
+        config['hooks']['PostToolUse'] ||= []
+      end
+
+      def warn_if_existing_lint_hook(post_tool_use_hooks)
+        existing = find_existing_lint_command(post_tool_use_hooks)
+        return unless existing
+
+        truncated = (existing.length > 60) ? "#{existing[0, 57]}..." : existing
+        puts "  [!] Found existing lint hook: #{truncated}"
+        puts '     You may want to remove duplicate hooks from settings.local.json'
+      end
+
+      def find_existing_lint_command(post_tool_use_hooks)
+        lint_patterns = [/rubocop/i, /standardrb/i, /lint/i, /\.rb/]
+
+        post_tool_use_hooks.each do |hook_config|
+          next unless hook_config['matcher'].to_s.match?(/Edit|Write/i)
+
+          (hook_config['hooks'] || []).each do |hook|
+            command = hook['command'].to_s
+            return command if lint_patterns.any? { |pat| command.match?(pat) }
+          end
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/rubocop_claude/init_wizard/linter_configurer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RubocopClaude
+  class InitWizard
+    # Handles linter config detection and setup (StandardRB or RuboCop)
+    class LinterConfigurer
+      def initialize(wizard)
+        @wizard = wizard
+      end
+
+      def run
+        config_type = detect_config_type
+        case config_type
+        when :standard then setup_standard_config
+        when :rubocop then setup_rubocop_config
+        else create_new_config
+        end
+      end
+
+      private
+
+      def detect_config_type
+        if File.exist?('.standard.yml')
+          :standard
+        elsif File.exist?('.rubocop.yml')
+          :rubocop
+        else
+          :none
+        end
+      end
+
+      def setup_standard_config
+        @wizard.using_standard = true
+        puts 'Detected: StandardRB (.standard.yml)'
+        add_to_linter_config('.standard.yml', 'plugins', 'plugin')
+      end
+
+      def setup_rubocop_config
+        puts 'Detected: RuboCop (.rubocop.yml)'
+        add_to_linter_config('.rubocop.yml', 'require', 'require')
+      end
+
+      def add_to_linter_config(file, key, prompt_label)
+        config = @wizard.load_yaml(file)
+        existing = config[key] || []
+
+        if existing.include?('rubocop-claude')
+          puts '  rubocop-claude already configured'
+        elsif @wizard.prompt_yes?("  Add rubocop-claude #{prompt_label}?", default: true)
+          config[key] = existing + ['rubocop-claude']
+          @wizard.save_yaml(file, config)
+          @wizard.add_change("Added rubocop-claude to #{file} #{key}")
+        end
+        puts
+      end
+
+      def create_new_config
+        puts 'No linter config found.'
+        choice = @wizard.prompt_choice(
+          'Which linter do you use?',
+          {'s' => 'StandardRB', 'r' => 'RuboCop', 'n' => 'Skip'},
+          default: 's'
+        )
+
+        case choice
+        when 's' then create_standard_config
+        when 'r' then create_rubocop_config
+        end
+        puts
+      end
+
+      def create_standard_config
+        @wizard.using_standard = true
+        config = {'plugins' => ['rubocop-claude']}
+        @wizard.save_yaml('.standard.yml', config)
+        @wizard.add_change('Created .standard.yml with rubocop-claude')
+        puts '  Created .standard.yml'
+      end
+
+      def create_rubocop_config
+        config = {'require' => ['rubocop-claude']}
+        @wizard.save_yaml('.rubocop.yml', config)
+        @wizard.add_change('Created .rubocop.yml with rubocop-claude')
+        puts '  Created .rubocop.yml'
+      end
+    end
+  end
+end

data/lib/rubocop_claude/init_wizard/preferences_gatherer.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RubocopClaude
+  class InitWizard
+    # Handles gathering user preferences for cop configuration
+    class PreferencesGatherer
+      def initialize(wizard)
+        @wizard = wizard
+      end
+
+      def run
+        puts 'Configuration options:'
+        puts
+
+        gather_ai_defaults
+        gather_visibility_style
+        gather_emoji_preference
+        gather_commented_code_preference
+        gather_hooks_preference
+        puts
+      end
+
+      private
+
+      def gather_ai_defaults
+        if @wizard.using_standard
+          puts '  Metrics cops (MethodLength, ClassLength, etc.) will be enabled.'
+          puts '  (StandardRB handles style; we add metrics enforcement)'
+          @wizard.add_change('Metrics cops enabled (StandardRB mode)')
+        else
+          puts '  AI Defaults: Stricter metrics, guard clauses, frozen constants, etc.'
+          puts '  (See README "Suggested RuboCop Defaults" for full list)'
+          ai_defaults = @wizard.prompt_yes?('  Enable AI defaults?', default: true)
+          @wizard.add_change(ai_defaults ? 'AI defaults enabled' : 'AI defaults disabled (Claude cops only)')
+        end
+      end
+
+      def gather_visibility_style
+        choice = @wizard.prompt_choice(
+          '  Visibility style?',
+          {'g' => 'grouped (private section)', 'm' => 'modifier (private def)'},
+          default: 'g'
+        )
+
+        style = (choice == 'm') ? 'modifier' : 'grouped'
+        @wizard.add_config_override('Claude/ExplicitVisibility', {'EnforcedStyle' => style})
+        @wizard.add_change("Visibility style: #{style}")
+      end
+
+      def gather_emoji_preference
+        allow_emoji = @wizard.prompt_yes?('  Allow emoji in strings?', default: false)
+
+        if allow_emoji
+          @wizard.add_config_override('Claude/NoFancyUnicode', {'AllowInStrings' => true})
+          @wizard.add_change('Emoji allowed in strings')
+        else
+          @wizard.add_change('Emoji not allowed anywhere')
+        end
+      end
+
+      def gather_commented_code_preference
+        choice = @wizard.prompt_choice(
+          '  Flag commented code:',
+          {'1' => 'Single lines too', '2' => 'Only multi-line blocks'},
+          default: '2'
+        )
+
+        min_lines = choice.to_i
+        @wizard.add_config_override('Claude/NoCommentedCode', {'MinLines' => min_lines})
+        @wizard.add_change("Commented code detection: #{(min_lines == 1) ? "single lines" : "multi-line only"}")
+      end
+
+      def gather_hooks_preference
+        puts
+        puts '  Claude Code hooks auto-lint Ruby files after each edit.'
+        @wizard.install_hooks = @wizard.prompt_yes?('  Install Claude Code hooks?', default: false)
+        return unless @wizard.install_hooks
+
+        gather_hook_linter_preference
+        @wizard.add_change("Claude Code hooks enabled (#{@wizard.hook_linter})")
+      end
+
+      def gather_hook_linter_preference
+        choice = @wizard.prompt_choice(
+          '  Linter for hooks?',
+          {'r' => 'RuboCop', 's' => 'StandardRB'},
+          default: 'r'
+        )
+
+        @wizard.hook_linter = (choice == 's') ? 'standardrb' : 'rubocop'
+      end
+    end
+  end
+end

data/lib/rubocop_claude/plugin.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'lint_roller'
+
+module RubocopClaude
+  class Plugin < LintRoller::Plugin
+    def about
+      LintRoller::About.new(
+        name: 'rubocop-claude',
+        version: VERSION,
+        homepage: 'https://github.com/nabm/rubocop-claude',
+        description: 'AI-focused Ruby linting - catches common AI coding anti-patterns'
+      )
+    end
+
+    def supported?(context)
+      context.engine == :rubocop
+    end
+
+    def rules(_context)
+      LintRoller::Rules.new(
+        type: :path,
+        config_format: :rubocop,
+        value: config_path
+      )
+    end
+
+    private
+
+    def config_path
+      File.expand_path('../../config/default.yml', __dir__)
+    end
+  end
+end

data/lib/rubocop_claude/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RubocopClaude
+  VERSION = '0.1.0'
+end

data/rubocop-claude.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'lib/rubocop_claude/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'rubocop-claude'
+  spec.version = RubocopClaude::VERSION
+  spec.authors = ['Nicholas Marshall']
+  spec.email = ['nialbima@users.noreply.github.com']
+
+  spec.summary = 'AI-focused Ruby linting via StandardRB plugin'
+  spec.description = 'A Rubocop/StandardRB plugin providing automated Rubocop foot-rake feedback to AI coding agents.'
+  spec.homepage = 'https://github.com/nabm/rubocop-claude'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.1.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+  spec.metadata['default_lint_roller_plugin'] = 'RubocopClaude::Plugin'
+
+  spec.files = Dir.glob('{config,lib,templates,exe}/**/*') + %w[
+    LICENSE.txt
+    README.md
+    CHANGELOG.md
+    rubocop-claude.gemspec
+  ]
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'lint_roller', '~> 1.1'
+  spec.add_dependency 'rubocop', '>= 1.50'
+
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop-packaging', '~> 0.6.0'
+  spec.add_development_dependency 'rubocop-rspec', '~> 3.9'
+  spec.add_development_dependency 'standard', '~> 1.40'
+end

data/templates/cops/class-structure.md

@@ -0,0 +1,58 @@
+# Layout/ClassStructure
+
+**What it catches:** Class/module contents in wrong order.
+
+**Why it matters:** Consistent ordering makes code easier to navigate.
+
+## Expected Order
+
+1. `include`, `extend`, `prepend`
+2. Constants
+3. Class methods (`def self.foo`)
+4. `initialize`
+5. Public instance methods
+6. Protected methods
+7. Private methods
+
+## How to Fix
+
+```ruby
+# BAD
+class User
+  def greet
+    "Hello"
+  end
+
+  include Comparable
+
+  ROLE = "admin"
+
+  def initialize(name)
+    @name = name
+  end
+end
+
+# GOOD
+class User
+  include Comparable
+
+  ROLE = "admin"
+
+  def initialize(name)
+    @name = name
+  end
+
+  def greet
+    "Hello"
+  end
+end
+```
+
+## Autocorrection
+
+**This cop autocorrects** - it will reorder methods automatically.
+
+## Decision Criteria
+
+- Let the autocorrect handle it
+- If it produces odd results, review manually and adjust

data/templates/cops/disable-cops-directive.md

@@ -0,0 +1,33 @@
+# Style/DisableCopsWithinSourceCodeDirective
+
+**What it catches:** `# rubocop:disable` comments inline.
+
+**Why it matters:** Disabling cops hides problems rather than fixing them.
+
+## How to Fix
+
+**Don't disable the cop.** Fix the underlying issue instead.
+
+```ruby
+# BAD
+# rubocop:disable Metrics/MethodLength
+def very_long_method
+  # ... lots of code ...
+end
+# rubocop:enable Metrics/MethodLength
+
+# GOOD - refactor the method
+def method_part_one
+  # ...
+end
+
+def method_part_two
+  # ...
+end
+```
+
+## Decision Criteria
+
+- If you genuinely can't fix the issue, **ask the human**
+- Never add `# rubocop:disable` without explicit human approval
+- If the cop seems wrong for this codebase, discuss with the human about configuring it globally

data/templates/cops/explicit-visibility.md

@@ -0,0 +1,52 @@
+# Claude/ExplicitVisibility
+
+**What it catches:** (in grouped mode) Inline `private def foo` instead of grouped `private` sections.
+
+**Why it matters:** Grouped visibility is the dominant Ruby convention. All private methods appear under the `private` keyword, making it easy to scan a class and see its public interface at the top.
+
+## How to Fix
+
+```ruby
+# BAD - modifier style (inline)
+class User
+  def public_method
+  end
+
+  private def secret_method
+  end
+
+  private def another_secret
+  end
+end
+
+# GOOD - grouped style
+class User
+  def public_method
+  end
+
+  private
+
+  def secret_method
+  end
+
+  def another_secret
+  end
+end
+```
+
+## Configuration
+
+```yaml
+Claude/ExplicitVisibility:
+  Enabled: true
+  EnforcedStyle: grouped  # default - or 'modifier' for inline style
+```
+
+## For AI Assistants
+
+**When adding private methods:**
+1. Place them after the `private` keyword at the bottom of the class
+2. If no `private` section exists, add one before your new method
+3. Don't use `private def` inline style unless the project consistently uses it
+
+**When you see `private def`:** The project may prefer modifier style. Check other files before "fixing" it.

data/templates/cops/metrics.md

@@ -0,0 +1,73 @@
+# Metrics/* Cops
+
+**What they catch:** Methods that are too complex or too long.
+
+- `Metrics/CyclomaticComplexity` - Too many branching paths
+- `Metrics/AbcSize` - Too many assignments, branches, conditions
+- `Metrics/MethodLength` - Too many lines
+
+**Why it matters:** Complex methods are hard to understand, test, and maintain.
+
+## How to Fix
+
+### Extract Helper Methods
+
+```ruby
+# BAD - one big method
+def process_order(order)
+  # validate order
+  # calculate totals
+  # apply discounts
+  # process payment
+  # send notifications
+end
+
+# GOOD - broken into focused methods
+def process_order(order)
+  validate_order(order)
+  totals = calculate_totals(order)
+  totals = apply_discounts(totals, order.customer)
+  process_payment(order, totals)
+  send_notifications(order)
+end
+```
+
+### Reduce Nesting
+
+```ruby
+# BAD - deep nesting
+def process(data)
+  if data.valid?
+    if data.complete?
+      if data.authorized?
+        # actual work
+      end
+    end
+  end
+end
+
+# GOOD - early returns
+def process(data)
+  return unless data.valid?
+  return unless data.complete?
+  return unless data.authorized?
+
+  # actual work
+end
+```
+
+### Simplify Conditionals
+
+```ruby
+# BAD - complex conditional
+if user.admin? || (user.moderator? && post.reported?) || user.id == post.author_id
+
+# GOOD - named method
+if can_moderate_post?(user, post)
+```
+
+## Decision Criteria
+
+- If a method triggers these, it probably needs refactoring
+- Ask if you're not sure how to split it up
+- Don't just add `# rubocop:disable` - that's never the answer

data/templates/cops/mystery-regex.md

@@ -0,0 +1,54 @@
+# Claude/MysteryRegex
+
+**What it catches:** Inline regexes longer than 25 characters (configurable).
+
+**Why it matters:** Complex regexes are cryptic. A named constant with a descriptive name makes the intent clear. Comments can explain what the pattern matches.
+
+## How to Fix
+
+```ruby
+# BAD - what does this match?
+text.match?(/\A[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z/)
+
+# BAD - still cryptic even in a method
+def valid_email?(text)
+  text.match?(/\A[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z/)
+end
+
+# GOOD - name explains intent
+EMAIL_PATTERN = /\A[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z/
+
+def valid_email?(text)
+  text.match?(EMAIL_PATTERN)
+end
+
+# BETTER - comment explains the pattern
+# Matches email addresses: local-part@domain.tld
+# Simplified from RFC 5322 - allows common characters only
+EMAIL_PATTERN = /\A[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z/
+```
+
+## Naming Conventions
+
+| Pattern Type | Naming Examples |
+|--------------|-----------------|
+| Email | `EMAIL_PATTERN`, `EMAIL_REGEX` |
+| URL | `URL_PATTERN`, `HTTP_URL_REGEX` |
+| Phone | `PHONE_NUMBER_PATTERN` |
+| Date | `ISO_DATE_PATTERN`, `DATE_REGEX` |
+| Validation | `VALID_USERNAME_PATTERN` |
+| Parsing | `LOG_LINE_PATTERN`, `CSV_ROW_REGEX` |
+
+## When Short Regexes Are Fine
+
+These are OK inline:
+- `/\A\d+\z/` - just digits
+- `/\s+/` - whitespace
+- `/[,;]/` - simple character class
+- `/\.rb\z/` - file extension
+
+## Decision Criteria
+
+- Extract to constant if you'd need to think about what it matches
+- Always add a comment for non-obvious patterns
+- Use `_PATTERN` or `_REGEX` suffix consistently in the project