debtective 0.2.3.4 → 0.2.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09e2ba02faff3be09a87e2babe120bb59e28f0ea509ad8cc8ef1f9a12cf55ae6'
-  data.tar.gz: e1c5d6197706783907a1756671928eac854d1d771eb541d58b18dba8053da003
+  metadata.gz: 0ca6f9979cf0b568bf7abd46ec7bca857f7fd2e62a8d15e85cd80920450395a7
+  data.tar.gz: c7df027f440b683be96278a5c57ae8b1829ac261b861a11b68d78b2c502be2cf
 SHA512:
-  metadata.gz: f1641ef5d5031d12d7c85665a252ab168cf456297621b81c400f22c8a8017868eb3c7873eade9ae2c8b0cb21c93a85d702ff16ffd4a45b822edd0d450ca42835
-  data.tar.gz: f371a5a826c7daff0c6cc2a31e7e5686731f29d74b568e96174de0000bdec70c62318481ff2a21ef98ff84d279053fbbb747511f75b0e0c79c8adb160f540bcb
+  metadata.gz: b02f93cac47d43efbd15521a6be821d9de597b8d56d14980a42456211b57f9c6c06161d4aae27f66b2bcc47bee034112dd721e232f87bb698eacef504ce1ea0e
+  data.tar.gz: f7e4f1cd2af557f31e4e36ec89adb77af8eecffe6dfdfeb3ea6df5ff3d40c9d0aca0a66a7b9b6fe786b6e0883f0d8f81a01c4b5b0301904ae1f0f8bab9a3b54e

data/bin/debtective

@@ -1,26 +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/export"
-  Debtective::Todos::Export.new(user_name: user_name, quiet: quiet).call
-when "--offenses"
-  require "debtective/offenses/export"
-  Debtective::Offenses::Export.new(user_name: user_name, quiet: quiet).call
-when "--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