annotate_callbacks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 972243c4b3851cdbe9e9856027d52e0525be83d010d5c7d8ccb9a84acf647afe
+  data.tar.gz: '08e595601483bc43aa3b2c177dfbe1873dbdce029593048d3d270362dfe1726c'
+SHA512:
+  metadata.gz: e7bb6ae953a4458147133311a2ba92290f541e089e55decbd51fe1ca531dd9a157594045efd711e0d68a54e509444a3edbdfa869cb86d23508b4d526c205c3db
+  data.tar.gz: bce0d79758a6487d7507663bce8b398f5540d2fb7197af1127ee71d9520a75dd5ca6bb40e8b72309cbfcb984d76a808fe8f81315cde2fc47ec21e474519498c3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 sloppybook
+
+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,81 @@
+# AnnotateCallbacks
+
+Automatically annotate Rails model files with a comment block summarizing their ActiveRecord callbacks, including those inherited from concerns and parent classes.
+
+## Example Output
+
+```ruby
+# == Callbacks ==
+#
+#   before_validation  :normalize_email
+#   before_save        :encrypt_password
+#   before_save        :track_changes                        if: :changed?  [Trackable]
+#   after_create       :send_welcome_email
+#   after_create       (block: app/models/user.rb:18)
+#   after_save         :update_cache                         if: :name_changed?
+#   before_destroy     :check_admin
+#
+# == End Callbacks ==
+
+class User < ApplicationRecord
+  include Trackable
+
+  before_validation :normalize_email
+  before_save :encrypt_password
+  after_create -> { NotificationService.ping(self) }
+  # ...
+end
+```
+
+- Callbacks from concerns are shown with `[ConcernName]`
+- Block/lambda callbacks show source location: `(block: path:line)`
+- Internal framework callbacks (`autosave_associated_records_for_*`, `dependent: :destroy` etc.) are automatically filtered out
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+group :development do
+  gem "annotate_callbacks"
+end
+```
+
+```bash
+bundle install
+```
+
+## Usage
+
+```bash
+# Add callback annotations
+bundle exec rake callbacks:annotate
+
+# Remove callback annotations
+bundle exec rake callbacks:remove
+```
+
+## How It Works
+
+Uses `ApplicationRecord.descendants` and Rails runtime reflection (`_save_callbacks`, `_create_callbacks`, etc.) to detect all registered callbacks on each model class.
+
+- Callbacks defined in concerns are included, with source module shown as `[ModuleName]`
+- Block/lambda callbacks show relative source location: `(block: app/models/user.rb:10)`
+- Symbol conditions (`if: :active?`) are shown; Proc conditions are omitted
+- Internal framework callbacks are filtered out by name pattern and source module
+- Abstract classes are skipped
+- Files are written atomically (Tempfile + mv)
+- `rake callbacks:annotate` requires Rails environment; `rake callbacks:remove` does not
+
+## Development
+
+```bash
+git clone https://github.com/sloppybook/annotate_callbacks.git
+cd annotate_callbacks
+bundle install
+bundle exec rspec
+```
+
+## License
+
+[MIT License](LICENSE.txt)

data/lib/annotate_callbacks/annotator.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "fileutils"
+
+module AnnotateCallbacks
+  class Annotator
+    ANNOTATION_START = "# == Callbacks =="
+    ANNOTATION_END   = "# == End Callbacks =="
+    ANNOTATION_REGEX = /^#{Regexp.escape(ANNOTATION_START)}\n(.*?)^#{Regexp.escape(ANNOTATION_END)}\n\n?/m
+    MODEL_DIR = "app/models"
+
+    def annotate(model_class, file_path)
+      callbacks = Inspector.new(model_class).callbacks
+      return :skipped if callbacks.empty?
+
+      content = File.read(file_path, encoding: "UTF-8")
+      clean_content = content.sub(ANNOTATION_REGEX, "")
+
+      insert_pos = class_definition_line(clean_content)
+      return :skipped unless insert_pos
+
+      annotation = build_annotation(callbacks)
+      lines = clean_content.lines
+      insert_pos = skip_preceding_comments(lines, insert_pos)
+      lines.insert(insert_pos, annotation)
+      new_content = lines.join
+
+      return :unchanged if new_content == content
+
+      atomic_write(file_path, new_content)
+      :annotated
+    end
+
+    def remove_annotation(file_path)
+      content = File.read(file_path, encoding: "UTF-8")
+      return :skipped unless content.include?(ANNOTATION_START)
+
+      new_content = content.sub(ANNOTATION_REGEX, "")
+      return :unchanged if new_content == content
+
+      atomic_write(file_path, new_content)
+      :removed
+    end
+
+    def annotate_all
+      results = Hash.new { |h, k| h[k] = [] }
+
+      each_model do |model_class, file_path|
+        status = annotate(model_class, file_path)
+        results[status] << file_path
+      rescue StandardError => e
+        results[:errors] << { file: file_path, error: e.message }
+      end
+
+      results
+    end
+
+    def remove_all
+      results = Hash.new { |h, k| h[k] = [] }
+
+      Dir.glob(File.join(MODEL_DIR, "**", "*.rb")).sort.each do |file|
+        status = remove_annotation(file)
+        results[status] << file
+      rescue StandardError => e
+        results[:errors] << { file: file, error: e.message }
+      end
+
+      results
+    end
+
+    private
+
+    def each_model
+      ApplicationRecord.descendants.each do |klass|
+        next if klass.abstract_class?
+
+        file = source_file_for(klass)
+        next unless file
+
+        yield klass, file
+      end
+    end
+
+    def source_file_for(klass)
+      file = Object.const_source_location(klass.name)&.first if klass.name
+      return nil unless file
+
+      file.start_with?(project_model_dir) ? file : nil
+    end
+
+    def project_model_dir
+      @project_model_dir ||= File.expand_path(MODEL_DIR)
+    end
+
+    def class_definition_line(content)
+      content.lines.index { |line| line.match?(/\A\s*(class|module)\s+/) }
+    end
+
+    def skip_preceding_comments(lines, pos)
+      while pos > 0
+        prev = lines[pos - 1].strip
+        break unless prev.start_with?("#")
+        break if prev.match?(/^#.*(?:frozen_string_literal|encoding|warn_indent):/)
+        pos -= 1
+      end
+      pos
+    end
+
+    def atomic_write(file_path, content)
+      dir = File.dirname(file_path)
+      Tempfile.create(["annotate_callbacks", ".rb"], dir) do |tmp|
+        tmp.write(content)
+        tmp.flush
+        FileUtils.mv(tmp.path, file_path)
+      end
+    end
+
+    def build_annotation(callbacks)
+      max_type_len = callbacks.map { |c| c.type.length }.max
+      max_name_len = callbacks.map { |c| format_name(c).length }.max
+
+      lines = [ANNOTATION_START, "#"]
+      callbacks.each do |cb|
+        entry = "#   %-#{max_type_len}s  %-#{max_name_len}s" % [cb.type, format_name(cb)]
+        entry += "  #{cb.options}" if cb.options
+        entry += "  [#{cb.source}]" if cb.source
+        lines << entry.rstrip
+      end
+      lines << "#"
+      lines << ANNOTATION_END
+      lines.map { |l| "#{l}\n" }.join + "\n"
+    end
+
+    def format_name(cb)
+      cb.method_name.start_with?("(") ? cb.method_name : ":#{cb.method_name}"
+    end
+  end
+end

data/lib/annotate_callbacks/inspector.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module AnnotateCallbacks
+  class Inspector
+    CallbackEntry = Data.define(:type, :method_name, :options, :source)
+
+    CALLBACK_TYPES = %w[
+      initialize find touch validation
+      save create update destroy
+      commit rollback
+    ].freeze
+
+    INTERNAL_FILTER_PATTERNS = [
+      /\Aautosave_associated_records_for_/,
+    ].freeze
+
+    INTERNAL_BLOCK_PATHS = %w[
+      active_record/associations/builder/
+      active_record/timestamp
+      active_record/transactions
+      active_record/locking
+    ].freeze
+
+    INTERNAL_SOURCES = %w[
+      ActiveRecord::AutosaveAssociation
+      ActiveRecord::Timestamp
+      ActiveRecord::Transactions
+      ActiveRecord::Persistence
+      ActiveRecord::AttributeMethods::Dirty
+      ActiveRecord::Locking::Optimistic
+      ActiveRecord::CounterCache
+      ActiveRecord::Normalization
+      ActiveModel::Attributes::Normalization
+    ].freeze
+
+    def initialize(model_class)
+      @target = model_class
+    end
+
+    def callbacks
+      CALLBACK_TYPES
+        .flat_map { |type| extract_callbacks_for(type) }
+        .reject { |cb| internal?(cb) }
+    end
+
+    private
+
+    def extract_callbacks_for(type)
+      method_name = "_#{type}_callbacks"
+      return [] unless @target.respond_to?(method_name)
+
+      @target.send(method_name).filter_map { |cb| build_callback_info(cb, type) }
+    end
+
+    def build_callback_info(cb, type)
+      name = case cb.filter
+             when Symbol then cb.filter.to_s
+             when Proc then format_block(cb.filter)
+             else return nil
+             end
+
+      CallbackEntry.new(
+        type: "#{cb.kind}_#{type}",
+        method_name: name,
+        options: extract_options(cb),
+        source: detect_source(cb.filter)
+      )
+    end
+
+    def internal?(cb)
+      internal_by_name?(cb) || internal_by_block_path?(cb) || internal_by_source?(cb)
+    end
+
+    def internal_by_name?(cb)
+      INTERNAL_FILTER_PATTERNS.any? { |p| p.match?(cb.method_name) }
+    end
+
+    def internal_by_block_path?(cb)
+      return false unless cb.method_name.start_with?("(block:")
+
+      INTERNAL_BLOCK_PATHS.any? { |path| cb.method_name.include?(path) }
+    end
+
+    def internal_by_source?(cb)
+      cb.source && INTERNAL_SOURCES.any? { |s| cb.source.start_with?(s) }
+    end
+
+    def detect_source(filter)
+      return nil unless filter.is_a?(Symbol)
+      return nil unless @target.method_defined?(filter) || @target.private_method_defined?(filter)
+
+      owner = @target.instance_method(filter).owner
+      owner == @target ? nil : owner.name
+    rescue NameError
+      nil
+    end
+
+    def extract_options(cb)
+      if_conditions = extract_symbol_conditions(cb, :@if)
+      unless_conditions = extract_symbol_conditions(cb, :@unless)
+
+      parts = []
+      parts << "if: #{if_conditions.join(", ")}" if if_conditions.any?
+      parts << "unless: #{unless_conditions.join(", ")}" if unless_conditions.any?
+      parts.empty? ? nil : parts.join(", ")
+    end
+
+    def extract_symbol_conditions(cb, ivar)
+      (cb.instance_variable_get(ivar) || [])
+        .select { |c| c.is_a?(Symbol) }
+        .map { |c| ":#{c}" }
+    end
+
+    def format_block(proc_obj)
+      loc = proc_obj.source_location
+      return "(block)" unless loc
+
+      path = defined?(Rails) ? loc[0].sub("#{Rails.root}/", "") : loc[0]
+      "(block: #{path}:#{loc[1]})"
+    end
+  end
+end

data/lib/annotate_callbacks/railtie.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module AnnotateCallbacks
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      namespace :callbacks do
+        desc "Annotate callbacks in model files"
+        task annotate: :environment do
+          Rails.application.eager_load!
+
+          results = Annotator.new.annotate_all
+
+          puts "Annotated: #{results[:annotated].length} file(s)"
+          results[:annotated].each { |f| puts "  #{f}" }
+
+          if results[:errors].any?
+            puts "\nErrors: #{results[:errors].length}"
+            results[:errors].each { |e| puts "  #{e[:file]}: #{e[:error]}" }
+          end
+        end
+
+        desc "Remove callback annotations from model files"
+        task :remove do
+          results = Annotator.new.remove_all
+
+          puts "Removed: #{results[:removed].length} file(s)"
+          results[:removed].each { |f| puts "  #{f}" }
+
+          if results[:errors].any?
+            puts "\nErrors: #{results[:errors].length}"
+            results[:errors].each { |e| puts "  #{e[:file]}: #{e[:error]}" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/annotate_callbacks/version.rb

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

data/lib/annotate_callbacks.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "annotate_callbacks/version"
+require_relative "annotate_callbacks/inspector"
+require_relative "annotate_callbacks/annotator"
+
+module AnnotateCallbacks
+end
+
+require_relative "annotate_callbacks/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: annotate_callbacks
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- sloppybook
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Adds a comment block summarizing all ActiveRecord callbacks (including
+  those from concerns and parent classes) at the top of each model file using runtime
+  reflection.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/annotate_callbacks.rb
+- lib/annotate_callbacks/annotator.rb
+- lib/annotate_callbacks/inspector.rb
+- lib/annotate_callbacks/railtie.rb
+- lib/annotate_callbacks/version.rb
+homepage: https://github.com/sloppybook/annotate_callbacks
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sloppybook/annotate_callbacks
+  source_code_uri: https://github.com/sloppybook/annotate_callbacks
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Annotate ActiveRecord callbacks as comments in model files
+test_files: []