why-classes 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 49efb3c918546952656ce560c450af6b1789e75b2292311bc1775092e736a65c
+  data.tar.gz: a5fa304162f3af5851c059ce0e808340abfa9e08b0ea1174d430f7f252a20417
+SHA512:
+  metadata.gz: efbf0be84df9e152612e5bb3ea4142260471fbdec61b53487224c499b0b4dbfcd9ac10fbd72494843e4726e13c866391d6dcdbc95091e7fab8fee6117bb9b605
+  data.tar.gz: b0bc59250372fb99e49cf12909ed921bc2d86d70d3631b7a3dbb698acf6d8bb2e67249ab93377c6737a6306f67f7c5c63d2f7ebe46e0ba6e8ec3749e518fa83c

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Quaresma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,128 @@
+# why-classes
+
+> Not everything needs to be a class.
+
+`why-classes` is a linter and refactoring tool for Ruby, inspired by Dave Thomas's
+talk on the over-use of classes. Ruby gives you modules, composition, `Struct`, and
+`Data` — but reflex and framework habits push us toward classes even when a simpler
+construct would be clearer. This gem finds those "class smells" in a codebase (or a
+single file), explains each one, and can rewrite the mechanically-safe ones for you.
+
+It targets Rails codebases (with Rails-aware suppression and advice) but works on
+plain Ruby with no dependency on Rails or RuboCop.
+
+Under the hood it parses with [Prism](https://github.com/ruby/prism) (via
+`Prism::Translation::Parser`) and rewrites with the `parser` gem's `TreeRewriter`, so
+detection and autocorrection share one coordinate system.
+
+## The rules
+
+| Rule | Smell | Suggests | Autocorrect |
+|------|-------|----------|-------------|
+| `DataBucket` | `attr_*` + a field-assigning `initialize`, no behaviour | `Struct.new` / `Data.define` | ✅ `--fix` |
+| `StatelessSingletonMethods` | only `self.` methods, no state | `module` + `extend self` | advice |
+| `FunctionBucket` | a single `call`/`perform`/`run`, no state | `module_function` | advice |
+| `InvalidInitialState` | `initialize` leaves a field `nil`, needs a setter first | pass it in / drop the object | advice |
+| `InheritanceForMixins` | inheriting a fat base (`< ActiveRecord::Base`) for behaviour | include only the mixins you use | advice |
+| `SingleAttributeReader` | a method that only reads one field | a freestanding function | advice (off by default) |
+
+`attr_reader`-only buckets become immutable `Data.define`; `attr_accessor`/`attr_writer`
+buckets (mutation expected) become `Struct.new`.
+
+## Install
+
+```bash
+gem install why-classes
+# or in a Gemfile:
+gem "why-classes", group: :development
+```
+
+## Usage
+
+```bash
+why-classes                       # scan the current directory, report + suggest
+why-classes app/models/point.rb   # scan one file
+why-classes --diff app/           # preview the rewrites as a unified diff
+why-classes --fix app/            # apply the safe (DataBucket) rewrites
+why-classes --only DataBucket app # run a single rule
+why-classes --format json app     # machine-readable output
+why-classes --list-rules          # list every rule
+```
+
+Example:
+
+```
+app/models/point.rb:1:1: [DataBucket] [correctable] Point is a data bucket: it only stores fields and has no behaviour.
+  Replace the class with:
+      Point = Data.define(:x, :y)
+    Data objects are immutable and compare by value; `.new` keeps the same fields.
+```
+
+### Options
+
+| Flag | Meaning |
+|------|---------|
+| `--diff`, `--dry-run` | show a diff of proposed rewrites; write nothing |
+| `-a`, `--fix` | apply suggested (safe-tier) corrections and write files |
+| `--fix-unsafe` | also apply unsafe-tier corrections (reserved for future rules) |
+| `--only A,B` / `--except A,B` | select rules |
+| `--format progress\|clang\|json\|diff` | output format (default `progress`) |
+| `--config PATH` | use a specific `.why-classes.yml` |
+| `--[no-]rails` | toggle Rails awareness |
+| `--fail-level none\|convention\|warning` | CI exit-code threshold (default `convention`) |
+
+Exit codes: `0` clean (or below the fail level), `1` offenses found, `2` usage error.
+
+## Configuration
+
+Drop a `.why-classes.yml` at your project root; it is deep-merged over the defaults.
+
+```yaml
+AllRules:
+  Include: ["**/*.rb"]
+  Exclude: ["db/**/*", "vendor/**/*"]
+  Rails: true
+
+Rules:
+  DataBucket:
+    Enabled: true
+    Autocorrect: true
+    PreferData: false        # true => always emit Data.define, even for accessors
+  FunctionBucket:
+    MethodNames: [call, perform, run, execute]
+  SingleAttributeReader:
+    Enabled: true            # opt in to the noisy one
+```
+
+### Inline suppression
+
+```ruby
+# why-classes:disable DataBucket
+class LegacyThing            # not flagged anywhere in this file
+end
+
+class CreateUser # why-classes:disable-line FunctionBucket
+  def call = :ok
+end
+```
+
+## Safety
+
+Autocorrection is opt-in and reviewable. `--fix` only touches `DataBucket`, the most
+mechanical transform, and even then it **bails to advice-only** when a superclass,
+default arguments, extra `initialize` logic, real behaviour, or metaprogramming is
+present. Every rewrite is re-parsed with Prism and discarded if it would produce
+invalid Ruby. Converting a class changes its public shape (`Data` is immutable, `==`
+becomes value equality) — always review the diff.
+
+## Development
+
+```bash
+bin/setup        # or: bundle install
+bundle exec rspec
+bundle exec exe/why-classes lib   # dogfood
+```
+
+## License
+
+MIT.

data/config/default.yml

@@ -0,0 +1,69 @@
+# Default configuration for why-classes.
+# A project `.why-classes.yml` is deep-merged over this file.
+
+AllRules:
+  Include:
+    - "**/*.rb"
+  Exclude:
+    - "db/**/*"
+    - "vendor/**/*"
+    - "node_modules/**/*"
+    - "tmp/**/*"
+    - "spec/fixtures/**/*"
+    - "test/fixtures/**/*"
+  # Rails-aware suppression and advice. Harmless on plain-Ruby projects.
+  Rails: true
+
+Rules:
+  DataBucket:
+    Enabled: true
+    Autocorrect: true          # Suggested-tier: eligible for --fix
+    # attr_reader-only buckets become Data.define; attr_accessor/attr_writer
+    # (mutation expected) become Struct.new. Set PreferData: true to always
+    # emit Data.define regardless of mutability.
+    PreferData: false
+
+  StatelessSingletonMethods:
+    Enabled: true
+    Autocorrect: false         # Unsafe-tier: advice-only for now (--fix-unsafe later)
+
+  FunctionBucket:
+    Enabled: true
+    Autocorrect: false
+    MethodNames:
+      - call
+      - perform
+      - run
+      - execute
+
+  InheritanceForMixins:
+    Enabled: true              # advice only
+
+  InvalidInitialState:
+    Enabled: true              # advice only
+
+  SingleAttributeReader:
+    Enabled: false             # noisy; opt-in
+
+Rails:
+  # Subclasses of these legitimately must be classes -> suppress the
+  # "shouldn't be a class" family of rules on them.
+  FrameworkBaseClasses:
+    - ActiveRecord::Base
+    - ApplicationRecord
+    - ActionController::Base
+    - ApplicationController
+    - ActionController::API
+    - ActiveJob::Base
+    - ApplicationJob
+    - ActionMailer::Base
+    - ApplicationMailer
+    - ActiveModel::Serializer
+  # Lean mixins suggested by InheritanceForMixins.
+  MixinSuggestions:
+    ActiveRecord::Base:
+      - ActiveModel::Model
+      - ActiveModel::Validations
+    ApplicationRecord:
+      - ActiveModel::Model
+      - ActiveModel::Validations

data/exe/why-classes

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

data/lib/why_classes/ast/class_shape.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "node_helpers"
+
+module WhyClasses
+  module AST
+    # A computed-once summary of a single class (or module) node. Rules read a
+    # ClassShape instead of re-walking the AST.
+    class ClassShape
+      H = NodeHelpers
+
+      attr_reader :node
+
+      def initialize(node)
+        @node = node
+      end
+
+      def module?
+        node.type == :module
+      end
+
+      def name
+        @name ||= H.class_name(node)
+      end
+
+      def superclass
+        return nil if module?
+
+        @superclass ||= H.superclass_path(node)
+      end
+
+      def superclass?
+        !superclass.nil?
+      end
+
+      def instance_methods
+        @instance_methods ||= H.instance_methods(node)
+      end
+
+      def instance_method_names
+        instance_methods.map { |m| m.children[0] }
+      end
+
+      def singleton_methods
+        @singleton_methods ||= H.singleton_methods(node)
+      end
+
+      def singleton_method_names
+        singleton_methods.map { |m| m.children[1] || m.children[0] }
+      end
+
+      def initialize_method
+        @initialize_method ||= H.initialize_method(node)
+      end
+
+      def attr_macros
+        @attr_macros ||= H.attr_macros(node)
+      end
+
+      def attr_fields
+        @attr_fields ||= H.attr_fields(node)
+      end
+
+      # Body statements that are neither method defs, attr macros, nor bare
+      # comments -- e.g. constants, includes, other macro calls.
+      def other_statements
+        @other_statements ||= begin
+          skip = instance_methods + singleton_methods
+          H.body_statements(H.class_body(node)).reject do |s|
+            skip.include?(s) ||
+              (H.node?(s) && s.type == :send && %i[attr_reader attr_writer attr_accessor].include?(s.children[1]))
+          end.select { |s| H.node?(s) }
+        end
+      end
+
+      def uses_metaprogramming?
+        return @meta if defined?(@meta)
+
+        @meta = H.uses_metaprogramming?(node)
+      end
+
+      def instance_variables_written
+        @ivw ||= H.ivars_assigned(node)
+      end
+
+      def instance_variables_read
+        @ivr ||= H.ivars_read(node)
+      end
+
+      # Instance methods other than initialize.
+      def behavior_methods
+        instance_methods.reject { |m| m.children[0] == :initialize }
+      end
+
+      # A class "has state" if it stores instance variables that are not merely
+      # the constructor writing attr-backed fields.
+      def stateful?
+        !instance_variables_written.empty? || !instance_variables_read.empty?
+      end
+
+      def location
+        node.location
+      end
+    end
+  end
+end

data/lib/why_classes/ast/node_helpers.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module WhyClasses
+  module AST
+    # Predicates over the parser-gem AST. Every helper operates on the *direct*
+    # body of a class/module node and never recurses into nested classes, so a
+    # rule handling an outer class does not accidentally analyse an inner one.
+    module NodeHelpers
+      module_function
+
+      Node = ::Parser::AST::Node
+
+      def node?(obj)
+        obj.is_a?(Node)
+      end
+
+      # The list of top-level statements in a class/module/def body.
+      def body_statements(body)
+        return [] if body.nil?
+        return body.children if body.type == :begin
+
+        [body]
+      end
+
+      # Body node of a :class (children[2]) or :module (children[1]).
+      def class_body(class_node)
+        class_node.type == :module ? class_node.children[1] : class_node.children[2]
+      end
+
+      # "Foo::Bar" for a const node, else nil.
+      def const_path(const_node)
+        return nil unless node?(const_node) && const_node.type == :const
+
+        scope, name = const_node.children
+        scope.nil? ? name.to_s : "#{const_path(scope)}::#{name}"
+      end
+
+      def class_name(class_node)
+        const_path(class_node.children[0])
+      end
+
+      # Superclass const path for a :class node, or nil.
+      def superclass_path(class_node)
+        return nil unless class_node.type == :class
+
+        const_path(class_node.children[1])
+      end
+
+      # Instance method definitions declared directly in the body (:def).
+      def instance_methods(class_node)
+        body_statements(class_body(class_node)).select { |n| node?(n) && n.type == :def }
+      end
+
+      # Singleton methods: `def self.foo` (:defs) plus methods inside
+      # `class << self` (:sclass) blocks.
+      def singleton_methods(class_node)
+        stmts = body_statements(class_body(class_node))
+        defs = stmts.select { |n| node?(n) && n.type == :defs }
+        sclass_defs = stmts.select { |n| node?(n) && n.type == :sclass }
+                           .flat_map { |sc| body_statements(sc.children[1]) }
+                           .select { |n| node?(n) && n.type == :def }
+        defs + sclass_defs
+      end
+
+      # attr_reader/attr_writer/attr_accessor macro calls -> flat list of field
+      # symbols keyed by macro name.
+      def attr_macros(class_node)
+        result = { attr_reader: [], attr_writer: [], attr_accessor: [] }
+        body_statements(class_body(class_node)).each do |stmt|
+          next unless node?(stmt) && stmt.type == :send && stmt.children[0].nil?
+
+          macro = stmt.children[1]
+          next unless result.key?(macro)
+
+          fields = stmt.children[2..].select { |a| node?(a) && a.type == :sym }.map { |a| a.children[0] }
+          result[macro].concat(fields)
+        end
+        result
+      end
+
+      # All field symbols exposed by any attr_* macro.
+      def attr_fields(class_node)
+        attr_macros(class_node).values.flatten.uniq
+      end
+
+      # Instance variables assigned anywhere in the subtree.
+      def ivars_assigned(node)
+        collect(node) { |n| n.type == :ivasgn }.map { |n| n.children[0] }.uniq
+      end
+
+      # Instance variables read anywhere in the subtree.
+      def ivars_read(node)
+        collect(node) { |n| n.type == :ivar }.map { |n| n.children[0] }.uniq
+      end
+
+      # Names of `def initialize` in the body.
+      def initialize_method(class_node)
+        instance_methods(class_node).find { |m| m.children[0] == :initialize }
+      end
+
+      # True when initialize only assigns instance variables straight from its
+      # own parameters (no logic, no defaults, no computed values).
+      def initialize_only_assigns_params?(class_node)
+        init = initialize_method(class_node)
+        return false unless init
+
+        params = param_names(init.children[1])
+        # No default values / splats / blocks allowed.
+        return false unless simple_params?(init.children[1])
+
+        assignments = body_statements(init.children[2])
+        return false if assignments.empty?
+
+        assignments.all? do |stmt|
+          node?(stmt) && stmt.type == :ivasgn &&
+            (value = stmt.children[1]) &&
+            value.type == :lvar &&
+            params.include?(value.children[0])
+        end
+      end
+
+      # Parameter names of an :args node.
+      def param_names(args_node)
+        return [] unless node?(args_node)
+
+        args_node.children.map { |a| a.children[0] }
+      end
+
+      # True when every parameter is a plain required positional (:arg) or
+      # required keyword (:kwarg) -- no defaults, splats, or blocks.
+      def simple_params?(args_node)
+        return true if args_node.nil?
+
+        args_node.children.all? { |a| node?(a) && %i[arg kwarg].include?(a.type) }
+      end
+
+      # True when all parameters are keyword arguments.
+      def keyword_params?(args_node)
+        return false if args_node.nil? || args_node.children.empty?
+
+        args_node.children.all? { |a| node?(a) && %i[kwarg kwoptarg].include?(a.type) }
+      end
+
+      METAPROGRAMMING_SENDS = %i[
+        define_method define_singleton_method instance_variable_set
+        instance_variable_get method_missing respond_to_missing?
+        class_eval instance_eval module_eval const_set
+        attr define_attribute_methods
+      ].freeze
+
+      # Static analysis is unreliable in the presence of metaprogramming, so any
+      # rule that would rewrite code must bail to advice-only when this is true.
+      def uses_metaprogramming?(class_node)
+        collect(class_node) do |n|
+          (n.type == :send && METAPROGRAMMING_SENDS.include?(n.children[1])) ||
+            n.type == :def && %i[method_missing respond_to_missing?].include?(n.children[0])
+        end.any?
+      end
+
+      # Recursively collect nodes matching the block. By default the walk stays
+      # within the current type definition: it descends into method bodies
+      # (def/defs) and `class << self` (sclass) but not into *nested* class or
+      # module definitions, so a class's analysis never bleeds into an inner one.
+      def collect(node, cross_scopes: false, &block)
+        found = []
+        walk_local(node, cross_scopes, found, &block)
+        found
+      end
+
+      NESTED_SCOPE_TYPES = %i[class module].freeze
+
+      def walk_local(node, cross_scopes, found, &block)
+        return unless node?(node)
+
+        found << node if block.call(node)
+        node.children.each do |child|
+          next unless node?(child)
+          next if !cross_scopes && NESTED_SCOPE_TYPES.include?(child.type)
+
+          walk_local(child, cross_scopes, found, &block)
+        end
+      end
+      private_class_method :walk_local
+    end
+  end
+end

data/lib/why_classes/cli.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "version"
+require_relative "options"
+require_relative "runner"
+require_relative "registry"
+
+module WhyClasses
+  # Command-line entry point. Parses ARGV into Options, runs, returns an exit code.
+  class CLI
+    VALID_FORMATS = %w[progress clang json diff].freeze
+    VALID_FAIL_LEVELS = %w[none convention warning].freeze
+
+    def initialize(argv, io: $stdout, err: $stderr)
+      @argv = argv
+      @io = io
+      @err = err
+    end
+
+    def run
+      overrides = parse_options
+      return @early_exit if @early_exit
+
+      options = Options.defaults(**overrides, paths: @argv)
+      Runner.new(options).run(io: @io)
+    rescue OptionParser::ParseError => e
+      @err.puts "why-classes: #{e.message}"
+      2
+    rescue StandardError => e
+      @err.puts "why-classes: #{e.class}: #{e.message}"
+      2
+    end
+
+    private
+
+    def parse_options # rubocop:disable Metrics/MethodLength
+      overrides = {}
+      parser.parse!(@argv)
+      apply_validations(overrides)
+      overrides
+    rescue SystemExit
+      overrides
+    end
+
+    def parser # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+      @collected ||= {}
+      OptionParser.new do |o|
+        o.banner = "Usage: why-classes [options] [paths...]"
+
+        o.on("--diff", "--dry-run", "Show a diff of proposed rewrites; write nothing") { @collected[:mode] = :diff }
+        o.on("-a", "--fix", "Apply suggested (safe-tier) corrections and write files") { @collected[:mode] = :fix }
+        o.on("--fix-unsafe", "Also apply unsafe-tier corrections") { @collected[:fix_unsafe] = true }
+        o.on("--only RULES", Array, "Run only these rules") { |v| @collected[:only] = v }
+        o.on("--except RULES", Array, "Skip these rules") { |v| @collected[:except] = v }
+        o.on("--format FORMAT", "Output format: #{VALID_FORMATS.join(', ')}") { |v| @collected[:format] = v }
+        o.on("--config PATH", "Path to a .why-classes.yml") { |v| @collected[:config_path] = v }
+        o.on("--[no-]rails", "Toggle Rails awareness") { |v| @collected[:rails] = v }
+        o.on("--fail-level LEVEL", "CI exit threshold: #{VALID_FAIL_LEVELS.join(', ')}") { |v| @collected[:fail_level] = v }
+        o.on("--list-rules", "List all rules and exit") { list_rules_and_exit }
+        o.on("-v", "--version", "Print version and exit") { print_version_and_exit }
+        o.on("-h", "--help", "Print this help and exit") { print_help_and_exit(o) }
+      end
+    end
+
+    def apply_validations(overrides)
+      overrides.merge!(@collected)
+      if overrides[:format] && !VALID_FORMATS.include?(overrides[:format])
+        raise OptionParser::InvalidArgument, "unknown format #{overrides[:format].inspect}"
+      end
+      if overrides[:fail_level] && !VALID_FAIL_LEVELS.include?(overrides[:fail_level])
+        raise OptionParser::InvalidArgument, "unknown fail-level #{overrides[:fail_level].inspect}"
+      end
+    end
+
+    def list_rules_and_exit
+      Registry.all.sort_by(&:rule_name).each do |rule|
+        mark = rule.autocorrectable? ? "[correctable]" : "[advice]    "
+        @io.puts "#{mark} #{rule.rule_name.ljust(28)} #{rule.description}"
+      end
+      @early_exit = 0
+      raise SystemExit
+    end
+
+    def print_version_and_exit
+      @io.puts WhyClasses::VERSION
+      @early_exit = 0
+      raise SystemExit
+    end
+
+    def print_help_and_exit(parser)
+      @io.puts parser
+      @early_exit = 0
+      raise SystemExit
+    end
+  end
+end

data/lib/why_classes/config_loader.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "configuration"
+
+module WhyClasses
+  # Loads config/default.yml and deep-merges a project .why-classes.yml over it.
+  module ConfigLoader
+    DEFAULT_PATH = File.expand_path("../../config/default.yml", __dir__)
+    PROJECT_FILE = ".why-classes.yml"
+
+    module_function
+
+    def load(explicit_path: nil, start_dir: Dir.pwd)
+      base = read(DEFAULT_PATH)
+      project = explicit_path ? read(explicit_path) : read(discover(start_dir))
+      Configuration.new(deep_merge(base, project))
+    end
+
+    # Walk up from start_dir looking for .why-classes.yml.
+    def discover(start_dir)
+      dir = File.expand_path(start_dir)
+      loop do
+        candidate = File.join(dir, PROJECT_FILE)
+        return candidate if File.file?(candidate)
+
+        parent = File.dirname(dir)
+        break if parent == dir
+
+        dir = parent
+      end
+      nil
+    end
+
+    def read(path)
+      return {} if path.nil? || !File.file?(path)
+
+      YAML.safe_load_file(path) || {}
+    end
+
+    def deep_merge(base, override)
+      base.merge(override) do |_key, base_val, over_val|
+        if base_val.is_a?(Hash) && over_val.is_a?(Hash)
+          deep_merge(base_val, over_val)
+        else
+          over_val
+        end
+      end
+    end
+  end
+end