annotate 2.6.3 → 3.2.0

data/README.md

@@ -0,0 +1,331 @@
+## Annotate (aka AnnotateModels)
+
+[![Gem Version](https://badge.fury.io/rb/annotate.svg)](http://badge.fury.io/rb/annotate)
+[![Downloads count](https://img.shields.io/gem/dt/annotate.svg?style=flat)](https://rubygems.org/gems/annotate)
+[![Build status](https://travis-ci.org/ctran/annotate_models.svg?branch=develop)](https://travis-ci.org/ctran/annotate_models)
+[![CI Status](https://github.com/ctran/annotate_models/workflows/CI/badge.svg)](https://github.com/ctran/annotate_models/actions?workflow=CI)
+[![Coveralls](https://coveralls.io/repos/ctran/annotate_models/badge.svg?branch=develop)](https://coveralls.io/r/ctran/annotate_models?branch=develop)
+[![Maintenability](https://codeclimate.com/github/ctran/annotate_models/badges/gpa.svg)](https://codeclimate.com/github/ctran/annotate_models)
+[![Inline docs](http://inch-ci.org/github/ctran/annotate_models.svg?branch=develop)](http://inch-ci.org/github/ctran/annotate_models)
+
+Add a comment summarizing the current schema to the top or bottom of each of your...
+
+- ActiveRecord models
+- Fixture files
+- Tests and Specs
+- Object Daddy exemplars
+- Machinist blueprints
+- Fabrication fabricators
+- Thoughtbot's factory_bot factories, i.e. the `(spec|test)/factories/<model>_factory.rb` files
+- `routes.rb` file (for Rails projects)
+
+
+The schema comment looks like this:
+
+```ruby
+# == Schema Info
+#
+# Table name: line_items
+#
+#  id                  :integer(11)    not null, primary key
+#  quantity            :integer(11)    not null
+#  product_id          :integer(11)    not null
+#  unit_price          :float
+#  order_id            :integer(11)
+#
+
+class LineItem < ActiveRecord::Base
+  belongs_to :product
+  . . .
+```
+
+It also annotates geometrical columns, `geom` type and `srid`,
+when using `SpatialAdapter`, `PostgisAdapter` or `PostGISAdapter`:
+
+```ruby
+# == Schema Info
+#
+# Table name: trips
+#
+#  local           :geometry        point, 4326
+#  path            :geometry        line_string, 4326
+```
+
+Also, if you pass the `-r` option, it'll annotate `routes.rb` with the output of `rake routes`.
+
+
+## Upgrading to 3.X and annotate models not working?
+
+In versions 2.7.X the annotate gem defaulted to annotating models if no arguments were passed in.
+The annotate gem by default would not allow for routes and models to be annotated together.
+A [change was added in #647](https://github.com/ctran/annotate_models/pull/647).
+You [can read more here](https://github.com/ctran/annotate_models/issues/663).
+
+There are a few ways of fixing this:
+
+- If using CLI explicitly pass in models flag using `--models`
+
+OR
+
+a) Running `rails g annotate:install` will overwrite your defaults with the annotating `models` option set to `'true'`.
+
+b) In `lib/tasks/auto_annotate_models.rake` add the `models` key-value option:
+
+```ruby
+    Annotate.set_defaults(
+      ...
+      'models'                      => 'true',
+      ...
+```
+
+## Install
+
+Into Gemfile from rubygems.org:
+
+```ruby
+group :development do
+  gem 'annotate'
+end
+```
+
+Into Gemfile from Github:
+
+```ruby
+group :development do
+  gem 'annotate', git: 'https://github.com/ctran/annotate_models.git'
+end
+```
+
+Into environment gems from rubygems.org:
+
+    gem install annotate
+
+Into environment gems from Github checkout:
+
+    git clone https://github.com/ctran/annotate_models.git annotate_models
+    cd annotate_models
+    rake gem
+    gem install dist/annotate-*.gem
+
+## Usage
+
+(If you used the Gemfile install, prefix the below commands with `bundle exec`.)
+
+### Usage in Rails
+
+To annotate all your models, tests, fixtures, and factories:
+
+    cd /path/to/app
+    annotate
+
+To annotate just your models, tests, and factories:
+
+    annotate --models --exclude fixtures
+
+To annotate just your models:
+
+    annotate --models
+
+To annotate routes.rb:
+
+    annotate --routes
+
+To remove model/test/fixture/factory/serializer annotations:
+
+    annotate --delete
+
+To remove routes.rb annotations:
+
+    annotate --routes --delete
+
+To automatically annotate every time you run `db:migrate`,
+either run `rails g annotate:install`
+or add `Annotate.load_tasks` to your `Rakefile`.
+
+See the [configuration in Rails](#configuration-in-rails) section for more info.
+
+### Usage Outside of Rails
+
+Everything above applies, except that `--routes` is not meaningful,
+and you will probably need to explicitly set one or more `--require` option(s), and/or one or more `--model-dir` options
+to inform `annotate` about the structure of your project and help it bootstrap and load the relevant code.
+
+## Configuration
+
+If you want to always skip annotations on a particular model, add this string
+anywhere in the file:
+
+    # -*- SkipSchemaAnnotations
+
+### Configuration in Rails
+
+To generate a configuration file (in the form of a `.rake` file), to set
+default options:
+
+    rails g annotate:install
+
+Edit this file to control things like output format, where annotations are
+added (top or bottom of file), and in which artifacts.
+
+The generated rakefile `lib/tasks/auto_annotate_models.rake` also contains
+`Annotate.load_tasks`. This adds a few rake tasks which duplicate command-line
+functionality:
+
+    rake annotate_models                          # Add schema information (as comments) to model and fixture files
+    rake annotate_routes                          # Adds the route map to routes.rb
+    rake remove_annotation                        # Remove schema information from model and fixture files
+
+By default, once you've generated a configuration file, annotate will be
+executed whenever you run `rake db:migrate` (but only in development mode).
+If you want to disable this behavior permanently,
+edit the `.rake` file and change:
+
+```ruby
+    'skip_on_db_migrate'   => 'false',
+```
+
+To:
+
+```ruby
+    'skip_on_db_migrate'   => 'true',
+```
+
+If you want to run `rake db:migrate` as a one-off without running annotate,
+you can do so with a simple environment variable, instead of editing the
+`.rake` file:
+
+    ANNOTATE_SKIP_ON_DB_MIGRATE=1 rake db:migrate
+
+## Options
+
+    Usage: annotate [options] [model_file]*
+            --additional-file-patterns   Additional file paths or globs to annotate, separated by commas (e.g. `/foo/bar/%model_name%/*.rb,/baz/%model_name%.rb`)
+        -d, --delete                     Remove annotations from all model files or the routes.rb file
+        -p [before|top|after|bottom],    Place the annotations at the top (before) or the bottom (after) of the model/test/fixture/factory/route/serializer file(s)
+            --position
+            --pc, --position-in-class [before|top|after|bottom]
+                                         Place the annotations at the top (before) or the bottom (after) of the model file
+            --pf, --position-in-factory [before|top|after|bottom]
+                                         Place the annotations at the top (before) or the bottom (after) of any factory files
+            --px, --position-in-fixture [before|top|after|bottom]
+                                         Place the annotations at the top (before) or the bottom (after) of any fixture files
+            --pt, --position-in-test [before|top|after|bottom]
+                                         Place the annotations at the top (before) or the bottom (after) of any test files
+            --pr, --position-in-routes [before|top|after|bottom]
+                                         Place the annotations at the top (before) or the bottom (after) of the routes.rb file
+            --ps, --position-in-serializer [before|top|after|bottom]
+                                         Place the annotations at the top (before) or the bottom (after) of the serializer files
+            --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
+            --wo, --wrapper-open STR     Annotation wrapper opening.
+            --wc, --wrapper-close STR    Annotation wrapper closing
+        -r, --routes                     Annotate routes.rb with the output of 'rake routes'
+            --models                     Annotate ActiveRecord models
+        -a, --active-admin               Annotate active_admin models
+        -v, --version                    Show the current version of this gem
+        -m, --show-migration             Include the migration version number in the annotation
+        -k, --show-foreign-keys          List the table's foreign key constraints in the annotation
+            --ck, --complete-foreign-keys
+                                         Complete foreign key names in the annotation
+        -i, --show-indexes               List the table's database indexes in the annotation
+        -s, --simple-indexes             Concat the column's related indexes in the annotation
+            --model-dir dir              Annotate model files stored in dir rather than app/models, separate multiple dirs with commas
+            --root-dir dir               Annotate files stored within root dir projects, separate multiple dirs with commas
+            --ignore-model-subdirects    Ignore subdirectories of the models directory
+            --sort                       Sort columns alphabetically, rather than in creation order
+            --classified-sort            Sort columns alphabetically, but first goes id, then the rest columns, then the timestamp columns and then the association columns
+        -R, --require path               Additional file to require before loading models, may be used multiple times
+        -e [tests,fixtures,factories,serializers],
+            --exclude                    Do not annotate fixtures, test files, factories, and/or serializers
+        -f [bare|rdoc|yard|markdown],    Render Schema Infomation as plain/RDoc/YARD/Markdown
+            --format
+            --force                      Force new annotations even if there are no changes.
+            --frozen                     Do not allow to change annotations. Exits non-zero if there are going to be changes to files.
+            --timestamp                  Include timestamp in (routes) annotation
+            --trace                      If unable to annotate a file, print the full stack trace, not just the exception message.
+        -I, --ignore-columns REGEX       don't annotate columns that match a given REGEX (e.g. `annotate -I '^(id|updated_at|created_at)'`)
+            --ignore-routes REGEX        don't annotate routes that match a given REGEX (e.g. `annotate -I '(mobile|resque|pghero)'`)_
+            --hide-limit-column-types VALUES
+                                         don't show limit for given column types, separated by commas (e.g. `integer,boolean,text`)
+            --hide-default-column-types VALUES
+                                         don't show default for given column types, separated by commas (e.g. `json,jsonb,hstore`)
+            --ignore-unknown-models      don't display warnings for bad model files
+            --with-comment               include database comments in model annotations
+
+### Option: `additional_file_patterns`
+
+CLI: `--additional-file-patterns`<br>
+Ruby: `:additional_file_patterns`
+
+Provide additional paths for the gem to annotate.  These paths can include
+globs. It is recommended to use absolute paths.  Here are some examples:
+
+*   `/app/lib/decorates/%MODEL_NAME%/*.rb`
+*   `/app/lib/forms/%PLURALIZED_MODEL_NAME%/**/*.rb`
+*   `/app/lib/forms/%TABLE_NAME%/*.rb`
+
+
+The appropriate model will be inferred using the `%*%` syntax, annotating any
+matching files. It works with existing filename resolutions (options for which
+can be found in the `resolve_filename` method of `annotate_models.rb`).
+
+When using in a Rails config, you can use the following:
+
+`File.join(Rails.application.root,
+'app/lib/forms/%PLURALIZED_MODEL_NAME%/***/**.rb')`
+
+## 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`.
+
+## Markdown
+
+The format produced is actually MultiMarkdown, making use of the syntax
+extension for tables.  It's recommended you use `kramdown` as your parser if
+you want to use this format.  If you're using `yard` to generate
+documentation, specify a format of markdown with `kramdown` as the provider by
+adding this to your `.yardopts` file:
+
+    --markup markdown
+    --markup-provider kramdown
+
+Be sure to add this to your `Gemfile` as well:
+
+    gem 'kramdown', groups => [:development], require => false
+
+## WARNING
+
+**Don't add text after an automatically-created comment block.** This tool
+will blow away the initial/final comment block in your models if it looks like
+it was previously added by this gem.
+
+Be sure to check the changes that this tool makes! If you are using Git, you
+may simply check your project's status after running `annotate`:
+
+    $ git status
+
+If you are not using a VCS (like Git, Subversion or similar), please tread
+extra carefully, and consider using one.
+
+## Links
+
+*   Factory Bot: http://github.com/thoughtbot/factory_bot
+*   Object Daddy: http://github.com/flogic/object_daddy
+*   Machinist: http://github.com/notahat/machinist
+*   Fabrication: http://github.com/paulelliott/fabrication
+*   SpatialAdapter: http://github.com/pdeffendol/spatial_adapter
+*   PostgisAdapter: http://github.com/nofxx/postgis_adapter
+*   PostGISAdapter: https://github.com/dazuma/activerecord-postgis-adapter
+
+
+## License
+
+Released under the same license as Ruby. No Support. No Warranty.
+
+## Authors
+
+[See AUTHORS.md](AUTHORS.md).

data/RELEASE.md

@@ -0,0 +1,19 @@
+## Prerequisite 
+
+- Install "git-flow" (`brew install git-flow`)
+- Install "bump" gem (`gem install bump`)
+
+
+## Perform a release
+
+- `git flow release start <release>`
+- Update the `CHANGELOG.md` file
+- `bump current`
+- `bump patch`
+- `rm -rf dist`
+- `rake spec`
+- `rake gem`
+- `git flow release finish <release>`
+
+- `rake gem:publish`
+

data/annotate.gemspec

@@ -1,39 +1,32 @@
-# This file is auto-generated!
-# DO NOT EDIT THIS FILE DIRECTLY!
-# Instead, edit the Rakefile and run 'rake gems:gemspec'.# -*- encoding: utf-8 -*-
-# stub: annotate 2.6.3 ruby lib
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'annotate/version'
 
 Gem::Specification.new do |s|
-  s.name = "annotate"
-  s.version = "2.6.3"
+  s.name = 'annotate'
+  s.version = Annotate.version
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.require_paths = ["lib"]
-  s.authors = ["Alex Chaffee", "Cuong Tran", "Marcos Piccinini", "Turadg Aleahmad", "Jon Frisby"]
-  s.date = "2014-04-05"
-  s.description = "Annotates Rails/ActiveRecord Models, routes, fixtures, and others based on the database schema."
-  s.email = ["alex@stinky.com", "cuong@gmail.com", "x@nofxx.com", "turadg@aleahmad.net", "jon@cloudability.com"]
-  s.executables = ["annotate"]
-  s.extra_rdoc_files = ["README.rdoc", "CHANGELOG.rdoc", "TODO.rdoc"]
-  s.files = [".travis.yml", "AUTHORS.rdoc", "CHANGELOG.rdoc", "LICENSE.txt", "README.rdoc", "TODO.rdoc", "annotate.gemspec", "bin/annotate", "lib/annotate.rb", "lib/annotate/active_record_patch.rb", "lib/annotate/annotate_models.rb", "lib/annotate/annotate_routes.rb", "lib/annotate/tasks.rb", "lib/annotate/version.rb", "lib/generators/annotate/USAGE", "lib/generators/annotate/install_generator.rb", "lib/generators/annotate/templates/auto_annotate_models.rake", "lib/tasks/annotate_models.rake", "lib/tasks/annotate_routes.rake", "lib/tasks/migrate.rake"]
-  s.homepage = "http://github.com/ctran/annotate_models"
-  s.licenses = ["Ruby"]
-  s.rubyforge_project = "annotate"
-  s.rubygems_version = "2.2.2"
-  s.summary = "Annotates Rails Models, routes, fixtures, and others based on the database schema."
+  s.required_ruby_version = '>= 2.4.0'
+  s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to? :required_rubygems_version=
+  s.authors = ['Alex Chaffee', 'Cuong Tran', 'Marcos Piccinini', 'Turadg Aleahmad', 'Jon Frisby']
+  s.description = 'Annotates Rails/ActiveRecord Models, routes, fixtures, and others based on the database schema.'
+  s.email = ['alex@stinky.com', 'cuong.tran@gmail.com', 'x@nofxx.com', 'turadg@aleahmad.net', 'jon@cloudability.com']
+  s.executables = ['annotate']
+  s.extra_rdoc_files = ['README.md', 'CHANGELOG.md']
+  s.files = `git ls-files -z LICENSE.txt *.md *.gemspec bin lib`.split("\x0")
+  s.homepage = 'https://github.com/ctran/annotate_models'
+  s.licenses = ['Ruby']
+  s.require_paths = ['lib']
+  s.rubygems_version = '2.1.11'
+  s.summary = 'Annotates Rails Models, routes, fixtures, and others based on the database schema.'
 
-  if s.respond_to? :specification_version then
-    s.specification_version = 4
+  s.specification_version = 4 if s.respond_to? :specification_version
+  s.add_runtime_dependency(%q<rake>, '>= 10.4', '< 14.0')
+  s.add_runtime_dependency(%q<activerecord>, ['>= 3.2', '< 8.0'])
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<rake>, [">= 0.8.7"])
-      s.add_runtime_dependency(%q<activerecord>, [">= 2.3.0"])
-    else
-      s.add_dependency(%q<rake>, [">= 0.8.7"])
-      s.add_dependency(%q<activerecord>, [">= 2.3.0"])
-    end
-  else
-    s.add_dependency(%q<rake>, [">= 0.8.7"])
-    s.add_dependency(%q<activerecord>, [">= 2.3.0"])
-  end
+  s.metadata = {
+    "bug_tracker_uri" => "https://github.com/ctran/annotate_models/issues/",
+    "source_code_uri" => "https://github.com/ctran/annotate_models.git"
+  }
 end

data/bin/annotate

@@ -1,148 +1,32 @@
 #!/usr/bin/env ruby
+
+unless File.exist?('./Rakefile') || File.exist?('./Gemfile')
+  abort 'Please run annotate from the root of the project.'
+end
+
 require 'rubygems'
 begin
   require 'bundler'
   Bundler.setup
-rescue Exception => e
+rescue StandardError
 end
 
 here = File.expand_path(File.dirname __FILE__)
-$:<< "#{here}/../lib"
+$LOAD_PATH << "#{here}/../lib"
 
-require 'optparse'
 require 'annotate'
-Annotate.bootstrap_rake
-
-target = {
-  :klass => AnnotateModels,
-  :task => :do_annotations,
-}
-has_set_position = {}
-OptionParser.new do |opts|
-  opts.banner = "Usage: annotate [options] [model_file]*"
-
-  opts.on('-d', '--delete',
-          "Remove annotations from all model files or the routes.rb file") do
-
-    target[:task] = :remove_annotations
-  end
-
-  opts.on('-p', '--position [before|after]', ['before', 'after'],
-          "Place the annotations at the top (before) or the bottom (after) of the model/test/fixture/factory/routes file(s)") do |p|
-    ENV['position'] = p
-    [
-      'position_in_class','position_in_factory','position_in_fixture','position_in_test', 'position_in_routes'
-    ].each do |key|
-      ENV[key] = p unless(has_set_position[key])
-    end
-  end
-
-  opts.on('--pc', '--position-in-class [before|after]', ['before', 'after'],
-          "Place the annotations at the top (before) or the bottom (after) of the model file") do |p|
-    ENV['position_in_class'] = p
-    has_set_position['position_in_class'] = true
-  end
-
-  opts.on('--pf', '--position-in-factory [before|after]', ['before', 'after'],
-          "Place the annotations at the top (before) or the bottom (after) of any factory files") do |p|
-    ENV['position_in_factory'] = p
-    has_set_position['position_in_factory'] = true
-  end
-
-  opts.on('--px', '--position-in-fixture [before|after]', ['before', 'after'],
-          "Place the annotations at the top (before) or the bottom (after) of any fixture files") do |p|
-    ENV['position_in_fixture'] = p
-    has_set_position['position_in_fixture'] = true
-  end
-
-  opts.on('--pt', '--position-in-test [before|after]', ['before', 'after'],
-          "Place the annotations at the top (before) or the bottom (after) of any test files") do |p|
-    ENV['position_in_test'] = p
-    has_set_position['position_in_test'] = true
-  end
-
-  opts.on('--pr', '--position-in-routes [before|after]', ['before', 'after'],
-          "Place the annotations at the top (before) or the bottom (after) of the routes.rb file") do |p|
-    ENV['position_in_routes'] = p
-    has_set_position['position_in_routes'] = true
-  end
+require 'annotate/parser'
 
-  opts.on('-r', '--routes',
-          "Annotate routes.rb with the output of 'rake routes'") do
-    target = {
-      :klass => AnnotateRoutes,
-      :task => :do_annotations
-    }
-  end
-
-  opts.on('-v', '--version',
-          "Show the current version of this gem") do
-    puts "annotate v#{Annotate.version}"; exit
-  end
-
-  opts.on('-m', '--show-migration',
-          "Include the migration version number in the annotation") do
-    ENV['include_version'] = "yes"
-  end
-
-  opts.on('-i', '--show-indexes',
-          "List the table's database indexes in the annotation") do
-    ENV['show_indexes'] = "yes"
-  end
-
-  opts.on('-s', '--simple-indexes',
-          "Concat the column's related indexes in the annotation") do
-    ENV['simple_indexes'] = "yes"
-  end
-
-  opts.on('--model-dir dir',
-          "Annotate model files stored in dir rather than app/models") do |dir|
-    ENV['model_dir'] = dir
-  end
-
-  opts.on('--ignore-model-subdirects',
-          "Ignore subdirectories of the models directory") do |dir|
-    ENV['ignore_model_sub_dir'] = "yes"
-  end
-
-  opts.on('--sort',
-          "Sort columns alphabetically, rather than in creation order") do |dir|
-    ENV['sort'] = "yes"
-  end
-
-  opts.on('-R', '--require path',
-          "Additional file to require before loading models, may be used multiple times") do |path|
-    if !ENV['require'].blank?
-      ENV['require'] = ENV['require'] + ",#{path}"
-    else
-      ENV['require'] = path
-    end
-  end
-
-  opts.on('-e', '--exclude [tests,fixtures,factories]', Array, "Do not annotate fixtures, test files, and/or factories") do |exclusions|
-    exclusions ||= %w(tests fixtures factories)
-    exclusions.each { |exclusion| ENV["exclude_#{exclusion}"] = "yes" }
-  end
-
-  opts.on('-f', '--format [bare|rdoc|markdown]', ['bare', 'rdoc', 'markdown'], 'Render Schema Infomation as plain/RDoc/Markdown') do |fmt|
-    ENV["format_#{fmt}"] = 'yes'
-  end
-
-  opts.on('--force', 'Force new annotations even if there are no changes.') do |force|
-    ENV['force'] = 'yes'
-  end
-
-  opts.on('--trace', 'If unable to annotate a file, print the full stack trace, not just the exception message.') do |value|
-    ENV['trace'] = 'yes'
-  end
+Annotate.bootstrap_rake
 
-  opts.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
+options_result = Annotate::Parser.parse(ARGV)
 
-end.parse!
+exit if options_result[:exit]
 
+options = Annotate.setup_options(
+  is_rake: ENV['is_rake'] && !ENV['is_rake'].empty?
+)
+Annotate.eager_load(options) if Annotate::Helpers.include_models?
 
-options=Annotate.setup_options({ :is_rake => !ENV['is_rake'].blank? })
-Annotate.eager_load(options)
-target[:klass].send(target[:task], options)
+AnnotateModels.send(options_result[:target_action], options) if Annotate::Helpers.include_models?
+AnnotateRoutes.send(options_result[:target_action], options) if Annotate::Helpers.include_routes?

data/lib/annotate/active_record_patch.rb

@@ -2,7 +2,7 @@
 
 module ::ActiveRecord
   class Base
-    def self.method_missing(name, *args)
+    def self.method_missing(_name, *_args)
       # ignore this, so unknown/unloaded macros won't cause parsing to fail
     end
   end