plan_my_stuff 0.3.0 → 0.4.0

data/lib/plan_my_stuff/base_project.rb

@@ -0,0 +1,661 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Shared base for GitHub Projects V2 wrappers. Holds attribute definitions,
+  # generic find/list/update machinery, hydration, and instance helpers.
+  # Concrete subclasses (Project, TestingProject) add their own +create!+
+  # behavior and optional filtering on +find+/+list+.
+  #
+  # Not instantiated directly. +find+ and +list+ dispatch via +build_detail+/
+  # +build_summary+ to the correct concrete subclass based on the metadata
+  # +kind+ field in the project readme.
+  class BaseProject < PlanMyStuff::ApplicationRecord
+    MAX_AUTO_PAGINATE_ITEMS = 500
+    ITEMS_PER_PAGE = 100
+
+    # @return [String, nil] GitHub node ID
+    attribute :id, :string
+    # @return [Integer, nil] project number
+    attribute :number, :integer
+    # @return [Boolean, nil] whether the project is closed
+    attribute :closed
+    # @return [PlanMyStuff::BaseProjectMetadata] parsed metadata (empty when no PMS metadata present)
+    attribute :metadata, default: -> { PlanMyStuff::ProjectMetadata.new }
+    # @return [String, nil] full readme as stored on GitHub
+    attribute :raw_readme, :string
+    # @return [String, nil] project short description (from shortDescription)
+    attribute :description, :string
+    # @return [Time, nil] GitHub's updatedAt timestamp
+    attribute :updated_at
+    # @return [String, nil] project title
+    attribute :title, :string
+    # @return [String, nil] project URL
+    attribute :url, :string
+    # @return [String, nil] user-visible readme content (without metadata comment)
+    attribute :readme, :string
+    # @return [Array<Hash>] status options ({id:, name:})
+    attribute :statuses, default: -> { [] }
+    # @return [Array<Hash>] all field definitions
+    attribute :fields, default: -> { [] }
+    # @return [Array<PlanMyStuff::ProjectItem>] project items
+    attribute :items, default: -> { [] }
+    # @return [String, nil] cursor for next page (only in cursor mode)
+    attribute :next_cursor, :string
+    # @return [Boolean, nil] whether more pages exist (only in cursor mode)
+    attribute :has_next_page
+
+    class << self
+      # Generic find - returns whichever concrete project type is at the given
+      # number, dispatching on metadata kind. Subclasses may override to apply
+      # filtering (e.g. Project raises for testing projects by default).
+      #
+      # @param number [Integer]
+      # @param paginate [Symbol] :auto (default) or :cursor
+      # @param cursor [String, nil] pagination cursor for :cursor mode
+      #
+      # @return [PlanMyStuff::BaseProject]
+      #
+      def find(number, paginate: :auto, cursor: nil)
+        org = PlanMyStuff.configuration.organization
+
+        case paginate
+        when :auto
+          find_auto_paginated(org, number)
+        when :cursor
+          find_with_cursor(org, number, cursor: cursor)
+        else
+          raise(ArgumentError, "Unknown paginate mode: #{paginate.inspect}. Use :auto or :cursor")
+        end
+      end
+
+      # Generic list - returns all projects in the configured organization,
+      # each dispatched to its concrete type (Project or TestingProject).
+      # Subclasses may override to apply filtering.
+      #
+      # @return [Array<PlanMyStuff::BaseProject>]
+      #
+      def list
+        org = PlanMyStuff.configuration.organization
+        data = PlanMyStuff.client.graphql(
+          PlanMyStuff::GraphQL::Queries::LIST_PROJECTS,
+          variables: { org: org },
+        )
+
+        nodes = data.dig(:organization, :projectsV2, :nodes) || []
+        nodes.map { |node| build_summary(node) }
+      end
+
+      # Updates an existing project.
+      #
+      # @param project_number [Integer]
+      # @param title [String, nil]
+      # @param readme [String, nil] user-visible readme content (metadata preserved)
+      # @param description [String, nil] project short description
+      # @param metadata [Hash, nil] custom fields to merge into existing metadata
+      #
+      # @return [PlanMyStuff::BaseProject]
+      #
+      def update!(project_number:, title: nil, readme: nil, description: nil, metadata: nil)
+        org = PlanMyStuff.configuration.organization
+        project_id = resolve_project_id(org, project_number)
+
+        update_input = { projectId: project_id }
+        update_input[:title] = title unless title.nil?
+        update_input[:shortDescription] = description unless description.nil?
+
+        if metadata.present? || !readme.nil?
+          current = find(project_number)
+          parsed = PlanMyStuff::MetadataParser.parse(current.raw_readme)
+          existing_metadata = parsed[:metadata]
+
+          if metadata.present?
+            # Seed with fresh metadata when project has no existing PMS metadata
+            if existing_metadata[:schema_version].blank?
+              existing_metadata = PlanMyStuff::ProjectMetadata.build(user: nil).to_h
+            end
+
+            merged_custom_fields = (existing_metadata[:custom_fields] || {}).merge(metadata[:custom_fields] || {})
+            existing_metadata = existing_metadata.merge(metadata)
+            existing_metadata[:custom_fields] = merged_custom_fields
+            PlanMyStuff::CustomFields.new(
+              PlanMyStuff.configuration.custom_fields_for(:project),
+              merged_custom_fields,
+            ).validate!
+          end
+
+          body = readme.nil? ? parsed[:body] : readme
+          update_input[:readme] = PlanMyStuff::MetadataParser.serialize(existing_metadata, body)
+        end
+
+        PlanMyStuff.client.graphql(
+          PlanMyStuff::GraphQL::Queries::UPDATE_PROJECT,
+          variables: { input: update_input },
+        )
+
+        find(project_number)
+      end
+
+      # Clones an existing GitHub Project into the configured organization.
+      # The copy inherits all custom fields and board layout from the source.
+      # Returns the newly created project via +find+, dispatched to the correct
+      # concrete subclass (Project or TestingProject) based on the cloned readme.
+      #
+      # @param source_number [Integer] project number of the project to copy from
+      # @param title [String] title for the new project
+      #
+      # @return [PlanMyStuff::BaseProject]
+      #
+      def clone!(source_number:, title:)
+        org = PlanMyStuff.configuration.organization
+        org_id = resolve_org_id(org)
+        source_project_id = resolve_project_id(org, source_number)
+
+        data = PlanMyStuff.client.graphql(
+          PlanMyStuff::GraphQL::Queries::COPY_PROJECT_V2,
+          variables: {
+            input: {
+              ownerId: org_id,
+              projectId: source_project_id,
+              title: title,
+              includeDraftIssues: false,
+            },
+          },
+        )
+
+        new_number = data.dig(:copyProjectV2, :projectV2, :number)
+        PlanMyStuff::BaseProject.find(new_number)
+      end
+
+      # Resolves a project number, falling back to config.default_project_number.
+      #
+      # @param project_number [Integer, nil]
+      #
+      # @return [Integer]
+      #
+      def resolve_default_project_number(project_number)
+        return project_number if project_number.present?
+
+        PlanMyStuff.configuration.default_project_number ||
+          raise(ArgumentError, 'project_number is required when config.default_project_number is not set')
+      end
+
+      private
+
+        # Builds a summary Project from a list query node.
+        # Dispatches to TestingProject when the readme metadata has kind: "testing".
+        #
+        # @param node [Hash]
+        #
+        # @return [PlanMyStuff::BaseProject]
+        #
+        def build_summary(node)
+          raw_readme = node[:readme] || ''
+          parsed_meta = PlanMyStuff::MetadataParser.parse(raw_readme)
+          klass = dispatch_project_class(parsed_meta[:metadata])
+          project = klass.new
+          project.__send__(:hydrate_summary, node)
+          project
+        end
+
+        # Builds a detailed Project from a find query response.
+        # Dispatches to TestingProject when the readme metadata has kind: "testing".
+        #
+        # @param graphql_project [Hash]
+        # @param items [Array<Hash>]
+        # @param next_cursor [String, nil]
+        # @param has_next_page [Boolean, nil]
+        #
+        # @return [PlanMyStuff::BaseProject]
+        #
+        def build_detail(graphql_project, items:, next_cursor: nil, has_next_page: nil)
+          raw_readme = graphql_project[:readme] || ''
+          parsed_meta = PlanMyStuff::MetadataParser.parse(raw_readme)
+          klass = dispatch_project_class(parsed_meta[:metadata])
+          project = klass.new
+          project.__send__(
+            :hydrate_detail,
+            graphql_project,
+            items: items,
+            next_cursor: next_cursor,
+            has_next_page: has_next_page,
+          )
+          project
+        end
+
+        # Returns the appropriate project class based on the metadata kind field.
+        # Always dispatches to a concrete subclass (never BaseProject itself).
+        #
+        # @param meta_hash [Hash]
+        #
+        # @return [Class]
+        #
+        def dispatch_project_class(meta_hash)
+          return PlanMyStuff::TestingProject if meta_hash[:kind] == 'testing'
+
+          PlanMyStuff::Project
+        end
+
+        # @param org [String]
+        # @param number [Integer]
+        #
+        # @return [PlanMyStuff::BaseProject]
+        #
+        def find_auto_paginated(org, number)
+          all_items = []
+          cursor = nil
+          raw_project = nil
+          page = nil
+
+          loop do
+            page = fetch_project_page(org, number, cursor)
+            raw_project ||= page[:raw]
+            all_items.concat(page[:items])
+
+            break if !page[:has_next_page] || all_items.length >= MAX_AUTO_PAGINATE_ITEMS
+
+            cursor = page[:next_cursor]
+          end
+
+          build_detail(
+            raw_project,
+            items: all_items,
+            next_cursor: page[:next_cursor],
+            has_next_page: page[:has_next_page],
+          )
+        end
+
+        # @param org [String]
+        # @param number [Integer]
+        # @param cursor [String, nil]
+        #
+        # @return [PlanMyStuff::BaseProject]
+        #
+        def find_with_cursor(org, number, cursor:)
+          page = fetch_project_page(org, number, cursor)
+          build_detail(
+            page[:raw],
+            items: page[:items],
+            next_cursor: page[:next_cursor],
+            has_next_page: page[:has_next_page],
+          )
+        end
+
+        # Fetches a single page of project data. Returns a lightweight hash
+        # for pagination loop consumption (not a Project instance).
+        #
+        # @param org [String]
+        # @param number [Integer]
+        # @param cursor [String, nil]
+        #
+        # @return [Hash] with :raw, :items, :next_cursor, :has_next_page
+        #
+        def fetch_project_page(org, number, cursor)
+          variables = { org: org, number: number }
+          variables[:cursor] = cursor if cursor
+
+          data = PlanMyStuff.client.graphql(
+            PlanMyStuff::GraphQL::Queries::FIND_PROJECT,
+            variables: variables,
+          )
+
+          raw_project = data.dig(:organization, :projectV2)
+          page_info = raw_project.dig(:items, :pageInfo) || {}
+          items_data = raw_project.dig(:items, :nodes) || []
+
+          {
+            raw: raw_project,
+            items: items_data.map { |item| parse_project_item(item) },
+            next_cursor: page_info[:endCursor],
+            has_next_page: page_info[:hasNextPage],
+          }
+        end
+
+        # @param item [Hash] raw GraphQL project item node
+        #
+        # @return [Hash]
+        #
+        def parse_project_item(item)
+          content = item[:content] || {}
+          field_values = item.dig(:fieldValues, :nodes) || []
+          repo_name = content.dig(:repository, :nameWithOwner)
+
+          {
+            id: item[:id],
+            type: item[:type],
+            content_node_id: content[:id],
+            title: content[:title],
+            body: content[:body],
+            number: content[:number],
+            url: content[:url],
+            state: content[:state],
+            repo: repo_name.present? ? PlanMyStuff::Repo.resolve(repo_name) : nil,
+            status: extract_item_status(field_values),
+            field_values: parse_field_values(field_values),
+            github_response: item,
+          }
+        end
+
+        # @param field_values [Array<Hash>]
+        #
+        # @return [String, nil]
+        #
+        def extract_item_status(field_values)
+          status_value = field_values.find { |fv| fv.dig(:field, :name) == 'Status' }
+
+          status_value&.dig(:name)
+        end
+
+        # @param field_values [Array<Hash>]
+        #
+        # @return [Hash]
+        #
+        def parse_field_values(field_values)
+          result = {}
+
+          field_values.each do |fv|
+            field_name = fv.dig(:field, :name)
+            next unless field_name
+
+            value = fv[:name] || fv[:text]
+            users_node = fv[:users]
+            if users_node
+              value = (users_node[:nodes] || []).map { |u| u[:login] }
+            end
+
+            result[field_name] = value
+          end
+
+          result
+        end
+
+        # Resolves a project number to its node ID.
+        #
+        # @param org [String]
+        # @param project_number [Integer]
+        #
+        # @return [String]
+        #
+        def resolve_project_id(org, project_number)
+          data = PlanMyStuff.client.graphql(
+            PlanMyStuff::GraphQL::Queries::PROJECT_ID,
+            variables: { org: org, number: project_number },
+          )
+
+          data.dig(:organization, :projectV2, :id)
+        end
+
+        # Resolves an organization login to its node ID.
+        #
+        # @param org [String]
+        #
+        # @return [String]
+        #
+        def resolve_org_id(org)
+          data = PlanMyStuff.client.graphql(
+            PlanMyStuff::GraphQL::Queries::ORG_ID,
+            variables: { org: org },
+          )
+
+          data.dig(:organization, :id)
+        end
+    end
+
+    # Returns the Status single-select field definition.
+    #
+    # @return [Hash] with :id and :options keys
+    #
+    # @raise [PlanMyStuff::APIError] if no Status field exists
+    #
+    def status_field
+      field = fields.find { |f| f[:name] == 'Status' && f[:options] }
+
+      raise(APIError, "No 'Status' field found on project ##{number}") unless field
+
+      field
+    end
+
+    # @return [Boolean]
+    def pms_project?
+      metadata.schema_version.present?
+    end
+
+    # Persists the project. Creates if new, updates if persisted.
+    #
+    # @raise [PlanMyStuff::StaleObjectError] on update if stale
+    #
+    # @return [self]
+    #
+    def save!
+      if new_record?
+        created = self.class.create!(
+          title: title,
+          readme: readme || '',
+          description: description,
+          **create_kwargs_from_metadata,
+        )
+        hydrate_from_project(created)
+      else
+        update!(
+          title: title,
+          readme: readme,
+          description: description,
+          metadata: metadata_for_update,
+        )
+      end
+
+      self
+    end
+
+    # Updates this project on GitHub. Raises StaleObjectError if the remote
+    # has been modified since this instance was loaded.
+    #
+    # @param attrs [Hash] attributes to update (title:, readme:, description:, metadata:)
+    #
+    # @raise [PlanMyStuff::StaleObjectError] if remote updated_at differs from local
+    #
+    # @return [self]
+    #
+    def update!(**attrs)
+      raise_if_stale!
+
+      self.class.update!(
+        project_number: number,
+        **attrs,
+      )
+
+      reload
+    end
+
+    # Re-fetches this project from GitHub and updates all local attributes.
+    #
+    # @return [self]
+    #
+    def reload
+      fresh = self.class.find(number)
+      hydrate_from_project(fresh)
+      self
+    end
+
+    private
+
+      # Kwargs derived from +metadata+ for forwarding to +self.class.create!+
+      # so +save!+ preserves in-memory metadata mutations on new records.
+      # Subclasses override to include type-specific metadata attributes.
+      #
+      # @return [Hash]
+      #
+      def create_kwargs_from_metadata
+        {
+          user: metadata.created_by,
+          visibility: metadata.visibility,
+          custom_fields: metadata.custom_fields.to_h,
+        }
+      end
+
+      # Metadata hash forwarded to the class +update!+ so +save!+ preserves
+      # in-memory metadata mutations on persisted records. Returns +nil+ when
+      # the instance has no PMS metadata to avoid clobbering remote values.
+      #
+      # @return [Hash, nil]
+      #
+      def metadata_for_update
+        return if metadata.schema_version.blank?
+
+        metadata.to_h
+      end
+
+      # Populates this instance from a list query node (summary only).
+      #
+      # @param node [Hash]
+      #
+      # @return [void]
+      #
+      def hydrate_summary(node)
+        @github_response = node
+        self.id = node[:id]
+        self.number = node[:number]
+        self.title = node[:title]
+        self.description = node[:shortDescription]
+        self.url = node[:url]
+        self.closed = node[:closed]
+        self.updated_at = parse_github_time(node[:updatedAt])
+        persisted!
+      end
+
+      # Populates this instance from a detailed find query response.
+      #
+      # @param graphql_project [Hash]
+      # @param items [Array<Hash>]
+      # @param next_cursor [String, nil]
+      # @param has_next_page [Boolean, nil]
+      #
+      # @return [void]
+      #
+      def hydrate_detail(graphql_project, items:, next_cursor: nil, has_next_page: nil)
+        @github_response = graphql_project
+        self.id = graphql_project[:id]
+        self.number = graphql_project[:number]
+        self.title = graphql_project[:title]
+        self.description = graphql_project[:shortDescription]
+        self.url = graphql_project[:url]
+        self.closed = graphql_project[:closed]
+        self.updated_at = parse_github_time(graphql_project[:updatedAt])
+
+        self.raw_readme = graphql_project[:readme] || ''
+        parsed = PlanMyStuff::MetadataParser.parse(raw_readme)
+        self.metadata = build_project_metadata(parsed[:metadata])
+        self.readme = parsed[:body]
+
+        fields_nodes = graphql_project.dig(:fields, :nodes) || []
+        self.statuses = extract_statuses(fields_nodes)
+        self.fields = extract_fields(fields_nodes)
+        self.items = items.map { |item_hash| item_class.build(item_hash, project: self) }
+        self.next_cursor = next_cursor
+        self.has_next_page = has_next_page
+        persisted!
+      end
+
+      # Copies attributes from another Project instance into self.
+      #
+      # @param other [PlanMyStuff::BaseProject]
+      #
+      # @return [void]
+      #
+      def hydrate_from_project(other)
+        @github_response = other.github_response
+        self.id = other.id
+        self.number = other.number
+        self.title = other.title
+        self.description = other.description
+        self.url = other.url
+        self.closed = other.closed
+        self.updated_at = other.updated_at
+        self.raw_readme = other.raw_readme
+        self.readme = other.readme
+        self.metadata = other.metadata
+        self.statuses = other.statuses
+        self.fields = other.fields
+        self.items = other.items
+        self.next_cursor = other.next_cursor
+        self.has_next_page = other.has_next_page
+        persisted!
+      end
+
+      # Raises StaleObjectError if the remote project has been modified
+      # since this instance was loaded.
+      #
+      # @raise [PlanMyStuff::StaleObjectError]
+      #
+      # @return [void]
+      #
+      def raise_if_stale!
+        return if new_record?
+        return if updated_at.nil?
+
+        remote = self.class.find(number)
+        remote_time = remote.updated_at
+        local_time = updated_at
+
+        return if remote_time.nil?
+        return if local_time && remote_time.to_i == local_time.to_i
+
+        raise(PlanMyStuff::StaleObjectError.new(
+          "Project ##{number} has been modified remotely",
+          local_updated_at: local_time,
+          remote_updated_at: remote_time,
+        ))
+      end
+
+      # Builds the appropriate metadata object for this project instance.
+      # Dispatches to TestingProjectMetadata when kind is "testing".
+      #
+      # @param meta_hash [Hash]
+      #
+      # @return [PlanMyStuff::BaseProjectMetadata]
+      #
+      def build_project_metadata(meta_hash)
+        if meta_hash[:kind] == 'testing'
+          PlanMyStuff::TestingProjectMetadata.from_hash(meta_hash)
+        else
+          PlanMyStuff::ProjectMetadata.from_hash(meta_hash)
+        end
+      end
+
+      # Extracts status options from the "Status" single-select field.
+      #
+      # @param fields_nodes [Array<Hash>]
+      #
+      # @return [Array<Hash>]
+      #
+      def extract_statuses(fields_nodes)
+        status_field = fields_nodes.find { |f| f[:name] == 'Status' && f.key?(:options) }
+
+        return [] unless status_field
+
+        (status_field[:options] || []).map do |opt|
+          { id: opt[:id], name: opt[:name] }
+        end
+      end
+
+      # @param fields_nodes [Array<Hash>]
+      #
+      # @return [Array<Hash>]
+      #
+      def extract_fields(fields_nodes)
+        fields_nodes.map do |f|
+          field = { id: f[:id], name: f[:name] }
+          field[:options] = f[:options].map { |o| { id: o[:id], name: o[:name] } } if f[:options]
+          field
+        end
+      end
+
+      # Returns the item class used to build items for this project type.
+      # Subclasses override to return a domain-specific item class.
+      #
+      # @return [Class]
+      #
+      def item_class
+        raise(NotImplementedError, 'Subclass must implement #item_class to return the appropriate item class')
+      end
+  end
+end