plan_my_stuff 0.1.0

data/lib/plan_my_stuff/project_item.rb

@@ -0,0 +1,414 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Wraps a single item within a GitHub Projects V2 project.
+  # Stores a reference to its parent Project for delegation.
+  #
+  # Class methods:
+  #   ProjectItem.create!(issue)                             -- add existing issue
+  #   ProjectItem.create!(title, draft: true, body: "...")  -- create draft item
+  #   ProjectItem.move_item(item_id:, status:)
+  #   ProjectItem.assign(item_id:, assignee:)
+  #
+  # Instance methods:
+  #   item.move_to!("Done")
+  #   item.assign!("octocat")
+  #
+  class ProjectItem < PlanMyStuff::ApplicationRecord
+    # @return [String] GitHub node ID (e.g. "PVTI_...")
+    attr_reader :id
+    # @return [String, nil] node ID of the underlying content (Issue, PR, or DraftIssue)
+    attr_reader :content_node_id
+
+    # @return [String, nil] GitHub item type (e.g. "DRAFT_ISSUE", "ISSUE", "PULL_REQUEST")
+    attr_reader :type
+
+    # @return [String, nil]
+    attr_accessor :title
+    # @return [Integer, nil]
+    attr_accessor :number
+    # @return [String, nil]
+    attr_accessor :url
+    # @return [String, nil]
+    attr_accessor :state
+    # @return [String, nil]
+    attr_accessor :status
+    # @return [Hash]
+    attr_accessor :field_values
+    # @return [PlanMyStuff::Project, nil]
+    attr_accessor :project
+    # @return [PlanMyStuff::Issue, nil] linked issue (nil for draft items)
+    attr_accessor :issue
+
+    class << self
+      # Builds a persisted ProjectItem from parsed item data.
+      #
+      # @param item_hash [Hash] parsed item data (from Project.parse_project_item)
+      # @param project [PlanMyStuff::Project] parent project
+      #
+      # @return [PlanMyStuff::ProjectItem]
+      #
+      def build(item_hash, project:)
+        item = new(
+          id: item_hash[:id],
+          type: item_hash[:type],
+          content_node_id: item_hash[:content_node_id],
+          title: item_hash[:title],
+          number: item_hash[:number],
+          url: item_hash[:url],
+          state: item_hash[:state],
+          status: item_hash[:status],
+          field_values: item_hash[:field_values] || {},
+          project: project,
+        )
+        item.__send__(:persisted!)
+        item
+      end
+
+      # Creates a project item by adding an existing issue or creating a draft.
+      #
+      # @param issue_or_title [PlanMyStuff::Issue, String] Issue instance (non-draft) or title string (draft)
+      # @param draft [Boolean] when true, creates a draft item from a title string
+      # @param body [String, nil] body for draft items (ignored for non-draft)
+      # @param project_number [Integer, nil] defaults to config.default_project_number
+      #
+      # @return [PlanMyStuff::ProjectItem]
+      #
+      def create!(issue_or_title, draft: false, body: nil, project_number: nil)
+        if draft
+          add_draft_item(title: issue_or_title, body: body, project_number: project_number)
+        else
+          add_item(issue: issue_or_title, project_number: project_number)
+        end
+      end
+
+      # Moves a project item to a new status column.
+      #
+      # @param item_id [String] project item ID (e.g. "PVTI_...")
+      # @param status [String] status name, resolved to option ID internally
+      # @param project_number [Integer, nil] defaults to config.default_project_number
+      #
+      # @return [Hash] the updated item
+      #
+      def move_item(item_id:, status:, project_number: nil)
+        project_number = resolve_default_project_number(project_number)
+        project = Project.find(project_number)
+
+        status_field = project.status_field
+        option_id = resolve_status_option_id(status_field, status)
+
+        PlanMyStuff.client.graphql(
+          update_single_select_mutation,
+          variables: {
+            projectId: project.id,
+            itemId: item_id,
+            fieldId: status_field[:id],
+            optionId: option_id,
+          },
+        )
+      end
+
+      # Assigns users to a project item.
+      # Issues/PRs use REST via Issue.update!, drafts use GraphQL.
+      #
+      # @param number [Integer, nil] issue number (nil for drafts)
+      # @param content_node_id [String] node ID of the underlying content
+      # @param assignees [Array<String>] GitHub usernames
+      # @param draft [Boolean] whether the item is a draft issue
+      # @param repo [Symbol, String, nil] repo key (for issues)
+      #
+      # @return [void]
+      #
+      def assign(number:, content_node_id:, assignees:, draft: false, repo: nil)
+        if draft
+          client = PlanMyStuff.client
+          user_ids = assignees.map do |assignee|
+            user_data = client.graphql(user_node_id_query, variables: { login: assignee })
+            user_id = user_data.dig(:user, :id)
+
+            raise(APIError, "GitHub user not found: #{assignee}") if user_id.nil?
+
+            user_id
+          end
+
+          client.graphql(
+            assign_draft_mutation,
+            variables: { draftIssueId: content_node_id, assigneeIds: user_ids },
+          )
+        else
+          Issue.update!(number: number, repo: repo, assignees: assignees)
+        end
+      end
+
+      private
+
+        # Adds a GitHub issue to a project board.
+        #
+        # @param issue [PlanMyStuff::Issue]
+        # @param project_number [Integer, nil]
+        #
+        # @return [PlanMyStuff::ProjectItem]
+        #
+        def add_item(issue:, project_number:)
+          project_number = resolve_default_project_number(project_number)
+          client = PlanMyStuff.client
+          org = PlanMyStuff.configuration.organization
+
+          github_issue = client.rest(:issue, issue.repo, issue.number)
+          node_id = github_issue.respond_to?(:node_id) ? github_issue.node_id : github_issue[:node_id]
+
+          project_id = resolve_project_id(org, project_number)
+
+          data = client.graphql(
+            add_item_mutation,
+            variables: { projectId: project_id, contentId: node_id },
+          )
+
+          item_data = data.dig(:addProjectV2ItemById, :item) || {}
+          project = Project.find(project_number)
+
+          item = build(
+            {
+              id: item_data[:id],
+              title: issue.title,
+              number: issue.number,
+              url: nil,
+              state: issue.state,
+              status: nil,
+              field_values: {},
+            },
+            project: project,
+          )
+          item.issue = issue
+          item
+        end
+
+        # Adds a draft issue to a project board.
+        #
+        # @param title [String]
+        # @param body [String, nil]
+        # @param project_number [Integer, nil]
+        #
+        # @return [PlanMyStuff::ProjectItem]
+        #
+        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)
+
+          variables = { projectId: project_id, title: title }
+          variables[:body] = body if body.present?
+
+          data = PlanMyStuff.client.graphql(
+            add_draft_item_mutation,
+            variables: variables,
+          )
+
+          item_data = data.dig(:addProjectV2DraftIssue, :projectItem) || {}
+          project = Project.find(project_number)
+
+          build(
+            {
+              id: item_data[:id],
+              title: title,
+              number: nil,
+              url: nil,
+              state: nil,
+              status: nil,
+              field_values: {},
+            },
+            project: project,
+          )
+        end
+
+        # Resolves a project number, falling back to config.default_project_number.
+        #
+        # @param project_number [Integer, nil]
+        #
+        # @return [Integer]
+        #
+        def resolve_default_project_number(project_number)
+          return project_number if project_number.present?
+
+          PlanMyStuff.configuration.default_project_number ||
+            raise(ArgumentError, 'project_number is required when config.default_project_number is not set')
+        end
+
+        # @return [String]
+        def add_item_mutation
+          <<~GRAPHQL
+            mutation($projectId: ID!, $contentId: ID!) {
+              addProjectV2ItemById(input: {
+                projectId: $projectId,
+                contentId: $contentId
+              }) {
+                item {
+                  id
+                }
+              }
+            }
+          GRAPHQL
+        end
+
+        # @return [String]
+        def add_draft_item_mutation
+          <<~GRAPHQL
+            mutation($projectId: ID!, $title: String!, $body: String) {
+              addProjectV2DraftIssue(input: {
+                projectId: $projectId,
+                title: $title,
+                body: $body
+              }) {
+                projectItem {
+                  id
+                }
+              }
+            }
+          GRAPHQL
+        end
+
+        # @return [String]
+        def update_single_select_mutation
+          <<~GRAPHQL
+            mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
+              updateProjectV2ItemFieldValue(input: {
+                projectId: $projectId,
+                itemId: $itemId,
+                fieldId: $fieldId,
+                value: { singleSelectOptionId: $optionId }
+              }) {
+                projectV2Item {
+                  id
+                }
+              }
+            }
+          GRAPHQL
+        end
+
+        # @return [String]
+        def assign_draft_mutation
+          <<~GRAPHQL
+            mutation($draftIssueId: ID!, $assigneeIds: [ID!]) {
+              updateProjectV2DraftIssue(input: {
+                draftIssueId: $draftIssueId,
+                assigneeIds: $assigneeIds
+              }) {
+                draftIssue { id }
+              }
+            }
+          GRAPHQL
+        end
+
+        # @return [String]
+        def user_node_id_query
+          <<~GRAPHQL
+            query($login: String!) {
+              user(login: $login) {
+                id
+              }
+            }
+          GRAPHQL
+        end
+
+        # @return [String]
+        def project_id_query
+          <<~GRAPHQL
+            query($org: String!, $number: Int!) {
+              organization(login: $org) {
+                projectV2(number: $number) {
+                  id
+                }
+              }
+            }
+          GRAPHQL
+        end
+
+        # Resolves a status name to its option ID.
+        #
+        # @param status_field [Hash]
+        # @param status_name [String]
+        #
+        # @return [String]
+        #
+        def resolve_status_option_id(status_field, status_name)
+          option = status_field[:options].find { |o| o[:name] == status_name }
+
+          unless option
+            available = status_field[:options].pluck(:name).join(', ')
+            raise(ArgumentError, "Unknown status '#{status_name}'. Available: #{available}")
+          end
+
+          option[:id]
+        end
+
+        # Resolves a project number to its node ID.
+        #
+        # @param org [String]
+        # @param project_number [Integer]
+        #
+        # @return [String]
+        #
+        def resolve_project_id(org, project_number)
+          data = PlanMyStuff.client.graphql(
+            project_id_query,
+            variables: { org: org, number: project_number },
+          )
+
+          data.dig(:organization, :projectV2, :id)
+        end
+    end
+
+    # @see super
+    def initialize(**attrs)
+      @id = attrs.delete(:id)
+      @type = attrs.delete(:type)
+      @content_node_id = attrs.delete(:content_node_id)
+      super
+      @field_values ||= {}
+    end
+
+    # Moves this item to a new status column on its parent project.
+    #
+    # @param status [String] status name (e.g. "In Progress", "Done")
+    #
+    # @return [Hash] mutation result
+    #
+    def move_to!(status)
+      self.class.move_item(
+        project_number: project.number,
+        item_id: id,
+        status: status,
+      )
+    end
+
+    # Assigns users to this item on its parent project.
+    #
+    # @param assignees [String, Array<String>] GitHub username(s)
+    #
+    # @return [void]
+    #
+    def assign!(assignees)
+      self.class.assign(
+        number: number,
+        content_node_id: content_node_id,
+        assignees: Array.wrap(assignees),
+        draft: draft?,
+      )
+    end
+
+    # @return [Boolean]
+    def draft?
+      type == 'DRAFT_ISSUE'
+    end
+
+    private
+
+      # Marks this record as persisted.
+      #
+      # @return [void]
+      #
+      def persisted!
+        @persisted = true
+      end
+  end
+end