annotaterb 4.4.1 → 4.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a337f543f32142efaffbfd396196692d42a98438352b3bdd406c104c25a9958a
-  data.tar.gz: 27d091e7fed5953ccdd26c4b4874e45a0fcff541630595fa467e010629efb9ba
+  metadata.gz: 2c9e326fa73164a6a2e43edc402e6990cfbb5d953ac5fd1ccf8c71fa6d358ee1
+  data.tar.gz: dabf1afd54a8dec7a96ed8c259ca84e0a6085618713be78f43f075a51a22db7f
 SHA512:
-  metadata.gz: 44125b3f65246ad1b5a0dd0d354487462ea6584c6147165650268244fd8d3c9826cf337873f24c31e008efa1c560b37bcb71e36af7fc05c9bc381d48e2b1e4b0
-  data.tar.gz: 7979e2309e3c09ee11fc090a424e7006a94634c7a970fe34b61028b3a90d495b684cc2a4a6fa78221b288dfe5e6682567835fb6839ada3903dfaa599a4f8cfdc
+  metadata.gz: 12e277c2d09e37e1001e64b0f08542ff03981bf5bbe37e86ed3dca01b1ec52c5b1805ce6f5cb1a8e5b25c3b9d655cb2345d0c9d878ecf4ae6bbfd265870445ac
+  data.tar.gz: 88d7c9ba17c3abbf38e635365314d1c4b372e67ec5ef0dcba9f7f4f5b6ef90d0e285a2150887127fa75f847a1ee2e8e4c7a30548729a4f903cf71f42be793177

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [v4.5.0](https://github.com/drwl/annotaterb/tree/v4.5.0) (2024-02-08)
+
+[Full Changelog](https://github.com/drwl/annotaterb/compare/v4.4.1...v4.5.0)
+
+**Closed issues:**
+
+- Add an automated way to migrate from the old annotate gem [\#73](https://github.com/drwl/annotaterb/issues/73)
+- Default array value is double-quoted/escaped [\#57](https://github.com/drwl/annotaterb/issues/57)
+
+**Merged pull requests:**
+
+- Bump version to v4.5.0 [\#79](https://github.com/drwl/annotaterb/pull/79) ([drwl](https://github.com/drwl))
+- Update README on the new Rails generator commands [\#78](https://github.com/drwl/annotaterb/pull/78) ([drwl](https://github.com/drwl))
+- Bump github/codeql-action from 2 to 3 [\#77](https://github.com/drwl/annotaterb/pull/77) ([dependabot[bot]](https://github.com/apps/dependabot))
+- Add command to generate a configuration file [\#76](https://github.com/drwl/annotaterb/pull/76) ([drwl](https://github.com/drwl))
+- Bump actions/checkout from 3 to 4 [\#75](https://github.com/drwl/annotaterb/pull/75) ([dependabot[bot]](https://github.com/apps/dependabot))
+- CI: Configure dependabot to update GH Actions [\#74](https://github.com/drwl/annotaterb/pull/74) ([olleolleolle](https://github.com/olleolleolle))
+- Refactor `FileBuilder` and `MagicCommentParser` [\#71](https://github.com/drwl/annotaterb/pull/71) ([drwl](https://github.com/drwl))
+- Test running annotations after a migration [\#70](https://github.com/drwl/annotaterb/pull/70) ([drwl](https://github.com/drwl))
+- Add integration test for rake task installer [\#69](https://github.com/drwl/annotaterb/pull/69) ([drwl](https://github.com/drwl))
+- Add integration test for annotating routes [\#68](https://github.com/drwl/annotaterb/pull/68) ([drwl](https://github.com/drwl))
+- Remove optional args [\#67](https://github.com/drwl/annotaterb/pull/67) ([drwl](https://github.com/drwl))
+- Remove optional arg from `AnnotationPatternGenerator` [\#66](https://github.com/drwl/annotaterb/pull/66) ([drwl](https://github.com/drwl))
+- Remove `ARGV` use during runtime [\#65](https://github.com/drwl/annotaterb/pull/65) ([drwl](https://github.com/drwl))
+- Add integration test for annotating a singular file [\#64](https://github.com/drwl/annotaterb/pull/64) ([drwl](https://github.com/drwl))
+- Generate changelog for v4.4.1 [\#63](https://github.com/drwl/annotaterb/pull/63) ([drwl](https://github.com/drwl))
+- Add support for factory\_bot's default suffixed pattern [\#59](https://github.com/drwl/annotaterb/pull/59) ([drwl](https://github.com/drwl))
+
+## [v4.4.1](https://github.com/drwl/annotaterb/tree/v4.4.1) (2023-09-11)
+
+[Full Changelog](https://github.com/drwl/annotaterb/compare/v4.4.0...v4.4.1)
+
+**Merged pull requests:**
+
+- Bump version to v4.4.1 [\#62](https://github.com/drwl/annotaterb/pull/62) ([drwl](https://github.com/drwl))
+- Fix annotation for columns with `Date` and `DateTime` default values [\#61](https://github.com/drwl/annotaterb/pull/61) ([drwl](https://github.com/drwl))
+- Add integration tests [\#60](https://github.com/drwl/annotaterb/pull/60) ([drwl](https://github.com/drwl))
+- Fix the default array value from being escaped [\#58](https://github.com/drwl/annotaterb/pull/58) ([drwl](https://github.com/drwl))
+- Update dummyapp Rails version [\#56](https://github.com/drwl/annotaterb/pull/56) ([drwl](https://github.com/drwl))
+- Bump puma from 5.6.5 to 6.3.1 in /dummyapp [\#55](https://github.com/drwl/annotaterb/pull/55) ([dependabot[bot]](https://github.com/apps/dependabot))
+- Generate changelog for v4.4.0 [\#53](https://github.com/drwl/annotaterb/pull/53) ([drwl](https://github.com/drwl))
+- Add CLI specs using `aruba` gem [\#43](https://github.com/drwl/annotaterb/pull/43) ([drwl](https://github.com/drwl))
+
 ## [v4.4.0](https://github.com/drwl/annotaterb/tree/v4.4.0) (2023-06-24)
 
 [Full Changelog](https://github.com/drwl/annotaterb/compare/v4.3.1...v4.4.0)

data/README.md

@@ -65,6 +65,35 @@ To skip the automatic annotation that happens after a db task, pass the environm
 $ ANNOTATERB_SKIP_ON_DB_TASKS=1 bin/rails db:migrate
 ```
 
+### Added Rails generators
+The following Rails generator commands get added.
+
+```sh
+$ bin/rails generator --help
+
+...
+
+AnnotateRb:
+  annotate_rb:config
+  annotate_rb:hook
+  annotate_rb:install
+  annotate_rb:update_config
+...
+
+```
+
+`bin/rails g annotate_rb:config`
+- Generates a new configuration file, `.annotaterb.yml`, using defaults from the gem.
+
+`bin/rails g annotate_rb:hook`
+- Installs the Rake file to automatically annotate Rails models on a database task (e.g. AnnotateRb will automatically run after running `bin/rails db:migrate`).
+
+`bin/rails g annotate_rb:install`
+- Runs the `config` and `hook` generator commands
+
+`bin/rails g annotate_rb:update_config`
+- Appends to `.annotaterb.yml` any configuration key-value pairs that are used by the Gem. This is useful when there's a drift between the config file values and the gem defaults (i.e. when new features get added).
+
 ## Migrating from the annotate gem
 Refer to the [migration guide](MIGRATION_GUIDE.md).
 

data/VERSION

@@ -1 +1 @@
-4.4.1
+4.6.0

data/lib/annotate_rb/config_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  class ConfigGenerator
+    class << self
+      # Returns unset configuration key-value pairs as yaml.
+      # Useful when a config file was generated an older version of gem and new
+      #   settings get added.
+      def unset_config_defaults
+        user_defaults = ConfigLoader.load_config
+        defaults = Options.from({}, {}).to_h
+
+        differences = defaults.keys - user_defaults.keys
+        result = defaults.slice(*differences)
+
+        # Generates proper YAML including the leading hyphens `---` header
+        yml_content = YAML.dump(result, StringIO.new).string
+        # Remove the header
+        yml_content.sub("---", "")
+      end
+
+      def default_config_yml
+        defaults_hash = Options.from({}, {}).to_h
+        _yml_content = YAML.dump(defaults_hash, StringIO.new).string
+      end
+    end
+  end
+end

data/lib/annotate_rb/eager_loader.rb

@@ -8,8 +8,12 @@ module AnnotateRb
         options[:require].count > 0 && options[:require].each { |path| require path }
 
         if defined?(::Rails::Application)
-          klass = ::Rails::Application.send(:subclasses).first
-          klass.eager_load!
+          if defined?(::Zeitwerk)
+            # Delegate to Zeitwerk to load stuff as needed
+          else
+            klass = ::Rails::Application.send(:subclasses).first
+            klass.eager_load!
+          end
         else
           options[:model_dir].each do |dir|
             ::Rake::FileList["#{dir}/**/*.rb"].each do |fname|

data/lib/annotate_rb/model_annotator/annotated_file/generator.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module AnnotatedFile
+      # Generates the file with fresh annotations
+      class Generator
+        def initialize(file_content, new_annotations, annotation_position, options)
+          @annotation_position = annotation_position
+          @options = options
+
+          @new_wrapped_annotations = wrapped_content(new_annotations)
+
+          @new_annotations = new_annotations
+          @file_content = file_content
+
+          @parsed_file = FileParser::ParsedFile.new(@file_content, @new_annotations, options).parse
+        end
+
+        # @return [String] Returns the annotated file content to be written back to a file
+        def generate
+          # Need to keep `.to_s` for now since the it can be either a String or Symbol
+          annotation_write_position = @options[@annotation_position].to_s
+
+          # New method: first remove annotations
+          content_without_annotations = if @parsed_file.has_annotations?
+            @file_content.sub(@parsed_file.annotations_with_whitespace, "")
+          elsif @options[:force]
+            @file_content.sub(@parsed_file.annotations_with_whitespace, "")
+          else
+            @file_content
+          end
+
+          # We need to get class start and class end depending on the position
+          parsed = FileParser::CustomParser.new(content_without_annotations, "", 0).tap(&:parse)
+
+          _content = if %w[after bottom].include?(annotation_write_position)
+            content_annotated_after(parsed, content_without_annotations)
+          else
+            content_annotated_before(parsed, content_without_annotations, annotation_write_position)
+          end
+        end
+
+        private
+
+        def content_annotated_before(parsed, content_without_annotations, write_position)
+          same_write_position = @parsed_file.has_annotations? && @parsed_file.annotation_position.to_s == write_position
+
+          # Could error if there's no class or module declaration
+          _constant_name, line_number_before = parsed.starts.first
+
+          content_with_annotations_written_before = []
+          content_with_annotations_written_before << content_without_annotations.lines[0...line_number_before]
+          content_with_annotations_written_before << $/ if @parsed_file.has_leading_whitespace? && same_write_position
+          content_with_annotations_written_before << @new_wrapped_annotations.lines
+          content_with_annotations_written_before << $/ if @parsed_file.has_trailing_whitespace? && same_write_position
+          content_with_annotations_written_before << content_without_annotations.lines[line_number_before..]
+
+          content_with_annotations_written_before.join
+        end
+
+        def content_annotated_after(parsed, content_without_annotations)
+          _constant_name, line_number_after = parsed.ends.last
+
+          content_with_annotations_written_after = []
+          content_with_annotations_written_after << content_without_annotations.lines[0..line_number_after]
+          content_with_annotations_written_after << $/
+          content_with_annotations_written_after << @new_wrapped_annotations.lines
+          content_with_annotations_written_after << content_without_annotations.lines[(line_number_after + 1)..]
+
+          content_with_annotations_written_after.join
+        end
+
+        def wrapped_content(content)
+          wrapper_open = if @options[:wrapper_open]
+            "# #{@options[:wrapper_open]}\n"
+          else
+            ""
+          end
+
+          wrapper_close = if @options[:wrapper_close]
+            "# #{@options[:wrapper_close]}\n"
+          else
+            ""
+          end
+
+          _wrapped_info_block = "#{wrapper_open}#{content}#{wrapper_close}"
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/annotated_file/updater.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module AnnotatedFile
+      # Updates existing annotations
+      class Updater
+        def initialize(file_content, new_annotations, _annotation_position, options)
+          @options = options
+
+          @new_annotations = new_annotations
+          @file_content = file_content
+
+          @parsed_file = FileParser::ParsedFile.new(@file_content, @new_annotations, options).parse
+        end
+
+        # @return [String] Returns the annotated file content to be written back to a file
+        def update
+          return "" if !@parsed_file.has_annotations?
+
+          new_annotation = wrapped_content(@new_annotations)
+
+          _content = @file_content.sub(@parsed_file.annotations, new_annotation)
+        end
+
+        private
+
+        def wrapped_content(content)
+          wrapper_open = if @options[:wrapper_open]
+            "# #{@options[:wrapper_open]}\n"
+          else
+            ""
+          end
+
+          wrapper_close = if @options[:wrapper_close]
+            "# #{@options[:wrapper_close]}\n"
+          else
+            ""
+          end
+
+          _wrapped_info_block = "#{wrapper_open}#{content}#{wrapper_close}"
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/annotated_file.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module AnnotatedFile
+      autoload :Generator, "annotate_rb/model_annotator/annotated_file/generator"
+      autoload :Updater, "annotate_rb/model_annotator/annotated_file/updater"
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/annotator.rb

@@ -4,11 +4,11 @@ module AnnotateRb
   module ModelAnnotator
     class Annotator
       class << self
-        def do_annotations(options = {})
+        def do_annotations(options)
           new(options).do_annotations
         end
 
-        def remove_annotations(options = {})
+        def remove_annotations(options)
           new(options).remove_annotations
         end
       end

data/lib/annotate_rb/model_annotator/file_name_resolver.rb

@@ -5,8 +5,13 @@ module AnnotateRb
     class FileNameResolver
       class << self
         def call(filename_template, model_name, table_name)
+          # e.g. with a model file name like "app/models/collapsed/example/test_model.rb"
+          # and using a collapsed `model_name` such as "collapsed/test_model"
+          model_name_without_namespace = model_name.split("/").last
+
           filename_template
             .gsub("%MODEL_NAME%", model_name)
+            .gsub("%MODEL_NAME_WITHOUT_NS%", model_name_without_namespace)
             .gsub("%PLURALIZED_MODEL_NAME%", model_name.pluralize)
             .gsub("%TABLE_NAME%", table_name || model_name.pluralize)
         end

data/lib/annotate_rb/model_annotator/file_parser/annotation_finder.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    module FileParser
+      class AnnotationFinder
+        COMPAT_PREFIX = "== Schema Info"
+        COMPAT_PREFIX_MD = "## Schema Info"
+        DEFAULT_ANNOTATION_ENDING = "#"
+
+        class MalformedAnnotation < StandardError; end
+
+        class NoAnnotationFound < StandardError; end
+
+        # Returns the line index (not the line number) that the annotation starts.
+        attr_reader :annotation_start
+        # Returns the line index (not the line number) that the annotation ends, inclusive.
+        attr_reader :annotation_end
+
+        attr_reader :parser
+
+        def initialize(content, wrapper_open, wrapper_close)
+          @content = content
+          @wrapper_open = wrapper_open
+          @wrapper_close = wrapper_close
+          @annotation_start = nil
+          @annotation_end = nil
+          @parser = nil
+        end
+
+        # Find the annotation's line start and line end
+        def run
+          # CustomParser returns line numbers as 0-indexed
+          @parser = FileParser::CustomParser.new(@content, "", 0).tap(&:parse)
+          comments = @parser.comments
+
+          start = comments.find_index { |comment, _| comment.include?(COMPAT_PREFIX) || comment.include?(COMPAT_PREFIX_MD) }
+          raise NoAnnotationFound if start.nil? # Stop execution because we did not find
+
+          if @wrapper_open
+            prev_comment, _prev_line_number = comments[start - 1]
+
+            # Change start to the line before if wrapper_open is defined and we find the wrapper open comment
+            if prev_comment&.include?(@wrapper_open)
+              start -= 1
+            end
+          end
+
+          # Find a contiguous block of comments from the starting point
+          ending = start
+          while ending < comments.size - 1
+            _comment, line_number = comments[ending]
+            _next_comment, next_line_number = comments[ending + 1]
+
+            if next_line_number - line_number == 1
+              ending += 1
+            else
+              break
+            end
+          end
+
+          raise MalformedAnnotation if start == ending
+
+          if @wrapper_close
+            if comments[ending].first.include?(@wrapper_close)
+              # We can end here because it's the end of the annotation block
+            else
+              # Walk back until we find the end of the annotation comment block or the wrapper close to be flexible
+              #  We check if @wrapper_close is a substring because `comments` contains strings with the comment character
+              while ending > start && comments[ending].first != DEFAULT_ANNOTATION_ENDING && !comments[ending].first.include?(@wrapper_close)
+                ending -= 1
+              end
+            end
+          else
+            # Walk back until we find the end of the annotation comment block
+            while ending > start && comments[ending].first != DEFAULT_ANNOTATION_ENDING
+              ending -= 1
+            end
+          end
+
+          # We want .last because we want the line indexes
+          @annotation_start = comments[start].last
+          @annotation_end = comments[ending].last
+
+          [@annotation_start, @annotation_end]
+        end
+
+        def annotation
+          @annotation ||=
+            begin
+              lines = @content.lines
+              lines[@annotation_start..@annotation_end].join
+            end
+        end
+
+        # Returns true if annotations are detected in the file content
+        def annotated?
+          @annotation_start && @annotation_end
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/file_parser/custom_parser.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "ripper"
+
+module AnnotateRb
+  module ModelAnnotator
+    module FileParser
+      class CustomParser < Ripper
+        # Overview of Ripper: https://kddnewton.com/2022/02/14/formatting-ruby-part-1.html
+        # Ripper API: https://kddnewton.com/ripper-docs/
+
+        class << self
+          def parse(string)
+            _parser = new(string, "", 0).tap(&:parse)
+          end
+        end
+
+        attr_reader :comments
+
+        def initialize(input, ...)
+          super
+          @_stack_code_block = []
+          @_input = input
+          @_const_event_map = {}
+
+          @comments = []
+          @block_starts = []
+          @block_ends = []
+          @const_type_map = {}
+        end
+
+        def starts
+          @block_starts
+        end
+
+        def ends
+          @block_ends
+        end
+
+        def type_map
+          @const_type_map
+        end
+
+        def on_program(...)
+          {
+            comments: @comments,
+            starts: @block_starts,
+            ends: @block_ends,
+            type_map: @const_type_map
+          }
+        end
+
+        def on_const_ref(const)
+          add_event(__method__, const, lineno)
+          @block_starts << [const, lineno]
+          super
+        end
+
+        # Used for `class Foo::User`
+        def on_const_path_ref(_left, const)
+          add_event(__method__, const, lineno)
+          @block_starts << [const, lineno]
+          super
+        end
+
+        def on_module(const, _bodystmt)
+          add_event(__method__, const, lineno)
+          @const_type_map[const] = :module unless @const_type_map[const]
+          @block_ends << [const, lineno]
+          super
+        end
+
+        def on_class(const, _superclass, _bodystmt)
+          add_event(__method__, const, lineno)
+          @const_type_map[const] = :class unless @const_type_map[const]
+          @block_ends << [const, lineno]
+          super
+        end
+
+        # Gets the `RSpec` opening in:
+        # ```ruby
+        # RSpec.describe "Collapsed::TestModel" do
+        #   # Deliberately left empty
+        # end
+        # ```
+        # receiver: "RSpec", operator: ".", method: "describe"
+        def on_command_call(receiver, operator, method, args)
+          add_event(__method__, receiver, lineno)
+          @block_starts << [receiver, lineno]
+
+          # We keep track of blocks using a stack
+          @_stack_code_block << receiver
+          super
+        end
+
+        def on_method_add_block(method, block)
+          # When parsing a line with no explicit receiver, the method will be presented in an Array.
+          # It's not immediately clear why.
+          #
+          # Example:
+          # ```ruby
+          # describe "Collapsed::TestModel" do
+          #   # Deliberately left empty
+          # end
+          # ```
+          #
+          # => method = ["describe"]
+          if method.is_a?(Array) && method.size == 1
+            method = method.first
+          end
+
+          add_event(__method__, method, lineno)
+
+          if @_stack_code_block.last == method
+            @block_ends << [method, lineno]
+            @_stack_code_block.pop
+          else
+            @block_starts << [method, lineno]
+          end
+          super
+        end
+
+        def on_method_add_arg(method, args)
+          add_event(__method__, method, lineno)
+          @block_starts << [method, lineno]
+
+          # We keep track of blocks using a stack
+          @_stack_code_block << method
+          super
+        end
+
+        # Gets the `FactoryBot` line in:
+        # ```ruby
+        # FactoryBot.define do
+        #   factory :user do
+        #     ...
+        #   end
+        # end
+        # ```
+        def on_call(receiver, operator, message)
+          # We only want to add the parsed line if the beginning of the Ruby
+          if @block_starts.empty?
+            add_event(__method__, receiver, lineno)
+            @block_starts << [receiver, lineno]
+          end
+
+          super
+        end
+
+        # Gets the `factory` block start in:
+        # ```ruby
+        # factory :user, aliases: [:author, :commenter] do
+        #   ...
+        # end
+        # ```
+        def on_command(message, args)
+          add_event(__method__, message, lineno)
+          @block_starts << [message, lineno]
+
+          # We keep track of blocks using a stack
+          @_stack_code_block << message
+          super
+        end
+
+        # Matches the `end` in:
+        # ```ruby
+        # factory :user, aliases: [:author, :commenter] do
+        #   first_name { "John" }
+        #   last_name { "Doe" }
+        #   date_of_birth { 18.years.ago }
+        # end
+        # ```
+        def on_do_block(block_var, bodystmt)
+          if block_var.blank? && bodystmt.blank?
+            @block_ends << ["end", lineno]
+            add_event(__method__, "end", lineno)
+          end
+          super
+        end
+
+        def on_embdoc_beg(value)
+          add_event(__method__, value, lineno)
+          @comments << [value.strip, lineno]
+          super
+        end
+
+        def on_embdoc_end(value)
+          add_event(__method__, value, lineno)
+          @comments << [value.strip, lineno]
+          super
+        end
+
+        def on_embdoc(value)
+          add_event(__method__, value, lineno)
+          @comments << [value.strip, lineno]
+          super
+        end
+
+        def on_comment(value)
+          add_event(__method__, value, lineno)
+          @comments << [value.strip, lineno]
+          super
+        end
+
+        private
+
+        def add_event(event, const, lineno)
+          if !@_const_event_map[lineno]
+            @_const_event_map[lineno] = []
+          end
+
+          @_const_event_map[lineno] << [const, event]
+        end
+      end
+    end
+  end
+end