plan_my_stuff 0.1.0 → 1.0.0

data/lib/plan_my_stuff/reminders/fire.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module Reminders
+    # Emits +issue_reminder_due.plan_my_stuff+ 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 ActiveRecord::RecordNotFound
+            next
+          end
+        end
+
+        # @return [Array<Integer>]
+        def effective_reminder_days
+          (@issue.metadata.reminder_days.presence || PlanMyStuff.configuration.reminder_days).sort
+        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 +PlanMyStuff.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

data/lib/plan_my_stuff/reminders/sweep.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module Reminders
+    # Walks a single repo's waiting issues, dispatching each to +Closer+
+    # when past the inactivity ceiling or +Fire+ when a reminder is due.
+    # Called from +RemindersSweepJob+; no ActiveJob dependency here so
+    # the logic stays unit-testable and callable from a plain rake task.
+    class Sweep
+      # @param repo [Symbol, String] repo key or full name
+      # @param now [Time] clock reference
+      #
+      def initialize(repo:, now: Time.now.utc)
+        @repo = repo
+        @now = now.utc
+      end
+
+      # Runs the sweep. No-op when +config.reminders_enabled+ is false.
+      #
+      # @return [void]
+      #
+      def call
+        return unless PlanMyStuff.configuration.reminders_enabled
+
+        candidates.each do |issue|
+          if PlanMyStuff::Reminders::Closer.should_close?(issue, now: @now)
+            PlanMyStuff::Reminders::Closer.new(issue, now: @now).call
+          elsif PlanMyStuff::Reminders::Fire.ready?(issue, now: @now)
+            PlanMyStuff::Reminders::Fire.new(issue, now: @now).call
+          end
+        end
+      end
+
+      private
+
+        # Issues carrying either waiting label, deduplicated by number.
+        # GitHub's labels filter is AND across multiple labels, so we
+        # query each label separately and merge.
+        #
+        # @return [Array<PlanMyStuff::Issue>]
+        #
+        def candidates
+          user_label = PlanMyStuff.configuration.waiting_on_user_label
+          approval_label = PlanMyStuff.configuration.waiting_on_approval_label
+
+          by_label = [user_label, approval_label].flat_map do |label|
+            PlanMyStuff::Issue.list(repo: @repo, labels: [label], state: :open)
+          end
+
+          by_label.uniq(&:number)
+        end
+    end
+  end
+end

data/lib/plan_my_stuff/reminders.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Follow-up reminder engine. The +Sweep+ class walks the waiting issues
+  # in a repo and dispatches to +Fire+ for reminders that are due or
+  # +Closer+ for issues that have exceeded the inactivity threshold.
+  #
+  # Entry point for the sweep lives in +RemindersSweepJob+; this module
+  # holds the POROs so they can be unit-tested without ActiveJob.
+  module Reminders
+  end
+end

data/lib/plan_my_stuff/repo.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  class Repo
+    # @return [Symbol, nil] configured key (e.g. :my_repo)
+    attr_reader :key
+
+    # @return [String] repo name (e.g. "MyRepository")
+    attr_reader :name
+
+    # @return [String] organization name (e.g. "YourOrgName")
+    attr_reader :organization
+
+    delegate :split, to: :to_s
+
+    class << self
+      # Builds a Repo instance from a Symbol key, full name String, or nil (default).
+      #
+      # @raise [PlanMyStuff::ConfigurationError] if repo is not provided and cannot be resolved from config
+      # @raise [ArgumentError] if repo cannot be resolved
+      # @raise [ArgumentError] if repo is invalid format
+      #
+      # @param repo [Symbol, String, PlanMyStuff::Repo, nil]
+      #
+      # @return [PlanMyStuff::Repo]
+      #
+      def resolve!(repo = nil)
+        return repo if repo.is_a?(PlanMyStuff::Repo)
+
+        repo ||= PlanMyStuff.configuration.default_repo
+
+        if repo.nil?
+          raise(
+            PlanMyStuff::ConfigurationError,
+            'No repo provided and config.default_repo is not set. ' \
+              'Either pass repo: explicitly or set config.default_repo in your initializer.',
+          )
+        end
+
+        case repo
+        when Symbol
+          full_name = PlanMyStuff.configuration.repos[repo]
+          raise(ArgumentError, "Unknown repo key: #{repo.inspect}") if full_name.nil?
+
+          from_full_name!(full_name, key: repo)
+        when String
+          if PlanMyStuff.configuration.repos.has_key?(repo.to_sym)
+            resolve!(repo.to_sym)
+          else
+            key = PlanMyStuff.configuration.repos.key(repo)
+            from_full_name!(repo, key: key)
+          end
+        else
+          raise(ArgumentError, "Cannot resolve repo: #{repo.inspect}")
+        end
+      end
+
+      # Reverse lookup for the +Issue#to_param+ prefix: finds the configured repo whose nickname (per
+      # +config.repo_nickname_for+) matches +nickname+ and returns its +Repo+ instance.
+      #
+      # @raise [ArgumentError] if no configured repo has the given nickname
+      #
+      # @param nickname [String]
+      #
+      # @return [PlanMyStuff::Repo]
+      #
+      def from_nickname!(nickname)
+        config = PlanMyStuff.configuration
+        match = config.repos.keys.find { |key| config.repo_nickname_for(key) == nickname }
+        raise(ArgumentError, "Unknown repo nickname: #{nickname.inspect}") if match.nil?
+
+        resolve!(match)
+      end
+
+      private
+
+        # @raise [ArgumentError] if full_name is not in "Org/Repo" format
+        #
+        # @param full_name [String] e.g. "YourOrgName/MyRepository"
+        # @param key [Symbol, nil]
+        #
+        # @return [PlanMyStuff::Repo]
+        #
+        def from_full_name!(full_name, key: nil)
+          org, name = full_name.split('/', 2)
+
+          raise(ArgumentError, "Invalid repo full_name: #{full_name.inspect}") if name.nil?
+
+          new(name: name, organization: org, key: key)
+        end
+    end
+
+    # @param name [String]
+    # @param organization [String]
+    # @param key [Symbol, nil]
+    #
+    def initialize(name:, organization:, key: nil)
+      @key = key
+      @name = name
+      @organization = organization
+    end
+
+    # @return [String] full repo path (e.g. "YourOrgName/MyRepository")
+    def full_name
+      "#{organization}/#{name}"
+    end
+
+    # Human-readable repo label used as the +Issue#to_param+ prefix. Resolves through +config.repo_nickname_for+
+    # when this repo carries a configured +key+; falls back to the bare repo +name+ for unconfigured repos.
+    #
+    # @return [String]
+    #
+    def nickname
+      return PlanMyStuff.configuration.repo_nickname_for(key) if key
+
+      name
+    end
+
+    # @see #full_name
+    alias to_s full_name
+
+    # Enables implicit string coercion so Repo instances behave as strings when passed to Octokit or compared with
+    # String#==.
+    #
+    # @see #full_name
+    alias to_str full_name
+
+    # Compares by full_name. Accepts another Repo or a String.
+    #
+    # @param other [PlanMyStuff::Repo, String, Object]
+    #
+    # @return [Boolean]
+    #
+    def ==(other)
+      case other
+      when PlanMyStuff::Repo
+        full_name == other.full_name
+      when String
+        full_name == other
+      else
+        super
+      end
+    end
+  end
+end