annotated 0.0.1

data/lib/annotated/annotate_routes/header_generator.rb

@@ -0,0 +1,113 @@
+require_relative "helpers"
+
+module AnnotateRoutes
+  class HeaderGenerator
+    PREFIX = "== Route Map".freeze
+    PREFIX_MD = "## Route Map".freeze
+    HEADER_ROW = ["Prefix", "Verb", "URI Pattern", "Controller#Action"].freeze
+
+    class << self
+      def generate(options = {})
+        new(options, routes_map(options)).generate
+      end
+
+      private :new
+
+      private
+
+      def routes_map(options)
+        result = `rake routes`.chomp("\n").split("\n", -1)
+
+        # In old versions of Rake, the first line of output was the cwd.  Not so
+        # much in newer ones.  We ditch that line if it exists, and if not, we
+        # keep the line around.
+        result.shift if %r{^\(in /}.match?(result.first)
+
+        ignore_routes = options[:ignore_routes]
+        regexp_for_ignoring_routes = ignore_routes ? /#{ignore_routes}/ : nil
+
+        # Skip routes which match given regex
+        # Note: it matches the complete line (route_name, path, controller/action)
+        if regexp_for_ignoring_routes
+          result.reject { |line| line =~ regexp_for_ignoring_routes }
+        else
+          result
+        end
+      end
+    end
+
+    def initialize(options, routes_map)
+      @options = options
+      @routes_map = routes_map
+    end
+
+    def generate
+      magic_comments_map, contents_without_magic_comments = Helpers.extract_magic_comments_from_array(routes_map)
+
+      out = []
+
+      magic_comments_map.each do |magic_comment|
+        out << magic_comment
+      end
+      out << "" if magic_comments_map.any?
+
+      out << comment(options[:wrapper_open]) if options[:wrapper_open]
+
+      out << comment(markdown? ? PREFIX_MD : PREFIX) + timestamp_if_required
+      out << comment
+      return out if contents_without_magic_comments.size.zero?
+
+      maxs = [HEADER_ROW.map(&:size)] + contents_without_magic_comments[1..-1].map { |line| line.split.map(&:size) }
+
+      if markdown?
+        max = maxs.map(&:max).compact.max
+
+        out << comment(content(HEADER_ROW, maxs))
+        out << comment(content(["-" * max, "-" * max, "-" * max, "-" * max], maxs))
+      else
+        out << comment(content(contents_without_magic_comments[0], maxs))
+      end
+
+      out += contents_without_magic_comments[1..-1].map { |line| comment(content(markdown? ? line.split(" ") : line, maxs)) }
+      out << comment(options[:wrapper_close]) if options[:wrapper_close]
+
+      out
+    end
+
+    private
+
+    attr_reader :options, :routes_map
+
+    def comment(row = "")
+      if row == ""
+        "#"
+      else
+        "# #{row}"
+      end
+    end
+
+    def content(line, maxs)
+      return line.rstrip unless markdown?
+
+      line.each_with_index.map { |elem, index| format_line_element(elem, maxs, index) }.join(" | ")
+    end
+
+    def format_line_element(elem, maxs, index)
+      min_length = maxs.map { |arr| arr[index] }.max || 0
+      format("%-#{min_length}.#{min_length}s", elem.tr("|", "-"))
+    end
+
+    def markdown?
+      options[:format_markdown]
+    end
+
+    def timestamp_if_required(time = Time.now)
+      if options[:timestamp]
+        time_formatted = time.strftime("%Y-%m-%d %H:%M")
+        " (Updated #{time_formatted})"
+      else
+        ""
+      end
+    end
+  end
+end

data/lib/annotated/annotate_routes/helpers.rb

@@ -0,0 +1,69 @@
+module AnnotateRoutes
+  module Helpers
+    MAGIC_COMMENT_MATCHER = /(^#\s*encoding:.*)|(^# coding:.*)|(^# -\*- coding:.*)|(^# -\*- encoding\s?:.*)|(^#\s*frozen_string_literal:.+)|(^# -\*- frozen_string_literal\s*:.+-\*-)/
+
+    class << self
+      # TODO: write the method doc using ruby rdoc formats
+      # This method returns an array of 'real_content' and 'header_position'.
+      # 'header_position' will either be :before, :after, or
+      # a number.  If the number is > 0, the
+      # annotation was found somewhere in the
+      # middle of the file.  If the number is
+      # zero, no annotation was found.
+      def strip_annotations(content)
+        real_content = []
+        mode = :content
+        header_position = 0
+
+        content.split("\n", -1).each_with_index do |line, line_number|
+          if mode == :header && line !~ /\s*#/
+            mode = :content
+            real_content << line unless line.blank?
+          elsif mode == :content
+            if /^\s*#\s*== Route.*$/.match?(line)
+              header_position = line_number + 1 # index start's at 0
+              mode = :header
+            else
+              real_content << line
+            end
+          end
+        end
+
+        real_content_and_header_position(real_content, header_position)
+      end
+
+      # @param [Array<String>] content
+      # @return [Array<String>] all found magic comments
+      # @return [Array<String>] content without magic comments
+      def extract_magic_comments_from_array(content_array)
+        magic_comments = []
+        new_content = []
+
+        content_array.each do |row|
+          if MAGIC_COMMENT_MATCHER.match?(row)
+            magic_comments << row.strip
+          else
+            new_content << row
+          end
+        end
+
+        [magic_comments, new_content]
+      end
+
+      private
+
+      def real_content_and_header_position(real_content, header_position)
+        # By default assume the annotation was found in the middle of the file
+
+        # ... unless we have evidence it was at the beginning ...
+        return real_content, :before if header_position == 1
+
+        # ... or that it was at the end.
+        return real_content, :after if header_position >= real_content.count
+
+        # and the default
+        [real_content, header_position]
+      end
+    end
+  end
+end

data/lib/annotated/annotate_routes.rb

@@ -0,0 +1,119 @@
+# == Annotate Routes
+#
+# Based on:
+#
+#
+#
+# Prepends the output of "rake routes" to the top of your routes.rb file.
+# Yes, it's simple but I'm thick and often need a reminder of what my routes
+# mean.
+#
+# Running this task will replace any existing route comment generated by the
+# task. Best to back up your routes file before running:
+#
+# Author:
+#  Gavin Montague
+#  gavin@leftbrained.co.uk
+#
+# Released under the same license as Ruby. No Support. No Warranty.
+#
+
+require_relative "annotate_routes/helpers"
+require_relative "annotate_routes/header_generator"
+
+module AnnotateRoutes
+  class << self
+    def do_annotations(options = {})
+      if routes_file_exist?
+        existing_text = File.read(routes_file)
+        content, header_position = Helpers.strip_annotations(existing_text)
+        new_content = annotate_routes(HeaderGenerator.generate(options), content, header_position, options)
+        new_text = new_content.join("\n")
+        if rewrite_contents(existing_text, new_text, options[:frozen])
+          puts "#{routes_file} was annotated."
+        else
+          puts "#{routes_file} was not changed."
+        end
+      else
+        puts "#{routes_file} could not be found."
+      end
+    end
+
+    def remove_annotations(options = {})
+      if routes_file_exist?
+        existing_text = File.read(routes_file)
+        content, header_position = Helpers.strip_annotations(existing_text)
+        new_content = strip_on_removal(content, header_position)
+        new_text = new_content.join("\n")
+        if rewrite_contents(existing_text, new_text, options[:frozen])
+          puts "Annotations were removed from #{routes_file}."
+        else
+          puts "#{routes_file} was not changed (Annotation did not exist)."
+        end
+      else
+        puts "#{routes_file} could not be found."
+      end
+    end
+
+    private
+
+    def routes_file_exist?
+      File.exist?(routes_file)
+    end
+
+    def routes_file
+      @routes_rb ||= File.join("config", "routes.rb")
+    end
+
+    def strip_on_removal(content, header_position)
+      if header_position == :before
+        content.shift while content.first == ""
+      elsif header_position == :after
+        content.pop while content.last == ""
+      end
+
+      # Make sure we end on a trailing newline.
+      content << "" unless content.last == ""
+
+      # TODO: If the user buried it in the middle, we should probably see about
+      # TODO: preserving a single line of space between the content above and
+      # TODO: below...
+      content
+    end
+
+    def rewrite_contents(existing_text, new_text, frozen)
+      content_changed = (existing_text != new_text)
+
+      if content_changed
+        abort "annotate error. #{routes_file} needs to be updated, but annotate was run with `--frozen`." if frozen
+        File.open(routes_file, "wb") { |f| f.puts(new_text) }
+      end
+
+      content_changed
+    end
+
+    def annotate_routes(header, content, header_position, options = {})
+      magic_comments_map, content = Helpers.extract_magic_comments_from_array(content)
+      if %w[before top].include?(options[:position_in_routes])
+        header <<= "" if content.first != ""
+        magic_comments_map << "" if magic_comments_map.any?
+        new_content = magic_comments_map + header + content
+      else
+        # Ensure we have adequate trailing newlines at the end of the file to
+        # ensure a blank line separating the content from the annotation.
+        content << "" unless content.last == ""
+
+        # We're moving something from the top of the file to the bottom, so ditch
+        # the spacer we put in the first time around.
+        content.shift if header_position == :before && content.first == ""
+
+        new_content = magic_comments_map + content + header
+      end
+
+      # Make sure we end on a trailing newline.
+      new_content << "" unless new_content.last == ""
+
+      new_content
+    end
+  end
+end

data/lib/annotated/constants.rb

@@ -0,0 +1,39 @@
+module Annotated
+  module Constants
+    TRUE_RE = /^(true|t|yes|y|1)$/i
+
+    ##
+    # The set of available options to customize the behavior of Annotated.
+    #
+    POSITION_OPTIONS = [
+      :position_in_routes, :position_in_class, :position_in_test,
+      :position_in_fixture, :position_in_factory, :position,
+      :position_in_serializer
+    ].freeze
+
+    FLAG_OPTIONS = [
+      :show_indexes, :simple_indexes, :include_version, :exclude_tests,
+      :exclude_fixtures, :exclude_factories, :ignore_model_sub_dir,
+      :format_bare, :format_rdoc, :format_yard, :format_markdown, :sort, :force, :frozen,
+      :trace, :timestamp, :exclude_serializers, :classified_sort,
+      :show_foreign_keys, :show_complete_foreign_keys,
+      :exclude_scaffolds, :exclude_controllers, :exclude_helpers,
+      :exclude_sti_subclasses, :ignore_unknown_models, :with_comment, :with_comment_column,
+      :show_check_constraints
+    ].freeze
+
+    OTHER_OPTIONS = [
+      :additional_file_patterns, :ignore_columns, :skip_on_db_migrate, :wrapper_open, :wrapper_close,
+      :wrapper, :routes, :models, :hide_limit_column_types, :hide_default_column_types,
+      :ignore_routes, :active_admin
+    ].freeze
+
+    PATH_OPTIONS = [
+      :require, :model_dir, :root_dir
+    ].freeze
+
+    ALL_ANNOTATE_OPTIONS = [
+      POSITION_OPTIONS, FLAG_OPTIONS, OTHER_OPTIONS, PATH_OPTIONS
+    ].freeze
+  end
+end

data/lib/annotated/helpers.rb

@@ -0,0 +1,30 @@
+module Annotated
+  # Class for holding helper methods. Done to make lib/annotate.rb less bloated.
+  class Helpers
+    class << self
+      def skip_on_migration?
+        ENV["ANNOTATE_SKIP_ON_DB_MIGRATE"] =~ Constants::TRUE_RE || ENV["skip_on_db_migrate"] =~ Constants::TRUE_RE
+      end
+
+      def include_routes?
+        ENV["routes"] =~ Constants::TRUE_RE
+      end
+
+      def include_models?
+        ENV["models"] =~ Constants::TRUE_RE
+      end
+
+      def true?(val)
+        val.present? && Constants::TRUE_RE.match?(val)
+      end
+
+      def fallback(*args)
+        args.detect(&:present?)
+      end
+
+      def reset_options(options)
+        options.flatten.each { |key| ENV[key.to_s] = nil }
+      end
+    end
+  end
+end

data/lib/annotated/parser.rb

@@ -0,0 +1,314 @@
+require "optparse"
+
+module Annotated
+  # Class for handling command line arguments
+  class Parser # rubocop:disable Metrics/ClassLength
+    def self.parse(args, env = {})
+      new(args, env).parse
+    end
+
+    attr_reader :args, :options, :env
+
+    DEFAULT_OPTIONS = {
+      target_action: :do_annotations,
+      exit: false
+    }.freeze
+
+    ANNOTATION_POSITIONS = %w[before top after bottom].freeze
+    FILE_TYPE_POSITIONS = %w[position_in_class position_in_factory position_in_fixture position_in_test position_in_routes position_in_serializer].freeze
+    EXCLUSION_LIST = %w[tests fixtures factories serializers].freeze
+    FORMAT_TYPES = %w[bare rdoc yard markdown].freeze
+
+    def initialize(args, env)
+      @args = args
+      @options = DEFAULT_OPTIONS.dup
+      @env = env
+    end
+
+    def parse
+      # To split up because right now this method parses and commits
+      parser.parse!(args)
+
+      commit
+
+      options
+    end
+
+    private
+
+    def parser
+      OptionParser.new do |option_parser|
+        add_options_to_parser(option_parser)
+      end
+    end
+
+    def commit
+      env.each_pair do |key, value|
+        ENV[key] = value
+      end
+    end
+
+    def add_options_to_parser(option_parser) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      has_set_position = {}
+
+      option_parser.banner = "Usage: annotate [options] [model_file]*"
+
+      option_parser.on("--additional-file-patterns path1,path2,path3",
+        Array,
+        "Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%model_name%/*.rb,/baz/%model_name%.rb`)") do |additional_file_patterns|
+        ENV["additional_file_patterns"] = additional_file_patterns
+      end
+
+      option_parser.on("-d",
+        "--delete",
+        "Remove annotations from all model files or the routes.rb file") do
+        @options[:target_action] = :remove_annotations
+      end
+
+      option_parser.on("-p",
+        "--position [before|top|after|bottom]",
+        ANNOTATION_POSITIONS,
+        "Place the annotations at the top (before) or the bottom (after) of the model/test/fixture/factory/route/serializer file(s)") do |position|
+        env["position"] = position
+
+        FILE_TYPE_POSITIONS.each do |key|
+          env[key] = position unless has_set_position[key]
+        end
+      end
+
+      option_parser.on("--pc",
+        "--position-in-class [before|top|after|bottom]",
+        ANNOTATION_POSITIONS,
+        "Place the annotations at the top (before) or the bottom (after) of the model file") do |position_in_class|
+        env["position_in_class"] = position_in_class
+        has_set_position["position_in_class"] = true
+      end
+
+      option_parser.on("--pf",
+        "--position-in-factory [before|top|after|bottom]",
+        ANNOTATION_POSITIONS,
+        "Place the annotations at the top (before) or the bottom (after) of any factory files") do |position_in_factory|
+        env["position_in_factory"] = position_in_factory
+        has_set_position["position_in_factory"] = true
+      end
+
+      option_parser.on("--px",
+        "--position-in-fixture [before|top|after|bottom]",
+        ANNOTATION_POSITIONS,
+        "Place the annotations at the top (before) or the bottom (after) of any fixture files") do |position_in_fixture|
+        env["position_in_fixture"] = position_in_fixture
+        has_set_position["position_in_fixture"] = true
+      end
+
+      option_parser.on("--pt",
+        "--position-in-test [before|top|after|bottom]",
+        ANNOTATION_POSITIONS,
+        "Place the annotations at the top (before) or the bottom (after) of any test files") do |position_in_test|
+        env["position_in_test"] = position_in_test
+        has_set_position["position_in_test"] = true
+      end
+
+      option_parser.on("--pr",
+        "--position-in-routes [before|top|after|bottom]",
+        ANNOTATION_POSITIONS,
+        "Place the annotations at the top (before) or the bottom (after) of the routes.rb file") do |position_in_routes|
+        env["position_in_routes"] = position_in_routes
+        has_set_position["position_in_routes"] = true
+      end
+
+      option_parser.on("--ps",
+        "--position-in-serializer [before|top|after|bottom]",
+        ANNOTATION_POSITIONS,
+        "Place the annotations at the top (before) or the bottom (after) of the serializer files") do |position_in_serializer|
+        env["position_in_serializer"] = position_in_serializer
+        has_set_position["position_in_serializer"] = true
+      end
+
+      option_parser.on("--w",
+        "--wrapper STR",
+        "Wrap annotation with the text passed as parameter.",
+        "If --w option is used, the same text will be used as opening and closing") do |wrapper|
+        env["wrapper"] = wrapper
+      end
+
+      option_parser.on("--wo",
+        "--wrapper-open STR",
+        "Annotation wrapper opening.") do |wrapper_open|
+        env["wrapper_open"] = wrapper_open
+      end
+
+      option_parser.on("--wc",
+        "--wrapper-close STR",
+        "Annotation wrapper closing") do |wrapper_close|
+        env["wrapper_close"] = wrapper_close
+      end
+
+      option_parser.on("-r",
+        "--routes",
+        "Annotate routes.rb with the output of 'rake routes'") do
+        env["routes"] = "true"
+      end
+
+      option_parser.on("--models",
+        "Annotate ActiveRecord models") do
+        env["models"] = "true"
+      end
+
+      option_parser.on("-a",
+        "--active-admin",
+        "Annotate active_admin models") do
+        env["active_admin"] = "true"
+      end
+
+      option_parser.on("-v",
+        "--version",
+        "Show the current version of this gem") do
+        puts "annotate v#{Annotated.version}"
+        @options[:exit] = true
+      end
+
+      option_parser.on("-m",
+        "--show-migration",
+        "Include the migration version number in the annotation") do
+        env["include_version"] = "yes"
+      end
+
+      option_parser.on("-c",
+        "--show-check-constraints",
+        "List the table's check constraints in the annotation") do
+        env["show_check_constraints"] = "yes"
+      end
+
+      option_parser.on("-k",
+        "--show-foreign-keys",
+        "List the table's foreign key constraints in the annotation") do
+        env["show_foreign_keys"] = "yes"
+      end
+
+      option_parser.on("--ck",
+        "--complete-foreign-keys",
+        "Complete foreign key names in the annotation") do
+        env["show_foreign_keys"] = "yes"
+        env["show_complete_foreign_keys"] = "yes"
+      end
+
+      option_parser.on("-i",
+        "--show-indexes",
+        "List the table's database indexes in the annotation") do
+        env["show_indexes"] = "yes"
+      end
+
+      option_parser.on("-s",
+        "--simple-indexes",
+        "Concat the column's related indexes in the annotation") do
+        env["simple_indexes"] = "yes"
+      end
+
+      option_parser.on("--model-dir dir",
+        "Annotate model files stored in dir rather than app/models, separate multiple dirs with commas") do |dir|
+        env["model_dir"] = dir
+      end
+
+      option_parser.on("--root-dir dir",
+        "Annotate files stored within root dir projects, separate multiple dirs with commas") do |dir|
+        env["root_dir"] = dir
+      end
+
+      option_parser.on("--ignore-model-subdirects",
+        "Ignore subdirectories of the models directory") do
+        env["ignore_model_sub_dir"] = "yes"
+      end
+
+      option_parser.on("--sort",
+        "Sort columns alphabetically, rather than in creation order") do
+        env["sort"] = "yes"
+      end
+
+      option_parser.on("--classified-sort",
+        "Sort columns alphabetically, but first goes id, then the rest columns, then the timestamp columns and then the association columns") do
+        env["classified_sort"] = "yes"
+      end
+
+      option_parser.on("-R",
+        "--require path",
+        "Additional file to require before loading models, may be used multiple times") do |path|
+        env["require"] = if env["require"].present?
+          "#{env["require"]},#{path}"
+        else
+          path
+        end
+      end
+
+      option_parser.on("-e",
+        "--exclude [tests,fixtures,factories,serializers]",
+        Array,
+        "Do not annotate fixtures, test files, factories, and/or serializers") do |exclusions|
+        exclusions ||= EXCLUSION_LIST
+        exclusions.each { |exclusion| env["exclude_#{exclusion}"] = "yes" }
+      end
+
+      option_parser.on("-f",
+        "--format [bare|rdoc|yard|markdown]",
+        FORMAT_TYPES,
+        "Render Schema Infomation as plain/RDoc/Yard/Markdown") do |format_type|
+        env["format_#{format_type}"] = "yes"
+      end
+
+      option_parser.on("--force",
+        "Force new annotations even if there are no changes.") do
+        env["force"] = "yes"
+      end
+
+      option_parser.on("--frozen",
+        "Do not allow to change annotations. Exits non-zero if there are going to be changes to files.") do
+        env["frozen"] = "yes"
+      end
+
+      option_parser.on("--timestamp",
+        "Include timestamp in (routes) annotation") do
+        env["timestamp"] = "true"
+      end
+
+      option_parser.on("--trace",
+        "If unable to annotate a file, print the full stack trace, not just the exception message.") do
+        env["trace"] = "yes"
+      end
+
+      option_parser.on("-I",
+        "--ignore-columns REGEX",
+        "don't annotate columns that match a given REGEX (i.e., `annotate -I '^(id|updated_at|created_at)'`") do |regex|
+        env["ignore_columns"] = regex
+      end
+
+      option_parser.on("--ignore-routes REGEX",
+        "don't annotate routes that match a given REGEX (i.e., `annotate -I '(mobile|resque|pghero)'`") do |regex|
+        env["ignore_routes"] = regex
+      end
+
+      option_parser.on("--hide-limit-column-types VALUES",
+        "don't show limit for given column types, separated by commas (i.e., `integer,boolean,text`)") do |values|
+        env["hide_limit_column_types"] = values.to_s
+      end
+
+      option_parser.on("--hide-default-column-types VALUES",
+        "don't show default for given column types, separated by commas (i.e., `json,jsonb,hstore`)") do |values|
+        env["hide_default_column_types"] = values.to_s
+      end
+
+      option_parser.on("--ignore-unknown-models",
+        "don't display warnings for bad model files") do
+        env["ignore_unknown_models"] = "true"
+      end
+
+      option_parser.on("--with-comment",
+        "include database comments in model annotations") do
+        env["with_comment"] = "true"
+      end
+
+      option_parser.on("--with-comment-column",
+        "include database comments in model annotations, as its own column, after all others") do
+        env["with_comment_column"] = "true"
+      end
+    end
+  end
+end

data/lib/annotated/tasks.rb

@@ -0,0 +1,6 @@
+require "rubygems"
+require "rake"
+
+# Make tasks visible for Rails also when used as gem.
+Dir[File.join(File.dirname(__FILE__), "..", "tasks", "**/*.rake")].each { |rake| load rake }
+Dir[File.join(File.dirname(__FILE__), "..", "..", "tasks", "**/*.rake")].each { |rake| load rake }

data/lib/annotated/version.rb

@@ -0,0 +1,5 @@
+module Annotated
+  def self.version
+    "0.0.1"
+  end
+end