plan_my_stuff 0.9.0 → 0.10.1

data/lib/plan_my_stuff/issue_extractions/approvals.rb

@@ -0,0 +1,370 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module IssueExtractions
+    module Approvals
+      # @return [Array<PlanMyStuff::Approval>] all required approvers (pending + approved + rejected)
+      def approvers
+        metadata.approvals
+      end
+
+      # @return [Array<PlanMyStuff::Approval>] approvers who have not yet acted (pending only; rejections are NOT
+      #   pending -- the approver has responded)
+      def pending_approvals
+        approvers.select(&:pending?)
+      end
+
+      # @return [Array<PlanMyStuff::Approval>] approvers who have rejected
+      def rejected_approvals
+        approvers.select(&:rejected?)
+      end
+
+      # @return [Boolean] true when at least one approver is required on this issue
+      def approvals_required?
+        approvers.present?
+      end
+
+      # @return [Boolean] true when approvers are required AND every approver has approved. A single rejection blocks
+      #   this gate until the approver revokes.
+      def fully_approved?
+        approvals_required? && approvers.all?(&:approved?)
+      end
+
+      # Adds approvers to this issue's required-approvals list. Idempotent: users already present are no-ops. Only
+      # support users may call this.
+      #
+      # Fires +plan_my_stuff.issue.approval_requested+ when any user is newly added. Also fires
+      # +plan_my_stuff.issue.approvals_invalidated+ (+trigger: :approver_added+) when the new approvers flip the issue
+      # out of a fully-approved state.
+      #
+      # @param user_ids [Array<Integer>, Integer]
+      # @param user [Object, nil] actor; must be a support user
+      #
+      # @return [Array<PlanMyStuff::Approval>] newly-added approvals (empty when all were duplicates)
+      #
+      def request_approvals!(user_ids:, user: nil)
+        guard_support!(user)
+        ids = Array.wrap(user_ids).map(&:to_i)
+
+        just_added, was_fully_approved = modify_approvals! do |current|
+          existing_ids = current.map(&:user_id)
+          new_ids = ids - existing_ids
+          added = new_ids.map { |id| PlanMyStuff::Approval.new(user_id: id, status: 'pending') }
+          [current + added, added]
+        end
+
+        finish_request_approvals(just_added, user: user, was_fully_approved: was_fully_approved)
+        just_added
+      end
+
+      # Removes approvers from this issue's required-approvals list. Only support users may call this. Removing a
+      # pending approver may flip the issue into +fully_approved?+ (fires +all_approved+). Removing an approved
+      # approver fires no events (state does not flip). Removing the last approver never fires aggregate events (issue
+      # no longer has +approvals_required?+).
+      #
+      # @param user_ids [Array<Integer>, Integer]
+      # @param user [Object, nil] actor; must be a support user
+      #
+      # @return [Array<PlanMyStuff::Approval>] removed approval records
+      #
+      def remove_approvers!(user_ids:, user: nil)
+        guard_support!(user)
+        ids = Array.wrap(user_ids).map(&:to_i)
+
+        just_removed, was_fully_approved = modify_approvals! do |current|
+          removed = current.select { |a| ids.include?(a.user_id) }
+          [current - removed, removed]
+        end
+
+        emit_aggregate_events(was_fully_approved: was_fully_approved, trigger: nil, user: user)
+        just_removed
+      end
+
+      # Flips the caller's approval to +approved+ from any other state (+pending+ or +rejected+). Only the approver
+      # themselves may call this. Fires +plan_my_stuff.issue.approval_granted+ and, when this flip completes the
+      # approval set, +plan_my_stuff.issue.all_approved+.
+      #
+      # @raise [PlanMyStuff::ValidationError] when the caller is not in the approvers list or is already approved
+      #
+      # @param user [Object, Integer] actor; must resolve to an approver
+      #
+      # @return [PlanMyStuff::Approval] the updated approval
+      #
+      def approve!(user:)
+        actor_id = resolve_actor_id!(user)
+
+        just_approved, was_fully_approved = modify_approvals! do |current|
+          approval = current.find { |a| a.user_id == actor_id }
+          raise(PlanMyStuff::ValidationError, "User #{actor_id} is not in the approvers list") if approval.nil?
+          raise(PlanMyStuff::ValidationError, "User #{actor_id} has already approved") if approval.approved?
+
+          approval.status = 'approved'
+          approval.approved_at = Time.current
+          approval.rejected_at = nil
+          [current, approval]
+        end
+
+        finish_state_change(:approval_granted, just_approved, user: user, was_fully_approved: was_fully_approved)
+        just_approved
+      end
+
+      # Flips the caller's approval to +rejected+ from any other state (+pending+ or +approved+). Only the approver
+      # themselves may call this. Fires +plan_my_stuff.issue.approval_rejected+ and, when this flip drops the issue
+      # out of +fully_approved?+ (i.e. the caller was the last +approved+ approver),
+      # +plan_my_stuff.issue.approvals_invalidated+ (+trigger: :rejected+).
+      #
+      # @raise [PlanMyStuff::ValidationError] when the caller is not in the approvers list or is already rejected
+      #
+      # @param user [Object, Integer] actor; must resolve to an approver
+      #
+      # @return [PlanMyStuff::Approval] the updated approval
+      #
+      def reject!(user:)
+        actor_id = resolve_actor_id!(user)
+
+        just_rejected, was_fully_approved = modify_approvals! do |current|
+          approval = current.find { |a| a.user_id == actor_id }
+          raise(PlanMyStuff::ValidationError, "User #{actor_id} is not in the approvers list") if approval.nil?
+          raise(PlanMyStuff::ValidationError, "User #{actor_id} has already rejected") if approval.rejected?
+
+          approval.status = 'rejected'
+          approval.rejected_at = Time.current
+          approval.approved_at = nil
+          [current, approval]
+        end
+
+        finish_state_change(
+          :approval_rejected,
+          just_rejected,
+          user: user,
+          was_fully_approved: was_fully_approved,
+          trigger: :rejected,
+        )
+        just_rejected
+      end
+
+      # Flips an approved or rejected record back to +pending+. Approvers may revoke their own response; support users
+      # may revoke any approver's response by passing +target_user_id:+. Non-support callers passing a
+      # +target_user_id:+ that is not their own raise +AuthorizationError+.
+      #
+      # Emits the granular event keyed off the source state: +plan_my_stuff.issue.approval_revoked+ from approved, or
+      # +plan_my_stuff.issue.rejection_revoked+ from rejected. When revoking an approval drops the issue out of
+      # +fully_approved?+, also fires +plan_my_stuff.issue.approvals_invalidated+ (+trigger: :revoked+). Revoking a
+      # rejection cannot change +fully_approved?+ (the issue was already gated), so no aggregate event fires.
+      #
+      # @raise [PlanMyStuff::AuthorizationError] when a non-support caller targets another user
+      # @raise [PlanMyStuff::ValidationError] when the target is not in the approvers list or is currently pending
+      #
+      # @param user [Object, Integer] the caller
+      # @param target_user_id [Integer, nil] approver whose response should be revoked; defaults to the caller
+      #
+      # @return [PlanMyStuff::Approval] the updated approval
+      #
+      def revoke_approval!(user:, target_user_id: nil)
+        actor_id = resolve_actor_id!(user)
+        caller_is_support = PlanMyStuff::UserResolver.support?(PlanMyStuff::UserResolver.resolve(user))
+        target_id = target_user_id&.to_i || actor_id
+
+        if !caller_is_support && target_id != actor_id
+          raise(PlanMyStuff::AuthorizationError, "Only support users may revoke another user's response")
+        end
+
+        revoked_from = nil
+        just_revoked, was_fully_approved = modify_approvals! do |current|
+          approval = current.find { |a| a.user_id == target_id }
+          raise(PlanMyStuff::ValidationError, "User #{target_id} is not in the approvers list") if approval.nil?
+          if approval.pending?
+            raise(PlanMyStuff::ValidationError, "User #{target_id} has not responded -- nothing to revoke")
+          end
+
+          revoked_from = approval.status
+          approval.status = 'pending'
+          approval.approved_at = nil
+          approval.rejected_at = nil
+          [current, approval]
+        end
+
+        event = (revoked_from == 'approved') ? :approval_revoked : :rejection_revoked
+        finish_state_change(
+          event,
+          just_revoked,
+          user: user,
+          was_fully_approved: was_fully_approved,
+          trigger: (event == :approval_revoked) ? :revoked : nil,
+        )
+        just_revoked
+      end
+
+      private
+
+        # Captures +fully_approved?+ state, yields the current approvals (deep-copied) for mutation, persists the new
+        # list to GitHub, and reloads +self+. Returns +[extra, was_fully_approved]+.
+        #
+        # @yieldparam current [Array<PlanMyStuff::Approval>] deep-copied approvals
+        # @yieldreturn [Array(Array<PlanMyStuff::Approval>, Object)] +[new_list, extra]+
+        #
+        # @return [Array(Object, Boolean)]
+        #
+        def modify_approvals!
+          was_fully_approved = fully_approved?
+          was_pending_count = metadata.approvals.count(&:pending?)
+          current = metadata.approvals.map { |a| PlanMyStuff::Approval.new(a.attributes) }
+
+          new_list, extra = yield(current)
+
+          new_pending_count = new_list.count(&:pending?)
+          metadata_updates = { approvals: new_list.map(&:to_h) }
+          metadata_updates.merge!(waiting_on_approval_metadata_updates(was_pending_count, new_pending_count))
+
+          self.class.update!(number: number, repo: repo, metadata: metadata_updates)
+          reload
+
+          sync_waiting_on_approval_label!(was_pending_count, new_pending_count)
+
+          [extra, was_fully_approved]
+        end
+
+        # Computes the metadata delta for the waiting-on-approval timer based on the change in pending-approval count.
+        # The timer resets only when pending count goes UP (add approver, revoke-to-pending) so that remaining pending
+        # approvers keep their original schedule when a peer approves. Drop-to-zero clears the timer entirely.
+        #
+        # @param was [Integer] pending count before the mutation
+        # @param now [Integer] pending count after the mutation
+        #
+        # @return [Hash]
+        #
+        def waiting_on_approval_metadata_updates(was, now)
+          if now > was
+            ts = Time.now.utc
+            {
+              waiting_on_approval_at: PlanMyStuff.format_time(ts),
+              next_reminder_at: format_next_reminder_at(from: ts),
+            }
+          elsif now.zero? && was.positive?
+            {
+              waiting_on_approval_at: nil,
+              next_reminder_at: metadata.waiting_on_user_at ? PlanMyStuff.format_time(metadata.next_reminder_at) : nil,
+            }
+          else
+            {}
+          end
+        end
+
+        # Adds or removes the configured waiting-on-approval label when the pending-approval count crosses the zero
+        # boundary. Mutations that stay on the same side of zero leave the label untouched.
+        #
+        # @param was [Integer] pending count before the mutation
+        # @param now [Integer] pending count after the mutation
+        #
+        # @return [void]
+        #
+        def sync_waiting_on_approval_label!(was, now)
+          label = PlanMyStuff.configuration.waiting_on_approval_label
+
+          if now.positive? && was.zero?
+            PlanMyStuff::Label.ensure!(repo: repo, name: label)
+            PlanMyStuff::Label.add!(issue: self, labels: [label]) if labels.exclude?(label)
+          elsif now.zero? && was.positive?
+            PlanMyStuff::Label.remove!(issue: self, labels: [label]) if labels.include?(label)
+          end
+        end
+
+        # Ensures +user+ resolves to a support user. +nil+ user is treated as unauthorized.
+        #
+        # @raise [PlanMyStuff::AuthorizationError] when the actor is not a support user
+        #
+        # @param user [Object, Integer, nil]
+        #
+        # @return [void]
+        #
+        def guard_support!(user)
+          resolved = PlanMyStuff::UserResolver.resolve(user)
+          return if resolved && PlanMyStuff::UserResolver.support?(resolved)
+
+          raise(PlanMyStuff::AuthorizationError, 'Only support users may manage approvers')
+        end
+
+        # Resolves +user+ to an integer user_id.
+        #
+        # @raise [ArgumentError] when user is nil
+        #
+        # @param user [Object, Integer]
+        #
+        # @return [Integer]
+        #
+        def resolve_actor_id!(user)
+          raise(ArgumentError, 'user: is required') if user.nil?
+
+          resolved = PlanMyStuff::UserResolver.resolve(user)
+          PlanMyStuff::UserResolver.user_id(resolved)
+        end
+
+        # Fires +approval_requested+ (when any users were newly added) and, if the aggregate state flipped out of
+        # fully-approved, the +approvals_invalidated+ follow-up.
+        #
+        # @param added [Array<PlanMyStuff::Approval>]
+        # @param user [Object, nil]
+        # @param was_fully_approved [Boolean]
+        #
+        # @return [void]
+        #
+        def finish_request_approvals(added, user:, was_fully_approved:)
+          return if added.empty?
+
+          PlanMyStuff::Notifications.instrument(
+            'issue.approval_requested',
+            self,
+            user: user,
+            approvals: added,
+          )
+          emit_aggregate_events(was_fully_approved: was_fully_approved, trigger: :approver_added, user: user)
+        end
+
+        # Fires the granular event (+approval_granted+ / +approval_revoked+) then any aggregate follow-up triggered
+        # by the state flip.
+        #
+        # @param event [Symbol] +:approval_granted+ or +:approval_revoked+
+        # @param approval [PlanMyStuff::Approval]
+        # @param user [Object, nil]
+        # @param was_fully_approved [Boolean]
+        # @param trigger [Symbol, nil] passed through to +approvals_invalidated+
+        #
+        # @return [void]
+        #
+        def finish_state_change(event, approval, user:, was_fully_approved:, trigger: nil)
+          PlanMyStuff::Notifications.instrument(
+            "issue.#{event}",
+            self,
+            user: user,
+            approval: approval,
+          )
+          emit_aggregate_events(was_fully_approved: was_fully_approved, trigger: trigger, user: user)
+        end
+
+        # Fires +all_approved+ or +approvals_invalidated+ based on whether +fully_approved?+ flipped. Suppresses
+        # +approvals_invalidated+ when the issue no longer has any approvers required (dropping the list to empty is
+        # not an invalidation).
+        #
+        # @param was_fully_approved [Boolean]
+        # @param trigger [Symbol, nil]
+        # @param user [Object, nil]
+        #
+        # @return [void]
+        #
+        def emit_aggregate_events(was_fully_approved:, trigger:, user:)
+          now = fully_approved?
+
+          if !was_fully_approved && now
+            PlanMyStuff::Notifications.instrument('issue.all_approved', self, user: user)
+          elsif was_fully_approved && !now && approvals_required?
+            PlanMyStuff::Notifications.instrument(
+              'issue.approvals_invalidated',
+              self,
+              user: user,
+              trigger: trigger,
+            )
+          end
+        end
+    end
+  end
+end