plan_my_stuff 0.1.0 → 1.0.0

data/lib/plan_my_stuff/comment.rb

@@ -1,37 +1,51 @@
 # 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
   # - `Comment.create!` / `Comment.list` return persisted instances
   # - `comment.save!` / `comment.update!` / `comment.reload` for persistence
   class Comment < PlanMyStuff::ApplicationRecord
-    # @return [Integer] GitHub comment ID
-    attr_reader :id
-    # @return [String] full body as stored on GitHub
-    attr_reader :raw_body
+    # @return [Integer, nil] GitHub comment ID
+    attribute :id, :big_integer
+    # @return [String, nil] full body as stored on GitHub
+    attribute :raw_body, :string
     # @return [PlanMyStuff::CommentMetadata] parsed metadata (empty when no PMS metadata present)
-    attr_reader :metadata
-
-    # @return [String] comment body without the metadata HTML comment
-    attr_accessor :body
-    # @return [PlanMyStuff::Issue] parent issue
-    attr_accessor :issue
-    # @param value [Symbol, String, nil]
-    attr_writer :visibility
+    attribute :metadata, default: -> { PlanMyStuff::CommentMetadata.new }
+    # @return [String, nil] comment body without the metadata HTML comment
+    attribute :body, :string
+    # @return [PlanMyStuff::Issue, nil] parent issue
+    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.
+    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 attachments [Array] files to upload to +config.attachment_repo+ and record on the comment. Each entry
+      #   may be an uploaded-file object responding to +#path+ and +#original_filename+ (e.g. Rails
+      #   +ActionDispatch::Http::UploadedFile+), a String/Pathname path to a local file, or a pre-built
+      #   +PlanMyStuff::Attachment+ instance (passthrough, no re-upload).
       #
       # @return [PlanMyStuff::Comment]
       #
@@ -42,26 +56,47 @@ module PlanMyStuff
         visibility: :public,
         custom_fields: {},
         skip_responded: false,
-        issue_body: false
+        issue_body: false,
+        waiting_on_reply: false,
+        attachments: []
       )
-        resolved_user = UserResolver.resolve(user)
+        raise(PlanMyStuff::LockedIssueError, "Issue ##{issue.number} is locked") if issue.locked?
+
+        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,
           issue_body: issue_body,
         )
+        comment_metadata.validate_custom_fields!
+        comment_metadata.attachments = PlanMyStuff::AttachmentUploader.upload_all!(
+          repo: issue.repo,
+          issue_number: issue.number,
+          files: attachments,
+        )
 
         header = build_header(resolved_user)
         full_body = "#{header}\n\n#{body}"
-        serialized_body = MetadataParser.serialize(comment_metadata.to_h, full_body)
-
-        result = PlanMyStuff.client.rest(:add_comment, issue.repo, issue.number, serialized_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)
+        store_etag_to_cache(
+          client,
+          issue.repo,
+          read_field(result, :id),
+          result,
+          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
 
-        build(result, issue: issue)
+        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)
+        comment
       end
 
       # Updates an existing GitHub comment body.
@@ -73,7 +108,16 @@ module PlanMyStuff
       # @return [Object] Octokit response
       #
       def update!(id:, repo:, body:)
-        PlanMyStuff.client.rest(:update_comment, repo, id, body)
+        client = PlanMyStuff.client
+        result = client.rest(:update_comment, repo, id, body)
+        store_etag_to_cache(
+          client,
+          repo,
+          id,
+          result,
+          cache_writer: :write_comment,
+        )
+        result
       end
 
       # Finds a single comment by ID, given its parent issue.
@@ -84,7 +128,16 @@ module PlanMyStuff
       # @return [PlanMyStuff::Comment]
       #
       def find(id, issue:)
-        github_comment = PlanMyStuff.client.rest(:issue_comment, issue.repo, id)
+        client = PlanMyStuff.client
+        github_comment =
+          fetch_with_etag_cache(
+            client,
+            issue.repo,
+            id,
+            rest_method: :issue_comment,
+            cache_reader: :read_comment,
+            cache_writer: :write_comment,
+          )
         build(github_comment, issue: issue)
       end
 
@@ -96,8 +149,21 @@ module PlanMyStuff
       # @return [Array<PlanMyStuff::Comment>]
       #
       def list(issue:, pms_only: false)
-        github_comments = PlanMyStuff.client.rest(:issue_comments, issue.repo, issue.number)
-        comments = github_comments.map { |gc| build(gc, issue: issue) }
+        client = PlanMyStuff.client
+        params = { issue_number: issue.number }
+
+        cached = PlanMyStuff::Cache.read_list(:comment, issue.repo, params)
+        request_options = cached ? { headers: { 'If-None-Match' => cached[:etag] } } : {}
+
+        github_comments = client.rest(:issue_comments, issue.repo, issue.number, **request_options)
+
+        comments =
+          if cached && not_modified?(client)
+            cached[:body].map { |gc| build(gc, issue: issue) }
+          else
+            store_list_etag_to_cache(client, :comment, issue.repo, params, github_comments)
+            github_comments.map { |gc| build(gc, issue: issue) }
+          end
 
         pms_only ? comments.select(&:pms_comment?) : comments
       end
@@ -126,7 +192,7 @@ module PlanMyStuff
         def build_header(user)
           display_name =
             if user.present?
-              UserResolver.display_name(user)
+              PlanMyStuff::UserResolver.display_name(user)
             else
               'Unknown'
             end
@@ -147,88 +213,96 @@ 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.
+        # 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.
         #
-        # @param issue [PlanMyStuff::Issue] parent issue
-        # @param user [Object, nil] resolved user object
+        # No-ops on non-PMS issues or when no user is resolved.
+        #
+        # @param issue [PlanMyStuff::Issue]
+        # @param user [Object, nil] resolved user
+        # @param waiting_on_reply [Boolean]
+        # @param comment [PlanMyStuff::Comment] the just-created comment
         #
         # @return [void]
         #
-        def mark_issue_responded_if_first_support_comment(issue, user)
+        def apply_waiting_state_transitions!(issue, user, waiting_on_reply, comment)
           return if user.nil?
 
-          return unless UserResolver.support?(user)
           return unless issue.pms_issue?
 
-          return if issue.metadata.responded?
-
-          Issue.update!(
-            number: issue.number,
-            repo: issue.repo,
-            metadata: { responded_at: Time.now.utc.iso8601 },
-          )
+          # 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 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)
+          elsif issue.metadata.waiting_on_user_at.present?
+            issue.clear_waiting_on_user!
+          end
         end
     end
 
-    def initialize(**attrs)
-      @id = attrs.delete(:id)
-      @raw_body = nil
-      @metadata = CommentMetadata.new
-      super
-    end
-
     # 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,
+          attachments: metadata.attachments,
         )
         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!(**attrs)
+    def update!(user: nil, **attrs)
       raise_if_stale!
 
+      captured_changes = capture_update_changes(attrs)
+
       new_body = attrs[:body] || body
+      new_body = preserve_header(new_body) if attrs.key?(:body)
       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
-        meta_hash[:updated_at] = Time.now.utc.iso8601
       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
+      PlanMyStuff::Notifications.instrument('comment_updated', self, user: user, changes: captured_changes)
+      self
     end
 
     # Re-fetches this comment from GitHub and updates all local attributes.
@@ -236,41 +310,58 @@ module PlanMyStuff
     # @return [self]
     #
     def reload
-      github_comment = PlanMyStuff.client.rest(:issue_comment, issue.repo, id)
-      hydrate_from_github(github_comment, issue: issue)
+      fresh = self.class.find(id, issue: issue)
+      hydrate_from_comment(fresh)
       self
     end
 
+    # GitHub web URL for this comment, for escape-hatch "View on GitHub" links.
+    #
+    # @return [String, nil]
+    #
+    def html_url
+      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.
+    #
+    # @return [Hash]
+    #
+    def as_json(options = {})
+      merged_except = Array.wrap(options[:except]) + ['issue']
+      super(options.merge(except: merged_except)).merge('issue_number' => issue&.number)
+    end
+
     # @return [Boolean]
     def pms_comment?
       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
     #
     def visibility
-      @visibility || metadata.visibility&.to_sym
+      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
 
@@ -293,6 +384,39 @@ module PlanMyStuff
 
     private
 
+      # Prepends the existing header to new_body if the comment currently has one.
+      #
+      # @param new_body [String]
+      #
+      # @return [String]
+      #
+      def preserve_header(new_body)
+        existing_header = header
+        return new_body if existing_header.blank?
+
+        "#{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.
+      #
+      # @param attrs [Hash]
+      #
+      # @return [Hash{String => Array(Object, Object)}]
+      #
+      def capture_update_changes(attrs)
+        changes = {}
+        if attrs.key?(:body) && attrs[:body] != body
+          changes['body'] = [body, attrs[:body]]
+        end
+        if attrs.key?(:visibility)
+          new_visibility = attrs[:visibility].to_s
+          current_visibility = visibility&.to_s
+          changes['visibility'] = [current_visibility, new_visibility] if current_visibility != new_visibility
+        end
+        changes
+      end
+
       # Populates this instance from a GitHub API response.
       #
       # @param github_comment [Object] Octokit comment response
@@ -301,15 +425,18 @@ module PlanMyStuff
       # @return [void]
       #
       def hydrate_from_github(github_comment, issue:)
-        @id = read_field(github_comment, :id)
-        @raw_body = read_field(github_comment, :body)
-        @issue = issue
-
-        parsed = MetadataParser.parse(@raw_body)
-        @metadata = CommentMetadata.from_hash(parsed[:metadata])
-        @body = parsed[:body]
-        @visibility = @metadata.visibility&.to_sym
-        @persisted = true
+        @github_response = github_comment
+        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 = PlanMyStuff::MetadataParser.parse(raw_body)
+        self.metadata = PlanMyStuff::CommentMetadata.from_hash(parsed[:metadata])
+        self.body = parsed[:body]
+        self.visibility = metadata.visibility&.to_sym
+        persisted!
       end
 
       # Copies attributes from another Comment instance into self.
@@ -319,38 +446,36 @@ module PlanMyStuff
       # @return [void]
       #
       def hydrate_from_comment(other)
-        @id = other.id
-        @body = other.body
-        @raw_body = other.raw_body
-        @issue = other.issue
-        @metadata = other.metadata
-        @visibility = other.visibility
-        @persisted = true
+        @github_response = other.github_response
+        self.id = other.id
+        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]
       #
       def raise_if_stale!
         return if new_record?
-        return if metadata.updated_at.nil?
+        return if updated_at.nil?
 
-        github_comment = PlanMyStuff.client.rest(:issue_comment, issue.repo, id)
-        parsed = MetadataParser.parse(
-          github_comment.respond_to?(:body) ? github_comment.body : github_comment[:body],
-        )
-        remote_metadata = CommentMetadata.from_hash(parsed[:metadata])
-        remote_time = remote_metadata.updated_at
-        local_time = metadata.updated_at
+        remote = self.class.find(id, issue: issue)
+        remote_time = remote.updated_at
+        local_time = updated_at
 
         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,9 +1,11 @@
 # 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
+    # @return [Array<PlanMyStuff::Attachment>] consuming-app attachment records associated with this comment
+    attr_reader :attachments
 
     class << self
       # Builds a CommentMetadata from a parsed hash (e.g. from MetadataParser)
@@ -14,8 +16,9 @@ module PlanMyStuff
       #
       def from_hash(hash)
         metadata = new
-        apply_common_from_hash(metadata, hash)
+        apply_common_from_hash(metadata, hash, PlanMyStuff.configuration.custom_fields_for(:comment))
         metadata.issue_body = hash[:issue_body] || false
+        metadata.attachments = hash[:attachments]
 
         metadata
       end
@@ -26,13 +29,21 @@ module PlanMyStuff
       # @param visibility [String] "public" or "internal"
       # @param custom_fields [Hash] app-defined field values
       # @param issue_body [Boolean] whether this comment holds the issue body
+      # @param attachments [Array<Hash, PlanMyStuff::Attachment>] consuming-app attachment records
       #
       # @return [CommentMetadata]
       #
-      def build(user:, visibility: 'internal', custom_fields: {}, issue_body: false)
+      def build(user:, visibility: 'internal', custom_fields: {}, issue_body: false, attachments: [])
         metadata = new
-        apply_common_build(metadata, user: user, visibility: visibility, custom_fields_data: custom_fields)
+        apply_common_build(
+          metadata,
+          user: user,
+          visibility: visibility,
+          custom_fields_data: custom_fields,
+          custom_fields_schema: PlanMyStuff.configuration.custom_fields_for(:comment),
+        )
         metadata.issue_body = issue_body
+        metadata.attachments = attachments
 
         metadata
       end
@@ -41,6 +52,18 @@ module PlanMyStuff
     def initialize
       super
       @issue_body = false
+      @attachments = []
+    end
+
+    # Assigns +attachments+, normalizing each entry through
+    # +PlanMyStuff::Attachment+ and dropping any malformed ones.
+    #
+    # @param raw [Array, nil]
+    #
+    # @return [Array<PlanMyStuff::Attachment>]
+    #
+    def attachments=(raw)
+      @attachments = normalize_attachments(raw)
     end
 
     # @return [Boolean]
@@ -50,7 +73,47 @@ module PlanMyStuff
 
     # @return [Hash]
     def to_h
-      super.merge(issue_body: issue_body)
+      super.merge(
+        issue_body: issue_body,
+        attachments: attachments.map(&:to_h),
+      )
     end
+
+    private
+
+      # Builds a +PlanMyStuff::Attachment+ from each parsed entry.
+      # Accepts:
+      # - an existing +PlanMyStuff::Attachment+
+      # - the structured shape +{filename:, owner:, repo:, sha:, path:}+
+      #
+      # Malformed hash entries are silently dropped so a single bad
+      # historical entry doesn't crash +Comment.find+. An already-
+      # constructed +Attachment+ that fails validation raises so the
+      # caller is not silently missing an uploaded file.
+      #
+      # @param raw [Array, nil]
+      #
+      # @return [Array<PlanMyStuff::Attachment>]
+      #
+      def normalize_attachments(raw)
+        Array.wrap(raw).filter_map do |entry|
+          next if entry.nil?
+
+          attachment =
+            if entry.is_a?(PlanMyStuff::Attachment)
+              entry
+            elsif entry.respond_to?(:transform_keys)
+              PlanMyStuff::Attachment.new(entry.transform_keys(&:to_sym))
+            end
+          next if attachment.nil?
+
+          attachment.validate!
+          attachment
+        rescue ActiveModel::ValidationError, ActiveModel::UnknownAttributeError, ArgumentError
+          raise if entry.is_a?(PlanMyStuff::Attachment)
+
+          next
+        end
+      end
   end
 end