plan_my_stuff 0.26.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6561200ae8220464aa3e705f21ae4d6695a4c3ae3db222677bb1deddddcd37b7
-  data.tar.gz: 98d519079e5c203741de10ce667341246d20335253033357a5d3ae8e1b48feee
+  metadata.gz: 9aac5ec777cf9b53a459843e9bdbf1177178fe1623457a60d266e993db3d2d93
+  data.tar.gz: 1b7089b760fa0552e3b861732472e43cab09667699e1528703809a2ce753254f
 SHA512:
-  metadata.gz: 8c78d58f9322827d0483389f56dd82d02786929b851cfc6bf81bdc11973f7cdb06e3866b12c40054d4db71f44a24f5c817fd41213b374cf96eeec75e4c384b44
-  data.tar.gz: 9b1464ab72de0568958a73d75bb79f4d7e4095bbebc9e97dcf5f97445c79eace14f83d65da99de36f61c10f5ca37e178e5ffb2ef59afa941cad8f49b3ba56be2
+  metadata.gz: 84f1cc4e7dd87ed3e33f2095d3c0f57c9ad61972ffaa5ed1d9379dfb6bb0e7bc1b07491c76c6c4f4618c39b977d7240689de5552a8c9f60fe1b474c29dde2637
+  data.tar.gz: 1d355a051c6d6f0903c80558019790ab0e1d84adb8885b28b0c18b57802ed16c338ab7793ca24f535dc01980296fcc33b19eacc3acd204d08586db25d63138d4

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.28.0
+
+### Added
+
+- `Issue.list_page_info(...)` returns a `PlanMyStuff::Issue::PageInfo` value object exposing `.issues`, `.page`,
+  `.per_page`, `.has_next?`, and `.has_prev?`. `Issue.list` now delegates to it; return type unchanged
+  (`Array<Issue>`). Closes #63.
+
+## 0.27.0
+
+### Added
+
+- `PlanMyStuff::Issue#mark_responded!(user)` - stamps `metadata.responded_at` on the first support-user engagement of
+  any kind. No-ops when the user is blank, not a support user, the issue isn't a PMS issue, or `responded_at` is
+  already set.
+
+### Changed
+
+- `Pipeline.take!` and the `issues.assigned` webhook now stamp `metadata.responded_at` on first support engagement
+  (was previously only set by the first support comment) (closes #60).
+
 ## 0.26.0
 
 ### Added

data/app/controllers/plan_my_stuff/webhooks/github_controller.rb

@@ -91,6 +91,10 @@ module PlanMyStuff
         # GitHub already records the issue assignment (that's what triggered this webhook), so the gem does not
         # call +assign!+ on the project item -- that would clobber co-assignees on the underlying issue.
         #
+        # Regardless of pipeline state, +mark_responded!+ stamps +metadata.responded_at+ when a support user is the
+        # assignee -- including self-assigns to issues already in the pipeline. The method's own guards no-op for
+        # non-support assignees and already-responded issues.
+        #
         # @return [void]
         #
         def handle_issue_assigned
@@ -101,6 +105,14 @@ module PlanMyStuff
 
           return if assignee_login.blank?
 
+          repo = payload_params.dig(:repository, :full_name)
+          issue = PlanMyStuff::Issue.find(issue_number, repo: repo)
+          assignee_user = PlanMyStuff::UserResolver.from_github_login(assignee_login)
+
+          # Stamp before the already-in-pipeline early-return so a support user self-assigning to an
+          # already-taken issue still records a first response.
+          issue.mark_responded!(assignee_user)
+
           existing = PlanMyStuff::Pipeline::IssueLinker.find_project_item(issue_number)
           if existing.present?
             Rails.logger.info("[PlanMyStuff] Issue ##{issue_number} already in pipeline project, skipping")
@@ -108,9 +120,6 @@ module PlanMyStuff
             return
           end
 
-          repo = payload_params.dig(:repository, :full_name)
-          issue = PlanMyStuff::Issue.find(issue_number, repo: repo)
-
           if issue.approvals_required? && !issue.fully_approved?
             Rails.logger.info("[PlanMyStuff] Issue ##{issue_number} has pending approvals, skipping")
 
@@ -119,7 +128,7 @@ module PlanMyStuff
 
           number = PlanMyStuff::Pipeline.resolve_pipeline_project_number!
           project_item = PlanMyStuff::ProjectItem.create!(issue, project_number: number)
-          PlanMyStuff::Pipeline.take!(project_item, user: PlanMyStuff::UserResolver.from_github_login(assignee_login))
+          PlanMyStuff::Pipeline.take!(project_item, user: assignee_user)
         end
 
         # Removes the issue from the pipeline project when the LAST assignee is removed. If any assignees remain,

data/lib/plan_my_stuff/comment.rb

@@ -91,7 +91,7 @@ module PlanMyStuff
           cache_writer: :write_comment,
         )
 
-        mark_issue_responded_if_first_support_comment!(issue, resolved_user) unless skip_responded
+        issue.mark_responded!(resolved_user) unless skip_responded
 
         comment = build(result, issue: issue)
         PlanMyStuff::Notifications.instrument('comment_created', comment, user: resolved_user)
@@ -218,29 +218,6 @@ module PlanMyStuff
           :internal
         end
 
-        # Sets responded_at on the issue metadata if this is the first support comment and the issue hasn't been
-        # responded to yet.
-        #
-        # @param issue [PlanMyStuff::Issue] parent issue
-        # @param user [Object, nil] resolved user object
-        #
-        # @return [void]
-        #
-        def mark_issue_responded_if_first_support_comment!(issue, user)
-          return if user.nil?
-
-          return unless PlanMyStuff::UserResolver.support?(user)
-          return unless issue.pms_issue?
-
-          return if issue.metadata.responded?
-
-          PlanMyStuff::Issue.update!(
-            number: issue.number,
-            repo: issue.repo,
-            metadata: { responded_at: PlanMyStuff.format_time(Time.now.utc) },
-          )
-        end
-
         # Mutates issue waiting state based on the comment's author. Support users with +waiting_on_reply: true+ enter
         # the issue into waiting-on-user state. Non-support users clear any active waiting-on-user state and
         # auto-reopen issues that were closed by the inactivity sweep.

data/lib/plan_my_stuff/issue.rb

@@ -9,6 +9,21 @@ module PlanMyStuff
   # - `Issue.create!` / `Issue.find` / `Issue.list` return persisted instances
   # - `issue.save!` / `issue.update!` / `issue.reload` for persistence
   class Issue < PlanMyStuff::ApplicationRecord
+    # Value object returned by +Issue.list_page_info+: the fetched issues plus pagination metadata read from the
+    # +Link+ header of the +list_issues+ response. +:total_pages+ is intentionally absent -- GitHub's issues endpoint
+    # is cursor-paginated and never advertises +rel="last"+.
+    #
+    # @!attribute [r] issues
+    #   @return [Array<PlanMyStuff::Issue>]
+    # @!attribute [r] page
+    #   @return [Integer] echo of the requested page
+    # @!attribute [r] per_page
+    #   @return [Integer] echo of the requested per_page
+    PageInfo = Data.define(:issues, :page, :per_page, :has_next, :has_prev) do
+      alias_method :has_next?, :has_next
+      alias_method :has_prev?, :has_prev
+    end
+
     include PlanMyStuff::IssueExtractions::Approvals
     include PlanMyStuff::IssueExtractions::Links
     include PlanMyStuff::IssueExtractions::Viewers
@@ -332,7 +347,38 @@ module PlanMyStuff
       #
       # @return [Array<PlanMyStuff::Issue>]
       #
-      def list(
+      def list(**)
+        list_page_info(**).issues
+      end
+
+      # Lists GitHub issues like +.list+, but returns a +PageInfo+ value object carrying the issues plus pagination
+      # metadata read from the response's +Link+ header in the same request. Use this over +.list+ when a caller needs
+      # to know whether more pages exist (e.g. to render "Next"/"Prev" controls) without an optimistic +page + 1+
+      # probe.
+      #
+      # Shares the entire parameter surface, filtering, and PR-rejection behavior of +.list+; see it for semantics.
+      #
+      # Note the PR-filter wart: +per_page+ caps GitHub's raw item count (issues + PRs), but PRs are stripped
+      # client-side afterward, so +page_info.issues.length+ may be smaller than +per_page+. +has_next?+ comes straight
+      # from the +Link+ header, so it reflects raw items too -- a page can report +has_next? == true+ while showing
+      # fewer than +per_page+ issues.
+      #
+      # @raise [ArgumentError] when +priority_list: false+ is passed, or when +issue_type:+ is an Array
+      # @raise [PlanMyStuff::IssueFieldsNotEnabledError] when +issue_fields:+ is passed and
+      #   +config.issue_fields_enabled+ is +false+
+      #
+      # @param repo [Symbol, String, nil] defaults to config.default_repo
+      # @param state [Symbol] :open, :closed, or :all
+      # @param labels [Array<String>]
+      # @param issue_type [String, Symbol, nil] a single GitHub issue type name
+      # @param issue_fields [Hash{String,Symbol => Object,Range,nil}, nil] GitHub Issue Field equality / range filters
+      # @param priority_list [Boolean, nil] when +true+, restricts to +Priority List+ +Yes+ issues
+      # @param page [Integer]
+      # @param per_page [Integer]
+      #
+      # @return [PlanMyStuff::Issue::PageInfo]
+      #
+      def list_page_info(
         repo: nil,
         state: :open,
         labels: [],
@@ -366,8 +412,16 @@ module PlanMyStuff
         params[:issue_field_values] = field_pairs.join(',') if field_pairs.present?
 
         github_issues = client.rest(:list_issues, resolved_repo, **params)
+        rels = client.last_response&.rels || {}
         filtered = github_issues.reject { |gi| gi.respond_to?(:pull_request) && gi.pull_request }
-        filtered.map { |gi| build(gi, repo: resolved_repo) }
+
+        PageInfo.new(
+          issues: filtered.map { |gi| build(gi, repo: resolved_repo) },
+          page: page,
+          per_page: per_page,
+          has_next: rels[:next].present?,
+          has_prev: rels[:prev].present?,
+        )
       end
 
       # Convenience shortcut for +list(priority_list: true, ...)+. See +.list+ for parameter semantics.
@@ -886,6 +940,30 @@ module PlanMyStuff
       save!(user: user, skip_notification: skip_notification)
     end
 
+    # Stamps +metadata.responded_at+ on the first support-user engagement with this issue. Centralizes the guards so
+    # every engagement path (first support comment, +Pipeline.take!+, self-assign webhook) can funnel through one
+    # method. No-ops unless +user+ resolves to a support user on a PMS issue that hasn't been responded to yet.
+    #
+    # @param user [Object, nil] actor engaging with the issue (resolved via +PlanMyStuff::UserResolver+)
+    #
+    # @return [void]
+    #
+    def mark_responded!(user)
+      resolved = PlanMyStuff::UserResolver.resolve(user)
+      return if resolved.blank?
+
+      return unless PlanMyStuff::UserResolver.support?(resolved)
+      return unless pms_issue?
+
+      return if metadata.responded?
+
+      self.class.update!(
+        number: number,
+        repo: repo,
+        metadata: { responded_at: PlanMyStuff.format_time(Time.now.utc) },
+      )
+    end
+
     # Re-fetches this issue from GitHub and updates all local attributes.
     #
     # @return [self]

data/lib/plan_my_stuff/pipeline.rb

@@ -150,7 +150,8 @@ module PlanMyStuff
       locked_statuses.include?(project_item.status)
     end
 
-    # Moves a project item to "Started".
+    # Moves a project item to "Started". When +user+ is a support user, also stamps +metadata.responded_at+ on the
+    # issue via +Issue#mark_responded!+ (a no-op if it's already responded to / not a PMS issue).
     #
     # @param project_item [PlanMyStuff::ProjectItem]
     # @param user [Object, nil] actor forwarded to the +pipeline_started.plan_my_stuff+ payload
@@ -162,6 +163,8 @@ module PlanMyStuff
       status = resolve_status_name(PlanMyStuff::Pipeline::Status::STARTED)
       result = project_item.move_to!(status)
 
+      project_item.issue.mark_responded!(user) if user.present?
+
       instrument(PlanMyStuff::Pipeline::Status::STARTED, project_item, user: user)
       result
     end

data/lib/plan_my_stuff/version.rb

@@ -3,7 +3,7 @@
 module PlanMyStuff
   module VERSION
     MAJOR = 0
-    MINOR = 26
+    MINOR = 28
     TINY = 0
 
     # Set PRE to nil unless it's a pre-release (beta, rc, etc.)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plan_my_stuff
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.28.0
 platform: ruby
 authors:
 - Brands Insurance