chusaku 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf3fc6d454cdeaf9c8c31019c1b0ec6dc4c676203a8c44cd40e24dee49ace832
-  data.tar.gz: ba06bb7b2868c6c2d53ac93504eb00fe0ef5527b1224f04c6c862fd27e7734fe
+  metadata.gz: 006eca0c4d1c3b87363edd35f9070dd48bc0693e1b56b01fd3900696fa50387d
+  data.tar.gz: d5d3816c84eaba7c36d4e06e30eb7b8783b1dbb69f3c42190a278bf82fd01619
 SHA512:
-  metadata.gz: b932a1b72743a06701d7fa3d7a80068baf0e31df76d78a0dea7b892a46bb663c3dcd9e444599b3942a9a5eb3289b5b90b962ef39216e8f15ff04bde5bff0946b
-  data.tar.gz: c609bb26e27dc4018766e84d55aa38715385bff1fc444468481ff781649f9af3037e2078ada729814f9d92963e9b3752f48b1bb6cbdbe05a00000eae5ea169b4
+  metadata.gz: b103a27205545c18aba9e7570e0f0c63aafa558b0cb6b870520e8a25d60cbb73cdfceccc7937c09c3de5090cc304b08c1151a29ba16602802b0fdf685f8fe360
+  data.tar.gz: ff6eb6258eea5a27f0422d633975251827c114af744f229ab3f4eca101a6ce840b39c4bf47300f16813944b055502f78d1a88d89725d827edf90649003b43b22

data/.rubocop.yml

@@ -7,6 +7,9 @@ AllCops:
     - 'test/mock/app/**/*'
     - 'test/mock/examples/**/*'
 
+Layout/LineLength:
+  Max: 120
+
 Metrics/AbcSize:
   Exclude:
     - 'test/**/*'
@@ -16,6 +19,9 @@ Metrics/MethodLength:
   Exclude:
     - 'test/**/*'
 
+Metrics/ModuleLength:
+  Max: 250
+
 Style/ClassAndModuleChildren:
   Exclude:
     - 'test/**/*'

data/chusaku.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.name = 'chusaku'
   spec.version = Chusaku::VERSION
   spec.authors = ['Nishiki Liu']
-  spec.email = ['nishiki.liu@gmail.com']
+  spec.email = ['nishiki@hey.com']
 
   spec.summary = 'Annotate your Rails controllers with route info.'
   spec.description = 'Annotate your Rails controllers with route info.'
@@ -37,15 +37,15 @@ Gem::Specification.new do |spec|
       f.match(%r{^(test|spec|features)/})
     end
   end
-  spec.bindir        = 'bin'
-  spec.executables   = 'chusaku'
+  spec.bindir = 'bin'
+  spec.executables = 'chusaku'
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 2.0'
-  spec.add_development_dependency 'minitest', '~> 5.0'
-  spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'rubocop', '~> 0.77'
-  spec.add_development_dependency 'rubocop-performance', '~> 1.5'
+  spec.add_development_dependency 'bundler', '~> 2.2'
+  spec.add_development_dependency 'minitest', '~> 5.14'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rubocop', '~> 1.7'
+  spec.add_development_dependency 'rubocop-performance', '~> 1.9'
 
-  spec.add_dependency 'rails', '> 2.0'
+  spec.add_dependency 'railties', '>= 3.0'
 end

data/lib/chusaku.rb

@@ -15,8 +15,8 @@ module Chusaku
     #     # ...
     #   end
     #
-    # @param {Hash} flags - CLI flags
-    # @return {Integer} - 0 on success, 1 on error
+    # @param flags [Hash] CLI flags
+    # @return [Integer] 0 on success, 1 on error
     def call(flags = {})
       @flags = flags
       @routes = Chusaku::Routes.call
@@ -38,10 +38,10 @@ module Chusaku
 
     # Adds annotations to the given file.
     #
-    # @param {String} path - Path to file
-    # @param {String} controller - Controller name
-    # @param {Array<String>} actions - List of valid actions for the controller
-    # @return {void}
+    # @param path [String] Path to file
+    # @param controller [String] Controller name
+    # @param actions [Array<String>] List of valid actions for the controller
+    # @return [void]
     def annotate_file(path:, controller:, actions:)
       parsed_file = Chusaku::Parser.call(path: path, actions: actions)
       parsed_file[:groups].each_cons(2) do |prev, curr|
@@ -59,7 +59,7 @@ module Chusaku
 
     # Given a parsed group, clean out its contents.
     #
-    # @param {Hash} group - { type: Symbol, body: String }
+    # @param group [Hash] { type => Symbol, body => String }
     # @return {void}
     def clean_group(group)
       return unless group[:type] == :comment
@@ -74,52 +74,114 @@ module Chusaku
     #
     #   @route GET /waterlilies/:id (waterlilies)
     #
-    # @param {Hash} group - Parsed content given by Chusaku::Parser
-    # @param {Hash} route_data - Individual route data given by Chusaku::Routes
-    # @return {void}
+    # @param group [Hash] Parsed content given by Chusaku::Parser
+    # @param route_data [Hash] Individual route data given by Chusaku::Routes
+    # @return [void]
     def annotate_group(group:, route_data:)
       whitespace = /^(\s*).*$/.match(group[:body])[1]
       route_data.reverse_each do |datum|
-        name = datum[:name]
-        annotation = "@route #{datum[:verb]} #{datum[:path]}"
-        annotation += " (#{name})" unless name.nil?
-        comment = "#{whitespace}# #{annotation}\n"
+        comment = "#{whitespace}# #{annotate_route(**datum)}\n"
         group[:body] = comment + group[:body]
       end
     end
 
+    # Generate route annotation.
+    #
+    # @param verb [String] HTTP verb for route
+    # @param path [String] Rails path for route
+    # @param name [String] Name used in route helpers
+    # @param defaults [Hash] Default parameters for route
+    # @return [String] "@route <verb> <path> {<defaults>} (<name>)"
+    def annotate_route(verb:, path:, name:, defaults:)
+      annotation = "@route #{verb} #{path}"
+      if defaults&.any?
+        defaults_str =
+          defaults
+          .map { |key, value| "#{key}: #{value.inspect}" }
+          .join(', ')
+        annotation += " {#{defaults_str}}"
+      end
+      annotation += " (#{name})" unless name.nil?
+      annotation
+    end
+
     # Write annotated content to a file if it differs from the original.
     #
-    # @param {String} path - File path to write to
-    # @param {Hash} parsed_file - Hash mutated by `annotate_group`
-    # @return {void}
+    # @param path [String] File path to write to
+    # @param parsed_file [Hash] Hash mutated by {#annotate_group}
+    # @return [void]
     def write_to_file(path:, parsed_file:)
-      content = parsed_file[:groups].map { |pf| pf[:body] }.join
-      return unless parsed_file[:content] != content
-
-      unless @flags.include?(:dry)
-        File.open(path, 'r+') do |file|
-          if file.respond_to?(:test_write)
-            file.test_write(content, path)
-          else
-            file.write(content)
-          end
+      new_content = new_content_for(parsed_file)
+      return unless parsed_file[:content] != new_content
+
+      !@flags.include?(:dry) && perform_write(path: path, content: new_content)
+      @annotated_paths.push(path)
+    end
+
+    # Extracts the new file content for the given parsed file.
+    #
+    # @param parsed_file [Hash] { groups => Array<Hash> }
+    # @return [String] New file content
+    def new_content_for(parsed_file)
+      parsed_file[:groups].map { |pf| pf[:body] }.join
+    end
+
+    # Wraps the write operation. Needed to clearly distinguish whether it's a
+    # write in the test suite or a write in actual use.
+    #
+    # @param path [String] File path
+    # @param content [String] File content
+    # @return [void]
+    def perform_write(path:, content:)
+      File.open(path, file_mode) do |file|
+        if file.respond_to?(:test_write)
+          file.test_write(content, path)
+        else
+          file.write(content)
         end
       end
+    end
 
-      @annotated_paths.push(path)
+    # When running the test suite, we want to make sure we're not overwriting
+    # any files. `r` mode ensures that, and `w` is used for actual usage.
+    #
+    # @return [String] 'r' or 'w'
+    def file_mode
+      File.instance_methods.include?(:test_write) ? 'r' : 'w'
     end
 
     # Output results to user.
     #
-    # @return {Integer} - 0 for success, 1 for error
+    # @return [Integer] 0 for success, 1 for error
     def output_results
-      if @annotated_paths.any?
-        puts("Annotated #{@annotated_paths.join(', ')}")
-        @flags.include?(:error_on_annotation) ? 1 : 0
+      puts(output_copy)
+      exit_code = 0
+      exit_code = 1 if @annotated_paths.any? && @flags.include?(:error_on_annotation)
+      exit_code
+    end
+
+    # Determines the copy to be used in the program output.
+    #
+    # @return [String] Copy to be outputted to user
+    def output_copy
+      return 'Nothing to annotate.' if @annotated_paths.empty?
+
+      annotated_paths = @annotated_paths.join(', ')
+      dry_run = @flags.include?(:dry)
+      error_on_annotation = @flags.include?(:error_on_annotation)
+
+      if dry_run && error_on_annotation
+        <<~COPY
+          Annotations missing in the following files: #{annotated_paths}
+
+          Run `chusaku` to annotate them. Exiting with status code 1.
+        COPY
+      elsif dry_run
+        "The following files would be annotated without `--dry-run`: #{annotated_paths}"
+      elsif error_on_annotation
+        "Annotated #{annotated_paths}.\n\nExiting with status code 1."
       else
-        puts('Nothing to annotate')
-        0
+        "Annotated #{annotated_paths}."
       end
     end
   end

data/lib/chusaku/cli.rb

@@ -14,17 +14,17 @@ module Chusaku
     Finished = Class.new(RuntimeError)
     NotARailsProject = Class.new(RuntimeError)
 
-    # Initializes a new instance of Chusaku::CLI.
+    # Initializes a new instance of `Chusaku::CLI`.
     #
-    # @return {Chusaku::CLI} - Instance of this class
+    # @return [Chusaku::CLI] Instance of this class
     def initialize
       @options = {}
     end
 
     # Parse CLI flags, if any, and handle applicable behaviors.
     #
-    # @param {Array<String>} args - CLI arguments
-    # @return {Integer} - 0 on success, 1 on error
+    # @param args [Array<String>] CLI arguments
+    # @return [Integer] 0 on success, 1 on error
     def call(args = ARGV)
       optparser.parse!(args)
       check_for_rails_project
@@ -40,8 +40,8 @@ module Chusaku
 
     # Raises exception if Rails project cannot be detected.
     #
-    # @raise {Chusaku::CLI::NotARailsProject} - Exception if not Rails project
-    # @return {void}
+    # @raise [Chusaku::CLI::NotARailsProject] Exception if not Rails project
+    # @return [void]
     def check_for_rails_project
       has_controllers = File.directory?('./app/controllers')
       has_rakefile = File.exist?('./Rakefile')
@@ -50,7 +50,7 @@ module Chusaku
 
     # Returns an instance of OptionParser with supported flags.
     #
-    # @return {OptionParser} - Preconfigured OptionParser instance
+    # @return [OptionParser] Preconfigured OptionParser instance
     def optparser
       OptionParser.new do |opts|
         opts.banner = 'Usage: chusaku [options]'
@@ -63,8 +63,8 @@ module Chusaku
 
     # Adds `--exit-with-error-on-annotation` flag.
     #
-    # @param {OptionParser} opts - OptionParser instance
-    # @return {void}
+    # @param opts [OptionParser] OptionParser instance
+    # @return [void]
     def add_error_on_annotation_flag(opts)
       opts.on(
         '--exit-with-error-on-annotation',
@@ -76,8 +76,8 @@ module Chusaku
 
     # Adds `--dry-run` flag.
     #
-    # @param {OptionParser} opts - OptionParser instance
-    # @return {void}
+    # @param opts [OptionParser] OptionParser instance
+    # @return [void]
     def add_dry_run_flag(opts)
       opts.on(
         '--dry-run',
@@ -89,8 +89,8 @@ module Chusaku
 
     # Adds `--version` flag.
     #
-    # @param {OptionParser} opts - OptionParser instance
-    # @return {void}
+    # @param opts [OptionParser] OptionParser instance
+    # @return [void]
     def add_version_flag(opts)
       opts.on(
         '-v',
@@ -104,8 +104,8 @@ module Chusaku
 
     # Adds `--help` flag.
     #
-    # @param {OptionParser} opts - OptionParser instance
-    # @return {void}
+    # @param opts [OptionParser] OptionParser instance
+    # @return [void]
     def add_help_flag(opts)
       opts.on(
         '-h',

data/lib/chusaku/parser.rb

@@ -3,6 +3,8 @@
 module Chusaku
   # Handles parsing a file and groups its lines into categories.
   module Parser
+    # Primary method to call.
+    #
     # Example output:
     #
     #   {
@@ -31,9 +33,9 @@ module Chusaku
     #     ]
     #   }
     #
-    # @param {String} path - File path to parse
-    # @param {Array<String>} actions - List of valid actions for this route
-    # @return {Hash} - { content: String, groups: Array<Hash> }
+    # @param path [String] File path to parse
+    # @param actions [Array<String>] List of valid actions for this route
+    # @return [Hash] { content => String, groups => Array<Hash> }
     def self.call(path:, actions:)
       groups = []
       group = {}
@@ -58,20 +60,22 @@ module Chusaku
       { content: content, groups: groups }
     end
 
-    # Given a line and actions, returns the line's type:
+    # Given a line and actions, returns the line's type.
+    #
+    # A type can be one of:
     #
     #   1. comment - A line that is entirely commented. Lines that have trailing
     #                comments do not fall under this category.
     #   2. action  - A line that contains an action definition.
     #   3. code    - Anything else.
     #
-    # And give back a Hash in the form:
+    # Returns a Hash in the form:
     #
     #   { type: :action, body: 'def foo', action: 'foo' }
     #
-    # @param {String} line - A line of a file
-    # @param {Array<String>} actions - List of valid actions for this route
-    # @return {Hash} - { type: Symbol, body: String, action: String }
+    # @param line [String] A line of a file
+    # @param actions [Array<String>] List of valid actions for this route
+    # @return [Hash] { type => Symbol, body => String, action => String }
     def self.parse_line(line:, actions:)
       comment_match = /^\s*#.*$/.match(line)
       def_match = /^\s*def\s+(\w*)\s*\w*.*$/.match(line)

data/lib/chusaku/routes.rb

@@ -4,6 +4,8 @@ module Chusaku
   # Handles extracting information about the Rails project's routes.
   class Routes
     class << self
+      # Primary method to call.
+      #
       # Example output:
       #
       #   {
@@ -23,15 +25,21 @@ module Chusaku
       #     }
       #   }
       #
-      # @return {Hash} - Routes hash
+      # @return [Hash] Routes hash
       def call
         routes = {}
 
         Rails.application.routes.routes.each do |route|
-          controller, action = extract_controller_and_action_from(route)
+          controller, action, defaults = extract_data_from(route)
           routes[controller] ||= {}
           routes[controller][action] ||= []
-          routes[controller][action].push(format_route(route))
+
+          add_info_for \
+            route: route,
+            routes: routes,
+            controller: controller,
+            action: action,
+            defaults: defaults
         end
 
         backfill_routes(routes)
@@ -39,23 +47,56 @@ module Chusaku
 
       private
 
-      # Extract information of a given route.
+      # Adds formatted route info for the given param combination.
+      #
+      # @param route [Hash] Route info
+      # @param routes [Hash] Collection of all route info
+      # @param controller [String] Controller key
+      # @param action [String] Action key
+      # @param defaults [Hash] Default parameters for route
+      # @return [void]
+      def add_info_for(route:, routes:, controller:, action:, defaults:)
+        verbs_for(route).each do |verb|
+          routes[controller][action]
+            .push(format(route: route, verb: verb, defaults: defaults))
+          routes[controller][action].uniq!
+        end
+      end
+
+      # Extract the HTTP verbs for a Rails route. Required for older versions of
+      # Rails that return regular expressions for a route verb which sometimes
+      # contains multiple verbs.
+      #
+      # @param route [ActionDispatch::Journey::Route] Route given by Rails
+      # @return [Array<String>] List of HTTP verbs for the given route
+      def verbs_for(route)
+        route_verb = route.verb.to_s
+
+        %w[GET POST PUT PATCH DELETE].select do |verb|
+          route_verb.include?(verb)
+        end
+      end
+
+      # Formats information for a given route.
       #
-      # @param {ActionDispatch::Journey::Route} route - Route given by Rails
-      # @return {Hash} - { verb: String, path: String, name: String }
-      def format_route(route)
+      # @param route [ActionDispatch::Journey::Route] Route given by Rails
+      # @param verb [String] HTTP verb
+      # @param defaults [Hash] Default parameters for route
+      # @return [Hash] { verb => String, path => String, name => String }
+      def format(route:, verb:, defaults:)
         {
-          verb: route.verb,
+          verb: verb,
           path: route.path.spec.to_s.gsub('(.:format)', ''),
-          name: route.name
+          name: route.name,
+          defaults: defaults
         }
       end
 
       # Given a routes hash, backfill entries that aren't already filled by
       # `Rails.application.routes`.
       #
-      # @param {Hash} routes - Routes hash generated by this class
-      # @return {Hash} - Backfilled routes hash
+      # @param routes [Hash] Routes hash generated by this class
+      # @return [Hash] Backfilled routes hash
       def backfill_routes(routes)
         paths = {}
 
@@ -73,14 +114,14 @@ module Chusaku
 
       # Given a route, extract the controller and action strings.
       #
-      # @param {ActionDispatch::Journey::Route} route - Route instance
-      # @return {Array<String>} - [String, String]
-      def extract_controller_and_action_from(route)
-        defaults = route.defaults
-        controller = defaults[:controller]
-        action = defaults[:action]
+      # @param route [ActionDispatch::Journey::Route] Route instance
+      # @return [Array<Object>] (String, String, Hash)
+      def extract_data_from(route)
+        defaults = route.defaults.dup
+        controller = defaults.delete(:controller)
+        action = defaults.delete(:action)
 
-        [controller, action]
+        [controller, action, defaults]
       end
     end
   end

data/lib/chusaku/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Chusaku
-  VERSION = '0.3.0'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chusaku
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Nishiki Liu
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-12-16 00:00:00.000000000 Z
+date: 2021-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,87 +16,87 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.14'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.77'
+        version: '1.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.77'
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.9'
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
 description: Annotate your Rails controllers with route info.
 email:
-- nishiki.liu@gmail.com
+- nishiki@hey.com
 executables:
 - chusaku
 extensions: []
@@ -127,7 +127,7 @@ metadata:
   homepage_uri: https://github.com/nshki/chusaku
   source_code_uri: https://github.com/nshki/chusaku
   changelog_uri: https://github.com/nshki/chusaku
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -142,8 +142,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.2.15
+signing_key:
 specification_version: 4
 summary: Annotate your Rails controllers with route info.
 test_files: []