smart_todo 1.9.2 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: beb68e6ca2807c8c2fb782fb34109d5abe45f3e306cab7ad2f34b211f6a250aa
-  data.tar.gz: cc9978ba39c42bf194de59836c945197d066537187e34285857758bfcaf63ed5
+  metadata.gz: cd76c16d18b12ed3caada5a661031dd5f14c60aa1b0b227c0eb720116755c2cc
+  data.tar.gz: 91dadbb687dcfd22c4152f2b38054873f6d64fce3b43d8d96b8ac6891947e92a
 SHA512:
-  metadata.gz: 580080fabbbcc83ad8f372e56b5d4c2238688fc4617edd1501ac3032ddd61497db9e9c2a648f7a7b32acdda27790fa63fe0eb5c5c08d8b97c2e72116f2868f92
-  data.tar.gz: 6593132b64a848caa0205518b8c2124d04e6099b225af92e18ff997b5d204c1518c70c556280b766f3d6ea639bf9d4b44460152230f37baeda08f49f707bc889
+  metadata.gz: cede44f989ddbc2a4174c5c273e1e7e08521bbaaddc2a18fe5afc88d04fb84cdb6644e9d6c6839f6e7257dc1271f7f188bbdc6edec21a19debb8e0a438c20130
+  data.tar.gz: fc3d770921d2c2d7a275236ea068c9aef5f2202de990c644afeb4cfb974581e62e8ba77ae91bc6d6af265b438dde88b62052a9046f57301808a1a695d12e3c1c

data/.github/workflows/build.yml

@@ -15,7 +15,7 @@ jobs:
         version: [3.0, 3.1, 3.2, 3.3]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Ruby ${{ matrix.version }}
         uses: ruby/setup-ruby@v1
         with:

data/.github/workflows/rubocop.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    smart_todo (1.9.2)
+    smart_todo (1.11.0)
       prism (~> 1.0)
 
 GEM
@@ -10,26 +10,26 @@ GEM
     addressable (2.8.7)
       public_suffix (>= 2.0.2, < 7.0)
     ast (2.4.3)
-    bigdecimal (3.1.9)
-    crack (1.0.0)
+    bigdecimal (3.3.1)
+    crack (1.0.1)
       bigdecimal
       rexml
-    hashdiff (1.1.2)
+    hashdiff (1.2.1)
     json (2.10.2)
     language_server-protocol (3.17.0.4)
     lint_roller (1.1.0)
-    minitest (5.25.5)
+    minitest (5.26.0)
     parallel (1.26.3)
     parser (3.3.7.3)
       ast (~> 2.4.1)
       racc
-    prism (1.4.0)
-    public_suffix (6.0.1)
+    prism (1.6.0)
+    public_suffix (6.0.2)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
+    rake (13.3.0)
     regexp_parser (2.10.0)
-    rexml (3.4.1)
+    rexml (3.4.4)
     rubocop (1.74.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
@@ -49,7 +49,7 @@ GEM
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
-    webmock (3.25.1)
+    webmock (3.26.0)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)

data/lib/smart_todo/cli.rb

@@ -66,6 +66,9 @@ module SmartTodo
         opts.on("--dispatcher DISPATCHER") do |dispatcher|
           @options[:dispatcher] = dispatcher
         end
+        opts.on("--repo [REPO]", "Repository name to include in notifications") do |repo|
+          @options[:repo] = repo || File.basename(Dir.pwd)
+        end
       end
     end
 
@@ -103,12 +106,40 @@ module SmartTodo
         end
 
         @errors.concat(todo.errors)
-        dispatches << [event_message, todo] if event_met
+
+        next unless event_met
+
+        event_message = append_context_if_applicable(event_message, todo, event_met, events)
+
+        dispatches << [event_message, todo]
       end
 
       dispatches
     end
 
+    private
+
+    # @param event_message [String] the original event message
+    # @param todo [Todo] the todo object that may contain context
+    # @param event [Event] the event that was met
+    # @param events [Events] the events instance for fetching issue context
+    # @return [String] the event message, potentially with context appended
+    def append_context_if_applicable(event_message, todo, event, events)
+      return event_message unless should_apply_context?(todo, event)
+
+      org, repo, issue_number = todo.context.arguments
+      context_message = events.issue_context(org, repo, issue_number)
+
+      context_message ? "#{event_message}\n\n#{context_message}" : event_message
+    end
+
+    # @param todo [Todo] the todo object to check for context
+    # @param event [Event] the event to check
+    # @return [Boolean] true if context should be applied, false otherwise
+    def should_apply_context?(todo, event)
+      !!todo.context
+    end
+
     def process_dispatches(dispatches)
       queue = Queue.new
       dispatches.each { |dispatch| queue << dispatch }

data/lib/smart_todo/comment_parser.rb

@@ -2,6 +2,9 @@
 
 module SmartTodo
   class CommentParser
+    SUPPORTED_TAGS = ["TODO", "FIXME", "OPTIMIZE"].freeze
+    TAG_PATTERN = /^#\s(#{SUPPORTED_TAGS.join("|")})\(/
+
     attr_reader :todos
 
     def initialize
@@ -54,7 +57,7 @@ module SmartTodo
 
         source = comment.location.slice
 
-        if source.match?(/^#\sTODO\(/)
+        if source.match?(TAG_PATTERN)
           todos << current_todo if current_todo
           current_todo = Todo.new(source, filepath)
         elsif current_todo && (indent = source[/^#(\s*)/, 1].length) && (indent - current_todo.indent == 2)

data/lib/smart_todo/dispatchers/base.rb

@@ -68,7 +68,7 @@ module SmartTodo
         <<~EOM
           #{header}
 
-          You have an assigned TODO in the `#{@file}` file.
+          You have an assigned TODO in the `#{@file}` file#{repo}.
           #{@event_message}
 
           Here is the associated comment on your TODO:
@@ -91,6 +91,15 @@ module SmartTodo
       def existing_user
         "Hello :wave:,"
       end
+
+      def repo
+        repo = @options[:repo]
+        return unless repo
+
+        unless repo.empty?
+          " in repository `#{repo}`"
+        end
+      end
     end
   end
 end

data/lib/smart_todo/dispatchers/slack.rb

@@ -7,7 +7,8 @@ module SmartTodo
     class Slack < Base
       class << self
         def validate_options!(options)
-          options[:slack_token] ||= ENV.fetch("SMART_TODO_SLACK_TOKEN") { raise(ArgumentError, "Missing :slack_token") }
+          options[:slack_token] ||= ENV.fetch("SMART_TODO_SLACK_TOKEN", "")
+          raise(ArgumentError, "Missing :slack_token") if options[:slack_token].empty?
 
           options.fetch(:fallback_channel) { raise(ArgumentError, "Missing :fallback_channel") }
         end

data/lib/smart_todo/events.rb

@@ -75,6 +75,8 @@ module SmartTodo
           false
         end
       end
+    rescue Net::HTTPError, JSON::ParserError
+      "Error retrieving gem information for *#{gem_name}*."
     end
 
     # Check if +gem_name+ was bumped to the +requirements+ expected
@@ -130,6 +132,8 @@ module SmartTodo
       else
         false
       end
+    rescue Net::HTTPError, JSON::ParserError
+      "Error retrieving issue information for #{organization}/#{repo}##{issue_number}."
     end
 
     # Check if the pull request +pr_number+ is closed
@@ -155,6 +159,34 @@ module SmartTodo
       else
         false
       end
+    rescue Net::HTTPError, JSON::ParserError
+      "Error retrieving pull request information for #{organization}/#{repo}##{pr_number}."
+    end
+
+    # Retrieve context information for an issue
+    # This is used when a TODO has a context: issue() attribute
+    #
+    # @param organization [String] the GitHub organization name
+    # @param repo [String] the GitHub repo name
+    # @param issue_number [String, Integer]
+    # @return [String, nil]
+    def issue_context(organization, repo, issue_number)
+      headers = github_headers(organization, repo)
+      response = github_client.get("/repos/#{organization}/#{repo}/issues/#{issue_number}", headers)
+
+      if response.code_type < Net::HTTPClientError
+        nil
+      else
+        issue = JSON.parse(response.body)
+        state = issue["state"]
+        title = issue["title"]
+        assignee = issue["assignee"] ? "@#{issue["assignee"]["login"]}" : "unassigned"
+
+        "📌 Context: Issue ##{issue_number} - \"#{title}\" [#{state}] (#{assignee}) - " \
+          "https://github.com/#{organization}/#{repo}/issues/#{issue_number}"
+      end
+    rescue Net::HTTPError, JSON::ParserError
+      nil
     end
 
     # Check if the installed ruby version meets requirements.

data/lib/smart_todo/todo.rb

@@ -4,6 +4,7 @@ module SmartTodo
   class Todo
     attr_reader :filepath, :comment, :indent
     attr_reader :events, :assignees, :errors
+    attr_accessor :context
 
     def initialize(source, filepath = "-e")
       @filepath = filepath
@@ -12,6 +13,7 @@ module SmartTodo
 
       @events = []
       @assignees = []
+      @context = nil
       @errors = []
 
       parse(source[(indent + 1)..])
@@ -66,6 +68,28 @@ module SmartTodo
             end
           when :to
             metadata.assignees << visit(element.value)
+          when :context
+            value = visit(element.value)
+
+            unless value.is_a?(String)
+              metadata.errors << "Incorrect `:context` format: expected string value"
+              next
+            end
+
+            unless value =~ %r{^([^/]+)/([^#]+)#(\d+)$}
+              metadata.errors << "Incorrect `:context` format: expected \"org/repo#issue_number\""
+              next
+            end
+
+            org = ::Regexp.last_match(1)
+            repo = ::Regexp.last_match(2)
+            issue_number = ::Regexp.last_match(3)
+
+            if org.empty? || repo.empty?
+              metadata.errors << "Incorrect `:context` format: org and repo cannot be empty"
+            else
+              metadata.context = CallNode.new(:issue, [org, repo, issue_number], element.value.location)
+            end
           end
         end
       end

data/lib/smart_todo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SmartTodo
-  VERSION = "1.9.2"
+  VERSION = "1.11.0"
 end

data/lib/smart_todo_comment_format_cop.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "smart_todo"
+require "parser"
+
+module RuboCop
+  module Cop
+    module SmartTodo
+      # A RuboCop cop to enforce proper formatting of SmartTodo comments.
+      # SmartTodo comments must have their description on separate lines, indented by 2 spaces.
+      #
+      # Bad:
+      #   # TODO(on: date('2024-03-29'), to: 'john@example.com'): Remove this
+      #   # TODO(on: date('2024-03-29'), to: 'john@example.com') Remove this
+      #   # TODO(on: date('2024-03-29'), to: 'john@example.com')
+      #   # Remove this (not indented)
+      #
+      # Good:
+      #   # TODO(on: date('2024-03-29'), to: 'john@example.com')
+      #   #   Remove this (indented by 2 extra spaces)
+      #
+      class SmartTodoCommentFormatCop < Base
+        extend AutoCorrector
+
+        MSG_INLINE = "SmartTodo comment must not be on the same line as the TODO. " \
+          "For more info please look at https://github.com/Shopify/smart_todo/wiki/Syntax"
+        MSG_INDENT = "SmartTodo continuation line must be indented by 2 spaces. " \
+          "For more info please look at https://github.com/Shopify/smart_todo/wiki/Syntax"
+
+        SMART_TODO_PATTERN = /\A\s*#\s*(TODO|FIXME|OPTIMIZE)\(on:/
+        INLINE_TEXT_PATTERN = /\A(\s*#\s*(?:TODO|FIXME|OPTIMIZE)\(.+\))\s*:?\s+(.+)/
+
+        def on_new_investigation
+          processed_source.comments.each_with_index do |comment, index|
+            next unless smart_todo_comment?(comment)
+
+            check_inline_text(comment)
+            check_continuation_indent(comment, processed_source.comments[index + 1])
+          end
+        end
+
+        private
+
+        def smart_todo_comment?(comment)
+          comment.text.match?(SMART_TODO_PATTERN)
+        end
+
+        def check_inline_text(comment)
+          match = comment.text.match(INLINE_TEXT_PATTERN)
+          return unless match
+
+          add_offense(comment.location.expression, message: MSG_INLINE) do |corrector|
+            todo_part = match[1]
+            text_part = match[2]
+            indentation = " " * comment.location.column
+
+            corrected = "#{todo_part}\n#{indentation}#   #{text_part}"
+            corrector.replace(comment.location.expression, corrected)
+          end
+        end
+
+        def check_continuation_indent(comment, next_comment)
+          return unless next_comment
+          return unless next_comment.location.line == comment.location.line + 1
+          return if smart_todo_comment?(next_comment)
+          return if empty_comment?(next_comment)
+          return if properly_indented?(next_comment)
+
+          add_offense(next_comment.location.expression, message: MSG_INDENT) do |corrector|
+            corrected = fix_indentation(next_comment.text)
+            corrector.replace(next_comment.location.expression, corrected)
+          end
+        end
+
+        def empty_comment?(comment)
+          comment.text.match?(/\A\s*#\s*\z/)
+        end
+
+        def properly_indented?(comment)
+          # A properly indented continuation has exactly 2 spaces after the #
+          comment.text.match?(/\A\s*#   \S/)
+        end
+
+        def fix_indentation(text)
+          # Extract leading whitespace and content
+          match = text.match(/\A(\s*)#\s*(\S.*)\z/)
+          return text unless match
+
+          leading_space = match[1]
+          content = match[2]
+          "#{leading_space}#   #{content}"
+        end
+      end
+    end
+  end
+end

data/lib/smart_todo_cop.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "smart_todo"
+require "date"
 
 module RuboCop
   module Cop
@@ -12,12 +13,20 @@ module RuboCop
       class SmartTodoCop < Base
         HELP = "For more info please look at https://github.com/Shopify/smart_todo/wiki/Syntax"
         MSG = "Don't write regular TODO comments. Write SmartTodo compatible syntax comments. #{HELP}"
+        INVESTIGATED_TAGS = ::SmartTodo::CommentParser::SUPPORTED_TAGS +
+          ::SmartTodo::CommentParser::SUPPORTED_TAGS.map(&:downcase)
+        TODO_PATTERN = /^#\s@?(#{INVESTIGATED_TAGS.join("|")})\b/
 
         # @param processed_source [RuboCop::ProcessedSource]
         # @return [void]
         def on_new_investigation
           processed_source.comments.each do |comment|
-            next unless /^#\sTODO/.match?(comment.text)
+            next unless (match = TODO_PATTERN.match(comment.text))
+
+            if match[1] != match[1].upcase
+              add_offense(comment)
+              next
+            end
 
             metadata = metadata(comment.text)
 
@@ -25,10 +34,10 @@ module RuboCop
               add_offense(comment, message: "Invalid TODO format: #{metadata.errors.join(", ")}. #{HELP}")
             elsif !smart_todo?(metadata)
               add_offense(comment)
-            elsif (methods = invalid_event_methods(metadata.events)).any?
-              add_offense(comment, message: "Invalid event method(s): #{methods.join(", ")}. #{HELP}")
             elsif invalid_assignees(metadata.assignees).any?
               add_offense(comment, message: "Invalid event assignee. This method only accepts strings. #{HELP}")
+            elsif (invalid_events = validate_events(metadata.events)).any?
+              add_offense(comment, message: "#{invalid_events.join(". ")}. #{HELP}")
             end
           end
         end
@@ -49,17 +58,94 @@ module RuboCop
             metadata.assignees.any?
         end
 
-        # @param metadata [Array<SmartTodo::Parser::MethodNode>]
-        # @return [Array<String>]
-        def invalid_event_methods(events)
-          events.map(&:method_name).reject { |method| ::SmartTodo::Events.method_defined?(method) }
-        end
-
         # @param assignees [Array]
         # @return [Array]
         def invalid_assignees(assignees)
           assignees.reject { |assignee| assignee.is_a?(String) }
         end
+
+        # @param events [Array<SmartTodo::Todo::CallNode>]
+        # @return [Array<String>]
+        def validate_events(events)
+          invalid_methods = events.map(&:method_name).reject { |method| ::SmartTodo::Events.method_defined?(method) }
+          return ["Invalid event method(s): #{invalid_methods.join(", ")}"] if invalid_methods.any?
+
+          events.map do |event|
+            send(validate_method(event.method_name), event.arguments)
+          end.compact
+        end
+
+        # @param event_type [Symbol]
+        # @return [String]
+        def validate_method(event_type)
+          "validate_#{event_type}_args"
+        end
+
+        # @param args [Array]
+        # @return [String, nil] Returns error message if date is invalid, nil if valid
+        def validate_date_args(args)
+          date = args.first
+          Date.parse(date)
+          nil
+        rescue ArgumentError, TypeError
+          "Invalid date format: #{date}"
+        end
+
+        # @param args [Array]
+        # @return [String, nil] Returns error message if arguments are invalid, nil if valid
+        def validate_issue_close_args(args)
+          validate_fixed_arity_args(args, 3, "issue_close", ["organization", "repo", "issue_number"])
+        end
+
+        # @param args [Array]
+        # @return [String, nil] Returns error message if arguments are invalid, nil if valid
+        def validate_pull_request_close_args(args)
+          validate_fixed_arity_args(args, 3, "pull_request_close", ["organization", "repo", "pr_number"])
+        end
+
+        # @param args [Array]
+        # @return [String, nil] Returns error message if arguments are invalid, nil if valid
+        def validate_gem_release_args(args)
+          validate_gem_args(args, "gem_release")
+        end
+
+        # @param args [Array]
+        # @return [String, nil] Returns error message if arguments are invalid, nil if valid
+        def validate_gem_bump_args(args)
+          validate_gem_args(args, "gem_bump")
+        end
+
+        # @param args [Array]
+        # @return [String, nil] Returns error message if arguments are invalid, nil if valid
+        def validate_ruby_version_args(args)
+          if args.empty?
+            "Invalid ruby_version event: Expected at least 1 argument (version requirement), got 0"
+          elsif !args.all? { |arg| arg.is_a?(String) }
+            "Invalid ruby_version event: Version requirements must be strings"
+          end
+        end
+
+        # Helper method for validating fixed arity events
+        def validate_fixed_arity_args(args, expected_count, event_name, arg_names)
+          if args.size != expected_count
+            message = "Invalid #{event_name} event: Expected #{expected_count} arguments "
+            message += "(#{arg_names.join(", ")}), got #{args.size}"
+            message
+          elsif !args.all? { |arg| arg.is_a?(String) }
+            "Invalid #{event_name} event: Arguments must be strings"
+          end
+        end
+
+        # Helper method for validating gem-related events
+        def validate_gem_args(args, event_name)
+          if args.empty?
+            "Invalid #{event_name} event: Expected at least 1 argument (gem_name), got 0"
+          elsif !args[0].is_a?(String)
+            "Invalid #{event_name} event: First argument (gem_name) must be a string"
+          elsif args.size > 1 && !args[1..].all? { |arg| arg.is_a?(String) }
+            "Invalid #{event_name} event: Version requirements must be strings"
+          end
+        end
       end
     end
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: smart_todo
 version: !ruby/object:Gem::Version
-  version: 1.9.2
+  version: 1.11.0
 platform: ruby
 authors:
 - Shopify
 bindir: exe
 cert_chain: []
-date: 2025-03-31 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -121,6 +121,7 @@ files:
 - lib/smart_todo/slack_client.rb
 - lib/smart_todo/todo.rb
 - lib/smart_todo/version.rb
+- lib/smart_todo_comment_format_cop.rb
 - lib/smart_todo_cop.rb
 - service.yml
 - shipit.rubygems.yml
@@ -147,7 +148,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.6
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Enhance todo's comments in your codebase.
 test_files: []