plan_my_stuff 0.1.0 → 1.0.0

data/lib/plan_my_stuff/custom_fields.rb

@@ -1,10 +1,30 @@
 # frozen_string_literal: true
 
+require 'active_model'
+
 module PlanMyStuff
   # Dynamic accessor object for app-defined custom fields stored in metadata.
   # Backed by the config.custom_fields schema, provides both hash-style and
   # method-style access to field values.
+  #
+  # Includes ActiveModel::Validations for type checking, required field
+  # enforcement, and unknown field detection.
   class CustomFields
+    TYPE_MAP = {
+      string: [String],
+      integer: [Integer],
+      boolean: [TrueClass, FalseClass],
+      array: [Array],
+      hash: [Hash],
+    }.freeze
+
+    include ActiveModel::Validations
+
+    validate :validate_custom_fields
+
+    # @return [Hash{Symbol => Hash}]
+    attr_reader :schema
+
     # @param schema [Hash{Symbol => Hash}] field definitions from config.custom_fields
     # @param data [Hash] parsed field data from metadata JSON
     #
@@ -40,26 +60,90 @@ module PlanMyStuff
       to_h.to_json(...)
     end
 
+    # @param method_name [Symbol]
+    # @param include_private [Boolean]
+    #
+    # @return [Boolean]
+    #
+    def respond_to_missing?(method_name, include_private = false)
+      key = method_name.to_s.delete_suffix('=').to_sym
+      @schema.key?(key) || @data.key?(key) || super
+    end
+
+    # Dynamic reader/writer access to custom field values. Only resolves field
+    # names that appear in the schema or already have a value in @data; unknown
+    # names fall through to super (raising NoMethodError).
+    #
+    # @param method_name [Symbol]
+    # @param args [Array]
+    #
+    # @return [Object]
+    #
+    def method_missing(method_name, *args)
+      name = method_name.to_s
+
+      if name.end_with?('=')
+        key = name.delete_suffix('=').to_sym
+        if @schema.key?(key) || @data.key?(key)
+          return @data[key] = args.first
+        end
+      elsif @schema.key?(method_name) || @data.key?(method_name)
+        return @data[method_name]
+      end
+
+      super
+    end
+
     private
 
-      def respond_to_missing?(method_name, include_private = false)
-        key = method_name.to_s.delete_suffix('=').to_sym
-        @schema.key?(key) || @data.key?(key) || super
+      # @return [void]
+      def validate_custom_fields
+        validate_unknown_fields
+        validate_required_fields
+        validate_field_types
       end
 
-      def method_missing(method_name, *args)
-        name = method_name.to_s
+      # @return [void]
+      def validate_unknown_fields
+        known_keys = @schema.keys
+        @data.each_key do |key|
+          if known_keys.exclude?(key)
+            errors.add(:base, "#{key} is not a recognized custom field")
+          end
+        end
+      end
 
-        if name.end_with?('=')
-          key = name.delete_suffix('=').to_sym
-          if @schema.key?(key) || @data.key?(key)
-            return @data[key] = args.first
+      # @return [void]
+      def validate_required_fields
+        @schema.each do |field_name, field_config|
+          if field_config[:required] && !@data.key?(field_name)
+            errors.add(:base, "#{field_name} is required")
           end
-        elsif @schema.key?(method_name) || @data.key?(method_name)
-          return @data[method_name]
         end
+      end
+
+      # @return [void]
+      def validate_field_types
+        @schema.each do |field_name, field_config|
+          next unless @data.key?(field_name)
+
+          value = @data[field_name]
+          next if value.nil?
 
-        super
+          expected_type = field_config[:type]
+          ruby_types = TYPE_MAP[expected_type]
+          next if ruby_types.nil?
+          next if ruby_types.any? { |t| value.is_a?(t) }
+
+          expected_name =
+            if expected_type == :boolean
+              'TrueClass/FalseClass'
+            else
+              ruby_types.first.name
+            end
+
+          errors.add(:base, "#{field_name} must be a #{expected_name}, got #{value.class}")
+        end
       end
   end
 end

data/lib/plan_my_stuff/engine.rb

@@ -4,8 +4,20 @@ module PlanMyStuff
   class Engine < ::Rails::Engine
     isolate_namespace PlanMyStuff
 
-    rake_tasks do
-      load(File.expand_path('../tasks/plan_my_stuff.rake', __dir__))
+    # 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')).each { |path| require path }
+      end
     end
   end
 end

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
 
@@ -66,8 +66,19 @@ module PlanMyStuff
     end
   end
 
+  # Raised when a webhook HMAC-SHA256 signature check fails
+  class WebhookSignatureError < PlanMyStuff::Error
+    def initialize(message = 'Invalid webhook signature')
+      super
+    end
+  end
+
+  # Raised when a pipeline operation fails
+  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
 
@@ -84,4 +95,53 @@ module PlanMyStuff
       super(message)
     end
   end
+
+  # 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 < PlanMyStuff::Error
+  end
+
+  # Raised when an operation is attempted on an issue whose conversation
+  # is locked on GitHub (archived or manually locked).
+  class LockedIssueError < PlanMyStuff::Error
+  end
+
+  # Raised when an Issue Fields API call is attempted while
+  # +config.issue_fields_enabled+ is +false+. Consumers whose org has not been
+  # admitted to the Issue Fields public preview flip the flag off; this error
+  # surfaces faster (and with a clearer message) than the underlying
+  # +GraphQLError+ that GitHub would otherwise return.
+  class IssueFieldsNotEnabledError < PlanMyStuff::Error
+    def initialize(message = nil)
+      super(message || 'Issue Fields are disabled; set config.issue_fields_enabled = true to enable')
+    end
+  end
+
+  # Raised by +PlanMyStuff::Pipeline+ forward transitions when the linked
+  # +Issue+ has any pending manager approvals.
+  class PendingApprovalsError < PlanMyStuff::ValidationError
+    # @return [PlanMyStuff::Issue, nil]
+    attr_reader :issue
+
+    # @return [Integer]
+    attr_reader :pending_count
+
+    # @param message [String, nil]
+    # @param issue [PlanMyStuff::Issue, nil]
+    # @param pending_count [Integer]
+    #
+    def initialize(message = nil, issue: nil, pending_count: 0)
+      @issue = issue
+      @pending_count = pending_count
+      super(message || default_message)
+    end
+
+    private
+
+      # @return [String]
+      def default_message
+        "Issue ##{issue&.number} has #{pending_count} pending approval(s); " \
+          'cannot move forward through pipeline.'
+      end
+  end
 end