plan_my_stuff 0.19.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15988155f3d1798b5b0f43cbb1597f7e8b7ed881feb3db2504da7ecd74ab9c59
-  data.tar.gz: 35f298dce675a86ca15153a354411c23806e8420374fe5eb4fd7d2c392e0ed9d
+  metadata.gz: 0d33c652f54d9d078276d12baac63134e8bba4064185f61626c66fd924ea958a
+  data.tar.gz: 54f5c69130890fa5ae807d642cd8d89d2f0d74c4d12b638ed892d8f9b2df22d8
 SHA512:
-  metadata.gz: 838ebf5cb77a3467fb291d76acd9b2ded4cc40d88e65673ca41374324736c6cdc11e5bbc0ed7e04eaf0c0bb5ac4f799c3052379cdc87edcd7343dc30be370059
-  data.tar.gz: b30d829c2255b61485c72d639992f1095f9726b7e6d8952114eef2e44c91f1016c0f05bd3abd238faf0be83a37c8b75ef492208351d33cbbe1f2f689270e7614
+  metadata.gz: 36d2a9a1624279d818d6c1a16fcfd51cd8e047e4f02d51044673fecb0ef3433b4a953290eb51deb868b9a8959fe365abf4dcb0645883466941047c6915c070d3
+  data.tar.gz: fbadf2e2e8337a7014e148e898291de7ef4453729332f2c8d2609942487ebec7359a97a687e44340edac1a0d7c8e36fdeddcd3cc90c8fe30a108f76f7ba74a49

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.21.0
+
+### Breaking
+
+- `PMS::Attachment` no longer accepts/stores a single `url:` attribute. Construct with explicit
+  `filename:`, `owner:`, `repo:`, `sha:`, `path:` instead; `#url` is now a derived method that returns the
+  GitHub blob viewer URL (`https://github.com/{owner}/{repo}/blob/{sha}/{path}`) rather than the
+  `raw.githubusercontent.com` URL. `#to_h` emits the structured fields and no longer includes a `url` key.
+  Persisted comment metadata in the legacy `{filename, url}` shape is migrated on read and rewritten in the
+  new shape on next save (closes #70).
+
+### Added
+
+- Comment bodies now render a visible `<details><summary>attachments (N)</summary>` block listing each
+  attachment as a markdown link to its blob URL, between the `pms-metadata` block and the user body. The
+  parser strips this block on read so round-trips stay clean.
+
+## 0.20.0
+
+### Breaking
+
+- `priority_list` and `priority_list_priority` keys removed from `IssueMetadata` serialization. Existing issues
+  migrate to the GitHub Issue Field equivalents (`Priority List`, `Priority List Priority`) on their next save.
+
+### Added
+
+- `Issue#priority_list?` and `Issue#priority_list_priority` read the corresponding issue field values directly.
+- `Issue.priority_list(repo:, state:, labels:, page:, per_page:)` convenience method delegates to
+  `Issue.list(priority_list: true, ...)`.
+- `Issue.list` and `Issue.count` accept `priority_list:` for server-side filtering via the GitHub issue fields
+  API (passes `priority_list: false` raises `ArgumentError` -- the API has no negation qualifier).
+
+### Deprecated
+
+- `IssueMetadata#priority_list`, `#priority_list=`, `#priority_list?`, `#priority_list_priority`, and
+  `#priority_list_priority=` emit deprecation warnings on each read/write. Legacy writes forward to the issue
+  field on `Issue#save!` / `#update!` / `Issue.create!`. The accessors will be removed in 1.0.0.
+
 ## 0.19.0
 
 ### Added

data/lib/plan_my_stuff/attachment.rb

@@ -6,33 +6,40 @@ require 'tmpdir'
 module PlanMyStuff
   # Value object representing a single attachment record on a +Comment+.
   # Persisted in +CommentMetadata#attachments+; the gem owns the upload
-  # (see +PlanMyStuff::AttachmentUploader+) and stores a SHA-pinned
-  # +raw.githubusercontent.com+ permalink so the file remains reachable
-  # across later branch rewrites.
+  # (see +PlanMyStuff::AttachmentUploader+) and stores the structured
+  # location (+owner+/+repo+/+sha+/+path+) of the uploaded file so the
+  # blob remains addressable across later branch rewrites.
   #
   # Mirrors +PlanMyStuff::Link+ / +PlanMyStuff::Approval+:
   # +ActiveModel::Attributes+-backed, with +Serializers::JSON+ for
   # round-trip through the metadata blob.
   #
   class Attachment
-    RAW_URL_REGEX =
-      %r{\Ahttps://raw\.githubusercontent\.com/(?<owner>[^/\s]+)/(?<repo>[^/\s]+)/(?<sha>[^/\s]+)/(?<path>.+)\z}
-
     include ActiveModel::Model
     include ActiveModel::Attributes
     include ActiveModel::Serializers::JSON
 
     # @return [String] display filename (user-provided original name)
     attribute :filename, :string
-    # @return [String] SHA-pinned raw.githubusercontent.com permalink to the uploaded file
-    attribute :url, :string
+    # @return [String] owner of the attachment repo (e.g. +"BrandsInsurance"+)
+    attribute :owner, :string
+    # @return [String] attachment repo name
+    attribute :repo, :string
+    # @return [String] commit SHA pinning the file
+    attribute :sha, :string
+    # @return [String] path within the attachment repo (no leading slash)
+    attribute :path, :string
+
+    validates :filename, :owner, :repo, :sha, :path, presence: true
 
-    validates :filename, presence: true
-    validates :url, presence: true, format: { with: RAW_URL_REGEX }
+    # @return [String] blob-viewer URL for the pinned file
+    def url
+      "https://github.com/#{owner}/#{repo}/blob/#{sha}/#{path}"
+    end
 
     # @return [Hash]
     def to_h
-      { filename: filename, url: url }
+      { filename: filename, owner: owner, repo: repo, sha: sha, path: path }
     end
 
     # @param other [Object]
@@ -56,22 +63,21 @@ module PlanMyStuff
     # Defaults the destination to +Dir.tmpdir+ joined with +File.basename(filename)+ (directory components
     # stripped to prevent path traversal).
     #
-    # @param path [String, nil] destination path; defaults to +File.join(Dir.tmpdir, File.basename(filename))+
+    # @param dest [String, nil] destination path; defaults to +File.join(Dir.tmpdir, File.basename(filename))+
     #
     # @return [String] the path the bytes were written to
     #
-    def download_to(path = nil)
-      path ||= File.join(Dir.tmpdir, File.basename(filename.to_s))
-      match = RAW_URL_REGEX.match(url)
+    def download_to(dest = nil)
+      dest ||= File.join(Dir.tmpdir, File.basename(filename.to_s))
       body = PlanMyStuff.client.rest(
         :contents,
-        "#{match[:owner]}/#{match[:repo]}",
-        path: match[:path],
-        ref: match[:sha],
+        "#{owner}/#{repo}",
+        path: path,
+        ref: sha,
         accept: 'application/vnd.github.raw',
       )
-      File.binwrite(path, body)
-      path
+      File.binwrite(dest, body)
+      dest
     end
   end
 end

data/lib/plan_my_stuff/attachment_uploader.rb

@@ -6,8 +6,8 @@ require 'securerandom'
 
 module PlanMyStuff
   # Uploads attachment files to a shared attachment repo (+config.attachment_repo+ under +config.organization+) using
-  # GitHub's Git Data API, returning SHA-pinned +raw.githubusercontent.com+ permalinks wrapped in
-  # +PlanMyStuff::Attachment+ instances.
+  # GitHub's Git Data API, returning +PlanMyStuff::Attachment+ instances populated with the structured
+  # +owner+/+repo+/+sha+/+path+ location of each uploaded file.
   #
   # One commit per batch (atomic): all files in a single +upload_all!+ call land in the same tree/commit so partial
   # failures cannot leave +config.main_branch+ in an inconsistent state.
@@ -202,8 +202,13 @@ module PlanMyStuff
         # @return [PlanMyStuff::Attachment]
         #
         def build_attachment(commit_sha:, slot:)
-          url = "https://raw.githubusercontent.com/#{attachment_repo_full_name}/#{commit_sha}/#{slot[:path]}"
-          PlanMyStuff::Attachment.new(filename: slot[:filename], url: url)
+          PlanMyStuff::Attachment.new(
+            filename: slot[:filename],
+            owner: PlanMyStuff.configuration.organization,
+            repo: PlanMyStuff.configuration.attachment_repo,
+            sha: commit_sha,
+            path: slot[:path],
+          )
         end
 
         # @return [String] +"<organization>/<attachment_repo>"+

data/lib/plan_my_stuff/comment_metadata.rb

@@ -2,6 +2,17 @@
 
 module PlanMyStuff
   class CommentMetadata < PlanMyStuff::BaseMetadata
+    LEGACY_URL_REGEXES = [
+      %r{\Ahttps://raw\.githubusercontent\.com/(?<owner>[^/\s]+)/(?<repo>[^/\s]+)/(?<sha>[^/\s]+)/(?<path>.+)\z},
+      %r{\Ahttps://github\.com/(?<owner>[^/\s]+)/(?<repo>[^/\s]+)/blob/(?<sha>[^/\s]+)/(?<path>.+)\z},
+    ].freeze
+
+    LEGACY_ATTACHMENT_DEPRECATION_MESSAGE =
+      'PlanMyStuff: legacy attachment metadata shape {filename, url} detected. It will continue to parse ' \
+        'until 1.0.0, at which point legacy detection will be removed. New writes use the structured ' \
+        '{filename, owner, repo, sha, path} shape introduced in #70; existing entries migrate on their ' \
+        'next write.'
+
     # @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
@@ -82,9 +93,14 @@ module PlanMyStuff
     private
 
       # Builds a +PlanMyStuff::Attachment+ from each parsed entry.
-      # Each entry is a +{filename:, url:}+ hash (symbol keys when
-      # built locally, string keys when read back from GitHub
-      # metadata) or an existing +PlanMyStuff::Attachment+.
+      # Accepts:
+      # - an existing +PlanMyStuff::Attachment+
+      # - the new shape +{filename:, owner:, repo:, sha:, path:}+
+      # - the legacy shape +{filename:, url:}+ where +url+ is a raw
+      #   +raw.githubusercontent.com+ permalink or a +github.com/.../blob/...+
+      #   blob-viewer URL; parsed once into structured fields so the
+      #   next write drops the +url+ key (migrate-on-write).
+      #
       # 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
@@ -102,7 +118,7 @@ module PlanMyStuff
             if entry.is_a?(PlanMyStuff::Attachment)
               entry
             elsif entry.respond_to?(:transform_keys)
-              PlanMyStuff::Attachment.new(entry.transform_keys(&:to_sym))
+              PlanMyStuff::Attachment.new(structured_attrs(entry.transform_keys(&:to_sym)))
             end
           next if attachment.nil?
 
@@ -114,5 +130,33 @@ module PlanMyStuff
           next
         end
       end
+
+      # Returns +attrs+ untouched when it already carries structured
+      # fields, otherwise parses a legacy +url+ into
+      # +owner+/+repo+/+sha+/+path+. Unparseable URLs yield a hash
+      # with no structured fields, leaving +Attachment+ validation to
+      # drop the entry.
+      #
+      # @param attrs [Hash{Symbol=>Object}]
+      #
+      # @return [Hash{Symbol=>Object}]
+      #
+      def structured_attrs(attrs)
+        return attrs if attrs.key?(:owner)
+
+        PlanMyStuff.deprecator.warn(LEGACY_ATTACHMENT_DEPRECATION_MESSAGE)
+
+        url = attrs[:url].to_s
+        match = LEGACY_URL_REGEXES.lazy.filter_map { |re| re.match(url) }.first
+
+        return attrs.except(:url) if match.nil?
+
+        attrs.except(:url).merge(
+          owner: match[:owner],
+          repo: match[:repo],
+          sha: match[:sha],
+          path: match[:path],
+        )
+      end
   end
 end

data/lib/plan_my_stuff/issue.rb

@@ -296,26 +296,46 @@ module PlanMyStuff
 
       # Lists GitHub issues with optional filters and pagination.
       #
+      # @raise [ArgumentError] when +priority_list: false+ is passed
+      #
       # @param repo [Symbol, String, nil] defaults to config.default_repo
       # @param state [Symbol] :open, :closed, or :all
       # @param labels [Array<String>]
+      # @param priority_list [Boolean, nil] when +true+, restricts to issues whose +Priority List+ issue field is
+      #   +Yes+ (server-side filter via the +issue_field_values+ query param). +false+ raises +ArgumentError+ -- GitHub
+      #   has no negation qualifier. Silently dropped when +config.issue_fields_enabled+ is +false+.
       # @param page [Integer]
       # @param per_page [Integer]
       #
       # @return [Array<PlanMyStuff::Issue>]
       #
-      def list(repo: nil, state: :open, labels: [], page: 1, per_page: 25)
+      def list(repo: nil, state: :open, labels: [], priority_list: nil, page: 1, per_page: 25)
+        if priority_list == false
+          raise(ArgumentError, 'priority_list: false is not supported (no GitHub negation qualifier)')
+        end
+
         client = PlanMyStuff.client
         resolved_repo = client.resolve_repo!(repo)
 
         params = { state: state.to_s, page: page, per_page: per_page }
         params[:labels] = labels.sort.join(',') if labels.present?
+        if priority_list && PlanMyStuff.configuration.issue_fields_enabled
+          params[:issue_field_values] = 'priority-list:Yes'
+        end
 
         github_issues = client.rest(:list_issues, resolved_repo, **params)
         filtered = github_issues.reject { |gi| gi.respond_to?(:pull_request) && gi.pull_request }
         filtered.map { |gi| build(gi, repo: resolved_repo) }
       end
 
+      # Convenience shortcut for +list(priority_list: true, ...)+. See +.list+ for parameter semantics.
+      #
+      # @return [Array<PlanMyStuff::Issue>]
+      #
+      def priority_list(**)
+        list(**, priority_list: true)
+      end
+
       # Counts GitHub issues matching the given filters without paginating full payloads.
       #
       # Uses GitHub's Search API (+search/issues+), which returns +total_count+ in a single
@@ -327,13 +347,23 @@ module PlanMyStuff
       # - The Search API has its own rate limit (30 req/min authenticated) separate from
       #   the core REST API.
       #
+      # @raise [ArgumentError] when +priority_list: false+ is passed
+      #
       # @param repo [Symbol, String, nil] defaults to config.default_repo
       # @param state [Symbol] :open, :closed, or :all
       # @param labels [Array<String>]
+      # @param priority_list [Boolean, nil] when +true+, restricts to issues whose +Priority List+ issue field is
+      #   +Yes+ (server-side filter via the +field.priority-list:Yes+ Search qualifier). +false+ raises
+      #   +ArgumentError+ -- GitHub has no negation qualifier. Silently dropped when
+      #   +config.issue_fields_enabled+ is +false+.
       #
       # @return [Integer]
       #
-      def count(repo: nil, state: :open, labels: [])
+      def count(repo: nil, state: :open, labels: [], priority_list: nil)
+        if priority_list == false
+          raise(ArgumentError, 'priority_list: false is not supported (no GitHub negation qualifier)')
+        end
+
         client = PlanMyStuff.client
         resolved_repo = client.resolve_repo!(repo)
 
@@ -344,7 +374,12 @@ module PlanMyStuff
         qualifiers += labels_to_use.map do |label|
           "label:\"#{label}\""
         end
-        client.rest(:search_issues, qualifiers.join(' '), per_page: 1).total_count
+        search_options = { per_page: 1 }
+        if priority_list && PlanMyStuff.configuration.issue_fields_enabled
+          qualifiers << 'field.priority-list:Yes'
+          search_options[:advanced_search] = true
+        end
+        client.rest(:search_issues, qualifiers.join(' '), **search_options).total_count
       end
 
       # Submits one or more pre-built payloads to GitHub's "Import Issues" preview endpoint
@@ -663,6 +698,8 @@ module PlanMyStuff
     # @return [self]
     #
     def save!(user: nil, skip_notification: false)
+      forward_legacy_priority_list_metadata!
+
       if new_record?
         created = self.class.create!(
           title: title,
@@ -795,6 +832,16 @@ module PlanMyStuff
       @issue_fields ||= load_issue_fields!
     end
 
+    # @return [Boolean]
+    def priority_list?
+      issue_fields['Priority List'] == 'Yes'
+    end
+
+    # @return [Integer, nil]
+    def priority_list_priority
+      issue_fields['Priority List Priority']
+    end
+
     # Bulk-updates GitHub Issue Field values in a single +setIssueFieldValue+ mutation. Each key is the field display
     # name; values are coerced to the right input fragment based on the field's type. Passing +nil+ as a value clears
     # that field.
@@ -934,6 +981,28 @@ module PlanMyStuff
         reload
       end
 
+      # Forwards a pending legacy +metadata.priority_list+ /
+      # +#priority_list_priority+ write into +@pending_issue_fields+ so the next
+      # +save!+ persists the values into the +Priority List+ /
+      # +Priority List Priority+ GitHub Issue Fields. Caller-supplied
+      # +issue_fields:+ entries win on key collision. Silently skipped when
+      # +config.issue_fields_enabled+ is +false+.
+      #
+      # @return [void]
+      #
+      def forward_legacy_priority_list_metadata!
+        return unless PlanMyStuff.configuration.issue_fields_enabled
+        return unless metadata.instance_variable_get(:@legacy_priority_list_pending)
+
+        legacy_pl = metadata.instance_variable_get(:@priority_list)
+        legacy_plp = metadata.instance_variable_get(:@priority_list_priority)
+
+        legacy_fields = { 'Priority List' => legacy_pl ? 'Yes' : nil }
+        legacy_fields['Priority List Priority'] = legacy_plp unless legacy_plp == -1
+
+        @pending_issue_fields = legacy_fields.merge(@pending_issue_fields || {})
+      end
+
       # Applies in-memory updates from an +update!+ kwargs hash. Top-level scalars go through their setters so
       # +@body_dirty+ and friends stay in sync; +metadata:+ is merged into +@metadata+ (top-level attrs assigned
       # directly, custom_fields merged key-by-key).

data/lib/plan_my_stuff/issue_metadata.rb

@@ -2,14 +2,16 @@
 
 module PlanMyStuff
   class IssueMetadata < PlanMyStuff::BaseMetadata
+    PRIORITY_LIST_METADATA_DEPRECATION =
+      'PlanMyStuff: IssueMetadata#priority_list / #priority_list_priority are deprecated. priority_list moved to ' \
+        "GitHub Issue Fields ('Priority List' single_select, 'Priority List Priority' number) in 0.20.0. Reads " \
+        'now come from issue_fields; legacy writes forward to set_issue_fields! on save. The metadata accessors ' \
+        'will be removed in 1.0.0.'
+
     # @return [Time, nil] first support action timestamp, nil until set
     attr_accessor :responded_at
     # @return [String, nil] user-facing URL in the consuming app
     attr_accessor :issues_url
-    # @return [Boolean] whether this issue appears on the priority dashboard
-    attr_accessor :priority_list
-    # @return [Integer] sort order on priority dashboard (-1 = unranked)
-    attr_accessor :priority_list_priority
     # @return [Array<Integer>] user IDs of non-support users allowed to view internal comments
     attr_accessor :visibility_allowlist
     # @return [String, nil] merged PR commit SHA for release tracking
@@ -50,8 +52,14 @@ module PlanMyStuff
 
         metadata.responded_at = parse_time(hash[:responded_at])
         metadata.issues_url = hash[:issues_url]
-        metadata.priority_list = hash.fetch(:priority_list, false)
-        metadata.priority_list_priority = hash.fetch(:priority_list_priority, -1)
+        if hash.key?(:priority_list) || hash.key?(:priority_list_priority)
+          PlanMyStuff.deprecator.warn(PRIORITY_LIST_METADATA_DEPRECATION)
+          metadata.instance_variable_set(:@priority_list, hash[:priority_list]) if hash.key?(:priority_list)
+          if hash.key?(:priority_list_priority)
+            metadata.instance_variable_set(:@priority_list_priority, hash[:priority_list_priority])
+          end
+          metadata.instance_variable_set(:@legacy_priority_list_pending, true)
+        end
         metadata.visibility_allowlist = Array.wrap(hash[:visibility_allowlist])
         metadata.commit_sha = hash[:commit_sha]
         metadata.auto_complete = hash.fetch(:auto_complete, true)
@@ -86,8 +94,6 @@ module PlanMyStuff
 
         metadata.responded_at = nil
         metadata.issues_url = build_issues_url(PlanMyStuff.configuration)
-        metadata.priority_list = false
-        metadata.priority_list_priority = -1
         metadata.visibility_allowlist = []
         metadata.commit_sha = nil
         metadata.auto_complete = true
@@ -169,8 +175,6 @@ module PlanMyStuff
 
     def initialize
       super
-      @priority_list = false
-      @priority_list_priority = -1
       @visibility_allowlist = []
       @auto_complete = true
       @links = []
@@ -188,9 +192,55 @@ module PlanMyStuff
       !!auto_complete
     end
 
+    # @deprecated Use +Issue#priority_list?+. Removed in 1.0.0.
+    #
+    # @return [Object, nil]
+    #
+    def priority_list
+      PlanMyStuff.deprecator.warn(PRIORITY_LIST_METADATA_DEPRECATION)
+      @priority_list
+    end
+
+    # @deprecated Use +Issue#update!(issue_fields: { 'Priority List' => 'Yes' })+. Removed in 1.0.0.
+    #
+    # @param value [Object]
+    #
+    # @return [Object]
+    #
+    def priority_list=(value)
+      PlanMyStuff.deprecator.warn(PRIORITY_LIST_METADATA_DEPRECATION)
+      @legacy_priority_list_pending = true
+      @priority_list = value
+    end
+
+    # @deprecated Use +Issue#priority_list?+. Removed in 1.0.0.
+    #
     # @return [Boolean]
+    #
     def priority_list?
-      !!priority_list
+      PlanMyStuff.deprecator.warn(PRIORITY_LIST_METADATA_DEPRECATION)
+      !!@priority_list
+    end
+
+    # @deprecated Use +Issue#priority_list_priority+. Removed in 1.0.0.
+    #
+    # @return [Object, nil]
+    #
+    def priority_list_priority
+      PlanMyStuff.deprecator.warn(PRIORITY_LIST_METADATA_DEPRECATION)
+      @priority_list_priority
+    end
+
+    # @deprecated Use +Issue#update!(issue_fields: { 'Priority List Priority' => N })+. Removed in 1.0.0.
+    #
+    # @param value [Object]
+    #
+    # @return [Object]
+    #
+    def priority_list_priority=(value)
+      PlanMyStuff.deprecator.warn(PRIORITY_LIST_METADATA_DEPRECATION)
+      @legacy_priority_list_pending = true
+      @priority_list_priority = value
     end
 
     # @return [Boolean]
@@ -220,8 +270,6 @@ module PlanMyStuff
       super.merge(
         responded_at: PlanMyStuff.format_time(responded_at),
         issues_url: issues_url,
-        priority_list: priority_list,
-        priority_list_priority: priority_list_priority,
         visibility_allowlist: visibility_allowlist,
         commit_sha: commit_sha,
         auto_complete: auto_complete,

data/lib/plan_my_stuff/metadata_parser.rb

@@ -18,6 +18,15 @@ module PlanMyStuff
       </details>\n*
     }mx
 
+    # Visible attachments block emitted after the metadata block when the
+    # metadata carries non-empty +attachments+ (issue #70). Parse strips it
+    # so round-trips stay clean.
+    ATTACHMENTS_PATTERN = %r{
+      \A<details><summary>attachments\ \(\d+\)</summary>\n\n
+      .*?\n\n
+      </details>\n*
+    }mx
+
     # Legacy format kept for parsing only - existing issues serialized before 0.17.0
     # used a hidden HTML comment. They migrate to the new format on the next write.
     LEGACY_METADATA_PATTERN = /\A<!-- pms-metadata:(.*?) -->\n*/m
@@ -40,7 +49,7 @@ module PlanMyStuff
 
       match = raw_body.match(pattern)
       metadata = JSON.parse(match[1], symbolize_names: true)
-      body = raw_body.sub(pattern, '')
+      body = raw_body.sub(pattern, '').sub(ATTACHMENTS_PATTERN, '')
 
       { metadata: metadata, body: body }
     rescue JSON::ParserError
@@ -61,14 +70,37 @@ module PlanMyStuff
         raise(ArgumentError, "metadata must be a Hash or PlanMyStuff::CustomFields, got #{metadata.class}")
       end
 
-      json =
-        if metadata.is_a?(PlanMyStuff::CustomFields)
-          JSON.pretty_generate(metadata.to_h)
-        else
-          JSON.pretty_generate(metadata)
-        end
+      hash = metadata.is_a?(PlanMyStuff::CustomFields) ? metadata.to_h : metadata
+      json = JSON.pretty_generate(hash)
+
+      "<details><summary>pms-metadata</summary>\n\n```json\n#{json}\n```\n\n</details>\n\n" \
+        "#{attachments_block(hash)}#{body}"
+    end
 
-      "<details><summary>pms-metadata</summary>\n\n```json\n#{json}\n```\n\n</details>\n\n#{body}"
+    # Renders the visible attachments block when +metadata+ carries
+    # non-empty +:attachments+, otherwise returns an empty string.
+    #
+    # @param metadata [Hash]
+    #
+    # @return [String]
+    #
+    def attachments_block(metadata)
+      attachments = metadata[:attachments]
+      return '' if attachments.blank?
+
+      lines = attachments.map { |a| attachment_line(a) }.join("\n")
+      "<details><summary>attachments (#{attachments.size})</summary>\n\n#{lines}\n\n</details>\n\n"
+    end
+
+    # @param attachment [Hash{Symbol=>String}]
+    #
+    # @return [String]
+    #
+    def attachment_line(attachment)
+      url = "https://github.com/#{attachment[:owner]}/#{attachment[:repo]}" \
+        "/blob/#{attachment[:sha]}/#{attachment[:path]}"
+      safe_filename = attachment[:filename].to_s.gsub(']', '\]')
+      "- [#{safe_filename}](#{url})"
     end
 
     # @param raw_body [String]

data/lib/plan_my_stuff/version.rb

@@ -3,7 +3,7 @@
 module PlanMyStuff
   module VERSION
     MAJOR = 0
-    MINOR = 19
+    MINOR = 21
     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.19.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Brands Insurance