plan_my_stuff 0.7.0 → 0.9.0

data/lib/plan_my_stuff/comment.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 module PlanMyStuff
-  # Wraps a GitHub comment with parsed PMS metadata.
-  # Class methods provide the public API for CRUD operations.
+  # Wraps a GitHub comment with parsed PMS metadata. Class methods provide the public API for CRUD operations.
   #
   # Follows an ActiveRecord-style pattern:
   # - `Comment.new(**attrs)` creates an unpersisted instance
@@ -21,25 +20,28 @@ module PlanMyStuff
     attribute :issue
     # @return [Time, nil] GitHub's updated_at timestamp
     attribute :updated_at
+    # @return [Time, nil] GitHub's created_at timestamp; settable on unpersisted comments for use with +Issue.import+
+    attribute :created_at
     # @return [Symbol, nil] :public or :internal (locally set or from metadata)
     attribute :visibility
 
-    # @return [Boolean, nil] transient flag used by the new-comment form to
-    #   request waiting-on-user state when a support user posts. Not persisted.
+    # @return [Boolean, nil] transient flag used by the new-comment form to request waiting-on-user state when a
+    #   support user posts. Not persisted.
     attr_accessor :waiting_on_reply
 
     class << self
       # Creates a comment on a GitHub issue with PMS metadata and a visible header.
       #
+      # @raise [PlanMyStuff::LockedIssueError] if the parent issue is locked
+      #
       # @param issue [PlanMyStuff::Issue] parent issue
       # @param body [String]
       # @param user [Object, Integer] user object or user_id
       # @param visibility [Symbol] :public or :internal
       # @param custom_fields [Hash]
       # @param issue_body [Boolean] whether this comment holds the issue body
-      # @param waiting_on_reply [Boolean] when true and the author is a
-      #   support user, marks the issue as waiting on an end-user reply.
-      #   Ignored for non-support authors.
+      # @param waiting_on_reply [Boolean] when true and the author is a support user, marks the issue as waiting on
+      #   an end-user reply. Ignored for non-support authors.
       #
       # @return [PlanMyStuff::Comment]
       #
@@ -55,9 +57,9 @@ module PlanMyStuff
       )
         raise(PlanMyStuff::LockedIssueError, "Issue ##{issue.number} is locked") if issue.locked?
 
-        resolved_user = UserResolver.resolve(user)
+        resolved_user = PlanMyStuff::UserResolver.resolve(user)
         visibility = resolve_visibility(visibility, resolved_user)
-        comment_metadata = CommentMetadata.build(
+        comment_metadata = PlanMyStuff::CommentMetadata.build(
           user: resolved_user,
           visibility: visibility.to_s,
           custom_fields: custom_fields,
@@ -67,7 +69,7 @@ module PlanMyStuff
 
         header = build_header(resolved_user)
         full_body = "#{header}\n\n#{body}"
-        serialized_body = MetadataParser.serialize(comment_metadata.to_h, full_body)
+        serialized_body = PlanMyStuff::MetadataParser.serialize!(comment_metadata.to_h, full_body)
 
         client = PlanMyStuff.client
         result = client.rest(:add_comment, issue.repo, issue.number, serialized_body)
@@ -79,11 +81,11 @@ module PlanMyStuff
           cache_writer: :write_comment,
         )
 
-        mark_issue_responded_if_first_support_comment(issue, resolved_user) unless skip_responded
+        mark_issue_responded_if_first_support_comment!(issue, resolved_user) unless skip_responded
 
         comment = build(result, issue: issue)
         PlanMyStuff::Notifications.instrument('comment.created', comment, user: resolved_user)
-        apply_waiting_state_transitions(issue, resolved_user, waiting_on_reply, comment)
+        apply_waiting_state_transitions!(issue, resolved_user, waiting_on_reply, comment)
         comment
       end
 
@@ -180,7 +182,7 @@ module PlanMyStuff
         def build_header(user)
           display_name =
             if user.present?
-              UserResolver.display_name(user)
+              PlanMyStuff::UserResolver.display_name(user)
             else
               'Unknown'
             end
@@ -201,39 +203,37 @@ module PlanMyStuff
 
           return :public if user.blank?
 
-          return :public unless UserResolver.support?(user)
+          return :public unless PlanMyStuff::UserResolver.support?(user)
 
           :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.
+        # 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)
+        def mark_issue_responded_if_first_support_comment!(issue, user)
           return if user.nil?
 
-          return unless UserResolver.support?(user)
+          return unless PlanMyStuff::UserResolver.support?(user)
           return unless issue.pms_issue?
 
           return if issue.metadata.responded?
 
-          Issue.update!(
+          PlanMyStuff::Issue.update!(
             number: issue.number,
             repo: issue.repo,
-            metadata: { responded_at: Time.now.utc.iso8601 },
+            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.
+        # 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.
         #
         # No-ops on non-PMS issues or when no user is resolved.
         #
@@ -244,7 +244,7 @@ module PlanMyStuff
         #
         # @return [void]
         #
-        def apply_waiting_state_transitions(issue, user, waiting_on_reply, comment)
+        def apply_waiting_state_transitions!(issue, user, waiting_on_reply, comment)
           return if user.nil?
 
           return unless issue.pms_issue?
@@ -252,7 +252,7 @@ module PlanMyStuff
           # Auto-reopen fires only for non-support replies; a support comment on a
           # +closed_by_inactivity+ issue is treated as a closure note and requires
           # the explicit Reopen button to bring the issue back.
-          if UserResolver.support?(user)
+          if PlanMyStuff::UserResolver.support?(user)
             issue.enter_waiting_on_user!(user: user) if waiting_on_reply
           elsif issue.metadata.closed_by_inactivity
             issue.reopen_by_reply!(comment: comment, user: user)
@@ -264,32 +264,34 @@ module PlanMyStuff
 
     # Persists the comment. Creates if new, updates if persisted.
     #
-    # @raise [PlanMyStuff::StaleObjectError] on update if stale
-    #
     # @return [self]
     #
-    def save!
+    def save!(user: nil)
       if new_record?
         created = self.class.create!(
           issue: issue,
           body: body,
+          user: user || metadata.created_by,
           visibility: visibility || :public,
+          custom_fields: metadata.custom_fields.to_h,
+          issue_body: metadata.issue_body,
+          waiting_on_reply: waiting_on_reply,
         )
         hydrate_from_comment(created)
       else
-        update!(body: body)
+        update_attrs = { user: user, body: body }
+        update_attrs[:visibility] = visibility if visibility_changed?
+        update!(**update_attrs)
       end
 
       self
     end
 
-    # Updates this comment on GitHub. Raises StaleObjectError if the remote
-    # has been modified since this instance was loaded.
+    # Updates this comment on GitHub. Raises StaleObjectError if the remote has been modified since this instance was
+    # loaded.
     #
     # @param attrs [Hash] attributes to update (body:, visibility:)
     #
-    # @raise [PlanMyStuff::StaleObjectError] if remote updated_at differs from local
-    #
     # @return [self]
     #
     def update!(user: nil, **attrs)
@@ -302,11 +304,12 @@ module PlanMyStuff
       meta_hash = metadata.to_h
 
       if attrs.key?(:visibility)
-        new_visibility = attrs[:visibility].to_s
+        resolved_user = PlanMyStuff::UserResolver.resolve(user)
+        new_visibility = self.class.__send__(:resolve_visibility, attrs[:visibility], resolved_user).to_s
         meta_hash[:visibility] = new_visibility
       end
 
-      serialized = MetadataParser.serialize(meta_hash, new_body)
+      serialized = PlanMyStuff::MetadataParser.serialize!(meta_hash, new_body)
       self.class.update!(id: id, repo: issue.repo, body: serialized)
 
       reload
@@ -332,8 +335,8 @@ module PlanMyStuff
       safe_read_field(github_response, :html_url)
     end
 
-    # Serializes the comment to a JSON-safe hash, excluding the back-reference
-    # to the parent issue to prevent recursive serialization cycles.
+    # Serializes the comment to a JSON-safe hash, excluding the back-reference to the parent issue to prevent
+    # recursive serialization cycles.
     #
     # @return [Hash]
     #
@@ -347,8 +350,8 @@ module PlanMyStuff
       metadata.schema_version.present?
     end
 
-    # Returns the comment visibility as a symbol.
-    # Uses the locally set value if present, otherwise falls back to metadata.
+    # Returns the comment visibility as a symbol. Uses the locally set value if present, otherwise falls back to
+    # metadata.
     #
     # @return [Symbol, nil] :public or :internal
     #
@@ -356,22 +359,21 @@ module PlanMyStuff
       super || metadata.visibility&.to_sym
     end
 
-    # Checks if the comment is visible to the given user.
-    # Public PMS comments: visible to everyone the parent issue is visible to.
-    # Internal PMS comments: visible only to support users.
-    # Non-PMS comments: visible only to support users.
+    # Checks if the comment is visible to the given user. Public PMS comments: visible to everyone the parent issue
+    # is visible to. Internal PMS comments: visible only to support users. Non-PMS comments: visible only to support
+    # users.
     #
     # @param user [Object, Integer] user object or user_id
     #
     # @return [Boolean]
     #
     def visible_to?(user)
-      resolved = PMS::UserResolver.resolve(user)
+      resolved = PlanMyStuff::UserResolver.resolve(user)
 
       if pms_comment?
-        issue.visible_to?(resolved) && (visibility != :internal || PMS::UserResolver.support?(resolved))
+        issue.visible_to?(resolved) && (visibility != :internal || PlanMyStuff::UserResolver.support?(resolved))
       else
-        PMS::UserResolver.support?(resolved)
+        PlanMyStuff::UserResolver.support?(resolved)
       end
     end
 
@@ -407,9 +409,8 @@ module PlanMyStuff
         "#{existing_header}\n\n#{new_body}"
       end
 
-      # Computes the +ActiveModel::Dirty+-style changes hash from the +update!+
-      # +attrs+ hash vs the current in-memory state. Only includes keys whose
-      # value actually differs.
+      # Computes the +ActiveModel::Dirty+-style changes hash from the +update!+ +attrs+ hash vs the current in-memory
+      # state. Only includes keys whose value actually differs.
       #
       # @param attrs [Hash]
       #
@@ -440,10 +441,11 @@ module PlanMyStuff
         self.id = read_field(github_comment, :id)
         self.raw_body = read_field(github_comment, :body)
         self.updated_at = parse_github_time(safe_read_field(github_comment, :updated_at))
+        self.created_at = parse_github_time(safe_read_field(github_comment, :created_at))
         self.issue = issue
 
-        parsed = MetadataParser.parse(raw_body)
-        self.metadata = CommentMetadata.from_hash(parsed[:metadata])
+        parsed = PlanMyStuff::MetadataParser.parse(raw_body)
+        self.metadata = PlanMyStuff::CommentMetadata.from_hash(parsed[:metadata])
         self.body = parsed[:body]
         self.visibility = metadata.visibility&.to_sym
         persisted!
@@ -461,16 +463,16 @@ module PlanMyStuff
         self.body = other.body
         self.raw_body = other.raw_body
         self.updated_at = other.updated_at
+        self.created_at = other.created_at
         self.issue = other.issue
         self.metadata = other.metadata
         self.visibility = other.visibility
         persisted!
       end
 
-      # Raises StaleObjectError if the remote comment has been modified
-      # since this instance was loaded.
+      # Raises StaleObjectError if the remote comment has been modified since this instance was loaded.
       #
-      # @raise [PlanMyStuff::StaleObjectError]
+      # @raise [PlanMyStuff::StaleObjectError] if comment was modified after loading
       #
       # @return [void]
       #
@@ -485,7 +487,7 @@ module PlanMyStuff
         return if remote_time.nil?
         return if local_time && remote_time.to_i == local_time.to_i
 
-        raise(StaleObjectError.new(
+        raise(PlanMyStuff::StaleObjectError.new(
           "Comment ##{id} has been modified remotely",
           local_updated_at: local_time,
           remote_updated_at: remote_time,

data/lib/plan_my_stuff/comment_metadata.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module PlanMyStuff
-  class CommentMetadata < BaseMetadata
+  class CommentMetadata < PlanMyStuff::BaseMetadata
     # @return [Boolean] true if this comment holds the issue's body content
     attr_accessor :issue_body