smart_todo 1.0.0

data/lib/smart_todo/events/date.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module SmartTodo
+  module Events
+    # An event that check if the passed date is passed
+    class Date
+      # @param on_date [String] a string parsable by Time.parse
+      # @return [String, false]
+      def self.met?(on_date)
+        if Time.now >= Time.parse(on_date)
+          message(on_date)
+        else
+          false
+        end
+      end
+
+      # @param on_date [String]
+      # @return [String]
+      def self.message(on_date)
+        "We are past the *#{on_date}* due date and your TODO is now ready to be addressed."
+      end
+    end
+  end
+end

data/lib/smart_todo/events/gem_release.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+
+module SmartTodo
+  module Events
+    # An event that check if a new version of gem has been released on RubyGem
+    # with the expected version specifiers.
+    # This event will make an API call to the RubyGem API
+    class GemRelease
+      # @param gem_name [String]
+      # @param requirements [Array] a list of version specifiers.
+      #   The specifiers are the same as the one used in Gemfiles or Gemspecs
+      #
+      # @example Expecting a specific version
+      #   GemRelease.new('rails', ['6.0'])
+      #
+      # @example Expecting a version in the 5.x.x series
+      #   GemRelease.new('rails', ['> 5.2', '< 6'])
+      def initialize(gem_name, requirements)
+        @gem_name = gem_name
+        @requirements = Gem::Requirement.new(requirements)
+      end
+
+      # @return [String, false]
+      def met?
+        response = client.get("/api/v1/versions/#{@gem_name}.json")
+
+        if response.code_type < Net::HTTPClientError
+          error_message
+        elsif (gem = version_released?(response.body))
+          message(gem['number'])
+        else
+          false
+        end
+      end
+
+      # Error message send to Slack in case a gem couldn't be found
+      #
+      # @return [String]
+      def error_message
+        "The gem *#{@gem_name}* doesn't seem to exist, I can't determine if your TODO is ready to be addressed."
+      end
+
+      # @return [String]
+      def message(version_number)
+        "The gem *#{@gem_name}* was released to version *#{version_number}* and your TODO is now ready to be addressed."
+      end
+
+      private
+
+      # @param gem_versions [String] the response sent from RubyGems
+      # @return [true, false]
+      def version_released?(gem_versions)
+        JSON.parse(gem_versions).find do |gem|
+          @requirements.satisfied_by?(Gem::Version.new(gem['number']))
+        end
+      end
+
+      # @return [Net::HTTP] an instance of Net::HTTP
+      def client
+        @client ||= Net::HTTP.new('rubygems.org', Net::HTTP.https_default_port).tap do |client|
+          client.use_ssl = true
+        end
+      end
+    end
+  end
+end

data/lib/smart_todo/events/pull_request_close.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+
+module SmartTodo
+  module Events
+    # An event that check if a GitHun Pull Request or Issue is closed.
+    # This event will make an API call to the GitHub API.
+    #
+    # If the Pull Request or Issue is on a private repository, exporting a token
+    # with the `repos` scope in the +SMART_TODO_GITHUB_TOKEN+ environment variable
+    # is required.
+    class PullRequestClose
+      TOKEN_ENV = 'SMART_TODO_GITHUB_TOKEN'
+
+      # @param organization [String]
+      # @param repo [String]
+      # @param pr_number [String, Integer]
+      def initialize(organization, repo, pr_number)
+        @url = "/repos/#{organization}/#{repo}/pulls/#{pr_number}"
+        @organization = organization
+        @repo = repo
+        @pr_number = pr_number
+      end
+
+      # @return [String, false]
+      def met?
+        response = client.get(@url, default_headers)
+
+        if response.code_type < Net::HTTPClientError
+          error_message
+        elsif pull_request_closed?(response.body)
+          message
+        else
+          false
+        end
+      end
+
+      # Error message send to Slack in case the Pull Request or Issue couldn't be found.
+      #
+      # @return [String]
+      def error_message
+        <<~EOM
+          I can't retrieve the information from the PR or Issue *#{@pr_number}* in the
+          *#{@organization}/#{@repo}* repository.
+
+          If the repository is a private one, make sure to export the `#{TOKEN_ENV}`
+          environment variable with a correct GitHub token.
+        EOM
+      end
+
+      # @return [String]
+      def message
+        <<~EOM
+          The Pull Request or Issue https://github.com/#{@organization}/#{@repo}/pull/#{@pr_number}
+          is now closed, your TODO is ready to be addressed.
+        EOM
+      end
+
+      private
+
+      # @return [Net::HTTP] an instance of Net::HTTP
+      def client
+        @client ||= Net::HTTP.new('api.github.com', Net::HTTP.https_default_port).tap do |client|
+          client.use_ssl = true
+        end
+      end
+
+      # @param pull_request [String] the Pull Request or Issue
+      #   detail sent back from the GitHub API
+      #
+      # @return [true, false]
+      def pull_request_closed?(pull_request)
+        JSON.parse(pull_request)['state'] == 'closed'
+      end
+
+      # @return [Hash]
+      def default_headers
+        { 'Accept' => 'application/vnd.github.v3+json' }.tap do |headers|
+          headers['Authorization'] = "token #{ENV[TOKEN_ENV]}" if ENV[TOKEN_ENV]
+        end
+      end
+    end
+  end
+end

data/lib/smart_todo/events.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SmartTodo
+  # This module contains all the methods accessible for SmartTodo comments.
+  # It is meant to be reopened by the host application in order to define
+  # its own events.
+  #
+  # An event needs to return a +String+ containing the message that will be
+  # sent to the TODO assignee or +false+ in case the event hasn't been met.
+  #
+  # @example Adding a custom event
+  #   module SmartTodo
+  #     module Events
+  #       def trello_card_close(card)
+  #         ...
+  #       end
+  #     end
+  #   end
+  #
+  #   TODO(on: trello_card_close(381), to: 'john@example.com')
+  module Events
+    extend self
+
+    # Check if the +date+ is in the past
+    #
+    # @param date [String] a correctly formatted date
+    # @return [false, String]
+    def date(date)
+      Date.met?(date)
+    end
+
+    # Check if a new version of +gem_name+ was released with the +requirements+ expected
+    #
+    # @param gem_name [String]
+    # @param requirements [Array<String>] a list of version specifiers
+    # @return [false, String]
+    def gem_release(gem_name, *requirements)
+      GemRelease.new(gem_name, requirements).met?
+    end
+
+    # Check if the Pull Request or issue +pr_number+ is closed
+    #
+    # @param organization [String] the GitHub organization name
+    # @param repo [String] the GitHub repo name
+    # @param pr_number [String, Integer]
+    # @return [false, String]
+    def pull_request_close(organization, repo, pr_number)
+      PullRequestClose.new(organization, repo, pr_number).met?
+    end
+    alias_method :issue_close, :pull_request_close
+  end
+end

data/lib/smart_todo/parser/comment_parser.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'ripper'
+
+module SmartTodo
+  module Parser
+    # This class is used to parse Ruby code and will stop each time
+    # a Ruby comment is encountered. It will detect if a TODO comment
+    # is a Smart Todo and will gather the comments associated to the TODO.
+    class CommentParser < Ripper::Filter
+      def initialize(*)
+        super
+        @node = nil
+      end
+
+      # @param comment [String] the actual Ruby comment
+      # @param data [Array<TodoNode>]
+      # @return [Array<TodoNode>]
+      def on_comment(comment, data)
+        if todo_metadata?(comment)
+          append_existing_node(data)
+          @node = TodoNode.new(comment)
+        elsif todo_comment?(comment)
+          @node << comment
+        else
+          append_existing_node(data)
+          @node = nil
+        end
+
+        data
+      end
+
+      # @param init [Array]
+      # @return [Array<TodoNode>]
+      def parse(init = [])
+        super(init)
+
+        init.tap { append_existing_node(init) }
+      end
+
+      private
+
+      # @param comment [String] the actual Ruby comment
+      # @return [nil, Integer]
+      def todo_metadata?(comment)
+        /^#\sTODO\(/ =~ comment
+      end
+
+      # Check if the comment is associated with the Smart Todo
+      # @param comment [String] the actual Ruby comment
+      # @return [true, false]
+      #
+      # @example When a comment is associated to a SmartTodo
+      #   TODO(on_date(...), to: '...')
+      #     This is an associated comment
+      #
+      # @example When a comment is not associated to a SmartTodo
+      #   TODO(on_date(...), to: '...')
+      #   This is an associated comment (Note the indentation)
+      def todo_comment?(comment)
+        @node&.indented_comment?(comment)
+      end
+
+      # @param data [Array<TodoNode>]
+      # @return [Array<TodoNode>]
+      def append_existing_node(data)
+        data << @node if @node
+      end
+    end
+  end
+end

data/lib/smart_todo/parser/metadata_parser.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'ripper'
+
+module SmartTodo
+  module Parser
+    # A MethodNode represent an event associated to a TODO.
+    class MethodNode
+      attr_reader :method_name, :arguments
+
+      # @param method_name [Symbol]
+      # @param arguments [Array<String>]
+      def initialize(method_name, arguments)
+        @arguments = arguments
+        @method_name = method_name
+      end
+    end
+
+    # This class is used to parse the ruby TODO() comment.
+    class MetadataParser < Ripper
+      # @param source [String] the actual Ruby code
+      def self.parse(source)
+        sexp = new(source).parse
+        Visitor.new.tap { |v| v.process(sexp) }
+      end
+
+      # @return [Array] an Array of Array
+      #   the first element from each inner array is a token
+      def on_stmts_add(_, data)
+        data
+      end
+
+      # @param method [String] the name of the method
+      #   when the parser hits one.
+      # @param args [Array]
+      # @return [Array, MethodNode]
+      def on_method_add_arg(method, args)
+        if method == 'TODO'
+          args
+        else
+          MethodNode.new(method, args)
+        end
+      end
+
+      # @param list [nil, Array]
+      # @param arg [String]
+      # @return [Array]
+      def on_args_add(list, arg)
+        Array(list) << arg
+      end
+
+      # @param string_content [String]
+      # @return [String]
+      def on_string_add(_, string_content)
+        string_content
+      end
+
+      # @param key [String]
+      # @param value [String, Integer, MethodNode]
+      def on_assoc_new(key, value)
+        key.tr!(':', '')
+
+        case key
+        when 'on'
+          [:on_todo_event, value]
+        when 'to'
+          [:on_todo_assignee, value]
+        else
+          [:unknown, value]
+        end
+      end
+
+      # @param data [Hash]
+      # @return [Hash]
+      def on_bare_assoc_hash(data)
+        data
+      end
+    end
+
+    class Visitor
+      attr_reader :events, :assignee
+
+      def initialize
+        @events = []
+      end
+
+      # Iterate over each tokens returned from the parser and call
+      # the corresponding method
+      #
+      # @param sexp [Array]
+      # @return [void]
+      def process(sexp)
+        return unless sexp
+
+        if sexp[0].is_a?(Array)
+          sexp.each { |node| process(node) }
+        else
+          method, *args = sexp
+          send(method, *args) if method.is_a?(Symbol) && respond_to?(method)
+        end
+      end
+
+      # @param method_node [MethodNode]
+      # @return [void]
+      def on_todo_event(method_node)
+        events << method_node
+      end
+
+      # @param assignee [String]
+      # @return [void]
+      def on_todo_assignee(assignee)
+        @assignee = assignee
+      end
+    end
+  end
+end

data/lib/smart_todo/parser/todo_node.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SmartTodo
+  module Parser
+    # Represents a SmartTodo which includes the associated events
+    # as well as the assignee.
+    class TodoNode
+      DEFAULT_RUBY_INDENTATION = 2
+
+      attr_reader :metadata
+
+      # @param todo [String] the actual Ruby comment
+      def initialize(todo)
+        @metadata = MetadataParser.parse(todo.gsub(/^#/, ''))
+        @comments = []
+        @start = todo.match(/^#(\s+)/)[1].size
+      end
+
+      # Return the associated comment for this TODO
+      #
+      # @return [String]
+      def comment
+        @comments.join
+      end
+
+      # @param comment [String]
+      # @return [void]
+      def <<(comment)
+        @comments << comment.gsub(/^#(\s+)/, '')
+      end
+
+      # Check if the +comment+ is indented two spaces below the
+      # TODO declaration. If yes the comment is considered to be part
+      # of the TODO itself. Otherwise it's just a regular comment.
+      #
+      # @param comment [String]
+      # @return [true, false]
+      def indented_comment?(comment)
+        comment.match(/^#(\s+)/)[1].size - @start == DEFAULT_RUBY_INDENTATION
+      end
+    end
+  end
+end