debtective 0.2.3.3 → 0.2.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5c39390d5b43a335045481e47b106c30facd0d66ea88359209ecc57887f6a4e
-  data.tar.gz: 182beede8ace506b42e175bdd9fec0748464bfe4aa75ff1e95c7d100df4c5444
+  metadata.gz: ebde46135dabc88a0da1b27f4134cd932bebf3c329dc1e894413f4dd914caa15
+  data.tar.gz: d0a7a1181c6766d0aaac682ab1fcfe1433e2a7ced12cf14b86d0c72d7c7a9b0b
 SHA512:
-  metadata.gz: c846a7c047b667926d576a51331820b26e98d8e25ff16bdb192a2c8aa080aceac69f9cb7f747c90d8e3c25ed6c7c59bd3fbd6642a2da2572ffeeb304c54aa10d
-  data.tar.gz: 4870ac4fcc0b9fa93eeaf2f72e410b06bd7b9bcea56e44557f32ee2788c572186cdea8177a6168c24cc6917360e5d02e90793b951d5d1bcdb58806cad00ca28b
+  metadata.gz: ff8049df8035520a01ee0f3f5f9f6287c9e1575596123dec02e1720c5150c1053bf5e821a29c1886c77bf9a29b3cf946c5534d749c7b502519f1e5cfab06836d
+  data.tar.gz: 4cbacb9e39e81170c37a61c1e0d0dd585014451f53e560f5a12f0bfca60e5db91faa3cf441eaddc142cd2f9d595fe5e69b7b117216d8068aab977843bf800412

data/bin/debtective

@@ -1,23 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "debtective"
+require "debtective/command"
 
-user_name =
-  if ARGV.include?("--me")
-    `git config user.name`.strip
-  elsif ARGV.include?("--user")
-    ARGV[ARGV.index("--user") + 1]
-  end
-
-quiet = ARGV.include?("--quiet")
-
-case ARGV[0]
-when "--todos"
-  require "debtective/todos/output"
-  Debtective::Todos::Output.new(user_name, quiet: quiet).call
-when "--offenses", "--gems"
-  puts "Upcoming feature"
-else
-  puts "Please pass one of this options: [--todos, --offenses, --gems]"
-end
+Debtective::Command.new(ARGV).call

data/lib/debtective/command.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "debtective"
+require_relative "comments/command"
+
+module Debtective
+  # Handle commands from CLI
+  class Command
+    # @param args [Array<String>] ARGVs from command line (order matters)
+    def initialize(args)
+      @args = args
+    end
+
+    # Forward to the proper command
+    def call
+      case @args.first&.delete("--")
+      when "comments"
+        Debtective::Comments::Command.new(@args, quiet: quiet?).call
+      when "gems"
+        puts "Upcoming feature!"
+      else
+        puts "Please pass one of this options: [--comments, --gems]"
+      end
+    end
+
+    private
+
+    def quiet?
+      @args.include?("--quiet")
+    end
+  end
+end

data/lib/debtective/comments/build_comment.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "comment/fixme"
+require_relative "comment/magic"
+require_relative "comment/note"
+require_relative "comment/offense"
+require_relative "comment/shebang"
+require_relative "comment/todo"
+require_relative "comment/yard"
+
+module Debtective
+  module Comments
+    # Build proper comment type given the code line
+    class BuildComment
+      # Order matters, for example the Comment::Note regex matches
+      # (almost) all previous regexes so it needs to be tested last
+      TYPES = {
+        /#\sTODO:/ => Comment::Todo,
+        /#\sFIXME:/ => Comment::Fixme,
+        /\s# rubocop:disable (.*)/ => Comment::Offense,
+        /#\s@/ => Comment::Yard,
+        /^# (frozen_string_literal|coding|encoding|warn_indent|sharable_constant_value):/ => Comment::Magic,
+        /^#!/ => Comment::Shebang,
+        /(^|\s)#\s/ => Comment::Note
+      }.freeze
+
+      # @param line [String] code line
+      # @param pathname [Pathname] file path
+      # @param index [Integer] position of the line in the file
+      def initialize(line:, pathname:, index:)
+        @line = line
+        @pathname = pathname
+        @index = index
+      end
+
+      # @return [Debtective::Comments::Base]
+      def call
+        klass&.new(pathname: @pathname, index: @index)
+      end
+
+      private
+
+      def klass
+        TYPES.each { |regex, klass| return klass if @line.match?(regex) }
+        nil
+      end
+    end
+  end
+end

data/lib/debtective/comments/command.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "export"
+
+module Debtective
+  module Comments
+    # Handle comments command and given ARGVs
+    class Command
+      TYPE_OPTIONS = %w[fixme magic note offense shebang todo yard].freeze
+
+      # @param args [Array<String>] ARGVs from command line (order matters)
+      # @param quiet [Boolean]
+      def initialize(args, quiet: false)
+        @args = args
+        @quiet = quiet
+      end
+
+      # @return [Debtective::Comments::Export]
+      def call
+        Export.new(
+          user_name: user_name,
+          quiet: @quiet,
+          included_types: included_types,
+          excluded_types: excluded_types,
+          included_paths: paths("include"),
+          excluded_paths: paths("exclude")
+        ).call
+      end
+
+      private
+
+      def user_name
+        if @args.include?("--me")
+          `git config user.name`.strip
+        elsif @args.include?("--user")
+          @args[@args.index("--user") + 1]
+        end
+      end
+
+      def included_types
+        TYPE_OPTIONS.select { @args.include?("--#{_1}") }
+      end
+
+      def excluded_types
+        TYPE_OPTIONS.select { @args.include?("--no-#{_1}") }
+      end
+
+      def paths(rule)
+        return [] unless @args.include?("--#{rule}")
+
+        paths = []
+        @args[(@args.index("--#{rule}") + 1)..].each do |arg|
+          return paths if arg.match?(/^--.*/)
+
+          paths << arg
+        end
+        paths
+      end
+    end
+  end
+end

data/lib/debtective/comments/comment/base.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "../find_commit"
+
+module Debtective
+  module Comments
+    module Comment
+      # Hold comment information
+      class Base
+        # Does not match YARD or shebang comments
+        REGULAR_COMMENT = /^\s*#\s(?!@)/
+
+        attr_accessor :pathname
+
+        # @param pathname [Pathname] path of the file
+        # @param index [Integer] position of the comment in the file
+        def initialize(pathname:, index:)
+          @pathname = pathname
+          @index = index
+        end
+
+        # @return [String]
+        def type
+          self.class.name.split("::").last.downcase
+        end
+
+        # @return [Integer]
+        def comment_start
+          @index
+        end
+
+        # @return [Integer]
+        def comment_end
+          @comment_end ||= last_following_comment_index || comment_start
+        end
+
+        # @return [Integer]
+        def statement_start
+          @statement_start ||= inline? ? @index : comment_end.next
+        end
+
+        # @return [Integer]
+        def statement_end
+          statement_start
+        end
+
+        # Location in the codebase (for clickable link)
+        # @return [String]
+        def location
+          "#{@pathname.to_s.gsub(%r{^./}, "")}:#{comment_start + 1}"
+        end
+
+        # Return commit that introduced the todo
+        # @return [Debtective::Comments::FindCommit::Commit]
+        def commit
+          @commit ||= FindCommit.new(pathname: @pathname, line: lines[@index]).call
+        end
+
+        # @return [Integer]
+        def days
+          return if commit.time.nil?
+
+          ((Time.now - commit.time) / (24 * 60 * 60)).round
+        end
+
+        # @return [Hash]
+        def to_h
+          {
+            pathname: @pathname,
+            location: location,
+            type: type,
+            comment_boundaries: [comment_start, comment_end],
+            statement_boundaries: [statement_start, statement_end],
+            commit: commit.sha,
+            author: commit.author.to_h,
+            time: commit.time
+          }
+        end
+
+        private
+
+        def lines
+          @lines ||= @pathname.readlines
+        end
+
+        def inline?
+          @inline ||= !lines[@index].match?(/^\s*#/)
+        end
+
+        def last_following_comment_index
+          if inline?
+            @index
+          else
+            lines.index.with_index do |line, i|
+              i > @index &&
+                !line.strip.empty? &&
+                !line.match?(REGULAR_COMMENT)
+            end&.-(1)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/debtective/comments/comment/fixme.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../find_end_of_statement"
+
+module Debtective
+  module Comments
+    module Comment
+      # Hold FIXME comment information
+      class Fixme < Base
+        # (see Base#statement_end)
+        def statement_end
+          return super if inline?
+
+          FindEndOfStatement.new(lines: lines, first_line_index: statement_start).call
+        end
+      end
+    end
+  end
+end

data/lib/debtective/comments/comment/magic.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Debtective
+  module Comments
+    module Comment
+      # Hold magic comment information
+      class Magic < Base
+        # (see Base#comment_end)
+        def comment_end
+          @index
+        end
+
+        # (see Base#statement_start)
+        def statement_start
+          nil
+        end
+
+        # (see Base#statement_end)
+        def statement_end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/debtective/comments/comment/note.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Debtective
+  module Comments
+    module Comment
+      # Hold note comment information (any "other" comment)
+      class Note < Base; end
+    end
+  end
+end

data/lib/debtective/comments/comment/offense.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Debtective
+  module Comments
+    module Comment
+      # Hold offense information
+      class Offense < Base; end
+    end
+  end
+end

data/lib/debtective/comments/comment/shebang.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Debtective
+  module Comments
+    module Comment
+      # Hold shebang comment (#!) information
+      class Shebang < Base
+        # (see Base#comment_end)
+        def comment_end
+          @index
+        end
+
+        # (see Base#statement_start)
+        def statement_start
+          nil
+        end
+
+        # (see Base#statement_end)
+        def statement_end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/debtective/comments/comment/todo.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../find_end_of_statement"
+
+module Debtective
+  module Comments
+    module Comment
+      # Hold TODO comment information
+      class Todo < Base
+        # (see Base#statement_end)
+        def statement_end
+          return super if inline?
+
+          FindEndOfStatement.new(lines: lines, first_line_index: statement_start).call
+        end
+      end
+    end
+  end
+end

data/lib/debtective/comments/comment/yard.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../find_end_of_statement"
+
+module Debtective
+  module Comments
+    module Comment
+      # Hold YARD comment information
+      class Yard < Base
+        # (see Base#comment_end)
+        def comment_end
+          @index
+        end
+
+        # (see Base#statement_start)
+        def statement_start
+          last_following_comment_index.next
+        end
+
+        # (see Base#statement_end)
+        def statement_end
+          FindEndOfStatement.new(lines: lines, first_line_index: statement_start).call
+        end
+      end
+    end
+  end
+end

data/lib/debtective/comments/export.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "json"
+require "parser/current"
+require_relative "../stderr_helper"
+require_relative "build_comment"
+require_relative "print"
+
+module Debtective
+  module Comments
+    # Export comments in a JSON file and to stdout
+    class Export
+      include StderrHelper
+
+      OPTIONS = {
+        user_name: nil,
+        quiet: false,
+        included_types: [],
+        excluded_types: [],
+        included_paths: [],
+        excluded_paths: []
+      }.freeze
+
+      FILE_PATH = "comments.json"
+
+      # @param user_name [String] git user email to filter
+      # @param quiet [boolean]
+      # @param included_types [Array<String>] types of comment to export
+      # @param excluded_types [Array<String>] types of comment to skip
+      # @param included_paths [Array<String>] paths to explore
+      # @param excluded_paths [Array<String>] paths to skip
+      def initialize(**options)
+        OPTIONS.each do |key, default|
+          instance_variable_set(:"@#{key}", options[key] || default)
+        end
+      end
+
+      # @return [void]
+      def call
+        # suppress_stderr prevents stderr outputs from compilations
+        suppress_stderr do
+          @comments = @quiet ? find_comments : log_table
+        end
+        filter_comments!
+        log_counts unless @quiet
+        write_json_file
+        puts(FILE_PATH) unless @quiet
+      end
+
+      private
+
+      def find_comments
+        pathnames.flat_map do |pathname|
+          last_comment_found = nil
+          pathname.readlines.filter_map.with_index do |line, index|
+            next if last_comment_found && index < last_comment_found.comment_end.next
+            next unless comment?(line)
+
+            comment = BuildComment.new(line: line, pathname: pathname, index: index).call
+            next if comment.nil?
+
+            last_comment_found = comment
+            export_comment(comment)
+          end
+        end
+      end
+
+      def comment?(line)
+        return true if line =~ /^\s*#(\s|!)/
+        return false unless line =~ /\s(#\s.*)/
+
+        # Ensure it is really a comment to avoid something like
+        # puts("hello # world")
+        # to be considered as an inline comment
+        !Parser::CurrentRuby.parse(line).to_s.include?(Regexp.last_match[1])
+      rescue Parser::SyntaxError
+        false
+      end
+
+      # Export the comment if asked so by the user
+      # @return [Debtective::Comments::Comment::Base, nil]
+      # @note This method is watched by Print class to log in stdout
+      def export_comment(comment)
+        if @included_types.include?(comment.type) ||
+           (@included_types.empty? && !@excluded_types.include?(comment.type))
+
+          comment
+        end
+      end
+
+      def log_table
+        Print.new(user_name: @user_name).call { find_comments }
+      end
+
+      # List of paths to search in
+      def pathnames
+        Dir["./**/*"]
+          .map { Pathname(_1) }
+          .select { _1.file? && _1.extname == ".rb" && explore?(_1) }
+      end
+
+      def explore?(path)
+        return false if @excluded_paths.any? { path.to_s.gsub(%r{^./}, "").match?(/^#{_1}/) }
+        return true if @included_paths.empty?
+
+        @included_paths.any? { path.to_s.gsub(%r{^./}, "").match?(/^#{_1}/) }
+      end
+
+      # Select comments committed by the user
+      def filter_comments!
+        return if @user_name.nil?
+
+        @comments.select! { _1.commit.author.name == @user_name }
+      end
+
+      def log_counts
+        puts "total: #{@comments.count}"
+      end
+
+      def write_json_file
+        File.open(self.class::FILE_PATH, "w") do |file|
+          file.puts(
+            JSON.pretty_generate(
+              @comments.map(&:to_h)
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/lib/debtective/comments/find_commit.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "git"
+require "open3"
+
+module Debtective
+  module Comments
+    # Find the commit that introduced the given line of code
+    class FindCommit
+      Author = Struct.new(:email, :name)
+      Commit = Struct.new(:sha, :author, :time)
+
+      # @param pathname [Pathname] file path
+      # @param line [String] line of code
+      def initialize(pathname:, line:)
+        @pathname = pathname
+        @line = line
+      end
+
+      # @return [Debtective::Comments::FindCommit::Commit]
+      def call
+        Commit.new(sha, author, time)
+      rescue Git::GitExecuteError
+        author = Author.new(nil, nil)
+        Commit.new(nil, author, nil)
+      end
+
+      # @return [Debtective::Comments::FindCommit::Author]
+      def author
+        Author.new(commit.author.email, commit.author.name)
+      end
+
+      # @return [Time]
+      def time
+        commit.date
+      end
+
+      # @return [String]
+      def sha
+        @sha ||=
+          begin
+            cmd = "git log -S \"#{safe_code}\" #{@pathname}"
+            stdout, _stderr, _status = ::Open3.capture3(cmd)
+            stdout[/commit (\w{40})\n/, 1]
+          end
+      end
+
+      private
+
+      # @return [Git::Base]
+      def git
+        Git.open(".")
+      end
+
+      # @return [Git::Object::Commit]
+      def commit
+        git.gcommit(sha)
+      end
+
+      # Characters " and ` can break the git command
+      def safe_code
+        @line.gsub(/"/, "\\\"").gsub("`", "\\\\`")
+      end
+    end
+  end
+end

data/lib/debtective/comments/find_end_of_statement.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Debtective
+  module Comments
+    # Find the index of the line ending a statement
+    #
+    # @example
+    #   FindEndOfStatement.new(
+    #     [
+    #       "class User",
+    #       "  def example",
+    #       "    x + y",
+    #       "  end"
+    #       "end"
+    #     ],
+    #     1
+    #   ).call
+    #   => 3
+    #
+    class FindEndOfStatement
+      # @param lines [Array<String>] lines of code
+      # @param first_line_index [Integer] index of the statement first line
+      def initialize(lines:, first_line_index:)
+        @lines = lines
+        @first_line_index = first_line_index
+      end
+
+      # @return [Integer] index of the line ending the statement
+      # @note suppress_stderr prevents outputs from RubyVM::InstructionSequence.compile
+      def call
+        last_line_index
+      end
+
+      private
+
+      # Recursively find index of the line ending the statement
+      # (it is possible that no line ends the statement
+      # especially if the first line is not the start of a statement)
+      def last_line_index(index = @first_line_index)
+        return @first_line_index if index >= @lines.size
+        return index if !chained?(index) && statement?(index)
+
+        last_line_index(index + 1)
+      end
+
+      # Check if the code from first index to given index is a statement,
+      # e.i. can be parsed by a ruby parser (using whitequark/parser)
+      def statement?(index)
+        code = @lines[@first_line_index..index].join("\n")
+        RubyVM::InstructionSequence.compile(code)
+      rescue SyntaxError
+        false
+      end
+
+      # Check if current line is chained, e.i. next line start with a "."
+      def chained?(index)
+        @lines[index + 1]&.match?(/^(\s*)\./)
+      end
+    end
+  end
+end