octokitted 0.0.6 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f50897f06c435796e586cc57693cd25e312344890f209d463df1a967879b36e3
-  data.tar.gz: 7895d7418b7baaf86e33ac9cd457e3d80c9df0b16776cc4a23e9eec2183e02f2
+  metadata.gz: c7fe4c051e60f41068c020cd9c0fbfe3bae4d1cb673e22de5dc17c3b76e46ea9
+  data.tar.gz: b6c569962b05022e655a077f9f692c5d17a2bab406e29722188887dc7be248cc
 SHA512:
-  metadata.gz: 32fc230ed082aebecc9c20a046a19dee3f98d1863385506d8cd12b1be5ac86a40bed13a55cabcd561fd0b865db7d7509e34fd4ec34f31993e306812df415aa8c
-  data.tar.gz: 233c1748bfcba805594a9158ec56ef8197d4df432b8024fbf72756d38187b6e9d503e0bb68248b824760333f85e04dd9bf79ae40fead940bdba13d78055c951e
+  metadata.gz: b3a9add54171018622c44d309e6ac50435d3c225fe4795eb917c9812a3a567881210fa8f538b6b575eb00cb7bc7d2831da3899cfa9f29115ef30ce42fffa384f
+  data.tar.gz: 2cb81e5b5a4e078cfc7dec09202092c01c609a888ffc2c6e176390f45de1ebcdd3f4c9873378a90ccd33fddc4d4425493846af1288886ee2f1489a7e38432dbe

data/README.md

@@ -3,3 +3,11 @@
 [![test](https://github.com/GrantBirki/octokitted/actions/workflows/test.yml/badge.svg)](https://github.com/GrantBirki/octokitted/actions/workflows/test.yml) [![lint](https://github.com/GrantBirki/octokitted/actions/workflows/lint.yml/badge.svg)](https://github.com/GrantBirki/octokitted/actions/workflows/lint.yml) [![CodeQL](https://github.com/GrantBirki/octokitted/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/GrantBirki/octokitted/actions/workflows/codeql-analysis.yml)
 
 A self-hydrating version of Octokit for usage in CI systems - like GitHub Actions!
+
+> **kit** or **kitted** (_verb_)
+>
+> Defintion: provide someone or something with the appropriate clothing or equipment.
+>
+> "we were all kitted out in life jackets", "our octokit client was kitted out for CI usage"
+
+![octokitted](./docs/assets/dalle.png)

data/lib/octokitted/common/issue.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "contracts"
+
+class Issue
+  include Contracts::Core
+  include Contracts::Builtin
+
+  # A helper class for common operations on GitHub Issues
+  def initialize(octokitted)
+    @octokit = octokitted.octokit
+    @log = octokitted.log
+    @octokitted = octokitted
+  end
+
+  # Adds a set of labels to an issue or pull request
+  # :param labels: The labels to add to the issue (Array of strings)
+  # :param issue_number: The issue number to add labels to
+  Contract KeywordArgs[labels: ArrayOf[String], issue_number: Maybe[Numeric]] => Any
+  def add_labels(labels:, issue_number: nil)
+    issue_number = construct_issue_numer(issue_number)
+    @log.debug("adding labels: #{labels} to issue: #{issue_number}")
+
+    @octokit.add_labels_to_an_issue(@octokitted.org_and_repo, issue_number, labels)
+  end
+
+  # Removes a set of labels from an issue or pull request
+  # If the label does not exist, the exception is caught and logged
+  # :param labels: The labels to remove from the issue (Array of strings)
+  # :param issue_number: The issue number to remove labels from
+  Contract KeywordArgs[labels: ArrayOf[String], issue_number: Maybe[Numeric]] => Any
+  def remove_labels(labels:, issue_number: nil)
+    issue_number = construct_issue_numer(issue_number)
+    @log.debug("removing labels: #{labels} from issue: #{issue_number}")
+
+    labels.each do |label|
+      @octokit.remove_label(@octokitted.org_and_repo, issue_number, label)
+    rescue Octokit::NotFound
+      @log.warn("label: #{label} not found on issue: #{issue_number}")
+    end
+  end
+
+  # Adds a comment to an issue or pull request
+  # :param comment: The comment to add to the issue (String)
+  # :param issue_number: The issue number to add the comment to
+  Contract KeywordArgs[comment: String, issue_number: Maybe[Numeric]] => Any
+  def add_comment(comment:, issue_number: nil)
+    issue_number = construct_issue_numer(issue_number)
+    @log.debug("adding comment: #{comment} to issue: #{issue_number}")
+
+    @octokit.add_comment(@octokitted.org_and_repo, issue_number, comment)
+  end
+
+  # Closes an issue
+  # :param issue_number: The issue number to close
+  Contract KeywordArgs[issue_number: Maybe[Numeric], options: Maybe[Hash]] => Any
+  def close(issue_number: nil, options: {})
+    issue_number = construct_issue_numer(issue_number)
+    @log.debug("closing issue: #{issue_number}")
+
+    @octokit.close_issue(@octokitted.org_and_repo, issue_number, options)
+  end
+
+  private
+
+  # Helper method to construct the issue number from the auto-hydrated issue_number if it exists
+  # :param issue_number: The issue number to use if not nil
+  # :return: The issue number to use
+  # Note: If the issue_number is nil, we trye use the auto-hydrated issue_number...
+  # ... if the issue_number is not nil, we use that
+  Contract Maybe[Numeric] => Numeric
+  def construct_issue_numer(issue_number)
+    return @octokitted.issue_number if issue_number.nil?
+
+    return issue_number
+  end
+end

data/lib/octokitted.rb

@@ -5,34 +5,56 @@ require "logger"
 require "contracts"
 
 require_relative "octokitted/git_plugin"
+require_relative "octokitted/common/issue"
 
 class Octokitted
   # A Octokitted class to interact with the GitHub API
-  attr_reader :login, :org, :repo, :org_and_repo, :octokit, :cloned_repos
+  attr_reader :login,
+              :org,
+              :repo,
+              :org_and_repo,
+              :octokit,
+              :cloned_repos,
+              :log,
+              :github_event,
+              :sha,
+              :issue_number,
+              :issue
 
   include Contracts::Core
   include Contracts::Builtin
 
   # Initialize the class
+  # :param event_path: The path to the GitHub event data (defaults to the GITHUB_EVENT_PATH env var)
   # :param login: The login to use for GitHubAPI interactions (defaults to the owner of the token)
   # :param org: The org to use with the Octokitted class
   # :param repo: The repo to interact with with the Octokitted class
+  # :param issue_number: The issue/pull_request number to interact with with the Octokitted class
   # :param token: The token to use to authenticate with the GitHub API
   # :param logger: The logger to use for logging
-  def initialize(login: nil, org: nil, repo: nil, token: nil, logger: nil)
+  #
+  # Note: If you do not provide an org, repo, token, or issue_number, Octokitted will attempt to self-hydrate...
+  # ... these values from the environment and the GitHub event data when you call `.new` on the class
+  def initialize(event_path: nil, login: nil, org: nil, repo: nil, issue_number: nil, token: nil, logger: nil)
     @log = logger || setup_logger
     @cloned_repos = []
-    org_and_repo_hash = fetch_org_and_repo
+    @event_path = event_path || ENV.fetch("GITHUB_EVENT_PATH", nil)
+    @sha = ENV.fetch("GITHUB_SHA", nil)
+    org_and_repo_hash = fetch_org_and_repo(org, repo)
     @login = login
     @org = org || org_and_repo_hash[:org]
     @repo = repo || org_and_repo_hash[:repo]
     @token = token || fetch_token
     @octokit = setup_octokit_client
     @org_and_repo = org_and_repo_hash[:org_and_repo]
+    @github_event = fetch_github_event(@event_path)
+    @issue_number = issue_number || fetch_issue_number(@github_event)
     @login = @octokit.login if @login.nil? # reset the login to the owner of the token if not provided
 
     # setup the git plugin
     @git = GitPlugin.new(logger: @log, login: @login, token: @token)
+    # setup the common Issue plugin
+    @issue = Issue.new(self)
 
     @log.debug("Octokitted initialized")
     @log.debug("login: #{@octokit.login}")
@@ -115,8 +137,11 @@ class Octokitted
 
   # Fetch the org and repo from the environment
   # :return: A hash containing the org and repo, and the org and repo separately
-  Contract None => HashOf[Symbol, String]
-  def fetch_org_and_repo
+  Contract Maybe[String], Maybe[String] => Hash
+  def fetch_org_and_repo(org, repo)
+    # if org and repo are provided, and not nil, use them
+    return { org_and_repo: "#{org}/#{repo}", org:, repo: } if org && repo
+
     org_and_repo = ENV.fetch("GITHUB_REPOSITORY", nil)
     org = nil
     repo = nil
@@ -127,6 +152,38 @@ class Octokitted
     return { org_and_repo:, org:, repo: }
   end
 
+  # A helper method that attempts to self-hydrate context from the GitHub event data
+  # In Actions, the GITHUB_EVENT_PATH env var is set to a file containing the GitHub json event data
+  # If it exists, we try to load it into this class
+  # :param event_path: The path to the GitHub event data (defaults to the GITHUB_EVENT_PATH env var)
+  # :return: A Hash of the GitHub event data or nil if not found
+  Contract Maybe[String] => Maybe[Hash]
+  def fetch_github_event(event_path)
+    unless event_path
+      @log.warn("GITHUB_EVENT_PATH env var not found")
+      return nil
+    end
+
+    @log.info("GitHub Event data auto-hydrated")
+    return JSON.parse(File.read(event_path), symbolize_names: true)
+  end
+
+  # A helper method that attempts to self-hydrate the issue_number from the GitHub event data
+  # :param github_event: The GitHub event data (Hash)
+  # :return: The issue_number or nil if not found
+  Contract Maybe[Hash] => Maybe[Numeric]
+  def fetch_issue_number(github_event)
+    if github_event.nil?
+      @log.debug("GitHub event data not found - issue_number not auto-hydrated")
+      return nil
+    end
+
+    issue_number = (github_event[:issue] || github_event[:pull_request] || github_event)[:number]
+
+    @log.info("issue_number auto-hydrated - issue_number: #{issue_number}")
+    return issue_number
+  end
+
   # fetch the GitHub token from the environment
   # :return: The GitHub token or nil if not found
   Contract None => Maybe[String]

data/lib/version.rb

@@ -2,6 +2,6 @@
 
 module Octokitted
   module Version
-    VERSION = "0.0.6"
+    VERSION = "0.0.8"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: octokitted
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.8
 platform: ruby
 authors:
 - Grant Birkinbine
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-09-16 00:00:00.000000000 Z
+date: 2023-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: contracts
@@ -78,6 +78,7 @@ files:
 - LICENSE
 - README.md
 - lib/octokitted.rb
+- lib/octokitted/common/issue.rb
 - lib/octokitted/git_plugin.rb
 - lib/version.rb
 - octokitted.gemspec