why-classes 0.1.0

data/lib/why_classes/configuration.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module WhyClasses
+  # A merged configuration (project .why-classes.yml over config/default.yml),
+  # exposing per-rule lookups and Rails awareness.
+  class Configuration
+    attr_reader :raw
+
+    def initialize(data)
+      @data = data
+      @raw = data
+    end
+
+    def all_rules
+      @data.fetch("AllRules", {})
+    end
+
+    def rules
+      @data.fetch("Rules", {})
+    end
+
+    def rails_config
+      @data.fetch("Rails", {})
+    end
+
+    def include_globs
+      all_rules.fetch("Include", ["**/*.rb"])
+    end
+
+    def exclude_globs
+      all_rules.fetch("Exclude", [])
+    end
+
+    def rails?
+      all_rules.fetch("Rails", true)
+    end
+
+    def enabled?(rule_name)
+      rule_config(rule_name).fetch("Enabled", true)
+    end
+
+    def autocorrect?(rule_name)
+      rule_config(rule_name).fetch("Autocorrect", false)
+    end
+
+    def rule_option(rule_name, key, default = nil)
+      rule_config(rule_name).fetch(key, default)
+    end
+
+    def rule_config(rule_name)
+      rules.fetch(rule_name, {})
+    end
+
+    def framework_base_classes
+      rails_config.fetch("FrameworkBaseClasses", [])
+    end
+
+    def framework_base_class?(const_path)
+      return false if const_path.nil?
+
+      framework_base_classes.include?(const_path)
+    end
+
+    def mixin_suggestions_for(const_path)
+      rails_config.fetch("MixinSuggestions", {}).fetch(const_path, nil)
+    end
+  end
+end

data/lib/why_classes/correction.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "parser/source/tree_rewriter"
+require_relative "parser"
+
+module WhyClasses
+  # Applies correctable offenses to a file's source via Parser::Source::TreeRewriter,
+  # which shares the coordinate system used for detection. Every rewrite is
+  # re-parsed as a fail-safe: if the result no longer parses, it is discarded and
+  # the original source is kept (the offense is still reported as advice).
+  module Correction
+    Result = Data.define(:source, :applied)
+
+    module_function
+
+    def apply(source_file, correctable_offenses)
+      return Result.new(source: source_file.source, applied: 0) if correctable_offenses.empty?
+
+      rewriter = ::Parser::Source::TreeRewriter.new(source_file.buffer)
+      applied = 0
+      correctable_offenses.each do |offense|
+        offense.corrector.call(rewriter)
+        applied += 1
+      rescue ::Parser::ClobberingError
+        # Overlapping edit -- skip this one, keep the rest.
+        next
+      end
+
+      new_source = rewriter.process
+      return Result.new(source: source_file.source, applied: 0) unless reparses?(new_source, source_file.path)
+
+      Result.new(source: new_source, applied: applied)
+    rescue ::Parser::ClobberingError
+      Result.new(source: source_file.source, applied: 0)
+    end
+
+    # Strict validation: the detection parser is intentionally error-tolerant,
+    # so use native Prism (which reports errors) to reject any rewrite that
+    # produced syntactically invalid Ruby.
+    def reparses?(source, _path)
+      ::Prism.parse(source).success?
+    end
+  end
+end

data/lib/why_classes/correctors/data_bucket_corrector.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../ast/node_helpers"
+
+module WhyClasses
+  module Correctors
+    # Decides whether a data-bucket class can be mechanically rewritten to a
+    # Struct/Data one-liner, and generates the replacement source.
+    #
+    # Conservative by design: anything it is unsure about is reported as
+    # advice-only (analysis returns nil) rather than rewritten incorrectly.
+    module DataBucketCorrector
+      H = AST::NodeHelpers
+
+      Analysis = Data.define(:fields, :kind, :keyword) do
+        def replacement(name)
+          list = fields.map { |f| ":#{f}" }.join(", ")
+          case kind
+          when :data
+            "#{name} = Data.define(#{list})"
+          when :struct
+            keyword ? "#{name} = Struct.new(#{list}, keyword_init: true)" : "#{name} = Struct.new(#{list})"
+          end
+        end
+      end
+
+      module_function
+
+      # Returns an Analysis when the class is a safely-convertible data bucket,
+      # else nil (caller downgrades to advice-only).
+      def analyze(shape, prefer_data:)
+        return nil unless viable?(shape)
+
+        fields = fields_for(shape)
+        return nil if fields.empty?
+
+        init = shape.initialize_method
+        # attr fields must be covered by the constructor's parameters.
+        return nil unless shape.attr_fields.all? { |f| fields.include?(f) }
+
+        keyword = init ? H.keyword_params?(init.children[1]) : false
+        Analysis.new(fields: fields, kind: kind_for(shape, prefer_data), keyword: keyword)
+      end
+
+      # The structural preconditions for treating a class as a pure data bucket.
+      def viable?(shape)
+        return false if shape.module?
+        return false if shape.uses_metaprogramming?
+        return false unless superclass_ok?(shape)
+        return false unless shape.behavior_methods.empty?
+        return false unless shape.singleton_methods.empty?
+        return false unless shape.other_statements.empty?
+
+        init = shape.initialize_method
+        # No initialize: a bare attr_* container still qualifies.
+        return !shape.attr_fields.empty? if init.nil?
+
+        H.initialize_only_assigns_params?(shape.node)
+      end
+
+      def superclass_ok?(shape)
+        shape.superclass.nil? || shape.superclass == "Object"
+      end
+
+      def fields_for(shape)
+        init = shape.initialize_method
+        init ? H.param_names(init.children[1]) : shape.attr_fields
+      end
+
+      # attr_accessor/attr_writer imply mutation -> Struct; otherwise Data.
+      def kind_for(shape, prefer_data)
+        writable = !(shape.attr_macros[:attr_writer] + shape.attr_macros[:attr_accessor]).empty?
+        return :struct if writable && !prefer_data
+
+        :data
+      end
+    end
+  end
+end

data/lib/why_classes/disable_comments.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module WhyClasses
+  # Honours inline suppression comments:
+  #   # why-classes:disable RuleA, RuleB      (whole file)
+  #   # why-classes:disable-line RuleA        (that line only)
+  # A bare `disable`/`disable-line` with no rule names (or `all`) suppresses
+  # every rule.
+  module DisableComments
+    DIRECTIVE = /#\s*why-classes:disable(?<line>-line)?\s*(?<rules>[\w:,\s]*)$/
+
+    Directives = Data.define(:file_rules, :line_rules) do
+      def allow?(offense)
+        return false if suppressed?(file_rules, offense.rule_name)
+
+        !suppressed?(line_rules.fetch(offense.line, nil), offense.rule_name)
+      end
+
+      def suppressed?(set, rule_name)
+        return false if set.nil?
+
+        set.include?(:all) || set.include?(rule_name)
+      end
+    end
+
+    module_function
+
+    def parse(comments)
+      file_rules = []
+      line_rules = Hash.new { |h, k| h[k] = [] }
+
+      comments.each do |comment|
+        match = DIRECTIVE.match(comment.text)
+        next unless match
+
+        names = rule_names(match[:rules])
+        if match[:line]
+          line_rules[comment.location.line].concat(names)
+        else
+          file_rules.concat(names)
+        end
+      end
+
+      Directives.new(file_rules: file_rules.uniq, line_rules: line_rules.transform_values(&:uniq))
+    end
+
+    def filter(offenses, comments)
+      directives = parse(comments)
+      offenses.select { |offense| directives.allow?(offense) }
+    end
+
+    def rule_names(raw)
+      names = raw.to_s.split(/[,\s]+/).reject(&:empty?)
+      return [:all] if names.empty? || names.include?("all")
+
+      names
+    end
+  end
+end

data/lib/why_classes/file_finder.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module WhyClasses
+  # Expands CLI paths into a concrete list of Ruby files, honouring the
+  # configuration's Include/Exclude globs. Explicitly-named files are always
+  # included; Exclude only filters directory expansion.
+  module FileFinder
+    module_function
+
+    def find(paths, configuration)
+      paths = ["."] if paths.nil? || paths.empty?
+      files = []
+      paths.each do |path|
+        if File.file?(path)
+          files << normalize(path)
+        elsif File.directory?(path)
+          files.concat(expand_dir(path, configuration))
+        end
+      end
+      files.uniq
+    end
+
+    def expand_dir(dir, configuration)
+      configuration.include_globs
+                   .flat_map { |glob| Dir.glob(File.join(dir, glob), File::FNM_EXTGLOB) }
+                   .select { |f| File.file?(f) }
+                   .map { |f| normalize(f) }
+                   .reject { |f| excluded?(f, configuration) }
+                   .uniq
+    end
+
+    def excluded?(file, configuration)
+      configuration.exclude_globs.any? do |glob|
+        File.fnmatch?(glob, file, File::FNM_PATHNAME | File::FNM_EXTGLOB) ||
+          File.fnmatch?("**/#{glob}", file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+      end
+    end
+
+    def normalize(path)
+      path.delete_prefix("./")
+    end
+  end
+end

data/lib/why_classes/formatters/base_formatter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module WhyClasses
+  module Formatters
+    # Formatters receive the array of FileReport objects produced by the Runner
+    # and write output to an IO.
+    class BaseFormatter
+      def initialize(io = $stdout)
+        @io = io
+      end
+
+      # @param reports [Array<Runner::FileReport>]
+      def call(reports)
+        raise NotImplementedError
+      end
+
+      private
+
+      attr_reader :io
+
+      def total_offenses(reports)
+        reports.sum { |r| r.offenses.size }
+      end
+
+      def total_corrected(reports)
+        reports.sum(&:applied)
+      end
+    end
+  end
+end

data/lib/why_classes/formatters/clang_formatter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "base_formatter"
+
+module WhyClasses
+  module Formatters
+    # One line per offense: `path:line:col: [Rule] message`. Editor/CI friendly.
+    class ClangFormatter < BaseFormatter
+      def call(reports)
+        reports.each do |report|
+          report.offenses.each do |offense|
+            io.puts "#{report.path}:#{offense.line}:#{offense.column + 1}: " \
+                    "[#{offense.rule_name}] #{offense.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/why_classes/formatters/diff_formatter.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "base_formatter"
+
+module WhyClasses
+  module Formatters
+    # Shows a unified diff of the proposed rewrites (for --diff / --dry-run).
+    # Only files that actually changed are printed.
+    class DiffFormatter < BaseFormatter
+      def call(reports)
+        changed = reports.select(&:changed?)
+        changed.each do |report|
+          io.puts "--- #{report.path}"
+          io.puts "+++ #{report.path}"
+          io.print UnifiedDiff.render(report.original_source, report.corrected_source)
+        end
+        corrections = total_corrected(reports)
+        io.puts "#{changed.size} file#{'s' unless changed.size == 1} would change, " \
+                "#{corrections} correction#{'s' unless corrections == 1}."
+      end
+
+      # A small LCS-based unified diff over lines. Sufficient for the localized
+      # rewrites this tool produces. Ops carry the actual line text.
+      module UnifiedDiff
+        Op = Struct.new(:kind, :text, :a_line, :b_line) # kind: :eq/:del/:add
+
+        module_function
+
+        def render(before, after, context: 3)
+          a = before.lines
+          b = after.lines
+          ops = diff_ops(a, b)
+          hunks(ops, context).map { |slice| format_hunk(slice) }.join
+        end
+
+        def diff_ops(a, b)
+          table = lcs_table(a, b)
+          ops = []
+          i = a.size
+          j = b.size
+          while i.positive? && j.positive?
+            if a[i - 1] == b[j - 1]
+              ops.unshift(Op.new(:eq, a[i - 1], i, j))
+              i -= 1
+              j -= 1
+            elsif table[i - 1][j] >= table[i][j - 1]
+              ops.unshift(Op.new(:del, a[i - 1], i, nil))
+              i -= 1
+            else
+              ops.unshift(Op.new(:add, b[j - 1], nil, j))
+              j -= 1
+            end
+          end
+          ops.unshift(Op.new(:del, a[(i -= 1)], i + 1, nil)) while i.positive?
+          ops.unshift(Op.new(:add, b[(j -= 1)], nil, j + 1)) while j.positive?
+          ops
+        end
+
+        def lcs_table(a, b)
+          table = Array.new(a.size + 1) { Array.new(b.size + 1, 0) }
+          a.size.times do |i|
+            b.size.times do |j|
+              table[i + 1][j + 1] = a[i] == b[j] ? table[i][j] + 1 : [table[i][j + 1], table[i + 1][j]].max
+            end
+          end
+          table
+        end
+
+        # Slice ops into hunks around changes, keeping `context` equal lines.
+        def hunks(ops, context)
+          change_idx = ops.each_index.select { |k| ops[k].kind != :eq }
+          return [] if change_idx.empty?
+
+          ranges = []
+          change_idx.each do |k|
+            lo = [k - context, 0].max
+            hi = [k + context, ops.size - 1].min
+            if ranges.any? && lo <= ranges.last[1] + 1
+              ranges.last[1] = hi
+            else
+              ranges << [lo, hi]
+            end
+          end
+          ranges.map { |lo, hi| ops[lo..hi] }
+        end
+
+        def format_hunk(slice)
+          a_lines = slice.select { |op| op.kind != :add }
+          b_lines = slice.select { |op| op.kind != :del }
+          a_start = a_lines.first&.a_line || 0
+          b_start = b_lines.first&.b_line || 0
+          header = "@@ -#{a_start},#{a_lines.size} +#{b_start},#{b_lines.size} @@\n"
+          body = slice.map { |op| "#{prefix(op.kind)}#{ensure_newline(op.text)}" }.join
+          header + body
+        end
+
+        def prefix(kind)
+          { eq: " ", del: "-", add: "+" }.fetch(kind)
+        end
+
+        def ensure_newline(text)
+          text.end_with?("\n") ? text : "#{text}\n"
+        end
+      end
+    end
+  end
+end

data/lib/why_classes/formatters/json_formatter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "base_formatter"
+
+module WhyClasses
+  module Formatters
+    # Machine-readable output (editors, LSP bridges, CI dashboards).
+    class JsonFormatter < BaseFormatter
+      def call(reports)
+        payload = {
+          "summary" => {
+            "files_inspected" => reports.size,
+            "offenses" => total_offenses(reports),
+            "corrected" => total_corrected(reports)
+          },
+          "files" => reports.map { |report| file_payload(report) }
+        }
+        io.puts JSON.pretty_generate(payload)
+      end
+
+      private
+
+      def file_payload(report)
+        {
+          "path" => report.path,
+          "offenses" => report.offenses.map do |offense|
+            {
+              "rule" => offense.rule_name,
+              "message" => offense.message,
+              "suggestion" => offense.suggestion,
+              "line" => offense.line,
+              "column" => offense.column + 1,
+              "severity" => offense.severity.to_s,
+              "correctable" => offense.correctable?
+            }
+          end
+        }
+      end
+    end
+  end
+end

data/lib/why_classes/formatters/progress_formatter.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "base_formatter"
+
+module WhyClasses
+  module Formatters
+    # The default human-readable formatter: one block per offense with its
+    # suggestion, then a summary line.
+    class ProgressFormatter < BaseFormatter
+      def call(reports)
+        reports.each do |report|
+          report.offenses.each { |offense| print_offense(report, offense) }
+        end
+        print_summary(reports)
+      end
+
+      private
+
+      def print_offense(report, offense)
+        marker = offense.correctable? ? " [correctable]" : ""
+        io.puts "#{report.path}:#{offense.line}:#{offense.column + 1}: " \
+                "[#{offense.rule_name}]#{marker} #{offense.message}"
+        offense.suggestion.to_s.each_line { |line| io.puts "  #{line.chomp}" }
+        io.puts
+      end
+
+      def print_summary(reports)
+        files = reports.size
+        offenses = total_offenses(reports)
+        corrected = total_corrected(reports)
+        summary = "#{files} file#{'s' unless files == 1} inspected, " \
+                  "#{offenses} offense#{'s' unless offenses == 1} detected"
+        summary += ", #{corrected} corrected" if corrected.positive?
+        io.puts summary
+      end
+    end
+  end
+end

data/lib/why_classes/offense.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module WhyClasses
+  # An immutable finding produced by a Rule.
+  #
+  # +corrector+ is nil for advice-only offenses, or a callable taking a
+  # Parser::Source::TreeRewriter and queueing the edits that apply the
+  # suggested refactoring.
+  Offense = Data.define(
+    :rule_name,
+    :message,
+    :suggestion,
+    :path,
+    :line,
+    :column,
+    :severity,
+    :correctable,
+    :corrector
+  ) do
+    def correctable?
+      correctable && !corrector.nil?
+    end
+
+    # Sort key: by position within a file.
+    def position
+      [line, column]
+    end
+  end
+end

data/lib/why_classes/options.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module WhyClasses
+  # Parsed CLI options (dogfooding the gem's own advice: a plain Data value).
+  #
+  # mode: :report | :diff | :fix
+  Options = Data.define(
+    :paths,
+    :mode,
+    :fix_unsafe,
+    :only,
+    :except,
+    :format,
+    :config_path,
+    :rails,
+    :fail_level
+  ) do
+    def self.defaults(**overrides)
+      new(**{
+        paths: [],
+        mode: :report,
+        fix_unsafe: false,
+        only: [],
+        except: [],
+        format: "progress",
+        config_path: nil,
+        rails: nil,
+        fail_level: "convention"
+      }.merge(overrides))
+    end
+  end
+end

data/lib/why_classes/parser.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "prism"
+require "prism/translation/parser"
+require "parser/source/tree_rewriter"
+
+module WhyClasses
+  # Wraps Prism's official parser-compatible frontend so that detection and
+  # rewriting share a single coordinate system. Prism is the actual parsing
+  # engine under the hood; the +parser+ gem supplies the AST node interface,
+  # source buffer, ranges and TreeRewriter.
+  module Parser
+    Result = Data.define(:ast, :comments, :buffer, :error)
+
+    module_function
+
+    # Parses +source+ and returns a Result. Parse errors are non-fatal: on
+    # failure +ast+ is nil and +error+ carries the exception message, so a
+    # single unparseable file never aborts a whole run.
+    def parse(source, path = "(source)")
+      buffer = ::Parser::Source::Buffer.new(path, source: source)
+      parser = ::Prism::Translation::Parser.new
+      parser.diagnostics.all_errors_are_fatal = false
+      parser.diagnostics.ignore_warnings      = true
+
+      ast, comments = parser.parse_with_comments(buffer)
+      Result.new(ast: ast, comments: comments, buffer: buffer, error: nil)
+    rescue ::Parser::SyntaxError, EncodingError => e
+      Result.new(ast: nil, comments: [], buffer: buffer, error: e.message)
+    end
+  end
+end

data/lib/why_classes/registry.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module WhyClasses
+  # Tracks every Rule subclass and resolves the active set from --only/--except
+  # and the configuration.
+  module Registry
+    @rules = {}
+
+    module_function
+
+    def register(rule_class)
+      @rules[rule_class.rule_name] = rule_class
+    end
+
+    def all
+      @rules.values
+    end
+
+    def names
+      @rules.keys
+    end
+
+    def fetch(name)
+      @rules.fetch(name)
+    end
+
+    def known?(name)
+      @rules.key?(name)
+    end
+
+    # Resolve the rule classes to run given config + CLI selection.
+    def active(configuration:, only: nil, except: nil)
+      selected = all
+      selected = selected.select { |r| Array(only).include?(r.rule_name) } if only && !only.empty?
+      selected = selected.reject { |r| Array(except).include?(r.rule_name) } if except && !except.empty?
+      selected.select { |r| configuration.enabled?(r.rule_name) }
+    end
+  end
+end