plan_my_stuff 0.1.0

data/lib/plan_my_stuff/test_helpers.rb

@@ -0,0 +1,501 @@
+# frozen_string_literal: true
+
+require 'plan_my_stuff'
+
+module PlanMyStuff
+  # Test support for consuming apps. Provides:
+  # - `PlanMyStuff.test_mode!` to stub all API calls
+  # - Factory-style builders: `build_issue`, `build_comment`, `build_project`
+  # - RSpec matchers: `expect_pms_issue_created`, `expect_pms_comment_created`, `expect_pms_item_moved`
+  #
+  # Usage:
+  #   require 'plan_my_stuff/test_helpers'
+  #
+  #   RSpec.configure do |config|
+  #     config.include PlanMyStuff::TestHelpers
+  #   end
+  module TestHelpers
+    # Recorded actions during test mode, keyed by type:
+    #   :issue_created, :comment_created, :item_moved
+    thread_mattr_accessor :recorded_actions
+    self.recorded_actions = []
+
+    class << self
+      # Builds a fake persisted Issue without hitting the API.
+      #
+      # @param title [String]
+      # @param body [String]
+      # @param state [Symbol, String]
+      # @param number [Integer]
+      # @param repo [String]
+      # @param labels [Array<String>]
+      # @param metadata [Hash] raw metadata fields to merge
+      #
+      # @return [PlanMyStuff::Issue]
+      #
+      def build_issue(
+        title: 'Test Issue',
+        body: 'Test body',
+        state: :open,
+        number: 1,
+        repo: 'TestOrg/TestRepo',
+        labels: [],
+        metadata: {}
+      )
+        issue = PlanMyStuff::Issue.new(
+          title: title,
+          body: body,
+          state: state.to_s,
+          number: number,
+          repo: repo,
+          labels: labels,
+        )
+
+        issue_metadata = PlanMyStuff::IssueMetadata.from_hash({
+          schema_version: PlanMyStuff::BaseMetadata::SCHEMA_VERSION,
+          gem_version: PlanMyStuff::VERSION::STRING,
+          visibility: 'public',
+          custom_fields: {},
+        }.merge(metadata))
+
+        issue.instance_variable_set(:@metadata, issue_metadata)
+        issue.instance_variable_set(:@persisted, true)
+
+        body_comment = build_comment(
+          body: body,
+          issue: issue,
+          metadata: { issue_body: true },
+        )
+        issue.instance_variable_set(:@comments, [body_comment])
+
+        issue
+      end
+
+      # Builds a fake persisted Comment without hitting the API.
+      #
+      # @param body [String]
+      # @param visibility [Symbol, String]
+      # @param id [Integer]
+      # @param issue [PlanMyStuff::Issue, nil] parent issue (auto-built if nil)
+      # @param metadata [Hash] raw metadata fields to merge
+      #
+      # @return [PlanMyStuff::Comment]
+      #
+      def build_comment(body: 'Test comment', visibility: :public, id: 1, issue: nil, metadata: {})
+        issue ||= build_issue
+
+        comment = PlanMyStuff::Comment.new(
+          body: body,
+          id: id,
+          issue: issue,
+        )
+        comment.visibility = visibility.to_sym
+
+        comment_metadata = PlanMyStuff::CommentMetadata.from_hash({
+          schema_version: PlanMyStuff::BaseMetadata::SCHEMA_VERSION,
+          gem_version: PlanMyStuff::VERSION::STRING,
+          visibility: visibility.to_s,
+          custom_fields: {},
+        }.merge(metadata))
+
+        comment.instance_variable_set(:@metadata, comment_metadata)
+        comment.instance_variable_set(:@persisted, true)
+        comment
+      end
+
+      # Builds a fake persisted Project without hitting the API.
+      #
+      # @param title [String]
+      # @param number [Integer]
+      # @param statuses [Array<String>] status names (auto-assigned IDs)
+      # @param items [Array<Hash>] item data hashes
+      #
+      # @return [PlanMyStuff::Project]
+      #
+      def build_project(title: 'Test Project', number: 1, statuses: [], items: [])
+        status_options = statuses.each_with_index.map do |name, i|
+          { id: "status_option_#{i}", name: name }
+        end
+
+        project = PlanMyStuff::Project.new(
+          id: "PVT_fake_#{number}",
+          number: number,
+          title: title,
+          statuses: status_options,
+          fields: [{ id: 'field_status', name: 'Status', options: status_options }],
+        )
+        project.instance_variable_set(:@persisted, true)
+
+        project.items = items.map do |item_hash|
+          PlanMyStuff::ProjectItem.build(
+            {
+              id: item_hash[:id] || "PVTI_fake_#{rand(10_000)}",
+              title: item_hash[:title] || 'Untitled',
+              number: item_hash[:number],
+              url: item_hash[:url],
+              state: item_hash[:state],
+              status: item_hash[:status],
+              field_values: item_hash[:field_values] || {},
+            },
+            project: project,
+          )
+        end
+
+        project
+      end
+    end
+
+    # RSpec matchers included when the module is included in a test config.
+    # Each matcher asserts that a matching action was recorded during test mode.
+
+    # @param filters [Hash] attribute filters (e.g. repo:, title:)
+    def expect_pms_issue_created(**filters)
+      expect_pms_action(:issue_created, 'issue to be created', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. number:, repo:)
+    def expect_pms_issue_found(**filters)
+      expect_pms_action(:issue_found, 'issue to be found', **filters)
+    end
+
+    # @param filters [Hash] attribute filters
+    def expect_pms_issues_listed(**filters)
+      expect_pms_action(:issues_listed, 'issues to be listed', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. number:, state:)
+    def expect_pms_issue_updated(**filters)
+      expect_pms_action(:issue_updated, 'issue to be updated', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. number:, user_ids:)
+    def expect_pms_viewers_added(**filters)
+      expect_pms_action(:viewers_added, 'viewers to be added', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. number:, user_ids:)
+    def expect_pms_viewers_removed(**filters)
+      expect_pms_action(:viewers_removed, 'viewers to be removed', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. issue_number:, visibility:)
+    def expect_pms_comment_created(**filters)
+      expect_pms_action(:comment_created, 'comment to be created', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. issue_number:, pms_only:)
+    def expect_pms_comments_listed(**filters)
+      expect_pms_action(:comments_listed, 'comments to be listed', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. id:, body:)
+    def expect_pms_comment_updated(**filters)
+      expect_pms_action(:comment_updated, 'comment to be updated', **filters)
+    end
+
+    # @param filters [Hash] attribute filters
+    def expect_pms_projects_listed(**filters)
+      expect_pms_action(:projects_listed, 'projects to be listed', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. number:)
+    def expect_pms_project_found(**filters)
+      expect_pms_action(:project_found, 'project to be found', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. project:, status:)
+    def expect_pms_item_moved(**filters)
+      expect_pms_action(:item_moved, 'item to be moved', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. project:, title:)
+    def expect_pms_item_created(**filters)
+      expect_pms_action(:item_created, 'item to be created', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. project:, assignee:)
+    def expect_pms_item_assigned(**filters)
+      expect_pms_action(:item_assigned, 'item to be assigned', **filters)
+    end
+
+    private
+
+      # @return [void]
+      def expect_pms_action(type, description, **filters)
+        match = PlanMyStuff::TestHelpers.recorded_actions.find do |action|
+          action[:type] == type && matches_filters?(action[:params], filters)
+        end
+
+        expect(match).to(
+          be_truthy,
+          "Expected PMS #{description} with #{filters.inspect}, " \
+            "but recorded actions were: #{format_actions(type)}",
+        )
+      end
+
+      # @return [Boolean]
+      def matches_filters?(params, filters)
+        filters.all? do |key, value|
+          params.key?(key) && params[key].to_s == value.to_s
+        end
+      end
+
+      # @return [String]
+      def format_actions(type)
+        actions = PlanMyStuff::TestHelpers.recorded_actions.select { |a| a[:type] == type }
+        return '(none)' if actions.empty?
+
+        actions.map { |a| a[:params].inspect }.join(', ')
+      end
+  end
+
+  class << self
+    # Activates test mode: stubs all API-calling class methods on Issue,
+    # Comment, and ProjectItem so no real HTTP requests are made.
+    # Records all actions for assertion matchers.
+    #
+    # @return [void]
+    #
+    def test_mode!
+      TestHelpers.recorded_actions = []
+      return if @_test_mode
+
+      @_test_mode_originals = {}
+      stub_issue_class_methods!
+      stub_comment_class_methods!
+      stub_project_class_methods!
+      stub_project_item_class_methods!
+      @_test_mode = true
+    end
+
+    # Restores original class methods overwritten by test_mode!
+    #
+    # @return [void]
+    #
+    def exit_test_mode!
+      return unless @_test_mode
+
+      (@_test_mode_originals || {}).each do |klass, methods|
+        methods.each do |name, original|
+          klass.define_singleton_method(name, original)
+        end
+      end
+
+      @_test_mode_originals = nil
+      @_test_mode = false
+      TestHelpers.recorded_actions = []
+    end
+
+    private
+
+      # Saves the original method so it can be restored by exit_test_mode!
+      #
+      # @param klass [Class]
+      # @param method_name [Symbol]
+      #
+      # @return [void]
+      #
+      def save_original(klass, method_name)
+        @_test_mode_originals[klass] ||= {}
+        @_test_mode_originals[klass][method_name] = klass.method(method_name)
+      end
+
+      # @return [void]
+      def stub_issue_class_methods!
+        issue_mod = PlanMyStuff::Issue
+        %i[create! find list update! add_viewers remove_viewers].each { |m| save_original(issue_mod, m) }
+
+        issue_mod.define_singleton_method(:create!) do |**params|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :issue_created,
+            params: {
+              title: params[:title],
+              body: params[:body],
+              repo: params[:repo],
+              labels: params[:labels] || [],
+            },
+          }
+
+          PlanMyStuff::TestHelpers.build_issue(
+            title: params[:title],
+            body: params[:body],
+            repo: params[:repo]&.to_s || 'TestOrg/TestRepo',
+            labels: params[:labels] || [],
+          )
+        end
+
+        issue_mod.define_singleton_method(:find) do |number, repo: nil|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :issue_found,
+            params: { number: number, repo: repo },
+          }
+
+          PlanMyStuff::TestHelpers.build_issue(number: number, repo: repo&.to_s || 'TestOrg/TestRepo')
+        end
+
+        issue_mod.define_singleton_method(:list) do |**params|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :issues_listed,
+            params: params,
+          }
+
+          []
+        end
+
+        issue_mod.define_singleton_method(:update!) do |**params|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :issue_updated,
+            params: params,
+          }
+
+          nil
+        end
+
+        issue_mod.define_singleton_method(:add_viewers) do |**params|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :viewers_added,
+            params: params,
+          }
+
+          nil
+        end
+
+        issue_mod.define_singleton_method(:remove_viewers) do |**params|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :viewers_removed,
+            params: params,
+          }
+
+          nil
+        end
+      end
+
+      # @return [void]
+      def stub_comment_class_methods!
+        comment_mod = PlanMyStuff::Comment
+        %i[create! list update!].each { |m| save_original(comment_mod, m) }
+
+        comment_mod.define_singleton_method(:create!) do |**params|
+          issue_number = params[:issue].respond_to?(:number) ? params[:issue].number : nil
+
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :comment_created,
+            params: {
+              issue_number: issue_number,
+              body: params[:body],
+              visibility: (params[:visibility] || :public).to_sym,
+            },
+          }
+
+          PlanMyStuff::TestHelpers.build_comment(
+            body: params[:body],
+            visibility: params[:visibility] || :public,
+            issue: params[:issue],
+          )
+        end
+
+        comment_mod.define_singleton_method(:list) do |**params|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :comments_listed,
+            params: {
+              issue_number: params[:issue].respond_to?(:number) ? params[:issue].number : nil,
+              pms_only: params[:pms_only] || false,
+            },
+          }
+
+          []
+        end
+
+        comment_mod.define_singleton_method(:update!) do |**params|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :comment_updated,
+            params: params,
+          }
+
+          nil
+        end
+      end
+
+      # @return [void]
+      def stub_project_class_methods!
+        project_mod = PlanMyStuff::Project
+        %i[list find].each { |m| save_original(project_mod, m) }
+
+        project_mod.define_singleton_method(:list) do |**params|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :projects_listed,
+            params: params,
+          }
+
+          []
+        end
+
+        project_mod.define_singleton_method(:find) do |number, **params|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :project_found,
+            params: { number: number }.merge(params),
+          }
+
+          PlanMyStuff::TestHelpers.build_project(number: number)
+        end
+      end
+
+      # @return [void]
+      def stub_project_item_class_methods!
+        item_mod = PlanMyStuff::ProjectItem
+        %i[move_item create! assign].each { |m| save_original(item_mod, m) }
+
+        item_mod.define_singleton_method(:move_item) do |**params|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :item_moved,
+            params: {
+              project: params[:project_number],
+              item_id: params[:item_id],
+              status: params[:status],
+            },
+          }
+          nil
+        end
+
+        item_mod.define_singleton_method(:create!) do |issue_or_title, **params|
+          title = issue_or_title.respond_to?(:title) ? issue_or_title.title : issue_or_title.to_s
+          number = issue_or_title.respond_to?(:number) ? issue_or_title.number : nil
+
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :item_created,
+            params: {
+              project: params[:project_number],
+              title: title,
+              number: number,
+              draft: params[:draft] || false,
+            },
+          }
+
+          project = PlanMyStuff::TestHelpers.build_project(number: params[:project_number] || 1)
+          PlanMyStuff::ProjectItem.build(
+            {
+              id: "PVTI_fake_#{rand(10_000)}",
+              title: title,
+              number: number,
+              status: nil,
+              field_values: {},
+            },
+            project: project,
+          )
+        end
+
+        item_mod.define_singleton_method(:assign) do |**params|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :item_assigned,
+            params: {
+              project: params[:project_number],
+              item_id: params[:item_id],
+              assignee: params[:assignee],
+            },
+          }
+
+          nil
+        end
+      end
+  end
+end

data/lib/plan_my_stuff/user_resolver.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Resolves user objects from user objects or integer IDs, and extracts
+  # display names, IDs, and support status using configuration methods.
+  module UserResolver
+    class << self
+      # Resolves a user param (object or integer ID) into a user object.
+      #
+      # @param user [Object, Integer] user object or user_id integer
+      #
+      # @return [Object] the resolved user object
+      #
+      def resolve(user)
+        return if user.nil?
+
+        return user unless user.is_a?(Integer)
+
+        config = PlanMyStuff.configuration
+        klass = Object.const_get(config.user_class)
+        klass.find_by!(config.user_id_method => user)
+      end
+
+      # Extracts the display name from a user object.
+      #
+      # @param user [Object] user object (not an integer ID)
+      #
+      # @return [String]
+      #
+      def display_name(user)
+        user.public_send(PlanMyStuff.configuration.display_name_method)
+      end
+
+      # Extracts the app-side user ID from a user object.
+      #
+      # @param user [Object] user object (not an integer ID)
+      #
+      # @return [Integer]
+      #
+      def user_id(user)
+        user.public_send(PlanMyStuff.configuration.user_id_method)
+      end
+
+      # Checks whether a user is support staff.
+      #
+      # @param user [Object] user object (not an integer ID)
+      #
+      # @return [Boolean]
+      #
+      def support?(user)
+        method = PlanMyStuff.configuration.support_method
+
+        if method.is_a?(Proc)
+          method.call(user)
+        else
+          user.public_send(method)
+        end
+      end
+    end
+  end
+end

data/lib/plan_my_stuff/verifier.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Verifies PlanMyStuff configuration by making API calls to GitHub.
+  # Checks token validity, org access, repo access, and project access.
+  class Verifier
+    Result = Struct.new(:name, :passed, :message)
+
+    # @return [Array<Result>]
+    attr_reader :results
+
+    # @return [Verifier]
+    def initialize
+      @results = []
+    end
+
+    # Runs all verification checks and returns self.
+    #
+    # @return [Verifier]
+    #
+    def run
+      check_token
+      check_organization
+      check_repos
+      check_default_project
+      self
+    end
+
+    # @return [Boolean]
+    def passed?
+      results.all?(&:passed)
+    end
+
+    private
+
+      # @return [void]
+      def check_token
+        user = PlanMyStuff.client.rest(:user)
+        @results << Result.new('Token', true, "Authenticated as #{user.login}")
+      rescue => e
+        @results << Result.new('Token', false, e.message)
+      end
+
+      # @return [void]
+      def check_organization
+        org = PlanMyStuff.configuration.organization
+        PlanMyStuff.client.rest(:organization, org)
+        @results << Result.new('Organization', true, "Access to #{org} confirmed")
+      rescue => e
+        @results << Result.new('Organization', false, "#{org}: #{e.message}")
+      end
+
+      # @return [void]
+      def check_repos
+        config = PlanMyStuff.configuration
+
+        if config.repos.empty? && config.default_repo.nil?
+          @results << Result.new('Repos', true, 'No repos configured (skipped)')
+          return
+        end
+
+        config.repos.each do |key, full_name|
+          check_single_repo(key, full_name)
+        end
+
+        return if config.default_repo.nil? || config.repos.key?(config.default_repo)
+
+        @results << Result.new(
+          'Default repo',
+          false,
+          "default_repo #{config.default_repo.inspect} not found in repos hash",
+        )
+      end
+
+      # @return [void]
+      def check_single_repo(key, full_name)
+        PlanMyStuff.client.rest(:repository, full_name)
+        @results << Result.new("Repo :#{key}", true, "Access to #{full_name} confirmed")
+      rescue => e
+        @results << Result.new("Repo :#{key}", false, "#{full_name}: #{e.message}")
+      end
+
+      # @return [void]
+      def check_default_project
+        project_number = PlanMyStuff.configuration.default_project_number
+
+        if project_number.nil?
+          @results << Result.new('Project', true, 'No default project configured (skipped)')
+          return
+        end
+
+        project = PlanMyStuff::Project.find(project_number)
+        @results << Result.new(
+          'Project',
+          true,
+          "Access to project ##{project_number} (#{project.title}) confirmed",
+        )
+      rescue => e
+        @results << Result.new('Project', false, "Project ##{project_number}: #{e.message}")
+      end
+  end
+end

data/lib/plan_my_stuff/version.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module VERSION
+    MAJOR = 0
+    MINOR = 1
+    TINY = 0
+
+    # Set PRE to nil unless it's a pre-release (beta, rc, etc.)
+    PRE = nil
+
+    STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.').freeze
+
+    # :nodoc:
+    def self.to_s
+      STRING
+    end
+  end
+end