annotate 2.4.1.beta1 → 2.5.0.pre1

data/History.txt

@@ -1,3 +1,77 @@
+== 2.5.0
+
+* Fixed that schema kept prepending additional newlines
+* Updates to make annotate smarter about when to touch a model 
+* Recognize column+type, and don't change a file unless the column+type combination of the new schema are different than that of the old (i.e., don't regenerate if columns happen to be in a different order. That's just how life is sometimes)
+* Grab old specification even if it has \r\n as line endings rather than pure \ns
+* Various warning and specification fixes
+* Fix "no such file to load -- annotate/annotate_models (MissingSourceFile)" error (require statements in tasks now use full path to lib files)
+* warn about macros, to mitigate when we're included during a production run, not just a rakefile run -- possibly at the expense of too much noise 
+* Adding rake as a runtime dependency
+* If the schema is already in the model file, it will be replaced into the same location.  If it didn't previously exist, it'll be placed according to the "position", as before. 
+* Allow task loading from Rakefile for gems (plugin installation already auto-detects).
+* Add skip_on_db_migrate option as well for people that don't want it 
+* Fix options parsing to convert strings to proper booleans. Change annotate to use opt
+ ions hash instead of ENV. 
+* Add support for Fabrication fabricators
+* Leave magic encoding comment intact
+* Fix issue #14 - RuntimeError: Already memoized
+* Count a model as 'annotated' if any of its tests/fixtures are annotated
+* Support FactoryGirl
+* Support :change migrations (Rails 3.1)
+* Allow models with non-standard capitalization
+* Widen type column so we can handle longtexts with chopping things off.
+* Skip trying to get list of models from commandline when running via Rake (was
+  preventing the use of multiple rake tasks in one command if one of them was
+  db:migrate).
+* Add ability to skip annotations for a model by adding
+  '# -*- SkipSchemaAnnotations' anywhere in the file.
+* Don't show column limits for integer and boolean types.
+* Add sorting for columns and indexes. (Helpful for out-of-order migration
+  execution, but use --no-sort if you don't want this.)
+* Annotate unit tests in subfolders.
+* Add generator to install rakefile that automatically annotates on db:migrate.
+* Correct Gemfile to clarify which environments need which gems.
+* Add an .rvmrc to facilitate clean development.
+* Refactor out ActiveRecord monkey-patch to permit extending without
+  side-effects.
+* Use ObjectSpace to locate models to facilitate handling of models with
+  non-standard capitalization.
+  Note that this still requires that the inflector be configured to understand
+  the special case.
+* Shore up test cases a bit.
+* Merge against many of the older branches on Github whose functionality is
+  already reflected to reduce confusion about what is and is not implemented
+  here.
+* Accept String or Symbol for :position (et al) options.
+* Rename "annotate" bin to "annotate_models" to avoid conflicting with
+  ImageMagick.
+* Add RDoc output formatting as an option.
+* Add Markdown output formatting as an option.
+* Add option to force annotation regeneration.
+* Add new configuration option for controlling where info is placed in
+  fixtures/factories.
+* Fix for models without tables.
+* Fix gemspec generation now that Jeweler looks at Gemfile.
+* Fix warning: `NOTE: Gem::Specification#default_executable= is deprecated with
+  no replacement. It will be removed on or after 2011-10-01.`
+* Fix handling of files with no trailing newline when putting annotations at
+  the end of the file.
+
+== 2.4.2 2009-11-21
+
+* Annotates (spec|test)/factories/<model>_factory.rb files
+
+== 2.4.1 2009-11-20
+
+* Annotates thoughtbot's factory_girl factories (test/factories/<model>_factory.rb)
+* Move default annotation position back to top
+
+== 2.4.0 2009-12-13
+
+* Incorporated lots of patches from the Github community, including support for Blueprints fixtures
+* Several bug fixes
+
 == 2.1 2009-10-18
 
 * New options
@@ -5,7 +79,7 @@
   * -i to show database indexes in annotations
   * -e to exclude annotating tests or fixtures
   * -m to include the migration version number in the annotation
-  * --model-dir to annotate model files stored a different place than app/models  
+  * --model-dir to annotate model files stored a different place than app/models
 * Ignore unknown macros ('acts_as_whatever')
 
 == 2.0 2009-02-03

data/README.rdoc

@@ -2,11 +2,14 @@
 
 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
+- ActiveRecord models
+- Fixture files
+- Tests and Specs
+- Object Daddy exemplars
+- Machinist blueprints
+- Fabrication fabricators
+- Thoughtbot's factory_girl factories, i.e. the (spec|test)/factories/<model>_factory.rb files
+- routes.rb file
 
 The schema comment looks like this:
 
@@ -40,20 +43,18 @@ Also, if you pass the -r option, it'll annotate routes.rb with the output of "ra
 
 Into Gemfile from Github:
 
-    gem 'annotate', :git => 'git://github.com/ctran/annotate_models.git'
-    
+    gem 'annotate', :git => 'git://github.com/MrJoy/annotate_models.git'
 
-Into environment gems From Rubygems.org:
+Into environment gems From rubygems.org:
 
-  sudo gem install annotate
+    gem install annotate
 
 Into environment gems from Github checkout:
 
-  git clone git://github.com/ctran/annotate_models.git annotate
-  cd annotate
-  rake gem
-  sudo gem install pkg/annotate-*.gem
-
+  git clone git://github.com/MrJoy/annotate_models.git annotate_models
+  cd annotate_models
+  rake build
+  gem install pkg/annotate-*.gem
 
 == USAGE
 
@@ -62,43 +63,61 @@ Into environment gems from Github checkout:
 To annotate all your models, tests, fixtures, etc.:
 
   cd /path/to/app
-  annotate
+  annotate_models
 
 To annotate your models and tests:
 
-  annotate --exclude fixtures
+  annotate_models --exclude fixtures
 
 To annotate just your models:
 
-  annotate --exclude tests,fixtures
+  annotate_models --exclude tests,fixtures
 
 To annotate routes.rb:
 
-  annotate -r
+  annotate_models -r
+
+To remove annotations:
+
+  annotate_models -d
+
+To automatically annotate after running 'rake db:migrate', ensure you've added
+annotate_models to your Rails project's Gemfile, and run this:
+
+  rails g annotate_models:install
 
-To automatically annotate after running 'rake db:migrate':
-  
-  [*needs more clarity*] unpack the gem into vendor/plugins, or maybe vendor/gems, or maybe just require tasks/migrate.rake.
+This will produce a .rake file that will ensure annotation happens after
+migration (but only in development mode), and provide configuration options
+you can use to tailor the output.
 
-If you install annotate_models as a plugin, it will automatically
-adjust your <tt>rake db:migrate</tt> tasks so that they update the
-annotations in your model files for you once the migration is
-completed.
+If you want to always skip annotations on a particular model, add this string
+anywhere in the file:
+
+  # -*- SkipSchemaAnnotations
 
 == OPTIONS
 
-    Usage: annotate [options] [model_file]*
+    Usage: annotate_models [options] [model_file]*
         -d, --delete                     Remove annotations from all model files
         -p, --position [before|after]    Place the annotations at the top (before) or the bottom (after) of the model file
         -r, --routes                     Annotate routes.rb with the output of 'rake routes'
         -v, --version                    Show the current version of this gem
         -m, --show-migration             Include the migration version number 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
+        -i, --show-indexes               List the indexes for the table in the annotation
+        -s, --simple-indexes             Include information about indexes inline with the relevant column
             --model-dir dir              Annotate model files stored in dir rather than app/models
+            --ignore-model-subdirs       Ignore sub-directories of the models directory.
         -R, --require path               Additional files to require before loading models
-        -e, --exclude [tests,fixtures]   Do not annotate fixtures, test files, or both
+        -e [tests,fixtures]              Skip annotation of fixtures/factories/test files
+            --exclude
+        -n  --no-sort                    Sort by column creation order rather than alphabetical order
+
+== SORTING
 
+By default, columns will be sorted alphabetically so that the results of
+annotation are consistent regardless of what order migrations are executed in.
+
+If you prefer the old behavior, use --no-sort.
 
 == WARNING
 
@@ -107,40 +126,44 @@ block in your models if it looks like it was previously added
 by annotate models, so you don't want to add additional text
 to an automatically created comment block.
 
-        * * Back up your model files before using... * *
+BACK UP YOUR MODELS BEFORE USING THIS TOOL!
 
 == LINKS
 
-* Factory Girl => http://github.com/thoughtbot/factory_girl (NOT IMPLEMENTED)
-* Object Daddy => http://github.com/flogic/object_daddy
-* SpatialAdapter => http://github.com/pdeffendol/spatial_adapter
-* PostgisAdapter => http://github.com/nofxx/postgis_adapter
+- Factory Girl: http://github.com/thoughtbot/factory_girl
+- 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
 
 == LICENSE:
 
 Released under the same license as Ruby. No Support. No Warranty.
 
-== AUTHOR:
-
-Original code by: Dave Thomas -- Pragmatic Programmers, LLC
-Overhauled by: Alex Chaffee
-Gemmed by: Cuong Tran
-Maintained by: Alex Chaffee and Cuong Tran
-
-Modifications by:
-
- - Alex Chaffee - http://github.com/alexch - alex@pivotallabs.com
- - Cuong Tran - http://github.com/ctran - ctran@pragmaquest.com
- - Jack Danger - http://github.com/JackDanger
- - Michael Bumann - http://github.com/bumi
- - Henrik Nyh - http://github.com/henrik
- - Marcos Piccinini - http://github.com/nofxx
- - Neal Clark - http://github.com/nclark
- - Jacqui Maher - http://github.com/jacqui
- - Nick Plante - http://github.com/zapnap - http://blog.zerosum.org
- - Pedro Visintin - http://github.com/peterpunk - http://www.pedrovisintin.com
- - Bob Potter - http://github.com/bpot
- - Gavin Montague - http://github.com/govan/
- - Alexander Semyonov - http://github.com/rotuka/
- 
+== AUTHORS:
+
+- Original code by: Dave Thomas -- Pragmatic Programmers, LLC <http://agilewebdevelopment.com/plugins/annotate_models>
+- Overhauled by: Alex Chaffee <http://alexch.github.com> alex@stinky.com
+- Gemmed by: Cuong Tran <http://github.com/ctran> ctran@pragmaquest.com
+- Maintained by: Alex Chaffee and Cuong Tran
+- Homepage: http://github.com/ctran/annotate_models
+
+With help from:
+
+- Jack Danger - http://github.com/JackDanger
+- Michael Bumann - http://github.com/bumi
+- Henrik Nyh - http://github.com/henrik
+- Marcos Piccinini - http://github.com/nofxx
+- Neal Clark - http://github.com/nclark
+- Jacqui Maher - http://github.com/jacqui
+- Nick Plante - http://github.com/zapnap - http://blog.zerosum.org
+- Pedro Visintin - http://github.com/peterpunk - http://www.pedrovisintin.com
+- Bob Potter - http://github.com/bpot
+- Gavin Montague - http://github.com/govan
+- Alexander Semyonov - http://github.com/rotuka
+- Nathan Brazil - http://github.com/bitaxis
+- Ian Duggan http://github.com/ijcd
+- Jon Frisby http://github.com/mrjoy
+
 and many others that I may have missed to add.

data/bin/annotate

@@ -1,55 +1,73 @@
 #!/usr/bin/env ruby
-
 require 'optparse'
-require 'annotate'
+require 'rake/dsl_definition'
+require 'rake'
+begin
+  require "annotate"
+rescue LoadError
+  here = File.expand_path(File.dirname __FILE__)
+  $:<< "#{here}/../lib"
+  require "annotate"
+end
 
 task = :annotate_models
 
 OptionParser.new do |opts|
-  opts.banner = "Usage: annotate [options] [model_file]*"
+  opts.banner = "Usage: annotate_models [options] [model_file]*"
 
-  opts.on('-d', '--delete', 
-  "Remove annotations from all model files") do
+  opts.on('-d', '--delete',
+          "Remove annotations from all model files") do
     task = :remove_annotation
   end
 
-  opts.on('-p', '--position [before|after]', ['before', 'after'], 
-  "Place the annotations at the top (before) or the bottom (after) of the model file") do |p| 
+  ENV['position'] = 'before' # hack: make sure default position is "before"
+  opts.on('-p', '--position [before|after]', ['before', 'after'],
+          "Place the annotations at the top (before) or the bottom (after) of the model file") do |p|
     ENV['position'] = p
   end
 
-  opts.on('-r', '--routes', 
-  "Annotate routes.rb with the output of 'rake routes'") do
+  opts.on('-r', '--routes',
+          "Annotate routes.rb with the output of 'rake routes'") do
     task = :annotate_routes
   end
 
-  opts.on('-v', '--version', 
-  "Show the current version of this gem") do 
+  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
+  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   
+  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
+          "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|
+  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('-n', '--no-sort',
+          "Sort columns in creation order rather than alphabetically") do |dir|
+    ENV['no_sort'] = "yes"
+  end
+
   opts.on('-R', '--require path',
-  "Additional files to require before loading models") do |path|
+          "Additional files to require before loading models") do |path|
     if ENV['require']
       ENV['require'] = ENV['require'] + ",#{path}"
     else
@@ -61,8 +79,17 @@ OptionParser.new do |opts|
     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
+
 end.parse!
 
+ENV['is_cli'] = '1'
 if Annotate.load_tasks
   Rake::Task[task].invoke
 else

data/lib/annotate.rb

@@ -1,23 +1,13 @@
-$:.unshift(File.dirname(__FILE__)) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
-
-require 'yaml'
+here = File.dirname __FILE__
+require "#{here}/annotate/version"
 
 module Annotate
-  def self.version
-    version_file = File.dirname(__FILE__) + "/../VERSION.yml"
-    if File.exist?(version_file)
-      config = YAML.load(File.read(version_file))
-      version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
-    else
-      version = "0.0.0"
-    end
-  end
-  
   def self.load_tasks
     if File.exists?('Rakefile')
       require 'rake'
       load 'Rakefile'
+      # Rails 3 wants to load our .rake files for us.
+      # TODO: selectively do this require on Rails 2.x?
       Dir[File.join(File.dirname(__FILE__), 'tasks', '**/*.rake')].each { |rake| load rake }
       return true
     else

data/lib/annotate/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/annotate_models.rb

@@ -1,20 +1,41 @@
 module AnnotateModels
-  class << self
-    # Annotate Models plugin use this header
-    COMPAT_PREFIX = "== Schema Info"
-    PREFIX = "== Schema Information"
-
-    FIXTURE_DIRS = ["test/fixtures","spec/fixtures"]
-    # File.join for windows reverse bar compat?
-    # I dont use windows, can`t test
-    UNIT_TEST_DIR     = File.join("test", "unit"  )
-    SPEC_MODEL_DIR    = File.join("spec", "models")
-    # Object Daddy http://github.com/flogic/object_daddy/tree/master
-    EXEMPLARS_TEST_DIR     = File.join("test", "exemplars")
-    EXEMPLARS_SPEC_DIR     = File.join("spec", "exemplars")
-    # Machinist http://github.com/notahat/machinist
-    BLUEPRINTS_DIR         = File.join("test", "blueprints")
+  # Annotate Models plugin use this header
+  COMPAT_PREFIX    = "== Schema Info"
+  COMPAT_PREFIX_MD = "## Schema Info"
+  PREFIX           = "== Schema Information"
+  PREFIX_MD        = "## Schema Information"
+  END_MARK         = "== Schema Information End"
+  PATTERN          = /^\n?# (?:#{COMPAT_PREFIX}|#{COMPAT_PREFIX_MD}).*?\n(#.*\n)*\n/
+
+  # File.join for windows reverse bar compat?
+  # I dont use windows, can`t test
+  UNIT_TEST_DIR         = File.join("test", "unit"  )
+  SPEC_MODEL_DIR        = File.join("spec", "models")
+  FIXTURE_TEST_DIR      = File.join("test", "fixtures")
+  FIXTURE_SPEC_DIR      = File.join("spec", "fixtures")
+  FIXTURE_DIRS = ["test/fixtures","spec/fixtures"]
+
+  # Object Daddy http://github.com/flogic/object_daddy/tree/master
+  EXEMPLARS_TEST_DIR    = File.join("test", "exemplars")
+  EXEMPLARS_SPEC_DIR    = File.join("spec", "exemplars")
+
+  # Machinist http://github.com/notahat/machinist
+  BLUEPRINTS_TEST_DIR   = File.join("test", "blueprints")
+  BLUEPRINTS_SPEC_DIR   = File.join("spec", "blueprints")
+
+  # Factory Girl http://github.com/thoughtbot/factory_girl
+  FACTORY_GIRL_TEST_DIR = File.join("test", "factories")
+  FACTORY_GIRL_SPEC_DIR = File.join("spec", "factories")
+
+  # Fabrication https://github.com/paulelliott/fabrication.git
+  FABRICATORS_TEST_DIR  = File.join("test", "fabricators")
+  FABRICATORS_SPEC_DIR  = File.join("spec", "fabricators")
+
+  # Don't show limit (#) on these column types
+  # Example: show "integer" instead of "integer(4)"
+  NO_LIMIT_COL_TYPES = ["integer", "boolean"]
 
+  class << self
     def model_dir
       @model_dir || "app/models"
     end
@@ -26,14 +47,14 @@ module AnnotateModels
     # Simple quoting for the default column value
     def quote(value)
       case value
-        when NilClass                 then "NULL"
-        when TrueClass                then "TRUE"
-        when FalseClass               then "FALSE"
-        when Float, Fixnum, Bignum    then value.to_s
+      when NilClass                 then "NULL"
+      when TrueClass                then "TRUE"
+      when FalseClass               then "FALSE"
+      when Float, Fixnum, Bignum    then value.to_s
         # BigDecimals need to be output in a non-normalized form and quoted.
-        when BigDecimal               then value.to_s('F')
-        else
-          value.inspect
+      when BigDecimal               then value.to_s('F')
+      else
+        value.inspect
       end
     end
 
@@ -42,21 +63,34 @@ module AnnotateModels
     # each column. The line contains the column name,
     # the type (and length), and any optional attributes
     def get_schema_info(klass, header, options = {})
-      info = "# #{header}\n#\n"
-      info << "# Table name: #{klass.table_name}\n#\n"
+      info = "# #{header}\n"
+      info<< "#\n"
+      info<< "# Table name: #{klass.table_name}\n"
+      info<< "#\n"
+
+      max_size = klass.column_names.map{|name| name.size}.max || 0
+      max_size += options[:format_rdoc] ? 5 : 1
 
-      max_size = klass.column_names.collect{|name| name.size}.max + 1
-      klass.columns.each do |col|
+      if(options[:format_markdown])
+        info<< sprintf( "# %-#{max_size + 4}.#{max_size + 4}s | %-18.18s | %s\n", 'Field', 'Type', 'Attributes' )
+        info<< "# #{ '-' * ( max_size + 4 ) } | #{'-' * 18} | #{ '-' * 25 }\n"
+      end
+
+      cols = klass.columns
+      cols = cols.sort_by(&:name) unless(options[:no_sort])
+      cols.each do |col|
         attrs = []
         attrs << "default(#{quote(col.default)})" unless col.default.nil?
         attrs << "not null" unless col.null
-        attrs << "primary key" if col.name == klass.primary_key
+        attrs << "primary key" if col.name.to_sym == klass.primary_key.to_sym
 
-        col_type = col.type.to_s
+        col_type = (col.type || col.sql_type).to_s
         if col_type == "decimal"
           col_type << "(#{col.precision}, #{col.scale})"
         else
-          col_type << "(#{col.limit})" if col.limit
+          if (col.limit)
+            col_type << "(#{col.limit})" unless NO_LIMIT_COL_TYPES.include?(col_type)
+          end
         end
 
         # Check out if we got a geometric column
@@ -66,8 +100,8 @@ module AnnotateModels
         end
 
         # Check if the column has indices and print "indexed" if true
-        # If the indice include another colum, print it too.
-        if options[:simple_indexes] # Check out if this column is indexed
+        # If the index includes another column, print it too.
+        if options[:simple_indexes] && klass.table_exists?# Check out if this column is indexed
           indices = klass.connection.indexes(klass.table_name)
           if indices = indices.select { |ind| ind.columns.include? col.name }
             indices.each do |ind|
@@ -77,14 +111,26 @@ module AnnotateModels
           end
         end
 
-        info << sprintf("#  %-#{max_size}.#{max_size}s:%-15.15s %s", col.name, col_type, attrs.join(", ")).rstrip + "\n"
+        if options[:format_rdoc]
+          info << sprintf("# %-#{max_size}.#{max_size}s<tt>%s</tt>", "*#{col.name}*::", attrs.unshift(col_type).join(", ")).rstrip + "\n"
+        elsif options[:format_markdown]
+          info << sprintf("# **%-#{max_size}.#{max_size}s** | `%-16.16s` | `%s`", col.name, col_type, attrs.join(", ").rstrip) + "\n"
+        else
+          info << sprintf("#  %-#{max_size}.#{max_size}s:%-16.16s %s", col.name, col_type, attrs.join(", ")).rstrip + "\n"
+        end
       end
 
-      if options[:show_indexes]
+      if options[:show_indexes] && klass.table_exists?
         info << get_index_info(klass)
       end
 
-      info << "#\n\n"
+      if options[:format_rdoc]
+        info << "#--\n"
+        info << "# #{END_MARK}\n"
+        info << "#++\n\n"
+      else
+        info << "#\n\n"
+      end
     end
 
     def get_index_info(klass)
@@ -94,7 +140,7 @@ module AnnotateModels
       return "" if indexes.empty?
 
       max_size = indexes.collect{|index| index.name.size}.max + 1
-      indexes.each do |index|
+      indexes.sort_by{|index| index.name}.each do |index|
         index_info << sprintf("#  %-#{max_size}.#{max_size}s %s %s", index.name, "(#{index.columns.join(",")})", index.unique ? "UNIQUE" : "").rstrip + "\n"
       end
       return index_info
@@ -108,7 +154,7 @@ module AnnotateModels
     #
     # === Options (opts)
     #  :position<Symbol>:: where to place the annotated section in fixture or model file,
-    #                      "before" or "after". Default is "before".
+    #                      :before or :after. Default is :before.
     #  :position_in_class<Symbol>:: where to place the annotated section in model file
     #  :position_in_fixture<Symbol>:: where to place the annotated section in fixture file
     #  :position_in_others<Symbol>:: where to place the annotated section in the rest of
@@ -117,26 +163,44 @@ module AnnotateModels
     def annotate_one_file(file_name, info_block, options={})
       if File.exist?(file_name)
         old_content = File.read(file_name)
+        return false if(old_content =~ /# -\*- SkipSchemaAnnotations.*\n/)
 
         # Ignore the Schema version line because it changes with each migration
-        header = Regexp.new(/(^# Table name:.*?\n(#.*[\r]?\n)*[\r]?\n)/)
-        old_header = old_content.match(header).to_s
-        new_header = info_block.match(header).to_s
+        header_pattern = /(^# Table name:.*?\n(#.*[\r]?\n)*[\r]?\n)/
+        old_header = old_content.match(header_pattern).to_s
+        new_header = info_block.match(header_pattern).to_s
 
-        old_columns = old_header && old_header.scan(/#[\t\s]+([\w\d]+)[\t\s]+\:([\d\w]+)/).sort
-        new_columns = new_header && new_header.scan(/#[\t\s]+([\w\d]+)[\t\s]+\:([\d\w]+)/).sort
+        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
 
-        if old_columns == new_columns
+        encoding = Regexp.new(/(^#\s*encoding:.*\n)|(^# coding:.*\n)|(^# -\*- coding:.*\n)/)
+        encoding_header = old_content.match(encoding).to_s
+
+        if old_columns == new_columns && !options[:force]
           false
         else
-          # Replace the old schema info with the new schema info
-          new_content = old_content.sub(/^# #{COMPAT_PREFIX}.*?\n(#.*\n)*\n/, info_block)
-          # But, if there *was* no old schema info, we simply need to insert it
-          if new_content == old_content
-            new_content = options[:position] == 'before' ?
-              (info_block + old_content) :
-              ((old_content =~ /\n$/ ? old_content : old_content + '\n') + info_block)
-          end
+          
+# todo: figure out if we need to extract any logic from this merge chunk
+# <<<<<<< HEAD
+#           # Replace the old schema info with the new schema info
+#           new_content = old_content.sub(/^# #{COMPAT_PREFIX}.*?\n(#.*\n)*\n*/, info_block)
+#           # But, if there *was* no old schema info, we simply need to insert it
+#           if new_content == old_content
+#             old_content.sub!(encoding, '')
+#             new_content = options[:position] == 'after' ?
+#               (encoding_header + (old_content =~ /\n$/ ? old_content : old_content + "\n") + info_block) :
+#               (encoding_header + info_block + old_content)
+#           end
+# =======
+
+          # Strip the old schema info, and insert new schema info.
+          old_content.sub!(encoding, '')
+          old_content.sub!(PATTERN, '')
+          
+          new_content = (options[:position] || 'before').to_s == 'after' ?
+            (encoding_header + (old_content.rstrip + "\n\n" + info_block)) :
+            (encoding_header + info_block + old_content)
 
           File.open(file_name, "wb") { |f| f.puts new_content }
           true
@@ -148,7 +212,7 @@ module AnnotateModels
       if File.exist?(file_name)
         content = File.read(file_name)
 
-        content.sub!(/^# #{COMPAT_PREFIX}.*?\n(#.*\n)*\n/, '')
+        content.sub!(PATTERN, '')
 
         File.open(file_name, "wb") { |f| f.puts content }
       end
@@ -160,7 +224,7 @@ module AnnotateModels
     # of the model and fixture source files.
     # Returns true or false depending on whether the source
     # files were modified.
-    def annotate(klass, file, header,options={})
+    def annotate(klass, file, header, options={})
       info = get_schema_info(klass, header, options)
       annotated = false
       model_name = klass.name.underscore
@@ -169,37 +233,41 @@ module AnnotateModels
       if annotate_one_file(model_file_name, info, options_with_position(options, :position_in_class))
         annotated = true
       end
- 
-      unless ENV['exclude_tests']
+
+      unless options[:exclude_tests]
         [
-          File.join(UNIT_TEST_DIR,      "#{model_name}_test.rb"), # test
-          File.join(SPEC_MODEL_DIR,     "#{model_name}_spec.rb"), # spec
-        ].each do |file| 
+          find_test_file(UNIT_TEST_DIR,      "#{model_name}_test.rb"), # test
+          find_test_file(SPEC_MODEL_DIR,     "#{model_name}_spec.rb"), # spec
+        ].each do |file|
           # todo: add an option "position_in_test" -- or maybe just ask if anyone ever wants different positions for model vs. test vs. fixture
-          annotate_one_file(file, info, options_with_position(options, :position_in_fixture))
+          if annotate_one_file(file, info, options_with_position(options, :position_in_fixture))
+            annotated = true
+          end
         end
       end
 
-      unless ENV['exclude_fixtures']
+      unless options[:exclude_fixtures]
         [
-        File.join(EXEMPLARS_TEST_DIR, "#{model_name}_exemplar.rb"),  # Object Daddy
-        File.join(EXEMPLARS_SPEC_DIR, "#{model_name}_exemplar.rb"),  # Object Daddy
-        File.join(BLUEPRINTS_DIR,     "#{model_name}_blueprint.rb"), # Machinist Blueprints
-        ].each do |file| 
-          annotate_one_file(file, info, options_with_position(options, :position_in_fixture))
-        end
-
-        FIXTURE_DIRS.each do |dir|
-          fixture_file_name = File.join(dir,klass.table_name + ".yml")
-          if File.exist?(fixture_file_name)
-            annotate_one_file(fixture_file_name, info, options_with_position(options, :position_in_fixture))         
+         File.join(FIXTURE_TEST_DIR,       "#{klass.table_name}.yml"),     # fixture
+         File.join(FIXTURE_SPEC_DIR,       "#{klass.table_name}.yml"),     # fixture
+         File.join(EXEMPLARS_TEST_DIR,     "#{model_name}_exemplar.rb"),   # Object Daddy
+         File.join(EXEMPLARS_SPEC_DIR,     "#{model_name}_exemplar.rb"),   # Object Daddy
+         File.join(BLUEPRINTS_TEST_DIR,    "#{model_name}_blueprint.rb"),  # Machinist Blueprints
+         File.join(BLUEPRINTS_SPEC_DIR,    "#{model_name}_blueprint.rb"),  # Machinist Blueprints
+         File.join(FACTORY_GIRL_TEST_DIR,  "#{model_name}_factory.rb"),    # Factory Girl Factories
+         File.join(FACTORY_GIRL_SPEC_DIR,  "#{model_name}_factory.rb"),    # Factory Girl Factories
+         File.join(FABRICATORS_TEST_DIR,   "#{model_name}_fabricator.rb"), # Fabrication Fabricators
+         File.join(FABRICATORS_SPEC_DIR,   "#{model_name}_fabricator.rb"), # Fabrication Fabricators
+        ].each do |file|
+          if annotate_one_file(file, info, options_with_position(options, :position_in_fixture))
+            annotated = true
           end
         end
       end
-      
+
       annotated
     end
-    
+
     # position = :position_in_fixture or :position_in_class
     def options_with_position(options, position_in)
       options.merge(:position=>(options[position_in] || options[:position]))
@@ -210,14 +278,22 @@ module AnnotateModels
     # the underscore or CamelCase versions of model names.
     # Otherwise we take all the model files in the
     # model_dir directory.
-    def get_model_files
-      models = ARGV.dup
-      models.shift
+    def get_model_files(options)
+      if(!options[:is_rake])
+        models = ARGV.dup
+        models.shift
+      else
+        models = []
+      end
       models.reject!{|m| m.match(/^(.*)=/)}
       if models.empty?
         begin
           Dir.chdir(model_dir) do
-            models = Dir["**/*.rb"]
+            models = if options[:ignore_model_sub_dir]
+              Dir["*.rb"]
+            else
+              Dir["**/*.rb"]
+            end
           end
         rescue SystemCallError
           puts "No models found in directory '#{model_dir}'."
@@ -233,18 +309,18 @@ module AnnotateModels
     # Check for namespaced models in subdirectories as well as models
     # in subdirectories without namespacing.
     def get_model_class(file)
-      require File.expand_path("#{model_dir}/#{file}") # this is for non-rails projects, which don't get Rails auto-require magic
-      model = ActiveSupport::Inflector.camelize(file.gsub(/\.rb$/, ''))
-      parts = model.split('::')
-      begin
-        parts.inject(Object) {|klass, part| klass.const_get(part) }
-      rescue LoadError, NameError
-        begin
-          Object.const_get(parts.last)
-        rescue LoadError, NameError
-          Object.const_get(Module.constants.detect{|c|parts.last.downcase == c.downcase})
-        end
-      end
+      # this is for non-rails projects, which don't get Rails auto-require magic
+      require File.expand_path("#{model_dir}/#{file}")
+
+      model_path = file.gsub(/\.rb$/, '')
+      get_loaded_model(model_path) || get_loaded_model(model_path.split('/').last)
+    end
+
+    # Retrieve loaded model class by path to the file where it's supposed to be defined.
+    def get_loaded_model(model_path)
+      ObjectSpace.each_object.
+        select { |c| c.is_a?(Class) && c.ancestors.include?(ActiveRecord::Base) }.
+        detect { |c| ActiveSupport::Inflector.underscore(c) == model_path }
     end
 
     # We're passed a name of things that might be
@@ -258,7 +334,7 @@ module AnnotateModels
         end
       end
 
-      header = PREFIX.dup
+      header = options[:format_markdown] ? PREFIX_MD.dup : PREFIX.dup
 
       if options[:include_version]
         version = ActiveRecord::Migrator.current_version rescue 0
@@ -272,19 +348,17 @@ module AnnotateModels
       end
 
       annotated = []
-      get_model_files.each do |file|
+      get_model_files(options).each do |file|
         begin
           klass = get_model_class(file)
-          if klass < ActiveRecord::Base && !klass.abstract_class?
+          if klass && klass < ActiveRecord::Base && !klass.abstract_class?
             if annotate(klass, file, header, options)
               annotated << klass
             end
           end
         rescue Exception => e
-          puts "Unable to annotate #{file}: #{e.inspect}"
-          puts ""
-# todo: check if all backtrace lines are in "gems" -- if so, it's an annotate bug, so print the whole stack trace.
-#          puts e.backtrace.join("\n\t")  
+          # todo: check if all backtrace lines are in "gems" -- if so, it's an annotate bug, so print the whole stack trace.
+          puts "Unable to annotate #{file}: #{e.message} (#{e.backtrace.first})"
         end
       end
       if annotated.empty?
@@ -300,25 +374,33 @@ module AnnotateModels
         self.model_dir = options[:model_dir]
       end
       deannotated = []
-      get_model_files.each do |file|
+      get_model_files(options).each do |file|
         begin
           klass = get_model_class(file)
           if klass < ActiveRecord::Base && !klass.abstract_class?
             deannotated << klass
 
+            model_name = klass.name.underscore
             model_file_name = File.join(model_dir, file)
             remove_annotation_of_file(model_file_name)
 
-            FIXTURE_DIRS.each do |dir|
-              fixture_file_name = File.join(dir,klass.table_name + ".yml")
-              remove_annotation_of_file(fixture_file_name) if File.exist?(fixture_file_name)
-            end
-            
-            [ File.join(UNIT_TEST_DIR, "#{klass.name.underscore}_test.rb"),
-              File.join(SPEC_MODEL_DIR,"#{klass.name.underscore}_spec.rb")].each do |file|
+            [
+             File.join(UNIT_TEST_DIR,          "#{model_name}_test.rb"),
+             File.join(SPEC_MODEL_DIR,         "#{model_name}_spec.rb"),
+             File.join(FIXTURE_TEST_DIR,       "#{klass.table_name}.yml"),     # fixture
+             File.join(FIXTURE_SPEC_DIR,       "#{klass.table_name}.yml"),     # fixture
+             File.join(EXEMPLARS_TEST_DIR,     "#{model_name}_exemplar.rb"),   # Object Daddy
+             File.join(EXEMPLARS_SPEC_DIR,     "#{model_name}_exemplar.rb"),   # Object Daddy
+             File.join(BLUEPRINTS_TEST_DIR,    "#{model_name}_blueprint.rb"),  # Machinist Blueprints
+             File.join(BLUEPRINTS_SPEC_DIR,    "#{model_name}_blueprint.rb"),  # Machinist Blueprints
+             File.join(FACTORY_GIRL_TEST_DIR,  "#{model_name}_factory.rb"),    # Factory Girl Factories
+             File.join(FACTORY_GIRL_SPEC_DIR,  "#{model_name}_factory.rb"),    # Factory Girl Factories
+             File.join(FABRICATORS_TEST_DIR,   "#{model_name}_fabricator.rb"), # Fabrication Fabricators
+             File.join(FABRICATORS_SPEC_DIR,   "#{model_name}_fabricator.rb"), # Fabrication Fabricators
+            ].each do |file|
               remove_annotation_of_file(file) if File.exist?(file)
             end
-            
+
           end
         rescue Exception => e
           puts "Unable to annotate #{file}: #{e.message}"
@@ -326,15 +408,9 @@ module AnnotateModels
       end
       puts "Removed annotation from: #{deannotated.join(', ')}"
     end
-  end
-end
-
-# monkey patches
 
-module ::ActiveRecord
-  class Base
-    def self.method_missing(name, *args)
-      # ignore this, so unknown/unloaded macros won't cause parsing to fail
+    def find_test_file(dir, file_name)
+      Dir.glob(File.join(dir, "**", file_name)).first || File.join(dir, file_name)
     end
   end
 end