plan_my_stuff 0.2.0 → 0.4.0

data/lib/plan_my_stuff/testing_project.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # A GitHub Projects V2 project used to track manual verification of features.
+  # Identified by kind: "testing" in its readme metadata. Sibling of Project -
+  # both inherit shared machinery from BaseProject.
+  #
+  # BaseProject.find / BaseProject.list dispatch to TestingProject automatically
+  # when the metadata kind matches; TestingProject.find raises APIError if the
+  # requested project is not a testing project. TestingProject.create!
+  # bootstraps testing-specific custom fields after creating the underlying
+  # GH project.
+  class TestingProject < PlanMyStuff::BaseProject
+    # Default GH Project custom field definitions bootstrapped on creation.
+    # Fields already present on the project are skipped.
+    #
+    # "Test Status" is intentionally a separate field from GitHub's built-in
+    # "Status" (which BaseProject and Pipeline hardcode). Using a parallel
+    # field lets the QA sign-off flow own its own options (Passed/Failed)
+    # without colliding with the board's default Status column — a testing
+    # project pointed at a pipeline-tracked repo won't overwrite either.
+    BOOTSTRAP_FIELDS = [
+      { name: 'Test Status', data_type: 'SINGLE_SELECT', options: ['Todo', 'In Progress', 'Passed', 'Failed'] },
+      { name: 'Testers', data_type: 'TEXT' },
+      { name: 'Watchers', data_type: 'TEXT' },
+      { name: 'Pass Mode', data_type: 'SINGLE_SELECT', options: %w[all any] },
+      { name: 'Due Date', data_type: 'DATE' },
+      { name: 'Deadline Miss Reason', data_type: 'TEXT' },
+      { name: 'Result Notes', data_type: 'TEXT' },
+      { name: 'Passed By', data_type: 'TEXT' },
+      { name: 'Failed By', data_type: 'TEXT' },
+      { name: 'Passed At', data_type: 'TEXT' },
+    ].freeze
+
+    # Override metadata default so unhydrated TestingProject instances carry
+    # the correct metadata subclass.
+    attribute :metadata, default: -> { PlanMyStuff::TestingProjectMetadata.new }
+
+    class << self
+      # Creates a new testing project in the configured organization.
+      # Writes TestingProjectMetadata to the project readme and bootstraps
+      # any missing custom fields defined in BOOTSTRAP_FIELDS.
+      #
+      # @param title [String]
+      # @param user [Object, Integer, nil]
+      # @param visibility [String] "public" or "internal"
+      # @param custom_fields [Hash] app-defined metadata field values
+      # @param readme [String] user-visible readme content
+      # @param description [String, nil] project short description
+      # @param subject_urls [Array<String>] PR/issue URLs covered
+      # @param due_date [Date, nil] project-level deadline
+      # @param deadline_miss_reason [String, nil]
+      #
+      # @return [PlanMyStuff::TestingProject]
+      #
+      def create!(
+        title:,
+        user: nil,
+        visibility: 'internal',
+        custom_fields: {},
+        readme: '',
+        description: nil,
+        subject_urls: [],
+        due_date: nil,
+        deadline_miss_reason: nil
+      )
+        org = PlanMyStuff.configuration.organization
+
+        project_metadata = PlanMyStuff::TestingProjectMetadata.build(
+          user: user,
+          visibility: visibility,
+          custom_fields: custom_fields,
+          subject_urls: subject_urls,
+          due_date: due_date,
+          deadline_miss_reason: deadline_miss_reason,
+        )
+        project_metadata.validate_custom_fields!
+
+        template_number = PlanMyStuff.configuration.testing_template_project_number
+
+        if template_number.present?
+          create_from_template!(
+            title: title,
+            description: description,
+            readme: readme,
+            project_metadata: project_metadata,
+            template_number: template_number,
+          )
+        else
+          create_with_bootstrap!(
+            title: title,
+            description: description,
+            readme: readme,
+            project_metadata: project_metadata,
+            org: org,
+          )
+        end
+      end
+
+      # Finds a testing project by number. Raises if the project exists but is
+      # not a testing project.
+      #
+      # @param number [Integer]
+      # @param paginate [Symbol] :auto (default) or :cursor
+      # @param cursor [String, nil]
+      #
+      # @raise [ArgumentError] if the project is not a testing project
+      #
+      # @return [PlanMyStuff::TestingProject]
+      #
+      def find(number, paginate: :auto, cursor: nil)
+        project = super
+
+        unless project.is_a?(self)
+          raise(ArgumentError, "Project ##{number} is not a testing project; use PlanMyStuff::Project.find")
+        end
+
+        project
+      end
+
+      # Lists all testing projects in the configured organization.
+      #
+      # @return [Array<PlanMyStuff::TestingProject>]
+      #
+      def list
+        super.select { |p| p.is_a?(self) }
+      end
+
+      private
+
+        # Creates a TestingProject by cloning the configured template project,
+        # then writes PMS metadata to the clone's readme.
+        #
+        # @param title [String]
+        # @param description [String, nil]
+        # @param readme [String]
+        # @param project_metadata [PlanMyStuff::TestingProjectMetadata]
+        # @param template_number [Integer]
+        #
+        # @return [PlanMyStuff::TestingProject]
+        #
+        def create_from_template!(title:, description:, readme:, project_metadata:, template_number:)
+          project = clone!(source_number: template_number, title: title)
+
+          serialized_readme = PlanMyStuff::MetadataParser.serialize(project_metadata.to_h, readme)
+          update_input = { projectId: project.id, readme: serialized_readme }
+          update_input[:shortDescription] = description if description.present?
+
+          PlanMyStuff.client.graphql(
+            PlanMyStuff::GraphQL::Queries::UPDATE_PROJECT,
+            variables: { input: update_input },
+          )
+
+          find(project.number)
+        end
+
+        # Creates a TestingProject from scratch via createProjectV2, then
+        # bootstraps any missing custom fields defined in BOOTSTRAP_FIELDS.
+        # Used as a fallback when no template project is configured.
+        #
+        # @param title [String]
+        # @param description [String, nil]
+        # @param readme [String]
+        # @param project_metadata [PlanMyStuff::TestingProjectMetadata]
+        # @param org [String]
+        #
+        # @return [PlanMyStuff::TestingProject]
+        #
+        def create_with_bootstrap!(title:, description:, readme:, project_metadata:, org:)
+          org_id = resolve_org_id(org)
+          data = PlanMyStuff.client.graphql(
+            PlanMyStuff::GraphQL::Queries::CREATE_PROJECT,
+            variables: { input: { ownerId: org_id, title: title } },
+          )
+
+          new_project = data.dig(:createProjectV2, :projectV2) || {}
+          project_id = new_project[:id]
+          project_number = new_project[:number]
+
+          serialized_readme = PlanMyStuff::MetadataParser.serialize(project_metadata.to_h, readme)
+          update_input = { projectId: project_id, readme: serialized_readme }
+          update_input[:shortDescription] = description if description.present?
+
+          PlanMyStuff.client.graphql(
+            PlanMyStuff::GraphQL::Queries::UPDATE_PROJECT,
+            variables: { input: update_input },
+          )
+
+          bootstrap_fields!(project_id, project_number)
+
+          find(project_number)
+        end
+
+        # Creates any missing custom fields on the newly created GH Project.
+        #
+        # @param project_id [String] GitHub node ID of the project
+        # @param project_number [Integer]
+        #
+        # @return [void]
+        #
+        def bootstrap_fields!(project_id, project_number)
+          current = find(project_number)
+          existing_names = current.fields.pluck(:name)
+
+          BOOTSTRAP_FIELDS.each do |field_def|
+            next if existing_names.include?(field_def[:name])
+
+            create_project_field!(project_id, field_def)
+          end
+        end
+
+        # Executes a createProjectV2Field mutation for one field definition.
+        #
+        # @param project_id [String]
+        # @param field_def [Hash] :name, :data_type, and optional :options
+        #
+        # @return [void]
+        #
+        def create_project_field!(project_id, field_def)
+          input = {
+            projectId: project_id,
+            dataType: field_def[:data_type],
+            name: field_def[:name],
+          }
+
+          if field_def[:data_type] == 'SINGLE_SELECT'
+            input[:singleSelectOptions] =
+              field_def[:options].map { |opt| { name: opt, color: 'GRAY', description: '' } }
+          end
+
+          PlanMyStuff.client.graphql(
+            PlanMyStuff::GraphQL::Queries::CREATE_PROJECT_V2_FIELD,
+            variables: { input: input },
+          )
+        end
+
+        # @param field_values [Array<Hash>] raw GraphQL field value nodes
+        #
+        # @return [String, nil]
+        #
+        def extract_item_status(field_values)
+          status_value = field_values.find { |fv| fv.dig(:field, :name) == 'Test Status' }
+          status_value&.dig(:name)
+        end
+    end
+
+    # Returns the Test Status single-select field definition.
+    #
+    # @return [Hash] with :id and :options keys
+    #
+    # @raise [PlanMyStuff::APIError] if no Test Status field exists
+    #
+    def status_field
+      field = fields.find { |f| f[:name] == 'Test Status' && f[:options] }
+
+      raise(APIError, "No 'Test Status' field found on project ##{number}") unless field
+
+      field
+    end
+
+    private
+
+      # @see super
+      def create_kwargs_from_metadata
+        super.merge(
+          subject_urls: metadata.respond_to?(:subject_urls) ? Array.wrap(metadata.subject_urls) : [],
+          due_date: metadata.respond_to?(:due_date) ? metadata.due_date : nil,
+          deadline_miss_reason: metadata.respond_to?(:deadline_miss_reason) ? metadata.deadline_miss_reason : nil,
+        )
+      end
+
+      # Returns the item class used to build items for testing projects.
+      #
+      # @return [Class]
+      #
+      def item_class
+        PlanMyStuff::TestingProjectItem
+      end
+
+      # @param fields_nodes [Array<Hash>]
+      #
+      # @return [Array<Hash>]
+      #
+      def extract_statuses(fields_nodes)
+        field = fields_nodes.find { |f| f[:name] == 'Test Status' && f.key?(:options) }
+        return [] unless field
+
+        (field[:options] || []).map { |opt| { id: opt[:id], name: opt[:name] } }
+      end
+  end
+end

data/lib/plan_my_stuff/testing_project_item.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # A project item belonging to a TestingProject. Extends BaseProjectItem with
+  # testing-specific field updaters and pass/fail sign-off logic.
+  class TestingProjectItem < PlanMyStuff::BaseProjectItem
+    # Updates the Pass Mode single-select field on this testing project item.
+    #
+    # @param value [String] "all" or "any"
+    #
+    # @return [Hash] mutation result
+    #
+    def update_pass_mode!(value)
+      self.class.update_single_select_field!(
+        project_number: project.number,
+        item_id: id,
+        field_name: 'Pass Mode',
+        value: value,
+      )
+    end
+
+    # Updates the due date field on this testing project item.
+    #
+    # @param date [Date, String]
+    #
+    # @return [Hash] mutation result
+    #
+    def update_due_date!(date)
+      self.class.update_date_field!(
+        project_number: project.number,
+        item_id: id,
+        field_name: 'Due Date',
+        date: date,
+      )
+    end
+
+    # Updates the Testers field (comma-joined user IDs) on this item.
+    #
+    # @param user_ids [Integer, String, Array<Integer, String>]
+    #
+    # @return [Hash] mutation result
+    #
+    def update_testers!(user_ids)
+      update_field!('Testers', Array.wrap(user_ids).join(', '))
+    end
+
+    # Updates the Watchers field (comma-joined user IDs) on this item.
+    #
+    # @param user_ids [Integer, String, Array<Integer, String>]
+    #
+    # @return [Hash] mutation result
+    #
+    def update_watchers!(user_ids)
+      update_field!('Watchers', Array.wrap(user_ids).join(', '))
+    end
+
+    # Updates the Result Notes field on this testing project item.
+    #
+    # @param notes [String]
+    #
+    # @return [Hash] mutation result
+    #
+    def update_result_notes!(notes)
+      update_field!('Result Notes', notes)
+    end
+
+    # Records the timestamp when this item was passed as an ISO 8601 string.
+    #
+    # @param time [Time]
+    #
+    # @return [Hash] mutation result
+    #
+    def update_passed_at!(time)
+      update_field!('Passed At', time.utc.iso8601)
+    end
+
+    # Updates the Deadline Miss Reason field on this testing project item.
+    #
+    # @param reason [String]
+    #
+    # @return [Hash] mutation result
+    #
+    def update_deadline_miss_reason!(reason)
+      update_field!('Deadline Miss Reason', reason)
+    end
+
+    # Appends +user_id+ to the Passed By field and, when the pass_mode
+    # condition is satisfied, moves the item to the Passed status.
+    #
+    # pass_mode "all" - flips to Passed when every tester has signed off.
+    # pass_mode "any" - flips to Passed as soon as one tester signs off.
+    #
+    # No-op when the user has already signed off on this item.
+    #
+    # @param user [Object] PMS user object of the tester signing off
+    #
+    # @return [void]
+    #
+    def mark_passed!(user)
+      raise(PMS::ValidationError, 'No user configured for sign-off.') if user.blank?
+
+      user_id = PMS::UserResolver.user_id(user).to_s
+      current = user_ids_from_field('Passed By')
+      return if current.include?(user_id)
+
+      new_passed_by = current + [user_id]
+      update_passed_by!(new_passed_by)
+      field_values['Passed By'] = new_passed_by.join(', ')
+
+      testers = user_ids_from_field('Testers')
+      pass_mode = field_values['Pass Mode']
+
+      should_pass =
+        case pass_mode
+        when 'any' then true
+        when 'all' then new_passed_by.sort == testers.sort
+        else false
+        end
+
+      return unless should_pass
+
+      update_passed_at!(Time.now.utc)
+      move_to!('Passed')
+    end
+
+    # Records +user_id+ as having failed this item, writes +result_notes+,
+    # and moves the item to the Failed status.
+    #
+    # @param user [Object] PMS user object of the tester failing the item
+    # @param result_notes [String] required explanation of the failure
+    #
+    # @raise [PlanMyStuff::ValidationError] if result_notes is blank
+    #
+    # @return [void]
+    #
+    def mark_failed!(user, result_notes:)
+      raise(PMS::ValidationError, 'Result notes are required when failing an item.') if result_notes.blank?
+      raise(PMS::ValidationError, 'No user configured for sign-off.') if user.blank?
+
+      update_result_notes!(result_notes)
+
+      user_id = PMS::UserResolver.user_id(user).to_s
+      current = user_ids_from_field('Failed By')
+      return if current.include?(user_id)
+
+      new_failed_by = current + [user_id]
+      update_failed_by!(new_failed_by)
+      field_values['Failed By'] = new_failed_by.join(', ')
+
+      move_to!('Failed')
+    end
+
+    private
+
+      # @param user_ids [Integer, String, Array<Integer, String>]
+      #
+      # @return [Hash] mutation result
+      #
+      def update_passed_by!(user_ids)
+        update_field!('Passed By', Array.wrap(user_ids).join(', '))
+      end
+
+      # @param user_ids [Integer, String, Array<Integer, String>]
+      #
+      # @return [Hash] mutation result
+      #
+      def update_failed_by!(user_ids)
+        update_field!('Failed By', Array.wrap(user_ids).join(', '))
+      end
+
+      # Parses a comma-separated field value into an array of trimmed logins.
+      #
+      # @param field_name [String]
+      #
+      # @return [Array<String>]
+      #
+      def user_ids_from_field(field_name)
+        val = field_values[field_name]
+        return [] if val.blank?
+
+        val.split(',').map(&:strip).compact_blank
+      end
+  end
+end

data/lib/plan_my_stuff/testing_project_metadata.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Metadata for testing projects, stored in the GH Project readme field.
+  # Detected at read time by kind: "testing" in the serialized metadata blob.
+  class TestingProjectMetadata < BaseProjectMetadata
+    # @return [Array<String>] PR/issue URLs this testing project covers
+    attr_accessor :subject_urls
+    # @return [Date, nil] project-level deadline
+    attr_accessor :due_date
+    # @return [String, nil] free-text captured when the project deadline slips
+    attr_accessor :deadline_miss_reason
+
+    class << self
+      # Builds a TestingProjectMetadata from a parsed hash.
+      #
+      # @param hash [Hash]
+      #
+      # @return [PlanMyStuff::TestingProjectMetadata]
+      #
+      def from_hash(hash)
+        metadata = new
+        apply_common_from_hash(metadata, hash, PlanMyStuff.configuration.custom_fields_for(:testing))
+        metadata.subject_urls = Array.wrap(hash[:subject_urls])
+        metadata.due_date = parse_date(hash[:due_date])
+        metadata.deadline_miss_reason = hash[:deadline_miss_reason]
+        metadata
+      end
+
+      # Builds a new TestingProjectMetadata for project creation.
+      #
+      # @param user [Object, Integer] user object or user_id
+      # @param visibility [String] "public" or "internal"
+      # @param custom_fields [Hash] app-defined field values
+      # @param subject_urls [Array<String>] PR/issue URLs covered
+      # @param due_date [Date, nil] project-level deadline
+      # @param deadline_miss_reason [String, nil]
+      #
+      # @return [PlanMyStuff::TestingProjectMetadata]
+      #
+      def build(
+        user:,
+        visibility: 'internal',
+        custom_fields: {},
+        subject_urls: [],
+        due_date: nil,
+        deadline_miss_reason: nil
+      )
+        metadata = new
+        apply_common_build(
+          metadata,
+          user: user,
+          visibility: visibility,
+          custom_fields_data: custom_fields,
+          custom_fields_schema: PlanMyStuff.configuration.custom_fields_for(:testing),
+        )
+        metadata.subject_urls = Array.wrap(subject_urls)
+        metadata.due_date = due_date
+        metadata.deadline_miss_reason = deadline_miss_reason
+        metadata
+      end
+
+      private
+
+        # @param value [String, Date, nil]
+        #
+        # @return [Date, nil]
+        #
+        def parse_date(value)
+          return if value.nil?
+          return value if value.is_a?(Date)
+
+          Date.parse(value.to_s)
+        rescue ArgumentError, TypeError
+          nil
+        end
+    end
+
+    def initialize
+      super
+      @kind = 'testing'
+      @subject_urls = []
+    end
+
+    # @return [Hash]
+    def to_h
+      super.merge(
+        subject_urls: subject_urls,
+        due_date: due_date&.iso8601,
+        deadline_miss_reason: deadline_miss_reason,
+      )
+    end
+  end
+end

data/lib/plan_my_stuff/user_resolver.rb

@@ -33,21 +33,26 @@ module PlanMyStuff
 
       # Extracts the app-side user ID from a user object.
       #
-      # @param user [Object] user object (not an integer ID)
+      # @param user [Object, nil] user object (not an integer ID)
       #
-      # @return [Integer]
+      # @return [Integer, nil]
       #
       def user_id(user)
+        return if user.nil?
+
         user.public_send(PlanMyStuff.configuration.user_id_method)
       end
 
       # Checks whether a user is support staff.
+      # Anonymous users (nil) are never support.
       #
-      # @param user [Object] user object (not an integer ID)
+      # @param user [Object, nil] user object (not an integer ID)
       #
       # @return [Boolean]
       #
       def support?(user)
+        return false if user.nil?
+
         method = PlanMyStuff.configuration.support_method
 
         if method.is_a?(Proc)

data/lib/plan_my_stuff/version.rb

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