plan_my_stuff 0.8.0 → 0.10.0

data/lib/plan_my_stuff/issue.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+require_relative 'issue_extractions/approvals'
+require_relative 'issue_extractions/links'
+require_relative 'issue_extractions/viewers'
+require_relative 'issue_extractions/waiting'
+
 module PlanMyStuff
   # Wraps a GitHub issue with parsed PMS metadata and comments.
   # Class methods provide the public API for CRUD operations.
@@ -9,6 +14,11 @@ module PlanMyStuff
   # - `Issue.create!` / `Issue.find` / `Issue.list` return persisted instances
   # - `issue.save!` / `issue.update!` / `issue.reload` for persistence
   class Issue < PlanMyStuff::ApplicationRecord
+    include PlanMyStuff::IssueExtractions::Approvals
+    include PlanMyStuff::IssueExtractions::Links
+    include PlanMyStuff::IssueExtractions::Viewers
+    include PlanMyStuff::IssueExtractions::Waiting
+
     # @return [Integer, nil] GitHub issue number
     attribute :number, :integer
     # @return [String, nil] full body as stored on GitHub
@@ -363,7 +373,11 @@ module PlanMyStuff
           canonical =
             case value
             when String
-              value
+              begin
+                resolve_issue_type!(value.to_sym)
+              rescue ArgumentError
+                value
+              end
             when Symbol
               ISSUE_TYPE_NICKNAMES[value] || raise(
                 ArgumentError,
@@ -486,311 +500,6 @@ module PlanMyStuff
       "#{base}?repo=#{URI.encode_www_form_component(repo.full_name)}"
     end
 
-    # @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 user IDs to this issue's visibility allowlist (non-support users whose ID is in the allowlist can see
-    # internal comments).
-    #
-    # Fires +plan_my_stuff.issue.viewers_added+.
-    #
-    # @param user_ids [Array<Integer>, Integer]
-    # @param user [Object, nil] actor for the notification event
-    #
-    # @return [Array<Integer>] the new allowlist
-    #
-    def add_viewers!(user_ids:, user: nil)
-      ids = Array.wrap(user_ids)
-      modify_allowlist! { |allowlist| allowlist | ids }
-      PlanMyStuff::Notifications.instrument('issue.viewers_added', self, user: user, user_ids: ids)
-      metadata.visibility_allowlist
-    end
-
-    # Removes user IDs from this issue's visibility allowlist.
-    #
-    # Fires +plan_my_stuff.issue.viewers_removed+.
-    #
-    # @param user_ids [Array<Integer>, Integer]
-    # @param user [Object, nil] actor for the notification event
-    #
-    # @return [Array<Integer>] the new allowlist
-    #
-    def remove_viewers!(user_ids:, user: nil)
-      ids = Array.wrap(user_ids)
-      modify_allowlist! { |allowlist| allowlist - ids }
-      PlanMyStuff::Notifications.instrument('issue.viewers_removed', self, user: user, user_ids: ids)
-      metadata.visibility_allowlist
-    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
-
-    # 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)
-
-      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),
-        },
-      )
-      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)
-
-      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,
-        },
-      )
-      reload
-    end
-
-    # Reopens an issue that was auto-closed by the inactivity sweep, clears +metadata.closed_by_inactivity+, and
-    # emits +plan_my_stuff.issue.reopened_by_reply+ 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)
-
-      self.class.update!(
-        number: number,
-        repo: repo,
-        state: :open,
-        metadata: { closed_by_inactivity: false },
-      )
-      reload
-
-      PlanMyStuff::Notifications.instrument(
-        'issue.reopened_by_reply',
-        self,
-        user: user,
-        comment: comment,
-      )
-      self
-    end
-
     # Tags the issue with the configured +archived_label+, removes it from every Projects V2 board it belongs to,
     # locks its conversation on GitHub, and stamps +metadata.archived_at+. Emits +plan_my_stuff.issue.archived+ on
     # success.
@@ -942,255 +651,6 @@ module PlanMyStuff
       super
     end
 
-    # Delegates visibility check to metadata.
-    # Non-PMS issues are always visible.
-    #
-    # @param user [Object, Integer] user object or user_id
-    #
-    # @return [Boolean]
-    #
-    def visible_to?(user)
-      if pms_issue?
-        metadata.visible_to?(user)
-      else
-        PlanMyStuff::UserResolver.support?(PlanMyStuff::UserResolver.resolve(user))
-      end
-    end
-
-    # Lazy-memoized array of +Issue+ objects for +:related+ links. Silently drops targets that 404 so a dangling
-    # pointer doesn't break the rest of the list.
-    #
-    # @return [Array<PlanMyStuff::Issue>]
-    #
-    def related
-      links_cache[:related] ||= fetch_related
-    end
-
-    # Adds a +:related+ link to +target+ and, unless this call is already a reciprocal, mirrors the link back on
-    # +target+ so the pairing is symmetric. Dedups on +(type, issue_number, repo)+ - re-adding is a no-op.
-    #
-    # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
-    # @param user [Object, nil] actor for notification events
-    # @param reciprocal [Boolean] internal flag; set by the mirror call
-    #
-    # @return [PlanMyStuff::Link]
-    #
-    def add_related!(target, user: nil, reciprocal: false)
-      link = build_link!(target, type: :related)
-      validate_not_self!(link)
-
-      existing = current_links
-      return link if existing.include?(link)
-
-      persist_links!(existing + [link])
-      unless reciprocal
-        mirror_on_target(link, user: user) { |other| other.add_related!(self, user: user, reciprocal: true) }
-      end
-
-      link
-    end
-
-    # Removes a +:related+ link to +target+ and, unless this call is already a reciprocal, mirrors the removal on
-    # +target+. No-op when the link isn't present locally.
-    #
-    # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
-    # @param user [Object, nil]
-    # @param reciprocal [Boolean]
-    #
-    # @return [PlanMyStuff::Link]
-    #
-    def remove_related!(target, user: nil, reciprocal: false)
-      link = build_link!(target, type: :related)
-      validate_not_self!(link)
-
-      existing = current_links
-      return link if existing.exclude?(link)
-
-      persist_links!(existing.reject { |l| l == link })
-      unless reciprocal
-        mirror_on_target(link, user: user) { |other| other.remove_related!(self, user: user, reciprocal: true) }
-      end
-
-      link
-    end
-
-    # Lazy-memoized parent issue via GitHub's native sub-issues API. GitHub enforces at most one parent per issue.
-    #
-    # @return [PlanMyStuff::Issue, nil]
-    #
-    def parent
-      return links_cache[:parent] if links_cache.key?(:parent)
-
-      links_cache[:parent] = fetch_parent
-    end
-
-    # Lazy-memoized sub-issues via GitHub's native sub-issues API.
-    #
-    # @return [Array<PlanMyStuff::Issue>]
-    #
-    def sub_tickets
-      links_cache[:sub_tickets] ||= fetch_sub_tickets
-    end
-
-    # Adds +target+ as a sub-issue of self via +POST /issues/{number}/sub_issues+. Native GitHub action;
-    # notifications are handled by GitHub itself.
-    #
-    # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
-    #
-    # @return [PlanMyStuff::Link]
-    #
-    def add_sub_issue!(target)
-      mutate_sub_issue!(target, method: :post, path: sub_issues_path)
-    end
-
-    # Removes +target+ as a sub-issue of self via +DELETE /issues/{number}/sub_issue+ (singular).
-    #
-    # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
-    #
-    # @return [PlanMyStuff::Link]
-    #
-    def remove_sub_issue!(target)
-      mutate_sub_issue!(target, method: :delete, path: remove_sub_issue_path)
-    end
-
-    # Makes +target+ the parent of self. If self already has a parent, it is detached first. Returns a +Link+
-    # describing the new +:parent+ relationship.
-    #
-    # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
-    #
-    # @return [PlanMyStuff::Link]
-    #
-    def set_parent!(target)
-      parent.presence&.remove_sub_issue!(self)
-
-      target_issue = resolve_target_issue(target, type: :parent)
-      target_issue.add_sub_issue!(self)
-      invalidate_links_cache!
-
-      build_link!(target_issue, type: :parent)
-    end
-
-    # Detaches self from its current parent, if any. Returns the +Link+ that was removed, or nil when there was no
-    # parent.
-    #
-    # @return [PlanMyStuff::Link, nil]
-    #
-    def remove_parent!
-      current = parent
-      return if current.nil?
-
-      current.remove_sub_issue!(self)
-      invalidate_links_cache!
-
-      build_link!(current, type: :parent)
-    end
-
-    # Lazy-memoized issues that block self (i.e. self is blocked by each returned issue) via GitHub's native
-    # issue-dependency REST API.
-    #
-    # @return [Array<PlanMyStuff::Issue>]
-    #
-    def blocked_by
-      links_cache[:blocked_by] ||= fetch_dependencies('blocked_by')
-    end
-
-    # Lazy-memoized issues that self blocks.
-    #
-    # @return [Array<PlanMyStuff::Issue>]
-    #
-    def blocking
-      links_cache[:blocking] ||= fetch_dependencies('blocking')
-    end
-
-    # Records that +target+ blocks self. Native GitHub action; notifications are handled by GitHub itself.
-    #
-    # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
-    #
-    # @return [PlanMyStuff::Link]
-    #
-    def add_blocker!(target)
-      link = build_link!(target, type: :blocked_by)
-      validate_not_self!(link)
-
-      target_issue = resolve_target_issue(target, type: :blocked_by)
-      PlanMyStuff.client.rest(
-        :post,
-        dependency_path('blocked_by'),
-        { issue_id: target_issue.__send__(:require_github_id!) },
-      )
-      invalidate_links_cache!
-      link
-    end
-
-    # Removes the record that +target+ blocks self.
-    #
-    # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
-    #
-    # @return [PlanMyStuff::Link]
-    #
-    def remove_blocker!(target)
-      link = build_link!(target, type: :blocked_by)
-      validate_not_self!(link)
-
-      target_issue = resolve_target_issue(target, type: :blocked_by)
-      PlanMyStuff.client.rest(
-        :delete,
-        "#{dependency_path('blocked_by')}/#{target_issue.__send__(:require_github_id!)}",
-      )
-      invalidate_links_cache!
-      link
-    end
-
-    # Lazy-memoized issue that self was marked as duplicate of, via GitHub's native close-as-duplicate. Returns nil
-    # for issues that are open or closed for other reasons.
-    #
-    # @return [PlanMyStuff::Issue, nil]
-    #
-    def duplicate_of
-      return links_cache[:duplicate_of] if links_cache.key?(:duplicate_of)
-
-      links_cache[:duplicate_of] = fetch_duplicate_of
-    end
-
-    # Closes self as a duplicate of +target+ via GitHub's native close-as-duplicate, carrying over viewers,
-    # assignees, and a back-pointer comment on the target.
-    #
-    # Side effects, in order:
-    # 1. Resolves +target+; raises +ValidationError+ if missing.
-    # 2. Raises +ValidationError+ when self is already closed.
-    # 3. Merges self's +visibility_allowlist+ onto target.
-    # 4. Merges self's assignees onto target.
-    # 5. Posts a PMS comment on target with the back-pointer.
-    # 6. Closes self with +state_reason: :duplicate+ and
-    #    +duplicate_of: { owner:, repo:, number: }+.
-    # 7. Reloads self; invalidates link caches.
-    # 8. Fires +plan_my_stuff.issue.marked_duplicate+.
-    #
-    # Partial failures are not rolled back - GitHub retains whatever side effects succeeded before the failing step.
-    #
-    # @raise [PlanMyStuff::ValidationError] when the issue is already closed
-    #
-    # @param target [PlanMyStuff::Issue, PlanMyStuff::Link, Hash]
-    # @param user [Object, nil] actor for notification + comment
-    #
-    # @return [PlanMyStuff::Link]
-    #
-    def mark_duplicate!(target, user: nil)
-      raise(PlanMyStuff::ValidationError, 'Cannot mark a closed issue as duplicate') if state == 'closed'
-
-      target_issue = resolve_duplicate_target!(target)
-      merge_visibility_allowlist_onto!(target_issue)
-      merge_assignees_onto!(target_issue)
-      post_duplicate_back_pointer!(target_issue, user: user)
-      close_as_duplicate!(target_issue)
-
-      reload
-      invalidate_links_cache!
-      PlanMyStuff::Notifications.instrument('issue.marked_duplicate', self, target: target_issue, user: user)
-
-      build_link!(target_issue, type: :duplicate_of)
-    end
-
     # GitHub GraphQL node ID (required for native sub-issue mutations). Read from the hydrated REST response.
     #
     # @return [String, nil]
@@ -1210,193 +670,6 @@ module PlanMyStuff
 
     private
 
-      # Yields +self.metadata.visibility_allowlist+ for modification, persists the updated allowlist via the
-      # class-level +update!+, and reloads +self+ so subsequent reads see the fresh state.
-      #
-      # @yieldparam allowlist [Array<Integer>]
-      # @yieldreturn [Array<Integer>] the new allowlist
-      #
-      # @return [void]
-      #
-      def modify_allowlist!
-        new_allowlist = yield(Array.wrap(metadata.visibility_allowlist))
-        self.class.update!(
-          number: number,
-          repo: repo,
-          metadata: { visibility_allowlist: new_allowlist },
-        )
-        reload
-      end
-
-      # 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
-
       # Populates this instance from a GitHub API response.
       #
       # @param github_issue [Object] Octokit issue response
@@ -1454,20 +727,6 @@ module PlanMyStuff
         invalidate_links_cache!
       end
 
-      # 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
-
       # Fires the appropriate notification event for an update: +issue.closed+ or +issue.reopened+ on a state
       # transition, otherwise +issue.updated+ with the captured dirty-tracking diff.
       #
@@ -1487,50 +746,6 @@ module PlanMyStuff
         end
       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
-
       # Full-write persistence path for an already-persisted issue. Delegates to +Issue.update!+ passing the full
       # in-memory state (title/state/labels plus the current +metadata+ object so the class method serializes it
       # authoritatively). Only passes +body:+ when +@body_dirty+, so the PMS body comment is rewritten exactly when
@@ -1649,69 +864,6 @@ module PlanMyStuff
         PlanMyStuff::Comment.list(issue: self)
       end
 
-      # @return [Hash{Symbol => Array}]
-      def links_cache
-        @links_cache ||= {}
-      end
-
-      # Clears all memoized link readers. Called from +#hydrate_from_github+ and after any successful write.
-      #
-      # @return [void]
-      #
-      def invalidate_links_cache!
-        @links_cache = {}
-      end
-
-      # Normalizes +target+ to a +PlanMyStuff::Link+ with the source repo defaulting to self's repo.
-      #
-      # @return [PlanMyStuff::Link]
-      #
-      def build_link!(target, type:)
-        PlanMyStuff::Link.build!(target, type: type, source_repo: repo&.full_name)
-      end
-
-      # @raise [PlanMyStuff::ValidationError] when target is the same issue (self-link)
-      #
-      # @return [void]
-      #
-      def validate_not_self!(link)
-        return if link.issue_number != number
-        return unless link.same_repo?(repo)
-
-        raise(PlanMyStuff::ValidationError, 'Cannot link an issue to itself')
-      end
-
-      # Reads +metadata.links+ and coerces any legacy hash entries to +Link+ instances. Invalid entries are dropped.
-      #
-      # @return [Array<PlanMyStuff::Link>]
-      #
-      def current_links
-        metadata.links.filter_map do |entry|
-          next entry if entry.is_a?(PlanMyStuff::Link)
-
-          PlanMyStuff::Link.build!(entry)
-        rescue ActiveModel::ValidationError, ArgumentError
-          next
-        end
-      end
-
-      # Writes the given link array back to GitHub via +Issue.update!+ and updates local metadata so subsequent
-      # in-memory reads see the change without a +reload+.
-      #
-      # @param new_links [Array<PlanMyStuff::Link>]
-      #
-      # @return [void]
-      #
-      def persist_links!(new_links)
-        self.class.update!(
-          number: number,
-          repo: repo,
-          metadata: { links: new_links.map(&:to_h) },
-        )
-        metadata.links = new_links
-        invalidate_links_cache!
-      end
-
       # Walks every Projects V2 board this issue sits on and deletes the corresponding item. Paginates via
       # +LIST_ISSUE_PROJECT_ITEMS+ with a safety cap to avoid runaway loops. Delete failures propagate.
       #
@@ -1746,135 +898,6 @@ module PlanMyStuff
         end
       end
 
-      # Attempts the reciprocal write on +link+'s target. On failure, fires
-      # +plan_my_stuff.issue.link_reciprocal_failed+ so the consuming app can surface the half-written pairing.
-      #
-      # @param link [PlanMyStuff::Link]
-      # @param user [Object, nil]
-      #
-      # @return [void]
-      #
-      def mirror_on_target(link, user:)
-        target = PlanMyStuff::Issue.find(link.issue_number, repo: link.repo)
-        yield(target)
-      rescue PlanMyStuff::Error, Octokit::Error => e
-        PlanMyStuff::Notifications.instrument(
-          'issue.link_reciprocal_failed',
-          self,
-          user: user,
-          link: link,
-          error: e.message,
-        )
-      end
-
-      # @return [Array<PlanMyStuff::Issue>]
-      def fetch_related
-        current_links.filter_map do |link|
-          next unless link.type == 'related'
-
-          PlanMyStuff::Issue.find(link.issue_number, repo: link.repo)
-        rescue PlanMyStuff::APIError, Octokit::NotFound
-          next
-        end
-      end
-
-      # @return [PlanMyStuff::Issue, nil]
-      def fetch_parent
-        response = PlanMyStuff.client.rest(:get, parent_path)
-        return if response.blank?
-
-        parent_number = response.respond_to?(:number) ? response.number : response[:number]
-        PlanMyStuff::Issue.find(parent_number, repo: repo)
-      rescue PlanMyStuff::APIError => e
-        return if e.status == 404
-
-        raise
-      end
-
-      # @return [Array<PlanMyStuff::Issue>]
-      def fetch_sub_tickets
-        response = PlanMyStuff.client.rest(:get, sub_issues_path)
-        Array.wrap(response).filter_map do |row|
-          sub_number = row.respond_to?(:number) ? row.number : row[:number]
-          PlanMyStuff::Issue.find(sub_number, repo: repo)
-        rescue PlanMyStuff::APIError, Octokit::NotFound
-          next
-        end
-      end
-
-      # Normalizes +target+ to a fully-hydrated +Issue+ (fetching when we only have a +Link+ or hash). Used by
-      # +set_parent!+ / +remove_parent!+ to invert the call back through +#add_sub_issue!+ / +#remove_sub_issue!+ on
-      # the parent side.
-      #
-      # @return [PlanMyStuff::Issue]
-      #
-      def resolve_target_issue(target, type:)
-        return target if target.is_a?(PlanMyStuff::Issue)
-
-        link = build_link!(target, type: type)
-        PlanMyStuff::Issue.find(link.issue_number, repo: link.repo)
-      end
-
-      # Shared path for add_sub_issue! / remove_sub_issue!. Builds the link, resolves the target, runs the
-      # mutation, busts caches.
-      #
-      # @return [PlanMyStuff::Link]
-      #
-      def mutate_sub_issue!(target, method:, path:)
-        link = build_link!(target, type: :sub_ticket)
-        validate_not_self!(link)
-
-        target_issue = resolve_target_issue(target, type: :sub_ticket)
-        PlanMyStuff.client.rest(
-          method,
-          path,
-          { sub_issue_id: target_issue.__send__(:require_github_id!) },
-        )
-        invalidate_links_cache!
-        link
-      end
-
-      # @return [String]
-      def parent_path
-        "/repos/#{repo.organization}/#{repo.name}/issues/#{number}/parent"
-      end
-
-      # @return [String]
-      def sub_issues_path
-        "/repos/#{repo.organization}/#{repo.name}/issues/#{number}/sub_issues"
-      end
-
-      # GitHub's REMOVE endpoint is +/sub_issue+ (singular), distinct from the list/add path +/sub_issues+ (plural).
-      #
-      # @return [String]
-      #
-      def remove_sub_issue_path
-        "/repos/#{repo.organization}/#{repo.name}/issues/#{number}/sub_issue"
-      end
-
-      # Fetches one side of the native issue-dependency graph for self (+blocked_by+ or +blocking+) via REST.
-      # Response is an array of Issue objects; we map through +Issue.find+ to get fully hydrated instances (the
-      # dependency endpoint returns a slim projection).
-      #
-      # @param side [String] "blocked_by" or "blocking"
-      #
-      # @return [Array<PlanMyStuff::Issue>]
-      #
-      def fetch_dependencies(side)
-        response = PlanMyStuff.client.rest(:get, dependency_path(side))
-        Array.wrap(response).filter_map do |row|
-          number = row.respond_to?(:number) ? row.number : row[:number]
-          PlanMyStuff::Issue.find(number, repo: repo)
-        rescue PlanMyStuff::APIError, Octokit::NotFound
-          next
-        end
-      end
-
-      # @return [String]
-      def dependency_path(side)
-        "/repos/#{repo.organization}/#{repo.name}/issues/#{number}/dependencies/#{side}"
-      end
-
       # @raise [PlanMyStuff::Error]
       # @return [Integer]
       #
@@ -1884,95 +907,5 @@ module PlanMyStuff
 
         id
       end
-
-      # @return [PlanMyStuff::Issue, nil]
-      def fetch_duplicate_of
-        data = PlanMyStuff.client.graphql(
-          PlanMyStuff::GraphQL::Queries::FETCH_DUPLICATE_OF,
-          variables: { owner: repo.organization, repo: repo.name, number: number },
-        )
-        issue_data = data.dig(:repository, :issue) || {}
-        return unless issue_data[:stateReason].to_s.casecmp?('DUPLICATE')
-
-        the_dupe = issue_data[:duplicateOf]
-        return if the_dupe.blank?
-
-        PlanMyStuff::Issue.find(the_dupe[:number], repo: the_dupe.dig(:repository, :nameWithOwner))
-      end
-
-      # Resolves +target+ to an +Issue+.
-      #
-      # @raise [PlanMyStuff::ValidationError] when the duplicate target cannot be found
-      #
-      # @return [PlanMyStuff::Issue]
-      #
-      def resolve_duplicate_target!(target)
-        resolve_target_issue(target, type: :duplicate_of)
-      rescue Octokit::NotFound, PlanMyStuff::APIError => e
-        raise(PlanMyStuff::ValidationError, "Duplicate target not found: #{e.message}")
-      end
-
-      # Unions self's visibility_allowlist onto +target+'s.
-      #
-      # @return [void]
-      #
-      def merge_visibility_allowlist_onto!(target)
-        return if metadata.visibility_allowlist.blank?
-
-        merged = Array.wrap(target.metadata.visibility_allowlist) | Array.wrap(metadata.visibility_allowlist)
-        target.update!(metadata: { visibility_allowlist: merged })
-      end
-
-      # Unions self's GitHub assignees (by login) onto +target+'s.
-      #
-      # @return [void]
-      #
-      def merge_assignees_onto!(target)
-        source_logins = extract_assignee_logins(github_response)
-        return if source_logins.empty?
-
-        merged = extract_assignee_logins(target.github_response) | source_logins
-        target.update!(assignees: merged)
-      end
-
-      # @param response [Object] Octokit issue response
-      #
-      # @return [Array<String>]
-      #
-      def extract_assignee_logins(response)
-        raw = safe_read_field(response, :assignees) || []
-        raw.filter_map { |a| a.respond_to?(:login) ? a.login : a[:login] || a['login'] }
-      end
-
-      # @return [void]
-      def post_duplicate_back_pointer!(target, user:)
-        visibility = target.metadata.visibility.presence || 'public'
-        PlanMyStuff::Comment.create!(
-          issue: target,
-          body: "Marked duplicate of this by #{repo.full_name}##{number}",
-          user: user,
-          visibility: visibility.to_sym,
-        )
-      end
-
-      # Closes self as a duplicate of +target+ via GitHub's native +closeIssue+ GraphQL mutation with
-      # +stateReason: DUPLICATE+ and +duplicateIssueId+. The REST +duplicate_of+ body param is not recognized; only
-      # this GraphQL path actually wires up +Issue#duplicateOf+ on the closed issue.
-      #
-      # @raise [PlanMyStuff::Error] when source or target issue has no node_id
-      #
-      # @return [void]
-      #
-      def close_as_duplicate!(target)
-        source_node_id = github_node_id
-        target_node_id = target.github_node_id
-        raise(PlanMyStuff::Error, "Issue ##{number} has no node_id") if source_node_id.blank?
-        raise(PlanMyStuff::Error, "Target issue ##{target.number} has no node_id") if target_node_id.blank?
-
-        PlanMyStuff.client.graphql(
-          PlanMyStuff::GraphQL::Queries::CLOSE_AS_DUPLICATE,
-          variables: { issueId: source_node_id, duplicateIssueId: target_node_id },
-        )
-      end
   end
 end