annotaterb 4.0.0.beta.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ca3a25c118bfa3f5910e4fe455de3d9333c353d409f434cffde12694f87cff5
+  data.tar.gz: 417dcf943056ec0f44ba7eb973c3ad2dc99cb435315d41a13d1fc9f53bb87b9e
+SHA512:
+  metadata.gz: 2d34ca80e5686ef6cadfe0a2624aecd891fde3628653e68fa8b86613ac6382a4d7bdcf8e0c7504988dd653023be3d1190c5a072d46890b9c874ecaf1abbc20f7
+  data.tar.gz: 2ae8ca4a18c83437b379f7823291c094a87db9465742bf2c1c94c99fcfe1cb833f894367774a44ff2a9e7c8f41f9670f8baeedff1d5832bbbf2c49a6ced8ac80

data/LICENSE.txt

@@ -0,0 +1,55 @@
+You can redistribute it and/or modify it under either the terms of the
+2-clause BSDL (see the file BSDL), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or binary form,
+     provided that you do at least ONE of the following:
+
+       a) distribute the binaries and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard binaries non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under these terms.
+
+     For the list of those files and their copying conditions, see the
+     file LEGAL.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/README.md

@@ -0,0 +1,91 @@
+## AnnotateRb
+### forked from the [Annotate aka AnnotateModels gem](https://github.com/ctran/annotate_models)
+
+----------
+[![CI](https://github.com/drwl/annotaterb/actions/workflows/ci.yml/badge.svg)](https://github.com/drwl/annotaterb/actions/workflows/ci.yml)
+
+Adds comments summarizing the model schema or routes in your:
+
+- ActiveRecord models
+- Fixture files
+- Tests and Specs
+- FactoryBot factories
+- `routes.rb` file (for Rails projects)
+
+The schema comment looks like this:
+
+```ruby
+# == Schema Information
+#
+# Table name: tasks
+#
+#  id         :integer          not null, primary key
+#  content    :string
+#  count      :integer
+#  status     :boolean
+#  created_at :datetime         not null
+#  updated_at :datetime         not null
+#
+class Task < ApplicationRecord
+  ...
+```
+----------
+## Installation
+
+```sh
+$ gem install annotaterb
+```
+
+Or install it into your Rails project through the Gemfile:
+
+```rb
+group :development do
+  ...
+
+  gem "annotaterb"
+  
+  ...
+```
+
+### Automatically annotate models
+For Rails projects, model files can get automatically annotated after migration tasks. To do this, run the following command:
+
+```sh
+$ bin/rails g annotate_rb:install
+```
+
+This will copy a rake task into your Rails project's `lib/tasks` directory that will hook into the Rails project rake tasks, automatically running AnnotateRb after database migration rake tasks.
+
+## Migrating from the annotate gem
+
+Add steps for migrating from annotate gem.
+
+## Usage
+
+AnnotateRb has a CLI that you can use to add or remove annotations.
+
+```sh
+# To show the CLI options
+$ bundle exec annotaterb 
+```
+
+## Configuration
+
+
+### How to skip annotating a particular model
+If you want to always skip annotations on a particular model, add this string
+anywhere in the file:
+
+    # -*- SkipSchemaAnnotations
+
+## Sorting
+
+By default, columns will be sorted in database order (i.e. the order in which
+migrations were run).
+
+If you prefer to sort alphabetically so that the results of annotation are
+consistent regardless of what order migrations are executed in, use `--sort`.
+
+## License
+
+Released under the same license as Ruby. No Support. No Warranty.

data/VERSION

@@ -0,0 +1 @@
+4.0.0.beta.1

data/exe/annotaterb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+unless File.exist?('./Rakefile') || File.exist?('./Gemfile')
+  abort 'Please run annotaterb from the root of the project.'
+end
+
+begin
+  require 'bundler'
+  Bundler.setup
+rescue StandardError
+end
+
+$LOAD_PATH.unshift("#{__dir__}/../lib")
+
+require 'annotate_rb'
+
+exit_status = ::AnnotateRb::Runner.run(ARGV)
+
+# TODO: Return exit status
+# exit exit_status

data/lib/annotate_rb/active_record_patch.rb

@@ -0,0 +1,9 @@
+# monkey patches
+
+module ::ActiveRecord
+  class Base
+    def self.method_missing(_name, *_args)
+      # ignore this, so unknown/unloaded macros won't cause parsing to fail
+    end
+  end
+end

data/lib/annotate_rb/commands/annotate_models.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module Commands
+    class AnnotateModels
+      def call(options)
+        puts "Annotating models"
+
+        if options[:debug]
+          puts "Running with debug mode, options:"
+          pp options.to_h
+        end
+
+        # Eager load Models when we're annotating models
+        AnnotateRb::EagerLoader.call(options)
+
+        AnnotateRb::ModelAnnotator::Annotator.send(options[:target_action], options)
+      end
+    end
+  end
+end
+

data/lib/annotate_rb/commands/annotate_routes.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module Commands
+    class AnnotateRoutes
+      def call(options)
+        puts "Annotating routes"
+
+        if options[:debug]
+          puts "Running with debug mode, options:"
+          pp options.to_h
+        end
+
+        AnnotateRb::RouteAnnotator::Annotator.send(options[:target_action], options)
+      end
+    end
+  end
+end
+

data/lib/annotate_rb/commands/print_help.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module Commands
+    class PrintHelp
+      def initialize(parser)
+        @parser = parser
+      end
+
+      def call(_options)
+        puts @parser.help
+      end
+    end
+  end
+end
+

data/lib/annotate_rb/commands/print_version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module Commands
+    class PrintVersion
+      def call(_options)
+        puts "AnnotateRb v#{Core.version}"
+      end
+    end
+  end
+end
+

data/lib/annotate_rb/commands.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module Commands
+    autoload :PrintVersion, 'annotate_rb/commands/print_version'
+    autoload :PrintHelp, 'annotate_rb/commands/print_help'
+    autoload :AnnotateModels, 'annotate_rb/commands/annotate_models'
+    autoload :AnnotateRoutes, 'annotate_rb/commands/annotate_routes'
+  end
+end

data/lib/annotate_rb/config_finder.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  class ConfigFinder
+    DOTFILE = '.annotaterb.yml'
+
+    class << self
+      def find_project_root
+        # We should expect this method to be called from a Rails project root and returning it
+        # e.g. "/Users/drwl/personal/annotaterb/dummyapp"
+        Dir.pwd
+      end
+
+      def find_project_dotfile
+        file_path = File.expand_path(DOTFILE, find_project_root)
+
+        return file_path if File.exist?(file_path)
+      end
+    end
+  end
+end

data/lib/annotate_rb/config_loader.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  # Raised when a configuration file is not found.
+  class ConfigNotFoundError < StandardError
+  end
+
+  class ConfigLoader
+    class << self
+      def load_config
+        config_path = ConfigFinder.find_project_dotfile
+
+        if config_path
+          load_yaml_configuration(config_path)
+        else
+          {}
+        end
+      end
+
+      # Method from Rubocop::ConfigLoader
+      def load_yaml_configuration(absolute_path)
+        file_contents = read_file(absolute_path)
+
+        hash = yaml_safe_load(file_contents, absolute_path) || {}
+
+        # TODO: Print config if debug flag/option is set
+
+        raise(TypeError, "Malformed configuration in #{absolute_path}") unless hash.is_a?(Hash)
+
+        hash
+      end
+
+      # Read the specified file, or exit with a friendly, concise message on
+      # stderr. Care is taken to use the standard OS exit code for a "file not
+      # found" error.
+      #
+      # Method from Rubocop::ConfigLoader
+      def read_file(absolute_path)
+        File.read(absolute_path, encoding: Encoding::UTF_8)
+      rescue Errno::ENOENT
+        raise ConfigNotFoundError, "Configuration file not found: #{absolute_path}"
+      end
+
+      # Method from Rubocop::ConfigLoader
+      def yaml_safe_load(yaml_code, filename)
+        yaml_safe_load!(yaml_code, filename)
+      rescue ::StandardError
+        if defined?(::SafeYAML)
+          raise 'SafeYAML is unmaintained, no longer needed and should be removed'
+        end
+
+        raise
+      end
+
+      # Method from Rubocop::ConfigLoader
+      def yaml_safe_load!(yaml_code, filename)
+        YAML.safe_load(
+          yaml_code, permitted_classes: [Regexp, Symbol], aliases: true, filename: filename, symbolize_names: true
+        )
+      end
+    end
+  end
+end

data/lib/annotate_rb/core.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module Core
+    class << self
+      def version
+        @version ||= File.read(File.expand_path('../../VERSION', __dir__)).strip
+      end
+
+      def load_rake_tasks
+        return if @load_rake_tasks
+
+        rake_tasks = Dir[File.join(File.dirname(__FILE__), 'tasks', '**/*.rake')]
+
+        rake_tasks.each do |task|
+          load task
+        end
+
+        @load_rake_tasks = true
+      end
+    end
+  end
+end

data/lib/annotate_rb/eager_loader.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  # Not sure what this does just yet
+  class EagerLoader
+    class << self
+      def call(options)
+        options[:require].count > 0 && options[:require].each { |path| require path }
+
+        if defined?(::Rails::Application)
+          klass = ::Rails::Application.send(:subclasses).first
+          klass.eager_load!
+        else
+          options[:model_dir].each do |dir|
+            ::Rake::FileList["#{dir}/**/*.rb"].each do |fname|
+              require File.expand_path(fname)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/env.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  class Env
+    class << self
+      def read(key)
+        key = key.to_s unless key.is_a?(String)
+
+        ENV[key]
+      end
+
+      def write(key, value)
+        key = key.to_s unless key.is_a?(String)
+
+        ENV[key] = value.to_s
+      end
+
+      def fetch(key, default_value)
+        key = key.to_s unless key.is_a?(String)
+        val = read(key)
+
+        if val.nil?
+          default_value
+        else
+          val
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/annotation_pattern_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class AnnotationPatternGenerator
+      COMPAT_PREFIX = '== Schema Info'.freeze
+      COMPAT_PREFIX_MD = '## Schema Info'.freeze
+
+      class << self
+        def call(options = Options.from({}))
+          if options[:wrapper_open]
+            return /(?:^(\n|\r\n)?# (?:#{options[:wrapper_open]}).*(\n|\r\n)?# (?:#{COMPAT_PREFIX}|#{COMPAT_PREFIX_MD}).*?(\n|\r\n)(#.*(\n|\r\n))*(\n|\r\n)*)|^(\n|\r\n)?# (?:#{COMPAT_PREFIX}|#{COMPAT_PREFIX_MD}).*?(\n|\r\n)(#.*(\n|\r\n))*(\n|\r\n)*/
+          end
+          /^(\n|\r\n)?# (?:#{COMPAT_PREFIX}|#{COMPAT_PREFIX_MD}).*?(\n|\r\n)(#.*(\n|\r\n))*(\n|\r\n)*/
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/annotator.rb

@@ -0,0 +1,74 @@
+# require 'bigdecimal'
+
+module AnnotateRb
+  module ModelAnnotator
+    class Annotator
+      # Annotate Models plugin use this header
+      PREFIX = '== Schema Information'.freeze
+      PREFIX_MD = '## Schema Information'.freeze
+
+      MAGIC_COMMENT_MATCHER = Regexp.new(/(^#\s*encoding:.*(?:\n|r\n))|(^# coding:.*(?:\n|\r\n))|(^# -\*- coding:.*(?:\n|\r\n))|(^# -\*- encoding\s?:.*(?:\n|\r\n))|(^#\s*frozen_string_literal:.+(?:\n|\r\n))|(^# -\*- frozen_string_literal\s*:.+-\*-(?:\n|\r\n))/).freeze
+
+      class << self
+        # We're passed a name of things that might be
+        # ActiveRecord models. If we can find the class, and
+        # if its a subclass of ActiveRecord::Base,
+        # then pass it to the associated block
+        def do_annotations(options = {})
+          header = options[:format_markdown] ? PREFIX_MD.dup : PREFIX.dup
+          version = ActiveRecord::Migrator.current_version rescue 0
+          if options[:include_version] && version > 0
+            header << "\n# Schema version: #{version}"
+          end
+
+          annotated = []
+          model_files_to_annotate = ModelFilesGetter.call(options)
+
+          model_files_to_annotate.each do |path, filename|
+            ModelFileAnnotator.call(annotated, File.join(path, filename), header, options)
+          end
+
+          if annotated.empty?
+            puts 'Model files unchanged.'
+          else
+            puts "Annotated (#{annotated.length}): #{annotated.join(', ')}"
+          end
+        end
+
+        def remove_annotations(options = {})
+          deannotated = []
+          deannotated_klass = false
+          ModelFilesGetter.call(options).each do |file|
+            file = File.join(file)
+            begin
+              klass = ModelClassGetter.call(file, options)
+              if klass < ActiveRecord::Base && !klass.abstract_class?
+                model_name = klass.name.underscore
+                table_name = klass.table_name
+                model_file_name = file
+                deannotated_klass = true if FileAnnotationRemover.call(model_file_name, options)
+
+                patterns = PatternGetter.call(options)
+
+                patterns
+                  .map { |f| FileNameResolver.call(f, model_name, table_name) }
+                  .each do |f|
+                  if File.exist?(f)
+                    FileAnnotationRemover.call(f, options)
+                    deannotated_klass = true
+                  end
+                end
+              end
+              deannotated << klass if deannotated_klass
+            rescue StandardError => e
+              $stderr.puts "Unable to deannotate #{File.join(file)}: #{e.message}"
+              $stderr.puts "\t" + e.backtrace.join("\n\t") if options[:trace]
+            end
+          end
+          puts "Removed annotations from: #{deannotated.join(', ')}"
+        end
+      end
+    end
+  end
+end
+

data/lib/annotate_rb/model_annotator/bad_model_file_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class BadModelFileError < LoadError
+      def to_s
+        "file doesn't contain a valid model class"
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/constants.rb

@@ -0,0 +1,22 @@
+module AnnotateRb
+  module ModelAnnotator
+    module Constants
+      TRUE_RE = /^(true|t|yes|y|1)$/i.freeze
+
+      ##
+      # The set of available options to customize the behavior of Annotate.
+      #
+      POSITION_OPTIONS = ::AnnotateRb::Options::POSITION_OPTION_KEYS
+
+      FLAG_OPTIONS = ::AnnotateRb::Options::FLAG_OPTION_KEYS
+
+      OTHER_OPTIONS = ::AnnotateRb::Options::OTHER_OPTION_KEYS
+
+      PATH_OPTIONS = ::AnnotateRb::Options::PATH_OPTION_KEYS
+
+      ALL_ANNOTATE_OPTIONS = ::AnnotateRb::Options::ALL_OPTION_KEYS
+
+      SKIP_ANNOTATION_PREFIX = '# -\*- SkipSchemaAnnotations'.freeze
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/file_annotation_remover.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class FileAnnotationRemover
+      class << self
+        def call(file_name, options = Options.from({}))
+          if File.exist?(file_name)
+            content = File.read(file_name)
+            return false if content =~ /#{Constants::SKIP_ANNOTATION_PREFIX}.*\n/
+
+            wrapper_open = options[:wrapper_open] ? "# #{options[:wrapper_open]}\n" : ''
+            content.sub!(/(#{wrapper_open})?#{AnnotationPatternGenerator.call(options)}/, '')
+
+            File.open(file_name, 'wb') { |f| f.puts content }
+
+            true
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/annotate_rb/model_annotator/file_annotator.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module AnnotateRb
+  module ModelAnnotator
+    class FileAnnotator
+      class << self
+        # Add a schema block to a file. If the file already contains
+        # a schema info block (a comment starting with "== Schema Information"),
+        # check if it matches the block that is already there. If so, leave it be.
+        # If not, remove the old info block and write a new one.
+        #
+        # == Returns:
+        # true or false depending on whether the file was modified.
+        #
+        # === Options (opts)
+        #  :force<Symbol>:: whether to update the file even if it doesn't seem to need it.
+        #  :position_in_*<Symbol>:: where to place the annotated section in fixture or model file,
+        #                           :before, :top, :after or :bottom. Default is :before.
+        #
+        def call(file_name, info_block, position, options = {})
+          return false unless File.exist?(file_name)
+          old_content = File.read(file_name)
+          return false if old_content =~ /#{Constants::SKIP_ANNOTATION_PREFIX}.*\n/
+
+          # Ignore the Schema version line because it changes with each migration
+          header_pattern = /(^# Table name:.*?\n(#.*[\r]?\n)*[\r]?)/
+          old_header = old_content.match(header_pattern).to_s
+          new_header = info_block.match(header_pattern).to_s
+
+          column_pattern = /^#[\t ]+[\w\*\.`]+[\t ]+.+$/
+          old_columns = old_header && old_header.scan(column_pattern).sort
+          new_columns = new_header && new_header.scan(column_pattern).sort
+
+          return false if old_columns == new_columns && !options[:force]
+
+          abort "annotate error. #{file_name} needs to be updated, but annotate was run with `--frozen`." if options[:frozen]
+
+          # Replace inline the old schema info with the new schema info
+          wrapper_open = options[:wrapper_open] ? "# #{options[:wrapper_open]}\n" : ""
+          wrapper_close = options[:wrapper_close] ? "# #{options[:wrapper_close]}\n" : ""
+          wrapped_info_block = "#{wrapper_open}#{info_block}#{wrapper_close}"
+
+          annotation_pattern = AnnotationPatternGenerator.call(options)
+          old_annotation = old_content.match(annotation_pattern).to_s
+
+          # if there *was* no old schema info or :force was passed, we simply
+          # need to insert it in correct position
+          if old_annotation.empty? || options[:force]
+            magic_comments_block = Helper.magic_comments_as_string(old_content)
+            old_content.gsub!(Annotator::MAGIC_COMMENT_MATCHER, '')
+
+            annotation_pattern = AnnotationPatternGenerator.call(options)
+            old_content.sub!(annotation_pattern, '')
+
+            new_content = if %w(after bottom).include?(options[position].to_s)
+                            magic_comments_block + (old_content.rstrip + "\n\n" + wrapped_info_block)
+                          elsif magic_comments_block.empty?
+                            magic_comments_block + wrapped_info_block + old_content.lstrip
+                          else
+                            magic_comments_block + "\n" + wrapped_info_block + old_content.lstrip
+                          end
+          else
+            # replace the old annotation with the new one
+
+            # keep the surrounding whitespace the same
+            space_match = old_annotation.match(/\A(?<start>\s*).*?\n(?<end>\s*)\z/m)
+            new_annotation = space_match[:start] + wrapped_info_block + space_match[:end]
+
+            annotation_pattern = AnnotationPatternGenerator.call(options)
+            new_content = old_content.sub(annotation_pattern, new_annotation)
+          end
+
+          File.open(file_name, 'wb') { |f| f.puts new_content }
+          true
+        end
+      end
+    end
+  end
+end