why-classes 0.1.0

data/lib/why_classes/rule.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "offense"
+require_relative "registry"
+require_relative "ast/node_helpers"
+require_relative "ast/class_shape"
+
+module WhyClasses
+  # Base class for every detector. A rule walks the parser-style AST, dispatches
+  # to `on_<type>` handlers a subclass defines, and emits Offenses via
+  # #add_offense. Rules never mutate source; a correctable offense carries a
+  # `corrector` callable that queues edits on a Parser::Source::TreeRewriter.
+  class Rule
+    H = AST::NodeHelpers
+
+    class << self
+      def rule_name
+        name.split("::").last
+      end
+
+      # Human-readable one-liner shown by `--list-rules`. Override in subclasses.
+      def description
+        ""
+      end
+
+      # Whether this rule can ever autocorrect. Advice-only rules return false.
+      def autocorrectable?
+        false
+      end
+
+      def inherited(subclass)
+        super
+        # Anonymous subclasses (in specs) are not registered.
+        Registry.register(subclass) unless subclass.name.nil?
+      end
+    end
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    # Run this rule over a SourceFile and return its offenses.
+    def call(source_file)
+      @source_file = source_file
+      @offenses = []
+      walk(source_file.ast)
+      @offenses
+    end
+
+    private
+
+    attr_reader :configuration, :source_file
+
+    def rails?
+      configuration.rails?
+    end
+
+    def rule_option(key, default = nil)
+      configuration.rule_option(self.class.rule_name, key, default)
+    end
+
+    def shape(class_node)
+      AST::ClassShape.new(class_node)
+    end
+
+    def walk(node)
+      return unless node.is_a?(::Parser::AST::Node)
+
+      handler = "on_#{node.type}"
+      send(handler, node) if respond_to?(handler, true)
+      node.children.each { |child| walk(child) }
+    end
+
+    def add_offense(node, message:, suggestion:, severity: :convention, corrector: nil)
+      range = node.location.expression
+      @offenses << Offense.new(
+        rule_name: self.class.rule_name,
+        message: message,
+        suggestion: suggestion,
+        path: source_file.path,
+        line: range.line,
+        column: range.column,
+        severity: severity,
+        correctable: !corrector.nil?,
+        corrector: corrector
+      )
+    end
+  end
+end

data/lib/why_classes/rules/data_bucket.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+require_relative "../correctors/data_bucket_corrector"
+
+module WhyClasses
+  module Rules
+    # Rule 4 (summary): "If it's just a data bucket, use a Struct, Data object, or
+    # a Hash." A class that only declares attr_* fields and an initialize that
+    # assigns them, with no behaviour, is a data bucket.
+    class DataBucket < Rule
+      def self.description
+        "Class that only holds data (attr_* + field-assigning initialize) -> use Struct or Data."
+      end
+
+      def self.autocorrectable?
+        true
+      end
+
+      def on_class(node)
+        s = shape(node)
+        return if s.name.nil?
+        return if configuration.framework_base_class?(s.superclass)
+        return unless data_bucket?(s)
+
+        analysis = Correctors::DataBucketCorrector.analyze(s, prefer_data: rule_option("PreferData", true))
+        corrector = build_corrector(node, s, analysis)
+
+        add_offense(
+          node,
+          message: "#{s.name} is a data bucket: it only stores fields and has no behaviour.",
+          suggestion: suggestion_for(s, analysis),
+          corrector: corrector
+        )
+      end
+
+      private
+
+      # Loose detection (for advice): has attr fields, no real behaviour, and
+      # either no initialize or an initialize that only assigns fields.
+      def data_bucket?(s)
+        return false if s.attr_fields.empty? && s.initialize_method.nil?
+        return false unless s.behavior_methods.empty?
+        return false unless s.singleton_methods.empty?
+        return false if s.uses_metaprogramming?
+
+        init = s.initialize_method
+        return true if init.nil? && !s.attr_fields.empty?
+
+        H.initialize_only_assigns_params?(s.node)
+      end
+
+      def build_corrector(node, _shape, analysis)
+        return nil if analysis.nil?
+        return nil unless configuration.autocorrect?(self.class.rule_name)
+
+        name = H.class_name(node)
+        replacement = analysis.replacement(name)
+        ->(rewriter) { rewriter.replace(node.location.expression, replacement) }
+      end
+
+      def suggestion_for(s, analysis)
+        if analysis
+          target = analysis.replacement(s.name)
+          caveat =
+            if analysis.kind == :data
+              "Data objects are immutable and compare by value; `.new` keeps the same fields."
+            else
+              "Struct adds value equality plus `to_a`/`[]`/`each`; it stays mutable."
+            end
+          "Replace the class with:\n    #{target}\n  #{caveat}"
+        else
+          "Consider a Struct or Data.define for these fields instead of a hand-written class " \
+            "(couldn't rewrite automatically: a superclass, default args, or extra logic is present)."
+        end
+      end
+    end
+  end
+end

data/lib/why_classes/rules/function_bucket.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module WhyClasses
+  module Rules
+    # Rule 2 (summary): "If it's named after a design pattern, it's probably a
+    # workaround for a less flexible language." The classic service object -- a
+    # class with a single `call`/`perform`/`run` instance method and no state --
+    # is a bucket for a function.
+    class FunctionBucket < Rule
+      def self.description
+        "Class with a single call/perform/run method and no state -> use a module function."
+      end
+
+      def on_class(node)
+        s = shape(node)
+        return if s.name.nil?
+        return if configuration.framework_base_class?(s.superclass)
+        return if s.superclass? # framework/base subclasses handled above; other inheritance is separate
+        return unless function_bucket?(s)
+
+        method = s.behavior_methods.first.children[0]
+        add_offense(
+          node,
+          message: "#{s.name} is a bucket for a single function (`##{method}`) with no state.",
+          suggestion: "Prefer a module function or a plain method:\n" \
+                      "    module #{s.name}\n      module_function\n\n" \
+                      "      def #{method}(...)\n        ...\n      end\n    end\n" \
+                      "  Callers become `#{s.name}.#{method}(...)` with no throwaway instance."
+        )
+      end
+
+      private
+
+      def function_bucket?(s)
+        return false if s.uses_metaprogramming?
+
+        behavior = s.behavior_methods
+        return false unless behavior.size == 1
+        return false unless method_names.include?(behavior.first.children[0])
+        return false unless s.singleton_methods.empty?
+        return false unless s.attr_fields.empty?
+
+        # No real state: either no initialize, or an initialize that only stashes
+        # collaborators (still a smell, but we require truly stateless here).
+        s.initialize_method.nil?
+      end
+
+      def method_names
+        Array(rule_option("MethodNames", %w[call perform run execute])).map(&:to_sym)
+      end
+    end
+  end
+end

data/lib/why_classes/rules/inheritance_for_mixins.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module WhyClasses
+  module Rules
+    # Thomas criticises inheriting from a fat base class purely to inject
+    # behaviour (e.g. `< ActiveRecord::Base` pulls in hundreds of methods) rather
+    # than to specialise. Advice-only: safe rewriting needs whole-program
+    # knowledge of which inherited methods are actually used.
+    class InheritanceForMixins < Rule
+      def self.description
+        "Inheriting a fat base class to inject methods -> include only the mixins you use."
+      end
+
+      def on_class(node)
+        return unless rails?
+
+        s = shape(node)
+        return if s.name.nil?
+        return unless s.superclass?
+
+        mixins = configuration.mixin_suggestions_for(s.superclass)
+        return if mixins.nil?
+
+        add_offense(
+          node,
+          message: "#{s.name} < #{s.superclass} inherits a large surface just to gain behaviour.",
+          suggestion: "If you only need part of it, include the specific mixins instead:\n" \
+                      "    class #{s.name}\n" +
+                      mixins.map { |m| "      include #{m}" }.join("\n") +
+                      "\n    end\n  Inherit only when you are genuinely specialising #{s.superclass}."
+        )
+      end
+    end
+  end
+end

data/lib/why_classes/rules/invalid_initial_state.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module WhyClasses
+  module Rules
+    # A red-flag pattern: initialize leaves a field nil, so the object is invalid
+    # until a setter is called after `.new`. A signal the "object" is really a
+    # sequence of function calls in disguise.
+    class InvalidInitialState < Rule
+      def self.description
+        "Object constructed in an invalid state (initialize sets a field to nil, needs a setter first)."
+      end
+
+      def on_class(node)
+        s = shape(node)
+        return if s.name.nil?
+
+        init = s.initialize_method
+        return if init.nil?
+
+        writers = s.attr_macros[:attr_writer] + s.attr_macros[:attr_accessor]
+        nils = nil_assigned_ivars(init)
+        return if nils.empty?
+
+        nils.each do |ivar|
+          field = ivar.to_s.delete_prefix("@").to_sym
+          next unless writers.include?(field)
+          next unless field_read_in_behavior?(s, ivar)
+
+          add_offense(
+            node,
+            message: "#{s.name}#initialize sets #{ivar} = nil and exposes a setter, so a " \
+                     "#{s.name} is invalid until `#{field}=` is called.",
+            suggestion: "Require #{field} up front instead:\n" \
+                        "    def initialize(#{field})\n      @#{field} = #{field}\n    end\n" \
+                        "  or drop the object entirely and pass #{field} to a module function."
+          )
+        end
+      end
+
+      private
+
+      def nil_assigned_ivars(init)
+        H.body_statements(init.children[2]).select do |stmt|
+          H.node?(stmt) && stmt.type == :ivasgn &&
+            (val = stmt.children[1]) && H.node?(val) && val.type == :nil
+        end.map { |stmt| stmt.children[0] }
+      end
+
+      def field_read_in_behavior?(s, ivar)
+        s.behavior_methods.any? { |m| H.ivars_read(m).include?(ivar) }
+      end
+    end
+  end
+end

data/lib/why_classes/rules/single_attribute_reader.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module WhyClasses
+  module Rules
+    # Decoupled polymorphism: an instance method that only reads a single field
+    # could be a freestanding function that works on anything responding to that
+    # field. Off by default -- it is a stylistic nudge and can be noisy.
+    class SingleAttributeReader < Rule
+      def self.description
+        "Instance method that only reads one field -> consider a freestanding polymorphic function."
+      end
+
+      def on_class(node)
+        s = shape(node)
+        return if s.name.nil?
+        return if s.uses_metaprogramming?
+
+        s.behavior_methods.each do |method|
+          read = H.ivars_read(method)
+          written = H.ivars_assigned(method)
+          next unless written.empty?
+          next unless read.size == 1
+
+          field = read.first.to_s.delete_prefix("@")
+          add_offense(
+            method,
+            message: "#{s.name}##{method.children[0]} only reads @#{field}; it isn't tied to #{s.name}.",
+            suggestion: "A freestanding function is more flexible and works on any object " \
+                        "exposing `#{field}`:\n" \
+                        "    def #{method.children[0]}(#{field})\n      # use #{field} directly\n    end"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/why_classes/rules/stateless_singleton_methods.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../rule"
+
+module WhyClasses
+  module Rules
+    # Rule 3 (summary): "If it has no state, it should not be a class." A class
+    # whose body is only `self.` methods is a namespace for functions, not an
+    # object factory -- it should be a module.
+    class StatelessSingletonMethods < Rule
+      def self.description
+        "Class with only class methods and no state -> use a module with `extend self`."
+      end
+
+      def on_class(node)
+        s = shape(node)
+        return if s.name.nil?
+        return if s.superclass? # inheritance is a separate concern (see InheritanceForMixins)
+        return if configuration.framework_base_class?(s.superclass)
+        return unless only_singleton_methods?(s)
+
+        add_offense(
+          node,
+          message: "#{s.name} has only class methods and no state; it's a bucket of functions, " \
+                   "not an object factory.",
+          suggestion: "Make it a module and expose the methods with `extend self`:\n" \
+                      "    module #{s.name}\n      def #{example_method(s)}(...)\n        ...\n      end\n\n" \
+                      "      private\n      # helper methods here are now genuinely private\n\n" \
+                      "      extend self\n    end"
+        )
+      end
+
+      private
+
+      def only_singleton_methods?(s)
+        return false if s.singleton_methods.empty?
+        return false unless s.instance_methods.empty?
+        return false unless s.attr_fields.empty?
+        return false if s.uses_metaprogramming?
+
+        # Allow only constants / comments as other statements.
+        s.other_statements.all? { |n| %i[casgn].include?(n.type) }
+      end
+
+      def example_method(s)
+        s.singleton_method_names.first || "call"
+      end
+    end
+  end
+end

data/lib/why_classes/runner.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "config_loader"
+require_relative "registry"
+require_relative "source_file"
+require_relative "file_finder"
+require_relative "disable_comments"
+require_relative "correction"
+require_relative "formatters/progress_formatter"
+require_relative "formatters/clang_formatter"
+require_relative "formatters/json_formatter"
+require_relative "formatters/diff_formatter"
+
+module WhyClasses
+  # Orchestrates a run: find files, analyse each with the active rules, optionally
+  # apply corrections, hand the results to a formatter, and compute an exit code.
+  class Runner
+    FileReport = Data.define(:path, :offenses, :original_source, :corrected_source, :applied) do
+      def changed?
+        corrected_source != original_source
+      end
+    end
+
+    SEVERITY_RANK = { none: 0, convention: 1, warning: 2 }.freeze
+
+    FORMATTERS = {
+      "progress" => Formatters::ProgressFormatter,
+      "clang" => Formatters::ClangFormatter,
+      "json" => Formatters::JsonFormatter,
+      "diff" => Formatters::DiffFormatter
+    }.freeze
+
+    def initialize(options, configuration: nil)
+      @options = options
+      @configuration = configuration || build_configuration
+    end
+
+    attr_reader :configuration
+
+    def run(io: $stdout)
+      reports = analyze_files(FileFinder.find(@options.paths, @configuration))
+      formatter_for(@options.mode, io).call(reports)
+      exit_code(reports)
+    end
+
+    # Analyse a single already-built SourceFile and return its filtered,
+    # position-sorted offenses. Handy for specs.
+    def offenses_for(source_file)
+      return [] unless source_file.parsed?
+
+      rules = Registry.active(configuration: @configuration, only: @options.only, except: @options.except)
+      raw = rules.flat_map { |rule_class| rule_class.new(@configuration).call(source_file) }
+      DisableComments.filter(raw, source_file.comments).sort_by(&:position)
+    end
+
+    private
+
+    def analyze_files(paths)
+      paths.map { |path| process(SourceFile.from_path(path)) }
+    end
+
+    def process(source_file)
+      offenses = offenses_for(source_file)
+      corrected, applied = maybe_correct(source_file, offenses)
+      FileReport.new(
+        path: source_file.path,
+        offenses: offenses,
+        original_source: source_file.source,
+        corrected_source: corrected,
+        applied: applied
+      )
+    end
+
+    def maybe_correct(source_file, offenses)
+      return [source_file.source, 0] unless correcting?
+
+      correctable = offenses.select do |offense|
+        offense.correctable? && @configuration.autocorrect?(offense.rule_name)
+      end
+      result = Correction.apply(source_file, correctable)
+      write_file(source_file.path, result.source) if @options.mode == :fix && result.source != source_file.source
+      [result.source, result.applied]
+    end
+
+    def correcting?
+      %i[fix diff].include?(@options.mode)
+    end
+
+    def write_file(path, source)
+      File.write(path, source)
+    end
+
+    def formatter_for(mode, io)
+      klass = mode == :diff ? Formatters::DiffFormatter : FORMATTERS.fetch(@options.format, Formatters::ProgressFormatter)
+      klass.new(io)
+    end
+
+    def exit_code(reports)
+      threshold = SEVERITY_RANK.fetch(@options.fail_level.to_sym, 1)
+      return 0 if threshold.zero?
+
+      offending = reports.any? do |report|
+        report.offenses.any? { |o| SEVERITY_RANK.fetch(o.severity, 1) >= threshold }
+      end
+      offending ? 1 : 0
+    end
+
+    def build_configuration
+      config = ConfigLoader.load(explicit_path: @options.config_path)
+      return config if @options.rails.nil?
+
+      Configuration.new(ConfigLoader.deep_merge(config.raw, { "AllRules" => { "Rails" => @options.rails } }))
+    end
+  end
+end

data/lib/why_classes/source_file.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+
+module WhyClasses
+  # A single Ruby source file: its path, raw source and lazily-parsed AST.
+  class SourceFile
+    attr_reader :path
+
+    def self.from_path(path)
+      new(path, File.read(path))
+    end
+
+    def initialize(path, source)
+      @path = path
+      @source = source
+    end
+
+    attr_reader :source
+
+    def result
+      @result ||= Parser.parse(@source, @path)
+    end
+
+    def ast
+      result.ast
+    end
+
+    def buffer
+      result.buffer
+    end
+
+    def comments
+      result.comments
+    end
+
+    def parsed?
+      !ast.nil?
+    end
+
+    def parse_error
+      result.error
+    end
+  end
+end

data/lib/why_classes/version.rb

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

data/lib/why_classes.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "why_classes/version"
+require_relative "why_classes/parser"
+require_relative "why_classes/source_file"
+require_relative "why_classes/offense"
+require_relative "why_classes/ast/node_helpers"
+require_relative "why_classes/ast/class_shape"
+require_relative "why_classes/registry"
+require_relative "why_classes/rule"
+require_relative "why_classes/configuration"
+require_relative "why_classes/config_loader"
+require_relative "why_classes/disable_comments"
+require_relative "why_classes/correction"
+require_relative "why_classes/file_finder"
+
+# Rules self-register with the Registry when required.
+require_relative "why_classes/rules/data_bucket"
+require_relative "why_classes/rules/stateless_singleton_methods"
+require_relative "why_classes/rules/function_bucket"
+require_relative "why_classes/rules/invalid_initial_state"
+require_relative "why_classes/rules/inheritance_for_mixins"
+require_relative "why_classes/rules/single_attribute_reader"
+
+require_relative "why_classes/options"
+require_relative "why_classes/runner"
+require_relative "why_classes/cli"
+
+# why-classes detects the over-use of classes in Ruby (per Dave Thomas's talk)
+# and suggests/applies refactorings toward modules, composition, Struct and Data.
+module WhyClasses
+end