octokitted 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f1a1eec4292305ffb36ee14107f171a44eb4c4ec36b681ac1cbb43239fee2ca
-  data.tar.gz: f11e7f4e512223b975247f83720d6d9a465f5126e70e8928007c8be2e01fb350
+  metadata.gz: 930bcddc8ee154391c8deb09e7a2c0e483e49d6cb3091adeb70239d0388d3e5d
+  data.tar.gz: b64e1ba7b33e4c2eeb73975825bf5fa7cd2eaf37f63383b01427e4adddbd7e4a
 SHA512:
-  metadata.gz: 520b1c0f16cb7ff369e287eeebeb8c27efbca078ca31fc16825682dd4bc4cd30594532c63eaf76787af5245092fa5a092a7c71f1e0faa07ea1efc48503ec973a
-  data.tar.gz: f2b6bf07d1a3463b960daaa02aded2db981bb0640affb5b87afc78a3c7726040f907e915bb3e3c2796c404b35ec9c3d08c666e6347c8ba54dde612eaa7ec3014
+  metadata.gz: c2738d3e5a2bb9bb665a8ed84f76ecbe4594b753e46b27a49d504587fbceae86f4a5905bd704368373bf4868551fe5a014716555e274f22fcad95b8d29eb107c
+  data.tar.gz: 486cf3f74dc41658968876d79d11383c1d8bfe7577f822c4fe17660555e96f4fa5480f180acd86bd140cbd8af7c972ad4068bb74436a8d2127238ba56141afb9

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/git_plugin.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
 require "git"
+require "contracts"
 
 class GitPlugin
   attr_reader :login
 
+  include Contracts::Core
+  include Contracts::Builtin
+
   # Initialize the class
+  Contract KeywordArgs[logger: Any, login: Maybe[String], token: Maybe[String]] => Any
   def initialize(logger:, login:, token:)
     @log = logger
     @login = login
@@ -14,25 +19,32 @@ class GitPlugin
 
   # Removes / cleans up all repos that this class has cloned
   # :param cloned_repos: An array of paths to cloned repos to remove
+  # :return: true to indicate success
+  Contract ArrayOf[String] => true
   def remove_all_clones!(cloned_repos)
     @log.debug("removing all cloned repos")
     cloned_repos.each do |path|
       @log.debug("removing cloned repo: #{path}")
       FileUtils.rm_r(path)
     end
+    true
   end
 
   # Removes a single cloned repo
   # :param path: The path to the cloned repo to remove (String)
+  # :return: true to indicate success
+  Contract String => true
   def remove_clone!(path)
     @log.debug("removing cloned repo: #{path}")
     FileUtils.rm_r(path)
+    return true
   end
 
   # Clone a repository
   # :param path: The relative path to clone the repo to - (default: ".")
   # :param options: The options to pass to the Git.clone method (default: {} - https://rubydoc.info/gems/git/Git#clone-class_method)
   # :return: Hash of the Git Object, and the path to the cloned repo
+  Contract KeywordArgs[org: String, repo: String, path: Maybe[String], options: Maybe[Hash]] => Hash
   def clone(org:, repo:, path: ".", options: {})
     @log.debug("cloning #{org}/#{repo}")
     git_object = Git.clone("https://#{@token}@github.com/#{org}/#{repo}.git", repo, path:, log: @log, **options)

data/lib/octokitted.rb

@@ -2,33 +2,59 @@
 
 require "octokit"
 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 = []
+    @event_path = event_path || ENV.fetch("GITHUB_EVENT_PATH", nil)
+    @sha = ENV.fetch("GITHUB_SHA", nil)
     org_and_repo_hash = fetch_org_and_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
-    @log = logger || setup_logger
     @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}")
@@ -38,8 +64,9 @@ class Octokitted
 
   # Setter method for the repo instance variable
   # :param repo: The repo to set
-  # :return: the new org/repo
+  # :return: it does not return as it is a setter method
   # Example: gh.repo = "test"
+  Contract String => Any
   def repo=(repo)
     @repo = repo
     @org_and_repo = "#{@org}/#{@repo}"
@@ -48,8 +75,9 @@ class Octokitted
 
   # Setter method for the org instance variable
   # :param org: The org to set
-  # :return: the new org/repo
+  # :return: it does not return as it is a setter method
   # Example: gh.org = "test"
+  Contract String => Any
   def org=(org)
     @org = org
     @org_and_repo = "#{@org}/#{@repo}"
@@ -60,12 +88,17 @@ class Octokitted
   # :param path: The relative path to clone the repo to - (default: ".")
   # :param options: The options to pass (default: {} - https://rubydoc.info/gems/git/Git#clone-class_method)
   # :return: The Git object to operate with
+  Contract Maybe[String], Maybe[Hash] => Git::Base
   def clone(path: ".", options: {})
     result = @git.clone(org: @org, repo: @repo, path:, options:)
     @cloned_repos << result[:path]
     return result[:git_object]
   end
 
+  # Remove a cloned repository
+  # :param path: The relative path to the cloned repo to remove (String)
+  # :return: true to indicate success
+  Contract String => true
   def remove_clone!(path)
     valid = false
 
@@ -82,11 +115,16 @@ class Octokitted
 
     @git.remove_clone!(path)
     @cloned_repos.delete(path)
+    true
   end
 
+  # Remove all cloned repositories that have been cloned with this instance of Octokitted
+  # :return: true to indicate success
+  Contract None => true
   def remove_all_clones!
     @git.remove_all_clones!(@cloned_repos)
     @cloned_repos = []
+    true
   end
 
   private
@@ -99,6 +137,7 @@ 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
     org_and_repo = ENV.fetch("GITHUB_REPOSITORY", nil)
     org = nil
@@ -110,8 +149,41 @@ 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
+  # :return: The GitHub token or nil if not found
+  Contract None => Maybe[String]
   def fetch_token
     # first try to use the OCTOKIT_ACCESS_TOKEN env var if it exists
     token = ENV.fetch("OCTOKIT_ACCESS_TOKEN", nil) # if running in actions
@@ -121,7 +193,10 @@ class Octokitted
     token = ENV.fetch("GITHUB_TOKEN", nil) # if running in actions
     return token unless token.nil?
 
-    raise "No GitHub token found"
+    # if we get here, we don't have a token - this is okay because we can still do some things...
+    # ... without a token, rate limiting can be an issue
+    @log.warn("No GitHub token found")
+    return nil
   end
 
   # Setup an Octokit client

data/lib/version.rb

@@ -2,6 +2,6 @@
 
 module Octokitted
   module Version
-    VERSION = "0.0.5"
+    VERSION = "0.0.7"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: octokitted
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.7
 platform: ruby
 authors:
 - Grant Birkinbine
@@ -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