plan_my_stuff 0.23.1 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0853fca62201cdc20425d04f36c026ac6c774f25c66fc50c8af03153351ec3c9'
-  data.tar.gz: bb2fcbc5a0c73e63a855171c59bea381276e2d6dc3644c46a86cf0c45b5ca0a9
+  metadata.gz: 1cf33c92cfa763f5ace87a1419cf8c7369f27e8adc10d1c092c044b99d151a4a
+  data.tar.gz: 3b2a482534b9f9094d550385c064f50f4dc37db3c2a6361e4aa899d4b4dc5713
 SHA512:
-  metadata.gz: 2289f6bfac960098c6c5a9c8fdc90f66a1078f75fb4aea86620f2b65cfdcef201e12c4b48eabd52d5d7bebf8b488051550597544f98433bc2529c44eae4d8a11
-  data.tar.gz: f9c66f66762f229bf9023ac85e6b636740cc74020dbe011f046b6dd391304b2e5d1416abe72bc8a7c9c8c2018c28f8fd393d370a44649fe1767f1c7d96a05fb3
+  metadata.gz: ef36dbcfb77d4c3763d2165993c50fb9f4f7e8b0729a1efc1d63fb9155abb039bf9db92fb59a49d3302ebfec024bafc19dd15b54be84a2d7919040405a10803f
+  data.tar.gz: beae8f4926a95e4a47786c4ffefc886300f255466d7e08a7e607f444e91883e920b3bf60d666d33b539eed2dac7a1241f64cd23ae42ebe292a8a113ce150de8d

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.24.0
+
+### Added
+
+- `PlanMyStuff::Issue.list` and `PlanMyStuff::Issue.count` now accept `issue_type:` (String / Symbol) and
+  `issue_fields:` (Hash keyed by display name) filter kwargs. `issue_type:` resolves symbol nicknames through
+  `ISSUE_TYPE_NICKNAMES` and `config.issue_types`; Arrays raise `ArgumentError` since GitHub's REST `type` param
+  and Search `type:` qualifier each accept only one value. `issue_fields:` accepts scalar (equality) or `Range`
+  (date / numeric bounds -- inclusive
+  `..` -> `>=`/`<=`, exclusive `...` -> `>=`/`<`, beginless / endless ranges drop the unbounded side) values and ANDs
+  multiple constraints together. Composes with the existing `priority_list:` filter into the same
+  `issue_field_values` (REST) / `field.<slug>:` (Search) qualifier list. Search-API calls flip
+  `advanced_search=true` when any field qualifier is present. `issue_fields:` raises
+  `IssueFieldsNotEnabledError` when `config.issue_fields_enabled` is `false` (closes #54).
+
 ## 0.23.1
 
 ### Added

data/lib/plan_my_stuff/issue.rb

@@ -296,11 +296,29 @@ module PlanMyStuff
 
       # Lists GitHub issues with optional filters and pagination.
       #
-      # @raise [ArgumentError] when +priority_list: false+ is passed
+      # +issue_fields:+ is a Hash keyed by GitHub Issue Field display name (String / Symbol). Each value is either
+      # a scalar (equality match -- Date / Time are emitted as ISO 8601, everything else as +to_s+) or a +Range+ for
+      # numeric / date bounds:
+      #
+      # - +Date.parse('2026-01-01')..Date.today+ -> +start-date:>=2026-01-01,start-date:<=2026-05-21+
+      # - +Date.parse('2026-01-01')...Date.today+ -> +start-date:>=2026-01-01,start-date:<2026-05-21+ (exclusive end)
+      # - +..Date.today+ (beginless) / +Date.parse('2026-01-01')..+ (endless) drop the unbounded side
+      #
+      # Multiple field constraints AND together. Composes with the existing +priority_list:+ filter: both feed the
+      # same +issue_field_values+ query param.
+      #
+      # @raise [ArgumentError] when +priority_list: false+ is passed, or when +issue_type:+ is an Array (GitHub's
+      #   REST +type+ param only accepts a single value)
+      # @raise [PlanMyStuff::IssueFieldsNotEnabledError] when +issue_fields:+ is passed and
+      #   +config.issue_fields_enabled+ is +false+
       #
       # @param repo [Symbol, String, nil] defaults to config.default_repo
       # @param state [Symbol] :open, :closed, or :all
       # @param labels [Array<String>]
+      # @param issue_type [String, Symbol, nil] a single GitHub issue type name. Symbols resolve through
+      #   +ISSUE_TYPE_NICKNAMES+ then +config.issue_types+ for org-specific renames.
+      # @param issue_fields [Hash{String,Symbol => Object,Range,nil}, nil] GitHub Issue Field equality / range
+      #   filters. See description for the value shapes the gem accepts.
       # @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+.
@@ -309,19 +327,38 @@ module PlanMyStuff
       #
       # @return [Array<PlanMyStuff::Issue>]
       #
-      def list(repo: nil, state: :open, labels: [], priority_list: nil, page: 1, per_page: 25)
+      def list(
+        repo: nil,
+        state: :open,
+        labels: [],
+        issue_type: nil,
+        issue_fields: nil,
+        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
+        if issue_fields.present? && !PlanMyStuff.configuration.issue_fields_enabled
+          raise(PlanMyStuff::IssueFieldsNotEnabledError)
+        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?
+
+        resolved_type = resolve_issue_types_filter(issue_type)
+        params[:type] = resolved_type if resolved_type.present?
+
+        field_pairs = []
+        field_pairs.concat(build_issue_field_filter_pairs(issue_fields)) if issue_fields.present?
         if priority_list && PlanMyStuff.configuration.issue_fields_enabled
-          params[:issue_field_values] = 'priority-list:Yes'
+          field_pairs << 'priority-list:Yes'
         end
+        params[:issue_field_values] = field_pairs.join(',') if field_pairs.present?
 
         github_issues = client.rest(:list_issues, resolved_repo, **params)
         filtered = github_issues.reject { |gi| gi.respond_to?(:pull_request) && gi.pull_request }
@@ -347,11 +384,18 @@ 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
+      # @raise [ArgumentError] when +priority_list: false+ is passed, or when +issue_type:+ is an Array
+      # @raise [PlanMyStuff::IssueFieldsNotEnabledError] when +issue_fields:+ is passed and
+      #   +config.issue_fields_enabled+ is +false+
       #
       # @param repo [Symbol, String, nil] defaults to config.default_repo
       # @param state [Symbol] :open, :closed, or :all
       # @param labels [Array<String>]
+      # @param issue_type [String, Symbol, nil] a single GitHub issue type name. Symbols resolve through
+      #   +ISSUE_TYPE_NICKNAMES+ then +config.issue_types+.
+      # @param issue_fields [Hash{String,Symbol => Object,Range,nil}, nil] GitHub Issue Field equality / range
+      #   filters. See +.list+ for the value shapes the gem accepts. Each pair is emitted as a
+      #   +field.<slug>:<value>+ Search qualifier and triggers +advanced_search=true+.
       # @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
@@ -359,10 +403,13 @@ module PlanMyStuff
       #
       # @return [Integer]
       #
-      def count(repo: nil, state: :open, labels: [], priority_list: nil)
+      def count(repo: nil, state: :open, labels: [], issue_type: nil, issue_fields: nil, priority_list: nil)
         if priority_list == false
           raise(ArgumentError, 'priority_list: false is not supported (no GitHub negation qualifier)')
         end
+        if issue_fields.present? && !PlanMyStuff.configuration.issue_fields_enabled
+          raise(PlanMyStuff::IssueFieldsNotEnabledError)
+        end
 
         client = PlanMyStuff.client
         resolved_repo = client.resolve_repo!(repo)
@@ -374,11 +421,19 @@ module PlanMyStuff
         qualifiers += labels_to_use.map do |label|
           "label:\"#{label}\""
         end
-        search_options = { per_page: 1 }
+
+        resolved_type = resolve_issue_types_filter(issue_type)
+        qualifiers << "type:#{resolved_type}" if resolved_type.present?
+
+        field_pairs = []
+        field_pairs.concat(build_issue_field_filter_pairs(issue_fields)) if issue_fields.present?
         if priority_list && PlanMyStuff.configuration.issue_fields_enabled
-          qualifiers << 'field.priority-list:Yes'
-          search_options[:advanced_search] = true
+          field_pairs << 'priority-list:Yes'
         end
+        qualifiers += field_pairs.map { |pair| "field.#{pair}" }
+
+        search_options = { per_page: 1 }
+        search_options[:advanced_search] = true if field_pairs.present?
         client.rest(:search_issues, qualifiers.join(' '), **search_options).total_count
       end
 
@@ -528,6 +583,93 @@ module PlanMyStuff
           PlanMyStuff.configuration.issue_types[canonical] || canonical
         end
 
+        # Resolves an +issue_type:+ filter kwarg (used by +.list+ / +.count+) into a single canonical type name.
+        # Accepts a scalar (String / Symbol); +nil+ returns +nil+ so callers can skip the filter entirely. Runs
+        # through +resolve_issue_type!+ so symbol nicknames and +config.issue_types+ overrides apply consistently
+        # with +create!+ / +update!+. Arrays raise +ArgumentError+ -- GitHub's REST +type+ param and Search
+        # +type:+ qualifier each accept a single value at a time.
+        #
+        # @raise [ArgumentError] when +value+ is an Array
+        #
+        # @param value [String, Symbol, nil]
+        #
+        # @return [String, nil]
+        #
+        def resolve_issue_types_filter(value)
+          return if value.nil?
+          if value.is_a?(Array)
+            raise(ArgumentError, 'issue_type: must be a single String / Symbol; GitHub does not accept multiple types')
+          end
+
+          resolve_issue_type!(value)
+        end
+
+        # Slugifies a field name into the kebab-case form GitHub expects in +issue_field_values+ and the Search API's
+        # +field.<slug>:+ qualifier (e.g. +"Priority List"+ / +:priority_list+ -> +"priority-list"+). Lowercases and
+        # collapses runs of whitespace or underscores into a single hyphen.
+        #
+        # @param name [String, Symbol]
+        #
+        # @return [String]
+        #
+        def field_filter_slug(name)
+          name.to_s.downcase.gsub(/[\s_]+/, '-')
+        end
+
+        # Coerces an issue-field filter value to the literal string GitHub expects in the query (Date / Time -> ISO
+        # 8601, Numeric / scalar -> +to_s+). Range bounds are handled separately by
+        # +build_issue_field_filter_pairs+.
+        #
+        # @param value [Object]
+        #
+        # @return [String]
+        #
+        def format_field_filter_value(value)
+          case value
+          when Date, Time then value.iso8601
+          else value.to_s
+          end
+        end
+
+        # Expands an +issue_fields:+ kwarg hash into the flat +Array<String>+ of +slug:value+ pairs that both REST
+        # (+issue_field_values=...+) and Search (+field.slug:value...+) consume.
+        #
+        # Scalars become a single equality pair. +Range+ values expand into one or two comparison pairs:
+        # +>=+/+<=+ for inclusive bounds, +<+ for an exclusive end (+...+). Beginless / endless ranges emit only
+        # the bounded side. +nil+ values are skipped.
+        #
+        # @param hash [Hash{String,Symbol => Object,Range,nil}]
+        #
+        # @return [Array<String>]
+        #
+        def build_issue_field_filter_pairs(hash)
+          hash.flat_map do |name, value|
+            slug = field_filter_slug(name)
+            case value
+            when nil then []
+            when Range then range_field_filter_pairs(slug, value)
+            else ["#{slug}:#{format_field_filter_value(value)}"]
+            end
+          end
+        end
+
+        # Expands a +Range+ value into the +slug:>=begin+ / +slug:<=end+ (or +<end+ for +...+) pair(s) GitHub expects.
+        #
+        # @param slug [String]
+        # @param range [Range]
+        #
+        # @return [Array<String>]
+        #
+        def range_field_filter_pairs(slug, range)
+          pairs = []
+          pairs << "#{slug}:>=#{format_field_filter_value(range.begin)}" if range.begin.present?
+          if range.end.present?
+            end_op = range.exclude_end? ? '<' : '<='
+            pairs << "#{slug}:#{end_op}#{format_field_filter_value(range.end)}"
+          end
+          pairs
+        end
+
         # @raise [PlanMyStuff::APIError] when the GitHub API call fails
         #
         # @return [Hash]

data/lib/plan_my_stuff/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plan_my_stuff
 version: !ruby/object:Gem::Version
-  version: 0.23.1
+  version: 0.24.0
 platform: ruby
 authors:
 - Brands Insurance