ghx 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54d0617ded0141f352b6e27b38245f8d269546093d328ffa8428cef0cc45ae0f
-  data.tar.gz: 52bd1ef5a4c214203938a1dbbadf487ac49c5fc398ccc17045ec2c400425ff80
+  metadata.gz: 2b80c109f50e1c94cc2aa0bd727a2dbe547b66080380a2847132bc7cda0b34b8
+  data.tar.gz: 179db655ee4d499eb53912cc3a09ebc7ff5c9100d650b4ef6567ce2a8ff9acb7
 SHA512:
-  metadata.gz: 14df558d839c2efb46d68b78482b30c7c6b26ba86be9c1c38a6e4d22202678f5e19f1a2f4a56f713060ba216523c75b2ee57945e590e10407059c5c9ce1a3382
-  data.tar.gz: 14c21c92397ade112c51e2bef0253bcd5d61a28a5b28b776c699fb0b8c6af392d9e611c03bb0aaa1575bf1ec075e7b337f2e717fe9dd4a85cb0995280f3d7932
+  metadata.gz: 22bbefe3f68291efca16223b120575cf64997a9f2f07cc09963f0454314c423933d4cbbaf4b5c26b267d292e560114ca71e6f8faf08e7ad84e016c70229edd3e
+  data.tar.gz: 1082fc4c645cf94a660305ef1e0f7fdaff8c06ebd7bab58ac74d8acead82cb01cf12c8608681f8019b83ad79e479d602fab0f073270dc4d82017d997ae11f18e

data/lib/ghx/dependabot/alert.rb

@@ -115,9 +115,11 @@
 
 module GHX
   module Dependabot
+    # A Dependabot Alert
     class Alert
       attr_reader :number, :state, :dependency, :security_advisory, :security_vulnerability, :url, :html_url, :created_at, :updated_at
 
+      # @param json_data [Hash] The JSON data for the alert, from the API
       def initialize(json_data)
         @number = json_data["number"]
         @state = json_data["state"]

data/lib/ghx/dependabot/package.rb

@@ -1,5 +1,6 @@
 module GHX
   module Dependabot
+    # A package is a dependency that is managed by a package manager. Referenced by a SecurityVulnerability.
     class Package
       attr_reader :ecosystem, :name
 

data/lib/ghx/dependabot/security_vulnerability.rb

@@ -1,5 +1,6 @@
 module GHX
   module Dependabot
+    # A SecurityVulnerability is referenced by an Alert
     class SecurityVulnerability
       attr_reader :package, :severity, :vulnerable_version_range, :first_patched_version
 

data/lib/ghx/dependabot.rb

@@ -1,6 +1,15 @@
 module GHX
+  # Module for Dependabot-related classes and methods
   module Dependabot
+    # Get Dependabot alerts for a given repository
+    #
+    # @note ONLY RETURNS THE FIRST 100 ALERTS
+    # @param owner [String] the owner of the repository
+    # @param repo [String] the repository name
+    # @return [Array<GHX::Dependabot::Alert>] the alerts
     def self.get_alerts(owner:, repo:)
+      # TODO: Add pagination to get all alerts in one go
+
       GHX.rest_client.get("repos/#{owner}/#{repo}/dependabot/alerts?state=open&per_page=100").map do |alert|
         GHX::Dependabot::Alert.new(alert)
       end

data/lib/ghx/errors.rb

@@ -0,0 +1,7 @@
+module GHX
+  class GHXError < StandardError; end
+
+  class RateLimitExceededError < GHXError; end
+
+  class OtherApiError < GHXError; end
+end

data/lib/ghx/graphql_client.rb

@@ -1,9 +1,14 @@
 module GHX
+  # Internal class to interact with the GitHub GraphQL API
   class GraphqlClient
+    # @param api_key [String]
     def initialize(api_key)
       @api_key = api_key
     end
 
+    # Perform a GraphQL Query and return the result
+    # @param query [String] GraphQL Query
+    # @return [Net::HTTPResponse]
     def query(query)
       uri = URI("https://api.github.com/graphql")
       req = Net::HTTP::Post.new(uri)
@@ -15,54 +20,5 @@ module GHX
         http.request(req)
       end
     end
-
-    # @param [String] project_id
-    # @param [GithubProjectItem] project_item
-    # @param [DateTime] reported_at
-    def update_project_item_reported_at(project_item_id:, reported_at:, project_id: GithubProject::MAIN_GH_PROJECT_ID)
-      field_id = "PVTF_lADOALH_aM4Ac-_zzgSzAZs" # project_item.field_map["Reported At"]
-
-      gql_query = <<~GQL
-        mutation {
-          updateProjectV2ItemFieldValue(input: {
-            fieldId: "#{field_id}",
-            itemId: "#{project_item_id}",
-            projectId: "#{project_id}",
-            value: { 
-              date: "#{reported_at.to_date}"
-            }
-          }) {
-            projectV2Item {
-              id  
-            }
-          }
-        }
-      GQL
-
-      query(gql_query)
-    end
-
-    def update_project_item_reported_by(project_item_id:, reported_by:, project_id: GithubProject::MAIN_GH_PROJECT_ID)
-      field_id = "PVTF_lADOALH_aM4Ac-_zzgSzBcc" # project_item.field_map["Reporter"]
-
-      gql_query = <<~GQL
-        mutation {
-          updateProjectV2ItemFieldValue(input: {
-            fieldId: "#{field_id}",
-            itemId: "#{project_item_id}",
-            projectId: "#{project_id}",
-            value: { 
-              text: "#{reported_by}"
-            }
-          }) {
-            projectV2Item {
-              id  
-            }
-          }
-        }
-      GQL
-
-      query(gql_query)
-    end
   end
 end

data/lib/ghx/issue.rb

@@ -1,29 +1,45 @@
 module GHX
+  # A GitHub Issue
   class Issue
     attr_accessor :owner, :repo, :number, :title, :body, :state, :state_reason, :author, :assignees, :labels, :milestone, :created_at, :updated_at, :closed_at
 
+    # Search for issues in a repository
+    # @param owner [String] the owner of the repository
+    # @param repo [String] the repository name
+    # @param query [String] the search query, using GitHub's search syntax
+    # @return [Array<Issue>] the issues found
     def self.search(owner:, repo:, query:)
       data = GHX.rest_client.get("search/issues?q=#{URI.encode_www_form_component(query)}+is:issue+repo:#{owner}/#{repo}")
       data.fetch("items").to_a.map do |issue_data|
         new(owner: owner, repo: repo, **issue_data)
       end
-    rescue => e
-      GHX.logger.error "Error searching for issues with query: #{e.message}"
-      GHX.logger.error "Received data: #{data}"
-      []
     end
 
+    # Find an issue by its number
+    # @param owner [String] the owner of the repository
+    # @param repo [String] the repository name
+    # @param number [Integer] the issue number
+    # @return [Issue] the issue found
     def self.find(owner:, repo:, number:)
       response_data = GHX.rest_client.get("repos/#{owner}/#{repo}/issues/#{number}")
       new(owner: owner, repo: repo, **response_data)
     end
 
+    # @param owner [String] the owner of the repository
+    # @param repo [String] the repository name
+    # @param **args [Hash] the attributes of the issue you wish to assign
+    # @return [Issue] the new issue
     def initialize(owner:, repo:, **args)
       @owner = owner
       @repo = repo
       update_attributes(args)
     end
 
+    # Save the issue to GitHub. Handles both creating and updating.
+    #
+    # If the issue has a number, it will be updated. Otherwise, it will be created.
+    #
+    # @return [Issue] the saved issue
     def save
       @number.nil? ? create : update
     end

data/lib/ghx/project_item.rb

@@ -1,7 +1,14 @@
 module GHX
+  # A GitHub Project Item. This is a single item in a GitHub Project Board.
+  #
+  # ProjectsV2 are only available via the GraphQL API. This class wraps access to the API and provides a more OO interface.
+  #
+  # @note Access to ProjectItems should be done largely (if not always) through the Project class.
   class ProjectItem
     attr_accessor :id, :project_id, :issue_number, :issue_title, :issue_url, :issue_state, :field_values, :field_map
 
+    # @param field_configuration [Array<Hash>] An array of field configurations. These are the fields that are available to the Project Item. These are provided via the Project itself. It's much easier to access ProjectItems through the project because of this.
+    # @param data [Hash] The data from the GraphQL API.
     def initialize(field_configuration:, data:)
       _setup_field_configuration(field_configuration)
 
@@ -33,7 +40,11 @@ module GHX
       end
     end
 
-    # Updates the given fields to the given values. Makes a GraphQL call per field to do the update.
+    # Updates the given fields to the given values. Makes a GraphQL call *per field* to do the update.
+    #
+    # The implementation wraps access to the various types for each field. Since GraphQL requires us to type match on all
+    # requests, this gives us convenience, especially for things like a select field. We can pass in the value, and the
+    # method will find the ID of the option and update the field for us.
     #
     # @param fields [Hash] A hash of field names to values.
     def update(**fields)
@@ -138,23 +149,27 @@ module GHX
 
     private
 
+    # Parse the field_configuration and set up the instance variables and accessors.
+    #
+    # Example field_configuration:
+    # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCno", :name=>"Title", :data_type=>"TITLE", :options=>nil}
+    # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCns", :name=>"Assignees", :data_type=>"ASSIGNEES", :options=>nil}
+    # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSzAZs", :name=>"Reported At", :data_type=>"DATE", :options=>nil}
+    # {:id=>"PVTSSF_lADOALH_aM4Ac-_zzgSxCnw", :name=>"Status", :data_type=>"SINGLE_SELECT", :options=>[{:id=>"f971fb55", :name=>"To triage"}, {:id=>"856cdede", :name=>"Ready to Assign"}, {:id=>"f75ad846", :name=>"Assigned"}, {:id=>"47fc9ee4", :name=>"Fix In progress"}, {:id=>"5ef0dc97", :name=>"Additional Info Requested"}, {:id=>"98236657", :name=>"Done - Fixed"}, {:id=>"98aea6ad", :name=>"Done - Won't Fix"}, {:id=>"a3b4fc3a", :name=>"Duplicate"}, {:id=>"81377549", :name=>"Not a Vulnerability"}]}
+    # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCn0", :name=>"Labels", :data_type=>"LABELS", :options=>nil}
+    # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCn4", :name=>"Linked pull requests", :data_type=>"LINKED_PULL_REQUESTS", :options=>nil}
+    # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCn8", :name=>"Milestone", :data_type=>"MILESTONE", :options=>nil}
+    # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCoA", :name=>"Repository", :data_type=>"REPOSITORY", :options=>nil}
+    # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCoM", :name=>"Reviewers", :data_type=>"REVIEWERS", :options=>nil}
+    # {:id=>"PVTSSF_lADOALH_aM4Ac-_zzgSxCuA", :name=>"Severity", :data_type=>"SINGLE_SELECT", :options=>[{:id=>"79628723", :name=>"Informational"}, {:id=>"153889c6", :name=>"Low"}, {:id=>"093709ee", :name=>"Medium"}, {:id=>"5a00bbe7", :name=>"High"}, {:id=>"00e0bbaf", :name=>"Critical"}, {:id=>"fd986bd9", :name=>"Duplicate"}]}
+    # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSzBcc", :name=>"Reporter", :data_type=>"TEXT", :options=>nil}
+    # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSzBho", :name=>"Resolve By", :data_type=>"DATE", :options=>nil}
+    # {:id=>"PVTSSF_lADOALH_aM4Ac-_zzgTKjOw", :name=>"Payout Status", :data_type=>"SINGLE_SELECT", :options=>[{:id=>"53c47c02", :name=>"Ready for Invoice"}, {:id=>"0b8a4629", :name=>"Payout in Process"}, {:id=>"5f356a58", :name=>"Payout Complete"}, {:id=>"368048ac", :name=>"Ineligible for Payout"}]}
+    #
+    #
     def _setup_field_configuration(field_configuration)
       @field_configuration = field_configuration.map { |fc| fc.merge({normalized_name: normalized_field_value_name(fc[:name])}) }
 
-      # Example field_configuration:
-      # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCno", :name=>"Title", :data_type=>"TITLE", :options=>nil}
-      # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCns", :name=>"Assignees", :data_type=>"ASSIGNEES", :options=>nil}
-      # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSzAZs", :name=>"Reported At", :data_type=>"DATE", :options=>nil}
-      # {:id=>"PVTSSF_lADOALH_aM4Ac-_zzgSxCnw", :name=>"Status", :data_type=>"SINGLE_SELECT", :options=>[{:id=>"f971fb55", :name=>"To triage"}, {:id=>"856cdede", :name=>"Ready to Assign"}, {:id=>"f75ad846", :name=>"Assigned"}, {:id=>"47fc9ee4", :name=>"Fix In progress"}, {:id=>"5ef0dc97", :name=>"Additional Info Requested"}, {:id=>"98236657", :name=>"Done - Fixed"}, {:id=>"98aea6ad", :name=>"Done - Won't Fix"}, {:id=>"a3b4fc3a", :name=>"Duplicate"}, {:id=>"81377549", :name=>"Not a Vulnerability"}]}
-      # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCn0", :name=>"Labels", :data_type=>"LABELS", :options=>nil}
-      # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCn4", :name=>"Linked pull requests", :data_type=>"LINKED_PULL_REQUESTS", :options=>nil}
-      # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCn8", :name=>"Milestone", :data_type=>"MILESTONE", :options=>nil}
-      # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCoA", :name=>"Repository", :data_type=>"REPOSITORY", :options=>nil}
-      # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSxCoM", :name=>"Reviewers", :data_type=>"REVIEWERS", :options=>nil}
-      # {:id=>"PVTSSF_lADOALH_aM4Ac-_zzgSxCuA", :name=>"Severity", :data_type=>"SINGLE_SELECT", :options=>[{:id=>"79628723", :name=>"Informational"}, {:id=>"153889c6", :name=>"Low"}, {:id=>"093709ee", :name=>"Medium"}, {:id=>"5a00bbe7", :name=>"High"}, {:id=>"00e0bbaf", :name=>"Critical"}, {:id=>"fd986bd9", :name=>"Duplicate"}]}
-      # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSzBcc", :name=>"Reporter", :data_type=>"TEXT", :options=>nil}
-      # {:id=>"PVTF_lADOALH_aM4Ac-_zzgSzBho", :name=>"Resolve By", :data_type=>"DATE", :options=>nil}
-      # {:id=>"PVTSSF_lADOALH_aM4Ac-_zzgTKjOw", :name=>"Payout Status", :data_type=>"SINGLE_SELECT", :options=>[{:id=>"53c47c02", :name=>"Ready for Invoice"}, {:id=>"0b8a4629", :name=>"Payout in Process"}, {:id=>"5f356a58", :name=>"Payout Complete"}, {:id=>"368048ac", :name=>"Ineligible for Payout"}]}
       @field_configuration.each do |field|
         next unless field[:name]
         next if field[:name].to_s.empty?

data/lib/ghx/rest_client.rb

@@ -1,57 +1,62 @@
 require "net/http"
 
 module GHX
+  # RestClient is a simple wrapper around Net::HTTP to make it easier to make API calls to the GitHub REST API.
+  #
+  # This is necessary because not all GitHub API endpoints are covered by Octokit.
   class RestClient
     attr_reader :api_key
 
+    # @param api_key [String] the GitHub API key
     def initialize(api_key)
       @api_key = api_key
     end
 
-    # @return [Hash] the JSON response
+    # Make a GET request to the given path
+    # @param path [String] the path to the API endpoint
+    # @return [Hash] the parsed JSON response
     def get(path)
       uri = URI.parse("https://api.github.com/#{path}")
       request = Net::HTTP::Get.new(uri)
-      request["Accept"] = "application/vnd.github+json"
-      request["Authorization"] = "Bearer #{@api_key}"
-      request["X-Github-Api-Version"] = "2022-11-28"
-
-      req_options = {
-        use_ssl: uri.scheme == "https"
-      }
 
-      response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
-        http.request(request)
-      end
+      response = _http_request(uri: uri, request: request)
 
       JSON.parse(response.body)
     end
 
-    # @return [Hash] the JSON response
+    # Make a POST request to the given path with the given params
+    # @param path [String] the path to the API endpoint
+    # @param params [Hash] the request body
+    # @return [Hash] the parsed JSON response
     def post(path, params)
       uri = URI.parse("https://api.github.com/#{path}")
       request = Net::HTTP::Post.new(uri)
-      request["Accept"] = "application/vnd.github+json"
-      request["Authorization"] = "Bearer #{@api_key}"
-      request["X-Github-Api-Version"] = "2022-11-28"
-
-      req_options = {
-        use_ssl: uri.scheme == "https"
-      }
 
       request.body = params.to_json
 
-      response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
-        http.request(request)
-      end
+      response = _http_request(uri: uri, request: request)
 
       JSON.parse(response.body)
     end
 
-    # @return [Hash] the JSON response
+    # Make a PATCH request to the given path with the given params
+    # @param path [String] the path to the API endpoint
+    # @param params [Hash] the request body
+    # @return [Hash] the parsed JSON response
     def patch(path, params)
       uri = URI.parse("https://api.github.com/#{path}")
       request = Net::HTTP::Patch.new(uri)
+
+      request.body = params.to_json
+
+      response = _http_request(uri: uri, request: request)
+
+      JSON.parse(response.body)
+    end
+
+    private
+
+    def _http_request(uri:, request:)
       request["Accept"] = "application/vnd.github+json"
       request["Authorization"] = "Bearer #{@api_key}"
       request["X-Github-Api-Version"] = "2022-11-28"
@@ -60,13 +65,22 @@ module GHX
         use_ssl: uri.scheme == "https"
       }
 
-      request.body = params.to_json
-
       response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
         http.request(request)
       end
 
-      JSON.parse(response.body)
+      if response.code.to_i < 400
+        response
+      elsif [403, 429].include?(response.code.to_i)
+        if response["X-RateLimit-Remaining"].to_i == 0
+          reset_time = Time.at(response["X-RateLimit-Reset"].to_i)
+          raise GHX::RateLimitExceededError, "GitHub API rate limit exceeded. Try again after #{reset_time}"
+        else
+          raise GHX::RateLimitExceededError, "GitHub API rate limit exceeded. Try again later."
+        end
+      else
+        raise GHX::OtherApiError, "GitHub API returned an error: #{response.code} #{response.body}"
+      end
     end
   end
 end

data/lib/ghx.rb

@@ -13,6 +13,7 @@ class Hash
 end
 
 require_relative "version"
+require_relative "ghx/errors"
 require_relative "ghx/graphql_client"
 require_relative "ghx/rest_client"
 require_relative "ghx/dependabot"
@@ -25,34 +26,52 @@ require_relative "ghx/project_item"
 # Extra classes to support more OO interfaces to the GitHub API. Wraps both the REST API and GraphQL API. Currently
 # incomplete. Functionality has been built for our existing use-cases, but nothing else.
 module GHX
+  # Defaults to $stdout
+  # @return [Logger]
   def self.logger
     @logger ||= Logger.new($stdout)
   end
 
+  # @param logger [Logger]
   def self.logger=(logger)
     @logger = logger
   end
 
+  # Internal octokit client.
+  # API Key defaults to ENV["GITHUB_TOKEN"]
+  # @return [Octokit::Client]
   def self.octokit
     @octokit ||= Octokit::Client.new(access_token: ENV["GITHUB_TOKEN"])
   end
 
+  # @param octokit [Octokit::Client]
+  # @return [Octokit::Client]
   def self.octokit=(octokit)
     @octokit = octokit
   end
 
+  # Internal graphql client.
+  # API Key defaults to ENV["GITHUB_TOKEN"]
+  # @return [GHX::GraphqlClient]
   def self.graphql
     @graphql ||= GHX::GraphqlClient.new(ENV["GITHUB_GRAPHQL_TOKEN"])
   end
 
+  # @param graphql [GHX::GraphqlClient]
+  # @return [GHX::GraphqlClient]
   def self.graphql=(graphql)
     @graphql = graphql
   end
 
+  # Internal graphql client.
+  # API Key defaults to ENV["GITHUB_TOKEN"]
+  # @return [GHX::RestClient]
   def self.rest_client
     @rest_client ||= GHX::RestClient.new(ENV["GITHUB_TOKEN"])
   end
 
+  # @param rest_client [GHX::RestClient]
+  # @return [GHX::RestClient]
   def self.rest_client=(rest_client)
     @rest_client = rest_client
   end

data/lib/version.rb

@@ -1,3 +1,3 @@
 module GHX
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ghx
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - CompanyCam
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-21 00:00:00.000000000 Z
+date: 2024-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: octokit
@@ -106,6 +106,7 @@ files:
 - lib/ghx/dependabot/alert.rb
 - lib/ghx/dependabot/package.rb
 - lib/ghx/dependabot/security_vulnerability.rb
+- lib/ghx/errors.rb
 - lib/ghx/graphql_client.rb
 - lib/ghx/issue.rb
 - lib/ghx/project.rb