plan_my_stuff 0.6.0 → 0.8.0

data/lib/plan_my_stuff/configuration.rb

@@ -2,9 +2,8 @@
 
 module PlanMyStuff
   class Configuration
-    # Default controller for each controllable route group. Consuming apps
-    # override by assigning values into +controllers+; lookups go through
-    # +controller_for+ which falls back to this table.
+    # Default controller for each controllable route group. Consuming apps override by assigning values into
+    # +controllers+; lookups go through +controller_for+ which falls back to this table.
     #
     # @return [Hash{Symbol => String}]
     #
@@ -32,6 +31,13 @@ module PlanMyStuff
     # @return [String] GitHub PAT with repo and project scopes. Required.
     attr_accessor :access_token
 
+    # Classic GitHub PAT used for the Issues Import API (golden-comet-preview). Requires the +repo+ scope (admin-level
+    # repository access). Fine-grained tokens are not supported by that endpoint.
+    #
+    # @return [String, nil]
+    #
+    attr_accessor :import_access_token
+
     # @return [String] GitHub organization name. Required.
     attr_accessor :organization
 
@@ -41,10 +47,9 @@ module PlanMyStuff
     # @return [Integer, nil] default GitHub Projects V2 number for add_to_project calls
     attr_accessor :default_project_number
 
-    # @return [Integer, nil] GitHub Projects V2 number of the template project to clone
-    # when creating new TestingProjects. When set, TestingProject.create! copies the
-    # template (preserving its fields and board layout) instead of bootstrapping fields
-    # from scratch. Leave nil to use the default bootstrap-fields path.
+    # @return [Integer, nil] GitHub Projects V2 number of the template project to clone when creating new
+    # TestingProjects. When set, TestingProject.create! copies the template (preserving its fields and board layout)
+    # instead of bootstrapping fields from scratch. Leave nil to use the default bootstrap-fields path.
     attr_accessor :testing_template_project_number
 
     # @return [String] consuming app's user model class name, constantized for lookups
@@ -56,8 +61,8 @@ module PlanMyStuff
     # @return [Symbol] method called on user object to extract the app-side user ID
     attr_accessor :user_id_method
 
-    # Determines if a user is support staff. Symbol (method name on user) or Proc that
-    # receives the user object and returns boolean.
+    # Determines if a user is support staff. Symbol (method name on user) or Proc that receives the user object and
+    # returns boolean.
     #
     # @return [Symbol, Proc]
     #
@@ -66,8 +71,7 @@ module PlanMyStuff
     # @return [Symbol] which markdown gem to use: :commonmarker or :redcarpet
     attr_accessor :markdown_renderer
 
-    # Default options passed to the markdown renderer. Per-call options in
-    # Markdown.render merge on top of these.
+    # Default options passed to the markdown renderer. Per-call options in Markdown.render merge on top of these.
     #
     # For :commonmarker - passed as `options:` to `Commonmarker.to_html`
     #   e.g. `{ render: { hardbreaks: true } }`
@@ -80,22 +84,21 @@ module PlanMyStuff
     #
     attr_accessor :markdown_options
 
-    # Proc returning boolean, or nil (always send). When it returns false the request is
-    # deferred to a background job instead of hitting GitHub.
+    # Proc returning boolean, or nil (always send). When it returns false the request is deferred to a background job
+    # instead of hitting GitHub.
     #
     # @return [Proc, nil]
     #
     attr_accessor :should_send_request
 
-    # Map of action type to job class name for deferred requests.
-    # Keys: :create_ticket, :post_comment, :update_status.
+    # Map of action type to job class name for deferred requests. Keys: :create_ticket, :post_comment, :update_status.
     #
     # @return [Hash{Symbol => String}]
     #
     attr_accessor :job_classes
 
-    # Fallback actor for notification events when a caller does not pass +user:+.
-    # Set to a proc/lambda that returns the current request user.
+    # Fallback actor for notification events when a caller does not pass +user:+. Set to a proc/lambda that returns the
+    # current request user.
     #
     # Example: +config.current_user = -> { Current.user }+
     #
@@ -103,42 +106,65 @@ module PlanMyStuff
     #
     attr_accessor :current_user
 
-    # Shared field definitions stored in issue/comment metadata.
-    # Keys are field names, values are hashes with :type and :required.
-    # These fields apply to both issues and comments.
+    # Callback invoked from gem controller +rescue+ blocks just after the error is logged and just before the
+    # user-facing redirect/render. Lets consuming apps forward swallowed errors to their monitoring service. Receives
+    # the rescued exception.
+    #
+    # Example:
+    #   config.controller_rescue = ->(error) { MonitoringService.notice_error(error) }
+    #
+    # @return [Proc, nil]
+    #
+    attr_accessor :controller_rescue
+
+    # Shared field definitions stored in issue/comment metadata. Keys are field names, values are hashes with :type and
+    # :required. These fields apply to both issues and comments.
     #
     # @return [Hash{Symbol => Hash}]
     #
     attr_accessor :custom_fields
 
-    # Issue-only field definitions, deep-merged on top of shared custom_fields.
-    # Context-specific config wins on key conflicts.
+    # Issue-only field definitions, deep-merged on top of shared custom_fields. Context-specific config wins on key
+    # conflicts.
     #
     # @return [Hash{Symbol => Hash}]
     #
     attr_accessor :issue_custom_fields
 
-    # Comment-only field definitions, deep-merged on top of shared custom_fields.
-    # Context-specific config wins on key conflicts.
+    # Comment-only field definitions, deep-merged on top of shared custom_fields. Context-specific config wins on key
+    # conflicts.
     #
     # @return [Hash{Symbol => Hash}]
     #
     attr_accessor :comment_custom_fields
 
-    # Project-only field definitions, deep-merged on top of shared custom_fields.
-    # Context-specific config wins on key conflicts.
+    # Project-only field definitions, deep-merged on top of shared custom_fields. Context-specific config wins on key
+    # conflicts.
     #
     # @return [Hash{Symbol => Hash}]
     #
     attr_accessor :project_custom_fields
 
-    # Testing-project-only field definitions, deep-merged on top of shared custom_fields.
-    # Context-specific config wins on key conflicts.
+    # Testing-project-only field definitions, deep-merged on top of shared custom_fields. Context-specific config wins
+    # on key conflicts.
     #
     # @return [Hash{Symbol => Hash}]
     #
     attr_accessor :testing_custom_fields
 
+    # Canonical-name to org-side display-name map for GitHub native issue types. Lets the consuming app rename the
+    # seven canonical types the gem knows about (+"Bug"+, +"Feature"+, +"IT Issue / Hardware"+, +"Other"+,
+    # +"Performance"+, +"Question"+, +"Task"+) to whatever their org actually uses. Both Symbol shortcuts (resolved via
+    # the gem's nickname map) and String inputs to +Issue.create!+ / +Issue.update!+ are passed through this map;
+    # missing keys fall through unchanged.
+    #
+    # Example: +config.issue_types = { 'Bug' => 'User Bug', 'Feature' => 'Enhancement' }+ then +issue_type: :feature+
+    # or +issue_type: 'Feature'+ both write +'Enhancement'+ to GitHub.
+    #
+    # @return [Hash{String => String}]
+    #
+    attr_accessor :issue_types
+
     # @return [String, nil] URL prefix for building user-facing ticket URLs in the consuming app
     attr_accessor :issues_url_prefix
 
@@ -163,23 +189,21 @@ module PlanMyStuff
     # @return [String, nil] commit hash of the deploying build, prefix-matched against issue metadata commit_sha
     attr_accessor :production_commit_sha
 
-    # Canonical status name to display alias map. Allows consuming apps to rename
-    # pipeline statuses (e.g. "Started" to "In Progress").
+    # Canonical status name to display alias map. Allows consuming apps to rename pipeline statuses (e.g. "Started" to
+    # "In Progress").
     #
     # @return [Hash{String => String}]
     #
     attr_accessor :pipeline_statuses
 
-    # Display name for the +Testing+ single-select custom field on the
-    # pipeline project. Defaults to +"Testing"+.
+    # Display name for the +Testing+ single-select custom field on the pipeline project. Defaults to +"Testing"+.
     #
     # @return [String]
     #
     attr_accessor :pipeline_testing_field_name
 
-    # Map of canonical testing field option keys (+:active+, +:inactive+)
-    # to display labels. Allows consuming apps to rename the option labels
-    # without changing the canonical identifiers.
+    # Map of canonical testing field option keys (+:active+, +:inactive+) to display labels. Allows consuming apps to
+    # rename the option labels without changing the canonical identifiers.
     #
     # @return [Hash{Symbol => String}]
     #
@@ -191,10 +215,8 @@ module PlanMyStuff
     # @return [String] branch name that triggers deployment when a PR merges
     attr_accessor :production_branch
 
-    # Hash mapping consuming-app user id to GitHub login. Used by the
-    # "Take" UI flow to assign the GitHub user when a support user claims
-    # an issue. Keys are whatever +config.user_id_method+ returns on the
-    # current user.
+    # Hash mapping consuming-app user id to GitHub login. Used by the "Take" UI flow to assign the GitHub user when a
+    # support user claims an issue. Keys are whatever +config.user_id_method+ returns on the current user.
     #
     # Example: +config.github_login_for = { 1 => 'some_username', 2 => 'octocat' }+
     #
@@ -202,48 +224,44 @@ module PlanMyStuff
     #
     attr_accessor :github_login_for
 
-    # Per-group route mounting toggles. Keys: :webhooks, :issues, :projects.
-    # Set a key to false to skip mounting that route group.
+    # Per-group route mounting toggles. Keys: :webhooks, :issues, :projects. Set a key to false to skip mounting that
+    # route group.
     #
     # @return [Hash{Symbol => Boolean}]
     #
     attr_accessor :mount_groups
 
-    # Per-route controller overrides. Keys are the controllable route symbols
-    # defined in +DEFAULT_CONTROLLERS+; values are fully-qualified controller
-    # paths (e.g. +'my_app/issues'+). Unset keys fall back to the gem default.
-    # Consuming apps typically subclass the gem controller to add before_actions
-    # or tweak responses, then swap their subclass in here.
+    # Per-route controller overrides. Keys are the controllable route symbols defined in +DEFAULT_CONTROLLERS+; values
+    # are fully-qualified controller paths (e.g. +'my_app/issues'+). Unset keys fall back to the gem default. Consuming
+    # apps typically subclass the gem controller to add before_actions or tweak responses, then swap their subclass in
+    # here.
     #
     # @return [Hash{Symbol => String}]
     #
     attr_accessor :controllers
 
-    # Whether to use Rails.cache for ETag-based HTTP caching of GitHub reads.
-    # Defaults to true; set to false to bypass the cache entirely.
+    # Whether to use Rails.cache for ETag-based HTTP caching of GitHub reads. Defaults to true; set to false to bypass
+    # the cache entirely.
     #
     # @return [Boolean]
     #
     attr_accessor :cache_enabled
 
-    # Opaque app-supplied version string embedded in every PMS cache key.
-    # Bumping this string invalidates all cached entries from the consuming
-    # app's side (e.g. after a deploy or schema change). Defaults to nil.
+    # Opaque app-supplied version string embedded in every PMS cache key. Bumping this string invalidates all cached
+    # entries from the consuming app's side (e.g. after a deploy or schema change). Defaults to nil.
     #
     # @return [String, nil]
     #
     attr_accessor :cache_version
 
-    # Whether the reminders sweep performs any work. Defaults to +true+.
-    # Set to +false+ in apps that don't want follow-up reminders or inactivity
-    # auto-close.
+    # Whether the reminders sweep performs any work. Defaults to +true+. Set to +false+ in apps that don't want
+    # follow-up reminders or inactivity auto-close.
     #
     # @return [Boolean]
     #
     attr_accessor :reminders_enabled
 
-    # Days-since-waiting at which reminder events fire. Per-issue override
-    # via +metadata.reminder_days+.
+    # Days-since-waiting at which reminder events fire. Per-issue override via +metadata.reminder_days+.
     #
     # @return [Array<Integer>]
     #
@@ -267,45 +285,42 @@ module PlanMyStuff
     #
     attr_accessor :waiting_on_approval_label
 
-    # Label name applied to issues auto-closed by the inactivity sweep.
-    # Removed when an issue is auto-reopened via a user reply.
+    # Label name applied to issues auto-closed by the inactivity sweep. Removed when an issue is auto-reopened via a
+    # user reply.
     #
     # @return [String]
     #
     attr_accessor :user_inactive_label
 
-    # Whether the archive sweep performs any work. Defaults to +true+.
-    # Set to +false+ in apps that don't want auto-archiving of aged-closed
-    # issues.
+    # Whether the archive sweep performs any work. Defaults to +true+. Set to +false+ in apps that don't want
+    # auto-archiving of aged-closed issues.
     #
     # @return [Boolean]
     #
     attr_accessor :archiving_enabled
 
-    # Days after +closed_at+ at which a non-inactive-closed issue becomes an
-    # archive candidate.
+    # Days after +closed_at+ at which a non-inactive-closed issue becomes an archive candidate.
     #
     # @return [Integer]
     #
     attr_accessor :archive_closed_after_days
 
-    # Label name added to archived issues. Also used by the sweep as a
-    # skip marker to avoid re-archiving the same issue.
+    # Label name added to archived issues. Also used by the sweep as a skip marker to avoid re-archiving the same
+    # issue.
     #
     # @return [String]
     #
     attr_accessor :archived_label
 
-    # Whether the pipeline sweep removes aged-out +Completed+ items.
-    # Defaults to +true+. Set to +false+ to keep items in +Completed+
-    # indefinitely.
+    # Whether the pipeline sweep removes aged-out +Completed+ items. Defaults to +true+. Set to +false+ to keep items
+    # in +Completed+ indefinitely.
     #
     # @return [Boolean]
     #
     attr_accessor :pipeline_completion_purge_enabled
 
-    # Hours after a project item's last update at which the sweep removes
-    # it from the pipeline if its status is +Completed+. Defaults to +24+.
+    # Hours after a project item's last update at which the sweep removes it from the pipeline if its status is
+    # +Completed+. Defaults to +24+.
     #
     # @return [Integer]
     #
@@ -317,8 +332,7 @@ module PlanMyStuff
     #
     attr_accessor :process_aws_webhooks
 
-    # Class instantiated per request for SNS signature verification.
-    # Must respond to +authenticate!(raw_body)+.
+    # Class instantiated per request for SNS signature verification. Must respond to +authenticate!(raw_body)+.
     #
     # @return [Class]
     #
@@ -351,6 +365,7 @@ module PlanMyStuff
       @comment_custom_fields = {}
       @project_custom_fields = {}
       @testing_custom_fields = {}
+      @issue_types = {}
       @pipeline_enabled = true
       @pipeline_statuses = {}
       @pipeline_testing_field_name = PlanMyStuff::Pipeline::Testing::FIELD_NAME
@@ -406,13 +421,13 @@ module PlanMyStuff
       return if missing.empty?
 
       raise(
-        ConfigurationError,
+        PlanMyStuff::ConfigurationError,
         "Missing required PlanMyStuff configuration: #{missing.join(', ')}",
       )
     end
 
-    # Returns the merged custom fields schema for the given context.
-    # Context-specific fields deep-merge on top of shared fields.
+    # Returns the merged custom fields schema for the given context. Context-specific fields deep-merge on top of
+    # shared fields.
     #
     # @param context [Symbol] :issue or :comment
     #
@@ -431,16 +446,14 @@ module PlanMyStuff
       custom_fields.deep_merge(context_fields)
     end
 
-    # Returns the controller path for the given route group, preferring a
-    # consuming-app override from +controllers+ and falling back to the gem
-    # default from +DEFAULT_CONTROLLERS+. The returned value always begins
-    # with +'/'+ so the isolated engine does not re-prefix it with
-    # +plan_my_stuff/+.
-    #
-    # @param key [Symbol]
+    # Returns the controller path for the given route group, preferring a consuming-app override from +controllers+
+    # and falling back to the gem default from +DEFAULT_CONTROLLERS+. The returned value always begins with +'/'+ so
+    # the isolated engine does not re-prefix it with +plan_my_stuff/+.
     #
     # @raise [KeyError] if +key+ is not a controllable route group
     #
+    # @param key [Symbol]
+    #
     # @return [String]
     #
     def controller_for(key)

data/lib/plan_my_stuff/errors.rb

@@ -6,7 +6,7 @@ module PlanMyStuff
   end
 
   # Raised when GitHub REST API returns a non-success HTTP status
-  class APIError < Error
+  class APIError < PlanMyStuff::Error
     # @return [Integer]
     attr_reader :status
 
@@ -20,7 +20,7 @@ module PlanMyStuff
   end
 
   # Raised when GitHub GraphQL API returns errors in the response body
-  class GraphQLError < Error
+  class GraphQLError < PlanMyStuff::Error
     # @return [Array<Hash>]
     attr_reader :errors
 
@@ -34,7 +34,7 @@ module PlanMyStuff
   end
 
   # Raised when GitHub rate limit is exhausted (429 or rate limit headers)
-  class RateLimitError < Error
+  class RateLimitError < PlanMyStuff::Error
     # @return [Time]
     attr_reader :retry_after
 
@@ -48,7 +48,7 @@ module PlanMyStuff
   end
 
   # Raised when an object has been modified remotely since it was loaded
-  class StaleObjectError < Error
+  class StaleObjectError < PlanMyStuff::Error
     # @return [Time, nil]
     attr_reader :local_updated_at
 
@@ -67,18 +67,18 @@ module PlanMyStuff
   end
 
   # Raised when a webhook HMAC-SHA256 signature check fails
-  class WebhookSignatureError < Error
+  class WebhookSignatureError < PlanMyStuff::Error
     def initialize(message = 'Invalid webhook signature')
       super
     end
   end
 
   # Raised when a pipeline operation fails
-  class PipelineError < Error
+  class PipelineError < PlanMyStuff::Error
   end
 
   # Raised when custom field validation fails (Phase 1)
-  class ValidationError < Error
+  class ValidationError < PlanMyStuff::Error
     # @return [String, nil]
     attr_reader :field
 
@@ -98,17 +98,17 @@ module PlanMyStuff
 
   # Raised when a caller is not authorized to perform an action (e.g.
   # a non-support user attempts to manage approvers on an issue).
-  class AuthorizationError < Error
+  class AuthorizationError < PlanMyStuff::Error
   end
 
   # Raised when an operation is attempted on an issue whose conversation
   # is locked on GitHub (archived or manually locked).
-  class LockedIssueError < Error
+  class LockedIssueError < PlanMyStuff::Error
   end
 
   # Raised by +PlanMyStuff::Pipeline+ forward transitions when the linked
   # +Issue+ has any pending manager approvals.
-  class PendingApprovalsError < ValidationError
+  class PendingApprovalsError < PlanMyStuff::ValidationError
     # @return [PlanMyStuff::Issue, nil]
     attr_reader :issue
 

data/lib/plan_my_stuff/graphql/queries.rb

@@ -9,7 +9,7 @@ module PlanMyStuff
     # Callers pass the constant straight to +PlanMyStuff.client.graphql+:
     #
     #   PlanMyStuff.client.graphql(
-    #     PMS::GraphQL::Queries::DELETE_PROJECT_ITEM,
+    #     PlanMyStuff::GraphQL::Queries::DELETE_PROJECT_ITEM,
     #     variables: { projectId: ..., itemId: ... },
     #   )
     #