ahnnotate 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8c69ae3868972bae9fd2390bf305aba574c1a9522049ed1ce203b25b8423b9cb
+  data.tar.gz: dd3d1e477e1351de18d99f54d1471ac1fc03c5a815a4eee0c78d104c3486aacd
+SHA512:
+  metadata.gz: 6469c1d8fe2603f98757c149aa0d7e16e3a9460d635c8395a8a548268b743ae2c16bd3a958f34acf9f19cc4dd072c579bcae34f207953977d59483bd207fc9ff
+  data.tar.gz: f2b2e026256a531b29eb2d3dc6d9b8950fa1ef90303b923bacdaa4f0e21d1d7d471d73e2be072058b5530a9e06e9c5bb8a0e62e574c45db2f46dfaa0e3260231

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.5.3
+before_install: gem install bundler -v 1.17.1

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in ahnnotate.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,55 @@
+PATH
+  remote: .
+  specs:
+    ahnnotate (0.2.0)
+      activerecord (>= 4.0.0, < 6)
+      parser
+      proc_party
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (5.2.1.1)
+      activesupport (= 5.2.1.1)
+    activerecord (5.2.1.1)
+      activemodel (= 5.2.1.1)
+      activesupport (= 5.2.1.1)
+      arel (>= 9.0)
+    activesupport (5.2.1.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    arel (9.0.0)
+    ast (2.4.0)
+    coderay (1.1.2)
+    concurrent-ruby (1.1.3)
+    i18n (1.1.1)
+      concurrent-ruby (~> 1.0)
+    method_source (0.9.2)
+    minitest (5.11.3)
+    parser (2.5.3.0)
+      ast (~> 2.4.0)
+    proc_party (0.2.0)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    rake (10.5.0)
+    sqlite3 (1.3.13)
+    thread_safe (0.3.6)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.17)
+  ahnnotate!
+  minitest (~> 5.0)
+  pry
+  rake (~> 10.0)
+  sqlite3
+
+BUNDLED WITH
+   1.17.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Zach Ahn
+
+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,118 @@
+# Ahnnotate
+
+Ahnnotate comments on your ActiveRecord models with their respective schemas!
+
+Ahnnotate performs static analysis on your files to determine which files
+should be annotated. The primary goals of ahnnotate are ease of configuration
+and correctness.
+
+It's very similar to [annotate][annotate] and was inspired heavily by it.
+Annotate has more features than ahnnotate does; it may fit your needs much
+better.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "ahnnotate"
+```
+
+And then execute:
+
+```
+bundle
+```
+
+
+## Usage
+
+Please use source control management software like git, mercurial, etc! The
+purpose of this software is to overwrite your source files. Although I'm pretty
+comfortable running this in my own projects, I've definitely made a couple bugs
+in my lifetime!
+
+
+### In a Rails app
+
+To run it manually, run:
+
+```bash
+bundle exec ahnnotate --fix
+# OR
+bundle exec rake ahnnotate
+```
+
+(Leaving out the `--fix` argument runs the command but doesn't make any changes
+to your filesystem. The rake task assumes that you do want to fix by default.)
+
+Ahnnotate automatically runs after running migrations. This can be disabled,
+though by creating a `.ahnnotate.yml` configuration file and setting
+`rake_db_autorun: false`.
+
+See `bundle exec ahnnotate --help` for some more help.
+
+
+### In apps using ActiveRecord but not Rails
+
+You'll need some initial configuration to get things working. But I'm sure
+you're used to that since you aren't using Rails! 😝
+
+You'll need a `.ahnnotate.yml` file at the root of your project with one key,
+`boot:`. Ahnnotate will `eval` the contents, and it really just needs it to
+connect to your database. It might look something like the following, I tested
+it with one of my Rails apps:
+
+```yaml
+---
+boot: |
+  require "dotenv/load" # If you use something like dotenv to load ENV variables
+  require "yaml"
+  require "erb"
+  require "active_record"
+
+  config_file = File.read("config/database.yml")
+  config_file = ERB.new(config_file).result(binding)
+  config = YAML.load(config_file)
+
+  environment = ENV.fetch("RAILS_ENV", "development")
+  database_config = config[environment]
+
+  ActiveRecord::Base.establish_connection(database_config)
+```
+
+You may also need to configure the location of your models.
+
+```yaml
+annotate:
+  models:
+    path: path/to/your/models # also accepts an array of paths
+```
+
+It doesn't officially support automatically running after migrations on
+non-Rails apps.
+
+See `bundle exec ahnnotate --help` for some more help.
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake test` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on its [project page][github].
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License][mit].
+
+
+[annotate]: https://github.com/ctran/annotate_models
+[github]: https://github.com/zachahn/ahnnotate
+[mit]: https://opensource.org/licenses/MIT

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/ahnnotate.gemspec

@@ -0,0 +1,33 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "ahnnotate/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ahnnotate"
+  spec.version = Ahnnotate::VERSION
+  spec.authors = ["Zach Ahn"]
+  spec.email = ["engineering@zachahn.com"]
+
+  spec.summary = %("Annotate" your models)
+  spec.description = %(Heavily inspired by the `annotate` gem)
+  spec.license = "MIT"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.17"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "pry"
+
+  spec.add_runtime_dependency "activerecord", ">= 4.0.0", "< 6"
+  spec.add_runtime_dependency "parser"
+  spec.add_runtime_dependency "proc_party"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "ahnnotate"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/rake

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/ahnnotate

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+if File.exist?(File.expand_path("../.git", __dir__))
+  lib = File.expand_path("../lib", __dir__)
+
+  if !$LOAD_PATH.include?(lib)
+    $LOAD_PATH.unshift(lib)
+  end
+end
+
+require "ahnnotate"
+require "ahnnotate/cli"
+
+Ahnnotate::Cli.new(name: File.basename(__FILE__)).run(ARGV)

data/lib/ahnnotate/cli.rb

@@ -0,0 +1,116 @@
+require "optparse"
+require "rubygems/text"
+
+module Ahnnotate
+  class Cli
+    def initialize(name:)
+      @name = name
+      @options = Options.new(fix: false)
+    end
+
+    def run(argv, config = nil)
+      argv = argv.dup
+
+      debug_options = argv.delete("--debug-opts") || argv.delete("--debug-options")
+
+      parser.parse(argv)
+
+      if debug_options
+        puts @options
+      end
+
+      if @options.exit?
+        return
+      end
+
+      root = Pathname.new(Dir.pwd)
+      config ||= Config.load(root: root)
+
+      Function::Main.new(root, @options, config).call
+    end
+
+    private
+
+    def parser
+      if instance_variable_defined?(:@parser)
+        return @parser
+      end
+
+      @parser = OptionParser.new do |opts|
+        opts.banner = "Usage: #{@name} [options]"
+        opts.separator ""
+        opts.separator "Command line options:"
+        opts.separator ""
+
+        opts.on("--[no-]fix", "Actually modify files") do |fix|
+          @options.fix = fix
+        end
+
+        opts.on("-h", "--help", "Prints this help message") do
+          @options.exit = true
+          puts opts
+        end
+
+        opts.on("--version", "Print version") do
+          @options.exit = true
+          puts Ahnnotate::VERSION
+        end
+
+        opts.separator ""
+        opts.separator ""
+        opts.separator "Configuration file:"
+        opts.separator ""
+
+        # The gsub converts all non-consecutive newlines into a space.
+        # Consecutive newlines are left alone.
+        configuration_file_help = <<-MSG.gsub(/(?<!\n)\n(?!\n)/, " ")
+The configuration file (`.ahnnotate.yml`) must be placed at the root of your
+project, or wherever you will be calling this script. Any unset config option
+will fall back to the following default configuration:
+
+%{default}
+
+In Rails projects (projects which explicitly use the `Rails` gem), ahnnotate
+merges the following configs in with the defaults. This should allow ahnnotate
+to work out of the box.
+
+%{rails_additions}
+
+(It should generally be possible to speed up the "boot" process by only loading
+ActiveRecord, custom inflections, etc. Note though that the actual models do
+not need to be loaded into the runtime; ahnnotate will read them as needed)
+        MSG
+
+        output = format(
+          configuration_file_help,
+          default: yaml_dump_and_indent(Ahnnotate::Config.default, indent: 4),
+          rails_additions: yaml_dump_and_indent(Ahnnotate::Config.rails_additions, indent: 4)
+        )
+
+        opts.separator wrap_and_indent(text: output, width: 72 + 4, indent: 4)
+      end
+
+      @parser
+    end
+
+    def yaml_dump_and_indent(object, indent:)
+      YAML.dump(object).gsub(/^/, " " * indent)
+    end
+
+    def wrap_and_indent(text:, width:, indent:)
+      GemTextWrapper.format_text(text, width, indent)
+    end
+  end
+
+  # I really had a feeling Ruby would have a "word wrap" feature somewhere.
+  # Somewhere in the Rubygems code was not my first guess lol.
+  module GemTextWrapper
+    class << self
+      include Gem::Text
+
+      def clean_text(text)
+        text
+      end
+    end
+  end
+end

data/lib/ahnnotate/column.rb

@@ -0,0 +1,60 @@
+module Ahnnotate
+  class Column
+    attr_reader :name
+    attr_reader :type
+
+    def initialize(name:, type:, nullable:, primary_key:, default:)
+      @name = name
+      @type = type
+      @nullable = nullable
+      @primary_key = primary_key
+      @default = default
+    end
+
+    def details
+      if @details
+        return @details
+      end
+
+      details = []
+
+      if !nullable?
+        details.push("not null")
+      end
+
+      if has_default?
+        details.push("default (#{default.inspect})")
+      end
+
+      if primary_key?
+        details.push("primary key")
+      end
+
+      @details = details.join(", ")
+    end
+
+    def default
+      if @default.nil?
+        return nil
+      end
+
+      if type == "boolean"
+        return !ActiveModel::Type::Boolean::FALSE_VALUES.include?(@default)
+      end
+
+      @default
+    end
+
+    def has_default?
+      !default.nil?
+    end
+
+    def nullable?
+      !!@nullable
+    end
+
+    def primary_key?
+      !!@primary_key
+    end
+  end
+end

data/lib/ahnnotate/config.rb

@@ -0,0 +1,67 @@
+module Ahnnotate
+  class Config
+    def self.load(root:)
+      config_path = root.join(".ahnnotate.yml")
+
+      if !config_path.exist?
+        return new({})
+      end
+
+      loaded_config = YAML.safe_load(File.read(config_path))
+      new(loaded_config)
+    end
+
+    def self.default
+      @default ||= {
+        "boot" => nil,
+        "rake_db_autorun" => false,
+        "annotate" => {
+          "models" => {
+            "enabled" => true,
+            "path" => "app/models",
+          },
+        },
+      }
+    end
+
+    def self.rails_additions
+      @rails_additions ||= {
+        "boot" => %(require File.expand_path("config/environment").to_s),
+        "rake_db_autorun" => true,
+      }
+    end
+
+    def self.effective_default
+      if @effective_default
+        return @effective_default
+      end
+
+      @effective_default ||= YAML.load(YAML.dump(default)) # deep dup
+
+      if Gem.loaded_specs.key?("rails")
+        @effective_default.merge!(rails_additions)
+      end
+
+      @effective_default
+    end
+
+    def initialize(config)
+      @config =
+        if config.is_a?(Hash)
+          config
+        else
+          {}
+        end
+    end
+
+    def [](*args)
+      specified_config = @config.dig(*args)
+
+      if specified_config.nil?
+        self.class.effective_default.dig(*args)
+      else
+        specified_config
+      end
+    end
+  end
+end

data/lib/ahnnotate/error.rb

@@ -0,0 +1,8 @@
+module Ahnnotate
+  class Error < StandardError
+    class VfsError < Error; end
+    class VfsReadError < VfsError; end
+    class VfsWriteError < VfsError; end
+    class VfsOutsideOfRoot < VfsError; end
+  end
+end

data/lib/ahnnotate/facet/models/main.rb

@@ -0,0 +1,49 @@
+module Ahnnotate
+  module Facet
+    module Models
+      class Main
+        def initialize(config, tables, vfs)
+          @config = config
+          @tables = tables
+          @vfs = vfs
+        end
+
+        def call
+          formatter = Function::Format.new(comment: "#")
+
+          model_nodes.each do |model_node|
+            table = @tables[model_node.table_name]
+
+            if table.nil?
+              next
+            end
+
+            @vfs[model_node.path] =
+              formatter.call(table, @vfs[model_node.path])
+          end
+        end
+
+        def model_nodes
+          @model_nodes ||=
+            begin
+              model_path = @config["annotate", "models", "path"]
+              model_files = @vfs.each_in(model_path)
+              processor = Processor.new
+              models = model_files.map do |path, contents|
+                module_nodes = processor.call(contents)
+                module_nodes.each { |node| node.path = path }
+                module_nodes
+              end
+
+              models
+                .flatten
+                .yield_self(&ResolveClassRelationships.new)
+                .yield_self(&ResolveActiveRecordModels.new)
+                .select(&:is_a_kind_of_activerecord_base?)
+                .reject(&:abstract_class?)
+            end
+        end
+      end
+    end
+  end
+end