plan_my_stuff 0.7.0 → 0.8.0

data/lib/plan_my_stuff/base_project_item.rb

@@ -1,18 +1,17 @@
 # frozen_string_literal: true
 
 module PlanMyStuff
-  # Shared base for GitHub Projects V2 item wrappers. Holds attribute
-  # definitions, generic build/create/move/update/delete/assign machinery,
-  # and core instance helpers.
+  # Shared base for GitHub Projects V2 item wrappers. Holds attribute definitions, generic
+  # build/create/move/update/delete/assign machinery, and core instance helpers.
   #
-  # Not meant to be used directly. Concrete subclasses (ProjectItem,
-  # TestingProjectItem) add their own domain-specific methods.
+  # Not meant to be used directly. Concrete subclasses (ProjectItem, TestingProjectItem) add their own domain-specific
+  # methods.
   #
   # Class methods:
   #   BaseProjectItem.create!(issue)                             -- add existing issue
   #   BaseProjectItem.create!(title, draft: true, body: "...")  -- create draft item
-  #   BaseProjectItem.move_item(item_id:, status:)
-  #   BaseProjectItem.assign(item_id:, assignee:)
+  #   BaseProjectItem.move_item!(item_id:, status:)
+  #   BaseProjectItem.assign!(item_id:, assignee:)
   #
   # Instance methods:
   #   item.move_to!("Done")
@@ -101,9 +100,9 @@ module PlanMyStuff
       def create!(issue_or_title, draft: false, body: nil, project_number: nil, user: nil)
         item =
           if draft
-            add_draft_item(title: issue_or_title, body: body, project_number: project_number)
+            add_draft_item!(title: issue_or_title, body: body, project_number: project_number)
           else
-            add_item(issue: issue_or_title, project_number: project_number)
+            add_item!(issue: issue_or_title, project_number: project_number)
           end
 
         PlanMyStuff::Notifications.instrument('project_item.added', item, user: user)
@@ -118,12 +117,12 @@ module PlanMyStuff
       #
       # @return [Hash] the updated item
       #
-      def move_item(item_id:, status:, project_number: nil)
-        project_number = resolve_default_project_number(project_number)
+      def move_item!(item_id:, status:, project_number: nil)
+        project_number = resolve_default_project_number!(project_number)
         project = BaseProject.find(project_number)
 
         status_field = project.status_field
-        option_id = resolve_status_option_id(status_field, status)
+        option_id = resolve_status_option_id!(status_field, status)
 
         PlanMyStuff.client.graphql(
           PlanMyStuff::GraphQL::Queries::UPDATE_SINGLE_SELECT_FIELD,
@@ -146,11 +145,11 @@ module PlanMyStuff
       # @return [Hash] mutation result
       #
       def update_single_select_field!(item_id:, field_name:, value:, project_number: nil)
-        project_number = resolve_default_project_number(project_number)
+        project_number = resolve_default_project_number!(project_number)
         project = BaseProject.find(project_number)
 
-        field = resolve_single_select_field(project, field_name)
-        option_id = resolve_status_option_id(field, value)
+        field = resolve_single_select_field!(project, field_name)
+        option_id = resolve_status_option_id!(field, value)
 
         PlanMyStuff.client.graphql(
           PlanMyStuff::GraphQL::Queries::UPDATE_SINGLE_SELECT_FIELD,
@@ -173,10 +172,10 @@ module PlanMyStuff
       # @return [Hash] mutation result
       #
       def update_field!(item_id:, field_name:, value:, project_number: nil)
-        project_number = resolve_default_project_number(project_number)
+        project_number = resolve_default_project_number!(project_number)
         project = BaseProject.find(project_number)
 
-        field = resolve_text_field(project, field_name)
+        field = resolve_text_field!(project, field_name)
 
         PlanMyStuff.client.graphql(
           PlanMyStuff::GraphQL::Queries::UPDATE_TEXT_FIELD,
@@ -199,10 +198,10 @@ module PlanMyStuff
       # @return [Hash] mutation result
       #
       def update_date_field!(item_id:, field_name:, date:, project_number: nil)
-        project_number = resolve_default_project_number(project_number)
+        project_number = resolve_default_project_number!(project_number)
         project = BaseProject.find(project_number)
 
-        field = resolve_text_field(project, field_name)
+        field = resolve_text_field!(project, field_name)
 
         PlanMyStuff.client.graphql(
           PlanMyStuff::GraphQL::Queries::UPDATE_DATE_FIELD,
@@ -215,18 +214,18 @@ module PlanMyStuff
         )
       end
 
-      # Deletes a project item from its parent project. Returns the
-      # +deletedItemId+ from the GraphQL response on success.
+      # Deletes a project item from its parent project. Returns the +deletedItemId+ from the GraphQL response on
+      # success.
+      #
+      # @raise [PlanMyStuff::APIError] if the GraphQL mutation fails
       #
       # @param item_id [String] project item ID (e.g. "PVTI_...")
       # @param project_number [Integer, nil] defaults to config.default_project_number
       #
       # @return [String] the deleted item ID echoed back by GitHub
       #
-      # @raise [PlanMyStuff::APIError] if the GraphQL mutation fails
-      #
-      def delete_item(item_id:, project_number: nil)
-        project_number = resolve_default_project_number(project_number)
+      def delete_item!(item_id:, project_number: nil)
+        project_number = resolve_default_project_number!(project_number)
         org = PlanMyStuff.configuration.organization
         project_id = resolve_project_id(org, project_number)
 
@@ -241,8 +240,9 @@ module PlanMyStuff
         deleted_id
       end
 
-      # Assigns users to a project item.
-      # Issues/PRs use REST via Issue.update!, drafts use GraphQL.
+      # Assigns users to a project item. Issues/PRs use REST via Issue.update!, drafts use GraphQL.
+      #
+      # @raise [PlanMyStuff::APIError] if a username cannot be resolved or the GraphQL mutation fails
       #
       # @param number [Integer, nil] issue number (nil for drafts)
       # @param content_node_id [String] node ID of the underlying content
@@ -252,7 +252,7 @@ module PlanMyStuff
       #
       # @return [void]
       #
-      def assign(number:, content_node_id:, assignees:, draft: false, repo: nil)
+      def assign!(number:, content_node_id:, assignees:, draft: false, repo: nil)
         if draft
           client = PlanMyStuff.client
           user_ids = assignees.map do |assignee|
@@ -262,7 +262,7 @@ module PlanMyStuff
             )
             user_id = user_data.dig(:user, :id)
 
-            raise(APIError, "GitHub user not found: #{assignee}") if user_id.nil?
+            raise(PlanMyStuff::APIError, "GitHub user not found: #{assignee}") if user_id.nil?
 
             user_id
           end
@@ -272,7 +272,7 @@ module PlanMyStuff
             variables: { draftIssueId: content_node_id, assigneeIds: user_ids },
           )
         else
-          Issue.update!(number: number, repo: repo, assignees: assignees)
+          PlanMyStuff::Issue.update!(number: number, repo: repo, assignees: assignees)
         end
       end
 
@@ -285,8 +285,8 @@ module PlanMyStuff
         #
         # @return [PlanMyStuff::BaseProjectItem]
         #
-        def add_item(issue:, project_number:)
-          project_number = resolve_default_project_number(project_number)
+        def add_item!(issue:, project_number:)
+          project_number = resolve_default_project_number!(project_number)
           client = PlanMyStuff.client
           org = PlanMyStuff.configuration.organization
 
@@ -329,8 +329,8 @@ module PlanMyStuff
         #
         # @return [PlanMyStuff::BaseProjectItem]
         #
-        def add_draft_item(title:, body:, project_number:)
-          project_number = resolve_default_project_number(project_number)
+        def add_draft_item!(title:, body:, project_number:)
+          project_number = resolve_default_project_number!(project_number)
           org = PlanMyStuff.configuration.organization
           project_id = resolve_project_id(org, project_number)
 
@@ -363,23 +363,25 @@ module PlanMyStuff
           )
         end
 
-        # @see PlanMyStuff::Project.resolve_default_project_number
-        def resolve_default_project_number(project_number)
-          PlanMyStuff::Project.resolve_default_project_number(project_number)
+        # @see PlanMyStuff::Project.resolve_default_project_number!
+        def resolve_default_project_number!(project_number)
+          PlanMyStuff::Project.resolve_default_project_number!(project_number)
         end
 
-        # Finds a text field by name on a project. Raises ArgumentError if
-        # the field is not found or is a single-select field.
+        # Finds a text field by name on a project. Raises ArgumentError if the field is not found or is a single-select
+        # field.
+        #
+        # @raise [ArgumentError] if the field is not found or is a single-select field
         #
         # @param project [PlanMyStuff::BaseProject]
         # @param field_name [String]
         #
         # @return [Hash]
         #
-        def resolve_text_field(project, field_name)
+        def resolve_text_field!(project, field_name)
           field = project.fields.find { |f| f[:name] == field_name && f[:options].nil? }
 
-          unless field
+          if field.nil?
             available = project.fields.select { |f| f[:options].nil? }.pluck(:name).join(', ')
             raise(ArgumentError, "Unknown text field '#{field_name}'. Available: #{available}")
           end
@@ -387,15 +389,17 @@ module PlanMyStuff
           field
         end
 
+        # @raise [ArgumentError] if the field is not found or is not a single-select field
+        #
         # @param project [PlanMyStuff::BaseProject]
         # @param field_name [String]
         #
         # @return [Hash]
         #
-        def resolve_single_select_field(project, field_name)
+        def resolve_single_select_field!(project, field_name)
           field = project.fields.find { |f| f[:name] == field_name && f[:options].present? }
 
-          unless field
+          if field.nil?
             available = project.fields.select { |f| f[:options].present? }.pluck(:name).join(', ')
             raise(ArgumentError, "Unknown single-select field '#{field_name}'. Available: #{available}")
           end
@@ -405,15 +409,17 @@ module PlanMyStuff
 
         # Resolves a status name to its option ID.
         #
+        # @raise [ArgumentError] if +status_name+ is not a valid option for +status_field+
+        #
         # @param status_field [Hash]
         # @param status_name [String]
         #
         # @return [String]
         #
-        def resolve_status_option_id(status_field, status_name)
+        def resolve_status_option_id!(status_field, status_name)
           option = status_field[:options].find { |o| o[:name] == status_name }
 
-          unless option
+          if option.nil?
             available = status_field[:options].pluck(:name).join(', ')
             raise(ArgumentError, "Unknown status '#{status_name}'. Available: #{available}")
           end
@@ -446,7 +452,7 @@ module PlanMyStuff
     #
     def move_to!(status, user: nil)
       previous_status = self.status
-      result = self.class.move_item(
+      result = self.class.move_item!(
         project_number: project.number,
         item_id: id,
         status: status,
@@ -495,20 +501,17 @@ module PlanMyStuff
       )
     end
 
-    # Deletes this item from its parent project. Marks the in-memory
-    # instance as destroyed so +destroyed?+ returns true and +persisted?+
-    # returns false.
+    # Deletes this item from its parent project. Marks the in-memory instance as destroyed so +destroyed?+ returns
+    # true and +persisted?+ returns false.
     #
     # No-op if the instance is already destroyed.
     #
     # @return [String, nil] the deleted item ID, or nil if already destroyed
     #
-    # @raise [PlanMyStuff::APIError] if the GraphQL mutation fails
-    #
     def destroy!(user: nil)
       return if destroyed?
 
-      deleted_id = self.class.delete_item(
+      deleted_id = self.class.delete_item!(
         project_number: project.number,
         item_id: id,
       )
@@ -518,7 +521,8 @@ module PlanMyStuff
       deleted_id
     end
 
-    # Assigns users to this item on its parent project.
+    # Assigns users to this item on its parent project. For draft items the underlying call uses the draft-issue
+    # assign mutation; for issue-backed items it delegates to +Issue.update!+ with +assignees:+.
     #
     # @param assignees [String, Array<String>] GitHub username(s)
     #
@@ -527,7 +531,7 @@ module PlanMyStuff
     def assign!(assignees, user: nil)
       assignee_list = Array.wrap(assignees)
 
-      self.class.assign(
+      self.class.assign!(
         number: number,
         content_node_id: content_node_id,
         assignees: assignee_list,
@@ -543,8 +547,8 @@ module PlanMyStuff
       )
     end
 
-    # Serializes the project item to a JSON-safe hash, excluding the back-reference
-    # to the parent project to prevent recursive serialization cycles.
+    # Serializes the project item to a JSON-safe hash, excluding the back-reference to the parent project to prevent
+    # recursive serialization cycles.
     #
     # @return [Hash]
     #
@@ -573,7 +577,7 @@ module PlanMyStuff
       return super if @issue_assigned
       return if draft?
 
-      self.issue = PMS::Issue.find(number, repo: repo)
+      self.issue = PlanMyStuff::Issue.find(number, repo: repo)
       super
     end
   end

data/lib/plan_my_stuff/base_project_metadata.rb

@@ -4,7 +4,7 @@ module PlanMyStuff
   # Shared base for project-style metadata (regular and testing). Holds the
   # +kind+ dispatch field and serialization hook. Not instantiated directly;
   # use +ProjectMetadata+ or +TestingProjectMetadata+.
-  class BaseProjectMetadata < BaseMetadata
+  class BaseProjectMetadata < PlanMyStuff::BaseMetadata
     # @return [String, nil] dispatch key: "project" or "testing"
     attr_accessor :kind
 

data/lib/plan_my_stuff/client.rb

@@ -4,25 +4,63 @@ require 'active_support/core_ext/hash/keys'
 require 'octokit'
 
 module PlanMyStuff
-  # Infrastructure wrapper around Octokit. Handles auth, error normalization,
-  # and repo resolution. Domain modules (Issues, Projects, etc.) use this
-  # internally via PlanMyStuff.client.
+  # Infrastructure wrapper around Octokit. Handles auth, error normalization, and repo resolution. Domain modules
+  # (Issues, Projects, etc.) use this internally via PlanMyStuff.client.
   class Client
     # @return [Octokit::Client]
     attr_reader :octokit
 
-    # Returns the Faraday response from the most recent Octokit call.
-    # Useful for reading headers (e.g. `ETag`, `X-RateLimit-Remaining`)
-    # that aren't included in the parsed response body.
+    # Returns the Faraday response from the most recent Octokit call. Useful for reading headers (e.g. `ETag`,
+    # `X-RateLimit-Remaining`) that aren't included in the parsed response body.
     #
     # @return [Faraday::Response, nil]
     delegate :last_response, to: :octokit
 
+    class << self
+      # Activates trace mode: every +rest+ and +graphql+ call is recorded into +traced_requests+ until
+      # +exit_trace_mode!+ is called. Useful for debugging which GitHub calls a code path makes.
+      #
+      # @return [void]
+      #
+      def trace_mode!
+        @trace_mode = true
+        @traced_requests = []
+      end
+
+      # Disables trace mode and clears any recorded requests.
+      #
+      # @return [void]
+      #
+      def exit_trace_mode!
+        @trace_mode = false
+        @traced_requests = []
+      end
+
+      # @return [Boolean]
+      def trace_mode?
+        @trace_mode == true
+      end
+
+      # @return [Array<Hash>]
+      def traced_requests
+        @traced_requests ||= []
+      end
+    end
+
+    # @raise [PlanMyStuff::ConfigurationError] if +import_access_token+ is blank when +importing: true+
+    #
     # @return [Client]
-    def initialize
+    #
+    def initialize(importing: false)
       PlanMyStuff.configuration.validate!
 
-      @octokit = Octokit::Client.new(access_token: PlanMyStuff.configuration.access_token)
+      access_token = importing ? PlanMyStuff.configuration.import_access_token : PlanMyStuff.configuration.access_token
+
+      if importing && access_token.blank?
+        raise(PlanMyStuff::ConfigurationError, 'Import access token is required for import client but not configured')
+      end
+
+      @octokit = Octokit::Client.new(access_token: access_token)
     end
 
     # Delegates a REST API call to Octokit, normalizing errors.
@@ -33,16 +71,10 @@ module PlanMyStuff
     #
     # @return [Object] Octokit response
     #
-    def rest(method, *, **kwargs, &)
-      if kwargs.empty?
-        octokit.public_send(method, *, &)
-      else
-        octokit.public_send(method, *, **kwargs, &)
+    def rest(method, *args, **kwargs, &block)
+      trace!(:rest, method: method, args: args, kwargs: kwargs) do
+        execute_rest!(method, *args, **kwargs, &block)
       end
-    rescue Octokit::TooManyRequests => e
-      raise_rate_limit_error(e)
-    rescue Octokit::ClientError, Octokit::ServerError => e
-      raise(APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
     end
 
     # Executes a GraphQL query against GitHub's /graphql endpoint.
@@ -53,26 +85,9 @@ module PlanMyStuff
     # @return [Hash] parsed response data
     #
     def graphql(query, variables: {})
-      payload = { query: query }
-      payload[:variables] = variables unless variables.empty?
-
-      response = octokit.post('/graphql', payload.to_json)
-      data =
-        if response.is_a?(Hash)
-          response
-        else
-          (response.respond_to?(:to_h) ? response.to_h : response)
-        end
-
-      data = data.deep_symbolize_keys if data.respond_to?(:deep_symbolize_keys)
-
-      check_graphql_errors!(data)
-
-      data[:data]
-    rescue Octokit::TooManyRequests => e
-      raise_rate_limit_error(e)
-    rescue Octokit::ClientError, Octokit::ServerError => e
-      raise(APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
+      trace!(:graphql, query: query, variables: variables) do
+        execute_graphql!(query, variables)
+      end
     end
 
     # Resolves a repo param to a full "Org/Repo" string.
@@ -81,17 +96,90 @@ module PlanMyStuff
     #
     # @return [String] full repo path (e.g. "BrandsInsurance/Element")
     #
-    # @raise [ArgumentError] if repo cannot be resolved
-    #
-    def resolve_repo(repo = nil)
-      PlanMyStuff::Repo.resolve(repo).full_name
+    def resolve_repo!(repo = nil)
+      PlanMyStuff::Repo.resolve!(repo).full_name
     end
 
     private
 
-      # @param data [Hash] parsed GraphQL response
+      # @raise [PlanMyStuff::APIError] if Octokit call fails with client or server error
+      #
+      # @return [Object]
+      #
+      def execute_rest!(method, *, **kwargs, &)
+        if kwargs.empty?
+          octokit.public_send(method, *, &)
+        else
+          octokit.public_send(method, *, **kwargs, &)
+        end
+      rescue Octokit::TooManyRequests => e
+        raise_rate_limit_error!(e)
+      rescue Octokit::ClientError, Octokit::ServerError => e
+        raise(PlanMyStuff::APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
+      end
+
+      # @raise [PlanMyStuff::APIError] if Octokit call fails with client or server error
+      #
+      # @return [Hash]
+      #
+      def execute_graphql!(query, variables)
+        payload = { query: query }
+        payload[:variables] = variables unless variables.empty?
+
+        response = octokit.post('/graphql', payload.to_json)
+        data =
+          if response.is_a?(Hash)
+            response
+          else
+            (response.respond_to?(:to_h) ? response.to_h : response)
+          end
+
+        data = data.deep_symbolize_keys if data.respond_to?(:deep_symbolize_keys)
+
+        check_graphql_errors!(data)
+
+        data[:data]
+      rescue Octokit::TooManyRequests => e
+        raise_rate_limit_error!(e)
+      rescue Octokit::ClientError, Octokit::ServerError => e
+        raise(PlanMyStuff::APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
+      end
+
+      # Records the wrapped call into +Client.traced_requests+ when trace mode is on; otherwise just yields.
       #
-      # @raise [GraphQLError] if response contains errors
+      # @param kind [Symbol] :rest or :graphql
+      # @param details [Hash] call-specific details (method/args/query/variables)
+      #
+      # @return [Object]
+      #
+      def trace!(kind, **details)
+        return yield unless self.class.trace_mode?
+
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        begin
+          result = yield
+          record_trace(kind, start, details)
+          result
+        rescue => e
+          record_trace(kind, start, details, error: e)
+          raise
+        end
+      end
+
+      # @return [void]
+      def record_trace(kind, start, details, error: nil)
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1_000).round(2)
+        entry = { kind: kind, duration_ms: duration_ms, status: octokit.last_response&.status, **details }
+        if error
+          entry[:error] = error.class.name
+          entry[:error_message] = error.message
+        end
+        self.class.traced_requests << entry
+      end
+
+      # @raise [PlanMyStuff::GraphQLError] if response contains errors
+      #
+      # @param data [Hash] parsed GraphQL response
       #
       # @return [void]
       #
@@ -100,16 +188,16 @@ module PlanMyStuff
         return if errors.blank?
 
         messages = errors.filter_map { |e| e[:message] }
-        raise(GraphQLError.new(messages.join('; '), errors: errors))
+        raise(PlanMyStuff::GraphQLError.new(messages.join('; '), errors: errors))
       end
 
-      # @param exception [Octokit::TooManyRequests]
+      # @raise [PlanMyStuff::RateLimitError] if GitHub has been rate limited
       #
-      # @raise [RateLimitError]
+      # @param exception [Octokit::TooManyRequests]
       #
-      def raise_rate_limit_error(exception)
+      def raise_rate_limit_error!(exception)
         retry_after = parse_retry_after(exception)
-        raise(RateLimitError.new(exception.message, retry_after: retry_after))
+        raise(PlanMyStuff::RateLimitError.new(exception.message, retry_after: retry_after))
       end
 
       # @param exception [Octokit::TooManyRequests]