rubocounsel 0.1.0

data/README.md

@@ -0,0 +1,78 @@
+# RuboCounsel
+
+<img src="rubocounsel.png" alt="RuboCounsel" width="400">
+
+An interactive CLI tool that transforms the RuboCop experience from "fix these errors" to "let's decide on your team's style together." Instead of dumping a wall of offenses, RuboCounsel walks you through each failing cop, explains what it does, shows real code examples, and helps you make informed decisions that get written to `.rubocop.yml`.
+
+The result: a RuboCop configuration that reflects conscious choices, not cargo-culted defaults.
+
+<img src="example.png" alt="RuboCounsel example" width="600">
+
+## Installation
+
+Add the gem to your application's Gemfile:
+
+```bash
+bundle add rubocounsel
+```
+
+Or install it directly:
+
+```bash
+gem install rubocounsel
+```
+
+## Usage
+
+Run RuboCounsel against your project:
+
+```bash
+rubocounsel
+```
+
+Or specify paths:
+
+```bash
+rubocounsel app/ lib/
+```
+
+Any RuboCop flags are passed through, so you can filter to specific cops or use a custom config:
+
+```bash
+rubocounsel --only Style/StringLiterals
+rubocounsel --config .rubocop_strict.yml app/
+```
+
+RuboCounsel will:
+
+1. Run RuboCop and identify which cops have offenses
+2. Skip any cops you've already configured in `.rubocop.yml`
+3. Walk you through each remaining cop interactively
+
+For each cop, you'll see its documentation and a link to the full docs, then choose to:
+
+- **Configure** — set the cop's attributes (style, max length, etc.) via guided prompts
+- **Disable** — add `Enabled: false` to your config
+- **Skip** — leave it unconfigured for now
+
+Configuration choices are saved to `.rubocop.yml` after each cop, so you won't lose progress if you quit early. Re-running RuboCounsel will pick up where you left off, skipping cops that are already configured.
+
+RuboCounsel supports extension gems like `rubocop-rails`, `rubocop-rspec`, and `rubocop-performance` — any cops registered in your bundle will be included automatically.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/dewyze/rubocounsel. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/dewyze/rubocounsel/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the RuboCounsel project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/dewyze/rubocounsel/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/exe/rubocounsel

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rubocounsel"
+
+exit RuboCounsel::CLI.run(ARGV)

data/lib/rubocounsel/cli.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "cli/ui"
+
+module RuboCounsel
+  # Command-line interface that ties all components together.
+  #
+  # Responsibilities:
+  #   - Run the Runner to collect offending cops
+  #   - Pass offending cop names to the Counselor
+  #   - Pass Counselor's choices to ConfigWriter
+  #   - Output the generated config
+  class CLI
+    HELP = <<~TEXT
+      Usage: rubocounsel [options] [paths]
+
+      RuboCounsel walks you through each offending RuboCop cop interactively,
+      helping you configure, disable, or skip each one.
+
+      All RuboCop flags are passed through (e.g. --only, --except, --config).
+
+      Options:
+        -h, --help       Show this help message
+        -v, --version    Show version
+    TEXT
+
+    def self.run(args, output: $stdout)
+      if args.include?("--help") || args.include?("-h")
+        output.puts HELP
+        return 0
+      end
+
+      if args.include?("--version") || args.include?("-v")
+        output.puts "rubocounsel #{RuboCounsel::VERSION}"
+        return 0
+      end
+
+      options, paths = RuboCop::Options.new.parse(args)
+      paths = ["."] if paths.empty?
+
+      new(paths: paths, rubocop_options: options, output: output).run
+    end
+
+    def initialize(paths: ["."], rubocop_options: {}, counselor_factory: nil, output: $stdout)
+      @paths = paths
+      @rubocop_options = rubocop_options
+      @counselor_factory = counselor_factory || method(:default_counselor)
+      @output = output
+    end
+
+    def run
+      ::CLI::UI::StdoutRouter.enable
+
+      cop_names = collect_offending_cops
+      return 0 if cop_names.empty?
+
+      all_choices = {}
+      counsel_cops(cop_names) do |cop_name, choice|
+        all_choices[cop_name] = choice
+        output_config(all_choices)
+      end
+
+      if all_choices.empty?
+        @output.puts "All offending cops are already configured."
+      end
+
+      0
+    rescue Interrupt
+      @output.puts "\nExiting..."
+      0
+    end
+
+    private
+
+    def collect_offending_cops
+      runner = Runner.new(rubocop_options: @rubocop_options)
+      runner.run(@paths)
+      runner.offending_cops.to_a
+    end
+
+    def counsel_cops(cop_names, &block)
+      counselor = @counselor_factory.call(cop_names)
+      counselor.counsel(&block)
+    end
+
+    def default_counselor(cop_names)
+      Counselor.new(cop_names)
+    end
+
+    def output_config(choices)
+      ConfigWriter.new(choices).merge_and_write(".rubocop.yml")
+    end
+  end
+end

data/lib/rubocounsel/config_writer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require "active_support/core_ext/hash/deep_merge"
+
+module RuboCounsel
+  # Generates .rubocop.yml content from user choices.
+  #
+  # Converts a hash of cop choices to YAML format and optionally writes to file.
+  # The choices hash maps cop names to their configuration settings:
+  #
+  #   {
+  #     "Style/StringLiterals" => { "EnforcedStyle" => "double_quotes" },
+  #     "Metrics/MethodLength" => { "Max" => 15 }
+  #   }
+  class ConfigWriter
+    PRIORITY_KEYS = ["inherit_from", "inherit_mode", "require", "AllCops"].freeze
+
+    attr_reader :choices
+
+    def initialize(choices)
+      @choices = choices
+    end
+
+    def to_yaml
+      return "" if choices.empty?
+
+      add_blank_lines(sort_config(choices).to_yaml)
+    end
+
+    def write(path)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, to_yaml)
+    end
+
+    # Merges choices into an existing config file and writes it back.
+    def merge_and_write(path)
+      existing = File.exist?(path) ? YAML.load_file(path) || {} : {}
+      merged = sort_config(existing.deep_merge(choices))
+      File.write(path, add_blank_lines(merged.to_yaml))
+    end
+
+    private
+
+    def sort_config(config)
+      priority = {}
+      cops = {}
+
+      config.each do |key, value|
+        if PRIORITY_KEYS.include?(key)
+          priority[key] = value
+        else
+          cops[key] = value
+        end
+      end
+
+      ordered = PRIORITY_KEYS.each_with_object({}) do |key, hash|
+        hash[key] = priority[key] if priority.key?(key)
+      end
+
+      ordered.merge(cops.sort.to_h)
+    end
+
+    def add_blank_lines(yaml)
+      yaml.gsub(/^([A-Za-z])/, "\n\\1").lstrip
+    end
+  end
+end

data/lib/rubocounsel/configurable_attribute.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RuboCounsel
+  # Represents one configurable aspect of a cop (e.g., EnforcedStyle, Max).
+  #
+  # Determines the attribute type based on its value:
+  #   - :choice   - has a list of valid options (EnforcedStyle with SupportedStyles)
+  #   - :boolean  - true/false value
+  #   - :integer  - numeric value
+  #   - :array    - list of values (AllowedMethods, etc.)
+  #   - :string   - any other string value
+  class ConfigurableAttribute
+    attr_reader :name, :default_value, :options
+
+    def initialize(name, default_value, options: nil)
+      @name = name
+      @default_value = default_value
+      @options = options
+    end
+
+    def type
+      return :choice if @options
+
+      case @default_value
+      when true, false
+        :boolean
+      when Integer
+        :integer
+      when Array
+        :array
+      else
+        :string
+      end
+    end
+
+    def choice?
+      type == :choice
+    end
+
+    def boolean?
+      type == :boolean
+    end
+  end
+end

data/lib/rubocounsel/cop_catalog.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/inclusion"
+require "rubocop"
+
+module RuboCounsel
+  # Central repository of cop information.
+  # Uses RuboCop's Registry for cop discovery and ExampleLoader for documentation.
+  #
+  # The Registry is RuboCop's authoritative cop list - stable and complete.
+  # Examples come from YARD parsing (separate concern, can fail gracefully).
+  class CopCatalog
+    # InternalAffairs cops are for RuboCop development, not end users.
+    EXCLUDED_COP_DEPARTMENTS = ["InternalAffairs"].freeze
+
+    def initialize(example_loader: ExampleLoader.instance)
+      @example_loader = example_loader
+      @cops = nil
+      @examples_by_class_name = nil
+    end
+
+    # Returns a Hash where keys are cop names (e.g., "Style/StringLiterals")
+    # and values are cop classes.
+    def cops
+      @cops ||= load_cops
+    end
+
+    # Returns the cop class for the given name, or nil if not found.
+    def lookup(cop_name)
+      cops[cop_name]
+    end
+
+    # Returns an Array of Example objects for the given cop name.
+    # Returns empty array if no examples found.
+    def examples_for(cop_name)
+      cop_class = lookup(cop_name)
+      return [] unless cop_class
+
+      examples_by_class_name[cop_class.to_s] || []
+    end
+
+    # Returns the full YARD docstring for the given cop name.
+    # Returns nil if no docstring found.
+    def docstring_for(cop_name)
+      cop_class = lookup(cop_name)
+      return nil unless cop_class
+
+      docstrings_by_class_name[cop_class.to_s]
+    end
+
+    private
+
+    def load_cops
+      result = {}
+
+      RuboCop::Cop::Registry.global.each do |cop_class|
+        next if cop_class.department.to_s.in?(EXCLUDED_COP_DEPARTMENTS)
+
+        result[cop_class.cop_name] = cop_class
+      end
+
+      result
+    end
+
+    def examples_by_class_name
+      @examples_by_class_name ||= @example_loader.examples
+    end
+
+    def docstrings_by_class_name
+      @docstrings_by_class_name ||= @example_loader.docstrings
+    end
+  end
+end

data/lib/rubocounsel/cop_entry.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+module RuboCounsel
+  # Represents a single cop with its configuration and examples.
+  #
+  # This is an entry in the CopCatalog - a data object that combines:
+  #   - The cop class (from Registry)
+  #   - Its configuration (from RuboCop's default config)
+  #   - Its examples (from YARD parsing)
+  #   - Computed configurable attributes
+  class CopEntry
+    # Keys in cop configuration that are metadata, not user-configurable options.
+    METADATA_KEYS = [
+      "Description",
+      "StyleGuide",
+      "Enabled",
+      "VersionAdded",
+      "VersionChanged",
+      "VersionRemoved",
+      "Reference",
+      "Safe",
+      "SafeAutoCorrect"
+    ].freeze
+
+    attr_reader :cop_class, :examples
+
+    def initialize(cop_class, examples: [])
+      @cop_class = cop_class
+      @examples = examples
+    end
+
+    def cop_name
+      @cop_class.cop_name
+    end
+
+    def configuration
+      @configuration ||= RuboCop::ConfigLoader.default_configuration[cop_name].to_h
+    end
+
+    def configurable_attributes
+      @configurable_attributes ||= build_configurable_attributes
+    end
+
+    private
+
+    def build_configurable_attributes
+      attributes = []
+
+      configuration.each do |key, value|
+        next if metadata_key?(key)
+        next if supported_key?(key)
+
+        options = find_options_for(key)
+        attributes << ConfigurableAttribute.new(key, value, options: options)
+      end
+
+      attributes
+    end
+
+    def metadata_key?(key)
+      METADATA_KEYS.include?(key)
+    end
+
+    def supported_key?(key)
+      key.start_with?("Supported")
+    end
+
+    # Finds the corresponding SupportedXxx options for an EnforcedXxx key.
+    # E.g., EnforcedStyle -> SupportedStyles
+    def find_options_for(key)
+      return nil unless key.start_with?("Enforced")
+
+      # EnforcedStyle -> SupportedStyles, EnforcedHashRocketStyle -> SupportedHashRocketStyles
+      supported_key = key.sub("Enforced", "Supported") + "s"
+      configuration[supported_key]
+    end
+  end
+end

data/lib/rubocounsel/counselor.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "cli/ui"
+require "rubocop"
+
+module RuboCounsel
+  # The interactive CLI experience for walking through offending cops.
+  #
+  # Responsibilities:
+  #   - Walk through each offending cop
+  #   - Display cop information and examples
+  #   - Collect user choices via cli-ui prompts
+  #   - Return choices hash for ConfigWriter
+  #
+  # Cops that are already configured in .rubocop.yml are skipped by default.
+  class Counselor
+    ACTIONS = ["Configure", "Disable", "Skip"].freeze
+    FILE_TARGETING_ATTRIBUTES = ["Include", "Exclude"].freeze
+
+    def initialize(cop_names, catalog: CopCatalog.new, user_config: nil, output: $stdout)
+      @cop_names = cop_names
+      @catalog = catalog
+      @user_config_override = user_config
+      @output = output
+    end
+
+    def counsel
+      choices = {}
+
+      @cop_names.each do |cop_name|
+        choice = counsel_cop(cop_name)
+        if choice
+          choices[cop_name] = choice
+          yield(cop_name, choice) if block_given?
+        end
+      end
+
+      choices
+    end
+
+    private
+
+    def counsel_cop(cop_name)
+      return nil if already_configured?(cop_name)
+
+      entry = build_cop_entry(cop_name)
+      return nil unless entry
+
+      docstring = @catalog.docstring_for(cop_name)
+
+      ::CLI::UI::Frame.open(entry.cop_name, color: :blue) do
+        display_cop_info(entry, docstring)
+        action = ::CLI::UI::Prompt.ask("What would you like to do?", options: ACTIONS)
+
+        case action
+        when "Disable"
+          { "Enabled" => false }
+        when "Skip"
+          nil
+        when "Configure"
+          configure_cop(entry)
+        end
+      end
+    end
+
+    def already_configured?(cop_name)
+      user_config.key?(cop_name)
+    end
+
+    def user_config
+      @user_config ||= @user_config_override || load_user_config
+    end
+
+    def load_user_config
+      return {} unless File.exist?(".rubocop.yml")
+
+      RuboCop::ConfigLoader.load_file(".rubocop.yml")
+    end
+
+    def build_cop_entry(cop_name)
+      cop_class = @catalog.lookup(cop_name)
+      return nil unless cop_class
+
+      examples = @catalog.examples_for(cop_name)
+      CopEntry.new(cop_class, examples: examples)
+    end
+
+    def display_cop_info(entry, docstring)
+      # Prefer full YARD docstring over short config description
+      description = docstring || entry.configuration["Description"]
+      @output.puts ::CLI::UI.fmt("{{cyan:#{description}}}\n") if description
+
+      # Show documentation URL
+      doc_url = entry.cop_class.documentation_url
+      @output.puts ::CLI::UI.fmt("{{underline:#{doc_url}}}\n") if doc_url
+    end
+
+    def configure_cop(entry)
+      config = {}
+
+      display_array_attributes_message(entry.configurable_attributes)
+
+      entry.configurable_attributes.each do |attr|
+        value = prompt_for_attribute(attr, entry.examples)
+        config[attr.name] = value unless value.nil?
+      end
+
+      config
+    end
+
+    def display_array_attributes_message(attributes)
+      array_attrs = attributes
+        .select { |attr| attr.type == :array }
+        .reject { |attr| FILE_TARGETING_ATTRIBUTES.include?(attr.name) }
+
+      return if array_attrs.empty?
+
+      names = array_attrs.map(&:name).join(", ")
+      @output.puts ::CLI::UI.fmt(
+        "{{green:These attributes accept lists and can be configured directly in .rubocop.yml: #{names}}}"
+      )
+    end
+
+    def prompt_for_attribute(attr, examples)
+      if attr.type.in?([:choice, :boolean]) && !has_examples_for?(attr.name, examples)
+        display_no_examples_message(attr.name)
+      end
+
+      case attr.type
+      when :choice
+        prompt_for_choice(attr, examples)
+      when :boolean
+        prompt_for_boolean(attr, examples)
+      when :array
+        # Skip array attributes (Include, Exclude, AllowedMethods, etc.)
+        # These aren't style choices and prompting for them causes type corruption
+        nil
+      else
+        prompt_for_value(attr)
+      end
+    end
+
+    def prompt_for_choice(attr, examples)
+      # Put default first, then the rest
+      default_val = attr.default_value.to_s
+      sorted_options = attr.options.sort_by { |opt| opt == default_val ? 0 : 1 }
+      options_with_default = sorted_options.map do |opt|
+        opt == default_val ? "#{opt} (default)" : opt
+      end
+
+      loop do
+        options = has_examples_for?(attr.name, examples) ? options_with_default + ["Show examples"] : options_with_default
+
+        answer = ::CLI::UI::Prompt.ask("#{attr.name}?", options: options)
+
+        if answer == "Show examples"
+          display_examples_for_attribute(attr.name, examples)
+        else
+          # Strip "(default)" suffix if present
+          return answer.sub(/ \(default\)$/, "")
+        end
+      end
+    end
+
+    def has_examples_for?(attr_name, examples)
+      examples.any? { |ex| ex.attribute == attr_name }
+    end
+
+    def prompt_for_boolean(attr, examples)
+      # Always show default first
+      base_options = if attr.default_value
+                       ["yes (default)", "no"]
+                     else
+                       ["no (default)", "yes"]
+                     end
+
+      loop do
+        options = has_examples_for?(attr.name, examples) ? base_options + ["Show examples"] : base_options
+
+        answer = ::CLI::UI::Prompt.ask("#{attr.name}?", options: options)
+
+        if answer == "Show examples"
+          display_examples_for_attribute(attr.name, examples)
+        else
+          return answer.sub(/ \(default\)$/, "") == "yes"
+        end
+      end
+    end
+
+    def prompt_for_value(attr)
+      ::CLI::UI::Prompt.ask(
+        "#{attr.name}? (default: #{attr.default_value})",
+        default: attr.default_value.to_s
+      )
+    end
+
+    def display_no_examples_message(attr_name)
+      @output.puts ::CLI::UI.fmt("{{italic:No examples available for #{attr_name}.}}")
+    end
+
+    def display_examples_for_attribute(attr_name, examples)
+      relevant = examples.select { |ex| ex.attribute == attr_name }
+      return if relevant.empty?
+
+      relevant.each do |example|
+        label = example.default? ? "#{example.value} (default)" : example.value
+        @output.puts <<~OUTPUT
+          #{::CLI::UI.fmt("{{yellow:#{label}:}}")}
+          #{example.text}
+        OUTPUT
+      end
+    end
+  end
+end