plan_my_stuff 0.3.0 → 0.4.0

data/lib/plan_my_stuff/project_item.rb

@@ -1,422 +1,8 @@
 # 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 [PlanMyStuff::Repo, nil]
-    attr_accessor :repo
-    # @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_writer :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],
-          repo: item_hash[:repo],
-          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],
-              content_node_id: node_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],
-              content_node_id: item_data.dig(:content, :id),
-              type: 'DRAFT_ISSUE',
-              title: title,
-              number: nil,
-              url: nil,
-              state: nil,
-              status: nil,
-              field_values: {},
-            },
-            project: project,
-          )
-        end
-
-        # @see PlanMyStuff::Project.resolve_default_project_number
-        def resolve_default_project_number(project_number)
-          PlanMyStuff::Project.resolve_default_project_number(project_number)
-        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
-                  content { ... on DraftIssue { 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?,
-        repo: repo,
-      )
-    end
-
-    # @return [Boolean]
-    def draft?
-      type == 'DRAFT_ISSUE'
-    end
-
-    # @return [PlanMyStuff::Issue, nil]
-    def issue
-      return @issue if defined?(@issue)
-      return if draft?
-
-      @issue = PMS::Issue.find(number, repo: repo)
-    end
-
-    private
-
-      # Marks this record as persisted.
-      #
-      # @return [void]
-      #
-      def persisted!
-        @persisted = true
-      end
+  # Concrete project item subclass for standard (non-testing) GitHub Projects V2
+  # projects. All generic machinery lives in BaseProjectItem.
+  class ProjectItem < PlanMyStuff::BaseProjectItem
   end
 end

data/lib/plan_my_stuff/project_item_metadata.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Metadata stored on the body of a +ProjectItem+ -- primarily used for
+  # draft items, which have their own body field distinct from any linked
+  # issue. Regular (non-draft) items rely on their linked issue's
+  # +IssueMetadata+ instead, to avoid double-bookkeeping.
+  #
+  # Lays the groundwork for the Phase 13 testing-tracking workflow
+  # (T-049), which will assign non-GitHub users (e.g. internal QA
+  # accounts) to draft items via the +pms_assignee+ field.
+  #
+  class ProjectItemMetadata < BaseMetadata
+    # @return [Integer, nil] consuming app user id of the PMS-side assignee
+    attr_accessor :pms_assignee
+
+    class << self
+      # Builds a ProjectItemMetadata from a parsed hash (e.g. from MetadataParser)
+      #
+      # @param hash [Hash]
+      #
+      # @return [PlanMyStuff::ProjectItemMetadata]
+      #
+      def from_hash(hash)
+        metadata = new
+        apply_common_from_hash(metadata, hash, {})
+        metadata.pms_assignee = hash[:pms_assignee]
+        metadata
+      end
+
+      # Builds a new ProjectItemMetadata, auto-filling gem defaults.
+      #
+      # @param user [Object, Integer] user object or user_id
+      # @param visibility [String] "public" or "internal"
+      #
+      # @return [PlanMyStuff::ProjectItemMetadata]
+      #
+      def build(user:, visibility: 'internal')
+        metadata = new
+        apply_common_build(
+          metadata,
+          user: user,
+          visibility: visibility,
+        )
+        metadata.pms_assignee = nil
+        metadata
+      end
+    end
+
+    # @return [Hash]
+    def to_h
+      super.merge(pms_assignee: pms_assignee)
+    end
+  end
+end

data/lib/plan_my_stuff/project_metadata.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module PlanMyStuff
-  class ProjectMetadata < BaseMetadata
+  # Metadata for regular (non-testing) projects.
+  class ProjectMetadata < BaseProjectMetadata
     class << self
       # Builds a ProjectMetadata from a parsed hash (e.g. from MetadataParser)
       #
@@ -12,7 +13,7 @@ module PlanMyStuff
       def from_hash(hash)
         metadata = new
         apply_common_from_hash(metadata, hash, PlanMyStuff.configuration.custom_fields_for(:project))
-
+        metadata.kind = hash.fetch(:kind, 'project')
         metadata
       end
 
@@ -33,9 +34,14 @@ module PlanMyStuff
           custom_fields_data: custom_fields,
           custom_fields_schema: PlanMyStuff.configuration.custom_fields_for(:project),
         )
-
+        metadata.kind = 'project'
         metadata
       end
     end
+
+    def initialize
+      super
+      @kind = 'project'
+    end
   end
 end

data/lib/plan_my_stuff/reminders/closer.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module Reminders
+    # Auto-closes a waiting issue that has exceeded the configured
+    # +inactivity_close_days+ ceiling. Clears waiting state and emits a
+    # dedicated +plan_my_stuff.issue.closed_inactive+ event.
+    #
+    # Goes through +Issue#update!+ with +skip_notification: true+ so the
+    # regular +issue.closed+ event is suppressed in favor of the
+    # dedicated +issue.closed_inactive+. +Issue#persist_update!+'s
+    # +clear_waiting_state_on_close!+ hook handles stripping waiting
+    # labels and clearing waiting timestamps in the single save write.
+    class Closer
+      # Returns +true+ when the issue has waited longer than
+      # +inactivity_close_days+ relative to +now+.
+      #
+      # @param issue [PlanMyStuff::Issue]
+      # @param now [Time]
+      #
+      # @return [Boolean]
+      #
+      def self.should_close?(issue, now: Time.now.utc)
+        start = issue.metadata.waiting_on_user_at || issue.metadata.waiting_on_approval_at
+        return false if start.nil?
+
+        ((now.utc - start) / 1.day) >= PlanMyStuff.configuration.inactivity_close_days
+      end
+
+      # @param issue [PlanMyStuff::Issue] candidate issue from the sweep
+      # @param now [Time] clock reference
+      #
+      def initialize(issue, now: Time.now.utc)
+        @issue = issue
+        @now = now.utc
+      end
+
+      # Closes the issue, tags it with the configured
+      # +user_inactive_label+, then emits
+      # +plan_my_stuff.issue.closed_inactive+.
+      #
+      # @return [void]
+      #
+      def call
+        @issue.update!(
+          state: :closed,
+          metadata: { closed_by_inactivity: true },
+          skip_notification: true,
+        )
+        add_user_inactive_label
+        PlanMyStuff::Notifications.instrument(
+          'issue.closed_inactive',
+          @issue,
+          reason: :inactivity,
+        )
+      end
+
+      private
+
+        # @return [void]
+        def add_user_inactive_label
+          label = PlanMyStuff.configuration.user_inactive_label
+          return if @issue.labels.include?(label)
+
+          PlanMyStuff::Label.ensure!(repo: @issue.repo, name: label)
+          PlanMyStuff::Label.add(issue: @issue, labels: [label])
+        end
+    end
+  end
+end

data/lib/plan_my_stuff/reminders/fire.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module Reminders
+    # Emits +plan_my_stuff.issue.reminder_due+ for a single waiting issue
+    # and advances its +next_reminder_at+ to the next milestone in the
+    # effective +reminder_days+ schedule (or +nil+ when the last milestone
+    # has passed).
+    class Fire
+      # Returns +true+ when the issue has a +next_reminder_at+ in the
+      # past relative to +now+.
+      #
+      # @param issue [PlanMyStuff::Issue]
+      # @param now [Time]
+      #
+      # @return [Boolean]
+      #
+      def self.ready?(issue, now: Time.now.utc)
+        due = issue.metadata.next_reminder_at
+        due.present? && due <= now
+      end
+
+      # @param issue [PlanMyStuff::Issue] candidate issue from the sweep
+      # @param now [Time] clock reference (defaults to +Time.now.utc+)
+      #
+      def initialize(issue, now: Time.now.utc)
+        @issue = issue
+        @now = now.utc
+      end
+
+      # Emits the reminder event and advances the schedule.
+      #
+      # @return [void]
+      #
+      def call
+        payload = build_payload
+        PlanMyStuff::Notifications.instrument('issue.reminder_due', @issue, **payload)
+
+        @issue.update!(
+          metadata: { next_reminder_at: next_reminder_at_value },
+          skip_notification: true,
+        )
+      end
+
+      private
+
+        # @return [Hash]
+        def build_payload
+          payload = {
+            waiting_kind: waiting_kind,
+            days_waiting: days_waiting,
+            reminder_day: reminder_day,
+            last_activity_at: last_activity_at,
+          }
+          payload[:pending_approvers] = pending_approvers if waiting_kind == :approval
+          payload
+        end
+
+        # @return [Symbol] +:user+ or +:approval+
+        def waiting_kind
+          @issue.metadata.waiting_on_user_at.present? ? :user : :approval
+        end
+
+        # @return [Time] the timestamp waiting started for the active kind
+        def starting_clock
+          @issue.metadata.waiting_on_user_at || @issue.metadata.waiting_on_approval_at
+        end
+
+        # @return [Integer]
+        def days_waiting
+          ((@now - starting_clock) / 1.day).to_i
+        end
+
+        # Most recent milestone passed, used as the +reminder_day+ label in
+        # the event payload.
+        #
+        # @return [Integer, nil]
+        #
+        def reminder_day
+          effective_reminder_days.select { |d| d <= days_waiting }.max
+        end
+
+        # Informational: last comment timestamp (falling back to the
+        # issue's GitHub +updated_at+ when there are no comments). Uses
+        # +updated_at+ on Comment since that's the only timestamp PMS
+        # exposes on comment records.
+        #
+        # @return [Time, nil]
+        #
+        def last_activity_at
+          last_comment = @issue.comments.max_by { |c| c.updated_at || Time.at(0).utc }
+          last_comment&.updated_at || @issue.updated_at
+        end
+
+        # Resolves pending-approval user IDs via +UserResolver+. IDs that
+        # fail to resolve (e.g. deleted users) are dropped.
+        #
+        # @return [Array<Object>]
+        #
+        def pending_approvers
+          @issue.pending_approvals.filter_map do |approval|
+            PlanMyStuff::UserResolver.resolve(approval.user_id)
+          rescue
+            next
+          end
+        end
+
+        # @return [Array<Integer>]
+        def effective_reminder_days
+          @issue.metadata.reminder_days.presence || PlanMyStuff.configuration.reminder_days
+        end
+
+        # Time of the next milestone past +now+, or +nil+ when the last
+        # milestone has passed. Returned as a native +Time+ (not ISO
+        # string) so +IssueMetadata#to_h+'s +format_time+ serializes it
+        # cleanly.
+        #
+        # @return [Time, nil]
+        #
+        def next_reminder_at_value
+          start = starting_clock
+          remaining = effective_reminder_days.select { |d| start + d.days > @now }
+          return if remaining.empty?
+
+          (start + remaining.first.days).utc
+        end
+    end
+  end
+end