plan_my_stuff 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06744d7c7bc63206522ce6d7c9176eeb8e93fabb4de903d7df32b17cfae6948d
-  data.tar.gz: 2338f2f85989b2ee3b29a48c114a82d36c8105c13e4caf19b2601ff02cbf063c
+  metadata.gz: 0d33c652f54d9d078276d12baac63134e8bba4064185f61626c66fd924ea958a
+  data.tar.gz: 54f5c69130890fa5ae807d642cd8d89d2f0d74c4d12b638ed892d8f9b2df22d8
 SHA512:
-  metadata.gz: dd143db048f77a46fe7875b1592b9ff1dc26e6ddac13af60c177ae977f799606d172a23ca861222a1a133d53fb91d16be19dd40d8f7027b680316276d99088f0
-  data.tar.gz: 607957cf66e887c31bb6ab3f9a93726da0cf853cb3d43e8d34857b0dd789981788de4f0c8c6e076ad5236141732867ed9641971dcc683df5e4683e6b726542f3
+  metadata.gz: 36d2a9a1624279d818d6c1a16fcfd51cd8e047e4f02d51044673fecb0ef3433b4a953290eb51deb868b9a8959fe365abf4dcb0645883466941047c6915c070d3
+  data.tar.gz: fbadf2e2e8337a7014e148e898291de7ef4453729332f2c8d2609942487ebec7359a97a687e44340edac1a0d7c8e36fdeddcd3cc90c8fe30a108f76f7ba74a49

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # 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

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/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 = 20
+    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.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Brands Insurance