plan_my_stuff 0.20.0 → 0.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06744d7c7bc63206522ce6d7c9176eeb8e93fabb4de903d7df32b17cfae6948d
-  data.tar.gz: 2338f2f85989b2ee3b29a48c114a82d36c8105c13e4caf19b2601ff02cbf063c
+  metadata.gz: 4eda8634e75b318cd847d512405f71d4ffe2b0d7a6beccd6404912a6c64f1c2b
+  data.tar.gz: 80c7edb2a0e861c3dc0f76b06ae23232bde0ed52d04f4cdada69bd29aa8107dd
 SHA512:
-  metadata.gz: dd143db048f77a46fe7875b1592b9ff1dc26e6ddac13af60c177ae977f799606d172a23ca861222a1a133d53fb91d16be19dd40d8f7027b680316276d99088f0
-  data.tar.gz: 607957cf66e887c31bb6ab3f9a93726da0cf853cb3d43e8d34857b0dd789981788de4f0c8c6e076ad5236141732867ed9641971dcc683df5e4683e6b726542f3
+  metadata.gz: 3336630d6d5ee6b8bad51fdfa08a647aa58933e0f30a36241fd137a4d3f5b67656386d36fd0990d289499a7cf2643469e32c1642d4f2d5811be5fc671ea9d420
+  data.tar.gz: 15db293bc2203d60ca7e2b5d102035b1a8d064a74b84666e13d0fbcad1ab15dbe576f02af2f7582c56c9f65246dbb23e41043f6036e304801722c40890c463fc

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.21.1
+
+### Added
+
+- `config.eager_load_controllers_on_boot` (default `false`). When `true`, the engine eager-loads
+  `app/controllers/` in `after_initialize` so consuming apps with `eager_load = false` (dev mode) see
+  `PlanMyStuff::*Controller` constants without having to reference them first. Opt in if the host app
+  probes engine controllers via `defined?`, e.g. `defined?(PlanMyStuff::Issues::TakesController)` would
+  otherwise return `nil` until something triggered Zeitwerk autoload. Falls back to `Kernel#require` on
+  Zeitwerk < 2.6.2 (which lacks `eager_load_dir`).
+
+## 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/CONFIGURATION.md

@@ -49,6 +49,19 @@ config.repo_nicknames = { safety: 'Compliance' } # :element -> "Element", :under
 `Issue#to_param` then returns `"Element-1234"` / `"Compliance-567"`, encoding both repo and number in a single
 URL segment so `youtrack_issue_path(@issue)` works without a `repo:` query param.
 
+## Attachments
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `attachment_repo` | `String` | `'pms-attachments'` | Bare repo (under `organization`) for uploaded attachments. |
+
+The repo must already exist; the uploader does not create it. Attachments commit onto
+`config.main_branch` under `<repo_key_or_name>/issue-<number>/<uuid>.<ext>`.
+
+```ruby
+config.attachment_repo = 'pms-attachments'
+```
+
 ## Projects
 
 | Option | Type | Default | Description |
@@ -337,6 +350,20 @@ config.cache_version = Rails.configuration.x.image_tag
 config.mount_groups = { webhooks: true, issues: true, projects: true }
 ```
 
+## Boot behavior
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `eager_load_controllers_on_boot` | `Boolean` | `false` | Eager-load engine controllers in `after_initialize`. |
+
+Opt in if the host app probes engine controllers via `defined?` in dev mode. When `true`, the
+engine walks `app/controllers` once on boot so `defined?(PlanMyStuff::SomeController)` resolves
+without first referencing the constant.
+
+```ruby
+config.eager_load_controllers_on_boot = true
+```
+
 ## Controller overrides
 
 | Option | Type | Default | Description |

data/lib/generators/plan_my_stuff/install/templates/initializer.rb

@@ -30,6 +30,15 @@ PlanMyStuff.configure do |config|
   # need an entry.
   # config.repo_nicknames = { safety: 'Compliance' }
 
+  # --------------------------------------------------------------------------
+  # Attachments
+  # --------------------------------------------------------------------------
+  # Bare repo name (under `organization`) that stores uploaded attachment
+  # binaries. The repo must already exist; the uploader does not create it.
+  # Attachments commit onto `config.main_branch` under
+  # `<repo_key_or_name>/issue-<number>/<uuid>.<ext>`.
+  # config.attachment_repo = 'pms-attachments'
+
   # --------------------------------------------------------------------------
   # Projects
   # --------------------------------------------------------------------------
@@ -184,6 +193,16 @@ PlanMyStuff.configure do |config|
   #
   # config.issue_fields_enabled = false
 
+  # --------------------------------------------------------------------------
+  # Boot behavior
+  # --------------------------------------------------------------------------
+  # Eager-load the engine's controllers in after_initialize so that
+  # `defined?(PlanMyStuff::SomeController)` resolves without first referencing
+  # the constant. Opt in if the host app probes engine controllers via
+  # `defined?` in dev mode.
+  #
+  # config.eager_load_controllers_on_boot = true
+
   # --------------------------------------------------------------------------
   # Release pipeline
   # --------------------------------------------------------------------------

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/configuration.rb

@@ -373,6 +373,15 @@ module PlanMyStuff
     #
     attr_accessor :issue_fields_enabled
 
+    # Whether to eager-load the engine's controllers on host boot. Defaults to +false+ (opt-in). When +true+, the engine
+    # walks +app/controllers+ during +after_initialize+ so +defined?(PlanMyStuff::SomeController)+ resolves without
+    # first referencing the constant. Enable in host apps that rely on +defined?+ probes against engine controllers in
+    # dev mode.
+    #
+    # @return [Boolean]
+    #
+    attr_accessor :eager_load_controllers_on_boot
+
     # @return [Configuration]
     def initialize
       @repos = {}
@@ -413,6 +422,7 @@ module PlanMyStuff
       @pipeline_completion_purge_enabled = true
       @pipeline_completion_ttl_hours = 24
       @issue_fields_enabled = true
+      @eager_load_controllers_on_boot = false
       @process_aws_webhooks = Rails.env.production?
       @sns_verifier_class = ::Aws::SNS::MessageVerifier if defined?(::Aws::SNS::MessageVerifier)
       @sns_verifier_error =

data/lib/plan_my_stuff/engine.rb

@@ -3,5 +3,21 @@
 module PlanMyStuff
   class Engine < ::Rails::Engine
     isolate_namespace PlanMyStuff
+
+    # Opt-in (via +config.eager_load_controllers_on_boot+): eager-load the engine's controllers regardless of the host
+    # app's eager_load setting. Without this, `defined?(PlanMyStuff::SomeController)` returns nil in host-app dev mode
+    # until something explicitly references the constant, since `defined?` does not trigger Zeitwerk autoload.
+    config.after_initialize do
+      next unless PlanMyStuff.configuration.eager_load_controllers_on_boot
+
+      controllers_dir = File.expand_path('../../app/controllers', __dir__)
+      loader = Rails.autoloaders.main
+
+      if loader.respond_to?(:eager_load_dir)
+        loader.eager_load_dir(controllers_dir)
+      else
+        Dir.glob(File.join(controllers_dir, '**/*.rb')).sort.each { |path| require path }
+      end
+    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,8 +3,8 @@
 module PlanMyStuff
   module VERSION
     MAJOR = 0
-    MINOR = 20
-    TINY = 0
+    MINOR = 21
+    TINY = 1
 
     # Set PRE to nil unless it's a pre-release (beta, rc, etc.)
     PRE = nil

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plan_my_stuff
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.1
 platform: ruby
 authors:
 - Brands Insurance
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-20 00:00:00.000000000 Z
+date: 2026-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails