plan_my_stuff 0.17.0 → 0.19.0

data/lib/plan_my_stuff/issue.rb

@@ -255,16 +255,20 @@ module PlanMyStuff
 
       # Finds a single GitHub issue by number and parses its PMS metadata.
       #
+      # Accepts a numeric id (Integer or all-digit String) plus an optional +repo:+ kwarg, or a nickname-id String
+      # (e.g. +"Rawr-1234"+) where the repo is encoded in the prefix and +repo:+ is ignored.
+      #
       # @raise [Octokit::NotFound] when the issue number resolves to a pull request
+      # @raise [ArgumentError] when a nickname-id String references an unknown repo nickname
       #
-      # @param number [Integer]
-      # @param repo [Symbol, String, nil] defaults to config.default_repo
+      # @param id_or_number [Integer, String]
+      # @param repo [Symbol, String, nil] defaults to config.default_repo; ignored when +id_or_number+ is a nickname id
       #
       # @return [PlanMyStuff::Issue]
       #
-      def find(number, repo: nil)
+      def find(id_or_number, repo: nil)
+        number, resolved_repo = resolve_find_args(id_or_number, repo)
         client = PlanMyStuff.client
-        resolved_repo = client.resolve_repo!(repo)
 
         github_issue =
           fetch_with_etag_cache(
@@ -393,8 +397,68 @@ module PlanMyStuff
         raise(PlanMyStuff::APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
       end
 
+      # @raise [ArgumentError] when +repo+ resolves to a Repo with no configured key (cannot reverse-resolve through
+      #   +Repo.from_nickname!+, so the resulting token would not round-trip through +Issue.find+ / +from_param+)
+      #
+      # @param number [Integer]
+      # @param repo [String] full repo path, e.g. +"BrandsInsurance/Element"+
+      #
+      # @return [String]
+      #
+      def to_param(number, repo)
+        return if number.blank?
+        return if repo.blank?
+
+        repo_obj = PlanMyStuff::Repo.resolve!(repo)
+        if repo_obj.key.nil?
+          raise(
+            ArgumentError,
+            "Repo #{repo_obj.full_name.inspect} is not configured in config.repos; " \
+              'cannot build reversible Issue#to_param token',
+          )
+        end
+
+        "#{repo_obj.nickname}-#{number}"
+      end
+
+      # Parses an +Issue#to_param+ string of the form +"Nickname-1234"+ back into +[Repo, Integer]+. The repo is
+      # looked up via +PlanMyStuff::Repo.from_nickname!+, which scans +config.repos+ for the key whose
+      # +config.repo_nickname_for+ matches.
+      #
+      # @raise [ArgumentError] when +param+ does not match the +"Prefix-1234"+ shape or the prefix is not a known
+      #   repo nickname
+      #
+      # @param param [String]
+      #
+      # @return [Array(PlanMyStuff::Repo, Integer)]
+      #
+      def from_param(param)
+        match = param.to_s.match(/\A(?<nickname>.+)-(?<number>\d+)\z/)
+        raise(ArgumentError, "Invalid issue param: #{param.inspect}") if match.nil?
+
+        [PlanMyStuff::Repo.from_nickname!(match[:nickname]), match[:number].to_i]
+      end
+
       private
 
+        # Splits the +Issue.find+ first arg into +[number, resolved_repo_full_name]+. A nickname-id String like
+        # +"Rawr-1234"+ is decoded via +from_param+ (repo derived from the prefix; +repo:+ kwarg ignored). All other
+        # inputs (Integer, all-digit String) fall through to the existing +client.resolve_repo!+ path with the kwarg.
+        #
+        # @param id_or_number [Integer, String]
+        # @param repo [Symbol, String, PlanMyStuff::Repo, nil]
+        #
+        # @return [Array(Integer, String)]
+        #
+        def resolve_find_args(id_or_number, repo)
+          if id_or_number.is_a?(String) && !id_or_number.match?(/\A\d+\z/)
+            repo_obj, number = from_param(id_or_number)
+            [number, repo_obj.full_name]
+          else
+            [id_or_number.to_i, PlanMyStuff.client.resolve_repo!(repo)]
+          end
+        end
+
         # Resolves an +issue_type:+ kwarg to the literal display name GitHub expects. Two stages: a Symbol is first
         # looked up in the gem-side +ISSUE_TYPE_NICKNAMES+ to get a canonical name; then the canonical (or
         # directly-provided String) name is passed through +config.issue_types+ for org-specific renames. Missing
@@ -443,9 +507,8 @@ module PlanMyStuff
         end
 
         # Builds the visible body string written to GitHub for an issue: a markdown link to the consuming-app
-        # per-issue URL (carrying the repo as a +?repo=+ query param so the consuming app knows which repo this issue
-        # lives in), labelled with the GitHub +Org/Repo#number+. Returns +""+ when either +config.issues_url_prefix+
-        # or +number+ is missing.
+        # per-issue URL (in +Issue#to_param+ form, e.g. +"/issues/Rawr-1234"+), labelled with the GitHub
+        # +Org/Repo#number+. Returns +""+ when either +config.issues_url_prefix+ or +number+ is missing.
         #
         # @param number [Integer]
         # @param repo [String] full repo path, e.g. +"BrandsInsurance/Element"+
@@ -456,7 +519,8 @@ module PlanMyStuff
           prefix = PlanMyStuff.configuration.issues_url_prefix
           return '' if prefix.blank? || number.blank?
 
-          url = "#{prefix.to_s.chomp('/')}/#{number}?repo=#{URI.encode_www_form_component(repo)}"
+          to_par = to_param(number, repo)
+          url = "#{prefix.to_s.chomp('/')}/#{to_par}"
           "[#{repo}##{number}](#{url})"
         end
 
@@ -526,17 +590,29 @@ module PlanMyStuff
       @body_dirty = true
     end
 
-    # @return [String, nil] per-issue URL in the consuming app (+config.issues_url_prefix+ + +"/"+ + +number+ +
-    #   +"?repo=Org/Repo"+, or +nil+ when either prefix or number is missing). Also rendered as the destination of
-    #   the markdown link in the GitHub issue body.
+    # Single-segment URL token combining repo nickname and issue number, used by Rails route helpers
+    # (+youtrack_issue_path(@issue)+ -> +"/issues/Rawr-1234"+). Returns +nil+ for new records or when +number+ or
+    # +repo+ is unset; +Issue.from_param+ parses the same shape back into +[Repo, Integer]+.
+    #
+    # @return [String, nil]
+    #
+    def to_param
+      return if new_record?
+
+      self.class.to_param(number, repo)
+    end
+
+    # @return [String, nil] per-issue URL in the consuming app (+config.issues_url_prefix+ + +"/"+ + +to_param+, or
+    #   +nil+ when prefix, number, or repo is missing). Also rendered as the destination of the markdown link in
+    #   the GitHub issue body.
     def user_link
       prefix = PlanMyStuff.configuration.issues_url_prefix
-      return if prefix.blank? || number.blank?
+      return if prefix.blank?
 
-      base = "#{prefix.to_s.chomp('/')}/#{number}"
-      return base if repo.blank?
+      to_par = to_param
+      return if to_par.blank?
 
-      "#{base}?repo=#{URI.encode_www_form_component(repo.full_name)}"
+      "#{prefix.to_s.chomp('/')}/#{to_par}"
     end
 
     # Tags the issue with the configured +archived_label+, removes it from every Projects V2 board it belongs to,

data/lib/plan_my_stuff/repo.rb

@@ -55,6 +55,23 @@ module PlanMyStuff
         end
       end
 
+      # Reverse lookup for the +Issue#to_param+ prefix: finds the configured repo whose nickname (per
+      # +config.repo_nickname_for+) matches +nickname+ and returns its +Repo+ instance.
+      #
+      # @raise [ArgumentError] if no configured repo has the given nickname
+      #
+      # @param nickname [String]
+      #
+      # @return [PlanMyStuff::Repo]
+      #
+      def from_nickname!(nickname)
+        config = PlanMyStuff.configuration
+        match = config.repos.keys.find { |key| config.repo_nickname_for(key) == nickname }
+        raise(ArgumentError, "Unknown repo nickname: #{nickname.inspect}") if match.nil?
+
+        resolve!(match)
+      end
+
       private
 
         # @raise [ArgumentError] if full_name is not in "Org/Repo" format
@@ -88,6 +105,17 @@ module PlanMyStuff
       "#{organization}/#{name}"
     end
 
+    # Human-readable repo label used as the +Issue#to_param+ prefix. Resolves through +config.repo_nickname_for+
+    # when this repo carries a configured +key+; falls back to the bare repo +name+ for unconfigured repos.
+    #
+    # @return [String]
+    #
+    def nickname
+      return PlanMyStuff.configuration.repo_nickname_for(key) if key
+
+      name
+    end
+
     # @see #full_name
     alias to_s full_name
 

data/lib/plan_my_stuff/version.rb

@@ -3,7 +3,7 @@
 module PlanMyStuff
   module VERSION
     MAJOR = 0
-    MINOR = 17
+    MINOR = 19
     TINY = 0
 
     # Set PRE to nil unless it's a pre-release (beta, rc, etc.)

metadata

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