plan_my_stuff 0.1.0 → 1.0.0

data/lib/plan_my_stuff/configuration.rb

@@ -2,9 +2,43 @@
 
 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.
+    #
+    # @return [Hash{Symbol => String}]
+    #
+    DEFAULT_CONTROLLERS = {
+      'issues': 'plan_my_stuff/issues',
+      'comments': 'plan_my_stuff/comments',
+      'labels': 'plan_my_stuff/labels',
+      'projects': 'plan_my_stuff/projects',
+      'project_items': 'plan_my_stuff/project_items',
+      'testing_projects': 'plan_my_stuff/testing_projects',
+      'testing_project_items': 'plan_my_stuff/testing_project_items',
+      'issues/closures': 'plan_my_stuff/issues/closures',
+      'issues/viewers': 'plan_my_stuff/issues/viewers',
+      'issues/takes': 'plan_my_stuff/issues/takes',
+      'issues/testings': 'plan_my_stuff/issues/testings',
+      'issues/waitings': 'plan_my_stuff/issues/waitings',
+      'issues/links': 'plan_my_stuff/issues/links',
+      'issues/approvals': 'plan_my_stuff/issues/approvals',
+      'project_items/statuses': 'plan_my_stuff/project_items/statuses',
+      'project_items/assignments': 'plan_my_stuff/project_items/assignments',
+      'testing_project_items/results': 'plan_my_stuff/testing_project_items/results',
+      'webhooks/github': 'plan_my_stuff/webhooks/github',
+      'webhooks/aws': 'plan_my_stuff/webhooks/aws',
+    }.freeze
+
     # @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
 
@@ -14,6 +48,11 @@ 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.
+    attr_accessor :testing_template_project_number
+
     # @return [String] consuming app's user model class name, constantized for lookups
     attr_accessor :user_class
 
@@ -23,8 +62,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]
     #
@@ -33,8 +72,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 } }`
@@ -47,35 +85,73 @@ 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.
+    # 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 }+
     #
     # @return [Proc, nil]
     #
-    attr_accessor :should_send_request
+    attr_accessor :current_user
 
-    # Map of action type to job class name for deferred requests.
-    # Keys: :create_ticket, :post_comment, :update_status.
+    # 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.
     #
-    # @return [Hash{Symbol => String}]
+    # Example:
+    #   config.controller_rescue = ->(error) { MonitoringService.notice_error(error) }
     #
-    attr_accessor :job_classes
+    # @return [Proc, nil]
+    #
+    attr_accessor :controller_rescue
 
-    # @return [Proc, nil] custom notifier for deferred requests, or nil to use DeferredMailer
-    attr_accessor :deferred_notifier
+    # 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
 
-    # @return [String, nil] sender address for built-in deferred request notifications
-    attr_accessor :deferred_email_from
+    # 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
 
-    # @return [String, nil] recipient address for built-in deferred request notifications
-    attr_accessor :deferred_email_to
+    # 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
 
-    # App-defined field definitions stored in issue/comment metadata.
-    # Keys are field names, values are hashes with :type and :required.
+    # 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 :custom_fields
+    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.
+    #
+    # @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
@@ -83,23 +159,296 @@ module PlanMyStuff
     # @return [String, nil] name of the consuming app, stored in metadata (e.g. "Atlas")
     attr_accessor :app_name
 
-    # Named repo configs. Set via config.repos[:element] = 'BrandsInsurance/Element'.
+    # @return [Boolean] whether the release pipeline feature is enabled
+    attr_accessor :pipeline_enabled
+
+    # @return [Integer, nil] GitHub Projects V2 number for the pipeline board (falls back to default_project_number)
+    attr_accessor :pipeline_project_number
+
+    # @return [String, nil] HMAC secret for GitHub webhook signature verification (required when webhooks mounted)
+    attr_accessor :webhook_secret
+
+    # @return [String, nil] expected SNS topic ARN for AWS webhook validation
+    attr_accessor :sns_topic_arn
+
+    # @return [String, nil] suffix matched against ECS event resource ARNs (e.g. 'rawr-production-2-web')
+    attr_accessor :aws_service_identifier
+
+    # @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").
+    #
+    # @return [Hash{String => String}]
+    #
+    attr_accessor :pipeline_statuses
+
+    # 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.
     #
     # @return [Hash{Symbol => String}]
     #
-    attr_reader :repos
+    attr_accessor :pipeline_testing_values
+
+    # Canonical Issue Field name to consumer field name map. Lets a consuming org rename the native issue fields the
+    # gem refers to internally (e.g. +"Issue Status"+ -> +"Status"+) without touching gem code. Applied via
+    # +PlanMyStuff::IssueFieldTranslation+ on reads, writes, and filters; unmapped names pass through unchanged.
+    #
+    # @return [Hash{String => String}]
+    #
+    attr_accessor :issue_field_names
+
+    # Canonical Issue Field value translations, nested by canonical field name:
+    # +{ 'Issue Status' => { 'Waiting on Reply' => 'Awaiting Customer', ... } }+. Lets a consuming org rename
+    # single-select option labels without touching gem code. Applied via +PlanMyStuff::IssueFieldTranslation+;
+    # unmapped fields / values pass through unchanged.
+    #
+    # @return [Hash{String => Hash{String => String}}]
+    #
+    attr_accessor :issue_field_values
+
+    # @return [String] branch name that PRs merge into for "Ready for release" transition
+    attr_accessor :main_branch
+
+    # @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.
+    #
+    # Example: +config.github_login_for = { 1 => 'some_username', 2 => 'octocat' }+
+    #
+    # @return [Hash{Object => String}]
+    #
+    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.
+    #
+    # @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.
+    #
+    # @return [Hash{Symbol => String}]
+    #
+    attr_accessor :controllers
+
+    # Parent class string for +PlanMyStuff::ApplicationController+. Defaults to +'::ApplicationController'+. Override
+    # when the consuming app does not use the +ApplicationController+ name (e.g. +'ActionController::Base'+,
+    # +'RawrApplicationController'+). Must be set before the gem's controllers load - the standard
+    # +config/initializers/plan_my_stuff.rb+ location is correct, since Rails resolves the superclass once at class
+    # definition time.
+    #
+    # @return [String]
+    #
+    attr_accessor :parent_controller
+
+    # 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.
+    #
+    # @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.
+    #
+    # @return [Boolean]
+    #
+    attr_accessor :reminders_enabled
+
+    # Days-since-waiting at which reminder events fire. Per-issue override via +metadata.reminder_days+.
+    #
+    # @return [Array<Integer>]
+    #
+    attr_accessor :reminder_days
+
+    # Days of inactivity after which the sweep auto-closes a waiting issue.
+    #
+    # @return [Integer]
+    #
+    attr_accessor :inactivity_close_days
+
+    # Label name used to flag issues waiting on an end-user reply.
+    #
+    # @return [String]
+    #
+    attr_accessor :waiting_on_user_label
+
+    # Label name used to flag issues waiting on pending approvals.
+    #
+    # @return [String]
+    #
+    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.
+    #
+    # @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.
+    #
+    # @return [Boolean]
+    #
+    attr_accessor :archiving_enabled
+
+    # 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.
+    #
+    # @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.
+    #
+    # @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+.
+    #
+    # @return [Integer]
+    #
+    attr_accessor :pipeline_completion_ttl_hours
+
+    # Whether to process incoming AWS webhook events. Defaults to +Rails.env.production?+.
+    #
+    # @return [Boolean]
+    #
+    attr_accessor :process_aws_webhooks
+
+    # Class instantiated per request for SNS signature verification. Must respond to +authenticate!(raw_body)+.
+    #
+    # @return [Class]
+    #
+    attr_accessor :sns_verifier_class
+
+    # Exception class rescued during SNS signature verification.
+    #
+    # @return [Class]
+    #
+    attr_accessor :sns_verifier_error
+
+    # Named repo configs. Set via config.repos[:element] = 'BrandsInsurance/Element', or assign a whole hash with
+    # config.repos = { element: 'BrandsInsurance/Element', underwriter: 'BrandsInsurance/Underwriter' }.
+    #
+    # @return [Hash{Symbol => String}]
+    #
+    attr_accessor :repos
+
+    # Human-readable repo names used as the +to_param+ prefix on +PlanMyStuff::Issue+ instances. Symbol-keyed
+    # against +repos+ -- missing keys fall back to +key.to_s.titleize+, so only entries that diverge from a simple
+    # +titleize+ of the key (e.g. +:safety+ -> +"Compliance"+) need to be listed.
+    #
+    # @return [Hash{Symbol => String}]
+    #
+    attr_accessor :repo_nicknames
+
+    # Bare repo name (under +config.organization+) that stores uploaded attachment binaries. Defaults to
+    # +'pms-attachments'+. The repo must exist; the uploader does not create it. Attachments commit onto
+    # +config.main_branch+ and live under +<repo_key_or_name>/issue-<number>/<uuid>.<ext>+.
+    #
+    # @return [String]
+    #
+    attr_accessor :attachment_repo
+
+    # Whether GitHub's Issue Fields (public preview) are wired up for the configured org. Defaults to +true+ (opt-out):
+    # when +false+, +Issue#issue_fields+ returns an empty +IssueFieldValueSet+ without making a request and
+    # +Issue#set_issue_fields!+ / +IssueField.list+ raise +IssueFieldsNotEnabledError+. Set to +false+ if your org has
+    # not been admitted to the Issue Fields preview, to avoid raw GraphQL errors from GitHub.
+    #
+    # @return [Boolean]
+    #
+    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 = {}
+      @repo_nicknames = {}
+      @attachment_repo = 'pms-attachments'
       @user_class = 'User'
       @display_name_method = :to_s
       @user_id_method = :id
       @support_method = :support?
       @markdown_renderer = :commonmarker
       @markdown_options = {}
-      @job_classes = {}
       @custom_fields = {}
+      @issue_custom_fields = {}
+      @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
+      @pipeline_testing_values = PlanMyStuff::Pipeline::Testing::VALUES.dup
+      @issue_field_names = {}
+      @issue_field_values = {}
+      @main_branch = 'main'
+      @production_branch = 'production'
+      @mount_groups = { webhooks: true, issues: true, projects: true }
+      @controllers = {}
+      @parent_controller = '::ApplicationController'
+      @cache_enabled = true
+      @github_login_for = {}
+      @reminders_enabled = true
+      @reminder_days = [1, 3, 7, 10, 14, 18].freeze
+      @inactivity_close_days = 30
+      @waiting_on_user_label = 'waiting-on-user'
+      @waiting_on_approval_label = 'waiting-on-approval'
+      @user_inactive_label = 'user-inactive'
+      @archiving_enabled = true
+      @archive_closed_after_days = 90
+      @archived_label = 'archived'
+      @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 =
+        if defined?(::Aws::SNS::MessageVerifier::VerificationError)
+          ::Aws::SNS::MessageVerifier::VerificationError
+        end
     end
 
     # Sets the authentication block for engine controllers.
@@ -125,13 +474,95 @@ module PlanMyStuff
       missing << 'access_token' if access_token.nil? || access_token.to_s.strip.empty?
       missing << 'organization' if organization.nil? || organization.to_s.strip.empty?
 
-      return if missing.empty?
+      if missing.present?
+        raise(
+          PlanMyStuff::ConfigurationError,
+          "Missing required PlanMyStuff configuration: #{missing.join(', ')}",
+        )
+      end
+
+      validate_repo_nicknames!
+    end
+
+    # 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
+    #
+    # @return [Hash{Symbol => Hash}]
+    #
+    def custom_fields_for(context)
+      context_fields =
+        case context
+        when :issue then issue_custom_fields
+        when :comment then comment_custom_fields
+        when :project then project_custom_fields
+        when :testing then testing_custom_fields
+        else {}
+        end
+
+      custom_fields.deep_merge(context_fields)
+    end
 
-      raise(
-        ConfigurationError,
-        "Missing required PlanMyStuff configuration: #{missing.join(', ')}",
-      )
+    # 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)
+      path = controllers[key] || DEFAULT_CONTROLLERS.fetch(key)
+      path.start_with?('/') ? path : "/#{path}"
     end
+
+    # Human-readable nickname for a repo key, used as the +to_param+ prefix on +PlanMyStuff::Issue+ instances. Falls
+    # back to +key.to_s.titleize+ when no explicit entry exists in +repo_nicknames+.
+    #
+    # @param key [Symbol, String]
+    #
+    # @return [String]
+    #
+    def repo_nickname_for(key)
+      repo_nicknames[key&.to_sym] || key.to_s.titleize
+    end
+
+    private
+
+      # Resolved nicknames feed directly into +Issue#to_param+ and route +:id+ tokens, so collisions or chars outside
+      # +[A-Za-z0-9_]+ (notably +-+, the nickname/number separator) break URL round-tripping.
+      #
+      # @raise [ConfigurationError] when any resolved nickname collides with another or contains non-token chars
+      #
+      # @return [void]
+      #
+      def validate_repo_nicknames!
+        resolved = repos.keys.index_with { |key| repo_nickname_for(key).to_s }
+
+        invalid = resolved.reject { |_key, nickname| nickname.match?(/\A[A-Za-z0-9_]+\z/) }
+        if invalid.present?
+          pairs = invalid.map { |key, nickname| "#{key.inspect} => #{nickname.inspect}" }
+          raise(
+            PlanMyStuff::ConfigurationError,
+            "Invalid repo nickname(s) (must match /\\A[A-Za-z0-9_]+\\z/): #{pairs.join(', ')}",
+          )
+        end
+
+        dupes = resolved.group_by { |_key, nickname| nickname }.select { |_n, entries| entries.size > 1 }
+        return if dupes.blank?
+
+        details = dupes.map do |nickname, entries|
+          keys = entries.map { |entry| entry.first.inspect }.join(', ')
+          "#{nickname.inspect} (#{keys})"
+        end
+        raise(
+          PlanMyStuff::ConfigurationError,
+          "Duplicate repo nickname(s): #{details.join('; ')}",
+        )
+      end
   end
 
   class ConfigurationError < StandardError