annotated-rails 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.rvmrc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3

data/.yardopts

@@ -0,0 +1 @@
+--no-private --files CHANGELOG.md

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+TODO
+----
+
+* rake task(rake annotate)
+* add exception handling for "bad" models:
+
+      Annotaiting GoodModel BadModel(failed)
+      BadModel exception:
+      bla/bla/bla
+      bla
+
+current(master)
+---------------
+
+nothing here yet
+
+0.0.1
+-----
+
+what in the box:
+
+* annotation for table and indexes
+* binary file with annotation/denotation ability
+* abstract class ignoring
+* NO trailing characters

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in annotate-rails.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 kucaahbe
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,85 @@
+# annotated-rails [![Build Status](http://travis-ci.org/kucaahbe/annotated-rails.png)](http://travis-ci.org/kucaahbe/annotated-rails)
+
+Provides schema annotation for your models.
+
+Like this:
+
+```ruby
+class Post < ActiveRecord::Base
+  ...
+end
+#--
+# generated by 'annotated-rails' gem, please do not remove this line and content below, instead use `bundle exec annotate-rails -d` command
+#++
+# Table name: posts
+#
+# * id             :integer         not null
+#   title          :string(30)
+#   content        :text
+#   slug           :string(255)     not null
+#   author_name    :string(255)
+#   comments_count :integer         default 0
+#   created_at     :datetime        not null
+#   updated_at     :datetime        not null
+#
+#  Indexes:
+#   index_posts_on_slug  slug
+#--
+# generated by 'annotated-rails' gem, please do not remove this line and content above, instead use `bundle exec annotate-rails -d` command
+#++
+```
+
+Inspired by [ctran/annotate_models](http://github.com/ctran/annotate_models)
+
+For using with <strong>3.x rails</strong>, do not tested against earlier versions.
+
+## Installation
+
+Add this line to your rails Gemfile:
+
+    group :development do
+      gem 'annotated-rails'
+    end
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install annotated-rails
+
+## Usage
+
+To annotate:
+
+    bundle exec annotate-rails
+
+To remove annotation:
+
+    bundle exec annotate-rails -d
+
+To see CLI help:
+
+    bundle exec annotate-rails -h|--help
+
+## Future plans
+
+* look at the CHANGELOG for what is going to be done
+* add guard/something similar support
+* add annotations for other things
+
+## Testing
+
+* clone
+* bundle
+* rake
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Add tests for your changes
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request

data/Rakefile

@@ -0,0 +1,25 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+task :default => :spec
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts='--tag ~wip'
+end
+
+namespace :spec do
+  RSpec::Core::RakeTask.new(:wip) do |t|
+    t.rspec_opts='--tag wip'
+    t.fail_on_error = false
+  end
+
+  RSpec::Core::RakeTask.new(:rcov) do |t|
+    t.rspec_opts=['-r simplecov']
+  end
+end
+
+desc "Validate the gemspec"
+task :gemspec do
+  eval(File.read(Dir["*.gemspec"].first)).validate && puts('gemspec valid')
+end

data/annotated-rails.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/annotated/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["kucaahbe"]
+  gem.email         = ["kucaahbe@ukr.net"]
+  gem.description   = %q{Y.a. Rails models annotation}
+  gem.summary       = gem.description+%q{inspired by annotate_models gem}
+  gem.homepage      = "http://github.com/kucaahbe/annotated-rails"
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "annotated-rails"
+  gem.require_paths = ["lib"]
+  gem.bindir        = 'bin'
+  gem.executables   << 'annotate-rails'
+  gem.version       = Annotated::VERSION
+
+  gem.add_runtime_dependency 'activerecord', '>= 3.0.0'
+
+  gem.add_development_dependency 'rspec', '~> 2.8.0'
+  gem.add_development_dependency 'rspec-rails', '~> 2.8.0'
+  gem.add_development_dependency 'rails', '~> 3.2.0'
+  gem.add_development_dependency 'sqlite3'
+  gem.add_development_dependency 'yard'
+  gem.add_development_dependency 'bluecloth'
+end

data/bin/annotate-rails

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: annotate-rails [options]"
+
+  opts.separator ""
+
+  opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
+    options[:verbose] = v
+  end
+
+  opts.on("-d", "--delete", "Delete annotations") do |d|
+    options[:delete] = d
+  end
+end.parse!
+
+ENV['ANN_CLI']='true'
+print 'Loading rails environment: '
+require './config/environment'
+puts 'done.'
+require 'annotated/models'
+
+if options.delete(:delete)
+  Annotated::Models.instance.denotate!
+else
+  Annotated::Models.instance.annotate!(options)
+end

data/lib/annotated/models.rb

@@ -0,0 +1,187 @@
+require 'singleton'
+
+# {include:file:README.md}
+module Annotated
+
+  # @private
+  module Helpers
+
+    private
+
+    def puts_message msg
+      puts msg if ENV['ANN_CLI']
+    end
+
+    def print_message msg
+      print msg if ENV['ANN_CLI']
+    end
+
+    protected
+
+    def debug?
+      @debug ||= ENV.has_key?('ANN_DEBUG')
+    end
+
+  end
+
+  class Models
+
+    # @private
+    class Annotator
+
+      include Helpers
+
+      def initialize model_const, model_file_full_path
+        @model, @path = model_const, model_file_full_path
+        @annotatable = true
+      end
+
+      attr_reader :path, :model
+
+      def annotatable? # I'm not sure is this a right word...
+        make_annotation!
+        @annotatable
+      end
+
+      def annotation
+        make_annotation!
+      end
+
+      def add_regexp
+        /\z/
+      end
+
+      def remove_regexp
+        border = '# '+STRONG_ANNOTATION
+        border.gsub!(' ', '\s')
+        border.gsub!('#', '\#')
+        %r{\n(\#--\n)?#{border}.+#{border}.*\n?(\#++)?}m
+      end
+
+      private
+
+      def make_annotation!
+        return @annotatable=false if @model.abstract_class?
+        return @annotation if defined?(@annotation)
+
+        # TODO add exception handling inside this method to notify about broken models
+        table_name = @model.table_name.to_s
+        annotation_header = <<annheader
+#--
+# #{ANNOTATION % 'below'}
+#++
+annheader
+        annotation_footer = <<annfooter
+
+#--
+# #{ANNOTATION % 'above'}
+#++
+annfooter
+        annotation_table = []
+
+        # append table name:
+        annotation_table << "# Table name: #{table_name}"
+        annotation_table << '#'
+        column_with_maximum_name_length = @model.columns.map(&:name).max_by { |c| c.length }.length
+
+        @model.columns.each do |column|
+          column_limit = if column.type==:decimal && column.precision
+                           "(#{[column.precision, column.scale].join(',')})"
+                         else
+                           column.limit ? "(#{column.limit})" : ''
+                         end
+
+          other_column_attrs = []
+          other_column_attrs << NOT_NULL unless column.null
+          other_column_attrs << DEFAULT % column.default if column.default
+
+          annotation_table << sprintf(
+            %Q|# %s %-#{column_with_maximum_name_length+1}s:%-16s%s|,
+            column.primary && PRIMARY_KEY_MARK || ' ',
+            column.name,
+            column.type.to_s+column_limit,
+            other_column_attrs.join(',')
+          ).rstrip
+        end
+
+        # annotating indexes if present
+        annotation_index = []
+        if (indexes = ActiveRecord::Base.connection.indexes(table_name)) and not indexes.empty?
+          annotation_index << "\n#"
+          annotation_index << "#  Indexes:"
+          maximum_index_name_length = indexes.map(&:name).max_by { |c| c.length }.length
+          indexes.each do |index|
+            # todo add other index fields
+            annotation_index << sprintf(
+              "#   %-#{maximum_index_name_length}s  %s  %s",
+              index.name,
+              index.columns.join(','),
+              index.unique ? 'unique' : ''
+            ).rstrip
+          end
+        end
+
+        @annotation = annotation_header + annotation_table.join("\n") + annotation_index.join("\n") + annotation_footer
+      end
+
+    end # Annotator
+
+    include Singleton
+    include Helpers
+
+    STRONG_ANNOTATION = %q|generated by 'annotated-rails' gem|
+    ANNOTATION        = %Q|#{STRONG_ANNOTATION}, please do not remove this line and content %s, instead use `bundle exec annotate-rails -d` command|
+    NOT_NULL          = 'not null'
+    PRIMARY_KEY_MARK  = '*'
+    DEFAULT           = 'default %s'
+
+    def annotate! options = {}
+      print_message "Annotating: "
+
+      annotators.each do |annotator|
+        next unless annotator.annotatable?
+
+        print_message annotator.model.to_s+' '
+
+        content = File.read(annotator.path).gsub(annotator.remove_regexp, "\n")
+        content.gsub!(annotator.add_regexp, annotator.annotation)
+
+        write_file annotator.path, content
+      end
+
+      puts_message "\n"
+    end
+
+    def denotate!
+      annotators.each do |annotator|
+        content = File.read(annotator.path).gsub(annotator.remove_regexp, "\n")
+        write_file annotator.path, content
+      end
+    end
+
+    private
+
+    def annotators
+      return @annotators if defined?(@annotators)
+      @annotators = []
+
+      begin
+        Dir[::Rails.root.join('app/models/','**/*.rb').to_s].each do |module_path|
+          require module_path
+          @annotators << Annotator.new(ActiveRecord::Base.descendants.last,module_path) # "last".method here, todo a better way for constants and file path's handling
+        end
+      rescue Exception => e
+        #puts e.inspect if debug?
+      end
+
+      @annotators # make sure we return annotators
+    end
+
+    protected
+
+    def write_file destination, content
+      File.open(destination, 'wb') { |file| file.write(content) }
+    end
+
+  end
+end

data/lib/annotated/version.rb

@@ -0,0 +1,3 @@
+module Annotated
+  VERSION = "0.0.1"
+end

data/lib/annotated-rails.rb

@@ -0,0 +1,2 @@
+# I have nothing to load here,
+# it's for bundler, maybe...

data/spec/annotated/models/annotator_spec.rb

@@ -0,0 +1,46 @@
+require 'spec_helper'
+require 'annotated/models'
+
+describe Annotated::Models::Annotator do
+
+  context "#path" do
+    it "should return file path" do
+      described_class.new(Post,'/path/to/post').path.should eq('/path/to/post')
+    end
+  end
+
+  context "#annotation" do
+
+    it "should return annotation for Post" do
+      described_class.new(Post,'/path/to/post').annotation.should eq(<<-ANNOTATION)
+#--
+# generated by 'annotated-rails' gem, please do not remove this line and content below, instead use `bundle exec annotate-rails -d` command
+#++
+# Table name: posts
+#
+# * id                                         :integer         not null
+#   title                                      :string(255)
+#   content                                    :text
+#   some_long_named_column_bla_bla_bla_bla_bla :text
+#   author_name                                :string(10)      not null
+#   comments_count                             :integer         not null,default 0
+#   null_true                                  :string(255)
+#   null_true_with_default                     :string(255)     default bla
+#   decimal_column                             :decimal
+#   decimal_column_with_precision              :integer(23)
+#   decimal_column_with_precision_and_scale    :decimal(23,5)
+#   decimal_column_with_scale                  :decimal
+#   created_at                                 :datetime        not null
+#   updated_at                                 :datetime        not null
+#
+#  Indexes:
+#   index_posts_on_author_name  author_name
+#--
+# generated by 'annotated-rails' gem, please do not remove this line and content above, instead use `bundle exec annotate-rails -d` command
+#++
+ANNOTATION
+    end
+
+  end
+
+end

data/spec/annotated/models_spec.rb

@@ -0,0 +1,184 @@
+require 'spec_helper'
+require 'annotated/models'
+
+describe Annotated::Models do
+
+  subject { Annotated::Models.instance }
+
+  let(:annotator) { Annotated::Models::Annotator }
+
+  before :all do
+    User   = Class.new
+    Avatar = Class.new
+  end
+
+  before :each do
+    StubFile.clear!
+  end
+
+  context "#annotate!" do
+
+    it "must annotate all models" do
+      annotator.any_instance.stub(:make_annotation!)
+
+      subject.should_receive(:annotators).
+        and_return(
+          annotators=[annotator.new(User,'path1'),annotator.new(Avatar,'path2')]
+      )
+      annotators.each { |a| a.should_receive(:annotation).and_return('String') }
+
+      File.should_receive(:read).with('path1').and_return((user_file=StubFile.new(<<-USER,'path1')).content)
+class User < ActiveRecord::Base
+end
+USER
+      File.should_receive(:read).with('path2').and_return((avatar_file=StubFile.new(<<-AVATAR,'path2')).content)
+class Avatar < ActiveRecord::Base
+end
+AVATAR
+      File.stub(:open) do |path,mode,block|
+        StubFile.open path, mode, &block
+      end
+
+      subject.annotate!
+
+      user_file.content.should eq((<<-TEXT).chomp)
+class User < ActiveRecord::Base
+end
+String
+TEXT
+      avatar_file.content.should eq((<<-TEXT).chomp)
+class Avatar < ActiveRecord::Base
+end
+String
+TEXT
+    end
+
+    it "must not annotate abstract AR classes" do
+      SomeBase = Class.new
+
+      SomeBase.should_receive(:abstract_class?) { true }
+
+      subject.should_receive(:annotators).and_return(annotators=[annotator.new(SomeBase,'some_base_model_path')])
+
+      File.should_not_receive(:read).with('some_base_model_path')
+
+      subject.annotate!
+    end
+
+    it "must annotate file using one write operation" do
+      LalaClass = Class.new
+      annotator.any_instance.stub(:make_annotation!)
+
+      subject.should_receive(:annotators).
+        and_return(
+          annotators=[annotator.new(LalaClass,'lala_path')]
+      )
+      annotators.each { |a| a.should_receive(:annotation).and_return('String') }
+
+      File.should_receive(:read).with('lala_path').once.and_return('file_content')
+      File.should_receive(:open).with('lala_path','wb').once
+
+      subject.annotate!
+    end
+
+    it "must be able to renotate" do
+      annotator.any_instance.stub(:make_annotation!)
+
+      subject.should_receive(:annotators).
+        and_return(
+          annotators=[annotator.new(User,'path1'),annotator.new(Avatar,'path2')]
+      )
+      annotators.each { |a| a.should_receive(:annotation).and_return('NewAnnotation') }
+
+      File.should_receive(:read).with('path1').and_return((user_file=StubFile.new(<<-USER,'path1')).content)
+class User < ActiveRecord::Base
+end
+#--
+# generated by 'annotated-rails' gem dfg dfg 
+#++
+#old 
+# annotation
+#  text
+#--
+# generated by 'annotated-rails' gem dfg dfg 
+#++
+USER
+      File.should_receive(:read).with('path2').and_return((avatar_file=StubFile.new(<<-AVATAR,'path2')).content)
+class Avatar < ActiveRecord::Base
+end
+#--
+# generated by 'annotated-rails' gem dfg dfg 
+#++
+# another old 
+# annotation asd
+#  text lolo
+#--
+# generated by 'annotated-rails' gem dfg dfg 
+#++
+AVATAR
+      File.stub(:open) do |path,mode,block|
+        StubFile.open path, mode, &block
+      end
+
+      subject.annotate!
+
+      user_file.content.should eq((<<-TEXT).chomp)
+class User < ActiveRecord::Base
+end
+NewAnnotation
+TEXT
+      avatar_file.content.should eq((<<-TEXT).chomp)
+class Avatar < ActiveRecord::Base
+end
+NewAnnotation
+TEXT
+    end
+
+  end
+
+  context "#denotate!" do
+
+    it "must denotate all models" do
+      subject.should_receive(:annotators).and_return(annotators=[annotator.new(User,'path1'),annotator.new(Avatar,'path2')])
+
+      File.should_receive(:read).with('path1').and_return((user_file=StubFile.new(<<-USER,'path1')).content)
+class User < ActiveRecord::Base
+end
+# generated by 'annotated-rails' gem asdasd
+# blabla
+# generated
+#text
+# generated by 'annotated-rails' gem gdfgdfgdfg
+USER
+      File.should_receive(:read).with('path2').and_return((avatar_file=StubFile.new(<<-AVATAR,'path2')).content)
+class Avatar < ActiveRecord::Base
+end
+#--
+# generated by 'annotated-rails' gem dfg dfg 
+#++
+# blabla
+# generated
+#text
+#--
+# generated by 'annotated-rails' gem dfg dfg 
+#++
+AVATAR
+      File.stub(:open) do |path,mode,block|
+        StubFile.open path, mode, &block
+      end
+
+      subject.denotate!
+
+      user_file.content.should eq((<<-TEXT))
+class User < ActiveRecord::Base
+end
+TEXT
+      avatar_file.content.should eq(z=(<<-TEXT))
+class Avatar < ActiveRecord::Base
+end
+TEXT
+    end
+
+  end
+
+end

data/spec/dummy/.gitignore

@@ -0,0 +1,3 @@
+db/*.sqlite3
+log
+test

data/spec/dummy/README.rdoc

@@ -0,0 +1 @@
+This is a dummy rails application for testing purposes