plan_my_stuff 0.1.0 → 1.0.0

data/lib/plan_my_stuff/issue_extractions/waiting.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module IssueExtractions
+    module Waiting
+      # @return [Boolean]
+      def awaiting_reply?
+        issue_fields['Issue Status'] == 'Waiting on Reply'
+      end
+
+      # Marks the issue as waiting on an end-user reply. Sets +metadata.waiting_on_user_at+ to now, (re)computes
+      # +metadata.next_reminder_at+, and adds the configured +waiting_on_user_label+ to the issue. Called from
+      # +Comment.create!+ when a support user posts a comment with +waiting_on_reply: true+, and from the
+      # +Issues::WaitingsController+ toggle.
+      #
+      # @param user [Object, nil] actor for the label notification event
+      #
+      # @return [self]
+      #
+      def enter_waiting_on_user!(user: nil)
+        now = Time.now.utc
+        label = PlanMyStuff.configuration.waiting_on_user_label
+
+        PlanMyStuff::Label.ensure!(repo: repo, name: label)
+        PlanMyStuff::Label.add!(issue: self, labels: [label], user: user) if labels.exclude?(label)
+
+        to_update = {}
+        if PlanMyStuff.configuration.issue_fields_enabled
+          to_update[:issue_fields] = { 'Issue Status' => 'Waiting on Reply' }
+        end
+
+        self.class.update!(
+          number: number,
+          repo: repo,
+          metadata: {
+            waiting_on_user_at: PlanMyStuff.format_time(now),
+            next_reminder_at: format_next_reminder_at(from: now),
+          },
+          **to_update,
+        )
+        reload
+      end
+
+      # Clears the waiting-on-user state: removes the label, clears +metadata.waiting_on_user_at+, and clears
+      # +metadata.next_reminder_at+ unless a waiting-on-approval timer is still active. No-ops if the issue is not
+      # currently waiting on a user reply.
+      #
+      # @return [self]
+      #
+      def clear_waiting_on_user!
+        label = PlanMyStuff.configuration.waiting_on_user_label
+        return self if metadata.waiting_on_user_at.nil? && labels.exclude?(label)
+
+        PlanMyStuff::Label.remove!(issue: self, labels: [label]) if labels.include?(label)
+
+        to_update = {}
+        if PlanMyStuff.configuration.issue_fields_enabled
+          to_update[:issue_fields] = { 'Issue Status' => 'Open' }
+        end
+
+        self.class.update!(
+          number: number,
+          repo: repo,
+          metadata: {
+            waiting_on_user_at: nil,
+            next_reminder_at:
+              metadata.waiting_on_approval_at ? PlanMyStuff.format_time(metadata.next_reminder_at) : nil,
+          },
+          **to_update,
+        )
+        reload
+      end
+
+      # Reopens an issue that was auto-closed by the inactivity sweep, clears +metadata.closed_by_inactivity+, and
+      # emits +issue_reopened_by_reply.plan_my_stuff+ carrying the reopening comment. Does not emit the regular
+      # +issue.reopened+ event \- subscribers that specifically care about this flow subscribe to the dedicated event.
+      #
+      # @param comment [PlanMyStuff::Comment] the reopening comment
+      # @param user [Object, nil] actor for the notification event
+      #
+      # @return [self]
+      #
+      def reopen_by_reply!(comment:, user: nil)
+        inactive_label = PlanMyStuff.configuration.user_inactive_label
+        PlanMyStuff::Label.remove!(issue: self, labels: [inactive_label]) if labels.include?(inactive_label)
+
+        to_update = {}
+        if PlanMyStuff.configuration.issue_fields_enabled
+          to_update[:issue_fields] = { 'Issue Status' => 'Reopened' }
+        end
+
+        self.class.update!(
+          number: number,
+          repo: repo,
+          state: :open,
+          metadata: { closed_by_inactivity: false },
+          **to_update,
+        )
+        reload
+
+        PlanMyStuff::Notifications.instrument(
+          'issue_reopened_by_reply',
+          self,
+          user: user,
+          comment: comment,
+        )
+        self
+      end
+
+      private
+
+        # Formats the next reminder time as an ISO 8601 UTC string, using per-issue +metadata.reminder_days+ when set
+        # or +config.reminder_days+ otherwise. Returns +nil+ when the effective schedule is empty.
+        #
+        # @param from [Time] baseline timestamp
+        #
+        # @return [String, nil]
+        #
+        def format_next_reminder_at(from:)
+          days = metadata.reminder_days.presence || PlanMyStuff.configuration.reminder_days
+          return if days.empty?
+
+          PlanMyStuff.format_time(from + days.first.days)
+        end
+
+        # When an issue is transitioning from open to closed, strips both waiting labels from the outgoing labels
+        # array and clears the waiting-related timestamps on +metadata+ so a single save writes both state change and
+        # cleanup. No-op for any other transition.
+        #
+        # @param attrs [Hash] the kwargs hash being assembled for +Issue.update!+; mutated in place
+        #
+        # @return [void]
+        #
+        def clear_waiting_state_on_close(attrs)
+          return unless state_changed?
+          return unless state_was == 'open'
+          return unless state == 'closed'
+
+          return if metadata.waiting_on_user_at.blank? && metadata.waiting_on_approval_at.blank?
+
+          waiting_labels = [
+            PlanMyStuff.configuration.waiting_on_user_label,
+            PlanMyStuff.configuration.waiting_on_approval_label,
+          ]
+          attrs[:labels] = Array.wrap(attrs[:labels]) - waiting_labels
+
+          metadata.waiting_on_user_at = nil
+          metadata.waiting_on_approval_at = nil
+          metadata.next_reminder_at = nil
+        end
+
+        # When an inactivity-closed issue is being reopened, strips the +user_inactive_label+ from the outgoing labels
+        # and clears +metadata.closed_by_inactivity+ so the save writes both. No-op for any other transition or for
+        # reopens of non-inactive closes.
+        #
+        # @param attrs [Hash] the kwargs hash being assembled for +Issue.update!+; mutated in place
+        #
+        # @return [void]
+        #
+        def clear_inactivity_state_on_reopen(attrs)
+          return unless state_changed?
+          return unless state_was == 'closed'
+          return unless state == 'open'
+          return unless metadata.closed_by_inactivity
+
+          attrs[:labels] = Array.wrap(attrs[:labels]) - [PlanMyStuff.configuration.user_inactive_label]
+          metadata.closed_by_inactivity = false
+        end
+    end
+  end
+end

data/lib/plan_my_stuff/issue_field.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Value object wrapping an organization-level GitHub Issue Field definition (public preview).
+  # Issue Fields are structured per-issue metadata (text, number, date, or single-select)
+  # configured once at the org level and applied across all of the org's repositories.
+  #
+  # Read-only on the gem side: callers manage field *definitions* through the GitHub UI, while
+  # the gem only handles field *values* on individual issues (see +Issue#issue_fields+).
+  class IssueField
+    # GraphQL +__typename+ -> normalized type symbol used internally.
+    TYPES = {
+      IssueFieldText: :text,
+      IssueFieldNumber: :number,
+      IssueFieldDate: :date,
+      IssueFieldSingleSelect: :single_select,
+    }.freeze
+
+    # @return [String] GraphQL node ID, e.g. +"IFSS_kgDOAAGskA"+
+    attr_reader :id
+
+    # @return [String] display name (e.g. +"Priority"+)
+    attr_reader :name
+
+    # @return [Symbol] one of +:text+, +:number+, +:date+, +:single_select+
+    attr_reader :type
+
+    # @return [String, nil]
+    attr_reader :description
+
+    # @return [Array<Hash>] for +:single_select+, the option list as returned by GraphQL with symbol keys
+    #   (+id+, +name+, +description+, +color+). Empty for other field types.
+    attr_reader :options
+
+    class << self
+      # Lists Issue Field definitions configured on the org.
+      #
+      # @raise [PlanMyStuff::IssueFieldsNotEnabledError] if +config.issue_fields_enabled+ is +false+
+      #
+      # @param org [String, nil] org login; defaults to +config.organization+
+      #
+      # @return [Array<PlanMyStuff::IssueField>]
+      #
+      def list(org: nil)
+        ensure_enabled!
+
+        org_login = org || PlanMyStuff.configuration.organization
+        data = PlanMyStuff.client.graphql(
+          PlanMyStuff::GraphQL::Queries::LIST_ORG_ISSUE_FIELDS,
+          variables: { org: org_login },
+        )
+        Array.wrap(data.dig(:organization, :issueFields, :nodes)).map { |node| from_graphql(node) }
+      end
+
+      # @param name [String, Symbol]
+      # @param org [String, nil]
+      #
+      # @return [PlanMyStuff::IssueField, nil]
+      #
+      def find(name, org: nil)
+        list(org: org).find { |field| field.name.casecmp?(name.to_s) }
+      end
+
+      # @param node [Hash] one node from +LIST_ORG_ISSUE_FIELDS+
+      #
+      # @return [PlanMyStuff::IssueField]
+      #
+      def from_graphql(node)
+        typename = node[:__typename]
+        type = TYPES[typename.to_sym] if typename
+        raise(PlanMyStuff::Error, "Unknown Issue Field typename: #{typename.inspect}") if type.nil?
+
+        new(
+          id: node.fetch(:id),
+          name: node.fetch(:name),
+          type: type,
+          description: node[:description],
+          options: Array.wrap(node[:options]),
+        )
+      end
+
+      private
+
+        # @raise [PlanMyStuff::IssueFieldsNotEnabledError]
+        #
+        # @return [void]
+        #
+        def ensure_enabled!
+          return if PlanMyStuff.configuration.issue_fields_enabled
+
+          raise(PlanMyStuff::IssueFieldsNotEnabledError)
+        end
+    end
+
+    # @param id [String]
+    # @param name [String]
+    # @param type [Symbol]
+    # @param description [String, nil]
+    # @param options [Array<Hash>]
+    #
+    def initialize(id:, name:, type:, description: nil, options: [])
+      @id = id
+      @name = name
+      @type = type
+      @description = description
+      @options = options
+    end
+
+    # Resolves a single-select option name to its GraphQL node ID.
+    #
+    # @raise [PlanMyStuff::Error] if this field is not a single-select, or the option name is unknown
+    #
+    # @param option_name [String, Symbol]
+    #
+    # @return [String]
+    #
+    def option_id_for!(option_name)
+      raise(PlanMyStuff::Error, "Field #{name.inspect} is not a single-select") unless type == :single_select
+
+      match = options.find { |option| option.fetch(:name).casecmp?(option_name.to_s) }
+      raise(PlanMyStuff::Error, "Unknown option #{option_name.inspect} for field #{name.inspect}") if match.nil?
+
+      match.fetch(:id)
+    end
+  end
+end

data/lib/plan_my_stuff/issue_field_translation.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Translates between the canonical Issue Field names / values the gem refers to internally (e.g. +"Issue Status"+,
+  # +"Waiting on Reply"+) and the names / values a consuming org actually uses on GitHub. Driven by
+  # +config.issue_field_names+ (canonical field name => consumer field name) and +config.issue_field_values+
+  # (canonical field name => { canonical value => consumer value }).
+  #
+  # Outbound (canonical -> consumer) translation happens on writes and filters; inbound (consumer -> canonical) on
+  # reads, so internal comparisons like +issue_fields['Issue Status'] == 'Waiting on Reply'+ keep working regardless of
+  # how the org named the field or option. Unconfigured names / values pass through unchanged (identity fallback,
+  # mirroring +config.pipeline_statuses+).
+  module IssueFieldTranslation
+    module_function
+
+    # @param canonical [String, Symbol] canonical field name
+    #
+    # @return [String] the consumer's field name, or the canonical name when unmapped
+    #
+    def consumer_field_name(canonical)
+      PlanMyStuff.configuration.issue_field_names.fetch(canonical.to_s, canonical.to_s)
+    end
+
+    # @param consumer [String] the consumer's field name (as GitHub returns it)
+    #
+    # @return [String] the canonical field name, or the consumer name when unmapped
+    #
+    def canonical_field_name(consumer)
+      PlanMyStuff.configuration.issue_field_names.invert.fetch(consumer, consumer)
+    end
+
+    # Translates a canonical value to the consumer's value for the given canonical field. Non-String values (numbers,
+    # dates, +nil+) pass through untouched -- only single-select / text labels are translatable.
+    #
+    # @param canonical_field [String, Symbol] canonical field name
+    # @param value [Object, nil] canonical value
+    #
+    # @return [Object, nil] the consumer's value, or the input when unmapped / non-String
+    #
+    def consumer_value(canonical_field, value)
+      return value unless value.is_a?(String)
+
+      value_map(canonical_field).fetch(value, value)
+    end
+
+    # Translates a consumer value back to the canonical value for the given canonical field.
+    #
+    # @param canonical_field [String, Symbol] canonical field name
+    # @param value [Object, nil] consumer value
+    #
+    # @return [Object, nil] the canonical value, or the input when unmapped / non-String
+    #
+    def canonical_value(canonical_field, value)
+      return value unless value.is_a?(String)
+
+      value_map(canonical_field).invert.fetch(value, value)
+    end
+
+    # @param canonical_field [String, Symbol]
+    #
+    # @return [Hash{String => String}] canonical-value => consumer-value map for the field (empty when unconfigured)
+    #
+    def value_map(canonical_field)
+      PlanMyStuff.configuration.issue_field_values.fetch(canonical_field.to_s, {})
+    end
+  end
+end

data/lib/plan_my_stuff/issue_field_value_set.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Hash-like read-side view of GitHub Issue Field values on a single +Issue+. Returned by
+  # +Issue#issue_fields+. Values are coerced into Ruby types on construction: date fields come back
+  # as +Date+, number fields as +Float+, single-select fields as the option name +String+, and
+  # text fields as the raw +String+.
+  #
+  # Access is by canonical field name (consumer names / values are reverse-translated via
+  # +PlanMyStuff::IssueFieldTranslation+ on construction); string and symbol keys both work. Iteration yields
+  # +[name, value]+ pairs in the order GitHub returned them.
+  class IssueFieldValueSet
+    include Enumerable
+
+    delegate :empty?, to: :@hash
+
+    class << self
+      # @param nodes [Array<Hash>, nil] +issueFieldValues.nodes+ from the GraphQL read query
+      #
+      # @return [PlanMyStuff::IssueFieldValueSet]
+      #
+      def from_graphql(nodes)
+        pairs = Array.wrap(nodes).map do |node|
+          canonical_name = PlanMyStuff::IssueFieldTranslation.canonical_field_name(node.dig(:field, :name))
+          [canonical_name, PlanMyStuff::IssueFieldTranslation.canonical_value(canonical_name, coerce(node))]
+        end
+        new(pairs.to_h)
+      end
+
+      # @param node [Hash]
+      #
+      # @return [Object]
+      #
+      def coerce(node)
+        case node[:__typename].to_s
+        when 'IssueFieldDateValue' then Date.parse(node.fetch(:value))
+        when 'IssueFieldNumberValue' then node.fetch(:value).to_f
+        when 'IssueFieldSingleSelectValue' then node.fetch(:name)
+        else node.fetch(:value)
+        end
+      end
+    end
+
+    # @param hash [Hash{String => Object}]
+    #
+    def initialize(hash)
+      @hash = hash
+    end
+
+    # @param name [String, Symbol] field display name
+    #
+    # @return [Object, nil]
+    #
+    def [](name)
+      @hash[name.to_s]
+    end
+
+    # @return [Hash{String => Object}] copy of the underlying hash
+    def to_h
+      @hash.dup
+    end
+
+    # @return [Enumerator, void]
+    def each(&)
+      @hash.each(&)
+    end
+  end
+end

data/lib/plan_my_stuff/issue_metadata.rb

@@ -1,17 +1,37 @@
 # frozen_string_literal: true
 
 module PlanMyStuff
-  class IssueMetadata < BaseMetadata
+  class IssueMetadata < PlanMyStuff::BaseMetadata
     # @return [Time, nil] first support action timestamp, nil until set
     attr_accessor :responded_at
     # @return [String, nil] user-facing URL in the consuming app
     attr_accessor :issues_url
-    # @return [Boolean] whether this issue appears on the priority dashboard
-    attr_accessor :priority_list
-    # @return [Integer] sort order on priority dashboard (-1 = unranked)
-    attr_accessor :priority_list_priority
     # @return [Array<Integer>] user IDs of non-support users allowed to view internal comments
     attr_accessor :visibility_allowlist
+    # @return [String, nil] merged PR commit SHA for release tracking
+    attr_accessor :commit_sha
+    # @return [Boolean] whether to auto-complete on deployment (default: true)
+    attr_accessor :auto_complete
+    # @return [Array<PlanMyStuff::Link>] metadata-backed issue relationships.
+    #   Only +:related+ links live here; native relationships (blocking,
+    #   parent, sub_ticket, duplicate_of) live on GitHub.
+    attr_accessor :links
+    # @return [Array<PlanMyStuff::Approval>] manager approvals required on
+    #   this issue. See +Issue.request_approvals!+ and +Issue#fully_approved?+.
+    attr_accessor :approvals
+    # @return [Time, nil] when the issue entered "waiting on user reply" state
+    attr_accessor :waiting_on_user_at
+    # @return [Time, nil] when the issue entered "waiting on approval" state
+    attr_accessor :waiting_on_approval_at
+    # @return [Time, nil] when the next reminder event should fire for this issue
+    attr_accessor :next_reminder_at
+    # @return [Array<Integer>, nil] per-issue override of +config.reminder_days+;
+    #   applies to both waiting kinds
+    attr_accessor :reminder_days
+    # @return [Boolean] whether this issue was auto-closed by the inactivity sweep
+    attr_accessor :closed_by_inactivity
+    # @return [Time, nil] when the archive sweep tagged this issue as archived
+    attr_accessor :archived_at
 
     class << self
       # Builds an IssueMetadata from a parsed hash (e.g. from MetadataParser)
@@ -22,13 +42,21 @@ module PlanMyStuff
       #
       def from_hash(hash)
         metadata = new
-        apply_common_from_hash(metadata, hash)
+        apply_common_from_hash(metadata, hash, PlanMyStuff.configuration.custom_fields_for(:issue))
 
         metadata.responded_at = parse_time(hash[:responded_at])
         metadata.issues_url = hash[:issues_url]
-        metadata.priority_list = hash.fetch(:priority_list, false)
-        metadata.priority_list_priority = hash.fetch(:priority_list_priority, -1)
         metadata.visibility_allowlist = Array.wrap(hash[:visibility_allowlist])
+        metadata.commit_sha = hash[:commit_sha]
+        metadata.auto_complete = hash.fetch(:auto_complete, true)
+        metadata.links = normalize_links(hash[:links])
+        metadata.approvals = normalize_approvals(hash[:approvals])
+        metadata.waiting_on_user_at = parse_time(hash[:waiting_on_user_at])
+        metadata.waiting_on_approval_at = parse_time(hash[:waiting_on_approval_at])
+        metadata.next_reminder_at = parse_time(hash[:next_reminder_at])
+        metadata.reminder_days = normalize_reminder_days(hash[:reminder_days])
+        metadata.closed_by_inactivity = hash.fetch(:closed_by_inactivity, false)
+        metadata.archived_at = parse_time(hash[:archived_at])
 
         metadata
       end
@@ -42,13 +70,27 @@ module PlanMyStuff
       #
       def build(user:, visibility: 'public', custom_fields: {})
         metadata = new
-        apply_common_build(metadata, user: user, visibility: visibility, custom_fields_data: custom_fields)
+        apply_common_build(
+          metadata,
+          user: user,
+          visibility: visibility,
+          custom_fields_data: custom_fields,
+          custom_fields_schema: PlanMyStuff.configuration.custom_fields_for(:issue),
+        )
 
         metadata.responded_at = nil
         metadata.issues_url = build_issues_url(PlanMyStuff.configuration)
-        metadata.priority_list = false
-        metadata.priority_list_priority = -1
         metadata.visibility_allowlist = []
+        metadata.commit_sha = nil
+        metadata.auto_complete = true
+        metadata.links = []
+        metadata.approvals = []
+        metadata.waiting_on_user_at = nil
+        metadata.waiting_on_approval_at = nil
+        metadata.next_reminder_at = nil
+        metadata.reminder_days = nil
+        metadata.closed_by_inactivity = false
+        metadata.archived_at = nil
 
         metadata
       end
@@ -61,18 +103,79 @@ module PlanMyStuff
 
           config.issues_url_prefix.to_s
         end
+
+        # Builds a +PlanMyStuff::Link+ from each parsed entry. Malformed
+        # entries (wrong shape, missing fields, invalid values) are
+        # silently dropped so a single bad entry doesn't crash
+        # +Issue.find+ for an otherwise healthy issue.
+        #
+        # @param raw [Array, nil]
+        #
+        # @return [Array<PlanMyStuff::Link>]
+        #
+        def normalize_links(raw)
+          Array.wrap(raw).filter_map do |entry|
+            PlanMyStuff::Link.build!(entry)
+          rescue ActiveModel::ValidationError, ArgumentError
+            next
+          end
+        end
+
+        # Builds a +PlanMyStuff::Approval+ from each parsed entry.
+        # Malformed entries (wrong shape, missing fields, invalid values,
+        # unknown attributes) are silently dropped so a single bad entry
+        # doesn't crash +Issue.find+ for an otherwise healthy issue.
+        #
+        # @param raw [Array, nil]
+        #
+        # @return [Array<PlanMyStuff::Approval>]
+        #
+        def normalize_approvals(raw)
+          Array.wrap(raw).filter_map do |entry|
+            approval = PlanMyStuff::Approval.new(entry.transform_keys(&:to_sym))
+            approval.validate!
+            approval
+          rescue ActiveModel::ValidationError, ArgumentError, NoMethodError
+            next
+          end
+        end
+
+        # Normalizes a raw +reminder_days+ value from parsed metadata.
+        # Returns +nil+ when absent so callers can fall back to config;
+        # otherwise returns the array with non-integer entries dropped.
+        #
+        # @param raw [Object]
+        #
+        # @return [Array<Integer>, nil]
+        #
+        def normalize_reminder_days(raw)
+          return if raw.nil?
+
+          Array.wrap(raw).filter_map do |entry|
+            Integer(entry)
+          rescue ArgumentError, TypeError
+            next
+          end
+        end
     end
 
     def initialize
       super
-      @priority_list = false
-      @priority_list_priority = -1
       @visibility_allowlist = []
+      @auto_complete = true
+      @links = []
+      @approvals = []
+      @waiting_on_user_at = nil
+      @waiting_on_approval_at = nil
+      @next_reminder_at = nil
+      @reminder_days = nil
+      @closed_by_inactivity = false
+      @archived_at = nil
     end
 
     # @return [Boolean]
-    def priority_list?
-      !!priority_list
+    def auto_complete?
+      !!auto_complete
     end
 
     # @return [Boolean]
@@ -91,20 +194,28 @@ module PlanMyStuff
     def visible_to?(user)
       return true if public?
 
-      resolved = UserResolver.resolve(user)
-      return true if UserResolver.support?(resolved)
+      resolved = PlanMyStuff::UserResolver.resolve(user)
+      return true if PlanMyStuff::UserResolver.support?(resolved)
 
-      visibility_allowlist.include?(UserResolver.user_id(resolved))
+      visibility_allowlist.include?(PlanMyStuff::UserResolver.user_id(resolved))
     end
 
     # @return [Hash]
     def to_h
       super.merge(
-        responded_at: format_time(responded_at),
+        responded_at: PlanMyStuff.format_time(responded_at),
         issues_url: issues_url,
-        priority_list: priority_list,
-        priority_list_priority: priority_list_priority,
         visibility_allowlist: visibility_allowlist,
+        commit_sha: commit_sha,
+        auto_complete: auto_complete,
+        links: links.map(&:to_h),
+        approvals: approvals.map(&:to_h),
+        waiting_on_user_at: PlanMyStuff.format_time(waiting_on_user_at),
+        waiting_on_approval_at: PlanMyStuff.format_time(waiting_on_approval_at),
+        next_reminder_at: PlanMyStuff.format_time(next_reminder_at),
+        reminder_days: reminder_days,
+        closed_by_inactivity: closed_by_inactivity,
+        archived_at: PlanMyStuff.format_time(archived_at),
       )
     end
   end