plan_my_stuff 0.8.0 → 0.10.0

data/lib/plan_my_stuff/issue_extractions/links.rb

@@ -0,0 +1,525 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module IssueExtractions
+    module Links
+      # 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
+
+      private
+
+        # @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
+
+        # 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
+
+        # @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
+end

data/lib/plan_my_stuff/issue_extractions/viewers.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module IssueExtractions
+    module Viewers
+      # 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
+
+      # 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
+
+      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
+    end
+  end
+end