Add issue_pin event to link TODOs with GitHub issues

couimet · claude · couimet · commit 236b2b0049ea · 2025-10-23T14:26:38.000-04:00
Introduces a new `issue_pin` event that allows developers to reference GitHub issues in TODO comments without requiring the issue to be closed. This enables capturing "notes to future self" and maintaining context between code and GitHub issues for tracking purposes.

Key features:
- Links `TODO`s directly to GitHub issues (org/repo/issue_number format)
- Always returns issue information regardless of state (open/closed)
- Shows issue title, state, and assignee when smart_todo runs
- Works without the `to:` parameter (no notifications required)
- Optional `to:` parameter still supported for email notifications
- Uses existing GitHub authentication infrastructure

The event name `issue_pin` was chosen to convey the concept of pinning a note or reminder to an issue, similar to a sticky note.

Unlike `issue_close` which only triggers when an issue is closed, `issue_pin` always displays the current issue status, making it perfect for tracking work items and maintaining links between implementation decisions and their corresponding GitHub issues.

Implementation includes comprehensive test coverage and RuboCop cop updates to allow the event to work without assignees.

🤖 Generated with Claude Code
Co-Authored-By: Claude &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -40,6 +40,16 @@ When the TODO's event is met (i.e. a certain date is reached), the TODO's assign
   end
 ```
 
+**Pin TODOs to GitHub Issues**
+```ruby
+  # TODO(on: issue_pin('shopify', 'smart_todo', '123'))
+  #   Remember to handle the edge cases discussed in the issue
+  def process_order
+  end
+```
+
+The `issue_pin` event allows you to link TODO comments to GitHub issues without requiring the issue to be closed. This is perfect for tracking work items and maintaining context between your code and GitHub issues.
+
 Documentation
 ----------------
 Please check out the GitHub [wiki](https://github.com/Shopify/smart_todo/wiki) for documentation and example on how to setup SmartTodo in your project.
diff --git a/lib/smart_todo/events.rb b/lib/smart_todo/events.rb
@@ -132,6 +132,35 @@ def issue_close(organization, repo, issue_number)
       end
     end
 
+    # Pin a TODO to a GitHub issue for tracking purposes
+    # Unlike issue_close, this will always return issue information regardless of state
+    #
+    # @param organization [String] the GitHub organization name
+    # @param repo [String] the GitHub repo name
+    # @param issue_number [String, Integer]
+    # @return [String] Always returns a message with issue information
+    def issue_pin(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
+        <<~EOM
+          I can't retrieve the information from the issue *#{issue_number}* in the *#{organization}/#{repo}* repository.
+
+          If the repository is a private one, make sure to export the `#{GITHUB_TOKEN}`
+          environment variable with a correct GitHub token.
+        EOM
+      else
+        issue = JSON.parse(response.body)
+        state = issue["state"]
+        title = issue["title"]
+        assignee = issue["assignee"] ? "@#{issue["assignee"]["login"]}" : "unassigned"
+
+        "📌 Pinned to issue ##{issue_number}: \"#{title}\" [#{state}] (#{assignee}) - " \
+          "https://github.com/#{organization}/#{repo}/issues/#{issue_number}"
+      end
+    end
+
     # Check if the pull request +pr_number+ is closed
     #
     # @param organization [String] the GitHub organization name
diff --git a/lib/smart_todo_cop.rb b/lib/smart_todo_cop.rb
@@ -53,9 +53,15 @@ def metadata(comment)
         # @param metadata [SmartTodo::Parser::Visitor]
         # @return [true, false]
         def smart_todo?(metadata)
-          metadata.events.any? &&
-            metadata.events.all? { |event| event.is_a?(::SmartTodo::Todo::CallNode) } &&
-            metadata.assignees.any?
+          has_valid_events = metadata.events.any? &&
+            metadata.events.all? { |event| event.is_a?(::SmartTodo::Todo::CallNode) }
+
+          # Allow issue_pin without assignees (to: parameter)
+          if has_valid_events && metadata.events.any? { |e| e.method_name == :issue_pin }
+            true
+          else
+            has_valid_events && metadata.assignees.any?
+          end
         end
 
         # @param assignees [Array]
@@ -97,6 +103,12 @@ 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_issue_pin_args(args)
+          validate_fixed_arity_args(args, 3, "issue_pin", ["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)
diff --git a/test/smart_todo/events/issue_pin_test.rb b/test/smart_todo/events/issue_pin_test.rb
@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+module SmartTodo
+  class Events
+    class IssuePinTest < Minitest::Test
+      def test_when_issue_is_open
+        stub_request(:get, /api.github.com/)
+          .to_return(body: JSON.dump(
+            state: "open",
+            title: "Add support for caching",
+            number: 123,
+            assignee: { login: "johndoe" },
+          ))
+
+        expected = "📌 Pinned to issue #123: \"Add support for caching\" [open] (@johndoe) - " \
+          "https://github.com/rails/rails/issues/123"
+
+        assert_equal(expected, issue_pin("rails", "rails", "123"))
+      end
+
+      def test_when_issue_is_closed
+        stub_request(:get, /api.github.com/)
+          .to_return(body: JSON.dump(
+            state: "closed",
+            title: "Fix memory leak",
+            number: 456,
+            assignee: { login: "janedoe" },
+          ))
+
+        expected = "📌 Pinned to issue #456: \"Fix memory leak\" [closed] (@janedoe) - " \
+          "https://github.com/shopify/smart_todo/issues/456"
+
+        assert_equal(expected, issue_pin("shopify", "smart_todo", "456"))
+      end
+
+      def test_when_issue_has_no_assignee
+        stub_request(:get, /api.github.com/)
+          .to_return(body: JSON.dump(
+            state: "open",
+            title: "Improve documentation",
+            number: 789,
+            assignee: nil,
+          ))
+
+        expected = "📌 Pinned to issue #789: \"Improve documentation\" [open] (unassigned) - " \
+          "https://github.com/org/repo/issues/789"
+
+        assert_equal(expected, issue_pin("org", "repo", "789"))
+      end
+
+      def test_when_issue_does_not_exist
+        stub_request(:get, /api.github.com/)
+          .to_return(status: 404)
+
+        expected = <<~EOM
+          I can't retrieve the information from the issue *999* in the *rails/rails* repository.
+
+          If the repository is a private one, make sure to export the `#{GITHUB_TOKEN}`
+          environment variable with a correct GitHub token.
+        EOM
+
+        assert_equal(expected, issue_pin("rails", "rails", "999"))
+      end
+
+      def test_when_token_env_is_not_present
+        stub_request(:get, /api.github.com/)
+          .to_return(body: JSON.dump(
+            state: "open",
+            title: "Test issue",
+            number: 1,
+            assignee: nil,
+          ))
+
+        result = issue_pin("rails", "rails", "1")
+        assert(result.include?("📌 Pinned to issue #1"))
+
+        assert_requested(:get, /api.github.com/) do |request|
+          assert(!request.headers.key?("Authorization"))
+        end
+      end
+
+      def test_when_token_env_is_present
+        ENV[GITHUB_TOKEN] = "abc123"
+
+        stub_request(:get, /api.github.com/)
+          .to_return(body: JSON.dump(
+            state: "open",
+            title: "Test issue",
+            number: 2,
+            assignee: nil,
+          ))
+
+        result = issue_pin("rails", "rails", "2")
+        assert(result.include?("📌 Pinned to issue #2"))
+
+        assert_requested(:get, /api.github.com/) do |request|
+          assert_equal("token abc123", request.headers["Authorization"])
+        end
+      ensure
+        ENV.delete(GITHUB_TOKEN)
+      end
+
+      def test_when_organization_specific_token_is_present
+        ENV["#{GITHUB_TOKEN}__RAILS"] = "rails_token"
+
+        stub_request(:get, /api.github.com/)
+          .to_return(body: JSON.dump(
+            state: "open",
+            title: "Test issue",
+            number: 3,
+            assignee: nil,
+          ))
+
+        result = issue_pin("rails", "rails", "3")
+        assert(result.include?("📌 Pinned to issue #3"))
+
+        assert_requested(:get, /api.github.com/) do |request|
+          assert_equal("token rails_token", request.headers["Authorization"])
+        end
+      ensure
+        ENV.delete("#{GITHUB_TOKEN}__RAILS")
+      end
+
+      def test_when_repo_specific_token_is_present
+        ENV["#{GITHUB_TOKEN}__RAILS__RAILS"] = "rails_rails_token"
+
+        stub_request(:get, /api.github.com/)
+          .to_return(body: JSON.dump(
+            state: "open",
+            title: "Test issue",
+            number: 4,
+            assignee: nil,
+          ))
+
+        result = issue_pin("rails", "rails", "4")
+        assert(result.include?("📌 Pinned to issue #4"))
+
+        assert_requested(:get, /api.github.com/) do |request|
+          assert_equal("token rails_rails_token", request.headers["Authorization"])
+        end
+      ensure
+        ENV.delete("#{GITHUB_TOKEN}__RAILS__RAILS")
+      end
+
+      private
+
+      def issue_pin(*args)
+        Events.new.issue_pin(*args)
+      end
+    end
+  end
+end
diff --git a/test/smart_todo/integration_test.rb b/test/smart_todo/integration_test.rb
@@ -104,6 +104,62 @@ def hello
       )
     end
 
+    def test_outputs_issue_pin_information_without_sending_notification
+      ruby_code = <<~EOM
+        # TODO(on: issue_pin('shopify', 'smart_todo', '123'))
+        #   Remember to update the caching strategy
+        def hello
+        end
+      EOM
+
+      stub_request(:get, /api.github.com/)
+        .to_return(body: JSON.dump(
+          state: "open",
+          title: "Improve caching",
+          number: 123,
+          assignee: { login: "developer" },
+        ))
+
+      generate_ruby_file(ruby_code) do |file|
+        # Run CLI with output dispatcher to see results
+        output = capture_subprocess_io do
+          CLI.new.run([file.path, "--dispatcher", "output"])
+        end.join
+
+        # Check that the issue information is in the output
+        assert_match(/📌 Pinned to issue #123/, output)
+        assert_match(/Improve caching/, output)
+      end
+    end
+
+    def test_sends_notification_when_issue_pin_has_assignee
+      ruby_code = <<~EOM
+        # TODO(on: issue_pin('shopify', 'smart_todo', '456'), to: 'team@example.com')
+        #   Don't forget about the refactoring
+        def hello
+        end
+      EOM
+
+      stub_request(:get, /api.github.com/)
+        .to_return(body: JSON.dump(
+          state: "closed",
+          title: "Refactor authentication",
+          number: 456,
+          assignee: nil,
+        ))
+
+      generate_ruby_file(ruby_code) do |file|
+        run_cli(file)
+      end
+
+      assert_slack_message_sent(
+        "Hello :wave:,",
+        "📌 Pinned to issue #456",
+        "Refactor authentication",
+        "Don't forget about the refactoring",
+      )
+    end
+
     private
 
     def assert_slack_message_sent(*messages)
diff --git a/test/smart_todo/smart_todo_cop_test.rb b/test/smart_todo/smart_todo_cop_test.rb
@@ -149,6 +149,42 @@ def hello
       RUBY
     end
 
+    def test_does_not_add_offense_when_using_issue_pin_without_to_parameter
+      expect_no_offense(<<~RUBY)
+        # TODO(on: issue_pin('shopify', 'smart_todo', '123'))
+        #   Remember to handle the edge cases
+        def hello
+        end
+      RUBY
+    end
+
+    def test_does_not_add_offense_when_using_issue_pin_with_to_parameter
+      expect_no_offense(<<~RUBY)
+        # TODO(on: issue_pin('shopify', 'smart_todo', '456'), to: 'team@example.com')
+        #   Update the documentation
+        def hello
+        end
+      RUBY
+    end
+
+    def test_adds_offense_when_issue_pin_has_wrong_number_of_arguments
+      expect_offense(<<~RUBY)
+        # TODO(on: issue_pin('shopify', 'smart_todo'))
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SmartTodo/SmartTodoCop: Invalid issue_pin event: Expected 3 arguments (organization, repo, issue_number), got 2. For more info please look at https://github.com/Shopify/smart_todo/wiki/Syntax
+        def hello
+        end
+      RUBY
+    end
+
+    def test_adds_offense_when_issue_pin_has_non_string_arguments
+      expect_offense(<<~RUBY)
+        # TODO(on: issue_pin('shopify', 'smart_todo', 123))
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SmartTodo/SmartTodoCop: Invalid issue_pin event: Arguments must be strings. For more info please look at https://github.com/Shopify/smart_todo/wiki/Syntax
+        def hello
+        end
+      RUBY
+    end
+
     def test_does_not_add_offense_when_comment_is_not_a_todo
       expect_no_offense(<<~RUBY)
         # @return [Void]
